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

package/chat/index.jsx

@@ -0,0 +1,287 @@
+// Rivet-authored (no React Aria / Angular CDK counterpart). Headless behaviour for chat surfaces; feature set inspired by
+// HeroUI Pro's public AI component docs (PromptInput Enter / Shift+Enter, autosizing composer, stick-to-bottom
+// conversation with a jump-to-bottom button, file drop on the composer, streamed responses); independent implementation.
+// - Plain functions called from resumable handlers (`onKeyDown={(e) => { if (isSubmitKey(e)) … }}`): nothing runs at load.
+// - Stick-to-bottom is CSS first (`flex-direction: column-reverse` scroll container: the browser starts at the bottom and
+//   keeps it there while content grows); these helpers only measure / scroll for the jump button and its visibility.
+// - `.tsx` (not `.ts`): the package's `./*` export maps to `<name>/index.tsx`, and closures of `.ts` modules never resume.
+import { effect } from "@rivetjs/reactivity";
+/* -------------------------------------------------------------------------------------------------
+ * Composer keys
+ * -----------------------------------------------------------------------------------------------*/
+/**
+ * Enter submits a composer; Shift+Enter inserts a newline (when `allowsNewlines`, default). Never during IME composition
+ * (`isComposing` / keyCode 229: Enter confirms the candidate), never with Alt. Call `preventDefault()` when it returns true.
+ */
+export function isSubmitKey(event, allowsNewlines = true) {
+    if (event.key !== "Enter" || event.isComposing || event.keyCode === 229 || event.altKey)
+        return false;
+    return event.shiftKey ? !allowsNewlines : true;
+}
+let fieldSizing;
+/** Whether the browser sizes a textarea to its content in CSS (`field-sizing: content`). */
+export function supportsFieldSizing() {
+    return (fieldSizing ??= typeof CSS !== "undefined" && typeof CSS.supports === "function" && CSS.supports("field-sizing", "content"));
+}
+/**
+ * Grow `textarea` to its content up to `maxHeight` px (the CSS `max-height` when omitted). A no-op where CSS
+ * `field-sizing: content` already does it; call it from the `input` handler (fallback for browsers without it).
+ */
+export function autosizeTextArea(textarea, maxHeight) {
+    if (supportsFieldSizing())
+        return;
+    const style = textarea.style;
+    style.height = "auto";
+    const limit = maxHeight ?? (parseFloat(getComputedStyle(textarea).maxHeight) || Infinity);
+    const height = Math.min(textarea.scrollHeight, limit);
+    style.height = `${height}px`;
+    style.overflowY = textarea.scrollHeight > limit ? "auto" : "hidden";
+}
+/* -------------------------------------------------------------------------------------------------
+ * Stick to bottom
+ * -----------------------------------------------------------------------------------------------*/
+/** Distance below which a conversation counts as "at the bottom" (px). */
+export const AT_BOTTOM_THRESHOLD = 24;
+const reversed = (el) => getComputedStyle(el).flexDirection === "column-reverse";
+/** Pixels between the visible bottom edge of `el` and the end of its content (works for `column-reverse` containers). */
+export function distanceFromBottom(el) {
+    // column-reverse: scrollTop is 0 at the bottom and negative above it (CSSOM View, all current engines).
+    if (reversed(el))
+        return Math.max(0, -el.scrollTop);
+    return Math.max(0, el.scrollHeight - el.clientHeight - el.scrollTop);
+}
+/** Whether `el` is scrolled to (within `threshold` px of) its end. */
+export function isAtBottom(el, threshold = AT_BOTTOM_THRESHOLD) {
+    return distanceFromBottom(el) <= threshold;
+}
+/** Scroll `el` to the end of its content. */
+export function scrollToBottom(el, behavior = "smooth") {
+    const top = reversed(el) ? 0 : el.scrollHeight;
+    if (typeof el.scrollTo === "function")
+        el.scrollTo({ top, behavior });
+    else
+        el.scrollTop = top;
+}
+/** Writes `data-at-bottom="true"` (or removes it) on `el` from its scroll position; returns the state. Call it on `scroll`. */
+export function syncAtBottom(el, threshold = AT_BOTTOM_THRESHOLD) {
+    const atBottom = isAtBottom(el, threshold);
+    if (atBottom)
+        el.setAttribute("data-at-bottom", "true");
+    else
+        el.removeAttribute("data-at-bottom");
+    return atBottom;
+}
+/** The scroll container of a conversation part (`[data-chat-viewport]` ancestor of `from`). */
+export function conversationViewportOf(from) {
+    return from?.closest("[data-chat-viewport]") ?? null;
+}
+/* -------------------------------------------------------------------------------------------------
+ * Files (drop / pick)
+ * -----------------------------------------------------------------------------------------------*/
+/** Whether a drag carries files (`dataTransfer.types` includes "Files"). */
+export function dragHasFiles(event) {
+    const types = event.dataTransfer?.types;
+    if (!types)
+        return false;
+    for (let i = 0; i < types.length; i++)
+        if (types[i] === "Files")
+            return true;
+    return false;
+}
+/**
+ * `accept` filter of a file input (`".pdf,image/*,text/plain"`) applied to `file`: extensions, exact MIME types and
+ * `type/*` wildcards; an empty / missing filter accepts everything.
+ */
+export function acceptsFile(file, accept) {
+    if (!accept)
+        return true;
+    const name = file.name.toLowerCase();
+    const type = file.type.toLowerCase();
+    for (const raw of accept.split(",")) {
+        const rule = raw.trim().toLowerCase();
+        if (!rule)
+            continue;
+        if (rule.startsWith(".") ? name.endsWith(rule) : rule.endsWith("/*") ? type.startsWith(rule.slice(0, -1)) : type === rule)
+            return true;
+    }
+    return false;
+}
+/** Files of a drop / input change, filtered by `accept`, at most one unless `multiple`. */
+export function selectedFiles(list, accept, multiple = true) {
+    const out = [];
+    if (!list)
+        return out;
+    for (let i = 0; i < list.length; i++) {
+        const file = list[i];
+        if (acceptsFile(file, accept))
+            out.push(file);
+        if (!multiple && out.length === 1)
+            break;
+    }
+    return out;
+}
+/**
+ * Append every chunk of `source` (an async iterable or a `ReadableStream` of strings / UTF-8 bytes, e.g. a `fetch` body)
+ * to `target`; resolves with the full text. One signal write per chunk: bindings reading `target` update in place.
+ */
+export async function streamText(target, source, options = {}) {
+    const decoder = new TextDecoder();
+    const append = (chunk) => {
+        const piece = typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+        if (!piece)
+            return;
+        const next = target() + piece;
+        target.set(next);
+        options.onChunk?.(next, piece);
+    };
+    const abort = options.signal;
+    if (typeof source.getReader === "function") {
+        const reader = source.getReader();
+        const stop = () => void reader.cancel().catch(() => { });
+        abort?.addEventListener("abort", stop, { once: true });
+        try {
+            while (!abort?.aborted) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                append(value);
+            }
+        }
+        finally {
+            abort?.removeEventListener("abort", stop);
+            reader.releaseLock();
+        }
+    }
+    else {
+        for await (const chunk of source) {
+            if (abort?.aborted)
+                break;
+            append(chunk);
+        }
+    }
+    return target();
+}
+/**
+ * `text` as an async iterable of word-sized chunks on a local timer (demos, tests, offline fallbacks): no network.
+ * Whitespace is kept with the word before it, so the joined chunks equal `text`.
+ */
+export async function* simulateStream(text, options = {}) {
+    const interval = options.interval ?? 30;
+    const per = Math.max(1, options.wordsPerChunk ?? 1);
+    const jitter = Math.min(1, Math.max(0, options.jitter ?? 0));
+    const random = options.random ?? Math.random;
+    const words = text.match(/\S+\s*|\s+/g) ?? [];
+    for (let i = 0; i < words.length;) {
+        if (options.signal?.aborted)
+            return;
+        // Size: per ± jitter (at least one word). Delay: interval ± jitter, longer after a sentence or a line break.
+        const size = jitter ? Math.max(1, Math.round(per * (1 + jitter * (random() * 2 - 1)))) : per;
+        const previous = i > 0 ? words[i - 1] : "";
+        const pause = jitter && /[.!?:]\s*$|\n/.test(previous) ? 1 + 3 * jitter : 1;
+        const delay = jitter ? interval * pause * (1 + jitter * (random() * 2 - 1)) : interval;
+        await new Promise((resolve) => setTimeout(resolve, Math.max(0, delay)));
+        if (options.signal?.aborted)
+            return;
+        yield words.slice(i, i + size).join("");
+        i += size;
+    }
+}
+const reducedMotion = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+/**
+ * Natural height of `el`'s content while its own height is pinned: the contents' range box (descendants overflowing the
+ * pinned box included) plus the last child's bottom margin and `el`'s bottom padding / border. Not `scrollHeight`: with
+ * `overflow: clip` the element is no scroll container and `scrollHeight` stops at the pinned height.
+ */
+function contentHeight(el) {
+    const top = el.getBoundingClientRect().top;
+    const range = el.ownerDocument.createRange();
+    range.selectNodeContents(el);
+    const style = getComputedStyle(el);
+    const last = el.lastElementChild;
+    const margin = last ? parseFloat(getComputedStyle(last).marginBottom) || 0 : 0;
+    return Math.ceil(range.getBoundingClientRect().bottom - top + margin + (parseFloat(style.paddingBottom) || 0) + (parseFloat(style.borderBottomWidth) || 0));
+}
+/**
+ * While `active()` is true, `el` grows smoothly instead of jumping a line / block at a time: its height is pinned in px
+ * (`overflow: clip`) and eased toward its content height (range box of its contents) one rAF step per frame, each step
+ * capped at `maxSpeed` (no single-frame jump), shrinking the same way. DOM changes (MutationObserver) wake the loop;
+ * it sleeps once the height has settled. When `active()` turns false the last growth finishes and the height is
+ * released to `auto`. Reduced motion / no MutationObserver: a no-op. Browser only. Returns a disposer.
+ */
+export function followHeight(el, active, options = {}) {
+    if (typeof MutationObserver === "undefined" || typeof requestAnimationFrame !== "function" || reducedMotion())
+        return () => { };
+    const style = el.style;
+    const maxSpeed = options.maxSpeed ?? 240;
+    const smoothing = options.smoothing ?? 90;
+    let frame = 0;
+    let on = false;
+    let pinned = false;
+    let height = 0;
+    let last = 0;
+    const release = () => {
+        pinned = false;
+        style.height = "";
+        style.overflow = "";
+    };
+    const step = (now) => {
+        frame = 0;
+        const dt = last ? Math.min(now - last, 50) : 1000 / 60;
+        last = now;
+        const gap = contentHeight(el) - height;
+        if (Math.abs(gap) < 0.5) {
+            height += gap;
+            style.height = `${height}px`;
+            last = 0;
+            if (!on)
+                release();
+            return;
+        }
+        const eased = Math.abs(gap) * (1 - Math.exp(-dt / smoothing));
+        height += Math.sign(gap) * Math.max(0.5, Math.min(eased, (maxSpeed * dt) / 1000));
+        style.height = `${height}px`;
+        frame = requestAnimationFrame(step);
+    };
+    const wake = () => {
+        if (!frame && pinned)
+            frame = requestAnimationFrame(step);
+    };
+    const observer = new MutationObserver(wake);
+    const start = () => {
+        if (on)
+            return;
+        on = true;
+        if (!pinned) {
+            pinned = true;
+            height = el.getBoundingClientRect().height;
+            style.height = `${height}px`;
+            style.overflow = "clip";
+        }
+        observer.observe(el, { subtree: true, childList: true, characterData: true });
+        wake();
+    };
+    // The loop keeps measuring until the height settles (the finished markup may still change after the stream ends).
+    const stop = () => {
+        if (!on)
+            return;
+        on = false;
+        observer.disconnect();
+        wake();
+    };
+    const dispose = effect(() => {
+        if (active())
+            start();
+        else
+            stop();
+    });
+    return () => {
+        dispose();
+        on = false;
+        observer.disconnect();
+        if (frame)
+            cancelAnimationFrame(frame);
+        frame = 0;
+        if (pinned)
+            release();
+    };
+}

package/checkbox/behaviour.d.ts

@@ -0,0 +1,172 @@
+import type { Ref } from "@rivetjs/runtime/jsx-runtime";
+import { createToggleState, type ToggleState, type ToggleStateOptions } from "../state/toggle.js";
+import { type FormValidationState, type MaybeAccessor, type ValidationBehavior, type ValidationErrors, type ValidationFunction, type ValidationResult } from "../state/form-validation.js";
+import { type CheckboxGroupState } from "../state/checkbox-group.js";
+import { type PressEvents } from "../interactions/press.jsx";
+import { type SlotId } from "../slots/index.jsx";
+export type PropBag = Record<string, unknown>;
+/** The input element ref (`ref()` from `@rivetjs/runtime/dom`). */
+export type InputRef = Ref<HTMLInputElement>;
+/** RA `AriaToggleProps` (+ `ToggleProps`, `InputDOMProps`, `AriaValidationProps`, `PressEvents`, `FocusableProps`). */
+export interface AriaToggleProps extends ToggleStateOptions, PressEvents {
+    /** The label content (RA: whether there is one; only its presence matters). */
+    children?: unknown;
+    /** The value of the input element, used when submitting an HTML form. Read once at mount (a group's item key). */
+    value?: string;
+    /** The name of the input element, used when submitting an HTML form. Read once at mount (form identity). */
+    name?: string;
+    /** The `<form>` element to associate the input with. Read once at mount (form identity). */
+    form?: string;
+    /** Whether the input is disabled (a value, or an accessor that stays live). */
+    isDisabled?: boolean | (() => boolean | undefined);
+    /** Whether the input is read-only (a value, or an accessor that stays live). */
+    isReadOnly?: MaybeAccessor<boolean | undefined>;
+    /** Whether the input is required (a value, or an accessor that stays live). */
+    isRequired?: MaybeAccessor<boolean | undefined>;
+    /** Whether the input value is invalid (a value, or an accessor that stays live). */
+    isInvalid?: MaybeAccessor<boolean | undefined>;
+    validate?: ValidationFunction<boolean>;
+    /** @default 'aria' (RA hook default; RAC components pass "native" or the Form's) */
+    validationBehavior?: ValidationBehavior;
+    /** Server errors (RAC: the enclosing `<Form>`'s `FormValidationContext`). */
+    validationErrors?: MaybeAccessor<ValidationErrors | undefined>;
+    id?: string;
+    autoFocus?: boolean;
+    excludeFromTabOrder?: boolean;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    "aria-errormessage"?: string;
+    /** Identifies the element (or elements) whose contents or presence are controlled by the current element. */
+    "aria-controls"?: string;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+    onKeyDown?: (e: KeyboardEvent) => void;
+    onKeyUp?: (e: KeyboardEvent) => void;
+}
+/** RA `AriaCheckboxProps`. */
+export interface AriaCheckboxProps extends AriaToggleProps {
+    /** Indeterminism is presentational only (a value, or an accessor that stays live). */
+    isIndeterminate?: MaybeAccessor<boolean | undefined>;
+}
+/** RA `ToggleAria` / `CheckboxAria` / `SwitchAria`. */
+export interface ToggleAria {
+    /** Props for the label wrapper element. */
+    labelProps: PropBag;
+    /** Props for the input element. */
+    inputProps: PropBag;
+    /** Props for the description element, if any (`id` is a slot id: provide it through `TextContext`). */
+    descriptionProps: {
+        id: SlotId;
+    };
+    /** Props for the error message element, if any (slot id). */
+    errorMessageProps: {
+        id: SlotId;
+    };
+    isSelected: () => boolean;
+    isPressed: () => boolean;
+    isDisabled: () => boolean;
+    isReadOnly: () => boolean;
+    isInvalid: () => boolean;
+    validationErrors: () => string[];
+    validationDetails: () => ValidationResult["validationDetails"];
+    /** Rivet: the toggle state the bags read. */
+    state: ToggleState;
+    /** Rivet: the input ref the bags set (focused on label press). */
+    inputRef: InputRef;
+}
+/**
+ * RA `privateValidationStateProp`: the validation a group item reports to (the group's), instead of its own.
+ * @internal
+ */
+export interface ItemValidation {
+    group: CheckboxGroupState;
+    value: string;
+    /** The item's own validation (behaviour "aria": realtime only). */
+    own: FormValidationState;
+    behavior: ValidationBehavior;
+}
+/**
+ * One input ref from the component's own ref and the user's (`inputRef` prop, context `inputRef`): a
+ * callback ref for the element that is also readable (`ref()` → the element), like RA `useObjectRef(mergeRefs(…))`.
+ */
+export declare function mergeInputRefs(...refs: (InputRef | ((el: HTMLInputElement | null) => unknown) | {
+    current: HTMLInputElement | null;
+} | undefined)[]): InputRef;
+/** What the input handlers act on. */
+export interface ToggleContext {
+    state: ToggleState;
+    validation: FormValidationState;
+    item?: ItemValidation;
+}
+/** RA `useToggle`. */
+export declare function toggleProps(props: AriaToggleProps, state: ToggleState, inputRef?: InputRef, item?: ItemValidation): ToggleAria;
+/** RA `useCheckbox`: `toggleProps` + the label `onMouseDown` (keep focus off the label) + `indeterminate`. */
+export declare function checkboxProps(props: AriaCheckboxProps, state: ToggleState, inputRef?: InputRef, item?: ItemValidation): ToggleAria;
+/** RA `checkboxGroupData` entry: kept on the group state (`state.data`). */
+export interface CheckboxGroupData {
+    name?: string;
+    form?: string;
+    descriptionId?: SlotId;
+    errorMessageId?: SlotId;
+    validationBehavior: ValidationBehavior;
+}
+/** RA `AriaCheckboxGroupProps`. */
+export interface AriaCheckboxGroupProps {
+    /** Whether a visible label renders (RA `label`: any truthy content). */
+    label?: unknown;
+    /** A value, or an accessor that stays live (live props). */
+    isDisabled?: MaybeAccessor<boolean | undefined>;
+    isReadOnly?: MaybeAccessor<boolean | undefined>;
+    isRequired?: MaybeAccessor<boolean | undefined>;
+    name?: string;
+    form?: string;
+    /** @default 'aria' */
+    validationBehavior?: ValidationBehavior;
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-details"?: string;
+    onFocus?: (e: FocusEvent) => void;
+    onBlur?: (e: FocusEvent) => void;
+    onFocusChange?: (isFocused: boolean) => void;
+}
+export interface CheckboxGroupAria {
+    groupProps: PropBag;
+    labelProps: PropBag;
+    descriptionProps: {
+        id: SlotId;
+    };
+    errorMessageProps: {
+        id: SlotId;
+    };
+    isInvalid: () => boolean;
+    validationErrors: () => string[];
+    validationDetails: () => ValidationResult["validationDetails"];
+}
+/** RA `useCheckboxGroup`. */
+export declare function checkboxGroupProps(props: AriaCheckboxGroupProps, state: CheckboxGroupState): CheckboxGroupAria;
+/** RA `AriaCheckboxGroupItemProps`. */
+export interface AriaCheckboxGroupItemProps extends Omit<AriaCheckboxProps, "isSelected" | "defaultSelected"> {
+    value: string;
+}
+/** RA `useCheckboxGroupItem`. */
+export declare function checkboxGroupItemProps(props: AriaCheckboxGroupItemProps, state: CheckboxGroupState, inputRef?: InputRef): ToggleAria;
+/** Label press (mouse / touch): toggle, focus the input, commit validation (RA `useToggle` label `onPress`). */
+export declare function toggleLabelPress(ctx: ToggleContext, inputRef: InputRef): void;
+/** `change` on the input (RA `onChange`: `setSelected(checked)`; useFormValidation commits). */
+export declare function toggleChange(event: Event, _props: object, ctx: ToggleContext): void;
+/** `focus` on the input: sync the custom validity (server / validate errors) before a submit. */
+export declare function toggleFocus(event: FocusEvent, _props: object, ctx: ToggleContext): void;
+/** `invalid` on the input (RA useFormValidation `onInvalid`). */
+export declare function toggleInvalid(event: Event, _props: object, ctx: ToggleContext): void;
+/**
+ * Native group validation (RA useCheckboxGroupItem → useFormValidation layout effect with the group's
+ * validation): the group's realtime error is the custom validity of every checkbox; native validities
+ * (required) merge into the group's next result.
+ */
+export declare function syncGroupValidity(group: CheckboxGroupState, input: HTMLInputElement, behavior?: ValidationBehavior): void;
+export { createToggleState };