@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/lengthLayoutContext.tsx

@@ -0,0 +1,100 @@
+// REQ-VALUETYPE-013 — host layout context for measure-resolved length targets.
+// Parent geometry is opt-in via MotionLengthLayoutProvider (gallery stages, sheet hosts).
+// Viewport defaults from Dimensions; auto sizes come from the element's own onLayout.
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react'
+import type { LengthLayoutContext } from '@unrulysystems/native-motion-core'
+
+const LengthLayoutReactContext = createContext<LengthLayoutContext | null>(null)
+
+export function useLengthLayoutParentContext(): LengthLayoutContext | null {
+  return useContext(LengthLayoutReactContext)
+}
+
+export interface MotionLengthLayoutProviderProps {
+  readonly value: LengthLayoutContext
+  readonly children: ReactNode
+}
+
+/** Provide parent/viewport geometry for descendant measure-resolved %/calc targets. */
+export function MotionLengthLayoutProvider({
+  value,
+  children,
+}: MotionLengthLayoutProviderProps): ReactNode {
+  const parent = useContext(LengthLayoutReactContext)
+  const merged = useMemo(
+    (): LengthLayoutContext => ({
+      ...parent,
+      ...value,
+    }),
+    [parent, value],
+  )
+  return (
+    <LengthLayoutReactContext.Provider value={merged}>{children}</LengthLayoutReactContext.Provider>
+  )
+}
+
+/**
+ * The strict lazy-RN-load classifier (review c513f5cf4a15): only a positively-identified
+ * missing *requested* 'react-native' module is an absence. A SyntaxError or a transitive
+ * MODULE_NOT_FOUND is a broken dependency/module initialization and must stay loud — never be
+ * laundered into an absent optional facility.
+ */
+function isMissingModuleAbsence(error: unknown): boolean {
+  const code =
+    error !== null && typeof error === 'object' && 'code' in error
+      ? String((error as { code?: unknown }).code)
+      : ''
+  const message = error instanceof Error ? error.message : String(error)
+  return code === 'MODULE_NOT_FOUND' && /Cannot find module ['"]react-native['"]/i.test(message)
+}
+
+/** Lazy require of react-native for the optional host facilities; absence is classified above. */
+function requireReactNativeOptional<T>(): { Dimensions?: T | undefined } | undefined {
+  let Dimensions: T | undefined
+  // The destructure lives INSIDE the try: a getter-backed host module faulting on export ACCESS
+  // is classified by the same law as a module-evaluation fault.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports -- lazy host touch
+  try {
+    ;({ Dimensions } = require('react-native') as { Dimensions?: T })
+  } catch (error) {
+    if (isMissingModuleAbsence(error)) return undefined
+    throw error
+  }
+  if (Dimensions === undefined) return undefined
+  return { Dimensions }
+}
+
+/**
+ * Viewport size for vw/vh measure-resolve. Lazy require of react-native so vitest RN mocks
+ * that omit Dimensions do not crash module evaluation. An absent optional facility → `{}`.
+ * A successful require whose Dimensions.get throws propagates (host dependency fault).
+ */
+export function defaultViewportContext(): LengthLayoutContext {
+  const reactNative = requireReactNativeOptional<{
+    get: (key: string) => { width: number; height: number }
+  }>()
+  const Dimensions = reactNative?.Dimensions
+  if (Dimensions === undefined || typeof Dimensions.get !== 'function') return {}
+  const { width, height } = Dimensions.get('window')
+  if (!Number.isFinite(width) || !Number.isFinite(height)) return {}
+  return { viewportWidth: width, viewportHeight: height }
+}
+
+/**
+ * Subscribe to viewport geometry changes (rotation / window resize). Resting vw/vh values
+ * re-measure against the fresh viewport on this edge (review ae0a42832d85). An absent optional
+ * facility (no Dimensions, or no change event on the host) is a no-op unsubscribe — but the
+ * SAME strict classifier as defaultViewportContext (review 8e777bfcf811): a parse/init or
+ * transitive load fault propagates, never masquerades as absence.
+ */
+export function subscribeViewportContextChange(onChange: () => void): () => void {
+  const reactNative = requireReactNativeOptional<{
+    addEventListener?: (
+      event: string,
+      listener: (dims: { window: unknown; screen: unknown }) => void,
+    ) => { remove: () => void }
+  }>()
+  const subscription = reactNative?.Dimensions?.addEventListener?.('change', onChange)
+  return () => subscription?.remove()
+}

package/src/native/motion/lengthLayoutHost.ts

@@ -0,0 +1,44 @@
+// REQ-VALUETYPE-013 — host onLayout → length-context auto measures + deferred flush.
+
+import type { LengthLayoutContext } from '@unrulysystems/native-motion-core'
+
+export interface HostLayoutSize {
+  readonly width: number
+  readonly height: number
+}
+
+export interface HostLayoutGate {
+  readonly severity: 'development' | 'production'
+  readonly report: (error: Error) => void
+}
+
+/**
+ * Seed autoWidth/autoHeight from the host's content layout and flush deferred measure-resolved
+ * animate targets. Returns whether a deferred flush commanded. No-op when layout is absent.
+ */
+export function seedLengthLayoutFromHostLayout(
+  layout: HostLayoutSize | undefined,
+  box: { current: LengthLayoutContext },
+  flushDeferredLengthMeasures: () => boolean,
+  gate?: HostLayoutGate,
+): boolean {
+  if (layout === undefined) return false
+  if (!Number.isFinite(layout.width) || !Number.isFinite(layout.height)) {
+    const error = new Error(
+      `Motion host onLayout returned a non-finite size (${layout.width}, ${layout.height}); ` +
+        'layout measurements must be finite before measure-resolved lengths can flush (REQ-VALUETYPE-013).',
+    )
+    // The optional gate keeps the standalone host adapter backward-compatible for non-runtime
+    // callers; MotionView always supplies it, so malformed native layout never becomes a silent
+    // pending state in the public runtime.
+    if (gate?.severity === 'development') throw error
+    gate?.report(error)
+    return false
+  }
+  box.current = {
+    ...box.current,
+    autoWidth: layout.width,
+    autoHeight: layout.height,
+  }
+  return flushDeferredLengthMeasures()
+}

package/src/native/motion/mappedKeys.ts

@@ -0,0 +1,184 @@
+// The driver-visible target keys are data so node-side parity tooling can classify the native
+// surface without importing a React Native entry point. MotionView remains their runtime owner.
+// Do not export a Set: Object.freeze(new Set()) still permits Set.prototype.add(), which would make
+// classification depend on import order. The mutable collection stays module-private.
+// R4 (REQ-DRIVER-027, the zero-delta law): this set equals the registry's full shipped value-key
+// set — every transform, opacity, color, layout-prop, and discrete key. The list stays literal — the
+// registry cross-check test (mappedKeys.test.ts) is what binds it, and node-side parity tooling
+// must not drag core's registry module into every consumer of this data export.
+// The three mapped classes as LITERAL const arrays (r15 d32a7c1e94b6): the public
+// MotionViewStyle type derives its bindable-key unions from the numeric-style and color
+// classes (plus the U5-W3 TRANSFORM_STRING_KEY_NAME literal below for `transform`), so the
+// binding surface the TYPES admit is the surface the runtime accepts by
+// construction.
+export const TRANSFORM_KEY_NAMES = [
+  // Transform class (composeTransform.ts owns the canonical composition order; the order data
+  // itself lives in transformOrder.ts, RN-import-free).
+  'x',
+  'y',
+  'scale',
+  'scaleX',
+  'scaleY',
+  'rotate',
+  'rotateX',
+  'rotateY',
+  'skewX',
+  'skewY',
+  'perspective',
+] as const
+
+export const NUMERIC_STYLE_KEY_NAMES = [
+  // Opacity.
+  'opacity',
+  // Layout-prop class: numeric style commits on the generic lane.
+  'width',
+  'height',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'borderRadius',
+  'borderTopLeftRadius',
+  'borderTopRightRadius',
+  'borderBottomLeftRadius',
+  'borderBottomRightRadius',
+  'borderWidth',
+  'borderTopWidth',
+  'borderRightWidth',
+  'borderBottomWidth',
+  'borderLeftWidth',
+  'margin',
+  'marginTop',
+  'marginRight',
+  'marginBottom',
+  'marginLeft',
+  'padding',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+] as const
+
+export const COLOR_KEY_NAMES = [
+  // Color class: the [0,100] progress lane with projected rgba endpoints.
+  'backgroundColor',
+  'color',
+  'borderColor',
+] as const
+
+export const DISCRETE_KEY_NAMES = [
+  // Discrete class (T23 B): the color-lane pattern with a projected keyword (a step or a
+  // constant, per REQ-VALUETYPE-015's two paths). `display`
+  // commits the RN style field; `visibility` commits as the ratified composed override
+  // (charter Decision 15: hidden = effective opacity 0 + pointerEvents 'none').
+  'display',
+  'visibility',
+] as const
+
+/** The numeric style keys a public MotionValue<number> may BIND to (mapped, non-rgba). */
+export type BindableStyleKeyName = (typeof NUMERIC_STYLE_KEY_NAMES)[number]
+
+/**
+ * The rgba-class keys a public MotionValue<string> may BIND to (U5, REQ-API-026). Derived from
+ * the literal class for the same reason `BindableStyleKeyName` is: a hand-written union is a
+ * second authority that drifts silently.
+ */
+export type BindableColorKeyName = (typeof COLOR_KEY_NAMES)[number]
+
+// U5 W3 (REQ-API-026, packet contract 2): the `transform` style key binds a
+// MotionValue<string> parsed per set() into the driver-mapped transform components. `transform`
+// itself is NOT a driver-mapped value key — the parsed components are — so it stays OUT of the
+// mappedKeys set below; the literal const is the single authority the public MotionViewStyle
+// union and the runtime split gate both derive from.
+export const TRANSFORM_STRING_KEY_NAME = 'transform' as const
+
+/** The style key a public MotionValue<string> of transform functions may BIND to (U5 W3). */
+export type BindableTransformStringKeyName = typeof TRANSFORM_STRING_KEY_NAME
+
+/**
+ * The Motion transform shorthands as a type — the public `MotionViewStyle` both SUBTRACTS this set
+ * from its RN-derived members and re-declares it. It derives from the array above for the same
+ * reason `BindableStyleKeyName` does: a hand-written union is a second authority that drifts
+ * silently, and this one had already been transcribed name-for-name (fix-up review).
+ */
+export type TransformShorthandName = (typeof TRANSFORM_KEY_NAMES)[number]
+
+const mappedKeys = new Set<string>([
+  ...TRANSFORM_KEY_NAMES,
+  ...NUMERIC_STYLE_KEY_NAMES,
+  ...COLOR_KEY_NAMES,
+  ...DISCRETE_KEY_NAMES,
+])
+
+// The full name list as immutable data (a frozen array, not a Set — Set.prototype.add survives
+// Object.freeze): the REQ-DRIVER-027 zero-delta test needs BOTH directions enumerable, so a
+// mapped typo or an extra unknown key fails set equality instead of hiding behind a
+// membership-only probe (review r2 major e5226f7bf313).
+export const MAPPED_KEY_NAMES: readonly string[] = Object.freeze([...mappedKeys])
+
+export const MAPPED_KEYS = Object.freeze({
+  size: mappedKeys.size,
+  has(key: string): boolean {
+    return mappedKeys.has(key)
+  },
+})
+
+// The SHIPPED Motion prop surface as literal data (R7 M4): the classifier derives
+// "shipped => no blocker" from THIS export — the value-channel precedent (derived from
+// the shipped surface, never assumed). The runtime owner is shippedSurface.ts's
+// VIEW_MOTION_PROP_NAMES; the cross-check test (mappedKeys.test.ts) binds the literal to
+// it, keeping node-side parity tooling RN-import-free.
+export const SHIPPED_MOTION_PROP_KEYS = [
+  'initial',
+  'animate',
+  'exit',
+  'transition',
+  'style',
+  'layout',
+  'layoutId',
+  // R11 M2 (REQ-LAYOUT-022 / REQ-API-038): scroll-offset measurement root.
+  'layoutScroll',
+  'onAnimationComplete',
+  'onLayoutAnimationComplete',
+  // U7e (REQ-LAYOUT-001 lineage): the layout-flight start callback.
+  'onLayoutAnimationStart',
+  'drag',
+  'dragConstraints',
+  'dragElastic',
+  'dragSnapPoints',
+  'dragPropagation',
+  'dragControls',
+  'dragListener',
+  // R15 D4 (REQ-API-044): direction lock.
+  'dragDirectionLock',
+  'onDirectionLock',
+  // R15 D5 (REQ-API-045 / REQ-API-046): release physics + external drag values.
+  'dragMomentum',
+  'dragTransition',
+  'dragSnapToOrigin',
+  '_dragX',
+  '_dragY',
+  'onPanSessionStart',
+  'onPanStart',
+  'onPan',
+  'onPanEnd',
+  'onMeasureDragConstraints',
+  'onDragStart',
+  'onDrag',
+  'onDragEnd',
+  'onTap',
+  'onTapStart',
+  'onTapCancel',
+  // U7d (REQ-API-030 global form): the root-observing press scope flag.
+  'globalTapTarget',
+  'whileTap',
+  'whileDrag',
+  'variants',
+  'inherit',
+  // T17 (specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md): branded-worklet transform template.
+  'transformTemplate',
+  // T23 C (specs/T23-MIX-DISCRETE-BUILD-PACKET.md): per-frame latest-values callback.
+  'onUpdate',
+  // T24 B1: the dynamic-variants custom payload.
+  'custom',
+] as const