@astryx-vue/core 0.3.0 → 0.4.0

package/dist/{index-T2FOcOuI.d.ts → index-jOwU3YoR.d.ts}

@@ -1,8 +1,8 @@
 import { n as LayerPlacement, t as LayerAlignment } from "./position-DFW5ymAF.js";
-import "./useAsyncSource-xpQovjV_.js";
-import { o as FieldStatusInput } from "./types-0Q_SJv_F.js";
+import "./useAsyncSource-aGzrvRkI.js";
+import { o as FieldStatusInput } from "./types-Bb7OGivY.js";
 import "./useClipboard-CU-kfqeJ.js";
-import "./useResizable-DDwPpPe6.js";
+import "./useResizable-1MHPNaRD.js";
 import { CSSProperties, Component, ComponentPublicInstance, ComputedRef, InjectionKey, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
 import { CalendarDate } from "@internationalized/date";
 //#region src/composables/useDateRange.d.ts
@@ -176,6 +176,8 @@ interface ClickableContainerHandlers {
   onClick: (event: MouseEvent) => void;
   onMouseUp: (event: MouseEvent) => void;
 }
+declare function hasInteractiveAncestor(element: Element, root: Element): boolean;
+declare function hasTextSelection(node: Element): boolean;
 /**
  * 把容器的 click / mouseup 交给调用方绑到根元素上。
  * 组件挂载后会给容器加上 `data-pressable-container`，嵌套的可点容器因此不会互相抢走点击。
@@ -335,6 +337,7 @@ declare function shiftTime(value: string, minuteDelta: number, hasSeconds: boole
 declare function isTimeInRange(value: string, min?: string, max?: string): boolean;
 type TimePresentation = 'text-input' | 'popover' | 'bottom-sheet' | 'native' | 'adaptive-bottom-sheet' | 'adaptive-native';
 type NativePicker = 'touch' | 'always' | 'never';
+type TimeSurface = 'text' | 'native' | 'sheet';
 declare function resolveTimeSurface(options: {
   presentation?: TimePresentation;
   nativePicker?: NativePicker;
@@ -343,7 +346,7 @@ declare function resolveTimeSurface(options: {
   increment: number;
   /** 额外的“系统控件表达不了”的信号，例如预设时间列表。 */
   needsTypedField?: boolean;
-}): 'text' | 'native';
+}): TimeSurface;
 //#endregion
 //#region src/composables/useDatePresentation.d.ts
 /** Which surface collects a date. The text-only option belongs to the time field. */
@@ -394,16 +397,45 @@ type DisclosureHandleRef = Ref<DisclosureHandle | null> | ((handle: DisclosureHa
  */
 declare function useDisclosureHandle(read: () => DisclosureHandleRef | undefined, handle: DisclosureHandle): void;
 //#endregion
+//#region src/layer/dismissStack.d.ts
+/**
+ * 全页面共用的「浮层关闭栈」。
+ *
+ * 以前每一个浮层各自在 document 上挂一套 pointerdown 和 keydown 监听，
+ * 结果按一次 Escape 会把所有开着的层一起关掉：Dialog 里开一个下拉菜单，
+ * 一次 Escape 连 Dialog 也关了。这里把这件事收成一处：
+ *
+ * - document 上只有一套监听，栈里有层才挂上去，栈空了就摘掉。
+ * - Escape 永远只看「最上面那一层」：`'close'` 关掉它，`'block'` 吃掉按键但不关，
+ *   `'ignore'` 留给这一层自己处理。不会把按键交给下面那层。
+ * - 点在某一层里面（含它的触发器）就只关掉它上面那些层，这一层自己不动；
+ *   点在所有层外面时只关最上面那一层。
+ *
+ * 「哪一层在上面」用三条线索判断，和上游一致：嵌套深度（组件树里更深的在上，
+ * Teleport 切不断）、容器互相包含（同一深度时，DOM 上包着别人的在上），
+ * 以及每个身份只认一次的序号（同一层重新登记时不许插队）。
+ */
+/**
+ * Escape 到达某一层时的三种处理。
+ *
+ * 按键永远只打最上面那一层，没有「让给下面」这一档。
+ */
+type DismissEscape = 'close' | 'block' | 'ignore';
+//#endregion
 //#region src/composables/useDismiss.d.ts
 interface UseDismissOptions {
   /** 要监听点击外部的容器元素 */
   container: Ref<HTMLElement | null>;
   /** 触发器元素（点击它不算点击外部） */
   trigger?: Ref<HTMLElement | null>;
-  /** 是否启用点击外部关闭 */
+  /** 是否启用关闭 */
   isEnabled: Ref<boolean>;
-  /** 是否启用 Escape 键关闭 */
-  enableEscape?: Ref<boolean>;
+  /**
+   * Escape 到达这一层时怎么处理。
+   * `'close'` 关掉，`'block'` 吃掉按键但不关，`'ignore'` 留给自己会
+   * `preventDefault` 的输入组件。默认 `'close'`。
+   */
+  dismissOnEscape?: MaybeRefOrGetter<DismissEscape>;
   /** 关闭回调 */
   onDismiss: () => void;
   /**
@@ -416,10 +448,12 @@ interface UseDismissOptions {
  * 统一处理浮层组件的关闭逻辑：点击外部和按 Escape 键。
  * 用于 Popover、Tooltip、DropdownMenu、ContextMenu 等。
  *
- * 设计决策：
- * - 使用 pointerdown 事件（包含 mouse 和 touch）
- * - 在 nextTick 后附加监听器，避免打开时的点击立即触发关闭
- * - Escape 键使用全局栈，确保最内层的浮层优先处理
+ * 真正的判定在 `layer/dismissStack.ts` 里：全页面共用一个关闭栈，
+ * 一次点外面只关最上面那一层，Escape 也只打最上面那一层。这里只负责在
+ * `isEnabled` 变真时把这一层登记进去，变假或作用域销毁时摘出来。
+ *
+ * 因为所有浮层都走这个入口，用它的组件自动获得了「只关最上面一层」的行为，
+ * 组件自己不用改。
  */
 declare function useDismiss(options: UseDismissOptions): void;
 //#endregion
@@ -500,7 +534,7 @@ interface UseFocusTrapOptions {
   isEnabled?: MaybeRefOrGetter<boolean>;
   /** 同一个开关，原版的名字。两者任一为真即启用。 */
   isActive?: MaybeRefOrGetter<boolean>;
-  /** 容器里按下 Escape 时调用。不传就不管这个键。 */
+  /** 容器里按下 Escape 时调用。不传就不管这个键。输入法拼字时的 Escape 不算。 */
   onEscape?: () => void;
   /** 初始焦点目标（可选） */
   initialFocus?: () => HTMLElement | null;
@@ -520,7 +554,11 @@ interface FocusTrap {
  * 用于模态对话框、抽屉等需要限制焦点范围的浮层组件。
  *
  * 打开时把焦点送进容器，关闭或卸载时把焦点还给打开前聚焦的元素；
- * 焦点从没进过容器、或者已经被别处拿走时不还。
+ * 焦点从没进过容器、或者已经被别处拿走时不还。还焦点时焦点环跟着上一次的输入走：
+ * 用鼠标或手指关掉的，回到触发器上不画环。
+ *
+ * Tab 只在焦点真的在陷阱里面时才被拦下。浮层开着、焦点却合理地留在外面
+ * （例如挂在输入框上的列表框）时，拦下 Tab 会让整个页面都没法用 Tab。
  */
 declare function useFocusTrap(options?: UseFocusTrapOptions): FocusTrap;
 //#endregion
@@ -956,6 +994,36 @@ interface UseLayerReturn {
  */
 declare function useLayer(options: UseLayerOptions): UseLayerReturn;
 //#endregion
+//#region src/composables/useLayerMountTarget.d.ts
+/**
+ * 读最近的浮层挂载点。Dialog 打开时是它内部的挂载点，其余情况是 `null`。
+ *
+ * 挂载点是「浮层内容实际挂到哪个 DOM 元素里」。浮层平时挂在 `body`，
+ * 但 Dialog 打开时它是一个原生模态层，挂在外面的浮层会被压住、点不到，
+ * 所以要先问一句。
+ */
+declare function useLayerMountTarget(): Readonly<Ref<HTMLElement | null>>;
+/**
+ * 读最近的浮层挂载点，并算成可以直接给 `Teleport` 的 `to`。
+ * 没有挂载点就是 `'body'`。
+ *
+ * ```vue
+ * <Teleport :to="teleportTarget">
+ * ```
+ */
+declare function useLayerTeleportTarget(): ComputedRef<string | HTMLElement>;
+/**
+ * 浮层该挂到哪。
+ *
+ * Dialog 提供了挂载点时优先用它，再往外挂就出了模态层。
+ * 否则看触发器旁边有没有不能挂浮层的祖先（段落、链接、按钮）。
+ * 有的话挂到那个祖先的外面、尽量靠近原位，嵌套主题和 Tab 顺序还在。
+ * 两边都没有，才挂到 `body`。
+ *
+ * `sentinel` 是触发器所在的元素。函数看的是它的父元素。
+ */
+declare function useResolvedLayerTeleport(sentinel: Ref<HTMLElement | null>): ComputedRef<string | HTMLElement>;
+//#endregion
 //#region src/composables/useListFocus.d.ts
 /**
  * 一维列表的方向。
@@ -986,7 +1054,7 @@ interface UseListFocusOptions {
    * 导航方向。
    * @default 'vertical'
    */
-  orientation?: ListFocusOrientation;
+  orientation?: MaybeRefOrGetter<ListFocusOrientation>;
   /**
    * Home / End 是否跳到第一项 / 最后一项。
    * @default true
@@ -1075,8 +1143,9 @@ interface LongPressHandlers {
  * surface. The press is cancelled when the finger travels past the tolerance,
  * lifts, a second finger lands, or the touch is cancelled.
  *
- * 两种绑法：自己接指针事件时用 `start` / `moveTo` / `cancel`；直接要触摸监听时
- * 把 `handlers` 摊到元素上。
+ * 两种绑法，同一个检测器：直接要触摸监听时把 `handlers` 摊到元素上；
+ * 自己已经在跑指针事件状态机时（`useMenuPress` 就是）调 `start` / `moveTo` / `cancel`。
+ * 按住时长、移动容差、计时器都在这里，所以长按在右键菜单和菜单触发器上是同一个意思。
  */
 declare function useLongPress(options: LongPressOptions): LongPressHandlers;
 //#endregion
@@ -1090,80 +1159,179 @@ declare function useLongPress(options: LongPressOptions): LongPressHandlers;
  */
 declare function useMediaQuery(query: string): Ref<boolean>;
 //#endregion
-//#region src/ContextMenu/useMenuPress.d.ts
-/** Forget an armed swallower. Called when a surface unmounts and in tests. */
+//#region src/composables/internal/menuPressGesture.d.ts
+/**
+ * 菜单按压的纯状态机。不碰 DOM，每一步都能脱离浏览器单测。
+ *
+ * 所有菜单和选择器共用这一套：指针**松开**时下面是哪一行，就由哪一行执行；
+ * 按住期间高亮跟着指针走。macOS 和 iOS 的菜单就是这样。
+ *
+ * 状态：
+ * - `idle`：没有手势。
+ * - `triggerPress`：手指按在触发器上，菜单还没开。鼠标不经过这一步，按下就开。
+ * - `open`：菜单在按住的指针下面打开了（鼠标按下，或手指按满长按时间），指针还没进菜单。
+ * - `tracking`：指针按着，高亮跟着它。
+ *
+ * 落定规则：打开菜单的那次按压，只有指针进过菜单、或者按满 `MENU_PRESS_SETTLE_MS`，
+ * 松开时才执行；否则什么都不执行，菜单保持打开。没有这条，一个在指针下面弹出的菜单
+ * 会替用户挑一行谁都没选的。
+ *
+ * 行是不透明的 `T`：调用方把指针下可用的那一行找出来喂进来，`null` 表示指针在分割线、
+ * 标题、禁用行上，或者在菜单外。
+ */
+/** 打开菜单的那次按压至少要按多久，松开时才能执行。 */
+declare const MENU_PRESS_SETTLE_MS = 300;
+type MenuPressPointerType = 'mouse' | 'touch' | 'pen';
+type MenuPressGesture<T> = {
+  phase: 'idle';
+} | {
+  phase: 'triggerPress';
+  pointerType: MenuPressPointerType;
+  startedAt: number;
+} | {
+  phase: 'open';
+  pointerType: MenuPressPointerType;
+  openedAt: number;
+} | {
+  phase: 'tracking';
+  pointerType: MenuPressPointerType;
+  /** 按压从哪里开始。 */
+  origin: 'trigger' | 'menu';
+  /** 指针下面当前那一行可用的行。 */
+  row: T | null;
+};
+type MenuPressEvent<T> = {
+  type: 'down';
+  target: 'trigger' | 'menu';
+  pointerType: MenuPressPointerType;
+  /** 落在菜单里时，按下位置那一行可用的行。 */
+  row: T | null;
+  time: number;
+} |
+/** 触发器上的按压还按着，菜单开了。 */
+{
+  type: 'opened';
+  time: number;
+} | {
+  type: 'move';
+  row: T | null;
+  isInMenu: boolean;
+  time: number;
+} | {
+  type: 'up';
+  row: T | null;
+  isInMenu: boolean;
+  isOnTrigger: boolean;
+  time: number;
+} |
+/** 浏览器拿走了手势：pointercancel、第二根手指、滚动。 */
+{
+  type: 'cancel';
+};
+type MenuPressEffect<T> = {
+  type: 'none';
+} |
+/** 鼠标按下触发器：现在就在按住的指针下面打开菜单。 */
+{
+  type: 'open';
+} | {
+  type: 'highlight';
+  row: T;
+} | {
+  type: 'clear';
+} | {
+  type: 'act';
+  row: T;
+} |
+/**
+ * 手势结束，没有行执行。`stray` 表示浏览器还会为这次手势补一个 click，
+ * 必须吞掉；`dismiss` 表示菜单该关（鼠标在菜单外松开）。
+ */
+{
+  type: 'settle';
+  stray: boolean;
+  dismiss: boolean;
+};
+interface MenuPressStep<T> {
+  gesture: MenuPressGesture<T>;
+  effect: MenuPressEffect<T>;
+}
+/** 往前走一步。纯函数：同样的输入，同样的输出。 */
+declare function menuPressStep<T>(gesture: MenuPressGesture<T>, event: MenuPressEvent<T>): MenuPressStep<T>;
+//#endregion
+//#region src/composables/internal/menuPressDom.d.ts
+/** 带这个标记的菜单根用的是按压模型。嵌套的飞出层靠它分清一次按压归哪一层。 */
+declare const MENU_PRESS_MARKER = "data-astryx-menu-press";
+//#endregion
+//#region src/composables/internal/strayClick.d.ts
+/**
+ * 按压模型派发的那次行激活是不是正在进行。只在那次派发的同步过程中为真，
+ * 所以把激活转交给里面链接的行，能分清这是模型的 click 还是浏览器多出来的那个。
+ */
+declare function isMenuPressActivation(): boolean;
+/** 撤掉已经布下的口子。卸载和测试里用。 */
 declare function resetMenuPress(): void;
+//#endregion
+//#region src/composables/useMenuPress.d.ts
 interface MenuPressOptions {
-  /** The element carrying `role="menu"` for this level. */
+  /** 菜单（或列表框）的根：按压要从它的行里挑。 */
   menuRef: Ref<HTMLElement | null>;
-  /** Whether the surface carries the press model right now. */
-  isEnabled: () => boolean;
-  /** A mouse press was released outside the menu with nothing acting. */
-  onDismiss: () => void;
-  /**
-   * Selector matching the ENABLED rows. A pointer over anything else inside the
-   * menu (a divider, a heading, a disabled row) picks nothing.
-   */
-  itemSelector?: string;
-  /** The control that opens the menu, when a press may start there. */
+  /** 能开菜单的控件，按压也可以从这里开始。 */
   triggerRef?: Ref<HTMLElement | null>;
   /**
-   * A mouse pressed the trigger, or a finger rested on it for the long-press
-   * delay: open the menu under the held pointer and return whether it opened.
-   * Return false when the press closed an open menu instead.
+   * 只匹配**可用**行的选择器。指针压在分割线、标题、禁用行上时什么都不挑。
+   * @default 三种菜单项角色里没有 `aria-disabled="true"` 的
    */
-  onTriggerPress?: (pointerType: 'mouse' | 'pen' | 'touch') => boolean;
+  itemSelector?: string;
   /**
-   * Move the highlight; `null` clears it. Defaults to moving DOM focus with
-   * `preventScroll` onto the row.
+   * 鼠标按下触发器，或手指在上面按满长按时间：在按住的指针下面打开菜单，返回打开了没有。
+   * 返回 false（这一按把开着的菜单关掉了）会结束这次手势。
+   * 同一次手势里触发器收到的 click 用 `isTriggerClickFromPress()` 认出来。
    */
+  onTriggerPress?: (pointerType: MenuPressPointerType) => boolean;
+  /** 移动高亮，`null` 表示清掉。默认把 DOM 焦点（`preventScroll`）移到那一行。 */
   onHighlight?: (row: HTMLElement | null) => void;
-  /**
-   * Act on the row under the release. Defaults to dispatching a click on the
-   * row that carries the release button and modifier keys.
-   */
+  /** 执行松开位置的那一行。默认替它派发一次 click，带上松开时的按键和修饰键。 */
   onActivate?: (row: HTMLElement, release: PointerEvent) => void;
-  /** How long a finger must rest on the trigger before the menu opens under it. */
+  /** **鼠标**在菜单外松开、什么都没执行：关掉菜单。手指在外面松开不会调它。 */
+  onDismiss?: () => void;
+  /** 按住时指针停在边缘要自动滚动的元素。默认是溢出的菜单根，返回 null 表示不滚。 */
+  getScroller?: () => HTMLElement | null;
+  /** 按视口坐标找元素。默认 `document.elementFromPoint`。测试用的接缝。 */
+  hitTest?: (x: number, y: number) => Element | null;
+  /** @default 500 */
   longPressDelayMs?: number;
+  /** 这套模型当前是否生效，每次按下时读。@default true */
+  isEnabled?: MaybeRefOrGetter<boolean>;
 }
 interface MenuPress {
-  /** Attach to the menu root's `pointerdown`. */
+  /** 菜单根的 pointerdown 处理函数。不方便摊对象时单独绑：`@pointerdown="press.onPointerDown"`。 */
   onPointerDown: (event: PointerEvent) => void;
-  /** Spread onto the menu root: claims presses that begin inside it. */
+  /** 用 `v-bind` 摊到菜单根上：接管从里面开始的按压，并打上标记。 */
   menuProps: {
-    'onPointerDown': (event: PointerEvent) => void;
-    'data-astryx-menu-press': string;
+    'onPointerdown': (event: PointerEvent) => void;
+    'data-astryx-menu-press': '';
   };
-  /** Spread onto the trigger: a mouse press opens at once, a held finger opens after the delay. */
+  /** 用 `v-bind` 摊到触发器上：鼠标按下就开，手指按住才开。 */
   triggerProps: {
-    onPointerDown: (event: PointerEvent) => void;
-    onContextMenu: (event: MouseEvent) => void;
+    onPointerdown: (event: PointerEvent) => void;
+    onContextmenu: (event: MouseEvent) => void;
   };
-  /**
-   * Whether the click reaching the trigger belongs to the gesture that just
-   * pressed it. That press already opened or closed the menu, so the click must
-   * neither toggle nor reopen.
-   */
+  /** 触发器收到的这次 click 是不是刚才那次按压的。那次按压已经开或关过菜单，click 不能再切换。 */
   isTriggerClickFromPress: () => boolean;
-  /** End the gesture in flight with nothing acting, for when the menu closes under it. */
+  /** 什么都不执行，结束正在进行的手势（菜单关了）。 */
   cancel: () => void;
 }
 /**
- * The press model of a painted menu surface.
- *
- * A finger's pointer events stay with the element it landed on, so the gesture
- * is tracked at the document level by `pointerId`:
+ * 对应原版 Astryx 的 `hooks/useMenuPress`。纯状态机见 `internal/menuPressGesture.ts`。
  *
- * - The highlight follows the finger.
- * - The row under the RELEASE acts, the way its own click would, carrying the
- *   release's modifiers; the browser's own click for that gesture is swallowed
- *   so the row never acts twice.
- * - A finger released outside leaves the menu open; a mouse released outside
- *   dismisses it.
- * - `pointercancel` and a second pointer end the gesture with nothing acting.
- *
- * 传了 `triggerRef` 和 `onTriggerPress` 之后，按压也可以从触发器开始：鼠标按下就开，
- * 手指按住到 `longPressDelayMs` 才开，开着的时候手指可以滑进菜单里挑行。
+ * 菜单里的一次按压，不管从触发器还是从菜单里开始，从头管到尾：
+ * - 按 `pointerId` 在文档层跟踪。手指的事件一直发给它落下的元素，所以只有文档看得见它滑到了哪。
+ * - 高亮跟着指针走。
+ * - **松开**位置那一行执行，就像它自己被点了一样，带上松开时的修饰键；浏览器为这次手势补的 click 被吞掉。
+ * - 鼠标按下触发器就打开；手指按住满 `longPressDelayMs` 才打开，然后可以一路滑进菜单挑行。
+ * - pointercancel、第二根手指、窗口失焦都以什么都不执行结束。滚动交给浏览器（菜单根上的 `touch-action`）。
+ * - 菜单会滚动时，按住的指针停在上下边缘附近，菜单自动朝那边滚。
  */
 declare function useMenuPress(options: MenuPressOptions): MenuPress;
 //#endregion
@@ -1230,6 +1398,18 @@ interface NumberField {
   /** 处理键盘事件 */
   onKeyDown: (event: KeyboardEvent) => void;
 }
+interface SteppedValueOptions {
+  currentValue: number | null;
+  direction: NumberStepDirection;
+  min: number | null;
+  max: number | null;
+  step: number | null | undefined;
+  integerOnly: boolean;
+}
+/**
+ * 按步长网格走一格：以 min 为起点对齐，先取整再夹到范围内。
+ */
+declare function computeSteppedValue(options: SteppedValueOptions): number | null;
 /**
  * 数字输入框逻辑：步进、范围限制、整数限制、键盘增减。
  */
@@ -1339,29 +1519,47 @@ interface PendingChange<T> {
  */
 declare function usePendingChange<T>(action: () => ((value: T) => void | Promise<void>) | undefined): PendingChange<T>;
 //#endregion
-//#region src/composables/internal/pressFeedback.d.ts
+//#region src/composables/usePressFeedback.d.ts
+interface UsePressFeedbackOptions {
+  /**
+   * 要不要带上默认的按压色（`astryx-pressable` 类，在 `::after` 上画一层）。
+   * 组件自己在样式里读 `--_press-paint-image` 画按压时传 false，只拿标记。
+   * @default true
+   */
+  hasOverlay?: boolean;
+}
 interface UsePressFeedbackReturn {
   /**
-   * 铺到「背景画按压反馈」的那个元素上。
-   * 同一个元素还要配一份 `styles/pressable.css` 里的样式（引入 hook 时自动带上）。
+   * 用 `v-bind` 摊到「画按压」的那个元素上。
+   * 里面总有 `data-astryx-pressable` 标记；`hasOverlay` 为真时还有 `class: 'astryx-pressable'`。
    */
-  pressableProps: Record<string, string>;
+  pressableProps: Readonly<Record<string, string>>;
 }
 /**
  * 对应原版 Astryx 的 `hooks/usePressFeedback`。
  *
- * 手指按下去时，CSS 的 `:active` 会在手指落下的瞬间就亮，而且滚动已经开始了它可能还亮着。
- * 这里的按压模型反过来：先等 150 毫秒，确认这真是按压；手指一动超过 10 像素、
- * 或者页面滚走了，马上作废，本次按压里不再亮回来；快速点一下则在抬手时补上；
- * 松手后 200 毫秒淡出。这几个时间和系统列表的手感一致。
+ * 把一个元素标成触屏按压模型的可按表面，并确保文档级控制器已经装上。
+ *
+ * 手指下，CSS 的 `:active` 落手就亮，滚动开始了还可能亮着。按压模型反过来：
+ * 先等 150 毫秒确认是按压；手指挪动超过 10 像素或者页面滚动，立刻作废，这次手势里不再亮回来；
+ * 太快的轻点在抬手时补亮；抬手后 200 毫秒淡出。鼠标不受影响，`:active` 照旧。
+ *
+ * 一个文档只有一个控制器：第一个挂载的可按组件装上，最后一个卸载时拆掉。
+ * 调用它不会给元素加监听或状态，一次按压只改一个属性。服务端不装。
+ */
+declare function usePressFeedback(options?: UsePressFeedbackOptions): UsePressFeedbackReturn;
+//#endregion
+//#region src/composables/useResolvedLabelHidden.d.ts
+/**
+ * 隐藏标签的正名是 `isLabelHidden`，旧名 `labelHidden` 先留着。
  *
- * 一个文档级控制器给所有带标记的元素做这件事（第一个用到的组件装上，最后一个卸载时拆掉），
- * 所以调用这个组合式函数不会给你的元素加监听，也不加状态。
+ * 默认不隐藏时，两个名字任一为真就隐藏。Vue 会把没传的布尔属性当成 false，
+ * 这种默认值用「或」就够了。
  *
- * 鼠标上的表现不变：`styles/pressable.css` 里给鼠标留了 `:active`，
- * 在 `@media (pointer: coarse)` 之外才生效。
+ * 默认隐藏（PowerSearch）时必须分清「没传」和「传了 false」。
+ * 两个都传了，听正名。这个判断要在 setup 里做：渲染函数里拿不到当前实例。
  */
-declare function usePressFeedback(): UsePressFeedbackReturn;
+declare function useResolvedLabelHidden(isLabelHidden: () => boolean | undefined, labelHidden: () => boolean | undefined, fallback?: boolean): ComputedRef<boolean>;
 //#endregion
 //#region src/composables/useRestoreFocus.d.ts
 interface UseRestoreFocusOptions {
@@ -1379,38 +1577,80 @@ interface RestoreFocus {
 /**
  * 在浮层组件打开时保存当前焦点元素，关闭时恢复焦点。
  * 用于对话框、抽屉、弹出菜单等浮层组件。
+ *
+ * 恢复时焦点环跟着上一次的输入走：键盘关掉的照常画环，鼠标或手指关掉的不画。
  */
 declare function useRestoreFocus(options: UseRestoreFocusOptions): RestoreFocus;
 //#endregion
+//#region src/composables/internal/scrollGeometry.d.ts
+interface MeasuredScrollAxisState {
+  isScrollable: boolean;
+  atStart: boolean;
+  atEnd: boolean;
+}
+//#endregion
 //#region src/composables/useScrollableArea.d.ts
 type ScrollAxis = 'inline' | 'block' | 'both';
 type ScrollOverscroll = 'allow' | 'contain';
 type ScrollStickyContainment = 'whenScrollable' | 'always';
 type ScrollRole = 'group' | 'region';
-interface ScrollAxisState {
-  isScrollable: boolean;
-  atStart: boolean;
-  atEnd: boolean;
-}
+/**
+ * 能滚动时，键盘从哪里进来。
+ * - `content`：内容自己有可聚焦的东西（例如表格的单元格），视口不进 Tab 顺序，也不带名字。
+ * - `viewport`：视口在能滚动时成为一个 Tab 停靠点，带上名字和角色。
+ * - `contentOrViewport`：同上；但 Tab 进来时，如果内容里第一个就是普通按钮或链接，焦点直接交给它。
+ */
+type ScrollKeyboardAccess = {
+  owner: 'content';
+} | {
+  owner: 'viewport';
+  label: string;
+  role?: ScrollRole;
+} | {
+  owner: 'contentOrViewport';
+  label: string;
+  role?: ScrollRole;
+};
+type ScrollAxisState = MeasuredScrollAxisState;
 interface ScrollableAreaState {
   inline: ScrollAxisState;
   block: ScrollAxisState;
 }
 interface UseScrollableAreaOptions {
+  /** @default 'block' */
   axis?: ScrollAxis;
-  label: string;
+  /** 键盘归属。不传时按 `{ owner: 'viewport', label, role }`。 */
+  keyboardAccess?: ScrollKeyboardAccess;
+  /** 视口的无障碍名称。只在没传 `keyboardAccess` 时用。 */
+  label?: string;
+  /** @default 'group' */
   role?: ScrollRole;
+  /** @default 'allow' */
   overscroll?: ScrollOverscroll;
+  /** @default 'whenScrollable' */
   stickyContainment?: ScrollStickyContainment;
 }
-declare function useScrollableArea(options: UseScrollableAreaOptions): UseScrollableAreaResult;
 interface UseScrollableAreaResult {
+  /** 绑到视口的 `:ref` 上。 */
   viewport: (element: unknown) => void;
+  /** 绑到内容的 `ref` 上。 */
   content: Ref<HTMLElement | null>;
+  /** 用 `v-bind` 摊到视口上：角色、名字、tabindex 和 `data-scroll-*` 状态。 */
   viewportAttrs: ComputedRef<Record<string, string | number | undefined>>;
+  /** 视口的 overflow 和 overscroll。这几项归这个 composable 管，调用方不要再写。 */
   viewportStyle: ComputedRef<CSSProperties>;
   state: ComputedRef<ScrollableAreaState>;
 }
+/**
+ * 对应原版 Astryx 的 `hooks/useScrollableArea`：可滚动容器系统的核心。
+ *
+ * 按逻辑轴（行内 / 块方向）给调用方的视口和内容加上滚动行为：
+ * 只有内容真的溢出时视口才变成滚动容器；量出每条轴能不能滚、到没到两头；
+ * 能滚时视口进入 Tab 顺序，让键盘也能滚；`overscroll: 'contain'` 只在真能滚的轴上生效。
+ * 量出的状态登记到滚动归属表里，嵌套的滚动区域和键盘委托都靠它分清谁是哪一层。
+ * 藏起来、没挂上或者尺寸为 0 的视口量不出来，保留上一次的结果，等下一次有效的信号。
+ */
+declare function useScrollableArea(options: UseScrollableAreaOptions): UseScrollableAreaResult;
 //#endregion
 //#region src/composables/internal/scrollLock.d.ts
 declare function useScrollLock(isLocked: Ref<boolean>): void;
@@ -1422,8 +1662,11 @@ interface ScrollOverflowState {
   hasOverflow: boolean;
 }
 /**
- * 观察一个横向滚动容器，报告起始边和结束边有没有被挡住。
- * 容差 1px，滚动和尺寸变化都会重新量。
+ * 观察一个横向滚动容器，报告起始边和结束边有没有被挡住。容差 1px。
+ *
+ * 每次滚动都量。尺寸变化和刚绑上时，只在容器真的被渲染时才量：藏起来的容器没有边可报，
+ * 保留上一次的结果，等它露出来之后的那次尺寸变化再量。藏着的容器被脚本滚动时照样量，
+ * 因为同样大小地露出来不会再有尺寸变化。
  */
 declare function useScrollOverflow(): UseScrollOverflowResult;
 interface UseScrollOverflowResult {
@@ -1457,6 +1700,72 @@ declare function snapToGraphemeBoundary(text: string, offset: number): number;
  */
 declare function useStreamingText(targetText: MaybeRefOrGetter<string>, isStreaming?: MaybeRefOrGetter<boolean>, options?: MaybeRefOrGetter<UseStreamingTextOptions>): ComputedRef<string>;
 //#endregion
+//#region src/composables/useTouchTrigger.d.ts
+/**
+ * 悬停类浮层在触屏上怎么响应。
+ *
+ * - `auto`：点一下打开，除非触发器本身是个会做事的东西（按钮、链接、表单控件）。
+ * - `tap`：总是点一下打开，哪怕触发器自己也有动作。
+ * - `none`：触屏上从不打开。
+ */
+type LayerTouchTrigger = 'auto' | 'tap' | 'none';
+/**
+ * 激活这个元素是不是「做了别的事」，而不是「显示浮层」。
+ *
+ * 比「可聚焦」窄是有意的：纯文字 Tooltip 的触发器带 `tabindex=0`，
+ * 键盘用户要能聚焦它读提示，但它本身没有动作。
+ *
+ * 返回 true 只决定「浮层不开」，那一下点击本身不会被吞掉：这里不调
+ * `preventDefault`，也不调 `stopPropagation`。
+ */
+declare function isActionTrigger(element: HTMLElement): boolean;
+interface UseTouchTriggerOptions {
+  /** 触屏上的触发方式。 */
+  touchTrigger: MaybeRefOrGetter<LayerTouchTrigger>;
+  /** 触发器是不是还能用。 @default true */
+  isEnabled?: MaybeRefOrGetter<boolean>;
+  /** 打开状态是不是由外面控制。受控的浮层不会被点击开关。 @default false */
+  isControlled?: MaybeRefOrGetter<boolean>;
+  /** 浮层现在是否打开。 */
+  isOpen: MaybeRefOrGetter<boolean>;
+  /** 浮层元素的 id，用来判断「点在浮层里面」。 */
+  layerId: MaybeRefOrGetter<string>;
+  /** 触发器元素。 */
+  triggerRef: Ref<HTMLElement | null>;
+  /** 立刻打开，不等悬停延时。 */
+  show: () => void;
+  /** 立刻关闭。 */
+  hide: () => void;
+}
+interface UseTouchTriggerReturn {
+  /**
+   * 当前这次交互是不是没有悬停能力的指针（手指，或者已经落下的笔）。
+   * 悬停在屏幕上的笔是 false，因为它确实在悬停。
+   */
+  isTouchPointer: Ref<boolean>;
+  /**
+   * 这一次交互是不是触屏。和上一条不同的是，用户一碰键盘它就变回 false，
+   * 这样点过一次之后焦点驱动的浮层还能用。
+   */
+  isTouchInteraction: () => boolean;
+  /** 绑到触发器的 pointerenter 上：在合成的悬停事件之前记下指针类型。 */
+  handlePointerEnter: (event: PointerEvent) => void;
+  /**
+   * 绑到触发器的 pointerdown 上。返回 true 表示这次按压是触屏、
+   * 并且已经由这里处理掉了，调用方自己的按下逻辑不要重复执行。
+   */
+  handlePointerDown: (event: PointerEvent) => boolean;
+  /** 忘掉「是点开的」这件事。其它关闭路径（Escape、受控关闭）都要调。 */
+  clearTapOpen: () => void;
+}
+/**
+ * 悬停类浮层（Tooltip、HoverCard）共用的触屏行为。
+ *
+ * 触屏上表达不了「悬停」：点一下会合成 `mouseenter`，不处理的悬停浮层要么
+ * 每次点都弹出来、又没有东西能关掉它，要么把用户点控件的这一下吃掉。
+ */
+declare function useTouchTrigger(options: UseTouchTriggerOptions): UseTouchTriggerReturn;
+//#endregion
 //#region src/composables/useTypeahead.d.ts
 interface UseTypeaheadOptions {
   /** 当前 DOM 顺序上的标签。某一项可以是 null，表示这个下标不能匹配。 */
@@ -1485,8 +1794,9 @@ interface UseTypeaheadReturn {
  *
  * 反复按同一个字母会在匹配项之间循环，而不是把查询收得更窄。
  * 空格留给激活；只有缓冲里已经有字时，空格才算查询的一部分。
+ * 输入法拼字时的按键属于输入法，不算跳转。
  * 这个函数自己不移动焦点，调用方在 `onMatch` 里接 `useListFocus` 或其他集合。
  */
 declare function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn;
 //#endregion
-export { useLongPress as $, useAppShellMobile as $n, EntryAnimationPreset as $t, UseOverflowOptions as A, ContentRevealOptions as An, perceptualLightness as At, parseISODate as B, INTERACTIVE_SELECTORS as Bn, UseGridFocusReturn as Bt, useRestoreFocus as C, parseISOTime as Cn, IndicatorFocusRingHandlers as Ct, usePendingChange as D, UseControllableStateOptions as Dn, ImageSampleRegion as Dt, PendingChange as E, ControllableState as En, useIndicatorFocusRing as Et, NumberStepDirection as F, ComboboxOption as Fn, useHandleRef as Ft, useMergedRefs as G, UseChatStreamScrollReturn as Gn, FileRejection as Gt, todayISODate as H, useClickableContainer as Hn, FocusTrap as Ht, UseNumberFieldOptions as I, UseComboboxOptions as In, GridRovingFocus as It, resetMenuPress as J, UseChatNewMessagesOptions as Jn, formatFileSize as Jt, MenuPress as K, useChatStreamScroll as Kn, FileSelectionOptions as Kt, useNumberField as L, useCombobox as Ln, UseGridRovingFocusOptions as Lt, computeOverflow as M, UseContainerRevealOptions as Mn, Hotkey as Mt, useOverflow as N, useContainerReveal as Nn, useHotkeys as Nt, ComputeOverflowInput as O, useControllableState as On, UseImageModeOptions as Ot, NumberField as P, Combobox as Pn, HandleRef as Pt, LongPressOptions as Q, appShellMobileKey as Qn, useFieldControlState as Qt, addMonths as R, useCoarsePointer as Rn, useGridRovingFocus as Rt, UseRestoreFocusOptions as S, parseDisplayTime as Sn, useInputContainer as St, usePressFeedback as T, shiftTime as Tn, UseIndicatorFocusRingReturn as Tt, MergedRef as U, ChatScrollToBottomOptions as Un, UseFocusTrapOptions as Ut, toISODate as V, UseClickableContainerOptions as Vn, useGridFocus as Vt, MergedRefHandle as W, UseChatStreamScrollOptions as Wn, useFocusTrap as Wt, useMediaQuery as X, useChatNewMessages as Xn, FieldControlState as Xt, useMenuPress as Y, UseChatNewMessagesReturn as Yn, selectFiles as Yt, LongPressHandlers as Z, AppShellMobile as Zn, FieldControlStateInput as Zt, ScrollableAreaState as _, ParsedTime as _n, UseInputStatusIconOptions as _t, UseStreamingTextOptions as a, DisclosureHandle as an, WeekStartsOn as ar, UseLayerOptions as at, useScrollableArea as b, formatISOTime as bn, InputContainerHandlers as bt, ScrollOverflowState as c, devWarn as cn, formatDateRange as cr, KeyboardHintOrientation as ct, useScrollLock as d, DateSurface as dn, isSameRange as dr, useKeyboardHint as dt, UseEntryAnimationOptions as en, AnnounceFn as er, ListFocus as et, ScrollAxis as f, resolveDatePresentation as fn, orderRange as fr, InteractiveRole as ft, ScrollStickyContainment as g, NativePicker as gn, InputStatusVariant as gt, ScrollRole as h, ISOTimeString as hn, useInteractiveRole as ht, StreamingTextSpeed as i, useDismiss as in, RangeClickResult as ir, LayerMode as it, UseOverflowReturn as j, UseContainerReveal as jn, useImageMode as jt, ComputeOverflowResult as k, ContainerRevealOptions as kn, imageModeFromPixels as kt, UseScrollOverflowResult as l, useDevWarning as ln, isDayOutsideSpan as lr, UseKeyboardHint as lt, ScrollOverscroll as m, HourFormat as mn, spanDays as mr, UseInteractiveRoleReturn as mt, UseTypeaheadReturn as n, useEntryAnimation as nn, useAnnounce as nr, UseListFocusOptions as nt, snapToGraphemeBoundary as o, DisclosureHandleRef as on, applyRangeClick as or, UseLayerReturn as ot, ScrollAxisState as p, resolveDateSurface as pn, resolveWeekStart as pr, UseInteractiveRoleOptions as pt, MenuPressOptions as q, CHAT_MESSAGE_CLASS as qn, FileSelectionResult as qt, useTypeahead as r, UseDismissOptions as rn, ISODateRange as rr, useListFocus as rt, useStreamingText as s, useDisclosureHandle as sn, compareISODate as sr, useLayer as st, UseTypeaheadOptions as t, UseEntryAnimationReturn as tn, AnnouncePoliteness as tr, ListFocusOrientation as tt, useScrollOverflow as u, DatePresentation as un, isRangeWithinSpan as ur, UseKeyboardHintOptions as ut, UseScrollableAreaOptions as v, TimePresentation as vn, UseInputStatusIconReturn as vt, UsePressFeedbackReturn as w, resolveTimeSurface as wn, UseIndicatorFocusRingOptions as wt, RestoreFocus as x, isTimeInRange as xn, UseInputContainerOptions as xt, UseScrollableAreaResult as y, formatDisplayTime as yn, useInputStatusIcon as yt, buildMonthGrid as z, ClickableContainerHandlers as zn, UseGridFocusOptions as zt };
+export { MergedRefHandle as $, UseContainerReveal as $n, Hotkey as $t, useResolvedLabelHidden as A, useDevWarning as An, applyRangeClick as Ar, UseKeyboardHint as At, computeOverflow as B, TimeSurface as Bn, useInputStatusIcon as Bt, ScrollableAreaState as C, useEntryAnimation as Cn, useAppShellMobile as Cr, useLayerTeleportTarget as Ct, RestoreFocus as D, DisclosureHandleRef as Dn, ISODateRange as Dr, UseLayerReturn as Dt, useScrollableArea as E, DisclosureHandle as En, useAnnounce as Er, UseLayerOptions as Et, usePendingChange as F, HourFormat as Fn, isSameRange as Fr, UseInteractiveRoleReturn as Ft, computeSteppedValue as G, parseISOTime as Gn, UseIndicatorFocusRingOptions as Gt, NumberField as H, formatISOTime as Hn, UseInputContainerOptions as Ht, ComputeOverflowInput as I, ISOTimeString as In, orderRange as Ir, useInteractiveRole as It, buildMonthGrid as J, ControllableState as Jn, ImageSampleRegion as Jt, useNumberField as K, resolveTimeSurface as Kn, UseIndicatorFocusRingReturn as Kt, ComputeOverflowResult as L, NativePicker as Ln, resolveWeekStart as Lr, InputStatusVariant as Lt, UsePressFeedbackReturn as M, DateSurface as Mn, formatDateRange as Mr, useKeyboardHint as Mt, usePressFeedback as N, resolveDatePresentation as Nn, isDayOutsideSpan as Nr, InteractiveRole as Nt, UseRestoreFocusOptions as O, useDisclosureHandle as On, RangeClickResult as Or, useLayer as Ot, PendingChange as P, resolveDateSurface as Pn, isRangeWithinSpan as Pr, UseInteractiveRoleOptions as Pt, MergedRef as Q, ContentRevealOptions as Qn, useImageMode as Qt, UseOverflowOptions as R, ParsedTime as Rn, spanDays as Rr, UseInputStatusIconOptions as Rt, ScrollStickyContainment as S, UseEntryAnimationReturn as Sn, appShellMobileKey as Sr, useLayerMountTarget as St, UseScrollableAreaResult as T, useDismiss as Tn, AnnouncePoliteness as Tr, LayerMode as Tt, NumberStepDirection as U, isTimeInRange as Un, useInputContainer as Ut, useOverflow as V, formatDisplayTime as Vn, InputContainerHandlers as Vt, UseNumberFieldOptions as W, parseDisplayTime as Wn, IndicatorFocusRingHandlers as Wt, toISODate as X, useControllableState as Xn, imageModeFromPixels as Xt, parseISODate as Y, UseControllableStateOptions as Yn, UseImageModeOptions as Yt, todayISODate as Z, ContainerRevealOptions as Zn, perceptualLightness as Zt, ScrollAxis as _, FieldControlState as _n, CHAT_MESSAGE_CLASS as _r, useLongPress as _t, UseTouchTriggerOptions as a, useGridRovingFocus as an, useCombobox as ar, resetMenuPress as at, ScrollOverscroll as b, EntryAnimationPreset as bn, useChatNewMessages as br, UseListFocusOptions as bt, useTouchTrigger as c, useGridFocus as cn, INTERACTIVE_SELECTORS as cr, MenuPressEffect as ct, snapToGraphemeBoundary as d, useFocusTrap as dn, hasTextSelection as dr, MenuPressPointerType as dt, useHotkeys as en, UseContainerRevealOptions as er, useMergedRefs as et, useStreamingText as f, FileRejection as fn, useClickableContainer as fr, MenuPressStep as ft, useScrollLock as g, selectFiles as gn, useChatStreamScroll as gr, LongPressOptions as gt, useScrollOverflow as h, formatFileSize as hn, UseChatStreamScrollReturn as hr, LongPressHandlers as ht, LayerTouchTrigger as i, UseGridRovingFocusOptions as in, UseComboboxOptions as ir, isMenuPressActivation as it, UsePressFeedbackOptions as j, DatePresentation as jn, compareISODate as jr, UseKeyboardHintOptions as jt, useRestoreFocus as k, devWarn as kn, WeekStartsOn as kr, KeyboardHintOrientation as kt, StreamingTextSpeed as l, FocusTrap as ln, UseClickableContainerOptions as lr, MenuPressEvent as lt, UseScrollOverflowResult as m, FileSelectionResult as mn, UseChatStreamScrollOptions as mr, useMediaQuery as mt, UseTypeaheadReturn as n, useHandleRef as nn, Combobox as nr, MenuPressOptions as nt, UseTouchTriggerReturn as o, UseGridFocusOptions as on, useCoarsePointer as or, MENU_PRESS_MARKER as ot, ScrollOverflowState as p, FileSelectionOptions as pn, ChatScrollToBottomOptions as pr, menuPressStep as pt, addMonths as q, shiftTime as qn, useIndicatorFocusRing as qt, useTypeahead as r, GridRovingFocus as rn, ComboboxOption as rr, useMenuPress as rt, isActionTrigger as s, UseGridFocusReturn as sn, ClickableContainerHandlers as sr, MENU_PRESS_SETTLE_MS as st, UseTypeaheadOptions as t, HandleRef as tn, useContainerReveal as tr, MenuPress as tt, UseStreamingTextOptions as u, UseFocusTrapOptions as un, hasInteractiveAncestor as ur, MenuPressGesture as ut, ScrollAxisState as v, FieldControlStateInput as vn, UseChatNewMessagesOptions as vr, ListFocus as vt, UseScrollableAreaOptions as w, UseDismissOptions as wn, AnnounceFn as wr, useResolvedLayerTeleport as wt, ScrollRole as x, UseEntryAnimationOptions as xn, AppShellMobile as xr, useListFocus as xt, ScrollKeyboardAccess as y, useFieldControlState as yn, UseChatNewMessagesReturn as yr, ListFocusOrientation as yt, UseOverflowReturn as z, TimePresentation as zn, UseInputStatusIconReturn as zt };