@lilydesignsystem/svelte-headless 0.1.0

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

@@ -0,0 +1,19 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Accessible label (REQUIRED for icon-only buttons) */
+    label: string;
+    /** HTML button type */
+    type?: "button" | "submit" | "reset";
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Toggle button pressed state */
+    pressed?: boolean;
+    /** Click handler */
+    onclick?: (event: MouseEvent) => void;
+    /** Icon content */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const IconButton: import("svelte").Component<$$ComponentProps, {}, "">;
+type IconButton = ReturnType<typeof IconButton>;
+export default IconButton;

package/dist/components/IconList/IconList.svelte

@@ -0,0 +1,56 @@
+<script lang="ts">
+    // IconList component
+    //
+    // A headless `<ul>` that hosts a list of items each with a leading icon.
+    // List semantics come from `<ul>`; an optional `aria-label` names the
+    // list for assistive technology. Children are typically `IconListItem`
+    // components.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   label — string, optional. aria-label naming the list.
+    //   children — Snippet, required. Icon list items.
+    //   ...restProps — additional HTML attributes spread onto the <ul>.
+    //
+    // Syntax:
+    //   <IconList label="Features">…</IconList>
+    //
+    // Accessibility:
+    //   - <ul> conveys list semantics
+    //   - Optional aria-label names the list
+    //
+    // Internationalization:
+    //   - label is consumer-supplied
+    //
+    // Claude rules:
+    //   - Headless: no styles
+    //
+    // References:
+    //   - USWDS Icon list: https://designsystem.digital.gov/components/icon-list/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        label = undefined,
+        children,
+        ...restProps
+    }: {
+        /** Optional CSS class appended to the base class */
+        class?: string;
+        /** Optional aria-label naming the list */
+        label?: string;
+        /** Icon list item children */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- IconList.svelte -->
+<ul
+    class={`icon-list ${className}`}
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</ul>

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

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Optional CSS class appended to the base class */
+    class?: string;
+    /** Optional aria-label naming the list */
+    label?: string;
+    /** Icon list item children */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const IconList: import("svelte").Component<$$ComponentProps, {}, "">;
+type IconList = ReturnType<typeof IconList>;
+export default IconList;

package/dist/components/IconListItem/IconListItem.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+    // IconListItem component
+    //
+    // A headless `<li>` with an optional leading-icon slot and required text
+    // content. The icon snippet renders inside an `aria-hidden="true"` span so
+    // screen readers do not announce decorative glyphs; the textual content
+    // remains the accessible name of the item.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   icon — Snippet, optional. Decorative leading icon.
+    //   children — Snippet, required. Text content.
+    //   ...restProps — additional HTML attributes spread onto the <li>.
+    //
+    // Syntax:
+    //   <IconListItem icon={iconSnippet}>Fast</IconListItem>
+    //
+    // Accessibility:
+    //   - Icon span has aria-hidden="true" (decorative)
+    //   - Text content is the accessible name
+    //
+    // Internationalization:
+    //   - Text comes from children (consumer-supplied)
+    //
+    // Claude rules:
+    //   - Headless: no styles
+    //   - children is REQUIRED
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        icon = undefined,
+        children,
+        ...restProps
+    }: {
+        /** Optional CSS class appended to the base class */
+        class?: string;
+        /** Optional leading icon snippet (decorative) */
+        icon?: Snippet;
+        /** Item text content */
+        children: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- IconListItem.svelte -->
+<li
+    class={`icon-list-item ${className}`}
+    {...restProps}
+>
+    {#if icon}
+        <span class="icon-list-item-icon" aria-hidden="true">
+            {@render icon()}
+        </span>
+    {/if}
+    <span class="icon-list-item-text">
+        {@render children?.()}
+    </span>
+</li>

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

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Optional CSS class appended to the base class */
+    class?: string;
+    /** Optional leading icon snippet (decorative) */
+    icon?: Snippet;
+    /** Item text content */
+    children: Snippet;
+    [key: string]: unknown;
+};
+declare const IconListItem: import("svelte").Component<$$ComponentProps, {}, "">;
+type IconListItem = ReturnType<typeof IconListItem>;
+export default IconListItem;

package/dist/components/Image/Image.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+    // Image component
+    //
+    // An image component that displays visual content with proper accessibility through
+    // required alt text and optional caption support. When a caption is provided, it renders
+    // a <figure> containing the <img> and a <figcaption> for semantic association. Without
+    // a caption, it renders a plain <img> element. Supports native lazy loading.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   src — string, required. The image source URL.
+    //   alt — string, required. Alternative text describing the image for screen readers.
+    //   caption — string, default undefined. When provided, wraps the image in a figure/figcaption.
+    //   loading — "lazy" | "eager", default undefined. Controls native browser loading behavior.
+    //   ...restProps — additional HTML attributes spread onto the root element (img or figure).
+    //
+    // Syntax:
+    //   <Image src="/photo.jpg" alt="Description" />
+    //
+    // Examples:
+    //   <!-- Basic image with alt text -->
+    //   <Image src="/photo.jpg" alt="A sunset over the ocean" />
+    //
+    //   <!-- Image with caption wrapped in figure/figcaption -->
+    //   <Image src="/photo.jpg" alt="A sunset over the ocean" caption="Photo by Jane Doe" />
+    //
+    //   <!-- Lazy-loaded image -->
+    //   <Image src="/large-photo.jpg" alt="Landscape" loading="lazy" />
+    //
+    // Keyboard:
+    //   - None — images are not interactive by default
+    //
+    // Accessibility:
+    //   - alt attribute provides the accessible name for the image (required)
+    //   - <figure> and <figcaption> semantically associate the caption with the image
+    //   - Screen readers announce the alt text when encountering the image
+    //
+    // Internationalization:
+    //   - The alt and caption props allow localized text; no hardcoded user-facing strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - restProps spread onto <img> when no caption, onto <figure> when caption is present
+    //   - alt prop is required to enforce accessibility
+    //
+    // References:
+    //   - WAI Images Tutorial: https://www.w3.org/WAI/tutorials/images/
+    //   - HTML figure element: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure
+
+    let {
+        class: className = "",
+        src,
+        alt,
+        caption = undefined,
+        loading = undefined,
+        ...restProps
+    }: {
+        src: string;
+        alt: string;
+        caption?: string;
+        loading?: "lazy" | "eager";
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- Image.svelte -->
+{#if caption}
+    <figure
+        class={`image ${className}`}
+        {...restProps}
+    >
+        <img
+            {src}
+            {alt}
+            {loading}
+        />
+        <figcaption>{caption}</figcaption>
+    </figure>
+{:else}
+    <img
+        class={`image ${className}`}
+        {src}
+        {alt}
+        {loading}
+        {...restProps}
+    />
+{/if}

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

@@ -0,0 +1,10 @@
+type $$ComponentProps = {
+    src: string;
+    alt: string;
+    caption?: string;
+    loading?: "lazy" | "eager";
+    [key: string]: unknown;
+};
+declare const Image: import("svelte").Component<$$ComponentProps, {}, "">;
+type Image = ReturnType<typeof Image>;
+export default Image;

package/dist/components/ImageCropper/ImageCropper.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+    // ImageCropper component
+    //
+    // A headless container for cropping and resizing an image to a selected region
+    // using mouse, touch, or stylus input to move and resize a crop rectangle.
+    // Renders a <div> with role="application" and an accessible label. Commonly used
+    // in avatar and profile-photo editors, media upload workflows, document scanning,
+    // and content management systems. The consumer provides the actual cropping
+    // implementation (an HTML image with an overlay, a canvas, SVG resize handles,
+    // or a third-party cropping library).
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible description of the image cropper via aria-label.
+    //   children — Snippet, required. The image and crop overlay surface.
+    //   ...restProps — additional HTML attributes spread onto the <div>.
+    //
+    // Syntax:
+    //   <ImageCropper label="Crop your profile photo">
+    //     <img src="/uploads/photo.jpg" alt="Photo to crop" />
+    //   </ImageCropper>
+    //
+    // Examples:
+    //   <!-- Avatar upload flow -->
+    //   <ImageCropper label="Crop your profile photo to a square">
+    //     <img src={previewUrl} alt="Selected photo to crop" />
+    //   </ImageCropper>
+    //
+    //   <!-- Document scan crop region -->
+    //   <ImageCropper label="Adjust the crop region around the document">
+    //     <canvas width="600" height="800"></canvas>
+    //   </ImageCropper>
+    //
+    // Keyboard:
+    //   - None — pointer- and keyboard-based crop interactions are handled by the consumer-provided overlay surface.
+    //
+    // Accessibility:
+    //   - role="application" indicates a complex widget with custom pointer interactions
+    //   - aria-label provides an accessible description of the image cropper purpose
+    //   - Assistive technologies pass keyboard events through to the application
+    //
+    // Internationalization:
+    //   - The label prop externalizes the accessible description for localization
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - No internal cropping logic — consumer provides image/canvas/SVG implementation
+    //   - role="application" is intentional for complex pointer interaction widgets
+    //
+    // References:
+    //   - WAI-ARIA application role: https://www.w3.org/TR/wai-aria-1.2/#application
+    import type { Snippet } from "svelte";
+    let {
+        class: className = "",
+        label,
+        children,
+        ...restProps
+    }: { label: string; children: Snippet; [key: string]: unknown } = $props();
+</script>
+
+<!-- ImageCropper.svelte -->
+<div
+    class={`image-cropper ${className}`}
+    role="application"
+    aria-label={label}
+    {...restProps}
+>
+    {@render children?.()}
+</div>

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

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

package/dist/components/ImageFileInput/ImageFileInput.svelte

@@ -0,0 +1,70 @@
+<script lang="ts">
+    // ImageFileInput component
+    //
+    // An image file input that provides a file upload control pre-configured to accept
+    // image files. Wraps a native <input type="file"> element with accessible labeling
+    // and sensible defaults for image selection. Useful for profile photo uploads, gallery
+    // image selection, document scanning, and any form requiring image file input.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name applied via aria-label.
+    //   accept — string, default "image/*". MIME type filter for the file picker dialog.
+    //   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 element.
+    //
+    // Syntax:
+    //   <ImageFileInput label="Upload profile photo" />
+    //
+    // Examples:
+    //   <!-- Basic image upload -->
+    //   <ImageFileInput label="Upload profile photo" />
+    //
+    //   <!-- Restricted to specific image formats -->
+    //   <ImageFileInput label="Upload document scan" accept="image/png, image/jpeg" required />
+    //
+    // Keyboard:
+    //   - Tab: Focus the file input
+    //   - Enter / Space: Open the file picker dialog (native browser behavior)
+    //
+    // Accessibility:
+    //   - aria-label provides an accessible name for the file input
+    //   - Uses native <input type="file"> which provides built-in keyboard and screen reader support
+    //
+    // Internationalization:
+    //   - The label prop allows localized accessible names; no hardcoded user-facing strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses native <input type="file"> element with accept="image/*" default
+    //   - Consumer can narrow accepted types via the accept prop
+    //
+    // References:
+    //   - MDN Input type="file": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file
+    let {
+        class: className = "",
+        label,
+        accept = "image/*",
+        required = false,
+        disabled = false,
+        ...restProps
+    }: {
+        label: string;
+        accept?: string;
+        required?: boolean;
+        disabled?: boolean;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ImageFileInput.svelte -->
+<input
+    class={`image-file-input ${className}`}
+    type="file"
+    aria-label={label}
+    {accept}
+    {required}
+    {disabled}
+    {...restProps}
+/>

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

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

package/dist/components/ImageInput/ImageInput.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+    // ImageInput component
+    //
+    // A headless image submit button using the native HTML <input type="image">
+    // element. Displays an image that, when clicked within a form, submits the
+    // form along with the click coordinates. This is a graphical alternative to
+    // <input type="submit"> and is commonly used for custom submit buttons,
+    // image maps, or graphical form controls.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   src — string, required. URL of the image to display.
+    //   alt — string, required. Alternative text for accessibility.
+    //   width — number | undefined, default undefined. Image width in pixels.
+    //   height — number | undefined, default undefined. Image height in pixels.
+    //   disabled — boolean, default false. Whether the button is disabled.
+    //   ...restProps — additional HTML attributes spread onto the <input>.
+    //
+    // Syntax:
+    //   <ImageInput src="/submit.png" alt="Submit form" />
+    //
+    // Examples:
+    //   <!-- Image submit with dimensions -->
+    //   <ImageInput src="/icons/go.png" alt="Go" width={32} height={32} />
+    //
+    //   <!-- Conditionally disabled image submit -->
+    //   <ImageInput src="/submit.png" alt="Submit" disabled={!formValid} />
+    //
+    // Keyboard:
+    //   - Enter: activates the image button (native behavior)
+    //   - Space: activates the image button (native behavior)
+    //
+    // Accessibility:
+    //   - The alt attribute provides the accessible name for the image button
+    //   - Native <input type="image"> has an implicit button role
+    //   - No additional ARIA attributes needed beyond native semantics
+    //
+    // Internationalization:
+    //   - The alt prop externalizes the accessible name for translation
+    //   - No hardcoded user-facing strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles -- consumer provides all styling
+    //   - No children snippet -- uses image for visual content
+    //
+    // References:
+    //   - MDN input type="image": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/image
+
+    let {
+        class: className = "",
+        src,
+        alt,
+        width = undefined,
+        height = undefined,
+        disabled = false,
+        ...restProps
+    }: {
+        /** Image URL. */
+        src: string;
+        /** Alternative text. */
+        alt: string;
+        /** Image width in pixels. */
+        width?: number;
+        /** Image height in pixels. */
+        height?: number;
+        /** Whether disabled. */
+        disabled?: boolean;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- ImageInput.svelte -->
+<input
+    class={`image-input ${className}`}
+    type="image"
+    {src}
+    {alt}
+    {width}
+    {height}
+    {disabled}
+    {...restProps}
+/>

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

@@ -0,0 +1,16 @@
+type $$ComponentProps = {
+    /** Image URL. */
+    src: string;
+    /** Alternative text. */
+    alt: string;
+    /** Image width in pixels. */
+    width?: number;
+    /** Image height in pixels. */
+    height?: number;
+    /** Whether disabled. */
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+declare const ImageInput: import("svelte").Component<$$ComponentProps, {}, "">;
+type ImageInput = ReturnType<typeof ImageInput>;
+export default ImageInput;

package/dist/components/InfoState/InfoState.svelte

@@ -0,0 +1,99 @@
+<script lang="ts">
+    // InfoState component
+    //
+    // A headless composition of optional illustration, required title, optional
+    // description, and optional action — useful for empty states, error states,
+    // success states, and informational placeholder views. Renders a `<section>`
+    // with role="status" and a configurable `data-level`.
+    //
+    // Props:
+    //   class — string, optional. CSS class appended to the base class.
+    //   level — "info" | "empty" | "error" | "success", default "info". Sets data-level.
+    //   title — string, REQUIRED. Section heading text.
+    //   description — string, optional. Body text.
+    //   label — string, optional. aria-label override (defaults to title).
+    //   illustration — Snippet, optional. Visual element above title.
+    //   action — Snippet, optional. CTA button(s) below description.
+    //   children — Snippet, optional. Custom default content.
+    //   ...restProps — additional HTML attributes spread onto the <section>.
+    //
+    // Syntax:
+    //   <InfoState level="empty" title="No results" description="Try a different filter." />
+    //
+    // Examples:
+    //   <InfoState level="error" title="Something went wrong" description={msg}>
+    //     {#snippet action()}<button onclick={retry}>Retry</button>{/snippet}
+    //   </InfoState>
+    //
+    // Keyboard:
+    //   - None on the container; any action snippet provides interactivity
+    //
+    // Accessibility:
+    //   - role="status" announces non-disruptive updates
+    //   - aria-label defaults to title text
+    //
+    // Internationalization:
+    //   - title, description, label all come from props
+    //
+    // Claude rules:
+    //   - Headless: no styles
+    //   - level only sets data-level for consumer CSS hooks
+    //
+    // References:
+    //   - MDN <section>: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/section
+    //   - WAI-ARIA role="status": https://www.w3.org/WAI/ARIA/apg/patterns/alert/
+
+    import type { Snippet } from "svelte";
+
+    let {
+        class: className = "",
+        level = "info",
+        title,
+        description = undefined,
+        label = undefined,
+        illustration = undefined,
+        action = undefined,
+        children = undefined,
+        ...restProps
+    }: {
+        /** Level of the info state */
+        level?: "info" | "empty" | "error" | "success";
+        /** Section heading text (required) */
+        title: string;
+        /** Body description */
+        description?: string;
+        /** aria-label override (defaults to title) */
+        label?: string;
+        /** Illustration above title */
+        illustration?: Snippet;
+        /** Action(s) below description */
+        action?: Snippet;
+        /** Custom default content (alternative to title/description/action) */
+        children?: Snippet;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- InfoState.svelte -->
+<section
+    class={`info-state ${className}`}
+    role="status"
+    data-level={level}
+    aria-label={label || title}
+    {...restProps}
+>
+    {#if children}
+        {@render children?.()}
+    {:else}
+        {#if illustration}
+            <div class="info-state-illustration">{@render illustration()}</div>
+        {/if}
+        <h2 class="info-state-title">{title}</h2>
+        {#if description}
+            <p class="info-state-description">{description}</p>
+        {/if}
+        {#if action}
+            <div class="info-state-action">{@render action()}</div>
+        {/if}
+    {/if}
+</section>

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

@@ -0,0 +1,21 @@
+import type { Snippet } from "svelte";
+type $$ComponentProps = {
+    /** Level of the info state */
+    level?: "info" | "empty" | "error" | "success";
+    /** Section heading text (required) */
+    title: string;
+    /** Body description */
+    description?: string;
+    /** aria-label override (defaults to title) */
+    label?: string;
+    /** Illustration above title */
+    illustration?: Snippet;
+    /** Action(s) below description */
+    action?: Snippet;
+    /** Custom default content (alternative to title/description/action) */
+    children?: Snippet;
+    [key: string]: unknown;
+};
+declare const InfoState: import("svelte").Component<$$ComponentProps, {}, "">;
+type InfoState = ReturnType<typeof InfoState>;
+export default InfoState;