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

package/src/unstable/v2/wardic-config.tsx

@@ -0,0 +1,84 @@
+/**
+ * `WardicConfig` on the Solid 2 binding (#434, Motion's `MotionConfig`): settings for the Wardic
+ * elements below it, as on the Solid 1 binding. A context value is its own provider.
+ *
+ * @module
+ */
+import type { JSX } from "@solidjs/web"
+import * as Option from "effect/Option"
+import { createContext, createMemo, useContext } from "solid-js"
+import type * as ReducedMotion from "@wardic/core/ReducedMotion"
+import type { WardicTransformPoint, WardicVariantTransition } from "../../config.ts"
+import { configIsValidPropOf, configReducedMotionOf, configTransformPagePointOf, configSkipAnimationsOf, configTransitionOf, type WardicConfigValue } from "../../wardic-config-value.ts"
+import { CLIENT_ONLY } from "./solid-reactivity.ts"
+
+// `null` for none, as the binding's other contexts: Solid 2 throws on a read of a context made with
+// `undefined` and no provider above, and most elements have no `WardicConfig` above them.
+const WardicConfigContext = createContext<WardicConfigValue | null>(null)
+
+/** `WardicConfig`'s props. */
+export interface WardicConfigProps {
+  /**
+   * The **Config transition**: each Wardic element below runs on it when it gives no `transition` of
+   * its own, a Variant child in place of its parent's, as Motion's `MotionConfig` `transition`. It
+   * replaces an enclosing config's, or with `inherit: true` lays its own fields over it. Read when
+   * each animation starts.
+   */
+  readonly transition?: WardicVariantTransition | undefined
+  /**
+   * How the Wardic elements below honour the user's `prefers-reduced-motion`, as Motion's
+   * `MotionConfig` `reducedMotion`: `"user"` follows it, `"always"` reduces motion whatever it is,
+   * `"never"` animates whatever it is. It replaces an enclosing config's, and the `WardicProvider`'s
+   * for them; with none, theirs applies. Read when each animation starts.
+   */
+  readonly reducedMotion?: ReducedMotion.Config | undefined
+  /**
+   * Every animation of the Wardic elements below lands at its end on the next frame, as Motion's
+   * `MotionConfig` `skipAnimations`: its legs, exits, layout animations, a drag's release,
+   * `createAnimate` and `createSpring`, each still told. For end-to-end and visual-regression tests.
+   * An inner config's `false` animates its subtree again. Read when each animation starts.
+   */
+  readonly skipAnimations?: boolean | undefined
+  /**
+   * Which of the props given a Wardic element's tag below reach the element (Motion's
+   * `MotionConfig` `isValidProp`): one it returns `false` for is kept off it, for a prop a styling
+   * system reads that shouldn't render as an attribute. Asked of no prop starting with `on`, nor a
+   * wrapped component's, which get every prop, as Motion's do. It replaces an enclosing config's. Read as
+   * each element is made, for the props it has then.
+   */
+  readonly isValidProp?: ((key: string) => boolean) | undefined
+  /**
+   * Where the points a drag or a pan below uses are (Motion's `MotionConfig`
+   * `transformPagePoint`): handed each point in the viewport's coordinates, it gives the one the
+   * gesture uses. Read at each drag or pan start, and applied to its down, each move, a drag
+   * controls' start and its snap to the cursor, and to the boxes drag constraints are measured from;
+   * never to a layout animation's boxes, which Wardic already reads through their ancestors'
+   * transforms. `correctParentTransform(parent)` makes one for a zoomed or rotated parent, and
+   * `transformViewBoxPoint(svg)` one for an SVG's viewBox. It replaces an enclosing config's.
+   */
+  readonly transformPagePoint?: WardicTransformPoint | undefined
+  readonly children?: JSX.Element
+}
+
+/**
+ * Settings for the Wardic elements below it (Motion's `MotionConfig`): their default
+ * `transition`, their `reducedMotion` and `skipAnimations`. Nest it anywhere under a
+ * `WardicProvider`; an inner one replaces an outer one's, unless its transition inherits it.
+ *
+ * ```tsx
+ * <WardicConfig transition={{ type: "spring", stiffness: 300, damping: 30 }}>
+ *   <wardic.div animate={{ x: 100 }} />
+ * </WardicConfig>
+ * ```
+ */
+export function WardicConfig(props: WardicConfigProps): JSX.Element {
+  const parent = useWardicConfig()
+  // One object per change, so the elements below share it, and its caches (#66, #301) hit. Transparent
+  // to hydration ids, as every computation the binding makes (#209).
+  const transition = createMemo(() => configTransitionOf(props.transition, parent), CLIENT_ONLY)
+  return <WardicConfigContext value={{ transition, reducedMotion: () => configReducedMotionOf(props.reducedMotion, parent), skipAnimations: () => configSkipAnimationsOf(props.skipAnimations, parent), isValidProp: () => configIsValidPropOf(props.isValidProp, parent), transformPagePoint: () => configTransformPagePointOf(props.transformPagePoint, parent) }}>{props.children}</WardicConfigContext>
+}
+
+/** The nearest `WardicConfig`'s settings, or none. Internal. */
+export const useWardicConfig = (): WardicConfigValue | undefined => Option.getOrUndefined(Option.fromNullishOr(useContext(WardicConfigContext)))
+

package/src/unstable/v2/wardic.tsx

@@ -0,0 +1,41 @@
+/**
+ * `wardic.<tag>` and `wardic.create` on Solid 2 (#209, ADR-0008, ADR-0045): the **Complete element**'s
+ * component forms, every Feature brought with it (#511, ADR-0067), as Motion's `motion` is. How a
+ * component is made, and what the forms share, is `element.tsx`'s; `w.tsx` holds the Slim element's.
+ *
+ * @module
+ */
+import type { JSX } from "@solidjs/web"
+import { type Create, createOf, formOf, type WardicComponent } from "./element.tsx"
+import { COMPLETE } from "./complete.ts"
+
+export {
+  type GivenWard,
+  type WardicBeside,
+  type WardicComponent,
+  type WardicMotion,
+  type WardicProps,
+  type WardicWrappable,
+  type WardicWrapped,
+  type WardNodeKey,
+  type WardRefCallback,
+} from "./element.tsx"
+
+/** `wardic.create(tag | Component)`: a Complete element's component (`element.tsx`'s `createWith`). */
+export const create: Create = createOf(COMPLETE)
+
+/** `wardic`: `wardic.create`, and `wardic.<tag>`, a component for that element (one per tag). */
+export type Wardic = { readonly create: Create } & {
+  readonly [Tag in keyof JSX.IntrinsicElements]: WardicComponent<Tag>
+}
+
+/**
+ * The Complete element: `wardic.div` and every other tag, with every Feature whatever its section
+ * gives, and `wardic.create(Component)`. Handy for trying something out, heavy for a page: under a
+ * `strict` provider it throws in development. Motion's `motion.div`.
+ *
+ * @example <wardic.div drag whileHover={{ scale: 1.05 }} />
+ * @see https://wardic.dev/reference/solid/elements/wardic
+ */
+// `wardic.<tag>` is cached, so `wardic.div === wardic.div` (ADR-0067: the Complete element).
+export const wardic: Wardic = formOf<Wardic>(create, {})

package/src/variant-node.ts

@@ -0,0 +1,368 @@
+/**
+ * An element's place in variant orchestration on the Solid 1 binding (ADR-0007, #50), shared by
+ * every Wardic surface: `createWard` (so `wardic.*` and `<Reorder.Item>`), `wardic.create(Component)`
+ * and the directives. The rules it runs are Solid-free, in `variant-tree.ts` (#209).
+ *
+ * Membership is decided once, at setup, as `initial` is read. The names stay reactive.
+ */
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import { constTrue, constUndefined, constVoid } from "effect/Function"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { type Accessor, createEffect, createMemo, createSignal, on, onCleanup, untrack } from "solid-js"
+import type { ControlsChange } from "./animation-controls.ts"
+import type { WardicTransition, WardicVariantLabels } from "./config.ts"
+import {
+  activeNamesOf,
+  type ChangeAtTrigger,
+  changeAtTrigger,
+  controlsChangeOf,
+  changeConfigOf,
+  orchestrationAt,
+  type GestureHandDown,
+  handDownFrom,
+  handDownOf,
+  type GestureStates,
+  NO_GESTURE_STATES,
+  NO_HAND_DOWN,
+  sameHandDown,
+  topGestureName,
+  triggerKeyOf,
+  handedDown,
+  hasOwnVariants,
+  inheritedContext,
+  initialNameOf,
+  nameOf,
+  ownOrInherited,
+  childDelayOf,
+  mayStartOf,
+  type NameConfig,
+  nameConfigOf,
+  type NameOrchestration,
+  passedThrough,
+  sameStagger,
+  staggerOf,
+  staggerOfName,
+  type VariantConfig,
+  type WardicChildRegistration,
+  type WardicStaggerConfig,
+  type WardicVariantContextValue,
+} from "./variant-tree.ts"
+import { ownTransitionOf, sameLabels, transitionOfTarget } from "./variant-target.ts"
+
+/** An element's place in variant orchestration, on the client. */
+export interface VariantNode {
+  /** What its children read: its own context, its parent's passed through, or none. */
+  readonly provided: WardicVariantContextValue | undefined
+  /** The context its spine inherits names and its default transition from: its parent's, for a Variant child. */
+  readonly inherited: WardicVariantContextValue | undefined
+  /** Its stagger delay in seconds, as a Variant child; `undefined` for any other element. */
+  readonly extraDelay: ((name: string | undefined) => number) | undefined
+  /** Whether its spine may start a Retarget: its ancestor's `beforeChildren` and its own `afterChildren` allow it. */
+  readonly canStart: () => boolean
+  /** Its spine's settle report on each frame: to its ancestor's registry, and to its own `beforeChildren`. */
+  readonly onFrame: (done: boolean) => void
+  /**
+   * Bind its spine's gesture states (#291), once it mounts: the names it hands its Variant children
+   * follow them. Only an element whose Variant children join it has one.
+   */
+  readonly bindGestures: ((states: Accessor<GestureStates>) => void) | undefined
+  /**
+   * A list's names orchestrated each on their own (#297's PR 2): its spine's gates and per-name
+   * settles. Only an element that joins a provider or provides has one.
+   */
+  readonly names: NameOrchestration | undefined
+}
+
+/** The orchestration an element with variants of its own runs for its Variant children. */
+interface OwnOrchestration {
+  readonly context: WardicVariantContextValue
+  readonly canStart: () => boolean
+  readonly settled: (done: boolean) => void
+  readonly bindGestures: (states: Accessor<GestureStates>) => void
+  /** A list's name's own `afterChildren` (#297's PR 2): its keys wait for its children's of that name. */
+  readonly canStartFor: (name: string) => boolean
+  /** Its keys of a list's names settled, or moving again (#297's PR 2). */
+  readonly settledFor: (names: ReadonlyArray<string>, done: boolean) => void
+}
+
+/** A registered Variant child, as its ancestor's registry holds it. */
+/** A registered Variant child's stagger slot, as its ancestor's registry holds it: set at each trigger. */
+interface ChildRecord {
+  index: number
+  total: number
+  /** The names of a list whose keys it has settled since the list last changed (#297's PR 2). */
+  readonly names: Set<string>
+}
+
+/**
+ * The registry, stagger and `when` an element with variants of its own runs for its Variant
+ * children (ADR-0007), and the names it hands them. Call within a Solid owner.
+ */
+const ownOrchestration = (
+  cfg: Accessor<VariantConfig>,
+  parent: WardicVariantContextValue | undefined,
+  inherited: WardicVariantContextValue | undefined,
+  change: Accessor<ControlsChange | undefined>,
+): OwnOrchestration => {
+  const config = untrack(cfg)
+  // Children in mount order (a Set keeps insertion order); the effect below snapshots that
+  // order at each trigger. Kept with a count of the unsettled ones rather than a signal of the
+  // records, so a child's mount, unmount or settle costs the same at 1,000 children as at 1.
+  const records = new Set<ChildRecord>()
+  const [unsettled, setUnsettled] = createSignal(0)
+  // The names of a list whose own keys have settled since the list last changed (#297's PR 2).
+  const ownNames = new Set<string>()
+  // True once this element's own animation settles; false again at each variant change.
+  // Drives `beforeChildren`.
+  const [ownSettled, setOwnSettled] = createSignal(false)
+
+  const register = (): WardicChildRegistration => {
+    const record: ChildRecord = { index: 0, total: 1, names: new Set() }
+    // A child starts unsettled; its spine reports each frame, so only a change counts.
+    let settled = false
+    records.add(record)
+    setUnsettled((k) => k + 1)
+    const setSettled = (done: boolean): void => {
+      if (done === settled) return
+      settled = done
+      setUnsettled((k) => k + Bool.match(done, { onTrue: () => -1, onFalse: () => 1 }))
+    }
+    const dispose = (): void => {
+      if (!records.delete(record)) return
+      if (!settled) setUnsettled((k) => k - 1)
+    }
+    return {
+      index: () => {
+        fresh()
+        return record.index
+      },
+      total: () => {
+        fresh()
+        return record.total
+      },
+      setSettled,
+      setSettledFor: (name, done) => {
+        Bool.match(done, { onTrue: () => record.names.add(name), onFalse: () => record.names.delete(name) })
+      },
+      dispose,
+    }
+  }
+
+  // Snapshot-at-trigger (ADR-0007): each child's index and total are recomputed only when a trigger
+  // (this element's variant, or its gestures' names, #291) changes, so a mount, unmount or reorder
+  // mid-transition doesn't reshuffle in-flight delays. `staggerDirection: -1` reverses the index.
+  // Taken at the first slot read after the change (as the Solid 2 binding's, #209 PR 4a): a child
+  // the same change Retargets reads its slot before an effect of this element's could run.
+  let stale = true
+  const fresh = (): void => {
+    if (!stale) return
+    stale = false
+    // Each in order: a name's `staggerDirection` turns it at its delay (#297), a list's names each theirs.
+    const n = records.size
+    let i = 0
+    records.forEach((record) => {
+      record.total = n
+      record.index = i
+      i++
+    })
+  }
+
+  // The names handed down. `animate`'s is reactive; `initial`'s is read once.
+  // A list the same name by name is no change (#297).
+  const variant: Accessor<WardicVariantLabels | undefined> = createMemo(
+    () => {
+      const c = cfg()
+      return handedDown(c, () => nameOf(c.animate), () => UndefinedOr.map(parent, (p) => p.variant()))
+    },
+    undefined,
+    { equals: sameLabels },
+  )
+
+  // What it hands down for its gestures (#291), whether each is on and its label: its spine's states, bound once it mounts.
+  // Changed only when a name does, so its children re-resolve only then.
+  const [states, setStates] = createSignal<Accessor<GestureStates> | undefined>(undefined)
+  const gestures: Accessor<GestureHandDown> = createMemo(
+    () => handDownOf(cfg(), UndefinedOr.match(states(), { onUndefined: () => NO_GESTURE_STATES, onDefined: (on) => on() }), handDownFrom(inherited)),
+    NO_HAND_DOWN,
+    { equals: sameHandDown },
+  )
+
+  // The Controls change its latest trigger came with (#433): while it's the latest, its override is
+  // the orchestration.
+  const at: Accessor<ChangeAtTrigger> = createMemo((previous: ChangeAtTrigger | undefined) =>
+    changeAtTrigger(change(), triggerKeyOf(variant(), gestures(), change()), previous))
+  // Its orchestration (#277, #291, Motion's): the own transition of its highest active gesture's name,
+  // else of its target (the variant it names), else its `transition`; a Controls change's override at
+  // the trigger it came with (#433).
+  const orchestration: Accessor<WardicTransition | undefined> = createMemo(() =>
+    orchestrationAt(at(), () => {
+      const c = cfg()
+      const own = UndefinedOr.match(topGestureName(activeNamesOf(gestures())), {
+        onDefined: (name) => ownTransitionOf(undefined, name, c.variants, c.custom),
+        onUndefined: () => ownTransitionOf(c.animate, variant(), c.variants, c.custom),
+      })
+      return transitionOfTarget(own, c.transition)
+    }))
+  // What its children's stagger and `when` snapshot at: its variant, its gestures' names (#291), and
+  // a Controls change (#433).
+  const trigger: Accessor<string> = createMemo((previous: string | undefined) => {
+    const next = triggerKeyOf(variant(), gestures(), change())
+    if (next !== previous) {
+      stale = true
+      // Each name waits again (#297's PR 2): its keys, and its children's, settle anew.
+      ownNames.clear()
+      records.forEach((record) => record.names.clear())
+    }
+    return next
+  })
+  const stagger: Accessor<WardicStaggerConfig> = createMemo(() => staggerOf(orchestration()), undefined, { equals: sameStagger })
+  // A list's names have each their own (#297's PR 2): none for the list as a whole.
+  const when: Accessor<"beforeChildren" | "afterChildren" | undefined> = () => {
+    if (Arr.isArray(variant())) return undefined
+    return UndefinedOr.map(orchestration(), (t) => t.when)
+  }
+  const initial = handedDown<WardicVariantLabels | false>(config, () => initialNameOf(config.initial), () => UndefinedOr.map(parent, (p) => p.initial))
+
+  // Each name's orchestration for the Variant children's keys of that name (#297, Motion's
+  // `animateVariant` a name): its own transition's, else the element's. Kept per name until the
+  // config changes; a key from no name takes the element's whole orchestration.
+  const byName: Accessor<Map<string, NameConfig>> = createMemo(() => {
+    cfg()
+    return new Map()
+  })
+  const configOf = (name: string): NameConfig => {
+    // A Controls change's override orchestrates every name at its trigger (#433).
+    const changed = changeConfigOf(untrack(at))
+    if (Predicate.isNotUndefined(changed)) return changed
+    const known = byName()
+    const kept = known.get(name)
+    if (Predicate.isNotUndefined(kept)) return kept
+    const c = untrack(cfg)
+    const made = nameConfigOf(transitionOfTarget(ownTransitionOf(undefined, name, c.variants, c.custom), c.transition))
+    known.set(name, made)
+    return made
+  }
+  const staggerFor = (name: string | undefined): WardicStaggerConfig => {
+    if (Predicate.isUndefined(name)) return stagger()
+    return configOf(name).stagger
+  }
+  // Each of a list's names' own `when` (#297's PR 2), read by polling: which of its names' keys have
+  // settled since the list last changed (`ownNames`, above), and (in each record) its children's.
+  const mayStartFor = (name: string): boolean => Bool.or(untrack(() => configOf(name)).when !== "beforeChildren", ownNames.has(name))
+  const canStartFor = (name: string): boolean => {
+    if (untrack(() => configOf(name)).when !== "afterChildren") return true
+    let all = true
+    records.forEach((record) => {
+      if (Bool.not(record.names.has(name))) all = false
+    })
+    return all
+  }
+  const settledFor = (names: ReadonlyArray<string>, done: boolean): void =>
+    Arr.forEach(names, (name) => {
+      Bool.match(done, { onTrue: () => ownNames.add(name), onFalse: () => ownNames.delete(name) })
+    })
+
+  // `beforeChildren` waits again at each trigger, until this element's own animation settles.
+  createEffect(
+    on(trigger, () => {
+      setOwnSettled(false)
+    }),
+  )
+
+  const childrenMayStart: Accessor<boolean> = () => when() !== "beforeChildren" || ownSettled()
+  const allChildrenSettled: Accessor<boolean> = () => unsettled() === 0
+  // The transition its children default to: its own, else the one it inherits.
+  const transition: Accessor<WardicTransition | undefined> = createMemo(() => ownOrInherited(cfg().transition, inherited))
+
+  return {
+    context: { variant, initial, transition, gestures, register, stagger, staggerFor, mayStartFor, when, childrenMayStart, allChildrenSettled, change },
+    // It holds its own start for `afterChildren` (it owns the registry, so it reads it directly).
+    canStart: () => when() !== "afterChildren" || allChildrenSettled(),
+    settled: (done) => setOwnSettled(done),
+    bindGestures: (on) => {
+      setStates(() => on)
+    },
+    canStartFor,
+    settledFor,
+  }
+}
+
+/** A node's gesture binding: its own orchestration's, none without one. A guard: it's made per element. */
+const bindOf = (own: OwnOrchestration | undefined): ((states: Accessor<GestureStates>) => void) | undefined => {
+  if (Predicate.isUndefined(own)) return undefined
+  return own.bindGestures
+}
+
+/**
+ * An element's place in variant orchestration on the client, from its config and the nearest
+ * context (`useVariantContext()`). Call within a Solid owner.
+ */
+export const createVariantNode = (
+  cfg: Accessor<VariantConfig>,
+  parent: WardicVariantContextValue | undefined,
+  controls?: Accessor<ControlsChange | undefined>,
+): VariantNode => {
+  const config = untrack(cfg)
+  const inherited = inheritedContext(config, parent)
+  // The Controls change in effect (#433): its own controls', else the one its provider is in.
+  const change = controlsChangeOf(controls, inherited)
+  // A Variant child registers with the ancestor it joins, for its stagger slot and its `when`.
+  const joined = UndefinedOr.map(inherited, (context) => ({ context, registration: context.register() }))
+  if (Predicate.isNotUndefined(joined)) onCleanup(joined.registration.dispose)
+  const own = Bool.match(hasOwnVariants(config), {
+    onFalse: constUndefined,
+    onTrue: () => ownOrchestration(cfg, parent, inherited, change),
+  })
+  // The spine reports on every frame (the per-frame path, docs/agents/effect-first.md): both
+  // reports are resolved here, once, so a frame makes two plain calls and allocates nothing.
+  const reportJoined: (done: boolean) => void = UndefinedOr.match(joined, {
+    onUndefined: () => constVoid,
+    onDefined: ({ registration }) => registration.setSettled,
+  })
+  const reportOwn: (done: boolean) => void = UndefinedOr.match(own, { onUndefined: () => constVoid, onDefined: (o) => o.settled })
+  return {
+    provided: UndefinedOr.match(own, { onDefined: (o) => o.context, onUndefined: () => passedThrough(config, parent) }),
+    inherited,
+    extraDelay: UndefinedOr.map(joined, ({ context, registration }) => (name: string | undefined) => {
+      const s = staggerOfName(context, name)
+      const n = registration.total()
+      return childDelayOf(s, registration.index(), n)
+    }),
+    canStart: () =>
+      UndefinedOr.match(inherited, { onUndefined: constTrue, onDefined: (context) => context.childrenMayStart() }) &&
+      UndefinedOr.match(own, { onUndefined: constTrue, onDefined: (o) => o.canStart() }),
+    onFrame: (done) => {
+      reportJoined(done)
+      reportOwn(done)
+    },
+    bindGestures: bindOf(own),
+    names: namesOf(joined, own),
+  }
+}
+
+/**
+ * Its spine's per-name orchestration (#297's PR 2): a name's keys start once its provider's
+ * `beforeChildren` and its own `afterChildren` for that name allow; their starts and settles are told
+ * to both. None for an element that joins nothing and provides nothing: made per element, a guard.
+ */
+const namesOf = (
+  joined: { readonly context: WardicVariantContextValue; readonly registration: WardicChildRegistration } | undefined,
+  own: OwnOrchestration | undefined,
+): NameOrchestration | undefined => {
+  if (Bool.and(Predicate.isUndefined(joined), Predicate.isUndefined(own))) return undefined
+  const tell = (names: ReadonlyArray<string>, done: boolean): void => {
+    UndefinedOr.map(joined, ({ registration }) => UndefinedOr.map(registration.setSettledFor, (set) => Arr.forEach(names, (name) => set(name, done))))
+    UndefinedOr.map(own, (o) => o.settledFor(names, done))
+  }
+  return {
+    mayStart: (name) =>
+      Bool.and(
+        UndefinedOr.match(joined, { onUndefined: constTrue, onDefined: ({ context }) => mayStartOf(context, name) }),
+        UndefinedOr.match(own, { onUndefined: constTrue, onDefined: (o) => o.canStartFor(name) }),
+      ),
+    moving: (names) => tell(names, false),
+    settled: (names) => tell(names, true),
+  }
+}