zkit-ui 1.0.0

package/src/services/PickerService/index.tsx

@@ -0,0 +1,410 @@
+/**
+ * @file PickerService - 命令式选择器服务
+ * @description 提供 pick、pickDate、pickAddress、pickBetweenTime 等方法
+ * @example
+ * ```tsx
+ * import { pickerService } from 'zkit-ui';
+ *
+ * const result = await pickerService.pick({ options: [...], value: 'id' });
+ * const date = await pickerService.pickDate({ value: '2024-01-01' });
+ * ```
+ */
+
+import * as React from 'react';
+import {
+  Picker,
+  type PickerConfirmPayload,
+  type PickerValue,
+  type PickerProps,
+} from '../../ui/Picker';
+import { DatePicker, type DatePickerProps, type DatePickerValue } from '../../ui/DatePicker';
+import {
+  AddressCascader,
+  type AddressCascaderOption,
+  type AddressCascaderProps,
+  type AddressCascaderValue,
+} from '../../ui/AddressCascader';
+import { BetweenTime, type BetweenTimeProps } from '../../ui/BetweenTime';
+
+// ============ Types ============
+
+/** 通用选择器返回结果 */
+export type PickerResult = {
+  /** 选中值 */
+  value: PickerValue;
+  /** 选中值数组（多列时） */
+  values: PickerConfirmPayload['values'];
+  /** 选中项文本 */
+  label: string;
+  /** 选中项文本数组（多列时） */
+  labels: string[];
+  /** 选中项数据 */
+  items: PickerConfirmPayload['items'];
+} | null;
+
+/** 日期选择器返回结果 */
+export type DatePickerResult = {
+  /** 选中日期值 */
+  value: DatePickerValue;
+  /** 格式化后的日期文本 */
+  label: string;
+} | null;
+
+/** 地址选择器返回结果 */
+export type AddressPickerResult = {
+  /** 选中地址码数组 */
+  value: AddressCascaderValue;
+  /** 选中地址码数组 */
+  values: string[];
+  /** 完整地址文本 */
+  label: string;
+  /** 各级地址文本数组 */
+  labels: string[];
+  /** 选中项数据 */
+  items: AddressCascaderOption[];
+} | null;
+
+/** 时间区间选择器返回结果 */
+export type BetweenTimePickerResult = {
+  /** 时间区间 [开始, 结束] */
+  value: string[];
+} | null;
+
+/** 通用选择器配置 */
+export type PickOptions = Omit<
+  PickerProps,
+  'open' | 'onOpenChange' | 'onConfirm' | 'onCancel' | 'children' | 'onDismissComplete'
+>;
+/** 日期选择器配置 */
+export type PickDateOptions = Omit<
+  DatePickerProps,
+  'open' | 'onOpenChange' | 'onConfirm' | 'onCancel' | 'children' | 'onDismissComplete'
+>;
+/** 地址选择器配置 */
+export type PickAddressOptions = Omit<
+  AddressCascaderProps,
+  'open' | 'onOpenChange' | 'onConfirm' | 'onCancel' | 'children' | 'onDismissComplete'
+>;
+/** 时间区间选择器配置 */
+export type PickBetweenTimeOptions = Omit<
+  BetweenTimeProps,
+  'open' | 'onOpenChange' | 'onConfirm' | 'onCancel' | 'children' | 'onDismissComplete'
+>;
+
+type PickerType = 'picker' | 'date' | 'address' | 'betweenTime';
+
+type PickerRequestMap = {
+  picker: {
+    options: PickOptions;
+    result: PickerResult;
+  };
+  date: {
+    options: PickDateOptions;
+    result: DatePickerResult;
+  };
+  address: {
+    options: PickAddressOptions;
+    result: AddressPickerResult;
+  };
+  betweenTime: {
+    options: PickBetweenTimeOptions;
+    result: BetweenTimePickerResult;
+  };
+};
+
+type PickerRequestResult = PickerRequestMap[PickerType]['result'];
+
+type PickerRequest<T extends PickerType = PickerType> = {
+  [K in T]: {
+    id: string;
+    type: K;
+    options: PickerRequestMap[K]['options'];
+    resolve: ((result: PickerRequestResult) => void) | null;
+  };
+}[T];
+
+type DatePickerConfirmPayload = Parameters<NonNullable<DatePickerProps['onConfirm']>>[0];
+type AddressCascaderConfirmPayload = Parameters<NonNullable<AddressCascaderProps['onConfirm']>>[0];
+type BetweenTimeConfirmPayload = Parameters<NonNullable<BetweenTimeProps['onConfirm']>>[0];
+
+type PickerState = {
+  activeRequest: PickerRequest | null;
+  queuedRequests: PickerRequest[];
+  open: boolean;
+};
+
+// ============ Service Class ============
+
+/**
+ * 选择器服务类
+ * @internal
+ */
+class PickerServiceClass {
+  private setState: React.Dispatch<React.SetStateAction<PickerState>> | null = null;
+  private sequence = 0;
+
+  /** @internal 设置状态更新器 */
+  setStateUpdater(updater: React.Dispatch<React.SetStateAction<PickerState>> | null) {
+    this.setState = updater;
+  }
+
+  /** @internal 显示选择器 */
+  private show<T extends PickerType>(
+    type: T,
+    options: PickerRequestMap[T]['options']
+  ): Promise<PickerRequestMap[T]['result']> {
+    return new Promise((resolve) => {
+      if (!this.setState) {
+        console.warn('[PickerService] Provider not mounted');
+        resolve(null as PickerRequestMap[T]['result']);
+        return;
+      }
+      const request = {
+        id: `picker-request-${Date.now()}-${++this.sequence}`,
+        type,
+        options,
+        resolve: (result: PickerRequestResult) => {
+          resolve(result as PickerRequestMap[T]['result']);
+        },
+      } as PickerRequest;
+      this.setState((prev) => {
+        if (!prev.activeRequest) {
+          return { ...prev, activeRequest: request, open: true };
+        }
+        return {
+          ...prev,
+          queuedRequests: [...prev.queuedRequests, request],
+        };
+      });
+    });
+  }
+
+  /** 打开通用选择器 */
+  pick(options: PickOptions): Promise<PickerResult> {
+    return this.show('picker', options);
+  }
+
+  /** 打开日期选择器 */
+  pickDate(options: PickDateOptions = {}): Promise<DatePickerResult> {
+    return this.show('date', options);
+  }
+
+  /** 打开地址选择器 */
+  pickAddress(options: PickAddressOptions = {}): Promise<AddressPickerResult> {
+    return this.show('address', options);
+  }
+
+  /** 打开时间区间选择器 */
+  pickBetweenTime(options: PickBetweenTimeOptions = {}): Promise<BetweenTimePickerResult> {
+    return this.show('betweenTime', options);
+  }
+
+  /** 关闭当前选择器 */
+  close() {
+    this.setState?.((prev) => {
+      if (!prev.activeRequest || !prev.open) return prev;
+      return { ...prev, open: false };
+    });
+  }
+}
+
+/** 选择器服务实例 */
+export const pickerService = new PickerServiceClass();
+
+// ============ Provider Component ============
+
+const initialState: PickerState = {
+  activeRequest: null,
+  queuedRequests: [],
+  open: false,
+};
+
+/**
+ * 选择器服务 Provider
+ * @description 需要在应用根组件中包裹，已内置于 ComponentLibProvider
+ */
+export function PickerServiceProvider({ children }: { children: React.ReactNode }) {
+  const [state, setState] = React.useState<PickerState>(initialState);
+  const activeRequestRef = React.useRef<PickerRequest | null>(null);
+  const queuedRequestsRef = React.useRef<PickerRequest[]>([]);
+  const settledRequestIdsRef = React.useRef(new Set<string>());
+  activeRequestRef.current = state.activeRequest;
+  queuedRequestsRef.current = state.queuedRequests;
+
+  /** 同一个请求只允许 settle 一次，关闭动画结束前仍保留 activeRequest 做串行调度。 */
+  const settleRequest = React.useCallback((request: PickerRequest | null, result: PickerRequestResult) => {
+    if (!request) return;
+    if (settledRequestIdsRef.current.has(request.id)) return;
+    settledRequestIdsRef.current.add(request.id);
+    request.resolve?.(result);
+  }, []);
+
+  React.useEffect(() => {
+    pickerService.setStateUpdater(setState);
+
+    return () => {
+      settleRequest(activeRequestRef.current, null);
+      for (const request of queuedRequestsRef.current) {
+        settleRequest(request, null);
+      }
+      pickerService.setStateUpdater(null);
+    };
+  }, [settleRequest]);
+
+  /** 业务层要求关闭时，先 settle 当前 promise，但不立刻销毁实例。 */
+  const handleOpenChange = React.useCallback((open: boolean) => {
+    if (open) {
+      setState((prev) => {
+        if (!prev.activeRequest || prev.open) return prev;
+        return { ...prev, open: true };
+      });
+      return;
+    }
+
+    settleRequest(activeRequestRef.current, null);
+    setState((prev) => {
+      if (!prev.activeRequest || !prev.open) return prev;
+      return { ...prev, open: false };
+    });
+  }, [settleRequest]);
+
+  /** 取消时 resolve null */
+  const handleCancel = React.useCallback(() => {
+    settleRequest(activeRequestRef.current, null);
+  }, [settleRequest]);
+
+  /** 原生 dismiss 真正结束后，再安全切到下一个排队请求。 */
+  const handleDismissComplete = React.useCallback(
+    (requestId: string) => {
+      setState((prev) => {
+        if (prev.activeRequest?.id !== requestId) return prev;
+
+        settleRequest(prev.activeRequest, null);
+        settledRequestIdsRef.current.delete(requestId);
+
+        const [nextRequest, ...restQueue] = prev.queuedRequests;
+        if (!nextRequest) {
+          return {
+            activeRequest: null,
+            queuedRequests: restQueue,
+            open: false,
+          };
+        }
+
+        return {
+          activeRequest: nextRequest,
+          queuedRequests: restQueue,
+          open: true,
+        };
+      });
+    },
+    [settleRequest]
+  );
+
+  /** 确认时 resolve 结果 */
+  const handlePickerConfirm = React.useCallback(
+    (payload: PickerConfirmPayload) => {
+      settleRequest(activeRequestRef.current, {
+        value: payload.value,
+        values: payload.values,
+        label: payload.label,
+        labels: payload.labels,
+        items: payload.items,
+      });
+    },
+    [settleRequest]
+  );
+
+  const handleDateConfirm = React.useCallback(
+    (payload: DatePickerConfirmPayload) => {
+      settleRequest(activeRequestRef.current, {
+        value: payload.value,
+        label: payload.label,
+      });
+    },
+    [settleRequest]
+  );
+
+  const handleAddressConfirm = React.useCallback(
+    (payload: AddressCascaderConfirmPayload) => {
+      settleRequest(activeRequestRef.current, {
+        value: payload.value,
+        values: payload.values,
+        label: payload.label,
+        labels: payload.labels,
+        items: payload.items,
+      });
+    },
+    [settleRequest]
+  );
+
+  const handleBetweenTimeConfirm = React.useCallback(
+    (payload: BetweenTimeConfirmPayload) => {
+      settleRequest(activeRequestRef.current, {
+        value: payload.value,
+      });
+    },
+    [settleRequest]
+  );
+
+  const activeRequest = state.activeRequest;
+  const activeRequestId = activeRequest?.id;
+
+  return (
+    <>
+      {children}
+      {activeRequest?.type === 'picker' && (
+        <Picker
+          key={activeRequest.id}
+          {...activeRequest.options}
+          open={state.open}
+          onOpenChange={handleOpenChange}
+          onConfirm={handlePickerConfirm}
+          onCancel={handleCancel}
+          onDismissComplete={() => {
+            if (activeRequestId) handleDismissComplete(activeRequestId);
+          }}
+        />
+      )}
+      {activeRequest?.type === 'date' && (
+        <DatePicker
+          key={activeRequest.id}
+          {...activeRequest.options}
+          open={state.open}
+          onOpenChange={handleOpenChange}
+          onConfirm={handleDateConfirm}
+          onCancel={handleCancel}
+          onDismissComplete={() => {
+            if (activeRequestId) handleDismissComplete(activeRequestId);
+          }}
+        />
+      )}
+      {activeRequest?.type === 'address' && (
+        <AddressCascader
+          key={activeRequest.id}
+          {...activeRequest.options}
+          open={state.open}
+          onOpenChange={handleOpenChange}
+          onConfirm={handleAddressConfirm}
+          onCancel={handleCancel}
+          onDismissComplete={() => {
+            if (activeRequestId) handleDismissComplete(activeRequestId);
+          }}
+        />
+      )}
+      {activeRequest?.type === 'betweenTime' && (
+        <BetweenTime
+          key={activeRequest.id}
+          {...activeRequest.options}
+          open={state.open}
+          onOpenChange={handleOpenChange}
+          onConfirm={handleBetweenTimeConfirm}
+          onCancel={handleCancel}
+          onDismissComplete={() => {
+            if (activeRequestId) handleDismissComplete(activeRequestId);
+          }}
+        />
+      )}
+    </>
+  );
+}

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type { Theme, ThemeOverride } from './types';
+import { mergeTheme } from './mergeTheme';
+import { getDefaultTheme } from '../config';
+
+type ThemeContextValue = {
+  theme: Theme;
+  getTheme: () => Theme;
+};
+
+// ThemeContext 用于在组件树中向下传递主题对象。
+// 这里提供默认值（getDefaultTheme），这样即使应用侧没有包 ThemeProvider：
+// - useTheme() 也不会返回 undefined
+// - 组件仍能正常渲染（使用组件库默认主题 + 全局配置覆盖）
+export const ThemeContext = React.createContext<ThemeContextValue>({
+  theme: getDefaultTheme(),
+  getTheme: getDefaultTheme,
+});
+
+export type ThemeProviderProps = {
+  // baseTheme 允许应用侧提供“完整主题对象”作为基线（例如某个品牌主题）
+  // 然后再用 theme 进行局部覆盖。
+  baseTheme?: Theme;
+  // theme 是覆盖对象（Partial），只需要传你要改的字段即可
+  theme?: ThemeOverride;
+  children: React.ReactNode;
+};
+
+export function ThemeProvider({ baseTheme, theme, children }: ThemeProviderProps) {
+  const value = React.useMemo(() => {
+    // 优先级（低 -> 高）：
+    // 1) defaultTheme
+    // 2) configureComponentLib({ theme })
+    // 3) ThemeProvider({ baseTheme })
+    // 4) ThemeProvider({ theme })
+    const finalTheme = mergeTheme(baseTheme ?? getDefaultTheme(), theme);
+    return { theme: finalTheme, getTheme: () => finalTheme };
+  }, [baseTheme, theme]);
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}

package/src/theme/defaultTheme.ts

@@ -0,0 +1,30 @@
+import type { Theme } from './types';
+
+// defaultTheme 是组件库的默认主题：
+// - 当应用侧不包 ThemeProvider 时，组件会使用这套默认颜色
+// - 当应用侧包了 ThemeProvider 且只覆盖部分字段时，未覆盖的字段也会从这里补齐
+export const defaultTheme: Theme = {
+  colors: {
+    // 默认主色（偏深色），适合作为按钮等强调元素背景
+    primary: '#111827',
+    // 主色上的文字/图标颜色
+    onPrimary: '#FFFFFF',
+
+    // 默认次要色（浅背景）
+    secondary: '#EEF2FF',
+    // 次要色上的文字/图标颜色
+    onSecondary: '#111827',
+
+    // 默认表面背景（卡片、控件背景）
+    surface: '#FFFFFF',
+    // 表面上的文字/图标颜色
+    onSurface: '#111827',
+
+    // 默认边框色
+    border: '#d9d9d9',
+    // 弱化文字色
+    muted: '#6B7280',
+    // 禁用态颜色（这里复用 muted）
+    disabled: '#6B7280',
+  },
+};

package/src/theme/mergeTheme.ts

@@ -0,0 +1,16 @@
+import type { Theme, ThemeOverride } from './types';
+
+// mergeTheme 用于实现“部分覆盖”体验：
+// - 业务侧只改 colors.primary 时，只需传 { colors: { primary } }
+// - 未覆盖字段回落到 base
+export function mergeTheme(base: Theme, override?: ThemeOverride): Theme {
+  if (!override) return base;
+  return {
+    ...base,
+    ...override,
+    colors: {
+      ...base.colors,
+      ...(override.colors ?? {}),
+    },
+  };
+}

package/src/theme/types.ts

@@ -0,0 +1,36 @@
+// Theme 是组件库内部约定的“主题对象”结构
+// 目前只包含 colors，后续如果需要也可以增加 spacing / radii / typography 等字段
+export type Theme = {
+  colors: {
+    // 组件主色，例如按钮、选中态等强调色
+    primary: string;
+    // 主色上的前景色（通常是文字颜色），要求与 primary 有足够对比度
+    onPrimary: string;
+
+    // 次要色，常用于弱一点的按钮、标签背景等
+    secondary: string;
+    // 次要色上的前景色
+    onSecondary: string;
+
+    // 一般面的背景色（例如卡片、默认控件背景）
+    surface: string;
+    // 一般面上的前景色（例如普通文字颜色）
+    onSurface: string;
+
+    // 边框颜色（输入框边框、分割线等）
+    border: string;
+
+    // 次要文字、提示文字等弱一点的颜色
+    muted: string;
+
+    // 禁用态文字/图标颜色
+    disabled: string;
+  };
+};
+
+// ThemeOverride 用于在应用侧覆盖默认主题：
+// - 可以只传入部分字段（Partial），未传入的会回落到 defaultTheme
+// - colors 也是部分覆盖，便于只改 primary 这类场景
+export type ThemeOverride = Partial<Theme> & {
+  colors?: Partial<Theme['colors']>;
+};

package/src/theme/useTheme.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+import { ThemeContext } from './ThemeProvider';
+
+// useTheme 用于在组件内部读取当前主题
+// - 如果应用侧包了 ThemeProvider：返回合并后的主题
+// - 如果没有包 ThemeProvider：返回 defaultTheme（由 ThemeContext 默认值提供）
+export function useTheme() {
+  const ctx = React.useContext(ThemeContext);
+  return ctx.getTheme?.() ?? ctx.theme;
+}

package/src/types/svg.d.ts

@@ -0,0 +1,9 @@
+// 让 TypeScript 认识 `import Icon from './icon.svg'` 这种写法。
+// 在 React Native + react-native-svg-transformer 的组合下，svg 会被转换成一个 React 组件。
+declare module '*.svg' {
+  import * as React from 'react';
+  import type { SvgProps } from 'react-native-svg';
+  const SvgComponent: React.FC<SvgProps>;
+  export default SvgComponent;
+}
+

package/src/types/vant-area-data.d.ts

@@ -0,0 +1,19 @@
+declare module '@vant/area-data' {
+  export type AreaList = {
+    province_list: Record<string, string>;
+    city_list: Record<string, string>;
+    county_list: Record<string, string>;
+  };
+
+  export const areaList: AreaList;
+
+  export type CascaderNode = {
+    text: string;
+    value: string;
+    children?: CascaderNode[];
+    disabled?: boolean;
+  };
+
+  export function useCascaderAreaData(): CascaderNode[];
+}
+

package/src/ui/Accordion/README.md

@@ -0,0 +1,67 @@
+# Accordion
+
+组合式手风琴/折叠面板，适合设置项、FAQ、表单分组和信息分层。组件默认使用 `value/defaultValue/onChange` 状态模型，支持受控与非受控；动画由 Reanimated shared value 驱动，展开内容、指示器和按压反馈共享同一节奏。
+
+## 基础用法
+
+```tsx
+import * as React from 'react';
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+  Text,
+} from 'zkit-ui';
+
+export function DemoAccordion() {
+  const [value, setValue] = React.useState<string | null>('profile');
+
+  return (
+    <Accordion value={value} onChange={setValue} variant="card" size="md">
+      <AccordionItem value="profile">
+        <AccordionTrigger title="账户资料" description="姓名、头像和公开信息" />
+        <AccordionContent>
+          <Text>这里放账户资料表单。</Text>
+        </AccordionContent>
+      </AccordionItem>
+
+      <AccordionItem value="security">
+        <AccordionTrigger title="安全设置" />
+        <AccordionContent>
+          <Text>这里放密码、多因素认证和设备管理。</Text>
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  );
+}
+```
+
+## 状态模型
+
+- `type="single"` 是默认模式，`value` 为当前打开项或 `null`；默认 `collapsible=true`，再次点击已打开项会收起。
+- `type="multiple"` 时 `value` 为数组，任意项都可独立展开/收起。
+- 受控模式只由外部 `value` 驱动视觉状态；非受控模式使用 `defaultValue` 初始化内部 store。
+
+## 组合插槽
+
+`AccordionTrigger` 提供 `title`、`description`、`leading`、`trailing`、`indicator` 和 `children`。这些插槽都可以传普通节点，也可以传 render prop：
+
+```tsx
+<AccordionTrigger
+  title={({ open }) => (open ? '收起详情' : '展开详情')}
+  indicator={({ open }) => <YourIcon rotate={open ? 180 : 0} />}
+/>
+```
+
+传入 `children` 时会完全接管 trigger 主体内容；`indicator={false}` 可隐藏默认箭头。
+
+## 外观与动画
+
+- `variant`：`card`、`filled`、`plain`
+- `tone`：`neutral`、`primary`、`success`、`warning`、`danger`、`info`
+- `size`：`sm`、`md`、`lg`
+- `animation`：传 `{ duration, easing, reduceMotion }` 覆盖默认动画；传 `false` 关闭动画。
+- `mountStrategy`：`eager` 默认保持内容挂载，`lazy` 首次展开后保持挂载，`unmountOnExit` 收起动画结束后卸载。
+
+所有内置像素尺寸都通过 `wp(...)` 计算。业务侧传入 `itemGap`、`AccordionIndicator size`、`strokeWidth`、自定义 padding 等像素值时也应使用 `wp(...)`。