zkit-ui 1.0.0

package/src/services/ActionDialogService/README.md

@@ -0,0 +1,146 @@
+# ActionDialog
+
+顶层操作对话框，提供两种入口：
+
+- `ActionDialog`：声明式组件，支持 `open/defaultOpen/onOpenChange`
+- `actionDialog`：全局命令式服务，适合路由守卫、请求确认、跨组件业务流程
+
+`ComponentLibProvider` 已内置 `ActionDialogProvider`；只有单独使用 `actionDialog` 服务时才需要确认 Provider 已挂载。
+
+## 设计取舍
+
+- 声明式组件拥有状态模型；service 只调度宿主实例，避免半受控状态竞争。
+- `message` 承载简单正文，`children` 承载复杂内容；不再使用含糊的 `content`。
+- action 的 `role` 决定结果语义，`tone/variant` 决定视觉，不把业务结果和样式绑死。
+- ActionDialog 只确认用户意图，不承接业务异步；确认后直接关闭，异步进度与结果态交给 `loading.promise()`。
+- `footer.layout="auto"` 默认横排；3 个短标签也保持横排，长标签、自定义节点或更多动作才自动堆叠。需要固定样式时显式传 `row/stack/bar`。
+- 默认同一时刻只显示一个全局 dialog；新调用会替换旧调用并以 `replace` 结算。需要串行展示时传 `collisionStrategy: 'queue'`。
+- 默认不点蒙层关闭，Android back / iOS accessibility escape 可关闭；这是确认类弹窗更稳妥的默认行为。
+- `actionDialog` 全局服务默认使用顶层 `inline` 宿主，避开 Android 触发时创建原生 Modal 窗口的延迟；声明式组件默认仍用 `modal`，也可按场景切到 `hostMode="inline"`。
+- 默认过渡是低成本 `motion="fade"`，只做遮罩与卡片透明度变化；需要更明显的中心弹出感时再显式使用 `motion="scale"`。
+
+## 声明式使用
+
+```tsx
+import { ActionDialog } from 'zkit-ui';
+
+<ActionDialog
+  open={open}
+  onOpenChange={setOpen}
+  title="删除确认"
+  message="确定要删除这条记录吗？"
+  actions={[
+    { key: 'cancel', role: 'cancel' },
+    { key: 'delete', role: 'confirm', label: '删除', tone: 'danger' },
+  ]}
+/>;
+```
+
+## 命令式确认
+
+```tsx
+import { actionDialog, loading } from 'zkit-ui';
+
+const confirmed = await actionDialog.confirm({
+  title: '删除确认',
+  message: '确定要删除这条记录吗？',
+  tone: 'danger',
+  confirmLabel: '删除',
+});
+
+if (confirmed) {
+  await loading.promise(remove(), {
+    loading: '删除中',
+    success: '已删除',
+    error: '删除失败',
+  });
+}
+```
+
+## 自定义动作
+
+```tsx
+const handle = actionDialog.open({
+  title: '离开页面',
+  message: '还有未保存内容，确认离开？',
+  actions: [
+    { key: 'cancel', role: 'cancel' },
+    {
+      key: 'stay',
+      role: 'neutral',
+      label: '继续编辑',
+      closeOnPress: false,
+      onPress: ({ dismiss }) => {
+        dismiss();
+        return false;
+      },
+    },
+    {
+      key: 'leave',
+      role: 'confirm',
+      label: '离开',
+    },
+  ],
+});
+
+const result = await handle.result;
+```
+
+`onPress` 是同步拦截钩子；同步返回 `false` 会阻止默认关闭。业务异步不要放进 `onPress`，应在弹窗关闭并得到确认结果后用 `loading.promise()` 展示 loading / success / error。
+
+## 自定义 Footer
+
+```tsx
+actionDialog.open({
+  title: '高级操作',
+  message: '底部区域可以完全接管，但仍复用 action 语义。',
+  actions: [
+    { key: 'cancel', role: 'cancel' },
+    { key: 'save', role: 'confirm', label: '保存' },
+  ],
+  footer: {
+    render: ({ pressAction, close }) => (
+      <MyFooter onCancel={close} onSave={() => pressAction('save')} />
+    ),
+  },
+});
+```
+
+## 常用 API
+
+### `ActionDialog`
+
+| 参数 | 说明 |
+| --- | --- |
+| `open/defaultOpen/onOpenChange` | 标准受控/非受控打开状态 |
+| `title` | 标题区域 |
+| `message` | 简单正文 |
+| `children` | 复杂内容 |
+| `actions` | 底部动作列表 |
+| `footer.layout` | `'auto' \| 'row' \| 'stack' \| 'bar'`，默认 `auto` |
+| `dismiss.overlayPress` | 点击蒙层关闭，默认 `false` |
+| `dismiss.backPress` | Android back / accessibility escape 关闭，默认 `true` |
+| `keyboard.avoid` | 键盘出现时避让，默认 `true` |
+| `hostMode` | `'modal' \| 'inline'`，声明式默认 `modal` |
+| `motion` | `'none' \| 'fade' \| 'scale'`，默认 `fade` |
+| `layout` | `width/maxWidth/contentPadding/radius`，设计尺寸会通过 `wp(...)` 换算 |
+| `colors/labels` | 颜色与文案 escape hatch |
+
+### `actionDialog`
+
+| 方法 | 说明 |
+| --- | --- |
+| `open(options)` | 打开自定义对话框，返回 `ActionDialogHandle` |
+| `confirm(options)` | 打开确认框，确认返回 `true`，其它关闭返回 `false` |
+| `alert(options)` | 打开提示框，关闭后 resolve |
+| `close()` | 关闭当前对话框 |
+| `closeByScope(scopeKey)` | 关闭命中 scope 的当前或排队对话框 |
+| `closeAll()` | 关闭当前并清空队列 |
+| `getSnapshot()` | 读取当前打开态、active id 与队列数量 |
+
+`ActionDialogHandle` 包含：
+
+- `id`
+- `result: Promise<ActionDialogResult>`
+- `close()`
+- `update(patch)`

package/src/services/ActionDialogService/index.tsx

@@ -0,0 +1,39 @@
+export { ActionDialog } from './ActionDialog';
+export { ActionDialogProvider, actionDialog } from './service';
+export type {
+  ActionDialogAction,
+  ActionDialogActionContext,
+  ActionDialogActionPressResult,
+  ActionDialogActionResult,
+  ActionDialogActionRole,
+  ActionDialogActionTone,
+  ActionDialogActionVariant,
+  ActionDialogAlertOptions,
+  ActionDialogCollisionStrategy,
+  ActionDialogColors,
+  ActionDialogConfirmOptions,
+  ActionDialogDismissOptions,
+  ActionDialogDismissReason,
+  ActionDialogDismissResult,
+  ActionDialogFooterLayout,
+  ActionDialogFooterOptions,
+  ActionDialogFooterRenderContext,
+  ActionDialogHandle,
+  ActionDialogHostMode,
+  ActionDialogKeyboardOptions,
+  ActionDialogLabels,
+  ActionDialogLayerOptions,
+  ActionDialogLayoutOptions,
+  ActionDialogMotion,
+  ActionDialogOpenChangeMeta,
+  ActionDialogOpenChangeReason,
+  ActionDialogOpenOptions,
+  ActionDialogProps,
+  ActionDialogRef,
+  ActionDialogResolvedAction,
+  ActionDialogResolvedFooterLayout,
+  ActionDialogResult,
+  ActionDialogSemanticActionOptions,
+  ActionDialogService,
+  ActionDialogSnapshot,
+} from './types';

package/src/services/ActionDialogService/service.tsx

@@ -0,0 +1,355 @@
+import * as React from 'react';
+import { ActionDialog } from './ActionDialog';
+import { createSemanticAction, mergeOpenOptions } from './shared';
+import type {
+  ActionDialogAlertOptions,
+  ActionDialogConfirmOptions,
+  ActionDialogDismissReason,
+  ActionDialogHandle,
+  ActionDialogOpenOptions,
+  ActionDialogResult,
+  ActionDialogService,
+  ActionDialogSnapshot,
+} from './types';
+
+type ActionDialogRequest = ActionDialogOpenOptions & {
+  id: string;
+  resolve: (result: ActionDialogResult) => void;
+  settled: boolean;
+};
+
+type ActionDialogServiceState = {
+  activeRequest: ActionDialogRequest | null;
+  queuedRequests: ActionDialogRequest[];
+  open: boolean;
+};
+
+type ActionDialogServiceController = {
+  open: (request: ActionDialogRequest) => void;
+  close: (id: string | undefined, reason: ActionDialogDismissReason) => void;
+  closeByScope: (scopeKey: string, reason: ActionDialogDismissReason) => void;
+  closeAll: (reason: ActionDialogDismissReason) => void;
+  update: (id: string, patch: Partial<ActionDialogOpenOptions>) => void;
+  getSnapshot: () => ActionDialogSnapshot;
+};
+
+const initialState: ActionDialogServiceState = {
+  activeRequest: null,
+  queuedRequests: [],
+  open: false,
+};
+
+class ActionDialogServiceClass implements ActionDialogService {
+  private controller: ActionDialogServiceController | null = null;
+  private sequence = 0;
+
+  _bind(controller: ActionDialogServiceController | null) {
+    this.controller = controller;
+  }
+
+  open(options: ActionDialogOpenOptions = {}): ActionDialogHandle {
+    const id = `action_dialog_${Date.now()}_${++this.sequence}`;
+    let resolveResult: (result: ActionDialogResult) => void = () => {};
+    const result = new Promise<ActionDialogResult>((resolve) => {
+      resolveResult = resolve;
+    });
+    const request: ActionDialogRequest = {
+      ...options,
+      id,
+      resolve: resolveResult,
+      settled: false,
+    };
+
+    const handle: ActionDialogHandle = {
+      id,
+      result,
+      close: () => this.controller?.close(id, 'api'),
+      update: (patch) => this.controller?.update(id, patch),
+    };
+
+    if (!this.controller) {
+      if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        console.warn('[actionDialog] ActionDialogProvider is not mounted.');
+      }
+      this.settle(request, { type: 'dismiss', reason: 'unmount' });
+      return handle;
+    }
+
+    this.controller.open(request);
+    return handle;
+  }
+
+  async confirm({
+    cancelAction,
+    cancelLabel,
+    confirmAction,
+    confirmLabel,
+    footer,
+    tone = 'default',
+    ...restOptions
+  }: ActionDialogConfirmOptions = {}) {
+    const handle = this.open({
+      ...restOptions,
+      footer: { layout: footer?.layout },
+      actions: [
+        createSemanticAction(cancelAction, cancelLabel, 'cancel', 'cancel', 'neutral'),
+        createSemanticAction(
+          confirmAction,
+          confirmLabel,
+          'confirm',
+          'confirm',
+          tone === 'danger' ? 'danger' : 'primary'
+        ),
+      ],
+    });
+    const result = await handle.result;
+    return result.type === 'action' && result.action.role === 'confirm';
+  }
+
+  async alert({
+    confirmAction,
+    confirmLabel,
+    footer,
+    tone = 'default',
+    ...restOptions
+  }: ActionDialogAlertOptions = {}) {
+    const handle = this.open({
+      ...restOptions,
+      footer: { layout: footer?.layout },
+      actions: [
+        createSemanticAction(
+          confirmAction,
+          confirmLabel,
+          'confirm',
+          'confirm',
+          tone === 'danger' ? 'danger' : 'primary'
+        ),
+      ],
+    });
+    await handle.result;
+  }
+
+  close() {
+    this.controller?.close(undefined, 'api');
+  }
+
+  closeByScope(scopeKey: string) {
+    if (!scopeKey) return;
+    this.controller?.closeByScope(scopeKey, 'api');
+  }
+
+  closeAll() {
+    this.controller?.closeAll('api');
+  }
+
+  getSnapshot(): ActionDialogSnapshot {
+    return (
+      this.controller?.getSnapshot() ?? {
+        activeId: null,
+        open: false,
+        queuedCount: 0,
+      }
+    );
+  }
+
+  _settle(request: ActionDialogRequest, result: ActionDialogResult) {
+    this.settle(request, result);
+  }
+
+  private settle(request: ActionDialogRequest, result: ActionDialogResult) {
+    if (request.settled) return;
+    request.settled = true;
+    request.onClose?.(result);
+    request.resolve(result);
+  }
+}
+
+const actionDialogService = new ActionDialogServiceClass();
+
+export const actionDialog: ActionDialogService = actionDialogService;
+
+function settleRequest(request: ActionDialogRequest | null | undefined, result: ActionDialogResult) {
+  if (!request) return;
+  actionDialogService._settle(request, result);
+}
+
+export function ActionDialogProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = React.useState<ActionDialogServiceState>(initialState);
+  const stateRef = React.useRef(state);
+  stateRef.current = state;
+
+  const showNextRequest = React.useCallback(() => {
+    setState((prev) => {
+      const [nextRequest, ...restQueue] = prev.queuedRequests;
+      if (!nextRequest) {
+        return {
+          activeRequest: null,
+          queuedRequests: [],
+          open: false,
+        };
+      }
+
+      return {
+        activeRequest: nextRequest,
+        queuedRequests: restQueue,
+        open: true,
+      };
+    });
+  }, []);
+
+  const controller = React.useMemo<ActionDialogServiceController>(
+    () => ({
+      open: (request) => {
+        setState((prev) => {
+          if (request.collisionStrategy === 'queue' && prev.activeRequest) {
+            return {
+              ...prev,
+              queuedRequests: [...prev.queuedRequests, request],
+            };
+          }
+
+          settleRequest(prev.activeRequest, { type: 'dismiss', reason: 'replace' });
+          for (const queuedRequest of prev.queuedRequests) {
+            settleRequest(queuedRequest, { type: 'dismiss', reason: 'replace' });
+          }
+
+          return {
+            activeRequest: request,
+            queuedRequests: [],
+            open: true,
+          };
+        });
+      },
+      close: (id, reason) => {
+        setState((prev) => {
+          if (id && prev.activeRequest?.id !== id) {
+            let changed = false;
+            const nextQueue = prev.queuedRequests.filter((request) => {
+              if (request.id !== id) return true;
+              changed = true;
+              settleRequest(request, { type: 'dismiss', reason });
+              return false;
+            });
+            return changed ? { ...prev, queuedRequests: nextQueue } : prev;
+          }
+
+          if (!prev.activeRequest) return prev;
+          settleRequest(prev.activeRequest, { type: 'dismiss', reason });
+          return { ...prev, open: false };
+        });
+      },
+      closeByScope: (scopeKey, reason) => {
+        setState((prev) => {
+          let changed = false;
+          const nextQueue = prev.queuedRequests.filter((request) => {
+            if (request.scopeKey !== scopeKey) return true;
+            changed = true;
+            settleRequest(request, { type: 'dismiss', reason });
+            return false;
+          });
+
+          if (prev.activeRequest?.scopeKey === scopeKey) {
+            settleRequest(prev.activeRequest, { type: 'dismiss', reason });
+            return { ...prev, queuedRequests: nextQueue, open: false };
+          }
+
+          return changed ? { ...prev, queuedRequests: nextQueue } : prev;
+        });
+      },
+      closeAll: (reason) => {
+        setState((prev) => {
+          settleRequest(prev.activeRequest, { type: 'dismiss', reason });
+          for (const queuedRequest of prev.queuedRequests) {
+            settleRequest(queuedRequest, { type: 'dismiss', reason });
+          }
+          return {
+            activeRequest: prev.activeRequest,
+            queuedRequests: [],
+            open: prev.activeRequest ? false : prev.open,
+          };
+        });
+      },
+      update: (id, patch) => {
+        setState((prev) => {
+          if (prev.activeRequest?.id === id) {
+            return {
+              ...prev,
+              activeRequest: {
+                ...mergeOpenOptions(prev.activeRequest, patch),
+                id,
+                resolve: prev.activeRequest.resolve,
+                settled: prev.activeRequest.settled,
+              },
+            };
+          }
+
+          let changed = false;
+          const queuedRequests = prev.queuedRequests.map((request) => {
+            if (request.id !== id) return request;
+            changed = true;
+            return {
+              ...mergeOpenOptions(request, patch),
+              id,
+              resolve: request.resolve,
+              settled: request.settled,
+            };
+          });
+
+          return changed ? { ...prev, queuedRequests } : prev;
+        });
+      },
+      getSnapshot: () => ({
+        activeId: stateRef.current.activeRequest?.id ?? null,
+        open: stateRef.current.open,
+        queuedCount: stateRef.current.queuedRequests.length,
+      }),
+    }),
+    []
+  );
+
+  React.useEffect(() => {
+    actionDialogService._bind(controller);
+
+    return () => {
+      const currentState = stateRef.current;
+      settleRequest(currentState.activeRequest, { type: 'dismiss', reason: 'unmount' });
+      for (const queuedRequest of currentState.queuedRequests) {
+        settleRequest(queuedRequest, { type: 'dismiss', reason: 'unmount' });
+      }
+      actionDialogService._bind(null);
+    };
+  }, [controller]);
+
+  const handleClose = React.useCallback((result: ActionDialogResult) => {
+    setState((prev) => {
+      if (!prev.activeRequest) return prev;
+      settleRequest(prev.activeRequest, result);
+      return { ...prev, open: false };
+    });
+  }, []);
+
+  const activeRequest = state.activeRequest;
+  const activeDialogProps = React.useMemo(() => {
+    if (!activeRequest) return {};
+    const { collisionStrategy, id, resolve, scopeKey, settled, ...props } = activeRequest;
+    void collisionStrategy;
+    void id;
+    void resolve;
+    void scopeKey;
+    void settled;
+    return props;
+  }, [activeRequest]);
+
+  return (
+    <>
+      {children}
+      <ActionDialog
+        {...activeDialogProps}
+        hostMode={activeRequest?.hostMode ?? 'inline'}
+        open={Boolean(activeRequest && state.open)}
+        onClose={handleClose}
+        onDismissComplete={showNextRequest}
+      />
+    </>
+  );
+}