@lilydesignsystem/svelte-headless 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog — @lilydesignsystem/svelte-headless
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/)
+and the package follows [Semantic Versioning](https://semver.org/).
+
+## 0.1.0 — 2026-09-16
+
+**Package renamed: `lily-design-system-svelte-headless` → `@lilydesignsystem/svelte-headless`.** npm scoped packages
+are registry-distinct from their unscoped counterparts, so this is a
+new package with no publish history of its own — version reset to
+`0.1.0` per this project's established rename precedent (the July
+2026 `*-select` → `*-picker` rename). No code or behaviour change
+relative to `lily-design-system-svelte-headless`'s last published version (`0.1.0`);
+its full changelog continues below, now read as history prior to the
+rescope. The old unscoped name is deprecated on the registry (never
+unpublished), pointing consumers here.
+
+---
+
+## 0.3.1 — 2026-08-26
+
+Metadata-only patch; no code change. Ships the corrected package
+metadata to the registry:
+
+- `license` is the project SPDX menu (`MIT OR Apache-2.0 OR
+  GPL-2.0-only OR GPL-3.0-only OR BSD-3-Clause`), replacing the
+  single-license field that contradicted the repository's LICENSE.md.
+- `repository`, `homepage`, and `bugs` point at the LilyDesignSystem
+  organisation and the documentation site.
+- `description` says "Targets WCAG 2.2 AAA." — the previous
+  "WCAG 2.2 AAA compliant" claimed a conformance no audit supports.
+- `author` names the maintainer rather than a bare email address.
+
+Also as of this release, 0.2.0 is marked deprecated on npm (it
+declared a `main` that was never built; see 0.3.0's notes).
+
+## 0.3.0 — 2026-08-23
+
+### Fixed
+
+- **The package had no entry point.** `package.json` declared
+  `"main": "index.js"` and no such file was ever built or shipped, so
+  every `import … from "@lilydesignsystem/svelte-headless"` failed at
+  resolution. 0.2.0 is broken on npm for this reason. The package now
+  builds a real `dist/` with svelte-package and points `main`/`types`/
+  `exports` at it.
+
+### Added
+
+- A generated barrel (`index.ts`, written by `build.mjs`) exporting all
+  491 components in the catalog. It is generated rather than
+  hand-maintained because the catalog grows, and a hand-written list
+  silently omits new components.
+- `build.mjs` — generates the barrel, builds `dist/`, and fails loudly if
+  the bundle comes out empty.
+- A `files` allowlist.
+
+### Changed
+
+- **Tarball contents.** Previously the package shipped its entire working
+  tree — sources, tests, Storybook stories, docs and config. It now ships
+  only `dist/` plus the docs.
+- `peerDependencies` now declares the framework it needs.
+- The description said "236 components"; the catalog has 491.
+
+### Also fixed
+
+- `ProgressCircle`'s tests queried `getByRole("Progress")`, which is not a
+  valid ARIA role and never matched; the component correctly renders
+  `role="progressbar"`. Those four tests had been failing, in both the
+  `components/` and `src/lib/components/` mirrors.
+
+All 4906 tests pass; 8 were failing before.

package/LICENSE.md

@@ -0,0 +1,64 @@
+<!-- Synced from the canonical repository by bin/sync-special-files.
+     Do not edit here; edit the root copy and re-run the script.
+     Canonical: https://github.com/LilyDesignSystem/lily-design-system/blob/main/LICENSE.md -->
+
+# License
+
+Lily Design System™ is free open source software.
+
+License is any of these, at your option, or contact us for custom license options.
+
+* [MIT](https://opensource.org/license/mit) ([SPDX: MIT](https://spdx.org/licenses/MIT.html))
+
+* [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0) ([SPDX: Apache-2.0](https://spdx.org/licenses/Apache-2.0.html))
+
+* [GNU General Public License v2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html) ([SPDX: GPL-2.0-only](https://spdx.org/licenses/GPL-2.0-only.html))
+
+* [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0-standalone.html) ([SPDX: GPL-3.0-only](https://spdx.org/licenses/GPL-3.0-only.html))
+
+* [BSD 3-Clause License](https://opensource.org/license/bsd-3-clause) ([SPDX: BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html))
+
+## SPDX
+
+The machine-readable expression for the choice above is:
+
+```
+SPDX-License-Identifier: MIT OR Apache-2.0 OR GPL-2.0-only OR GPL-3.0-only OR BSD-3-Clause
+```
+
+Every package manifest in this repository should carry that expression, or a
+single identifier from the list where the packaging format does not accept a
+disjunction. You do not need permission to pick one: choose whichever member of
+the list suits your project and comply with that one.
+
+This applies to the whole repository — the component catalog, the seven headless
+libraries, the seven example applications, the seven helper catalogs, the
+`themes/` stylesheets, the `bin/` tooling, and the documentation.
+
+## Scope note
+
+This file supersedes an earlier `CC BY-NC-SA` notice. That notice was a content
+license with a non-commercial clause, it was not an open-source license, and it
+contradicted both the specification and the published packages. It should not be
+relied on. If you obtained Lily under it and that raises a question for you,
+contact <joel@joelparkerhenderson.com>.
+
+## Trademarks
+
+Lily™ and Lily Design System™ are trademarks. The trademarks are distinct from
+the software license: a trademark claim (™) asserts use of the marks and is
+independent of the licenses above. A license to the software is not a license to
+the marks.
+
+You may say your project uses Lily, is built with Lily, or is compatible with
+Lily. Please do not use the marks as the name of your fork or product, or in a
+way that suggests affiliation or endorsement. For any use beyond that, contact
+<joel@joelparkerhenderson.com>.
+
+## Third-party references
+
+Lily's example applications and `themes/` stylesheets take visual reference from
+public-sector design systems including NHS UK, GOV.UK, and USWDS. Lily is not
+affiliated with, endorsed by, or connected to any of those organisations. Their
+names and marks belong to them, and this license grants nothing in respect of
+them.

package/dist/components/AccordionCheckbox/AccordionCheckbox.svelte

@@ -0,0 +1,115 @@
+<script lang="ts">
+    // AccordionCheckbox component
+    //
+    // A compound disclosure widget that pairs a checkbox option with a
+    // revealable panel. The user sees a checkbox option; checking the box
+    // reveals an accordion panel of additional content beneath it. Multiple
+    // AccordionCheckbox instances stacked vertically form a list of
+    // independent toggleable options.
+    //
+    // Unlike Details, which uses a <summary> toggle, this component uses a
+    // real form control. The `checked` prop is the source of truth.
+    //
+    // Props:
+    //   class — string, optional. CSS class name appended to .accordion-checkbox.
+    //   label — string, required. Checkbox label text.
+    //   checked — boolean, default false. Whether the checkbox is checked
+    //             and the panel is revealed; bindable.
+    //   id — string, optional. Base id for the checkbox/panel link;
+    //        auto-generated if not provided.
+    //   children — Snippet, required. Content shown when checked.
+    //   ...restProps — additional HTML attributes spread onto the root <div>.
+    //
+    // Syntax:
+    //   <AccordionCheckbox label="Show options">…</AccordionCheckbox>
+    //
+    // Examples:
+    //   <!-- Basic disclosure -->
+    //   <AccordionCheckbox label="I have a follow-up question">
+    //     <textarea aria-label="Your question"></textarea>
+    //   </AccordionCheckbox>
+    //
+    //   <!-- Two-way binding with parent state -->
+    //   <AccordionCheckbox label="Subscribe to updates" bind:checked={subscribe}>
+    //     <p>Choose your topics below.</p>
+    //   </AccordionCheckbox>
+    //
+    // Keyboard:
+    //   - Tab: moves focus onto the checkbox
+    //   - Space: toggles the checkbox (native), revealing or hiding the panel
+    //
+    // Accessibility:
+    //   - aria-controls on the checkbox references the panel id
+    //   - aria-expanded on the checkbox reflects the checked state
+    //   - role="region" + aria-labelledby on the panel
+    //   - hidden attribute on the panel when unchecked
+    //
+    // Internationalization:
+    //   - The label prop accepts any string; consumers provide localized text
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses $bindable() on checked for two-way state synchronization
+    //   - Auto-generates a unique id so multiple instances do not collide
+    //
+    // References:
+    //   - WAI-ARIA Disclosure Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/
+    //   - MDN input type=checkbox: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox
+    //   - MDN aria-controls: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        checked = $bindable(false),
+        id,
+        children,
+        ...restProps
+    }: {
+        /** Checkbox label text. */
+        label: string;
+        /** Whether the checkbox is checked. Bindable. */
+        checked?: boolean;
+        /** Base id for the checkbox/panel link. */
+        id?: string;
+        /** Content shown when checked. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+
+    const generatedId = `accordion-checkbox-${Math.random().toString(36).slice(2, 9)}`;
+    const baseId = $derived(id ?? generatedId);
+    const checkboxId = $derived(`${baseId}-checkbox`);
+    const panelId = $derived(`${baseId}-panel`);
+</script>
+
+<!-- AccordionCheckbox.svelte -->
+<div
+    class={`accordion-checkbox ${className}`}
+    {...restProps}
+>
+    <input
+        type="checkbox"
+        class="accordion-checkbox-input"
+        id={checkboxId}
+        aria-controls={panelId}
+        aria-expanded={checked}
+        bind:checked
+    />
+    <label
+        class="accordion-checkbox-label"
+        for={checkboxId}
+    >
+        {label}
+    </label>
+    <div
+        class="accordion-checkbox-panel"
+        id={panelId}
+        role="region"
+        aria-labelledby={checkboxId}
+        hidden={!checked}
+    >
+        {@render children?.()}
+    </div>
+</div>

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

@@ -0,0 +1,15 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Checkbox label text. */
+    label: string;
+    /** Whether the checkbox is checked. Bindable. */
+    checked?: boolean;
+    /** Base id for the checkbox/panel link. */
+    id?: string;
+    /** Content shown when checked. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const AccordionCheckbox: import("svelte").Component<$$ComponentProps, {}, "checked">;
+type AccordionCheckbox = ReturnType<typeof AccordionCheckbox>;
+export default AccordionCheckbox;

package/dist/components/AccordionLink/AccordionLink.svelte

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

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

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

package/dist/components/AccordionList/AccordionList.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+    // AccordionList component
+    //
+    // AccordionList elements within an AccordionNav. Provides an optional
+    // accessible label for the list.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, optional. Accessible name for the group via aria-label.
+    //   children — Snippet, required. AccordionListItem elements.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Note: Renders a <div> (not <ol>) because AccordionListItem renders <details>,
+    // and <details> is not a valid child of <ol>/<ul>.
+    //
+    // Syntax:
+    //   <AccordionNav>
+    //     <AccordionList>
+    //       <AccordionListItem>...</AccordionListItem>
+    //     </AccordionList>
+    //   </AccordionNav>
+    //
+    // Examples:
+    //   <AccordionNav label="My Nav">
+    //     <AccordionList label="Questions">
+    //       <AccordionListItem>
+    //         <summary>What is this?</summary>
+    //         <p>A design system.</p>
+    //       </AccordionListItem>
+    //     </AccordionList>
+    //  </AccordionNav>
+    //
+    // Keyboard: None — passive container. Keyboard interactions are handled
+    // by AccordionListItem children.
+    //
+    // Accessibility:
+    //   - aria-label optionally provides an accessible name for the group
+    //
+    // Internationalization:
+    //   - The label prop accepts any translated string
+    //   - No hardcoded text
+    //
+    // Claude rules:
+    //   - Compound component — used inside AccordionNav, contains AccordionListItem children
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //
+    // References:
+    //   - WAI-ARIA group role: https://www.w3.org/TR/wai-aria-1.2/#group
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = "",
+        children,
+        ...restProps
+    }: {
+        /** Optional accessible label for the group. */
+        label?: string;
+        /** AccordionListItem elements. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- AccordionList.svelte -->
+<div
+    class={`accordion-list ${className}`}
+    role="group"
+    aria-label={label || undefined}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Optional accessible label for the group. */
+    label?: string;
+    /** AccordionListItem elements. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const AccordionList: import("svelte").Component<$$ComponentProps, {}, "">;
+type AccordionList = ReturnType<typeof AccordionList>;
+export default AccordionList;

package/dist/components/AccordionListItem/AccordionListItem.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+    // AccordionListItem component
+    //
+    // A single expandable section within an AccordionList, using the native
+    // HTML <details> element for built-in disclosure behavior. The consumer
+    // provides a <summary> element (the clickable header) and content (the
+    // expandable body) as children. The open prop is two-way bindable via
+    // $bindable(), allowing parent components to programmatically control
+    // and observe the expanded state.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   open — boolean, default false, bindable. Whether the item is expanded.
+    //   children — Snippet, required. A <summary> and content elements.
+    //   ...restProps — additional HTML attributes spread onto <details>.
+    //
+    // Syntax:
+    //   <AccordionListItem>
+    //     <summary>Header</summary>
+    //     <p>Content</p>
+    //   </AccordionListItem>
+    //
+    // Examples:
+    //   <!-- Basic accordion item -->
+    //   <AccordionListItem>
+    //     <summary>What is Svelte?</summary>
+    //     <p>A compiler-based UI framework.</p>
+    //   </AccordionListItem>
+    //
+    //   <!-- Pre-expanded with binding -->
+    //   <AccordionListItem bind:open={isOpen}>
+    //     <summary>Details</summary>
+    //     <p>Expanded content.</p>
+    //   </AccordionListItem>
+    //
+    // Keyboard:
+    //   - Tab: Focus the summary element
+    //   - Enter / Space: Toggle open/close (browser native behavior)
+    //
+    // Accessibility:
+    //   - Native <details> provides implicit disclosure widget semantics
+    //   - Browser automatically manages expanded/collapsed state announcement
+    //
+    // Internationalization:
+    //   - No hardcoded text; all content comes through children
+    //
+    // Claude rules:
+    //   - Compound component — use inside AccordionList
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Do not replace native <details> with custom ARIA widgets
+    //   - The open prop must use $bindable() for two-way binding
+    //
+    // References:
+    //   - HTML details element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        open = $bindable(false),
+        children,
+        ...restProps
+    }: {
+        /** Whether expanded. Bindable. */
+        open?: boolean;
+        /** A <summary> and content elements. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- AccordionListItem.svelte -->
+<details
+    class={`accordion-list-item ${className}`}
+    bind:open
+    {...restProps}
+>
+    {@render children?.()}
+</details>

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

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Whether expanded. Bindable. */
+    open?: boolean;
+    /** A <summary> and content elements. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const AccordionListItem: import("svelte").Component<$$ComponentProps, {}, "open">;
+type AccordionListItem = ReturnType<typeof AccordionListItem>;
+export default AccordionListItem;

package/dist/components/AccordionNav/AccordionNav.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+    // AccordionNav component
+    //
+    // A headless navigation container for an accordion, rendered as a <nav>
+    // element with an accessible label. Serves as the outermost wrapper for
+    // collapsible accordion content. Contains an AccordionList which holds
+    // AccordionListItem children. Commonly used for FAQs, settings panels,
+    // filter groups, and mobile navigation menus.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name via aria-label.
+    //   children — Snippet, required. AccordionList element.
+    //   ...restProps — additional HTML attributes spread onto the <nav>.
+    //
+    // Syntax:
+    //   <AccordionNav label="FAQ">
+    //     <AccordionList>...</AccordionList>
+    //   </AccordionNav>
+    //
+    // Examples:
+    //   <!-- FAQ accordion -->
+    //   <AccordionNav label="Frequently Asked Questions">
+    //     <AccordionList>
+    //       <AccordionListItem>
+    //         <summary>What is this?</summary>
+    //         <p>A design system.</p>
+    //       </AccordionListItem>
+    //     </AccordionList>
+    //   </AccordionNav>
+    //
+    // Keyboard: None — this is a passive container. Keyboard interactions
+    // are handled by AccordionListItem children (Enter/Space to toggle).
+    //
+    // Accessibility:
+    //   - <nav> element provides navigation landmark semantics
+    //   - aria-label provides the accessible name for screen readers
+    //
+    // Internationalization:
+    //   - The label prop is the only user-facing string
+    //   - No hardcoded text; all content comes through props and children
+    //
+    // Claude rules:
+    //   - Compound component — use with AccordionList and AccordionListItem
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //
+    // References:
+    //   - WAI-ARIA Accordion Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/accordion/
+    //   - HTML nav element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        children,
+        ...restProps
+    }: {
+        /** Accessible label. */
+        label: string;
+        /** AccordionList element. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- AccordionNav.svelte -->
+<nav
+    class={`accordion-nav ${className}`}
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</nav>

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

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

package/dist/components/ActionBar/ActionBar.svelte

@@ -0,0 +1,96 @@
+<script lang="ts">
+    // ActionBar component
+    //
+    // A contextual action bar that appears when items are selected, showing
+    // the selection count and bulk action buttons. Renders a `<div>` with
+    // `role="toolbar"`. The selected count label is consumer-formatted for
+    // i18n (e.g., "3 selected"). When both `clearSelectionLabel` and
+    // `onClearSelection` are provided, a clear-selection button is rendered.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   label — string, REQUIRED. aria-label for the toolbar.
+    //   selectedCount — number, REQUIRED. Count of currently selected items.
+    //   selectedCountLabel — string, REQUIRED. Pre-formatted count display.
+    //   clearSelectionLabel — string, optional. Accessible label for clear.
+    //   onClearSelection — () => void, optional. Clear-selection click handler.
+    //   children — Snippet, optional. Action button children.
+    //
+    // Syntax:
+    //   <ActionBar
+    //       label="Bulk actions"
+    //       selectedCount={3}
+    //       selectedCountLabel="3 selected"
+    //       clearSelectionLabel="Clear selection"
+    //       onClearSelection={handleClear}
+    //   >
+    //       <ActionBarButton label="Delete">Delete</ActionBarButton>
+    //   </ActionBar>
+    //
+    // Keyboard:
+    //   - Tab: Move focus through toolbar buttons
+    //
+    // Accessibility:
+    //   - role="toolbar" with aria-label
+    //   - data-selected-count exposes the count for consumer styling
+    //
+    // Internationalization:
+    //   - All user-facing text comes through props
+    //
+    // References:
+    //   - WAI-ARIA Toolbar Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        selectedCount,
+        selectedCountLabel,
+        clearSelectionLabel = undefined,
+        onClearSelection = undefined,
+        children = undefined,
+        ...restProps
+    }: {
+        class?: string;
+        /** Accessible label for the toolbar (REQUIRED) */
+        label: string;
+        /** Count of currently selected items (REQUIRED) */
+        selectedCount: number;
+        /** Pre-formatted display of the count (REQUIRED) */
+        selectedCountLabel: string;
+        /** Accessible label for the clear-selection button */
+        clearSelectionLabel?: string;
+        /** Clear-selection click handler */
+        onClearSelection?: () => void;
+        /** Action button children */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+
+    const showClear = $derived(
+        Boolean(clearSelectionLabel) && typeof onClearSelection === "function",
+    );
+</script>
+
+<!-- ActionBar.svelte -->
+<div
+    class={`action-bar ${className}`}
+    role="toolbar"
+    aria-label={label}
+    data-selected-count={selectedCount}
+    {...restProps}
+>
+    <span class="action-bar-count">{selectedCountLabel}</span>
+    {#if children}
+        {@render children?.()}
+    {/if}
+    {#if showClear}
+        <button
+            class="action-bar-clear"
+            type="button"
+            aria-label={clearSelectionLabel}
+            onclick={onClearSelection}
+        >×</button>
+    {/if}
+</div>