@gnome-ui/react-native 1.1.0 → 1.2.0

package/README.md

@@ -14,9 +14,12 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > `Link`, `TextField`, `Switch`, `Checkbox`, `RadioButton`), Tier 2 Layout &
 > Containers (`Separator`, `Card`, `BoxedList`, `ActionRow`, `HeaderBar`),
 > and Tier 3 Navigation (`Tabs`, `ViewSwitcher`, `Sidebar`, `SearchBar`,
-> `PathBar`) fully ported. Tier 4 Feedback in progress: `Spinner`,
-> `ProgressBar`, `Skeleton`, `Toast`/`Toaster`, `Banner`, and `Dialog`
-> shipped — `Tooltip`, `Status Page`, and `AnimatedIcon` remain. Component
+> `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
+> Advanced Controls in progress: `Dropdown` shipped — `Slider`,
+> `Spin Button`, `Avatar`, `Badge`, and `Popover` remain. Component
 > ports from `@gnome-ui/react` continue tier by tier. See
 > [ROADMAP.md](../../ROADMAP.md) Priority 3.
 
@@ -790,12 +793,147 @@ consistency with the established pattern, but this is the component where
 that tradeoff matters most — worth prioritizing for real-device screen
 reader verification before it's treated as settled.
 
+### Tooltip
+
+```tsx
+import { Button, Tooltip } from '@gnome-ui/react-native';
+
+<Tooltip label="Save file" placement="top">
+  <Button accessibilityLabel="Save">Save</Button>
+</Tooltip>;
+```
+
+Floating informational label. Positioned automatically and flips to the
+opposite side (then to whichever side actually fits) when the preferred
+placement has no room — the same algorithm as `@gnome-ui/react`'s
+`Tooltip`, measured with `measureInWindow()` instead of
+`getBoundingClientRect()`.
+
+**Trigger differs from the web version by necessity**: the web `Tooltip`
+only shows on mouse hover / keyboard focus — touch has no hover state, so
+it explicitly never shows on touch. RN is touch-first, so the primary
+trigger here is **long-press** (`delayLongPress={delay}`, released via
+`onPressOut`) — the standard mobile "peek" idiom. `onHoverIn`/`onHoverOut`
+are also wired for hover-capable input (trackpad/mouse on iPad, or a
+pointer-driven RN target) and `onFocus`/`onBlur` for external-keyboard
+accessibility, both delayed the same way the web version delays hover.
+
+Built on RN's own `Modal` (transparent, `pointerEvents="box-none"`), the
+same portal-substitute `Dialog` uses. `role="tooltip"` ports 1:1 — RN's
+`Role` union already has a `"tooltip"` value. `aria-describedby` has no RN
+equivalent, so the label is set as the trigger's `accessibilityHint`
+instead (unless the trigger already provides its own). The bubble's arrow
+reuses the same zero-size / transparent-border-on-three-sides triangle
+trick as the web CSS — RN `View`s support per-side `border*Color` too, the
+same technique `Spinner`'s ring already relies on.
+
+Not ported: repositioning on scroll/resize while visible (RN has no global
+scroll event, and a long-press is naturally cancelled by a scroll gesture
+starting). `tooltipBgColor`/`tooltipFgColor` aren't real `@gnome-ui/core`
+tokens (only CSS var fallbacks), so the RN port hardcodes the same literal
+light/dark values, the same workaround `Spinner`'s track color established.
+
+### Icon
+
+```tsx
+import { Search } from '@gnome-ui/icons';
+import { Icon } from '@gnome-ui/react-native';
+
+<Icon icon={Search} label="Search" size="lg" color="blue" />;
+```
+
+Renders an icon as an inline SVG via `react-native-svg` (a new peer
+dependency — this package's first). Accepts the same `AnyIconDefinition`
+union as `@gnome-ui/react`'s `Icon`: a structured `paths`-based
+`IconDefinition` from `@gnome-ui/icons`, a `simple-icons` `SimpleIcon`, or a
+plain `{ path }` object. `color` picks a named GNOME palette hue
+(`theme.blue3`, `theme.red3`, …) — RN has no `currentColor` to inherit from
+a parent the way the web version does, so omitting `color` resolves to the
+theme's default foreground color explicitly instead.
+
+`animated` icons (`Syncing`, `Recording`, `Downloading`, `Connecting`) carry
+raw `svg` markup instead of `paths` — rendered here through `react-native-
+svg`'s `SvgXml`. It parses the structural elements (`<g>`/`<path>`/
+`<circle>`) but has no CSS engine, so the markup's embedded `<style>`/
+`@keyframes` block is silently dropped and the shapes render at their
+authored rest position — which happens to be exactly the desired inert,
+static-frame behavior for a plain `<Icon>`, no special-casing needed. Wrap
+in `<AnimatedIcon>` to actually play the motion.
+
+### AnimatedIcon
+
+```tsx
+import { Syncing } from '@gnome-ui/icons';
+import { AnimatedIcon } from '@gnome-ui/react-native';
+
+<AnimatedIcon icon={Syncing} playing={isSyncing} label="Syncing" />;
+```
+
+Plays the motion for a known `animated` icon (`Syncing`, `Recording`,
+`Downloading`, `Connecting`) — rendered through plain `<Icon>`, these show a
+static frame instead, same as `@gnome-ui/react`'s `AnimatedIcon`.
+
+Unlike the web version (which plays a CSS animation embedded in the icon's
+raw `svg` markup via a `--gnome-icon-play-state` custom property), RN has
+no CSS engine to interpret `@keyframes` at all. Each of the 4 known icons'
+motion is instead hand-built with `Animated`, matched by referential
+identity against `@gnome-ui/icons`' own exports (`Syncing` → full-turn
+rotation, `Recording` → opacity pulse, `Downloading` → a translate+opacity
+"drop" on the arrow over a static tray, `Connecting` → three signal dots
+pulsing in a staggered sweep) — an icon `AnimatedIcon` doesn't recognize
+(a future 5th animated icon, or a consumer-authored one) falls back to the
+static `<Icon>` frame rather than throwing. Regardless of `playing`, the
+animation is always paused when the OS reduced-motion setting is on.
+
+### Dropdown
+
+```tsx
+import { Dropdown } from '@gnome-ui/react-native';
+
+<Dropdown
+  options={[
+    { value: 'blue', label: 'Blue' },
+    { value: 'green', label: 'Green', description: 'A calm accent' },
+  ]}
+  value={accentColor}
+  onChange={setAccentColor}
+  placeholder="Accent color"
+/>;
+```
+
+Expandable option list following the Adwaita combo-row pattern, mirroring
+`@gnome-ui/react`'s `Dropdown`.
+
+Built on RN's own `Modal` (transparent) — the same portal-substitute
+`Dialog`/`Tooltip` already use — with a full-screen backdrop `Pressable`
+that closes the list on an outside tap (the RN analog of the web version's
+document-level "click outside" listener; unlike `Tooltip`'s backdrop, this
+one isn't `pointerEvents="box-none"`, since it's meant to catch that tap
+rather than pass it through). `open` flips synchronously on trigger press;
+the trigger's on-screen rect and the panel's own rendered height each
+resolve independently into state, combined by a separate effect into the
+final position and flip-up/flip-down direction — the same two-independent-
+async-measurements pattern `Tooltip` established.
+
+Keyboard navigation (↑/↓ roving highlight, Home/End, type-ahead) has no
+port — RN's touch-first model has no keyboard focus to drive it, the same
+reasoning that already dropped `TabBar`'s roving-tabindex arrow keys.
+Selection is by direct tap only. `role="combobox"` on the trigger ports
+1:1; RN's `Role` union has no `"listbox"` value, so the panel uses
+`role="list"` instead — the same closest-available substitution `BoxedList`
+already established for a plain list container.
+
 ## Installation
 
 ```bash
-npm install @gnome-ui/react-native react-native
+npm install @gnome-ui/react-native react-native react-native-svg
 ```
 
+`react-native-svg` is a peer dependency, only needed for `Icon`/
+`AnimatedIcon` — it ships as one of Expo Go's included native modules, so
+Expo projects on `npx expo install react-native-svg` need no extra native
+build step; bare RN projects need it linked as usual for a native module.
+
 ## Example app
 
 [`apps/react-native-example`](../../apps/react-native-example) is a

package/dist/components/AnimatedIcon/AnimatedIcon.d.ts

@@ -0,0 +1,38 @@
+import { IconDefinition } from '@gnome-ui/icons';
+import { IconProps } from '../Icon';
+export interface AnimatedIconProps extends Omit<IconProps, 'icon'> {
+    /** Animated icon from `@gnome-ui/icons` (`animated: true` — `Syncing`, `Recording`, `Downloading`, `Connecting`). */
+    icon: IconDefinition;
+    /**
+     * Whether the animation plays. Defaults to `true`.
+     *
+     * Regardless of this prop, the animation is always paused when the OS
+     * reduced-motion setting is on — callers don't need to check
+     * `useReducedMotion()` themselves.
+     */
+    playing?: boolean;
+}
+/**
+ * Plays the motion for a known `animated` icon from `@gnome-ui/icons`
+ * (`Syncing`, `Recording`, `Downloading`, `Connecting`) — rendered through
+ * plain `<Icon>`, these show a static frame instead.
+ *
+ * Unlike `@gnome-ui/react`'s `AnimatedIcon` (which plays a CSS animation
+ * embedded in the icon's raw `svg` markup via a `--gnome-icon-play-state`
+ * custom property), RN has no CSS engine to interpret `@keyframes` at all —
+ * `<Icon>` already drops the `<style>` block silently (see its own doc
+ * comment), and this component instead hand-builds each of the 4 known
+ * icons' exact motion with `Animated`, matched against `RECIPES` by
+ * reference. When playing and reduced motion is off, it renders its own
+ * `<Svg>` with the matching `*Motion` recipe as children; otherwise (not
+ * playing, reduced motion on, or an icon `RECIPES` doesn't recognize) it
+ * defers straight to `<Icon>`.
+ *
+ * Useful for progress, sync, recording, download, and connection states, or
+ * cross-fading between icons by swapping `icon` while `playing` stays true.
+ *
+ * @example
+ * import { Syncing } from "@gnome-ui/icons";
+ * <AnimatedIcon icon={Syncing} playing={isSyncing} label="Syncing" />
+ */
+export declare const AnimatedIcon: ({ icon, playing, size, width, height, label, color, }: AnimatedIconProps) => import("react/jsx-runtime").JSX.Element;

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

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

package/dist/components/Dropdown/Dropdown.d.ts

@@ -0,0 +1,56 @@
+import { StyleProp, ViewStyle } from 'react-native';
+export interface DropdownOption<V extends string = string> {
+    /** The value submitted / returned on selection. */
+    value: V;
+    /** Display label shown in the list and trigger. */
+    label: string;
+    /** Optional descriptive text shown below the label. */
+    description?: string;
+    /** Whether the option is selectable. */
+    disabled?: boolean;
+}
+export interface DropdownProps<V extends string = string> {
+    /** The list of selectable options. */
+    options: DropdownOption<V>[];
+    /** The currently selected value. */
+    value?: V;
+    /** Called when the user selects an option. */
+    onChange?: (value: V) => void;
+    /** Placeholder shown when no option is selected. */
+    placeholder?: string;
+    /** Accessible label for the control. */
+    accessibilityLabel?: string;
+    /** Disables the entire control. */
+    disabled?: boolean;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Expandable option list following the Adwaita combo-row / drop-down
+ * pattern, mirroring `@gnome-ui/react`'s `Dropdown`.
+ *
+ * Built on RN's own `Modal` (transparent) — the same portal-substitute
+ * `Dialog`/`Tooltip` already use — with a full-screen backdrop `Pressable`
+ * (not `pointerEvents="box-none"` like `Tooltip`'s: unlike a tooltip, this
+ * panel is meant to catch and close on an outside tap, the RN analog of the
+ * web version's document-level "click outside" listener). `open` flips
+ * synchronously on trigger press; the trigger's on-screen rect
+ * (`measureInWindow`) and the panel's own rendered height (`onLayout`) each
+ * resolve independently into state, combined by a separate effect into the
+ * final `top`/`left`/`width`/`flipUp` — the same two-independent-
+ * async-measurements pattern `Tooltip` established (and for the same
+ * reason: gating `open` itself on the native measurement callback would
+ * make the component untestable in this package's Jest environment, where
+ * `measureInWindow` never calls back).
+ *
+ * Keyboard navigation (↑/↓ roving highlight, Home/End, type-ahead) has no
+ * port — RN's touch-first model has no keyboard focus to drive it, the
+ * same reasoning that already dropped `TabBar`'s roving-tabindex arrow
+ * keys. Selection is by direct tap only.
+ *
+ * `role="combobox"` on the trigger ports 1:1. RN's `Role` union has no
+ * `"listbox"` value (unlike `"option"`, which does exist) — the panel uses
+ * `role="list"` instead, the same closest-available substitution `BoxedList`
+ * already established for a plain list container.
+ */
+export declare const Dropdown: <V extends string = string>({ options, value, onChange, placeholder, accessibilityLabel, disabled, style, testID, }: DropdownProps<V>) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { DropdownOption, DropdownProps } from './Dropdown';
+export { Dropdown } from './Dropdown';

package/dist/components/Icon/Icon.d.ts

@@ -0,0 +1,56 @@
+import { AnyIconDefinition } from '@gnome-ui/icons';
+import { StyleProp, ViewStyle } from 'react-native';
+export type IconSize = 'sm' | 'md' | 'lg';
+/** Named GNOME palette color for the icon. `"default"` (or omitting the prop) resolves to the theme's default foreground color. */
+export type IconColor = 'default' | 'blue' | 'green' | 'yellow' | 'orange' | 'red' | 'purple' | 'brown';
+export interface IconProps {
+    /** Icon from `@gnome-ui/icons`, a `simple-icons` icon, or a raw `{ path }` object. */
+    icon: AnyIconDefinition;
+    /**
+     * Rendered size.
+     * - `sm` — 12 px
+     * - `md` — 16 px (default)
+     * - `lg` — 20 px
+     *
+     * Override with `width`/`height` for non-standard sizes.
+     */
+    size?: IconSize;
+    width?: number;
+    height?: number;
+    /** Accessible label. Omit for decorative icons — they are hidden from screen readers. */
+    label?: string;
+    /**
+     * Named GNOME palette color. Omit (or pass `"default"`) to use the
+     * theme's default foreground color — RN has no `currentColor`
+     * equivalent to inherit from a parent, unlike the web version.
+     */
+    color?: IconColor;
+    /** Forwarded to the underlying `Svg` — useful for a `transform` (e.g. a rotated disclosure chevron) or `margin`. */
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Renders an icon as an inline SVG, via `react-native-svg`.
+ *
+ * Accepts icons from `@gnome-ui/icons`, any `simple-icons` icon, or a plain
+ * `{ path }` object — same `AnyIconDefinition` union as `@gnome-ui/react`'s
+ * `Icon`. Pass `label` only when the icon conveys meaning on its own.
+ *
+ * `animated` icons (`Syncing`, `Recording`, …) carry raw `svg` markup
+ * instead of `paths` — rendered here through `SvgXml`, which parses the
+ * structural elements (`<g>`/`<path>`/`<circle>`) but has no CSS engine, so
+ * the embedded `<style>`/`@keyframes` block is silently dropped and the
+ * shapes render at their authored rest position. That happens to be exactly
+ * the desired "inert, static frame" behavior for a plain `<Icon>` — no
+ * special-casing needed here; wrap in `<AnimatedIcon>` to actually play the
+ * motion (RN has to hand-build that with `Animated`, since there is no CSS
+ * animation engine to interpret the markup's keyframes).
+ *
+ * @example
+ * import { Search } from "@gnome-ui/icons";
+ * <Icon icon={Search} label="Search" />
+ *
+ * @example
+ * import { siGithub } from "simple-icons";
+ * <Icon icon={siGithub} label="GitHub" />
+ */
+export declare const Icon: ({ icon, size, width, height, label, color, style }: IconProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { IconColor, IconProps, IconSize } from './Icon';
+export { Icon } from './Icon';

package/dist/components/Icon/shared.d.ts

@@ -0,0 +1,19 @@
+import { useGnomeTheme } from '../../GnomeProvider';
+import { IconColor, IconSize } from './Icon';
+/**
+ * Non-component helpers shared between `Icon` and `AnimatedIcon` — kept in
+ * their own module (not exported from `Icon.tsx` itself) so both files stay
+ * component-only for Fast Refresh, per the project's `react-refresh/
+ * only-export-components` lint rule.
+ */
+export declare const ICON_SIZE_MAP: Record<IconSize, number>;
+export declare function resolveIconColor(theme: ReturnType<typeof useGnomeTheme>, color: IconColor | undefined): string;
+export declare function iconAccessibilityProps(label: string | undefined): {
+    accessible: true;
+    accessibilityLabel: string;
+    accessibilityRole: "image";
+} | {
+    accessible: false;
+    accessibilityRole: "none";
+    accessibilityLabel?: undefined;
+};

package/dist/components/Tooltip/Tooltip.d.ts

@@ -0,0 +1,88 @@
+import { ReactElement, Ref } from 'react';
+import { PressableProps, View } from 'react-native';
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+export interface TooltipProps {
+    /**
+     * The tooltip label. Keep it short — a noun phrase or brief description.
+     * Do not duplicate information already visible on screen.
+     */
+    label: string;
+    /**
+     * Preferred placement relative to the trigger.
+     * The tooltip flips automatically if there is not enough space.
+     * Defaults to `"top"`.
+     */
+    placement?: TooltipPlacement;
+    /**
+     * Delay in milliseconds before the tooltip appears, on both the
+     * long-press and hover/focus triggers. Defaults to `500`. Set to `0` for
+     * instant.
+     */
+    delay?: number;
+    /**
+     * The element that triggers the tooltip.
+     * Must be a single element built on `Pressable` (e.g. `Button`, `Card`)
+     * that forwards its `ref` to the underlying `View`.
+     */
+    children: ReactElement<PressableProps & {
+        ref?: Ref<View>;
+    }>;
+}
+/**
+ * Informational tooltip following the Adwaita / GNOME HIG pattern.
+ *
+ * Wraps a single trigger element and shows a floating label. Positioned
+ * automatically and flips if there is not enough space, mirroring
+ * `@gnome-ui/react`'s `Tooltip`.
+ *
+ * **Trigger differs from the web version by necessity**: the web `Tooltip`
+ * shows only on mouse hover / keyboard focus — touch has no hover state, so
+ * it explicitly never shows on touch. RN is touch-first, so the primary
+ * trigger here is long-press (`delayLongPress={delay}`, released via
+ * `onPressOut`) — the standard mobile "peek" idiom. `onHoverIn`/`onHoverOut`
+ * are also wired for hover-capable input (trackpad/mouse on iPad or a
+ * pointer-driven RN target) and `onFocus`/`onBlur` for external-keyboard
+ * accessibility, both delayed the same way the web version delays hover.
+ *
+ * Built on RN's own `Modal` (transparent, `pointerEvents="box-none"`), the
+ * same portal-substitute `Dialog` uses — no DOM `Portal` equivalent exists.
+ * Unlike `Dialog`, `visible` is set synchronously on trigger (not gated on
+ * the async `measureInWindow` result): the trigger's on-screen rect and the
+ * tooltip's own rendered size each resolve independently into state, and a
+ * separate effect computes the final position only once both have arrived.
+ * Gating `visible` itself on `measureInWindow`'s callback was tried first
+ * and dropped — that callback never fires in this package's Jest
+ * environment (no real native view to measure), which would make the
+ * component untestable, and in production it would also lose a real
+ * quick-tap-then-release press if the callback resolved after `onPressOut`
+ * had already fired.
+ *
+ * `role="tooltip"` ports 1:1 — RN's newer web-aligned `Role` union (the
+ * same one `Dialog` uses for `role="dialog"`) already has a `"tooltip"`
+ * value, no substitution needed. `aria-describedby` has no RN equivalent
+ * (no cross-platform description-relationship prop exists), so the label is
+ * set as the trigger's `accessibilityHint` instead — read after the
+ * trigger's own label by VoiceOver/TalkBack, the nearest analog. The CSS
+ * arrow reuses the same zero-size / transparent-border-on-three-sides
+ * triangle trick as the web version — RN Views support per-side
+ * `border*Color` just like CSS, the same technique `Spinner`'s ring
+ * already relies on, applied here to a triangle instead of an arc.
+ *
+ * Not ported: repositioning on scroll/resize while visible (the web
+ * version listens for both) — RN has no global scroll event, and a
+ * long-press is naturally cancelled by a scroll gesture starting, so the
+ * window to go stale is negligible for the touch trigger; orientation
+ * change mid-hover is an accepted edge case for a component this transient.
+ * `tooltipBgColor`/`tooltipFgColor` are not real `@gnome-ui/core` tokens
+ * (only referenced as CSS var fallbacks, never defined) — hardcoded to the
+ * same literal light/dark values as the web fallback, the same workaround
+ * `Spinner`'s track color already established for this class of gap.
+ *
+ * @example
+ * <Tooltip label="Save file">
+ *   <Button accessibilityLabel="Save"><Icon icon={Save} /></Button>
+ * </Tooltip>
+ *
+ * @see https://developer.gnome.org/hig/patterns/feedback/tooltips.html
+ */
+export declare const Tooltip: ({ label, placement: preferredPlacement, delay, children, }: TooltipProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { TooltipPlacement, TooltipProps } from './Tooltip';
+export { Tooltip } from './Tooltip';