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

package/src/unstable/v2/sensors.ts

@@ -0,0 +1,169 @@
+/**
+ * Sensors on Solid 2 (#209 PR 3's Q1): each is a ref that's also its reading, as a ward is a ref
+ * carrying its props. Give it to an element's `ref` (alone, or in an array beside a ward); call it
+ * with nothing to read it, tracked as any signal:
+ *
+ * ```tsx
+ * const hovered = createHover()
+ * <div ref={hovered}>{hovered() ? "in" : "out"}</div>
+ * ```
+ *
+ * Each wraps a core recognizer (ADR-0006): attached, it runs on the provider's runtime until the
+ * sensor's owner is disposed or it's given another element. Each is a watch (#318, #379, ADR-0055),
+ * in a Scope of its own with no fiber. Its value starts at its rest (`false`,
+ * or `null` for a drag) and stays there on a server, where no ref is called. `createReducedMotion`,
+ * `createReducedMotionConfig` and `createPageInView` take no element: they follow the Probe's
+ * preference, the nearest config's setting over it, and the page's visibility (#443).
+ *
+ * @module
+ */
+import type * as InputFeed from "@wardic/core/InputFeed"
+import * as Probe from "@wardic/core/Probe"
+import * as Recognizer from "@wardic/core/Recognizer"
+import * as ReducedMotion from "@wardic/core/ReducedMotion"
+import * as Report from "@wardic/dom/Report"
+import type * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Scope from "effect/Scope"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { isServer } from "@solidjs/web"
+import { type Accessor, createSignal, onCleanup } from "solid-js"
+import type { WardicViewport } from "../../config.ts"
+import { inViewOptionsOf } from "../../gesture-callbacks.ts"
+import * as OwnerScope from "../../owner-scope.ts"
+import type { WardicServices } from "../../runtime.ts"
+import { fromAtom } from "./bridge.ts"
+import { useWardicReducedMotionSetting, useWardicRuntime } from "./provider.tsx"
+
+export type { CreateDragOptions } from "../../drag-samples.ts"
+
+/**
+ * A sensor: give it to an element's `ref` (alone, or in an array beside a ward), and call it with
+ * nothing to read it, tracked as any signal. Given another element, it follows that one.
+ */
+export interface Sensor<A> {
+  /** Its reading, tracked. */
+  (): A
+  /** Attach it to `element`: Solid calls it as a ref. */
+  (element: Element): void
+}
+
+/** Whether a sensor's call is Solid applying it as a ref. */
+const isElement = (value: unknown): value is Element => Predicate.hasProperty(value, "nodeType")
+
+
+/**
+ * A sensor of a watch's values (#318, ADR-0055), at `initial` until its first: attached, the watch
+ * runs in a Scope of its own, closed when the sensor is given another element or its owner is
+ * disposed. Call within an owner.
+ */
+export const watchSensorOf = <A>(
+  watchOf: (target: Element, handlers: InputFeed.Handlers<A>) => Effect.Effect<void, never, Scope.Scope | WardicServices>,
+  initial: A,
+): Sensor<A> => {
+  // A server never calls a ref: the sensor rests where it starts.
+  if (isServer) return ((): A => initial) as Sensor<A>
+  const runtime = useWardicRuntime()
+  const [value, setValue] = createSignal<A>(initial as Exclude<A, Function>)
+  // The element it's attached to, and its watch's Scope there.
+  let attached: { readonly element: Element; readonly scope: Scope.Closeable } | undefined
+  const detach = (): void => {
+    UndefinedOr.map(attached, ({ scope }) => OwnerScope.close(runtime, scope, "wardic.sensor: a finalizer failed"))
+    attached = undefined
+  }
+  onCleanup(detach)
+  const onDefect = (cause: Cause.Cause<never>): void => {
+    runtime.runFork(Report.failure("wardic.sensor: a gesture handler failed", cause))
+  }
+  const attach = (element: Element): void => {
+    if (Predicate.isNotUndefined(attached) && attached.element === element) return
+    detach()
+    // Attached before its watch starts, so one that throws as it subscribes is closed all the same (#618).
+    const scope = OwnerScope.open(runtime)
+    attached = { element, scope }
+    runtime.runSync(watchOf(element, { on: (next) => setValue(() => next as Exclude<A, Function>), onDefect }).pipe(Scope.provide(scope)))
+  }
+  // eslint-disable-next-line solid/reactivity -- the sensor: a ref Solid calls with its element, and an accessor its caller reads where it tracks
+  return ((element?: unknown): A | undefined => {
+    if (isElement(element)) {
+      attach(element)
+      return undefined
+    }
+    return value()
+  }) as Sensor<A>
+}
+
+/**
+ * `true` while the element it's given to as a `ref` is in view, `false` otherwise. What "in view"
+ * means is a `viewport`'s, as on a Wardic element: `root`, a scrolling container (the window if none);
+ * `margin`, grown around it, as CSS `rootMargin`; `amount` of the element that must show, `"some"`,
+ * `"all"` or 0 to 1; and `once`, to stay `true` after the first entry. `root` is read as it's
+ * attached: an ancestor's `ref`, which Solid applies before its children's, has it by then. Motion's
+ * `useInView`.
+ *
+ * @example
+ * const visible = createInView({ amount: "all", once: true })
+ * <section ref={visible}>{visible() ? "Seen" : "Not yet"}</section>
+ * @see https://wardic.dev/reference/solid/gestures/create-in-view
+ */
+// The core in-view watch, its options mapped as the element's `viewport` is (#273): `root` read as
+// it's attached.
+export const createInView = (viewport?: WardicViewport): Sensor<boolean> =>
+  watchSensorOf<boolean>(
+    (target, { on, onDefect }) => Recognizer.watchInView(target, inViewOptionsOf(viewport), { on: (transition) => on(transition.active), onDefect }),
+    false,
+  )
+
+/**
+ * Whether the visitor's system asks for reduced motion, as an accessor. A server renders `false`, and a
+ * hydrating page keeps it until it has mounted, so markup that depends on it hydrates. Wardic's
+ * animations honour the setting either way. Motion's `useReducedMotion`, which gives `null` on a server.
+ *
+ * @example
+ * const reduced = createReducedMotion()
+ * <Show when={!reduced()} fallback={<img src={still} />}><video autoplay src={clip} /></Show>
+ * @see https://wardic.dev/reference/solid/utilities/create-reduced-motion
+ */
+// The Probe's `prefersReducedMotion` Atom, held until mount (the Hydration hold, ADR-0021 decision 8).
+// The engine reads the preference as each animation starts, and snaps its positional keys (ADR-0029).
+export const createReducedMotion = (): Accessor<boolean> => {
+  if (isServer) return () => false
+  const probe = useWardicRuntime().runSync(Probe.Probe)
+  return fromAtom(probe.prefersReducedMotion, { serverValue: false })
+}
+
+/**
+ * Whether reduced motion applies here, as Wardic's animations here honour it: the nearest
+ * `WardicConfig`'s `reducedMotion`, else the provider's, over the visitor's setting. `"always"` is
+ * `true`, `"never"` `false`, and `"user"` follows the system. A server renders `"always"` as `true` and
+ * the rest as `false`, kept until the page has mounted. Motion's `useReducedMotionConfig`.
+ *
+ * @example
+ * const reduced = createReducedMotionConfig()
+ * const path = () => (reduced() ? undefined : arc())
+ * @see https://wardic.dev/reference/solid/utilities/create-reduced-motion
+ */
+// #443; tracked since #584.
+export const createReducedMotionConfig = (): Accessor<boolean> => {
+  const setting = useWardicReducedMotionSetting()
+  const prefers = createReducedMotion()
+  return () => ReducedMotion.applies(setting(), prefers())
+}
+
+/**
+ * Whether the page is shown: `false` while it's hidden, in a tab in the background or a minimised
+ * window. Pause what nobody can see, such as a carousel's autoplay. A server renders `true`, and a
+ * hydrating page keeps it until it has settled. Motion's `usePageInView`.
+ *
+ * @example
+ * const visible = createPageInView()
+ * createEffect(visible, (shown) => (shown ? player.play() : player.pause()))
+ * @see https://wardic.dev/reference/solid/gestures/create-page-in-view
+ */
+// #443, the Probe's `pageVisible`, held until settled (the Hydration hold).
+export const createPageInView = (): Accessor<boolean> => {
+  if (isServer) return () => true
+  const probe = useWardicRuntime().runSync(Probe.Probe)
+  return fromAtom(probe.pageVisible, { serverValue: true })
+}

package/src/unstable/v2/solid-reactivity.ts

@@ -0,0 +1,69 @@
+/**
+ * Solid 2's {@link Reactivity}, for the Solid-free modules the Solid 2 binding runs (#209), made
+ * per ward under its owner.
+ *
+ * - A trigger's signal is written where Solid 2 allows a write: the flush gate's hooks, an effect's
+ *   apply, an event. No internal signal is written in an owned scope but four, which say why
+ *   (`ownedWrite`, #257's audit; checked again in #618): a Variant child's registration, the gesture
+ *   states a ward binds to its variant node at setup, a ward given its element in a component's body,
+ *   and a ward given its `.with()` props in a spread's run (#264).
+ * - A watch is an effect in a root of its own under the ward's owner, so it ends with the ward, or
+ *   at its stop. Not under the computation it's made in: Solid 2 disposes a root with the
+ *   computation it's made in (a 1.x root outlived it), and a `style` re-run must not end a Live
+ *   value's watch. Nor detached: Solid 2 refuses a root with no owner inside an effect's apply,
+ *   where a ward mounts.
+ *
+ * @module
+ */
+import { createEffect, createRoot, createSignal, createTrackedEffect, type Owner, runWithOwner, untrack } from "solid-js"
+import type { Reactivity } from "../../reactivity.ts"
+
+/**
+ * The options of every computation the binding makes (#209 PR 4a): transparent to Solid 2's
+ * hydration ids. A memo or an effect otherwise takes its owner's next child id, and adopts the
+ * server's serialized value while hydrating; the binding makes them on the client only (a server
+ * ward is lean, ADR-0021), so the client's later ids would miss the server's markup.
+ */
+export const CLIENT_ONLY = { transparent: true } as const
+/** {@link CLIENT_ONLY}, deferred: an effect that skips its first run. */
+export const CLIENT_ONLY_DEFERRED = { transparent: true, defer: true } as const
+
+/**
+ * {@link CLIENT_ONLY} for a computation whose compute builds the value it returns, so it never
+ * returns a promise: Solid 2 skips its check of each result's shape (`sync`, which it documents for
+ * library code that returns sync values). Never for one that returns a value it was given, which an
+ * app may make a promise of, and never for a waiter (`lifecycle.ts`), which returns one by design.
+ */
+// #618 (M2): a computation returning an object paid `handleAsync`'s probe each run (rc.20), 15-55 ns.
+export const CLIENT_ONLY_SYNC = { transparent: true, sync: true } as const
+/** {@link CLIENT_ONLY_SYNC}, deferred: an effect that skips its first run. */
+export const CLIENT_ONLY_SYNC_DEFERRED = { transparent: true, sync: true, defer: true } as const
+
+const SETTLED = { name: "onSettled", ...CLIENT_ONLY }
+
+/**
+ * `onSettled` for client-only code (#209 PR 4b): Solid 2's own, a tracked effect running `callback`
+ * untracked once the render has settled, made {@link CLIENT_ONLY}. Solid's takes a hydration id,
+ * and a server's `onSettled` takes the same one, but code that runs on the client only has no server
+ * call to take it: the keys after it would miss the server's markup. A tracked effect's declared
+ * options are only `name`; it passes them to its node, as every computation does, which reads
+ * `transparent` (`@solidjs/signals` rc.15 to rc.18, dev and prod builds).
+ */
+export const onSettledClientOnly = (callback: () => void | (() => void)): void => createTrackedEffect(() => untrack(callback), SETTLED)
+
+/** Solid 2's reactive primitives, a watch made under `owner`. */
+export const reactivityIn = (owner: Owner | null): Reactivity => ({
+  untrack,
+  trigger: () => {
+    const [track, notify] = createSignal<undefined>(undefined, { equals: false })
+    return { track, notify: () => void notify(undefined) }
+  },
+  watch: (accessor, onChange) =>
+    runWithOwner(owner, () =>
+      createRoot((dispose) => {
+        createEffect(accessor, (value) => {
+          onChange(value)
+        }, CLIENT_ONLY_DEFERRED)
+        return dispose
+      }, CLIENT_ONLY)),
+})