@gnome-ui/react-native 1.1.0 → 1.3.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` 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.
 
@@ -790,12 +793,195 @@ 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.
+
+### Slider
+
+```tsx
+import { Slider } from '@gnome-ui/react-native';
+
+<Slider
+  value={volume}
+  onChange={setVolume}
+  accessibilityLabel="Volume"
+  marks={[
+    { value: 0, label: 'Min' },
+    { value: 100, label: 'Max' },
+  ]}
+/>;
+```
+
+Draggable range control following the Adwaita `GtkScale` pattern, mirroring
+`@gnome-ui/react`'s `Slider`.
+
+Touch drag is handled with RN's own `PanResponder` (this package's first use
+of it) reading each touch event's `locationX` — the position relative to the
+track view itself, recalculated by RN on every touch/move — so no
+`measureInWindow` round-trip is needed at all, unlike `Tooltip`/`Dropdown`'s
+trigger-rect measurement. `min`/`max`/`step` clamping and snapping is ported
+verbatim from the web version's pure-JS math.
+
+The web version's keyboard interaction (← / → one step, Page Up/Down ten
+steps, Home/End to the bounds) has no RN equivalent — a touch-first device
+has no keyboard driving those keys. Rather than dropping value-adjustment
+accessibility entirely (the reasoning that dropped `Dropdown`'s/`TabBar`'s
+keyboard nav), `accessibilityRole="adjustable"` +
+`onAccessibilityAction`/`accessibilityActions` wires up the "increment"/
+"decrement" actions VoiceOver's swipe-up/down and TalkBack's local-context
+menu generate for an adjustable element — the real native analog of
+keyboard stepping, one step per action. The bigger Page Up/Down and
+Home/End jumps have no equivalent screen-reader gesture on either platform,
+so only single-step adjustment is ported.
+
+RN's `transform` only accepts pixel offsets, unlike the CSS `%` units the
+web version's `left: X%; transform: translate(-50%, -50%)` thumb/tick
+centering trick needs — so those are positioned with a plain pixel `left`
+computed from the track's `onLayout`-measured width instead. Mark labels
+use a different trick, since (unlike the thumb/ticks) their own rendered
+width isn't a known constant: a zero-width `View` with
+`alignItems: 'center'` at the mark's percentage `left` lets Yoga center the
+`Text` child around that point regardless of how wide the label renders,
+with no measurement needed.
+
 ## 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/Slider/Slider.d.ts

@@ -0,0 +1,56 @@
+import { StyleProp, ViewProps, ViewStyle } from 'react-native';
+export interface SliderMark {
+    value: number;
+    label?: string;
+}
+export interface SliderProps extends Omit<ViewProps, 'style'> {
+    /** Current value. Must be between `min` and `max`. */
+    value: number;
+    /** Called when the value changes. */
+    onChange: (value: number) => void;
+    /** Minimum value. Defaults to `0`. */
+    min?: number;
+    /** Maximum value. Defaults to `100`. */
+    max?: number;
+    /**
+     * Granularity of each step.
+     * - The `adjustable` accessibility action (VoiceOver/TalkBack swipe up/down) moves by one step.
+     * Defaults to `1`.
+     */
+    step?: number;
+    /** Disables the control. */
+    disabled?: boolean;
+    /**
+     * Marks to display along the track.
+     * Each mark can have an optional label rendered below the track.
+     */
+    marks?: SliderMark[];
+    /** Accessible label. Required — RN has no visible-label association to fall back on. */
+    accessibilityLabel?: string;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Draggable range slider following the Adwaita `GtkScale` pattern.
+ *
+ * - Touch drag (via `PanResponder`) sets the value continuously.
+ * - `accessibilityRole="adjustable"` + `onAccessibilityAction` handles the
+ *   "increment"/"decrement" actions VoiceOver (swipe up/down) and TalkBack
+ *   generate for an adjustable element — RN's native analog of the web
+ *   version's ← / → keyboard stepping, since a touch-first device has no
+ *   keyboard to drive `ArrowLeft`/`ArrowRight`/`Home`/`End`/`PageUp`/
+ *   `PageDown` with. Those bigger/edge jumps have no equivalent gesture on
+ *   either platform's screen reader, so only single-step increment/decrement
+ *   is ported.
+ * - Optional tick marks with labels.
+ * - Fills the track from the left up to the thumb (accent colour).
+ *
+ * RN's `transform` only accepts pixel offsets, not the CSS `%` units the
+ * web version's `left: X%; transform: translate(-50%, -50%)` centering
+ * trick relies on — so the thumb and tick marks are positioned with a
+ * plain pixel `left` (`(pct / 100) * trackWidth - size / 2`, measured via
+ * `onLayout`) instead, and vertical centering comes from the track's own
+ * `justifyContent: 'center'` rather than a transform.
+ *
+ * @see https://developer.gnome.org/hig/patterns/controls/sliders.html
+ */
+export declare const Slider: ({ value, onChange, min, max, step, disabled, marks, accessibilityLabel, style, onLayout, ...viewProps }: SliderProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { SliderMark, SliderProps } from './Slider';
+export { Slider } from './Slider';

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';