@gnome-ui/react-native 1.8.0 → 1.10.0

package/dist/components/WidgetManager/WidgetManager.d.ts

@@ -0,0 +1,92 @@
+import { IconDefinition } from '@gnome-ui/icons';
+import { ReactNode } from 'react';
+import { StyleProp, ViewStyle } from 'react-native';
+export interface WidgetDefinition {
+    /** Stable unique identifier. Also the value stored in `value`. */
+    id: string;
+    /** Row label shown in the picker catalog and above the widget once added. */
+    label: string;
+    /** Optional secondary line shown below `label` in the picker row. */
+    description?: string;
+    /** Icon shown in the picker row and in the widget's own header once added. */
+    icon?: IconDefinition;
+    /** Renders the widget's body once it has been added to the manager. */
+    render: () => ReactNode;
+}
+/**
+ * `@gnome-ui/react`'s `pickerSurface` calls this option `"modal"`, naming it
+ * after its own `Modal` component. This package's `Modal` counterpart is
+ * `Dialog` (RN's own `Modal` primitive is a different, lower-level thing —
+ * see the main `ROADMAP.md`'s note on that exact naming trap), so the option
+ * is named after what it actually renders here instead of ported verbatim.
+ */
+export type WidgetManagerPickerSurface = 'dialog' | 'bottomSheet' | 'drawer';
+export interface WidgetManagerProps {
+    /** Full catalog of widgets available to add. */
+    catalog: WidgetDefinition[];
+    /** Controlled list of added widget ids, in display order. */
+    value: string[];
+    /** Called with the new id list when the user confirms the picker. */
+    onChange: (value: string[]) => void;
+    /** Header title. */
+    title: string;
+    /** Icon shown at the leading edge of the header. */
+    icon?: IconDefinition;
+    /** Which overlay renders the catalog picker. Defaults to `"dialog"`. */
+    pickerSurface?: WidgetManagerPickerSurface;
+    /** Label for the dashed "add widget" trigger. Defaults to `"Add Widget"`. */
+    addTriggerLabel?: string;
+    /** Message shown when there are no widgets and not in edit mode. Defaults to `"No widgets added"`. */
+    emptyStateLabel?: string;
+    /** Heading of the picker overlay. Defaults to `"Widgets"`. */
+    pickerTitle?: string;
+    /** Label for a catalog row's add action. Defaults to `"Add"`. */
+    addLabel?: string;
+    /** Label for a catalog row's remove action (already staged). Defaults to `"Remove"`. */
+    removeLabel?: string;
+    /** Label for the picker's confirm action. Defaults to `"Accept"`. */
+    confirmLabel?: string;
+    /** Label for the picker's cancel action. Defaults to `"Cancel"`. */
+    cancelLabel?: string;
+    /** Accessible name of the header's edit-mode toggle button. Defaults to `"Edit widgets"`. */
+    editLabel?: string;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Card that manages a controlled collection of "widgets" — pick which ones
+ * are visible from a catalog, each rendering its own arbitrary content.
+ * Mirrors `@gnome-ui/react`'s own `WidgetManager`.
+ *
+ * The header's edit button toggles a local `editing` state: in view mode
+ * only the added widgets (or an empty-state message) are shown; in edit
+ * mode a dashed "add widget" trigger also appears, opening a catalog picker
+ * (`pickerSurface`: `"dialog"`, `"bottomSheet"`, or `"drawer"`, each backed
+ * by the already-shipped `Dialog`/`BottomSheet`/`Drawer`). Adding/removing
+ * is staged inside the picker and only applied — via `onChange` — when the
+ * user confirms; canceling or dismissing the picker discards the staging.
+ * Widgets can only be removed through the picker, never inline in the card.
+ *
+ * The catalog list is wrapped in its own `ScrollView` (capped at 360dp)
+ * before being handed to whichever picker surface renders it — unlike the
+ * web version's `overflow-y: auto` on the `Modal`/`BottomSheet`/`Drawer`
+ * body, none of this package's three overlay components scroll their
+ * `children` for you, so a long catalog needs that scroll container built
+ * in here rather than assumed.
+ *
+ * `Dialog` already renders its own confirm/cancel action row from a
+ * `buttons` array, so only `bottomSheet`/`drawer` need the hand-rolled
+ * footer row the web version calls `pickerFooter` — the exact same split
+ * the web source itself documents ("Modal uses its own actions").
+ *
+ * Not ported: `aria-pressed` on the edit toggle — `Button`/`IconButton` set
+ * their own internal `accessibilityState={{ disabled }}` on the underlying
+ * `Pressable`, and RN merges a spread prop object outright rather than
+ * key-by-key, so passing a second `accessibilityState` here would silently
+ * replace rather than merge with it (the same `Popover`-trigger clobber
+ * `SplitButton` already worked around) — dropped rather than routed around
+ * for one decorative toggle-state announcement.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.WidgetManager.html
+ */
+export declare const WidgetManager: ({ catalog, value, onChange, title, icon, pickerSurface, addTriggerLabel, emptyStateLabel, pickerTitle, addLabel, removeLabel, confirmLabel, cancelLabel, editLabel, style, testID, }: WidgetManagerProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { WidgetDefinition, WidgetManagerPickerSurface, WidgetManagerProps, } from './WidgetManager';
+export { WidgetManager } from './WidgetManager';

package/dist/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './useBreakpoint';

package/dist/hooks/useBreakpoint.d.ts

@@ -0,0 +1,79 @@
+/**
+ * GNOME / libadwaita canonical breakpoints (in dp, assuming 1 sp = 1 dp at 1× density).
+ *
+ * | Name     | Max width | Pattern triggered |
+ * |----------|-----------|--------------------|
+ * | `narrow` | ≤ 400 dp  | Collapse split views; sidebar becomes overlay |
+ * | `medium` | ≤ 550 dp  | Move ViewSwitcher to a bottom bar |
+ * | `wide`   | ≤ 860 dp  | Collapse outer pane in nested split views |
+ *
+ * Identical thresholds to `@gnome-ui/react`'s `useBreakpoint` — only the
+ * measurement source differs (`useWindowDimensions` instead of
+ * `window.innerWidth`/a `resize` listener).
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.Breakpoint.html
+ */
+export declare const GNOME_BREAKPOINTS: {
+    /** ≤ 400 dp — split views collapse to single pane */
+    readonly narrow: 400;
+    /** ≤ 550 dp — ViewSwitcher moves to bottom bar */
+    readonly medium: 550;
+    /** ≤ 860 dp — outer pane of nested split views collapses */
+    readonly wide: 860;
+};
+export type GnomeBreakpointName = keyof typeof GNOME_BREAKPOINTS;
+export interface BreakpointState {
+    /** Width ≤ 400 dp — split views are collapsed. */
+    isNarrow: boolean;
+    /** Width ≤ 550 dp — medium or narrower. */
+    isMedium: boolean;
+    /** Width ≤ 860 dp — wide or narrower. */
+    isWide: boolean;
+    /** Current window width in dp. */
+    width: number;
+}
+/**
+ * Tracks the window width against GNOME / libadwaita breakpoints.
+ *
+ * Built on `useWindowDimensions` (not `Dimensions.get` + a manual listener),
+ * since it already re-renders its subscribers on every rotation/resize —
+ * there is no CSS media query to lean on here, unlike the web version.
+ *
+ * @example
+ * const { isNarrow, isMedium } = useBreakpoint();
+ * // isNarrow → true when the window is ≤ 400 dp wide (split views should collapse)
+ * // isMedium → true when ≤ 550 dp (use a bottom ViewSwitcher instead)
+ */
+export declare function useBreakpoint(): BreakpointState;
+/** The widest bucket, above every breakpoint, is `base`. */
+export type GnomeBreakpointBucket = GnomeBreakpointName | 'base';
+/**
+ * A value that may vary by breakpoint: either the value itself, or a map of
+ * breakpoint names to values.
+ *
+ * The buckets are max-widths, so the map reads like stacked `max-width`
+ * media queries — `base` is the widest, and the narrowest matching entry
+ * wins:
+ *
+ * ```ts
+ * { base: 3, wide: 2, narrow: 1 }
+ * // ≤ 400 dp → 1 | ≤ 860 dp → 2 | wider → 3
+ * // (550 dp matches `wide`, since no `medium` entry is given)
+ * ```
+ */
+export type ResponsiveValue<T> = T | ({
+    base?: T;
+} & Partial<Record<GnomeBreakpointName, T>>);
+/**
+ * Bucket a width falls into. The same thresholds serve `useBreakpoint` and
+ * `BreakpointBin` — a breakpoint applies to whatever it's measured against,
+ * window or container alike.
+ *
+ * A width of `0` means "not measured yet" and reports `base`, so the first
+ * render matches the widest layout rather than flashing the narrowest one.
+ */
+export declare function bucketForWidth(width: number): GnomeBreakpointBucket;
+/** True when `value` is a breakpoint map rather than a plain value. */
+export declare function isResponsiveMap<T>(value: ResponsiveValue<T> | undefined): boolean;
+/** Pick the entry for `bucket`, falling back outwards to the wider ones. */
+export declare function resolveResponsive<T>(value: ResponsiveValue<T> | undefined, bucket: GnomeBreakpointBucket, fallback: T): T;