@gnome-ui/react-native 1.5.0 → 1.7.0

package/README.md

@@ -17,12 +17,16 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > `PathBar`) fully ported. Tier 4 Feedback: `Spinner`, `ProgressBar`,
 > `Skeleton`, `Toast`/`Toaster`, `Banner`, `Dialog`, `Tooltip`, and
 > `AnimatedIcon` (which brought a new `Icon` component along with it, as its
-> own public component) shipped — `Status Page` skipped for now. Tier 5
+> own public component) and `StatusPage` shipped — Tier 4 complete. Tier 5
 > Advanced Controls fully ported: `Dropdown`, `Slider`, `SpinButton`,
 > `Avatar`, `Badge`, and `Popover`. Beyond Tier 5, `BottomSheet` (Tier 14)
 > and `Overlay`/`LevelBar`/`Expander`/`Divider`/`Highlight`/`FileTypeIcon`/
-> `SegmentedBar` (Tier 20), `Chip` (Tier 7), and `IconButton`/`Drawer`
-> (Tier 8/Tier 20) also shipped. Component ports from
+> `SegmentedBar`/`AvatarGroup`/`AvatarRotator`/`CoachMark`/`CoachMarkTour`
+> (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`
+> (Tier 20), and `Bin` (Tier 15) also 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
@@ -1430,6 +1434,646 @@ 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).
 
+### AvatarGroup
+
+```tsx
+import { AvatarGroup } from '@gnome-ui/react-native';
+
+<AvatarGroup
+  avatars={[{ name: 'Alice Martin' }, { name: 'Bob Smith' }, { name: 'Carol White' }]}
+  max={5}
+/>
+```
+
+Overlapping stack of `Avatar`s with a "+N" overflow indicator. Mirrors
+`@gnome-ui/react`'s `AvatarGroup`. The web version's separating ring
+around each overlapping avatar is two layered `box-shadow`s (an inset 1px
+dark/light border plus an outset 2px window-colored ring) — RN can only
+give a `View` one border, so this keeps just the outer window-colored
+ring (overriding `Avatar`'s own subtle 1px ring via its `style` prop),
+since that's the ring doing the actual "stay visually distinct from the
+avatar behind you" work. The overflow chip reuses `Avatar`'s own per-size
+box dimensions so it lines up exactly with the avatars beside it.
+`role="group"` + an auto-generated `accessibilityLabel` (joined names,
+plus "and N more" when overflowing) port 1:1 from RN's newer web-aligned
+`Role` union.
+
+### AvatarRotator
+
+```tsx
+import { AvatarRotator } from '@gnome-ui/react-native';
+
+<AvatarRotator name="Alice Martin" avatars={[url1, url2, url3]} />
+```
+
+Single avatar surface that crossfades through multiple image sources.
+Mirrors `@gnome-ui/react`'s `AvatarRotator`. Keeps `Avatar` focused on
+rendering one identity, while this component owns timing, crossfade
+animation, and pause behavior.
+
+Each source renders as its own absolutely-positioned `Avatar`, crossfaded
+with `Animated.timing` (`useNativeDriver: true`) — a `RotatorLayer`
+sub-component owns each layer's own `Animated.Value` rather than the
+parent tracking an array of them, the same "each item animates itself"
+shape `Toast`/`Toaster` already established for independently
+transitioning list items. `prefers-reduced-motion` stops the rotation
+outright, not just the fade — ported exactly from the web version's own
+auto-advance effect, which bails out early on both `isPaused` and reduced
+motion alike. `pauseOnHover` becomes `pauseOnPress`
+(`onPressIn`/`onPressOut`) — the same touch substitution `Toast`'s own
+press-and-hold pause already established, kept as a real toggleable prop
+here (defaults `true`).
+
+### CoachMark / CoachMarkTour
+
+```tsx
+import { CoachMark, CoachMarkTour } from '@gnome-ui/react-native';
+
+<CoachMark
+  open={open}
+  targetRef={target}
+  title="Sync your files"
+  description="Press this to keep every device up to date."
+  primaryAction={{ label: 'Got it', onPress: () => setOpen(false) }}
+  onDismiss={() => setOpen(false)}
+/>
+
+<CoachMarkTour
+  open={running}
+  steps={[
+    { targetRef: searchRef, title: 'Search', description: 'Find anything fast.' },
+    { targetRef: addRef, title: 'Add', description: 'Create a new item here.', placement: 'left' },
+  ]}
+  onFinish={() => setRunning(false)}
+  onSkip={() => setRunning(false)}
+/>
+```
+
+Spotlights a target element and anchors a callout bubble (title,
+description, step counter, actions) beside it, guiding a user to one
+feature. Compose several with `CoachMarkTour`, or drive one directly with
+`open`. Mirrors `@gnome-ui/react`'s `CoachMark`/`CoachMarkTour` — not a
+GNOME HIG widget, a pragmatic feature-discovery pattern.
+
+Positions with the same two-pass viewport-aware flip as the web version
+(`coachMarkUtils.ts`, duplicated verbatim — pure math, no DOM), resolved
+from `targetRef.current?.measureInWindow(...)` and the bubble's own
+`onLayout` size. **The measurement is deliberately delayed (a real
+`setTimeout`, not just one `requestAnimationFrame`)** — confirmed
+on-device that measuring too early catches a stale rect when the target
+sits below sibling content whose own size isn't final on the first commit
+(e.g. a multi-line description `Text` above it); a single rAF still
+landed before the follow-up layout pass accounted for it.
+
+The spotlight cutout has no CSS `box-shadow: 0 0 0 100vmax` port — that
+trick paints an opaque scrim everywhere except inside a rounded rect via a
+huge spread shadow, which RN's real OS shadows can't reproduce. Rebuilt as
+four plain `View` bands around the padded target rect, plus a separate
+rounded `accentColor`-bordered ring on top — the whole overlay sits inside
+one full-screen `Pressable`, so a tap anywhere within it (including
+visually "in the hole") triggers `dismissOnBackdrop`, matching the web
+version exactly. `dismissOnBackdrop` has no effect when `spotlight` is
+`false` — ported faithfully, not fixed: the web source only renders a
+backdrop element at all when `spotlight` is true. The arrow reuses
+`Popover`/`Tooltip`'s transparent-border-triangle trick rather than the
+web CSS's rotated-45°-square, offset along the bubble's edge by
+`arrowOffset` from the position math (unlike `Tooltip`/`Popover`'s simpler
+always-centered arrow). No focus trap and no scroll/resize
+re-positioning, the same established gaps for a transient RN floating
+element. `CoachMarkTour` is pure state orchestration on top of
+`CoachMark`, ported verbatim.
+
+### Clamp
+
+```tsx
+import { Clamp } from '@gnome-ui/react-native';
+
+<Clamp>
+  <BoxedList>{/* … */}</BoxedList>
+</Clamp>
+
+<Clamp maximumSize={480} tighteningThreshold={0.9}>
+  <Text>Never wider than 480 dp, and never edge-to-edge below it</Text>
+</Clamp>
+```
+
+Constrains its children to a maximum width while letting them shrink freely
+— mirrors `@gnome-ui/react`'s `Clamp` and the Adwaita `AdwClamp` widget. Use
+it on settings pages and forms so content never becomes too wide to read
+comfortably on a tablet or a landscape phone, while still filling the width
+on a narrow one. `maximumSize` defaults to **600** (the Adwaita recommended
+narrow-content width) and is in density-independent pixels, not CSS px.
+Adds no padding of its own.
+
+The web version's `margin-inline: auto` centering becomes
+`alignSelf: 'center'` rather than `marginHorizontal: 'auto'` — RN
+auto-margin support was left unverified for this Yoga version back when
+`Drawer` needed the same trick, so this follows `Drawer`'s resolution of
+using flex alignment instead. The one consequence is that `Clamp` expects a
+column-direction parent (RN's default): `alignSelf` acts on the cross axis,
+so inside a `flexDirection: 'row'` parent it would centre vertically. Wrap
+it in a plain `View` there.
+
+`tighteningThreshold` is a real percentage width here, unlike in
+`@gnome-ui/react`, where the prop is declared and documented but never
+reaches the DOM — implementing it exactly as that package documents it (a
+fraction of the available width, still capped by `maximumSize`) costs
+nothing on RN and avoids shipping a dead prop.
+
+### Box
+
+```tsx
+import { Box } from '@gnome-ui/react-native';
+
+// Vertical section (heading + content)
+<Box spacing={12}>
+  <Text variant="caption-heading" color="dim">Devices</Text>
+  <BoxedList>{/* … */}</BoxedList>
+</Box>
+
+// Horizontal icon + label
+<Box orientation="horizontal" spacing={6} align="center">
+  <Icon icon={Folder} size="sm" />
+  <Text>Documents</Text>
+</Box>
+```
+
+Fundamental flex layout primitive — the RN equivalent of `GtkBox`, and a 1:1
+mirror of `@gnome-ui/react`'s own `Box`. Arranges children in a row or
+column with consistent spacing from the GNOME HIG scale: **3** (tight) ·
+**6** (standard, the default) · **12** (medium) · **18** (large) · **24**
+(section) · **32** (loose) · **48** (jumbo), all in dp. `align` defaults to
+`"stretch"` when vertical and `"center"` when horizontal, `justify` to
+`"start"`.
+
+`BoxSpacing` keeps the web package's exact seven values rather than being
+remapped onto this package's own `theme.space1`–`space6` scale — the two
+overlap at 6/12/18/24/48 but not at 3 or 32/36, and `BoxSpacing` is a
+published type consumers may already be importing, so it ports verbatim.
+
+Two things the web version accepts don't survive the platform. `spacing`
+and `padding` are numbers only — RN's `gap`/`padding` take dp, not CSS
+strings like `"1rem"`. And `align`/`justify`, which the web hands straight
+to CSS, are mapped internally from their bare `start`/`end` keywords onto
+Yoga's `flex-start`/`flex-end`; the prop values stay the web ones, so the
+API reads identically across both packages. `display: 'flex'` needs no port
+at all — every RN `View` is already a flex container.
+
+### WrapBox
+
+```tsx
+import { WrapBox } from '@gnome-ui/react-native';
+
+// Tag list
+<WrapBox>
+  {tags.map((tag) => <Chip key={tag} label={tag} />)}
+</WrapBox>
+
+// Tight between items, loose between lines
+<WrapBox childSpacing={6} lineSpacing={18} justify="center">
+  {filters.map((filter) => <Chip key={filter} label={filter} />)}
+</WrapBox>
+```
+
+Flexible wrapping layout container — children flow horizontally and wrap to
+new lines when they don't fit, like words in a paragraph, without locking
+them into a grid. Mirrors `AdwWrapBox` (libadwaita 1.7 / GNOME 48) and
+`@gnome-ui/react`'s own `WrapBox`. Pair with `Chip` for tag lists and filter
+rows.
+
+`childSpacing` (default **6**) is the gap between items on a line;
+`lineSpacing` is the gap between lines and falls back to `childSpacing` when
+omitted — passing `0` really means zero, not "fall back". `justify` defaults
+to `"start"` and `align` to `"center"`; `wrapReverse` stacks lines bottom to
+top.
+
+The web version ships its values as CSS custom properties consumed by a
+stylesheet (`--wrapbox-gap`, `--wrapbox-justify`, …) because a CSS module
+can't take runtime values any other way — RN has no such indirection, so
+they're written straight onto the style object. `flex-flow: row wrap`
+becomes `flexDirection: 'row'` + `flexWrap`, and the CSS shorthand
+`gap: <row> <column>` splits into RN's separate `rowGap`/`columnGap`; the
+single `gap` property would set both, which is precisely what this component
+has to be able to avoid. As in `Box`, the spacing props are numbers only
+(dp, not CSS strings) and `align`/`justify` keep the web's bare `start`/`end`
+keywords while mapping internally onto Yoga's `flex-start`/`flex-end`.
+
+`alignContent: 'stretch'` is set explicitly even though neither package
+exposes an `alignContent` prop: **CSS defaults it to `stretch`, Yoga defaults
+it to `flex-start`**, so without it `align="stretch"` silently does nothing
+whenever the children have no cross-size of their own — the line collapses to
+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.
+
+### StatusPage
+
+```tsx
+import { StatusPage } from '@gnome-ui/react-native';
+
+<StatusPage
+  icon={StarOutline}
+  title="No favorites yet"
+  description="Packages you star will show up here."
+>
+  <Button variant="suggested" onPress={onAdd}>Add a package</Button>
+</StatusPage>
+
+// For sidebars, popovers, and small panels
+<StatusPage compact icon={Search} title="No results" />
+```
+
+Empty-state / status page following the Adwaita `AdwStatusPage` pattern —
+mirrors `@gnome-ui/react`'s `StatusPage`. Use it to fill a view with no
+content yet, an error state, or a completion confirmation. Always explain
+*why* the view is empty and *what the user can do* about it; don't use it
+for loading states, where `Spinner` or `ProgressBar` belong instead.
+`compact` scales padding, icon size, title variant, description
+variant/measure and both action-area gaps down together.
+
+It centres its content on both axes, but — exactly as in the web version —
+the vertical centring only does anything once a parent gives it height: put
+it in a `flex: 1` container to fill the view.
+
+The title renders through this package's `Text` at `variant="title-1"`
+(`"title-4"` when `compact`), so it also picks up `Text`'s automatic
+`header` accessibility role — a deliberate divergence from the web
+version's `<p class="title">`. That `<p>` exists because HTML forces you to
+pick a concrete `h1`–`h6` level for a component that can't know where it
+sits in the document outline; RN's `header` role carries no level, so the
+dilemma disappears. On a touch device the rotor is the only structural
+navigation a screen reader user has, which makes the role worth having.
+
+`max-width: 36ch` on the description has no RN unit to port to. `ch` is the
+advance width of "0", ≈ 0.5em in the sans faces Adwaita uses, so the cap is
+resolved against the description's own font size — 288 dp at body size, 216
+dp at caption size — keeping the measure font-relative the way the CSS is,
+rather than freezing one pixel value that `compact` would get wrong. The
+icon is dimmed by its wrapper's opacity (0.55 light / 0.45 dark, the two
+values the web's own `prefers-color-scheme` block hardcodes) and hidden
+from assistive tech with the `accessibilityElementsHidden` +
+`importantForAccessibility="no"` pair used in place of `aria-hidden`. The
+action area is a `WrapBox` rather than a hand-rolled row — `.actions` is a
+centred wrapping flex row with a gap and nothing else.
+
+### ToggleGroup / ToggleGroupItem
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from '@gnome-ui/react-native';
+
+const [align, setAlign] = useState('left');
+
+<ToggleGroup value={align} onValueChange={setAlign} accessibilityLabel="Alignment">
+  <ToggleGroupItem name="left" icon={FormatJustifyLeft} accessibilityLabel="Left" />
+  <ToggleGroupItem name="center" icon={FormatJustifyCenter} accessibilityLabel="Center" />
+  <ToggleGroupItem name="right" icon={FormatJustifyRight} accessibilityLabel="Right" />
+</ToggleGroup>
+
+// Items can be icon-only, label-only, or icon + label
+<ToggleGroupItem name="grid" icon={Applications} label="Grid" />
+```
+
+Mutually-exclusive group of toggle buttons for in-place option selection —
+mirrors `AdwToggleGroup` (libadwaita 1.7 / GNOME 48) and
+`@gnome-ui/react`'s own `ToggleGroup`. Use it for formatting controls,
+view-mode selectors and toolbar options, wherever a `ViewSwitcher` would be
+too heavy or doesn't belong in a `HeaderBar`. For icon-only items always
+pass an `accessibilityLabel`.
+
+The context and its `value`/`onValueChange` shape port 1:1 — pure React. The
+keyboard layer doesn't: the web version owns an `onKeyDown` implementing
+← / → cycling and Home / End jumps over a roving `tabIndex`, none of which
+has a touch counterpart, so it drops per this package's standing convention
+(set by `ViewSwitcher` and `TabBar`). The `radiogroup`/`radio` + `checked`
+pairing that VoiceOver and TalkBack actually announce carries the semantics
+instead.
+
+The group sets `accessibilityRole="radiogroup"` but deliberately **not**
+`accessible` — on iOS, `accessible` on a container collapses the whole
+subtree into a single accessibility element, which would make the individual
+toggles unreachable for VoiceOver. Without it the role still groups on
+Android while every item stays focusable on its own.
+
+Three `color-mix(in srgb, accent N%, transparent)` values resolve to 8-digit
+`#RRGGBBAA` hexes off `theme.accentBgColor` (the `Chip` precedent for the
+same selected-tint problem), so the tint follows the app's configurable
+accent color. The CSS paints its active ring as an `inset` box-shadow, which
+RN has no equivalent for — it becomes a real `borderWidth: 1` that every
+item carries at all times (transparent when inactive) so selecting one never
+shifts the row's layout, the substitution `AvatarGroup` already made for its
+own ring. `box-shadow: var(--gnome-shadow-sm)` on the group is dropped
+rather than approximated: the theme generator keeps shadow tokens in `raw`
+only, and `Card` already established that a border carries the same
+separation here. `:hover` collapses away and `:active` maps to `Pressable`'s
+`pressed` using `theme.activeOverlay`, whose light/dark values match the
+CSS's own `:active` colors exactly.
+
+The icon keeps the default foreground color instead of tracking the active
+accent text — `Icon` has no `currentColor` equivalent and its `color` prop
+is a fixed GNOME palette with no `accent` member, which couldn't follow a
+configurable accent anyway. Same call, same reason, as `Chip`.
+
+### InlineViewSwitcher / InlineViewSwitcherItem
+
+```tsx
+import { InlineViewSwitcher, InlineViewSwitcherItem } from '@gnome-ui/react-native';
+
+const [view, setView] = useState('grid');
+
+<InlineViewSwitcher value={view} onValueChange={setView} variant="pill">
+  <InlineViewSwitcherItem name="grid" label="Grid" icon={Applications} />
+  <InlineViewSwitcherItem name="list" label="List" icon={ViewSidebar} />
+</InlineViewSwitcher>
+
+// Collapse to a BottomSheet picker when the items stop fitting
+<InlineViewSwitcher value={view} onValueChange={setView} overflow="menu">
+  {/* … */}
+</InlineViewSwitcher>
+```
+
+Compact inline view switcher for content areas, cards and toolbars —
+wherever `ViewSwitcher` (header-bar sized) would be too heavy. Mirrors
+`AdwInlineViewSwitcher` (libadwaita 1.7 / GNOME 48) and `@gnome-ui/react`'s
+own `InlineViewSwitcher`. Four variants — `default` (card surface + border),
+`flat` (indicator only), `round` (pill container, solid accent indicator),
+`pill` (segmented-control look, no accent) — and four overflow strategies:
+`wrap`, `scroll`, `compact`, `menu`.
+
+Almost none of the *mechanism* ports, so this is a rebuild rather than a
+transliteration:
+
+- **The sliding indicator** is measured, not laid out. The web reads the
+  active button's `offsetLeft`/`offsetWidth`; here each item reports its own
+  `onLayout` up through the context and the indicator animates `translateX` +
+  `width` on **one JS-driven animation** (`useNativeDriver: false`). `width`
+  can't be native-driven and mixing a native with a JS value on one component
+  throws — the trade-off `Expander` already accepted for its animated height.
+  `scaleX` would have been native-driveable but distorts the corner radii the
+  variants are defined by. `useReducedMotion()` snaps it into place instead.
+- **Overflow detection** replaces `ResizeObserver` + `scrollWidth` vs
+  `clientWidth` with the item measurements already being collected: their
+  summed natural widths (RN leaves `flexShrink` at 0, so an overflowing row
+  still reports each item at full width) against the row's own `onLayout`.
+  The web's `naturalWidthRef` capture and 30 px hysteresis port verbatim —
+  without them, collapsing the labels shrinks the content and immediately
+  re-expands it.
+- **`overflow="scroll"`** becomes a horizontal `ScrollView` with the
+  scrollbar hidden; `scroll-snap-align: start` has no RN style, but the
+  measured item offsets feed `snapToOffsets`, which reproduces it exactly.
+- **`overflow="menu"`** reuses the already-shipped `BottomSheet`.
+
+The ←/→/Home/End keyboard layer drops as everywhere else here, and — as in
+`ToggleGroup` — the group takes `accessibilityRole="radiogroup"` but
+deliberately not `accessible`, which on iOS would collapse the items into one
+unreachable element.
+
+One divergence is a fix, not a port: the web applies its `.active` class to
+the menu trigger even though menu mode hides the indicator, which paints
+`round`'s trigger label in `accent-fg` (#fff) on a plain card — white on
+white. The RN trigger uses the idle color.
+
+### PreferencesGroup
+
+```tsx
+import { PreferencesGroup } from '@gnome-ui/react-native';
+
+<PreferencesGroup
+  title="Appearance"
+  description="How the app looks on this device."
+  headerSuffix={<Button variant="flat" onPress={reset}>Reset</Button>}
+>
+  <BoxedList>{rows}</BoxedList>
+</PreferencesGroup>
+```
+
+Titled section that wraps a `BoxedList` with an optional description —
+mirrors `AdwPreferencesGroup` and `@gnome-ui/react`'s own
+`PreferencesGroup`. Use it to group related settings under a named heading.
+It's purely a layout and labelling wrapper: it doesn't render the
+`BoxedList` itself, you pass one as `children`. All three header parts are
+optional; with none of them the header row is omitted entirely.
+
+The web's empty `.content` wrapper looks like dead markup but is
+load-bearing, so it's kept. The group is a 12 dp-gap flex column — without
+that wrapper every child would become a flex item of the group and pick up a
+12 dp gap between the rows themselves, instead of one gap between the header
+and the content as a whole.
+
+The title renders as `Text variant="body"` with an explicit semibold weight
+rather than `variant="heading"`, which is body-sized but **bold** and on the
+tighter heading line-height; the CSS `.title` is specifically semibold at the
+body line-height. It keeps the `header` accessibility role anyway (passed
+explicitly), since a settings-group heading is exactly the kind of landmark a
+screen reader rotor should list — the same call `StatusPage` makes for its
+own title. `min-width: 0` on the header text has no port and needs none: it's
+the classic CSS flexbox override for a min-content floor Yoga doesn't apply
+in the first place.
+
+### EntryRow
+
+```tsx
+import { EntryRow } from '@gnome-ui/react-native';
+
+const [name, setName] = useState('');
+
+<BoxedList>
+  <EntryRow title="Display name" value={name} onValueChange={setName} />
+  <EntryRow
+    title="Email"
+    value={email}
+    onValueChange={setEmail}
+    keyboardType="email-address"
+    leading={<Icon icon={MailRead} />}
+    trailing={<IconButton icon={Delete} label="Clear" onPress={() => setEmail('')} />}
+  />
+</BoxedList>
+```
+
+Row with an inline text entry field — mirrors `AdwEntryRow` and
+`@gnome-ui/react`'s own `EntryRow`. The `title` rises above the input as a
+small label once the field is focused or has content, and stands in for the
+placeholder until then. Use it inside a `BoxedList` for settings that take
+free-form text. Controlled (`value`) and uncontrolled (`defaultValue`) modes
+both work, and every remaining `TextInput` prop passes through.
+
+The float is one JS-driven `Animated.Value` (`useNativeDriver: false`):
+`fontSize` is part of the transition and can't be native-driven, and mixing a
+native with a JS value on one component throws — the same trade-off
+`Expander` and `InlineViewSwitcher` already accepted. `useReducedMotion()`
+snaps between the two states instead.
+
+**The label's travel is measured, not hardcoded.** The web expresses the
+resting position as `top: 50%; transform: translateY(-50%)` and the floated
+one as `top: 6px`, but RN can't interpolate between a percentage and a fixed
+offset — so the field reports its own height through `onLayout` and the
+distance is derived from it, which also keeps the label centred if you make
+the row taller than the 56 dp minimum.
+
+The `:focus` inset ring is dropped rather than approximated. `TextField`'s
+own precedent — recolor the border on focus — doesn't transfer, because an
+`EntryRow` has no border of its own: it's a row inside a `BoxedList`, and
+adding one would shift the list's geometry. On a touch device the state is
+already unmistakable: the label floats up, the text fades in, and the
+keyboard opens.
+
+Two deliberate divergences from the web version. The visible label is hidden
+from assistive tech and the `title` becomes the input's `accessibilityLabel`
+— RN has no `<label htmlFor>`, so otherwise the label would be announced as
+loose text next to an unnamed field (pass `accessibilityLabel` to override).
+And `testID` lands on the row rather than the input, matching every other
+component in this package; reach the field itself by its accessible name.
+
+### PasswordEntryRow
+
+```tsx
+import { PasswordEntryRow } from '@gnome-ui/react-native';
+
+<BoxedList>
+  <PasswordEntryRow title="Password" value={password} onValueChange={setPassword} />
+
+  {/* Registration and change-password forms */}
+  <PasswordEntryRow
+    title="New password"
+    value={next}
+    onValueChange={setNext}
+    autoComplete="new-password"
+  />
+</BoxedList>
+```
+
+Password entry row with a built-in reveal/conceal toggle — mirrors
+`AdwPasswordEntryRow` and `@gnome-ui/react`'s own `PasswordEntryRow`. It's an
+`EntryRow` that masks its input and always carries a trailing button to show
+or hide what's been typed, so don't add your own through `trailing` — that
+slot is for anything that should sit *before* the reveal button.
+
+`type={revealed ? 'text' : 'password'}` becomes RN's `secureTextEntry`, and
+`autoComplete` defaults to `"current-password"`, which is what lets password
+managers and the platform keyboard offer a saved credential.
+
+The reveal control is the already-shipped `IconButton` rather than a
+hand-rolled pressable, which costs one visual detail: `IconButton` is
+circular (it's `Button` at `shape="circular"`) where the web's
+`.revealButton` is a 32 dp square with a 6 dp radius. A circular flat icon
+button is the idiomatic touch control and keeps the row consistent with every
+other icon action here. The CSS's resting `opacity: 0.55` is dropped too — it
+exists so the button can brighten on hover, and with no hover on a touch
+device a permanently dimmed control is just harder to see.
+
+The web needs `e.stopPropagation()` so pressing the button doesn't also
+trigger the row's focus-the-input click. RN's responder system routes a touch
+to the innermost pressable, so there's nothing to stop.
+
+### ComboRow
+
+```tsx
+import { ComboRow } from '@gnome-ui/react-native';
+
+<BoxedList>
+  <ComboRow
+    title="Language"
+    subtitle="Used across the whole app"
+    value={language}
+    onValueChange={setLanguage}
+    options={[
+      { value: 'en', label: 'English' },
+      { value: 'es', label: 'Español' },
+    ]}
+  />
+</BoxedList>
+```
+
+Settings row with an inline combo selector at the trailing edge — mirrors
+`AdwComboRow` and `@gnome-ui/react`'s own `ComboRow`. Use it inside a
+`BoxedList` for a setting that picks one of a set of options. Controlled
+(`value`) and uncontrolled (`defaultValue`) modes both work; the trigger
+falls back to `"—"` when nothing is selected.
+
+**This is a composition of `ActionRow` + `Dropdown`, where the web version
+hand-rolls its own listbox inline** — around 200 lines re-implementing the
+trigger, the flip-up placement, outside-click dismissal, roving
+`aria-activedescendant` and the whole keyboard layer, none of which is
+meaningfully different from that package's own `Dropdown`. Nothing forced the
+duplication visually either: `.row` is `ActionRow`'s exact metrics and
+`.trigger` is `Dropdown`'s exact trigger. Composing the two already-shipped
+components means the flip-to-fit placement, the tap-outside dismissal and the
+`Modal`-based list all come along for free rather than being rebuilt.
+
+`Dropdown` is controlled-only, so the uncontrolled state lives in `ComboRow`
+— same behaviour as the web version, one level up. The keyboard layer drops
+as it does everywhere else here.
+
+### ColorPicker / ColorSwatch
+
+```tsx
+import { ColorPicker, ColorSwatch, GNOME_PALETTE } from '@gnome-ui/react-native';
+
+const [color, setColor] = useState('#3584e4');
+
+<ColorPicker value={color} onChange={setColor} />
+
+// Custom colors, with your own picker behind the "+"
+<ColorPicker
+  value={color}
+  onChange={setColor}
+  allowCustom
+  onRequestCustom={() => setPickerOpen(true)}
+/>
+```
+
+Color palette picker following the Adwaita `GtkColorButton` + swatch pattern
+— mirrors `@gnome-ui/react`'s own `ColorPicker`. Renders a wrapping row of
+circular `ColorSwatch` items backed by a radio group, defaulting to
+`GNOME_PALETTE` (the 9 Adwaita named colors, the same set `Avatar` uses).
+`ColorSwatch` is exported for standalone use; sizes are **22 / 30 / 38 dp**.
+
+**`allowCustom` is the one prop that changes meaning.** On the web it wires a
+hidden `<input type="color">` and the browser supplies the whole picker UI;
+RN has no such control, and an HSV picker is a component in its own right
+rather than a detail of this one. So the prop keeps its *visible* behaviour —
+the "+" button, and a `value` outside the palette shown as its own selected
+swatch — while the press is handed to a new **`onRequestCustom`** callback
+for your app to answer with whatever picker it has. The result round-trips
+through `value`/`onChange` exactly as before.
+
+The web's three `box-shadow` rings collapse into real box-model pieces, since
+RN gives a `View` one border: the resting `inset 0 0 0 1px` hairline becomes
+`borderWidth: 1`, the selected `inset 0 0 0 2px rgb(255 255 255 / .9)`
+becomes a 2 dp white border, and the outer `0 0 0 2px var(--swatch-color)`
+becomes a wrapper painted in the swatch color. That wrapper is **always**
+rendered with the same 2 dp padding and only changes color: a box-shadow ring
+costs no layout space on the web while a real padded wrapper does, so
+reserving it unconditionally is what keeps the row from reflowing as the
+selection moves.
+
+`filter: drop-shadow(...)` on the checkmark has no RN counterpart, so the
+path is drawn twice — a translucent black copy offset 1 dp down, then the
+white one on top. That's what the filter renders, and it's why it exists:
+without it the check disappears on the yellow swatch. The checkmark is
+hand-drawn with `react-native-svg` rather than taken from `@gnome-ui/icons`,
+mirroring the web version, which hand-draws it too — it's a stroked path, and
+`Icon`'s palette has no white to give it. The container is a `WrapBox`, and
+the "+" button's `border: 1.5px dashed` ports directly.
+
+### Bin
+
+```tsx
+import { Bin } from '@gnome-ui/react-native';
+
+<Bin style={{ maxWidth: 480 }}>
+  <ExpensiveChart data={series} />
+</Bin>
+```
+
+Single-child container with no visual styling — mirrors `AdwBin` and
+`@gnome-ui/react`'s own `Bin`. A transparent passthrough `View` forwarding
+every prop (and a ref to the underlying `View`) straight through, useful as
+a neutral base for custom components that need to apply layout or size
+constraints without introducing any chrome of their own. A plain RN `View`
+already has no default visual styling — no background, no border — so
+unlike the web port there's no CSS reset to strip; this is a pure
+passthrough.
+
 ## Installation
 
 ```bash