# Interactions & Auto-Save

Two modules cover almost everything a Sovrium page does in the browser without you writing JavaScript: `interactions` attaches behavior to a component, and `action` says what running it does. Inline-edit auto-save builds on both.

```yaml
- type: button
  content: Save
  interactions:
    click: { animation: pulse, submitForm: settings-form }
  action:
    type: crud
    operation: update
    table: settings
    onSuccess: { type: message, toast: { variant: success, message: 'Saved' } }
```

## The `interactions` Module

`interactions` holds four independent triggers. Each is optional and they combine freely.

| Trigger    | Fires when                         |
| ---------- | ---------------------------------- |
| `click`    | The component is clicked.          |
| `hover`    | The pointer is over the component. |
| `scroll`   | The component enters the viewport. |
| `entrance` | The page loads.                    |

:::callout
**These keys have no `on` prefix.** It is `interactions.click`, not `interactions.onClick`. An `on`-prefixed key is dropped at decode, so the interaction validates and then never fires.
:::

### `click`

| Property        | Description                                               |
| --------------- | --------------------------------------------------------- |
| `animation`     | `pulse`, `bounce`, `shake`, `flash`, `ripple`, or `none`. |
| `navigate`      | Internal route or same-page anchor to go to.              |
| `openUrl`       | External URL to open.                                     |
| `openInNewTab`  | Open `openUrl` in a new tab.                              |
| `scrollTo`      | Element id to smooth-scroll to.                           |
| `toggleElement` | Element id to show or hide.                               |
| `submitForm`    | Form id to submit.                                        |
| `modal`         | Modal id to open.                                         |

Behaviors combine: play an animation, then navigate.

### `hover`

| Property          | Description                                                |
| ----------------- | ---------------------------------------------------------- |
| `scale`           | Uniform scale factor on hover.                             |
| `transform`       | CSS transform on hover.                                    |
| `opacity`         | Opacity from 0 to 1.                                       |
| `backgroundColor` | Background color on hover.                                 |
| `color`           | Text color on hover.                                       |
| `borderColor`     | Border color on hover.                                     |
| `shadow`          | Box shadow on hover.                                       |
| `duration`        | Transition duration. `0` applies the effect instantly.     |
| `easing`          | `linear`, `ease`, `ease-in`, `ease-out`, or `ease-in-out`. |

All hover effects apply together on one coordinated transition.

### `scroll`

| Property    | Description                                                                                                          |
| ----------- | -------------------------------------------------------------------------------------------------------------------- |
| `animation` | **Required.** `fadeIn`, `fadeInUp`, `fadeInDown`, `fadeInLeft`, `fadeInRight`, `zoomIn`, `slideInUp`, `slideInDown`. |
| `threshold` | Fraction of the element visible before triggering, 0 to 1.                                                           |
| `delay`     | Delay before the animation starts.                                                                                   |
| `duration`  | Animation duration.                                                                                                  |
| `once`      | Trigger only the first time, rather than on every re-entry.                                                          |

### `entrance`

| Property    | Description                                                                             |
| ----------- | --------------------------------------------------------------------------------------- |
| `animation` | **Required.** `fadeIn`, `fadeInUp`, `fadeInDown`, `zoomIn`, `slideInUp`, `slideInDown`. |
| `delay`     | Delay before the animation starts.                                                      |
| `duration`  | Animation duration.                                                                     |
| `stagger`   | Delay between sibling animations, e.g. `50ms`.                                          |

`entrance` fires once on load; `scroll` fires on viewport entry and is the one that takes `threshold` and `once`.

## Actions & Response Handlers

An `action` says what a button or form does — `crud`, `auth`, `navigate`, or `automation` — and `onSuccess` / `onError` say what happens next.

A `crud` action needs `operation` (`create`, `update`, `delete`) **and** `table`. `confirm` gates it behind a dialog, with `confirmMessage` supplying the wording.

A response handler's `type` is `navigate`, `reset`, `message`, `successPage`, or `role-landing`. Alongside it, `toast` shows a notification (`variant` is `success`, `error`, `warning`, or `info`), `message` and `title` set inline copy, and `actions` renders follow-up buttons on a success page.

```yaml
- type: button
  content: Delete
  action:
    type: crud
    operation: delete
    table: tasks
    confirm: true
    confirmMessage: 'Delete this task? This cannot be undone.'
    onSuccess: { type: navigate, navigate: /tasks }
    onError: { type: message, toast: { variant: error, message: 'Delete failed' } }
```

`action.type: automation` invokes a named [automation](/en/docs/automations-overview).

## Auto-Save

Data components support inline-edit auto-save through the `autoSave` module, most often on `data-table`.

| Property                | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `saveMode`              | `manual` (default), `auto` (debounced), or `onBlur`.              |
| `autoSaveDebounceMs`    | Delay after the last keystroke. Default 500, minimum 100.         |
| `showSaveIndicator`     | Show Idle / Saving / Saved / Error status, with retry on failure. |
| `saveIndicatorPosition` | `inline`, `toast`, or `toolbar`.                                  |
| `saveAction`            | Override the action used to persist the edit.                     |

Only the changed cell is sent in the `PATCH` payload, rapid edits batch into one request, and navigating away flushes anything still pending.

## `reorderable-list`

A list whose items can be reordered by drag or keyboard, firing an action when the order changes.

| Property     | Description                                  |
| ------------ | -------------------------------------------- |
| `dataSource` | Optional table binding for the items.        |
| `children`   | The items, each rendered with a drag handle. |
| `onReorder`  | Action invoked once the new order settles.   |

## Related Pages

- [Scripts](/en/docs/interactivity-scripts) — when you do need your own JavaScript.
- [Data Components](/en/docs/data-components) — `data-table` inline editing.
- [Animations](/en/docs/animations) — the motion tokens these animations use.
- [Overlay Components](/en/docs/overlay-components) — toasts and dialogs handlers raise.
- [Automations](/en/docs/automations-overview) — what `action.type: automation` runs.