react-native-gtkx 0.1.0-alpha.4 → 0.2.0-alpha.2

package/dist/common/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../src/common/list.tsx"],"names":[],"mappings":"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","sourcesContent":["// Adwaita's boxed list, for code written in React Native.\n//\n// WHY this is here rather than in an app. `.boxed-list` is the single most\n// recognisable piece of GNOME chrome, and docs/research/react-native-first-showcase.md\n// measured what it actually is: a rounded, shadowed card whose rows carry\n// hairline separators, a hover tint and a press tint. Every one of those is a\n// style — there is no widget BEHAVIOUR in the look at all. So an app can build\n// it from `View` and `Pressable`, and `examples/tasks-nav` proves it.\n//\n// What an app should not have to do is rediscover the numbers. They come from\n// libadwaita's own compiled stylesheet, they are not obvious (the frame is a\n// three-part `box-shadow`, not a border; the first and last rows carry the\n// corner radii, not the container), and they move when libadwaita moves. That\n// is a platform's job, which is what this subpath is.\n//\n// Everything below is portable React Native underneath — no widget is created\n// that an app could not have created itself. Compare `Widget`/`SlotContent`\n// next door, which exist precisely because they CANNOT be written in RN.\nimport { type ReactNode } from \"react\"\nimport { useColorScheme } from \"../apis/index\"\nimport { Pressable } from \"../components/pressable\"\nimport { Text } from \"../components/text\"\nimport { View } from \"../components/view\"\nimport { PlatformColor, StyleSheet } from \"../style/index\"\nimport type { StyleProp } from \"../contracts\"\n\n/**\n * Where a row sits in its list, which is what decides its corner radii and\n * whether it draws a separator under itself.\n *\n * RN has no `:first-child`, so this is explicit. From a `FlatList` it is\n * `rowPosition(index, data.length)`; from a static list it is the same\n * expression over the array.\n */\nexport type ListRowPosition = \"first\" | \"middle\" | \"last\" | \"only\"\n\n/** The usual derivation, so no call site has to get the one-row case wrong. */\nexport const rowPosition = (index: number, count: number): ListRowPosition => {\n  const first = index === 0\n  const last = index === count - 1\n  if (first && last) {\n    return \"only\"\n  }\n  return first ? \"first\" : last ? \"last\" : \"middle\"\n}\n\n// libadwaita 1.9, /org/gnome/Adwaita/styles/gtk.css:\n//   list.boxed-list { background-color: var(--card-bg-color); border-radius: 12px;\n//                     box-shadow: 0 0 0 1px RGB(0 0 6/3%),\n//                                 0 1px 3px 1px RGB(0 0 6/7%),\n//                                 0 2px 6px 2px RGB(0 0 6/3%); }\nconst RADIUS = 12\n\nconst styles = StyleSheet.create({\n  list: {\n    backgroundColor: PlatformColor(\"card-bg-color\"),\n    borderRadius: RADIUS,\n    // The frame is a shadow, not a border, and that distinction is load\n    // bearing: a border would consume the box and inset every row by a pixel,\n    // and no border draws the two soft drops underneath.\n    boxShadow: [\n      {\n        offsetX: 0,\n        offsetY: 0,\n        spreadDistance: 1,\n        color: \"rgba(0, 0, 6, 0.03)\",\n      },\n      {\n        offsetX: 0,\n        offsetY: 1,\n        blurRadius: 3,\n        spreadDistance: 1,\n        color: \"rgba(0, 0, 6, 0.07)\",\n      },\n      {\n        offsetX: 0,\n        offsetY: 2,\n        blurRadius: 6,\n        spreadDistance: 2,\n        color: \"rgba(0, 0, 6, 0.03)\",\n      },\n    ],\n  },\n  // `list > row { padding: 2px }` plus\n  // `row > box.header { margin: 0 12px; border-spacing: 6px; min-height: 50px }`\n  // — 2 + 50 + 2 + the 1px separator is the 55px row pitch measured off the\n  // widget's own screenshot.\n  row: {\n    flexDirection: \"row\",\n    alignItems: \"center\",\n    minHeight: 54,\n    paddingVertical: 2,\n    paddingHorizontal: 14,\n    gap: 6,\n  },\n  separatorUnder: {\n    borderBottomWidth: 1,\n    borderBottomColor: PlatformColor(\"card-shade-color\"),\n  },\n  firstRow: { borderTopLeftRadius: RADIUS, borderTopRightRadius: RADIUS },\n  lastRow: {\n    borderBottomLeftRadius: RADIUS,\n    borderBottomRightRadius: RADIUS,\n  },\n  // `row > box.header > box.title { margin: 6px 0; border-spacing: 3px }`\n  titleBox: { flex: 1, marginVertical: 6, gap: 3 },\n  // The theme font is `Adwaita Sans 11`, i.e. 11pt = 14.67px, and Adwaita sets\n  // the subtitle to `font-size: smaller` — Pango's one-step-down, 1/1.2. RN's\n  // fontSize is numeric only (there is no `smaller`, no em, no inherited\n  // percentage), so the computed value is what an app can write. Documented\n  // in docs/api.md rather than hidden here.\n  title: { fontSize: 14.7 },\n  // `row label.subtitle { opacity: var(--dim-opacity) }`, 55% in the light\n  // Adwaita palette.\n  subtitle: { fontSize: 12.2, opacity: 0.55 },\n  separator: {\n    height: 1,\n    backgroundColor: PlatformColor(\"card-shade-color\"),\n  },\n})\n\n// Adwaita tints the hover and press states with a fraction of the FOREGROUND\n// colour (`color-mix(in srgb, currentColor 4%, transparent)`), so one literal\n// cannot serve both themes and CSS colour functions are not part of RN's\n// colour contract. Two literals plus the scheme is what an RN app writes on\n// every platform, and it is what this does.\nconst TINTS = {\n  light: { hover: \"rgba(0, 0, 0, 0.04)\", press: \"rgba(0, 0, 0, 0.08)\" },\n  dark: {\n    hover: \"rgba(255, 255, 255, 0.04)\",\n    press: \"rgba(255, 255, 255, 0.08)\",\n  },\n} as const\n\nexport type ListProps = {\n  children?: ReactNode\n  style?: StyleProp\n  testID?: string\n}\n\n/**\n * The `.boxed-list` frame: a rounded, shadowed card. Put `ListRow`s in it\n * directly, or a `FlatList` whose `renderItem` returns them.\n *\n * ```tsx\n * <List>\n *   {tasks.map((task, index) => (\n *     <ListRow\n *       key={task.id}\n *       title={task.title}\n *       position={rowPosition(index, tasks.length)}\n *       onPress={() => open(task)}\n *     />\n *   ))}\n * </List>\n * ```\n */\nexport const List = ({ children, style, testID }: ListProps): ReactNode => (\n  <View\n    testID={testID}\n    style={[styles.list, style]}\n  >\n    {children}\n  </View>\n)\n\nexport type ListRowProps = {\n  /** Primary line. A string renders with the row's own typography; a node is\n   *  rendered as given, for a title that needs its own styling. */\n  title?: ReactNode\n  /** Second, dimmed line. Omitted rows are single-line, as `AdwActionRow`'s\n   *  are. */\n  subtitle?: ReactNode\n  /** Leading content — a checkbox, an icon, a colour swatch. */\n  prefix?: ReactNode\n  /** Trailing content — buttons, a value, a chevron. */\n  suffix?: ReactNode\n  /** Makes the row activatable: it gains the hover and press tints and calls\n   *  this. Without it the row is inert, like a non-`activatable`\n   *  `AdwActionRow`. */\n  onPress?: () => void\n  /** Position in the list, for the corner radii and the separator. Defaults\n   *  to `\"middle\"`, which is right for a row that is neither. */\n  position?: ListRowPosition\n  /** Draw the hairline under this row. Default true for every position except\n   *  the last — set it false when the list supplies its own separators (a\n   *  `FlatList`'s `ItemSeparatorComponent`, say). */\n  separator?: boolean\n  style?: StyleProp\n  testID?: string\n}\n\n/**\n * One row of a {@link List} — `AdwActionRow`'s layout and states, built from\n * `Pressable`, `View` and `Text`.\n *\n * Hover and press come from `Pressable`'s state callback, so they cost what\n * they cost anywhere else in this platform: the hover path swaps a CSS class\n * on the widget without a React render (see components/pressable.tsx).\n *\n * **Not yet:** keyboard navigation between rows and a focus ring.\n * `GtkListBox` implements those as widget behaviour and RN has no focus model\n * for `View` to hang them on — `Pressable`'s state is `{pressed, hovered}`\n * with no `focused`. The ring itself is now drawable (`outlineWidth` and\n * friends), so what is missing is the state, not the paint.\n */\nexport const ListRow = ({\n  title,\n  subtitle,\n  prefix,\n  suffix,\n  onPress,\n  position = \"middle\",\n  separator,\n  style,\n  testID,\n}: ListRowProps): ReactNode => {\n  const scheme = useColorScheme() === \"dark\" ? \"dark\" : \"light\"\n  const tints = TINTS[scheme]\n  const isFirst = position === \"first\" || position === \"only\"\n  const isLast = position === \"last\" || position === \"only\"\n  const drawSeparator = separator ?? !isLast\n\n  const body = (\n    <>\n      {prefix}\n      <View style={styles.titleBox}>\n        {typeof title === \"string\" ? (\n          <Text style={styles.title}>{title}</Text>\n        ) : (\n          title\n        )}\n        {typeof subtitle === \"string\" ? (\n          <Text style={styles.subtitle}>{subtitle}</Text>\n        ) : (\n          subtitle\n        )}\n      </View>\n      {suffix}\n    </>\n  )\n\n  const base = [\n    styles.row,\n    isFirst && styles.firstRow,\n    isLast && styles.lastRow,\n    drawSeparator && styles.separatorUnder,\n    style,\n  ]\n\n  if (!onPress) {\n    return (\n      <View\n        testID={testID}\n        style={base}\n      >\n        {body}\n      </View>\n    )\n  }\n\n  return (\n    <Pressable\n      testID={testID}\n      onPress={onPress}\n      // The tint goes on the ROW, which is why the corner radii above have to\n      // be on the row too: a hovered first row must round its own top corners\n      // or the highlight paints square over the card's rounded ones.\n      style={({ hovered, pressed }) => [\n        ...base,\n        hovered && { backgroundColor: tints.hover },\n        pressed && { backgroundColor: tints.press },\n      ]}\n    >\n      {body}\n    </Pressable>\n  )\n}\n\n/**\n * The hairline between two rows, for lists that draw their own separators —\n * a `FlatList`'s `ItemSeparatorComponent` is exactly this, and using it means\n * the rows themselves stay position-agnostic apart from their corners.\n */\nexport const ListSeparator = (): ReactNode => <View style={styles.separator} />\n"]}

package/dist/common/navigation-stack.d.ts

@@ -0,0 +1,84 @@
+import { type ComponentProps, type ReactNode, type Ref } from "react";
+import { AdwNavigationPage as RawAdwNavigationPage, AdwNavigationView as RawAdwNavigationView, type Adw } from "../gtkx/bridge/index";
+type AdwPageProps = ComponentProps<typeof RawAdwNavigationPage>;
+export type NavigationStackPageProps = AdwPageProps & {
+    /** Stable identity of this page inside the view. Required: the whole sync
+     *  protocol is expressed in tags, and Adwaita itself pushes and pops by
+     *  tag. Use the same string you put in NavigationView's `stack`. */
+    tag: string;
+};
+/**
+ * One page of an {@link NavigationStack}.
+ *
+ * Children are passed to the widget untouched. To put React Native content
+ * inside a page, wrap it in `SlotContent` (see ./content) — the primitive
+ * deliberately does not guess, so raw GTK children keep working.
+ */
+export declare const NavigationStackPage: ({ tag, onHidden, onShown, ...rest }: NavigationStackPageProps) => React.JSX.Element;
+type AdwViewProps = ComponentProps<typeof RawAdwNavigationView>;
+export type NavigationStackProps = Omit<AdwViewProps, "onPopped" | "ref"> & {
+    /**
+     * The visible stack, root first, as page tags. Change it and the widget
+     * animates to match: appended tags push, removed tags pop, a changed root
+     * replaces the whole stack.
+     */
+    stack: readonly string[];
+    /** `NavigationStackPage` elements. Pages not in `stack` are still accepted —
+     *  they simply are not shown — so a router may render all of its screens. */
+    children?: ReactNode;
+    /**
+     * Whether push/pop/replace transitions animate at all, forwarded straight
+     * to `Adw.NavigationView`'s own `animate-transitions` property (already
+     * reachable through this component's inherited `Adw.NavigationView` props —
+     * spelled out here because it is the one prop consumers most often go
+     * looking for). GTK has exactly one transition style; there is no per-style
+     * choice to make here, only whether it plays. Default true, matching the
+     * widget's own default. Interactive swipe-back gestures always animate
+     * regardless of this value — that is Adwaita's own behavior, not this
+     * primitive's.
+     */
+    animateTransitions?: boolean;
+    /**
+     * The widget popped a page by itself: the Adwaita back button, Escape, the
+     * back gesture, or the back-history menu. NOT called for pops you caused by
+     * changing `stack`. This is where a router follows the view.
+     */
+    onPopped?: (tag: string) => void;
+    /** A closing page finished animating out and was dropped from the tree. */
+    onPageClosed?: (tag: string) => void;
+    /** A push/pop/replace transition started. */
+    onTransitionStart?: () => void;
+    /** …and finished. Driven by the transitioning page's own real
+     *  `shown`/`hidden` AdwNavigationPage signal (whichever settles it —
+     *  see beginTransition), with `transitionDuration` as a fallback for the
+     *  cases where neither arrives. */
+    onTransitionEnd?: () => void;
+    /** Fallback window in ms, used only when a page's own transition signal
+     *  never arrives (see the file header comment for the two cases this
+     *  covers) — for page retention and for the transition callbacks above.
+     *  NOT a measurement of the real transition length. Default 400. */
+    transitionDuration?: number;
+    /** Escape hatch: the underlying Adw.NavigationView, for anything this
+     *  primitive does not model. */
+    ref?: Ref<Adw.NavigationView | null>;
+};
+/**
+ * `Adw.NavigationView` driven declaratively.
+ *
+ * ```tsx
+ * const [stack, setStack] = useState(["home"])
+ *
+ * <NavigationStack
+ *   stack={stack}
+ *   onPopped={(tag) => setStack((s) => s.filter((t) => t !== tag))}
+ * >
+ *   <NavigationStackPage tag="home" title="Home">…</NavigationStackPage>
+ *   <NavigationStackPage tag="detail" title="Detail">…</NavigationStackPage>
+ * </NavigationStack>
+ * ```
+ *
+ * No router required. `react-native-gtkx/navigation` uses exactly this
+ * component to back `createStackNavigator`.
+ */
+export declare const NavigationStack: ({ stack, children, onPopped, onPageClosed, onTransitionStart, onTransitionEnd, transitionDuration, ref, ...rest }: NavigationStackProps) => React.JSX.Element;
+export {};

package/dist/common/navigation-stack.js

@@ -0,0 +1,313 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// react-native-gtkx/adwaita — Adw.NavigationView as a declarative primitive.
+//
+// This layer knows NOTHING about react-navigation. You hand it the ordered
+// stack of page tags you want visible, it animates the widget to that stack
+// and tells you when the WIDGET popped on its own (back button, Escape, the
+// back gesture). Bring react-navigation, bring your own router, or drive it
+// from useState — the primitive does not care.
+//
+// react-native-gtkx/navigation is a thin adapter on top of this file, the
+// same way @react-navigation/native-stack sits on top of react-native-screens.
+//
+// Why the primitive owns retention: react-navigation (and any router) drops a
+// popped route immediately, while Adwaita still animates the page out. If the
+// consumer had to keep rendering pages it already considers gone, every
+// consumer would reimplement that bookkeeping and the primitive would be
+// useless without a router. So NavigationView snapshots a page when it
+// leaves `stack` and drops it on the page's "hidden" signal — the real
+// AdwNavigationPage signal, not a guess — with `transitionDuration` as a
+// fallback timer for two cases where the signal never arrives on its own:
+// environments that never deliver it at all (headless compositors with
+// animations disabled), and a page skipped entirely by a multi-hop pop
+// (measured on the rig: `popToTag` from [a,b,c] to "a" fires hiding/hidden
+// only on "c", the page that was actually visible — "b" gets no signal at
+// all, on any environment, because it was never itself on screen during the
+// transition). onTransitionStart/onTransitionEnd and the InteractionManager
+// bracket around them use the exact same real-signal-first, timer-fallback
+// mechanism — see beginTransition below.
+import { Children, createContext, isValidElement, useCallback, useContext, useEffect, useInsertionEffect, useRef, useState, } from "react";
+import { InteractionManager } from "../apis/interaction-manager";
+import { AdwNavigationPage as RawAdwNavigationPage, AdwNavigationView as RawAdwNavigationView, } from "../gtkx/bridge/index";
+/** A conservative fallback window for the two cases described above, where
+ *  no real per-page signal ever arrives for this specific transition. This
+ *  is NOT a measurement of Adwaita's actual transition length — an earlier
+ *  version of this comment claimed "~200 ms measured", which was never
+ *  actually measured (found while auditing this file). On the project's own
+ *  headless GTK test rig the real signal always arrives, and in well under
+ *  a millisecond, so there is no rig measurement to cite either; this
+ *  number is simply a deliberately generous upper bound. Overridable
+ *  because a consumer may want a shorter/longer safety margin. */
+const DEFAULT_TRANSITION_MS = 400;
+const PageLifecycleContext = createContext(null);
+/**
+ * One page of an {@link NavigationStack}.
+ *
+ * Children are passed to the widget untouched. To put React Native content
+ * inside a page, wrap it in `SlotContent` (see ./content) — the primitive
+ * deliberately does not guess, so raw GTK children keep working.
+ */
+export const NavigationStackPage = ({ tag, onHidden, onShown, ...rest }) => {
+    const lifecycle = useContext(PageLifecycleContext);
+    const handleHidden = ((...args) => {
+        lifecycle?.reportHidden(tag);
+        onHidden?.(...args);
+    });
+    const handleShown = ((...args) => {
+        lifecycle?.reportShown(tag);
+        onShown?.(...args);
+    });
+    return (_jsx(RawAdwNavigationPage, { ...rest, tag: tag, onHidden: handleHidden, onShown: handleShown }));
+};
+/**
+ * `Adw.NavigationView` driven declaratively.
+ *
+ * ```tsx
+ * const [stack, setStack] = useState(["home"])
+ *
+ * <NavigationStack
+ *   stack={stack}
+ *   onPopped={(tag) => setStack((s) => s.filter((t) => t !== tag))}
+ * >
+ *   <NavigationStackPage tag="home" title="Home">…</NavigationStackPage>
+ *   <NavigationStackPage tag="detail" title="Detail">…</NavigationStackPage>
+ * </NavigationStack>
+ * ```
+ *
+ * No router required. `react-native-gtkx/navigation` uses exactly this
+ * component to back `createStackNavigator`.
+ */
+export const NavigationStack = ({ stack, children, onPopped, onPageClosed, onTransitionStart, onTransitionEnd, transitionDuration = DEFAULT_TRANSITION_MS, ref, ...rest }) => {
+    const viewRef = useRef(null);
+    // Mirror of the widget's visible stack. Maintained by the sync effect and
+    // by the popped handler; the two never race, because GTK signals run
+    // synchronously inside the very push/pop calls the effect makes.
+    const syncedRef = useRef([]);
+    const pagesByTag = new Map();
+    for (const child of Children.toArray(children)) {
+        if (isValidElement(child)) {
+            const tag = child.props.tag;
+            if (typeof tag === "string") {
+                pagesByTag.set(tag, child);
+            }
+        }
+    }
+    // Pages currently in the tree: everything in `stack`, plus pages that left
+    // it and are still animating out.
+    const [renderedTags, setRenderedTags] = useState(() => [...stack]);
+    const missing = stack.filter((tag) => !renderedTags.includes(tag));
+    if (missing.length > 0) {
+        // The sanctioned derive-state-during-render pattern: a new page must be
+        // in the tree within the same commit the sync effect pushes it.
+        setRenderedTags([...renderedTags, ...missing]);
+    }
+    // A state-held stable Map rather than a ref: the render path reads it for
+    // closing pages, and reading a ref during render is rightly banned.
+    const [snapshots] = useState(() => new Map());
+    useEffect(() => {
+        for (const [tag, element] of pagesByTag) {
+            snapshots.set(tag, element);
+        }
+    });
+    const dropPage = useCallback((tag) => {
+        let dropped = false;
+        setRenderedTags((tags) => {
+            if (!tags.includes(tag)) {
+                return tags;
+            }
+            dropped = true;
+            return tags.filter((rendered) => rendered !== tag);
+        });
+        if (dropped) {
+            snapshots.delete(tag);
+            onPageClosed?.(tag);
+        }
+    }, [onPageClosed, snapshots]);
+    // Signal handlers read the CURRENT requested stack, not the one captured
+    // when they were created. Refreshed in an insertion effect (the project's
+    // standard escape from writing refs during render): insertion effects run
+    // before layout effects, so the value is fresh by the time GTK can emit.
+    const stackRef = useRef(stack);
+    useInsertionEffect(() => {
+        stackRef.current = stack;
+    });
+    // Per-tag waiters for "this specific page's transition settled" — fed by
+    // reportHidden/reportShown below, drained (and deleted) the moment either
+    // fires. A page can end up "shown" after being "hiding" (an interrupted
+    // pop reversed) or "hidden" after being "showing" (an interrupted push
+    // superseded) — GObject-introspection documents both pairings — so a
+    // waiter for a given tag resolves on WHICHEVER of the two settles it,
+    // not just the one that would be expected in the common case.
+    const transitionWaitersRef = useRef(new Map());
+    const addTransitionWaiter = useCallback((tag, resolve) => {
+        const waiters = transitionWaitersRef.current.get(tag);
+        if (waiters) {
+            waiters.push(resolve);
+        }
+        else {
+            transitionWaitersRef.current.set(tag, [resolve]);
+        }
+    }, []);
+    const removeTransitionWaiter = useCallback((tag, resolve) => {
+        const waiters = transitionWaitersRef.current.get(tag);
+        if (!waiters) {
+            return;
+        }
+        const next = waiters.filter((waiter) => waiter !== resolve);
+        if (next.length > 0) {
+            transitionWaitersRef.current.set(tag, next);
+        }
+        else {
+            transitionWaitersRef.current.delete(tag);
+        }
+    }, []);
+    const resolveTransitionWaiters = useCallback((tag) => {
+        const waiters = transitionWaitersRef.current.get(tag);
+        if (!waiters) {
+            return;
+        }
+        transitionWaitersRef.current.delete(tag);
+        for (const resolve of waiters) {
+            resolve();
+        }
+    }, []);
+    const reportHidden = useCallback((tag) => {
+        resolveTransitionWaiters(tag);
+        // "hidden" also fires for a live page covered by a push — only pages
+        // gone from the requested stack are actually closing.
+        if (stackRef.current.includes(tag)) {
+            return;
+        }
+        dropPage(tag);
+    }, [dropPage, resolveTransitionWaiters]);
+    const reportShown = useCallback((tag) => {
+        resolveTransitionWaiters(tag);
+    }, [resolveTransitionWaiters]);
+    // Delivery of "hidden" is not guaranteed — see the file header comment for
+    // the two cases (a genuinely signal-less environment, and a page skipped
+    // over by a multi-hop pop) — so a timer slightly longer than the fallback
+    // window is the backstop. dropPage is idempotent: whichever wins, wins.
+    const scheduleDrop = useCallback((tag) => {
+        setTimeout(() => reportHidden(tag), transitionDuration);
+    }, [reportHidden, transitionDuration]);
+    // Bracket every transition with an InteractionManager handle so
+    // runAfterInteractions work (a screen's data load, a heavy render) waits
+    // for the slide instead of stealing its frames, closing it and firing
+    // onTransitionEnd exactly when the transition really settles: the real
+    // "shown"/"hidden" signal on `targetTag` (the page this specific push,
+    // popToTag or replaceWithTags call is bringing into view) if it arrives,
+    // `transitionDuration` otherwise. `targetTag` is undefined only for
+    // replaceWithTags([]) — no page becomes visible, nothing to wait on, the
+    // timer alone settles it. Overlapping transitions reference-count through
+    // the handle API.
+    const beginTransition = useCallback((targetTag) => {
+        const handle = InteractionManager.createInteractionHandle();
+        onTransitionStart?.();
+        let settled = false;
+        const settle = () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            InteractionManager.clearInteractionHandle(handle);
+            onTransitionEnd?.();
+        };
+        if (targetTag !== undefined) {
+            addTransitionWaiter(targetTag, settle);
+        }
+        setTimeout(() => {
+            if (targetTag !== undefined) {
+                removeTransitionWaiter(targetTag, settle);
+            }
+            settle();
+        }, transitionDuration);
+    }, [
+        addTransitionWaiter,
+        removeTransitionWaiter,
+        onTransitionEnd,
+        onTransitionStart,
+        transitionDuration,
+    ]);
+    useEffect(() => {
+        const view = viewRef.current;
+        if (!view) {
+            return;
+        }
+        const target = [...stack];
+        if (syncedRef.current.length === 0 && target.length > 0) {
+            // First mount: NavigationView shows the first added page by itself.
+            syncedRef.current = target.slice(0, 1);
+        }
+        let common = 0;
+        while (common < syncedRef.current.length &&
+            common < target.length &&
+            syncedRef.current[common] === target[common]) {
+            common += 1;
+        }
+        if (common === 0 && syncedRef.current[0] !== target[0]) {
+            // The root changed (a reset): swap the whole visible stack. The last
+            // tag becomes the visible page (undefined only when target is empty —
+            // see beginTransition's targetTag doc above).
+            const leaving = syncedRef.current.filter((tag) => !target.includes(tag));
+            syncedRef.current = [...target];
+            beginTransition(target[target.length - 1]);
+            view.replaceWithTags(target);
+            for (const tag of leaving) {
+                scheduleDrop(tag);
+            }
+            return;
+        }
+        if (syncedRef.current.length > common) {
+            const anchor = target[common - 1];
+            const leaving = syncedRef.current.slice(common);
+            syncedRef.current = syncedRef.current.slice(0, common);
+            if (anchor !== undefined) {
+                beginTransition(anchor);
+                view.popToTag(anchor);
+            }
+            for (const tag of leaving) {
+                scheduleDrop(tag);
+            }
+        }
+        for (let index = syncedRef.current.length; index < target.length; index += 1) {
+            const tag = target[index];
+            syncedRef.current.push(tag);
+            beginTransition(tag);
+            view.pushByTag(tag);
+        }
+    }, [stack, scheduleDrop, beginTransition]);
+    const handlePopped = (page) => {
+        const tag = page?.getTag();
+        if (!tag) {
+            return;
+        }
+        syncedRef.current = syncedRef.current.filter((synced) => synced !== tag);
+        // Reported unconditionally: the consumer decides whether this pop was
+        // one it already knows about. The primitive has no router state to
+        // consult, and guessing here is exactly what would couple the layers.
+        onPopped?.(tag);
+        scheduleDrop(tag);
+    };
+    // The context value must be identity-stable (every page reads it), so the
+    // live handlers are reached through refs rather than baked into the value.
+    const reportHiddenRef = useRef(reportHidden);
+    const reportShownRef = useRef(reportShown);
+    useInsertionEffect(() => {
+        reportHiddenRef.current = reportHidden;
+        reportShownRef.current = reportShown;
+    });
+    const [lifecycle] = useState(() => ({
+        reportHidden: (tag) => reportHiddenRef.current(tag),
+        reportShown: (tag) => reportShownRef.current(tag),
+    }));
+    return (_jsx(PageLifecycleContext.Provider, { value: lifecycle, children: _jsx(RawAdwNavigationView, { ...rest, ref: (instance) => {
+                viewRef.current = instance;
+                if (typeof ref === "function") {
+                    ref(instance);
+                }
+                else if (ref) {
+                    ref.current = instance;
+                }
+            }, onPopped: (page) => handlePopped(page), children: renderedTags.map((tag) => pagesByTag.get(tag) ?? snapshots.get(tag) ?? null) }) }));
+};
+//# sourceMappingURL=navigation-stack.js.map

package/dist/common/navigation-stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation-stack.js","sourceRoot":"","sources":["../../src/common/navigation-stack.tsx"],"names":[],"mappings":";AAAA,6EAA6E;AAC7E,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,4EAA4E;AAC5E,4EAA4E;AAC5E,+CAA+C;AAC/C,EAAE;AACF,0EAA0E;AAC1E,+EAA+E;AAC/E,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,wEAAwE;AACxE,yEAAyE;AACzE,uEAAuE;AACvE,uEAAuE;AACvE,yEAAyE;AACzE,0EAA0E;AAC1E,uEAAuE;AACvE,uEAAuE;AACvE,2EAA2E;AAC3E,0EAA0E;AAC1E,4EAA4E;AAC5E,4EAA4E;AAC5E,2EAA2E;AAC3E,yCAAyC;AACzC,OAAO,EACL,QAAQ,EACR,aAAa,EACb,cAAc,EACd,WAAW,EACX,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,MAAM,EACN,QAAQ,GAIT,MAAM,OAAO,CAAA;AACd,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,EACL,iBAAiB,IAAI,oBAAoB,EACzC,iBAAiB,IAAI,oBAAoB,GAE1C,MAAM,sBAAsB,CAAA;AAE7B;;;;;;;;kEAQkE;AAClE,MAAM,qBAAqB,GAAG,GAAG,CAAA;AAOjC,MAAM,oBAAoB,GAAG,aAAa,CAAuB,IAAI,CAAC,CAAA;AActE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,EAClC,GAAG,EACH,QAAQ,EACR,OAAO,EACP,GAAG,IAAI,EACkB,EAAE,EAAE;IAC7B,MAAM,SAAS,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAA;IAClD,MAAM,YAAY,GAAG,CAAC,CAAC,GAAG,IAAe,EAAE,EAAE;QAC3C,SAAS,EAAE,YAAY,CAAC,GAAG,CAAC,CAG3B;QAAC,QAAoD,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;IACnE,CAAC,CAA6B,CAAA;IAC9B,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,IAAe,EAAE,EAAE;QAC1C,SAAS,EAAE,WAAW,CAAC,GAAG,CAAC,CAE1B;QAAC,OAAmD,EAAE,CAAC,GAAG,IAAI,CAAC,CAAA;IAClE,CAAC,CAA4B,CAAA;IAC7B,OAAO,CACL,KAAC,oBAAoB,OACf,IAAI,EACR,GAAG,EAAE,GAAG,EACR,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,WAAW,GACpB,CACH,CAAA;AACH,CAAC,CAAA;AAmDD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,EAC9B,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,kBAAkB,GAAG,qBAAqB,EAC1C,GAAG,EACH,GAAG,IAAI,EACc,EAAE,EAAE;IACzB,MAAM,OAAO,GAAG,MAAM,CAA4B,IAAI,CAAC,CAAA;IACvD,0EAA0E;IAC1E,qEAAqE;IACrE,iEAAiE;IACjE,MAAM,SAAS,GAAG,MAAM,CAAW,EAAE,CAAC,CAAA;IAEtC,MAAM,UAAU,GAAG,IAAI,GAAG,EAAqB,CAAA;IAC/C,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/C,IAAI,cAAc,CAAoB,KAAK,CAAC,EAAE,CAAC;YAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAA;YAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;gBAC5B,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,kCAAkC;IAClC,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,CAAW,GAAG,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAA;IAC5E,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;IAClE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,wEAAwE;QACxE,gEAAgE;QAChE,eAAe,CAAC,CAAC,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC,CAAC,CAAA;IAChD,CAAC;IAED,0EAA0E;IAC1E,oEAAoE;IACpE,MAAM,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,EAAqB,CAAC,CAAA;IAChE,SAAS,CAAC,GAAG,EAAE;QACb,KAAK,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,IAAI,UAAU,EAAE,CAAC;YACxC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;QAC7B,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,GAAW,EAAQ,EAAE;QACpB,IAAI,OAAO,GAAG,KAAK,CAAA;QACnB,eAAe,CAAC,CAAC,IAAI,EAAE,EAAE;YACvB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,GAAG,IAAI,CAAA;YACd,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAA;QACpD,CAAC,CAAC,CAAA;QACF,IAAI,OAAO,EAAE,CAAC;YACZ,SAAS,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;YACrB,YAAY,EAAE,CAAC,GAAG,CAAC,CAAA;QACrB,CAAC;IACH,CAAC,EACD,CAAC,YAAY,EAAE,SAAS,CAAC,CAC1B,CAAA;IAED,yEAAyE;IACzE,0EAA0E;IAC1E,0EAA0E;IAC1E,yEAAyE;IACzE,MAAM,QAAQ,GAAG,MAAM,CAAoB,KAAK,CAAC,CAAA;IACjD,kBAAkB,CAAC,GAAG,EAAE;QACtB,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAA;IAC1B,CAAC,CAAC,CAAA;IAEF,yEAAyE;IACzE,0EAA0E;IAC1E,wEAAwE;IACxE,uEAAuE;IACvE,qEAAqE;IACrE,sEAAsE;IACtE,8DAA8D;IAC9D,MAAM,oBAAoB,GAAG,MAAM,CAAiC,IAAI,GAAG,EAAE,CAAC,CAAA;IAE9E,MAAM,mBAAmB,GAAG,WAAW,CACrC,CAAC,GAAW,EAAE,OAAmB,EAAQ,EAAE;QACzC,MAAM,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACrD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACvB,CAAC;aAAM,CAAC;YACN,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAA;QAClD,CAAC;IACH,CAAC,EACD,EAAE,CACH,CAAA;IAED,MAAM,sBAAsB,GAAG,WAAW,CACxC,CAAC,GAAW,EAAE,OAAmB,EAAQ,EAAE;QACzC,MAAM,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACrD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAM;QACR,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,OAAO,CAAC,CAAA;QAC3D,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAA;QAC7C,CAAC;aAAM,CAAC;YACN,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC1C,CAAC;IACH,CAAC,EACD,EAAE,CACH,CAAA;IAED,MAAM,wBAAwB,GAAG,WAAW,CAAC,CAAC,GAAW,EAAQ,EAAE;QACjE,MAAM,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACrD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAM;QACR,CAAC;QACD,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACxC,KAAK,MAAM,OAAO,IAAI,OAAO,EAAE,CAAC;YAC9B,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,GAAW,EAAQ,EAAE;QACpB,wBAAwB,CAAC,GAAG,CAAC,CAAA;QAC7B,qEAAqE;QACrE,sDAAsD;QACtD,IAAI,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,OAAM;QACR,CAAC;QACD,QAAQ,CAAC,GAAG,CAAC,CAAA;IACf,CAAC,EACD,CAAC,QAAQ,EAAE,wBAAwB,CAAC,CACrC,CAAA;IAED,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,GAAW,EAAQ,EAAE;QACpB,wBAAwB,CAAC,GAAG,CAAC,CAAA;IAC/B,CAAC,EACD,CAAC,wBAAwB,CAAC,CAC3B,CAAA;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,wEAAwE;IACxE,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,GAAW,EAAQ,EAAE;QACpB,UAAU,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,kBAAkB,CAAC,CAAA;IACzD,CAAC,EACD,CAAC,YAAY,EAAE,kBAAkB,CAAC,CACnC,CAAA;IAED,gEAAgE;IAChE,yEAAyE;IACzE,sEAAsE;IACtE,uEAAuE;IACvE,uEAAuE;IACvE,yEAAyE;IACzE,oEAAoE;IACpE,yEAAyE;IACzE,0EAA0E;IAC1E,kBAAkB;IAClB,MAAM,eAAe,GAAG,WAAW,CACjC,CAAC,SAA6B,EAAQ,EAAE;QACtC,MAAM,MAAM,GAAG,kBAAkB,CAAC,uBAAuB,EAAE,CAAA;QAC3D,iBAAiB,EAAE,EAAE,CAAA;QACrB,IAAI,OAAO,GAAG,KAAK,CAAA;QACnB,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAM;YACR,CAAC;YACD,OAAO,GAAG,IAAI,CAAA;YACd,kBAAkB,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAA;YACjD,eAAe,EAAE,EAAE,CAAA;QACrB,CAAC,CAAA;QACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,mBAAmB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;QACxC,CAAC;QACD,UAAU,CAAC,GAAG,EAAE;YACd,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,sBAAsB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;YAC3C,CAAC;YACD,MAAM,EAAE,CAAA;QACV,CAAC,EAAE,kBAAkB,CAAC,CAAA;IACxB,CAAC,EACD;QACE,mBAAmB;QACnB,sBAAsB;QACtB,eAAe;QACf,iBAAiB;QACjB,kBAAkB;KACnB,CACF,CAAA;IAED,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAA;QAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAM;QACR,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAA;QACzB,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxD,oEAAoE;YACpE,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;QACxC,CAAC;QACD,IAAI,MAAM,GAAG,CAAC,CAAA;QACd,OACE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM;YACjC,MAAM,GAAG,MAAM,CAAC,MAAM;YACtB,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,EAC5C,CAAC;YACD,MAAM,IAAI,CAAC,CAAA;QACb,CAAC;QACD,IAAI,MAAM,KAAK,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,qEAAqE;YACrE,sEAAsE;YACtE,8CAA8C;YAC9C,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;YACxE,SAAS,CAAC,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAA;YAC/B,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAA;YAC1C,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAA;YAC5B,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC1B,YAAY,CAAC,GAAG,CAAC,CAAA;YACnB,CAAC;YACD,OAAM;QACR,CAAC;QACD,IAAI,SAAS,CAAC,OAAO,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;YACtC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;YACjC,MAAM,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;YAC/C,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;YACtD,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,eAAe,CAAC,MAAM,CAAC,CAAA;gBACvB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;YACvB,CAAC;YACD,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC1B,YAAY,CAAC,GAAG,CAAC,CAAA;YACnB,CAAC;QACH,CAAC;QACD,KACE,IAAI,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EACpC,KAAK,GAAG,MAAM,CAAC,MAAM,EACrB,KAAK,IAAI,CAAC,EACV,CAAC;YACD,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAE,CAAA;YAC1B,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YAC3B,eAAe,CAAC,GAAG,CAAC,CAAA;YACpB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;QACrB,CAAC;IACH,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC,CAAA;IAE1C,MAAM,YAAY,GAAG,CAAC,IAA+B,EAAQ,EAAE;QAC7D,MAAM,GAAG,GAAG,IAAI,EAAE,MAAM,EAAE,CAAA;QAC1B,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,OAAM;QACR,CAAC;QACD,SAAS,CAAC,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,GAAG,CAAC,CAAA;QACxE,sEAAsE;QACtE,mEAAmE;QACnE,sEAAsE;QACtE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAA;QACf,YAAY,CAAC,GAAG,CAAC,CAAA;IACnB,CAAC,CAAA;IAED,0EAA0E;IAC1E,2EAA2E;IAC3E,MAAM,eAAe,GAAG,MAAM,CAAwB,YAAY,CAAC,CAAA;IACnE,MAAM,cAAc,GAAG,MAAM,CAAwB,WAAW,CAAC,CAAA;IACjE,kBAAkB,CAAC,GAAG,EAAE;QACtB,eAAe,CAAC,OAAO,GAAG,YAAY,CAAA;QACtC,cAAc,CAAC,OAAO,GAAG,WAAW,CAAA;IACtC,CAAC,CAAC,CAAA;IACF,MAAM,CAAC,SAAS,CAAC,GAAG,QAAQ,CAAgB,GAAG,EAAE,CAAC,CAAC;QACjD,YAAY,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC;QAC3D,WAAW,EAAE,CAAC,GAAW,EAAE,EAAE,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;KAC1D,CAAC,CAAC,CAAA;IAEH,OAAO,CACL,KAAC,oBAAoB,CAAC,QAAQ,IAAC,KAAK,EAAE,SAAS,YAC7C,KAAC,oBAAoB,OACf,IAAI,EACR,GAAG,EAAE,CAAC,QAAmC,EAAE,EAAE;gBAC3C,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAA;gBAC1B,IAAI,OAAO,GAAG,KAAK,UAAU,EAAE,CAAC;oBAC9B,GAAG,CAAC,QAAQ,CAAC,CAAA;gBACf,CAAC;qBAAM,IAAI,GAAG,EAAE,CAAC;oBACf,GAAG,CAAC,OAAO,GAAG,QAAQ,CAAA;gBACxB,CAAC;YACH,CAAC,EACD,QAAQ,EAAE,CAAC,IAA+B,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,YAEhE,YAAY,CAAC,GAAG,CACf,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAC3D,GACoB,GACO,CACjC,CAAA;AACH,CAAC,CAAA","sourcesContent":["// react-native-gtkx/adwaita — Adw.NavigationView as a declarative primitive.\n//\n// This layer knows NOTHING about react-navigation. You hand it the ordered\n// stack of page tags you want visible, it animates the widget to that stack\n// and tells you when the WIDGET popped on its own (back button, Escape, the\n// back gesture). Bring react-navigation, bring your own router, or drive it\n// from useState — the primitive does not care.\n//\n// react-native-gtkx/navigation is a thin adapter on top of this file, the\n// same way @react-navigation/native-stack sits on top of react-native-screens.\n//\n// Why the primitive owns retention: react-navigation (and any router) drops a\n// popped route immediately, while Adwaita still animates the page out. If the\n// consumer had to keep rendering pages it already considers gone, every\n// consumer would reimplement that bookkeeping and the primitive would be\n// useless without a router. So NavigationView snapshots a page when it\n// leaves `stack` and drops it on the page's \"hidden\" signal — the real\n// AdwNavigationPage signal, not a guess — with `transitionDuration` as a\n// fallback timer for two cases where the signal never arrives on its own:\n// environments that never deliver it at all (headless compositors with\n// animations disabled), and a page skipped entirely by a multi-hop pop\n// (measured on the rig: `popToTag` from [a,b,c] to \"a\" fires hiding/hidden\n// only on \"c\", the page that was actually visible — \"b\" gets no signal at\n// all, on any environment, because it was never itself on screen during the\n// transition). onTransitionStart/onTransitionEnd and the InteractionManager\n// bracket around them use the exact same real-signal-first, timer-fallback\n// mechanism — see beginTransition below.\nimport {\n  Children,\n  createContext,\n  isValidElement,\n  useCallback,\n  useContext,\n  useEffect,\n  useInsertionEffect,\n  useRef,\n  useState,\n  type ComponentProps,\n  type ReactNode,\n  type Ref,\n} from \"react\"\nimport { InteractionManager } from \"../apis/interaction-manager\"\nimport {\n  AdwNavigationPage as RawAdwNavigationPage,\n  AdwNavigationView as RawAdwNavigationView,\n  type Adw,\n} from \"../gtkx/bridge/index\"\n\n/** A conservative fallback window for the two cases described above, where\n *  no real per-page signal ever arrives for this specific transition. This\n *  is NOT a measurement of Adwaita's actual transition length — an earlier\n *  version of this comment claimed \"~200 ms measured\", which was never\n *  actually measured (found while auditing this file). On the project's own\n *  headless GTK test rig the real signal always arrives, and in well under\n *  a millisecond, so there is no rig measurement to cite either; this\n *  number is simply a deliberately generous upper bound. Overridable\n *  because a consumer may want a shorter/longer safety margin. */\nconst DEFAULT_TRANSITION_MS = 400\n\ntype PageLifecycle = {\n  reportHidden: (tag: string) => void\n  reportShown: (tag: string) => void\n}\n\nconst PageLifecycleContext = createContext<PageLifecycle | null>(null)\n\n// Every prop Adw.NavigationPage exposes flows through untouched, so anything\n// gtkx binds today (and anything it binds tomorrow) is reachable without a\n// change here. Only `onHidden` is intercepted, and it is still forwarded.\ntype AdwPageProps = ComponentProps<typeof RawAdwNavigationPage>\n\nexport type NavigationStackPageProps = AdwPageProps & {\n  /** Stable identity of this page inside the view. Required: the whole sync\n   *  protocol is expressed in tags, and Adwaita itself pushes and pops by\n   *  tag. Use the same string you put in NavigationView's `stack`. */\n  tag: string\n}\n\n/**\n * One page of an {@link NavigationStack}.\n *\n * Children are passed to the widget untouched. To put React Native content\n * inside a page, wrap it in `SlotContent` (see ./content) — the primitive\n * deliberately does not guess, so raw GTK children keep working.\n */\nexport const NavigationStackPage = ({\n  tag,\n  onHidden,\n  onShown,\n  ...rest\n}: NavigationStackPageProps) => {\n  const lifecycle = useContext(PageLifecycleContext)\n  const handleHidden = ((...args: unknown[]) => {\n    lifecycle?.reportHidden(tag)\n    // The consumer's own handler still runs, and runs second: retention\n    // bookkeeping must not depend on what the consumer does here.\n    ;(onHidden as ((...a: unknown[]) => void) | undefined)?.(...args)\n  }) as AdwPageProps[\"onHidden\"]\n  const handleShown = ((...args: unknown[]) => {\n    lifecycle?.reportShown(tag)\n    // Same ordering guarantee as onHidden above.\n    ;(onShown as ((...a: unknown[]) => void) | undefined)?.(...args)\n  }) as AdwPageProps[\"onShown\"]\n  return (\n    <RawAdwNavigationPage\n      {...rest}\n      tag={tag}\n      onHidden={handleHidden}\n      onShown={handleShown}\n    />\n  )\n}\n\ntype AdwViewProps = ComponentProps<typeof RawAdwNavigationView>\n\nexport type NavigationStackProps = Omit<AdwViewProps, \"onPopped\" | \"ref\"> & {\n  /**\n   * The visible stack, root first, as page tags. Change it and the widget\n   * animates to match: appended tags push, removed tags pop, a changed root\n   * replaces the whole stack.\n   */\n  stack: readonly string[]\n  /** `NavigationStackPage` elements. Pages not in `stack` are still accepted —\n   *  they simply are not shown — so a router may render all of its screens. */\n  children?: ReactNode\n  /**\n   * Whether push/pop/replace transitions animate at all, forwarded straight\n   * to `Adw.NavigationView`'s own `animate-transitions` property (already\n   * reachable through this component's inherited `Adw.NavigationView` props —\n   * spelled out here because it is the one prop consumers most often go\n   * looking for). GTK has exactly one transition style; there is no per-style\n   * choice to make here, only whether it plays. Default true, matching the\n   * widget's own default. Interactive swipe-back gestures always animate\n   * regardless of this value — that is Adwaita's own behavior, not this\n   * primitive's.\n   */\n  animateTransitions?: boolean\n  /**\n   * The widget popped a page by itself: the Adwaita back button, Escape, the\n   * back gesture, or the back-history menu. NOT called for pops you caused by\n   * changing `stack`. This is where a router follows the view.\n   */\n  onPopped?: (tag: string) => void\n  /** A closing page finished animating out and was dropped from the tree. */\n  onPageClosed?: (tag: string) => void\n  /** A push/pop/replace transition started. */\n  onTransitionStart?: () => void\n  /** …and finished. Driven by the transitioning page's own real\n   *  `shown`/`hidden` AdwNavigationPage signal (whichever settles it —\n   *  see beginTransition), with `transitionDuration` as a fallback for the\n   *  cases where neither arrives. */\n  onTransitionEnd?: () => void\n  /** Fallback window in ms, used only when a page's own transition signal\n   *  never arrives (see the file header comment for the two cases this\n   *  covers) — for page retention and for the transition callbacks above.\n   *  NOT a measurement of the real transition length. Default 400. */\n  transitionDuration?: number\n  /** Escape hatch: the underlying Adw.NavigationView, for anything this\n   *  primitive does not model. */\n  ref?: Ref<Adw.NavigationView | null>\n}\n\n/**\n * `Adw.NavigationView` driven declaratively.\n *\n * ```tsx\n * const [stack, setStack] = useState([\"home\"])\n *\n * <NavigationStack\n *   stack={stack}\n *   onPopped={(tag) => setStack((s) => s.filter((t) => t !== tag))}\n * >\n *   <NavigationStackPage tag=\"home\" title=\"Home\">…</NavigationStackPage>\n *   <NavigationStackPage tag=\"detail\" title=\"Detail\">…</NavigationStackPage>\n * </NavigationStack>\n * ```\n *\n * No router required. `react-native-gtkx/navigation` uses exactly this\n * component to back `createStackNavigator`.\n */\nexport const NavigationStack = ({\n  stack,\n  children,\n  onPopped,\n  onPageClosed,\n  onTransitionStart,\n  onTransitionEnd,\n  transitionDuration = DEFAULT_TRANSITION_MS,\n  ref,\n  ...rest\n}: NavigationStackProps) => {\n  const viewRef = useRef<Adw.NavigationView | null>(null)\n  // Mirror of the widget's visible stack. Maintained by the sync effect and\n  // by the popped handler; the two never race, because GTK signals run\n  // synchronously inside the very push/pop calls the effect makes.\n  const syncedRef = useRef<string[]>([])\n\n  const pagesByTag = new Map<string, ReactNode>()\n  for (const child of Children.toArray(children)) {\n    if (isValidElement<{ tag?: unknown }>(child)) {\n      const tag = child.props.tag\n      if (typeof tag === \"string\") {\n        pagesByTag.set(tag, child)\n      }\n    }\n  }\n\n  // Pages currently in the tree: everything in `stack`, plus pages that left\n  // it and are still animating out.\n  const [renderedTags, setRenderedTags] = useState<string[]>(() => [...stack])\n  const missing = stack.filter((tag) => !renderedTags.includes(tag))\n  if (missing.length > 0) {\n    // The sanctioned derive-state-during-render pattern: a new page must be\n    // in the tree within the same commit the sync effect pushes it.\n    setRenderedTags([...renderedTags, ...missing])\n  }\n\n  // A state-held stable Map rather than a ref: the render path reads it for\n  // closing pages, and reading a ref during render is rightly banned.\n  const [snapshots] = useState(() => new Map<string, ReactNode>())\n  useEffect(() => {\n    for (const [tag, element] of pagesByTag) {\n      snapshots.set(tag, element)\n    }\n  })\n\n  const dropPage = useCallback(\n    (tag: string): void => {\n      let dropped = false\n      setRenderedTags((tags) => {\n        if (!tags.includes(tag)) {\n          return tags\n        }\n        dropped = true\n        return tags.filter((rendered) => rendered !== tag)\n      })\n      if (dropped) {\n        snapshots.delete(tag)\n        onPageClosed?.(tag)\n      }\n    },\n    [onPageClosed, snapshots],\n  )\n\n  // Signal handlers read the CURRENT requested stack, not the one captured\n  // when they were created. Refreshed in an insertion effect (the project's\n  // standard escape from writing refs during render): insertion effects run\n  // before layout effects, so the value is fresh by the time GTK can emit.\n  const stackRef = useRef<readonly string[]>(stack)\n  useInsertionEffect(() => {\n    stackRef.current = stack\n  })\n\n  // Per-tag waiters for \"this specific page's transition settled\" — fed by\n  // reportHidden/reportShown below, drained (and deleted) the moment either\n  // fires. A page can end up \"shown\" after being \"hiding\" (an interrupted\n  // pop reversed) or \"hidden\" after being \"showing\" (an interrupted push\n  // superseded) — GObject-introspection documents both pairings — so a\n  // waiter for a given tag resolves on WHICHEVER of the two settles it,\n  // not just the one that would be expected in the common case.\n  const transitionWaitersRef = useRef<Map<string, Array<() => void>>>(new Map())\n\n  const addTransitionWaiter = useCallback(\n    (tag: string, resolve: () => void): void => {\n      const waiters = transitionWaitersRef.current.get(tag)\n      if (waiters) {\n        waiters.push(resolve)\n      } else {\n        transitionWaitersRef.current.set(tag, [resolve])\n      }\n    },\n    [],\n  )\n\n  const removeTransitionWaiter = useCallback(\n    (tag: string, resolve: () => void): void => {\n      const waiters = transitionWaitersRef.current.get(tag)\n      if (!waiters) {\n        return\n      }\n      const next = waiters.filter((waiter) => waiter !== resolve)\n      if (next.length > 0) {\n        transitionWaitersRef.current.set(tag, next)\n      } else {\n        transitionWaitersRef.current.delete(tag)\n      }\n    },\n    [],\n  )\n\n  const resolveTransitionWaiters = useCallback((tag: string): void => {\n    const waiters = transitionWaitersRef.current.get(tag)\n    if (!waiters) {\n      return\n    }\n    transitionWaitersRef.current.delete(tag)\n    for (const resolve of waiters) {\n      resolve()\n    }\n  }, [])\n\n  const reportHidden = useCallback(\n    (tag: string): void => {\n      resolveTransitionWaiters(tag)\n      // \"hidden\" also fires for a live page covered by a push — only pages\n      // gone from the requested stack are actually closing.\n      if (stackRef.current.includes(tag)) {\n        return\n      }\n      dropPage(tag)\n    },\n    [dropPage, resolveTransitionWaiters],\n  )\n\n  const reportShown = useCallback(\n    (tag: string): void => {\n      resolveTransitionWaiters(tag)\n    },\n    [resolveTransitionWaiters],\n  )\n\n  // Delivery of \"hidden\" is not guaranteed — see the file header comment for\n  // the two cases (a genuinely signal-less environment, and a page skipped\n  // over by a multi-hop pop) — so a timer slightly longer than the fallback\n  // window is the backstop. dropPage is idempotent: whichever wins, wins.\n  const scheduleDrop = useCallback(\n    (tag: string): void => {\n      setTimeout(() => reportHidden(tag), transitionDuration)\n    },\n    [reportHidden, transitionDuration],\n  )\n\n  // Bracket every transition with an InteractionManager handle so\n  // runAfterInteractions work (a screen's data load, a heavy render) waits\n  // for the slide instead of stealing its frames, closing it and firing\n  // onTransitionEnd exactly when the transition really settles: the real\n  // \"shown\"/\"hidden\" signal on `targetTag` (the page this specific push,\n  // popToTag or replaceWithTags call is bringing into view) if it arrives,\n  // `transitionDuration` otherwise. `targetTag` is undefined only for\n  // replaceWithTags([]) — no page becomes visible, nothing to wait on, the\n  // timer alone settles it. Overlapping transitions reference-count through\n  // the handle API.\n  const beginTransition = useCallback(\n    (targetTag: string | undefined): void => {\n      const handle = InteractionManager.createInteractionHandle()\n      onTransitionStart?.()\n      let settled = false\n      const settle = (): void => {\n        if (settled) {\n          return\n        }\n        settled = true\n        InteractionManager.clearInteractionHandle(handle)\n        onTransitionEnd?.()\n      }\n      if (targetTag !== undefined) {\n        addTransitionWaiter(targetTag, settle)\n      }\n      setTimeout(() => {\n        if (targetTag !== undefined) {\n          removeTransitionWaiter(targetTag, settle)\n        }\n        settle()\n      }, transitionDuration)\n    },\n    [\n      addTransitionWaiter,\n      removeTransitionWaiter,\n      onTransitionEnd,\n      onTransitionStart,\n      transitionDuration,\n    ],\n  )\n\n  useEffect(() => {\n    const view = viewRef.current\n    if (!view) {\n      return\n    }\n    const target = [...stack]\n    if (syncedRef.current.length === 0 && target.length > 0) {\n      // First mount: NavigationView shows the first added page by itself.\n      syncedRef.current = target.slice(0, 1)\n    }\n    let common = 0\n    while (\n      common < syncedRef.current.length &&\n      common < target.length &&\n      syncedRef.current[common] === target[common]\n    ) {\n      common += 1\n    }\n    if (common === 0 && syncedRef.current[0] !== target[0]) {\n      // The root changed (a reset): swap the whole visible stack. The last\n      // tag becomes the visible page (undefined only when target is empty —\n      // see beginTransition's targetTag doc above).\n      const leaving = syncedRef.current.filter((tag) => !target.includes(tag))\n      syncedRef.current = [...target]\n      beginTransition(target[target.length - 1])\n      view.replaceWithTags(target)\n      for (const tag of leaving) {\n        scheduleDrop(tag)\n      }\n      return\n    }\n    if (syncedRef.current.length > common) {\n      const anchor = target[common - 1]\n      const leaving = syncedRef.current.slice(common)\n      syncedRef.current = syncedRef.current.slice(0, common)\n      if (anchor !== undefined) {\n        beginTransition(anchor)\n        view.popToTag(anchor)\n      }\n      for (const tag of leaving) {\n        scheduleDrop(tag)\n      }\n    }\n    for (\n      let index = syncedRef.current.length;\n      index < target.length;\n      index += 1\n    ) {\n      const tag = target[index]!\n      syncedRef.current.push(tag)\n      beginTransition(tag)\n      view.pushByTag(tag)\n    }\n  }, [stack, scheduleDrop, beginTransition])\n\n  const handlePopped = (page: Adw.NavigationPage | null): void => {\n    const tag = page?.getTag()\n    if (!tag) {\n      return\n    }\n    syncedRef.current = syncedRef.current.filter((synced) => synced !== tag)\n    // Reported unconditionally: the consumer decides whether this pop was\n    // one it already knows about. The primitive has no router state to\n    // consult, and guessing here is exactly what would couple the layers.\n    onPopped?.(tag)\n    scheduleDrop(tag)\n  }\n\n  // The context value must be identity-stable (every page reads it), so the\n  // live handlers are reached through refs rather than baked into the value.\n  const reportHiddenRef = useRef<(tag: string) => void>(reportHidden)\n  const reportShownRef = useRef<(tag: string) => void>(reportShown)\n  useInsertionEffect(() => {\n    reportHiddenRef.current = reportHidden\n    reportShownRef.current = reportShown\n  })\n  const [lifecycle] = useState<PageLifecycle>(() => ({\n    reportHidden: (tag: string) => reportHiddenRef.current(tag),\n    reportShown: (tag: string) => reportShownRef.current(tag),\n  }))\n\n  return (\n    <PageLifecycleContext.Provider value={lifecycle}>\n      <RawAdwNavigationView\n        {...rest}\n        ref={(instance: Adw.NavigationView | null) => {\n          viewRef.current = instance\n          if (typeof ref === \"function\") {\n            ref(instance)\n          } else if (ref) {\n            ref.current = instance\n          }\n        }}\n        onPopped={(page: Adw.NavigationPage | null) => handlePopped(page)}\n      >\n        {renderedTags.map(\n          (tag) => pagesByTag.get(tag) ?? snapshots.get(tag) ?? null,\n        )}\n      </RawAdwNavigationView>\n    </PageLifecycleContext.Provider>\n  )\n}\n"]}

package/dist/common/widget.d.ts

@@ -0,0 +1,62 @@
+import { type ComponentType, type ReactNode } from "react";
+import { type LayoutEvent } from "../components/use-layout-child";
+import type { StyleProp } from "../contracts";
+import { type Gtk } from "../gtkx/bridge/index";
+export type WidgetProps = {
+    /** React Native style. The layout half drives Yoga, the visual half becomes
+     *  a GTK CSS class. Omit sizing and the widget's own natural size wins. */
+    style?: StyleProp;
+    onLayout?: (event: LayoutEvent) => void;
+    /** The GTK widget(s) to lay out. Your own `ref` on them is untouched. */
+    children: ReactNode;
+    testID?: string;
+};
+/**
+ * Put any GTK widget into React Native layout.
+ *
+ * ```tsx
+ * <View style={{ flexDirection: "row", gap: 8, padding: 12 }}>
+ *   <Widget style={{ flex: 1 }}>
+ *     <GtkEntry placeholderText="Search" />
+ *   </Widget>
+ *   <Widget>
+ *     <GtkButton iconName="edit-find-symbolic" />
+ *   </Widget>
+ * </View>
+ * ```
+ *
+ * The entry flexes, the button takes its natural size, both sit in the row
+ * exactly like React Native children — because to Yoga they now are.
+ *
+ * For the reverse direction (React Native content inside a GTK slot) see
+ * `SlotContent` and `IntrinsicContent`.
+ */
+export declare const Widget: ({ style, onLayout, children, testID }: WidgetProps) => React.JSX.Element;
+export type UseWidgetLayoutOptions = {
+    style?: StyleProp;
+    onLayout?: (event: LayoutEvent) => void;
+};
+/**
+ * The same thing as {@link Widget}, without the extra component — attach the
+ * ref yourself when you already hold one.
+ *
+ * ```tsx
+ * const ref = useRef<Gtk.Button | null>(null)
+ * useWidgetLayout(ref, { style: { width: 40, height: 40 } })
+ * return <GtkButton ref={ref} iconName="open-menu-symbolic" />
+ * ```
+ *
+ * Returns the GTK CSS class produced by the visual half of the style, or
+ * null — pass it to the widget's `cssClasses` if you want backgrounds and
+ * borders from the style to apply.
+ */
+export declare const useWidgetLayout: (ref: {
+    current: Gtk.Widget | null;
+}, options?: UseWidgetLayoutOptions) => string | null;
+export type ReactNativeLayoutProps = {
+    /** React Native style. The layout half drives Yoga, the visual half becomes
+     *  a GTK CSS class. Omit sizing and the widget's natural size wins. */
+    style?: StyleProp;
+    onLayout?: (event: LayoutEvent) => void;
+};
+export declare const wrapReactNative: <P extends object>(Component: ComponentType<P>, widgetName?: string) => ComponentType<P & ReactNativeLayoutProps>;