@gnome-ui/react-native 1.3.0 → 1.5.0

package/README.md

@@ -18,10 +18,16 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > `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
-> Advanced Controls in progress: `Dropdown` and `Slider` shipped —
-> `Spin Button`, `Avatar`, `Badge`, and `Popover` remain. Component
-> ports from `@gnome-ui/react` continue tier by tier. See
-> [ROADMAP.md](../../ROADMAP.md) Priority 3.
+> 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
+> `@gnome-ui/react` continue tier by tier — see this package's own
+> [ROADMAP.md](./ROADMAP.md) for full
+> per-tier status against all 130 `@gnome-ui/react` components, and the
+> main [ROADMAP.md](../../ROADMAP.md) Priority 3 for the framework
+> expansion this package belongs to.
 
 ## How it works
 
@@ -971,6 +977,459 @@ width isn't a known constant: a zero-width `View` with
 `Text` child around that point regardless of how wide the label renders,
 with no measurement needed.
 
+### SpinButton
+
+```tsx
+import { SpinButton } from '@gnome-ui/react-native';
+
+<SpinButton value={quantity} onChange={setQuantity} min={0} max={10} accessibilityLabel="Quantity" />;
+```
+
+Numeric −/+ stepper following the Adwaita `GtkSpinButton` pattern, mirroring
+`@gnome-ui/react`'s `SpinButton`. The `min`/`max`/`step`/`decimals`/`wrap`/
+`format` clamp-and-format math ports verbatim (pure JS, no DOM involved).
+
+The primary interaction is tapping the visible −/+ buttons, same as a
+sighted mouse user on the web version. The web version's keyboard
+interaction (↑/↓ one step, Page Up/Down ten steps, Home/End to bounds) has
+no RN equivalent — a touch-first device has no keyboard to drive it, the
+same reasoning `Slider` already applied. Rather than dropping value
+adjustment accessibility entirely, single-step increment/decrement reuses
+`Slider`'s exact `accessibilityRole="adjustable"` +
+`onAccessibilityAction`/`accessibilityActions` recipe (VoiceOver's
+swipe-up/down, TalkBack's local-context menu) — the bigger Page Up/Down and
+Home/End jumps have no equivalent screen-reader gesture on either platform,
+so those alone are dropped, same as `Slider`. The visible −/+ buttons and
+value text are hidden from the accessibility tree
+(`accessibilityElementsHidden`/`importantForAccessibility="no"`, mirroring
+the web version's `aria-hidden`/`tabIndex={-1}` on both `<button>`s and the
+value `<span>`) so a screen reader user gets one adjustable stop, not three.
+
+### Avatar
+
+```tsx
+import { Avatar } from '@gnome-ui/react-native';
+
+<Avatar name="Grace Hopper" size="lg" />
+<Avatar src="https://example.com/alice.jpg" alt="Alice's profile photo" />;
+```
+
+Circular avatar with image or initials fallback, mirroring `@gnome-ui/react`'s
+`Avatar`. The color-hash and initials-extraction math ports verbatim (pure
+JS, no DOM involved).
+
+The outer container carries `role="img"` + `accessibilityLabel` — RN's newer
+web-aligned `Role` union has an `"img"` value, a direct 1:1 port of the web
+version's `role="img"`, no substitution needed (same as `ProgressBar`'s
+`role="progressbar"`). The image/initials underneath are hidden from the
+accessibility tree, mirroring the web version's `aria-hidden` on both, so a
+screen reader gets one stop, not two — same reasoning as `SpinButton`'s
+hidden −/+ buttons.
+
+The web CSS's `box-shadow: inset 0 0 0 1px …` ring becomes a real 1px
+`borderWidth`/`borderColor` here (RN has no inset shadow) — the same
+substitution `Slider`'s thumb border already used for a ring effect.
+
+### Badge
+
+```tsx
+import { Avatar, Badge } from '@gnome-ui/react-native';
+
+<Badge variant="error" anchor={<Avatar name="Alice Bob" />}>3</Badge>
+<Badge dot variant="success" />;
+```
+
+Counter or status indicator, optionally overlaid on another element,
+mirroring `@gnome-ui/react`'s `Badge`. `children` renders as a themed `Text`
+label when it's a string or number (the common case — counts and short
+text); any other node renders as-is, the same convention `Button`'s
+`children` already established.
+
+The web CSS's `box-shadow: 0 0 0 2px var(--gnome-window-bg-color)` ring
+(always present, separating the badge from whatever's behind it) has no RN
+equivalent that avoids affecting layout — RN's `border*` shrinks the content
+box instead of drawing outside it. Reproduced instead with an outer wrapping
+`View` (2px padding, `theme.windowBgColor` background, pill radius) around
+the actual colored badge, so the ring appears to spread outward exactly like
+the web version's non-blurred shadow, without eating into the badge's own
+text padding.
+
+### Popover
+
+```tsx
+import { Button, Popover, Text } from '@gnome-ui/react-native';
+
+<Popover content={<Text>Rich content here</Text>}>
+  <Button>Open</Button>
+</Popover>;
+```
+
+Floating panel anchored to a trigger element, following the Adwaita
+`GtkPopover` pattern, mirroring `@gnome-ui/react`'s `Popover`. Unlike
+`Tooltip`, it can hold rich interactive content (buttons, links, forms).
+
+Reuses this package's own established pieces rather than re-deriving them:
+`Tooltip`'s `cloneElement`-onto-an-arbitrary-trigger architecture and
+4-placement fallback-cascade positioning (no arrow-offset-shift-when-clamped
+— same simplification `Tooltip` already accepted), and `Dropdown`'s
+toggle-on-press + full-screen backdrop `Pressable` that closes on an outside
+tap plus reduced-motion fade-in.
+
+**Deliberate divergence from `Dropdown`'s backdrop structure**: `Dropdown`
+nests its panel directly inside the backdrop `Pressable` and gets away with
+it because almost every pixel of its panel is itself a `Pressable` option
+row, which claims the touch responder before it can bubble to the backdrop.
+A popover's `content` is arbitrary — likely to have inert padding/whitespace
+with no `Pressable` of its own — so nesting the same way would let a tap on
+inert panel space fall through to the backdrop and close the popover, unlike
+the web version's `.contains()` check (which never closes on *any* tap
+inside the panel). Fixed with `onStartShouldSetResponder={() => true}` on
+the panel itself: it claims the touch responder for any touch RN's
+negotiation hasn't already given to a deeper `Pressable` inside `content`,
+without making the panel itself behave like a button.
+
+`BackHandler`'s `hardwareBackPress` (wired the same way `Dialog` already
+does) is the Android analog of the web version's document-level Escape
+listener. Focus-trapping and focus-restore-on-close have no port — no DOM
+`document.activeElement`/`querySelector` equivalent exists in RN, the same
+gap already present in `Dialog`/`Tooltip`/`Dropdown`.
+
+The web version's rotated-square-with-matching-background arrow is replaced
+with `Tooltip`'s simpler transparent-border-triangle technique — the same
+visual affordance, a much simpler RN-native primitive.
+
+### BottomSheet
+
+```tsx
+import { BottomSheet, Button } from '@gnome-ui/react-native';
+
+<Button onPress={() => setOpen(true)}>Open</Button>
+<BottomSheet open={open} title="Options" onClose={() => setOpen(false)}>
+  <Text>Rich content here</Text>
+</BottomSheet>;
+```
+
+Slide-up panel that overlays content from the bottom edge, mirroring
+`AdwBottomSheet` (libadwaita 1.6+) and `@gnome-ui/react`'s `BottomSheet`.
+Reuses `Dialog`'s backdrop-opacity-on-an-`AnimatedPressable` +
+no-op-`Pressable`-around-the-card recipe, and `BackHandler`'s
+`hardwareBackPress` as the Android analog of the web version's Escape
+listener.
+
+**Real drag-to-dismiss**, not a fixed-panel simplification: `PanResponder`
+(the same core API `Slider` already proved handles a threshold gesture)
+drives a single `Animated.Value` shared with the entrance/exit animation —
+dragging the handle bar past 150 px (same constant as the web version)
+requests a close; releasing short of that springs back to `0`. A real
+slide-up needs the sheet's own height first (RN's `transform` has no
+percentage-of-self units, the same `Slider`/`Avatar` pitfall) — the sheet
+renders once off-screen, measured via `onLayout`, before animating in.
+
+**A real, timed exit animation, unlike `Dialog`**: `Dialog`'s web source has
+no exit keyframes at all, but `BottomSheet`'s does — ported with a local
+`visible` state that lags one animation behind the `open` prop, flipping to
+`false` only in the exit `Animated.timing`'s own completion callback.
+
+The web version's `backdrop-filter: blur(4px)` has no port (no native blur
+view dependency, same reasoning that dropped `Sidebar`'s blurred variant),
+and `useBodyScrollLock` needs no RN equivalent (`Modal` already blocks all
+background interaction). `children`, when a plain string, is wrapped in
+`Text` before rendering — RN throws if a raw string is a `View`'s child,
+unlike the web version's plain `<div>{children}</div>`.
+
+### Overlay
+
+```tsx
+import { Overlay, Button } from '@gnome-ui/react-native';
+
+<Button onPress={() => setOpen(true)}>Open</Button>
+<Overlay open={open} onDismiss={() => setOpen(false)}>
+  <YourOwnCard />
+</Overlay>;
+```
+
+Standalone backdrop/scrim layer with a fade transition and
+press-to-dismiss — the shared building block behind `Dialog`, `Dropdown`,
+`Popover`, and `BottomSheet`'s own backdrops, extracted here for building
+custom overlay UI, mirroring `@gnome-ui/react`'s `Overlay`.
+
+Deliberately minimal, same as the web version: no focus trap, no
+`BackHandler`/Escape handling, no `role` — use `Dialog`/`Popover`/
+`BottomSheet` directly when you need those. Reuses `Dialog`'s exact
+backdrop recipe (`AnimatedPressable` + a no-op `Pressable` wrapping
+`children`, so a tap on your own content never bubbles to the backdrop and
+dismisses it) and `BottomSheet`'s real, timed exit animation technique — a
+local `visible` state that lags the `open` prop by one `Animated.timing`,
+flipping to `false` only in that animation's own completion callback.
+
+**Not retrofitted into `Dialog`/`Dropdown`/`Popover`/`BottomSheet`** — each
+already ships and is fully tested with its own inline copy of this same
+backdrop pattern (with small per-component differences: `Popover` claims
+the touch responder differently than the no-op-`Pressable` wrapper the
+others use). Extracting `Overlay` as a new standalone primitive was the
+scoped ask; retrofitting four already-shipped components to share it is a
+separate, riskier refactor this turn didn't take on.
+
+### LevelBar
+
+```tsx
+import { LevelBar } from '@gnome-ui/react-native';
+
+<LevelBar value={0.15} low={0.25} high={0.75} accessibilityLabel="Battery" />
+<LevelBar value={0.6} discrete numBlocks={5} accessibilityLabel="Signal strength" />;
+```
+
+Discrete level indicator with color-coded low/high offset zones, mirroring
+`GtkLevelBar` and `@gnome-ui/react`'s `LevelBar`. Use for a gauge/
+measurement display (disk usage, battery, signal strength) — not for task
+progress (`ProgressBar`) or a proportional category breakdown
+(`SegmentedBar`).
+
+The continuous fill reuses `ProgressBar`'s exact animation technique rather
+than animating `width` directly: a fixed `width: '100%'` fill with
+`transformOrigin: 'left'` and an animated `transform: [{ scaleX }]`, so the
+whole thing runs on `useNativeDriver: true` — a JS-driven `width` animation
+schedules its next frame via a plain `setTimeout` that routinely fires
+after a test's `render()` returns but before unmount, producing a spurious
+"update not wrapped in act()" warning, the same reasoning `ProgressBar`'s
+own docstring documents. `useReducedMotion()` mirrors `ProgressBar`'s
+determinate behavior (duration drops to `0`, an immediate jump).
+
+Discrete mode's per-block color transition has no port — a value change is
+a plain, unanimated color swap per block, a decorative nicety rather than a
+behavior gap. `role="meter"` ports 1:1 from RN's newer web-aligned `Role`
+union (unlike `AccessibilityRole`, which has no `"meter"` value at all).
+
+### Expander
+
+```tsx
+import { Expander } from '@gnome-ui/react-native';
+
+<Expander label="Show advanced options">
+  <TextField label="Custom endpoint" />
+</Expander>
+```
+
+Standalone disclosure triangle + collapsible content, mirroring `GtkExpander`
+and `@gnome-ui/react`'s `Expander`. A bare, unstyled counterpart to
+`ExpanderRow`; use it outside a settings-row context (e.g. "Show advanced
+options" in a form, or "Show details" under an error message).
+
+The web version clips the panel with a CSS grid-height animation and rides
+the content's `padding-top` on a second, separate transition, so a collapsed
+expander doesn't reserve blank space for hidden padding. RN has no CSS grid
+to lean on, so the panel is a single `Animated.View` whose numeric `height`
+is driven directly (`useNativeDriver: false`, the same accepted trade-off
+`Checkbox`/`RadioButton`/`Switch`/`AnimatedIcon` already make for
+non-transform properties) — since the content's own `onLayout` measurement
+already includes its `paddingTop`, one animated height reproduces the web
+version's two-transition result. Content stays mounted while collapsed
+(`accessibilityElementsHidden`/`importantForAccessibility="no"`, the same
+substitution for the web's `inert` used elsewhere in this package), and on
+first mount with `defaultExpanded` the panel briefly renders at its natural,
+unmeasured height so the initial reveal doesn't pop once layout resolves.
+
+The chevron is `PanEnd` (GNOME's own `pan-end-symbolic` disclosure triangle)
+rotating 0deg → 90deg on an `Animated.Value`, the same `interpolate`-to-
+`rotate` recipe `Spinner` uses for its own spin.
+
+### Divider
+
+```tsx
+import { Divider } from '@gnome-ui/react-native';
+
+<Divider>OR</Divider>
+<Divider>Continue with</Divider>
+<Divider />
+```
+
+Horizontal rule with an optional centered label — the common auth/login-form
+pattern ("Sign in" / **OR** / "Continue with Google"). Mirrors
+`@gnome-ui/react`'s `Divider`. For a bare dividing line with no label, use
+`Separator` instead — it also supports a vertical orientation, which
+`Divider` does not.
+
+`role="separator"` ports 1:1 from RN's newer web-aligned `Role` union (the
+same one `Avatar`/`Badge`/`LevelBar` already reach for) — unlike
+`Separator`'s own `accessible={false}`, since a labelled `Divider` ("OR") is
+exactly the kind of content a screen reader user needs read aloud, rather
+than a purely decorative line. The label reuses `Text`'s
+`variant="caption" color="dim"` verbatim, which already resolves to the same
+font-size/weight/dim-opacity the web version's `.label` class hard-codes.
+
+### Highlight
+
+```tsx
+import { Highlight } from '@gnome-ui/react-native';
+
+<Highlight text="Preferences for accessibility" query="access" />
+<Highlight text="The quick brown fox" query={['quick', 'fox']} />
+```
+
+Wraps every occurrence of `query` within `text` in a highlighted inline run
+— mirrors `@gnome-ui/react`'s `Highlight`, which wraps matches in a `<mark>`.
+Pairs with `SearchBar`'s suggestion list and any filterable list to show
+users which part of a result matched what they typed.
+
+The outer span is the themed `Text` component (so callers get the same
+`variant`/`color` API as everywhere else), but each matched run is a plain,
+unthemed RN `Text` carrying only the highlight's own overrides — RN's `Text`
+is the one primitive that inherits ambient `fontSize`/`color`/`fontFamily`
+from a parent `Text` when nested, the same way the web version's `<mark>`
+inherits from its surrounding text and only overrides
+`background-color`/`font-weight`. Reaching for the themed `Text` for the
+marked runs too would reset them to its own default `variant="body"` sizing
+instead of inheriting whatever variant the caller chose for the whole
+string.
+
+The web version's translucent `color-mix(in srgb, accent 30%, transparent)`
+background has no RN equivalent (`color-mix` is CSS-only) — resolved to a
+literal 8-digit `#RRGGBBAA` hex instead, since `accentBgColor` is always a
+plain 6-digit hex across all four theme variants. `border-radius` on the
+`<mark>` has no reliable port either: RN only paints `backgroundColor` on an
+inline (nested) `Text` run, not `borderRadius` — a decorative nicety
+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).
+
 ## Installation
 
 ```bash

package/dist/components/Avatar/Avatar.d.ts

@@ -0,0 +1,53 @@
+import { StyleProp, ViewStyle } from 'react-native';
+export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Named color palette for the initials fallback.
+ * Mirrors libadwaita's avatar color set.
+ */
+export type AvatarColor = 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'purple' | 'brown' | 'teal' | 'slate';
+export interface AvatarProps {
+    /**
+     * Full name used to generate initials and — when `color` is omitted —
+     * to deterministically pick a background color.
+     */
+    name?: string;
+    /** Image URL. When provided the initials fallback is hidden. */
+    src?: string;
+    /** Accessible label. Defaults to `name`, then `"Avatar"`. */
+    alt?: string;
+    /** Size of the avatar. Defaults to `"md"`. */
+    size?: AvatarSize;
+    /**
+     * Override the auto-derived background color for the initials fallback.
+     * When omitted a color is derived from `name` via a stable hash.
+     */
+    color?: AvatarColor;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Circular avatar with image or initials fallback.
+ *
+ * Follows the Adwaita `AdwAvatar` pattern — deterministic color from name,
+ * up to two initials when no image is supplied. Rebuilt with `View`/`Image`/
+ * `Text` rather than ported from `@gnome-ui/react`'s DOM-based JSX, but
+ * mirrors its prop API and color-hash/initials math (pure JS, ported
+ * verbatim).
+ *
+ * The outer container carries `role="img"` + `accessibilityLabel` — RN's
+ * newer web-aligned `Role` union has an `"img"` value, a direct 1:1 port of
+ * the web version's `role="img"`, no substitution needed (same as
+ * `ProgressBar`'s `role="progressbar"`). The image/initials underneath are
+ * hidden from the accessibility tree
+ * (`accessibilityElementsHidden`/`importantForAccessibility="no"`, mirroring
+ * the web version's `aria-hidden` on both), so a screen reader gets one
+ * stop, not two — same reasoning as `SpinButton`'s hidden −/+ buttons.
+ *
+ * The web CSS's `box-shadow: inset 0 0 0 1px …` ring (drawn on top, doesn't
+ * affect layout) becomes a real 1px `borderWidth`/`borderColor` here (RN has
+ * no inset shadow) — the same substitution `Slider`'s thumb border already
+ * used for a ring effect, at the cost of a negligible 1px content-box inset
+ * the web version doesn't have.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Avatar.html
+ */
+export declare const Avatar: ({ name, src, alt, size, color, style }: AvatarProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { AvatarColor, AvatarProps, AvatarSize } from './Avatar';
+export { Avatar } from './Avatar';

package/dist/components/Badge/Badge.d.ts

@@ -0,0 +1,48 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export type BadgeVariant = 'accent' | 'success' | 'warning' | 'error' | 'neutral';
+export interface BadgeProps {
+    /**
+     * Visual style. Defaults to `"accent"`.
+     * - `accent`  — blue, for counts and highlights.
+     * - `success` — green, for positive status.
+     * - `warning` — yellow, for cautionary status.
+     * - `error`   — red, for failures or urgent counts.
+     * - `neutral` — gray, for inactive or secondary counts.
+     */
+    variant?: BadgeVariant;
+    /**
+     * When true, renders a small dot with no label — used for unread/online indicators.
+     * The `children` are ignored in dot mode.
+     */
+    dot?: boolean;
+    /** Number or short text to display. Keep to 1–3 characters. String/number render as a themed label; other nodes render as-is. */
+    children?: ReactNode;
+    /**
+     * When provided, the badge is positioned over this child element at the
+     * top-right corner.
+     */
+    anchor?: ReactNode;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Counter or status indicator, optionally overlaid on another element.
+ *
+ * Rebuilt with `View`/`Text` rather than ported from `@gnome-ui/react`'s
+ * DOM-based JSX, but mirrors its prop API. `children` renders as a themed
+ * `Text` label when it's a string or number (the common case — counts and
+ * short text); any other node renders as-is, the same convention `Button`'s
+ * `children` already established.
+ *
+ * The web CSS's `box-shadow: 0 0 0 2px var(--gnome-window-bg-color)` ring
+ * (always present, separating the badge from whatever's behind it) has no
+ * RN equivalent that avoids affecting layout — RN's `border*` shrinks the
+ * content box instead of drawing outside it. Reproduced instead with an
+ * outer wrapping `View` (2px padding, `theme.windowBgColor` background,
+ * pill radius) around the actual colored badge, so the ring appears to
+ * spread outward exactly like the web version's non-blurred shadow, without
+ * eating into the badge's own text padding.
+ *
+ * @see https://developer.gnome.org/hig/patterns/feedback/badges.html
+ */
+export declare const Badge: ({ variant, dot, children, anchor, style }: BadgeProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { BadgeProps, BadgeVariant } from './Badge';
+export { Badge } from './Badge';