@gnome-ui/react-native 1.4.0 → 1.6.0

package/README.md

@@ -17,10 +17,14 @@ 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` (Tier 20) also
+> and `Overlay`/`LevelBar`/`Expander`/`Divider`/`Highlight`/`FileTypeIcon`/
+> `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), and `PreferencesGroup` (Tier 13) also
 > shipped. Component ports from
 > `@gnome-ui/react` continue tier by tier — see this package's own
 > [ROADMAP.md](./ROADMAP.md) for full
@@ -1291,6 +1295,579 @@ dropped, not a behavior gap. `prefers-contrast: more`'s solid-background/
 white-text swap ports via `useResolvedContrast()`, the same hook `Button`
 already uses for its own high-contrast branching.
 
+### FileTypeIcon
+
+```tsx
+import { FileTypeIcon } from '@gnome-ui/react-native';
+
+<FileTypeIcon name="report.pdf" />
+<FileTypeIcon mimeType="image/png" />
+<FileTypeIcon name="cover.jpg" thumbnail={thumbnailUrl} />
+<FileTypeIcon isFolder />
+```
+
+Small icon — optionally a thumbnail — resolved from a file's MIME type or
+name extension. Useful for file-manager-style listings. Mirrors
+`@gnome-ui/react`'s `FileTypeIcon`, falling back to the generic file icon
+(freedesktop's `text-x-generic`) when the type can't be resolved.
+
+`fileType.ts`'s category-resolution logic (MIME type / extension → one of
+13 categories, plus the freedesktop icon and generated label per category)
+is pure, DOM-free TS — duplicated verbatim from `@gnome-ui/react` rather
+than imported cross-package, the same `Icon.tsx` precedent already
+established for logic that isn't worth a shared package for one file's
+worth of code. `role="img"` + `accessibilityLabel` ports 1:1, and the
+thumbnail reuses `Avatar`'s own `Image`/`resizeMode="cover"` recipe, sized
+from `Icon`'s own size map so swapping between the resolved icon and a
+thumbnail never shifts layout.
+
+### Chip
+
+```tsx
+import { Chip } from '@gnome-ui/react-native';
+
+<Chip label="React" />
+<Chip label="React" onRemove={() => {}} />
+<Chip label="React" selectable selected={selected} onToggle={() => setSelected((s) => !s)} />
+```
+
+Compact pill-shaped label for tags, filters, and selection states. Mirrors
+`@gnome-ui/react`'s `Chip`. Three usage modes: **static** (just a visual
+label), **removable** (add `onRemove` for a × button), and **selectable**
+(add `selectable` + `selected` + `onToggle` for toggle behavior — same
+`isInteractive = selectable && !onRemove` precedence as the web version,
+so passing both renders the remove button, not a toggle). Pair with
+`WrapBox` for multi-chip layouts.
+
+The selected background/border tint
+(`color-mix(in srgb, accent 15%/50%, transparent)`) resolves to a literal
+8-digit `#RRGGBBAA` hex, the same `Highlight` precedent. The web version's
+`:hover`/`:active` background transitions collapse into a single
+pressed-state overlay tinted by `theme.activeOverlay` (the same
+`ActionRow`/`Card` recipe), since touch has no hover. The leading icon and
+remove (×) icon stay in the default foreground color rather than tracking
+the selected accent text (`color: inherit` on the web) — RN's `Icon` has
+no `currentColor` equivalent and only accepts a fixed named-swatch
+palette, none of which tracks the app's configurable accent color, so
+this is a decorative nicety dropped, not a behavior gap.
+`accessibilityRole="checkbox"` on the selectable form ports 1:1, the same
+`Checkbox` precedent.
+
+### SegmentedBar
+
+```tsx
+import { SegmentedBar } from '@gnome-ui/react-native';
+
+<SegmentedBar
+  values={[
+    { label: 'TypeScript', value: 60, color: '#3178c6' },
+    { label: 'JavaScript', value: 30, color: '#f7df1e' },
+    { label: 'CSS',        value: 10, color: '#563d7c' },
+  ]}
+/>
+```
+
+Horizontal bar split into proportional segments, one per category. Mirrors
+`@gnome-ui/react`'s `SegmentedBar`. Typical use case: repository language
+distribution. Values are normalized proportionally when they don't sum to
+100.
+
+The web version's hover interaction (dim every segment but the one under
+the pointer, brighten that one via `filter: brightness()`) is rebuilt for
+touch rather than dropped: each segment is a `Pressable`, and touching one
+dims the rest immediately via `onPressIn`/`onPressOut` — deliberately not
+gated behind `Tooltip`'s own long-press delay, since this feedback is the
+RN analog of a `Pressable`'s own instant `pressed` state, not the "peek"
+affordance a tooltip reveal is. Each segment is also wrapped in `Tooltip`
+(`placement="top"`, `delay={200}`, ported 1:1) for the label/percentage
+readout — `Tooltip` clones its own handlers onto the child while still
+calling the child's original ones, so the dim/highlight and the tooltip
+compose cleanly on the same `Pressable`. `filter: brightness(1.15)` on the
+actively-touched segment has no RN equivalent — dropped as a decorative
+nicety, since the touched segment already reads as highlighted by
+contrast once every other segment dims to 35% opacity.
+
+### IconButton
+
+```tsx
+import { IconButton } from '@gnome-ui/react-native';
+import { Search } from '@gnome-ui/icons';
+
+<IconButton icon={Search} label="Search" />
+<IconButton icon={Search} label="Search" tooltip="Search files" />
+```
+
+Icon-only action button composed from `Button`, `Icon`, and optionally
+`Tooltip` — mirrors `@gnome-ui/react`'s `IconButton`, itself already just a
+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.
+
+### Drawer
+
+```tsx
+import { Drawer } from '@gnome-ui/react-native';
+
+<Drawer open={open} title="Details" onClose={() => setOpen(false)}>
+  <Text>Drawer content can be any React node passed as children.</Text>
+</Drawer>
+```
+
+Slide-in panel for supplementary content, anchored to the left or right
+edge. Mirrors `@gnome-ui/react`'s `Drawer`. Supports a `rail` (an
+`IconButton` strip on the drawer's inner edge for switching panels without
+closing it) and nested-drawer width auto-scaling via context — a `Drawer`
+opened from within another drawer's content automatically renders
+narrower (`0.85^depth`, floored at 240px), so stacked drawers read as a
+drill-in hierarchy.
+
+Floats with a margin on every side and all four corners rounded, matching
+`@gnome-ui/react`'s own recent CSS update to the same look — positioned
+within the padded backdrop via `justifyContent` rather than the web CSS's
+`margin: auto` on the drawer itself, since RN auto-margin support was
+unverified for this Yoga version (confirmed correct with an on-device
+debug-color check before trusting it; `BottomSheet` already proves the
+same `justifyContent: 'flex-end'` mechanism on its own vertical axis).
+Unlike `BottomSheet`, there's no drag-to-dismiss — the web source defines
+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.
+
 ## Installation
 
 ```bash

package/dist/components/AvatarGroup/AvatarGroup.d.ts

@@ -0,0 +1,47 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { AvatarColor, AvatarSize } from '../Avatar';
+export interface AvatarGroupItem {
+    name?: string;
+    src?: string;
+    alt?: string;
+    color?: AvatarColor;
+}
+export interface AvatarGroupProps {
+    avatars: AvatarGroupItem[];
+    /** Max visible avatars before showing the overflow chip. Defaults to `5`. */
+    max?: number;
+    /** Size applied to all avatars and the overflow chip. Defaults to `"md"`. */
+    size?: AvatarSize;
+    /** Accessible label for the group. Auto-generated from names when omitted. */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * 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 (`borderWidth: 2,
+ * borderColor: theme.windowBgColor`, 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 inner
+ * hairline is a decorative nicety, not a behavior gap. The overflow chip
+ * reuses `Avatar`'s own per-size box dimensions (`sm`/`md`/`lg`/`xl` →
+ * 24/32/48/64) so it lines up exactly with the avatars beside it.
+ *
+ * `role="group"` + `accessibilityLabel` ports 1:1 from RN's newer
+ * web-aligned `Role` union (the same `Avatar`/`Badge`/`LevelBar`
+ * precedent) — the label is auto-generated from `avatars[].name` (joined,
+ * plus "and N more" when overflowing) exactly like the web version, unless
+ * overridden. The overflow chip's `+N` text is hidden from the
+ * accessibility tree (`accessibilityElementsHidden`/
+ * `importantForAccessibility="no"`) in favor of the chip's own
+ * `accessibilityLabel="+N more"` — the same one-stop-not-two reasoning
+ * `SpinButton`/`Avatar` already established for a decorative inner glyph.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Avatar.html
+ */
+export declare const AvatarGroup: ({ avatars, max, size, accessibilityLabel, style, testID, }: AvatarGroupProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { AvatarGroupItem, AvatarGroupProps } from './AvatarGroup';
+export { AvatarGroup } from './AvatarGroup';