@animus-ui/system 0.1.1-beta.2 → 0.1.2

package/dist/types/theme.d.ts

@@ -71,6 +71,68 @@ export type ScaleTokenRef<E extends string> = `${string}{${E}.${string}}${string
 export type ColorTokenRef = Theme extends {
     colors: infer C;
 } ? C extends Record<string, unknown> ? `{colors.${Extract<keyof C, string>}}` | `{colors.${Extract<keyof C, string>}/${number}}` : never : never;
+/**
+ * Optional `@property` registration metadata for a contextual var.
+ * A 1:1 mirror of the CSS `@property` descriptors — `initialValue` (never bare
+ * `initial`, which collides with the CSS-wide keyword). Supplied alongside the
+ * contextual var declaration; purely additive — it does NOT alter the phantom
+ * typing of the declared var names or the runtime theme object.
+ */
+export interface ContextualVarRegistration {
+    /** CSS `syntax` descriptor, e.g. `'<color>'` or `'*'`. Emitted quoted. */
+    syntax: string;
+    /** CSS `inherits` descriptor. */
+    inherits: boolean;
+    /** CSS `initial-value` descriptor. Omitted from output when absent. */
+    initialValue?: string;
+}
+/**
+ * OS `prefers-color-scheme` → declared mode name mapping.
+ * Presence of this config on a theme enables guarded system-fallback emission
+ * (`@media (prefers-color-scheme: …) { :root:not([data-color-mode]) { … } }`).
+ * Both values MUST name declared modes; the reserved name `system` is rejected
+ * (system is modeled as the ABSENCE of `data-color-mode`).
+ */
+export interface SystemPreferenceConfig {
+    /** Mode applied when the OS reports a light preference. */
+    light: string;
+    /** Mode applied when the OS reports a dark preference. */
+    dark: string;
+}
+/**
+ * Declared mode name → CSS `color-scheme` classification. When supplied it MUST
+ * be total across declared modes and agree with {@link SystemPreferenceConfig}.
+ */
+export type BrowserColorSchemeConfig = Record<string, 'light' | 'dark' | 'normal'>;
+/**
+ * Optional system-participation options accepted by `addColorModes`.
+ *
+ * Typed LOCALLY from the mode config's own keys (D1) — the mode-name union is
+ * deliberately NOT threaded through the builder-chain generics, so this adds no
+ * depth to the type-state machine (TS2589 discipline).
+ */
+export interface ColorModeOptions<Config> {
+    /** OS preference → declared mode name. Enables guarded system emission. */
+    systemPreference?: {
+        light: keyof Config & string;
+        dark: keyof Config & string;
+    };
+    /**
+     * Declared mode name → CSS `color-scheme`. Totality is enforced at build
+     * time, with one carve-out: the two modes named by `systemPreference` are
+     * FORCED to `light`/`dark` by the conflict rule anyway, so they default to
+     * those values and may be omitted — `browserColorScheme: {}` is the whole
+     * opt-in for a two-mode theme. Every mode NOT named by the mapping must be
+     * classified explicitly (a build error otherwise); an explicit value on a
+     * mapped mode is honored and still conflict-checked.
+     *
+     * Typed `Partial` for exactly that reason — compile-time totality would
+     * re-demand the forced entries. Runtime validation covers JS callers,
+     * casts, and `from()` composition, which all reach `build()` without this
+     * type applying.
+     */
+    browserColorScheme?: Partial<Record<keyof Config & string, 'light' | 'dark' | 'normal'>>;
+}
 /** Pipeline-ready JSON strings returned by `.serialize()` on a built theme. */
 export interface SerializedTheme {
     /** Flattened token map as JSON: { "space.8": "0.5rem", "breakpoints.sm": "768" } */
@@ -82,6 +144,58 @@ export interface SerializedTheme {
     /** Contextual vars registry as JSON: { "colors": ["background-current"] } */
     contextualVarsJson: string;
 }
+/**
+ * One authored `{scale.key}` reference occurrence inside a token value
+ * (manifest v2, D6). Captured BEFORE `resolveTokenRefs` rewrites the value —
+ * the authored graph is unrecoverable from resolved CSS (D8).
+ */
+export interface TokenReference {
+    /** The referenced dot-path exactly as authored, e.g. 'colors.blue.500'. */
+    path: string;
+    /**
+     * The authored opacity-modifier text when written `{path/NN}` (e.g. '50').
+     * Kept as the authored string — parsing to a number is an emission-time
+     * concern, not a capture-time one.
+     */
+    opacity?: string;
+}
+/**
+ * The AUTHORED form of one token value (manifest v2, D6):
+ * - `literal` — the value contains no `{scale.key}` refs.
+ * - `reference` — the value embeds one or more refs; `value` preserves the
+ *   authored string byte-exactly and `references` lists each ref target in
+ *   authored order.
+ * Flat shapes only (D11) — no recursive or conditional re-derivation.
+ */
+export type TokenDefinition = {
+    kind: 'literal';
+    value: string;
+} | {
+    kind: 'reference';
+    value: string;
+    references: TokenReference[];
+};
+/**
+ * Pre-resolution mode alias definitions (manifest v2, D6): mode name → alias
+ * dot-path → the AUTHORED color dot-path (the `colorRef` string, e.g.
+ * 'gray.300' — never its resolved raw value).
+ */
+export type ModeAliasDefinition = Record<string, Record<string, string>>;
+/**
+ * One CSS fragment recorded by `build()` (manifest v2, D6) — the EXACT string
+ * it composed. In this manifest version the fragments RECORD the composed
+ * strings; `variableCss` is still composed independently (the
+ * fragment→variableCss projection becomes load-bearing with the CSS wire
+ * plan).
+ */
+export interface ThemeCssFragment {
+    /** Stable fragment identifier (currently mirrors `kind`). */
+    id: string;
+    /** Semantic section: `@property` registrations vs the base variable CSS. */
+    kind: 'registrations' | 'base';
+    /** The exact composed CSS string — byte-identical to what build() joined. */
+    cssText: string;
+}
 /** Structured manifest emitted by ThemeBuilder.build() for plugin consumption. */
 export interface ThemeManifest {
     /** Flat token key → raw value (e.g. 'space.8' → '0.5rem', 'colors.ember' → '#FF2800') */
@@ -94,5 +208,23 @@ export interface ThemeManifest {
     variableCss: string;
     /** Contextual vars registry: scale_name → [var_name] for --current-{name} side-effects */
     contextualVars?: Record<string, string[]>;
+    /** OS preference → mode mapping, when the theme opted into system emission */
+    systemPreference?: SystemPreferenceConfig;
+    /** Mode → CSS `color-scheme` classification, when the theme opted in */
+    browserColorScheme?: BrowserColorSchemeConfig;
+    /** Version discriminant. ABSENT ⇒ v1 manifest (variant creation rejects). */
+    manifestVersion?: 2;
+    /** Authored literal-vs-reference structure per flattened token path. */
+    tokenDefinitions?: Record<string, TokenDefinition>;
+    /** Mode name → alias dot-path → AUTHORED color dot-path (pre-resolution). */
+    modeAliasDefinitions?: ModeAliasDefinition;
+    /** `@property` registrations by contextual var name, in declaration order. */
+    registrations?: Record<string, ContextualVarRegistration>;
+    /** Version of the emitter that composed this manifest's CSS. */
+    emitterVersion?: number;
+    /** sha256 hex over sorted-key canonical JSON of the authored inputs. */
+    contractHash?: string;
+    /** The exact CSS strings build() composed, in emission order. */
+    cssFragments?: ThemeCssFragment[];
 }
 //# sourceMappingURL=theme.d.ts.map

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

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

package/dist/utils/deepMerge.d.ts

@@ -1,5 +1,2 @@
-/**
- * Deep merge utility — replaces lodash.merge for variant accumulation.
- */
 export declare function deepMerge<A extends Record<string, any>, B extends Record<string, any>>(target: A, source: B): A & B;
 //# sourceMappingURL=deepMerge.d.ts.map

package/dist/utils/deepMerge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deepMerge.d.ts","sourceRoot":"","sources":["../../src/utils/deepMerge.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAiB7B"}
+{"version":3,"file":"deepMerge.d.ts","sourceRoot":"","sources":["../../src/utils/deepMerge.ts"],"names":[],"mappings":"AAMA,wBAAgB,SAAS,CACvB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC7B,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAU7B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@animus-ui/system",
-  "version": "0.1.1-beta.2",
+  "version": "0.1.2",
   "description": "Animus design system builder — tokens, prop groups, global styles",
   "keywords": [
     "css",
@@ -40,6 +40,14 @@
       "types": "./dist/groups/index.d.ts",
       "import": "./dist/groups/index.js"
     },
+    "./bootstrap": {
+      "types": "./dist/bootstrap/index.d.ts",
+      "import": "./dist/bootstrap/index.js"
+    },
+    "./appearance": {
+      "types": "./dist/appearance/index.d.ts",
+      "import": "./dist/appearance/index.js"
+    },
     "./compose": {
       "types": "./dist/compose.d.ts",
       "import": "./dist/compose.js"
@@ -59,11 +67,11 @@
   },
   "scripts": {
     "build": "bun run build:ts",
-    "build:ts": "tsdown && tsgo -p tsconfig.build.json",
-    "compile": "tsgo --noEmit"
+    "build:ts": "tsdown && tsc -p tsconfig.build.json",
+    "compile": "tsc --noEmit"
   },
   "dependencies": {
-    "@animus-ui/properties": "0.1.1-beta.2",
+    "@animus-ui/properties": "0.1.2",
     "csstype": "^3.1.3"
   },
   "devDependencies": {