@gnome-ui/react-native 1.12.0 → 1.13.0

package/README.md

@@ -3005,6 +3005,216 @@ purely so the control can brighten on hover, and touch has no hover.
 as `BottomTabBar`'s `bottomInset` — this package takes no dependency on
 `react-native-safe-area-context` itself.
 
+### Calendar
+
+```tsx
+import { Calendar } from '@gnome-ui/react-native';
+
+const [value, setValue] = useState<Date | null>(null);
+
+<Calendar value={value} onChange={setValue} />
+
+<Calendar
+  min={new Date(2024, 0, 1)}
+  max={new Date(2024, 11, 31)}
+  showWeekNumbers
+  weekStartsOn={0}
+/>
+```
+
+Month-grid date display — mirrors `GtkCalendar` and `@gnome-ui/react`'s own
+`Calendar`, ported from its `Calendar`+`CalendarBase`+`calendarUtils.ts`
+split. `calendarUtils.ts`'s pure date-math helpers port verbatim (zero DOM
+dependency on the web side already), the same `fileType.ts`/
+`coachMarkUtils.ts` precedent for dependency-free logic not worth a shared
+package.
+
+**The web version's entire keyboard layer drops here** — roving tabindex,
+arrow keys, PageUp/Down, Home/End, Enter/Space are all gone, replaced by
+plain tap-to-select on every day/month/year cell. Unlike `Slider`'s 1D
+`accessibilityRole="adjustable"` fallback, a full 2D date grid has no
+screen-reader analog to page through, so tap-to-select is the strict touch
+subset of the web interaction — the same trade-off `RatingStars`/
+`ToggleGroup`/`ColorPicker` already made. The heading label still cycles
+day grid → month grid → year grid on tap, exactly as on the web, so a
+distant year is two taps away rather than many pages of month navigation.
+
+`role="grid"`/`"row"` port 1:1 from RN's web-aligned `Role` union;
+`"gridcell"` isn't in that union, so day/month/year cells fall back to
+`"cell"` — the same kind of substitution `BoxedList` (`"list"`) and
+`ComboRow` (`"listbox"` → `"list"`) already made. The grid and its rows
+deliberately skip `accessible`, the `ToggleGroup`-corrected pattern: with
+many independently-focusable day cells inside, setting it would collapse
+the whole month into one VoiceOver stop. Day-name and week-number headers
+hold no interactive children, so they do set `accessible` to be announced
+as a single unit.
+
+`visibleMonths` (side-by-side month panels) and `autoFocus`
+(keyboard-focus-on-mount) are dropped outright, not merely unimplemented —
+both are desktop/keyboard concerns with no honest phone-width or
+no-keyboard counterpart. `locale` is dropped too, in favor of the app-wide
+locale `GnomeProvider` already exposes through `useDateTimeFormatter` —
+`Calendar` is the first component in this package to seriously exercise
+that hook, and every `Intl.DateTimeFormatOptions` object it passes is
+hoisted to module scope so the hook's own `useMemo`-over-`options` identity
+check actually holds across renders. Day and drill-down cells are equal-
+width flex rows (7 columns for days, matching `getCalendarWeeks`'s fixed
+6-row output; 4 columns for the 12-cell month/year grids) rather than a
+CSS Grid port, since Yoga has no grid layout at all.
+
+No `CalendarBase` split was extracted ahead of need — it was pulled out of
+this component's grid/navigation logic once `CalendarRange` actually
+shipped and needed it (see below), not carried as unused abstraction before
+that. The extraction changed no observable behavior: `Calendar`'s full
+pre-existing test suite passed unmodified against the refactor.
+
+### CalendarRange
+
+```tsx
+import { CalendarRange, type DateRange } from '@gnome-ui/react-native';
+
+const [range, setRange] = useState<DateRange | null>(null);
+
+<CalendarRange value={range} onChange={setRange} />
+
+<CalendarRange minRange={2} maxRange={5} value={range} onChange={setRange} />
+```
+
+Start/end date-range selection on the same grid engine as `Calendar` —
+month/year drill-down, `min`/`max`, week numbers — via `CalendarBase`, the
+shared engine `Calendar` extracted once this component actually needed it
+rather than adding the split ahead of need.
+
+The first tap anchors the range; the second commits it, so `onChange` only
+ever fires with **both** ends filled in. Tapping backwards is fine — the
+pair is ordered before it's emitted.
+
+**No live drag-preview band, unlike the web version.** The web
+`CalendarRange` grows the band under the mouse/keyboard focus between the
+two clicks; RN has no hover, and this package's whole keyboard layer is
+already dropped (see `Calendar`'s own doc comment above), so there's no
+signal to preview against. Rather than reach for a `PanResponder` drag
+gesture — a materially bigger feature the web version doesn't even have,
+since it's mouse-hover, not drag — the anchor day just shows as a normal
+selected day until the second tap lands and the full band appears at once,
+the same strict-touch-subset trade-off `RatingStars`/`ToggleGroup`/
+`Calendar` itself already made for other dropped hover/keyboard affordances.
+
+The range band has no CSS `::before`/pseudo-element or `color-mix()` to
+lean on in RN — it's an absolutely-positioned `View` behind each day's
+button, bleeding half the cell's own padding into its neighbor via a
+negative inset (the JS-math equivalent of the web CSS's
+`inset-inline: calc(gap/-2)` bleed) so consecutive in-range days read as one
+continuous stripe under the round day buttons; end caps skip the bleed on
+their outer side and round that corner instead, so a single-day range
+composes into a full pill from the same two conditionals rather than a
+separate case. Tint alpha uses the `#RRGGBBAA` hex-suffix substitution
+`Blockquote`/`Chip` already established for the web's `color-mix()`.
+
+### DatePicker
+
+```tsx
+import { DatePicker } from '@gnome-ui/react-native';
+
+const [value, setValue] = useState<Date | null>(null);
+
+<DatePicker label="Date" value={value} onChange={setValue} />
+
+<DatePicker
+  label="Meeting time"
+  showTime
+  hourCycle={12}
+  value={value}
+  onChange={setValue}
+/>
+```
+
+A `Popover`-anchored `Calendar` behind a text-entry-styled trigger, mirroring
+the `GtkCalendar` + `GtkPopover` composition GNOME apps use for date entry.
+Composed entirely from this package's own already-shipped pieces —
+`Popover` (Tier 5) and `Calendar` (Tier 20) — rather than reinventing any
+position-computation code, per this package's standing pitfall about not
+re-deriving `Popover`/`Dropdown`'s already-shipped trigger-rect + panel-size
+positioning.
+
+The trigger is a plain themed `Pressable` styled like `Dropdown`'s own
+text-entry-look trigger (bordered row, dimmed placeholder, trailing
+`XOfficeCalendar` icon) rather than a literal `TextField` composition — a
+`TextField` wraps a real editable `TextInput`, which a date-picker trigger
+never wants (it opens a panel, it doesn't accept typed text).
+`locale`/`formatOptions` are dropped in favor of `GnomeProvider`'s app-wide
+`useDateTimeFormatter`, the same convention `Calendar` itself just
+established: reading the hook's own `{...dateTimeFormat, ...options}` merge
+confirmed it already expresses `dateStyle`+`timeStyle`+`hourCycle` together,
+so three fixed, module-scope option objects (date-only, 24-hour, 12-hour)
+cover every `showTime`/`hourCycle` combination without needing an arbitrary
+caller-supplied `formatOptions` escape hatch. The web version's entire
+keyboard layer drops (no `ArrowDown`-opens-the-popover, no `Enter`/`Space`
+on the trigger), and `Calendar`'s own already-dropped `autoFocus` prop is
+correctly never wired here either.
+
+Picking a day keeps the popover open when `showTime` is on — only the Done
+button closes it, so the time columns stay reachable — and closes it
+immediately otherwise, ported as plain state logic from the web version's
+`handleSelect`, no web-only API involved.
+
+**`showTime` brought its own dependency.** The web `TimePicker`'s
+`TimeFields`/`timeUtils.ts` (hour/minute/AM-PM `SpinButton` columns plus
+pure 12/24-hour math) first ported into `DatePicker`'s own folder as an
+internal, non-exported module, the same "shared piece built by its first
+real consumer" precedent `IconButton` set for `Drawer`'s `rail` — since
+relocated to `TimePicker`'s own folder now that it's shipped (see below),
+with `DatePicker` importing it from there instead of carrying its own copy.
+`timeUtils.ts` ports verbatim (zero DOM dependency already), and
+`TimeFields` rebuilds on this
+package's own `SpinButton` (Tier 5) — its `wrap` boolean and
+`format: (n: number) => string` callback already cover the AM/PM column's
+"numeric spinner whose `format` maps 0/1 to text" trick with no new prop
+needed, confirmed by reading `SpinButton.tsx` before wiring it up.
+
+`SpinButton` has a fixed per-column minimum width (two 36 dp buttons plus a
+56 dp value `Text`, ~130 dp), so a 12-hour row of three columns
+(hours/minutes/AM-PM) can approach or exceed a narrow phone's screen width
+even after widening the popover panel past its default 320 dp cap —
+`Popover`'s own `panelStyle` prop (a `StyleProp<ViewStyle>`, not a
+`panelClassName` string the way the web version's CSS-module trigger works;
+confirmed by reading `Popover.tsx` first) raises the cap to 420 dp for
+`showTime`, and the footer row itself is `flexWrap: 'wrap'` so the Done
+button drops to its own line instead of clipping or forcing horizontal
+scroll.
+
+### TimePicker
+
+```tsx
+import { TimePicker } from '@gnome-ui/react-native';
+
+const [value, setValue] = useState<{ hours: number; minutes: number } | null>(null);
+
+<TimePicker label="Time" value={value} onChange={setValue} />
+
+<TimePicker label="Reminder" hourCycle={12} value={value} onChange={setValue} />
+```
+
+Paired hour/minute `SpinButton` columns behind the same bordered/dimmed-
+placeholder/trailing-icon trigger style `DatePicker` established — mirrors
+the `GtkSpinButton` + `GtkPopover` composition GNOME apps use for time
+entry, with 12- and 24-hour support.
+
+`TimeFields`/`timeUtils.ts` — the hour/minute/AM-PM `SpinButton` columns and
+their pure 12/24-hour math — live here now, relocated out of `DatePicker`'s
+folder once this component gave them a real public home; `DatePicker`'s
+`showTime` footer imports them from here instead of carrying its own copy.
+
+Unlike `DatePicker`'s `showTime` footer, there's no Done button: with no
+calendar-day tap to disambiguate from a close, each `SpinButton` column
+commits live via `onChange`, and the popover only closes by tapping outside
+or the trigger again — the same convention `Dropdown` already established.
+Formatting uses `hour`/`minute` `Intl.DateTimeFormat` component options
+(`{hour: '2-digit', minute: '2-digit', hourCycle}`) rather than `DatePicker`'s
+`dateStyle`+`timeStyle` pairing, since there's no date to render — ported
+straight from the web version's own formatter call, still routed through
+`GnomeProvider`'s `useDateTimeFormatter` for locale consistency.
+
 ## Installation
 
 ```bash

package/dist/components/Calendar/Calendar.d.ts

@@ -0,0 +1,95 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { CalendarView } from './CalendarBase';
+import { WeekStart } from './calendarUtils';
+export type { CalendarView } from './CalendarBase';
+export interface CalendarProps {
+    /** Controlled selected date. Pass `null` for "no selection". */
+    value?: Date | null;
+    /** Initial selected date when uncontrolled. Defaults to `null`. */
+    defaultValue?: Date | null;
+    /** Called when the user taps a day. */
+    onChange?: (date: Date) => void;
+    /** Controlled displayed month (any date within the desired month). */
+    month?: Date;
+    /**
+     * Initial displayed month when uncontrolled. Defaults to the selected
+     * date's month, falling back to the current month.
+     */
+    defaultMonth?: Date;
+    /** Called when the displayed month changes via navigation. */
+    onMonthChange?: (month: Date) => void;
+    /** Earliest selectable date (inclusive). Earlier days are disabled. */
+    min?: Date;
+    /** Latest selectable date (inclusive). Later days are disabled. */
+    max?: Date;
+    /**
+     * First day of the week: `0` (Sunday) … `6` (Saturday). Defaults to `1`
+     * (Monday) — the GNOME default across most locales.
+     */
+    weekStartsOn?: WeekStart;
+    /** Show the month/year heading with prev/next navigation. Mirrors `GtkCalendar:show-heading`. Defaults to `true`. */
+    showHeading?: boolean;
+    /** Show the abbreviated day-name column headers. Mirrors `GtkCalendar:show-day-names`. Defaults to `true`. */
+    showDayNames?: boolean;
+    /** Show an ISO week-number column. Mirrors `GtkCalendar:show-week-numbers`. Defaults to `false`. */
+    showWeekNumbers?: boolean;
+    /**
+     * Turn the heading label into a button that drills down day grid → month
+     * grid → year grid, the way modern date pickers let you jump years
+     * without paging month by month. Requires `showHeading`. Defaults to `true`.
+     */
+    showViewSwitcher?: boolean;
+    /** Grid shown on mount: `'days'`, `'months'` or `'years'`. Defaults to `'days'`. */
+    defaultView?: CalendarView;
+    /** Called when the drill-down view changes. */
+    onViewChange?: (view: CalendarView) => void;
+    /** Accessible label for the grid. Defaults to the current heading label. */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Month-grid date display — mirrors `GtkCalendar` and `@gnome-ui/react`'s own
+ * `Calendar`. Usable standalone (settings, forms) or as the panel inside
+ * `DatePicker`.
+ *
+ * The heading label drills down day grid → month grid → year grid so a
+ * distant year is two taps away instead of many pages, exactly as on the web.
+ * Leading/trailing days from adjacent months are shown dimmed and remain
+ * tappable — tapping one navigates to that month, matching `GtkCalendar`.
+ *
+ * A thin single-day `CalendarSelectionModel` over `CalendarBase` — the
+ * shared grid engine (month window, heading, day/month/year drill-down)
+ * extracted once `CalendarRange` actually needed it, per the note this
+ * component left when it first shipped rather than adding the split ahead
+ * of need.
+ *
+ * **The web version's entire keyboard layer drops here** (roving tabindex,
+ * arrow keys, PageUp/Down, Home/End, Enter/Space) — this package is
+ * touch-first, and unlike `Slider`'s 1D `accessibilityRole="adjustable"`
+ * escape hatch, there is no screen-reader analog for paging a full 2D date
+ * grid. Tap-to-select on each cell is the strict touch subset of the web
+ * interaction, the same trade-off already made for `RatingStars`/
+ * `ToggleGroup`/`ColorPicker`. `role="grid"`/`"row"` port 1:1 from RN's
+ * web-aligned `Role` union; `"gridcell"` doesn't exist in that union, so
+ * cells fall back to `"cell"`, the same kind of substitution `BoxedList`
+ * (`"list"`) and `ComboRow` (`"listbox"` → `"list"`) already made. The grid
+ * and its rows deliberately skip `accessible` — the `ToggleGroup`-corrected
+ * pattern: setting it on a container with many independently-focusable
+ * children (each day) would collapse the whole month into one VoiceOver
+ * stop. Column/row *headers* (day names, week numbers) hold no interactive
+ * children, so they do set `accessible` to be announced as a single unit.
+ *
+ * `visibleMonths` (side-by-side month panels) and `autoFocus`
+ * (keyboard-focus-on-mount) are dropped, not merely unimplemented: both are
+ * desktop/keyboard concerns with no honest RN counterpart — a phone screen
+ * has no room for two month panels side by side, and there is no keyboard to
+ * focus. `locale` is dropped too, in favor of the app-wide locale
+ * `GnomeProvider` already exposes through `useDateTimeFormatter`.
+ *
+ * For start/end selection use `CalendarRange`, which shares this same grid
+ * engine via `CalendarBase`.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/gtk/gtk4/class.Calendar.html
+ */
+export declare const Calendar: ({ value: controlledValue, defaultValue, onChange, min, max, ...props }: CalendarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/Calendar/CalendarBase.d.ts

@@ -0,0 +1,83 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+import { WeekStart } from './calendarUtils';
+/** Which grid the calendar is currently showing. */
+export type CalendarView = 'days' | 'months' | 'years';
+/** How one day cell should be painted, as decided by the selection model. */
+export interface CalendarDayState {
+    /** Endpoint of the selection — filled accent pill. */
+    selected?: boolean;
+    /** Left edge of a range. */
+    rangeStart?: boolean;
+    /** Right edge of a range. */
+    rangeEnd?: boolean;
+    /** Strictly between the two ends of a range. */
+    inRange?: boolean;
+    /** The range being painted is a preview, not a committed selection. */
+    preview?: boolean;
+    /** Appended to the day's accessible label, e.g. `', start of range'`. */
+    labelSuffix?: string;
+}
+/**
+ * Everything `CalendarBase` needs to know about *what is selected*, so the
+ * grid engine (month/year navigation, day/month/year drill-down) stays free
+ * of selection semantics and can drive both `Calendar` and `CalendarRange`.
+ *
+ * Trimmed from `@gnome-ui/react`'s own `CalendarSelectionModel`: no
+ * `seedFocus`/`hoverDay`/`focusDayChange`/`escape` — those exist only to
+ * drive the web version's keyboard roving-tabindex and mouse-hover range
+ * preview, and this package drops the entire keyboard layer the same way
+ * `Calendar` itself already does (no honest RN touch equivalent). Without a
+ * hover signal, a range picker's "preview" is just its own anchor day until
+ * the second tap commits — `CalendarRange` below relies on that rather than
+ * tracking a separate preview day.
+ */
+export interface CalendarSelectionModel {
+    dayState: (date: Date) => CalendarDayState;
+    isDayDisabled?: (date: Date) => boolean;
+    activateDay: (date: Date) => void;
+    isMonthSelected?: (month: Date) => boolean;
+    isYearSelected?: (year: number) => boolean;
+}
+export interface CalendarBaseProps {
+    selection: CalendarSelectionModel;
+    /** Controlled displayed month (any date within the desired month). */
+    month?: Date;
+    /**
+     * Initial displayed month when uncontrolled. Defaults to `fallbackMonth`,
+     * falling back to the current month.
+     */
+    defaultMonth?: Date;
+    /** Called when the displayed month changes via navigation. */
+    onMonthChange?: (month: Date) => void;
+    /** Seeds the displayed month when neither `month` nor `defaultMonth` is given. */
+    fallbackMonth?: Date | null;
+    /** Earliest selectable date (inclusive). Also disables out-of-range months/years. */
+    min?: Date;
+    /** Latest selectable date (inclusive). Also disables out-of-range months/years. */
+    max?: Date;
+    weekStartsOn?: WeekStart;
+    showHeading?: boolean;
+    showDayNames?: boolean;
+    showWeekNumbers?: boolean;
+    showViewSwitcher?: boolean;
+    defaultView?: CalendarView;
+    onViewChange?: (view: CalendarView) => void;
+    accessibilityLabel?: string;
+    /** Rendered inside the root, after the grid — status live regions, presets. */
+    footer?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * The shared calendar grid engine: month window, heading navigation, and the
+ * day / month / year drill-down grids. It owns *navigation*; `selection`
+ * owns *what is selected* — extracted from `Calendar` once `CalendarRange`
+ * actually needed the same engine, per the standing note `Calendar` left
+ * when it shipped rather than adding this split ahead of need.
+ *
+ * Not exported from the package barrel — `Calendar` and `CalendarRange` are
+ * its public faces, the same "internal engine, public wrapper" shape
+ * `TimeFields`/`TimePicker` already established.
+ */
+export declare const CalendarBase: ({ selection, month: controlledMonth, defaultMonth, onMonthChange, fallbackMonth, min, max, weekStartsOn, showHeading, showDayNames, showWeekNumbers, showViewSwitcher, defaultView, onViewChange, accessibilityLabel, footer, style, testID, }: CalendarBaseProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/Calendar/calendarUtils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure date helpers for `Calendar`. Duplicated verbatim from
+ * `@gnome-ui/react`'s `calendarUtils.ts` rather than imported cross-package
+ * — the same `fileType.ts`/`coachMarkUtils.ts` precedent for dependency-free
+ * logic that isn't worth a shared package for one file's worth of code. Zero
+ * DOM dependency on the web side already, so nothing here changes for RN.
+ *
+ * Every helper operates on the local time zone — a "day" is a wall-clock
+ * day, never a UTC instant.
+ *
+ * `fromISODateKey` doesn't make the cut: the web version uses it to decode
+ * `data-date` attributes from a single delegated `onMouseOver` listener (a
+ * hover-preview feature with no touch equivalent), and nothing else in this
+ * package needs to parse an ISO key back into a `Date`. `toISODateKey` stays
+ * — every day/week still wants a stable string for React `key`s and test
+ * IDs.
+ */
+export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Midnight (local) of the given date, as a fresh `Date`. */
+export declare const startOfDay: (date: Date) => Date;
+/** First day of the month containing `date`, at local midnight. */
+export declare const startOfMonth: (date: Date) => Date;
+/** `true` when both dates fall on the same calendar day. */
+export declare const isSameDay: (a: Date, b: Date) => boolean;
+/** `true` when both dates fall in the same calendar month. */
+export declare const isSameMonth: (a: Date, b: Date) => boolean;
+/** `date` shifted by `amount` days (may be negative). */
+export declare const addDays: (date: Date, amount: number) => Date;
+/**
+ * The date `year-month-day`, with the day clamped to the last valid day of that
+ * month. Used whenever a month or year jump must keep the day-of-month intact.
+ */
+export declare const clampDayToMonth: (year: number, month: number, day: number) => Date;
+/**
+ * `date` shifted by `amount` months, keeping the day-of-month where possible
+ * and clamping to the last valid day otherwise (e.g. Jan 31 + 1 month → Feb 28).
+ */
+export declare const addMonths: (date: Date, amount: number) => Date;
+/**
+ * `date` shifted by `amount` years, clamping the day-of-month where the target
+ * year is shorter (e.g. 29 Feb 2028 - 1 year → 28 Feb 2027).
+ */
+export declare const addYears: (date: Date, amount: number) => Date;
+/** How many years one page of the year view shows. */
+export declare const YEARS_PER_PAGE = 12;
+/** First year of the fixed-size page of years containing `year`. */
+export declare const startOfYearPage: (year: number) => number;
+/** Distance in days from the week's start to `date`, given the first weekday. */
+export declare const weekdayOffset: (date: Date, weekStartsOn: WeekStart) => number;
+/**
+ * The six-week grid (always 6 rows × 7 days) that the web `Calendar` renders
+ * for a month — leading/trailing days belong to the adjacent months. A fixed
+ * row count avoids the layout jump months of differing length would
+ * otherwise cause.
+ */
+export declare const getCalendarWeeks: (month: Date, weekStartsOn: WeekStart) => Date[][];
+/** ISO-8601 week number (weeks start Monday; week 1 contains the first Thursday). */
+export declare const isoWeekNumber: (date: Date) => number;
+/** `true` when `date` is outside the inclusive `[min, max]` range. */
+export declare const isOutOfRange: (date: Date, min?: Date, max?: Date) => boolean;
+/** `true` when every day of `date`'s month falls outside the inclusive `[min, max]` range. */
+export declare const isMonthOutOfRange: (date: Date, min?: Date, max?: Date) => boolean;
+/** `true` when every day of `date`'s year falls outside the inclusive `[min, max]` range. */
+export declare const isYearOutOfRange: (date: Date, min?: Date, max?: Date) => boolean;
+/** A stable `YYYY-MM-DD` key for a date, used for React `key`s and test IDs. */
+export declare const toISODateKey: (date: Date) => string;

package/dist/components/Calendar/index.d.ts

@@ -0,0 +1,2 @@
+export type { CalendarProps, CalendarView } from './Calendar';
+export { Calendar } from './Calendar';

package/dist/components/CalendarRange/CalendarRange.d.ts

@@ -0,0 +1,75 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { CalendarView } from '../Calendar/CalendarBase';
+import { WeekStart } from '../Calendar/calendarUtils';
+import { DateRange, SelectedDateRange } from './rangeUtils';
+export type { DateRange, SelectedDateRange } from './rangeUtils';
+export interface CalendarRangeProps {
+    /** Controlled range. Either end may be `null` while nothing is chosen. */
+    value?: DateRange | null;
+    /** Initial range when uncontrolled. Defaults to an empty range. */
+    defaultValue?: DateRange | null;
+    /**
+     * Called with the finished range — **only once both ends have a value**.
+     * The first tap merely anchors the range, so this never fires with a half
+     * selection.
+     */
+    onChange?: (range: SelectedDateRange) => void;
+    /** Called with the anchor day when the first of the two taps lands. */
+    onRangeStart?: (date: Date) => void;
+    /** Controlled displayed month (any date within the desired month). */
+    month?: Date;
+    /**
+     * Initial displayed month when uncontrolled. Defaults to the range's
+     * start month, falling back to the current month.
+     */
+    defaultMonth?: Date;
+    /** Called when the displayed month changes via navigation. */
+    onMonthChange?: (month: Date) => void;
+    /** Earliest selectable date (inclusive). */
+    min?: Date;
+    /** Latest selectable date (inclusive). */
+    max?: Date;
+    /** Shortest range the user may commit, in days (both ends counted). Defaults to `1`. */
+    minRange?: number;
+    /** Longest range the user may commit, in days (both ends counted). Unlimited by default. */
+    maxRange?: number;
+    weekStartsOn?: WeekStart;
+    showHeading?: boolean;
+    showDayNames?: boolean;
+    showWeekNumbers?: boolean;
+    showViewSwitcher?: boolean;
+    defaultView?: CalendarView;
+    onViewChange?: (view: CalendarView) => void;
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Start/end date-range selection driving the same grid engine as `Calendar`
+ * — month/year drill-down, `min`/`max`, week numbers — via `CalendarBase`,
+ * the shared engine `Calendar` extracted once this component actually
+ * needed it.
+ *
+ * The first tap anchors the range; the second commits it. `onChange`
+ * therefore only ever fires with **both** ends filled in. Tapping backwards
+ * is fine — the pair is ordered before it is emitted.
+ *
+ * **No live drag-preview band, unlike the web version.** The web
+ * `CalendarRange` grows the band under the mouse/keyboard focus between the
+ * two clicks; RN has no hover and this package's whole keyboard layer is
+ * already dropped (see `Calendar`'s own doc comment), so there is no signal
+ * to preview against. The anchor day simply shows as a normal selected day
+ * until the second tap lands and the full band appears at once — the
+ * touch-first subset of the same interaction, the same kind of trade-off
+ * `RatingStars`/`ToggleGroup`/`Calendar` itself already made for dropped
+ * hover/keyboard affordances. `CalendarBase`'s `CalendarSelectionModel` was
+ * trimmed to match — no `hoverDay`/`focusDayChange` to wire up here.
+ *
+ * `visibleMonths` (side-by-side month panels, the usual desktop range-picker
+ * shape) has no phone-width equivalent — dropped, the same `Calendar`
+ * `visibleMonths` precedent. `locale` is dropped too, in favor of
+ * `GnomeProvider`'s app-wide `useDateTimeFormatter`.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/gtk/gtk4/class.Calendar.html
+ */
+export declare const CalendarRange: ({ value: controlledValue, defaultValue, onChange, onRangeStart, min, max, minRange, maxRange, ...props }: CalendarRangeProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/CalendarRange/index.d.ts

@@ -0,0 +1,2 @@
+export type { CalendarRangeProps, DateRange, SelectedDateRange } from './CalendarRange';
+export { CalendarRange } from './CalendarRange';

package/dist/components/CalendarRange/rangeUtils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pure helpers for `CalendarRange`. Kept dependency-free and side-effect-free,
+ * mirroring the `calendarUtils.ts` split `Calendar` already uses. Ported
+ * verbatim from `@gnome-ui/react`'s own `rangeUtils.ts` — zero DOM
+ * dependency there already.
+ */
+/** A range under construction — either end may still be missing. */
+export interface DateRange {
+    start: Date | null;
+    end: Date | null;
+}
+/** A finished range: both ends have a value. The only shape `onChange` emits. */
+export interface SelectedDateRange {
+    start: Date;
+    end: Date;
+}
+/** The empty range, as a fresh object so callers never share one. */
+export declare const emptyRange: () => DateRange;
+/** Both dates as a range, oldest first — so picking backwards still works. */
+export declare const orderRange: (a: Date, b: Date) => SelectedDateRange;
+/**
+ * Length of the range in days, counting both ends (so a single day is `1`).
+ * Rounded, because a DST change makes a "day" 23 or 25 hours long.
+ */
+export declare const rangeLength: (range: SelectedDateRange) => number;
+/** `true` when `date` falls on or between both ends. */
+export declare const isWithinRange: (date: Date, range: SelectedDateRange) => boolean;
+/** `true` when the range satisfies the `minRange`/`maxRange` day limits. */
+export declare const isRangeAllowed: (range: SelectedDateRange, minRange?: number, maxRange?: number) => boolean;
+/** `true` when both ends have a value — the condition for emitting a change. */
+export declare const isRangeComplete: (range: DateRange) => range is SelectedDateRange;

package/dist/components/DatePicker/DatePicker.d.ts

@@ -0,0 +1,75 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { WeekStart } from '../Calendar/calendarUtils';
+import { PopoverPlacement } from '../Popover';
+export interface DatePickerProps {
+    /** Controlled selected date. Pass `null` for "no selection". */
+    value?: Date | null;
+    /** Initial selected date when uncontrolled. Defaults to `null`. */
+    defaultValue?: Date | null;
+    /** Called when the user picks a date (or, with `showTime`, edits a time column). */
+    onChange?: (date: Date) => void;
+    /** Earliest selectable date (inclusive). */
+    min?: Date;
+    /** Latest selectable date (inclusive). */
+    max?: Date;
+    /** First day of the week: `0` (Sunday) … `6` (Saturday). Defaults to `1` (Monday). */
+    weekStartsOn?: WeekStart;
+    /**
+     * Add hour/minute columns under the calendar, making the emitted `Date` a
+     * point in time rather than a civil date. Picking a day then keeps the
+     * popover open — the selection is only finished by the Done button.
+     */
+    showTime?: boolean;
+    /** 12- or 24-hour columns when `showTime` is on. Defaults to `24`. */
+    hourCycle?: 12 | 24;
+    /** Minute increment for the time spinner. Defaults to `1`. */
+    minuteStep?: number;
+    /** Label on the button that closes a `showTime` popover. Defaults to `'Done'`. */
+    doneLabel?: string;
+    /** Text shown in the trigger while no date is selected. */
+    placeholder?: string;
+    /** Visible label rendered above the trigger. */
+    label?: string;
+    /** Accessible name for the trigger when no visible `label` is provided. */
+    accessibilityLabel?: string;
+    /** Show an ISO week-number column in the calendar. */
+    showWeekNumbers?: boolean;
+    /** Disable the control. */
+    disabled?: boolean;
+    /** Preferred popover placement relative to the trigger. Defaults to `'bottom'`. */
+    placement?: PopoverPlacement;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * A `Popover`-anchored `Calendar` behind a text-entry-styled trigger —
+ * mirrors the `GtkCalendar` + `GtkPopover` composition GNOME apps use for
+ * date entry.
+ *
+ * Rebuilt on this package's own already-shipped `Popover` (Tier 5) and
+ * `Calendar` (Tier 20) rather than reinventing either: the trigger is a
+ * `Pressable` styled like `Dropdown`'s own text-entry-look trigger (same
+ * bordered row, dimmed placeholder, trailing icon), and the panel is
+ * `Calendar` plus an optional `showTime` footer, composed exactly the way
+ * `Popover`'s own doc comment expects a rich-content consumer to use it —
+ * no new position-computation code, per this package's standing pitfall
+ * about not reinventing `Popover`/`Dropdown`'s already-shipped trigger-rect
+ * + panel-size positioning.
+ *
+ * **The web version's entire keyboard layer drops** — no `ArrowDown`-opens,
+ * no `Enter`/`Space` on the trigger — the same touch-first convention this
+ * whole package follows; `Calendar`'s own `autoFocus` prop was already
+ * dropped when `Calendar` was ported (no keyboard focus concept without a
+ * keyboard), so it isn't wired here either. `locale`/`formatOptions` are
+ * dropped in favor of `GnomeProvider`'s app-wide `useDateTimeFormatter`,
+ * following `Calendar`'s own just-shipped convention rather than
+ * reintroducing a locale prop pair.
+ *
+ * Picking a day keeps the popover open when `showTime` is on (only the Done
+ * button closes it, so the time columns stay reachable) and closes it
+ * immediately otherwise — ported as-is from the web version's
+ * `handleSelect`, plain state logic with no web-only API involved.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/gtk/gtk4/class.Calendar.html
+ */
+export declare const DatePicker: ({ value: controlledValue, defaultValue, onChange, min, max, weekStartsOn, showTime, hourCycle, minuteStep, doneLabel, placeholder, label, accessibilityLabel, showWeekNumbers, disabled, placement, style, testID, }: DatePickerProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/DatePicker/index.d.ts

@@ -0,0 +1,2 @@
+export type { DatePickerProps } from './DatePicker';
+export { DatePicker } from './DatePicker';