@box-kite/react 2.2.4 → 2.2.6

package/utils/date/dateTime.d.ts

@@ -0,0 +1,144 @@
+import { DateKind } from './iso';
+import { DateInput, ZoneOptions } from './value';
+import { ZoneInput } from './zones';
+/** An amount of time to move a value by. Years to days move the calendar; hours and below move the clock. */
+export interface Duration {
+    years?: number;
+    months?: number;
+    weeks?: number;
+    days?: number;
+    hours?: number;
+    minutes?: number;
+    seconds?: number;
+    milliseconds?: number;
+}
+export type DateUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second' | 'millisecond';
+export interface UnitOptions extends ZoneOptions {
+    /** Whose week `'week'` means — Monday-first in Moldova, Sunday-first in the US. Default the configured locale. */
+    locale?: string;
+}
+/** Every reading of one value at once — what a date control hands its `onValueChange` beside the string. */
+export interface DateTimeDetails {
+    /** The value itself, written canonically. */
+    value: string;
+    kind: DateKind;
+    /** The zone the wall-clock fields below are read in. */
+    zone: string;
+    /** The moment in UTC (`…Z`). A date is its midnight in `zone`; a time has none. */
+    utc: string | null;
+    /** The moment on `zone`'s wall clock, with its offset. */
+    zoned: string | null;
+    /** The same moment as the reader's own wall clock, with no zone: what a person in the browser sees. */
+    local: string | null;
+    /** `zone`'s offset at that moment, `+03:00`. */
+    offset: string | null;
+    /** A `Date` for the moment, for an API that wants one. */
+    date: Date | null;
+    /** Epoch milliseconds. */
+    epoch: number | null;
+    year: number;
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+    second: number;
+    millisecond: number;
+}
+/** What kind a string is, or `null` when it is not a date value at all. */
+export declare function kindOf(input: DateInput): DateKind | null;
+/** Whether the input is a value — of `kind`, when one is named. */
+export declare function isValid(input: DateInput, kind?: DateKind): boolean;
+/** The input rewritten canonically, its kind kept: `2026-10-19 14:30` → `2026-10-19T14:30:00`. */
+export declare function normalize(input: DateInput): string | null;
+/** The moment in UTC: `2026-10-19T11:30:00Z`. A date-time is read on `zone`'s wall clock, a date as its midnight there. */
+export declare function toUtc(input: DateInput, options?: Omit<ZoneOptions, 'zone'> & {
+    from?: ZoneInput;
+}): string | null;
+/** The moment on another zone's wall clock, with that zone's offset: `2026-10-19T07:30:00-04:00`. */
+export declare function toZone(input: DateInput, zone: ZoneInput, options?: Omit<ZoneOptions, 'zone'> & {
+    from?: ZoneInput;
+}): string | null;
+/** The moment on the reader's wall clock, with its offset. On a server, "the reader" is `configureDates({ timeZone })` or the server. */
+export declare function toLocal(input: DateInput, options?: Omit<ZoneOptions, 'zone'> & {
+    from?: ZoneInput;
+}): string | null;
+/** The day an input falls on in `zone`: `2026-10-19`. */
+export declare function toPlainDate(input: DateInput, options?: ZoneOptions): string | null;
+/** The wall-clock time an input shows in `zone`: `14:30:00`. */
+export declare function toPlainTime(input: DateInput, options?: ZoneOptions): string | null;
+/** The wall clock an input shows in `zone`, with no zone attached: `2026-10-19T14:30:00`. */
+export declare function toPlainDateTime(input: DateInput, options?: ZoneOptions): string | null;
+/** The instant an input names, on `zone`'s wall clock. A date-time is read there; a date is its midnight. */
+export declare function toInstant(input: DateInput, options?: ZoneOptions): string | null;
+/** Epoch milliseconds. */
+export declare function toEpoch(input: DateInput, options?: ZoneOptions): number | null;
+/** A `Date`, for an API that insists. A date is its midnight in `zone`, which is the one way a `Date` can hold a day. */
+export declare function toDate(input: DateInput, options?: ZoneOptions): Date | null;
+/** A `Date` or epoch milliseconds as a value of `kind` — by default the instant, in UTC. */
+export declare function fromDate(date: Date | number, options?: ZoneOptions & {
+    kind?: DateKind;
+}): string | null;
+/** A date and a time put together: a date-time, or with `zone` the instant it names there. */
+export declare function combine(date: DateInput, time: DateInput, options?: ZoneOptions): string | null;
+/** Today's date in `zone`. Default the reader's. */
+export declare function today(zone?: ZoneInput): string;
+/** This moment on `zone`'s wall clock, with its offset — `now('utc')` is `…Z`. */
+export declare function now(zone?: ZoneInput): string;
+/** The time on `zone`'s wall clock. */
+export declare function currentTime(zone?: ZoneInput): string;
+/**
+ * Moves a value by a duration, keeping its kind. The calendar half (years to days) moves the wall clock, so a
+ * day later is the same time tomorrow across a DST change; the clock half (hours down) moves the instant. A
+ * date ignores the clock half, and a time wraps round midnight.
+ */
+export declare function add(input: DateInput, duration: Duration, options?: ZoneOptions): string | null;
+export declare function subtract(input: DateInput, duration: Duration, options?: ZoneOptions): string | null;
+/** The first moment of the unit a value is in — the 1st of its month, its week's first day in the locale, its hour. */
+export declare function startOf(input: DateInput, unit: DateUnit, options?: UnitOptions): string | null;
+/** The last moment of the unit — for a date, the last day; for anything with a clock, one millisecond before the next unit. */
+export declare function endOf(input: DateInput, unit: DateUnit, options?: UnitOptions): string | null;
+/**
+ * Below zero when `a` is earlier, above when later, `0` when equal. Two values of one zone-free kind compare
+ * on their wall clocks; anything else compares as instants, a zone-free side read in `zone`.
+ */
+export declare function compare(a: DateInput, b: DateInput, options?: ZoneOptions): number;
+export declare function isBefore(a: DateInput, b: DateInput, options?: ZoneOptions): boolean;
+export declare function isAfter(a: DateInput, b: DateInput, options?: ZoneOptions): boolean;
+/** Whether two inputs are the same moment — `…14:30+03:00` and `…11:30Z` are. */
+export declare function isEqual(a: DateInput, b: DateInput, options?: ZoneOptions): boolean;
+/** Whether two inputs fall in the same unit — the same day, the same week in the locale — on `zone`'s wall clock. */
+export declare function isSame(a: DateInput, b: DateInput, unit: DateUnit, options?: UnitOptions): boolean;
+/** Whether `input` is from `start` to `end`, both included. A missing end is open. */
+export declare function isBetween(input: DateInput, start: DateInput, end: DateInput, options?: ZoneOptions): boolean;
+/** The input, moved inside `[min, max]`. */
+export declare function clamp(input: DateInput, min: DateInput, max: DateInput, options?: ZoneOptions): string | null;
+/**
+ * How many whole units `a` is after `b` (negative when before). Months and years count on the calendar — 31
+ * January to 28 February is not yet a month — and days count calendar days between two dates.
+ */
+export declare function difference(a: DateInput, b: DateInput, unit: DateUnit, options?: ZoneOptions): number | null;
+/** How many days the month a value falls in has. */
+export declare function daysInMonthOf(input: DateInput, options?: ZoneOptions): number | null;
+/**
+ * Every reading of a value at once: the canonical string, the UTC moment, the moment on `zone`'s wall clock
+ * and on the reader's, the offset, a `Date`, the epoch, and the wall-clock fields. `null` for a non-value.
+ */
+export declare function details(input: DateInput, options?: ZoneOptions): DateTimeDetails | null;
+/** Minutes east of UTC that `zone` is at a moment (default now): `180` for Chisinau in summer, `-240` for New York. */
+export declare function offsetOf(zone?: ZoneInput, at?: DateInput): number | null;
+/** What a date control reports beside its value: the readings an app most often wants, all `null` for no value. */
+export interface DateReadings {
+    /** The moment in UTC, `…Z`. A date is its midnight in the control's zone; a time has none. */
+    utc: string | null;
+    /** The moment on the reader's own wall clock, with no zone. */
+    local: string | null;
+    /** The moment on the control's zone's wall clock, with its offset. */
+    zoned: string | null;
+    date: Date | null;
+    epoch: number | null;
+    /** The zone the control reads and writes in. */
+    zone: string;
+    offset: string | null;
+}
+/** The readings for a value in a control's zone — what `onValueChange` hands over beside the string. */
+export declare function readingsOf(value: string | null | undefined, zone?: ZoneInput): DateReadings;

package/utils/date/fieldModel.d.ts

@@ -0,0 +1,74 @@
+import { Disambiguation } from './zones';
+/** What a field edits: a day, a time of day, or both. */
+export type FieldType = 'date' | 'time' | 'datetime';
+/** How fine a time is edited. */
+export type FieldGranularity = 'minute' | 'second';
+/** A part of a field a person edits, one number at a time. */
+export type SegmentType = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod';
+export interface Segment {
+    type: SegmentType | 'literal';
+    /** What a literal reads — a `/`, a `.`, a `, `. */
+    text: string;
+}
+export interface FieldConfig {
+    type: FieldType;
+    locale: string;
+    hourCycle: 12 | 24;
+    granularity: FieldGranularity;
+}
+/** A field part-way through being filled in: one number per segment, `dayPeriod` 0 for AM and 1 for PM. */
+export type Draft = Partial<Record<SegmentType, number>>;
+/**
+ * The segments in the order the locale writes them, with its own separators — `dd.mm.yyyy` in Moldova,
+ * `mm/dd/yyyy` in the US, `yyyy-mm-dd` in Sweden. Read off `formatToParts`, so no locale table ships, and on
+ * the Gregorian calendar with Latin digits whatever the locale's default, since the field edits numbers.
+ */
+export declare function segmentsFor(config: FieldConfig): Segment[];
+/** The editable segments alone. */
+export declare function editable(segments: readonly Segment[]): SegmentType[];
+/** The values a segment takes. A day's top follows the month and year typed so far — 29 in a leap February. */
+export declare function rangeOf(type: SegmentType, draft: Draft, config: FieldConfig): {
+    min: number;
+    max: number;
+};
+/** Up or down by `delta`, wrapping inside the segment's range the way a clock does. An empty segment takes its placeholder. */
+export declare function step(draft: Draft, type: SegmentType, delta: number, config: FieldConfig, placeholder: Draft): Draft;
+/** How far Page Up and Page Down move a segment. */
+export declare const PAGE_STEP: Record<SegmentType, number>;
+export interface Typed {
+    draft: Draft;
+    /** The digits typed into this segment so far, which a next digit appends to. */
+    buffer: string;
+    /** Whether no further digit could make sense here, so focus moves on. */
+    advance: boolean;
+}
+/**
+ * One digit typed into a segment. It appends while the number still fits the range and starts again when it
+ * would not, and focus moves on as soon as another digit could not fit — `4` in a month is April at once,
+ * `1` waits for a `0`, `1` or `2`.
+ */
+export declare function typeDigit(draft: Draft, type: SegmentType, buffer: string, digit: string, config: FieldConfig): Typed;
+/** A letter typed into the AM/PM segment: the first letter of either period in the locale, or `a`/`p`. */
+export declare function typePeriod(draft: Draft, letter: string, locale: string): Draft | null;
+/** What a segment shows: its number padded, the digits being typed, AM/PM, or its placeholder when empty. */
+export declare function segmentText(type: SegmentType, draft: Draft, buffer: string, locale: string): string;
+export interface FieldValueOptions {
+    /** The zone a date-time is an instant in; `null` keeps it a wall clock with no zone. */
+    zone: string | null;
+    disambiguation?: Disambiguation;
+}
+/** Whether every segment the field shows has a number. */
+export declare function isComplete(draft: Draft, segments: readonly Segment[]): boolean;
+/**
+ * The value a draft spells, or `null` while a segment is empty. A day past the month's end (31 typed before a
+ * February) is pulled back onto its last day, the way a calendar would read it.
+ */
+export declare function valueOf(draft: Draft, segments: readonly Segment[], config: FieldConfig, options: FieldValueOptions): string | null;
+/** A value taken apart into a draft, on `zone`'s wall clock. Anything unreadable is an empty draft. */
+export declare function draftOf(value: string | null | undefined, config: FieldConfig, zone: string | null): Draft;
+/** The segments a draft keeps when the config changes shape — a 12-hour clock turned to 24 keeps the time. */
+export declare function reshape(draft: Draft, from: FieldConfig, to: FieldConfig): Draft;
+/** The times of a day every `step` minutes from midnight — what a time list offers. */
+export declare function timeSlots(step: number): string[];
+/** The slot a time falls in, so a list highlights 14:30 for 14:37 on a half-hour step. */
+export declare function slotOf(time: string | null, step: number): string | null;

package/utils/date/format.d.ts

@@ -0,0 +1,39 @@
+import { DateInput } from './value';
+import { ZoneInput } from './zones';
+/** What `Intl.DateTimeFormat` takes, less the zone, which is spelt `zone` here and accepts `'local'`. */
+export interface FormatOptions extends Omit<Intl.DateTimeFormatOptions, 'timeZone'> {
+    /** A BCP 47 tag. Default: the configured locale, or the runtime's. */
+    locale?: string;
+    /** The wall clock an instant is shown on. Default `'local'`. A date, a time or a date-time has no zone, so this does nothing to one. */
+    zone?: ZoneInput;
+}
+/** One formatter per locale and option set: building one costs ~40µs and formatting with a cached one ~4µs. */
+export declare function formatter(locale: string, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat;
+/**
+ * A value in the reader's words: `19 Oct 2026`, `14:30`, `Oct 19, 2026, 2:30 PM`. Pass `dateStyle`/`timeStyle`
+ * or the component options (`month: 'long'`) for another shape; with none, the kind decides. Returns `''` for
+ * an input that is not a date at all, so a missing value renders as nothing.
+ */
+export declare function format(input: DateInput, options?: FormatOptions): string;
+export declare function tidy(text: string): string;
+/** The same, as parts — what a field builds its segments from. */
+export declare function formatToParts(input: DateInput, options?: FormatOptions): Intl.DateTimeFormatPart[];
+/** Two values as one range, `Oct 19 – 23, 2026`, with what they share written once. */
+export declare function formatRange(start: DateInput, end: DateInput, options?: FormatOptions): string;
+export interface RelativeOptions {
+    locale?: string;
+    /** What "now" is. Default the current moment; pass one a server rendered with, so the browser agrees with it. */
+    now?: DateInput;
+    zone?: ZoneInput;
+    /** `'auto'` (default) says `yesterday` and `in 2 days`; `'always'` says `1 day ago`. */
+    numeric?: 'auto' | 'always';
+    style?: 'long' | 'short' | 'narrow';
+}
+/** `3 minutes ago`, `tomorrow`, `in 2 weeks`. A date is counted in calendar days, so yesterday is yesterday at any hour. */
+export declare function formatRelative(input: DateInput, options?: RelativeOptions): string;
+/** What a zone is called at an instant: `Eastern European Summer Time`, `EEST`, `GMT+3`. */
+export declare function zoneName(zone?: ZoneInput, options?: {
+    locale?: string;
+    style?: Intl.DateTimeFormatOptions['timeZoneName'];
+    at?: DateInput;
+}): string;

package/utils/date/iso.d.ts

@@ -0,0 +1,40 @@
+import { DateTimeFields } from './calendar';
+import { Disambiguation } from './zones';
+/**
+ * The four things a date value can be, and the string each one is written as:
+ *
+ * - `date` — a day with no time and no zone: `2026-10-19`. A birthday, a due date.
+ * - `time` — a wall-clock time with no date: `14:30:00`. Opening hours.
+ * - `datetime` — a date and a time with no zone: `2026-10-19T14:30:00`. "Local" in the sense of *wherever you
+ *   are* — an alarm, a train timetable. Temporal's `PlainDateTime`.
+ * - `instant` — one moment in time, written with the offset it was read in: `2026-10-19T14:30:00+03:00`, or
+ *   `…Z` in UTC. Anything stored, compared across zones or sent to a server.
+ */
+export type DateKind = 'date' | 'time' | 'datetime' | 'instant';
+/** A value taken apart: the wall clock as written, plus — for an instant — the offset and zone it was written in. */
+export interface ParsedValue {
+    kind: DateKind;
+    fields: DateTimeFields;
+    /** Minutes east of UTC. Instants only. */
+    offset: number;
+    /** The IANA zone named in brackets (`…+03:00[Europe/Chisinau]`), when there was one. */
+    zone?: string;
+}
+/** The epoch an instant names. */
+export declare function epochOf(value: ParsedValue): number;
+/**
+ * Reads an ISO 8601 / RFC 3339 / RFC 9557 string: a date, a time, a date-time, or one with an offset (`Z`,
+ * `+03:00`) and optionally a bracketed zone. `T` or a space between the halves, seconds and fractions
+ * optional, the basic form (`20261019T1430`) too. A bracketed zone with no offset is resolved in that zone.
+ */
+export declare function parseIso(input: string, disambiguation?: Disambiguation): ParsedValue | null;
+export declare function dateText(fields: DateTimeFields): string;
+/** Seconds always, milliseconds when there are any — Temporal's rule, so a value never changes length with its content. */
+export declare function timeText(fields: DateTimeFields): string;
+/** The canonical string for a value. An instant in UTC is written `Z`; in any other zone with its offset. */
+export declare function toIso(value: ParsedValue, zoneSuffix?: boolean): string;
+export declare function dateValue(fields: {
+    year: number;
+    month: number;
+    day: number;
+}): ParsedValue;

package/utils/date/locale.d.ts

@@ -0,0 +1,17 @@
+/** Which day a week starts on and which days are the weekend. Days count from 0, Sunday, the way `Date#getDay` does. */
+export interface WeekInfo {
+    firstDay: number;
+    weekend: readonly number[];
+}
+/** The locale's week, from `Intl.Locale#getWeekInfo` where the engine has it and from CLDR's table where it does not. */
+export declare function weekInfo(locale?: string): WeekInfo;
+/** Whether the locale reads the clock in 12 hours or 24. */
+export declare function hourCycleOf(locale?: string): 12 | 24;
+/** January first, in the locale's words. */
+export declare function monthNames(locale?: string, style?: 'long' | 'short' | 'narrow'): string[];
+/** Sunday first — rotate by `weekInfo().firstDay` for the order the locale reads a week in. */
+export declare function weekdayNames(locale?: string, style?: 'long' | 'short' | 'narrow'): string[];
+/** The locale's words for AM and PM. */
+export declare function dayPeriodNames(locale?: string): [string, string];
+/** What the locale calls a date field — `Jahr`, `месяц`, `hour` — for naming a segment to a screen reader. */
+export declare function fieldName(field: 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'dayPeriod' | 'timeZoneName', locale?: string): string;

package/utils/date/parse.d.ts

@@ -0,0 +1,20 @@
+import { DateKind } from './iso';
+import { DateInput, ZoneOptions } from './value';
+export interface ParseOptions extends ZoneOptions {
+    /** What to hand back. Default: whatever the input turned out to be — a date, a time, a date-time or an instant. */
+    kind?: DateKind;
+    /** Whose order `03/04/2026` is read in. Default the configured locale, or the runtime's. */
+    locale?: string;
+    /** What fills in a year the text leaves out, and the century of a two-digit one. Default today. */
+    reference?: DateInput;
+}
+type Order = ('year' | 'month' | 'day')[];
+/** The order the locale writes a numeric date in: `day month year` in Moldova, `month day year` in the US. */
+export declare function dateOrder(locale: string): Order;
+/**
+ * Reads whatever a person or a system wrote down: ISO 8601 in any of its spellings, a `Date`, epoch
+ * milliseconds, an HTTP date, or text in the locale's own order (`19.10.2026 14:30`, `10/19/2026 2:30 PM`,
+ * `19 oct 2026`, `tomorrow`). Hands back the canonical string for `kind`, or `null`.
+ */
+export declare function parse(input: DateInput, options?: ParseOptions): string | null;
+export {};

package/utils/date/settings.d.ts

@@ -0,0 +1,26 @@
+/** What the date layer falls back on when a call names no locale and no zone. */
+export interface DateSettings {
+    /** A BCP 47 tag. Unset, the runtime's own default — the browser's language, or the server's. */
+    locale?: string;
+    /**
+     * The reader's IANA zone, when the runtime is not the reader. Unset, `'local'` means the runtime's own
+     * zone: the browser's in a browser and the server's on a server. A server that knows the reader's zone —
+     * from the cookie `zoneCookie()` writes — sets it here, or passes it to the call.
+     */
+    timeZone?: string;
+}
+/** Merges into what is set; `undefined` clears one key. Returns what was set before, so a test can put it back. */
+export declare function configureDates(next: DateSettings): DateSettings;
+export declare function dateSettings(): Readonly<DateSettings>;
+/** The runtime's own IANA zone: the browser's, or the server's — `process.env.TZ`, which is UTC in most containers. */
+export declare function systemZone(): string;
+/** The reader's zone: the configured one, or the runtime's. */
+export declare function localZone(): string;
+export declare function systemLocale(): string;
+export declare function defaultLocale(): string;
+/** Forgets the runtime's zone and locale, for a test that changes `TZ` under a running process. */
+export declare function resetSystemCaches(): void;
+/** A `document.cookie` string carrying the browser's zone, so a server rendering the next request can read it. */
+export declare function zoneCookie(zone?: string, name?: string): string;
+/** The zone out of a `Cookie` header, or `undefined` — the server half of `zoneCookie()`. */
+export declare function readZoneCookie(header: string | null | undefined, name?: string): string | undefined;

package/utils/date/value.d.ts

@@ -0,0 +1,43 @@
+import { DateTimeFields } from './calendar';
+import { DateKind, ParsedValue } from './iso';
+import { Disambiguation, ZoneInput } from './zones';
+/** Anything the date layer reads: an ISO string, a `Date`, or epoch milliseconds. `null` and `undefined` read as nothing. */
+export type DateInput = string | number | Date | null | undefined;
+export interface ZoneOptions {
+    /**
+     * The zone a wall clock is read or written in. Default `'local'` — the reader's zone in a browser, and on
+     * a server the configured one (`configureDates({ timeZone })`) or the server's own.
+     */
+    zone?: ZoneInput;
+    /** What a wall-clock time a zone skips or repeats means. Default `'compatible'`. */
+    disambiguation?: Disambiguation;
+}
+/** An instant re-expressed in `zone`: same moment, that zone's wall clock and offset. */
+export declare function instantIn(epoch: number, zone: string): ParsedValue;
+/**
+ * Takes any input apart. A string is ISO 8601 / RFC 3339 / RFC 9557, or — for what a server or a mail header
+ * writes (`Mon, 19 Oct 2026 14:30:00 GMT`) — whatever `Date.parse` reads, as long as it names its offset.
+ */
+export declare function read(input: DateInput, disambiguation?: Disambiguation): ParsedValue | null;
+/** An instant written in UTC (`…Z`) with no zone named: the shape a `Date`, a server and JSON all write. */
+export declare function utcInstant(epoch: number): ParsedValue;
+/**
+ * The zone an instant is read in: the one asked for, the one it names in brackets, or the reader's. Its offset alone
+ * does not name a zone — `…Z` from a server is a moment, not a statement about where anybody is.
+ */
+export declare function zoneOf(value: ParsedValue, zone?: ZoneInput): string;
+/** A result written the way its input was: `…Z` stays `…Z`, anything else takes the zone it was worked out in. */
+export declare function written(source: ParsedValue, epoch: number, zone: string): ParsedValue;
+/**
+ * A value as another kind, in `zone` — the one conversion everything else is written on. Returns `null` for a
+ * conversion with nothing to go on: a time has no date, so it has no instant either.
+ */
+export declare function convert(value: ParsedValue, kind: DateKind, options?: ZoneOptions): ParsedValue | null;
+/** The canonical string for any input as `kind`, or `null`. */
+export declare function as(input: DateInput, kind: DateKind, options?: ZoneOptions): string | null;
+/** The epoch an input names — a date is its midnight and a date-time its wall clock, both in `zone`. */
+export declare function epochFor(value: ParsedValue, options?: ZoneOptions): number | null;
+/** The wall clock a value shows: its own fields, or for an instant the fields in `zone`. */
+export declare function wallOf(value: ParsedValue, zone?: ZoneInput): DateTimeFields;
+/** A value of the same kind built from a new wall clock, re-resolved in its zone when it is an instant. */
+export declare function withWall(value: ParsedValue, fields: DateTimeFields, options?: ZoneOptions): ParsedValue;

package/utils/date/zoneOptions.d.ts

@@ -0,0 +1,19 @@
+/** One zone as a list offers it. */
+export interface ZoneOption {
+    /** The IANA name, `Europe/Chisinau` — the value. */
+    id: string;
+    /** The place, `Chisinau`, which is what people look for. */
+    city: string;
+    /** The part before the place, `Europe`. */
+    region: string;
+    /** Minutes east of UTC right now. */
+    offset: number;
+    /** `UTC+03:00`. */
+    offsetText: string;
+    /** The label a list shows and searches: `Chisinau (UTC+03:00)`. */
+    label: string;
+}
+/** Every zone, or those given, with the offset each is at `at` — ordered west to east, then by place. */
+export declare function zoneOptions(zones?: readonly string[], at?: number): ZoneOption[];
+/** Matches a query against the place, the region, the IANA name and the offset, so `chis`, `europe` and `+3` all find Chisinau. */
+export declare function matchZone(option: ZoneOption, query: string): boolean;

package/utils/date/zones.d.ts

@@ -0,0 +1,32 @@
+import { DateTimeFields } from './calendar';
+/**
+ * Where a zone input points: `'local'` is the reader (`localZone()`), `'system'` the runtime, `'utc'` UTC,
+ * and anything else an IANA name (`'Europe/Chisinau'`) or a fixed offset (`'+03:00'`).
+ */
+export type ZoneInput = 'local' | 'system' | 'utc' | (string & {});
+/**
+ * What to do with a wall-clock time a zone skips or repeats — Temporal's four answers. `'compatible'` takes
+ * the later reading of a skipped time and the earlier of a repeated one, which is what every OS does.
+ */
+export type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
+/** Minutes east of UTC for a fixed offset (`'+03:00'`, `'-0530'`), or `undefined` for anything else. */
+export declare function fixedOffset(zone: string): number | undefined;
+/** `+03:00`, `-05:30`, `+00:00`. A historical offset carrying seconds keeps them. */
+export declare function formatOffset(minutes: number): string;
+/** The zone an input resolves to: `'UTC'`, a fixed offset in `+hh:mm` form, an IANA name — or `null` for nonsense. */
+export declare function normalizeZone(zone: ZoneInput | undefined): string | null;
+export declare function isValidZone(zone: string): boolean;
+/** `normalizeZone`, with nonsense as an error rather than a `null` to forget about. */
+export declare function requireZone(zone: ZoneInput | undefined): string;
+/** Minutes east of UTC that `zone` is at `epoch` — `+180` for Chisinau in summer, `-240` for New York. */
+export declare function offsetAt(zone: string, epoch: number): number;
+/** The wall clock `zone` shows at `epoch`. */
+export declare function wallAt(zone: string, epoch: number): DateTimeFields;
+/**
+ * The instant a wall-clock time names in `zone`. A day either side of it brackets every offset the zone could
+ * be at, so the candidates are at most two: none in a spring-forward gap, two in a fall-back overlap.
+ * Returns `null` only for `'reject'` on a time that is skipped or repeated.
+ */
+export declare function wallToEpoch(fields: DateTimeFields, zone: string, disambiguation?: Disambiguation): number | null;
+/** Every IANA zone the runtime knows, `UTC` first. */
+export declare function timeZones(): readonly string[];

package/utils/scroll/scrollUtils.d.ts

@@ -0,0 +1,6 @@
+import { ElementLike } from '../dom/domUtils';
+/**
+ * The element that scrolls `value` into view, or `null` for the page: the nearest ancestor that scrolls and has
+ * something to scroll. Both halves count — `overflow-x: hidden` alone computes `overflow-y` to `auto`.
+ */
+export declare function scrollParentOf(value: ElementLike): HTMLElement | null;

package/utils/sortable/sortableUtils.d.ts

@@ -0,0 +1,25 @@
+/** Where an item sat when a drag began, relative to the list: its top edge and its height, in px. */
+export interface SortableSlot {
+    top: number;
+    height: number;
+}
+/**
+ * The model behind `<SortableList>`: which slot a dragged item is over, how far its neighbours step aside
+ * to make room, and the keyboard's moves. The slots are read once, when the drag starts, so every answer
+ * is about the layout the person is looking at rather than one that moves under the pointer.
+ */
+declare namespace SortableUtils {
+    /** How far a press on a handle travels before it is a drag rather than a press, in px. */
+    const SLOP = 4;
+    /** The index the held item would be dropped at, having travelled `travel` px from slot `from`. */
+    function targetIndex(slots: readonly SortableSlot[], from: number, travel: number): number;
+    /** What the held item takes up in the list: its height and the gap after it, which is what a neighbour steps by. */
+    function pitchOf(slots: readonly SortableSlot[], from: number): number;
+    /** How far the item at `index` steps aside while the item from `from` is held over `to`. */
+    function shiftOf(slots: readonly SortableSlot[], from: number, to: number, index: number): number;
+    /** `array` with the entry at `from` moved to `to`, everything between stepping along by one. A new array. */
+    function move<T>(array: readonly T[], from: number, to: number): T[];
+    /** Where a key moves the held item in a list of `count`, or `null` when the key is not a move. A vertical list, so the block axis. */
+    function keyTarget(key: string, index: number, count: number): number | null;
+}
+export default SortableUtils;

package/utils/swipe/swipeUtils.d.ts

@@ -0,0 +1,53 @@
+/** Which tray a swipe reveals: `start` sits under the inline start edge, so in a left-to-right page a swipe to the right shows it. */
+export type SwipeSide = 'start' | 'end';
+/** How wide each tray is when it is fully open, in px. `0` is a side with no actions, which a swipe cannot open. */
+export interface SwipeTrays {
+    start: number;
+    end: number;
+}
+/** Where a released swipe comes to rest: open on one side, closed, or carried through to the outermost action. */
+export interface SwipeRest {
+    open: SwipeSide | null;
+    full: SwipeSide | null;
+}
+/**
+ * The model behind `<SwipeItem>`. Every offset here is **logical**: positive moves the content towards the
+ * inline end and reveals the `start` tray, so the arithmetic is the same in a right-to-left page and only
+ * the component turns it back into a physical translate. No DOM and no React — a swipe is numbers.
+ */
+declare namespace SwipeUtils {
+    /** How far a press travels before it is a gesture at all, in px — under it, a press is a tap. */
+    const SLOP = 8;
+    /** A release faster than this, in px per ms, is a flick: it goes the way it was going, however far it got. */
+    const FLICK = 0.4;
+    /** How much of the item a full swipe has to cross before letting go performs the outermost action. */
+    const FULL_RATIO = 0.6;
+    /**
+     * What a press is once it has moved past the slop: a swipe when it went more sideways than up or down,
+     * otherwise a scroll the page owns. `null` until then.
+     */
+    function intent(dx: number, dy: number): 'swipe' | 'scroll' | null;
+    /** The offset for a press that started at `rest` and has travelled `travel` along the reading order. */
+    function offsetFor(rest: number, travel: number, trays: SwipeTrays, width: number, fullSwipe: boolean): number;
+    /** The side whose outermost action a release would perform, or `null` when it has not been carried far enough. */
+    function armed(offset: number, trays: SwipeTrays, width: number, fullSwipe: boolean): SwipeSide | null;
+    /**
+     * Where a release settles. A flick goes the way it was moving; otherwise a tray past half open opens and
+     * one short of it closes — the rule every platform swipe follows, because the eye judges halfway.
+     */
+    function settle(offset: number, velocity: number, trays: SwipeTrays, width: number, fullSwipe: boolean): SwipeRest;
+    /** A pointer sample: when, in ms, and where along the line, in px. */
+    interface Sample {
+        t: number;
+        x: number;
+    }
+    /** How far back a release looks to judge its speed: the last tenth of a second is the flick, not the whole drag. */
+    const VELOCITY_WINDOW = 100;
+    /** The samples worth keeping once `next` arrives: those inside the window, and `next`. */
+    function track(samples: readonly Sample[], next: Sample): Sample[];
+    /** The speed along the line at release, in px per ms. Under a frame of samples is no measurement at all, so `0`. */
+    function velocity(samples: readonly Sample[]): number;
+    /** The offset a tray rests at: its whole width, towards the side it is on. */
+    function restOffset(open: SwipeSide | null, trays: SwipeTrays): number;
+}
+export default SwipeUtils;

package/utils/virtual/measuredWindow.d.ts

@@ -0,0 +1,28 @@
+import { VirtualWindow } from './virtualUtils';
+/**
+ * Windowing for a list whose rows each have their own height — `<VirtualList>`'s, where `VirtualUtils` is the
+ * fixed pitch a listbox has. Its own module so neither consumer carries the other's arithmetic.
+ */
+declare namespace MeasuredWindow {
+    /** Rows either side of the screen when the caller names none. */
+    const DEFAULT_OVERSCAN = 4;
+    /** How far a focused row outside the window may be from it and still be kept rendered, so focus is not dropped. */
+    const PIN_REACH = 50;
+    /** Where each row of a list whose rows differ in height starts: `count + 1` entries, the last being the total. */
+    function offsetsOf(sizes: readonly number[]): number[];
+    /** What a row not yet drawn counts as: the mean of the rows that have been, or `fallback` before any has. */
+    function typicalSize(sizes: Iterable<number>, fallback: number): number;
+    interface MeasuredWindowOptions {
+        /** From `offsetsOf`. */
+        offsets: readonly number[];
+        /** The part of the list on screen, in px from the list's own top edge. Either end may be outside the list. */
+        viewStart: number;
+        viewEnd: number;
+        overscan?: number;
+        /** A row that has to stay rendered — the one focus is in — or `-1`. */
+        pin?: number;
+    }
+    /** The rows to render for a list whose rows each have their own height, and the space above and below them. */
+    function measuredWindow(options: MeasuredWindowOptions): VirtualWindow;
+}
+export default MeasuredWindow;

package/utils/virtual/rowSearch.d.ts

@@ -0,0 +1,11 @@
+/** Where each row starts, ascending: an array, or a list that computes an entry when it is asked for one. */
+export type RowTops = {
+    readonly length: number;
+    readonly [index: number]: number;
+};
+/**
+ * The row a point `y` falls in — the last of the first `count` rows that starts at or above it — clamped
+ * to the list. A binary search, since a scroll asks on every frame and a datasource grid lays out a million
+ * rows it never allocates. `DataGrid` and `VirtualList` both window through it.
+ */
+export declare function rowAt(tops: RowTops, y: number, count?: number): number;