@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.2.0

package/dist/utils/dom/ripple.js

@@ -0,0 +1,96 @@
+import { t } from "../../config/theme/tokens.js";
+import { useConfig } from "../../config/context.js";
+import { applyStyleAttrs } from "../props.js";
+import { afterTransitions } from "../style/transitions.js";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+//#region src/utils/dom/ripple.ts
+/**
+* 波纹：按下时从指针位置扩散出一圈半透明的颜色，松开后淡出（键盘按下 Enter / 空格时从中心扩散）。
+* 纯 CSS 动画，时长取主题的 durations：开启“减少动态效果”时没有扩散过程，只是按下时变色。
+* 按钮、导航项、菜单项等可点击的组件共用；宿主元素加 rippleHostStyles.host（定位与裁切）。
+* 默认开启，createUi / Provider 的 ripple 全局开关，组件的 ripple prop 单独覆盖（见 useRipple）。
+*
+*   const ripple = useRipple(() => props.ripple)
+*   mergeAttrs<'button'>(默认, rest, { ...ripple })
+*/
+var expand = css.keyframes({
+	from: { transform: "scale(0)" },
+	to: { transform: "scale(1)" }
+});
+/** 宿主元素需要的样式：波纹相对它定位，超出圆角的部分裁掉 */
+var rippleHostStyles = css.create({ host: {
+	position: "relative",
+	overflow: "hidden"
+} });
+/** 波纹 的样式：ripple、fading */
+var rippleStyles = css.create({
+	ripple: {
+		position: "absolute",
+		borderRadius: "_full",
+		pointerEvents: "none",
+		backgroundColor: "color-mix(in srgb, currentColor 22%, transparent)",
+		animationName: expand,
+		animationDuration: "_durations.lg",
+		animationTimingFunction: "_easings.standard",
+		animationFillMode: "forwards",
+		transition: `opacity ${t.durations.md} ${t.easings.exit}`
+	},
+	fading: { opacity: 0 }
+});
+/** 波纹 的样式：at */
+var ripplePlacementStyles = css.create({ at: (x, y, size) => ({
+	left: x,
+	top: y,
+	width: size,
+	height: size
+}) });
+/**
+* 组件里用的波纹：按开关决定是否出波纹，返回的两个处理函数展开到宿主元素上（`...ripple`）。
+* own 读组件自己的 ripple prop（没写时为 undefined，沿用配置）；在 setup 里调用
+*/
+function useRipple(own) {
+	const config = useConfig();
+	const handler = (event) => {
+		if (own() ?? config.ripple) startRipple(event);
+	};
+	return {
+		onPointerdown: handler,
+		onKeydown: handler
+	};
+}
+/** 不可用的宿主不出波纹 */
+var isDisabled = (host) => host.matches(":disabled, [aria-disabled=\"true\"]");
+/**
+* 在 event.currentTarget 上开始一个波纹，松开、移出、取消或失去焦点时淡出并移除。
+* 键盘事件只认 Enter 与空格（按住不放的重复事件忽略）。
+*/
+function startRipple(event) {
+	const host = event.currentTarget;
+	if (!(host instanceof HTMLElement) || isDisabled(host)) return;
+	const keyboard = event instanceof KeyboardEvent;
+	if (keyboard && (event.repeat || event.key !== "Enter" && event.key !== " ")) return;
+	if (!keyboard && event.button !== 0) return;
+	const rect = host.getBoundingClientRect();
+	const x = keyboard ? rect.width / 2 : event.clientX - rect.left;
+	const y = keyboard ? rect.height / 2 : event.clientY - rect.top;
+	const radius = Math.hypot(Math.max(x, rect.width - x), Math.max(y, rect.height - y));
+	const ripple = document.createElement("span");
+	ripple.setAttribute("aria-hidden", "true");
+	applyStyleAttrs(ripple, css.attrs(rippleStyles.ripple, ripplePlacementStyles.at(x - radius, y - radius, radius * 2)));
+	host.append(ripple);
+	const release = () => {
+		for (const [type, target] of releaseEvents) target.removeEventListener(type, release);
+		ripple.classList.add(...(css.attrs(rippleStyles.fading).class ?? "").split(" "));
+		afterTransitions(ripple).then(() => ripple.remove());
+	};
+	const releaseEvents = keyboard ? [["keyup", host], ["blur", host]] : [
+		["pointerup", window],
+		["pointercancel", window],
+		["pointerleave", host]
+	];
+	for (const [type, target] of releaseEvents) target.addEventListener(type, release);
+}
+//#endregion
+export { rippleHostStyles, ripplePlacementStyles, rippleStyles, startRipple, useRipple };
+
+//# sourceMappingURL=ripple.js.map

package/dist/utils/dom/ripple.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ripple.js","names":[],"sources":["../../../src/utils/dom/ripple.ts"],"sourcesContent":["/**\n * 波纹：按下时从指针位置扩散出一圈半透明的颜色，松开后淡出（键盘按下 Enter / 空格时从中心扩散）。\n * 纯 CSS 动画，时长取主题的 durations：开启“减少动态效果”时没有扩散过程，只是按下时变色。\n * 按钮、导航项、菜单项等可点击的组件共用；宿主元素加 rippleHostStyles.host（定位与裁切）。\n * 默认开启，createUi / Provider 的 ripple 全局开关，组件的 ripple prop 单独覆盖（见 useRipple）。\n *\n *   const ripple = useRipple(() => props.ripple)\n *   mergeAttrs<'button'>(默认, rest, { ...ripple })\n */\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport { useConfig } from '../../config/context';\nimport { applyStyleAttrs } from '../props';\nimport { afterTransitions } from '../style/transitions';\nimport { t } from '../../config/theme/tokens';\n\nconst expand = css.keyframes({\n  from: { transform: 'scale(0)' },\n  to: { transform: 'scale(1)' },\n});\n\n/** 宿主元素需要的样式：波纹相对它定位，超出圆角的部分裁掉 */\nexport const rippleHostStyles = css.create({\n  host: { position: 'relative', overflow: 'hidden' },\n});\n\n/** 波纹 的样式：ripple、fading */\nexport const rippleStyles = css.create({\n  ripple: {\n    position: 'absolute',\n    borderRadius: '_full',\n    pointerEvents: 'none',\n    // 跟随文字颜色：实底按钮上是浅色，描边按钮上是深色\n    backgroundColor: 'color-mix(in srgb, currentColor 22%, transparent)',\n    animationName: expand,\n    animationDuration: '_durations.lg',\n    animationTimingFunction: '_easings.standard',\n    animationFillMode: 'forwards',\n    transition: `opacity ${t.durations.md} ${t.easings.exit}`,\n  },\n  fading: { opacity: 0 },\n});\n\n// 位置与大小是任意值，用动态样式；单独一个 create，见 COMPONENTS.md §4\n/** 波纹 的样式：at */\nexport const ripplePlacementStyles = css.create({\n  at: (x: number, y: number, size: number) => ({ left: x, top: y, width: size, height: size }),\n});\n\n/** useRipple 的结果：展开到宿主元素上（mergeProps 的受管层） */\nexport interface RippleHandlers {\n  /** 指针按下：从按下的位置扩散 */\n  onPointerdown: (event: PointerEvent) => void;\n  /** Enter / 空格：从中心扩散 */\n  onKeydown: (event: KeyboardEvent) => void;\n}\n\n/**\n * 组件里用的波纹：按开关决定是否出波纹，返回的两个处理函数展开到宿主元素上（`...ripple`）。\n * own 读组件自己的 ripple prop（没写时为 undefined，沿用配置）；在 setup 里调用\n */\nexport function useRipple(own: () => boolean | undefined): RippleHandlers {\n  const config = useConfig();\n  const handler = (event: PointerEvent | KeyboardEvent) => {\n    if (own() ?? config.ripple) startRipple(event);\n  };\n  return { onPointerdown: handler, onKeydown: handler };\n}\n\n/** 不可用的宿主不出波纹 */\nconst isDisabled = (host: Element) => host.matches(':disabled, [aria-disabled=\"true\"]');\n\n/**\n * 在 event.currentTarget 上开始一个波纹，松开、移出、取消或失去焦点时淡出并移除。\n * 键盘事件只认 Enter 与空格（按住不放的重复事件忽略）。\n */\nexport function startRipple(event: PointerEvent | KeyboardEvent): void {\n  const host = event.currentTarget;\n  if (!(host instanceof HTMLElement) || isDisabled(host)) return;\n  const keyboard = event instanceof KeyboardEvent;\n  if (keyboard && (event.repeat || (event.key !== 'Enter' && event.key !== ' '))) return;\n  if (!keyboard && event.button !== 0) return;\n\n  const rect = host.getBoundingClientRect();\n  const x = keyboard ? rect.width / 2 : event.clientX - rect.left;\n  const y = keyboard ? rect.height / 2 : event.clientY - rect.top;\n  // 圆心到最远的角的距离：扩散完正好盖满整个元素\n  const radius = Math.hypot(Math.max(x, rect.width - x), Math.max(y, rect.height - y));\n  const ripple = document.createElement('span');\n  ripple.setAttribute('aria-hidden', 'true');\n  applyStyleAttrs(\n    ripple,\n    css.attrs(rippleStyles.ripple, ripplePlacementStyles.at(x - radius, y - radius, radius * 2)),\n  );\n  host.append(ripple);\n\n  const release = () => {\n    for (const [type, target] of releaseEvents) target.removeEventListener(type, release);\n    ripple.classList.add(...(css.attrs(rippleStyles.fading).class ?? '').split(' '));\n    void afterTransitions(ripple).then(() => ripple.remove());\n  };\n  const releaseEvents: [string, EventTarget][] = keyboard\n    ? [\n        ['keyup', host],\n        ['blur', host],\n      ]\n    : [\n        ['pointerup', window],\n        ['pointercancel', window],\n        ['pointerleave', host],\n      ];\n  for (const [type, target] of releaseEvents) target.addEventListener(type, release);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,IAAM,SAAS,IAAI,UAAU;CAC3B,MAAM,EAAE,WAAW,WAAW;CAC9B,IAAI,EAAE,WAAW,WAAW;AAC9B,CAAC;;AAGD,IAAa,mBAAmB,IAAI,OAAO,EACzC,MAAM;CAAE,UAAU;CAAY,UAAU;AAAS,EACnD,CAAC;;AAGD,IAAa,eAAe,IAAI,OAAO;CACrC,QAAQ;EACN,UAAU;EACV,cAAc;EACd,eAAe;EAEf,iBAAiB;EACjB,eAAe;EACf,mBAAmB;EACnB,yBAAyB;EACzB,mBAAmB;EACnB,YAAY,WAAW,EAAE,UAAU,GAAE,GAAI,EAAE,QAAQ;CACrD;CACA,QAAQ,EAAE,SAAS,EAAE;AACvB,CAAC;;AAID,IAAa,wBAAwB,IAAI,OAAO,EAC9C,KAAK,GAAW,GAAW,UAAkB;CAAE,MAAM;CAAG,KAAK;CAAG,OAAO;CAAM,QAAQ;AAAK,GAC5F,CAAC;;;;;AAcD,SAAgB,UAAU,KAAgD;CACxE,MAAM,SAAS,UAAU;CACzB,MAAM,WAAW,UAAwC;EACvD,IAAI,IAAI,KAAK,OAAO,QAAQ,YAAY,KAAK;CAC/C;CACA,OAAO;EAAE,eAAe;EAAS,WAAW;CAAQ;AACtD;;AAGA,IAAM,cAAc,SAAkB,KAAK,QAAQ,qCAAmC;;;;;AAMtF,SAAgB,YAAY,OAA2C;CACrE,MAAM,OAAO,MAAM;CACnB,IAAI,EAAE,gBAAgB,gBAAgB,WAAW,IAAI,GAAG;CACxD,MAAM,WAAW,iBAAiB;CAClC,IAAI,aAAa,MAAM,UAAW,MAAM,QAAQ,WAAW,MAAM,QAAQ,MAAO;CAChF,IAAI,CAAC,YAAY,MAAM,WAAW,GAAG;CAErC,MAAM,OAAO,KAAK,sBAAsB;CACxC,MAAM,IAAI,WAAW,KAAK,QAAQ,IAAI,MAAM,UAAU,KAAK;CAC3D,MAAM,IAAI,WAAW,KAAK,SAAS,IAAI,MAAM,UAAU,KAAK;CAE5D,MAAM,SAAS,KAAK,MAAM,KAAK,IAAI,GAAG,KAAK,QAAQ,CAAC,GAAG,KAAK,IAAI,GAAG,KAAK,SAAS,CAAC,CAAC;CACnF,MAAM,SAAS,SAAS,cAAc,MAAM;CAC5C,OAAO,aAAa,eAAe,MAAM;CACzC,gBACE,QACA,IAAI,MAAM,aAAa,QAAQ,sBAAsB,GAAG,IAAI,QAAQ,IAAI,QAAQ,SAAS,CAAC,CAAC,CAC7F;CACA,KAAK,OAAO,MAAM;CAElB,MAAM,gBAAgB;EACpB,KAAK,MAAM,CAAC,MAAM,WAAW,eAAe,OAAO,oBAAoB,MAAM,OAAO;EACpF,OAAO,UAAU,IAAI,IAAI,IAAI,MAAM,aAAa,MAAM,CAAC,CAAC,SAAS,GAAA,CAAI,MAAM,GAAG,CAAC;EAC/E,iBAAsB,MAAM,CAAC,CAAC,WAAW,OAAO,OAAO,CAAC;CAC1D;CACA,MAAM,gBAAyC,WAC3C,CACE,CAAC,SAAS,IAAI,GACd,CAAC,QAAQ,IAAI,CAAC,IAEhB;EACE,CAAC,aAAa,MAAM;EACpB,CAAC,iBAAiB,MAAM;EACxB,CAAC,gBAAgB,IAAI;CAAC;CAE5B,KAAK,MAAM,CAAC,MAAM,WAAW,eAAe,OAAO,iBAAiB,MAAM,OAAO;AACnF"}

package/dist/utils/dom/roving-focus.d.ts

@@ -0,0 +1,44 @@
+/** 方向键的方向 */
+export interface RovingOrientations {
+    /** 左右键（从右到左排版时反过来） */
+    horizontal: unknown;
+    /** 上下键 */
+    vertical: unknown;
+    /** 四个方向键都可以（如分页、网格状的工具栏） */
+    both: unknown;
+}
+/** rovingFocus 的选项 */
+export interface RovingFocusOptions {
+    /** 项的选择器，在容器内查找；不可用（disabled、aria-disabled="true"）、隐藏的项跳过 */
+    items: string;
+    /** 方向键的方向，默认 horizontal */
+    orientation?: keyof RovingOrientations;
+    /** 到两端后是否从另一端继续，默认 true */
+    loop?: boolean;
+    /** 按字母跳到以它开头的项（菜单、列表），默认 false；匹配的是项的文字 */
+    typeahead?: boolean;
+    /** Tab 进入时落在哪一项：默认是上次聚焦的项，其次是选中或当前的项（aria-selected / pressed / checked / current），再其次是第一项 */
+    initial?: (items: HTMLElement[]) => HTMLElement | undefined;
+}
+/** 开始管理容器里各项的焦点，返回清理函数 */
+export declare function rovingFocus(container: HTMLElement, options: RovingFocusOptions): () => void;
+/** gridFocus 的选项 */
+export interface GridFocusOptions {
+    /** 行的选择器，在容器内查找（如 `[role="row"]`） */
+    rows: string;
+    /** 行里可聚焦的格的选择器（格本身，或格里的按钮）；不可用、隐藏的格跳过 */
+    cells: string;
+    /** PageUp / PageDown 一次移动几行，默认 10 */
+    pageRows?: number;
+    /** Tab 进入时落在哪一格：默认是上次聚焦的格，其次是选中或当前的格，再其次是第一格 */
+    initial?: (cells: HTMLElement[]) => HTMLElement | undefined;
+}
+/**
+ * 网格的漫游焦点（WAI-ARIA 的 Grid 模式）：整个网格只有一格能用 Tab 进入，方向键在行列之间移动。
+ * ← → 在行内移动（从右到左排版时反过来），↑ ↓ 到上下一行的同一列（那一行短时到最后一格），
+ * Home / End 到行首、行尾，Ctrl + Home / End 到第一格、最后一格，PageUp / PageDown 跨几行。不循环。
+ * 表格的单元格导航、整页日历用它；行、格增删时自动重新计算。返回清理函数
+ *
+ *   _effect(() => (table ? gridFocus(table, { rows: 'tr', cells: '[role="gridcell"]' }) : undefined));
+ */
+export declare function gridFocus(container: HTMLElement, options: GridFocusOptions): () => void;

package/dist/utils/dom/roving-focus.js

@@ -0,0 +1,184 @@
+import { clamp } from "../data/number.js";
+import { isRtl } from "./direction.js";
+import { createTypeahead } from "./typeahead.js";
+//#region src/utils/dom/roving-focus.ts
+/**
+* 漫游焦点（WAI-ARIA 的 roving tabindex）：一组项里只有一个能用 Tab 进入（tabindex=0），其余为 -1；
+* 组内用方向键移动，Home / End 到两端。Tabs、Toolbar、Menu、ToggleGroup 共用（参考 Radix 的 RovingFocusGroup）。
+* 二维的网格（表格的单元格、整页日历）用 gridFocus：方向键在行列之间移动。
+*
+* 直接管理容器里各项的 tabindex（组件渲染时不要再写 tabindex），所以项可以是任意可聚焦元素：
+* 工具栏里的按钮、标签页、链接都行。项增删、选中项变化时自动重新计算。
+*
+*   _effect(() => (list ? rovingFocus(list, { items: '[role="tab"]', orientation: 'horizontal' }) : undefined));
+*/
+/** 可以停留：没有不可用，也不在隐藏或 inert 的区域里 */
+var isEnabled = (element) => !element.matches(":disabled, [aria-disabled=\"true\"]") && !element.closest("[hidden], [inert]");
+/** 选中或当前的项：Tab 进入时优先落在它上面 */
+var isMarked = (element) => element.getAttribute("aria-selected") === "true" || element.getAttribute("aria-pressed") === "true" || element.getAttribute("aria-checked") === "true" || element.hasAttribute("aria-current") && element.getAttribute("aria-current") !== "false";
+/** 开始管理容器里各项的焦点，返回清理函数 */
+function rovingFocus(container, options) {
+	const { orientation = "horizontal", loop = true } = options;
+	const typeahead = options.typeahead ? createTypeahead() : void 0;
+	let current;
+	const all = () => [...container.querySelectorAll(options.items)].filter((item) => {
+		if (item.parentElement?.closest("[data-roving-focus]") !== container) return false;
+		const layer = item.closest("[popover], dialog");
+		return !layer || layer === container || !container.contains(layer);
+	});
+	const enabled = () => all().filter(isEnabled);
+	/** 定下哪一项是 Tab 进入点，其余设为 -1 */
+	function sync() {
+		const items = enabled();
+		const stop = (current && items.includes(current) ? current : void 0) ?? options.initial?.(items) ?? items.find(isMarked) ?? items[0];
+		for (const item of all()) {
+			const value = item === stop ? "0" : "-1";
+			if (item.getAttribute("tabindex") !== value) item.setAttribute("tabindex", value);
+		}
+	}
+	function onKeydown(event) {
+		if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;
+		const items = enabled();
+		const index = items.indexOf(event.target);
+		if (index < 0) return;
+		const rtl = isRtl(container);
+		const horizontal = orientation !== "vertical";
+		const vertical = orientation !== "horizontal";
+		const step = {
+			ArrowRight: horizontal ? rtl ? -1 : 1 : void 0,
+			ArrowLeft: horizontal ? rtl ? 1 : -1 : void 0,
+			ArrowDown: vertical ? 1 : void 0,
+			ArrowUp: vertical ? -1 : void 0,
+			Home: "first",
+			End: "last"
+		}[event.key];
+		if (step === void 0) {
+			const match = typeahead?.next(event.key, items.map((item) => item.textContent ?? ""), index);
+			if (match != null && match >= 0) {
+				event.preventDefault();
+				items[match].focus();
+			}
+			return;
+		}
+		event.preventDefault();
+		let next;
+		if (step === "first") next = 0;
+		else if (step === "last") next = items.length - 1;
+		else if (loop) next = (index + step + items.length) % items.length;
+		else next = clamp(index + step, 0, items.length - 1);
+		items[next].focus();
+	}
+	function onFocusin(event) {
+		const target = event.target;
+		if (!all().includes(target)) return;
+		current = target;
+		sync();
+	}
+	container.setAttribute("data-roving-focus", "");
+	container.addEventListener("keydown", onKeydown);
+	container.addEventListener("focusin", onFocusin);
+	const observer = new MutationObserver(sync);
+	observer.observe(container, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [
+			"disabled",
+			"aria-disabled",
+			"aria-selected",
+			"aria-pressed",
+			"aria-checked",
+			"aria-current",
+			"hidden",
+			"data-roving-focus"
+		]
+	});
+	sync();
+	return () => {
+		container.removeAttribute("data-roving-focus");
+		container.removeEventListener("keydown", onKeydown);
+		container.removeEventListener("focusin", onFocusin);
+		observer.disconnect();
+	};
+}
+/**
+* 网格的漫游焦点（WAI-ARIA 的 Grid 模式）：整个网格只有一格能用 Tab 进入，方向键在行列之间移动。
+* ← → 在行内移动（从右到左排版时反过来），↑ ↓ 到上下一行的同一列（那一行短时到最后一格），
+* Home / End 到行首、行尾，Ctrl + Home / End 到第一格、最后一格，PageUp / PageDown 跨几行。不循环。
+* 表格的单元格导航、整页日历用它；行、格增删时自动重新计算。返回清理函数
+*
+*   _effect(() => (table ? gridFocus(table, { rows: 'tr', cells: '[role="gridcell"]' }) : undefined));
+*/
+function gridFocus(container, options) {
+	const pageRows = options.pageRows ?? 10;
+	let current;
+	/** 各行里能停留的格（空行去掉） */
+	const grid = () => [...container.querySelectorAll(options.rows)].map((row) => [...row.querySelectorAll(options.cells)].filter(isEnabled)).filter((cells) => cells.length > 0);
+	const allCells = () => [...container.querySelectorAll(options.cells)];
+	function sync() {
+		const cells = grid().flat();
+		const stop = (current && cells.includes(current) ? current : void 0) ?? options.initial?.(cells) ?? cells.find(isMarked) ?? cells[0];
+		for (const cell of allCells()) {
+			const value = cell === stop ? "0" : "-1";
+			if (cell.getAttribute("tabindex") !== value) cell.setAttribute("tabindex", value);
+		}
+	}
+	function onKeydown(event) {
+		if (event.defaultPrevented || event.altKey || event.metaKey) return;
+		const rows = grid();
+		const row = rows.findIndex((cells) => cells.includes(event.target));
+		if (row < 0) return;
+		const column = rows[row].indexOf(event.target);
+		const rtl = isRtl(container);
+		const last = rows.length - 1;
+		const at = (r, c) => {
+			const cells = rows[clamp(r, 0, last)];
+			return cells[clamp(c, 0, cells.length - 1)];
+		};
+		const ctrl = event.ctrlKey;
+		const next = {
+			ArrowRight: ctrl ? void 0 : () => at(row, column + (rtl ? -1 : 1)),
+			ArrowLeft: ctrl ? void 0 : () => at(row, column + (rtl ? 1 : -1)),
+			ArrowDown: ctrl ? void 0 : () => at(row + 1, column),
+			ArrowUp: ctrl ? void 0 : () => at(row - 1, column),
+			Home: () => ctrl ? rows[0][0] : rows[row][0],
+			End: () => ctrl ? rows[last].at(-1) : rows[row].at(-1),
+			PageDown: ctrl ? void 0 : () => at(row + pageRows, column),
+			PageUp: ctrl ? void 0 : () => at(row - pageRows, column)
+		}[event.key]?.();
+		if (!next) return;
+		event.preventDefault();
+		next.focus();
+	}
+	function onFocusin(event) {
+		const target = event.target;
+		if (!allCells().includes(target)) return;
+		current = target;
+		sync();
+	}
+	container.addEventListener("keydown", onKeydown);
+	container.addEventListener("focusin", onFocusin);
+	const observer = new MutationObserver(sync);
+	observer.observe(container, {
+		childList: true,
+		subtree: true,
+		attributes: true,
+		attributeFilter: [
+			"disabled",
+			"aria-disabled",
+			"aria-selected",
+			"aria-current",
+			"hidden"
+		]
+	});
+	sync();
+	return () => {
+		container.removeEventListener("keydown", onKeydown);
+		container.removeEventListener("focusin", onFocusin);
+		observer.disconnect();
+	};
+}
+//#endregion
+export { gridFocus, rovingFocus };
+
+//# sourceMappingURL=roving-focus.js.map

package/dist/utils/dom/roving-focus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-focus.js","names":[],"sources":["../../../src/utils/dom/roving-focus.ts"],"sourcesContent":["/**\n * 漫游焦点（WAI-ARIA 的 roving tabindex）：一组项里只有一个能用 Tab 进入（tabindex=0），其余为 -1；\n * 组内用方向键移动，Home / End 到两端。Tabs、Toolbar、Menu、ToggleGroup 共用（参考 Radix 的 RovingFocusGroup）。\n * 二维的网格（表格的单元格、整页日历）用 gridFocus：方向键在行列之间移动。\n *\n * 直接管理容器里各项的 tabindex（组件渲染时不要再写 tabindex），所以项可以是任意可聚焦元素：\n * 工具栏里的按钮、标签页、链接都行。项增删、选中项变化时自动重新计算。\n *\n *   _effect(() => (list ? rovingFocus(list, { items: '[role=\"tab\"]', orientation: 'horizontal' }) : undefined));\n */\nimport { clamp } from '../data/number';\nimport { isRtl } from './direction';\nimport { createTypeahead } from './typeahead';\n\n/** 方向键的方向 */\nexport interface RovingOrientations {\n  /** 左右键（从右到左排版时反过来） */\n  horizontal: unknown;\n  /** 上下键 */\n  vertical: unknown;\n  /** 四个方向键都可以（如分页、网格状的工具栏） */\n  both: unknown;\n}\n\n/** rovingFocus 的选项 */\nexport interface RovingFocusOptions {\n  /** 项的选择器，在容器内查找；不可用（disabled、aria-disabled=\"true\"）、隐藏的项跳过 */\n  items: string;\n  /** 方向键的方向，默认 horizontal */\n  orientation?: keyof RovingOrientations;\n  /** 到两端后是否从另一端继续，默认 true */\n  loop?: boolean;\n  /** 按字母跳到以它开头的项（菜单、列表），默认 false；匹配的是项的文字 */\n  typeahead?: boolean;\n  /** Tab 进入时落在哪一项：默认是上次聚焦的项，其次是选中或当前的项（aria-selected / pressed / checked / current），再其次是第一项 */\n  initial?: (items: HTMLElement[]) => HTMLElement | undefined;\n}\n\n/** 可以停留：没有不可用，也不在隐藏或 inert 的区域里 */\nconst isEnabled = (element: HTMLElement) =>\n  !element.matches(':disabled, [aria-disabled=\"true\"]') && !element.closest('[hidden], [inert]');\n\n/** 选中或当前的项：Tab 进入时优先落在它上面 */\nconst isMarked = (element: HTMLElement) =>\n  element.getAttribute('aria-selected') === 'true' ||\n  element.getAttribute('aria-pressed') === 'true' ||\n  element.getAttribute('aria-checked') === 'true' ||\n  (element.hasAttribute('aria-current') && element.getAttribute('aria-current') !== 'false');\n\n/** 开始管理容器里各项的焦点，返回清理函数 */\nexport function rovingFocus(container: HTMLElement, options: RovingFocusOptions): () => void {\n  const { orientation = 'horizontal', loop = true } = options;\n  const typeahead = options.typeahead ? createTypeahead() : undefined;\n  let current: HTMLElement | undefined;\n\n  // 嵌套的组（自己也调用了 rovingFocus 的容器）各管各的：只取最近的组是自己的项。\n  // 工具栏里的 ToggleGroup 不调用，它的按钮归工具栏\n  // 容器里的弹层（popover、dialog）是另一个焦点范围：工具栏里 Popover 的面板、对话框里的按钮不归工具栏\n  const all = () =>\n    [...container.querySelectorAll<HTMLElement>(options.items)].filter((item) => {\n      if (item.parentElement?.closest('[data-roving-focus]') !== container) return false;\n      const layer = item.closest('[popover], dialog');\n      // 容器自己就是弹层（菜单的面板）时，它里面的项照常归它\n      return !layer || layer === container || !container.contains(layer);\n    });\n  const enabled = () => all().filter(isEnabled);\n\n  /** 定下哪一项是 Tab 进入点，其余设为 -1 */\n  function sync() {\n    const items = enabled();\n    const stop =\n      (current && items.includes(current) ? current : undefined) ??\n      options.initial?.(items) ??\n      items.find(isMarked) ??\n      items[0];\n    for (const item of all()) {\n      const value = item === stop ? '0' : '-1';\n      if (item.getAttribute('tabindex') !== value) item.setAttribute('tabindex', value);\n    }\n  }\n\n  function onKeydown(event: KeyboardEvent) {\n    if (event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey) return;\n    const items = enabled();\n    const index = items.indexOf(event.target as HTMLElement);\n    if (index < 0) return;\n    const rtl = isRtl(container);\n    const horizontal = orientation !== 'vertical';\n    const vertical = orientation !== 'horizontal';\n    const steps: Record<string, number | 'first' | 'last' | undefined> = {\n      ArrowRight: horizontal ? (rtl ? -1 : 1) : undefined,\n      ArrowLeft: horizontal ? (rtl ? 1 : -1) : undefined,\n      ArrowDown: vertical ? 1 : undefined,\n      ArrowUp: vertical ? -1 : undefined,\n      Home: 'first',\n      End: 'last',\n    };\n    const step = steps[event.key];\n    if (step === undefined) {\n      const match = typeahead?.next(\n        event.key,\n        items.map((item) => item.textContent ?? ''),\n        index,\n      );\n      if (match != null && match >= 0) {\n        event.preventDefault();\n        items[match]!.focus();\n      }\n      return;\n    }\n    event.preventDefault();\n    let next: number;\n    if (step === 'first') next = 0;\n    else if (step === 'last') next = items.length - 1;\n    else if (loop) next = (index + step + items.length) % items.length;\n    else next = clamp(index + step, 0, items.length - 1);\n    items[next]!.focus();\n  }\n\n  function onFocusin(event: FocusEvent) {\n    const target = event.target as HTMLElement;\n    if (!all().includes(target)) return;\n    current = target;\n    sync();\n  }\n\n  container.setAttribute('data-roving-focus', '');\n  container.addEventListener('keydown', onKeydown);\n  container.addEventListener('focusin', onFocusin);\n  // 项增删、选中或可用状态变化时重新定 Tab 进入点\n  const observer = new MutationObserver(sync);\n  observer.observe(container, {\n    childList: true,\n    subtree: true,\n    attributes: true,\n    attributeFilter: [\n      'disabled',\n      'aria-disabled',\n      'aria-selected',\n      'aria-pressed',\n      'aria-checked',\n      'aria-current',\n      'hidden',\n      // 嵌套的组挂载时（子组件先于父组件）重新划分各组的项\n      'data-roving-focus',\n    ],\n  });\n  sync();\n\n  return () => {\n    container.removeAttribute('data-roving-focus');\n    container.removeEventListener('keydown', onKeydown);\n    container.removeEventListener('focusin', onFocusin);\n    observer.disconnect();\n  };\n}\n\n/** gridFocus 的选项 */\nexport interface GridFocusOptions {\n  /** 行的选择器，在容器内查找（如 `[role=\"row\"]`） */\n  rows: string;\n  /** 行里可聚焦的格的选择器（格本身，或格里的按钮）；不可用、隐藏的格跳过 */\n  cells: string;\n  /** PageUp / PageDown 一次移动几行，默认 10 */\n  pageRows?: number;\n  /** Tab 进入时落在哪一格：默认是上次聚焦的格，其次是选中或当前的格，再其次是第一格 */\n  initial?: (cells: HTMLElement[]) => HTMLElement | undefined;\n}\n\n/**\n * 网格的漫游焦点（WAI-ARIA 的 Grid 模式）：整个网格只有一格能用 Tab 进入，方向键在行列之间移动。\n * ← → 在行内移动（从右到左排版时反过来），↑ ↓ 到上下一行的同一列（那一行短时到最后一格），\n * Home / End 到行首、行尾，Ctrl + Home / End 到第一格、最后一格，PageUp / PageDown 跨几行。不循环。\n * 表格的单元格导航、整页日历用它；行、格增删时自动重新计算。返回清理函数\n *\n *   _effect(() => (table ? gridFocus(table, { rows: 'tr', cells: '[role=\"gridcell\"]' }) : undefined));\n */\nexport function gridFocus(container: HTMLElement, options: GridFocusOptions): () => void {\n  const pageRows = options.pageRows ?? 10;\n  let current: HTMLElement | undefined;\n\n  /** 各行里能停留的格（空行去掉） */\n  const grid = () =>\n    [...container.querySelectorAll<HTMLElement>(options.rows)]\n      .map((row) => [...row.querySelectorAll<HTMLElement>(options.cells)].filter(isEnabled))\n      .filter((cells) => cells.length > 0);\n  const allCells = () => [...container.querySelectorAll<HTMLElement>(options.cells)];\n\n  function sync() {\n    const cells = grid().flat();\n    const stop =\n      (current && cells.includes(current) ? current : undefined) ??\n      options.initial?.(cells) ??\n      cells.find(isMarked) ??\n      cells[0];\n    for (const cell of allCells()) {\n      const value = cell === stop ? '0' : '-1';\n      if (cell.getAttribute('tabindex') !== value) cell.setAttribute('tabindex', value);\n    }\n  }\n\n  function onKeydown(event: KeyboardEvent) {\n    if (event.defaultPrevented || event.altKey || event.metaKey) return;\n    const rows = grid();\n    const row = rows.findIndex((cells) => cells.includes(event.target as HTMLElement));\n    if (row < 0) return;\n    const column = rows[row]!.indexOf(event.target as HTMLElement);\n    const rtl = isRtl(container);\n    const last = rows.length - 1;\n    const at = (r: number, c: number) => {\n      const cells = rows[clamp(r, 0, last)]!;\n      return cells[clamp(c, 0, cells.length - 1)];\n    };\n    const ctrl = event.ctrlKey;\n    const targets: Record<string, (() => HTMLElement | undefined) | undefined> = {\n      ArrowRight: ctrl ? undefined : () => at(row, column + (rtl ? -1 : 1)),\n      ArrowLeft: ctrl ? undefined : () => at(row, column + (rtl ? 1 : -1)),\n      ArrowDown: ctrl ? undefined : () => at(row + 1, column),\n      ArrowUp: ctrl ? undefined : () => at(row - 1, column),\n      Home: () => (ctrl ? rows[0]![0] : rows[row]![0]),\n      End: () => (ctrl ? rows[last]!.at(-1) : rows[row]!.at(-1)),\n      PageDown: ctrl ? undefined : () => at(row + pageRows, column),\n      PageUp: ctrl ? undefined : () => at(row - pageRows, column),\n    };\n    const next = targets[event.key]?.();\n    if (!next) return;\n    event.preventDefault();\n    next.focus();\n  }\n\n  function onFocusin(event: FocusEvent) {\n    const target = event.target as HTMLElement;\n    if (!allCells().includes(target)) return;\n    current = target;\n    sync();\n  }\n\n  container.addEventListener('keydown', onKeydown);\n  container.addEventListener('focusin', onFocusin);\n  const observer = new MutationObserver(sync);\n  observer.observe(container, {\n    childList: true,\n    subtree: true,\n    attributes: true,\n    attributeFilter: ['disabled', 'aria-disabled', 'aria-selected', 'aria-current', 'hidden'],\n  });\n  sync();\n\n  return () => {\n    container.removeEventListener('keydown', onKeydown);\n    container.removeEventListener('focusin', onFocusin);\n    observer.disconnect();\n  };\n}\n"],"mappings":"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"}

package/dist/utils/dom/scroll-spy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 滚动高亮（scroll spy）：页面滚到哪一节，就报告哪一节的 id。TableOfContents 用它高亮当前小节。
+ *
+ *   const current = useScrollSpy(() => ({ ids: headings.map((heading) => heading.id) }));
+ *
+ * 当前节 = 顶部已经越过阅读线的最后一个元素；阅读线是元素自己的 scroll-margin-top（标题让开粘性顶栏的距离，
+ * 见 layoutVars.stickyOffset），所以点目录跳过去之后，高亮的正好是跳到的那一节。
+ * 滚到底时最后几节可能永远到不了阅读线：这时高亮视口里的最后一个。
+ */
+import { type Ref } from 'vue';
+/** useScrollSpy 每次读取的选项 */
+export interface ScrollSpyOptions {
+    /** 要追踪的元素的 id，按文档顺序 */
+    ids: readonly string[];
+    /** 滚动容器；不写时是页面（窗口） */
+    root?: HTMLElement | null;
+}
+/** 当前节的 id（在 setup 里调用）；还没滚到第一节时为 undefined */
+export declare function useScrollSpy(read: () => ScrollSpyOptions): Readonly<Ref<string | undefined>>;
+/** 目录里的一项 */
+export interface HeadingEntry {
+    /** 标题的 id（锚点） */
+    id: string;
+    /** 标题文字 */
+    label: string;
+    /** 标题级别：2 是 h2，3 是 h3… */
+    level: number;
+}
+/** 收集容器里带 id 的标题，生成目录（页面渲染后调用）；默认收集 h2、h3 */
+export declare function collectHeadings(container: ParentNode, selector?: string): HeadingEntry[];

package/dist/utils/dom/scroll-spy.js

@@ -0,0 +1,55 @@
+import { useEventListener } from "./event-listener.js";
+import { onMounted, onScopeDispose, shallowRef, watch } from "vue";
+//#region src/utils/dom/scroll-spy.ts
+/**
+* 滚动高亮（scroll spy）：页面滚到哪一节，就报告哪一节的 id。TableOfContents 用它高亮当前小节。
+*
+*   const current = useScrollSpy(() => ({ ids: headings.map((heading) => heading.id) }));
+*
+* 当前节 = 顶部已经越过阅读线的最后一个元素；阅读线是元素自己的 scroll-margin-top（标题让开粘性顶栏的距离，
+* 见 layoutVars.stickyOffset），所以点目录跳过去之后，高亮的正好是跳到的那一节。
+* 滚到底时最后几节可能永远到不了阅读线：这时高亮视口里的最后一个。
+*/
+/** 当前节的 id（在 setup 里调用）；还没滚到第一节时为 undefined */
+function useScrollSpy(read) {
+	const current = shallowRef();
+	if (typeof window === "undefined") return current;
+	function update() {
+		const { ids, root } = read();
+		const elements = ids.map((id) => document.getElementById(id)).filter((element) => element !== null);
+		const top = root ? root.getBoundingClientRect().top : 0;
+		const scroller = root ?? document.scrollingElement ?? document.documentElement;
+		const atBottom = scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 1;
+		const bottom = root ? root.getBoundingClientRect().bottom : window.innerHeight;
+		let next;
+		for (const element of elements) {
+			const offset = element.getBoundingClientRect().top - top;
+			if (offset <= (parseFloat(getComputedStyle(element).scrollMarginTop) || 0) + 1 || atBottom && offset < bottom - top) next = element.id;
+		}
+		current.value = next;
+	}
+	let frame = 0;
+	const schedule = () => {
+		cancelAnimationFrame(frame);
+		frame = requestAnimationFrame(update);
+	};
+	useEventListener(() => read().root ?? window, "scroll", schedule, { passive: true });
+	useEventListener(window, "resize", schedule);
+	onMounted(update);
+	watch(() => read().root, schedule);
+	watch(() => read().ids, schedule, { flush: "post" });
+	onScopeDispose(() => cancelAnimationFrame(frame));
+	return current;
+}
+/** 收集容器里带 id 的标题，生成目录（页面渲染后调用）；默认收集 h2、h3 */
+function collectHeadings(container, selector = "h2[id], h3[id]") {
+	return [...container.querySelectorAll(selector)].map((heading) => ({
+		id: heading.id,
+		label: heading.textContent?.trim() ?? "",
+		level: Number(heading.tagName.slice(1)) || 2
+	}));
+}
+//#endregion
+export { collectHeadings, useScrollSpy };
+
+//# sourceMappingURL=scroll-spy.js.map

package/dist/utils/dom/scroll-spy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-spy.js","names":[],"sources":["../../../src/utils/dom/scroll-spy.ts"],"sourcesContent":["/**\n * 滚动高亮（scroll spy）：页面滚到哪一节，就报告哪一节的 id。TableOfContents 用它高亮当前小节。\n *\n *   const current = useScrollSpy(() => ({ ids: headings.map((heading) => heading.id) }));\n *\n * 当前节 = 顶部已经越过阅读线的最后一个元素；阅读线是元素自己的 scroll-margin-top（标题让开粘性顶栏的距离，\n * 见 layoutVars.stickyOffset），所以点目录跳过去之后，高亮的正好是跳到的那一节。\n * 滚到底时最后几节可能永远到不了阅读线：这时高亮视口里的最后一个。\n */\nimport { onMounted, onScopeDispose, shallowRef, watch, type Ref } from 'vue';\nimport { useEventListener } from './event-listener';\n\n/** useScrollSpy 每次读取的选项 */\nexport interface ScrollSpyOptions {\n  /** 要追踪的元素的 id，按文档顺序 */\n  ids: readonly string[];\n  /** 滚动容器；不写时是页面（窗口） */\n  root?: HTMLElement | null;\n}\n\n/** 当前节的 id（在 setup 里调用）；还没滚到第一节时为 undefined */\nexport function useScrollSpy(read: () => ScrollSpyOptions): Readonly<Ref<string | undefined>> {\n  const current = shallowRef<string | undefined>();\n  if (typeof window === 'undefined') return current;\n\n  function update() {\n    const { ids, root } = read();\n    const elements = ids\n      .map((id) => document.getElementById(id))\n      .filter((element): element is HTMLElement => element !== null);\n    const top = root ? root.getBoundingClientRect().top : 0;\n    const scroller = root ?? document.scrollingElement ?? document.documentElement;\n    const atBottom = scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 1;\n    const bottom = root ? root.getBoundingClientRect().bottom : window.innerHeight;\n    let next: string | undefined;\n    for (const element of elements) {\n      const offset = element.getBoundingClientRect().top - top;\n      const line = parseFloat(getComputedStyle(element).scrollMarginTop) || 0;\n      // +1：跳转后元素正好停在阅读线上，取整误差不该让它算作还没到\n      if (offset <= line + 1 || (atBottom && offset < bottom - top)) next = element.id;\n    }\n    current.value = next;\n  }\n\n  // 一帧最多量一次\n  let frame = 0;\n  const schedule = () => {\n    cancelAnimationFrame(frame);\n    frame = requestAnimationFrame(update);\n  };\n  // 滚动容器常常在挂载后才拿到（ref 回调）：换了容器就换绑，并按新容器重新算，不能留着按窗口算的结果\n  useEventListener(() => read().root ?? window, 'scroll', schedule, { passive: true });\n  useEventListener(window, 'resize', schedule);\n  onMounted(update);\n  watch(() => read().root, schedule);\n  watch(() => read().ids, schedule, { flush: 'post' });\n  onScopeDispose(() => cancelAnimationFrame(frame));\n  return current;\n}\n\n/** 目录里的一项 */\nexport interface HeadingEntry {\n  /** 标题的 id（锚点） */\n  id: string;\n  /** 标题文字 */\n  label: string;\n  /** 标题级别：2 是 h2，3 是 h3… */\n  level: number;\n}\n\n/** 收集容器里带 id 的标题，生成目录（页面渲染后调用）；默认收集 h2、h3 */\nexport function collectHeadings(\n  container: ParentNode,\n  selector = 'h2[id], h3[id]',\n): HeadingEntry[] {\n  return [...container.querySelectorAll<HTMLElement>(selector)].map((heading) => ({\n    id: heading.id,\n    label: heading.textContent?.trim() ?? '',\n    level: Number(heading.tagName.slice(1)) || 2,\n  }));\n}\n"],"mappings":";;;;;;;;;;;;;AAqBA,SAAgB,aAAa,MAAiE;CAC5F,MAAM,UAAU,WAA+B;CAC/C,IAAI,OAAO,WAAW,aAAa,OAAO;CAE1C,SAAS,SAAS;EAChB,MAAM,EAAE,KAAK,SAAS,KAAK;EAC3B,MAAM,WAAW,IACd,KAAK,OAAO,SAAS,eAAe,EAAE,CAAC,CAAC,CACxC,QAAQ,YAAoC,YAAY,IAAI;EAC/D,MAAM,MAAM,OAAO,KAAK,sBAAsB,CAAC,CAAC,MAAM;EACtD,MAAM,WAAW,QAAQ,SAAS,oBAAoB,SAAS;EAC/D,MAAM,WAAW,SAAS,YAAY,SAAS,gBAAgB,SAAS,eAAe;EACvF,MAAM,SAAS,OAAO,KAAK,sBAAsB,CAAC,CAAC,SAAS,OAAO;EACnE,IAAI;EACJ,KAAK,MAAM,WAAW,UAAU;GAC9B,MAAM,SAAS,QAAQ,sBAAsB,CAAC,CAAC,MAAM;GAGrD,IAAI,WAFS,WAAW,iBAAiB,OAAO,CAAC,CAAC,eAAe,KAAK,KAEjD,KAAM,YAAY,SAAS,SAAS,KAAM,OAAO,QAAQ;EAChF;EACA,QAAQ,QAAQ;CAClB;CAGA,IAAI,QAAQ;CACZ,MAAM,iBAAiB;EACrB,qBAAqB,KAAK;EAC1B,QAAQ,sBAAsB,MAAM;CACtC;CAEA,uBAAuB,KAAK,CAAC,CAAC,QAAQ,QAAQ,UAAU,UAAU,EAAE,SAAS,KAAK,CAAC;CACnF,iBAAiB,QAAQ,UAAU,QAAQ;CAC3C,UAAU,MAAM;CAChB,YAAY,KAAK,CAAC,CAAC,MAAM,QAAQ;CACjC,YAAY,KAAK,CAAC,CAAC,KAAK,UAAU,EAAE,OAAO,OAAO,CAAC;CACnD,qBAAqB,qBAAqB,KAAK,CAAC;CAChD,OAAO;AACT;;AAaA,SAAgB,gBACd,WACA,WAAW,kBACK;CAChB,OAAO,CAAC,GAAG,UAAU,iBAA8B,QAAQ,CAAC,CAAC,CAAC,KAAK,aAAa;EAC9E,IAAI,QAAQ;EACZ,OAAO,QAAQ,aAAa,KAAK,KAAK;EACtC,OAAO,OAAO,QAAQ,QAAQ,MAAM,CAAC,CAAC,KAAK;CAC7C,EAAE;AACJ"}

package/dist/utils/dom/sortable.d.ts

@@ -0,0 +1,82 @@
+/** 排列方向：决定按哪个轴拖动、方向键用上下还是左右 */
+export interface SortableOrientations {
+    /** 竖排（默认） */
+    vertical: unknown;
+    /** 横排 */
+    horizontal: unknown;
+}
+/** 分组（多容器）：项分在几个组里，组内排序，也能拖到别的组 */
+export interface SortableGroups<T> {
+    /** 各组的 key，按排列顺序（键盘 ← / → 按这个顺序换组） */
+    keys: () => readonly string[];
+    /** 项在哪一组 */
+    of: (item: T) => string;
+    /** 组的名称：读屏播报用它；默认是 key */
+    label?: (group: string) => string;
+    /** 能不能放进 to 组：返回不能的原因，null、undefined 是可以 */
+    canMove?: (item: T, to: string) => string | null | undefined;
+    /** 放到了别的组：index 是在目标组里的位置。使用方改数据（或先处理、刷新），项才换组 */
+    onMove: (item: T, to: string, index: number) => void;
+    /** 放到了不能放的组：项已回到原处，可以在这里提示原因 */
+    onReject?: (item: T, to: string, reason: string) => void;
+}
+/** useSortable 的选项 */
+export interface SortableOptions<T> {
+    /** 当前的各项（分组时是所有组的项） */
+    items: () => readonly T[];
+    /** 项的 key，同一列表里唯一 */
+    getKey: (item: T) => string;
+    /** 项的名称：读屏播报与把手的名称用它；默认是 key */
+    getLabel?: (item: T) => string;
+    /** 组内顺序变了：写回新的数组。分组时可以不给，组内就不能排序 */
+    onChange?: (items: T[]) => void;
+    /** 各项所在的容器（元素或组件实例）：布局动画、自动滚动在它里面进行；分组时是包住所有组的元素 */
+    container: () => unknown;
+    /** 排列方向，默认 vertical；分组时指组内的方向 */
+    orientation?: () => keyof SortableOrientations;
+    /** 分组（多容器）；组的元素上展开 groupProps(组) */
+    groups?: SortableGroups<T>;
+    /** 不可用 */
+    disabled?: () => boolean;
+}
+/** 拖动中的落点 */
+export interface SortableTarget {
+    /** 落在哪一组（不分组时是空字符串） */
+    group: string;
+    /** 在组里的位置，从 0 开始 */
+    index: number;
+    /** 不能放进这一组的原因；可以放时为 null */
+    reason: string | null;
+}
+/** 分组时指针拖动的影子：跟着指针走，位置是视口坐标 */
+export interface SortableGhost {
+    /** 被拖的项的 key */
+    key: string;
+    /** 左边缘 */
+    left: number;
+    /** 上边缘 */
+    top: number;
+    /** 宽度（按下时项的宽度） */
+    width: number;
+}
+/** useSortable 的返回值 */
+export interface SortableState {
+    /** 正在拖动或被键盘拿起的项的 key */
+    readonly active: string | undefined;
+    /** 拖动中的落点：分组时组件按它高亮目标组、画插入线 */
+    readonly target: SortableTarget | undefined;
+    /** 分组时指针拖动的影子；单列、键盘操作时没有 */
+    readonly ghost: SortableGhost | undefined;
+    /** 读屏播报的文字：放进 aria-live 区域 */
+    readonly announcement: string;
+    /** 操作说明元素的 id：把手经 aria-describedby 指向它 */
+    readonly instructionsId: string;
+    /** 把手的属性：展开到把手元素（button）上 */
+    handleProps(key: string): Record<string, unknown>;
+    /** 项的属性：展开到项的根元素上 */
+    itemProps(key: string): Record<string, unknown>;
+    /** 组的属性：分组时展开到每一组的元素上（指针按它判断在哪一组） */
+    groupProps(group: string): Record<string, unknown>;
+}
+/** 拖动排序的状态与事件（在 setup 里调用） */
+export declare function useSortable<T>(options: SortableOptions<T>): SortableState;