@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/auth/SignUpForm/SignUpForm.tsx

@@ -0,0 +1,298 @@
+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,
+  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;
+  /** 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;
+  onSignIn?: () => void;
+  /** SSO area under the divider; defaults to SsoButtons, `null` hides it. */
+  sso?: ReactNode;
+  eyebrow?: ReactNode;
+  title?: ReactNode;
+  description?: ReactNode;
+  className?: string;
+}
+
+/** 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 = '#',
+  onSignIn,
+  sso = <SsoButtons />,
+  eyebrow = 'Get started',
+  title = 'Create your account',
+  description = 'Set up a workspace for your team in a couple of minutes.',
+  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('');
+  const [terms, setTerms] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const { loading, error, run } = useAsyncSubmit('The account could not be created.');
+  const busy = loadingProp ?? loading;
+  const alert = errorProp ?? error;
+  const nameInvalid = submitted && name.trim() === '';
+  const emailInvalid = submitted && !EMAIL_RE.test(email.trim());
+  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)}>
+      <AuthHeader eyebrow={eyebrow} title={title} description={description} />
+      <form
+        noValidate
+        aria-label="Create account"
+        className="flex flex-col gap-4"
+        onSubmit={(e) => {
+          e.preventDefault();
+          setSubmitted(true);
+          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} />}
+        {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
+            id={fields !== undefined ? passwordId : undefined}
+            showStrength
+            strength={password.length > 0 && password.length < minPasswordLength ? 0 : undefined}
+            value={password}
+            onValueChange={setPassword}
+            required
+          />
+          {passwordHelp != null && (
+            <FieldDescription>
+              {typeof passwordHelp === 'function' ? passwordHelp(minPasswordLength) : passwordHelp}
+            </FieldDescription>
+          )}
+          <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>
+      </form>
+      {sso != null && (
+        <>
+          <AuthDivider>Or sign up with</AuthDivider>
+          {sso}
+        </>
+      )}
+      <p className="mt-7 text-center text-[13px] text-muted-foreground">
+        Already have an account?{' '}
+        <Link
+          href={signInHref}
+          onClick={
+            onSignIn
+              ? (e: MouseEvent) => {
+                  e.preventDefault();
+                  onSignIn();
+                }
+              : undefined
+          }
+        >
+          Sign in
+        </Link>
+      </p>
+    </div>
+  );
+}

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

@@ -0,0 +1,22 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Sign-up form',
+  family: 'auth',
+  status: 'stable',
+  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',
+  ],
+};

package/src/auth/SignUpForm/examples/CustomFields.tsx

@@ -0,0 +1,56 @@
+import { SignUpForm } from '../SignUpForm';
+
+/** Ordered text/email fields, kit validation, and values.fields keyed by these ids. */
+export default function CustomFields() {
+  return (
+    <SignUpForm
+      sso={null}
+      minPasswordLength={12}
+      passwordHelp={(minimum) => `Use at least ${minimum} characters.`}
+      fields={[
+        {
+          id: 'username',
+          label: 'Username',
+          placeholder: 'Account name',
+          help: 'Choose your account name.',
+          required: true,
+          type: 'text',
+          autoComplete: 'username',
+        },
+        {
+          id: 'displayName',
+          label: 'Display name',
+          placeholder: 'Avery Collins',
+          help: 'The name others will see.',
+          required: true,
+          autoComplete: 'name',
+        },
+        {
+          id: 'email',
+          label: 'Email',
+          placeholder: 'you@example.com',
+          help: 'For account notifications.',
+          required: true,
+          type: 'email',
+          autoComplete: 'email',
+        },
+        {
+          id: 'tenant',
+          label: 'Tenant identifier',
+          placeholder: 'Organization',
+          help: 'Your organization identifier.',
+          required: true,
+          autoComplete: 'off',
+        },
+        {
+          id: 'workspace',
+          label: 'Workspace identifier',
+          placeholder: 'Workspace',
+          help: 'Optional. Leave empty to choose later.',
+          required: false,
+          autoComplete: 'off',
+        },
+      ]}
+    />
+  );
+}

package/src/auth/SignUpForm/examples/Error.tsx

@@ -0,0 +1,5 @@
+import { SignUpForm } from '../SignUpForm';
+
+export default function Error() {
+  return <SignUpForm error="The account could not be created. Try again." sso={null} />;
+}

package/src/auth/SignUpForm/examples/Loading.tsx

@@ -0,0 +1,6 @@
+import { SignUpForm } from '../SignUpForm';
+
+/** Policy loading is separate from loading, which represents submitting an account. */
+export default function Loading() {
+  return <SignUpForm policyLoading />;
+}

package/src/auth/SignUpForm/examples/NoTerms.tsx

@@ -0,0 +1,6 @@
+import { SignUpForm } from '../SignUpForm';
+
+/** Explicit opt-out; omitting terms continues to require consent. */
+export default function NoTerms() {
+  return <SignUpForm terms={false} sso={null} passwordHelp={(minimum) => `Use at least ${minimum} characters.`} />;
+}

package/src/auth/SignUpForm/examples/Submitting.tsx

@@ -0,0 +1,5 @@
+import { SignUpForm } from '../SignUpForm';
+
+export default function Submitting() {
+  return <SignUpForm loading sso={null} />;
+}

package/src/auth/SignUpForm/examples/Unavailable.tsx

@@ -0,0 +1,15 @@
+import { Link } from '@gntik-ai/ui';
+import { SignUpForm } from '../SignUpForm';
+
+/** No account creation form or submit control while self-service is unavailable. */
+export default function Unavailable() {
+  return (
+    <SignUpForm
+      unavailable={{
+        title: 'Registration unavailable',
+        message: 'Contact your administrator to request an account.',
+        action: <Link href="mailto:admin@example.com">Request access</Link>,
+      }}
+    />
+  );
+}

package/src/auth/SsoButtons/SsoButtons.test.tsx

@@ -0,0 +1,23 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { SsoButtons } from './SsoButtons';
+
+describe('SsoButtons', () => {
+  it('renders the default providers in a named group', async () => {
+    const { container } = render(<SsoButtons />);
+    expect(screen.getByRole('group', { name: 'Single sign-on' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Continue with SSO' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('reports the chosen provider and shows its loading state', async () => {
+    const onSelect = vi.fn();
+    const { rerender } = render(<SsoButtons onSelect={onSelect} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Continue with Google' }));
+    expect(onSelect).toHaveBeenCalledWith('google');
+    rerender(<SsoButtons onSelect={onSelect} loadingId="google" />);
+    expect(screen.getByRole('button', { name: 'Continue with Google' })).toHaveAttribute('aria-busy', 'true');
+    expect(screen.getByRole('button', { name: 'Continue with SSO' })).toBeDisabled();
+  });
+});

package/src/auth/SsoButtons/SsoButtons.tsx

@@ -0,0 +1,52 @@
+import { Button, cn } from '@gntik-ai/ui';
+import { ssoProviders, type SsoProvider } from './fixtures';
+
+export type { SsoProvider } from './fixtures';
+
+export interface SsoButtonsProps {
+  providers?: SsoProvider[];
+  /** Called with the provider id. */
+  onSelect?: (providerId: string) => void;
+  /** Provider currently redirecting (shows a spinner and disables the others). */
+  loadingId?: string | null;
+  disabled?: boolean;
+  /** `stack` (full-width rows, default) or `grid` (two columns from `sm`). */
+  layout?: 'stack' | 'grid';
+  /** Accessible name of the group. */
+  label?: string;
+  className?: string;
+}
+
+/** Neutral single-sign-on buttons: text labels and lucide icons, no brand colours or logos. */
+export function SsoButtons({
+  providers = ssoProviders,
+  onSelect,
+  loadingId = null,
+  disabled = false,
+  layout = 'stack',
+  label = 'Single sign-on',
+  className,
+}: SsoButtonsProps) {
+  return (
+    <div
+      role="group"
+      aria-label={label}
+      className={cn('grid gap-2.5', layout === 'grid' && 'sm:grid-cols-2', className)}
+    >
+      {providers.map((p) => (
+        <Button
+          key={p.id}
+          variant="secondary"
+          size="lg"
+          icon={p.icon}
+          loading={loadingId === p.id}
+          disabled={disabled || (loadingId != null && loadingId !== p.id)}
+          onClick={() => onSelect?.(p.id)}
+          className="w-full text-[13.5px] font-medium"
+        >
+          {p.label}
+        </Button>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,9 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'SSO buttons',
+  family: 'auth',
+  status: 'stable',
+  description: 'Neutral "Continue with …" provider buttons with lucide icons and a per-provider loading state.',
+  uses: ['Button'],
+};

package/src/auth/SsoButtons/fixtures.ts

@@ -0,0 +1,15 @@
+import { Building2, Globe, KeyRound, type LucideIcon } from '@gntik-ai/icons';
+
+export interface SsoProvider {
+  id: string;
+  /** Full button text, e.g. "Continue with SSO". */
+  label: string;
+  /** A neutral lucide icon (no brand logos or colours). */
+  icon?: LucideIcon;
+}
+
+export const ssoProviders: SsoProvider[] = [
+  { id: 'sso', label: 'Continue with SSO', icon: Building2 },
+  { id: 'google', label: 'Continue with Google', icon: Globe },
+  { id: 'passkey', label: 'Continue with a passkey', icon: KeyRound },
+];

package/src/auth/index.ts

@@ -0,0 +1,16 @@
+export * from './ForgotPasswordForm/ForgotPasswordForm';
+export { meta as forgotPasswordFormMeta } from './ForgotPasswordForm/block.meta';
+export * from './MfaChallenge/MfaChallenge';
+export { meta as mfaChallengeMeta } from './MfaChallenge/block.meta';
+export * from './ResetPasswordForm/ResetPasswordForm';
+export { meta as resetPasswordFormMeta } from './ResetPasswordForm/block.meta';
+export * from './SignInForm/SignInForm';
+export { meta as signInFormMeta } from './SignInForm/block.meta';
+export * from './SignUpForm/SignUpForm';
+export { meta as signUpFormMeta } from './SignUpForm/block.meta';
+export * from './SsoButtons/SsoButtons';
+export { meta as ssoButtonsMeta } from './SsoButtons/block.meta';
+export { ssoProviders } from './SsoButtons/fixtures';
+export { AuthHeader, AuthDivider, type AuthHeaderProps } from './shared';
+export type { AuthIdentifierConfig, AuthValidationMessages, AuthFormAccessibilityProps } from './shared';
+export type { AuthSignUpField, AuthUnavailableState, AuthSignUpValidationMessages } from './shared';