@apollo-design/theme 0.0.0-stage → 0.1.9

package/dist/get-design-token.mjs

@@ -0,0 +1,42 @@
+import compactAlgorithm from './algorithms/compact.mjs';
+import darkAlgorithm from './algorithms/dark.mjs';
+import defaultAlgorithm from './algorithms/default.mjs';
+import formatToken from './alias.mjs';
+import { defaultSeedToken } from './seed.mjs';
+
+const algorithms = {
+  default: defaultAlgorithm,
+  dark: darkAlgorithm,
+  compact: compactAlgorithm
+};
+function resolveThemeAppearance(config, system = "light") {
+  const explicit = Array.isArray(config.algorithm) ? config.algorithm : config.algorithm ? [config.algorithm] : void 0;
+  if (explicit) {
+    for (const algorithm of [...explicit].reverse()) {
+      if (algorithm === darkAlgorithm) return "dark";
+      if (algorithm === defaultAlgorithm) return "light";
+    }
+    if (explicit.length === 0 || explicit.includes(compactAlgorithm)) return "light";
+  }
+  return config.mode === "system" ? system : config.mode ?? "light";
+}
+function getDesignToken(config = {}, systemAppearance = "light") {
+  const appearance = resolveThemeAppearance(config, systemAppearance);
+  const scheme = config.preset?.[appearance];
+  const algorithm = config.algorithm ?? scheme?.algorithm ?? (appearance === "dark" ? darkAlgorithm : defaultAlgorithm);
+  const list = Array.isArray(algorithm) ? algorithm : [algorithm];
+  const [first = defaultAlgorithm, ...following] = list;
+  const overrides = Object.fromEntries(
+    [config.preset?.token, scheme?.token, config.token].flatMap(
+      (layer) => Object.entries(layer ?? {}).filter(([, value]) => value !== void 0)
+    )
+  );
+  const seed = { ...defaultSeedToken, ...overrides };
+  const derivativeToken = following.reduce(
+    (result, fn) => fn(seed, result),
+    first(seed, void 0)
+  );
+  return formatToken({ ...derivativeToken, override: overrides });
+}
+
+export { algorithms, compactAlgorithm, darkAlgorithm, defaultAlgorithm, getDesignToken, resolveThemeAppearance };

package/dist/index.d.mts

@@ -0,0 +1,360 @@
+import { M as MapToken, A as AliasToken, S as SeedToken, T as ThemeConfig, a as ThemeAppearance, P as PresetColorKey, b as PresetColorType, C as ColorPalette, c as ColorNeutralMapToken, d as ColorMapToken, e as CommonMapToken, f as StyleMapToken, H as HeightMapToken, F as FontMapToken, g as SizeMapToken } from './shared/theme.DBaLDtcj.mjs';
+export { h as ComponentTokenMap, G as GlobalToken, i as MappingAlgorithm, j as PresetColorPalettes, k as ThemeMode, l as ThemePreset, m as ThemePresetScheme, n as ThemeTokenOverrides } from './shared/theme.DBaLDtcj.mjs';
+import * as vue from 'vue';
+import { Ref, ComputedRef, InjectionKey, PropType, SlotsType, VNodeChild } from 'vue';
+
+/** formatToken 的输入：Map token 上额外挂一个 `override`（来自 ThemeConfig.token） */
+type DerivativeTokenWithOverride = MapToken & {
+    /**
+     * 允许 `undefined`：`ThemeConfig.token` 是 `Partial<...>`，
+     * 显式的 `{ colorPrimary: undefined }` 是合法输入，语义上等于没传。
+     */
+    override?: Partial<AliasToken & Record<string, string | number | boolean>>;
+};
+/**
+ * Map → Alias。
+ *
+ * `override` 的处理顺序有个容易搞错的地方：
+ *   - `override` 里**属于 Seed 的键**会被丢弃（它们已经在 Seed 阶段合并过了）
+ *   - 剩下的非 Seed 键在**最后**再覆盖一次（见函数末尾的 `...overrideTokens`）
+ * 所以非 Seed 的 override 会盖掉 alias 的派生结果。这是 antd 的契约：
+ * 用户传 `colorPrimaryBg` 应当生效，而不是被 `colorPrimaryBorder` 的派生值盖回去。
+ */
+declare function formatToken(derivativeToken: DerivativeTokenWithOverride): AliasToken;
+
+/** 共享变量默认前缀；自定义前缀需由对应样式消费。 */
+declare const DEFAULT_CSS_VAR_PREFIX = "apollo";
+/**
+ * 这些 token 虽然是 number，但**不加 px**。
+ *
+ * 初始清单参考 antd 6.6.4 的 `es/theme/useToken.js`；单位由当前 Token 契约决定。
+ */
+declare const UNITLESS: Record<string, true>;
+/** 不产出 CSS 变量的 token（antd 的 `ignore`） */
+declare const IGNORE: Record<string, true>;
+/** 保留原值、不转成 var() 引用的 token（antd 的 `preserve`，即断点值） */
+declare const PRESERVE: Record<string, true>;
+/**
+ * token 名 → CSS 变量名。
+ *
+ * 三段 replace 的顺序不能调换，也不能合并成一个"更聪明"的正则。
+ * 逐字来自 `@ant-design/cssinjs` 的 `util/css-variables.js`：
+ *
+ *   1. `([a-z0-9])([A-Z])`   → 常规 camelCase 边界     colorPrimary → color-Primary
+ *   2. `([A-Z]+)([A-Z][a-z0-9]+)` → 连续大写后的边界   XSMax → XS-Max
+ *   3. `([a-z])([A-Z0-9])`   → 小写接单个大写或数字     sizeLG → size-LG
+ *
+ * 结果整体小写。例：`borderRadiusLG` → `--apollo-border-radius-lg`。
+ * CSS 变量名是对外契约，静态 CSS 和运行时注入必须使用同一名称。
+ */
+declare function token2CSSVar(token: string, prefix?: string): string;
+interface TransformResult {
+    /** CSS 变量名 → 值（number 且非 unitless 的会带 px） */
+    vars: Record<string, string>;
+    /**
+     * token 名 → `var(--xxx)`。
+     * `preserve` 命中的 token 保留**原始类型**（与 cssinjs 一致：断点值仍是 number，
+     * 因为组件要拿它做 JS 里的比较，不能变成字符串）。
+     */
+    refs: Record<string, string | number>;
+}
+/**
+ * 把 token 对象拆成「变量声明表」与「引用表」。
+ *
+ * 只处理 string / number —— boolean（wireframe / motion / focusOutline）不产出变量，
+ * 因为 CSS 里没有对应的消费方式，且它们只影响派生过程。
+ */
+declare function transformToken(token: Partial<AliasToken>, prefix?: string): TransformResult;
+/**
+ * 零运行时路径：产出一段可直接落盘的 CSS。
+ *
+ * 例：`getCSSVarDeclarations(token)` → `:root{--apollo-color-primary:#1677ff;...}`
+ *     `getCSSVarDeclarations(token, { selector: '[data-apollo-theme=dark]' })` → 作用域覆盖
+ */
+declare function getCSSVarDeclarations(token: Partial<AliasToken>, options?: {
+    prefix?: string;
+    selector?: string;
+}): string;
+/**
+ * 运行时注入路径（开放决策 zero-runtime-mode = B：零运行时是默认，但不是唯一）。
+ *
+ * 与静态路径**共用同一套变量命名**（transformToken），否则两条路径会分叉 ——
+ * 静态 CSS 写 `--apollo-x`、运行时写别的名字，组件样式就会拿到空值。
+ *
+ * 实现方式走 `CSSStyleDeclaration.setProperty`，不引入任何 CSS-in-JS 运行时：
+ * 本包不生成样式表、不生成 hash 类名，只写自定义属性。
+ */
+interface CSSVarScope {
+    /** 把 token 写入目标元素（重复调用覆盖同名变量，不残留） */
+    apply: (token: Partial<AliasToken>) => void;
+    /** 释放本 scope 的变量，恢复仍活跃的 scope 或原有 inline 值 */
+    remove: () => void;
+    /** 当前已写入的变量名 */
+    readonly keys: string[];
+}
+declare function createCSSVarScope(el: HTMLElement | SVGElement, prefix?: string): CSSVarScope;
+/** 一次性写入（无后续移除需求的场景，如 SSR 后的客户端挂载） */
+declare function applyCSSVar(el: HTMLElement | SVGElement, token: Partial<AliasToken>, prefix?: string): void;
+
+/**
+ * 紧凑模式派生算法。
+ *
+ * 两个要点：
+ *  1. **基础字号换成 `fontSizeSM`** —— 紧凑不只是缩间距，连字号的指数表起点都变了
+ *  2. **基础控件高度 -4**，然后重新派生三档
+ *
+ * `genCompactSizeMapToken(mapToken ?? token)` 的参数选择很关键：
+ * antd 传的是**原始 seed**（当有 mapToken 时）而不是 mapToken 本身。
+ * 因为紧凑梯度只需要 sizeUnit / sizeStep 两个 seed 值，用 mapToken 也一样 ——
+ * 但为了逐位一致，这里保持与 antd 相同的取参。
+ */
+declare function compactAlgorithm(token: SeedToken, mapToken?: MapToken): MapToken;
+
+/**
+ * 暗色派生算法。
+ *
+ * 与 default 的关键差异（每一条都影响取值，不能省）：
+ *  1. 功能色用 `generate(base, { theme: 'dark' })`，且 5/6/7 档反转
+ *  2. 中性色的默认基色是 #000 / #fff，且用 lighten 而不是 darken
+ *  3. 预设色的 Hover/Active **对调**：Hover 取第 7 档、Active 取第 5 档（亮色是 5/7）
+ *  4. `colorPrimaryBg` / `colorPrimaryBgHover` 被覆写为 Border 档位
+ *     （antd issue #30524：暗色下选中的背景色要更实）
+ *
+ * `mapToken` 为 undefined 时自己先跑一遍 default —— 这是 `Theme.getDerivativeToken`
+ * reduce 的第一步，保证 dark 可以单独使用也能作为链首。
+ */
+declare function darkAlgorithm(token: SeedToken, mapToken?: MapToken): MapToken;
+
+/**
+ * 默认（亮色）派生算法。
+ *
+ * 签名 `(token, mapToken)` 里的第二个参数在 default 上用不到
+ * （default 永远是链首），但必须保留：三个算法共享 `MappingAlgorithm` 类型，
+ * 由 `getDesignToken` 用 reduce 串联。
+ */
+declare function defaultAlgorithm(token: SeedToken): MapToken;
+
+/**
+ * 三个算法。
+ *
+ * 可组合：`algorithm: [darkAlgorithm, compactAlgorithm]` —— 顺序有意义，
+ * 后者在前者结果上继续派生（antd 的 `Theme.getDerivativeToken` 是 reduce）。
+ */
+declare const algorithms: {
+    readonly default: typeof defaultAlgorithm;
+    readonly dark: typeof darkAlgorithm;
+    readonly compact: typeof compactAlgorithm;
+};
+declare function getDesignToken(config?: ThemeConfig, systemAppearance?: ThemeAppearance): AliasToken;
+
+/** Merge configuration, never a previously expanded preset or derived AliasToken. */
+declare function mergeThemeConfig(parent: ThemeConfig | undefined, own: ThemeConfig | undefined): ThemeConfig | undefined;
+
+/**
+ * antd 的 13 个预设色。
+ *
+ * 注意 `pink` 与 `magenta` 同值 —— pink 是 magenta 的废弃别名，保留是为了兼容。
+ * 派生时会为 pink 单独生成一套 `pink-1..10`，与 magenta 完全重复，这是 antd 的行为。
+ */
+declare const PresetColors: PresetColorKey[];
+declare const defaultPresetColors: PresetColorType;
+/**
+ * antd 6.6.4 的 Seed Token 默认值（34 个，不含 13 个预设色）。
+ *
+ * `colorLink` / `colorTextBase` / `colorBgBase` 默认为空串 —— 空串是**有意义的**：
+ * 派生时 `colorLink` 空串会回落到 `colorInfo`，`colorTextBase` / `colorBgBase` 空串会
+ * 在 default 与 dark 里落到不同的默认值（#fff/#000 与 #000/#fff）。
+ * 因此**不能**把它们改成 undefined 或删掉，否则会丢失这个分支。
+ */
+declare const defaultSeedToken: SeedToken;
+
+/** 中性色派生的签名。default 与 dark 各实现一份。 */
+type GenerateNeutralColorPalettes = (bgBaseColor: string, textBaseColor: string, shadowColor?: string) => ColorNeutralMapToken;
+/**
+ * 由 Seed 派生全部功能色与中性色。
+ *
+ * `generateColorPalettes` / `generateNeutralColorPalettes` 由具体算法（default / dark）注入。
+ * 这个「注入」不是过度设计：dark 与 default 的**取档顺序不同**（dark 的 5/6/7 是 6/5/4），
+ * 且中性色的默认值与公式都不同。抽出来才保证两者共用同一套键集合。
+ */
+declare function genColorMapToken(seed: SeedToken, options: {
+    generateColorPalettes: (baseColor: string) => ColorPalette;
+    generateNeutralColorPalettes: GenerateNeutralColorPalettes;
+}): ColorMapToken;
+
+/**
+ * 动效时长与线宽、圆角的公共派生。
+ *
+ * `toFixed(1)` 不能省：motionUnit = 0.1 时 `0 + 0.1 * 3` 在浮点下是 0.30000000000000004，
+ * 直接模板化会得到 `0.30000000000000004s`。antd 用 toFixed(1) 规避，我们同。
+ */
+declare function genCommonMapToken(token: Pick<SeedToken, 'motionUnit' | 'motionBase' | 'borderRadius' | 'lineWidth'>): CommonMapToken & {
+    lineWidthBold: number;
+} & Omit<StyleMapToken, 'lineWidthBold'>;
+
+/**
+ * 由基础控件高度派生三档。
+ *
+ * 结果是**浮点数**（0.75 / 0.5 / 1.25 倍），不是取整后的整数 ——
+ * antd 直接把它们写进 CSS，浏览器负责亚像素渲染。取整会改变视觉基线。
+ */
+declare function genControlHeight(controlHeight: number): Omit<HeightMapToken, 'controlHeight'>;
+
+/**
+ * 由基础字号派生 17 个字体 Map Token。
+ *
+ * 注意 `fontSizeXL` 与 `fontSizeHeading4` 同值（都取 fontSizes[3]）、
+ * `fontSizeLG` 与 `fontSizeHeading5` 同值（fontSizes[2]）—— 这不是笔误，
+ * antd 就是这么定义的，改成不同的值会让 DOM 契约与视觉基线同时漂移。
+ */
+declare function genFontMapToken(fontSize: number): FontMapToken;
+
+interface FontSizePair {
+    size: number;
+    lineHeight: number;
+}
+/**
+ * 10 档，定长元组而**不是** `FontSizePair[]`。
+ *
+ * 为什么必须是元组：仓库开了 `noUncheckedIndexedAccess`，
+ * 用数组的话 `pairs[6].size` 的类型是 `number | undefined`，下游要么加 `!`（掩盖真实风险），
+ * 要么到处写兜底分支（覆盖率里出现不可达代码）。定长元组让"一定有 10 档"这件事进入类型系统。
+ */
+type FontSizePairs = readonly [
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair,
+    FontSizePair
+];
+declare function getLineHeight(fontSize: number): number;
+/**
+ * 以 base 为基准生成 10 档字号。
+ *
+ * 公式来源见 antd 注释里引用的 https://zhuanlan.zhihu.com/p/32746810（指数分级）。
+ * 三个细节不能改：
+ *   - `index > 1` 用 floor、否则用 ceil（保证比 base 小的那一档不会塌成 0）
+ *   - 结果统一取偶（`Math.floor(intSize / 2) * 2`）
+ *   - **第 2 档强制等于 base**，抵消取整误差。非整数 base（如 12.5）时这一条才会显出差别：
+ *     ceil(12.5) → 13 → 取偶 → 12，强制回填后才回到 12.5。
+ */
+declare function genFontSizes(base: number): FontSizePairs;
+
+/**
+ * 求「前景色叠在背景色上，视觉等价于某个不透明色」的那个不透明色。
+ *
+ * antd 用它把「半透明前景」反解成「实色 + alpha」，供不支持透明的场景使用。
+ *
+ * 算法是从 0.01 起以 0.01 步长暴力搜索第一个能让 RGB 都落在 [0,255] 的 alpha。
+ * 这是 O(100) 的循环，不是解析解 —— 改写成闭式解会改变取值（因为 antd 的搜索
+ * 顺序决定了「第一个满足」是哪一个），所以必须逐字保留。
+ *
+ * 短路条件：`originAlpha < 1` 时直接返回原色（已经是半透明，无需再解）。
+ */
+declare function getAlphaColor(frontColor: string, backgroundColor: string): string;
+
+/**
+ * 由基础圆角派生 5 档圆角。
+ *
+ * 这些断点（5/6/7/8/14/16）是 antd 的设计经验值，没有公式 —— 只能逐段照抄。
+ * 因此每个分支都被 `radius-2 / radius-7 / radius-16` 等基准用例覆盖，
+ * 改任何一个数字都会让基准比对失败。
+ */
+declare function genRadius(radiusBase: number): Omit<StyleMapToken, 'lineWidthBold'>;
+
+/**
+ * 默认尺寸梯度（9 档）。
+ *
+ * 注意 `sizeMS` 与 `size` 同值 —— antd 的冗余定义，保留。
+ */
+declare function genSizeMapToken(token: Pick<SeedToken, 'sizeUnit' | 'sizeStep'>): SizeMapToken;
+/**
+ * 紧凑模式的尺寸梯度。
+ *
+ * 与默认的区别不只是整体缩小：`sizeMD` 与 `sizeLG` 同值、`size` 与 `sizeSM` 同值、
+ * `sizeXS` 与 `sizeXXS` 同值。这是 antd 紧凑模式的设计取舍（合并相邻档位），
+ * 不能用「默认梯度整体减 2」代替。
+ */
+declare function genCompactSizeMapToken(token: Pick<SeedToken, 'sizeUnit' | 'sizeStep'>): SizeMapToken;
+
+/**
+ * Vue 绑定层。
+ *
+ * 分文件是为了让「纯函数派生」与「Vue 接线」在**源码层**可分辨：
+ * `getDesignToken` 及其依赖不 import vue，读代码时能一眼看出派生链是框架无关的。
+ *
+ * 公共根入口同时导出 Vue 绑定，Vue 已声明为 peerDependency。
+ * 发布构建保留模块，不在这里承诺一个未声明的独立纯函数子路径。
+ */
+interface ThemeContext {
+    /** 当前生效的 ThemeConfig（可写，用于运行时换主题） */
+    config: Ref<ThemeConfig>;
+    /** 完整 token（随 config 变化重算） */
+    token: ComputedRef<AliasToken>;
+    /** Internal source identity. Missing metadata denotes an explicitly provided context. */
+    readonly sourceActive?: Readonly<Ref<boolean>>;
+}
+declare const ThemeContextKey: InjectionKey<ThemeContext>;
+declare function createThemeContext(config: ThemeConfig): ThemeContext;
+/**
+ * 在子组件中取主题。没有 Provider 时回落到默认主题（不抛错，方便单测与渐进接入）。
+ *
+ * ⚠️ 第三个参数 `true` 不能省：`inject` 只有在显式声明「默认值是工厂」时才会调用它，
+ * 否则会**把函数本身当成默认值返回** —— 表现为 `useTheme().token` 是 undefined，
+ * 而且不报类型错（TS 看到的是 ThemeContext）。已踩过一次。
+ */
+declare function useTheme(): ThemeContext;
+/** 只要 token 的快捷方式 */
+declare function useToken(): ComputedRef<AliasToken>;
+/** 一次性把 token 写到某个元素上（无 Provider 的场景，如 SSR 后的客户端补挂） */
+declare function injectTokenCssVar(el: HTMLElement | SVGElement, token: Partial<AliasToken>, prefix?: string): void;
+/**
+ * ThemeProvider。
+ *
+ * `injectCssVar` 打开时把 token 以 CSS 变量写入 `target`（默认 `document.documentElement`）。
+ * 这就是开放决策 `zero-runtime-mode = B` 里的「运行时注入路径」——
+ * 静态 CSS 是默认路径，这条服务于运行时换主题。
+ *
+ * 卸载时移除写过的全部变量：不清理的话 HMR 与路由切换后会残留上一份主题的值。
+ */
+declare const ThemeProvider: vue.DefineComponent<vue.ExtractPropTypes<{
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: () => ThemeConfig;
+    };
+    injectCssVar: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    target: {
+        type: PropType<HTMLElement | SVGElement | null>;
+        default: undefined;
+    };
+}>, () => unknown, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    theme: {
+        type: PropType<ThemeConfig>;
+        default: () => ThemeConfig;
+    };
+    injectCssVar: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    target: {
+        type: PropType<HTMLElement | SVGElement | null>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    theme: ThemeConfig;
+    injectCssVar: boolean;
+    target: HTMLElement | SVGElement | null;
+}, SlotsType<{
+    default?: () => VNodeChild;
+}>, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+export { AliasToken, ColorMapToken, ColorNeutralMapToken, ColorPalette, CommonMapToken, DEFAULT_CSS_VAR_PREFIX, FontMapToken, HeightMapToken, IGNORE, MapToken, PRESERVE, PresetColorKey, PresetColorType, PresetColors, SeedToken, SizeMapToken, StyleMapToken, ThemeAppearance, ThemeConfig, ThemeContextKey, ThemeProvider, UNITLESS, algorithms, applyCSSVar, compactAlgorithm, createCSSVarScope, createThemeContext, darkAlgorithm, defaultAlgorithm, defaultPresetColors, defaultSeedToken, formatToken, genColorMapToken, genCommonMapToken, genCompactSizeMapToken, genControlHeight, genFontMapToken, genFontSizes, genRadius, genSizeMapToken, getAlphaColor, getCSSVarDeclarations, getDesignToken, getLineHeight, injectTokenCssVar, mergeThemeConfig, token2CSSVar, transformToken, useTheme, useToken };
+export type { CSSVarScope, DerivativeTokenWithOverride, ThemeContext, TransformResult };