@payfit/unity-components
Version:
114 lines (113 loc) • 5.62 kB
TypeScript
import { ReactNode } from 'react';
import { LabelProps } from '../label/Label.js';
import { PasswordInputProps } from './parts/PasswordInput.js';
import { PasswordRule } from './types.js';
export interface TanstackPasswordFieldProps extends Omit<PasswordInputProps, 'name' | 'value' | 'defaultValue' | 'isInvalid'>, Pick<LabelProps, 'isRequired' | 'requiredVariant'> {
/** Label for the password field */
label: string;
/** Helper text below the label */
helperText?: ReactNode;
/** Title for the validation rules section (default: "Your password must have:") */
rulesTitle?: ReactNode;
/** Array of password rules to display - status is controlled by consumer */
rules?: PasswordRule[];
/** A contextual link to display below the text field. */
contextualLink?: ReactNode;
/** Callback function to be called when the clear button is pressed */
onClearButtonPress?: () => void;
}
/**
* The `TanstackPasswordField` component provides a complete password input solution with visibility toggle,
* validation rules display, and caps lock detection, fully integrated with TanStack Form.
*
* Use this component to collect password input with real-time validation feedback. The component displays
* a list of password requirements that update dynamically as users type, helping them create passwords
* that meet your security criteria.
*
* The component acts as a **presentation layer only**. Define all validation logic externally using
* TanStack Form validators, then pass the evaluated rule statuses to the component for display.
*
* **Key features:**
* - Password visibility toggle for showing/hiding entered text
* - Real-time validation rules display with checked/unchecked visual feedback
* - Caps Lock warning indicator to prevent accidental input mistakes
* - Full accessibility support with ARIA labels and keyboard navigation
* - Integration with TanStack Form for validation and state management
* - Contextual link support for "Forgot password?" or similar actions
*
* **Important props:**
* - `label` — Required text label for the field
* - `rules` — Array of password rules with their validation status (you control the logic)
* - `helperText` — Optional helper text displayed below the label
* - `rulesTitle` — Custom title for the rules section (defaults to "Your password must have:")
* - `showCapsLockWarning` — Enable/disable caps lock detection (default: true)
* - `autoComplete` — Browser autocomplete hint: 'current-password' or 'new-password'
* - `contextualLink` — Optional link element (e.g., "Forgot password?")
* @param {TanstackPasswordFieldProps} props - Component properties
* @example
* ```tsx
* import { useTanstackUnityForm, fieldRevalidateLogic } from '@payfit/unity-components'
* import { z } from 'zod'
*
* function PasswordForm() {
* const ruleDefs = [
* {
* id: 'length',
* label: 'At least 10 characters',
* validate: (value: string) => value.length >= 10
* }
* ]
*
* const form = useTanstackUnityForm({
* defaultValues: { password: '' },
* validationLogic: fieldRevalidateLogic({
* whenPristine: 'blur',
* whenDirty: 'change',
* fields: ['password'],
* })
* })
*
* return (
* <form.AppForm>
* <form.Form>
* <form.AppField name="password">
* {(field) => {
* const rules = ruleDefs.map(rule => ({
* id: rule.id,
* label: rule.label,
* status: rule.validate(field.state.value) ? 'checked' : 'unchecked'
* }))
*
* return (
* <field.PasswordField
* label="Create Password"
* rules={rules}
* isRequired
* />
* )
* }}
* </form.AppField>
* </form.Form>
* </form.AppForm>
* )
* }
* ```
* @remarks
* - Access the component via `<field.PasswordField>` within `<form.AppField name="...">` scope
* - Do not pass `name`, `value`, or `isInvalid` props — these are managed by TanStack Form context
* - The `rules` prop is purely presentational — compute rule statuses in your component and pass them in
* - For async validation (e.g., checking password breaches), use TanStack Form's `onDynamicAsync` validator
* - Use `autoComplete="current-password"` for login forms and `autoComplete="new-password"` for registration
* - **New to password fields?** See the step-by-step tutorial in the developer docs
* - **Want to understand the architecture?** Read the validation guide in the developer docs
* @see {@link TanstackPasswordFieldProps} for all available props
* @see {@link useTanstackUnityForm} for form setup and validation
* @see Tutorial: Adding Password Field with Validation in the developer docs
* @see Guide: Understanding Password Field Validation in the developer docs
* @see Source code in {@link https://github.com/PayFit/hr-apps/tree/master/libs/shared/unity/components/src/components/password-field GitHub}
* @see Design specs in {@link https://www.figma.com/design/poaMyU7abAgL9VRhx4ygyy/Unity-DS-%3E-Components-Library Figma}
* @see Design docs at {@link https://www.payfit.design/ Payfit.design}
* @see Developer docs at {@link https://unity-components.payfit.io/?path=/docs/forms-reference-passwordfield--docs unity-components.payfit.io}
*/
declare const TanstackPasswordField: import('react').ForwardRefExoticComponent<TanstackPasswordFieldProps & import('react').RefAttributes<HTMLInputElement>>;
export { TanstackPasswordField };