@wardic/solid 0.0.0-stage → 1.0.0-rc.1

package/src/index.ts

@@ -0,0 +1,334 @@
+/**
+ * @wardic/solid — the Solid framework binding: `WardicProvider` and `WardicConfig`; `createWard`, a **Ward** to
+ * spread onto an element, with variant orchestration through `ward.Provider`; `wardic.*`,
+ * `wardic.create()` and the `use:wardic` directive; `<AnimatePresence>`, `<LayoutGroup>` and
+ * `<Reorder>`; and the low-level `createX` primitives (ADR-0008, ADR-0042). Built directly on
+ * `effect`'s in-core reactivity (`effect/reactivity`) — there is no `@effect-atom/atom-solid`
+ * dependency.
+ */
+/**
+ * The version of `@wardic/solid` this is.
+ *
+ * @see https://wardic.dev/reference/solid/utilities/version
+ */
+export const VERSION = "0.1.0-alpha.0"
+
+/**
+ * `WardicProvider` (one Effect runtime + `AtomRegistry` per ADR-0006), the
+ * `useWardicRuntime` accessor, and the scoped-fiber runner (`runScoped` /
+ * `useWardicFiber`) that interrupts forked fibers on consumer unmount.
+ *
+ * NOTE: `provider.tsx` ships Solid JSX, so consumers must add `@wardic/solid`
+ * (and any other workspace package shipping Solid JSX) to `ssr.noExternal` in
+ * their Vite config so the Solid plugin transforms it — already pre-wired in
+ * examples/solid-start-basic.
+ */
+export {
+  createInstantLayoutTransition,
+  createInstantTransition,
+  createResetProjection,
+  runScoped,
+  useAnimateLayout,
+  useWardicFiber,
+  useWardicGate,
+  useWardicRuntime,
+  WardicProvider,
+  LazyWardic,
+} from "./provider.tsx"
+
+/**
+ * **Features** (#511, ADR-0067): what a Slim element (`w.*`) has only when it's chosen, on a
+ * `WardicProvider` or a `LazyWardic` (`features={[colors]}`), each its own import so an app ships only
+ * those it uses; a Complete element (`wardic.*`) has every one. `colors`: every CSS colour space beyond
+ * a hex, `rgb()`, `hsl()` and the colour names. `layout`: layout animations, the props `layout`,
+ * `layoutId`, `layoutScroll` and `layoutRoot` (`LayoutGroup` and `Reorder` bring it themselves).
+ */
+export type { Feature, FeatureLoad, Features, FeaturesProp } from "./feature.ts"
+export { colors } from "./features/colors.ts"
+export { layout } from "./features/layout.ts"
+/**
+ * The gestures (#511, ADR-0067 decision 3), a Feature each: `hover`, `press` (its Keyboard presses
+ * included), `focus`, `inView`, `pan` and `drag` (`dragControls` and the release's inertia included).
+ * Every one but `inView` stands on the gestures' input: the Environment's when it gives one, else the
+ * DOM's. Motion's bundles: `domAnimation` (`hover`, `press`, `focus`, `inView`) and `domMax` (every
+ * Feature).
+ */
+export { drag } from "./features/drag.ts"
+export { focus } from "./features/focus.ts"
+export { hover } from "./features/hover.ts"
+export { inView } from "./features/in-view.ts"
+export { pan } from "./features/pan.ts"
+export { press } from "./features/press.ts"
+export { domAnimation } from "./features/dom-animation.ts"
+export { domMax } from "./features/dom-max.ts"
+// The Instant change and the Projection reset (#443): Motion's `useInstantTransition` and kin.
+export type { InstantTransition } from "./instant.ts"
+// `WardicConfig`'s `transformPagePoint` helpers (#443, Motion's): a drag inside a transformed parent, or an SVG's viewBox.
+export { correctParentTransform, transformViewBoxPoint } from "./page-point.ts"
+export type { AnimateLayout, WardicEnv, WardicRuntime, WardicServices } from "./runtime.ts"
+export type { AnimateLayoutOptions } from "@wardic/dom/ProjectionSystem"
+
+/**
+ * `<WardicConfig>` (#434, Motion's `MotionConfig`): settings for the Wardic elements below it, its
+ * **Config transition** their default `transition`. It nests anywhere under a `WardicProvider`.
+ */
+export { WardicConfig, type WardicConfigProps } from "./wardic-config.tsx"
+
+/**
+ * The provider's **Flush gate** (ADR-0006): where each element's animated values are written,
+ * drawn onto the elements together once a frame, at the end of its animation tick (ADR-0034).
+ * It's `@wardic/dom`'s, built by the provider with Solid's `batch` (ADR-0031), and
+ * `useWardicGate` returns it; the types are re-exported here.
+ */
+export type { Shape as FlushGate, Sink as FlushSink } from "@wardic/dom/FlushGate"
+
+/**
+ * Reactive bridges (ADR-0006): `streamToSignal` (core `Stream` -> Solid signal,
+ * scoped fiber) and `fromAtom` (Effect `Atom` -> Solid signal via the runtime's
+ * `AtomRegistry`).
+ */
+export { fromAtom, streamToSignal } from "./bridge.ts"
+export type { WardicDragInfo, WardicPoint, WardicPointInfo, WardicPressEvent, WardicPressInfo, WardicPressInput } from "./gesture-info.ts"
+export type { WardicBoundingBox, WardicDragConstraints, WardicMeasureDragConstraints } from "./drag-constraints.ts"
+// Drag controls (#431, Motion's `useDragControls`): a drag started from a handle or a track.
+export { createDragControls, type WardicDragControls, type WardicDragControlsOptions } from "./drag-controls.ts"
+// Imperative animation (#433, Motion's `useAnimate`): an Animation scope, its `animate` and its Playback controls;
+// a sequence of Segments (Motion's), on the same controls.
+export { createAnimate } from "./create-animate.ts"
+export type {
+  WardicAnimate,
+  WardicAnimateOptions,
+  WardicAnimationScope,
+  WardicAnimationSequence,
+  WardicAnimationSubject,
+  WardicElementSegment,
+  WardicFunctionSegment,
+  WardicPlaybackControls,
+  WardicPlayState,
+  WardicSegment,
+  WardicSegmentOptions,
+  WardicSegmentTarget,
+  WardicSequenceLabel,
+  WardicSequenceOptions,
+  WardicSequenceTime,
+} from "./imperative.ts"
+// Animation controls (#433, Motion's `useAnimationControls`): `animate={controls}`, then `start`, `set` and `stop`.
+export { createAnimationControls, type WardicAnimationControls, type WardicControlsDefinition } from "./animation-controls.ts"
+
+/**
+ * Low-level sensor hooks: `createHover` / `createPress` / `createFocus` /
+ * `createInView` / `createDrag` (recognizer-backed signals) and `createReducedMotion`
+ * (`Probe.prefersReducedMotion` atom bridge); `createReducedMotionConfig`, the nearest config's
+ * setting over it, and `createPageInView`, whether the page is shown (#443).
+ */
+export {
+  type CreateDragOptions,
+  createInView,
+  createPageInView,
+  createReducedMotion,
+  createReducedMotionConfig,
+} from "./sensors.ts"
+export { createDrag } from "./drag-sensor.ts"
+export { createFocus } from "./focus-sensor.ts"
+export { createHover } from "./hover-sensor.ts"
+export { createPress } from "./press-sensor.ts"
+// `createCycle` (#443, Motion's `useCycle`): one of a list of states at a time, stepped through.
+export { createCycle, type Cycle } from "./cycle.ts"
+
+/**
+ * Live values (#130, ADR-0043): a value the user moves, given in an element's `style` (an accessor
+ * or an Atom), followed while no layer of the Override stack sets its key. `createTransform` maps
+ * one (through a function, or ranges), `createFollowValue` follows one on any transition (#441) and
+ * `createSpring` with a spring; `createScroll`, `createVelocity` and `createTime` make one from a
+ * scroll, a value's velocity and time (#234). `createAnimationFrame` tells a callback each frame, and `createWillChange` makes a
+ * `willChange` that turns on as its element animates (#443).
+ */
+export {
+  createAnimationFrame,
+  createFollowValue,
+  createScroll,
+  createSpring,
+  createTime,
+  createTransform,
+  createVelocity,
+  createWillChange,
+  type ElementSource,
+  type ScrollOptions,
+  type ScrollValues,
+} from "./live-value.ts"
+export type { FollowAccessor, FollowValueOptions, Live, LiveSource, SpringAccessor, WillChange } from "./live-style.ts"
+
+/**
+ * `createWard` — a **Ward**, one element's motion binding (ADR-0005, ADR-0042): recognizers ->
+ * Override stack -> spring/tween Retarget -> the gate, which commits each frame onto the
+ * element (ADR-0034), with an SSR-correct synchronous initial (ADR-0003). Returns a callable
+ * `Ward` to spread onto a JSX element (`<div {...ward()}>`).
+ */
+export { createWard } from "./complete.ts"
+export { type Ward, type WardStyle, type WardValue, type WardProps, type WardUserProps } from "./create-ward.tsx"
+export type {
+  WardConfig,
+  WardicDragTransition,
+  WardicViewport,
+  WardicReducedMotion,
+  WardicSkipAnimations,
+  WardicInertia,
+  WardicOrchestration,
+  WardicStagger,
+  WardicPath,
+  WardicPropagate,
+  WardicTransformShorthands,
+  WardicTransformTemplate,
+  WardicScaleCorrector,
+  WardicLayoutBox,
+  WardicTransformPoint,
+  WardicAnimationDefinition,
+  WardicTransition,
+  WardicTransitionEntries,
+  WardicValueKey,
+  WardicValueTransition,
+  WardicKeyframes,
+  WardicTargetValues,
+  WardicValues,
+  WardicVariant,
+  WardicVariantLabels,
+  WardicVariantResolver,
+  WardicVariants,
+  WardicVariantTransition,
+} from "./config.ts"
+
+/**
+ * `<Reorder>` (ADR-0020, ADR-0008 Tier 1): `Reorder.Group` / `Reorder.Item`, built on the
+ * headless API: `createReorderGroup` (a `ReorderGroup`) and `createReorderItem` (a
+ * `ReorderItemWard`) spread onto any elements, and the `use:reorderItem` directive
+ * (client-only). The app owns `values`, sets them from `onReorder`, and keys its items
+ * with `<For>`.
+ */
+export {
+  createReorderGroup,
+  createReorderItem,
+  Reorder,
+  type ReorderElementTag,
+  type ReorderGroup,
+  type ReorderGroupProps,
+  type ReorderItemProps,
+  type ReorderGroupConfig,
+  type ReorderGroupSpread,
+  type ReorderGroupUserProps,
+  type ReorderItemConfig,
+  type ReorderItemSpread,
+  type ReorderItemUserProps,
+  type ReorderItemWard,
+  type ReorderItemLayout,
+  type ReorderItemDirectiveValue,
+  reorderItem,
+} from "./reorder.tsx"
+
+/**
+ * `runDragTrack` (ADR-0004): the binding-orchestrated drag track, run by every Wardic element's
+ * spine (`runSpine`), `createWard`'s and `wardic.create(Component)`'s alike. The pointer
+ * DIRECT-SETS `x`/`y` while the spring drives every other key + `whileDrag`; the release runs on
+ * the **Drag transition**: a **Fling**, a snap back to the origin (`dragSnapToOrigin`), or a rest
+ * where it was let go (`dragMomentum={false}`).
+ */
+export {
+  type DragSnapshot,
+  type DragTrackConfig,
+  type RunDragTrackOptions,
+  runDragTrack,
+} from "./drag.ts"
+
+/**
+ * Variant orchestration context (ADR-0007): the `WardicVariantContext` that
+ * carries the parent's current variant NAME + inherited transition down the
+ * tree, and the `useVariantContext` reader. `ward.Provider` (a property on the
+ * `createWard` callable) publishes into it; inheriting children resolve the name
+ * against their own `variants` map.
+ */
+export {
+  type WardicVariantContextValue,
+  useVariantContext,
+  WardicVariantContext,
+} from "./variants.ts"
+
+/**
+ * `wardic` (ADR-0008 Tier 1, ADR-0042): the `wardic.*` element proxy, `wardic.create(tag)`
+ * HOC, and, called, the `use:wardic` directive. `wardic.div` / `wardic.create("div")` build a
+ * Complete element that puts a Ward on its element and merges the animated style over the
+ * user's static style (`Style.over`) while preserving the user's ref (`mergeRefs`) and passing
+ * all other props through. `<div use:wardic={config}>` puts one on any element, client-only:
+ * import `wardic` for it to resolve.
+ */
+export {
+  type Wardic,
+  type WardicComponent,
+  type WardicMotionProps,
+  type WardicProps,
+  wardic,
+} from "./wardic.tsx"
+/**
+ * `w` (#511, ADR-0067; Motion's `m`): the **Slim element**'s forms, `w.<tag>`, `w.create`,
+ * `w.createWard` and `use:w`, each as its `wardic` form but with only the Features chosen above it.
+ */
+export { type W, w } from "./w.tsx"
+// #443 (Motion's): `wardic.create`'s options; whether a component is a Wardic element's and what it
+// wraps; whether a prop is a motion prop.
+export { isWardicComponent, unwrapWardicComponent, type WardicCreateOptions } from "./wardic-component.ts"
+export { isValidWardicProp } from "./motion-props.ts"
+
+/**
+ * `<AnimatePresence>` — exit-before-unmount (ADR-0007). Wraps its children (a conditional
+ * one, under a `<Show>`, or a `<For>`'s); when one leaves, the presence RETAINS its DOM
+ * node and drives the child's `exit` (parent-driven, since Solid disposes the leaving
+ * child's reactive owner), removing the node once the exit settles. `PresenceContext`
+ * carries the registrar down to descendant spines. `initial={false}` starts the child
+ * present at its first render at its `animate` (#134). Many children, each exiting in its
+ * place, and `mode="wait"` (#277, ADR-0048).
+ */
+export {
+  AnimatePresence,
+  type AnimatePresenceProps,
+  PresenceContext,
+  type PresenceContextValue,
+  type PresenceMode,
+  type PresenceRecord,
+  useIsPresent,
+  usePresence,
+  usePresenceContext,
+  usePresenceData,
+} from "./presence.tsx"
+
+/**
+ * `layout` / `layoutId` surface (ADR-0009 + ADR-0005). `layout` FLIP runs on the
+ * box-based projection system: `createProjectionNode` registers the element as a
+ * projection node (the provider-owned tree handles nesting + sibling reflow).
+ * `<LayoutGroup>` is now a thin grouping boundary whose `layoutDependency`
+ * triggers a full Measure pass. `layoutId` shared-element animation (Switch and
+ * Crossfade) is matched entirely by the Projection system (ADR-0010 *Amendment
+ * (#13)*); `measureLayoutBox` reads an untransformed box.
+ */
+export { type CreateProjectionNodeOptions, LayoutGroup, createProjectionNode } from "./layout.tsx"
+export { measureLayoutBox } from "@wardic/dom/ProjectionSystem"
+
+/**
+ * Motion's easing functions, by Motion's names (#360, ADR-0052), so a port's imports carry over:
+ * `import { easeOut, cubicBezier } from "@wardic/solid"`. An `ease` also takes the names as
+ * strings (`ease: "easeOut"`) and a bézier's four numbers. The Penner set and `Easing.spring` are
+ * in `@wardic/core/Easing`.
+ */
+export {
+  anticipate,
+  backIn,
+  backInOut,
+  backOut,
+  circIn,
+  circInOut,
+  circOut,
+  cubicBezier,
+  easeIn,
+  easeInOut,
+  easeOut,
+  steps,
+} from "@wardic/core/Easing"
+export { stagger, type WardicStaggerOptions } from "./stagger.ts"
+export { arc, type WardicArcOptions } from "./arc.ts"

package/src/instant.ts

@@ -0,0 +1,90 @@
+/**
+ * The **Instant change** and the **Projection reset** (#443, Motion's `useInstantLayoutTransition`,
+ * `useInstantTransition` and `useResetProjection`), scoped to a provider's runtime: its projection
+ * system's `instant` and `reset`, and a flag its elements' animations read as they start.
+ *
+ * Solid-free: both bindings run it over their own provider's context value (#209).
+ *
+ * @module
+ */
+import type * as ProjectionSystem from "@wardic/dom/ProjectionSystem"
+import { constFalse, constVoid } from "effect/Function"
+import * as Predicate from "effect/Predicate"
+
+/**
+ * Whether a provider's animations are instant now (#443, Motion's `instantAnimations`): while on,
+ * every animation that starts is a **Skipped animation** (#468). `start` turns it on, and it goes off
+ * two Refresh frames after the last `start`, as Motion's does; `end` turns it off at once (Motion's
+ * `disableInstantTransitions`).
+ */
+export interface InstantAnimations {
+  readonly active: () => boolean
+  readonly start: () => void
+  readonly end: () => void
+}
+
+/** A provider's {@link InstantAnimations}, timed by its Environment's Refresh frames, found at the first `start`. */
+export const makeInstantAnimations = (requestFrame: () => (callback: () => void) => unknown): InstantAnimations => {
+  let on = false
+  // The calls so far: a call's turn-off is skipped once a later call has come.
+  let calls = 0
+  return {
+    active: () => on,
+    start: () => {
+      on = true
+      calls++
+      const call = calls
+      const request = requestFrame()
+      request(() =>
+        request(() => {
+          if (call === calls) on = false
+        }))
+    },
+    end: () => {
+      on = false
+    },
+  }
+}
+
+/** A server's: never on. */
+export const NO_INSTANT: InstantAnimations = { active: constFalse, start: constVoid, end: constVoid }
+
+/**
+ * `createInstantTransition()`'s start: `start(fn)` runs `fn`, and its layout change and every
+ * animation that starts until two frames after the call land at once. A later call extends it, and
+ * `start.end()` ends it now.
+ */
+// #443, Motion's `useInstantTransition`; `end` is its `disableInstantTransitions`.
+export interface InstantTransition {
+  (fn: () => void): void
+  readonly end: () => void
+}
+
+/**
+ * An Instant change of the layout (#443): `fn` run, and the next Measure pass blocked. On a server,
+ * with no projection system, `fn` alone.
+ */
+export const instantLayoutOf =
+  (projection: () => ProjectionSystem.Shape | undefined) =>
+  (fn?: () => void): void => {
+    const system = projection()
+    if (Predicate.isNotUndefined(system)) return system.instant(fn)
+    if (Predicate.isNotUndefined(fn)) fn()
+  }
+
+/** An Instant change of the layout and of the animations started meanwhile (#443): see {@link InstantTransition}. */
+export const instantTransitionOf = (projection: () => ProjectionSystem.Shape | undefined, instant: () => InstantAnimations): InstantTransition =>
+  Object.assign(
+    (fn: () => void): void =>
+      instantLayoutOf(projection)(() => {
+        instant().start()
+        fn()
+      }),
+    { end: () => instant().end() },
+  )
+
+/** A Projection reset (#443): the projection system's `reset`; nothing on a server. */
+export const resetOf = (projection: () => ProjectionSystem.Shape | undefined) => (): void => {
+  const system = projection()
+  if (Predicate.isNotUndefined(system)) system.reset()
+}

package/src/layout-group.ts

@@ -0,0 +1,32 @@
+/**
+ * A **Layout group**'s namespace for `layoutId` (#432, CONTEXT.md; Motion's `LayoutGroup`,
+ * `.reference/motion` at `16c6122`), Solid-free: both bindings' `<LayoutGroup>` make its id, and every
+ * layout node's `layoutId` is put in it before it reaches the Projection system.
+ *
+ * @module
+ */
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+
+/**
+ * Whether a group joins the id of the group it's in (Motion's `inherit`): `true` and `"id"` both do
+ * (Motion's `true` also joins its node group, whose members are measured together, which Wardic's
+ * whole-tree Measure pass already does, ADR-0009); `false` starts a namespace of its own.
+ */
+export type LayoutGroupInherit = boolean | "id"
+
+/**
+ * A group's id (Motion's): with `inherit` and an outer group's id, that id joined with its own
+ * (`outer-inner`), or the outer one's alone when it has none; else its own, or none.
+ */
+export const layoutGroupIdOf = (outer: string | undefined, id: string | undefined, inherit: LayoutGroupInherit = true): string | undefined => {
+  if (inherit === false) return id
+  if (Predicate.isUndefined(outer)) return id
+  return UndefinedOr.match(id, { onUndefined: () => outer, onDefined: (own) => `${outer}-${own}` })
+}
+
+/** `layoutId` in the group `group` (Motion's `useLayoutId`): `${group}-${layoutId}`, or as it is outside any. */
+export const layoutIdIn = (group: string | undefined, layoutId: string | undefined): string | undefined => {
+  if (Predicate.isUndefined(group)) return layoutId
+  return UndefinedOr.map(layoutId, (own) => `${group}-${own}`)
+}