zyzz 0.0.21 → 0.0.23

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

@@ -1,5 +1,6 @@
 /** Converts portable scalar values without source parsing or device state. @module */
 import * as Color from './Color.js'
+import * as Calculation from './Calculation.js'
 
 /** Portable property domains shared by static and dynamic native conversion. */
 export const properties = {
@@ -47,6 +48,7 @@ export const properties = {
   columnGap: 'length',
   direction: ['ltr', 'rtl'],
   display: ['contents', 'flex', 'none'],
+  flex: 'flex',
   flexBasis: 'size',
   flexDirection: ['column', 'column-reverse', 'row', 'row-reverse'],
   flexGrow: 'number',
@@ -59,6 +61,7 @@ export const properties = {
   fontWeight: 'weight',
   gap: 'length',
   height: 'size',
+  inset: 'boxOffset',
   justifyContent: [
     'center',
     'flex-end',
@@ -205,18 +208,87 @@ export function convert(
       return value
     fail('unsupported_value', 'Invalid native percentage.', path)
   }
-  if (kind === 'box' || kind === 'boxSigned') {
+  if (kind === 'flex') {
+    flex(value, options, path)
+    return 0
+  }
+  if (kind === 'box' || kind === 'boxOffset' || kind === 'boxSigned') {
     const values =
-      typeof value === 'string' ? value.trim().split(/\s+/) : [value]
+      typeof value === 'string' ? Calculation.parts(value) : [value]
     if (!values.length || values.length > 4)
       fail('unsupported_value', 'Use one to four scalar lengths.', path)
     for (const value of values)
-      length(value, options, kind === 'boxSigned', path)
+      if (kind === 'boxOffset') convert('offset', value, options, path)
+      else length(value, options, kind === 'boxSigned', path)
     return 0
   }
   return length(value, options, kind === 'signed' || kind === 'offset', path)
 }
 
+/**
+ * Expands the CSS `flex` shorthand to native longhands with CSS semantics.
+ * Omitted factors default to 1 and an omitted basis to 0, unlike the React Native `flex` prop.
+ */
+export function flex(
+  value: number | string,
+  options: Options,
+  path: readonly string[],
+): flex.ReturnType {
+  const keyword = typeof value === 'string' ? value.trim() : undefined
+  if (keyword === 'none')
+    return { flexBasis: 'auto', flexGrow: 0, flexShrink: 0 }
+  if (keyword === 'auto')
+    return { flexBasis: 'auto', flexGrow: 1, flexShrink: 1 }
+  if (keyword === 'initial')
+    return { flexBasis: 'auto', flexGrow: 0, flexShrink: 1 }
+
+  const parts = typeof value === 'string' ? Calculation.parts(value) : [value]
+  const kinds: ('basis' | 'factor')[] = []
+  for (const part of parts) {
+    const numeric =
+      typeof part === 'number' ||
+      /^[+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(part)
+    // A unitless zero after two factors is the basis, as in CSS.
+    const basis =
+      !numeric || (kinds.join(' ') === 'factor factor' && Number(part) === 0)
+    kinds.push(basis ? 'basis' : 'factor')
+  }
+  // Factors stay adjacent, and the basis may precede or follow them.
+  if (
+    ![
+      'basis',
+      'basis factor',
+      'basis factor factor',
+      'factor',
+      'factor basis',
+      'factor factor',
+      'factor factor basis',
+    ].includes(kinds.join(' '))
+  )
+    fail('unsupported_value', 'Invalid flex shorthand.', path)
+
+  const factors = parts
+    .filter((_, index) => kinds[index] === 'factor')
+    .map((part) => convert('number', Number(part), options, path) as number)
+  const basis = parts.find((_, index) => kinds[index] === 'basis')
+
+  return {
+    flexBasis: basis === undefined ? 0 : convert('size', basis, options, path),
+    flexGrow: factors[0] ?? 1,
+    flexShrink: factors[1] ?? 1,
+  }
+}
+
+/** Native longhands produced by the `flex` shorthand. */
+export declare namespace flex {
+  /** Grow and shrink factors with a converted basis. */
+  type ReturnType = {
+    readonly flexBasis: number | string
+    readonly flexGrow: number
+    readonly flexShrink: number
+  }
+}
+
 /** Converts a portable length to logical units. */
 export function length(
   value: number | string,
@@ -225,9 +297,19 @@ export function length(
   path: readonly string[],
 ): number {
   if (value === 0 || value === '0') return 0
+  if (typeof value === 'string' && /^\s*calc\(/i.test(value)) {
+    const result = Calculation.length(value.trim(), options)
+    if (!signed && result < 0)
+      fail(
+        'unsupported_value',
+        'Converted length is outside the native property domain.',
+        path,
+      )
+    return result
+  }
   const match =
     typeof value === 'string' &&
-    /^([+-]?(?:\d+(?:\.\d+)?|\.\d+))(px|rem)$/.exec(value)
+    /^([+-]?(?:\d+(?:\.\d+)?|\.\d+)(?:[eE][+-]?\d+)?)(px|rem)$/.exec(value)
   if (!match)
     fail(
       'unsupported_value',

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

@@ -0,0 +1,78 @@
+/** Owns scoped React subscriptions and committed native style readers. @module */
+import type * as NativeContext from '../../runtime/NativeContext.js'
+import * as React from 'react'
+
+/** Internal view update payload shared with the native bridge. */
+export type Patch = {
+  /** Runtime-local mounted view identifier. */
+  readonly id: number
+  /** Processed native style properties. */
+  readonly props: Record<string, unknown>
+}
+
+type Selection = {
+  readonly commit: () => void
+  readonly patch?: Patch | undefined
+}
+type Reader = (value: NativeContext.Context) => Selection
+type Writer = (patches: readonly Patch[]) => void
+
+/** Nearest configuration-owned selection. */
+export const context = React.createContext<
+  ReturnType<typeof create> | undefined
+>(undefined)
+
+/** Creates subscriptions owned by a Provider or a provider-free style consumer. */
+export function create(initial: NativeContext.Context) {
+  let snapshot = Object.freeze(initial)
+  const bindings = new Map<Reader, Writer>()
+  const listeners = new Set<() => void>()
+
+  return {
+    bind(read: Reader, write: Writer) {
+      bindings.set(read, write)
+      return () => {
+        bindings.delete(read)
+      }
+    },
+    getSnapshot: () => snapshot,
+    subscribe(listener: () => void) {
+      const entry = () => listener()
+      listeners.add(entry)
+      return () => {
+        listeners.delete(entry)
+      }
+    },
+    update(value: NativeContext.Context) {
+      if (
+        snapshot.colorScheme === value.colorScheme &&
+        snapshot.set === value.set &&
+        snapshot.viewport?.height === value.viewport?.height &&
+        snapshot.viewport?.width === value.viewport?.width
+      )
+        return
+
+      // Resolve every binding before applying a scope change that can fail.
+      const selections: Selection[] = []
+      const batches = new Map<Writer, Patch[]>()
+      for (const [read, write] of bindings) {
+        const selection = read(value)
+        selections.push(selection)
+        if (!selection.patch) continue
+        let batch = batches.get(write)
+        if (!batch) {
+          batch = []
+          batches.set(write, batch)
+        }
+        batch.push(selection.patch)
+      }
+      for (const [write, patches] of batches) write(patches)
+
+      snapshot = Object.freeze(value)
+      for (const selection of selections) selection.commit()
+      // Subscriptions added during notification wait for the next change.
+      for (const listener of Array.from(listeners))
+        if (listeners.has(listener)) listener()
+    },
+  }
+}

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

@@ -0,0 +1,77 @@
+/** Resolves compiled style applications for consumers outside native view bindings. @module */
+import * as NativeContext from '../../runtime/NativeContext.js'
+import * as React from 'react'
+import type { useStyles } from '../react.js'
+import type * as Store from './Store.js'
+
+/** Subscribes to a selection and returns its style resolvers. */
+export function use(
+  store: ReturnType<typeof Store.create>,
+): useStyles.ReturnType {
+  const value = React.useSyncExternalStore(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+  )
+  return React.useMemo(
+    () => ({
+      props: (props) =>
+        props && Object.hasOwn(props, 'style')
+          ? { ...props, style: NativeContext.resolve(props.style, value) }
+          : props,
+      style: <style>(style: style, input?: unknown) =>
+        NativeContext.resolve(style, value, input) as useStyles.Style<style>,
+    }),
+    [value],
+  )
+}
+
+/**
+ * Wraps a component so its style props resolve through an entrypoint's selection hook.
+ * @throws For invalid style prop names.
+ */
+export function wrap<const component extends React.ElementType>(
+  Component: component,
+  options: wrap.Options,
+  useStyles: () => useStyles.ReturnType,
+) {
+  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 prop names accepted by a wrapper. */
+export declare namespace wrap {
+  /** Entrypoints narrow these names to the wrapped component's props. */
+  type Options = {
+    /** Additional style props declared by the wrapped component. */
+    readonly styleProps?: readonly string[] | undefined
+  }
+}

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 */
+/** React subscriptions for compiled native styles and variable values. @module */
+import * as Config from '../Config.js'
+import type * as NativeContext from '../runtime/NativeContext.js'
+import * as NativeVars from '../runtime/NativeVars.js'
 import * as React from 'react'
-import * as NativeContext from '../runtime/NativeContext.js'
+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 context = React.createContext(styles(undefined))
+/** 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))
 
-/** Supplies set and resolved device appearance to compiled native components. */
+  function BoundProvider(props: defineConfig.ProviderProps<options>) {
+    if (props.vars !== undefined && !names?.has(props.vars))
+      throw new Error(`Unknown native vars: ${props.vars}.`)
+
+    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 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 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. */
+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)
 }
 
-/** Compiler-inserted unconditional subscription, including memoized components. */
-export function useStyles() {
-  return React.useContext(context)
+/**
+ * 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 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>,
+): 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)
 }
 
-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-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
   }
 }