@grackle-ai/web-components 0.107.2

package/src/test-utils/storybook-decorators.tsx

@@ -0,0 +1,50 @@
+/**
+ * Storybook decorators for page-level components that call useGrackle().
+ */
+
+import type { Decorator } from "@storybook/react";
+import { MemoryRouter, Routes, Route } from "react-router";
+import { MockGrackleProvider } from "../mocks/MockGrackleProvider.js";
+import { SidebarProvider } from "../context/SidebarContext.js";
+
+/**
+ * Decorator for stories that test page-level components which call useGrackle().
+ * Apply via `decorators: [withMockGrackle]` in the story meta.
+ */
+export const withMockGrackle: Decorator = (Story) => (
+  <MockGrackleProvider>
+    <SidebarProvider>
+      <Story />
+    </SidebarProvider>
+  </MockGrackleProvider>
+);
+
+/**
+ * Creates a decorator that wraps the story in MockGrackleProvider + MemoryRouter
+ * with the given initial route entries and a catch-all Route for useParams().
+ *
+ * Use with `parameters: { skipRouter: true }` in the story meta to prevent
+ * the global preview.tsx from adding a second MemoryRouter.
+ *
+ * @example
+ * ```tsx
+ * const meta = {
+ *   component: TaskPage,
+ *   decorators: [withMockGrackleRoute(["/tasks/task-001"], "/tasks/:taskId")],
+ *   parameters: { skipRouter: true },
+ * };
+ * ```
+ */
+export function withMockGrackleRoute(initialEntries: string[], routePath: string = "*"): Decorator {
+  return (Story) => (
+    <MockGrackleProvider>
+      <MemoryRouter initialEntries={initialEntries}>
+        <SidebarProvider>
+          <Routes>
+            <Route path={routePath} element={<Story />} />
+          </Routes>
+        </SidebarProvider>
+      </MemoryRouter>
+    </MockGrackleProvider>
+  );
+}

package/src/test-utils/storybook-helpers.ts

@@ -0,0 +1,262 @@
+/**
+ * Mock data builders and helpers for Storybook stories.
+ *
+ * Provides factory functions that create realistic test data with
+ * sensible defaults and optional overrides.
+ */
+
+import type {
+  Environment,
+  Session,
+  SessionEvent,
+  Workspace,
+  TaskData,
+  FindingData,
+  TokenInfo,
+  PersonaData,
+  ScheduleData,
+  CredentialProviderConfig,
+  Codespace,
+} from "../hooks/types.js";
+import type { GraphNode, GraphLink } from "../hooks/types.js";
+
+export {
+  MOCK_ENVIRONMENTS,
+  MOCK_SESSIONS,
+  MOCK_WORKSPACES,
+  MOCK_TASKS,
+  MOCK_FINDINGS,
+  MOCK_TOKENS,
+  MOCK_PERSONAS,
+} from "../mocks/mockData.js";
+
+// ─── Factory functions ──────────────────────────────────────────────────────
+
+let idCounter: number = 0;
+
+/** Generate a unique ID for test entities. */
+function nextId(prefix: string): string {
+  return `${prefix}-${++idCounter}`;
+}
+
+/** Create an Environment with sensible defaults. */
+export function makeEnvironment(overrides: Partial<Environment> = {}): Environment {
+  return {
+    id: nextId("env"),
+    displayName: "Test Env",
+    adapterType: "local",
+    adapterConfig: "{}",
+    status: "connected",
+    bootstrapped: true,
+    ...overrides,
+  };
+}
+
+/** Create a Session with sensible defaults. */
+export function makeSession(overrides: Partial<Session> = {}): Session {
+  return {
+    id: nextId("sess"),
+    environmentId: "env-1",
+    runtime: "claude-code",
+    status: "idle",
+    prompt: "Test prompt",
+    startedAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+/** Create a Workspace with sensible defaults. */
+export function makeWorkspace(overrides: Partial<Workspace> = {}): Workspace {
+  return {
+    id: nextId("ws"),
+    name: "Test Workspace",
+    description: "",
+    repoUrl: "",
+    linkedEnvironmentIds: ["env-1"],
+    status: "active",
+    workingDirectory: "",
+    useWorktrees: false,
+    defaultPersonaId: "",
+    tokenBudget: 0,
+    costBudgetMillicents: 0,
+    createdAt: "2026-01-01T00:00:00Z",
+    updatedAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+/** Create a TaskData with sensible defaults. */
+export function makeTask(overrides: Partial<TaskData> = {}): TaskData {
+  return {
+    id: nextId("task"),
+    workspaceId: "ws-1",
+    title: "Test Task",
+    description: "",
+    status: "not_started",
+    branch: "main",
+    latestSessionId: "",
+    dependsOn: [],
+    sortOrder: 0,
+    createdAt: "2026-01-01T00:00:00Z",
+    parentTaskId: "",
+    depth: 0,
+    childTaskIds: [],
+    canDecompose: false,
+    defaultPersonaId: "",
+    workpad: "",
+    tokenBudget: 0,
+    costBudgetMillicents: 0,
+    ...overrides,
+  };
+}
+
+/** Create a FindingData with sensible defaults. */
+export function makeFinding(overrides: Partial<FindingData> = {}): FindingData {
+  return {
+    id: nextId("finding"),
+    workspaceId: "ws-1",
+    taskId: "task-1",
+    sessionId: "sess-1",
+    category: "general",
+    title: "Test Finding",
+    content: "Finding content",
+    tags: [],
+    createdAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+/** Create a TokenInfo with sensible defaults. */
+export function makeToken(overrides: Partial<TokenInfo> = {}): TokenInfo {
+  return {
+    name: "TEST_TOKEN",
+    tokenType: "env_var",
+    envVar: "TEST_TOKEN",
+    filePath: "",
+    expiresAt: "",
+    ...overrides,
+  };
+}
+
+/** Create a PersonaData with sensible defaults. */
+export function makePersona(overrides: Partial<PersonaData> = {}): PersonaData {
+  return {
+    id: nextId("persona"),
+    name: "Test Persona",
+    description: "A test persona",
+    systemPrompt: "You are a test agent.",
+    toolConfig: "",
+    runtime: "claude-code",
+    model: "sonnet",
+    maxTurns: 0,
+    mcpServers: "",
+    createdAt: "2026-01-01T00:00:00Z",
+    updatedAt: "2026-01-01T00:00:00Z",
+    type: "agent",
+    script: "",
+    allowedMcpTools: [],
+    ...overrides,
+  };
+}
+
+/** Create a ScheduleData with sensible defaults. */
+export function makeSchedule(overrides: Partial<ScheduleData> = {}): ScheduleData {
+  return {
+    id: nextId("schedule"),
+    title: "Test Schedule",
+    description: "A test schedule",
+    scheduleExpression: "5m",
+    personaId: "persona-1",
+    workspaceId: "",
+    parentTaskId: "",
+    enabled: true,
+    lastRunAt: "",
+    nextRunAt: new Date(Date.now() + 5 * 60_000).toISOString(),
+    runCount: 0,
+    createdAt: "2026-01-01T00:00:00Z",
+    updatedAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+/** Create a SessionEvent with sensible defaults. */
+export function makeEvent(overrides: Partial<SessionEvent> = {}): SessionEvent {
+  return {
+    sessionId: "sess-1",
+    eventType: "text",
+    timestamp: "2026-01-01T00:00:00Z",
+    content: "Test event content",
+    ...overrides,
+  };
+}
+
+/** Create a Codespace with sensible defaults. */
+export function makeCodespace(overrides: Partial<Codespace> = {}): Codespace {
+  return {
+    name: "test-codespace",
+    repository: "owner/repo",
+    state: "Available",
+    gitStatus: "clean",
+    ...overrides,
+  };
+}
+
+/** Default credential provider config (all off). */
+export function makeCredentialProviders(overrides: Partial<CredentialProviderConfig> = {}): CredentialProviderConfig {
+  return {
+    claude: "off",
+    github: "off",
+    copilot: "off",
+    codex: "off",
+    goose: "off",
+    ...overrides,
+  };
+}
+
+/** Create a GraphNode with sensible defaults. */
+export function makeGraphNode(overrides: Partial<GraphNode> = {}): GraphNode {
+  return {
+    id: nextId("kn"),
+    label: "Test Knowledge Node",
+    kind: "knowledge",
+    category: "concept",
+    content: "Test node content.",
+    tags: [],
+    createdAt: "2026-01-15T10:00:00Z",
+    updatedAt: "2026-02-20T14:30:00Z",
+    val: 1,
+    ...overrides,
+  };
+}
+
+/** Create a GraphLink with sensible defaults. */
+export function makeGraphLink(overrides: Partial<GraphLink> = {}): GraphLink {
+  return {
+    source: "kn-1",
+    target: "kn-2",
+    type: "relates_to",
+    ...overrides,
+  };
+}
+
+/** No-op callback for story args. */
+export const noop = (): void => {};
+
+// ─── Storybook decorators ───────────────────────────────────────────────────
+
+export { withMockGrackle, withMockGrackleRoute } from "./storybook-decorators.js";
+
+// ─── Aliases (some stories use "build" prefix) ──────────────────────────────
+
+export const buildEnvironment: typeof makeEnvironment = makeEnvironment;
+export const buildSession: typeof makeSession = makeSession;
+export const buildWorkspace: typeof makeWorkspace = makeWorkspace;
+export const buildTask: typeof makeTask = makeTask;
+export const buildFinding: typeof makeFinding = makeFinding;
+export const buildToken: typeof makeToken = makeToken;
+export const buildPersona: typeof makePersona = makePersona;
+export const buildEvent: typeof makeEvent = makeEvent;
+export const buildCodespace: typeof makeCodespace = makeCodespace;
+export const buildCredentialProviderConfig: typeof makeCredentialProviders = makeCredentialProviders;
+export const buildGraphNode: typeof makeGraphNode = makeGraphNode;
+export const buildGraphLink: typeof makeGraphLink = makeGraphLink;

package/src/themes.ts

@@ -0,0 +1,142 @@
+// ============================================================================
+// Theme Registry — Grackle Web UI
+// ============================================================================
+// Central registry of available themes. To add a new theme:
+//   1. Add a ThemeDefinition entry to THEMES below
+//   2. Add a matching [data-theme="<id>"] block in theme.scss
+//   3. That's it — the Settings UI, useTheme hook, and persistence all
+//      pick up new entries automatically.
+// ============================================================================
+
+/** Describes a single UI theme. */
+export interface ThemeDefinition {
+  /** Unique identifier — must match the data-theme attribute value in theme.scss. */
+  id: string;
+  /** Display name shown in Settings. */
+  label: string;
+  /** Short description shown in Settings. */
+  description: string;
+  /** Preview colors shown as swatches in Settings (bg, accent, text). */
+  swatches?: string[];
+  /** If set, this theme has a light variant toggled in Settings. */
+  variantLightId?: string;
+  /** If set, this theme has a dark variant toggled in Settings. */
+  variantDarkId?: string;
+  /** If true, this entry is a variant and should not be rendered as a standalone card. */
+  hidden?: boolean;
+}
+
+/**
+ * All available themes.  Order determines display order in Settings.
+ * Themes with `hidden: true` are valid IDs but rendered as part of
+ * their parent's light/dark toggle rather than as separate cards.
+ */
+export const THEMES: readonly ThemeDefinition[] = [
+  {
+    id: "grackle",
+    label: "Grackle",
+    description: "The default Grackle theme — iridescent purple on clean dark.",
+    swatches: ["#0e1218", "#8b5cf6", "#60a5fa", "#e5e7eb", "#34d399"],
+    variantLightId: "grackle-light",
+    variantDarkId: "grackle-dark",
+  },
+  {
+    id: "grackle-light",
+    label: "Grackle Light",
+    description: "Light Grackle variant.",
+    hidden: true,
+  },
+  {
+    id: "grackle-dark",
+    label: "Grackle Dark",
+    description: "Dark Grackle variant.",
+    hidden: true,
+  },
+  {
+    id: "glass",
+    label: "Glassmorphism",
+    description: "Dark frosted-glass aesthetic with backdrop blur effects.",
+    swatches: ["#0a0c14", "#4ecca3", "#70a1ff", "#e2e8f0", "#a855f7"],
+  },
+  {
+    id: "matrix",
+    label: "Matrix",
+    description: "Phosphor-green CRT terminal with scanlines and glow.",
+    swatches: ["#050505", "#00ff41", "#00bfff", "#33ff77", "#ffb000"],
+  },
+  {
+    id: "brutalist",
+    label: "Neubrutalism",
+    description: "Thick borders, raw colors, bold type — ugly on purpose.",
+    swatches: ["#f5f0e8", "#ff5757", "#5ce1e6", "#1a1a1a", "#ffde59"],
+    variantLightId: "brutalist-light",
+    variantDarkId: "brutalist-dark",
+  },
+  {
+    id: "brutalist-light",
+    label: "Neubrutalism Light",
+    description: "Light neubrutalism variant.",
+    hidden: true,
+  },
+  {
+    id: "brutalist-dark",
+    label: "Neubrutalism Dark",
+    description: "Dark neubrutalism variant.",
+    hidden: true,
+  },
+  {
+    id: "monokai",
+    label: "Monokai",
+    description: "Classic warm editor palette — pink, green, and purple.",
+    swatches: ["#272822", "#f92672", "#a6e22e", "#f8f8f2", "#ae81ff"],
+    variantLightId: "monokai-light",
+    variantDarkId: "monokai-dark",
+  },
+  {
+    id: "monokai-dark",
+    label: "Monokai Dark",
+    description: "Dark Monokai variant.",
+    hidden: true,
+  },
+  {
+    id: "monokai-light",
+    label: "Monokai Light",
+    description: "Light Monokai variant.",
+    hidden: true,
+  },
+  {
+    id: "ubuntu",
+    label: "Ubuntu",
+    description: "Aubergine terminal with the GNOME Tango palette.",
+    swatches: ["#300a24", "#8ae234", "#ef2929", "#eeeeec", "#fce94f"],
+  },
+  {
+    id: "sandstone",
+    label: "Sandstone",
+    description: "Warm terracotta accent on dark brown, in the style of Claude Code.",
+    swatches: ["#1a1815", "#C15F3C", "#6b8afd", "#e8e6e3", "#a78bfa"],
+  },
+  {
+    id: "verdigris",
+    label: "Verdigris",
+    description: "Teal accent on charcoal, in the style of ChatGPT.",
+    swatches: ["#141414", "#00a67e", "#3b82f6", "#ececec", "#ab68ff"],
+  },
+  {
+    id: "primer",
+    label: "Primer",
+    description: "Blue accent on ink-dark grey, in the style of GitHub.",
+    swatches: ["#0d1117", "#58a6ff", "#3fb950", "#c9d1d9", "#bc8cff"],
+  },
+] as const;
+
+/** The set of valid theme IDs derived from the registry. */
+export const THEME_IDS: ReadonlySet<string> = new Set(THEMES.map((t) => t.id));
+
+/** The default theme ID used when nothing is persisted. */
+export const DEFAULT_THEME_ID: string = "grackle";
+
+/** Look up a theme definition by ID, returning undefined if not found. */
+export function getThemeById(id: string): ThemeDefinition | undefined {
+  return THEMES.find((t) => t.id === id);
+}

package/src/utils/boardColumns.ts

@@ -0,0 +1,141 @@
+/**
+ * Pure helpers for bucketing tasks into Kanban board columns.
+ *
+ * Unlike the sidebar `groupTasksByStatus()` (which adds a virtual "blocked"
+ * group), the board keeps blocked tasks in their actual-status column and
+ * overlays a badge.
+ */
+
+import type { TaskData } from "../hooks/types.js";
+import { BOARD_COLUMN_ORDER, getStatusStyle, resolveStatus, type TaskStatusKey, type TaskStatusStyle } from "./taskStatus.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Represents a single column on the Kanban board. */
+export interface BoardColumn {
+  /** Canonical status key (e.g. "working"). */
+  status: TaskStatusKey;
+  /** Human-readable column heading. */
+  label: string;
+  /** Visual style for the column header. */
+  style: TaskStatusStyle;
+  /** Tasks in this column, sorted by `sortOrder`. */
+  tasks: BoardTask[];
+}
+
+/** A task decorated with board-specific computed properties. */
+export interface BoardTask {
+  /** Original task data. */
+  task: TaskData;
+  /** True when the task has unresolved dependencies. */
+  isBlocked: boolean;
+  /** Number of direct child tasks. */
+  childCount: number;
+  /** Number of direct child tasks that are complete. */
+  doneChildCount: number;
+  /** Paused sub-badge label derived from latest session status. */
+  pausedSubBadge?: "Needs input" | "Ready to complete";
+}
+
+// ---------------------------------------------------------------------------
+// Bucketing
+// ---------------------------------------------------------------------------
+
+/** Options for building board columns. */
+interface BuildColumnsOptions {
+  /** Flat list of tasks belonging to one workspace. */
+  tasks: TaskData[];
+  /** Map of taskId → status for all tasks (used for dependency checking). */
+  taskStatusById: Map<string, string>;
+  /** Map of taskId → latest session status (used for paused sub-badges). */
+  sessionStatusByTaskId?: Map<string, string>;
+}
+
+/**
+ * Bucket tasks into fixed board columns.
+ *
+ * - Always returns all five columns (empty ones get an empty `tasks` array).
+ * - Resolves legacy status aliases to canonical keys.
+ * - Sorts tasks within each column by `sortOrder`.
+ * - Computes blocked state and child-progress counts.
+ * - Derives paused sub-badges from the latest session status.
+ */
+export function buildBoardColumns({
+  tasks,
+  taskStatusById,
+  sessionStatusByTaskId,
+}: BuildColumnsOptions): BoardColumn[] {
+  // Index children by parent
+  const childrenByParent = new Map<string, TaskData[]>();
+  for (const t of tasks) {
+    if (t.parentTaskId) {
+      const list = childrenByParent.get(t.parentTaskId);
+      if (list) {
+        list.push(t);
+      } else {
+        childrenByParent.set(t.parentTaskId, [t]);
+      }
+    }
+  }
+
+  // Pre-build empty buckets keyed by status
+  const buckets = new Map<TaskStatusKey, BoardTask[]>(
+    BOARD_COLUMN_ORDER.map((s) => [s, []]),
+  );
+
+  for (const task of tasks) {
+    const column = resolveStatus(task.status);
+    const isBlocked =
+      task.dependsOn.length > 0 &&
+      task.dependsOn.some((depId) => taskStatusById.get(depId) !== "complete");
+
+    const children = childrenByParent.get(task.id) ?? [];
+    const childCount = children.length;
+    const doneChildCount = children.filter((c) => c.status === "complete").length;
+
+    let pausedSubBadge: BoardTask["pausedSubBadge"];
+    if (column === "paused" && sessionStatusByTaskId) {
+      const sessionStatus = sessionStatusByTaskId.get(task.id);
+      if (sessionStatus === "idle") {
+        pausedSubBadge = "Needs input";
+      } else if (sessionStatus === "completed") {
+        pausedSubBadge = "Ready to complete";
+      }
+    }
+
+    const boardTask: BoardTask = {
+      task,
+      isBlocked,
+      childCount,
+      doneChildCount,
+      pausedSubBadge,
+    };
+
+    const bucket = buckets.get(column);
+    if (bucket) {
+      bucket.push(boardTask);
+    } else {
+      // Unknown status → fall back to not_started column
+      buckets.get("not_started")!.push(boardTask);
+    }
+  }
+
+  // Sort tasks in each bucket by sortOrder
+  for (const columnTasks of buckets.values()) {
+    columnTasks.sort((a, b) => a.task.sortOrder - b.task.sortOrder);
+  }
+
+  // Build final column array in display order
+  return BOARD_COLUMN_ORDER.map((status) => {
+    const style = getStatusStyle(status);
+
+    return {
+      status,
+      label: style.label,
+      style,
+      tasks: buckets.get(status) ?? [],
+    };
+  });
+}