@ticatec/topside-elements 1.0.0

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="topside-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>
+    .topside-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(--topside-page-stack-color-surface, var(--topside-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 = 'topside-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/topside-elements/PageStack';
+  import type {PageStackApi} from '@ticatec/topside-elements/PageStack';
+</script>
+```
+
+## Basic usage
+
+```svelte
+<script lang="ts">
+  import PageStack from '@ticatec/topside-elements/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/topside-elements/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/topside-elements/app-layout';
+  import PageStack from '@ticatec/topside-elements/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/topside-elements/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.

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

@@ -0,0 +1,154 @@
+# PageStack
+
+一个局部（非模态）的导航栈：push 一个组件覆盖当前内容区，呈现为一个新"页面"；这个页面可以自己关闭，回到下面被覆盖的内容。适用于最常见的 App 外壳形态——固定的 topbar/bottombar + 一个可以不断"钻进"子页面的内容区，且不依赖任何路由方案。
+
+面向 **Svelte 5**，使用 snippet API。和 `Dialog`（`overlay/dialog`）不同，`PageStack` **不是全局单例**，也**不会**挂载到 `<body>` 上——每个实例拥有自己独立的栈，作用域仅限于它被渲染的那个容器，一个页面里可以同时存在多个互不干扰的 `PageStack` 实例。
+
+[English](./README.md)
+
+## 引入
+
+```svelte
+<script lang="ts">
+  import PageStack, {getPageStack} from '@ticatec/topside-elements/PageStack';
+  import type {PageStackApi} from '@ticatec/topside-elements/PageStack';
+</script>
+```
+
+## 基本用法
+
+```svelte
+<script lang="ts">
+  import PageStack from '@ticatec/topside-elements/PageStack';
+  import DetailPage from './DetailPage.svelte';
+
+  let stack: PageStack;
+
+  async function openDetail(id: string) {
+    const result = await stack.push(DetailPage, {id});
+    console.log('详情页关闭，结果:', result);
+  }
+</script>
+
+<PageStack bind:this={stack}>
+  <HomePage onSelect={openDetail}/>
+</PageStack>
+```
+
+在 `DetailPage.svelte` 内部，通过 context 拿到 `close`，自己关闭自己（可选带一个返回值）——不需要把 `PageStack` 实例一路通过 props 传下去：
+
+```svelte
+<script lang="ts">
+  import {getPageStack} from '@ticatec/topside-elements/PageStack';
+
+  interface Props { id: string }
+  let {id}: Props = $props();
+
+  const stackApi = getPageStack();
+</script>
+
+<button onclick={() => stackApi?.close({saved: true})}>保存并返回</button>
+<button onclick={() => stackApi?.close()}>取消</button>
+```
+
+## 和外壳布局组合使用
+
+`PageStack` 只负责"内容区可以 push/pop 子页面"这一件事。持久的 topbar/bottombar 外壳交给 `app-layout` 里的 `RowsLayout`（或 `HeaderLayout`）来组合：
+
+```svelte
+<script lang="ts">
+  import {RowsLayout} from '@ticatec/topside-elements/app-layout';
+  import PageStack from '@ticatec/topside-elements/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 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `style` | `string` | `''` | 根元素的行内样式 |
+| `transitionDuration` | `number` | `260` | 用来拼出默认的过渡参数（`{x: '100%', duration, easing: cubicOut}`），仅在没有传 `transitionParams` 时生效；设为 `0` 关闭动画。一旦传了 `transitionParams`，这个值会被忽略。 |
+| `transition` | `(node, params?) => TransitionConfig` | `fly`（从右侧滑入） | 换成任意 `svelte/transition` 函数（`fade`、`scale`、`slide`、`fly`……）或者自定义函数，见下面。 |
+| `transitionParams` | `Record<string, any>` | — | 传给 `transition` 的参数。一旦设置，会完全替代基于 `transitionDuration` 生成的默认参数——需要 `duration`/`easing` 的话要自己带上。 |
+| `children` | `Snippet` | — | 根页面内容（深度为 `0`） |
+
+### 更换 push/pop 的动画效果
+
+默认每一帧从右侧滑入（`fly`，贴近常见的移动端"钻入下一层"观感）。通过 `transition`/`transitionParams` 换成任意 `svelte/transition`，或者干脆关掉：
+
+```svelte
+<script lang="ts">
+  import PageStack from '@ticatec/topside-elements/PageStack';
+  import {fade} from 'svelte/transition';
+</script>
+
+<!-- 换成淡入淡出，而不是滑动 -->
+<PageStack transition={fade} transitionParams={{duration: 200}}>
+  ...
+</PageStack>
+
+<!-- 从左侧滑入，而不是右侧 -->
+<PageStack transitionParams={{x: '-100%', duration: 200}}>
+  ...
+</PageStack>
+
+<!-- 完全关闭动画 -->
+<PageStack transitionDuration={0}>
+  ...
+</PageStack>
+```
+
+自定义函数也可以，只要符合 Svelte 过渡函数的签名 `(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>
+```
+
+## 实例方法（通过 `bind:this` 调用）
+
+| 方法 | 说明 |
+|------|------|
+| `push<R>(component, props?): Promise<R>` | 把一个组件 push 到栈顶，覆盖当前内容。返回的 Promise 会在该页面调用 `close()` 时以其传入值 resolve（或被外部 `pop()` 的参数 resolve，或在 `reset()` 时以 `undefined` resolve）。 |
+| `pop(result?): void` | 从外部关闭当前栈顶的一帧（例如 bottombar 上的返回按钮）。栈为空时是 no-op。 |
+| `reset(): void` | 立即清空整个栈（不做过渡动画），并把所有还没 resolve 的 `push()` Promise 以 `undefined` resolve。适合"注销登录、切换上下文"这类场景。 |
+
+## Context API（供被 push 进来的页面使用）
+
+`getPageStack()` 在 `PageStack` 之外调用返回 `undefined`；在 `PageStack` 内部（无论是根页面 `children`，还是任意一层被 push 进来的页面）调用都能拿到一个 `PageStackApi`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `close` | `(result?) => void` | 关闭*当前*这一页。在根页面上调用是 no-op（会打一条开发环境的 warning）——根页面不是被 push 进来的，没有"返回上一层"这个语义。 |
+| `push` | `<R>(component, props?) => Promise<R>` | 和 `PageStack` 实例上的 `push` 是同一个函数，让被 push 进来的页面可以继续往下钻，不需要拿到外层组件的引用。 |
+| `depth` | `number` | 当前页面在栈中的深度，根页面为 `0`。 |
+
+## 被 push 的页面内部弹出 Dialog/Popover 等浮层
+
+不需要任何特殊处理。`Dialog` / `Popover` / `FloatingPanel` 都是挂载到 `document.body` 上的（见 `overlay/common/mountSingleton.ts`），并不是 `PageStack` 某一帧的 DOM 后代，所以帧上基于 `transform` 的滑入滑出动画不会影响、裁剪或错位它们的定位。唯一要避免的是：页面自己手写一个 `position: fixed` 的元素而不是用库里现成的浮层组件——那样的元素才会在过渡动画期间被帧的 `transform` "困住"。
+
+## 说明
+
+- 只有栈顶的一帧可交互；更早的帧仍然挂载在下面（不是 `display: none`），纯粹是为了让滑动过渡有内容可以"揭示"出来。被覆盖时它们会被标记为 `inert`（移出 Tab 顺序和点击命中），所以这只是"视觉上留在后面"，目前还不是"保活/保留滚动位置"机制。
+- 每次 push 都是全新挂载。如果需要在 push/pop 一个来回之后保留某个页面的状态，把状态放在调用方（发起 `push` 的那个组件）里，再通过 `props` 传回去，或者提到某个 store 里。

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

@@ -0,0 +1,6 @@
+import PageStack from './PageStack.svelte';
+import { getPageStack } from './PageStackContext';
+import type { PageStackApi } from './PageStackContext';
+export default PageStack;
+export { getPageStack };
+export type { PageStackApi };

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

@@ -0,0 +1,4 @@
+import PageStack from './PageStack.svelte';
+import { getPageStack } from './PageStackContext';
+export default PageStack;
+export { getPageStack };