@payfit/unity-components 1.2.0 → 2.1.4

package/dist/esm/components/toggle-switch/ToggleSwitch.js

@@ -1,24 +1,30 @@
-import { jsxs as o, jsx as e } from "react/jsx-runtime";
-import { forwardRef as f } from "react";
-import { uyTv as g } from "@payfit/unity-themes";
-import { Switch as m } from "react-aria-components";
-const v = g({
+import { jsx as e, jsxs as a } from "react/jsx-runtime";
+import { forwardRef as h } from "react";
+import { uyTv as v } from "@payfit/unity-themes";
+import { Switch as b } from "react-aria-components";
+import { useBreakpointListener as w } from "../../hooks/use-breakpoint-listener.js";
+const x = v({
   slots: {
-    container: ["uy:flex uy:gap-100 uy:group"],
+    container: ["uy:flex uy:flex-col uy:sm:flex-row uy:gap-100 uy:group"],
+    mobileContainer: [
+      "uy:flex uy:flex-1 uy:justify-between uy:sm:justify-start uy:gap-200 uy:sm:gap-100 uy:group uy:my-75 uy:sm:my-0"
+    ],
     textWrapper: ["uy:flex uy:flex-col uy:gap-50"],
-    label: ["uy:typography-body uy:text-content-form-enabled"],
+    label: [
+      "uy:typography-body uy:text-content-form-enabled uy:leading-4! uy:sm:leading-3!"
+    ],
     hintText: ["uy:typography-body-small uy:text-content-neutral-low"],
     indicator: [
-      "uy:p-50 uy:w-500 uy:h-300 uy:flex uy:items-center",
+      "uy:p-50 uy:w-6.75 uy:h-4 uy:sm:w-500 uy:sm:h-300 uy:flex uy:items-center uy:shrink-0 uy:grow-0",
       "uy:rounded-pill",
       "uy:border uy:border-solid uy:border-border-form-disabled uy:bg-surface-form-disabled",
       "uy:cursor-pointer uy:transition-colors uy:duration-200 uy:ease-in-out",
       "uy:group-data-[pressed]:bg-surface-form-pressed uy:group-data-[pressed]:border-border-form-pressed",
       "uy:group-data-[disabled]:bg-surface-form-disabled uy:group-data-[disabled]:border-border-form-disabled uy:group-data-[disabled]:cursor-not-allowed",
-      "uy:group-data-[focus-visible]:outline-2 uy:group-data-[focus-visible]:outline uy:group-data-[focus-visible]:outline-offset-2 uy:group-data-[focus-visible]:outline-utility-focus-ring"
+      "uy:group-data-[focus-visible]:outline-2 uy:group-data-[focus-visible]:outline-offset-2 uy:group-data-[focus-visible]:outline-utility-focus-ring"
     ],
     knob: [
-      "uy:w-200 uy:h-200 uy:rounded-circle",
+      "uy:w-300 uy:h-300 uy:sm:w-200 uy:sm:h-200 uy:rounded-circle",
       "uy:border uy:border-solid uy:border-border-form-disabled uy:bg-surface-form-enabled",
       "uy:transition-all uy:duration-200 uy:ease-in-out",
       'uy:group-data-[selected="true"]:translate-x-[90%]',
@@ -33,39 +39,72 @@ const v = g({
         knob: 'uy:group-data-[selected="true"]:border-border-inverted-enabled uy:group-data-[selected="true"]:group-data-[pressed]:bg-surface-form-pressed uy:group-data-[selected="true"]:group-data-[pressed]:border-border-inverted-pressed'
       },
       true: {
+        label: "uy:text-content-form-disabled",
         indicator: "",
         knob: ""
       }
     }
   }
-}), h = f(
+}), N = h(
   ({
-    label: d,
+    label: o,
     helperText: r,
-    isLabelSrOnly: u = !1,
-    isDisabled: a,
-    ...t
-  }, s) => {
-    const { container: l, indicator: i, knob: y, textWrapper: c, label: p, hintText: b } = v({ isDisabled: a }), n = { ...t, role: "switch" };
-    return /* @__PURE__ */ o(
-      m,
+    isLabelSrOnly: s = !1,
+    isDisabled: d,
+    ...m
+  }, u) => {
+    const {
+      container: t,
+      indicator: i,
+      knob: l,
+      textWrapper: y,
+      label: c,
+      hintText: n,
+      mobileContainer: f
+    } = x({ isDisabled: d }), g = w() === "xs", p = { ...m, role: "switch" };
+    return g ? /* @__PURE__ */ e(
+      b,
+      {
+        ...p,
+        ref: u,
+        className: t(),
+        isDisabled: d,
+        children: /* @__PURE__ */ a("div", { className: f(), children: [
+          /* @__PURE__ */ a(
+            "div",
+            {
+              className: y({
+                className: s ? "uy:sr-only" : ""
+              }),
+              "data-dd-privacy": "allow",
+              children: [
+                /* @__PURE__ */ e("span", { className: c(), children: o }),
+                r && /* @__PURE__ */ e("span", { className: n(), children: r })
+              ]
+            }
+          ),
+          /* @__PURE__ */ e("div", { className: i(), "data-dd-privacy": "mask", children: /* @__PURE__ */ e("div", { className: l() }) })
+        ] })
+      }
+    ) : /* @__PURE__ */ a(
+      b,
       {
-        ...n,
-        ref: s,
-        className: l(),
-        isDisabled: a,
+        ...p,
+        ref: u,
+        className: t(),
+        isDisabled: d,
         children: [
-          /* @__PURE__ */ e("div", { className: i(), "data-dd-privacy": "mask", children: /* @__PURE__ */ e("div", { className: y() }) }),
-          /* @__PURE__ */ o(
+          /* @__PURE__ */ e("div", { className: i(), "data-dd-privacy": "mask", children: /* @__PURE__ */ e("div", { className: l() }) }),
+          /* @__PURE__ */ a(
             "div",
             {
-              className: c({
-                className: u ? "uy:sr-only" : ""
+              className: y({
+                className: s ? "uy:sr-only" : ""
               }),
               "data-dd-privacy": "allow",
               children: [
-                /* @__PURE__ */ e("span", { className: p(), children: d }),
-                r && /* @__PURE__ */ e("span", { className: b(), children: r })
+                /* @__PURE__ */ e("span", { className: c(), children: o }),
+                r && /* @__PURE__ */ e("span", { className: n(), children: r })
               ]
             }
           )
@@ -74,8 +113,8 @@ const v = g({
     );
   }
 );
-h.displayName = "ToggleSwitch";
+N.displayName = "ToggleSwitch";
 export {
-  h as ToggleSwitch,
-  v as toggleSwitch
+  N as ToggleSwitch,
+  x as toggleSwitch
 };

package/dist/esm/components/toggle-switch-field/TanstackToggleSwitchField.d.ts

@@ -0,0 +1,11 @@
+import { TanstackToggleSwitchProps } from '../toggle-switch/TanstackToggleSwitch.js';
+export interface TanstackToggleSwitchFieldProps extends TanstackToggleSwitchProps {
+    /** The label for the toggle switch. */
+    label: string;
+    /** Helper text to display below the toggle switch label. */
+    switchHelperText?: string;
+    /** Whether the label is only visible to screen readers. */
+    isLabelSrOnly?: boolean;
+}
+declare const TanstackToggleSwitchField: import('react').ForwardRefExoticComponent<Omit<TanstackToggleSwitchFieldProps, "ref"> & import('react').RefAttributes<HTMLLabelElement>>;
+export { TanstackToggleSwitchField };

package/dist/esm/components/toggle-switch-field/TanstackToggleSwitchField.js

@@ -0,0 +1,34 @@
+import { jsxs as i, jsx as o } from "react/jsx-runtime";
+import { forwardRef as n } from "react";
+import { TanstackFormFeedbackText as s } from "../form-field/parts/TanstackFormFeedbackText.js";
+import { TanstackFormField as l } from "../form-field/TanstackFormField.js";
+import { TanstackToggleSwitch as T } from "../toggle-switch/TanstackToggleSwitch.js";
+function p({
+  label: t,
+  switchHelperText: r,
+  isDisabled: e,
+  isReadOnly: m,
+  isLabelSrOnly: c
+}, a) {
+  return /* @__PURE__ */ i(l, { children: [
+    /* @__PURE__ */ o(
+      T,
+      {
+        ref: a,
+        label: t,
+        helperText: r,
+        isLabelSrOnly: c,
+        ...{
+          isDisabled: e,
+          isReadOnly: m
+        }
+      }
+    ),
+    /* @__PURE__ */ o(s, {})
+  ] });
+}
+const d = n(p);
+d.displayName = "TanstackToggleSwitchField";
+export {
+  d as TanstackToggleSwitchField
+};

package/dist/esm/components/toggle-switch-field/ToggleSwitchField.d.ts

@@ -63,6 +63,8 @@ type ToggleSwitchFieldComponent = (<TSchema extends Schema>(props: ToggleSwitchF
  * [API](/?path=/docs/forms-toggleswitchfield--docs) • [Demo](/?path=/story/forms-toggleswitchfield--primary)
  * @note The schema type parameter is needed to ensure type safety with the form's schema.
  * If you omit it, the `name` prop will not be type-safe.
+ * @deprecated React Hook Form components are deprecated. Use the TanStack Form version instead.
+ * @see Storybook docs: https://unity-components.payfit.io/?path=/docs/forms-introduction-to-unity-forms--docs
  */
 declare const ToggleSwitchField: ToggleSwitchFieldComponent;
 export { ToggleSwitchField };

package/dist/esm/components/toggle-switch-group/TanstackToggleSwitchGroup.d.ts

@@ -0,0 +1,57 @@
+import { ToggleSwitchGroupProps } from './ToggleSwitchGroup.js';
+export type TanstackToggleSwitchGroupProps = Omit<ToggleSwitchGroupProps, 'value' | 'defaultValue' | 'isInvalid' | 'feedbackText'>;
+/**
+ * TanStack‑controlled group component for multiple `ToggleSwitch` children.
+ *
+ * `TanstackToggleSwitchGroup` wraps `ToggleSwitchGroup` and binds its value
+ * (a `string[]`) to the TanStack field context via `useFieldContext`. The
+ * selection state is fully driven by the form — do not pass `value` or
+ * `defaultValue` directly.
+ *
+ * Behavior:
+ * - The value comes from `field.state.value` (string[]), defaulting to `[]`.
+ * - Changes are propagated via `field.handleChange` and forwarded to `onChange`.
+ * - The invalid state (`isInvalid`) is derived from `field.state.meta`
+ *   (`isTouched` && `!isValid`).
+ *
+ * Accessibility:
+ * - The group handles its own label and `helperText`.
+ * - For error feedback coming from the form, use the dedicated Field variant
+ *   (`TanstackToggleSwitchGroupField`).
+ *
+ * Usage constraints:
+ * - Must be rendered inside `<form.AppField name="…">`.
+ * - Pre‑fill via `useTanstackUnityForm({ defaultValues: { … } })`.
+ *
+ * Example:
+ * ```tsx
+ * const form = useTanstackUnityForm({
+ *   validators: { onBlur: z.object({ pref: z.array(z.string()).optional() }) },
+ *   defaultValues: { pref: ['email'] },
+ * })
+ *
+ * return (
+ *   <form.AppForm>
+ *     <form.Form>
+ *       <form.AppField name="pref">
+ *         {() => (
+ *           <TanstackToggleSwitchGroup label="Notifications">
+ *             <ToggleSwitch value="email" label="Email" />
+ *             <ToggleSwitch value="sms" label="SMS" />
+ *             <ToggleSwitch value="push" label="Push" />
+ *           </TanstackToggleSwitchGroup>
+ *         )}
+ *       </form.AppField>
+ *     </form.Form>
+ *   </form.AppForm>
+ * )
+ * ```
+ * @public
+ * @see ToggleSwitchGroup
+ * @see useFieldContext
+ * @remarks The `value`, `defaultValue`, `isInvalid`, and `feedbackText` props are handled by the TanStack integration and therefore omitted.
+ * @param props Group props (excluding `value`, `defaultValue`, `isInvalid`, `feedbackText`).
+ * @returns A form‑controlled `fieldset` containing the child switches.
+ */
+declare const TanstackToggleSwitchGroup: import('react').ForwardRefExoticComponent<TanstackToggleSwitchGroupProps & import('react').RefAttributes<HTMLFieldSetElement>>;
+export { TanstackToggleSwitchGroup };

package/dist/esm/components/toggle-switch-group/TanstackToggleSwitchGroup.js

@@ -0,0 +1,23 @@
+import { jsx as l } from "react/jsx-runtime";
+import { forwardRef as n } from "react";
+import { useFieldContext as c } from "../../hooks/tanstack-form-context.js";
+import { ToggleSwitchGroup as u } from "./ToggleSwitchGroup.js";
+const m = n(function({ onChange: a, ...e }, r) {
+  const t = c(), i = Array.isArray(t.state.value) ? t.state.value : [], s = t.state.meta.isTouched && !t.state.meta.isValid;
+  return /* @__PURE__ */ l(
+    u,
+    {
+      ...e,
+      ref: r,
+      value: i,
+      isInvalid: s,
+      onChange: (o) => {
+        t.handleChange(o), a?.(o);
+      }
+    }
+  );
+});
+m.displayName = "TanstackToggleSwitchGroup";
+export {
+  m as TanstackToggleSwitchGroup
+};

package/dist/esm/components/toggle-switch-group/ToggleSwitchGroup.js

@@ -69,7 +69,7 @@ const Y = q(
         onFocus: x,
         onBlur: D,
         children: [
-          /* @__PURE__ */ t("legend", { className: "uy:mb-50", children: /* @__PURE__ */ t(U, { isRequired: y, requiredVariant: R, children: i }) }),
+          /* @__PURE__ */ t("legend", { className: "uy:mb-25", children: /* @__PURE__ */ t(U, { isRequired: y, requiredVariant: R, children: i }) }),
           o && /* @__PURE__ */ t(
             j,
             {

package/dist/esm/components/toggle-switch-group-field/TanstackToggleSwitchGroupField.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { TanstackToggleSwitchGroupProps } from '../toggle-switch-group/TanstackToggleSwitchGroup.js';
+export interface TanstackToggleSwitchGroupFieldProps extends TanstackToggleSwitchGroupProps {
+    /** Helper text to display below the group. */
+    helperText?: ReactNode;
+    /** Optional content displayed under the whole field (not the group). */
+    contextualLink?: ReactNode;
+    children: ReactNode;
+}
+/**
+ * Composite TanStack field for a group of toggle switches.
+ *
+ * `TanstackToggleSwitchGroupField` assembles a complete field using
+ * `TanstackFormField`, the TanStack‑controlled `TanstackToggleSwitchGroup`,
+ * and the feedback area. Render it inside `<form.AppField name="…">` to bind
+ * to the form state and validation.
+ */
+declare const TanstackToggleSwitchGroupField: import('react').ForwardRefExoticComponent<TanstackToggleSwitchGroupFieldProps & import('react').RefAttributes<HTMLFieldSetElement>>;
+export { TanstackToggleSwitchGroupField };

package/dist/esm/components/toggle-switch-group-field/TanstackToggleSwitchGroupField.js

@@ -0,0 +1,50 @@
+import { jsxs as g, jsx as o } from "react/jsx-runtime";
+import { forwardRef as k } from "react";
+import { TanstackFormFeedbackText as F } from "../form-field/parts/TanstackFormFeedbackText.js";
+import { TanstackFormField as u } from "../form-field/TanstackFormField.js";
+import { TanstackToggleSwitchGroup as h } from "../toggle-switch-group/TanstackToggleSwitchGroup.js";
+function w({
+  label: r,
+  helperText: t,
+  isDisabled: m,
+  isReadOnly: c,
+  isRequired: a,
+  requiredVariant: e,
+  contextualLink: i,
+  children: n,
+  onFocus: p,
+  onBlur: s,
+  onFocusChange: l,
+  onChange: T,
+  ...d
+}, f) {
+  return /* @__PURE__ */ g(u, { children: [
+    /* @__PURE__ */ o(
+      h,
+      {
+        ref: f,
+        label: r,
+        helperText: t,
+        isRequired: a,
+        requiredVariant: e,
+        onFocus: p,
+        onBlur: s,
+        onFocusChange: l,
+        onChange: T,
+        ...{
+          isDisabled: m,
+          isReadOnly: c
+        },
+        ...d,
+        children: n
+      }
+    ),
+    /* @__PURE__ */ o(F, {}),
+    i
+  ] });
+}
+const x = k(w);
+x.displayName = "TanstackToggleSwitchGroupField";
+export {
+  x as TanstackToggleSwitchGroupField
+};

package/dist/esm/components/toggle-switch-group-field/ToggleSwitchGroupField.d.ts

@@ -77,6 +77,8 @@ type ToggleSwitchGroupFieldComponent = (<TSchema extends Schema>(props: ToggleSw
  * [API](/?path=/docs/forms-toggleswitchgroupfield--docs) • [Demo](/?path=/story/forms-toggleswitchgroupfield--primary)
  * @note The schema type parameter is needed to ensure type safety with the form's schema.
  * If you omit it, the `name` prop will not be type-safe.
+ * @deprecated React Hook Form components are deprecated. Use the TanStack Form version instead.
+ * @see Storybook docs: https://unity-components.payfit.io/?path=/docs/forms-introduction-to-unity-forms--docs
  */
 declare const ToggleSwitchGroupField: ToggleSwitchGroupFieldComponent;
 export { ToggleSwitchGroupField };

package/dist/esm/docs/{table → examples/data}/mocks/employee-columns.d.ts

@@ -1,3 +1,3 @@
-import { Employee } from '../../../mocks/employees.js';
+import { Employee } from '../../../../mocks/employees.js';
 export declare const employeeColumns: (import('@tanstack/table-core').AccessorKeyColumnDefBase<Employee, string> & Partial<import('@tanstack/table-core').IdIdentifier<Employee, string>>)[];
 export declare const employeeColumnsWithCheckbox: ((import('@tanstack/table-core').AccessorKeyColumnDefBase<Employee, string> & Partial<import('@tanstack/table-core').IdIdentifier<Employee, string>>) | import('@tanstack/table-core').DisplayColumnDef<Employee, unknown>)[];

package/dist/esm/hooks/tanstack-form-context.d.ts

@@ -0,0 +1 @@
+export declare const fieldContext: import('react').Context<import('@tanstack/react-form').AnyFieldApi>, formContext: import('react').Context<import('@tanstack/react-form').AnyFormApi>, useFieldContext: <TData>() => import('@tanstack/react-form').FieldApi<any, string, TData, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any, any>, useFormContext: () => import('@tanstack/react-form').ReactFormExtendedApi<Record<string, never>, any, any, any, any, any, any, any, any, any, any, any>;

package/dist/esm/hooks/tanstack-form-context.js

@@ -0,0 +1,8 @@
+import { createFormHookContexts as o } from "@tanstack/react-form";
+const { fieldContext: e, formContext: r, useFieldContext: n, useFormContext: x } = o();
+export {
+  e as fieldContext,
+  r as formContext,
+  n as useFieldContext,
+  x as useFormContext
+};

package/dist/esm/hooks/use-container-query-level.d.ts

@@ -0,0 +1,42 @@
+export type ContainerQueryLevel = 'component' | 'section' | 'page' | 'app';
+interface UseContainerQueryLevelOptions {
+    /**
+     * The ref to the container element to observe
+     */
+    ref: React.RefObject<HTMLElement | null>;
+}
+interface UseContainerQueryLevelReturn {
+    /**
+     * The current container query level based on the container width
+     */
+    level: ContainerQueryLevel;
+    /**
+     * The current width of the observed container
+     */
+    width: number;
+}
+/**
+ * Hook that determines the current container query level based on container width.
+ *
+ * This hook uses ResizeObserver to monitor the width of a container element and
+ * determines which container query level it falls into based on Unity's container
+ * breakpoints from design tokens. Breakpoints are automatically synced with Unity's
+ * design system: component (< 703px), section (703-1062px), page (1063-1438px), app (≥ 1439px).
+ * @param options Configuration options containing the ref to observe
+ * @returns Object containing the current level and width
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const containerRef = useRef<HTMLDivElement>(null)
+ *   const { level, width } = useContainerQueryLevel({ ref: containerRef })
+ *
+ *   return (
+ *     <div ref={containerRef}>
+ *       Current level: {level} (width: {width}px)
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export declare function useContainerQueryLevel(options: UseContainerQueryLevelOptions): UseContainerQueryLevelReturn;
+export {};

package/dist/esm/hooks/use-container-query-level.js

@@ -0,0 +1,33 @@
+import s from "@payfit/unity-themes/tokens/sizes.json";
+import { useResizeObserver as c } from "usehooks-ts";
+const i = () => {
+  const n = s.container, o = {
+    section: parseInt(n.section.$value.replace("px", ""), 10),
+    page: parseInt(n.page.$value.replace("px", ""), 10),
+    app: parseInt(n.app.$value.replace("px", ""), 10)
+  };
+  if (typeof window > "u")
+    return o;
+  const r = getComputedStyle(document.documentElement), e = (t) => {
+    const p = r.getPropertyValue(`--uy-container-${t}`), a = parseInt(p.replace("px", ""), 10);
+    return isNaN(a) ? o[t] : a;
+  };
+  return {
+    section: e("section"),
+    page: e("page"),
+    app: e("app")
+  };
+};
+function d(n) {
+  const { ref: o } = n, e = c({
+    ref: o,
+    box: "border-box"
+  }).width ?? 0, t = i();
+  return {
+    level: e >= t.app ? "app" : e >= t.page ? "page" : e >= t.section ? "section" : "component",
+    width: e
+  };
+}
+export {
+  d as useContainerQueryLevel
+};

package/dist/esm/hooks/use-form.d.ts

@@ -44,5 +44,7 @@ export type UseUnityFormReturn<TSchema extends Schema> = {
  * ```
  * @remarks
  * [API]() • [Demo]()
+ * @deprecated React Hook Form components are deprecated. Use the TanStack Form version instead.
+ * @see Storybook docs: https://unity-components.payfit.io/?path=/docs/forms-introduction-to-unity-forms--docs
  */
 export declare function useUnityForm<TSchema extends Schema>(schema: TSchema, options?: Omit<UseHookFormProps<StandardSchemaV1.InferInput<TSchema>, any, StandardSchemaV1.InferOutput<TSchema>>, 'resolver'>): UseUnityFormReturn<TSchema>;

package/dist/esm/hooks/use-has-scroll.d.ts

@@ -0,0 +1,71 @@
+import { RefObject } from 'react';
+import { ScrollDetectionResult, ScrollDetectionStrategy } from '../utils/scroll-detection.js';
+/**
+ * Configuration options for the useHasScroll hook
+ */
+export interface UseHasScrollOptions {
+    /**
+     * Detection strategy to use:
+     * - 'size': Compare scrollHeight/scrollWidth vs clientHeight/clientWidth (default)
+     *   Use when you need to detect actual scrollable content
+     * - 'style': Check computed overflow styles (overflow, overflowX, overflowY)
+     *   Use when you need to check if element is configured for scrolling
+     * - 'both': Element must satisfy both size and style conditions
+     *   Use for strict validation that element both has overflow style AND exceeds bounds
+     * @default 'size'
+     */
+    strategy?: ScrollDetectionStrategy;
+    /**
+     * Debounce delay in milliseconds for scroll detection updates
+     * Higher values improve performance but reduce responsiveness
+     * Set to 0 to disable debouncing
+     * @default 100
+     */
+    debounceMs?: number;
+    /**
+     * Watch for DOM mutations (content changes) in the element
+     * Disable for static content to improve performance
+     * @default true
+     */
+    watchMutations?: boolean;
+    /**
+     * Watch for element resize events
+     * Disable if element size is fixed to improve performance
+     * @default true
+     */
+    watchResize?: boolean;
+}
+/**
+ * React hook to detect if an element has scrollable content
+ * This hook monitors a DOM element and determines whether it has scrollable content
+ * using configurable detection strategies. It automatically updates when the element's
+ * size changes or its content is modified.
+ * @param {RefObject<HTMLElement>} ref - React ref to the element to monitor
+ * @param {UseHasScrollOptions} options - Configuration options
+ * @returns {ScrollDetectionResult} Current scroll detection state
+ * @example
+ * ```tsx
+ * // Basic usage with default size-based detection
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { hasVerticalScroll } = useHasScroll(containerRef);
+ * ```
+ * @example
+ * ```tsx
+ * // Style-based detection
+ * const { hasVerticalScroll } = useHasScroll(containerRef, { strategy: 'style' });
+ * ```
+ * @example
+ * ```tsx
+ * // Strict detection with both methods
+ * const { hasVerticalScroll } = useHasScroll(containerRef, { strategy: 'both' });
+ * ```
+ * @example
+ * ```tsx
+ * // Performance optimized for static content
+ * const scrollState = useHasScroll(containerRef, {
+ *   watchMutations: false,
+ *   debounceMs: 0
+ * });
+ * ```
+ */
+export declare function useHasScroll(ref: RefObject<HTMLElement>, options?: UseHasScrollOptions): ScrollDetectionResult;

package/dist/esm/hooks/use-has-scroll.js

@@ -0,0 +1,75 @@
+import { useState as p, useCallback as z, useLayoutEffect as F, useEffect as y } from "react";
+import { detectScroll as A } from "../utils/scroll-detection.js";
+function E(r, b = {}) {
+  const {
+    strategy: a = "size",
+    debounceMs: u = 100,
+    watchMutations: i = !0,
+    watchResize: m = !0
+  } = b, [d, v] = p({
+    hasVerticalScroll: !1,
+    hasHorizontalScroll: !1,
+    hasAnyScroll: !1,
+    detectionMethod: {
+      size: { vertical: !1, horizontal: !1 },
+      style: { vertical: !1, horizontal: !1 }
+    }
+  }), e = z(() => {
+    const s = r.current;
+    if (!s)
+      return;
+    const o = A(s, a);
+    v(o);
+  }, [r, a]);
+  return F(() => {
+    if (!r.current) return;
+    e();
+    const o = requestAnimationFrame(() => {
+      e();
+    });
+    return () => {
+      cancelAnimationFrame(o);
+    };
+  }, [e]), y(() => {
+    let s = !0, o;
+    const S = () => {
+      const n = r.current;
+      if (!n) return;
+      let c;
+      const h = () => {
+        clearTimeout(c), c = setTimeout(e, u);
+      };
+      e(), requestAnimationFrame(() => {
+        e();
+      });
+      const l = [];
+      if (m) {
+        const t = new ResizeObserver(h);
+        t.observe(n), l.push(t);
+      }
+      if (i) {
+        const t = new MutationObserver(h);
+        t.observe(n, {
+          childList: !0,
+          subtree: !0,
+          characterData: !0,
+          attributes: !0,
+          attributeFilter: ["style", "class"]
+        }), l.push(t);
+      }
+      o = () => {
+        clearTimeout(c), l.forEach((t) => {
+          t.disconnect();
+        });
+      };
+    }, f = () => {
+      s && (r.current ? S() : requestAnimationFrame(f));
+    };
+    return f(), () => {
+      s = !1, o?.();
+    };
+  }, [r, e, u, m, i]), d;
+}
+export {
+  E as useHasScroll
+};