@slotted/theme 0.0.0-stage → 0.1.0-beta.0

package/dist/types/index.d.ts

@@ -0,0 +1,24 @@
+export { contrast, deltaE, fromSrgb, parseSeed, relativeLuminance, toHex, toLinearSrgb, } from './color';
+export type { Luminance, Oklch } from './color';
+export { LAYER_NAMES, LAYER_ORDER_STATEMENT } from './layer-order';
+export { applyBounds, boundCss, boundValue, fitBound } from './bound';
+export type { Bound } from './bound';
+export { derivationCss, evaluateRecipe, SCHEMES, SEED_NAMES } from './recipe';
+export type { AliasDerivation, Derivation, MixDerivation, Recipe, Scheme, SeedDerivation, SeedName, } from './recipe';
+export { checkScheme, CONTRAST_REQUIREMENT, seedGrid } from './recipe-checks';
+export { recipes } from './recipes';
+export type { TokenContract, TokenDefinition } from './contract-types';
+export { DENSITIES, defineTheme, extendTheme, flattenTheme } from './define';
+export type { Density, FontFaceDefinition, Theme, ThemeDefinition, ThemeOverrides } from './define';
+export { COMPONENT_TOKENS, contract } from './generated/contract';
+export type { BaseToken, ColorToken, ComponentToken, DensityToken, MotionToken, SchemeToken, } from './generated/contract';
+export { resolveTokens } from './resolve';
+export { validateContract, validateTheme } from './validate';
+export type { FlatTheme } from './validate';
+export { renderTheme } from './render';
+export { splitTopLevel } from './rules';
+export { ruleErrors } from './rule-policy';
+export type { RuleError } from './rule-policy';
+export { applyTheme, THEME_CHANGE_EVENT } from './apply';
+export { seedStyle } from './seeds';
+export type { ThemeChangeDetail } from './apply';

package/dist/types/layer-order.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `slotted` is the only top-level layer. `theme-rules` holds the rules a theme
+ * carries, after the family stylesheets they adjust, so a theme rule wins by
+ * layer order and never by specificity. `reset` and `tokens` hold no rule;
+ * they are declared because a layer takes its position from the first
+ * mention of its name.
+ */
+export declare const LAYER_NAMES: readonly ["reset", "tokens", "theme", "components", "theme-rules"];
+export declare const LAYER_ORDER_STATEMENT: string;

package/dist/types/recipe-checks.d.ts

@@ -0,0 +1,11 @@
+import { type Oklch } from './color';
+import type { Scheme } from './recipe';
+/** The text ratio each scheme promises. `high-contrast` earns its name at AAA. */
+export declare const CONTRAST_REQUIREMENT: Readonly<Record<Scheme, number>>;
+/**
+ * The ratios of `theme-conformance` over evaluated colours, as messages. A
+ * recipe passes when every seed of `seedGrid()` leaves this list empty.
+ */
+export declare function checkScheme(values: Readonly<Record<string, Oklch>>, scheme: Scheme): string[];
+/** Hue 0–345 by 15, chroma 0–0.35 by 0.05, lightness 0.2–0.95 by 0.05: 3072 seeds. */
+export declare function seedGrid(): Oklch[];

package/dist/types/recipe.d.ts

@@ -0,0 +1,41 @@
+import { type Bound } from './bound';
+import type { Oklch } from './color';
+import { SEED_NAMES, type SeedName } from './seeds';
+export { SEED_NAMES, type SeedName };
+export declare const SCHEMES: readonly ["light", "dark", "high-contrast"];
+export type Scheme = (typeof SCHEMES)[number];
+/** A colour taken from a seed: fixed or offset lightness, scaled chroma, shifted hue. */
+export interface SeedDerivation {
+    readonly seed: SeedName;
+    readonly l: number | {
+        readonly offset: number;
+        readonly min?: number;
+        readonly max?: number;
+    };
+    readonly c: {
+        readonly scale: number;
+        readonly max: number;
+    };
+    readonly h?: number;
+    readonly bounds?: readonly Bound[];
+}
+/** A colour moved `share` toward white, or toward black when its lightness is above 0.9. */
+export interface MixDerivation {
+    readonly mix: string;
+    readonly share: number;
+    readonly bounds?: readonly Bound[];
+}
+export interface AliasDerivation {
+    readonly alias: string;
+}
+export type Derivation = SeedDerivation | MixDerivation | AliasDerivation;
+/** Per scheme, the derivation of every colour token the recipe owns. */
+export type Recipe = Readonly<Record<Scheme, Readonly<Record<string, Derivation>>>>;
+/**
+ * Every token of one scheme, computed with the arithmetic `derivationCss`
+ * writes: the browser's `oklch(from …)` and `color-mix(in oklch, …)` on the
+ * same constants.
+ */
+export declare function evaluateRecipe(recipe: Recipe, seeds: Readonly<Record<SeedName, Oklch>>, scheme: Scheme): Record<string, Oklch>;
+/** The CSS value of one derivation. */
+export declare function derivationCss(rule: Derivation): string;

package/dist/types/recipes/index.d.ts

@@ -0,0 +1,4 @@
+import type { Recipe } from '../recipe';
+export declare const recipes: {
+    readonly standard: Recipe;
+};

package/dist/types/recipes/standard.d.ts

@@ -0,0 +1,2 @@
+import type { Recipe } from '../recipe';
+export declare const standard: Recipe;

package/dist/types/render.d.ts

@@ -0,0 +1,6 @@
+import { type Theme } from './define';
+/**
+ * The stylesheet of one theme. The theme is checked as `defineTheme` checks
+ * it, and the text is safe to inline in an HTML `<style>`.
+ */
+export declare function renderTheme(theme: Theme): string;

package/dist/types/resolve.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Expands the `var()` references a token map makes to itself. It is not a CSS
+ * engine: it resolves within one map, which is what one theme block is.
+ */
+export declare function resolveTokens(values: Readonly<Record<string, string>>): Record<string, string>;

package/dist/types/rule-policy.d.ts

@@ -0,0 +1,41 @@
+/**
+ * What a theme rule may select and read (design §10.2, ADR 0004). A rule
+ * selects only what a binding renders on purpose — a family by `data-ui`, its
+ * parts by `data-part`, and the `data-*` attributes a family or the theme
+ * axes set — and reads only tokens. Everything else is an implementation
+ * detail of a family stylesheet, which changes without notice.
+ *
+ * `defineTheme` (every rule given as text) and `slotted-build-theme` (every
+ * rule, after lightningcss has parsed it) both call `ruleErrors`, so the two
+ * paths hold one policy.
+ */
+/** One violation: the 1-based line in the rule text, the selector of the rule it sits in, and why. */
+export interface RuleError {
+    readonly line: number;
+    readonly selector: string;
+    readonly message: string;
+}
+/**
+ * The reasons a selector list breaks the policy, each naming the part of the
+ * selector at fault. `nested` is true for a rule inside a style rule, where
+ * `&` is that rule's element.
+ */
+export declare function selectorErrors(selector: string, nested?: boolean): string[];
+/** The reason a declaration writes a property no theme may write, or `undefined`. */
+export declare function propertyWriteError(name: string): string | undefined;
+/**
+ * The reason a `var()`, or a `style()` query in a value or in `@container`,
+ * reads a property no theme may read, or `undefined`.
+ */
+export declare function tokenReadError(name: string, reader?: 'var' | 'style'): string | undefined;
+/**
+ * Every policy violation in a theme's CSS text: each style rule's selector,
+ * nested rules and rules in conditional groups included; every `@scope`,
+ * `@import` and `@layer`, at any depth; every `@property` naming a private
+ * property or a token; every declaration that writes a private property or
+ * stands outside a style rule; and every `var()` and `style()` query the text
+ * reads, outside strings and comments, with escapes in the function and
+ * property names decoded. The
+ * text is taken to be balanced; `splitTopLevel` refuses one that is not.
+ */
+export declare function ruleErrors(css: string): RuleError[];

package/dist/types/rules.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Splits CSS into its top-level statements: a block ends at the brace that
+ * returns to depth 0, an at-statement at the semicolon. Strings and comments
+ * are skipped, so a brace inside `content: "}"` does not end a rule.
+ *
+ * A theme rule is text a theme author wrote, concatenated with every other
+ * rule into one `@layer`, so an unbalanced `}` here would close that layer
+ * (or the `@scope` around it) early and let the rest of the input escape its
+ * boundary. The five malformed shapes below are refused rather than silently
+ * reinterpreted: a closing brace with nothing open, braces still open at the
+ * end, a string never closed (or ended by a newline), a comment never closed,
+ * and a trailing `\` that would escape whatever the compiler writes next.
+ */
+export declare function splitTopLevel(css: string): string[];
+/**
+ * The rules of one theme, ready for the compiler: `@keyframes`, `@font-face`
+ * and `@property` leave the scope they cannot live in, and every keyframes
+ * name takes the theme's prefix so two themes on one page never collide.
+ * `renderTheme` calls it only on rules `ruleErrors` accepted, which refuses
+ * `@scope`, `@import` and `@layer` at any depth.
+ */
+export declare function processRules(themeName: string, sources: readonly string[]): {
+    hoisted: string[];
+    body: string;
+};

package/dist/types/seeds.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The seeds: the colours every derived colour token is computed from. This
+ * module is the entry `@slotted/theme/seeds`, which writes a reader's seeds
+ * without loading the contract, the validator or the renderer.
+ */
+export declare const SEED_NAMES: readonly ["accent", "neutral", "success", "warning", "danger"];
+export type SeedName = (typeof SEED_NAMES)[number];
+/** The `style` object that gives an element its own seeds, for React `style` and Angular `[style]`. */
+export declare function seedStyle(seeds: Readonly<Partial<Record<SeedName, string>>>): Record<string, string>;

package/dist/types/validate.d.ts

@@ -0,0 +1,26 @@
+import type { TokenContract } from './contract-types';
+type Values = Record<string, string>;
+/** The resolved shape of a theme: what `flattenTheme` returns and what the contract is checked on. */
+export interface FlatTheme {
+    readonly name: string;
+    readonly base: Values;
+    readonly schemes: Readonly<Record<string, Values>>;
+    readonly densities: Readonly<Record<string, Values>>;
+    readonly reducedMotion: Values;
+}
+/**
+ * A token value, a component value or a font field is interpolated into CSS
+ * text verbatim (`render.ts` writes `${name}: ${value};` and the like). An
+ * unquoted, uncommented `;`, `{` or `}` inside it would close the
+ * declaration, the rule or the `@layer`/`@scope` it is written into, and a
+ * string or comment the value leaves open, or a trailing `\` escaping the
+ * character written after it, would do the same to whatever follows it in
+ * the stylesheet — so all of them are rejected here, and so is a value that
+ * is not a string, which `String()` could turn into any text. `url("a;b.woff2")`
+ * and `"1px /* comment *\/"` stay legitimate: the scan this shares with
+ * `splitTopLevel` skips a structural character inside either.
+ */
+export declare function hasUnsafeStructuralChar(value: unknown): boolean;
+export declare function validateContract(contract: TokenContract): string[];
+export declare function validateTheme(contract: TokenContract, theme: Partial<FlatTheme>): string[];
+export {};

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@slotted/theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrelopes-code/slotted.git",
+    "directory": "packages/theme"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "src/contract.json",
+    "cli",
+    "conformance"
+  ],
+  "bin": {
+    "slotted-build-theme": "./cli/build-theme.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./layer-order": {
+      "types": "./dist/types/layer-order.d.ts",
+      "import": "./dist/layer-order.js"
+    },
+    "./seeds": {
+      "types": "./dist/types/seeds.d.ts",
+      "import": "./dist/seeds.js"
+    },
+    "./contract.json": "./src/contract.json",
+    "./conformance": "./conformance/theme-conformance.mjs",
+    "./styles.css": "./dist/styles.css"
+  },
+  "dependencies": {
+    "lightningcss": "1.33.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "jsdom": "30.0.1",
+    "typescript": "6.0.3",
+    "vite": "8.2.2",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "generate": "node scripts/generate-sources.mjs",
+    "build": "vite build && tsc -p tsconfig.build.json && node scripts/write-styles.mjs",
+    "test": "vitest run && node --test test/*.test.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit --pretty false",
+    "verify": "pnpm build && pnpm test && pnpm typecheck"
+  }
 }