@qw-ui/core 0.3.0-next.40 → 0.3.0-next.42

package/README.md

@@ -1,59 +1,43 @@
 # @qw-ui/core
 
-> L2 · Headless Core — zag.js machine 薄包装，纯 TS / SSR-safe，零样式。
-
-**层级 L2 · 行为唯一事实源**。所有组件的交互逻辑、状态机、ARIA 语义、键盘与 focus 行为都只写在这里；React/Vue 适配层零业务逻辑。纯 TypeScript，无样式、SSR 安全。
+跨框架无样式行为层。Framework-neutral headless contracts for qw-ui.
 
 ## 安装
 
+当前开发版本使用 `next`：
+
 ```bash
-pnpm add @qw-ui/core
+npm install @qw-ui/core@next
 ```
 
-无框架 peer 依赖（内部封装 `@zag-js/*`）。通常你不直接装它——`@qw-ui/react` / `@qw-ui/vue` 已把它作为依赖带上；只有自建适配层或直接消费状态机时才单独装。
+包发布于 [公共 npm](https://www.npmjs.com/package/@qw-ui/core)。如环境配置了其他镜像，可在安装命令后追加 `--registry=https://registry.npmjs.org/`。
 
 ## 最小示例
 
-按子路径导入某组件的 machine / 契约类型（每个组件一个 export 入口）：
-
 ```ts
-import * as button from "@qw-ui/core/button";
-import type { QwDialogProps, QwDialogApi } from "@qw-ui/core/dialog";
-import { resolveIconName } from "@qw-ui/core/icon";
-```
-
-子路径与组件 slug 一一对应：`dialog / tabs / toast / button / empty / divider / loading / skeleton / top-bar / icon / search-bar / avatar / image / textarea / tag / input`。
+import { resolveButtonState, BUTTON_VARIANTS } from '@qw-ui/core/button';
 
-## 目录契约
-
-每个组件在 `src/<slug>/` 下必须齐备（G1 `verify:demos` 强制）：
-
-```
-index.ts + __test__/ + docs/{overview.md, accessibility.md, demos.ts, visual.ts}
+const state = resolveButtonState({ loading: true });
+console.log(state.effectiveDisabled); // true
+console.log(BUTTON_VARIANTS); // solid / soft / outline / ghost / link
 ```
 
-`docs/` 是文档站与双栈 demo 的唯一清单来源；行为改一处（core），双栈同步生效。
+## 使用说明
 
-## 关联包
+适合实现自定义框架适配层或直接使用共享行为契约。此包不提供组件 CSS，也不直接渲染 UI。常规应用优先使用 React、Vue 或 WC 包；状态机 API 以对应组件子路径的类型声明为准。
 
-| 包 | 关系 |
-|---|---|
-| [@qw-ui/react](../react/README.md) | 基于本包 machine 的 React 适配 |
-| [@qw-ui/vue](../vue/README.md) | 基于本包 machine 的 Vue 适配 |
-| [@qw-ui/tokens](../tokens/README.md) | 组件视觉所依赖的 T3 token（本包自身零样式） |
-| [@qw-ui/icons](../icons/README.md) | `icon` 子路径的图标名解析依赖 |
+## 兼容性
 
-## 版本通道
+ESM / TypeScript，支持无 DOM 的服务端导入。交互组件的运行环境基线为 Chrome 123 / iOS Safari 16.4。
 
-| 通道 | 安装 | 说明 |
-|---|---|---|
-| `latest`（稳定） | `pnpm add @qw-ui/core` | `main` 通道，Release PR review 后发布 |
-| `next`（预发布） | `pnpm add @qw-ui/core@next` | `release/next` 通道，高频自增 `x.y.z-next.N` |
+## 版本通道
 
-9 个公开包 `fixed` 锁步同版本号。npm 发布固定走 `registry.npmjs.org`；内网装依赖走 `registry.anpm.alibaba-inc.com`（tnpm 代理），发布 registry 不要指向内网。流程详见 [development-workflow.md](../../docs/development-workflow.md)。
+- `next`：main 更新并通过检查后自动发布，用于试用当前能力。
+- `latest`：负责人手动发布的正式版本。正式版可用后，使用 `npm install @qw-ui/core@latest`；正式版支持范围以该版本 README 为准。
+- 生产项目建议锁定明确版本。配套使用的 `@qw-ui/*` 包应选择同批版本；内部运行时依赖由包管理器安装。
 
-## 仓库 & License
+## 文档与许可证
 
-- 主仓库：<http://gitlab.alibaba-inc.com/qianwen/qw-ui>
-- 问题反馈：<http://gitlab.alibaba-inc.com/qianwen/qw-ui/issues>
-- License：MIT
+- [组件文档与接入指南](https://qw-ui.qianwen.com/)
+- [npm 版本列表](https://www.npmjs.com/package/@qw-ui/core?activeTab=versions)
+- MIT，详见包内 `LICENSE`。

package/dist/action-sheet/action-sheet.d.ts

@@ -0,0 +1,110 @@
+import type { machine, Props as ZagDialogProps, Service } from "@zag-js/dialog";
+import type { ModalRenderRuntime } from "../modal-render-runtime.js";
+import { connectPopup, type QwPopupProps } from "../popup/popup.js";
+/**
+ * ActionSheet 的 Core machine。物理层就是 Popup 的同一 machine（modalDialogMachine 惰性 scope lookup、
+ * 单层模态与 Zag effects 全部继承）；动作数据经 machine props 传入，处理器只读最新 service.prop。
+ */
+export declare const actionSheetMachine: typeof machine;
+/** 单个纵向文字动作。value 是精确通知值，label/description 不作身份。 */
+export interface QwActionSheetAction {
+    value: string;
+    label: string;
+    /** 可见说明，trim 后为空视为缺省。 */
+    description?: string;
+    /** 危险动作：可见危险说明 + data-danger；没有第二次确认。 */
+    danger?: boolean;
+    /** 危险说明，优先于 description；都缺省时为「危险操作」。 */
+    dangerDescription?: string;
+    /** 原生 disabled：不可聚焦、不通知、不关闭。 */
+    disabled?: boolean;
+    /** 为 true 时通知动作但不请求关闭。默认 false。 */
+    keepOpen?: boolean;
+}
+/** ActionSheet 输入。固定底部，不接受 placement。 */
+export interface QwActionSheetProps extends Omit<QwPopupProps, "placement"> {
+    /** 纵向动作，缺省 []。 */
+    actions?: readonly QwActionSheetAction[];
+    /** 是否显示取消按钮，默认 true。 */
+    showCancel?: boolean;
+    /** 取消按钮文字，默认「取消」。 */
+    cancelText?: string;
+    /** 每次启用动作被激活时通知一次。 */
+    onAction?: (value: string) => void;
+}
+/** Core 派生的动作数据。适配层只渲染，不判断 disabled/duplicate/keepOpen。 */
+export interface QwResolvedActionSheetAction {
+    readonly source: QwActionSheetAction;
+    readonly sourceIndex: number;
+    readonly value: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly dangerDescription?: string;
+    readonly danger: boolean;
+    readonly duplicate: boolean;
+    readonly disabled: boolean;
+    readonly keepOpen: boolean;
+    /** 去重后的可见说明条目（普通说明、危险说明）。 */
+    readonly accessibleDescription: readonly string[];
+    /** 渲染用说明文本；无说明时 undefined。 */
+    readonly descriptionText?: string;
+}
+/** createActionSheetProps 的输出：Zag dialog context + 动作数据（只供 Core 处理器读取）。 */
+export type QwActionSheetMachineProps = Partial<ZagDialogProps> & {
+    actions?: readonly QwActionSheetAction[];
+    onAction?: (value: string) => void;
+};
+type ActionSheetNormalize = Parameters<typeof connectPopup>[1];
+type NormalizedProps = ReturnType<ActionSheetNormalize["element"]>;
+export type QwActionSheetApi = ReturnType<typeof connectPopup> & {
+    readonly actions: readonly QwResolvedActionSheetAction[];
+    readonly showCancel: boolean;
+    readonly cancelText: string;
+    getListProps(): NormalizedProps;
+    getItemProps(details: {
+        index: number;
+    }): NormalizedProps;
+    getActionProps(details: {
+        index: number;
+    }): NormalizedProps;
+    getActionLabelProps(details: {
+        index: number;
+    }): NormalizedProps;
+    getActionDescriptionProps(details: {
+        index: number;
+    }): NormalizedProps;
+    getCancelProps(): NormalizedProps;
+};
+/** 可访问名称：title → ariaLabel → 「动作面板」。空白视为缺省。 */
+export declare function getActionSheetAccessibleName(props: Pick<QwActionSheetProps, "title" | "ariaLabel">): string;
+/**
+ * 归一化动作：按输入顺序保留全部可见项；重复 value 只第一项可能启用，第一项 disabled 不晋升后项。
+ * 危险说明 dangerDescription → description → 「危险操作」，与普通说明相同则只出现一次。
+ */
+export declare function resolveActionSheetActions(actions?: readonly QwActionSheetAction[]): readonly QwResolvedActionSheetAction[];
+export type QwActionSheetActivation = {
+    readonly kind: "blocked";
+} | {
+    readonly kind: "action";
+    readonly value: string;
+    readonly requestClose: boolean;
+};
+/**
+ * 以最新列表复核一次渲染时的动作：源对象 identity + sourceIndex + value 都一致且仍启用才放行。
+ * 已删除、被同值新对象替换、被禁用或变成重复后项的旧处理器一律 blocked。
+ */
+export declare function resolveActionSheetActivation(latestActions: readonly QwActionSheetAction[] | undefined, rendered: Pick<QwResolvedActionSheetAction, "source" | "sourceIndex" | "value">): QwActionSheetActivation;
+/** Popup 的 data 属性（placement 固定 bottom）。 */
+export declare function getActionSheetDataAttrs(props: Pick<QwActionSheetProps, "safeArea">): Record<string, string | undefined>;
+/**
+ * 公开 props → 同一 Popup machine 的 context。机械委托 createPopupProps(props, runtime)：
+ * 受控优先、初态许可/拒绝仍由 Popup Core 决定；actions/onAction 只作为最新数据随 service.prop 传递。
+ */
+export declare function createActionSheetProps(props?: QwActionSheetProps, runtime?: ModalRenderRuntime): QwActionSheetMachineProps;
+/**
+ * 包装 connectPopup：继承开合/getters 与单层模态拒绝，增加动作 list/item/label/description/cancel getters。
+ * 动作激活：读最新 service.prop("actions") 复核 → onAction(value) → 非 keepOpen 时同一 api.setOpen(false)。
+ * 取消只请求关闭，零动作通知。
+ */
+export declare function connectActionSheet(service: Service, normalize: ActionSheetNormalize, props?: QwActionSheetProps, runtime?: ModalRenderRuntime): QwActionSheetApi;
+export {};

package/dist/action-sheet/index.d.ts

@@ -0,0 +1,2 @@
+export { actionSheetMachine, createActionSheetProps, connectActionSheet, resolveActionSheetActions, resolveActionSheetActivation, getActionSheetAccessibleName, getActionSheetDataAttrs, } from "./action-sheet.js";
+export type { QwActionSheetAction, QwActionSheetProps, QwActionSheetApi, QwActionSheetMachineProps, QwActionSheetActivation, QwResolvedActionSheetAction, } from "./action-sheet.js";

package/dist/action-sheet/index.js

@@ -0,0 +1,2 @@
+import { a as getActionSheetDataAttrs, i as getActionSheetAccessibleName, n as connectActionSheet, o as resolveActionSheetActions, r as createActionSheetProps, s as resolveActionSheetActivation, t as actionSheetMachine } from "../action-sheet-Cvcr1S_m.js";
+export { actionSheetMachine, connectActionSheet, createActionSheetProps, getActionSheetAccessibleName, getActionSheetDataAttrs, resolveActionSheetActions, resolveActionSheetActivation };

package/dist/action-sheet-Cvcr1S_m.js

@@ -0,0 +1,183 @@
+import { n as createPopupProps, o as popupMachine, t as connectPopup } from "./popup-z5d8IYCt.js";
+//#region src/action-sheet/action-sheet.ts
+/**
+* ActionSheet 的 Core machine。物理层就是 Popup 的同一 machine（modalDialogMachine 惰性 scope lookup、
+* 单层模态与 Zag effects 全部继承）；动作数据经 machine props 传入，处理器只读最新 service.prop。
+*/
+const actionSheetMachine = popupMachine;
+const FALLBACK_NAME = "动作面板";
+const DANGER_FALLBACK = "危险操作";
+const CANCEL_TEXT = "取消";
+const text = (value) => {
+	const normalized = value?.trim();
+	return normalized ? normalized : void 0;
+};
+/** 可访问名称：title → ariaLabel → 「动作面板」。空白视为缺省。 */
+function getActionSheetAccessibleName(props) {
+	return text(props.title) ?? text(props.ariaLabel) ?? FALLBACK_NAME;
+}
+/**
+* 归一化动作：按输入顺序保留全部可见项；重复 value 只第一项可能启用，第一项 disabled 不晋升后项。
+* 危险说明 dangerDescription → description → 「危险操作」，与普通说明相同则只出现一次。
+*/
+function resolveActionSheetActions(actions = []) {
+	const seen = /* @__PURE__ */ new Set();
+	return actions.map((source, sourceIndex) => {
+		const duplicate = seen.has(source.value);
+		seen.add(source.value);
+		const description = text(source.description);
+		const danger = source.danger === true;
+		const dangerDescription = danger ? text(source.dangerDescription) ?? description ?? DANGER_FALLBACK : void 0;
+		const accessibleDescription = [description, dangerDescription].filter((entry) => entry !== void 0).filter((entry, index, entries) => entries.indexOf(entry) === index);
+		return {
+			source,
+			sourceIndex,
+			value: source.value,
+			label: source.label,
+			description,
+			dangerDescription,
+			danger,
+			duplicate,
+			disabled: source.disabled === true || duplicate,
+			keepOpen: source.keepOpen === true,
+			accessibleDescription,
+			descriptionText: accessibleDescription.length > 0 ? accessibleDescription.join(" ") : void 0
+		};
+	});
+}
+/**
+* 以最新列表复核一次渲染时的动作：源对象 identity + sourceIndex + value 都一致且仍启用才放行。
+* 已删除、被同值新对象替换、被禁用或变成重复后项的旧处理器一律 blocked。
+*/
+function resolveActionSheetActivation(latestActions, rendered) {
+	const latest = resolveActionSheetActions(latestActions)[rendered.sourceIndex];
+	if (!latest || latest.source !== rendered.source || latest.value !== rendered.value || latest.disabled) return { kind: "blocked" };
+	return {
+		kind: "action",
+		value: latest.value,
+		requestClose: !latest.keepOpen
+	};
+}
+function toPopupProps(props) {
+	const { actions: _actions, showCancel: _showCancel, cancelText: _cancelText, onAction: _onAction, ...rest } = props;
+	const popup = {
+		...rest,
+		placement: "bottom"
+	};
+	if (!text(props.title)) popup.ariaLabel = getActionSheetAccessibleName(props);
+	return popup;
+}
+/** Popup 的 data 属性（placement 固定 bottom）。 */
+function getActionSheetDataAttrs(props) {
+	return {
+		"data-placement": "bottom",
+		"data-safe-area": props.safeArea === false ? void 0 : ""
+	};
+}
+/**
+* 公开 props → 同一 Popup machine 的 context。机械委托 createPopupProps(props, runtime)：
+* 受控优先、初态许可/拒绝仍由 Popup Core 决定；actions/onAction 只作为最新数据随 service.prop 传递。
+*/
+function createActionSheetProps(props = {}, runtime) {
+	return {
+		...createPopupProps(toPopupProps(props), runtime),
+		actions: props.actions ?? [],
+		onAction: props.onAction
+	};
+}
+function stableId(service) {
+	return `action-sheet:${service.scope.id ?? ""}`;
+}
+/**
+* 包装 connectPopup：继承开合/getters 与单层模态拒绝，增加动作 list/item/label/description/cancel getters。
+* 动作激活：读最新 service.prop("actions") 复核 → onAction(value) → 非 keepOpen 时同一 api.setOpen(false)。
+* 取消只请求关闭，零动作通知。
+*/
+function connectActionSheet(service, normalize, props = {}, runtime) {
+	const popup = connectPopup(service, normalize, toPopupProps(props), runtime);
+	const actions = resolveActionSheetActions(props.actions);
+	const base = stableId(service);
+	const isOpen = () => service.state.matches("open");
+	const readProp = (key) => service.prop(key);
+	const labelId = (index) => `${base}:action:${index}:label`;
+	const descriptionId = (index) => `${base}:action:${index}:description`;
+	const showCancel = props.showCancel !== false;
+	const cancelText = text(props.cancelText) ?? CANCEL_TEXT;
+	const activate = (rendered) => (event) => {
+		if (!isOpen()) return;
+		const result = resolveActionSheetActivation(readProp("actions") ?? props.actions, rendered);
+		if (result.kind === "blocked") {
+			event?.preventDefault?.();
+			return;
+		}
+		(readProp("onAction") ?? props.onAction)?.(result.value);
+		if (result.requestClose) popup.setOpen(false);
+	};
+	return {
+		...popup,
+		actions,
+		showCancel,
+		cancelText,
+		getListProps: () => normalize.element({
+			"data-scope": "action-sheet",
+			"data-part": "list",
+			"data-visual-target": "action-sheet-list",
+			"data-empty": actions.length === 0 ? "" : void 0
+		}),
+		getItemProps: () => normalize.element({
+			"data-scope": "action-sheet",
+			"data-part": "entry"
+		}),
+		getActionProps({ index }) {
+			const action = actions[index];
+			if (!action) return normalize.element({
+				"data-scope": "action-sheet",
+				"data-part": "item",
+				type: "button",
+				disabled: true
+			});
+			const labelledBy = action.danger && !action.description && action.descriptionText ? `${labelId(index)} ${descriptionId(index)}` : labelId(index);
+			return normalize.element({
+				"data-scope": "action-sheet",
+				"data-part": "item",
+				"data-visual-target": action.danger ? "action-sheet-danger" : "action-sheet-item",
+				id: `${base}:action:${index}`,
+				type: "button",
+				disabled: action.disabled,
+				"aria-labelledby": labelledBy,
+				"aria-describedby": action.descriptionText ? descriptionId(index) : void 0,
+				"data-value": action.value,
+				"data-danger": action.danger ? "" : void 0,
+				"data-disabled": action.disabled ? "" : void 0,
+				"data-duplicate": action.duplicate ? "" : void 0,
+				"data-keep-open": action.keepOpen ? "" : void 0,
+				onClick: activate(action)
+			});
+		},
+		getActionLabelProps: ({ index }) => normalize.element({
+			"data-scope": "action-sheet",
+			"data-part": "label",
+			id: labelId(index),
+			"data-danger": actions[index]?.danger ? "" : void 0
+		}),
+		getActionDescriptionProps: ({ index }) => normalize.element({
+			"data-scope": "action-sheet",
+			"data-part": "description",
+			"data-visual-target": "action-sheet-description",
+			id: descriptionId(index),
+			"data-danger": actions[index]?.danger ? "" : void 0
+		}),
+		getCancelProps: () => normalize.element({
+			"data-scope": "action-sheet",
+			"data-part": "cancel",
+			"data-visual-target": "action-sheet-cancel",
+			id: `${base}:cancel`,
+			type: "button",
+			onClick: () => popup.setOpen(false)
+		})
+	};
+}
+//#endregion
+export { getActionSheetDataAttrs as a, getActionSheetAccessibleName as i, connectActionSheet as n, resolveActionSheetActions as o, createActionSheetProps as r, resolveActionSheetActivation as s, actionSheetMachine as t };
+
+//# sourceMappingURL=action-sheet-Cvcr1S_m.js.map

package/dist/action-sheet-Cvcr1S_m.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-sheet-Cvcr1S_m.js","names":[],"sources":["../src/action-sheet/action-sheet.ts"],"sourcesContent":["import type { machine, Props as ZagDialogProps, Service } from \"@zag-js/dialog\";\nimport type { ModalRenderRuntime } from \"../modal-render-runtime.js\";\nimport {\n  connectPopup,\n  createPopupProps,\n  popupMachine,\n  type QwPopupProps,\n} from \"../popup/popup.js\";\n\n/**\n * ActionSheet 的 Core machine。物理层就是 Popup 的同一 machine（modalDialogMachine 惰性 scope lookup、\n * 单层模态与 Zag effects 全部继承）；动作数据经 machine props 传入，处理器只读最新 service.prop。\n */\nexport const actionSheetMachine: typeof machine = popupMachine;\n\n/** 单个纵向文字动作。value 是精确通知值，label/description 不作身份。 */\nexport interface QwActionSheetAction {\n  value: string;\n  label: string;\n  /** 可见说明，trim 后为空视为缺省。 */\n  description?: string;\n  /** 危险动作：可见危险说明 + data-danger；没有第二次确认。 */\n  danger?: boolean;\n  /** 危险说明，优先于 description；都缺省时为「危险操作」。 */\n  dangerDescription?: string;\n  /** 原生 disabled：不可聚焦、不通知、不关闭。 */\n  disabled?: boolean;\n  /** 为 true 时通知动作但不请求关闭。默认 false。 */\n  keepOpen?: boolean;\n}\n\n/** ActionSheet 输入。固定底部，不接受 placement。 */\nexport interface QwActionSheetProps extends Omit<QwPopupProps, \"placement\"> {\n  /** 纵向动作，缺省 []。 */\n  actions?: readonly QwActionSheetAction[];\n  /** 是否显示取消按钮，默认 true。 */\n  showCancel?: boolean;\n  /** 取消按钮文字，默认「取消」。 */\n  cancelText?: string;\n  /** 每次启用动作被激活时通知一次。 */\n  onAction?: (value: string) => void;\n}\n\n/** Core 派生的动作数据。适配层只渲染，不判断 disabled/duplicate/keepOpen。 */\nexport interface QwResolvedActionSheetAction {\n  readonly source: QwActionSheetAction;\n  readonly sourceIndex: number;\n  readonly value: string;\n  readonly label: string;\n  readonly description?: string;\n  readonly dangerDescription?: string;\n  readonly danger: boolean;\n  readonly duplicate: boolean;\n  readonly disabled: boolean;\n  readonly keepOpen: boolean;\n  /** 去重后的可见说明条目（普通说明、危险说明）。 */\n  readonly accessibleDescription: readonly string[];\n  /** 渲染用说明文本；无说明时 undefined。 */\n  readonly descriptionText?: string;\n}\n\n/** createActionSheetProps 的输出：Zag dialog context + 动作数据（只供 Core 处理器读取）。 */\nexport type QwActionSheetMachineProps = Partial<ZagDialogProps> & {\n  actions?: readonly QwActionSheetAction[];\n  onAction?: (value: string) => void;\n};\n\ntype ActionSheetNormalize = Parameters<typeof connectPopup>[1];\ntype NormalizedProps = ReturnType<ActionSheetNormalize[\"element\"]>;\n\nexport type QwActionSheetApi = ReturnType<typeof connectPopup> & {\n  readonly actions: readonly QwResolvedActionSheetAction[];\n  readonly showCancel: boolean;\n  readonly cancelText: string;\n  getListProps(): NormalizedProps;\n  getItemProps(details: { index: number }): NormalizedProps;\n  getActionProps(details: { index: number }): NormalizedProps;\n  getActionLabelProps(details: { index: number }): NormalizedProps;\n  getActionDescriptionProps(details: { index: number }): NormalizedProps;\n  getCancelProps(): NormalizedProps;\n};\n\nconst FALLBACK_NAME = \"动作面板\";\nconst DANGER_FALLBACK = \"危险操作\";\nconst CANCEL_TEXT = \"取消\";\n\nconst text = (value: string | undefined): string | undefined => {\n  const normalized = value?.trim();\n  return normalized ? normalized : undefined;\n};\n\n/** 可访问名称：title → ariaLabel → 「动作面板」。空白视为缺省。 */\nexport function getActionSheetAccessibleName(props: Pick<QwActionSheetProps, \"title\" | \"ariaLabel\">): string {\n  return text(props.title) ?? text(props.ariaLabel) ?? FALLBACK_NAME;\n}\n\n/**\n * 归一化动作：按输入顺序保留全部可见项；重复 value 只第一项可能启用，第一项 disabled 不晋升后项。\n * 危险说明 dangerDescription → description → 「危险操作」，与普通说明相同则只出现一次。\n */\nexport function resolveActionSheetActions(\n  actions: readonly QwActionSheetAction[] = [],\n): readonly QwResolvedActionSheetAction[] {\n  const seen = new Set<string>();\n  return actions.map((source, sourceIndex) => {\n    const duplicate = seen.has(source.value);\n    seen.add(source.value);\n    const description = text(source.description);\n    const danger = source.danger === true;\n    const dangerDescription = danger ? text(source.dangerDescription) ?? description ?? DANGER_FALLBACK : undefined;\n    const accessibleDescription = [description, dangerDescription]\n      .filter((entry): entry is string => entry !== undefined)\n      .filter((entry, index, entries) => entries.indexOf(entry) === index);\n    return {\n      source,\n      sourceIndex,\n      value: source.value,\n      label: source.label,\n      description,\n      dangerDescription,\n      danger,\n      duplicate,\n      disabled: source.disabled === true || duplicate,\n      keepOpen: source.keepOpen === true,\n      accessibleDescription,\n      descriptionText: accessibleDescription.length > 0 ? accessibleDescription.join(\" \") : undefined,\n    };\n  });\n}\n\nexport type QwActionSheetActivation =\n  | { readonly kind: \"blocked\" }\n  | { readonly kind: \"action\"; readonly value: string; readonly requestClose: boolean };\n\n/**\n * 以最新列表复核一次渲染时的动作：源对象 identity + sourceIndex + value 都一致且仍启用才放行。\n * 已删除、被同值新对象替换、被禁用或变成重复后项的旧处理器一律 blocked。\n */\nexport function resolveActionSheetActivation(\n  latestActions: readonly QwActionSheetAction[] | undefined,\n  rendered: Pick<QwResolvedActionSheetAction, \"source\" | \"sourceIndex\" | \"value\">,\n): QwActionSheetActivation {\n  const latest = resolveActionSheetActions(latestActions)[rendered.sourceIndex];\n  if (!latest || latest.source !== rendered.source || latest.value !== rendered.value || latest.disabled) return { kind: \"blocked\" };\n  return { kind: \"action\", value: latest.value, requestClose: !latest.keepOpen };\n}\n\nfunction toPopupProps(props: QwActionSheetProps): QwPopupProps {\n  const { actions: _actions, showCancel: _showCancel, cancelText: _cancelText, onAction: _onAction, ...rest } = props;\n  void _actions; void _showCancel; void _cancelText; void _onAction;\n  const popup: QwPopupProps = { ...rest, placement: \"bottom\" };\n  // 有标题时 Zag 写 aria-labelledby；无标题时名称回退「动作面板」而非 Popup 的「弹出层」。\n  if (!text(props.title)) popup.ariaLabel = getActionSheetAccessibleName(props);\n  return popup;\n}\n\n/** Popup 的 data 属性（placement 固定 bottom）。 */\nexport function getActionSheetDataAttrs(props: Pick<QwActionSheetProps, \"safeArea\">): Record<string, string | undefined> {\n  return { \"data-placement\": \"bottom\", \"data-safe-area\": props.safeArea === false ? undefined : \"\" };\n}\n\n/**\n * 公开 props → 同一 Popup machine 的 context。机械委托 createPopupProps(props, runtime)：\n * 受控优先、初态许可/拒绝仍由 Popup Core 决定；actions/onAction 只作为最新数据随 service.prop 传递。\n */\nexport function createActionSheetProps(props: QwActionSheetProps = {}, runtime?: ModalRenderRuntime): QwActionSheetMachineProps {\n  return { ...createPopupProps(toPopupProps(props), runtime), actions: props.actions ?? [], onAction: props.onAction };\n}\n\nfunction stableId(service: Service): string {\n  return `action-sheet:${service.scope.id ?? \"\"}`;\n}\n\n/**\n * 包装 connectPopup：继承开合/getters 与单层模态拒绝，增加动作 list/item/label/description/cancel getters。\n * 动作激活：读最新 service.prop(\"actions\") 复核 → onAction(value) → 非 keepOpen 时同一 api.setOpen(false)。\n * 取消只请求关闭，零动作通知。\n */\nexport function connectActionSheet(\n  service: Service,\n  normalize: ActionSheetNormalize,\n  props: QwActionSheetProps = {},\n  runtime?: ModalRenderRuntime,\n): QwActionSheetApi {\n  const popup = connectPopup(service, normalize, toPopupProps(props), runtime);\n  const actions = resolveActionSheetActions(props.actions);\n  const base = stableId(service);\n  const isOpen = () => service.state.matches(\"open\");\n  const readProp = <K extends \"actions\" | \"onAction\">(key: K): QwActionSheetMachineProps[K] =>\n    (service.prop as unknown as (name: K) => QwActionSheetMachineProps[K])(key);\n  const labelId = (index: number) => `${base}:action:${index}:label`;\n  const descriptionId = (index: number) => `${base}:action:${index}:description`;\n  const showCancel = props.showCancel !== false;\n  const cancelText = text(props.cancelText) ?? CANCEL_TEXT;\n\n  const activate = (rendered: QwResolvedActionSheetAction) => (event?: { preventDefault?(): void }) => {\n    if (!isOpen()) return;\n    const result = resolveActionSheetActivation(readProp(\"actions\") ?? props.actions, rendered);\n    if (result.kind === \"blocked\") {\n      event?.preventDefault?.();\n      return;\n    }\n    (readProp(\"onAction\") ?? props.onAction)?.(result.value);\n    if (result.requestClose) popup.setOpen(false);\n  };\n\n  return {\n    ...popup,\n    actions,\n    showCancel,\n    cancelText,\n    getListProps: () => normalize.element({\n      \"data-scope\": \"action-sheet\",\n      \"data-part\": \"list\",\n      \"data-visual-target\": \"action-sheet-list\",\n      \"data-empty\": actions.length === 0 ? \"\" : undefined,\n    }),\n    getItemProps: () => normalize.element({ \"data-scope\": \"action-sheet\", \"data-part\": \"entry\" }),\n    getActionProps({ index }) {\n      const action = actions[index];\n      if (!action) return normalize.element({ \"data-scope\": \"action-sheet\", \"data-part\": \"item\", type: \"button\", disabled: true });\n      const labelledBy = action.danger && !action.description && action.descriptionText\n        ? `${labelId(index)} ${descriptionId(index)}`\n        : labelId(index);\n      return normalize.element({\n        \"data-scope\": \"action-sheet\",\n        \"data-part\": \"item\",\n        \"data-visual-target\": action.danger ? \"action-sheet-danger\" : \"action-sheet-item\",\n        id: `${base}:action:${index}`,\n        type: \"button\",\n        disabled: action.disabled,\n        \"aria-labelledby\": labelledBy,\n        \"aria-describedby\": action.descriptionText ? descriptionId(index) : undefined,\n        \"data-value\": action.value,\n        \"data-danger\": action.danger ? \"\" : undefined,\n        \"data-disabled\": action.disabled ? \"\" : undefined,\n        \"data-duplicate\": action.duplicate ? \"\" : undefined,\n        \"data-keep-open\": action.keepOpen ? \"\" : undefined,\n        onClick: activate(action),\n      });\n    },\n    getActionLabelProps: ({ index }) => normalize.element({\n      \"data-scope\": \"action-sheet\",\n      \"data-part\": \"label\",\n      id: labelId(index),\n      \"data-danger\": actions[index]?.danger ? \"\" : undefined,\n    }),\n    getActionDescriptionProps: ({ index }) => normalize.element({\n      \"data-scope\": \"action-sheet\",\n      \"data-part\": \"description\",\n      \"data-visual-target\": \"action-sheet-description\",\n      id: descriptionId(index),\n      \"data-danger\": actions[index]?.danger ? \"\" : undefined,\n    }),\n    getCancelProps: () => normalize.element({\n      \"data-scope\": \"action-sheet\",\n      \"data-part\": \"cancel\",\n      \"data-visual-target\": \"action-sheet-cancel\",\n      id: `${base}:cancel`,\n      type: \"button\",\n      onClick: () => popup.setOpen(false),\n    }),\n  };\n}\n"],"mappings":"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"}

package/dist/area-picker/area-picker.d.ts

@@ -0,0 +1,113 @@
+import { type Machine, type Service } from "@zag-js/core";
+import { type CascaderOption } from "../cascader/cascader.js";
+import type { QwPickerProps } from "../picker/picker.js";
+import type { PickerColumn, PickerValue } from "../picker/selection-model.js";
+/** Caller-owned region data. No national administrative dataset is bundled. Codes are opaque strings. */
+export interface AreaPickerNode {
+    code: string;
+    label: string;
+    disabled?: boolean;
+    leaf?: boolean;
+    children?: AreaPickerNode[];
+}
+export interface AreaPickerChangeDetails {
+    value: string[];
+    labels: string[];
+    path: AreaPickerNode[];
+    code: string | undefined;
+}
+export interface AreaPickerLoadDetails {
+    node: AreaPickerNode;
+    path: string[];
+    signal: AbortSignal;
+}
+export interface QwAreaPickerProps extends Omit<QwPickerProps, "columns" | "value" | "defaultValue" | "onValueChange" | "onPreviewChange"> {
+    data: readonly AreaPickerNode[];
+    /** Explicit locale boundary copied by the real Picker portal. */
+    lang?: string;
+    dir?: string;
+    value?: string[];
+    defaultValue?: string[];
+    /** Maximum hierarchy depth, default 3. Explicit leaf nodes may terminate earlier. */
+    maxDepth?: number;
+    columnLabels?: string[];
+    loadChildren?: (details: AreaPickerLoadDetails) => Promise<AreaPickerNode[]>;
+    loadingText?: string;
+    errorText?: string;
+    retryText?: string;
+    name?: string;
+    onValueChange?: (details: AreaPickerChangeDetails) => void;
+    onPreviewChange?: (details: AreaPickerChangeDetails) => void;
+}
+export declare const AREA_PICKER_PARTS: readonly ["root", "status", "retry-trigger", "input"];
+export declare function toAreaPickerOptions(data: readonly AreaPickerNode[]): CascaderOption[];
+/** Fill enabled descendants; a disabled ancestor invalidates its entire branch. */
+export declare function resolveAreaPickerValue(options: readonly CascaderOption[], value: readonly (string | null)[], maxDepth?: number): string[];
+export interface QwAreaPickerSchema {
+    props: QwAreaPickerProps;
+    context: {
+        value: string[];
+        preview: string[];
+        base: string;
+        options: CascaderOption[];
+        loading: string[];
+        error: string[];
+    };
+    refs: {
+        controller: AbortController | null;
+        active: boolean;
+        request: number;
+        options: CascaderOption[] | undefined;
+    };
+    state: "idle";
+    action: "preview" | "commit" | "sync" | "success" | "error" | "retry" | "reset" | "open";
+    effect: "lifecycle";
+    event: {
+        type: "PREVIEW" | "COMMIT";
+        value: PickerValue;
+    } | {
+        type: "SYNC" | "RETRY" | "RESET" | "OPEN";
+    } | {
+        type: "SUCCESS";
+        request: number;
+        path: string[];
+        data: AreaPickerNode[];
+    } | {
+        type: "ERROR";
+        request: number;
+        path: string[];
+    };
+}
+export type QwAreaPickerMachine = Machine<QwAreaPickerSchema>;
+export type QwAreaPickerService = Service<QwAreaPickerSchema>;
+export declare function createAreaPickerProps(props: QwAreaPickerProps): QwAreaPickerProps;
+export declare const areaPickerMachine: QwAreaPickerMachine;
+export interface QwAreaPickerApi {
+    value: string[];
+    labels: string[];
+    previewValue: string[];
+    valid: boolean;
+    loading: boolean;
+    error: boolean;
+    statusText: string;
+    retryText: string;
+    columns: PickerColumn[];
+    pickerProps: QwPickerProps;
+    notifyPreview(value: PickerValue): void;
+    notifyCommit(value: PickerValue): void;
+    retry(): void;
+    getRootProps(): Record<string, string | undefined>;
+    getStatusProps(): Record<string, string | boolean>;
+    getRetryProps(): {
+        type: "button";
+        hidden: boolean;
+        onClick(): void;
+    };
+    getInputProps(): {
+        type: "hidden";
+        name: string | undefined;
+        value: string;
+        disabled: boolean;
+    };
+}
+export declare function connectAreaPicker(service: QwAreaPickerService, props: QwAreaPickerProps): QwAreaPickerApi;

package/dist/area-picker/index.d.ts

@@ -0,0 +1 @@
+export * from "./area-picker.js";