@payfit/unity-components 1.2.0 → 2.1.4

package/dist/esm/components/card/parts/CardContent.d.ts

@@ -0,0 +1,37 @@
+import { PropsWithChildren } from 'react';
+export interface CardContentProps extends PropsWithChildren {
+    /** Additional CSS classes to apply to the content container */
+    className?: string;
+}
+/**
+ * The `CardContent` component provides a container for the main content within a Card.
+ * It ensures consistent spacing and layout for card content.
+ *
+ * Use CardContent to wrap the main body of your card content. This is optional but provides
+ * better semantic structure and consistent styling.
+ * @param {CardContentProps} props - The props for the `CardContent` component
+ * @example
+ * ```tsx
+ * import { Card, CardTitle, CardContent } from '@payfit/unity-components'
+ *
+ * function Example() {
+ *   return (
+ *     <Card>
+ *       <CardTitle>My Card</CardTitle>
+ *       <CardContent>
+ *         <p>This is the main content of the card.</p>
+ *       </CardContent>
+ *     </Card>
+ *   )
+ * }
+ * ```
+ * @see {@link CardContentProps} for all available props
+ * @remarks
+ * - CardContent is optional but recommended for better structure
+ * - You can also place content directly in the Card without CardContent
+ */
+declare function CardContent({ children, className }: CardContentProps): import("react/jsx-runtime").JSX.Element;
+declare namespace CardContent {
+    var displayName: string;
+}
+export { CardContent };

package/dist/esm/components/card/parts/CardContent.js

@@ -0,0 +1,8 @@
+import { jsx as o } from "react/jsx-runtime";
+function r({ children: t, className: n }) {
+  return /* @__PURE__ */ o("div", { className: n, "data-unity-slot": "card.content", children: t });
+}
+r.displayName = "CardContent";
+export {
+  r as CardContent
+};

package/dist/esm/components/card/parts/CardTitle.d.ts

@@ -0,0 +1,55 @@
+import { PropsWithChildren } from 'react';
+export interface CardTitleProps extends PropsWithChildren {
+    /** The heading level for the title. Defaults to 3 */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Whether to visually hide the title (still accessible to screen readers) */
+    isHidden?: boolean;
+}
+/**
+ * The `CardTitle` component renders the title for a Card. It provides semantic heading structure
+ * and ensures proper accessibility labeling for the Card container.
+ *
+ * Use CardTitle when you need to give your Card a visible or screen-reader-accessible title.
+ * You can configure the heading level, apply custom styles, or hide it visually while maintaining
+ * accessibility.
+ * @param {CardTitleProps} props - The props for the `CardTitle` component
+ * @example
+ * ```tsx
+ * import { Card, CardTitle } from '@payfit/unity-components'
+ *
+ * function Example() {
+ *   return (
+ *     <Card>
+ *       <CardTitle>My Card Title</CardTitle>
+ *       <p>Card content goes here</p>
+ *     </Card>
+ *   )
+ * }
+ * ```
+ * @example
+ * ```tsx
+ * // Custom heading level
+ * <Card>
+ *   <CardTitle level={2}>Important Section</CardTitle>
+ *   <p>Content...</p>
+ * </Card>
+ * ```
+ * @example
+ * ```tsx
+ * // Hidden title for accessibility
+ * <Card>
+ *   <CardTitle isHidden>Screen reader only title</CardTitle>
+ *   <p>Visual content that describes itself</p>
+ * </Card>
+ * ```
+ * @see {@link CardTitleProps} for all available props
+ * @remarks
+ * - The title is required for accessibility unless the Card has an `aria-label`
+ * - Use `isHidden` to hide the title visually while keeping it accessible
+ * - The default heading level is 3, but you can configure it based on your page structure
+ */
+declare function CardTitle({ children, level, isHidden }: CardTitleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace CardTitle {
+    var displayName: string;
+}
+export { CardTitle };

package/dist/esm/components/card/parts/CardTitle.js

@@ -0,0 +1,33 @@
+import { jsx as s } from "react/jsx-runtime";
+import { uyTv as n } from "@payfit/unity-themes";
+import { Heading as o } from "react-aria-components";
+import { useCardContext as d } from "../Card.context.js";
+const l = n({
+  base: ["uy:typography-h3 uy:text-content-neutral uy:leading-none"],
+  variants: {
+    isHidden: {
+      true: "uy:sr-only",
+      false: ""
+    }
+  },
+  defaultVariants: {
+    isHidden: !1
+  }
+});
+function u({ children: t, level: e = 3, isHidden: a = !1 }) {
+  const { titleId: r } = d(), i = l({ isHidden: a });
+  return /* @__PURE__ */ s(
+    o,
+    {
+      level: e,
+      id: r,
+      className: i,
+      "data-unity-slot": "card.title",
+      children: t
+    }
+  );
+}
+u.displayName = "CardTitle";
+export {
+  u as CardTitle
+};

package/dist/esm/components/checkbox/Checkbox.js

@@ -1,12 +1,12 @@
-import { jsxs as o, jsx as a, Fragment as j } from "react/jsx-runtime";
-import { forwardRef as B, isValidElement as p, cloneElement as y } from "react";
+import { jsxs as l, jsx as a, Fragment as j } from "react/jsx-runtime";
+import { forwardRef as B, isValidElement as h, cloneElement as f } from "react";
 import { useId as R } from "react-aria";
 import { Checkbox as D } from "react-aria-components";
-import { Text as h } from "../text/Text.js";
+import { Text as u } from "../text/Text.js";
 import { checkbox as E } from "./Checkbox.variants.js";
 import { CheckboxIndicator as V } from "./parts/CheckboxIndicator.js";
 const F = B(
-  ({ children: f, helperText: i, feedbackText: r, ...l }, v) => {
+  ({ children: v, helperText: i, feedbackText: r, ...o }, N) => {
     const e = R(), {
       isDisabled: s,
       isReadOnly: d,
@@ -14,70 +14,78 @@ const F = B(
       isRequired: n,
       requiredVariant: c = "required",
       ...x
-    } = l, {
-      base: u,
-      wrapper: N,
-      asterisk: g,
-      optionalTag: $,
-      descriptionsContainer: k,
-      helperText: C,
-      feedbackText: q
+    } = o, {
+      base: g,
+      wrapper: $,
+      asterisk: k,
+      optionalTag: C,
+      descriptionsContainer: q,
+      helperText: m,
+      feedbackText: b
     } = E({
       isDisabled: s,
       isReadOnly: d,
       isInvalid: t
-    }), m = [l["aria-labelledby"], `${e}-label`].filter(Boolean), b = [
-      l["aria-describedby"],
+    }), y = [o["aria-labelledby"], `${e}-label`].filter(Boolean), p = [
+      o["aria-describedby"],
       typeof i == "string" ? `${e}-helper-text` : void 0,
       typeof r == "string" ? `${e}-feedback-text` : void 0
-    ].filter(Boolean), w = m.length > 0 ? m.join(" ") : void 0, I = b.length > 0 ? b.join(" ") : void 0;
-    return /* @__PURE__ */ o("div", { className: u(), children: [
+    ].filter(Boolean), w = y.length > 0 ? y.join(" ") : void 0, I = p.length > 0 ? p.join(" ") : void 0;
+    return /* @__PURE__ */ l("div", { className: g(), children: [
       /* @__PURE__ */ a(
         D,
         {
           ...x,
           isInvalid: t,
-          ref: v,
-          className: N(),
+          ref: N,
+          className: $(),
           "aria-labelledby": w,
           "aria-describedby": I,
           isDisabled: s,
           isReadOnly: d,
-          children: (S) => /* @__PURE__ */ o(j, { children: [
-            /* @__PURE__ */ a(V, { ...S, className: "uy:mr-[6px]" }),
-            /* @__PURE__ */ a("span", { id: `${e}-label`, "data-dd-privacy": "allow", children: f }),
-            c === "required" && n && /* @__PURE__ */ o("span", { className: g(), children: [
+          children: (S) => /* @__PURE__ */ l(j, { children: [
+            /* @__PURE__ */ a(
+              V,
+              {
+                ...S,
+                className: "uy:mt-50 uy:sm:mt-25 uy:ml-0"
+              }
+            ),
+            /* @__PURE__ */ a("span", { id: `${e}-label`, "data-dd-privacy": "allow", children: v }),
+            c === "required" && n && /* @__PURE__ */ l("span", { className: k(), children: [
               "*",
               /* @__PURE__ */ a("span", { className: "uy:sr-only", children: "required" })
             ] }),
-            c === "optional" && !n && /* @__PURE__ */ a("span", { className: $(), children: "(optional)" })
+            c === "optional" && !n && /* @__PURE__ */ a("span", { className: C(), children: "(optional)" })
           ] })
         }
       ),
-      (i || r) && /* @__PURE__ */ o("div", { className: k(), "data-dd-privacy": "allow", children: [
+      (i || r) && /* @__PURE__ */ l("div", { className: q(), "data-dd-privacy": "allow", children: [
         typeof i == "string" ? /* @__PURE__ */ a(
-          h,
+          u,
           {
             variant: "bodySmall",
             color: "content.neutral.low",
             id: `${e}-helper-text`,
+            className: m(),
             children: i
           }
-        ) : p(i) && y(i, {
+        ) : h(i) && f(i, {
           "data-id": `${e}-helper-text`,
-          className: C()
+          className: m()
         }),
         t && (typeof r == "string" ? /* @__PURE__ */ a(
-          h,
+          u,
           {
             variant: "bodySmallStrong",
             color: "content.form.invalid",
             id: `${e}-feedback-text`,
+            className: b(),
             children: r
           }
-        ) : p(r) && y(r, {
+        ) : h(r) && f(r, {
           "data-id": `${e}-feedback-text`,
-          className: q()
+          className: b()
         }))
       ] })
     ] });

package/dist/esm/components/checkbox/Checkbox.variants.d.ts

@@ -13,12 +13,12 @@ export declare const checkbox: import('tailwind-variants').TVReturnType<{
         };
     };
 }, {
-    base: string;
-    wrapper: string;
+    base: string[];
+    wrapper: string[];
     asterisk: string;
     optionalTag: string;
     descriptionsContainer: string;
-    helperText: string;
+    helperText: string[];
     feedbackText: string;
 }, undefined, {
     isDisabled: {
@@ -35,12 +35,12 @@ export declare const checkbox: import('tailwind-variants').TVReturnType<{
         };
     };
 }, {
-    base: string;
-    wrapper: string;
+    base: string[];
+    wrapper: string[];
     asterisk: string;
     optionalTag: string;
     descriptionsContainer: string;
-    helperText: string;
+    helperText: string[];
     feedbackText: string;
 }, import('tailwind-variants').TVReturnType<{
     isDisabled: {
@@ -57,11 +57,11 @@ export declare const checkbox: import('tailwind-variants').TVReturnType<{
         };
     };
 }, {
-    base: string;
-    wrapper: string;
+    base: string[];
+    wrapper: string[];
     asterisk: string;
     optionalTag: string;
     descriptionsContainer: string;
-    helperText: string;
+    helperText: string[];
     feedbackText: string;
 }, undefined, unknown, unknown, undefined>>;

package/dist/esm/components/checkbox/Checkbox.variants.js

@@ -1,13 +1,29 @@
 import { uyTv as e } from "@payfit/unity-themes";
-const l = e({
+const r = e({
   slots: {
-    base: "uy:group uy:inline-flex uy:flex-col uy:gap-50 uy:py-[1px]",
-    wrapper: "uy:inline-flex uy:items-start uy:gap-[2px] uy:typography-body uy:text-content-form-enabled uy:data-[focus-visible]:outline uy:data-[focus-visible]:outline-[2px] uy:data-[focus-visible]:outline-utility-focus-ring uy:data-[focus-visible]:outline-offset-2 uy:rounded-25 uy:leading-[1lh] uy:data-[disabled]:text-content-form-disabled",
+    base: [
+      "uy:group uy:inline-flex uy:flex-col",
+      "uy:rounded-md uy:sm:rounded-25",
+      "uy:px-150 uy:sm:px-0 uy:py-125 uy:sm:py-px",
+      "uy:border uy:sm:border-none uy:border-solid uy:border-border-neutral-enabled",
+      'uy:has-data-[focus-visible="true"]:outline-2 uy:has-data-[focus-visible="true"]:outline-utility-focus-ring uy:has-data-[focus-visible="true"]:outline-offset-2',
+      "uy:has-data-[disabled=true]:border-border-neutral-disabled",
+      "uy:has-data-[readonly=true]:border-border-neutral-disabled"
+    ],
+    wrapper: [
+      "uy:sm:rounded-25 uy:leading-none uy:sm:leading-[1lh]",
+      "uy:inline-flex uy:items-start uy:gap-75",
+      "uy:typography-body uy:text-content-form-enabled",
+      "uy:data-[disabled=true]:text-content-form-disabled uy:data-[disabled]:cursor-not-allowed",
+      "uy:data-[readonly=true]:cursor-not-allowed"
+    ],
     asterisk: "uy:text-content-danger",
     optionalTag: "uy:typography-body uy:leading-1",
-    descriptionsContainer: "uy:ml-300 uy:leading-1 uy:inline-flex uy:flex-col uy:gap-50",
-    helperText: "uy:typography-body-small uy:text-content-neutral-low",
-    feedbackText: "uy:typography-body-small-strong uy:text-content-form-invalid"
+    descriptionsContainer: "uy:ml-300 uy:leading-1 uy:inline-flex uy:flex-col",
+    helperText: [
+      "uy:block uy:typography-body-small uy:text-content-neutral-low uy:mt-50"
+    ],
+    feedbackText: "uy:typography-body-small-strong uy:text-content-form-invalid uy:mt-50"
   },
   variants: {
     isDisabled: {
@@ -61,5 +77,5 @@ const l = e({
   ]
 });
 export {
-  l as checkbox
+  r as checkbox
 };

package/dist/esm/components/checkbox/TanstackCheckbox.d.ts

@@ -0,0 +1,28 @@
+import { CheckboxProps } from './Checkbox.js';
+export type TanstackCheckboxProps = Omit<CheckboxProps, 'name' | 'selected' | 'defaultSelected' | 'isInvalid'>;
+/**
+ * `TanstackCheckbox` is a controlled checkbox wired to the TanStack Form field context.
+ * It is based on the Unity `Checkbox` component.
+ *
+ * Value, invalid state, and events are driven by the TanStack field API.
+ *
+ * Example:
+ * ```tsx
+ * function ExampleField() {
+ *   const form = useTanstackUnityForm<{ acceptTerms: boolean }>({ validators: {} })
+ *   return (
+ *     <form>
+ *       <form.AppField name="acceptTerms">
+ *         {() => (
+ *           <TanstackCheckbox>
+ *             I accept the terms and conditions
+ *           </TanstackCheckbox>
+ *         )}
+ *       </form.AppField>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+declare const TanstackCheckbox: import('react').ForwardRefExoticComponent<TanstackCheckboxProps & import('react').RefAttributes<HTMLLabelElement>>;
+export { TanstackCheckbox };

package/dist/esm/components/checkbox/TanstackCheckbox.js

@@ -0,0 +1,51 @@
+import { jsx as p } from "react/jsx-runtime";
+import { forwardRef as u } from "react";
+import { useFieldContext as k } from "../../hooks/tanstack-form-context.js";
+import { useFieldA11yContext as C } from "../form-field/TanstackFormField.context.js";
+import { Checkbox as y } from "./Checkbox.js";
+const I = u(
+  ({
+    children: i,
+    value: r,
+    isIndeterminate: d,
+    onBlur: n,
+    onChange: l,
+    isReadOnly: s,
+    isDisabled: c,
+    isRequired: m,
+    requiredVariant: b,
+    ...f
+  }, h) => {
+    const e = k(), a = C(), x = e.state.meta.isTouched && !e.state.meta.isValid, t = [a.helperTextId, a.feedbackTextId].filter(Boolean).join(" ");
+    return /* @__PURE__ */ p(
+      y,
+      {
+        ...f,
+        id: a.inputId,
+        ref: h,
+        value: r,
+        isSelected: e.state.value,
+        isIndeterminate: d,
+        requiredVariant: b,
+        isRequired: m,
+        onChange: (o) => {
+          e.handleChange(o), l?.(o);
+        },
+        onBlur: () => {
+          e.handleBlur(), n?.();
+        },
+        isReadOnly: s,
+        isDisabled: c,
+        isInvalid: x,
+        "aria-labelledby": a.labelId,
+        "aria-describedby": t.length > 0 ? t : void 0,
+        "aria-details": a.contextualLinkId,
+        children: i
+      }
+    );
+  }
+);
+I.displayName = "TanstackCheckbox";
+export {
+  I as TanstackCheckbox
+};

package/dist/esm/components/checkbox/parts/CheckboxIndicator.js

@@ -12,7 +12,7 @@ const c = u({
   variants: {
     isSelected: {
       true: {
-        base: "uy:border-border-form-active uy:bg-surface-form-active"
+        base: "uy:border-border-form-selected uy:bg-surface-form-active uy:hover:border-border-form-active"
       }
     },
     isDisabled: {
@@ -85,8 +85,8 @@ const c = u({
       isSelected: !0,
       isReadOnly: !0,
       className: {
-        base: "uy:bg-surface-form-disabled! uy:border-border-form-disabled",
-        checkmark: "uy:text-border-form-read-only"
+        base: "uy:bg-surface-form-disabled! uy:border-border-form-disabled!",
+        checkmark: "uy:text-surface-form-read-only!"
       }
     }
   ]
@@ -96,16 +96,16 @@ function n({
   isDisabled: s,
   isIndeterminate: a,
   isInvalid: t,
-  isReadOnly: d,
-  className: o
+  isReadOnly: o,
+  className: d
 }) {
   const { base: i, checkmark: l } = c({
     isSelected: r || a,
     isDisabled: s,
     isInvalid: t,
-    isReadOnly: d
+    isReadOnly: o
   });
-  return /* @__PURE__ */ e("div", { className: i({ className: o }), "data-dd-privacy": "mask", children: /* @__PURE__ */ e(
+  return /* @__PURE__ */ e("div", { className: i({ className: d }), "data-dd-privacy": "mask", children: /* @__PURE__ */ e(
     "svg",
     {
       fill: "none",

package/dist/esm/components/checkbox-field/CheckboxField.d.ts

@@ -69,6 +69,8 @@ type CheckboxFieldComponent = (<TSchema extends Schema>(props: CheckboxFieldProp
  * @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 CheckboxField: CheckboxFieldComponent;
 export { CheckboxField };

package/dist/esm/components/checkbox-field/TanstackCheckboxField.d.ts

@@ -0,0 +1,14 @@
+import { ReactNode } from 'react';
+import { TanstackCheckboxProps } from '../checkbox/TanstackCheckbox.js';
+import { LabelProps } from '../label/Label.js';
+export interface FieldProps extends Pick<LabelProps, 'isRequired' | 'requiredVariant'> {
+    /** The label for the checkbox. */
+    children: ReactNode;
+    /** Helper text to display below the checkbox. */
+    helperText?: ReactNode;
+    /** A contextual link to display below the checkbox. */
+    contextualLink?: ReactNode;
+}
+export type TanstackCheckboxFieldProps = FieldProps & TanstackCheckboxProps;
+declare const TanstackCheckboxField: import('react').ForwardRefExoticComponent<FieldProps & TanstackCheckboxProps & import('react').RefAttributes<HTMLLabelElement>>;
+export { TanstackCheckboxField };

package/dist/esm/components/checkbox-field/TanstackCheckboxField.js

@@ -0,0 +1,40 @@
+import { jsxs as n, jsx as e } from "react/jsx-runtime";
+import { forwardRef as f } from "react";
+import { TanstackCheckbox as x } from "../checkbox/TanstackCheckbox.js";
+import { TanstackFormFeedbackText as p } from "../form-field/parts/TanstackFormFeedbackText.js";
+import { TanstackFormField as l } from "../form-field/TanstackFormField.js";
+function F({
+  children: o,
+  helperText: r,
+  contextualLink: i,
+  isRequired: t,
+  isDisabled: a,
+  isReadOnly: c,
+  requiredVariant: m,
+  value: s,
+  ...d
+}, k) {
+  return /* @__PURE__ */ n(l, { children: [
+    /* @__PURE__ */ e(
+      x,
+      {
+        ref: k,
+        value: s,
+        requiredVariant: m,
+        helperText: r,
+        feedbackText: /* @__PURE__ */ e(p, {}),
+        ...d,
+        isDisabled: a,
+        isReadOnly: c,
+        isRequired: t,
+        children: o
+      }
+    ),
+    i
+  ] });
+}
+const T = f(F);
+T.displayName = "TanstackCheckboxField";
+export {
+  T as TanstackCheckboxField
+};

package/dist/esm/components/checkbox-group/TanstackCheckboxGroup.d.ts

@@ -0,0 +1,4 @@
+import { CheckboxGroupProps } from './CheckboxGroup.js';
+export type TanstackCheckboxGroupProps = Omit<CheckboxGroupProps, 'name' | 'value' | 'defaultValue' | 'isInvalid'>;
+declare const TanstackCheckboxGroup: import('react').ForwardRefExoticComponent<TanstackCheckboxGroupProps & import('react').RefAttributes<HTMLDivElement>>;
+export { TanstackCheckboxGroup };

package/dist/esm/components/checkbox-group/TanstackCheckboxGroup.js

@@ -0,0 +1,37 @@
+import { jsx as u } from "react/jsx-runtime";
+import { forwardRef as b } from "react";
+import { useFieldContext as f } from "../../hooks/tanstack-form-context.js";
+import { useFieldA11yContext as h } from "../form-field/TanstackFormField.context.js";
+import { CheckboxGroup as x } from "./CheckboxGroup.js";
+const k = b(
+  ({ onChange: r, onBlur: i, isReadOnly: d, isDisabled: n, children: l, label: s, ...c }, m) => {
+    const e = f(), a = h(), p = e.state.meta.isTouched && !e.state.meta.isValid, o = [a.helperTextId, a.feedbackTextId].filter(Boolean).join(" ");
+    return /* @__PURE__ */ u(
+      x,
+      {
+        ...c,
+        ref: m,
+        id: a.inputId,
+        label: s,
+        value: e.state.value,
+        onChange: (t) => {
+          e.handleChange(t), r?.(t);
+        },
+        onBlur: (t) => {
+          e.handleBlur(), i?.(t);
+        },
+        isReadOnly: d,
+        isDisabled: n,
+        isInvalid: p,
+        "aria-labelledby": a.labelId,
+        "aria-describedby": o.length > 0 ? o : void 0,
+        "aria-details": a.contextualLinkId,
+        children: l
+      }
+    );
+  }
+);
+k.displayName = "TanstackCheckboxGroup";
+export {
+  k as TanstackCheckboxGroup
+};

package/dist/esm/components/checkbox-group-field/CheckboxGroupField.d.ts

@@ -74,6 +74,8 @@ type CheckboxGroupFieldComponent = (<TSchema extends Schema>(props: CheckboxGrou
  * ```
  * @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 CheckboxGroupField: CheckboxGroupFieldComponent;
 export { CheckboxGroupField };

package/dist/esm/components/checkbox-group-field/TanstackCheckGroupField.d.ts

@@ -0,0 +1,72 @@
+import { ReactNode } from 'react';
+import { TanstackCheckboxGroupProps } from '../checkbox-group/TanstackCheckboxGroup.js';
+import { LabelProps } from '../label/Label.js';
+export interface FieldProps extends Pick<LabelProps, 'isRequired' | 'requiredVariant'> {
+    /** Helper text to display below the group. */
+    helperText?: ReactNode;
+    /** A contextual link to display below the group. */
+    contextualLink?: ReactNode;
+}
+export type TanstackCheckGroupFieldProps = FieldProps & TanstackCheckboxGroupProps;
+/**
+ * `TanstackCheckGroupField` is a composite field for TanStack Form that renders a
+ * complete checkbox group (label, helper/error, group) and automatically connects to
+ * the field context provided by `useTanstackUnityForm` and `<form.AppField name="…">`.
+ *
+ * Behavior:
+ * - Group rendering: relies on `TanstackCheckboxGroup` to manage the value (array of
+ *   strings), focus, and events.
+ * - Messaging: renders helper text (`TanstackFormHelperText` via the `helperText` prop)
+ *   and error feedback (`TanstackFormFeedbackText`) according to the TanStack form state.
+ * - Contextual link: allows displaying an additional link below the field via the
+ *   `contextualLink` prop.
+ *
+ * Accessibility:
+ * - ARIA attributes (`aria-labelledby`, `aria-describedby`, `aria-details`) are wired by
+ *   `TanstackFormField` and its sub-parts to associate the label, helper, and feedback
+ *   with the control.
+ *
+ * Key props:
+ * - `label: string` — group label text.
+ * - `helperText?: ReactNode` — helper text displayed above the feedback.
+ * - `contextualLink?: ReactNode` — contextual link (referenced via `aria-details`).
+ * - Inherits the props from `TanstackCheckboxGroup` (except direct value management).
+ * - `isRequired?`, `requiredVariant?` — control how the required/optional indicator is displayed.
+ *
+ * Example:
+ * ```tsx
+ * import { TanstackCheckGroupField } from '@/components/checkbox-group-field/TanstackCheckGroupField'
+ * import { Checkbox } from '@/components/checkbox/Checkbox'
+ * import { useTanstackUnityForm } from '@/hooks/use-tanstack-form'
+ * import * as z from 'zod'
+ *
+ * const schema = z.object({
+ *   preferences: z.array(z.enum(['email','sms','push'])).min(1),
+ * })
+ *
+ * function Example() {
+ *   const form = useTanstackUnityForm({ validators: { onBlur: schema } })
+ *   return (
+ *     <form.AppForm>
+ *       <form.Form>
+ *         <form.AppField name="preferences">
+ *           {() => (
+ *             <TanstackCheckGroupField label="Preferences" helperText="Choose at least one option">
+ *               <Checkbox value="email">Email</Checkbox>
+ *               <Checkbox value="sms">SMS</Checkbox>
+ *               <Checkbox value="push">Push</Checkbox>
+ *             </TanstackCheckGroupField>
+ *           )}
+ *         </form.AppField>
+ *       </form.Form>
+ *     </form.AppForm>
+ *   )
+ * }
+ * ```
+ *
+ * Migration notes from a non‑TanStack field:
+ * - Do not pass a `name` prop to the component — use `<form.AppField name="…">`.
+ * - `value`, `defaultValue`, and `isInvalid` are derived from the TanStack context.
+ */
+declare const TanstackCheckGroupField: import('react').ForwardRefExoticComponent<FieldProps & TanstackCheckboxGroupProps & import('react').RefAttributes<HTMLDivElement>>;
+export { TanstackCheckGroupField };