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

package/src/cycle-index.ts

@@ -0,0 +1,18 @@
+/**
+ * `createCycle`'s step, Solid-free, on both bindings (#443).
+ *
+ * @module
+ */
+import * as Bool from "effect/Boolean"
+import * as Predicate from "effect/Predicate"
+
+/**
+ * The index a cycle's step goes to from `current` among `length` items (Motion's `useCycle`): `next`
+ * when it's a number, as given; else the one after `current`, the first after the last (Motion's
+ * `wrap`).
+ */
+export const nextIndexOf = (current: number, length: number, next: unknown): number =>
+  Bool.match(Predicate.isNumber(next), {
+    onTrue: () => next as number,
+    onFalse: () => (current + 1) % length,
+  })

package/src/cycle.ts

@@ -0,0 +1,34 @@
+/**
+ * `createCycle` on Solid 1 (#443, Motion's `useCycle`): one of a list of states at a time, stepped
+ * through.
+ *
+ * @module
+ */
+import { type Accessor, createSignal } from "solid-js"
+import { nextIndexOf } from "./cycle-index.ts"
+
+/** `createCycle`'s step: to the next value, the first after the last, or to index `i`. Motion's `Cycle`. */
+export type Cycle = (i?: number) => void
+
+/**
+ * One of a list of values at a time: the first to begin with, and `cycle()` steps to the next, the
+ * first after the last. `cycle(i)` goes to index `i`. Two steps in one handler step twice. Motion's
+ * `useCycle`, its value an accessor.
+ *
+ * @example
+ * const [x, cycleX] = createCycle(0, 50, 100)
+ * <w.div animate={{ x: x() }} onClick={() => cycleX()} />
+ * @see https://wardic.dev/reference/solid/utilities/create-cycle
+ */
+// #443. The index is kept outside the signal too, as Motion keeps it in a ref; `cycle(i)` is taken as
+// given, unchecked, and anything but a number steps, as Motion's (`typeof next !== "number"`).
+export const createCycle = <T,>(...items: ReadonlyArray<T>): readonly [Accessor<T>, Cycle] => {
+  // The index as a plain variable too, as Motion's ref: two steps in one handler step twice.
+  let current = 0
+  const [index, setIndex] = createSignal(0)
+  const cycle: Cycle = (next) => {
+    current = nextIndexOf(current, items.length, next)
+    setIndex(current)
+  }
+  return [() => items[index()] as T, cycle]
+}

package/src/directive.ts

@@ -0,0 +1,87 @@
+/**
+ * `use:wardic` — the Solid directive surface for Wardic motion (ADR-0008 Tier 1, ADR-0042):
+ * it puts a **Ward** on the element it's on. It's the `wardic` export itself, called:
+ * `wardic.<tag>` and `wardic.create` are its properties (`wardic.tsx`).
+ *
+ * Solid's compiler turns `<div use:wardic={config}>` into `wardic(el, () => config)`,
+ * so {@link wardicDirective} receives the live element plus a reactive `Accessor<WardConfig>`
+ * (the compiler always wraps the value in a thunk). The directive drives that GIVEN
+ * element through the shared {@link runSpine} — the same path as every Wardic element
+ * (ADR-0006, ADR-0034): the gate commits the projected `Patch` onto `el.style` each frame,
+ * writing ONLY the animated keys so any inline style the user set (e.g.
+ * `style={{ height: "100px" }}`) is preserved. The directive doesn't own the element's
+ * `style` prop, so a key both set goes to whichever wrote last: animate a key the
+ * element's `style` doesn't set, or use `wardic.*`, whose `style` gives up the keys
+ * Wardic holds.
+ *
+ * Directives run inside the component owner (Solid invokes them during render), so
+ * `runSpine`'s `createEffect` / `onCleanup` teardown is owner-scoped — the fibers
+ * are interrupted and the element is unregistered from the gate on element removal.
+ *
+ * CLIENT-ONLY (ADR-0003): `use:wardic` runs AFTER hydration, so the `initial` style
+ * is NOT applied during SSR / the pre-mount render — the element may flash before
+ * the first commit. For an SSR-correct initial (no flash), use `createWard`
+ * or `wardic.create` (their `style` carries the Starting style until the first commit).
+ *
+ * `use:wardic` resolves through the `wardic` import (`import { wardic } from
+ * "@wardic/solid"`): Solid's `use:` compiles to a bare `wardic(...)` reference. A
+ * local Ward can't shadow it, since a Ward is named after its element or `ward`
+ * (ADR-0042, the reason the directive isn't `use:wardic`).
+ */
+import { constVoid } from "effect/Function"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { createUniqueId, type Accessor, untrack } from "solid-js"
+import { useWardicGate, useWardicRuntime } from "./provider.tsx"
+import { controlledOf, runSpine, type SpineInternals } from "./create-ward.tsx"
+import { usePresenceContext } from "./presence.tsx"
+import { madeWith } from "./spine.ts"
+import type { WardConfig } from "./config.ts"
+import { createVariantNode } from "./variant-node.ts"
+import { useVariantContext } from "./variants.ts"
+
+/**
+ * A directive's body (`use:wardic`, `use:w`, #511): drive `el` through Wardic's motion spine, a
+ * Complete element or a Slim one as `internal` says.
+ *
+ * @param el the directive's host element (supplied by Solid).
+ * @param value the reactive config accessor (Solid wraps `use:wardic={config}` as `() => config`).
+ */
+export const runDirective = (el: HTMLElement, value: Accessor<WardConfig>, internal: SpineInternals): void => {
+  // The directive runs in a component owner, so it reads the nearest variant context
+  // (ADR-0007) and, as a Variant child, joins it (#50). It renders no children, so it
+  // provides none.
+  // Animation controls for its `animate` (#433): each change they make is its entry.
+  const { cfg, controls } = controlledOf(value)
+  const node = createVariantNode(cfg, useVariantContext(), UndefinedOr.map(controls, (c) => c.change))
+  // Under a presence, its element is told to it (#286): its `key`, and whether it's a twin.
+  const presence = usePresenceContext()
+  if (Predicate.isNotUndefined(presence)) madeWith(presence, constVoid, untrack(cfg))(el)
+  runSpine({
+    runtime: useWardicRuntime(),
+    gate: useWardicGate(),
+    id: createUniqueId(),
+    el: () => el,
+    cfg,
+    controls,
+    parent: node.inherited,
+    extraDelay: node.extraDelay,
+    byName: node.names,
+    canStart: node.canStart,
+    bindGestures: node.bindGestures,
+    onFrame: node.onFrame,
+    makeSink: (element) => ({ target: element }),
+    internal,
+  })
+}
+
+declare module "solid-js" {
+  // biome-ignore lint/style/useNamingConvention: augmenting Solid's JSX namespace.
+  namespace JSX {
+    interface Directives {
+      wardic: WardConfig
+      /** `use:w` (#511): a Slim element's directive. */
+      w: WardConfig
+    }
+  }
+}

package/src/drag-constraints.ts

@@ -0,0 +1,103 @@
+/**
+ * A drag's constraints as an app gives them (#273, ADR-0047), Solid-free: Motion's bounding box of
+ * numbers, or the container its box must stay inside, an accessor read at each measure, with Motion's
+ * `onMeasureDragConstraints`. Both bindings turn them into the drag track's: core's `Drag.Bounds`, or a
+ * container the track measures ({@link DragContainer}).
+ *
+ * @module
+ */
+import type * as Drag from "@wardic/core/Drag"
+import * as ProjectionSystem from "@wardic/dom/ProjectionSystem"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { constUndefined } from "effect/Function"
+import type { WardicTransformPoint } from "./config.ts"
+
+/** A box's edges, as Motion's `BoundingBox`: on x, `left` and `right`; on y, `top` and `bottom`. */
+export interface WardicBoundingBox {
+  readonly top: number
+  readonly right: number
+  readonly bottom: number
+  readonly left: number
+}
+
+/**
+ * `dragConstraints` (Motion's): the range of the element's x (`left` to `right`) and y
+ * (`top` to `bottom`), an edge left out unbounded; the container its box must stay inside, an accessor
+ * read at each measure (a drag's start, a resize of either); or `false`, none.
+ */
+export type WardicDragConstraints = false | Partial<WardicBoundingBox> | (() => Element | undefined)
+
+/** Motion's `onMeasureDragConstraints`: the bounds measured against the container in, its own out, or none to keep them. */
+export type WardicMeasureDragConstraints = (constraints: WardicBoundingBox) => WardicBoundingBox | undefined | void
+
+/**
+ * An element constraint, as the drag track takes it: its container, read at each measure, and the
+ * bounds measured against it, the app's `onMeasureDragConstraints` applied.
+ */
+export interface DragContainer {
+  readonly element: () => Element | undefined
+  readonly bounds: (container: Element) => Drag.Bounds
+}
+
+/** An axis range from its two edges, either left out. */
+const rangeOf = (min: number | undefined, max: number | undefined): Drag.AxisRange => ({
+  ...UndefinedOr.match(min, { onUndefined: () => ({}), onDefined: (edge) => ({ min: edge }) }),
+  ...UndefinedOr.match(max, { onUndefined: () => ({}), onDefined: (edge) => ({ max: edge }) }),
+})
+
+/** Motion's box as core's bounds: x from `left` to `right`, y from `top` to `bottom`. */
+export const boundsOfBox = (box: Partial<WardicBoundingBox>): Drag.Bounds => ({ x: rangeOf(box.left, box.right), y: rangeOf(box.top, box.bottom) })
+
+/** An edge of measured bounds, which has both. */
+const edge = (value: number | undefined): number => UndefinedOr.match(value, { onUndefined: () => 0, onDefined: (n) => n })
+
+/** A measured axis's two edges. */
+const edgesOf = (range: Drag.AxisRange | undefined): readonly [number, number] =>
+  UndefinedOr.match(range, { onUndefined: () => [0, 0] as const, onDefined: (r) => [edge(r.min), edge(r.max)] as const })
+
+/** Measured bounds as Motion's box, for `onMeasureDragConstraints`. */
+const boxOfBounds = (bounds: Drag.Bounds): WardicBoundingBox => {
+  const [left, right] = edgesOf(bounds.x)
+  const [top, bottom] = edgesOf(bounds.y)
+  return { left, right, top, bottom }
+}
+
+/** What a drag track takes from an element's `dragConstraints`. */
+export interface TrackConstraints {
+  readonly constraints?: Drag.Bounds | undefined
+  readonly container?: DragContainer | undefined
+}
+
+const NONE: TrackConstraints = {}
+
+/**
+ * The drag track's constraints from `dragConstraints`: Motion's box as bounds, or a container measured
+ * against `element`, `onMeasure` read at each measure.
+ */
+export const trackConstraintsOf = (
+  constraints: WardicDragConstraints | undefined,
+  element: HTMLElement,
+  onMeasure: () => WardicMeasureDragConstraints | undefined,
+  mapPoint: () => WardicTransformPoint | undefined = constUndefined,
+): TrackConstraints => {
+  if (Predicate.isUndefined(constraints)) return NONE
+  if (constraints === false) return NONE
+  if (Predicate.isFunction(constraints)) {
+    return {
+      container: {
+        element: constraints,
+        bounds: (container) => {
+          // Its boxes through the nearest config's `transformPagePoint` (#443), read at each measure.
+          const measured = ProjectionSystem.dragBoundsWithin(element, container, mapPoint())
+          return UndefinedOr.match(onMeasure(), {
+            onUndefined: () => measured,
+            onDefined: (adjust) =>
+              UndefinedOr.match(adjust(boxOfBounds(measured)) as WardicBoundingBox | undefined, { onUndefined: () => measured, onDefined: boundsOfBox }),
+          })
+        },
+      },
+    }
+  }
+  return { constraints: boundsOfBox(constraints) }
+}

package/src/drag-controls.ts

@@ -0,0 +1,94 @@
+/**
+ * **Drag controls** (#431, CONTEXT.md; Motion's `useDragControls`), Solid-free: controls made apart
+ * from any element and given to one or more, whose `start(event)` begins each one's drag from a
+ * pointer that went down elsewhere, a handle or a track. Both bindings export {@link createDragControls};
+ * each element's drag track subscribes while it's mounted.
+ *
+ * @module
+ */
+import * as Arr from "effect/Array"
+import { constVoid } from "effect/Function"
+import * as UndefinedOr from "effect/UndefinedOr"
+
+/** `controls.start`'s options, as Motion's. */
+export interface WardicDragControlsOptions {
+  /** Moves the element so its centre is under the pointer as the drag begins, on the axes it drags. Default `false`. */
+  readonly snapToCursor?: boolean | undefined
+  /** How far the pointer moves, in pixels, before the drag starts. Default 3. */
+  readonly distanceThreshold?: number | undefined
+}
+
+/**
+ * `createDragControls()`'s controls: give them to elements as `dragControls`, then start, stop or
+ * cancel their drags from anywhere.
+ */
+// #431, Motion's `DragControls`.
+export interface WardicDragControls {
+  /**
+   * Starts a drag on each element given these controls, from `event`, a pointer pressed elsewhere: call
+   * it from that pointer's `pointerdown`. Each follows the pointer as if it had been pressed itself,
+   * once the pointer has moved past the threshold. Of two elements given the same controls on one axis,
+   * only the first drags, unless the other has `dragPropagation`. One leaving an `<AnimatePresence>`
+   * doesn't start. Give the handle `touch-action: none`, or a touch on it scrolls the page.
+   */
+  // Each takes its Drag claim as any drag does (Motion's drag lock).
+  readonly start: (event: PointerEvent, options?: WardicDragControlsOptions) => void
+  /** Ends each drag as letting go of the pointer would: it carries on as released, and `onDragEnd` (Solid 2: `dragEnd`) is called. */
+  readonly stop: () => void
+  /**
+   * Ends each drag where it is: it doesn't carry on, `onDragEnd` isn't called, and `whileDrag` goes off.
+   * A `layout` element goes back to its place, as after any drag.
+   */
+  readonly cancel: () => void
+}
+
+/** What an element's drag track gives the controls it's subscribed to. */
+export interface ControlledDrag {
+  readonly start: (event: PointerEvent, options: WardicDragControlsOptions) => void
+  readonly stop: () => void
+  readonly cancel: () => void
+}
+
+/** Each controls' subscribed tracks. */
+// Module state (#460, Q7): each controls object's drags, held weakly by it.
+const subscribed = new WeakMap<WardicDragControls, Set<ControlledDrag>>()
+
+const NO_OPTIONS: WardicDragControlsOptions = {}
+
+/**
+ * Makes drag controls, which start an element's drag from somewhere else, such as a handle: give them
+ * to each element they drive as `dragControls`, on a `w.*` element, in a ward's config or on a
+ * `Reorder.Item`, and add `dragListener={false}` when a press on the element itself shouldn't drag it.
+ * Needs no owner. Motion's `useDragControls`.
+ *
+ * @example
+ * const controls = createDragControls()
+ * <div onPointerDown={(e) => controls.start(e)} style={{ "touch-action": "none" }}>handle</div>
+ * <w.div drag="x" dragControls={controls} dragListener={false} />
+ * @see https://wardic.dev/reference/solid/gestures/create-drag-controls
+ */
+// #431: made outside the elements they drive; each element's drag track subscribes while it's mounted.
+export const createDragControls = (): WardicDragControls => {
+  const tracks = new Set<ControlledDrag>()
+  // A track that subscribes or leaves while the controls call each is left out of that call.
+  const each = (call: (track: ControlledDrag) => void): void => Arr.forEach(Arr.fromIterable(tracks), call)
+  const controls: WardicDragControls = {
+    start: (event, options = NO_OPTIONS) => each((track) => track.start(event, options)),
+    stop: () => each((track) => track.stop()),
+    cancel: () => each((track) => track.cancel()),
+  }
+  subscribed.set(controls, tracks)
+  return controls
+}
+
+/** Subscribe a drag track to `controls` (internal): unsubscribed by the function it returns. Controls not made by {@link createDragControls} drive nothing. */
+export const subscribeDragControls = (controls: WardicDragControls, track: ControlledDrag): (() => void) =>
+  UndefinedOr.match(subscribed.get(controls), {
+    onUndefined: () => constVoid,
+    onDefined: (tracks) => {
+      tracks.add(track)
+      return () => {
+        tracks.delete(track)
+      }
+    },
+  })

package/src/drag-samples.ts

@@ -0,0 +1,54 @@
+/**
+ * A `createDrag` sensor's samples (ADR-0019), Solid-free (#209): the core drag watch shaped by the
+ * sensor's options, for both bindings' `createDrag` (#379).
+ *
+ * @module
+ */
+import * as Drag from "@wardic/core/Drag"
+import type * as InputFeed from "@wardic/core/InputFeed"
+import type * as InputSource from "@wardic/core/InputSource"
+import * as DragRecognizer from "@wardic/core/DragRecognizer"
+import type * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
+import * as UndefinedOr from "effect/UndefinedOr"
+import type { WardicTransformPoint } from "./config.ts"
+import { pointMapOptionOf } from "./wardic-config-value.ts"
+
+/** The axis, claim and bounds options for {@link createDrag}. */
+export interface CreateDragOptions {
+  /** Keeps the drag to one axis, `"x"` or `"y"`: the other reads 0, and only that axis is taken. */
+  readonly axis?: "x" | "y"
+  /**
+   * `false`: takes no drag from the element, so watching a drag over an area blocks no draggable
+   * inside it, and a draggable inside it blocks nothing here. Default `true`.
+   */
+  // A Drag claim (ADR-0019, *Amendment (#29)*).
+  readonly claim?: boolean
+  /** Keeps `offset` within bounds, each axis's `min` and `max` in pixels: `{ x: { min: 0, max: 200 } }`. */
+  readonly bounds?: Drag.Bounds
+  /** How far `offset` can be pulled past `bounds`: 0 stops it at them (the default), 1 lets it go freely. */
+  readonly elastic?: number
+}
+
+/**
+ * Watch a drag's samples (#379): the core drag watch on `target` with `options`' axis and claim, each
+ * sample kept within `bounds` when present (`Drag.within`, the off-axis zeroed before clamping), told
+ * to `handlers.on` inside its pointer event, for both bindings' `createDrag`. Its points through
+ * `mapPoint`, its nearest `WardicConfig`'s `transformPagePoint` read at each down (#443).
+ */
+export const watchDragSamples = (
+  target: unknown,
+  options: CreateDragOptions,
+  handlers: InputFeed.Handlers<Drag.Sample>,
+  mapPoint?: () => WardicTransformPoint | undefined,
+): Effect.Effect<void, never, Scope.Scope | InputSource.InputSource> => {
+  const { axis = "xy", claim = true } = options
+  const on = UndefinedOr.match(options.bounds, {
+    onUndefined: () => handlers.on,
+    onDefined: (bounds) => {
+      const kept = Drag.within(bounds, UndefinedOr.map(options.elastic, (elastic) => ({ elastic })))
+      return (sample: Drag.Sample) => handlers.on(kept(sample))
+    },
+  })
+  return DragRecognizer.watchDrag(target, { axis, claim, mapPoint: UndefinedOr.map(mapPoint, pointMapOptionOf) }, { ...handlers, on })
+}

package/src/drag-sensor.ts

@@ -0,0 +1,46 @@
+/**
+ * `createDrag` (#548): in a module of its own, so it brings the `drag` Feature only to an app that uses it,
+ * and on the pages that do (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import type * as Drag from "@wardic/core/Drag"
+import * as InputSource from "@wardic/core/InputSource"
+import * as Effect from "effect/Effect"
+import type { Accessor } from "solid-js"
+import { watchToSignal } from "./bridge.ts"
+import { type CreateDragOptions, watchDragSamples } from "./drag-samples.ts"
+import type { Feature } from "./feature.ts"
+import { drag } from "./features/drag.ts"
+import { inputIn } from "./gesture-features.ts"
+import { useBrought } from "./provider.tsx"
+import { useWardicConfig } from "./wardic-config.tsx"
+import { transformPagePointOf } from "./wardic-config-value.ts"
+
+/** What it brings (ADR-0067 decision 12): its gesture's Feature, whatever its section has (#511). */
+const DRAG: ReadonlyArray<Feature> = [drag]
+
+/**
+ * The latest sample of a drag on `target`, `null` before the first: where the pointer is, how far it
+ * has come, its velocity, and the gesture's `phase`. It moves nothing: it reports, for a drag that
+ * drives something else, such as a slider's value. `target` is the element itself, so call it where
+ * it exists. Like an element's own drag, it takes the element's drag while a gesture is on, unless
+ * `claim: false`.
+ *
+ * @example
+ * const drag = createDrag(props.track, { axis: "x" })
+ * const value = () => (drag()?.offset.x ?? 0) / 2
+ * @see https://wardic.dev/reference/solid/gestures/create-drag
+ */
+// The core drag watch (#379), each sample kept within `bounds` when given. It holds `target`'s Drag
+// claim while a gesture is on, shared with every other drag on it; refused one, it gets no samples for
+// that gesture.
+export const createDrag = (target: unknown, options?: CreateDragOptions): Accessor<Drag.Sample | null> => {
+  // Its points through the nearest WardicConfig's `transformPagePoint` (#443), read at each down.
+  const pagePoint = transformPagePointOf(useWardicConfig())
+  const services = useBrought(DRAG)
+  return watchToSignal<Drag.Sample | null>(
+    (handlers) => Effect.provideService(watchDragSamples(target, { ...options }, handlers, pagePoint), InputSource.InputSource, inputIn(services())),
+    null,
+  )
+}