@crab-dev/css 0.1.17 → 0.1.18

package/README.md

@@ -78,6 +78,27 @@ const style = assignVars({
 })
 ```
 
+## Immutable design tokens
+
+Use `defineTokens` for nested token structures that are interpolated from another module. Wake
+recognizes only a direct top-level `const` initialized through this imported helper; the argument
+must contain statically evaluable plain objects, arrays, and primitive values.
+
+```ts
+import { css, defineTokens } from '@crab-dev/css'
+
+export const tokens = defineTokens({
+  color: { accent: 'rebeccapurple' },
+})
+
+export const button = css`
+  color: ${tokens.color.accent};
+`
+```
+
+The return type is deeply readonly and the runtime value is deeply frozen. Ordinary mutable
+objects do not acquire this cross-module compiler guarantee.
+
 ## Compile-time contract
 
 `css`, `keyframes`, and `globalStyle` must be used as direct tagged templates

package/index.cjs

@@ -27,6 +27,50 @@ function globalStyle() {
   return compilerOnly('globalStyle')
 }
 
+function defineTokens(value) {
+  if (value === null || typeof value !== 'object') {
+    throw new TypeError('@crab-dev/css: defineTokens expects a plain object or array.')
+  }
+
+  const pending = [value]
+  const seen = new WeakSet()
+  while (pending.length > 0) {
+    const current = pending.pop()
+    if (seen.has(current)) continue
+    seen.add(current)
+
+    const prototype = Object.getPrototypeOf(current)
+    const plainObject = prototype === null || Object.getPrototypeOf(prototype) === null
+    if (!Array.isArray(current) && !plainObject) {
+      throw new TypeError('@crab-dev/css: defineTokens accepts only plain objects and arrays.')
+    }
+
+    const descriptors = Object.getOwnPropertyDescriptors(current)
+    for (const key of Reflect.ownKeys(descriptors)) {
+      if (typeof key === 'symbol') {
+        throw new TypeError('@crab-dev/css: defineTokens does not accept symbol keys.')
+      }
+      const descriptor = descriptors[key]
+      if ('get' in descriptor || 'set' in descriptor) {
+        throw new TypeError('@crab-dev/css: defineTokens does not accept accessors.')
+      }
+      const item = descriptor.value
+      if (item === null) {
+        continue
+      } else if (typeof item === 'object') {
+        pending.push(item)
+      } else if (
+        !['string', 'number', 'boolean', 'undefined'].includes(typeof item) ||
+        (typeof item === 'number' && !Number.isFinite(item))
+      ) {
+        throw new TypeError('@crab-dev/css: defineTokens contains an unsupported value.')
+      }
+    }
+    Object.freeze(current)
+  }
+  return value
+}
+
 function cx(...values) {
   const classes = []
   const pending = values.slice().reverse()
@@ -146,5 +190,6 @@ exports.assignVars = assignVars
 exports.createVar = createVar
 exports.css = css
 exports.cx = cx
+exports.defineTokens = defineTokens
 exports.globalStyle = globalStyle
 exports.keyframes = keyframes

package/index.d.ts

@@ -40,6 +40,22 @@ export type ClassValue =
 
 export type CSSVariableStyles = Record<string, string | number>
 
+export type TokenPrimitive = string | number | boolean | null | undefined
+
+export type TokenValue =
+  | TokenPrimitive
+  | { readonly [key: string]: TokenValue }
+  | readonly TokenValue[]
+
+export type DeepReadonlyToken<T> =
+  T extends TokenPrimitive
+    ? T
+    : T extends readonly unknown[]
+      ? { readonly [K in keyof T]: DeepReadonlyToken<T[K]> }
+      : T extends object
+        ? { readonly [K in keyof T]: DeepReadonlyToken<T[K]> }
+        : never
+
 /**
  * Declares a scoped class. Wake replaces this template tag with a ClassName
  * and extracts its CSS during compilation.
@@ -70,6 +86,9 @@ export declare function globalStyle(
   ...interpolations: readonly CSSInterpolation[]
 ): void
 
+/** Marks a recursively pure token structure as deeply immutable for safe ESM propagation. */
+export declare function defineTokens<const T extends TokenValue>(value: T): DeepReadonlyToken<T>
+
 /** Creates a realm-unique `var(--custom-property)` reference. */
 export declare function createVar(debugName?: string): CSSVar
 

package/index.mjs

@@ -25,6 +25,50 @@ export function globalStyle() {
   return compilerOnly('globalStyle')
 }
 
+export function defineTokens(value) {
+  if (value === null || typeof value !== 'object') {
+    throw new TypeError('@crab-dev/css: defineTokens expects a plain object or array.')
+  }
+
+  const pending = [value]
+  const seen = new WeakSet()
+  while (pending.length > 0) {
+    const current = pending.pop()
+    if (seen.has(current)) continue
+    seen.add(current)
+
+    const prototype = Object.getPrototypeOf(current)
+    const plainObject = prototype === null || Object.getPrototypeOf(prototype) === null
+    if (!Array.isArray(current) && !plainObject) {
+      throw new TypeError('@crab-dev/css: defineTokens accepts only plain objects and arrays.')
+    }
+
+    const descriptors = Object.getOwnPropertyDescriptors(current)
+    for (const key of Reflect.ownKeys(descriptors)) {
+      if (typeof key === 'symbol') {
+        throw new TypeError('@crab-dev/css: defineTokens does not accept symbol keys.')
+      }
+      const descriptor = descriptors[key]
+      if ('get' in descriptor || 'set' in descriptor) {
+        throw new TypeError('@crab-dev/css: defineTokens does not accept accessors.')
+      }
+      const item = descriptor.value
+      if (item === null) {
+        continue
+      } else if (typeof item === 'object') {
+        pending.push(item)
+      } else if (
+        !['string', 'number', 'boolean', 'undefined'].includes(typeof item) ||
+        (typeof item === 'number' && !Number.isFinite(item))
+      ) {
+        throw new TypeError('@crab-dev/css: defineTokens contains an unsupported value.')
+      }
+    }
+    Object.freeze(current)
+  }
+  return value
+}
+
 export function cx(...values) {
   const classes = []
   const pending = values.slice().reverse()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crab-dev/css",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Type-safe, zero-runtime CSS authoring for Wake",
   "keywords": [
     "css",