@lilydesignsystem/svelte-headless 0.6.0 → 0.6.2

package/dist/components/Autosuggest/Autosuggest.svelte

@@ -1,24 +1,191 @@
 <script lang="ts">
-    import type { Snippet } from "svelte";
+    // Autosuggest component
+    //
+    // A text input that proposes matching options as users type: the WAI-ARIA
+    // combobox pattern with list autocomplete. The input is the combobox; the
+    // suggestions are a listbox of options. The consumer computes the
+    // suggestions in onInput (filtering, fetching) and passes them back in
+    // `suggestions`; the component owns the open state, the highlight, the keys
+    // and the selection.
+    //
+    // Props:
+    //   class — string, optional. Appended to the root's class list.
+    //   label — string, required. Accessible name of the input and the listbox.
+    //   value — string, default "". Bindable. The input's text.
+    //   suggestions — { value: string; label: string }[], default []. The options to show.
+    //   onInput — (query: string) => void, optional. Called as the user types.
+    //   onSelect — (value: string) => void, optional. Called when a suggestion is chosen.
+    //   placeholder — string, optional. Placeholder text.
+    //   name — string, optional. Form field name of the input.
+    //   ...restProps — additional HTML attributes spread onto the root <div>.
+    //
+    // Syntax:
+    //   <Autosuggest label="Country" bind:value {suggestions} onInput={search} />
+    //
+    // Keyboard:
+    //   - ArrowDown: open the list / highlight the next option (wraps)
+    //   - ArrowUp: open the list / highlight the previous option (wraps)
+    //   - Home / End: highlight the first / last option while the list is open
+    //   - Enter: choose the highlighted option
+    //   - Escape: close the list without choosing
+    //
+    // Accessibility:
+    //   - role="combobox" on the input, aria-autocomplete="list", aria-expanded,
+    //     aria-controls naming the listbox, aria-activedescendant naming the
+    //     highlighted option (which carries aria-selected="true")
+    //   - The list stays in the DOM, hidden while closed, so aria-controls always resolves
+    //
+    // Claude rules:
+    //   - Choosing an option writes its `value` into the input and closes the list
+    //   - The list opens only while there are suggestions; blur closes it
+    //   - Pressing on an option does not blur the input, so a click can choose it
+    //   - A form reset restores the starting text (defaultValue + bind:value)
+    //
+    // References:
+    //   - WAI-ARIA APG combobox pattern: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+
+    import { untrack } from "svelte";
+
+    const uid = $props.id();
+    const listId = `autosuggest-list-${uid}`;
+    const optionId = (index: number) => `autosuggest-option-${uid}-${index}`;
 
     let {
         class: className = "",
-        label = undefined,
-        children,
+        label,
+        value = $bindable(""),
+        suggestions = [],
+        onInput = undefined,
+        onSelect = undefined,
+        placeholder = undefined,
+        name = undefined,
         ...restProps
     }: {
-        label?: string;
-        children: Snippet;
+        /** Accessible label. */
+        label: string;
+        /** The input's text. Bindable. */
+        value?: string;
+        /** The options to show. */
+        suggestions?: { value: string; label: string }[];
+        /** Called with the typed text. */
+        onInput?: (query: string) => void;
+        /** Called with the chosen suggestion's value. */
+        onSelect?: (value: string) => void;
+        /** Placeholder text. */
+        placeholder?: string;
+        /** Form field name. */
+        name?: string;
         [key: string]: unknown;
     } = $props();
+
+    // The starting text, which a form reset restores (bind:value reads defaultValue).
+    const initialValue = untrack(() => value);
+    let wanted = $state(false);
+    let active = $state(-1);
+    const open = $derived(wanted && suggestions.length > 0);
+
+    function choose(index: number) {
+        const suggestion = suggestions[index];
+        if (!suggestion) return;
+        value = suggestion.value;
+        wanted = false;
+        active = -1;
+        onSelect?.(suggestion.value);
+    }
+
+    function oninput(event: Event) {
+        value = (event.currentTarget as HTMLInputElement).value;
+        wanted = true;
+        active = -1;
+        onInput?.(value);
+    }
+
+    function onkeydown(event: KeyboardEvent) {
+        const count = suggestions.length;
+        switch (event.key) {
+            case "ArrowDown":
+                if (count === 0) return;
+                active = open ? (active + 1) % count : 0;
+                wanted = true;
+                break;
+            case "ArrowUp":
+                if (count === 0) return;
+                active = open && active > 0 ? active - 1 : count - 1;
+                wanted = true;
+                break;
+            case "Home":
+                if (!open) return;
+                active = 0;
+                break;
+            case "End":
+                if (!open) return;
+                active = count - 1;
+                break;
+            case "Enter":
+                if (!open || active < 0) return;
+                choose(active);
+                break;
+            case "Escape":
+                if (!open) return;
+                wanted = false;
+                active = -1;
+                break;
+            default:
+                return;
+        }
+        event.preventDefault();
+    }
+
+    function onblur() {
+        wanted = false;
+        active = -1;
+    }
 </script>
 
 <!-- Autosuggest.svelte -->
 <div
     class={`autosuggest ${className}`}
-    role="combobox"
-    aria-label={label}
     {...restProps}
 >
-    {@render children?.()}
+    <input
+        class="autosuggest-input"
+        type="text"
+        role="combobox"
+        autocomplete="off"
+        aria-label={label}
+        aria-autocomplete="list"
+        aria-expanded={open}
+        aria-controls={listId}
+        aria-activedescendant={open && active >= 0 ? optionId(active) : undefined}
+        {placeholder}
+        {name}
+        bind:value
+        defaultValue={initialValue}
+        {oninput}
+        {onkeydown}
+        {onblur}
+    />
+    <!-- svelte-ignore a11y_no_noninteractive_element_interactions (keeps focus in the input while an option is pressed) -->
+    <ul
+        class="autosuggest-list"
+        role="listbox"
+        id={listId}
+        aria-label={label}
+        hidden={!open}
+        onmousedown={(event) => event.preventDefault()}
+    >
+        {#each suggestions as suggestion, index (suggestion.value)}
+            <!-- svelte-ignore a11y_click_events_have_key_events (the input owns the keys) -->
+            <li
+                class="autosuggest-option"
+                role="option"
+                id={optionId(index)}
+                aria-selected={index === active}
+                data-value={suggestion.value}
+                onclick={() => choose(index)}
+            >
+                {suggestion.label}
+            </li>
+        {/each}
+    </ul>
 </div>

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

@@ -1,9 +1,23 @@
-import type { Snippet } from "svelte";
 type $$ComponentProps = {
-    label?: string;
-    children: Snippet;
+    /** Accessible label. */
+    label: string;
+    /** The input's text. Bindable. */
+    value?: string;
+    /** The options to show. */
+    suggestions?: {
+        value: string;
+        label: string;
+    }[];
+    /** Called with the typed text. */
+    onInput?: (query: string) => void;
+    /** Called with the chosen suggestion's value. */
+    onSelect?: (value: string) => void;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Form field name. */
+    name?: string;
     [key: string]: unknown;
 };
-declare const Autosuggest: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const Autosuggest: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Autosuggest = ReturnType<typeof Autosuggest>;
 export default Autosuggest;

package/dist/components/AvatarGroup/AvatarGroup.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- AvatarGroup.svelte -->
-<div class={`avatar-group ${className}`} aria-label={label} {...restProps}>
+<div
+    class={`avatar-group ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
 </div>

package/dist/components/BarChart/BarChart.svelte

@@ -52,7 +52,11 @@
     class={`bar-chart ${className}`}
     {...restProps}
 >
-    <div class="bar-chart-graphic" role="img" aria-label={label}>
+    <div
+        class="bar-chart-graphic"
+        role="img"
+        aria-label={label}
+    >
         {@render children?.()}
     </div>
     {#if dataTable}

package/dist/components/BarcodeImage/BarcodeImage.svelte

@@ -14,4 +14,10 @@
 </script>
 
 <!-- BarcodeImage.svelte -->
-<img class={`barcode-image ${className}`} {src} {alt} {loading} {...restProps} />
+<img
+    class={`barcode-image ${className}`}
+    {src}
+    {alt}
+    {loading}
+    {...restProps}
+/>

package/dist/components/BreadcrumbLink/BreadcrumbLink.svelte

@@ -2,17 +2,27 @@
     import type { Snippet } from "svelte";
     let {
         class: className = "",
+        href,
         label = undefined,
         children,
         ...restProps
     }: {
+        /** The URL to navigate to. */
+        href: string;
+        /** Accessible label override for screen readers. */
         label?: string;
+        /** The link content. */
         children: Snippet;
         [key: string]: unknown;
     } = $props();
 </script>
 
 <!-- BreadcrumbLink.svelte -->
-<div class={`breadcrumb-link ${className}`} aria-label={label} {...restProps}>
+<a
+    class={`breadcrumb-link ${className}`}
+    {href}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</a>

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

@@ -1,6 +1,10 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
+    /** The URL to navigate to. */
+    href: string;
+    /** Accessible label override for screen readers. */
     label?: string;
+    /** The link content. */
     children: Snippet;
     [key: string]: unknown;
 };

package/dist/components/BreadcrumbListItem/BreadcrumbListItem.svelte

@@ -3,7 +3,7 @@
     //
     // A single step in a breadcrumb navigation trail. Renders as a semantic <li>
     // element designed to be placed inside a BreadcrumbList component. Supports
-    // aria-current="page" to indicate the user's current location. Typically
+    // data-current to indicate the user's current location. Typically
     // contains a link for ancestor pages, or plain text for the current page.
     //
     // Props:
@@ -27,7 +27,7 @@
     //
     // Accessibility:
     //   - Implicit listitem role from the semantic <li> element
-    //   - aria-current="page" set when current is true, indicating the user's location
+    //   - data-current set when current is true, indicating the user's location
     //
     // Internationalization:
     //   - All text comes through children snippet; no hardcoded strings
@@ -58,7 +58,7 @@
 <!-- BreadcrumbListItem.svelte -->
 <li
     class={`breadcrumb-list-item ${className}`}
-    aria-current={current ? "page" : undefined}
+    data-current={current ? "" : undefined}
     {...restProps}
 >
     {@render children?.()}

package/dist/components/Byline/Byline.svelte

@@ -27,7 +27,10 @@
 </script>
 
 <!-- Byline.svelte -->
-<div class={`byline ${className}`} {...restProps}>
+<div
+    class={`byline ${className}`}
+    {...restProps}
+>
     <span class="byline-authors">{@render children?.()}</span>
     {#if published}
         <span class="byline-published">{@render published()}</span>

package/dist/components/CandlestickChart/CandlestickChart.svelte

@@ -52,7 +52,11 @@
     class={`candlestick-chart ${className}`}
     {...restProps}
 >
-    <div class="candlestick-chart-graphic" role="img" aria-label={label}>
+    <div
+        class="candlestick-chart-graphic"
+        role="img"
+        aria-label={label}
+    >
         {@render children?.()}
     </div>
     {#if dataTable}

package/dist/components/Caption/Caption.svelte

@@ -54,6 +54,7 @@
 </script>
 
 <!-- Caption.svelte -->
+<!-- svelte-ignore a11y_figcaption_parent (Caption is a figure part; the consumer places it inside their <figure>) -->
 <figcaption
     class={`caption ${className}`}
     {...restProps}

package/dist/components/CareCard/CareCard.svelte

@@ -69,6 +69,7 @@
 </script>
 
 <!-- CareCard.svelte -->
+<!-- svelte-ignore a11y_no_redundant_roles (explicit role keeps the landmark when a wrapper host changes the tag) -->
 <section
     class={`care-card ${className}`}
     role="region"

package/dist/components/Cascader/Cascader.svelte

@@ -39,6 +39,8 @@
 
     import type { Snippet } from "svelte";
 
+    import { popoverState } from "../Popover/popover.js";
+
     let {
         class: className = "",
         label,
@@ -87,7 +89,11 @@
     >
         {value ?? placeholder ?? ""}
     </button>
-    <div class="cascader-panel" hidden={!expanded}>
+    <div
+        class="cascader-panel"
+        popover="manual"
+        use:popoverState={expanded}
+    >
         {#if children}{@render children?.()}{/if}
     </div>
 </div>

package/dist/components/ChatComposer/ChatComposer.svelte

@@ -86,7 +86,11 @@
 </script>
 
 <!-- ChatComposer.svelte -->
-<form class={`chat-composer ${className}`} onsubmit={onSubmit} {...restProps}>
+<form
+    class={`chat-composer ${className}`}
+    onsubmit={onSubmit}
+    {...restProps}
+>
     {@render children?.()}
     <textarea
         class="chat-composer-input"
@@ -96,8 +100,7 @@
         {placeholder}
         {name}
         {disabled}
-        onkeydown={onKeydown}
-    ></textarea>
+        onkeydown={onKeydown}></textarea>
     <button
         class="chat-composer-button"
         type={busy ? "button" : "submit"}

package/dist/components/ChatList/ChatList.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- ChatList.svelte -->
-<div class={`chat-list ${className}`} aria-label={label} {...restProps}>
+<ol
+    class={`chat-list ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</ol>

package/dist/components/ChatListItem/ChatListItem.svelte

@@ -3,16 +3,24 @@
     let {
         class: className = "",
         label = undefined,
+        current = false,
         children,
         ...restProps
     }: {
         label?: string;
+        /** Marks the currently selected conversation (aria-current="true"). */
+        current?: boolean;
         children: Snippet;
         [key: string]: unknown;
     } = $props();
 </script>
 
 <!-- ChatListItem.svelte -->
-<div class={`chat-list-item ${className}`} aria-label={label} {...restProps}>
+<li
+    class={`chat-list-item ${className}`}
+    aria-label={label}
+    aria-current={current ? "true" : undefined}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</li>

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

@@ -1,6 +1,8 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     label?: string;
+    /** Marks the currently selected conversation (aria-current="true"). */
+    current?: boolean;
     children: Snippet;
     [key: string]: unknown;
 };

package/dist/components/ChatMessage/ChatMessage.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- ChatMessage.svelte -->
-<div class={`chat-message ${className}`} aria-label={label} {...restProps}>
+<article
+    class={`chat-message ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</article>

package/dist/components/ChatNav/ChatNav.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- ChatNav.svelte -->
-<div class={`chat-nav ${className}`} aria-label={label} {...restProps}>
+<nav
+    class={`chat-nav ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</nav>

package/dist/components/CheckListItem/CheckListItem.svelte

@@ -61,7 +61,10 @@
 </script>
 
 <!-- CheckListItem.svelte -->
-<li class={`check-list-item ${className}`} {...restProps}>
+<li
+    class={`check-list-item ${className}`}
+    {...restProps}
+>
     <label>
         <input
             type="checkbox"

package/dist/components/CheckboxGroup/CheckboxGroup.svelte

@@ -72,6 +72,7 @@
 </script>
 
 <!-- CheckboxGroup.svelte -->
+<!-- svelte-ignore a11y_no_redundant_roles (explicit role=group is part of the documented contract) -->
 <fieldset
     class={`checkbox-group ${className}`}
     role="group"

package/dist/components/ChoroplethChart/ChoroplethChart.svelte

@@ -52,7 +52,11 @@
     class={`choropleth-chart ${className}`}
     {...restProps}
 >
-    <div class="choropleth-chart-graphic" role="img" aria-label={label}>
+    <div
+        class="choropleth-chart-graphic"
+        role="img"
+        aria-label={label}
+    >
         {@render children?.()}
     </div>
     {#if dataTable}

package/dist/components/Citation/Citation.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- Citation.svelte -->
-<div class={`citation ${className}`} aria-label={label} {...restProps}>
+<cite
+    class={`citation ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</cite>

package/dist/components/Coachmark/Coachmark.svelte

@@ -27,7 +27,7 @@
     //   - role="dialog" with aria-modal="false" (non-modal popover dialog)
     //   - aria-labelledby points at the heading
     //   - aria-describedby points at the description (when provided)
-    //   - hidden attribute removes the closed coachmark from the AT tree
+    //   - closed, it is display: none (popover="manual", or the hidden attribute where the Popover API is missing), so out of the AT tree
     //
     // Internationalization:
     //   - All user-facing strings via props
@@ -37,15 +37,14 @@
     //   - WAI-ARIA Dialog Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
 
     function makeId(prefix: string): string {
-        if (
-            typeof crypto !== "undefined" &&
-            typeof crypto.randomUUID === "function"
-        ) {
+        if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
             return `${prefix}-${crypto.randomUUID()}`;
         }
         return `${prefix}-${Math.random().toString(36).slice(2, 11)}`;
     }
 
+    import { popoverState } from "../Popover/popover.js";
+
     let {
         class: className = "",
         open = false,
@@ -80,17 +79,28 @@
     aria-modal="false"
     aria-labelledby={titleId}
     aria-describedby={description ? descId : undefined}
-    hidden={!open}
+    popover="manual"
+    use:popoverState={open}
     {...restProps}
 >
-    <h2 class="coachmark-title" id={titleId}>{title}</h2>
+    <h2
+        class="coachmark-title"
+        id={titleId}
+    >
+        {title}
+    </h2>
     {#if description}
-        <p class="coachmark-description" id={descId}>{description}</p>
+        <p
+            class="coachmark-description"
+            id={descId}
+        >
+            {description}
+        </p>
     {/if}
     <button
         class="coachmark-dismiss"
         type="button"
         aria-label={dismissLabel}
-        onclick={onDismiss}
-    >×</button>
+        onclick={onDismiss}>×</button
+    >
 </div>

package/dist/components/Code/Code.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- Code.svelte -->
-<div class={`code ${className}`} aria-label={label} {...restProps}>
+<code
+    class={`code ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</code>

package/dist/components/CodeBlock/CodeBlock.svelte

@@ -13,6 +13,10 @@
 </script>
 
 <!-- CodeBlock.svelte -->
-<div class={`code-block ${className}`} aria-label={label} {...restProps}>
+<pre
+    class={`code-block ${className}`}
+    aria-label={label}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+</pre>

package/dist/components/CollectionListItem/CollectionListItem.svelte

@@ -85,7 +85,7 @@
     {/if}
     <h3 class="collection-list-item-heading">
         {#if href}
-            <a href={href}>{heading}</a>
+            <a {href}>{heading}</a>
         {:else}
             {heading}
         {/if}