@payfit/unity-components
Version:
82 lines (81 loc) • 3.81 kB
TypeScript
import { ReactNode } from 'react';
import { LabelProps } from '../label/Label.js';
import { TanstackSelectableButtonGroupProps } from '../selectable-button-group/TanstackSelectableButtonGroup.js';
export type TanstackSelectableButtonGroupFieldProps = TanstackSelectableButtonGroupProps & Pick<LabelProps, 'isRequired' | 'requiredVariant'> & {
/** The label for the selectable button group field. */
label: string;
/** Helper text to display below the selectable button group field. */
helperText?: ReactNode;
/** A contextual link to display below the selectable button group field. */
contextualLink?: ReactNode;
/** The SelectableButton components to render within the group. */
children: ReactNode;
};
/**
* The `TanstackSelectableButtonGroupField` component renders a full field (label, selectable button group)
* wired to the TanStack Form context. It manages state and accessibility via the
* context provided by `useTanstackUnityForm` and `<form.AppField name="…">`.
*
* Behavior:
* - Renders `TanstackSelectableButtonGroup` with its children.
* - Displays the label (`TanstackFormLabel`), helper text (`TanstackFormHelperText`),
* feedback messages (`TanstackFormFeedbackText`), and an optional contextual link.
*
* Accessibility:
* - Automatically wires `aria-labelledby`, `aria-describedby` (helper/feedback), and
* `aria-details` using identifiers from the `a11y` context.
*
* Key props:
* - `label: string` — label text.
* - `selectionMode?: "single" | "multiple"` — determines how many options can be selected.
* - `helperText?: ReactNode` — helper text displayed below the field.
* - `contextualLink?: ReactNode` — optional contextual link, referenced via `aria-details`.
* - Inherits props from `TanstackSelectableButtonGroup`.
* - `isRequired?`, `requiredVariant?` — control the required indicator in the label.
*
* Example:
* ```tsx
* import { useTanstackUnityForm } from "@payfit/unity-components"
* import { SelectableButton } from "@payfit/unity-components"
*
* function Example() {
* const schema = z.object({
* choice: z.array(z.string()).min(1, { message: 'Select at least one option' })
* })
*
* const form = useTanstackUnityForm<{ choice: string[] }>({ validators: {
* onBlur: schema,
* } })
* return (
* <form.AppForm>
* <form.AppField name="choice">
* {(field) => (
* <field.SelectableButtonGroup
* label="Choose your preferences"
* helperText="Select one or more options"
* selectionMode="multiple"
* >
* <SelectableButton value="option1">Option 1</SelectableButton>
* <SelectableButton value="option2">Option 2</SelectableButton>
* </field.SelectableButtonGroup>
* )}
* </form.AppField>
* </form.AppForm>
* )
* }
* ```
* @remarks Migration from `SelectableButtonGroupField` (non‑TanStack):
* - Do not pass a `name` prop to the field: use `<form.AppField name="…">`.
* - `value`, `defaultValue`, and `isInvalid` are derived from the TanStack form context.
*/
declare const TanstackSelectableButtonGroupField: import('react').ForwardRefExoticComponent<TanstackSelectableButtonGroupProps & Pick<LabelProps, "isRequired" | "requiredVariant"> & {
/** The label for the selectable button group field. */
label: string;
/** Helper text to display below the selectable button group field. */
helperText?: ReactNode;
/** A contextual link to display below the selectable button group field. */
contextualLink?: ReactNode;
/** The SelectableButton components to render within the group. */
children: ReactNode;
} & import('react').RefAttributes<HTMLDivElement>>;
export { TanstackSelectableButtonGroupField };