@rivetjs/cdk 0.0.0-stage → 0.1.0-alpha.1

package/landmark/manager.js

@@ -0,0 +1,364 @@
+// Ported from react-aria (packages/react-aria/src/landmark/useLandmark.ts: LandmarkManager,
+// UNSTABLE_createLandmarkController), Apache-2.0, © Adobe.
+// Rivet:
+// - Plain `.ts` (browser-only code, never server-rewritten); `./index.tsx` holds `landmarkProps` (useLandmark).
+// - Landmarks hold `ref()` accessors (read as `ref()` where RA reads `ref.current`).
+// - The manager singleton lives on `document[Symbol.for("rivet-cdk-landmark-manager")]` and announces a
+//   replacement with `rv-landmark-manager-change` (RA: `react-aria-landmark-manager` /
+//   `react-aria-landmark-manager-change`): its landmarks hold `ref()` accessors, not React ref objects, so
+//   they must not join a React Aria manager on the same page. The wrap event keeps RA's name
+//   (`react-aria-landmark-navigation`, public API).
+// - `useLandmarkManager` (useSyncExternalStore) → `registerLandmark` subscribes to the manager-change
+//   event and re-registers with the new manager.
+import { getEventTarget, nodeContains } from "../utils/dom.js";
+// Increment this version number whenever the
+// LandmarkManagerApi or Landmark interfaces change.
+const LANDMARK_API_VERSION = 1;
+// Symbol under which the singleton landmark manager instance is attached to the document.
+const landmarkSymbol = Symbol.for("rivet-cdk-landmark-manager");
+const CHANGE_EVENT = "rv-landmark-manager-change";
+// RA: `process.env.NODE_ENV !== 'production'` (bundlers replace it; a missing `process` counts as dev).
+const isDev = () => globalThis.process?.env?.NODE_ENV !== "production";
+function subscribe(fn) {
+    document.addEventListener(CHANGE_EVENT, fn);
+    return () => document.removeEventListener(CHANGE_EVENT, fn);
+}
+function getLandmarkManager() {
+    if (typeof document === "undefined")
+        return null;
+    // Reuse an existing instance if it has the same or greater version.
+    const doc = document;
+    const instance = doc[landmarkSymbol];
+    if (instance && instance.version >= LANDMARK_API_VERSION)
+        return instance;
+    // Otherwise, create a new instance and dispatch an event so anything using the existing
+    // instance updates and re-registers their landmarks with the new one.
+    doc[landmarkSymbol] = new LandmarkManager();
+    document.dispatchEvent(new CustomEvent(CHANGE_EVENT));
+    return doc[landmarkSymbol];
+}
+class LandmarkManager {
+    landmarks = [];
+    isListening = false;
+    refCount = 0;
+    version = LANDMARK_API_VERSION;
+    constructor() {
+        this.f6Handler = this.f6Handler.bind(this);
+        this.focusinHandler = this.focusinHandler.bind(this);
+        this.focusoutHandler = this.focusoutHandler.bind(this);
+    }
+    setupIfNeeded() {
+        if (this.isListening)
+            return;
+        document.addEventListener("keydown", this.f6Handler, { capture: true });
+        document.addEventListener("focusin", this.focusinHandler, { capture: true });
+        document.addEventListener("focusout", this.focusoutHandler, { capture: true });
+        this.isListening = true;
+    }
+    teardownIfNeeded() {
+        if (!this.isListening || this.landmarks.length > 0 || this.refCount > 0)
+            return;
+        document.removeEventListener("keydown", this.f6Handler, { capture: true });
+        document.removeEventListener("focusin", this.focusinHandler, { capture: true });
+        document.removeEventListener("focusout", this.focusoutHandler, { capture: true });
+        this.isListening = false;
+    }
+    focusLandmark(landmark, direction) {
+        this.landmarks.find((l) => l.ref() === landmark)?.focus?.(direction);
+    }
+    /** Return set of landmarks with a specific role. */
+    getLandmarksByRole(role) {
+        return new Set(this.landmarks.filter((l) => l.role === role));
+    }
+    /** Return first landmark with a specific role. */
+    getLandmarkByRole(role) {
+        return this.landmarks.find((l) => l.role === role);
+    }
+    addLandmark(newLandmark) {
+        this.setupIfNeeded();
+        const element = newLandmark.ref();
+        if (this.landmarks.find((landmark) => landmark.ref === newLandmark.ref) || !element)
+            return;
+        if (this.landmarks.filter((landmark) => landmark.role === "main").length > 1 && isDev()) {
+            console.error('Page can contain no more than one landmark with the role "main".');
+        }
+        if (this.landmarks.length === 0) {
+            this.landmarks = [newLandmark];
+            this.checkLabels(newLandmark.role);
+            return;
+        }
+        // Binary search to insert new landmark based on position in document relative to existing landmarks.
+        // https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition
+        let start = 0;
+        let end = this.landmarks.length - 1;
+        while (start <= end) {
+            const mid = Math.floor((start + end) / 2);
+            const comparedPosition = element.compareDocumentPosition(this.landmarks[mid].ref());
+            const isNewAfterExisting = Boolean(comparedPosition & Node.DOCUMENT_POSITION_PRECEDING || comparedPosition & Node.DOCUMENT_POSITION_CONTAINS);
+            if (isNewAfterExisting)
+                start = mid + 1;
+            else
+                end = mid - 1;
+        }
+        this.landmarks.splice(start, 0, newLandmark);
+        this.checkLabels(newLandmark.role);
+    }
+    updateLandmark(landmark) {
+        const index = this.landmarks.findIndex((l) => l.ref === landmark.ref);
+        if (index >= 0) {
+            this.landmarks[index] = { ...this.landmarks[index], ...landmark };
+            this.checkLabels(this.landmarks[index].role);
+        }
+    }
+    removeLandmark(ref) {
+        this.landmarks = this.landmarks.filter((landmark) => landmark.ref !== ref);
+        this.teardownIfNeeded();
+    }
+    /**
+     * Warn if there are 2+ landmarks with the same role but no label.
+     * Labels for landmarks with the same role must also be unique.
+     *
+     * See https://www.w3.org/WAI/ARIA/apg/practices/landmark-regions/.
+     */
+    checkLabels(role) {
+        const landmarksWithRole = this.getLandmarksByRole(role);
+        if (landmarksWithRole.size > 1) {
+            const duplicatesWithoutLabel = [...landmarksWithRole].filter((landmark) => !landmark.label);
+            if (duplicatesWithoutLabel.length > 0 && isDev()) {
+                console.warn(`Page contains more than one landmark with the '${role}' role. If two or more landmarks on a page share the same role, all must be labeled with an aria-label or aria-labelledby attribute: `, duplicatesWithoutLabel.map((landmark) => landmark.ref()));
+            }
+            else if (isDev()) {
+                const labels = [...landmarksWithRole].map((landmark) => landmark.label);
+                const duplicateLabels = labels.filter((item, index) => labels.indexOf(item) !== index);
+                duplicateLabels.forEach((label) => {
+                    console.warn(`Page contains more than one landmark with the '${role}' role and '${label}' label. If two or more landmarks on a page share the same role, they must have unique labels: `, [...landmarksWithRole].filter((landmark) => landmark.label === label).map((landmark) => landmark.ref()));
+                });
+            }
+        }
+    }
+    /**
+     * Get the landmark that is the closest parent in the DOM.
+     * Returns undefined if no parent is a landmark.
+     */
+    closestLandmark(element) {
+        const landmarkMap = new Map(this.landmarks.map((l) => [l.ref(), l]));
+        let currentElement = element;
+        while (currentElement && !landmarkMap.has(currentElement) && currentElement !== document.body && currentElement.parentElement) {
+            currentElement = currentElement.parentElement;
+        }
+        return landmarkMap.get(currentElement);
+    }
+    /**
+     * Gets the next landmark, in DOM focus order, or previous if backwards is specified.
+     * If last landmark, next should be the first landmark.
+     * If not inside a landmark, will return first landmark.
+     * Returns undefined if there are no landmarks.
+     */
+    getNextLandmark(element, { backward }) {
+        const currentLandmark = this.closestLandmark(element);
+        let nextLandmarkIndex = backward ? this.landmarks.length - 1 : 0;
+        if (currentLandmark)
+            nextLandmarkIndex = this.landmarks.indexOf(currentLandmark) + (backward ? -1 : 1);
+        const wrapIfNeeded = () => {
+            // When we reach the end of the landmark sequence, fire a custom event that can be listened for by applications.
+            // If this event is canceled, we return immediately. This can be used to implement landmark navigation across iframes.
+            if (nextLandmarkIndex < 0) {
+                if (!element.dispatchEvent(new CustomEvent("react-aria-landmark-navigation", { detail: { direction: "backward" }, bubbles: true, cancelable: true }))) {
+                    return true;
+                }
+                nextLandmarkIndex = this.landmarks.length - 1;
+            }
+            else if (nextLandmarkIndex >= this.landmarks.length) {
+                if (!element.dispatchEvent(new CustomEvent("react-aria-landmark-navigation", { detail: { direction: "forward" }, bubbles: true, cancelable: true }))) {
+                    return true;
+                }
+                nextLandmarkIndex = 0;
+            }
+            if (nextLandmarkIndex < 0 || nextLandmarkIndex >= this.landmarks.length)
+                return true;
+            return false;
+        };
+        if (wrapIfNeeded())
+            return undefined;
+        // Skip over hidden landmarks.
+        const i = nextLandmarkIndex;
+        while (this.landmarks[nextLandmarkIndex].ref()?.closest("[aria-hidden=true]")) {
+            nextLandmarkIndex += backward ? -1 : 1;
+            if (wrapIfNeeded())
+                return undefined;
+            if (nextLandmarkIndex === i)
+                break;
+        }
+        return this.landmarks[nextLandmarkIndex];
+    }
+    /**
+     * Look at next landmark. If an element was previously focused inside, restore focus there.
+     * If not, focus the landmark itself.
+     * If no landmarks at all, or none with focusable elements, don't move focus.
+     */
+    f6Handler(e) {
+        if (e.key === "F6") {
+            // If alt key pressed, focus main landmark, otherwise navigate forward or backward based on shift key.
+            const handled = e.altKey ? this.focusMain() : this.navigate(getEventTarget(e), e.shiftKey);
+            if (handled) {
+                e.preventDefault();
+                e.stopPropagation();
+            }
+        }
+    }
+    focusMain() {
+        const main = this.getLandmarkByRole("main");
+        const element = main?.ref();
+        if (element && element.isConnected) {
+            this.focusLandmark(element, "forward");
+            return true;
+        }
+        return false;
+    }
+    navigate(from, backward) {
+        const nextLandmark = this.getNextLandmark(from, { backward });
+        if (!nextLandmark)
+            return false;
+        // If something was previously focused in the next landmark, then return focus to it
+        if (nextLandmark.lastFocused) {
+            const lastFocused = nextLandmark.lastFocused;
+            if (nodeContains(document.body, lastFocused)) {
+                lastFocused.focus();
+                return true;
+            }
+        }
+        // Otherwise, focus the landmark itself
+        const element = nextLandmark.ref();
+        if (element && element.isConnected) {
+            this.focusLandmark(element, backward ? "backward" : "forward");
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Sets lastFocused for a landmark, if focus is moved within that landmark.
+     * Lets the last focused landmark know it was blurred if something else is focused.
+     */
+    focusinHandler(e) {
+        const target = getEventTarget(e);
+        const currentLandmark = this.closestLandmark(target);
+        if (currentLandmark && currentLandmark.ref() !== target) {
+            this.updateLandmark({ ref: currentLandmark.ref, lastFocused: target });
+        }
+        const previousFocusedElement = e.relatedTarget;
+        if (previousFocusedElement) {
+            const closestPreviousLandmark = this.closestLandmark(previousFocusedElement);
+            if (closestPreviousLandmark && closestPreviousLandmark.ref() === previousFocusedElement)
+                closestPreviousLandmark.blur();
+        }
+    }
+    /**
+     * Track if the focus is lost to the body. If it is, do cleanup on the landmark that last had
+     * focus.
+     */
+    focusoutHandler(e) {
+        const previousFocusedElement = getEventTarget(e);
+        const nextFocusedElement = e.relatedTarget;
+        // the === document seems to be a jest thing for focus to go there on generic blur event such as landmark.blur();
+        // browsers appear to send focus instead to document.body and the relatedTarget is null when that happens
+        if (!nextFocusedElement || nextFocusedElement === document) {
+            const closestPreviousLandmark = this.closestLandmark(previousFocusedElement);
+            if (closestPreviousLandmark && closestPreviousLandmark.ref() === previousFocusedElement)
+                closestPreviousLandmark.blur();
+        }
+    }
+    createLandmarkController() {
+        let instance = this;
+        instance.refCount++;
+        instance.setupIfNeeded();
+        return {
+            navigate(direction, opts) {
+                const element = opts?.from || document.activeElement;
+                return instance.navigate(element, direction === "backward");
+            },
+            focusNext(opts) {
+                const element = opts?.from || document.activeElement;
+                return instance.navigate(element, false);
+            },
+            focusPrevious(opts) {
+                const element = opts?.from || document.activeElement;
+                return instance.navigate(element, true);
+            },
+            focusMain() {
+                return instance.focusMain();
+            },
+            dispose() {
+                if (instance) {
+                    instance.refCount--;
+                    instance.teardownIfNeeded();
+                    instance = null;
+                }
+            },
+        };
+    }
+    registerLandmark(landmark) {
+        if (this.landmarks.find((l) => l.ref === landmark.ref))
+            this.updateLandmark(landmark);
+        else
+            this.addLandmark(landmark);
+        return () => this.removeLandmark(landmark.ref);
+    }
+}
+/** Creates a LandmarkController, which allows programmatic navigation of landmarks. */
+export function UNSTABLE_createLandmarkController() {
+    // Get the current landmark manager and create a controller using it.
+    let instance = getLandmarkManager();
+    let controller = instance?.createLandmarkController();
+    const unsubscribe = subscribe(() => {
+        // If the landmark manager changes, dispose the old
+        // controller and create a new one.
+        controller?.dispose();
+        instance = getLandmarkManager();
+        controller = instance?.createLandmarkController();
+    });
+    // Return a wrapper that proxies requests to the current controller instance.
+    return {
+        navigate(direction, opts) {
+            return controller.navigate(direction, opts);
+        },
+        focusNext(opts) {
+            return controller.focusNext(opts);
+        },
+        focusPrevious(opts) {
+            return controller.focusPrevious(opts);
+        },
+        focusMain() {
+            return controller.focusMain();
+        },
+        dispose() {
+            controller?.dispose();
+            unsubscribe();
+            controller = undefined;
+            instance = null;
+        },
+    };
+}
+/** @internal Register a landmark with the current manager (and its replacements); returns the cleanup. */
+export function registerLandmark(ref, role, label, focus, isLandmarkFocused) {
+    const defaultFocus = () => {
+        isLandmarkFocused.set(true);
+        // RA focuses in an effect after `tabIndex=-1` rendered; focus now, with the attribute in place.
+        const element = ref();
+        if (element) {
+            if (!element.hasAttribute("tabindex"))
+                element.setAttribute("tabindex", "-1");
+            element.focus();
+        }
+    };
+    const blur = () => isLandmarkFocused.set(false);
+    const register = () => getLandmarkManager()?.registerLandmark({ ref, label, role, focus: focus || defaultFocus, blur });
+    let unregister = register();
+    const unsubscribe = subscribe(() => {
+        unregister?.();
+        unregister = register();
+    });
+    return () => {
+        unsubscribe();
+        unregister?.();
+    };
+}

package/layout/index.d.ts

@@ -0,0 +1,90 @@
+import { type Signal } from "@rivetjs/reactivity";
+/** Material Design breakpoints (media queries). PascalCase: used like an enum. */
+export declare const Breakpoints: {
+    readonly XSmall: "(max-width: 599.98px)";
+    readonly Small: "(min-width: 600px) and (max-width: 959.98px)";
+    readonly Medium: "(min-width: 960px) and (max-width: 1279.98px)";
+    readonly Large: "(min-width: 1280px) and (max-width: 1919.98px)";
+    readonly XLarge: "(min-width: 1920px)";
+    readonly Handset: string;
+    readonly Tablet: string;
+    readonly Web: string;
+    readonly HandsetPortrait: "(max-width: 599.98px) and (orientation: portrait)";
+    readonly TabletPortrait: "(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait)";
+    readonly WebPortrait: "(min-width: 840px) and (orientation: portrait)";
+    readonly HandsetLandscape: "(max-width: 959.98px) and (orientation: landscape)";
+    readonly TabletLandscape: "(min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)";
+    readonly WebLandscape: "(min-width: 1280px) and (orientation: landscape)";
+};
+/** The `MediaQueryList` surface the observer uses (`addListener` for older / fake lists). */
+export interface MediaQueryListLike {
+    readonly matches: boolean;
+    readonly media: string;
+    addListener?(listener: (event: {
+        matches: boolean;
+    }) => void): void;
+    removeListener?(listener: (event: {
+        matches: boolean;
+    }) => void): void;
+    addEventListener?(type: "change", listener: (event: {
+        matches: boolean;
+    }) => void): void;
+    removeEventListener?(type: "change", listener: (event: {
+        matches: boolean;
+    }) => void): void;
+}
+/** Angular `MediaMatcher`: `matchMedia(query)`. */
+export interface MediaMatcher {
+    matchMedia(query: string): MediaQueryListLike;
+}
+/** A `MediaMatcher` (Angular service). `nonce`: CSP nonce for the workaround `<style>` (default: `getNonce()`). */
+export declare function createMediaMatcher(options?: {
+    nonce?: string | null;
+}): MediaMatcher;
+/** The current state of a layout breakpoint. */
+export interface BreakpointState {
+    /** Whether any of the queries matches. */
+    matches: boolean;
+    /** Each query given to `observe`, with its current matched state. */
+    breakpoints: {
+        [key: string]: boolean;
+    };
+}
+/** Minimal observable (the RxJS subset `observe()` returns). */
+export interface BreakpointObservable {
+    subscribe(observer?: ((state: BreakpointState) => void) | {
+        next?: (state: BreakpointState) => void;
+        complete?: () => void;
+    }): {
+        unsubscribe(): void;
+    };
+}
+/** Angular `BreakpointObserver`. */
+export interface BreakpointObserver {
+    /** Whether one or more media queries match now (comma-separated queries count separately). */
+    isMatched(value: string | readonly string[]): boolean;
+    /**
+     * Results for `value` (one or more queries): the current state on subscribe, then one emission per
+     * batch of changes (debounced to a macrotask, as `debounceTime(0)`).
+     */
+    observe(value: string | readonly string[]): BreakpointObservable;
+    /** `ngOnDestroy`: completes every subscription and removes the media query listeners. */
+    destroy(): void;
+}
+/** A `BreakpointObserver` over `matcher` (default: a new `createMediaMatcher()`). */
+export declare function createBreakpointObserver(matcher?: MediaMatcher): BreakpointObserver;
+/** The shared `BreakpointObserver` (Angular root service), created on first use. */
+export declare function breakpointObserver(): BreakpointObserver;
+/**
+ * Signal of the `BreakpointState` for `value`, for bindings. Server and before `connect()`: built from
+ * `initial` (a boolean for every query, or per query; default false — mobile-first markup). Call
+ * `connect()` in a client effect (`clientEffect(() => bp.connect())`): it reads the real state and
+ * follows changes; it returns the disconnect function.
+ */
+export declare function breakpointState(value: string | readonly string[], options?: {
+    initial?: boolean | Record<string, boolean>;
+    observer?: () => BreakpointObserver;
+}): {
+    state: Signal<BreakpointState>;
+    connect(): () => void;
+};

package/layout/index.js

@@ -0,0 +1,207 @@
+// Ported from angular/components src/cdk/layout (MIT, © Google LLC): `Breakpoints`, `MediaMatcher`,
+// `BreakpointObserver`, `BreakpointState`.
+//
+// Rivet: prefer CSS media / container queries — they need no JavaScript and no resume state. Use
+// this module when a handler or a client effect must branch on a breakpoint. Services become
+// factories (`createMediaMatcher`, `createBreakpointObserver`; `breakpointObserver()` is the shared
+// one); RxJS `Observable<BreakpointState>` becomes a minimal observable with the same emission
+// semantics (current state on subscribe, then debounced changes, completion on `destroy()`), and
+// `breakpointState(value, …)` gives a signal for bindings. Server: no `matchMedia` → the noop
+// matcher (only `all` / "" match), like Angular's non-browser platform; pass `initial` to choose the
+// server-rendered state (mobile-first default: nothing matches).
+import { signal } from "@rivetjs/reactivity";
+import { coerceArray } from "../coercion/index.js";
+import { getPlatform } from "../platform/index.js";
+import { getNonce } from "../utils/dom.js";
+/** Material Design breakpoints (media queries). PascalCase: used like an enum. */
+export const Breakpoints = {
+    XSmall: "(max-width: 599.98px)",
+    Small: "(min-width: 600px) and (max-width: 959.98px)",
+    Medium: "(min-width: 960px) and (max-width: 1279.98px)",
+    Large: "(min-width: 1280px) and (max-width: 1919.98px)",
+    XLarge: "(min-width: 1920px)",
+    Handset: "(max-width: 599.98px) and (orientation: portrait), " + "(max-width: 959.98px) and (orientation: landscape)",
+    Tablet: "(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait), " + "(min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)",
+    Web: "(min-width: 840px) and (orientation: portrait), " + "(min-width: 1280px) and (orientation: landscape)",
+    HandsetPortrait: "(max-width: 599.98px) and (orientation: portrait)",
+    TabletPortrait: "(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait)",
+    WebPortrait: "(min-width: 840px) and (orientation: portrait)",
+    HandsetLandscape: "(max-width: 959.98px) and (orientation: landscape)",
+    TabletLandscape: "(min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)",
+    WebLandscape: "(min-width: 1280px) and (orientation: landscape)",
+};
+// Global registry of injected empty `@media` rules (WebKit / Blink workaround).
+const mediaQueriesForWebkitCompatibility = new Set();
+let mediaQueryStyleNode;
+/**
+ * An empty `@media` rule per query: WebKit only fires `matchMedia` listeners for queries with a rule;
+ * Blink may stop firing when no rule matches an element (one rule targets `body`).
+ */
+function createEmptyStyleRule(query, nonce) {
+    if (mediaQueriesForWebkitCompatibility.has(query))
+        return;
+    try {
+        if (!mediaQueryStyleNode) {
+            mediaQueryStyleNode = document.createElement("style");
+            if (nonce)
+                mediaQueryStyleNode.setAttribute("nonce", nonce);
+            mediaQueryStyleNode.setAttribute("type", "text/css");
+            document.head.appendChild(mediaQueryStyleNode);
+        }
+        if (mediaQueryStyleNode.sheet) {
+            // Curly braces dropped against injection: they are not valid media query syntax.
+            mediaQueryStyleNode.sheet.insertRule(`@media ${query.replace(/[{}]/g, "")} {body{ }}`, 0);
+            mediaQueriesForWebkitCompatibility.add(query);
+        }
+    }
+    catch (e) {
+        console.error(e);
+    }
+}
+/** No-op `matchMedia` for non-browser platforms: only `all` and "" match. */
+function noopMatchMedia(query) {
+    return { matches: query === "all" || query === "", media: query, addListener: () => { }, removeListener: () => { } };
+}
+/** A `MediaMatcher` (Angular service). `nonce`: CSP nonce for the workaround `<style>` (default: `getNonce()`). */
+export function createMediaMatcher(options = {}) {
+    const platform = getPlatform();
+    const native = platform.isBrowser && typeof window !== "undefined" && window.matchMedia ? window.matchMedia.bind(window) : noopMatchMedia;
+    return {
+        matchMedia(query) {
+            if (platform.WEBKIT || platform.BLINK)
+                createEmptyStyleRule(query, options.nonce === undefined ? getNonce() : options.nonce);
+            return native(query);
+        },
+    };
+}
+/** Split comma-separated queries into separate queries (each gets its own `MediaQueryList`). */
+function splitQueries(queries) {
+    return queries.flatMap((query) => query.split(",")).map((query) => query.trim());
+}
+function listen(mql, handler) {
+    if (mql.addEventListener)
+        mql.addEventListener("change", handler);
+    else
+        mql.addListener?.(handler);
+}
+function unlisten(mql, handler) {
+    if (mql.removeEventListener)
+        mql.removeEventListener("change", handler);
+    else
+        mql.removeListener?.(handler);
+}
+/** A `BreakpointObserver` over `matcher` (default: a new `createMediaMatcher()`). */
+export function createBreakpointObserver(matcher = createMediaMatcher()) {
+    const queries = new Map();
+    const completions = new Set();
+    let destroyed = false;
+    const register = (query) => {
+        let entry = queries.get(query);
+        if (entry)
+            return entry;
+        const mql = matcher.matchMedia(query);
+        const listeners = new Set();
+        const handler = () => {
+            for (const listener of [...listeners])
+                listener();
+        };
+        queries.set(query, (entry = { mql, listeners, handler }));
+        return entry;
+    };
+    return {
+        isMatched(value) {
+            return splitQueries(coerceArray(value)).some((query) => register(query).mql.matches);
+        },
+        observe(value) {
+            const list = splitQueries(coerceArray(value));
+            const entries = list.map(register);
+            const state = () => {
+                const response = { matches: false, breakpoints: {} };
+                list.forEach((query, i) => {
+                    const matches = entries[i].mql.matches;
+                    response.matches = response.matches || matches;
+                    response.breakpoints[query] = matches;
+                });
+                return response;
+            };
+            return {
+                subscribe(observer) {
+                    const next = typeof observer === "function" ? observer : observer?.next;
+                    const complete = typeof observer === "function" ? undefined : observer?.complete;
+                    if (destroyed) {
+                        complete?.();
+                        return { unsubscribe() { } };
+                    }
+                    let timer;
+                    let closed = false;
+                    const onChange = () => {
+                        if (closed || timer !== undefined)
+                            return;
+                        timer = setTimeout(() => {
+                            timer = undefined;
+                            if (!closed)
+                                next?.(state());
+                        }, 0);
+                    };
+                    for (const entry of entries) {
+                        if (!entry.listeners.size)
+                            listen(entry.mql, entry.handler);
+                        entry.listeners.add(onChange);
+                    }
+                    const unsubscribe = () => {
+                        if (closed)
+                            return;
+                        closed = true;
+                        clearTimeout(timer);
+                        completions.delete(finish);
+                        for (const entry of entries) {
+                            entry.listeners.delete(onChange);
+                            if (!entry.listeners.size)
+                                unlisten(entry.mql, entry.handler);
+                        }
+                    };
+                    const finish = () => {
+                        unsubscribe();
+                        complete?.();
+                    };
+                    completions.add(finish);
+                    next?.(state());
+                    return { unsubscribe };
+                },
+            };
+        },
+        destroy() {
+            destroyed = true;
+            for (const finish of [...completions])
+                finish();
+        },
+    };
+}
+let shared;
+/** The shared `BreakpointObserver` (Angular root service), created on first use. */
+export function breakpointObserver() {
+    return (shared ??= createBreakpointObserver());
+}
+/**
+ * Signal of the `BreakpointState` for `value`, for bindings. Server and before `connect()`: built from
+ * `initial` (a boolean for every query, or per query; default false — mobile-first markup). Call
+ * `connect()` in a client effect (`clientEffect(() => bp.connect())`): it reads the real state and
+ * follows changes; it returns the disconnect function.
+ */
+export function breakpointState(value, options = {}) {
+    const list = splitQueries(coerceArray(value));
+    const initial = options.initial ?? false;
+    const breakpoints = {};
+    for (const query of list)
+        breakpoints[query] = typeof initial === "boolean" ? initial : !!initial[query];
+    const state = signal({ matches: Object.values(breakpoints).some(Boolean), breakpoints });
+    return {
+        state,
+        connect() {
+            const subscription = (options.observer ?? breakpointObserver)()
+                .observe(list)
+                .subscribe((next) => state.set(next));
+            return () => subscription.unsubscribe();
+        },
+    };
+}