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

package/disclosure/index.jsx

@@ -0,0 +1,300 @@
+// Ported from react-aria-components Disclosure.tsx (DisclosureGroup, Disclosure, DisclosurePanel;
+// DisclosureGroupStateContext, DisclosureContext, DisclosureStateContext)
+// (packages/react-aria-components/src/Disclosure.tsx), Apache-2.0, © Adobe.
+//
+// RAC composition: `<DisclosureGroup><Disclosure id><Heading><Button slot="trigger"/></Heading>
+// <DisclosurePanel/></Disclosure>…</DisclosureGroup>`.
+// Rivet:
+// - state = `@rivetjs/cdk/state/disclosure` (react-stately useDisclosureState / useDisclosureGroupState):
+//   `isExpanded` / `expandedKeys` are plain values (controlled) or Signals (two-way).
+// - useDisclosure = `disclosureProps` (./behaviour.tsx): the trigger props reach the `<Button slot="trigger">`
+//   through ButtonContext (accessor `aria-expanded`); the panel's `hidden` binding runs the upstream layout
+//   effect (size variables, animations, `hidden="until-found"`) only on a change; the server renders the
+//   final `hidden` / `aria-expanded` / `data-expanded`, so nothing runs before the first press.
+// - Inside a group a Disclosure's `isExpanded` is the group's `expandedKeys.has(id)` (an accessor) and its
+//   changes toggle the group key (RAC).
+// - `data-focus-visible-within` is written by focusin / focusout handlers (RAC useFocusRing({within})).
+// - `class` = RAC `className` (defaults `rv-DisclosureGroup`, `rv-Disclosure`, `rv-DisclosurePanel`).
+// `render` (RAC DOMRenderProps) on DisclosureGroup / Disclosure / DisclosurePanel (their `<div>`): given, the attributes object goes to `render(attrs, renderProps)`.
+// Deviations: DOM ids derive from one generated id per disclosure (`<id>-trigger`,
+//   `<id>-panel`) instead of two `useId`s.
+import { _regionState, createContext, getOwner, onCleanup, signal, untrack, useContext } from "@rivetjs/reactivity";
+import { clientEffect, ref as createRef } from "@rivetjs/runtime/dom";
+import { isSlot } from "@rivetjs/runtime/slot";
+import { resumableContext } from "@rivetjs/runtime/resume-format";
+import { DEFAULT_SLOT, Provider, contextProps, mergeRefValues, renderProps, } from "../slots/index.jsx";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { dataBool, setDataAttr } from "../utils/data-attrs.jsx";
+import { createId } from "../utils/id.js";
+import { isFocusVisible } from "../interactions/focus-visible.jsx";
+import { ButtonContext } from "../button/index.jsx";
+import { allowsMultiple, createDisclosureGroupState, createDisclosureState, closeAll, isGroupDisabled, isKeyExpanded, openAll, registerDisclosure, setExpandedKeys, toggleKey, unregisterDisclosure, } from "../state/disclosure.js";
+import { disclosurePanelBeforeMatch, disclosurePanelStyle, disclosureProps } from "./behaviour.jsx";
+import { hasLive, liveAssign, liveKeys, liveOptions } from "../utils/live.jsx";
+/** Group props that stay live (LIVE-SWEEP round 2); `expandedKeys` is controlled (`liveKeys`). */
+const GROUP_LIVE = ["isDisabled", "allowsMultipleExpanded"];
+import { renderPropsOf } from "../slots/index.jsx";
+import { read } from "../interactions/utils.js";
+export { allowsMultiple, createDisclosureGroupState, createDisclosureState, openAll, closeAll };
+export { DetailsDisclosure } from "./details.jsx";
+const isFn = (v) => typeof v === "function" && !isSlot(v);
+// focus-visible-within (RAC useFocusRing({ within: true })): attribute + optional render-prop signal.
+function focusWithinIn(e, sig) {
+    const el = e.currentTarget;
+    const visible = isFocusVisible();
+    setDataAttr(el, "data-focus-visible-within", visible);
+    sig?.set(visible);
+}
+function focusWithinOut(e, sig) {
+    const el = e.currentTarget;
+    if (e.relatedTarget instanceof Node && el.contains(e.relatedTarget))
+        return;
+    setDataAttr(el, "data-focus-visible-within", false);
+    sig?.set(false);
+}
+/** RAC `DisclosureGroupStateContext`. */
+export const DisclosureGroupStateContext = resumableContext(createContext(null, { id: "rv-disclosure-group-state" }));
+const GROUP_OWNED = ["style"];
+/** A DisclosureGroup is a grouping of related disclosures, sometimes called an accordion (RAC `DisclosureGroup`). */
+export function DisclosureGroup(props) {
+    // Live props: a controlled `expandedKeys={keys()}` stays live (accessor normalised to a Set; never written).
+    const state = props.state ??
+        createDisclosureGroupState(hasLive(props) ? liveAssign(liveOptions(props, GROUP_LIVE), { expandedKeys: liveKeys(props, "expandedKeys") }) : props);
+    // Ensure only one item is expanded if allowsMultipleExpanded turns false (upstream effect; Signal `multi`).
+    if (typeof state.allowsMultipleExpanded === "function")
+        clientEffect(() => {
+            const keys = state.expandedKeys();
+            if (!allowsMultiple(state) && keys.size > 1)
+                untrack(() => setExpandedKeys(state, new Set([keys.values().next().value])));
+        });
+    const rp = renderPropsOf(props, {
+        defaultClassName: "rv-DisclosureGroup",
+        values: { isDisabled: state.isDisabled, state },
+    });
+    const dom = globalDOMProps(props, GROUP_OWNED);
+    const id = props.id, isDisabled = state.isDisabled, ref = props.ref;
+    if (props.render) {
+        const attrs = {
+            ...dom,
+            id,
+            ref,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-disabled": () => dataBool(isGroupDisabled(state)),
+            children: () => <Provider values={[[DisclosureGroupStateContext, state]]}>{() => rp.children()}</Provider>,
+        };
+        return props.render(attrs, { isDisabled, state });
+    }
+    return (<div {...dom} id={id} ref={ref} class={rp.class()} style={rp.style()} data-disabled={dataBool(isGroupDisabled(state))}>
+      <Provider values={[[DisclosureGroupStateContext, state]]}>{() => rp.children()}</Provider>
+    </div>);
+}
+/** RAC `DisclosureContext`. */
+export const DisclosureContext = resumableContext(createContext(null, { id: "rv-disclosure" }));
+/** RAC `DisclosureStateContext`. */
+export const DisclosureStateContext = resumableContext(createContext(null, { id: "rv-disclosure-state" }));
+const InternalDisclosureContext = resumableContext(createContext(null, { id: "rv-disclosure-internal" }));
+const DISCLOSURE_OWNED = ["style", "onFocusIn", "onFocusOut"];
+/** A disclosure is a collapsible section of content (RAC `Disclosure`). */
+export function Disclosure(inProps) {
+    // Live props (P5): `isDisabled` stays live (press checks, button, `data-disabled`), `isExpanded` is controlled (an
+    // accessor only when defined at creation); class / style / children from a live view; the rest is read once.
+    return untrack(() => disclosure(inProps));
+}
+/** A live disclosure's disabled state: its own (live or static) flag or the group's (a returned arrow: resumable). */
+function disclosureDisabled(own, group) {
+    return () => !!read(own) || (group ? isGroupDisabled(group) : false);
+}
+function disclosure(inProps) {
+    const [ctxProps, ref] = contextProps(inProps, inProps.ref, DisclosureContext);
+    const props = hasLive(ctxProps) ? liveOptions(ctxProps, ["isDisabled"], ["isExpanded"]) : ctxProps;
+    const groupState = useContext(DisclosureGroupStateContext);
+    // Generate an id if one wasn't provided.
+    const domId = createId();
+    const id = props.id ?? domId;
+    const userChange = props.onExpandedChange, onOpened = props.onOpened, onClosed = props.onClosed;
+    if (groupState) {
+        registerDisclosure(groupState, id, !!read(props.isDisabled));
+        if (getOwner())
+            onCleanup(() => unregisterDisclosure(groupState, id));
+    }
+    const state = createDisclosureState({
+        isExpanded: groupState ? () => isKeyExpanded(groupState, id) : props.isExpanded,
+        defaultExpanded: props.defaultExpanded,
+        // Inline (a resume symbol): toggles the group key, then the user's callback.
+        onExpandedChange: (isExpanded) => {
+            if (groupState)
+                toggleKey(groupState, id);
+            userChange?.(isExpanded);
+        },
+    });
+    // Angular CDK accordion item events: opened / closed on every change (also a group collapsing it), destroyed.
+    if (onOpened || onClosed) {
+        // The last reported state is a region signal (serialized): a resumed page's effect, which first runs
+        // after the first change, still compares against the server-rendered state.
+        const reported = _regionState(() => signal(untrack(state.isExpanded)));
+        clientEffect(() => {
+            const now = state.isExpanded();
+            if (now === untrack(reported))
+                return;
+            reported.set(now);
+            untrack(() => (now ? onOpened?.() : onClosed?.()));
+        });
+    }
+    const onDestroyed = props.onDestroyed;
+    if (onDestroyed && getOwner())
+        onCleanup(() => onDestroyed());
+    const panelRef = createRef();
+    const ownDisabled = props.isDisabled;
+    const isDisabled = typeof ownDisabled === "function" || groupState?.liveDisabled
+        ? disclosureDisabled(ownDisabled, groupState)
+        : ownDisabled || groupState?.isDisabled || false;
+    // Render props keep their type (`isDisabled: boolean`): the value at creation.
+    const disabledNow = !!read(isDisabled);
+    const { buttonProps, panelProps } = disclosureProps({ id: domId, isDisabled, panelRef }, state);
+    const wantsStates = isFn(props.class) || isFn(props.style) || isFn(props.children);
+    const focusWithin = wantsStates ? signal(false) : undefined;
+    // Options hoisted: no function in the `rp` initializer (spread sites capture `rp.class` /
+    // `rp.style`, not the children accessor: per-key live views).
+    const rpOptions = {
+        defaultClassName: "rv-Disclosure",
+        values: { isExpanded: () => state.isExpanded(), isDisabled: disabledNow, isFocusVisibleWithin: () => !!focusWithin?.(), state },
+    };
+    const rp = renderPropsOf(props, rpOptions);
+    const dom = globalDOMProps(props, DISCLOSURE_OWNED);
+    const { onFocusIn, onFocusOut } = props;
+    const slot = props.slot || undefined, r = ref, 
+    // RAC filterDOMProps forwards `id` (also the group key).
+    rootId = props.id != null ? String(props.id) : undefined;
+    if (props.render) {
+        const attrs = {
+            ...dom,
+            ref: r,
+            id: rootId,
+            slot,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            "data-expanded": () => dataBool(state.isExpanded()),
+            "data-disabled": () => dataBool(read(isDisabled)),
+            onFocusIn: (e) => {
+                focusWithinIn(e, focusWithin);
+                onFocusIn?.(e);
+            },
+            onFocusOut: (e) => {
+                focusWithinOut(e, focusWithin);
+                onFocusOut?.(e);
+            },
+            children: () => rp.children(),
+        };
+        return (<Provider values={[
+                [ButtonContext, { slots: { [DEFAULT_SLOT]: {}, trigger: buttonProps } }],
+                [InternalDisclosureContext, { panelProps, panelRef, state }],
+                [DisclosureStateContext, state],
+            ]}>
+        {props.render(attrs, { isExpanded: () => state.isExpanded(), isDisabled: disabledNow, isFocusVisibleWithin: () => !!focusWithin?.(), state })}
+      </Provider>);
+    }
+    return (<Provider values={[
+            [ButtonContext, { slots: { [DEFAULT_SLOT]: {}, trigger: buttonProps } }],
+            [InternalDisclosureContext, { panelProps, panelRef, state }],
+            [DisclosureStateContext, state],
+        ]}>
+      <div {...dom} ref={r} id={rootId} slot={slot} class={rp.class()} style={rp.style()} data-expanded={dataBool(state.isExpanded())} data-disabled={dataBool(read(isDisabled))} onFocusIn={(e) => {
+            focusWithinIn(e, focusWithin);
+            onFocusIn?.(e);
+        }} onFocusOut={(e) => {
+            focusWithinOut(e, focusWithin);
+            onFocusOut?.(e);
+        }}>
+        {rp.children()}
+      </div>
+    </Provider>);
+}
+const PANEL_OWNED = ["style", "onFocusIn", "onFocusOut", "id", "role"];
+/** A DisclosurePanel provides the content for a disclosure (RAC `DisclosurePanel`). */
+export function DisclosurePanel(props) {
+    const ctx = useContext(InternalDisclosureContext);
+    if (!ctx)
+        throw new Error("DisclosurePanel must be rendered inside a Disclosure.");
+    const { panelProps, panelRef, state } = ctx;
+    const role = props.role ?? "group";
+    const wantsStates = isFn(props.class) || isFn(props.style) || isFn(props.children);
+    const focusWithin = wantsStates ? signal(false) : undefined;
+    // Options hoisted: no function in the `rp` initializer (spread sites capture `rp.class` /
+    // `rp.style`, not the children accessor: per-key live views).
+    const rpOptions = {
+        defaultClassName: "rv-DisclosurePanel",
+        values: { isFocusVisibleWithin: () => !!focusWithin?.() },
+    };
+    const rp = renderPropsOf(props, rpOptions);
+    const dom = globalDOMProps(props, PANEL_OWNED);
+    const { onFocusIn, onFocusOut } = props;
+    const ref = mergeRefValues(panelRef, props.ref);
+    const id = props.id ?? panelProps.id, ariaLabel = props["aria-label"], ariaLabelledby = props["aria-labelledby"] ?? panelProps["aria-labelledby"];
+    // Server: the initial size variables (the browser sets them from the hidden binding on change).
+    const sizeStyle = disclosurePanelStyle(untrack(state.isExpanded));
+    // Browser: keep the size variables the `hidden` binding last wrote (CSSOM). The panel element (a spread) is
+    // one binding over all attributes: `hidden` is evaluated first (JSX attribute order) and writes the px sizes,
+    // re-applying the server values here would clobber them (resumed panel stayed at its server size).
+    // `rp.style` alone (not `rp`): the style binding must not capture the children accessor (per-key live views).
+    const rpStyle = rp.style;
+    const style = () => {
+        const user = rpStyle();
+        const panel = untrack(panelRef);
+        return { ...(panel ? currentVars(panel, sizeStyle) : parseVars(sizeStyle)), ...user };
+    };
+    if (props.render) {
+        const attrs = {
+            ...dom,
+            ref,
+            id,
+            role,
+            class: () => rp.class(),
+            // `hidden` before `style`: the hidden binding writes the size variables, `style` then keeps them.
+            hidden: () => panelProps.hidden(),
+            style,
+            "aria-label": ariaLabel,
+            "aria-labelledby": ariaLabelledby,
+            "aria-hidden": () => (panelProps["aria-hidden"]() ? "true" : undefined),
+            onBeforeMatch: (e) => disclosurePanelBeforeMatch(e, { id: "" }, state),
+            onFocusIn: (e) => {
+                focusWithinIn(e, focusWithin);
+                onFocusIn?.(e);
+            },
+            onFocusOut: (e) => {
+                focusWithinOut(e, focusWithin);
+                onFocusOut?.(e);
+            },
+            children: () => rp.children(),
+        };
+        return props.render(attrs, { isFocusVisibleWithin: () => !!focusWithin?.() });
+    }
+    return (<div {...dom} ref={ref} id={id} role={role} class={rp.class()} hidden={panelProps.hidden()} style={style()} aria-label={ariaLabel} aria-labelledby={ariaLabelledby} aria-hidden={panelProps["aria-hidden"]() ? "true" : undefined} on:beforematch={(e) => disclosurePanelBeforeMatch(e, { id: "" }, state)} onFocusIn={(e) => {
+            focusWithinIn(e, focusWithin);
+            onFocusIn?.(e);
+        }} onFocusOut={(e) => {
+            focusWithinOut(e, focusWithin);
+            onFocusOut?.(e);
+        }}>
+      <Provider values={[[ButtonContext, null]]}>{() => rp.children()}</Provider>
+    </div>);
+}
+const currentVars = (panel, css) => {
+    const out = parseVars(css);
+    for (const name in out) {
+        const v = panel.style.getPropertyValue(name);
+        if (v)
+            out[name] = v;
+    }
+    return out;
+};
+const parseVars = (css) => {
+    const out = {};
+    for (const decl of css.split(";")) {
+        const i = decl.indexOf(":");
+        if (i > 0)
+            out[decl.slice(0, i)] = decl.slice(i + 1);
+    }
+    return out;
+};

package/drag-drop/cdk-index.d.ts

@@ -0,0 +1,22 @@
+export { Drag, type DragProps } from "./drag.jsx";
+export { DropList, type DropListProps } from "./drop-list.jsx";
+export { DropListGroup, type DropListGroupProps } from "./drop-list-group.jsx";
+export { DragHandle, type DragHandleProps } from "./drag-handle.jsx";
+export { DragPreview, type DragPreviewProps } from "./drag-preview.jsx";
+export { DragPlaceholder, type DragPlaceholderProps } from "./drag-placeholder.jsx";
+export { DragInstance, type DragInputs } from "./directives/drag.js";
+export { DropListInstance, type DropListInputs } from "./directives/drop-list.js";
+export { DropListGroupInstance } from "./directives/drop-list-group.js";
+export { DragHandleInstance } from "./directives/drag-handle.js";
+export { dragInstance, dropListInstance } from "./lazy-refs.js";
+export { DragDropConfigContext, type DragDropConfig, type DragAxis, type DragStartDelay } from "./directives/config.js";
+export type { DragStart, DragRelease, DragEnd, DragEnter, DragExit, DragDrop, DragMove, DragSortEvent } from "./drag-events.js";
+export { dragDrop, type DragDropService } from "./drag-drop.js";
+export { DragRef, createDragRef, type DragRefConfig, type DragConstrainPosition, type Point, type PreviewContainer } from "./drag-ref.js";
+export { DropListRef, createDropListRef, type DropListOrientation } from "./drop-list-ref.js";
+export { DragDropRegistry, dragDropRegistry } from "./drag-drop-registry.js";
+export type { DropListSortStrategy, SortPredicate } from "./sorting/drop-list-sort-strategy.js";
+export { SingleAxisSortStrategy } from "./sorting/single-axis-sort-strategy.js";
+export { MixedSortStrategy } from "./sorting/mixed-sort-strategy.js";
+export type { DragHelperTemplate, StampedView, DragTemplateFactory } from "./dom/root-node.js";
+export { moveItemInArray, transferArrayItem, copyArrayItem } from "./drag-utils.js";

package/drag-drop/cdk-index.jsx

@@ -0,0 +1,25 @@
+// Ported from Angular Components (src/cdk/drag-drop/index.ts, public-api.ts), MIT, © Google LLC.
+// Rivet: `@rivetjs/cdk/drag-drop/cdk` — the Angular CDK engine: components (`cdkDrag` → `<Drag>`, …),
+// directive instances + element lookups (Angular `@ViewChild(CdkDrag)`), event types, config context,
+// the refs for imperative use (`createDragRef` / `dragDrop`), sort strategies and the array helpers.
+// No `DragDropModule` (no NgModules); `CDK_DRAG_PARENT` / `CDK_DROP_LIST` / … tokens are DOM-derived
+// (directives/registry.ts) instead of injected.
+export { Drag } from "./drag.jsx";
+export { DropList } from "./drop-list.jsx";
+export { DropListGroup } from "./drop-list-group.jsx";
+export { DragHandle } from "./drag-handle.jsx";
+export { DragPreview } from "./drag-preview.jsx";
+export { DragPlaceholder } from "./drag-placeholder.jsx";
+export { DragInstance } from "./directives/drag.js";
+export { DropListInstance } from "./directives/drop-list.js";
+export { DropListGroupInstance } from "./directives/drop-list-group.js";
+export { DragHandleInstance } from "./directives/drag-handle.js";
+export { dragInstance, dropListInstance } from "./lazy-refs.js";
+export { DragDropConfigContext } from "./directives/config.js";
+export { dragDrop } from "./drag-drop.js";
+export { DragRef, createDragRef } from "./drag-ref.js";
+export { DropListRef, createDropListRef } from "./drop-list-ref.js";
+export { DragDropRegistry, dragDropRegistry } from "./drag-drop-registry.js";
+export { SingleAxisSortStrategy } from "./sorting/single-axis-sort-strategy.js";
+export { MixedSortStrategy } from "./sorting/mixed-sort-strategy.js";
+export { moveItemInArray, transferArrayItem, copyArrayItem } from "./drag-utils.js";

package/drag-drop/directives/assertions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Asserts that a particular node is an element.
+ * @param node Node to be checked.
+ * @param name Name to attach to the error message.
+ */
+export declare function assertElementNode(node: Node, name: string): asserts node is HTMLElement;

package/drag-drop/directives/assertions.js

@@ -0,0 +1,13 @@
+// Ported from Angular Components (src/cdk/drag-drop/directives/assertions.ts), MIT, © Google LLC.
+// Rivet: the components always render an element, so this only guards alternate roots
+// (`rootElementSelector`) and the imperative API.
+/**
+ * Asserts that a particular node is an element.
+ * @param node Node to be checked.
+ * @param name Name to attach to the error message.
+ */
+export function assertElementNode(node, name) {
+    if (node.nodeType !== 1) {
+        throw Error(`${name} must be attached to an element node. ` + `Currently attached to "${node.nodeName}".`);
+    }
+}

package/drag-drop/directives/config.d.ts

@@ -0,0 +1,30 @@
+import type { DragConstrainPosition, DragRefConfig } from "../drag-ref.js";
+import type { DropListOrientation } from "../drop-list-ref.js";
+export type { DropListOrientation };
+/** Possible values that can be used to configure the drag start delay. */
+export type DragStartDelay = number | {
+    touch: number;
+    mouse: number;
+};
+/** Possible axis along which dragging can be locked. */
+export type DragAxis = "x" | "y";
+/**
+ * Object that can be used to configure the drag
+ * items and drop lists within a module or a component.
+ */
+export interface DragDropConfig extends Partial<DragRefConfig> {
+    lockAxis?: DragAxis | null;
+    dragStartDelay?: DragStartDelay;
+    constrainPosition?: DragConstrainPosition;
+    previewClass?: string | string[];
+    boundaryElement?: string;
+    rootElementSelector?: string;
+    draggingDisabled?: boolean;
+    sortingDisabled?: boolean;
+    listAutoScrollDisabled?: boolean;
+    listOrientation?: DropListOrientation;
+    zIndex?: number;
+    previewContainer?: "global" | "parent";
+}
+/** Injection token that can be used to configure the behavior of the drag&drop-related components (Angular `CDK_DRAG_CONFIG`). */
+export declare const DragDropConfigContext: import("@rivetjs/reactivity").Context<DragDropConfig | null>;

package/drag-drop/directives/config.js

@@ -0,0 +1,7 @@
+// Ported from Angular Components (src/cdk/drag-drop/directives/config.ts), MIT, © Google LLC.
+// Rivet: the `CDK_DRAG_CONFIG` injection token is `DragDropConfigContext` (provide it with
+// `<Provider token={DragDropConfigContext} value={…}>` + function children, or `provide()`); `Drag` /
+// `DropList` read it while rendering, so the config is captured with their handlers and resumes.
+import { createContext } from "@rivetjs/reactivity";
+/** Injection token that can be used to configure the behavior of the drag&drop-related components (Angular `CDK_DRAG_CONFIG`). */
+export const DragDropConfigContext = createContext(null);

package/drag-drop/directives/drag-handle.d.ts

@@ -0,0 +1,10 @@
+/** Handle that can be used to drag a `Drag` instance (Angular `CdkDragHandle`). */
+export declare class DragHandleInstance {
+    /** Element the handle is rendered as. */
+    readonly element: HTMLElement;
+    constructor(element: HTMLElement);
+    /** Whether starting to drag through this handle is disabled. */
+    get disabled(): boolean;
+}
+/** The handle elements of a drag element (not those of nested drags). */
+export declare function handleElements(dragElement: HTMLElement, dragAttr: string): HTMLElement[];

package/drag-drop/directives/drag-handle.js

@@ -0,0 +1,29 @@
+// Ported from Angular Components (src/cdk/drag-drop/directives/drag-handle.ts), MIT, © Google LLC.
+// Rivet: the handle's only input (`disabled`) is rendered by `<DragHandle>` as `data-disabled`, so the
+// instance is derived from the DOM: the owning `DragInstance` collects the `[data-rv-drag-handle]`
+// elements below its element (Angular: `CDK_DRAG_PARENT`, else the parent walk in `ngAfterViewInit`)
+// and re-syncs them before every pointer down (Angular: `_stateChanges`). No handle code ships with
+// the page. `_stateChanges` / `_addHandle` / `_removeHandle` map to `DragInstance._syncHandles()`.
+import { HANDLE_ATTR } from "./registry.js";
+/** Handle that can be used to drag a `Drag` instance (Angular `CdkDragHandle`). */
+export class DragHandleInstance {
+    /** Element the handle is rendered as. */
+    element;
+    constructor(element) {
+        this.element = element;
+    }
+    /** Whether starting to drag through this handle is disabled. */
+    get disabled() {
+        return this.element.hasAttribute("data-disabled");
+    }
+}
+/** The handle elements of a drag element (not those of nested drags). */
+export function handleElements(dragElement, dragAttr) {
+    const result = [];
+    dragElement.querySelectorAll(`[${HANDLE_ATTR}]`).forEach((handle) => {
+        // Owned by the closest drag (a handle on the drag element itself counts too).
+        if (handle.closest(`[${dragAttr}]`) === dragElement)
+            result.push(handle);
+    });
+    return result;
+}

package/drag-drop/directives/drag.d.ts

@@ -0,0 +1,194 @@
+import { type Stream } from "../../scrolling/emitter.js";
+import { type ElementLike } from "../dom/coerce.js";
+import { type Directionality } from "../../bidi/index.js";
+import type { DragDrop, DragEnd, DragEnter, DragExit, DragMove, DragRelease, DragStart } from "../drag-events.js";
+import { type DragConstrainPosition, type DragRef, type Point, type PreviewContainer } from "../drag-ref.js";
+import type { DropListInstance } from "./drop-list.js";
+import type { DragAxis, DragDropConfig, DragStartDelay } from "./config.js";
+import { DragHandleInstance } from "./drag-handle.js";
+import { type MaybeAccessor } from "./registry.js";
+/** Inputs and outputs of a draggable (Angular `cdkDrag*` inputs / outputs, `Cdk` prefix dropped). */
+export interface DragInputs<T = any> {
+    /** Arbitrary data to attach to this drag instance. */
+    data?: MaybeAccessor<T>;
+    /** Locks the position of the dragged element along the specified axis. */
+    lockAxis?: MaybeAccessor<DragAxis | null | undefined>;
+    /**
+     * Selector that will be used to determine the root draggable element, starting from
+     * the `Drag` element and going up the DOM. Passing an alternate root element is useful
+     * when trying to enable dragging on an element that you might not have access to.
+     */
+    rootElementSelector?: MaybeAccessor<string | undefined>;
+    /**
+     * Node or selector that will be used to determine the element to which the draggable's
+     * position will be constrained. If a string is passed in, it'll be used as a selector that
+     * will be matched starting from the element's parent and going up the DOM until a match
+     * has been found.
+     */
+    boundaryElement?: MaybeAccessor<string | ElementLike | null | undefined>;
+    /**
+     * Amount of milliseconds to wait after the user has put their
+     * pointer down before starting to drag the element.
+     */
+    dragStartDelay?: MaybeAccessor<DragStartDelay | string | undefined>;
+    /**
+     * Sets the position of a `Drag` that is outside of a drop container.
+     * Can be used to restore the element's position for a returning user.
+     */
+    freeDragPosition?: MaybeAccessor<Point | undefined>;
+    /** Whether starting to drag this element is disabled. */
+    disabled?: MaybeAccessor<boolean | undefined>;
+    /**
+     * Function that can be used to customize the logic of how the position of the drag item
+     * is limited while it's being dragged. Gets called with a point containing the current position
+     * of the user's pointer on the page, a reference to the item being dragged and its dimensions.
+     * Should return a point describing where the item should be rendered.
+     */
+    constrainPosition?: DragConstrainPosition;
+    /** Class to be added to the preview element. */
+    previewClass?: MaybeAccessor<string | string[] | undefined>;
+    /**
+     * Configures the place into which the preview of the item will be inserted. Can be configured
+     * globally through `DragDropConfigContext`. Possible values:
+     * - `global` - Preview will be inserted at the bottom of the `<body>`. The advantage is that
+     * you don't have to worry about `overflow: hidden` or `z-index`, but the item won't retain
+     * its inherited styles.
+     * - `parent` - Preview will be inserted into the parent of the drag item. The advantage is that
+     * inherited styles will be preserved, but it may be clipped by `overflow: hidden` or not be
+     * visible due to `z-index`. Furthermore, the preview is going to have an effect over selectors
+     * like `:nth-child` and some flexbox configurations.
+     * - `ElementLike` - Preview will be inserted into a specific element.
+     * Same advantages and disadvantages as `parent`.
+     */
+    previewContainer?: MaybeAccessor<PreviewContainer | undefined>;
+    /**
+     * If the parent of the dragged element has a `scale` transform, it can throw off the
+     * positioning when the user starts dragging. Use this input to notify the CDK of the scale.
+     */
+    scale?: MaybeAccessor<number | string | undefined>;
+    /** Emits when the user starts dragging the item. */
+    onStarted?: (event: DragStart<T>) => void;
+    /** Emits when the user has released a drag item, before any animations have started. */
+    onReleased?: (event: DragRelease<T>) => void;
+    /** Emits when the user stops dragging an item in the container. */
+    onEnded?: (event: DragEnd<T>) => void;
+    /** Emits when the user has moved the item into a new container. */
+    onEntered?: (event: DragEnter<any, T>) => void;
+    /** Emits when the user removes the item its container by dragging it into another container. */
+    onExited?: (event: DragExit<any, T>) => void;
+    /** Emits when the user drops the item inside a container. */
+    onDropped?: (event: DragDrop<any, any, T>) => void;
+    /**
+     * Emits as the user is dragging the item. Use with caution,
+     * because this event will fire for every pixel that the user has dragged.
+     */
+    onMoved?: (event: DragMove<T>) => void;
+}
+/** Options a drag instance is created with (component props + render context). */
+export interface DragSetup<T = any> {
+    inputs?: DragInputs<T>;
+    /** `DragDropConfigContext` value where the `<Drag>` rendered. */
+    config?: DragDropConfig | null;
+    /** `DirectionalityContext` value where the `<Drag>` rendered (else the document's). */
+    dir?: Directionality | null;
+}
+/** Element that can be moved inside a `DropList` container (Angular `CdkDrag`). */
+export declare class DragInstance<T = any> {
+    /** The `<Drag>` element. */
+    readonly element: HTMLElement;
+    /** Droppable container that the draggable is a part of. */
+    dropContainer: DropListInstance | null;
+    /** Reference to the underlying drag instance. */
+    _dragRef: DragRef<DragInstance<T>>;
+    /**
+     * Emits as the user is dragging the item. Use with caution,
+     * because this event will fire for every pixel that the user has dragged.
+     * (Angular `cdkDragMoved` observable; the `onMoved` prop is its output binding.)
+     */
+    readonly moved: Stream<DragMove<T>>;
+    private _inputs;
+    private _config;
+    private _dir;
+    private _dragDropRegistry;
+    private _destroyed;
+    private _disposeSync;
+    private _containerBeforeStarted;
+    private _movedSubscription;
+    private _handles;
+    private _previewView;
+    private _placeholderView;
+    constructor(element: HTMLElement, setup?: DragSetup<T>);
+    /** Arbitrary data to attach to this drag instance. */
+    get data(): T;
+    /** Locks the position of the dragged element along the specified axis. */
+    get lockAxis(): DragAxis | null;
+    /** Selector of an alternate root element. */
+    get rootElementSelector(): string | undefined;
+    /** Element (or selector) the draggable's position is constrained to. */
+    get boundaryElement(): string | ElementLike | null | undefined;
+    /** Delay before dragging starts. */
+    get dragStartDelay(): DragStartDelay | string;
+    /** Position of a standalone drag item. */
+    get freeDragPosition(): Point | undefined;
+    /** Whether starting to drag this element is disabled. */
+    get disabled(): boolean;
+    private get _ownDisabled();
+    /** Position constraint function. */
+    get constrainPosition(): DragConstrainPosition | undefined;
+    /** Class to be added to the preview element. */
+    get previewClass(): string | string[] | undefined;
+    /** Place into which the preview of the item will be inserted. */
+    get previewContainer(): PreviewContainer | undefined;
+    /** Scale of the drag element's parent. */
+    get scale(): number;
+    /**
+     * Returns the element that is being used as a placeholder
+     * while the current element is being dragged.
+     */
+    getPlaceholderElement(): HTMLElement;
+    /** Returns the root draggable element. */
+    getRootElement(): HTMLElement;
+    /** Resets a standalone drag item to its initial position. */
+    reset(): void;
+    /** Resets drag item to end of boundary element. */
+    resetToBoundary(): void;
+    /**
+     * Gets the pixel coordinates of the draggable outside of a drop container.
+     */
+    getFreeDragPosition(): Readonly<Point>;
+    /**
+     * Sets the current position in pixels the draggable outside of a drop container.
+     * @param value New position to be set.
+     */
+    setFreeDragPosition(value: Point): void;
+    /** Rivet: the props of a lazily created (bare) instance arrived with its own handler. */
+    _setInputs(setup: DragSetup<T>): void;
+    /** Rivet: sync what the DOM holds (handles, container state) before the ref sees a pointer down. */
+    _beforePointerDown(): void;
+    /** Angular `ngOnDestroy`. */
+    destroy(): void;
+    private _handlesSynced;
+    /** Re-collects the handles below the element (Angular: `_handles` + `_stateChanges`). */
+    _syncHandles(): void;
+    /** The handles of the drag item (Angular `_handles`). */
+    get _handleInstances(): readonly DragHandleInstance[];
+    /** Syncs the root element with the `DragRef`. */
+    private _updateRootElement;
+    /** Gets the boundary element, based on the `boundaryElement` value. */
+    private _getBoundaryElement;
+    /** The preview / placeholder `<template>` of this drag item (the last one wins, like Angular). */
+    private _template;
+    /** Syncs the inputs of the Drag with the options of the underlying DragRef. */
+    private _syncInputs;
+    /** Handles the events from the underlying `DragRef`. */
+    private _handleEvents;
+    /** `cdkDragMoved` (only observed while there is a listener, like Angular's lazy Observable). */
+    private _subscribeMoved;
+    /** Rivet: signal inputs Angular re-syncs on change (`ngOnChanges`, the `disabled` setter). */
+    private _syncReactiveInputs;
+    /** The server-rendered `transform` of `freeDragPosition` is handed over to the ref. */
+    private _rootTransformRendered;
+    /** Host classes (Angular host bindings). */
+    _syncHostClasses(): void;
+    private _toggleClass;
+}