@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/LayoutGroup.tsx

@@ -0,0 +1,163 @@
+// REQ-API-036 / REQ-LAYOUT-021 — LayoutGroup, the layout-identity namespace (native entry).
+// Web forwards the pin's own LayoutGroup (full pin nodeGroup semantics). Native owns THIS rung's
+// contracted half: id namespacing of descendant layoutId registration + pin id/inherit prefix
+// vocabulary + lifetime-constant context. Pin-style projection-group dirty fan-out (nodeGroup
+// willUpdate batching) is DEFERRED — native layout siblings already reflow via Yoga + the CORE
+// layout-transition path without a projection-node membership graph (see Finding 2026-07-22 r1).
+// Owner identity is always `<LayoutGroup>` (REQ-API-014).
+
+import { createContext, useContext, useRef, type ReactNode } from 'react'
+import { describeValue } from '@unrulysystems/native-motion-core'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+import type { NativeSeverity } from './motionViewController'
+
+/** Pin vocabulary: boolean | "id" (default true). */
+export type LayoutGroupInherit = boolean | 'id'
+
+export interface LayoutGroupProps {
+  readonly children?: ReactNode
+  readonly id?: string | undefined
+  readonly inherit?: LayoutGroupInherit | undefined
+}
+
+/**
+ * Id-scope context only for this rung. The pin also carries a projection `group` (nodeGroup);
+ * native defers that half — sibling layout coordination rides the host layout path.
+ */
+export interface LayoutGroupContextValue {
+  readonly id: string | undefined
+}
+
+const LAYOUT_GROUP_OWNER = '<LayoutGroup>' as const
+
+const DEFAULT_CONTEXT: LayoutGroupContextValue = Object.freeze({
+  id: undefined,
+})
+
+export const LayoutGroupContext = createContext<LayoutGroupContextValue>(DEFAULT_CONTEXT)
+
+export function useLayoutGroup(): LayoutGroupContextValue {
+  return useContext(LayoutGroupContext)
+}
+
+/**
+ * Pin law retained as a pure classifier for tests and future group wiring: only `true` inherits
+ * the parent projection group. This rung does not mint or consume projection groups.
+ */
+export function shouldInheritGroup(inherit: LayoutGroupInherit): boolean {
+  return inherit === true
+}
+
+export function shouldInheritId(inherit: LayoutGroupInherit): boolean {
+  return inherit === true || inherit === 'id'
+}
+
+/**
+ * Resolve this group's public id scope against an upstream group id (pin LayoutGroup laws):
+ * when inherit admits id inheritance and an upstream id exists, prefix
+ * (`upstream + "-" + id` or bare upstream when the child omits id); otherwise the local id.
+ */
+export function resolveLayoutGroupId(
+  id: string | undefined,
+  inherit: LayoutGroupInherit,
+  upstreamId: string | undefined,
+): string | undefined {
+  if (shouldInheritId(inherit) && upstreamId !== undefined && upstreamId.length > 0) {
+    return id !== undefined && id.length > 0 ? `${upstreamId}-${id}` : upstreamId
+  }
+  return id
+}
+
+/**
+ * Pin motion host law: when a group id is in scope, registry identity is
+ * `groupId + "-" + layoutId`; otherwise the authored layoutId is used as-is.
+ */
+export function resolveNamespacedLayoutId(
+  groupId: string | undefined,
+  layoutId: string | undefined,
+): string | undefined {
+  if (layoutId === undefined) return undefined
+  if (groupId !== undefined && groupId.length > 0) return `${groupId}-${layoutId}`
+  return layoutId
+}
+
+export interface LayoutGroupGate {
+  readonly severity: NativeSeverity
+  readonly report: (error: Error) => void
+}
+
+const ACCEPTED_PROP_NAMES = new Set(['children', 'id', 'inherit'])
+
+function refuse(gate: LayoutGroupGate, message: string): void {
+  const error = new Error(message)
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+}
+
+export function gateLayoutGroupId(value: unknown, gate: LayoutGroupGate): string | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || value.length === 0) {
+    refuse(
+      gate,
+      `${LAYOUT_GROUP_OWNER}: invalid id = ${describeValue(value)} — expected a non-empty string ` +
+        '(REQ-API-036).',
+    )
+    return undefined
+  }
+  return value
+}
+
+export function gateLayoutGroupInherit(
+  value: unknown,
+  gate: LayoutGroupGate,
+): LayoutGroupInherit | undefined {
+  if (value === undefined) return undefined
+  if (value === true || value === false || value === 'id') return value
+  refuse(
+    gate,
+    `${LAYOUT_GROUP_OWNER}: invalid inherit = ${describeValue(value)} — expected ` +
+      `true | false | "id" (REQ-API-036).`,
+  )
+  return undefined
+}
+
+export function gateLayoutGroupUnknownProps(
+  rest: Readonly<Record<string, unknown>>,
+  gate: LayoutGroupGate,
+): void {
+  for (const key of Object.keys(rest)) {
+    if (rest[key] === undefined) continue
+    if (ACCEPTED_PROP_NAMES.has(key)) continue
+    refuse(
+      gate,
+      `${LAYOUT_GROUP_OWNER}: prop '${key}' is outside the contracted LayoutGroup surface ` +
+        '(REQ-API-036: id/inherit/children) — it fails loud rather than silently doing nothing.',
+    )
+  }
+}
+
+export function LayoutGroup({ children, id, inherit, ...rest }: LayoutGroupProps) {
+  const severity = ambientNativeSeverity()
+  const gate: LayoutGroupGate = { severity, report: consoleReporter }
+
+  gateLayoutGroupUnknownProps(rest as Record<string, unknown>, gate)
+  const gatedId = gateLayoutGroupId(id, gate)
+  // Default inherit is true (pin). Production refusal of a bad inherit falls back to default
+  // rather than inventing a third vocabulary.
+  const gatedInherit = gateLayoutGroupInherit(inherit, gate) ?? true
+
+  const parent = useContext(LayoutGroupContext)
+
+  // Lifetime-constant context (pin: useRef + null check — id scope never flips on re-render).
+  // inherit true and "id" both inherit the id prefix this rung; they differ only on the deferred
+  // projection-group half (web re-export still applies the full pin distinction).
+  const contextRef = useRef<LayoutGroupContextValue | null>(null)
+  if (contextRef.current === null) {
+    const resolvedId = resolveLayoutGroupId(gatedId, gatedInherit, parent.id)
+    contextRef.current = Object.freeze({ id: resolvedId })
+  }
+
+  return (
+    <LayoutGroupContext.Provider value={contextRef.current}>{children}</LayoutGroupContext.Provider>
+  )
+}

package/src/native/motion/MotionConfig.tsx

@@ -0,0 +1,400 @@
+// REQ-API-035 — MotionConfig, the tree-wide configuration provider (native entry).
+// Web forwards the pin's own MotionConfig; native implements the context so transition
+// defaults and reducedMotion reach every Motion element in the subtree through the shared
+// controller lane. Owner identity is always `<MotionConfig>` (REQ-API-014).
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react'
+import { AccessibilityInfo } from 'react-native'
+import {
+  captureTransition,
+  describeValue,
+  validateTransitionRefusal,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+import { normalizeTransitionEaseAlias } from '@unrulysystems/native-motion-core/internal-driver'
+import { ambientNativeSeverity, consoleReporter } from './severity'
+import type { NativeSeverity } from './motionViewController'
+
+export type ReducedMotionConfig = 'always' | 'never' | 'user'
+
+/** Config-lane transition: the pin's `inherit` merge flag is stripped before the property lane. */
+export type MotionConfigTransition = Transition & { readonly inherit?: boolean }
+
+export type TransformPagePoint = (point: { readonly x: number; readonly y: number }) => {
+  readonly x: number
+  readonly y: number
+}
+
+export interface MotionConfigContextValue {
+  readonly transition: Transition | undefined
+  readonly reducedMotion: ReducedMotionConfig
+  readonly isStatic: boolean
+  readonly skipAnimations: boolean
+  /** Resolved preference for the current config: always/user+platform → true; never → false. */
+  readonly shouldReduceMotion: boolean
+  /**
+   * R15 D3 (REQ-API-043): page-point correction at the recognizer-ingest boundary (pin
+   * transformPagePoint). Applied to hub start points and measure reads under transformed
+   * ancestors — never an accepted-but-inert prop (G-INV-8).
+   */
+  readonly transformPagePoint: TransformPagePoint | undefined
+}
+
+export interface MotionConfigProps {
+  readonly children?: ReactNode
+  readonly transition?: MotionConfigTransition | undefined
+  readonly reducedMotion?: ReducedMotionConfig | undefined
+  readonly nonce?: string | undefined
+  readonly isStatic?: boolean | undefined
+  /** R15 D3 (REQ-API-043): page-point correction (pin MotionConfig transformPagePoint). */
+  readonly transformPagePoint?: TransformPagePoint | undefined
+  readonly skipAnimations?: boolean | undefined
+}
+
+const MOTION_CONFIG_OWNER = '<MotionConfig>' as const
+
+const DEFAULT_CONTEXT: MotionConfigContextValue = Object.freeze({
+  transition: undefined,
+  reducedMotion: 'never',
+  isStatic: false,
+  skipAnimations: false,
+  shouldReduceMotion: false,
+  transformPagePoint: undefined,
+})
+
+export const MotionConfigContext = createContext<MotionConfigContextValue>(DEFAULT_CONTEXT)
+
+export function useMotionConfig(): MotionConfigContextValue {
+  return useContext(MotionConfigContext)
+}
+
+// Lifetime-constant value (the pin's useConstant law for isStatic — must not flip between renders
+// because it changes how many hooks Motion hosts fire).
+function useConstant<T>(init: () => T): T {
+  const ref = useRef<{ readonly value: T } | null>(null)
+  if (ref.current === null) ref.current = { value: init() }
+  return ref.current.value
+}
+
+/**
+ * Nested config transition resolution (pin `resolveTransition` from motion-dom@12.42.2):
+ * when the child transition carries `inherit: true`, merge parent then child overrides;
+ * otherwise the child transition replaces the parent (or is undefined).
+ * The `inherit` flag is stripped before the value reaches the property lane.
+ */
+/** Strip only `inherit`; materialize every other own key once (getters fire here, G-INV-8). */
+function stripInheritFlag(raw: MotionConfigTransition): Transition {
+  const source = raw as Record<PropertyKey, unknown>
+  const out: Record<PropertyKey, unknown> = Object.create(null)
+  let hasLaneKey = false
+  for (const key of Reflect.ownKeys(raw)) {
+    if (key === 'inherit') continue
+    hasLaneKey = true
+    // One read of the own property (accessor or data) — never copy descriptor.value of a getter.
+    const value = source[key]
+    Object.defineProperty(out, key, {
+      value,
+      enumerable: Object.getOwnPropertyDescriptor(raw, key)?.enumerable === true,
+      configurable: true,
+      writable: true,
+    })
+  }
+  return (hasLaneKey ? out : Object.freeze({})) as Transition
+}
+
+export function resolveConfigTransition(
+  transition: MotionConfigTransition | undefined,
+  parentTransition: Transition | undefined,
+): Transition | undefined {
+  if (transition === undefined) return parentTransition
+  const inherit = transition.inherit === true
+  const rest = stripInheritFlag(transition)
+  // Family-2: canonicalize easings→ease before merge so parent ease cannot clobber child easings
+  // (and dual-key inheritance never leaves the pin-facing shape as easings-only).
+  const parent =
+    parentTransition === undefined ? undefined : normalizeTransitionEaseAlias(parentTransition)
+  const childKeys = Reflect.ownKeys(rest as object)
+  const child =
+    childKeys.length === 0 ? undefined : normalizeTransitionEaseAlias(rest as Transition)
+  if (inherit && parent !== undefined) {
+    if (child === undefined) return parent
+    // Merge own keys only (null-prototype) — no Object.prototype pollution.
+    const merged: Record<PropertyKey, unknown> = Object.create(null)
+    for (const key of Reflect.ownKeys(parent as object)) {
+      const d = Object.getOwnPropertyDescriptor(parent as object, key)
+      if (d !== undefined)
+        Object.defineProperty(merged, key, { ...d, configurable: true, writable: true })
+    }
+    for (const key of Reflect.ownKeys(child as object)) {
+      const d = Object.getOwnPropertyDescriptor(child as object, key)
+      if (d !== undefined)
+        Object.defineProperty(merged, key, { ...d, configurable: true, writable: true })
+    }
+    return Object.freeze(merged) as Transition
+  }
+  // Bare `{ inherit: true }` with no parent / no lane keys → parent or undefined.
+  if (child === undefined) {
+    return inherit ? parent : undefined
+  }
+  return child
+}
+
+const REDUCED_MOTION_VALUES = new Set<string>(['always', 'never', 'user'])
+
+const ACCEPTED_PROP_NAMES = new Set([
+  'children',
+  'transition',
+  'reducedMotion',
+  'nonce',
+  'isStatic',
+  'skipAnimations',
+  'transformPagePoint',
+])
+
+export interface MotionConfigGate {
+  readonly severity: NativeSeverity
+  readonly report: (error: Error) => void
+}
+
+function refuse(gate: MotionConfigGate, message: string): void {
+  const error = new Error(message)
+  if (gate.severity === 'development') throw error
+  gate.report(error)
+}
+
+/** Capture + validate a config transition; production refuses the prop (returns undefined). */
+export function gateMotionConfigTransition(
+  value: unknown,
+  gate: MotionConfigGate,
+): Transition | undefined {
+  if (value === undefined) return undefined
+  const proto =
+    typeof value === 'object' && value !== null ? Object.getPrototypeOf(value) : undefined
+  if (
+    typeof value !== 'object' ||
+    value === null ||
+    Array.isArray(value) ||
+    (proto !== Object.prototype && proto !== null)
+  ) {
+    refuse(
+      gate,
+      `${MOTION_CONFIG_OWNER}: invalid transition = ${describeValue(value)} — a transition must ` +
+        'be a plain object of transition options (REQ-API-035).',
+    )
+    return undefined
+  }
+  // Strip only inherit via Reflect.ownKeys — never object-rest / Object.keys (non-enumerable
+  // easings and invalid own keys must still reach captureTransition + validate, G-INV-8).
+  const raw = value as MotionConfigTransition
+  // One-read capture of inherit (373eu6): validation and merge must observe the same truth —
+  // a stateful accessor cannot bypass the boolean check by returning different values.
+  const hasInherit = Object.hasOwn(raw, 'inherit')
+  const inheritSnapshot: unknown = hasInherit ? raw.inherit : undefined
+  // REQ-API-035(e) / xxytww: inherit is a boolean nesting switch — non-boolean fails loud.
+  if (hasInherit && inheritSnapshot !== undefined && typeof inheritSnapshot !== 'boolean') {
+    refuse(
+      gate,
+      `${MOTION_CONFIG_OWNER}: invalid inherit = ${describeValue(inheritSnapshot)} — expected a boolean ` +
+        '(REQ-API-035).',
+    )
+    if (gate.severity !== 'development') return undefined
+  }
+  const laneOptions = stripInheritFlag(raw)
+  const snapshot =
+    Reflect.ownKeys(laneOptions as object).length === 0
+      ? (Object.freeze({}) as Transition)
+      : captureTransition(laneOptions as Transition)
+  const refusal = validateTransitionRefusal(snapshot, { componentId: MOTION_CONFIG_OWNER })
+  if (refusal !== null) {
+    if (gate.severity === 'development') throw refusal
+    gate.report(refusal)
+    return undefined
+  }
+  // Family-2: canonicalize easings→ease on the accepted snapshot (deep-captured by captureTransition).
+  const normalized = normalizeTransitionEaseAlias(snapshot)
+  // Preserve inherit on the resolved shape only for nested merge — caller uses resolveConfigTransition.
+  if (inheritSnapshot === true) {
+    const withInherit: Record<PropertyKey, unknown> = Object.create(null)
+    for (const key of Reflect.ownKeys(normalized as object)) {
+      const d = Object.getOwnPropertyDescriptor(normalized as object, key)
+      if (d !== undefined)
+        Object.defineProperty(withInherit, key, { ...d, configurable: true, writable: true })
+    }
+    Object.defineProperty(withInherit, 'inherit', {
+      value: true,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+    return Object.freeze(withInherit) as MotionConfigTransition
+  }
+  return normalized
+}
+
+export function gateMotionConfigReducedMotion(
+  value: unknown,
+  gate: MotionConfigGate,
+): ReducedMotionConfig | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string' || !REDUCED_MOTION_VALUES.has(value)) {
+    refuse(
+      gate,
+      `${MOTION_CONFIG_OWNER}: invalid reducedMotion = ${describeValue(value)} — expected ` +
+        `"always" | "never" | "user" (REQ-API-035).`,
+    )
+    return undefined
+  }
+  return value as ReducedMotionConfig
+}
+
+export function gateMotionConfigBoolean(
+  propName: string,
+  value: unknown,
+  gate: MotionConfigGate,
+): boolean | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'boolean') {
+    refuse(
+      gate,
+      `${MOTION_CONFIG_OWNER}: invalid ${propName} = ${describeValue(value)} — expected a boolean ` +
+        '(REQ-API-035).',
+    )
+    return undefined
+  }
+  return value
+}
+
+/** Native refuses nonce (DOM CSP — WEB-ONLY-BY-LAW). */
+export function gateMotionConfigNonce(value: unknown, gate: MotionConfigGate): void {
+  if (value === undefined) return
+  refuse(
+    gate,
+    `${MOTION_CONFIG_OWNER}: nonce is WEB-ONLY-BY-LAW (a DOM CSP attribute with no native analog) ` +
+      '— it fails loud on the native entry (REQ-API-035).',
+  )
+}
+
+export function gateMotionConfigUnknownProps(
+  rest: Readonly<Record<string, unknown>>,
+  gate: MotionConfigGate,
+): void {
+  for (const key of Object.keys(rest)) {
+    if (rest[key] === undefined) continue
+    if (ACCEPTED_PROP_NAMES.has(key)) continue
+    refuse(
+      gate,
+      `${MOTION_CONFIG_OWNER}: prop '${key}' is outside the contracted MotionConfig surface ` +
+        '(REQ-API-035: transition/reducedMotion/isStatic/skipAnimations/nonce/children) — ' +
+        'it fails loud rather than silently doing nothing.',
+    )
+  }
+}
+
+function gateTransformPagePoint(
+  value: unknown,
+  gate: MotionConfigGate,
+): TransformPagePoint | undefined {
+  if (value === undefined) return undefined
+  if (typeof value !== 'function') {
+    refuse(
+      gate,
+      `${MOTION_CONFIG_OWNER}: invalid transformPagePoint = ${describeValue(value)} — expected a ` +
+        'function (point) => point (REQ-API-043).',
+    )
+    return undefined
+  }
+  return value as TransformPagePoint
+}
+
+export function MotionConfig({
+  children,
+  transition,
+  reducedMotion,
+  nonce,
+  isStatic,
+  skipAnimations,
+  transformPagePoint,
+  ...rest
+}: MotionConfigProps) {
+  const severity = ambientNativeSeverity()
+  const gate: MotionConfigGate = { severity, report: consoleReporter }
+
+  gateMotionConfigUnknownProps(rest as Record<string, unknown>, gate)
+  gateMotionConfigNonce(nonce, gate)
+
+  const parent = useContext(MotionConfigContext)
+  const gatedTransition = gateMotionConfigTransition(transition, gate)
+  const resolvedTransition = resolveConfigTransition(
+    gatedTransition as MotionConfigTransition | undefined,
+    parent.transition,
+  )
+  const gatedReduced = gateMotionConfigReducedMotion(reducedMotion, gate) ?? parent.reducedMotion
+  const gatedIsStaticRaw = gateMotionConfigBoolean('isStatic', isStatic, gate)
+  // Lifetime-constant isStatic (pin useConstant law).
+  const frozenIsStatic = useConstant(() =>
+    gatedIsStaticRaw !== undefined ? gatedIsStaticRaw : parent.isStatic,
+  )
+  const gatedSkip = gateMotionConfigBoolean('skipAnimations', skipAnimations, gate)
+  const resolvedSkip = gatedSkip !== undefined ? gatedSkip : parent.skipAnimations
+  const gatedTransform =
+    gateTransformPagePoint(transformPagePoint, gate) ?? parent.transformPagePoint
+
+  // Platform reduced-motion preference — only consulted for "user".
+  const [userPrefersReduce, setUserPrefersReduce] = useState(false)
+  useEffect(() => {
+    if (gatedReduced !== 'user') {
+      setUserPrefersReduce(false)
+      return
+    }
+    let cancelled = false
+    void AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+      if (!cancelled) setUserPrefersReduce(enabled === true)
+    })
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      (enabled: boolean) => {
+        if (!cancelled) setUserPrefersReduce(enabled === true)
+      },
+    )
+    return () => {
+      cancelled = true
+      // RN subscription shape: { remove() } on modern; function on older.
+      if (subscription !== undefined && typeof subscription.remove === 'function') {
+        subscription.remove()
+      }
+    }
+  }, [gatedReduced])
+
+  const shouldReduceMotion =
+    gatedReduced === 'always' || (gatedReduced === 'user' && userPrefersReduce)
+
+  const context = useMemo<MotionConfigContextValue>(
+    () =>
+      Object.freeze({
+        transition: resolvedTransition,
+        reducedMotion: gatedReduced,
+        isStatic: frozenIsStatic,
+        skipAnimations: resolvedSkip,
+        shouldReduceMotion,
+        transformPagePoint: gatedTransform,
+      }),
+    [
+      resolvedTransition,
+      gatedReduced,
+      frozenIsStatic,
+      resolvedSkip,
+      shouldReduceMotion,
+      gatedTransform,
+    ],
+  )
+
+  return <MotionConfigContext.Provider value={context}>{children}</MotionConfigContext.Provider>
+}