docs(editor): components

editor/fundamentals/components.mdx

@@ -1,79 +1,168 @@
 ---
-title: "Components (formerly Nested Artboards)"
-sidebarTitle: "Components"
-description: "Components streamline your workflow with reusable artboards and animations. Changes made to the source component are reflected across all of its instances."
+title: "Components"
+description: "Create reusable artboards that can be instanced throughout your Rive files."
 ---
 
 import { YouTube } from '/snippets/youtube.mdx'
 
+
+Components are reusable artboards. Create a component once, then use customized instances of it throughout your Rive file. Changes made to the source component are reflected across all of its instances.
+
+You can use components in several ways:
+
+- Place a component inside another artboard as a nested component.
+- Reference a component from a [View Model property](/editor/data-binding/property-types#view-model), allowing you to swap them at runtime.
+- [Instantiate components from scripts](/scripting/protocols/node-scripts#instantiating-components).
+- Use components as items in [Lists](/editor/data-binding/lists).
+
+Components can include their own graphics, animations, state machines, and data, allowing you to build complex experiences from smaller, reusable pieces.
+
 <YouTube id="HRUr9mnh41A" />
 
+
 ## Creating a Component
 
-Any artboard can be converted to a component. To do so, select an artboard on the stage and use the component icon in the inspector to toggle its status.
+### Converting Artboards to Components
+
+Any artboard can be converted into a reusable component.
+
+<Steps>
+  <Step>
+    Select an artboard.
+  </Step>
+  <Step>
+    In the Inspector, select the **Component** icon or press `Shift` + `N`.
+  </Step>
+</Steps>
+
+You can identify components by their purple artboard title on the stage.
+
+
+![Convert an artboard to a component](/images/editor/artboards/convert-to-component.gif)
+
+<Note>
+Artboards that aren't components aren't exported with your Rive file. This can be useful for artboards used only while authoring, such as tests or reference artboards.
+</Note>
+
+### Converting Objects to Components
+
+You can select one or more objects on an artboard and convert them into a new component.
+
+<Steps>
+  <Step>
+    Select the object or objects you want to convert.
+  </Step>
+  <Step>
+    Right-click the selection and select **Create Component**.
+  </Step>
+</Steps>
+
+Rive creates a new component containing the selected objects and replaces the original selection with an instance of that component.
+
+![Create a new component from an element inside the artboard](/images/editor/artboards/convert-object-to-component.gif)
+
+**Animations and State Machines**
+
+If the selected objects are animated by a timeline on the original artboard, the relevant keys are removed from that timeline and copied to a new timeline inside the component.
+
+State machines aren't copied to the new component. State machines can depend on objects, animations, data, and other elements outside the selection, so you'll need to create a new state machine inside the component.
+
+Data bindings are copied to the new component, but their view models are not.
+
+#### Troubleshooting
+
+Components are self-contained, so Rive can't create a component if the selection depends on objects outside of it. Make sure you include any required dependencies in your selection.
+
+For example, a draw order dependency that crosses the new component's boundary will prevent the component from being created and display the **"Can't create component"** error: **"These dependencies point across the new component's boundary and would break."**
+
+![Can't create component error caused by a dependency crossing the component boundary](/images/editor/artboards/cannot-create-new-component.png)
+
+## Placing Components
+
+Use the **Component Tool**, formerly known as the Nested Artboard Tool, to place instances of components on the stage. Select the tool from the toolbar or press `N`.
+
+Click anywhere on the stage to choose from the available components and place an instance at that location.
+
+![Placing a component instance by clicking stage with the Component Tool and choosing from the menu of available components](/images/editor/artboards/place-component.gif)
+
+<Note>
+If an artboard doesn't appear in the component menu, make sure you've [converted it to a component](#converting-artboards-to-components).
+</Note>
+
+Alternatively, use the dropdown next to the **Component Tool** to choose a component before placing it.
+
+![Placing a component instance by clicking the Component Tool dropdown, selecting a component, and clicking the stage](/images/editor/artboards/place-specific-component.gif)
+
 
-Alternatively, you can use the `Shift` + `N` shortcut with an artboard selected. If you're coming from Figma, then the `Cmd/Ctrl` + `Alt/Option` + `K`, shortcut will also work.
+The component menu follows the sort mode used in the Assets panel:
 
-Select the component toggle in the inspector again to revert your selection back to a regular artboard, or use the `Shift` + `Alt/Option` + `N` shortcut.
+- **Custom** displays components as they're organized in the Assets panel.
+- **Source/Type** groups components by their source. This is particularly useful when working with [Libraries](/editor/libraries).
 
-Currently, only artboards that have been flagged as components will be exported to your `.riv` file. If you think you may want to programmatically access an artboard at runtime, you should mark it as a component. More options on specific export behaviors are coming soon.
+![Sort assets by Custom](/images/editor/artboards/assets-sort.png)
 
-## Using Components
+## Editing Components
 
-Use the Component Tool — formerly known as the Nested Artboard Tool — to select and place instances of a component on the stage. Select the tool from the toolbar or use the `N` shortcut to enable it.
+Double-click a component instance to open its source component. Changes you make to the source component are reflected in all of its instances, while properties configured on individual instances remain unchanged.
 
-Click anywhere on the stage to place the component in the desired location. A menu will display available components to instance. If none show up, you may have no artboards marked as components in your file.
+![Double click to edit a component](/images/editor/artboards/edit-component.gif)
 
-![Placing a component instance by clicking stage with the Component Tool and choosing from the menu of available components](/images/editor/fundamentals/components-add.gif)
+## Component Instance Properties
 
-Alternatively, select the dropdown menu to the right of the toolbar icon to select the component ahead of time. The menu is informed by the sort mode of the assets tab — the 'Custom' mode will present components as they’re organized in the asset panel, while the 'Source/Type' mode will present components from their source. The latter will become useful with our Libraries feature.
+Select a component instance to configure its properties in the Inspector. These properties control the data, animation, source, layout, and other behavior of that specific instance without changing the source component.
 
-## Configuring a Component Instance
+![Component properties in the sidebar](/images/editor/artboards/component-properties.png)
 
-Once you’ve added an instance of a component, select a timeline or state machine for playback.
+<Note>
+You can't change the origin of a component instance directly. To use a different origin, place the component instance inside a group and adjust the group's origin instead.
+</Note>
 
-### State Machines
+### Source
 
-After assigning an instance, the default state machine is displayed in the inspector.
+**Source** determines which component is displayed by the instance. Select a component directly, or data bind the source to change the component dynamically.
 
-![The default state machine for a placed component instance shown in the Inspector](/images/editor/fundamentals/components-statemachine.gif)
+Learn more about [Data Binding](/editor/data-binding).
 
-### Adding an Animation
+### Data
 
-You can playback any animation associated with a component. You’ll need to add the desired animation to the instance using the plus button in the Inspector.
+Configure the data used by a component instance.
 
-![Adding an animation to a component instance by clicking the plus button in the Animations section in the Inspector](/images/editor/fundamentals/components-animations.gif)
+**Stateful Components**
 
-These animations can be used by themselves, mixed with the state machine, or layered with other animations.
+If the component is a [Stateful Component](/editor/data-binding/stateful-components), you can set its exposed properties directly on the component instance.
 
-Note that before adding the animation, you must select whether it's a simple or remapped animation.
+**Model**
 
-#### Simple
+Use **Model** to set the view model instance used by the component.
 
-Simple animations are an easy way to playback a component's timeline.
+- **Inherit** uses a compatible view model instance from the closest parent.
+- To specify an instance, add a **View Model** property to the parent's view model and assign an instance to it. You can then select that property as the component's **Model**.
 
-![Keying the start point of a simple animation on the timeline for a component instance](/images/editor/fundamentals/components-animation-simple.gif)
+Learn more about [View Models and Instances](/editor/data-binding/view-models).
 
-A simple animation lets you key its start point on a timeline. You also have the option to change the animation's playback speed.
+### Mode
 
-#### Remap
+**Mode** determines how the component instance sizes and responds to the space available from its parent. See [Component Sizing](/editor/layouts/component-sizing) for more information about sizing modes and their properties.
 
-Remap animations allow you to key time values of an animation on the timeline. This lets you stretch, shrink, or even play an animation in reverse.
+### Animations
 
-![Keying time values of a remap animation on the timeline](/images/editor/fundamentals/components-animation-remap.gif)
+Choose the animations that play on a component instance. In most cases, you'll want to select a state machine, but you can also add one or more timeline animations.
 
-Note that the time value is in percent, with 0% representing the start of the timeline and 100% representing the end.
+**State Machine**
 
-### Mix Value
+Select a state machine to run on the component instance. You can adjust its playback **Speed** and enable **Quantize**.
 
-As you add additional animations to a Component, animations begin to mix together. This mixing is important, especially when multiple animations share keyed properties. Without adjusting this value, your Component may not playback your animations in the way you want.
+**Timeline Animations**
 
-By default, any animation added to a component starts with a mix value of 100%. You can adjust this value in design mode or in a specific animation by setting keys. **Note that an animation that has a non-zero mix value will always be mixing with other animations, regardless if it has a play key set or not.**
+Add timeline animations to play on their own, alongside a state machine, or layered with other animations. When adding a timeline animation, choose between **Simple** and **Remap**.
 
-To ensure the correct animation is playing, ensure that you key the mix value for the desired animation to 100%, and all other animations have a mix of 0%.
+**Simple** plays the timeline normally and provides the following controls:
 
-### Mode (Component Sizing)
+- **Mix** controls how much the animation contributes when mixed with other animations.
+- **Speed** controls the animation's playback speed.
+- **Playing** controls whether the animation is playing.
 
-Component instances can use **Node**, **Leaf**, or **Layout** sizing to control how they respond to the space available from their parent.
+**Remap** lets you control the position of the animation's playhead directly:
 
-See [Component Sizing](/editor/layouts/component-sizing) to learn how each option scales, fits, or reflows a component.
+- **Mix** controls how much the animation contributes when mixed with other animations.
+- **Time** controls the animation's playhead as a percentage, where `0%` is the beginning and `100%` is the end.