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

package/src/unstable/v2/presence-hooks.ts

@@ -0,0 +1,157 @@
+/**
+ * Motion's presence hooks on Solid 2 (#277's PR 5b, ADR-0048), in the shape #257 settled on: async
+ * values, no callbacks. Each is given to `ref`, which ties it to the child that holds its element.
+ *
+ * - `usePresence()` holds the leaving child until `safeToRemove()`; `next("leave")` resolves as it
+ *   leaves, once its node is back in place, with the presence's `custom`. The child's own code is
+ *   disposed by then: what runs after the `await` is plain work that ends by calling `safeToRemove()`.
+ * - `useIsPresent()` is a sensor: `true`, `false` from its child's leave on, for what still runs on
+ *   the retained node.
+ * - `usePresenceData()` is the presence's `custom`.
+ *
+ * @module
+ */
+import { isServer } from "@solidjs/web"
+import { constUndefined } from "effect/Function"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { type Accessor, createSignal } from "solid-js"
+import { usePresenceContext } from "./presence.tsx"
+import { eachOf, Waiters } from "./waiters.ts"
+
+/** What a `usePresence` handle waits for. */
+export interface PresenceLeaveEvents {
+  /** Its child left: the presence's `custom`. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly leave: any
+}
+
+/** A `usePresence` handle, your own exit: see the module. */
+// `PresenceExit`, not `PresenceHold`: the glossary's **Hold** is a stretch of a run (#618, P1).
+export interface PresenceExit {
+  /** Given to `ref`: the element whose child it holds. */
+  (element: Element): void
+  /** Whether its child is present: `false` from its leave on. */
+  readonly isPresent: Accessor<boolean>
+  /** A promise of its child's leave, with the presence's `custom`: rejected if the child or the presence goes some other way. */
+  readonly next: <E extends keyof PresenceLeaveEvents>(name: E) => Promise<PresenceLeaveEvents[E]>
+  /** Each leave from the call on, for `for await`. */
+  readonly each: <E extends keyof PresenceLeaveEvents>(name: E) => AsyncIterable<PresenceLeaveEvents[E]>
+  /** Let its child go: once it's left; before, nothing. */
+  readonly safeToRemove: () => void
+}
+
+/** `useIsPresent`'s sensor: read for whether its child is present, given to `ref` for its element. */
+export interface IsPresent {
+  (): boolean
+  (element: Element): void
+}
+
+/** The `AbortError`'s message for a `next("leave")` its child or presence cut off. */
+const GONE = "The child went before it left its presence."
+
+/** Whether a call is Solid applying the handle as a ref. */
+const isElement = (value: unknown): value is Element => Predicate.hasProperty(value, "nodeType")
+
+/** A registration with the nearest presence, `isPresent` turning `false` at its child's leave. */
+const watchOf = (
+  holds: boolean,
+  onLeave: (custom: unknown, release: () => void) => void,
+  onGone: () => void,
+): { readonly present: Accessor<boolean>; readonly attach: (element: Element) => void } => {
+  const [present, setPresent] = createSignal(true)
+  let element: Element | undefined
+  UndefinedOr.map(usePresenceContext(), (presence) =>
+    UndefinedOr.map(presence.watch, (watch) =>
+      watch({
+        element: () => element,
+        holds,
+        leave: (custom, release) => {
+          setPresent(false)
+          onLeave(custom, release)
+        },
+        gone: onGone,
+      })))
+  return {
+    present,
+    attach: (at) => {
+      element = at
+    },
+  }
+}
+
+/**
+ * Holds a child of `<AnimatePresence>` on the page as it leaves, until you call `safeToRemove()`: for
+ * an exit of your own, such as a Web Animation. Give it to `ref` on an element in the child. Its
+ * `next("leave")` resolves as the child leaves; `isPresent()` is `false` from then on. Motion's
+ * `usePresence`.
+ *
+ * @example
+ * const exit = usePresence()
+ * void exit.next("leave").then(() => setTimeout(exit.safeToRemove, 300))
+ * <div ref={exit} />
+ * @see https://wardic.dev/reference/solid/presence/use-presence
+ */
+// The child's own code is disposed by the time it leaves: what runs after the await is plain work that
+// ends with safeToRemove(). Outside a presence it's always present, and next("leave") never settles.
+export const usePresence = (): PresenceExit => {
+  if (isServer) return SERVER_EXIT
+  const waiters = new Waiters<PresenceLeaveEvents>(GONE)
+  let release: () => void = () => {}
+  const { present, attach } = watchOf(
+    true,
+    (custom, done) => {
+      release = done
+      waiters.tell("leave", () => custom)
+    },
+    () => waiters.dispose(),
+  )
+  const hold = ((element: Element): void => {
+    attach(element)
+  }) as PresenceExit
+  Object.defineProperties(hold, {
+    isPresent: { value: present },
+    next: { value: <E extends keyof PresenceLeaveEvents>(name: E) => waiters.wait(name) },
+    each: { value: <E extends keyof PresenceLeaveEvents>(name: E) => eachOf<PresenceLeaveEvents, E>(waiters, name) },
+    safeToRemove: { value: () => release() },
+  })
+  return hold
+}
+
+/**
+ * Whether a child of `<AnimatePresence>` is still present: `false` from its leave on, while its exit
+ * plays. Give it to `ref` on an element in the child, and call it to read. Outside a presence, always
+ * `true`. Motion's `useIsPresent`.
+ *
+ * @example
+ * const present = useIsPresent()
+ * <button ref={present} disabled={!present()}>Save</button>
+ * @see https://wardic.dev/reference/solid/presence/use-is-present
+ */
+export const useIsPresent = (): IsPresent => {
+  if (isServer) return (() => true) as IsPresent
+  const { present, attach } = watchOf(false, () => {}, () => {})
+  // 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): boolean | undefined => {
+    if (isElement(element)) {
+      attach(element)
+      return undefined
+    }
+    return present()
+  }) as IsPresent
+}
+
+/** Motion's `usePresenceData`: the nearest presence's `custom`, `undefined` outside one. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export const usePresenceData = <T = any,>(): Accessor<T | undefined> => {
+  const presence = usePresenceContext()
+  return () => UndefinedOr.map(UndefinedOr.map(presence, (p) => p.data), (data) => data()) as T | undefined
+}
+
+/** A server's hold: nothing leaves there. */
+const SERVER_EXIT: PresenceExit = Object.defineProperties((() => {}) as unknown as PresenceExit, {
+  isPresent: { value: () => true },
+  next: { value: (): Promise<never> => new Promise<never>(constUndefined) },
+  each: { value: () => ({ [Symbol.asyncIterator]: () => ({ next: () => Promise.resolve({ value: undefined, done: true as const }) }) }) },
+  safeToRemove: { value: () => {} },
+})

package/src/unstable/v2/presence.tsx

@@ -0,0 +1,174 @@
+/**
+ * `<AnimatePresence>` on Solid 2 (#209, ADR-0007): exit-before-unmount for its children (many since
+ * #277, ADR-0048), and `mode="wait"`, as the Solid 1 binding's. Its work (each retained node, its parent-driven exit,
+ * the twins it hands back) is Solid-free, in `presence-controller.ts`. What's Solid 2's:
+ *
+ * - **The children are resolved with `children()`** under the presence's context, so each child's
+ *   ward registers its exit record with it.
+ * - **An effect tells the controller which elements are present,** in its apply: after Solid 2's
+ *   flush has applied the change, the leaving nodes removed. The controller puts them back before
+ *   the flush ends, so no paint shows them gone.
+ * - **Once settled** (`onSettledClientOnly`), the first render has ended, for `initial={false}` (#134).
+ *
+ * @module
+ */
+import { isServer, type JSX } from "@solidjs/web"
+import * as Bool from "effect/Boolean"
+import { constUndefined } from "effect/Function"
+import * as Option from "effect/Option"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { children, createContext, createEffect, createMemo, createSignal, onCleanup, untrack, useContext } from "solid-js"
+import { makePresence, type PresenceMode, propagateTo } from "../../presence-controller.ts"
+import type { PresenceContextValue } from "../../presence-record.ts"
+import { useBuiltProjection, useWardicDefaultTransition, useWardicPositionalKeys, useWardicReducedMotion, useWardicRenderer, useWardicRuntime } from "./provider.tsx"
+import { CLIENT_ONLY, onSettledClientOnly } from "./solid-reactivity.ts"
+import { hasRef, makePresenceHandle, type Presence, serverPresenceHandle } from "./presence-handle.ts"
+
+/**
+ * The nearest `<AnimatePresence>`'s registrar, `null` outside one: Solid 2 takes an `undefined`
+ * default for none and then throws in `useContext`.
+ */
+export const PresenceContext = createContext<PresenceContextValue | null>(null)
+
+/** The nearest `<AnimatePresence>`'s registrar, `undefined` outside one. */
+export const usePresenceContext = (): PresenceContextValue | undefined => Option.getOrUndefined(Option.fromNullishOr(useContext(PresenceContext)))
+
+/** {@link AnimatePresence}'s props. */
+export interface AnimatePresenceProps {
+  readonly children?: JSX.Element
+  /**
+   * `false`: the child present at this presence's first render starts at its `animate`, with no
+   * enter animation (it and every Wardic element under it, as Motion's); a child that enters later
+   * animates in from its `initial`. Exits are unchanged.
+   */
+  readonly initial?: boolean
+  /**
+   * Its exits, heard: a `createPresence()` handle, or a callback handed the
+   * presence's own handle. Optional: left out, no handle is made. Read once.
+   */
+  readonly ref?: ((presence: Presence) => void) | undefined
+  /**
+   * How a child enters while another exits, Motion's `mode`: `"sync"` (the default),
+   * at once, beside the leaver; `"popLayout"`, at once, the leaver popped out of the flow where it was
+   * (`position: absolute`, its size kept), so the children after it take their places, a `layout`
+   * one animating there; `"wait"`, once every leaver has animated out and been removed. A
+   * waiting child is built at once, as Solid builds it, so its own code (its effects included) runs
+   * then, off the page; its Wardic elements start once it's on the page.
+   */
+  readonly mode?: PresenceMode | undefined
+  /**
+   * What a leaving child's dynamic `exit` resolves with (Motion's `custom`), over the
+   * child's own `custom`: a child that has left can't take new props, so the presence hands it the
+   * latest. Read as each child leaves.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readonly custom?: any
+  /**
+   * Where `mode="popLayout"` pins a leaver (Motion's): by its inline start (`"left"`,
+   * the default) or end (`"right"`), which a right-to-left layout flips, as Motion's does, and by its
+   * `"top"` (the default) or `"bottom"`. Each edge keeps its distance from its container's while the
+   * leaver exits, so one pinned by the bottom right stays in that corner as the container resizes.
+   * Read as each leaver pops.
+   */
+  readonly anchorX?: "left" | "right" | undefined
+  readonly anchorY?: "top" | "bottom" | undefined
+  /**
+   * Whether its children's going and coming moves the `layout` elements around them (Motion's
+   * prop): `true` (the default) tells the projection when a child enters, a leaver pops or a leaver is
+   * removed, so a `layout` sibling animates into or out of the space; `false` tells it nothing, and a
+   * sibling animates only when something else measures it. Read at each change.
+   */
+  readonly presenceAffectsLayout?: boolean | undefined
+  /**
+   * Motion's `propagate`: inside another presence's child, when that child
+   * leaves, this presence's children all leave too, each running its exit, and that child goes once
+   * they've all gone. Without it (the default), its children go with that child, as they are. Read
+   * once.
+   */
+  readonly propagate?: boolean
+}
+
+/**
+ * Wraps its children (a conditional one, `<Show>`, or a `<For>`'s) and animates each one's exit
+ * before it's removed: each that leaves exits in its place, and one that comes back mid-exit
+ * is a new node, entering beside the leaver, or, with the leaver's `key` on its Wardic element,
+ * taking over from where the leaver is.
+ * A leaving child runs its own `exit` if it's a `wardic.*` element or an element with a ward on
+ * it, and the exits of the Wardic elements inside it either way, staying until they've ended; a
+ * plain child with nothing inside it to wait for goes at once. Inside a `<WardicProvider>`.
+ */
+export function AnimatePresence(props: AnimatePresenceProps): JSX.Element {
+  // A server render has no exit to drive: the same boundaries, a context that registers nothing.
+  // eslint-disable-next-line solid/components-return-once -- `isServer` is a constant: the component takes one path for its life
+  if (isServer) return serverPresence(props)
+  // Its own handle, made only when `ref` is given (#257): its exits are told to it, and it's handed to `ref`.
+  const ref = untrack(() => props.ref)
+  const own = Bool.match(hasRef(ref), { onTrue: makePresenceHandle, onFalse: constUndefined })
+  // `mode="wait"`'s held children may go on the page (#277): the children are rendered again.
+  const [released, release] = createSignal<undefined>(undefined, { equals: false })
+  // The presence above, if any (#277's PR 5c): read before this one provides its own.
+  const parent = usePresenceContext()
+  const presence = makePresence({
+    runtime: useWardicRuntime(),
+    renderer: useWardicRenderer(),
+    projection: useBuiltProjection(),
+    reducedMotion: useWardicReducedMotion(),
+    positionalKeys: useWardicPositionalKeys(),
+    defaultTransition: useWardicDefaultTransition(),
+    initial: () => untrack(() => props.initial),
+    events: UndefinedOr.map(own, (handle) => handle.events),
+    mode: () => props.mode,
+    custom: () => untrack(() => props.custom),
+    anchorX: () => untrack(() => props.anchorX),
+    anchorY: () => untrack(() => props.anchorY),
+    presenceAffectsLayout: () => untrack(() => props.presenceAffectsLayout),
+    release: () => release(undefined),
+  })
+  UndefinedOr.map(own, (handle) => (ref as (presence: Presence) => void)(handle.handle))
+  onSettledClientOnly(presence.mounted)
+  // `propagate` (#277's PR 5c): with a presence above, its teardown waits to hear whether this one's
+  // child left. Read before this presence provides its own context.
+  onCleanup(propagateTo(parent, untrack(() => props.propagate) === true, presence))
+
+  // Resolved under the context, so the child's ward sees it.
+  const Tracker = (): JSX.Element => {
+    const resolved = children(() => props.children)
+    // What goes on the page (#277): every child, but under `mode="wait"` one entering is held off it
+    // while a child exits. The controller is told what went on.
+    const shown = createMemo(() => {
+      released()
+      return presence.shown(resolved())
+    }, CLIENT_ONLY)
+    createEffect(
+      shown,
+      (current) => {
+        presence.present(current)
+      },
+      CLIENT_ONLY,
+    )
+    return shown as unknown as JSX.Element
+  }
+
+  // Its `custom`, reactive, for `usePresenceData` (#277's PR 5b).
+  const context: PresenceContextValue = { ...presence.context, data: () => props.custom }
+  return (
+    <PresenceContext value={context}>
+      <Tracker />
+    </PresenceContext>
+  )
+}
+
+/** {@link AnimatePresence} during a server render: the client's boundaries, nothing to track. */
+const serverPresence = (props: AnimatePresenceProps): JSX.Element => {
+  // A `ref` is handed the server's handle, on which nothing exits (#257).
+  const ref = untrack(() => props.ref)
+  if (hasRef(ref)) ref(serverPresenceHandle())
+  // A server renders once: every child is set up with the first render (#134).
+  const context: PresenceContextValue = { register: () => () => {}, blocksInitial: () => untrack(() => props.initial) === false, data: () => props.custom }
+  const Tracker = (): JSX.Element => children(() => props.children) as unknown as JSX.Element
+  return (
+    <PresenceContext value={context}>
+      <Tracker />
+    </PresenceContext>
+  )
+}

package/src/unstable/v2/press-sensor.ts

@@ -0,0 +1,31 @@
+/**
+ * `createPress` (#548): in a module of its own, so it brings the `press` Feature only to an app that uses it,
+ * and on the pages that do (ADR-0067, *Amendment (#548)*).
+ *
+ * @module
+ */
+import type { Feature } from "../../feature.ts"
+import { press } from "../../features/press.ts"
+import { PressGesture } from "../../features/keys.ts"
+import { serviceOf } from "../../gesture-features.ts"
+import { useBrought } from "./provider.tsx"
+import { type Sensor, watchSensorOf } from "./sensors.ts"
+
+/** What it brings (ADR-0067 decision 12): its gesture's Feature, whatever its section has (#511). */
+const PRESS: ReadonlyArray<Feature> = [press]
+
+/**
+ * `true` while the element it's given to as a `ref` is pressed, by a pointer held down on it or by
+ * Enter or Space while it has focus, `false` once it's released or the press is cancelled. An element
+ * that takes no focus of itself is given `tabindex="0"`, so a keyboard can press it.
+ *
+ * @example
+ * const pressed = createPress()
+ * <button ref={pressed}>{pressed() ? "Holding" : "Press and hold"}</button>
+ * @see https://wardic.dev/reference/solid/gestures/create-press
+ */
+// The core press watch; a Keyboard press (#427).
+export const createPress = (): Sensor<boolean> => {
+  const services = useBrought(PRESS)
+  return watchSensorOf<boolean>((target, { on, onDefect }) => serviceOf(services(), PressGesture).watch(target, { on: (press) => on(press.phase === "start"), onDefect }), false)
+}