@gnome-ui/react-native 1.11.0 → 1.13.0

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';

package/dist/components/LinkedGroup/LinkedGroup.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+import { StyleProp, View, ViewStyle } from 'react-native';
+export interface LinkedGroupProps {
+    /**
+     * Each child must accept and merge a `style` prop the way every
+     * `@gnome-ui/react-native` component already does (`style` last in its
+     * own internal style array) — see the component doc for why.
+     */
+    children: ReactNode;
+    /** Stack children vertically instead of horizontally. */
+    vertical?: boolean;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * 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 instead 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, using the same
+ * "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 two-piece connected border —
+ * generalized here from a fixed two children to an arbitrary list. 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.
+ *
+ * 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, so there's nothing yet for the z-index bump to protect.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/style-classes.html#linked-style-class
+ *
+ * @example
+ * <LinkedGroup>
+ *   <Button variant="flat">Bold</Button>
+ *   <Button variant="flat">Italic</Button>
+ * </LinkedGroup>
+ */
+export declare const LinkedGroup: import('react').ForwardRefExoticComponent<LinkedGroupProps & import('react').RefAttributes<View>>;

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

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

package/dist/components/NavigationSplitView/NavigationSplitView.d.ts

@@ -0,0 +1,69 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export interface NavigationSplitViewProps {
+    /**
+     * The sidebar / list pane (left side on wide screens).
+     * On narrow screens this is the "list" view shown when `showContent` is false.
+     */
+    sidebar: ReactNode;
+    /**
+     * The detail / content pane (right side on wide screens).
+     * On narrow screens this is the "detail" view shown when `showContent` is true.
+     */
+    content: ReactNode;
+    /**
+     * Controls which pane is visible on narrow screens (≤ 400 dp).
+     * - `false` (default) — show the sidebar list.
+     * - `true` — show the content detail.
+     *
+     * Has no effect on wide screens where both panes are visible simultaneously.
+     */
+    showContent?: boolean;
+    /** Minimum sidebar width in dp. Defaults to `180`. */
+    minSidebarWidth?: number;
+    /** Maximum sidebar width in dp. Defaults to `280`. */
+    maxSidebarWidth?: number;
+    /** Fraction of total width given to the sidebar (0–1). Defaults to `0.25`. */
+    sidebarWidthFraction?: number;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * 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 are visible side-by-side, separated by a `Separator`. On **narrow**
+ * screens only one pane is shown 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 (`StyleSheet` values aren't CSS `calc`/`clamp` expressions),
+ * so the container measures its own width via `onLayout` and the same clamp
+ * is computed in JS — `0` until the first layout pass resolves, the same
+ * one-frame imprecision this package already accepts elsewhere (e.g.
+ * `ProgressBar`'s `trackWidth`-dependent math).
+ *
+ * Narrow-mode pane switching is animated (`translateX`, matching the web
+ * CSS's own `transition: transform`), so — unlike `TabPanel`'s simpler
+ * `display: 'none'` swap — both panes stay laid out and absolutely
+ * positioned rather than being removed from flow, using the same measured
+ * container width for the slide distance (RN `transform` has no
+ * percentage-of-self units, so this can't be a bare `-100%`/`100%` the way
+ * the web version's CSS is). One shared `Animated.Value` drives both
+ * panes' opposite-direction translation, the same "skip the animation on
+ * initial mount, only animate subsequent prop changes" guard `Switch`/
+ * `StepIndicator` already established for a controlled boolean prop.
+ *
+ * The web's `inert` attribute (removes the hidden pane from both the a11y
+ * tree and the tab order while it stays mounted off-screen) has no single
+ * RN equivalent — reproduced with `accessibilityElementsHidden` +
+ * `importantForAccessibility="no-hide-descendants"` (the whole-subtree a11y
+ * exclusion, not just the single-element `"no"` `PathBar`'s decorative
+ * separator uses) plus `pointerEvents="none"` so the off-screen pane can't
+ * intercept touches meant for the visible one.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.NavigationSplitView.html
+ */
+export declare const NavigationSplitView: ({ sidebar, content, showContent, minSidebarWidth, maxSidebarWidth, sidebarWidthFraction, style, testID, }: NavigationSplitViewProps) => import("react/jsx-runtime").JSX.Element;

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

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

package/dist/components/RatingStars/RatingStars.d.ts

@@ -0,0 +1,48 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { IconSize } from '../Icon';
+export interface RatingStarsProps {
+    /** Current rating, between `0` and `max`. */
+    value: number;
+    /** Number of stars. Defaults to `5`. */
+    max?: number;
+    /**
+     * Called when the user picks a rating. Omit to render a read-only
+     * display (e.g. an average rating) instead of an interactive input.
+     */
+    onChange?: (value: number) => void;
+    /** Star size. Defaults to `"md"`. */
+    size?: IconSize;
+    /** Renders as read-only even when `onChange` is provided. */
+    disabled?: boolean;
+    /** Accessible label. Defaults to `"Rating"` (interactive) or a generated `"N out of M stars"` (read-only). */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * 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. for showing an
+ * average/read-only rating.
+ *
+ * The web version's `role="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 — same standing convention `ToggleGroup`
+ * already established for this package (its own doc comment covers the
+ * reasoning). What's left, tapping a star to commit that rating, is a
+ * strict subset of the web interaction, not an approximation of it.
+ *
+ * Each star's fill color is `tintColor={theme.warningBgColor}` rather than
+ * `Icon`'s own fixed `color="yellow"` (→ `theme.yellow4`, a different hex):
+ * the source CSS reads `var(--gnome-warning-bg-color, #f6d32d)` directly
+ * with no `color-mix()` darkening step, so the semantic warning token
+ * itself — already tracking dark mode and every contrast level — is the
+ * exact match, not an approximation through the fixed palette. Stars carry
+ * no `label` on `Icon` (decorative — `iconAccessibilityProps` already hides
+ * an unlabeled icon from the tree); the accessible name lives on the
+ * container (read-only) or each `Pressable` (interactive) instead, mirroring
+ * `ToggleGroupItem`'s icon-only items.
+ */
+export declare const RatingStars: ({ value, max, onChange, size, disabled, accessibilityLabel, style, testID, }: RatingStarsProps) => import("react/jsx-runtime").JSX.Element;

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

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

package/dist/components/TimePicker/TimeFields.d.ts

@@ -0,0 +1,36 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { TimeValue } from './timeUtils';
+export interface TimeFieldsProps {
+    /** The time the columns show. Always concrete — callers supply the fallback. */
+    value: TimeValue;
+    /** Called with the whole time whenever any column moves. */
+    onChange: (value: TimeValue) => void;
+    /** 12- or 24-hour presentation. Defaults to `24`. */
+    hourCycle?: 12 | 24;
+    /** Minute increment for the spinner. Defaults to `1`. */
+    minuteStep?: number;
+    /**
+     * Prefix for each column's accessible label — `"Start"` gives
+     * "Start hours". Needed when a panel carries more than one set of columns.
+     */
+    labelPrefix?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * The hour/minute (and AM/PM) `SpinButton` columns — the panel half of
+ * `TimePicker`, split out so `DatePicker`'s `showTime` footer can reuse the
+ * same 12/24-hour bookkeeping without re-implementing it.
+ *
+ * Ported from `@gnome-ui/react`'s `TimePicker/TimeFields.tsx`: mirrors its
+ * prop API and `to12`/`to24` bookkeeping exactly, rebuilt on this package's
+ * own `SpinButton` (already shipped in Tier 5, with a matching `wrap`
+ * boolean and `format: (n: number) => string` callback — confirmed by
+ * reading `SpinButton.tsx` before wiring this up, no new prop needed for the
+ * AM/PM column's "numeric spinner whose `format` maps 0/1 to text" trick).
+ *
+ * **Not exported from the package**: `TimePicker` is this module's public
+ * face; `DatePicker`'s `showTime` footer imports it directly via
+ * `@/components/TimePicker/TimeFields`, the same cross-folder internal
+ * import `Calendar/calendarUtils.ts`'s `WeekStart` already established.
+ */
+export declare const TimeFields: ({ value, onChange, hourCycle, minuteStep, labelPrefix, style, }: TimeFieldsProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/TimePicker/TimePicker.d.ts

@@ -0,0 +1,55 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { PopoverPlacement } from '../Popover';
+import { TimeValue } from './timeUtils';
+export type { TimeValue } from './timeUtils';
+export interface TimePickerProps {
+    /** Controlled selected time. Pass `null` for "no selection". */
+    value?: TimeValue | null;
+    /** Initial selected time when uncontrolled. Defaults to `null`. */
+    defaultValue?: TimeValue | null;
+    /** Called when the user changes the time. */
+    onChange?: (value: TimeValue) => void;
+    /** 12- or 24-hour presentation. Defaults to `24`. */
+    hourCycle?: 12 | 24;
+    /** Minute increment for the spinner. Defaults to `1`. */
+    minuteStep?: number;
+    /** Text shown in the trigger while no time 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;
+    /** Disable the control. */
+    disabled?: boolean;
+    /** Preferred popover placement relative to the trigger. Defaults to `'bottom'`. */
+    placement?: PopoverPlacement;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Hour/minute selection built from paired `SpinButton`s inside a `Popover`,
+ * behind an entry-styled trigger — mirrors the `GtkSpinButton` + `GtkPopover`
+ * composition GNOME apps use for time entry, with 12- and 24-hour support.
+ *
+ * Rebuilt on this package's own already-shipped `Popover` (Tier 5) rather
+ * than reinventing its trigger-rect + panel-size positioning, the same
+ * standing pitfall `DatePicker` already avoided. The panel is just
+ * `TimeFields` — no Done button, unlike `DatePicker`'s `showTime` footer:
+ * there is no calendar tap to disambiguate from a close here, so each
+ * column commits live and the popover only closes the same way `Dropdown`'s
+ * does, by tapping outside or the trigger again.
+ *
+ * **`TimeFields`/`timeUtils` moved here from `DatePicker`'s own folder**,
+ * where they first shipped as an internal dependency of its `showTime`
+ * footer — this is their intended public home (per the ROADMAP note left
+ * when `DatePicker` shipped), `DatePicker` now imports them from here
+ * instead of carrying its own copy.
+ *
+ * The web version's entire keyboard layer drops (no `ArrowDown`-opens focus
+ * management, no `Enter`/`Space` on the trigger) — the same touch-first
+ * convention `DatePicker` already follows. `locale` is dropped in favor of
+ * `GnomeProvider`'s app-wide `useDateTimeFormatter`, same as `DatePicker`.
+ *
+ * @see https://developer.gnome.org/hig/patterns/controls/spin-buttons.html
+ */
+export declare const TimePicker: ({ value: controlledValue, defaultValue, onChange, hourCycle, minuteStep, placeholder, label, accessibilityLabel, disabled, placement, style, testID, }: TimePickerProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { TimePickerProps, TimeValue } from './TimePicker';
+export { TimePicker } from './TimePicker';

package/dist/components/TimePicker/timeUtils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure time helpers shared by `TimePicker` and `DatePicker`'s `showTime`
+ * footer. Ported verbatim from `@gnome-ui/react`'s `TimePicker/timeUtils.ts`
+ * — no DOM dependency there already, the same `calendarUtils.ts` precedent.
+ *
+ * Not exported from the package barrel — `DatePicker` imports it directly
+ * via `@/components/TimePicker/timeUtils`, the same cross-folder internal
+ * import `Calendar/calendarUtils.ts`'s `WeekStart` already established.
+ */
+/** A wall-clock time, in 24-hour terms. */
+export interface TimeValue {
+    /** Hours, `0`–`23`. */
+    hours: number;
+    /** Minutes, `0`–`59`. */
+    minutes: number;
+}
+/** Zero-padded two-digit rendering for a clock column. */
+export declare const pad2: (n: number) => string;
+/** Split a 0–23 hour into its 12-hour parts (`period`: 0 = AM, 1 = PM). */
+export declare const to12: (hours24: number) => {
+    hour: number;
+    period: number;
+};
+/** Recombine a 12-hour clock reading into a 0–23 hour. */
+export declare const to24: (hour12: number, period: number) => number;
+/** The wall-clock time carried by a `Date`. */
+export declare const timeOf: (date: Date) => TimeValue;
+/**
+ * `date`'s calendar day at `time`'s wall clock.
+ *
+ * A local `Date` cannot represent an hour that a DST spring-forward skips, and
+ * the platform silently shifts it (02:30 → 03:30). That shift is kept — it is
+ * the only real instant for that reading — so callers should read the result
+ * back rather than assume the requested hour survived.
+ */
+export declare const mergeDateAndTime: (date: Date, time: TimeValue) => Date;