@lilydesignsystem/svelte-headless 0.1.0

package/dist/components/Combobox/Combobox.svelte

@@ -0,0 +1,111 @@
+<script lang="ts">
+    // Combobox component
+    //
+    // A headless combobox combining a text input with a dropdown listbox of
+    // suggestions for autocomplete or type-ahead search experiences. Users type into
+    // the input to filter suggestions, then select from matching options in the
+    // dropdown. Commonly used for search fields, address inputs, tag selectors, and
+    // choosing from large option sets.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name via aria-label on both input and listbox.
+    //   value — string, default "". Bindable current text input value.
+    //   open — boolean, default false. Bindable dropdown visibility state.
+    //   children — Snippet, required. Option elements rendered inside the listbox dropdown.
+    //   ...restProps — additional HTML attributes spread onto the wrapper <div>.
+    //
+    // Syntax:
+    //   <Combobox label="Search" bind:value bind:open>
+    //     <div role="option" tabindex="-1">Option 1</div>
+    //   </Combobox>
+    //
+    // Examples:
+    //   <!-- Combobox with filtered options -->
+    //   <Combobox label="Select a fruit" bind:value bind:open>
+    //     {#each filtered as option}
+    //       <div role="option" tabindex="-1" onclick={() => { value = option; open = false; }}>
+    //         {option}
+    //       </div>
+    //     {/each}
+    //   </Combobox>
+    //
+    // Keyboard:
+    //   - Escape: Close the dropdown listbox
+    //
+    // Accessibility:
+    //   - role="combobox" on the input identifies it as a combobox widget
+    //   - aria-expanded reflects the open state for screen readers
+    //   - aria-controls links the input to the associated listbox by ID
+    //   - aria-autocomplete="list" indicates suggestions are provided via a list
+    //   - role="listbox" on the dropdown identifies selectable options
+    //
+    // Internationalization:
+    //   - The label prop provides the accessible name; no hardcoded strings
+    //   - All option content is provided by consumers through the children snippet
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Generates a unique listboxId for the aria-controls relationship
+    //   - Consumer is responsible for filtering options based on value
+    //
+    // References:
+    //   - WAI-ARIA Combobox Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+
+    import type { Snippet } from "svelte";
+
+    const uid = $props.id();
+    const listboxId = `combobox-listbox-${uid}`;
+
+    let {
+        class: className = "",
+        label,
+        value = $bindable(""),
+        open = $bindable(false),
+        children,
+        ...restProps
+    }: {
+        /** Accessible label. */
+        label: string;
+        /** Current input value. Bindable. */
+        value?: string;
+        /** Whether dropdown is open. Bindable. */
+        open?: boolean;
+        /** Dropdown option elements. */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+
+    function onkeydown(event: KeyboardEvent) {
+        if (event.key === "Escape") {
+            event.preventDefault();
+            open = false;
+        }
+    }
+</script>
+
+<!-- Combobox.svelte -->
+<div
+    class={`combobox ${className}`}
+    {...restProps}
+>
+    <input
+        type="text"
+        role="combobox"
+        aria-label={label}
+        aria-expanded={open}
+        aria-controls={listboxId}
+        aria-autocomplete="list"
+        bind:value
+        {onkeydown}
+    />
+    {#if open}
+        <div
+            role="listbox"
+            id={listboxId}
+            aria-label={label}
+        >
+            {@render children?.()}
+        </div>
+    {/if}
+</div>

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

@@ -0,0 +1,15 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible label. */
+    label: string;
+    /** Current input value. Bindable. */
+    value?: string;
+    /** Whether dropdown is open. Bindable. */
+    open?: boolean;
+    /** Dropdown option elements. */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const Combobox: import("svelte").Component<$$ComponentProps, {}, "open" | "value">;
+type Combobox = ReturnType<typeof Combobox>;
+export default Combobox;

package/dist/components/Command/Command.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+    // Command component
+    //
+    // A headless command palette providing a searchable list of actions or items.
+    // It renders a search region containing a text input and a listbox for results.
+    // The search value is bindable, allowing consumers to implement their own filtering
+    // logic and dynamically update the listbox content. Commonly used for Ctrl+K quick-access
+    // command palettes, searchable menus, and action launchers.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name for the search region and input.
+    //   placeholder — string, default undefined. Placeholder text for the search input.
+    //   value — string, default "". Current search text; bindable via bind:value.
+    //   children — Snippet, required. Listbox content, typically option or command items.
+    //   ...restProps — additional HTML attributes spread onto the outer <div>.
+    //
+    // Syntax:
+    //   <Command label="Command palette" placeholder="Search..." bind:value={query}>
+    //     <div role="option">Action</div>
+    //   </Command>
+    //
+    // Examples:
+    //   <!-- Command palette with filtered commands -->
+    //   <Command label="Command palette" placeholder="Search commands..." bind:value={query}>
+    //     {#each filteredCommands as cmd}
+    //       <div role="option">{cmd.name}</div>
+    //     {/each}
+    //   </Command>
+    //
+    // Keyboard:
+    //   - Tab: Move focus into and out of the search input
+    //   - Additional keyboard navigation within the listbox should be implemented by the consumer
+    //
+    // Accessibility:
+    //   - role="search" identifies the outer container as a search landmark
+    //   - aria-label provides accessible names for the search region, input, and listbox
+    //   - role="listbox" identifies the results container for selectable options
+    //   - autocomplete="off" prevents browser autocomplete from interfering
+    //
+    // Internationalization:
+    //   - The label and placeholder props provide all text; no hardcoded strings
+    //   - All command content is provided by consumers through the children snippet
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Consumer is responsible for filtering and rendering listbox content
+    //   - Consumer should implement arrow key navigation within the listbox
+    //
+    // References:
+    //   - WAI-ARIA Listbox Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/listbox/
+    //   - WAI-ARIA Combobox Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label,
+        placeholder = undefined,
+        value = $bindable(""),
+        children,
+        ...restProps
+    }: {
+        label: string;
+        placeholder?: string;
+        value?: string;
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- Command.svelte -->
+<div
+    class={`command ${className}`}
+    role="search"
+    aria-label={label}
+    {...restProps}
+>
+    <input
+        type="search"
+        bind:value
+        aria-label={label}
+        {placeholder}
+        autocomplete="off"
+    />
+    <div
+        role="listbox"
+        aria-label={label}
+    >
+        {@render children?.()}
+    </div>
+</div>

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

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

package/dist/components/Comment/Comment.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>
+
+<!-- Comment.svelte -->
+<div class={`comment ${className}`} aria-label={label} {...restProps}>
+    {@render children?.()}
+</div>

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

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

package/dist/components/Container/Container.svelte

@@ -0,0 +1,23 @@
+<script lang="ts">
+    // Container component
+    // A generic block-level content container.
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: {
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- Container.svelte -->
+<div
+    class={`container ${className}`}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

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

package/dist/components/ContainerWithFixedWidth/ContainerWithFixedWidth.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+    // ContainerWithFixedWidth component
+    //
+    // A headless centered content wrapper with a fixed max-width breakpoint. Renders
+    // a `<div>` with inline `max-width` and `margin-inline: auto` so the container
+    // centers within its parent. Consumer CSS may further refine spacing or breakpoints.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   maxWidth — string, default "1200px". Max width CSS value.
+    //   children — Snippet, required. The content to wrap.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <ContainerWithFixedWidth maxWidth="960px">…</ContainerWithFixedWidth>
+    //
+    // Examples:
+    //   <ContainerWithFixedWidth maxWidth="80ch">
+    //     <article>…</article>
+    //   </ContainerWithFixedWidth>
+    //
+    // Keyboard:
+    //   - None (purely structural)
+    //
+    // Accessibility:
+    //   - No ARIA role (presentational layout container)
+    //
+    // Internationalization:
+    //   - All text comes through children; no hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: only inline styles are `max-width` and `margin-inline` (functional layout)
+    //
+    // References:
+    //   - CSS Container Queries: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        maxWidth = "1200px",
+        children,
+        ...restProps
+    }: {
+        /** Max width CSS value */
+        maxWidth?: string;
+        /** Container content */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ContainerWithFixedWidth.svelte -->
+<div
+    class={`container-with-fixed-width ${className}`}
+    data-max-width={maxWidth}
+    style={`max-width: ${maxWidth}; margin-inline: auto;`}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Max width CSS value */
+    maxWidth?: string;
+    /** Container content */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const ContainerWithFixedWidth: import("svelte").Component<$$ComponentProps, {}, "">;
+type ContainerWithFixedWidth = ReturnType<typeof ContainerWithFixedWidth>;
+export default ContainerWithFixedWidth;

package/dist/components/ContainerWithFluidWidth/ContainerWithFluidWidth.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+    // ContainerWithFluidWidth component
+    //
+    // A headless full-width content wrapper with horizontal padding. Renders a
+    // `<div>` that spans the full width of its parent and applies a configurable
+    // `padding-inline` so content does not touch viewport edges.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   paddingInline — string, default "1rem". Horizontal padding CSS value.
+    //   children — Snippet, required. The content to wrap.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <ContainerWithFluidWidth paddingInline="2rem">…</ContainerWithFluidWidth>
+    //
+    // Examples:
+    //   <ContainerWithFluidWidth paddingInline="clamp(1rem, 4vw, 3rem)">
+    //     <section>…</section>
+    //   </ContainerWithFluidWidth>
+    //
+    // Keyboard:
+    //   - None (purely structural)
+    //
+    // Accessibility:
+    //   - No ARIA role (presentational layout container)
+    //
+    // Internationalization:
+    //   - All text comes through children; no hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: only inline styles are `width: 100%` and `padding-inline` (functional layout)
+    //
+    // References:
+    //   - MDN padding-inline: https://developer.mozilla.org/en-US/docs/Web/CSS/padding-inline
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        paddingInline = "1rem",
+        children,
+        ...restProps
+    }: {
+        /** Horizontal padding CSS value */
+        paddingInline?: string;
+        /** Container content */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ContainerWithFluidWidth.svelte -->
+<div
+    class={`container-with-fluid-width ${className}`}
+    data-padding-inline={paddingInline}
+    style={`width: 100%; padding-inline: ${paddingInline};`}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Horizontal padding CSS value */
+    paddingInline?: string;
+    /** Container content */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const ContainerWithFluidWidth: import("svelte").Component<$$ComponentProps, {}, "">;
+type ContainerWithFluidWidth = ReturnType<typeof ContainerWithFluidWidth>;
+export default ContainerWithFluidWidth;

package/dist/components/ContentBlock/ContentBlock.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    let {
+        class: className = "",
+        width = "normal",
+        children,
+        ...restProps
+    }: {
+        width?: "narrower" | "narrow" | "normal" | "wide" | "wider" | "widest" | "fluid";
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ContentBlock.svelte -->
+<div
+    class={`content-block ${className}`}
+    data-width={width}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,9 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    width?: "narrower" | "narrow" | "normal" | "wide" | "wider" | "widest" | "fluid";
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const ContentBlock: import("svelte").Component<$$ComponentProps, {}, "">;
+type ContentBlock = ReturnType<typeof ContentBlock>;
+export default ContentBlock;

package/dist/components/ContentsLink/ContentsLink.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>
+
+<!-- ContentsLink.svelte -->
+<div class={`contents-link ${className}`} aria-label={label} {...restProps}>
+    {@render children?.()}
+</div>

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

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

package/dist/components/ContentsList/ContentsList.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+    // ContentsList component
+    //
+    // A headless ordered list for a table of contents. Renders a semantic <ol>
+    // element containing ContentsListItem children. Designed to be placed inside
+    // a ContentsNav component. The ordered list conveys the sequential nature of
+    // page sections to assistive technology.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   children — Snippet, required. ContentsListItem components or <li> elements.
+    //   ...restProps — additional HTML attributes spread onto the <ol>.
+    //
+    // Syntax:
+    //   <ContentsList>
+    //     <ContentsListItem><a href="#section">Section</a></ContentsListItem>
+    //   </ContentsList>
+    //
+    // Examples:
+    //   <!-- Contents list inside a navigation landmark -->
+    //   <ContentsNav label="On this page">
+    //     <ContentsList>
+    //       <ContentsListItem><a href="#introduction">Introduction</a></ContentsListItem>
+    //       <ContentsListItem><a href="#usage">Usage</a></ContentsListItem>
+    //     </ContentsList>
+    //   </ContentsNav>
+    //
+    // Keyboard:
+    //   - None — passive list container; keyboard navigation handled by links within items
+    //
+    // Accessibility:
+    //   - <ol> provides implicit list role conveying sequential section order
+    //
+    // Internationalization:
+    //   - All content is provided by consumers through children; no hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Compound component: used inside ContentsNav, contains ContentsListItem children
+    //
+    // References:
+    //   - MDN ol element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: { children: Snippet; [key: string]: unknown } = $props();
+</script>
+
+<!-- ContentsList.svelte -->
+<ol
+    class={`contents-list ${className}`}
+    {...restProps}
+>
+    {@render children?.()}
+</ol>

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

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

package/dist/components/ContentsListItem/ContentsListItem.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+    // ContentsListItem component
+    //
+    // A headless list item for use within a table of contents or navigation list.
+    // Renders a semantic <li> element that wraps consumer-provided content, typically
+    // an anchor link to a page section. Supports nesting for hierarchical
+    // document structures by placing a `<ol>` inside. Used as a child of
+    // ContentsList or any ordered/ordered list in a navigation context.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   children — Snippet, required. List item content (typically a link or nested list).
+    //   ...restProps — additional HTML attributes spread onto the <li>.
+    //
+    // Syntax:
+    //   <ContentsListItem><a href="#section">Section</a></ContentsListItem>
+    //
+    // Examples:
+    //   <!-- Nested contents list items for subsections -->
+    //   <ContentsListItem>
+    //     <a href="#section-3">Results</a>
+    //     <ul>
+    //       <ContentsListItem><a href="#section-3a">Data</a></ContentsListItem>
+    //       <ContentsListItem><a href="#section-3b">Analysis</a></ContentsListItem>
+    //     </ul>
+    //   </ContentsListItem>
+    //
+    // Keyboard:
+    //   - None — keyboard interaction is handled by contained links or the parent list
+    //
+    // Accessibility:
+    //   - Semantic <li> provides implicit listitem role
+    //   - Should be placed within a <ul> or <ol> parent for valid HTML structure
+    //   - Supports aria-current="page" or aria-current="true" on the <li> for current page indication
+    //
+    // Internationalization:
+    //   - All content is provided through the children snippet; no hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Compound component: used as a child within ContentsList
+    //
+    // References:
+    //   - WAI-ARIA Menu Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/menu/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        children,
+        ...restProps
+    }: {
+        /** List item content (typically a link or text) */
+        children: Snippet;
+        /** Additional HTML attributes */
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ContentsListItem.svelte -->
+<li class={`contents-list-item ${className}`} {...restProps}>
+    {@render children?.()}
+</li>

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

@@ -0,0 +1,10 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** List item content (typically a link or text) */
+    children: Snippet;
+    /** Additional HTML attributes */
+    [key: string]: unknown;
+};
+declare const ContentsListItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type ContentsListItem = ReturnType<typeof ContentsListItem>;
+export default ContentsListItem;