pixelize-native-library 1.0.6 → 1.2.0

package/lib/typescript/modules/data-table/DataTable.variants.d.ts

@@ -0,0 +1,118 @@
+/**
+ * DataTable's style + behaviour resolution — the same split every sibling module copies
+ * (see `Select.variants.ts` / `Menu.variants.ts`):
+ *  - STRUCTURE (row/cell layout, padding, border WIDTH) lives in the variant resolvers below —
+ *    static per (brand, mode), registered once via `StyleSheet.create`.
+ *  - COLOUR is resolved from the theme's ROLE colours (`resolveDataTableColors`), never a raw ramp,
+ *    never a hardcoded hex. A table has no per-instance colour choice, so the resolver takes no
+ *    selector argument (same shape as `resolveCheckboxColors`).
+ *  - BEHAVIOUR (sort cycling, selection set maths, the sorted-column accessible name) is pure here
+ *    so the contract is unit-testable without rendering React Native.
+ *
+ * Free of React, of `lucide`, and of any native import, so the WCAG + behaviour tests import it
+ * directly (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
+ */
+import type { RoleColors, Theme } from "../../theme/hooks";
+export type DataTableAlign = "left" | "center" | "right";
+export type DataTableSortDirection = "asc" | "desc";
+/** The three glyphs a header can show. A literal union rather than an `IconName` import, so this
+ *  file stays free of the icon registry (which pulls `lucide` at runtime); `Icon`'s own `name` prop
+ *  still type-checks these against the closed `IconName` set at the call site. */
+export type DataTableSortIcon = "chevron-up" | "chevron-down" | "chevrons-up-down";
+/** Same touch-target floor as Button/Select (44dp — Apple HIG minimum, WCAG 2.5.5 AAA). */
+export declare const MIN_TOUCH_TARGET = 44;
+/** Header cells are sortable buttons, so the header is a direct 44dp target — never slop-expanded. */
+export declare const DATA_TABLE_HEADER_HEIGHT = 44;
+export declare const DATA_TABLE_DEFAULT_ROW_HEIGHT = 48;
+export declare const DATA_TABLE_DEFAULT_COLUMN_WIDTH = 120;
+export declare const DATA_TABLE_SELECT_COLUMN_WIDTH = 48;
+export declare const DATA_TABLE_SORT_ICON_SIZE = 14;
+export declare const DATA_TABLE_SKELETON_ROW_COUNT = 5;
+export declare const DATA_TABLE_SKELETON_CELL_HEIGHT = 12;
+/**
+ * Symmetric touch expansion for a pressable row, so `rowHeight + 2·slop ≥ 44` even when a caller
+ * passes a compact `rowHeight` (same `slopFor` technique `Button`/`Select` use for their short sizes).
+ */
+export declare function rowTouchSlop(rowHeight: number): number;
+export declare function resolveColumnWidth(width: number | undefined): number;
+/** The row's full width — what the header and every body row are pinned to, so the two stay aligned
+ *  while the shared horizontal `ScrollView` moves them together. */
+export declare function resolveTotalWidth(widths: readonly (number | undefined)[], selectable: boolean): number;
+export interface DataTableColors {
+    /** Header fill. `bg.sunken` separates the header band from the body without a second border. */
+    readonly headerBackground: string;
+    /** Header label — `fg.muted`, measured ≥ 4.5:1 on `headerBackground` for every brand × mode. */
+    readonly headerText: string;
+    /** Sort glyph. The SAME value as `headerText`: a colour that clears the stricter 4.5:1 text
+     *  minimum clears the icon's 3:1 non-text minimum for free (Menu/Select's identical argument). */
+    readonly headerIcon: string;
+    /** The header/body boundary — `border.interactive` (≥ 3:1, WCAG 1.4.11), not the decorative
+     *  `border.default`, which is a ~1.2:1 hairline on every brand. */
+    readonly headerBorder: string;
+    /** Even-row fill. */
+    readonly rowBackground: string;
+    /** Odd-row zebra fill. */
+    readonly rowBackgroundAlt: string;
+    /** Pressed-row fill. `bg.raised` rather than `bg.sunken`, because `bg.sunken` is already the zebra
+     *  stripe — pressing an odd row would otherwise change nothing. `bg.hover` is excluded for the
+     *  reason `ListItem` documents (it drops `fg.default` below 4.5:1 on 4 light brands). */
+    readonly rowPressed: string;
+    /** Body cell text, measured ≥ 4.5:1 on all three row fills above. */
+    readonly cellText: string;
+}
+export declare function resolveDataTableColors(colors: RoleColors): DataTableColors;
+/** Zebra striping, or the pressed fill when the row is being touched. */
+export declare function resolveRowBackground(colors: DataTableColors, index: number, pressed: boolean): string;
+/**
+ * asc → desc → asc on the active column; any other column starts at asc. Pressing a new column
+ * never inherits the previous column's direction — a fresh sort reads ascending.
+ */
+export declare function nextSortDirection(columnKey: string, activeKey: string | undefined, activeDirection: DataTableSortDirection | undefined): DataTableSortDirection;
+export declare function resolveSortIcon(columnKey: string, activeKey: string | undefined, activeDirection: DataTableSortDirection | undefined): DataTableSortIcon;
+/**
+ * WCAG 1.3.3 / 4.1.2 — the sort glyph is a visual-only cue, so the header's accessible name carries
+ * the same state in words. Without this a screen-reader user hears only the column title and cannot
+ * tell which column the table is sorted by.
+ */
+export declare function resolveSortAccessibilityLabel(header: string, columnKey: string, activeKey: string | undefined, activeDirection: DataTableSortDirection | undefined): string;
+/**
+ * Fallback cell text when a column has no `render`. `row` is generic and unconstrained (a table
+ * accepts any shape of data), so reading `column.key` off it is a deliberate, narrow escape from
+ * `T` rather than a real type hole — the alternative is forcing every caller to supply `render`.
+ */
+export declare function resolveDefaultCellText(row: unknown, key: string): string;
+export declare function toggleSelectionKey(selectedKeys: readonly string[], key: string): string[];
+export interface DataTableSelectAllState {
+    readonly checked: boolean;
+    readonly indeterminate: boolean;
+}
+export declare function resolveSelectAllState(selectedKeys: readonly string[], rowKeys: readonly string[]): DataTableSelectAllState;
+/**
+ * Select-all only ever adds or removes the rows currently in `data` — a key selected elsewhere
+ * (a previous page, a filtered-out row) survives both directions, so the caller owns the full set.
+ */
+export declare function resolveSelectAllSelection(selectedKeys: readonly string[], rowKeys: readonly string[]): string[];
+export declare const dataTableRowStructure: import("../../core/style").VariantResolver<import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const dataTableHeaderRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const dataTableCellStructure: import("../../core/style").ThemedVariantResolver<Theme, {
+    align: {
+        left: {
+            justifyContent: "flex-start";
+        };
+        center: {
+            justifyContent: "center";
+        };
+        right: {
+            justifyContent: "flex-end";
+        };
+    };
+}, import("react-native").ViewStyle>;
+/**
+ * The keyboard/AT focus ring for a sortable header cell or a pressable row, drawn INSIDE the
+ * element's own bounds. Both are full-bleed: a header cell abuts its neighbours and a row spans the
+ * table's whole width, so the gap-outside ring `Button`/`CopyButton` use would be clipped by the
+ * table's own scroll containers. Square, like the cells it sits in. Colour is applied inline.
+ */
+export declare const dataTableFocusRingStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const dataTableSelectCellStructure: import("../../core/style").VariantResolver<import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=DataTable.variants.d.ts.map

package/lib/typescript/modules/data-table/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public surface of `pixelize-native-library/data-table`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. The resolvers (`resolveDataTableColors`, `nextSortDirection`, …) stay
+ * internal — a consumer configures a DataTable through its props, never by importing its internals.
+ */
+export { DataTable } from "./DataTable";
+export type { DataTableProps, DataTableColumn } from "./DataTable";
+export type { DataTableAlign, DataTableSortDirection } from "./DataTable.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/date-picker/Calendar.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Calendar — the inline month grid every other export in this module composes. All of its date
+ * arithmetic lives in `DatePicker.variants.ts` (pure, unit-tested); this file is layout, state and
+ * accessibility only.
+ *
+ * The header doubles as a quick-jump toggle: while it is open the grid shows the twelve months of
+ * the cursor's year and the ‹ › controls page YEARS instead of months — one panel covering both
+ * dimensions, instead of a separate year grid and month grid to navigate between. The ‹ › controls
+ * themselves are the library's own `Button` (icon-only, ghost/neutral) — composed, not
+ * reimplemented; only the toggle needs a custom `Pressable`, for the `aria-expanded` (WCAG 4.1.2)
+ * `Button`'s closed a11y contract can't express (see `resolveCalendarChromeColors`).
+ *
+ * Keyboard (web only, WCAG 2.1.1): the 42 day cells are ONE tab stop, not 42 — exactly one carries
+ * `tabIndex={0}` and the arrows/Home/End/PageUp/PageDown move which. The DOM half lives in
+ * `Calendar.keys.web.ts`, the date arithmetic in `resolveCalendarFocusMove`; Enter/Space are left
+ * to `react-native-web`'s own `role="button"` press handling.
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { CalendarSelectionMode, DateRange, FirstDayOfWeek } from "./DatePicker.variants";
+export interface CalendarProps {
+    /** The selected day in `"single"` mode. Ignored in `"range"` mode. */
+    value?: Date | null;
+    /** Fires with the tapped day at local noon. Alias: `onSelect`. */
+    onChange?: (date: Date) => void;
+    /** Same as `onChange` — preferred name for single-select usage. */
+    onSelect?: (date: Date) => void;
+    mode?: CalendarSelectionMode;
+    rangeValue?: DateRange | null;
+    onRangeChange?: (range: DateRange) => void;
+    minDate?: Date;
+    maxDate?: Date;
+    disabledDates?: Date[];
+    /** `1` = Monday (default), `0` = Sunday. */
+    firstDayOfWeek?: FirstDayOfWeek;
+    /** Drives month + weekday NAMES only, via `Intl.DateTimeFormat`. */
+    locale?: string;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const Calendar: import("react").NamedExoticComponent<CalendarProps>;
+//# sourceMappingURL=Calendar.d.ts.map

package/lib/typescript/modules/date-picker/Calendar.keys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Native/default counterpart of `Calendar.keys.web.ts`. A physical keyboard driving a month grid is
+ * a web concern, so both hooks are no-ops here with identical signatures.
+ *
+ * Same `.ts` / `.web.ts` pair `core/a11y/keyboard.ts` and `../modal/renderWebPortal.ts` use: Metro
+ * resolves the `.web.ts` only for a web bundle, so no DOM code enters the native graph, and Jest
+ * (whose `react-native` preset has no `web` platform) always resolves THIS file — the web half is
+ * tested by importing it explicitly.
+ *
+ * These live in the module rather than in `core/a11y` on purpose: `useRovingKeys` models one flat
+ * list on one axis, and a month grid is 2-D over Dates (week wrapping, month paging). Forcing it
+ * into that helper would distort both.
+ */
+import type { RefObject } from "react";
+import type { View } from "react-native";
+import type { CalendarFocusMove } from "./DatePicker.variants";
+export declare function useCalendarGridKeys(_ref: RefObject<View | null>, _active: boolean, _onMove: (move: CalendarFocusMove) => void): void;
+export declare function useCalendarGridFocus(_ref: RefObject<View | null>, _focusedKey: string, _active: boolean): void;
+//# sourceMappingURL=Calendar.keys.d.ts.map

package/lib/typescript/modules/date-picker/Calendar.keys.web.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Web implementation of the Calendar day-grid's keyboard navigation. Metro only resolves this file
+ * for a web bundle (see `Calendar.keys.ts`), so it is the one place here that may assume a DOM.
+ *
+ * The DOM types are hand-written for the same reason `core/a11y/keyboard.web.ts` writes its own:
+ * `tsconfig.json` sets `"lib": ["ESNext"]`, `any` is lint-banned, and augmenting `react-native`'s
+ * types would ship through `lib/typescript/**`. A module-local structural surface plus
+ * `declare const document` erases entirely at emit.
+ *
+ * This file owns ONLY the DOM half — which key means which move, and moving real focus. Every date
+ * calculation lives in `resolveCalendarFocusMove` (`DatePicker.variants.ts`), pure and unit-tested.
+ *
+ * Enter and Space are deliberately unhandled: the day cells are `role="button"`, which
+ * `react-native-web`'s `PressResponder.isValidKeyPress` already presses on both keys. Handling them
+ * here too would select the day twice.
+ */
+import type { RefObject } from "react";
+import type { View } from "react-native";
+import type { CalendarFocusMove } from "./DatePicker.variants";
+/**
+ * Arrow/Home/End/PageUp/PageDown on the grid container. Listens on the CONTAINER (capture phase),
+ * never on `document`, so two calendars on one page never fight over the same arrow key, and so an
+ * arrow pressed on the ‹ › header buttons is left alone.
+ */
+export declare function useCalendarGridKeys(ref: RefObject<View | null>, active: boolean, onMove: (move: CalendarFocusMove) => void): void;
+/**
+ * Moves real DOM focus onto whichever day cell currently owns `tabIndex={0}`, after `focusedKey`
+ * changed the roving index.
+ *
+ * The `contains` guard is the whole safety of this hook: it only ever moves focus that is ALREADY
+ * inside the grid. Without it, a caller's own selection (or the first mount) would rip focus out of
+ * the field that opened the picker.
+ */
+export declare function useCalendarGridFocus(ref: RefObject<View | null>, focusedKey: string, active: boolean): void;
+//# sourceMappingURL=Calendar.keys.web.d.ts.map

package/lib/typescript/modules/date-picker/DatePicker.d.ts

@@ -0,0 +1,40 @@
+/**
+ * DatePicker — a field styled like `Input`'s box (`PickerField`) that opens `Calendar` and/or
+ * `TimePicker` in `PickerShell` (React Native's OWN `Modal` — see `PickerShell.tsx`). In
+ * `"datetime"` mode the sheet shows a Date | Time `Tabs` strip above the active panel — the
+ * library's own `Tabs` component, composed rather than reimplemented.
+ *
+ * The sheet edits a local DRAFT, never `value` directly: `Calendar`/`TimePicker` inside the modal
+ * report into `draft`, and only Confirm commits it via `onChange`. Cancel — and the backdrop, which
+ * is the same dismissal — discards the draft, so "Cancel restores the prior value" holds by
+ * construction (the prior value was never touched).
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { DatePickerMode, FirstDayOfWeek } from "./DatePicker.variants";
+export interface DatePickerProps {
+    value?: Date | null;
+    onChange: (date: Date | null) => void;
+    mode?: DatePickerMode;
+    /** When true (default for `mode="date"`), tapping a day commits and closes the sheet. */
+    confirmOnSelect?: boolean;
+    label?: string;
+    placeholder?: string;
+    minDate?: Date;
+    maxDate?: Date;
+    disabled?: boolean;
+    error?: string;
+    clearable?: boolean;
+    /** Replaces the ENTIRE field text, including the time half in `"datetime"` mode. Defaults to a
+     *  medium `Intl` date (plus a hand-built clock string — see `formatTime`'s doc comment). */
+    format?: (date: Date) => string;
+    use24Hour?: boolean;
+    /** `1` = Monday (default), `0` = Sunday. */
+    firstDayOfWeek?: FirstDayOfWeek;
+    /** Drives month + weekday NAMES only, via `Intl.DateTimeFormat`. */
+    locale?: string;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    containerStyle?: LayoutStyle;
+    testID?: string;
+}
+export declare const DatePicker: import("react").NamedExoticComponent<DatePickerProps>;
+//# sourceMappingURL=DatePicker.d.ts.map

package/lib/typescript/modules/date-picker/DatePicker.variants.d.ts

@@ -0,0 +1,322 @@
+/**
+ * date-picker's date maths + style/behaviour resolution. Same split every reference module uses:
+ *  - PURE DATE MATHS (grid building, comparison, clamping, formatting) lives here so the bug-prone
+ *    part — leap years, month boundaries, DST — is unit-tested without a renderer.
+ *  - STRUCTURE (heights, padding, radius, border WIDTH) lives in the `createThemedVariants`
+ *    resolvers, registered once per theme identity.
+ *  - COLOUR is resolved from the theme's ROLE colours by `resolveCalendarDayColors` /
+ *    `resolveTimeOptionColors` / `resolveDateFieldColors`, never a hardcoded hex.
+ *  - ACCESSIBILITY prop derivation is pure too, so the day-cell / field contracts are testable.
+ *
+ * Free of React and of `lucide`, so the WCAG + maths tests import it directly (mocking only
+ * `react-native`'s `StyleSheet`, as `core/style` does).
+ *
+ * EVERY `Date` this module constructs is anchored at local NOON. A date built at midnight lands on
+ * the previous day in any zone whose DST transition happens at 00:00 (America/Santiago,
+ * Asia/Beirut) — the single most common calendar bug class there is.
+ */
+import type { RoleColors, Theme } from "../../theme/hooks";
+export type CalendarSelectionMode = "single" | "range";
+export type DatePickerMode = "date" | "datetime" | "time";
+/** `1` = Monday (the library default — the team and its consumer apps are India-based, where the
+ *  week starts on Monday), `0` = Sunday. */
+export type FirstDayOfWeek = 0 | 1;
+export type Meridiem = "AM" | "PM";
+export interface DateRange {
+    readonly start: Date | null;
+    readonly end: Date | null;
+}
+export interface MonthCursor {
+    readonly year: number;
+    /** 0-indexed, matching `Date#getMonth`. */
+    readonly month: number;
+}
+/** Same floor as Button/Select — 44dp (WCAG 2.5.5 / HIG). Duplicated, not imported: modules stay
+ *  isolated. */
+export declare const MIN_TOUCH_TARGET = 44;
+export declare const DAY_CELL_MIN_HEIGHT = 44;
+export declare const QUICK_JUMP_CELL_MIN_HEIGHT = 44;
+export declare const TIME_OPTION_HEIGHT = 44;
+/** The field matches `Input`'s `md` box exactly (height, font, icon, slop) so a DatePicker and an
+ *  Input sitting side by side in a form line up with no seam. */
+export declare const DATE_FIELD_HEIGHT = 40;
+export declare const DATE_FIELD_FONT_SIZE = 16;
+export declare const DATE_FIELD_ICON_SIZE = 18;
+export declare const DATE_FIELD_INNER_HEIGHT: number;
+/** Sized against `DATE_FIELD_INNER_HEIGHT` — the height the trigger actually renders at — so the
+ *  real target clears 44dp (`DatePicker.render.test.tsx` asserts the rendered node, not the sum). */
+export declare const DATE_FIELD_HIT_SLOP = 3;
+/** The clear affordance is narrower than the field is tall, so it reaches 44×44 through `hitSlop`
+ *  — 6dp, which is smaller than the field's `space[2]` column gap, so its target can never overlap
+ *  the trailing calendar glyph's. */
+export declare const CLEAR_BUTTON_WIDTH = 32;
+export declare const CLEAR_BUTTON_HIT_SLOP = 6;
+export declare const GRID_COLUMNS = 7;
+/** Always six rows, so the sheet's height never jumps between a 4-row February and a 6-row March. */
+export declare const GRID_ROWS = 6;
+export declare const GRID_CELL_COUNT: number;
+export declare const QUICK_JUMP_COLUMNS = 3;
+export declare const MONTHS_IN_YEAR = 12;
+export declare const HOURS_IN_DAY = 24;
+export declare const MINUTES_IN_HOUR = 60;
+export declare const DEFAULT_LOCALE = "en-US";
+export declare const DEFAULT_FIRST_DAY_OF_WEEK: FirstDayOfWeek;
+export declare const DEFAULT_PLACEHOLDER = "Select date";
+/** En dash, spaced — the typographic range separator, not a hyphen. */
+export declare const RANGE_SEPARATOR = " \u2013 ";
+/** Hour a fresh `datetime`/`time` selection starts from when the caller passed no value. Noon, for
+ *  the same DST reason every date here is built at noon. */
+export declare const DEFAULT_TIME_HOUR = 12;
+/** The same calendar day, at local noon. */
+export declare function atNoon(date: Date): Date;
+/** Local noon on `year`/`month`/`day`. Out-of-range `month`/`day` roll over exactly as `Date` does,
+ *  which is what makes grid building and month arithmetic a single expression below. */
+export declare function makeDate(year: number, month: number, day: number): Date;
+/** Sortable YYYYMMDD integer. Comparing these instead of timestamps makes every day-level predicate
+ *  immune to time-of-day and to DST offsets. */
+export declare function dayOrdinal(date: Date): number;
+/** `2024-03-15`. The stable per-day key for React lists and `testID`s. */
+export declare function toDayKey(date: Date): string;
+export declare function isSameDay(a: Date | null | undefined, b: Date | null | undefined): boolean;
+/** Inclusive of both endpoints. A reversed pair (`end` before `start`) is normalised, so a caller
+ *  mid-drag never gets `false` for every day. */
+export declare function isWithinRange(date: Date, start: Date | null | undefined, end: Date | null | undefined): boolean;
+/** Day-level clamp — the result is always at noon, so it is safe to hand straight to `onChange`. */
+export declare function clampToRange(date: Date, minDate?: Date | null, maxDate?: Date | null): Date;
+export interface DateDisabledOptions {
+    readonly minDate?: Date | null | undefined;
+    readonly maxDate?: Date | null | undefined;
+    readonly disabledDates?: readonly Date[] | undefined;
+}
+export declare function isDateDisabled(date: Date, options?: DateDisabledOptions): boolean;
+export interface MonthGridDay {
+    readonly date: Date;
+    readonly dayOfMonth: number;
+    /** False for the leading/trailing days borrowed from the neighbouring months. */
+    readonly inCurrentMonth: boolean;
+}
+/**
+ * The 6×7 cell grid for one month, in display order. `month` is 0-indexed (`Date#getMonth`), and
+ * out-of-range values roll over — `buildMonthGrid(2024, 12, 1)` is January 2025.
+ */
+export declare function buildMonthGrid(year: number, month: number, firstDayOfWeek?: FirstDayOfWeek): MonthGridDay[];
+export declare function chunkIntoWeeks(days: readonly MonthGridDay[]): MonthGridDay[][];
+export declare function monthCursorOf(date: Date): MonthCursor;
+export declare function addMonths(cursor: MonthCursor, delta: number): MonthCursor;
+/** True when at least one day of the month is inside `[minDate, maxDate]` — the enablement rule for
+ *  the ‹ › month navigation. */
+export declare function canShowMonth(cursor: MonthCursor, minDate?: Date | null, maxDate?: Date | null): boolean;
+/** The same rule one level up — the ‹ › navigation pages years while the quick-jump grid is open. */
+export declare function canShowYear(year: number, minDate?: Date | null, maxDate?: Date | null): boolean;
+/**
+ * One arrow/Home/End/PageUp/PageDown press's effect on the day-grid's roving focus. Pure and
+ * platform-agnostic: `Calendar.keys.web.ts` only maps DOM key names onto these, so the whole 2-D
+ * traversal — week wrapping, month boundaries — is unit-testable without a DOM.
+ *
+ * Deliberately NOT `core/a11y`'s `useRovingKeys`: that helper's model is one flat list with one
+ * axis, and a month grid needs both axes over a Date, not an index.
+ */
+export type CalendarFocusMove = "prevDay" | "nextDay" | "prevWeek" | "nextWeek" | "weekStart" | "weekEnd" | "prevMonth" | "nextMonth";
+export declare function resolveCalendarFocusMove(move: CalendarFocusMove, from: Date, firstDayOfWeek?: FirstDayOfWeek): Date;
+export declare const EMPTY_RANGE: DateRange;
+/**
+ * One tap's effect on a range. A tap starts a fresh range whenever there is nothing to extend
+ * (no start, or a complete range) or when it lands before the current start; otherwise it closes
+ * the range.
+ */
+export declare function nextRangeSelection(current: DateRange, date: Date): DateRange;
+/** The default field text — a medium date (`Mar 15, 2024` in `en-US`). */
+export declare function formatDate(date: Date, locale?: string): string;
+/** The FULL readable date a day cell announces (WCAG 1.3.1) — never the bare day number. */
+export declare function formatFullDate(date: Date, locale?: string): string;
+export declare function formatMonthYear(cursor: MonthCursor, locale?: string): string;
+export declare function formatYear(year: number, locale?: string): string;
+export declare function monthShortNames(locale?: string): string[];
+/** Seven weekday abbreviations in display order. 2023-01-01 was a Sunday, so `+ dayIndex` walks
+ *  `getDay()` 0..6 without any lookup table. */
+export declare function weekdayLabels(firstDayOfWeek?: FirstDayOfWeek, locale?: string): string[];
+export declare function toDisplayHour(hour24: number, use24Hour: boolean): number;
+export declare function toMeridiem(hour24: number): Meridiem;
+export declare function fromDisplayHour(displayHour: number, meridiem: Meridiem, use24Hour: boolean): number;
+/** Moves an hour across the AM/PM boundary without touching which hour of the half-day it is. */
+export declare function applyMeridiem(hour24: number, meridiem: Meridiem): number;
+export declare function buildHourOptions(use24Hour: boolean): number[];
+/** `step` is clamped to 1..60; a non-finite step falls back to 1 rather than looping forever. */
+export declare function buildMinuteOptions(step?: number): number[];
+/** `base`'s calendar day at `hour24`:`minute`. No base → today. */
+export declare function withTime(base: Date | null | undefined, hour24: number, minute: number): Date;
+/** `day`'s calendar day at `base`'s time of day. No base → noon, so a fresh selection is DST-safe. */
+export declare function withDay(base: Date | null | undefined, day: Date): Date;
+/**
+ * Deliberately NOT `Intl`-formatted. `locale` on this module is documented as driving month and
+ * weekday NAMES only; a hand-built clock string is identical on every engine, which matters because
+ * Hermes' `Intl` support varies by platform and RN version.
+ */
+export declare function formatTime(date: Date, use24Hour?: boolean): string;
+export interface FieldValueOptions {
+    readonly locale?: string | undefined;
+    readonly use24Hour?: boolean | undefined;
+    /** Replaces the ENTIRE field text, including the time half in `datetime` mode. */
+    readonly format?: ((date: Date) => string) | undefined;
+}
+export declare function formatFieldValue(value: Date | null | undefined, mode: DatePickerMode, options?: FieldValueOptions): string;
+/** A half-open range shows only the end it has — never a dangling separator. */
+export declare function formatRangeValue(range: DateRange | null | undefined, format: (date: Date) => string): string;
+export interface CalendarDayState {
+    /** The single selected day, or a range endpoint. */
+    readonly selected: boolean;
+    /** Inside a complete range (endpoints included — `selected` takes precedence for those). */
+    readonly inRange: boolean;
+    /** A leading/trailing day borrowed from a neighbouring month. */
+    readonly adjacent: boolean;
+    readonly disabled: boolean;
+    readonly today: boolean;
+    readonly pressed: boolean;
+}
+export interface CalendarDayColors {
+    /** Always a concrete fill (the sheet's own surface when the cell is "unfilled"), so every
+     *  label/background pair the component can render is measurable. */
+    readonly background: string;
+    readonly label: string;
+    /** The today ring — a border, never a fill: fill is reserved for selection. `undefined` on a
+     *  selected cell, whose accent fill already marks it. */
+    readonly ring: string | undefined;
+}
+/**
+ * Maps one cell's state onto role colours. The press fill is `bg.raised`, NOT `bg.sunken`: the
+ * range-middle label is `accent.text`, which measures 4.40:1 on `bg.sunken` (slate light) — just
+ * under AA — and 4.63:1 on `bg.raised`. Same class of fix `Tabs` documents for its pressed tab.
+ *
+ * A SELECTED cell keeps its accent fill while pressed: its label is `accent.onSolid`, which is only
+ * derived to be readable on `accent.solid`.
+ *
+ * The today ring reads `fg.muted`, not an accent token: `fg.muted` is proven ≥ 4.5:1 against
+ * `bg.surface` specifically (`readableOn(gray, [background[50], backgroundColor.muted])` in
+ * `roles/index.ts`) — comfortably clearing the ring's 3:1 floor on every brand × mode. `accent.solid`
+ * is only proven readable AGAINST its own derived `onSolid` label, never against a neutral surface,
+ * so it is not a safe ring colour here.
+ */
+export declare function resolveCalendarDayColors(colors: RoleColors, state: CalendarDayState): CalendarDayColors;
+export interface CalendarChromeColors {
+    readonly surface: string;
+    readonly weekdayLabel: string;
+    readonly headerLabel: string;
+    readonly headerIcon: string;
+    readonly headerPressed: string;
+}
+/**
+ * `headerLabel`/`headerIcon` on `surface` reuse the exact pairing `Select`'s trigger text/icon
+ * already prove against `bg.surface` (`Select.test.ts`); `headerPressed` reuses `bg.sunken`, the
+ * same press fill `Select`'s option rows prove `fg.default` stays ≥ 4.5:1 on. The month +/- nav
+ * itself is the library's own `Button` (icon-only, ghost/neutral) — already contrast-proven in
+ * `Button.test.ts` — so this table only covers the custom month/year quick-jump toggle, which
+ * needs `aria-expanded` (WCAG 4.1.2) that `Button`'s closed a11y contract can't
+ * express, the same reason `Select`'s own trigger is a custom `Pressable` and not `Button`.
+ */
+export declare function resolveCalendarChromeColors(colors: RoleColors): CalendarChromeColors;
+export interface TimeOptionState {
+    readonly selected: boolean;
+    readonly pressed: boolean;
+}
+export interface TimeOptionColors {
+    readonly background: string;
+    readonly label: string;
+}
+export declare function resolveTimeOptionColors(colors: RoleColors, state: TimeOptionState): TimeOptionColors;
+export interface DateFieldState {
+    readonly focused: boolean;
+    readonly invalid: boolean;
+}
+export interface DateFieldColors {
+    readonly border: string;
+    readonly text: string;
+    readonly placeholder: string;
+    readonly icon: string;
+    readonly message: string;
+    readonly label: string;
+}
+/**
+ * The field's colours, token-for-token identical to `Input`'s: the error border reads
+ * `status.danger.solid` (the decorative `status.danger.border` measures below 3:1 on every brand),
+ * and the box paints no background of its own so it reads on whatever canvas the form sits on.
+ */
+export declare function resolveDateFieldColors(colors: RoleColors, state: DateFieldState): DateFieldColors;
+export interface DateFieldAccessibilityInput {
+    readonly label?: string | undefined;
+    /** The formatted value, or `""` when empty. */
+    readonly displayValue: string;
+    readonly placeholder: string;
+    readonly disabled?: boolean | undefined;
+    readonly open: boolean;
+}
+export interface DateFieldAccessibilityProps {
+    readonly accessibilityRole: "button";
+    readonly accessibilityLabel: string;
+    /** Flat, not `accessibilityState`: react-native-web discards the object form entirely. */
+    readonly "aria-disabled": boolean;
+    readonly "aria-expanded": boolean;
+    /** The `Pressable disabled` prop — blocks opening the picker while disabled. */
+    readonly disabled: boolean;
+}
+/**
+ * RN has no `htmlFor`-equivalent link from a field to its sibling label `Text`, so the label's text
+ * is folded into the field's own accessible name — the same fallback `Input`/`Select` make.
+ */
+export declare function resolveDateFieldAccessibility(input: DateFieldAccessibilityInput): DateFieldAccessibilityProps;
+export interface CalendarDayAccessibilityInput {
+    readonly date: Date;
+    readonly selected: boolean;
+    readonly disabled: boolean;
+    /** Inside a range but not an endpoint — colour alone conveys it, so it must reach the label too. */
+    readonly inRange?: boolean | undefined;
+    readonly today?: boolean | undefined;
+    readonly locale?: string | undefined;
+}
+export interface CalendarDayAccessibilityProps {
+    readonly accessibilityRole: "button";
+    /** The FULL readable date — a screen reader announcing "15" tells the user nothing. */
+    readonly accessibilityLabel: string;
+    /** Flat, not `accessibilityState`: react-native-web discards the object form entirely. */
+    readonly "aria-selected": boolean;
+    readonly "aria-disabled": boolean;
+}
+/** Appended to a day's label when the grid conveys the state with colour only (WCAG 1.4.1). */
+export declare const TODAY_SUFFIX = "today";
+export declare const IN_RANGE_SUFFIX = "in selected range";
+export declare function resolveCalendarDayAccessibility(input: CalendarDayAccessibilityInput): CalendarDayAccessibilityProps;
+export declare const calendarStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const calendarHeaderStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** The month/year quick-jump toggle — the one custom header control (see `resolveCalendarChromeColors`
+ *  for why it isn't `Button`). The ‹ › month/year nav either side of it IS `Button` (icon-only). */
+export declare const calendarHeaderButtonStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Wraps the six week rows so the keyboard grid has one node to listen on and to scope its cell
+ *  lookup to. Repeats `calendarStructure`'s own `rowGap` so nesting changes no spacing. */
+export declare const calendarGridStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** No column gap: a range fill has to be continuous across the days it spans. */
+export declare const calendarWeekRowStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const calendarWeekdayCellStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/**
+ * `flex: 1` (not a fixed 44dp width) because seven columns must fit the narrowest phone: the cell's
+ * HEIGHT always meets the 44dp floor, its width only above 364dp — 7 × 44 plus 56dp of horizontal
+ * chrome (overlay 2 × 12 + sheet 2 × 8 + calendar 2 × 8). Cells are ~43.4dp at Android's common
+ * 360dp and ~37.7dp on an iPhone SE. See MODULE.md's "Known gaps".
+ */
+export declare const calendarDayCellStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const quickJumpGridStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const quickJumpCellStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Visible rows before a column scrolls. */
+export declare const TIME_VISIBLE_ROWS = 5;
+export declare const timeColumnsStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const timeColumnStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const timeOptionStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Byte-for-byte `Input`'s `md` box — same height, padding, radius and hairline. */
+export declare const dateFieldStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const clearButtonStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Tighter horizontal padding than Select's sheet: seven 44dp columns need the width. */
+export declare const pickerOverlayStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const pickerSheetStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+/** Houses the two `Button`s (Cancel/Confirm) — colour, touch target and press feedback are entirely
+ *  `Button`'s own already-proven surface (`Button.test.ts`), same "compose, don't reimplement"
+ *  choice `alert-dialog` makes for its identical action row. */
+export declare const pickerFooterStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+//# sourceMappingURL=DatePicker.variants.d.ts.map

package/lib/typescript/modules/date-picker/DateRangePicker.d.ts

@@ -0,0 +1,32 @@
+/**
+ * DateRangePicker — the same field+modal shell as `DatePicker` (`PickerField`/`PickerShell`),
+ * driving `Calendar` in `mode="range"` instead of `"single"`. No `mode`/`use24Hour` — a date RANGE
+ * has no time-of-day dimension in this module's spec, matching `Calendar`'s own
+ * `rangeValue`/`onRangeChange` pair (`Calendar`'s single-date `value`/`onChange` are simply unused
+ * here, exactly as its own doc comment anticipates for a "range-only Calendar").
+ */
+import type { LayoutStyle } from "../../core/style";
+import type { DateRange, FirstDayOfWeek } from "./DatePicker.variants";
+export interface DateRangePickerProps {
+    value?: DateRange;
+    onChange: (range: DateRange) => void;
+    label?: string;
+    placeholder?: string;
+    minDate?: Date;
+    maxDate?: Date;
+    disabled?: boolean;
+    error?: string;
+    clearable?: boolean;
+    /** Formats ONE endpoint; the field joins `start`/`end` with the typographic range separator.
+     *  Defaults to a medium `Intl` date (`formatDate`). */
+    format?: (date: Date) => string;
+    /** `1` = Monday (default), `0` = Sunday. */
+    firstDayOfWeek?: FirstDayOfWeek;
+    /** Drives month + weekday NAMES only, via `Intl.DateTimeFormat`. */
+    locale?: string;
+    /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
+    containerStyle?: LayoutStyle;
+    testID?: string;
+}
+export declare const DateRangePicker: import("react").NamedExoticComponent<DateRangePickerProps>;
+//# sourceMappingURL=DateRangePicker.d.ts.map