@lilydesignsystem/svelte-headless 0.1.0

package/dist/components/TimelineListItem/TimelineListItem.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+    // TimelineListItem component
+    //
+    // A single event entry within a TimelineList ordered list. Renders a semantic
+    // <li> element containing an optional <time> element for machine-readable dates
+    // and an optional heading, followed by descriptive content via children. Used
+    // for project milestones, activity feeds, order histories, or any chronological
+    // sequence of events.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   datetime — string, optional. ISO date/time string for the <time> element.
+    //   heading — string, optional. Visible date/time text rendered inside the <time> element.
+    //   children — Snippet, required. Event description content.
+    //   ...restProps — additional HTML attributes spread onto the <li>.
+    //
+    // Syntax:
+    //   <TimelineListItem datetime="2024-01-15" heading="Jan 15">Event description</TimelineListItem>
+    //
+    // Examples:
+    //   <!-- Timeline entries inside a TimelineList -->
+    //   <TimelineList label="Order history">
+    //     <TimelineListItem datetime="2024-01-15" heading="January 15, 2024">
+    //       Order placed
+    //     </TimelineListItem>
+    //     <TimelineListItem datetime="2024-01-16" heading="January 16, 2024">
+    //       Order shipped
+    //     </TimelineListItem>
+    //     <TimelineListItem datetime="2024-01-19" heading="January 19, 2024">
+    //       Order delivered
+    //     </TimelineListItem>
+    //   </TimelineList>
+    //
+    //   <!-- Timeline entry without a date -->
+    //   <TimelineListItem>Status pending review</TimelineListItem>
+    //
+    // Keyboard:
+    //   - None directly -- standard list item with no interactive behavior
+    //
+    // Accessibility:
+    //   - Semantic <li> element provides list item semantics within the parent <ol>
+    //   - <time> element with datetime attribute provides machine-readable date
+    //   - Screen readers announce list position (e.g. "2 of 4") from the parent <ol>
+    //
+    // Internationalization:
+    //   - The heading prop accepts any translated date/time string
+    //   - All content is provided through the children snippet
+    //   - No hardcoded strings in the component
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles -- consumer provides all styling
+    //   - Compound component: must be used inside a TimelineList
+    //   - Consumer can target <time> or data attributes for visual styling
+    //
+    // References:
+    //   - HTML <time> element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time
+    //   - WAI-ARIA listitem role: https://www.w3.org/TR/wai-aria-1.2/#listitem
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        datetime = "",
+        heading = "",
+        children,
+        ...restProps
+    }: {
+        /** ISO date/time string for the <time> element. */
+        datetime?: string;
+        /** Visible date/time text for the <time> element. */
+        heading?: string;
+        /** Event description content. */
+        children: Snippet;
+        /** Additional HTML attributes spread onto the <li>. */
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- TimelineListItem.svelte -->
+<li
+    class={`timeline-list-item ${className}`}
+    {...restProps}
+>
+    {#if datetime || heading}
+        <time datetime={datetime || undefined}>{heading}</time>
+    {/if}
+    {@render children?.()}
+</li>

package/dist/components/TimelineListItem/TimelineListItem.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** ISO date/time string for the <time> element. */
+    datetime?: string;
+    /** Visible date/time text for the <time> element. */
+    heading?: string;
+    /** Event description content. */
+    children: Snippet;
+    /** Additional HTML attributes spread onto the <li>. */
+    [key: string]: unknown;
+};
+declare const TimelineListItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type TimelineListItem = ReturnType<typeof TimelineListItem>;
+export default TimelineListItem;

package/dist/components/TimeoutDialog/TimeoutDialog.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = undefined,
+        open = false,
+        children,
+        ...restProps
+    }: {
+        label?: string;
+        open?: boolean;
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- TimeoutDialog.svelte -->
+<dialog
+    class={`timeout-dialog ${className}`}
+    role="alertdialog"
+    aria-label={label}
+    {open}
+    {...restProps}
+>
+    {@render children?.()}
+</dialog>

package/dist/components/TimeoutDialog/TimeoutDialog.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    label?: string;
+    open?: boolean;
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const TimeoutDialog: import("svelte").Component<$$ComponentProps, {}, "">;
+type TimeoutDialog = ReturnType<typeof TimeoutDialog>;
+export default TimeoutDialog;

package/dist/components/Timer/Timer.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+    // Timer component
+    //
+    // A headless timer that renders a semantic <time> element with role="timer"
+    // and aria-live="polite" for accessible countdown or elapsed time displays.
+    // The consumer manages the actual timer logic (intervals, countdowns) and
+    // provides formatted display content through the children snippet. Commonly
+    // used for session timeouts, countdowns, stopwatches, cooking timers, and
+    // exam time limits.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible label for screen readers via aria-label.
+    //   children — Snippet, required. Formatted timer display content.
+    //   ...restProps — additional HTML attributes spread onto the <time> (e.g. datetime="PT5M30S").
+    //
+    // Syntax:
+    //   <Timer label="Countdown">05:30</Timer>
+    //
+    // Examples:
+    //   <!-- Timer with machine-readable datetime attribute -->
+    //   <Timer label="Session timeout" datetime="PT5M30S">5:30</Timer>
+    //
+    //   <!-- Dynamic elapsed time -->
+    //   <Timer label="Elapsed time">{formatted}</Timer>
+    //
+    // Keyboard:
+    //   - None -- informational display, not interactive
+    //
+    // Accessibility:
+    //   - role="timer" indicates countdown or elapsed time
+    //   - aria-label provides the accessible name for screen readers
+    //   - aria-live="polite" announces timer updates without interrupting
+    //   - Semantic <time> element supports machine-readable time data
+    //
+    // Internationalization:
+    //   - The label prop externalizes the accessible label string
+    //   - The children snippet allows localized time formatting
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles -- consumer provides all styling
+    //   - Consumer manages timer logic; component only provides structure and accessibility
+    //   - Optional datetime attribute via restProps for ISO 8601 duration format
+    //
+    // References:
+    //   - WAI-ARIA timer role: https://www.w3.org/TR/wai-aria-1.2/#timer
+    //   - HTML <time> element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/time
+    //   - ISO 8601 Duration format: https://en.wikipedia.org/wiki/ISO_8601#Durations
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        children,
+        ...restProps
+    }: {
+        /** Accessible label for screen readers */
+        label: string;
+        /** Timer display content (formatted time string) */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- Timer.svelte -->
+<time
+    class={`timer ${className}`}
+    role="timer"
+    aria-label={label}
+    aria-live="polite"
+    {...restProps}
+>
+    {@render children?.()}
+</time>

package/dist/components/Timer/Timer.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible label for screen readers */
+    label: string;
+    /** Timer display content (formatted time string) */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const Timer: import("svelte").Component<$$ComponentProps, {}, "">;
+type Timer = ReturnType<typeof Timer>;
+export default Timer;

package/dist/components/TimerButton/TimerButton.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    let {
+        class: className = "",
+        label = undefined,
+        children,
+        ...restProps
+    }: {
+        label?: string;
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- TimerButton.svelte -->
+<div class={`timer-button ${className}`} aria-label={label} {...restProps}>
+    {@render children?.()}
+</div>

package/dist/components/TimerButton/TimerButton.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    label?: string;
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const TimerButton: import("svelte").Component<$$ComponentProps, {}, "">;
+type TimerButton = ReturnType<typeof TimerButton>;
+export default TimerButton;

package/dist/components/Toast/Toast.svelte

@@ -0,0 +1,80 @@
+<script lang="ts">
+    // Toast component
+    //
+    // A headless notification toast that provides a brief, transient message to
+    // the user via ARIA live regions. Uses role="status" with aria-live="polite"
+    // by default, or role="alert" with aria-live="assertive" for urgent messages.
+    // Toasts are typically used for success confirmations, error messages, and
+    // informational updates without requiring user interaction.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, default undefined. Optional accessible label via aria-label.
+    //   urgent — boolean, default false. When true, uses role="alert" and aria-live="assertive".
+    //   children — Snippet, required. The toast message content.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <Toast label="Success">Your changes have been saved.</Toast>
+    //
+    // Examples:
+    //   <!-- Urgent error toast -->
+    //   <Toast label="Error" urgent>Something went wrong.</Toast>
+    //
+    //   <!-- Informational toast -->
+    //   <Toast label="Info">
+    //     <p>3 new messages in your inbox.</p>
+    //   </Toast>
+    //
+    // Keyboard:
+    //   - None -- passive notification container; announced via live regions
+    //
+    // Accessibility:
+    //   - role="status" (default) for polite announcements at the next graceful opportunity
+    //   - role="alert" (when urgent) for immediate, time-sensitive announcements
+    //   - aria-live="polite" (default) waits for a pause before announcing
+    //   - aria-live="assertive" (when urgent) interrupts current speech
+    //   - aria-label provides optional descriptive label for the toast region
+    //
+    // Internationalization:
+    //   - The label prop accepts any translated string
+    //   - All toast content is provided through the children snippet
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles -- consumer provides all styling
+    //   - The urgent prop controls both role and aria-live simultaneously
+    //
+    // References:
+    //   - WAI-ARIA Alert Role: https://www.w3.org/TR/wai-aria-1.2/#alert
+    //   - WAI-ARIA Status Role: https://www.w3.org/TR/wai-aria-1.2/#status
+    //   - WAI-ARIA Live Regions: https://www.w3.org/TR/wai-aria-1.2/#aria-live
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = undefined,
+        urgent = false,
+        children,
+        ...restProps
+    }: {
+        /** Optional accessible label. */
+        label?: string;
+        /** Whether to use alert role instead of status. */
+        urgent?: boolean;
+        /** Toast content. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- Toast.svelte -->
+<div
+    class={`toast ${className}`}
+    role={urgent ? "alert" : "status"}
+    aria-label={label}
+    aria-live={urgent ? "assertive" : "polite"}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

package/dist/components/Toast/Toast.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Optional accessible label. */
+    label?: string;
+    /** Whether to use alert role instead of status. */
+    urgent?: boolean;
+    /** Toast content. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const Toast: import("svelte").Component<$$ComponentProps, {}, "">;
+type Toast = ReturnType<typeof Toast>;
+export default Toast;

package/dist/components/ToggleButton/ToggleButton.svelte

@@ -0,0 +1,102 @@
+<script lang="ts">
+    // ToggleButton component
+    //
+    // A headless binary on/off toggle button using role="switch". Renders a
+    // <button> with aria-checked to communicate state. Supports click and
+    // keyboard (Space key) interaction. The pressed state is bindable for
+    // two-way data flow. Commonly used for settings like dark mode,
+    // notifications, or feature flags.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name via aria-label.
+    //   pressed — boolean, default false. Whether the toggle is on. Bindable.
+    //   disabled — boolean, default false. Whether the toggle is disabled.
+    //   children — Snippet, optional. Button content.
+    //   ...restProps — additional HTML attributes spread onto the <button>.
+    //
+    // Syntax:
+    //   <ToggleButton label="Dark mode" bind:pressed />
+    //
+    // Examples:
+    //   <!-- Dark mode toggle -->
+    //   <ToggleButton label="Dark mode" bind:pressed />
+    //
+    //   <!-- Mute toggle with disabled state -->
+    //   <ToggleButton label="Mute audio" bind:pressed={muted} disabled={locked} />
+    //
+    // Keyboard:
+    //   - Space: toggles between on and off states
+    //   - Enter: activates the button (native button behavior)
+    //
+    // Accessibility:
+    //   - role="switch" identifies the element as a two-state toggle
+    //   - aria-checked={pressed} communicates the current state
+    //   - aria-label={label} provides the accessible name
+    //
+    // Internationalization:
+    //   - The label prop accepts any translated string
+    //   - No hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses $bindable() for two-way data binding on pressed
+    //   - type="button" prevents accidental form submission
+    //
+    // References:
+    //   - WAI-ARIA Switch Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/switch/
+    //   - WAI-ARIA Switch Role: https://www.w3.org/TR/wai-aria-1.2/#switch
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        pressed = $bindable(false),
+        disabled = false,
+        children,
+        ...restProps
+    }: {
+        /** Accessible label. */
+        label: string;
+        /** Whether the toggle is on. Bindable. */
+        pressed?: boolean;
+        /** Whether the toggle is disabled. */
+        disabled?: boolean;
+        /** Optional button content. */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+
+    function onclick() {
+        if (!disabled) {
+            pressed = !pressed;
+        }
+    }
+
+    function onkeydown(event: KeyboardEvent) {
+        if (event.key === " ") {
+            event.preventDefault();
+            if (!disabled) {
+                pressed = !pressed;
+            }
+        }
+    }
+</script>
+
+<!-- ToggleButton.svelte -->
+<button
+    class={`toggle-button ${className}`}
+    type="button"
+    role="switch"
+    aria-checked={pressed}
+    aria-label={label}
+    {disabled}
+    {onclick}
+    {onkeydown}
+    {...restProps}
+>
+    {#if children}
+        {@render children?.()}
+    {/if}
+</button>

package/dist/components/ToggleButton/ToggleButton.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible label. */
+    label: string;
+    /** Whether the toggle is on. Bindable. */
+    pressed?: boolean;
+    /** Whether the toggle is disabled. */
+    disabled?: boolean;
+    /** Optional button content. */
+    children?: Snippet;
+    [key: string]: unknown;
+};
+declare const ToggleButton: import("svelte").Component<$$ComponentProps, {}, "pressed">;
+type ToggleButton = ReturnType<typeof ToggleButton>;
+export default ToggleButton;

package/dist/components/ToggleGroup/ToggleGroup.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+    // ToggleGroup component
+    //
+    // A headless container for a collection of related toggle buttons. Renders a
+    // <div> with the ARIA group role and an accessible label to semantically
+    // associate toggle buttons. Useful for text formatting toolbars (bold, italic,
+    // underline), view mode selectors, or any interface where multiple options can
+    // be independently toggled on or off. Each child button should use aria-pressed
+    // to indicate its toggle state.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name for the group via aria-label.
+    //   children — Snippet, required. Toggle button elements.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <ToggleGroup label="Text formatting">...</ToggleGroup>
+    //
+    // Examples:
+    //   <!-- Text formatting toggle group -->
+    //   <ToggleGroup label="Text formatting">
+    //     <button aria-pressed="true">Bold</button>
+    //     <button aria-pressed="false">Italic</button>
+    //     <button aria-pressed="false">Underline</button>
+    //   </ToggleGroup>
+    //
+    // Keyboard:
+    //   - None at the container level; child buttons handle Tab, Enter/Space
+    //
+    // Accessibility:
+    //   - role="group" identifies the container as a semantic grouping
+    //   - aria-label={label} provides an accessible name describing the toggle collection
+    //
+    // Internationalization:
+    //   - The label prop accepts any translated string
+    //   - No hardcoded user-facing strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles -- consumer provides all styling
+    //   - Consumer provides toggle buttons with aria-pressed attributes
+    //
+    // References:
+    //   - WAI-ARIA group role: https://www.w3.org/TR/wai-aria-1.2/#group
+    //   - WAI-ARIA Button Pattern (toggle): https://www.w3.org/WAI/ARIA/apg/patterns/button/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        children,
+        ...restProps
+    }: {
+        /** Accessible label. */
+        label: string;
+        /** Toggle button elements. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ToggleGroup.svelte -->
+<div
+    class={`toggle-group ${className}`}
+    role="group"
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

package/dist/components/ToggleGroup/ToggleGroup.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible label. */
+    label: string;
+    /** Toggle button elements. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const ToggleGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type ToggleGroup = ReturnType<typeof ToggleGroup>;
+export default ToggleGroup;

package/dist/components/ToolBar/ToolBar.svelte

@@ -0,0 +1,114 @@
+<script lang="ts">
+    // ToolBar component
+    //
+    // A headless toolbar container that provides the ARIA toolbar role and built-in
+    // keyboard navigation for action buttons and controls. It implements the roving
+    // focus pattern with Left/Right arrow keys to move between items and Home/End
+    // keys to jump to first/last items. Focus wraps around from last to first and
+    // vice versa.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name for the toolbar via aria-label.
+    //   children — Snippet, required. ToolBarButton elements.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <ToolBar label="Editor tools">...</ToolBar>
+    //
+    // Examples:
+    //   <!-- Text editor toolbar -->
+    //   <ToolBar label="Editor tools">
+    //     <ToolBarButton>Bold</ToolBarButton>
+    //     <ToolBarButton>Italic</ToolBarButton>
+    //     <ToolBarButton>Underline</ToolBarButton>
+    //   </ToolBar>
+    //
+    // Keyboard:
+    //   - ArrowRight: move focus to next item (wraps to first)
+    //   - ArrowLeft: move focus to previous item (wraps to last)
+    //   - Home: move focus to first item
+    //   - End: move focus to last item
+    //   - Tab: enter/exit the toolbar
+    //
+    // Accessibility:
+    //   - role="toolbar" identifies the container as a toolbar widget
+    //   - aria-label provides the accessible name for the toolbar
+    //
+    // Internationalization:
+    //   - The label prop accepts any translated string
+    //   - No hardcoded user-facing strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles -- consumer provides all styling
+    //   - Compound component: use with ToolBarButton
+    //   - Uses horizontal (ArrowLeft/ArrowRight) navigation
+    //   - Arrow keys wrap around at boundaries
+    //
+    // References:
+    //   - WAI-ARIA Toolbar Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        children,
+        ...restProps
+    }: {
+        /** Accessible label. */
+        label: string;
+        /** ToolBarButton elements. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+
+    let toolbarRef: HTMLElement | undefined = $state(undefined);
+
+    function onkeydown(event: KeyboardEvent) {
+        if (!toolbarRef) return;
+        const items = Array.from(
+            toolbarRef.querySelectorAll<HTMLElement>(
+                "button, [role='button'], [tabindex]",
+            ),
+        );
+        const current = document.activeElement as HTMLElement;
+        const index = items.indexOf(current);
+        switch (event.key) {
+            case "ArrowRight": {
+                event.preventDefault();
+                const next = index < items.length - 1 ? index + 1 : 0;
+                items[next]?.focus();
+                break;
+            }
+            case "ArrowLeft": {
+                event.preventDefault();
+                const prev = index > 0 ? index - 1 : items.length - 1;
+                items[prev]?.focus();
+                break;
+            }
+            case "Home": {
+                event.preventDefault();
+                items[0]?.focus();
+                break;
+            }
+            case "End": {
+                event.preventDefault();
+                items[items.length - 1]?.focus();
+                break;
+            }
+        }
+    }
+</script>
+
+<!-- ToolBar.svelte -->
+<div
+    class={`tool-bar ${className}`}
+    role="toolbar"
+    aria-label={label}
+    bind:this={toolbarRef}
+    {onkeydown}
+    {...restProps}
+>
+    {@render children?.()}
+</div>