@gntik-ai/templates 0.0.0-stage → 0.5.0

package/src/changelog/Page.tsx

@@ -0,0 +1,174 @@
+import { PageHeader } from '@gntik-ai/blocks';
+import { ArrowRight, Rss } from '@gntik-ai/icons';
+import {
+  Badge,
+  Button,
+  EmptyState,
+  Heading,
+  HStack,
+  Link,
+  Page,
+  Stack,
+  Text,
+  Timestamp,
+  Toggle,
+  ToggleGroup,
+  type BreadcrumbItem,
+} from '@gntik-ai/ui';
+import { useId, useState } from 'react';
+import { ConsoleShell, type ConsoleShellProps } from '../shared/ConsoleShell';
+import {
+  changelogBreadcrumbs,
+  changelogEntries,
+  changelogTagLabels,
+  changelogTagTones,
+  type ChangelogEntry,
+  type ChangelogTag,
+} from './data';
+
+export interface ChangelogProps {
+  title: string;
+  description: string;
+  /** Entries, newest first. */
+  entries: ChangelogEntry[];
+  /** Tags initially pressed; none = every entry. */
+  defaultTags: ChangelogTag[];
+  onTagsChange: (tags: ChangelogTag[]) => void;
+  /** Subscribe action (RSS, email…); omit to hide it. */
+  onSubscribe: (() => void) | null;
+  breadcrumbs: BreadcrumbItem[];
+  currentHref: string;
+  shell: Omit<ConsoleShellProps, 'children'>;
+}
+
+const isTag = (v: string): v is ChangelogTag => v in changelogTagLabels;
+
+/** Changelog: dated release entries with tag badges and a "New" badge, filtered by tag. */
+export default function ChangelogPage(props: Partial<ChangelogProps>) {
+  const {
+    title = 'Changelog',
+    description = 'New features, improvements and fixes, newest first.',
+    entries = changelogEntries,
+    defaultTags = [],
+    onTagsChange,
+    onSubscribe = () => {},
+    breadcrumbs = changelogBreadcrumbs,
+    currentHref = '/help/changelog',
+    shell,
+  } = props;
+  const [tags, setTags] = useState<ChangelogTag[]>(defaultTags);
+  const countId = useId();
+  const tagsInUse = (Object.keys(changelogTagLabels) as ChangelogTag[]).filter((t) =>
+    entries.some((e) => e.tags.includes(t)),
+  );
+  const visible = tags.length === 0 ? entries : entries.filter((e) => e.tags.some((t) => tags.includes(t)));
+
+  const changeTags = (next: string[]) => {
+    const valid = next.filter(isTag);
+    setTags(valid);
+    onTagsChange?.(valid);
+  };
+
+  return (
+    <ConsoleShell breadcrumbs={breadcrumbs} currentHref={currentHref} {...shell}>
+      <Page
+        header={
+          <PageHeader
+            breadcrumbs={null}
+            title={title}
+            description={description}
+            status=""
+            meta={[]}
+            tabs={null}
+            actions={onSubscribe ? [{ label: 'Subscribe', icon: Rss, variant: 'secondary', onClick: onSubscribe }] : []}
+          />
+        }
+      >
+        <Stack gap={8}>
+          <HStack gap={3} wrap>
+            <ToggleGroup
+              aria-label="Filter by tag"
+              aria-describedby={countId}
+              size="sm"
+              multiple
+              value={tags}
+              onValueChange={changeTags}
+            >
+              {tagsInUse.map((t) => (
+                <Toggle key={t} value={t}>
+                  {changelogTagLabels[t]}
+                </Toggle>
+              ))}
+            </ToggleGroup>
+            {tags.length > 0 && (
+              <Button variant="ghost" size="sm" onClick={() => changeTags([])}>
+                Show all
+              </Button>
+            )}
+            <Text id={countId} as="span" variant="caption" tone="muted" aria-live="polite">
+              {visible.length === 1 ? '1 release' : `${visible.length} releases`}
+            </Text>
+          </HStack>
+          {visible.length === 0 ? (
+            <EmptyState
+              size="sm"
+              titleAs="h2"
+              title="No releases with these tags"
+              description="Pick another tag or show every release."
+            />
+          ) : (
+            <ol aria-label="Releases" className="flex flex-col divide-y divide-border">
+              {visible.map((e) => (
+                <li key={e.id} className="grid gap-3 py-7 first:pt-0 md:grid-cols-[10rem_1fr] md:gap-8">
+                  <Stack gap={1}>
+                    <Timestamp
+                      value={e.date}
+                      format="absolute"
+                      tooltip={false}
+                      dateOptions={{ dateStyle: 'medium' }}
+                      className="text-[13px] font-medium text-foreground"
+                    />
+                    <Text as="span" variant="caption" tone="muted" className="font-mono">
+                      v{e.version}
+                    </Text>
+                  </Stack>
+                  <article aria-labelledby={`${countId}-${e.id}`}>
+                    <Stack gap={3}>
+                      <HStack gap={2} wrap>
+                        {e.isNew && (
+                          <Badge tone="primary" variant="solid">
+                            New
+                          </Badge>
+                        )}
+                        {e.tags.map((t) => (
+                          <Badge key={t} tone={changelogTagTones[t]}>
+                            {changelogTagLabels[t]}
+                          </Badge>
+                        ))}
+                      </HStack>
+                      <Heading id={`${countId}-${e.id}`} level={2} size="sm">
+                        {e.title}
+                      </Heading>
+                      <Text tone="muted">{e.summary}</Text>
+                      <ul className="flex list-disc flex-col gap-1.5 ps-5 text-[13.5px] leading-6 text-foreground marker:text-muted-foreground">
+                        {e.changes.map((c) => (
+                          <li key={c}>{c}</li>
+                        ))}
+                      </ul>
+                      {e.href && (
+                        <Link href={e.href} className="inline-flex items-center gap-1 self-start text-[13px]">
+                          Read the release notes <ArrowRight size={14} aria-hidden />
+                          <span className="sr-only"> for {e.version}</span>
+                        </Link>
+                      )}
+                    </Stack>
+                  </article>
+                </li>
+              ))}
+            </ol>
+          )}
+        </Stack>
+      </Page>
+    </ConsoleShell>
+  );
+}

package/src/changelog/data.ts

@@ -0,0 +1,105 @@
+import type { BadgeProps, BreadcrumbItem } from '@gntik-ai/ui';
+
+export type ChangelogTag = 'feature' | 'improvement' | 'fix' | 'security' | 'deprecation';
+
+export interface ChangelogEntry {
+  id: string;
+  /** Release version, e.g. "2.14". */
+  version: string;
+  date: string;
+  title: string;
+  summary: string;
+  /** Bullet list of changes. */
+  changes: string[];
+  tags: ChangelogTag[];
+  /** Shows the "New" badge (e.g. released since the viewer's last visit). */
+  isNew?: boolean;
+  /** "Read more" link. */
+  href?: string;
+}
+
+export const changelogTagLabels: Record<ChangelogTag, string> = {
+  feature: 'Feature',
+  improvement: 'Improvement',
+  fix: 'Fix',
+  security: 'Security',
+  deprecation: 'Deprecation',
+};
+
+export const changelogTagTones: Record<ChangelogTag, NonNullable<BadgeProps['tone']>> = {
+  feature: 'primary',
+  improvement: 'info',
+  fix: 'neutral',
+  security: 'warning',
+  deprecation: 'destructive',
+};
+
+export const changelogBreadcrumbs: BreadcrumbItem[] = [{ label: 'Help', href: '/help' }, { label: 'Changelog' }];
+
+/** Neutral release notes, newest first. */
+export const changelogEntries: ChangelogEntry[] = [
+  {
+    id: 'v2-14',
+    version: '2.14',
+    date: '2026-09-29',
+    title: 'Deploy gates and scheduled rollbacks',
+    summary: 'Block releases while an incident is open, and schedule a rollback for a quiet hour.',
+    changes: [
+      'Deploy gates check open incidents, failing checks and freeze windows before every release.',
+      'Rollbacks can be scheduled; the deployment page shows a countdown and a cancel action.',
+      'The deployments table remembers its density and hidden columns per project.',
+    ],
+    tags: ['feature', 'improvement'],
+    isNew: true,
+    href: '/changelog/v2-14',
+  },
+  {
+    id: 'v2-13-2',
+    version: '2.13.2',
+    date: '2026-09-18',
+    title: 'Stricter API key scopes',
+    summary: 'New keys default to read-only; existing keys keep their scopes.',
+    changes: [
+      'Keys created from now on start read-only.',
+      'Audit log entries now include the key’s last four characters.',
+    ],
+    tags: ['security'],
+    isNew: true,
+  },
+  {
+    id: 'v2-13-1',
+    version: '2.13.1',
+    date: '2026-09-07',
+    title: 'Fixes for usage exports',
+    summary: 'CSV exports respect the selected range and time zone again.',
+    changes: [
+      'Exports used UTC instead of the workspace time zone.',
+      'Large exports no longer time out after 30 seconds.',
+    ],
+    tags: ['fix'],
+  },
+  {
+    id: 'v2-13',
+    version: '2.13',
+    date: '2026-08-25',
+    title: 'Saved views for every table',
+    summary: 'Save filters, sorting and columns as a view, and share it with your workspace.',
+    changes: [
+      'Saved views on projects, deployments, members and invoices.',
+      'Views can be private or shared with the workspace.',
+    ],
+    tags: ['feature'],
+  },
+  {
+    id: 'v2-12',
+    version: '2.12',
+    date: '2026-08-04',
+    title: 'Legacy webhooks are deprecated',
+    summary: 'Version 1 webhooks stop on 1 December 2026. Move to signed webhooks before then.',
+    changes: [
+      'Signed webhooks include a timestamp and an HMAC header.',
+      'The integrations page lists every endpoint still on version 1.',
+    ],
+    tags: ['deprecation', 'security'],
+  },
+];

package/src/changelog/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Changelog',
+  family: 'Help',
+  priority: 'P3',
+  status: 'experimental',
+  description:
+    'Release notes in the console: dated entries with version, tag badges and a “New” badge, a multi-select tag filter (ToggleGroup) with a live count, and a Subscribe action.',
+  layout: 'SidebarLayout · Page',
+  blocks: ['app-sidebar', 'app-topbar', 'page-header'],
+};

package/src/code-editor/Page.test.tsx

@@ -0,0 +1,83 @@
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import type { MonacoLoader } from '@gntik-ai/editor';
+import { expectNoAxeViolations } from '../test/a11y';
+import CodeEditorPage from './Page';
+import { filesToTree } from './data';
+
+/** Minimal Monaco stand-in (same approach as the CodePanel block tests). */
+function mockMonaco() {
+  const model = (value: string) => ({
+    getValue: () => value,
+    setValue: vi.fn(),
+    onDidChangeContent: () => ({ dispose: vi.fn() }),
+    dispose: vi.fn(),
+  });
+  const editor = {
+    defineTheme: vi.fn(),
+    setTheme: vi.fn(),
+    setModelLanguage: vi.fn(),
+    remeasureFonts: vi.fn(),
+    createModel: vi.fn((value: string) => model(value)),
+    create: vi.fn((_el: HTMLElement, opts: { value?: string }) => {
+      const m = model(opts.value ?? '');
+      return {
+        getModel: () => m,
+        getValue: () => m.getValue(),
+        setValue: vi.fn(),
+        onDidChangeModelContent: () => ({ dispose: vi.fn() }),
+        updateOptions: vi.fn(),
+        layout: vi.fn(),
+        dispose: vi.fn(),
+        setPosition: vi.fn(),
+        revealLineInCenter: vi.fn(),
+        focus: vi.fn(),
+      };
+    }),
+    createDiffEditor: vi.fn(() => ({
+      setModel: vi.fn(),
+      getModel: () => null,
+      updateOptions: vi.fn(),
+      layout: vi.fn(),
+      dispose: vi.fn(),
+    })),
+  };
+  return { editor, loader: (() => Promise.resolve({ editor })) as unknown as MonacoLoader };
+}
+
+describe('CodeEditorPage', () => {
+  it('renders the editor chrome, file tree and code panel', { timeout: 15000 }, async () => {
+    const m = mockMonaco();
+    render(<CodeEditorPage loader={m.loader} />);
+    expect(screen.getByRole('main', { name: 'projects-api editor' })).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'projects-api' })).toBeInTheDocument();
+    expect(screen.getByRole('tree', { name: 'Files' })).toBeInTheDocument();
+    expect(screen.getByRole('tab', { name: /handler\.ts/ })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getAllByRole('tab')).toHaveLength(2);
+    await waitFor(() => expect(m.editor.create).toHaveBeenCalled());
+    await expectNoAxeViolations();
+  });
+
+  it('opens a file from the tree as the active tab', { timeout: 15000 }, async () => {
+    const m = mockMonaco();
+    render(<CodeEditorPage loader={m.loader} />);
+    await userEvent.click(within(screen.getByRole('treeitem', { name: /deploy\.yaml/ })).getByText('deploy.yaml'));
+    expect(screen.getAllByRole('tab')).toHaveLength(3);
+    expect(screen.getByRole('tab', { name: /deploy\.yaml/ })).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('deletes a file from its context menu', { timeout: 15000 }, async () => {
+    const m = mockMonaco();
+    const onDeleteFile = vi.fn();
+    render(<CodeEditorPage loader={m.loader} onDeleteFile={onDeleteFile} />);
+    fireEvent.contextMenu(within(screen.getByRole('treeitem', { name: /query\.ts/ })).getByText('query.ts'));
+    await userEvent.click(await screen.findByRole('menuitem', { name: 'Delete file' }));
+    expect(onDeleteFile).toHaveBeenCalledWith('src/query.ts');
+    expect(screen.queryByRole('treeitem', { name: /query\.ts/ })).toBeNull();
+    expect(screen.getAllByRole('tab')).toHaveLength(1);
+  });
+
+  it('builds a folders-first tree from paths', () => {
+    expect(filesToTree(['b.md', 'src/a.ts', 'src/lib/c.ts']).map((n) => n.id)).toEqual(['src/', 'b.md']);
+  });
+});

package/src/code-editor/Page.tsx

@@ -0,0 +1,207 @@
+import { CodePanel, type CodeFile, type CodeProblem } from '@gntik-ai/blocks';
+import type { MonacoLoader } from '@gntik-ai/editor';
+import { Copy, ExternalLink, Save, Trash2, X } from '@gntik-ai/icons';
+import {
+  Badge,
+  Breadcrumbs,
+  Button,
+  CanvasLayout,
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuTrigger,
+  MenuItem,
+  MenuSeparator,
+  StatusTag,
+  TreeList,
+  type BreadcrumbItem,
+} from '@gntik-ai/ui';
+import { useState, type MouseEvent } from 'react';
+import { editorBreadcrumbs, editorDefaultOpen, editorFiles, editorProblems, editorProject, filesToTree } from './data';
+
+export interface CodeEditorPageProps {
+  title: string;
+  /** StatusTag key next to the title. */
+  status: string;
+  /** Branch or version shown as a badge. */
+  branch: string;
+  files: CodeFile[];
+  problems: CodeProblem[];
+  /** Paths open as tabs initially (the first one is active). */
+  defaultOpen: string[];
+  /** Receives the edited files (path → new content). A returned promise shows the saving state. */
+  onSave: (changes: Record<string, string>) => void | Promise<void>;
+  /** Called after "Delete" in a file's context menu; the file leaves the tree and the tabs. */
+  onDeleteFile: (path: string) => void;
+  /** Monaco loader (self-hosting, tests). Monaco loads lazily by default. */
+  loader: MonacoLoader;
+  breadcrumbs: BreadcrumbItem[];
+  fullScreen: boolean;
+}
+
+/**
+ * Code editor page: CanvasLayout with a file TreeList (context menu: open, copy path, close,
+ * delete) in the palette and the CodePanel block (file tabs, editor / diff, problems) as the
+ * canvas. Opening a file from the tree focuses its tab; edits survive reopening and Save
+ * hands them over.
+ */
+export default function CodeEditorPage(props: Partial<CodeEditorPageProps>) {
+  const {
+    title = editorProject.title,
+    status = editorProject.status,
+    branch = editorProject.branch,
+    files: initialFiles = editorFiles,
+    problems = editorProblems,
+    defaultOpen = editorDefaultOpen,
+    onSave,
+    onDeleteFile,
+    loader,
+    breadcrumbs = editorBreadcrumbs,
+    fullScreen = true,
+  } = props;
+  const [deleted, setDeleted] = useState<string[]>([]);
+  const [open, setOpen] = useState(() => defaultOpen.filter((p) => initialFiles.some((f) => f.path === p)));
+  const [active, setActive] = useState(open[0] ?? '');
+  const [nonce, setNonce] = useState(0);
+  const [edits, setEdits] = useState<Record<string, string>>({});
+  const [saving, setSaving] = useState(false);
+  const [note, setNote] = useState('');
+  const [target, setTarget] = useState<string | null>(null);
+
+  const files = initialFiles.filter((f) => !deleted.includes(f.path));
+  const isFile = (id: string | null | undefined): id is string => !!id && files.some((f) => f.path === id);
+  const openFiles = open.flatMap((p) => {
+    const f = files.find((x) => x.path === p);
+    return f ? [{ ...f, content: edits[p] ?? f.content }] : [];
+  });
+  const dirty = Object.keys(edits).filter((p) => edits[p] !== files.find((f) => f.path === p)?.content);
+
+  const openFile = (path: string) => {
+    if (!isFile(path)) return;
+    setOpen((list) => (list.includes(path) ? list : [...list, path]));
+    setActive(path);
+    // CodePanel only takes an initial file: remount it on the requested tab (edits live here).
+    setNonce((n) => n + 1);
+  };
+  const closeFile = (path: string) => {
+    const rest = open.filter((p) => p !== path);
+    setOpen(rest);
+    if (active === path) setActive(rest[0] ?? '');
+    setNonce((n) => n + 1);
+  };
+  const deleteFile = (path: string) => {
+    closeFile(path);
+    setDeleted((d) => [...d, path]);
+    onDeleteFile?.(path);
+    setNote(`Deleted ${path}`);
+  };
+  const copyPath = async (path: string) => {
+    try {
+      await navigator.clipboard.writeText(path);
+      setNote(`Copied ${path}`);
+    } catch {
+      setNote('Copy failed');
+    }
+  };
+  const save = async () => {
+    setSaving(true);
+    try {
+      await onSave?.(Object.fromEntries(dirty.map((p) => [p, edits[p] ?? ''])));
+      setNote('All changes saved');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  // Right click: the row under the pointer. Keyboard (Shift+F10): the focused row.
+  const pickTarget = (event: MouseEvent<HTMLElement>) => {
+    const fromPointer = (event.target as HTMLElement).closest<HTMLElement>('[role="treeitem"]');
+    const fromFocus = document.activeElement?.closest<HTMLElement>('[role="treeitem"]');
+    setTarget((fromPointer ?? fromFocus)?.dataset.id ?? null);
+  };
+  const menuFile = isFile(target) ? target : null;
+
+  return (
+    <CanvasLayout
+      fullScreen={fullScreen}
+      mainLabel={`${title} editor`}
+      smallScreenNotice={null}
+      paletteLabel="Files"
+      palette={
+        <ContextMenu>
+          <ContextMenuTrigger
+            tabIndex={-1}
+            role="group"
+            aria-label="Project files"
+            hint="Shift+F10 opens file actions"
+            onContextMenu={pickTarget}
+            className="block border-0 bg-transparent p-0"
+          >
+            <TreeList
+              aria-label="Files"
+              nodes={filesToTree(files.map((f) => f.path))}
+              defaultExpanded={['src/', 'config/']}
+              selected={active ? [active] : []}
+              onSelectedChange={(ids) => ids[0] && openFile(ids[0])}
+              onAction={(node) => openFile(node.id)}
+            />
+          </ContextMenuTrigger>
+          <ContextMenuContent className="w-52">
+            <MenuItem icon={ExternalLink} disabled={!menuFile} onClick={() => menuFile && openFile(menuFile)}>
+              Open
+            </MenuItem>
+            <MenuItem icon={Copy} disabled={!menuFile} onClick={() => menuFile && void copyPath(menuFile)}>
+              Copy path
+            </MenuItem>
+            <MenuItem
+              icon={X}
+              disabled={!menuFile || !open.includes(menuFile)}
+              onClick={() => menuFile && closeFile(menuFile)}
+            >
+              Close tab
+            </MenuItem>
+            <MenuSeparator />
+            <MenuItem icon={Trash2} destructive disabled={!menuFile} onClick={() => menuFile && deleteFile(menuFile)}>
+              Delete file
+            </MenuItem>
+          </ContextMenuContent>
+        </ContextMenu>
+      }
+      header={
+        <>
+          <div className="flex min-w-0 flex-1 items-center gap-3">
+            <Breadcrumbs items={breadcrumbs} className="hidden min-w-0 md:flex" />
+            <h1 className="truncate font-mono text-[14px] font-semibold text-foreground">{title}</h1>
+            <StatusTag status={status} />
+            <Badge size="sm" className="hidden font-mono sm:inline-flex">
+              {branch}
+            </Badge>
+            <p aria-live="polite" className="hidden truncate text-[12px] text-muted-foreground sm:block">
+              {note || (dirty.length ? `${dirty.length} unsaved ${dirty.length === 1 ? 'file' : 'files'}` : '')}
+            </p>
+          </div>
+          <Button size="sm" icon={Save} loading={saving} disabled={dirty.length === 0} onClick={() => void save()}>
+            Save
+          </Button>
+        </>
+      }
+    >
+      <div className="h-full overflow-auto p-3 sm:p-4">
+        {/* CodePanel titles its problems list h3 and has no heading level prop. */}
+        <h2 className="sr-only">Open files</h2>
+        {openFiles.length === 0 ? (
+          <p className="p-6 text-center text-[13px] text-muted-foreground">Open a file from the tree to edit it.</p>
+        ) : (
+          <CodePanel
+            key={`${nonce}`}
+            files={openFiles}
+            problems={problems.filter((p) => open.includes(p.file))}
+            defaultFile={active}
+            height={420}
+            loader={loader}
+            onChange={(path, value) => setEdits((e) => ({ ...e, [path]: value }))}
+          />
+        )}
+      </div>
+    </CanvasLayout>
+  );
+}