docs(editor): binding data

docs.json

@@ -204,6 +204,7 @@
                       "editor/data-binding/lists"
                     ]
                   },
+                  "editor/data-binding/binding-data",
                   "editor/data-binding/converters",
                   "editor/data-binding/controlling-data",
                   "editor/data-binding/property-groups",

editor/data-binding/binding-data.mdx

@@ -0,0 +1,148 @@
+---
+title: "Binding Data"
+description: "Binding is how you connect data to properties and elements in your Rive file."
+---
+
+import { YouTube } from '/snippets/youtube.mdx'
+import { UseCase } from '/snippets/use-case.mdx'
+
+For example, if you have a `teamName` property bound to a text run in your scene, changing the `teamName` value updates the displayed text automatically.
+
+You can change property values in the editor or at runtime, allowing you to create dynamic experiences that adapt to each user.
+
+Bindings are not limited to visual properties. You can bind values throughout your file, including transforms, animation speeds, [converter values](/editor/data-binding/converters#converter-types), [script inputs](/scripting/script-inputs#data-binding-inputs), [transition condition values](/editor/state-machine/transitions), and more.
+
+This allows the same data to drive behavior, animation, and logic across your scene, helping keep everything in sync.
+
+## Binding a Property
+
+Let's control the `X` position of a circle using `circleX`, which is a Number property in our View Model.
+
+![Bind a property](/images/editor/data-binding/binding-data/bind-value.gif)
+
+<Steps>
+  <Step title="Bind the property">
+    With your circle selected, right-click the `X` field, and select **Data Bind**.
+  </Step>
+  <Step title="Select the property">
+    In the **Property** dropdown, select `circleX`.
+  </Step>
+</Steps>
+
+The `X` field should now be highlighted in green, indicating that it's bound to a value.
+
+The circle's horizontal position is now driven by the `circleX` property. Any time the property's value changes, the circle updates automatically.
+
+![Bind a property](/images/editor/data-binding/binding-data/updating-values.gif)
+
+<Warning>
+  If the field has a yellow border, there is a problem with the binding.
+
+  In most cases, the property type is incompatible with the target value. For example, the `X` position of an element can only be bound to a Number property.
+</Warning>
+
+<Tip>
+  **Previewing Bindings**
+
+  By default, your data only controls your elements when the state machine is playing.
+
+  To preview your data-bound values, turn on the **Data Binding Preview Toggle**.
+
+  ![Preview data binding](/images/editor/data-binding/binding-data/preview-data-binding.gif)
+</Tip>
+
+### Updating a Binding
+
+Right-click the bound element and select **Update Bind**.
+
+![Update a binding](/images/editor/data-binding/binding-data/update-bind.gif)
+
+### Removing a Binding
+
+Right-click the bound element and select **Unbind**.
+
+![Remove a binding](/images/editor/data-binding/binding-data/unbind.gif)
+
+## Binding Options
+
+Each binding has the following properties.
+
+### Property
+
+The View Model property the target is connected to.
+
+![Property field](/images/editor/data-binding/binding-data/property.png)
+
+### Path
+
+When binding to nested View Models, there may be multiple properties with the same name available.
+
+The path determines which specific property instance the binding should use.
+
+![Preview data binding](/images/editor/data-binding/binding-data/path.gif)
+
+See also [Absolute vs Relative Binding](#absolute-vs-relative-binding).
+
+### Bind Direction
+
+By default, the View Model property (**source**) controls the bound element or value (**target**), but it can also work the other way around.
+
+<YouTube id="Syt6i4-Bkm4" />
+
+#### Target to Source
+
+When a binding has `Target to Source` toggled on, a change to the element will update the view model property.
+
+![Target to source](/images/editor/data-binding/binding-data/target-to-source.png)
+
+<UseCase
+  title="Tracking Positions"
+>
+  Let's say you have a walk cycle animation and you want to track the exact Y position of the head as it bobs up and down.
+
+  With the head's `Y` position bound to `headY` using **Target to Source**, the `headY` property updates automatically as the head moves.
+</UseCase>
+
+#### Bidirectional
+
+A change to the view model property will update the element **AND** a change to the element will update the view model property.
+
+![Bidirectional data binding](/images/editor/data-binding/binding-data/bidirectional.gif)
+
+Clicking the **Bidirectional** toggle multiple times will cycle between **Bidirectional (prefer target value)** and **Bidirectional (prefer source value)**.
+
+In rare cases, both the source and target may change at the same time. This setting determines which value wins when a conflict occurs.
+
+<UseCase
+  title="Checkers"
+>
+  Let's say you're building a game of checkers and need to create logic for dragging and dropping each piece.
+
+  The initial position of each piece is determined by the `piecePositionX` and `piecePositionY` properties (source to target).
+
+  As the piece is dragged, the piece itself (target) updates those property values (target to source).
+</UseCase>
+
+### Bind Once
+
+When **Bind Once** is enabled, the binding only applies the value a single time when the scene starts or the binding is created.
+
+![Bind once](/images/editor/data-binding/binding-data/bind-once.png)
+
+After the initial value is applied, future changes to the source or target are ignored.
+
+<UseCase>
+  Let's say you're creating a particle effect and want each particle to start with a random rotation value.
+
+  You could bind the particle's rotation to a random number property using **Bind Once**. Each particle would receive its initial rotation value, but future changes to the property would not affect existing particles.
+</UseCase>
+
+### Absolute vs Relative Binding
+
+<YouTube id="4LOXhXesG74" />
+
+By default, new data binding connections are created as absolute binds.
+
+- **Absolute Binding**: The binding points to a specific property instance within the View Model hierarchy.
+- **Relative Binding**: The binding searches for a property with a matching name relative to the current context.
+

editor/data-binding/converters.mdx

@@ -35,6 +35,10 @@ Use them to adapt your data to match the property you're binding to—for exampl
 
 Converters can be used individually or combined into [groups](#converter-groups) to perform more complex transformations.
 
+Each converter has its own set of properties, many of which can be bound to other View Model properties.
+This allows converter behavior to update dynamically. For example, you could bind the maximum value of a range map, a multiplier in a formula, or the padding amount in a string converter.
+
+
 | Category | Converter                | Description                               |
 |----------|--------------------------|-------------------------------------------|
 | String   | [Pad](#pad)                      | Add padding to a string                   |
@@ -192,5 +196,3 @@ Converters run from top to bottom:
 Drag a converter up or down to change when it runs.
 
 Earlier converters affect all converters that follow.
-
-

editor/data-binding/overview.mdx

@@ -56,31 +56,3 @@ Artboards are assigned an instance to populate the data bindings. Changing which
 In order for an instance to be visible to developers, it must be marked as Exported. Otherwise, it is considered internal to the file. One reason you may want to keep it internal is if you only use the instance to test your design when it is configured with a given set of values, including edge cases.
 
 These exported instances can then be assigned to an artboard at runtime by developers. Alternatively, developers can create empty instances which have default values, such as zero for numbers and empty strings. Once the instance is assigned, its values will begin updating according to the bindings.
-
-### Binding
-
-A binding is an association between a view model property and an editor element. For instance, you might have a string property called "name" bound to a text run. Once bound, the text run will take the value from the view model property. See [Bind Direction](#bind-direction) for additional options.
-
-#### Absolute & Relative Binding
-By default, new data binding connections are created as absolute binds.
-
-- Absolute Binding: the bind points the value at a specific property location within the view model tree. For example, "the second property of the first view model".
-- Relative Binding: the bind finds the value of property with a specific name, regardless of where it falls within the view model tree. For example, a relative binding to "myNumber" will look for a property of that name within the view model available.
-
-<YouTube id="4LOXhXesG74" />
-
-#### Bind Direction
-
-Bindings can be source to target, target to source, or bidirectional. In this case, "source" means the property, and "target" means the editor element.
-
-<YouTube id="Syt6i4-Bkm4" />
-
-The default binding is source to target. This means that changes to the property update the value of the element. For example, an XPos property updates the X position of an object.
-
-Target to source means that changes to the element's value update the property. For example, the X position of an object updates the XPos property.
-
-Bidirectional means that changes are applied in both directions, meaning either the element or the property can update the other.
-
-Additionally, a binding may be marked as "Bind Once". This means that the initial value will apply and thereafter the binding will not apply any updates.
-
-<YouTube id="OBmP-KxqIyU" />

snippets/use-case.mdx

@@ -0,0 +1,14 @@
+export const UseCase = ({ title, children }) => {
+  return (
+    <aside class="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-neutral-200 bg-neutral-50 dark:border-neutral-700 dark:bg-white/10" data-callout-type="info">
+      <div class="mt-0.5 w-4" data-component-part="callout-icon">
+        <svg width="11" height="14" viewBox="0 0 11 14" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="text-neutral-800 dark:text-neutral-300 w-3.5 h-auto" aria-label="Tip"><path d="M3.12794 12.4232C3.12794 12.5954 3.1776 12.7634 3.27244 12.907L3.74114 13.6095C3.88471 13.8248 4.21067 14 4.46964 14H6.15606C6.41415 14 6.74017 13.825 6.88373 13.6095L7.3508 12.9073C7.43114 12.7859 7.49705 12.569 7.49705 12.4232L7.50055 11.3513H3.12521L3.12794 12.4232ZM5.31288 0C2.52414 0.00875889 0.5 2.26889 0.5 4.78826C0.5 6.00188 0.949566 7.10829 1.69119 7.95492C2.14321 8.47011 2.84901 9.54727 3.11919 10.4557C3.12005 10.4625 3.12175 10.4698 3.12261 10.4771H7.50342C7.50427 10.4698 7.50598 10.463 7.50684 10.4557C7.77688 9.54727 8.48281 8.47011 8.93484 7.95492C9.67728 7.13181 10.1258 6.02703 10.1258 4.78826C10.1258 2.15486 7.9709 0.000106649 5.31288 0ZM7.94902 7.11267C7.52078 7.60079 6.99082 8.37878 6.6077 9.18794H4.02051C3.63739 8.37878 3.10743 7.60079 2.67947 7.11294C2.11997 6.47551 1.8126 5.63599 1.8126 4.78826C1.8126 3.09829 3.12794 1.31944 5.28827 1.3126C7.2435 1.3126 8.81315 2.88226 8.81315 4.78826C8.81315 5.63599 8.50688 6.47551 7.94902 7.11267ZM4.87534 2.18767C3.66939 2.18767 2.68767 3.16939 2.68767 4.37534C2.68767 4.61719 2.88336 4.81288 3.12521 4.81288C3.36705 4.81288 3.56274 4.61599 3.56274 4.37534C3.56274 3.6515 4.1515 3.06274 4.87534 3.06274C5.11719 3.06274 5.31288 2.86727 5.31288 2.62548C5.31288 2.38369 5.11599 2.18767 4.87534 2.18767Z"></path></svg>
+      </div>
+      <div class="text-sm prose dark:prose-invert min-w-0 w-full [&_kbd]:bg-background-light dark:[&_kbd]:bg-background-dark [&_code]:!text-current [&_kbd]:!text-current [&_a]:!text-current [&_a]:border-current [&_strong]:!text-current text-neutral-800 dark:text-neutral-300" data-component-part="callout-content">
+        <strong>Example{ title && ` - ${title}` }</strong>
+
+        { children }
+      </div>
+    </aside>
+  );
+};