@canonical/terrazzo-plugin-css 0.3.1 → 0.4.0

package/dist/types/types/src/artifact/types.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Canonical artifact types — the JSON contract between the Terrazzo CSS plugin
+ * (producer) and the LSP (consumer).
+ *
+ * This is the single source of truth. Both `@canonical/terrazzo-plugin-css` and
+ * `@canonical/terrazzo-lsp` import from this package.
+ */
+/** Tier classification for a token. */
+export type TokenTier = "primitive" | "semantic" | "derived";
+/** Shared list of known DTCG token type literals recognised by Canonical tooling. */
+export declare const KNOWN_DTCG_TOKEN_TYPES: readonly ["color", "dimension", "number", "typography", "fontFamily", "fontWeight", "fontStyle", "figureStyle", "textDecoration", "letterCase", "fontPosition", "duration", "cubicBezier", "gradient", "border", "shadow", "transition", "strokeStyle"];
+/** Known DTCG token type literals recognised by Canonical tooling. */
+export type KnownDtcgTokenType = (typeof KNOWN_DTCG_TOKEN_TYPES)[number];
+/**
+ * DTCG $type values used by the Canonical token system.
+ *
+ * The `(string & {})` arm preserves backward compatibility — callers may
+ * pass arbitrary strings without a type error, but autocomplete still
+ * suggests the known literals.
+ */
+export type DtcgTokenType = KnownDtcgTokenType | (string & {});
+/** Runtime guard for narrowing unknown strings to the shared known DTCG set. */
+export declare function isKnownDtcgTokenType(value: string | null | undefined): value is KnownDtcgTokenType;
+/** Derivation formula kind for derived-tier tokens. */
+export type DerivationKind = "hover" | "active" | "disabled" | "delta" | "channel-modifier" | "channel-surface";
+/** An at-rule context surrounding a declaration (e.g. `@layer ds.modifiers`). */
+export interface ArtifactAtRule {
+    /** At-rule name (e.g. "layer", "media"). */
+    name: string;
+    /** At-rule prelude (e.g. "ds.modifiers", "(prefers-color-scheme: dark)"). */
+    prelude: string;
+}
+/** 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;
+    /** Enclosing at-rules, innermost-first (e.g. `@layer`, `@media`). */
+    atRules?: ArtifactAtRule[];
+}
+/** A single token entry in the artifact JSON. */
+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: DtcgTokenType;
+    /** Token tier classification. */
+    tier: TokenTier;
+    /** DTCG $description. */
+    description?: string;
+    /** Full alias resolution chain (token IDs). */
+    aliasChain?: string[];
+    /** Resolved CSS value (mode-invariant tokens). */
+    value?: 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;
+    /** 0-indexed line number in the CSS output file (legacy, prefer `declarations`). */
+    cssOutputLine?: number;
+    /** 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;
+    /** `true` when the token has a CSS `@property` registration. */
+    registered?: boolean;
+    /** `@property` syntax (e.g. `"<color>"`). */
+    syntax?: string | null;
+    /** `@property` inherits flag. */
+    inherits?: boolean | null;
+    /** `@property` initial-value. */
+    initialValue?: string | null;
+    /** DTCG $extensions passthrough. */
+    extensions?: Record<string, unknown>;
+}
+/** Input contract for constructing a DTCG-sourced artifact token. */
+export interface ArtifactTokenInit {
+    /** CSS custom property name as emitted. */
+    cssVar: string;
+    /** DTCG token ID from source. */
+    id: string;
+    /** DTCG $type. */
+    type: DtcgTokenType;
+    /** Token tier classification. */
+    tier: TokenTier;
+    /** CSS output file containing this token's declaration. */
+    cssOutputFile: string;
+    /** DTCG $description. */
+    description?: string;
+    /** Declaration sites emitted in CSS output. */
+    declarations?: ArtifactDeclaration[];
+    /** Full alias resolution chain (token IDs). */
+    aliasChain?: string[];
+    /** Light-mode resolved CSS value. */
+    valueLight?: string;
+    /** Dark-mode resolved CSS value. */
+    valueDark?: string;
+    /** DTCG source file path (relative). */
+    sourceFile?: string;
+    /** Line number in the DTCG source file. */
+    sourceLine?: number;
+}
+/** Input contract for constructing a derived or plugin-generated artifact token. */
+export interface DerivedArtifactTokenInit {
+    /** CSS custom property name as emitted. */
+    cssVar: string;
+    /** DTCG $type. */
+    type: DtcgTokenType;
+    /** Token tier classification. */
+    tier: TokenTier;
+    /** CSS output file containing this token's declaration. */
+    cssOutputFile: string;
+    /** CSS var name of the source token. */
+    derivedFrom: string;
+    /** Formula kind for the derived token. */
+    derivation: DerivationKind;
+    /** DTCG $description. */
+    description?: string;
+    /** Declaration sites emitted in CSS output. */
+    declarations?: ArtifactDeclaration[];
+    /** Light-mode resolved CSS value. */
+    valueLight?: string;
+    /** Dark-mode resolved CSS value. */
+    valueDark?: string;
+}
+/** The complete artifact: CSS variable name → token metadata. */
+export type Artifact = Record<string, ArtifactToken>;
+/**
+ * Wrapped artifact format (supports legacy/spec envelope).
+ * The plugin may emit either flat or wrapped.
+ */
+export type ArtifactEnvelope = Artifact | {
+    version: string;
+    generator: string;
+    tokens: Artifact;
+};
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,3 @@
+export { isKnownDtcgTokenType, KNOWN_DTCG_TOKEN_TYPES, } from "./artifact/types.js";
+export type { Artifact, ArtifactAtRule, ArtifactDeclaration, ArtifactEnvelope, ArtifactToken, ArtifactTokenInit, DerivationKind, DerivedArtifactTokenInit, DtcgTokenType, KnownDtcgTokenType, TokenTier, } from "./artifact/types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../types/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,kBAAkB,EAClB,SAAS,GACV,MAAM,qBAAqB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonical/terrazzo-plugin-css",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",
@@ -49,7 +49,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@canonical/token-types": "^0.3.1"
+    "@canonical/token-types": "^0.4.0"
   },
   "devDependencies": {
     "@canonical/webarchitect": "^0.17.1",