@xaui/native 0.9.1-alpha.9 → 0.9.1-alpha.91

package/dist/utils/dates.d.cts

@@ -0,0 +1,93 @@
+/** Sunday is 0, as `Date.getDay()` has it. */
+export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** A closed interval. Either end may be absent, and an absent end is unbounded. */
+export type DateBounds = {
+    min?: Date;
+    max?: Date;
+};
+/**
+ * Midnight, local time.
+ *
+ * **Every comparison in this file goes through it**, because a `Date` is an instant and a
+ * calendar day is not: two instants eleven hours apart are the same square on the grid, and
+ * `a.getTime() === b.getTime()` would say they are not. Constructing a new date from the
+ * three parts is also what drops the time zone question — the parts are already local.
+ */
+/**
+ * How many days that month has, with `month` zero-based as `Date` has it.
+ *
+ * Asked by anything that has to keep a day number inside its month — a masked field where
+ * the reader has typed 31 into February, a calendar clamping a chosen day as the month
+ * changes under it.
+ */
+export declare function daysInMonth(year: number, month: number): number;
+export declare function startOfDay(date: Date): Date;
+/** The same square on the grid, whatever time either one carries. */
+export declare function isSameDay(a: Date, b: Date): boolean;
+export declare function isSameMonth(a: Date, b: Date): boolean;
+/**
+ * `count` days later, or earlier when it is negative.
+ *
+ * Through the day-of-month rather than through milliseconds: a day is not always 86 400
+ * seconds, and adding that many across a daylight-saving boundary lands an hour into the
+ * day before. `Date` normalises an out-of-range day itself, so day 32 of January is the
+ * first of February with no arithmetic here.
+ */
+export declare function addDays(date: Date, count: number): Date;
+/**
+ * `count` months later, **clamped to the end of the target month**.
+ *
+ * The clamp is the whole reason this is not one line: `new Date(2026, 0, 31)` plus a month
+ * is the 31st of February, which `Date` rolls forward to the 3rd of March. A calendar
+ * stepping from January to February must land on February, and the last day of it is the
+ * only answer that is not a different month.
+ */
+export declare function addMonths(date: Date, count: number): Date;
+/** The first day of `date`'s week, given which day a week starts on. */
+export declare function startOfWeek(date: Date, firstDayOfWeek?: WeekDay): Date;
+/**
+ * Whether a day falls inside the bounds — **compared by day, not by instant**.
+ *
+ * A `max` of "today" written as `new Date()` carries the current time, and an instant
+ * comparison would refuse the rest of today. Normalising both ends is what makes a bound a
+ * date rather than a moment.
+ */
+export declare function isWithinBounds(date: Date, bounds?: DateBounds): boolean;
+/**
+ * The forty-two days a month grid shows: the month itself, and enough of the months either
+ * side to fill the first and last weeks.
+ *
+ * **Always forty-two, never five weeks for a short month.** A grid that changed height
+ * between March and April would move everything under it twice a year, and the calendar
+ * would jump as you paged through it.
+ */
+export declare function monthGrid(month: Date, firstDayOfWeek?: WeekDay): Date[];
+/** The seven days of `date`'s week, in the order they are read. */
+export declare function weekGrid(date: Date, firstDayOfWeek?: WeekDay): Date[];
+/**
+ * Which day the week starts on where the caller is.
+ *
+ * `Intl.Locale`'s week info answers it properly and is the right answer where it exists —
+ * Saturday-first locales are real, and a hand-kept list of Monday-first ones has never
+ * included them. It is missing from most React Native engines, so the list is the fallback
+ * rather than the source, and the list is only ever asked Monday or Sunday.
+ */
+export declare function firstDayOfWeekFor(locale: string): WeekDay;
+/**
+ * The seven weekday names, starting on the right day.
+ *
+ * Any January in a known year would do as a source of seven consecutive days; 2023 opened
+ * on a Sunday, which makes the offset arithmetic below read as what it is.
+ */
+export declare function weekdayNames(locale: string, firstDayOfWeek?: WeekDay, format?: Intl.DateTimeFormatOptions['weekday']): string[];
+/** The month and the year, as the header reads them — "septembre 2026". */
+export declare function monthLabel(month: Date, locale: string): string;
+/**
+ * The twelve month names, in the calendar's locale — "janvier", "février", … — for the
+ * month grid the year picker drills into.
+ *
+ * Any year would do as a source of twelve consecutive months; 2023 is the one
+ * `weekdayNames` already uses. Falls back to English long names on an engine with no
+ * `Intl`, like every other formatter in this file.
+ */
+export declare function monthNames(locale: string, format?: Intl.DateTimeFormatOptions['month']): string[];

package/dist/utils/dates.d.ts

@@ -0,0 +1,93 @@
+/** Sunday is 0, as `Date.getDay()` has it. */
+export type WeekDay = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** A closed interval. Either end may be absent, and an absent end is unbounded. */
+export type DateBounds = {
+    min?: Date;
+    max?: Date;
+};
+/**
+ * Midnight, local time.
+ *
+ * **Every comparison in this file goes through it**, because a `Date` is an instant and a
+ * calendar day is not: two instants eleven hours apart are the same square on the grid, and
+ * `a.getTime() === b.getTime()` would say they are not. Constructing a new date from the
+ * three parts is also what drops the time zone question — the parts are already local.
+ */
+/**
+ * How many days that month has, with `month` zero-based as `Date` has it.
+ *
+ * Asked by anything that has to keep a day number inside its month — a masked field where
+ * the reader has typed 31 into February, a calendar clamping a chosen day as the month
+ * changes under it.
+ */
+export declare function daysInMonth(year: number, month: number): number;
+export declare function startOfDay(date: Date): Date;
+/** The same square on the grid, whatever time either one carries. */
+export declare function isSameDay(a: Date, b: Date): boolean;
+export declare function isSameMonth(a: Date, b: Date): boolean;
+/**
+ * `count` days later, or earlier when it is negative.
+ *
+ * Through the day-of-month rather than through milliseconds: a day is not always 86 400
+ * seconds, and adding that many across a daylight-saving boundary lands an hour into the
+ * day before. `Date` normalises an out-of-range day itself, so day 32 of January is the
+ * first of February with no arithmetic here.
+ */
+export declare function addDays(date: Date, count: number): Date;
+/**
+ * `count` months later, **clamped to the end of the target month**.
+ *
+ * The clamp is the whole reason this is not one line: `new Date(2026, 0, 31)` plus a month
+ * is the 31st of February, which `Date` rolls forward to the 3rd of March. A calendar
+ * stepping from January to February must land on February, and the last day of it is the
+ * only answer that is not a different month.
+ */
+export declare function addMonths(date: Date, count: number): Date;
+/** The first day of `date`'s week, given which day a week starts on. */
+export declare function startOfWeek(date: Date, firstDayOfWeek?: WeekDay): Date;
+/**
+ * Whether a day falls inside the bounds — **compared by day, not by instant**.
+ *
+ * A `max` of "today" written as `new Date()` carries the current time, and an instant
+ * comparison would refuse the rest of today. Normalising both ends is what makes a bound a
+ * date rather than a moment.
+ */
+export declare function isWithinBounds(date: Date, bounds?: DateBounds): boolean;
+/**
+ * The forty-two days a month grid shows: the month itself, and enough of the months either
+ * side to fill the first and last weeks.
+ *
+ * **Always forty-two, never five weeks for a short month.** A grid that changed height
+ * between March and April would move everything under it twice a year, and the calendar
+ * would jump as you paged through it.
+ */
+export declare function monthGrid(month: Date, firstDayOfWeek?: WeekDay): Date[];
+/** The seven days of `date`'s week, in the order they are read. */
+export declare function weekGrid(date: Date, firstDayOfWeek?: WeekDay): Date[];
+/**
+ * Which day the week starts on where the caller is.
+ *
+ * `Intl.Locale`'s week info answers it properly and is the right answer where it exists —
+ * Saturday-first locales are real, and a hand-kept list of Monday-first ones has never
+ * included them. It is missing from most React Native engines, so the list is the fallback
+ * rather than the source, and the list is only ever asked Monday or Sunday.
+ */
+export declare function firstDayOfWeekFor(locale: string): WeekDay;
+/**
+ * The seven weekday names, starting on the right day.
+ *
+ * Any January in a known year would do as a source of seven consecutive days; 2023 opened
+ * on a Sunday, which makes the offset arithmetic below read as what it is.
+ */
+export declare function weekdayNames(locale: string, firstDayOfWeek?: WeekDay, format?: Intl.DateTimeFormatOptions['weekday']): string[];
+/** The month and the year, as the header reads them — "septembre 2026". */
+export declare function monthLabel(month: Date, locale: string): string;
+/**
+ * The twelve month names, in the calendar's locale — "janvier", "février", … — for the
+ * month grid the year picker drills into.
+ *
+ * Any year would do as a source of twelve consecutive months; 2023 is the one
+ * `weekdayNames` already uses. Falls back to English long names on an engine with no
+ * `Intl`, like every other formatter in this file.
+ */
+export declare function monthNames(locale: string, format?: Intl.DateTimeFormatOptions['month']): string[];

package/dist/utils/decorator-box.d.cts

@@ -0,0 +1,25 @@
+import type { ViewStyle } from 'react-native';
+import type { XAUITheme } from '../theme/theme.type';
+/**
+ * What `FieldGroup.Prefix` and `FieldGroup.Suffix` share — everything but the edge they
+ * are pinned to. They are taken **out of flow** and laid over the field, which is what
+ * lets the box stay the field node itself: no wrapper borrows its border, its fill and
+ * its radius, so a `FieldGroup` and a bare field cannot drift apart. The field clears
+ * them by their measured width.
+ *
+ * `zIndex` is not decoration: the prefix is written before the field, so without it the
+ * field's own fill paints over the glyph.
+ *
+ * **And `zIndex` alone is not enough on Android**, which is why the elevation is here too.
+ * `primary` is the one variant that lifts its field — `theme.shadows.field`, which carries
+ * an `elevation` — and an elevated sibling holds a *native* Z that a React `zIndex` does
+ * not outrank: the field ends up over the decorator in the order Android hit-tests, and a
+ * `TextInput` swallows the touch. The symptom is a suffix that is plainly visible and does
+ * nothing, on `primary` and nowhere else — a `NumberField`'s stepper pair, a reveal toggle,
+ * a clear button.
+ *
+ * A step above the field's own rather than a number written here, so the two cannot drift.
+ * It draws no shadow of its own: Android takes an elevation shadow from the view's outline
+ * and a decorator has no background to give it one.
+ */
+export declare const decoratorBox: (theme: XAUITheme) => ViewStyle;

package/dist/utils/decorator-box.d.ts

@@ -0,0 +1,25 @@
+import type { ViewStyle } from 'react-native';
+import type { XAUITheme } from '../theme/theme.type';
+/**
+ * What `FieldGroup.Prefix` and `FieldGroup.Suffix` share — everything but the edge they
+ * are pinned to. They are taken **out of flow** and laid over the field, which is what
+ * lets the box stay the field node itself: no wrapper borrows its border, its fill and
+ * its radius, so a `FieldGroup` and a bare field cannot drift apart. The field clears
+ * them by their measured width.
+ *
+ * `zIndex` is not decoration: the prefix is written before the field, so without it the
+ * field's own fill paints over the glyph.
+ *
+ * **And `zIndex` alone is not enough on Android**, which is why the elevation is here too.
+ * `primary` is the one variant that lifts its field — `theme.shadows.field`, which carries
+ * an `elevation` — and an elevated sibling holds a *native* Z that a React `zIndex` does
+ * not outrank: the field ends up over the decorator in the order Android hit-tests, and a
+ * `TextInput` swallows the touch. The symptom is a suffix that is plainly visible and does
+ * nothing, on `primary` and nowhere else — a `NumberField`'s stepper pair, a reveal toggle,
+ * a clear button.
+ *
+ * A step above the field's own rather than a number written here, so the two cannot drift.
+ * It draws no shadow of its own: Android takes an elevation shadow from the view's outline
+ * and a decorator has no background to give it one.
+ */
+export declare const decoratorBox: (theme: XAUITheme) => ViewStyle;

package/dist/utils/discovery.d.cts

@@ -0,0 +1,68 @@
+import type { Anchor, Size2D } from './placement';
+/** Where the parts of a coach mark go, in the coordinates of the host it is drawn in. */
+export type DiscoveryGeometry = {
+    /** The accent disc, centred on the target. */
+    circle: Box;
+    /** The ring around the target, saying which thing is being talked about. */
+    halo: Box;
+    /** The target's own rectangle, for the copy drawn over the disc. */
+    target: Rect;
+    /**
+     * The block of text: which edge it is pinned to, where it starts, how wide it may be,
+     * and which way its lines set. It has no height of its own — the text decides that, up
+     * to `maxHeight`.
+     *
+     * **One of `top` and `bottom`, never both.** A block under the target is pinned by its
+     * top, because that is the edge nearest the thing it describes; a block above one is
+     * pinned by its **bottom**, for the same reason — and that is what lets it grow upwards
+     * as the text gets longer instead of running down into the target.
+     */
+    message: {
+        top?: number;
+        bottom?: number;
+        start: number;
+        width: number;
+        maxHeight: number;
+        align: 'start' | 'end';
+    };
+};
+type Box = {
+    size: number;
+    top: number;
+    start: number;
+};
+type Rect = {
+    top: number;
+    start: number;
+    width: number;
+    height: number;
+};
+export type DiscoveryInput = {
+    target: Anchor;
+    window: Size2D;
+    /** The disc's diameter as a multiple of the window's width. */
+    scale: number;
+    /** How far the halo stands off the target, in points. */
+    padding: number;
+    /** The rendered height of the message, once it has been measured. */
+    messageHeight?: number;
+};
+/**
+ * A coach mark's geometry: a disc centred on the thing being taught, a ring around it, and
+ * a block of text that fits **inside the disc** rather than beside it.
+ *
+ * That last part is the only interesting arithmetic here. The text is placed at a `y`, and
+ * how wide the disc is at that `y` is the chord of a circle — `√(r² − dy²)` — so a block
+ * near the disc's centre is nearly its full width and one near the top or bottom is a
+ * sliver. Laying the text out at the disc's width instead would run it past the curve at
+ * both ends, which is the shape everybody's first coach mark has.
+ *
+ * When that chord is too narrow to read a paragraph in, the block gives up on the disc and
+ * sets from the screen's own edge instead — the side the target is **not** on, so the text
+ * runs away from the thing it describes rather than under it.
+ *
+ * A pure function so the arithmetic can be tested, and because none of it is React's: the
+ * caller measures the target and hands the rectangle over.
+ */
+export declare function discoveryGeometry({ target, window, scale, padding, messageHeight, }: DiscoveryInput): DiscoveryGeometry;
+export {};

package/dist/utils/discovery.d.ts

@@ -0,0 +1,68 @@
+import type { Anchor, Size2D } from './placement';
+/** Where the parts of a coach mark go, in the coordinates of the host it is drawn in. */
+export type DiscoveryGeometry = {
+    /** The accent disc, centred on the target. */
+    circle: Box;
+    /** The ring around the target, saying which thing is being talked about. */
+    halo: Box;
+    /** The target's own rectangle, for the copy drawn over the disc. */
+    target: Rect;
+    /**
+     * The block of text: which edge it is pinned to, where it starts, how wide it may be,
+     * and which way its lines set. It has no height of its own — the text decides that, up
+     * to `maxHeight`.
+     *
+     * **One of `top` and `bottom`, never both.** A block under the target is pinned by its
+     * top, because that is the edge nearest the thing it describes; a block above one is
+     * pinned by its **bottom**, for the same reason — and that is what lets it grow upwards
+     * as the text gets longer instead of running down into the target.
+     */
+    message: {
+        top?: number;
+        bottom?: number;
+        start: number;
+        width: number;
+        maxHeight: number;
+        align: 'start' | 'end';
+    };
+};
+type Box = {
+    size: number;
+    top: number;
+    start: number;
+};
+type Rect = {
+    top: number;
+    start: number;
+    width: number;
+    height: number;
+};
+export type DiscoveryInput = {
+    target: Anchor;
+    window: Size2D;
+    /** The disc's diameter as a multiple of the window's width. */
+    scale: number;
+    /** How far the halo stands off the target, in points. */
+    padding: number;
+    /** The rendered height of the message, once it has been measured. */
+    messageHeight?: number;
+};
+/**
+ * A coach mark's geometry: a disc centred on the thing being taught, a ring around it, and
+ * a block of text that fits **inside the disc** rather than beside it.
+ *
+ * That last part is the only interesting arithmetic here. The text is placed at a `y`, and
+ * how wide the disc is at that `y` is the chord of a circle — `√(r² − dy²)` — so a block
+ * near the disc's centre is nearly its full width and one near the top or bottom is a
+ * sliver. Laying the text out at the disc's width instead would run it past the curve at
+ * both ends, which is the shape everybody's first coach mark has.
+ *
+ * When that chord is too narrow to read a paragraph in, the block gives up on the disc and
+ * sets from the screen's own edge instead — the side the target is **not** on, so the text
+ * runs away from the thing it describes rather than under it.
+ *
+ * A pure function so the arithmetic can be tested, and because none of it is React's: the
+ * caller measures the target and hands the rectangle over.
+ */
+export declare function discoveryGeometry({ target, window, scale, padding, messageHeight, }: DiscoveryInput): DiscoveryGeometry;
+export {};

package/dist/utils/filter-items.d.cts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+/**
+ * Whether a row survives what has been typed.
+ *
+ * `includes` rather than `startsWith`: a long list is searched by whichever word someone
+ * remembers as often as by the one that happens to come first, and a prefix match on
+ * "New York" refuses "york".
+ *
+ * An empty query keeps everything, which is what makes the field's resting state the whole
+ * list rather than none of it.
+ */
+export declare function matchesQuery(label: string, query: string): boolean;
+/**
+ * The children with the rows that do not survive the query dropped, and a count of the ones
+ * that did.
+ *
+ * **Direct children only.** `collectItemLabels` walks the whole tree because reading a label
+ * changes nothing, where dropping a row nested inside a caller's own component would mean
+ * rebuilding that component's children for it — and a filter that silently rewrote a
+ * caller's tree is worse than one that leaves it alone. A row wrapped in something of your
+ * own is a row the search will not hide.
+ *
+ * The count is what tells the content whether to show its empty state, and it counts **rows**
+ * rather than children: a label or a separator surviving is not a result.
+ *
+ * Shared by the `Autocomplete` and the `Combobox` — the same panel filtered by the same
+ * query, typed into two different fields. §2 bis: promotion at the second use, beside
+ * `collectItemLabels`, which was promoted for the same pair one component earlier.
+ */
+export declare function filterItems(children: ReactNode, query: string, isItem: (type: unknown) => boolean): {
+    children: ReactNode[];
+    matched: number;
+};

package/dist/utils/filter-items.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+/**
+ * Whether a row survives what has been typed.
+ *
+ * `includes` rather than `startsWith`: a long list is searched by whichever word someone
+ * remembers as often as by the one that happens to come first, and a prefix match on
+ * "New York" refuses "york".
+ *
+ * An empty query keeps everything, which is what makes the field's resting state the whole
+ * list rather than none of it.
+ */
+export declare function matchesQuery(label: string, query: string): boolean;
+/**
+ * The children with the rows that do not survive the query dropped, and a count of the ones
+ * that did.
+ *
+ * **Direct children only.** `collectItemLabels` walks the whole tree because reading a label
+ * changes nothing, where dropping a row nested inside a caller's own component would mean
+ * rebuilding that component's children for it — and a filter that silently rewrote a
+ * caller's tree is worse than one that leaves it alone. A row wrapped in something of your
+ * own is a row the search will not hide.
+ *
+ * The count is what tells the content whether to show its empty state, and it counts **rows**
+ * rather than children: a label or a separator surviving is not a result.
+ *
+ * Shared by the `Autocomplete` and the `Combobox` — the same panel filtered by the same
+ * query, typed into two different fields. §2 bis: promotion at the second use, beside
+ * `collectItemLabels`, which was promoted for the same pair one component earlier.
+ */
+export declare function filterItems(children: ReactNode, query: string, isItem: (type: unknown) => boolean): {
+    children: ReactNode[];
+    matched: number;
+};

package/dist/utils/flip.d.cts

@@ -0,0 +1,20 @@
+/** Which of the two faces. */
+export type FlipFace = 'front' | 'back';
+/** Which way round the card turns. */
+export type FlipRotation = 'normal' | 'reverse';
+/**
+ * How far a face is turned, in degrees, at that point in the flip.
+ *
+ * The two faces are **a half turn apart at every moment**, which is the whole trick: the
+ * front starts flat and ends face-down, the back starts face-down and ends flat, and because
+ * a hidden backface is not drawn, exactly one of them is on screen at any angle.
+ *
+ * Writing it as one function rather than two expressions in the component is what makes that
+ * relationship testable — and it is the one thing a flip gets wrong: a back that is a
+ * separate spring, or a back at `progress * 180` rather than `(progress − 1) * 180`, shows
+ * two faces at once through the middle of the turn.
+ *
+ * `reverse` negates both, so the card comes round the other way. Negating one of them would
+ * make the two faces meet rather than follow each other.
+ */
+export declare function faceAngle(progress: number, face: FlipFace, rotation?: FlipRotation): number;

package/dist/utils/flip.d.ts

@@ -0,0 +1,20 @@
+/** Which of the two faces. */
+export type FlipFace = 'front' | 'back';
+/** Which way round the card turns. */
+export type FlipRotation = 'normal' | 'reverse';
+/**
+ * How far a face is turned, in degrees, at that point in the flip.
+ *
+ * The two faces are **a half turn apart at every moment**, which is the whole trick: the
+ * front starts flat and ends face-down, the back starts face-down and ends flat, and because
+ * a hidden backface is not drawn, exactly one of them is on screen at any angle.
+ *
+ * Writing it as one function rather than two expressions in the component is what makes that
+ * relationship testable — and it is the one thing a flip gets wrong: a back that is a
+ * separate spring, or a back at `progress * 180` rather than `(progress − 1) * 180`, shows
+ * two faces at once through the middle of the turn.
+ *
+ * `reverse` negates both, so the card comes round the other way. Negating one of them would
+ * make the two faces meet rather than follow each other.
+ */
+export declare function faceAngle(progress: number, face: FlipFace, rotation?: FlipRotation): number;

package/dist/utils/item-labels.d.cts

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+/**
+ * The `value` and label of every row in a tree, read from the **elements** rather than from
+ * mounted components.
+ *
+ * A trigger has to name the chosen row before that row has ever rendered: the list lives in
+ * a portal that only mounts when it opens, so a control with a `defaultValue` would show
+ * its placeholder until the user opened it once and closed it again. React hands the
+ * content its children as elements whatever it does with them, and a label is a prop or a
+ * string child — both readable without mounting anything.
+ *
+ * A row wrapped in a component of the caller's own is not reachable this way, which is what
+ * a `children` escape hatch on the value slot is for.
+ *
+ * Shared by the `Select` and the `Autocomplete`: the same trigger, the same portal, the
+ * same problem. §2 bis — promotion at the second use.
+ */
+export declare function collectItemLabels(children: ReactNode, isItem: (type: unknown) => boolean): ReadonlyArray<readonly [string, string]>;
+/** A row's label: the prop if it has one, else whatever its children stringify to. */
+export declare function readItemLabel(props: {
+    label?: string;
+    children?: ReactNode;
+}): string | undefined;

package/dist/utils/item-labels.d.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+/**
+ * The `value` and label of every row in a tree, read from the **elements** rather than from
+ * mounted components.
+ *
+ * A trigger has to name the chosen row before that row has ever rendered: the list lives in
+ * a portal that only mounts when it opens, so a control with a `defaultValue` would show
+ * its placeholder until the user opened it once and closed it again. React hands the
+ * content its children as elements whatever it does with them, and a label is a prop or a
+ * string child — both readable without mounting anything.
+ *
+ * A row wrapped in a component of the caller's own is not reachable this way, which is what
+ * a `children` escape hatch on the value slot is for.
+ *
+ * Shared by the `Select` and the `Autocomplete`: the same trigger, the same portal, the
+ * same problem. §2 bis — promotion at the second use.
+ */
+export declare function collectItemLabels(children: ReactNode, isItem: (type: unknown) => boolean): ReadonlyArray<readonly [string, string]>;
+/** A row's label: the prop if it has one, else whatever its children stringify to. */
+export declare function readItemLabel(props: {
+    label?: string;
+    children?: ReactNode;
+}): string | undefined;

package/dist/utils/mask.d.cts

@@ -0,0 +1,121 @@
+/**
+ * The four shapes `MaskField` ships ready-made. Anything else is a **pattern string** —
+ * `#` a digit, `A` a letter, `*` either, every other character a literal put back in as the
+ * parts fill.
+ */
+export type MaskFieldMask = 'date' | 'time' | 'datetime' | 'credit-card';
+export declare const MASK_FIELD_MASKS: readonly ["date", "time", "datetime", "credit-card"];
+/**
+ * Which of the three parts of a date comes first, and which second.
+ *
+ * Three orders rather than every permutation, because these are the three the world writes:
+ * day-first across most of Europe, month-first in the United States, year-first in East
+ * Asia and in ISO 8601.
+ */
+export type DateOrder = 'DMY' | 'MDY' | 'YMD';
+/** What a placeholder calls each date part. The letters are a language's, so they are given. */
+export type SegmentLabels = {
+    day: string;
+    month: string;
+    year: string;
+};
+/** The class of input a fill position accepts. */
+type Fill = 'digit' | 'letter' | 'alnum';
+/**
+ * One run of a resolved mask: a `fill` of positions that accept input, or a `literal` that
+ * is typed back in once the parts before it have something in them.
+ *
+ * A completed fill may `clamp` — a month at 12, a day at the length of its month — reading
+ * the parts already written to do it. A fill is never *raised*: a reader halfway through
+ * `01` has typed a zero, and moving it under them loses the keystroke.
+ */
+type Part = {
+    kind: 'fill';
+    fill: Fill;
+    width: number;
+    name: string;
+    clamp?: (raw: string, written: Record<string, string>) => string;
+} | {
+    kind: 'literal';
+    text: string;
+};
+/** A mask resolved to the parts a keystroke is walked through. */
+export type Mask = {
+    parts: readonly Part[];
+    /** The shape shown when the box is empty — `DD/MM/YYYY`, `#### #### #### ####`. */
+    placeholder: string;
+    /** The full rendered length, so the field can cap the caret at the end of the shape. */
+    length: number;
+    /** `number-pad` when every fill is digits, `default` otherwise. */
+    keyboard: 'number-pad' | 'default';
+};
+/**
+ * The order that locale writes a date in.
+ *
+ * Read out of `Intl` rather than off a table of countries: the platform already ships the
+ * answer for every locale it supports, and a table here would be a second one, shorter and
+ * out of date. A locale `Intl` does not know falls back to day-first, which is what most of
+ * the world writes.
+ */
+export declare function dateOrderFor(locale: string): DateOrder;
+/**
+ * The separator that locale writes between the date parts.
+ *
+ * The same argument as the order, and the same fallback. A locale that writes its date with
+ * a word between the parts — some do — has no single separator, so anything that is not one
+ * character comes back as a slash.
+ */
+export declare function dateSeparatorFor(locale: string): string;
+export type ResolveMaskOptions = {
+    /** The order and the separator come from here for `date` / `datetime` when neither is set. */
+    locale?: string;
+    /** Give it when the order is a decision rather than a locale — an ISO field is `YMD`. */
+    order?: DateOrder;
+    /** Between the date parts. Unset, it is the one the locale writes. */
+    separator?: string;
+    /** What the placeholder calls each date part. */
+    labels?: SegmentLabels;
+};
+/**
+ * A `mask` prop — a preset name or a pattern string — to the parts a keystroke walks.
+ *
+ * The presets carry rules a pattern cannot: `date` and `datetime` take their order and
+ * separator from the locale, and `date`, `datetime` and `time` clamp their parts as they
+ * complete. `credit-card` and any pattern are shape only.
+ */
+export declare function resolveMask(spec: MaskFieldMask | string, options?: ResolveMaskOptions): Mask;
+/**
+ * What the reader typed, as this mask writes it.
+ *
+ * The input and the parts are walked in lockstep: a literal is **eaten** off the input when
+ * it is already there and **put back** when it is not, and a fill takes the next characters
+ * of its class, skipping anything that is not. That is what makes the field survive a paste,
+ * a keyboard that offers its own punctuation, a backspace over a separator — and being run
+ * over its own output, which a field re-rendered from a controlled `value` does on every
+ * keystroke. `maskInput(maskInput(x))` is `maskInput(x)`.
+ *
+ * A fill is clamped only once it is full, and never raised.
+ */
+export declare function maskInput(input: string, mask: Mask): string;
+/**
+ * The `Date` a `date` mask's text is, or `null` while it is not one.
+ *
+ * `null` covers both "not finished" and "not a real day", and deliberately so: a caller
+ * holding a `Date | null` needs no third state. A year is taken as written — `0023` is the
+ * year 23, not 2023 — since guessing a century is the kind of help that is wrong once and
+ * then silently wrong forever.
+ */
+export declare function parseMaskedDate(text: string, locale?: string, order?: DateOrder): Date | null;
+/** A `Date` as a `date` mask writes it — the inverse of `parseMaskedDate`. */
+export declare function formatMaskedDate(date: Date, locale?: string, order?: DateOrder, separator?: string): string;
+/** The hours and minutes a `time` mask's text is, or `null` while it is not both. */
+export declare function parseMaskedTime(text: string): {
+    hours: number;
+    minutes: number;
+} | null;
+/** Hours and minutes as a `time` mask writes them — `09:05`. */
+export declare function formatMaskedTime(time: {
+    hours: number;
+    minutes: number;
+}): string;
+export {};