@rio-cloud/rio-uikit 2.0.1 → 2.2.0

package/hooks/useLatest.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Keeps a mutable ref in sync with the latest value from the current render.
+ *
+ * Useful when an effect or callback must always access the newest value
+ * without adding that value to a dependency array and re-triggering logic.
+ *
+ * Common use cases:
+ * - Access latest callback props inside long-lived effects/listeners
+ * - Avoid stale closures in timers, subscriptions, and event handlers
+ *
+ * @typeParam TValue - The value type to keep up to date.
+ * @param value - Current value from render scope.
+ * @returns A ref whose `.current` always points to the latest value.
+ */
+declare const useLatest: <TValue>(value: TValue) => React.MutableRefObject<TValue>;
+export default useLatest;

package/hooks/useLatest.js

@@ -0,0 +1,11 @@
+import { useRef as r, useEffect as s } from "react";
+const o = (t) => {
+  const e = r(t);
+  return s(() => {
+    e.current = t;
+  }, [t]), e;
+};
+export {
+  o as default
+};
+//# sourceMappingURL=useLatest.js.map

package/hooks/useLatest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLatest.js","sources":["../../src/hooks/useLatest.ts"],"sourcesContent":["import { useEffect, useRef } from 'react';\n\n/**\n * Keeps a mutable ref in sync with the latest value from the current render.\n *\n * Useful when an effect or callback must always access the newest value\n * without adding that value to a dependency array and re-triggering logic.\n *\n * Common use cases:\n * - Access latest callback props inside long-lived effects/listeners\n * - Avoid stale closures in timers, subscriptions, and event handlers\n *\n * @typeParam TValue - The value type to keep up to date.\n * @param value - Current value from render scope.\n * @returns A ref whose `.current` always points to the latest value.\n */\nconst useLatest = <TValue>(value: TValue): React.MutableRefObject<TValue> => {\n    const ref = useRef(value);\n\n    useEffect(() => {\n        ref.current = value;\n    }, [value]);\n\n    return ref;\n};\n\nexport default useLatest;\n"],"names":["useLatest","value","ref","useRef","useEffect"],"mappings":";AAgBA,MAAMA,IAAY,CAASC,MAAkD;AACzE,QAAMC,IAAMC,EAAOF,CAAK;AAExB,SAAAG,EAAU,MAAM;AACZ,IAAAF,EAAI,UAAUD;AAAA,EAClB,GAAG,CAACA,CAAK,CAAC,GAEHC;AACX;"}

package/hooks/useOnboarding.d.ts

@@ -2,6 +2,83 @@ import { PopoverDOM as DriverPopoverDOM, State as DriverState, AllowedButtons, D
 export type PopoverDOM = DriverPopoverDOM;
 export type OnboardingState = DriverState;
 type DriverCallbackOptions = Parameters<DriverHook>[2];
+type OnboardingPopoverContent = {
+    /**
+     * Title text to be shown.
+     *
+     * You can use HTML here, but maybe you shouldn't.
+     */
+    title?: string;
+    /**
+     * Description text to be shown.
+     *
+     * You can use HTML here, but maybe you shouldn't.
+     */
+    description?: string;
+    /**
+     * The position of the popover relative to the target element.
+     *
+     * @default 'left'
+     */
+    side?: 'top' | 'right' | 'bottom' | 'left' | 'over';
+    /**
+     * Where the popover is anchored to the target element.
+     *
+     * @default 'start'
+     */
+    align?: 'start' | 'center' | 'end';
+    /**
+     * The buttons that should be shown in the popover - for this step only.
+     *
+     * When highlighting a single element (there is just a single step), there are no buttons by default. When
+     * showing a step of a multi-step tour, all buttons are shown by default.
+     *
+     * The "close" button is a simple "X" in the popover.
+     * The "previous" and "next" buttons are actual text buttons. can define the text contents of those buttons via
+     * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.
+     *
+     * This overrides the showButtons array on the {@link OnboardingOptions}.
+     */
+    showButtons?: AllowedButtons[];
+    /**
+     * The buttons that should be disabled in the popover - for this step only.
+     *
+     * This is useful when you want to show some of the buttons, but disable them anyway.
+     *
+     * This overrides the disableButtons array on the {@link OnboardingOptions}.
+     */
+    disableButtons?: AllowedButtons[];
+    /**
+     * Whether to disable interaction with the highlighted element.
+     *
+     * @default false
+     */
+    disableActiveInteraction?: boolean;
+    /**
+     * Custom class to add to the popover element.
+     *
+     * This can be used to style the popover.
+     */
+    popoverClass?: string;
+    /**
+     * Text to use for the "previous" button - specific for this step only.
+     *
+     * This overrides the prevBtnText on the {@link OnboardingOptions}.
+     */
+    prevBtnText?: string;
+    /**
+     * Text to use for the "next" button - specific for this step only.
+     *
+     * This overrides the nextBtnText on the {@link OnboardingOptions}.
+     */
+    nextBtnText?: string;
+    /**
+     * Text to use for the "done" (a.k.a. the final "next") button - specific for this step only.
+     *
+     * This overrides the doneBtnText on the {@link OnboardingOptions}.
+     */
+    doneBtnText?: string;
+};
 /**
  * Describes a single step in an Onboarding Tour.
  *
@@ -26,83 +103,7 @@ export type OnboardingStep = DriveStep & {
     /**
      * Defines the content and appearance of the popover.
      */
-    popover: {
-        /**
-         * Title text to be shown.
-         *
-         * You can use HTML here, but maybe you shouldn't.
-         */
-        title?: string;
-        /**
-         * Description text to be shown.
-         *
-         * You can use HTML here, but maybe you shouldn't.
-         */
-        description?: string;
-        /**
-         * The position of the popover relative to the target element.
-         *
-         * @default 'left'
-         */
-        side?: 'top' | 'right' | 'bottom' | 'left' | 'over';
-        /**
-         * Where the popover is anchored to the target element.
-         *
-         * @default 'start'
-         */
-        align?: 'start' | 'center' | 'end';
-        /**
-         * The buttons that should be shown in the popover - for this step only.
-         *
-         * When highlighting a single element (there is just a single step), there are no buttons by default. When
-         * showing a step of a multi-step tour, all buttons are shown by default.
-         *
-         * The "close" button is a simple "X" in the popover.
-         * The "previous" and "next" buttons are actual text buttons. can define the text contents of those buttons via
-         * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.
-         *
-         * This overrides the showButtons array on the {@link OnboardingOptions}.
-         */
-        showButtons?: AllowedButtons[];
-        /**
-         * The buttons that should be disabled in the popover - for this step only.
-         *
-         * This is useful when you want to show some of the buttons, but disable them anyway.
-         *
-         * This overrides the disableButtons array on the {@link OnboardingOptions}.
-         */
-        disableButtons?: AllowedButtons[];
-        /**
-         * Whether to disable interaction with the highlighted element.
-         *
-         * @default false
-         */
-        disableActiveInteraction?: boolean;
-        /**
-         * Custom class to add to the popover element.
-         *
-         * This can be used to style the popover.
-         */
-        popoverClass?: string;
-        /**
-         * Text to use for the "previous" button - specific for this step only.
-         *
-         * This overrides the prevBtnText on the {@link OnboardingOptions}.
-         */
-        prevBtnText?: string;
-        /**
-         * Text to use for the "next" button - specific for this step only.
-         *
-         * This overrides the nextBtnText on the {@link OnboardingOptions}.
-         */
-        nextBtnText?: string;
-        /**
-         * Text to use for the "done" (a.k.a. the final "next") button - specific for this step only.
-         *
-         * This overrides the doneBtnText on the {@link OnboardingOptions}.
-         */
-        doneBtnText?: string;
-    };
+    popover: OnboardingPopoverContent;
     /**
      * Callback triggered when the highlighting is about to become visible.
      *
@@ -136,14 +137,19 @@ type OnboardingOptions = {
      */
     steps?: OnboardingStep[];
     /**
-     * The buttons that should be shown in popovers.
+     * Array of buttons to show in the popover.
      *
      * When highlighting a single element (there is just a single step), there are no buttons by default. When showing
      * a step of a multi-step tour, all buttons are shown by default.
      *
-     * The "close" button is a simple "X" in the popover.
-     * The "previous" and "next" buttons are actual text buttons. can define the text contents of those buttons via
+     * The `close` button is a simple "X" in the popover.
+     *
+     * The `previous` and `next` buttons are actual text buttons. You can define the text contents of those buttons via
      * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.
+     *
+     * Defaults to ["next", "previous", "close"] for product tours and [] for single element highlighting.
+     *
+     * @default '["next", "previous", "close"]'
      */
     showButtons?: AllowedButtons[];
     /**

package/hooks/useOnboarding.js.map

@@ -1 +1 @@
-{"version":3,"file":"useOnboarding.js","sources":["../../src/hooks/useOnboarding.ts"],"sourcesContent":["import {\n    driver,\n    type PopoverDOM as DriverPopoverDOM,\n    type State as DriverState,\n    type AllowedButtons,\n    type DriveStep,\n    type DriverHook,\n} from 'driver.js';\nimport 'driver.js/dist/driver.css';\n\n// Features:\n// [x] - Close on click outside\n// [x] - Multiple steps with backdrop\n// [x] - drive vs. highlight\n// [x] - allow for controlling state (setStep, etc)\n// [-] - Single step to replace OnboardingTip (no buttons except close), no backdrop\n// [-] - Styling - as driver.js is using a singleton, setting styles for another onboarding step will override the global styles\n\nexport type PopoverDOM = DriverPopoverDOM;\nexport type OnboardingState = DriverState;\n\ntype DriverCallbackOptions = Parameters<DriverHook>[2];\n\n/**\n * Describes a single step in an Onboarding Tour.\n *\n * Is based on the underlying {@link DriveStep driver.js step configuration object}.\n *\n * @see https://driverjs.com/docs/configuration\n */\nexport type OnboardingStep = DriveStep & {\n    /**\n     * The target element to highlight.\n     *\n     * This can be a DOM element (ref), a function that returns a DOM element, or a CSS selector (most likely, you want\n     * to go with a selector as it's the easiest one to implement).\n     *\n     * If this is a selector, the first matching element will be highlighted.\n     *\n     * If no element is given, the popover will simply be centered on the screen.\n     *\n     * @example '[data-onboarding-walkthrough-step=\"2\"]'\n     */\n    element?: string | Element;\n\n    /**\n     * Defines the content and appearance of the popover.\n     */\n    popover: {\n        /**\n         * Title text to be shown.\n         *\n         * You can use HTML here, but maybe you shouldn't.\n         */\n        title?: string;\n\n        /**\n         * Description text to be shown.\n         *\n         * You can use HTML here, but maybe you shouldn't.\n         */\n        description?: string;\n\n        /**\n         * The position of the popover relative to the target element.\n         *\n         * @default 'left'\n         */\n        side?: 'top' | 'right' | 'bottom' | 'left' | 'over';\n\n        /**\n         * Where the popover is anchored to the target element.\n         *\n         * @default 'start'\n         */\n        align?: 'start' | 'center' | 'end';\n\n        /**\n         * The buttons that should be shown in the popover - for this step only.\n         *\n         * When highlighting a single element (there is just a single step), there are no buttons by default. When\n         * showing a step of a multi-step tour, all buttons are shown by default.\n         *\n         * The \"close\" button is a simple \"X\" in the popover.\n         * The \"previous\" and \"next\" buttons are actual text buttons. can define the text contents of those buttons via\n         * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.\n         *\n         * This overrides the showButtons array on the {@link OnboardingOptions}.\n         */\n        showButtons?: AllowedButtons[];\n\n        /**\n         * The buttons that should be disabled in the popover - for this step only.\n         *\n         * This is useful when you want to show some of the buttons, but disable them anyway.\n         *\n         * This overrides the disableButtons array on the {@link OnboardingOptions}.\n         */\n        disableButtons?: AllowedButtons[];\n\n        /**\n         * Whether to disable interaction with the highlighted element.\n         *\n         * @default false\n         */\n        disableActiveInteraction?: boolean;\n\n        /**\n         * Custom class to add to the popover element.\n         *\n         * This can be used to style the popover.\n         */\n        popoverClass?: string;\n\n        /**\n         * Text to use for the \"previous\" button - specific for this step only.\n         *\n         * This overrides the prevBtnText on the {@link OnboardingOptions}.\n         */\n        prevBtnText?: string;\n\n        /**\n         * Text to use for the \"next\" button - specific for this step only.\n         *\n         * This overrides the nextBtnText on the {@link OnboardingOptions}.\n         */\n        nextBtnText?: string;\n\n        /**\n         * Text to use for the \"done\" (a.k.a. the final \"next\") button - specific for this step only.\n         *\n         * This overrides the doneBtnText on the {@link OnboardingOptions}.\n         */\n        doneBtnText?: string;\n    };\n\n    /**\n     * Callback triggered when the highlighting is about to become visible.\n     *\n     * @param element The target DOM element of the step.\n     * @param step The {@link DriveStep driver.js step object} configured for the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onHighlightStarted?: (element: Element | undefined, step: OnboardingStep, opts: DriverCallbackOptions) => void;\n\n    /**\n     * Callback triggered when the highlight is visible.\n     *\n     * @param element The target DOM element of the step.\n     * @param step The {@link DriveStep driver.js step object} configured for the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onHighlighted?: (element: Element | undefined, step: OnboardingStep, opts: DriverCallbackOptions) => void;\n\n    /**\n     * Callback triggered when the highlight is about to become invisible.\n     *\n     * @param element The target DOM element of the step.\n     * @param step The {@link DriveStep driver.js step object} configured for the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onDeselected?: (element: Element | undefined, step: OnboardingStep, opts: DriverCallbackOptions) => void;\n};\n\ntype OnboardingOptions = {\n    /**\n     * Array of steps to highlight.\n     *\n     * You should pass this when you want to set up a tour.\n     */\n    steps?: OnboardingStep[];\n\n    /**\n     * The buttons that should be shown in popovers.\n     *\n     * When highlighting a single element (there is just a single step), there are no buttons by default. When showing\n     * a step of a multi-step tour, all buttons are shown by default.\n     *\n     * The \"close\" button is a simple \"X\" in the popover.\n     * The \"previous\" and \"next\" buttons are actual text buttons. can define the text contents of those buttons via\n     * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.\n     */\n    showButtons?: AllowedButtons[];\n\n    /**\n     * The buttons that should be disabled in popovers.\n     *\n     * This is useful when you want to show some of the buttons, but disable them anyway.\n     */\n    disableButtons?: AllowedButtons[];\n\n    /**\n     * Text to use for the \"previous\" button.\n     *\n     * @default 'Previous'\n     */\n    prevBtnText?: string;\n\n    /**\n     * Text to use for the \"next\" button.\n     *\n     * @default 'Next'\n     */\n    nextBtnText?: string;\n\n    /**\n     * Text to use for the \"done\" (a.k.a. the final \"next\") button.\n     *\n     * When given, this overrides the {@link nextBtnText} in the final popover of a tour.\n     *\n     * @default 'Done'\n     */\n    doneBtnText?: string;\n\n    /**\n     * Indicates whether to show progress in the onboarding popover.\n     *\n     * @default true\n     */\n    showProgress?: boolean;\n\n    /**\n     * Whether to allow closing the popover by clicking on the backdrop.\n     *\n     * This should be disabled during a tour to ensure the user completes the tour, but can be enabled on the last step.\n     *\n     * @default false\n     */\n    allowClose?: boolean;\n\n    /**\n     * Distance between the highlighted element and the cutout.\n     *\n     * @default 10\n     */\n    stagePadding?: number;\n\n    /**\n     * Radius of the cutout around the highlighted element.\n     *\n     * @default 5\n     */\n    stageRadius?: number;\n\n    /**\n     * Whether to allow keyboard navigation.\n     *\n     * @default true\n     */\n    allowKeyboardControl?: boolean;\n\n    /**\n     * Whether to disable interaction with the highlighted element.\n     * Can be configured at the step level as well.\n     *\n     * @default false\n     */\n    disableActiveInteraction?: boolean;\n\n    /**\n     * Option to disable the backdrop. Note, the backdrop element is still there but with 100% opacity\n     * and the close on the backdrop is disabled.\n     *\n     * @default false\n     */\n    noBackdrop?: boolean;\n\n    /**\n     * Additional classes set on the popover itself.\n     */\n    popoverClass?: string;\n\n    /**\n     * Callback triggered when an onboarding popover renders.\n     *\n     * @param element The target DOM element of the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onPopoverRender?: (popover: PopoverDOM, opts: OnboardingState) => void;\n\n    /**\n     * Callback triggered when the onboarding tour is destroyed.\n     */\n    onDestroyed?: () => void;\n};\n\nexport const useOnboardingTour = (params: OnboardingOptions) => {\n    const {\n        steps,\n        prevBtnText = 'Previous',\n        nextBtnText = 'Next',\n        doneBtnText = 'Done',\n        showProgress = true,\n        allowClose = false,\n        stagePadding = 10,\n        stageRadius = 5,\n        allowKeyboardControl = true,\n        showButtons,\n        disableButtons,\n        popoverClass,\n        noBackdrop = false,\n        onPopoverRender = () => {},\n        onDestroyed = () => {},\n        ...driverProps\n    } = params;\n\n    const handlePopoverRender = (popover: DriverPopoverDOM, options: DriverCallbackOptions) => {\n        onPopoverRender(popover, options.state);\n    };\n\n    const handleDestroyed = () => {\n        onDestroyed();\n    };\n\n    const isSingleStep = !steps || steps.length === 1;\n\n    // This configuration is applied to all steps.\n    // Driver.js allows also for individual customization for single steps too.\n    const driverInstance = driver({\n        steps,\n        prevBtnText,\n        nextBtnText,\n        doneBtnText,\n        showProgress: isSingleStep ? false : showProgress,\n        showButtons: isSingleStep ? (['close'] as AllowedButtons[]) : showButtons,\n        allowClose,\n        overlayOpacity: noBackdrop ? 0 : 0.5,\n        disableButtons,\n        progressText: '{{current}} / {{total}}',\n        overlayColor: 'var(--color-black)',\n        stagePadding,\n        stageRadius,\n        allowKeyboardControl,\n        popoverClass,\n        onPopoverRender: handlePopoverRender,\n        onDestroyed: handleDestroyed,\n        ...driverProps,\n    });\n\n    return {\n        // Use for onboarding tours. Pass in all steps as \"steps\" parameter for initial configuration.\n        run: () => driverInstance.drive(),\n\n        // Use for single element highlights -> see useOnboardingTip\n        // highlight: (step: OnboardingStep) => driverInstance.highlight(step),\n\n        // Cleanup the onboarding\n        destroy: () => driverInstance.destroy(),\n\n        // Gets the current state of the onboarding with the current step\n        onboardingState: () => driverInstance.getState(),\n\n        // Recalculate and redraw the highlight\n        refresh: () => driverInstance.refresh(),\n\n        // Is the tour or highlight currently active\n        isActive: () => driverInstance.isActive(),\n\n        // Move to the next step\n        moveNext: () => driverInstance.moveNext(),\n\n        // Move to the previous step\n        movePrevious: () => driverInstance.movePrevious(),\n\n        // Move to the step 4\n        moveTo: (stepNumber: number) => driverInstance.moveTo(stepNumber),\n\n        // Is there a next step\n        hasNextStep: () => driverInstance.hasNextStep(),\n\n        // Is there a previous step\n        hasPreviousStep: () => driverInstance.hasPreviousStep(),\n\n        // Is the current step the first step\n        isFirstStep: () => driverInstance.isFirstStep(),\n\n        // Is the current step the last step\n        isLastStep: () => driverInstance.isLastStep(),\n\n        // Gets the active step index\n        getActiveIndex: () => driverInstance.getActiveIndex(),\n    };\n};\n\ntype OnboardingTipOptions = {\n    allowClose?: boolean;\n    stagePadding?: number;\n    stageRadius?: number;\n    noBackdrop?: boolean;\n};\n\n/**\n * Note: please use the {@link import('../components/onboarding/OnboardingTip')#default OnboardingTip} instead of this\n * hook!\n *\n * This is kept only for future development of driver.js with the hope to solve the global driver styling issue and to\n * eventually replace the OnboardingTooltip also with driver.js.\n *\n * @experimental\n */\nexport const useOnboardingTip = (options?: OnboardingTipOptions) => {\n    const { allowClose = true, stagePadding = 0, stageRadius = 5, noBackdrop = true } = options || {};\n\n    const driverInstance = driver({\n        allowClose,\n        stagePadding,\n        stageRadius,\n        overlayOpacity: noBackdrop ? 0 : 0.5,\n        overlayColor: undefined,\n    });\n\n    return {\n        highlight: (step: OnboardingStep) => driverInstance.highlight(step),\n        destroy: () => driverInstance.destroy(),\n        refresh: () => driverInstance.refresh(),\n        isActive: () => driverInstance.isActive(),\n    };\n};\n"],"names":["useOnboardingTour","params","steps","prevBtnText","nextBtnText","doneBtnText","showProgress","allowClose","stagePadding","stageRadius","allowKeyboardControl","showButtons","disableButtons","popoverClass","noBackdrop","onPopoverRender","onDestroyed","driverProps","handlePopoverRender","popover","options","handleDestroyed","isSingleStep","driverInstance","driver","stepNumber","useOnboardingTip","step"],"mappings":";;AA8RO,MAAMA,IAAoB,CAACC,MAA8B;AAC5D,QAAM;AAAA,IACF,OAAAC;AAAA,IACA,aAAAC,IAAc;AAAA,IACd,aAAAC,IAAc;AAAA,IACd,aAAAC,IAAc;AAAA,IACd,cAAAC,IAAe;AAAA,IACf,YAAAC,IAAa;AAAA,IACb,cAAAC,IAAe;AAAA,IACf,aAAAC,IAAc;AAAA,IACd,sBAAAC,IAAuB;AAAA,IACvB,aAAAC;AAAA,IACA,gBAAAC;AAAA,IACA,cAAAC;AAAA,IACA,YAAAC,IAAa;AAAA,IACb,iBAAAC,IAAkB,MAAM;AAAA,IAAC;AAAA,IACzB,aAAAC,IAAc,MAAM;AAAA,IAAC;AAAA,IACrB,GAAGC;AAAA,EAAA,IACHhB,GAEEiB,IAAsB,CAACC,GAA2BC,MAAmC;AACvF,IAAAL,EAAgBI,GAASC,EAAQ,KAAK;AAAA,EAC1C,GAEMC,IAAkB,MAAM;AAC1B,IAAAL,EAAA;AAAA,EACJ,GAEMM,IAAe,CAACpB,KAASA,EAAM,WAAW,GAI1CqB,IAAiBC,EAAO;AAAA,IAC1B,OAAAtB;AAAA,IACA,aAAAC;AAAA,IACA,aAAAC;AAAA,IACA,aAAAC;AAAA,IACA,cAAciB,IAAe,KAAQhB;AAAA,IACrC,aAAagB,IAAgB,CAAC,OAAO,IAAyBX;AAAA,IAC9D,YAAAJ;AAAA,IACA,gBAAgBO,IAAa,IAAI;AAAA,IACjC,gBAAAF;AAAA,IACA,cAAc;AAAA,IACd,cAAc;AAAA,IACd,cAAAJ;AAAA,IACA,aAAAC;AAAA,IACA,sBAAAC;AAAA,IACA,cAAAG;AAAA,IACA,iBAAiBK;AAAA,IACjB,aAAaG;AAAA,IACb,GAAGJ;AAAA,EAAA,CACN;AAED,SAAO;AAAA;AAAA,IAEH,KAAK,MAAMM,EAAe,MAAA;AAAA;AAAA;AAAA;AAAA,IAM1B,SAAS,MAAMA,EAAe,QAAA;AAAA;AAAA,IAG9B,iBAAiB,MAAMA,EAAe,SAAA;AAAA;AAAA,IAGtC,SAAS,MAAMA,EAAe,QAAA;AAAA;AAAA,IAG9B,UAAU,MAAMA,EAAe,SAAA;AAAA;AAAA,IAG/B,UAAU,MAAMA,EAAe,SAAA;AAAA;AAAA,IAG/B,cAAc,MAAMA,EAAe,aAAA;AAAA;AAAA,IAGnC,QAAQ,CAACE,MAAuBF,EAAe,OAAOE,CAAU;AAAA;AAAA,IAGhE,aAAa,MAAMF,EAAe,YAAA;AAAA;AAAA,IAGlC,iBAAiB,MAAMA,EAAe,gBAAA;AAAA;AAAA,IAGtC,aAAa,MAAMA,EAAe,YAAA;AAAA;AAAA,IAGlC,YAAY,MAAMA,EAAe,WAAA;AAAA;AAAA,IAGjC,gBAAgB,MAAMA,EAAe,eAAA;AAAA,EAAe;AAE5D,GAkBaG,IAAmB,CAACN,MAAmC;AAChE,QAAM,EAAE,YAAAb,IAAa,IAAM,cAAAC,IAAe,GAAG,aAAAC,IAAc,GAAG,YAAAK,IAAa,GAAA,IAASM,KAAW,CAAA,GAEzFG,IAAiBC,EAAO;AAAA,IAC1B,YAAAjB;AAAA,IACA,cAAAC;AAAA,IACA,aAAAC;AAAA,IACA,gBAAgBK,IAAa,IAAI;AAAA,IACjC,cAAc;AAAA,EAAA,CACjB;AAED,SAAO;AAAA,IACH,WAAW,CAACa,MAAyBJ,EAAe,UAAUI,CAAI;AAAA,IAClE,SAAS,MAAMJ,EAAe,QAAA;AAAA,IAC9B,SAAS,MAAMA,EAAe,QAAA;AAAA,IAC9B,UAAU,MAAMA,EAAe,SAAA;AAAA,EAAS;AAEhD;"}
+{"version":3,"file":"useOnboarding.js","sources":["../../src/hooks/useOnboarding.ts"],"sourcesContent":["import {\n    driver,\n    type PopoverDOM as DriverPopoverDOM,\n    type State as DriverState,\n    type AllowedButtons,\n    type DriveStep,\n    type DriverHook,\n} from 'driver.js';\nimport 'driver.js/dist/driver.css';\n\n// Features:\n// [x] - Close on click outside\n// [x] - Multiple steps with backdrop\n// [x] - drive vs. highlight\n// [x] - allow for controlling state (setStep, etc)\n// [-] - Single step to replace OnboardingTip (no buttons except close), no backdrop\n// [-] - Styling - as driver.js is using a singleton, setting styles for another onboarding step will override the global styles\n\nexport type PopoverDOM = DriverPopoverDOM;\nexport type OnboardingState = DriverState;\n\ntype DriverCallbackOptions = Parameters<DriverHook>[2];\n\ntype OnboardingPopoverContent = {\n    /**\n     * Title text to be shown.\n     *\n     * You can use HTML here, but maybe you shouldn't.\n     */\n    title?: string;\n\n    /**\n     * Description text to be shown.\n     *\n     * You can use HTML here, but maybe you shouldn't.\n     */\n    description?: string;\n\n    /**\n     * The position of the popover relative to the target element.\n     *\n     * @default 'left'\n     */\n    side?: 'top' | 'right' | 'bottom' | 'left' | 'over';\n\n    /**\n     * Where the popover is anchored to the target element.\n     *\n     * @default 'start'\n     */\n    align?: 'start' | 'center' | 'end';\n\n    /**\n     * The buttons that should be shown in the popover - for this step only.\n     *\n     * When highlighting a single element (there is just a single step), there are no buttons by default. When\n     * showing a step of a multi-step tour, all buttons are shown by default.\n     *\n     * The \"close\" button is a simple \"X\" in the popover.\n     * The \"previous\" and \"next\" buttons are actual text buttons. can define the text contents of those buttons via\n     * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.\n     *\n     * This overrides the showButtons array on the {@link OnboardingOptions}.\n     */\n    showButtons?: AllowedButtons[];\n\n    /**\n     * The buttons that should be disabled in the popover - for this step only.\n     *\n     * This is useful when you want to show some of the buttons, but disable them anyway.\n     *\n     * This overrides the disableButtons array on the {@link OnboardingOptions}.\n     */\n    disableButtons?: AllowedButtons[];\n\n    /**\n     * Whether to disable interaction with the highlighted element.\n     *\n     * @default false\n     */\n    disableActiveInteraction?: boolean;\n\n    /**\n     * Custom class to add to the popover element.\n     *\n     * This can be used to style the popover.\n     */\n    popoverClass?: string;\n\n    /**\n     * Text to use for the \"previous\" button - specific for this step only.\n     *\n     * This overrides the prevBtnText on the {@link OnboardingOptions}.\n     */\n    prevBtnText?: string;\n\n    /**\n     * Text to use for the \"next\" button - specific for this step only.\n     *\n     * This overrides the nextBtnText on the {@link OnboardingOptions}.\n     */\n    nextBtnText?: string;\n\n    /**\n     * Text to use for the \"done\" (a.k.a. the final \"next\") button - specific for this step only.\n     *\n     * This overrides the doneBtnText on the {@link OnboardingOptions}.\n     */\n    doneBtnText?: string;\n};\n\n/**\n * Describes a single step in an Onboarding Tour.\n *\n * Is based on the underlying {@link DriveStep driver.js step configuration object}.\n *\n * @see https://driverjs.com/docs/configuration\n */\nexport type OnboardingStep = DriveStep & {\n    /**\n     * The target element to highlight.\n     *\n     * This can be a DOM element (ref), a function that returns a DOM element, or a CSS selector (most likely, you want\n     * to go with a selector as it's the easiest one to implement).\n     *\n     * If this is a selector, the first matching element will be highlighted.\n     *\n     * If no element is given, the popover will simply be centered on the screen.\n     *\n     * @example '[data-onboarding-walkthrough-step=\"2\"]'\n     */\n    element?: string | Element;\n\n    /**\n     * Defines the content and appearance of the popover.\n     */\n    popover: OnboardingPopoverContent;\n\n    /**\n     * Callback triggered when the highlighting is about to become visible.\n     *\n     * @param element The target DOM element of the step.\n     * @param step The {@link DriveStep driver.js step object} configured for the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onHighlightStarted?: (element: Element | undefined, step: OnboardingStep, opts: DriverCallbackOptions) => void;\n\n    /**\n     * Callback triggered when the highlight is visible.\n     *\n     * @param element The target DOM element of the step.\n     * @param step The {@link DriveStep driver.js step object} configured for the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onHighlighted?: (element: Element | undefined, step: OnboardingStep, opts: DriverCallbackOptions) => void;\n\n    /**\n     * Callback triggered when the highlight is about to become invisible.\n     *\n     * @param element The target DOM element of the step.\n     * @param step The {@link DriveStep driver.js step object} configured for the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onDeselected?: (element: Element | undefined, step: OnboardingStep, opts: DriverCallbackOptions) => void;\n};\n\ntype OnboardingOptions = {\n    /**\n     * Array of steps to highlight.\n     *\n     * You should pass this when you want to set up a tour.\n     */\n    steps?: OnboardingStep[];\n\n    /**\n     * Array of buttons to show in the popover.\n     *\n     * When highlighting a single element (there is just a single step), there are no buttons by default. When showing\n     * a step of a multi-step tour, all buttons are shown by default.\n     *\n     * The `close` button is a simple \"X\" in the popover.\n     *\n     * The `previous` and `next` buttons are actual text buttons. You can define the text contents of those buttons via\n     * the {@link prevBtnText}, {@link nextBtnText} and {@link doneBtnText} properties.\n     *\n     * Defaults to [\"next\", \"previous\", \"close\"] for product tours and [] for single element highlighting.\n     *\n     * @default '[\"next\", \"previous\", \"close\"]'\n     */\n    showButtons?: AllowedButtons[];\n\n    /**\n     * The buttons that should be disabled in popovers.\n     *\n     * This is useful when you want to show some of the buttons, but disable them anyway.\n     */\n    disableButtons?: AllowedButtons[];\n\n    /**\n     * Text to use for the \"previous\" button.\n     *\n     * @default 'Previous'\n     */\n    prevBtnText?: string;\n\n    /**\n     * Text to use for the \"next\" button.\n     *\n     * @default 'Next'\n     */\n    nextBtnText?: string;\n\n    /**\n     * Text to use for the \"done\" (a.k.a. the final \"next\") button.\n     *\n     * When given, this overrides the {@link nextBtnText} in the final popover of a tour.\n     *\n     * @default 'Done'\n     */\n    doneBtnText?: string;\n\n    /**\n     * Indicates whether to show progress in the onboarding popover.\n     *\n     * @default true\n     */\n    showProgress?: boolean;\n\n    /**\n     * Whether to allow closing the popover by clicking on the backdrop.\n     *\n     * This should be disabled during a tour to ensure the user completes the tour, but can be enabled on the last step.\n     *\n     * @default false\n     */\n    allowClose?: boolean;\n\n    /**\n     * Distance between the highlighted element and the cutout.\n     *\n     * @default 10\n     */\n    stagePadding?: number;\n\n    /**\n     * Radius of the cutout around the highlighted element.\n     *\n     * @default 5\n     */\n    stageRadius?: number;\n\n    /**\n     * Whether to allow keyboard navigation.\n     *\n     * @default true\n     */\n    allowKeyboardControl?: boolean;\n\n    /**\n     * Whether to disable interaction with the highlighted element.\n     * Can be configured at the step level as well.\n     *\n     * @default false\n     */\n    disableActiveInteraction?: boolean;\n\n    /**\n     * Option to disable the backdrop. Note, the backdrop element is still there but with 100% opacity\n     * and the close on the backdrop is disabled.\n     *\n     * @default false\n     */\n    noBackdrop?: boolean;\n\n    /**\n     * Additional classes set on the popover itself.\n     */\n    popoverClass?: string;\n\n    /**\n     * Callback triggered when an onboarding popover renders.\n     *\n     * @param element The target DOM element of the step.\n     * @param opts The configuration options and current state of the driver object as well as the driver object itself.\n     */\n    onPopoverRender?: (popover: PopoverDOM, opts: OnboardingState) => void;\n\n    /**\n     * Callback triggered when the onboarding tour is destroyed.\n     */\n    onDestroyed?: () => void;\n};\n\nexport const useOnboardingTour = (params: OnboardingOptions) => {\n    const {\n        steps,\n        prevBtnText = 'Previous',\n        nextBtnText = 'Next',\n        doneBtnText = 'Done',\n        showProgress = true,\n        allowClose = false,\n        stagePadding = 10,\n        stageRadius = 5,\n        allowKeyboardControl = true,\n        showButtons,\n        disableButtons,\n        popoverClass,\n        noBackdrop = false,\n        onPopoverRender = () => {},\n        onDestroyed = () => {},\n        ...driverProps\n    } = params;\n\n    const handlePopoverRender = (popover: DriverPopoverDOM, options: DriverCallbackOptions) => {\n        onPopoverRender(popover, options.state);\n    };\n\n    const handleDestroyed = () => {\n        onDestroyed();\n    };\n\n    const isSingleStep = !steps || steps.length === 1;\n\n    // This configuration is applied to all steps.\n    // Driver.js allows also for individual customization for single steps too.\n    const driverInstance = driver({\n        steps,\n        prevBtnText,\n        nextBtnText,\n        doneBtnText,\n        showProgress: isSingleStep ? false : showProgress,\n        showButtons: isSingleStep ? (['close'] as AllowedButtons[]) : showButtons,\n        allowClose,\n        overlayOpacity: noBackdrop ? 0 : 0.5,\n        disableButtons,\n        progressText: '{{current}} / {{total}}',\n        overlayColor: 'var(--color-black)',\n        stagePadding,\n        stageRadius,\n        allowKeyboardControl,\n        popoverClass,\n        onPopoverRender: handlePopoverRender,\n        onDestroyed: handleDestroyed,\n        ...driverProps,\n    });\n\n    return {\n        // Use for onboarding tours. Pass in all steps as \"steps\" parameter for initial configuration.\n        run: () => driverInstance.drive(),\n\n        // Use for single element highlights -> see useOnboardingTip\n        // highlight: (step: OnboardingStep) => driverInstance.highlight(step),\n\n        // Cleanup the onboarding\n        destroy: () => driverInstance.destroy(),\n\n        // Gets the current state of the onboarding with the current step\n        onboardingState: () => driverInstance.getState(),\n\n        // Recalculate and redraw the highlight\n        refresh: () => driverInstance.refresh(),\n\n        // Is the tour or highlight currently active\n        isActive: () => driverInstance.isActive(),\n\n        // Move to the next step\n        moveNext: () => driverInstance.moveNext(),\n\n        // Move to the previous step\n        movePrevious: () => driverInstance.movePrevious(),\n\n        // Move to the step 4\n        moveTo: (stepNumber: number) => driverInstance.moveTo(stepNumber),\n\n        // Is there a next step\n        hasNextStep: () => driverInstance.hasNextStep(),\n\n        // Is there a previous step\n        hasPreviousStep: () => driverInstance.hasPreviousStep(),\n\n        // Is the current step the first step\n        isFirstStep: () => driverInstance.isFirstStep(),\n\n        // Is the current step the last step\n        isLastStep: () => driverInstance.isLastStep(),\n\n        // Gets the active step index\n        getActiveIndex: () => driverInstance.getActiveIndex(),\n    };\n};\n\ntype OnboardingTipOptions = {\n    allowClose?: boolean;\n    stagePadding?: number;\n    stageRadius?: number;\n    noBackdrop?: boolean;\n};\n\n/**\n * Note: please use the {@link import('../components/onboarding/OnboardingTip')#default OnboardingTip} instead of this\n * hook!\n *\n * This is kept only for future development of driver.js with the hope to solve the global driver styling issue and to\n * eventually replace the OnboardingTooltip also with driver.js.\n *\n * @experimental\n */\nexport const useOnboardingTip = (options?: OnboardingTipOptions) => {\n    const { allowClose = true, stagePadding = 0, stageRadius = 5, noBackdrop = true } = options || {};\n\n    const driverInstance = driver({\n        allowClose,\n        stagePadding,\n        stageRadius,\n        overlayOpacity: noBackdrop ? 0 : 0.5,\n        overlayColor: undefined,\n    });\n\n    return {\n        highlight: (step: OnboardingStep) => driverInstance.highlight(step),\n        destroy: () => driverInstance.destroy(),\n        refresh: () => driverInstance.refresh(),\n        isActive: () => driverInstance.isActive(),\n    };\n};\n"],"names":["useOnboardingTour","params","steps","prevBtnText","nextBtnText","doneBtnText","showProgress","allowClose","stagePadding","stageRadius","allowKeyboardControl","showButtons","disableButtons","popoverClass","noBackdrop","onPopoverRender","onDestroyed","driverProps","handlePopoverRender","popover","options","handleDestroyed","isSingleStep","driverInstance","driver","stepNumber","useOnboardingTip","step"],"mappings":";;AAqSO,MAAMA,IAAoB,CAACC,MAA8B;AAC5D,QAAM;AAAA,IACF,OAAAC;AAAA,IACA,aAAAC,IAAc;AAAA,IACd,aAAAC,IAAc;AAAA,IACd,aAAAC,IAAc;AAAA,IACd,cAAAC,IAAe;AAAA,IACf,YAAAC,IAAa;AAAA,IACb,cAAAC,IAAe;AAAA,IACf,aAAAC,IAAc;AAAA,IACd,sBAAAC,IAAuB;AAAA,IACvB,aAAAC;AAAA,IACA,gBAAAC;AAAA,IACA,cAAAC;AAAA,IACA,YAAAC,IAAa;AAAA,IACb,iBAAAC,IAAkB,MAAM;AAAA,IAAC;AAAA,IACzB,aAAAC,IAAc,MAAM;AAAA,IAAC;AAAA,IACrB,GAAGC;AAAA,EAAA,IACHhB,GAEEiB,IAAsB,CAACC,GAA2BC,MAAmC;AACvF,IAAAL,EAAgBI,GAASC,EAAQ,KAAK;AAAA,EAC1C,GAEMC,IAAkB,MAAM;AAC1B,IAAAL,EAAA;AAAA,EACJ,GAEMM,IAAe,CAACpB,KAASA,EAAM,WAAW,GAI1CqB,IAAiBC,EAAO;AAAA,IAC1B,OAAAtB;AAAA,IACA,aAAAC;AAAA,IACA,aAAAC;AAAA,IACA,aAAAC;AAAA,IACA,cAAciB,IAAe,KAAQhB;AAAA,IACrC,aAAagB,IAAgB,CAAC,OAAO,IAAyBX;AAAA,IAC9D,YAAAJ;AAAA,IACA,gBAAgBO,IAAa,IAAI;AAAA,IACjC,gBAAAF;AAAA,IACA,cAAc;AAAA,IACd,cAAc;AAAA,IACd,cAAAJ;AAAA,IACA,aAAAC;AAAA,IACA,sBAAAC;AAAA,IACA,cAAAG;AAAA,IACA,iBAAiBK;AAAA,IACjB,aAAaG;AAAA,IACb,GAAGJ;AAAA,EAAA,CACN;AAED,SAAO;AAAA;AAAA,IAEH,KAAK,MAAMM,EAAe,MAAA;AAAA;AAAA;AAAA;AAAA,IAM1B,SAAS,MAAMA,EAAe,QAAA;AAAA;AAAA,IAG9B,iBAAiB,MAAMA,EAAe,SAAA;AAAA;AAAA,IAGtC,SAAS,MAAMA,EAAe,QAAA;AAAA;AAAA,IAG9B,UAAU,MAAMA,EAAe,SAAA;AAAA;AAAA,IAG/B,UAAU,MAAMA,EAAe,SAAA;AAAA;AAAA,IAG/B,cAAc,MAAMA,EAAe,aAAA;AAAA;AAAA,IAGnC,QAAQ,CAACE,MAAuBF,EAAe,OAAOE,CAAU;AAAA;AAAA,IAGhE,aAAa,MAAMF,EAAe,YAAA;AAAA;AAAA,IAGlC,iBAAiB,MAAMA,EAAe,gBAAA;AAAA;AAAA,IAGtC,aAAa,MAAMA,EAAe,YAAA;AAAA;AAAA,IAGlC,YAAY,MAAMA,EAAe,WAAA;AAAA;AAAA,IAGjC,gBAAgB,MAAMA,EAAe,eAAA;AAAA,EAAe;AAE5D,GAkBaG,IAAmB,CAACN,MAAmC;AAChE,QAAM,EAAE,YAAAb,IAAa,IAAM,cAAAC,IAAe,GAAG,aAAAC,IAAc,GAAG,YAAAK,IAAa,GAAA,IAASM,KAAW,CAAA,GAEzFG,IAAiBC,EAAO;AAAA,IAC1B,YAAAjB;AAAA,IACA,cAAAC;AAAA,IACA,aAAAC;AAAA,IACA,gBAAgBK,IAAa,IAAI;AAAA,IACjC,cAAc;AAAA,EAAA,CACjB;AAED,SAAO;AAAA,IACH,WAAW,CAACa,MAAyBJ,EAAe,UAAUI,CAAI;AAAA,IAClE,SAAS,MAAMJ,EAAe,QAAA;AAAA,IAC9B,SAAS,MAAMA,EAAe,QAAA;AAAA,IAC9B,UAAU,MAAMA,EAAe,SAAA;AAAA,EAAS;AAEhD;"}

package/hooks/usePostMessage.d.ts

@@ -23,7 +23,8 @@ export type RemoteAction = {
  *
  * @param messagePrefix a custom prefix to limit the event listener for these events
  * @param onReceiveMessage a callback function triggered when a message is received
- * @returns
+ * @deprecated Please use the {@link import('./useIncomingPostMessages')#default useIncomingPostMessages} and/or
+ * {@link import('./usePostMessageSender')#default usePostMessageSender} hooks instead.
  */
 declare const usePostMessage: (messagePrefix: string, onReceiveMessage?: (eventData: any) => void) => {
     sendMessageToParent: (message: RemoteAction) => void;

package/hooks/usePostMessage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usePostMessage.js","sources":["../../src/hooks/usePostMessage.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport { isEmpty, noop } from 'es-toolkit/compat';\n\nexport type RemoteAction = {\n    /**\n     * The RemoteAction is inspired by a plain redux action where the type is the\n     * action identifier.\n     *\n     * @example\n     *\n     * ```json\n     * {\n     *      \"type\": \"EVENT_SET_VISIBLE_WIDGETS\",\n     *      \"payload\": [\"foo\", \"bar\"],\n     * }\n     * ```\n     */\n    type: string;\n\n    /**\n     * The action payload itself.\n     */\n    payload: any;\n};\n\n/**\n * A custom hook to ease the exchange of postMessage events between iframes and the parent window.\n *\n * @param messagePrefix a custom prefix to limit the event listener for these events\n * @param onReceiveMessage a callback function triggered when a message is received\n * @returns\n */\nconst usePostMessage = (messagePrefix: string, onReceiveMessage?: (eventData: any) => void) => {\n    const sendMessageToParent = (message: RemoteAction) => {\n        const referrer = document.referrer;\n        if (referrer) {\n            window.parent.postMessage(message, referrer);\n        }\n    };\n\n    const sendMessageToWidget = (message: RemoteAction, targetFrames: HTMLIFrameElement | HTMLIFrameElement[]) => {\n        if (!targetFrames || isEmpty(targetFrames)) {\n            return;\n        }\n\n        const frames = Array.isArray(targetFrames) ? [...targetFrames] : [targetFrames];\n\n        [...frames].forEach(target => {\n            const contentWindow = target.contentWindow;\n            if (contentWindow) {\n                contentWindow.postMessage(message, '*');\n            }\n        });\n    };\n\n    const receiveMessage = (event: MessageEvent, callback: (eventData: any) => void) => {\n        const actionType = event.data.type;\n        if (!actionType) {\n            return;\n        }\n\n        if (actionType.startsWith(messagePrefix)) {\n            callback(event.data);\n        }\n    };\n\n    useEffect(() => {\n        const listenerCallback = (event: MessageEvent) => receiveMessage(event, onReceiveMessage || noop);\n        window.addEventListener('message', listenerCallback, false);\n        return () => window.removeEventListener('message', listenerCallback, false);\n    }, []);\n\n    return {\n        sendMessageToParent,\n        sendMessageToWidget,\n    };\n};\n\nexport default usePostMessage;\n"],"names":["usePostMessage","messagePrefix","onReceiveMessage","sendMessageToParent","message","referrer","sendMessageToWidget","targetFrames","isEmpty","target","contentWindow","receiveMessage","event","callback","actionType","useEffect","listenerCallback","noop"],"mappings":";;AAgCA,MAAMA,IAAiB,CAACC,GAAuBC,MAAgD;AAC3F,QAAMC,IAAsB,CAACC,MAA0B;AACnD,UAAMC,IAAW,SAAS;AAC1B,IAAIA,KACA,OAAO,OAAO,YAAYD,GAASC,CAAQ;AAAA,EAEnD,GAEMC,IAAsB,CAACF,GAAuBG,MAA0D;AAC1G,QAAI,CAACA,KAAgBC,EAAQD,CAAY;AACrC;AAKJ,KAAC,GAFc,MAAM,QAAQA,CAAY,IAAI,CAAC,GAAGA,CAAY,IAAI,CAACA,CAAY,CAEpE,EAAE,QAAQ,CAAAE,MAAU;AAC1B,YAAMC,IAAgBD,EAAO;AAC7B,MAAIC,KACAA,EAAc,YAAYN,GAAS,GAAG;AAAA,IAE9C,CAAC;AAAA,EACL,GAEMO,IAAiB,CAACC,GAAqBC,MAAuC;AAChF,UAAMC,IAAaF,EAAM,KAAK;AAC9B,IAAKE,KAIDA,EAAW,WAAWb,CAAa,KACnCY,EAASD,EAAM,IAAI;AAAA,EAE3B;AAEA,SAAAG,EAAU,MAAM;AACZ,UAAMC,IAAmB,CAACJ,MAAwBD,EAAeC,GAAOV,KAAoBe,CAAI;AAChG,kBAAO,iBAAiB,WAAWD,GAAkB,EAAK,GACnD,MAAM,OAAO,oBAAoB,WAAWA,GAAkB,EAAK;AAAA,EAC9E,GAAG,CAAA,CAAE,GAEE;AAAA,IACH,qBAAAb;AAAA,IACA,qBAAAG;AAAA,EAAA;AAER;"}
+{"version":3,"file":"usePostMessage.js","sources":["../../src/hooks/usePostMessage.ts"],"sourcesContent":["import { useEffect } from 'react';\nimport { isEmpty, noop } from 'es-toolkit/compat';\n\nexport type RemoteAction = {\n    /**\n     * The RemoteAction is inspired by a plain redux action where the type is the\n     * action identifier.\n     *\n     * @example\n     *\n     * ```json\n     * {\n     *      \"type\": \"EVENT_SET_VISIBLE_WIDGETS\",\n     *      \"payload\": [\"foo\", \"bar\"],\n     * }\n     * ```\n     */\n    type: string;\n\n    /**\n     * The action payload itself.\n     */\n    payload: any;\n};\n\n/**\n * A custom hook to ease the exchange of postMessage events between iframes and the parent window.\n *\n * @param messagePrefix a custom prefix to limit the event listener for these events\n * @param onReceiveMessage a callback function triggered when a message is received\n * @deprecated Please use the {@link import('./useIncomingPostMessages')#default useIncomingPostMessages} and/or\n * {@link import('./usePostMessageSender')#default usePostMessageSender} hooks instead.\n */\nconst usePostMessage = (messagePrefix: string, onReceiveMessage?: (eventData: any) => void) => {\n    const sendMessageToParent = (message: RemoteAction) => {\n        const referrer = document.referrer;\n        if (referrer) {\n            window.parent.postMessage(message, referrer);\n        }\n    };\n\n    const sendMessageToWidget = (message: RemoteAction, targetFrames: HTMLIFrameElement | HTMLIFrameElement[]) => {\n        if (!targetFrames || isEmpty(targetFrames)) {\n            return;\n        }\n\n        const frames = Array.isArray(targetFrames) ? [...targetFrames] : [targetFrames];\n\n        [...frames].forEach(target => {\n            const contentWindow = target.contentWindow;\n            if (contentWindow) {\n                contentWindow.postMessage(message, '*');\n            }\n        });\n    };\n\n    const receiveMessage = (event: MessageEvent, callback: (eventData: any) => void) => {\n        const actionType = event.data.type;\n        if (!actionType) {\n            return;\n        }\n\n        if (actionType.startsWith(messagePrefix)) {\n            callback(event.data);\n        }\n    };\n\n    useEffect(() => {\n        const listenerCallback = (event: MessageEvent) => receiveMessage(event, onReceiveMessage || noop);\n        window.addEventListener('message', listenerCallback, false);\n        return () => window.removeEventListener('message', listenerCallback, false);\n    }, []);\n\n    return {\n        sendMessageToParent,\n        sendMessageToWidget,\n    };\n};\n\nexport default usePostMessage;\n"],"names":["usePostMessage","messagePrefix","onReceiveMessage","sendMessageToParent","message","referrer","sendMessageToWidget","targetFrames","isEmpty","target","contentWindow","receiveMessage","event","callback","actionType","useEffect","listenerCallback","noop"],"mappings":";;AAiCA,MAAMA,IAAiB,CAACC,GAAuBC,MAAgD;AAC3F,QAAMC,IAAsB,CAACC,MAA0B;AACnD,UAAMC,IAAW,SAAS;AAC1B,IAAIA,KACA,OAAO,OAAO,YAAYD,GAASC,CAAQ;AAAA,EAEnD,GAEMC,IAAsB,CAACF,GAAuBG,MAA0D;AAC1G,QAAI,CAACA,KAAgBC,EAAQD,CAAY;AACrC;AAKJ,KAAC,GAFc,MAAM,QAAQA,CAAY,IAAI,CAAC,GAAGA,CAAY,IAAI,CAACA,CAAY,CAEpE,EAAE,QAAQ,CAAAE,MAAU;AAC1B,YAAMC,IAAgBD,EAAO;AAC7B,MAAIC,KACAA,EAAc,YAAYN,GAAS,GAAG;AAAA,IAE9C,CAAC;AAAA,EACL,GAEMO,IAAiB,CAACC,GAAqBC,MAAuC;AAChF,UAAMC,IAAaF,EAAM,KAAK;AAC9B,IAAKE,KAIDA,EAAW,WAAWb,CAAa,KACnCY,EAASD,EAAM,IAAI;AAAA,EAE3B;AAEA,SAAAG,EAAU,MAAM;AACZ,UAAMC,IAAmB,CAACJ,MAAwBD,EAAeC,GAAOV,KAAoBe,CAAI;AAChG,kBAAO,iBAAiB,WAAWD,GAAkB,EAAK,GACnD,MAAM,OAAO,oBAAoB,WAAWA,GAAkB,EAAK;AAAA,EAC9E,GAAG,CAAA,CAAE,GAEE;AAAA,IACH,qBAAAb;AAAA,IACA,qBAAAG;AAAA,EAAA;AAER;"}

package/hooks/useRioCookieConsent.d.ts

@@ -0,0 +1,49 @@
+export type RioCookieConsentStatus = 'missing' | 'invalid' | 'ux-cookies-accepted' | 'marketing-cookies-accepted' | 'custom';
+export type RioCookieConsentInfo = {
+    /**
+     * Name of the RIO consent cookie.
+     */
+    cookieName: 'cookie_settings';
+    /**
+     * Indicates whether the consent cookie exists.
+     */
+    isSet: boolean;
+    /**
+     * Raw cookie value as read from `document.cookie`.
+     */
+    rawValue?: string;
+    /**
+     * Parsed and normalized cookie switches when JSON parsing succeeds.
+     */
+    parsedValue?: Record<string, number>;
+    /**
+     * True when UX cookies are accepted (`switch-49 === 1`).
+     */
+    uxCookiesAccepted: boolean;
+    /**
+     * True when marketing cookies are accepted (`switch-2 === 1`).
+     */
+    marketingCookiesAccepted: boolean;
+    /**
+     * Computed consent status derived from parsed cookie values.
+     */
+    status: RioCookieConsentStatus;
+};
+export type UseRioCookieConsentResult = {
+    /**
+     * Reads and parses the RIO cookie consent settings.
+     */
+    getRioCookieConsentInfo: () => RioCookieConsentInfo;
+};
+/**
+ * Returns helpers for reading RIO's cookie consent state from `cookie_settings`.
+ *
+ * @returns {UseRioCookieConsentResult} Cookie consent helper functions.
+ *
+ * @example
+ * const { getRioCookieConsentInfo } = useRioCookieConsent();
+ * const consent = getRioCookieConsentInfo();
+ * const uxAccepted = consent.uxCookiesAccepted;
+ */
+declare const useRioCookieConsent: () => UseRioCookieConsentResult;
+export default useRioCookieConsent;

package/hooks/useRioCookieConsent.js

@@ -0,0 +1,44 @@
+import { useCallback as c } from "react";
+import n from "./useCookies.js";
+const a = (e) => {
+  if (!e)
+    return {
+      cookieName: "cookie_settings",
+      isSet: !1,
+      uxCookiesAccepted: !1,
+      marketingCookiesAccepted: !1,
+      status: "missing"
+    };
+  try {
+    const t = JSON.parse(e), s = t["switch-49"] === 1, o = t["switch-2"] === 1;
+    let i = "custom";
+    return s && !o ? i = "ux-cookies-accepted" : !s && o && (i = "marketing-cookies-accepted"), {
+      cookieName: "cookie_settings",
+      isSet: !0,
+      rawValue: e,
+      parsedValue: {
+        "switch-2": Number(t["switch-2"]),
+        "switch-49": Number(t["switch-49"])
+      },
+      uxCookiesAccepted: s,
+      marketingCookiesAccepted: o,
+      status: i
+    };
+  } catch {
+    return {
+      cookieName: "cookie_settings",
+      isSet: !0,
+      rawValue: e,
+      uxCookiesAccepted: !1,
+      marketingCookiesAccepted: !1,
+      status: "invalid"
+    };
+  }
+}, u = () => {
+  const { getCookie: e } = n();
+  return { getRioCookieConsentInfo: c(() => a(e("cookie_settings")), [e]) };
+};
+export {
+  u as default
+};
+//# sourceMappingURL=useRioCookieConsent.js.map

package/hooks/useRioCookieConsent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useRioCookieConsent.js","sources":["../../src/hooks/useRioCookieConsent.ts"],"sourcesContent":["import { useCallback } from 'react';\n\nimport useCookies from './useCookies';\n\nexport type RioCookieConsentStatus =\n    | 'missing'\n    | 'invalid'\n    | 'ux-cookies-accepted'\n    | 'marketing-cookies-accepted'\n    | 'custom';\n\nexport type RioCookieConsentInfo = {\n    /**\n     * Name of the RIO consent cookie.\n     */\n    cookieName: 'cookie_settings';\n\n    /**\n     * Indicates whether the consent cookie exists.\n     */\n    isSet: boolean;\n\n    /**\n     * Raw cookie value as read from `document.cookie`.\n     */\n    rawValue?: string;\n\n    /**\n     * Parsed and normalized cookie switches when JSON parsing succeeds.\n     */\n    parsedValue?: Record<string, number>;\n\n    /**\n     * True when UX cookies are accepted (`switch-49 === 1`).\n     */\n    uxCookiesAccepted: boolean;\n\n    /**\n     * True when marketing cookies are accepted (`switch-2 === 1`).\n     */\n    marketingCookiesAccepted: boolean;\n\n    /**\n     * Computed consent status derived from parsed cookie values.\n     */\n    status: RioCookieConsentStatus;\n};\n\nexport type UseRioCookieConsentResult = {\n    /**\n     * Reads and parses the RIO cookie consent settings.\n     */\n    getRioCookieConsentInfo: () => RioCookieConsentInfo;\n};\n\nconst evaluateRioCookieSettings = (cookieValue?: string): RioCookieConsentInfo => {\n    if (!cookieValue) {\n        return {\n            cookieName: 'cookie_settings',\n            isSet: false,\n            uxCookiesAccepted: false,\n            marketingCookiesAccepted: false,\n            status: 'missing',\n        };\n    }\n\n    try {\n        const parsed = JSON.parse(cookieValue) as Record<string, unknown>;\n        const uxCookiesAccepted = parsed['switch-49'] === 1;\n        const marketingCookiesAccepted = parsed['switch-2'] === 1;\n\n        let status: RioCookieConsentStatus = 'custom';\n        if (uxCookiesAccepted && !marketingCookiesAccepted) {\n            status = 'ux-cookies-accepted';\n        } else if (!uxCookiesAccepted && marketingCookiesAccepted) {\n            status = 'marketing-cookies-accepted';\n        }\n\n        return {\n            cookieName: 'cookie_settings',\n            isSet: true,\n            rawValue: cookieValue,\n            parsedValue: {\n                'switch-2': Number(parsed['switch-2']),\n                'switch-49': Number(parsed['switch-49']),\n            },\n            uxCookiesAccepted,\n            marketingCookiesAccepted,\n            status,\n        };\n    } catch {\n        return {\n            cookieName: 'cookie_settings',\n            isSet: true,\n            rawValue: cookieValue,\n            uxCookiesAccepted: false,\n            marketingCookiesAccepted: false,\n            status: 'invalid',\n        };\n    }\n};\n\n/**\n * Returns helpers for reading RIO's cookie consent state from `cookie_settings`.\n *\n * @returns {UseRioCookieConsentResult} Cookie consent helper functions.\n *\n * @example\n * const { getRioCookieConsentInfo } = useRioCookieConsent();\n * const consent = getRioCookieConsentInfo();\n * const uxAccepted = consent.uxCookiesAccepted;\n */\nconst useRioCookieConsent = (): UseRioCookieConsentResult => {\n    const { getCookie } = useCookies();\n\n    const getRioCookieConsentInfo = useCallback(() => {\n        return evaluateRioCookieSettings(getCookie('cookie_settings'));\n    }, [getCookie]);\n\n    return { getRioCookieConsentInfo };\n};\n\nexport default useRioCookieConsent;\n"],"names":["evaluateRioCookieSettings","cookieValue","parsed","uxCookiesAccepted","marketingCookiesAccepted","status","useRioCookieConsent","getCookie","useCookies","useCallback"],"mappings":";;AAuDA,MAAMA,IAA4B,CAACC,MAA+C;AAC9E,MAAI,CAACA;AACD,WAAO;AAAA,MACH,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,mBAAmB;AAAA,MACnB,0BAA0B;AAAA,MAC1B,QAAQ;AAAA,IAAA;AAIhB,MAAI;AACA,UAAMC,IAAS,KAAK,MAAMD,CAAW,GAC/BE,IAAoBD,EAAO,WAAW,MAAM,GAC5CE,IAA2BF,EAAO,UAAU,MAAM;AAExD,QAAIG,IAAiC;AACrC,WAAIF,KAAqB,CAACC,IACtBC,IAAS,wBACF,CAACF,KAAqBC,MAC7BC,IAAS,+BAGN;AAAA,MACH,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,UAAUJ;AAAA,MACV,aAAa;AAAA,QACT,YAAY,OAAOC,EAAO,UAAU,CAAC;AAAA,QACrC,aAAa,OAAOA,EAAO,WAAW,CAAC;AAAA,MAAA;AAAA,MAE3C,mBAAAC;AAAA,MACA,0BAAAC;AAAA,MACA,QAAAC;AAAA,IAAA;AAAA,EAER,QAAQ;AACJ,WAAO;AAAA,MACH,YAAY;AAAA,MACZ,OAAO;AAAA,MACP,UAAUJ;AAAA,MACV,mBAAmB;AAAA,MACnB,0BAA0B;AAAA,MAC1B,QAAQ;AAAA,IAAA;AAAA,EAEhB;AACJ,GAYMK,IAAsB,MAAiC;AACzD,QAAM,EAAE,WAAAC,EAAA,IAAcC,EAAA;AAMtB,SAAO,EAAE,yBAJuBC,EAAY,MACjCT,EAA0BO,EAAU,iBAAiB,CAAC,GAC9D,CAACA,CAAS,CAAC,EAEL;AACb;"}

package/hooks/useSearch.d.ts

@@ -57,7 +57,7 @@ type UseSearchOptions<T> = {
  */
 declare const useSearch: <T extends object>(list: T[], options?: UseSearchOptions<T>) => {
     searchValue: string;
-    setSearchValue: import('react').Dispatch<import('react').SetStateAction<string>> | import('es-toolkit/function').DebouncedFunction<(q: string) => void>;
+    setSearchValue: (query: string) => void;
     filteredList: T[];
 };
 export default useSearch;

package/hooks/useSearch.js

@@ -1,31 +1,42 @@
-import { useState as d, useCallback as b, useMemo as m } from "react";
-import { debounce as S } from "es-toolkit/function";
-const g = (r, e) => e.split(".").reduce((t, u) => t ? t[u] : void 0, r), h = (r) => Object.keys(r).filter((e) => {
+import { useState as i, useMemo as b, useCallback as V, useEffect as h } from "react";
+import { debounce as v } from "es-toolkit/function";
+const y = (r, e) => e.split(".").reduce((t, s) => t ? t[s] : void 0, r), C = (r) => Object.keys(r).filter((e) => {
   const t = r[e];
   return typeof t == "string" || typeof t == "number";
-}), M = (r, e = {}) => {
-  const [t, u] = d(""), o = b(
-    e.debounceMs ? S((n) => u(n), e.debounceMs) : u,
-    [e.debounceMs]
-  ), f = m(() => {
+}), w = (r, e = {}) => {
+  const [t, s] = i(""), [l, a] = i(""), f = b(() => e.debounceMs ? v((c) => a(c), e.debounceMs) : null, [e.debounceMs]), m = V(
+    (u) => {
+      if (s(u), !f) {
+        a(u);
+        return;
+      }
+      f(u);
+    },
+    [f]
+  );
+  h(() => {
+    e.debounceMs || a(t);
+  }, [e.debounceMs, t]);
+  const S = b(() => {
+    const u = e.debounceMs ? l : t;
     if (!t)
       return r;
     if (r.length === 0)
       return [];
-    const n = e.caseSensitive ?? !1, a = n ? t : t.toLowerCase();
+    const c = e.caseSensitive ?? !1, d = c ? u : u.toLowerCase();
     if (e.customFilter)
-      return r.filter((c) => e.customFilter?.(c, t));
-    const l = e.fields ?? h(r[0]);
+      return r.filter((o) => e.customFilter?.(o, u));
+    const g = e.fields ?? C(r[0]);
     return r.filter(
-      (c) => l.some((i) => {
-        const s = g(c, i.toString());
-        return typeof s == "string" ? (n ? s : s.toLowerCase()).includes(a) : typeof s == "number" ? s.toString().includes(a) : !1;
+      (o) => g.some((M) => {
+        const n = y(o, M.toString());
+        return typeof n == "string" ? (c ? n : n.toLowerCase()).includes(d) : typeof n == "number" ? n.toString().includes(d) : !1;
       })
     );
-  }, [r, e, t]);
-  return { searchValue: t, setSearchValue: o, filteredList: f };
+  }, [l, r, e, t]);
+  return { searchValue: t, setSearchValue: m, filteredList: S };
 };
 export {
-  M as default
+  w as default
 };
 //# sourceMappingURL=useSearch.js.map

package/hooks/useSearch.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSearch.js","sources":["../../src/hooks/useSearch.ts"],"sourcesContent":["import { useMemo, useState, useCallback } from 'react';\nimport { debounce } from 'es-toolkit/function';\n\n/**\n * Options for configuring the `useSearch` hook.\n */\ntype UseSearchOptions<T> = {\n    /**\n     * List of object fields to search within. Dot notation (e.g. `'address.city'`) is supported for nested properties.\n     * If omitted, all top-level string and number fields will be used.\n     */\n    fields?: (keyof T | string)[]; // `string` to allow dot notation\n\n    /**\n     * Optional custom filtering function.\n     * If provided, this takes precedence over field-based filtering.\n     *\n     * @param item - The current item in the list.\n     * @param query - The current search query string.\n     * @returns `true` if the item should be included in the filtered list.\n     */\n    customFilter?: (item: T, query: string) => boolean;\n\n    /**\n     * Number of milliseconds to debounce the search input.\n     * If omitted, debounce is disabled.\n     */\n    debounceMs?: number;\n\n    /**\n     * Whether to perform a case-sensitive match.\n     * Default is `false` (case-insensitive).\n     *\n     * @default false\n     */\n    caseSensitive?: boolean;\n};\n\n/**\n * Gets the value of a nested field from an object using dot notation.\n *\n * @param obj - The object to traverse.\n * @param path - The dot-notated path string.\n * @returns The value at the specified path, or undefined.\n */\nconst getNestedValue = (obj: any, path: string): unknown =>\n    path.split('.').reduce((val, key) => (val ? val[key] : undefined), obj);\n\nconst inferSearchableFields = <T extends object>(item: T): string[] =>\n    Object.keys(item).filter(key => {\n        const value = (item as any)[key];\n        return typeof value === 'string' || typeof value === 'number';\n    });\n\n/**\n * A hook to filter a list of objects by a search value.\n * Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.\n *\n * @template T - The type of items in the list (must be an object).\n *\n * @param list - The array of objects to search through.\n * @param options - Configuration options for the search behavior.\n * @param options.fields - Fields to search through. If omitted, all top-level string/number fields are used.\n * @param options.customFilter - Optional custom filter function overriding field-based filtering.\n * @param options.debounceMs - Debounce time in milliseconds.\n * @param options.caseSensitive - Whether the search should be case-sensitive.\n *\n * @returns An object containing:\n * - `searchValue`: The current search input string.\n * - `setSearchValue`: A setter function to update the search query.\n * - `filteredList`: The list of items matching the current search query.\n *\n * @example\n * ```ts\n * const { searchValue, setSearchValue, filteredList } = useSearch(users, {\n *   fields: ['name', 'email'],\n *   debounceMs: 300,\n * });\n * ```\n */\nconst useSearch = <T extends object>(list: T[], options: UseSearchOptions<T> = {}) => {\n    const [searchValue, _setSearchValue] = useState('');\n\n    // Debounced setter\n    const setSearchValue = useCallback(\n        options.debounceMs ? debounce((q: string) => _setSearchValue(q), options.debounceMs) : _setSearchValue,\n        [options.debounceMs]\n    );\n\n    const filteredList = useMemo(() => {\n        if (!searchValue) {\n            return list;\n        }\n        if (list.length === 0) {\n            return [];\n        }\n\n        const isCaseSensitive = options.caseSensitive ?? false;\n        const query = isCaseSensitive ? searchValue : searchValue.toLowerCase();\n\n        // Custom filter takes precedence\n        if (options.customFilter) {\n            return list.filter(item => options.customFilter?.(item, searchValue));\n        }\n\n        const fields = options.fields ?? inferSearchableFields(list[0]);\n\n        return list.filter(item =>\n            fields.some(field => {\n                const value = getNestedValue(item, field.toString());\n\n                if (typeof value === 'string') {\n                    const target = isCaseSensitive ? value : value.toLowerCase();\n                    return target.includes(query);\n                }\n\n                if (typeof value === 'number') {\n                    return value.toString().includes(query);\n                }\n\n                return false;\n            })\n        );\n    }, [list, options, searchValue]);\n\n    return { searchValue, setSearchValue, filteredList };\n};\n\nexport default useSearch;\n"],"names":["getNestedValue","obj","path","val","key","inferSearchableFields","item","value","useSearch","list","options","searchValue","_setSearchValue","useState","setSearchValue","useCallback","debounce","q","filteredList","useMemo","isCaseSensitive","query","fields","field"],"mappings":";;AA6CA,MAAMA,IAAiB,CAACC,GAAUC,MAC9BA,EAAK,MAAM,GAAG,EAAE,OAAO,CAACC,GAAKC,MAASD,IAAMA,EAAIC,CAAG,IAAI,QAAYH,CAAG,GAEpEI,IAAwB,CAAmBC,MAC7C,OAAO,KAAKA,CAAI,EAAE,OAAO,CAAAF,MAAO;AAC5B,QAAMG,IAASD,EAAaF,CAAG;AAC/B,SAAO,OAAOG,KAAU,YAAY,OAAOA,KAAU;AACzD,CAAC,GA4BCC,IAAY,CAAmBC,GAAWC,IAA+B,OAAO;AAClF,QAAM,CAACC,GAAaC,CAAe,IAAIC,EAAS,EAAE,GAG5CC,IAAiBC;AAAA,IACnBL,EAAQ,aAAaM,EAAS,CAACC,MAAcL,EAAgBK,CAAC,GAAGP,EAAQ,UAAU,IAAIE;AAAA,IACvF,CAACF,EAAQ,UAAU;AAAA,EAAA,GAGjBQ,IAAeC,EAAQ,MAAM;AAC/B,QAAI,CAACR;AACD,aAAOF;AAEX,QAAIA,EAAK,WAAW;AAChB,aAAO,CAAA;AAGX,UAAMW,IAAkBV,EAAQ,iBAAiB,IAC3CW,IAAQD,IAAkBT,IAAcA,EAAY,YAAA;AAG1D,QAAID,EAAQ;AACR,aAAOD,EAAK,OAAO,CAAAH,MAAQI,EAAQ,eAAeJ,GAAMK,CAAW,CAAC;AAGxE,UAAMW,IAASZ,EAAQ,UAAUL,EAAsBI,EAAK,CAAC,CAAC;AAE9D,WAAOA,EAAK;AAAA,MAAO,CAAAH,MACfgB,EAAO,KAAK,CAAAC,MAAS;AACjB,cAAMhB,IAAQP,EAAeM,GAAMiB,EAAM,UAAU;AAEnD,eAAI,OAAOhB,KAAU,YACFa,IAAkBb,IAAQA,EAAM,YAAA,GACjC,SAASc,CAAK,IAG5B,OAAOd,KAAU,WACVA,EAAM,WAAW,SAASc,CAAK,IAGnC;AAAA,MACX,CAAC;AAAA,IAAA;AAAA,EAET,GAAG,CAACZ,GAAMC,GAASC,CAAW,CAAC;AAE/B,SAAO,EAAE,aAAAA,GAAa,gBAAAG,GAAgB,cAAAI,EAAA;AAC1C;"}
+{"version":3,"file":"useSearch.js","sources":["../../src/hooks/useSearch.ts"],"sourcesContent":["import { useMemo, useState, useCallback, useEffect } from 'react';\nimport { debounce } from 'es-toolkit/function';\n\n/**\n * Options for configuring the `useSearch` hook.\n */\ntype UseSearchOptions<T> = {\n    /**\n     * List of object fields to search within. Dot notation (e.g. `'address.city'`) is supported for nested properties.\n     * If omitted, all top-level string and number fields will be used.\n     */\n    fields?: (keyof T | string)[]; // `string` to allow dot notation\n\n    /**\n     * Optional custom filtering function.\n     * If provided, this takes precedence over field-based filtering.\n     *\n     * @param item - The current item in the list.\n     * @param query - The current search query string.\n     * @returns `true` if the item should be included in the filtered list.\n     */\n    customFilter?: (item: T, query: string) => boolean;\n\n    /**\n     * Number of milliseconds to debounce the search input.\n     * If omitted, debounce is disabled.\n     */\n    debounceMs?: number;\n\n    /**\n     * Whether to perform a case-sensitive match.\n     * Default is `false` (case-insensitive).\n     *\n     * @default false\n     */\n    caseSensitive?: boolean;\n};\n\n/**\n * Gets the value of a nested field from an object using dot notation.\n *\n * @param obj - The object to traverse.\n * @param path - The dot-notated path string.\n * @returns The value at the specified path, or undefined.\n */\nconst getNestedValue = (obj: any, path: string): unknown =>\n    path.split('.').reduce((val, key) => (val ? val[key] : undefined), obj);\n\nconst inferSearchableFields = <T extends object>(item: T): string[] =>\n    Object.keys(item).filter(key => {\n        const value = (item as any)[key];\n        return typeof value === 'string' || typeof value === 'number';\n    });\n\n/**\n * A hook to filter a list of objects by a search value.\n * Supports field-based filtering, custom filtering logic, debounce, and case sensitivity.\n *\n * @template T - The type of items in the list (must be an object).\n *\n * @param list - The array of objects to search through.\n * @param options - Configuration options for the search behavior.\n * @param options.fields - Fields to search through. If omitted, all top-level string/number fields are used.\n * @param options.customFilter - Optional custom filter function overriding field-based filtering.\n * @param options.debounceMs - Debounce time in milliseconds.\n * @param options.caseSensitive - Whether the search should be case-sensitive.\n *\n * @returns An object containing:\n * - `searchValue`: The current search input string.\n * - `setSearchValue`: A setter function to update the search query.\n * - `filteredList`: The list of items matching the current search query.\n *\n * @example\n * ```ts\n * const { searchValue, setSearchValue, filteredList } = useSearch(users, {\n *   fields: ['name', 'email'],\n *   debounceMs: 300,\n * });\n * ```\n */\nconst useSearch = <T extends object>(list: T[], options: UseSearchOptions<T> = {}) => {\n    // what the input renders (must update immediately)\n    const [searchValue, _setSearchValue] = useState('');\n\n    // what filtering uses (debounced if configured)\n    const [debouncedValue, setDebouncedValue] = useState('');\n\n    // stable debounced updater\n    const debouncedUpdate = useMemo(() => {\n        if (!options.debounceMs) {\n            return null;\n        }\n\n        const fn = debounce((query: string) => setDebouncedValue(query), options.debounceMs);\n        return fn;\n    }, [options.debounceMs]);\n\n    // setter exposed to consumers\n    const setSearchValue = useCallback(\n        (query: string) => {\n            _setSearchValue(query);\n\n            if (!debouncedUpdate) {\n                setDebouncedValue(query);\n                return;\n            }\n\n            debouncedUpdate(query);\n        },\n        [debouncedUpdate]\n    );\n\n    // keep debouncedValue in sync for the \"no debounce\" case and initial render\n    useEffect(() => {\n        if (!options.debounceMs) {\n            setDebouncedValue(searchValue);\n        }\n    }, [options.debounceMs, searchValue]);\n\n    const filteredList = useMemo(() => {\n        const activeQueryValue = options.debounceMs ? debouncedValue : searchValue;\n\n        if (!searchValue) {\n            return list;\n        }\n        if (list.length === 0) {\n            return [];\n        }\n\n        const isCaseSensitive = options.caseSensitive ?? false;\n        const query = isCaseSensitive ? activeQueryValue : activeQueryValue.toLowerCase();\n\n        // Custom filter takes precedence\n        if (options.customFilter) {\n            return list.filter(item => options.customFilter?.(item, activeQueryValue));\n        }\n\n        const fields = options.fields ?? inferSearchableFields(list[0]);\n\n        return list.filter(item =>\n            fields.some(field => {\n                const value = getNestedValue(item, field.toString());\n\n                if (typeof value === 'string') {\n                    const target = isCaseSensitive ? value : value.toLowerCase();\n                    return target.includes(query);\n                }\n\n                if (typeof value === 'number') {\n                    return value.toString().includes(query);\n                }\n\n                return false;\n            })\n        );\n    }, [debouncedValue, list, options, searchValue]);\n\n    return { searchValue, setSearchValue, filteredList };\n};\n\nexport default useSearch;\n"],"names":["getNestedValue","obj","path","val","key","inferSearchableFields","item","value","useSearch","list","options","searchValue","_setSearchValue","useState","debouncedValue","setDebouncedValue","debouncedUpdate","useMemo","debounce","query","setSearchValue","useCallback","useEffect","filteredList","activeQueryValue","isCaseSensitive","fields","field"],"mappings":";;AA6CA,MAAMA,IAAiB,CAACC,GAAUC,MAC9BA,EAAK,MAAM,GAAG,EAAE,OAAO,CAACC,GAAKC,MAASD,IAAMA,EAAIC,CAAG,IAAI,QAAYH,CAAG,GAEpEI,IAAwB,CAAmBC,MAC7C,OAAO,KAAKA,CAAI,EAAE,OAAO,CAAAF,MAAO;AAC5B,QAAMG,IAASD,EAAaF,CAAG;AAC/B,SAAO,OAAOG,KAAU,YAAY,OAAOA,KAAU;AACzD,CAAC,GA4BCC,IAAY,CAAmBC,GAAWC,IAA+B,OAAO;AAElF,QAAM,CAACC,GAAaC,CAAe,IAAIC,EAAS,EAAE,GAG5C,CAACC,GAAgBC,CAAiB,IAAIF,EAAS,EAAE,GAGjDG,IAAkBC,EAAQ,MACvBP,EAAQ,aAIFQ,EAAS,CAACC,MAAkBJ,EAAkBI,CAAK,GAAGT,EAAQ,UAAU,IAHxE,MAKZ,CAACA,EAAQ,UAAU,CAAC,GAGjBU,IAAiBC;AAAA,IACnB,CAACF,MAAkB;AAGf,UAFAP,EAAgBO,CAAK,GAEjB,CAACH,GAAiB;AAClB,QAAAD,EAAkBI,CAAK;AACvB;AAAA,MACJ;AAEA,MAAAH,EAAgBG,CAAK;AAAA,IACzB;AAAA,IACA,CAACH,CAAe;AAAA,EAAA;AAIpB,EAAAM,EAAU,MAAM;AACZ,IAAKZ,EAAQ,cACTK,EAAkBJ,CAAW;AAAA,EAErC,GAAG,CAACD,EAAQ,YAAYC,CAAW,CAAC;AAEpC,QAAMY,IAAeN,EAAQ,MAAM;AAC/B,UAAMO,IAAmBd,EAAQ,aAAaI,IAAiBH;AAE/D,QAAI,CAACA;AACD,aAAOF;AAEX,QAAIA,EAAK,WAAW;AAChB,aAAO,CAAA;AAGX,UAAMgB,IAAkBf,EAAQ,iBAAiB,IAC3CS,IAAQM,IAAkBD,IAAmBA,EAAiB,YAAA;AAGpE,QAAId,EAAQ;AACR,aAAOD,EAAK,OAAO,CAAAH,MAAQI,EAAQ,eAAeJ,GAAMkB,CAAgB,CAAC;AAG7E,UAAME,IAAShB,EAAQ,UAAUL,EAAsBI,EAAK,CAAC,CAAC;AAE9D,WAAOA,EAAK;AAAA,MAAO,CAAAH,MACfoB,EAAO,KAAK,CAAAC,MAAS;AACjB,cAAMpB,IAAQP,EAAeM,GAAMqB,EAAM,UAAU;AAEnD,eAAI,OAAOpB,KAAU,YACFkB,IAAkBlB,IAAQA,EAAM,YAAA,GACjC,SAASY,CAAK,IAG5B,OAAOZ,KAAU,WACVA,EAAM,WAAW,SAASY,CAAK,IAGnC;AAAA,MACX,CAAC;AAAA,IAAA;AAAA,EAET,GAAG,CAACL,GAAgBL,GAAMC,GAASC,CAAW,CAAC;AAE/C,SAAO,EAAE,aAAAA,GAAa,gBAAAS,GAAgB,cAAAG,EAAA;AAC1C;"}

package/hooks/useSearchHighlight.d.ts

@@ -0,0 +1,60 @@
+export declare const SEARCH_HIGHLIGHT_CLASS = "search-result-highlight";
+export type UseSearchHighlightParams = {
+    /**
+     * Ref to the element whose text content should be searched.
+     */
+    ref: React.RefObject<HTMLElement>;
+    /**
+     * Search query used for highlighting.
+     */
+    query: string;
+    /**
+     * Name of the CSS highlight.
+     *
+     * @default 'search-result-highlight'
+     */
+    highlightClassName?: string;
+    /**
+     * Optional selector to limit the search scope
+     * (e.g. '.ListMenuGroup' or '.OptionLabel').
+     */
+    scopeSelector?: string;
+    /**
+     * Whether to perform a case-sensitive match.
+     *
+     * @default false
+     */
+    caseSensitive?: boolean;
+    /**
+     * Optional dependencies that should trigger re-collecting and applying ranges.
+     * Useful when the DOM changes after the query changes (e.g. debounced filtering).
+     */
+    deps?: unknown[];
+};
+/**
+ * React hook for visually highlighting search query matches
+ * using the native CSS Highlight API.
+ *
+ * The hook scans the text content of the referenced element
+ * and applies a named CSS highlight to all matching substrings.
+ *
+ * Key characteristics:
+ * - Progressive enhancement: safely no-ops in unsupported browsers
+ * - Does not modify or re-render DOM markup
+ * - Designed for search UIs (Autocomplete, ListMenu, Dropdown, etc.)
+ *
+ * Usage notes:
+ * - The hook must always be called unconditionally
+ * - Use `useSearchHighlight.supported()` only for render-time
+ *   fallback decisions (e.g. `<mark>` rendering)
+ *
+ * @param ref           Ref to the element whose text should be searched
+ * @param query         Search query to highlight
+ * @param highlightName Optional CSS highlight name
+ * @param scopeSelector Optional selector to limit the search scope
+ */
+declare const useSearchHighlight: {
+    (params: UseSearchHighlightParams): void;
+    supported(): boolean;
+};
+export default useSearchHighlight;