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

package/src/arc.ts

@@ -0,0 +1,34 @@
+/**
+ * `arc()` (#438, Motion's): a curved Path for a transition's `path`, `x` and `y` travelling along it
+ * together. Solid-free, on both bindings.
+ *
+ * @module
+ */
+import * as Arc from "@wardic/core/Arc"
+import type { WardicPath } from "./config.ts"
+
+/** `arc()`'s options (Motion's `ArcOptions`). */
+export interface WardicArcOptions {
+  /** How far it bulges off the straight line, as a share of the distance: `1` peaks at the whole distance. Default 0.5. */
+  readonly strength?: number
+  /** Where along the way (0–1) it's highest. Default 0.5. */
+  readonly peak?: number
+  /** The side it bulges to, turning with the direction of travel. Left out, it keeps to one side of the screen. */
+  readonly direction?: "cw" | "ccw"
+  /** Whether it turns the element to follow the curve: `true` all the way, a number 0–1 that share of it. */
+  readonly rotate?: boolean | number
+}
+
+/**
+ * A curved path for a transition: `x` and `y` travel along a curve between where they start and their
+ * target, on `x`'s transition, in place of two straight lines. Make it once, in a component's body or
+ * at module level: with no `direction`, it remembers which side of the screen it bulged to. Motion's
+ * `arc()`.
+ *
+ * @example
+ * const path = arc({ strength: 0.4, rotate: true })
+ * <w.div animate={{ x: 200, y: 80 }} transition={{ path, duration: 0.6 }} />
+ * @see https://wardic.dev/reference/solid/transitions/arc
+ */
+// #438.
+export const arc = (options: WardicArcOptions = {}): WardicPath => Arc.make(options)

package/src/bridge.ts

@@ -0,0 +1,98 @@
+/**
+ * Reactive bridges (ADR-0006): the two adapters that turn Effect-side reactive
+ * sources into Solid `Accessor`s the JSX layer can read.
+ *
+ * - {@link streamToSignal} bridges a core frame/recognizer `Stream` into a Solid
+ *   signal: a fiber forked on the provider runtime runs `Stream.runForEach`,
+ *   pushing each emission into the signal. The fiber is scoped to the consuming
+ *   component's `onCleanup` (via {@link runScoped}), so unmount interrupts it,
+ *   tears down its Scope, and drops the ref-count on the Shared sources it
+ *   subscribed to — exactly the per-element fiber lifecycle ADR-0006 prescribes.
+ * - {@link fromAtom} bridges an Effect `Atom` (reactive service inputs like
+ *   `Probe.prefersReducedMotion` / `Probe.viewport`) into a Solid signal via the
+ *   provider runtime's `AtomRegistry`: it reads the atom's current value for the
+ *   initial signal, subscribes to push updates, and unsubscribes on `onCleanup`.
+ *
+ * Both MUST be called within a Solid owner (component body / `createRoot`) —
+ * they register `onCleanup` and read the runtime from context.
+ */
+import type * as InputFeed from "@wardic/core/InputFeed"
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import { AtomRegistry, type Atom } from "effect/reactivity"
+import { type Accessor, createSignal, from, onCleanup, onMount } from "solid-js"
+import { runScoped, runWatch, useWardicRuntime } from "./provider.tsx"
+import type { WardicServices } from "./runtime.ts"
+import { isHydrating, isServer } from "./server.ts"
+
+/**
+ * A core `Stream` as an accessor: `initial` until its first value, then its latest, the stream run on
+ * the provider's runtime until the owner is cleaned up. Call it where you'd make a signal.
+ *
+ * @example
+ * const point = streamToSignal(pointerMoves, { x: 0, y: 0 })
+ * @see https://wardic.dev/reference/solid/advanced/bridges
+ */
+// `Stream.runForEach` through `runScoped`; `set(() => v)`, so an object or function value is stored as
+// it is. The stream's `R` is the provider runtime's services.
+export const streamToSignal = <A>(
+  stream: Stream.Stream<A, never, WardicServices>,
+  initial: A,
+): Accessor<A> => {
+  const [get, set] = createSignal(initial)
+  const runtime = useWardicRuntime()
+  runScoped(
+    runtime,
+    Stream.runForEach(stream, (v) => Effect.sync(() => set(() => v))),
+  )
+  return get
+}
+
+/**
+ * A gesture watch's values as a Solid `Accessor` (#318, ADR-0055): `initial` until the first, the
+ * watch run with {@link runWatch} (a Scope of its own, closed with the owner; a handler's throw
+ * reported). Must be called within a Solid owner under a `WardicProvider`.
+ */
+export const watchToSignal = <A>(
+  watchOf: (handlers: InputFeed.Handlers<A>) => Effect.Effect<void, never, Scope.Scope | WardicServices>,
+  initial: A,
+): Accessor<A> => {
+  const [get, set] = createSignal(initial)
+  runWatch(useWardicRuntime(), (onDefect) => watchOf({ on: (value) => set(() => value), onDefect }))
+  return get
+}
+
+/**
+ * An Effect `Atom` as an accessor: read through the provider's `AtomRegistry`, and followed until the
+ * owner is cleaned up. For a server render, give `serverValue`: the server renders it, and a hydrating
+ * page keeps it until mount, then follows the atom.
+ *
+ * @example
+ * const visible = fromAtom(probe.pageVisible, { serverValue: true })
+ * @see https://wardic.dev/reference/solid/advanced/bridges
+ */
+// Solid's `from`, seeded with the atom's value; `set(() => v)`, so an object or function value is stored
+// as it is. A server builds no registry (ADR-0021); the Hydration hold is decision 8.
+export const fromAtom = <A>(atom: Atom.Atom<A>, options?: { readonly serverValue?: A }): Accessor<A> => {
+  const runtime = useWardicRuntime()
+  const held = Predicate.isNotUndefined(options) && "serverValue" in options
+  if (held && isServer) {
+    const serverValue = options.serverValue as A
+    return () => serverValue
+  }
+  if (held && isHydrating()) {
+    const [value, setValue] = createSignal<A>(options.serverValue as A)
+    onMount(() => {
+      const registry = runtime.runSync(AtomRegistry.AtomRegistry)
+      setValue(() => registry.get(atom))
+      onCleanup(registry.subscribe(atom, (v) => setValue(() => v)))
+    })
+    return value
+  }
+  // A `Context.Service` key is itself an `Effect<Shape, never, Identifier>`,
+  // so running it on the provider runtime yields the registry instance.
+  const registry = runtime.runSync(AtomRegistry.AtomRegistry)
+  return from<A>((set) => registry.subscribe(atom, (v) => set(() => v)), registry.get(atom))
+}

package/src/complete.ts

@@ -0,0 +1,45 @@
+/**
+ * The **Complete element**'s own code (#511, ADR-0067; #548): what tells the spine it brings every
+ * Feature, and `createWard`, the Complete ward. In a module of its own, apart from the spine every
+ * element shares, so an app whose pages use the Slim element (`w.*`) ships no Feature from here, even
+ * when one of them uses a Complete element (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import type { Accessor } from "solid-js"
+import type { WardConfig, WardicVariantLabels } from "./config.ts"
+import { createWardWith, type SpineInternals, type Ward } from "./create-ward.tsx"
+import { ALL } from "./features/all.ts"
+import type { InferredMotion, TargetKey } from "./ward-keys.ts"
+
+/**
+ * Makes a ward: Wardic's motion for an element of your own. Spread what it returns on the element,
+ * `{...card()}`, or `{...card({ ref, style })}` to keep your own. `config` is the motion props, or an
+ * accessor of them for a config that changes. `card.value(key)` reads what the element shows. This
+ * one has every Feature; `w.createWard` has its section's.
+ *
+ * @example
+ * const card = createWard({ initial: { opacity: 0 }, animate: { opacity: 1 } })
+ * <article {...card()} />
+ * @see https://wardic.dev/reference/solid/elements/ward
+ */
+// One element's motion binding (ADR-0042), owning computations under the current owner. An accessor
+// config is read reactively (a change Retargets, velocity kept); `initial` once at setup (ADR-0003).
+// Its keys are inferred from its targets (#305, InferredMotion), so `transition` takes entries for
+// them. A Complete element (#511).
+export function createWard<
+  K extends TargetKey = never,
+  N extends string = never,
+  LI extends WardicVariantLabels = never,
+  LA extends WardicVariantLabels = never,
+  D extends boolean | "x" | "y" = never,
+>(config: InferredMotion<WardConfig, K, N, LI, LA, D> | Accessor<InferredMotion<WardConfig, K, N, LI, LA, D>>): Ward {
+  return createWardWith(config as WardConfig | Accessor<WardConfig>, COMPLETE)
+}
+
+/**
+ * What a **Complete element** tells the spine (#511, ADR-0067): it brings every Feature. Its forms'
+ * (`createWard`, `wardic.*`, `wardic.create`, `use:wardic`) alone: a Slim element's never name it, so
+ * its app ships no Feature it doesn't choose.
+ */
+export const COMPLETE: SpineInternals = { brings: ALL, complete: true }