@gntik-ai/templates 0.0.0-stage → 0.6.0

package/src/board/Page.test.tsx

@@ -0,0 +1,68 @@
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import BoardPage from './Page';
+import { boardColumns, boardState, moveCard } from './data';
+
+const lane = (name: string) => screen.getByRole('region', { name: new RegExp(`^${name}`) });
+
+describe('BoardPage', () => {
+  it('renders every column with its cards', { timeout: 15000 }, async () => {
+    render(<BoardPage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Sprint board' })).toBeInTheDocument();
+    for (const c of boardColumns)
+      expect(within(lane(c.title)).getAllByRole('button')).toHaveLength(boardState[c.id]!.length);
+    await expectNoAxeViolations();
+  });
+
+  it('moves a card with the keyboard and announces each step', { timeout: 15000 }, async () => {
+    const onMove = vi.fn();
+    render(<BoardPage onMove={onMove} />);
+    const card = within(lane('Backlog')).getByRole('button', { name: /Rotate staging/ });
+    card.focus();
+    await userEvent.keyboard(' ');
+    expect(card).toHaveAttribute('aria-pressed', 'true');
+    expect(
+      screen.getByText(/Picked up Rotate staging database credentials in Backlog, position 1 of 3/),
+    ).toBeInTheDocument();
+    await userEvent.keyboard('{ArrowRight}');
+    const moved = within(lane('In progress')).getByRole('button', { name: /Rotate staging/ });
+    expect(moved).toHaveFocus();
+    expect(screen.getByText('Moved to In progress, position 1 of 3.')).toBeInTheDocument();
+    await userEvent.keyboard('{ArrowDown} ');
+    expect(onMove).toHaveBeenCalledWith('T-101', 'in-progress', 1);
+    expect(
+      screen.getByText(/Dropped Rotate staging database credentials in In progress, position 2 of 3/),
+    ).toBeInTheDocument();
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  });
+
+  it('Escape returns a picked-up card to where it was', { timeout: 15000 }, async () => {
+    render(<BoardPage />);
+    within(lane('In review'))
+      .getByRole('button', { name: /audit log export/ })
+      .focus();
+    await userEvent.keyboard(' {ArrowRight}{Escape}');
+    expect(within(lane('In review')).getByRole('button', { name: /audit log export/ })).toHaveFocus();
+    expect(screen.getByText(/Cancelled\./)).toBeInTheDocument();
+  });
+
+  it('drops a card dragged with the pointer and opens the detail drawer', { timeout: 15000 }, async () => {
+    const onMove = vi.fn();
+    render(<BoardPage onMove={onMove} />);
+    const card = within(lane('Backlog')).getByRole('button', { name: /invoices table/ });
+    fireEvent.dragStart(card);
+    fireEvent.dragOver(lane('Done'));
+    fireEvent.drop(lane('Done'));
+    expect(onMove).toHaveBeenCalledWith('T-103', 'done', 1);
+    await userEvent.click(within(lane('Done')).getByRole('button', { name: /invoices table/ }));
+    const drawer = await screen.findByRole('dialog', { name: 'Empty state for the invoices table' });
+    expect(within(drawer).getByRole('combobox', { name: 'Status' })).toHaveTextContent('Done');
+    await expectNoAxeViolations();
+  });
+
+  it('moveCard keeps every other card in order', () => {
+    expect(moveCard(boardState, 'T-104', 'backlog', 1).backlog).toEqual(['T-101', 'T-104', 'T-102', 'T-103']);
+  });
+});

package/src/board/Page.tsx

@@ -0,0 +1,178 @@
+import { PageHeader } from '@gntik-ai/blocks';
+import { Plus } from '@gntik-ai/icons';
+import {
+  Avatar,
+  Badge,
+  Drawer,
+  DrawerBody,
+  DrawerContent,
+  DrawerDescription,
+  DrawerHeader,
+  DrawerTitle,
+  HStack,
+  Page,
+  SimpleSelect,
+  Stack,
+  Text,
+  Timestamp,
+  VisuallyHidden,
+  type BreadcrumbItem,
+} from '@gntik-ai/ui';
+import { useId, useState } from 'react';
+import { ConsoleShell, type ConsoleShellProps } from '../shared/ConsoleShell';
+import {
+  boardBreadcrumbs,
+  boardCards,
+  boardColumns,
+  boardState,
+  locate,
+  priorityLabels,
+  priorityTones,
+  type BoardCard,
+  type BoardColumn,
+  type BoardState,
+} from './data';
+import { Lane } from './Lane';
+import { useBoard } from './useBoard';
+
+export interface BoardProps {
+  title: string;
+  description: string;
+  columns: BoardColumn[];
+  cards: BoardCard[];
+  /** Card ids per column id. */
+  defaultState: BoardState;
+  /** Fires after a drop (pointer, keyboard or the detail drawer's status select). */
+  onMove: (cardId: string, toColumn: string, toIndex: number) => void;
+  onCreate: () => void;
+  breadcrumbs: BreadcrumbItem[];
+  currentHref: string;
+  shell: Omit<ConsoleShellProps, 'children'>;
+}
+
+/** Kanban board: columns with pointer and keyboard drag-and-drop, live announcements and a card detail Drawer. */
+export default function BoardPage(props: Partial<BoardProps>) {
+  const {
+    title = 'Sprint board',
+    description = 'Drag cards between columns, or focus a card and press Space to pick it up.',
+    columns = boardColumns,
+    cards = boardCards,
+    defaultState = boardState,
+    onMove,
+    onCreate,
+    breadcrumbs = boardBreadcrumbs,
+    currentHref = '/projects',
+    shell,
+  } = props;
+  const board = useBoard({ columns, cards, initial: defaultState, onMove });
+  const [openId, setOpenId] = useState<string | null>(null);
+  const ids = useId();
+  const byId = new Map(cards.map((c) => [c.id, c]));
+  const open = openId ? byId.get(openId) : undefined;
+  const openAt = openId ? locate(board.state, openId) : null;
+
+  return (
+    <ConsoleShell breadcrumbs={breadcrumbs} currentHref={currentHref} {...shell}>
+      <Page
+        width="full"
+        header={
+          <PageHeader
+            breadcrumbs={null}
+            title={title}
+            description={description}
+            status=""
+            meta={[]}
+            tabs={null}
+            actions={[{ label: 'New card', icon: Plus, onClick: onCreate }]}
+          />
+        }
+      >
+        <VisuallyHidden id={`${ids}-help`}>
+          Press Space to pick up the card, arrow keys to move it, Space to drop and Escape to cancel. Enter opens the
+          details.
+        </VisuallyHidden>
+        <VisuallyHidden aria-live="assertive" aria-atomic="true">
+          {board.announcement}
+        </VisuallyHidden>
+        <div role="group" aria-label="Board" className="flex gap-4 overflow-x-auto pb-2">
+          {columns.map((col) => (
+            <Lane
+              key={col.id}
+              column={col}
+              cards={(board.state[col.id] ?? []).flatMap((id) => byId.get(id) ?? [])}
+              headingId={`${ids}-${col.id}`}
+              instructionsId={`${ids}-help`}
+              grabbedId={board.grabbedId}
+              draggingId={board.dragging}
+              isDropTarget={board.dropColumn === col.id}
+              register={board.register}
+              onOpen={setOpenId}
+              onCardKeyDown={board.onCardKeyDown}
+              onCardKeyUp={board.onCardKeyUp}
+              onDragStart={board.onDragStart}
+              onDragEnd={board.onDragEnd}
+              onDragOver={board.onColumnDragOver(col.id)}
+              onDrop={board.onColumnDrop(col.id)}
+            />
+          ))}
+        </div>
+      </Page>
+      <Drawer open={open != null} onOpenChange={(next) => !next && setOpenId(null)}>
+        <DrawerContent size="md">
+          {open && (
+            <>
+              <DrawerHeader>
+                <DrawerTitle>{open.title}</DrawerTitle>
+                <DrawerDescription>{open.id}</DrawerDescription>
+              </DrawerHeader>
+              <DrawerBody>
+                <Stack gap={5}>
+                  <HStack gap={2} wrap>
+                    <Badge tone={priorityTones[open.priority]}>{priorityLabels[open.priority]} priority</Badge>
+                    {open.labels.map((l) => (
+                      <Badge key={l} variant="outline">
+                        {l}
+                      </Badge>
+                    ))}
+                  </HStack>
+                  <Text variant="supporting">{open.description}</Text>
+                  <dl className="grid grid-cols-[7rem_1fr] items-center gap-x-4 gap-y-3 text-[13px]">
+                    <dt className="text-muted-foreground">Status</dt>
+                    <dd>
+                      <SimpleSelect
+                        aria-label="Status"
+                        size="sm"
+                        items={columns.map((c) => ({ value: c.id, label: c.title }))}
+                        value={openAt?.column ?? null}
+                        onValueChange={(v) => v && board.moveTo(open.id, v, board.state[v]?.length ?? 0)}
+                        className="w-44"
+                      />
+                    </dd>
+                    <dt className="text-muted-foreground">Assignee</dt>
+                    <dd className="flex items-center gap-2 text-foreground">
+                      <Avatar size="xs" name={open.assignee} aria-hidden />
+                      {open.assignee}
+                    </dd>
+                    <dt className="text-muted-foreground">Due</dt>
+                    <dd className="text-foreground">
+                      {open.due ? (
+                        <Timestamp
+                          value={open.due}
+                          format="absolute"
+                          tooltip={false}
+                          dateOptions={{ dateStyle: 'medium' }}
+                        />
+                      ) : (
+                        'No due date'
+                      )}
+                    </dd>
+                  </dl>
+                </Stack>
+              </DrawerBody>
+            </>
+          )}
+        </DrawerContent>
+      </Drawer>
+    </ConsoleShell>
+  );
+}

package/src/board/data.ts

@@ -0,0 +1,127 @@
+import type { BadgeProps, BreadcrumbItem } from '@gntik-ai/ui';
+
+export interface BoardColumn {
+  id: string;
+  title: string;
+}
+
+export interface BoardCard {
+  id: string;
+  title: string;
+  description: string;
+  assignee: string;
+  labels: string[];
+  priority: 'low' | 'medium' | 'high';
+  /** ISO date. */
+  due?: string;
+}
+
+/** Card ids per column id, in display order. */
+export type BoardState = Record<string, string[]>;
+
+export const priorityTones: Record<BoardCard['priority'], NonNullable<BadgeProps['tone']>> = {
+  low: 'neutral',
+  medium: 'info',
+  high: 'warning',
+};
+export const priorityLabels: Record<BoardCard['priority'], string> = { low: 'Low', medium: 'Medium', high: 'High' };
+
+export const boardBreadcrumbs: BreadcrumbItem[] = [
+  { label: 'Acme Industries', href: '/overview' },
+  { label: 'Projects', href: '/projects' },
+  { label: 'Board' },
+];
+
+export const boardColumns: BoardColumn[] = [
+  { id: 'backlog', title: 'Backlog' },
+  { id: 'in-progress', title: 'In progress' },
+  { id: 'review', title: 'In review' },
+  { id: 'done', title: 'Done' },
+];
+
+export const boardCards: BoardCard[] = [
+  {
+    id: 'T-101',
+    title: 'Rotate staging database credentials',
+    description: 'Move the staging credentials to the secrets store and rotate them.',
+    assignee: 'Ada Example',
+    labels: ['security'],
+    priority: 'high',
+    due: '2026-10-08',
+  },
+  {
+    id: 'T-102',
+    title: 'Add retry budget to webhooks',
+    description: 'Cap retries per endpoint per hour so one bad endpoint cannot flood the queue.',
+    assignee: 'Linus Park',
+    labels: ['backend'],
+    priority: 'medium',
+  },
+  {
+    id: 'T-103',
+    title: 'Empty state for the invoices table',
+    description: 'Explain why the table is empty on new workspaces and link to billing settings.',
+    assignee: 'Grace Hall',
+    labels: ['frontend', 'design'],
+    priority: 'low',
+  },
+  {
+    id: 'T-104',
+    title: 'Migrate usage exports to the new queue',
+    description: 'Large exports should run as background jobs and notify when ready.',
+    assignee: 'Ada Example',
+    labels: ['backend'],
+    priority: 'high',
+    due: '2026-10-15',
+  },
+  {
+    id: 'T-105',
+    title: 'Keyboard shortcuts for the deployments table',
+    description: 'J / K to move, Enter to open, X to select.',
+    assignee: 'Grace Hall',
+    labels: ['frontend', 'a11y'],
+    priority: 'medium',
+  },
+  {
+    id: 'T-106',
+    title: 'Document the audit log export format',
+    description: 'Fields, types and an example line for the JSON export.',
+    assignee: 'Linus Park',
+    labels: ['docs'],
+    priority: 'low',
+  },
+  {
+    id: 'T-107',
+    title: 'Region picker on project creation',
+    description: 'Default to the workspace region, warn about data residency.',
+    assignee: 'Ada Example',
+    labels: ['frontend'],
+    priority: 'medium',
+  },
+];
+
+export const boardState: BoardState = {
+  backlog: ['T-101', 'T-102', 'T-103'],
+  'in-progress': ['T-104', 'T-105'],
+  review: ['T-106'],
+  done: ['T-107'],
+};
+
+/** Moves a card to `toColumn` at `toIndex` (clamped); returns a new state. */
+export function moveCard(state: BoardState, cardId: string, toColumn: string, toIndex: number): BoardState {
+  const next: BoardState = {};
+  for (const [col, ids] of Object.entries(state)) next[col] = ids.filter((id) => id !== cardId);
+  const target = next[toColumn] ?? [];
+  const index = Math.max(0, Math.min(toIndex, target.length));
+  next[toColumn] = [...target.slice(0, index), cardId, ...target.slice(index)];
+  return next;
+}
+
+/** Column id and index of a card. */
+export function locate(state: BoardState, cardId: string): { column: string; index: number } | null {
+  for (const [column, ids] of Object.entries(state)) {
+    const index = ids.indexOf(cardId);
+    if (index >= 0) return { column, index };
+  }
+  return null;
+}

package/src/board/template.meta.ts

@@ -0,0 +1,12 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta: TemplateMeta = {
+  name: 'Board',
+  family: 'Resources',
+  priority: 'P3',
+  status: 'experimental',
+  description:
+    'Kanban board in the console: columns with counts, cards with priority, labels, due date and assignee; pointer drag-and-drop between and within columns, keyboard moves (Space to pick up, arrows to move, Space to drop, Escape to cancel) with live announcements, and a card detail Drawer whose status select also moves the card.',
+  layout: 'SidebarLayout · Page',
+  blocks: ['app-sidebar', 'app-topbar', 'page-header'],
+};

package/src/board/useBoard.ts

@@ -0,0 +1,146 @@
+import { useRef, useState, type DragEvent, type KeyboardEvent } from 'react';
+import { flushSync } from 'react-dom';
+import { locate, moveCard, type BoardCard, type BoardColumn, type BoardState } from './data';
+
+export interface UseBoardOptions {
+  columns: readonly BoardColumn[];
+  cards: readonly BoardCard[];
+  initial: BoardState;
+  onMove?: (cardId: string, toColumn: string, toIndex: number) => void;
+}
+
+interface Grab {
+  id: string;
+  origin: { column: string; index: number };
+}
+
+/**
+ * Board state with both drag paths: pointer (HTML drag and drop onto a column or before a card)
+ * and keyboard (Space picks up, arrows move, Space or Enter drops, Escape cancels). Every step is
+ * announced through `announcement`, and focus follows the moved card.
+ */
+export function useBoard({ columns, cards, initial, onMove }: UseBoardOptions) {
+  const [state, setState] = useState<BoardState>(initial);
+  const [grab, setGrab] = useState<Grab | null>(null);
+  const [dragging, setDragging] = useState<string | null>(null);
+  const [dropColumn, setDropColumn] = useState<string | null>(null);
+  const [announcement, setAnnouncement] = useState('');
+  const buttons = useRef(new Map<string, HTMLButtonElement>());
+
+  const titleOf = (id: string) => cards.find((c) => c.id === id)?.title ?? id;
+  const columnTitle = (id: string) => columns.find((c) => c.id === id)?.title ?? id;
+  const where = (s: BoardState, column: string, index: number) =>
+    `${columnTitle(column)}, position ${index + 1} of ${s[column]?.length ?? 0}`;
+
+  const register = (id: string) => (el: HTMLButtonElement | null) => {
+    if (el) buttons.current.set(id, el);
+    else buttons.current.delete(id);
+  };
+
+  /** Moves synchronously so the remounted card can take focus right away. */
+  const commit = (id: string, column: string, index: number) => {
+    const next = moveCard(state, id, column, index);
+    flushSync(() => setState(next));
+    buttons.current.get(id)?.focus();
+    return next;
+  };
+
+  const moveTo = (id: string, column: string, index: number, announce = true) => {
+    const next = commit(id, column, index);
+    const at = locate(next, id);
+    if (at) {
+      if (announce) setAnnouncement(`Dropped ${titleOf(id)} in ${where(next, at.column, at.index)}.`);
+      onMove?.(id, at.column, at.index);
+    }
+  };
+
+  const onCardKeyDown = (id: string) => (e: KeyboardEvent<HTMLButtonElement>) => {
+    const at = locate(state, id);
+    if (!at) return;
+    const held = grab?.id === id;
+    if (e.key === ' ' || (held && e.key === 'Enter')) {
+      e.preventDefault();
+      if (held) {
+        setGrab(null);
+        setAnnouncement(`Dropped ${titleOf(id)} in ${where(state, at.column, at.index)}.`);
+        onMove?.(id, at.column, at.index);
+      } else {
+        setGrab({ id, origin: at });
+        setAnnouncement(
+          `Picked up ${titleOf(id)} in ${where(state, at.column, at.index)}. Use the arrow keys to move, Space to drop, Escape to cancel.`,
+        );
+      }
+      return;
+    }
+    if (!held) return;
+    const colIndex = columns.findIndex((c) => c.id === at.column);
+    let target: { column: string; index: number } | null = null;
+    if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+      const nextCol = columns[colIndex + (e.key === 'ArrowRight' ? 1 : -1)];
+      if (nextCol) target = { column: nextCol.id, index: Math.min(at.index, state[nextCol.id]?.length ?? 0) };
+    } else if (e.key === 'ArrowUp' || e.key === 'ArrowDown') {
+      const index = at.index + (e.key === 'ArrowDown' ? 1 : -1);
+      if (index >= 0 && index < (state[at.column]?.length ?? 0)) target = { column: at.column, index };
+    } else if (e.key === 'Escape' && grab) {
+      e.preventDefault();
+      const next = commit(id, grab.origin.column, grab.origin.index);
+      setGrab(null);
+      setAnnouncement(`Cancelled. ${titleOf(id)} returned to ${where(next, grab.origin.column, grab.origin.index)}.`);
+      return;
+    }
+    if (!target) return;
+    e.preventDefault();
+    const next = commit(id, target.column, target.index);
+    const now = locate(next, id);
+    if (now) setAnnouncement(`Moved to ${where(next, now.column, now.index)}.`);
+  };
+
+  /** Space activates buttons on keyup; cancel it so picking up does not open the card. */
+  const onCardKeyUp = (e: KeyboardEvent<HTMLButtonElement>) => {
+    if (e.key === ' ') e.preventDefault();
+  };
+
+  const onDragStart = (id: string) => (e: DragEvent<HTMLElement>) => {
+    e.dataTransfer?.setData('text/plain', id);
+    if (e.dataTransfer) e.dataTransfer.effectAllowed = 'move';
+    setDragging(id);
+  };
+  const onDragEnd = () => {
+    setDragging(null);
+    setDropColumn(null);
+  };
+  const onColumnDragOver = (column: string) => (e: DragEvent<HTMLElement>) => {
+    if (!dragging) return;
+    e.preventDefault();
+    if (dropColumn !== column) setDropColumn(column);
+  };
+  const onColumnDrop = (column: string) => (e: DragEvent<HTMLElement>) => {
+    if (!dragging) return;
+    e.preventDefault();
+    const before = (e.target as HTMLElement).closest<HTMLElement>('[data-card-index]');
+    const from = locate(state, dragging);
+    let index = before ? Number(before.dataset.cardIndex) : (state[column]?.length ?? 0);
+    // Dropping before a later card of the same column: the card leaves its slot first.
+    if (from && from.column === column && from.index < index) index -= 1;
+    const id = dragging;
+    setDragging(null);
+    setDropColumn(null);
+    moveTo(id, column, index);
+  };
+
+  return {
+    state,
+    grabbedId: grab?.id ?? null,
+    dragging,
+    dropColumn,
+    announcement,
+    register,
+    moveTo,
+    onCardKeyDown,
+    onCardKeyUp,
+    onDragStart,
+    onDragEnd,
+    onColumnDragOver,
+    onColumnDrop,
+  };
+}

package/src/changelog/Page.test.tsx

@@ -0,0 +1,31 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import ChangelogPage from './Page';
+import { changelogEntries } from './data';
+
+describe('ChangelogPage', () => {
+  it('renders every release with its badges', { timeout: 15000 }, async () => {
+    render(<ChangelogPage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Changelog' })).toBeInTheDocument();
+    const list = screen.getByRole('list', { name: 'Releases' });
+    expect(within(list).getAllByRole('article')).toHaveLength(changelogEntries.length);
+    expect(within(list).getAllByText('New')).toHaveLength(changelogEntries.filter((e) => e.isNew).length);
+    await expectNoAxeViolations();
+  });
+
+  it('filters by tag and resets', { timeout: 15000 }, async () => {
+    const onTagsChange = vi.fn();
+    render(<ChangelogPage onTagsChange={onTagsChange} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Security' }));
+    expect(onTagsChange).toHaveBeenLastCalledWith(['security']);
+    const list = screen.getByRole('list', { name: 'Releases' });
+    expect(within(list).getAllByRole('article')).toHaveLength(
+      changelogEntries.filter((e) => e.tags.includes('security')).length,
+    );
+    expect(screen.getByText('2 releases')).toBeInTheDocument();
+    await userEvent.click(screen.getByRole('button', { name: 'Show all' }));
+    expect(screen.getByText(`${changelogEntries.length} releases`)).toBeInTheDocument();
+  });
+});