zabi-components 7.0.2 → 8.1.0

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

@@ -0,0 +1,56 @@
+import type { HTMLAttributes } from "svelte/elements";
+import { type Photo, type PhotoViewerAction, type PhotoViewerCloseReason, type PhotoViewerStrings } from "../util/photo.js";
+/**
+ * Photos one at a time, on the whole screen: swipe or use the arrows to
+ * go between them, pinch or double tap to look closer, swipe down or
+ * press Escape to leave.
+ *
+ * ```svelte
+ * <PhotoGrid {photos} onopen={(at) => { index = at; open = true; }} />
+ * <PhotoViewer {photos} bind:index bind:isOpen={open} actions={[share, remove]} />
+ * ```
+ *
+ * It is a modal dialog, on the same footing as Modal, Drawer and
+ * BottomSheet. When it closes, focus goes to the tile of the photo that
+ * was showing, if the `PhotoGrid` it was opened from shows it; otherwise
+ * to whatever opened it.
+ *
+ * It is dark in both themes: the photos are on black. Nothing in it is
+ * written on that black: every control, the counter and the caption sit
+ * on plates in the theme's own surface colour, so they read over any
+ * photo in either theme.
+ *
+ * Other attributes (`id`, `data-*`, ...) land on the `role="dialog"` panel.
+ */
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "onclose" | "aria-label"> & {
+    photos: Photo[];
+    /** Place in `photos` of the photo that is showing. Supports `bind:index`. */
+    index?: number;
+    isOpen?: boolean;
+    /**
+     * Things to do with the photo that is showing. Up to three are
+     * buttons in a bar under the photo; with more, two are, and the
+     * rest are in a menu. The viewer does nothing by itself: each action
+     * is your own function.
+     */
+    actions?: PhotoViewerAction[];
+    /**
+     * Render the overlay in `document.body`, so an ancestor with a
+     * transform, filter or clipped overflow cannot trap it; pass `false`
+     * to render in place.
+     */
+    portal?: boolean;
+    /** Fired when the viewer closes itself, with what the user did. */
+    onclose?: (detail: {
+        reason: PhotoViewerCloseReason;
+    }) => void;
+    /** Accessible name of the dialog. */
+    label?: string;
+    /** Overrides for the built-in strings. */
+    strings?: Partial<PhotoViewerStrings>;
+    /** Extra classes for the dialog panel. */
+    class?: string;
+};
+declare const PhotoViewer: import("svelte").Component<Props, {}, "index" | "isOpen">;
+type PhotoViewer = ReturnType<typeof PhotoViewer>;
+export default PhotoViewer;

package/dist/molecules/PropsTable.svelte

@@ -1,43 +1,58 @@
 <script lang="ts">
+    import { mergeStrings } from "../util/ready-made-strings.js";
+    import { zabiStringsFor } from "../util/zabi-strings.js";
     import type { ComponentProp } from "../types/page.types";
     import Table from "../atoms/Table.svelte";
+    import { cn } from "../util/cn.js";
+    import {
+        DEFAULT_PROPS_TABLE_STRINGS,
+        type PropsTableStrings,
+    } from "../util/ready-made-strings.js";
 
     interface Props {
+        /** Extra classes for the host element. */
+        class?: string;
         props: ComponentProp[];
         caption?: string;
+        /** The column headings, Yes and No, and the line for an empty table. */
+        strings?: Partial<PropsTableStrings>;
     }
 
-    let { props, caption = "Props / API" }: Props = $props();
+    let { class: className = "", props, caption = "Props / API", strings }: Props = $props();
+
+    /** The app-wide words for this component, from a `ZabiStringsProvider` above it, if there is one. */
+    const provided = zabiStringsFor("propsTable");
+    const text = $derived(mergeStrings(DEFAULT_PROPS_TABLE_STRINGS, provided(), strings));
 </script>
 
 {#if props.length === 0}
-    <div class="rounded-lg border border-border bg-base-50 px-4 py-4 text-sm text-description">
-        No documented props.
+    <div class={cn("rounded-control border border-border bg-card px-4 py-4 text-sm text-description", className)}>
+        {text.empty}
     </div>
 {:else}
     <Table caption={caption}>
         <thead>
-            <tr class="bg-base-50">
+            <tr class="bg-surface-elevated">
                 <th class="border-b border-border px-4 py-3 text-left font-semibold text-headline">
-                    Name
+                    {text.name}
                 </th>
                 <th class="border-b border-border px-4 py-3 text-left font-semibold text-headline">
-                    Type
+                    {text.type}
                 </th>
                 <th class="border-b border-border px-4 py-3 text-left font-semibold text-headline">
-                    Required
+                    {text.required}
                 </th>
                 <th class="border-b border-border px-4 py-3 text-left font-semibold text-headline">
-                    Default
+                    {text.default}
                 </th>
                 <th class="border-b border-border px-4 py-3 text-left font-semibold text-headline">
-                    Description
+                    {text.description}
                 </th>
             </tr>
         </thead>
         <tbody>
             {#each props as prop}
-                <tr class="hover:bg-base-50/70">
+                <tr class="hover:bg-surface-hover">
                     <td class="border-b border-border px-4 py-3 font-mono text-body">
                         {prop.name}
                     </td>
@@ -45,7 +60,7 @@
                         {prop.type}
                     </td>
                     <td class="border-b border-border px-4 py-3 text-description">
-                        {prop.required ? "Yes" : "No"}
+                        {prop.required ? text.yes : text.no}
                     </td>
                     <td class="border-b border-border px-4 py-3 text-description">
                         {prop.defaultValue || "—"}

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

@@ -1,7 +1,12 @@
 import type { ComponentProp } from "../types/page.types";
+import { type PropsTableStrings } from "../util/ready-made-strings.js";
 interface Props {
+    /** Extra classes for the host element. */
+    class?: string;
     props: ComponentProp[];
     caption?: string;
+    /** The column headings, Yes and No, and the line for an empty table. */
+    strings?: Partial<PropsTableStrings>;
 }
 declare const PropsTable: import("svelte").Component<Props, {}, "">;
 type PropsTable = ReturnType<typeof PropsTable>;

package/dist/molecules/PullToRefresh.svelte

@@ -0,0 +1,263 @@
+<script lang="ts">
+    import { mergeStrings } from "../util/ready-made-strings.js";
+    import { zabiStringsFor } from "../util/zabi-strings.js";
+    import type { Snippet } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import ArrowDown from "@lucide/svelte/icons/arrow-down";
+    import Spinner from "../atoms/Spinner.svelte";
+    import { cn } from "../util/cn.js";
+    import {
+        DEFAULT_PULL_TO_REFRESH_STRINGS,
+        pullDistance,
+        scrollContainerOf,
+        type PullToRefreshStrings,
+    } from "../util/pull-to-refresh.js";
+    import { DRAG_SLOP, prefersReducedMotion } from "../util/sheet-drag.js";
+
+    /**
+     * A list that reloads when it is pulled down from its top, on a touch
+     * screen.
+     *
+     * The pull is a shortcut. The same refresh is a button at the top of the
+     * region, out of sight until keyboard focus reaches it, and named for a
+     * screen reader; "Refreshing" and "Updated" are announced, and the
+     * region is `aria-busy` meanwhile.
+     *
+     * It only acts while what scrolls the list (the page, or the nearest
+     * scrolling ancestor, such as the content of an `AppShell`) is at its
+     * top, and never takes an ordinary scroll. The indicator is in the flow
+     * of the region, above the list, so under an app bar it comes out below
+     * the bar.
+     *
+     * ```svelte
+     * <PullToRefresh onrefresh={() => loadRounds()}>
+     *     <List items={rounds} />
+     * </PullToRefresh>
+     * ```
+     */
+    type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "children" | "aria-busy"> & {
+        /**
+         * Reloads the list. Return the promise: the indicator stays until it
+         * settles. A promise that rejects ends the refresh too, and nothing
+         * is announced as updated; say what went wrong yourself.
+         */
+        onrefresh?: () => Promise<void> | void;
+        /** Whether a refresh is running. Bindable: set it to show the indicator for a refresh of your own. */
+        refreshing?: boolean;
+        /** No pull and no button. */
+        disabled?: boolean;
+        /** How far the indicator has to come out for letting go to refresh, in px. */
+        threshold?: number;
+        /**
+         * The button that refreshes without the gesture. Without it the pull
+         * is the only way this component offers, and the app has to give
+         * another (WCAG 2.5.1).
+         */
+        showButton?: boolean;
+        /** The words the component says by itself, for another language. */
+        strings?: Partial<PullToRefreshStrings>;
+        class?: string;
+        /** The list. */
+        children?: Snippet;
+    };
+
+    let {
+        onrefresh,
+        refreshing = $bindable<Exclude<Props["refreshing"], undefined>>(),
+        disabled = false,
+        threshold = 64,
+        showButton = true,
+        strings,
+        class: className = "",
+        children,
+        ...restProps
+    }: Props = $props();
+
+    // No fallback on a bindable prop (see Collapsible): the default is applied here.
+    const applyDefaults = () => {
+        if (refreshing === undefined) refreshing = false;
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
+    /** The app-wide words for this component, from a `ZabiStringsProvider` above it, if there is one. */
+    const provided = zabiStringsFor("pullToRefresh");
+    const text = $derived(mergeStrings(DEFAULT_PULL_TO_REFRESH_STRINGS, provided(), strings));
+
+    let root = $state<HTMLDivElement>();
+    /** How far the indicator is out under a finger, in px; null when no pull is going on. */
+    let pulled = $state<number | null>(null);
+    /** What the status region says. It is in the page, empty, before anything is said. */
+    let status = $state("");
+    /** Set when a refresh of this component's own failed: nothing was updated. */
+    let failed = false;
+
+    const armed = $derived(pulled !== null && pulled >= threshold);
+
+    async function refresh() {
+        if (disabled || refreshing) return;
+        failed = false;
+        refreshing = true;
+        try {
+            await onrefresh?.();
+        } catch {
+            // The app's to report (see `onrefresh`). The refresh is over all the same.
+            failed = true;
+        } finally {
+            refreshing = false;
+        }
+    }
+
+    // The announcements follow `refreshing`, whoever set it.
+    let wasRefreshing = false;
+    $effect(() => {
+        const now = !!refreshing;
+        if (now === wasRefreshing) return;
+        wasRefreshing = now;
+        status = now ? text.refreshing : failed ? "" : text.done;
+    });
+
+    // The browser's own pull-to-refresh must not fire as well: that is a
+    // property of what scrolls, which is not this element.
+    $effect(() => {
+        const element = root;
+        if (!element || disabled) return;
+        const scroller = scrollContainerOf(element);
+        const before = scroller.style.overscrollBehaviorY;
+        scroller.style.overscrollBehaviorY = "contain";
+        return () => {
+            scroller.style.overscrollBehaviorY = before;
+        };
+    });
+
+    // --- The pull. Touch events, because the browser owns the gesture (it
+    // scrolls) until it is taken, and only a touch listener that is not
+    // passive can take it. A mouse does not pull.
+    $effect(() => {
+        const element = root;
+        if (!element || disabled) return;
+        const scroller = scrollContainerOf(element);
+        let touchId: number | null = null;
+        let startX = 0;
+        let startY = 0;
+        let pulling = false;
+
+        const find = (list: TouchList) => Array.from(list).find((touch) => touch.identifier === touchId);
+
+        function onTouchStart(event: TouchEvent) {
+            if (touchId !== null || event.touches.length !== 1 || refreshing) return;
+            if (scroller.scrollTop > 0) return;
+            const touch = event.touches[0];
+            touchId = touch.identifier;
+            startX = touch.clientX;
+            startY = touch.clientY;
+            pulling = false;
+        }
+
+        function onTouchMove(event: TouchEvent) {
+            const touch = find(event.touches);
+            if (!touch) return;
+            const dx = touch.clientX - startX;
+            const dy = touch.clientY - startY;
+            if (!pulling) {
+                // Scrolled since, upwards, or sideways: not a pull.
+                if (scroller.scrollTop > 0 || dy < DRAG_SLOP) return;
+                if (Math.abs(dx) > Math.abs(dy)) {
+                    touchId = null;
+                    return;
+                }
+                pulling = true;
+                // Measured from where the pull was recognised.
+                startY = touch.clientY;
+            }
+            if (event.cancelable) event.preventDefault();
+            pulled = pullDistance(touch.clientY - startY, threshold);
+        }
+
+        function finish(event: TouchEvent, cancelled: boolean) {
+            if (!find(event.changedTouches)) return;
+            touchId = null;
+            const far = pulling && !cancelled && pulled !== null && pulled >= threshold;
+            pulling = false;
+            pulled = null;
+            if (far) void refresh();
+        }
+
+        const onTouchEnd = (event: TouchEvent) => finish(event, false);
+        const onTouchCancel = (event: TouchEvent) => finish(event, true);
+
+        element.addEventListener("touchstart", onTouchStart, { passive: true });
+        element.addEventListener("touchmove", onTouchMove, { passive: false });
+        element.addEventListener("touchend", onTouchEnd);
+        element.addEventListener("touchcancel", onTouchCancel);
+        return () => {
+            element.removeEventListener("touchstart", onTouchStart);
+            element.removeEventListener("touchmove", onTouchMove);
+            element.removeEventListener("touchend", onTouchEnd);
+            element.removeEventListener("touchcancel", onTouchCancel);
+        };
+    });
+
+    /**
+     * The height of the indicator: under the finger while pulling, at the
+     * threshold while the refresh runs. Where motion is unwanted it does not
+     * follow the finger: it is there, at full height, or it is not.
+     */
+    const indicatorHeight = $derived.by(() => {
+        if (refreshing) return threshold;
+        if (pulled === null) return 0;
+        return prefersReducedMotion() ? (pulled > 0 ? threshold : 0) : pulled;
+    });
+</script>
+
+<div
+    {...restProps}
+    bind:this={root}
+    class={cn("relative", className)}
+    aria-busy={refreshing ? "true" : undefined}
+    data-pull-to-refresh
+    data-refreshing={refreshing ? "true" : "false"}
+>
+    <!-- In the page before it says anything, or the first announcement is lost. -->
+    <div class="sr-only" role="status" aria-live="polite" data-pull-status>{status}</div>
+
+    {#if showButton && !disabled}
+        <!-- Out of sight until keyboard focus reaches it: the list is what the region is for. -->
+        <button
+            type="button"
+            class="focus-ring sr-only cursor-pointer rounded-control bg-action-secondary text-sm font-medium text-headline hover:bg-action-secondary-hover active:bg-action-secondary-active focus-visible:not-sr-only focus-visible:absolute focus-visible:start-[8px] focus-visible:top-[8px] focus-visible:z-10 focus-visible:min-h-11 focus-visible:px-[16px]"
+            aria-disabled={refreshing ? "true" : undefined}
+            data-pull-button
+            onclick={() => void refresh()}
+        >
+            {text.refresh}
+        </button>
+    {/if}
+
+    <!-- Decorative: the status region and the button carry it for assistive technology. -->
+    <div
+        class={cn(
+            "flex items-end justify-center overflow-hidden text-sm text-description",
+            pulled === null && "transition-[height] duration-200 ease-out motion-reduce:transition-none",
+        )}
+        style:height="{indicatorHeight}px"
+        aria-hidden="true"
+        data-pull-indicator
+        data-armed={armed ? "true" : "false"}
+    >
+        <div class="flex h-[64px] shrink-0 items-center gap-[8px]">
+            {#if refreshing}
+                <Spinner size="md" />
+                <span>{text.refreshing}</span>
+            {:else}
+                <ArrowDown
+                    size={16}
+                    class={cn("transition-transform duration-150 motion-reduce:transition-none", armed && "rotate-180")}
+                />
+                <span>{armed ? text.release : text.pull}</span>
+            {/if}
+        </div>
+    </div>
+
+    {@render children?.()}
+</div>

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

@@ -0,0 +1,52 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import { type PullToRefreshStrings } from "../util/pull-to-refresh.js";
+/**
+ * A list that reloads when it is pulled down from its top, on a touch
+ * screen.
+ *
+ * The pull is a shortcut. The same refresh is a button at the top of the
+ * region, out of sight until keyboard focus reaches it, and named for a
+ * screen reader; "Refreshing" and "Updated" are announced, and the
+ * region is `aria-busy` meanwhile.
+ *
+ * It only acts while what scrolls the list (the page, or the nearest
+ * scrolling ancestor, such as the content of an `AppShell`) is at its
+ * top, and never takes an ordinary scroll. The indicator is in the flow
+ * of the region, above the list, so under an app bar it comes out below
+ * the bar.
+ *
+ * ```svelte
+ * <PullToRefresh onrefresh={() => loadRounds()}>
+ *     <List items={rounds} />
+ * </PullToRefresh>
+ * ```
+ */
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "children" | "aria-busy"> & {
+    /**
+     * Reloads the list. Return the promise: the indicator stays until it
+     * settles. A promise that rejects ends the refresh too, and nothing
+     * is announced as updated; say what went wrong yourself.
+     */
+    onrefresh?: () => Promise<void> | void;
+    /** Whether a refresh is running. Bindable: set it to show the indicator for a refresh of your own. */
+    refreshing?: boolean;
+    /** No pull and no button. */
+    disabled?: boolean;
+    /** How far the indicator has to come out for letting go to refresh, in px. */
+    threshold?: number;
+    /**
+     * The button that refreshes without the gesture. Without it the pull
+     * is the only way this component offers, and the app has to give
+     * another (WCAG 2.5.1).
+     */
+    showButton?: boolean;
+    /** The words the component says by itself, for another language. */
+    strings?: Partial<PullToRefreshStrings>;
+    class?: string;
+    /** The list. */
+    children?: Snippet;
+};
+declare const PullToRefresh: import("svelte").Component<Props, {}, "refreshing">;
+type PullToRefresh = ReturnType<typeof PullToRefresh>;
+export default PullToRefresh;

package/dist/molecules/RadioGroup.svelte

@@ -4,9 +4,13 @@
         RADIO_GROUP_CONTROL_SHELL,
         RADIO_GROUP_OPTION_LABEL_ROW,
         RADIO_GROUP_RING_OVERLAY,
+        SELECTION_CONTROL_INPUT,
     } from "../atoms/selection-control.styles";
+    import type { HTMLFieldsetAttributes } from "svelte/elements";
     import { generateId } from "../util/ssr-safe.js";
     import { SvelteMap } from "svelte/reactivity";
+    import { cn } from "../util/cn.js";
+    import { resetValueOf, groupBinding } from "../util/hydration.js";
 
     export type RadioGroupOption = {
         value: string;
@@ -15,22 +19,35 @@
         description?: string;
     };
 
-    interface Props {
+    /** Other attributes (`id`, `data-*`, `aria-*`, ...) land on the `<fieldset>`. */
+    type Props = Omit<HTMLFieldsetAttributes, "class" | "name" | "disabled"> & {
+        /** Extra classes for the host element. */
+        class?: string;
         options: RadioGroupOption[];
         /** Selected value; `bind:value`. Use `undefined` for no selection. */
         value?: string | undefined;
-        /** Uncontrolled initial value. */
+        /**
+         * The selection to start with when `value` is `undefined` as the
+         * group is created. Applied once: it does not come back when the
+         * value is set to `undefined` later, and it never replaces a choice.
+         */
         defaultValue?: string | undefined;
+        /**
+         * Name the value is submitted under in a form. Without a name the
+         * group is not part of the form around it: it submits nothing and a
+         * form reset leaves it alone.
+         */
         name?: string;
         disabled?: boolean;
         legend?: string;
         label?: string;
-    }
+    };
 
     let {
+        class: className = "",
         options,
         defaultValue,
-        value = $bindable(defaultValue),
+        value = $bindable(),
         name: nameProp,
         disabled = false,
         legend = "",
@@ -38,6 +55,21 @@
         ...restProps
     }: Props = $props();
 
+    // No fallback on the bindable prop: with one, `bind:value={undefined}`
+    // (which the prop's own documentation names as "no selection") throws
+    // `props_invalid_value` and the page never hydrates. The default is
+    // applied once, here, so the server renders it too. A choice made in the
+    // server markup before hydration is taken in after this and wins.
+    (() => {
+        if (value === undefined && defaultValue !== undefined) value = defaultValue;
+    })();
+
+    /**
+     * The radios always share a name, the caller's or one made here: without
+     * one they are not a group to the browser. With a name made here they are
+     * kept out of any form around them (`form` names a form that does not
+     * exist): it used to be submitted as `radiogroup-…`, a field nobody named.
+     */
     const fallbackName = generateId("radiogroup");
     const groupName = $derived(nameProp || fallbackName);
     const legendText = $derived(legend || label);
@@ -71,13 +103,24 @@
         return option.value === fallbackValue ? 0 : -1;
     }
 
-    function handleChange(event: Event) {
-        if (disabled) return;
-        const target = event.target as HTMLInputElement;
-        value = target.value;
-    }
-
     const elementsByValue = new SvelteMap<string, HTMLInputElement>();
+
+    /**
+     * The radios are bound, so an option picked before the page hydrated is
+     * kept: Svelte's binding hands it over here instead of overwriting it
+     * (see util/hydration.ts). A form reset empties the selection, as it empties
+     * a bound native input.
+     */
+    const chosen = groupBinding<string>(
+        () => value,
+        (next) => {
+            if (!disabled) value = next;
+        },
+        () => {
+            if (!disabled) value = resetValueOf<string>(elementsByValue.values());
+        },
+    );
+
     function registerRadio(valueKey: string) {
         return (node: HTMLInputElement) => {
             elementsByValue.set(valueKey, node);
@@ -150,7 +193,7 @@
 </script>
 
 <fieldset
-    class="space-y-3"
+    class={cn("space-y-3", className)}
     aria-disabled={disabled ? "true" : undefined}
     onkeydown={handleKeydown}
     {...restProps}
@@ -164,18 +207,17 @@
     <div class="space-y-3">
         {#each options as option (option.value)}
             {@const optionDisabled = isOptionDisabled(option)}
-            {@const isChecked = value === option.value}
             <label class={optionLabelWrapperClasses}>
                 <span class={radioControlShellClasses}>
                     <input
                         type="radio"
                         name={groupName}
+                        form={nameProp ? undefined : groupName}
                         value={option.value}
-                        checked={isChecked}
+                        bind:group={chosen.value}
                         disabled={optionDisabled}
                         tabindex={tabIndexFor(option)}
-                        class="sr-only"
-                        onchange={handleChange}
+                        class={SELECTION_CONTROL_INPUT}
                         {@attach registerRadio(option.value)}
                     />
                     <span class={radioRingOverlayClasses}></span>

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

@@ -1,20 +1,33 @@
+import type { HTMLFieldsetAttributes } from "svelte/elements";
 export type RadioGroupOption = {
     value: string;
     label: string;
     disabled?: boolean;
     description?: string;
 };
-interface Props {
+/** Other attributes (`id`, `data-*`, `aria-*`, ...) land on the `<fieldset>`. */
+type Props = Omit<HTMLFieldsetAttributes, "class" | "name" | "disabled"> & {
+    /** Extra classes for the host element. */
+    class?: string;
     options: RadioGroupOption[];
     /** Selected value; `bind:value`. Use `undefined` for no selection. */
     value?: string | undefined;
-    /** Uncontrolled initial value. */
+    /**
+     * The selection to start with when `value` is `undefined` as the
+     * group is created. Applied once: it does not come back when the
+     * value is set to `undefined` later, and it never replaces a choice.
+     */
     defaultValue?: string | undefined;
+    /**
+     * Name the value is submitted under in a form. Without a name the
+     * group is not part of the form around it: it submits nothing and a
+     * form reset leaves it alone.
+     */
     name?: string;
     disabled?: boolean;
     legend?: string;
     label?: string;
-}
+};
 declare const RadioGroup: import("svelte").Component<Props, {}, "value">;
 type RadioGroup = ReturnType<typeof RadioGroup>;
 export default RadioGroup;