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

package/checkbox/index.jsx

@@ -0,0 +1,310 @@
+// Ported from react-aria-components `Checkbox` (packages/react-aria-components/src/Checkbox.tsx), Apache-2.0, © Adobe.
+// CheckboxGroup, CheckboxField, CheckboxButton and the deprecated all-in-one Checkbox.
+// Rivet:
+// - render props are accessors (`{({ isSelected }) => (isSelected() ? <Check /> : null)}`); `class` / `style`
+//   may be functions of them (RAC `className` → `class`); state `data-*` attributes are bindings.
+// - `isSelected`: a plain value (controlled), a two-way Signal, or an accessor (`() => boolean`, controlled and
+//   live); `isIndeterminate` / `isDisabled` / `isInvalid` may be accessors.
+// - the native input sits in an inline-styled visually hidden span (RA `VisuallyHidden`); `indeterminate` is
+//   bound as a DOM property (`prop:indeterminate`) only when `isIndeterminate` is given (absent / `false`: the property
+//   keeps its default, and a resumed page records no load-time effect for it — UI-COLD 2026-10-08).
+// - `InternalCheckboxContext` is resumable (`rv-checkbox-internal`): CheckboxButton reads the field's
+//   behaviour bags from it.
+// `render` (RAC DOMRenderProps): given, the attributes go to `render(attrs, <part>RenderProps)` instead of the default element (CheckboxGroup / CheckboxField `<div>`, CheckboxButton / Checkbox `<label>` with the hidden input inside `children`). Deviations: `inputRef` is a Rivet `ref()` (or callback).
+import { probeSlots, slotProbing } from "#server";
+import { createContext, untrack, useContext } from "@rivetjs/reactivity";
+import { mergeProps as mergeLive } from "@rivetjs/runtime/props";
+import { hasLive, liveOmit, liveOptions, liveWithoutData } from "../utils/live.jsx";
+import { liveRenderProps } from "../slots/index.jsx";
+import { read } from "../state/form-validation.js";
+import { createCheckboxGroupState, isCheckboxGroupDisabled, isCheckboxGroupReadOnly, isCheckboxGroupRequired, } from "../state/checkbox-group.js";
+import { createToggleState } from "../state/toggle.js";
+import { formValidationBehavior, formValidationErrors } from "../form/index.jsx";
+import { FieldErrorContext } from "../form/field-error.jsx";
+import { LabelContext } from "../label/index.jsx";
+import { TextContext } from "../text/index.jsx";
+import { visuallyHidden } from "../a11y/index.js";
+import { useFocusRing } from "../focus/focus-ring.jsx";
+import { hoverProps } from "../interactions/hover.jsx";
+import { mergeInto, mergeProps } from "../interactions/merge-props.jsx";
+import {} from "../utils/render.js";
+import { globalDOMProps } from "../utils/dom-props.js";
+import { Provider, resumableContext, contextProps, createSlot, renderProps, renderPropsOf, } from "../slots/index.jsx";
+import { checkboxGroupItemProps, checkboxGroupProps, checkboxProps, mergeInputRefs, } from "./behaviour.jsx";
+/** RAC `CheckboxContext`. */
+export const CheckboxContext = resumableContext(createContext(null, { id: "rv-checkbox" }));
+/** RAC `CheckboxFieldContext`. */
+export const CheckboxFieldContext = resumableContext(createContext(null, { id: "rv-checkbox-field" }));
+/** RAC `CheckboxGroupContext`. */
+export const CheckboxGroupContext = resumableContext(createContext(null, { id: "rv-checkbox-group" }));
+/** RAC `CheckboxGroupStateContext`. */
+export const CheckboxGroupStateContext = resumableContext(createContext(null, { id: "rv-checkbox-group-state" }));
+const DOM_OWNED = ["style", "onClick", "render"];
+/** State keys made accessors at the part boundary when live (live props P5; `isSelected` = controlled). */
+const LIVE_KEYS = [
+    "isDisabled",
+    "isReadOnly",
+    "isRequired",
+    "isInvalid",
+    "isIndeterminate",
+    "aria-label",
+    "aria-labelledby",
+    "aria-describedby",
+    "aria-details",
+    "aria-errormessage",
+    "aria-controls",
+];
+/**
+ * A checkbox group allows a user to select multiple items from a list of options.
+ */
+export function CheckboxGroup(props) {
+    // Live props (P5): `isDisabled` / `isReadOnly` / `isRequired` / `isInvalid` and a controlled `value` stay live
+    // (accessors into the state), class / style / children from a live view; the rest of the body is read once
+    // (untracked: a prop change never re-creates the group).
+    return untrack(() => checkboxGroup(props));
+}
+const GROUP_LIVE = ["isDisabled", "isReadOnly", "isRequired", "isInvalid"];
+/** A group flag attribute: the creation value, or a returned accessor while the flag is live (resumable). */
+function flagAttr(live, now) {
+    return live ? trueOf(live) : now || undefined;
+}
+function trueOf(flag) {
+    return () => !!flag() || undefined;
+}
+function groupReader(state, which) {
+    return () => (which === 0 ? isCheckboxGroupDisabled(state) : which === 1 ? isCheckboxGroupReadOnly(state) : isCheckboxGroupRequired(state));
+}
+function checkboxGroup(props) {
+    // Inside another field's server slot probe (`probeSlots`): this field's subtree holds none of that field's slots.
+    if (slotProbing)
+        return null;
+    const [ctxMerged, ref] = contextProps(props, props.ref, CheckboxGroupContext);
+    const merged = hasLive(ctxMerged) ? liveOptions(ctxMerged, GROUP_LIVE, ["value"]) : ctxMerged;
+    const validationBehavior = formValidationBehavior(merged.validationBehavior);
+    const options = merged === ctxMerged ? merged : { ...merged };
+    const state = createCheckboxGroupState({ ...options, validationBehavior, validationErrors: formValidationErrors() });
+    const initialLabel = !merged["aria-label"] && !merged["aria-labelledby"];
+    const [labelRef, hasLabel] = createSlot(initialLabel);
+    const { groupProps, labelProps, descriptionProps, errorMessageProps, isInvalid, validationErrors, validationDetails } = checkboxGroupProps({ ...options, label: initialLabel, validationBehavior }, state);
+    const labelledBy = groupProps["aria-labelledby"];
+    const ownLabelledBy = merged["aria-labelledby"];
+    const group = { ...groupProps, "aria-labelledby": () => (initialLabel && hasLabel() ? labelledBy : initialLabel ? ownLabelledBy : labelledBy) };
+    const isDisabled = flagAttr(state.disabled, state.isDisabled);
+    const isReadOnly = flagAttr(state.readOnly, state.isReadOnly);
+    const isRequired = flagAttr(state.requiredNow, state.required);
+    const groupValues = {
+        isDisabled: groupReader(state, 0),
+        isReadOnly: groupReader(state, 1),
+        isRequired: groupReader(state, 2),
+        isInvalid,
+        state,
+    };
+    // Live props (P5): class / style / children through a live view (`renderPropsOf`).
+    const rp = renderPropsOf(merged, { values: groupValues, defaultClassName: "rv-CheckboxGroup" });
+    // Object-literal function value (R2 makes it a resumable symbol; a plain local const arrow is not, and a
+    // provider entry holding one is dropped when a resumed region is re-created).
+    const fieldError = {
+        validation: () => ({ isInvalid: isInvalid(), validationErrors: validationErrors(), validationDetails: validationDetails() }),
+    };
+    // The flags go through the spread: a function (live) attribute value outside a spread is not a server binding, and a
+    // plain JSX attribute of the same name would take the key from the spread.
+    const dom = mergeProps(globalDOMProps(merged, ["style", "render"]), group, {
+        "data-readonly": isReadOnly,
+        "data-required": isRequired,
+        "data-disabled": isDisabled,
+    });
+    const slot = merged.slot || undefined;
+    const values = [
+        [CheckboxGroupStateContext, state],
+        [LabelContext, { ...labelProps, ref: labelRef, elementType: "span" }],
+        [TextContext, { slots: { description: descriptionProps, errorMessage: errorMessageProps } }],
+        [FieldErrorContext, fieldError.validation],
+    ];
+    // Rivet (server): inputs render before the Description / FieldError: probe which slotted parts render (as Select).
+    if (typeof document === "undefined")
+        probeSlots(values, () => rp.children());
+    const render = merged.render;
+    if (render)
+        return render({
+            ...dom,
+            ref: ref,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "data-invalid": () => isInvalid() || undefined,
+            children: () => <Provider values={values}>{rp.children()}</Provider>,
+        }, groupValues);
+    return (<div {...dom} ref={ref} class={rp.class()} style={rp.style()} slot={slot} data-invalid={isInvalid() || undefined}>
+      <Provider values={values}>{rp.children()}</Provider>
+    </div>);
+}
+const InternalCheckboxContext = resumableContext(createContext(null, { id: "rv-checkbox-internal" }));
+/** RAC `useCheckboxAria`: group item or standalone checkbox behaviour. */
+function checkboxAria(props, userInputRef) {
+    const validationBehavior = formValidationBehavior(props.validationBehavior);
+    const groupState = useContext(CheckboxGroupStateContext);
+    const inputRef = mergeInputRefs(userInputRef, props.inputRef);
+    // Live props (P5): `props` passed `liveOptions` (accessors for the live state keys); the option bags forward unread.
+    const children = untrack(() => props.children);
+    const options = mergeLive(liveWithoutData(props), {
+        children: typeof children === "function" ? true : children,
+        validationBehavior,
+    });
+    if (groupState)
+        return checkboxGroupItemProps(mergeLive(options, { value: untrack(() => props.value) }), groupState, inputRef);
+    return checkboxProps(mergeLive(options, { validationErrors: formValidationErrors() }), createToggleState(props), inputRef);
+}
+/**
+ * A checkbox allows a user to select an item, with support for validation and help text.
+ */
+export function CheckboxField(props) {
+    // Inside another field's server slot probe (`probeSlots`): this field's subtree holds none of that field's slots.
+    if (slotProbing)
+        return null;
+    const userInputRef = props.inputRef;
+    const otherProps = liveOmit(props, ["inputRef"]);
+    const [ctxMerged, ref] = contextProps(otherProps, props.ref, CheckboxFieldContext);
+    // Live props (P5): state keys become accessors at the boundary (read by the toggle / validation / attribute code).
+    const merged = liveOptions(ctxMerged, LIVE_KEYS, ["isSelected"]);
+    const live = merged !== ctxMerged || hasLive(ctxMerged);
+    const groupState = useContext(CheckboxGroupStateContext);
+    const aria = untrack(() => checkboxAria(merged, userInputRef));
+    const { descriptionProps, errorMessageProps, isSelected, isDisabled, isReadOnly, isInvalid, validationDetails, validationErrors } = aria;
+    const indeterminate = untrack(() => merged.isIndeterminate);
+    const isIndeterminate = () => !!read(indeterminate);
+    const requiredProp = untrack(() => merged.isRequired);
+    const isRequired = () => !!read(requiredProp);
+    const fieldValues = { isSelected, isIndeterminate, isDisabled, isReadOnly, isInvalid, isRequired };
+    const rp = live
+        ? renderProps({ defaultClassName: "rv-CheckboxField", values: fieldValues }, liveRenderProps(merged))
+        : renderProps({
+            ...merged,
+            defaultClassName: "rv-CheckboxField",
+            values: fieldValues,
+        });
+    const dom = globalDOMProps(merged, DOM_OWNED);
+    const slot = untrack(() => merged.slot) || undefined;
+    // Object-literal function value (R2 makes it a resumable symbol; a plain local const arrow is not, and a
+    // provider entry holding one is dropped when a resumed region is re-created).
+    const fieldError = {
+        validation: () => ({ isInvalid: isInvalid(), validationErrors: validationErrors(), validationDetails: validationDetails() }),
+    };
+    const values = [
+        [InternalCheckboxContext, { ...aria, defaultClassName: "rv-CheckboxButton", isIndeterminate: indeterminate, isRequired: requiredProp }],
+        [TextContext, { slots: { description: descriptionProps, errorMessage: errorMessageProps } }],
+        // In a CheckboxGroup, validation is handled at the group level instead of repeated on each checkbox.
+        [FieldErrorContext, groupState ? null : fieldError.validation],
+    ];
+    // Rivet (server): the input renders before its Description / FieldError: probe which slotted parts render (as Select).
+    if (typeof document === "undefined")
+        probeSlots(values, () => rp.children());
+    if (merged.render)
+        return merged.render({
+            ...dom,
+            ref: ref,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "data-selected": () => isSelected() || undefined,
+            "data-indeterminate": () => isIndeterminate() || undefined,
+            "data-disabled": () => isDisabled() || undefined,
+            "data-readonly": () => isReadOnly() || undefined,
+            "data-invalid": () => isInvalid() || undefined,
+            "data-required": () => isRequired() || undefined,
+            children: () => <Provider values={values}>{rp.children()}</Provider>,
+        }, fieldValues);
+    return (<div {...dom} ref={ref} class={rp.class()} style={rp.style()} slot={slot} data-selected={isSelected() || undefined} data-indeterminate={isIndeterminate() || undefined} data-disabled={isDisabled() || undefined} data-readonly={isReadOnly() || undefined} data-invalid={isInvalid() || undefined} data-required={isRequired() || undefined}>
+      <Provider values={values}>{rp.children()}</Provider>
+    </div>);
+}
+/**
+ * A checkbox allows a user to select multiple items from a list of individual items, or
+ * to mark one individual item as selected.
+ *
+ * @deprecated Use CheckboxField + CheckboxButton instead.
+ */
+export function Checkbox(props) {
+    const userInputRef = props.inputRef;
+    const otherProps = liveOmit(props, ["inputRef"]);
+    const [ctxMerged, ref] = contextProps(otherProps, props.ref, CheckboxContext);
+    const merged = liveOptions(ctxMerged, LIVE_KEYS, ["isSelected"]);
+    const aria = untrack(() => checkboxAria(merged, userInputRef));
+    const value = {
+        ...aria,
+        defaultClassName: "rv-Checkbox",
+        isIndeterminate: untrack(() => merged.isIndeterminate),
+        isRequired: untrack(() => merged.isRequired),
+    };
+    const button = (hasLive(merged) ? mergeLive(merged, { ref }) : { ...merged, ref });
+    return (<Provider values={[[InternalCheckboxContext, value]]}>
+      <CheckboxButton {...button}/>
+    </Provider>);
+}
+/**
+ * A checkbox button is the clickable area of a checkbox, including the indicator and label.
+ */
+export function CheckboxButton(props) {
+    const { labelProps, inputProps, isSelected, isDisabled, isReadOnly, isPressed, isInvalid, inputRef, defaultClassName, isIndeterminate, isRequired } = useContext(InternalCheckboxContext);
+    const buttonRef = props.ref;
+    const { isFocused, isFocusVisible, focusProps } = useFocusRing();
+    const isInteractionDisabled = () => isDisabled() || isReadOnly();
+    const { onHoverStart, onHoverEnd, onHoverChange } = props;
+    const { hoverProps: hover, isHovered } = hoverProps({ onHoverStart, onHoverEnd, onHoverChange, isDisabled: isInteractionDisabled }, props);
+    const indeterminate = () => !!read(isIndeterminate);
+    const required = () => !!read(isRequired);
+    const buttonValues = {
+        isSelected,
+        isIndeterminate: indeterminate,
+        isPressed,
+        isHovered,
+        isFocused,
+        isFocusVisible,
+        isDisabled,
+        isReadOnly,
+        isInvalid,
+        isRequired: required,
+    };
+    const rp = hasLive(props)
+        ? renderProps({ defaultClassName, values: buttonValues }, liveRenderProps(props))
+        : renderProps({
+            ...props,
+            defaultClassName,
+            values: buttonValues,
+        });
+    // `globalDOMProps` returns a fresh bag: merged into in place (static path).
+    const dom = mergeInto(globalDOMProps(props, DOM_OWNED), labelProps, hover);
+    const input = mergeProps(inputProps, focusProps);
+    // `prop:indeterminate` is a load-time DOM property write on a resumed page (a client effect: the runtime boots at
+    // idle). Without an `isIndeterminate` (absent / plain `false`) the input keeps the property's default (`false`, RA's
+    // effect writes the same), so it is bound only when given.
+    const indeterminateGiven = isIndeterminate !== undefined && isIndeterminate !== false;
+    const nativeInput = () => indeterminateGiven ? <input {...input} ref={inputRef} prop:indeterminate={indeterminate()}/> : <input {...input} ref={inputRef}/>;
+    const slot = untrack(() => props.slot) || undefined;
+    const render = untrack(() => props.render);
+    if (render)
+        return render({
+            ...dom,
+            ref: buttonRef,
+            class: () => rp.class(),
+            style: () => rp.style(),
+            slot,
+            "data-selected": () => isSelected() || undefined,
+            "data-indeterminate": () => indeterminate() || undefined,
+            "data-pressed": () => isPressed() || undefined,
+            "data-hovered": () => isHovered() || undefined,
+            "data-focused": () => isFocused() || undefined,
+            "data-focus-visible": () => isFocusVisible() || undefined,
+            "data-disabled": () => isDisabled() || undefined,
+            "data-readonly": () => isReadOnly() || undefined,
+            "data-invalid": () => isInvalid() || undefined,
+            "data-required": () => required() || undefined,
+            children: () => (<>
+            <span style={visuallyHidden}>{nativeInput()}</span>
+            {rp.children()}
+          </>),
+        }, buttonValues);
+    return (<label {...dom} ref={buttonRef} class={rp.class()} style={rp.style()} slot={slot} data-selected={isSelected() || undefined} data-indeterminate={indeterminate() || undefined} data-pressed={isPressed() || undefined} data-hovered={isHovered() || undefined} data-focused={isFocused() || undefined} data-focus-visible={isFocusVisible() || undefined} data-disabled={isDisabled() || undefined} data-readonly={isReadOnly() || undefined} data-invalid={isInvalid() || undefined} data-required={required() || undefined}>
+      <span style={visuallyHidden}>{nativeInput()}</span>
+      {rp.children()}
+    </label>);
+}

package/clipboard/index.d.ts

@@ -0,0 +1,49 @@
+/** Options of `[cdkCopyToClipboard]` (`CdkCopyToClipboardConfig` for the `attempts` default). */
+export interface CopyToClipboardOptions {
+    /** Content to be copied. */
+    text: string;
+    /**
+     * How many times to attempt the copy (long text may need time to fill the intermediate textarea).
+     * Capped at 50. Default 1.
+     */
+    attempts?: number;
+    /** `(cdkCopyToClipboardCopied)`: called once with whether copying succeeded. */
+    copied?: (successful: boolean) => void;
+}
+/**
+ * A pending copy-to-clipboard operation. Copying modifies the DOM and forces a re-layout, which for a
+ * large string can take long enough that the browser refuses `execCommand("copy")`: this object lets
+ * the re-layout happen in a separate tick from copying. Call `destroy()` when done, whether or not
+ * `copy()` was called.
+ */
+export declare class PendingCopy {
+    private _textarea;
+    private readonly _document;
+    constructor(text: string, _document: Document);
+    /** Finishes copying the text; returns whether it worked. Focus returns to the element focused before. */
+    copy(): boolean;
+    /** Cleans up the DOM changes used to perform the copy operation. */
+    destroy(): void;
+}
+/** Prepares `text` to be copied later (large strings); the caller must `destroy()` the result. */
+export declare function beginCopy(text: string, doc?: Document): PendingCopy;
+/** Angular `Clipboard.copy`: copies `text` synchronously (textarea + `execCommand`); returns whether it worked. */
+export declare function copyText(text: string, doc?: Document): boolean;
+/** The functions `copyToClipboard` uses (tests replace them, as the original spec spies on `Clipboard`). */
+export declare const _clipboard: {
+    copy: typeof copyText;
+    beginCopy: typeof beginCopy;
+};
+/**
+ * `[cdkCopyToClipboard]` click behaviour: copies `options.text`, retrying up to `attempts` times
+ * (1 ms apart) when the browser refuses, then calls `copied(successful)` once. `owner` identifies the
+ * trigger (usually `event.currentTarget`), so `destroyCopyToClipboard(owner)` can cancel retries.
+ */
+export declare function copyToClipboard(owner: object, options: CopyToClipboardOptions): void;
+/** Directive `ngOnDestroy`: stop retrying and destroy pending copies started for `owner`. */
+export declare function destroyCopyToClipboard(owner: object): void;
+/**
+ * Copy `text` with `navigator.clipboard.writeText`, falling back to `copyText` (insecure contexts,
+ * refused permission); resolves true when the clipboard accepted it.
+ */
+export declare function copy(text: string): Promise<boolean>;

package/clipboard/index.js

@@ -0,0 +1,136 @@
+// Clipboard.
+// Ported from angular/components src/cdk/clipboard (MIT, © Google LLC): `Clipboard.copy` /
+// `beginCopy` (→ `copyText`, `beginCopy`), `PendingCopy`, the `[cdkCopyToClipboard]` directive
+// (→ `copyToClipboard(element, options)` handler body + `destroyCopyToClipboard`). Plus `copy()`:
+// the async `navigator.clipboard.writeText` path with the same textarea fallback.
+//
+// Rivet: services become module functions (a handler can call them without capturing an
+// unserializable service object); the directive's pending copies / retry timer live in a WeakMap
+// keyed by the trigger element (transient, never serialized). Browser only; call from a user gesture.
+/**
+ * A pending copy-to-clipboard operation. Copying modifies the DOM and forces a re-layout, which for a
+ * large string can take long enough that the browser refuses `execCommand("copy")`: this object lets
+ * the re-layout happen in a separate tick from copying. Call `destroy()` when done, whether or not
+ * `copy()` was called.
+ */
+export class PendingCopy {
+    _textarea;
+    _document;
+    constructor(text, _document) {
+        this._document = _document;
+        const textarea = (this._textarea = _document.createElement("textarea"));
+        const styles = textarea.style;
+        // Hidden for display and accessibility; fixed at top 0 so focusing it for a split second never
+        // scrolls the page.
+        styles.position = "fixed";
+        styles.top = styles.opacity = "0";
+        styles.left = "-999em";
+        textarea.setAttribute("aria-hidden", "true");
+        textarea.value = text;
+        // `readonly` prevents the screen from jumping on iOS Safari.
+        textarea.readOnly = true;
+        // In fullscreen mode the textarea must be inside the fullscreen element, or the copy is refused.
+        (_document.fullscreenElement || _document.body).appendChild(textarea);
+    }
+    /** Finishes copying the text; returns whether it worked. Focus returns to the element focused before. */
+    copy() {
+        const textarea = this._textarea;
+        let successful = false;
+        try {
+            // Older browsers could throw if copy is not supported.
+            if (textarea) {
+                const currentFocus = this._document.activeElement;
+                textarea.select();
+                textarea.setSelectionRange(0, textarea.value.length);
+                successful = this._document.execCommand("copy");
+                if (currentFocus)
+                    currentFocus.focus();
+            }
+        }
+        catch {
+            // Discard: `successful` stays false.
+        }
+        return successful;
+    }
+    /** Cleans up the DOM changes used to perform the copy operation. */
+    destroy() {
+        const textarea = this._textarea;
+        if (textarea) {
+            textarea.remove();
+            this._textarea = undefined;
+        }
+    }
+}
+const ownerDocument = (doc) => doc ?? document;
+/** Prepares `text` to be copied later (large strings); the caller must `destroy()` the result. */
+export function beginCopy(text, doc) {
+    return new PendingCopy(text, ownerDocument(doc));
+}
+/** Angular `Clipboard.copy`: copies `text` synchronously (textarea + `execCommand`); returns whether it worked. */
+export function copyText(text, doc) {
+    const pending = beginCopy(text, doc);
+    const successful = pending.copy();
+    pending.destroy();
+    return successful;
+}
+/** The functions `copyToClipboard` uses (tests replace them, as the original spec spies on `Clipboard`). */
+export const _clipboard = { copy: copyText, beginCopy };
+const directives = new WeakMap();
+/**
+ * `[cdkCopyToClipboard]` click behaviour: copies `options.text`, retrying up to `attempts` times
+ * (1 ms apart) when the browser refuses, then calls `copied(successful)` once. `owner` identifies the
+ * trigger (usually `event.currentTarget`), so `destroyCopyToClipboard(owner)` can cancel retries.
+ */
+export function copyToClipboard(owner, options) {
+    let state = directives.get(owner);
+    if (!state)
+        directives.set(owner, (state = { pending: new Set(), timeout: null, destroyed: false }));
+    state.destroyed = false;
+    // Avoid an infinite loop when a large number of attempts is passed in.
+    const attempts = Math.min(options.attempts ?? 1, 50);
+    if (attempts > 1) {
+        let remaining = attempts;
+        const pending = _clipboard.beginCopy(options.text);
+        state.pending.add(pending);
+        const s = state;
+        const attempt = () => {
+            const successful = pending.copy();
+            if (!successful && --remaining && !s.destroyed)
+                s.timeout = setTimeout(attempt, 1);
+            else {
+                s.timeout = null;
+                s.pending.delete(pending);
+                pending.destroy();
+                options.copied?.(successful);
+            }
+        };
+        attempt();
+    }
+    else
+        options.copied?.(_clipboard.copy(options.text));
+}
+/** Directive `ngOnDestroy`: stop retrying and destroy pending copies started for `owner`. */
+export function destroyCopyToClipboard(owner) {
+    const state = directives.get(owner);
+    if (!state)
+        return;
+    if (state.timeout)
+        clearTimeout(state.timeout);
+    for (const pending of state.pending)
+        pending.destroy();
+    state.pending.clear();
+    state.destroyed = true;
+}
+/**
+ * Copy `text` with `navigator.clipboard.writeText`, falling back to `copyText` (insecure contexts,
+ * refused permission); resolves true when the clipboard accepted it.
+ */
+export async function copy(text) {
+    try {
+        await navigator.clipboard.writeText(text);
+        return true;
+    }
+    catch {
+        return copyText(text);
+    }
+}

package/coercion/index.d.ts

@@ -0,0 +1,36 @@
+/** Allowed values for a boolean option. */
+export type BooleanInput = string | boolean | null | undefined;
+/** Allowed values for a number option. */
+export type NumberInput = string | number | null | undefined;
+/** Coerces a data-bound value (typically a string) to a boolean: everything but `null`, `undefined`, `false` and `"false"` is true. */
+export declare function coerceBooleanProperty(value: unknown): boolean;
+/** Coerces a data-bound value (typically a string) to a number; non-numbers give `fallbackValue` (default 0). */
+export declare function coerceNumberProperty(value: unknown): number;
+export declare function coerceNumberProperty<D>(value: unknown, fallback: D): number | D;
+/**
+ * Whether the provided value is considered a number. `parseFloat` rejects null / "" / booleans (where
+ * `Number` gives 0) but accepts "123hello", which `Number` rejects: both must agree.
+ */
+export declare function _isNumberValue(value: unknown): boolean;
+/** Wraps the provided value in an array, unless the provided value is an array. */
+export declare function coerceArray<T>(value: T | T[]): T[];
+export declare function coerceArray<T>(value: T | readonly T[]): readonly T[];
+/** Coerces a value to a CSS pixel value: numbers get `px`, strings pass, `null` / `undefined` give "". */
+export declare function coerceCssPixelValue(value: unknown): string;
+/**
+ * Coerces a value to an array of trimmed non-empty strings. Non-arrays are stringified and split with
+ * `separator` (default whitespace); `null` / `undefined` give `[]`.
+ */
+export declare function coerceStringArray(value: unknown, separator?: string | RegExp): string[];
+/** A Rivet element ref (`ref<T>()` / signal accessor) or the element itself (Angular: `ElementRef<T> | T`). */
+export type ElementInput<T> = T | (() => T | undefined | null);
+/**
+ * Coerces a ref (accessor function such as `ref<T>()`) or an element into the element. Angular's
+ * `ElementRef` maps to Rivet's ref accessor.
+ */
+export declare function coerceElement<T>(elementOrRef: ElementInput<T>): T;
+/**
+ * Angular `coerceObservable` equivalent: a reactive accessor (signal / computed / `() => T`) passes
+ * through, a plain value becomes a constant accessor. Functions are always treated as accessors.
+ */
+export declare function coerceAccessor<T>(data: T | (() => T)): () => T;

package/coercion/index.js

@@ -0,0 +1,58 @@
+// Ported from angular/components src/cdk/coercion (MIT, © Google LLC).
+// Coerce loosely typed option values (attribute strings, numbers, refs) into the type a widget needs.
+// Pure and server-safe.
+/** Coerces a data-bound value (typically a string) to a boolean: everything but `null`, `undefined`, `false` and `"false"` is true. */
+export function coerceBooleanProperty(value) {
+    return value != null && `${value}` !== "false";
+}
+export function coerceNumberProperty(value, fallbackValue = 0) {
+    if (_isNumberValue(value))
+        return Number(value);
+    return arguments.length === 2 ? fallbackValue : 0;
+}
+/**
+ * Whether the provided value is considered a number. `parseFloat` rejects null / "" / booleans (where
+ * `Number` gives 0) but accepts "123hello", which `Number` rejects: both must agree.
+ */
+export function _isNumberValue(value) {
+    return !isNaN(parseFloat(value)) && !isNaN(Number(value));
+}
+export function coerceArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/** Coerces a value to a CSS pixel value: numbers get `px`, strings pass, `null` / `undefined` give "". */
+export function coerceCssPixelValue(value) {
+    if (value == null)
+        return "";
+    return typeof value === "string" ? value : `${value}px`;
+}
+/**
+ * Coerces a value to an array of trimmed non-empty strings. Non-arrays are stringified and split with
+ * `separator` (default whitespace); `null` / `undefined` give `[]`.
+ */
+export function coerceStringArray(value, separator = /\s+/) {
+    const result = [];
+    if (value != null) {
+        const sourceValues = Array.isArray(value) ? value : `${value}`.split(separator);
+        for (const sourceValue of sourceValues) {
+            const trimmed = `${sourceValue}`.trim();
+            if (trimmed)
+                result.push(trimmed);
+        }
+    }
+    return result;
+}
+/**
+ * Coerces a ref (accessor function such as `ref<T>()`) or an element into the element. Angular's
+ * `ElementRef` maps to Rivet's ref accessor.
+ */
+export function coerceElement(elementOrRef) {
+    return (typeof elementOrRef === "function" ? elementOrRef() : elementOrRef);
+}
+/**
+ * Angular `coerceObservable` equivalent: a reactive accessor (signal / computed / `() => T`) passes
+ * through, a plain value becomes a constant accessor. Functions are always treated as accessors.
+ */
+export function coerceAccessor(data) {
+    return typeof data === "function" ? data : () => data;
+}