@ticatec/uniface-element 5.0.0 → 5.0.2

package/dist/navigation/nav_menu/NavigatorMenu.svelte.d.ts

@@ -1,10 +1,9 @@
 import type MenuItem from "./MenuItem";
-import type { OnMenuClick } from "./MenuItem";
-import type { IHierarchyData } from "../../lib";
+import type { MenuNode, OnMenuClick } from "./MenuItem";
 type GetText<T> = (item: T) => string;
 type Variant = 'vertical' | 'horizontal';
 interface Props {
-    menuItems: Array<IHierarchyData<MenuItem>>;
+    menuItems: Array<MenuNode>;
     style?: string;
     textField: string | GetText<MenuItem>;
     onItemClick: OnMenuClick;

package/dist/navigation/nav_menu/NavigatorMenuItem.svelte

@@ -1,13 +1,13 @@
 <script lang="ts">
     import {slide, fly} from "svelte/transition";
     import type MenuItem from "./MenuItem";
-    import type {OnMenuClick} from "./MenuItem";
-    import type {IHierarchyData} from "../../lib";
+    import type {MenuNode, OnMenuClick} from "./MenuItem";
+    import NavigatorMenuItem from "./NavigatorMenuItem.svelte";
 
     type GetText<T> = (item: T) => string;
 
     interface Props {
-        menu: IHierarchyData<MenuItem>;
+        menu: MenuNode;
         textField: string | GetText<MenuItem>;
         onMenuItemClick: OnMenuClick;
         defaultExpand?: boolean;
@@ -26,14 +26,17 @@
         cascade = false
     }: Props = $props();
 
-    let expand = $state(defaultExpand);
+    // defaultExpand seeds local interaction state once; subsequent prop changes must
+    // not overwrite a choice the user has already made.
+    const getInitialExpanded = () => defaultExpand;
+    let expand = $state(getInitialExpanded());
     let respond = $state(true);
     let liEl: HTMLElement;
     /** true = 子菜单飞到左边（右边空间不够时） */
     let flyLeft = $state(false);
 
-    let expandable = $derived(menu.children.length > 0);
-    let menuText = $derived(typeof textField == 'string' ? menu.data?.[textField] ?? 'Unknown item' : textField(menu.data));
+    let expandable = $derived(!!menu.children?.length);
+    let menuText = $derived(typeof textField == 'string' ? menu.item?.[textField] ?? 'Unknown item' : textField(menu.item));
 
     // 级联模式下，展开前先测一下右边够不够放子菜单
     const measureFlyout = () => {
@@ -53,16 +56,25 @@
                 }
                 expand = !expand;
             } else {
-                onMenuItemClick?.(menu.data);
+                onMenuItemClick?.(menu.item);
             }
         }
     }
+
+    function handleMenuItemKeyDown(e: KeyboardEvent) {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleMenuItemClick();
+        }
+    }
 </script>
 
 <li bind:this={liEl} class:expandable class:fold={!expand} class:cascade class:fly-left={flyLeft}>
     <span
         onclick={handleMenuItemClick}
-        aria-hidden="true"
+        onkeydown={handleMenuItemKeyDown}
+        role="button" tabindex="0"
+        aria-expanded={expandable ? expand : undefined}
     >
         <span class="label">{menuText}</span>
         {#if expandable}
@@ -74,14 +86,14 @@
     {#if expandable && expand}
         {#if cascade}
             <ul class="flyout" transition:fly={{duration: 200, x: flyLeft ? -20 : 20}}>
-                {#each menu.children as el}
-                    <svelte:self menu={el} {onMenuItemClick} {textField} {cascade}/>
+                {#each menu.children ?? [] as el}
+                    <NavigatorMenuItem menu={el} {onMenuItemClick} {textField} {cascade}/>
                 {/each}
             </ul>
         {:else}
             <ul class="inline" transition:slide={{duration: 200}}>
-                {#each menu.children as el}
-                    <svelte:self menu={el} {onMenuItemClick} {textField} {cascade}/>
+                {#each menu.children ?? [] as el}
+                    <NavigatorMenuItem menu={el} {onMenuItemClick} {textField} {cascade}/>
                 {/each}
             </ul>
         {/if}
@@ -168,4 +180,4 @@
         left: auto;
         right: 100%;
     }
-</style>
+</style>

package/dist/navigation/nav_menu/NavigatorMenuItem.svelte.d.ts

@@ -1,9 +1,9 @@
 import type MenuItem from "./MenuItem";
-import type { OnMenuClick } from "./MenuItem";
-import type { IHierarchyData } from "../../lib";
+import type { MenuNode, OnMenuClick } from "./MenuItem";
+import NavigatorMenuItem from "./NavigatorMenuItem.svelte";
 type GetText<T> = (item: T) => string;
 interface Props {
-    menu: IHierarchyData<MenuItem>;
+    menu: MenuNode;
     textField: string | GetText<MenuItem>;
     onMenuItemClick: OnMenuClick;
     defaultExpand?: boolean;

package/dist/navigation/navigator/Navigator.svelte

@@ -26,16 +26,23 @@
         activeItem = item;
         itemClickHandler?.(item);
     };
+
+    const handleKeyDown = (item: any) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleClick(item);
+        }
+    };
 </script>
 
 <div class="uniface-navigator-panel" {style}>
-    <div class="navigator-content">
+    <div class="navigator-content" role="list">
         {#each items as item}
             <div class="uniface-navigator-item {retrieveStatus?.(item) ?? NavItemStatus.Completed}"
                  class:active={activeItem === item}
                  class:highlight={highlights.indexOf(item) > -1}
-                 aria-hidden="true"
-                 onclick={() => handleClick(item)}>
+                 role="button" tabindex="0" aria-current={activeItem === item ? 'step' : undefined}
+                 onclick={() => handleClick(item)} onkeydown={handleKeyDown(item)}>
                 <span>{item.text}</span>
             </div>
         {/each}
@@ -44,15 +51,7 @@
 
 <style>
     .uniface-navigator-panel {
-        --uniface-navigator-background-color: var(--uniface-application-bg);
-        --uniface-navigator-vertical-padding: 16px;
-        --uniface-navigator-completed-text-color: #374151;
-        --uniface-navigator-not-start-text-color: #6B7280;
-        --uniface-navigator-warning-dot-color: #C62828;
-        --uniface-navigator-hover-text-color: #298DFF;
-        --uniface-navigator-active-text-color: #0061FF;
         --uniface-navigator-active-text-weight: 600;
-        --uniface-navigator-highlight-text-color: #0061FF;
 
         position: relative;
         width: 100%;
@@ -76,7 +75,7 @@
         font-size: 12px;
         padding: 4px 8px 4px 24px;
         position: relative;
-        background: linear-gradient(to right, transparent 12px, lightgray 12px, lightgray 13px, transparent 13px);
+        background: linear-gradient(to right, transparent 12px, var(--uniface-navigator-connector-color) 12px, var(--uniface-navigator-connector-color) 13px, transparent 13px);
     }
 
     .uniface-navigator-item:first-child {
@@ -134,14 +133,15 @@
     .uniface-navigator-item.active::before {
         content: "";
         position: absolute;
-        left: 5px;
+        left: 8px;
         top: 50%;
         transform: translateY(-50%);
-        width: 15px;
-        height: 15px;
-        border: 4px solid var(--uniface-navigator-active-text-color);
+        box-sizing: border-box;
+        width: 10px;
+        height: 10px;
+        border: 3px solid var(--uniface-navigator-active-text-color);
         border-radius: 50%;
-        background-color: white;
+        background-color: var(--uniface-navigator-background-color, white);
     }
 
     .uniface-navigator-item.active:hover {

package/dist/navigation/page-stack/PageStack.svelte

@@ -0,0 +1,160 @@
+<script lang="ts">
+    import {untrack} from 'svelte';
+    import type {Snippet} from 'svelte';
+    import type {TransitionConfig} from 'svelte/transition';
+    import {fly} from 'svelte/transition';
+    import {cubicOut} from 'svelte/easing';
+    import PageStackFrame from './PageStackFrame.svelte';
+    import {providePageStackContext} from './PageStackContext';
+
+    interface StackEntry {
+        id: string;
+        component: any;
+        props: Record<string, any>;
+        resolve: (value: any) => void;
+    }
+
+    type TransitionFn = (node: Element, params?: any) => TransitionConfig;
+
+    interface Props {
+        style?: string;
+        /** 每一帧 push/pop 的滑入滑出时长（ms）。仅在没有传 transitionParams 时生效；设为 0 关闭动画。 */
+        transitionDuration?: number;
+        /**
+         * 换成任意 svelte/transition 函数（fly/fade/scale/slide...）或自定义的过渡函数。
+         * 默认是从右侧滑入的 fly，效果同 transitionParams 未设置时的 {x:'100%', duration:transitionDuration, easing:cubicOut}。
+         */
+        transition?: TransitionFn;
+        /** 传给 transition 函数的参数；一旦提供，会完全替代基于 transitionDuration 生成的默认参数。 */
+        transitionParams?: Record<string, any>;
+        /** 根页面（初始内容，depth = 0） */
+        children?: Snippet;
+    }
+
+    let {
+        style = '',
+        transitionDuration = 260,
+        transition = fly,
+        transitionParams,
+        children
+    }: Props = $props();
+
+    let resolvedTransitionParams = $derived(
+        transitionParams ?? {x: '100%', duration: transitionDuration, easing: cubicOut}
+    );
+
+    let stack = $state<StackEntry[]>([]);
+
+    const generateId = (): string => `page_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+
+    function closeEntry(id: string, result?: any): void {
+        // untrack: push()/close()/reset() are meant to be callable from anywhere,
+        // including from inside a caller's own $effect (e.g. a page that
+        // auto-navigates further based on its props). Reading `stack` (to find/
+        // filter it) *and* writing it back in the same synchronous call would
+        // otherwise get attributed to whatever effect happens to be running at
+        // call time, and the write would then re-trigger that same effect —
+        // Svelte reports this as "effect reads and writes the same state" /
+        // effect_update_depth_exceeded. untrack() keeps this internal
+        // read+write from being picked up as a dependency of an unrelated,
+        // currently-running effect; existing subscribers of `stack` (the
+        // {#each} below) are unaffected — untrack only suppresses *new*
+        // spurious subscriptions created during this call.
+        let entry: StackEntry | undefined;
+        untrack(() => {
+            entry = stack.find(e => e.id === id);
+            if (!entry) return;
+            // 先移除再 resolve：resolve 可能同步触发调用方的后续逻辑（比如再次 push），
+            // 那时候这一帧必须已经不在栈里了。
+            stack = stack.filter(e => e.id !== id);
+        });
+        entry?.resolve(result);
+    }
+
+    /**
+     * push 一个组件进栈，覆盖显示在当前内容之上。返回的 Promise 在该页面调用
+     * getPageStack().close(result) 时以 result resolve；也可以用 PageStack 实例的
+     * pop(result) 从外部（比如 bottombar 的返回按钮）关闭当前栈顶。
+     */
+    export function push<R = any>(component: any, props: Record<string, any> = {}): Promise<R> {
+        return new Promise<R>(resolve => {
+            const id = generateId();
+            // see closeEntry() above for why this is wrapped in untrack()
+            untrack(() => {
+                stack = [...stack, {id, component, props, resolve: resolve as (v: any) => void}];
+            });
+        });
+    }
+
+    /** 关闭当前栈顶的一帧。栈为空时是 no-op。 */
+    export function pop(result?: any): void {
+        const top = stack[stack.length - 1];
+        if (top) closeEntry(top.id, result);
+    }
+
+    /** 清空整个栈，直接回到根页面。不逐帧过渡，适合"注销/切换上下文"这类场景。 */
+    export function reset(): void {
+        // see closeEntry() above for why this is wrapped in untrack()
+        let entries: StackEntry[] = [];
+        untrack(() => {
+            entries = stack;
+            stack = [];
+        });
+        entries.forEach(entry => entry.resolve(undefined));
+    }
+
+    // 根页面（children）本身也活在这个 context 里，depth = 0，close() 是 no-op——
+    // 根页面不是被 push 进来的，没有"关闭返回上一层"的语义，但它应该能拿到 push()
+    // 来发起第一层导航，不需要额外用 bind:this 去引用 PageStack 实例。
+    providePageStackContext({
+        close: () => {
+            if (typeof console !== 'undefined') {
+                console.warn('[PageStack] root page has no close() semantics — it was not pushed onto the stack');
+            }
+        },
+        push,
+        depth: 0
+    });
+</script>
+
+<div class="uniface-page-stack" {style}>
+    <div class="page-stack-root" inert={stack.length > 0}>
+        {@render children?.()}
+    </div>
+    {#each stack as entry, i (entry.id)}
+        <div class="page-stack-frame" style="z-index: {i + 1}" inert={i < stack.length - 1}
+             transition:transition={resolvedTransitionParams}>
+            <PageStackFrame
+                    id={entry.id}
+                    component={entry.component}
+                    props={entry.props}
+                    depth={i + 1}
+                    close={(result) => closeEntry(entry.id, result)}
+                    {push}
+            />
+        </div>
+    {/each}
+</div>
+
+<style>
+    .uniface-page-stack {
+        width: 100%;
+        height: 100%;
+        position: relative;
+        overflow: hidden;
+        box-sizing: border-box;
+    }
+
+    .page-stack-root {
+        width: 100%;
+        height: 100%;
+        position: relative;
+    }
+
+    .page-stack-frame {
+        position: absolute;
+        inset: 0;
+        overflow: auto;
+        background-color: var(--uniface-page-stack-color-surface, var(--uniface-color-surface));
+    }
+</style>

package/dist/navigation/page-stack/PageStack.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Snippet } from 'svelte';
+import type { TransitionConfig } from 'svelte/transition';
+type TransitionFn = (node: Element, params?: any) => TransitionConfig;
+interface Props {
+    style?: string;
+    /** 每一帧 push/pop 的滑入滑出时长（ms）。仅在没有传 transitionParams 时生效；设为 0 关闭动画。 */
+    transitionDuration?: number;
+    /**
+     * 换成任意 svelte/transition 函数（fly/fade/scale/slide...）或自定义的过渡函数。
+     * 默认是从右侧滑入的 fly，效果同 transitionParams 未设置时的 {x:'100%', duration:transitionDuration, easing:cubicOut}。
+     */
+    transition?: TransitionFn;
+    /** 传给 transition 函数的参数；一旦提供，会完全替代基于 transitionDuration 生成的默认参数。 */
+    transitionParams?: Record<string, any>;
+    /** 根页面（初始内容，depth = 0） */
+    children?: Snippet;
+}
+declare const PageStack: import("svelte").Component<Props, {
+    push: <R = any>(component: any, props?: Record<string, any>) => Promise<R>;
+    pop: (result?: any) => void;
+    reset: () => void;
+}, "">;
+type PageStack = ReturnType<typeof PageStack>;
+export default PageStack;

package/dist/navigation/page-stack/PageStackContext.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 每一层被 push 进 PageStack 的页面组件，都可以通过 getPageStack() 拿到这个 API。
+ * 根页面（PageStack 的 children）同样能拿到（depth = 0），但它的 close() 是 no-op——
+ * 根页面不是被 push 进来的，没有"关闭并返回上一层"这个语义。
+ */
+export interface PageStackApi<T = any> {
+    /**
+     * 关闭当前页面。对应这一页 push() 时返回的 Promise 会以 result resolve。
+     * 根页面调用无效果（会在开发模式下打一条 warning）。
+     */
+    close: (result?: T) => void;
+    /**
+     * 在当前页面之上继续 push 一个新页面，和 PageStack 实例上的 push() 是同一个函数——
+     * 多级 drill-down 时不需要一路把最外层的 PageStack 引用传下去。
+     */
+    push: <R = any>(component: any, props?: Record<string, any>) => Promise<R>;
+    /** 当前页面在栈中的深度，根页面为 0，第一层 push 进来的页面为 1，以此类推。 */
+    depth: number;
+}
+export declare function providePageStackContext(api: PageStackApi): void;
+/**
+ * 在被 PageStack push 进来的页面组件（或它的任意后代）里调用，拿到 {close, push, depth}。
+ * 在 PageStack 之外调用返回 undefined。
+ */
+export declare function getPageStack<T = any>(): PageStackApi<T> | undefined;

package/dist/navigation/page-stack/PageStackContext.js

@@ -0,0 +1,12 @@
+import { getContext, setContext, hasContext } from 'svelte';
+const CONTEXT_KEY = 'uniface-page-stack';
+export function providePageStackContext(api) {
+    setContext(CONTEXT_KEY, api);
+}
+/**
+ * 在被 PageStack push 进来的页面组件（或它的任意后代）里调用，拿到 {close, push, depth}。
+ * 在 PageStack 之外调用返回 undefined。
+ */
+export function getPageStack() {
+    return hasContext(CONTEXT_KEY) ? getContext(CONTEXT_KEY) : undefined;
+}

package/dist/navigation/page-stack/PageStackFrame.svelte

@@ -0,0 +1,24 @@
+<script lang="ts">
+    import {providePageStackContext} from './PageStackContext';
+
+    interface Props {
+        id: string;
+        component: any;
+        props: Record<string, any>;
+        depth: number;
+        close: (result?: any) => void;
+        push: <R = any>(component: any, props?: Record<string, any>) => Promise<R>;
+    }
+
+    let {id, component: Comp, props, depth, close, push}: Props = $props();
+
+    // Context identity is fixed for the lifetime of this frame — mirrors
+    // DialogWrapper's getInitialDialogId pattern (overlay/dialog/DialogWrapper.svelte):
+    // later prop changes (e.g. depth staying the same but close/push identity
+    // churning on parent re-render) must not replace what this frame's
+    // descendants already captured via getPageStack().
+    const getInitialContext = () => ({close, push, depth});
+    providePageStackContext(getInitialContext());
+</script>
+
+<Comp {...props}/>

package/dist/navigation/page-stack/PageStackFrame.svelte.d.ts

@@ -0,0 +1,11 @@
+interface Props {
+    id: string;
+    component: any;
+    props: Record<string, any>;
+    depth: number;
+    close: (result?: any) => void;
+    push: <R = any>(component: any, props?: Record<string, any>) => Promise<R>;
+}
+declare const PageStackFrame: import("svelte").Component<Props, {}, "">;
+type PageStackFrame = ReturnType<typeof PageStackFrame>;
+export default PageStackFrame;

package/dist/navigation/page-stack/README.md

@@ -0,0 +1,154 @@
+# PageStack
+
+A local (non-modal) navigation stack: push a component to cover the current content with a new "page", and let it close itself to return to what was underneath. Built for the common app-shell shape — a persistent top bar / bottom bar with a content area that drills down into sub-pages — without pulling in routing.
+
+Targets **Svelte 5** and the snippet API. Unlike `Dialog` (`overlay/dialog`), `PageStack` is **not** a global singleton and does **not** portal to `<body>`: each instance owns its own stack, is scoped to whatever container it's rendered in, and multiple independent instances can coexist on the same screen.
+
+[中文文档](./README_CN.md)
+
+## Import
+
+```svelte
+<script lang="ts">
+  import PageStack, {getPageStack} from '@ticatec/uniface-element/PageStack';
+  import type {PageStackApi} from '@ticatec/uniface-element/PageStack';
+</script>
+```
+
+## Basic usage
+
+```svelte
+<script lang="ts">
+  import PageStack from '@ticatec/uniface-element/PageStack';
+  import DetailPage from './DetailPage.svelte';
+
+  let stack: PageStack;
+
+  async function openDetail(id: string) {
+    const result = await stack.push(DetailPage, {id});
+    console.log('detail closed with', result);
+  }
+</script>
+
+<PageStack bind:this={stack}>
+  <HomePage onSelect={openDetail}/>
+</PageStack>
+```
+
+Inside `DetailPage.svelte`, close itself (optionally returning a value) via context — no need to thread a reference to the `PageStack` instance down through props:
+
+```svelte
+<script lang="ts">
+  import {getPageStack} from '@ticatec/uniface-element/PageStack';
+
+  interface Props { id: string }
+  let {id}: Props = $props();
+
+  const stackApi = getPageStack();
+</script>
+
+<button onclick={() => stackApi?.close({saved: true})}>Save & back</button>
+<button onclick={() => stackApi?.close()}>Cancel</button>
+```
+
+## Composing with the app-shell layouts
+
+`PageStack` only owns the "content area drills down into pages" behavior. Combine it with `app-layout`'s `RowsLayout` (or `HeaderLayout`) for the persistent top bar / bottom bar chrome:
+
+```svelte
+<script lang="ts">
+  import {RowsLayout} from '@ticatec/uniface-element/app-layout';
+  import PageStack from '@ticatec/uniface-element/PageStack';
+
+  let stack: PageStack;
+</script>
+
+<RowsLayout topHeight="48px" bottomHeight="56px">
+  {#snippet top()}<TopBar/>{/snippet}
+  {#snippet bottom()}<BottomBar onBack={() => stack.pop()}/>{/snippet}
+
+  <PageStack bind:this={stack}>
+    <HomePage/>
+  </PageStack>
+</RowsLayout>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `style` | `string` | `''` | Inline style applied to the root element |
+| `transitionDuration` | `number` | `260` | Used to build the default transition params (`{x: '100%', duration, easing: cubicOut}`) when `transitionParams` isn't set. `0` disables the animation. Ignored once `transitionParams` is provided. |
+| `transition` | `(node, params?) => TransitionConfig` | `fly` (slide in from the right) | Swap in any `svelte/transition` function (`fade`, `scale`, `slide`, `fly`, ...) or a custom one — see below. |
+| `transitionParams` | `Record<string, any>` | — | Params passed to `transition`. Once set, it fully replaces the `transitionDuration`-derived default — include `duration`/`easing` yourself if you need them. |
+| `children` | `Snippet` | — | Root page content (depth `0`) |
+
+### Changing the push/pop animation
+
+By default each pushed frame slides in from the right (`fly`, matching the common mobile drill-down feel). Swap it for any other `svelte/transition` — or turn it off — via `transition`/`transitionParams`:
+
+```svelte
+<script lang="ts">
+  import PageStack from '@ticatec/uniface-element/PageStack';
+  import {fade} from 'svelte/transition';
+</script>
+
+<!-- cross-fade instead of sliding -->
+<PageStack transition={fade} transitionParams={{duration: 200}}>
+  ...
+</PageStack>
+
+<!-- slide in from the left instead of the right -->
+<PageStack transitionParams={{x: '-100%', duration: 200}}>
+  ...
+</PageStack>
+
+<!-- no animation at all -->
+<PageStack transitionDuration={0}>
+  ...
+</PageStack>
+```
+
+A custom function works too, as long as it matches Svelte's transition signature `(node, params) => {duration?, easing?, css?, tick?}`:
+
+```svelte
+<script lang="ts">
+  function popIn(node: Element, {duration = 200} = {}) {
+    return {
+      duration,
+      css: (t: number) => `transform: scale(${0.9 + t * 0.1}); opacity: ${t}`
+    };
+  }
+</script>
+
+<PageStack transition={popIn} transitionParams={{duration: 150}}>
+  ...
+</PageStack>
+```
+
+## Instance methods (`bind:this`)
+
+| Method | Description |
+|--------|-------------|
+| `push<R>(component, props?): Promise<R>` | Pushes a component on top of the stack, covering the current content. Resolves with whatever value the pushed page passes to `close()` (or `pop()`'s argument, or `undefined` if the stack is `reset()`). |
+| `pop(result?): void` | Closes the current top frame from outside (e.g. a bottom bar back button). No-op if the stack is empty. |
+| `reset(): void` | Clears the whole stack immediately (no transition) and resolves every pending `push()` promise with `undefined`. Useful for "sign out / switch context" flows. |
+
+## Context API (for a pushed page itself)
+
+`getPageStack()` returns `undefined` outside a `PageStack`, and a `PageStackApi` for anything rendered inside one — both the root (`children`, depth `0`) and any pushed frame (depth `1`, `2`, ...):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `close` | `(result?) => void` | Closes *this* page. On the root page this is a no-op (logs a dev warning) — the root wasn't pushed, so it has nothing to "return" to. |
+| `push` | `<R>(component, props?) => Promise<R>` | Same function as the `PageStack` instance's `push` — lets a pushed page drill down further without a reference to the outer component. |
+| `depth` | `number` | This page's depth in the stack. `0` for the root. |
+
+## Popups inside a pushed page
+
+No special handling needed. `Dialog` / `Popover` / `FloatingPanel` mount to `document.body` (see `overlay/common/mountSingleton.ts`), so they are never DOM descendants of a `PageStack` frame — a `transform`-based push/pop animation on the frame wrapper can't clip or reposition them. The one thing to avoid: a page hand-rolling its own `position: fixed` element instead of using the library's overlay components — that *would* get trapped by the frame's `transform` during the transition.
+
+## Notes
+
+- Only the top frame is interactive; earlier frames stay mounted underneath (not `display: none`) purely so the slide transition has something to reveal. They're marked `inert` (removed from tab order and hit-testing) while covered, so this is a visual keep-behind, not a "keep-alive/preserve scroll position" mechanism today.
+- Every pushed frame is a fresh mount. If you need to preserve a page's state across a push/pop round trip, keep that state in the caller (the component that called `push`) and pass it back in via `props`, or lift it into a store.