@gntik-ai/blocks 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gntik-ai/blocks",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "gntik-ui blocks: page chrome, data display, tables, forms, feedback, billing, team and builder sections composed from @gntik-ai/ui.",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "@gntik-ai/flow": "0.5.0",
     "@gntik-ai/icons": "0.5.0",
     "@gntik-ai/tokens": "0.2.1",
-    "@gntik-ai/ui": "0.5.0",
+    "@gntik-ai/ui": "0.7.0",
     "lucide-react": "^1.48.0"
   },
   "devDependencies": {

package/src/auth/SignUpForm/SignUpForm.configured.test.tsx

@@ -0,0 +1,316 @@
+import { render, screen, within, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { SignUpForm } from './SignUpForm';
+
+const fields = [
+  {
+    id: 'username',
+    label: 'Username',
+    placeholder: 'Account name',
+    help: 'Choose an account name.',
+    required: true,
+    type: 'text' as const,
+    autoComplete: 'username',
+  },
+  {
+    id: 'displayName',
+    label: 'Display name',
+    placeholder: 'Your name',
+    help: 'Name shown to others.',
+    required: true,
+    type: 'text' as const,
+    autoComplete: 'name',
+  },
+  {
+    id: 'email',
+    label: 'Email',
+    placeholder: 'you@example.com',
+    help: 'For account notifications.',
+    required: true,
+    type: 'email' as const,
+    autoComplete: 'email',
+  },
+  {
+    id: 'tenant',
+    label: 'Tenant identifier',
+    placeholder: 'Tenant',
+    help: 'Your organization.',
+    required: true,
+    type: 'text' as const,
+    autoComplete: 'off',
+  },
+  {
+    id: 'workspace',
+    label: 'Workspace identifier',
+    placeholder: 'Workspace',
+    help: 'Optional workspace.',
+    required: false,
+    type: 'text' as const,
+    autoComplete: 'off',
+  },
+];
+
+describe('SignUpForm configured fields', () => {
+  it('blocks whitespace-only required fields independently of password and consent, and refocuses the summary on retry', async () => {
+    const onSubmit = vi.fn();
+    render(
+      <SignUpForm
+        fields={[
+          {
+            id: 'username',
+            label: 'Username',
+            required: true,
+            help: 'Choose an account name.',
+            messages: { required: 'An account name is required.' },
+          },
+          { id: 'workspace', label: 'Workspace identifier' },
+        ]}
+        terms={false}
+        sso={null}
+        onSubmit={onSubmit}
+      />,
+    );
+    await userEvent.type(screen.getByLabelText('Username'), '   ');
+    await userEvent.type(screen.getByLabelText('Password'), 'correct-horse-42');
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).not.toHaveBeenCalled();
+    const summary = screen.getByRole('region', { name: 'There is 1 problem with this form' });
+    expect(summary).toHaveFocus();
+    await userEvent.tab();
+    expect(within(summary).getByRole('link', { name: 'Username: An account name is required.' })).toHaveFocus();
+    await userEvent.keyboard('{Enter}');
+    expect(screen.getByLabelText('Username')).toHaveFocus();
+    expect(screen.getByLabelText('Username')).toHaveAccessibleDescription(
+      'Choose an account name. An account name is required.',
+    );
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(summary).toHaveFocus();
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it('renders ordered fields, links all errors to inputs, and submits trimmed values with an empty optional field', async () => {
+    const onSubmit = vi.fn();
+    const { container } = render(<SignUpForm fields={fields} onSubmit={onSubmit} sso={null} />);
+    expect(
+      Array.from(container.querySelectorAll('input[type="text"], input[type="email"], input[type="password"]')).map(
+        (input) => input.getAttribute('placeholder'),
+      ),
+    ).toEqual(['Account name', 'Your name', 'you@example.com', 'Tenant', 'Workspace', null]);
+    for (const field of fields) {
+      const input = screen.getByLabelText(field.label);
+      expect(input).toHaveAttribute('type', field.type);
+      expect(input).toHaveAttribute('autocomplete', field.autoComplete);
+      expect(input).toHaveAccessibleDescription(field.help);
+      expect(input).toHaveProperty('required', field.required);
+    }
+    await expectNoAxeViolations(container);
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).not.toHaveBeenCalled();
+    const summary = screen.getByRole('region');
+    expect(summary).toHaveFocus();
+    expect(within(summary).getAllByRole('link')).toHaveLength(6);
+    await userEvent.click(within(summary).getByRole('link', { name: 'Username: Enter Username.' }));
+    expect(screen.getByLabelText('Username')).toHaveFocus();
+    expect(screen.getByLabelText('Username')).toHaveAttribute('aria-invalid', 'true');
+    expect(screen.getByLabelText('Username')).toHaveAccessibleDescription('Choose an account name. Enter Username.');
+    await expectNoAxeViolations(container);
+    await userEvent.type(screen.getByLabelText('Username'), ' avery ');
+    await userEvent.type(screen.getByLabelText('Display name'), ' Avery Collins ');
+    await userEvent.type(screen.getByLabelText('Email'), ' avery@example.com ');
+    await userEvent.type(screen.getByLabelText('Tenant identifier'), ' team ');
+    await userEvent.type(screen.getByLabelText('Password'), 'correct-horse-42');
+    await userEvent.click(screen.getByRole('checkbox'));
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).toHaveBeenCalledWith({
+      name: '',
+      email: 'avery@example.com',
+      password: 'correct-horse-42',
+      fields: {
+        username: 'avery',
+        displayName: 'Avery Collins',
+        email: 'avery@example.com',
+        tenant: 'team',
+        workspace: '',
+      },
+    });
+  });
+});
+
+it('omits consent only when terms is explicitly false, in default and configured modes', async () => {
+  const onSubmit = vi.fn();
+  const { rerender } = render(<SignUpForm terms={false} sso={null} onSubmit={onSubmit} />);
+  expect(screen.queryByRole('checkbox')).not.toBeInTheDocument();
+  await userEvent.type(screen.getByLabelText('Full name'), ' Avery ');
+  await userEvent.type(screen.getByLabelText('Work email'), 'avery@example.com');
+  await userEvent.type(screen.getByLabelText('Password'), 'correct-horse-42');
+  await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+  expect(onSubmit).toHaveBeenCalledWith({ name: 'Avery', email: 'avery@example.com', password: 'correct-horse-42' });
+  onSubmit.mockClear();
+  rerender(<SignUpForm fields={[]} terms={false} sso={null} onSubmit={onSubmit} />);
+  await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+  expect(onSubmit).toHaveBeenCalledWith({ name: '', email: '', password: 'correct-horse-42', fields: {} });
+});
+
+it.each([undefined, 8, 12])(
+  'uses the password minimum %s for inline validation, optional help and the meter',
+  async (minimum) => {
+    const onSubmit = vi.fn();
+    const min = minimum ?? 8;
+    const { container } = render(
+      <SignUpForm
+        fields={[]}
+        terms={false}
+        minPasswordLength={minimum}
+        passwordHelp={`Use at least ${min} characters to secure your account.`}
+        onSubmit={onSubmit}
+        sso={null}
+      />,
+    );
+    const password = screen.getByLabelText('Password');
+    expect(password).toHaveAccessibleDescription(
+      expect.stringContaining(`Use at least ${min} characters to secure your account.`),
+    );
+    await userEvent.type(password, min === 8 ? 'Abc1!xy' : 'Abc1!xyzabc');
+    expect(password).toHaveValue(min === 8 ? 'Abc1!xy' : 'Abc1!xyzabc');
+    expect(screen.getByText('Too weak')).toBeInTheDocument();
+    expect(screen.getByText(`Use at least ${min} characters.`)).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).not.toHaveBeenCalled();
+    expect(password).toHaveAttribute('aria-invalid', 'true');
+    await expectNoAxeViolations(container);
+    await userEvent.type(password, 'z');
+    expect(password).toHaveValue(min === 8 ? 'Abc1!xyz' : 'Abc1!xyzabcz');
+    await waitFor(() => expect(screen.queryByText(`Use at least ${min} characters.`)).not.toBeInTheDocument());
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  },
+);
+
+it('replaces the form with an unavailable callout and consumer action', async () => {
+  const onAction = vi.fn();
+  const { container } = render(
+    <SignUpForm
+      unavailable={{
+        title: 'Registration unavailable',
+        message: 'Contact your administrator.',
+        action: <button onClick={onAction}>Request access</button>,
+      }}
+    />,
+  );
+  expect(screen.getByText('Registration unavailable')).toBeInTheDocument();
+  expect(screen.getByText('Contact your administrator.')).toBeInTheDocument();
+  expect(screen.queryByRole('form')).not.toBeInTheDocument();
+  expect(container.querySelector('input')).toBeNull();
+  expect(screen.queryByRole('button', { name: 'Create account' })).not.toBeInTheDocument();
+  await userEvent.click(screen.getByRole('button', { name: 'Request access' }));
+  expect(onAction).toHaveBeenCalledTimes(1);
+  await expectNoAxeViolations(container);
+});
+
+it('shows skeletons and cannot submit while policy is loading, then restores the form', async () => {
+  const onSubmit = vi.fn();
+  const { container, rerender } = render(<SignUpForm policyLoading onSubmit={onSubmit} />);
+  expect(screen.getByRole('status')).toHaveTextContent('Loading sign-up policy');
+  expect(container.querySelectorAll('[aria-hidden="true"]').length).toBeGreaterThan(0);
+  expect(screen.queryByRole('form')).not.toBeInTheDocument();
+  expect(container.querySelector('input')).toBeNull();
+  expect(screen.queryByRole('button', { name: 'Create account' })).not.toBeInTheDocument();
+  expect(onSubmit).not.toHaveBeenCalled();
+  await expectNoAxeViolations(container);
+  rerender(<SignUpForm policyLoading={false} onSubmit={onSubmit} />);
+  expect(screen.getByRole('form')).toBeInTheDocument();
+});
+
+it('validates non-empty optional email and uses consumer-supplied messages', async () => {
+  const onSubmit = vi.fn();
+  render(
+    <SignUpForm
+      fields={[
+        {
+          id: 'contact',
+          label: 'Contact',
+          type: 'email',
+          help: 'Optional contact address.',
+          messages: { invalid: 'Check the contact address.' },
+        },
+      ]}
+      terms={false}
+      messages={{ passwordTooShort: (minimum) => `Password needs ${minimum} characters.` }}
+      onSubmit={onSubmit}
+      sso={null}
+    />,
+  );
+  await userEvent.type(screen.getByLabelText('Contact'), 'invalid');
+  await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+  const summary = screen.getByRole('region');
+  expect(within(summary).getByRole('link', { name: 'Contact: Check the contact address.' })).toBeInTheDocument();
+  await userEvent.click(within(summary).getByRole('link', { name: 'Password: Password needs 8 characters.' }));
+  expect(screen.getByLabelText('Password')).toHaveFocus();
+  expect(onSubmit).not.toHaveBeenCalled();
+});
+
+it('keeps password help, strength and error descriptions linked and focuses consent from the summary', async () => {
+  const { container } = render(
+    <SignUpForm fields={[]} passwordHelp="Choose at least 8 characters to secure your account." sso={null} />,
+  );
+  const password = screen.getByLabelText('Password');
+  await userEvent.type(password, 'Abc1!xy');
+  await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+  expect(password).toHaveAccessibleDescription(
+    'Strength: Too weak Choose at least 8 characters to secure your account. Use at least 8 characters.',
+  );
+  const summary = screen.getByRole('region');
+  await userEvent.click(within(summary).getByRole('link', { name: 'Password: Use at least 8 characters.' }));
+  expect(password).toHaveFocus();
+  await userEvent.click(screen.getByRole('button', { name: 'Show password' }));
+  expect(password).toHaveAttribute('type', 'text');
+  expect(password).toHaveAttribute('aria-invalid', 'true');
+  expect(password).toHaveAccessibleDescription(
+    'Strength: Too weak Choose at least 8 characters to secure your account. Use at least 8 characters.',
+  );
+  const termsLink = within(summary).getByRole('link', { name: 'Terms: Accept the terms to continue.' });
+  const termsTarget = termsLink.getAttribute('href')!.slice(1);
+  expect(document.getElementById(termsTarget)).toBe(screen.getByRole('checkbox'));
+  expect(container.querySelectorAll(`[id="${termsTarget}"]`)).toHaveLength(1);
+  termsLink.focus();
+  await userEvent.keyboard('{Enter}');
+  expect(screen.getByRole('checkbox')).toHaveFocus();
+  expect(screen.getByRole('checkbox')).toHaveAccessibleDescription('Accept the terms to continue.');
+  await userEvent.keyboard(' ');
+  expect(screen.getByRole('checkbox')).toBeChecked();
+  expect(within(summary).queryByRole('link', { name: 'Terms: Accept the terms to continue.' })).not.toBeInTheDocument();
+});
+
+it('treats field ids as consumer keys, including names inherited by ordinary objects', async () => {
+  const onSubmit = vi.fn();
+  render(
+    <SignUpForm
+      fields={[{ id: 'constructor', label: 'Account identifier', required: true }]}
+      terms={false}
+      sso={null}
+      onSubmit={onSubmit}
+    />,
+  );
+  expect(screen.getByLabelText('Account identifier')).toHaveValue('');
+  await userEvent.type(screen.getByLabelText('Account identifier'), ' account ');
+  await userEvent.type(screen.getByLabelText('Password'), 'correct-horse-42');
+  await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+  expect(onSubmit).toHaveBeenCalledWith({
+    name: '',
+    email: '',
+    password: 'correct-horse-42',
+    fields: { constructor: 'account' },
+  });
+});
+
+it('preserves default submit-time validation and omits a validation summary in default mode', async () => {
+  render(<SignUpForm sso={null} />);
+  await userEvent.type(screen.getByLabelText('Password'), 'Abc1!xy');
+  expect(screen.getByText('Too weak')).toBeInTheDocument();
+  expect(screen.queryByText('Use at least 8 characters.')).not.toBeInTheDocument();
+  expect(screen.getByLabelText('Password')).not.toHaveAttribute('aria-invalid', 'true');
+  await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+  expect(screen.getByText('Use at least 8 characters.')).toBeInTheDocument();
+  expect(screen.queryByRole('region')).not.toBeInTheDocument();
+});

package/src/auth/SignUpForm/SignUpForm.tsx

@@ -1,22 +1,59 @@
-import { Alert, Button, Checkbox, Field, FieldError, FieldLabel, Input, Link, PasswordInput, cn } from '@gntik-ai/ui';
+import {
+  Alert,
+  Button,
+  Checkbox,
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  Input,
+  Link,
+  PasswordInput,
+  Skeleton,
+  cn,
+} from '@gntik-ai/ui';
 import { Mail, User } from '@gntik-ai/icons';
 import { useId, useState, type MouseEvent, type ReactNode } from 'react';
 import { SsoButtons } from '../SsoButtons/SsoButtons';
-import { AuthDivider, AuthHeader, EMAIL_RE, authFormClass, useAsyncSubmit } from '../shared';
+import {
+  AuthDivider,
+  AuthHeader,
+  EMAIL_RE,
+  authFormClass,
+  authSignUpFieldError,
+  useAsyncSubmit,
+  type AuthSignUpField,
+  type AuthUnavailableState,
+  type AuthSignUpValidationMessages,
+} from '../shared';
+import { ValidationSummary, type ValidationIssue } from '../../forms/ValidationSummary/ValidationSummary';
 
 export interface SignUpValues {
   name: string;
   email: string;
   password: string;
+  /** Present only in configured mode. Text/email values are trimmed and keyed by field id. */
+  fields?: Record<string, string>;
 }
 
 export interface SignUpFormProps {
+  /** Ordered text/email inputs before Password. Omit to keep the default fields and payload. */
+  fields?: readonly AuthSignUpField[];
+  messages?: AuthSignUpValidationMessages;
+  /** Replaces all account creation controls with a consumer-supplied callout. */
+  unavailable?: AuthUnavailableState;
+  /** Resolving policy, separate from loading (an account submission). No form is rendered. */
+  policyLoading?: boolean;
   /** Creates the account. A returned promise shows the loading state; a rejection shows in the alert. */
   onSubmit?: (values: SignUpValues) => void | Promise<void>;
   error?: string | null;
   loading?: boolean;
-  /** Minimum password length. */
+  /** Optional password guidance; receives the current minimum length when a function is supplied. */
+  passwordHelp?: ReactNode | ((minimum: number) => ReactNode);
+  /** Minimum password length. Defaults to 8. */
   minPasswordLength?: number;
+  /** Omit to require consent; false removes the checkbox and consent validation. */
+  terms?: false;
   termsHref?: string;
   privacyHref?: string;
   signInHref?: string;
@@ -31,10 +68,16 @@ export interface SignUpFormProps {
 
 /** Account creation: name, work email, password with a strength meter and a required terms checkbox. */
 export function SignUpForm({
+  fields,
+  messages,
+  unavailable,
+  policyLoading = false,
   onSubmit,
   error: errorProp,
   loading: loadingProp,
   minPasswordLength = 8,
+  passwordHelp,
+  terms: termsProp,
   termsHref = '#',
   privacyHref = '#',
   signInHref = '#',
@@ -46,6 +89,16 @@ export function SignUpForm({
   className,
 }: SignUpFormProps) {
   const termsErrorId = useId();
+  const fieldPrefix = useId();
+  const passwordId = `${fieldPrefix}-password`;
+  const termsId = `${fieldPrefix}-terms`;
+  const [fieldValues, setFieldValues] = useState<Record<string, string>>({});
+  const [submitCount, setSubmitCount] = useState(0);
+  const fieldValue = (id: string) => (Object.hasOwn(fieldValues, id) ? (fieldValues[id] ?? '') : '');
+  const configuredErrors: ValidationIssue[] = (fields ?? []).flatMap((field) => {
+    const message = authSignUpFieldError(fieldValue(field.id), field);
+    return message ? [{ fieldId: `${fieldPrefix}-field-${field.id}`, label: field.label, message }] : [];
+  });
   const [name, setName] = useState('');
   const [email, setEmail] = useState('');
   const [password, setPassword] = useState('');
@@ -56,8 +109,41 @@ export function SignUpForm({
   const alert = errorProp ?? error;
   const nameInvalid = submitted && name.trim() === '';
   const emailInvalid = submitted && !EMAIL_RE.test(email.trim());
-  const passwordInvalid = submitted && password.length < minPasswordLength;
-  const termsInvalid = submitted && !terms;
+  const passwordInvalid =
+    (submitted || (fields !== undefined && password.length > 0)) && password.length < minPasswordLength;
+  const termsInvalid = submitted && termsProp !== false && !terms;
+
+  const passwordError =
+    messages?.passwordTooShort?.(minPasswordLength) ?? `Use at least ${minPasswordLength} characters.`;
+  const termsError = messages?.termsRequired ?? 'Accept the terms to continue.';
+  const summaryErrors = [
+    ...configuredErrors,
+    ...(password.length < minPasswordLength
+      ? [{ fieldId: passwordId, label: 'Password', message: passwordError }]
+      : []),
+    ...(termsProp !== false && !terms ? [{ fieldId: termsId, label: 'Terms', message: termsError }] : []),
+  ];
+
+  if (unavailable)
+    return (
+      <div className={cn(authFormClass, className)}>
+        <Alert tone="info" title={unavailable.title} description={unavailable.message} actions={unavailable.action} />
+      </div>
+    );
+
+  if (policyLoading)
+    return (
+      <div className={cn(authFormClass, 'flex flex-col gap-4', className)}>
+        <span role="status" className="sr-only">
+          Loading sign-up policy…
+        </span>
+        <Skeleton aria-hidden className="h-8 w-3/4" />
+        <Skeleton aria-hidden className="h-4 w-full" />
+        <Skeleton aria-hidden className="h-12 w-full" />
+        <Skeleton aria-hidden className="h-12 w-full" />
+        <Skeleton aria-hidden className="h-12 w-full" />
+      </div>
+    );
 
   return (
     <div className={cn(authFormClass, className)}>
@@ -69,60 +155,118 @@ export function SignUpForm({
         onSubmit={(e) => {
           e.preventDefault();
           setSubmitted(true);
-          if (name.trim() === '' || !EMAIL_RE.test(email.trim()) || password.length < minPasswordLength || !terms)
+          if (fields !== undefined) {
+            setSubmitCount((count) => count + 1);
+            if (summaryErrors.length > 0) return;
+            const values = Object.fromEntries(fields.map((field) => [field.id, fieldValue(field.id).trim()]));
+            void run(() =>
+              onSubmit?.({ name: values.name ?? '', email: values.email ?? '', password, fields: values }),
+            );
+            return;
+          }
+          if (
+            name.trim() === '' ||
+            !EMAIL_RE.test(email.trim()) ||
+            password.length < minPasswordLength ||
+            (termsProp !== false && !terms)
+          )
             return;
           void run(() => onSubmit?.({ name: name.trim(), email: email.trim(), password }));
         }}
       >
         {alert && <Alert tone="destructive" description={alert} />}
-        <Field invalid={nameInvalid}>
-          <FieldLabel>Full name</FieldLabel>
-          <Input
-            leadingIcon={User}
-            autoComplete="name"
-            placeholder="Avery Collins"
-            value={name}
-            onValueChange={setName}
-            required
-          />
-          <FieldError match={nameInvalid}>Enter your name.</FieldError>
-        </Field>
-        <Field invalid={emailInvalid}>
-          <FieldLabel>Work email</FieldLabel>
-          <Input
-            type="email"
-            leadingIcon={Mail}
-            autoComplete="email"
-            placeholder="name@company.com"
-            value={email}
-            onValueChange={setEmail}
-            required
-          />
-          <FieldError match={emailInvalid}>Enter a valid email address.</FieldError>
-        </Field>
+        {fields !== undefined && submitted && (
+          // Destructive text needs an untinted surface to meet contrast in the light theme.
+          <ValidationSummary errors={summaryErrors} submitCount={submitCount} className="bg-background" />
+        )}
+        {fields !== undefined ? (
+          fields.map((field) => {
+            const message = authSignUpFieldError(fieldValue(field.id), field);
+            const invalid = submitted && message !== null;
+            return (
+              <Field key={field.id} invalid={invalid}>
+                <FieldLabel>{field.label}</FieldLabel>
+                <Input
+                  id={`${fieldPrefix}-field-${field.id}`}
+                  type={field.type ?? 'text'}
+                  autoComplete={field.autoComplete}
+                  placeholder={field.placeholder}
+                  required={field.required}
+                  value={fieldValue(field.id)}
+                  onValueChange={(value) => setFieldValues((values) => ({ ...values, [field.id]: value }))}
+                />
+                {field.help != null && <FieldDescription>{field.help}</FieldDescription>}
+                <FieldError match={invalid}>{message}</FieldError>
+              </Field>
+            );
+          })
+        ) : (
+          <>
+            <Field invalid={nameInvalid}>
+              <FieldLabel>Full name</FieldLabel>
+              <Input
+                leadingIcon={User}
+                autoComplete="name"
+                placeholder="Avery Collins"
+                value={name}
+                onValueChange={setName}
+                required
+              />
+              <FieldError match={nameInvalid}>Enter your name.</FieldError>
+            </Field>
+            <Field invalid={emailInvalid}>
+              <FieldLabel>Work email</FieldLabel>
+              <Input
+                type="email"
+                leadingIcon={Mail}
+                autoComplete="email"
+                placeholder="name@company.com"
+                value={email}
+                onValueChange={setEmail}
+                required
+              />
+              <FieldError match={emailInvalid}>Enter a valid email address.</FieldError>
+            </Field>
+          </>
+        )}
         <Field invalid={passwordInvalid}>
           <FieldLabel>Password</FieldLabel>
-          <PasswordInput showStrength value={password} onValueChange={setPassword} required />
-          <FieldError match={passwordInvalid}>Use at least {minPasswordLength} characters.</FieldError>
-        </Field>
-        <div>
-          <Checkbox
-            checked={terms}
-            onCheckedChange={setTerms}
-            aria-invalid={termsInvalid || undefined}
-            aria-describedby={termsInvalid ? termsErrorId : undefined}
-            label={
-              <>
-                I agree to the <Link href={termsHref}>Terms</Link> and <Link href={privacyHref}>Privacy Policy</Link>.
-              </>
-            }
+          <PasswordInput
+            id={fields !== undefined ? passwordId : undefined}
+            showStrength
+            strength={password.length > 0 && password.length < minPasswordLength ? 0 : undefined}
+            value={password}
+            onValueChange={setPassword}
+            required
           />
-          {termsInvalid && (
-            <p id={termsErrorId} className="mt-1.5 text-[12.5px] text-destructive-text">
-              Accept the terms to continue.
-            </p>
+          {passwordHelp != null && (
+            <FieldDescription>
+              {typeof passwordHelp === 'function' ? passwordHelp(minPasswordLength) : passwordHelp}
+            </FieldDescription>
           )}
-        </div>
+          <FieldError match={passwordInvalid}>{passwordError}</FieldError>
+        </Field>
+        {termsProp !== false && (
+          <div>
+            <Checkbox
+              render={fields !== undefined ? <span id={termsId} /> : undefined}
+              checked={terms}
+              onCheckedChange={setTerms}
+              aria-invalid={termsInvalid || undefined}
+              aria-describedby={termsInvalid ? termsErrorId : undefined}
+              label={
+                <>
+                  I agree to the <Link href={termsHref}>Terms</Link> and <Link href={privacyHref}>Privacy Policy</Link>.
+                </>
+              }
+            />
+            {termsInvalid && (
+              <p id={termsErrorId} className="mt-1.5 text-[12.5px] text-destructive-text">
+                {termsError}
+              </p>
+            )}
+          </div>
+        )}
         <Button type="submit" size="lg" loading={busy} className="mt-2 w-full">
           Create account
         </Button>

package/src/auth/SignUpForm/block.meta.ts

@@ -4,6 +4,19 @@ export const meta: BlockMeta = {
   name: 'Sign-up form',
   family: 'auth',
   status: 'stable',
-  description: 'Account creation with name, email, a password strength meter and a required terms checkbox.',
-  uses: ['Field', 'Input', 'PasswordInput', 'Checkbox', 'Button', 'Alert', 'Link', 'SsoButtons'],
+  description:
+    'Account creation with default name/email fields or ordered text/email fields (values.fields), a password strength meter and required consent (terms=false opts out). minPasswordLength defaults to 8 and drives length validation and the insufficient-length meter; optional passwordHelp can receive the minimum. Configured fields support help, required, autoComplete and validation messages, with a linked validation summary on invalid submit. policyLoading renders skeletons without a form; unavailable replaces the form with consumer title, message and optional action. loading remains submitting; error is form-level feedback. Examples: custom-fields, no-terms, unavailable, loading, submitting and error.',
+  uses: [
+    'Field',
+    'Input',
+    'PasswordInput',
+    'Checkbox',
+    'Button',
+    'Alert',
+    'Link',
+    'SsoButtons',
+    'Skeleton',
+    'FieldDescription',
+    'ValidationSummary',
+  ],
 };