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

package/state/tooltip.js

@@ -0,0 +1,153 @@
+// Ported from React Stately (@react-stately/tooltip useTooltipTriggerState), Apache-2.0, © Adobe.
+// Modifications: the open state is a serializable signal (`isOpen` / `defaultOpen`), created as region
+// state (a resumed page re-creating the tooltip's region keeps it); the methods are free functions
+// (`openTooltip(state)`, `closeTooltip(state)`) so state stays JSON and handlers resume. Per-instance
+// timers live in a browser-side WeakMap keyed by the state object (never serialized); the global
+// warmup / cooldown state is module state, as in the original (one per page, created on first use),
+// held in one mutable object (resume-extracted symbols import module bindings read-only).
+import { signal, untrack, _regionState } from "@rivetjs/reactivity";
+import { createOverlayTriggerState, setOpen } from "./overlays.js";
+export const TOOLTIP_DELAY = 1500; // this seems to be a 1.5 second delay, check with design
+export const TOOLTIP_COOLDOWN = 500;
+/** The show delay now (ms): the live accessor when given (untracked: event time), else `state.delay`. */
+export const tooltipDelay = (state) => (state.live?.delay ? (untrack(state.live.delay) ?? TOOLTIP_DELAY) : state.delay);
+/** The close delay now (ms): the live accessor when given (untracked: event time), else `state.closeDelay`. */
+export const tooltipCloseDelay = (state) => state.live?.closeDelay ? (untrack(state.live.closeDelay) ?? TOOLTIP_COOLDOWN) : state.closeDelay;
+// Global state (react-stately module scope): which tooltips are open, the warmup and cooldown timers.
+const tooltips = new Map();
+const g = {
+    globalWarmedUp: false,
+    globalWarmUpTimeout: null,
+    globalCooldownTimeout: null,
+};
+// `closeTimeout` ref of the original, per state object.
+const closeTimeouts = new WeakMap();
+/**
+ * Manages state for a tooltip trigger. Tracks whether the tooltip is open, and provides methods to
+ * toggle this state. Ensures only one tooltip is open at a time and controls the delay for showing a
+ * tooltip (react-stately `useTooltipTriggerState`).
+ */
+export function createTooltipTriggerState(props = {}) {
+    const delayProp = props.delay, closeDelayProp = props.closeDelay;
+    const liveDelay = typeof delayProp === "function" ? delayProp : undefined;
+    const liveCloseDelay = typeof closeDelayProp === "function" ? closeDelayProp : undefined;
+    const delay = (liveDelay ? untrack(liveDelay) : delayProp) ?? TOOLTIP_DELAY;
+    const closeDelay = (liveCloseDelay ? untrack(liveCloseDelay) : closeDelayProp) ?? TOOLTIP_COOLDOWN;
+    const live = liveDelay || liveCloseDelay ? { delay: liveDelay, closeDelay: liveCloseDelay } : undefined;
+    return _regionState(() => ({ ...createOverlayTriggerState(props), shouldSkipAnimation: signal(false), delay, closeDelay, ...(live ? { live } : {}) }));
+}
+const ensureTooltipEntry = (state) => {
+    tooltips.set(state, (immediate, instant) => hideTooltip(state, immediate, instant));
+};
+const closeOpenTooltips = (state) => {
+    for (const [other, hide] of tooltips)
+        if (other !== state) {
+            // Close other open tooltips instantly (no exit animation), since they are being replaced by
+            // this one during the warmup period.
+            hide(true, true);
+            tooltips.delete(other);
+        }
+};
+function showTooltip(state, instant) {
+    const closeTimeout = closeTimeouts.get(state);
+    if (closeTimeout)
+        clearTimeout(closeTimeout);
+    closeTimeouts.set(state, null);
+    closeOpenTooltips(state);
+    ensureTooltipEntry(state);
+    state.shouldSkipAnimation.set(!!instant);
+    g.globalWarmedUp = true;
+    setOpen(state, true);
+    if (g.globalWarmUpTimeout) {
+        clearTimeout(g.globalWarmUpTimeout);
+        g.globalWarmUpTimeout = null;
+    }
+    if (g.globalCooldownTimeout) {
+        clearTimeout(g.globalCooldownTimeout);
+        g.globalCooldownTimeout = null;
+    }
+}
+function hideTooltip(state, immediate, instant) {
+    state.shouldSkipAnimation.set(!!instant);
+    const closeDelay = tooltipCloseDelay(state);
+    if (immediate || closeDelay <= 0) {
+        const closeTimeout = closeTimeouts.get(state);
+        if (closeTimeout)
+            clearTimeout(closeTimeout);
+        closeTimeouts.set(state, null);
+        setOpen(state, false);
+    }
+    else if (!closeTimeouts.get(state)) {
+        closeTimeouts.set(state, setTimeout(() => {
+            closeTimeouts.set(state, null);
+            setOpen(state, false);
+        }, closeDelay));
+    }
+    if (g.globalWarmUpTimeout) {
+        clearTimeout(g.globalWarmUpTimeout);
+        g.globalWarmUpTimeout = null;
+    }
+    if (g.globalWarmedUp) {
+        if (g.globalCooldownTimeout)
+            clearTimeout(g.globalCooldownTimeout);
+        g.globalCooldownTimeout = setTimeout(() => {
+            tooltips.delete(state);
+            g.globalCooldownTimeout = null;
+            g.globalWarmedUp = false;
+        }, Math.max(TOOLTIP_COOLDOWN, closeDelay));
+    }
+}
+function warmupTooltip(state) {
+    closeOpenTooltips(state);
+    ensureTooltipEntry(state);
+    const isOpen = untrack(state.isOpen);
+    if (!isOpen && !g.globalWarmedUp) {
+        if (g.globalWarmUpTimeout)
+            clearTimeout(g.globalWarmUpTimeout);
+        g.globalWarmUpTimeout = setTimeout(() => {
+            g.globalWarmUpTimeout = null;
+            g.globalWarmedUp = true;
+            // First tooltip in a sequence: animate in.
+            showTooltip(state, false);
+        }, tooltipDelay(state));
+    }
+    else if (!isOpen) {
+        // Already warmed up: appear instantly without an animation.
+        showTooltip(state, true);
+    }
+}
+/**
+ * Shows the tooltip. By default, the tooltip becomes visible after a delay depending on a global
+ * warmup timer. The `immediate` option shows the tooltip immediately instead.
+ */
+export function openTooltip(state, immediate) {
+    if (!immediate && tooltipDelay(state) > 0 && !closeTimeouts.get(state))
+        warmupTooltip(state);
+    // Immediate opens (e.g. focus, or delay of 0) appear instantly without an animation only if
+    // another tooltip is already warmed up.
+    else
+        showTooltip(state, g.globalWarmedUp);
+}
+/** Hides the tooltip (after `closeDelay` unless `immediate`). */
+export function closeTooltip(state, immediate) {
+    hideTooltip(state, immediate);
+}
+/** The original's unmount effect: cancel the close timer and drop the tooltip from the registry. */
+export function disposeTooltip(state) {
+    const closeTimeout = closeTimeouts.get(state);
+    if (closeTimeout)
+        clearTimeout(closeTimeout);
+    closeTimeouts.delete(state);
+    tooltips.delete(state);
+}
+/** Test hook: reset the global warmup / cooldown state. */
+export function _resetTooltips() {
+    for (const state of [...tooltips.keys()])
+        disposeTooltip(state);
+    if (g.globalWarmUpTimeout)
+        clearTimeout(g.globalWarmUpTimeout);
+    if (g.globalCooldownTimeout)
+        clearTimeout(g.globalCooldownTimeout);
+    g.globalWarmUpTimeout = g.globalCooldownTimeout = null;
+    g.globalWarmedUp = false;
+}

package/stepper/index.d.ts

@@ -0,0 +1,117 @@
+import { type ButtonProps } from "../button/index.jsx";
+import { type GlobalDOMAttributes } from "../utils/dom-props.js";
+import type { DOMRenderProps } from "../utils/render.js";
+import { type RefValue, type RenderProps } from "../slots/index.jsx";
+import { type StepContentPositionState, type StepItemState, type StepperOrientation, type StepperState, type StepperStateProps, type StepState, type StepStateProps } from "./state.js";
+export * from "./state.js";
+/** The state of the nearest `Stepper` (`null` outside one). */
+export declare const StepperContext: import("@rivetjs/reactivity").Context<StepperState | null>;
+/** The nearest `Step`: its stepper + state (`null` outside one). */
+export interface StepContextValue {
+    stepper: StepperState;
+    step: StepItemState;
+}
+export declare const StepContext: import("@rivetjs/reactivity").Context<StepContextValue | null>;
+/** The nearest stepper's API (throws outside a `Stepper`): accessors + actions (upstream `CdkStepper` methods). */
+export interface StepperApi {
+    state: StepperState;
+    selectedIndex: () => number;
+    stepCount: () => number;
+    orientation: () => StepperOrientation;
+    select: (index: number) => void;
+    next: () => void;
+    previous: () => void;
+    reset: () => void;
+}
+/** The nearest `Stepper`'s API. */
+export declare function useStepper(): StepperApi;
+/** Render props of a step (accessors). */
+export interface StepRenderProps {
+    /** Zero-based index. `[data-index]` */
+    index: () => number;
+    /** Whether the step is selected. `[data-selected]` */
+    isSelected: () => boolean;
+    /** Whether the step is completed (upstream `completed`). `[data-completed]` */
+    isCompleted: () => boolean;
+    /** Whether the step has an error that is shown (`showError`). `[data-invalid]` */
+    hasError: () => boolean;
+    /** Whether the user can navigate to the step. `[data-disabled]` when not. */
+    isNavigable: () => boolean;
+    /** `[data-optional]` */
+    isOptional: () => boolean;
+    /** `[data-editable]` */
+    isEditable: () => boolean;
+    /** Whether this is the last registered step (exact once every step rendered: client side). */
+    isLast: () => boolean;
+    /** Indicator type (upstream `indicatorType`: number / edit / done / error / custom). `[data-state]` */
+    state: () => StepState;
+    /** Orientation of the stepper. `[data-orientation]` */
+    orientation: () => StepperOrientation;
+}
+/** The nearest `Step`'s render props (throws outside a `Step`). */
+export declare function useStep(): StepRenderProps;
+interface PartProps<E extends Element> extends GlobalDOMAttributes<E> {
+    id?: string;
+    ref?: RefValue<E>;
+    [attribute: `aria-${string}`]: unknown;
+}
+/** Render props of the stepper (accessors). */
+export interface StepperRenderProps {
+    /** `[data-selected-index]` */
+    selectedIndex: () => number;
+    stepCount: () => number;
+    /** `[data-orientation]` */
+    orientation: () => StepperOrientation;
+}
+export interface StepperProps extends StepperStateProps, RenderProps<StepperRenderProps>, DOMRenderProps<"div", StepperRenderProps>, PartProps<HTMLElement> {
+}
+/** The stepper root: owns the state (upstream `CdkStepper`). `div` (tabs semantics) or `ol` (list semantics). */
+export declare function Stepper(props: StepperProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface StepListProps extends RenderProps<StepperRenderProps>, DOMRenderProps<"div", StepperRenderProps>, PartProps<HTMLDivElement> {
+}
+/**
+ * The header strip (Material's header container): `role="tablist"` + `aria-orientation` for a horizontal tabs
+ * stepper, a plain `div` otherwise. `aria-label` / `aria-labelledby` land here.
+ */
+export declare function StepList(props: StepListProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface StepProps extends StepStateProps, RenderProps<StepRenderProps>, DOMRenderProps<"div", StepRenderProps>, PartProps<HTMLElement> {
+}
+/** One step (upstream `CdkStep`): registers with the stepper, provides `StepContext`. `div` or `li` (list semantics). */
+export declare function Step(props: StepProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** Render props of a header (the step's, + interaction states as attributes). */
+export type StepHeaderRenderProps = StepRenderProps;
+export interface StepHeaderProps extends RenderProps<StepHeaderRenderProps>, DOMRenderProps<"div", StepHeaderRenderProps>, PartProps<HTMLElement> {
+}
+/**
+ * The step's header (upstream `CdkStepHeader` + Material's header attributes): click / Enter / Space select the step
+ * (validation permitting), arrows move focus between headers (tabs semantics). Default content: the step `label`.
+ */
+export declare function StepHeader(props: StepHeaderProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export interface StepLabelProps extends RenderProps<StepRenderProps>, DOMRenderProps<"div", StepRenderProps>, PartProps<HTMLDivElement> {
+}
+/** The step's label (upstream `CdkStepLabel`): a `div` inside the header, with the step's state attributes. */
+export declare function StepLabel(props: StepLabelProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** Render props of a panel. */
+export interface StepPanelRenderProps {
+    index: () => number;
+    isSelected: () => boolean;
+    /** `[data-position]` */
+    position: () => StepContentPositionState;
+    orientation: () => StepperOrientation;
+}
+export interface StepPanelProps extends RenderProps<StepPanelRenderProps>, DOMRenderProps<"div", StepPanelRenderProps>, PartProps<HTMLDivElement> {
+    /** Index of the step this panel belongs to; omit inside a `Step` (that step). */
+    index?: number;
+}
+/**
+ * The content of a step (Material's content containers): `role="tabpanel"` (horizontal) / `"region"` (vertical),
+ * labelled by the header; hidden + inert unless its step is selected; `data-position` previous / current / next.
+ */
+export declare function StepPanel(props: StepPanelProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+export type StepperButtonProps = Omit<ButtonProps, "onPress"> & {
+    onPress?: ButtonProps["onPress"];
+};
+/** Moves to the next step (upstream `CdkStepperNext`; `type` default `"submit"`). */
+export declare function StepperNext(props: StepperButtonProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;
+/** Moves to the previous step (upstream `CdkStepperPrevious`; `type` default `"button"`). */
+export declare function StepperPrevious(props: StepperButtonProps): import("@rivetjs/runtime/jsx-runtime").CompiledElement;