# Interactivity & Scripts

Sovrium pages are server-rendered, then progressively enhanced with declarative interactivity. This page covers the `scripts` block (external/inline scripts, feature flags, config data), the `interactions` module (click actions, hover effects, entrance animations), auto-save for inline editing, reorderable lists, and custom HTML. No hand-written event wiring is required for the built-in patterns.

```yaml
pages:
  - name: Dashboard
    path: /dashboard
    scripts:
      external:
        - { src: 'https://cdn.example.com/widget.js', async: true, position: body-end }
      features: { betaPanel: true }
    components:
      - type: button
        content: Save
        interactions:
          onClick: { animation: pulse, submitForm: settings-form }
```

## `scripts`

Page-level client-side script management.

| Property   | Description                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| `external` | External JavaScript dependencies — each `{ src, async, defer, module, integrity, crossorigin, position }`. |
| `inline`   | Inline JavaScript snippets — each `{ code, async? }`. `async: true` wraps the code in an async IIFE.       |
| `features` | Client-side feature toggles — a boolean flag or `{ enabled, config }` per feature.                         |
| `config`   | Arbitrary client-side configuration data exposed to scripts.                                               |

### External script attributes

| Attribute     | Description                                           |
| ------------- | ----------------------------------------------------- |
| `src`         | Script source URL.                                    |
| `async`       | Load asynchronously (non-blocking).                   |
| `defer`       | Defer execution until the DOM is parsed.              |
| `module`      | Load as an ES module (`type="module"`).               |
| `integrity`   | Subresource-integrity hash for security.              |
| `crossorigin` | CORS setting: `anonymous` or `use-credentials`.       |
| `position`    | Insert location: `head`, `body-start`, or `body-end`. |

## `interactions`

The shared `interactions` module attaches client-side behavior to a component: click actions, hover effects, and entrance animations.

### `onClick`

| Property     | Description                                                          |
| ------------ | -------------------------------------------------------------------- |
| `animation`  | Animation to play on click (`pulse`, `ripple`, `bounce`, or `none`). |
| `navigate`   | Path to navigate to (internal route or same-page anchor).            |
| `url`        | External URL to open (in same tab, or new tab with a target).        |
| `scrollTo`   | Anchor section to smooth-scroll to.                                  |
| `toggle`     | Element id to show/hide.                                             |
| `submitForm` | Form id to submit.                                                   |
| `modalId`    | Modal section id to open.                                            |

Click behaviors can combine — e.g. play an animation, then navigate.

### `onHover`

| Property          | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `transform`       | CSS transform on hover (scale/rotate/translate; e.g. `scale: 1.05`).     |
| `opacity`         | Opacity value on hover (0–1).                                            |
| `backgroundColor` | Background color on hover.                                               |
| `textColor`       | Text color on hover.                                                     |
| `borderColor`     | Border color on hover.                                                   |
| `boxShadow`       | Box shadow on hover.                                                     |
| `duration`        | Transition duration (ms; `0` applies effects instantly).                 |
| `easing`          | Timing function: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`. |

All hover effects apply simultaneously with coordinated timing.

### `onEntrance`

| Property    | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| `animation` | Animation type triggered when the element enters the viewport. |
| `threshold` | Fraction of the element visible before triggering (0–1).       |
| `delay`     | Delay before the animation starts.                             |
| `once`      | Trigger only once.                                             |

## Actions & response handlers

Interactive components carry an `action` (e.g. `crud`, `auth`, `navigate`, `automation`) with `onSuccess`/`onError` response handlers. A handler may show a `toast`, `navigate`, `reset` the form, show a `message`, or render a `successPage` with follow-up `actions`. `action.type: automation` invokes a named [automation](/en/docs/automations-overview).

```yaml
- type: button
  content: Submit
  action:
    type: crud
    operation: create
    onSuccess: { type: navigate, url: /thanks }
    onError: { type: message, toast: { variant: error, message: 'Save failed' } }
```

## Auto-Save

Data components support inline-edit auto-save via the `autoSave` module (most commonly on `data-table`).

| Property                | Description                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------- |
| `saveMode`              | `auto` (debounced), `onBlur` (save when the edited field loses focus), or `manual` (default).         |
| `autoSaveDebounceMs`    | Debounce delay after the last keystroke (default: 500; min: 100). Rapid edits batch into one request. |
| `showSaveIndicator`     | Display status: Idle / Saving… / Saved / Error (with retry on failure).                               |
| `saveIndicatorPosition` | `inline` (near the edited cell), `toast`, or `toolbar`.                                               |

Only the changed cell value is sent in the PATCH payload; navigating away flushes pending saves immediately.

## `reorderable-list`

A list whose items can be reordered by drag-and-drop or keyboard, firing an `onReorder` action.

| Property     | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| `dataSource` | Optional table binding for list items.                      |
| `children`   | The list items (each rendered with a drag handle).          |
| `onReorder`  | Action invoked when items are reordered (drag or keyboard). |

## `custom-html` (`customHTML`)

Embed raw HTML — inline or from a file — in a sandboxed context with access to theme CSS variables.

| Property  | Description                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| `content` | Inline HTML string.                                                                           |
| `htmlSrc` | Path to an external HTML file, relative to the project root. Takes precedence over `content`. |

The HTML renders in a sandboxed context (no access to parent-page JS) and can reference theme variables (e.g. `var(--color-primary)`). An invalid `htmlSrc` renders a clear error instead of crashing.

```yaml
- type: customHTML
  content: '<div style="color: var(--color-primary)">Custom block</div>'
```

## Clipboard & patterns

Common interactive patterns are built from the primitives above: copy-to-clipboard buttons (a `button` with an action), debounced search inputs (`searchInput` with `debounceMs`), modals opened via `onClick.modalId`, and visibility gating via the `visibility` module (server-rendered but hidden client-side when auth conditions are unmet — hidden components never leak sensitive data into the HTML).

## Related Pages

- [Pages Overview](/en/docs/pages-overview) — the component model, actions, and `scripts`/`vars`.
- [Form Controls](/en/docs/form-controls) — inputs that auto-save or submit via actions.
- [Data Components](/en/docs/data-components) — `data-table` inline-edit auto-save.
- [Overlay Components](/en/docs/overlay-components) — toasts and dialogs triggered by interactions.
- [Automations](/en/docs/automations-overview) — automations invoked by `action.type: automation`.