Harden CSSX React tracking

Author: cray0000

docs/api/runtime.md

@@ -153,6 +153,9 @@ function App() {
 
 Nested providers override outer `:root` variables for their subtree. Runtime
 `variables['--name']` still has higher priority than provider `:root` values.
+Compiled provider sheets may also use template interpolation inside `:root`
+custom property values, so a precompiled provider layer can pass dynamic theme
+tokens through `{ sheet, values }`.
 
 Use `themed(tagName, Component)` for components that should be addressable by
 tag selectors in provider/global CSS. Class selectors remain global utilities

packages/css-to-rn/src/compiler.ts

@@ -176,7 +176,7 @@ function compileRuleList (
         ))
         continue
       }
-      compileRootVariables(declarations, rootVariables, state, isTemplate)
+      compileRootVariables(declarations, rootVariables, state)
       continue
     }
 
@@ -213,8 +213,7 @@ function compileRuleList (
 function compileRootVariables (
   declarations: CssDeclarationAst[],
   rootVariables: Record<string, string>,
-  state: CompileState,
-  isTemplate: boolean
+  state: CompileState
 ): void {
   for (const declaration of declarations) {
     if (declaration.type !== 'declaration') continue
@@ -232,16 +231,6 @@ function compileRootVariables (
     }
 
     const value = declaration.value ?? ''
-    if (isTemplate && hasDynamicSlots(value)) {
-      addDiagnostic(state, diagnostic(
-        'UNSUPPORTED_INTERPOLATION_POSITION',
-        'Interpolation is not supported inside :root variable declarations.',
-        'error',
-        positionOf(declaration)
-      ))
-      continue
-    }
-
     rootVariables[property] = value
   }
 }

packages/css-to-rn/src/react/config.ts

@@ -88,6 +88,7 @@ const EMPTY_TRACKING_SHEET: CompiledCssSheet = {
   metadata: EMPTY_METADATA,
   diagnostics: []
 }
+const DYNAMIC_ROOT_SLOT_RE = /var\(\s*--__cssx_dynamic_(\d+)\s*\)/g
 
 export function configureCssx (config: CssxReactConfig): void {
   setRuntimeConfig(config)
@@ -155,14 +156,10 @@ export function themed<P extends object> (
 
 function useCssxRenderTracker (options: CssxReactConfig): TrackedCssxSheet {
   const trackerRef = useRef<TrackedCssxSheet | null>(null)
-
-  if (trackerRef.current == null) {
-    trackerRef.current = new TrackedCssxSheet(EMPTY_TRACKING_SHEET, options)
-  } else {
-    trackerRef.current.update(EMPTY_TRACKING_SHEET, options)
-  }
-
-  const tracker = trackerRef.current
+  const committedTracker = trackerRef.current
+  const tracker = committedTracker?.matches(EMPTY_TRACKING_SHEET, options)
+    ? committedTracker
+    : new TrackedCssxSheet(EMPTY_TRACKING_SHEET, options)
   const renderDependencies = tracker.startRender()
 
   useSyncExternalStore(
@@ -173,6 +170,7 @@ function useCssxRenderTracker (options: CssxReactConfig): TrackedCssxSheet {
 
   useCommitEffect(() => {
     tracker.commitRender(renderDependencies)
+    trackerRef.current = tracker
   })
 
   return tracker
@@ -223,7 +221,7 @@ function collectProviderStyle (
   if (isTrackedCssxSheet(input)) {
     const sheet = input.getSheet()
     layers.push({ sheet, cacheKey: input })
-    collectRootVariables(sheet, scopedVariables)
+    collectRootVariables(sheet, scopedVariables, input.getOptions().values)
     return
   }
 
@@ -239,7 +237,7 @@ function collectProviderStyle (
     const sheet = typeof layer.sheet === 'string'
       ? compileCss(layer.sheet, { mode: 'runtime' })
       : layer.sheet
-    collectRootVariables(sheet, scopedVariables)
+    collectRootVariables(sheet, scopedVariables, layer.values)
   }
 }
 
@@ -271,9 +269,34 @@ function normalizeProviderStyleLayer (
 
 function collectRootVariables (
   sheet: CompiledCssSheet,
-  scopedVariables: Record<string, unknown>[]
+  scopedVariables: Record<string, unknown>[],
+  values: readonly unknown[] = []
 ): void {
-  if (sheet.rootVariables != null) scopedVariables.push(sheet.rootVariables)
+  if (sheet.rootVariables != null) {
+    scopedVariables.push(applyLayerValuesToRootVariables(sheet.rootVariables, values))
+  }
+}
+
+function applyLayerValuesToRootVariables (
+  rootVariables: Record<string, string>,
+  values: readonly unknown[]
+): Record<string, string> {
+  if (values.length === 0) return rootVariables
+
+  const output: Record<string, string> = {}
+  for (const name of Object.keys(rootVariables)) {
+    const value = rootVariables[name]
+    let valid = true
+    const next = value.replace(DYNAMIC_ROOT_SLOT_RE, (_match, rawIndex: string) => {
+      const interpolation = values[Number(rawIndex)]
+      if (typeof interpolation === 'string') return interpolation
+      if (typeof interpolation === 'number') return String(interpolation)
+      valid = false
+      return ''
+    })
+    if (valid) output[name] = next
+  }
+  return output
 }
 
 function isProviderStyleLayer (value: unknown): value is CssxProviderStyleLayer {

packages/css-to-rn/src/react/hooks.ts

@@ -33,6 +33,25 @@ const useCommitEffect = typeof window === 'undefined'
   ? useEffect
   : useLayoutEffect
 const CSS_VARIABLE_NAME_RE = /^--[A-Za-z0-9_-]+$/
+const EMPTY_METADATA = {
+  hasVars: false,
+  vars: [],
+  hasMedia: false,
+  hasViewportUnits: false,
+  hasInterpolations: false,
+  hasDynamicRuntimeDependencies: false,
+  hasAnimations: false,
+  hasTransitions: false
+}
+const EMPTY_LAYER_SHEET: CompiledCssSheet = {
+  version: 1,
+  id: 'cssx_empty_layer',
+  contentHash: 'cssx_empty_layer',
+  rules: [],
+  keyframes: {},
+  metadata: EMPTY_METADATA,
+  diagnostics: []
+}
 
 export type CssxLayerHookInput =
   | string
@@ -67,14 +86,10 @@ export function useCssxSheet (
     ...context,
     ...options
   }
-
-  if (trackerRef.current == null) {
-    trackerRef.current = new TrackedCssxSheet(sheet, mergedOptions)
-  } else {
-    trackerRef.current.update(sheet, mergedOptions)
-  }
-
-  const tracker = trackerRef.current
+  const committedTracker = trackerRef.current
+  const tracker = committedTracker?.matches(sheet, mergedOptions)
+    ? committedTracker
+    : new TrackedCssxSheet(sheet, mergedOptions)
   const renderDependencies = tracker.startRender()
 
   useSyncExternalStore(
@@ -85,6 +100,7 @@ export function useCssxSheet (
 
   useCommitEffect(() => {
     tracker.commitRender(renderDependencies)
+    trackerRef.current = tracker
   })
 
   return tracker
@@ -119,30 +135,42 @@ export function useCssxLayer (
   input: CssxLayerHookInput,
   options: CssxReactConfig = {}
 ): CssxLayerHookOutput {
-  if (!input) return input
-
-  if (typeof input === 'string') return useRuntimeCss(input, options)
-  if (input instanceof TrackedCssxSheet) return input
-  if (isCompiledSheet(input)) return useCssxSheet(input, options)
+  const context = useCssxConfig()
+  const target = options.target ?? context.target
+  const normalized = useMemo(
+    () => normalizeLayerHookInput(input, target),
+    [input, target]
+  )
+  const tracker = useCssxSheet(normalized.sheet, {
+    ...options,
+    values: normalized.values
+  })
 
-  if (isLayerObject(input)) {
-    const sheet = input.sheet
-    if (typeof sheet === 'string') {
-      return {
-        ...input,
-        sheet: useRuntimeCss(sheet, options)
+  switch (normalized.kind) {
+    case 'empty':
+      return input as null | undefined | false
+    case 'tracked':
+      return input as CssxLayerHookOutput
+    case 'layerTracked':
+      return input as CssxLayerHookOutput
+    case 'layerString': {
+      const layerInput = input as {
+        sheet: string | CompiledCssSheet | TrackedCssxSheet
+        values?: readonly unknown[]
       }
+      return {
+        ...layerInput,
+        sheet: tracker
+      } as CssxLayerHookOutput
     }
-    if (sheet instanceof TrackedCssxSheet) return input as CssxLayerHookOutput
-    if (isCompiledSheet(sheet)) {
-      return useCssxSheet(sheet, {
-        ...options,
-        values: input.values
-      })
-    }
+    case 'compiled':
+    case 'string':
+    case 'layerCompiled':
+      return tracker
+    case 'unknown':
+    default:
+      return input as CssxLayerHookOutput
   }
-
-  return input as CssxLayerHookOutput
 }
 
 export function useCssVariableRaw (
@@ -151,16 +179,20 @@ export function useCssVariableRaw (
 ): string | undefined {
   assertCssVariableName(name)
   const context = useCssxRuntimeContext()
-  const dependenciesRef = useRef<CssxDependencySnapshot>(createDependencySnapshot())
+  const committedDependenciesRef = useRef<CssxDependencySnapshot>(createDependencySnapshot())
   const result = resolveCssVariableRaw(name, fallback, context.scopedVariables)
-  dependenciesRef.current = createVariableDependencySnapshot(result)
+  const renderDependencies = createVariableDependencySnapshot(result)
 
   useSyncExternalStore(
-    listener => subscribeRuntimeStore(listener, () => dependenciesRef.current),
+    listener => subscribeRuntimeStore(listener, () => committedDependenciesRef.current),
     getRuntimeVersion,
     getRuntimeVersion
   )
 
+  useCommitEffect(() => {
+    committedDependenciesRef.current = renderDependencies
+  })
+
   return result.value
 }
 
@@ -208,6 +240,80 @@ function isLayerObject (value: unknown): value is {
   )
 }
 
+type NormalizedLayerHookInput =
+  | {
+    kind: 'empty' | 'unknown' | 'tracked' | 'layerTracked'
+    sheet: CompiledCssSheet
+    values?: readonly unknown[]
+  }
+  | {
+    kind: 'string' | 'compiled' | 'layerString' | 'layerCompiled'
+    sheet: CompiledCssSheet
+    values?: readonly unknown[]
+  }
+
+function normalizeLayerHookInput (
+  input: CssxLayerHookInput,
+  target: CssxReactConfig['target']
+): NormalizedLayerHookInput {
+  if (!input) {
+    return {
+      kind: 'empty',
+      sheet: EMPTY_LAYER_SHEET
+    }
+  }
+
+  if (typeof input === 'string') {
+    return {
+      kind: 'string',
+      sheet: compileCss(input, { target })
+    }
+  }
+
+  if (input instanceof TrackedCssxSheet) {
+    return {
+      kind: 'tracked',
+      sheet: EMPTY_LAYER_SHEET
+    }
+  }
+
+  if (isCompiledSheet(input)) {
+    return {
+      kind: 'compiled',
+      sheet: input
+    }
+  }
+
+  if (isLayerObject(input)) {
+    const sheet = input.sheet
+    if (typeof sheet === 'string') {
+      return {
+        kind: 'layerString',
+        sheet: compileCss(sheet, { target }),
+        values: input.values
+      }
+    }
+    if (sheet instanceof TrackedCssxSheet) {
+      return {
+        kind: 'layerTracked',
+        sheet: EMPTY_LAYER_SHEET
+      }
+    }
+    if (isCompiledSheet(sheet)) {
+      return {
+        kind: 'layerCompiled',
+        sheet,
+        values: input.values
+      }
+    }
+  }
+
+  return {
+    kind: 'unknown',
+    sheet: EMPTY_LAYER_SHEET
+  }
+}
+
 function resolveCssVariableRaw (
   name: string,
   fallback?: unknown,