@gnome-ui/react-native 1.9.0 → 1.11.0

package/README.md

@@ -25,14 +25,17 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > (Tier 20), `Chip` (Tier 7), `IconButton`/`Drawer` (Tier 8/Tier 20), and
 > `Clamp` (Tier 6), `Box` (Tier 20), `WrapBox`/`ToggleGroup` (Tier 7), and
 > `InlineViewSwitcher` (Tier 8), `PreferencesGroup` (Tier 13), and
-> `EntryRow`/`PasswordEntryRow`/`ComboRow` (Tier 12), `ColorPicker`
+> `EntryRow`/`PasswordEntryRow`/`ComboRow`/`SpinRow` (Tier 12), `SplitButton`
+> (Tier 8), `ColorPicker`
 > (Tier 20), `Bin` (Tier 15), `Blockquote` (Tier 20), `ButtonRow`
 > (Tier 8), `Callout` (Tier 20), `CheckRow` (Tier 12), `ExpanderRow`
 > (Tier 8), `FieldGroup` (Tier 20), and `MultiSelectDropdown` (Tier 20)
 > also shipped, along with `FilterableMultiSelectDropdown` — an original
 > `@gnome-ui/react`-only component (not a GNOME HIG port) built once its
 > prerequisite `MultiSelectDropdown` landed — and `PasswordField`/
-> `RangeSlider`/`StatusBadge` (all Tier 20). `BottomTabBar` also shipped —
+> `RangeSlider`/`StatusBadge`/`WidgetManager` (all Tier 20) — `WidgetManager`
+> was previously deferred as low-priority, built once named directly since
+> every piece it composes had already shipped. `BottomTabBar` also shipped —
 > a React Native-only original with no `@gnome-ui/react` source at all
 > (desktop apps don't have a bottom tab bar pattern to mirror), built on
 > explicit request for the iOS/Android fixed bottom-navigation shape.
@@ -42,7 +45,9 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > query to lean on. `ButtonContent` (Tier 15) also shipped — an icon+label
 > layout helper mostly redundant with `Button`'s own `leadingIcon`/
 > `trailingIcon`, kept for composing the same spacing outside `Button`
-> itself. Component ports from `@gnome-ui/react` continue tier by
+> itself. `TagInput` (Tier 20) also shipped — a `WrapBox` + `Chip`
+> composition, unblocked once both had shipped. Component ports from
+> `@gnome-ui/react` continue tier by
 > tier — see this package's own [ROADMAP.md](./ROADMAP.md) for full
 > per-tier status against all 130 `@gnome-ui/react` components, and the
 > main [ROADMAP.md](../../ROADMAP.md) Priority 3 for the framework
@@ -182,6 +187,42 @@ yourself, matching the resolved label color (`theme.accentFgColor`,
 `theme.destructiveFgColor`, `theme.windowFgColor`, …) if you want them to
 match.
 
+### SplitButton
+
+```tsx
+import { SplitButton, Button } from '@gnome-ui/react-native';
+
+<SplitButton
+  label="Save"
+  onPress={() => save()}
+  dropdownContent={
+    <Button variant="flat" size="sm" onPress={() => saveAs()}>
+      Save as Template
+    </Button>
+  }
+/>;
+```
+
+Primary action button with an attached dropdown arrow, mirroring
+`AdwSplitButton` and `@gnome-ui/react`'s own `SplitButton`. Pressing the
+label half fires `onPress`; pressing the arrow half opens a floating panel
+with `dropdownContent` (menus, options, etc.). Supports the same
+`default`/`suggested`/`destructive` variants as `Button`.
+
+The label half is a real `Button` — its resting/pressed/disabled colors
+come for free. The arrow half is a hand-rolled `Pressable`, not a second
+`Button`: `Popover` (which supplies the floating panel) clones a prop-level
+`accessibilityState` onto its trigger, and RN merges a spread prop object
+outright rather than key-by-key — nesting a full `Button` there would
+silently clobber `Button`'s own internal `accessibilityState={{ disabled
+}}`. The hand-rolled `Pressable` owns `accessibilityState={{ disabled }}`
+itself instead, letting `Popover`'s clone merge in `expanded` alongside it.
+Its resting colors are derived from a small local color formula mirroring
+`Button`'s own (unexported) one, so the two halves render pixel-identical
+colors; they read as one connected control via zeroed shared inner corner
+radii plus a 1px separator, the RN equivalent of the web CSS's split
+`border-radius` and `.separator` span.
+
 ### Text
 
 ```tsx
@@ -1423,6 +1464,41 @@ thin composition of those same three pieces. `label` is required since the
 button has no visible text. Built as a genuine prerequisite for `Drawer`'s
 `rail`, not scope creep — every piece it composes already existed.
 
+### CopyButton
+
+```tsx
+import { CopyButton } from '@gnome-ui/react-native';
+
+<CopyButton value="CVE-2024-3094" />
+<CopyButton value={installCommand} label="Copy install command" copiedLabel="Added to clipboard" />
+```
+
+Icon button that copies `value` to the clipboard, swapping to a checkmark
+and a "Copied!" tooltip for `resetDelay` ms (default 2000) as confirmation
+— mirrors `@gnome-ui/react`'s `CopyButton`. RN has no `navigator.clipboard`,
+so this is built on `@react-native-clipboard/clipboard` (a new peer
+dependency, deliberately chosen over `expo-clipboard` so this package
+works the same in bare RN and Expo, not just this repo's own Expo example
+app — the same "no new peer dependency without a deliberate decision"
+standard `AnimatedIcon`'s `react-native-svg` addition was held to).
+
+**Real environment finding**: `@react-native-clipboard/clipboard`'s native
+module isn't part of Expo Go's preinstalled module set, so any app using
+this component needs a custom dev client (`npx expo prebuild` +
+`expo run:ios`/`run:android`) rather than plain Expo Go — confirmed by
+hitting `TurboModuleRegistry.getEnforcing(...): 'RNCClipboard' could not
+be found` in Expo Go before building this repo's own example app a dev
+client to verify the component on-device.
+
+Its `setString` is synchronous and void — unlike the web version's
+`navigator.clipboard.writeText`, which returns a `Promise` that can
+reject, there's no error channel to observe under normal operation.
+`onCopyError` is kept for API parity (and wraps the native call in a
+`try`/`catch` defensively) but in practice won't fire the way it can on
+web. The live-region announcement uses `role="status"` directly — RN's
+newer `Role` union does include `"status"`, unlike the older
+`AccessibilityRole` enum `Toast` had to substitute `"alert"` for.
+
 ### Drawer
 
 ```tsx
@@ -1453,6 +1529,44 @@ no exit keyframes at all, so this follows `Dialog`'s simpler animation
 shape instead. `backdrop-filter: blur(4px)` has no port (no native blur
 dependency in this package).
 
+### Toolbar
+
+```tsx
+import { Button, Spacer, Toolbar } from '@gnome-ui/react-native';
+
+<Toolbar>
+  <Button variant="flat">Cancel</Button>
+  <Spacer />
+  <Button variant="flat">Done</Button>
+</Toolbar>
+```
+
+Horizontal action bar following the libadwaita `.toolbar` pattern —
+mirrors `@gnome-ui/react`'s `Toolbar`. Directly portable, no web-only APIs
+— a flex row with `theme.space1` (6 dp) padding and gap, the standard
+spacing for rows of flat buttons in header bars, action bars, and tool
+rows. 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`
+the way CSS `color` cascades, so a value there would reach nothing (every
+child, e.g. `Button`, already sets its own explicit colors).
+
+### Spacer
+
+```tsx
+import { Spacer } from '@gnome-ui/react-native';
+```
+
+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"` — the 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).
+
 ### AvatarGroup
 
 ```tsx
@@ -1685,6 +1799,41 @@ zero height before `alignItems` gets to stretch anything into it. Caught
 on-device; it's a no-op in the ordinary case where the container hugs its
 content rather than having a fixed height.
 
+### TagInput
+
+```tsx
+import { TagInput } from '@gnome-ui/react-native';
+
+const [tags, setTags] = useState(['react', 'gnome']);
+
+<TagInput label="Tags" value={tags} onChange={setTags} placeholder="Add a tag…" />;
+```
+
+Type-to-add multi-value input rendering entries as removable `Chip`s in a
+`WrapBox`, mirroring `@gnome-ui/react`'s own `TagInput`. Type and press
+Return, or type a `,`, to commit the draft as a tag; paste a comma or
+newline-separated list to add several at once; Backspace with an empty
+draft removes the last tag; tap a chip's `×` to remove that one.
+
+The web version wires typed-`,` and pasted-list handling as two separate
+handlers (`onKeyDown`'s `,` case, `onPaste`). RN's `TextInput` has no
+`paste` event to mirror — but a paste still flows through `onChangeText`
+with the full resulting text, exactly like a typed `,` does, so both
+collapse into one handler here: whenever the text contains a `,` or
+newline, split on it and commit every non-empty part. Return is handled via
+`onSubmitEditing` (no `Enter` keystroke to catch on a touch keyboard), and
+Backspace-on-empty uses `onKeyPress` — the one `TextInput` event that still
+fires with the field already empty (`onChangeText` doesn't fire deleting
+from nothing).
+
+The tag box is a `Pressable` (mirrors the web version's
+`onClick={() => inputRef.current?.focus()}` on the container) with
+`accessible={false}` set explicitly: `Pressable` defaults `accessible` to
+`true`, which would otherwise collapse every `Chip`'s remove button and the
+draft input into a single VoiceOver stop — the same container-swallows-
+subtree trap documented for a bare `View` plus `accessibilityRole`, hit
+here via `Pressable`'s own default instead.
+
 ### StatusPage
 
 ```tsx
@@ -2022,6 +2171,38 @@ components means the flip-to-fit placement, the tap-outside dismissal and the
 — same behaviour as the web version, one level up. The keyboard layer drops
 as it does everywhere else here.
 
+### SpinRow
+
+```tsx
+import { SpinRow } from '@gnome-ui/react-native';
+
+<BoxedList>
+  <SpinRow
+    title="Volume"
+    subtitle="Output level"
+    value={volume}
+    onValueChange={setVolume}
+    min={0}
+    max={100}
+  />
+</BoxedList>
+```
+
+Settings row with an integrated spin button for numeric values — mirrors
+`AdwSpinRow` and `@gnome-ui/react`'s own `SpinRow`. Use it inside a
+`BoxedList` for settings with numeric ranges (volume, timeout duration,
+count limits, etc.). Controlled (`value`) and uncontrolled (`defaultValue`)
+modes both work.
+
+**This is a composition of `ActionRow` + `SpinButton`, the same shape as
+`ComboRow`'s `ActionRow` + `Dropdown` composition above.** `SpinButton` is
+controlled-only, so the uncontrolled `defaultValue` state lives in `SpinRow`,
+one level up. The web version's keyboard interaction (↑/↓ one step, Page
+Up/Down ten steps, Home/End to bounds) drops as it does everywhere else in
+this package — `SpinButton` already provides the touch/screen-reader
+equivalents it was built with (tap the visible −/+ buttons, or the
+`accessibilityRole="adjustable"` increment/decrement actions).
+
 ### ColorPicker / ColorSwatch
 
 ```tsx
@@ -2222,6 +2403,36 @@ nesting one `Pressable` inside another would create two overlapping tap
 targets. `aria-labelledby` has no RN equivalent, so `accessibilityLabel`
 combines the title and subtitle instead.
 
+### SwitchRow
+
+```tsx
+import { BoxedList, SwitchRow } from '@gnome-ui/react-native';
+
+<BoxedList>
+  <SwitchRow
+    title="Wi-Fi"
+    subtitle="Home Network"
+    checked={wifi}
+    onCheckedChange={setWifi}
+  />
+</BoxedList>
+```
+
+Activatable row with an integrated switch, for use inside a `BoxedList`
+— mirrors `@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` — `AdwSwitchRow` makes the whole row the
+interactive element, the same shape `CheckRow` already established for its
+checkbox. Use for a single on/off setting; prefer `CheckRow` for
+multi-select scenarios. Supports both controlled (`checked`) and
+uncontrolled (`defaultChecked`) modes, the same `isControlled`/internal-
+state-fallback shape already used by `Expander`/`ComboRow`/`Popover`/
+`CheckRow`. The switch visual reuses `Switch`'s exact track/thumb animation
+recipe, but as plain non-interactive `Animated.View`s rather than the real
+`Switch` component — nesting one `Pressable` inside another would create
+two overlapping tap targets. `aria-labelledby` has no RN equivalent, so
+`accessibilityLabel` combines the title and subtitle instead.
+
 ### ExpanderRow
 
 ```tsx
@@ -2396,6 +2607,157 @@ counter. Six variants (`success`/`warning`/`error`/`new`/`accent`/
 `neutral`) reuse `Badge`'s exact color-mapping shape, plus a `new` (purple)
 variant `Badge` doesn't have.
 
+### StepIndicator
+
+```tsx
+import { StepIndicator } from '@gnome-ui/react-native';
+
+<StepIndicator steps={5} currentStep={1} />
+
+<StepIndicator
+  steps={['Account', 'Profile', 'Payment', 'Confirm']}
+  currentStep={2}
+  onStepClick={setCurrentStep}
+/>
+
+<StepIndicator steps={4} currentStep={2} orientation="vertical" />
+```
+
+Numbered "Step X of Y" progress indicator for onboarding/wizard flows —
+mirrors `@gnome-ui/react`'s `StepIndicator`. Directly portable, no web-only
+APIs involved: each step's circle derives its state (upcoming/current/
+completed) purely from `currentStep`. Each circle animates its own
+border/background color (an independent pair of 0/1 `Animated.Value`s,
+one for "accented border" and one for "filled background", since they
+flip on different transitions) — the content swap between number and
+checkmark and the connector-line recolor are instant, matching the source
+CSS exactly (only `background-color`/`border-color` transition there).
+
+The connecting line between circles reuses the 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 valid RN position/dimension values, unlike
+the `transform: translateX('50%')` trick this package avoids elsewhere.
+The checkmark uses `tintColor` rather than `color`, since RN icons have no
+`currentColor` to inherit — the same call `BottomTabBar`'s active-tab icon
+already made for tracking the *configurable* accent.
+
+The outer container sets `role="navigation"` **without** `accessible` —
+the `ToggleGroup`-established pattern for a grouping role over multiple
+independently-focusable children (each step circle): `accessible` here
+would collapse the whole indicator into one VoiceOver stop on iOS. Assert
+`element.props.role` on a `testID` in tests instead of
+`getByRole('navigation')`. A completed step's circle becomes a `Pressable`
+only when `onStepClick` is provided — the current and upcoming steps are
+never pressable, matching the web version.
+
+### Timeline
+
+```tsx
+import { Timeline } from '@gnome-ui/react-native';
+
+<Timeline
+  items={[
+    { leading: <Text color="dim">10:00</Text>, icon: <Icon icon={Check} tintColor={theme.accentFgColor} />, content: <Text>Approved</Text> },
+    { content: <Text>Pending review</Text> },
+  ]}
+/>
+
+<Timeline orientation="horizontal" variant="dotted" items={steps} />
+```
+
+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. The node track itself additionally gets a fixed width
+(vertical, 24 dp, matching the source CSS's literal grid column) or
+height (horizontal, 28 dp, the larger of the dot/icon node sizes) so
+`content` starts at the same position across items even when dot and
+icon nodes are mixed in the same list.
+
+`orientation="horizontal"` wraps itself in a horizontal `ScrollView`,
+reimagining the web CSS's `overflow-x: auto`. 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) — each
+item gets a flat 72 dp `minWidth` instead, unconditionally scrollable.
+
+**Real, on-device-confirmed platform bug found while building `variant="dotted"`**:
+RN's `borderStyle: 'dotted'` renders nothing at all — no error, just
+invisible — unless *every* side shares the same width and color; the
+direct 1:1 port of the web CSS's single-side `border-left`/`border-top`
+dotted line (one bordered side, the other three left unset) silently
+produced no line whatsoever. Confirmed via the iOS Simulator with
+saturated debug colors: a uniform four-side `borderWidth`/`borderColor`
+renders the dotted pattern correctly, but reintroducing even three
+`transparent` sides (uniform width, per-side color) suppresses it again.
+Fixed by drawing the dotted connector as a narrow (6 dp) box with a
+uniform dotted border on all four sides instead of a single bordered
+edge — visually indistinguishable from a single dotted line at this
+thickness. **Any future dotted/dashed RN border needs all sides
+width-and-color-uniform — a single-side border in that style silently
+renders invisible.**
+
+`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}`), since RN has no `currentColor` for
+this component to tint an arbitrary child with. `role="list"`/
+`role="listitem"` are set without `accessible`, the same
+`ToggleGroup`/`StepIndicator`-established pattern for a grouping role
+over children that may themselves contain focusable content.
+
+### WidgetManager
+
+```tsx
+import { WidgetManager, type WidgetDefinition } from '@gnome-ui/react-native';
+
+const catalog: WidgetDefinition[] = [
+  { id: 'clock', label: 'Clock', description: 'Shows the current time', render: () => <ClockWidget /> },
+  { id: 'weather', label: 'Weather', render: () => <WeatherWidget /> },
+];
+
+<WidgetManager title="My Dashboard" catalog={catalog} value={widgetIds} onChange={setWidgetIds} />;
+```
+
+Card that manages a controlled collection of "widgets" — pick which ones
+are visible from a `catalog`, each rendering its own arbitrary content via
+`render()` — mirrors `@gnome-ui/react`'s own `WidgetManager`. The header's
+edit button toggles a local `editing` state: in view mode only the added
+widgets (or an empty-state message) show; in edit mode a dashed "add
+widget" trigger also appears, opening a catalog picker (`pickerSurface`:
+`"dialog"`, `"bottomSheet"`, or `"drawer"`). Adding/removing is staged
+inside the picker and only applied — via `onChange` — when the user
+confirms; canceling or dismissing discards the staging. Widgets can only be
+removed through the picker, never inline in the card.
+
+Every piece this composes already existed: `ActionRow`+`BoxedList` for the
+catalog rows, `Button`/`IconButton`/`Icon`/`StatusPage` for the rest of the
+chrome, and `Dialog`/`BottomSheet`/`Drawer` for the three `pickerSurface`
+options. The web version's option is called `"modal"`, after its own
+`Modal` component — this package's `Modal` counterpart is `Dialog` (RN's
+own `Modal` primitive is a different, lower-level thing), so the option is
+named after what it actually renders here instead of ported verbatim. None
+of those three overlay components scroll their `children` for you, unlike
+the web version's `overflow-y: auto` body, so the catalog list gets its own
+capped `ScrollView` before being handed to whichever surface renders it.
+`Dialog` already renders its own confirm/cancel row from a `buttons` array;
+only `bottomSheet`/`drawer` need the hand-rolled footer row the web source
+itself calls out ("Modal uses its own actions").
+
+Not ported: `aria-pressed` on the edit toggle — `Button`/`IconButton` set
+their own internal `accessibilityState` on the underlying `Pressable`, and
+a second `accessibilityState` prop passed in here would silently replace
+rather than merge with it (the same `Popover`-trigger clobber `SplitButton`
+already worked around) — dropped rather than routed around for one
+decorative toggle-state announcement.
+
 ### BottomTabBar
 
 ```tsx
@@ -2494,6 +2856,55 @@ threshold. Unlike the web version there's no `data-breakpoint` attribute
 to expose for CSS targeting (RN has no attribute selectors) — branch on
 `activeBreakpoint` directly inside the render prop instead.
 
+### ScrollToTop
+
+```tsx
+import { ScrollToTop } from '@gnome-ui/react-native';
+
+const scrollRef = useRef<ScrollView>(null);
+const [scrollY, setScrollY] = useState(0);
+
+<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>;
+```
+
+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: RN has no page-level scroll event to observe
+internally, so the web version's `useScrollToTopVisibility` (a `window`/
+element `scroll` listener) doesn't port at all. `visible="auto"` (the
+default) is instead a pure function of a `scrollY` number prop the
+consumer feeds from their own `ScrollView`'s `onScroll` — no internal
+state or listener needed. There's likewise no way for this component to
+scroll a `ScrollView`/`FlatList` on the consumer's behalf the way the web
+version calls `scrollTarget.scrollTo(...)` itself, so pressing the button
+calls the required `onPress` instead — typically
+`scrollRef.current?.scrollTo({ y: 0, animated: true })`.
+
+Same "no `document.body`/portal target" gap `Toaster` already documents —
+mount this yourself as the last child of the `View` wrapping your
+scrollable content 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.
+`topInset`/`bottomInset` let you thread in your own
+`useSafeAreaInsets()` values for a `"top-*"`/`"bottom-*"` position, same
+as `BottomTabBar`'s `bottomInset` — this package takes no dependency on
+`react-native-safe-area-context` itself.
+
 ## Installation
 
 ```bash

package/dist/components/CopyButton/CopyButton.d.ts

@@ -0,0 +1,44 @@
+import { IconButtonProps } from '../IconButton';
+export interface CopyButtonProps extends Omit<IconButtonProps, 'icon' | 'label' | 'onPress' | 'tooltip'> {
+    /** The text copied to the clipboard when the button is activated. */
+    value: string;
+    /** Accessible label and tooltip shown before copying. Defaults to `"Copy"`. */
+    label?: string;
+    /** Accessible label and tooltip shown briefly after a successful copy. Defaults to `"Copied!"`. */
+    copiedLabel?: string;
+    /** How long the "copied" confirmation state is shown, in milliseconds. Defaults to `2000`. */
+    resetDelay?: number;
+    /**
+     * Called after `value` is written to the clipboard.
+     * Named `onCopied` (not `onCopy`), mirroring the web version's own naming.
+     */
+    onCopied?: (value: string) => void;
+    /**
+     * Called if the copy attempt throws. Kept for API parity with the web
+     * version's `onCopyError` (whose `navigator.clipboard.writeText` can
+     * reject, e.g. on permission denial) — but `@react-native-clipboard/
+     * clipboard`'s `setString` is a synchronous, void-returning native call
+     * with no error channel at all, so in normal operation this won't fire
+     * the way it can on web. Kept as a defensive catch around the native
+     * call (a real, if unlikely, synchronous throw) rather than removed.
+     */
+    onCopyError?: (error: unknown) => void;
+}
+/**
+ * Icon button that copies `value` to the clipboard, swapping to a checkmark
+ * and a "Copied!" tooltip for `resetDelay` ms as confirmation — mirrors
+ * `@gnome-ui/react`'s `CopyButton`.
+ *
+ * RN has no `navigator.clipboard`, so this is built on
+ * `@react-native-clipboard/clipboard` (the community-standard clipboard
+ * module, not `expo-clipboard` — chosen so this package works the same in
+ * bare RN and Expo, not just this repo's own Expo example app). Its
+ * `setString` is synchronous and void — see `onCopyError`'s doc for what
+ * that means for error handling.
+ *
+ * The live-region announcement uses `role="status"` directly (RN's newer
+ * `Role` union does include `"status"`, unlike the older
+ * `AccessibilityRole` enum `Toast` had to substitute `"alert"` for) plus
+ * `accessibilityLiveRegion="polite"` for Android's announcement mechanism.
+ */
+export declare const CopyButton: ({ value, label, copiedLabel, resetDelay, onCopied, onCopyError, ...props }: CopyButtonProps) => import("react/jsx-runtime").JSX.Element;

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

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

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