@trajectonomics/design-system-theme 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trajectonomics
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1,114 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _trajectonomics_design_system = require("@trajectonomics/design-system");
+// src/errors.ts
+/** Machine-readable rejection codes for Theme definition. */
+let ThemeErrorCode = /* @__PURE__ */ function(ThemeErrorCode) {
+	ThemeErrorCode["INVALID_THEME_NAME"] = "INVALID_THEME_NAME";
+	ThemeErrorCode["MISSING_TOKENS_SECTION"] = "MISSING_TOKENS_SECTION";
+	ThemeErrorCode["MISSING_CONTRACT_ROLE"] = "MISSING_CONTRACT_ROLE";
+	ThemeErrorCode["UNKNOWN_CONTRACT_ROLE"] = "UNKNOWN_CONTRACT_ROLE";
+	ThemeErrorCode["WRONG_TOKEN_TYPE"] = "WRONG_TOKEN_TYPE";
+	ThemeErrorCode["UNSAFE_TOKEN_VALUE"] = "UNSAFE_TOKEN_VALUE";
+	return ThemeErrorCode;
+}({});
+/** Error thrown when a Theme violates a domain rule; carries a distinct `code` and the offending `field`. */
+var ThemeError = class extends Error {
+	code;
+	field;
+	constructor(code, field, message) {
+		super(`[${code}]: ${message}`);
+		this.name = "ThemeError";
+		this.code = code;
+		this.field = field;
+	}
+};
+// src/validation.ts
+const TOKENS_FIELD = "tokens";
+const UNSAFE_VALUE = /[;}]|url\s*\(/i;
+const ROLE_NAMES = new Set(_trajectonomics_design_system.semanticTokenContract.roles.map((role) => role.name));
+function tokenField(roleName) {
+	return `${TOKENS_FIELD}.${roleName}`;
+}
+function validateThemeName(name) {
+	if (typeof name === "string" && name.trim().length > 0) return name.trim();
+	throw new ThemeError("INVALID_THEME_NAME", "name", "Theme name must be a non-empty string.");
+}
+function assertSafeValue(value, field) {
+	if (!UNSAFE_VALUE.test(value)) return;
+	throw new ThemeError("UNSAFE_TOKEN_VALUE", field, "A Theme token value must not contain characters that can break out of a CSS declaration.");
+}
+function assertTokenValue(role, value, field) {
+	if (typeof value !== "string") throw new ThemeError("WRONG_TOKEN_TYPE", field, `"${role.name}" takes a string.`);
+	assertSafeValue(value, field);
+	try {
+		return (0, _trajectonomics_design_system.createPrimitiveToken)({
+			name: role.name,
+			type: role.type,
+			value
+		}).value;
+	} catch (error) {
+		if (error instanceof _trajectonomics_design_system.DomainError && error.code === _trajectonomics_design_system.DomainErrorCode.INVALID_TOKEN_VALUE) throw new ThemeError("WRONG_TOKEN_TYPE", field, `"${role.name}" takes a ${role.type} value.`);
+		throw error;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Validates a Theme against the Contract, returning its normalized values. */
+function validateTheme(input) {
+	const candidate = isRecord(input) ? input : void 0;
+	const name = validateThemeName(candidate?.["name"]);
+	const tokens = candidate?.["tokens"];
+	if (!isRecord(tokens)) throw new ThemeError("MISSING_TOKENS_SECTION", TOKENS_FIELD, "A Theme must have a tokens section.");
+	const validated = {};
+	for (const role of _trajectonomics_design_system.semanticTokenContract.roles) {
+		const field = tokenField(role.name);
+		if (!Object.hasOwn(tokens, role.name)) throw new ThemeError("MISSING_CONTRACT_ROLE", field, `Theme is missing the Contract role "${role.name}".`);
+		validated[role.name] = assertTokenValue(role, tokens[role.name], field);
+	}
+	for (const roleName of Object.keys(tokens)) if (!ROLE_NAMES.has(roleName)) throw new ThemeError("UNKNOWN_CONTRACT_ROLE", tokenField(roleName), `"${roleName}" is not a role in the Semantic Token Contract.`);
+	return {
+		name,
+		tokens: validated
+	};
+}
+// src/define-theme.ts
+/** The checked factory for Themes: validates raw Theme data against the Semantic Token Contract. */
+function defineTheme(input) {
+	const validated = validateTheme(input);
+	return Object.freeze({
+		name: validated.name,
+		contractVersion: _trajectonomics_design_system.semanticTokenContract.version,
+		tokens: Object.freeze({ ...validated.tokens })
+	});
+}
+// src/theme-to-css.ts
+function escapeCssString(value) {
+	let escaped = "";
+	for (const character of value) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		if (character === "\\") escaped += "\\\\";
+		else if (character === "\"") escaped += "\\\"";
+		else if (codePoint < 32 || codePoint === 127) escaped += `\\${codePoint.toString(16)} `;
+		else escaped += character;
+	}
+	return escaped;
+}
+function cssVariableName(roleName) {
+	return `--ds-${roleName.replaceAll(".", "-")}`;
+}
+/** The Theme-to-CSS emitter: data-theme-scoped CSS custom properties for a valid Theme. */
+function themeToCss(theme) {
+	const validated = validateTheme(theme);
+	const declarations = _trajectonomics_design_system.semanticTokenContract.roles.map((role) => {
+		const value = validated.tokens[role.name];
+		return `  ${cssVariableName(role.name)}: ${value};`;
+	});
+	return `${`[data-theme="${escapeCssString(validated.name)}"]`} {\n${declarations.join("\n")}\n}\n`;
+}
+exports.ThemeError = ThemeError;
+exports.ThemeErrorCode = ThemeErrorCode;
+exports.defineTheme = defineTheme;
+exports.themeToCss = themeToCss;
+
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["semanticTokenContract","createPrimitiveToken","DomainError","DomainErrorCode","semanticTokenContract","semanticTokenContract"],"sources":["../src/errors.ts","../src/validation.ts","../src/define-theme.ts","../src/theme-to-css.ts"],"sourcesContent":["/** Machine-readable rejection codes for Theme definition. */\nexport enum ThemeErrorCode {\n\tINVALID_THEME_NAME = \"INVALID_THEME_NAME\",\n\tMISSING_TOKENS_SECTION = \"MISSING_TOKENS_SECTION\",\n\tMISSING_CONTRACT_ROLE = \"MISSING_CONTRACT_ROLE\",\n\tUNKNOWN_CONTRACT_ROLE = \"UNKNOWN_CONTRACT_ROLE\",\n\tWRONG_TOKEN_TYPE = \"WRONG_TOKEN_TYPE\",\n\tUNSAFE_TOKEN_VALUE = \"UNSAFE_TOKEN_VALUE\",\n}\n\n/** Error thrown when a Theme violates a domain rule; carries a distinct `code` and the offending `field`. */\nexport class ThemeError extends Error {\n\treadonly code: ThemeErrorCode\n\treadonly field: string\n\n\tconstructor(code: ThemeErrorCode, field: string, message: string) {\n\t\tsuper(`[${code}]: ${message}`)\n\t\tthis.name = \"ThemeError\"\n\t\tthis.code = code\n\t\tthis.field = field\n\t}\n}\n","import {\n\tcreatePrimitiveToken,\n\tDomainError,\n\tDomainErrorCode,\n\ttype SemanticTokenRole,\n\tsemanticTokenContract,\n} from \"@trajectonomics/design-system\"\nimport { ThemeError, ThemeErrorCode } from \"./errors\"\nimport type { ThemeInput } from \"./theme-input\"\n\nconst TOKENS_FIELD = \"tokens\"\nconst UNSAFE_VALUE = /[;}]|url\\s*\\(/i\nconst ROLE_NAMES = new Set(semanticTokenContract.roles.map((role) => role.name))\n\nfunction tokenField(roleName: string): string {\n\treturn `${TOKENS_FIELD}.${roleName}`\n}\n\nfunction validateThemeName(name: unknown): string {\n\tif (typeof name === \"string\" && name.trim().length > 0) return name.trim()\n\tthrow new ThemeError(\n\t\tThemeErrorCode.INVALID_THEME_NAME,\n\t\t\"name\",\n\t\t\"Theme name must be a non-empty string.\",\n\t)\n}\n\nfunction assertSafeValue(value: string, field: string): void {\n\tif (!UNSAFE_VALUE.test(value)) return\n\tthrow new ThemeError(\n\t\tThemeErrorCode.UNSAFE_TOKEN_VALUE,\n\t\tfield,\n\t\t\"A Theme token value must not contain characters that can break out of a CSS declaration.\",\n\t)\n}\n\nfunction assertTokenValue(role: SemanticTokenRole, value: unknown, field: string): string {\n\tif (typeof value !== \"string\") {\n\t\tthrow new ThemeError(ThemeErrorCode.WRONG_TOKEN_TYPE, field, `\"${role.name}\" takes a string.`)\n\t}\n\tassertSafeValue(value, field)\n\ttry {\n\t\treturn createPrimitiveToken({ name: role.name, type: role.type, value }).value\n\t} catch (error) {\n\t\tif (error instanceof DomainError && error.code === DomainErrorCode.INVALID_TOKEN_VALUE) {\n\t\t\tthrow new ThemeError(\n\t\t\t\tThemeErrorCode.WRONG_TOKEN_TYPE,\n\t\t\t\tfield,\n\t\t\t\t`\"${role.name}\" takes a ${role.type} value.`,\n\t\t\t)\n\t\t}\n\t\tthrow error\n\t}\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n\treturn typeof value === \"object\" && value !== null\n}\n\n/** Validates a Theme against the Contract, returning its normalized values. */\nexport function validateTheme(input: unknown): ThemeInput {\n\tconst candidate = isRecord(input) ? input : undefined\n\tconst name = validateThemeName(candidate?.[\"name\"])\n\tconst tokens = candidate?.[\"tokens\"]\n\tif (!isRecord(tokens)) {\n\t\tthrow new ThemeError(\n\t\t\tThemeErrorCode.MISSING_TOKENS_SECTION,\n\t\t\tTOKENS_FIELD,\n\t\t\t\"A Theme must have a tokens section.\",\n\t\t)\n\t}\n\tconst validated: Record<string, string> = {}\n\tfor (const role of semanticTokenContract.roles) {\n\t\tconst field = tokenField(role.name)\n\t\tif (!Object.hasOwn(tokens, role.name)) {\n\t\t\tthrow new ThemeError(\n\t\t\t\tThemeErrorCode.MISSING_CONTRACT_ROLE,\n\t\t\t\tfield,\n\t\t\t\t`Theme is missing the Contract role \"${role.name}\".`,\n\t\t\t)\n\t\t}\n\t\tvalidated[role.name] = assertTokenValue(role, tokens[role.name], field)\n\t}\n\tfor (const roleName of Object.keys(tokens)) {\n\t\tif (!ROLE_NAMES.has(roleName)) {\n\t\t\tthrow new ThemeError(\n\t\t\t\tThemeErrorCode.UNKNOWN_CONTRACT_ROLE,\n\t\t\t\ttokenField(roleName),\n\t\t\t\t`\"${roleName}\" is not a role in the Semantic Token Contract.`,\n\t\t\t)\n\t\t}\n\t}\n\treturn { name, tokens: validated }\n}\n","import type { Theme } from \"@trajectonomics/design-system\"\nimport { semanticTokenContract } from \"@trajectonomics/design-system\"\nimport type { ThemeInput } from \"./theme-input\"\nimport { validateTheme } from \"./validation\"\n\n/** The checked factory for Themes: validates raw Theme data against the Semantic Token Contract. */\nexport function defineTheme(input: ThemeInput): Theme {\n\tconst validated = validateTheme(input)\n\treturn Object.freeze({\n\t\tname: validated.name,\n\t\tcontractVersion: semanticTokenContract.version,\n\t\ttokens: Object.freeze({ ...validated.tokens }),\n\t})\n}\n","import { semanticTokenContract, type Theme } from \"@trajectonomics/design-system\"\nimport { validateTheme } from \"./validation\"\n\nfunction escapeCssString(value: string): string {\n\tlet escaped = \"\"\n\tfor (const character of value) {\n\t\tconst codePoint = character.codePointAt(0) ?? 0\n\t\tif (character === \"\\\\\") escaped += \"\\\\\\\\\"\n\t\telse if (character === '\"') escaped += '\\\\\"'\n\t\telse if (codePoint < 0x20 || codePoint === 0x7f) {\n\t\t\tescaped += `\\\\${codePoint.toString(16)} `\n\t\t} else escaped += character\n\t}\n\treturn escaped\n}\n\nfunction cssVariableName(roleName: string): string {\n\treturn `--ds-${roleName.replaceAll(\".\", \"-\")}`\n}\n\n/** The Theme-to-CSS emitter: data-theme-scoped CSS custom properties for a valid Theme. */\nexport function themeToCss(theme: Theme): string {\n\tconst validated = validateTheme(theme)\n\tconst declarations = semanticTokenContract.roles.map((role) => {\n\t\tconst value = validated.tokens[role.name]!\n\t\treturn `  ${cssVariableName(role.name)}: ${value};`\n\t})\n\tconst selector = `[data-theme=\"${escapeCssString(validated.name)}\"]`\n\treturn `${selector} {\\n${declarations.join(\"\\n\")}\\n}\\n`\n}\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -0,0 +1,27 @@
+import { Theme, Theme as Theme$1 } from "@trajectonomics/design-system";
+/** Input for defining a Theme: a name and tokens; a full Theme also fits, but its version is ignored. */
+interface ThemeInput {
+  readonly name: string;
+  readonly tokens: Readonly<Record<string, string>>;
+}
+/** The checked factory for Themes: validates raw Theme data against the Semantic Token Contract. */
+export declare function defineTheme(input: ThemeInput): Theme$1;
+/** Machine-readable rejection codes for Theme definition. */
+export declare enum ThemeErrorCode {
+  INVALID_THEME_NAME = "INVALID_THEME_NAME",
+  MISSING_TOKENS_SECTION = "MISSING_TOKENS_SECTION",
+  MISSING_CONTRACT_ROLE = "MISSING_CONTRACT_ROLE",
+  UNKNOWN_CONTRACT_ROLE = "UNKNOWN_CONTRACT_ROLE",
+  WRONG_TOKEN_TYPE = "WRONG_TOKEN_TYPE",
+  UNSAFE_TOKEN_VALUE = "UNSAFE_TOKEN_VALUE"
+}
+/** Error thrown when a Theme violates a domain rule; carries a distinct `code` and the offending `field`. */
+export declare class ThemeError extends Error {
+  readonly code: ThemeErrorCode;
+  readonly field: string;
+  constructor(code: ThemeErrorCode, field: string, message: string);
+}
+/** The Theme-to-CSS emitter: data-theme-scoped CSS custom properties for a valid Theme. */
+export declare function themeToCss(theme: Theme$1): string;
+export type { Theme, ThemeInput };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+import { Theme, Theme as Theme$1 } from "@trajectonomics/design-system";
+/** Input for defining a Theme: a name and tokens; a full Theme also fits, but its version is ignored. */
+interface ThemeInput {
+  readonly name: string;
+  readonly tokens: Readonly<Record<string, string>>;
+}
+/** The checked factory for Themes: validates raw Theme data against the Semantic Token Contract. */
+export declare function defineTheme(input: ThemeInput): Theme$1;
+/** Machine-readable rejection codes for Theme definition. */
+export declare enum ThemeErrorCode {
+  INVALID_THEME_NAME = "INVALID_THEME_NAME",
+  MISSING_TOKENS_SECTION = "MISSING_TOKENS_SECTION",
+  MISSING_CONTRACT_ROLE = "MISSING_CONTRACT_ROLE",
+  UNKNOWN_CONTRACT_ROLE = "UNKNOWN_CONTRACT_ROLE",
+  WRONG_TOKEN_TYPE = "WRONG_TOKEN_TYPE",
+  UNSAFE_TOKEN_VALUE = "UNSAFE_TOKEN_VALUE"
+}
+/** Error thrown when a Theme violates a domain rule; carries a distinct `code` and the offending `field`. */
+export declare class ThemeError extends Error {
+  readonly code: ThemeErrorCode;
+  readonly field: string;
+  constructor(code: ThemeErrorCode, field: string, message: string);
+}
+/** The Theme-to-CSS emitter: data-theme-scoped CSS custom properties for a valid Theme. */
+export declare function themeToCss(theme: Theme$1): string;
+export type { Theme, ThemeInput };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,110 @@
+import { DomainError, DomainErrorCode, createPrimitiveToken, semanticTokenContract } from "@trajectonomics/design-system";
+// src/errors.ts
+/** Machine-readable rejection codes for Theme definition. */
+let ThemeErrorCode = /* @__PURE__ */ function(ThemeErrorCode) {
+	ThemeErrorCode["INVALID_THEME_NAME"] = "INVALID_THEME_NAME";
+	ThemeErrorCode["MISSING_TOKENS_SECTION"] = "MISSING_TOKENS_SECTION";
+	ThemeErrorCode["MISSING_CONTRACT_ROLE"] = "MISSING_CONTRACT_ROLE";
+	ThemeErrorCode["UNKNOWN_CONTRACT_ROLE"] = "UNKNOWN_CONTRACT_ROLE";
+	ThemeErrorCode["WRONG_TOKEN_TYPE"] = "WRONG_TOKEN_TYPE";
+	ThemeErrorCode["UNSAFE_TOKEN_VALUE"] = "UNSAFE_TOKEN_VALUE";
+	return ThemeErrorCode;
+}({});
+/** Error thrown when a Theme violates a domain rule; carries a distinct `code` and the offending `field`. */
+var ThemeError = class extends Error {
+	code;
+	field;
+	constructor(code, field, message) {
+		super(`[${code}]: ${message}`);
+		this.name = "ThemeError";
+		this.code = code;
+		this.field = field;
+	}
+};
+// src/validation.ts
+const TOKENS_FIELD = "tokens";
+const UNSAFE_VALUE = /[;}]|url\s*\(/i;
+const ROLE_NAMES = new Set(semanticTokenContract.roles.map((role) => role.name));
+function tokenField(roleName) {
+	return `${TOKENS_FIELD}.${roleName}`;
+}
+function validateThemeName(name) {
+	if (typeof name === "string" && name.trim().length > 0) return name.trim();
+	throw new ThemeError("INVALID_THEME_NAME", "name", "Theme name must be a non-empty string.");
+}
+function assertSafeValue(value, field) {
+	if (!UNSAFE_VALUE.test(value)) return;
+	throw new ThemeError("UNSAFE_TOKEN_VALUE", field, "A Theme token value must not contain characters that can break out of a CSS declaration.");
+}
+function assertTokenValue(role, value, field) {
+	if (typeof value !== "string") throw new ThemeError("WRONG_TOKEN_TYPE", field, `"${role.name}" takes a string.`);
+	assertSafeValue(value, field);
+	try {
+		return createPrimitiveToken({
+			name: role.name,
+			type: role.type,
+			value
+		}).value;
+	} catch (error) {
+		if (error instanceof DomainError && error.code === DomainErrorCode.INVALID_TOKEN_VALUE) throw new ThemeError("WRONG_TOKEN_TYPE", field, `"${role.name}" takes a ${role.type} value.`);
+		throw error;
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Validates a Theme against the Contract, returning its normalized values. */
+function validateTheme(input) {
+	const candidate = isRecord(input) ? input : void 0;
+	const name = validateThemeName(candidate?.["name"]);
+	const tokens = candidate?.["tokens"];
+	if (!isRecord(tokens)) throw new ThemeError("MISSING_TOKENS_SECTION", TOKENS_FIELD, "A Theme must have a tokens section.");
+	const validated = {};
+	for (const role of semanticTokenContract.roles) {
+		const field = tokenField(role.name);
+		if (!Object.hasOwn(tokens, role.name)) throw new ThemeError("MISSING_CONTRACT_ROLE", field, `Theme is missing the Contract role "${role.name}".`);
+		validated[role.name] = assertTokenValue(role, tokens[role.name], field);
+	}
+	for (const roleName of Object.keys(tokens)) if (!ROLE_NAMES.has(roleName)) throw new ThemeError("UNKNOWN_CONTRACT_ROLE", tokenField(roleName), `"${roleName}" is not a role in the Semantic Token Contract.`);
+	return {
+		name,
+		tokens: validated
+	};
+}
+// src/define-theme.ts
+/** The checked factory for Themes: validates raw Theme data against the Semantic Token Contract. */
+function defineTheme(input) {
+	const validated = validateTheme(input);
+	return Object.freeze({
+		name: validated.name,
+		contractVersion: semanticTokenContract.version,
+		tokens: Object.freeze({ ...validated.tokens })
+	});
+}
+// src/theme-to-css.ts
+function escapeCssString(value) {
+	let escaped = "";
+	for (const character of value) {
+		const codePoint = character.codePointAt(0) ?? 0;
+		if (character === "\\") escaped += "\\\\";
+		else if (character === "\"") escaped += "\\\"";
+		else if (codePoint < 32 || codePoint === 127) escaped += `\\${codePoint.toString(16)} `;
+		else escaped += character;
+	}
+	return escaped;
+}
+function cssVariableName(roleName) {
+	return `--ds-${roleName.replaceAll(".", "-")}`;
+}
+/** The Theme-to-CSS emitter: data-theme-scoped CSS custom properties for a valid Theme. */
+function themeToCss(theme) {
+	const validated = validateTheme(theme);
+	const declarations = semanticTokenContract.roles.map((role) => {
+		const value = validated.tokens[role.name];
+		return `  ${cssVariableName(role.name)}: ${value};`;
+	});
+	return `${`[data-theme="${escapeCssString(validated.name)}"]`} {\n${declarations.join("\n")}\n}\n`;
+}
+export { ThemeError, ThemeErrorCode, defineTheme, themeToCss };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/errors.ts","../src/validation.ts","../src/define-theme.ts","../src/theme-to-css.ts"],"sourcesContent":["/** Machine-readable rejection codes for Theme definition. */\nexport enum ThemeErrorCode {\n\tINVALID_THEME_NAME = \"INVALID_THEME_NAME\",\n\tMISSING_TOKENS_SECTION = \"MISSING_TOKENS_SECTION\",\n\tMISSING_CONTRACT_ROLE = \"MISSING_CONTRACT_ROLE\",\n\tUNKNOWN_CONTRACT_ROLE = \"UNKNOWN_CONTRACT_ROLE\",\n\tWRONG_TOKEN_TYPE = \"WRONG_TOKEN_TYPE\",\n\tUNSAFE_TOKEN_VALUE = \"UNSAFE_TOKEN_VALUE\",\n}\n\n/** Error thrown when a Theme violates a domain rule; carries a distinct `code` and the offending `field`. */\nexport class ThemeError extends Error {\n\treadonly code: ThemeErrorCode\n\treadonly field: string\n\n\tconstructor(code: ThemeErrorCode, field: string, message: string) {\n\t\tsuper(`[${code}]: ${message}`)\n\t\tthis.name = \"ThemeError\"\n\t\tthis.code = code\n\t\tthis.field = field\n\t}\n}\n","import {\n\tcreatePrimitiveToken,\n\tDomainError,\n\tDomainErrorCode,\n\ttype SemanticTokenRole,\n\tsemanticTokenContract,\n} from \"@trajectonomics/design-system\"\nimport { ThemeError, ThemeErrorCode } from \"./errors\"\nimport type { ThemeInput } from \"./theme-input\"\n\nconst TOKENS_FIELD = \"tokens\"\nconst UNSAFE_VALUE = /[;}]|url\\s*\\(/i\nconst ROLE_NAMES = new Set(semanticTokenContract.roles.map((role) => role.name))\n\nfunction tokenField(roleName: string): string {\n\treturn `${TOKENS_FIELD}.${roleName}`\n}\n\nfunction validateThemeName(name: unknown): string {\n\tif (typeof name === \"string\" && name.trim().length > 0) return name.trim()\n\tthrow new ThemeError(\n\t\tThemeErrorCode.INVALID_THEME_NAME,\n\t\t\"name\",\n\t\t\"Theme name must be a non-empty string.\",\n\t)\n}\n\nfunction assertSafeValue(value: string, field: string): void {\n\tif (!UNSAFE_VALUE.test(value)) return\n\tthrow new ThemeError(\n\t\tThemeErrorCode.UNSAFE_TOKEN_VALUE,\n\t\tfield,\n\t\t\"A Theme token value must not contain characters that can break out of a CSS declaration.\",\n\t)\n}\n\nfunction assertTokenValue(role: SemanticTokenRole, value: unknown, field: string): string {\n\tif (typeof value !== \"string\") {\n\t\tthrow new ThemeError(ThemeErrorCode.WRONG_TOKEN_TYPE, field, `\"${role.name}\" takes a string.`)\n\t}\n\tassertSafeValue(value, field)\n\ttry {\n\t\treturn createPrimitiveToken({ name: role.name, type: role.type, value }).value\n\t} catch (error) {\n\t\tif (error instanceof DomainError && error.code === DomainErrorCode.INVALID_TOKEN_VALUE) {\n\t\t\tthrow new ThemeError(\n\t\t\t\tThemeErrorCode.WRONG_TOKEN_TYPE,\n\t\t\t\tfield,\n\t\t\t\t`\"${role.name}\" takes a ${role.type} value.`,\n\t\t\t)\n\t\t}\n\t\tthrow error\n\t}\n}\n\nfunction isRecord(value: unknown): value is Readonly<Record<string, unknown>> {\n\treturn typeof value === \"object\" && value !== null\n}\n\n/** Validates a Theme against the Contract, returning its normalized values. */\nexport function validateTheme(input: unknown): ThemeInput {\n\tconst candidate = isRecord(input) ? input : undefined\n\tconst name = validateThemeName(candidate?.[\"name\"])\n\tconst tokens = candidate?.[\"tokens\"]\n\tif (!isRecord(tokens)) {\n\t\tthrow new ThemeError(\n\t\t\tThemeErrorCode.MISSING_TOKENS_SECTION,\n\t\t\tTOKENS_FIELD,\n\t\t\t\"A Theme must have a tokens section.\",\n\t\t)\n\t}\n\tconst validated: Record<string, string> = {}\n\tfor (const role of semanticTokenContract.roles) {\n\t\tconst field = tokenField(role.name)\n\t\tif (!Object.hasOwn(tokens, role.name)) {\n\t\t\tthrow new ThemeError(\n\t\t\t\tThemeErrorCode.MISSING_CONTRACT_ROLE,\n\t\t\t\tfield,\n\t\t\t\t`Theme is missing the Contract role \"${role.name}\".`,\n\t\t\t)\n\t\t}\n\t\tvalidated[role.name] = assertTokenValue(role, tokens[role.name], field)\n\t}\n\tfor (const roleName of Object.keys(tokens)) {\n\t\tif (!ROLE_NAMES.has(roleName)) {\n\t\t\tthrow new ThemeError(\n\t\t\t\tThemeErrorCode.UNKNOWN_CONTRACT_ROLE,\n\t\t\t\ttokenField(roleName),\n\t\t\t\t`\"${roleName}\" is not a role in the Semantic Token Contract.`,\n\t\t\t)\n\t\t}\n\t}\n\treturn { name, tokens: validated }\n}\n","import type { Theme } from \"@trajectonomics/design-system\"\nimport { semanticTokenContract } from \"@trajectonomics/design-system\"\nimport type { ThemeInput } from \"./theme-input\"\nimport { validateTheme } from \"./validation\"\n\n/** The checked factory for Themes: validates raw Theme data against the Semantic Token Contract. */\nexport function defineTheme(input: ThemeInput): Theme {\n\tconst validated = validateTheme(input)\n\treturn Object.freeze({\n\t\tname: validated.name,\n\t\tcontractVersion: semanticTokenContract.version,\n\t\ttokens: Object.freeze({ ...validated.tokens }),\n\t})\n}\n","import { semanticTokenContract, type Theme } from \"@trajectonomics/design-system\"\nimport { validateTheme } from \"./validation\"\n\nfunction escapeCssString(value: string): string {\n\tlet escaped = \"\"\n\tfor (const character of value) {\n\t\tconst codePoint = character.codePointAt(0) ?? 0\n\t\tif (character === \"\\\\\") escaped += \"\\\\\\\\\"\n\t\telse if (character === '\"') escaped += '\\\\\"'\n\t\telse if (codePoint < 0x20 || codePoint === 0x7f) {\n\t\t\tescaped += `\\\\${codePoint.toString(16)} `\n\t\t} else escaped += character\n\t}\n\treturn escaped\n}\n\nfunction cssVariableName(roleName: string): string {\n\treturn `--ds-${roleName.replaceAll(\".\", \"-\")}`\n}\n\n/** The Theme-to-CSS emitter: data-theme-scoped CSS custom properties for a valid Theme. */\nexport function themeToCss(theme: Theme): string {\n\tconst validated = validateTheme(theme)\n\tconst declarations = semanticTokenContract.roles.map((role) => {\n\t\tconst value = validated.tokens[role.name]!\n\t\treturn `  ${cssVariableName(role.name)}: ${value};`\n\t})\n\tconst selector = `[data-theme=\"${escapeCssString(validated.name)}\"]`\n\treturn `${selector} {\\n${declarations.join(\"\\n\")}\\n}\\n`\n}\n"],"mappings":";;;AACA,IAAY,iBAAL,yBAAA,gBAAA;CACN,eAAA,wBAAA;CACA,eAAA,4BAAA;CACA,eAAA,2BAAA;CACA,eAAA,2BAAA;CACA,eAAA,sBAAA;CACA,eAAA,wBAAA;;AACD,EAAA,CAAA,CAAA;;AAGA,IAAa,aAAb,cAAgC,MAAM;CACrC;CACA;CAEA,YAAY,MAAsB,OAAe,SAAiB;EACjE,MAAM,IAAI,KAAK,KAAK,SAAS;EAC7B,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,QAAQ;CACd;AACD;;ACXA,MAAM,eAAe;AACrB,MAAM,eAAe;AACrB,MAAM,aAAa,IAAI,IAAI,sBAAsB,MAAM,KAAK,SAAS,KAAK,IAAI,CAAC;AAE/E,SAAS,WAAW,UAA0B;CAC7C,OAAO,GAAG,aAAa,GAAG;AAC3B;AAEA,SAAS,kBAAkB,MAAuB;CACjD,IAAI,OAAO,SAAS,YAAY,KAAK,KAAK,CAAC,CAAC,SAAS,GAAG,OAAO,KAAK,KAAK;CACzE,MAAM,IAAI,WAAA,sBAET,QACA,wCACD;AACD;AAEA,SAAS,gBAAgB,OAAe,OAAqB;CAC5D,IAAI,CAAC,aAAa,KAAK,KAAK,GAAG;CAC/B,MAAM,IAAI,WAAA,sBAET,OACA,0FACD;AACD;AAEA,SAAS,iBAAiB,MAAyB,OAAgB,OAAuB;CACzF,IAAI,OAAO,UAAU,UACpB,MAAM,IAAI,WAAA,oBAA4C,OAAO,IAAI,KAAK,KAAK,kBAAkB;CAE9F,gBAAgB,OAAO,KAAK;CAC5B,IAAI;EACH,OAAO,qBAAqB;GAAE,MAAM,KAAK;GAAM,MAAM,KAAK;GAAM;EAAM,CAAC,CAAC,CAAC;CAC1E,SAAS,OAAO;EACf,IAAI,iBAAiB,eAAe,MAAM,SAAS,gBAAgB,qBAClE,MAAM,IAAI,WAAA,oBAET,OACA,IAAI,KAAK,KAAK,YAAY,KAAK,KAAK,QACrC;EAED,MAAM;CACP;AACD;AAEA,SAAS,SAAS,OAA4D;CAC7E,OAAO,OAAO,UAAU,YAAY,UAAU;AAC/C;;AAGA,SAAgB,cAAc,OAA4B;CACzD,MAAM,YAAY,SAAS,KAAK,IAAI,QAAQ,KAAA;CAC5C,MAAM,OAAO,kBAAkB,YAAY,OAAO;CAClD,MAAM,SAAS,YAAY;CAC3B,IAAI,CAAC,SAAS,MAAM,GACnB,MAAM,IAAI,WAAA,0BAET,cACA,qCACD;CAED,MAAM,YAAoC,CAAC;CAC3C,KAAK,MAAM,QAAQ,sBAAsB,OAAO;EAC/C,MAAM,QAAQ,WAAW,KAAK,IAAI;EAClC,IAAI,CAAC,OAAO,OAAO,QAAQ,KAAK,IAAI,GACnC,MAAM,IAAI,WAAA,yBAET,OACA,uCAAuC,KAAK,KAAK,GAClD;EAED,UAAU,KAAK,QAAQ,iBAAiB,MAAM,OAAO,KAAK,OAAO,KAAK;CACvE;CACA,KAAK,MAAM,YAAY,OAAO,KAAK,MAAM,GACxC,IAAI,CAAC,WAAW,IAAI,QAAQ,GAC3B,MAAM,IAAI,WAAA,yBAET,WAAW,QAAQ,GACnB,IAAI,SAAS,gDACd;CAGF,OAAO;EAAE;EAAM,QAAQ;CAAU;AAClC;;;ACvFA,SAAgB,YAAY,OAA0B;CACrD,MAAM,YAAY,cAAc,KAAK;CACrC,OAAO,OAAO,OAAO;EACpB,MAAM,UAAU;EAChB,iBAAiB,sBAAsB;EACvC,QAAQ,OAAO,OAAO,EAAE,GAAG,UAAU,OAAO,CAAC;CAC9C,CAAC;AACF;;ACVA,SAAS,gBAAgB,OAAuB;CAC/C,IAAI,UAAU;CACd,KAAK,MAAM,aAAa,OAAO;EAC9B,MAAM,YAAY,UAAU,YAAY,CAAC,KAAK;EAC9C,IAAI,cAAc,MAAM,WAAW;OAC9B,IAAI,cAAc,MAAK,WAAW;OAClC,IAAI,YAAY,MAAQ,cAAc,KAC1C,WAAW,KAAK,UAAU,SAAS,EAAE,EAAE;OACjC,WAAW;CACnB;CACA,OAAO;AACR;AAEA,SAAS,gBAAgB,UAA0B;CAClD,OAAO,QAAQ,SAAS,WAAW,KAAK,GAAG;AAC5C;;AAGA,SAAgB,WAAW,OAAsB;CAChD,MAAM,YAAY,cAAc,KAAK;CACrC,MAAM,eAAe,sBAAsB,MAAM,KAAK,SAAS;EAC9D,MAAM,QAAQ,UAAU,OAAO,KAAK;EACpC,OAAO,KAAK,gBAAgB,KAAK,IAAI,EAAE,IAAI,MAAM;CAClD,CAAC;CAED,OAAO,GAAG,gBADuB,gBAAgB,UAAU,IAAI,EAAE,IAC9C,MAAM,aAAa,KAAK,IAAI,EAAE;AAClD"}

package/dist/themes/dark.css

@@ -0,0 +1,21 @@
+[data-theme="dark"] {
+  --ds-color-background: #0a0a0a;
+  --ds-color-foreground: #fafafa;
+  --ds-color-card: #171717;
+  --ds-color-card-foreground: #fafafa;
+  --ds-color-popover: #171717;
+  --ds-color-popover-foreground: #fafafa;
+  --ds-color-primary: #e5e5e5;
+  --ds-color-primary-foreground: #171717;
+  --ds-color-secondary: #262626;
+  --ds-color-secondary-foreground: #fafafa;
+  --ds-color-muted: #262626;
+  --ds-color-muted-foreground: #a1a1a1;
+  --ds-color-accent: #262626;
+  --ds-color-accent-foreground: #fafafa;
+  --ds-color-destructive: #ff6467;
+  --ds-color-destructive-foreground: #ffffff;
+  --ds-color-border: #262626;
+  --ds-color-input: #262626;
+  --ds-color-ring: #737373;
+}

package/dist/themes/light.css

@@ -0,0 +1,21 @@
+[data-theme="light"] {
+  --ds-color-background: #ffffff;
+  --ds-color-foreground: #0a0a0a;
+  --ds-color-card: #ffffff;
+  --ds-color-card-foreground: #0a0a0a;
+  --ds-color-popover: #ffffff;
+  --ds-color-popover-foreground: #0a0a0a;
+  --ds-color-primary: #171717;
+  --ds-color-primary-foreground: #fafafa;
+  --ds-color-secondary: #f5f5f5;
+  --ds-color-secondary-foreground: #171717;
+  --ds-color-muted: #f5f5f5;
+  --ds-color-muted-foreground: #737373;
+  --ds-color-accent: #f5f5f5;
+  --ds-color-accent-foreground: #171717;
+  --ds-color-destructive: #e7000b;
+  --ds-color-destructive-foreground: #ffffff;
+  --ds-color-border: #e5e5e5;
+  --ds-color-input: #e5e5e5;
+  --ds-color-ring: #a1a1a1;
+}

package/package.json

@@ -1,6 +1,65 @@
 {
-  "name": "@trajectonomics/design-system-theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@trajectonomics/design-system-theme",
+	"version": "0.1.0-alpha.0",
+	"description": "Trajectonomics design system: Theme definition, validation and CSS emission",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/trajectonomics/design-system.git",
+		"directory": "packages/theme"
+	},
+	"type": "module",
+	"sideEffects": [
+		"**/*.css"
+	],
+	"engines": {
+		"node": ">=20.0.0"
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.cts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.cts",
+				"default": "./dist/index.cjs"
+			}
+		},
+		"./themes/light.css": "./dist/themes/light.css",
+		"./themes/dark.css": "./dist/themes/dark.css",
+		"./tailwind.css": "./tailwind.css",
+		"./package.json": "./package.json"
+	},
+	"files": [
+		"dist",
+		"tailwind.css"
+	],
+	"publishConfig": {
+		"access": "public",
+		"provenance": true,
+		"tag": "latest"
+	},
+	"scripts": {
+		"build": "tsdown && bun run build:css",
+		"build:css": "bun run scripts/build-theme-css.ts",
+		"generate:tailwind": "bun run scripts/generate-tailwind-theme.ts",
+		"test": "bun test",
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json && tsc -p tsconfig.scripts.json",
+		"lint": "biome ci --error-on-warnings .",
+		"lint:package": "publint --strict && attw --pack . --profile node16 --exclude-entrypoints ./themes/light.css ./themes/dark.css ./tailwind.css"
+	},
+	"peerDependencies": {
+		"@trajectonomics/design-system": "^0.1.0-alpha.0"
+	},
+	"devDependencies": {
+		"@tailwindcss/cli": "^4.3.5",
+		"@trajectonomics/design-system": "workspace:*",
+		"@types/bun": "^1.4.4",
+		"tailwindcss": "^4.3.5",
+		"typescript": "^7.0.2"
+	}
+}

package/tailwind.css

@@ -0,0 +1,21 @@
+@theme inline {
+	--color-background: var(--ds-color-background);
+	--color-foreground: var(--ds-color-foreground);
+	--color-card: var(--ds-color-card);
+	--color-card-foreground: var(--ds-color-card-foreground);
+	--color-popover: var(--ds-color-popover);
+	--color-popover-foreground: var(--ds-color-popover-foreground);
+	--color-primary: var(--ds-color-primary);
+	--color-primary-foreground: var(--ds-color-primary-foreground);
+	--color-secondary: var(--ds-color-secondary);
+	--color-secondary-foreground: var(--ds-color-secondary-foreground);
+	--color-muted: var(--ds-color-muted);
+	--color-muted-foreground: var(--ds-color-muted-foreground);
+	--color-accent: var(--ds-color-accent);
+	--color-accent-foreground: var(--ds-color-accent-foreground);
+	--color-destructive: var(--ds-color-destructive);
+	--color-destructive-foreground: var(--ds-color-destructive-foreground);
+	--color-border: var(--ds-color-border);
+	--color-input: var(--ds-color-input);
+	--color-ring: var(--ds-color-ring);
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.