@gnome-ui/react-native 1.7.0 → 1.9.0

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;