@gntik-ai/templates 0.0.0-stage → 0.5.0

package/src/resource-detail/Page.tsx

@@ -0,0 +1,262 @@
+import {
+  ActivityFeed,
+  DangerZone,
+  DescriptionListCard,
+  FormSection,
+  PageHeader,
+  StatusTimeline,
+  type ActivityItem,
+  type DangerZoneAction,
+  type DescriptionItem,
+  type PageChromeAction,
+  type PageHeaderMetaItem,
+  type StatusEvent,
+} from '@gntik-ai/blocks';
+import { FileText, RotateCw } from '@gntik-ai/icons';
+import {
+  Button,
+  Field,
+  FieldDescription,
+  FieldLabel,
+  Grid,
+  Input,
+  Page,
+  Section,
+  Stack,
+  Tabs,
+  TabsList,
+  TabsPanel,
+  TabsTab,
+  Textarea,
+  type BreadcrumbItem,
+} from '@gntik-ai/ui';
+import { useState } from 'react';
+import { ConsoleShell, type ConsoleShellProps } from '../shared/ConsoleShell';
+import {
+  detailActivity,
+  detailBreadcrumbs,
+  detailDangerActions,
+  detailEvents,
+  detailItems,
+  detailMeta,
+  detailResource,
+  type ResourceSettings,
+} from './data';
+
+export type ResourceDetailTab = 'overview' | 'activity' | 'settings';
+
+export interface ResourceDetailProps {
+  /**
+   * Optional boolean, default false. Shows only the keyboard-accessible Overview tab in
+   * the "Resource sections" tablist, using explicit resource props without sample defaults.
+   * Ignores activity, events, dangerActions, defaultTab, onSaveSettings and onDangerAction.
+   * Explicit actions and onEditDetails are still honored. ConsoleShell defaults are unchanged.
+   */
+  readOnly?: boolean;
+  /**
+   * Optional readonly StatusEvent[], default undefined; used only when readOnly is true.
+   * Omitted: no history card. Empty: named StatusTimeline empty state. Populated: exactly
+   * the supplied events, without fabricated actors. Editable mode continues to use events.
+   */
+  history?: readonly StatusEvent[];
+  name: string;
+  description: string;
+  /** StatusTag key next to the title. */
+  status: string;
+  breadcrumbs: BreadcrumbItem[];
+  meta: PageHeaderMetaItem[];
+  actions: PageChromeAction[];
+  details: readonly DescriptionItem[];
+  /** Title of the Overview details card (default "Configuration"). */
+  overviewTitle: string;
+  /** Description of the Overview details card. */
+  overviewDescription: string;
+  /** Title of the Overview status-history card (default "Status history"). */
+  historyTitle: string;
+  events: readonly StatusEvent[];
+  activity: readonly ActivityItem[];
+  dangerActions: DangerZoneAction[];
+  defaultTab: ResourceDetailTab;
+  onTabChange: (tab: ResourceDetailTab) => void;
+  onEditDetails: () => void;
+  onSaveSettings: (settings: ResourceSettings) => void;
+  /** Confirmed Danger zone action id (e.g. `pause`, `delete`). */
+  onDangerAction: (actionId: string) => void | Promise<void>;
+  shell: Omit<ConsoleShellProps, 'children'>;
+}
+
+const TABS: Array<{ value: ResourceDetailTab; label: string }> = [
+  { value: 'overview', label: 'Overview' },
+  { value: 'activity', label: 'Activity' },
+  { value: 'settings', label: 'Settings' },
+];
+
+/** Resource detail: editable tabs by default, or explicit-only Overview when readOnly is true. */
+export default function ResourceDetailPage(props: Partial<ResourceDetailProps>) {
+  const readOnly = props.readOnly ?? false;
+  const {
+    name = readOnly ? '' : detailResource.name,
+    description = readOnly ? '' : detailResource.description,
+    status = readOnly ? '' : detailResource.status,
+    breadcrumbs = readOnly ? [] : detailBreadcrumbs,
+    meta: metaProp,
+    actions: actionsProp,
+    details: detailsProp,
+    overviewTitle = 'Configuration',
+    overviewDescription = readOnly ? '' : 'Settings of this resource.',
+    historyTitle = 'Status history',
+    events = readOnly ? [] : detailEvents,
+    activity = readOnly ? [] : detailActivity,
+    dangerActions = readOnly ? [] : detailDangerActions,
+    defaultTab = 'overview',
+    onTabChange,
+    onEditDetails,
+    onSaveSettings,
+    onDangerAction,
+    shell,
+  } = props;
+  const meta = metaProp ?? (readOnly ? [] : detailMeta);
+  const actions: PageChromeAction[] =
+    actionsProp ??
+    (readOnly
+      ? []
+      : [
+          { label: 'View logs', icon: FileText, variant: 'secondary' },
+          { label: 'Redeploy', icon: RotateCw, variant: 'primary' },
+        ]);
+  const details = detailsProp ?? (readOnly ? [] : detailItems);
+  const historyEvents = readOnly ? props.history : events;
+  const [tab, setTab] = useState<ResourceDetailTab>(defaultTab);
+  const [settings, setSettings] = useState<ResourceSettings>({ name, description });
+  const [saved, setSaved] = useState<ResourceSettings>({ name, description });
+  const dirty = settings.name !== saved.name || settings.description !== saved.description;
+  const tabs = readOnly ? TABS.filter((t) => t.value === 'overview') : TABS;
+
+  return (
+    <ConsoleShell currentHref="/deployments" breadcrumbs={breadcrumbs} {...shell}>
+      <Page
+        width="wide"
+        header={
+          <PageHeader
+            breadcrumbs={null}
+            title={name}
+            description={description}
+            status={status}
+            meta={meta}
+            actions={actions}
+            tabs={null}
+          />
+        }
+      >
+        <Tabs
+          value={readOnly ? 'overview' : tab}
+          onValueChange={(v) => {
+            const next = tabs.find((t) => t.value === v)?.value ?? 'overview';
+            setTab(next);
+            onTabChange?.(next);
+          }}
+        >
+          <TabsList aria-label="Resource sections">
+            {tabs.map((t) => (
+              <TabsTab key={t.value} value={t.value}>
+                {t.label}
+              </TabsTab>
+            ))}
+          </TabsList>
+
+          <TabsPanel value="overview">
+            <Grid cols={historyEvents === undefined ? 1 : { base: 1, lg: 5 }} gap={6} align="start">
+              <DescriptionListCard
+                className={historyEvents === undefined ? undefined : 'lg:col-span-3'}
+                titleAs="h2"
+                title={overviewTitle}
+                description={overviewDescription}
+                items={details}
+                onEdit={onEditDetails}
+              />
+              {historyEvents !== undefined && (
+                <Section
+                  role={readOnly ? 'group' : undefined}
+                  variant="card"
+                  padding="md"
+                  title={historyTitle}
+                  className="lg:col-span-2"
+                >
+                  <StatusTimeline events={historyEvents} maxVisible={readOnly ? undefined : 4} />
+                </Section>
+              )}
+            </Grid>
+          </TabsPanel>
+
+          {!readOnly && (
+            <TabsPanel value="activity">
+              <Section
+                variant="card"
+                padding="md"
+                title="Activity"
+                description="Changes made to this resource by people and automations."
+              >
+                <ActivityFeed items={activity} label="Activity, newest first" />
+              </Section>
+            </TabsPanel>
+          )}
+
+          {!readOnly && (
+            <TabsPanel value="settings">
+              <Stack gap={8}>
+                <form
+                  noValidate
+                  onSubmit={(e) => {
+                    e.preventDefault();
+                    setSaved(settings);
+                    onSaveSettings?.(settings);
+                  }}
+                >
+                  <FormSection
+                    title="General"
+                    description="Name and description shown across the console."
+                    actions={
+                      <>
+                        <Button variant="ghost" disabled={!dirty} onClick={() => setSettings(saved)}>
+                          Discard
+                        </Button>
+                        <Button type="submit" disabled={!dirty}>
+                          Save changes
+                        </Button>
+                      </>
+                    }
+                  >
+                    <Stack gap={4}>
+                      <Field>
+                        <FieldLabel required>Name</FieldLabel>
+                        <Input
+                          required
+                          value={settings.name}
+                          onValueChange={(v) => setSettings((s) => ({ ...s, name: v }))}
+                        />
+                        <FieldDescription>Lowercase letters, numbers and dashes.</FieldDescription>
+                      </Field>
+                      <Field>
+                        <FieldLabel>Description</FieldLabel>
+                        <Textarea
+                          rows={3}
+                          value={settings.description}
+                          onValueChange={(v) => setSettings((s) => ({ ...s, description: v }))}
+                        />
+                      </Field>
+                    </Stack>
+                  </FormSection>
+                </form>
+                <DangerZone
+                  description="These actions affect everyone who uses this resource."
+                  actions={dangerActions}
+                  onConfirm={onDangerAction}
+                />
+              </Stack>
+            </TabsPanel>
+          )}
+        </Tabs>
+      </Page>
+    </ConsoleShell>
+  );
+}

package/src/resource-detail/data.ts

@@ -0,0 +1,55 @@
+import {
+  DEPLOYMENT_DETAILS,
+  DEPLOYMENT_EVENTS,
+  PROJECT_ACTIVITY,
+  type ActivityItem,
+  type DangerZoneAction,
+  type DescriptionItem,
+  type PageHeaderMetaItem,
+  type StatusEvent,
+} from '@gntik-ai/blocks';
+import { Clock, GitBranch, Globe } from '@gntik-ai/icons';
+import type { BreadcrumbItem } from '@gntik-ai/ui';
+
+/** The editable part of the resource (Settings tab). */
+export interface ResourceSettings {
+  name: string;
+  description: string;
+}
+
+export const detailResource = {
+  name: 'orders-api',
+  status: 'running',
+  description: 'Public REST API for orders, carts and checkout.',
+} as const;
+
+export const detailBreadcrumbs: BreadcrumbItem[] = [
+  { label: 'Deployments', href: '/deployments' },
+  { label: detailResource.name, mono: true },
+];
+
+export const detailMeta: PageHeaderMetaItem[] = [
+  { label: 'Region', value: 'eu-west-1', icon: Globe, mono: true },
+  { label: 'Branch', value: 'main', icon: GitBranch, mono: true },
+  { label: 'Last deploy', value: '12 min ago', icon: Clock },
+];
+export const detailItems: DescriptionItem[] = DEPLOYMENT_DETAILS;
+export const detailEvents: StatusEvent[] = DEPLOYMENT_EVENTS;
+export const detailActivity: ActivityItem[] = PROJECT_ACTIVITY;
+
+export const detailDangerActions: DangerZoneAction[] = [
+  {
+    id: 'pause',
+    title: 'Pause deployment',
+    description: 'Stops serving traffic until you resume it. Configuration is kept.',
+    actionLabel: 'Pause',
+    destructive: false,
+  },
+  {
+    id: 'delete',
+    title: 'Delete deployment',
+    description: `Permanently deletes ${detailResource.name}, its secrets and history. This cannot be undone.`,
+    actionLabel: 'Delete deployment',
+    confirmText: detailResource.name,
+  },
+];

package/src/resource-detail/examples/postgres-table-detail.tsx

@@ -0,0 +1,28 @@
+import ResourceDetailPage from '../Page';
+import { shell } from './shell';
+
+export default function TableDetail() {
+  const table = {
+    name: 'records',
+    columns: ['id', 'title', 'created_at'],
+    indexes: ['records_pkey'],
+    policies: ['Members can read'],
+    security: 'Row-level security enabled',
+  };
+  // Schema information has no history field; no timeline or empty history card is appropriate.
+  return (
+    <ResourceDetailPage
+      readOnly
+      name="Table detail"
+      meta={[{ label: 'Table', value: table.name, mono: true }]}
+      overviewTitle="Schema details"
+      details={[
+        { id: 'columns', label: 'Columns', value: table.columns.join(', '), mono: true },
+        { id: 'indexes', label: 'Indexes', value: table.indexes.join(', '), mono: true },
+        { id: 'policies', label: 'Policies', value: table.policies.join(', ') },
+        { id: 'security', label: 'Security', value: table.security },
+      ]}
+      shell={shell}
+    />
+  );
+}

package/src/resource-detail/examples/realtime-configuration.tsx

@@ -0,0 +1,26 @@
+import ResourceDetailPage from '../Page';
+import { shell } from './shell';
+
+export default function RealtimeConfiguration() {
+  const configuration = {
+    workspaceId: 'workspace_42',
+    realtimeEndpointUrl: 'https://realtime.example.com',
+    features: ['Subscriptions', 'Presence'],
+    dataSources: ['primary'],
+  };
+  // No history field exists in this response, so omit history entirely.
+  return (
+    <ResourceDetailPage
+      readOnly
+      name="Realtime configuration"
+      overviewTitle="Connection details"
+      details={[
+        { id: 'workspace', label: 'Workspace ID', value: configuration.workspaceId, mono: true },
+        { id: 'endpoint', label: 'Endpoint', value: configuration.realtimeEndpointUrl, mono: true },
+        { id: 'features', label: 'Features', value: configuration.features.join(', ') },
+        { id: 'sources', label: 'Data sources', value: configuration.dataSources.join(', ') },
+      ]}
+      shell={shell}
+    />
+  );
+}

package/src/resource-detail/examples/runtime-with-transition.tsx

@@ -0,0 +1,30 @@
+import type { StatusEvent } from '@gntik-ai/blocks';
+import ResourceDetailPage from '../Page';
+import { shell } from './shell';
+
+export default function RuntimeWithTransition() {
+  const runtime = { state: 'Ready', lastTransitionAt: '2026-05-01T10:00:00Z' };
+  // Map only the source's state and transition time; it supplies no actor or earlier events.
+  const history: readonly StatusEvent[] = runtime.lastTransitionAt
+    ? [
+        {
+          id: 'transition',
+          status: runtime.state,
+          tone: 'success',
+          title: 'Runtime ready',
+          at: runtime.lastTransitionAt,
+        },
+      ]
+    : [];
+  return (
+    <ResourceDetailPage
+      readOnly
+      name="Function runtime"
+      status="running"
+      overviewTitle="Runtime details"
+      details={[{ id: 'state', label: 'State', value: runtime.state }]}
+      history={history}
+      shell={shell}
+    />
+  );
+}

package/src/resource-detail/examples/runtime-without-transition.tsx

@@ -0,0 +1,33 @@
+import type { StatusEvent } from '@gntik-ai/blocks';
+import ResourceDetailPage from '../Page';
+import { shell } from './shell';
+
+export default function RuntimeWithoutTransition() {
+  const runtime: { state: string; lastTransitionAt: string | null } = {
+    state: 'Pending',
+    lastTransitionAt: null,
+  };
+  // Null transition time means explicit empty history, not an invented event or an omitted card.
+  const history: readonly StatusEvent[] = runtime.lastTransitionAt
+    ? [
+        {
+          id: 'transition',
+          status: runtime.state,
+          tone: 'warning',
+          title: 'Runtime pending',
+          at: runtime.lastTransitionAt,
+        },
+      ]
+    : [];
+  return (
+    <ResourceDetailPage
+      readOnly
+      name="Function runtime"
+      status="pending"
+      overviewTitle="Runtime details"
+      details={[{ id: 'state', label: 'State', value: runtime.state }]}
+      history={history}
+      shell={shell}
+    />
+  );
+}

package/src/resource-detail/examples/shell.ts

@@ -0,0 +1,12 @@
+import type { ConsoleShellProps } from '../../shared/ConsoleShell';
+
+/** Explicit frame props prevent ConsoleShell's editable-demo fixtures from appearing. */
+export const shell: Omit<ConsoleShellProps, 'children'> = {
+  nav: [],
+  breadcrumbs: [],
+  workspaces: null,
+  user: null,
+  usage: null,
+  helpHref: null,
+  topbar: { environment: null, search: null, notifications: null, theme: null },
+};

package/src/resource-detail/template.meta.ts

@@ -0,0 +1,21 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Resource detail',
+  family: 'Resources',
+  priority: 'P1',
+  status: 'beta',
+  description:
+    'Resource detail with editable Overview, Activity and Settings tabs by default; optional readOnly (boolean, default false) uses only explicit header and detail props and one Overview tab, with optional history (readonly StatusEvent[], default undefined): omitted hides the history card, [] shows the named empty state, and events render exactly as supplied without invented actors. Read-only ignores activity, events, dangerActions, defaultTab, onSaveSettings and onDangerAction; explicit actions and onEditDetails are honored. The Resource sections tablist retains Tab, arrow, Home/End and Enter/Space keyboard navigation; history is a named group containing the Status history list or empty-state region. Uses token styling in dark (default), light and high_contrast. Examples: runtime-with-transition maps state and lastTransitionAt to one actor-free event, runtime-without-transition maps null to [], and realtime-configuration and postgres-table-detail omit history. ConsoleShell retains sample frame defaults unless explicit shell props are supplied, as in the examples.',
+  layout: 'SidebarLayout + Page',
+  blocks: [
+    'app-sidebar',
+    'app-topbar',
+    'page-header',
+    'description-list-card',
+    'status-timeline',
+    'activity-feed',
+    'form-section',
+    'danger-zone',
+  ],
+};

package/src/resource-form/Page.test.tsx

@@ -0,0 +1,40 @@
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import ResourceFormPage from './Page';
+
+describe('ResourceFormPage', () => {
+  it('renders the form sections and a clean save bar', { timeout: 15000 }, async () => {
+    const { container } = render(<ResourceFormPage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Edit project' })).toBeInTheDocument();
+    for (const name of ['General', 'Region', 'Billing'])
+      expect(screen.getByRole('heading', { level: 2, name })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Save changes' })).toBeDisabled();
+    // ValidationSummary links target control ids.
+    expect(screen.getByRole('combobox', { name: /Region/ })).toHaveAttribute('id', 'region');
+    await expectNoAxeViolations(container);
+  });
+
+  it('shows the validation summary and focuses the field from its link', { timeout: 15000 }, async () => {
+    const onSubmit = vi.fn();
+    const { container } = render(<ResourceFormPage onSubmit={onSubmit} />);
+    const email = screen.getByRole('textbox', { name: /Billing email/ });
+    await userEvent.clear(email);
+    await userEvent.type(email, 'not-an-email');
+    expect(screen.getByText('You have unsaved changes')).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Save changes' }));
+    expect(onSubmit).not.toHaveBeenCalled();
+    const summary = screen.getByRole('region', { name: /There is 1 problem/ });
+    await waitFor(() => expect(summary).toHaveFocus());
+    await userEvent.click(screen.getByRole('link', { name: /Billing email/ }));
+    expect(email).toHaveFocus();
+    await expectNoAxeViolations(container);
+
+    await userEvent.clear(email);
+    await userEvent.type(email, 'finance@example.com');
+    await userEvent.click(screen.getByRole('button', { name: 'Save changes' }));
+    expect(onSubmit).toHaveBeenCalledWith(expect.objectContaining({ billingEmail: 'finance@example.com' }));
+    await waitFor(() => expect(screen.getByRole('button', { name: 'Save changes' })).toBeDisabled());
+  });
+});