zabi-components 7.0.2 → 8.1.0

package/dist/util/collapsible.d.ts

@@ -0,0 +1,57 @@
+/** Types and pure helpers for `Collapsible` and `CollapsibleGroup`. Kept out of the components so they can be tested without a DOM. */
+/** Heading element the default trigger is wrapped in. */
+export type CollapsibleHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * First argument of the `trigger` snippet. Spread it on your own `<button>`:
+ * it carries the whole wiring, so the button needs nothing else to work.
+ */
+export type CollapsibleTriggerProps = {
+    id: string;
+    /** Keeps a trigger inside a `<form>` from submitting it. */
+    type: "button";
+    "aria-expanded": boolean;
+    "aria-controls": string;
+    disabled: boolean;
+    onclick: (event: MouseEvent) => void;
+    /** How a `CollapsibleGroup` finds its header buttons for the arrow keys. */
+    "data-collapsible-trigger": "";
+};
+/** Second argument of the `trigger` snippet. */
+export interface CollapsibleTriggerState {
+    open: boolean;
+    disabled: boolean;
+}
+/** What a `Collapsible` hands its group. */
+export interface CollapsibleGroupMember {
+    triggerId: string;
+    isOpen: () => boolean;
+    /** A disabled member keeps its state: the group neither closes it nor counts it. */
+    isDisabled: () => boolean;
+    close: () => void;
+}
+/** What a member gets back when it joins a group. */
+export interface CollapsibleGroupRegistration {
+    /** Removes the member again. */
+    unregister: () => void;
+    /**
+     * True when the member asked to start open in a single-open group that
+     * already has an open panel. The member then renders closed from the
+     * start, on the server too, instead of opening and being closed again.
+     */
+    startClosed: boolean;
+}
+/** What a `CollapsibleGroup` offers the Collapsibles inside it, through context. */
+export interface CollapsibleGroupContext {
+    /** False when opening one panel closes the others. */
+    readonly multiple: boolean;
+    register: (member: CollapsibleGroupMember) => CollapsibleGroupRegistration;
+    /** Called whenever a member is open, however it got there. */
+    opened: (member: CollapsibleGroupMember) => void;
+}
+/** Context key shared by the two components. */
+export declare const COLLAPSIBLE_GROUP: unique symbol;
+/**
+ * Index of the header button an accordion key moves focus to, or `null` when
+ * the key is not one of them. Arrow keys wrap, as they do in Tabs and Dropdown.
+ */
+export declare function nextTriggerIndex(key: string, current: number, count: number): number | null;

package/dist/util/collapsible.js

@@ -0,0 +1,23 @@
+/** Types and pure helpers for `Collapsible` and `CollapsibleGroup`. Kept out of the components so they can be tested without a DOM. */
+/** Context key shared by the two components. */
+export const COLLAPSIBLE_GROUP = Symbol("zabi-collapsible-group");
+/**
+ * Index of the header button an accordion key moves focus to, or `null` when
+ * the key is not one of them. Arrow keys wrap, as they do in Tabs and Dropdown.
+ */
+export function nextTriggerIndex(key, current, count) {
+    if (count === 0)
+        return null;
+    switch (key) {
+        case "ArrowDown":
+            return (current + 1) % count;
+        case "ArrowUp":
+            return (current - 1 + count) % count;
+        case "Home":
+            return 0;
+        case "End":
+            return count - 1;
+        default:
+            return null;
+    }
+}

package/dist/util/confirm-dialog.d.ts

@@ -0,0 +1,11 @@
+/** Public types for `ConfirmDialog`. */
+/** Sets the confirm button's style and the icon beside the message. */
+export type ConfirmDialogVariant = "danger" | "warning" | "info";
+/** How the user backed out: the cancel button, or one of Modal's own ways to close. */
+export type ConfirmDialogCancelReason = "cancel-button" | "escape" | "backdrop" | "close-button";
+/**
+ * What `onconfirm` may return. `false`, returned or resolved, keeps the dialog
+ * open; anything else closes it. A promise puts the dialog in its loading
+ * state until it settles.
+ */
+export type ConfirmDialogResult = void | boolean | Promise<void | boolean>;

package/dist/util/confirm-dialog.js

@@ -0,0 +1,2 @@
+/** Public types for `ConfirmDialog`. */
+export {};

package/dist/util/date.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Calendar dates as strings: `YYYY-MM-DD` for a day, `YYYY-MM` for a month,
+ * `HH:mm` (or `HH:mm:ss`) for a time of day. The formats a native date or
+ * time input reads and writes.
+ *
+ * A date here is a day on the calendar, not a moment. Nothing in this file
+ * goes through a local `Date`: the arithmetic is on the numbers, or on UTC,
+ * where every day has 24 hours. So a date never moves to the day before or
+ * after because of a time zone, and a day on which the clocks change is a day
+ * like any other.
+ *
+ * Years 0001 to 9999, four digits: within that, two dates compare as strings.
+ */
+export interface DateParts {
+    year: number;
+    /** 1 to 12. */
+    month: number;
+    day: number;
+}
+export declare function isLeapYear(year: number): boolean;
+/** Days in a month; `month` is 1 to 12. */
+export declare function daysInMonth(year: number, month: number): number;
+/** The parts of a `YYYY-MM-DD` string, or null when it is not a real date. */
+export declare function parseIsoDate(value: string | null | undefined): DateParts | null;
+export declare function isIsoDate(value: string | null | undefined): value is string;
+/** The parts of a `YYYY-MM` string, or null when it is not a real month. */
+export declare function parseIsoMonth(value: string | null | undefined): {
+    year: number;
+    month: number;
+} | null;
+export declare function toIsoDate(year: number, month: number, day: number): string;
+export declare function toIsoMonth(year: number, month: number): string;
+/** The month a date is in: `2026-10-06` gives `2026-10`. Null for a string that is not a date. */
+export declare function monthOf(date: string | null | undefined): string | null;
+/** The date `count` days later (earlier when negative), or null outside years 1 to 9999. */
+export declare function addDays(date: string, count: number): string | null;
+/** The month `count` months later (earlier when negative), or null outside years 1 to 9999. */
+export declare function addMonthsToMonth(month: string, count: number): string | null;
+/**
+ * The same day of the month `count` months later. A day the target month does
+ * not have becomes its last one: 31 January plus a month is 28 or 29 February.
+ */
+export declare function addMonths(date: string, count: number): string | null;
+/** Day of the week, 0 for Sunday to 6 for Saturday. -1 for a string that is not a date. */
+export declare function weekdayOf(date: string): number;
+/** A whole number from 0 to 6 for the first day of the week; anything else is Monday. */
+export declare function normaliseWeekStart(weekStartsOn: number | undefined): number;
+/** The first day of the week a date is in. */
+export declare function startOfWeek(date: string, weekStartsOn?: number): string | null;
+/** The last day of the week a date is in. */
+export declare function endOfWeek(date: string, weekStartsOn?: number): string | null;
+/**
+ * The weeks of a month, each seven entries from the first day of the week. A
+ * day of the month is its ISO date; a place before the 1st or after the last
+ * day is null. There are as many weeks as the month touches: four (a
+ * 28-day February that starts on the first day of the week), five or six.
+ */
+export declare function monthGrid(month: string, weekStartsOn?: number): (string | null)[][];
+/** The seven days of the week as numbers (0 for Sunday), from the first day of the week. */
+export declare function weekdayOrder(weekStartsOn?: number): number[];
+/**
+ * Today where the user is, as `YYYY-MM-DD`. This is the one place that reads
+ * the local clock: "today" is a local idea. Call it in the browser; on a
+ * server it is the server's day.
+ */
+export declare function todayIso(now?: Date): string;
+/** Today in UTC: the same on a server and in a browser at the same moment. */
+export declare function todayIsoUtc(now?: Date): string;
+/** A date held between `min` and `max`, either of which may be missing or invalid. */
+export declare function clampDate(date: string, min?: string | null, max?: string | null): string;
+/**
+ * A date for reading: `formatDate("2026-10-06", "sv")` is "6 okt. 2026",
+ * `formatDate("2026-10-06", "en-GB")` is "6 Oct 2026".
+ *
+ * `value` is `YYYY-MM-DD`, what a DateField holds. The day shown is always
+ * the day in the string: it does not depend on the time zone of the browser
+ * or the server. An empty or invalid value gives an empty string.
+ *
+ * Pass the `locale` of the page. Without it the runtime's own is used, which
+ * on a server is the server's and may differ from the reader's, so text
+ * rendered on the server and again in the browser may not match.
+ *
+ * `options` are those of `Intl.DateTimeFormat`; `timeZone` is not one you can
+ * set here.
+ */
+export declare function formatDate(value: string | null | undefined, locale?: string | string[], options?: Intl.DateTimeFormatOptions): string;
+/**
+ * A time of day for reading: `formatTime("19:00", "sv")` is "19:00",
+ * `formatTime("19:00", "en-US")` is "7:00 PM".
+ *
+ * `value` is `HH:mm` or `HH:mm:ss`, what a TimeField holds. It is a time on
+ * the clock, with no zone: nothing shifts it. An empty or invalid value gives
+ * an empty string. `locale` and `options` as for `formatDate`.
+ */
+export declare function formatTime(value: string | null | undefined, locale?: string | string[], options?: Intl.DateTimeFormatOptions): string;

package/dist/util/date.js

@@ -0,0 +1,237 @@
+/**
+ * Calendar dates as strings: `YYYY-MM-DD` for a day, `YYYY-MM` for a month,
+ * `HH:mm` (or `HH:mm:ss`) for a time of day. The formats a native date or
+ * time input reads and writes.
+ *
+ * A date here is a day on the calendar, not a moment. Nothing in this file
+ * goes through a local `Date`: the arithmetic is on the numbers, or on UTC,
+ * where every day has 24 hours. So a date never moves to the day before or
+ * after because of a time zone, and a day on which the clocks change is a day
+ * like any other.
+ *
+ * Years 0001 to 9999, four digits: within that, two dates compare as strings.
+ */
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const ISO_MONTH = /^(\d{4})-(\d{2})$/;
+const ISO_TIME = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?$/;
+const pad = (value, length = 2) => String(value).padStart(length, "0");
+export function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+}
+/** Days in a month; `month` is 1 to 12. */
+export function daysInMonth(year, month) {
+    if (month === 2)
+        return isLeapYear(year) ? 29 : 28;
+    return [4, 6, 9, 11].includes(month) ? 30 : 31;
+}
+/** The parts of a `YYYY-MM-DD` string, or null when it is not a real date. */
+export function parseIsoDate(value) {
+    const match = ISO_DATE.exec(value ?? "");
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    if (year < 1 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month))
+        return null;
+    return { year, month, day };
+}
+export function isIsoDate(value) {
+    return parseIsoDate(value) !== null;
+}
+/** The parts of a `YYYY-MM` string, or null when it is not a real month. */
+export function parseIsoMonth(value) {
+    const match = ISO_MONTH.exec(value ?? "");
+    if (!match)
+        return null;
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    if (year < 1 || month < 1 || month > 12)
+        return null;
+    return { year, month };
+}
+export function toIsoDate(year, month, day) {
+    return `${pad(year, 4)}-${pad(month)}-${pad(day)}`;
+}
+export function toIsoMonth(year, month) {
+    return `${pad(year, 4)}-${pad(month)}`;
+}
+/** The month a date is in: `2026-10-06` gives `2026-10`. Null for a string that is not a date. */
+export function monthOf(date) {
+    const parts = parseIsoDate(date);
+    return parts ? toIsoMonth(parts.year, parts.month) : null;
+}
+/**
+ * A UTC timestamp for the day. `Date.UTC` reads a year under 100 as 19xx, so
+ * the year is set afterwards.
+ */
+function utcOf({ year, month, day }) {
+    const date = new Date(Date.UTC(2000, month - 1, day));
+    date.setUTCFullYear(year);
+    return date;
+}
+function isoOfUtc(date) {
+    return toIsoDate(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate());
+}
+const inRange = (year) => year >= 1 && year <= 9999;
+/** The date `count` days later (earlier when negative), or null outside years 1 to 9999. */
+export function addDays(date, count) {
+    const parts = parseIsoDate(date);
+    if (!parts)
+        return null;
+    const moved = utcOf(parts);
+    moved.setUTCDate(moved.getUTCDate() + count);
+    return inRange(moved.getUTCFullYear()) ? isoOfUtc(moved) : null;
+}
+/** The month `count` months later (earlier when negative), or null outside years 1 to 9999. */
+export function addMonthsToMonth(month, count) {
+    const parts = parseIsoMonth(month);
+    if (!parts)
+        return null;
+    const index = parts.year * 12 + (parts.month - 1) + count;
+    const year = Math.floor(index / 12);
+    return inRange(year) ? toIsoMonth(year, (index % 12 + 12) % 12 + 1) : null;
+}
+/**
+ * The same day of the month `count` months later. A day the target month does
+ * not have becomes its last one: 31 January plus a month is 28 or 29 February.
+ */
+export function addMonths(date, count) {
+    const parts = parseIsoDate(date);
+    if (!parts)
+        return null;
+    const target = parseIsoMonth(addMonthsToMonth(toIsoMonth(parts.year, parts.month), count));
+    if (!target)
+        return null;
+    const day = Math.min(parts.day, daysInMonth(target.year, target.month));
+    return toIsoDate(target.year, target.month, day);
+}
+/** Day of the week, 0 for Sunday to 6 for Saturday. -1 for a string that is not a date. */
+export function weekdayOf(date) {
+    const parts = parseIsoDate(date);
+    return parts ? utcOf(parts).getUTCDay() : -1;
+}
+/** A whole number from 0 to 6 for the first day of the week; anything else is Monday. */
+export function normaliseWeekStart(weekStartsOn) {
+    return Number.isInteger(weekStartsOn) && weekStartsOn >= 0 && weekStartsOn <= 6
+        ? weekStartsOn
+        : 1;
+}
+/** The first day of the week a date is in. */
+export function startOfWeek(date, weekStartsOn = 1) {
+    const weekday = weekdayOf(date);
+    if (weekday === -1)
+        return null;
+    return addDays(date, -((weekday - normaliseWeekStart(weekStartsOn) + 7) % 7));
+}
+/** The last day of the week a date is in. */
+export function endOfWeek(date, weekStartsOn = 1) {
+    const start = startOfWeek(date, weekStartsOn);
+    return start ? addDays(start, 6) : null;
+}
+/**
+ * The weeks of a month, each seven entries from the first day of the week. A
+ * day of the month is its ISO date; a place before the 1st or after the last
+ * day is null. There are as many weeks as the month touches: four (a
+ * 28-day February that starts on the first day of the week), five or six.
+ */
+export function monthGrid(month, weekStartsOn = 1) {
+    const parts = parseIsoMonth(month);
+    if (!parts)
+        return [];
+    const first = toIsoDate(parts.year, parts.month, 1);
+    const lead = (weekdayOf(first) - normaliseWeekStart(weekStartsOn) + 7) % 7;
+    const days = daysInMonth(parts.year, parts.month);
+    const cells = Array.from({ length: lead }, () => null);
+    for (let day = 1; day <= days; day += 1)
+        cells.push(toIsoDate(parts.year, parts.month, day));
+    while (cells.length % 7 !== 0)
+        cells.push(null);
+    const weeks = [];
+    for (let index = 0; index < cells.length; index += 7)
+        weeks.push(cells.slice(index, index + 7));
+    return weeks;
+}
+/** The seven days of the week as numbers (0 for Sunday), from the first day of the week. */
+export function weekdayOrder(weekStartsOn = 1) {
+    const start = normaliseWeekStart(weekStartsOn);
+    return Array.from({ length: 7 }, (_, index) => (start + index) % 7);
+}
+/**
+ * Today where the user is, as `YYYY-MM-DD`. This is the one place that reads
+ * the local clock: "today" is a local idea. Call it in the browser; on a
+ * server it is the server's day.
+ */
+export function todayIso(now = new Date()) {
+    return toIsoDate(now.getFullYear(), now.getMonth() + 1, now.getDate());
+}
+/** Today in UTC: the same on a server and in a browser at the same moment. */
+export function todayIsoUtc(now = new Date()) {
+    return isoOfUtc(now);
+}
+/** A date held between `min` and `max`, either of which may be missing or invalid. */
+export function clampDate(date, min, max) {
+    if (isIsoDate(min) && date < min)
+        return min;
+    if (isIsoDate(max) && date > max)
+        return max;
+    return date;
+}
+function formatter(locale, options) {
+    try {
+        // Formatted in UTC, where the value was put: the reader's zone never moves it.
+        return new Intl.DateTimeFormat(locale || undefined, { ...options, timeZone: "UTC" });
+    }
+    catch {
+        // An unknown locale tag or option: fall back to the runtime's own.
+        try {
+            return new Intl.DateTimeFormat(undefined, { ...options, timeZone: "UTC" });
+        }
+        catch {
+            return null;
+        }
+    }
+}
+/**
+ * A date for reading: `formatDate("2026-10-06", "sv")` is "6 okt. 2026",
+ * `formatDate("2026-10-06", "en-GB")` is "6 Oct 2026".
+ *
+ * `value` is `YYYY-MM-DD`, what a DateField holds. The day shown is always
+ * the day in the string: it does not depend on the time zone of the browser
+ * or the server. An empty or invalid value gives an empty string.
+ *
+ * Pass the `locale` of the page. Without it the runtime's own is used, which
+ * on a server is the server's and may differ from the reader's, so text
+ * rendered on the server and again in the browser may not match.
+ *
+ * `options` are those of `Intl.DateTimeFormat`; `timeZone` is not one you can
+ * set here.
+ */
+export function formatDate(value, locale, options = { day: "numeric", month: "short", year: "numeric" }) {
+    const parts = parseIsoDate(value);
+    if (!parts)
+        return "";
+    return formatter(locale, options)?.format(utcOf(parts)) ?? value;
+}
+/**
+ * A time of day for reading: `formatTime("19:00", "sv")` is "19:00",
+ * `formatTime("19:00", "en-US")` is "7:00 PM".
+ *
+ * `value` is `HH:mm` or `HH:mm:ss`, what a TimeField holds. It is a time on
+ * the clock, with no zone: nothing shifts it. An empty or invalid value gives
+ * an empty string. `locale` and `options` as for `formatDate`.
+ */
+export function formatTime(value, locale, 
+// The locale's own short time: "07:05" in Swedish, "7:05 AM" in American English.
+options = { timeStyle: "short" }) {
+    const match = ISO_TIME.exec(value ?? "");
+    if (!match)
+        return "";
+    const hours = Number(match[1]);
+    const minutes = Number(match[2]);
+    const seconds = Number(match[3] ?? "0");
+    if (hours > 23 || minutes > 59 || seconds > 59)
+        return "";
+    const moment = new Date(Date.UTC(2000, 0, 1, hours, minutes, seconds));
+    return formatter(locale, options)?.format(moment) ?? value;
+}

package/dist/util/drawer.d.ts

@@ -0,0 +1,12 @@
+/** Public types and pure helpers for `Drawer`. */
+/**
+ * The edge the drawer is anchored to. `left` and `right` are physical and stay
+ * put in a right-to-left page; `start` and `end` follow the writing direction.
+ */
+export type DrawerSide = "left" | "right" | "start" | "end";
+/** Panel width on wide screens. On a phone the panel is never wider than the screen. */
+export type DrawerSize = "sm" | "md" | "lg";
+/** What the user did to close the drawer. The same values Modal reports. */
+export type DrawerCloseReason = "escape" | "backdrop" | "close-button";
+/** The physical edge a side resolves to, given the writing direction. */
+export declare function resolveDrawerEdge(side: DrawerSide, rtl: boolean): "left" | "right";

package/dist/util/drawer.js

@@ -0,0 +1,7 @@
+/** Public types and pure helpers for `Drawer`. */
+/** The physical edge a side resolves to, given the writing direction. */
+export function resolveDrawerEdge(side, rtl) {
+    if (side === "left" || side === "right")
+        return side;
+    return (side === "start") !== rtl ? "left" : "right";
+}

package/dist/util/dropdown.d.ts

@@ -0,0 +1,46 @@
+import type { Component } from "svelte";
+/** An icon component, as `@lucide/svelte` icons are. */
+export type DropdownItemIcon = Component<{
+    size?: number;
+    class?: string;
+}>;
+export type DropdownItemTone = "default" | "danger";
+/** One entry of Dropdown's `options`. */
+export interface DropdownOption {
+    value: string | number;
+    label: string;
+    /**
+     * A disabled item stays focusable, so the arrow keys still reach it and a
+     * screen reader can read why it is unavailable; it cannot be chosen.
+     */
+    disabled?: boolean;
+    /** Rendered before the label, at 16px. Decorative: the label names the item. */
+    icon?: DropdownItemIcon;
+    /** `danger` for a destructive action such as Delete. */
+    tone?: DropdownItemTone;
+    /** Second line under the label, e.g. why the item is disabled. */
+    description?: string;
+}
+/**
+ * How a Dropdown's menu is shown: `popover` under its trigger, `sheet` in a
+ * BottomSheet, or `auto`: a sheet on a phone, the pop-over everywhere else.
+ */
+export type DropdownPresentation = "auto" | "popover" | "sheet";
+/**
+ * A phone, for `auto`: a touch screen (`pointer: coarse`) narrower than the
+ * `sm` breakpoint. A tablet has the room for a pop-over under its trigger,
+ * and a narrow window with a mouse has the precision for one.
+ */
+export declare const SHEET_MEDIA_QUERY = "(pointer: coarse) and (max-width: 639.98px)";
+/**
+ * Whether a menu asked for as `presentation` opens in a sheet right now.
+ * Read when the menu opens, in the browser: on the server it is never a sheet,
+ * so what is rendered before anyone touches the control is the same everywhere.
+ */
+export declare function opensAsSheet(presentation: DropdownPresentation): boolean;
+/** What a Dropdown tells the items inside it. */
+export interface DropdownContext {
+    /** `option` inside a listbox, `menuitem` inside a menu. */
+    readonly itemRole: "menuitem" | "option";
+}
+export declare const DROPDOWN_CONTEXT_KEY: unique symbol;

package/dist/util/dropdown.js

@@ -0,0 +1,21 @@
+/**
+ * A phone, for `auto`: a touch screen (`pointer: coarse`) narrower than the
+ * `sm` breakpoint. A tablet has the room for a pop-over under its trigger,
+ * and a narrow window with a mouse has the precision for one.
+ */
+export const SHEET_MEDIA_QUERY = "(pointer: coarse) and (max-width: 639.98px)";
+/**
+ * Whether a menu asked for as `presentation` opens in a sheet right now.
+ * Read when the menu opens, in the browser: on the server it is never a sheet,
+ * so what is rendered before anyone touches the control is the same everywhere.
+ */
+export function opensAsSheet(presentation) {
+    if (presentation === "sheet")
+        return true;
+    if (presentation !== "auto")
+        return false;
+    return (typeof window !== "undefined" &&
+        typeof window.matchMedia === "function" &&
+        window.matchMedia(SHEET_MEDIA_QUERY).matches);
+}
+export const DROPDOWN_CONTEXT_KEY = Symbol("dropdown");

package/dist/util/field.d.ts

@@ -0,0 +1,38 @@
+/**
+ * What Input, Textarea and Select share about the text under a field, and
+ * DateField and TimeField through Input. Kept in one place so the four cannot
+ * drift: which message shows, in which variant, and what the control is
+ * described by.
+ */
+import type { SemanticVariant } from "../types/variants.js";
+export interface FieldMessageInput {
+    variant?: SemanticVariant;
+    message?: string;
+    hint?: string;
+    error?: string;
+}
+export interface FieldMessageState {
+    /** The variant the control is drawn in: `error` whenever there is an error. */
+    variant: SemanticVariant;
+    /** The text of the status message: the error, or else `message`. */
+    message: string;
+    /** Whether the status message is rendered. A `message` without a variant is not. */
+    showMessage: boolean;
+    /** Whether the hint is rendered. */
+    showHint: boolean;
+}
+/**
+ * `error` wins over `variant` and `message`: it sets the error variant and is
+ * the message. Without it, `message` shows in a `success`, `warning` or
+ * `error` variant, as it always has, and not in `default`: text for a field
+ * that is neither is a `hint`.
+ */
+export declare function fieldMessageState({ variant, message, hint, error, }: FieldMessageInput): FieldMessageState;
+export declare const fieldHintId: (fieldId: string) => string;
+export declare const fieldMessageId: (fieldId: string) => string;
+/**
+ * The ids a control is described by: the caller's own (a FormField around the
+ * field, say), then the hint, then the status message. Only ids of elements
+ * that are rendered; `undefined` when there are none, so no empty attribute.
+ */
+export declare function fieldDescribedBy(fieldId: string, state: Pick<FieldMessageState, "showMessage" | "showHint">, own?: string | null): string | undefined;

package/dist/util/field.js

@@ -0,0 +1,38 @@
+/**
+ * What Input, Textarea and Select share about the text under a field, and
+ * DateField and TimeField through Input. Kept in one place so the four cannot
+ * drift: which message shows, in which variant, and what the control is
+ * described by.
+ */
+/**
+ * `error` wins over `variant` and `message`: it sets the error variant and is
+ * the message. Without it, `message` shows in a `success`, `warning` or
+ * `error` variant, as it always has, and not in `default`: text for a field
+ * that is neither is a `hint`.
+ */
+export function fieldMessageState({ variant = "default", message = "", hint = "", error = "", }) {
+    const resolvedVariant = error ? "error" : variant;
+    const resolvedMessage = error || message;
+    return {
+        variant: resolvedVariant,
+        message: resolvedMessage,
+        showMessage: !!resolvedMessage && resolvedVariant !== "default",
+        showHint: !!hint,
+    };
+}
+export const fieldHintId = (fieldId) => `${fieldId}-hint`;
+export const fieldMessageId = (fieldId) => `${fieldId}-message`;
+/**
+ * The ids a control is described by: the caller's own (a FormField around the
+ * field, say), then the hint, then the status message. Only ids of elements
+ * that are rendered; `undefined` when there are none, so no empty attribute.
+ */
+export function fieldDescribedBy(fieldId, state, own) {
+    return ([
+        own,
+        state.showHint ? fieldHintId(fieldId) : "",
+        state.showMessage ? fieldMessageId(fieldId) : "",
+    ]
+        .filter(Boolean)
+        .join(" ") || undefined);
+}