@50arms/ui 0.0.0-stage → 35.2.0

package/dist/types/lib/syntax/registry.d.ts

@@ -0,0 +1,37 @@
+import type { Grammar } from "./types";
+/**
+ * Normalises and checks a grammar at definition time, so a malformed rule fails
+ * where it was written rather than as slightly-wrong colours in a browser.
+ *
+ * Every pattern is rebuilt with two flags forced on:
+ *
+ *   `y` (sticky) — a plain regex SEARCHES FORWARD from the position, so a rule
+ *   can match text the scanner has not reached yet and silently swallow
+ *   everything in between. Sticky anchors it to exactly where the scanner is.
+ *
+ *   `d` (hasIndices) — `groups` needs the offset of each capture, and
+ *   `match.indices` is the only way to get it that survives optional groups.
+ *
+ * Forcing them beats throwing on their absence: a grammar author writes an
+ * ordinary regex and the one thing they could get subtly wrong is unreachable.
+ */
+export declare function defineGrammar(grammar: Grammar): Grammar;
+/**
+ * Registered explicitly from a VALUE import rather than by each language module
+ * importing the registry for its side effect. `package.json` declares
+ * `sideEffects: ["*.css"]`, which tells every bundler a bare `import "./x"` of
+ * a `.ts` module is safe to delete — and esbuild does. That already cost this
+ * project its entire icon set once (CAV-11); the registry that a table is
+ * pushed INTO cannot be pruned while the table is reachable.
+ */
+export declare function registerGrammar(grammar: Grammar): void;
+/**
+ * Looks up a language by name or alias. Returns undefined for anything
+ * unregistered — callers render it as plain text, because an unknown language
+ * on a code block must never be an error. The block still has to be readable.
+ */
+export declare function getGrammar(language: string | null | undefined): Grammar | undefined;
+/** The canonical name for an alias — `ts` becomes `typescript`. */
+export declare function resolveLanguage(language: string | null | undefined): string | null;
+/** Every registered language, canonical names only, sorted. Drives the picker. */
+export declare function listLanguages(): string[];

package/dist/types/lib/syntax/tokenize.d.ts

@@ -0,0 +1,17 @@
+import type { Token } from "./types";
+/**
+ * Tokenizes `source` as `language`. An unknown or missing language yields one
+ * `text` token spanning the input — never an error, never an empty result. A
+ * code block labelled with a language nobody implemented still has to be
+ * readable, and an editor still has to be editable.
+ */
+export declare function tokenize(source: string, language: string | null | undefined): Token[];
+/**
+ * Asserts what the whole design rests on: the tokens reproduce the source
+ * exactly. Exported because it is used by every language's test rather than
+ * re-derived in each one, and because a consumer building a grammar at runtime
+ * should have the same check available.
+ *
+ * Returns a description of the first violation, or null when the list is sound.
+ */
+export declare function checkCoverage(source: string, tokens: Token[]): string | null;

package/dist/types/lib/syntax/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The token contract. Every grammar in this system produces this shape and
+ * nothing else — the highlighter, the editor overlay, the markdown renderer and
+ * the tests all read it.
+ *
+ * WHY A FLAT TOKEN LIST AND NOT AN HTML STRING. The obvious design (and the one
+ * the Vue original uses) is `highlight(code) -> "<span class=…>…"`, one function
+ * per language. It cannot do the two things this component exists to do:
+ *
+ *   1. EDITING. The editor is a transparent `<textarea>` sitting exactly on top
+ *      of a `<pre>` of the same text. That only works if the rendered text is
+ *      character-for-character the source — same characters, same order, same
+ *      length. A list of offsets into the original string makes that checkable;
+ *      a string of markup makes it a promise nobody can verify.
+ *   2. NESTING. A fenced code block inside markdown, or `<style>` inside a Vue
+ *      SFC, is a region of one language inside another. With offsets, an inner
+ *      grammar's tokens splice into the outer stream and everything downstream
+ *      is unaware anything happened. With strings you are concatenating markup
+ *      and hoping the escaping survives.
+ *
+ * The invariant that makes both work, asserted by `tokenize`'s own tests:
+ * tokens are non-overlapping, ascending, and cover the whole input with no
+ * gaps. `src.slice(t.start, t.end)` joined over every token IS the source.
+ */
+/**
+ * Token categories. Deliberately a closed set: each one maps to exactly one CSS
+ * custom property in `src/styles/syntax.css`, so a language cannot invent a
+ * colour, and adding a category is a visible, one-place decision.
+ *
+ * Named for ROLE rather than for any one language's grammar — `property` covers
+ * a JSON key, a CSS declaration name and a JS object key, because all three are
+ * "the name on the left" and should read the same way in every language.
+ */
+export type TokenType = "text" | "comment" | "punctuation" | "operator" | "string" | "escape" | "number" | "boolean" | "null" | "regex" | "keyword" | "property" | "variable" | "function" | "type" | "constant" | "tag" | "attribute" | "selector" | "atrule" | "heading" | "emphasis" | "strong" | "strike" | "link" | "url" | "marker" | "quote" | "invalid";
+/** A run of source text with one category. Half-open range: `[start, end)`. */
+export interface Token {
+    /** Offset into the ORIGINAL source string, never into a nested substring. */
+    start: number;
+    end: number;
+    type: TokenType;
+    /**
+     * The grammar that produced this token. An embedded region carries the INNER
+     * language's name, which is what lets a consumer style a fenced block
+     * differently from the markdown around it — and what makes a nesting bug
+     * visible in a test rather than merely wrong on screen.
+     */
+    lang: string;
+}
+/**
+ * One scanning rule, tried in order at the current position.
+ *
+ * `match` MUST carry the sticky flag. A non-sticky regex searches forward from
+ * the position and can match text the scanner has not reached, silently
+ * swallowing the characters in between — the failure looks like "highlighting
+ * is slightly off" and is very hard to trace back. `defineGrammar` throws on a
+ * non-sticky pattern rather than letting that ship.
+ */
+export interface Rule {
+    match: RegExp;
+    /** Category for the entire match. Mutually exclusive with `groups`. */
+    token?: TokenType;
+    /**
+     * Category per capture group, for a rule that matches several things at once
+     * (`key` `:` in JSON, `<` `div` in HTML). `null` leaves a group as plain
+     * text. Anything between groups is emitted as `text`, so coverage holds.
+     */
+    groups?: (TokenType | null)[];
+    /** Enter another state of the SAME grammar (a string body, a comment). */
+    push?: string;
+    /** Leave the current state. Applied after the token is emitted. */
+    pop?: true;
+    /**
+     * Enter ANOTHER grammar for the region that follows, until `until` matches.
+     * A string names it outright (`<style>` -> css); a function reads it off the
+     * match, which is how a fence takes its language from its own info string and
+     * how `<script lang="ts">` differs from `<script>`.
+     *
+     * Returning null (unknown language) is not an error — the region is scanned
+     * as plain text and still terminates correctly at `until`. An unrecognised
+     * language must never break the document containing it.
+     */
+    embed?: string | ((match: RegExpExecArray) => string | null);
+    /** Required with `embed`: the pattern that ends the embedded region. */
+    until?: RegExp;
+    /** Category for the terminator itself. Defaults to `punctuation`. */
+    untilToken?: TokenType;
+}
+/**
+ * A language. `states.root` is the entry point; other states are pushed by
+ * rules. Most grammars need only `root` plus a state per multi-line construct.
+ */
+export interface Grammar {
+    name: string;
+    aliases?: readonly string[];
+    states: Record<string, Rule[]>;
+    /**
+     * Full override for a language the rule stack genuinely cannot express.
+     * Markdown is the only one: its structure is by BLOCK (a list item's content
+     * is decided by indentation relative to its marker, several lines later),
+     * which no positional rule stack can see. It parses properly and emits this
+     * same token shape, so every consumer stays unaware of the difference.
+     *
+     * A grammar with `tokenize` may leave `states` empty.
+     */
+    tokenize?: (source: string, ctx: TokenizeContext) => Token[];
+}
+/**
+ * Handed to a `tokenize` override so it can highlight regions of other
+ * languages — a fenced block, YAML front matter — without importing the
+ * registry itself and creating a cycle.
+ */
+export interface TokenizeContext {
+    /**
+     * Tokenize `source` as `language`, with every offset shifted by `offset` so
+     * the result splices into the caller's stream. An unknown language yields one
+     * `text` token, never an error.
+     */
+    sub(source: string, language: string | null, offset: number): Token[];
+}

package/dist/types/lib/time/index.d.ts

@@ -0,0 +1,4 @@
+export { AmbiguousTimeError, isoDateString, isoDateTimeString, type CalendarDuration, type Disambiguation, type Instant, type PlainDate, type PlainDateTime, type TimeZone, } from "./types";
+export { addDuration, dayFraction, dayLengthMs, hoursInDay, instantAtFraction, instantToPlainDate, instantToPlainDateTime, nextDay, offsetAt, plainDateTimeToInstant, startOfDay, } from "./zone";
+export { addDays, addMonths, atMidnight, atTime, comparePlainDate, dayOfWeek, daysBetween, daysInMonth, endOfMonth, isSameDate, monthGridDays, parsePlainDate, startOfMonth, startOfWeek, weekDays, } from "./plain";
+export { relativeAge } from "./relativeAge";

package/dist/types/lib/time/instant.d.ts

@@ -0,0 +1,2 @@
+/** A moment as epoch millis, from the three shapes a caller holds (ISO string, epoch millis, `Date`). `NaN` when it does not parse. The one parser the time layer shares. DX-4797. */
+export declare function toEpochMs(when: string | number | Date): number;

package/dist/types/lib/time/plain.d.ts

@@ -0,0 +1,61 @@
+import { isoDateString, type PlainDate, type PlainDateTime } from "./types";
+/** Days in `month` of `year`, leap years included. */
+export declare function daysInMonth(year: number, month: number): number;
+/** `date` moved by `days`, which may be negative, rolling months and years. */
+export declare function addDays(date: PlainDate, days: number): PlainDate;
+/**
+ * `date` moved by `months`, clamping the day to the target month's length.
+ *
+ * CLAMPING, NOT ROLLING: one month after the 31st of January is the 28th or
+ * 29th of February, never the 3rd of March. Rolling is what `Date.setMonth`
+ * does natively and it is why "next month" buttons skip February.
+ */
+export declare function addMonths(date: PlainDate, months: number): PlainDate;
+/** Whole days from `a` to `b`; negative when `b` is earlier. */
+export declare function daysBetween(a: PlainDate, b: PlainDate): number;
+/** Negative when `a` is earlier, 0 when equal, positive when later. */
+export declare function comparePlainDate(a: PlainDate, b: PlainDate): number;
+export declare function isSameDate(a: PlainDate, b: PlainDate): boolean;
+/** 0 = Sunday … 6 = Saturday, matching `Date.getUTCDay` and `Intl`'s weekday order. */
+export declare function dayOfWeek(date: PlainDate): number;
+/**
+ * The first day of the week `date` falls in.
+ *
+ * `weekStartsOn` IS A PARAMETER WITH NO DEFAULT ANYWHERE UP THE STACK, because
+ * there is no correct global answer: Sunday in the US and Japan, Monday across
+ * Europe and by ISO 8601, Saturday in much of the Middle East. A component that
+ * picks one silently is wrong for most of the world, so the calendar surfaces
+ * it and this function simply obeys.
+ */
+export declare function startOfWeek(date: PlainDate, weekStartsOn: number): PlainDate;
+/** The 1st of `date`'s month. */
+export declare function startOfMonth(date: PlainDate): PlainDate;
+/** The last day of `date`'s month. */
+export declare function endOfMonth(date: PlainDate): PlainDate;
+/**
+ * Every day a month grid shows, INCLUDING the leading and trailing days that
+ * belong to the neighbouring months.
+ *
+ * Always whole weeks, so the result is a multiple of seven and the grid never
+ * has a ragged edge. The count varies — a 28-day February beginning on the
+ * week's first day needs four rows, and a 31-day month beginning on its last
+ * day needs six. Callers that assume six rows draw an empty one eleven months
+ * a year; callers that assume five are simply wrong twice a year.
+ */
+export declare function monthGridDays(date: PlainDate, weekStartsOn: number): PlainDate[];
+/** The seven days of the week `date` falls in. */
+export declare function weekDays(date: PlainDate, weekStartsOn: number): PlainDate[];
+/**
+ * Parse `YYYY-MM-DD`.
+ *
+ * FAILS LOUDLY on anything else, including the shapes `Date` accepts and
+ * silently reinterprets. `new Date("2026-2-30")` yields the 2nd of March, which
+ * is a data error becoming a rendered event on the wrong day with nothing
+ * anywhere reporting a problem.
+ */
+export declare function parsePlainDate(iso: string): PlainDate;
+export { isoDateString };
+/** A `PlainDateTime` at midnight on `date` — the wall reading, not an instant. */
+export declare function atMidnight(date: PlainDate): PlainDateTime;
+/** A `PlainDateTime` at `hour`:`minute` on `date`. */
+export declare function atTime(date: PlainDate, hour: number, minute?: number): PlainDateTime;

package/dist/types/lib/time/relativeAge.d.ts

@@ -0,0 +1,18 @@
+import type { RelativeAgeStrings } from "../i18n/areas/formats";
+/**
+ * A moment's age in words (English shown; the words come from `strings`): "just now", "4m ago", "4h ago", "1d 6h ago",
+ * "2w ago".
+ *
+ * Stays two-unit only in the day range (a message from earlier today reads
+ * as "6h ago", not "0d 6h ago") — days-plus-hours is the one range where a
+ * single unit throws away information a reader of a chat transcript actually
+ * wants ("this morning" vs "yesterday afternoon" are different facts, and
+ * "1d ago" collapses both). Beyond a week it drops to whole weeks, same as
+ * every sibling formatter in this codebase — nobody needs "9d ago" instead
+ * of "1w 2d ago", and nobody needs either instead of a calendar date, but a
+ * chat message's hover row has no room for a calendar date, so weeks it is.
+ *
+ * `now` is the instant to measure against (default: the clock). `RelativeTime`'s shared ticker passes later instants to find
+ * when this text next changes.
+ */
+export declare function relativeAge(when: string | number | Date, strings: RelativeAgeStrings, locale: string, now?: number): string;

package/dist/types/lib/time/relativeClock.d.ts

@@ -0,0 +1,8 @@
+/** The text of a moment as of `now` (epoch ms). `relativeAge` is one. */
+export type RelativeFormat = (at: string | number | Date, now?: number) => string;
+/** The first instant after `now` at which `format(at, instant)` differs from `format(at, now)`, within `HORIZON_MS`. */
+export declare function nextTextChangeAt(at: number, format: RelativeFormat, now: number): number;
+/** Calls `onChange` whenever `format(at)` may now read differently. Returns the unsubscribe. The last unsubscribe stops the timer. */
+export declare function subscribeRelativeClock(at: number, format: RelativeFormat, onChange: () => void): () => void;
+/** Mounted subscribers right now; the tests pin that it returns to zero. */
+export declare function relativeClockSubscriberCount(): number;

package/dist/types/lib/time/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * A point on the timeline, as milliseconds since the epoch.
+ *
+ * NOT a `Date`. A `Date` is a mutable object that prints itself in the host's
+ * local zone, and every calendar bug in the survey behind this component
+ * involved someone reading a `Date`'s local fields when they meant a specific
+ * zone's. A number cannot be misread that way — it has no fields to read.
+ */
+export type Instant = number;
+/** An IANA time zone identifier, e.g. `"America/New_York"`. */
+export type TimeZone = string;
+/**
+ * A calendar day. No time, no zone, no offset — just which square on the wall.
+ *
+ * `month` IS ONE-BASED, matching `Temporal` and matching how every human writes
+ * a date. `Date`'s zero-based month is the single most common off-by-one in
+ * date code and it is not reproduced here.
+ */
+export interface PlainDate {
+    readonly year: number;
+    /** 1–12. */
+    readonly month: number;
+    /** 1–31. */
+    readonly day: number;
+}
+/**
+ * A wall-clock reading. What a clock on the wall says, with no claim about
+ * which wall.
+ *
+ * This is the type that makes the ambiguity explicit rather than accidental:
+ * `2026-11-01T01:30` in New York happened TWICE, and `2026-03-08T02:30` never
+ * happened at all. A `PlainDateTime` can represent both, which is precisely why
+ * turning one into an `Instant` requires saying what to do about it.
+ */
+export interface PlainDateTime extends PlainDate {
+    /** 0–23. */
+    readonly hour: number;
+    /** 0–59. */
+    readonly minute: number;
+    /** 0–59. */
+    readonly second: number;
+    /** 0–999. */
+    readonly millisecond: number;
+}
+/**
+ * How much to move, in CALENDAR units rather than elapsed time.
+ *
+ * THE DISTINCTION IS THE WHOLE POINT, and getting it wrong is the bug in every
+ * library surveyed. "One day later" is not "86,400,000 ms later": across a
+ * spring-forward boundary it is 23 hours, and across a fall-back it is 25. A
+ * user dragging an event from Saturday to Sunday expects it to keep its
+ * wall-clock time, so the move has to be expressed as `{ days: 1 }` and
+ * resolved against the zone — never added as a number.
+ *
+ * `hours` and `minutes` ARE exact elapsed time, and that is correct: dragging
+ * an event down by two hours means two hours of real duration.
+ */
+export interface CalendarDuration {
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+}
+/**
+ * What to do when a wall-clock reading does not name exactly one instant.
+ *
+ * Spelled as `Temporal.ZonedDateTime.from`'s option of the same name, with the
+ * same meanings, so this is one more thing that becomes a deletion later.
+ *
+ * - `compatible` — what every other date library does, and the default.
+ *   In a GAP (spring forward) move forward by the size of the gap; in an
+ *   OVERLAP (fall back) take the first of the two.
+ * - `earlier` / `later` — take that side explicitly.
+ * - `reject` — throw. For a parser or an import, where a time that never
+ *   existed is a fact about bad input rather than something to paper over.
+ */
+export type Disambiguation = "compatible" | "earlier" | "later" | "reject";
+/** Thrown by `reject` disambiguation, and never by anything else. */
+export declare class AmbiguousTimeError extends Error {
+    readonly wall: PlainDateTime;
+    readonly zone: TimeZone;
+    readonly kind: "gap" | "overlap";
+    constructor(wall: PlainDateTime, zone: TimeZone, kind: "gap" | "overlap");
+}
+/** `2026-03-08T02:30:00.000` — used in errors, and by the ISO helpers. */
+export declare function isoDateTimeString(wall: PlainDateTime): string;
+/** `2026-03-08`. */
+export declare function isoDateString(date: PlainDate): string;

package/dist/types/lib/time/zone.d.ts

@@ -0,0 +1,106 @@
+import { type Disambiguation, type Instant, type PlainDate, type PlainDateTime, type TimeZone } from "./types";
+/** The wall-clock reading in `zone` at `instant`. */
+export declare function instantToPlainDateTime(zone: TimeZone, instant: Instant): PlainDateTime;
+/**
+ * The same wall-clock fields, but as though they were UTC.
+ *
+ * `Date.UTC` is NOT used directly anywhere in this file: it maps years 0–99
+ * onto 1900–1999, so a year-40 date silently becomes 1940. `setUTCFullYear` has
+ * no such rule. The calendar will never render year 40, but a helper that is
+ * wrong for an input it never receives is a trap left for whoever reuses it.
+ */
+export declare function wallAsUtcMs(wall: PlainDateTime): number;
+/**
+ * `zone`'s offset from UTC at `instant`, in milliseconds. East is positive.
+ *
+ * THE ONE PRIMITIVE. Read by asking the browser what the wall clock says at
+ * that instant and subtracting: if it is 07:00 UTC and the clock in New York
+ * reads 02:00, the offset is −5 hours. No table, no parsing of a zone name, no
+ * assumption that an offset is a whole number of hours — `Pacific/Chatham` sits
+ * at +12:45, and `Asia/Kathmandu` at +5:45.
+ */
+export declare function offsetAt(zone: TimeZone, instant: Instant): number;
+/**
+ * The instant at which `zone`'s clock reads `wall`.
+ *
+ * See `Disambiguation` for what happens when that is not exactly one instant.
+ * The default is `compatible`, which is what `Temporal` and every other date
+ * library do, so the surprising cases are the ones you have to ask for.
+ */
+export declare function plainDateTimeToInstant(zone: TimeZone, wall: PlainDateTime, disambiguation?: Disambiguation): Instant;
+/** The calendar day `instant` falls on, in `zone`. */
+export declare function instantToPlainDate(zone: TimeZone, instant: Instant): PlainDate;
+/**
+ * The first instant of `date` in `zone`.
+ *
+ * NOT "midnight". In `America/Santiago` on 2026-09-06 the clock jumps from
+ * 00:00 to 01:00, so the day's first instant reads 01:00 — and a grid that
+ * assumes its own origin is midnight puts every event on that day an hour out.
+ * `America/Havana` and `Asia/Beirut` do the same thing on their own dates.
+ *
+ * Implemented by asking for midnight and, when the clock skipped it, walking
+ * forward a minute at a time until a reading exists. The walk is bounded: no
+ * transition in the IANA database exceeds two hours, so 180 iterations cannot
+ * be reached by real data, and the bound exists to fail loudly rather than spin
+ * if that ever stops being true.
+ */
+export declare function startOfDay(zone: TimeZone, date: PlainDate): Instant;
+/** The day after `date` on the calendar, ignoring zones entirely. */
+export declare function nextDay(date: PlainDate): PlainDate;
+/**
+ * How long `date` actually lasts in `zone`, in milliseconds.
+ *
+ * Measured as the distance between one day's first instant and the next day's,
+ * which is true by construction for every case — 23 hours, 25 hours, the 30
+ * minutes of Lord Howe, and a day that starts at 01:00 — with no special case
+ * for any of them. That is the entire reason positions in the grid are a RATIO
+ * of this number rather than `hour × rowHeight`.
+ */
+export declare function dayLengthMs(zone: TimeZone, date: PlainDate): number;
+/**
+ * How many hours `date` lasts in `zone` — 23, 24, 25, or 23.5.
+ *
+ * Fractional by design. `Australia/Lord_Howe` shifts by thirty minutes, so a
+ * signature returning an integer would be lying about a real zone, and any
+ * caller branching on `=== 23` is already broken.
+ */
+export declare function hoursInDay(zone: TimeZone, date: PlainDate): number;
+/**
+ * Where `instant` sits within `date`, as a fraction from 0 to 1.
+ *
+ * THE LOAD-BEARING FUNCTION. A 23-hour day compresses and a 25-hour day
+ * stretches with no branch anywhere, because the divisor is the day's real
+ * length. Values outside 0–1 mean the instant is not on this day and are
+ * returned rather than clamped — the layout core needs to know by how much in
+ * order to clip a multi-day span.
+ */
+export declare function dayFraction(zone: TimeZone, date: PlainDate, instant: Instant): number;
+/**
+ * The exact inverse of `dayFraction`.
+ *
+ * IT MUST BE EXACT, and that is not a stylistic preference. Rendering maps an
+ * instant to a position and hit-testing maps a position back to an instant; if
+ * the two disagree by even a rounding step, an event lands one slot away from
+ * where it was dropped. FullCalendar's Australia selection bug is exactly this
+ * pair drifting apart. `dayFraction(z, d, instantAtFraction(z, d, f)) === f`
+ * for every zone in the corpus, and there is a test that says so.
+ */
+export declare function instantAtFraction(zone: TimeZone, date: PlainDate, fraction: number): Instant;
+/**
+ * Move `instant` by a CALENDAR duration.
+ *
+ * Days are applied on the calendar and then re-anchored to the same wall-clock
+ * time, so an event dragged from Saturday to Sunday across a transition keeps
+ * reading 09:00 rather than becoming 08:00 or 10:00. Hours and minutes are
+ * applied afterwards as exact elapsed time, because dragging an event down the
+ * grid by two hours does mean two hours.
+ *
+ * ORDER MATTERS AND IS FIXED: days first, then time. The other order makes
+ * "one day and two hours later" depend on which side of a transition the
+ * intermediate value happened to land on.
+ */
+export declare function addDuration(zone: TimeZone, instant: Instant, duration: {
+    days?: number;
+    hours?: number;
+    minutes?: number;
+}, disambiguation?: Disambiguation): Instant;

package/dist/types/lib/use-controllable.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One value that may be driven from outside or kept here.
+ *
+ * WHY IT IS SHARED RATHER THAN WRITTEN FOUR TIMES: `CodeEditor` has four of
+ * these (text, wrap, view, expanded) and the subtle half is identical in all
+ * four — a controlled instance must NEVER write its own state, or it renders
+ * the consumer's value for one frame and its own for the next, which shows up
+ * as a control that flickers back after every change.
+ *
+ * `controlled === undefined` decides, once per render, exactly as React's own
+ * inputs do. Switching a prop from undefined to a value mid-life is a consumer
+ * bug everywhere in React and is not defended against here.
+ */
+export declare function useControllable<T>(controlled: T | undefined, initial: T, onChange?: (next: T) => void): [T, (next: T) => void];

package/dist/types/lib/use-fill-height.d.ts

@@ -0,0 +1,26 @@
+import { type RefCallback } from "react";
+/**
+ * Size an element to the space between its own top and the bottom of the box
+ * that scrolls it, and keep it sized as the page changes around it.
+ *
+ * Returns a ref callback for the element. The height is written as inline style
+ * rather than returned as state on purpose — a returned number would re-render
+ * the subtree on every resize frame, and the value is only ever consumed by one
+ * property on one element.
+ *
+ * ```tsx
+ * const fillRef = useFillHeight(fill);
+ * <div ref={fillRef} className="max-h-full …" />
+ * ```
+ *
+ * WHAT IT WATCHES, and why that list rather than a global observer. The number
+ * changes when a box ABOVE the element changes size: the scrollport itself, an
+ * ancestor between the two, or a sibling laid out before it. All three are
+ * observed. The element itself is deliberately NOT observed — it is the thing
+ * being written, and observing it is the loop.
+ *
+ * A sibling ADDED after mount is the known gap: the observer set is built once
+ * per attach. In practice the content above a filling element is a page header,
+ * not a live list, and a `key`ed remount covers the rest.
+ */
+export declare function useFillHeight(enabled?: boolean): RefCallback<HTMLElement>;

package/dist/types/lib/use-hydrated.d.ts

@@ -0,0 +1,8 @@
+/**
+ * DX-5411 / DX-5425 — false on a server and during hydration, true once the client has taken over.
+ *
+ * A prerendered page's first client render must draw exactly what the server drew, so anything that reads the browser
+ * (a stored choice, a share sheet) or must not act before the bundle runs (a submit, a write to storage) waits on this.
+ * A client render that is not hydrating (no server HTML underneath) is true from its first render.
+ */
+export declare function useHydrated(): boolean;

package/dist/types/lib/use-media-query.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Subscribes to a CSS media query and re-renders when it changes.
+ *
+ * WHY A HOOK AND NOT A CSS CLASS. Almost everything responsive in this system
+ * belongs in CSS, where it costs nothing and works before hydration. This
+ * exists for the case CSS cannot reach: a layout whose measurements are written
+ * as INLINE STYLE from application state — a resizable panel group being the
+ * one that matters here. A utility class cannot override `style="flex-grow:3"`,
+ * so the component has to know the width to write a different value.
+ *
+ * Reach for a `lg:` variant first. This is the exception, not the pattern.
+ *
+ * `useSyncExternalStore` rather than `useState` + `useEffect`: it reads the
+ * value during render on the client and returns the server snapshot during SSR,
+ * so there is no first paint at the wrong breakpoint and no hydration mismatch
+ * warning. The effect version renders once with a guess and then corrects
+ * itself, which is a visible layout jump on exactly the devices this is for.
+ */
+export declare function useMediaQuery(query: string, serverFallback?: boolean): boolean;
+/** Tailwind's own breakpoints, so a JS check and a `lg:` class agree. */
+export declare const BREAKPOINTS: {
+    readonly sm: 640;
+    readonly md: 768;
+    readonly lg: 1024;
+    readonly xl: 1280;
+};
+export type Breakpoint = keyof typeof BREAKPOINTS;
+/** True below the named breakpoint — the JS twin of `max-<bp>:`. */
+export declare function useBelow(breakpoint: Breakpoint, serverFallback?: boolean): boolean;

package/dist/types/lib/use-relabel-base-ui-dismiss.d.ts

@@ -0,0 +1,6 @@
+import { type RefObject } from "react";
+/**
+ * Names Base UI's screen-reader dismiss buttons `label`. Pass the element they sit in before the
+ * input (`anchorRef`); put the returned ref on the `Positioner`, which holds the other.
+ */
+export declare function useRelabelBaseUiDismiss(label: string, anchorRef: RefObject<Element | null>): (positioner: Element | null) => void;

package/dist/types/lib/use-release-snap-drag.d.ts

@@ -0,0 +1,25 @@
+import type { PointerEvent as ReactPointerEvent } from "react";
+/** A press that has not moved this far (px) is a click, not a drag: a track click never glides from the pointer. */
+export declare const DRAG_THRESHOLD_PX = 3;
+/** A position along a track, as a percentage held to the track's ends. */
+export declare const clampPercent: (percent: number) => number;
+/**
+ * DXUI-17 / Slider `snap="release"`. Base UI rounds every pointer position to `step` before it reports it,
+ * so it cannot draw a thumb between steps. While a pointer holds the control this tracks where the pointer
+ * is along the track (`dragPercent`), which only moves what is DRAWN; the value Base UI reports stays on the
+ * steps. `settling` is true from a release that followed a drag until the next press or key, and is the
+ * only thing that enables the glide onto the step.
+ *
+ * Follows the pressing pointer only, ends on its pointerup or pointercancel, and, like Base UI, ends on a
+ * move that reports no button down (the pointerup was lost). Assumes a left-to-right track, as Base UI does
+ * without a DirectionProvider.
+ */
+export declare function useReleaseSnapDrag({ enabled, reducedMotion }: {
+    enabled: boolean;
+    reducedMotion: boolean;
+}): {
+    dragPercent: number | null;
+    settling: boolean;
+    endSettling: () => void;
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+};

package/dist/types/lib/use-roving-options.d.ts

@@ -0,0 +1,10 @@
+import { type KeyboardEvent } from "react";
+export interface RovingOptions {
+    /** Attach to the element with `role="listbox"`. */
+    listRef: React.RefObject<HTMLDivElement | null>;
+    /** `0` for the one option that is a Tab stop, `-1` for the rest. */
+    tabIndexFor: (index: number) => 0 | -1;
+    /** Attach to the same element; each option carries `data-option-index`. */
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+}
+export declare function useRovingOptions(count: number, selectedIndex: number, columns: number): RovingOptions;

package/dist/types/lib/values/absent.d.ts

@@ -0,0 +1,7 @@
+/** The shared "no value" reading for a blank field — a date, a number, a
+ *  phone number, a currency amount: nothing recorded. Shared by every
+ *  formatter that reads absence this way, so the glyph itself never drifts
+ *  between them (DX-3254). `formatBoolean` does NOT use this — see its own
+ *  module doc for why a tri-state boolean reads absence as "Unknown"
+ *  instead. */
+export declare const ABSENT = "\u2014";

package/dist/types/lib/values/boolean.d.ts

@@ -0,0 +1,29 @@
+import type { BooleanStrings } from "../i18n/areas/formats";
+export interface FormatBooleanOptions {
+    /** Word for `true`. Default `strings.yes`. */
+    trueLabel?: string;
+    /** Word for `false`. Default `strings.no`. */
+    falseLabel?: string;
+    /** Word for `null` / `undefined`. Default `strings.unknown` — see the module doc
+     *  for why this is not the em dash the rest of this package uses for
+     *  absence. */
+    unknownLabel?: string;
+}
+/**
+ * `true` → `strings.yes`, `false` → `strings.no`, `null` / `undefined` →
+ * `strings.unknown` (all three overridable via `options`).
+ */
+export declare function formatBoolean(value: boolean | null | undefined, strings: BooleanStrings, options?: FormatBooleanOptions): string;
+/**
+ * A human-typed word → `true`, `false`, or `null` for anything else
+ * (including an empty string — a caller cannot distinguish "typed nothing"
+ * from "typed a real value" if both return `false`).
+ *
+ * Matches case-insensitively against the spellings in `strings.trueWords` /
+ * `strings.falseWords` (English: `yes`/`y`/`true`/`t`/`1` and `no`/`n`/`false`/
+ * `f`/`0`). Deliberately does NOT guess at anything outside that list — a
+ * typo like `"yse"` returning `null` for a caller to reject is correct;
+ * returning `false` for it (or any other unrecognised text) would silently
+ * record the opposite of an unreadable answer.
+ */
+export declare function parseBoolean(input: string, strings: BooleanStrings): boolean | null;