zkit-ui 1.0.0

package/src/services/ActionDialogService/shared.ts

@@ -0,0 +1,204 @@
+import type * as React from 'react';
+import type {
+  ActionDialogAction,
+  ActionDialogActionRole,
+  ActionDialogActionTone,
+  ActionDialogActionVariant,
+  ActionDialogColors,
+  ActionDialogDismissOptions,
+  ActionDialogFooterLayout,
+  ActionDialogKeyboardOptions,
+  ActionDialogLabels,
+  ActionDialogLayoutOptions,
+  ActionDialogOpenOptions,
+  ActionDialogResolvedAction,
+  ActionDialogResolvedFooterLayout,
+  ActionDialogResult,
+  ActionDialogSemanticActionOptions,
+} from './types';
+
+export const ACTION_DIALOG_DEFAULT_Z_INDEX = 4200;
+
+export const ACTION_DIALOG_DEFAULT_LAYOUT: Required<ActionDialogLayoutOptions> = {
+  width: 320,
+  maxWidth: 380,
+  contentPadding: 20,
+  radius: 20,
+};
+
+export const ACTION_DIALOG_DEFAULT_DISMISS: Required<ActionDialogDismissOptions> = {
+  overlayPress: false,
+  backPress: true,
+};
+
+export const ACTION_DIALOG_DEFAULT_KEYBOARD: Required<ActionDialogKeyboardOptions> = {
+  avoid: true,
+  dismissOnOverlayPress: true,
+  dismissOnClose: true,
+};
+
+export const ACTION_DIALOG_DEFAULT_COLORS: Required<ActionDialogColors> = {
+  backdrop: 'rgba(17, 24, 39, 0.48)',
+  surface: '',
+  title: '',
+  message: '',
+  border: '',
+};
+
+const AUTO_ROW_MAX_ACTIONS = 3;
+const AUTO_ROW_MAX_LABEL_WEIGHT = 8;
+
+export function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function positiveNumber(value: number | undefined, fallback: number) {
+  return isFiniteNumber(value) && value > 0 ? value : fallback;
+}
+
+export function resolveLayout(layout: ActionDialogLayoutOptions | undefined): Required<ActionDialogLayoutOptions> {
+  return {
+    width: positiveNumber(layout?.width, ACTION_DIALOG_DEFAULT_LAYOUT.width),
+    maxWidth: positiveNumber(layout?.maxWidth, ACTION_DIALOG_DEFAULT_LAYOUT.maxWidth),
+    contentPadding: positiveNumber(layout?.contentPadding, ACTION_DIALOG_DEFAULT_LAYOUT.contentPadding),
+    radius: positiveNumber(layout?.radius, ACTION_DIALOG_DEFAULT_LAYOUT.radius),
+  };
+}
+
+export function resolveDismissOptions(
+  dismissible: boolean,
+  dismiss: ActionDialogDismissOptions | undefined
+): Required<ActionDialogDismissOptions> {
+  return {
+    overlayPress: dismissible && (dismiss?.overlayPress ?? ACTION_DIALOG_DEFAULT_DISMISS.overlayPress),
+    backPress: dismissible && (dismiss?.backPress ?? ACTION_DIALOG_DEFAULT_DISMISS.backPress),
+  };
+}
+
+export function resolveKeyboardOptions(
+  keyboard: ActionDialogKeyboardOptions | undefined
+): Required<ActionDialogKeyboardOptions> {
+  return {
+    avoid: keyboard?.avoid ?? ACTION_DIALOG_DEFAULT_KEYBOARD.avoid,
+    dismissOnOverlayPress:
+      keyboard?.dismissOnOverlayPress ?? ACTION_DIALOG_DEFAULT_KEYBOARD.dismissOnOverlayPress,
+    dismissOnClose: keyboard?.dismissOnClose ?? ACTION_DIALOG_DEFAULT_KEYBOARD.dismissOnClose,
+  };
+}
+
+export function resolveFooterLayout(
+  layout: ActionDialogFooterLayout | undefined,
+  actions: readonly Pick<ActionDialogResolvedAction, 'label'>[]
+): ActionDialogResolvedFooterLayout {
+  if (layout === 'bar' || layout === 'row' || layout === 'stack') return layout;
+  if (actions.length <= 2) return 'row';
+  if (actions.length > AUTO_ROW_MAX_ACTIONS) return 'stack';
+  return actions.every((action) => {
+    const weight = getPrimitiveLabelWeight(action.label);
+    return weight != null && weight <= AUTO_ROW_MAX_LABEL_WEIGHT;
+  })
+    ? 'row'
+    : 'stack';
+}
+
+function defaultToneForRole(role: ActionDialogActionRole): ActionDialogActionTone {
+  if (role === 'confirm') return 'primary';
+  return 'neutral';
+}
+
+function getPrimitiveLabelWeight(label: React.ReactNode) {
+  const text = typeof label === 'string' || typeof label === 'number' ? String(label).trim() : '';
+  if (!text) return null;
+
+  return Array.from(text).reduce((total, char) => {
+    const code = char.codePointAt(0) ?? 0;
+    return total + (code > 0xff ? 2 : 1);
+  }, 0);
+}
+
+function defaultVariantForTone(tone: ActionDialogActionTone): ActionDialogActionVariant {
+  return tone === 'neutral' ? 'soft' : 'solid';
+}
+
+function fallbackLabel(role: ActionDialogActionRole, key: string, labels: ActionDialogLabels): React.ReactNode {
+  if (role === 'confirm') return labels.confirm;
+  if (role === 'cancel') return labels.cancel;
+  return key;
+}
+
+export function resolveActions(
+  actions: readonly ActionDialogAction[] | undefined,
+  labels: ActionDialogLabels
+): ActionDialogResolvedAction[] {
+  if (!actions?.length) return [];
+
+  return actions.map((action, index) => {
+    const role = action.role ?? 'neutral';
+    const key = action.key ?? `${role}-${index}`;
+    const tone = action.tone ?? defaultToneForRole(role);
+    const variant = action.variant ?? defaultVariantForTone(tone);
+
+    return {
+      key,
+      role,
+      label: action.label ?? fallbackLabel(role, key, labels),
+      tone,
+      variant,
+      closeOnPress: action.closeOnPress ?? true,
+      disabled: Boolean(action.disabled),
+      loading: Boolean(action.loading),
+      accessibilityLabel: action.accessibilityLabel,
+      testID: action.testID,
+      onPress: action.onPress,
+    };
+  });
+}
+
+export function createActionResult(action: ActionDialogResolvedAction): ActionDialogResult {
+  return {
+    type: 'action',
+    action: {
+      key: action.key,
+      role: action.role,
+    },
+  };
+}
+
+export function mergeOpenOptions(
+  base: ActionDialogOpenOptions,
+  patch: Partial<ActionDialogOpenOptions>
+): ActionDialogOpenOptions {
+  return {
+    ...base,
+    ...patch,
+    colors: { ...base.colors, ...patch.colors },
+    dismiss: { ...base.dismiss, ...patch.dismiss },
+    footer: { ...base.footer, ...patch.footer },
+    keyboard: { ...base.keyboard, ...patch.keyboard },
+    labels: { ...base.labels, ...patch.labels },
+    layer: { ...base.layer, ...patch.layer },
+    layout: { ...base.layout, ...patch.layout },
+  };
+}
+
+export function createSemanticAction(
+  input: ActionDialogSemanticActionOptions | undefined,
+  fallbackLabel: React.ReactNode | undefined,
+  key: string,
+  role: ActionDialogActionRole,
+  tone: ActionDialogActionTone
+): ActionDialogAction {
+  return {
+    key: input?.key ?? key,
+    role,
+    label: input?.label ?? fallbackLabel,
+    tone: input?.tone ?? tone,
+    variant: input?.variant,
+    closeOnPress: input?.closeOnPress ?? true,
+    disabled: input?.disabled,
+    loading: input?.loading,
+    accessibilityLabel: input?.accessibilityLabel,
+    testID: input?.testID,
+    onPress: input?.onPress,
+  };
+}

package/src/services/ActionDialogService/types.ts

@@ -0,0 +1,197 @@
+import type * as React from 'react';
+import type { ModalProps, StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+export type ActionDialogActionRole = 'confirm' | 'cancel' | 'neutral';
+export type ActionDialogActionTone = 'primary' | 'neutral' | 'danger';
+export type ActionDialogActionVariant = 'solid' | 'soft' | 'outline' | 'ghost';
+export type ActionDialogFooterLayout = 'auto' | 'row' | 'stack' | 'bar';
+export type ActionDialogResolvedFooterLayout = Exclude<ActionDialogFooterLayout, 'auto'>;
+export type ActionDialogDismissReason = 'api' | 'back' | 'overlay' | 'replace' | 'unmount';
+export type ActionDialogOpenChangeReason = 'action' | ActionDialogDismissReason;
+export type ActionDialogCollisionStrategy = 'replace' | 'queue';
+export type ActionDialogHostMode = 'modal' | 'inline';
+export type ActionDialogMotion = 'none' | 'fade' | 'scale';
+
+export type ActionDialogActionResult = {
+  type: 'action';
+  action: {
+    key: string;
+    role: ActionDialogActionRole;
+  };
+};
+
+export type ActionDialogDismissResult = {
+  type: 'dismiss';
+  reason: ActionDialogDismissReason;
+};
+
+export type ActionDialogResult = ActionDialogActionResult | ActionDialogDismissResult;
+
+export type ActionDialogActionContext = {
+  action: ActionDialogResolvedAction;
+  close: () => void;
+  dismiss: (reason?: Extract<ActionDialogDismissReason, 'api'>) => void;
+};
+
+export type ActionDialogActionPressResult = void | false;
+
+export type ActionDialogAction = {
+  key?: string;
+  role?: ActionDialogActionRole;
+  label?: React.ReactNode;
+  tone?: ActionDialogActionTone;
+  variant?: ActionDialogActionVariant;
+  closeOnPress?: boolean;
+  disabled?: boolean;
+  loading?: boolean;
+  accessibilityLabel?: string;
+  testID?: ViewProps['testID'];
+  onPress?: (context: ActionDialogActionContext) => ActionDialogActionPressResult;
+};
+
+export type ActionDialogResolvedAction = Required<
+  Pick<ActionDialogAction, 'closeOnPress' | 'disabled' | 'key' | 'loading' | 'role' | 'tone' | 'variant'>
+> &
+  Pick<ActionDialogAction, 'accessibilityLabel' | 'label' | 'onPress' | 'testID'>;
+
+export type ActionDialogFooterRenderContext = {
+  actions: ActionDialogResolvedAction[];
+  layout: ActionDialogResolvedFooterLayout;
+  close: () => void;
+  pressAction: (key: string) => void;
+};
+
+export type ActionDialogFooterOptions = {
+  layout?: ActionDialogFooterLayout;
+  render?: (context: ActionDialogFooterRenderContext) => React.ReactNode;
+};
+
+export type ActionDialogDismissOptions = {
+  overlayPress?: boolean;
+  backPress?: boolean;
+};
+
+export type ActionDialogKeyboardOptions = {
+  avoid?: boolean;
+  dismissOnOverlayPress?: boolean;
+  dismissOnClose?: boolean;
+};
+
+export type ActionDialogLayoutOptions = {
+  width?: number;
+  maxWidth?: number;
+  contentPadding?: number;
+  radius?: number;
+};
+
+export type ActionDialogLayerOptions = {
+  zIndex?: number;
+};
+
+export type ActionDialogColors = {
+  backdrop?: string;
+  surface?: string;
+  title?: string;
+  message?: string;
+  border?: string;
+};
+
+export type ActionDialogLabels = {
+  confirm: string;
+  cancel: string;
+  close: string;
+};
+
+export type ActionDialogOpenChangeMeta = {
+  reason: ActionDialogOpenChangeReason;
+  result?: ActionDialogResult;
+};
+
+export type ActionDialogRef = {
+  close: (reason?: Extract<ActionDialogDismissReason, 'api'>) => void;
+  pressAction: (key: string) => void;
+  getOpen: () => boolean;
+};
+
+export type ActionDialogProps = {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean, meta: ActionDialogOpenChangeMeta) => void;
+  onClose?: (result: ActionDialogResult) => void;
+  onDismissComplete?: () => void;
+  onActionError?: (error: unknown, action: ActionDialogResolvedAction) => void;
+
+  title?: React.ReactNode;
+  message?: React.ReactNode;
+  children?: React.ReactNode;
+  actions?: readonly ActionDialogAction[];
+  footer?: ActionDialogFooterOptions;
+
+  disabled?: boolean;
+  dismissible?: boolean;
+  dismiss?: ActionDialogDismissOptions;
+  hostMode?: ActionDialogHostMode;
+  keyboard?: ActionDialogKeyboardOptions;
+  layout?: ActionDialogLayoutOptions;
+  layer?: ActionDialogLayerOptions;
+  colors?: Partial<ActionDialogColors>;
+  labels?: Partial<ActionDialogLabels>;
+  motion?: ActionDialogMotion;
+  modalProps?: Omit<
+    ModalProps,
+    'children' | 'onRequestClose' | 'presentationStyle' | 'statusBarTranslucent' | 'transparent' | 'visible'
+  >;
+
+  style?: StyleProp<ViewStyle>;
+  testID?: ViewProps['testID'];
+  accessibilityLabel?: ViewProps['accessibilityLabel'];
+};
+
+export type ActionDialogSemanticActionOptions = Omit<Partial<ActionDialogAction>, 'role'>;
+
+export type ActionDialogOpenOptions = Omit<
+  ActionDialogProps,
+  'defaultOpen' | 'modalProps' | 'onDismissComplete' | 'onOpenChange' | 'open'
+> & {
+  scopeKey?: string;
+  collisionStrategy?: ActionDialogCollisionStrategy;
+};
+
+export type ActionDialogConfirmOptions = Omit<ActionDialogOpenOptions, 'actions' | 'footer'> & {
+  confirmLabel?: React.ReactNode;
+  cancelLabel?: React.ReactNode;
+  confirmAction?: ActionDialogSemanticActionOptions;
+  cancelAction?: ActionDialogSemanticActionOptions;
+  tone?: 'default' | 'danger';
+  footer?: Pick<ActionDialogFooterOptions, 'layout'>;
+};
+
+export type ActionDialogAlertOptions = Omit<ActionDialogOpenOptions, 'actions' | 'footer'> & {
+  confirmLabel?: React.ReactNode;
+  confirmAction?: ActionDialogSemanticActionOptions;
+  tone?: 'default' | 'danger';
+  footer?: Pick<ActionDialogFooterOptions, 'layout'>;
+};
+
+export type ActionDialogHandle = {
+  id: string;
+  result: Promise<ActionDialogResult>;
+  close: (reason?: Extract<ActionDialogDismissReason, 'api'>) => void;
+  update: (patch: Partial<ActionDialogOpenOptions>) => void;
+};
+
+export type ActionDialogSnapshot = {
+  open: boolean;
+  activeId: string | null;
+  queuedCount: number;
+};
+
+export type ActionDialogService = {
+  open: (options?: ActionDialogOpenOptions) => ActionDialogHandle;
+  confirm: (options?: ActionDialogConfirmOptions) => Promise<boolean>;
+  alert: (options?: ActionDialogAlertOptions) => Promise<void>;
+  close: (reason?: Extract<ActionDialogDismissReason, 'api'>) => void;
+  closeByScope: (scopeKey: string) => void;
+  closeAll: (reason?: Extract<ActionDialogDismissReason, 'api'>) => void;
+  getSnapshot: () => ActionDialogSnapshot;
+};

package/src/services/CardToastService/README.md

@@ -0,0 +1,128 @@
+# CardToastService
+
+全局卡片 Toast 服务，适合保存成功、网络失败、轻量操作反馈这类不应打断用户流程的提示。
+
+`ComponentLibProvider` 已内置 `ToastProvider`。如果单独接入，需要把 `ToastProvider` 放在应用根部。
+
+```tsx
+import { ToastProvider } from 'zkit-ui';
+
+export function App() {
+  return <ToastProvider>{/* app */}</ToastProvider>;
+}
+```
+
+## 默认行为
+
+- 默认视觉保持原卡片 Toast：语义 webp 图标、淡色背景、细边框、`wp(320)` 宽度、`wp(10)` 圆角和 iOS sheen 动效不变。
+- 默认 `placement: 'top'`，位置会叠加 safe area，额外偏移保持原来的 `35` 设计像素。
+- 默认 `strategy: 'replace'`，新提示替换当前提示，避免连续操作时堆积。
+- 默认 `duration: 2400`，传 `duration: 0` 时不会自动关闭，并会自动显示关闭按钮。
+- 动画只使用 opacity / transform，避免布局动画和 JS 高频驱动。
+- Toast 是全局轻反馈层，默认显示在 Dialog、Picker 等交互遮罩之上；阻塞式 Loading、图片预览等最高优先级浮层仍应高于 Toast。
+
+## 使用方式
+
+```ts
+import { toast } from 'zkit-ui';
+
+toast.success('保存成功');
+toast.error('网络错误', {
+  description: '请检查网络后重试',
+  duration: 3200,
+});
+toast.info('已刷新', { placement: 'bottom' });
+```
+
+完整配置入口：
+
+```ts
+const handle = toast.show({
+  tone: 'warning',
+  title: '资料未完整',
+  description: '请补充手机号后继续',
+  action: {
+    label: '去补充',
+    onPress: () => {
+      // navigate(...)
+    },
+  },
+});
+
+handle.update({ tone: 'success', title: '已补充', description: undefined });
+handle.dismiss();
+```
+
+## 队列策略
+
+```ts
+toast.info('按顺序展示', { strategy: 'queue' });
+toast.success('可堆叠提示', { strategy: 'stack', maxVisible: 3 });
+```
+
+| strategy | 行为 |
+| --- | --- |
+| `replace` | 关闭当前可见 Toast，展示最新一条。默认值 |
+| `queue` | 当前 Toast 完整退出后，再展示下一条 |
+| `stack` | 同位置最多展示 `maxVisible` 条，超出时关闭最旧一条 |
+
+## 全局默认值
+
+```ts
+toast.configure({
+  placement: 'top',
+  offset: 35,
+  duration: 2400,
+  strategy: 'replace',
+  maxVisible: 3,
+  closeButton: false,
+});
+```
+
+单条 Toast 的 options 优先级高于 `configure`。
+
+## 自定义渲染
+
+```tsx
+toast.custom(
+  ({ dismiss }) => (
+    <Pressable onPress={() => dismiss()}>
+      <Text>自定义 Toast</Text>
+    </Pressable>
+  ),
+  {
+    accessibilityLabel: '自定义 Toast',
+    duration: 0,
+  }
+);
+```
+
+自定义渲染仍由 `ToastProvider` 管理生命周期、队列、safe area 和退出清理。自定义内容里的像素尺寸仍应使用 `wp(...)`。
+
+## API 摘要
+
+| API | 说明 |
+| --- | --- |
+| `toast.show(options)` | 展示完整配置的 Toast，返回 `ToastHandle` |
+| `toast.success/error/warning/info/neutral(title, options?)` | 语义快捷入口 |
+| `toast.custom(render, options?)` | 自定义内容入口 |
+| `toast.update(idOrHandle, patch)` | 更新可见或排队中的 Toast |
+| `toast.dismiss(idOrHandle?)` | 关闭指定 Toast；不传时关闭最新可见 Toast |
+| `toast.dismissAll()` | 关闭所有可见和排队 Toast |
+| `toast.configure(defaults)` | 设置全局默认值 |
+
+常用 options：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `tone` | `'success' \| 'error' \| 'warning' \| 'info' \| 'neutral'` | 语义色 |
+| `title` | `ReactNode` | 主文案 |
+| `description` | `ReactNode` | 辅助文案 |
+| `duration` | `number` | 自动关闭时长，`0` 表示常驻 |
+| `placement` | `'top' \| 'bottom'` | 出现位置 |
+| `offset` | `number` | 相对 safe area 的设计像素偏移 |
+| `strategy` | `'replace' \| 'queue' \| 'stack'` | 连续触发策略 |
+| `action` | `ToastAction` | 可点击动作 |
+| `closeButton` | `boolean` | 是否展示关闭按钮 |
+| `icon` | `ReactNode \| false \| render` | 自定义图标或隐藏图标 |
+| `render` | `(context) => ReactNode` | 完全自定义内容 |