zyzz 0.0.22 → 0.0.24

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

@@ -5,6 +5,7 @@ import NativeZyzz from './NativeZyzz.js'
 import * as React from 'react'
 import * as ReactNative from 'react-native'
 import * as Store from './Store.js'
+import * as Styles from './Styles.js'
 import * as Subscription from '../react.js'
 import * as Viewport from './Viewport.js'
 
@@ -13,34 +14,128 @@ export function defineConfig<const options extends Config.create.Options = {}>(
   options: options & Parameters<typeof Config.create<options>>[0] = {} as never,
 ): Subscription.defineConfig.ReturnType<options> {
   const config = Subscription.defineConfig<options>(options)
-  return Object.freeze({
-    ...config,
-    Provider: dimensions(config.Provider),
-  }) as Subscription.defineConfig.ReturnType<options>
+  // Copy descriptors rather than spreading, so deferred helpers stay deferred.
+  return Object.freeze(
+    Object.defineProperties(
+      { Provider: dimensions(config.Provider) } as Record<string, unknown>,
+      Object.fromEntries(
+        Object.entries(Object.getOwnPropertyDescriptors(config)).filter(
+          ([name]) => name !== 'Provider',
+        ),
+      ),
+    ),
+  ) as unknown as Subscription.defineConfig.ReturnType<options>
 }
 
 /** Provides selected variables, appearance, and automatic native dimensions. */
 export const Provider = dimensions(Subscription.Provider)
 
-export { useStyles, useVars, withStyles } from '../react.js'
+/**
+ * Compiler-inserted subscription for resolving native style applications.
+ * Outside a Provider, selections use default variables, the light scheme, and window dimensions.
+ */
+export function useStyles(): Subscription.useStyles.ReturnType {
+  const owner = React.useContext(Store.context)
+  const [fallback] = React.useState(() =>
+    Store.create({
+      colorScheme: 'light',
+      viewport: ReactNative.Dimensions.get('window'),
+    }),
+  )
+  React.useLayoutEffect(() => {
+    if (owner) return
+    const update = () =>
+      fallback.update({
+        colorScheme: 'light',
+        viewport: ReactNative.Dimensions.get('window'),
+      })
+    // Dimensions can change between render and commit.
+    update()
+    const subscription = ReactNative.Dimensions.addEventListener(
+      'change',
+      update,
+    )
+    return () => subscription.remove()
+  }, [fallback, owner])
+
+  return Styles.use(owner ?? fallback)
+}
+
+export { useVars } from '../react.js'
+
+/**
+ * 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<Subscription.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?: Subscription.withStyles.Options<component>,
+): React.ForwardRefExoticComponent<React.ComponentPropsWithRef<component>>
+export function withStyles(
+  Component: React.ElementType,
+  options: Subscription.withStyles.Options<
+    (props: Readonly<Record<string, unknown>>) => React.ReactNode
+  > = {},
+): React.ElementType {
+  return Styles.wrap(Component, options, useStyles)
+}
 
 function dimensions<props extends Subscription.Provider.Props>(
   Component: React.FunctionComponent<props>,
 ): React.FunctionComponent<props> {
   return function WindowProvider(props: props) {
     const window = ReactNative.useWindowDimensions()
+    const scheme = ReactNative.useColorScheme()
     const viewport = React.useMemo(
       () => ({ height: window.height, width: window.width }),
       [window.height, window.width],
     )
+    const appearance = React.useMemo(
+      () => ({
+        adaptive,
+        colorScheme: scheme === 'dark' ? ('dark' as const) : ('light' as const),
+      }),
+      [scheme],
+    )
     return React.createElement(
       Viewport.context.Provider,
       { value: viewport },
-      React.createElement(Component, props),
+      React.createElement(
+        Viewport.appearance.Provider,
+        { value: appearance },
+        React.createElement(Component, props),
+      ),
     )
   }
 }
 
+// iOS resolves these colors from the window's appearance, so scheme changes need no Fabric update.
+const adaptive =
+  ReactNative.Platform.OS === 'ios'
+    ? (light: string | number, dark: string | number) =>
+        ReactNative.DynamicColorIOS({
+          dark: dark as ReactNative.ColorValue,
+          light: light as ReactNative.ColorValue,
+        })
+    : undefined
+
 /** Compiler-only binding path, with React subscriptions for Expo Go. */
 export const useNativeStyles = useBindings
 
@@ -55,55 +150,68 @@ type Instance = {
 
 function useBindings() {
   const owner = React.useContext(Store.context)
-  const [fallback] = React.useState(() =>
-    Store.create({
+  // Views inside a Provider never read the fallback, so it is created only outside one.
+  const fallbackRef = React.useRef<ReturnType<typeof Store.create> | undefined>(
+    undefined,
+  )
+  if (!owner)
+    fallbackRef.current ??= Store.create({
       colorScheme: 'light',
       viewport: ReactNative.Dimensions.get('window'),
-    }),
-  )
-  const store = owner ?? fallback
+    })
+  const fallback = fallbackRef.current
+  const store = (owner ?? fallback)!
   const [, render] = React.useReducer((count: number) => count + 1, 0)
-  const [refs] = React.useState(
-    () =>
-      new Map<
-        Instance,
-        {
-          active: boolean
-          ref: React.Ref<Instance> | undefined
-          release: () => void
-        }
-      >(),
-  )
-  React.useLayoutEffect(() => {
-    for (const [instance, entry] of refs) {
-      if (entry.active) continue
-      entry.release()
-      refs.delete(instance)
+  const [refs] = React.useState(() => {
+    const entries = new Map<
+      Instance,
+      {
+        active: boolean
+        ref: React.Ref<Instance> | undefined
+        release: () => void
+      }
+    >()
+    let scheduled = false
+    return {
+      entries,
+      // Runs after the commit, once every cleanup and re-attachment has settled, without a layout effect per render.
+      sweep() {
+        if (scheduled) return
+        scheduled = true
+        queueMicrotask(() => {
+          scheduled = false
+          for (const [instance, entry] of entries) {
+            if (entry.active) continue
+            entry.release()
+            entries.delete(instance)
+          }
+        })
+      },
     }
   })
-  React.useLayoutEffect(
-    () => () => {
-      for (const entry of refs.values()) entry.release()
-      refs.clear()
-    },
-    [refs],
-  )
   return {
     style: NativeContext.application,
     view: (props: Record<string, unknown>) => {
       const snapshot = store.getSnapshot()
       const selected = NativeContext.resolve(props.style, snapshot)
       const initial = NativeContext.key(props.style, snapshot)
+      // A context-free style never needs a binding, so React keeps a stable element without a ref wrapper.
+      if (
+        !initial.length &&
+        typeof selected !== 'function' &&
+        props.ref == null
+      )
+        return { ...props, style: selected }
 
       return {
         ...props,
         ref: (value: Instance | null) => {
           const ref = props.ref as React.Ref<Instance> | undefined
           if (!value) return
-          let entry = refs.get(value)
+          let entry = refs.entries.get(value)
           if (entry && entry.ref !== ref) {
             entry.release()
-            refs.delete(value)
+            refs.entries.delete(value)
             entry = undefined
           }
           if (!entry) {
@@ -118,7 +226,7 @@ function useBindings() {
                 else if (ref) ref.current = null
               },
             }
-            refs.set(value, entry)
+            refs.entries.set(value, entry)
           }
           entry.active = true
           const attached = entry
@@ -133,7 +241,9 @@ function useBindings() {
               if (store.getSnapshot() !== snapshot) render()
               return unsubscribe
             }
-            const id = NativeZyzz!.attach(node, nativeProps(selected))
+            // Most views never change selection, so they bind on their first patch.
+            let id: number | undefined
+            let bound = false
             let previous = initial
             const read = (context: NativeContext.Context) => {
               const keys = NativeContext.key(props.style, context)
@@ -142,30 +252,38 @@ function useBindings() {
                 keys.every((key, index) => Object.is(key, previous[index]))
               )
                 return { commit: () => {} }
-              const selected = NativeContext.resolve(props.style, context)
-              if (!selective(selected)) return { commit: render }
+              const next = NativeContext.resolve(props.style, context)
+              if (!selective(next)) return { commit: render }
+              id ??= ++bindings
               return {
                 commit: () => {
                   previous = keys
+                  bound = true
                 },
-                patch: {
-                  id,
-                  props: nativeProps(selected),
-                },
+                patch: bound
+                  ? { id, props: nativeProps(next) }
+                  : {
+                      id,
+                      node,
+                      props: nativeProps(next),
+                      rendered: nativeProps(selected),
+                    },
               }
             }
             // Context can change between render and committing the host ref.
-            const current = read(store.getSnapshot())
-            if (current.patch) write([current.patch])
-            current.commit()
+            if (store.getSnapshot() !== snapshot) {
+              const current = read(store.getSnapshot())
+              if (current.patch) write([current.patch])
+              current.commit()
+            }
             const unbind = store.bind(read, write)
             return () => {
               unbind()
-              NativeZyzz!.detach(id)
+              if (bound) NativeZyzz!.detach(id!)
             }
           })()
           const update = () =>
-            fallback.update({
+            fallback!.update({
               colorScheme: 'light',
               viewport: ReactNative.Dimensions.get('window'),
             })
@@ -180,6 +298,7 @@ function useBindings() {
             detach()
             subscription?.remove()
             attached.active = false
+            refs.sweep()
           }
         },
         style: selected,
@@ -190,6 +309,21 @@ function useBindings() {
 
 function selective(style: unknown): boolean {
   if (typeof style === 'function') return false
+  const shared =
+    typeof style === 'object' &&
+    style !== null &&
+    !Array.isArray(style) &&
+    Object.isFrozen(style)
+  const cached = shared ? patchable.get(style) : undefined
+  if (cached !== undefined) return cached
+  const result = writable(style)
+  if (shared) patchable.set(style, result)
+  return result
+}
+
+const patchable = new WeakMap<object, boolean>()
+
+function writable(style: unknown): boolean {
   const value = ReactNative.StyleSheet.flatten(
     style as ReactNative.StyleProp<ReactNative.ViewStyle>,
   )
@@ -213,7 +347,16 @@ function selective(style: unknown): boolean {
   )
 }
 
+// Compiled styles are frozen and shared by every view that selects them.
+const converted = new WeakMap<object, Record<string, unknown>>()
 function nativeProps(style: unknown): Record<string, unknown> {
+  const shared =
+    typeof style === 'object' &&
+    style !== null &&
+    !Array.isArray(style) &&
+    Object.isFrozen(style)
+  const cached = shared ? converted.get(style) : undefined
+  if (cached) return cached
   const flattened =
     ReactNative.StyleSheet.flatten(
       style as ReactNative.StyleProp<ReactNative.ViewStyle>,
@@ -223,9 +366,13 @@ function nativeProps(style: unknown): Record<string, unknown> {
     if (name === 'color' || name.endsWith('Color'))
       result[name] = ReactNative.processColor(value as ReactNative.ColorValue)
   }
+  if (shared) converted.set(style, result)
   return result
 }
 
+// Binding identifiers are unique per JavaScript runtime, like the native module.
+let bindings = 0
+
 function write(patches: readonly Store.Patch[]) {
   NativeZyzz!.update(patches)
 }

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

@@ -4,16 +4,14 @@ import { TurboModuleRegistry } from 'react-native'
 
 /** Codegen contract, consumed only by the native adapter. */
 export interface Spec extends TurboModule {
-  /** Links a mounted Fabric node and its rendered style. */
-  readonly attach: (
-    node: CodegenTypes.UnsafeObject,
-    props: CodegenTypes.UnsafeObject,
-  ) => number
   /** Releases a view binding. */
   readonly detach: (id: number) => void
   /** Reports live bindings and applied update batches. */
   readonly inspect: () => CodegenTypes.UnsafeObject
-  /** Applies one batch of changed native styles. */
+  /**
+   * Applies one batch of changed native styles. An update with `node` and
+   * `rendered` first binds that mounted Fabric node to its rendered style.
+   */
   readonly update: (updates: ReadonlyArray<CodegenTypes.UnsafeObject>) => void
 }
 

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

@@ -48,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',
@@ -60,6 +61,7 @@ export const properties = {
   fontWeight: 'weight',
   gap: 'length',
   height: 'size',
+  inset: 'boxOffset',
   justifyContent: [
     'center',
     'flex-end',
@@ -206,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' ? 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,

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

@@ -6,8 +6,12 @@ import * as React from 'react'
 export type Patch = {
   /** Runtime-local mounted view identifier. */
   readonly id: number
+  /** Mounted Fabric node, sent until the binding's first patch commits. */
+  readonly node?: object | undefined
   /** Processed native style properties. */
   readonly props: Record<string, unknown>
+  /** Processed style React rendered, sent with `node`. */
+  readonly rendered?: Record<string, unknown> | undefined
 }
 
 type Selection = {

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/Viewport.ts

@@ -1,4 +1,5 @@
 /** Connects the native device adapter to framework subscriptions. @module */
+import type * as NativeContext from '../../runtime/NativeContext.js'
 import type * as Media from '../../runtime/internal/NativeMedia.js'
 import * as React from 'react'
 
@@ -6,3 +7,9 @@ import * as React from 'react'
 export const context = React.createContext<Media.Viewport | undefined>(
   undefined,
 )
+
+/** Device appearance for `colorScheme: 'system'`, with the platform's appearance-following color when it has one. */
+export const appearance = React.createContext<{
+  readonly adaptive?: NativeContext.Context['adaptive']
+  readonly colorScheme: 'dark' | 'light'
+}>({ colorScheme: 'light' })