@gnome-ui/react-native 1.0.0 → 1.1.0

package/README.md

@@ -15,8 +15,8 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > 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`, and `Toast`/`Toaster` shipped — `Banner`,
-> `Dialog`, `Tooltip`, `Status Page`, and `AnimatedIcon` remain. Component
+> `ProgressBar`, `Skeleton`, `Toast`/`Toaster`, `Banner`, and `Dialog`
+> shipped — `Tooltip`, `Status Page`, and `AnimatedIcon` remain. Component
 > ports from `@gnome-ui/react` continue tier by tier. See
 > [ROADMAP.md](../../ROADMAP.md) Priority 3.
 
@@ -680,6 +680,116 @@ skips straight to the settled state. RN's `AccessibilityRole` union has no
 closest available role, paired with `accessibilityLiveRegion="polite"`
 (Android's live-region API) as the nearest match to `aria-live="polite"`.
 
+### Banner
+
+```tsx
+import { Banner } from '@gnome-ui/react-native';
+
+<Banner variant="info">A new version is available.</Banner>;
+<Banner variant="error" actionLabel="Retry" onAction={() => {}}>
+  Sync failed
+</Banner>;
+<Banner variant="success" dismissible onDismiss={() => {}}>
+  Changes saved successfully.
+</Banner>;
+```
+
+Persistent message strip for the top of a view. `variant` is `"info"`
+(default) | `"warning"` | `"error"` | `"success"`, each mapping to the
+matching `theme.<variant>BgColor`/`<variant>FgColor` token pair. Unlike
+`Toast`, it never auto-dismisses — it stays until the user acts or presses
+the optional dismiss button, so there's no `duration` prop at all.
+
+Same accessibility substitution as `Toast`: RN's `AccessibilityRole` union
+has no "status" value (the web version's `role="status"`), so `"alert"` +
+`accessibilityLiveRegion="polite"` stands in for it. The banner itself is a
+plain `View`, not `Pressable` (only its action/dismiss buttons are
+interactive), so — per the `BoxedList` lesson that a bare `View` isn't an
+accessibility element by default — `accessible` is set explicitly alongside
+`accessibilityRole`.
+
+The web version's per-variant `:hover`/`:active` background tint on the
+action/dismiss buttons (a light overlay on the darker info/error/success
+backgrounds, a dark one on the light warning background) collapses to a
+single `Pressable`-pressed-state overlay, the same simplification `Toast`
+and `Card` already made for their own press states.
+
+### Dialog
+
+```tsx
+import { Dialog } from '@gnome-ui/react-native';
+
+// Standard
+<Dialog open={open} title="About Sync" onClose={() => setOpen(false)}>
+  Files are synced automatically every 15 minutes.
+</Dialog>;
+
+// With buttons
+<Dialog
+  open={open}
+  title="Discard changes?"
+  onClose={() => setOpen(false)}
+  buttons={[
+    { label: 'Keep editing', onPress: () => setOpen(false) },
+    { label: 'Discard', variant: 'destructive', onPress: () => setOpen(false) },
+  ]}
+>
+  Your changes have not been saved.
+</Dialog>;
+
+// Alert — role="alertdialog" + responses/onResponse
+<Dialog
+  open={open}
+  role="alertdialog"
+  title="Delete file?"
+  responses={[
+    { id: 'cancel', label: 'Cancel' },
+    { id: 'delete', label: 'Delete', variant: 'destructive' },
+  ]}
+  onResponse={(id) => setOpen(false)}
+>
+  This action cannot be undone.
+</Dialog>;
+```
+
+Blocking modal dialog. **Standard** takes `title` + `children` + `buttons[]`
+with per-button `onPress`; **Alert** (`role="alertdialog"`) takes
+`responses[]` + a single `onResponse(id)` instead — the same two-API shape
+as `@gnome-ui/react`'s `Dialog`, since `AlertDialog` there is a mode of the
+same component rather than a separate one. `AboutDialog` (a distinct
+`@gnome-ui/react` component, not a `Dialog` variant) has no RN port yet.
+
+Built on RN's own `Modal` (`transparent`, `animationType="none"` — the
+entrance is a custom `Animated.timing`) rather than the web version's DOM
+`Portal` + manual focus trap: `Modal` already floats above everything with
+no portal target needed, and already blocks interaction with the screen
+behind it, so there's no `useBodyScrollLock` port. Its `onRequestClose`
+fires on the **Android hardware back button** — the direct analog of the
+web version's document-level Escape listener (iOS has no back button, so
+this is Android-only, matching the platform's own convention). Focus
+trapping (`Tab`/`Shift+Tab` cycling between focusable elements) has no
+port at all — there's no keyboard `Tab` concept in RN's touch-first model,
+the same reasoning that already dropped `TabBar`'s roving-tabindex arrow
+keys.
+
+`role` is set via RN's newer, web-aligned `role` prop (not
+`accessibilityRole`) — its `Role` union has real `"dialog"`/`"alertdialog"`
+values, unlike the older `AccessibilityRole` enum `Toast`/`Banner` had to
+substitute `"alert"` into for the web's `role="status"`.
+`accessibilityViewIsModal` (iOS-only) is the closest match to
+`aria-modal="true"`, restricting VoiceOver to the dialog's subtree. The
+dialog card sets `accessible` explicitly (a bare `View` with `role` isn't
+an accessibility element by default — the same `BoxedList` lesson) —
+**this shares the same open, unverified-on-a-real-device accessibility
+question already flagged for `BoxedList`/`TabBar`/`ViewSwitcher`'s
+container-role pattern**: `accessible={true}` on a container may collapse
+its subtree into one opaque VoiceOver stop, which for `Dialog` specifically
+would mean its footer buttons become unreachable via VoiceOver even though
+they're independently `Pressable`. Kept for `getByRole` testability and
+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.
+
 ## Installation
 
 ```bash

package/dist/components/Banner/Banner.d.ts

@@ -0,0 +1,50 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewProps, ViewStyle } from 'react-native';
+export type BannerVariant = 'info' | 'warning' | 'error' | 'success';
+export interface BannerProps extends Omit<ViewProps, 'style'> {
+    /**
+     * Visual emphasis level.
+     * - `info` (default) — neutral, accent-colored. Use for tips and notices.
+     * - `warning` — yellow. Use for recoverable problems.
+     * - `error` — red. Use for failures that need attention.
+     * - `success` — green. Use for confirmations.
+     */
+    variant?: BannerVariant;
+    /** The message text. Keep it short — one or two sentences. */
+    children: ReactNode;
+    /**
+     * Label for the optional action button placed at the trailing end.
+     * When provided, `onAction` should also be supplied.
+     */
+    actionLabel?: string;
+    /** Called when the user presses the action button. */
+    onAction?: () => void;
+    /**
+     * When true a dismiss (×) button is shown at the trailing edge.
+     * Provide `onDismiss` to handle removal from the list.
+     */
+    dismissible?: boolean;
+    /** Called when the user presses the dismiss button. */
+    onDismiss?: () => void;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Persistent message strip displayed at the top of a view, following the
+ * Adwaita `AdwBanner` pattern. Use for important information that persists
+ * until the user acts or explicitly dismisses it — unlike `Toast`, it never
+ * auto-dismisses.
+ *
+ * RN's `AccessibilityRole` union has no "status" value (the web version's
+ * `role="status"`); `"alert"` is the closest available role, paired with
+ * `accessibilityLiveRegion="polite"` (Android's live-region API) as the
+ * nearest match to `aria-live="polite"` — the same substitution `Toast`
+ * already established for the identical web role pair. Since the banner
+ * itself is a plain `View` (not `Pressable` — only its buttons are
+ * interactive), `accessible` is set explicitly alongside `accessibilityRole`,
+ * per the `BoxedList` lesson that a bare `View` isn't an accessibility
+ * element by default.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Banner.html
+ * @see https://developer.gnome.org/hig/patterns/feedback/banners.html
+ */
+export declare const Banner: ({ variant, children, actionLabel, onAction, dismissible, onDismiss, style, ...viewProps }: BannerProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { BannerProps, BannerVariant } from './Banner';
+export { Banner } from './Banner';

package/dist/components/Dialog/Dialog.d.ts

@@ -0,0 +1,105 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export type DialogButtonVariant = 'default' | 'suggested' | 'destructive';
+export interface DialogButton {
+    /** Button label. */
+    label: string;
+    /** Visual variant. Defaults to `"default"`. */
+    variant?: DialogButtonVariant;
+    /** Called when the button is pressed. */
+    onPress: () => void;
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+}
+export type AlertDialogResponseVariant = DialogButtonVariant;
+export interface AlertDialogResponse {
+    /**
+     * Unique identifier returned via `onResponse`.
+     * Use `"cancel"` by convention for the dismissive action.
+     */
+    id: string;
+    /** Button label. */
+    label: string;
+    /** Visual emphasis. Defaults to `"default"`. */
+    variant?: AlertDialogResponseVariant;
+    /** Disables the button. */
+    disabled?: boolean;
+}
+export interface DialogProps {
+    /** Whether the dialog is visible. */
+    open: boolean;
+    /** Dialog heading. */
+    title?: ReactNode;
+    /** Body content. */
+    children?: ReactNode;
+    /** Action buttons (standard dialog API). */
+    buttons?: DialogButton[];
+    /** Called on Android back button / backdrop press. */
+    onClose?: () => void;
+    /** Whether pressing the backdrop closes the dialog. Defaults to `true`. */
+    closeOnBackdrop?: boolean;
+    /**
+     * Use `"alertdialog"` for confirmations and destructive warnings — screen
+     * readers announce it immediately. Defaults to `"dialog"`.
+     *
+     * When using `role="alertdialog"`, prefer the `responses`/`onResponse` API
+     * over `buttons`/`onPress` for semantic clarity.
+     */
+    role?: 'dialog' | 'alertdialog';
+    /**
+     * Response buttons (AlertDialog API). Alternative to `buttons` — each
+     * response has a semantic `id` returned via `onResponse`. The Android back
+     * button and backdrop press fire the first non-destructive response.
+     */
+    responses?: AlertDialogResponse[];
+    /**
+     * Called with the `id` of the response button pressed.
+     * Required when `responses` is provided.
+     */
+    onResponse?: (id: string) => void;
+    style?: StyleProp<ViewStyle>;
+    /** Forwarded to the backdrop — useful for testing. */
+    testID?: string;
+}
+/**
+ * Blocking modal dialog following the Adwaita pattern.
+ *
+ * **Standard** — `title` + `children` + `buttons[]`.
+ *
+ * **Alert** — add `role="alertdialog"` + `responses[]` + `onResponse`.
+ * Uses a semantic response id instead of per-button `onPress`. The Android
+ * back button / backdrop press fire the first non-destructive response.
+ * Mirrors `AdwAlertDialog`.
+ *
+ * Built on RN's own `Modal` rather than `@gnome-ui/react`'s DOM `Portal` +
+ * manual focus trap: `Modal` already floats above everything with no portal
+ * target needed, already blocks interaction with the screen behind it (no
+ * `useBodyScrollLock` equivalent needed), and its `onRequestClose` fires on
+ * the Android hardware back button — the direct analog of the web version's
+ * document-level Escape listener. Focus-trapping (`Tab`/`Shift+Tab` cycling)
+ * has no port: there is no keyboard `Tab` concept in RN's touch-first model,
+ * the same reasoning that already dropped `TabBar`'s roving-tabindex arrow
+ * keys.
+ *
+ * `role` is passed straight through as RN's own `role` prop (not
+ * `accessibilityRole`) — RN's newer, web-aligned `Role` union has real
+ * `"dialog"`/`"alertdialog"` values, unlike the older `AccessibilityRole`
+ * enum `Toast`/`Banner` had to substitute `"alert"` into for the web's
+ * `role="status"`. `accessibilityViewIsModal` (iOS) is the closest match to
+ * `aria-modal="true"`, restricting VoiceOver to the dialog's subtree.
+ *
+ * There is no exit animation on either platform — the source CSS only
+ * defines entrance keyframes, and `Modal`'s `visible={false}` unmounts
+ * immediately, matching the web version returning `null` outright when
+ * `!open`. Entrance is an `Animated.timing` fading + scaling + sliding the
+ * card in (mirrors `@keyframes dialog-in`) alongside a plain backdrop fade
+ * (`@keyframes backdrop-in`), replayed via a `useEffect` keyed on `open`
+ * since — unlike `Toast`, which mounts once per instance — the same
+ * `Dialog` element toggles `open` repeatedly while `Modal` itself
+ * mounts/unmounts internally. `useReducedMotion()` skips straight to the
+ * settled state.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Dialog.html
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.AlertDialog.html
+ */
+export declare const Dialog: ({ open, title, children, buttons, onClose, closeOnBackdrop, role, responses, onResponse, style, testID, }: DialogProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { AlertDialogResponse, AlertDialogResponseVariant, DialogButton, DialogButtonVariant, DialogProps, } from './Dialog';
+export { Dialog } from './Dialog';