@lilydesignsystem/svelte-headless 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/)
 and the package follows [Semantic Versioning](https://semver.org/).
 
+## 0.5.0 — 2026-10-14 (scrollspy, link counts)
+
+- `ContentsNav` gains scrollspy (`spy`): the link of the section in view gets `aria-current` and `data-active`. Props `spy`, `offset`, `root`, `current`, bindable `active`, `onActiveChange`.
+- `ContentsLink` gains `count` and `countLabel`: a visible, localised count inside the link, with `data-count` (and `data-complete` at 0). The Svelte `ContentsLink` is now a real `<a>` (it was a placeholder `<div>`).
+
+## Unreleased — 2026-10-11 (labels and contracts)
+
+`PinInputDiv` takes `digitLabel` and no longer names its boxes in English; `FiveStarRatingPicker` takes `starLabel`; `FiveFaceRatingPicker` / `FiveFaceRatingView` default their labels to the numbers. `Tag` is not a live region unless `live` is set. The form-reset fixes listed above now also reach `components/`, which the build publishes. See the repository CHANGELOG (2026-10-11).
+
+## Unreleased — 2026-10-11
+
+Fixed: `FiveStarRatingPicker`, `FiveFaceRatingPicker`, `NetPromoterScorePicker` and `PinInputDiv` restore their initial value when their `<form>` is reset (one tick after `reset`, unless it is
+cancelled); before, a reset changed the inputs without telling the component, so its value disagreed with what the
+form showed or submitted. `PinInputDiv` also now shows its initial `value` instead of overwriting it with an empty string on mount.
+
 ## 0.4.0 — 2026-10-06
 
 **16 new components (catalog 555 → 571); no breaking changes.**

package/dist/components/ContentsLink/ContentsLink.svelte

@@ -1,18 +1,52 @@
 <script lang="ts">
+    // ContentsLink component
+    //
+    // One table of contents link: an <a href> to a page section, with an optional count (for example
+    // of tasks to do in that section).
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   href — string, default "#". The link target.
+    //   label — string, optional. aria-label override. It replaces the link's whole accessible name, so
+    //     if you also show a count, include the count in it.
+    //   count — number, optional. Sets data-count on the link (and data-complete when 0), as CSS hooks.
+    //   countLabel — string, optional. Visible, localised count text (e.g. "3 to do"), rendered inside
+    //     the link after the text so the link's accessible name includes it. No default, no English.
+    //   children — Snippet, required. The link text.
+    //   ...restProps — additional HTML attributes spread onto the <a>.
+    //
+    // Accessibility:
+    //   - The count is text inside the link, never colour alone (WCAG 1.4.1).
+
     import type { Snippet } from "svelte";
+
     let {
         class: className = "",
         label = undefined,
+        href = "#",
+        count = undefined,
+        countLabel = undefined,
         children,
         ...restProps
     }: {
         label?: string;
+        href?: string;
+        count?: number;
+        countLabel?: string;
         children: Snippet;
         [key: string]: unknown;
     } = $props();
 </script>
 
 <!-- ContentsLink.svelte -->
-<div class={`contents-link ${className}`} aria-label={label} {...restProps}>
+<a
+    class={`contents-link ${className}`}
+    {href}
+    aria-label={label}
+    data-count={count}
+    data-complete={count === 0 ? "" : undefined}
+    {...restProps}
+>
     {@render children?.()}
-</div>
+    {#if countLabel}<span class="contents-link-count">{countLabel}</span>{/if}
+</a>

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

@@ -1,6 +1,9 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     label?: string;
+    href?: string;
+    count?: number;
+    countLabel?: string;
     children: Snippet;
     [key: string]: unknown;
 };

package/dist/components/ContentsNav/ContentsNav.svelte

@@ -10,8 +10,21 @@
     //   className — string, optional. CSS class name.
     //   label — string, required. Accessible name for the navigation landmark (e.g., "Contents").
     //   children — Snippet, required. Typically a ContentsList component.
+    //   spy — boolean, default false. Scrollspy: mark the link of the section currently in view.
+    //   offset — number, default 0. Scrollspy activation line, in px below the top of `root`
+    //     (set it to a fixed header's height, matching the targets' scroll-margin-top).
+    //   root — HTMLElement | null, default null (the viewport). A scrolling element other than the viewport.
+    //   current — string, default "true". The aria-current token set on the active link.
+    //   active — string, bindable. The id of the section currently in view (spy only).
+    //   onActiveChange — (id: string) => void, optional. Called when the active section changes.
     //   ...restProps — additional HTML attributes spread onto the <nav>.
     //
+    // Scrollspy (spy): the links are the consumer's own `<a href="#id">` elements inside the nav. The
+    //   active section is the last one whose top has passed the activation line; at the bottom of the
+    //   scroll range the last section is active; before the first section, the first. The active link gets
+    //   aria-current={current} and data-active; its ancestor <li>s get data-descendant-active. A click makes
+    //   its link active at once and holds it until the scroll settles. Lily never animates or moves focus.
+    //
     // Syntax:
     //   <ContentsNav label="Contents">
     //     <ContentsList>
@@ -53,12 +66,191 @@
         class: className = "",
         label,
         children,
+        spy = false,
+        offset = 0,
+        root = null,
+        current = "true",
+        active = $bindable(""),
+        onActiveChange,
         ...restProps
-    }: { label: string; children: Snippet; [key: string]: unknown } = $props();
+    }: {
+        label: string;
+        children: Snippet;
+        spy?: boolean;
+        offset?: number;
+        root?: HTMLElement | null;
+        current?: string;
+        active?: string;
+        onActiveChange?: (id: string) => void;
+        [key: string]: unknown;
+    } = $props();
+
+    let navEl: HTMLElement | undefined = $state();
+
+    $effect(() => {
+        const nav = navEl;
+        if (!spy || !nav || typeof window === "undefined") return;
+        const spyOffset = offset;
+        const spyRoot = root;
+        const token = current;
+        let locked = false;
+        let lockTimer: ReturnType<typeof setTimeout> | undefined;
+        let frame = 0;
+        let last = "";
+        // Until the reader first scrolls, the URL hash decides (links may render after mount).
+        let hashPending = false;
+
+        const scroller: Window | HTMLElement = spyRoot ?? window;
+
+        function mark(link: HTMLAnchorElement | undefined): void {
+            for (const a of contentsLinks(nav!)) {
+                if (a === link) {
+                    a.setAttribute("aria-current", token);
+                    a.setAttribute("data-active", "");
+                } else {
+                    a.removeAttribute("aria-current");
+                    a.removeAttribute("data-active");
+                }
+            }
+            for (const li of nav!.querySelectorAll("li")) {
+                if (link && li.contains(link) && li.querySelector(":scope > a") !== link) {
+                    li.setAttribute("data-descendant-active", "");
+                } else {
+                    li.removeAttribute("data-descendant-active");
+                }
+            }
+            const id = link ? contentsLinkId(link) : "";
+            if (id !== last) {
+                last = id;
+                active = id;
+                if (id) onActiveChange?.(id);
+            }
+        }
+
+        function update(): void {
+            if (locked) return;
+            if (hashPending) {
+                const id = decodeURIComponent(window.location.hash.slice(1));
+                const hashed = id ? contentsLinks(nav!).find((a) => contentsLinkId(a) === id) : undefined;
+                if (hashed) {
+                    mark(hashed);
+                    return;
+                }
+            }
+            const links = contentsLinks(nav!);
+            const pairs = links
+                .map((a) => ({ a, el: contentsTarget(a, nav!.ownerDocument) }))
+                .filter((p): p is { a: HTMLAnchorElement; el: HTMLElement } => p.el !== null);
+            if (pairs.length === 0) {
+                mark(undefined);
+                return;
+            }
+            const base = spyRoot ? spyRoot.getBoundingClientRect().top : 0;
+            const tops = pairs.map((p) => p.el.getBoundingClientRect().top - base);
+            const atBottom = spyRoot
+                ? spyRoot.scrollTop + spyRoot.clientHeight >= spyRoot.scrollHeight - 1
+                : window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 1;
+            mark(pairs[activeSectionIndex(tops, spyOffset, atBottom)].a);
+        }
+
+        function schedule(): void {
+            if (frame) return;
+            frame = requestAnimationFrame(() => {
+                frame = 0;
+                update();
+            });
+        }
+
+        function onScroll(): void {
+            hashPending = false;
+            schedule();
+        }
+
+        function release(): void {
+            locked = false;
+            if (lockTimer) clearTimeout(lockTimer);
+            update();
+        }
+
+        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;
+            // The link is current at once; observer-style updates wait until the scroll settles.
+            mark(link as HTMLAnchorElement);
+            locked = true;
+            if (lockTimer) clearTimeout(lockTimer);
+            lockTimer = setTimeout(release, 1000);
+        }
+
+        function onHashChange(): void {
+            const id = decodeURIComponent(window.location.hash.slice(1));
+            const link = contentsLinks(nav!).find((a) => contentsLinkId(a) === id);
+            if (link) mark(link);
+        }
+
+        scroller.addEventListener("scroll", onScroll, { passive: true });
+        scroller.addEventListener("scrollend", release);
+        window.addEventListener("resize", schedule);
+        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"] });
+
+        // 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;
+        if (hashLink) mark(hashLink);
+        else update();
+
+        return () => {
+            scroller.removeEventListener("scroll", onScroll);
+            scroller.removeEventListener("scrollend", release);
+            window.removeEventListener("resize", schedule);
+            window.removeEventListener("hashchange", onHashChange);
+            nav.removeEventListener("click", onClick);
+            mutations?.disconnect();
+            if (frame) cancelAnimationFrame(frame);
+            if (lockTimer) clearTimeout(lockTimer);
+        };
+    });
+</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}
     class={`contents-nav ${className}`}
     aria-label={label}
     {...restProps}

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

@@ -1,9 +1,26 @@
+/**
+ * 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 declare function activeSectionIndex(tops: number[], offset: number, atBottom: boolean): number;
+/** The in-page `<a href="#id">` links inside `nav`. */
+export declare function contentsLinks(nav: Element): HTMLAnchorElement[];
+export declare function contentsLinkId(link: Element): string;
+export declare function contentsTarget(link: Element, doc: Document): HTMLElement | null;
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     label: string;
     children: Snippet;
+    spy?: boolean;
+    offset?: number;
+    root?: HTMLElement | null;
+    current?: string;
+    active?: string;
+    onActiveChange?: (id: string) => void;
     [key: string]: unknown;
 };
-declare const ContentsNav: import("svelte").Component<$$ComponentProps, {}, "">;
+declare const ContentsNav: import("svelte").Component<$$ComponentProps, {}, "active">;
 type ContentsNav = ReturnType<typeof ContentsNav>;
 export default ContentsNav;

package/dist/components/DataTableTD/DataTableTD.svelte

@@ -2,13 +2,12 @@
     // DataTableTD component
     //
     // A single data cell within a DataTableRow. Renders as a <td> with
-    // role="gridcell". Supports an active state for indicating the currently
-    // focused or selected cell, communicated via aria-selected for screen
-    // readers. Uses a roving tabindex pattern.
+    // role="gridcell". Supports an active state marking the grid's single roving tab
+    // stop (tabindex="0"); it does not set aria-selected.
     //
     // Props:
     //   className — string, optional. CSS class name.
-    //   active — boolean, default false. Whether this cell is active/selected.
+    //   active — boolean, default false. Whether this cell is the roving tab stop.
     //   children — Snippet, required. Cell content.
     //   ...restProps — additional HTML attributes spread onto the <td>.
     //
@@ -21,7 +20,7 @@
     //
     // Accessibility:
     //   - role="gridcell" identifies the cell as part of an interactive grid
-    //   - aria-selected set to true when active; omitted otherwise
+    //   - `active` is the roving tab stop only: it never sets aria-selected, because focus is not selection (a grid with real selection passes aria-selected itself)
     //   - Roving tabindex: tabindex="0" when active, "-1" otherwise
     //
     // Claude rules:
@@ -39,7 +38,7 @@
         children,
         ...restProps
     }: {
-        /** Whether this cell is active/selected. */
+        /** Whether this cell is the roving tab stop (tabindex="0"). Never sets aria-selected. */
         active?: boolean;
         /** Cell content. */
         children: Snippet;
@@ -51,7 +50,6 @@
 <td
     class={`data-table-td ${className}`}
     role="gridcell"
-    aria-selected={active || undefined}
     tabindex={active ? 0 : -1}
     {...restProps}
 >

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

@@ -1,6 +1,6 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
-    /** Whether this cell is active/selected. */
+    /** Whether this cell is the roving tab stop (tabindex="0"). Never sets aria-selected. */
     active?: boolean;
     /** Cell content. */
     children: Snippet;

package/dist/components/FiveFaceRatingPicker/FiveFaceRatingPicker.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+    import { untrack } from "svelte";
     // FiveFaceRatingPicker component
     //
     // A five-face rating input that lets users select a satisfaction level from 1 to 5
@@ -11,7 +12,7 @@
     //   label — string, required. Accessible name for the rating group via aria-label.
     //   value — number, default 0. Current rating (1-5, 0 = none); bindable via bind:value.
     //   name — string, default "face-rating". Radio group name for form submission.
-    //   labels — string[], default ["Very bad", "Bad", "Okay", "Good", "Very good"]. Accessible labels for each face.
+    //   labels — string[], default ["1", "2", "3", "4", "5"] (no English default; pass words, e.g. ["Very bad", …, "Very good"]). Accessible labels for each face.
     //   disabled — boolean, default false. Whether the entire group is disabled.
     //   ...restProps — additional HTML attributes spread onto the fieldset.
     //
@@ -53,7 +54,8 @@
         label,
         value = $bindable(0),
         name = "face-rating",
-        labels = ["Very bad", "Bad", "Okay", "Good", "Very good"],
+        // The numbers, not English words: the words are the consumer's to supply.
+        labels = ["1", "2", "3", "4", "5"],
         disabled = false,
         ...restProps
     }: {
@@ -71,10 +73,38 @@
     } = $props();
 
     const faces = [1, 2, 3, 4, 5];
+
+    // Form reset: the radios use a one-way `checked`, which a reset clears
+    // without telling this component, so `value` would keep a rating the form no
+    // longer submits. Restore the initial value instead — one tick later, after
+    // the browser has reset the DOM, and not when the reset was cancelled.
+    let root: HTMLFieldSetElement | undefined = $state();
+    const initialValue = untrack(() => value);
+    $effect(() => {
+        const form = root?.form ?? root?.closest("form");
+        if (!form) return;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const onReset = (event: Event) => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                if (event.defaultPrevented || !root) return;
+                value = initialValue;
+                for (const input of root.querySelectorAll<HTMLInputElement>('input[type="radio"]')) {
+                    input.checked = input.value === String(initialValue);
+                }
+            }, 0);
+        };
+        form.addEventListener("reset", onReset);
+        return () => {
+            clearTimeout(timer);
+            form.removeEventListener("reset", onReset);
+        };
+    });
 </script>
 
 <!-- FiveFaceRatingPicker.svelte -->
 <fieldset
+    bind:this={root}
     class={`five-face-rating-picker ${className}`}
     role="radiogroup"
     aria-label={label}

package/dist/components/FiveFaceRatingView/FiveFaceRatingView.svelte

@@ -10,7 +10,7 @@
     //   className — string, optional. CSS class name.
     //   value — number, required. Rating value (1-5) to display.
     //   label — string, required. Accessible description via aria-label.
-    //   labels — string[], default ["Very bad", "Bad", "Okay", "Good", "Very good"]. Text labels for each face.
+    //   labels — string[], default ["1", "2", "3", "4", "5"] (no English default; pass words, e.g. ["Very bad", …, "Very good"]). Text labels for each face.
     //   ...restProps — additional HTML attributes spread onto the span.
     //
     // Syntax:
@@ -46,7 +46,8 @@
         class: className = "",
         value,
         label,
-        labels = ["Very bad", "Bad", "Okay", "Good", "Very good"],
+        // The numbers, not English words: the words are the consumer's to supply.
+        labels = ["1", "2", "3", "4", "5"],
         ...restProps
     }: {
         /** Rating value (1-5). */

package/dist/components/FiveStarRatingPicker/FiveStarRatingPicker.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+    import { untrack } from "svelte";
     // FiveStarRatingPicker component
     //
     // A five-star rating input that lets users select a rating from 1 to 5 stars using
@@ -9,6 +10,7 @@
     // Props:
     //   className — string, optional. CSS class name.
     //   label — string, required. Accessible name for the rating group via aria-label.
+    //   starLabel — (star: number) => string, optional. Each option's text; defaults to the number (no English).
     //   value — number, default 0. Current rating (1-5, 0 = none); bindable via bind:value.
     //   name — string, default "rating". Radio group name for form submission.
     //   disabled — boolean, default false. Whether the entire group is disabled.
@@ -52,6 +54,7 @@
         label,
         value = $bindable(0),
         name = "rating",
+        starLabel,
         disabled = false,
         ...restProps
     }: {
@@ -61,16 +64,46 @@
         value?: number;
         /** Radio group name for form submission. */
         name?: string;
+        /** Each option's text, e.g. (n) => `${n} stars`. Defaults to the number alone: no English default. */
+        starLabel?: (star: number) => string;
         /** Whether the entire group is disabled. */
         disabled?: boolean;
         [key: string]: unknown;
     } = $props();
 
     const stars = [1, 2, 3, 4, 5];
+
+    // Form reset: the radios use a one-way `checked`, which a reset clears
+    // without telling this component, so `value` would keep a rating the form no
+    // longer submits. Restore the initial value instead — one tick later, after
+    // the browser has reset the DOM, and not when the reset was cancelled.
+    let root: HTMLFieldSetElement | undefined = $state();
+    const initialValue = untrack(() => value);
+    $effect(() => {
+        const form = root?.form ?? root?.closest("form");
+        if (!form) return;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const onReset = (event: Event) => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                if (event.defaultPrevented || !root) return;
+                value = initialValue;
+                for (const input of root.querySelectorAll<HTMLInputElement>('input[type="radio"]')) {
+                    input.checked = input.value === String(initialValue);
+                }
+            }, 0);
+        };
+        form.addEventListener("reset", onReset);
+        return () => {
+            clearTimeout(timer);
+            form.removeEventListener("reset", onReset);
+        };
+    });
 </script>
 
 <!-- FiveStarRatingPicker.svelte -->
 <fieldset
+    bind:this={root}
     class={`five-star-rating-picker ${className}`}
     role="radiogroup"
     aria-label={label}
@@ -86,8 +119,7 @@
                 checked={value === star}
                 onchange={() => (value = star)}
             />
-            {star}
-            {star === 1 ? "star" : "stars"}
+            {starLabel ? starLabel(star) : star}
         </label>
     {/each}
 </fieldset>

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

@@ -5,6 +5,8 @@ type $$ComponentProps = {
     value?: number;
     /** Radio group name for form submission. */
     name?: string;
+    /** Each option's text, e.g. (n) => `${n} stars`. Defaults to the number alone: no English default. */
+    starLabel?: (star: number) => string;
     /** Whether the entire group is disabled. */
     disabled?: boolean;
     [key: string]: unknown;

package/dist/components/GanttTableTD/GanttTableTD.svelte

@@ -3,8 +3,8 @@
     //
     // A single cell within a GanttTableTr representing a time period in the
     // Gantt table grid. Renders as a <td> with role="gridcell". Supports an
-    // active state to indicate the task spans this time period, communicated
-    // via aria-selected for screen readers.
+    // active state that makes the cell a tab stop (tabindex="0"); it does
+    // not set aria-selected, which would announce focus as selection.
     //
     // Props:
     //   className — string, optional. CSS class name.
@@ -31,7 +31,7 @@
     //
     // Accessibility:
     //   - role="gridcell" identifies the cell as part of a grid
-    //   - aria-selected set to true when active; omitted otherwise
+    //   - `active` is the roving tab stop only: it never sets aria-selected, because focus is not selection (a grid with real selection passes aria-selected itself)
     //   - Roving tabindex: tabindex="0" when active, "-1" otherwise
     //
     // Internationalization:
@@ -65,7 +65,6 @@
 <td
     class={`gantt-table-td ${className}`}
     role="gridcell"
-    aria-selected={active || undefined}
     tabindex={active ? 0 : -1}
     {...restProps}
 >

package/dist/components/KanbanTableTD/KanbanTableTD.svelte

@@ -7,7 +7,7 @@
     //
     // Props:
     //   className — string, optional. CSS class name.
-    //   active — boolean, optional. Marks the cell as currently active/selected.
+    //   active — boolean, optional. Marks the cell as the roving tab stop.
     //   label — string, optional. Accessible name for the cell via aria-label.
     //   children — Snippet, optional. Cell content such as task cards or text.
     //   ...restProps — additional HTML attributes spread onto the <td>.
@@ -28,7 +28,7 @@
     //
     // Accessibility:
     //   - role="gridcell" identifies the cell as part of a grid
-    //   - aria-selected indicates the active/selected state when active is true
+    //   - `active` is the roving tab stop only: it never sets aria-selected, because focus is not selection (a grid with real selection passes aria-selected itself)
     //   - tabindex enables roving tabindex (0 when active, -1 otherwise)
     //   - aria-label optionally provides an accessible name for the cell
     //
@@ -52,7 +52,7 @@
         children,
         ...restProps
     }: {
-        /** Marks the cell as currently active/selected. */
+        /** Marks the cell as the roving tab stop (tabindex="0"). Never sets aria-selected. */
         active?: boolean;
         /** Accessible name for the cell. */
         label?: string;
@@ -66,7 +66,6 @@
 <td
     class={`kanban-table-td ${className}`}
     role="gridcell"
-    aria-selected={active || undefined}
     tabindex={active ? 0 : -1}
     aria-label={label}
     {...restProps}

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

@@ -1,6 +1,6 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
-    /** Marks the cell as currently active/selected. */
+    /** Marks the cell as the roving tab stop (tabindex="0"). Never sets aria-selected. */
     active?: boolean;
     /** Accessible name for the cell. */
     label?: string;

package/dist/components/NetPromoterScorePicker/NetPromoterScorePicker.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+    import { untrack } from "svelte";
     // NetPromoterScorePicker component
     //
     // A headless Net Promoter Score (NPS) rating input that renders a fieldset
@@ -69,10 +70,38 @@
         name?: string;
         [key: string]: unknown;
     } = $props();
+
+    // Form reset: the radios use a one-way `checked`, which a reset clears
+    // without telling this component, so `value` would keep a rating the form no
+    // longer submits. Restore the initial value instead — one tick later, after
+    // the browser has reset the DOM, and not when the reset was cancelled.
+    let root: HTMLFieldSetElement | undefined = $state();
+    const initialValue = untrack(() => value);
+    $effect(() => {
+        const form = root?.form ?? root?.closest("form");
+        if (!form) return;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const onReset = (event: Event) => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                if (event.defaultPrevented || !root) return;
+                value = initialValue;
+                for (const input of root.querySelectorAll<HTMLInputElement>('input[type="radio"]')) {
+                    input.checked = input.value === String(initialValue);
+                }
+            }, 0);
+        };
+        form.addEventListener("reset", onReset);
+        return () => {
+            clearTimeout(timer);
+            form.removeEventListener("reset", onReset);
+        };
+    });
 </script>
 
 <!-- NetPromoterScorePicker: a fieldset radiogroup with 11 radio buttons (0-10) -->
 <fieldset
+    bind:this={root}
     class={`net-promoter-score-picker ${className}`}
     role="radiogroup"
     aria-label={label}

package/dist/components/PinInputDiv/PinInputDiv.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+    import { untrack } from "svelte";
     // PinInputDiv component
     //
     // A headless PIN input that renders a group of single-character numeric inputs
@@ -12,6 +13,7 @@
     //   className — string, optional. CSS class name.
     //   label — string, required. Accessible label for the group of inputs via aria-label.
     //   length — number, default 4. Number of digit inputs to render.
+    //   digitLabel — (position, length) => string, optional. Each input's accessible name; defaults to `label`.
     //   value — string, default "". Bindable combined string of all entered digits.
     //   disabled — boolean, default false. Whether all inputs are disabled.
     //   ...restProps — additional HTML attributes spread onto the group <div>.
@@ -60,6 +62,7 @@
         class: className = "",
         label,
         length = 4,
+        digitLabel,
         value = $bindable(""),
         disabled = false,
         ...restProps
@@ -68,6 +71,11 @@
         label: string;
         /** Number of digit inputs to render */
         length?: number;
+        /**
+         * Each digit input's accessible name, e.g. (n, of) => `Digit ${n} of ${of}`.
+         * Without it each input is named by `label`: no English default.
+         */
+        digitLabel?: (position: number, length: number) => string;
         /** Combined string of all entered digits, bindable */
         value?: string;
         /** Whether all inputs are disabled */
@@ -79,7 +87,12 @@
     // Internal state: array of individual digit characters.
     // Note: the length prop is captured at initialization time for the initial
     // array size. This is intentional -- the pin length is expected to be static.
-    let digits: string[] = $state(Array.from({ length }, () => ""));
+    // Seeded from the initial `value`: starting empty meant the effect below
+    // overwrote a bound starting value with "" on mount.
+    const initialDigits = untrack(() =>
+        Array.from({ length }, (_, i) => (/^[0-9]$/.test(value[i] ?? "") ? value[i] : "")),
+    );
+    let digits: string[] = $state([...initialDigits]);
 
     // References to each input element for focus management
     let inputRefs: HTMLInputElement[] = $state([]);
@@ -93,6 +106,32 @@
     });
 
     // Handle input events on individual digit fields
+    // Form reset: the digit inputs use a one-way `value`, which a reset clears
+    // without telling this component, so `value` would keep digits the fields no
+    // longer show. Restore the initial digits instead — one tick later, after the
+    // browser has reset the DOM, and not when the reset was cancelled.
+    let root: HTMLDivElement | undefined = $state();
+    $effect(() => {
+        const form = root?.closest("form");
+        if (!form) return;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        const onReset = (event: Event) => {
+            clearTimeout(timer);
+            timer = setTimeout(() => {
+                if (event.defaultPrevented) return;
+                digits = [...initialDigits];
+                inputRefs.forEach((input, i) => {
+                    if (input) input.value = initialDigits[i];
+                });
+            }, 0);
+        };
+        form.addEventListener("reset", onReset);
+        return () => {
+            clearTimeout(timer);
+            form.removeEventListener("reset", onReset);
+        };
+    });
+
     function handleInput(index: number, event: Event): void {
         const target = event.target as HTMLInputElement;
         const inputValue = target.value;
@@ -137,6 +176,7 @@
 
 <!-- PinInputDiv.svelte -->
 <div
+    bind:this={root}
     class={`pin-input-div ${className}`}
     role="group"
     aria-label={label}
@@ -148,7 +188,7 @@
             type="text"
             inputmode="numeric"
             maxlength="1"
-            aria-label={`Digit ${index + 1} of ${length}`}
+            aria-label={digitLabel ? digitLabel(index + 1, length) : label}
             value={digits[index]}
             {disabled}
             oninput={(e) => handleInput(index, e)}

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

@@ -3,6 +3,11 @@ type $$ComponentProps = {
     label: string;
     /** Number of digit inputs to render */
     length?: number;
+    /**
+     * Each digit input's accessible name, e.g. (n, of) => `Digit ${n} of ${of}`.
+     * Without it each input is named by `label`: no English default.
+     */
+    digitLabel?: (position: number, length: number) => string;
     /** Combined string of all entered digits, bindable */
     value?: string;
     /** Whether all inputs are disabled */

package/dist/components/Tag/Tag.svelte

@@ -47,11 +47,18 @@
     let {
         class: className = "",
         label,
+        live = false,
         children,
         ...restProps
     }: {
         /** Accessible label for screen readers */
         label: string;
+        /**
+         * Announce changes: a `role="status"` live region, for a tag whose text
+         * changes in place (a job's status). Off by default — a page of static
+         * tags should not be a page of live regions.
+         */
+        live?: boolean;
         /** The tag content (text, icon, etc.) */
         children: Snippet;
         /** Additional HTML attributes */
@@ -60,11 +67,16 @@
 </script>
 
 <!-- Tag.svelte -->
-<span
-    class={`tag ${className}`}
-    role="status"
-    aria-label={label}
-    {...restProps}
->
-    {@render children?.()}
-</span>
+{#if live}
+    <span class={`tag ${className}`} role="status" aria-label={label} {...restProps}>
+        {@render children?.()}
+    </span>
+{:else}
+    <!-- Not a live region: aria-label is not allowed on a plain <span>, so the
+         label is screen-reader text appended after the content (the themes hide
+         .screen-reader-span). The content stays exposed: it may hold a focusable
+         control, such as a remove button. -->
+    <span class={`tag ${className}`} {...restProps}>
+        {@render children?.()}{#if label}<span class="screen-reader-span">{label}</span>{/if}
+    </span>
+{/if}

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

@@ -2,6 +2,12 @@ import type { Snippet } from "svelte";
 type $$ComponentProps = {
     /** Accessible label for screen readers */
     label: string;
+    /**
+     * Announce changes: a `role="status"` live region, for a tag whose text
+     * changes in place (a job's status). Off by default — a page of static
+     * tags should not be a page of live regions.
+     */
+    live?: boolean;
     /** The tag content (text, icon, etc.) */
     children: Snippet;
     /** Additional HTML attributes */

package/index.md

@@ -85,7 +85,7 @@ A headless Svelte 5 component library with 490 components. All components are he
   - **data-table-td**: a data table interactive grid data cell for displaying and sorting tabular data
 - **date-field**: a structured field for entering date components
 - **date-input**: an input for entering a date value
-- **date-range**: a display of a start and end date range
+- **date-range**: paired start and end date inputs
 - **date-time-now-input**: an input for entering a date and time and "now" button
 - **date-time-local-input**: an input for entering a date and time without time zone
 - **details**: a disclosure widget that shows and hides content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lilydesignsystem/svelte-headless",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "engines": {
     "node": "=26"
   },
@@ -14,7 +14,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/LilyDesignSystem/lily-design-system-svelte-headless.git"
+    "url": "git+https://github.com/LilyDesignSystem/lily-design-system.git",
+    "directory": "lily-design-system-svelte-headless"
   },
   "keywords": [
     "lily",