zabi-components 8.0.0 → 9.0.0

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,10 +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;
@@ -16,32 +19,63 @@
         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;
-    }
+        /**
+         * Draw a ring round the chosen row. Off, the filled radio alone shows
+         * the choice; keyboard focus keeps its ring either way.
+         */
+        chosenRing?: boolean;
+    };
 
     let {
         class: className = "",
         options,
         defaultValue,
-        value = $bindable(defaultValue),
+        value = $bindable(),
         name: nameProp,
         disabled = false,
         legend = "",
         label = "",
+        chosenRing = true,
         ...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);
@@ -75,13 +109,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);
@@ -166,20 +211,28 @@
     {/if}
 
     <div class="space-y-3">
-        {#each options as option (option.value)}
+        {#each options as option, index (option.value)}
             {@const optionDisabled = isOptionDisabled(option)}
-            {@const isChecked = value === option.value}
-            <label class={optionLabelWrapperClasses}>
-                <span class={radioControlShellClasses}>
+            {@const descriptionId = option.description ? `${fallbackName}-${index}-description` : undefined}
+            <!-- A one-line row is centred in its height; with a description the radio stays at the top, by the label. -->
+            <label
+                class={cn(
+                    optionLabelWrapperClasses,
+                    !option.description && "items-center",
+                    !chosenRing && "selection-control-option-row-quiet",
+                )}
+            >
+                <span class={cn(radioControlShellClasses, !option.description && "mt-0")}>
                     <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}
+                        aria-describedby={descriptionId}
+                        class={SELECTION_CONTROL_INPUT}
                         {@attach registerRadio(option.value)}
                     />
                     <span class={radioRingOverlayClasses}></span>
@@ -190,7 +243,8 @@
                         {option.label}
                     </span>
                     {#if option.description}
-                        <span class="text-sm text-description">
+                        <!-- aria-hidden keeps it out of the name; aria-describedby still reads it. -->
+                        <span id={descriptionId} class="text-sm text-description" aria-hidden="true">
                             {option.description}
                         </span>
                     {/if}

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

@@ -1,22 +1,38 @@
+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;
-}
+    /**
+     * Draw a ring round the chosen row. Off, the filled radio alone shows
+     * the choice; keyboard focus keeps its ring either way.
+     */
+    chosenRing?: boolean;
+};
 declare const RadioGroup: import("svelte").Component<Props, {}, "value">;
 type RadioGroup = ReturnType<typeof RadioGroup>;
 export default RadioGroup;

package/dist/molecules/Section.svelte

@@ -76,7 +76,7 @@
             case "muted":
                 return "bg-base-50";
             case "accent":
-                return "bg-brand-50 dark:bg-brand-950";
+                return "bg-brand-50";
             case "transparent":
                 return "bg-transparent";
             default: