@lilydesignsystem/svelte-headless 0.6.0 → 0.6.2

package/dist/components/ScrollBar/ScrollBar.svelte

@@ -2,19 +2,27 @@
     // ScrollBar component
     //
     // A headless scrollbar track element that provides the ARIA scrollbar role
-    // and value attributes for a custom scrollbar control. Renders a <div> with
-    // orientation, value range, and accessible labeling. The consumer provides the
-    // visual thumb element as children and implements drag/scroll interaction logic.
+    // and value attributes for a custom scrollbar control. Renders a focusable
+    // <div> with orientation, value range, and accessible labeling, and owns the
+    // keyboard: the keys move the bindable value. The consumer provides the
+    // visual thumb element as children, scrolls its content to the value, and
+    // implements drag handling.
     //
     // Props:
     //   className — string, optional. CSS class name.
     //   orientation — "vertical" | "horizontal", default "vertical". The scrollbar direction.
+    //   value — number, default 0. Bindable. The scroll position, reflected in aria-valuenow.
+    //   min — number, default 0. The start of the range.
+    //   max — number, default 100. The end of the range.
+    //   step — number, default 1. The arrow-key increment.
+    //   pageStep — number, default 10. The Page Up / Page Down increment.
+    //   controls — string, optional. The id of the scrolled element, via aria-controls.
     //   label — string, required. Accessible name for the scrollbar via aria-label.
     //   children — Snippet, required. ScrollBar content, typically the draggable thumb element.
     //   ...restProps — additional HTML attributes spread onto the <div>.
     //
     // Syntax:
-    //   <ScrollBar orientation="vertical" label="Scroll">
+    //   <ScrollBar orientation="vertical" label="Scroll" controls="messages" bind:value={position}>
     //     <div>thumb</div>
     //   </ScrollBar>
     //
@@ -24,17 +32,18 @@
     //     <div class="thumb"></div>
     //   </ScrollBar>
     //
-    //   <!-- Vertical scrollbar with custom attributes -->
-    //   <ScrollBar orientation="vertical" label="Page scroll" aria-valuenow={scrollPos}>
+    //   <!-- Vertical scrollbar bound to the consumer's scroll position -->
+    //   <ScrollBar orientation="vertical" label="Page scroll" bind:value={scrollPos}>
     //     <div class="thumb"></div>
     //   </ScrollBar>
     //
     // Keyboard:
-    //   - Arrow Up/Left: scroll backward (decrease value) — consumer must implement
-    //   - Arrow Down/Right: scroll forward (increase value) — consumer must implement
-    //   - Page Up/Down: scroll by large increment — consumer must implement
-    //   - Home: scroll to beginning — consumer must implement
-    //   - End: scroll to end — consumer must implement
+    //   - Arrow Up/Left: decrease value by step
+    //   - Arrow Down/Right: increase value by step
+    //   - Page Up/Down: decrease/increase value by pageStep
+    //   - Home: value to min
+    //   - End: value to max
+    //   The value is clamped to [min, max].
     //
     // Accessibility:
     //   - role="scrollbar" identifies the element as a scrollbar control
@@ -47,8 +56,8 @@
     //
     // Claude rules:
     //   - Headless: no CSS, no styles — consumer provides all styling
-    //   - Initial value attributes (0/0/100) are defaults; consumer updates dynamically
-    //   - Consumer implements all drag handling and position updates
+    //   - The component moves the value on keys; the consumer scrolls its content to
+    //     the value, writes the value back as the content scrolls, and handles drag
     //
     // References:
     //   - WAI-ARIA scrollbar role: https://www.w3.org/TR/wai-aria-1.2/#scrollbar
@@ -58,18 +67,68 @@
     let {
         class: className = "",
         orientation = "vertical",
+        value = $bindable(0),
+        min = 0,
+        max = 100,
+        step = 1,
+        pageStep = 10,
+        controls = undefined,
         label,
         children,
         ...restProps
     }: {
         /** ScrollBar orientation. */
         orientation?: "vertical" | "horizontal";
+        /** Scroll position. Bindable. */
+        value?: number;
+        /** Start of the range. */
+        min?: number;
+        /** End of the range. */
+        max?: number;
+        /** Arrow-key increment. */
+        step?: number;
+        /** Page Up / Page Down increment. */
+        pageStep?: number;
+        /** Id of the scrolled element. */
+        controls?: string;
         /** Accessible label. */
         label: string;
         /** ScrollBar content. */
         children: Snippet;
         [key: string]: unknown;
     } = $props();
+
+    function clamp(v: number): number {
+        return Math.min(max, Math.max(min, v));
+    }
+
+    function onkeydown(event: KeyboardEvent) {
+        switch (event.key) {
+            case "ArrowUp":
+            case "ArrowLeft":
+                value = clamp(value - step);
+                break;
+            case "ArrowDown":
+            case "ArrowRight":
+                value = clamp(value + step);
+                break;
+            case "PageUp":
+                value = clamp(value - pageStep);
+                break;
+            case "PageDown":
+                value = clamp(value + pageStep);
+                break;
+            case "Home":
+                value = min;
+                break;
+            case "End":
+                value = max;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+    }
 </script>
 
 <!-- ScrollBar.svelte -->
@@ -78,9 +137,12 @@
     role="scrollbar"
     aria-label={label}
     aria-orientation={orientation}
-    aria-valuenow={0}
-    aria-valuemin={0}
-    aria-valuemax={100}
+    aria-controls={controls}
+    aria-valuenow={value}
+    aria-valuemin={min}
+    aria-valuemax={max}
+    tabindex="0"
+    {onkeydown}
     {...restProps}
 >
     {@render children?.()}

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

@@ -2,12 +2,24 @@ import type { Snippet } from "svelte";
 type $$ComponentProps = {
     /** ScrollBar orientation. */
     orientation?: "vertical" | "horizontal";
+    /** Scroll position. Bindable. */
+    value?: number;
+    /** Start of the range. */
+    min?: number;
+    /** End of the range. */
+    max?: number;
+    /** Arrow-key increment. */
+    step?: number;
+    /** Page Up / Page Down increment. */
+    pageStep?: number;
+    /** Id of the scrolled element. */
+    controls?: string;
     /** Accessible label. */
     label: string;
     /** ScrollBar content. */
     children: Snippet;
     [key: string]: unknown;
 };
-declare const ScrollBar: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const ScrollBar: import("svelte").Component<$$ComponentProps, {}, "value">;
 type ScrollBar = ReturnType<typeof ScrollBar>;
 export default ScrollBar;

package/dist/components/Scroller/Scroller.svelte

@@ -33,7 +33,10 @@
     aria-label={label}
     {...restProps}
 >
-    <div class="scroller-background" aria-live="polite">
+    <div
+        class="scroller-background"
+        aria-live="polite"
+    >
         {@render background?.()}
     </div>
     <ScrollerBase

package/dist/components/ScrollerBase/ScrollerBase.svelte

@@ -46,7 +46,7 @@
             {
                 rootMargin: `-${triggerFromTop} 0px -${(100 - offset * 100).toFixed(2)}% 0px`,
                 threshold: 0,
-            }
+            },
         );
         for (const step of steps) observer.observe(step);
 

package/dist/components/SectionLink/SectionLink.svelte

@@ -18,8 +18,6 @@
 <!-- SectionLink.svelte -->
 <a
     class={`section-link ${className}`}
-
-
     {href}
     {...restProps}
 >

package/dist/components/SectionList/SectionList.svelte

@@ -16,8 +16,6 @@
 <!-- SectionList.svelte -->
 <ul
     class={`section-list ${className}`}
-
-
     {...restProps}
 >
     {@render children?.()}

package/dist/components/SectionListItem/SectionListItem.svelte

@@ -18,9 +18,7 @@
 <!-- SectionListItem.svelte -->
 <li
     class={`section-list-item ${className}`}
-
-
-    aria-current={current ? "page" : undefined}
+    data-current={current ? "" : undefined}
     {...restProps}
 >
     {@render children?.()}

package/dist/components/SectionNav/SectionNav.svelte

@@ -16,7 +16,6 @@
 <!-- SectionNav.svelte -->
 <nav
     class={`section-nav ${className}`}
-
     aria-label={label}
     {...restProps}
 >

package/dist/components/Separator/Separator.svelte

@@ -52,6 +52,7 @@
 </script>
 
 <!-- Separator.svelte -->
+<!-- svelte-ignore a11y_no_redundant_roles (explicit role keeps the contract on wrapper hosts) -->
 <hr
     class={`separator ${className}`}
     role="separator"

package/dist/components/Sheet/Sheet.svelte

@@ -2,8 +2,10 @@
     // Sheet component
     //
     // A headless sliding panel overlay that appears from an edge of the viewport,
-    // functioning as a modal dialog. Conditionally rendered based on the open state,
-    // with Escape key to dismiss. Commonly used for navigation menus, settings panels,
+    // functioning as a modal dialog: while open it renders a native <dialog> opened
+    // with showModal() (see ../Dialog/modal.ts), so the page behind it is inert, Tab
+    // stays inside it, and focus returns to the opener when it closes.
+    // Conditionally rendered based on the open state, with Escape key to dismiss. Commonly used for navigation menus, settings panels,
     // detail views, or filter interfaces that slide in from the top, right, bottom, or left.
     //
     // Props:
@@ -12,7 +14,7 @@
     //   open — boolean, default false. Whether the sheet is visible; bindable via bind:open.
     //   side — "left" | "right" | "top" | "bottom", default "right". Which edge the sheet appears from.
     //   children — Snippet, required. Content to render inside the sheet.
-    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //   ...restProps — additional HTML attributes spread onto the <dialog>.
     //
     // Syntax:
     //   <Sheet label="Settings" bind:open side="right">
@@ -32,13 +34,14 @@
     //   </Sheet>
     //
     // Keyboard:
-    //   - Escape: closes the sheet by setting open to false
-    //   - Tab: moves focus between focusable elements within the sheet
+    //   - Escape: closes the sheet by setting open to false (also the native cancel event)
+    //   - Tab: moves focus between focusable elements within the sheet; showModal() keeps it inside
     //
     // Accessibility:
-    //   - role="dialog" identifies the sheet as a dialog window
+    //   - role="dialog" provided natively by the <dialog> element
     //   - aria-label provides an accessible name for the dialog
-    //   - aria-modal="true" indicates the dialog is modal (content behind is inert)
+    //   - aria-modal="true" is true: showModal() makes the content behind inert
+    //   - focus moves into the sheet on open and returns to the opener on close
     //   - tabindex="-1" allows programmatic focus on the dialog container
     //   - data-side attribute exposes the side for CSS targeting
     //
@@ -48,13 +51,15 @@
     // Claude rules:
     //   - Headless: no CSS, no styles — consumer provides all styling
     //   - Open uses $bindable() for two-way binding with bind:open
-    //   - Consumer implements focus trapping and slide-in animations via CSS
+    //   - Focus trapping comes from showModal() via ../Dialog/modal.ts (open-attribute fallback where it is
+    //     missing, e.g. jsdom); consumer implements slide-in animations via CSS
     //   - Completely removed from DOM when closed ({#if open})
     //
     // References:
     //   - WAI-ARIA Dialog (Modal) Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
 
     import type { Snippet } from "svelte";
+    import { modalDialog } from "../Dialog/modal.js";
 
     let {
         class: className = "",
@@ -81,20 +86,36 @@
             open = false;
         }
     }
+    function oncancel(event: Event) {
+        event.preventDefault();
+        open = false;
+    }
+    function onclose() {
+        open = false;
+    }
+    // Open as a real modal, then make sure focus is inside: showModal() already moves it in a browser, the
+    // open-attribute fallback does not.
+    function modal(node: HTMLDialogElement) {
+        const action = modalDialog(node, true);
+        if (!node.contains(document.activeElement)) node.focus();
+        return action;
+    }
 </script>
 
 <!-- Sheet.svelte -->
 {#if open}
-    <div
+    <dialog
         class={`sheet ${className}`}
-        role="dialog"
         aria-label={label}
         aria-modal="true"
         tabindex="-1"
         data-side={side}
+        use:modal
         {onkeydown}
+        {oncancel}
+        {onclose}
         {...restProps}
     >
         {@render children?.()}
-    </div>
+    </dialog>
 {/if}

package/dist/components/ShowMore/ShowMore.svelte

@@ -48,8 +48,15 @@
 </script>
 
 <!-- ShowMore.svelte -->
-<div class={`show-more ${className}`} {...restProps}>
-    <div class="show-more-content" id={contentId} data-expanded={expanded}>
+<div
+    class={`show-more ${className}`}
+    {...restProps}
+>
+    <div
+        class="show-more-content"
+        id={contentId}
+        data-expanded={expanded}
+    >
         {@render children?.()}
     </div>
     <button

package/dist/components/SlideOutDrawer/SlideOutDrawer.svelte

@@ -2,7 +2,9 @@
     // SlideOutDrawer component
     //
     // A headless slide-out drawer that renders a modal dialog container which
-    // slides in from the side of the screen. When open, it can be dismissed with
+    // slides in from the side of the screen. The container is a native <dialog>
+    // opened with showModal() (see ../Dialog/modal.ts): the page behind it is inert,
+    // Tab stays inside it, and focus returns to the opener when it closes. When open, it can be dismissed with
     // the Escape key. Commonly used for navigation menus, filters, settings panels,
     // or secondary content in mobile and web applications.
     //
@@ -11,7 +13,7 @@
     //   label — string, required. Accessible label for the dialog via aria-label.
     //   open — boolean, default false. Whether the drawer is visible; bindable via bind:open.
     //   children — Snippet, required. The drawer content.
-    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //   ...restProps — additional HTML attributes spread onto the <dialog>.
     //
     // Syntax:
     //   <SlideOutDrawer label="Menu" bind:open={isOpen}>
@@ -34,12 +36,14 @@
     //   </SlideOutDrawer>
     //
     // Keyboard:
-    //   - Escape: closes the drawer by setting open to false
+    //   - Escape: closes the drawer by setting open to false (also the native cancel event)
+    //   - Tab: stays inside the drawer while it is open
     //
     // Accessibility:
-    //   - role="dialog" for modal overlay semantics
+    //   - role="dialog" provided natively by the <dialog> element
     //   - aria-label describes the drawer purpose
-    //   - aria-modal="true" indicates modal behavior (content behind is inert)
+    //   - aria-modal="true" is true: showModal() makes the content behind inert
+    //   - focus moves into the drawer on open and returns to the opener on close
     //   - tabindex="-1" allows the dialog to receive programmatic focus
     //   - WCAG 2.2 AAA: properly labeled modal with keyboard dismissal
     //
@@ -51,13 +55,15 @@
     //   - Headless: no CSS, no styles — consumer provides all styling
     //   - Open uses $bindable() for two-way binding with bind:open
     //   - Completely removed from DOM when closed ({#if open})
-    //   - Consumer implements focus trapping and slide animations via CSS
+    //   - Focus trapping comes from showModal() via ../Dialog/modal.ts (open-attribute fallback where it is
+    //     missing, e.g. jsdom); consumer implements slide animations via CSS
     //
     // References:
     //   - WAI-ARIA Dialog (Modal) Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
     //   - WAI-ARIA dialog role: https://www.w3.org/TR/wai-aria-1.2/#dialog
 
     import type { Snippet } from "svelte";
+    import { modalDialog } from "../Dialog/modal.js";
 
     let {
         class: className = "",
@@ -79,22 +85,39 @@
     // Escape key closes the drawer, matching standard dialog behavior.
     function handleKeydown(event: KeyboardEvent) {
         if (event.key === "Escape") {
+            event.preventDefault();
             open = false;
         }
     }
+    function oncancel(event: Event) {
+        event.preventDefault();
+        open = false;
+    }
+    function onclose() {
+        open = false;
+    }
+    // Open as a real modal, then make sure focus is inside: showModal() already moves it in a browser, the
+    // open-attribute fallback does not.
+    function modal(node: HTMLDialogElement) {
+        const action = modalDialog(node, true);
+        if (!node.contains(document.activeElement)) node.focus();
+        return action;
+    }
 </script>
 
-<!-- SlideOutDrawer: a modal dialog container, conditionally rendered -->
+<!-- SlideOutDrawer: a modal <dialog>, conditionally rendered and opened with showModal() -->
 {#if open}
-    <div
+    <dialog
         class={`slide-out-drawer ${className}`}
-        role="dialog"
         aria-label={label}
         aria-modal="true"
         tabindex="-1"
+        use:modal
         onkeydown={handleKeydown}
+        {oncancel}
+        {onclose}
         {...restProps}
     >
         {@render children?.()}
-    </div>
+    </dialog>
 {/if}

package/dist/components/SliderButton/SliderButton.svelte

@@ -1,18 +1,76 @@
 <script lang="ts">
+    // SliderButton: a slide-to-confirm control. A <button role="slider"> whose aria-valuenow is the position, 0 to
+    // 100. ArrowRight/ArrowLeft move it by `step`; Home returns it to 0; End, Enter or Space complete it (the
+    // keyboard fallback for the drag). Reaching 100 calls `onconfirm` and resets to 0. The consumer draws the track
+    // and thumb from aria-valuenow, and wires pointer drag through the same position if it wants one.
     import type { Snippet } from "svelte";
     let {
         class: className = "",
-        label = undefined,
-        children,
+        label,
+        step = 10,
+        disabled = false,
+        onconfirm = undefined,
+        children = undefined,
         ...restProps
     }: {
-        label?: string;
-        children: Snippet;
+        /** Accessible label describing the confirmation action. */
+        label: string;
+        /** How far one arrow press moves the slider, in percent. */
+        step?: number;
+        disabled?: boolean;
+        /** Called when the slider reaches 100%. */
+        onconfirm?: () => void;
+        children?: Snippet;
         [key: string]: unknown;
     } = $props();
+
+    let position = $state(0);
+
+    function moveTo(next: number) {
+        if (next >= 100) {
+            position = 0;
+            onconfirm?.();
+        } else {
+            position = Math.max(0, next);
+        }
+    }
+
+    function onkeydown(event: KeyboardEvent) {
+        if (disabled) return;
+        switch (event.key) {
+            case "ArrowRight":
+                moveTo(position + step);
+                break;
+            case "ArrowLeft":
+                moveTo(position - step);
+                break;
+            case "Home":
+                moveTo(0);
+                break;
+            case "End":
+            case "Enter":
+            case " ":
+                moveTo(100);
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+    }
 </script>
 
 <!-- SliderButton.svelte -->
-<div class={`slider-button ${className}`} aria-label={label} {...restProps}>
+<button
+    type="button"
+    role="slider"
+    class={`slider-button ${className}`}
+    aria-label={label}
+    aria-valuenow={position}
+    aria-valuemin={0}
+    aria-valuemax={100}
+    {disabled}
+    {onkeydown}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</button>

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

@@ -1,7 +1,13 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
-    label?: string;
-    children: Snippet;
+    /** Accessible label describing the confirmation action. */
+    label: string;
+    /** How far one arrow press moves the slider, in percent. */
+    step?: number;
+    disabled?: boolean;
+    /** Called when the slider reaches 100%. */
+    onconfirm?: () => void;
+    children?: Snippet;
     [key: string]: unknown;
 };
 declare const SliderButton: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/SplitButton/SplitButton.svelte

@@ -52,13 +52,14 @@
     //   - WAI-ARIA Menu Button: https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
 
     import type { Snippet } from "svelte";
+    import { popoverState, popoverSupported, toggleOpened } from "../Popover/popover.js";
 
     let {
         class: className = "",
         label,
         primaryLabel,
         menuLabel,
-        menuOpen = false,
+        menuOpen = $bindable(false),
         disabled = false,
         onprimaryclick = undefined,
         onmenutoggle = undefined,
@@ -71,18 +72,30 @@
         primaryLabel: string;
         /** Accessible label for the menu trigger (required) */
         menuLabel: string;
-        /** Whether the dropdown menu is open */
+        /** Whether the dropdown menu is open. Bindable: the browser opens and light-dismisses it. */
         menuOpen?: boolean;
         /** Whether both buttons are disabled */
         disabled?: boolean;
         /** Primary action handler */
         onprimaryclick?: (event: MouseEvent) => void;
-        /** Menu toggle handler */
+        /** Menu toggle handler; call preventDefault() to keep the menu as it is */
         onmenutoggle?: (event: MouseEvent) => void;
         /** The menu content */
         children: Snippet;
         [key: string]: unknown;
     } = $props();
+
+    const uid = $props.id();
+    const menuId = `split-button-menu-${uid}`;
+    let menu: HTMLDivElement | undefined = $state();
+
+    // With the Popover API the trigger's command="toggle-popover" opens and closes the menu and the toggle event
+    // writes `menuOpen` back; without it, the click toggles `menuOpen` and popoverState sets `hidden`.
+    function toggle(event: MouseEvent) {
+        onmenutoggle?.(event);
+        if (event.defaultPrevented) return;
+        if (menu && !popoverSupported(menu)) menuOpen = !menuOpen;
+    }
 </script>
 
 <!-- SplitButton.svelte -->
@@ -107,9 +120,20 @@
         aria-haspopup="menu"
         aria-expanded={menuOpen}
         aria-label={menuLabel}
-        onclick={onmenutoggle}
+        aria-controls={menuId}
+        command="toggle-popover"
+        commandfor={menuId}
+        popovertarget={menuId}
+        onclick={toggle}
     ></button>
-    <div class="split-button-menu" hidden={!menuOpen}>
+    <div
+        bind:this={menu}
+        class="split-button-menu"
+        id={menuId}
+        popover="auto"
+        use:popoverState={menuOpen}
+        ontoggle={(event) => (menuOpen = toggleOpened(event))}
+    >
         {@render children?.()}
     </div>
 </div>

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

@@ -6,18 +6,18 @@ type $$ComponentProps = {
     primaryLabel: string;
     /** Accessible label for the menu trigger (required) */
     menuLabel: string;
-    /** Whether the dropdown menu is open */
+    /** Whether the dropdown menu is open. Bindable: the browser opens and light-dismisses it. */
     menuOpen?: boolean;
     /** Whether both buttons are disabled */
     disabled?: boolean;
     /** Primary action handler */
     onprimaryclick?: (event: MouseEvent) => void;
-    /** Menu toggle handler */
+    /** Menu toggle handler; call preventDefault() to keep the menu as it is */
     onmenutoggle?: (event: MouseEvent) => void;
     /** The menu content */
     children: Snippet;
     [key: string]: unknown;
 };
-declare const SplitButton: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const SplitButton: import("svelte").Component<$$ComponentProps, {}, "menuOpen">;
 type SplitButton = ReturnType<typeof SplitButton>;
 export default SplitButton;