@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/ai/TraceWaterfall/fixtures.ts

@@ -0,0 +1,133 @@
+export type SpanKind = 'chain' | 'llm' | 'tool' | 'retrieval' | 'http';
+
+export interface TraceSpan {
+  id: string;
+  /** Parent span id; omit for the root span(s). */
+  parentId?: string;
+  name: string;
+  kind: SpanKind;
+  /** Start offset from the trace start, in ms. */
+  start: number;
+  /** Duration in ms. */
+  duration: number;
+  /** `running`: still in progress (its `duration` is the time elapsed so far). */
+  status: 'ok' | 'error' | 'running';
+  /** Extra key/value details shown in the side panel. */
+  attributes?: Record<string, string | number>;
+}
+
+export const traceSpans: TraceSpan[] = [
+  {
+    id: 's1',
+    name: 'POST /v1/answer',
+    kind: 'http',
+    start: 0,
+    duration: 2450,
+    status: 'ok',
+    attributes: { 'http.status': 200, 'request.id': 'req_7f3a' },
+  },
+  {
+    id: 's2',
+    parentId: 's1',
+    name: 'retrieve context',
+    kind: 'retrieval',
+    start: 40,
+    duration: 380,
+    status: 'ok',
+    attributes: { documents: 8 },
+  },
+  {
+    id: 's3',
+    parentId: 's2',
+    name: 'embed query',
+    kind: 'llm',
+    start: 45,
+    duration: 115,
+    status: 'ok',
+    attributes: { model: 'embed-small', 'tokens.input': 24 },
+  },
+  {
+    id: 's4',
+    parentId: 's2',
+    name: 'vector search',
+    kind: 'retrieval',
+    start: 170,
+    duration: 240,
+    status: 'ok',
+    attributes: { index: 'docs-v3', topK: 8 },
+  },
+  {
+    id: 's5',
+    parentId: 's1',
+    name: 'generate answer',
+    kind: 'llm',
+    start: 440,
+    duration: 1760,
+    status: 'ok',
+    attributes: { model: 'general-large', 'tokens.input': 3120, 'tokens.output': 412, temperature: 0.2 },
+  },
+  {
+    id: 's6',
+    parentId: 's5',
+    name: 'tool: lookup_order',
+    kind: 'tool',
+    start: 900,
+    duration: 150,
+    status: 'error',
+    attributes: { error: 'timeout after 150ms' },
+  },
+  {
+    id: 's7',
+    parentId: 's5',
+    name: 'tool: lookup_order (retry)',
+    kind: 'tool',
+    start: 1060,
+    duration: 240,
+    status: 'ok',
+    attributes: { attempt: 2 },
+  },
+  { id: 's8', parentId: 's1', name: 'format response', kind: 'chain', start: 2210, duration: 220, status: 'ok' },
+];
+
+/** A trace still in progress: the answer is being generated. */
+export const runningTraceSpans: TraceSpan[] = [
+  {
+    id: 'r1',
+    name: 'POST /v1/answer',
+    kind: 'http',
+    start: 0,
+    duration: 1840,
+    status: 'running',
+    attributes: { 'request.id': 'req_9c21' },
+  },
+  {
+    id: 'r2',
+    parentId: 'r1',
+    name: 'retrieve context',
+    kind: 'retrieval',
+    start: 30,
+    duration: 410,
+    status: 'ok',
+    attributes: { documents: 6 },
+  },
+  {
+    id: 'r3',
+    parentId: 'r1',
+    name: 'generate answer',
+    kind: 'llm',
+    start: 450,
+    duration: 1390,
+    status: 'running',
+    attributes: { model: 'general-large', 'tokens.output': 188 },
+  },
+  {
+    id: 'r4',
+    parentId: 'r3',
+    name: 'tool: search_docs',
+    kind: 'tool',
+    start: 620,
+    duration: 310,
+    status: 'ok',
+    attributes: { results: 4 },
+  },
+];

package/src/ai/TraceWaterfall/span-details.tsx

@@ -0,0 +1,51 @@
+import { Badge, StatusTag } from '@gntik-ai/ui';
+import type { TraceSpan } from './fixtures';
+
+/** StatusTag dictionary of span statuses (running is announced by its label, not colour alone). */
+export const SPAN_STATUSES = {
+  ok: { label: 'OK', tone: 'success' },
+  error: { label: 'Error', tone: 'destructive' },
+  running: { label: 'Running', tone: 'info' },
+} as const;
+
+export function formatSpanDuration(ms: number) {
+  return ms >= 1000 ? `${(ms / 1000).toFixed(ms >= 10000 ? 1 : 2)}s` : `${Math.round(ms)}ms`;
+}
+
+export interface SpanDetailsProps {
+  span: TraceSpan;
+  /** Heading level of the span name. */
+  headingAs: 'h3' | 'h4' | 'h5';
+}
+
+/** Default content of the details pane: name, kind, status, timing and attributes. */
+export function SpanDetails({ span, headingAs: Heading }: SpanDetailsProps) {
+  return (
+    <div className="flex flex-col gap-3">
+      <div>
+        <Heading className="text-[13.5px] font-semibold break-words text-foreground">{span.name}</Heading>
+        <div className="mt-1.5 flex flex-wrap items-center gap-1.5">
+          <Badge variant="soft" size="sm">
+            {span.kind}
+          </Badge>
+          <StatusTag size="sm" status={span.status} statuses={SPAN_STATUSES} />
+        </div>
+      </div>
+      <dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1.5 text-[12px]">
+        <dt className="text-muted-foreground">Start</dt>
+        <dd className="font-mono text-foreground">+{formatSpanDuration(span.start)}</dd>
+        <dt className="text-muted-foreground">{span.status === 'running' ? 'Elapsed' : 'Duration'}</dt>
+        <dd className="font-mono text-foreground">
+          {formatSpanDuration(span.duration)}
+          {span.status === 'running' && <span className="font-sans text-muted-foreground"> (in progress)</span>}
+        </dd>
+        {Object.entries(span.attributes ?? {}).map(([k, v]) => (
+          <div key={k} className="contents">
+            <dt className="truncate text-muted-foreground">{k}</dt>
+            <dd className="font-mono break-words text-foreground">{String(v)}</dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}

package/src/ai/index.ts

@@ -0,0 +1,13 @@
+export * from './AssistantCardGrid/AssistantCardGrid';
+export { meta as assistantCardGridMeta } from './AssistantCardGrid/block.meta';
+export * from './TraceWaterfall/TraceWaterfall';
+export { meta as traceWaterfallMeta } from './TraceWaterfall/block.meta';
+export { traceSpans, runningTraceSpans } from './TraceWaterfall/fixtures';
+export * from './TokenCostCard/TokenCostCard';
+export { meta as tokenCostCardMeta } from './TokenCostCard/block.meta';
+export * from './PromptEditor/PromptEditor';
+export { meta as promptEditorMeta } from './PromptEditor/block.meta';
+export * from './EvaluationScorecard/EvaluationScorecard';
+export { meta as evaluationScorecardMeta } from './EvaluationScorecard/block.meta';
+export * from './ModelKeysList/ModelKeysList';
+export { meta as modelKeysListMeta } from './ModelKeysList/block.meta';

package/src/auth/ForgotPasswordForm/ForgotPasswordForm.test.tsx

@@ -0,0 +1,209 @@
+import { ThemeProvider } from '@gntik-ai/ui';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef } from 'react';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { ForgotPasswordForm, type ForgotPasswordFormRef } from './ForgotPasswordForm';
+
+describe('ForgotPasswordForm', () => {
+  it('can hide or replace inbox copy and both resend actions', () => {
+    const { rerender } = render(
+      <ForgotPasswordForm defaultSent sentTitle={null} sentDescription={null} sentStatus={null} resendActions={null} />,
+    );
+    expect(screen.queryByText('Check your email')).not.toBeInTheDocument();
+    expect(screen.queryByText(/If an account exists/)).not.toBeInTheDocument();
+    expect(screen.queryByText('Reset link sent.')).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Resend link' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: 'Use a different email' })).not.toBeInTheDocument();
+    rerender(
+      <ForgotPasswordForm
+        sentTitle="Request received"
+        sentDescription="If eligible, instructions will arrive."
+        sentStatus="Request received."
+        resendActions={<a href="#help">Get help</a>}
+      />,
+    );
+    expect(screen.getByRole('heading', { name: 'Request received' })).toBeInTheDocument();
+    expect(screen.getByRole('status')).toHaveTextContent('Request received.');
+    expect(screen.getByRole('link', { name: 'Get help' })).toBeInTheDocument();
+  });
+
+  it('configures request and sent copy and heading levels, including suppression', () => {
+    const { container, rerender } = render(
+      <ForgotPasswordForm title="Recover access" description="Enter your account name." headingLevel="h2" />,
+    );
+    expect(screen.getByRole('heading', { level: 2, name: 'Recover access' })).toBeInTheDocument();
+    expect(screen.getByText('Enter your account name.')).toBeInTheDocument();
+    rerender(<ForgotPasswordForm headingLevel={null} aria-label="Recover access" />);
+    expect(container.querySelector('h1,h2,h3,h4,h5,h6,[role="heading"]')).toBeNull();
+    expect(screen.getByRole('form', { name: 'Recover access' })).toBeInTheDocument();
+    rerender(
+      <ForgotPasswordForm
+        key="sent"
+        defaultSent
+        sentTitle="Request received"
+        sentDescription="If eligible, you will receive instructions."
+        headingLevel="h2"
+      />,
+    );
+    expect(screen.getByRole('heading', { level: 2, name: 'Request received' })).toBeInTheDocument();
+    expect(screen.getByText('If eligible, you will receive instructions.')).toBeInTheDocument();
+    rerender(<ForgotPasswordForm key="sent" headingLevel={null} />);
+    expect(container.querySelector('h1,h2,h3,h4,h5,h6,[role="heading"]')).toBeNull();
+  });
+
+  it('exposes identifier focus and preserves server feedback and help associations', () => {
+    const ref = createRef<ForgotPasswordFormRef>();
+    render(
+      <ForgotPasswordForm
+        ref={ref}
+        identifier={{ help: 'Account email', helpId: 'email-help' }}
+        fieldInvalid={{ identifier: true }}
+        feedbackId="recovery-feedback"
+        aria-describedby="form-feedback"
+        error="Request could not be completed."
+      />,
+    );
+    const input = screen.getByLabelText('Email');
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+    expect(input.getAttribute('aria-describedby')?.split(' ')).toEqual(
+      expect.arrayContaining(['email-help', 'recovery-feedback']),
+    );
+    expect(screen.getByRole('form', { name: 'Reset password request' })).toHaveAttribute(
+      'aria-describedby',
+      'form-feedback',
+    );
+    expect(screen.getByRole('alert')).toHaveAttribute('id', 'recovery-feedback');
+    ref.current?.focus('identifier');
+    expect(input).toHaveFocus();
+  });
+
+  it('uses consumer validation messages, focuses the identifier and chains help and errors', async () => {
+    const onSubmit = vi.fn();
+    render(
+      <ForgotPasswordForm
+        identifier={{ type: 'text', label: 'Username', help: 'Account name', helpId: 'recovery-help', minLength: 3 }}
+        messages={{ identifierRequired: 'Username is required.', identifierTooShort: 'Username is too short.' }}
+        onSubmit={onSubmit}
+      />,
+    );
+    const input = screen.getByLabelText('Username');
+    expect(input).not.toHaveAttribute('aria-invalid');
+    expect(screen.getByRole('form', { name: 'Reset password request' })).toHaveAttribute('novalidate');
+    await userEvent.click(screen.getByRole('button', { name: 'Send reset link' }));
+    expect(input).toHaveFocus();
+    expect(onSubmit).not.toHaveBeenCalled();
+    const error = screen.getByText('Username is required.').closest('[role="alert"]');
+    expect(error).toBeInTheDocument();
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+    expect(input.getAttribute('aria-describedby')?.split(' ')).toEqual(
+      expect.arrayContaining(['recovery-help', error?.id]),
+    );
+    await userEvent.type(input, 'ab');
+    expect(screen.getByText('Username is too short.')).toBeInTheDocument();
+    await userEvent.type(input, 'c');
+    expect(input).not.toHaveAttribute('aria-invalid');
+    expect(input).toHaveAccessibleDescription('Account name');
+  });
+
+  it('accepts a username-or-email configuration and submits the trimmed value', async () => {
+    const onSubmit = vi.fn();
+    render(
+      <ForgotPasswordForm
+        identifier={{
+          type: 'text',
+          autoComplete: 'username',
+          label: 'Username or email',
+          help: 'Use your account name or email.',
+          placeholder: 'Account name',
+          maxLength: 255,
+        }}
+        onSubmit={onSubmit}
+      />,
+    );
+    const input = screen.getByRole('textbox', { name: 'Username or email' });
+    expect(input).toHaveAttribute('type', 'text');
+    expect(input).toHaveAttribute('autocomplete', 'username');
+    expect(input).toHaveAttribute('maxlength', '255');
+    expect(input).toHaveAttribute('placeholder', 'Account name');
+    expect(input).toHaveAccessibleDescription('Use your account name or email.');
+    await userEvent.type(input, '  avery  ');
+    await userEvent.click(screen.getByRole('button', { name: 'Send reset link' }));
+    expect(onSubmit).toHaveBeenCalledWith('avery');
+  });
+
+  it('renders the request step', async () => {
+    const { container } = render(<ForgotPasswordForm />);
+    expect(screen.getByRole('heading', { name: 'Forgot your password?' })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('sends the link and shows the sent state', async () => {
+    const onSubmit = vi.fn().mockResolvedValue(undefined);
+    const { container } = render(<ForgotPasswordForm onSubmit={onSubmit} />);
+    await userEvent.type(screen.getByLabelText('Email'), 'avery@example.com');
+    await userEvent.click(screen.getByRole('button', { name: 'Send reset link' }));
+    expect(onSubmit).toHaveBeenCalledWith('avery@example.com');
+    expect(await screen.findByRole('heading', { name: 'Check your email' })).toBeInTheDocument();
+    expect(screen.getByText('avery@example.com')).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Resend link' }));
+    expect(onSubmit).toHaveBeenCalledTimes(2);
+    await expectNoAxeViolations(container);
+  });
+});
+
+// Public rendering seams: identifier mode, theme, heading policy and validation/recovery state.
+describe('ForgotPasswordForm accessibility matrix', () => {
+  for (const theme of ['dark', 'light', 'high_contrast'] as const) {
+    for (const mode of ['email', 'username'] as const) {
+      for (const suppressed of [false, true]) {
+        for (const state of ['initial', 'errors', 'sent'] as const) {
+          it(`${theme} / ${mode} / headings ${!suppressed} / ${state}`, async () => {
+            const onSubmit = vi.fn();
+            const { container } = render(
+              <ThemeProvider defaultMode={theme} storageKey={null}>
+                <h1>Account access</h1>
+                <ForgotPasswordForm
+                  identifier={
+                    mode === 'username'
+                      ? {
+                          type: 'text',
+                          autoComplete: 'username',
+                          label: 'Username',
+                          help: 'Use your account name.',
+                          minLength: 3,
+                          maxLength: 255,
+                        }
+                      : undefined
+                  }
+                  headingLevel={suppressed ? null : undefined}
+                  defaultSent={state === 'sent'}
+                  messages={{
+                    identifierRequired: 'Account name is required.',
+                    passwordRequired: 'Password is required.',
+                  }}
+                  onSubmit={onSubmit}
+                />
+              </ThemeProvider>,
+            );
+            if (state === 'initial' || state === 'errors') {
+              const input = screen.getByRole('textbox', { name: mode === 'username' ? 'Username' : 'Email' });
+              expect(input).toHaveAttribute('type', mode === 'username' ? 'text' : 'email');
+              expect(input).toHaveAttribute('autocomplete', mode === 'username' ? 'username' : 'email');
+              expect(screen.getByRole('form', { name: 'Reset password request' })).toHaveAttribute('novalidate');
+              if (state === 'errors') {
+                await userEvent.click(screen.getByRole('button', { name: 'Send reset link' }));
+                expect(input).toHaveFocus();
+                expect(input).toHaveAttribute('aria-invalid', 'true');
+                expect(onSubmit).not.toHaveBeenCalled();
+                expect(screen.getByText('Account name is required.')).toBeInTheDocument();
+              }
+            }
+            if (suppressed) expect(container.querySelectorAll('h1,h2,h3,h4,h5,h6,[role="heading"]')).toHaveLength(1);
+            await expectNoAxeViolations(container);
+          });
+        }
+      }
+    }
+  }
+});

package/src/auth/ForgotPasswordForm/ForgotPasswordForm.tsx

@@ -0,0 +1,211 @@
+import { Alert, Button, Field, FieldDescription, FieldError, FieldLabel, Input, Link, cn } from '@gntik-ai/ui';
+import { ArrowLeft, Mail, MailCheck } from '@gntik-ai/icons';
+import { useImperativeHandle, useRef, useState, type MouseEvent, type ReactNode, type Ref } from 'react';
+import {
+  AuthHeader,
+  authIdentifierError,
+  authFormClass,
+  useAsyncSubmit,
+  type AuthIdentifierConfig,
+  type AuthValidationMessages,
+  type AuthFormAccessibilityProps,
+  type AuthHeaderProps,
+} from '../shared';
+
+export interface ForgotPasswordFormRef {
+  focus(field: 'identifier'): void;
+}
+
+export interface ForgotPasswordFormProps extends AuthFormAccessibilityProps {
+  /** React 19 ref for focus after a server response; available in the request state. */
+  ref?: Ref<ForgotPasswordFormRef>;
+  identifier?: AuthIdentifierConfig;
+  /** The kit validates before submit. Supply copy here; do not add a second inline validator. */
+  messages?: AuthValidationMessages;
+  /** Requests the reset link. A returned promise shows the loading state; a rejection shows in the alert. */
+  onSubmit?: (email: string) => void | Promise<void>;
+  error?: string | null;
+  defaultEmail?: string;
+  /** Start on the "sent" step (e.g. after a redirect). */
+  defaultSent?: boolean;
+  signInHref?: string;
+  onBackToSignIn?: () => void;
+  eyebrow?: ReactNode;
+  title?: ReactNode;
+  description?: ReactNode;
+  sentTitle?: ReactNode;
+  sentDescription?: ReactNode;
+  /** Replaces the screen-reader sent announcement; `null` hides it. */
+  sentStatus?: ReactNode;
+  /** Replaces both resend/change-identifier actions; `null` hides them. */
+  resendActions?: ReactNode;
+  /** Applies to both request and sent states. `null` omits the internal heading. */
+  headingLevel?: AuthHeaderProps['headingLevel'];
+  className?: string;
+}
+
+/** Request a reset link by email, then a "check your inbox" state with resend and a way back. */
+export function ForgotPasswordForm({
+  identifier,
+  messages,
+  ref,
+  fieldInvalid,
+  feedbackId,
+  'aria-describedby': describedBy,
+  'aria-label': ariaLabel = 'Reset password request',
+  'aria-labelledby': labelledBy,
+  onSubmit,
+  error: errorProp,
+  defaultEmail = '',
+  defaultSent = false,
+  signInHref = '#',
+  onBackToSignIn,
+  eyebrow = 'Account recovery',
+  title = 'Forgot your password?',
+  description = "Enter the email you sign in with and we'll send you a reset link.",
+  sentTitle = 'Check your email',
+  sentDescription,
+  sentStatus = 'Reset link sent.',
+  resendActions,
+  headingLevel,
+  className,
+}: ForgotPasswordFormProps) {
+  const [email, setEmail] = useState(defaultEmail);
+  const [submitted, setSubmitted] = useState(false);
+  const [sent, setSent] = useState(defaultSent);
+  const { loading, error, run } = useAsyncSubmit('The reset link could not be sent.');
+  const alert = errorProp ?? error;
+  const identifierInput = useRef<HTMLInputElement>(null);
+  useImperativeHandle(ref, () => ({ focus: () => identifierInput.current?.focus() }), []);
+  const identifierError = authIdentifierError(email, identifier, messages);
+  const emailInvalid = submitted && identifierError !== null;
+
+  const send = async () => {
+    const ok = await run(() => onSubmit?.(email.trim()));
+    if (ok) setSent(true);
+  };
+
+  const back = (
+    <Link
+      href={signInHref}
+      tone="muted"
+      className="inline-flex items-center gap-1.5 text-[13px]"
+      onClick={
+        onBackToSignIn
+          ? (e: MouseEvent) => {
+              e.preventDefault();
+              onBackToSignIn();
+            }
+          : undefined
+      }
+    >
+      <ArrowLeft size={14} aria-hidden className="rtl:-scale-x-100" />
+      Back to sign in
+    </Link>
+  );
+
+  if (sent) {
+    return (
+      <div className={cn(authFormClass, className)}>
+        <span className="mb-5 grid size-11 place-items-center rounded-xl bg-primary/14 text-primary-chip-text">
+          <MailCheck size={20} aria-hidden />
+        </span>
+        <AuthHeader
+          eyebrow={eyebrow}
+          title={sentTitle}
+          headingLevel={headingLevel}
+          description={
+            sentDescription === undefined ? (
+              <>
+                If an account exists for{' '}
+                <span className="font-medium text-foreground">{email.trim() || 'that address'}</span>, you will receive
+                a link to reset your password. It expires in 1 hour.
+              </>
+            ) : (
+              sentDescription
+            )
+          }
+        />
+        {sentStatus != null && (
+          <div role="status" className="sr-only">
+            {sentStatus}
+          </div>
+        )}
+        {alert && <Alert id={feedbackId} tone="destructive" description={alert} className="mb-4" />}
+        {resendActions !== null && (
+          <div className="flex flex-col gap-2.5">
+            {resendActions === undefined ? (
+              <>
+                <Button variant="secondary" size="lg" loading={loading} className="w-full" onClick={() => void send()}>
+                  Resend link
+                </Button>
+                <Button
+                  variant="ghost"
+                  size="lg"
+                  className="w-full"
+                  onClick={() => {
+                    setSent(false);
+                    setSubmitted(false);
+                  }}
+                >
+                  Use a different email
+                </Button>
+              </>
+            ) : (
+              resendActions
+            )}
+          </div>
+        )}
+        <p className="mt-7 text-center">{back}</p>
+      </div>
+    );
+  }
+
+  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;
+          }
+          void send();
+        }}
+      >
+        {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>
+        <Button type="submit" size="lg" loading={loading} className="mt-2 w-full">
+          Send reset link
+        </Button>
+      </form>
+      <p className="mt-7 text-center">{back}</p>
+    </div>
+  );
+}

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

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Forgot password form',
+  family: 'auth',
+  status: 'stable',
+  description:
+    'Email (default) or username-or-email password recovery; onSubmit receives the trimmed identifier. 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. ref.focus accepts identifier. title/description and sentTitle/sentDescription configure request and sent copy; sentTitle, sentDescription, sentStatus and resendActions accept null to hide inbox copy, announcements and resend/change-identifier actions. Preview: forgot-password-form--username-or-email.',
+  uses: ['Field', 'FieldLabel', 'FieldDescription', 'FieldError', 'Input', 'Button', 'Alert', 'Link'],
+};

package/src/auth/ForgotPasswordForm/examples/UsernameOrEmail.tsx

@@ -0,0 +1,24 @@
+import { ForgotPasswordForm, type ForgotPasswordFormProps } from '../ForgotPasswordForm';
+
+/** /preview.html?kind=block&id=forgot-password-form--username-or-email */
+export default function UsernameOrEmail(props: Pick<ForgotPasswordFormProps, 'headingLevel'>) {
+  return (
+    <ForgotPasswordForm
+      {...props}
+      identifier={{
+        type: 'text',
+        autoComplete: 'username',
+        label: 'Username or email',
+        help: 'Use your account name or email address.',
+        placeholder: 'Account name or email',
+        maxLength: 255,
+      }}
+      messages={{ identifierRequired: 'Enter your username or email.' }}
+      description="Enter your account name or email to request recovery instructions."
+      sentTitle="Request received"
+      sentDescription="If the account is eligible, you will receive recovery instructions."
+      sentStatus="Recovery request received."
+      resendActions={null}
+    />
+  );
+}