zabi-components 8.0.0 → 9.0.0

package/dist/atoms/PickerField.svelte

@@ -0,0 +1,239 @@
+<script lang="ts">
+    import ChevronDown from "@lucide/svelte/icons/chevron-down";
+    import type { Snippet } from "svelte";
+    import type { HTMLAnchorAttributes, HTMLButtonAttributes } from "svelte/elements";
+    import { cn } from "../util/cn.js";
+    import { fieldDescribedBy, fieldMessageState } from "../util/field.js";
+    import { FIELD_CONTROL_TRIGGER, fieldControlEdge, fieldControlSize } from "../util/field-control.js";
+    import { generateId } from "../util/ssr-safe.js";
+    import FieldMessages from "./FieldMessages.svelte";
+
+    /**
+     * A field-shaped trigger that opens whatever the app gives it, usually its
+     * own BottomSheet: the app owns the list, the search and the value. It
+     * looks like a Select of the same `size` and is one control: a `<button>`
+     * (a link with `href`) named by its label and its current value.
+     *
+     * Other attributes (`data-*`, `aria-*`, `onfocus`, ...) land on that
+     * element. The component does not open anything: `onclick` does, and the
+     * app sets `expanded` while its sheet is open.
+     */
+    type Props = Omit<
+        HTMLButtonAttributes,
+        | "class"
+        | "value"
+        | "name"
+        | "disabled"
+        | "type"
+        | "onclick"
+        | "aria-describedby"
+        | "aria-haspopup"
+        | "aria-expanded"
+        | "aria-controls"
+        | "children"
+    > & {
+        /** Extra classes for the host element. */
+        class?: string;
+        /** Id of the control. Omit to auto-generate. */
+        id?: string;
+        /** The label above the field. It is part of the control's name. */
+        label?: string;
+        /** The text of what is chosen. It is display text; `formValue` is what a form sends. */
+        value?: string;
+        /** Shown in the placeholder colour while there is no `value`. */
+        placeholder?: string;
+        /** An icon or an avatar before the text. */
+        leading?: Snippet;
+        /** Replaces the chevron at the end: a calendar or a clock, say. It is decoration, so it should be `aria-hidden`. */
+        trailing?: Snippet;
+        /** Replaces the value text, for rich content. The control is still named by `value`, so give that too. */
+        children?: Snippet;
+        size?: "sm" | "md" | "lg";
+        disabled?: boolean;
+        /** Status text under the field. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+        message?: string;
+        variant?: "default" | "success" | "warning" | "error";
+        /** Help text under the field, read out with it. */
+        hint?: string;
+        /**
+         * An error under the field, announced. A button cannot take
+         * `aria-invalid`, so the error is the error edge colour and the
+         * described-by message; it wins over `variant` and `message`.
+         */
+        error?: string;
+        /** What the control opens: `aria-haspopup`. Default `"dialog"`. Not put on a link. */
+        haspopup?: "dialog" | "listbox" | "menu" | "true";
+        /** Whether what it opens is open now: `aria-expanded`, and the chevron turns. Leave it out and neither is set. Not put on a link. */
+        expanded?: boolean;
+        /** Id of what it opens: `aria-controls`. */
+        controls?: string;
+        /** Makes the control a link to this address, which works without scripts: a page that does the picking. With scripts, `onclick` may call `preventDefault()` and open a sheet instead. */
+        href?: string;
+        /** With `href`: where the link opens. */
+        target?: HTMLAnchorAttributes["target"];
+        /** With `href`: the link's relationship, such as `noopener`. */
+        rel?: HTMLAnchorAttributes["rel"];
+        /** The name a hidden input submits `formValue` under. Without it there is no hidden input. */
+        name?: string;
+        /** What the form submits for the choice, such as an id. */
+        formValue?: string;
+        /** The inner `<button>` (or `<a>`). Bindable: the app focuses it when its sheet closes, so a keyboard user is back where they were. */
+        element?: HTMLButtonElement | HTMLAnchorElement | null;
+        /** Ids of other elements that describe the field. The hint and the message are added after them. */
+        "aria-describedby"?: string | null;
+        onclick?: (event: MouseEvent) => void;
+    };
+
+    let {
+        class: className = "",
+        id: idProp,
+        label = "",
+        value = "",
+        placeholder = "",
+        leading,
+        trailing,
+        children,
+        size = "md",
+        disabled = false,
+        variant = "default",
+        message = "",
+        hint = "",
+        error = "",
+        haspopup = "dialog",
+        expanded,
+        controls,
+        href,
+        target,
+        rel,
+        name = "",
+        formValue = "",
+        element = $bindable(),
+        "aria-describedby": describedBy,
+        onclick,
+        ...restProps
+    }: Props = $props();
+
+    const fallbackId = generateId("picker-field");
+    const fieldId = $derived(idProp ?? fallbackId);
+    const labelId = $derived(`${fieldId}-label`);
+    const valueId = $derived(`${fieldId}-value`);
+
+    const isLink = $derived(href !== undefined && href !== null);
+    const status = $derived(fieldMessageState({ variant, message, hint, error }));
+    const isEmpty = $derived(value === "");
+    const sizeClass = $derived(fieldControlSize(size));
+
+    const controlClasses = $derived(
+        cn(
+            FIELD_CONTROL_TRIGGER,
+            sizeClass.box,
+            sizeClass.text,
+            fieldControlEdge(status.variant),
+            // `disabled:` does not match an `<a>`: a disabled link wears the pair itself.
+            isLink && disabled && "cursor-not-allowed border-input-border bg-input-disabled text-action-disabled-text hover:bg-input-disabled active:bg-input-disabled",
+        ),
+    );
+
+    /**
+     * The name is the label and the value (the placeholder while there is
+     * none), as a Select's is. Without a label the content names it. A
+     * caller's own `aria-label` or `aria-labelledby` wins.
+     */
+    const labelledBy = $derived(label ? `${labelId} ${valueId}` : undefined);
+
+    /** A disabled link has no `href`, but a pointer can still press it. */
+    function handleLinkClick(event: MouseEvent) {
+        if (disabled) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        onclick?.(event);
+    }
+</script>
+
+{#snippet content()}
+    {#if leading}
+        <span class="flex shrink-0 items-center" data-picker-field-leading>{@render leading()}</span>
+    {/if}
+    <!-- A value has no colour class of its own, and a disabled control none
+    at all: the control's `text-body` and its disabled colour are inherited
+    (a colour class here beat the disabled one in Select). -->
+    <span
+        id={valueId}
+        class={cn("min-w-0 flex-1 truncate text-start", isEmpty && !disabled && !children && "text-input-placeholder")}
+    >
+        {#if children}
+            {@render children()}
+        {:else}
+            {isEmpty ? placeholder : value}
+        {/if}
+    </span>
+    {#if trailing}
+        <span class="flex shrink-0 items-center text-description" data-picker-field-trailing>{@render trailing()}</span>
+    {:else}
+        <ChevronDown
+            size={20}
+            class={cn(
+                "shrink-0 text-description transition-transform duration-(--duration-moderate) motion-reduce:transition-none",
+                expanded && "rotate-180",
+            )}
+            aria-hidden="true"
+        />
+    {/if}
+{/snippet}
+
+<div class={cn("w-full min-w-0", className)}>
+    {#if label}
+        {#if isLink}
+            <!-- A link cannot be a label's control. -->
+            <span id={labelId} class="mb-2 block text-sm font-medium text-label">{label}</span>
+        {:else}
+            <label id={labelId} for={fieldId} class="mb-2 block text-sm font-medium text-label">{label}</label>
+        {/if}
+    {/if}
+
+    {#if isLink}
+        <!-- With `href` the control is a link with its role left native, and
+        no `aria-haspopup` or `aria-expanded`: it goes to a page. Disabled, it
+        has no `href` and says it is unavailable, as a disabled Button link. -->
+        <a
+            bind:this={element}
+            id={fieldId}
+            href={disabled ? undefined : href}
+            {target}
+            {rel}
+            class={controlClasses}
+            role={disabled ? "link" : undefined}
+            aria-disabled={disabled ? "true" : undefined}
+            aria-labelledby={labelledBy}
+            aria-describedby={fieldDescribedBy(fieldId, status, describedBy)}
+            {...(restProps as unknown as HTMLAnchorAttributes)}
+            onclick={handleLinkClick}
+        >
+            {@render content()}
+        </a>
+    {:else}
+        <button
+            bind:this={element}
+            type="button"
+            id={fieldId}
+            {disabled}
+            class={controlClasses}
+            aria-haspopup={haspopup}
+            aria-expanded={expanded}
+            aria-controls={controls}
+            aria-labelledby={labelledBy}
+            aria-describedby={fieldDescribedBy(fieldId, status, describedBy)}
+            {...restProps}
+            {onclick}
+        >
+            {@render content()}
+        </button>
+    {/if}
+
+    {#if name}
+        <input type="hidden" {name} value={formValue} {disabled} />
+    {/if}
+    <FieldMessages {fieldId} {status} {hint} gap="mt-1" messageClass="w-full" />
+</div>

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

@@ -0,0 +1,67 @@
+import type { Snippet } from "svelte";
+import type { HTMLAnchorAttributes, HTMLButtonAttributes } from "svelte/elements";
+/**
+ * A field-shaped trigger that opens whatever the app gives it, usually its
+ * own BottomSheet: the app owns the list, the search and the value. It
+ * looks like a Select of the same `size` and is one control: a `<button>`
+ * (a link with `href`) named by its label and its current value.
+ *
+ * Other attributes (`data-*`, `aria-*`, `onfocus`, ...) land on that
+ * element. The component does not open anything: `onclick` does, and the
+ * app sets `expanded` while its sheet is open.
+ */
+type Props = Omit<HTMLButtonAttributes, "class" | "value" | "name" | "disabled" | "type" | "onclick" | "aria-describedby" | "aria-haspopup" | "aria-expanded" | "aria-controls" | "children"> & {
+    /** Extra classes for the host element. */
+    class?: string;
+    /** Id of the control. Omit to auto-generate. */
+    id?: string;
+    /** The label above the field. It is part of the control's name. */
+    label?: string;
+    /** The text of what is chosen. It is display text; `formValue` is what a form sends. */
+    value?: string;
+    /** Shown in the placeholder colour while there is no `value`. */
+    placeholder?: string;
+    /** An icon or an avatar before the text. */
+    leading?: Snippet;
+    /** Replaces the chevron at the end: a calendar or a clock, say. It is decoration, so it should be `aria-hidden`. */
+    trailing?: Snippet;
+    /** Replaces the value text, for rich content. The control is still named by `value`, so give that too. */
+    children?: Snippet;
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    /** Status text under the field. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+    message?: string;
+    variant?: "default" | "success" | "warning" | "error";
+    /** Help text under the field, read out with it. */
+    hint?: string;
+    /**
+     * An error under the field, announced. A button cannot take
+     * `aria-invalid`, so the error is the error edge colour and the
+     * described-by message; it wins over `variant` and `message`.
+     */
+    error?: string;
+    /** What the control opens: `aria-haspopup`. Default `"dialog"`. Not put on a link. */
+    haspopup?: "dialog" | "listbox" | "menu" | "true";
+    /** Whether what it opens is open now: `aria-expanded`, and the chevron turns. Leave it out and neither is set. Not put on a link. */
+    expanded?: boolean;
+    /** Id of what it opens: `aria-controls`. */
+    controls?: string;
+    /** Makes the control a link to this address, which works without scripts: a page that does the picking. With scripts, `onclick` may call `preventDefault()` and open a sheet instead. */
+    href?: string;
+    /** With `href`: where the link opens. */
+    target?: HTMLAnchorAttributes["target"];
+    /** With `href`: the link's relationship, such as `noopener`. */
+    rel?: HTMLAnchorAttributes["rel"];
+    /** The name a hidden input submits `formValue` under. Without it there is no hidden input. */
+    name?: string;
+    /** What the form submits for the choice, such as an id. */
+    formValue?: string;
+    /** The inner `<button>` (or `<a>`). Bindable: the app focuses it when its sheet closes, so a keyboard user is back where they were. */
+    element?: HTMLButtonElement | HTMLAnchorElement | null;
+    /** Ids of other elements that describe the field. The hint and the message are added after them. */
+    "aria-describedby"?: string | null;
+    onclick?: (event: MouseEvent) => void;
+};
+declare const PickerField: import("svelte").Component<Props, {}, "element">;
+type PickerField = ReturnType<typeof PickerField>;
+export default PickerField;

package/dist/atoms/Progress.svelte

@@ -1,13 +1,35 @@
 <script lang="ts">
+    import { isDevBuild } from "../util/app-shell.js";
+    import {
+        PROGRESS_STRINGS,
+        canSegment,
+        filledSegments,
+        type ProgressStrings,
+    } from "../util/progress.js";
+    import { mergeStrings } from "../util/ready-made-strings.js";
     import { generateId } from "../util/ssr-safe.js";
+    import { zabiStringsFor } from "../util/zabi-strings.js";
 
     interface Props {
         /** Extra classes for the host element. */
         class?: string;
         value?: number;
         max?: number;
-        size?: "sm" | "md" | "lg";
+        /** Height of the bar: 4, 8, 12 and 16px. */
+        size?: "sm" | "md" | "lg" | "xl";
+        /**
+         * Draws `max` separate segments, `value` of them filled, for a count
+         * such as 4 of 19. `max` must be a whole number from 2 to 24; any
+         * other `max` draws the continuous bar.
+         */
+        segmented?: boolean;
+        /** Overrides for the built-in strings. */
+        strings?: Partial<ProgressStrings>;
         label?: string;
+        /** Names the progressbar when there is no visible `label`. Reaches the element with role="progressbar". */
+        "aria-label"?: string;
+        /** Points the progressbar at another element's id for its name. Reaches the element with role="progressbar". */
+        "aria-labelledby"?: string;
     }
 
     let {
@@ -15,43 +37,101 @@
         value = 0,
         max = 100,
         size = "md",
+        segmented = false,
+        strings,
         label = "",
+        "aria-label": ariaLabel,
+        "aria-labelledby": ariaLabelledby,
         ...restProps
     }: Props = $props();
 
     const progressId = generateId("progress");
+    const labelId = `${progressId}-label`;
 
-    let percentage = $derived(Math.min(Math.max((value / max) * 100, 0), 100));
+    // A max that is not a positive, finite number would give an empty or full
+    // bar with aria-valuemax=0: fall back to the default.
+    let safeMax = $derived(Number.isFinite(max) && max > 0 ? max : 100);
+    let safeValue = $derived(
+        Number.isFinite(value) ? Math.min(Math.max(value, 0), safeMax) : 0,
+    );
+    let percentage = $derived((safeValue / safeMax) * 100);
+    let labelledby = $derived(
+        ariaLabelledby ?? (ariaLabel || !label ? undefined : labelId),
+    );
 
-    let sizeClasses = $derived({
+    const sizeClasses = {
         sm: "h-1",
         md: "h-2",
         lg: "h-3",
+        xl: "h-4",
+    };
+
+    /** The app-wide words for this component, from a `ZabiStringsProvider` above it, if there is one. */
+    const provided = zabiStringsFor("progress");
+    const text = $derived(mergeStrings(PROGRESS_STRINGS, provided(), strings));
+
+    /** Segmented only where `max` can be drawn as segments; otherwise the continuous bar. */
+    let asSegments = $derived(segmented && canSegment(max));
+    let filled = $derived(filledSegments(value, safeMax));
+    let valueText = $derived(asSegments ? text.valueText(filled, safeMax) : undefined);
+
+    $effect(() => {
+        if (!isDevBuild() || !segmented || canSegment(max)) return;
+        console.warn(
+            "[zabi-components] Progress: `segmented` needs a whole-number `max` from 2 to 24; drawing the continuous bar instead.",
+        );
     });
 </script>
 
 <div class={className} {...restProps}>
     {#if label}
         <div class="flex justify-between items-center mb-2">
-            <label for={progressId} class="text-sm font-medium text-label"
-                >{label}</label
+            <!-- A span named through aria-labelledby, not a label: `for` only
+            names form controls, so it left the progressbar without a name. -->
+            <span id={labelId} class="text-sm font-medium text-label"
+                >{label}</span
             >
-            <span class="text-sm text-caption">{Math.round(percentage)}%</span>
+            <span class="text-sm text-caption">{asSegments ? valueText : `${Math.round(percentage)}%`}</span>
         </div>
     {/if}
 
-    <div
-        id={progressId}
-        class="w-full border border-input-border bg-input rounded-full overflow-hidden {sizeClasses[size]}"
-        role="progressbar"
-        aria-valuenow={value}
-        aria-valuemin="0"
-        aria-valuemax={max}
-        {...restProps}
-    >
+    {#if asSegments}
         <div
-            class="h-full bg-brand-600 rounded-full"
-            style="width: {percentage}%"
-        ></div>
-    </div>
+            id={progressId}
+            class="flex w-full {safeMax > 12 ? 'gap-[2px]' : 'gap-1'} {sizeClasses[size]}"
+            role="progressbar"
+            aria-label={ariaLabel}
+            aria-labelledby={labelledby}
+            aria-valuenow={filled}
+            aria-valuemin="0"
+            aria-valuemax={safeMax}
+            aria-valuetext={valueText}
+        >
+            {#each { length: safeMax } as _, index (index)}
+                <!-- Presentational: the count is said once, by the progressbar. -->
+                <span
+                    class="h-full flex-1 min-w-0 rounded-full {index < filled
+                        ? 'bg-progress-fill forced-colors:bg-[Highlight]'
+                        : 'bg-progress-track border border-progress-track-border forced-colors:border-[CanvasText]'}"
+                    aria-hidden="true"
+                ></span>
+            {/each}
+        </div>
+    {:else}
+        <div
+            id={progressId}
+            class="w-full border border-progress-track-border bg-progress-track rounded-full overflow-hidden {sizeClasses[size]}"
+            role="progressbar"
+            aria-label={ariaLabel}
+            aria-labelledby={labelledby}
+            aria-valuenow={safeValue}
+            aria-valuemin="0"
+            aria-valuemax={safeMax}
+        >
+            <div
+                class="h-full bg-progress-fill rounded-full"
+                style="width: {percentage}%"
+            ></div>
+        </div>
+    {/if}
 </div>

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

@@ -1,10 +1,24 @@
+import { type ProgressStrings } from "../util/progress.js";
 interface Props {
     /** Extra classes for the host element. */
     class?: string;
     value?: number;
     max?: number;
-    size?: "sm" | "md" | "lg";
+    /** Height of the bar: 4, 8, 12 and 16px. */
+    size?: "sm" | "md" | "lg" | "xl";
+    /**
+     * Draws `max` separate segments, `value` of them filled, for a count
+     * such as 4 of 19. `max` must be a whole number from 2 to 24; any
+     * other `max` draws the continuous bar.
+     */
+    segmented?: boolean;
+    /** Overrides for the built-in strings. */
+    strings?: Partial<ProgressStrings>;
     label?: string;
+    /** Names the progressbar when there is no visible `label`. Reaches the element with role="progressbar". */
+    "aria-label"?: string;
+    /** Points the progressbar at another element's id for its name. Reaches the element with role="progressbar". */
+    "aria-labelledby"?: string;
 }
 declare const Progress: import("svelte").Component<Props, {}, "">;
 type Progress = ReturnType<typeof Progress>;

package/dist/atoms/Radio.svelte

@@ -1,9 +1,16 @@
 <script lang="ts">
+    import type { Snippet } from "svelte";
+    import type { HTMLInputAttributes } from "svelte/elements";
+    import type { SemanticVariant } from "../types/variants.js";
     import SelectionControl from "./SelectionControl.svelte";
     import type { SelectionControlMarkProps } from "./SelectionControl.svelte";
     import { RADIO_CHECKED_DOT_CLASSES } from "./selection-control.styles";
 
-    interface Props {
+    /** Other attributes (`required`, `data-*`, `aria-*`, ...) land on the `<input>`. */
+    type Props = Omit<
+        HTMLInputAttributes,
+        "class" | "id" | "name" | "value" | "disabled" | "checked" | "type" | "onchange"
+    > & {
         /** Extra classes for the host element. */
         class?: string;
         id?: string;
@@ -15,7 +22,31 @@
         checked?: boolean;
         onChange?: (event: Event) => void;
         onchange?: (event: Event) => void;
-    }
+        /**
+         * Drawn inside the one label, between the box and the label text, as
+         * decoration for the name `label` already gives. A leading image
+         * should have an empty alt: the label names the row.
+         */
+        leading?: Snippet;
+        /**
+         * A line under the label, tied to the radio with `aria-describedby`.
+         * The label names the radio; the description does not join the name.
+         */
+        description?: string;
+        /**
+         * Where the radio sits in the row. `end` puts it after the leading,
+         * the label and the description, at the far edge; the row is still
+         * one label and fills the width it is given.
+         */
+        controlPosition?: "start" | "end";
+        variant?: SemanticVariant;
+        /** Status text under the control. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+        message?: string;
+        /** Help text under the control, read out with it. */
+        hint?: string;
+        /** An error under the control. It marks the input invalid and is announced; it wins over `variant` and `message`. */
+        error?: string;
+    };
 
     let {
         class: className = "",
@@ -25,11 +56,25 @@
         label = "",
         disabled = false,
         defaultChecked = false,
-        checked = $bindable(defaultChecked),
+        checked = $bindable<Exclude<Props["checked"], undefined>>(),
         onChange,
         onchange,
+        leading,
+        description,
+        controlPosition = "start",
         ...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);
 </script>
 
 {#snippet mark(_props: SelectionControlMarkProps)}
@@ -49,6 +94,9 @@
     {onChange}
     {onchange}
     {mark}
+    {leading}
+    {description}
+    {controlPosition}
     class={className}
     {...restProps}
 />

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

@@ -1,4 +1,8 @@
-interface Props {
+import type { Snippet } from "svelte";
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { SemanticVariant } from "../types/variants.js";
+/** Other attributes (`required`, `data-*`, `aria-*`, ...) land on the `<input>`. */
+type Props = Omit<HTMLInputAttributes, "class" | "id" | "name" | "value" | "disabled" | "checked" | "type" | "onchange"> & {
     /** Extra classes for the host element. */
     class?: string;
     id?: string;
@@ -10,7 +14,31 @@ interface Props {
     checked?: boolean;
     onChange?: (event: Event) => void;
     onchange?: (event: Event) => void;
-}
+    /**
+     * Drawn inside the one label, between the box and the label text, as
+     * decoration for the name `label` already gives. A leading image
+     * should have an empty alt: the label names the row.
+     */
+    leading?: Snippet;
+    /**
+     * A line under the label, tied to the radio with `aria-describedby`.
+     * The label names the radio; the description does not join the name.
+     */
+    description?: string;
+    /**
+     * Where the radio sits in the row. `end` puts it after the leading,
+     * the label and the description, at the far edge; the row is still
+     * one label and fills the width it is given.
+     */
+    controlPosition?: "start" | "end";
+    variant?: SemanticVariant;
+    /** Status text under the control. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+    message?: string;
+    /** Help text under the control, read out with it. */
+    hint?: string;
+    /** An error under the control. It marks the input invalid and is announced; it wins over `variant` and `message`. */
+    error?: string;
+};
 declare const Radio: import("svelte").Component<Props, {}, "checked">;
 type Radio = ReturnType<typeof Radio>;
 export default Radio;