zyzz 0.0.22 → 0.0.24

package/src/react-native/react.ts

@@ -1,22 +1,17 @@
 /** React subscriptions for compiled native styles and variable values. @module */
 import * as Config from '../Config.js'
-import * as NativeContext from '../runtime/NativeContext.js'
+import type * as NativeContext from '../runtime/NativeContext.js'
 import * as NativeVars from '../runtime/NativeVars.js'
 import * as React from 'react'
 import type * as Vars from '../Vars.js'
 import * as Store from './internal/Store.js'
+import * as Styles from './internal/Styles.js'
 import * as Viewport from './internal/Viewport.js'
 
-const unbound = {
-  getSnapshot: () => undefined,
-  subscribe: () => () => {},
-}
-
 /** Creates native authoring helpers and a Provider typed to the configured variables. */
 export function defineConfig<const options extends Config.create.Options = {}>(
   options: options & Parameters<typeof Config.create<options>>[0] = {} as never,
 ): defineConfig.ReturnType<options> {
-  const config = Config.create<options>(options)
   const defaultVars = (options as Config.VariableOptions).defaultVars
   const names =
     defaultVars === undefined
@@ -33,10 +28,71 @@ export function defineConfig<const options extends Config.create.Options = {}>(
     })
   }
 
+  if ((options as Config.VariableOptions).vars === undefined)
+    return Object.freeze({
+      ...Config.create<options>(options),
+      Provider: BoundProvider,
+    }) as defineConfig.ReturnType<options>
+
+  // Compiled native styles and `useVars` read precompiled tables, so variable
+  // configurations build their authoring helpers on first runtime use.
+  let config: Helpers | undefined
+  const create = () =>
+    (config ??= (Config.create as (options: object) => Helpers)(options))
   return Object.freeze({
-    ...config,
+    get appearance() {
+      return create().appearance
+    },
     Provider: BoundProvider,
-  }) as defineConfig.ReturnType<options>
+    get script() {
+      return create().script
+    },
+    style: (...args: never[]) => create().style(...args),
+    variants: (...args: never[]) => create().variants(...args),
+    vars: deferred(() => create().vars),
+  }) as unknown as defineConfig.ReturnType<options>
+}
+
+/** Untyped view of a variable configuration's helpers. */
+type Helpers = {
+  readonly appearance: unknown
+  readonly script: unknown
+  readonly style: (...args: never[]) => unknown
+  readonly variants: (...args: never[]) => unknown
+  readonly vars: object
+}
+
+/** Forwards every operation to a value built on first use, mirroring it onto the proxy target so invariants hold. */
+function deferred<value extends object>(create: () => value): value {
+  const target = (() => {}) as unknown as value
+  let ready = false
+  function resolve() {
+    if (ready) return target
+    const value = create()
+    Object.defineProperties(target, Object.getOwnPropertyDescriptors(value))
+    Object.setPrototypeOf(target, Object.getPrototypeOf(value))
+    if (Object.isFrozen(value)) Object.freeze(target)
+    ready = true
+    return target
+  }
+  return new Proxy(target, {
+    apply: (_, self, args) =>
+      Reflect.apply(create() as (...args: unknown[]) => unknown, self, args),
+    defineProperty: (_, key, descriptor) =>
+      Reflect.defineProperty(resolve(), key, descriptor),
+    deleteProperty: (_, key) => Reflect.deleteProperty(resolve(), key),
+    get: (_, key) => Reflect.get(resolve(), key),
+    getOwnPropertyDescriptor: (_, key) =>
+      Reflect.getOwnPropertyDescriptor(resolve(), key),
+    getPrototypeOf: () => Reflect.getPrototypeOf(resolve()),
+    has: (_, key) => Reflect.has(resolve(), key),
+    isExtensible: () => Reflect.isExtensible(resolve()),
+    ownKeys: () => Reflect.ownKeys(resolve()),
+    preventExtensions: () => Reflect.preventExtensions(resolve()),
+    set: (_, key, value) => Reflect.set(resolve(), key, value),
+    setPrototypeOf: (_, prototype) =>
+      Reflect.setPrototypeOf(resolve(), prototype),
+  })
 }
 
 /** Native configuration helpers and inferred Provider props. */
@@ -66,23 +122,30 @@ export function Provider(props: Provider.Props) {
   if (Object.hasOwn(props, 'set'))
     throw new Error('Provider uses vars instead of set.')
   if (
-    (props.colorScheme !== 'light' && props.colorScheme !== 'dark') ||
+    (props.colorScheme !== 'light' &&
+      props.colorScheme !== 'dark' &&
+      props.colorScheme !== 'system') ||
     (props.vars !== undefined &&
       (typeof props.vars !== 'string' || !props.vars.trim()))
   )
     throw new Error(
-      'Native appearance requires a resolved light/dark scheme and a nonempty vars name.',
+      'Native appearance requires a light, dark, or system scheme and a nonempty vars name.',
     )
 
   const viewport = React.useContext(Viewport.context)
+  const system = React.useContext(Viewport.appearance)
+  const colorScheme =
+    props.colorScheme === 'system' ? system.colorScheme : props.colorScheme
+  const adaptive = props.colorScheme === 'system' ? system.adaptive : undefined
   const [store] = React.useState(() =>
-    Store.create({ colorScheme: props.colorScheme, set: props.vars, viewport }),
+    Store.create({ adaptive, colorScheme, set: props.vars, viewport }),
   )
   const [, publish] = React.useReducer((version: number) => version + 1, 0)
   const committed = React.useRef(props.children)
   const snapshot = store.getSnapshot()
   const pending =
-    snapshot.colorScheme !== props.colorScheme ||
+    snapshot.adaptive !== adaptive ||
+    snapshot.colorScheme !== colorScheme ||
     snapshot.set !== props.vars ||
     snapshot.viewport?.width !== viewport?.width ||
     snapshot.viewport?.height !== viewport?.height
@@ -93,9 +156,9 @@ export function Provider(props: Provider.Props) {
     // Keep the committed subtree until its selection is published. This avoids
     // rendering new application props with the previous store snapshot, without
     // mutating an external store during a potentially abandoned React render.
-    store.update({ colorScheme: props.colorScheme, set: props.vars, viewport })
+    store.update({ adaptive, colorScheme, set: props.vars, viewport })
     publish()
-  }, [children, pending, props.colorScheme, props.vars, store, viewport])
+  }, [adaptive, children, colorScheme, pending, props.vars, store, viewport])
 
   return React.createElement(Store.context.Provider, { value: store }, children)
 }
@@ -106,22 +169,49 @@ export declare namespace Provider {
   type Props = {
     /** Components that consume compiled native styling or values. */
     readonly children?: React.ReactNode | undefined
-    /** Resolved device scheme or an application override. */
-    readonly colorScheme: 'dark' | 'light'
+    /**
+     * Resolved device scheme, an application override, or `system` to follow the device.
+     * On iOS, `system` styles whose schemes differ only in color switch without updates.
+     */
+    readonly colorScheme: 'dark' | 'light' | 'system'
     /** Selected variables. Omission uses each configuration's default. */
     readonly vars?: string | undefined
   }
 }
 
-/** Compiler-inserted subscription for resolving native style applications. */
-export function useStyles() {
-  const store = React.useContext(Store.context) ?? unbound
-  const value = React.useSyncExternalStore(
-    store.subscribe,
-    store.getSnapshot,
-    store.getSnapshot,
+/**
+ * Compiler-inserted subscription for resolving native style applications.
+ * Outside a Provider, selections use default variables and the light scheme.
+ */
+export function useStyles(): useStyles.ReturnType {
+  const [fallback] = React.useState(() =>
+    Store.create({ colorScheme: 'light' }),
   )
-  return React.useMemo(() => styles(value), [value])
+  return Styles.use(React.useContext(Store.context) ?? fallback)
+}
+
+/** Resolver types for Provider-selected native styles. */
+export declare namespace useStyles {
+  /** Resolvers bound to the nearest Provider selection. */
+  type ReturnType = {
+    /** Resolves the `style` prop of applied props and preserves other props. */
+    readonly props: <
+      props extends Readonly<Record<string, unknown>> | null | undefined,
+    >(
+      props: props,
+    ) => props
+    /** Resolves an applied style, native style, style array, or style callback. */
+    readonly style: <style>(style: style, input?: unknown) => Style<style>
+  }
+  /**
+   * Resolved style type. Caller-owned values keep their types. Native applications
+   * always carry `style`, so an applied style drops the `undefined` allowed by the shared props type.
+   */
+  type Style<style> = [
+    style extends object ? (string extends keyof style ? style : never) : never,
+  ] extends [never]
+    ? style
+    : Exclude<style, undefined>
 }
 
 /** Compiler fallback for native view bindings when no native adapter is installed. */
@@ -171,46 +261,37 @@ export function useVars(
 }
 
 /**
- * Resolves compiled style props for components using React updates.
- * @param Component - Function, class, or ref-forwarding component receiving native styles.
+ * Resolves compiled style props for function components using React updates.
+ * @param Component - Function, memo, or ref-forwarding component receiving native styles.
  * @param options - Additional style-bearing prop names.
- * @returns A component preserving the original props and ref.
- * @throws For invalid style prop names or unresolved native selections.
+ * @returns A component with the original call signature and ref. Type parameters remain when `styleProps` is omitted.
+ * @throws For invalid style prop names.
+ */
+export function withStyles<
+  props extends object,
+  result extends React.ReactNode,
+>(
+  Component: (props: props) => result,
+  options?: NoInfer<withStyles.Options<(props: props) => result>>,
+): (props: props) => result
+/**
+ * Resolves compiled style props for class and host components using React updates.
+ * @param Component - Class component or host element type receiving native styles.
+ * @param options - Additional style-bearing prop names.
+ * @returns A component preserving the original props and instance ref.
+ * @throws For invalid style prop names.
  */
 export function withStyles<const component extends React.ElementType>(
   Component: component,
-  options: withStyles.Options<component> = {},
-) {
-  const additional = options.styleProps ?? []
-  if (
-    !Array.isArray(additional) ||
-    additional.some(
-      (name) =>
-        typeof name !== 'string' || !name || name === 'key' || name === 'ref',
-    )
-  )
-    throw new Error(
-      'withStyles requires style prop names excluding key and ref.',
-    )
-
-  const names = [...new Set(['style', 'contentContainerStyle', ...additional])]
-  const Wrapped = React.forwardRef<
-    React.ComponentRef<component>,
-    React.ComponentPropsWithoutRef<component>
-  >((props, ref) => {
-    const selected = useStyles()
-    const resolved: Record<string, unknown> = { ...props, ref }
-    for (const name of names)
-      if (Object.hasOwn(props, name))
-        resolved[name] = selected.style(
-          (props as Record<string, unknown>)[name],
-        )
-
-    return React.createElement(Component, resolved)
-  })
-  Wrapped.displayName = `withStyles(${typeof Component === 'string' ? Component : Component.displayName || Component.name || 'Component'})`
-
-  return Wrapped
+  options?: withStyles.Options<component>,
+): React.ForwardRefExoticComponent<React.ComponentPropsWithRef<component>>
+export function withStyles(
+  Component: React.ElementType,
+  options: withStyles.Options<
+    (props: Readonly<Record<string, unknown>>) => React.ReactNode
+  > = {},
+): React.ElementType {
+  return Styles.wrap(Component, options, useStyles)
 }
 
 /** Style-bearing component properties resolved by the wrapper. */
@@ -226,14 +307,3 @@ export declare namespace withStyles {
       | undefined
   }
 }
-
-function styles(value: NativeContext.Context | undefined) {
-  return {
-    props: (props: Record<string, unknown> | null | undefined) =>
-      props && Object.hasOwn(props, 'style')
-        ? { ...props, style: NativeContext.resolve(props.style, value) }
-        : props,
-    style: (style: unknown, input?: unknown) =>
-      NativeContext.resolve(style, value, input),
-  }
-}

package/src/runtime/NativeContext.ts

@@ -7,6 +7,14 @@ const dependency = Symbol('zyzz.native.dependency')
 
 /** Render-local set and resolved appearance. */
 export type Context = {
+  /**
+   * Builds a color that follows the platform appearance. When present, styles whose
+   * light and dark selections differ only in color use it and need no scheme update.
+   * Must be stable, since adapted styles are cached per selection pair.
+   */
+  readonly adaptive?:
+    | ((light: string | number, dark: string | number) => unknown)
+    | undefined
   /** Resolved system appearance or an explicit override. */
   readonly colorScheme: 'dark' | 'light'
   /** Named compiled set; omission uses each configuration default. */
@@ -37,7 +45,15 @@ export function create<const tables extends Tables>(
     const set = context.set ?? defaultVars
     const table = tables[set] ?? fallback
     if (!table) throw new Error(`Unknown native set: ${set}.`)
-    return table[context.colorScheme](input!).style
+    const style = table[context.colorScheme](input!).style
+    if (!context.adaptive) return style
+    return (
+      adapt(
+        table.light(input!).style,
+        table.dark(input!).style,
+        context.adaptive,
+      ) ?? style
+    )
   }
   return bind(select, (context) => {
     const table = tables[context.set ?? defaultVars] ?? fallback
@@ -94,10 +110,10 @@ export function responsive<
 export function application(value: unknown, input?: unknown): unknown {
   return {
     [binding]: (context: Context) => resolve(value, context, input),
-    [dependency]: (context: Context) => [
-      ...key(value, context),
-      ...key(input, context),
-    ],
+    [dependency]: (context: Context) =>
+      input === undefined
+        ? key(value, context)
+        : [...key(value, context), ...key(input, context)],
   }
 }
 
@@ -117,6 +133,64 @@ export function key(value: unknown, context: Context): readonly unknown[] {
   return []
 }
 
+const adapted = new WeakMap<object, WeakMap<object, object | null>>()
+
+/** Merges selections that differ only in color, or returns undefined. Results keep their identity across schemes. */
+function adapt(
+  light: unknown,
+  dark: unknown,
+  color: NonNullable<Context['adaptive']>,
+): unknown {
+  if (light === dark) return light
+  if (!record(light) || !record(dark)) return undefined
+  let pairs = adapted.get(light)
+  if (!pairs) adapted.set(light, (pairs = new WeakMap()))
+  if (pairs.has(dark)) return pairs.get(dark) ?? undefined
+  const result: Record<string, unknown> | null = (() => {
+    const keys = Object.keys(light)
+    if (keys.length !== Object.keys(dark).length) return null
+    const merged: Record<string, unknown> = {}
+    for (const key of keys) {
+      if (!Object.hasOwn(dark, key)) return null
+      const [first, second] = [light[key], dark[key]]
+      if (equal(first, second)) merged[key] = first
+      else if (
+        (key === 'color' || key.endsWith('Color')) &&
+        (typeof first === 'string' || typeof first === 'number') &&
+        (typeof second === 'string' || typeof second === 'number')
+      )
+        merged[key] = color(first, second)
+      else return null
+    }
+    return merged
+  })()
+  const value = result && Object.freeze(result)
+  pairs.set(dark, value)
+  return value ?? undefined
+}
+
+function equal(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) return true
+  if (Array.isArray(left))
+    return (
+      Array.isArray(right) &&
+      left.length === right.length &&
+      left.every((value, index) => equal(value, right[index]))
+    )
+  if (!record(left) || !record(right)) return false
+  const keys = Object.keys(left)
+  return (
+    keys.length === Object.keys(right).length &&
+    keys.every(
+      (key) => Object.hasOwn(right, key) && equal(left[key], right[key]),
+    )
+  )
+}
+
+function record(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
 function bind(
   select: (context: Context, input?: never) => unknown,
   read: (context: Context) => readonly unknown[],
@@ -125,10 +199,10 @@ function bind(
     return {
       style: {
         [binding]: (context: Context) => select(context, input),
-        [dependency]: (context: Context) => [
-          ...read(context),
-          ...key(input, context),
-        ],
+        [dependency]: (context: Context) =>
+          input === undefined
+            ? read(context)
+            : [...read(context), ...key(input, context)],
       },
     }
   }

package/src/runtime/NativeDynamic.ts

@@ -205,6 +205,13 @@ export function create(
             [`${property}Bottom`]: bottom,
             [`${property}Left`]: left,
           })
+        } else if (property === 'inset') {
+          const parts =
+            typeof value === 'string' ? Calculation.parts(value) : [value]
+          const [top, right = top, bottom = top, left = right] = parts.map(
+            (part) => Scalar.convert('offset', part, options, [property]),
+          )
+          Object.assign(output, { top, right, bottom, left })
         } else if (property === 'borderColor' || property === 'borderWidth') {
           for (const side of ['Top', 'Right', 'Bottom', 'Left'])
             output[

package/src/unplugin/index.ts

@@ -13,6 +13,7 @@ import * as AtRules from '../compiler/internal/AtRules.js'
 import * as Catalogs from '../compiler/internal/Catalogs.js'
 import * as Contract from '../compiler/internal/Contract.js'
 import * as Vite from '../vite/index.js'
+import * as ThemeRules from '../web/internal/Themes.js'
 
 /** Portable build configuration. Vite uses the options from `zyzz/vite` instead. */
 export type Options = {
@@ -284,7 +285,9 @@ const portable = createUnplugin<Options | undefined, false>(
             }
           }
 
+          // Only the combined stylesheet is emitted, so generated theme rules are shared once.
           const result = compiler.compile({
+            [ThemeRules.shared]: 'all',
             [Syntax.cache]: snapshot.programs(modules),
             compiler: options.compiler,
             reset: options.reset ? Reset.read() : undefined,
@@ -460,7 +463,7 @@ const portable = createUnplugin<Options | undefined, false>(
           let line = 0
           css = ''
           for (const chunk of chunks) {
-            if (!chunk.code) continue
+            if (!chunk.code.trim()) continue
             const traced = Mapping.fromMap(chunk.map)
             for (const mapping of Mapping.allMappings(traced)) {
               const generated = {

package/src/variants.ts

@@ -26,8 +26,9 @@ type ChoiceName<choices> = keyof choices extends infer key
       ? key
       : never
   : never
+/** `void` targets skip dynamic choice return types, which resolve through `Checked` and cycle when selections are read first. */
 type DynamicKeys<choices> = {
-  [key in keyof choices]: choices[key] extends (...args: never[]) => unknown
+  [key in keyof choices]: choices[key] extends (...args: never[]) => void
     ? key
     : never
 }[keyof choices]
@@ -36,7 +37,7 @@ type Choice<choices> =
   | {
       [key in DynamicKeys<choices>]: choices[key] extends (
         values: infer values,
-      ) => unknown
+      ) => void
         ? { readonly [name in key]: values } & {
             readonly [name in Exclude<keyof choices, key>]?: never
           }