rastack 0.0.24 → 0.0.26
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.
- package/CHANGELOG.md +4 -0
- package/dist/rastack-design.d.ts +17 -0
- package/dist/rastack-design.js +134 -0
- package/dist/rastack-tokens.d.ts +15 -0
- package/dist/rastack-tokens.js +43 -0
- package/dist/rastack-wasm-build.d.ts +1 -1
- package/dist/rastack-wasm-build.js +3 -3
- package/dist/rastack.d.ts +2 -0
- package/dist/rastack.js +12 -0
- package/dist/tokens/color.d.ts +22 -0
- package/dist/tokens/color.js +70 -0
- package/dist/tokens/compile.d.ts +34 -0
- package/dist/tokens/compile.js +103 -0
- package/dist/tokens/css.d.ts +30 -0
- package/dist/tokens/css.js +102 -0
- package/dist/tokens/define.d.ts +71 -0
- package/dist/tokens/define.js +98 -0
- package/dist/tokens/index.d.ts +17 -0
- package/dist/tokens/index.js +33 -0
- package/dist/tokens/resolve.d.ts +40 -0
- package/dist/tokens/resolve.js +135 -0
- package/dist/tokens/studio.d.ts +21 -0
- package/dist/tokens/studio.js +328 -0
- package/dist/tokens/theme.d.ts +55 -0
- package/dist/tokens/theme.js +139 -0
- package/dist/tokens/ts.d.ts +15 -0
- package/dist/tokens/ts.js +73 -0
- package/dist/tokens/types.d.ts +92 -0
- package/dist/tokens/types.js +35 -0
- package/hooks/query/delete.ts +3 -1
- package/jest.config.cjs +6 -0
- package/package.json +3 -2
- package/src/rastack-design.ts +117 -0
- package/src/rastack-tokens.ts +46 -0
- package/src/rastack-wasm-build.ts +3 -3
- package/src/rastack.ts +12 -0
- package/src/tokens/color.ts +74 -0
- package/src/tokens/compile.ts +85 -0
- package/src/tokens/css.ts +138 -0
- package/src/tokens/define.ts +128 -0
- package/src/tokens/index.ts +18 -0
- package/src/tokens/resolve.ts +170 -0
- package/src/tokens/studio.ts +357 -0
- package/src/tokens/theme.ts +180 -0
- package/src/tokens/ts.ts +80 -0
- package/src/tokens/types.ts +125 -0
- package/test/tokens.spec.ts +302 -0
- package/theme/index.ts +9 -0
- package/theme/provider.tsx +157 -0
- package/tokens.ts +9 -0
- package/tsconfig.json +3 -0
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Design-token model — the **W3C Design Tokens (DTCG) format**.
|
|
3
|
+
*
|
|
4
|
+
* A design token is the smallest, named, platform-agnostic decision about how
|
|
5
|
+
* the UI looks: a colour, a spacing step, a radius, a font family. The DTCG
|
|
6
|
+
* community-group spec (https://tr.designtokens.org) is the industry standard
|
|
7
|
+
* serialization: a nested JSON tree of **groups** whose leaves are **tokens**,
|
|
8
|
+
* each carrying a `$value`, an optional `$type`, and an optional
|
|
9
|
+
* `$description`. Values may be literals or **aliases** — a `"{group.token}"`
|
|
10
|
+
* reference to another token.
|
|
11
|
+
*
|
|
12
|
+
* ```jsonc
|
|
13
|
+
* {
|
|
14
|
+
* "color": {
|
|
15
|
+
* "$type": "color",
|
|
16
|
+
* "brand": { "500": { "$value": "#4F6BFF" } },
|
|
17
|
+
* "text": { "$value": "{color.brand.500}" } // alias
|
|
18
|
+
* }
|
|
19
|
+
* }
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* This module is the pure data model shared by the compiler
|
|
23
|
+
* (`tools/src/tokens/{resolve,css,ts}.ts`) and the React runtime
|
|
24
|
+
* (`rastack/theme`). It has no filesystem or React dependency, so it builds for
|
|
25
|
+
* the browser exactly like `rastack/define`.
|
|
26
|
+
*/
|
|
27
|
+
|
|
28
|
+
/** The DTCG `$type`s this framework understands. */
|
|
29
|
+
export type TokenType =
|
|
30
|
+
| "color"
|
|
31
|
+
| "dimension"
|
|
32
|
+
| "fontFamily"
|
|
33
|
+
| "fontWeight"
|
|
34
|
+
| "duration"
|
|
35
|
+
| "cubicBezier"
|
|
36
|
+
| "number"
|
|
37
|
+
| "shadow"
|
|
38
|
+
| "border"
|
|
39
|
+
| "typography"
|
|
40
|
+
| "transition";
|
|
41
|
+
|
|
42
|
+
/** A shadow token value (single shadow or a stack of them). */
|
|
43
|
+
export interface ShadowValue {
|
|
44
|
+
offsetX: string | number;
|
|
45
|
+
offsetY: string | number;
|
|
46
|
+
blur?: string | number;
|
|
47
|
+
spread?: string | number;
|
|
48
|
+
color: string;
|
|
49
|
+
inset?: boolean;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Anything that can appear as a token `$value` (including aliases as strings). */
|
|
53
|
+
export type TokenValue =
|
|
54
|
+
| string
|
|
55
|
+
| number
|
|
56
|
+
| boolean
|
|
57
|
+
| ShadowValue
|
|
58
|
+
| ShadowValue[]
|
|
59
|
+
| string[]
|
|
60
|
+
| Record<string, unknown>;
|
|
61
|
+
|
|
62
|
+
/** A single design token — a group leaf. Identified by the presence of `$value`. */
|
|
63
|
+
export interface DesignToken {
|
|
64
|
+
$value: TokenValue;
|
|
65
|
+
$type?: TokenType;
|
|
66
|
+
$description?: string;
|
|
67
|
+
$extensions?: Record<string, unknown>;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* A group node: named children (tokens or nested groups) plus optional group
|
|
72
|
+
* metadata. `$type` set on a group is **inherited** by descendant tokens that
|
|
73
|
+
* don't declare their own — the standard DTCG type-inheritance rule.
|
|
74
|
+
*
|
|
75
|
+
* Typed loosely (`any` children) on purpose: the tree is arbitrary-depth data,
|
|
76
|
+
* mirroring how the codebase types OpenAPI documents.
|
|
77
|
+
*/
|
|
78
|
+
export interface TokenGroup {
|
|
79
|
+
$type?: TokenType;
|
|
80
|
+
$description?: string;
|
|
81
|
+
[child: string]: DesignToken | TokenGroup | TokenType | string | undefined;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** The root of a token tree. */
|
|
85
|
+
export type TokenDocument = TokenGroup;
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* A themeable token document: a base tree plus named **modes** (e.g. `light`,
|
|
89
|
+
* `dark`) that override a subset of tokens. Modes compile to CSS selector
|
|
90
|
+
* scopes, so a running app flips theme by toggling one attribute.
|
|
91
|
+
*/
|
|
92
|
+
export interface ThemedTokens {
|
|
93
|
+
/** Base tokens — the values that apply in every mode. */
|
|
94
|
+
tokens: TokenDocument;
|
|
95
|
+
/** Per-mode overrides, deep-merged over the base. */
|
|
96
|
+
modes?: Record<string, TokenDocument>;
|
|
97
|
+
/** Which mode is the default (emitted onto `:root`). */
|
|
98
|
+
defaultMode?: string;
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** A token after alias resolution and `$type` inheritance — ready to emit. */
|
|
102
|
+
export interface ResolvedToken {
|
|
103
|
+
/** Dotted path, e.g. `color.brand.500`. */
|
|
104
|
+
path: string;
|
|
105
|
+
/** The token's `$type` (inherited or inferred). */
|
|
106
|
+
type: TokenType | undefined;
|
|
107
|
+
/** The literal value with every alias followed to its source. */
|
|
108
|
+
value: TokenValue;
|
|
109
|
+
/**
|
|
110
|
+
* If this token is a direct alias of another, the target's dotted path.
|
|
111
|
+
* Emitters use it to preserve the reference (CSS `var(--target)`), so theming
|
|
112
|
+
* cascades instead of being flattened away.
|
|
113
|
+
*/
|
|
114
|
+
aliasOf?: string;
|
|
115
|
+
$description?: string;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** True when a node is a token leaf (has `$value`) rather than a group. */
|
|
119
|
+
export function isToken(node: unknown): node is DesignToken {
|
|
120
|
+
return (
|
|
121
|
+
typeof node === "object" &&
|
|
122
|
+
node !== null &&
|
|
123
|
+
Object.prototype.hasOwnProperty.call(node, "$value")
|
|
124
|
+
);
|
|
125
|
+
}
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
|
|
2
|
+
import { join } from "path";
|
|
3
|
+
import {
|
|
4
|
+
defineTheme,
|
|
5
|
+
defineTokens,
|
|
6
|
+
emitCss,
|
|
7
|
+
emitTs,
|
|
8
|
+
cssVarName,
|
|
9
|
+
formatCssValue,
|
|
10
|
+
ref,
|
|
11
|
+
resolveTokens,
|
|
12
|
+
resolveTheme,
|
|
13
|
+
t,
|
|
14
|
+
ThemedTokens,
|
|
15
|
+
TokenDocument,
|
|
16
|
+
} from "../src/tokens";
|
|
17
|
+
import { compileTokens, loadTokens } from "../src/tokens/compile";
|
|
18
|
+
import { renderStudio } from "../src/tokens/studio";
|
|
19
|
+
|
|
20
|
+
const workRoot = join(__dirname, "tokens-fixtures");
|
|
21
|
+
|
|
22
|
+
function findTok<T extends { path: string }>(list: T[], path: string): T {
|
|
23
|
+
const found = list.find((x) => x.path === path);
|
|
24
|
+
if (!found) throw new Error(`missing token ${path}`);
|
|
25
|
+
return found;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
describe("design tokens — resolution", () => {
|
|
29
|
+
it("inherits a group $type down to its tokens", () => {
|
|
30
|
+
const doc: TokenDocument = {
|
|
31
|
+
color: { $type: "color", brand: { 500: { $value: "#4F6BFF" } } },
|
|
32
|
+
};
|
|
33
|
+
const resolved = resolveTokens(doc);
|
|
34
|
+
expect(findTok(resolved, "color.brand.500").type).toBe("color");
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
it("resolves alias values transitively and records the immediate target", () => {
|
|
38
|
+
const doc: TokenDocument = {
|
|
39
|
+
color: {
|
|
40
|
+
$type: "color",
|
|
41
|
+
brand: { 500: { $value: "#4F6BFF" } },
|
|
42
|
+
accent: { $value: ref("color.brand.500") },
|
|
43
|
+
cta: { $value: ref("color.accent") },
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
const resolved = resolveTokens(doc);
|
|
47
|
+
const accent = findTok(resolved, "color.accent");
|
|
48
|
+
const cta = findTok(resolved, "color.cta");
|
|
49
|
+
expect(accent.value).toBe("#4F6BFF");
|
|
50
|
+
expect(accent.aliasOf).toBe("color.brand.500");
|
|
51
|
+
// transitive: cta -> accent -> brand.500
|
|
52
|
+
expect(cta.value).toBe("#4F6BFF");
|
|
53
|
+
expect(cta.aliasOf).toBe("color.accent");
|
|
54
|
+
});
|
|
55
|
+
|
|
56
|
+
it("throws on a dangling alias", () => {
|
|
57
|
+
const doc: TokenDocument = { color: { a: { $type: "color", $value: ref("color.missing") } } };
|
|
58
|
+
expect(() => resolveTokens(doc)).toThrow(/unknown token "color.missing"/);
|
|
59
|
+
});
|
|
60
|
+
|
|
61
|
+
it("throws on an alias cycle", () => {
|
|
62
|
+
const doc: TokenDocument = {
|
|
63
|
+
a: { $type: "color", $value: ref("b") },
|
|
64
|
+
b: { $type: "color", $value: ref("a") },
|
|
65
|
+
};
|
|
66
|
+
expect(() => resolveTokens(doc)).toThrow(/cycle/i);
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
it("names CSS variables from dotted paths (kebab, camel-split, prefix)", () => {
|
|
70
|
+
expect(cssVarName("color.brand.500")).toBe("--color-brand-500");
|
|
71
|
+
expect(cssVarName("color.surfaceAlt")).toBe("--color-surface-alt");
|
|
72
|
+
expect(cssVarName("color.accent", "rs")).toBe("--rs-color-accent");
|
|
73
|
+
});
|
|
74
|
+
});
|
|
75
|
+
|
|
76
|
+
describe("design tokens — DSL builders", () => {
|
|
77
|
+
it("t.dimension coerces bare numbers to px; t.duration to ms", () => {
|
|
78
|
+
const doc = defineTokens({
|
|
79
|
+
space: { md: t.dimension(16) },
|
|
80
|
+
motion: { fast: t.duration(150) },
|
|
81
|
+
}).tokens;
|
|
82
|
+
const resolved = resolveTokens(doc);
|
|
83
|
+
expect(findTok(resolved, "space.md").value).toBe("16px");
|
|
84
|
+
expect(findTok(resolved, "motion.fast").value).toBe("150ms");
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
it("defineTokens normalises a bare tree and a themed shape alike", () => {
|
|
88
|
+
const bare = defineTokens({ color: { bg: t.color("#fff") } });
|
|
89
|
+
expect(bare.tokens.color).toBeDefined();
|
|
90
|
+
expect(bare.modes).toEqual({});
|
|
91
|
+
|
|
92
|
+
const themed = defineTokens({ tokens: { color: { bg: t.color("#fff") } }, defaultMode: "light" });
|
|
93
|
+
expect(themed.defaultMode).toBe("light");
|
|
94
|
+
});
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
describe("design tokens — CSS emission", () => {
|
|
98
|
+
const themed: ThemedTokens = {
|
|
99
|
+
tokens: {
|
|
100
|
+
color: {
|
|
101
|
+
$type: "color",
|
|
102
|
+
brand: { 500: { $value: "#4F6BFF" } },
|
|
103
|
+
accent: { $value: ref("color.brand.500") },
|
|
104
|
+
bg: { $value: "#FFFFFF" },
|
|
105
|
+
},
|
|
106
|
+
space: { $type: "dimension", md: { $value: "16px" } },
|
|
107
|
+
font: { family: { $type: "fontFamily", sans: { $value: ["Inter", "sans-serif"] } } },
|
|
108
|
+
shadow: { $type: "shadow", sm: { $value: { offsetX: "0", offsetY: "1px", blur: "2px", color: "#0001" } } },
|
|
109
|
+
},
|
|
110
|
+
modes: { dark: { color: { bg: { $value: "#06080F" } } } },
|
|
111
|
+
defaultMode: "light",
|
|
112
|
+
};
|
|
113
|
+
|
|
114
|
+
const css = emitCss(themed);
|
|
115
|
+
|
|
116
|
+
it("emits :root custom properties", () => {
|
|
117
|
+
expect(css).toMatch(/:root\s*\{/);
|
|
118
|
+
expect(css).toContain("--color-brand-500: #4F6BFF;");
|
|
119
|
+
expect(css).toContain("--space-md: 16px;");
|
|
120
|
+
});
|
|
121
|
+
|
|
122
|
+
it("preserves aliases as var() references so themes cascade", () => {
|
|
123
|
+
expect(css).toContain("--color-accent: var(--color-brand-500);");
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
it("quotes font families with spaces and joins the stack", () => {
|
|
127
|
+
expect(css).toContain('--font-family-sans: Inter, sans-serif;');
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
it("renders shadows as box-shadow strings", () => {
|
|
131
|
+
expect(css).toContain("--shadow-sm: 0 1px 2px #0001;");
|
|
132
|
+
});
|
|
133
|
+
|
|
134
|
+
it("scopes a mode override to its selector and omits unchanged tokens", () => {
|
|
135
|
+
expect(css).toContain('[data-theme="dark"]');
|
|
136
|
+
// only bg changed in dark
|
|
137
|
+
const darkBlock = css.slice(css.indexOf('[data-theme="dark"]'));
|
|
138
|
+
expect(darkBlock).toContain("--color-bg: #06080F;");
|
|
139
|
+
expect(darkBlock).not.toContain("--color-brand-500");
|
|
140
|
+
});
|
|
141
|
+
|
|
142
|
+
it("respects a variable prefix", () => {
|
|
143
|
+
expect(emitCss(themed, { prefix: "rs" })).toContain("--rs-color-brand-500:");
|
|
144
|
+
});
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
describe("design tokens — typed TS emission", () => {
|
|
148
|
+
const base = resolveTokens({
|
|
149
|
+
color: { $type: "color", brand: { 500: { $value: "#4F6BFF" } }, surfaceAlt: { $value: "#eee" } },
|
|
150
|
+
});
|
|
151
|
+
const source = emitTs(base);
|
|
152
|
+
|
|
153
|
+
it("emits a nested theme tree of var() references", () => {
|
|
154
|
+
expect(source).toContain('"500": "var(--color-brand-500)"');
|
|
155
|
+
expect(source).toContain('surfaceAlt: "var(--color-surface-alt)"');
|
|
156
|
+
});
|
|
157
|
+
|
|
158
|
+
it("emits a TokenPath union of every token", () => {
|
|
159
|
+
expect(source).toContain('| "color.brand.500"');
|
|
160
|
+
expect(source).toContain('| "color.surfaceAlt"');
|
|
161
|
+
});
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
describe("design tokens — compile to disk", () => {
|
|
165
|
+
const outDir = join(workRoot, "out");
|
|
166
|
+
const jsonSrc = join(workRoot, "sample.tokens.json");
|
|
167
|
+
|
|
168
|
+
beforeAll(() => {
|
|
169
|
+
mkdirSync(workRoot, { recursive: true });
|
|
170
|
+
writeFileSync(
|
|
171
|
+
jsonSrc,
|
|
172
|
+
JSON.stringify({
|
|
173
|
+
tokens: { color: { $type: "color", accent: { $value: "#4F6BFF" } } },
|
|
174
|
+
modes: { dark: { color: { accent: { $value: "#8BA4FF" } } } },
|
|
175
|
+
defaultMode: "light",
|
|
176
|
+
}),
|
|
177
|
+
);
|
|
178
|
+
});
|
|
179
|
+
afterAll(() => rmSync(workRoot, { recursive: true, force: true }));
|
|
180
|
+
|
|
181
|
+
it("writes tokens.rastack.json, tokens.css and tokens.ts", () => {
|
|
182
|
+
const { files } = compileTokens(jsonSrc, outDir);
|
|
183
|
+
expect(files.map((f) => f.split("/").pop())).toEqual([
|
|
184
|
+
"tokens.rastack.json",
|
|
185
|
+
"tokens.css",
|
|
186
|
+
"tokens.ts",
|
|
187
|
+
]);
|
|
188
|
+
for (const f of files) expect(existsSync(f)).toBe(true);
|
|
189
|
+
expect(readFileSync(join(outDir, "tokens.css"), "utf8")).toContain("--color-accent: #4F6BFF;");
|
|
190
|
+
expect(readFileSync(join(outDir, "tokens.ts"), "utf8")).toContain('| "color.accent"');
|
|
191
|
+
});
|
|
192
|
+
|
|
193
|
+
it("loadTokens parses a bare DTCG tree as well as a themed doc", () => {
|
|
194
|
+
const bareSrc = join(workRoot, "bare.tokens.json");
|
|
195
|
+
writeFileSync(bareSrc, JSON.stringify({ color: { $type: "color", bg: { $value: "#fff" } } }));
|
|
196
|
+
const themed = loadTokens(bareSrc);
|
|
197
|
+
expect(themed.tokens.color).toBeDefined();
|
|
198
|
+
});
|
|
199
|
+
});
|
|
200
|
+
|
|
201
|
+
describe("design tokens — studio page", () => {
|
|
202
|
+
const themed = defineTokens({
|
|
203
|
+
tokens: { color: { brand: { 500: t.color("#4F6BFF") }, accent: t.color(ref("color.brand.500")) } },
|
|
204
|
+
modes: { dark: { color: { brand: { 500: t.color("#8BA4FF") } } } },
|
|
205
|
+
defaultMode: "light",
|
|
206
|
+
});
|
|
207
|
+
|
|
208
|
+
it("renders a self-contained HTML page embedding the tokens + CSS", () => {
|
|
209
|
+
const html = renderStudio(themed, { editable: true });
|
|
210
|
+
expect(html).toMatch(/^<!doctype html>/);
|
|
211
|
+
expect(html).toContain("--color-brand-500: #4F6BFF;");
|
|
212
|
+
expect(html).toContain('id="studio-data"');
|
|
213
|
+
// the embedded payload carries the layers + raw doc for the editor
|
|
214
|
+
expect(html).toContain('"color.accent"');
|
|
215
|
+
expect(html).toContain('"editable":true');
|
|
216
|
+
});
|
|
217
|
+
});
|
|
218
|
+
|
|
219
|
+
describe("design tokens — defineTheme() intent layer", () => {
|
|
220
|
+
it("derives a full 50–950 brand scale from one colour, with 500 = the seed", () => {
|
|
221
|
+
const resolved = resolveTheme(defineTheme({ brand: "#4F6BFF" }));
|
|
222
|
+
expect(findTok(resolved.base, "color.brand.500").value).toBe("#4F6BFF");
|
|
223
|
+
for (const step of ["50", "100", "200", "300", "400", "600", "700", "800", "900", "950"]) {
|
|
224
|
+
expect(findTok(resolved.base, `color.brand.${step}`).value).toMatch(/^#[0-9A-F]{6}$/);
|
|
225
|
+
}
|
|
226
|
+
});
|
|
227
|
+
|
|
228
|
+
it("generates semantic tokens plus a dark mode by default", () => {
|
|
229
|
+
const themed = defineTheme({ brand: "#4F6BFF" });
|
|
230
|
+
expect(Object.keys(themed.modes ?? {})).toEqual(["dark"]);
|
|
231
|
+
const resolved = resolveTheme(themed);
|
|
232
|
+
for (const name of ["bg", "surface", "border", "text", "text-muted", "accent", "on-accent"]) {
|
|
233
|
+
expect(findTok(resolved.base, `color.${name}`)).toBeDefined();
|
|
234
|
+
}
|
|
235
|
+
// The accent is an alias of the brand ramp, and reads lighter in dark.
|
|
236
|
+
expect(findTok(resolved.base, "color.accent").aliasOf).toBe("color.brand.500");
|
|
237
|
+
expect(findTok(resolved.modes.dark, "color.accent").aliasOf).toBe("color.brand.400");
|
|
238
|
+
// dark bg is dark, light bg is white
|
|
239
|
+
expect(findTok(resolved.base, "color.bg").value).toBe("#FFFFFF");
|
|
240
|
+
expect(findTok(resolved.modes.dark, "color.bg").value).not.toBe("#FFFFFF");
|
|
241
|
+
});
|
|
242
|
+
|
|
243
|
+
it("picks a readable on-accent colour by contrast", () => {
|
|
244
|
+
expect(findTok(resolveTheme(defineTheme({ brand: "#FACC15" })).base, "color.on-accent").value).toBe("#0B1020");
|
|
245
|
+
expect(findTok(resolveTheme(defineTheme({ brand: "#1D4ED8" })).base, "color.on-accent").value).toBe("#FFFFFF");
|
|
246
|
+
});
|
|
247
|
+
|
|
248
|
+
it("maps radius keywords and honours a numeric radius", () => {
|
|
249
|
+
expect(findTok(resolveTheme(defineTheme({ brand: "#4F6BFF", radius: "sharp" })).base, "color.brand.500")).toBeDefined();
|
|
250
|
+
const r = resolveTheme(defineTheme({ brand: "#4F6BFF", radius: 20 }));
|
|
251
|
+
expect(findTok(r.base, "radius.md").value).toBe("20px");
|
|
252
|
+
});
|
|
253
|
+
|
|
254
|
+
it("lowers to the same ThemedTokens shape and compiles to valid CSS", () => {
|
|
255
|
+
const css = emitCss(defineTheme({ brand: "#4F6BFF", font: "Poppins" }));
|
|
256
|
+
expect(css).toContain("--color-brand-500: #4F6BFF;");
|
|
257
|
+
expect(css).toContain("--color-accent: var(--color-brand-500);");
|
|
258
|
+
expect(css).toContain('[data-theme="dark"]');
|
|
259
|
+
expect(css).toContain("--font-family-sans: Poppins;");
|
|
260
|
+
});
|
|
261
|
+
|
|
262
|
+
it("applies colour overrides and the extend escape hatch", () => {
|
|
263
|
+
const themed = defineTheme({
|
|
264
|
+
brand: "#4F6BFF",
|
|
265
|
+
colors: { success: "#00A86B" },
|
|
266
|
+
extend: { tokens: { z: { index: { modal: { $type: "number", $value: 1000 } } } } },
|
|
267
|
+
});
|
|
268
|
+
const base = resolveTheme(themed).base;
|
|
269
|
+
expect(findTok(base, "color.success").value).toBe("#00A86B");
|
|
270
|
+
expect(findTok(base, "z.index.modal").value).toBe(1000);
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
it("appearance:'light' emits no dark mode; 'dark' makes :root dark", () => {
|
|
274
|
+
expect(Object.keys(defineTheme({ brand: "#4F6BFF", appearance: "light" }).modes ?? {})).toEqual([]);
|
|
275
|
+
const dark = defineTheme({ brand: "#4F6BFF", appearance: "dark" });
|
|
276
|
+
expect(dark.defaultMode).toBe("dark");
|
|
277
|
+
expect(findTok(resolveTheme(dark).base, "color.bg").value).not.toBe("#FFFFFF");
|
|
278
|
+
});
|
|
279
|
+
});
|
|
280
|
+
|
|
281
|
+
describe("design tokens — the repo's own theme.tokens.ts + .json agree", () => {
|
|
282
|
+
it("the TS authoring source resolves and matches the JSON source", () => {
|
|
283
|
+
// Executed by ts-jest, importing the package by its subpath name.
|
|
284
|
+
// eslint-disable-next-line @typescript-eslint/no-var-requires
|
|
285
|
+
const tsThemed = require("../../tokens/theme.tokens").default as ThemedTokens;
|
|
286
|
+
const jsonThemed = loadTokens(join(__dirname, "..", "..", "tokens", "theme.tokens.json"));
|
|
287
|
+
|
|
288
|
+
const fromTs = resolveTheme(tsThemed);
|
|
289
|
+
const fromJson = resolveTheme(jsonThemed);
|
|
290
|
+
|
|
291
|
+
// Same set of token paths and the same emitted CSS values (composite types
|
|
292
|
+
// like shadows may be authored with numbers in TS and strings in JSON, but
|
|
293
|
+
// must render identically).
|
|
294
|
+
const map = (r: ReturnType<typeof resolveTheme>) =>
|
|
295
|
+
Object.fromEntries(r.base.map((tok) => [tok.path, formatCssValue(tok)]));
|
|
296
|
+
expect(map(fromTs)).toEqual(map(fromJson));
|
|
297
|
+
|
|
298
|
+
// Alias cascades through the dark mode (accent follows brand.500).
|
|
299
|
+
const darkAccent = findTok(fromTs.modes.dark, "color.accent");
|
|
300
|
+
expect(darkAccent.value).toBe("#8BA4FF");
|
|
301
|
+
});
|
|
302
|
+
});
|
package/theme/index.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `rastack/theme` — the React runtime that applies a design-token set: a
|
|
3
|
+
* `<ThemeProvider>` that injects the token CSS variables and manages light/dark
|
|
4
|
+
* (and any custom) modes, plus `useTheme` / `useToken` / `useThemeMode` hooks.
|
|
5
|
+
*
|
|
6
|
+
* Tokens are authored with `rastack/tokens` and compiled by `rastack tokens`;
|
|
7
|
+
* this is where they light up the UI.
|
|
8
|
+
*/
|
|
9
|
+
export * from "./provider";
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
import React, {
|
|
2
|
+
createContext,
|
|
3
|
+
ReactNode,
|
|
4
|
+
useContext,
|
|
5
|
+
useEffect,
|
|
6
|
+
useMemo,
|
|
7
|
+
useState,
|
|
8
|
+
} from "react";
|
|
9
|
+
import {
|
|
10
|
+
emitCss,
|
|
11
|
+
formatCssValue,
|
|
12
|
+
cssVarName,
|
|
13
|
+
resolveTheme,
|
|
14
|
+
ThemedTokens,
|
|
15
|
+
} from "../src/tokens";
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* `rastack/theme` — apply a design-token set to a React app.
|
|
19
|
+
*
|
|
20
|
+
* The counterpart to `rastack tokens`: where the CLI emits static CSS, this
|
|
21
|
+
* provider injects the same CSS custom properties at runtime and manages the
|
|
22
|
+
* active **mode** (light / dark / …). Because every value is a CSS variable,
|
|
23
|
+
* flipping mode re-cascades instantly with no re-render of consuming
|
|
24
|
+
* components — exactly like `RAStackProvider` reconfiguring the API in place.
|
|
25
|
+
*
|
|
26
|
+
* ```tsx
|
|
27
|
+
* import tokens from "../tokens/theme.tokens"; // defineTokens(...)
|
|
28
|
+
* import { ThemeProvider, useToken, useThemeMode } from "rastack/theme";
|
|
29
|
+
*
|
|
30
|
+
* <ThemeProvider tokens={tokens}>
|
|
31
|
+
* <App />
|
|
32
|
+
* </ThemeProvider>
|
|
33
|
+
*
|
|
34
|
+
* const accent = useToken("color.accent"); // "var(--color-accent)"
|
|
35
|
+
* const [mode, setMode] = useThemeMode(); // "light" | "dark" | …
|
|
36
|
+
* ```
|
|
37
|
+
*/
|
|
38
|
+
|
|
39
|
+
export interface ThemeContextValue {
|
|
40
|
+
/** The active mode, or `undefined` for the base (mode-less) theme. */
|
|
41
|
+
mode: string | undefined;
|
|
42
|
+
/** Switch mode; unknown modes fall back to the base. */
|
|
43
|
+
setMode: (mode: string | undefined) => void;
|
|
44
|
+
/** The modes this theme defines. */
|
|
45
|
+
modes: string[];
|
|
46
|
+
/** `token("color.accent")` → `"var(--color-accent)"`. */
|
|
47
|
+
token: (path: string) => string;
|
|
48
|
+
/**
|
|
49
|
+
* The resolved *literal* value of a token in the current mode
|
|
50
|
+
* (`"#4F6BFF"`), for contexts without CSS variables (React Native, canvas).
|
|
51
|
+
*/
|
|
52
|
+
value: (path: string) => string | undefined;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
const ThemeContext = createContext<ThemeContextValue | null>(null);
|
|
56
|
+
|
|
57
|
+
export interface ThemeProviderProps {
|
|
58
|
+
/** A `defineTokens(...)` result, or a bare `{ tokens, modes }` document. */
|
|
59
|
+
tokens: ThemedTokens;
|
|
60
|
+
/** Initial mode. Defaults to the token set's `defaultMode`. */
|
|
61
|
+
mode?: string;
|
|
62
|
+
/** Prefix every CSS variable (`prefix="rs"` → `--rs-color-accent`). */
|
|
63
|
+
prefix?: string;
|
|
64
|
+
/**
|
|
65
|
+
* The attribute set on `<html>` for the active mode. Default `data-theme`,
|
|
66
|
+
* matching the emitted CSS's `[data-theme="dark"]` selectors.
|
|
67
|
+
*/
|
|
68
|
+
modeAttribute?: string;
|
|
69
|
+
/**
|
|
70
|
+
* Where to scope the CSS. `document` (default) injects a `<style>` and sets
|
|
71
|
+
* the mode attribute on `<html>`. Pass an element to scope to a subtree.
|
|
72
|
+
*/
|
|
73
|
+
target?: HTMLElement | "document";
|
|
74
|
+
children: ReactNode;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
export function ThemeProvider({
|
|
78
|
+
tokens,
|
|
79
|
+
mode: initialMode,
|
|
80
|
+
prefix = "",
|
|
81
|
+
modeAttribute = "data-theme",
|
|
82
|
+
target = "document",
|
|
83
|
+
children,
|
|
84
|
+
}: ThemeProviderProps): JSX.Element {
|
|
85
|
+
const resolved = useMemo(() => resolveTheme(tokens), [tokens]);
|
|
86
|
+
const css = useMemo(() => emitCss(tokens, { prefix }), [tokens, prefix]);
|
|
87
|
+
const [mode, setMode] = useState<string | undefined>(
|
|
88
|
+
initialMode ?? resolved.defaultMode,
|
|
89
|
+
);
|
|
90
|
+
|
|
91
|
+
// Inject (and keep in sync) the generated CSS as a single <style> element.
|
|
92
|
+
useEffect(() => {
|
|
93
|
+
if (typeof document === "undefined") return;
|
|
94
|
+
const style = document.createElement("style");
|
|
95
|
+
style.setAttribute("data-rastack-theme", "");
|
|
96
|
+
style.textContent = css;
|
|
97
|
+
document.head.appendChild(style);
|
|
98
|
+
return () => {
|
|
99
|
+
style.remove();
|
|
100
|
+
};
|
|
101
|
+
}, [css]);
|
|
102
|
+
|
|
103
|
+
// Reflect the active mode onto the target element's attribute.
|
|
104
|
+
useEffect(() => {
|
|
105
|
+
if (typeof document === "undefined") return;
|
|
106
|
+
const el =
|
|
107
|
+
target === "document" ? document.documentElement : (target as HTMLElement);
|
|
108
|
+
const prev = el.getAttribute(modeAttribute);
|
|
109
|
+
if (mode) el.setAttribute(modeAttribute, mode);
|
|
110
|
+
else el.removeAttribute(modeAttribute);
|
|
111
|
+
return () => {
|
|
112
|
+
if (prev != null) el.setAttribute(modeAttribute, prev);
|
|
113
|
+
else el.removeAttribute(modeAttribute);
|
|
114
|
+
};
|
|
115
|
+
}, [mode, modeAttribute, target]);
|
|
116
|
+
|
|
117
|
+
const ctx = useMemo<ThemeContextValue>(() => {
|
|
118
|
+
const active = (mode && resolved.modes[mode]) || resolved.base;
|
|
119
|
+
const literals = new Map(active.map((t) => [t.path, formatCssValue(t)]));
|
|
120
|
+
return {
|
|
121
|
+
mode,
|
|
122
|
+
setMode,
|
|
123
|
+
modes: Object.keys(resolved.modes),
|
|
124
|
+
token: (path) => `var(${cssVarName(path, prefix)})`,
|
|
125
|
+
value: (path) => literals.get(path),
|
|
126
|
+
};
|
|
127
|
+
}, [mode, resolved, prefix]);
|
|
128
|
+
|
|
129
|
+
return <ThemeContext.Provider value={ctx}>{children}</ThemeContext.Provider>;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** The full theme context (mode, setMode, token/value lookups). */
|
|
133
|
+
export function useTheme(): ThemeContextValue {
|
|
134
|
+
const ctx = useContext(ThemeContext);
|
|
135
|
+
if (!ctx) throw new Error("useTheme must be used within a <ThemeProvider>.");
|
|
136
|
+
return ctx;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** `[mode, setMode]` — the active mode and a switcher. */
|
|
140
|
+
export function useThemeMode(): [string | undefined, (mode: string | undefined) => void] {
|
|
141
|
+
const { mode, setMode } = useTheme();
|
|
142
|
+
return [mode, setMode];
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
/** A token's CSS-variable reference: `useToken("color.accent")` → `"var(--color-accent)"`. */
|
|
146
|
+
export function useToken(path: string): string {
|
|
147
|
+
return useTheme().token(path);
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* A token's resolved *literal* value in the active mode (`"#4F6BFF"`). Use on
|
|
152
|
+
* platforms without CSS variables (React Native); on the web prefer
|
|
153
|
+
* {@link useToken} so mode switches don't re-render.
|
|
154
|
+
*/
|
|
155
|
+
export function useTokenValue(path: string): string | undefined {
|
|
156
|
+
return useTheme().value(path);
|
|
157
|
+
}
|
package/tokens.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `rastack/tokens` — the design-system authoring DSL and pure token engine.
|
|
3
|
+
*
|
|
4
|
+
* Author your design system in TypeScript with {@link defineTokens} + {@link t},
|
|
5
|
+
* following the industry-standard W3C Design Tokens (DTCG) format. `rastack
|
|
6
|
+
* tokens` compiles it to CSS custom properties + a typed theme; `rastack/theme`
|
|
7
|
+
* applies it at runtime. Filesystem-free, so it also runs in the browser.
|
|
8
|
+
*/
|
|
9
|
+
export * from "./src/tokens";
|