@unif/react-native-ui 0.4.0 → 1.0.1

package/src/core/portal.tsx

@@ -0,0 +1,144 @@
+import React, {
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useCallback,
+} from 'react';
+import { ThemeContext } from './theme/hooks';
+import { ContextBridgeContext } from './theme/provider';
+import { warning } from './utils/dev';
+
+/** Portal 条目：一个 React 节点 + 唯一标识 */
+type PortalEntry = {
+  key: symbol;
+  node: React.ReactNode;
+};
+
+// ─── 模块级单例 ────────────────────────────────────────────────────────────────
+//
+// PortalHost 在此注册自身的 setState 函数，
+// Portal 从此读取并调用，实现跨层级渲染。
+//
+// 选择模块级单例而非 React Context 的原因：
+// PortalHost 和 Portal 在组件树中通常是兄弟节点（PortalHost 在根部，
+// Portal 在深层子组件中），两者之间没有父子关系，无法通过 Context 传递。
+
+let hostUpdate:
+  | ((fn: (entries: PortalEntry[]) => PortalEntry[]) => void)
+  | null = null;
+// 统计当前挂载的 PortalHost 数量，超过 1 个时发出警告
+let hostCount = 0;
+
+/** 在 PortalHost 中注册一个新的 Portal 节点，返回其唯一 key */
+function mountPortal(node: React.ReactNode): symbol {
+  const key = Symbol();
+  hostUpdate?.((prev) => [...prev, { key, node }]);
+  return key;
+}
+
+/** 按 key 从 PortalHost 中移除 Portal 节点 */
+function unmountPortal(key: symbol): void {
+  hostUpdate?.((prev) => prev.filter((e) => e.key !== key));
+}
+
+/** 按 key 更新 PortalHost 中已存在的 Portal 节点内容 */
+function updatePortal(key: symbol, node: React.ReactNode): void {
+  hostUpdate?.((prev) => prev.map((e) => (e.key === key ? { key, node } : e)));
+}
+
+/**
+ * Portal 的宿主容器，负责渲染所有通过 `<Portal>` 传送来的节点。
+ *
+ * 应放置在应用根部（通常在 ThemeProvider 内部），且全局只挂载一次。
+ * 挂载多个时会发出 DEV 警告。
+ *
+ * 渲染原理：PortalHost 使用 useLayoutEffect 提前注册 hostUpdate，
+ * 确保 Portal 的 useEffect 触发时 hostUpdate 已就绪，节点能正确插入。
+ */
+export function PortalHost() {
+  const [entries, setEntries] = useState<PortalEntry[]>([]);
+
+  // useLayoutEffect 确保注册在 Portal 的 useEffect 之前执行
+  useLayoutEffect(() => {
+    hostCount++;
+    warning(
+      hostCount <= 1,
+      'Multiple PortalHost instances detected. Ensure PortalHost is only mounted once at the app root.'
+    );
+    hostUpdate = setEntries;
+    return () => {
+      hostCount--;
+      // 卸载时仅清空自己注册的 hostUpdate，避免影响后续 PortalHost
+      if (hostUpdate === setEntries) {
+        hostUpdate = null;
+      }
+    };
+  }, []);
+
+  return (
+    <>
+      {entries.map((e) => (
+        <React.Fragment key={String(e.key)}>{e.node}</React.Fragment>
+      ))}
+    </>
+  );
+}
+
+interface PortalProps {
+  children: React.ReactNode;
+}
+
+/**
+ * 将子节点传送到最近的 `<PortalHost>` 渲染，突破组件树层级限制。
+ *
+ * 典型用途：Dialog、Sheet、Toast、Tooltip 等浮层组件，
+ * 需要渲染在 z 轴最顶层（脱离父容器的 overflow/transform 约束）。
+ *
+ * 上下文桥接：Portal 会将当前的 ThemeContext 和 ContextBridgeContext 透传给
+ * 传送过去的节点，确保主题和自定义 Context 在 Portal 内依然可用。
+ *
+ * 生命周期：
+ * - 挂载时：在 PortalHost 中注册节点（mountPortal）
+ * - 每次渲染时：更新节点内容（updatePortal），保持与父组件状态同步
+ * - 卸载时：从 PortalHost 中移除节点（unmountPortal）
+ */
+export function Portal({ children }: PortalProps) {
+  const themeCtx = useContext(ThemeContext);
+  const ContextBridge = useContext(ContextBridgeContext);
+  const keyRef = useRef<symbol | null>(null);
+
+  // 包裹内容：注入 ThemeContext 和自定义 ContextBridge，保证 Portal 内 Context 连续
+  const wrapContent = useCallback(
+    (content: React.ReactNode) => {
+      const inner = (
+        <ThemeContext.Provider value={themeCtx}>
+          {content}
+        </ThemeContext.Provider>
+      );
+      return ContextBridge ? <ContextBridge>{inner}</ContextBridge> : inner;
+    },
+    [themeCtx, ContextBridge]
+  );
+
+  useEffect(() => {
+    const key = mountPortal(wrapContent(children));
+    keyRef.current = key;
+    return () => {
+      unmountPortal(key);
+      keyRef.current = null;
+    };
+    // 仅在挂载/卸载时触发——更新由下方处理
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // 每次渲染时更新 portal 内容（包括 children、themeCtx 等依赖变化时）
+  useEffect(() => {
+    if (keyRef.current) {
+      updatePortal(keyRef.current, wrapContent(children));
+    }
+  });
+
+  return null;
+}

package/src/core/styles/recipe/helpers.ts

@@ -0,0 +1,39 @@
+import type { Tokens } from '../../theme/types';
+import type { SlotMap, SlotStyleOrFactory } from './types';
+
+/** 若样式定义是工厂函数则调用它，否则直接返回 */
+export function evalStyle<S extends SlotMap>(
+  style: SlotStyleOrFactory<S> | ((tokens: Tokens) => S),
+  tokens: Tokens
+): Partial<S> | S {
+  return typeof style === 'function' ? style(tokens) : style;
+}
+
+/**
+ * 浅合并两个 SlotMap：对每个 key 执行对象展开，
+ * patch 中的属性会覆盖 target 中同名属性。
+ */
+export function mergeSlots<S extends SlotMap>(target: S, patch: Partial<S>): S {
+  const result = { ...target };
+  for (const key in patch) {
+    result[key as keyof S] = {
+      ...(result[key as keyof S] as object),
+      ...(patch[key] as object),
+    } as S[keyof S];
+  }
+  return result;
+}
+
+/**
+ * 构建变体缓存键：将所有变体 key 的当前值（含 defaults 回退）
+ * 拼接为 "|" 分隔的字符串，用于 Map 索引。
+ */
+export function buildCacheKey(
+  variantKeys: readonly string[],
+  props: Record<string, unknown>,
+  defaults: Record<string, unknown>
+): string {
+  return variantKeys
+    .map((k) => String(props[k] ?? defaults[k] ?? ''))
+    .join('|');
+}

package/src/core/styles/recipe/index.ts

@@ -0,0 +1,155 @@
+import { lightTokens } from '../../theme/tokens';
+import type { Tokens } from '../../theme/types';
+import type {
+  SlotMap,
+  RecipeConfig,
+  Recipe,
+  SlotStyleOrFactory,
+} from './types';
+import { evalStyle, mergeSlots, buildCacheKey } from './helpers';
+
+/**
+ * 创建一个样式配方（Recipe）实例。
+ *
+ * Recipe 封装了"多变体样式合并"逻辑，流程如下：
+ * 1. 从 base 计算基础样式
+ * 2. 按各变体 key 的当前值叠加对应变体样式
+ * 3. 检查 compoundVariants，满足所有条件的额外叠加
+ * 4. 将结果冻结并写入 WeakMap 缓存（tokens 变化时缓存自动失效）
+ *
+ * @param config RecipeConfig 配置
+ * @returns 冻结的 Recipe 实例
+ */
+export function recipe<S extends SlotMap>(config: RecipeConfig<S>): Recipe<S> {
+  // 用 lightTokens 预计算 base 的插槽 key 列表（工厂函数需要一次示例调用）
+  const baseSlots =
+    typeof config.base === 'function'
+      ? config.base(lightTokens)
+      : (config.base as S);
+  const slotKeys = Object.freeze(
+    Object.keys(baseSlots)
+  ) as readonly (keyof S)[];
+  const variantKeys = Object.freeze(
+    Object.keys(config.variants ?? {})
+  ) as readonly string[];
+  const defaults = Object.freeze(config.defaults ?? {}) as Readonly<
+    Record<string, unknown>
+  >;
+
+  // 两级缓存：WeakMap<tokens, Map<cacheKey, frozenResult>>
+  // tokens 对象被 GC 时自动释放，避免内存泄漏
+  const cache = new WeakMap<Tokens, Map<string, S>>();
+
+  function resolveWith(props: Record<string, unknown>, tokens: Tokens): S {
+    const cacheKey = buildCacheKey(variantKeys, props, defaults);
+    let tokenCache = cache.get(tokens);
+    if (!tokenCache) {
+      tokenCache = new Map();
+      cache.set(tokens, tokenCache);
+    }
+    const cached = tokenCache.get(cacheKey);
+    if (cached) return cached;
+
+    // 第一步：base 样式
+    let result: S = evalStyle(config.base, tokens) as S;
+
+    // 第二步：逐个变体叠加
+    for (const k of variantKeys) {
+      const effectiveValue = String(props[k] ?? defaults[k] ?? '');
+      if (!effectiveValue) continue;
+      const variantMap = config.variants?.[k];
+      if (!variantMap) continue;
+      const variantStyle = variantMap[effectiveValue];
+      if (variantStyle == null) continue;
+      result = mergeSlots(result, evalStyle(variantStyle, tokens));
+    }
+
+    // 第三步：compoundVariants（所有条件同时满足时才应用）
+    for (const cv of config.compoundVariants ?? []) {
+      const { style, ...conditions } = cv;
+      const matches = Object.entries(conditions).every(([k, v]) => {
+        const effective = props[k] ?? defaults[k];
+        return Array.isArray(v) ? v.includes(effective) : effective === v;
+      });
+      if (matches) {
+        result = mergeSlots(
+          result,
+          evalStyle(style as SlotStyleOrFactory<S>, tokens)
+        );
+      }
+    }
+
+    // 深度冻结结果：防止外部意外修改，同时便于 ESLint 的 no-mutating-styles 检查
+    const frozen = Object.freeze(
+      Object.fromEntries(
+        Object.entries(result).map(([k, v]) => [k, Object.freeze(v)])
+      )
+    ) as S;
+    tokenCache.set(cacheKey, frozen);
+    return frozen;
+  }
+
+  /**
+   * 继承当前 recipe 并扩展配置，常用于主题定制或组件变体扩展。
+   * 新 recipe 的变体键为原有键 + 新增键的并集，base 和 variants 按插槽深度合并。
+   */
+  function extendRecipe(extConfig: Partial<RecipeConfig<S>>): Recipe<S> {
+    const newVariantKeys = Object.keys(extConfig.variants ?? {}).filter(
+      (k) => !variantKeys.includes(k)
+    );
+    const mergedVariantKeys = [...variantKeys, ...newVariantKeys];
+
+    const mergedConfig: RecipeConfig<S> = {
+      defaults: { ...defaults, ...(extConfig.defaults ?? {}) },
+      base:
+        extConfig.base != null
+          ? typeof config.base === 'function'
+            ? (t: Tokens) =>
+                mergeSlots(
+                  (config.base as (tokens: Tokens) => S)(t),
+                  evalStyle(extConfig.base!, t)
+                )
+            : (t: Tokens) =>
+                mergeSlots(config.base as S, evalStyle(extConfig.base!, t))
+          : config.base,
+      variants: {
+        ...config.variants,
+        ...Object.fromEntries(
+          Object.entries(extConfig.variants ?? {}).map(([k, v]) => [
+            k,
+            { ...((config.variants as any)?.[k] ?? {}), ...v },
+          ])
+        ),
+      } as RecipeConfig<S>['variants'],
+      compoundVariants: [
+        ...(config.compoundVariants ?? []),
+        ...(extConfig.compoundVariants ?? []),
+      ],
+      interactions: {
+        ...(config.interactions ?? {}),
+        ...(extConfig.interactions ?? {}),
+      },
+    };
+
+    const ext = recipe(mergedConfig);
+    // 手动修正 variantKeys 为合并后的列表（recipe() 内部只能看到 mergedConfig 的 variants）
+    (ext as any).variantKeys = Object.freeze(mergedVariantKeys);
+    return ext;
+  }
+
+  return Object.freeze({
+    slotKeys,
+    variantKeys,
+    defaults,
+    resolve: resolveWith,
+    extend: extendRecipe,
+  });
+}
+
+export type {
+  SlotMap,
+  RecipeConfig,
+  Recipe,
+  VariantProps,
+  SlotStyles,
+} from './types';

package/src/core/styles/recipe/types.ts

@@ -0,0 +1,97 @@
+import type { ViewStyle, TextStyle, ImageStyle } from 'react-native';
+import type { Tokens } from '../../theme/types';
+
+/**
+ * SlotMap：样式插槽的映射类型。
+ * Key 为插槽名称（如 `root`、`label`、`icon`），Value 为对应的 RN 样式类型。
+ * 每个组件通过定义 SlotMap 来声明自己有哪些可样式化的部分。
+ */
+export type SlotMap = Record<string, ViewStyle | TextStyle | ImageStyle>;
+
+/**
+ * 单个变体的样式定义：可以是静态的 Partial<S>，
+ * 也可以是接收 tokens 并返回样式的工厂函数（动态颜色/间距）。
+ */
+export type SlotStyleOrFactory<S extends SlotMap> =
+  | Partial<S>
+  | ((tokens: Tokens) => Partial<S>);
+
+/** 变体定义：key 为变体名（如 "visual"），value 为各取值对应的样式 */
+export type VariantDef<S extends SlotMap> = {
+  [variantKey: string]: {
+    [variantValue: string]: SlotStyleOrFactory<S> | null;
+  };
+};
+
+/**
+ * recipe() 的配置项。
+ *
+ * 设计思路参考 Vanilla Extract `recipe`：
+ * - `base`：所有变体共享的基础样式
+ * - `variants`：按 prop key/value 索引的变体样式，支持多维度组合
+ * - `compoundVariants`：多个变体同时满足条件时应用的额外样式
+ * - `interactions`：按压/涟漪等交互状态样式（待组件层消费）
+ */
+export interface RecipeConfig<
+  S extends SlotMap,
+  V extends VariantDef<S> = VariantDef<S>
+> {
+  /** 各变体的默认值（组件未传对应 prop 时使用） */
+  defaults?: Partial<Record<string, unknown>>;
+  /** 基础样式：所有变体共享，可为静态对象或 token 工厂函数 */
+  base: ((tokens: Tokens) => S) | Partial<S>;
+  /** 变体样式映射 */
+  variants?: V;
+  /**
+   * 复合变体：当多个变体同时满足特定条件时叠加的额外样式。
+   * 例如：size=sm 且 visual=outline 时额外减小 padding。
+   */
+  compoundVariants?: Array<{
+    style: SlotStyleOrFactory<S>;
+    [key: string]: unknown;
+  }>;
+  /** 交互状态样式（供按钮等可交互组件使用） */
+  interactions?: {
+    pressed?: SlotStyleOrFactory<S>;
+    androidRipple?: (tokens: Tokens) => { color: string; borderless?: boolean };
+  };
+}
+
+/**
+ * Recipe 实例接口：由 `recipe()` 工厂函数返回。
+ *
+ * 核心方法 `resolve(props, tokens)` 根据传入的 props 和当前主题 tokens
+ * 计算出最终合并后的样式对象，结果会被 WeakMap 缓存。
+ */
+export interface Recipe<S extends SlotMap = SlotMap> {
+  /** 插槽名称列表，用于验证用户传入的自定义样式是否合法 */
+  readonly slotKeys: readonly (keyof S)[];
+  /** 变体 key 列表 */
+  readonly variantKeys: readonly string[];
+  /** 默认变体值 */
+  readonly defaults: Readonly<Record<string, unknown>>;
+  /**
+   * 根据 props 和 tokens 解析最终样式。
+   * 结果按 `tokens` 对象为外层 key、`variantCacheKey` 为内层 key 两级缓存，
+   * tokens 引用不变时命中缓存，无需重新计算。
+   */
+  resolve(props: Record<string, unknown>, tokens: Tokens): S;
+  /** 继承当前 recipe 并扩展/覆盖部分配置，返回新的 Recipe 实例 */
+  extend(config: Partial<RecipeConfig<S>>): Recipe<S>;
+}
+
+/**
+ * 从 Recipe 类型中提取变体 Props 类型。
+ * 实际返回 `Record<string, unknown>`——后续可通过更精确的映射收窄。
+ */
+export type VariantProps<R extends Recipe<any>> = R extends Recipe<any>
+  ? Record<string, unknown>
+  : never;
+
+/**
+ * 从 Recipe 类型中提取解析后的 SlotMap 类型（即 `resolve()` 的返回类型）。
+ * 用于组件内部声明样式变量的类型。
+ */
+export type SlotStyles<R extends Recipe<any>> = R extends Recipe<infer S>
+  ? S
+  : never;

package/src/core/styles/useStyles.ts

@@ -0,0 +1,43 @@
+import { useContext } from 'react';
+import type { Recipe, SlotMap } from './recipe';
+import { ThemeContext } from '../theme/hooks';
+
+/**
+ * 从 Recipe 解析当前主题下的样式，并可选地与用户自定义样式合并。
+ *
+ * 用法示例：
+ * ```tsx
+ * const s = useStyles(buttonRecipe, { visual, size }, styles);
+ * // s.root / s.label / s.icon 即为最终合并后的样式对象
+ * ```
+ *
+ * 合并规则：`recipe.resolve(props, tokens)` 的基础样式 + 用户 `styles[slot]`，
+ * 用户样式的同名属性会覆盖基础样式。
+ *
+ * @param r       Recipe 实例（由 `recipe()` 创建）
+ * @param props   传递给 Recipe 的变体 props（如 `{ visual: 'outline', size: 'sm' }`）
+ * @param styles  用户自定义的插槽样式覆盖（可选）
+ * @returns       按插槽名索引的最终样式对象
+ */
+export function useStyles<S extends SlotMap>(
+  r: Recipe<S>,
+  props: Record<string, unknown> = {},
+  styles?: Partial<S>
+): S {
+  const { tokens } = useContext(ThemeContext);
+  // recipe.resolve 内部有 WeakMap 缓存，tokens 和 props 不变时直接返回缓存结果
+  const resolved = r.resolve(props, tokens);
+
+  // 无自定义样式时直接返回缓存的 resolved，避免额外对象分配
+  if (!styles) return resolved;
+
+  // 按插槽逐一合并，用户样式覆盖 recipe 基础样式
+  const merged = {} as S;
+  for (const key of r.slotKeys) {
+    const k = key as string;
+    const base = (resolved as any)[k];
+    const override = (styles as any)[k];
+    (merged as any)[k] = override ? { ...base, ...override } : base;
+  }
+  return merged;
+}

package/src/core/theme/animationClock.tsx

@@ -0,0 +1,48 @@
+import React, { createContext, useContext, useMemo } from 'react';
+
+interface AnimationClockContextValue {
+  /**
+   * ThemeProvider 首次挂载时的时间戳（毫秒，来自 Date.now()）。
+   * Skeleton 使用此值计算 animationDelay 以同步闪烁相位。
+   */
+  mountedAt: number;
+}
+
+/**
+ * 动画时钟 Context：提供 ThemeProvider 的挂载时间戳。
+ *
+ * 默认值为 0，表示 Context 尚未被提供（应始终包裹在 AnimationClockProvider 内使用）。
+ */
+export const AnimationClockContext = createContext<AnimationClockContextValue>({
+  mountedAt: 0,
+});
+
+/**
+ * 动画时钟 Provider：记录首次挂载的时间戳并注入到子树。
+ *
+ * 由 ThemeProvider 在内部自动包裹，无需应用层手动使用。
+ * `mountedAt` 通过 useMemo([], []) 固定为首次渲染时刻，
+ * ThemeProvider 重渲染时不会更新，确保 Skeleton 等组件的动画延迟计算稳定。
+ */
+export function AnimationClockProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  // 空依赖数组确保 mountedAt 仅在组件首次挂载时计算一次
+  const value = useMemo(() => ({ mountedAt: Date.now() }), []);
+
+  return (
+    <AnimationClockContext.Provider value={value}>
+      {children}
+    </AnimationClockContext.Provider>
+  );
+}
+
+/**
+ * 获取当前的动画时钟数据（mountedAt 时间戳）。
+ * 供 Skeleton 等需要同步动画相位的组件使用。
+ */
+export function useAnimationClock(): AnimationClockContextValue {
+  return useContext(AnimationClockContext);
+}

package/src/core/theme/createTheme.ts

@@ -0,0 +1,77 @@
+import { lightTokens, darkTokens } from './tokens';
+import type { Theme, Tokens, CreateThemeInput } from './types';
+
+/**
+ * 根据基础圆角值派生全套圆角 token。
+ * 所有圆角均以同一个 `base` 值为基准按比例缩放，
+ * 保证设计系统内圆角风格的一致性。
+ *
+ * @param base 基础圆角（px），默认为 6
+ */
+function deriveRadius(base: number) {
+  return {
+    radiusSm: Math.round(base * 0.5), // 最小圆角
+    radius: base, // 默认圆角
+    radiusMd: Math.round(base * 1.33), // 中等圆角
+    radiusLg: Math.round(base * 1.67), // 大圆角
+    radiusXl: Math.round(base * 2), // 超大圆角
+    radiusFull: 999, // 完全圆（胶囊形）
+  };
+}
+
+/**
+ * 将覆盖值合并到 base tokens，并在必要时重新派生圆角 token 组。
+ * 结果对象被冻结（Object.freeze），防止在 Provider 外被意外修改。
+ *
+ * @param base      基础 token（lightTokens 或 darkTokens）
+ * @param overrides 需要覆盖的 token 子集
+ */
+function buildTokens(base: Tokens, overrides: Partial<Tokens>): Tokens {
+  const merged = { ...base, ...overrides };
+  // 若 radius 被覆盖，重新派生所有圆角 token（保持一致性）
+  if (overrides.radius !== undefined) {
+    Object.assign(merged, deriveRadius(overrides.radius));
+  }
+  return Object.freeze(merged) as Tokens;
+}
+
+/**
+ * 根据品牌覆盖值创建 Theme（亮色 + 暗色 token 对）。
+ *
+ * 必须在模块顶层调用（不可在组件内部调用），
+ * 因为 Object.freeze 的结果应在组件渲染前确定，
+ * 避免每次渲染重新创建对象导致 ThemeProvider 不必要的重渲染。
+ *
+ * 使用示例：
+ * ```ts
+ * const myTheme = createTheme({ primary: '#6366f1', radius: 8 });
+ * // 传入 ThemeProvider：<ThemeProvider theme={myTheme}>
+ * ```
+ *
+ * @param input 品牌定制输入，支持主色、暗色主色覆盖、基础圆角
+ * @returns     包含 light 和 dark 两套冻结 token 的 Theme 对象
+ */
+export function createTheme(input: CreateThemeInput): Theme {
+  const lightOverrides: Partial<Tokens> = {};
+  const darkOverrides: Partial<Tokens> = {};
+
+  if (input.primary !== undefined) {
+    // 亮色主色覆盖；暗色主色若未单独指定则沿用亮色主色
+    lightOverrides.primary = input.primary;
+    darkOverrides.primary = input.dark?.primary ?? input.primary;
+  } else if (input.dark?.primary !== undefined) {
+    // 仅覆盖暗色主色（亮色保持默认）
+    darkOverrides.primary = input.dark.primary;
+  }
+
+  if (input.radius !== undefined) {
+    // 圆角同时应用于亮色和暗色（圆角与颜色模式无关）
+    lightOverrides.radius = input.radius;
+    darkOverrides.radius = input.radius;
+  }
+
+  return {
+    light: buildTokens(lightTokens, lightOverrides),
+    dark: buildTokens(darkTokens, darkOverrides),
+  };
+}