@box-kite/react 2.2.5 → 2.2.6

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[];