zabi-components 8.0.0 → 9.0.0

package/dist/atoms/Chip.svelte.d.ts

@@ -0,0 +1,57 @@
+import { type Snippet } from "svelte";
+import type { HTMLAnchorAttributes, HTMLButtonAttributes } from "svelte/elements";
+/**
+ * One type for the four forms, as Button has one for the button and the
+ * link: a union of the elements' attributes is too large to carry through
+ * a wrapper. Other attributes land on the element that is the control: the
+ * `<a>`, the `<button>` or the `<input>`; `class` is always the chip's.
+ */
+type Props = Omit<HTMLButtonAttributes, "class" | "type" | "value" | "onchange" | "children"> & {
+    /** Makes the chip a link to this address, which works without scripts. */
+    href?: string;
+    target?: HTMLAnchorAttributes["target"];
+    rel?: HTMLAnchorAttributes["rel"];
+    download?: HTMLAnchorAttributes["download"];
+    hreflang?: HTMLAnchorAttributes["hreflang"];
+    /** With `href`: what `aria-current` says while `selected`. */
+    current?: "page" | "true" | "step" | "location" | "date" | "time";
+    /**
+     * `checkbox` or `radio`: a real input under the chip, which submits in
+     * a form without scripts. Without it (and without `href`) the chip is a
+     * toggle button. Inside a ChipGroup with a `type`, the group's.
+     * `submit` or `button`: a button that does not toggle. A press posts
+     * the form (`submit`, with `name` and `value`) or only calls `onclick`;
+     * `selected` is drawn as on a toggle and said with `aria-pressed`, and
+     * the app decides it, as a server's answer does.
+     */
+    type?: "checkbox" | "radio" | "submit" | "button";
+    /** Name the input is submitted under. Inside a ChipGroup with a `name`, the group's. */
+    name?: string;
+    /** What the input submits, and what a ChipGroup's `value` holds when it is chosen. */
+    value?: string;
+    /** The chip is chosen. Bindable; the one prop for `checked`, `aria-pressed` and `aria-current`. */
+    selected?: boolean;
+    required?: boolean;
+    form?: string;
+    /** 28, 32 or 40px tall. On a coarse pointer the touch target reaches 44px; the box does not grow. */
+    size?: "sm" | "md" | "lg";
+    /** An icon or an avatar before the label. */
+    leading?: Snippet;
+    /** A check icon before the label while selected. On for a checkbox and a toggle button, off for a link and a radio. */
+    checkmark?: boolean;
+    /**
+     * A button chip (`type="submit"`, `"button"` or a toggle) while its
+     * action is on its way, as Button's: `aria-busy` and `aria-disabled`,
+     * a spinner over the label, the press swallowed. The chip keeps its
+     * width and stays a Tab stop, so focus is not lost. Ignored by a link
+     * and by `checkbox` / `radio`, which are not actions.
+     */
+    loading?: boolean;
+    /** Called with the new `selected` when a person changes it. */
+    onchange?: (selected: boolean) => void;
+    class?: string;
+    children?: Snippet;
+};
+declare const Chip: import("svelte").Component<Props, {}, "selected">;
+type Chip = ReturnType<typeof Chip>;
+export default Chip;

package/dist/atoms/CodeBlock.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+    import { DEFAULT_CODE_BLOCK_TEXTS, zabiStringsFor } from "../util/zabi-strings.js";
     import Check from "@lucide/svelte/icons/check";
     import Copy from "@lucide/svelte/icons/copy";
     import IconButton from "./IconButton.svelte";
@@ -12,6 +13,10 @@
         /** @deprecated use `class`. */
         className?: string;
         showCopyButton?: boolean;
+        /** Accessible name of the copy button. */
+        copyLabel?: string;
+        /** Its name for the two seconds after the code was copied. */
+        copiedLabel?: string;
         /** If true, `{@html code}` — only trusted, sanitized input. */
         trustHtml?: boolean;
     }
@@ -22,10 +27,17 @@
         class: classAttr = "",
         className: legacyClass = "",
         showCopyButton = true,
+        copyLabel: copyLabelGiven,
+        copiedLabel: copiedLabelGiven,
         trustHtml = false,
         ...restProps
     }: Props & Record<string, unknown> = $props();
 
+    /** Each text: the prop, else the app-wide word from a `ZabiStringsProvider` above this one, else English. */
+    const provided = zabiStringsFor("codeBlock");
+    const copyLabel = $derived(copyLabelGiven ?? provided()?.copyLabel ?? DEFAULT_CODE_BLOCK_TEXTS.copyLabel);
+    const copiedLabel = $derived(copiedLabelGiven ?? provided()?.copiedLabel ?? DEFAULT_CODE_BLOCK_TEXTS.copiedLabel);
+
     /** `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}`));
@@ -61,7 +73,7 @@
             <IconButton
                 variant="ghost"
                 size="sm"
-                label={copied ? "Code copied to clipboard" : "Copy code to clipboard"}
+                label={copied ? copiedLabel : copyLabel}
                 onclick={copyToClipboard}
             >
                 {#if copied}
@@ -70,6 +82,9 @@
                     <Copy size={16} class="shrink-0" aria-hidden="true" />
                 {/if}
             </IconButton>
+            <!-- A button's new name is not read out while it keeps focus.
+            This says it: always in the page, filled when the code is copied. -->
+            <span class="sr-only" role="status" data-code-block-status>{copied ? copiedLabel : ""}</span>
         {/if}
     </div>
 
@@ -80,8 +95,11 @@
 </div>
 
 <style>
+    /* The token's default is this same stack. It is repeated as the fallback
+       because Tailwind only emits theme variables it sees used, and it does
+       not read a component's scoped styles. */
     .code-block {
-        font-family: "Monaco", "Menlo", "Ubuntu Mono", monospace;
+        font-family: var(--font-family-mono, "Monaco", "Menlo", "Ubuntu Mono", monospace);
     }
 
     :global(.language-svelte .token.tag),

package/dist/atoms/CodeBlock.svelte.d.ts

@@ -6,6 +6,10 @@ interface Props {
     /** @deprecated use `class`. */
     className?: string;
     showCopyButton?: boolean;
+    /** Accessible name of the copy button. */
+    copyLabel?: string;
+    /** Its name for the two seconds after the code was copied. */
+    copiedLabel?: string;
     /** If true, `{@html code}` — only trusted, sanitized input. */
     trustHtml?: boolean;
 }

package/dist/atoms/CodeField.svelte

@@ -0,0 +1,385 @@
+<script lang="ts">
+    import type { HTMLInputAttributes } from "svelte/elements";
+    import type { SemanticVariant } from "../types/variants.js";
+    import { cn } from "../util/cn.js";
+    import type { SizeVariant } from "../types/variants.js";
+    import {
+        activePlace,
+        caretAfterSanitise,
+        CODE_FIELD_GAP_REM,
+        CODE_FIELD_GROUP_GAP_REM,
+        CODE_FIELD_SIZES,
+        codeGroups,
+        codeLength,
+        DEFAULT_CODE_FIELD_STRINGS,
+        isCodeChar,
+        nearestBox,
+        pasteInto,
+        replaceAt,
+        sanitiseCode,
+        type CodeFieldMode,
+        type CodeFieldStrings,
+    } from "../util/code-field.js";
+    import { fieldDescribedBy, fieldMessageState } from "../util/field.js";
+    import { mergeStrings } from "../util/ready-made-strings.js";
+    import { generateId } from "../util/ssr-safe.js";
+    import { zabiStringsFor } from "../util/zabi-strings.js";
+    import FieldMessages from "./FieldMessages.svelte";
+
+    /**
+     * A field for a one-time or verification code. One real `<input>` holds
+     * the code, so autofill from a message, paste, the numeric keyboard, form
+     * posting by `name` and a single accessible name all work as on `Input`;
+     * the boxes are drawn under it and hidden from assistive technology.
+     * Other attributes (`autocomplete`, `inputmode`, `data-*`, ...) land on
+     * the `<input>`.
+     */
+    type Props = Omit<
+        HTMLInputAttributes,
+        | "class"
+        | "size"
+        | "value"
+        | "type"
+        | "id"
+        | "name"
+        | "required"
+        | "disabled"
+        | "readonly"
+        | "maxlength"
+        | "oninput"
+        | "onblur"
+        | "aria-label"
+        | "aria-describedby"
+    > & {
+        /** Omit to auto-generate. */
+        id?: string;
+        /** The code typed so far. Bindable. */
+        value?: string;
+        /** The name the code is posted under, with or without scripts. */
+        name?: string;
+        class?: string;
+        /** Places in the code. A whole number from 1 to 12. */
+        length?: number;
+        /** `numeric` (default): digits only. `alphanumeric` also takes letters. */
+        mode?: CodeFieldMode;
+        /** Box size: `sm` (44px tall, a compact row), `md` (default), `lg`. */
+        size?: SizeVariant;
+        /**
+         * Draws the boxes in groups with a wider gap between them: a number is
+         * the size of each group (`4` makes 4 and 4 of 8), a list gives each
+         * group's size. Only the drawing changes: one input, one value, and a
+         * paste with spaces or dashes still fills it. A row that cannot fit at
+         * large text or a narrow width wraps between groups.
+         */
+        groups?: number | number[];
+        /** Names the field. Defaults to the provider's `codeField.label`, then "Verification code". */
+        label?: string;
+        /** Keeps the label for assistive technology and takes it off the screen. */
+        labelHidden?: boolean;
+        required?: boolean;
+        disabled?: boolean;
+        readonly?: boolean;
+        variant?: SemanticVariant;
+        /** Status text under the field. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+        message?: string;
+        /** Help text under the field, read out with it. */
+        hint?: string;
+        /** An error under the field. It marks the field invalid and is announced; it wins over `variant` and `message`. */
+        error?: string;
+        /** Called with the code when the last place is filled by typing, pasting or autofill. It does not submit anything. */
+        oncomplete?: (value: string) => void;
+        /** Overrides for the built-in strings: label, description. */
+        strings?: Partial<CodeFieldStrings>;
+        oninput?: (event: Event) => void;
+        onblur?: (event: Event) => void;
+        "aria-label"?: string;
+        /** Ids of other elements that describe the field. The length, the hint and the message are added after them. */
+        "aria-describedby"?: string | null;
+    };
+
+    /** An event on the input, as Svelte types the handlers of an element. */
+    type OnInput<E extends Event> = E & { currentTarget: EventTarget & HTMLInputElement };
+
+    let {
+        id: idProp,
+        value = $bindable<Exclude<Props["value"], undefined>>(),
+        name = "",
+        class: className = "",
+        length: lengthProp = 6,
+        mode = "numeric",
+        size = "md",
+        groups,
+        label,
+        labelHidden = false,
+        required = false,
+        disabled = false,
+        readonly = false,
+        variant = "default",
+        message = "",
+        hint = "",
+        error = "",
+        oncomplete,
+        strings,
+        oninput,
+        onblur,
+        "aria-label": ariaLabel,
+        "aria-describedby": describedBy,
+        ...restProps
+    }: Props = $props();
+
+    // No fallback on a bindable prop (see Input): the default is applied here,
+    // at once and whenever a parent hands back `undefined`.
+    const applyDefaults = () => {
+        if (value === undefined) value = "";
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
+    const length = $derived(codeLength(lengthProp));
+    const sizing = $derived(CODE_FIELD_SIZES[size] ?? CODE_FIELD_SIZES.md);
+    const groupSizes = $derived(codeGroups(groups, length));
+    const grouped = $derived(groupSizes.length > 1);
+    /** Which group each box is in, for the drawing, and the first box of each. */
+    const groupStarts = $derived(groupSizes.map((_, index) => groupSizes.slice(0, index).reduce((sum, n) => sum + n, 0)));
+    const provided = zabiStringsFor("codeField");
+    const text = $derived(mergeStrings(DEFAULT_CODE_FIELD_STRINGS, provided(), strings));
+    const shownLabel = $derived(label || text.label);
+
+    const fallbackId = generateId("code");
+    const inputId = $derived(idProp ?? fallbackId);
+    const lengthId = $derived(`${inputId}-length`);
+    const status = $derived(fieldMessageState({ variant, message, hint, error }));
+
+    let input: HTMLInputElement | undefined = $state();
+    let cells: HTMLElement | undefined = $state();
+    let focused = $state(false);
+    let caret = $state(0);
+
+    /**
+     * Without scripts the input is a plain bordered field showing what is
+     * typed, which posts like any other. Once the page is interactive it
+     * becomes the invisible layer over the boxes.
+     */
+    let enhanced = $state(false);
+    $effect(() => {
+        enhanced = true;
+    });
+
+    const places = $derived(Array.from({ length }, (_, index) => value?.[index] ?? ""));
+    const active = $derived(enhanced && focused && !disabled && !readonly ? activePlace(caret, length) : -1);
+
+    const variantClass = $derived(
+        status.variant === "success"
+            ? "border-success"
+            : status.variant === "warning"
+              ? "border-warning"
+              : status.variant === "error"
+                ? "border-error"
+                : "border-input-border",
+    );
+
+    /** The focus ring of `.focus-ring`, drawn on the box the caret is in. */
+    const RING = "shadow-[0_0_0_2px_var(--color-focus-ring-offset),0_0_0_4px_var(--color-focus-ring)]";
+
+    let complete = "";
+
+    /** Sets the code, and calls `oncomplete` when this makes it whole. */
+    function commit(next: string, caretAt: number) {
+        const previous = value ?? "";
+        if (next !== previous) value = next;
+        if (input) {
+            if (input.value !== next) input.value = next;
+            try {
+                input.setSelectionRange(caretAt, caretAt);
+            } catch {
+                // A browser that cannot place the caret: typing still works.
+            }
+        }
+        caret = caretAt;
+        if (next.length === length) {
+            if (next !== complete) {
+                complete = next;
+                oncomplete?.(next);
+            }
+        } else {
+            complete = "";
+        }
+    }
+
+    function syncCaret() {
+        if (input) caret = input.selectionStart ?? input.value.length;
+    }
+
+    function handleInput(event: OnInput<Event>) {
+        oninput?.(event);
+        const field = event.currentTarget;
+        const raw = field.value;
+        const clean = sanitiseCode(raw, mode, length);
+        const at = caretAfterSanitise(raw, field.selectionStart ?? raw.length, mode, length);
+        commit(clean, Math.min(at, clean.length));
+    }
+
+    /**
+     * A character typed over a filled place replaces it; one typed at the end
+     * is added. A character that does not belong never gets in.
+     */
+    function handleKeydown(event: OnInput<KeyboardEvent>) {
+        restProps.onkeydown?.(event);
+        if (event.defaultPrevented || readonly || disabled) return;
+        if (event.ctrlKey || event.metaKey || event.altKey || event.key.length !== 1) return;
+        const field = event.currentTarget;
+        if (!isCodeChar(event.key, mode)) {
+            event.preventDefault();
+            return;
+        }
+        const start = field.selectionStart ?? 0;
+        const end = field.selectionEnd ?? start;
+        if (start === end && start < field.value.length) {
+            event.preventDefault();
+            commit(replaceAt(field.value, start, event.key), start + 1);
+        } else if (start === end && field.value.length >= length) {
+            event.preventDefault();
+        }
+    }
+
+    /** Takes the whole code from the clipboard, wherever the caret is; "123 456" and "123-456" are 123456. */
+    function handlePaste(event: OnInput<ClipboardEvent>) {
+        restProps.onpaste?.(event);
+        if (event.defaultPrevented || readonly || disabled) return;
+        const field = event.currentTarget;
+        event.preventDefault();
+        const pasted = event.clipboardData?.getData("text") ?? "";
+        const start = field.selectionStart ?? field.value.length;
+        const end = field.selectionEnd ?? start;
+        const next = pasteInto(field.value, start, end, pasted, mode, length);
+        if (next === field.value && sanitiseCode(pasted, mode, length) === "") return;
+        commit(next, next.length === length ? length : Math.min(next.length, start + sanitiseCode(pasted, mode, length).length));
+    }
+
+    /** A tap on a box puts the caret there, or at the end of the code when that box is still empty. */
+    function handleClick(event: OnInput<MouseEvent>) {
+        restProps.onclick?.(event);
+        if (!input || !cells) return;
+        const boxes = Array.from(cells.querySelectorAll<HTMLElement>("[data-code-cell]"));
+        let index = nearestBox(
+            boxes.map((box) => box.getBoundingClientRect()),
+            event.clientX,
+            event.clientY,
+        );
+        if (index < 0) return syncCaret();
+        index = Math.min(index, input.value.length);
+        try {
+            input.setSelectionRange(index, index);
+        } catch {
+            // Nothing to place.
+        }
+        syncCaret();
+    }
+
+    const fieldClass = $derived(
+        enhanced
+            ? "absolute inset-0 size-full min-w-0 cursor-text border-0 bg-transparent p-0 text-base text-transparent caret-transparent outline-none selection:bg-transparent disabled:cursor-not-allowed"
+            : cn(
+                  sizing.box,
+                  "w-full rounded-control border bg-input px-3 text-center text-xl font-medium tracking-[0.35em] text-body tabular-nums hover:bg-input-hover disabled:cursor-not-allowed disabled:bg-input-disabled disabled:text-action-disabled-text focus-ring",
+                  variantClass,
+              ),
+    );
+</script>
+
+{#snippet cell(place: string, index: number)}
+    <span
+        data-code-cell
+        data-active={index === active ? "" : undefined}
+        style:max-inline-size="{sizing.maxRem}rem"
+        style:min-inline-size="{sizing.minEm}em"
+        class={cn(
+            "flex flex-1 items-center justify-center rounded-control border bg-input font-medium text-body tabular-nums transition-colors duration-150",
+            sizing.box,
+            sizing.text,
+            variantClass,
+            disabled && "cursor-not-allowed bg-input-disabled text-action-disabled-text",
+            index === active && RING,
+        )}
+    >
+        {place}
+    </span>
+{/snippet}
+
+<div class={cn("w-full", className)}>
+    <label for={inputId} class={cn("mb-2 block text-sm font-medium text-label", labelHidden && "sr-only")}>
+        {shownLabel}
+    </label>
+    <div
+        class="relative"
+        style:max-inline-size="calc({length} * {sizing.maxRem}rem + {length - 1 - Math.max(groupSizes.length - 1, 0)} * {CODE_FIELD_GAP_REM}rem + {Math.max(groupSizes.length - 1, 0)} * {CODE_FIELD_GROUP_GAP_REM}rem)"
+        bind:this={cells}
+    >
+        {#if enhanced}
+            <div
+                class={cn("flex flex-wrap", grouped ? "gap-x-4 gap-y-2" : "gap-2")}
+                aria-hidden="true"
+                data-code-cells
+                data-grouped={grouped ? "" : undefined}
+            >
+                {#if grouped}
+                    {#each groupSizes as groupSize, group (group)}
+                        <div
+                            data-code-group
+                            class="flex gap-2"
+                            style:flex="{groupSize} 1 0"
+                            style:min-inline-size="calc({groupSize} * {sizing.minEm * sizing.digitRem}rem + {groupSize - 1} * {CODE_FIELD_GAP_REM}rem)"
+                            style:max-inline-size="calc({groupSize} * {sizing.maxRem}rem + {groupSize - 1} * {CODE_FIELD_GAP_REM}rem)"
+                        >
+                            {#each places.slice(groupStarts[group], groupStarts[group] + groupSize) as place, offset (offset)}
+                                {@render cell(place, groupStarts[group] + offset)}
+                            {/each}
+                        </div>
+                    {/each}
+                {:else}
+                    {#each places as place, index (index)}
+                        {@render cell(place, index)}
+                    {/each}
+                {/if}
+            </div>
+        {/if}
+        <input
+            bind:this={input}
+            id={inputId}
+            type="text"
+            {name}
+            bind:value
+            {required}
+            {disabled}
+            {readonly}
+            inputmode={mode === "numeric" ? "numeric" : "text"}
+            autocomplete="one-time-code"
+            autocapitalize="off"
+            autocorrect="off"
+            spellcheck={false}
+            class={fieldClass}
+            aria-label={ariaLabel}
+            aria-invalid={status.variant === "error" ? "true" : undefined}
+            aria-required={required ? "true" : undefined}
+            aria-describedby={fieldDescribedBy(inputId, status, [describedBy, lengthId].filter(Boolean).join(" "))}
+            {...restProps}
+            oninput={handleInput}
+            onkeydown={handleKeydown}
+            onpaste={handlePaste}
+            onclick={handleClick}
+            onkeyup={syncCaret}
+            onselect={syncCaret}
+            onfocus={(event) => {
+                focused = true;
+                syncCaret();
+                restProps.onfocus?.(event);
+            }}
+            onblur={(event) => {
+                focused = false;
+                onblur?.(event);
+            }}
+        />
+    </div>
+    <span id={lengthId} class="sr-only">{text.description(length, mode)}</span>
+    <FieldMessages fieldId={inputId} {status} {hint} />
+</div>

package/dist/atoms/CodeField.svelte.d.ts

@@ -0,0 +1,61 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { SemanticVariant } from "../types/variants.js";
+import type { SizeVariant } from "../types/variants.js";
+import { type CodeFieldMode, type CodeFieldStrings } from "../util/code-field.js";
+/**
+ * A field for a one-time or verification code. One real `<input>` holds
+ * the code, so autofill from a message, paste, the numeric keyboard, form
+ * posting by `name` and a single accessible name all work as on `Input`;
+ * the boxes are drawn under it and hidden from assistive technology.
+ * Other attributes (`autocomplete`, `inputmode`, `data-*`, ...) land on
+ * the `<input>`.
+ */
+type Props = Omit<HTMLInputAttributes, "class" | "size" | "value" | "type" | "id" | "name" | "required" | "disabled" | "readonly" | "maxlength" | "oninput" | "onblur" | "aria-label" | "aria-describedby"> & {
+    /** Omit to auto-generate. */
+    id?: string;
+    /** The code typed so far. Bindable. */
+    value?: string;
+    /** The name the code is posted under, with or without scripts. */
+    name?: string;
+    class?: string;
+    /** Places in the code. A whole number from 1 to 12. */
+    length?: number;
+    /** `numeric` (default): digits only. `alphanumeric` also takes letters. */
+    mode?: CodeFieldMode;
+    /** Box size: `sm` (44px tall, a compact row), `md` (default), `lg`. */
+    size?: SizeVariant;
+    /**
+     * Draws the boxes in groups with a wider gap between them: a number is
+     * the size of each group (`4` makes 4 and 4 of 8), a list gives each
+     * group's size. Only the drawing changes: one input, one value, and a
+     * paste with spaces or dashes still fills it. A row that cannot fit at
+     * large text or a narrow width wraps between groups.
+     */
+    groups?: number | number[];
+    /** Names the field. Defaults to the provider's `codeField.label`, then "Verification code". */
+    label?: string;
+    /** Keeps the label for assistive technology and takes it off the screen. */
+    labelHidden?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    readonly?: boolean;
+    variant?: SemanticVariant;
+    /** Status text under the field. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+    message?: string;
+    /** Help text under the field, read out with it. */
+    hint?: string;
+    /** An error under the field. It marks the field invalid and is announced; it wins over `variant` and `message`. */
+    error?: string;
+    /** Called with the code when the last place is filled by typing, pasting or autofill. It does not submit anything. */
+    oncomplete?: (value: string) => void;
+    /** Overrides for the built-in strings: label, description. */
+    strings?: Partial<CodeFieldStrings>;
+    oninput?: (event: Event) => void;
+    onblur?: (event: Event) => void;
+    "aria-label"?: string;
+    /** Ids of other elements that describe the field. The length, the hint and the message are added after them. */
+    "aria-describedby"?: string | null;
+};
+declare const CodeField: import("svelte").Component<Props, {}, "value">;
+type CodeField = ReturnType<typeof CodeField>;
+export default CodeField;