@payfit/unity-components
Version:
85 lines (84 loc) • 4.16 kB
TypeScript
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 };