@ankhorage/zora 10.0.0 → 11.0.0

package/src/features/form/formMeta.ts

@@ -0,0 +1,34 @@
+import type { ZoraComponentMeta } from '../../metadata';
+export const formMeta = {
+  name: 'Form',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: ['FormError', 'FormField'],
+  blueprint: {
+    label: 'Form',
+    defaultProps: { submitLabel: 'Submit', loading: false, disabled: false },
+  },
+  bindings: {
+    events: {
+      submit: {
+        label: 'Submit',
+        description: 'Runs when the form is submitted.',
+        payload: { eventType: 'form.submit', fields: [] },
+      },
+    },
+  },
+  events: {
+    submit: {
+      label: 'Submit',
+      eventType: 'form.submit',
+      description: 'Emitted when the form is submitted.',
+      payloadFields: [],
+    },
+  },
+  slots: { actions: { label: 'Actions', allowedChildren: ['Button', 'ButtonGroup'] } },
+  props: {
+    submitLabel: { type: 'string', category: 'Content', label: 'Submit label', default: 'Submit' },
+    loading: { type: 'boolean', category: 'State', label: 'Loading', default: false },
+    disabled: { type: 'boolean', category: 'State', label: 'Disabled', default: false },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/{components/form/index.ts → features/form/public.ts}

@@ -1,13 +1,8 @@
-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,
   FormProps,
@@ -17,6 +12,10 @@ export type {
   UseFormControllerOptions,
   UseFormControllerResult,
   ValidationRule,
-} from './types';
+} from '../../types/form';
+export { Form } from './adapters/inbound/Form';
+export { FormActions } from './adapters/inbound/FormActions';
+export { FormError } from './adapters/inbound/FormError';
+export { FormField } from './adapters/inbound/FormField';
 export { useFormController } from './useFormController';
-export { hasRequiredRule, validateField, validateFields, validateValue } from './validation';
+export { hasRequiredRule, validateField, validateFields, validateValue } from './utils/validation';

package/src/{components → features}/form/useFormController.ts

@@ -6,8 +6,8 @@ import type {
   FormValues,
   UseFormControllerOptions,
   UseFormControllerResult,
-} from './types';
-import { validateFields } from './validation';
+} from '../../types/form';
+import { validateFields } from './utils/validation';
 
 function createInitialValues<TName extends string>(
   fields: readonly { name: TName }[],

package/src/{components/form → features/form/utils}/validation.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import type { FormFieldConfig, FormValues } from './types';
+import type { FormFieldConfig, FormValues } from '../../../types/form';
 import { validateFields, validateValue } from './validation';
 
 describe('form validation', () => {
@@ -12,6 +12,9 @@ describe('form validation', () => {
 
   test('validates email fields', () => {
     expect(validateValue('not-email', [{ kind: 'email' }])).toBe('Enter a valid email address.');
+    expect(validateValue('person@exam_ple.com', [{ kind: 'email' }])).toBe(
+      'Enter a valid email address.',
+    );
     expect(validateValue('person@example.com', [{ kind: 'email' }])).toBeUndefined();
   });
 

package/src/{components/form → features/form/utils}/validation.ts

@@ -1,12 +1,12 @@
+import { isEmail } from '@ankhorage/utility/regex';
+
 import type {
   FormFieldConfig,
   FormValidationErrors,
   FormValidationResult,
   FormValues,
   ValidationRule,
-} from './types';
-
-const emailPattern = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+} from '../../../types/form';
 
 export function hasRequiredRule(rules: readonly ValidationRule[] | undefined): boolean {
   return rules?.some((rule) => rule.kind === 'required') ?? false;
@@ -27,11 +27,7 @@ export function validateValue(
       return rule.message ?? 'This field is required.';
     }
 
-    if (
-      rule.kind === 'email' &&
-      normalizedValue.length > 0 &&
-      !emailPattern.test(normalizedValue)
-    ) {
+    if (rule.kind === 'email' && normalizedValue.length > 0 && !isEmail(normalizedValue)) {
       return rule.message ?? 'Enter a valid email address.';
     }
 

package/src/features/uploader/adapters/inbound/Uploader.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
 import { Modal } from '../../../../components/modal';
-import { FormField } from '../../../../patterns/form-field';
 import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { UploadAsset, UploaderProps, UploadType } from '../../../../types/upload';
 import { Button } from '../../../button/public';
+import { FormField } from '../../../form/public';
 import { Icon } from '../../../icon/public';
 import { Image } from '../../../image/public';
 import { Box, Stack } from '../../../layout/public';

package/src/index.ts

@@ -4,33 +4,6 @@ export type { BreadcrumbItem, BreadcrumbsProps } from './components/breadcrumbs'
 export { Breadcrumbs } from './components/breadcrumbs';
 export type { DatePickerProps, DatePickerValue } from './components/date-picker';
 export { DatePicker } from './components/date-picker';
-export type {
-  FormActionsProps,
-  FormErrorProps,
-  FormErrors,
-  FormFieldConfig,
-  FormFieldControlProps,
-  FormFieldInputType,
-  FormFieldProps,
-  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 {
   GradientColor,
   GradientColors,
@@ -139,6 +112,32 @@ export {
   type CheckboxGroupProps,
   type CheckboxProps,
 } from './features/form/checkbox/public';
+export type {
+  FormActionsProps,
+  FormErrorProps,
+  FormErrors,
+  FormFieldConfig,
+  FormFieldInputType,
+  FormFieldProps,
+  FormProps,
+  FormValidationErrors,
+  FormValidationResult,
+  FormValues,
+  UseFormControllerOptions,
+  UseFormControllerResult,
+  ValidationRule,
+} from './features/form/public';
+export {
+  Form,
+  FormActions,
+  FormError,
+  FormField,
+  hasRequiredRule,
+  useFormController,
+  validateField,
+  validateFields,
+  validateValue,
+} from './features/form/public';
 export {
   Radio,
   RadioGroup,

package/src/metadata/allowedChildren.ts

@@ -30,7 +30,7 @@ export const CONTAINER_ALLOWED_CHILDREN = [
   'RadioGroup',
   'ThemeModeToggle',
   'TextInput',
-  'FormField',
+  'Form',
   'Card',
   'Panel',
   'Notice',

package/src/metadata/componentMeta.test.ts

@@ -51,7 +51,7 @@ describe('ZORA_COMPONENT_META event metadata', () => {
     const eventType: ZoraComponentEventPayloadKind = event?.eventType ?? 'form.submit';
 
     expect(eventType).toBe('form.submit');
-    expect(event?.payloadFields?.map((field) => field.path)).toEqual(['payload.values']);
+    expect(event?.payloadFields).toEqual([]);
   });
 
   test('declares button event metadata', () => {
@@ -100,6 +100,21 @@ describe('ZORA_COMPONENT_META requirement metadata', () => {
 });
 
 describe('ZORA_COMPONENT_META invariants', () => {
+  test('keeps form nodes in their canonical hierarchy', () => {
+    expect(ZORA_COMPONENT_META.Form.allowedChildren).toEqual(['FormError', 'FormField']);
+    expect(ZORA_COMPONENT_META.FormField.allowedChildren).toEqual([
+      'Checkbox',
+      'CheckboxGroup',
+      'RadioGroup',
+      'TextInput',
+    ]);
+    for (const [name, meta] of Object.entries(ZORA_COMPONENT_META)) {
+      if (name === 'Form') continue;
+      expect(meta.allowedChildren).not.toContain('FormError');
+      expect(meta.allowedChildren).not.toContain('FormField');
+    }
+  });
+
   test('every key matches meta.name', () => {
     for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
       expect(meta.name).toBe(key);
@@ -136,6 +151,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'EmptyState',
       'Hero',
       'Button',
+      'FormError',
       'Checkbox',
       'CheckboxGroup',
       'Radio',
@@ -158,6 +174,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
     ]);
 
     const expectedContainerNodes = new Set([
+      'Form',
       'Surface',
       'MediaCard',
       'FlatList',

package/src/metadata/componentMeta.ts

@@ -1,7 +1,6 @@
 import { appBarMeta } from '../components/app-bar/meta';
 import { breadcrumbsMeta } from '../components/breadcrumbs/meta';
 import { datePickerMeta } from '../components/date-picker/meta';
-import { formActionsMeta, formErrorMeta, formFieldMeta, formMeta } from '../components/form/meta';
 import { gradientMeta } from '../components/gradient/meta';
 import { dropdownMenuMeta, menuMeta } from '../components/menu/meta';
 import { modalMeta } from '../components/modal/meta';
@@ -37,6 +36,10 @@ import { chipMeta } from '../features/chip/chipMeta';
 import { dataTableMeta } from '../features/data-table/dataTableMeta';
 import { emptyStateMeta } from '../features/empty-state/emptyStateMeta';
 import { checkboxGroupMeta, checkboxMeta } from '../features/form/checkbox/checkboxMeta';
+import { formActionsMeta } from '../features/form/formActionsMeta';
+import { formErrorMeta } from '../features/form/formErrorMeta';
+import { formFieldMeta } from '../features/form/formFieldMeta';
+import { formMeta } from '../features/form/formMeta';
 import { radioGroupMeta, radioMeta } from '../features/form/radio/radioMeta';
 import { textInputMeta } from '../features/form/text-input/textInputMeta';
 import { iconMeta } from '../features/icon/iconMeta';

package/src/patterns/auth/AuthForm.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+
+import { FormActions, FormError, useFormController } from '../../features/form/public';
+import { Stack } from '../../features/layout/public';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+import type { FormErrors, FormFieldConfig, FormValues } from '../../types/form';
+import { AuthFormField } from './AuthFormField';
+
+interface AuthFormProps<TName extends 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;
+  testID?: string;
+  interactionPolicy?: ZoraBaseProps['interactionPolicy'];
+}
+
+/*** Keeps config-driven field orchestration private to the auth patterns that own it. */
+export function AuthForm<TName extends string>({
+  fields,
+  values,
+  onChange,
+  onSubmit,
+  errors,
+  error,
+  loading = false,
+  disabled = false,
+  submitLabel = 'Submit',
+  actions,
+  testID,
+  interactionPolicy,
+}: AuthFormProps<TName>) {
+  const controller = useFormController({ fields, values, errors, onChange, onSubmit });
+  return (
+    <Stack gap="m" testID={testID}>
+      <FormError error={error} />
+      {fields.map((field) => (
+        <AuthFormField
+          key={field.name}
+          disabled={disabled}
+          error={controller.errors[field.name]}
+          field={field}
+          interactionPolicy={interactionPolicy}
+          loading={loading}
+          onChange={controller.setFieldValue}
+          value={values[field.name]}
+        />
+      ))}
+      <FormActions
+        disabled={disabled}
+        interactionPolicy={interactionPolicy}
+        loading={loading}
+        onSubmit={() => {
+          if (interactionPolicy !== 'passive') void controller.handleSubmit();
+        }}
+        submitLabel={submitLabel}
+      >
+        {actions}
+      </FormActions>
+    </Stack>
+  );
+}

package/src/patterns/auth/AuthFormField.tsx

@@ -0,0 +1,81 @@
+import React from 'react';
+
+import { FormField, hasRequiredRule } from '../../features/form/public';
+import { TextInput } from '../../features/form/text-input/public';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+import type { FormFieldConfig, FormFieldValue } from '../../types/form';
+
+interface AuthFormFieldProps<TName extends string> {
+  field: FormFieldConfig<TName>;
+  value: FormFieldValue;
+  onChange: (name: TName, value: FormFieldValue) => void;
+  error?: React.ReactNode;
+  disabled?: boolean;
+  loading?: boolean;
+  interactionPolicy?: ZoraBaseProps['interactionPolicy'];
+}
+
+/*** Adapts an auth field configuration to the public compositional form primitives. */
+export function AuthFormField<TName extends string>({
+  field,
+  value,
+  onChange,
+  error,
+  disabled = false,
+  loading = false,
+  interactionPolicy,
+}: AuthFormFieldProps<TName>) {
+  const fieldDisabled = disabled || loading || field.disabled;
+  return (
+    <FormField
+      description={field.description}
+      disabled={fieldDisabled}
+      errorText={error}
+      helperText={field.helperText}
+      invalid={Boolean(error)}
+      label={field.label}
+      readOnly={field.readOnly}
+      required={field.required ?? hasRequiredRule(field.rules)}
+      testID={field.testID}
+    >
+      <TextInput
+        accessibilityLabel={typeof field.label === 'string' ? field.label : undefined}
+        autoCapitalize={
+          field.autoCapitalize ??
+          (['email', 'password', 'url'].includes(field.type ?? 'text') ? 'none' : undefined)
+        }
+        autoComplete={field.autoComplete}
+        disabled={fieldDisabled}
+        interactionPolicy={interactionPolicy}
+        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}
+      />
+    </FormField>
+  );
+}
+
+/*** Resolves the native keyboard for an auth field configuration. */
+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;
+}
+
+/*** Resolves platform text-content hints for an auth field configuration. */
+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;
+}

package/src/patterns/auth/ForgotPasswordForm.tsx

@@ -1,9 +1,10 @@
 import React from 'react';
 
-import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
 import { Button } from '../../features/button/public';
 import { Stack } from '../../features/layout/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { FormFieldConfig, FormValues } from '../../types/form';
+import { AuthForm } from './AuthForm';
 import type { ForgotPasswordFormProps } from './types';
 import {
   defaultIdentifiers,
@@ -56,7 +57,7 @@ function ForgotPasswordFormInner({
   );
 
   return (
-    <Form
+    <AuthForm
       actions={
         onSignIn ? (
           <Stack direction="row" gap="s" wrap="wrap">

package/src/patterns/auth/OtpForm.tsx

@@ -1,9 +1,10 @@
 import React from 'react';
 
-import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
 import { Button } from '../../features/button/public';
 import { Stack } from '../../features/layout/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { FormFieldConfig, FormValues } from '../../types/form';
+import { AuthForm } from './AuthForm';
 import type { OtpFormProps } from './types';
 
 type OtpFieldName = 'otp';
@@ -51,7 +52,7 @@ function OtpFormInner({
   );
 
   return (
-    <Form
+    <AuthForm
       actions={
         onResend ? (
           <Stack direction="row" gap="s" wrap="wrap">

package/src/patterns/auth/SignInForm.tsx

@@ -1,9 +1,10 @@
 import React from 'react';
 
-import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
 import { Button } from '../../features/button/public';
 import { Stack } from '../../features/layout/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { FormFieldConfig, FormValues } from '../../types/form';
+import { AuthForm } from './AuthForm';
 import type { SignInFormProps } from './types';
 import {
   defaultIdentifiers,
@@ -68,7 +69,7 @@ function SignInFormInner({
   );
 
   return (
-    <Form
+    <AuthForm
       actions={
         hasActions ? (
           <Stack direction="row" gap="s" wrap="wrap">

package/src/patterns/auth/SignUpForm.tsx

@@ -1,9 +1,10 @@
 import React from 'react';
 
-import { Form, type FormFieldConfig, type FormValues } from '../../components/form';
 import { Button } from '../../features/button/public';
 import { Stack } from '../../features/layout/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { FormFieldConfig, FormValues } from '../../types/form';
+import { AuthForm } from './AuthForm';
 import type { SignUpFormProps } from './types';
 
 const defaultSignUpFields = [
@@ -48,7 +49,7 @@ function SignUpFormInner({
   const [values, setValues] = React.useState<FormValues>(() => createValues(fields));
 
   return (
-    <Form
+    <AuthForm
       actions={
         onSignIn ? (
           <Stack direction="row" gap="s" wrap="wrap">

package/src/patterns/auth/types.ts

@@ -1,9 +1,9 @@
 import type { ButtonIconSpec } from '@ankhorage/surface';
 import type React from 'react';
 
-import type { FormFieldConfig, FormValues } from '../../components/form';
 import type { ButtonProps } from '../../features/button/public';
 import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+import type { FormFieldConfig, FormValues } from '../../types/form';
 
 export type AuthIdentifierKind = 'email' | 'phone' | 'username';
 

package/src/patterns/auth/utils.ts

@@ -1,4 +1,4 @@
-import type { FormFieldConfig, ValidationRule } from '../../components/form';
+import type { FormFieldConfig, ValidationRule } from '../../types/form';
 import type { AuthIdentifierKind } from './types';
 
 export const defaultIdentifiers = ['email'] as const satisfies readonly AuthIdentifierKind[];

package/src/patterns/inspector-field/InspectorField.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
+import { FormField } from '../../features/form/public';
 import { Box, Stack } from '../../features/layout/public';
 import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
-import { FormField } from '../form-field';
 import type { InspectorFieldProps } from './types';
 
 function InspectorFieldInner({

package/src/registry.ts

@@ -4,7 +4,6 @@ import type React from 'react';
 import { AppBar } from './components/app-bar';
 import { Breadcrumbs } from './components/breadcrumbs';
 import { DatePicker } from './components/date-picker';
-import { Form, FormActions, FormError, FormField } from './components/form';
 import { Gradient } from './components/gradient';
 import { DropdownMenu, Menu } from './components/menu';
 import { Modal } from './components/modal';
@@ -35,6 +34,7 @@ import { ChipGroup } from './features/chip/public';
 import { DataTable } from './features/data-table/public';
 import { EmptyState } from './features/empty-state/public';
 import { Checkbox, CheckboxGroup } from './features/form/checkbox/public';
+import { Form, FormActions, FormError, FormField } from './features/form/public';
 import { Radio, RadioGroup } from './features/form/radio/public';
 import { TextInput } from './features/form/text-input/public';
 import { Icon } from './features/icon/public';

package/src/theme/themeScopeStructure.test.ts

@@ -65,10 +65,10 @@ const scopedComponentFiles = [
   join(srcDir, 'features', 'card', 'adapters', 'inbound', 'MetricCard.tsx'),
   join(srcDir, 'features', 'form', 'checkbox', 'adapters', 'inbound', 'Checkbox.tsx'),
   join(srcDir, 'features', 'form', 'checkbox', 'adapters', 'inbound', 'CheckboxGroup.tsx'),
-  join(srcDir, 'components', 'form', 'Form.tsx'),
-  join(srcDir, 'components', 'form', 'FormActions.tsx'),
-  join(srcDir, 'components', 'form', 'FormError.tsx'),
-  join(srcDir, 'components', 'form', 'FormField.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'Form.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'FormActions.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'FormError.tsx'),
+  join(srcDir, 'features', 'form', 'adapters', 'inbound', 'FormField.tsx'),
   join(srcDir, 'features', 'typography', 'adapters', 'inbound', 'Heading.tsx'),
   join(srcDir, 'features', 'icon', 'adapters', 'inbound', 'Icon.tsx'),
   join(srcDir, 'features', 'button', 'adapters', 'inbound', 'IconButton.tsx'),
@@ -99,7 +99,6 @@ const scopedComponentFiles = [
   join(srcDir, 'patterns', 'confirm-dialog', 'ConfirmDialog.tsx'),
   join(srcDir, 'patterns', 'disclosure-section', 'DisclosureSection.tsx'),
   join(srcDir, 'features', 'empty-state', 'adapters', 'inbound', 'EmptyState.tsx'),
-  join(srcDir, 'patterns', 'form-field', 'FormField.tsx'),
   join(srcDir, 'patterns', 'inspector-field', 'InspectorField.tsx'),
   join(srcDir, 'patterns', 'list', 'List.tsx'),
   join(srcDir, 'patterns', 'list', 'ListRow.tsx'),
@@ -136,7 +135,7 @@ const scopedPropTypeFiles = [
   join(srcDir, 'types', 'media-card.ts'),
   join(srcDir, 'types', 'metric-card.ts'),
   join(srcDir, 'types', 'checkbox.ts'),
-  join(srcDir, 'components', 'form', 'types.ts'),
+  join(srcDir, 'types', 'form.ts'),
   join(srcDir, 'types', 'heading.ts'),
   join(srcDir, 'types', 'icon.ts'),
   join(srcDir, 'types', 'icon-button.ts'),
@@ -162,7 +161,6 @@ const scopedPropTypeFiles = [
   join(srcDir, 'patterns', 'confirm-dialog', 'types.ts'),
   join(srcDir, 'patterns', 'disclosure-section', 'types.ts'),
   join(srcDir, 'types', 'empty-state.ts'),
-  join(srcDir, 'patterns', 'form-field', 'types.ts'),
   join(srcDir, 'patterns', 'inspector-field', 'types.ts'),
   join(srcDir, 'patterns', 'list', 'types.ts'),
   join(srcDir, 'patterns', 'notice', 'types.ts'),