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

package/portal/index.jsx

@@ -0,0 +1,83 @@
+// Portals that render on the server. `<Portal>` renders its children inside an owned
+// `<div data-rivet-portal>`: in place in the server HTML (visible without JavaScript, indexable),
+// then moved to its mount (default `document.body`) — at `load` on a resumed page, right after
+// mounting when rendered in the browser. Its owner's cleanup removes it (a `<Show>` turning false,
+// a re-created region, a client navigation). Because the move is a resumable `clientEffect`, a portal
+// behind `<Show when>` works whether `when` starts true (server-rendered branch: moved at load) or
+// false (created in the browser). Server markers inside the host stay balanced, so resumption is
+// unaffected by the move.
+//
+// Also: `PortalProvider` (React Aria `UNSAFE_PortalProvider`: default container for portals below
+// it), `Overlay` (React Aria `Overlay`: a portal + focus containment / restoration).
+//
+// `PortalProvider`, `Overlay` ported from @react-aria/overlays (PortalProvider.tsx, Overlay.tsx),
+// Apache-2.0, © Adobe. Imperative portals / outlets (Angular CDK): ./portal-outlet.ts.
+import { createContext, useContext } from "@rivetjs/reactivity";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { clientEffect, ref, Provider } from "@rivetjs/runtime/dom";
+import { FocusScope } from "../focus/focus-scope.jsx";
+import { ClearPressResponder } from "../interactions/pressable.jsx";
+import { resolveMount } from "./portal-mount.js";
+import { renderSlot } from "@rivetjs/runtime/slot";
+export { resolveMount };
+/** Default mount for portals below a `PortalProvider` (`null`: none). */
+export const PortalContext = resumableContext(createContext(null, { id: "rv-portal" }));
+/** Set the container of every `Portal` / `Overlay` / `OverlayContainer` rendered below it. */
+export function PortalProvider(props) {
+    // Plain children are a lazy compiler slot rendered under the provider; function children work too.
+    const children = props.children;
+    return (<Provider token={PortalContext} value={props.container ?? null}>
+      {renderSlot(children)}
+    </Provider>);
+}
+/**
+ * Rivet: optional hooks of the overlay layer, unset by default (cdk alone pays one property read per move).
+ * `place(host, from)` runs right after a `<Portal>` host moved from its in-place parent `from` (the trigger's subtree,
+ * still connected) to its mount; a styled layer copies scope attributes there (`@rivetjs/ui` stamps its theme scope).
+ */
+export const portalHooks = {};
+/**
+ * Render `children` at the end of `mount` (default `document.body`), inside a
+ * `<div data-rivet-portal>`. Server: rendered in place and moved at `load`.
+ */
+export function Portal(props) {
+    const host = ref();
+    const mount = props.mount ?? useContext(PortalContext), onPlaced = props.onPlaced;
+    clientEffect(() => {
+        const element = host();
+        if (!element)
+            return;
+        const target = resolveMount(mount);
+        if (element.parentNode !== target) {
+            // Moving a node blurs focus inside it (content that focused itself on mount, e.g. a menu item).
+            const focused = element.ownerDocument.activeElement;
+            const inside = !!focused && element.contains(focused), from = element.parentElement;
+            target.append(element);
+            portalHooks.place?.(element, from);
+            if (inside && element.ownerDocument.activeElement !== focused)
+                focused.focus({ preventScroll: true });
+        }
+        onPlaced?.();
+        return () => element.remove();
+    }, { when: "load" });
+    return (<div data-rivet-portal="" class={props.class} ref={host}>
+      {props.children}
+    </div>);
+}
+/**
+ * React Aria `Overlay`: a `Portal` with a `FocusScope` — focus returns to the element focused before
+ * it rendered when it goes away, and with `shouldContainFocus` Tab stays inside. Its content is wrapped
+ * in a `ClearPressResponder` (RA): press props of the trigger's `PressResponder` (DialogTrigger, …) do
+ * not reach buttons inside the overlay.
+ */
+export function Overlay(props) {
+    const children = props.children, exiting = props.isExiting;
+    const isExiting = typeof exiting === "function" ? !!exiting() : !!exiting;
+    return (<Portal mount={props.portalContainer} onPlaced={props.onPlaced}>
+      <ClearPressResponder>
+        {props.disableFocusManagement ? (children) : (<FocusScope restoreFocus contain={!!props.shouldContainFocus && !isExiting}>
+            {children}
+          </FocusScope>)}
+      </ClearPressResponder>
+    </Portal>);
+}

package/portal/portal-mount.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Where a portal renders: a CSS selector (resolved in the browser; serializable, so it works on
+ * resumed pages), an element `ref()`, an element or a function returning one (browser-rendered
+ * portals only: elements and plain functions do not serialize).
+ */
+export type PortalMount = string | Element | null | undefined | (() => Element | null | undefined);
+/** Resolve a mount to an element (`document.body` when missing). */
+export declare function resolveMount(mount: PortalMount): Element;

package/portal/portal-mount.js

@@ -0,0 +1,7 @@
+// Portal mount resolution (browser only), kept out of the component module.
+/** Resolve a mount to an element (`document.body` when missing). */
+export function resolveMount(mount) {
+    const value = typeof mount === "function" ? mount() : mount;
+    const element = typeof value === "string" ? document.querySelector(value) : value;
+    return element ?? document.body;
+}

package/portal/portal-outlet.d.ts

@@ -0,0 +1,88 @@
+import { type Owner } from "@rivetjs/reactivity";
+/** Attached view returned by an outlet (Angular `ComponentRef` / `EmbeddedViewRef`). */
+export interface PortalViewRef<C = unknown> {
+    /** Root nodes rendered into the outlet. */
+    readonly rootNodes: Node[];
+    /** Context (TemplatePortal) or props (ComponentPortal) it was rendered with. */
+    readonly context: C | undefined;
+    /** Destroy the view (dispose its owner, remove its nodes). */
+    destroy(): void;
+    /** Run `fn` when the view is destroyed. */
+    onDestroy(fn: () => void): void;
+    readonly destroyed: boolean;
+}
+export declare const throwNullPortalError: () => never;
+export declare const throwPortalAlreadyAttachedError: () => never;
+export declare const throwPortalOutletAlreadyDisposedError: () => never;
+export declare const throwUnknownPortalTypeError: () => never;
+export declare const throwNullPortalOutletError: () => never;
+export declare const throwNoPortalAttachedError: () => never;
+/** Something a portal can be attached to. */
+export interface PortalOutlet {
+    attach(portal: Portal<unknown>): unknown;
+    detach(): unknown;
+    dispose(): void;
+    hasAttached(): boolean;
+}
+/** Content that can be attached to a `PortalOutlet`. */
+export declare abstract class Portal<T> {
+    private _attachedHost;
+    /** Attach to `host`. */
+    attach(host: PortalOutlet): T;
+    /** Detach from the host it is attached to. */
+    detach(): void;
+    /** Whether it is attached to a host. */
+    get isAttached(): boolean;
+    /** Set the host reference without attaching (outlets call this). */
+    setAttachedHost(host: PortalOutlet | null): void;
+}
+/** A component rendered into an outlet. `owner` (from `getOwner()`) keeps the caller's contexts. */
+export declare class ComponentPortal<P = Record<string, unknown>> extends Portal<PortalViewRef<P>> {
+    readonly component: (props: P) => unknown;
+    props: P | undefined;
+    owner: Owner | null | undefined;
+    constructor(component: (props: P) => unknown, props?: P, owner?: Owner | null);
+}
+/** A render function (Angular `TemplateRef`) rendered into an outlet with an optional context. */
+export declare class TemplatePortal<C = undefined> extends Portal<PortalViewRef<C>> {
+    readonly template: (context: C) => unknown;
+    context: C | undefined;
+    owner: Owner | null | undefined;
+    constructor(template: (context: C) => unknown, context?: C, owner?: Owner | null);
+    /** Attach, optionally with a different context. */
+    attach(host: PortalOutlet, context?: C | undefined): PortalViewRef<C>;
+    detach(): void;
+}
+/** An existing element moved into the outlet (and back to where it was on detach). */
+export declare class DomPortal<T extends Element = HTMLElement> extends Portal<T> {
+    readonly element: T;
+    constructor(element: T);
+}
+/** Outlet base: attach bookkeeping and the dispose function of the attached content. */
+export declare abstract class BasePortalOutlet implements PortalOutlet {
+    protected _attachedPortal: Portal<unknown> | null;
+    private _disposeFn;
+    private _isDisposed;
+    hasAttached(): boolean;
+    attach<P>(portal: ComponentPortal<P>): PortalViewRef<P>;
+    attach<C>(portal: TemplatePortal<C>): PortalViewRef<C>;
+    attach<T extends Element>(portal: DomPortal<T>): T;
+    attach(portal: Portal<unknown>): unknown;
+    abstract attachComponentPortal<P>(portal: ComponentPortal<P>): PortalViewRef<P>;
+    abstract attachTemplatePortal<C>(portal: TemplatePortal<C>): PortalViewRef<C>;
+    attachDomPortal: null | ((portal: DomPortal<Element>) => unknown);
+    detach(): void;
+    dispose(): void;
+    setDisposeFn(fn: () => void): void;
+    private _invokeDisposeFn;
+}
+/** An outlet rendering into an element (Angular `DomPortalOutlet`). Browser only. */
+export declare class DomPortalOutlet extends BasePortalOutlet {
+    readonly outletElement: Element;
+    constructor(outletElement: Element);
+    attachComponentPortal<P>(portal: ComponentPortal<P>): PortalViewRef<P>;
+    attachTemplatePortal<C>(portal: TemplatePortal<C>): PortalViewRef<C>;
+    attachDomPortal: (portal: DomPortal<Element>) => Element;
+    /** Detach and remove the outlet element. */
+    dispose(): void;
+}

package/portal/portal-outlet.js

@@ -0,0 +1,222 @@
+// Imperative portals and outlets (Angular CDK portal): a `Portal` is content that can be attached
+// to a `PortalOutlet` somewhere else in the document. `ComponentPortal` = a Rivet component + props,
+// `TemplatePortal` = a render function + context (Angular's TemplateRef), `DomPortal` = an existing
+// element moved into the outlet and back. `DomPortalOutlet` renders into an element with the
+// runtime's `mount`. Browser only (outlets render client-side); for server-visible content use the
+// `<Portal>` component (`@rivetjs/cdk/portal`).
+//
+// Ported from @angular/cdk/portal (portal.ts, dom-portal-outlet.ts, portal-errors.ts), MIT, © Google LLC.
+import { runWithOwner } from "@rivetjs/reactivity";
+import { mount } from "@rivetjs/runtime/dom";
+export const throwNullPortalError = () => {
+    throw Error("Must provide a portal to attach");
+};
+export const throwPortalAlreadyAttachedError = () => {
+    throw Error("Host already has a portal attached");
+};
+export const throwPortalOutletAlreadyDisposedError = () => {
+    throw Error("This PortalOutlet has already been disposed");
+};
+export const throwUnknownPortalTypeError = () => {
+    throw Error("Attempting to attach an unknown Portal type. BasePortalOutlet accepts either a ComponentPortal, a TemplatePortal or a DomPortal.");
+};
+export const throwNullPortalOutletError = () => {
+    throw Error("Attempting to attach a portal to a null PortalOutlet");
+};
+export const throwNoPortalAttachedError = () => {
+    throw Error("Attempting to detach a portal that is not attached to a host");
+};
+/** Content that can be attached to a `PortalOutlet`. */
+export class Portal {
+    _attachedHost = null;
+    /** Attach to `host`. */
+    attach(host) {
+        if (host == null)
+            throwNullPortalOutletError();
+        if (host.hasAttached())
+            throwPortalAlreadyAttachedError();
+        this._attachedHost = host;
+        return host.attach(this);
+    }
+    /** Detach from the host it is attached to. */
+    detach() {
+        const host = this._attachedHost;
+        if (host != null) {
+            this._attachedHost = null;
+            host.detach();
+        }
+        else
+            throwNoPortalAttachedError();
+    }
+    /** Whether it is attached to a host. */
+    get isAttached() {
+        return this._attachedHost != null;
+    }
+    /** Set the host reference without attaching (outlets call this). */
+    setAttachedHost(host) {
+        this._attachedHost = host;
+    }
+}
+/** A component rendered into an outlet. `owner` (from `getOwner()`) keeps the caller's contexts. */
+export class ComponentPortal extends Portal {
+    component;
+    props;
+    owner;
+    constructor(component, props, owner) {
+        super();
+        this.component = component;
+        this.props = props;
+        this.owner = owner;
+    }
+}
+/** A render function (Angular `TemplateRef`) rendered into an outlet with an optional context. */
+export class TemplatePortal extends Portal {
+    template;
+    context;
+    owner;
+    constructor(template, context, owner) {
+        super();
+        this.template = template;
+        this.context = context;
+        this.owner = owner;
+    }
+    /** Attach, optionally with a different context. */
+    attach(host, context = this.context) {
+        this.context = context;
+        return super.attach(host);
+    }
+    detach() {
+        this.context = undefined;
+        return super.detach();
+    }
+}
+/** An existing element moved into the outlet (and back to where it was on detach). */
+export class DomPortal extends Portal {
+    element;
+    constructor(element) {
+        super();
+        this.element = element;
+    }
+}
+/** Outlet base: attach bookkeeping and the dispose function of the attached content. */
+export class BasePortalOutlet {
+    _attachedPortal = null;
+    _disposeFn = null;
+    _isDisposed = false;
+    hasAttached() {
+        return !!this._attachedPortal;
+    }
+    attach(portal) {
+        if (!portal)
+            throwNullPortalError();
+        if (this.hasAttached())
+            throwPortalAlreadyAttachedError();
+        if (this._isDisposed)
+            throwPortalOutletAlreadyDisposedError();
+        if (portal instanceof ComponentPortal) {
+            this._attachedPortal = portal;
+            return this.attachComponentPortal(portal);
+        }
+        if (portal instanceof TemplatePortal) {
+            this._attachedPortal = portal;
+            return this.attachTemplatePortal(portal);
+        }
+        if (this.attachDomPortal && portal instanceof DomPortal) {
+            this._attachedPortal = portal;
+            return this.attachDomPortal(portal);
+        }
+        return throwUnknownPortalTypeError();
+    }
+    attachDomPortal = null;
+    detach() {
+        if (this._attachedPortal) {
+            this._attachedPortal.setAttachedHost(null);
+            this._attachedPortal = null;
+        }
+        this._invokeDisposeFn();
+    }
+    dispose() {
+        if (this.hasAttached())
+            this.detach();
+        this._invokeDisposeFn();
+        this._isDisposed = true;
+    }
+    setDisposeFn(fn) {
+        this._disposeFn = fn;
+    }
+    _invokeDisposeFn() {
+        if (this._disposeFn) {
+            this._disposeFn();
+            this._disposeFn = null;
+        }
+    }
+}
+/** Render `render()` into `outlet` (in `owner`, for contexts) and wrap it as a view. */
+function renderView(outlet, render, context, owner) {
+    const before = outlet.lastChild;
+    const stop = runWithOwner(owner ?? null, () => mount(render, outlet));
+    const rootNodes = [];
+    for (let node = before ? before.nextSibling : outlet.firstChild; node; node = node.nextSibling)
+        if (node.nodeType !== 8)
+            rootNodes.push(node);
+    const listeners = [];
+    let destroyed = false;
+    return {
+        rootNodes,
+        context,
+        get destroyed() {
+            return destroyed;
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            stop();
+            for (const fn of listeners.splice(0))
+                fn();
+        },
+        onDestroy(fn) {
+            listeners.push(fn);
+        },
+    };
+}
+/** An outlet rendering into an element (Angular `DomPortalOutlet`). Browser only. */
+export class DomPortalOutlet extends BasePortalOutlet {
+    outletElement;
+    constructor(outletElement) {
+        super();
+        this.outletElement = outletElement;
+    }
+    attachComponentPortal(portal) {
+        const view = renderView(this.outletElement, () => portal.component(portal.props ?? {}), portal.props, portal.owner);
+        this.setDisposeFn(() => view.destroy());
+        this._attachedPortal = portal;
+        return view;
+    }
+    attachTemplatePortal(portal) {
+        const view = renderView(this.outletElement, () => portal.template(portal.context), portal.context, portal.owner);
+        this.setDisposeFn(() => view.destroy());
+        this._attachedPortal = portal;
+        return view;
+    }
+    attachDomPortal = (portal) => {
+        const element = portal.element;
+        if (!element.parentNode)
+            throw Error("DOM portal content must be attached to a parent node.");
+        // Anchor at the element's previous position, to put it back on detach.
+        const anchorNode = this.outletElement.ownerDocument.createComment("dom-portal");
+        element.parentNode.insertBefore(anchorNode, element);
+        this.outletElement.appendChild(element);
+        this._attachedPortal = portal;
+        super.setDisposeFn(() => {
+            if (anchorNode.parentNode)
+                anchorNode.parentNode.replaceChild(element, anchorNode);
+        });
+        return element;
+    };
+    /** Detach and remove the outlet element. */
+    dispose() {
+        super.dispose();
+        this.outletElement.remove();
+    }
+}

package/preview-trigger/behaviour.d.ts

@@ -0,0 +1,70 @@
+import { type FocusableElement } from "../interactions/utils.js";
+import type { ElementSource } from "../overlay/position.js";
+import { type TooltipTriggerProps, type TooltipTriggerState } from "../state/tooltip.js";
+export interface AriaPreviewTriggerProps extends Omit<TooltipTriggerProps, "trigger" | "shouldCloseOnPress"> {
+}
+export interface AriaPreviewTriggerOptions extends AriaPreviewTriggerProps {
+    /** A ref to the trigger element (e.g. a Link). */
+    triggerRef: ElementSource<FocusableElement>;
+    /** A ref to the popover element. */
+    popoverRef: ElementSource<HTMLElement>;
+    /** Rivet: the popover id (RA: `useId()`), so the server and the browser agree. */
+    popoverId: string;
+}
+export interface PreviewTriggerTriggerAria {
+    /** Props for the trigger element (e.g. a Link). */
+    triggerProps: Record<string, unknown>;
+    /** Props for the popover overlay element. */
+    popoverProps: {
+        id: string;
+        onFocusWithin: () => void;
+        onBlurWithin: () => void;
+    };
+}
+/** Cancel a pending close and keep the preview open. */
+export declare function previewTriggerKeepOpen(state: TooltipTriggerState): void;
+/**
+ * Close the preview unless something is still keeping it open: the pointer is within the safe area, or
+ * focus is within the trigger or popover. During focus transitions the active element may briefly be
+ * the body; the popover's focusin handler re-opens in that case (focus moving in).
+ */
+export declare function previewTriggerCheckClose(state: TooltipTriggerState, options: Pick<AriaPreviewTriggerOptions, "triggerRef" | "popoverRef">): void;
+/** useHover `onHoverStart`. */
+export declare function previewTriggerHoverStart(state: TooltipTriggerState): void;
+/** useHover `onHoverEnd`. */
+export declare function previewTriggerHoverEnd(state: TooltipTriggerState): void;
+/** The trigger's `onPointerEnter` (useHover). */
+export declare function previewTriggerPointerEnter(e: PointerEvent, props: AriaPreviewTriggerProps, state: TooltipTriggerState): void;
+/** The trigger's `onPointerLeave` (useHover). */
+export declare function previewTriggerPointerLeave(e: PointerEvent, props: AriaPreviewTriggerProps, state: TooltipTriggerState): void;
+/** The trigger's `onFocus`. */
+export declare function previewTriggerFocus(e: FocusEvent, options: Pick<AriaPreviewTriggerOptions, "popoverRef" | "isDisabled">, state: TooltipTriggerState): void;
+/** The trigger's `onBlur`. */
+export declare function previewTriggerBlur(_e: FocusEvent, options: Pick<AriaPreviewTriggerOptions, "triggerRef" | "popoverRef">, state: TooltipTriggerState): void;
+/** The trigger's `on:rv-focus-scope-restore` (RA `react-aria-focus-scope-restore`): restore focus without reopening. */
+export declare function previewTriggerFocusScopeRestore(e: Event, state: TooltipTriggerState): void;
+/**
+ * The trigger's `onKeyDown`: move focus from the link into the preview when the user presses Tab while
+ * it is open (tabbing back out of the popover is handled by the popover's own FocusScope); Escape closes.
+ */
+export declare function previewTriggerKeyDown(e: KeyboardEvent, options: Pick<AriaPreviewTriggerOptions, "popoverRef">, state: TooltipTriggerState): void;
+/** useLongPress `onLongPress` (touch): open the preview and move focus into it once it opens. */
+export declare function previewTriggerLongPress(state: TooltipTriggerState): void;
+/**
+ * Rivet (delegated useLongPress `{ pointerType: "touch" }`): the wrapper's `onPointerDown` — a touch held
+ * for 500 ms opens the preview (no click / context menu after it), released earlier it does nothing.
+ */
+export declare function previewTriggerTouchStart(e: PointerEvent, props: AriaPreviewTriggerProps, state: TooltipTriggerState): void;
+/**
+ * RA's effects while open (call from the popover's client effect; returns the release): the safe area
+ * connecting the link and the popover keeps the preview open while the pointer moves between them (even
+ * diagonally, any placement, even with closeDelay 0); after a long press, focus moves to the popover.
+ */
+export declare function attachPreviewTrigger(state: TooltipTriggerState, options: AriaPreviewTriggerOptions): () => void;
+/**
+ * Provides the behavior and accessibility implementation for a preview trigger (React Aria
+ * `usePreviewTrigger`). The bag's closures are created in this `.tsx` module, so resumed bindings may
+ * capture them. Long press: wire
+ * `previewTriggerTouchStart` on the trigger's `onPointerDown`.
+ */
+export declare function previewTriggerProps(options: AriaPreviewTriggerOptions, state: TooltipTriggerState): PreviewTriggerTriggerAria;