@lilydesignsystem/svelte-headless 0.1.0

package/dist/components/FileUpload/FileUpload.svelte

@@ -0,0 +1,115 @@
+<script lang="ts">
+    // FileUpload component
+    //
+    // A button-triggered file picker for uploading files. Combines a hidden
+    // <input type="file"> with a visible button and a live status region that
+    // announces how many files have been selected. Useful for document uploads,
+    // image uploads, and any form that accepts file attachments.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   label — string, required. Accessible name for the upload button; also displayed as button text.
+    //   accept — string, default undefined. Accepted file types (e.g., ".pdf", "image/*").
+    //   multiple — boolean, default false. Whether to allow selecting multiple files.
+    //   disabled — boolean, default false. Whether the button is disabled.
+    //   onchange — (files: FileList | null) => void, default undefined. Callback when files are selected.
+    //   ...restProps — additional HTML attributes spread onto the outer <div>.
+    //
+    // Syntax:
+    //   <FileUpload label="Upload files" accept=".pdf" onchange={handleFiles} />
+    //
+    // Examples:
+    //   <!-- Basic file upload -->
+    //   <FileUpload label="Upload files" accept=".pdf" onchange={handleFiles} />
+    //
+    //   <!-- Multiple image upload -->
+    //   <FileUpload label="Upload images" accept="image/*" multiple onchange={handleImages} />
+    //
+    // Keyboard:
+    //   - Tab: focus the upload button
+    //   - Enter/Space: activate the file picker dialog (native button behavior)
+    //
+    // Accessibility:
+    //   - aria-label on the button provides the accessible name
+    //   - aria-live="polite" on the status span announces file count changes
+    //   - data-file-count attribute for consumer CSS or testing
+    //   - Hidden file input is triggered via button click
+    //
+    // Internationalization:
+    //   - The label prop accepts any string; consumers provide localized text
+    //   - Status text "file"/"files" is hardcoded; override via consumer if needed
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses type="button" on trigger to prevent form submission
+    //   - Tracks file count via $state() for the live status region
+    //
+    // References:
+    //   - MDN input type="file": https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file
+
+    let {
+        class: className = "",
+        label,
+        accept = undefined,
+        multiple = false,
+        disabled = false,
+        onchange = undefined,
+        ...restProps
+    }: {
+        /** Accessible label for the button. */
+        label: string;
+        /** Accepted file types. */
+        accept?: string;
+        /** Allow multiple files. */
+        multiple?: boolean;
+        /** Whether disabled. */
+        disabled?: boolean;
+        /** Callback with selected files. */
+        onchange?: (files: FileList | null) => void;
+        [key: string]: unknown;
+    } = $props();
+
+    let inputRef: HTMLInputElement | undefined = $state(undefined);
+    let fileCount = $state(0);
+
+    function handleClick() {
+        inputRef?.click();
+    }
+
+    function handleChange(event: Event) {
+        const input = event.target as HTMLInputElement;
+        fileCount = input.files?.length ?? 0;
+        onchange?.(input.files);
+    }
+</script>
+
+<!-- FileUpload.svelte -->
+<div
+    class={`file-upload ${className}`}
+    {...restProps}
+>
+    <button
+        type="button"
+        aria-label={label}
+        {disabled}
+        onclick={handleClick}
+    >
+        {label}
+    </button>
+    <input
+        bind:this={inputRef}
+        type="file"
+        {accept}
+        {multiple}
+        hidden
+        onchange={handleChange}
+    />
+    <span
+        aria-live="polite"
+        data-file-count={fileCount}
+    >
+        {#if fileCount > 0}
+            {fileCount} {fileCount === 1 ? "file" : "files"} selected
+        {/if}
+    </span>
+</div>

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

@@ -0,0 +1,16 @@
+type $$ComponentProps = {
+    /** Accessible label for the button. */
+    label: string;
+    /** Accepted file types. */
+    accept?: string;
+    /** Allow multiple files. */
+    multiple?: boolean;
+    /** Whether disabled. */
+    disabled?: boolean;
+    /** Callback with selected files. */
+    onchange?: (files: FileList | null) => void;
+    [key: string]: unknown;
+};
+declare const FileUpload: import("svelte").Component<$$ComponentProps, {}, "">;
+type FileUpload = ReturnType<typeof FileUpload>;
+export default FileUpload;

package/dist/components/FiveFaceRatingPicker/FiveFaceRatingPicker.svelte

@@ -0,0 +1,96 @@
+<script lang="ts">
+    // FiveFaceRatingPicker component
+    //
+    // A five-face rating input that lets users select a satisfaction level from 1 to 5
+    // using labeled radio buttons representing faces from "Very bad" to "Very good".
+    // Commonly used in satisfaction surveys, feedback forms, and experience ratings
+    // where face-based labels are more intuitive than numeric scales.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   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.
+    //   disabled — boolean, default false. Whether the entire group is disabled.
+    //   ...restProps — additional HTML attributes spread onto the fieldset.
+    //
+    // Syntax:
+    //   <FiveFaceRatingPicker label="How was your experience?" bind:value />
+    //
+    // Examples:
+    //   <!-- Basic face rating with two-way binding -->
+    //   <FiveFaceRatingPicker label="How was your experience?" bind:value={rating} />
+    //
+    //   <!-- Custom face labels -->
+    //   <FiveFaceRatingPicker label="Rate service" bind:value labels={["Terrible", "Poor", "Fair", "Great", "Excellent"]} />
+    //
+    // Keyboard:
+    //   - Tab: Focus the selected radio (or first if none selected)
+    //   - ArrowDown / ArrowRight: Move to next radio button
+    //   - ArrowUp / ArrowLeft: Move to previous radio button
+    //   - Space: Select the focused radio button
+    //
+    // Accessibility:
+    //   - role="radiogroup" on the fieldset identifies the group as a set of radio buttons
+    //   - aria-label provides an accessible name for the entire rating group
+    //   - Each radio button has a visible text label for screen reader announcement
+    //
+    // Internationalization:
+    //   - All text content comes through the labels prop; no hardcoded user-facing strings
+    //   - The label prop allows localized accessible names
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses native radio buttons for built-in keyboard and accessibility behavior
+    //   - Value 0 means no selection; valid ratings are 1-5
+    //
+    // References:
+    //   - WAI-ARIA Radio Group Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton/
+
+    let {
+        class: className = "",
+        label,
+        value = $bindable(0),
+        name = "face-rating",
+        labels = ["Very bad", "Bad", "Okay", "Good", "Very good"],
+        disabled = false,
+        ...restProps
+    }: {
+        /** Accessible name for the rating group via aria-label. */
+        label: string;
+        /** Current rating (1-5, 0 = none). Bindable via bind:value. */
+        value?: number;
+        /** Radio group name for form submission. */
+        name?: string;
+        /** Labels for each face (array of 5 strings). */
+        labels?: string[];
+        /** Whether the entire group is disabled. */
+        disabled?: boolean;
+        [key: string]: unknown;
+    } = $props();
+
+    const faces = [1, 2, 3, 4, 5];
+</script>
+
+<!-- FiveFaceRatingPicker.svelte -->
+<fieldset
+    class={`five-face-rating-picker ${className}`}
+    role="radiogroup"
+    aria-label={label}
+    {disabled}
+    {...restProps}
+>
+    {#each faces as face, i}
+        <label>
+            <input
+                type="radio"
+                {name}
+                value={face}
+                checked={value === face}
+                onchange={() => (value = face)}
+            />
+            {labels[i]}
+        </label>
+    {/each}
+</fieldset>

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

@@ -0,0 +1,16 @@
+type $$ComponentProps = {
+    /** Accessible name for the rating group via aria-label. */
+    label: string;
+    /** Current rating (1-5, 0 = none). Bindable via bind:value. */
+    value?: number;
+    /** Radio group name for form submission. */
+    name?: string;
+    /** Labels for each face (array of 5 strings). */
+    labels?: string[];
+    /** Whether the entire group is disabled. */
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+declare const FiveFaceRatingPicker: import("svelte").Component<$$ComponentProps, {}, "value">;
+type FiveFaceRatingPicker = ReturnType<typeof FiveFaceRatingPicker>;
+export default FiveFaceRatingPicker;

package/dist/components/FiveFaceRatingPickerButton/FiveFaceRatingPickerButton.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+    // FiveFaceRatingPickerButton component
+    //
+    // A headless button representing one face in a five-face rating picker. Renders
+    // a <button> with aria-pressed to indicate the selected state and data-value for
+    // consumer CSS targeting. Each button represents a satisfaction level (1-5) with
+    // a descriptive label (e.g. "Very bad", "Good"). Commonly used in satisfaction
+    // surveys, feedback forms, and experience ratings.
+    //
+    // Props:
+    //   value — number, required. The rating value (1-5).
+    //   label — string, required. Accessible name for the button (e.g. "Very bad", "Good").
+    //   selected — boolean, default false. Whether this face is currently selected.
+    //   disabled — boolean, default false. Whether the button is disabled.
+    //   onclick — (event: MouseEvent) => void, optional. Click handler.
+    //   ...restProps — additional HTML attributes spread onto the <button>.
+    //
+    // Syntax:
+    //   <FiveFaceRatingPickerButton value={3} label="Okay" onclick={handleSelect} />
+    //
+    // Examples:
+    //   <!-- Selected face button -->
+    //   <FiveFaceRatingPickerButton value={4} label="Good" selected={true} onclick={handleSelect} />
+    //   <!-- Disabled face button -->
+    //   <FiveFaceRatingPickerButton value={1} label="Very bad" disabled={true} />
+    //
+    // Keyboard:
+    //   - Tab: Move focus to the button
+    //   - Enter: Activate the button (native button behavior)
+    //   - Space: Activate the button (native button behavior)
+    //
+    // Accessibility:
+    //   - aria-label provides an accessible name describing the face level
+    //   - aria-pressed indicates whether the face is currently selected
+    //   - data-value exposes the rating value for consumer CSS selectors
+    //
+    // Internationalization:
+    //   - The label prop provides the accessible name; no hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Compound component: used as a child within FiveFaceRatingPicker
+    //   - Consumer can use [data-value] CSS selectors for value-based styling
+    //
+    // References:
+    //   - WAI-ARIA Button Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+
+    let {
+        class: className = "",
+        value,
+        label,
+        selected = false,
+        disabled = false,
+        onclick = undefined,
+        ...restProps
+    }: {
+        /** The rating value (1-5). */
+        value: number;
+        /** Accessible name for the button (e.g. "Very bad", "Good"). */
+        label: string;
+        /** Whether this face is currently selected. */
+        selected?: boolean;
+        /** Whether the button is disabled. */
+        disabled?: boolean;
+        /** Click handler. */
+        onclick?: (event: MouseEvent) => void;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- FiveFaceRatingPickerButton.svelte -->
+<button
+    class={`five-face-rating-picker-button ${className}`}
+    type="button"
+    aria-label={label}
+    aria-pressed={selected}
+    {disabled}
+    data-value={value}
+    {onclick}
+    {...restProps}
+>{label}</button>

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

@@ -0,0 +1,16 @@
+type $$ComponentProps = {
+    /** The rating value (1-5). */
+    value: number;
+    /** Accessible name for the button (e.g. "Very bad", "Good"). */
+    label: string;
+    /** Whether this face is currently selected. */
+    selected?: boolean;
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+    /** Click handler. */
+    onclick?: (event: MouseEvent) => void;
+    [key: string]: unknown;
+};
+declare const FiveFaceRatingPickerButton: import("svelte").Component<$$ComponentProps, {}, "">;
+type FiveFaceRatingPickerButton = ReturnType<typeof FiveFaceRatingPickerButton>;
+export default FiveFaceRatingPickerButton;

package/dist/components/FiveFaceRatingView/FiveFaceRatingView.svelte

@@ -0,0 +1,73 @@
+<script lang="ts">
+    // FiveFaceRatingView component
+    //
+    // A read-only five-face rating display that shows a text label corresponding to a
+    // rating value from 1 to 5. This is the display-only companion to FiveFaceRatingPicker,
+    // used for showing previously submitted ratings in summaries, review lists, or
+    // dashboard displays. Renders a span with role="img" and the face label text.
+    //
+    // Props:
+    //   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.
+    //   ...restProps — additional HTML attributes spread onto the span.
+    //
+    // Syntax:
+    //   <FiveFaceRatingView value={4} label="Good rating" />
+    //
+    // Examples:
+    //   <!-- Display a submitted face rating -->
+    //   <FiveFaceRatingView value={3} label="Okay rating" />
+    //
+    //   <!-- Custom face labels -->
+    //   <FiveFaceRatingView value={5} label="Excellent" labels={["Terrible", "Poor", "Fair", "Great", "Excellent"]} />
+    //
+    // Keyboard:
+    //   - None — this is a passive, read-only display element
+    //
+    // Accessibility:
+    //   - role="img" indicates the span represents a visual/graphic element (the face rating)
+    //   - aria-label provides the full rating description for screen readers
+    //   - data-value attribute exposes the numeric value for consumer CSS or testing
+    //
+    // Internationalization:
+    //   - All text content comes through the labels and label props; no hardcoded user-facing strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses $derived() to look up the face label from the labels array based on value
+    //   - Companion to FiveFaceRatingPicker for the Input/View pattern
+    //
+    // References:
+    //   - WAI-ARIA img role: https://www.w3.org/WAI/ARIA/apd/roles/img/
+
+    let {
+        class: className = "",
+        value,
+        label,
+        labels = ["Very bad", "Bad", "Okay", "Good", "Very good"],
+        ...restProps
+    }: {
+        /** Rating value (1-5). */
+        value: number;
+        /** Accessible description. */
+        label: string;
+        /** Labels for each face. */
+        labels?: string[];
+        [key: string]: unknown;
+    } = $props();
+
+    let faceLabel = $derived(labels[value - 1] ?? "");
+</script>
+
+<!-- FiveFaceRatingView.svelte -->
+<span
+    class={`five-face-rating-view ${className}`}
+    role="img"
+    aria-label={label}
+    data-value={value}
+    {...restProps}
+>
+    {faceLabel}
+</span>

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

@@ -0,0 +1,12 @@
+type $$ComponentProps = {
+    /** Rating value (1-5). */
+    value: number;
+    /** Accessible description. */
+    label: string;
+    /** Labels for each face. */
+    labels?: string[];
+    [key: string]: unknown;
+};
+declare const FiveFaceRatingView: import("svelte").Component<$$ComponentProps, {}, "">;
+type FiveFaceRatingView = ReturnType<typeof FiveFaceRatingView>;
+export default FiveFaceRatingView;

package/dist/components/FiveStarRatingPicker/FiveStarRatingPicker.svelte

@@ -0,0 +1,93 @@
+<script lang="ts">
+    // FiveStarRatingPicker component
+    //
+    // A five-star rating input that lets users select a rating from 1 to 5 stars using
+    // radio buttons. This is one of the most common rating patterns on the web, used for
+    // product reviews, content ratings, and feedback forms. Each radio button is labeled
+    // with "N star" or "N stars" for clear screen reader communication.
+    //
+    // Props:
+    //   className — string, optional. CSS class name.
+    //   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 "rating". Radio group name for form submission.
+    //   disabled — boolean, default false. Whether the entire group is disabled.
+    //   ...restProps — additional HTML attributes spread onto the fieldset.
+    //
+    // Syntax:
+    //   <FiveStarRatingPicker label="Rate this" bind:value />
+    //
+    // Examples:
+    //   <!-- Basic star rating with two-way binding -->
+    //   <FiveStarRatingPicker label="Rate this product" bind:value={rating} />
+    //
+    //   <!-- Disabled star rating -->
+    //   <FiveStarRatingPicker label="Your rating" bind:value disabled />
+    //
+    // Keyboard:
+    //   - Tab: Focus the selected radio (or first if none selected)
+    //   - ArrowDown / ArrowRight: Move to next radio button
+    //   - ArrowUp / ArrowLeft: Move to previous radio button
+    //   - Space: Select the focused radio button
+    //
+    // Accessibility:
+    //   - role="radiogroup" on the fieldset identifies the group as a set of radio buttons
+    //   - aria-label provides an accessible name for the entire rating group
+    //   - Each radio label reads "1 star", "2 stars", etc. for screen reader clarity
+    //
+    // Internationalization:
+    //   - The label prop allows localized accessible names
+    //   - Star labels ("N star"/"N stars") are in the template; consumer can override via restProps
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Uses native radio buttons for built-in keyboard and accessibility behavior
+    //   - Value 0 means no selection; valid ratings are 1-5
+    //
+    // References:
+    //   - WAI-ARIA Radio Group Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/radiobutton/
+
+    let {
+        class: className = "",
+        label,
+        value = $bindable(0),
+        name = "rating",
+        disabled = false,
+        ...restProps
+    }: {
+        /** Accessible name for the rating group via aria-label. */
+        label: string;
+        /** Current rating (1-5, 0 = none). Bindable via bind:value. */
+        value?: number;
+        /** Radio group name for form submission. */
+        name?: string;
+        /** Whether the entire group is disabled. */
+        disabled?: boolean;
+        [key: string]: unknown;
+    } = $props();
+
+    const stars = [1, 2, 3, 4, 5];
+</script>
+
+<!-- FiveStarRatingPicker.svelte -->
+<fieldset
+    class={`five-star-rating-picker ${className}`}
+    role="radiogroup"
+    aria-label={label}
+    {disabled}
+    {...restProps}
+>
+    {#each stars as star}
+        <label>
+            <input
+                type="radio"
+                {name}
+                value={star}
+                checked={value === star}
+                onchange={() => (value = star)}
+            />
+            {star}
+            {star === 1 ? "star" : "stars"}
+        </label>
+    {/each}
+</fieldset>

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

@@ -0,0 +1,14 @@
+type $$ComponentProps = {
+    /** Accessible name for the rating group via aria-label. */
+    label: string;
+    /** Current rating (1-5, 0 = none). Bindable via bind:value. */
+    value?: number;
+    /** Radio group name for form submission. */
+    name?: string;
+    /** Whether the entire group is disabled. */
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+declare const FiveStarRatingPicker: import("svelte").Component<$$ComponentProps, {}, "value">;
+type FiveStarRatingPicker = ReturnType<typeof FiveStarRatingPicker>;
+export default FiveStarRatingPicker;

package/dist/components/FiveStarRatingPickerButton/FiveStarRatingPickerButton.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+    // FiveStarRatingPickerButton component
+    //
+    // A headless button representing one star in a five-star rating picker. Renders
+    // a <button> with aria-pressed to indicate the selected state and data-value for
+    // consumer CSS targeting. Each button represents a rating level (1-5) with a
+    // descriptive label (e.g. "1 star", "3 stars"). Commonly used in product reviews,
+    // content ratings, and feedback forms.
+    //
+    // Props:
+    //   value — number, required. The rating value (1-5).
+    //   label — string, required. Accessible name for the button (e.g. "1 star", "3 stars").
+    //   selected — boolean, default false. Whether this star is currently selected.
+    //   disabled — boolean, default false. Whether the button is disabled.
+    //   onclick — (event: MouseEvent) => void, optional. Click handler.
+    //   ...restProps — additional HTML attributes spread onto the <button>.
+    //
+    // Syntax:
+    //   <FiveStarRatingPickerButton value={3} label="3 stars" onclick={handleSelect} />
+    //
+    // Examples:
+    //   <!-- Selected star button -->
+    //   <FiveStarRatingPickerButton value={4} label="4 stars" selected={true} onclick={handleSelect} />
+    //   <!-- Disabled star button -->
+    //   <FiveStarRatingPickerButton value={1} label="1 star" disabled={true} />
+    //
+    // Keyboard:
+    //   - Tab: Move focus to the button
+    //   - Enter: Activate the button (native button behavior)
+    //   - Space: Activate the button (native button behavior)
+    //
+    // Accessibility:
+    //   - aria-label provides an accessible name describing the star level
+    //   - aria-pressed indicates whether the star is currently selected
+    //   - data-value exposes the rating value for consumer CSS selectors
+    //
+    // Internationalization:
+    //   - The label prop provides the accessible name; no hardcoded strings
+    //
+    // Claude rules:
+    //   - Headless: no CSS, no styles — consumer provides all styling
+    //   - Compound component: used as a child within FiveStarRatingPicker
+    //   - Consumer can use [data-value] CSS selectors for value-based styling
+    //
+    // References:
+    //   - WAI-ARIA Button Pattern: https://www.w3.org/WAI/ARIA/apg/patterns/button/
+
+    let {
+        class: className = "",
+        value,
+        label,
+        selected = false,
+        disabled = false,
+        onclick = undefined,
+        ...restProps
+    }: {
+        /** The rating value (1-5). */
+        value: number;
+        /** Accessible name for the button (e.g. "1 star", "3 stars"). */
+        label: string;
+        /** Whether this star is currently selected. */
+        selected?: boolean;
+        /** Whether the button is disabled. */
+        disabled?: boolean;
+        /** Click handler. */
+        onclick?: (event: MouseEvent) => void;
+        [key: string]: unknown;
+    } = $props();
+</script>
+
+<!-- FiveStarRatingPickerButton.svelte -->
+<button
+    class={`five-star-rating-picker-button ${className}`}
+    type="button"
+    aria-label={label}
+    aria-pressed={selected}
+    {disabled}
+    data-value={value}
+    {onclick}
+    {...restProps}
+>{label}</button>

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

@@ -0,0 +1,16 @@
+type $$ComponentProps = {
+    /** The rating value (1-5). */
+    value: number;
+    /** Accessible name for the button (e.g. "1 star", "3 stars"). */
+    label: string;
+    /** Whether this star is currently selected. */
+    selected?: boolean;
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+    /** Click handler. */
+    onclick?: (event: MouseEvent) => void;
+    [key: string]: unknown;
+};
+declare const FiveStarRatingPickerButton: import("svelte").Component<$$ComponentProps, {}, "">;
+type FiveStarRatingPickerButton = ReturnType<typeof FiveStarRatingPickerButton>;
+export default FiveStarRatingPickerButton;