@canonical/terrazzo-plugin-css 0.0.1

package/dist/types/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Type definitions for @canonical/terrazzo-plugin-css-v2.
+ *
+ * Types-first: every public contract is defined here before any
+ * implementation code exists.
+ */
+/** CSS @layer names. Set a value to `null` to omit the layer wrapper. */
+export interface LayerConfig {
+    /** Wraps sets (primitive, semantic). @default "ds.tokens" */
+    tokens: string | null;
+    /** Wraps modifier outputs (theme, typography, families). @default "ds.modifiers" */
+    modifiers: string | null;
+    /** Wraps surface class output. @default "ds.surfaces" */
+    surfaces: string | null;
+    /** Wraps derivation layer (states.css). @default "ds.states" */
+    states: string | null;
+}
+/** Color-scheme mapping for the theme modifier. */
+export interface ThemeColorScheme {
+    /** Resolver context name that maps to CSS `color-scheme: light`. */
+    light: string;
+    /** Resolver context name that maps to CSS `color-scheme: dark`. */
+    dark: string;
+    /** Which context is the default. @default "light" */
+    default: string;
+}
+/** CSS selectors for theme output. */
+export interface ThemeSelectors {
+    /** Merged `light-dark()` block selector. @default ":root" */
+    root?: string;
+    /** `color-scheme: light` override selector. @default ".light" */
+    light?: string;
+    /** `color-scheme: dark` override selector. @default ".dark" */
+    dark?: string;
+}
+/** Theme modifier configuration. */
+export interface ThemeConfig {
+    /** Resolver modifier name. */
+    modifier: string;
+    /** Color-scheme mapping. */
+    colorScheme: ThemeColorScheme;
+    /** Override CSS selectors. */
+    selectors?: ThemeSelectors;
+    /** Media query feature name, or `false` to omit. @default "prefers-color-scheme" */
+    media?: string | false;
+}
+/** Set-level filtering. */
+export interface SetConfig {
+    /** Glob patterns to exclude from the set output. */
+    exclude?: string[];
+}
+/** Typography modifier configuration. */
+export interface TypographyConfig {
+    /** Resolver modifier name. */
+    modifier: string;
+}
+/** Media-driven modifier configuration (motion, contrast). */
+export interface MediaModifierConfig {
+    /** Resolver modifier name. */
+    modifier: string;
+    /** Media feature name (e.g. "prefers-reduced-motion"). */
+    media: string;
+    /** Class-based override selectors, keyed by context name. */
+    selectors?: Record<string, string>;
+}
+/** NativeState derivation layer configuration. */
+export interface StatesConfig {
+    /** CSS selector for the derivation block. @default "*" */
+    selector: string;
+}
+/** Top-level plugin options. */
+export interface CanonicalPluginOptions {
+    /** CSS @layer names. */
+    layers?: Partial<LayerConfig>;
+    /** Set configurations (primitive, semantic). */
+    sets?: {
+        primitive?: SetConfig;
+        semantic?: SetConfig;
+    };
+    /** Theme modifier (light/dark with light-dark()). */
+    theme?: ThemeConfig;
+    /** Typography modifier. */
+    typography?: TypographyConfig;
+    /** Modifier family names (e.g. ["anticipation", "criticality"]). */
+    families?: string[];
+    /** Motion preference modifier. */
+    motion?: MediaModifierConfig;
+    /** Contrast preference modifier. */
+    contrast?: MediaModifierConfig;
+    /** Surface configuration. */
+    surfaces?: Record<string, never>;
+    /** NativeState derivation layer. */
+    states?: StatesConfig;
+    /**
+     * Base directory for token source files.
+     * Used to locate modifier source files and read `$extensions.com.canonical.modifier.aliasOf`.
+     * @default "./tokens/canonical"
+     */
+    tokensDir?: string;
+}
+/** Fully resolved layer config with defaults applied. */
+export interface ResolvedLayerConfig {
+    tokens: string | null;
+    modifiers: string | null;
+    surfaces: string | null;
+    states: string | null;
+}
+/** Fully resolved theme config with defaults applied. */
+export interface ResolvedThemeConfig {
+    modifier: string;
+    light: string;
+    dark: string;
+    defaultScheme: string;
+    rootSelector: string;
+    lightSelector: string;
+    darkSelector: string;
+    media: string | false;
+}
+export interface CSSDeclaration {
+    type: "Declaration";
+    property: string;
+    value: string;
+    comment?: string;
+}
+export interface CSSRule {
+    type: "Rule";
+    prelude: string[];
+    children: (CSSRule | CSSDeclaration)[];
+}
+export type CSSNode = CSSRule | CSSDeclaration;
+export interface PrintOptions {
+    indentChar?: string;
+    indentLv?: number;
+}
+/** Tier classification for a token. */
+export type TokenTier = "primitive" | "semantic" | "derived";
+/** Derivation formula kind for derived-tier tokens. */
+export type DerivationKind = "hover" | "active" | "disabled" | "delta" | "channel-modifier" | "channel-surface";
+/** A declaration site for an artifact token. */
+export interface ArtifactDeclaration {
+    /** CSS selector (e.g. ":root", ".warning", "*"). */
+    selector: string;
+    /** CSS output file (e.g. "modifiers.theme.css"). */
+    file: string;
+    /** 0-indexed line number in the CSS output file. */
+    line: number;
+}
+/** A single token entry in the LSP artifact. */
+export interface ArtifactToken {
+    /** CSS custom property name as emitted. */
+    cssVar: string;
+    /** DTCG token ID from source, or `null` for derived tokens. */
+    id: string | null;
+    /** DTCG $type. */
+    type: string;
+    /** Token tier classification. */
+    tier: TokenTier;
+    /** DTCG $description. */
+    description?: string;
+    /** Full alias resolution chain (token IDs). */
+    aliasChain?: string[];
+    /** Light-mode resolved CSS value. */
+    valueLight?: string;
+    /** Dark-mode resolved CSS value. */
+    valueDark?: string;
+    /** `true` when valueLight !== valueDark. */
+    isPaired: boolean;
+    /** DTCG source file path (relative). */
+    sourceFile?: string;
+    /** Line number in the DTCG source file. */
+    sourceLine?: number;
+    /** CSS output file containing this token's declaration. */
+    cssOutputFile: string;
+    /** Declaration sites: where this token is provided in the CSS output. */
+    declarations?: ArtifactDeclaration[];
+    /** CSS var name of the source token (derived tier). */
+    derivedFrom?: string;
+    /** Formula kind (derived tier). */
+    derivation?: DerivationKind;
+}
+/** The complete LSP artifact: CSS variable name -> token metadata. */
+export type Artifact = Record<string, ArtifactToken>;
+/** A light/dark value pair for theme-aware tokens. */
+export interface LightDarkPair {
+    /** CSS variable name (without `var()`). */
+    property: string;
+    /** Light-mode CSS value. */
+    light: string;
+    /** Dark-mode CSS value. */
+    dark: string;
+}
+/** Per-role delta values for NativeState derivation. */
+export interface StateDelta {
+    /** Semantic role (e.g. "color-foreground-primary"). */
+    role: string;
+    /** State kind (e.g. "hover", "active"). */
+    state: string;
+    /** Light-mode oklch L delta. */
+    lightDelta: number;
+    /** Dark-mode oklch L delta. */
+    darkDelta: number;
+}
+/** Minimal token shape for overlay detection. */
+export interface OverlayToken {
+    source?: {
+        loc?: unknown;
+    };
+    $value?: unknown;
+    aliasOf?: string;
+    $extensions?: Record<string, unknown>;
+}
+/** A modifier family context with its resolved CSS class declarations. */
+export interface ModifierContext {
+    /** Family name (e.g. "anticipation"). */
+    family: string;
+    /** Context name (e.g. "constructive"). */
+    context: string;
+    /** CSS class selector (e.g. ".constructive"). */
+    selector: string;
+    /** Declarations: --modifier-{role}: var(--{aliasTarget}). */
+    declarations: CSSDeclaration[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@canonical/terrazzo-plugin-css",
+  "version": "0.0.1",
+  "description": "Terrazzo CSS plugin for Canonical design tokens. Transforms DTCG tokens into CSS custom properties with light-dark(), modifier families, @layer ordering, and @media scoping.",
+  "type": "module",
+  "license": "LGPL-3.0",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run build:tsc",
+    "build:all": "bun run build",
+    "build:tsc": "tsc -p tsconfig.build.json",
+    "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
+    "check:webarchitect": "webarchitect library",
+    "check:fix": "bun run check:biome:fix && bun run check:ts",
+    "check:biome": "biome check",
+    "check:biome:fix": "biome check --write",
+    "check:ts": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@canonical/webarchitect": "^0.17.1",
+    "@terrazzo/token-tools": "2.0.0-beta.6",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}