zabi-components 7.0.2 → 8.1.0

package/dist/molecules/Collapsible.svelte

@@ -0,0 +1,243 @@
+<script lang="ts">
+    import { getContext, onDestroy, setContext, untrack, type Snippet } from "svelte";
+    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 {
+        COLLAPSIBLE_GROUP,
+        type CollapsibleGroupContext,
+        type CollapsibleGroupMember,
+        type CollapsibleHeadingLevel,
+        type CollapsibleTriggerProps,
+        type CollapsibleTriggerState,
+    } from "../util/collapsible.js";
+
+    /** 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. */
+        triggerClass?: string;
+        /** Extra classes for the panel. */
+        panelClass?: string;
+        /** Whether the panel is shown; supports `bind:open`. */
+        open?: boolean;
+        /** Called when the user toggles the panel, or a group closes it. */
+        onopenchange?: (open: boolean) => void;
+        /**
+         * The trigger cannot be activated. The panel keeps its current state:
+         * a group does not close a disabled panel either.
+         */
+        disabled?: boolean;
+        /** Text of the default trigger, a full-width header button with a chevron. */
+        title?: string;
+        /**
+         * Your own header, in place of the default trigger. Spread the first
+         * argument on a `<button>`; the second carries the open state.
+         */
+        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.
+         */
+        unmountOnClose?: boolean;
+        /**
+         * Gives the panel `role="region"`, which makes it a landmark. Defaults
+         * to true only inside a single-open `CollapsibleGroup`.
+         */
+        region?: boolean;
+        children?: Snippet;
+    };
+
+    let {
+        class: className = "",
+        triggerClass = "",
+        panelClass = "",
+        open = $bindable<Exclude<Props["open"], undefined>>(),
+        onopenchange,
+        disabled = false,
+        title,
+        trigger,
+        headingLevel,
+        unmountOnClose = false,
+        region,
+        children,
+        ...restProps
+    }: Props = $props();
+
+    // No fallback on a bindable prop: Svelte refuses `bind:…={undefined}` on
+    // one that has a fallback (`props_invalid_value`), and a page that throws
+    // while it hydrates never becomes interactive. The default is applied
+    // here instead: at once, for the server and the first render, and again
+    // whenever a parent hands back `undefined`.
+    const applyDefaults = () => {
+        if (open === undefined) open = false;
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
+    const triggerId = generateId("collapsible-trigger");
+    const panelId = generateId("collapsible-panel");
+
+    const group = getContext<CollapsibleGroupContext | undefined>(COLLAPSIBLE_GROUP);
+    // A Collapsible inside this panel is not a member of the group around it:
+    // opening it must not close the panel it lives in.
+    setContext(COLLAPSIBLE_GROUP, undefined);
+
+    /**
+     * True for a panel that asked to start open in a single-open group that
+     * already had one. It renders closed from the first render, the server's
+     * included, and `open` is brought in line after mount. Nobody changed
+     * anything, so `onopenchange` is not called for it.
+     */
+    let startClosed = $state(false);
+    /** What is rendered. Everything below reads this, not `open`. */
+    const isOpen = $derived(open && !startClosed);
+
+    let panelElement: HTMLDivElement | undefined = $state();
+
+    function setOpen(next: boolean) {
+        if (isOpen === next) return;
+        open = next;
+        onopenchange?.(next);
+    }
+
+    function toggle() {
+        if (disabled) return;
+        setOpen(!isOpen);
+    }
+
+    const member: CollapsibleGroupMember = {
+        triggerId,
+        // Spelled out rather than `isOpen`: the group asks while this
+        // component is still initialising, before `startClosed` is known, and
+        // on the server a derived value keeps its first answer.
+        isOpen: () => open && !startClosed,
+        isDisabled: () => disabled,
+        close: () => setOpen(false),
+    };
+
+    if (group) {
+        const registration = group.register(member);
+        startClosed = registration.startClosed;
+        onDestroy(registration.unregister);
+    }
+
+    // The bound prop cannot be written while the component initialises, so
+    // the settled state is written back here, once.
+    $effect(() => {
+        if (!startClosed) return;
+        open = false;
+        startClosed = false;
+    });
+
+    // An effect rather than a call in `toggle`, so a panel opened from outside
+    // through `bind:open` closes its siblings as well. Untracked, because the
+    // group reads the siblings' state: tracking that would re-run this effect
+    // when a sibling opens, and the two would close each other.
+    $effect(() => {
+        if (isOpen) untrack(() => group?.opened(member));
+    });
+
+    // A panel can close while focus is inside it: the parent sets `open`, or
+    // a group closes it. Hidden content cannot hold focus, which would fall
+    // to `<body>`, so the trigger takes it. This runs before the panel is
+    // hidden, while the focused element can still be found; focus is not
+    // touched in any other case.
+    $effect.pre(() => {
+        if (isOpen || !panelElement) return;
+        const panel = panelElement;
+        untrack(() => {
+            if (panel.contains(document.activeElement)) {
+                document.getElementById(triggerId)?.focus();
+            }
+        });
+    });
+
+    const triggerProps = $derived({
+        id: triggerId,
+        type: "button",
+        "aria-expanded": isOpen,
+        "aria-controls": panelId,
+        disabled,
+        onclick: toggle,
+        "data-collapsible-trigger": "",
+    } satisfies CollapsibleTriggerProps);
+
+    /**
+     * 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
+     * panel is exposed at a time, so a region is safe there. Everywhere else
+     * the panel is a plain named group unless the caller asks for a region.
+     */
+    const panelRole = $derived(
+        (region ?? (group ? !group.multiple : false)) ? "region" : "group",
+    );
+</script>
+
+{#snippet defaultTrigger()}
+    <button
+        {...triggerProps}
+        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,
+        )}
+    >
+        <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. -->
+    <div
+        bind:this={panelElement}
+        id={panelId}
+        role={panelRole}
+        aria-labelledby={triggerId}
+        hidden={!isOpen}
+        class={cn(!trigger && "px-3 pb-3 pt-1", panelClass)}
+    >
+        {#if isOpen || !unmountOnClose}
+            {@render children?.()}
+        {/if}
+    </div>
+</div>

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

@@ -0,0 +1,44 @@
+import { type Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import { type CollapsibleHeadingLevel, type CollapsibleTriggerProps, type CollapsibleTriggerState } from "../util/collapsible.js";
+/** 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. */
+    triggerClass?: string;
+    /** Extra classes for the panel. */
+    panelClass?: string;
+    /** Whether the panel is shown; supports `bind:open`. */
+    open?: boolean;
+    /** Called when the user toggles the panel, or a group closes it. */
+    onopenchange?: (open: boolean) => void;
+    /**
+     * The trigger cannot be activated. The panel keeps its current state:
+     * a group does not close a disabled panel either.
+     */
+    disabled?: boolean;
+    /** Text of the default trigger, a full-width header button with a chevron. */
+    title?: string;
+    /**
+     * Your own header, in place of the default trigger. Spread the first
+     * argument on a `<button>`; the second carries the open state.
+     */
+    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.
+     */
+    unmountOnClose?: boolean;
+    /**
+     * Gives the panel `role="region"`, which makes it a landmark. Defaults
+     * to true only inside a single-open `CollapsibleGroup`.
+     */
+    region?: boolean;
+    children?: Snippet;
+};
+declare const Collapsible: import("svelte").Component<Props, {}, "open">;
+type Collapsible = ReturnType<typeof Collapsible>;
+export default Collapsible;

package/dist/molecules/CollapsibleGroup.svelte

@@ -0,0 +1,126 @@
+<script lang="ts">
+    import { setContext, untrack, type Snippet } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import { cn } from "../util/cn.js";
+    import {
+        COLLAPSIBLE_GROUP,
+        nextTriggerIndex,
+        type CollapsibleGroupContext,
+        type CollapsibleGroupMember,
+    } from "../util/collapsible.js";
+
+    /** Other attributes (`id`, `aria-label`, `data-*`, ...) land on the host `<div>`. */
+    type Props = Omit<HTMLAttributes<HTMLDivElement>, "class"> & {
+        /** Extra classes for the host element. */
+        class?: string;
+        /** Lets several panels be open at once. By default opening one closes the others. */
+        multiple?: boolean;
+        /** The `Collapsible` components to coordinate. */
+        children?: Snippet;
+    };
+
+    let {
+        class: className = "",
+        multiple = false,
+        onkeydown,
+        children,
+        ...restProps
+    }: Props = $props();
+
+    let hostElement: HTMLDivElement | undefined = $state();
+
+    /** In the order the Collapsibles were created. */
+    const members = new Set<CollapsibleGroupMember>();
+
+    /** A disabled panel keeps its state, so it neither holds the one open slot nor loses it. */
+    function holdsTheSlot(member: CollapsibleGroupMember): boolean {
+        return member.isOpen() && !member.isDisabled();
+    }
+
+    function closeOthers(keep: CollapsibleGroupMember) {
+        for (const member of members) {
+            if (member !== keep && holdsTheSlot(member)) member.close();
+        }
+    }
+
+    setContext<CollapsibleGroupContext>(COLLAPSIBLE_GROUP, {
+        get multiple() {
+            return multiple;
+        },
+        register(member) {
+            // Settled here, while the members initialise, so the first render
+            // (the server's included) already shows one open panel.
+            const startClosed =
+                !multiple &&
+                holdsTheSlot(member) &&
+                [...members].some(holdsTheSlot);
+            members.add(member);
+            return { unregister: () => members.delete(member), startClosed };
+        },
+        opened(member) {
+            // A disabled panel is outside the one-open rule in both
+            // directions: it is not closed, and it closes nothing.
+            if (!multiple && !member.isDisabled()) closeOthers(member);
+        },
+    });
+
+    // Going from `multiple` back to single: the first open panel stays.
+    $effect(() => {
+        if (multiple) return;
+        untrack(() => {
+            const first = [...members].find(holdsTheSlot);
+            if (first) closeOthers(first);
+        });
+    });
+
+    /**
+     * The optional keys of the accordion pattern, between this group's own
+     * header buttons. A trigger nested in a panel belongs to no group, or to
+     * an inner one, and is left alone; Tab is never touched.
+     */
+    function handleKeydown(
+        event: KeyboardEvent & { currentTarget: EventTarget & HTMLDivElement },
+    ) {
+        onkeydown?.(event);
+        if (event.defaultPrevented) return;
+        if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+        const target = event.target;
+        if (!(target instanceof HTMLElement) || !hostElement) return;
+
+        const ids = new Set([...members].map((member) => member.triggerId));
+        if (!ids.has(target.id)) return;
+
+        // Read from the DOM so the order is the visual one. A disabled button
+        // cannot take focus, so it is skipped.
+        const triggers = Array.from(
+            hostElement.querySelectorAll<HTMLButtonElement>(
+                "[data-collapsible-trigger]",
+            ),
+        ).filter((element) => ids.has(element.id) && !element.disabled);
+
+        const next = nextTriggerIndex(
+            event.key,
+            triggers.indexOf(target as HTMLButtonElement),
+            triggers.length,
+        );
+        if (next === null) return;
+
+        // Also keeps the arrow keys from scrolling the page under the header.
+        event.preventDefault();
+        triggers[next]?.focus();
+    }
+</script>
+
+<!-- The listener only moves focus between buttons that are already in the
+tab order; the group itself is not interactive. -->
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div
+    bind:this={hostElement}
+    class={cn("flex flex-col", className)}
+    data-collapsible-group=""
+    data-multiple={multiple ? "" : undefined}
+    {...restProps}
+    onkeydown={handleKeydown}
+>
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,14 @@
+import { type Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/** Other attributes (`id`, `aria-label`, `data-*`, ...) land on the host `<div>`. */
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class"> & {
+    /** Extra classes for the host element. */
+    class?: string;
+    /** Lets several panels be open at once. By default opening one closes the others. */
+    multiple?: boolean;
+    /** The `Collapsible` components to coordinate. */
+    children?: Snippet;
+};
+declare const CollapsibleGroup: import("svelte").Component<Props, {}, "">;
+type CollapsibleGroup = ReturnType<typeof CollapsibleGroup>;
+export default CollapsibleGroup;

package/dist/molecules/ComponentDemo.svelte

@@ -1,14 +1,25 @@
 <script lang="ts">
+    import { mergeStrings } from "../util/ready-made-strings.js";
+    import { zabiStringsFor } from "../util/zabi-strings.js";
     import CodeBlock from "../atoms/CodeBlock.svelte";
     import Card from "../atoms/Card.svelte";
     import CardHeader from "../atoms/CardHeader.svelte";
     import CardContent from "../atoms/CardContent.svelte";
+    import { cn } from "../util/cn.js";
+    import {
+        DEFAULT_COMPONENT_DEMO_STRINGS,
+        type ComponentDemoStrings,
+    } from "../util/ready-made-strings.js";
 
     interface Props {
         title: string;
         description?: string;
         code: string;
         language?: string;
+        /** The words of the switch between the preview and the code. */
+        strings?: Partial<ComponentDemoStrings>;
+        class?: string;
+        /** @deprecated use `class`. */
         className?: string;
     }
 
@@ -17,12 +28,21 @@
         description = "",
         code,
         language = "svelte",
-        className = "",
+        strings,
+        class: classAttr = "",
+        className: legacyClass = "",
         children,
         ...restProps
     } = $props<Props & { children?: any }>();
 
+    /** `class` is the public prop; `className` is a deprecated alias.
+     * Both are merged here so existing call sites keep working. */
+    const className = $derived(cn(`${classAttr} ${legacyClass}`));
+
     let showCode = $state(false);
+
+    const provided = zabiStringsFor("componentDemo");
+    const text = $derived(mergeStrings(DEFAULT_COMPONENT_DEMO_STRINGS, provided(), (strings as Partial<ComponentDemoStrings> | undefined)));
 </script>
 
 <div class="relative">
@@ -36,8 +56,8 @@
         <CardContent>
             <button
                 onclick={() => (showCode = !showCode)}
-                class="absolute top-8 right-8 z-10 flex cursor-pointer items-center gap-2 rounded-md px-3 py-1.5 text-sm text-description transition-colors duration-200 hover:bg-base-50 hover:text-body"
-                aria-label={showCode ? "Show preview" : "Show code"}
+                class="absolute top-8 right-8 z-10 flex cursor-pointer items-center gap-2 rounded-control px-3 py-2 pointer-coarse:min-h-11 text-sm text-description transition-colors duration-200 hover:bg-surface-hover hover:text-body active:bg-surface-active"
+                aria-label={showCode ? text.showPreview : text.showCode}
             >
                 {#if showCode}
                     <svg
@@ -59,7 +79,7 @@
                             d="M2.458 12C3.732 7.943 7.523 5 12 5c4.478 0 8.268 2.943 9.542 7-1.274 4.057-5.064 7-9.542 7-4.477 0-8.268-2.943-9.542-7z"
                         />
                     </svg>
-                    Preview
+                    {text.preview}
                 {:else}
                     <svg
                         class="w-4 h-4"
@@ -74,7 +94,7 @@
                             d="M10 20l4-16m4 4l4 4-4 4M6 16l-4-4 4-4"
                         />
                     </svg>
-                    Code
+                    {text.code}
                 {/if}
             </button>
 

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

@@ -1,8 +1,13 @@
+import { type ComponentDemoStrings } from "../util/ready-made-strings.js";
 interface Props {
     title: string;
     description?: string;
     code: string;
     language?: string;
+    /** The words of the switch between the preview and the code. */
+    strings?: Partial<ComponentDemoStrings>;
+    class?: string;
+    /** @deprecated use `class`. */
     className?: string;
 }
 type $$ComponentProps = Props & {