@ankhorage/zora 0.5.3 → 0.6.1

package/src/components/form/FormField.tsx

@@ -0,0 +1,128 @@
+import { Field, Stack, Text } from '@ankhorage/surface';
+import React from 'react';
+
+import { Input } from '../input';
+import type { FormFieldConfig, FormFieldControlProps, FormFieldProps } from './types';
+import { hasRequiredRule } from './validation';
+
+function isControlFieldProps<TName extends string>(
+  props: FormFieldProps<TName>,
+): props is FormFieldControlProps<TName> {
+  return 'field' in props;
+}
+
+function resolveKeyboardType(field: FormFieldConfig) {
+  if (field.keyboardType) {
+    return field.keyboardType;
+  }
+
+  if (field.type === 'email') {
+    return 'email-address';
+  }
+
+  if (field.type === 'number' || field.type === 'otp') {
+    return 'number-pad';
+  }
+
+  if (field.type === 'tel') {
+    return 'phone-pad';
+  }
+
+  if (field.type === 'url') {
+    return 'url';
+  }
+
+  return undefined;
+}
+
+function resolveAutoCapitalize(field: FormFieldConfig) {
+  if (field.autoCapitalize) {
+    return field.autoCapitalize;
+  }
+
+  if (['email', 'password', 'url'].includes(field.type ?? 'text')) {
+    return 'none';
+  }
+
+  return undefined;
+}
+
+function resolveTextContentType(field: FormFieldConfig) {
+  if (field.textContentType) {
+    return field.textContentType;
+  }
+
+  if (field.type === 'email') {
+    return 'emailAddress';
+  }
+
+  if (field.type === 'password') {
+    return 'password';
+  }
+
+  if (field.type === 'otp') {
+    return 'oneTimeCode';
+  }
+
+  return undefined;
+}
+
+function renderLabel(label: React.ReactNode, description: React.ReactNode | undefined) {
+  return (
+    <Stack gap="xs">
+      <Text variant="label" weight="semiBold">
+        {label}
+      </Text>
+      {description ? (
+        <Text tone="muted" variant="bodySmall">
+          {description}
+        </Text>
+      ) : null}
+    </Stack>
+  );
+}
+
+export function FormField<TName extends string = string>(props: FormFieldProps<TName>) {
+  if (!isControlFieldProps(props)) {
+    const { label, description, helperText, children, ...fieldProps } = props;
+
+    return (
+      <Field {...fieldProps} helperText={helperText} label={renderLabel(label, description)}>
+        {children}
+      </Field>
+    );
+  }
+
+  const { field, value, error, disabled = false, loading = false, onChange, testID } = props;
+  const fieldDisabled = disabled || loading || field.disabled;
+  const required = field.required ?? hasRequiredRule(field.rules);
+
+  return (
+    <Field
+      disabled={fieldDisabled}
+      errorText={error}
+      helperText={field.helperText}
+      invalid={Boolean(error)}
+      label={renderLabel(field.label, field.description)}
+      readOnly={field.readOnly}
+      required={required}
+      testID={testID ?? field.testID}
+    >
+      <Input
+        accessibilityLabel={typeof field.label === 'string' ? field.label : undefined}
+        autoCapitalize={resolveAutoCapitalize(field)}
+        autoComplete={field.autoComplete}
+        disabled={fieldDisabled}
+        invalid={Boolean(error)}
+        keyboardType={resolveKeyboardType(field)}
+        maxLength={field.maxLength}
+        onChangeText={(nextValue) => onChange(field.name, nextValue)}
+        placeholder={field.placeholder}
+        readOnly={field.readOnly}
+        secureTextEntry={field.secureTextEntry ?? field.type === 'password'}
+        textContentType={resolveTextContentType(field)}
+        value={value}
+      />
+    </Field>
+  );
+}

package/src/components/form/index.ts

@@ -0,0 +1,24 @@
+export { Form } from './Form';
+export { FormActions } from './FormActions';
+export { FormError } from './FormError';
+export { FormField } from './FormField';
+export type {
+  FormActionsProps,
+  FormErrorProps,
+  FormErrors,
+  FormFieldConfig,
+  FormFieldControlProps,
+  FormFieldInputType,
+  FormFieldProps,
+  FormFieldValue,
+  FormFieldWrapperProps,
+  FormProps,
+  FormValidationErrors,
+  FormValidationResult,
+  FormValues,
+  UseFormControllerOptions,
+  UseFormControllerResult,
+  ValidationRule,
+} from './types';
+export { useFormController } from './useFormController';
+export { hasRequiredRule, validateField, validateFields, validateValue } from './validation';

package/src/components/form/types.ts

@@ -0,0 +1,115 @@
+import type { FieldProps as SurfaceFieldProps } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { InputProps } from '../input';
+
+export type ValidationRule =
+  | { kind: 'required'; message?: string }
+  | { kind: 'email'; message?: string }
+  | { kind: 'minLength'; value: number; message?: string }
+  | { kind: 'pattern'; value: string; message?: string };
+
+export type FormFieldValue = string;
+export type FormValues<TName extends string = string> = Record<TName, FormFieldValue>;
+export type FormErrors<TName extends string = string> = Partial<Record<TName, React.ReactNode>>;
+export type FormValidationErrors<TName extends string = string> = Partial<Record<TName, string>>;
+
+export type FormFieldInputType = 'email' | 'number' | 'otp' | 'password' | 'tel' | 'text' | 'url';
+
+export interface FormFieldConfig<TName extends string = string> {
+  name: TName;
+  label: React.ReactNode;
+  description?: React.ReactNode;
+  helperText?: React.ReactNode;
+  type?: FormFieldInputType;
+  placeholder?: string;
+  rules?: readonly ValidationRule[];
+  autoCapitalize?: InputProps['autoCapitalize'];
+  autoComplete?: InputProps['autoComplete'];
+  keyboardType?: InputProps['keyboardType'];
+  maxLength?: InputProps['maxLength'];
+  readOnly?: boolean;
+  required?: boolean;
+  secureTextEntry?: boolean;
+  textContentType?: InputProps['textContentType'];
+  disabled?: boolean;
+  testID?: string;
+}
+
+export interface FormFieldWrapperProps extends Pick<
+  SurfaceFieldProps,
+  'children' | 'disabled' | 'errorText' | 'invalid' | 'readOnly' | 'required' | 'testID'
+> {
+  label: React.ReactNode;
+  description?: React.ReactNode;
+  helperText?: React.ReactNode;
+}
+
+export interface FormFieldControlProps<TName extends string = string> {
+  field: FormFieldConfig<TName>;
+  value: FormFieldValue;
+  onChange: (name: TName, value: FormFieldValue) => void;
+  error?: React.ReactNode;
+  disabled?: boolean;
+  loading?: boolean;
+  testID?: string;
+}
+
+export type FormFieldProps<TName extends string = string> =
+  | FormFieldControlProps<TName>
+  | FormFieldWrapperProps;
+
+export interface FormActionsProps {
+  submitLabel?: React.ReactNode;
+  loading?: boolean;
+  disabled?: boolean;
+  onSubmit?: () => void;
+  children?: React.ReactNode;
+  testID?: string;
+}
+
+export interface FormErrorProps {
+  error?: React.ReactNode;
+  testID?: string;
+}
+
+export interface FormProps<TName extends string = string> {
+  fields: readonly FormFieldConfig<TName>[];
+  values: FormValues<TName>;
+  onChange: (values: FormValues<TName>) => void;
+  onSubmit: (values: FormValues<TName>) => void | Promise<void>;
+  errors?: FormErrors<TName>;
+  error?: React.ReactNode;
+  loading?: boolean;
+  disabled?: boolean;
+  submitLabel?: React.ReactNode;
+  actions?: React.ReactNode;
+  footer?: React.ReactNode;
+  validateOnChange?: boolean;
+  testID?: string;
+}
+
+export interface FormValidationResult<TName extends string = string> {
+  errors: FormValidationErrors<TName>;
+  valid: boolean;
+}
+
+export interface UseFormControllerOptions<TName extends string = string> {
+  fields: readonly FormFieldConfig<TName>[];
+  initialValues?: Partial<FormValues<TName>>;
+  values?: FormValues<TName>;
+  errors?: FormErrors<TName>;
+  onChange?: (values: FormValues<TName>) => void;
+  onSubmit?: (values: FormValues<TName>) => void | Promise<void>;
+  validateOnChange?: boolean;
+}
+
+export interface UseFormControllerResult<TName extends string = string> {
+  values: FormValues<TName>;
+  errors: FormErrors<TName>;
+  setValues: (values: FormValues<TName>) => void;
+  setFieldValue: (name: TName, value: FormFieldValue) => void;
+  validate: () => FormValidationResult<TName>;
+  handleSubmit: () => Promise<void>;
+  reset: () => void;
+}

package/src/components/form/useFormController.ts

@@ -0,0 +1,105 @@
+import React from 'react';
+
+import type {
+  FormErrors,
+  FormValues,
+  UseFormControllerOptions,
+  UseFormControllerResult,
+} from './types';
+import { validateFields } from './validation';
+
+function createInitialValues<TName extends string>(
+  fields: readonly { name: TName }[],
+  initialValues: Partial<FormValues<TName>> | undefined,
+): FormValues<TName> {
+  const values = fields.reduce<Record<string, string>>((nextValues, field) => {
+    nextValues[field.name] = initialValues?.[field.name] ?? '';
+    return nextValues;
+  }, {});
+
+  return values as FormValues<TName>;
+}
+
+export function useFormController<TName extends string = string>({
+  fields,
+  initialValues,
+  values: controlledValues,
+  errors: externalErrors,
+  onChange,
+  onSubmit,
+  validateOnChange = false,
+}: UseFormControllerOptions<TName>): UseFormControllerResult<TName> {
+  const initialValuesRef = React.useRef(createInitialValues(fields, initialValues));
+  const [internalValues, setInternalValues] = React.useState<FormValues<TName>>(
+    initialValuesRef.current,
+  );
+  const [validationErrors, setValidationErrors] = React.useState<FormErrors<TName>>({});
+
+  const values = controlledValues ?? internalValues;
+  const errors = React.useMemo(
+    () => ({
+      ...validationErrors,
+      ...externalErrors,
+    }),
+    [externalErrors, validationErrors],
+  );
+
+  const setValues = React.useCallback(
+    (nextValues: FormValues<TName>) => {
+      if (!controlledValues) {
+        setInternalValues(nextValues);
+      }
+
+      onChange?.(nextValues);
+    },
+    [controlledValues, onChange],
+  );
+
+  const validate = React.useCallback(() => {
+    const result = validateFields(fields, values);
+    setValidationErrors(result.errors);
+    return result;
+  }, [fields, values]);
+
+  const setFieldValue = React.useCallback(
+    (name: TName, value: string) => {
+      const nextValues = {
+        ...values,
+        [name]: value,
+      };
+
+      setValues(nextValues);
+
+      if (validateOnChange) {
+        const result = validateFields(fields, nextValues);
+        setValidationErrors(result.errors);
+      }
+    },
+    [fields, setValues, validateOnChange, values],
+  );
+
+  const handleSubmit = React.useCallback(async () => {
+    const result = validate();
+
+    if (!result.valid) {
+      return;
+    }
+
+    await onSubmit?.(values);
+  }, [onSubmit, validate, values]);
+
+  const reset = React.useCallback(() => {
+    setValidationErrors({});
+    setValues(initialValuesRef.current);
+  }, [setValues]);
+
+  return {
+    values,
+    errors,
+    setValues,
+    setFieldValue,
+    validate,
+    handleSubmit,
+    reset,
+  };
+}

package/src/components/form/validation.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { FormFieldConfig, FormValues } from './types';
+import { validateFields, validateValue } from './validation';
+
+describe('form validation', () => {
+  test('validates required fields', () => {
+    expect(validateValue('', [{ kind: 'required' }])).toBe('This field is required.');
+    expect(validateValue('   ', [{ kind: 'required', message: 'Required' }])).toBe('Required');
+    expect(validateValue('value', [{ kind: 'required' }])).toBeUndefined();
+  });
+
+  test('validates email fields', () => {
+    expect(validateValue('not-email', [{ kind: 'email' }])).toBe('Enter a valid email address.');
+    expect(validateValue('person@example.com', [{ kind: 'email' }])).toBeUndefined();
+  });
+
+  test('validates minimum length fields', () => {
+    expect(validateValue('short', [{ kind: 'minLength', value: 8 }])).toBe(
+      'Enter at least 8 characters.',
+    );
+    expect(validateValue('long-enough', [{ kind: 'minLength', value: 8 }])).toBeUndefined();
+  });
+
+  test('validates pattern fields', () => {
+    expect(validateValue('abc', [{ kind: 'pattern', value: '^\\d+$' }])).toBe(
+      'Enter a valid value.',
+    );
+    expect(validateValue('123', [{ kind: 'pattern', value: '^\\d+$' }])).toBeUndefined();
+  });
+
+  test('returns the first failed rule per field', () => {
+    expect(validateValue('', [{ kind: 'required' }, { kind: 'email' }])).toBe(
+      'This field is required.',
+    );
+  });
+
+  test('validates multiple fields', () => {
+    type FieldName = 'email' | 'password';
+    const fields: readonly FormFieldConfig<FieldName>[] = [
+      {
+        name: 'email',
+        label: 'Email',
+        rules: [{ kind: 'required' }, { kind: 'email' }],
+      },
+      {
+        name: 'password',
+        label: 'Password',
+        rules: [{ kind: 'required' }, { kind: 'minLength', value: 8 }],
+      },
+    ];
+    const values: FormValues<FieldName> = {
+      email: 'person@example.com',
+      password: 'short',
+    };
+
+    expect(validateFields(fields, values)).toEqual({
+      errors: {
+        password: 'Enter at least 8 characters.',
+      },
+      valid: false,
+    });
+  });
+
+  test('returns a successful validation result', () => {
+    const fields: readonly FormFieldConfig<'email'>[] = [
+      {
+        name: 'email',
+        label: 'Email',
+        rules: [{ kind: 'required' }, { kind: 'email' }],
+      },
+    ];
+
+    expect(validateFields(fields, { email: 'person@example.com' })).toEqual({
+      errors: {},
+      valid: true,
+    });
+  });
+});

package/src/components/form/validation.ts

@@ -0,0 +1,83 @@
+import type {
+  FormFieldConfig,
+  FormValidationErrors,
+  FormValidationResult,
+  FormValues,
+  ValidationRule,
+} from './types';
+
+const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export function hasRequiredRule(rules: readonly ValidationRule[] | undefined): boolean {
+  return rules?.some((rule) => rule.kind === 'required') ?? false;
+}
+
+export function validateValue(
+  value: string,
+  rules: readonly ValidationRule[] | undefined,
+): string | undefined {
+  if (!rules?.length) {
+    return undefined;
+  }
+
+  for (const rule of rules) {
+    const normalizedValue = value.trim();
+
+    if (rule.kind === 'required' && normalizedValue.length === 0) {
+      return rule.message ?? 'This field is required.';
+    }
+
+    if (
+      rule.kind === 'email' &&
+      normalizedValue.length > 0 &&
+      !emailPattern.test(normalizedValue)
+    ) {
+      return rule.message ?? 'Enter a valid email address.';
+    }
+
+    if (rule.kind === 'minLength' && value.length < rule.value) {
+      return rule.message ?? `Enter at least ${rule.value} characters.`;
+    }
+
+    if (rule.kind === 'pattern') {
+      try {
+        const pattern = new RegExp(rule.value);
+
+        if (normalizedValue.length > 0 && !pattern.test(value)) {
+          return rule.message ?? 'Enter a valid value.';
+        }
+      } catch {
+        return rule.message ?? 'Enter a valid value.';
+      }
+    }
+  }
+
+  return undefined;
+}
+
+export function validateField<TName extends string>(
+  field: FormFieldConfig<TName>,
+  values: FormValues<TName>,
+): string | undefined {
+  return validateValue(values[field.name], field.rules);
+}
+
+export function validateFields<TName extends string>(
+  fields: readonly FormFieldConfig<TName>[],
+  values: FormValues<TName>,
+): FormValidationResult<TName> {
+  const errors: FormValidationErrors<TName> = {};
+
+  for (const field of fields) {
+    const error = validateField(field, values);
+
+    if (error) {
+      errors[field.name] = error;
+    }
+  }
+
+  return {
+    errors,
+    valid: Object.keys(errors).length === 0,
+  };
+}

package/src/index.ts

@@ -8,6 +8,35 @@ export type { CheckboxGroupOption, CheckboxGroupProps, CheckboxProps } from './c
 export { Checkbox, CheckboxGroup } from './components/checkbox';
 export type { DrawerProps } from './components/drawer';
 export { Drawer } from './components/drawer';
+export type {
+  FormActionsProps,
+  FormErrorProps,
+  FormErrors,
+  FormFieldConfig,
+  FormFieldControlProps,
+  FormFieldInputType,
+  FormFieldProps,
+  FormFieldValue,
+  FormFieldWrapperProps,
+  FormProps,
+  FormValidationErrors,
+  FormValidationResult,
+  FormValues,
+  UseFormControllerOptions,
+  UseFormControllerResult,
+  ValidationRule,
+} from './components/form';
+export {
+  Form,
+  FormActions,
+  FormError,
+  FormField,
+  hasRequiredRule,
+  useFormController,
+  validateField,
+  validateFields,
+  validateValue,
+} from './components/form';
 export type { IconProps } from './components/icon';
 export { Icon } from './components/icon';
 export type { IconButtonProps } from './components/icon-button';
@@ -42,6 +71,20 @@ export type { SidebarLayoutProps } from './layout/sidebar-layout';
 export { SidebarLayout } from './layout/sidebar-layout';
 export type { TopbarLayoutProps } from './layout/topbar-layout';
 export { TopbarLayout } from './layout/topbar-layout';
+export type {
+  AuthFormBaseProps,
+  AuthIdentifierKind,
+  ForgotPasswordFormProps,
+  ForgotPasswordFormValues,
+  OtpFormProps,
+  OtpFormValues,
+  SignInFormProps,
+  SignInFormValues,
+  SignUpFormField,
+  SignUpFormProps,
+  SignUpFormValues,
+} from './patterns/auth';
+export { ForgotPasswordForm, OtpForm, SignInForm, SignUpForm } from './patterns/auth';
 export type {
   CollectionEditorProps,
   CollectionEditorRenderItemProps,
@@ -53,8 +96,6 @@ export type { DisclosureSectionProps } from './patterns/disclosure-section';
 export { DisclosureSection } from './patterns/disclosure-section';
 export type { EmptyStateAction, EmptyStateProps } from './patterns/empty-state';
 export { EmptyState } from './patterns/empty-state';
-export type { FormFieldProps } from './patterns/form-field';
-export { FormField } from './patterns/form-field';
 export type { InspectorFieldProps } from './patterns/inspector-field';
 export { InspectorField } from './patterns/inspector-field';
 export type { NoticeProps } from './patterns/notice';

package/src/patterns/auth/ForgotPasswordForm.tsx

@@ -0,0 +1,84 @@
+import { Stack } from '@ankhorage/surface';
+import React from 'react';
+
+import { Button } from '../../components/button';
+import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
+import type { ForgotPasswordFormProps } from './types';
+import {
+  defaultIdentifiers,
+  normalizeIdentifierKind,
+  resolveIdentifierLabel,
+  resolveIdentifierRules,
+  resolveIdentifierType,
+} from './utils';
+
+type ForgotPasswordFieldName = 'identifier';
+
+export function ForgotPasswordForm({
+  identifiers = defaultIdentifiers,
+  identifierLabel,
+  signInLabel = 'Sign in',
+  loading = false,
+  disabled = false,
+  error,
+  submitLabel = 'Send code',
+  onSubmit,
+  onSignIn,
+  testID,
+}: ForgotPasswordFormProps) {
+  const [values, setValues] = React.useState<FormValues<ForgotPasswordFieldName>>({
+    identifier: '',
+  });
+  const fields = React.useMemo<readonly FormFieldConfig<ForgotPasswordFieldName>[]>(
+    () => [
+      {
+        name: 'identifier',
+        label: identifierLabel ?? resolveIdentifierLabel(identifiers),
+        type: resolveIdentifierType(identifiers),
+        autoCapitalize: 'none',
+        rules: resolveIdentifierRules(identifiers),
+      },
+    ],
+    [identifierLabel, identifiers],
+  );
+
+  const handleSubmit = React.useCallback(
+    (formValues: FormValues<ForgotPasswordFieldName>) =>
+      onSubmit({
+        identifier: formValues.identifier.trim(),
+        identifierKind: normalizeIdentifierKind(formValues.identifier, identifiers),
+      }),
+    [identifiers, onSubmit],
+  );
+
+  return (
+    <Form
+      actions={
+        onSignIn ? (
+          <Stack direction="row" gap="s" wrap="wrap">
+            <Button
+              disabled={disabled || loading}
+              emphasis="ghost"
+              onPress={() => {
+                void onSignIn();
+              }}
+              size="s"
+              tone="neutral"
+            >
+              {signInLabel}
+            </Button>
+          </Stack>
+        ) : undefined
+      }
+      disabled={disabled}
+      error={error}
+      fields={fields}
+      loading={loading}
+      onChange={setValues}
+      onSubmit={handleSubmit}
+      submitLabel={submitLabel}
+      testID={testID}
+      values={values}
+    />
+  );
+}