@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/component/types.js

@@ -0,0 +1,111 @@
+// SPEC-COMPONENT §2 — the end-state public API types (REQ-API-006/015). This is the "Motion's API on top"
+// authoring surface: the declarative `Target` an author writes for `initial`/`animate`/`exit`, and the
+// `Transition` config. The types admit ONLY the universal-subset properties (REQ-SUBSET-011) with their
+// value shapes — there is NO permissive index signature and NO `any` escape hatch, so an unknown key or a
+// wrong-shaped value is a compile error where statically possible (REQ-API-015). Runtime `validateTarget`
+// (REQ-API-013) is the fail-closed backstop for what the type cannot catch (units, ranges, untyped
+// callers). Host-agnostic (REQ-CORE-003): the public `Transition` uses Motion's SECONDS unit — the internal
+// millisecond SPRING/TIMING resolver config is a DISTINCT type, bridged at an explicit boundary
+// (`./transition`), never leaked into this public surface. Imports no host package.
+// The universal target-property keys, grouped by the value shape an author may write. They mirror the
+// SUBSET registry's universal, non-gesture properties (REQ-SUBSET-011); `types.test.ts` asserts this list
+// is EXACTLY the registry's, so the compile-time `Target` type and the runtime membership authority can
+// never drift. Written as literal `const` arrays because the registry stores keys widened to `string` and
+// cannot furnish a literal key union — this is the single literal source the `Target` type is built from.
+const LENGTH_KEYS = [
+    'x',
+    'y',
+    'perspective',
+    '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',
+];
+const UNITLESS_KEYS = ['scale', 'scaleX', 'scaleY', 'opacity'];
+const ANGLE_KEYS = ['rotate', 'rotateX', 'rotateY', 'skewX', 'skewY'];
+const COLOR_KEYS = ['backgroundColor', 'color', 'borderColor'];
+const DISCRETE_KEYS = ['display', 'visibility'];
+// Runtime enumeration of every universal target-property key — the drift guard's compile-time↔runtime
+// bridge, and the key set `validateTarget`/`resolveTarget` iterate. Deep-immutable (readonly, `as const`).
+export const TARGET_PROPERTY_KEYS = [
+    ...LENGTH_KEYS,
+    ...UNITLESS_KEYS,
+    ...ANGLE_KEYS,
+    ...COLOR_KEYS,
+    ...DISCRETE_KEYS,
+];
+// This data is the runtime-readable counterpart of Transition below. Native's public-surface
+// verifier consumes it directly, so parity tooling cannot invent a second transition vocabulary.
+export const TRANSITION_OPTION_KEYS = [
+    'type',
+    'duration',
+    'delay',
+    'ease',
+    // Family-2 shipping slice: Motion authors sometimes spell the per-segment list `easings`
+    // (catalog Animation-keyframes). Runtime treats it as an alias of `ease` (same shape law).
+    'easings',
+    // T20 (REQ-API-052): catalog spelling `easing` (Benchmark-cold-start-motion). Same exclusive
+    // alias law as `easings`; converters normalize to `ease`.
+    'easing',
+    // R8 M2-B (REQ-API-033 law d): custom keyframe OFFSETS for a keyframe-array target. Keyframe-only —
+    // the layout lane never interpolates a keyframe array, so `times` is a PROPERTY-lane option, absent
+    // from the layout transition domain (shippedSurface.ts).
+    'times',
+    'stiffness',
+    'damping',
+    'mass',
+    'bounce',
+    'visualDuration',
+    'velocity',
+    // U7c (REQ-SPRING-014): the authored settle thresholds — spring physics options routed into
+    // the solver's settle condition, forwarded untransformed (the velocity precedent).
+    'restDelta',
+    'restSpeed',
+    // T18-a (REQ-API-049): the repeat family. PROPERTY-lane options — the layout/layoutId lanes
+    // refuse them rather than fold a snapshot delta (packet L4), so they are absent from the layout
+    // transition domain (shippedSurface.ts).
+    'repeat',
+    'repeatType',
+    'repeatDelay',
+    // T21 (REQ-API-053): the orchestration family — TREE-lane options consumed at the controlling
+    // node's start scheduling, never by a driver (the converters strip them, per-value map entries
+    // refuse them, and the layout lanes never list them).
+    'when',
+    'delayChildren',
+    'staggerChildren',
+    'staggerDirection',
+    // U8 (REQ-API-059): parametric path factory (`arc()`). PROPERTY-lane / element bag only;
+    // nested map entries and layout bags refuse (F3).
+    'path',
+];
+// T21 (REQ-API-053): the tree-lane subset of the vocabulary, single-sourced so the validator's
+// map-entry refusal, the native controller's driver-strip, and the web shim's pass-through all
+// branch on the same set.
+export const ORCHESTRATION_OPTION_KEYS = [
+    'when',
+    'delayChildren',
+    'staggerChildren',
+    'staggerDirection',
+];