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

package/resizable/index.d.ts

@@ -0,0 +1,263 @@
+import type { Content, JSX } from "@rivetjs/runtime/jsx-runtime";
+import type { StyleObject } from "../utils/types.js";
+import type { RefValue } from "../slots/index.jsx";
+import { type GroupState, type MaybeAccessor } from "./mount.js";
+import type { Layout, Orientation, ResizePreviewMode, ResizeTargetMinimumSize } from "./engine/global/types.js";
+import type { GroupImperativeHandle, LayoutChangedMeta, LayoutStorage } from "./engine/components/group/types.js";
+import type { OnPanelResize, PanelImperativeHandle, PanelSize, SizeUnit, GroupResizeBehavior } from "./engine/components/panel/types.js";
+export { isCoarsePointer } from "./engine/global/utils/isCoarsePointer.js";
+export type { Layout, LayoutChangedMeta, LayoutStorage, Orientation, ResizePreviewMode, ResizeTargetMinimumSize };
+export type { GroupImperativeHandle, OnPanelResize, PanelImperativeHandle, PanelSize, SizeUnit, GroupResizeBehavior };
+export type { GroupState };
+type DivAttributes = Omit<JSX.IntrinsicElements["div"], "children" | "style" | "ref" | "class" | "id">;
+/** A ref object (`useGroupRef()` / `usePanelRef()`) or a function receiving the handle. */
+export type ImperativeRef<T> = {
+    current: T | null;
+} | ((handle: T | null) => void);
+/** The nearest Group's state (upstream `GroupContext`). */
+export declare const GroupContext: import("@rivetjs/reactivity").Context<GroupState | null>;
+export interface GroupProps extends DivAttributes {
+    /** Panel and Separator components that comprise this group. */
+    children?: Content;
+    /** CSS class name (default `rv-ResizableGroup`). */
+    class?: string;
+    /**
+     * Default layout for the Group (map of Panel id to percentage).
+     *
+     * ℹ️ This value allows layouts to be remembered between page reloads (`useDefaultLayout`); rendered by the server.
+     */
+    defaultLayout?: MaybeAccessor<Layout | undefined>;
+    /**
+     * This library sets custom mouse cursor styles to indicate drag state.
+     * Use this prop to disable that behavior for Panels and Separators in this group.
+     */
+    disableCursor?: MaybeAccessor<boolean | undefined>;
+    /** Disable resize functionality. */
+    disabled?: MaybeAccessor<boolean | undefined>;
+    /** Ref attached to the root `HTMLDivElement`. */
+    elementRef?: RefValue<HTMLDivElement>;
+    /**
+     * Exposes the following imperative API:
+     * - `getLayout(): Layout`
+     * - `setLayout(layout: Layout): void`
+     */
+    groupRef?: ImperativeRef<GroupImperativeHandle>;
+    /**
+     * Uniquely identifies this group within an application (falls back to a generated id).
+     *
+     * ℹ️ This value will also be assigned to the `id` and `data-testid` attributes.
+     */
+    id?: string | number;
+    /**
+     * Called when the Group's layout is changing.
+     *
+     * ⚠️ For layout changes caused by pointer events, this method is called each time the pointer is moved.
+     * For most cases, it is recommended to use the `onLayoutChanged` callback instead.
+     */
+    onLayoutChange?: (layout: Layout) => void;
+    /**
+     * Called after the Group's layout has been changed (pointer: once released). Recommended for persisting layouts;
+     * `meta.isUserInteraction` is true for pointer / keyboard input, `meta.requestedLayout` is the layout before
+     * size-dependent constraints (prefer it when persisting).
+     */
+    onLayoutChanged?: (layout: Layout, meta: LayoutChangedMeta) => void;
+    /**
+     * Whether pointer dragging resizes `Panel`s immediately (`"panel"`, default) or renders separator previews until
+     * the pointer is released (`"separator"`; customize with `SeparatorOverlay`).
+     */
+    resizePreviewMode?: ResizePreviewMode;
+    /**
+     * Minimum size of the resizable hit target area (either `Separator` or `Panel` edge), for coarse (touch) and fine
+     * (mouse) pointers. @default { coarse: 20, fine: 10 }
+     */
+    resizeTargetMinimumSize?: ResizeTargetMinimumSize;
+    /** Specifies the resizable orientation. @default "horizontal" */
+    orientation?: Orientation;
+    /** CSS properties (the layout styles cannot be overridden, except for `overflow`). */
+    style?: StyleObject;
+}
+/**
+ * A Group wraps a set of resizable Panel components. Group content can be resized _horizontally_ or _vertically_.
+ *
+ * Group elements always include the following attributes:
+ *
+ * ```html
+ * <div data-group data-testid="group-id-prop" id="group-id-prop">
+ * ```
+ */
+export declare function Group(props: GroupProps): JSX.Element;
+export interface PanelProps extends Omit<DivAttributes, "onResize"> {
+    children?: Content;
+    /** CSS class name of the inner element (upstream: avoids styles that interfere with the flex layout). */
+    class?: string;
+    /** Panel size when collapsed. @default "0%" */
+    collapsedSize?: number | string;
+    /**
+     * Distance a collapsible panel must be resized past its `minSize` to collapse, or past its `collapsedSize` to
+     * expand. Defaults to half the distance between `collapsedSize` and `minSize`.
+     */
+    collapsedThreshold?: number | string;
+    /** This panel can be collapsed (when resized below its `minSize`). */
+    collapsible?: boolean;
+    /**
+     * Default size of Panel within its parent group; default is auto-assigned based on the total number of Panels.
+     *
+     * ℹ️ Numbers are pixels, strings without units percentages; explicit units: "px", "%", "em", "rem", "vh", "vw".
+     */
+    defaultSize?: number | string;
+    /** When disabled, a panel cannot be resized either directly or indirectly (by resizing another panel). */
+    disabled?: MaybeAccessor<boolean | undefined>;
+    /** Ref attached to the root `HTMLDivElement`. */
+    elementRef?: RefValue<HTMLDivElement>;
+    /**
+     * How should this Panel behave if the parent Group is resized? `preserve-relative-size` (percentage) or
+     * `preserve-pixel-size`. ⚠️ A Group must contain at least one Panel with `preserve-relative-size`.
+     * @default "preserve-relative-size"
+     */
+    groupResizeBehavior?: GroupResizeBehavior;
+    /**
+     * Uniquely identifies this panel within the parent group (falls back to a generated id); persisted layouts key on it.
+     * Also assigned to the `id` and `data-testid` attributes.
+     */
+    id?: string | number;
+    /** Maximum size of Panel within its parent group. @default "100%" */
+    maxSize?: number | string;
+    /** Minimum size of Panel within its parent group. @default "0%" */
+    minSize?: number | string;
+    /** Called when panel sizes change (size as a percentage and in pixels, the `id` prop, the previous size). */
+    onResize?: OnPanelResize;
+    /**
+     * Exposes the following imperative API: `collapse()`, `expand()`, `getSize()`, `isCollapsed()`, `resize(size)`.
+     */
+    panelRef?: ImperativeRef<PanelImperativeHandle>;
+    /** CSS properties of the inner element. */
+    style?: StyleObject;
+}
+/**
+ * A Panel wraps resizable content and can be configured with min/max size constraints and collapsible behavior.
+ *
+ * Panel elements always include the following attributes:
+ *
+ * ```html
+ * <div data-panel data-testid="panel-id-prop" id="panel-id-prop">
+ * ```
+ *
+ * ⚠️ Panel elements must be direct DOM children of their parent Group elements.
+ */
+export declare function Panel(props: PanelProps): JSX.Element;
+export interface SeparatorProps extends Omit<DivAttributes, "role" | "tabIndex"> {
+    children?: Content;
+    /**
+     * CSS class name (default `rv-ResizableSeparator`).
+     *
+     * ℹ️ Use the `data-separator` attribute for custom _hover_ and _active_ styles
+     */
+    class?: string;
+    /**
+     * When disabled, the separator cannot be used to resize its neighboring panels (they may still resize indirectly).
+     */
+    disabled?: MaybeAccessor<boolean | undefined>;
+    /** When true, double-clicking this `Separator` will not reset its `Panel` to its default size. */
+    disableDoubleClick?: boolean;
+    /** Ref attached to the root `HTMLDivElement`. */
+    elementRef?: RefValue<HTMLDivElement>;
+    /** Uniquely identifies the separator within the parent group (falls back to a generated id). */
+    id?: string | number;
+    /**
+     * Overrides the `Group` default preview for this `Separator` when `resizePreviewMode` is "separator": a function
+     * returning the preview content (or `<SeparatorOverlay … />`).
+     */
+    preview?: () => unknown;
+    /** CSS properties (`flex-grow` / `flex-shrink` cannot be overridden). */
+    style?: StyleObject;
+}
+/**
+ * Separators are not _required_ but they are _recommended_ as they improve keyboard accessibility.
+ *
+ * ⚠️ Separator elements must be direct DOM children of their parent Group elements.
+ *
+ * ```html
+ * <div data-separator data-testid="separator-id-prop" id="separator-id-prop" role="separator">
+ * ```
+ */
+export declare function Separator(props: SeparatorProps): JSX.Element;
+export interface SeparatorOverlayProps extends DivAttributes {
+    class?: string;
+    style?: StyleObject;
+}
+/**
+ * Customizes separator previews when resizePreviewMode is "separator".
+ * Render within a `Group` to style all overlay previews, or return it from an individual `Separator`'s `preview`
+ * function to style its overlay preview.
+ *
+ * Use `data-separator-overlay="active"` to style the separator being dragged,
+ * or `data-separator-overlay="inactive"` for separators moved indirectly.
+ *
+ * Set `width` (horizontal groups) or `height` (vertical groups) using `style` or `class`.
+ */
+export declare function SeparatorOverlay(props: SeparatorOverlayProps): JSX.Element;
+/** Convenience hook to return a properly typed ref for the Group component. */
+export declare function useGroupRef(): {
+    current: GroupImperativeHandle | null;
+};
+/** Convenience hook to return a properly typed ref for the Panel component. */
+export declare function usePanelRef(): {
+    current: PanelImperativeHandle | null;
+};
+/**
+ * Convenience hook to return a properly typed ref callback for the Group component: `[handle, setHandle]` (Rivet:
+ * `handle` is an accessor, upstream React state).
+ */
+export declare function useGroupCallbackRef(): [() => GroupImperativeHandle | null, (handle: GroupImperativeHandle | null) => void];
+/**
+ * Convenience hook to return a properly typed ref callback for the Panel component: `[handle, setHandle]` (Rivet:
+ * `handle` is an accessor, upstream React state).
+ */
+export declare function usePanelCallbackRef(): [() => PanelImperativeHandle | null, (handle: PanelImperativeHandle | null) => void];
+export interface UseDefaultLayoutOptions {
+    /**
+     * Debounce save operation by the specified number of milliseconds; defaults to 100ms
+     * @deprecated Use the `onLayoutChanged` callback instead; it does not require debouncing
+     */
+    debounceSaveMs?: number;
+    /** Only auto-save layouts that were directly caused by user input (keyboard or pointer). */
+    onlySaveAfterUserInteractions?: boolean;
+    /**
+     * For Groups that contain conditionally-rendered Panels: save and restore one layout per set of panel ids.
+     * ⚠️ Panel ids must match the Panels rendered within the Group during mount or the initial layout will be incorrect.
+     */
+    panelIds?: string[];
+    /**
+     * Storage implementation; supports localStorage (default, browser only), sessionStorage, cookies
+     * (`cookieStorage(...)`: also read by the server, no layout shift) and custom implementations.
+     */
+    storage?: LayoutStorage;
+    /** Uniquely identifies a specific group/layout. */
+    id?: string;
+    /** @deprecated Use the `id` param instead */
+    groupId?: string;
+}
+/**
+ * Saves and restores group layouts between page loads (localStorage, sessionStorage, cookies or any other storage).
+ *
+ * Rivet: `defaultLayout` is an accessor (pass it to `Group` as is). The server renders the stored layout when its
+ * storage is readable there (`cookieStorage(request cookie header)`); when the server could not read one (browser-only
+ * storage, static prerender) the stored layout is applied at idle on the client.
+ */
+export declare function useDefaultLayout(options: UseDefaultLayoutOptions): {
+    defaultLayout: () => Layout | undefined;
+    onLayoutChange: (layout: Layout) => void;
+    onLayoutChanged: (layout: Layout, meta: LayoutChangedMeta) => void;
+};
+/**
+ * Rivet addition (upstream documents it as an example): a cookie `LayoutStorage`. Pass the request's `Cookie` header
+ * (or a cookie map) on the server so the stored layout is server-rendered; in the browser it reads `document.cookie`.
+ */
+export declare function cookieStorage(source?: string | {
+    get(name: string): string | undefined;
+} | null, options?: {
+    maxAge?: number;
+    path?: string;
+}): LayoutStorage & {
+    readonly ssr: true;
+};