pixelize-native-library 1.0.7 → 1.2.1

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

@@ -0,0 +1,334 @@
+/**
+ * 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 PressedAccessibilityState {
+    /** The WEB half of "this is the chosen value". Every `role="button"` option this module renders
+     *  (a day cell, a quick-jump month, an hour/minute/meridiem) reports its chosen state through
+     *  `aria-pressed` — `aria-selected` is invalid on `role="button"` and browsers ignore it, same fix
+     *  `chip`'s filter toggle uses. More than one option can be pressed at once (a date range's two
+     *  endpoints); nothing in `aria-pressed` requires the mutual exclusivity a radio group would. */
+    readonly "aria-pressed": boolean;
+    /** The NATIVE half — react-native-web discards the object form, so no invalid `aria-selected`
+     *  reaches the DOM; native accessibility has no "pressed" state, so `selected` is the nearest. */
+    readonly accessibilityState: {
+        readonly selected: boolean;
+    };
+}
+export declare function resolvePressedAccessibilityState(selected: boolean): PressedAccessibilityState;
+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 extends PressedAccessibilityState {
+    readonly accessibilityRole: "button";
+    /** The FULL readable date — a screen reader announcing "15" tells the user nothing. */
+    readonly accessibilityLabel: string;
+    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

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

@@ -0,0 +1,26 @@
+/**
+ * PickerField — the pressable field box shared by `DatePicker` and `DateRangePicker`, styled
+ * byte-for-byte like `Input`'s `md` box (see `dateFieldStructure`'s doc comment) so either sits
+ * beside a real `Input` in a form with no visual seam. NOT part of this module's public surface —
+ * both pickers differ only in what value they format and how "clear" resets it; the field's markup,
+ * a11y wiring and focus/error treatment are otherwise identical.
+ */
+import type { IconName } from "../../core/icon";
+export interface PickerFieldProps {
+    label?: string;
+    placeholder: string;
+    /** The formatted value, or `""` when empty — also what gates the clear button. */
+    displayText: string;
+    error?: string;
+    disabled: boolean;
+    /** Whether the picker sheet is open — folded into the field's focus ring + `expanded` state. */
+    open: boolean;
+    clearable: boolean;
+    clearAccessibilityLabel: string;
+    trailingIcon: IconName;
+    onPress: () => void;
+    onClear: () => void;
+    testID?: string;
+}
+export declare const PickerField: import("react").NamedExoticComponent<PickerFieldProps>;
+//# sourceMappingURL=PickerField.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * PickerShell — the modal chrome (backdrop, overlay, sheet, Cancel/Confirm footer) shared by
+ * `DatePicker` and `DateRangePicker`. NOT part of this module's public surface (not re-exported
+ * from `index.ts`): the two pickers differ only in what they render as `children` (Calendar /
+ * TimePicker / a `Tabs` strip) — the sheet's presentation, dismissal and confirm/cancel wiring are
+ * otherwise identical, so this is a plain internal composition helper, the same "compose, don't
+ * reimplement" choice `alert-dialog` makes for its Modal + Button pairing.
+ *
+ * Renders in React Native's OWN `Modal`, imported directly from `"react-native"` — same reasoning
+ * as `Select`/`Menu`: this module owns its sheet's markup outright, never the library's own `Modal`
+ * COMPONENT (a persistent app dialog with a title/children contract is a different shape than a
+ * confirm/cancel picker sheet). The one deliberate exception is the web portal mechanism
+ * (`ModalPortalContext`/`renderWebPortal`), read for the same reason `Select.tsx`/`Menu.tsx` read
+ * it — see `../modal/ModalPortalContext.ts`.
+ */
+import type { ReactNode } from "react";
+export interface PickerShellProps {
+    open: boolean;
+    /** Names the sheet for a screen reader landing on it — it has no visible title to borrow. */
+    accessibilityLabel: string;
+    onCancel: () => void;
+    onConfirm: () => void;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    children: ReactNode;
+    testID?: string;
+}
+export declare const PickerShell: import("react").NamedExoticComponent<PickerShellProps>;
+//# sourceMappingURL=PickerShell.d.ts.map

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

@@ -0,0 +1,14 @@
+/**
+ * TimePicker — hour / minute (/ AM-PM) selection columns.
+ */
+import type { LayoutStyle } from "../../core/style";
+export interface TimePickerProps {
+    value?: Date | null;
+    onChange: (date: Date) => void;
+    use24Hour?: boolean;
+    minuteStep?: number;
+    style?: LayoutStyle;
+    testID?: string;
+}
+export declare const TimePicker: import("react").NamedExoticComponent<TimePickerProps>;
+//# sourceMappingURL=TimePicker.d.ts.map

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

@@ -0,0 +1,16 @@
+/**
+ * Public surface of `pixelize-native-library/date-picker`. Value exports and type exports are split
+ * for `verbatimModuleSyntax`. `PickerField`/`PickerShell` are internal composition helpers (see
+ * their own doc comments) and are deliberately not re-exported — a consumer builds a date/time UI
+ * through `Calendar`, `TimePicker`, `DatePicker`, or `DateRangePicker`, never their internals.
+ */
+export { Calendar } from "./Calendar";
+export type { CalendarProps } from "./Calendar";
+export { TimePicker } from "./TimePicker";
+export type { TimePickerProps } from "./TimePicker";
+export { DatePicker } from "./DatePicker";
+export type { DatePickerProps } from "./DatePicker";
+export { DateRangePicker } from "./DateRangePicker";
+export type { DateRangePickerProps } from "./DateRangePicker";
+export type { CalendarSelectionMode, DatePickerMode, DateRange, FirstDayOfWeek, Meridiem, } from "./DatePicker.variants";
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/modules/divider/Divider.variants.d.ts

@@ -1,6 +1,6 @@
 /**
  * Divider's style resolution — same split as `Card.variants` / `Button.variants`:
- *  - STRUCTURE (the hairline's thickness on the cross axis) lives in the themed `dividerStructure`
+ *  - STRUCTURE (the StyleSheet.hairlineWidth's thickness on the cross axis) lives in the themed `dividerStructure`
  *    resolver, static per (brand, mode), registered once via `StyleSheet.create`.
  *  - COLOUR is resolved from the theme's ROLE colours by `resolveDividerColor`, never a raw ramp
  *    and never a hardcoded hex.
@@ -8,8 +8,8 @@
  * Free of React, so the colour-resolution test imports this directly (mocking only `react-native`'s
  * `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
-import type { RoleColors } from "../../theme";
-import type { Theme } from "../../theme";
+import type { RoleColors } from "../../theme/hooks";
+import type { Theme } from "../../theme/hooks";
 export type DividerOrientation = "horizontal" | "vertical";
 /**
  * Maps the divider onto the theme's role colours. `colors.border.default` — the decorative rung,
@@ -23,18 +23,18 @@ export type DividerOrientation = "horizontal" | "vertical";
  */
 export declare function resolveDividerColor(colors: RoleColors): string;
 /**
- * Structural styles only — the hairline's thickness on the theme's `borderWidths` scale, spanning
+ * Structural styles only — the StyleSheet.hairlineWidth's thickness on the theme's `borderWidths` scale, spanning
  * the full cross axis. No colour (resolved separately, applied inline over this), so this compiles
  * once per theme identity via the `WeakMap`-cached themed resolver and never rebuilds per render.
  */
 export declare const dividerStructure: import("../../core/style").ThemedVariantResolver<Theme, {
     orientation: {
         horizontal: {
-            height: 1;
+            height: number;
             width: "100%";
         };
         vertical: {
-            width: 1;
+            width: number;
             alignSelf: "stretch";
         };
     };

package/lib/typescript/modules/drawer/Drawer.d.ts

@@ -10,7 +10,8 @@
  * transition for the whole native surface and can't keep a custom-Animated backdrop opacity in
  * lockstep with a custom panel slide. `animationType` is therefore always `"none"` here; this module
  * owns the whole transition, so it can collapse to an instant snap under reduced motion (WCAG 2.3.3)
- * without ever showing a frozen half-animated frame.
+ * without ever showing a frozen half-animated frame. Every duration and easing comes from the global
+ * motion system (`core/motion`) — `slow`/`decelerate` entering, `normal`/`accelerate` leaving.
  *
  * Because RN's `<Modal>` only hides its children once native dismissal completes (or the component
  * unmounts) — the same fact Modal.tsx's own top comment documents — the sheet stays internally

package/lib/typescript/modules/drawer/Drawer.variants.d.ts

@@ -4,24 +4,15 @@
  *    resolvers below, static per (brand, mode), registered once via `StyleSheet.create`.
  *  - COLOUR is resolved from the theme's ROLE colours by `resolveDrawerPanelColors`, never a raw
  *    ramp and never a hardcoded hex.
- *  - The reduced-motion contract (WCAG 2.3.3) is `resolveDrawerAnimationDuration`, and the
- *    safe-area-less bottom-inset fallback is `resolveDrawerBottomInset` — both kept pure so they are
+ *  - TIMING is not here at all: duration, easing and the reduced-motion contract (WCAG 2.3.3) come
+ *    from the global motion system (`core/motion`), so retuning the library retunes this drawer.
+ *  - The safe-area-less bottom-inset fallback is `resolveDrawerBottomInset` — kept pure so it is
  *    unit-testable without rendering React Native.
  *
  * Free of React and of any `Modal`/`Pressable`/`Animated` import, so the tests import it directly
  * (mocking only `react-native`'s `StyleSheet`, as `core/style` does).
  */
-import type { RoleColors, Theme } from "../../theme";
-/** The slide-up + backdrop-fade duration in ms. A component design constant — not on the theme's
- *  numeric scale — same status `PRESS_FADE_MS` (Button) / `ANIMATION_MS` (Toast) have. */
-export declare const DRAWER_ANIMATION_MS = 260;
-/** WCAG 2.3.3 — the slide/fade collapses to an instant snap (never a frozen frame) when the OS has
- *  reduced motion on. Mirrors Modal's `resolveModalAnimationType`, pulled into its own resolver
- *  because Drawer drives the transition with `Animated.timing` (a duration), not RN Modal's
- *  `animationType` (a discrete enum) — Modal's own native transition can't also fade a separately
- *  Animated backdrop in lockstep with a custom slide, which is why this module never sets
- *  `animationType` to anything but `"none"` and does the whole transition itself. */
-export declare function resolveDrawerAnimationDuration(reducedMotion: boolean): number;
+import type { RoleColors, Theme } from "../../theme/hooks";
 /**
  * Static bottom-inset fallback. `react-native-safe-area-context` is listed as an optional peer in
  * `peerDependenciesMeta`, but — same finding `Toast`'s MODULE.md already recorded — it is not

package/lib/typescript/modules/empty-state/EmptyState.d.ts

@@ -5,10 +5,13 @@
  * composition (the same reasoning `AlertDialog` documents for its own footer buttons) — never a
  * hand-rolled `Pressable` that would duplicate Button's press/focus/disabled/hit-target wiring.
  *
- * No `accessibilityRole` of its own: like `Card`, this is a plain grouping container with no
- * interaction beyond the composed Button, so there is nothing here for assistive tech to announce
- * beyond its children — the title and description read as their own `Text` elements, in order,
- * and the icon (redundant with the title) is hidden from the accessibility tree entirely.
+ * No `accessibilityRole` on the container: like `Card`, this is a plain grouping container with no
+ * interaction beyond the composed Button. The title is the state's heading (`accessibilityRole=
+ * "header"` at level 2, WCAG 1.3.1 / 2.4.6), the description reads as its own `Text` after it, and the icon
+ * (redundant with the title) is hidden from the accessibility tree entirely.
+ *
+ * Appearing is itself the status message (WCAG 4.1.3): a screen swapping its content for this block
+ * moves no focus, so `useAnnounce` speaks the title + description once, on arrival and on change.
  */
 import type { IconName } from "../../core/icon";
 import type { LayoutStyle } from "../../core/style";
@@ -21,6 +24,8 @@ export interface EmptyStateProps {
     title: string;
     description?: string;
     action?: EmptyStateAction;
+    /** Expands to fill and centre in a flex parent (e.g. a list empty slot). */
+    fill?: boolean;
     /** Layout-only, outermost, applied exactly once as the LAST entry in the root style array. */
     style?: LayoutStyle;
     testID?: string;

package/lib/typescript/modules/empty-state/EmptyState.variants.d.ts

@@ -11,7 +11,7 @@
  * Free of React and lucide, so the WCAG test imports this directly (mocking only `react-native`'s
  * `StyleSheet`, as `core/style` and every sibling module's tests do).
  */
-import type { RoleColors, Theme } from "../../theme";
+import type { RoleColors, Theme } from "../../theme/hooks";
 /**
  * The icon glyph's rendered size, in dp. A component design constant — same status `Button`'s
  * `ICON_STROKE` / `BUTTON_SIZES.*.iconSize` have — not on the theme's numeric scale: EmptyState
@@ -33,6 +33,12 @@ export interface EmptyStateColors {
  * it inverts light↔dark for free and can never be an off-palette value an app invented.
  */
 export declare function resolveEmptyStateColors(colors: RoleColors): EmptyStateColors;
+/**
+ * What a screen reader hears when this state appears (WCAG 4.1.3). The description carries the
+ * recovery step ("Try a different search"), so it is announced with the title rather than left to a
+ * swipe the user has no reason to make.
+ */
+export declare function resolveEmptyStateAnnouncement(title: string, description: string | undefined): string;
 /**
  * Structural styles only — centring, padding, and the vertical rhythm between children. No
  * colours (those are resolved separately and applied inline over this) and no closed union to
@@ -40,4 +46,5 @@ export declare function resolveEmptyStateColors(colors: RoleColors): EmptyStateC
  * never rebuilds per render.
  */
 export declare const emptyStateStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
+export declare const emptyStateFillStructure: import("../../core/style").ThemedVariantResolver<Theme, import("../../core/style").VariantGroups<import("react-native").ViewStyle>, import("react-native").ViewStyle>;
 //# sourceMappingURL=EmptyState.variants.d.ts.map