@astryx-vue/core 0.2.5 → 0.3.0

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

@@ -1,7 +1,9 @@
+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 "./useClipboard-CU-kfqeJ.js";
-import "./useResizable-CUoNPmUw.js";
-import { CSSProperties, Component, ComputedRef, InjectionKey, MaybeRefOrGetter, Ref } from "vue";
+import "./useResizable-DDwPpPe6.js";
+import { CSSProperties, Component, ComponentPublicInstance, ComputedRef, InjectionKey, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
 import { CalendarDate } from "@internationalized/date";
 //#region src/composables/useDateRange.d.ts
 interface ISODateRange {
@@ -339,6 +341,8 @@ declare function resolveTimeSurface(options: {
   coarse: boolean;
   hasSeconds: boolean;
   increment: number;
+  /** 额外的“系统控件表达不了”的信号，例如预设时间列表。 */
+  needsTypedField?: boolean;
 }): 'text' | 'native';
 //#endregion
 //#region src/composables/useDatePresentation.d.ts
@@ -352,6 +356,25 @@ type DateSurface = 'popover' | 'sheet' | 'native';
 declare function resolveDatePresentation(presentation: DatePresentation | undefined, nativePicker: NativePicker | undefined): DatePresentation;
 declare function resolveDateSurface(presentation: DatePresentation, coarse: boolean): DateSurface;
 //#endregion
+//#region src/composables/useDevWarning.d.ts
+/**
+ * 对应原版 Astryx 的 `devWarn`。
+ *
+ * 没有组件实例时用的开发期警告，只在开发构建里输出。
+ * 输出形如 `Component: message`，前缀写组件或组合式函数的名字。
+ */
+declare function devWarn(component: string, message: string): void;
+/**
+ * 对应原版 Astryx 的 `hooks/useDevWarning`。
+ *
+ * 条件成立时打一条开发期警告，同一次挂载只打一次。
+ * 直接写在渲染体里的警告每次渲染都会重来，用状态挡又白白多一次渲染，
+ * 所以这里靠 watch 在条件第一次成立时打一次。
+ *
+ * 生产构建里什么也不做，不会输出，也不留 watcher。
+ */
+declare function useDevWarning(component: string, message: string, condition?: MaybeRefOrGetter<boolean>): void;
+//#endregion
 //#region src/composables/useDisclosureHandle.d.ts
 interface DisclosureHandle {
   open: () => void;
@@ -400,6 +423,34 @@ interface UseDismissOptions {
  */
 declare function useDismiss(options: UseDismissOptions): void;
 //#endregion
+//#region src/composables/internal/entryAnimation.d.ts
+/** 入场动画的预设。名字说的是元素往哪个方向动。 */
+type EntryAnimationPreset = 'slideDown' | 'slideUp' | 'fadeIn' | 'scaleIn';
+interface UseEntryAnimationOptions {
+  /**
+   * 挂载时播放的动画。
+   * @default 'slideDown'
+   */
+  preset?: EntryAnimationPreset;
+}
+interface UseEntryAnimationReturn {
+  /**
+   * 绑到元素的 `class` 上。首屏渲染出来的元素、以及服务端渲染时都是 `null`，
+   * 也就是说这些元素不播放动画。
+   */
+  entryClass: string | null;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useEntryAnimation`。
+ *
+ * 元素挂载时播一次入场动画，但只对首屏画完之后才插进来的元素生效：
+ * 首屏就渲染出来的元素不播放，免得整页一起动。
+ *
+ * 用法是把返回的 `entryClass` 绑到 `class` 上。动画时长和缓动取自主题的
+ * motion token，「减少动态效果」打开时动画会直接落到结束状态。
+ */
+declare function useEntryAnimation(options?: UseEntryAnimationOptions): UseEntryAnimationReturn;
+//#endregion
 //#region src/composables/useFieldControlState.d.ts
 interface FieldControlStateInput {
   disabled?: MaybeRefOrGetter<boolean | undefined>;
@@ -443,14 +494,20 @@ declare function selectFiles(list: FileList | File[] | null | undefined, options
 //#endregion
 //#region src/composables/useFocusTrap.d.ts
 interface UseFocusTrapOptions {
-  /** 要陷阱焦点的容器元素 */
-  container: Ref<HTMLElement | null>;
+  /** 要陷阱焦点的容器元素。不传时由 hook 自己建一个，从返回值的 `containerRef` 取。 */
+  container?: Ref<HTMLElement | null>;
   /** 是否启用焦点陷阱 */
-  isEnabled: Ref<boolean>;
+  isEnabled?: MaybeRefOrGetter<boolean>;
+  /** 同一个开关，原版的名字。两者任一为真即启用。 */
+  isActive?: MaybeRefOrGetter<boolean>;
+  /** 容器里按下 Escape 时调用。不传就不管这个键。 */
+  onEscape?: () => void;
   /** 初始焦点目标（可选） */
   initialFocus?: () => HTMLElement | null;
 }
 interface FocusTrap {
+  /** 陷阱容器。传了 `container` 时就是它，没传时是这里新建的。 */
+  containerRef: Ref<HTMLElement | null>;
   /** 手动更新可聚焦元素列表 */
   update: () => void;
   /** 聚焦到陷阱内的第一个元素 */
@@ -461,8 +518,78 @@ interface FocusTrap {
 /**
  * 在容器内陷阱键盘焦点，按 Tab 时循环聚焦容器内的可聚焦元素。
  * 用于模态对话框、抽屉等需要限制焦点范围的浮层组件。
+ *
+ * 打开时把焦点送进容器，关闭或卸载时把焦点还给打开前聚焦的元素；
+ * 焦点从没进过容器、或者已经被别处拿走时不还。
  */
-declare function useFocusTrap(options: UseFocusTrapOptions): FocusTrap;
+declare function useFocusTrap(options?: UseFocusTrapOptions): FocusTrap;
+//#endregion
+//#region src/composables/useGridFocus.d.ts
+interface UseGridFocusOptions {
+  /**
+   * 网格的列数。上下方向键按这个数跨格。
+   */
+  columns: MaybeRefOrGetter<number>;
+  /**
+   * 选格子的选择器。要按 DOM 顺序选中**所有**位置，包括禁用和空的格子，
+   * 这样行列几何才对得上。
+   * @default 'button:not([disabled]), [tabindex]:not([tabindex="-1"])'
+   */
+  cellSelector?: string;
+  /**
+   * 判断某个格子能不能接焦点。不传就当每个格子都能接。
+   */
+  isCellFocusable?: (cell: HTMLElement) => boolean;
+  /**
+   * 从一个格子算出真正要聚焦的元素，例如 `role="gridcell"` 里包着的按钮。
+   * 不传就聚焦格子本身。
+   */
+  getFocusTarget?: (cell: HTMLElement) => HTMLElement | null;
+  /**
+   * 焦点已经走到第一个格子之前时调用。拿到列序号和步长（横向是 1，纵向是列数）。
+   */
+  onNavigateBefore?: (column: number, offset: number) => void;
+  /**
+   * 焦点已经走到最后一个格子之后时调用。参数同 `onNavigateBefore`。
+   */
+  onNavigateAfter?: (column: number, offset: number) => void;
+  /** 按 Page Up 时调用，例如日历翻到上个月。 */
+  onPageUp?: () => void;
+  /** 按 Page Down 时调用，例如日历翻到下个月。 */
+  onPageDown?: () => void;
+  /**
+   * 让整张网格只保留一个 Tab 落脚点：当前格子的目标元素 `tabindex="0"`，
+   * 其余都是 `-1`。打开后要把返回的 `handleFocus` 挂到容器的 `focus` 事件上。
+   * @default false
+   */
+  hasRovingTabIndex?: MaybeRefOrGetter<boolean>;
+}
+interface UseGridFocusReturn {
+  /** 挂到网格容器上。 */
+  gridRef: Ref<HTMLElement | null>;
+  /** 挂到网格容器的 `keydown` 上。 */
+  handleKeyDown: (event: KeyboardEvent) => void;
+  /** 挂到网格容器的 `focus` 上。没开 `hasRovingTabIndex` 时什么都不做，挂上也无害。 */
+  handleFocus: (event: FocusEvent) => void;
+  /** 按序号聚焦某个格子，序号会被夹到合法范围里。 */
+  focusCell: (index: number) => void;
+  /** 聚焦第一个能接焦点的格子。 */
+  focusFirst: () => void;
+  /** 聚焦最后一个能接焦点的格子。 */
+  focusLast: () => void;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useGridFocus`。
+ *
+ * 按 WAI-ARIA 的 grid 模式管二维网格的键盘导航：方向键一格一格走，
+ * Home/End 走到行首行尾，Ctrl+Home/Ctrl+End 走到整张网格的开头和结尾，
+ * Page Up/Down 交给调用方（日历里就是翻月）。走到边界时可以把事件交出去，
+ * 让别的网格接住焦点，例如翻到上个月继续用方向键。
+ *
+ * 它靠读 DOM 里格子的顺序算行列，所以格子要不要能聚焦、要不要聚焦格子里的某个按钮，
+ * 都是通过 `isCellFocusable` 和 `getFocusTarget` 两个回调交给调用方决定。
+ */
+declare function useGridFocus(options: UseGridFocusOptions): UseGridFocusReturn;
 //#endregion
 //#region src/composables/useGridRovingFocus.d.ts
 interface UseGridRovingFocusOptions {
@@ -565,6 +692,143 @@ declare function imageModeFromPixels(pixels: Uint8ClampedArray, threshold?: numb
  */
 declare function useImageMode(src: MaybeRefOrGetter<string | null | undefined>, options?: MaybeRefOrGetter<UseImageModeOptions>): Ref<'dark' | 'light' | null>;
 //#endregion
+//#region src/composables/useIndicatorFocusRing.d.ts
+interface UseIndicatorFocusRingOptions {
+  /** 只包住指示器的那个元素。它的第一个子元素就是要画环的东西。 */
+  containerRef: Ref<HTMLElement | null>;
+  /**
+   * 控件被停用时跳过焦点环，因为停用的控件本来就接不到焦点。
+   * @default false
+   */
+  isDisabled?: MaybeRefOrGetter<boolean>;
+}
+interface IndicatorFocusRingHandlers {
+  onFocus: (event: FocusEvent) => void;
+  onBlur: () => void;
+}
+interface UseIndicatorFocusRingReturn {
+  /** 铺到拿着真正输入框的那个元素上，不要铺在输入框本身。 */
+  focusProps: IndicatorFocusRingHandlers;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useIndicatorFocusRing`。
+ *
+ * 给「真输入框藏起来、画面上的图形代替它」的控件画标准焦点环：复选框、
+ * 单选框都把真正的 input 设成透明，焦点环只能画在旁边那个图形上。
+ *
+ * 环画在指示器自己的元素上，只有这个元素自己的圆角能决定环的形状；
+ * 而且只在 `:focus-visible` 时画，鼠标点一下不会亮。统一放在这里管，
+ * 主题换掉指示器也照样有可见焦点，不会因为漏了一个属性就整块没法用键盘。
+ */
+declare function useIndicatorFocusRing(options: UseIndicatorFocusRingOptions): UseIndicatorFocusRingReturn;
+//#endregion
+//#region src/composables/useInputContainer.d.ts
+interface UseInputContainerOptions {
+  /** 外层容器，也就是要变成可点的那一圈。 */
+  containerRef: Ref<HTMLElement | null>;
+  /** 容器里真正的输入框或文本域。 */
+  inputRef: Ref<HTMLElement | null>;
+  /**
+   * 输入框停用时不接管点击。
+   * @default false
+   */
+  disabled?: MaybeRefOrGetter<boolean>;
+}
+type InputContainerHandlers = ClickableContainerHandlers;
+/**
+ * 对应原版 Astryx 的 `hooks/useInputContainer`。
+ *
+ * 让输入框外面那一圈也能点：点在图标、内边距、状态图标这些没交互的地方时，
+ * 交给里面的输入框接焦点。底座是 `useClickableContainer`，所以清空按钮、
+ * 日历开关、链接这些嵌套的控件点上去还是它们自己的事，不会把焦点抢走。
+ *
+ * 文本类的输入框收 `.focus()`，复选框、单选框、文件这种收 `.click()`。
+ * TextInput、TextArea 这类把输入框包起来、外面还有一圈装饰的组件用它。
+ */
+declare function useInputContainer(options: UseInputContainerOptions): InputContainerHandlers;
+//#endregion
+//#region src/composables/useInputStatusIcon.d.ts
+/** 状态图标相对输入框的位置。 */
+type InputStatusVariant = 'attached' | 'detached' | 'tooltip';
+interface UseInputStatusIconOptions {
+  /** 输入框的状态（类型加文案），没有状态就不传。 */
+  status?: MaybeRefOrGetter<FieldStatusInput | undefined>;
+  /**
+   * 状态相对输入框怎么摆。`attached` 在框里画一个图标，`detached` 交给下面的
+   * 状态文案自己带图标，`tooltip` 画一个能用键盘够到的信息按钮。
+   * @default 'attached'
+   */
+  statusVariant?: MaybeRefOrGetter<InputStatusVariant>;
+  /**
+   * 输入框是否在 `InputGroup` 里，组自己会画状态。
+   * @default false
+   */
+  isInGroup?: MaybeRefOrGetter<boolean>;
+}
+interface UseInputStatusIconReturn {
+  /**
+   * 要渲染在输入框容器里的东西：`FieldIcon`（普通图标），或者 `FieldInfoTip`
+   * （带 tooltip 的信息按钮）。没有该画的东西时是 `null`。
+   * 和 `statusIconProps` 一起用：`<component :is="statusIcon" v-bind="statusIconProps" />`。
+   */
+  statusIcon: ComputedRef<Component | null>;
+  /** 上面那个组件要的属性。 */
+  statusIconProps: ComputedRef<Record<string, unknown>>;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useInputStatusIcon`。
+ *
+ * 决定输入框上那颗状态图标画什么，让同一状态下所有输入框长得一样：
+ * `attached` 画一个不说话的图标，文案留给下面的状态栏；`detached` 什么都不画，
+ * 因为状态栏自己带了图标；`tooltip` 画一个真按钮，键盘、鼠标、触摸、读屏都能
+ * 摸到它的说明。在 `InputGroup` 里也不画，组自己会画。
+ *
+ * 上游还会返回一个 `describedBy`，用来接进输入框的 `aria-describedby`。
+ * 我们这边 `Field` 已经把状态文案渲染成视觉隐藏文本并接进 `aria-describedby` 了，
+ * tooltip 按钮自己也带着 `aria-describedby`，所以不需要再返回一个 id。
+ */
+declare function useInputStatusIcon(options?: UseInputStatusIconOptions): UseInputStatusIconReturn;
+//#endregion
+//#region src/composables/useInteractiveRole.d.ts
+/** 多态组件最后该渲染成什么。 */
+type InteractiveRole = 'link' | 'button' | 'inert';
+interface UseInteractiveRoleOptions {
+  /** 地址。优先级最高：有它就渲染成链接。 */
+  href?: MaybeRefOrGetter<string | undefined>;
+  /**
+   * 有没有点击处理函数。没有地址时，有它就渲染成按钮。
+   *
+   * 上游直接看 `onClick` 有没有值。Vue 里「函数」和「取值函数」分不开，
+   * 传一个 `() => props.onClick` 会被当场调用掉，所以这里改收一个布尔，
+   * 由调用方写清楚自己有没有监听点击。
+   */
+  hasOnClick?: MaybeRefOrGetter<boolean>;
+  /**
+   * 停用时不看 `href`，因为停用的链接本身就不该是链接。
+   * 这时角色从 `onClick` 往下找，都没有就是 `inert`。
+   * @default false
+   */
+  isDisabled?: MaybeRefOrGetter<boolean>;
+}
+interface UseInteractiveRoleReturn {
+  /** 组件该渲染的元素：`a`、`button`，还是不带交互的 `span` / `div`。 */
+  role: ComputedRef<InteractiveRole>;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useInteractiveRole`。
+ *
+ * 把「这个多态组件到底渲染成什么」收在一处决定：有 `href` 就是链接，
+ * 没 `href` 但有 `onClick` 就是按钮，都没有就是一段普通内容。
+ * 时而是链接、时而按钮、时而是纯内容的组件都该走这里，判断先后顺序才不会各写一套。
+ *
+ * 只有 `link` 才真的渲染 `a`，这样键盘、中键新开标签这些行为都是浏览器给的。
+ *
+ * 上游还会读父级给的「触发上下文」（Popover、DropdownMenu 之类），
+ * 让组件自动成为新浮层的合法触发器。我们的浮层不支持子元素当触发器，
+ * 没有这份上下文可读，所以这里停在 `onClick` 这一层。
+ */
+declare function useInteractiveRole(options: UseInteractiveRoleOptions): UseInteractiveRoleReturn;
+//#endregion
 //#region src/composables/useKeyboardHint.d.ts
 type KeyboardHintOrientation = 'horizontal' | 'vertical' | 'both';
 interface UseKeyboardHintOptions {
@@ -590,6 +854,108 @@ interface UseKeyboardHint {
  */
 declare function useKeyboardHint(options?: UseKeyboardHintOptions): UseKeyboardHint;
 //#endregion
+//#region src/composables/useLayer.d.ts
+type LayerMode = 'context' | 'fixed';
+interface UseLayerOptions {
+  /**
+   * 定位方式。
+   * - `context`：跟着触发器元素定位（锚点定位）。
+   * - `fixed`：用 `x` / `y` 给出的视口坐标定位。
+   */
+  mode: LayerMode;
+  /**
+   * 外部锚点元素（context 模式）。不传就用返回的 `anchorRef` 绑定触发器。
+   */
+  anchor?: Ref<HTMLElement | null>;
+  /**
+   * 相对触发器的方位，context 模式有效。
+   * `start` / `end` 是逻辑方位，RTL 下自动镜像。
+   * @default 'below'
+   */
+  placement?: MaybeRefOrGetter<LayerPlacement>;
+  /**
+   * 沿方位轴的对齐方式，context 模式有效。
+   * @default 'center'
+   */
+  alignment?: MaybeRefOrGetter<LayerAlignment>;
+  /**
+   * 浮层与锚点之间的空隙，单位 px。
+   * @default 4
+   */
+  gap?: number;
+  /**
+   * fixed 模式的横向视口坐标，单位 px。
+   * @default 0
+   */
+  x?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * fixed 模式的纵向视口坐标，单位 px。
+   * @default 0
+   */
+  y?: MaybeRefOrGetter<number | undefined>;
+  /**
+   * 首次渲染就打开。
+   * @default false
+   */
+  isDefaultOpen?: boolean;
+  /**
+   * 点击浮层外部是否关闭。
+   * @default false
+   */
+  lightDismiss?: MaybeRefOrGetter<boolean>;
+  /**
+   * 是否等到第一次 `show()` 才渲染内容。关闭后内容卸载，只留下占位。
+   * @default false
+   */
+  lazyMount?: MaybeRefOrGetter<boolean>;
+  /**
+   * 浮层由 `show()` 打开后调用。
+   * 首次渲染就打开（`isDefaultOpen`）不算一次打开动作，不会调用它。
+   */
+  onShow?: () => void;
+  /** 浮层由 `hide()` 关闭后调用。 */
+  onHide?: () => void;
+}
+interface UseLayerReturn {
+  /** 浮层当前是否打开。 */
+  isOpen: ShallowRef<boolean>;
+  /** context 模式的锚点元素，用 `:ref` 绑到触发器上。 */
+  anchorRef: Ref<HTMLElement | null>;
+  /** 浮层内容容器，用 `:ref` 绑到浮层根元素上。 */
+  contentRef: Ref<HTMLElement | null>;
+  /** 浮层的内联样式：定位坐标，fixed 模式还带 `position: fixed`。 */
+  contentStyle: ComputedRef<CSSProperties>;
+  /** 实际生效的方位（空间不够时会翻转）。 */
+  resolvedPlacement: ComputedRef<LayerPlacement>;
+  /** 内容是否应该渲染。`lazyMount` 打开时第一次 `show()` 之前是 false。 */
+  isMounted: ComputedRef<boolean>;
+  /** 浮层的唯一 ID，用于 `aria-controls`、`aria-describedby` 这类关系。 */
+  id: string;
+  /** 锚点的 CSS 标识，用于高级定位场景。 */
+  anchorId: string;
+  /** 打开浮层。 */
+  show: () => void;
+  /** 关闭浮层。 */
+  hide: () => void;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/useLayer`：渲染浮层的最小内核。
+ * 负责开合状态、锚点定位（或固定坐标）、点击外部关闭和延迟渲染。
+ * `Popover`、`Tooltip`、`HoverCard` 都在它之上构建。
+ *
+ * 内容用 `Teleport` 送到 `body`，样式取自 `contentStyle`：
+ *
+ * ```vue
+ * <button :ref="layer.anchorRef" @click="layer.show()">打开</button>
+ * <Teleport to="body">
+ *   <div v-if="layer.isMounted" v-show="layer.isOpen" :ref="layer.contentRef" :style="layer.contentStyle">
+ *     ...
+ *   </div>
+ * </Teleport>
+ * ```
+ */
+declare function useLayer(options: UseLayerOptions): UseLayerReturn;
+//#endregion
 //#region src/composables/useListFocus.d.ts
 /**
  * 一维列表的方向。
@@ -675,8 +1041,10 @@ interface Point {
 interface LongPressOptions {
   /** Fired with the press point once the finger is held for `delayMs`. */
   onLongPress: (point: Point) => void;
-  /** When true, the detector is inert. */
-  isDisabled: () => boolean;
+  /** Read on each press. `true` keeps the detector inert. */
+  isDisabled?: MaybeRefOrGetter<boolean>;
+  /** The same switch as `isDisabled`, under the original name. Either one being true keeps the detector inert. */
+  disabled?: MaybeRefOrGetter<boolean>;
   /** Hold duration before the press fires, in ms. */
   delayMs?: number;
   /** Movement past this distance on either axis cancels the press. */
@@ -689,6 +1057,13 @@ interface LongPressHandlers {
   moveTo: (point: Point) => boolean;
   /** Drop any pending press. */
   cancel: () => void;
+  /** Touch listeners for the target element, ready to spread: `<div v-on="longPress.handlers">`. */
+  handlers: {
+    onTouchStart: (event: TouchEvent) => void;
+    onTouchMove: (event: TouchEvent) => void;
+    onTouchEnd: (event: TouchEvent) => void;
+    onTouchCancel: (event: TouchEvent) => void;
+  };
 }
 /**
  * 对应原版 Astryx 的 `hooks/useLongPress`。
@@ -698,7 +1073,10 @@ interface LongPressHandlers {
  * iOS Safari never synthesizes a `contextmenu` event for a held finger, so a
  * long press is the only touch affordance that can open a cursor-positioned
  * surface. The press is cancelled when the finger travels past the tolerance,
- * lifts, or the touch is cancelled.
+ * lifts, a second finger lands, or the touch is cancelled.
+ *
+ * 两种绑法：自己接指针事件时用 `start` / `moveTo` / `cancel`；直接要触摸监听时
+ * 把 `handlers` 摊到元素上。
  */
 declare function useLongPress(options: LongPressOptions): LongPressHandlers;
 //#endregion
@@ -720,12 +1098,55 @@ interface MenuPressOptions {
   menuRef: Ref<HTMLElement | null>;
   /** Whether the surface carries the press model right now. */
   isEnabled: () => boolean;
-  /** A mouse press that began inside the menu was released outside it. */
+  /** 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.
+   */
+  onTriggerPress?: (pointerType: 'mouse' | 'pen' | 'touch') => boolean;
+  /**
+   * Move the highlight; `null` clears it. Defaults to moving DOM focus with
+   * `preventScroll` onto the row.
+   */
+  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.
+   */
+  onActivate?: (row: HTMLElement, release: PointerEvent) => void;
+  /** How long a finger must rest on the trigger before the menu opens under it. */
+  longPressDelayMs?: number;
 }
 interface MenuPress {
   /** Attach to the menu root's `pointerdown`. */
   onPointerDown: (event: PointerEvent) => void;
+  /** Spread onto the menu root: claims presses that begin inside it. */
+  menuProps: {
+    'onPointerDown': (event: PointerEvent) => void;
+    'data-astryx-menu-press': string;
+  };
+  /** Spread onto the trigger: a mouse press opens at once, a held finger opens after the delay. */
+  triggerProps: {
+    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.
+   */
+  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.
@@ -740,9 +1161,29 @@ interface MenuPress {
  * - 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` 才开，开着的时候手指可以滑进菜单里挑行。
  */
 declare function useMenuPress(options: MenuPressOptions): MenuPress;
 //#endregion
+//#region src/composables/useMergedRefs.d.ts
+/** 可以交给 `useMergedRefs` 的目标：一个 `Ref`、一个函数 ref，或空着不填。 */
+type MergedRef<T> = Ref<T | null> | ((value: T | null) => void) | null | undefined;
+/** 合并出来的函数 ref。模板里的 `:ref` 收到的值是元素或组件实例。 */
+type MergedRefHandle = (value: Element | ComponentPublicInstance | null) => void;
+/**
+ * 对应原版 Astryx 的 `hooks/useMergedRefs`。
+ *
+ * 把多个 `Ref` 和函数 ref 合成一个函数 ref，交给模板的 `:ref`。
+ * 组件既要往外转发使用者给的 ref，又要自己留一份内部 ref 时用得上。
+ *
+ * 返回的函数在组合式函数的生命周期里只有一份。直接在模板里写
+ * `:ref="value => { ... }"` 每次渲染都会造一个新函数，Vue 会先解绑再重新绑定，
+ * 白白多做一轮解绑和挂载。
+ */
+declare function useMergedRefs<T = Element>(refs: readonly MergedRef<T>[]): MergedRefHandle;
+//#endregion
 //#region src/composables/useMonthGrid.d.ts
 declare function toISODate(date: CalendarDate): string;
 declare function parseISODate(value: string): CalendarDate;
@@ -754,17 +1195,22 @@ declare function addMonths(year: number, month: number, amount: number): {
 declare function todayISODate(): string;
 //#endregion
 //#region src/composables/useNumberField.d.ts
+type NumberStepDirection = 1 | -1;
 interface UseNumberFieldOptions {
   /** 当前值 */
   value: Ref<number | null>;
   /** 最小值 */
-  min?: number;
+  min?: MaybeRefOrGetter<number | null | undefined>;
   /** 最大值 */
-  max?: number;
+  max?: MaybeRefOrGetter<number | null | undefined>;
   /** 步进值 */
-  step?: number;
+  step?: MaybeRefOrGetter<number | null | undefined>;
   /** 是否禁用 */
-  disabled?: Ref<boolean>;
+  disabled?: MaybeRefOrGetter<boolean | undefined>;
+  /** 是否只读。只读时步进全部关闭 */
+  readOnly?: MaybeRefOrGetter<boolean | undefined>;
+  /** 是否只接受整数 */
+  integerOnly?: MaybeRefOrGetter<boolean | undefined>;
   /** 值变化回调 */
   onChange: (value: number | null) => void;
 }
@@ -773,13 +1219,19 @@ interface NumberField {
   increment: () => void;
   /** 减少值 */
   decrement: () => void;
+  /** 按方向步进。走了就返回 true */
+  step: (direction: NumberStepDirection) => boolean;
+  /** 还能不能再加一步 */
+  canIncrement: Ref<boolean>;
+  /** 还能不能再减一步 */
+  canDecrement: Ref<boolean>;
   /** 设置值（带验证） */
   setValue: (value: number | null) => void;
   /** 处理键盘事件 */
   onKeyDown: (event: KeyboardEvent) => void;
 }
 /**
- * 数字输入框逻辑：步进、范围限制、键盘增减。
+ * 数字输入框逻辑：步进、范围限制、整数限制、键盘增减。
  */
 declare function useNumberField(options: UseNumberFieldOptions): NumberField;
 //#endregion
@@ -887,6 +1339,30 @@ interface PendingChange<T> {
  */
 declare function usePendingChange<T>(action: () => ((value: T) => void | Promise<void>) | undefined): PendingChange<T>;
 //#endregion
+//#region src/composables/internal/pressFeedback.d.ts
+interface UsePressFeedbackReturn {
+  /**
+   * 铺到「背景画按压反馈」的那个元素上。
+   * 同一个元素还要配一份 `styles/pressable.css` 里的样式（引入 hook 时自动带上）。
+   */
+  pressableProps: Record<string, string>;
+}
+/**
+ * 对应原版 Astryx 的 `hooks/usePressFeedback`。
+ *
+ * 手指按下去时，CSS 的 `:active` 会在手指落下的瞬间就亮，而且滚动已经开始了它可能还亮着。
+ * 这里的按压模型反过来：先等 150 毫秒，确认这真是按压；手指一动超过 10 像素、
+ * 或者页面滚走了，马上作废，本次按压里不再亮回来；快速点一下则在抬手时补上；
+ * 松手后 200 毫秒淡出。这几个时间和系统列表的手感一致。
+ *
+ * 一个文档级控制器给所有带标记的元素做这件事（第一个用到的组件装上，最后一个卸载时拆掉），
+ * 所以调用这个组合式函数不会给你的元素加监听，也不加状态。
+ *
+ * 鼠标上的表现不变：`styles/pressable.css` 里给鼠标留了 `:active`，
+ * 在 `@media (pointer: coarse)` 之外才生效。
+ */
+declare function usePressFeedback(): UsePressFeedbackReturn;
+//#endregion
 //#region src/composables/useRestoreFocus.d.ts
 interface UseRestoreFocusOptions {
   /** 是否启用焦点恢复 */
@@ -1013,4 +1489,4 @@ interface UseTypeaheadReturn {
  */
 declare function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn;
 //#endregion
-export { UseKeyboardHint as $, useContainerReveal as $t, computeOverflow as A, isRangeWithinSpan as An, DatePresentation as At, MenuPress as B, formatISOTime as Bt, useRestoreFocus as C, ISODateRange as Cn, FieldControlStateInput as Ct, ComputeOverflowResult as D, compareISODate as Dn, DisclosureHandle as Dt, ComputeOverflowInput as E, applyRangeClick as En, useDismiss as Et, addMonths as F, ISOTimeString as Ft, LongPressHandlers as G, shiftTime as Gt, resetMenuPress as H, parseDisplayTime as Ht, buildMonthGrid as I, NativePicker as It, ListFocus as J, useControllableState as Jt, LongPressOptions as K, ControllableState as Kt, parseISODate as L, ParsedTime as Lt, NumberField as M, orderRange as Mn, resolveDatePresentation as Mt, UseNumberFieldOptions as N, resolveWeekStart as Nn, resolveDateSurface as Nt, UseOverflowOptions as O, formatDateRange as On, DisclosureHandleRef as Ot, useNumberField as P, spanDays as Pn, HourFormat as Pt, KeyboardHintOrientation as Q, UseContainerRevealOptions as Qt, toISODate as R, TimePresentation as Rt, UseRestoreFocusOptions as S, useAnnounce as Sn, FieldControlState as St, usePendingChange as T, WeekStartsOn as Tn, UseDismissOptions as Tt, useMenuPress as U, parseISOTime as Ut, MenuPressOptions as V, isTimeInRange as Vt, useMediaQuery as W, resolveTimeSurface as Wt, UseListFocusOptions as X, ContentRevealOptions as Xt, ListFocusOrientation as Y, ContainerRevealOptions as Yt, useListFocus as Z, UseContainerReveal as Zt, ScrollableAreaState as _, AppShellMobile as _n, FileRejection as _t, UseStreamingTextOptions as a, ClickableContainerHandlers as an, perceptualLightness as at, useScrollableArea as b, AnnounceFn as bn, formatFileSize as bt, ScrollOverflowState as c, useClickableContainer as cn, useHotkeys as ct, useScrollLock as d, UseChatStreamScrollReturn as dn, GridRovingFocus as dt, Combobox as en, UseKeyboardHintOptions as et, ScrollAxis as f, useChatStreamScroll as fn, UseGridRovingFocusOptions as ft, ScrollStickyContainment as g, useChatNewMessages as gn, useFocusTrap as gt, ScrollRole as h, UseChatNewMessagesReturn as hn, UseFocusTrapOptions as ht, StreamingTextSpeed as i, useCoarsePointer as in, imageModeFromPixels as it, useOverflow as j, isSameRange as jn, DateSurface as jt, UseOverflowReturn as k, isDayOutsideSpan as kn, useDisclosureHandle as kt, UseScrollOverflowResult as l, ChatScrollToBottomOptions as ln, HandleRef as lt, ScrollOverscroll as m, UseChatNewMessagesOptions as mn, FocusTrap as mt, UseTypeaheadReturn as n, UseComboboxOptions as nn, ImageSampleRegion as nt, snapToGraphemeBoundary as o, INTERACTIVE_SELECTORS as on, useImageMode as ot, ScrollAxisState as p, CHAT_MESSAGE_CLASS as pn, useGridRovingFocus as pt, useLongPress as q, UseControllableStateOptions as qt, useTypeahead as r, useCombobox as rn, UseImageModeOptions as rt, useStreamingText as s, UseClickableContainerOptions as sn, Hotkey as st, UseTypeaheadOptions as t, ComboboxOption as tn, useKeyboardHint as tt, useScrollOverflow as u, UseChatStreamScrollOptions as un, useHandleRef as ut, UseScrollableAreaOptions as v, appShellMobileKey as vn, FileSelectionOptions as vt, PendingChange as w, RangeClickResult as wn, useFieldControlState as wt, RestoreFocus as x, AnnouncePoliteness as xn, selectFiles as xt, UseScrollableAreaResult as y, useAppShellMobile as yn, FileSelectionResult as yt, todayISODate as z, formatDisplayTime as zt };
+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 };