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

package/src/motion-props.ts

@@ -0,0 +1,325 @@
+/**
+ * A `wardic.*` element's motion props (ADR-0008), Solid-free (#209): every prop the element takes
+ * off its props so none reaches the DOM, their types, and the config a Ward reads from them. Both
+ * bindings' components and `<Reorder.Item>` share them.
+ *
+ * @module
+ */
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Predicate from "effect/Predicate"
+import type { WardConfig } from "./config.ts"
+import type { Accessor } from "./reactivity.ts"
+
+/** Motion's gesture callbacks (#273): Solid 1's, which most elements don't take. */
+const GESTURE_CALLBACKS = [
+  "onHoverStart",
+  "onHoverEnd",
+  "onTapStart",
+  "onTap",
+  "onTapCancel",
+  "onDragStart",
+  "onDrag",
+  "onDragEnd",
+  "onDragTransitionEnd",
+  "onDirectionLock",
+  "onViewportEnter",
+  "onViewportLeave",
+  "onPanSessionStart",
+  "onPanStart",
+  "onPan",
+  "onPanEnd",
+] as const
+
+/**
+ * The keys most elements don't take, which a config with fixed keys reads only when given (#273): the
+ * gesture callbacks, `dragDirectionLock`, `dragControls` and `dragListener` (#431),
+ * `onMeasureDragConstraints`, `whileInView`, `whileFocus`, `viewport` and `custom` (#277).
+ */
+const RARE_KEYS = [
+  ...GESTURE_CALLBACKS,
+  "dragDirectionLock",
+  "dragControls",
+  "dragListener",
+  "onMeasureDragConstraints",
+  "propagate",
+  "layoutCrossfade",
+  "transformTemplate",
+  "onBeforeLayoutMeasure",
+  "onLayoutMeasure",
+  "whileInView",
+  "whileFocus",
+  "viewport",
+  "custom",
+  "key",
+] as const
+
+/** One of {@link RARE_KEYS}. */
+type RareKey = (typeof RARE_KEYS)[number]
+
+/**
+ * Every key {@link motionToConfig} copies into a config, in the order it sets them: the common keys,
+ * the rare ones, then the layout animation and update callbacks.
+ */
+const CONFIG_KEYS = [
+  "initial",
+  "animate",
+  "whileHover",
+  "whileTap",
+  "transition",
+  "variants",
+  "inherit",
+  "exit",
+  "drag",
+  "whileDrag",
+  "dragConstraints",
+  "dragElastic",
+  "dragMomentum",
+  "dragSnapToOrigin",
+  "dragTransition",
+  "dragPropagation",
+  "layout",
+  "layoutDependency",
+  "layoutId",
+  "layoutScroll",
+  "layoutRoot",
+  "layoutAnchor",
+  "onAnimationStart",
+  "onAnimationComplete",
+  ...RARE_KEYS,
+  "onLayoutAnimationStart",
+  "onLayoutAnimationComplete",
+  "onUpdate",
+  "appear",
+] as const
+
+/** One of {@link CONFIG_KEYS}. */
+type ConfigKey = (typeof CONFIG_KEYS)[number]
+
+/**
+ * A config's build from `motion`'s `keys`: each one's value, when it's defined; reading a key tracks
+ * it. A build allocates its config alone (#525, #540).
+ */
+const configBuildOf = (motion: WardicMotionProps, keys: ReadonlyArray<ConfigKey>): Accessor<WardConfig> => () => {
+  // Per element at mount (#540): a loop.
+  const config: Record<string, unknown> = {}
+  for (const key of keys) {
+    const value = motion[key]
+    if (Predicate.isNotUndefined(value)) config[key] = value
+  }
+  return config as WardConfig
+}
+
+/**
+ * Every motion prop the HOC consumes off the props object so it never leaks to
+ * the DOM. A subset (`initial` / `animate` / `variants` / `whileHover` /
+ * `whileTap` / `transition`) is wired into {@link createWard} today; the rest
+ * (`whileFocus` / `whileInView` / `exit` / `drag` / `dragConstraints` /
+ * `layout` / `layoutId`) are accepted + split now but NOT yet wired (a
+ * follow-up) — they are intentionally consumed so they don't render as DOM
+ * attributes. Shared with `<Reorder>`'s item and the Solid 2 binding (internal, not a package export).
+ */
+export const MOTION_PROPS = [
+  "initial",
+  "animate",
+  "variants",
+  "custom",
+  "inherit",
+  "whileHover",
+  "whileTap",
+  "propagate",
+  "whileFocus",
+  "whileInView",
+  "viewport",
+  "exit",
+  "drag",
+  "whileDrag",
+  "dragConstraints",
+  "dragElastic",
+  "dragMomentum",
+  "dragSnapToOrigin",
+  "dragTransition",
+  "dragPropagation",
+  "dragDirectionLock",
+  "dragControls",
+  "dragListener",
+  "onMeasureDragConstraints",
+  "layout",
+  "layoutDependency",
+  "layoutId",
+  "layoutScroll",
+  "layoutRoot",
+  "layoutAnchor",
+  "layoutCrossfade",
+  "onAnimationStart",
+  "onAnimationComplete",
+  ...GESTURE_CALLBACKS,
+  "onLayoutAnimationStart",
+  "onLayoutAnimationComplete",
+  "onUpdate",
+  "transformTemplate",
+  "onBeforeLayoutMeasure",
+  "onLayoutMeasure",
+  "appear",
+  "transition",
+  "key",
+] as const
+
+/**
+ * The motion props Solid 1 takes and Solid 2 doesn't (#257): Motion's animation and layout animation
+ * callbacks, which Solid 2 hands over as async values (`card.next("settled")`, `"layoutStart"`,
+ * `"layoutComplete"`).
+ */
+const SOLID_1_CALLBACKS = [
+  "onAnimationStart",
+  "onAnimationComplete",
+  "onLayoutAnimationStart",
+  "onLayoutAnimationComplete",
+  // Motion's gesture callbacks (#273): Solid 2 hears them through `next(name)`, so on a Solid 2
+  // element `onDrag`, `onDragStart` and `onDragEnd` are the DOM's HTML drag-and-drop events.
+  ...GESTURE_CALLBACKS,
+] as const
+
+/** The callbacks only Solid 1 takes (#257, #273): Solid 2's config and props leave them out. */
+export type SolidOneCallback = (typeof SOLID_1_CALLBACKS)[number]
+
+/** {@link MOTION_PROPS} on Solid 2 (#257): all but Solid 1's callbacks, so `onAnimationStart` on an element there is the DOM's. */
+export const MOTION_PROPS_V2 = /*#__PURE__*/ Arr.filter(MOTION_PROPS, (prop) => Bool.not(Arr.contains(SOLID_1_CALLBACKS, prop))) as ReadonlyArray<
+  Exclude<(typeof MOTION_PROPS)[number], (typeof SOLID_1_CALLBACKS)[number]>
+>
+
+const MOTION_PROP_SET: ReadonlySet<string> = /*#__PURE__*/ new Set(MOTION_PROPS)
+const MOTION_PROP_SET_V2: ReadonlySet<string> = /*#__PURE__*/ new Set(MOTION_PROPS_V2)
+
+/**
+ * Whether `key` is one of a Wardic element's motion props: what `wardic.*` takes for itself and keeps
+ * off its element. Wardic's own list, exactly: `whileHover` is one, `whileAnything` isn't. Motion's
+ * `isValidMotionProp`.
+ *
+ * @example
+ * isValidWardicProp("animate") // true
+ * isValidWardicProp("href") // false
+ * @see https://wardic.dev/reference/solid/utilities/component-checks
+ */
+// #443.
+export const isValidWardicProp = (key: string): boolean => MOTION_PROP_SET.has(key)
+
+/**
+ * Whether `key` is one of a Wardic element's motion props on Solid 2: Solid 1's list, without the
+ * callbacks that are the DOM's own events there (`onAnimationStart`, `onDrag`…), which an element
+ * hands on. Motion's `isValidMotionProp`.
+ *
+ * @see https://wardic.dev/reference/solid/utilities/component-checks
+ */
+// #443.
+export const isValidWardicPropV2 = (key: string): boolean => MOTION_PROP_SET_V2.has(key)
+
+/**
+ * The motion props a Wardic element takes beside its own: `initial`, `animate`, `transition`, the
+ * gestures, drag, layout and the callbacks. Give each as a value, which Solid keeps up to date:
+ * `animate={open() ? shown : hidden}`, not a function.
+ *
+ * @see https://wardic.dev/reference/solid/elements/props
+ */
+// The same props as WardConfig, so one JSDoc per prop is every hover's (#558). Each is a plain value,
+// with no MaybeAccessor (step 21f): a Wardic element's props are getters, so reading one inside the
+// config accessor (motionToConfig) tracks whatever signals back it.
+export type WardicMotionProps = WardConfig
+
+/** {@link WardicMotionProps} on Solid 2: all but Solid 1's callbacks, which its ward's events tell. */
+export type WardicMotionPropsV2 = Omit<WardicMotionProps, (typeof SOLID_1_CALLBACKS)[number]>
+
+/**
+ * Build a reactive `Accessor<WardConfig>` from a split-off `motion` props
+ * object (step 21f — the reactivity boundary).
+ *
+ * Each motion prop is a plain VALUE (the same static type as the matching
+ * {@link WardConfig} field). The returned accessor reads each prop DIRECTLY off
+ * the `motion` object inside the accessor body. Because `motion` is a Solid
+ * split-props object whose fields are reactive getters, reading `motion.animate`
+ * here subscribes to whatever signal backs the prop — so a tracked expression
+ * (`animate={open() ? a : b}`) re-runs this config accessor on a flip and drives a
+ * Retarget. NO `access()`/unwrapping: Solid's prop getters already do the tracking.
+ *
+ * Keys are only assigned when the value is defined — exactOptionalPropertyTypes
+ * forbids an explicit `undefined` on the optional config fields, and an absent key
+ * is exactly how a Ward reads "no field".
+ *
+ * `fixedKeys`: `motion`'s keys stay as they are (it isn't a proxy over a reactive spread), so only
+ * the keys it was given are read, found once (#273, #525): the config is rebuilt at each read, a
+ * mount reads it 13 times, and each read took the 28 common keys where most elements are given two
+ * or three. Without it, all are, as a proxy's keys can change.
+ */
+export const motionToConfig = (motion: WardicMotionProps, fixedKeys = false): Accessor<WardConfig> => {
+  if (fixedKeys) {
+    return configBuildOf(
+      motion,
+      Arr.filter(CONFIG_KEYS, (key) => key in motion),
+    )
+  }
+  return () => {
+    const config: { -readonly [K in keyof WardConfig]: WardConfig[K] } = {}
+    // Read each (reactive) prop getter inside the accessor so it tracks.
+    const initial = motion.initial
+    const animate = motion.animate
+    const whileHover = motion.whileHover
+    const whileTap = motion.whileTap
+    const transition = motion.transition
+    const variants = motion.variants
+    const inherit = motion.inherit
+    const exit = motion.exit
+    const drag = motion.drag
+    const whileDrag = motion.whileDrag
+    const dragConstraints = motion.dragConstraints
+    const dragElastic = motion.dragElastic
+    const dragMomentum = motion.dragMomentum
+    const dragSnapToOrigin = motion.dragSnapToOrigin
+    const dragTransition = motion.dragTransition
+    const dragPropagation = motion.dragPropagation
+    const layout = motion.layout
+    const layoutDependency = motion.layoutDependency
+    const layoutId = motion.layoutId
+    const layoutScroll = motion.layoutScroll
+    const layoutRoot = motion.layoutRoot
+    const layoutAnchor = motion.layoutAnchor
+    const onAnimationStart = motion.onAnimationStart
+    const onAnimationComplete = motion.onAnimationComplete
+    const onLayoutAnimationStart = motion.onLayoutAnimationStart
+    const onLayoutAnimationComplete = motion.onLayoutAnimationComplete
+    const onUpdate = motion.onUpdate
+    const appear = motion.appear
+    if (Predicate.isNotUndefined(initial)) config.initial = initial
+    if (Predicate.isNotUndefined(animate)) config.animate = animate
+    if (Predicate.isNotUndefined(whileHover)) config.whileHover = whileHover
+    if (Predicate.isNotUndefined(whileTap)) config.whileTap = whileTap
+    if (Predicate.isNotUndefined(transition)) config.transition = transition
+    if (Predicate.isNotUndefined(variants)) config.variants = variants
+    if (Predicate.isNotUndefined(inherit)) config.inherit = inherit
+    if (Predicate.isNotUndefined(exit)) config.exit = exit
+    if (Predicate.isNotUndefined(drag)) config.drag = drag
+    if (Predicate.isNotUndefined(whileDrag)) config.whileDrag = whileDrag
+    if (Predicate.isNotUndefined(dragConstraints)) config.dragConstraints = dragConstraints
+    if (Predicate.isNotUndefined(dragElastic)) config.dragElastic = dragElastic
+    if (Predicate.isNotUndefined(dragMomentum)) config.dragMomentum = dragMomentum
+    if (Predicate.isNotUndefined(dragSnapToOrigin)) config.dragSnapToOrigin = dragSnapToOrigin
+    if (Predicate.isNotUndefined(dragTransition)) config.dragTransition = dragTransition
+    if (Predicate.isNotUndefined(dragPropagation)) config.dragPropagation = dragPropagation
+    if (Predicate.isNotUndefined(layout)) config.layout = layout
+    if (Predicate.isNotUndefined(layoutDependency)) config.layoutDependency = layoutDependency
+    if (Predicate.isNotUndefined(layoutId)) config.layoutId = layoutId
+    if (Predicate.isNotUndefined(layoutScroll)) config.layoutScroll = layoutScroll
+    if (Predicate.isNotUndefined(layoutRoot)) config.layoutRoot = layoutRoot
+    if (Predicate.isNotUndefined(layoutAnchor)) config.layoutAnchor = layoutAnchor
+    if (Predicate.isNotUndefined(onAnimationStart)) config.onAnimationStart = onAnimationStart
+    if (Predicate.isNotUndefined(onAnimationComplete)) config.onAnimationComplete = onAnimationComplete
+    Arr.forEach(RARE_KEYS, (key) => {
+      const value = motion[key]
+      if (Predicate.isNotUndefined(value)) (config as Record<RareKey, unknown>)[key] = value
+    })
+    if (Predicate.isNotUndefined(onLayoutAnimationStart)) config.onLayoutAnimationStart = onLayoutAnimationStart
+    if (Predicate.isNotUndefined(onLayoutAnimationComplete)) config.onLayoutAnimationComplete = onLayoutAnimationComplete
+    if (Predicate.isNotUndefined(onUpdate)) config.onUpdate = onUpdate
+    if (Predicate.isNotUndefined(appear)) config.appear = appear
+    return config
+  }
+}

package/src/owner-scope.ts

@@ -0,0 +1,31 @@
+/**
+ * The Scopes a binding opens on its provider's runtime, for an element's or a hook's work: each a child
+ * of the runtime's own, so one nothing closed ends with the runtime, and closed with its owner without
+ * throwing into the Solid cleanup that closes it. Solid-free, for both bindings.
+ *
+ * @module
+ */
+import * as Report from "@wardic/dom/Report"
+import * as Exit from "effect/Exit"
+import type * as ManagedRuntime from "effect/ManagedRuntime"
+import * as Scope from "effect/Scope"
+
+/**
+ * A Scope for one owner's work on `runtime`: a child of the runtime's, so the runtime's disposal closes
+ * it if its owner hasn't. Its finalizers run in reverse order, as a Scope's do.
+ */
+// #618 (L1): no detached `Scope.makeUnsafe()`. A child closed first takes itself off its parent.
+export const open = (runtime: { readonly scope: Scope.Scope }): Scope.Closeable => Scope.forkUnsafe(runtime.scope, "sequential")
+
+/**
+ * Closes `scope` now, synchronously, on `runtime`. A finalizer that fails is logged and reported as
+ * `label` (`Report.failure`), never thrown: the rest of the Solid cleanup that closes it still runs. A
+ * Scope the runtime's disposal already closed is left as it is.
+ */
+// #618 (decision 5): `runtime.runSync(Scope.close(…))` threw a failed finalizer's cause into Solid's
+// cleanup, which skipped the rest of it.
+export const close = <R>(runtime: ManagedRuntime.ManagedRuntime<R, never>, scope: Scope.Closeable, label: string): void => {
+  if (scope.state._tag === "Closed") return
+  const exit = runtime.runSyncExit(Scope.close(scope, Exit.void))
+  if (Exit.isFailure(exit)) runtime.runFork(Report.failure(label, exit.cause))
+}

package/src/page-point.ts

@@ -0,0 +1,98 @@
+/**
+ * Point mappings for `WardicConfig`'s `transformPagePoint` (#443, Motion's `correctParentTransform`
+ * and `transformViewBoxPoint`), Solid-free, for both bindings. Each takes its element as it is, or an
+ * accessor of one (a ref's, set at mount), read at each point. Wardic's points are in the viewport's
+ * coordinates, where Motion's are the page's, so neither adds the page's scroll.
+ *
+ * @module
+ */
+import * as Predicate from "effect/Predicate"
+import type { WardicTransformPoint } from "./config.ts"
+
+/** An element given as it is, or an accessor of one. */
+export type ElementGiven<E extends Element> = E | (() => E | undefined)
+
+/** The element now: an accessor's, or the one given. */
+const elementOf = <E extends Element>(given: ElementGiven<E>): E | undefined => {
+  if (Predicate.isFunction(given)) return given()
+  return given
+}
+
+/** A 2D linear map's coefficients: the inverse of an element's transform, as Motion's `getInverseMatrix`. */
+interface Linear {
+  readonly a: number
+  readonly b: number
+  readonly c: number
+  readonly d: number
+}
+
+/** The inverse of `element`'s computed transform's linear part, or `undefined` for none, or one that can't be inverted. */
+const inverseOf = (element: Element): Linear | undefined => {
+  const transform = getComputedStyle(element).transform
+  if (Predicate.isUndefined(transform) || transform === "" || transform === "none") return undefined
+  const { a, b, c, d } = new DOMMatrixReadOnly(transform)
+  const det = a * d - b * c
+  if (Math.abs(det) < 1e-10) return undefined
+  return { a: d / det, b: -b / det, c: -c / det, d: a / det }
+}
+
+/**
+ * A `transformPagePoint` for a drag or a pan inside a parent with a CSS transform, rotated, scaled or
+ * skewed: each pointer point is turned through the inverse of the parent's transform, read at each
+ * point, so the element stays under the pointer at any zoom, and a parent that animates is followed.
+ * The parent is an element, or an accessor of a ref. Motion's `correctParentTransform`.
+ *
+ * @example
+ * let plan!: HTMLDivElement
+ * <div ref={plan} style={{ transform: `scale(${zoom()})` }}>
+ *   <WardicConfig transformPagePoint={correctParentTransform(() => plan)}>
+ *     <w.div drag />
+ *   </WardicConfig>
+ * </div>
+ * @see https://wardic.dev/reference/solid/utilities/page-points
+ */
+// #443. Points pass as they are while the parent is gone or has no transform.
+export const correctParentTransform =
+  (parent: ElementGiven<Element>): WardicTransformPoint =>
+  (point) => {
+    const element = elementOf(parent)
+    if (Predicate.isUndefined(element)) return point
+    const inverse = inverseOf(element)
+    if (Predicate.isUndefined(inverse)) return point
+    const box = element.getBoundingClientRect()
+    const cx = box.left + box.width / 2
+    const cy = box.top + box.height / 2
+    const dx = point.x - cx
+    const dy = point.y - cy
+    return { x: cx + inverse.a * dx + inverse.c * dy, y: cy + inverse.b * dx + inverse.d * dy }
+  }
+
+/**
+ * A `transformPagePoint` for a drag or a pan inside an SVG whose `viewBox` differs from the size it
+ * renders at: each pointer point is scaled into the viewBox's units, so a dragged shape stays under
+ * the pointer. The SVG is an element, or an accessor of a ref. Motion's `transformViewBoxPoint`.
+ *
+ * @example
+ * let svg!: SVGSVGElement
+ * <WardicConfig transformPagePoint={transformViewBoxPoint(() => svg)}>
+ *   <svg ref={svg} viewBox="0 0 100 100" width="500" height="500">
+ *     <w.rect drag width="10" height="10" />
+ *   </svg>
+ * </WardicConfig>
+ * @see https://wardic.dev/reference/solid/utilities/page-points
+ */
+// #443. Points pass as they are while the SVG is gone, has no viewBox, or renders at no size.
+export const transformViewBoxPoint =
+  (svg: ElementGiven<SVGSVGElement>): WardicTransformPoint =>
+  (point) => {
+    const element = elementOf(svg)
+    if (Predicate.isUndefined(element)) return point
+    const viewBox = element.viewBox.baseVal
+    if (Predicate.isNullish(viewBox) || (viewBox.width === 0 && viewBox.height === 0)) return point
+    const box = element.getBoundingClientRect()
+    if (box.width === 0 || box.height === 0) return point
+    return {
+      x: (point.x - box.left) * (viewBox.width / box.width) + box.left,
+      y: (point.y - box.top) * (viewBox.height / box.height) + box.top,
+    }
+  }