@gntik-ai/templates 0.0.0-stage → 0.5.0

package/src/live-event-stream/Page.tsx

@@ -0,0 +1,307 @@
+import {
+  ErrorPanel,
+  FormSection,
+  InlineCallout,
+  ListSkeleton,
+  LogViewer,
+  PageHeader,
+  type LogLine,
+} from '@gntik-ai/blocks';
+import {
+  Button,
+  EmptyState,
+  Field,
+  FieldLabel,
+  HStack,
+  Input,
+  InspectorLayout,
+  InspectorToggle,
+  JsonViewer,
+  Page,
+  StatusDot,
+  Toggle,
+  ToggleGroup,
+  useInspectorLayout,
+} from '@gntik-ai/ui';
+import { useMemo, useState, type ReactNode } from 'react';
+import { ConsoleShell, type ConsoleShellProps } from '../shared/ConsoleShell';
+import {
+  emptyStreamEvents,
+  streamDescription,
+  streamEventTypes,
+  streamSource,
+  streamTitle,
+  type LiveEvent,
+} from './data';
+
+export type { LiveEvent } from './data';
+
+export type LiveEventStreamStatus = 'idle' | 'connecting' | 'live' | 'error' | 'stopped';
+
+const CONNECTION = {
+  idle: { label: 'Not subscribed', tone: 'neutral', pulse: false },
+  connecting: { label: 'Connecting', tone: 'info', pulse: true },
+  live: { label: 'Live', tone: 'success', pulse: true },
+  error: { label: 'Error', tone: 'destructive', pulse: false },
+  stopped: { label: 'Stopped', tone: 'warning', pulse: false },
+} as const;
+
+/**
+ * Controlled subscription form, quiet windowed stream and pinnable JSON inspector.
+ * LiveEventStreamPage accepts Partial<LiveEventStreamProps>; omitted props use fixtures.
+ * No fetching, transport or subscription lifecycle is implemented here. Events must have
+ * unique ids and arrive oldest first. The newest maxEvents entries are retained.
+ *
+ * @remarks
+ * ARIA: one PageHeader h1; labelled FormSection; visible StatusDot text; a single polite,
+ * atomic connection status region. Only status changes and explicit consumer-throttled
+ * countAnnouncement updates change that region, never events.length. LogViewer uses
+ * announceLines=false (role=log, aria-live=off). Connecting replaces the log with decorative
+ * skeletons in an aria-busy section. ErrorPanel is wrapped in role=alert; validation uses
+ * InlineCallout. InspectorLayout supplies the complementary panel on desktop and a Drawer
+ * on small screens. Selection exposes aria-pressed on the row's inspect button.
+ * Pinning docks the panel without freezing selection. Eviction retains the last inspected
+ * payload and displays "This event is no longer in the buffer."
+ *
+ * Keyboard table:
+ * | Key | Behavior |
+ * | --- | --- |
+ * | Tab / Shift+Tab | Move through form, action, filters, search, Follow, inspect and copy. |
+ * | Enter / Space | Activate buttons, select an event, toggle Follow or pinning. |
+ * | Arrow keys | Navigate event-type and log-level ToggleGroups and the JSON tree. |
+ * | Escape | Close an unpinned inspector from its panel or toggle; return focus to the toggle. Pinned panels ignore Escape; use Close panel. |
+ * Scrolling up more than one row disables Follow and preserves the scroll offset.
+ * Enabling Follow pins the viewport to the bottom, where new events are appended.
+ *
+ * Themes: dark (default), light and high_contrast use only kit tokens. StatusDot pulses
+ * for connecting/live are disabled by prefers-reduced-motion. Sensitive fields in form
+ * must use the kit PasswordInput; the fixture contains only a non-sensitive Source field.
+ */
+export interface LiveEventStreamProps {
+  /** PageHeader h1. */
+  title: string;
+  /** Supporting text below the page title. */
+  description: string;
+  /** Consumer's subscription fields. Sensitive fields must use the kit PasswordInput. */
+  form: ReactNode;
+  /** Controlled connection state; defaults to idle. No transport is started by the template. */
+  status: LiveEventStreamStatus;
+  /** Controlled events in arrival order, oldest first. Defaults to the empty fixture. */
+  events: LiveEvent[];
+  /** Newest events retained (default 500). Nonnegative integers; invalid values use 500. */
+  maxEvents: number;
+  /** Type toggles, initially all enabled. Unlisted types remain visible. Defaults to fixture types. */
+  eventTypes: string[];
+  /** Optional consumer-throttled count text. Never inferred from events.length. */
+  countAnnouncement: string;
+  /** Called by Subscribe in idle, stopped or error. */
+  onSubscribe: () => void;
+  /** Called by Stop while live. */
+  onStop: () => void;
+  /** Called with the selected event after mouse or keyboard inspection. */
+  onSelectEvent: (event: LiveEvent) => void;
+  /** Stream error summary, shown in an ErrorPanel with role=alert when status is error. */
+  error: string;
+  /** Form validation feedback, shown in a destructive InlineCallout. */
+  validationMessage: string;
+  /** Explicit console navigation, workspace, user and topbar slots. */
+  shell: Omit<ConsoleShellProps, 'children'>;
+}
+
+function EventLog({
+  lines,
+  selectedLineId,
+  onSelectLine,
+}: {
+  lines: LogLine[];
+  selectedLineId?: string;
+  onSelectLine: (line: LogLine) => void;
+}) {
+  const { setOpen, panelId, docked, pinned } = useInspectorLayout();
+  return (
+    <LogViewer
+      title="Events"
+      titleAs="h2"
+      lines={lines}
+      announceLines={false}
+      selectedLineId={selectedLineId}
+      onSelectLine={(line) => {
+        onSelectLine(line);
+        setOpen(true);
+        if (docked && !pinned) requestAnimationFrame(() => document.getElementById(panelId)?.focus());
+      }}
+    />
+  );
+}
+
+export default function LiveEventStreamPage({
+  title = streamTitle,
+  description = streamDescription,
+  form = (
+    <Field>
+      <FieldLabel>Source</FieldLabel>
+      <Input defaultValue={streamSource} />
+    </Field>
+  ),
+  shell,
+  status = 'idle',
+  onSubscribe,
+  onStop,
+  onSelectEvent,
+  error = 'The subscription failed. Check the parameters and try again.',
+  validationMessage,
+  events = emptyStreamEvents,
+  maxEvents = 500,
+  eventTypes = streamEventTypes,
+  countAnnouncement,
+}: Partial<LiveEventStreamProps>) {
+  const [inspectorOpen, setInspectorOpen] = useState(false);
+  const [excludedTypes, setExcludedTypes] = useState<string[]>([]);
+  const [selected, setSelected] = useState<LiveEvent | null>(null);
+  const connection = CONNECTION[status];
+  const limit = Number.isInteger(maxEvents) && maxEvents >= 0 ? maxEvents : 500;
+  const buffer = useMemo(() => events.slice(Math.max(0, events.length - limit)), [events, limit]);
+  const eventsById = useMemo(() => new Map(buffer.map((event) => [event.id, event])), [buffer]);
+  const lines = useMemo<LogLine[]>(
+    () =>
+      buffer
+        .filter((event) => !excludedTypes.includes(event.type))
+        .map((event) => ({
+          id: event.id,
+          timestamp: event.timestamp,
+          level: 'info',
+          source: event.type,
+          message: event.summary ?? event.type,
+        })),
+    [buffer, excludedTypes],
+  );
+  return (
+    <ConsoleShell {...shell}>
+      <InspectorLayout
+        open={inspectorOpen}
+        onOpenChange={setInspectorOpen}
+        defaultPinned={false}
+        panelTitle="Event inspector"
+        panel={
+          selected ? (
+            <>
+              <JsonViewer
+                key={selected.id}
+                data={selected.payload}
+                label="Event payload"
+                defaultExpandDepth={2}
+                toolbar={false}
+              />
+              {!eventsById.has(selected.id) && (
+                <p className="mt-4 text-sm text-muted-foreground">This event is no longer in the buffer.</p>
+              )}
+            </>
+          ) : (
+            <p className="text-sm text-muted-foreground">Select an event to inspect its payload.</p>
+          )
+        }
+      >
+        <Page
+          width="wide"
+          header={
+            <PageHeader
+              title={title}
+              description={description}
+              breadcrumbs={null}
+              status=""
+              meta={[]}
+              tabs={null}
+              actions={[]}
+            />
+          }
+        >
+          <FormSection
+            title="Subscription parameters"
+            description="Choose the source to subscribe to."
+            actions={
+              <Button disabled={status === 'connecting'} onClick={status === 'live' ? onStop : onSubscribe}>
+                {status === 'live' ? 'Stop' : 'Subscribe'}
+              </Button>
+            }
+          >
+            {form}
+          </FormSection>
+          {validationMessage && (
+            <InlineCallout
+              tone="destructive"
+              title="Check subscription parameters"
+              description={validationMessage}
+              actions={[]}
+            />
+          )}
+          <HStack justify="between">
+            <StatusDot {...connection} />
+            <InspectorToggle label="Toggle event inspector" />
+          </HStack>
+          <p className="text-sm text-muted-foreground">
+            {buffer.length} of {events.length} events buffered
+          </p>
+          {eventTypes.length > 0 && (
+            <ToggleGroup
+              aria-label="Event types"
+              multiple
+              value={eventTypes.filter((type) => !excludedTypes.includes(type))}
+              onValueChange={(value) => setExcludedTypes(eventTypes.filter((type) => !value.includes(type)))}
+            >
+              {eventTypes.map((type) => (
+                <Toggle key={type} value={type}>
+                  {type}
+                </Toggle>
+              ))}
+            </ToggleGroup>
+          )}
+          <p role="status" aria-label="Connection status" aria-live="polite" aria-atomic="true" className="sr-only">
+            {connection.label}
+            {countAnnouncement ? `. ${countAnnouncement}` : ''}
+          </p>
+          {status === 'error' && (
+            <div role="alert" aria-label="Subscription error">
+              <ErrorPanel
+                title="Subscription error"
+                message={error}
+                code={null}
+                requestId=""
+                details=""
+                secondaryAction={null}
+                titleAs="h2"
+              />
+            </div>
+          )}
+          {status === 'connecting' ? (
+            <section aria-label="Events" aria-busy="true">
+              <div aria-hidden="true">
+                <ListSkeleton rows={5} label="Connecting" />
+              </div>
+            </section>
+          ) : buffer.length > 0 ? (
+            <EventLog
+              lines={lines}
+              selectedLineId={selected?.id}
+              onSelectLine={(line) => {
+                const event = eventsById.get(line.id);
+                if (!event) return;
+                setSelected(event);
+                onSelectEvent?.(event);
+              }}
+            />
+          ) : (
+            <div role="log" aria-label="Events" aria-live="off">
+              <EmptyState
+                titleAs="h2"
+                title={status === 'live' ? 'Listening for events' : 'No events yet'}
+                description={
+                  status === 'live' ? 'New events will appear here.' : 'Subscribe to start receiving events.'
+                }
+              />
+            </div>
+          )}
+        </Page>
+      </InspectorLayout>
+    </ConsoleShell>
+  );
+}

package/src/live-event-stream/data.ts

@@ -0,0 +1,44 @@
+/** Generic, transport-free subscription fixture. */
+export const streamTitle = 'Live event stream';
+export const streamDescription = 'Subscribe to a source and inspect the events it emits.';
+export const streamSource = 'activity';
+
+export interface LiveEvent {
+  /** Stable, unique event identity. */
+  id: string;
+  /** Consumer-formatted display timestamp. */
+  timestamp: string;
+  /** Event type used for filtering. */
+  type: string;
+  /** Optional concise row text; defaults to the event type. */
+  summary?: string;
+  /** Inspected only on selection; never serialised into log lines. */
+  payload: unknown;
+}
+
+export const emptyStreamEvents: LiveEvent[] = [];
+export const streamEventTypes = ['created', 'updated', 'deleted'];
+
+export const streamEvents: LiveEvent[] = [
+  {
+    id: 'event-1',
+    timestamp: '12:04:30.000',
+    type: 'created',
+    summary: 'Record created',
+    payload: { id: 'record-42', name: 'Sample record', revision: 1 },
+  },
+  {
+    id: 'event-2',
+    timestamp: '12:04:31.000',
+    type: 'updated',
+    summary: 'Record updated',
+    payload: { id: 'record-42', name: 'Updated record', revision: 2 },
+  },
+  {
+    id: 'event-3',
+    timestamp: '12:04:32.000',
+    type: 'deleted',
+    summary: 'Record deleted',
+    payload: { id: 'record-42', revision: 2 },
+  },
+];

package/src/live-event-stream/examples/Connecting.tsx

@@ -0,0 +1,5 @@
+import LiveEventStreamPage from '../Page';
+
+export default function Connecting() {
+  return <LiveEventStreamPage status="connecting" events={[]} />;
+}

package/src/live-event-stream/examples/Error.tsx

@@ -0,0 +1,5 @@
+import LiveEventStreamPage from '../Page';
+
+export default function ErrorExample() {
+  return <LiveEventStreamPage status="error" error="The event source is unavailable. Try subscribing again." />;
+}

package/src/live-event-stream/examples/LiveEmpty.tsx

@@ -0,0 +1,5 @@
+import LiveEventStreamPage from '../Page';
+
+export default function LiveEmpty() {
+  return <LiveEventStreamPage status="live" events={[]} />;
+}

package/src/live-event-stream/examples/LiveWithEvents.tsx

@@ -0,0 +1,6 @@
+import LiveEventStreamPage from '../Page';
+import { streamEvents } from '../data';
+
+export default function LiveWithEvents() {
+  return <LiveEventStreamPage status="live" events={streamEvents} />;
+}

package/src/live-event-stream/examples/Stopped.tsx

@@ -0,0 +1,6 @@
+import LiveEventStreamPage from '../Page';
+import { streamEvents } from '../data';
+
+export default function Stopped() {
+  return <LiveEventStreamPage status="stopped" events={streamEvents} />;
+}

package/src/live-event-stream/template.meta.ts

@@ -0,0 +1,74 @@
+import type { TemplateMeta } from '../meta';
+
+export const meta = {
+  name: 'Live event stream',
+  family: 'Builders',
+  priority: 'P3',
+  status: 'experimental',
+  description: `Controlled subscription form inside FormSection, a visible StatusDot connection indicator, a quiet role=log stream with LogViewer windowing, search, follow-tail and copy, and a pinnable JSON inspector on InspectorLayout. No fetching or transport; no trace waterfall, token cost or timer.
+
+## Props
+
+LiveEventStreamPage accepts Partial<LiveEventStreamProps>; omitted props use generic fixtures.
+
+| Prop | Type | Default / behavior |
+| --- | --- | --- |
+| title | string | Live event stream; PageHeader h1 |
+| description | string | Subscribe to a source and inspect the events it emits. |
+| form | ReactNode | Non-sensitive Source field inside FormSection; sensitive fields must use the kit PasswordInput |
+| status | idle / connecting / live / error / stopped | idle; fully controlled |
+| events | LiveEvent[] | Empty fixture; unique id, timestamp, type, optional summary and unknown payload; oldest first |
+| maxEvents | number | 500; nonnegative integer; retains newest entries, evicts oldest; invalid values use 500 |
+| eventTypes | string[] | created, updated, deleted; multiple ToggleGroup, initially all enabled; unlisted types remain visible |
+| countAnnouncement | string | Omitted; optional count text throttled by the consumer, never inferred from events.length |
+| onSubscribe | () => void | Subscribe callback in idle, stopped and error; disabled while connecting |
+| onStop | () => void | Stop callback while live |
+| onSelectEvent | (event: LiveEvent) => void | Mouse or keyboard selection callback |
+| error | string | Generic subscription error; ErrorPanel shown when status=error, inside role=alert |
+| validationMessage | string | Omitted; destructive InlineCallout |
+| shell | Omit<ConsoleShellProps, 'children'> | ConsoleShell fixture defaults; explicit consumer navigation, workspace, user and topbar slots |
+
+Status mapping: idle = neutral Not subscribed; connecting = info Connecting with pulse; live = success Live with pulse; error = destructive Error; stopped = warning Stopped. Subscribe is shown in idle/connecting/error/stopped and is disabled for connecting; live shows Stop. Idle has No events yet, live-empty has Listening for events, connecting replaces the log with decorative skeletons, and stopped keeps supplied buffered events visible.
+
+## ARIA pattern
+
+PageHeader h1 and labelled FormSection. One polite atomic live region announces connection status and explicit consumer-throttled count text only. LogViewer uses announceLines=false: role=log and aria-live=off; event additions are silent. Connecting uses an aria-busy section. Stream errors use ErrorPanel inside role=alert; validation uses InlineCallout. Inspect buttons have the name Inspect event <timestamp> and aria-pressed. InspectorLayout owns the complementary landmark on desktop, Drawer on small screens, docking, pinning and focus return. Pinning does not freeze the payload: subsequent selection updates it; eviction preserves the last inspected payload with the note This event is no longer in the buffer.
+
+## Keyboard table
+
+| Key | Behavior |
+| --- | --- |
+| Tab / Shift+Tab | Form fields, Subscribe/Stop, filters, search, Follow, row inspect/copy and panel controls |
+| Enter / Space | Activate buttons; select an event; toggle Follow and pinning |
+| Arrow keys | Navigate ToggleGroups and the JsonViewer tree |
+| Escape | From unpinned panel or toggle, close and return focus to inspector toggle; pinned panel ignores Escape, Close panel closes it |
+
+Follow pins the bottom, where the newest row is added. Scrolling up by more than one row turns Follow off and preserves the viewport offset; switching Follow on returns to the bottom.
+
+## Themes and examples
+
+Dark (default), light and high_contrast use only kit tokens. Connecting/live pulses stop under prefers-reduced-motion. State previews: live-event-stream--connecting, --live-empty, --live-with-events, --error and --stopped. Every state and the default template are covered by axe in all three themes.`,
+  layout: 'InspectorLayout',
+  blocks: [
+    'app-sidebar',
+    'app-topbar',
+    'page-header',
+    'form-section',
+    'log-viewer',
+    'empty-states',
+    'skeletons',
+    'inline-callout',
+    'error-panel',
+  ],
+  pattern:
+    'PageHeader h1, labelled FormSection, one polite atomic connection live region, quiet role=log stream (aria-live=off), alert errors and complementary JSON inspector. Selected inspect buttons expose aria-pressed.',
+  keyboard: [
+    ['Tab / Shift+Tab', 'Navigate form, action, filters, search, Follow, row inspect/copy and panel controls.'],
+    ['Enter / Space', 'Activate buttons, select an event and toggle Follow or pinning.'],
+    ['Arrow keys', 'Navigate ToggleGroups and the JSON tree.'],
+    [
+      'Escape',
+      'Close an unpinned inspector from panel or toggle and return focus to the toggle. Pinned panels ignore Escape.',
+    ],
+  ],
+} satisfies TemplateMeta & { pattern: string; keyboard: [string, string][] };

package/src/messaging/Page.test.tsx

@@ -0,0 +1,34 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../test/a11y';
+import MessagingPage from './Page';
+import { conversations } from './data';
+
+describe('MessagingPage', () => {
+  it('renders the conversation list and the empty thread', { timeout: 15000 }, async () => {
+    render(<MessagingPage />);
+    expect(screen.getByRole('main')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { level: 1, name: 'Messages' })).toBeInTheDocument();
+    const list = screen.getByRole('list', { name: 'Conversations' });
+    expect(within(list).getAllByRole('button')).toHaveLength(conversations.length);
+    expect(within(list).getByText('2')).toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: 'Select a conversation' })).toBeInTheDocument();
+    await expectNoAxeViolations();
+  });
+
+  it('opens a thread with attachments and sends a message', { timeout: 15000 }, async () => {
+    const onSend = vi.fn();
+    render(<MessagingPage onSend={onSend} />);
+    await userEvent.click(
+      within(screen.getByRole('list', { name: 'Conversations' })).getByRole('button', { name: /Release 2\.14/ }),
+    );
+    const log = screen.getByRole('log', { name: 'Messages in Release 2.14' });
+    expect(within(log).getAllByRole('article')).toHaveLength(4);
+    expect(within(log).getByText('rollback-runbook.pdf')).toBeInTheDocument();
+    await userEvent.type(screen.getByRole('textbox', { name: 'Message Release 2.14' }), 'Ship it.{Enter}');
+    expect(onSend).toHaveBeenCalledWith('c-release', 'Ship it.', []);
+    expect(within(log).getAllByRole('article')).toHaveLength(5);
+    expect(within(log).getByText('Ship it.')).toBeInTheDocument();
+    await expectNoAxeViolations();
+  });
+});