quirl.components.animation.demo

Standalone animation demo component for any Duck component.

Wraps any component and renders it with CSS-animated state transitions. Output is pure HTML/CSS/JS — no WebSocket, no Python runtime, no inheritance required on the wrapped component.

Module Contents

Classes

Demo	Wraps any component and renders it with animated state transitions.

Data

SUPPORTED_ACTIONS

API

class quirl.components.animation.demo.Demo(element: Optional[str] = None, properties: Optional[Dict[str, str]] = None, props: Optional[Dict[str, str]] = None, style: Optional[Dict[str, str]] = None, inner_html: Optional[Union[str, str, float]] = None, children: Optional[List[duck.html.components.HtmlComponent]] = None, **kwargs)

Bases: duck.html.components.container.Container

Wraps any component and renders it with animated state transitions.

Components that have nothing to demonstrate beyond “here’s what it looks like” should pass no steps at all — Demo then renders a plain, still preview with no fake cursor or click theater. The cursor/click machinery only builds when at least one step defines a real action.

Required Props:

• component: The component to demonstrate.

Optional Props:

• steps: List of animation steps. Leave empty/omitted for a static preview. Each step is a dict with: - delay (int, required): Milliseconds before the next step. - cursor (dict, optional): Either {"top": "50%", "left": "50%"}, positioned relative to the preview row (not the whole card), or {"target": "css-selector"} to center the cursor on a matched element within the stage. When target is given, no other keys are allowed. Omit cursor entirely to hide the cursor for that step. - target (str, optional): CSS selector relative to the demo, used for both the highlight pulse and any action. - action (dict, optional): What to do to target. {"type": "click"} {"type": "input", "value": "hello"} {"type": "toggle_class", "class_name": "is-active"} {"type": "focus"} {"type": "scroll_into_view"} Each supports an optional delay (ms before firing, defaults to 400).

• title: Heading above the demo.

• description: Optional text below the heading.

• id: Stable DOM id. Auto-generated if omitted.

Initialization

Initialize an HTML component.

Parameters:

• element – The HTML element tag name (e.g., textarea, input, button). Can be None, but make sure element is returned by get_element method.

• accept_inner_html – Whether the HTML component accepts an inner body (e.g., inner-body-here).

• inner_html – Inner html to add to the HTML component. Defaults to None.

• properties – Dictionary for properties to initialize the component with.

• props – Just same as properties argument (added for simplicity).

• style – Dictionary for style to initialize the component with.

• event_handlers – Events to automatically bind. Each dictionary maps an event name to its handler and may include additional keyword arguments forwarded to bind(), e.g. event_handlers=[{"click": on_button_click, **extra_kwargs}].

• **kwargs – Extra keyword arguments

Raises:

HtmlComponentError – If ‘element’ is not a string or ‘inner_html’ is set but ‘accept_inner_html’ is False.

build_cursor() → duck.html.components.container.Container

Build the fake mouse cursor element, scoped to the preview stage.

Returns:

A positioned Container acting as the cursor.

build_script() → duck.html.components.script.Script

Generate the JS state machine that drives the animation steps.

Returns:

A Script component that cycles through steps on the client.

build_styles() → duck.html.components.style.Style

Generate scoped CSS for the highlight pulse effect.

Returns:

A Style component with demo-specific keyframes.

docs_no_preview_reason

“Demo requires a component to wrap and isn’t meant to preview itself.”

docs_preview_kwargs

None

on_create()

Build the demo container with animated state transitions.

validate_steps() → None

Ensure every step has a delay, and every action has a known type.

Raises:

ValueError – If a step is malformed, or an action’s type isn’t one of SUPPORTED_ACTIONS.

quirl.components.animation.demo.SUPPORTED_ACTIONS

None