@lilydesignsystem/svelte-headless 0.6.0 → 0.6.2

package/dist/components/ColombiaCedulaDeCiudadaniaInput/ColombiaCedulaDeCiudadaniaInput.svelte

@@ -0,0 +1,55 @@
+<script lang="ts">
+    // ColombiaCedulaDeCiudadaniaInput component
+    //
+    // A headless input for entering Colombia's Cedula de Ciudadania Number.
+    // Format: Six to ten digits, usually written with dots as thousands separators (1.020.304.050). Newer cards carry the ten-digit Número Único de Identificación Personal (NUIP). There is no check digit.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible label for screen readers via aria-label.
+    //   value — string, default "". Bindable input value; supports bind:value.
+    //   required — boolean, default false. Whether the input is required for form submission.
+    //   disabled — boolean, default false. Whether the input is disabled.
+    //   ...restProps — additional HTML attributes spread onto the <input>.
+    //
+    // Syntax:
+    //   <ColombiaCedulaDeCiudadaniaInput label="Cedula de Ciudadania Number" bind:value />
+    //
+    // Accessibility:
+    //   - aria-label provides the accessible name for screen readers
+    //   - autocomplete="off" protects sensitive identifiers
+    //   - required and disabled states are conveyed to assistive technology
+    //
+    // Internationalization:
+    //   - The label prop externalizes user-facing text for translation
+    //
+    // References:
+    //   - https://en.wikipedia.org/wiki/Colombian_identity_card
+
+    let {
+        class: className = "",
+        label,
+        value = $bindable(""),
+        required = false,
+        disabled = false,
+        ...restProps
+    }: {
+        label: string;
+        value?: string;
+        required?: boolean;
+        disabled?: boolean;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ColombiaCedulaDeCiudadaniaInput.svelte -->
+<input
+    class={`colombia-cedula-de-ciudadania-input ${className}`}
+    type="text"
+    aria-label={label}
+    autocomplete="off"
+    bind:value
+    {required}
+    {disabled}
+    {...restProps}
+/>

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

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

package/dist/components/ColombiaCedulaDeCiudadaniaView/ColombiaCedulaDeCiudadaniaView.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+    // ColombiaCedulaDeCiudadaniaView component
+    //
+    // A headless display component for showing Colombia's
+    // Cedula de Ciudadania Number in a read-only format.
+    // Format: Six to ten digits, usually written with dots as thousands separators (1.020.304.050). Newer cards carry the ten-digit Número Único de Identificación Personal (NUIP). There is no check digit.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible label for screen readers via aria-label.
+    //   value — string, default "". The identifier string to display.
+    //   ...restProps — additional HTML attributes spread onto the <span>.
+    //
+    // Syntax:
+    //   <ColombiaCedulaDeCiudadaniaView label="Cedula de Ciudadania Number" value={value} />
+    //
+    // Accessibility:
+    //   - aria-label provides the accessible name so screen readers announce the purpose
+    //
+    // References:
+    //   - https://en.wikipedia.org/wiki/Colombian_identity_card
+
+    let {
+        class: className = "",
+        label,
+        value = "",
+        ...restProps
+    }: {
+        label: string;
+        value?: string;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ColombiaCedulaDeCiudadaniaView.svelte -->
+<span
+    class={`colombia-cedula-de-ciudadania-view ${className}`}
+    aria-label={label}
+    {...restProps}>{value}</span
+>

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

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

package/dist/components/ColumnChart/ColumnChart.svelte

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

package/dist/components/Combobox/Combobox.svelte

@@ -57,6 +57,8 @@
     const uid = $props.id();
     const listboxId = `combobox-listbox-${uid}`;
 
+    import { popoverState } from "../Popover/popover.js";
+
     let {
         class: className = "",
         label,
@@ -99,13 +101,13 @@
         bind:value
         {onkeydown}
     />
-    {#if open}
-        <div
-            role="listbox"
-            id={listboxId}
-            aria-label={label}
-        >
-            {@render children?.()}
-        </div>
-    {/if}
+    <div
+        role="listbox"
+        popover="manual"
+        use:popoverState={open}
+        id={listboxId}
+        aria-label={label}
+    >
+        {@render children?.()}
+    </div>
 </div>

package/dist/components/Comment/Comment.svelte

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

package/dist/components/ComposedChart/ComposedChart.svelte

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

package/dist/components/ContentsListItem/ContentsListItem.svelte

@@ -58,6 +58,9 @@
 </script>
 
 <!-- ContentsListItem.svelte -->
-<li class={`contents-list-item ${className}`} {...restProps}>
+<li
+    class={`contents-list-item ${className}`}
+    {...restProps}
+>
     {@render children?.()}
 </li>

package/dist/components/ContentsNav/ContentsNav.svelte

@@ -1,3 +1,39 @@
+<script
+    lang="ts"
+    module
+>
+    /**
+     * Which section is current: the last whose top has passed the activation line
+     * (`tops` are each section's top relative to the scroller; `offset` is the line).
+     * At the bottom of the scroll range the last section wins (a short last section
+     * never reaches the line); before the first section, the first.
+     */
+    export function activeSectionIndex(tops: number[], offset: number, atBottom: boolean): number {
+        if (tops.length === 0) return -1;
+        if (atBottom) return tops.length - 1;
+        let index = 0;
+        for (let i = 0; i < tops.length; i++) {
+            if (tops[i] <= offset + 1) index = i;
+        }
+        return index;
+    }
+
+    /** The in-page `<a href="#id">` links inside `nav`. */
+    export function contentsLinks(nav: Element): HTMLAnchorElement[] {
+        return Array.from(nav.querySelectorAll<HTMLAnchorElement>('a[href^="#"]')).filter(
+            (a) => a.getAttribute("href")!.length > 1,
+        );
+    }
+
+    export function contentsLinkId(link: Element): string {
+        return decodeURIComponent((link.getAttribute("href") ?? "").slice(1));
+    }
+
+    export function contentsTarget(link: Element, doc: Document): HTMLElement | null {
+        return doc.getElementById(contentsLinkId(link));
+    }
+</script>
+
 <script lang="ts">
     // ContentsNav component
     //
@@ -131,7 +167,9 @@
             if (locked) return;
             if (hashPending) {
                 const id = decodeURIComponent(window.location.hash.slice(1));
-                const hashed = id ? contentsLinks(nav!).find((a) => contentsLinkId(a) === id) : undefined;
+                const hashed = id
+                    ? contentsLinks(nav!).find((a) => contentsLinkId(a) === id)
+                    : undefined;
                 if (hashed) {
                     mark(hashed);
                     return;
@@ -174,7 +212,12 @@
 
         function onClick(event: Event): void {
             const link = (event.target as Element | null)?.closest?.("a");
-            if (!link || !nav!.contains(link) || !contentsTarget(link as HTMLAnchorElement, nav!.ownerDocument)) return;
+            if (
+                !link ||
+                !nav!.contains(link) ||
+                !contentsTarget(link as HTMLAnchorElement, nav!.ownerDocument)
+            )
+                return;
             // The link is current at once; observer-style updates wait until the scroll settles.
             mark(link as HTMLAnchorElement);
             locked = true;
@@ -194,13 +237,21 @@
         window.addEventListener("hashchange", onHashChange);
         nav.addEventListener("click", onClick);
         // Links rendered or re-pointed after mount (a list built from data) are picked up too.
-        const mutations = typeof MutationObserver === "undefined" ? null : new MutationObserver(schedule);
-        mutations?.observe(nav, { childList: true, subtree: true, attributes: true, attributeFilter: ["href"] });
+        const mutations =
+            typeof MutationObserver === "undefined" ? null : new MutationObserver(schedule);
+        mutations?.observe(nav, {
+            childList: true,
+            subtree: true,
+            attributes: true,
+            attributeFilter: ["href"],
+        });
 
         // The URL hash wins on load; otherwise the position decides.
         const initial = decodeURIComponent(window.location.hash.slice(1));
         hashPending = initial !== "";
-        const hashLink = initial ? contentsLinks(nav).find((a) => contentsLinkId(a) === initial) : undefined;
+        const hashLink = initial
+            ? contentsLinks(nav).find((a) => contentsLinkId(a) === initial)
+            : undefined;
         if (hashLink) mark(hashLink);
         else update();
 
@@ -217,37 +268,6 @@
     });
 </script>
 
-<script lang="ts" module>
-    /**
-     * Which section is current: the last whose top has passed the activation line
-     * (`tops` are each section's top relative to the scroller; `offset` is the line).
-     * At the bottom of the scroll range the last section wins (a short last section
-     * never reaches the line); before the first section, the first.
-     */
-    export function activeSectionIndex(tops: number[], offset: number, atBottom: boolean): number {
-        if (tops.length === 0) return -1;
-        if (atBottom) return tops.length - 1;
-        let index = 0;
-        for (let i = 0; i < tops.length; i++) {
-            if (tops[i] <= offset + 1) index = i;
-        }
-        return index;
-    }
-
-    /** The in-page `<a href="#id">` links inside `nav`. */
-    export function contentsLinks(nav: Element): HTMLAnchorElement[] {
-        return Array.from(nav.querySelectorAll<HTMLAnchorElement>('a[href^="#"]')).filter((a) => a.getAttribute("href")!.length > 1);
-    }
-
-    export function contentsLinkId(link: Element): string {
-        return decodeURIComponent((link.getAttribute("href") ?? "").slice(1));
-    }
-
-    export function contentsTarget(link: Element, doc: Document): HTMLElement | null {
-        return doc.getElementById(contentsLinkId(link));
-    }
-</script>
-
 <!-- ContentsNav.svelte -->
 <nav
     bind:this={navEl}

package/dist/components/ContextMenu/ContextMenu.svelte

@@ -52,6 +52,7 @@
     //   - WAI-ARIA Menu Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/menu/
 
     import type { Snippet } from "svelte";
+    import { popoverState, toggleOpened } from "../Popover/popover.js";
 
     let {
         class: className = "",
@@ -75,8 +76,7 @@
     // When the menu opens, focus the first menuitem.
     $effect(() => {
         if (open && menuRef) {
-            const firstItem =
-                menuRef.querySelector<HTMLElement>("[role='menuitem']");
+            const firstItem = menuRef.querySelector<HTMLElement>("[role='menuitem']");
             firstItem?.focus();
         }
     });
@@ -84,9 +84,7 @@
     // Keyboard navigation within the menu.
     function onkeydown(event: KeyboardEvent) {
         if (!menuRef) return;
-        const items = Array.from(
-            menuRef.querySelectorAll<HTMLElement>("[role='menuitem']"),
-        );
+        const items = Array.from(menuRef.querySelectorAll<HTMLElement>("[role='menuitem']"));
         const current = document.activeElement as HTMLElement;
         const index = items.indexOf(current);
 
@@ -122,15 +120,19 @@
     }
 </script>
 
-{#if open}
-    <div
-        class={`context-menu ${className}`}
-        role="menu"
-        aria-label={label}
-        bind:this={menuRef}
-        {onkeydown}
-        {...restProps}
-    >
-        {@render children?.()}
-    </div>
-{/if}
+<!-- popover="auto": there is no declarative trigger (a right-click or long-press opens it), so popoverState shows it
+     with showPopover() when `open` turns true, in the top layer; light dismiss and Escape come from the browser and the
+     toggle event writes `open` back. Positioning at the pointer stays the consumer's CSS. -->
+<div
+    class={`context-menu ${className}`}
+    role="menu"
+    aria-label={label}
+    popover="auto"
+    bind:this={menuRef}
+    use:popoverState={open}
+    ontoggle={(event) => (open = toggleOpened(event))}
+    {onkeydown}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

package/dist/components/ContextualHelp/ContextualHelp.svelte

@@ -3,49 +3,56 @@
     //
     // A help button that opens a popover with explanatory content. Renders a
     // wrapper `<div>` containing a `<button>` trigger (aria-haspopup="dialog",
-    // aria-expanded, aria-controls) and a `<div role="dialog">` panel that is
-    // hidden when `expanded` is false. The panel id is auto-generated for
-    // a stable aria-controls relationship.
+    // aria-expanded, aria-controls) and a `<div role="dialog" popover="auto">`
+    // panel. The trigger opens and closes the panel through the native Popover
+    // API with command="toggle-popover" commandfor={panelId} (and popovertarget
+    // for engines before command/commandfor), so open, Escape and light dismiss
+    // need no script; the panel's `toggle` event keeps `expanded` in step. Where
+    // the Popover API is missing (jsdom, old engines) the trigger's click toggles
+    // `expanded` and the panel's `hidden` attribute instead.
     //
     // Props:
     //   class — string, optional. CSS class appended to the base class.
-    //   label — string, REQUIRED. aria-label for the trigger button.
-    //   expanded — boolean, default false. Whether the popover is open.
-    //   onclick — (event: MouseEvent) => void, optional. Trigger click handler.
+    //   label — string, REQUIRED. aria-label for the trigger button (its accessible name).
+    //   triggerLabel — string, REQUIRED. Visible text of the trigger, such as "?" or "؟".
+    //     No default: the glyph is the consumer's, per script and locale. Pass "" when
+    //     the consumer's CSS draws an icon instead.
+    //   expanded — boolean, default false, bindable. Whether the popover is open;
+    //     set by the browser's toggle (trigger, Escape, light dismiss).
+    //   onclick — (event: MouseEvent) => void, optional. Trigger click handler;
+    //     call event.preventDefault() to stop the trigger toggling the panel.
     //   children — Snippet, optional. Popover content.
     //
     // Syntax:
-    //   <ContextualHelp label="Help" expanded={open} onclick={toggle}>
+    //   <ContextualHelp label="Help" triggerLabel="?" bind:expanded>
     //       <p>Help content</p>
     //   </ContextualHelp>
     //
+    // Keyboard:
+    //   - Enter / Space on the trigger toggles the panel
+    //   - Escape closes the panel (browser, Popover API)
+    //
     // Accessibility:
     //   - Trigger: aria-haspopup="dialog", aria-expanded, aria-controls
-    //   - Panel: role="dialog", id matched by aria-controls
+    //   - Panel: role="dialog", id matched by aria-controls and commandfor
     //
     // Internationalization:
-    //   - All user-facing strings via props
+    //   - All user-facing strings via props: label (accessible name) and
+    //     triggerLabel (visible glyph or text)
     //
     // References:
     //   - Adobe Spectrum ContextualHelp: https://spectrum.adobe.com/page/contextual-help/
     //   - WAI-ARIA Dialog Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+    //   - HTML command and commandfor: https://html.spec.whatwg.org/multipage/form-elements.html#attr-button-command
 
     import type { Snippet } from "svelte";
-
-    function makeId(prefix: string): string {
-        if (
-            typeof crypto !== "undefined" &&
-            typeof crypto.randomUUID === "function"
-        ) {
-            return `${prefix}-${crypto.randomUUID()}`;
-        }
-        return `${prefix}-${Math.random().toString(36).slice(2, 11)}`;
-    }
+    import { popoverState, popoverSupported, toggleOpened } from "../Popover/popover.js";
 
     let {
         class: className = "",
         label,
-        expanded = false,
+        triggerLabel,
+        expanded = $bindable(false),
         onclick = undefined,
         children = undefined,
         ...restProps
@@ -53,7 +60,9 @@
         class?: string;
         /** Accessible label for the trigger (REQUIRED) */
         label: string;
-        /** Whether the popover is open */
+        /** Visible text of the trigger, such as "?" (REQUIRED; no default) */
+        triggerLabel: string;
+        /** Whether the popover is open. Bindable. */
         expanded?: boolean;
         /** Trigger click handler */
         onclick?: (event: MouseEvent) => void;
@@ -62,11 +71,25 @@
         [key: string]: unknown;
     } = $props();
 
-    const panelId = makeId("contextual-help-panel");
+    // Hydration-stable: the server and the client agree on it, so commandfor still names the panel.
+    const uid = $props.id();
+    const panelId = `contextual-help-panel-${uid}`;
+    let panel: HTMLDivElement | undefined = $state();
+
+    function toggle(event: MouseEvent) {
+        onclick?.(event);
+        if (event.defaultPrevented) return;
+        // With the Popover API the browser toggles the panel (command / popovertarget) and the toggle event
+        // updates `expanded`; without it, toggle here.
+        if (panel && !popoverSupported(panel)) expanded = !expanded;
+    }
 </script>
 
 <!-- ContextualHelp.svelte -->
-<div class={`contextual-help ${className}`} {...restProps}>
+<div
+    class={`contextual-help ${className}`}
+    {...restProps}
+>
     <button
         class="contextual-help-trigger"
         type="button"
@@ -74,13 +97,19 @@
         aria-haspopup="dialog"
         aria-expanded={expanded}
         aria-controls={panelId}
-        {onclick}
-    >?</button>
+        command="toggle-popover"
+        commandfor={panelId}
+        popovertarget={panelId}
+        onclick={toggle}>{triggerLabel}</button
+    >
     <div
+        bind:this={panel}
         class="contextual-help-panel"
         id={panelId}
         role="dialog"
-        hidden={!expanded}
+        popover="auto"
+        use:popoverState={expanded}
+        ontoggle={(event) => (expanded = toggleOpened(event))}
     >
         {#if children}
             {@render children?.()}

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

@@ -3,7 +3,9 @@ type $$ComponentProps = {
     class?: string;
     /** Accessible label for the trigger (REQUIRED) */
     label: string;
-    /** Whether the popover is open */
+    /** Visible text of the trigger, such as "?" (REQUIRED; no default) */
+    triggerLabel: string;
+    /** Whether the popover is open. Bindable. */
     expanded?: boolean;
     /** Trigger click handler */
     onclick?: (event: MouseEvent) => void;
@@ -11,6 +13,6 @@ type $$ComponentProps = {
     children?: Snippet;
     [key: string]: unknown;
 };
-declare const ContextualHelp: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const ContextualHelp: import("svelte").Component<$$ComponentProps, {}, "expanded">;
 type ContextualHelp = ReturnType<typeof ContextualHelp>;
 export default ContextualHelp;

package/dist/components/ConvertDiv/ConvertDiv.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+    // ConvertDiv component
+    //
+    // A headless part of ConvertDiv: a group that converts a value from one unit into another, such as dollars into euros or miles into kilometres. Contract: a plain <div> with the base class and children; role="group" named by `label`.
+    // Converts nothing and carries no strings of its own; the consumer supplies the controls.
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        children,
+        ...restProps
+    }: {
+        /** Accessible name of the group (required). */
+        label: string;
+
+        /** The content. */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ConvertDiv.svelte -->
+<div
+    class={`convert-div ${className}`}
+    role="group"
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible name of the group (required). */
+    label: string;
+    /** The content. */
+    children?: Snippet;
+    [key: string]: unknown;
+};
+declare const ConvertDiv: import("svelte").Component<$$ComponentProps, {}, "">;
+type ConvertDiv = ReturnType<typeof ConvertDiv>;
+export default ConvertDiv;

package/dist/components/ConvertFromDiv/ConvertFromDiv.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+    // ConvertFromDiv component
+    //
+    // A headless part of ConvertDiv: the source side of a conversion, holding the value and unit to convert from. Contract: a plain <div> with the base class and children.
+    // Converts nothing and carries no strings of its own; the consumer supplies the controls.
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: {
+        /** The content. */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ConvertFromDiv.svelte -->
+<div
+    class={`convert-from-div ${className}`}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

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

package/dist/components/ConvertFromUnitDiv/ConvertFromUnitDiv.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+    // ConvertFromUnitDiv component
+    //
+    // A headless part of ConvertDiv: the unit to convert from, such as a select box of currencies or lengths. Contract: a plain <div> with the base class and children.
+    // Converts nothing and carries no strings of its own; the consumer supplies the controls.
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: {
+        /** The content. */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ConvertFromUnitDiv.svelte -->
+<div
+    class={`convert-from-unit-div ${className}`}
+    {...restProps}
+>
+    {@render children?.()}
+</div>