@gntik-ai/blocks 0.0.0-stage → 0.6.0

package/src/data-display/DescriptionListCard/DescriptionListCard.tsx

@@ -0,0 +1,120 @@
+import { Check, Copy, Pencil } from '@gntik-ai/icons';
+import {
+  Button,
+  Card,
+  CardAction,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  cn,
+  IconButton,
+  StatusTag,
+} from '@gntik-ai/ui';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { DEPLOYMENT_DETAILS } from './fixtures';
+
+export interface DescriptionItem {
+  id: string;
+  label: string;
+  /** Text value; also what the copy button copies unless `copyValue` is set. */
+  value?: string;
+  /** Rich value (overrides `value` for display). */
+  render?: ReactNode;
+  /** Shows the value as a StatusTag with this state key. */
+  status?: string;
+  /** Monospace value (IDs, regions, URLs). */
+  mono?: boolean;
+  /** Adds a copy button. */
+  copyable?: boolean;
+  copyValue?: string;
+}
+
+export interface DescriptionListCardProps {
+  title?: string;
+  description?: string;
+  items?: readonly DescriptionItem[];
+  /** Shows an Edit button in the header. */
+  onEdit?: () => void;
+  editLabel?: string;
+  /** Called after a value is copied. */
+  onCopy?: (item: DescriptionItem) => void;
+  /** Heading level of the title, to fit the page outline (default h3). */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+function CopyButton({ item, onCopy }: { item: DescriptionItem; onCopy?: (item: DescriptionItem) => void }) {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<number | undefined>(undefined);
+  useEffect(() => () => window.clearTimeout(timer.current), []);
+  const copy = async () => {
+    const text = item.copyValue ?? item.value ?? '';
+    try {
+      await navigator.clipboard?.writeText(text);
+    } catch {}
+    setCopied(true);
+    onCopy?.(item);
+    window.clearTimeout(timer.current);
+    timer.current = window.setTimeout(() => setCopied(false), 1500);
+  };
+  return (
+    <>
+      <IconButton
+        icon={copied ? Check : Copy}
+        label={copied ? `${item.label} copied` : `Copy ${item.label}`}
+        size="sm"
+        variant="ghost"
+        className={cn('size-7 shrink-0', copied && 'text-success-text')}
+        onClick={copy}
+      />
+      <span className="sr-only" aria-live="polite">
+        {copied ? 'Copied to clipboard' : ''}
+      </span>
+    </>
+  );
+}
+
+/** Key–value detail card: label column, values (mono, status or rich), copy buttons and an Edit action. */
+export function DescriptionListCard({
+  title = 'Configuration',
+  description = 'Settings of this deployment.',
+  items = DEPLOYMENT_DETAILS,
+  onEdit,
+  editLabel = 'Edit',
+  onCopy,
+  titleAs = 'h3',
+  className,
+}: DescriptionListCardProps) {
+  return (
+    <Card className={className}>
+      <CardHeader divided>
+        <CardTitle as={titleAs}>{title}</CardTitle>
+        {description && <CardDescription>{description}</CardDescription>}
+        {onEdit && (
+          <CardAction>
+            <Button variant="secondary" size="sm" icon={Pencil} onClick={onEdit}>
+              {editLabel}
+            </Button>
+          </CardAction>
+        )}
+      </CardHeader>
+      <dl className="divide-y divide-border px-5">
+        {items.map((item) => (
+          <div key={item.id} className="grid grid-cols-1 gap-1 py-3.5 sm:grid-cols-[160px_minmax(0,1fr)] sm:gap-4">
+            <dt className="text-[13px] text-muted-foreground">{item.label}</dt>
+            <dd className="flex min-w-0 items-center gap-2 text-[13px] text-foreground">
+              {item.status ? (
+                <StatusTag status={item.status} />
+              ) : (
+                <span className={cn('min-w-0 truncate', item.mono && 'font-mono text-[12.5px]')}>
+                  {item.render ?? item.value}
+                </span>
+              )}
+              {item.copyable && <CopyButton item={item} onCopy={onCopy} />}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </Card>
+  );
+}

package/src/data-display/DescriptionListCard/block.meta.ts

@@ -0,0 +1,9 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Description list card',
+  family: 'data-display',
+  status: 'beta',
+  description: 'Key–value detail card with mono, status and rich values, copy-to-clipboard buttons and an Edit action.',
+  uses: ['Card', 'Button', 'IconButton', 'StatusTag'],
+};

package/src/data-display/DescriptionListCard/fixtures.ts

@@ -0,0 +1,12 @@
+import type { DescriptionItem } from './DescriptionListCard';
+
+/** Configuration of a deployment. */
+export const DEPLOYMENT_DETAILS: DescriptionItem[] = [
+  { id: 'status', label: 'Status', status: 'running' },
+  { id: 'id', label: 'Deployment ID', value: 'dep_7f3c9a21', mono: true, copyable: true },
+  { id: 'runtime', label: 'Runtime', value: 'node-24', mono: true },
+  { id: 'region', label: 'Region', value: 'eu-west-1', mono: true },
+  { id: 'endpoint', label: 'Endpoint', value: 'https://api.example.com/v1/orders', mono: true, copyable: true },
+  { id: 'owner', label: 'Owner', value: 'Platform team' },
+  { id: 'created', label: 'Created', value: 'Mar 12, 2026, 09:41' },
+];

package/src/data-display/KpiRow/KpiRow.test.tsx

@@ -0,0 +1,29 @@
+import { render, screen } from '@testing-library/react';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { KpiRow } from './KpiRow';
+
+describe('KpiRow', () => {
+  it('renders the default KPIs as a description list with sparklines', async () => {
+    const { container } = render(<KpiRow />);
+    expect(screen.getByText('Active projects')).toBeInTheDocument();
+    expect(screen.getByText('$18,204')).toBeInTheDocument();
+    expect(screen.getAllByRole('img').length).toBe(4);
+    await expectNoAxeViolations(container);
+  });
+
+  it('colours the delta by sentiment, not direction', () => {
+    render(<KpiRow />);
+    const latency = screen.getByText(/Decreased by −8.1%/).parentElement;
+    expect(latency).toHaveAttribute('data-sentiment', 'positive');
+    const spend = screen.getByText(/Increased by \+4.2%/).parentElement;
+    expect(spend).toHaveAttribute('data-sentiment', 'negative');
+    expect(spend).toHaveClass('text-destructive-text');
+  });
+
+  it('renders the strip variant without notes or trends', async () => {
+    const { container } = render(<KpiRow variant="strip" showTrends={false} />);
+    expect(screen.queryByRole('img')).toBeNull();
+    expect(screen.queryByText('vs. last month')).toBeNull();
+    await expectNoAxeViolations(container);
+  });
+});

package/src/data-display/KpiRow/KpiRow.tsx

@@ -0,0 +1,101 @@
+import { cn, Sparkline, type SparklineTone } from '@gntik-ai/ui';
+import { TrendDelta, type KpiDelta } from '../shared/TrendDelta';
+import { KPI_ITEMS } from './fixtures';
+
+export interface KpiItem {
+  id: string;
+  label: string;
+  /** Pre-formatted value ("38,921", "842 ms"). */
+  value: string;
+  delta?: KpiDelta;
+  /** Optional series for a sparkline under the value, oldest first. */
+  trend?: readonly number[];
+  trendTone?: SparklineTone;
+}
+
+export interface KpiRowProps {
+  /** 3–5 tiles read best; more wrap onto a new row. */
+  items?: readonly KpiItem[];
+  /** `cards` (one card per KPI, default) or `strip` (a single divided card, for page headers). */
+  variant?: 'cards' | 'strip';
+  /** Draw sparklines for items that have a `trend`. */
+  showTrends?: boolean;
+  /** Accessible name of the list. */
+  label?: string;
+  className?: string;
+}
+
+const COLS: Record<number, string> = {
+  1: 'lg:grid-cols-1',
+  2: 'lg:grid-cols-2',
+  3: 'lg:grid-cols-3',
+  4: 'lg:grid-cols-4',
+  5: 'lg:grid-cols-5',
+};
+
+/**
+ * KPI row: label, big number, delta (direction and sentiment are independent) and an optional
+ * Sparkline. A description list, so each label is announced with its value.
+ */
+export function KpiRow({
+  items = KPI_ITEMS,
+  variant = 'cards',
+  showTrends = true,
+  label = 'Key metrics',
+  className,
+}: KpiRowProps) {
+  const strip = variant === 'strip';
+  const cols = COLS[Math.min(items.length, 5)] ?? 'lg:grid-cols-4';
+  return (
+    <dl
+      aria-label={label}
+      className={cn(
+        'grid grid-cols-1 sm:grid-cols-2',
+        cols,
+        strip
+          ? 'divide-y divide-border overflow-hidden rounded-xl border border-border bg-card shadow-sm sm:divide-x lg:divide-y-0'
+          : 'gap-4',
+        className,
+      )}
+    >
+      {items.map((item) => (
+        <div
+          key={item.id}
+          className={cn(
+            'flex min-w-0 flex-col',
+            strip ? 'px-5 py-4' : 'rounded-xl border border-border bg-card p-5 shadow-sm',
+          )}
+        >
+          <dt className={cn('truncate font-medium text-muted-foreground', strip ? 'text-[12px]' : 'text-[13px]')}>
+            {item.label}
+          </dt>
+          <dd className="mt-2 flex flex-wrap items-baseline gap-x-2 gap-y-1">
+            <span
+              className={cn(
+                'font-semibold tracking-tight text-foreground tabular-nums',
+                strip ? 'text-[22px]' : 'text-[26px]',
+              )}
+            >
+              {item.value}
+            </span>
+            {item.delta && <TrendDelta {...item.delta} />}
+          </dd>
+          {item.delta?.note && !strip && <dd className="mt-1 text-[12px] text-muted-foreground">{item.delta.note}</dd>}
+          {showTrends && item.trend && item.trend.length > 1 && (
+            <dd className="mt-3">
+              <Sparkline
+                data={item.trend}
+                label={item.label}
+                area
+                tone={item.trendTone ?? 'primary'}
+                width={240}
+                height={40}
+                className="block h-auto w-full"
+              />
+            </dd>
+          )}
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/data-display/KpiRow/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'KPI row',
+  family: 'data-display',
+  status: 'beta',
+  description:
+    'Three to five stat tiles: label, value, a delta whose arrow and colour are independent, and an optional sparkline. Cards or a divided strip.',
+  uses: ['Sparkline'],
+};

package/src/data-display/KpiRow/fixtures.ts

@@ -0,0 +1,34 @@
+import type { KpiItem } from './KpiRow';
+
+/** Four project KPIs: note latency and spend — same arrow logic, different sentiment. */
+export const KPI_ITEMS: KpiItem[] = [
+  {
+    id: 'projects',
+    label: 'Active projects',
+    value: '142',
+    delta: { value: '+6', direction: 'up', sentiment: 'positive', note: 'vs. 30 days ago' },
+    trend: [128, 130, 131, 133, 134, 137, 139, 142],
+  },
+  {
+    id: 'requests',
+    label: 'Requests · 24h',
+    value: '38,921',
+    delta: { value: '+12.4%', direction: 'up', sentiment: 'positive', note: 'vs. previous 24h' },
+    trend: [31, 34, 33, 38, 36, 41, 39],
+  },
+  {
+    id: 'latency',
+    label: 'Avg latency',
+    value: '842 ms',
+    delta: { value: '−8.1%', direction: 'down', sentiment: 'positive', note: 'vs. previous 24h' },
+    trend: [910, 884, 902, 861, 852, 848, 842],
+  },
+  {
+    id: 'spend',
+    label: 'Spend · month to date',
+    value: '$18,204',
+    delta: { value: '+4.2%', direction: 'up', sentiment: 'negative', note: 'vs. last month' },
+    trend: [12.1, 13.4, 14.2, 15.0, 16.3, 17.1, 18.2],
+    trendTone: 'warning',
+  },
+];

package/src/data-display/ResourceCardGrid/ResourceCardGrid.test.tsx

@@ -0,0 +1,22 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { ResourceCardGrid } from './ResourceCardGrid';
+
+describe('ResourceCardGrid', () => {
+  it('renders one card per resource', async () => {
+    const { container } = render(<ResourceCardGrid />);
+    expect(screen.getByRole('list', { name: 'Resources' })).toBeInTheDocument();
+    expect(screen.getAllByRole('heading', { level: 3 })).toHaveLength(6);
+    expect(screen.getByText('Degraded')).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('runs a menu action for the card', async () => {
+    const onAction = vi.fn();
+    render(<ResourceCardGrid onAction={onAction} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Actions for orders-db' }));
+    await userEvent.click(await screen.findByRole('menuitem', { name: 'Delete' }));
+    expect(onAction).toHaveBeenCalledWith('delete', expect.objectContaining({ id: 'db' }));
+  });
+});

package/src/data-display/ResourceCardGrid/ResourceCardGrid.tsx

@@ -0,0 +1,98 @@
+import { Copy, ExternalLink, Pencil, Trash2, type LucideIcon } from '@gntik-ai/icons';
+import { Avatar, cn, MoreMenu, StatusTag, type MoreMenuAction } from '@gntik-ai/ui';
+import { RESOURCE_CARDS } from './fixtures';
+
+export interface ResourceCard {
+  id: string;
+  name: string;
+  description?: string;
+  /** Icon tile (a lucide icon). Ignored when `avatar` is set. */
+  icon?: LucideIcon;
+  /** Avatar instead of the icon tile (people, teams, organisations). */
+  avatar?: { name: string; src?: string };
+  /** StatusTag state key (running, paused, failed…). */
+  status?: string;
+  /** Two or three small figures at the bottom of the card. */
+  meta?: ReadonlyArray<{ label: string; value: string }>;
+}
+
+export type ResourceAction = 'open' | 'rename' | 'duplicate' | 'delete';
+
+export interface ResourceCardGridProps {
+  items?: readonly ResourceCard[];
+  /** Accessible name of the list. */
+  label?: string;
+  /** Called with the default actions (Open, Rename, Duplicate, Delete). */
+  onAction?: (action: ResourceAction, item: ResourceCard) => void;
+  /** Replaces the default menu entirely. Return an empty array to hide the menu. */
+  getActions?: (item: ResourceCard) => Array<MoreMenuAction | 'separator'>;
+  /** Columns at the widest breakpoint. */
+  columns?: 2 | 3 | 4;
+  /** Heading level of each card's name, to fit the page outline (default h3). */
+  titleAs?: 'h2' | 'h3' | 'h4';
+  className?: string;
+}
+
+const COLS = { 2: 'lg:grid-cols-2', 3: 'lg:grid-cols-3', 4: 'lg:grid-cols-3 xl:grid-cols-4' } as const;
+
+/** Responsive grid of resource cards: icon or avatar, name, status, meta figures and a row-actions MoreMenu. */
+export function ResourceCardGrid({
+  items = RESOURCE_CARDS,
+  label = 'Resources',
+  onAction,
+  getActions,
+  columns = 3,
+  titleAs: TitleTag = 'h3',
+  className,
+}: ResourceCardGridProps) {
+  const defaults = (item: ResourceCard): Array<MoreMenuAction | 'separator'> => [
+    { label: 'Open', icon: ExternalLink, onSelect: () => onAction?.('open', item) },
+    { label: 'Rename', icon: Pencil, onSelect: () => onAction?.('rename', item) },
+    { label: 'Duplicate', icon: Copy, onSelect: () => onAction?.('duplicate', item) },
+    'separator',
+    { label: 'Delete', icon: Trash2, destructive: true, onSelect: () => onAction?.('delete', item) },
+  ];
+  return (
+    <ul aria-label={label} className={cn('grid grid-cols-1 gap-4 sm:grid-cols-2', COLS[columns], className)}>
+      {items.map((item) => {
+        const actions = getActions ? getActions(item) : defaults(item);
+        const IconCmp = item.icon;
+        return (
+          <li key={item.id} className="flex min-w-0 flex-col rounded-xl border border-border bg-card p-5 shadow-sm">
+            <div className="flex items-start justify-between gap-3">
+              {item.avatar ? (
+                <Avatar name={item.avatar.name} src={item.avatar.src} size="md" shape="rounded" />
+              ) : (
+                <span className="inline-flex size-10 shrink-0 items-center justify-center rounded-lg bg-secondary text-muted-foreground">
+                  {IconCmp && <IconCmp size={20} aria-hidden />}
+                </span>
+              )}
+              <div className="flex items-center gap-2">
+                {item.status && <StatusTag status={item.status} />}
+                {actions.length > 0 && (
+                  <MoreMenu items={actions} label={`Actions for ${item.name}`} variant="ghost" size="sm" />
+                )}
+              </div>
+            </div>
+            <div className="mt-4 min-w-0">
+              <TitleTag className="truncate text-[14px] font-semibold text-foreground">{item.name}</TitleTag>
+              {item.description && (
+                <p className="mt-0.5 truncate text-[12.5px] text-muted-foreground">{item.description}</p>
+              )}
+            </div>
+            {item.meta && item.meta.length > 0 && (
+              <dl className="mt-4 grid grid-cols-2 gap-3 border-t border-border pt-4">
+                {item.meta.map((m) => (
+                  <div key={m.label} className="flex min-w-0 flex-col-reverse">
+                    <dt className="truncate text-[11px] text-muted-foreground">{m.label}</dt>
+                    <dd className="truncate font-mono text-[14px] text-foreground tabular-nums">{m.value}</dd>
+                  </div>
+                ))}
+              </dl>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}

package/src/data-display/ResourceCardGrid/block.meta.ts

@@ -0,0 +1,10 @@
+import type { BlockMeta } from '../../meta';
+
+export const meta: BlockMeta = {
+  name: 'Resource card grid',
+  family: 'data-display',
+  status: 'beta',
+  description:
+    'Responsive grid of resource cards with icon or avatar, name, status, meta figures and a row-actions menu.',
+  uses: ['Avatar', 'StatusTag', 'MoreMenu'],
+};

package/src/data-display/ResourceCardGrid/fixtures.ts

@@ -0,0 +1,72 @@
+import { Boxes, Database, Globe, HardDrive, Server, Workflow } from '@gntik-ai/icons';
+import type { ResourceCard } from './ResourceCardGrid';
+
+/** Project resources. */
+export const RESOURCE_CARDS: ResourceCard[] = [
+  {
+    id: 'api',
+    name: 'orders-api',
+    description: 'Public REST API',
+    icon: Server,
+    status: 'running',
+    meta: [
+      { label: 'Requests 30d', value: '1.2M' },
+      { label: 'Cost 30d', value: '$412' },
+    ],
+  },
+  {
+    id: 'db',
+    name: 'orders-db',
+    description: 'Postgres 17 · 3 replicas',
+    icon: Database,
+    status: 'running',
+    meta: [
+      { label: 'Storage', value: '84 GB' },
+      { label: 'Cost 30d', value: '$238' },
+    ],
+  },
+  {
+    id: 'worker',
+    name: 'invoice-worker',
+    description: 'Queue consumer',
+    icon: Workflow,
+    status: 'degraded',
+    meta: [
+      { label: 'Jobs 30d', value: '48,210' },
+      { label: 'Cost 30d', value: '$96' },
+    ],
+  },
+  {
+    id: 'cdn',
+    name: 'static-assets',
+    description: 'Edge cache',
+    icon: Globe,
+    status: 'running',
+    meta: [
+      { label: 'Hit rate', value: '97.4%' },
+      { label: 'Cost 30d', value: '$31' },
+    ],
+  },
+  {
+    id: 'batch',
+    name: 'nightly-export',
+    description: 'Scheduled job',
+    icon: Boxes,
+    status: 'paused',
+    meta: [
+      { label: 'Last run', value: '2 days ago' },
+      { label: 'Cost 30d', value: '$12' },
+    ],
+  },
+  {
+    id: 'bucket',
+    name: 'backups',
+    description: 'Object storage',
+    icon: HardDrive,
+    status: 'failed',
+    meta: [
+      { label: 'Objects', value: '18,422' },
+      { label: 'Cost 30d', value: '$54' },
+    ],
+  },
+];

package/src/data-display/StatCard/StatCard.test.tsx

@@ -0,0 +1,30 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { expectNoAxeViolations } from '../../test/a11y';
+import { StatCard } from './StatCard';
+
+describe('StatCard', () => {
+  it('renders the first range by default', async () => {
+    const { container } = render(<StatCard />);
+    expect(screen.getByRole('heading', { name: 'Requests' })).toBeInTheDocument();
+    expect(screen.getByText('38,921')).toBeInTheDocument();
+    expect(screen.getByRole('img', { name: /Requests, 7d/ })).toBeInTheDocument();
+    await expectNoAxeViolations(container);
+  });
+
+  it('switches range and recalculates the value', async () => {
+    const onRangeChange = vi.fn();
+    render(<StatCard onRangeChange={onRangeChange} />);
+    await userEvent.click(screen.getByRole('button', { name: '90d' }));
+    expect(onRangeChange).toHaveBeenCalledWith('90d');
+    expect(screen.getByText('3.02M')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: '90d' })).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  it('calls the footer action', async () => {
+    const onClick = vi.fn();
+    render(<StatCard action={{ label: 'Open report', onClick }} />);
+    await userEvent.click(screen.getByRole('button', { name: 'Open report' }));
+    expect(onClick).toHaveBeenCalled();
+  });
+});