write about what is a decorator in general

vignettes/decorate-module-output.Rmd

@@ -19,6 +19,21 @@ enabling you to tailor the outputs to your specific requirements without rewriti
 
 ## Decorators
 
+In programming, **decoration** refers to the process of modifying an object while preserving its original class. For instance, given an object `x` of class `"my_class"`, a function `foo(x)` is considered a **decorator function** if it modifies `x` and returns an object that retains the same class. In this context, `x` is referred to as the **decorated object**, and `foo()` is the **decorator function**. Decorators can perform a variety of operations, such as adding new methods or modifying data, while ensuring the object remains compatible with its original usage.
+
+In the context of `teal` applications, decoration is specifically used to modify module outputs, such as plots or tables. For example, consider a decorator function `add_title(x, <plot_title>)` that takes a `ggplot2` plot object (`x`) as input, applies a title modification, and returns a modified `ggplot2` plot object. This function qualifies as a decorator because it preserves the original class of the input object. Conversely, a function like `create_plot(<data>, <x_axis>, <y_axis>)`, which generates a new plot object, is **not** a decorator, as it produces an output of a different class.
+
+Preserving the object's class during decoration is essential for compatibility. It ensures that the subsequent "display" logic can seamlessly handle both decorated and undecorated objects.
+
+The decoration process can vary in complexity:
+- **Simple Decorations**: Single-step modifications, such as a single method call that does not require additional data.
+- **Complex Decorations**: Multi-step operations that may involve interdependent transformations, potentially requiring input from dedicated `shiny` UI elements.
+
+This powerful functionality empowers application developers to significantly customize outputs beyond the default capabilities provided by existing module parameters. Decorations allow for advanced modifications, enabling highly tailored and dynamic user experiences in `teal` applications.
+
+
+## Decorators in `teal`
+
 One of ways of adjusting input data or customizing module outputs in `teal` is the usage of `transformators` 
 created through `teal_transform_module`. This document will focus on modifying outputs, and for clarity, we will refer 
 to these output-modifying objects as decoration objects or decorators.