@payfit/unity-components 2.46.13 → 2.46.14

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

@@ -0,0 +1,109 @@
+import { jsxs as k, jsx as t } from "react/jsx-runtime";
+import { forwardRef as q, useState as z, useId as A, useRef as H, useCallback as J, isValidElement as B, cloneElement as w, Children as K } from "react";
+import { uyTv as Q } from "@payfit/unity-themes";
+import { Label as U } from "../label/Label.js";
+import { Text as j } from "../text/Text.js";
+const W = Q({
+  base: "uy:flex uy:flex-col uy:gap-50"
+});
+function X(i) {
+  if (!B(i)) return !1;
+  const o = i.props;
+  return typeof o == "object" && o !== null && "value" in o && typeof o.value == "string";
+}
+const Y = q(
+  ({
+    label: i,
+    helperText: o,
+    feedbackText: r,
+    isDisabled: f,
+    isReadOnly: E,
+    isInvalid: a,
+    isRequired: y,
+    children: N,
+    requiredVariant: R,
+    value: m,
+    defaultValue: V,
+    onChange: g,
+    onFocus: C,
+    onBlur: G,
+    onFocusChange: h,
+    ...I
+  }, F) => {
+    const c = m !== void 0, [M, O] = z(
+      V ?? []
+    ), n = c ? m : M, v = A(), b = o ? `${v}-helper` : void 0, d = a && r ? `${v}-feedback` : void 0, $ = [b, d].filter(Boolean).join(" ") || void 0, S = H(!1), x = (e) => {
+      S.current = !0, C?.(e), h?.(!0);
+    }, D = (e) => {
+      S.current = !1, G?.(e), h?.(!1);
+    }, L = J(
+      (e) => {
+        let l;
+        n.includes(e) ? l = n.filter((s) => s !== e) : l = [...n, e], c || O(l), g?.(l);
+      },
+      [n, c, g]
+    ), P = () => K.map(N, (e, l) => {
+      if (!X(e)) return e;
+      const s = e, u = s.props, p = u.value;
+      return w(s, {
+        key: s.key ?? l,
+        isSelected: n.includes(p),
+        isDisabled: f ?? u.isDisabled,
+        isReadOnly: E ?? u.isReadOnly,
+        value: p,
+        onChange: () => {
+          L(p);
+        }
+      });
+    });
+    return /* @__PURE__ */ k(
+      "fieldset",
+      {
+        ...I,
+        ref: F,
+        className: W(),
+        "aria-describedby": $,
+        "aria-invalid": a || void 0,
+        "aria-required": y || void 0,
+        disabled: f,
+        onFocus: x,
+        onBlur: D,
+        children: [
+          /* @__PURE__ */ t("legend", { className: "uy:mb-25", children: /* @__PURE__ */ t(U, { isRequired: y, requiredVariant: R, children: i }) }),
+          o && /* @__PURE__ */ t(
+            j,
+            {
+              id: b,
+              variant: "bodySmall",
+              color: "content.neutral.low",
+              slot: "description",
+              children: o
+            }
+          ),
+          /* @__PURE__ */ t("div", { className: "uy:mt-100 uy:flex uy:flex-col uy:gap-150 uy:py-25", children: P() }),
+          a && r && (typeof r == "string" ? /* @__PURE__ */ t(
+            j,
+            {
+              id: d,
+              variant: "bodySmallStrong",
+              color: "content.form.invalid",
+              slot: "errorMessage",
+              children: r
+            }
+          ) : B(r) && w(
+            r,
+            {
+              id: d,
+              slot: "errorMessage"
+            }
+          ))
+        ]
+      }
+    );
+  }
+);
+Y.displayName = "ToggleSwitchGroup";
+export {
+  Y as ToggleSwitchGroup,
+  W as toggleSwitchGroup
+};

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

@@ -0,0 +1,84 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+import { ForwardedRef, JSX, PropsWithChildren, ReactNode } from 'react';
+import { FieldPath, FieldValues } from 'react-hook-form';
+import { Schema } from '../../hooks/use-form.types.js';
+import { LabelProps } from '../label/Label.js';
+import { ToggleSwitchGroupProps } from '../toggle-switch-group/ToggleSwitchGroup.js';
+interface FieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> extends PropsWithChildren<Pick<LabelProps, 'isRequired' | 'requiredVariant'>> {
+    /** The name of the field, which should match the form schema. */
+    name: TName;
+    /** The label for the toggle switch group. */
+    label: string;
+    /** Helper text to display below the toggle switch group. */
+    helperText?: ReactNode;
+    /** A contextual link to display below the toggle switch group. */
+    contextualLink?: ReactNode;
+    /** The default selected values of the toggle switch group. */
+    defaultValue?: string[];
+    /** Whether the toggle switch group is disabled. */
+    isDisabled?: boolean;
+    /** Whether the toggle switch group is read-only. */
+    isReadOnly?: boolean;
+    /** Whether the toggle switch group is invalid. */
+    isInvalid?: boolean;
+    /** Whether the toggle switch group is loading. */
+    isLoading?: boolean;
+    /** Callback when the selection changes. */
+    onChange?: (value: string[]) => void;
+    /** Handler called when the group receives focus. */
+    onFocus?: ToggleSwitchGroupProps['onFocus'];
+    /** Handler called when the group loses focus. */
+    onBlur?: ToggleSwitchGroupProps['onBlur'];
+    /** Handler that is called when the element's focus status changes. */
+    onFocusChange?: (isFocused: boolean) => void;
+}
+export type ToggleSwitchGroupFieldProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = FieldProps<TFieldValues, TName>;
+type ToggleSwitchGroupFieldComponent = (<TSchema extends Schema>(props: ToggleSwitchGroupFieldProps<StandardSchemaV1.InferOutput<TSchema>> & {
+    ref?: ForwardedRef<HTMLFieldSetElement>;
+}) => JSX.Element) & {
+    displayName?: string;
+};
+/**
+ * The `ToggleSwitchGroupField` component renders a group of related toggle switches that can be used in forms.
+ * It combines the functionality of ToggleSwitchGroup with form integration capabilities, providing
+ * automatic form state management, validation, and error handling.
+ *
+ * The component is ideal for collecting multiple binary preferences or settings within a form context,
+ * such as notification preferences or feature toggles.
+ * @param {ToggleSwitchGroupFieldProps} props - Props for the ToggleSwitchGroupField component
+ * @example
+ * ```tsx
+ * import { useUnityForm, ToggleSwitchGroupField, ToggleSwitch } from '@payfit/unity-components'
+ * import * as z from 'zod'
+ *
+ * function Example() {
+ *   const schema = z.object({
+ *     preferences: z.array(z.string())
+ *   })
+ *
+ *   const { Form } = useUnityForm(schema)
+ *
+ *   return (
+ *     <Form action={handleSubmit}>
+ *       <ToggleSwitchGroupField<typeof schema>
+ *         name="preferences"
+ *         label="Select your preferences"
+ *         helperText="Choose all that apply"
+ *       >
+ *         <ToggleSwitch value="email" label="Email notifications" />
+ *         <ToggleSwitch value="sms" label="SMS notifications" />
+ *       </ToggleSwitchGroupField>
+ *     </Form>
+ *   )
+ * }
+ * ```
+ * @see {@link ToggleSwitchGroupFieldProps} for all available props
+ * @remarks
+ * [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/components/toggle-switch-group-field/ToggleSwitchGroupField.js

@@ -0,0 +1,63 @@
+import { jsxs as T, jsx as i } from "react/jsx-runtime";
+import { forwardRef as x, useMemo as G } from "react";
+import { useFormContext as R } from "react-hook-form";
+import { createSchemaAdapter as q } from "../../utils/createSchemaAdapter.js";
+import { FormField as y } from "../form-field/FormField.js";
+import { FormControl as P } from "../form-field/parts/FormControl.js";
+import { FormFeedbackText as j } from "../form-field/parts/FormFeedbackText.js";
+import { isFieldRequired as v } from "../form-field/utils/isFieldRequired.js";
+import { useUnityFormProvider as C } from "../form/Form.context.js";
+import { ToggleSwitchGroup as U } from "../toggle-switch-group/ToggleSwitchGroup.js";
+function b({
+  name: o,
+  label: r,
+  defaultValue: e,
+  helperText: m,
+  contextualLink: c,
+  isRequired: p,
+  isInvalid: s,
+  isLoading: l,
+  isDisabled: n,
+  isReadOnly: d,
+  requiredVariant: u,
+  children: f,
+  ...F
+}, h) {
+  const { control: g, watch: a } = R(), { schema: t } = C(), w = G(
+    () => v(q(t), o),
+    [t, o]
+  ), S = a(o);
+  return /* @__PURE__ */ T(y, { control: g, name: o, ...{
+    isInvalid: s,
+    isLoading: l,
+    isDisabled: n,
+    isReadOnly: d
+  }, children: [
+    /* @__PURE__ */ i(P, { children: /* @__PURE__ */ i(
+      U,
+      {
+        ref: h,
+        label: r,
+        defaultValue: e,
+        value: S,
+        helperText: m,
+        requiredVariant: u,
+        ...F,
+        isRequired: w ?? p,
+        children: f
+      }
+    ) }),
+    /* @__PURE__ */ i(j, {}),
+    c
+  ] });
+}
+const k = x(function(r, e) {
+  return b(
+    r,
+    e
+  );
+});
+k.displayName = "ToggleSwitchGroupField";
+export {
+  k as ToggleSwitchGroupField
+};

package/dist/esm/components/tooltip/Tooltip.d.ts

@@ -0,0 +1,10 @@
+import { ReactElement } from 'react';
+export interface TooltipProps {
+    /** The content displayed in the tooltip. */
+    title: string;
+    /** The trigger element that displays the tooltip. */
+    children: ReactElement;
+    /** The duration of delay/close delay for the tooltip. */
+    duration?: 'short' | 'standard' | 'long' | 'very-long';
+}
+export declare const Tooltip: import('react').ForwardRefExoticComponent<TooltipProps & import('react').RefAttributes<HTMLDivElement>>;

package/dist/esm/components/tooltip/Tooltip.js

@@ -0,0 +1,31 @@
+import { jsxs as y, jsx as r } from "react/jsx-runtime";
+import { forwardRef as n } from "react";
+import { Button as p } from "react-aria-components/Button";
+import { TooltipTrigger as u, Tooltip as i } from "react-aria-components/Tooltip";
+import { Button as d } from "../button/Button.js";
+const m = (o) => o.type === d || o.type === p, c = {
+  short: [100, 150],
+  standard: [150, 200],
+  long: [200, 300],
+  "very-long": [300, 400]
+}, T = n(
+  ({ title: o, children: t, duration: a = "standard" }, e) => {
+    const [l, s] = c[a];
+    return /* @__PURE__ */ y(u, { delay: l, closeDelay: s, children: [
+      t,
+      /* @__PURE__ */ r(
+        i,
+        {
+          ref: e,
+          "data-dd-privacy": "allow",
+          offset: m(t) ? 6 : 8,
+          className: "uy:inline-flex uy:rounded-50 uy:pl-100 uy:pr-100 uy:pt-50 uy:pb-50 uy:bg-grayscale-l12 uy:max-w-[300px] uy:shadow-100",
+          children: /* @__PURE__ */ r("p", { className: "uy:typography-body-small uy:text-content-inverted uy:overflow-hidden uy:text-ellipsis uy:line-clamp-3", children: o })
+        }
+      )
+    ] });
+  }
+);
+export {
+  T as Tooltip
+};

package/dist/esm/components/tooltip/figma/Tooltip.figma.d.ts

@@ -0,0 +1,7 @@
+import { default as figma } from 'figma';
+declare const _default: {
+    example: figma.TemplateStringResult;
+    imports: string[];
+    id: string;
+};
+export default _default;

package/dist/esm/docs/blocks/Cards.d.ts

@@ -0,0 +1,18 @@
+import { default as React, PropsWithChildren } from 'react';
+type CardProps = React.PropsWithChildren;
+export declare const Card: React.FC<CardProps>;
+export declare const CardWithCover: React.FC<CardProps & {
+    coverSrc: string;
+    coverAlt: string;
+}>;
+export declare const CardHeader: React.FC<PropsWithChildren>;
+export declare const CardTitle: React.FC<PropsWithChildren>;
+export declare const CardContent: React.FC<PropsWithChildren>;
+export declare const CardActions: React.FC<PropsWithChildren>;
+export declare const Link: React.FC<PropsWithChildren<React.ComponentProps<'a'>>>;
+type CardGridProps = {
+    children: React.ReactNode;
+    cols?: number;
+};
+export declare const CardGrid: React.FC<CardGridProps>;
+export {};

package/dist/esm/docs/examples/data/mocks/employee-columns.d.ts

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

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

@@ -0,0 +1 @@
+export declare const fieldContext: import('react').Context<import('@tanstack/form-core').AnyFieldApi>, formContext: import('react').Context<import('@tanstack/form-core').AnyFormApi>, useFieldContext: <TData>() => import('@tanstack/form-core').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/tanstack-form-default-values.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Mirrors a form submit value shape while allowing each nested value to be
+ * initialized with `undefined`.
+ *
+ * TanStack Form `defaultValues` often describe an incomplete form state: a
+ * field can start empty even when the validated submit payload requires it.
+ * This type keeps the submit schema as the source of truth while making those
+ * empty initial field values type-safe.
+ */
+type DeepAllowUndefined<T> = T extends Array<infer Item> ? Array<DeepAllowUndefined<Item>> | undefined : T extends object ? {
+    [K in keyof T]: DeepAllowUndefined<T[K]> | undefined;
+} : T | undefined;
+/**
+ * Makes one path required again after `DeepAllowUndefined` allowed `undefined`
+ * throughout the value shape.
+ *
+ * Paths are expressed as tuples of object keys. Use `number` to target every
+ * item in an array, for example `['answers', number, 'questionId']`.
+ */
+type KeepRequiredAtPath<T, Path extends readonly unknown[]> = Path extends [] ? Exclude<T, undefined> : T extends Array<infer Item> ? Path extends [number, ...infer Rest extends readonly unknown[]] ? Array<KeepRequiredAtPath<Item, Rest>> : T : Path extends [
+    infer Key extends keyof T,
+    ...infer Rest extends readonly unknown[]
+] ? Omit<T, Key> & {
+    [K in Key]-?: KeepRequiredAtPath<Exclude<T[Key], undefined>, Rest>;
+} : T;
+/**
+ * Applies `KeepRequiredAtPath` to several paths.
+ *
+ * This is useful when some containers or technical identifiers must always be
+ * present in `defaultValues`, while regular user-input fields can still start
+ * as `undefined`.
+ */
+type KeepRequiredAtPaths<T, Paths extends ReadonlyArray<readonly unknown[]>> = Paths extends readonly [
+    infer Path extends readonly unknown[],
+    ...infer Rest extends ReadonlyArray<readonly unknown[]>
+] ? KeepRequiredAtPaths<KeepRequiredAtPath<T, Path>, Rest> : T;
+/**
+ * Helper type for TanStack Form `defaultValues`.
+ *
+ * It starts from the final submit values, allows `undefined` throughout the
+ * default form state, then re-requires the paths listed in `RequiredPaths`.
+ *
+ * We created it to avoid maintaining a separate default-values type or using
+ * unsafe casts when default values are intentionally less complete than the
+ * validated submit payload.
+ */
+export type TanstackFormDefaultValues<SubmitValues, RequiredPaths extends ReadonlyArray<readonly unknown[]> = []> = KeepRequiredAtPaths<DeepAllowUndefined<SubmitValues>, RequiredPaths>;
+/**
+ * Runtime no-op used to type-check TanStack Form default values.
+ *
+ * The function returns the provided value unchanged. Its purpose is to make
+ * object literals satisfy `TanstackFormDefaultValues` at compile time while
+ * keeping call sites compact.
+ */
+export declare function tanstackFormDefaultValues<SubmitValues, RequiredPaths extends ReadonlyArray<readonly unknown[]> = []>(value: TanstackFormDefaultValues<SubmitValues, RequiredPaths>): KeepRequiredAtPaths<DeepAllowUndefined<SubmitValues>, RequiredPaths>;
+export {};

package/dist/esm/hooks/tanstack-form-default-values.js

@@ -0,0 +1,6 @@
+function a(t) {
+  return t;
+}
+export {
+  a as tanstackFormDefaultValues
+};

package/dist/esm/hooks/use-async-list.d.ts

@@ -0,0 +1,2 @@
+import { useAsyncList } from 'react-stately/useAsyncList';
+export { useAsyncList };

package/dist/esm/hooks/use-breakpoint-listener.d.ts

@@ -0,0 +1,36 @@
+export type Breakpoint = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export declare function useBreakpointListener(): Breakpoint;
+/**
+ * Desktop breakpoints (md, lg, xl)
+ */
+export declare const DESKTOP_BREAKPOINTS: readonly ["md", "lg", "xl"];
+/**
+ * Mobile breakpoints (xs, sm)
+ */
+export declare const MOBILE_BREAKPOINTS: readonly ["xs", "sm"];
+/**
+ * Desktop breakpoint type
+ */
+export type DesktopBreakpoint = (typeof DESKTOP_BREAKPOINTS)[number];
+/**
+ * Mobile breakpoint type
+ */
+export type MobileBreakpoint = (typeof MOBILE_BREAKPOINTS)[number];
+/**
+ * Type guard to check if a breakpoint is a desktop breakpoint (md, lg, xl)
+ * @example
+ * const breakpoint = useBreakpointListener()
+ * if (isDesktopBreakpoint(breakpoint)) {
+ *   // Desktop layout
+ * }
+ */
+export declare const isDesktopBreakpoint: (breakpoint: Breakpoint) => breakpoint is DesktopBreakpoint;
+/**
+ * Type guard to check if a breakpoint is a mobile breakpoint (xs, sm)
+ * @example
+ * const breakpoint = useBreakpointListener()
+ * if (isMobileBreakpoint(breakpoint)) {
+ *   // Mobile layout
+ * }
+ */
+export declare const isMobileBreakpoint: (breakpoint: Breakpoint) => breakpoint is MobileBreakpoint;

package/dist/esm/hooks/use-breakpoint-listener.js

@@ -0,0 +1,26 @@
+import { useMediaQuery as n } from "./use-media-query.js";
+const i = (e) => {
+  const t = getComputedStyle(document.documentElement).getPropertyValue(
+    `--uy-breakpoint-${e}`
+  );
+  return parseInt(t.replace("px", ""), 10);
+}, r = (e) => `(min-width: ${i(e)}px)`;
+function a() {
+  const e = n(r("xl")), t = n(r("lg")), s = n(r("md")), o = n(r("sm"));
+  return e ? "xl" : t ? "lg" : s ? "md" : o ? "sm" : "xs";
+}
+const u = [
+  "md",
+  "lg",
+  "xl"
+], c = [
+  "xs",
+  "sm"
+], m = (e) => u.includes(e), p = (e) => c.includes(e);
+export {
+  u as DESKTOP_BREAKPOINTS,
+  c as MOBILE_BREAKPOINTS,
+  m as isDesktopBreakpoint,
+  p as isMobileBreakpoint,
+  a as useBreakpointListener
+};

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/common/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
+};