@gntik-ai/blocks 0.0.0-stage → 0.5.0

package/src/auth/SignInForm/SignInForm.tsx

@@ -0,0 +1,226 @@
+import {
+  Alert,
+  Button,
+  Checkbox,
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  Input,
+  Link,
+  PasswordInput,
+  cn,
+} from '@gntik-ai/ui';
+import { Lock, Mail } from '@gntik-ai/icons';
+import { useImperativeHandle, useRef, useState, type MouseEvent, type ReactNode, type Ref } from 'react';
+import { SsoButtons } from '../SsoButtons/SsoButtons';
+import {
+  AuthDivider,
+  AuthHeader,
+  authIdentifierError,
+  authFormClass,
+  useAsyncSubmit,
+  type AuthIdentifierConfig,
+  type AuthValidationMessages,
+  type AuthFormAccessibilityProps,
+  type AuthHeaderProps,
+} from '../shared';
+
+export interface SignInValues {
+  email: string;
+  /** Trimmed identifier in text mode. `email` remains available for existing consumers. */
+  identifier?: string;
+  password: string;
+  remember: boolean;
+}
+
+export interface SignInFormRef {
+  focus(field: 'identifier' | 'password'): void;
+}
+
+export interface SignInFormProps extends AuthFormAccessibilityProps {
+  /** React 19 ref for focus after a server response. */
+  ref?: Ref<SignInFormRef>;
+  identifier?: AuthIdentifierConfig;
+  /** The kit validates before submit. Supply copy here; do not add a second inline validator. */
+  messages?: AuthValidationMessages;
+  passwordHelp?: ReactNode;
+  passwordHelpId?: string;
+  /** Signs in. A returned promise shows the loading state; a rejection's message shows in the alert. */
+  onSubmit?: (values: SignInValues) => void | Promise<void>;
+  /** Error from the server (e.g. "Incorrect email or password"). */
+  error?: string | null;
+  /** Forces the loading state (when the parent tracks the request). */
+  loading?: boolean;
+  defaultEmail?: string;
+  forgotPasswordHref?: string;
+  onForgotPassword?: () => void;
+  signUpHref?: string;
+  onSignUp?: () => void;
+  /** Replaces the sign-up prompt; `null` hides it. Defaults to the existing account link. */
+  signUpPrompt?: ReactNode;
+  /** SSO area under the divider; defaults to SsoButtons, `null` hides it. */
+  sso?: ReactNode;
+  eyebrow?: ReactNode;
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Omit the internal heading with null; the form keeps its accessible name. */
+  headingLevel?: AuthHeaderProps['headingLevel'];
+  className?: string;
+}
+
+const linkHandler = (fn?: () => void) =>
+  fn
+    ? (e: MouseEvent) => {
+        e.preventDefault();
+        fn();
+      }
+    : undefined;
+
+/** Email + password sign-in with remember me, forgot-password link, SSO slot, error alert and loading. */
+export function SignInForm({
+  identifier,
+  messages,
+  passwordHelp,
+  passwordHelpId,
+  ref,
+  fieldInvalid,
+  feedbackId,
+  'aria-describedby': describedBy,
+  'aria-label': ariaLabel = 'Sign in',
+  'aria-labelledby': labelledBy,
+  onSubmit,
+  error: errorProp,
+  loading: loadingProp,
+  defaultEmail = '',
+  forgotPasswordHref = '#',
+  onForgotPassword,
+  signUpHref = '#',
+  onSignUp,
+  signUpPrompt,
+  sso = <SsoButtons />,
+  eyebrow = 'Secure access',
+  title = 'Sign in to your workspace',
+  description = 'Use your work email to continue.',
+  headingLevel,
+  className,
+}: SignInFormProps) {
+  const [email, setEmail] = useState(defaultEmail);
+  const [password, setPassword] = useState('');
+  const [remember, setRemember] = useState(true);
+  const [submitted, setSubmitted] = useState(false);
+  const { loading, error, run } = useAsyncSubmit('Sign-in failed. Try again.');
+  const busy = loadingProp ?? loading;
+  const alert = errorProp ?? error;
+  const identifierInput = useRef<HTMLInputElement>(null);
+  const passwordInput = useRef<HTMLInputElement>(null);
+  useImperativeHandle(
+    ref,
+    () => ({
+      focus: (field) => (field === 'password' ? passwordInput : identifierInput).current?.focus(),
+    }),
+    [],
+  );
+  const identifierError = authIdentifierError(email, identifier, messages);
+  const emailInvalid = submitted && identifierError !== null;
+  const passwordInvalid = submitted && password === '';
+
+  return (
+    <div className={cn(authFormClass, className)}>
+      <AuthHeader eyebrow={eyebrow} title={title} description={description} headingLevel={headingLevel} />
+      <form
+        noValidate
+        aria-label={ariaLabel}
+        aria-labelledby={labelledBy}
+        aria-describedby={describedBy}
+        className="flex flex-col gap-4"
+        onSubmit={(e) => {
+          e.preventDefault();
+          setSubmitted(true);
+          if (identifierError !== null) {
+            identifierInput.current?.focus();
+            return;
+          }
+          if (password === '') {
+            passwordInput.current?.focus();
+            return;
+          }
+          void run(() =>
+            onSubmit?.({
+              email: email.trim(),
+              ...(identifier?.type === 'text' ? { identifier: email.trim() } : {}),
+              password,
+              remember,
+            }),
+          );
+        }}
+      >
+        {alert && <Alert id={feedbackId} tone="destructive" description={alert} />}
+        <Field invalid={emailInvalid || fieldInvalid?.identifier === true}>
+          <FieldLabel>{identifier?.label ?? 'Email'}</FieldLabel>
+          <Input
+            ref={identifierInput}
+            aria-describedby={fieldInvalid?.identifier ? feedbackId : undefined}
+            type={identifier?.type ?? 'email'}
+            leadingIcon={Mail}
+            autoComplete={identifier?.autoComplete ?? 'email'}
+            placeholder={identifier?.placeholder ?? 'name@company.com'}
+            minLength={identifier?.minLength}
+            maxLength={identifier?.maxLength}
+            value={email}
+            onValueChange={setEmail}
+            required
+          />
+          {identifier?.help != null && <FieldDescription id={identifier.helpId}>{identifier.help}</FieldDescription>}
+          <FieldError role="alert" match={emailInvalid}>
+            {identifierError}
+          </FieldError>
+        </Field>
+        <Field invalid={passwordInvalid || fieldInvalid?.password === true}>
+          <div className="flex items-center justify-between gap-3">
+            <FieldLabel>Password</FieldLabel>
+            <Link href={forgotPasswordHref} onClick={linkHandler(onForgotPassword)} className="text-[12.5px]">
+              Forgot password?
+            </Link>
+          </div>
+          <PasswordInput
+            ref={passwordInput}
+            aria-describedby={fieldInvalid?.password ? feedbackId : undefined}
+            leadingIcon={Lock}
+            value={password}
+            onValueChange={setPassword}
+            required
+          />
+          {passwordHelp != null && <FieldDescription id={passwordHelpId}>{passwordHelp}</FieldDescription>}
+          <FieldError role="alert" match={passwordInvalid}>
+            {messages?.passwordRequired ?? 'Enter your password.'}
+          </FieldError>
+        </Field>
+        <Checkbox label="Keep me signed in" checked={remember} onCheckedChange={setRemember} />
+        <Button type="submit" size="lg" loading={busy} className="mt-2 w-full">
+          Sign in
+        </Button>
+      </form>
+      {sso != null && (
+        <>
+          <AuthDivider>Or continue with</AuthDivider>
+          {sso}
+        </>
+      )}
+      {signUpPrompt !== null && (
+        <p className="mt-7 text-center text-[13px] text-muted-foreground">
+          {signUpPrompt === undefined ? (
+            <>
+              New here?{' '}
+              <Link href={signUpHref} onClick={linkHandler(onSignUp)}>
+                Create an account
+              </Link>
+            </>
+          ) : (
+            signUpPrompt
+          )}
+        </p>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,22 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Sign-in form',
+  family: 'auth',
+  status: 'stable',
+  description:
+    'Email (default) or text identifier and password sign-in. Supports identifier (type, autoComplete, label, help/helpId, placeholder, minLength/maxLength), messages (identifierRequired/identifierInvalid/identifierTooShort/passwordRequired), and React 19 ref.focus. The kit owns inline validation and focuses the first invalid field; consumers supply messages, not a second inline validator. Server errors use error + fieldInvalid + feedbackId; aria-describedby describes the form, while flagged inputs also retain their help and error ids. headingLevel (h1/h2/h3/null) suppresses the heading without losing the form name; aria-label/aria-labelledby override the default name. passwordHelp/passwordHelpId describe the password. Text submissions add values.identifier and retain values.email; email-mode payloads are unchanged. sso and signUpPrompt accept replacements or null. Preview: sign-in-form--username.',
+  uses: [
+    'Field',
+    'FieldLabel',
+    'FieldDescription',
+    'FieldError',
+    'Input',
+    'PasswordInput',
+    'Checkbox',
+    'Button',
+    'Alert',
+    'Link',
+    'SsoButtons',
+  ],
+};

package/src/auth/SignInForm/examples/Username.tsx

@@ -0,0 +1,26 @@
+import { SignInForm, type SignInFormProps } from '../SignInForm';
+
+/** /preview.html?kind=block&id=sign-in-form--username */
+export default function Username(props: Pick<SignInFormProps, 'headingLevel'>) {
+  return (
+    <SignInForm
+      {...props}
+      identifier={{
+        type: 'text',
+        autoComplete: 'username',
+        label: 'Username',
+        help: 'Use your account name.',
+        placeholder: 'Account name',
+        minLength: 3,
+        maxLength: 120,
+      }}
+      messages={{
+        identifierRequired: 'Enter your username.',
+        identifierInvalid: 'Use at least three characters.',
+        passwordRequired: 'Enter your password.',
+      }}
+      description="Use your account name to continue."
+      sso={null}
+    />
+  );
+}

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

@@ -0,0 +1,33 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { SignUpForm } from './SignUpForm';
+
+describe('SignUpForm', () => {
+  it('renders the default form', async () => {
+    const { container } = render(<SignUpForm />);
+    expect(screen.getByRole('form', { name: 'Create account' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('requires the terms and submits the values', async () => {
+    const onSubmit = vi.fn();
+    const { container } = render(<SignUpForm onSubmit={onSubmit} sso={null} />);
+    await userEvent.type(screen.getByLabelText('Full name'), 'Avery Collins');
+    await userEvent.type(screen.getByLabelText('Work email'), 'avery@example.com');
+    await userEvent.type(screen.getByLabelText('Password'), 'correct-horse-42');
+    expect(screen.getByText(/Strength:/)).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).not.toHaveBeenCalled();
+    const terms = screen.getByRole('checkbox', { name: /I agree/ });
+    expect(terms).toHaveAccessibleDescription('Accept the terms to continue.');
+    await expectNoAxeViolations(container);
+    await userEvent.click(terms);
+    await userEvent.click(screen.getByRole('button', { name: 'Create account' }));
+    expect(onSubmit).toHaveBeenCalledWith({
+      name: 'Avery Collins',
+      email: 'avery@example.com',
+      password: 'correct-horse-42',
+    });
+  });
+});

package/src/auth/SignUpForm/SignUpForm.tsx

@@ -0,0 +1,154 @@
+import { Alert, Button, Checkbox, Field, FieldError, FieldLabel, Input, Link, PasswordInput, 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';
+
+export interface SignUpValues {
+  name: string;
+  email: string;
+  password: string;
+}
+
+export interface SignUpFormProps {
+  /** 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. */
+  minPasswordLength?: number;
+  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({
+  onSubmit,
+  error: errorProp,
+  loading: loadingProp,
+  minPasswordLength = 8,
+  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 [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 && password.length < minPasswordLength;
+  const termsInvalid = submitted && !terms;
+
+  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 (name.trim() === '' || !EMAIL_RE.test(email.trim()) || password.length < minPasswordLength || !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>
+        <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>.
+              </>
+            }
+          />
+          {termsInvalid && (
+            <p id={termsErrorId} className="mt-1.5 text-[12.5px] text-destructive-text">
+              Accept the terms to continue.
+            </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,9 @@
+import type { BlockMeta } from '../../meta';
+
+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'],
+};

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,15 @@
+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';