@gntik-ai/templates 0.0.0-stage → 0.6.0

package/src/create-wizard/Overlay.test.tsx

@@ -0,0 +1,68 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { useState } from 'react';
+import { ErrorPanel, FirstRunEmpty } from '@gntik-ai/blocks';
+import CreateWizardPage from './Page';
+
+it('creates through an overlay of a mounted list, with step-local error and empty surfaces', async () => {
+  const user = userEvent.setup();
+  const onFinish = vi.fn();
+  function List() {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <main>
+          <h1>Projects</h1>
+          <input aria-label="Filter projects" defaultValue="Keep me" />
+          <button onClick={() => setOpen(true)}>New project</button>
+        </main>
+        <CreateWizardPage
+          mode="overlay"
+          open={open}
+          onOpenChange={setOpen}
+          description="Configure a project"
+          onFinish={(values) => {
+            onFinish(values);
+            setOpen(false);
+          }}
+          stepFeedback={(step) =>
+            step === 1 ? (
+              <ErrorPanel
+                title="Source unavailable"
+                message="Try again"
+                requestId=""
+                details=""
+                secondaryAction={null}
+              />
+            ) : step === 2 ? (
+              <FirstRunEmpty
+                title="No environments"
+                description="Create one later"
+                actionLabel="Continue setup"
+                secondary={null}
+                steps={[]}
+              />
+            ) : null
+          }
+        />
+      </>
+    );
+  }
+  render(<List />);
+  const filter = screen.getByRole('textbox', { name: 'Filter projects' });
+  const url = window.location.href;
+  await user.click(screen.getByRole('button', { name: 'New project' }));
+  await screen.findByRole('dialog', { name: 'New project' });
+  await user.type(screen.getByRole('textbox', { name: /Project name/ }), 'orders-api');
+  await user.click(screen.getByRole('button', { name: 'Next' }));
+  expect(screen.getByText('Source unavailable')).toBeInTheDocument();
+  await user.click(screen.getByRole('button', { name: 'Next' }));
+  expect(screen.getByText('No environments')).toBeInTheDocument();
+  await user.click(screen.getByRole('button', { name: 'Next' }));
+  await user.click(screen.getByRole('button', { name: 'Create project' }));
+  await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+  expect(onFinish).toHaveBeenCalledTimes(1);
+  expect(screen.getByRole('textbox', { name: 'Filter projects' })).toBe(filter);
+  expect(filter).toHaveValue('Keep me');
+  expect(window.location.href).toBe(url);
+});

package/src/create-wizard/Page.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import CreateWizardPage from './Page';
+
+describe('CreateWizardPage', () => {
+  it('renders the wizard shell on the first step', { timeout: 15000 }, async () => {
+    const { container } = render(<CreateWizardPage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Project details' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /Next/ })).toBeDisabled();
+    await expectNoAxeViolations(container);
+  });
+
+  it('walks to the review step, edits, and finishes', { timeout: 15000 }, async () => {
+    const onFinish = vi.fn();
+    const { container } = render(<CreateWizardPage onFinish={onFinish} />);
+    await userEvent.type(screen.getByRole('textbox', { name: /Project name/ }), 'orders-api');
+    await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    await userEvent.click(screen.getByRole('radio', { name: 'Start from a template' }));
+    await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    expect(screen.getByRole('heading', { level: 1, name: 'Review and create' })).toBeInTheDocument();
+    expect(screen.queryByRole('heading', { name: 'Summary' })).toBeNull();
+    expect(screen.getAllByRole('heading', { level: 2 }).length).toBeGreaterThanOrEqual(2);
+    expect(screen.getByText('Start from a template')).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+
+    await userEvent.click(screen.getByRole('button', { name: 'Edit details' }));
+    expect(screen.getByRole('textbox', { name: /Project name/ })).toHaveValue('orders-api');
+    for (let i = 0; i < 3; i++) await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    await userEvent.click(screen.getByRole('button', { name: /Create project/ }));
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'orders-api', source: 'template', region: 'eu-west-1' }),
+    );
+    expect(await screen.findByText('Project “orders-api” created')).toBeInTheDocument();
+  });
+
+  it('takes its copy from the `copy` prop', { timeout: 15000 }, async () => {
+    render(
+      <CreateWizardPage
+        copy={{
+          detailsTitle: 'Agent details',
+          nameLabel: 'Agent name',
+          submitLabel: 'Create agent',
+          reviewTitle: 'Review the agent',
+        }}
+      />,
+    );
+    expect(screen.getByRole('heading', { level: 1, name: 'Agent details' })).toBeInTheDocument();
+    await userEvent.type(screen.getByRole('textbox', { name: /Agent name/ }), 'triage-bot');
+    for (let i = 0; i < 3; i++) await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    expect(screen.getByRole('heading', { level: 1, name: 'Review the agent' })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /Create agent/ })).toBeInTheDocument();
+    expect(screen.getByText('Agent name')).toBeInTheDocument();
+  });
+});

package/src/create-wizard/Page.tsx

@@ -0,0 +1,246 @@
+import { DescriptionListCard } from '@gntik-ai/blocks';
+import {
+  Checkbox,
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+  Heading,
+  Input,
+  Logo,
+  SelectableCard,
+  SelectableCardGroup,
+  SimpleSelect,
+  Stack,
+  Text,
+  Textarea,
+  WizardLayout,
+  type StepItem,
+  type WizardLayoutProps,
+} from '@gntik-ai/ui';
+import { useId, useState, type ReactNode } from 'react';
+import {
+  PROJECT_NAME_RE,
+  wizardCopy,
+  wizardInitialValues,
+  wizardRegions,
+  wizardSources,
+  wizardSteps,
+  type CreateWizardCopy,
+  type SourceOption,
+  type WizardRegion,
+  type WizardValues,
+} from './data';
+
+export interface CreateWizardProps extends Pick<
+  WizardLayoutProps,
+  | 'mode'
+  | 'size'
+  | 'open'
+  | 'onOpenChange'
+  | 'description'
+  | 'returnFocusRef'
+  | 'closeOnInteractOutside'
+  | 'stepAnnouncement'
+  | 'pendingLabel'
+> {
+  /** Step-local errors or empty states, rendered within the scrollable step body. */
+  stepFeedback?: (current: number) => ReactNode;
+  /** Flow name in the top bar. */
+  title: string;
+  steps: StepItem[];
+  initialValues: WizardValues;
+  sources: readonly SourceOption[];
+  regions: readonly WizardRegion[];
+  /** Called from the review step; return a promise to show the loading state. */
+  onFinish: (values: WizardValues) => void | Promise<void>;
+  /** Called after the exit is confirmed. */
+  onExit: () => void;
+  onStepChange: (index: number) => void;
+  /** Step titles, field labels, submit label…; unset keys keep the default (project) wording. */
+  copy: Partial<CreateWizardCopy>;
+}
+
+function StepIntro({ id, title, children }: { id: string; title: string; children?: ReactNode }) {
+  return (
+    <Stack gap={1}>
+      <Heading level={1} id={id} size="lg">
+        {title}
+      </Heading>
+      {children && <Text variant="supporting">{children}</Text>}
+    </Stack>
+  );
+}
+
+/** Multi-step create flow in the focus-mode WizardLayout, ending in a review of every answer. */
+export default function CreateWizardPage({
+  title = 'New project',
+  steps = wizardSteps,
+  initialValues = wizardInitialValues,
+  sources = wizardSources,
+  regions = wizardRegions,
+  onFinish,
+  onExit,
+  onStepChange,
+  copy: copyOverrides,
+  stepFeedback,
+  ...presentation
+}: Partial<CreateWizardProps>) {
+  const copy: CreateWizardCopy = { ...wizardCopy, ...copyOverrides };
+  const id = useId();
+  const [step, setStep] = useState(0);
+  const [values, setValues] = useState(initialValues);
+  const [touched, setTouched] = useState(false);
+  const [finishing, setFinishing] = useState(false);
+  const [status, setStatus] = useState('');
+  const set = <K extends keyof WizardValues>(key: K, value: WizardValues[K]) =>
+    setValues((v) => ({ ...v, [key]: value }));
+
+  const nameValid = PROJECT_NAME_RE.test(values.name);
+  const nameError = touched && !nameValid ? (values.name ? copy.nameInvalid : copy.nameRequired) : undefined;
+  const go = (index: number) => {
+    setStep(index);
+    onStepChange?.(index);
+  };
+  const sourceLabel = sources.find((s) => s.value === values.source)?.title ?? values.source;
+  const regionLabel = regions.find((r) => r.value === values.region)?.label ?? values.region;
+
+  const finish = async () => {
+    setFinishing(true);
+    try {
+      await onFinish?.(values);
+      setStatus(copy.created(values.name));
+    } finally {
+      setFinishing(false);
+    }
+  };
+
+  return (
+    <WizardLayout
+      {...presentation}
+      fullScreen
+      logo={<Logo size={22} />}
+      title={title}
+      steps={steps}
+      current={step}
+      onStepChange={go}
+      nextDisabled={step === 0 && !nameValid}
+      nextLoading={finishing}
+      finishLabel={copy.submitLabel}
+      onFinish={() => void finish()}
+      onExit={onExit}
+      exitTitle={copy.exitTitle}
+      exitDescription={copy.exitDescription}
+      footerStart={<span aria-live="polite">{status}</span>}
+    >
+      {stepFeedback?.(step)}
+      {step === 0 && (
+        <section aria-labelledby={`${id}-details`}>
+          <Stack gap={6}>
+            <StepIntro id={`${id}-details`} title={copy.detailsTitle}>
+              {copy.detailsIntro}
+            </StepIntro>
+            <Field invalid={nameError != null}>
+              <FieldLabel required>{copy.nameLabel}</FieldLabel>
+              <Input
+                required
+                value={values.name}
+                onValueChange={(v) => set('name', v)}
+                onBlur={() => setTouched(true)}
+                placeholder={copy.namePlaceholder}
+              />
+              <FieldDescription>{copy.nameHint}</FieldDescription>
+              <FieldError match={nameError != null}>{nameError}</FieldError>
+            </Field>
+            <Field>
+              <FieldLabel>{copy.descriptionLabel}</FieldLabel>
+              <Textarea rows={3} value={values.description} onValueChange={(v) => set('description', v)} />
+            </Field>
+          </Stack>
+        </section>
+      )}
+      {step === 1 && (
+        <section aria-labelledby={`${id}-source`}>
+          <Stack gap={6}>
+            <StepIntro id={`${id}-source`} title={copy.sourceTitle}>
+              {copy.sourceIntro}
+            </StepIntro>
+            <SelectableCardGroup
+              aria-labelledby={`${id}-source`}
+              value={values.source}
+              onValueChange={(v) => set('source', v)}
+              columns={1}
+            >
+              {sources.map((s) => {
+                const Icon = s.icon;
+                return (
+                  <SelectableCard
+                    key={s.value}
+                    value={s.value}
+                    title={s.title}
+                    description={s.description}
+                    icon={<Icon size={18} aria-hidden />}
+                  />
+                );
+              })}
+            </SelectableCardGroup>
+          </Stack>
+        </section>
+      )}
+      {step === 2 && (
+        <section aria-labelledby={`${id}-configure`}>
+          <Stack gap={6}>
+            <StepIntro id={`${id}-configure`} title={copy.configureTitle}>
+              {copy.configureIntro}
+            </StepIntro>
+            <SimpleSelect
+              label={copy.regionLabel}
+              items={regions}
+              value={values.region}
+              onValueChange={(v) => v && set('region', v)}
+              className="w-full"
+            />
+            <Checkbox
+              label={copy.previewsLabel}
+              description={copy.previewsDescription}
+              checked={values.previews}
+              onCheckedChange={(checked) => set('previews', checked)}
+            />
+          </Stack>
+        </section>
+      )}
+      {step === 3 && (
+        <section aria-labelledby={`${id}-review`}>
+          <Stack gap={6}>
+            <StepIntro id={`${id}-review`} title={copy.reviewTitle}>
+              {copy.reviewIntro}
+            </StepIntro>
+            <DescriptionListCard
+              titleAs="h2"
+              title={copy.reviewDetailsTitle}
+              description={copy.reviewDetailsDescription}
+              items={[
+                { id: 'name', label: copy.nameLabel, value: values.name, mono: true },
+                { id: 'description', label: copy.descriptionLabel, value: values.description || '—' },
+              ]}
+              onEdit={() => go(0)}
+              editLabel={copy.editDetailsLabel}
+            />
+            <DescriptionListCard
+              titleAs="h2"
+              title={copy.reviewSourceTitle}
+              description={copy.reviewSourceDescription}
+              items={[
+                { id: 'source', label: copy.sourceLabel, value: sourceLabel },
+                { id: 'region', label: copy.regionLabel, value: regionLabel },
+                { id: 'previews', label: copy.previewsLabel, value: values.previews ? copy.on : copy.off },
+              ]}
+              onEdit={() => go(1)}
+              editLabel={copy.editSourceLabel}
+            />
+          </Stack>
+        </section>
+      )}
+    </WizardLayout>
+  );
+}

package/src/create-wizard/data.ts

@@ -0,0 +1,139 @@
+import { Code2, GitBranch, LayoutTemplate, type LucideIcon } from '@gntik-ai/icons';
+import type { StepItem } from '@gntik-ai/ui';
+
+export interface WizardValues {
+  name: string;
+  description: string;
+  source: string;
+  region: string;
+  previews: boolean;
+}
+
+export interface SourceOption {
+  value: string;
+  title: string;
+  description: string;
+  icon: LucideIcon;
+}
+
+export interface WizardRegion {
+  value: string;
+  label: string;
+}
+
+export const wizardSteps: StepItem[] = [
+  { id: 'details', label: 'Details' },
+  { id: 'source', label: 'Source' },
+  { id: 'configure', label: 'Configure' },
+  { id: 'review', label: 'Review' },
+];
+
+export const wizardSources: SourceOption[] = [
+  {
+    value: 'repository',
+    title: 'Import a repository',
+    description: 'Build and deploy from a Git branch on every push.',
+    icon: GitBranch,
+  },
+  {
+    value: 'template',
+    title: 'Start from a template',
+    description: 'A ready-made service you can change later.',
+    icon: LayoutTemplate,
+  },
+  {
+    value: 'empty',
+    title: 'Empty project',
+    description: 'No code yet; connect a source when you are ready.',
+    icon: Code2,
+  },
+];
+
+export const wizardRegions: WizardRegion[] = [
+  { value: 'eu-west-1', label: 'EU West · Ireland' },
+  { value: 'eu-central-1', label: 'EU Central · Frankfurt' },
+  { value: 'us-east-1', label: 'US East · Virginia' },
+  { value: 'ap-south-1', label: 'Asia Pacific · Mumbai' },
+];
+
+export const wizardInitialValues: WizardValues = {
+  name: '',
+  description: '',
+  source: 'repository',
+  region: 'eu-west-1',
+  previews: true,
+};
+
+export const PROJECT_NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/** Every visible string of the wizard; products override any subset through the `copy` prop. */
+export interface CreateWizardCopy {
+  detailsTitle: string;
+  detailsIntro: string;
+  nameLabel: string;
+  namePlaceholder: string;
+  nameHint: string;
+  nameRequired: string;
+  nameInvalid: string;
+  descriptionLabel: string;
+  sourceTitle: string;
+  sourceIntro: string;
+  configureTitle: string;
+  configureIntro: string;
+  regionLabel: string;
+  previewsLabel: string;
+  previewsDescription: string;
+  reviewTitle: string;
+  reviewIntro: string;
+  /** @deprecated No longer rendered: the review cards are the step's h2 headings. Kept for compatibility. */
+  summaryHeading?: string;
+  reviewDetailsTitle: string;
+  reviewDetailsDescription: string;
+  editDetailsLabel: string;
+  reviewSourceTitle: string;
+  reviewSourceDescription: string;
+  editSourceLabel: string;
+  sourceLabel: string;
+  on: string;
+  off: string;
+  /** Submit button on the review step. */
+  submitLabel: string;
+  exitTitle: string;
+  exitDescription: string;
+  /** Live status after a successful finish. */
+  created: (name: string) => string;
+}
+
+export const wizardCopy: CreateWizardCopy = {
+  detailsTitle: 'Project details',
+  detailsIntro: 'Name the project; you can change the description later.',
+  nameLabel: 'Project name',
+  namePlaceholder: 'billing-dashboard',
+  nameHint: 'Lowercase letters, numbers and dashes.',
+  nameRequired: 'Enter a project name.',
+  nameInvalid: 'Use lowercase letters, numbers and dashes.',
+  descriptionLabel: 'Description',
+  sourceTitle: 'Choose a source',
+  sourceIntro: 'Where the project’s code comes from.',
+  configureTitle: 'Configure',
+  configureIntro: 'Region and deployment defaults.',
+  regionLabel: 'Region',
+  previewsLabel: 'Preview deployments',
+  previewsDescription: 'Deploy every pull request to its own URL.',
+  reviewTitle: 'Review and create',
+  reviewIntro: 'Check your answers; edit any section before creating the project.',
+  summaryHeading: 'Summary',
+  reviewDetailsTitle: 'Details',
+  reviewDetailsDescription: 'Name and description.',
+  editDetailsLabel: 'Edit details',
+  reviewSourceTitle: 'Source and configuration',
+  reviewSourceDescription: 'Where the code comes from and where it runs.',
+  editSourceLabel: 'Edit source',
+  sourceLabel: 'Source',
+  on: 'On',
+  off: 'Off',
+  submitLabel: 'Create project',
+  exitTitle: 'Leave project setup?',
+  exitDescription: 'The project has not been created yet. Your answers will be discarded.',
+  created: (name) => `Project “${name}” created`,
+};

package/src/create-wizard/examples/Overlay.tsx

@@ -0,0 +1,60 @@
+import { Button, Heading, Stack } from '@gntik-ai/ui';
+import { ErrorPanel, FirstRunEmpty } from '@gntik-ai/blocks';
+import { useState } from 'react';
+import CreateWizardPage from '../Page';
+
+/** Keep this component mounted: closing preserves the wizard's answers and current step. */
+export default function CreateWizardOverlay() {
+  const [open, setOpen] = useState(false);
+  const [projects, setProjects] = useState<string[]>([]);
+  const [sourceUnavailable, setSourceUnavailable] = useState(true);
+  return (
+    <>
+      <main className="p-6">
+        <Stack gap={4}>
+          <Heading level={1}>Projects</Heading>
+          <Button onClick={() => setOpen(true)}>New project</Button>
+          <ul>
+            {projects.map((name) => (
+              <li key={name}>{name}</li>
+            ))}
+          </ul>
+        </Stack>
+      </main>
+      <CreateWizardPage
+        mode="overlay"
+        open={open}
+        onOpenChange={setOpen}
+        description="Create a project over this list."
+        pendingLabel="Creating project…"
+        onFinish={(values) => {
+          setProjects((items) => [...items, values.name]);
+          setOpen(false);
+        }}
+        stepFeedback={(step) =>
+          step === 1 && sourceUnavailable ? (
+            <ErrorPanel
+              title="Sources are unavailable"
+              message="Retry or continue with a blank project."
+              code={503}
+              requestId=""
+              details=""
+              secondaryAction={null}
+              retryLabel="Retry sources"
+              onRetry={() => setSourceUnavailable(false)}
+            />
+          ) : step === 1 ? (
+            <FirstRunEmpty
+              title="No saved sources"
+              description="You can connect a source later."
+              steps={[]}
+              secondary={null}
+              actionLabel="Refresh sources"
+              onAction={() => setSourceUnavailable(true)}
+            />
+          ) : null
+        }
+      />
+    </>
+  );
+}

package/src/create-wizard/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Create wizard',
+  family: 'Resources',
+  priority: 'P2',
+  status: 'beta',
+  description:
+    'Focus-mode create flow: details, source, configuration and editable review cards. Page mode is the default; mode="overlay" mounts over an existing list without a new route. Overlay size defaults to fullscreen; size="dialog" uses a popup (fullscreen on mobile). Keep it mounted to preserve answers and the current step on close. The examples/Overlay.tsx demo goes from a list through Finish with step-local ErrorPanel and FirstRunEmpty surfaces. For a consumer-owned step model and validation/review slots, use dialog-wizard (default dialog size).',
+  layout: 'WizardLayout',
+  blocks: ['description-list-card', 'error-panel', 'empty-states'],
+};

package/src/create-workspace/Page.test.tsx

@@ -0,0 +1,41 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import CreateWorkspacePage from './Page';
+
+describe('CreateWorkspacePage', () => {
+  it('renders the first step with the address preview', { timeout: 15000 }, async () => {
+    const { container } = render(<CreateWorkspacePage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Name your workspace' })).toBeInTheDocument();
+    await userEvent.type(screen.getByRole('textbox', { name: /Workspace name/ }), 'Acme Labs');
+    expect(screen.getByText('app.example.com/acme-labs')).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('picks region and plan, invites members and finishes', { timeout: 15000 }, async () => {
+    const onFinish = vi.fn();
+    const { container } = render(<CreateWorkspacePage onFinish={onFinish} />);
+    await userEvent.type(screen.getByRole('textbox', { name: /Workspace name/ }), 'Acme Labs');
+    await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    await userEvent.click(screen.getByRole('radio', { name: 'United States' }));
+    await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    expect(screen.getByRole('radio', { name: 'Team' })).toBeChecked();
+    await expectNoAxeViolations(container);
+    await userEvent.click(screen.getByRole('radio', { name: 'Starter' }));
+    await userEvent.click(screen.getByRole('button', { name: /Next/ }));
+    await userEvent.type(screen.getByRole('textbox', { name: /Email addresses/ }), 'sam@example.com{Enter}');
+    await expectNoAxeViolations(container);
+    await userEvent.click(screen.getByRole('button', { name: /Create and invite/ }));
+    expect(onFinish).toHaveBeenCalledWith(
+      expect.objectContaining({
+        name: 'Acme Labs',
+        slug: 'acme-labs',
+        region: 'us',
+        plan: 'starter',
+        invites: ['sam@example.com'],
+        role: 'member',
+      }),
+    );
+  });
+});