@hia/theme-core 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,68 @@
1
+ import { gamutMapOklch, hexToOklch, clamp } from '../color/convert.js';
2
+ import { tonalScale } from '../color/scale.js';
3
+ import { bestOnColor } from '../color/contrast.js';
4
+ /**
5
+ * @lang zh-CN 语义状态色相锚点(OKLCH 角度,按 2026 主流设计系统约定):
6
+ * success 绿 145 / info 蓝 250 / warning 琥珀 70 / danger 红 25。
7
+ * **不要改动这些色相**——语义色的可辨识度依赖约定;个性化走覆盖机制而非改锚点。
8
+ * @lang en Semantic hue anchors (OKLCH degrees, per 2026 mainstream conventions):
9
+ * success green 145 / info blue 250 / warning amber 70 / danger red 25.
10
+ * **Do not change these** — recognisability depends on convention; personalise via overrides, not anchors.
11
+ */
12
+ export const SEMANTIC_HUES = { success: 145, info: 250, warning: 70, danger: 25 };
13
+ /** @lang zh-CN 语义状态中英文名(RoleColor.name 消费)。 @lang en Bilingual status names (consumed as RoleColor.name). */
14
+ export const SEMANTIC_NAMES = {
15
+ success: { zh: '成功', en: 'Success' },
16
+ info: { zh: '信息', en: 'Info' },
17
+ warning: { zh: '警告', en: 'Warning' },
18
+ danger: { zh: '危险', en: 'Danger' }
19
+ };
20
+ /**
21
+ * @lang zh-CN 从主色派生语义状态色组(ADR-012 决策 2)。
22
+ * 继承规则:语义基色的 L = 主色 L 向 0.55(通用可读档)收敛 40%;C = 主色 C 的 85% 并按语义色相
23
+ * 的可显示上限做色域映射(琥珀/绿高彩度可行,蓝红易越域,交给 gamutMap 收敛)。
24
+ * 每组产出与角色色同构的 10 阶 + on 色(bestOnColor)。
25
+ * @lang en Derives the semantic group from the primary (ADR-012 decision 2).
26
+ * Inheritance: the semantic base L converges 40% from the primary L toward 0.55 (a general readable level);
27
+ * C = 85% of the primary's C with per-hue gamut mapping (amber/green tolerate high chroma, blue/red clip).
28
+ * Each group yields the same 10-step scale + on colour as role colours.
29
+ */
30
+ export function deriveSemanticTokens(primaryHex) {
31
+ const primary = hexToOklch(primaryHex);
32
+ const out = {};
33
+ // 收敛公式:L_sem = L_primary + (0.55 - L_primary) * 0.4 —— 主色很暗/很亮时语义色仍回到可读区间,
34
+ // 同时保留"暗主题→略暗状态色"的家族感(40% 收敛而非拉平)。
35
+ // <lang en>Convergence: L_sem = L_primary + (0.55 − L_primary) × 0.4 — very dark/bright primaries still land
36
+ // in the readable band while keeping the family feel (40% convergence, not flattening).</lang>
37
+ const LBase = clamp(primary.L + (0.55 - primary.L) * 0.4, 0.4, 0.72);
38
+ const CBase = Math.max(primary.C * 0.85, 0.09); // 低彩主色也要保证状态色可辨(下限 0.09)。
39
+ for (const key of ['success', 'info', 'warning', 'danger']) {
40
+ const hue = SEMANTIC_HUES[key];
41
+ // 色域映射:C 可能超出该色相的可显示范围,gamutMap 收敛后再生成色阶。
42
+ // <lang en>Gamut map first: C may exceed the hue's displayable range, then build the scale.</lang>
43
+ const { hex } = gamutMapOklch(LBase, CBase, hue);
44
+ const scale = tonalScale(hex);
45
+ const role = { name: SEMANTIC_NAMES[key].zh, value: hex, scale, on: bestOnColor(hex).hex };
46
+ out[key] = role;
47
+ }
48
+ return out;
49
+ }
50
+ /**
51
+ * @lang zh-CN 判断语义组是否为派生态(ADR-012 决策 3):`semanticDerived[key]` 为 true 表示仍随主色刷新;
52
+ * 缺省视为用户值(旧预设/手动填入不跟随主色)。
53
+ * @lang en Whether a semantic group is still derived (ADR-012 decision 3): `semanticDerived[key] === true`
54
+ * keeps following the primary; absent means user-managed (old presets and manual input do not follow).
55
+ */
56
+ export function isSemanticDerived(flags, key) {
57
+ return flags?.[key] === true;
58
+ }
59
+ /**
60
+ * @lang zh-CN 深拷贝语义组(防调用方后续修改污染已构建主题,与 cloneGradientSettings 同语义)。
61
+ * @lang en Deep-copies a semantic group (prevents external mutation polluting the built theme, same semantics
62
+ * as cloneGradientSettings).
63
+ */
64
+ export function cloneSemanticTokens(tokens) {
65
+ const cloneRole = (r) => ({ name: r.name, value: r.value, scale: { ...r.scale }, on: r.on });
66
+ return { success: cloneRole(tokens.success), info: cloneRole(tokens.info), warning: cloneRole(tokens.warning), danger: cloneRole(tokens.danger) };
67
+ }
68
+ //# sourceMappingURL=semantic.js.map
@@ -0,0 +1,22 @@
1
+ /** @lang zh-CN 色觉模拟类型(三主型,严重度固定 1.0)。 @lang en CVD simulation types (three main ones, severity 1.0). */
2
+ export type CvdType = 'protanopia' | 'deuteranopia' | 'tritanopia';
3
+ /** @lang zh-CN 类型双语标签,供滤镜下拉直接消费。 @lang en Bilingual type labels, consumed directly by filter dropdowns. */
4
+ export declare const CVD_LABELS: Record<CvdType, {
5
+ zh: string;
6
+ en: string;
7
+ }>;
8
+ /**
9
+ * @lang zh-CN Machado 2009 severity 1.0 的 3×3 矩阵(线性 RGB → 线性 RGB)。
10
+ * 每行和 ≈ 1,故灰阶(R=G=B)映射后仍为灰阶;行为已由单测锁定。
11
+ * @lang en Machado 2009 severity-1.0 3×3 matrices (linear RGB → linear RGB). Rows sum to ≈1, so greys map to
12
+ * greys — asserted by tests.
13
+ */
14
+ export declare const MACHADO_2009_SEV1: Record<CvdType, readonly [number, number, number, number, number, number, number, number, number]>;
15
+ /**
16
+ * @lang zh-CN 对单个 HEX 色做色觉模拟:线性空间应用矩阵后钳制、编码回 HEX。
17
+ * 纯函数;负值钳 0、正值钳 1(矩阵可能把分量推出色域)。
18
+ * @lang en Simulates CVD on one HEX colour: applies the matrix in linear space, clamps, re-encodes to HEX.
19
+ * Pure; negative channels clamp to 0 and >1 to 1 (matrices can push components out of gamut).
20
+ */
21
+ export declare function simulateCvd(hex: string, type: CvdType): string;
22
+ //# sourceMappingURL=vision.d.ts.map
@@ -0,0 +1,63 @@
1
+ /**
2
+ * @lang zh-CN 色觉缺陷模拟(`W-tb-P36`):Machado & Oliveira & Fernandes 2009 模型,三种主型
3
+ * (红色弱 protan / 绿色弱 deutan / 蓝黄色弱 tritan)取**严重度 1.0** 的全量矩阵。
4
+ * 变换作用于**线性 RGB**(先 gamma 解码、矩阵相乘、再编码回去)——与论文定义及
5
+ * DaltonLens-Python 参考实现一致;灰阶在行和 ≈1 的性质下保持不变。
6
+ *
7
+ * 来源登记(原则②):Machado, Oliveira & Fernandes, "A Physiologically-based Model for
8
+ * Simulation of Color Vision Deficiency", IEEE Computer Graphics and Applications 25(5), 2009。
9
+ * 矩阵转写自 DaltonLens-Python(MIT,`daltonlens/simulate.py` 的 machado_2009_matrices),
10
+ * 该项目又转引自 colour-science 的 machado2010 数据集。本文件为**自研实现**(MIT 主库),
11
+ * 仅复制论文发表的矩阵数值并注明出处。
12
+ *
13
+ * 参考对照副本:`temp/daltonlens-simulate-reference.py`(T-tb-CLEANUP 清理范围)。
14
+ *
15
+ * @lang en Colour-vision-deficiency simulation (`W-tb-P36`): the Machado, Oliveira & Fernandes 2009 model,
16
+ * three main types (protan / deutan / tritan) at **severity 1.0**. The transform applies to **linear RGB**
17
+ * (gamma-decode, matrix multiply, re-encode) — matching the paper and the DaltonLens-Python reference;
18
+ * greys are invariant because each matrix row sums to ≈1.
19
+ *
20
+ * Source registry (research-first policy): Machado, Oliveira & Fernandes, "A Physiologically-based Model
21
+ * for Simulation of Color Vision Deficiency", IEEE CG&A 25(5), 2009. Matrix values transcribed from
22
+ * DaltonLens-Python (MIT, machado_2009_matrices), which in turn cites colour-science's machado2010 dataset.
23
+ * This file is our own implementation (MIT main repo): only the published paper values are used, credited.
24
+ *
25
+ * Reference copy kept at temp/daltonlens-simulate-reference.py (T-tb-CLEANUP scope).
26
+ */
27
+ import { hexToRgb, linearToSrgb, rgbToHex, srgbToLinear } from './convert.js';
28
+ /** @lang zh-CN 类型双语标签,供滤镜下拉直接消费。 @lang en Bilingual type labels, consumed directly by filter dropdowns. */
29
+ export const CVD_LABELS = {
30
+ protanopia: { zh: '红色弱模拟', en: 'Protanopia preview' },
31
+ deuteranopia: { zh: '绿色弱模拟', en: 'Deuteranopia preview' },
32
+ tritanopia: { zh: '蓝黄色弱模拟', en: 'Tritanopia preview' }
33
+ };
34
+ /**
35
+ * @lang zh-CN Machado 2009 severity 1.0 的 3×3 矩阵(线性 RGB → 线性 RGB)。
36
+ * 每行和 ≈ 1,故灰阶(R=G=B)映射后仍为灰阶;行为已由单测锁定。
37
+ * @lang en Machado 2009 severity-1.0 3×3 matrices (linear RGB → linear RGB). Rows sum to ≈1, so greys map to
38
+ * greys — asserted by tests.
39
+ */
40
+ export const MACHADO_2009_SEV1 = {
41
+ protanopia: [0.152286, 1.052583, -0.204868, 0.114503, 0.786281, 0.099216, -0.003882, -0.048116, 1.051998],
42
+ deuteranopia: [0.367322, 0.860646, -0.227968, 0.280085, 0.672501, 0.047413, -0.011820, 0.042940, 0.968881],
43
+ tritanopia: [1.255528, -0.076749, -0.178779, -0.078411, 0.930809, 0.147602, 0.004733, 0.691367, 0.303900]
44
+ };
45
+ /**
46
+ * @lang zh-CN 对单个 HEX 色做色觉模拟:线性空间应用矩阵后钳制、编码回 HEX。
47
+ * 纯函数;负值钳 0、正值钳 1(矩阵可能把分量推出色域)。
48
+ * @lang en Simulates CVD on one HEX colour: applies the matrix in linear space, clamps, re-encodes to HEX.
49
+ * Pure; negative channels clamp to 0 and >1 to 1 (matrices can push components out of gamut).
50
+ */
51
+ export function simulateCvd(hex, type) {
52
+ const [r, g, b] = hexToRgb(hex).map(srgbToLinear);
53
+ const m = MACHADO_2009_SEV1[type];
54
+ // 行 × 列:新通道 = 矩阵行与线性 RGB 向量的点积。
55
+ // <lang en>New channel = dot product of a matrix row with the linear RGB vector.</lang>
56
+ const out = [
57
+ m[0] * r + m[1] * g + m[2] * b,
58
+ m[3] * r + m[4] * g + m[5] * b,
59
+ m[6] * r + m[7] * g + m[8] * b
60
+ ];
61
+ return rgbToHex(out.map(linearToSrgb));
62
+ }
63
+ //# sourceMappingURL=vision.js.map
@@ -0,0 +1,70 @@
1
+ /**
2
+ * @lang zh-CN DTCG 令牌互操作(`W-tb-P38`,ADR-013):W3C Design Tokens Format **2025.10 稳定版**
3
+ * 的导出与白名单导入。依据(一手资料):design-tokens/community-group `schemas/src/2025.10/`
4
+ * 的 color/gradient/shadow/dimension/token/group schema——值形状逐条对照,不凭记忆。
5
+ *
6
+ * **导出映射**:`color.primary/secondary/third/aux<N>/semantic.<status>` 各组含 base/10 阶/on;
7
+ * `radius.*` 用 dimension(px);`shadow.*` 用 shadow 数组(双层阴影逐层展开);
8
+ * `typography.fontFamily` 用 fontFamily(字符串数组);`spacing.<i>` 用 dimension;
9
+ * 渐变用 `$type:"gradient"`(stops 数组,position 0–1),方向不在 DTCG 类型内 → 写入
10
+ * `$extensions["com.hia-theme-builder"].direction`。根级 `$extensions` 携带生成器信息。
11
+ *
12
+ * **导入(白名单子集)**:识别 `color.primary/secondary/semantic.<status>` 与 `radius`;
13
+ * 色值接受三形态(2025.10 对象 / 纯 hex 字符串(Tokens Studio 事实标准)/ 组内 `$ref`);
14
+ * 其余组跳过并出 `W_DTCG_SKIPPED` 警告(不静默丢弃)。
15
+ *
16
+ * @lang en DTCG token interop (`W-tb-P38`, ADR-013): W3C Design Tokens Format **2025.10 stable** export and
17
+ * whitelist import. Source of truth: the community-group `schemas/src/2025.10/` schemas — every value shape
18
+ * is checked against them, not recalled from memory.
19
+ *
20
+ * **Export mapping**: `color.primary/secondary/third/aux<N>/semantic.<status>` groups carry base/10 steps/on;
21
+ * `radius.*` as dimension(px); `shadow.*` as shadow arrays (both layers of our two-layer shadows);
22
+ * `typography.fontFamily` as fontFamily (string arrays); `spacing.<i>` as dimension; gradients as
23
+ * `$type:"gradient"` (stop array, position 0–1) with direction in `$extensions` since the DTCG gradient type
24
+ * has no axis concept. Root `$extensions` carries generator info.
25
+ *
26
+ * **Import (whitelist)**: recognises `color.primary/secondary/semantic.<status>` and `radius`; colour values
27
+ * accept three shapes (2025.10 objects / plain hex strings (Tokens Studio's de-facto form) / in-file `$ref`);
28
+ * other groups are skipped with `W_DTCG_SKIPPED` warnings — never silently dropped.
29
+ */
30
+ import type { Theme, ThemeDraft } from '../types.js';
31
+ import type { ExportTarget } from './types.js';
32
+ /**
33
+ * @lang zh-CN 导出 DTCG 2025.10 文本(`.tokens.json`)。根级组:color(含语义)、radius、shadow、
34
+ * typography、spacing、gradient;`$extensions["com.hia-theme-builder"]` 记录生成器与主题名。
35
+ * 可选组按 ADR-012/006 语义缺省不输出。
36
+ * @lang en Emits the DTCG 2025.10 text (`.tokens.json`). Root groups: colour (incl. semantics), radius, shadow,
37
+ * typography, spacing, gradient; `$extensions["com.hia-theme-builder"]` records generator and theme name.
38
+ * Optional groups are omitted when absent.
39
+ */
40
+ export declare function exportDtcgTokens(theme: Theme): string;
41
+ /** @lang zh-CN 导入错误/警告码(ADR-013)。 @lang en Import error/warning codes (ADR-013). */
42
+ export type DtcgIssueCode = 'E_DTCG_ROOT' | 'E_DTCG_TOKEN' | 'E_DTCG_COLOR' | 'E_JSON' | 'W_DTCG_SKIPPED';
43
+ export interface DtcgIssue {
44
+ code: DtcgIssueCode;
45
+ path: string;
46
+ message: string;
47
+ messageEn: string;
48
+ }
49
+ export interface DtcgParseResult {
50
+ ok: boolean;
51
+ /** @lang zh-CN 成功时的可编辑草稿(semanticDerived 全 false=用户值,不随主色刷新)。 @lang en An editable draft on success (semanticDerived all false — user-managed, not following the primary). */
52
+ draft?: ThemeDraft;
53
+ errors: DtcgIssue[];
54
+ warnings: DtcgIssue[];
55
+ }
56
+ /**
57
+ * @lang zh-CN 导入 DTCG 文件(白名单子集,ADR-013):识别 `color.primary/secondary/semantic.<status>` 与
58
+ * `radius`(md/base 为圆角基准)。成功返回可编辑草稿(**semanticDerived 全 false**——导入值视为用户值,
59
+ * 不随主色刷新,ADR-012 决策 3 的导入侧对称);跳过的组逐条 `W_DTCG_SKIPPED`。
60
+ * 语义组以导入基色重建完整色阶与 on 色(与角色色同一管线,保证导出物完整)。
61
+ * @lang en Imports a DTCG file (whitelist subset, ADR-013): recognises `color.primary/secondary/semantic.<status>`
62
+ * and `radius` (md/base becomes the base radius). Returns an editable draft with **semanticDerived all
63
+ * false** — imported values are user-managed (the import-side mirror of ADR-012 decision 3); skipped groups
64
+ * warn one by one. Semantic groups rebuild full scales and `on` from the imported base colours (same pipeline
65
+ * as role colours, so exports stay complete).
66
+ */
67
+ export declare function parseDtcgTokens(raw: unknown): DtcgParseResult;
68
+ /** @lang zh-CN DTCG 导出目标(注册在导出注册表;ZIP 内单一 `.tokens.json`,W3C 2025.10 形状)。 @lang en The DTCG export target (registered in the export registry; a single .tokens.json in W3C 2025.10 shape inside the ZIP). */
69
+ export declare const dtcgExportTarget: ExportTarget;
70
+ //# sourceMappingURL=dtcg.d.ts.map