zabi-components 8.1.0 → 9.0.0

package/dist/util/sheet-drag.js

@@ -8,9 +8,63 @@
  */
 /** Movement under this many px is a press, not a drag. */
 export const DRAG_SLOP = 6;
+/**
+ * Movement, on either axis, after which a touch in the content has an axis:
+ * more across than down is sideways (a carousel, a row that scrolls, a
+ * swipeable item), and stays so until the finger lifts.
+ */
+export const AXIS_SLOP = 8;
 /** Controls in the handle zone that keep their own press, except the grip itself. */
 const INTERACTIVE = "button, a[href], input, select, textarea, [data-sheet-no-drag]";
 const GRIP = "[data-sheet-grip]";
+/**
+ * Content that is dragged by a finger on its own and so is never the sheet's:
+ * anything carrying `data-sheet-no-drag`, and a range input. Read on a touch
+ * that starts in the content.
+ */
+const OWN_DRAG = "[data-sheet-no-drag], input[type='range']";
+/**
+ * Whether a computed `touch-action` hands vertical gestures to the element's
+ * own code: `none`, or panning on the x axis only. `auto`, `manipulation`,
+ * `pan-y` and the like let the browser pan vertically, which is the sheet's
+ * to take.
+ */
+function ownsVerticalGesture(touchAction) {
+    const tokens = touchAction.trim().split(/\s+/);
+    if (tokens.includes("none"))
+        return true;
+    const sideways = tokens.some((token) => token === "pan-x" || token === "pan-left" || token === "pan-right");
+    const vertical = tokens.some((token) => token === "pan-y" || token === "pan-up" || token === "pan-down");
+    return sideways && !vertical;
+}
+/**
+ * Whether a touch that begins on `target` belongs to the content and not to the
+ * sheet: it started on something that is dragged itself (`OWN_DRAG`), or it
+ * has, between it and the sheet's `scroller`, a box that scrolls on the y axis
+ * or one whose `touch-action` leaves vertical panning to the page's own code
+ * (`ownsVerticalGesture`: a map, a canvas, a drawing pad, a slider).
+ * A box that can scroll keeps the gesture whether it is at its top or not: a
+ * drag that sometimes scrolls a list and sometimes closes the sheet cannot be
+ * predicted, and the list does not hand over what it cannot use
+ * (`overscroll-contain`). The scroller itself is not asked here; it is the
+ * sheet's own content, and hands a pull down at its top to the sheet.
+ */
+export function contentTakesTouch(target, scroller) {
+    if (!(target instanceof Element))
+        return false;
+    if (target.closest(OWN_DRAG))
+        return true;
+    for (let node = target; node && node !== scroller; node = node.parentElement) {
+        const style = getComputedStyle(node);
+        if (ownsVerticalGesture(style.getPropertyValue("touch-action")))
+            return true;
+        const overflow = style.overflowY;
+        if ((overflow === "auto" || overflow === "scroll") && node.scrollHeight > node.clientHeight) {
+            return true;
+        }
+    }
+    return false;
+}
 /** The clock of this page, for when an event's own time cannot be used. */
 const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
 /**
@@ -159,8 +213,13 @@ export function attachSheetDrag({ handleZone, scroller }, callbacks) {
     // is not passive can take it.
     let touchId = null;
     let touchStart = 0;
+    let touchStartX = 0;
+    /** Decided once per gesture, after `AXIS_SLOP`: null until then. */
+    let touchAxis = null;
     let touchDragging = false;
     let startedAtTop = false;
+    /** The touch began on something inside the content that keeps it. */
+    let contentOwns = false;
     const touchOf = (event, list) => Array.from(list).find((touch) => touch.identifier === touchId);
     function onTouchStart(event) {
         if (touchId !== null || pointerId !== null || event.touches.length !== 1)
@@ -168,8 +227,11 @@ export function attachSheetDrag({ handleZone, scroller }, callbacks) {
         const touch = event.touches[0];
         touchId = touch.identifier;
         touchStart = touch.clientY;
+        touchStartX = touch.clientX;
+        touchAxis = null;
         touchDragging = false;
         startedAtTop = (scroller?.scrollTop ?? 0) <= 0;
+        contentOwns = !!scroller && contentTakesTouch(event.target, scroller);
     }
     function onTouchMove(event) {
         const touch = touchOf(event, event.touches);
@@ -178,8 +240,16 @@ export function attachSheetDrag({ handleZone, scroller }, callbacks) {
         const distance = touch.clientY - touchStart;
         if (!touchDragging) {
             // Content that has scrolled, or a swipe upwards: the content's.
-            if (!startedAtTop || (scroller?.scrollTop ?? 0) > 0)
+            if (contentOwns || touchAxis === "x" || !startedAtTop || (scroller?.scrollTop ?? 0) > 0)
                 return;
+            if (touchAxis === null) {
+                const across = Math.abs(touch.clientX - touchStartX);
+                if (Math.max(across, Math.abs(distance)) < AXIS_SLOP)
+                    return;
+                touchAxis = across > Math.abs(distance) ? "x" : "y";
+                if (touchAxis === "x")
+                    return;
+            }
             if (distance < DRAG_SLOP || !allowed())
                 return;
             touchDragging = true;

package/dist/util/skeleton.d.ts

@@ -0,0 +1,14 @@
+/** Every built-in string. Pass a partial object to `strings` to translate. */
+export interface SkeletonStrings {
+    /** The name of the loading status, for a lone `Skeleton` and for a `SkeletonGroup`. */
+    label: string;
+}
+export declare const DEFAULT_SKELETON_STRINGS: SkeletonStrings;
+/** The fewest and the most lines a text `Skeleton` draws with `lines`. */
+export declare const SKELETON_LINES_MAX = 20;
+/** `lines` as a whole number from 1 to 20, or 0 for "not a paragraph" (unset, below 1, not a number). */
+export declare function skeletonLineCount(lines: number | undefined): number;
+/** For `SkeletonGroup`: marks everything below it as pieces of one status. Call while the component initialises. */
+export declare function provideSkeletonGroup(): void;
+/** For `Skeleton`: whether it sits under a `SkeletonGroup`. Call while the component initialises. */
+export declare function inSkeletonGroup(): boolean;

package/dist/util/skeleton.js

@@ -0,0 +1,22 @@
+/** Types and helpers shared by `Skeleton` and `SkeletonGroup`. Kept out of the components so they can be tested without a DOM. */
+import { getContext, setContext } from "svelte";
+export const DEFAULT_SKELETON_STRINGS = {
+    label: "Loading…",
+};
+/** The fewest and the most lines a text `Skeleton` draws with `lines`. */
+export const SKELETON_LINES_MAX = 20;
+/** `lines` as a whole number from 1 to 20, or 0 for "not a paragraph" (unset, below 1, not a number). */
+export function skeletonLineCount(lines) {
+    if (lines === undefined || !Number.isFinite(lines) || lines < 1)
+        return 0;
+    return Math.min(SKELETON_LINES_MAX, Math.floor(lines));
+}
+const GROUP_KEY = Symbol("zabi-skeleton-group");
+/** For `SkeletonGroup`: marks everything below it as pieces of one status. Call while the component initialises. */
+export function provideSkeletonGroup() {
+    setContext(GROUP_KEY, true);
+}
+/** For `Skeleton`: whether it sits under a `SkeletonGroup`. Call while the component initialises. */
+export function inSkeletonGroup() {
+    return getContext(GROUP_KEY) === true;
+}

package/dist/util/sliding-indicator.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Measuring for the sliding indicator of Tabs and SegmentedControl. The
+ * component paints its selected item itself until a box has been measured, so
+ * a server render, a page that has not hydrated and an engine that cannot
+ * measure all keep the static look.
+ */
+export interface IndicatorBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The `item`'s box in the coordinates an absolutely positioned child of
+ * `container` uses: from the container's padding box, plus what the container
+ * has scrolled (so an indicator inside a scrolling list stays on its item).
+ * Measured as physical boxes, so a right-to-left layout needs nothing extra.
+ * Null where nothing can be measured (no layout, or the item is not shown).
+ */
+export declare function measureIndicator(container: HTMLElement, item: HTMLElement): IndicatorBox | null;
+/** Calls `onChange` when any of the `targets` changes size; a no-op without ResizeObserver. */
+export declare function observeSizes(targets: Array<Element | null | undefined>, onChange: () => void): () => void;
+/** Runs `callback` after the next frame; the timer stands in where there are no frames. */
+export declare function afterFrame(callback: () => void): () => void;

package/dist/util/sliding-indicator.js

@@ -0,0 +1,44 @@
+/**
+ * Measuring for the sliding indicator of Tabs and SegmentedControl. The
+ * component paints its selected item itself until a box has been measured, so
+ * a server render, a page that has not hydrated and an engine that cannot
+ * measure all keep the static look.
+ */
+/**
+ * The `item`'s box in the coordinates an absolutely positioned child of
+ * `container` uses: from the container's padding box, plus what the container
+ * has scrolled (so an indicator inside a scrolling list stays on its item).
+ * Measured as physical boxes, so a right-to-left layout needs nothing extra.
+ * Null where nothing can be measured (no layout, or the item is not shown).
+ */
+export function measureIndicator(container, item) {
+    const outer = container.getBoundingClientRect();
+    const inner = item.getBoundingClientRect();
+    if (inner.width === 0 && inner.height === 0)
+        return null;
+    return {
+        x: inner.left - outer.left - container.clientLeft + container.scrollLeft,
+        y: inner.top - outer.top - container.clientTop + container.scrollTop,
+        width: inner.width,
+        height: inner.height,
+    };
+}
+/** Calls `onChange` when any of the `targets` changes size; a no-op without ResizeObserver. */
+export function observeSizes(targets, onChange) {
+    if (typeof ResizeObserver === "undefined")
+        return () => { };
+    const observer = new ResizeObserver(onChange);
+    for (const target of targets)
+        if (target)
+            observer.observe(target);
+    return () => observer.disconnect();
+}
+/** Runs `callback` after the next frame; the timer stands in where there are no frames. */
+export function afterFrame(callback) {
+    if (typeof requestAnimationFrame === "function") {
+        const id = requestAnimationFrame(callback);
+        return () => cancelAnimationFrame(id);
+    }
+    const id = setTimeout(callback, 16);
+    return () => clearTimeout(id);
+}

package/dist/util/temporal-field.d.ts

@@ -0,0 +1,88 @@
+/**
+ * What DateField and TimeField share once they are given a `locale`: the
+ * words, and the pure parts of the time picker (which hours and minutes
+ * there are, which are outside `min` and `max`).
+ */
+/** The words DateField says when it has a `locale`. Replace any of them to translate. */
+export interface DateFieldStrings {
+    /** The sheet's action that empties the field. Shown while the field has a value and is not `required`. */
+    clear: string;
+    /** The sheet's name when the field has no label. */
+    chooseDate: string;
+}
+export declare const DATE_FIELD_STRINGS: DateFieldStrings;
+/** The words TimeField says when it has a `locale`. Replace any of them to translate. */
+export interface TimeFieldStrings {
+    /** The sheet's action that empties the field. Shown while the field has a value and is not `required`. */
+    clear: string;
+    /** The sheet's action that sets the chosen time and closes it. */
+    done: string;
+    /** Accessible name of the column of hours. */
+    hours: string;
+    /** Accessible name of the column of minutes. */
+    minutes: string;
+    /** The sheet's words beside Done for the time Done will set: "Chosen time 18:00". */
+    chosenTime: string;
+    /** The sheet's name when the field has no label. */
+    chooseTime: string;
+}
+export declare const TIME_FIELD_STRINGS: TimeFieldStrings;
+/** Whether a `locale` was given: a tag, or a list with at least one. */
+export declare function hasLocale(locale: string | string[] | undefined | null): boolean;
+/** The minutes between choices when the app says nothing: five. */
+export declare const DEFAULT_MINUTE_STEP = 5;
+/**
+ * Whether the library's time picker can serve this `step`. It has hours and
+ * minutes only, so a step in seconds (under 60) or `"any"` is left to the
+ * platform's own picker.
+ */
+export declare function stepFitsLibraryPicker(step: number | "any" | undefined): boolean;
+/** `step` (in seconds) as whole minutes between choices; five without one. */
+export declare function minuteStep(step: number | "any" | undefined): number;
+/** `"19:30"` (or `"19:30:15"`) as [19, 30]; null for anything else. */
+export declare function parseHourMinute(value: string | null | undefined): [number, number] | null;
+/**
+ * The time an empty field's columns stand at: `openAt`, else `now` (an
+ * hour and a minute), kept within `min` and `max` and on the minute step.
+ * Only a place to scroll to; nothing is chosen. Two-digit strings, as the
+ * columns' option values.
+ */
+export declare function openingTime(options: {
+    openAt?: string;
+    now: [number, number];
+    stepMinutes: number;
+    min?: string;
+    max?: string;
+}): [string, string];
+/**
+ * Whether a time is within `min` and `max`, either of which may be missing.
+ * Like the native input, a `min` later than `max` is a range over midnight:
+ * 22:00 to 06:00 allows 23:30 and 05:00.
+ */
+export declare function timeInRange(hour: number, minute: number, min?: string, max?: string): boolean;
+export interface TimeChoice {
+    /** Two digits: `"07"`. */
+    value: string;
+    label: string;
+    disabled: boolean;
+}
+/** The hour as the locale writes it: "19" in Swedish, "7 PM" in American English. */
+export declare function hourLabel(hour: number, locale: string | string[] | undefined): string;
+/** The minute as two digits, in the locale's own numerals. */
+export declare function minuteLabel(minute: number, locale: string | string[] | undefined): string;
+/** The 24 hours. An hour is disabled when no time in it is within `min` and `max`. */
+export declare function hourChoices(locale: string | string[] | undefined, min?: string, max?: string): TimeChoice[];
+/**
+ * The minutes of one hour: every `stepMinutes`, plus the minute of `current`
+ * when it is not on the step, so a value such as 19:07 can be kept. A minute
+ * is disabled when the time is outside `min` and `max`; with no hour chosen
+ * none is.
+ */
+export declare function minuteChoices(options: {
+    locale: string | string[] | undefined;
+    stepMinutes: number;
+    hour: string;
+    current?: string;
+    min?: string;
+    max?: string;
+}): TimeChoice[];

package/dist/util/temporal-field.js

@@ -0,0 +1,136 @@
+/**
+ * What DateField and TimeField share once they are given a `locale`: the
+ * words, and the pure parts of the time picker (which hours and minutes
+ * there are, which are outside `min` and `max`).
+ */
+import { formatTime } from "./date.js";
+export const DATE_FIELD_STRINGS = {
+    clear: "Clear",
+    chooseDate: "Choose date",
+};
+export const TIME_FIELD_STRINGS = {
+    clear: "Clear",
+    done: "Done",
+    hours: "Hours",
+    minutes: "Minutes",
+    chosenTime: "Chosen time",
+    chooseTime: "Choose time",
+};
+/** Whether a `locale` was given: a tag, or a list with at least one. */
+export function hasLocale(locale) {
+    return Array.isArray(locale) ? locale.length > 0 : !!locale;
+}
+/** The minutes between choices when the app says nothing: five. */
+export const DEFAULT_MINUTE_STEP = 5;
+/**
+ * Whether the library's time picker can serve this `step`. It has hours and
+ * minutes only, so a step in seconds (under 60) or `"any"` is left to the
+ * platform's own picker.
+ */
+export function stepFitsLibraryPicker(step) {
+    if (step === undefined)
+        return true;
+    return typeof step === "number" && Number.isFinite(step) && step >= 60;
+}
+/** `step` (in seconds) as whole minutes between choices; five without one. */
+export function minuteStep(step) {
+    if (typeof step === "number" && Number.isFinite(step) && step >= 60)
+        return Math.round(step / 60);
+    return DEFAULT_MINUTE_STEP;
+}
+const pad2 = (value) => String(value).padStart(2, "0");
+/** `"19:30"` (or `"19:30:15"`) as [19, 30]; null for anything else. */
+export function parseHourMinute(value) {
+    const match = /^(\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?$/.exec(value ?? "");
+    if (!match)
+        return null;
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    return hour > 23 || minute > 59 ? null : [hour, minute];
+}
+/**
+ * The time an empty field's columns stand at: `openAt`, else `now` (an
+ * hour and a minute), kept within `min` and `max` and on the minute step.
+ * Only a place to scroll to; nothing is chosen. Two-digit strings, as the
+ * columns' option values.
+ */
+export function openingTime(options) {
+    const { openAt, now, stepMinutes, min, max } = options;
+    const [hour, minute] = parseHourMinute(openAt) ?? now;
+    let at = hour * 60 + minute;
+    const lower = parseHourMinute(min);
+    const upper = parseHourMinute(max);
+    const from = lower ? lower[0] * 60 + lower[1] : null;
+    const to = upper ? upper[0] * 60 + upper[1] : null;
+    const inRange = (value) => timeInRange(Math.floor(value / 60) % 24, value % 60, min, max);
+    if (!inRange(at)) {
+        const overMidnight = from !== null && to !== null && from > to;
+        at = from !== null && (overMidnight || at < from) ? from : (to ?? at);
+    }
+    const floored = Math.floor(at / stepMinutes) * stepMinutes;
+    const stepped = inRange(floored) ? floored : Math.min(Math.ceil(at / stepMinutes) * stepMinutes, 23 * 60 + 59);
+    return [pad2(Math.floor(stepped / 60)), pad2(stepped % 60)];
+}
+/**
+ * Whether a time is within `min` and `max`, either of which may be missing.
+ * Like the native input, a `min` later than `max` is a range over midnight:
+ * 22:00 to 06:00 allows 23:30 and 05:00.
+ */
+export function timeInRange(hour, minute, min, max) {
+    const at = hour * 60 + minute;
+    const lower = parseHourMinute(min);
+    const upper = parseHourMinute(max);
+    const from = lower ? lower[0] * 60 + lower[1] : null;
+    const to = upper ? upper[0] * 60 + upper[1] : null;
+    if (from !== null && to !== null && from > to)
+        return at >= from || at <= to;
+    if (from !== null && at < from)
+        return false;
+    if (to !== null && at > to)
+        return false;
+    return true;
+}
+/** The hour as the locale writes it: "19" in Swedish, "7 PM" in American English. */
+export function hourLabel(hour, locale) {
+    return formatTime(`${pad2(hour)}:00`, locale, { hour: "numeric" }) || pad2(hour);
+}
+/** The minute as two digits, in the locale's own numerals. */
+export function minuteLabel(minute, locale) {
+    try {
+        return new Intl.NumberFormat(locale || undefined, { minimumIntegerDigits: 2, useGrouping: false }).format(minute);
+    }
+    catch {
+        return pad2(minute);
+    }
+}
+/** The 24 hours. An hour is disabled when no time in it is within `min` and `max`. */
+export function hourChoices(locale, min, max) {
+    return Array.from({ length: 24 }, (_, hour) => ({
+        value: pad2(hour),
+        label: hourLabel(hour, locale),
+        disabled: !Array.from({ length: 60 }, (_, minute) => minute).some((minute) => timeInRange(hour, minute, min, max)),
+    }));
+}
+/**
+ * The minutes of one hour: every `stepMinutes`, plus the minute of `current`
+ * when it is not on the step, so a value such as 19:07 can be kept. A minute
+ * is disabled when the time is outside `min` and `max`; with no hour chosen
+ * none is.
+ */
+export function minuteChoices(options) {
+    const { locale, stepMinutes, hour, current, min, max } = options;
+    const minutes = new Set();
+    for (let minute = 0; minute < 60; minute += stepMinutes)
+        minutes.add(minute);
+    const now = parseHourMinute(current);
+    if (now)
+        minutes.add(now[1]);
+    const chosenHour = hour === "" ? null : Number(hour);
+    return [...minutes]
+        .sort((a, b) => a - b)
+        .map((minute) => ({
+        value: pad2(minute),
+        label: minuteLabel(minute, locale),
+        disabled: chosenHour !== null && !timeInRange(chosenHour, minute, min, max),
+    }));
+}

package/dist/util/toaster.d.ts

@@ -90,3 +90,43 @@ export interface ToastPauseChange {
     /** True while a pointer is over the toast, a finger is on it, or focus is inside it. */
     paused: boolean;
 }
+/**
+ * How a `Toaster` presents its toasts. `"stack"` is the stack in the corner
+ * (and across the width on a phone); `"snackbar"` is the compact form for a
+ * phone, one at a time, docked above whatever is at the bottom; `"auto"` is
+ * the snackbar below 640px and the stack from there up.
+ */
+export type ToasterMode = "stack" | "snackbar" | "auto";
+/** The words of a toast on screen: its first line, and the line under it if there is one. */
+export declare function toastTexts(toast: {
+    title?: string;
+    message: string;
+    type: string;
+}, strings: Pick<ToasterStrings, "successTitle" | "errorTitle" | "warningTitle" | "infoTitle">): {
+    title: string;
+    message: string;
+    headerTitle: string;
+    secondLine: string;
+};
+/**
+ * True when the toast has to stay until a person has dealt with it, which
+ * makes it the one a `max` never drops: an error, one with an action, one
+ * with no end (`"persistent"`, or text too long to read in `long`).
+ */
+export declare function toastStays(toast: {
+    title?: string;
+    message: string;
+    type: string;
+    duration?: ToastDuration;
+    action?: unknown;
+}, defaultDuration?: ToastDuration): boolean;
+/**
+ * Ids of toasts that a `max` is dropping to make room for a newer one. Such a
+ * toast leaves at once, without the exit motion: a newer toast is coming in
+ * where it is, and the two would otherwise lie on each other for a moment.
+ */
+export declare const toastsReplaced: Set<string>;
+/** The Material standard curve (`--ease-standard`), as an easing function for a script-driven slide. */
+export declare function easeStandard(t: number): number;
+/** A toast dragged further than this share of its width is dismissed, flick or not. */
+export declare const TOAST_SWIPE_DISMISS_FRACTION = 0.4;

package/dist/util/toaster.js

@@ -73,3 +73,58 @@ export function resolveToastDuration(toast, defaultDuration) {
  * As long as `short`: holding a short toast starts it again, in effect.
  */
 export const TOAST_SECONDS_AFTER_HOLD = 3;
+/** The words of a toast on screen: its first line, and the line under it if there is one. */
+export function toastTexts(toast, strings) {
+    const title = toast.title?.trim() ?? "";
+    const message = toast.message.trim();
+    const fallback = toast.type === "success"
+        ? strings.successTitle
+        : toast.type === "error"
+            ? strings.errorTitle
+            : toast.type === "warning"
+                ? strings.warningTitle
+                : strings.infoTitle;
+    return {
+        title,
+        message,
+        // The title, or the message when there is no title.
+        headerTitle: title || message || fallback,
+        // The message, under a title that says something else.
+        secondLine: title && message && message !== title ? message : "",
+    };
+}
+/**
+ * True when the toast has to stay until a person has dealt with it, which
+ * makes it the one a `max` never drops: an error, one with an action, one
+ * with no end (`"persistent"`, or text too long to read in `long`).
+ */
+export function toastStays(toast, defaultDuration) {
+    const title = toast.title?.trim() ?? "";
+    const message = toast.message.trim();
+    const textLength = (title || message).length + (title && message && message !== title ? message.length : 0);
+    return (resolveToastDuration({ duration: toast.duration, type: toast.type, hasAction: !!toast.action, textLength }, defaultDuration) === 0);
+}
+/**
+ * Ids of toasts that a `max` is dropping to make room for a newer one. Such a
+ * toast leaves at once, without the exit motion: a newer toast is coming in
+ * where it is, and the two would otherwise lie on each other for a moment.
+ */
+export const toastsReplaced = new Set();
+/** The Material standard curve (`--ease-standard`), as an easing function for a script-driven slide. */
+export function easeStandard(t) {
+    const [x1, y1, x2, y2] = [0.2, 0, 0, 1];
+    const at = (a, b, s) => 3 * a * (1 - s) ** 2 * s + 3 * b * (1 - s) * s ** 2 + s ** 3;
+    let lo = 0;
+    let hi = 1;
+    let s = t;
+    for (let i = 0; i < 20; i++) {
+        s = (lo + hi) / 2;
+        if (at(x1, x2, s) < t)
+            lo = s;
+        else
+            hi = s;
+    }
+    return at(y1, y2, s);
+}
+/** A toast dragged further than this share of its width is dismissed, flick or not. */
+export const TOAST_SWIPE_DISMISS_FRACTION = 0.4;

package/dist/util/tone-surface.d.ts

@@ -0,0 +1,33 @@
+import type { SurfaceTone } from "../types/variants.js";
+export type ToneSurfaceOptions = {
+    tone?: SurfaceTone;
+    /** Any CSS colour for a fill the app chooses, such as `var(--group-colour)`. Wins over `tone`. */
+    fill?: string;
+    /** The label colour on `fill`, any CSS colour. Without it the label is the block's own text colour. */
+    onFill?: string;
+};
+export type ToneSurface = {
+    /** Utility classes for the fill and its on-colour scope; empty for `neutral`. */
+    classes: string;
+    /** Inline style for a custom fill, or undefined. */
+    style: string | undefined;
+    /** True when the surface is filled by tone or by `fill`, so the fill is its edge. */
+    filled: boolean;
+    /** True when the fill is the brand, the accent or a custom colour (the on-colour scope applies). */
+    scoped: boolean;
+};
+/**
+ * The classes and the inline style for a filled surface, shared by Card and Block.
+ *
+ * - `neutral` (the default): nothing, the component paints what it always did.
+ * - `tint`: the brand tint as a content surface. Text, links and rings are
+ *   guarded on it, so it needs no on-colour scope.
+ * - `brand` / `accent`: the fill and its `on-brand` / `on-accent` scope.
+ * - `fill`: the app's own colour. Wins over `tone`. The scope is `on-fill`,
+ *   with `onFill` as the label colour.
+ *
+ * The library cannot check the contrast of a `fill` and `onFill` pair: it is
+ * a colour the app picks at run time, so the app must hold the label to 4.5:1
+ * on the fill (3:1 for edges and focus rings).
+ */
+export declare function toneSurface({ tone, fill, onFill }: ToneSurfaceOptions): ToneSurface;

package/dist/util/tone-surface.js

@@ -0,0 +1,35 @@
+/**
+ * The classes and the inline style for a filled surface, shared by Card and Block.
+ *
+ * - `neutral` (the default): nothing, the component paints what it always did.
+ * - `tint`: the brand tint as a content surface. Text, links and rings are
+ *   guarded on it, so it needs no on-colour scope.
+ * - `brand` / `accent`: the fill and its `on-brand` / `on-accent` scope.
+ * - `fill`: the app's own colour. Wins over `tone`. The scope is `on-fill`,
+ *   with `onFill` as the label colour.
+ *
+ * The library cannot check the contrast of a `fill` and `onFill` pair: it is
+ * a colour the app picks at run time, so the app must hold the label to 4.5:1
+ * on the fill (3:1 for edges and focus rings).
+ */
+export function toneSurface({ tone = "neutral", fill, onFill }) {
+    if (fill) {
+        const parts = [`background-color: ${fill}`];
+        // --zabi-fill is the colour a solid control inside is lettered in when
+        // the scope inverts it; see `--zabi-inv-primary-text` in app.css.
+        parts.push(`--zabi-fill: ${fill}`);
+        if (onFill)
+            parts.push(`--zabi-on-fill: ${onFill}`);
+        return { classes: "on-fill", style: parts.join("; "), filled: true, scoped: true };
+    }
+    switch (tone) {
+        case "tint":
+            return { classes: "bg-card-tint", style: undefined, filled: true, scoped: false };
+        case "brand":
+            return { classes: "bg-action-primary on-brand", style: undefined, filled: true, scoped: true };
+        case "accent":
+            return { classes: "bg-accent on-accent", style: undefined, filled: true, scoped: true };
+        default:
+            return { classes: "", style: undefined, filled: false, scoped: false };
+    }
+}

package/dist/util/top-navbar.d.ts

@@ -2,9 +2,33 @@
 export interface TopNavbarStrings {
     /** Accessible name of the phone menu's button while the menu is closed. */
     openMenu: string;
-    /** The same button, while the menu is open. */
+    /** The same button, while the inline menu is open (the sheet's own button closes it). */
     closeMenu: string;
+    /** The phone menu's sheet: its heading and its accessible name, and the name of the links' `nav` when the bar has no `ariaLabel`. */
+    menuTitle?: string;
+    /** The heading over the theme choice in the phone menu's sheet. */
+    themeHeading?: string;
     /** Read after the label of a link that opens in a new tab. */
     opensInNewTab: string;
 }
-export declare const DEFAULT_TOP_NAVBAR_STRINGS: TopNavbarStrings;
+/**
+ * Every word, including the optional ones: `menuTitle` and `themeHeading` are
+ * optional in `TopNavbarStrings` so that code written before they existed, with
+ * a complete object, still type-checks.
+ */
+export declare const DEFAULT_TOP_NAVBAR_STRINGS: Required<TopNavbarStrings>;
+/**
+ * Where a piece of the bar's `actions` is drawn: in the `bar`, or in the
+ * `menu` sheet that opens below `collapseAt`, where it has the full width.
+ */
+export type TopNavbarPlace = "bar" | "menu";
+/** Called by the sheet's content: everything rendered inside it reads `"menu"`. */
+export declare function markTopNavbarPlace(place: TopNavbarPlace): void;
+/**
+ * Where the component calling this is drawn. Call it while the component
+ * initialises. A control in a TopNavbar's `actions` snippet can then draw
+ * itself large in the sheet and compact in the bar, with no argument to the
+ * snippet: `{#snippet actions()}<MyPicker />{/snippet}` keeps working. Outside
+ * a TopNavbar, in the bar and in `menu="inline"` it is `"bar"`.
+ */
+export declare function getTopNavbarPlace(): TopNavbarPlace;