zyzz 0.0.21 → 0.0.23

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
+}

package/src/runtime/NativeDynamic.ts

@@ -1,5 +1,6 @@
-/** Applies compiled native binding instructions to runtime scalar payloads. @module */
+/** Selects ordered native fragments and applies runtime scalar payloads. @module */
 import * as Scalar from '../react-native/internal/Scalar.js'
+import * as Calculation from '../react-native/internal/Calculation.js'
 import type * as StyleSheet from '../react-native/StyleSheet.js'
 import * as Native from './Native.js'
 import type * as Recipe from './Recipe.js'
@@ -45,14 +46,14 @@ export type Program = {
           readonly parts: readonly (
             | string
             | number
-            | { readonly slot: string }
+            | { readonly slot: string; readonly number?: true }
           )[]
         }
     )[]
   }[]
 }
 
-/** Binds generated instructions without running authoring callbacks or generating CSS. */
+/** Applies generated rules with bounded static caching and fresh scalar results. */
 export function create(
   options: create.Options,
 ): Callable<Record<string, unknown>> {
@@ -63,6 +64,10 @@ export function create(
     Object.freeze(value)
   }
   for (const style of Object.values(options.styles)) freeze(style)
+  const cache =
+    Object.keys(options.program.slots).length || options.payloads?.length
+      ? undefined
+      : new Map<string, StyleSheet.NativeStyle>()
 
   return (input = {}) => {
     const bindings: Record<string, string | number> = Object.create(null)
@@ -98,7 +103,9 @@ export function create(
     for (const [axis, choices] of Object.entries(options.axes)) {
       let value = Object.hasOwn(input, axis) ? input[axis] : undefined
       if (value === undefined) {
-        value = options.defaults[axis]
+        value = Object.hasOwn(options.defaults, axis)
+          ? options.defaults[axis]
+          : undefined
         if (value != null && Object.hasOwn(options.defaultPayloads ?? {}, axis))
           value = { [String(value)]: options.defaultPayloads![axis] }
       }
@@ -107,7 +114,8 @@ export function create(
         continue
       }
       let payload: unknown
-      if (typeof value === 'object' && !Array.isArray(value)) {
+      const scoped = typeof value === 'object' && !Array.isArray(value)
+      if (scoped) {
         const entries = Object.entries(value)
         if (entries.length !== 1)
           throw new Native.SelectionError(
@@ -128,12 +136,16 @@ export function create(
         (entry) => entry.axis === axis && entry.choice === choice,
       )
       if (definition) bind(definition.slots[0]!, payload)
-      else if (payload !== undefined)
+      else if (scoped)
         throw new Native.SelectionError(
           `Static native choice does not accept a payload: ${axis}.`,
         )
     }
 
+    const key = cache ? JSON.stringify(Object.values(selected)) : undefined
+    const cached = key === undefined ? undefined : cache?.get(key)
+    if (cached) return { style: input.style ? [cached, input.style] : cached }
+
     const output: Record<string, unknown> = {}
     let lineHeight: string | number | undefined
     for (const rule of options.program.rules) {
@@ -155,9 +167,15 @@ export function create(
           if (style.lineHeight !== undefined) lineHeight = undefined
           continue
         }
-        const values = step.parts.map((part) =>
-          typeof part === 'object' ? bindings[part.slot] : part,
-        )
+        const values = step.parts.map((part) => {
+          if (typeof part !== 'object') return part
+          const value = bindings[part.slot]
+          if (value !== undefined && part.number && typeof value !== 'number')
+            throw new Native.SelectionError(
+              'Native numeric bindings require numbers.',
+            )
+          return value
+        })
         if (values.some((value) => value === undefined))
           throw new Native.SelectionError(
             'Native binding program references an unbound slot.',
@@ -176,7 +194,7 @@ export function create(
         )
         if (property === 'padding' || property === 'margin') {
           const parts =
-            typeof value === 'string' ? value.trim().split(/\s+/) : [value]
+            typeof value === 'string' ? Calculation.parts(value) : [value]
           const [top, right = top, bottom = top, left = right] = parts.map(
             (part) =>
               Scalar.length(part, options, property === 'margin', [property]),
@@ -187,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[
@@ -227,6 +252,13 @@ export function create(
         ])
     }
     const style = output as StyleSheet.NativeStyle
+    if (cache && key !== undefined) {
+      Object.freeze(style)
+      // Bound retained selections without limiting the recipe's choice space.
+      if (cache.size >= 256) cache.delete(cache.keys().next().value!)
+      cache.set(key, style)
+    }
+
     return { style: input.style ? [style, input.style] : style }
   }
 }

package/src/runtime/NativeStatic.ts

@@ -0,0 +1,145 @@
+/** Selects finite native variants from precompiled fragments. @module */
+import * as Native from './Native.js'
+import type * as StyleSheet from '../react-native/StyleSheet.js'
+
+/**
+ * Binds finite selection data without including dynamic value converters.
+ * @param options - Compiler-owned axes, defaults, ordered rules, and native fragments.
+ * @returns A callable preserving finite choices and caller-owned native overrides.
+ * @throws {Native.SelectionError} For invalid selections, missing fragments, or invalid line heights.
+ */
+export function create<
+  const axes extends Readonly<Record<string, readonly string[]>>,
+>(options: create.Options<axes>): Native.Callable<axes> {
+  const axes = Object.entries(options.axes)
+  const rules = options.rules.map((rule) => ({
+    matches: rule.matches.map(([name, choices]) => {
+      const axis = axes.findIndex(([key]) => key === name)
+      return [
+        axis,
+        choices.map((choice) => axes[axis]![1].indexOf(choice)),
+      ] as const
+    }),
+    steps: rule.steps.map((step) => {
+      if (typeof step === 'number') return step
+      const style = options.styles[step]
+      if (!style)
+        throw new Native.SelectionError(
+          'Native binding program is missing a static style.',
+        )
+      freeze(style)
+      return style
+    }),
+  }))
+  const cache = new Map<string, StyleSheet.NativeStyle>()
+
+  return (input = {}) => {
+    for (const key of Object.keys(input))
+      if (key !== 'style' && !Object.hasOwn(options.axes, key))
+        throw new Native.SelectionError(`Unknown native recipe input: ${key}.`)
+    const selected: number[] = []
+    let key = ''
+    const values: Readonly<Record<string, unknown>> = input
+    for (const [axis, choices] of axes) {
+      const supplied = Object.hasOwn(values, axis) ? values[axis] : undefined
+      const value =
+        supplied === undefined
+          ? Object.hasOwn(options.defaults, axis)
+            ? options.defaults[axis]
+            : undefined
+          : supplied
+      if (
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+      ) {
+        const entries = Object.keys(value)
+        if (entries.length !== 1)
+          throw new Native.SelectionError(
+            'Native payloads require exactly one choice.',
+          )
+        if (choices.includes(entries[0]!))
+          throw new Native.SelectionError(
+            `Static native choice does not accept a payload: ${axis}.`,
+          )
+      }
+      const choice =
+        value == null
+          ? choices.length
+          : typeof value === 'string' || typeof value === 'boolean'
+            ? choices.indexOf(String(value))
+            : -1
+      if (choice < 0)
+        throw new Native.SelectionError(
+          `Unknown native recipe choice for ${axis}.`,
+        )
+      selected.push(choice)
+      key += `${choice},`
+    }
+    let style = cache.get(key)
+    if (!style) {
+      const output: Record<string, unknown> = {}
+      let lineHeight: number | undefined
+      for (const rule of rules) {
+        if (
+          !rule.matches.every(([axis, choices]) =>
+            choices.includes(selected[axis]!),
+          )
+        )
+          continue
+        for (const step of rule.steps) {
+          if (typeof step === 'number') lineHeight = step
+          else {
+            Object.assign(output, step)
+            if (step.lineHeight !== undefined) lineHeight = undefined
+          }
+        }
+      }
+      if (lineHeight !== undefined) {
+        if (
+          !Number.isFinite(lineHeight) ||
+          lineHeight < 0 ||
+          typeof output.fontSize !== 'number'
+        )
+          throw new Native.SelectionError(
+            'Numeric lineHeight requires an explicit fontSize and a nonnegative finite multiplier.',
+          )
+        output.lineHeight = lineHeight * output.fontSize
+        if (!Number.isFinite(output.lineHeight))
+          throw new Native.SelectionError(
+            'Converted lineHeight must be finite.',
+          )
+      }
+      style = Object.freeze(output) as StyleSheet.NativeStyle
+      // Retain a bounded working set even for recipes with many independent axes.
+      if (cache.size >= 256) cache.delete(cache.keys().next().value!)
+      cache.set(key, style)
+    }
+    return { style: input.style ? [style, input.style] : style }
+  }
+}
+
+/** Compiler-owned finite metadata and converted native fragments. */
+export declare namespace create {
+  /** Numeric steps are line-height multipliers resolved against the final font size. */
+  type Options<
+    axes extends Readonly<Record<string, readonly string[]>> = Readonly<
+      Record<string, readonly string[]>
+    >,
+  > = Native.create.Options<axes> & {
+    /** Ordered rules containing static fragment names and line-height multipliers. */
+    readonly rules: readonly {
+      /** Axis names and allowed choices, all of which must match. */
+      readonly matches: readonly (readonly [string, readonly string[]])[]
+      /** Fragment names or line-height multipliers applied in order. */
+      readonly steps: readonly (string | number)[]
+    }[]
+  }
+}
+
+function freeze(value: object): void {
+  if (Object.isFrozen(value)) return
+  for (const child of Object.values(value))
+    if (child && typeof child === 'object') freeze(child)
+  Object.freeze(value)
+}