zabi-components 7.0.2 → 8.1.0

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

@@ -1,4 +1,23 @@
-interface Props {
+import type { HTMLButtonAttributes } from "svelte/elements";
+import { type SelectPresentation, type SelectStrings } from "../util/select.js";
+/**
+ * Other attributes (`data-*`, `aria-*`, `onfocus`, ...) land on the
+ * trigger, which is a `<button>`: it is the control that takes focus and
+ * that the label names.
+ *
+ * The server's HTML also carries a native `<select>` with the same
+ * options. Until the component has mounted, and for good where there are
+ * no scripts, that is the control: it is what is seen, pressed and
+ * submitted. Once mounted the trigger and the list take over, and the
+ * native select stays, out of sight and out of reach, as the form control
+ * (`name`, `required`), kept at the same value. With
+ * `presentation="native"` it is the control throughout.
+ */
+type Props = Omit<HTMLButtonAttributes, "class" | "value" | "name" | "disabled" | "type" | "onchange" | "onclick" | "aria-describedby" | "children"> & {
+    /** Extra classes for the host element. */
+    class?: string;
+    /** Id of the trigger. Omit to auto-generate. */
+    id?: string;
     value?: string | number | undefined;
     options?: Array<{
         value: string | number;
@@ -6,9 +25,26 @@ interface Props {
         disabled?: boolean;
     }>;
     searchable?: boolean;
+    /**
+     * The component's own texts, for another language. Whatever is left
+     * out keeps its English default. The six older props for single texts
+     * (`placeholder`, `searchPlaceholder`, `noResultsText`,
+     * `loadingText`, `emptyStateTitle`, `emptyStateDescription`) win
+     * over it.
+     */
+    strings?: Partial<SelectStrings>;
     searchPlaceholder?: string;
     maxMenuHeight?: string;
     menuWidth?: string;
+    /**
+     * How the list is shown. `auto`: in a BottomSheet on a phone (a touch
+     * screen narrower than 640px), under the trigger everywhere else.
+     * `popover` and `sheet` are always the one or the other. `native`:
+     * only the browser's own `<select>`, styled as the field, with the
+     * platform's picker. It shows the options' labels and nothing else:
+     * no search field, and none of the loading or empty states.
+     */
+    presentation?: SelectPresentation;
     noResultsText?: string;
     isLoading?: boolean;
     loadingText?: string;
@@ -17,14 +53,28 @@ interface Props {
     emptyStateActionLabel?: string;
     placeholder?: string;
     label?: string;
+    /** The name the chosen value is submitted under, by the native `<select>`. */
+    name?: string;
+    /**
+     * The form is not sent while nothing is chosen. Checked by the
+     * browser on the native `<select>`; once mounted, the browser's own
+     * message is shown under the field and focus goes to the trigger.
+     */
     required?: boolean;
     disabled?: boolean;
     size?: "sm" | "md" | "lg";
     variant?: "default" | "success" | "warning" | "error";
+    /** 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;
     onchange?: (event: Event) => void;
     onEmptyStateAction?: () => void;
-}
+    /** Ids of other elements that describe the field. The hint and the message are added after them. */
+    "aria-describedby"?: string | null;
+};
 declare const Select: import("svelte").Component<Props, {}, "value">;
 type Select = ReturnType<typeof Select>;
 export default Select;

package/dist/atoms/SelectionControl.svelte

@@ -1,7 +1,11 @@
 <script lang="ts">
-    import type { Snippet } from "svelte";
+    import { onMount, tick, type Snippet } from "svelte";
+    import type { HTMLInputAttributes } from "svelte/elements";
     import { generateId } from "../util/ssr-safe.js";
+    import { cn } from "../util/cn.js";
+    import { groupBinding } from "../util/hydration.js";
     import {
+        SELECTION_CONTROL_INPUT,
         SELECTION_CONTROL_LABEL_ROW,
         selectionControlRingOverlayClasses,
         selectionControlShellClasses,
@@ -16,7 +20,12 @@
         disabled: boolean;
     };
 
-    interface Props {
+    type Props = Omit<
+        HTMLInputAttributes,
+        "class" | "id" | "name" | "value" | "disabled" | "checked" | "type" | "onchange"
+    > & {
+        /** Extra classes for the host element. */
+        class?: string;
         id?: string;
         type: SelectionControlType;
         shape: SelectionControlShape;
@@ -30,9 +39,10 @@
         onChange?: (event: Event) => void;
         onchange?: (event: Event) => void;
         mark?: Snippet<[SelectionControlMarkProps]>;
-    }
+    };
 
     let {
+        class: className = "",
         id: idProp,
         type,
         shape,
@@ -42,13 +52,24 @@
         disabled = false,
         loading = false,
         defaultChecked = false,
-        checked = $bindable(defaultChecked),
+        checked = $bindable<Exclude<Props["checked"], undefined>>(),
         onChange,
         onchange,
         mark,
         ...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 (checked === undefined) checked = defaultChecked;
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
     /** Call once per mount — `generateId()` in `$derived` would churn ids every tick. */
     const fallbackId = generateId("selection-control");
     const controlId = $derived(idProp ?? fallbackId);
@@ -60,8 +81,50 @@
 
     const controlRingClasses = $derived(selectionControlRingOverlayClasses(shape));
 
+    let input: HTMLInputElement | undefined = $state();
+
+    /**
+     * The input is bound, so a tick made before the page hydrated is kept:
+     * Svelte's binding finds the input changed and hands its state over here
+     * instead of overwriting it (see util/hydration.ts). A form reset arrives
+     * the same way.
+     *
+     * A choice that is adopted like that came without a `change` event that
+     * anything heard, and a parent that only listens (`onchange`, no
+     * `bind:checked`) would never learn of it. So while the component
+     * settles, a change made through the binding is noted, and reported once
+     * with a real `change` event on the input: the callbacks get the event
+     * they always get, and a form around the control hears it too.
+     */
+    let settling = true;
+    let adopted = false;
+
+    function take(next: boolean) {
+        if (next === !!checked) return;
+        checked = next;
+        if (settling) adopted = true;
+    }
+
+    /** What a single radio's group is bound to: its own value while it is checked. */
+    const NOT_CHOSEN = {};
+    const radio = groupBinding<unknown>(
+        () => (checked ? value : NOT_CHOSEN),
+        (chosen) => take(chosen === value),
+        () => take(false),
+    );
+
+    onMount(() => {
+        // The bindings adopt in a microtask of their own, queued before this one.
+        void tick().then(() => {
+            settling = false;
+            if (adopted) input?.dispatchEvent(new Event("change", { bubbles: true }));
+        });
+    });
+
     function handleChange(event: Event) {
         if (isDisabled) return;
+        // A real change is its own report: nothing is left to tell.
+        adopted = false;
         const target = event.target as HTMLInputElement;
         checked = target.checked;
         onChange?.(event);
@@ -69,24 +132,42 @@
     }
 </script>
 
-<div class="flex items-center gap-2">
+<div class={cn("flex items-center gap-2", className)}>
     <label for={controlId} class={labelWrapperClasses}>
         <span class={controlContainerClasses}>
-            <input
-                {type}
-                id={controlId}
-                {name}
-                {value}
-                {checked}
-                disabled={isDisabled}
-                class="sr-only"
-                aria-busy={loading ? "true" : undefined}
-                onchange={handleChange}
-                {...restProps}
-            />
+            <!-- One branch per type: a binding needs a type it can read. -->
+            {#if type === "checkbox"}
+                <input
+                    bind:this={input}
+                    type="checkbox"
+                    id={controlId}
+                    {name}
+                    {value}
+                    bind:checked={() => !!checked, take}
+                    disabled={isDisabled}
+                    class={SELECTION_CONTROL_INPUT}
+                    aria-busy={loading ? "true" : undefined}
+                    onchange={handleChange}
+                    {...restProps}
+                />
+            {:else}
+                <input
+                    bind:this={input}
+                    type="radio"
+                    id={controlId}
+                    {name}
+                    {value}
+                    bind:group={radio.value}
+                    disabled={isDisabled}
+                    class={SELECTION_CONTROL_INPUT}
+                    aria-busy={loading ? "true" : undefined}
+                    onchange={handleChange}
+                    {...restProps}
+                />
+            {/if}
             <span class={controlRingClasses}></span>
             {#if mark}
-                {@render mark({ checked, loading, disabled: isDisabled })}
+                {@render mark({ checked: !!checked, loading, disabled: isDisabled })}
             {/if}
         </span>
         {#if label}

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

@@ -1,4 +1,5 @@
-import type { Snippet } from "svelte";
+import { type Snippet } from "svelte";
+import type { HTMLInputAttributes } from "svelte/elements";
 import { type SelectionControlShape } from "./selection-control.styles";
 type SelectionControlType = "checkbox" | "radio";
 export type SelectionControlMarkProps = {
@@ -6,7 +7,9 @@ export type SelectionControlMarkProps = {
     loading: boolean;
     disabled: boolean;
 };
-interface Props {
+type Props = Omit<HTMLInputAttributes, "class" | "id" | "name" | "value" | "disabled" | "checked" | "type" | "onchange"> & {
+    /** Extra classes for the host element. */
+    class?: string;
     id?: string;
     type: SelectionControlType;
     shape: SelectionControlShape;
@@ -20,7 +23,7 @@ interface Props {
     onChange?: (event: Event) => void;
     onchange?: (event: Event) => void;
     mark?: Snippet<[SelectionControlMarkProps]>;
-}
+};
 declare const SelectionControl: import("svelte").Component<Props, {}, "checked">;
 type SelectionControl = ReturnType<typeof SelectionControl>;
 export default SelectionControl;

package/dist/atoms/Skeleton.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+    import { cn } from "../util/cn.js";
+
     type Variant = "text" | "circle" | "block";
 
     interface Props {
@@ -20,9 +22,9 @@
     }: Props = $props();
 
     const radius: Record<Variant, string> = {
-        text: "rounded-md",
+        text: "rounded-control",
         circle: "rounded-full",
-        block: "rounded-lg",
+        block: "rounded-control",
     };
 
     const defaultShape: Record<Variant, string> = {
@@ -46,7 +48,7 @@
 </script>
 
 <div
-    class="animate-pulse bg-surface-2 {defaultShape[variant]} {radius[variant]} {className}"
+    class={cn("animate-pulse bg-neutral-subtle", defaultShape[variant], radius[variant], className)}
     style={inlineStyle || undefined}
     role="status"
     aria-busy="true"

package/dist/atoms/Slider.svelte

@@ -0,0 +1,309 @@
+<script lang="ts">
+    import type { HTMLInputAttributes } from "svelte/elements";
+    import type { SemanticVariant, SizeVariant } from "../types/variants.js";
+    import { generateId } from "../util/ssr-safe.js";
+    import { cn } from "../util/cn.js";
+
+    /** Other attributes (`data-*`, `aria-*`, `list`, ...) land on the `<input>`. */
+    type Props = Omit<
+        HTMLInputAttributes,
+        "class" | "size" | "type" | "value" | "min" | "max" | "step" | "id"
+    > & {
+        /** Omit to auto-generate; pair with FormField `id` when used inside FormField. */
+        id?: string;
+        /** Current value; supports `bind:value`. Starts at `min` when not given. */
+        value?: number;
+        min?: number;
+        max?: number;
+        step?: number;
+        name?: string;
+        /** Extra classes for the host element. */
+        class?: string;
+        label?: string;
+        /** True when FormField supplies the visible `<label>`. */
+        hideLabel?: boolean;
+        disabled?: boolean;
+        /** Height of the row, on the scale Input and Button use. */
+        size?: SizeVariant;
+        /** Colours the message; `error` also marks the input invalid. */
+        variant?: SemanticVariant;
+        /** Helper or error text below the slider. */
+        message?: string;
+        /** Shows the current value beside the label. */
+        showValue?: boolean;
+        /**
+         * Turns the value into text ("40 %", "2 h"). It is what `showValue`
+         * shows, and what assistive technology reads instead of the bare
+         * number.
+         */
+        formatValue?: (value: number) => string;
+        /** Native `input` event: fires while the thumb moves. */
+        oninput?: (event: Event) => void;
+        /** Native `change` event: fires when the thumb is released. */
+        onchange?: (event: Event) => void;
+    };
+
+    let {
+        id: idProp,
+        min = 0,
+        max = 100,
+        step = 1,
+        value = $bindable<Exclude<Props["value"], undefined>>(),
+        name = "",
+        class: className = "",
+        label = "",
+        hideLabel = false,
+        disabled = false,
+        size = "md",
+        variant = "default",
+        message = "",
+        showValue = false,
+        formatValue,
+        oninput,
+        onchange,
+        ...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 (value === undefined) value = min;
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
+    const fallbackId = generateId("slider");
+    const inputId = $derived(idProp ?? fallbackId);
+
+    /**
+     * Row heights on the shared control scale (32 / 40 / 48), so a slider
+     * lines up with an Input or a Button of the same size beside it. The
+     * `<input>` itself is 44px tall in the two smaller rows, pulled back in
+     * with a negative margin: the whole input takes the pointer, so that is
+     * the touch target, and the row does not grow for it.
+     */
+    const sizeClass = $derived.by(() => {
+        if (size === "sm") return { box: "h-8 pointer-coarse:min-h-11", input: "h-11 -my-1.5" };
+        if (size === "lg") return { box: "h-12", input: "h-12" };
+        return { box: "h-10 pointer-coarse:min-h-11", input: "h-11 -my-0.5" };
+    });
+
+    /** Where the thumb sits, 0 to 1; drives the filled part of the track. */
+    const ratio = $derived.by(() => {
+        if (!(max > min)) return 0;
+        return Math.max(0, Math.min(1, (value - min) / (max - min)));
+    });
+
+    const valueText = $derived(formatValue ? formatValue(value) : String(value));
+    const labelVisible = $derived(!!label && !hideLabel);
+
+    // The `-text` step clears 4.5:1 on a page surface, as in Input.
+    const messageClasses = $derived.by(() => {
+        const base = "text-sm mt-2";
+        if (variant === "error") return `text-error-text ${base}`;
+        if (variant === "success") return `text-success-text ${base}`;
+        if (variant === "warning") return `text-warning-text ${base}`;
+        return `text-description ${base}`;
+    });
+</script>
+
+{#snippet valueOutput()}
+    <output
+        for={inputId}
+        class={cn(
+            "shrink-0 text-sm tabular-nums",
+            disabled ? "text-action-disabled-text" : "text-description",
+        )}
+        data-slider-value
+    >
+        {valueText}
+    </output>
+{/snippet}
+
+<div class={cn(className)}>
+    {#if labelVisible}
+        <div class="mb-2 flex items-baseline justify-between gap-3">
+            <label for={inputId} class="block text-sm font-medium text-label">{label}</label>
+            {#if showValue}
+                {@render valueOutput()}
+            {/if}
+        </div>
+    {/if}
+    <div class={cn("flex items-center gap-3", sizeClass.box)}>
+        <!-- A native range input: keyboard, touch, right-to-left and form
+        submission come with it. Only its looks are replaced, below. -->
+        <input
+            type="range"
+            id={inputId}
+            class={cn("slider min-w-0 flex-1", sizeClass.input)}
+            style:--zabi-slider-ratio={ratio}
+            data-size={size}
+            bind:value
+            {min}
+            {max}
+            {step}
+            name={name || undefined}
+            {disabled}
+            {oninput}
+            {onchange}
+            aria-valuetext={formatValue ? valueText : undefined}
+            aria-invalid={variant === "error" ? "true" : undefined}
+            aria-describedby={message ? `${inputId}-message` : undefined}
+            {...restProps}
+        />
+        {#if showValue && !labelVisible}
+            {@render valueOutput()}
+        {/if}
+    </div>
+    {#if message}
+        <p
+            id={`${inputId}-message`}
+            class={messageClasses}
+            role={variant === "error" ? "alert" : undefined}
+        >
+            {message}
+        </p>
+    {/if}
+</div>
+
+<style>
+    /*
+     * The parts of a range input are vendor pseudo-elements, which utilities
+     * cannot reach without an arbitrary variant per declaration. WebKit/Blink
+     * and Gecko each get their own rules: one unknown pseudo-element in a
+     * selector list drops the whole rule.
+     */
+    .slider {
+        --zabi-slider-thumb: 1.25rem;
+        --zabi-slider-track: 0.375rem;
+        --zabi-slider-fill: var(--color-action-primary);
+        --zabi-slider-rest: var(--color-control-track);
+        --zabi-slider-halo: 0 0 0 0 transparent;
+        /* The fill ends under the centre of the thumb, which travels less
+           than the full width. */
+        --zabi-slider-stop: calc(
+            var(--zabi-slider-ratio, 0) * (100% - var(--zabi-slider-thumb)) +
+                var(--zabi-slider-thumb) / 2
+        );
+        -webkit-appearance: none;
+        -moz-appearance: none;
+             appearance: none;
+        background: transparent;
+        cursor: pointer;
+        outline: none;
+        /* A touch that starts on the slider moves the thumb; vertical scrolling stays with the page. */
+        touch-action: pan-y;
+    }
+
+    .slider[data-size="sm"] {
+        --zabi-slider-thumb: 1rem;
+        --zabi-slider-track: 0.25rem;
+    }
+
+    .slider[data-size="lg"] {
+        --zabi-slider-thumb: 1.5rem;
+        --zabi-slider-track: 0.5rem;
+    }
+
+    /* Only where a pointer can hover: after a tap, `:hover` stays on the slider until the next tap elsewhere. */
+    @media (hover: hover) {
+        .slider:hover {
+            --zabi-slider-fill: var(--color-action-primary-hover);
+            --zabi-slider-rest: var(--color-control-track-hover);
+            --zabi-slider-halo: 0 0 0 4px var(--color-surface-hover);
+        }
+    }
+
+    .slider:active {
+        --zabi-slider-fill: var(--color-action-primary-active);
+        --zabi-slider-rest: var(--color-control-track-active);
+        --zabi-slider-halo: 0 0 0 6px var(--color-surface-active);
+    }
+
+    /* Same geometry as `.focus-ring`: a 2px gap, then a 2px ring, on the thumb. */
+    .slider:focus-visible {
+        --zabi-slider-halo:
+            0 0 0 2px var(--color-focus-ring-offset), 0 0 0 4px var(--color-focus-ring);
+    }
+
+    .slider:disabled {
+        --zabi-slider-fill: var(--color-action-disabled-text);
+        --zabi-slider-rest: var(--color-action-disabled);
+        --zabi-slider-halo: 0 0 0 0 transparent;
+        cursor: not-allowed;
+    }
+
+    /* WebKit and Blink: one track, painted in two parts. */
+    .slider::-webkit-slider-runnable-track {
+        height: var(--zabi-slider-track);
+        border-radius: 9999px;
+        background: linear-gradient(
+            to right,
+            var(--zabi-slider-fill) 0 var(--zabi-slider-stop),
+            var(--zabi-slider-rest) var(--zabi-slider-stop) 100%
+        );
+    }
+
+    .slider:dir(rtl)::-webkit-slider-runnable-track {
+        background: linear-gradient(
+            to left,
+            var(--zabi-slider-fill) 0 var(--zabi-slider-stop),
+            var(--zabi-slider-rest) var(--zabi-slider-stop) 100%
+        );
+    }
+
+    .slider::-webkit-slider-thumb {
+        -webkit-appearance: none;
+        appearance: none;
+        box-sizing: border-box;
+        width: var(--zabi-slider-thumb);
+        height: var(--zabi-slider-thumb);
+        margin-top: calc((var(--zabi-slider-track) - var(--zabi-slider-thumb)) / 2);
+        border: 2px solid var(--zabi-slider-fill);
+        border-radius: 9999px;
+        background: var(--color-card);
+        box-shadow: var(--zabi-slider-halo);
+        -webkit-transition: box-shadow 150ms;
+        transition: box-shadow 150ms;
+    }
+
+    /* Gecko: the filled part is its own pseudo-element and follows the direction. */
+    .slider::-moz-range-track {
+        height: var(--zabi-slider-track);
+        border-radius: 9999px;
+        background: var(--zabi-slider-rest);
+    }
+
+    .slider::-moz-range-progress {
+        height: var(--zabi-slider-track);
+        border-radius: 9999px;
+        background: var(--zabi-slider-fill);
+    }
+
+    .slider::-moz-range-thumb {
+        box-sizing: border-box;
+        width: var(--zabi-slider-thumb);
+        height: var(--zabi-slider-thumb);
+        border: 2px solid var(--zabi-slider-fill);
+        border-radius: 9999px;
+        background: var(--color-card);
+        box-shadow: var(--zabi-slider-halo);
+        -moz-transition: box-shadow 150ms;
+        transition: box-shadow 150ms;
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .slider::-webkit-slider-thumb {
+            -webkit-transition: none;
+            transition: none;
+        }
+
+        .slider::-moz-range-thumb {
+            -moz-transition: none;
+            transition: none;
+        }
+    }
+</style>

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

@@ -0,0 +1,40 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { SemanticVariant, SizeVariant } from "../types/variants.js";
+/** Other attributes (`data-*`, `aria-*`, `list`, ...) land on the `<input>`. */
+type Props = Omit<HTMLInputAttributes, "class" | "size" | "type" | "value" | "min" | "max" | "step" | "id"> & {
+    /** Omit to auto-generate; pair with FormField `id` when used inside FormField. */
+    id?: string;
+    /** Current value; supports `bind:value`. Starts at `min` when not given. */
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    name?: string;
+    /** Extra classes for the host element. */
+    class?: string;
+    label?: string;
+    /** True when FormField supplies the visible `<label>`. */
+    hideLabel?: boolean;
+    disabled?: boolean;
+    /** Height of the row, on the scale Input and Button use. */
+    size?: SizeVariant;
+    /** Colours the message; `error` also marks the input invalid. */
+    variant?: SemanticVariant;
+    /** Helper or error text below the slider. */
+    message?: string;
+    /** Shows the current value beside the label. */
+    showValue?: boolean;
+    /**
+     * Turns the value into text ("40 %", "2 h"). It is what `showValue`
+     * shows, and what assistive technology reads instead of the bare
+     * number.
+     */
+    formatValue?: (value: number) => string;
+    /** Native `input` event: fires while the thumb moves. */
+    oninput?: (event: Event) => void;
+    /** Native `change` event: fires when the thumb is released. */
+    onchange?: (event: Event) => void;
+};
+declare const Slider: import("svelte").Component<Props, {}, "value">;
+type Slider = ReturnType<typeof Slider>;
+export default Slider;