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

package/src/presence-record.ts

@@ -0,0 +1,189 @@
+/**
+ * What a Wardic element and its `<AnimatePresence>` share (ADR-0007): the record a child registers,
+ * and the presence's context value. Solid-free, so both bindings' spines write the same record (#209).
+ *
+ * @module
+ */
+import type * as Box from "@wardic/core/Box"
+import type * as Values from "@wardic/core/Values"
+import type * as Style from "@wardic/dom/Style"
+import type { WardicTransition, WardicVariantLabels } from "./config.ts"
+import { constFalse } from "effect/Function"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+
+/**
+ * A child's live presence registration. `snapshot` / `exit` are MUTABLE ref
+ * cells (`{ current }`) the child's spine writes to while alive; they outlive
+ * the child's owner so the parent-driven exit reads them after the child leaves.
+ */
+export interface PresenceRecord {
+  /** The child's root DOM element (the same `el` the spine wires). */
+  readonly element: HTMLElement
+  /** The latest emitted value-map, updated by the spine each frame. */
+  readonly snapshot: { current: Values.Values }
+  /**
+   * The exit, resolved as the child leaves: its target, a variant name or a dynamic variant
+   * resolved with `custom` (the presence's, when it has one, else the child's last), and the
+   * transition it runs on. The child keeps what it's resolved from current while alive.
+   */
+  readonly exitOf: (custom: unknown, inherited: WardicVariantLabels | undefined) => PresenceExit
+  /**
+   * Where it sits in the variant tree, decided at setup as the tree is: whether it joins the
+   * nearest element that provides a context (a **Variant child**, which then exits on that one's
+   * exit name, in its stagger), whether its own Variant children join it, and whether it's a twin
+   * (a `layoutId`, whose crossfade replaces its exit). Left out: none of them.
+   */
+  readonly tree?: PresenceTree
+  /**
+   * Where an exit key with no value in `snapshot` starts: its `style` value, else
+   * the element's Own value, read from the retained node at the exit, in the shape of `like`
+   * (the key's exit target). `undefined` starts it at its target. Optional: a record without
+   * it starts such a key at its target.
+   */
+  readonly startOf?: ((key: string, like: number | string) => number | string | undefined) | undefined
+  /**
+   * Its velocities now, each numeric key's: what a child back under its key starts with, when
+   * this one is taken over without an exit running. Optional: left out, 0.
+   */
+  readonly velocities?: (() => Readonly<Record<string, number>>) | undefined
+  /**
+   * Whether reduced motion applies to it now: its nearest `WardicConfig`'s, else the
+   * provider's, read as its exit starts. Optional: left out, the presence's.
+   */
+  readonly reducedMotion?: (() => boolean) | undefined
+  /**
+   * Whether its animations are skipped now: its nearest `WardicConfig`'s, read as its exit
+   * starts. Optional: left out, never.
+   */
+  readonly skipAnimations?: (() => boolean) | undefined
+}
+
+/** Where a Wardic element starts when its child takes over from a leaver (#286, ADR-0048): the values and velocities it's drawn at. */
+export interface PresenceSeed {
+  readonly values: Values.Values
+  readonly velocities: Readonly<Record<string, number>>
+  /** Where the element it takes over from painted, in the Root frame: a layout node moves from there. */
+  readonly box?: Box.Box | undefined
+  /** The crossfade factor a twin it takes over from had faded out to: its handover's fade goes on from there. */
+  readonly fade?: number | undefined
+}
+
+/**
+ * A child's exit, resolved as it leaves (#277): its values, and the transition it runs on, whose
+ * orchestration its Variant children's exits take.
+ */
+export interface PresenceExit {
+  readonly values: Values.Values
+  readonly transition: WardicTransition | undefined
+  /** The exit name it hands its Variant children (#290): its own `exit`, if a name or a list (#297), else the one it took. */
+  readonly name: WardicVariantLabels | undefined
+  /**
+   * A list's exit by name (#297): each name's keys (those it's the last to set) on its own transition,
+   * else the element's, and its orchestration for its Variant children's keys of that name. Every
+   * name has one, keys or none. Left out for a single name or a values map: the whole exit is one.
+   */
+  readonly groups?: ReadonlyArray<ExitGroup> | undefined
+  /** Its Keyframes (#429): each such key's stops, its value in `values` their last. Left out with none. */
+  readonly keyframes?: Readonly<Record<string, Style.Stops>> | undefined
+}
+
+/** One name of a list's exit (#297): its keys, and the transition they and its orchestration run on. */
+export interface ExitGroup {
+  readonly name: string
+  readonly values: Values.Values
+  readonly transition: WardicTransition | undefined
+}
+
+/** A record's place in the variant tree (#290, {@link PresenceRecord.tree}). */
+export interface PresenceTree {
+  readonly joins: boolean
+  readonly provides: boolean
+  readonly twin: boolean
+}
+
+/** The value `<AnimatePresence>` publishes to descendant `createWard` spines. */
+export interface PresenceContextValue {
+  /**
+   * Register a child's live record. Returns a disposer the registrant MAY call,
+   * but the child does NOT call it on its own `onCleanup` — `<AnimatePresence>`
+   * removes the registration after the exit completes.
+   */
+  readonly register: (rec: PresenceRecord) => () => void
+  /**
+   * Whether an element setting up now starts at its `animate`, with nothing animating at mount:
+   * `<AnimatePresence initial={false}>`, during its first render (Motion's
+   * `presenceContext.initial`). A child that enters later animates in. Optional: left out, never.
+   */
+  readonly blocksInitial?: () => boolean
+  /**
+   * Whether an element setting up now is inside a child `mode="wait"` holds off the page: `undefined`
+   * when it isn't, and it starts now. Else `start` is called once the child is on the page, and the
+   * call returned cancels that (the element gone first). Optional: left out, never.
+   */
+  readonly hold?: (el: HTMLElement, start: () => void) => (() => void) | undefined
+  /**
+   * A presence hook's registration: `usePresence`'s and `useIsPresent`'s.
+   * Optional: left out, nothing is watched.
+   */
+  readonly watch?: (watch: PresenceWatch) => void
+  /** The presence's `custom`, reactive: `usePresenceData`'s. Left out, `undefined`. */
+  readonly data?: () => unknown
+  /**
+   * A Wardic element made: its `key` and whether it's a twin, told as its element is
+   * made, before the presence decides what goes on the page (so `mode="wait"` doesn't hold a child
+   * back under its key), and before any of its child's wards mount (so the elements inside pair).
+   * Optional: left out, no child is keyed.
+   */
+  readonly made?: (el: Element, key: string | number | undefined, twin: boolean) => void
+  /**
+   * Where an element mounting now starts, when its child takes over from a leaver: asked once,
+   * before its first Retarget. `undefined`: as it would. Optional: left out, never.
+   */
+  readonly takeOverOf?: (el: Element) => PresenceSeed | undefined
+}
+
+/** Tell `presence` a Wardic element was made ({@link PresenceContextValue.made}): nothing without one. */
+export const presenceMade = (presence: PresenceContextValue | undefined, el: Element, key: string | number | undefined, twin: boolean): void => {
+  if (Predicate.isUndefined(presence)) return
+  UndefinedOr.map(presence.made, (tell) => tell(el, key, twin))
+}
+
+/** Where `el` starts as it mounts, taking over from a leaver ({@link PresenceContextValue.takeOverOf}): `undefined` as it would. */
+export const presenceSeedOf = (presence: PresenceContextValue | undefined, el: Element): PresenceSeed | undefined => {
+  if (Predicate.isUndefined(presence)) return undefined
+  return UndefinedOr.map(presence.takeOverOf, (of) => of(el))
+}
+
+/**
+ * What a presence hook registers (#277's PR 5b, ADR-0048): its element, whose leaving child it
+ * belongs to, and what it's told. Kept until that child goes, the presence goes, or its element
+ * leaves the page some other way.
+ */
+export interface PresenceWatch {
+  /** Its element, once it has one: the child that holds it is the one it belongs to. */
+  readonly element: () => Element | undefined
+  /** Whether it holds its child as it leaves, until `release` is called (`usePresence`). */
+  readonly holds: boolean
+  /**
+   * Its child left: called once, with the node back in place (or popped, `mode="popLayout"`), with
+   * the presence's `custom`, and `release`, which lets the child go once it holds it.
+   */
+  readonly leave: (custom: unknown, release: () => void) => void
+  /** Its child went some other way, or the presence did: it's dropped, with no leave. */
+  readonly gone: () => void
+}
+
+/** Whether `presence` holds an element setting up now at its `animate` ({@link PresenceContextValue.blocksInitial}). */
+export const presenceBlocksInitial = (presence: PresenceContextValue | undefined): boolean =>
+  UndefinedOr.match(presence, {
+    onUndefined: constFalse,
+    onDefined: (p) => UndefinedOr.match(p.blocksInitial, { onUndefined: constFalse, onDefined: (blocks) => blocks() }),
+  })
+
+/**
+ * Whether `el` waits for its child to go on the page ({@link PresenceContextValue.hold}): the call
+ * that cancels `start`, or `undefined` when it starts now.
+ */
+export const presenceHold = (presence: PresenceContextValue | undefined, el: HTMLElement, start: () => void): (() => void) | undefined =>
+  UndefinedOr.map(presence, (p) => UndefinedOr.map(p.hold, (hold) => hold(el, start)))

package/src/presence.tsx

@@ -0,0 +1,269 @@
+/**
+ * `<AnimatePresence>` — exit-before-unmount for its children (ADR-0007; many since #277, ADR-0048).
+ *
+ * Doctrine: the LEAVING child cannot animate its own exit — Solid disposes its
+ * reactive owner (and would remove its DOM node) the instant the `<Show>` (or
+ * other control flow) that renders it flips false. So exit is PARENT-DRIVEN:
+ *
+ *   1. While a child is alive, its spine REGISTERS a record with the nearest
+ *      `<AnimatePresence>` via {@link PresenceContext}: `snapshot.current`, the
+ *      latest emitted value-map, which the spine updates each frame, and `exitOf`,
+ *      which resolves its exit as it leaves (a target, a variant name, or a dynamic
+ *      variant resolved with `custom`). The child does NOT unregister on its own
+ *      `onCleanup` — `<AnimatePresence>` owns removal.
+ *   2. `<AnimatePresence>` resolves its children via Solid `children()` (one, or a
+ *      `<For>`'s many) and tracks the present elements. When one with a registration
+ *      leaves the resolved children, it RE-INSERTS / KEEPS that DOM node where it was
+ *      instead of letting it vanish, then runs the exit itself (from
+ *      `snapshot.current` toward what `exitOf` resolves, via the provider runtime + the
+ *      Renderer's `project`/`commit`), and on the exit's settle removes the node from
+ *      the DOM and the registration.
+ *   3. A leaving child with no registration, a plain one, still runs the exits of the
+ *      Wardic elements inside it and hands back the twins inside it, staying until
+ *      they've ended (#392); with nothing inside it to wait for, it goes at once.
+ *
+ * Node retention (the hard part): mirrors solid-transition-group's approach, child by
+ * child. We resolve `children()` (which returns the live DOM nodes) and, when
+ * the reactive branch drops one, RE-APPEND the captured node to our container so
+ * the disposed owner's removal is undone — the node survives long enough for the
+ * parent-driven exit, then we remove it on settle. The registration's snapshot /
+ * exit refs are plain objects that outlive the child's owner, so the exit has
+ * everything it needs after the child is gone.
+ *
+ * A child is its DOM node (#277): each that leaves exits on its own, in its place. A
+ * child that comes back mid-exit is a new node: with the leaver's `key` on its Wardic
+ * element it takes over from where the leaver is (#286); without one it enters beside
+ * the leaver while the leaver finishes, as Motion shows two children it can't tell
+ * apart.
+ *
+ * A leaving child that isn't a twin hands back the twins inside it (#181): each
+ * crossfades onto its other twin while the child runs its own exit, and the child
+ * goes once both have ended. Its exit's values reach the projection, so a twin
+ * inside stays on its other twin while the exit moves or scales the child.
+ */
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { type Accessor, children, createContext, createEffect, createMemo, createSignal, type JSX, onCleanup, onMount, untrack, useContext } from "solid-js"
+import { exitCompleteEvents, makePresence, type PresenceMode, propagateTo } from "./presence-controller.ts"
+import { useBuiltProjection, useWardicDefaultTransition, useWardicPositionalKeys, useWardicReducedMotion, useWardicRenderer, useWardicRuntime } from "./provider.tsx"
+import { isServer } from "./server.ts"
+import type { PresenceContextValue } from "./presence-record.ts"
+
+export { type PresenceContextValue, type PresenceRecord, presenceBlocksInitial, presenceHold } from "./presence-record.ts"
+export type { PresenceMode } from "./presence-controller.ts"
+
+/**
+ * Context carrying the nearest `<AnimatePresence>`'s registrar. `undefined` when
+ * there is no presence in scope — `createWard` then skips exit registration.
+ */
+export const PresenceContext = createContext<PresenceContextValue | undefined>(undefined)
+
+/** Read the nearest {@link PresenceContext}, or `undefined` outside one. */
+export const usePresenceContext = (): PresenceContextValue | undefined => 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. On a server, the rendered child.
+   */
+  readonly initial?: boolean
+  /**
+   * Called once every exiting child has animated out and been removed (Motion's prop): not
+   * when a child comes back mid-exit, nor when the presence itself goes. Read when it's called.
+   */
+  readonly onExitComplete?: (() => 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 (`onMount` 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
+}
+
+/**
+ * `<AnimatePresence>` — wraps its children (a conditional one, or a `<For>`'s) and
+ * animates each one's exit before it's removed; one that comes back mid-exit with the
+ * leaver's `key` on its Wardic element takes over from where the leaver is. Must be used
+ * inside a `<WardicProvider>` (it drives the exit on the provider runtime) and may wrap any
+ * control flow (e.g. `<Show>`). A leaving child runs its own `exit` if it's a `wardic.*` element or a
+ * `createWard` spine, 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.
+ */
+export function AnimatePresence(props: AnimatePresenceProps): JSX.Element {
+  const runtime = useWardicRuntime()
+  const reducedMotion = useWardicReducedMotion()
+  const positionalKeys = useWardicPositionalKeys()
+  const defaultTransition = useWardicDefaultTransition()
+  // A server render has no exit to drive and no runtime to log on: the same component
+  // boundaries, with a context that registers nothing (ADR-0021).
+  if (isServer) return serverPresence(props)
+  // `mode="wait"`'s held children may go on the page (#277): the children are rendered again.
+  const [released, release] = createSignal<void>(undefined, { equals: false })
+  // The retained nodes, their exits and the twins they hand back (`presence-controller.ts`).
+  // The presence above, if any (#277's PR 5c): read before this one provides its own.
+  const parent = usePresenceContext()
+  const presence = makePresence({
+    runtime,
+    renderer: useWardicRenderer(),
+    projection: useBuiltProjection(),
+    reducedMotion,
+    positionalKeys,
+    defaultTransition,
+    initial: () => props.initial,
+    // Motion's `onExitComplete` (#257).
+    events: exitCompleteEvents(runtime, () => untrack(() => props.onExitComplete)),
+    mode: () => props.mode,
+    custom: () => untrack(() => props.custom),
+    anchorX: () => untrack(() => props.anchorX),
+    anchorY: () => untrack(() => props.anchorY),
+    presenceAffectsLayout: () => untrack(() => props.presenceAffectsLayout),
+    release: () => release(),
+  })
+  // `initial={false}` (#134): the children set up with this first render start at their
+  // `animate`; one that enters after it animates in.
+  onMount(presence.mounted)
+
+  // Inner tracker: resolved + the tracking effect MUST run UNDER the
+  // PresenceContext.Provider, so the children's reactive owners are created
+  // within the context and their `createWard` spines see `usePresenceContext()`.
+  // (Resolving children() in the outer body would put their owners ABOVE the
+  // provider and they'd never register an exit record.)
+  const Tracker = (): JSX.Element => {
+    // children() memoizes the resolved value; a <Show> flip changes what it
+    // returns (the node -> undefined and back).
+    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())
+    })
+    createEffect(() => presence.present(shown()))
+    return shown as unknown as JSX.Element
+  }
+
+  // `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))
+
+  // Its `custom`, reactive, for `usePresenceData` (#277's PR 5b).
+  const context: PresenceContextValue = { ...presence.context, data: () => props.custom }
+  return (
+    <PresenceContext.Provider value={context}>
+      <Tracker />
+    </PresenceContext.Provider>
+  )
+}
+
+/** The element `target` is: an element, or an accessor of one; `undefined` before it has one. */
+const elementOf = (target: unknown): Element | undefined => {
+  if (Predicate.isFunction(target)) return asElement(target())
+  return asElement(target)
+}
+
+/** `at`, if it's an element. */
+const asElement = (at: unknown): Element | undefined => {
+  if (at instanceof Element) return at
+  return undefined
+}
+
+/** A presence hook's registration (#277's PR 5b): `isPresent`, `false` from its child's leave. */
+const watchOf = (target: unknown, holds: boolean, onLeave: (safeToRemove: () => void, custom: unknown) => void): Accessor<boolean> => {
+  const [present, setPresent] = createSignal(true)
+  if (isServer) return present
+  UndefinedOr.map(usePresenceContext(), (presence) =>
+    UndefinedOr.map(presence.watch, (watch) =>
+      watch({
+        element: () => elementOf(target),
+        holds,
+        leave: (custom, release) => {
+          setPresent(false)
+          onLeave(release, custom)
+        },
+        gone: () => {},
+      })))
+  return present
+}
+
+/**
+ * Motion's `usePresence`, in Solid's shape: the leaving child that holds
+ * `target` (an element, or an accessor of one) stays until `safeToRemove` is called. `onLeave` is
+ * called when it leaves, once its node is back in place (or popped, `mode="popLayout"`), with the
+ * presence's `custom`: the child's own code is already disposed by then, so what it does there is
+ * plain DOM work (a Web Animation, a timer) that ends by calling `safeToRemove`. Never at the
+ * presence's own teardown, and outside a presence, never. One that throws is reported, and lets the
+ * child go. Returns whether the child is present: `false` from its leave, for handlers still firing
+ * on the retained node.
+ */
+export function usePresence(
+  target: unknown,
+  // Motion's `custom` is `any`: the callback declares its own.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onLeave: (safeToRemove: () => void, custom: any) => void,
+): Accessor<boolean> {
+  return watchOf(target, true, onLeave)
+}
+
+/**
+ * Motion's `useIsPresent`: whether the child that holds `target` is present, `false`
+ * from its leave on. The child's own effects are disposed as it leaves, so it's for what still runs
+ * on the retained node: an event handler, a timer. Outside a presence, always `true`.
+ */
+export function useIsPresent(target: unknown): Accessor<boolean> {
+  return watchOf(target, false, () => {})
+}
+
+/** Motion's `usePresenceData`: the nearest presence's `custom`, `undefined` outside one. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function usePresenceData<T = any>(): Accessor<T | undefined> {
+  const presence = usePresenceContext()
+  return () => UndefinedOr.map(UndefinedOr.map(presence, (p) => p.data), (data) => data()) as T | undefined
+}
+
+/** {@link AnimatePresence} during a server render: the client's boundaries, nothing to track. */
+const serverPresence = (props: AnimatePresenceProps): JSX.Element => {
+  // A server renders once: every child is set up with the first render (#134).
+  const ctx: PresenceContextValue = { register: () => () => {}, blocksInitial: () => props.initial === false, data: () => props.custom }
+  const Tracker = (): JSX.Element => children(() => props.children) as unknown as JSX.Element
+  return (
+    <PresenceContext.Provider value={ctx}>
+      <Tracker />
+    </PresenceContext.Provider>
+  )
+}

package/src/press-sensor.ts

@@ -0,0 +1,33 @@
+/**
+ * `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 { Accessor } from "solid-js"
+import { watchToSignal } from "./bridge.ts"
+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"
+
+/** What it brings (ADR-0067 decision 12): its gesture's Feature, whatever its section has (#511). */
+const PRESS: ReadonlyArray<Feature> = [press]
+
+/**
+ * `true` while `target` 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. `target` is the element itself, so call
+ * it where it exists. An element that takes no focus of itself is given `tabindex="0"`, so a keyboard
+ * can press it.
+ *
+ * @example
+ * const pressed = createPress(props.button)
+ * <span>{pressed() ? "Holding" : "Press and hold"}</span>
+ * @see https://wardic.dev/reference/solid/gestures/create-press
+ */
+// The core press watch (#318); a Keyboard press (#427). `false` until its first transition.
+export const createPress = (target: unknown): Accessor<boolean> => {
+  const services = useBrought(PRESS)
+  return watchToSignal<boolean>(({ on, onDefect }) => serviceOf(services(), PressGesture).watch(target, { on: (press) => on(press.phase === "start"), onDefect }), false)
+}

package/src/press.ts

@@ -0,0 +1,40 @@
+/**
+ * A Wardic element's press (#427, ADR-0056): watched with its **Keyboard presses**, the element made
+ * focusable for them first, as Motion's press makes it, and kept from its pressable ancestors when its
+ * `propagate` says so (#439). Both bindings' elements and their `createPress` watch through it.
+ *
+ * @module
+ */
+import type * as InputFeed from "@wardic/core/InputFeed"
+import type * as InputSource from "@wardic/core/InputSource"
+import * as Recognizer from "@wardic/core/Recognizer"
+import * as DomInput from "@wardic/dom/DomInput"
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import { constTrue, type LazyArg } from "effect/Function"
+import type * as Scope from "effect/Scope"
+import * as UndefinedOr from "effect/UndefinedOr"
+import type { WardicPropagate } from "./config.ts"
+
+/** Whether an element's taps reach its pressable ancestors (#439): unless its `propagate` says `tap: false`. */
+export const tapPropagates = (propagate: WardicPropagate | undefined): boolean =>
+  UndefinedOr.match(propagate, { onUndefined: constTrue, onDefined: (p) => p.tap !== false })
+
+/**
+ * Watch the presses on `element` (#427): a pointer's, and its **Keyboard presses**, the element made
+ * focusable first. `keysTaken`: its Enter and Space are someone else's (a Reorder item's, which lift
+ * it, ADR-0037), so it hears no keys, and is left as it is. `propagates`: whether its presses reach its
+ * pressable ancestors (#439), read at each press's start.
+ */
+export const watchPressOn = (
+  element: unknown,
+  handlers: InputFeed.Handlers<Recognizer.PressEvent>,
+  keysTaken = false,
+  propagates: LazyArg<boolean> = constTrue,
+): Effect.Effect<void, never, Scope.Scope | InputSource.InputSource> =>
+  Effect.andThen(
+    Effect.sync(() => {
+      if (Bool.not(keysTaken)) DomInput.makeFocusable(element)
+    }),
+    Recognizer.watchPress(element, handlers, { keys: Bool.not(keysTaken), propagate: propagates }),
+  )