zyzz 0.0.25 → 0.0.27

package/src/internal/VariableSets.ts

@@ -55,19 +55,30 @@ export function from(metadata: Token.Metadata): Vars.Definition {
   ) as Vars.Definition
 }
 
-/** Validates and freezes a complete set or compatible partial override. */
+/**
+ * Validates and freezes a complete set, or grows a base set with compatible
+ * overrides and new leaves.
+ */
 export function build(
   input: unknown,
   contract: Token.Contract,
-  base?: Token.Metadata['values'],
-  baseQueries?: Query.Metadata,
-  basePaths?: Token.Metadata['paths'],
+  options: build.Options = {},
 ): Vars.Definition {
+  const base = options.base
   const values: Record<string, Token.Value> = Object.assign(
     Object.create(null),
-    base,
+    base?.values,
   )
-  const paths = { ...basePaths }
+  const paths = { ...base?.paths }
+  // Segment keys keep dotted typography conditions distinct from nested paths.
+  const leaves = new Set<string>()
+  const categories = new Set<string>()
+  for (const path of Object.keys(base?.values ?? {})) {
+    const parts = base!.paths?.[path] ?? path.split('.')
+    leaves.add(JSON.stringify(parts))
+    for (let index = 1; index < parts.length; index++)
+      categories.add(JSON.stringify(parts.slice(0, index)))
+  }
   const conditions: string[][] = []
   const active = new Set<object>()
   function visit(input: unknown, path: string[]) {
@@ -86,14 +97,31 @@ export function build(
     ) {
       if (!path.length)
         throw new Vars.InvalidError(path, 'Expected a variable record.')
-      const value = read(input, path, queryData)
+      if (categories.has(JSON.stringify(path)))
+        throw new Vars.InvalidError(
+          path,
+          'Extensions cannot replace a variable category with a leaf.',
+        )
       const name = path.join('.')
-      if (base && !Object.hasOwn(base, name))
+      const previous =
+        base && Object.hasOwn(base.values, name) ? base.values[name] : undefined
+      if (previous !== undefined && options.derived)
         throw new Vars.InvalidError(
           path,
-          'Extensions cannot add variable paths.',
+          'Derived variables cannot replace existing paths.',
         )
-      if (base && domain(base[name]!) !== domain(value))
+      // Restating the base reference would make the variable reference itself.
+      if (
+        previous !== undefined &&
+        Token.is(input) &&
+        input.path === name &&
+        (input.contract === contract ||
+          (contract[Token.identity] !== undefined &&
+            input.contract[Token.identity] === contract[Token.identity]))
+      )
+        return
+      const value = read(input, path, queryData)
+      if (previous !== undefined && domain(previous) !== domain(value))
         throw new Vars.InvalidError(
           path,
           'Variable overrides must preserve their domain.',
@@ -103,11 +131,19 @@ export function build(
       values[name] = value
       return
     }
+    if (leaves.has(JSON.stringify(path)))
+      throw new Vars.InvalidError(
+        path,
+        'Extensions cannot replace a variable leaf with a category.',
+      )
     const entries = record(input, path)
     if (active.has(input as object))
       throw new Vars.InvalidError(path, 'Cyclic variables are not supported.')
     active.add(input as object)
-    if (!entries.length && !base)
+    if (
+      !entries.length &&
+      (!base || (path.length > 0 && !categories.has(JSON.stringify(path))))
+    )
       throw new Vars.InvalidError(path, 'Variable records cannot be empty.')
     for (const [key, value] of entries) {
       const query = path[0] === 'typography' && Typography.condition(key)
@@ -122,34 +158,29 @@ export function build(
     active.delete(input as object)
   }
   const fields = Object.fromEntries(record(input, []))
-  const queries = { ...baseQueries }
+  const queries = { ...base?.queries }
   for (const key of ['breakpoint', 'container', 'containerNames'] as const) {
     if (Object.hasOwn(fields, key)) {
       const value = fields[key]
       if (base) {
         if (key === 'containerNames') {
           if (
-            JSON.stringify(value) !==
-            JSON.stringify(baseQueries?.containerNames ?? [])
+            !Array.isArray(value) ||
+            (base.queries?.containerNames ?? []).some(
+              (name) => !value.includes(name),
+            )
           )
             throw new Vars.InvalidError(
               [key],
-              'Extensions cannot change container identities.',
+              'Extensions cannot remove container identities.',
             )
-        } else {
-          for (const [name] of record(value, [key]))
-            if (!Object.hasOwn(baseQueries?.[key] ?? {}, name))
-              throw new Vars.InvalidError(
-                [key, name],
-                'Extensions cannot add query thresholds.',
-              )
-        }
+        } else record(value, [key])
       }
       Object.assign(queries, {
         [key]:
           key === 'containerNames'
             ? value
-            : { ...baseQueries?.[key], ...value },
+            : { ...base?.queries?.[key], ...value },
       })
       if (key !== 'container' || Object.keys(value as object).length === 0)
         delete fields[key]
@@ -178,6 +209,55 @@ export function build(
   ) as Vars.Definition
 }
 
+/** Set construction inputs. */
+export declare namespace build {
+  /** Base set metadata and how its existing paths may change. */
+  type Options = {
+    /** Set whose leaves the input overrides or extends. */
+    readonly base?:
+      | Pick<Token.Metadata, 'paths' | 'queries' | 'values'>
+      | undefined
+    /** Rejects existing paths, as derived leaves only add to the set. */
+    readonly derived?: boolean | undefined
+  }
+}
+
+/**
+ * Reads a set's references as values for a named extension. Typography presets
+ * keep their base values, since presets expand at each use.
+ */
+export function references(
+  variables: object,
+  metadata: Pick<Token.Metadata, 'paths' | 'queries' | 'values'>,
+): Vars.Values {
+  const tree: Record<string, unknown> = Object.create(null)
+
+  for (const [path, value] of Object.entries(metadata.values)) {
+    const parts = metadata.paths?.[path] ?? path.split('.')
+    let target = tree
+    let source: unknown = variables
+
+    for (const part of parts.slice(0, -1)) {
+      target = (target[part] ??= Object.create(null)) as Record<string, unknown>
+      source = (source as Record<string, unknown>)[part]
+    }
+
+    const name = parts.at(-1)!
+    target[name] =
+      parts[0] === 'typography'
+        ? value
+        : (source as Record<string, unknown>)[name]
+  }
+
+  for (const key of ['breakpoint', 'container'] as const)
+    if (Object.keys(metadata.queries?.[key] ?? {}).length)
+      tree[key] = metadata.queries![key]
+  if (metadata.queries?.containerNames?.length)
+    tree.containerNames = metadata.queries.containerNames
+
+  return tree as Vars.Values
+}
+
 function buildTree(
   values: Token.Metadata['values'],
   contract: Token.Contract,

package/src/react-native/internal/Tokens.ts

@@ -32,12 +32,11 @@ export function resolve(
           (metadata.contract[Token.identity] !== undefined &&
             metadata.contract[Token.identity] ===
               value.contract[Token.identity]))
-      const next = shared
-        ? Object.hasOwn(metadata.values, value.path)
-          ? metadata.values[value.path]
-          : undefined
-        : value.value
-      if (next === undefined) throw new Error('Theme is missing a live token.')
+      // A set sharing its contract with an extension lacks the extension's added paths.
+      const next =
+        shared && Object.hasOwn(metadata.values, value.path)
+          ? metadata.values[value.path]!
+          : value.value
       active.add(value)
       const result = scalar(next)
       active.delete(value)

package/src/vite/index.ts

@@ -907,15 +907,9 @@ export function zyzz(options: zyzz.Options = {}): Plugin {
           url += target.slice(raw.length)
         }
       } else {
-        const pathname = file
-          .replaceAll('\\', '/')
-          .split('/')
-          .map((part, index) =>
-            index === 0 && /^[a-z]:$/i.test(part)
-              ? part
-              : encodeURIComponent(part),
-          )
-          .join('/')
+        // Vite reads `/@fs/` URLs with `decodeURI`, which keeps reserved escapes
+        // such as `%40` in scoped package paths, so those characters stay raw.
+        const pathname = encodeURI(file.replaceAll('\\', '/'))
 
         url = `/@fs/${pathname}${target.slice(raw.length)}`
       }

package/src/web/internal/Themes.ts

@@ -70,6 +70,7 @@ export function create() {
     const completeDefaults = new Set<Token.Contract>()
     const empty: string[] = []
     const rules: Rule[] = []
+    const varied = variedPaths(themes)
 
     for (const [name, theme] of Object.entries(themes)) {
       if (!name) throw new Error('Theme names must be nonempty.')
@@ -130,8 +131,14 @@ export function create() {
       const paths = [...contract.paths]
       for (const [path, name] of paths) {
         const value = data.values[path]
-        if (value === undefined)
-          throw new Error('Theme scope is missing a live token.')
+        // A set sharing its contract with an extension lacks the extension's added paths.
+        if (value === undefined) continue
+        // An inherited base reference resolves through its fallback, unless a sibling set overrides it.
+        if (
+          inherited(value, path, data.contract) &&
+          !varied.get(data.contract)?.has(path)
+        )
+          continue
 
         const label = path
         declarations.push({
@@ -144,15 +151,16 @@ export function create() {
 
       rules.push(...declarations)
       for (const [path, name] of contract.paths)
-        conditional(
-          data.values[path]!,
-          name,
-          `.${className}`,
-          rules,
-          path,
-          [],
-          data.contract,
-        )
+        if (Object.hasOwn(data.values, path))
+          conditional(
+            data.values[path]!,
+            name,
+            `.${className}`,
+            rules,
+            path,
+            [],
+            data.contract,
+          )
     }
 
     for (const rule of rules) {
@@ -257,9 +265,9 @@ export function create() {
     if ('default' in value) {
       // Separate fallback properties preserve extensions and resolve references within each scope.
       const base = literal(value.default, label, owner)
-      // Rule consolidation must not change existing variable identities.
+      // Rule consolidation must not change existing variable identities, so the name hashes the fallback's CSS.
       const css = `:where(*){--fallback:${base};}${conditionalCss(value, '--fallback', ':where(*)', label, owner)}`
-      const name = `${owner ? property(owner, label ?? 'value') : variable(undefined, label ?? 'value')}-fallback-${Identity.name(css)}`
+      const name = `${owner ? property(owner, label ?? 'value') : variable(undefined, label ?? 'value')}-fallback-${Identity.hash(css)}`
       const emitted: Rule[] = [
         { conditions: [], property: name, selector: ':where(*)', value: base },
       ]
@@ -409,6 +417,44 @@ export function scope(value: string, identity?: string): string {
   return `z-theme-${namespace}${Identity.name(value)}`
 }
 
+/** Whether a set's value is its base's own reference at the same path, as named extensions inherit. */
+function inherited(value: Token.Value, path: string, contract: Token.Contract) {
+  return Token.is(value) && value.path === path && value.contract !== contract
+}
+
+/** Paths whose values differ between sets that share a contract. */
+function variedPaths(
+  themes: Readonly<Record<string, Theme.Definition | Vars.Definition>>,
+) {
+  const seen = new Map<Token.Contract, Map<string, string>>()
+  const varied = new Map<Token.Contract, Set<string>>()
+
+  for (const theme of Object.values(themes)) {
+    const data = Object.getOwnPropertyDescriptor(theme, Token.definition)
+      ?.value as Token.Metadata | undefined
+    if (!data) continue
+
+    const values = seen.get(data.contract) ?? new Map<string, string>()
+    seen.set(data.contract, values)
+
+    for (const [path, value] of Object.entries(data.values)) {
+      const key = Token.is(value)
+        ? JSON.stringify([value.contract[Token.identity], value.path])
+        : JSON.stringify(value)
+      const previous = values.get(path)
+
+      if (previous === undefined) values.set(path, key)
+      else if (previous !== key) {
+        const paths = varied.get(data.contract) ?? new Set<string>()
+        paths.add(path)
+        varied.set(data.contract, paths)
+      }
+    }
+  }
+
+  return varied
+}
+
 function variable(identity: string | undefined, path: string): string {
   const namespace = identity?.startsWith('id-') ? `${identity.slice(3)}-` : ''
   return `--z-${namespace}${path.split('.').map(Identity.name).join('-')}`