Skip to main content
View as Markdown

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.

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.

- 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.

- 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).