@gnome-ui/react-native 1.8.0 → 1.9.0

package/README.md

@@ -36,8 +36,14 @@ React Native component library following the [GNOME Human Interface Guidelines](
 > a React Native-only original with no `@gnome-ui/react` source at all
 > (desktop apps don't have a bottom tab bar pattern to mirror), built on
 > explicit request for the iOS/Android fixed bottom-navigation shape.
-> Component ports from `@gnome-ui/react` continue tier by tier — see this
-> package's own [ROADMAP.md](./ROADMAP.md) for full
+> `useBreakpoint` and `BreakpointBin` (both Tier 6) also shipped — the
+> package's first adaptive-layout primitives, built on `useWindowDimensions`
+> and `onLayout` respectively since there's no CSS media query/container
+> query to lean on. `ButtonContent` (Tier 15) also shipped — an icon+label
+> layout helper mostly redundant with `Button`'s own `leadingIcon`/
+> `trailingIcon`, kept for composing the same spacing outside `Button`
+> itself. 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.
@@ -497,6 +503,10 @@ button is the RN-idiomatic stand-in. The clear (×) button appears whenever
 glyphs (`🔍`/`×`) rather than `@gnome-ui/icons`, matching every other
 no-SVG-dependency component in this package.
 
+`inline` drops the header-bar background/border so the bar blends into any
+surface — a card, a plain content area, a custom container — instead of
+looking like it belongs to a `HeaderBar`.
+
 Dropped relative to `@gnome-ui/react`'s `SearchBar`: the `suggestions` /
 `onSuggestionSelect` / `loadingSuggestions` / `renderSuggestion` /
 `suggestionsLabel` autocomplete popover — it depends on a portal +
@@ -2104,6 +2114,37 @@ substitution `Chip`'s selected-state tint already established. `<blockquote>`/
 `<footer>`/`<cite>` have no RN element equivalent, so this renders as a
 plain `View` with no semantic role.
 
+### ButtonContent
+
+```tsx
+import { ButtonContent, Icon } from '@gnome-ui/react-native';
+import { Save } from '@gnome-ui/icons';
+
+<Pressable onPress={save}>
+  <ButtonContent icon={<Icon icon={Save} size="sm" />} label="Save" color="accent" />
+</Pressable>;
+```
+
+Icon + label layout helper mirroring `AdwButtonContent` — the same 6 dp
+gap, vertically-centered row every button in this package already
+produces internally via `leadingIcon`/`trailingIcon`. **Mostly redundant
+with `Button`'s own `leadingIcon`/`trailingIcon` props** for anything that
+actually is a `Button` — those already lay the icon and a themed,
+variant-colored label out identically, with no separate color prop
+needed. Reach for `ButtonContent` when composing icon+label content for
+something that *isn't* this package's `Button` instead: a bespoke
+`Pressable`, a custom card action, anywhere the same Adwaita spacing
+convention is wanted outside `Button` itself.
+
+Unlike the web version, there's no `currentColor` to inherit the
+surrounding button's text color from, so a `color` prop (the same
+`TextColor` union `Text`/`ButtonRow` already use) needs to be passed
+explicitly to match — e.g. `color="accent"` beside a `suggested`-style
+action, `color="destructive"` beside a destructive one. The icon slot is
+marked `accessibilityElementsHidden`/`importantForAccessibility="no-hide-
+descendants"`, the RN equivalent of the web version's `aria-hidden="true"`
+on its icon `<span>`.
+
 ### ButtonRow
 
 ```tsx
@@ -2397,6 +2438,62 @@ mode — `true` for a dot, a number for a count (capped at `"99+"`).
 this package takes no dependency on `react-native-safe-area-context`
 itself.
 
+### useBreakpoint
+
+```tsx
+import { useBreakpoint } from '@gnome-ui/react-native';
+
+const { isNarrow, isMedium, width } = useBreakpoint();
+
+return isNarrow ? <CompactLayout /> : <RegularLayout />;
+```
+
+Tracks the window width against the same GNOME/libadwaita canonical
+breakpoints as `@gnome-ui/react`'s hook of the same name — `narrow` (≤ 400
+dp, split views collapse), `medium` (≤ 550 dp, `ViewSwitcher` moves to a
+bottom bar), `wide` (≤ 860 dp, outer pane of a nested split view
+collapses). Built on `useWindowDimensions` rather than `Dimensions.get` +
+a manual listener, since it already re-renders subscribers on every
+rotation/resize — there's no CSS media query to lean on here, unlike the
+web version's `window.innerWidth` + `resize` listener.
+
+Also exports `bucketForWidth`/`resolveResponsive`/`ResponsiveValue` — the
+same small pure-function toolkit the web hook exports, for picking a
+value that varies by breakpoint (`{ base: 3, wide: 2, narrow: 1 }`-shaped
+maps). These aren't wired into any component's props yet; they're
+exported now so a future adaptive component (`Sidebar`'s `mode` prop,
+`NavigationSplitView`, …) doesn't have to redefine the bucket-fallback
+logic from scratch.
+
+### BreakpointBin
+
+```tsx
+import { BreakpointBin } from '@gnome-ui/react-native';
+
+<BreakpointBin breakpoints={[{ name: 'compact', maxWidth: 400 }]}>
+  {({ activeBreakpoint }) =>
+    activeBreakpoint === 'compact' ? <CompactCard /> : <WideCard />
+  }
+</BreakpointBin>;
+```
+
+The per-*component* (container-query) sibling of `useBreakpoint` — reacts
+to **its own width**, not the window, so the same component can render
+differently depending on how much space its parent gives it, regardless
+of device size. Two `BreakpointBin`s with identical `breakpoints` can be
+in different states side by side.
+
+`@gnome-ui/react`'s version watches itself with `ResizeObserver`; RN has
+no such API, so this measures via `onLayout` instead — fired on mount and
+again on every subsequent resize of the wrapping `View` (a parent's flex
+layout reflowing, a device rotation, an ancestor `BreakpointBin` flipping
+column↔row). The active breakpoint is the smallest `maxWidth` ≥ the
+current width, declaration order doesn't matter (sorted internally), and
+`activeBreakpoint` is `null` when the container is wider than every
+threshold. Unlike the web version there's no `data-breakpoint` attribute
+to expose for CSS targeting (RN has no attribute selectors) — branch on
+`activeBreakpoint` directly inside the render prop instead.
+
 ## Installation
 
 ```bash

package/dist/components/BreakpointBin/BreakpointBin.d.ts

@@ -0,0 +1,65 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewProps, ViewStyle } from 'react-native';
+export interface BreakpointDefinition {
+    /** Identifier for this breakpoint, e.g. `"compact"` or `"narrow"`. */
+    name: string;
+    /**
+     * Container width threshold in dp.
+     * This breakpoint becomes active when the container width is ≤ this value.
+     */
+    maxWidth: number;
+}
+export interface BreakpointBinState {
+    /**
+     * Name of the currently active breakpoint, or `null` when the container
+     * is wider than all defined breakpoints.
+     */
+    activeBreakpoint: string | null;
+    /** Current container width in dp (from `onLayout`). */
+    width: number;
+}
+export interface BreakpointBinProps extends Omit<ViewProps, 'children' | 'style'> {
+    /**
+     * Breakpoint definitions. The active breakpoint is the smallest
+     * `maxWidth` ≥ the container's current width — declaration order doesn't
+     * matter, they're sorted internally.
+     */
+    breakpoints: BreakpointDefinition[];
+    /**
+     * Render prop that receives the current breakpoint state.
+     *
+     * @example
+     * ```tsx
+     * <BreakpointBin breakpoints={[{ name: "compact", maxWidth: 400 }]}>
+     *   {({ activeBreakpoint }) =>
+     *     activeBreakpoint === "compact" ? <CompactLayout /> : <WideLayout />
+     *   }
+     * </BreakpointBin>
+     * ```
+     */
+    children: (state: BreakpointBinState) => ReactNode;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Container that fires layout changes when **its own width** crosses
+ * defined thresholds — the CSS container-query equivalent of
+ * `AdwBreakpointBin` (libadwaita 1.9 / GNOME 50), and the per-*component*
+ * sibling of `useBreakpoint` (which watches the window instead).
+ *
+ * `@gnome-ui/react`'s version watches its own width via `ResizeObserver`;
+ * RN has no such API, so this measures the same thing via `onLayout` —
+ * fired on mount and again on every subsequent resize of the `View` itself
+ * (e.g. the parent's flex layout reflowing, or a device rotation changing
+ * how much space this container is given). Composable the same way: the
+ * same component can render differently depending on how much space its
+ * parent gives it, regardless of the window size — two `BreakpointBin`s
+ * side by side with identical `breakpoints` can be in different states.
+ *
+ * Unlike the web version, there's no `data-breakpoint` attribute to expose
+ * for CSS targeting (RN has no attribute selectors) — branch on
+ * `activeBreakpoint` directly inside the render prop instead, exactly like
+ * every story below already does.
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.BreakpointBin.html
+ */
+export declare const BreakpointBin: ({ breakpoints, children, style, onLayout, ...viewProps }: BreakpointBinProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { BreakpointBinProps, BreakpointBinState, BreakpointDefinition, } from './BreakpointBin';
+export { BreakpointBin } from './BreakpointBin';

package/dist/components/ButtonContent/ButtonContent.d.ts

@@ -0,0 +1,47 @@
+import { ReactNode } from 'react';
+import { StyleProp, ViewProps, ViewStyle } from 'react-native';
+import { TextColor } from '../Text';
+export type ButtonContentIconPosition = 'start' | 'end';
+export interface ButtonContentProps extends Omit<ViewProps, 'style'> {
+    /** Icon placed next to the label. Rendered as-is — size/color it yourself. */
+    icon?: ReactNode;
+    /** Text label. */
+    label: string;
+    /**
+     * Position of the icon relative to the label.
+     * @default 'start'
+     */
+    iconPosition?: ButtonContentIconPosition;
+    /**
+     * Label color. RN has no `currentColor` equivalent, so unlike the web
+     * version (which inherits the parent button's text color via CSS), this
+     * needs to be told explicitly which color to match — e.g. `"accent"`
+     * when placed inside a `suggested` `Button`. Defaults to `"default"`.
+     */
+    color?: TextColor;
+    style?: StyleProp<ViewStyle>;
+}
+/**
+ * Icon + label layout helper for buttons that contain both an icon and
+ * text — the same 6 dp gap / vertically-centered row every button in this
+ * package already produces internally. Mirrors `AdwButtonContent`.
+ *
+ * **Mostly redundant with `Button`'s own `leadingIcon`/`trailingIcon`
+ * props** — pass those instead for anything that's actually a `Button`,
+ * they already lay the icon and (themed, variant-colored) label out
+ * identically and need no separate color prop. Reach for `ButtonContent`
+ * when composing icon+label content for something that *isn't* this
+ * package's `Button` — a bespoke `Pressable`, a `ButtonRow` title slot, a
+ * `Chip`'s custom content — anywhere the exact same Adwaita icon/label
+ * spacing convention is wanted outside `Button` itself.
+ *
+ * @example
+ * ```tsx
+ * <Pressable onPress={save}>
+ *   <ButtonContent icon={<Icon icon={DocumentSave} />} label="Save" />
+ * </Pressable>
+ * ```
+ *
+ * @see https://gnome.pages.gitlab.gnome.org/libadwaita/doc/main/class.ButtonContent.html
+ */
+export declare const ButtonContent: ({ icon, label, iconPosition, color, style, ...viewProps }: ButtonContentProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,2 @@
+export type { ButtonContentIconPosition, ButtonContentProps } from './ButtonContent';
+export { ButtonContent } from './ButtonContent';

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;