zabi-components 8.0.0 → 9.0.0

package/dist/util/toaster.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Every word a `Toaster` says by itself. An app in another language passes
+ * its own through `strings`; what it leaves out stays as it is here.
+ */
+export interface ToasterStrings {
+    /** Accessible name of the region the toasts are in. */
+    regionLabel: string;
+    /**
+     * What a toast says when it was pushed with neither a `title` nor a
+     * `message`, by type. A toast with a message shows the message.
+     */
+    successTitle: string;
+    errorTitle: string;
+    warningTitle: string;
+    infoTitle: string;
+    /** The time a toast has left, while its timer runs. */
+    closesIn: (seconds: number) => string;
+    /** The same, while a pointer, a finger or focus holds the timer. */
+    pausedClosesIn: (seconds: number) => string;
+    /** The button that stops the timer; shown with `showCountdown`. */
+    stop: string;
+    /** The button under a toast's opened details, which closes them again. */
+    okay: string;
+    /** Accessible name of the button that opens a toast's details. */
+    expand: string;
+    /** The same button, once they are open. */
+    collapse: string;
+    /** Accessible name of the button that dismisses a toast. */
+    dismiss: string;
+    /**
+     * Read after a toast's text when it has an action, so a screen reader
+     * user hears that there is one. `label` is the action's own.
+     */
+    actionAvailable: (label: string) => string;
+}
+export declare const DEFAULT_TOASTER_STRINGS: ToasterStrings;
+/**
+ * The three lengths a toast can be given by name, in milliseconds.
+ *
+ * `short` (3 s) is for a few words that need no reading time ("Saved").
+ * Anything a person has to read is `medium` (7 s) or `long` (14 s). What
+ * they have to act on, and an error, should stay: `"persistent"`.
+ */
+export declare const TOAST_DURATIONS: {
+    readonly short: 3000;
+    readonly medium: 7000;
+    readonly long: 14000;
+};
+/**
+ * How long a toast stays: one of the named lengths, `"persistent"` (until it
+ * is dismissed), or a number of milliseconds, where `0` is persistent too.
+ */
+export type ToastDuration = keyof typeof TOAST_DURATIONS | "persistent" | number;
+/**
+ * A toast with more visible text than this (title and message together) gets
+ * `long` when the app gave it no duration.
+ */
+export declare const TOAST_LONG_TEXT_LENGTH = 120;
+/**
+ * And one with more than this stays until it is dismissed: `long` was
+ * measured as too short to read it in, and nothing longer has a name.
+ */
+export declare const TOAST_PERSISTENT_TEXT_LENGTH = 240;
+/**
+ * How long a toast stays, in milliseconds; `0` is until it is dismissed.
+ *
+ * What the app said for the toast wins, whatever the toast is. When it said
+ * nothing: an error stays, and so does a toast with an action, since the user
+ * has to be able to reach the button. So does a text longer than
+ * `TOAST_PERSISTENT_TEXT_LENGTH`, whatever the Toaster's default. Everything
+ * else gets the Toaster's `defaultDuration`, or `medium` without one; a text
+ * longer than `TOAST_LONG_TEXT_LENGTH` gets `long`, unless the default is
+ * longer still.
+ */
+export declare function resolveToastDuration(toast: {
+    duration?: ToastDuration;
+    type: string;
+    hasAction: boolean;
+    textLength: number;
+}, defaultDuration?: ToastDuration): number;
+/**
+ * The least a toast has left when a finger that held it lifts, in seconds.
+ * As long as `short`: holding a short toast starts it again, in effect.
+ */
+export declare const TOAST_SECONDS_AFTER_HOLD = 3;
+/** What `onpausechange` of a `Toaster` is called with. */
+export interface ToastPauseChange {
+    /** The id of the toast, as `pushToast` returned it. */
+    id: string;
+    /** 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

@@ -0,0 +1,130 @@
+export const DEFAULT_TOASTER_STRINGS = {
+    regionLabel: "Notifications",
+    successTitle: "Changes saved",
+    errorTitle: "Something went wrong",
+    warningTitle: "Please review",
+    infoTitle: "Notice",
+    closesIn: (seconds) => `This message will close in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
+    pausedClosesIn: (seconds) => `Paused — closes in ${seconds} ${seconds === 1 ? "second" : "seconds"}.`,
+    stop: "Click to stop",
+    okay: "Okay",
+    expand: "Expand details",
+    collapse: "Collapse details",
+    dismiss: "Dismiss notification",
+    actionAvailable: (label) => `${label} available.`,
+};
+/**
+ * The three lengths a toast can be given by name, in milliseconds.
+ *
+ * `short` (3 s) is for a few words that need no reading time ("Saved").
+ * Anything a person has to read is `medium` (7 s) or `long` (14 s). What
+ * they have to act on, and an error, should stay: `"persistent"`.
+ */
+export const TOAST_DURATIONS = { short: 3000, medium: 7000, long: 14000 };
+/**
+ * A toast with more visible text than this (title and message together) gets
+ * `long` when the app gave it no duration.
+ */
+export const TOAST_LONG_TEXT_LENGTH = 120;
+/**
+ * And one with more than this stays until it is dismissed: `long` was
+ * measured as too short to read it in, and nothing longer has a name.
+ */
+export const TOAST_PERSISTENT_TEXT_LENGTH = 240;
+/** The milliseconds of a duration, `0` for one that stays; `undefined` for what is not a duration. */
+function toastDurationMs(duration) {
+    if (duration === "persistent")
+        return 0;
+    if (typeof duration === "string") {
+        return Object.prototype.hasOwnProperty.call(TOAST_DURATIONS, duration)
+            ? TOAST_DURATIONS[duration]
+            : undefined;
+    }
+    if (typeof duration !== "number" || Number.isNaN(duration))
+        return undefined;
+    return duration <= 0 ? 0 : duration;
+}
+/**
+ * How long a toast stays, in milliseconds; `0` is until it is dismissed.
+ *
+ * What the app said for the toast wins, whatever the toast is. When it said
+ * nothing: an error stays, and so does a toast with an action, since the user
+ * has to be able to reach the button. So does a text longer than
+ * `TOAST_PERSISTENT_TEXT_LENGTH`, whatever the Toaster's default. Everything
+ * else gets the Toaster's `defaultDuration`, or `medium` without one; a text
+ * longer than `TOAST_LONG_TEXT_LENGTH` gets `long`, unless the default is
+ * longer still.
+ */
+export function resolveToastDuration(toast, defaultDuration) {
+    const said = toastDurationMs(toast.duration);
+    if (said !== undefined)
+        return said;
+    if (toast.type === "error" || toast.hasAction)
+        return 0;
+    if (toast.textLength > TOAST_PERSISTENT_TEXT_LENGTH)
+        return 0;
+    const base = toastDurationMs(defaultDuration) ?? TOAST_DURATIONS.medium;
+    if (base === 0 || toast.textLength <= TOAST_LONG_TEXT_LENGTH)
+        return base;
+    return Math.max(base, TOAST_DURATIONS.long);
+}
+/**
+ * The least a toast has left when a finger that held it lifts, in seconds.
+ * 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/tooltip.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One tooltip at a time. A tooltip that opens closes the one that was open: a
+ * mouse resting on one trigger while Tab moves focus to another would
+ * otherwise show both, one of them stale.
+ */
+/** Called by a tooltip as it opens, with what closes it. Closes any other. */
+export declare function claimOpenTooltip(close: () => void): void;
+/** Called by a tooltip as it closes or goes. */
+export declare function releaseOpenTooltip(close: () => void): void;

package/dist/util/tooltip.js

@@ -0,0 +1,18 @@
+/**
+ * One tooltip at a time. A tooltip that opens closes the one that was open: a
+ * mouse resting on one trigger while Tab moves focus to another would
+ * otherwise show both, one of them stale.
+ */
+/** The tooltip that is open, as the function that closes it. */
+let closeOpen = null;
+/** Called by a tooltip as it opens, with what closes it. Closes any other. */
+export function claimOpenTooltip(close) {
+    if (closeOpen && closeOpen !== close)
+        closeOpen();
+    closeOpen = close;
+}
+/** Called by a tooltip as it closes or goes. */
+export function releaseOpenTooltip(close) {
+    if (closeOpen === close)
+        closeOpen = null;
+}

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

@@ -0,0 +1,34 @@
+/** The words `TopNavbar` says by itself. Pass any of them as `strings`. */
+export interface TopNavbarStrings {
+    /** Accessible name of the phone menu's button while the menu is closed. */
+    openMenu: string;
+    /** 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;
+}
+/**
+ * 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;

package/dist/util/top-navbar.js

@@ -0,0 +1,28 @@
+import { getContext, setContext } from "svelte";
+/**
+ * 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 const DEFAULT_TOP_NAVBAR_STRINGS = {
+    openMenu: "Open menu",
+    closeMenu: "Close menu",
+    menuTitle: "Menu",
+    themeHeading: "Theme",
+    opensInNewTab: "(opens in a new tab)",
+};
+const TOP_NAVBAR_PLACE = Symbol.for("zabi-components.top-navbar-place");
+/** Called by the sheet's content: everything rendered inside it reads `"menu"`. */
+export function markTopNavbarPlace(place) {
+    setContext(TOP_NAVBAR_PLACE, place);
+}
+/**
+ * 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 function getTopNavbarPlace() {
+    return getContext(TOP_NAVBAR_PLACE) ?? "bar";
+}

package/dist/util/touch-target.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Touch targets: 44 by 44px on a coarse pointer, nothing changed on a fine one.
+ *
+ * There are two ways to get there, and which one a control takes depends on
+ * what stands beside it.
+ *
+ * 1. The control itself grows: `pointer-coarse:min-h-11` (and `min-w-11` for a
+ *    square one), written where the size is. Button, IconButton, Input and
+ *    Select do this at `sm` and `md`, so a row of them still lines up; so does
+ *    any control that has a neighbour close by (the handle and the move
+ *    buttons of a SortableList row). `scripts/check-control-geometry.js` holds
+ *    the shared controls to it.
+ *
+ * 2. The control keeps its size and an invisible layer around it takes the
+ *    touch: `TOUCH_HIT_AREA` below. Only for a control that stands alone, with
+ *    nothing pressable within about 10px: a close button in the corner of an
+ *    Alert or in the header of a Modal, the switch of a Toggle. The layer
+ *    reaches past the visible box, so beside another control it would cover
+ *    that control's edge and a tap there would fire the wrong one. An `xs`
+ *    IconButton had such a layer and lost it for that reason. A Toggle is
+ *    stacked in settings lists, so its row is 44px tall on a coarse pointer:
+ *    the layer of one switch then never reaches the switch above or below.
+ */
+/**
+ * An invisible hit area of at least 44 by 44px, centred on the element, on a
+ * coarse pointer only. The element must be positioned (`relative`, `absolute`
+ * or `fixed`; `pointer-coarse:relative` where it was not positioned before, so
+ * a fine pointer sees no change) and must not clip its overflow.
+ */
+export declare const TOUCH_HIT_AREA = "pointer-coarse:before:absolute pointer-coarse:before:top-1/2 pointer-coarse:before:left-1/2 pointer-coarse:before:size-full pointer-coarse:before:min-h-11 pointer-coarse:before:min-w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-['']";

package/dist/util/touch-target.js

@@ -0,0 +1,30 @@
+/**
+ * Touch targets: 44 by 44px on a coarse pointer, nothing changed on a fine one.
+ *
+ * There are two ways to get there, and which one a control takes depends on
+ * what stands beside it.
+ *
+ * 1. The control itself grows: `pointer-coarse:min-h-11` (and `min-w-11` for a
+ *    square one), written where the size is. Button, IconButton, Input and
+ *    Select do this at `sm` and `md`, so a row of them still lines up; so does
+ *    any control that has a neighbour close by (the handle and the move
+ *    buttons of a SortableList row). `scripts/check-control-geometry.js` holds
+ *    the shared controls to it.
+ *
+ * 2. The control keeps its size and an invisible layer around it takes the
+ *    touch: `TOUCH_HIT_AREA` below. Only for a control that stands alone, with
+ *    nothing pressable within about 10px: a close button in the corner of an
+ *    Alert or in the header of a Modal, the switch of a Toggle. The layer
+ *    reaches past the visible box, so beside another control it would cover
+ *    that control's edge and a tap there would fire the wrong one. An `xs`
+ *    IconButton had such a layer and lost it for that reason. A Toggle is
+ *    stacked in settings lists, so its row is 44px tall on a coarse pointer:
+ *    the layer of one switch then never reaches the switch above or below.
+ */
+/**
+ * An invisible hit area of at least 44 by 44px, centred on the element, on a
+ * coarse pointer only. The element must be positioned (`relative`, `absolute`
+ * or `fixed`; `pointer-coarse:relative` where it was not positioned before, so
+ * a fine pointer sees no change) and must not clip its overflow.
+ */
+export const TOUCH_HIT_AREA = "pointer-coarse:before:absolute pointer-coarse:before:top-1/2 pointer-coarse:before:left-1/2 pointer-coarse:before:size-full pointer-coarse:before:min-h-11 pointer-coarse:before:min-w-11 pointer-coarse:before:-translate-x-1/2 pointer-coarse:before:-translate-y-1/2 pointer-coarse:before:content-['']";

package/dist/util/zabi-strings.d.ts

@@ -0,0 +1,141 @@
+import type { AvatarGroupStrings } from "./avatar.js";
+import type { CalendarStrings } from "./calendar.js";
+import type { DateFieldStrings, TimeFieldStrings } from "./temporal-field.js";
+import type { MediaGridStrings } from "./media-grid.js";
+import type { CodeFieldStrings } from "./code-field.js";
+import type { PhotoGridStrings, PhotoViewerStrings } from "./photo.js";
+import type { ProgressStrings } from "./progress.js";
+import type { PullToRefreshStrings } from "./pull-to-refresh.js";
+import type { RatingStrings } from "./rating.js";
+import type { ColorPickerStrings, ComponentDemoStrings, ContactFormStrings, PropsTableStrings } from "./ready-made-strings.js";
+import type { SelectStrings } from "./select.js";
+import type { SkeletonStrings } from "./skeleton.js";
+import type { SidebarAccountPanelStrings, SidebarBrandHeaderStrings, SidebarFooterStrings, SidebarNavigationStrings } from "./sidebar.js";
+import type { SortableListStrings } from "./sortable-list.js";
+import type { StepperStrings } from "./stepper.js";
+import type { SwipeableListItemStrings } from "./swipeable-list-item.js";
+import type { ThemeToggleLabels } from "./theme-mode.js";
+import type { ToasterStrings } from "./toaster.js";
+import type { TopNavbarStrings } from "./top-navbar.js";
+/**
+ * The few words that many components' single-text props default to. A
+ * component whose prop is not given says the one here.
+ */
+export interface ZabiCommonStrings {
+    /** The close button of a dialog, a drawer or a sheet (`closeLabel`). */
+    close: string;
+    /** AppBar's back control (`backLabel`). */
+    back: string;
+    /** A sheet's grip while it takes the sheet up a step (`expandLabel`). */
+    expand: string;
+    /** The same, while it takes it down (`collapseLabel`). */
+    collapse: string;
+    /** Read after the label of a required field (FormField's `requiredLabel`). */
+    required: string;
+    /** The button in a password field that shows what was typed (Input's `revealLabel`). */
+    showPassword: string;
+    /** Placeholder of a search field in a sidebar (`searchPlaceholder`). */
+    search: string;
+    /** ConfirmDialog's confirming button (`confirmLabel`). */
+    confirm: string;
+    /** ConfirmDialog's other button (`cancelLabel`). */
+    cancel: string;
+}
+export declare const DEFAULT_ZABI_COMMON_STRINGS: ZabiCommonStrings;
+/** Toast's own text: `closeLabel`. */
+export interface ToastTexts {
+    closeLabel: string;
+}
+export declare const DEFAULT_TOAST_TEXTS: ToastTexts;
+/** Alert's own text: `closeLabel`. */
+export interface AlertTexts {
+    closeLabel: string;
+}
+export declare const DEFAULT_ALERT_TEXTS: AlertTexts;
+/** CodeBlock's own texts: the copy button's name, and what is announced once copied. */
+export interface CodeBlockTexts {
+    copyLabel: string;
+    copiedLabel: string;
+}
+export declare const DEFAULT_CODE_BLOCK_TEXTS: CodeBlockTexts;
+/** ImageUpload's own texts, by the name of the prop each one is. */
+export interface ImageUploadTexts {
+    placeholder: string;
+    browseText: string;
+    changeText: string;
+    removeText: string;
+    selectedText: string;
+    removedText: string;
+    errorTitle: string;
+    errorRecovery: string;
+}
+export declare const DEFAULT_IMAGE_UPLOAD_TEXTS: ImageUploadTexts;
+/** UnsavedChangesBar's own texts, by the name of the prop each one is. */
+export interface UnsavedChangesBarTexts {
+    message: string;
+    label: string;
+    saveLabel: string;
+    discardLabel: string;
+}
+export declare const DEFAULT_UNSAVED_CHANGES_BAR_TEXTS: UnsavedChangesBarTexts;
+/** One optional entry per component that has words of its own, and `common`. */
+export interface ZabiStrings {
+    common?: Partial<ZabiCommonStrings>;
+    alert?: Partial<AlertTexts>;
+    avatarGroup?: Partial<AvatarGroupStrings>;
+    calendar?: Partial<CalendarStrings>;
+    codeBlock?: Partial<CodeBlockTexts>;
+    codeField?: Partial<CodeFieldStrings>;
+    colorPicker?: Partial<ColorPickerStrings>;
+    dateField?: Partial<DateFieldStrings>;
+    componentDemo?: Partial<ComponentDemoStrings>;
+    contactForm?: Partial<ContactFormStrings>;
+    imageUpload?: Partial<ImageUploadTexts>;
+    mediaGrid?: Partial<MediaGridStrings>;
+    photoGrid?: Partial<PhotoGridStrings>;
+    photoViewer?: Partial<PhotoViewerStrings>;
+    propsTable?: Partial<PropsTableStrings>;
+    progress?: Partial<ProgressStrings>;
+    pullToRefresh?: Partial<PullToRefreshStrings>;
+    rating?: Partial<RatingStrings>;
+    select?: Partial<SelectStrings>;
+    skeleton?: Partial<SkeletonStrings>;
+    sidebarAccountPanel?: Partial<SidebarAccountPanelStrings>;
+    sidebarBrandHeader?: Partial<SidebarBrandHeaderStrings>;
+    sidebarFooter?: Partial<SidebarFooterStrings>;
+    sidebarNavigation?: Partial<SidebarNavigationStrings>;
+    sortableList?: Partial<SortableListStrings>;
+    stepper?: Partial<StepperStrings>;
+    swipeableListItem?: Partial<SwipeableListItemStrings>;
+    themeToggle?: Partial<ThemeToggleLabels>;
+    timeField?: Partial<TimeFieldStrings>;
+    toast?: Partial<ToastTexts>;
+    toaster?: Partial<ToasterStrings>;
+    topNavbar?: Partial<TopNavbarStrings>;
+    unsavedChangesBar?: Partial<UnsavedChangesBarTexts>;
+}
+/** What the context holds: an object whose `current` is read when it is needed, so a change reaches every reader. */
+export interface ZabiStringsContext {
+    readonly current: ZabiStrings;
+}
+/** `over` on top of `under`, entry by entry: an inner provider only replaces the words it gives. */
+export declare function mergeZabiStrings(under: ZabiStrings | undefined, over: ZabiStrings | undefined): ZabiStrings;
+/** For `ZabiStringsProvider`: the provider above this one, if any. Call while the component initialises. */
+export declare function outerZabiStrings(): ZabiStringsContext | undefined;
+/** For `ZabiStringsProvider`: makes `context` what everything below reads. */
+export declare function provideZabiStrings(context: ZabiStringsContext): void;
+/**
+ * The words of the provider this component is under, for app code that wants
+ * the same words elsewhere. Call it while the component initialises, and read
+ * `current` where the words are used (in the markup, or a `$derived`), so a
+ * change of language is followed. Outside a provider `current` is empty.
+ */
+export declare function getZabiStrings(): ZabiStringsContext;
+/**
+ * A component's own entry: `zabiStringsFor("select")` returns a function that
+ * gives the provider's words for Select now, or undefined. Call it while the
+ * component initialises; call what it returns inside a `$derived`.
+ */
+export declare function zabiStringsFor<K extends Exclude<keyof ZabiStrings, "common">>(key: K): () => ZabiStrings[K];
+/** The common words with their defaults filled in, the same way. */
+export declare function zabiCommonStrings(): () => ZabiCommonStrings;