@gnome-ui/react-native 1.10.0 → 1.12.0

package/dist/components/ScrollToTop/ScrollToTop.d.ts

@@ -0,0 +1,105 @@
+import { StyleProp, View, ViewStyle } from 'react-native';
+/**
+ * Controls when the button is rendered.
+ *
+ * - `"auto"` — hidden until `scrollY` exceeds `threshold` (default).
+ * - `"always"` — always rendered regardless of scroll position.
+ */
+export type ScrollToTopVisible = 'always' | 'auto';
+/**
+ * Anchor corner or edge for the absolutely-positioned container.
+ * The button is inset `theme.space4` (24 dp) from each named edge.
+ */
+export type ScrollToTopPosition = 'bottom-right' | 'bottom-left' | 'bottom-center' | 'top-right' | 'top-left' | 'top-center';
+export interface ScrollToTopProps {
+    /**
+     * Controls when the button is visible.
+     *
+     * - `"auto"` (default) — shown only once `scrollY` exceeds `threshold`.
+     * - `"always"` — permanently visible.
+     */
+    visible?: ScrollToTopVisible;
+    /**
+     * Corner or edge where the button is anchored. Default: `"bottom-right"`.
+     */
+    position?: ScrollToTopPosition;
+    /**
+     * Offset the user must scroll past before the button appears.
+     * Only relevant when `visible="auto"`. Default: `300`.
+     */
+    threshold?: number;
+    /**
+     * The observed `ScrollView`/`FlatList`'s current vertical scroll offset —
+     * pass `nativeEvent.contentOffset.y` from its `onScroll` handler. Only
+     * relevant when `visible="auto"`; ignored (and safe to omit) otherwise.
+     * Default: `0`.
+     */
+    scrollY?: number;
+    /**
+     * Called when the button is pressed. There's no RN equivalent of the web
+     * version's own `scrollTarget.scrollTo({ top: 0, behavior: 'smooth' })` —
+     * `ScrollView`/`FlatList` are scrolled through a ref's imperative
+     * `scrollTo`/`scrollToOffset`, which this component has no way to hold on
+     * a consumer's behalf. Typically
+     * `() => scrollViewRef.current?.scrollTo({ y: 0, animated: true })`.
+     */
+    onPress: () => void;
+    /**
+     * Extra inset added on top of the base edge spacing when anchored to a
+     * `"top-*"` position — pass your own `useSafeAreaInsets().top` so the
+     * button clears a notch/status bar. Same "no new peer dependency" call
+     * `BottomTabBar`'s `bottomInset` already made. Default: `0`.
+     */
+    topInset?: number;
+    /** Same as `topInset`, for a `"bottom-*"` position. Default: `0`. */
+    bottomInset?: number;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Absolutely-positioned OSD button that scrolls a `ScrollView`/`FlatList`
+ * back to the top — mirrors `@gnome-ui/react`'s `ScrollToTop`, reimagined
+ * rather than ported 1:1 per this package's own ROADMAP note: RN has no
+ * page-level scroll event to observe internally the way the web version's
+ * `useScrollToTopVisibility` attaches a `window`/element `scroll` listener,
+ * so that hook doesn't port at all — `visible="auto"` is instead a pure
+ * function of a `scrollY` prop the consumer feeds from their own
+ * `ScrollView`'s `onScroll`, re-evaluated on every render with no internal
+ * state or listener needed.
+ *
+ * Same "no `document.body`/portal target" gap `Toaster` already
+ * documents — mount this yourself as the last child of the `View` wrapping
+ * your scrollable content (left at its default relative positioning) so it
+ * paints on top; `pointerEvents="box-none"` (the same technique `Toaster`
+ * uses) keeps the empty space around the button from intercepting touches
+ * meant for the content underneath.
+ *
+ * The web version's resting `opacity: 0.5`-until-hover/focus is dropped —
+ * the same call `PasswordEntryRow`'s reveal button already made: that
+ * effect exists purely so the control can brighten on hover, and touch has
+ * no hover, so a permanently dimmed control would just be harder to see.
+ *
+ * Forwards `ref` to the root positioning `View`, not the inner button —
+ * matching the web version's own `forwardRef` target.
+ *
+ * @example
+ * // Minimal — appears once `scrollY` exceeds 300, anchored bottom-right
+ * const [scrollY, setScrollY] = useState(0);
+ * const scrollRef = useRef<ScrollView>(null);
+ * <View style={{ flex: 1 }}>
+ *   <ScrollView
+ *     ref={scrollRef}
+ *     onScroll={(e) => setScrollY(e.nativeEvent.contentOffset.y)}
+ *     scrollEventThrottle={16}
+ *   >
+ *     ...
+ *   </ScrollView>
+ *   <ScrollToTop
+ *     scrollY={scrollY}
+ *     onPress={() => scrollRef.current?.scrollTo({ y: 0, animated: true })}
+ *   />
+ * </View>
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.ScrollToTop.html
+ */
+export declare const ScrollToTop: import('react').ForwardRefExoticComponent<ScrollToTopProps & import('react').RefAttributes<View>>;

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

@@ -0,0 +1,2 @@
+export type { ScrollToTopPosition, ScrollToTopProps, ScrollToTopVisible } from './ScrollToTop';
+export { ScrollToTop } from './ScrollToTop';

package/dist/components/Spacer/Spacer.d.ts

@@ -0,0 +1,25 @@
+import { StyleProp, View, ViewProps, ViewStyle } from 'react-native';
+export interface SpacerProps extends Omit<ViewProps, 'style'> {
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Invisible `flex: 1` filler for `Toolbar` and `HeaderBar` — mirrors
+ * `@gnome-ui/react`'s `Spacer`. Place between leading and trailing groups
+ * to push trailing items to the end.
+ *
+ * `accessible={false}` mirrors the web version's `aria-hidden="true"` —
+ * same "purely decorative, exclude from the accessibility tree entirely"
+ * call `Separator` already made, rather than reaching for `role`'s newer
+ * `"separator"` value (which exists but implies a divider a screen
+ * reader user might care about; a plain flex filler has no such meaning).
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/style-classes.html#spacer
+ *
+ * @example
+ * <Toolbar>
+ *   <Button variant="flat">Back</Button>
+ *   <Spacer />
+ *   <Button variant="flat">Done</Button>
+ * </Toolbar>
+ */
+export declare const Spacer: import('react').ForwardRefExoticComponent<SpacerProps & import('react').RefAttributes<View>>;

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

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

package/dist/components/StepIndicator/StepIndicator.d.ts

@@ -0,0 +1,56 @@
+import { StyleProp, ViewStyle } from 'react-native';
+export type StepIndicatorOrientation = 'horizontal' | 'vertical';
+export interface StepIndicatorProps {
+    /**
+     * Total number of steps, or an array of per-step labels rendered beside
+     * (vertical) or beneath (horizontal) each circle. Pass a plain number for
+     * an unlabelled sequence (only the "Step X of Y" caption is shown); pass
+     * an array of strings to label each step.
+     */
+    steps: number | string[];
+    /** Zero-based index of the current/active step. */
+    currentStep: number;
+    /** Layout direction. Default: `"horizontal"`. */
+    orientation?: StepIndicatorOrientation;
+    /**
+     * Called when a completed step's circle is pressed, letting the user jump
+     * back to a step they've already finished. Omit to make steps
+     * non-interactive. The current and upcoming steps are never pressable.
+     */
+    onStepClick?: (index: number) => void;
+    /** Accessible label for the indicator. Default: `"Progress"`. */
+    label?: string;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Numbered "Step X of Y" progress indicator for onboarding/wizard flows —
+ * mirrors `@gnome-ui/react`'s `StepIndicator`. Directly portable per this
+ * package's own ROADMAP note: no web-only APIs are involved, just derived
+ * dot/number state from `currentStep`.
+ *
+ * The outer container sets `role="navigation"` **without** `accessible` —
+ * the corrected pattern `ToggleGroup` established over the earlier
+ * `BoxedList`/`ViewSwitcher` precedent: `accessible` on a *grouping*
+ * container with multiple independently-focusable children (each step
+ * circle here) collapses the whole subtree into one VoiceOver stop on iOS.
+ * The role still groups on Android, and every step stays individually
+ * reachable; assert `element.props.role` on a `testID` in tests instead of
+ * `getByRole('navigation')`.
+ *
+ * The connecting line between circles reuses the exact CSS trick verbatim
+ * (`position: absolute; left: 50%; width: 100%` inside each equal-width
+ * flex item, so the line runs from one circle's center to the next's) —
+ * `left`/`width` percentages are supported for RN position/dimension
+ * props, unlike the `transform: translateX('50%')` trick this package has
+ * hit real bugs with elsewhere (that limitation is specific to `transform`).
+ *
+ * The web version's checkmark/number content swap and connector-line color
+ * change have no CSS `transition` at all (only `.circle`'s own
+ * `background-color`/`border-color` do), so only those two colors animate
+ * here — the content swap and connector recolor are instant, matching the
+ * source exactly rather than adding an unrequested fade.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.StepIndicator.html
+ */
+export declare const StepIndicator: ({ steps, currentStep, orientation, onStepClick, label, style, testID, }: StepIndicatorProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { StepIndicatorOrientation, StepIndicatorProps } from './StepIndicator';
+export { StepIndicator } from './StepIndicator';

package/dist/components/SwitchRow/SwitchRow.d.ts

@@ -0,0 +1,43 @@
+import { ReactNode } from 'react';
+import { PressableProps, StyleProp, View, ViewStyle } from 'react-native';
+export interface SwitchRowProps extends Omit<PressableProps, 'children' | 'style' | 'onPress'> {
+    /** Primary label. */
+    title: string;
+    /** Secondary line below the title. */
+    subtitle?: string;
+    /** Icon or image placed at the leading edge. */
+    leading?: ReactNode;
+    /** Controlled checked state. */
+    checked?: boolean;
+    /** Initial checked state when uncontrolled. Defaults to `false`. */
+    defaultChecked?: boolean;
+    /** Called with the next value when the row is pressed. */
+    onCheckedChange?: (checked: boolean) => void;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Activatable row with an integrated switch, mirroring `@gnome-ui/react`'s
+ * `SwitchRow`. The entire row is a single pressable — pressing anywhere
+ * toggles the switch, which is why this isn't `ActionRow` + a trailing
+ * `Switch` (the ROADMAP's own guess): `AdwSwitchRow` makes the whole row the
+ * interactive element, the same shape `CheckRow` already established for
+ * its checkbox. Prefer this over `CheckRow` for a single on/off setting,
+ * and `CheckRow` for selecting/deselecting individual items in a list.
+ *
+ * The switch visual reuses `Switch`'s exact track/thumb `Animated.Value`
+ * interpolation, but as plain non-interactive `Animated.View`s rather than
+ * importing the real `Switch` component — `Switch` is itself a `Pressable`,
+ * and nesting one touchable inside another (the row's own `Pressable`)
+ * would create two overlapping tap targets, the same reasoning `CheckRow`
+ * already applied to `Checkbox`. `aria-labelledby` (pointing the web
+ * button's `role="switch"` at the title/subtitle content) has no RN
+ * equivalent — `accessibilityLabel` combining title and subtitle is the
+ * substitution, same as `CheckRow`.
+ *
+ * Supports both controlled (`checked`) and uncontrolled (`defaultChecked`)
+ * modes, the same `isControlled`/internal-state-fallback shape already
+ * established by `Expander`/`ComboRow`/`Popover`/`CheckRow`.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.SwitchRow.html
+ */
+export declare const SwitchRow: import('react').ForwardRefExoticComponent<SwitchRowProps & import('react').RefAttributes<View>>;

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

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

package/dist/components/Timeline/Timeline.d.ts

@@ -0,0 +1,87 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export type TimelineOrientation = 'vertical' | 'horizontal';
+export type TimelineVariant = 'default' | 'dotted' | 'none';
+export interface TimelineItem {
+    /** Icon rendered inside the timeline node. Sized/colored by the consumer — see the component doc. */
+    icon?: ReactNode;
+    /**
+     * Content at the leading edge of the node.
+     * - **Vertical:** rendered to the left of the connector track.
+     * - **Horizontal:** rendered above the node.
+     *
+     * Typical use: timestamp, badge, short label.
+     */
+    leading?: ReactNode;
+    /** Main event content rendered adjacent to the node (title, description…). */
+    content: ReactNode;
+}
+export interface TimelineProps {
+    /** Ordered list of timeline events. */
+    items: TimelineItem[];
+    /**
+     * Axis direction of the connector line.
+     * - `"vertical"` — events stack top-to-bottom (default).
+     * - `"horizontal"` — events flow left-to-right, in a horizontal `ScrollView`.
+     */
+    orientation?: TimelineOrientation;
+    /**
+     * Visual style of the connector between nodes.
+     * - `"default"` — solid thin line.
+     * - `"dotted"` — dotted line; useful for future or pending events.
+     * - `"none"` — no connector; each node stands alone.
+     */
+    variant?: TimelineVariant;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Ordered sequence of events connected by a visual timeline — mirrors
+ * `@gnome-ui/react`'s `Timeline`. An original composition (no direct
+ * libadwaita widget), following GNOME HIG activity-feed/stepper patterns.
+ *
+ * The web version aligns every item's `leading` column (vertical) or row
+ * (horizontal) via CSS subgrid, so timestamps/labels line up across items
+ * regardless of how wide/tall any single one of them is. RN/Yoga has no
+ * grid or subgrid at all, so that alignment is reproduced by measurement
+ * instead — the same `onLayout` + `Record<index, size>` +
+ * "largest-so-far wins" technique `Slider`'s mark labels already
+ * established: every item's `leading` cell (always rendered, even when
+ * empty, matching the web version's own "same 3 children" comment)
+ * reports its own rendered width (vertical) or height (horizontal), and
+ * every cell gets a `minWidth`/`minHeight` equal to the largest one
+ * measured so far, so the node column/row starts at the same position in
+ * every item. The node track itself additionally gets a *fixed*
+ * width (vertical, matching the source CSS's literal `24px` column) or
+ * height (horizontal, the larger of the dot/icon node sizes, since the
+ * source's row there is CSS `auto` with no fixed value to port) — without
+ * it, an item with an icon node (28 dp) and one with a plain dot (12 dp)
+ * would each size their own track differently, misaligning `content`'s
+ * start position between them.
+ *
+ * `orientation="horizontal"` wraps itself in a horizontal `ScrollView`,
+ * reimagining the web CSS's `overflow-x: auto` — the direct native
+ * equivalent for "scroll instead of overflow when items don't fit". The
+ * web version's `grid-auto-columns: minmax(72px, 1fr)` also grows items
+ * to fill leftover space when the row *doesn't* overflow; that half
+ * doesn't port (a `ScrollView`'s content isn't bounded the way a CSS grid
+ * track is, so there's no "leftover space" to distribute) — each item
+ * just gets a flat 72 dp `minWidth` instead, unconditionally scrollable
+ * like `overflow-x: auto`'s own fallback path.
+ *
+ * `icon`/`leading`/`content` are plain `ReactNode`, the same as
+ * `PathBar`'s segment `icon` — the consumer sizes and colors their own
+ * icon (e.g. `tintColor={theme.accentFgColor}` on their own `<Icon>`),
+ * since RN has no `currentColor` for this component to tint an arbitrary
+ * child with the way the web version's CSS `color: accent-fg-color`
+ * does via inheritance onto the icon's SVG.
+ *
+ * `role="list"`/`role="listitem"` are set **without** `accessible` — the
+ * `ToggleGroup`/`StepIndicator`-established pattern for a grouping role
+ * over children that may themselves contain focusable content (an
+ * item's `content` is arbitrary `ReactNode` and could include one), so
+ * nothing nested inside gets swallowed into a single VoiceOver stop.
+ * Assert `element.props.role` on a `testID` in tests instead of
+ * `getByRole('list'/'listitem')`.
+ */
+export declare const Timeline: ({ items, orientation, variant, style, testID, }: TimelineProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { TimelineItem, TimelineOrientation, TimelineProps, TimelineVariant } from './Timeline';
+export { Timeline } from './Timeline';

package/dist/components/Toolbar/Toolbar.d.ts

@@ -0,0 +1,25 @@
+import { StyleProp, View, ViewProps, ViewStyle } from 'react-native';
+export interface ToolbarProps extends Omit<ViewProps, 'style'> {
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Horizontal action bar following the libadwaita `.toolbar` pattern —
+ * mirrors `@gnome-ui/react`'s `Toolbar`. Directly portable: no web-only
+ * APIs, just a flex row with fixed padding/gap.
+ *
+ * Provides `theme.space1` (6 dp) padding and gap — the standard spacing
+ * for rows of flat buttons in header bars, action bars, and tool rows.
+ * Place a `Spacer` between leading and trailing groups to push trailing
+ * items to the end. Use `Button variant="flat"` for buttons that blend
+ * into the bar, or `variant="raised"` for one that needs explicit
+ * elevation within a flat context.
+ *
+ * The web CSS's `color`/`font-family` on `.toolbar` are dropped — RN has
+ * no style inheritance from a parent `View` down to child `Text`
+ * elements the way CSS `color` cascades, so a value here would reach
+ * nothing (every child, e.g. `Button`, already sets its own explicit
+ * text/icon colors).
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/style-classes.html#toolbar-style-class
+ */
+export declare const Toolbar: import('react').ForwardRefExoticComponent<ToolbarProps & import('react').RefAttributes<View>>;

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

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