zabi-components 8.1.0 → 9.0.0

package/dist/molecules/ChipGroup.svelte

@@ -0,0 +1,325 @@
+<script lang="ts">
+    import { getContext, onMount, setContext, type Snippet } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import { cn } from "../util/cn.js";
+    import { generateId } from "../util/ssr-safe.js";
+    import {
+        CHIP_GAP,
+        CHIP_GROUP_CONTEXT_KEY,
+        SELECTED_CHIP_SELECTOR,
+        chipBox,
+        measureRowOverflow,
+        scrollLeftToReveal,
+        toggleValue,
+        type ChipGroupContext,
+        type RowMetrics,
+    } from "../util/chip.js";
+
+    /** Other attributes (`id`, `data-*`, `aria-label`, `aria-labelledby`, ...) land on the group element. */
+    type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "onchange" | "children"> & {
+        class?: string;
+        /**
+         * `wrap` breaks onto as many lines as it needs; `row` is one line that
+         * scrolls sideways, with the chosen chip brought into view on load.
+         * A group inside a group takes the layout of the one around it.
+         */
+        layout?: "wrap" | "row";
+        /** The group's accessible name. Not shown unless `showLabel`. */
+        label?: string;
+        /** Show `label` as text above the group (beside it, in a group inside a group). */
+        showLabel?: boolean;
+        /**
+         * `radio` or `checkbox`: the chips are inputs that share this group's
+         * `name` and `value`. Without it the group only lays out its chips,
+         * which are links or toggle buttons.
+         */
+        type?: "radio" | "checkbox";
+        /** Name the inputs submit under. */
+        name?: string;
+        /**
+         * What is chosen. Bindable: a string, or `undefined` for none, for
+         * `radio`; an array of strings for `checkbox`.
+         */
+        value?: string | string[] | undefined;
+        /** Disables every chip in the group. */
+        disabled?: boolean;
+        /** With `layout="row"`: `fade` dims the edge that has more chips beyond it; `none` never does. */
+        edge?: "fade" | "none";
+        /** With `layout="row"`: bring the chosen chip into view when the row appears. */
+        scrollSelectedIntoView?: boolean;
+        /** Called with the new `value` when a person changes it. */
+        onchange?: (value: string | string[] | undefined) => void;
+        children?: Snippet;
+    };
+
+    let {
+        class: className = "",
+        layout = "wrap",
+        label = "",
+        showLabel = false,
+        type,
+        name,
+        value = $bindable<Props["value"]>(),
+        disabled = false,
+        edge = "fade",
+        scrollSelectedIntoView = true,
+        onchange,
+        children,
+        ...restProps
+    }: Props = $props();
+
+    // No fallback on a bindable prop (see Rating): a checkbox group starts
+    // empty, here, so the server renders it and `bind:value={undefined}` works.
+    const applyDefaults = () => {
+        if (type === "checkbox" && value === undefined) value = [];
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
+    /** A group inside a group is a sub-group: it names its chips and does not scroll or wrap on its own. */
+    const parent = getContext<ChipGroupContext | undefined>(CHIP_GROUP_CONTEXT_KEY);
+    const nested = parent !== undefined;
+    const effectiveLayout = $derived(parent ? parent.layout : layout);
+
+    function isSelected(chip: string): boolean {
+        if (type === "radio") return value === chip;
+        if (type === "checkbox") return Array.isArray(value) && value.includes(chip);
+        return false;
+    }
+
+    setContext<ChipGroupContext>(CHIP_GROUP_CONTEXT_KEY, {
+        get type() {
+            return type;
+        },
+        get name() {
+            return name;
+        },
+        get layout() {
+            return effectiveLayout;
+        },
+        get disabled() {
+            return disabled;
+        },
+        get radioValue() {
+            return type === "radio" && typeof value === "string" ? value : undefined;
+        },
+        isSelected,
+        change(chip, checked, report) {
+            if (type === "radio") {
+                // Single selection never clears: unchecking is not a thing a radio does.
+                if (!checked) return;
+                value = chip;
+            } else if (type === "checkbox") {
+                value = toggleValue(Array.isArray(value) ? value : [], chip, checked);
+            } else {
+                return;
+            }
+            if (report) onchange?.(value);
+        },
+        restore() {
+            if (type === "radio") value = undefined;
+        },
+    });
+
+    const labelId = generateId("chip-group-label");
+    const role = $derived(type === "radio" ? "radiogroup" : "group");
+    const isRow = $derived(effectiveLayout === "row");
+    /** Only the outermost row scrolls; a sub-group is just inline. */
+    const scrolls = $derived(isRow && !nested);
+
+    // ---- The one-row layout: the chosen chip in view, and the edge cue. ----
+
+    let scroller = $state<HTMLDivElement | null>(null);
+    let overflowStart = $state(false);
+    let overflowEnd = $state(false);
+
+    function metricsOf(element: HTMLElement): RowMetrics {
+        return {
+            scrollLeft: element.scrollLeft,
+            scrollWidth: element.scrollWidth,
+            clientWidth: element.clientWidth,
+            rtl: getComputedStyle(element).direction === "rtl",
+        };
+    }
+
+    function measure() {
+        if (!scroller) return;
+        const overflow = measureRowOverflow(metricsOf(scroller));
+        overflowStart = overflow.start;
+        overflowEnd = overflow.end;
+    }
+
+    /** Room kept between the revealed chip and the edge: one gap, and the fade when there is one. */
+    const FADE_WIDTH = 24;
+
+    /** Scrolls the row, and only the row (it sets `scrollLeft`, so the page cannot move). Not animated. */
+    function revealSelected() {
+        const row = scroller;
+        if (!row) return;
+        const selected = row.querySelector(SELECTED_CHIP_SELECTOR);
+        if (!selected) return;
+        const box = row.getBoundingClientRect();
+        const item = chipBox(selected).getBoundingClientRect();
+        row.scrollLeft = scrollLeftToReveal(
+            metricsOf(row),
+            { left: box.left, right: box.right },
+            { left: item.left, right: item.right },
+            edge === "fade" ? CHIP_GAP + FADE_WIDTH : CHIP_GAP,
+        );
+    }
+
+    let revealed = false;
+    onMount(() => {
+        if (!revealed && scroller && scrolls && scrollSelectedIntoView) revealSelected();
+        revealed = true;
+    });
+
+    $effect(() => {
+        const row = scroller;
+        if (!row || !scrolls) {
+            overflowStart = false;
+            overflowEnd = false;
+            return;
+        }
+        measure();
+        row.addEventListener("scroll", measure, { passive: true });
+        let sizes: ResizeObserver | undefined;
+        let nodes: MutationObserver | undefined;
+        if (typeof ResizeObserver !== "undefined") {
+            const sized = new ResizeObserver(measure);
+            sizes = sized;
+            const watch = () => {
+                sized.disconnect();
+                sized.observe(row);
+                for (const child of row.children) sized.observe(child);
+            };
+            watch();
+            if (typeof MutationObserver !== "undefined") {
+                nodes = new MutationObserver(() => {
+                    watch();
+                    measure();
+                });
+                nodes.observe(row, { childList: true });
+            }
+        }
+        return () => {
+            row.removeEventListener("scroll", measure);
+            sizes?.disconnect();
+            nodes?.disconnect();
+        };
+    });
+
+    const hostClasses = $derived.by(() => {
+        if (nested) {
+            return cn(isRow ? "flex shrink-0 items-center gap-2" : "flex flex-wrap items-center gap-2", className);
+        }
+        if (isRow) {
+            // 4px of room on every side for the focus ring, which the scrolling box
+            // would clip, taken back by the negative margin (as Tabs does).
+            return cn(
+                "chip-row -m-1 flex flex-nowrap items-center gap-2 overflow-x-auto overflow-y-hidden overscroll-x-contain p-1 scroll-px-8 has-[>[data-chip-subgroup]]:gap-6",
+                className,
+            );
+        }
+        return cn("flex flex-wrap items-center gap-2 has-[>[data-chip-subgroup]]:gap-x-6", className);
+    });
+</script>
+
+{#snippet group(labelledBy: string | undefined)}
+    <div
+        bind:this={scroller}
+        {role}
+        class={hostClasses}
+        aria-label={labelledBy ? undefined : label || undefined}
+        aria-labelledby={labelledBy}
+        data-chip-subgroup={nested ? "" : undefined}
+        data-layout={nested ? undefined : effectiveLayout}
+        data-overflow-start={scrolls && edge === "fade" && overflowStart ? "" : undefined}
+        data-overflow-end={scrolls && edge === "fade" && overflowEnd ? "" : undefined}
+        {...restProps}
+    >
+        {#if nested && showLabel && label}
+            <span id={labelId} class="shrink-0 text-sm font-medium whitespace-nowrap text-label">{label}</span>
+        {/if}
+        {@render children?.()}
+    </div>
+{/snippet}
+
+{#if !nested && showLabel && label}
+    <div class="flex flex-col gap-2">
+        <span id={labelId} class="text-sm font-medium text-label">{label}</span>
+        {@render group(labelId)}
+    </div>
+{:else if nested && showLabel && label}
+    {@render group(labelId)}
+{:else}
+    {@render group(undefined)}
+{/if}
+
+<style>
+    /*
+     * One line that scrolls sideways, with no scrollbar. The edge cue is a
+     * mask, not a gradient laid over the chips, so it fades them into any
+     * background, a brand block included, and nothing sits on a chip or its
+     * focus ring. Only a side with more chips beyond it fades (the component
+     * writes data-overflow-start and -end after it has measured), and there
+     * is none on the server. The mask is physical; start is the right edge
+     * in a right-to-left row.
+     */
+    :global(.chip-row) {
+        scrollbar-width: none;
+    }
+
+    :global(.chip-row::-webkit-scrollbar) {
+        display: none;
+    }
+
+    :global(.chip-row[data-overflow-start]),
+    :global(.chip-row[data-overflow-end]) {
+        --chip-fade-start: 0px;
+        --chip-fade-end: 0px;
+        --chip-fade-left: var(--chip-fade-start);
+        --chip-fade-right: var(--chip-fade-end);
+    }
+
+    :global(.chip-row[data-overflow-start]) {
+        --chip-fade-start: 1.5rem;
+    }
+
+    :global(.chip-row[data-overflow-end]) {
+        --chip-fade-end: 1.5rem;
+    }
+
+    :global(.chip-row[data-overflow-start]:dir(rtl)),
+    :global(.chip-row[data-overflow-end]:dir(rtl)) {
+        --chip-fade-left: var(--chip-fade-end);
+        --chip-fade-right: var(--chip-fade-start);
+    }
+
+    :global(.chip-row[data-overflow-start]),
+    :global(.chip-row[data-overflow-end]) {
+        -webkit-mask-image: linear-gradient(
+            to right,
+            transparent,
+            black var(--chip-fade-left),
+            black calc(100% - var(--chip-fade-right)),
+            transparent
+        );
+        mask-image: linear-gradient(
+            to right,
+            transparent,
+            black var(--chip-fade-left),
+            black calc(100% - var(--chip-fade-right)),
+            transparent
+        );
+    }
+
+    /* Forced colours: a half-transparent label is harder to read than a cut-off one. */
+    @media (forced-colors: active) {
+        :global(.chip-row[data-overflow-start]),
+        :global(.chip-row[data-overflow-end]) {
+            -webkit-mask-image: none;
+            mask-image: none;
+        }
+    }
+</style>

package/dist/molecules/ChipGroup.svelte.d.ts

@@ -0,0 +1,41 @@
+import { type Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/** Other attributes (`id`, `data-*`, `aria-label`, `aria-labelledby`, ...) land on the group element. */
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "onchange" | "children"> & {
+    class?: string;
+    /**
+     * `wrap` breaks onto as many lines as it needs; `row` is one line that
+     * scrolls sideways, with the chosen chip brought into view on load.
+     * A group inside a group takes the layout of the one around it.
+     */
+    layout?: "wrap" | "row";
+    /** The group's accessible name. Not shown unless `showLabel`. */
+    label?: string;
+    /** Show `label` as text above the group (beside it, in a group inside a group). */
+    showLabel?: boolean;
+    /**
+     * `radio` or `checkbox`: the chips are inputs that share this group's
+     * `name` and `value`. Without it the group only lays out its chips,
+     * which are links or toggle buttons.
+     */
+    type?: "radio" | "checkbox";
+    /** Name the inputs submit under. */
+    name?: string;
+    /**
+     * What is chosen. Bindable: a string, or `undefined` for none, for
+     * `radio`; an array of strings for `checkbox`.
+     */
+    value?: string | string[] | undefined;
+    /** Disables every chip in the group. */
+    disabled?: boolean;
+    /** With `layout="row"`: `fade` dims the edge that has more chips beyond it; `none` never does. */
+    edge?: "fade" | "none";
+    /** With `layout="row"`: bring the chosen chip into view when the row appears. */
+    scrollSelectedIntoView?: boolean;
+    /** Called with the new `value` when a person changes it. */
+    onchange?: (value: string | string[] | undefined) => void;
+    children?: Snippet;
+};
+declare const ChipGroup: import("svelte").Component<Props, {}, "value">;
+type ChipGroup = ReturnType<typeof ChipGroup>;
+export default ChipGroup;

package/dist/molecules/Collapsible.svelte

@@ -3,7 +3,7 @@
     import type { HTMLAttributes } from "svelte/elements";
     import ChevronDown from "@lucide/svelte/icons/chevron-down";
     import { cn } from "../util/cn.js";
-    import { generateId } from "../util/ssr-safe.js";
+    import { generateId, isBrowser } from "../util/ssr-safe.js";
     import {
         COLLAPSIBLE_GROUP,
         type CollapsibleGroupContext,
@@ -13,11 +13,19 @@
         type CollapsibleTriggerState,
     } from "../util/collapsible.js";
 
-    /** Other attributes (`id`, `data-*`, ...) land on the host `<div>`. */
+    /**
+     * A trigger, then a panel of its own that it opens. It is not for a "show
+     * all" under a list: there the control comes after the content, and what
+     * it shows is more items of a list that is already on the screen. For
+     * that, put a `Button` with `aria-expanded` and `aria-controls` under the
+     * list and let the list draw the rest (Z-127).
+     *
+     * Other attributes (`id`, `data-*`, ...) land on the host `<div>`.
+     */
     type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "title"> & {
         /** Extra classes for the host element. */
         class?: string;
-        /** Extra classes for the default trigger button. */
+        /** Extra classes for the default trigger (a `<summary>`). */
         triggerClass?: string;
         /** Extra classes for the panel. */
         panelClass?: string;
@@ -30,18 +38,27 @@
          * a group does not close a disabled panel either.
          */
         disabled?: boolean;
-        /** Text of the default trigger, a full-width header button with a chevron. */
+        /**
+         * Text of the default trigger, a full-width header with a chevron. It is
+         * a native `<details>` / `<summary>`, so it opens and closes without
+         * scripts: before hydration, and for a visitor who has none.
+         */
         title?: string;
         /**
          * Your own header, in place of the default trigger. Spread the first
-         * argument on a `<button>`; the second carries the open state.
+         * argument on a `<button>`; the second carries the open state. This
+         * path needs scripts: the button and the `hidden` panel are yours to
+         * wire, and nothing opens until the page has hydrated. Use `title` for
+         * content that must open without scripts.
          */
         trigger?: Snippet<[CollapsibleTriggerProps, CollapsibleTriggerState]>;
         /** Wraps the default trigger in `<h1>`–`<h6>`. No heading when omitted. */
         headingLevel?: CollapsibleHeadingLevel;
         /**
-         * Closed content is kept in the DOM under `hidden`, so a form inside it
-         * keeps its values. Set this to remove the content while closed instead.
+         * Closed content stays in the DOM, inside the closed `<details>`, so a
+         * form inside it keeps its values and still submits them: closed
+         * details content is part of the form. Set this to remove the content
+         * while closed instead.
          */
         unmountOnClose?: boolean;
         /**
@@ -167,6 +184,67 @@
         "data-collapsible-trigger": "",
     } satisfies CollapsibleTriggerProps);
 
+    let detailsElement: HTMLDetailsElement | undefined = $state();
+
+    /**
+     * What only the server writes on the `<details>`: the `open` attribute and
+     * a mark that says the element came from the server. The client never
+     * writes `open` through the template: hydration would set it from the
+     * state and undo a toggle the visitor made before the scripts arrived.
+     * The effects below adopt that choice, then keep `open` in line.
+     */
+    const SERVER_MARK = "data-collapsible-ssr";
+    const serverAttributes = () =>
+        isBrowser() ? {} : { open: isOpen, [SERVER_MARK]: "" };
+
+    // Once, after mount: a panel toggled before hydration keeps that state.
+    $effect(() => {
+        const element = detailsElement;
+        if (!element?.hasAttribute(SERVER_MARK)) return;
+        element.removeAttribute(SERVER_MARK);
+        untrack(() => {
+            if (!disabled && element.open !== isOpen) setOpen(element.open);
+        });
+    });
+
+    // `open` follows the state: an `open` bound from outside, a group closing
+    // a sibling. Runs after the adoption above on the first pass.
+    $effect(() => {
+        const element = detailsElement;
+        if (element && element.open !== isOpen) element.open = isOpen;
+    });
+
+    /**
+     * The browser's `toggle` event is where a change made on the `<details>`
+     * enters: a click on the summary, Enter or Space, find-in-page opening it,
+     * or the native exclusive group closing it. It also fires, a task later,
+     * for a change this component made itself; `setOpen` then sees no change.
+     */
+    function handleToggle() {
+        const element = detailsElement;
+        if (!element) return;
+        if (disabled) {
+            // Find-in-page can still open a disabled panel: undo it.
+            if (element.open !== isOpen) element.open = isOpen;
+            return;
+        }
+        setOpen(element.open);
+    }
+
+    /** A summary cannot be disabled, so its click is cancelled instead. */
+    function handleSummaryClick(event: MouseEvent) {
+        if (disabled) event.preventDefault();
+    }
+
+    /**
+     * Native exclusivity (the `name` attribute) for a single-open group. A
+     * disabled panel stays out of it: the group neither closes nor counts it.
+     */
+    const detailsName = $derived(disabled ? undefined : group?.exclusiveName);
+
+    const rowClass =
+        "m-0 flex items-center justify-between gap-2 px-3 py-2 text-sm font-medium pointer-coarse:min-h-11";
+
     /**
      * A region is a landmark, and a page of them is noise (the WAI-ARIA
      * accordion pattern warns against it). In a single-open group at most one
@@ -178,66 +256,92 @@
     );
 </script>
 
-{#snippet defaultTrigger()}
-    <button
-        {...triggerProps}
+{#snippet defaultRow()}
+    <span class="min-w-0 flex-1">{title}</span>
+    <ChevronDown
+        size={16}
+        aria-hidden="true"
         class={cn(
-            "focus-ring flex w-full cursor-pointer items-center justify-between gap-2 rounded-control px-3 py-2 text-start text-sm font-medium text-headline transition-colors duration-150 hover:bg-surface-hover active:bg-surface-active motion-reduce:transition-none pointer-coarse:min-h-11 disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent disabled:active:bg-transparent",
-            triggerClass,
+            "shrink-0 text-description transition-transform duration-150 motion-reduce:transition-none",
+            isOpen && "rotate-180",
         )}
-    >
-        <span class="min-w-0 flex-1">{title}</span>
-        <ChevronDown
-            size={16}
-            aria-hidden="true"
-            class={cn(
-                "shrink-0 text-description transition-transform duration-150 motion-reduce:transition-none",
-                isOpen && "rotate-180",
-            )}
-        />
-    </button>
+    />
 {/snippet}
 
-<div
-    class={cn(className)}
-    data-state={isOpen ? "open" : "closed"}
-    data-disabled={disabled ? "" : undefined}
-    {...restProps}
->
-    {#if trigger}
-        {@render trigger(triggerProps, { open: isOpen, disabled })}
-    {:else if headingLevel === 1}
-        <!-- One branch per level, not `<svelte:element>`: hydration takes a
-        dynamic element out and puts it back, which blurs the trigger inside
-        it if the user had already tabbed to it. -->
-        <h1 class="m-0">{@render defaultTrigger()}</h1>
-    {:else if headingLevel === 2}
-        <h2 class="m-0">{@render defaultTrigger()}</h2>
-    {:else if headingLevel === 3}
-        <h3 class="m-0">{@render defaultTrigger()}</h3>
-    {:else if headingLevel === 4}
-        <h4 class="m-0">{@render defaultTrigger()}</h4>
-    {:else if headingLevel === 5}
-        <h5 class="m-0">{@render defaultTrigger()}</h5>
-    {:else if headingLevel === 6}
-        <h6 class="m-0">{@render defaultTrigger()}</h6>
-    {:else}
-        {@render defaultTrigger()}
-    {/if}
-
-    <!-- `hidden` is `display: none`: closed content takes no focus and is not
-    in the accessibility tree. The element itself stays, so `aria-controls`
-    always points at something. -->
+{#snippet panel()}
     <div
         bind:this={panelElement}
         id={panelId}
         role={panelRole}
         aria-labelledby={triggerId}
-        hidden={!isOpen}
+        hidden={trigger ? !isOpen : undefined}
         class={cn(!trigger && "px-3 pb-3 pt-1", panelClass)}
     >
         {#if isOpen || !unmountOnClose}
             {@render children?.()}
         {/if}
     </div>
+{/snippet}
+
+<div
+    class={cn(className)}
+    data-state={isOpen ? "open" : "closed"}
+    data-disabled={disabled ? "" : undefined}
+    {...restProps}
+>
+    {#if trigger}
+        {@render trigger(triggerProps, { open: isOpen, disabled })}
+        <!-- `hidden` is `display: none`: closed content takes no focus and is not
+        in the accessibility tree. The element itself stays, so `aria-controls`
+        always points at something. -->
+        {@render panel()}
+    {:else}
+        <!-- A native disclosure: the browser opens and closes it, so it works
+        before hydration and without scripts. `open` follows `isOpen` (see
+        `serverAttributes`); user changes come back through `toggle`. -->
+        <details
+            bind:this={detailsElement}
+            {...serverAttributes()}
+            name={detailsName}
+            ontoggle={handleToggle}
+        >
+            <summary
+                id={triggerId}
+                aria-controls={panelId}
+                aria-disabled={disabled ? "true" : undefined}
+                tabindex={disabled ? -1 : undefined}
+                data-collapsible-trigger=""
+                onclick={handleSummaryClick}
+                class={cn(
+                    "focus-ring block w-full cursor-pointer list-none rounded-control text-start text-sm font-medium text-headline transition-colors duration-150 hover:bg-surface-hover active:bg-surface-active motion-reduce:transition-none [&::-webkit-details-marker]:hidden",
+                    disabled &&
+                        "pointer-events-none cursor-not-allowed opacity-50 hover:bg-transparent active:bg-transparent",
+                    triggerClass,
+                )}
+            >
+                <!-- One branch per level, not `<svelte:element>`: hydration takes
+                a dynamic element out and puts it back, which blurs the trigger
+                inside it if the user had already tabbed to it. The heading goes
+                inside the summary: a summary inside a heading is not valid. The
+                flex row is on the inner element, not on the summary, which
+                older Safari does not lay out as flex. -->
+                {#if headingLevel === 1}
+                    <h1 class={rowClass}>{@render defaultRow()}</h1>
+                {:else if headingLevel === 2}
+                    <h2 class={rowClass}>{@render defaultRow()}</h2>
+                {:else if headingLevel === 3}
+                    <h3 class={rowClass}>{@render defaultRow()}</h3>
+                {:else if headingLevel === 4}
+                    <h4 class={rowClass}>{@render defaultRow()}</h4>
+                {:else if headingLevel === 5}
+                    <h5 class={rowClass}>{@render defaultRow()}</h5>
+                {:else if headingLevel === 6}
+                    <h6 class={rowClass}>{@render defaultRow()}</h6>
+                {:else}
+                    <span class={rowClass}>{@render defaultRow()}</span>
+                {/if}
+            </summary>
+            {@render panel()}
+        </details>
+    {/if}
 </div>