Documentation navigation

Published API · 0.1.0-rc.1

foldkit · dom

Published foldkit API declarations for dom.

./dom

@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit/dom'

Exported declarations

advanceFocus

Focuses the next or previous focusable element in the document relative to the element matching the given selector. Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

advanceFocus: (selector: string, direction: FocusDirection) => Effect.Effect<void, ElementNotFound>

clickElement

Programmatically clicks an element matching the given selector. Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

clickElement: (selector: string) => Effect.Effect<void, ElementNotFound>

closeDialog

Closes a dialog element using `.close()`. Cleans up the keyboard handlers installed by `showDialog`, restores modal background isolation, and then returns focus to the element that was focused before the dialog opened (the trigger, or the dialog beneath it when closing a stacked dialog). Resolves to `true` when it released the keyboard handlers, the return focus, and the stack entry. Resolves to `false` when the dialog held none, for example when the close runs before `showDialog` has installed them. A caller that unlocks page scroll after the close should unlock only when the result is `true`. Fails with `ElementNotFound` if the selector does not match an `HTMLDialogElement`.

closeDialog: (selector: string) => Effect.Effect<boolean, ElementNotFound>

detectElementMovement

Detects if the element matching the given selector moves in the viewport. Snapshots the element's position via `getBoundingClientRect` and watches for changes using a `ResizeObserver` plus window `scroll` and `resize` listeners. Resolves when movement is detected. Falls back to completing immediately if the element is missing. Cleanup runs automatically when the fiber is interrupted (e.g. by `Effect.raceFirst`), removing the observer and event listeners via `AbortSignal`.

detectElementMovement: (selector: string) => Effect.Effect<void>

ElementNotFound

Error indicating that a DOM element matching the given selector was not found.

export declare class ElementNotFound extends ElementNotFound_base<{
    readonly selector: string;
}> {
}

focus

Focuses an element matching the given selector after the next render has committed. Use `Dom.focus` inside a Command for focus that's caused by a Message dispatching: a dialog opening, an input becoming the active step in a form, returning focus to a trigger button after a popover closes, keyboard navigation across a stable layout. The Command fires from `update`'s return; the focus runs after the next render commits, so the element is in place by the time `.focus()` runs. Do not use `OnMount` for focus. The cause of focus-on-open is the Message, not the element appearing. Mount is for per-instance lifecycle effects bound to a VNode existing where the live element handle is needed (positioning, portaling, observer attachment, library setup). Waiting for the commit puts the element in the DOM. It does not make the element focusable. `.focus()` is a no-op on an element that is not rendered, so a target behind `visibility: hidden` or `display: none` leaves focus where it was, with nothing to distinguish that from focus having landed. This is worth knowing when something asynchronous reveals the target after the render commits: a panel held at `visibility: hidden` until a positioning library resolves its first layout is still hidden when the Command runs, however long the Command waits. Focus a target like that from whatever performs the reveal, which is the one place that knows the element has become focusable. The Message still causes the reveal, so the focus belongs to that Message rather than to a lifecycle effect standing in for it. Section headings, articles, and other non-natively-focusable elements are common URL fragment targets, but `.focus()` is a no-op on them without a `tabindex`. Pass `makeFocusable: true` to inject `tabindex="-1"` on the target if it has none, making programmatic focus actually land. Pass `preventScroll: true` to suppress the browser's default scroll-on-focus, useful when the focus call follows a deliberate scroll that should not be undone. The two options compose with `scrollIntoViewAfterPaint` for URL-fragment-navigation accessibility: scroll the section into view, then focus the same selector so keyboard users start Tab navigation from the target. Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

focus: (selector: string, options?: Readonly<{
    preventScroll?: boolean;
    makeFocusable?: boolean;
}>) => Effect.Effect<void, ElementNotFound>

FocusDirection

Direction for focus advancement: forward or backward in tab order.

export type FocusDirection = 'Next' | 'Previous';

inertOthers

Marks all DOM elements outside the given selectors as `inert` and `aria-hidden="true"`. Walks each allowed element up to `document.body`, marking siblings that don't contain an allowed element. Uses reference counting so nested calls are safe. A restore before the pending render commits invalidates the request before it can change the DOM.

inertOthers: (id: string, allowedSelectors: ReadonlyArray<string>) => Effect.Effect<void>

KeyBinding

export type KeyBinding<Output> = BindingBase<Output> & (Readonly<{
    keys: string;
    whenRepeated?: 'Ignore' | 'Allow';
}> | Readonly<{
    keys: Readonly<[string, string, ...Array<string>]>;
    whenRepeated?: never;
}>);

KeySequence

A single key press or a sequence of two or more key presses.

export type KeySequence = string | Readonly<[string, string, ...Array<string>]>;

lockScroll

Locks page scroll by setting `overflow: hidden` on the document element. Compensates for scrollbar width with padding to prevent layout shift. On iOS Safari, intercepts `touchmove` events to prevent page scroll while allowing scrolling within overflow containers. Uses reference counting so nested locks are safe. The page only unlocks when every lock has been released.

lockScroll: Effect.Effect<void>

releaseDialogResources

Releases the framework hygiene a dialog holds while open: the focus-trap keyboard handler, modal background isolation, the recorded return focus, the dialog stack entry, the z-index counter, and one page scroll lock. Use this when the element is removed without a close Message, such as navigation away from a route-keyed subtree. The runtime also calls it directly on disposal. The normal close path already releases these. That path is `closeDialog` first, then the Dialog component's scroll unlock when `closeDialog` reports a release. This function is the cleanup for the case where no close Message ever reaches `update`. Addressed by the dialog's id, not a selector, because the element is typically already gone from the DOM by the time this runs (that is the whole point of the backstop). The hygiene installed by `showDialog` is tracked by id so it can be reclaimed without a live element handle. The id must be non-empty and unique within the document, since it keys this cleanup accounting; a duplicate or empty id would release the wrong dialog's hygiene. Idempotent and exactly-once. It releases only when the dialog currently holds hygiene, then clears the per-dialog marker, so calling it after a normal close, or twice, is a no-op that never under-counts the shared scroll lock. Carries no application close semantics: the Dialog component owns the user-facing close (animation, `Closed` OutMessage, consumer Commands); this only reclaims framework resources. Resolves to `true` when it released resources, `false` when there was nothing to release. Never fails: an id with no held hygiene is a no-op, since the goal is reclaiming resources that may already be gone.

releaseDialogResources: (id: string) => Effect.Effect<boolean>

restoreInert

Restores all elements previously marked inert by `inertOthers` for the given ID. Safe to call without a preceding `inertOthers`. Acts as a no-op in that case.

restoreInert: (id: string) => Effect.Effect<void>

scrollIntoView

Scrolls an element into view by selector. Resolves the selector after `Render.afterCommit`. Defaults to `{ block: 'nearest' }`; pass a different `block` for use cases like URL-fragment landing where `'start'` is right. For a target the same Message just brought into the DOM, `scrollIntoViewAfterPaint` is the right choice. Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

scrollIntoView: (selector: string, options?: Readonly<{
    block?: ScrollLogicalPosition;
}>) => Effect.Effect<void, ElementNotFound>

scrollIntoViewAfterPaint

Like `scrollIntoView`, but waits for `Render.afterPaint` instead of `Render.afterCommit` before resolving the selector. Reach for this when the target was just brought into the DOM by the same Message that dispatches the scroll, such as a routing flow landing at a URL fragment. The two-frame wait gives the runtime time to commit the new Model and the browser time to lay it out before the scroll runs. For a target that's already on screen, `scrollIntoView` is the lighter choice. Defaults to `{ block: 'nearest' }`; pass `{ block: 'start' }` for URL fragment landings where the target should sit at the top of the viewport. Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

scrollIntoViewAfterPaint: (selector: string, options?: Readonly<{
    block?: ScrollLogicalPosition;
}>) => Effect.Effect<void, ElementNotFound>

scrollIntoViewIfNotVisible

Like `scrollIntoViewAfterPaint`, but skips the scroll if the element is already fully visible within its scroll container. Defaults to `{ block: 'center' }`; pass a different `block` when the target should land at a specific position when it does need to scroll. `when` selects the timing gate. `'Paint'` (the default) waits for `Render.afterPaint`, so the scroll lands after the target is on screen. `'Commit'` waits for `Render.afterCommit` instead, so the scroll lands in the same frame the DOM patch applies, before the browser paints. Use `'Commit'` when the target is brought into view and scrolled by the same Message (such as a menu opening), so it appears already scrolled rather than visibly jumping. Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

scrollIntoViewIfNotVisible: (selector: string, options?: Readonly<{
    block?: ScrollLogicalPosition;
    when?: 'Paint' | 'Commit';
}>) => Effect.Effect<void, ElementNotFound>

showDialog

Opens a dialog element using `show()` with high z-index, focus trapping, and Escape key handling. An unhandled Escape on the topmost dialog dispatches a `CustomEvent` named `cancel`, distinguishing it from native `cancel` events while preserving the dialog event contract. Uses `show()` instead of `showModal()` so that DevTools (and any other high-z-index overlay) remains interactive. Pass `isModal: true` to make the background inert and hide it from assistive technology. `allowedOutsideSelectors` keeps separate developer overlays available while modal isolation is active. Stacked modal dialogs isolate against the topmost one, and closing it restores the dialog beneath. The Dialog component provides its own backdrop, scroll locking, and transitions. Fails with `ElementNotFound` if the selector does not match an `HTMLDialogElement`. Pass `focusSelector` to focus an element inside the dialog when it opens. When it does not match a focusable element, or when none is provided, focus falls back to the first focusable descendant and then to the dialog itself. Records the element that had focus when the dialog opened so `closeDialog` can return focus there, the way `showModal()` would natively. Resolves to `true` when it installs the dialog resources, or `false` when that id already holds them. The latter makes concurrent lifecycle recovery and application Commands safe without duplicating focus traps or stack entries.

showDialog: (selector: string, options?: Readonly<{
    focusSelector?: string;
    isModal?: boolean;
    allowedOutsideSelectors?: ReadonlyArray<string>;
}>) => Effect.Effect<boolean, ElementNotFound>

streamFromEvent

streamFromEvent: <Target extends EventTarget, Type extends EventTypeOf<Target>, Output>(config: StreamFromEventConfig<Target, Type, Output>) => Stream.Stream<Output>

StreamFromEventConfig

Configuration for the `streamFromEvent` Stream helper. `target` is read inside the acquire Effect, never before it, so the resolved `EventTarget` is captured at the moment the Stream's scope opens. Pass a thunk when the target may not exist until the scope opens, or pass the `EventTarget` directly for always-present globals like `window` or `document`. `type` is constrained to the event names the target declares, and `mapEvent`'s parameter is the event those two resolve to. Annotating that parameter is checked against the resolved event rather than replacing it. `mapEvent(event)` transforms each dispatched event into a Stream value. The mapper runs synchronously in the same call stack as the browser's event dispatch, so calling `event.preventDefault()` inside it takes effect, unless the listener is passive. Some browsers default wheel and touch listeners on global targets to passive, where `preventDefault()` is ignored. Pass `options: { passive: false }` explicitly when cancelling those events, or reach for `streamFromEventFilterMapPreventDefault`, which does so for you. The output type is inferred from the mapper; `Subscription.make` checks that the final Stream emits the application's Message type.

export type StreamFromEventConfig<Target extends EventTarget, Type extends EventTypeOf<Target>, Output> = Readonly<{
    target: Target | (() => Target);
    type: Type;
    mapEvent: (event: EventOf<Target, Type>) => Output;
    options?: AddEventListenerOptions;
}>;

streamFromEventFilterMap

streamFromEventFilterMap: <Target extends EventTarget, Type extends EventTypeOf<Target>, Output>(config: StreamFromEventFilterMapConfig<Target, Type, Output>) => Stream.Stream<Output>

StreamFromEventFilterMapConfig

Configuration for the `streamFromEventFilterMap` Stream helper. `target` is read inside the acquire Effect, never before it, so the resolved `EventTarget` is captured at the moment the Stream's scope opens. Pass a thunk when the target may not exist until the scope opens, or pass the `EventTarget` directly for always-present globals like `window` or `document`. `type` is constrained to the event names the target declares, and `filterMapEvent`'s parameter is the event those two resolve to. Annotating that parameter is checked against the resolved event rather than replacing it. `filterMapEvent(event)` returns `Option.some(value)` to emit a value for the event, or `Option.none()` to ignore it. The mapper runs synchronously in the same call stack as the browser's event dispatch, so calling `event.preventDefault()` inside it takes effect, unless the listener is passive. Some browsers default wheel and touch listeners on global targets to passive, where `preventDefault()` is ignored. Pass `options: { passive: false }` explicitly when cancelling those events, or reach for `streamFromEventFilterMapPreventDefault`, which does so for you. The output type is inferred from the mapper; `Subscription.make` checks that the final Stream emits the application's Message type.

export type StreamFromEventFilterMapConfig<Target extends EventTarget, Type extends EventTypeOf<Target>, Output> = Readonly<{
    target: Target | (() => Target);
    type: Type;
    filterMapEvent: (event: EventOf<Target, Type>) => Option.Option<Output>;
    options?: AddEventListenerOptions;
}>;

streamFromEventFilterMapPreventDefault

streamFromEventFilterMapPreventDefault: <Target extends EventTarget, Type extends EventTypeOf<Target>, Output>(config: StreamFromEventFilterMapPreventDefaultConfig<Target, Type, Output>) => Stream.Stream<Output>

StreamFromEventFilterMapPreventDefaultConfig

Configuration for the `streamFromEventFilterMapPreventDefault` Stream helper. `target` is read inside the acquire Effect, never before it, so the resolved `EventTarget` is captured at the moment the Stream's scope opens. Pass a thunk when the target may not exist until the scope opens, or pass the `EventTarget` directly for always-present globals like `window` or `document`. `type` is constrained to the event names the target declares, and `filterMapEvent`'s parameter is the event those two resolve to. Annotating that parameter is checked against the resolved event rather than replacing it. `filterMapEvent(event)` returns `Option.some(value)` to mark the dispatch handled, or `Option.none()` to leave the default behavior intact. For a handled dispatch the helper calls `event.preventDefault()` and queues the value before the listener returns; the mapper itself never calls `preventDefault()`. `options.passive` defaults to `false` so `preventDefault()` keeps working for the events browsers would otherwise register as passive. The config rejects `passive: true`; the runtime guard also throws for unchecked JavaScript inputs. The output type is inferred from the mapper; `Subscription.make` checks that the final Stream emits the application's Message type.

export type StreamFromEventFilterMapPreventDefaultConfig<Target extends EventTarget, Type extends EventTypeOf<Target>, Output> = Readonly<{
    target: Target | (() => Target);
    type: Type;
    filterMapEvent: (event: EventOf<Target, Type>) => Option.Option<Output>;
    options?: PreventDefaultEventListenerOptions;
}>;

streamFromKeyBindings

Build a Stream that maps declarative key bindings to values. The output is inferred from each binding's `mapEvent` callback; `Subscription.make` checks that the final Stream emits the application's Message type. A string describes one key press. Modifiers are joined with `+`: `'Mod+K'`, `'Control+Shift+P'`, or `'Alt+ArrowDown'`. The supported modifiers are `Mod`, `Control`, `Meta`, `Alt`, and `Shift`. `Mod` resolves to Meta on Apple platforms and Control elsewhere; `modKey` can override that choice. Matching uses `KeyboardEvent.key`, case-insensitively, after the active keyboard layout has been applied. Use `Space` and `Plus` for those keys. An array describes an ordered sequence of two or more presses. Every press uses the same grammar, so `['G', 'Shift+G']` is valid. Sequences reset after one second by default; `sequenceTimeout` accepts any Effect Duration input. Modifier-only events and repeated keydowns do not advance a sequence. Bindings are suppressed by default when the event's composed path contains an `input`, `textarea`, `select`, or contenteditable element. Set `whileTyping` to `'Allow'` for a binding that must work there. Events emitted during IME composition are always ignored. Repeated keydowns are ignored for one-press bindings unless `whenRepeated` is `'Allow'`. An event another handler already canceled is ignored and clears any sequence in progress. Matched key presses call `preventDefault()` before dispatching. For a sequence, that policy applies to every matched press. Set `preventDefault` to `false` to opt out. Sequences sharing a prefix must use the same policy. Duplicate bindings and a complete binding that is also a sequence prefix are rejected when the Stream is created. This helper returns a Stream, not a complete Subscription entry. Use `Subscription.persistentEntry` for a fixed table. When availability depends on the Model that owns the entry, build it inside `dependenciesToStream` and derive each binding's `isEnabled` from the dependency record. A dependency change opens a new Stream scope and resets any sequence in progress. If a parent owns a condition for a lifted child, declare the table at that parent or put bindings with different parent-owned lifetimes in separate child entries so `Subscription.lift` can gate them individually. If the meaning of a key depends on the Model, dispatch a factual key Message and decide what it means in update instead of reading the Model from `mapEvent`.

streamFromKeyBindings: <Output>(config: StreamFromKeyBindingsConfig<Output>) => Stream.Stream<Output>

StreamFromKeyBindingsConfig

export type StreamFromKeyBindingsConfig<Output> = Readonly<{
    bindings: ReadonlyArray<KeyBinding<Output>>;
    target?: EventTarget | (() => EventTarget);
    modKey?: ModKey;
    sequenceTimeout?: Duration.Input;
}>;

streamFromMediaQuery

Creates a Stream from a CSS media query. When the Stream starts, it emits the current `matches` value through `mapMatches`. It emits again whenever that value changes. Stopping the Stream removes the listener. The Stream reads the current value again each time it restarts. Suppose a color-scheme Subscription runs only while the theme preference is `System`. The user selects `Dark`, changes the operating system to a light theme, and then selects `System` again. A new `change` listener waits for the next change, so the Model still records a dark system theme. This helper emits the current light value as soon as the Stream restarts. Creating the Stream does not access `window`; `window.matchMedia` is called only when the Stream starts. The Stream can therefore be created during server rendering as long as it runs only in the browser. This helper returns a Stream, not a Subscription entry. Pass it to `Subscription.persistentEntry` for a query the application always follows. To follow the query only in a particular Model state, use it with `Stream.when` inside a `Subscription.make` entry.

streamFromMediaQuery: <Output>(config: StreamFromMediaQueryConfig<Output>) => Stream.Stream<Output>

StreamFromMediaQueryConfig

Options for `streamFromMediaQuery`. `query` accepts any media query string supported by `window.matchMedia`, such as `'(prefers-reduced-motion: reduce)'`, `'(prefers-color-scheme: dark)'`, or a viewport breakpoint like `'(max-width: 1023px)'`. `window.matchMedia` is called when the Stream starts, not when the Stream is created. `mapMatches` converts the Boolean `matches` result into each value the Stream emits. The return type of `mapMatches` determines the Stream's output type. `Subscription.make` checks that output against the application's Message type.

export type StreamFromMediaQueryConfig<Output> = Readonly<{
    query: string;
    mapMatches: (isMatching: boolean) => Output;
}>;

TypedEventTarget

An `EventTarget` that declares the events it dispatches, so the `streamFromEvent` helpers can resolve an event name to its event type the way they do for `window`, `document`, and the DOM interfaces lib.dom declares event maps for. Annotate a target with this and the mapper's parameter follows from the event name, including a `CustomEvent`'s `detail`. A declared event overrides the corresponding native event and otherwise augments the target's native events, so an element that dispatches custom events can be annotated without losing events such as `click`. Any `EventTarget` is assignable to it, so the annotation is the only change needed.

export interface TypedEventTarget<EventMap extends {
    readonly [Type in keyof EventMap]: Event;
}> extends EventTarget {
    readonly [EventMapMarker]?: EventMap;
}

unlockScroll

Releases one scroll lock. When the last lock is released, restores the original `overflow` and `padding-right` on the document element. On iOS Safari, removes the `touchmove` listener.

unlockScroll: Effect.Effect<void>

waitForAnimationSettled

Waits for all CSS animations on the element matching the selector to settle. Covers both CSS transitions and CSS keyframe animations via the Web Animations API. Falls back to completing immediately if the element is missing or has no active animations. Leave animations must be finite. `animation-iteration-count: infinite` will keep the underlying `.finished` promise pending and hang the caller.

waitForAnimationSettled: (selector: string) => Effect.Effect<void>

WhileTyping

Whether a key binding may fire when its event comes from an editable element.

export type WhileTyping = 'Suppress' | 'Allow';