@gnome-ui/react-native 1.11.0 → 1.13.0

package/README.md

@@ -294,6 +294,43 @@ announces the same thing, mirroring the web version's `aria-label` on its
 icon span. Unlike the web `Link`, RN has no tab concept, so `external` is
 purely presentational — `href` always opens the same way regardless.
 
+### LinkedGroup
+
+```tsx
+import { Button, LinkedGroup } from '@gnome-ui/react-native';
+
+<LinkedGroup>
+  <Button>Cut</Button>
+  <Button>Copy</Button>
+  <Button>Paste</Button>
+</LinkedGroup>
+```
+
+Renders children as a single visually-connected unit with no gap and
+merged borders — the canonical GNOME pattern for button groups and
+segmented inputs. Mirrors `@gnome-ui/react`'s `LinkedGroup`, itself
+mirroring the libadwaita `.linked` style class.
+
+The web version reaches every child's border-radius via a CSS `> *`
+universal child selector — RN has no equivalent way for a parent `View`
+to reach into an arbitrary child's own internally-computed styles.
+Reimagined as the same `cloneElement`-onto-children technique
+`Popover`/`Tooltip` already use on their own trigger: each child gets a
+computed corner-radius/negative-margin override merged onto whatever
+`style` it already has, generalizing the "zero the shared inner corners,
+keep `theme.radiusMd` on the outer ones, overlap by 1 dp to collapse the
+shared border" recipe `SplitButton` already proved for its own fixed
+two-piece connected border. This only works because every component in
+this package already merges a passed-in `style` prop last — the same
+assumption `Popover`'s own trigger-cloning already depends on, so any
+custom child passed to `LinkedGroup` needs to follow that same
+convention.
+
+The web CSS also raises a hovered/focused child's `z-index` so its own
+border isn't visually covered by the next sibling's overlapping edge —
+dropped here: RN is touch-first (no `:hover`), and no component in this
+package currently renders an escaping focus ring that overlap could clip.
+
 ### TextField
 
 ```tsx
@@ -2510,6 +2547,40 @@ panel-height positioning almost verbatim, and gives each option row a
 leading checkbox-square visual instead of `Dropdown`'s single trailing
 checkmark.
 
+### NavigationSplitView
+
+```tsx
+import { NavigationSplitView } from '@gnome-ui/react-native';
+
+const [showContent, setShowContent] = useState(false);
+
+<NavigationSplitView
+  showContent={showContent}
+  sidebar={<MailList onSelect={() => setShowContent(true)} />}
+  content={<MailDetail onBack={() => setShowContent(false)} />}
+/>;
+```
+
+Two-pane sidebar + content layout following the Adwaita
+`AdwNavigationSplitView` pattern — mirrors `@gnome-ui/react`'s
+`NavigationSplitView`. On wide screens (`useBreakpoint().isNarrow ===
+false`, > 400 dp) both panes render side by side, separated by a
+`Separator`. On narrow screens only one pane shows at a time; `showContent`
+switches between the sidebar list and the detail view.
+
+The web version's `clamp(min, fraction * 100%, max)` sidebar width has no
+RN equivalent, so the container measures its own width via `onLayout` and
+the same clamp is computed in JS. Narrow-mode pane switching is animated
+(`translateX`) rather than an instant `display: 'none'` swap like
+`TabPanel` — both panes stay laid out and absolutely positioned, sliding
+via one shared `Animated.Value`, since RN `transform` has no
+percentage-of-self units to use a bare `-100%`/`100%` the way the web CSS
+does. The web's `inert` attribute (removes the hidden pane from the a11y
+tree and tab order while it stays mounted off-screen) has no single RN
+equivalent — reproduced with `accessibilityElementsHidden` +
+`importantForAccessibility="no-hide-descendants"` plus `pointerEvents="none"`
+so the off-screen pane can't intercept touches meant for the visible one.
+
 ### FilterableMultiSelectDropdown
 
 ```tsx
@@ -2589,6 +2660,35 @@ two independent `accessibilityRole="adjustable"` elements (one per thumb),
 the same VoiceOver/TalkBack increment/decrement analog `Slider` already
 established.
 
+### RatingStars
+
+```tsx
+import { RatingStars } from '@gnome-ui/react-native';
+
+// Read-only — omit onChange
+<RatingStars value={4.2} accessibilityLabel="Average rating: 4.2 out of 5" />
+
+// Interactive — pass onChange
+<RatingStars value={rating} onChange={setRating} />
+```
+
+Star rating display and input — mirrors `@gnome-ui/react`'s `RatingStars`.
+Renders `role="radiogroup"` of `role="radio"` stars when `onChange` is
+provided, or a static `role="img"` when it isn't (e.g. showing an
+average/read-only rating); passing `disabled` always falls back to the
+read-only display even with `onChange` provided. The web version's
+`radiogroup` layer also owns an `onKeyDown` handler for arrow-key
+roving-tabindex navigation and a mouse-hover preview that doesn't commit
+until clicked — neither has a touch counterpart, so both drop, the same
+standing convention `ToggleGroup` already established for this package.
+What's left, tapping a star to commit that rating, is a strict subset of
+the web interaction rather than an approximation of it. Each star's fill
+uses `tintColor={theme.warningBgColor}` rather than `Icon`'s fixed
+`color="yellow"` — the source CSS reads `var(--gnome-warning-bg-color)`
+directly with no `color-mix()` darkening step, so the semantic warning
+token (already tracking dark mode and every contrast level) is the exact
+match, not an approximation through the fixed palette.
+
 ### StatusBadge
 
 ```tsx
@@ -2905,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';