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.
Files changed (51) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/dist/rastack-design.d.ts +17 -0
  3. package/dist/rastack-design.js +134 -0
  4. package/dist/rastack-tokens.d.ts +15 -0
  5. package/dist/rastack-tokens.js +43 -0
  6. package/dist/rastack-wasm-build.d.ts +1 -1
  7. package/dist/rastack-wasm-build.js +3 -3
  8. package/dist/rastack.d.ts +2 -0
  9. package/dist/rastack.js +12 -0
  10. package/dist/tokens/color.d.ts +22 -0
  11. package/dist/tokens/color.js +70 -0
  12. package/dist/tokens/compile.d.ts +34 -0
  13. package/dist/tokens/compile.js +103 -0
  14. package/dist/tokens/css.d.ts +30 -0
  15. package/dist/tokens/css.js +102 -0
  16. package/dist/tokens/define.d.ts +71 -0
  17. package/dist/tokens/define.js +98 -0
  18. package/dist/tokens/index.d.ts +17 -0
  19. package/dist/tokens/index.js +33 -0
  20. package/dist/tokens/resolve.d.ts +40 -0
  21. package/dist/tokens/resolve.js +135 -0
  22. package/dist/tokens/studio.d.ts +21 -0
  23. package/dist/tokens/studio.js +328 -0
  24. package/dist/tokens/theme.d.ts +55 -0
  25. package/dist/tokens/theme.js +139 -0
  26. package/dist/tokens/ts.d.ts +15 -0
  27. package/dist/tokens/ts.js +73 -0
  28. package/dist/tokens/types.d.ts +92 -0
  29. package/dist/tokens/types.js +35 -0
  30. package/hooks/query/delete.ts +3 -1
  31. package/jest.config.cjs +6 -0
  32. package/package.json +3 -2
  33. package/src/rastack-design.ts +117 -0
  34. package/src/rastack-tokens.ts +46 -0
  35. package/src/rastack-wasm-build.ts +3 -3
  36. package/src/rastack.ts +12 -0
  37. package/src/tokens/color.ts +74 -0
  38. package/src/tokens/compile.ts +85 -0
  39. package/src/tokens/css.ts +138 -0
  40. package/src/tokens/define.ts +128 -0
  41. package/src/tokens/index.ts +18 -0
  42. package/src/tokens/resolve.ts +170 -0
  43. package/src/tokens/studio.ts +357 -0
  44. package/src/tokens/theme.ts +180 -0
  45. package/src/tokens/ts.ts +80 -0
  46. package/src/tokens/types.ts +125 -0
  47. package/test/tokens.spec.ts +302 -0
  48. package/theme/index.ts +9 -0
  49. package/theme/provider.tsx +157 -0
  50. package/tokens.ts +9 -0
  51. 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";
package/tsconfig.json CHANGED
@@ -11,6 +11,9 @@
11
11
  ],
12
12
  "outDir": "dist",
13
13
  "rootDir": "src",
14
+ "paths": {
15
+ "rastack/tokens": ["./tokens.ts"]
16
+ },
14
17
  "declaration": true,
15
18
  "esModuleInterop": true,
16
19
  "forceConsistentCasingInFileNames": true,