zyzz 0.0.21 → 0.0.22

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

@@ -0,0 +1,85 @@
+/** Resolves portable references for native tables and callback expressions. @module */
+import * as Calculation from './Calculation.js'
+import type * as Scalar from './Scalar.js'
+import type * as Style from '../../Style.js'
+import * as Token from '../../internal/Token.js'
+
+/** Identifies values whose behavior requires a web target. */
+export class UnsupportedError extends Error {
+  override name = 'Tokens.UnsupportedError'
+}
+
+/** Selects live token aliases and schemes without evaluating authored code. */
+export function resolve(
+  input: Style.Declaration['value'],
+  options: resolve.Options,
+): string | number {
+  const active = new Set<Token.Reference>()
+  function scalar(
+    value: Token.Value | Style.Declaration['value'],
+  ): string | number {
+    if (typeof value === 'number' || typeof value === 'string') return value
+    if (
+      Token.is(value) &&
+      !Object.getOwnPropertyDescriptor(value, Token.web)?.value
+    ) {
+      if (active.has(value))
+        throw new Error('Native token aliases must not form a cycle.')
+      const metadata = options.metadata
+      const shared =
+        metadata &&
+        (metadata.contract === value.contract ||
+          (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.')
+      active.add(value)
+      const result = scalar(next)
+      active.delete(value)
+      return result
+    }
+    if (Token.isExpression(value)) {
+      const text = value.parts.map(scalar).join('')
+      if (
+        !('group' in value) ||
+        value.group !== 'spacing' ||
+        !/^\s*calc\(/i.test(text)
+      )
+        return text
+      return `${Calculation.length(text, options) / (options.units?.px ?? 1)}px`
+    }
+    if (
+      value &&
+      typeof value === 'object' &&
+      'light' in value &&
+      'dark' in value
+    ) {
+      if (value.light !== value.dark)
+        options.resolution.schemeIndependent = false
+      return scalar(value[options.colorScheme])
+    }
+    if (value && typeof value === 'object' && 'default' in value)
+      throw new UnsupportedError(
+        'Media-conditioned variables require a web target.',
+      )
+    throw new UnsupportedError(
+      'Web variables, expressions, and dynamic bindings are not native scalar tokens.',
+    )
+  }
+  return scalar(input)
+}
+
+/** Native token selection and explicit unit conversion. */
+export declare namespace resolve {
+  /** Profile metadata and scheme independence shared by table preparation. */
+  type Options = Scalar.Options & {
+    readonly colorScheme: 'dark' | 'light'
+    readonly metadata: Token.Metadata | undefined
+    readonly resolution: { schemeIndependent: boolean }
+  }
+}

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

@@ -0,0 +1,8 @@
+/** Connects the native device adapter to framework subscriptions. @module */
+import type * as Media from '../../runtime/internal/NativeMedia.js'
+import * as React from 'react'
+
+/** Window measurements owned by the native Provider lifecycle. */
+export const context = React.createContext<Media.Viewport | undefined>(
+  undefined,
+)

package/src/react-native/react.ts

@@ -1,47 +1,239 @@
-/** React lifecycle for automatically compiled native styling. @module */
-import * as React from 'react'
+/** React subscriptions for compiled native styles and variable values. @module */
+import * as Config from '../Config.js'
 import * 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 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
+      ? undefined
+      : new Set(Object.keys((options as Config.VariableOptions).vars))
 
-const context = React.createContext(styles(undefined))
+  function BoundProvider(props: defineConfig.ProviderProps<options>) {
+    if (props.vars !== undefined && !names?.has(props.vars))
+      throw new Error(`Unknown native vars: ${props.vars}.`)
 
-/** Supplies set and resolved device appearance to compiled native components. */
+    return React.createElement(Provider, {
+      ...props,
+      vars: props.vars ?? defaultVars,
+    })
+  }
+
+  return Object.freeze({
+    ...config,
+    Provider: BoundProvider,
+  }) as defineConfig.ReturnType<options>
+}
+
+/** Native configuration helpers and inferred Provider props. */
+export declare namespace defineConfig {
+  /** Resolved scheme and variable names from the owning configuration. */
+  type ProviderProps<options extends Config.create.Options> = Omit<
+    Provider.Props,
+    'vars'
+  > & {
+    /** Selected variables. Omission uses the owning configuration's default. */
+    readonly vars?:
+      | (options extends { defaultVars: string; vars: infer catalog }
+          ? Extract<keyof catalog, string>
+          : never)
+      | undefined
+  }
+  /** Existing authoring helpers plus a configuration-scoped Provider. */
+  type ReturnType<options extends Config.create.Options = {}> =
+    Config.create.ReturnType<options> & {
+      /** Provides this configuration's typed selection to native consumers. */
+      readonly Provider: React.FunctionComponent<ProviderProps<options>>
+    }
+}
+
+/** Supplies selected variables, appearance, and adapter measurements to this subtree. */
 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.set !== undefined &&
-      (typeof props.set !== 'string' || !props.set.trim()))
+    (props.vars !== undefined &&
+      (typeof props.vars !== 'string' || !props.vars.trim()))
   )
     throw new Error(
-      'Native appearance requires a resolved light/dark scheme and a nonempty set name.',
+      'Native appearance requires a resolved light/dark scheme and a nonempty vars name.',
     )
-  const value = React.useMemo(
-    () => styles({ colorScheme: props.colorScheme, set: props.set }),
-    [props.colorScheme, props.set],
+
+  const viewport = React.useContext(Viewport.context)
+  const [store] = React.useState(() =>
+    Store.create({ colorScheme: props.colorScheme, set: props.vars, viewport }),
   )
-  return React.createElement(context.Provider, { value }, props.children)
+  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.set !== props.vars ||
+    snapshot.viewport?.width !== viewport?.width ||
+    snapshot.viewport?.height !== viewport?.height
+  const children = pending ? committed.current : props.children
+  React.useLayoutEffect(() => {
+    committed.current = children
+    if (!pending) return
+    // 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 })
+    publish()
+  }, [children, pending, props.colorScheme, props.vars, store, viewport])
+
+  return React.createElement(Store.context.Provider, { value: store }, children)
 }
 
-/** Application boundary inputs. Pass React Native's useColorScheme result with a light fallback. */
+/** Application boundary for native variable selection. */
 export declare namespace Provider {
-  /** Theme selection and resolved appearance for this React subtree. */
-  type Props = NativeContext.Context & {
-    /** Components that consume compiled native styles. */
+  /** Resolved appearance and a configuration-relative variable name. */
+  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'
+    /** Selected variables. Omission uses each configuration's default. */
+    readonly vars?: string | undefined
   }
 }
 
-/** Compiler-inserted unconditional subscription, including memoized components. */
+/** Compiler-inserted subscription for resolving native style applications. */
 export function useStyles() {
-  return React.useContext(context)
+  const store = React.useContext(Store.context) ?? unbound
+  const value = React.useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  )
+  return React.useMemo(() => styles(value), [value])
+}
+
+/** Compiler fallback for native view bindings when no native adapter is installed. */
+export function useNativeStyles() {
+  const selected = useStyles()
+  return { ...selected, view: selected.props }
+}
+
+/**
+ * Reads readonly native variables using the nearest Provider's selection.
+ * @throws For missing providers, uncompiled definitions, or unsupported field reads.
+ */
+export function useVars<const variables extends Vars.Definition>(
+  variables: variables,
+  select?: undefined,
+): NativeVars.Values<Vars.Extract<variables>>
+/**
+ * Subscribes to a selection, comparing results with Object.is.
+ * @throws For invalid variable selection or unsupported field reads.
+ */
+export function useVars<const variables extends Vars.Definition, selected>(
+  variables: variables,
+  select: (values: NativeVars.Values<Vars.Extract<variables>>) => selected,
+): selected
+export function useVars(
+  variables: Vars.Definition,
+  select: (values: never) => unknown = (values) => values,
+) {
+  const store = React.useContext(Store.context)
+  if (!store) throw new Error('useVars requires a Zyzz Provider.')
+
+  const read = React.useMemo(() => {
+    let previous: NativeContext.Context | undefined
+    let selected: unknown
+    return () => {
+      const snapshot = store.getSnapshot()
+      if (snapshot !== previous) {
+        const next = select(NativeVars.read(variables, snapshot) as never)
+        if (!previous || !Object.is(selected, next)) selected = next
+        previous = snapshot
+      }
+      return selected
+    }
+  }, [select, store, variables])
+
+  return React.useSyncExternalStore(store.subscribe, read, read)
+}
+
+/**
+ * Resolves compiled style props for components using React updates.
+ * @param Component - Function, class, 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.
+ */
+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
+}
+
+/** Style-bearing component properties resolved by the wrapper. */
+export declare namespace withStyles {
+  /** Additional names are resolved alongside style and contentContainerStyle. */
+  type Options<component extends React.ElementType> = {
+    /** Additional style props declared by the wrapped component. */
+    readonly styleProps?:
+      | readonly Exclude<
+          Extract<keyof React.ComponentProps<component>, string>,
+          'key' | 'ref'
+        >[]
+      | undefined
+  }
 }
 
 function styles(value: NativeContext.Context | undefined) {
   return {
-    style: (style: unknown, input?: unknown) =>
-      NativeContext.resolve(style, value, input),
     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/react-native/reanimated.ts

@@ -0,0 +1,162 @@
+/** Publishes scoped native selections to Reanimated shared values. @module */
+import * as NativeContext from '../runtime/NativeContext.js'
+import * as NativeVars from '../runtime/NativeVars.js'
+import * as React from 'react'
+import * as ReactNative from 'react-native'
+import * as Reanimated from 'react-native-reanimated'
+import * as Store from './internal/Store.js'
+import type * as StyleSheet from './StyleSheet.js'
+import type * as Vars from '../Vars.js'
+
+/**
+ * Reads a numeric or color property from a selected, composed native style.
+ * @param appliedStyle - Applied native style, including arrays and caller overrides.
+ * @param property - Numeric or color property to publish.
+ * @returns A shared value updated on style input and Provider selection changes.
+ * @throws For unresolved bindings, missing properties, or unsupported property values.
+ */
+export function useAnimatedStyleValue<
+  const property extends useAnimatedStyleValue.Property,
+>(
+  appliedStyle: StyleSheet.StyleProp<object>,
+  property: property,
+): Reanimated.SharedValue<useAnimatedStyleValue.Value<property>> {
+  const store = React.useContext(Store.context)
+  const read = React.useCallback(() => {
+    const resolved = NativeContext.resolve(appliedStyle, store?.getSnapshot())
+    const style = ReactNative.StyleSheet.flatten(
+      resolved as ReactNative.StyleProp<ReactNative.ViewStyle>,
+    )
+    const value = style?.[property as keyof ReactNative.ViewStyle]
+    const color = property === 'color' || property.endsWith('Color')
+    if (
+      color
+        ? typeof value !== 'string' || ReactNative.processColor(value) == null
+        : typeof value !== 'number' || !Number.isFinite(value)
+    )
+      throw new Error(
+        `useAnimatedStyleValue requires a numeric or color value for ${property}.`,
+      )
+
+    return value as useAnimatedStyleValue.Value<property>
+  }, [appliedStyle, property, store])
+
+  return useSelection(read, store)
+}
+
+/** Properties supported by scalar style animation bindings. */
+export declare namespace useAnimatedStyleValue {
+  /** Numeric native properties and native color properties. */
+  type Property = {
+    [key in keyof StyleSheet.NativeStyle]-?: key extends
+      | 'color'
+      | `${string}Color`
+      ? key
+      : Extract<StyleSheet.NativeStyle[key], number> extends never
+        ? never
+        : key
+  }[keyof StyleSheet.NativeStyle] &
+    string
+  /** Color strings or finite numeric selections, excluding layout strings. */
+  type Value<property extends Property> = property extends
+    | 'color'
+    | `${string}Color`
+    ? string
+    : number
+}
+
+/**
+ * Publishes compiled native variables without subscribing the component to React updates.
+ * @param variables - Statically linked variables from the owning configuration.
+ * @param select - Optional JS selector, with results compared using Object.is.
+ * @returns A shared value containing the selected serializable native values.
+ * @throws For a missing Provider, unsupported variable reads, or nonserializable selections.
+ */
+export function useAnimatedVars<const variables extends Vars.Definition>(
+  variables: variables,
+  select?: undefined,
+): Reanimated.SharedValue<NativeVars.Values<Vars.Extract<variables>>>
+/** Publishes a selected variable value to the UI thread. */
+export function useAnimatedVars<
+  const variables extends Vars.Definition,
+  selected extends useAnimatedVars.Value,
+>(
+  variables: variables,
+  select: (values: NativeVars.Values<Vars.Extract<variables>>) => selected,
+): Reanimated.SharedValue<selected>
+export function useAnimatedVars(
+  variables: Vars.Definition,
+  select: (values: never) => unknown = (values) => values,
+) {
+  const store = React.useContext(Store.context)
+  if (!store) throw new Error('useAnimatedVars requires a Zyzz Provider.')
+
+  const read = React.useCallback(
+    () => select(NativeVars.read(variables, store.getSnapshot()) as never),
+    [select, store, variables],
+  )
+
+  return useSelection(read, store)
+}
+
+/** Serializable selections shared with animation worklets. */
+export declare namespace useAnimatedVars {
+  /** Plain native values, arrays, and objects without functions or class instances. */
+  type Value =
+    | boolean
+    | null
+    | number
+    | readonly Value[]
+    | string
+    | undefined
+    | { readonly [key: string]: Value }
+}
+
+function useSelection<value>(
+  read: () => value,
+  store: ReturnType<typeof Store.create> | undefined,
+): Reanimated.SharedValue<value> {
+  const initial = read()
+  serializable(initial)
+  const previous = React.useRef(initial)
+  const shared = Reanimated.useSharedValue(initial)
+
+  React.useLayoutEffect(() => {
+    const update = () => {
+      const next = read()
+      if (Object.is(previous.current, next)) return
+      serializable(next)
+      shared.set(next)
+      previous.current = next
+    }
+    update()
+    return store?.subscribe(update)
+  }, [read, shared, store])
+
+  return shared
+}
+
+function serializable(value: unknown, ancestors = new Set<object>()): void {
+  if (value == null || typeof value === 'string' || typeof value === 'boolean')
+    return
+  if (typeof value === 'number' && Number.isFinite(value)) return
+  if (
+    typeof value !== 'object' ||
+    (Array.isArray(value)
+      ? Object.getPrototypeOf(value) !== Array.prototype
+      : Object.getPrototypeOf(value) !== Object.prototype &&
+        Object.getPrototypeOf(value) !== null)
+  )
+    throw new Error(
+      'Animated selections require finite, serializable native values.',
+    )
+
+  if (ancestors.has(value))
+    throw new Error('Animated selections cannot contain cycles.')
+  if (Object.getOwnPropertySymbols(value).length)
+    throw new Error('Animated selections cannot contain symbol properties.')
+
+  ancestors.add(value)
+  for (const entry of Object.values(value)) serializable(entry, ancestors)
+  ancestors.delete(value)
+}

package/src/runtime/NativeContext.ts

@@ -1,7 +1,9 @@
-/** Defers precompiled native selection until a React render supplies its context. @module */
+/** Defers precompiled native selection until a consumer supplies its scoped selection. @module */
 import type * as Native from './Native.js'
+import * as Media from './internal/NativeMedia.js'
 
 const binding = Symbol('zyzz.native.context')
+const dependency = Symbol('zyzz.native.dependency')
 
 /** Render-local set and resolved appearance. */
 export type Context = {
@@ -9,6 +11,8 @@ export type Context = {
   readonly colorScheme: 'dark' | 'light'
   /** Named compiled set; omission uses each configuration default. */
   readonly set?: string | undefined
+  /** Logical window dimensions supplied by the native adapter. */
+  readonly viewport?: Media.Viewport | undefined
 }
 
 type Callable = (input: never) => Native.Props<object>
@@ -25,6 +29,9 @@ export function create<const tables extends Tables>(
     Object.keys(tables).length === 1 && defaultVars === 'default'
       ? tables.default
       : undefined
+  const selections = new Set(
+    Object.values(tables).flatMap((table) => [table.dark, table.light]),
+  )
 
   function select(context: Context, input?: never) {
     const set = context.set ?? defaultVars
@@ -32,22 +39,12 @@ export function create<const tables extends Tables>(
     if (!table) throw new Error(`Unknown native set: ${set}.`)
     return table[context.colorScheme](input!).style
   }
-  function props(input?: never) {
-    return {
-      style: {
-        [binding]: (context: Context) => select(context, input),
-      },
-    }
-  }
-  const defaults = props()
-  Object.freeze(defaults.style)
-  Object.freeze(defaults)
-  const callable = (input?: never) =>
-    input === undefined ? defaults : props(input)
-  Object.defineProperty(callable, binding, {
-    value: select,
-  })
-  return callable as tables[keyof tables]['light']
+  return bind(select, (context) => {
+    const table = tables[context.set ?? defaultVars] ?? fallback
+    if (!table)
+      throw new Error(`Unknown native set: ${context.set ?? defaultVars}.`)
+    return selections.size === 1 ? [] : [table[context.colorScheme]]
+  }) as tables[keyof tables]['light']
 }
 
 /** Resolves generated bindings and arrays while preserving caller-owned native objects. */
@@ -72,3 +69,77 @@ export function resolve(
     return (...args: unknown[]) => resolve(value(...args), context)
   return value
 }
+
+/** Selects a precompiled media alternative before applying its scoped styling. */
+export function responsive<
+  const profiles extends Readonly<Record<string, Callable>>,
+>(
+  queries: readonly Media.Query[],
+  profiles: profiles,
+): profiles[keyof profiles] {
+  return bind(
+    (context, input) => {
+      const profile = profiles[Media.select(queries, context.viewport)]
+      if (!profile) throw new Error('Native media alternative is missing.')
+      return resolve(profile, context, input)
+    },
+    (context) => {
+      const profile = profiles[Media.select(queries, context.viewport)]
+      return [profile, ...key(profile, context)]
+    },
+  ) as unknown as profiles[keyof profiles]
+}
+
+/** Retains a compiled application and its input until a view selects its context. */
+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),
+    ],
+  }
+}
+
+/** Returns compiler-owned alternatives consumed by a native style application. */
+export function key(value: unknown, context: Context): readonly unknown[] {
+  if (Array.isArray(value)) return value.flatMap((entry) => key(entry, context))
+  if (
+    value &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    dependency in value
+  ) {
+    const read = value[dependency]
+    if (typeof read === 'function') return read(context)
+  }
+  if (value && typeof value === 'object' && 'style' in value)
+    return key(value.style, context)
+  return []
+}
+
+function bind(
+  select: (context: Context, input?: never) => unknown,
+  read: (context: Context) => readonly unknown[],
+) {
+  function props(input?: never) {
+    return {
+      style: {
+        [binding]: (context: Context) => select(context, input),
+        [dependency]: (context: Context) => [
+          ...read(context),
+          ...key(input, context),
+        ],
+      },
+    }
+  }
+  const defaults = props()
+  Object.freeze(defaults.style)
+  Object.freeze(defaults)
+  const callable = (input?: never) =>
+    input === undefined ? defaults : props(input)
+  Object.defineProperties(callable, {
+    [binding]: { value: select },
+    [dependency]: { value: read },
+  })
+  return callable
+}