@stephen-netu/design-system 0.1.0

package/src/d0-data-viz/Timeline.svelte

@@ -0,0 +1,188 @@
+<script lang="ts">
+  import type { TimelineEntry } from './types';
+
+  interface TimelineComponentProps {
+    entries: TimelineEntry[];
+    orientation?: 'horizontal' | 'vertical';
+    'aria-label'?: string;
+  }
+
+  let {
+    entries,
+    orientation = 'vertical',
+    'aria-label': ariaLabel = 'Timeline',
+  }: TimelineComponentProps = $props();
+
+  const DOT_RADIUS = 6;
+  const VERTICAL_SPACING = 80;
+  const HORIZONTAL_SPACING = 160;
+  const PADDING = 24;
+
+  let svgWidth = $derived(
+    orientation === 'horizontal'
+      ? PADDING * 2 + entries.length * HORIZONTAL_SPACING
+      : 320
+  );
+
+  let svgHeight = $derived(
+    orientation === 'vertical'
+      ? PADDING * 2 + entries.length * VERTICAL_SPACING
+      : 120
+  );
+</script>
+
+<svg
+  class="d0-timeline"
+  class:horizontal={orientation === 'horizontal'}
+  viewBox="0 0 {svgWidth} {svgHeight}"
+  xmlns="http://www.w3.org/2000/svg"
+  role="img"
+  aria-label={ariaLabel}
+>
+  <!-- Connecting line -->
+  {#if entries.length > 1}
+    {#if orientation === 'vertical'}
+      <line
+        class="d0-timeline-line"
+        x1={PADDING + DOT_RADIUS}
+        y1={PADDING}
+        x2={PADDING + DOT_RADIUS}
+        y2={PADDING + (entries.length - 1) * VERTICAL_SPACING}
+      />
+    {:else}
+      <line
+        class="d0-timeline-line"
+        x1={PADDING}
+        y1={PADDING + DOT_RADIUS + 20}
+        x2={PADDING + (entries.length - 1) * HORIZONTAL_SPACING}
+        y2={PADDING + DOT_RADIUS + 20}
+      />
+    {/if}
+  {/if}
+
+  <!-- Entries -->
+  {#each entries as entry, i (entry.id)}
+    {#if orientation === 'vertical'}
+      {@const cy = PADDING + i * VERTICAL_SPACING}
+      {@const cx = PADDING + DOT_RADIUS}
+
+      <!-- Dot -->
+      <circle
+        class="d0-timeline-dot"
+        cx={cx}
+        cy={cy}
+        r={DOT_RADIUS}
+        fill={entry.color ?? undefined}
+      >
+        <title>{entry.timestamp}</title>
+      </circle>
+
+      <!-- Label -->
+      <text
+        class="d0-timeline-label"
+        x={cx + DOT_RADIUS + 12}
+        y={cy - 4}
+        dominant-baseline="auto"
+      >
+        {entry.label}
+      </text>
+
+      <!-- Timestamp -->
+      <text
+        class="d0-timeline-timestamp"
+        x={cx + DOT_RADIUS + 12}
+        y={cy + 14}
+        dominant-baseline="auto"
+      >
+        {entry.timestamp}
+      </text>
+
+      <!-- Description -->
+      {#if entry.description}
+        <text
+          class="d0-timeline-desc"
+          x={cx + DOT_RADIUS + 12}
+          y={cy + 30}
+          dominant-baseline="auto"
+        >
+          {entry.description}
+        </text>
+      {/if}
+    {:else}
+      {@const cx = PADDING + i * HORIZONTAL_SPACING}
+      {@const cy = PADDING + DOT_RADIUS + 20}
+
+      <!-- Dot -->
+      <circle
+        class="d0-timeline-dot"
+        cx={cx}
+        cy={cy}
+        r={DOT_RADIUS}
+        fill={entry.color ?? undefined}
+      >
+        <title>{entry.timestamp}</title>
+      </circle>
+
+      <!-- Label (above line) -->
+      <text
+        class="d0-timeline-label"
+        x={cx}
+        y={cy - DOT_RADIUS - 8}
+        text-anchor="middle"
+      >
+        {entry.label}
+      </text>
+
+      <!-- Timestamp (below line) -->
+      <text
+        class="d0-timeline-timestamp"
+        x={cx}
+        y={cy + DOT_RADIUS + 18}
+        text-anchor="middle"
+      >
+        {entry.timestamp}
+      </text>
+    {/if}
+  {/each}
+</svg>
+
+<style>
+  .d0-timeline {
+    display: block;
+    width: 100%;
+    height: auto;
+  }
+
+  .d0-timeline-line {
+    stroke: var(--d0-timeline-line, rgba(184, 115, 51, 0.3));
+    stroke-width: 2;
+  }
+
+  .d0-timeline-dot {
+    fill: var(--d0-timeline-dot, #b87333);
+    transition: r 150ms ease;
+  }
+
+  .d0-timeline-dot:hover {
+    r: 8;
+  }
+
+  .d0-timeline-label {
+    fill: var(--color-text-primary, #e8e0d0);
+    font-family: var(--font-sans, system-ui, sans-serif);
+    font-size: 13px;
+    font-weight: 500;
+  }
+
+  .d0-timeline-timestamp {
+    fill: var(--d0-chart-text, #a09880);
+    font-family: var(--font-sans, system-ui, sans-serif);
+    font-size: 10px;
+  }
+
+  .d0-timeline-desc {
+    fill: var(--d0-chart-text, #a09880);
+    font-family: var(--font-sans, system-ui, sans-serif);
+    font-size: 11px;
+  }
+</style>

package/src/d0-data-viz/checkpoint-types.ts

@@ -0,0 +1,162 @@
+// D0 Data Viz — Checkpoint Timeline Types
+// Pure TypeScript — no Svelte, no DOM dependencies
+// ADR: ui-timeline-checkpoint-bar-001
+
+// === Checkpoint Types ===
+
+/** Component types for color coding per ADR spec */
+export type CheckpointComponentType =
+  | 'rust-crate'
+  | 'ui-bundle'
+  | 'config'
+  | 'faculty-state'
+  | 'substrate-binary'
+  | 'system-snapshot';
+
+/** Checkpoint status visual encoding */
+export type CheckpointStatus = 'committed' | 'system' | 'proposed' | 'partial';
+
+/** A single checkpoint entry on the timeline */
+export interface Checkpoint {
+  /** Unique sequence number (seqno per sigchain) */
+  seqno: number;
+  /** Human-readable identifier */
+  id: string;
+  /** Component name (e.g., "ryu-hamiltonian-panel") */
+  component: string;
+  /** Component type for color coding */
+  componentType: CheckpointComponentType;
+  /** Checkpoint status for visual encoding */
+  status: CheckpointStatus;
+  /** Version transition (optional) */
+  version?: {
+    from: string;
+    to: string;
+  };
+  /** Author identifier */
+  author?: string;
+  /** Associated task ID */
+  taskId?: string;
+  /** Human description */
+  description: string;
+  /** Timestamp as sequence number reference */
+  timestamp: number;
+}
+
+/** Color mapping — references CSS custom properties set by themeStore */
+export const CHECKPOINT_COLORS: Record<CheckpointComponentType, string> = {
+  'rust-crate': 'var(--d0-checkpoint-rust)',
+  'ui-bundle': 'var(--d0-checkpoint-ui)',
+  'config': 'var(--d0-checkpoint-config)',
+  'faculty-state': 'var(--d0-checkpoint-faculty)',
+  'substrate-binary': 'var(--d0-checkpoint-substrate)',
+  'system-snapshot': 'var(--d0-checkpoint-aggregate)',
+};
+
+/** Get checkpoint color with fallback for when CSS vars aren't set */
+export function getCheckpointColor(type: CheckpointComponentType, isDark = true): string {
+  const fallbacks: Record<CheckpointComponentType, { light: string; dark: string }> = {
+    'rust-crate': { light: '#8a5a28', dark: '#b87333' },
+    'ui-bundle': { light: '#2d6b6e', dark: '#5f9ea0' },
+    'config': { light: '#7c6fae', dark: '#a99fd6' },
+    'faculty-state': { light: '#d4a03d', dark: '#e6c470' },
+    'substrate-binary': { light: '#c75a5a', dark: '#d98a8a' },
+    'system-snapshot': { light: '#6b7280', dark: '#9ca3af' },
+  };
+  return fallbacks[type][isDark ? 'dark' : 'light'];
+}
+
+/** Visual encoding for checkpoint status */
+export const CHECKPOINT_STATUS_SYMBOLS: Record<CheckpointStatus, string> = {
+  'committed': '◉',    // Filled circle
+  'system': '◎',       // Double-ring circle
+  'proposed': '○',     // Hollow circle
+  'partial': '◐',      // Half-filled
+};
+
+// === Checkpoint Bar Props ===
+
+export interface CheckpointBarProps {
+  checkpoints: Checkpoint[];
+  currentSeqno: number;
+  previewSeqno?: number | null;
+  onCheckpointClick?: (checkpoint: Checkpoint) => void;
+  onCheckpointDoubleClick?: (checkpoint: Checkpoint) => void;
+  /** Callback when "Now" handle is dragged (seqno target) */
+  onNowHandleDrag?: (seqno: number) => void;
+  /** Callback when exiting preview mode */
+  onExitPreview?: () => void;
+  'aria-label'?: string;
+}
+
+// === Preview Mode ===
+
+export interface PreviewState {
+  seqno: number;
+  checkpoint: Checkpoint;
+  isReadOnly: boolean;
+}
+
+export interface RollbackConfirmation {
+  targetSeqno: number;
+  targetCheckpoint: Checkpoint;
+  currentSeqno: number;
+  affectedComponents: string[];
+  archivedConversations: number;
+}
+
+// === Keyboard Navigation ===
+
+export interface KeyboardNavigationState {
+  focusedIndex: number;
+  isPreviewMode: boolean;
+}
+
+/** Keyboard action mapping per ADR accessibility spec */
+export const CHECKPOINT_KEYBOARD_ACTIONS = {
+  ArrowLeft: 'navigate-prev',
+  ArrowRight: 'navigate-next',
+  Enter: 'preview',
+  'Shift+Enter': 'rollback',
+  Escape: 'exit-preview',
+  Home: 'jump-genesis',
+  End: 'jump-now',
+} as const;
+
+export type CheckpointKeyboardAction =
+  typeof CHECKPOINT_KEYBOARD_ACTIONS[keyof typeof CHECKPOINT_KEYBOARD_ACTIONS];
+
+// === Store Interface (Framework Agnostic) ===
+
+export interface TimelineStoreState {
+  checkpoints: Checkpoint[];
+  currentSeqno: number;
+  previewSeqno: number | null;
+  isScrubbing: boolean;
+  visibleRange: { start: number; end: number };
+}
+
+export interface TimelineStoreActions {
+  scrubTo(seqno: number): Promise<void>;
+  exitPreview(): void;
+  rollbackTo(seqno: number): Promise<RollbackResult>;
+  navigateToCheckpoint(index: number): void;
+}
+
+export interface RollbackResult {
+  success: boolean;
+  newSeqno?: number;
+  error?: string;
+}
+
+// === Lazy Loading Constants ===
+
+/** Number of checkpoints to keep in memory (per ADR performance spec) */
+export const VISIBLE_CHECKPOINTS = 50;
+
+/** Checkpoint bar height in pixels (ADR spec: 48px) */
+export const CHECKPOINT_BAR_HEIGHT = 48;
+
+/** Node sizes for visual encoding */
+export const CHECKPOINT_NODE_SIZE = 12;
+export const CHECKPOINT_NODE_ACTIVE_SIZE = 16;

package/src/d0-data-viz/d0-tokens.css

@@ -0,0 +1,32 @@
+/* D0 Data Viz — CSS Design Tokens */
+:root {
+  /* Chart */
+  --d0-chart-bg: var(--color-bg-panel, #222);
+  --d0-chart-grid: rgba(184, 115, 51, 0.1);
+  --d0-chart-text: var(--color-text-muted, #a09880);
+  --d0-chart-accent: var(--color-accent, #b87333);
+
+  /* Metric */
+  --d0-metric-trend-up: var(--color-success, #27ae60);
+  --d0-metric-trend-down: var(--color-error, #c0392b);
+
+  /* Timeline */
+  --d0-timeline-line: rgba(184, 115, 51, 0.3);
+  --d0-timeline-dot: var(--color-accent, #b87333);
+
+  /* CheckpointBar (ADR: ui-timeline-checkpoint-bar-001) */
+  --d0-checkpoint-bar-height: 48px;
+  --d0-checkpoint-node-size: 12px;
+  --d0-checkpoint-node-active-size: 16px;
+  --d0-checkpoint-line-color: rgba(184, 115, 51, 0.3);
+  --d0-checkpoint-tooltip-bg: rgba(34, 34, 34, 0.98);
+  --d0-checkpoint-tooltip-border: rgba(184, 115, 51, 0.3);
+
+  /* Checkpoint Colors by Component Type */
+  --d0-checkpoint-brass: #b87333;
+  --d0-checkpoint-teal: #5f9ea0;
+  --d0-checkpoint-gold: #daa520;
+  --d0-checkpoint-purple: #9370db;
+  --d0-checkpoint-red: #cd5c5c;
+  --d0-checkpoint-gray: #2f4f4f;
+}

package/src/d0-data-viz/index.ts

@@ -0,0 +1,58 @@
+// D0 Data Viz — Barrel Export
+
+// Types
+export type {
+  DataPoint,
+  DataSeries,
+  ChartProps,
+  MetricCardProps,
+  TimelineEntry,
+  TimelineProps,
+} from './types';
+
+// Checkpoint Types (ADR: ui-timeline-checkpoint-bar-001)
+export type {
+  Checkpoint,
+  CheckpointComponentType,
+  CheckpointStatus,
+  CheckpointBarProps,
+  PreviewState,
+  RollbackConfirmation,
+  RollbackResult,
+  TimelineStoreState,
+  TimelineStoreActions,
+  KeyboardNavigationState,
+  CheckpointKeyboardAction,
+} from './checkpoint-types';
+export {
+  CHECKPOINT_COLORS,
+  CHECKPOINT_STATUS_SYMBOLS,
+  CHECKPOINT_KEYBOARD_ACTIONS,
+  VISIBLE_CHECKPOINTS,
+  CHECKPOINT_BAR_HEIGHT,
+  CHECKPOINT_NODE_SIZE,
+  CHECKPOINT_NODE_ACTIVE_SIZE,
+  getCheckpointColor,
+} from './checkpoint-types';
+
+// StorageMap (wt:sovra-1115)
+export type { StorageNode, StorageMapConfig, TreemapCell, TreemapLayout, OwnerTier } from './storage-map-types';
+export { computeTreemap, formatBytes, TIER_COLORS } from './storage-map-types';
+
+// Components
+export { default as BarChart } from './BarChart.svelte';
+export { default as SparkLine } from './SparkLine.svelte';
+export { default as MetricCard } from './MetricCard.svelte';
+export { default as Timeline } from './Timeline.svelte';
+export { default as StorageMap } from './StorageMap.svelte';
+export { default as CheckpointBar } from './CheckpointBar.svelte';
+export { default as CheckpointPill } from './CheckpointPill.svelte';
+
+// Theme Integration
+export {
+  CHECKPOINT_CSS_VARS,
+  CHECKPOINT_COLOR_LABELS,
+  CHECKPOINT_DEFAULT_COLORS,
+  getEffectiveCheckpointColor,
+  THEME_INTEGRATION,
+} from './theme-integration';

package/src/d0-data-viz/storage-map-types.ts

@@ -0,0 +1,142 @@
+// StorageMap — BSP treemap types (wt:sovra-1115)
+// S-02: No HashMap/HashSet — use sorted arrays for lookups.
+// Pure TypeScript — no Svelte, no DOM.
+
+/** Ownership tier for a storage node */
+export type OwnerTier = 'kos' | 'external' | 'unknown';
+
+/** A single storage node in the treemap */
+export interface StorageNode {
+  path: string;
+  bytes: number;
+  ownerTier: OwnerTier;
+  label?: string;
+  children?: StorageNode[];
+}
+
+/** A flattened treemap cell ready for rendering */
+export interface TreemapCell {
+  path: string;
+  label: string;
+  bytes: number;
+  ownerTier: OwnerTier;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Layout result from the squarified treemap algorithm */
+export interface TreemapLayout {
+  cells: TreemapCell[];
+  totalBytes: number;
+}
+
+/** StorageMap component configuration */
+export interface StorageMapConfig {
+  /** Minimum cell dimension in px. Default 32. */
+  minCellSize?: number;
+  /** Gap between cells in px. Default 2. */
+  gap?: number;
+  /** Show path labels inside cells. Default true. */
+  showLabels?: boolean;
+}
+
+/** Color palette per owner tier */
+export const TIER_COLORS: Record<OwnerTier, { fill: string; stroke: string; text: string }> = {
+  kos: {
+    fill: 'rgba(184, 115, 51, 0.25)',
+    stroke: 'rgba(184, 115, 51, 0.6)',
+    text: '#d4a06a',
+  },
+  external: {
+    fill: 'rgba(160, 152, 128, 0.15)',
+    stroke: 'rgba(160, 152, 128, 0.4)',
+    text: '#a09880',
+  },
+  unknown: {
+    fill: 'rgba(90, 82, 69, 0.15)',
+    stroke: 'rgba(90, 82, 69, 0.3)',
+    text: '#706858',
+  },
+};
+
+// ── Squarified treemap layout ──────────────────────────────────────────────
+
+/**
+ * Compute a squarified treemap layout for flat node lists.
+ * S-02: deterministic — sorted by bytes descending, no randomness.
+ * S-05: bounded — iterates finite node array.
+ */
+export function computeTreemap(
+  nodes: StorageNode[],
+  width: number,
+  height: number,
+  config: StorageMapConfig = {}
+): TreemapLayout {
+  const gap = config.gap ?? 2;
+  const minCell = config.minCellSize ?? 32;
+
+  // Sort descending by size (deterministic, S-02)
+  const sorted = [...nodes].sort((a, b) => b.bytes - a.bytes);
+  const totalBytes = sorted.reduce((sum, n) => sum + n.bytes, 0);
+
+  if (totalBytes === 0 || sorted.length === 0) {
+    return { cells: [], totalBytes: 0 };
+  }
+
+  const cells: TreemapCell[] = [];
+  const aspectRatio = width / height;
+
+  // Simple slice-and-dice treemap (row-based for readability)
+  const usableWidth = width - gap * 2;
+  const usableHeight = height - gap * 2;
+
+  let x = gap;
+  let y = gap;
+  let rowHeight = usableHeight;
+
+  // Group into rows based on aspect ratio
+  const rowTarget = Math.max(1, Math.round(Math.sqrt(sorted.length / aspectRatio)));
+
+  for (let i = 0; i < sorted.length; i += rowTarget) {
+    const row = sorted.slice(i, i + rowTarget);
+    const rowBytes = row.reduce((sum, n) => sum + n.bytes, 0);
+
+    // Row height proportional to row's share of total
+    const actualRowHeight = Math.max(minCell, (rowBytes / totalBytes) * usableHeight);
+
+    let cellX = x;
+    for (const node of row) {
+      const cellWidth = Math.max(minCell, (node.bytes / rowBytes) * usableWidth);
+      const label = node.label ?? node.path.split('/').pop() ?? node.path;
+
+      cells.push({
+        path: node.path,
+        label,
+        bytes: node.bytes,
+        ownerTier: node.ownerTier,
+        x: cellX,
+        y,
+        width: cellWidth - gap,
+        height: actualRowHeight - gap,
+      });
+
+      cellX += cellWidth;
+    }
+
+    y += actualRowHeight;
+  }
+
+  return { cells, totalBytes };
+}
+
+/** Format bytes to human-readable string */
+export function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log2(bytes) / 10);
+  const clamped = Math.min(i, units.length - 1);
+  const value = bytes / Math.pow(1024, clamped);
+  return `${value.toFixed(clamped === 0 ? 0 : 1)} ${units[clamped]}`;
+}