@jam-overture/loom/signals/broadcast

READER_SIGNALS_EVENTvalue

const READER_SIGNALS_EVENT = "loom:signals"

VisibilityObservertype

Something that reports elements coming into and out of view. The browser's IntersectionObserver unless a host passes its own.

type VisibilityObserver = {
    readonly observe: (element: Element) => void;
    readonly disconnect: () => void;
};

VisibilityEntrytype

type VisibilityEntry = {
    readonly target: Element;
    readonly visible: boolean;
};

ObserveVisibilitytype

type ObserveVisibility = (onChange: (entries: readonly VisibilityEntry[]) => void) => VisibilityObserver;

ReaderSignalTypestype

The primitive types to report on: one list for every kind, or a list per kind.

type ReaderSignalTypes = readonly string[] | {
    readonly [Kind in ReaderSignalKind]?: readonly string[];
};

ReaderSignalOptionstype

type ReaderSignalOptions = {
    /** Called with every batch. A throw or rejection here is contained and never reaches the page. */
    readonly send?: (batch: ReaderSignalBatch) => void | Promise<void>;
    /** Which kinds to broadcast. Every kind when absent. */
    readonly kinds?: readonly ReaderSignalKind[];
    /**
     * Which primitive types to broadcast about. Every addressed type when absent.
     *
     * A list applies to every kind. An object sets it per kind — time on screen
     * for sections, activations for links — and a kind it does not name is
     * reported for every type, exactly as if `types` were absent for that kind.
     * Whether a kind is reported at all is still `kinds`.
     */
    readonly types?: ReaderSignalTypes;
    /** How often a batch is delivered. Five seconds when absent. */
    readonly flushEveryMs?: number;
    /**
     * How the broadcaster learns what is on screen. The browser's
     * `IntersectionObserver` when absent; a test passes its own.
     */
    readonly observeVisibility?: ObserveVisibility;
    /**
     * Whether a delegated signal carries the addressed nodes it happened inside.
     * On when absent.
     *
     * `activated` and `disclosed` are filed against the control a reader aimed
     * at, which is an addressed node of its own — so without the ancestry a
     * deployment can report which button was pressed and never which region it
     * was in. Off is for a host that reports on controls only and would rather
     * not carry the walk in every batch.
     */
    readonly within?: boolean;
    /** The clock. `Date.now` when absent. */
    readonly now?: () => number;
    /**
     * Where the view key's randomness comes from. The browser's
     * `crypto.getRandomValues` when absent; a test passes its own so it can name
     * the key it expects.
     */
    readonly random?: RandomBytes;
};

ReaderSignalBroadcasttype

type ReaderSignalBroadcast = {
    /** Deliver whatever has been gathered, now. */
    readonly flush: () => void;
    /** Deliver what is left and stop observing. Safe to call twice. */
    readonly stop: () => void;
};

ReaderSignalBroadcastErrortype

type ReaderSignalBroadcastError = {
    /** The root carries no tree id or revision — the page was not rendered with `addressed: true`. */
    readonly code: "unaddressed";
    readonly detail: string;
};

broadcastReaderSignalsfunction

Start broadcasting reader signals from the page under root.

Shown in use on What your readers do — Two: start the broadcaster, in the browser

const broadcastReaderSignals: (root: Element, options?: ReaderSignalOptions) => Result<ReaderSignalBroadcast, ReaderSignalBroadcastError>

DEFAULT_READER_SIGNAL_PATHvalue

Where a delivery goes when the host has no opinion.

const DEFAULT_READER_SIGNAL_PATH = "/api/reader-signals"

SendBeacontype

navigator.sendBeacon, narrowed to what this uses. false means it would not take it.

type SendBeacon = (url: string, body: Blob) => boolean;

PostBatchtype

The fallback. Called only when a beacon was unavailable or refused the batch.

type PostBatch = (url: string, body: string) => void;

DeliverOptionstype

type DeliverOptions = {
    /** Where to post. {@link DEFAULT_READER_SIGNAL_PATH} when absent. */
    readonly url?: string;
    /** The browser's, when absent. A test passes its own. */
    readonly beacon?: SendBeacon | null;
    /** `fetch` with `keepalive`, when absent. */
    readonly post?: PostBatch;
};

deliverReaderSignalsfunction

A send for broadcastReaderSignals that posts each batch.

const deliverReaderSignals: (options?: DeliverOptions) => ((batch: ReaderSignalBatch) => void)