zabi-components 8.0.0 → 9.0.0

package/dist/util/display-voice.js

@@ -0,0 +1,9 @@
+/**
+ * The display voice: the weight and tracking of a figure or a display line.
+ * Both are read from custom properties that are declared nowhere, so any
+ * ancestor can set them (`--zabi-display-weight: 400` for a light serif) and
+ * the defaults are what the display face looked like before. The `number:`
+ * hint is what makes Tailwind read the weight as a weight and not a family.
+ * Heading `variant="display"` and Stat share this string.
+ */
+export const displayVoice = "font-[number:var(--zabi-display-weight,700)] tracking-[var(--zabi-display-tracking,-0.02em)]";

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-control.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The look of a field-shaped control's box: Select's trigger and native select
+ * and PickerField draw it from here, so a picker beside a Select is the same
+ * box. Kept in one place so they cannot drift.
+ */
+export type FieldControlSize = "sm" | "md" | "lg";
+export interface FieldControlSizeClasses {
+    /** The trigger's box: a minimum height, so a label that wraps makes it taller. */
+    box: string;
+    /** The text size: 16px below `sm`, as Input. */
+    text: string;
+    /** The same box for a native `<select>`, which is always one line. */
+    native: string;
+    /** Where the trailing chevron sits. */
+    chevron: string;
+}
+/**
+ * Same fixed height scale as Button, IconButton and Input (32 / 40 / 48), and
+ * the same 16px text below `sm`. One line is exactly 32, 40 or 48px: the
+ * padding leaves room for the line and the border inside it, and is a step
+ * smaller below `sm`, where the text is 16px on a 24px line.
+ */
+export declare function fieldControlSize(size: FieldControlSize): FieldControlSizeClasses;
+/** The edge colour for a status: the field's own, or the status colour. */
+export declare function fieldControlEdge(variant: string): string;
+/** The field's surface, edge and states. */
+export declare const FIELD_CONTROL_SURFACE = "focus-ring w-full min-w-0 cursor-pointer rounded-control border bg-input text-body transition-colors duration-(--duration-base) hover:bg-input-hover active:bg-input-active focus-visible:bg-input-focus focus:outline-none focus-visible:outline-none disabled:cursor-not-allowed disabled:bg-input-disabled disabled:text-action-disabled-text";
+/** What the trigger adds to the surface: one row, text and chevron apart. */
+export declare const FIELD_CONTROL_TRIGGER = "focus-ring w-full min-w-0 cursor-pointer rounded-control border bg-input text-body transition-colors duration-(--duration-base) hover:bg-input-hover active:bg-input-active focus-visible:bg-input-focus focus:outline-none focus-visible:outline-none disabled:cursor-not-allowed disabled:bg-input-disabled disabled:text-action-disabled-text flex items-center justify-between gap-2";

package/dist/util/field-control.js

@@ -0,0 +1,32 @@
+/**
+ * The look of a field-shaped control's box: Select's trigger and native select
+ * and PickerField draw it from here, so a picker beside a Select is the same
+ * box. Kept in one place so they cannot drift.
+ */
+/**
+ * Same fixed height scale as Button, IconButton and Input (32 / 40 / 48), and
+ * the same 16px text below `sm`. One line is exactly 32, 40 or 48px: the
+ * padding leaves room for the line and the border inside it, and is a step
+ * smaller below `sm`, where the text is 16px on a 24px line.
+ */
+export function fieldControlSize(size) {
+    if (size === "sm")
+        return { box: "min-h-8 px-3 py-1 max-sm:py-0 pointer-coarse:min-h-11", text: "text-sm max-sm:text-base", native: "h-8 ps-3 pe-9 pointer-coarse:h-11", chevron: "end-3" };
+    if (size === "lg")
+        return { box: "min-h-12 px-4 py-2", text: "text-base", native: "h-12 ps-4 pe-10", chevron: "end-4" };
+    return { box: "min-h-10 px-3 py-2 max-sm:py-1 pointer-coarse:min-h-11", text: "text-sm max-sm:text-base", native: "h-10 ps-3 pe-9 pointer-coarse:h-11", chevron: "end-3" };
+}
+/** The edge colour for a status: the field's own, or the status colour. */
+export function fieldControlEdge(variant) {
+    return variant === "success"
+        ? "border-success focus-visible:border-success"
+        : variant === "warning"
+            ? "border-warning focus-visible:border-warning"
+            : variant === "error"
+                ? "border-error focus-visible:border-error"
+                : "border-input-border enabled:hover:border-input-border-hover";
+}
+/** The field's surface, edge and states. */
+export const FIELD_CONTROL_SURFACE = "focus-ring w-full min-w-0 cursor-pointer rounded-control border bg-input text-body transition-colors duration-(--duration-base) hover:bg-input-hover active:bg-input-active focus-visible:bg-input-focus focus:outline-none focus-visible:outline-none disabled:cursor-not-allowed disabled:bg-input-disabled disabled:text-action-disabled-text";
+/** What the trigger adds to the surface: one row, text and chevron apart. */
+export const FIELD_CONTROL_TRIGGER = `${FIELD_CONTROL_SURFACE} flex items-center justify-between gap-2`;

package/dist/util/field.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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;
+/** What Textarea's `countText` is given: the characters typed, the limit, and how many are left. */
+export interface TextareaCount {
+    length: number;
+    max: number;
+    remaining: number;
+}

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);
+}

package/dist/util/fit-in-viewport.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Keeps a floating box (a menu, a panel, a tooltip) where it can be seen.
+ *
+ * One module for everything that opens next to a trigger. Two layers:
+ *
+ * - `pickSide` and `shiftIntoViewport` are the two decisions every such box
+ *   needs: which side of its trigger it opens on, and how far it has to move
+ *   along that side to stay on screen. Tooltip uses them as they are.
+ * - `fitPanel` builds on them for a panel that hangs from one edge of its
+ *   anchor (Dropdown, Select's list, NavigationMenuContent): it also narrows
+ *   and shortens a panel too large for the screen. `measurePlacement` reads
+ *   the layout for it, and `watchViewport` re-runs it while the panel is open.
+ *
+ * The arithmetic is pure, so it can be tested without a layout.
+ *
+ * The screen is not the only thing that cuts a panel off. Inside a box that
+ * scrolls (a Modal's body, a list with its own scrollbar) the box clips it
+ * first. `measurePlacement` takes the nearest such box into account: it
+ * decides which side the panel opens on, and when the panel fits on neither
+ * side it says where to put the panel with `position: fixed`, which a
+ * scrolling ancestor does not clip.
+ */
+export type PanelBlock = "bottom" | "top";
+export type PanelInline = "start" | "end";
+export interface PanelBox {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+export interface FitPanelInput {
+    /** The box the panel is positioned against, in viewport coordinates. */
+    anchor: PanelBox;
+    /** The panel's natural size, measured with no limit on it. */
+    panel: {
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** The side asked for. It is kept whenever the panel fits there. */
+    block: PanelBlock;
+    inline: PanelInline;
+    /** Right-to-left layout: `start` is then the right edge. */
+    rtl?: boolean;
+    /** Room kept between the panel and every edge of the viewport. */
+    margin?: number;
+    /** Distance between the anchor and the panel. */
+    gap?: number;
+    /** False keeps the panel on the `block` side asked for, whatever fits. */
+    flipBlock?: boolean;
+    /** False keeps it on the `inline` edge asked for and slides it back inside instead. */
+    flipInline?: boolean;
+    /**
+     * The inside of the nearest ancestor that clips, in viewport coordinates.
+     * It decides which side the panel opens on and how far it slides; it
+     * never limits the panel's size, which only the viewport does.
+     */
+    clip?: PanelBox | null;
+}
+export interface PanelFit {
+    block: PanelBlock;
+    inline: PanelInline;
+    /**
+     * Distance to put between the anchor's `inline` edge and the panel's, for
+     * `inset-inline-start` or `inset-inline-end`. 0 when the panel fits as it
+     * is; otherwise what slides it back inside.
+     */
+    inlineOffset: number;
+    /** A limit to set, or null when the panel fits without one. */
+    maxWidth: number | null;
+    maxHeight: number | null;
+    /** Where the panel's box ends up, in viewport coordinates, and how wide it is there. */
+    left: number;
+    top: number;
+    width: number;
+    /** False when part of the panel is outside `clip` (or the viewport) even so. */
+    visible: boolean;
+}
+export type FloatingSide = "top" | "bottom" | "left" | "right";
+/**
+ * The side a floating box of `size` opens on: the preferred one when it fits
+ * there, the opposite one when only that fits, and otherwise whichever of the
+ * two has more room.
+ *
+ * `gap` is the distance between trigger and box; `margin` is how close to the
+ * viewport edge the box may come. `clip` is the inside of an ancestor that
+ * cuts the box off, when there is one: the box then has to fit in what both
+ * leave.
+ */
+export declare function pickSide(preferred: FloatingSide, trigger: PanelBox, size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, { gap, margin, clip, }?: {
+    gap?: number;
+    margin?: number;
+    clip?: PanelBox | null;
+}): FloatingSide;
+/**
+ * How far `box` has to move, in px, to lie inside the viewport with `margin`
+ * to spare. Zero on an axis where it already does. A box larger than the
+ * viewport is aligned to the start edge (top, left), where its text begins.
+ */
+export declare function shiftIntoViewport(box: PanelBox, viewport: {
+    width: number;
+    height: number;
+}, margin?: number): {
+    x: number;
+    y: number;
+};
+export interface ViewportPoint {
+    x: number;
+    y: number;
+}
+/**
+ * True when `point` lies in the triangle `a`, `b`, `c`, edges included. For
+ * the path a pointer takes from a trigger to its floating box: as long as it
+ * stays in the triangle between where it left and the near edge of the box,
+ * it is on its way there.
+ */
+export declare function insideTriangle(point: ViewportPoint, a: ViewportPoint, b: ViewportPoint, c: ViewportPoint): boolean;
+/** Where the panel fits, starting from the side asked for. */
+export declare function fitPanel(input: FitPanelInput): PanelFit;
+/** A fit that changes nothing: the panel where the CSS puts it, with no limits. */
+export declare function unfitted(block: PanelBlock, inline: PanelInline): PanelFit;
+export interface MeasureOptions {
+    margin?: number;
+    gap?: number;
+    flipBlock?: boolean;
+    flipInline?: boolean;
+    /** Overrides the anchor's own direction; `false` for a panel placed with `left`, not `inset-inline-start`. */
+    rtl?: boolean;
+    clip?: PanelBox | null;
+}
+/**
+ * Measures `panel` against `anchor` and returns its fit. Any limit already on
+ * the panel is lifted for the measurement, so the answer does not depend on
+ * the previous one. Call it before paint (from an effect) and apply the result.
+ */
+export declare function measureFit(anchor: Element, panel: HTMLElement, preferred: {
+    block: PanelBlock;
+    inline: PanelInline;
+}, options?: MeasureOptions): PanelFit;
+/**
+ * The nearest ancestor of `element` that clips what reaches outside it (any
+ * `overflow` but `visible`), with the box it clips to: its inside, without
+ * borders or scrollbars, in viewport coordinates. Null when only the viewport
+ * clips.
+ */
+export declare function clippingAncestor(element: Element): {
+    element: HTMLElement;
+    box: PanelBox;
+} | null;
+export interface PanelPlacement extends PanelFit {
+    /**
+     * Set when the panel has to leave a clipping ancestor to be seen: the
+     * `top`, `left` and `width` to give it with `position: fixed`. Null when
+     * it stays where the CSS puts it.
+     *
+     * The width is the one the panel has where the CSS puts it. A fixed box
+     * is sized against the viewport instead of the anchor, so without it the
+     * panel would change width as it leaves the box.
+     */
+    fixed: {
+        left: number;
+        top: number;
+        width: number;
+    } | null;
+}
+/**
+ * The fit of `panel`, with the nearest clipping ancestor of `anchor` taken
+ * into account.
+ *
+ * - The panel fits inside that ancestor on the side asked for: nothing changes.
+ * - It fits on the other side: it opens there.
+ * - It fits on neither: it is placed against the viewport with `fixed`, on the
+ *   side the viewport has room for, and reaches out of the ancestor. Only
+ *   while some of the anchor can be seen in the ancestor: scrolled out of it,
+ *   the anchor takes the panel with it.
+ * - It cannot be: something between the panel and that ancestor is the
+ *   containing block of fixed descendants (a `transform`, a `filter`). It then
+ *   opens on the side of the ancestor with more room, and is cut where that
+ *   ends. That is the limit of what a panel can do without leaving its place
+ *   in the DOM, and it stays there so that the keyboard, focus and a dialog's
+ *   focus trap treat it as part of what opened it.
+ */
+export declare function measurePlacement(anchor: Element, panel: HTMLElement, preferred: {
+    block: PanelBlock;
+    inline: PanelInline;
+}, options?: MeasureOptions): PanelPlacement;
+/**
+ * Calls `update` when the viewport changes size or anything outside `panel`
+ * scrolls, at most once a frame. Returns the function that stops it.
+ */
+export declare function watchViewport(update: () => void, panel?: Element | null): () => void;