h2o-library 2.0.0 → 2.1.0

package/dist/types/components/src/onboarding/onboarding.d.ts

@@ -0,0 +1,100 @@
+import "./onboarding.css";
+import type React from "react";
+import type { ReactNode } from "react";
+import { type OnboardingStorage, type UseOnboardingReturn } from "../../../hooks/src/use-onboarding";
+/** Where a step popup sits relative to its target. `"center"` ignores the target and centers on screen. */
+export type OnboardingPlacement = "top" | "bottom" | "left" | "right" | "auto" | "center";
+/**
+ * How a step finds its anchor element:
+ * - `string` — a CSS selector (e.g. `"#sidebar"`, `".profile"`, `"[data-tour=save]"`). A bare word falls back to an element id.
+ * - `HTMLElement` — the element directly.
+ * - `() => HTMLElement | null` — resolved lazily when the step shows.
+ */
+export type OnboardingTarget = string | HTMLElement | (() => HTMLElement | null);
+/**
+ * A single step in an onboarding flow.
+ *
+ * @property {OnboardingTarget} [target] - Element to anchor + spotlight. Omit for a centered step (welcome/finish screens).
+ * @property {ReactNode} [title] - Heading shown at the top of the popup.
+ * @property {ReactNode} content - Body message (required).
+ * @property {OnboardingPlacement} [placement] - Popup side. Default: the flow's `placement` (which defaults to `"auto"`).
+ * @property {number} [spotlightPadding] - Extra px around the target in the spotlight cutout.
+ * @property {number} [spotlightRadius] - Spotlight corner radius in px.
+ * @property {boolean} [disableInteraction] - Block clicks on the spotlighted element. Default: the flow's `disableInteraction`.
+ */
+export interface OnboardingStep {
+    target?: OnboardingTarget;
+    title?: ReactNode;
+    content: ReactNode;
+    placement?: OnboardingPlacement;
+    spotlightPadding?: number;
+    spotlightRadius?: number;
+    disableInteraction?: boolean;
+    showBack?: boolean;
+    showSkip?: boolean;
+    nextLabel?: string;
+    backLabel?: string;
+    finishLabel?: string;
+}
+/** Context passed to `renderStep` / `renderFooter` for fully custom popup UI. */
+export interface OnboardingRenderContext extends UseOnboardingReturn {
+    step: OnboardingStep;
+}
+/** Imperative handle exposed via `ref` on `Onboarding`. */
+export type OnboardingHandle = UseOnboardingReturn;
+/**
+ * Props for `Onboarding`. Most are flow-wide defaults that individual steps can override.
+ *
+ * @property {string} id - Stable flow id; persistence key.
+ * @property {OnboardingStep[]} steps - Ordered steps.
+ * @property {boolean} [run] - Controlled active state. Omit to auto-manage (see `autoStart`).
+ */
+export interface OnboardingProps {
+    id: string;
+    steps: OnboardingStep[];
+    run?: boolean;
+    autoStart?: boolean;
+    persist?: boolean;
+    storage?: OnboardingStorage;
+    startDelay?: number;
+    placement?: OnboardingPlacement;
+    spotlightPadding?: number;
+    spotlightRadius?: number;
+    disableInteraction?: boolean;
+    closeOnOverlayClick?: boolean;
+    closeOnEsc?: boolean;
+    keyboardNavigation?: boolean;
+    scrollIntoView?: boolean;
+    scrollBehavior?: ScrollBehavior;
+    offset?: number;
+    zIndex?: number;
+    showProgress?: boolean;
+    showSkip?: boolean;
+    showBack?: boolean;
+    showClose?: boolean;
+    nextLabel?: string;
+    backLabel?: string;
+    skipLabel?: string;
+    finishLabel?: string;
+    className?: string;
+    overlayClassName?: string;
+    onStart?: () => void;
+    onStepChange?: (index: number, previous: number, step: OnboardingStep) => void;
+    onSkip?: (index: number) => void;
+    onFinish?: () => void;
+    onClose?: () => void;
+    renderStep?: (ctx: OnboardingRenderContext) => ReactNode;
+    renderFooter?: (ctx: OnboardingRenderContext) => ReactNode;
+}
+/**
+ * Modular onboarding / product-tour overlay. Drive a flow by `id` with a `steps`
+ * array — each step spotlights an element (by selector/id) and shows a popup with
+ * Back / Skip / Next controls. Persists completion so a flow shows once.
+ *
+ * Headless control lives in {@link useOnboarding}; this component is the batteries-included UI.
+ *
+ * @param {OnboardingProps} props
+ * @param {React.Ref<OnboardingHandle>} ref - Imperative controls (`start`, `next`, `skip`, `reset`, …).
+ * @returns {JSX.Element | null} A portal with the spotlight overlay + popup while active.
+ */
+export declare const Onboarding: React.ForwardRefExoticComponent<OnboardingProps & React.RefAttributes<UseOnboardingReturn>>;

package/dist/types/components/src/radio-group/radio-group.d.ts

@@ -1,16 +1,19 @@
 import "./radio-group.css";
+import { Icon } from "../icon/icon";
 import type { IconType, TooltipPosition } from "../../../types";
 /**
  * One entry in a `RadioGroup` `options` array.
  * @property {string} label - Option title.
  * @property {string} value - Emitted to `onChange` when selected.
  * @property {import("../../../types").IconType} [icon] - Optional leading icon.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [iconProps] - Extra props forwarded to the built-in `Icon` (and its `<svg>`).
  * @property {"active"|"inactive"} [dot] - Optional status dot style when no icon.
  */
 export interface RadioOption {
     label: string;
     value: string;
     icon?: IconType;
+    iconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     dot?: "active" | "inactive";
     disabled?: boolean;
     tooltip?: string;

package/dist/types/hooks/index.d.ts

@@ -12,6 +12,7 @@ export * from "./src/use-key-press";
 export * from "./src/use-long-press";
 export * from "./src/use-media-query";
 export * from "./src/use-mouse";
+export * from "./src/use-onboarding";
 export * from "./src/use-timeout";
 export { useToast, ToastContext, type ToastContextType } from "./src/use-toast";
 export * from "./src/use-window-scroll";

package/dist/types/hooks/src/use-onboarding.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pluggable persistence adapter for onboarding flows. Swap to back completion
+ * with cookies, a backend, or anything else by implementing these two methods.
+ *
+ * @property {(id: string) => boolean} isCompleted - Whether the flow `id` was already finished/skipped.
+ * @property {(id: string, completed: boolean) => void} setCompleted - Persist (or clear) completion for `id`.
+ */
+export interface OnboardingStorage {
+    isCompleted: (id: string) => boolean;
+    setCompleted: (id: string, completed: boolean) => void;
+}
+export declare const localStorageOnboarding: OnboardingStorage;
+export declare const memoryOnboarding: OnboardingStorage;
+/**
+ * Options for {@link useOnboarding}.
+ *
+ * @property {string} id - Stable flow identifier; used as the persistence key.
+ * @property {number} total - Number of steps in the flow.
+ * @property {boolean} [run] - Controlled active state. Omit to let the hook manage start/stop internally.
+ * @property {boolean} [autoStart] - In uncontrolled mode, start on mount when the flow is not yet completed. Default `true`.
+ * @property {boolean} [persist] - Persist completion so a finished/skipped flow does not auto-restart. Default `true`.
+ * @property {OnboardingStorage} [storage] - Persistence adapter. Default `localStorageOnboarding`.
+ * @property {number} [startDelay] - Delay (ms) before auto-start, e.g. to let the page settle. Default `0`.
+ */
+export interface UseOnboardingOptions {
+    id: string;
+    total: number;
+    run?: boolean;
+    autoStart?: boolean;
+    persist?: boolean;
+    storage?: OnboardingStorage;
+    startDelay?: number;
+    onStart?: () => void;
+    onStepChange?: (index: number, previous: number) => void;
+    onSkip?: (index: number) => void;
+    onFinish?: () => void;
+    onStop?: () => void;
+}
+/** Imperative control surface + state returned by {@link useOnboarding}. */
+export interface UseOnboardingReturn {
+    active: boolean;
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    completed: boolean;
+    start: () => void;
+    stop: () => void;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    skip: () => void;
+    finish: () => void;
+    reset: () => void;
+}
+/**
+ * Headless onboarding/tour state machine: drives a flow by `id`, tracks the
+ * current step, persists completion, and supports controlled or uncontrolled use.
+ *
+ * Pair with the `Onboarding` component for ready-made coachmarks, or render your
+ * own UI from the returned state for a fully custom flow.
+ *
+ * @param {UseOnboardingOptions} options
+ * @returns {UseOnboardingReturn} State (`active`, `index`, `isFirst`, …) and controls (`next`, `prev`, `skip`, `finish`, `reset`, …).
+ */
+export declare function useOnboarding({ id, total, run, autoStart, persist, storage, startDelay, onStart, onStepChange, onSkip, onFinish, onStop, }: UseOnboardingOptions): UseOnboardingReturn;

package/dist/utils/components/index.d.ts

@@ -34,3 +34,5 @@ export * from "./src/segmented-toggle/segmented-toggle";
 export * from "./src/skeleton/skeleton";
 export * from "./src/date-picker/date-picker";
 export * from "./src/time-picker/time-picker";
+export * from "./src/expandable-search/expandable-search";
+export * from "./src/onboarding/onboarding";

package/dist/utils/components/src/button/button.d.ts

@@ -1,5 +1,6 @@
 import "./button.css";
 import type { IconType, TooltipPosition } from "../../../types";
+import { Icon } from "../icon/icon";
 import React from "react";
 /**
  * Extends native `HTMLButtonElement` attributes
@@ -11,6 +12,7 @@ import React from "react";
  * @property {"left"|"right"} [iconPosition] - Icon position relative to the label. Default `"right"`.
  * @property {boolean} [iconOnly] - Icon without visible text.
  * @property {number} [iconStrokeWidth] - SVG stroke width for the icon. Default `1.5`.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [iconProps] - Extra props forwarded to the built-in `Icon` (and its `<svg>`); overrides defaults like `size`/`strokeWidth`.
  * @property {boolean} [isLoading] - Shows a spinner and disables the button. Default `false`.
  * @property {boolean} [fullWidth] - Stretches to 100% width of the container. Default `false`.
  * @property {string} [tooltip] - If set, wraps the button in a `Tooltip` with this text.
@@ -22,6 +24,7 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
     label?: string;
     iconStrokeWidth?: number;
     icon?: IconType;
+    iconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     iconPosition?: "left" | "right";
     iconOnly?: boolean;
     isLoading?: boolean;

package/dist/utils/components/src/chip/chip.d.ts

@@ -1,5 +1,6 @@
 import "./chip.css";
 import type React from "react";
+import { Icon } from "../icon/icon";
 import type { IconType, TooltipPosition } from "../../../types";
 /**
  * Props for the `Chip` component: extends `HTMLAttributes<HTMLElement>` with H2O badge fields.
@@ -7,6 +8,7 @@ import type { IconType, TooltipPosition } from "../../../types";
  *
  * @property {string} label - Visible text (required).
  * @property {import("../../../types").IconType} [icon] - Leading icon; overrides `dot` when present.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [iconProps] - Extra props forwarded to the built-in `Icon` (and its `<svg>`); overrides `iconSize`/`iconStrokeWidth`/`iconClassName`.
  * @property {"neutral"|"primary"|"success"|"warning"|"error"} [variant] - Color family. Default `"neutral"`.
  * @property {"sm"|"md"|"lg"} [size] - Padding and font. Default `"md"`.
  * @property {boolean} [dot] - Renders a status dot instead of an icon when no `icon`.
@@ -16,6 +18,7 @@ import type { IconType, TooltipPosition } from "../../../types";
 type ChipProps = React.HTMLAttributes<HTMLElement> & {
     label: string;
     icon?: IconType;
+    iconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     variant?: "neutral" | "primary" | "success" | "warning" | "error";
     size?: "sm" | "md" | "lg";
     iconStrokeWidth?: number;
@@ -33,5 +36,5 @@ type ChipProps = React.HTMLAttributes<HTMLElement> & {
  * @param {ChipProps} props - Extends native element props; includes `label` and presentation.
  * @returns {JSX.Element} A `span` or `button`-like chip per `onClick` usage.
  */
-export declare const Chip: ({ label, icon, variant, size, iconStrokeWidth, iconClassName, iconSize, disabled, showBorder, dot, tooltip, tooltipPosition, className, onClick, ...props }: ChipProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Chip: ({ label, icon, iconProps, variant, size, iconStrokeWidth, iconClassName, iconSize, disabled, showBorder, dot, tooltip, tooltipPosition, className, onClick, ...props }: ChipProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/utils/components/src/content-switch/content-switch.d.ts

@@ -1,14 +1,17 @@
 import "./content-switch.css";
+import { Icon } from "../icon/icon";
 import type { IconType } from "../../../types";
 /**
  * Tab-like option in a `ContentSwitch` row (`role="tablist"` / `role="tab"`).
  * @property {string} value - Passed to `onChange` when selected.
  * @property {IconType} [icon] - Optional leading icon on the tab.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [iconProps] - Extra props forwarded to the built-in `Icon` (and its `<svg>`).
  */
 export type ContentSwitchOption = {
     label: string;
     value: string;
     icon?: IconType;
+    iconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     disabled?: boolean;
 };
 /**

package/dist/utils/components/src/expandable-search/expandable-search.d.ts

@@ -0,0 +1,40 @@
+import "./expandable-search.css";
+/**
+ * Props for `ExpandableSearch`.
+ *
+ * @property {"sm"|"md"|"lg"} [size] - Trigger and expanded field height. Default `"md"`.
+ * @property {string} [value] - Controlled value. When provided, the parent owns state.
+ * @property {string} [defaultValue] - Initial value when uncontrolled. Default `""`.
+ * @property {boolean} [defaultExpanded] - Initial expanded state when uncontrolled. Default `false`.
+ * @property {string} [placeholder] - Input placeholder. Default `"Search..."`.
+ * @property {number} [expandedWidth] - Width of the input area in px when expanded. Default `200`.
+ * @property {(value: string) => void} [onChange] - Fires on each keystroke with the new value.
+ * @property {(expanded: boolean) => void} [onExpandedChange] - Fires when expanded state changes.
+ * @property {string} [className] - Extra class names on the wrapper.
+ * @property {string} [openAriaLabel] - Aria label for the trigger when collapsed. Default `"Open search"`.
+ * @property {string} [closeAriaLabel] - Aria label for the trigger when expanded. Default `"Close search"`.
+ */
+interface ExpandableSearchProps {
+    size?: "sm" | "md" | "lg";
+    value?: string;
+    defaultValue?: string;
+    defaultExpanded?: boolean;
+    placeholder?: string;
+    expandedWidth?: number;
+    onChange?: (value: string) => void;
+    onExpandedChange?: (expanded: boolean) => void;
+    className?: string;
+    openAriaLabel?: string;
+    closeAriaLabel?: string;
+}
+/**
+ * Icon-only search trigger that expands into an inline input on click.
+ *
+ * Collapses automatically when the user clicks outside while the input is empty.
+ * Toggling while expanded clears the value. Supports controlled or uncontrolled value.
+ *
+ * @param {ExpandableSearchProps} props - Controlled/uncontrolled value and presentation.
+ * @returns {JSX.Element} A pill-shaped wrapper containing the input and toggle button.
+ */
+export declare const ExpandableSearch: ({ size, value, defaultValue, defaultExpanded, placeholder, expandedWidth, onChange, onExpandedChange, className, openAriaLabel, closeAriaLabel, }: ExpandableSearchProps) => JSX.Element;
+export {};

package/dist/utils/components/src/input/input.d.ts

@@ -1,11 +1,14 @@
 import "./input.css";
 import type { IconType, TooltipPosition } from "../../../types";
+import { Icon } from "../icon/icon";
 /**
  * Extends `HTMLInputElement` attributes
  *
  * @property {"sm"|"md"|"lg"} [size] - Field height and font scale. Default `"md"`.
  * @property {import("../../../types").IconType} [leftIcon] - Optional left decorative/action icon.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [leftIconProps] - Extra props forwarded to the left `Icon` (and its `<svg>`).
  * @property {import("../../../types").IconType} [rightIcon] - Optional right icon; pair with `onRightIconClick` for an action.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [rightIconProps] - Extra props forwarded to the right `Icon` (and its `<svg>`).
  * @property {boolean} [showClear] - Shows a clear control when the field has a value. Default `false`.
  * @property {string} [note] - Helper text below the field (non-error).
  * @property {string} [error] - Error message; styles the field as invalid when set.
@@ -16,7 +19,9 @@ interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "
     size?: "sm" | "md" | "lg";
     label?: string;
     leftIcon?: IconType;
+    leftIconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     rightIcon?: IconType;
+    rightIconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     onRightIconClick?: () => void;
     showClear?: boolean;
     note?: string;

package/dist/utils/components/src/onboarding/onboarding.d.ts

@@ -0,0 +1,100 @@
+import "./onboarding.css";
+import type React from "react";
+import type { ReactNode } from "react";
+import { type OnboardingStorage, type UseOnboardingReturn } from "../../../hooks/src/use-onboarding";
+/** Where a step popup sits relative to its target. `"center"` ignores the target and centers on screen. */
+export type OnboardingPlacement = "top" | "bottom" | "left" | "right" | "auto" | "center";
+/**
+ * How a step finds its anchor element:
+ * - `string` — a CSS selector (e.g. `"#sidebar"`, `".profile"`, `"[data-tour=save]"`). A bare word falls back to an element id.
+ * - `HTMLElement` — the element directly.
+ * - `() => HTMLElement | null` — resolved lazily when the step shows.
+ */
+export type OnboardingTarget = string | HTMLElement | (() => HTMLElement | null);
+/**
+ * A single step in an onboarding flow.
+ *
+ * @property {OnboardingTarget} [target] - Element to anchor + spotlight. Omit for a centered step (welcome/finish screens).
+ * @property {ReactNode} [title] - Heading shown at the top of the popup.
+ * @property {ReactNode} content - Body message (required).
+ * @property {OnboardingPlacement} [placement] - Popup side. Default: the flow's `placement` (which defaults to `"auto"`).
+ * @property {number} [spotlightPadding] - Extra px around the target in the spotlight cutout.
+ * @property {number} [spotlightRadius] - Spotlight corner radius in px.
+ * @property {boolean} [disableInteraction] - Block clicks on the spotlighted element. Default: the flow's `disableInteraction`.
+ */
+export interface OnboardingStep {
+    target?: OnboardingTarget;
+    title?: ReactNode;
+    content: ReactNode;
+    placement?: OnboardingPlacement;
+    spotlightPadding?: number;
+    spotlightRadius?: number;
+    disableInteraction?: boolean;
+    showBack?: boolean;
+    showSkip?: boolean;
+    nextLabel?: string;
+    backLabel?: string;
+    finishLabel?: string;
+}
+/** Context passed to `renderStep` / `renderFooter` for fully custom popup UI. */
+export interface OnboardingRenderContext extends UseOnboardingReturn {
+    step: OnboardingStep;
+}
+/** Imperative handle exposed via `ref` on `Onboarding`. */
+export type OnboardingHandle = UseOnboardingReturn;
+/**
+ * Props for `Onboarding`. Most are flow-wide defaults that individual steps can override.
+ *
+ * @property {string} id - Stable flow id; persistence key.
+ * @property {OnboardingStep[]} steps - Ordered steps.
+ * @property {boolean} [run] - Controlled active state. Omit to auto-manage (see `autoStart`).
+ */
+export interface OnboardingProps {
+    id: string;
+    steps: OnboardingStep[];
+    run?: boolean;
+    autoStart?: boolean;
+    persist?: boolean;
+    storage?: OnboardingStorage;
+    startDelay?: number;
+    placement?: OnboardingPlacement;
+    spotlightPadding?: number;
+    spotlightRadius?: number;
+    disableInteraction?: boolean;
+    closeOnOverlayClick?: boolean;
+    closeOnEsc?: boolean;
+    keyboardNavigation?: boolean;
+    scrollIntoView?: boolean;
+    scrollBehavior?: ScrollBehavior;
+    offset?: number;
+    zIndex?: number;
+    showProgress?: boolean;
+    showSkip?: boolean;
+    showBack?: boolean;
+    showClose?: boolean;
+    nextLabel?: string;
+    backLabel?: string;
+    skipLabel?: string;
+    finishLabel?: string;
+    className?: string;
+    overlayClassName?: string;
+    onStart?: () => void;
+    onStepChange?: (index: number, previous: number, step: OnboardingStep) => void;
+    onSkip?: (index: number) => void;
+    onFinish?: () => void;
+    onClose?: () => void;
+    renderStep?: (ctx: OnboardingRenderContext) => ReactNode;
+    renderFooter?: (ctx: OnboardingRenderContext) => ReactNode;
+}
+/**
+ * Modular onboarding / product-tour overlay. Drive a flow by `id` with a `steps`
+ * array — each step spotlights an element (by selector/id) and shows a popup with
+ * Back / Skip / Next controls. Persists completion so a flow shows once.
+ *
+ * Headless control lives in {@link useOnboarding}; this component is the batteries-included UI.
+ *
+ * @param {OnboardingProps} props
+ * @param {React.Ref<OnboardingHandle>} ref - Imperative controls (`start`, `next`, `skip`, `reset`, …).
+ * @returns {JSX.Element | null} A portal with the spotlight overlay + popup while active.
+ */
+export declare const Onboarding: React.ForwardRefExoticComponent<OnboardingProps & React.RefAttributes<UseOnboardingReturn>>;

package/dist/utils/components/src/radio-group/radio-group.d.ts

@@ -1,16 +1,19 @@
 import "./radio-group.css";
+import { Icon } from "../icon/icon";
 import type { IconType, TooltipPosition } from "../../../types";
 /**
  * One entry in a `RadioGroup` `options` array.
  * @property {string} label - Option title.
  * @property {string} value - Emitted to `onChange` when selected.
  * @property {import("../../../types").IconType} [icon] - Optional leading icon.
+ * @property {Omit<React.ComponentProps<typeof Icon>, "icon">} [iconProps] - Extra props forwarded to the built-in `Icon` (and its `<svg>`).
  * @property {"active"|"inactive"} [dot] - Optional status dot style when no icon.
  */
 export interface RadioOption {
     label: string;
     value: string;
     icon?: IconType;
+    iconProps?: Omit<React.ComponentProps<typeof Icon>, "icon">;
     dot?: "active" | "inactive";
     disabled?: boolean;
     tooltip?: string;

package/dist/utils/hooks/index.d.ts

@@ -12,6 +12,7 @@ export * from "./src/use-key-press";
 export * from "./src/use-long-press";
 export * from "./src/use-media-query";
 export * from "./src/use-mouse";
+export * from "./src/use-onboarding";
 export * from "./src/use-timeout";
 export { useToast, ToastContext, type ToastContextType } from "./src/use-toast";
 export * from "./src/use-window-scroll";

package/dist/utils/hooks/src/use-onboarding.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Pluggable persistence adapter for onboarding flows. Swap to back completion
+ * with cookies, a backend, or anything else by implementing these two methods.
+ *
+ * @property {(id: string) => boolean} isCompleted - Whether the flow `id` was already finished/skipped.
+ * @property {(id: string, completed: boolean) => void} setCompleted - Persist (or clear) completion for `id`.
+ */
+export interface OnboardingStorage {
+    isCompleted: (id: string) => boolean;
+    setCompleted: (id: string, completed: boolean) => void;
+}
+export declare const localStorageOnboarding: OnboardingStorage;
+export declare const memoryOnboarding: OnboardingStorage;
+/**
+ * Options for {@link useOnboarding}.
+ *
+ * @property {string} id - Stable flow identifier; used as the persistence key.
+ * @property {number} total - Number of steps in the flow.
+ * @property {boolean} [run] - Controlled active state. Omit to let the hook manage start/stop internally.
+ * @property {boolean} [autoStart] - In uncontrolled mode, start on mount when the flow is not yet completed. Default `true`.
+ * @property {boolean} [persist] - Persist completion so a finished/skipped flow does not auto-restart. Default `true`.
+ * @property {OnboardingStorage} [storage] - Persistence adapter. Default `localStorageOnboarding`.
+ * @property {number} [startDelay] - Delay (ms) before auto-start, e.g. to let the page settle. Default `0`.
+ */
+export interface UseOnboardingOptions {
+    id: string;
+    total: number;
+    run?: boolean;
+    autoStart?: boolean;
+    persist?: boolean;
+    storage?: OnboardingStorage;
+    startDelay?: number;
+    onStart?: () => void;
+    onStepChange?: (index: number, previous: number) => void;
+    onSkip?: (index: number) => void;
+    onFinish?: () => void;
+    onStop?: () => void;
+}
+/** Imperative control surface + state returned by {@link useOnboarding}. */
+export interface UseOnboardingReturn {
+    active: boolean;
+    index: number;
+    total: number;
+    isFirst: boolean;
+    isLast: boolean;
+    completed: boolean;
+    start: () => void;
+    stop: () => void;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    skip: () => void;
+    finish: () => void;
+    reset: () => void;
+}
+/**
+ * Headless onboarding/tour state machine: drives a flow by `id`, tracks the
+ * current step, persists completion, and supports controlled or uncontrolled use.
+ *
+ * Pair with the `Onboarding` component for ready-made coachmarks, or render your
+ * own UI from the returned state for a fully custom flow.
+ *
+ * @param {UseOnboardingOptions} options
+ * @returns {UseOnboardingReturn} State (`active`, `index`, `isFirst`, …) and controls (`next`, `prev`, `skip`, `finish`, `reset`, …).
+ */
+export declare function useOnboarding({ id, total, run, autoStart, persist, storage, startDelay, onStart, onStepChange, onSkip, onFinish, onStop, }: UseOnboardingOptions): UseOnboardingReturn;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "h2o-library",
-  "version": "2.0.0",
-  "description": "A set of components for H2O App development",
+  "version": "2.1.0",
+  "description": "A set of components for H2O Apps development",
   "main": "dist/index.cjs.js",
   "module": "dist/esm/index.js",
   "types": "dist/index.d.ts",
@@ -103,5 +103,10 @@
     "clsx": "^2.1.1",
     "recharts": "^2.15.3",
     "tailwind-merge": "^3.0.2"
+  },
+  "overrides": {
+    "@storybook/addon-actions": {
+      "uuid": "^11.1.1"
+    }
   }
 }