@gnome-ui/react-native 1.5.0 → 1.6.0

package/README.md

@@ -17,12 +17,15 @@ 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), 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
 > per-tier status against all 130 `@gnome-ui/react` components, and the
@@ -1430,6 +1433,441 @@ 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';

package/dist/components/AvatarRotator/AvatarRotator.d.ts

@@ -0,0 +1,65 @@
+import { StyleProp, ViewStyle } from 'react-native';
+import { AvatarColor, AvatarSize } from '../Avatar';
+export interface AvatarRotatorProps {
+    /** Full name used for the accessible label and initials fallback. */
+    name?: string;
+    /** Image URLs to rotate through. */
+    avatars?: string[];
+    /** Accessible label. Defaults to `name`. */
+    alt?: string;
+    /** Size of the avatar. Defaults to `"md"`. */
+    size?: AvatarSize;
+    /** Fallback initials color when no avatar image is available. */
+    color?: AvatarColor;
+    /** Time between avatar changes in milliseconds. Defaults to `3000`. */
+    interval?: number;
+    /** Crossfade duration in milliseconds. Defaults to `240`. */
+    transitionDuration?: number;
+    /** Pause automatic rotation while pressed and held. Defaults to `true`. */
+    pauseOnPress?: boolean;
+    /**
+     * Controlled active avatar index.
+     * When omitted the rotator manages index state internally.
+     */
+    activeIndex?: number;
+    /** Initial active avatar index for uncontrolled usage. Defaults to `0`. */
+    defaultActiveIndex?: number;
+    /** Called when the active avatar changes. */
+    onIndexChange?: (index: number) => void;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * 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`, layered
+ * via `StyleSheet.absoluteFill` and crossfaded with `Animated.timing` on
+ * `useNativeDriver: true` — an exact reproduction of the web version's
+ * stacked-`.layer`-elements-with-opacity-transition technique, just with
+ * `RotatorLayer` (see above) owning each layer's own `Animated.Value`
+ * instead of a single shared CSS custom property driving them all.
+ *
+ * **`prefers-reduced-motion` stops the rotation outright, not just the
+ * fade** — ported exactly: the web source's own auto-advance `useEffect`
+ * bails out early when reduced motion is on, the same as when paused, so
+ * this isn't merely an instant-swap-instead-of-crossfade case like
+ * `ProgressBar`'s determinate transitions.
+ *
+ * The web version's `pauseOnHover` (mouseEnter/mouseLeave, focus/blur)
+ * becomes `pauseOnPress` (`onPressIn`/`onPressOut`) — the same touch
+ * substitution `Toast`'s own press-and-hold pause already established,
+ * kept as a real toggleable prop here (unlike `Toast`, where the web
+ * source bakes the behavior in without an escape hatch).
+ * `usePrefersReducedMotion` (the web version's `@gnome-ui/hooks` import)
+ * has no bearing here — this package's own `useReducedMotion()` from
+ * `GnomeProvider` is the correct, already-established source for this.
+ *
+ * `role="img"` + `accessibilityLabel` ports 1:1 from RN's newer
+ * web-aligned `Role` union (the same `Avatar`/`AvatarGroup` precedent).
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Avatar.html
+ */
+export declare const AvatarRotator: ({ name, avatars, alt, size, color, interval, transitionDuration, pauseOnPress, activeIndex, defaultActiveIndex, onIndexChange, style, testID, }: AvatarRotatorProps) => import("react/jsx-runtime").JSX.Element;

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

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

package/dist/components/Box/Box.d.ts

@@ -0,0 +1,87 @@
+import { ReactNode } from 'react';
+import { StyleProp, View, ViewProps, ViewStyle } from 'react-native';
+/** GNOME HIG standard spacing values (matches `GtkBox` spacing tokens). */
+export type BoxSpacing = 3 | 6 | 12 | 18 | 24 | 32 | 48;
+/** Alias of `BoxSpacing` for use as a padding scale. */
+export type BoxPadding = BoxSpacing;
+export type BoxOrientation = 'horizontal' | 'vertical';
+export type BoxAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type BoxJustify = 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+export interface BoxProps extends Omit<ViewProps, 'style'> {
+    /**
+     * Direction children are arranged.
+     * `"vertical"` → `flexDirection: 'column'` (default).
+     * `"horizontal"` → `flexDirection: 'row'`.
+     */
+    orientation?: BoxOrientation;
+    /**
+     * Gap between children, in density-independent pixels.
+     * Accepts any of the GNOME HIG standard spacing values or any number.
+     * Defaults to `6` (the HIG "standard" inner spacing).
+     */
+    spacing?: BoxSpacing | number;
+    /**
+     * Cross-axis alignment (`alignItems`).
+     * Defaults to `"stretch"` for vertical, `"center"` for horizontal.
+     */
+    align?: BoxAlign;
+    /**
+     * Main-axis distribution (`justifyContent`).
+     * Defaults to `"start"`.
+     */
+    justify?: BoxJustify;
+    /** Inner padding applied to all sides, in density-independent pixels. */
+    padding?: BoxPadding | number;
+    children?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * 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 single row or column with consistent spacing
+ * following the GNOME Human Interface Guidelines spacing scale:
+ *
+ * | Token | dp | Use |
+ * |-------|----|-----|
+ * | tight | 3  | Dense UI, icon + label pairs |
+ * | standard | 6 | Default inner spacing |
+ * | medium | 12 | Between related groups |
+ * | large | 18 | Between loosely related sections |
+ * | section | 24 | Page-level section gaps |
+ * | loose | 32 | Large content separation |
+ * | jumbo | 48 | Hero / splash spacing |
+ *
+ * `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 passes
+ * straight through to CSS — are mapped 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; only the
+ * internal translation differs.
+ *
+ * `display: 'flex'` has no port and needs none — every RN `View` is already
+ * a flex container.
+ *
+ * @example
+ * // Vertical section (heading + content)
+ * <Box spacing={12}>
+ *   <Text variant="caption-heading" color="dim">Devices</Text>
+ *   <BoxedList>…</BoxedList>
+ * </Box>
+ *
+ * @example
+ * // Horizontal icon + label
+ * <Box orientation="horizontal" spacing={6} align="center">
+ *   <Icon icon={Folder} />
+ *   <Text>Documents</Text>
+ * </Box>
+ *
+ * @see https://developer.gnome.org/hig/guidelines/spacing.html
+ */
+export declare const Box: import('react').ForwardRefExoticComponent<BoxProps & import('react').RefAttributes<View>>;

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

@@ -0,0 +1,2 @@
+export type { BoxAlign, BoxJustify, BoxOrientation, BoxPadding, BoxProps, BoxSpacing, } from './Box';
+export { Box } from './Box';