@grackle-ai/web-components 0.107.2

package/src/components/editable/useEditableField.ts

@@ -0,0 +1,173 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/** Options for the useEditableField hook. */
+export interface UseEditableFieldOptions {
+  /** Current persisted value. */
+  value: string;
+  /** Called when the user saves a new value. */
+  onSave: (value: string) => void;
+  /** Optional validation — return an error string, or undefined if valid. */
+  validate?: (value: string) => string | undefined;
+  /** Unique identifier for this field (used for coordination). */
+  fieldId: string;
+  /** Which field is currently being edited (coordination from parent). */
+  activeFieldId?: string | null; // eslint-disable-line @rushstack/no-new-null
+  /** Callback to tell the parent which field is active. */
+  onActivate?: (fieldId: string | null) => void; // eslint-disable-line @rushstack/no-new-null
+  /** Whether Enter key triggers save (true for text inputs, false for textarea). */
+  enterToSave?: boolean;
+  /** Whether to trim whitespace before saving. Default true. */
+  trimOnSave?: boolean;
+}
+
+/** Return type for the useEditableField hook. */
+export interface UseEditableFieldReturn {
+  /** Whether this field is currently in edit mode. */
+  isEditing: boolean;
+  /** The current draft value while editing. */
+  draft: string;
+  /** Validation error message, or empty string. */
+  error: string;
+  /** Whether the draft differs from the persisted value. */
+  isDirty: boolean;
+  /** Enter edit mode with the current value as the draft. */
+  startEdit: () => void;
+  /** Exit edit mode without saving. */
+  cancelEdit: () => void;
+  /** Validate and save the current draft. */
+  save: () => void;
+  /** Update the draft value. Also clears any validation error. */
+  setDraft: (value: string) => void;
+  /** Clear the validation error. */
+  clearError: () => void;
+  /** Blur handler that auto-saves, respecting ignoreInitialBlur and data-edit-action. */
+  handleBlur: (event: React.FocusEvent) => void;
+  /** Keyboard handler for Escape (cancel) and optionally Enter (save). */
+  handleKeyDown: (event: React.KeyboardEvent) => void;
+  /**
+   * Ref that prevents the initial blur (caused by clicking the edit button)
+   * from triggering a save. Set to true when startEdit is called, reset on
+   * first blur.
+   */
+  ignoreInitialBlurRef: React.RefObject<boolean>;
+}
+
+/**
+ * Shared hook that encapsulates the click-to-edit state machine used by
+ * EditableTextField, EditableTextArea, and EditableSelect.
+ */
+export function useEditableField(options: UseEditableFieldOptions): UseEditableFieldReturn {
+  const {
+    value,
+    onSave,
+    validate,
+    fieldId,
+    activeFieldId,
+    onActivate,
+    enterToSave = true,
+    trimOnSave = true,
+  } = options;
+
+  const [draft, setDraftRaw] = useState("");
+  const [error, setError] = useState("");
+  const ignoreInitialBlurRef = useRef<boolean>(false);
+
+  const isEditing = activeFieldId === fieldId;
+
+  const setDraft = useCallback((v: string) => {
+    setDraftRaw(v);
+    setError("");
+  }, []);
+
+  const clearError = useCallback(() => {
+    setError("");
+  }, []);
+
+  const cancelEdit = useCallback(() => {
+    ignoreInitialBlurRef.current = false;
+    onActivate?.(null);
+    setDraftRaw("");
+    setError("");
+  }, [onActivate]);
+
+  const save = useCallback(() => {
+    const saveValue = trimOnSave ? draft.trim() : draft;
+
+    if (validate) {
+      const validationError = validate(draft);
+      if (validationError) {
+        setError(validationError);
+        return;
+      }
+    }
+
+    // No-op when value hasn't changed
+    const compareValue = trimOnSave ? value.trim() : value;
+    if (saveValue === compareValue) {
+      cancelEdit();
+      return;
+    }
+
+    onSave(saveValue);
+    cancelEdit();
+  }, [draft, value, trimOnSave, validate, onSave, cancelEdit]);
+
+  const startEdit = useCallback(() => {
+    ignoreInitialBlurRef.current = true;
+    onActivate?.(fieldId);
+    setDraftRaw(value);
+    setError("");
+  }, [fieldId, value, onActivate]);
+
+  const handleBlur = useCallback((event: React.FocusEvent) => {
+    if (ignoreInitialBlurRef.current) {
+      ignoreInitialBlurRef.current = false;
+      return;
+    }
+    if (
+      event.relatedTarget instanceof HTMLElement &&
+      event.relatedTarget.dataset.editAction === fieldId
+    ) {
+      return;
+    }
+    save();
+  }, [fieldId, save]);
+
+  const handleKeyDown = useCallback((event: React.KeyboardEvent) => {
+    if (event.key === "Escape") {
+      cancelEdit();
+    } else if (event.key === "Enter" && enterToSave) {
+      save();
+    }
+  }, [cancelEdit, enterToSave, save]);
+
+  const isDirty = (() => {
+    if (!isEditing) return false;
+    const compareValue = trimOnSave ? value.trim() : value;
+    const draftValue = trimOnSave ? draft.trim() : draft;
+    return draftValue !== compareValue;
+  })();
+
+  // If another field becomes active, reset our local state
+  useEffect(() => {
+    if (!isEditing && (draft !== "" || error !== "")) {
+      setDraftRaw("");
+      setError("");
+    }
+  }, [isEditing, draft, error]);
+
+  return {
+    isEditing,
+    draft,
+    error,
+    isDirty,
+    startEdit,
+    cancelEdit,
+    save,
+    setDraft,
+    clearError,
+    handleBlur,
+    handleKeyDown,
+    ignoreInitialBlurRef,
+  };
+}

package/src/components/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Component exports organized by category.
+ * @module components
+ */
+
+// Layout components - application shell structure
+export { StatusBar, Sidebar, BottomStatusBar } from "./layout/index.js";
+
+// Panel components - main content areas
+export { FindingsPanel } from "./panels/index.js";
+
+// List components - sidebar navigation
+export { EnvironmentNav } from "./lists/index.js";
+
+// Display components - content rendering
+export { EventRenderer } from "./display/index.js";
+
+// Notification components - toasts and callouts
+export { Toast, ToastContainer, Callout } from "./notifications/index.js";
+export type { CalloutVariant } from "./notifications/index.js";

package/src/components/knowledge/KnowledgeDetailPanel.module.scss

@@ -0,0 +1,162 @@
+.panel {
+  position: absolute;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  width: 350px;
+  background: var(--bg-surface, #1a1a2e);
+  border-left: 1px solid var(--border-default, #333);
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+  z-index: 10;
+  animation: slideIn 0.2s ease-out;
+}
+
+@keyframes slideIn {
+  from {
+    transform: translateX(100%);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px;
+  border-bottom: 1px solid var(--border-default, #333);
+}
+
+.title {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+}
+
+.closeButton {
+  background: none;
+  border: none;
+  color: var(--text-secondary, #999);
+  font-size: 24px;
+  cursor: pointer;
+  padding: 0 4px;
+  line-height: 1;
+
+  &:hover {
+    color: var(--text-primary, #fff);
+  }
+}
+
+.body {
+  padding: 16px;
+  flex: 1;
+  overflow-y: auto;
+}
+
+.badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 4px;
+  font-size: 12px;
+  font-weight: 500;
+  background: var(--bg-inset, #222);
+  color: var(--text-secondary, #999);
+  margin-bottom: 12px;
+}
+
+.section {
+  margin-bottom: 16px;
+}
+
+.sectionLabel {
+  font-size: 11px;
+  font-weight: 600;
+  text-transform: uppercase;
+  color: var(--text-disabled, #666);
+  margin-bottom: 6px;
+}
+
+.content {
+  font-size: 14px;
+  line-height: 1.5;
+  color: var(--text-primary, #eee);
+  margin: 0;
+  white-space: pre-wrap;
+}
+
+.tags {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+.tag {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 12px;
+  font-size: 12px;
+  background: var(--bg-inset, #222);
+  color: var(--text-secondary, #aaa);
+}
+
+.viewLink {
+  background: none;
+  border: 1px solid var(--accent-blue, #4A9EFF);
+  color: var(--accent-blue, #4A9EFF);
+  padding: 6px 12px;
+  border-radius: 6px;
+  cursor: pointer;
+  font-size: 13px;
+
+  &:hover {
+    background: var(--accent-blue, #4A9EFF);
+    color: #fff;
+  }
+}
+
+.edgeList {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.edgeItem {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 4px 0;
+  border-bottom: 1px solid var(--border-default, #2a2a2a);
+  font-size: 13px;
+}
+
+.edgeType {
+  font-family: monospace;
+  font-size: 11px;
+  color: var(--text-disabled, #666);
+}
+
+.edgeNodeLink {
+  background: none;
+  border: none;
+  color: var(--accent-blue, #4A9EFF);
+  cursor: pointer;
+  font-size: 12px;
+  font-family: monospace;
+
+  &:hover {
+    text-decoration: underline;
+  }
+}
+
+.timestamps {
+  margin-top: 16px;
+  font-size: 12px;
+  color: var(--text-disabled, #666);
+}

package/src/components/knowledge/KnowledgeDetailPanel.stories.tsx

@@ -0,0 +1,208 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { expect, fn, userEvent } from "@storybook/test";
+import type { GraphNode, NodeDetail } from "../../hooks/types.js";
+import { makeGraphNode } from "../../test-utils/storybook-helpers.js";
+import { KnowledgeDetailPanel } from "./KnowledgeDetailPanel.js";
+
+// ---------------------------------------------------------------------------
+// Mock data
+// ---------------------------------------------------------------------------
+
+const defaultNode: GraphNode = makeGraphNode({
+  id: "node-001",
+  label: "Authentication Flow",
+  content: "OAuth2 flow with PKCE for CLI clients.",
+  tags: ["auth", "security", "autodocs"],
+  val: 3,
+});
+
+const connectedNodeA: GraphNode = makeGraphNode({
+  id: "node-002",
+  label: "Session Token Storage",
+  category: "decision",
+  val: 1,
+});
+
+const connectedNodeB: GraphNode = makeGraphNode({
+  id: "node-003",
+  label: "Token Rotation Policy",
+  category: "insight",
+  val: 2,
+});
+
+const unknownNodeId: string = "62d111f7-aaaa-bbbb-cccc-123456789abc";
+
+const defaultDetail: NodeDetail = {
+  node: defaultNode,
+  edges: [
+    { fromId: "node-001", toId: "node-002", type: "relates_to" },
+    { fromId: "node-003", toId: "node-001", type: "derived_from" },
+  ],
+};
+
+const allNodes: GraphNode[] = [defaultNode, connectedNodeA, connectedNodeB];
+
+// ---------------------------------------------------------------------------
+// Story meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta<typeof KnowledgeDetailPanel> = {
+  title: "Grackle/Knowledge/KnowledgeDetailPanel",
+  component: KnowledgeDetailPanel,
+  args: {
+    detail: defaultDetail,
+    nodes: allNodes,
+    onClose: fn(),
+    onSelectNode: fn(),
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof KnowledgeDetailPanel>;
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+/** Panel renders the node label, badge, content, tags, and timestamps. */
+export const BasicRendering: Story = {
+  play: async ({ canvas }) => {
+    // Title
+    await expect(canvas.getByText("Authentication Flow")).toBeInTheDocument();
+
+    // Category badge
+    await expect(canvas.getByText("concept")).toBeInTheDocument();
+
+    // Content
+    await expect(canvas.getByText("OAuth2 flow with PKCE for CLI clients.")).toBeInTheDocument();
+
+    // Tags
+    await expect(canvas.getByText("auth")).toBeInTheDocument();
+    await expect(canvas.getByText("security")).toBeInTheDocument();
+
+    // Timestamps
+    await expect(canvas.getByText(/Created:/)).toBeInTheDocument();
+    await expect(canvas.getByText(/Updated:/)).toBeInTheDocument();
+  },
+};
+
+/** Edge links display connected node titles, not truncated UUIDs. */
+export const EdgeLinksShowNodeTitles: Story = {
+  play: async ({ canvas }) => {
+    // Should show resolved titles, not truncated UUIDs
+    await expect(canvas.getByText("Session Token Storage")).toBeInTheDocument();
+    await expect(canvas.getByText("Token Rotation Policy")).toBeInTheDocument();
+
+    // Edge types should be displayed
+    const edgeTypes = canvas.getAllByTestId("edge-type");
+    await expect(edgeTypes.length).toBe(2);
+    await expect(edgeTypes[0]).toHaveTextContent("relates_to");
+    await expect(edgeTypes[1]).toHaveTextContent("derived_from");
+  },
+};
+
+/** Edge links fall back to truncated UUID when node is not in the graph. */
+export const EdgeLinksFallbackToTruncatedId: Story = {
+  args: {
+    detail: {
+      node: defaultNode,
+      edges: [
+        { fromId: "node-001", toId: unknownNodeId, type: "mentions" },
+      ],
+    },
+    nodes: [defaultNode],
+  },
+  play: async ({ canvas }) => {
+    // Should show truncated UUID since the connected node is not in the nodes list
+    await expect(canvas.getByText("62d111f7...")).toBeInTheDocument();
+  },
+};
+
+/** Clicking an edge link calls onSelectNode with the connected node ID. */
+export const EdgeLinkClickCallsOnSelectNode: Story = {
+  play: async ({ canvas, args }) => {
+    const edgeLinks = canvas.getAllByTestId("edge-node-link");
+    await userEvent.click(edgeLinks[0]);
+    await expect(args.onSelectNode).toHaveBeenCalledWith("node-002");
+  },
+};
+
+/** Close button calls onClose. */
+export const CloseButtonCallsOnClose: Story = {
+  play: async ({ canvas, args }) => {
+    const closeButton = canvas.getByRole("button", { name: "Close" });
+    await userEvent.click(closeButton);
+    await expect(args.onClose).toHaveBeenCalled();
+  },
+};
+
+/** No edges section when the node has no edges. */
+export const NoEdges: Story = {
+  args: {
+    detail: {
+      node: defaultNode,
+      edges: [],
+    },
+  },
+  play: async ({ canvas }) => {
+    // Title should still render
+    await expect(canvas.getByText("Authentication Flow")).toBeInTheDocument();
+
+    // No "Edges" section label
+    const panel = canvas.getByTestId("knowledge-detail-panel");
+    await expect(panel.textContent).not.toContain("Edges (");
+  },
+};
+
+/** Reference nodes show the "View in Grackle" link and a reference badge. */
+export const ReferenceNode: Story = {
+  args: {
+    detail: {
+      node: makeGraphNode({
+        id: "ref-001",
+        kind: "reference",
+        sourceType: "task",
+        sourceId: "task-123",
+        label: "Fix login bug",
+        content: undefined,
+        tags: [],
+      }),
+      edges: [],
+    },
+    nodes: [],
+  },
+  play: async ({ canvas }) => {
+    // Reference badge
+    await expect(canvas.getByText("Reference (task)")).toBeInTheDocument();
+
+    // View in Grackle link
+    const viewLink = canvas.getByRole("button", { name: /View in Grackle/ });
+    await expect(viewLink).toBeInTheDocument();
+  },
+};
+
+/** Node without content or tags omits those sections. */
+export const MinimalNode: Story = {
+  args: {
+    detail: {
+      node: makeGraphNode({
+        label: "Minimal Node",
+        content: undefined,
+        tags: undefined,
+        createdAt: undefined,
+        updatedAt: undefined,
+      }),
+      edges: [],
+    },
+    nodes: [],
+  },
+  play: async ({ canvas }) => {
+    // Title renders
+    await expect(canvas.getByText("Minimal Node")).toBeInTheDocument();
+
+    // No Content or Tags sections
+    const panel = canvas.getByTestId("knowledge-detail-panel");
+    await expect(panel.textContent).not.toContain("Content");
+    await expect(panel.textContent).not.toContain("Tags");
+  },
+};

package/src/components/knowledge/KnowledgeDetailPanel.tsx

@@ -0,0 +1,122 @@
+/**
+ * Slide-in detail panel for a selected knowledge graph node.
+ *
+ * @module
+ */
+
+import { useMemo, type JSX } from "react";
+import type { GraphNode, NodeDetail } from "../../hooks/types.js";
+import { taskUrl, sessionUrl, findingUrl } from "../../utils/navigation.js";
+import { useAppNavigate } from "../../utils/navigation.js";
+import styles from "./KnowledgeDetailPanel.module.scss";
+
+interface KnowledgeDetailPanelProps {
+  detail: NodeDetail;
+  nodes: GraphNode[];
+  onClose: () => void;
+  onSelectNode: (id: string) => void;
+}
+
+/** Slide-in panel showing full details for a selected knowledge node. */
+export function KnowledgeDetailPanel({
+  detail,
+  nodes,
+  onClose,
+  onSelectNode,
+}: KnowledgeDetailPanelProps): JSX.Element {
+  const navigate = useAppNavigate();
+  const { node, edges } = detail;
+  const nodeById = useMemo(() => new Map(nodes.map((n) => [n.id, n])), [nodes]);
+
+  /** Navigate to the source entity for reference nodes. */
+  function handleViewInGrackle(): void {
+    if (node.kind !== "reference" || !node.sourceId) {
+      return;
+    }
+    switch (node.sourceType) {
+      case "task":
+        navigate(taskUrl(node.sourceId));
+        break;
+      case "session":
+        navigate(sessionUrl(node.sourceId));
+        break;
+      case "finding":
+        navigate(findingUrl(node.sourceId));
+        break;
+      default:
+        break;
+    }
+  }
+
+  return (
+    <div className={styles.panel} data-testid="knowledge-detail-panel">
+      <div className={styles.header}>
+        <h3 className={styles.title}>{node.label}</h3>
+        <button className={styles.closeButton} onClick={onClose} aria-label="Close">
+          &times;
+        </button>
+      </div>
+
+      <div className={styles.body}>
+        <div className={styles.badge}>
+          {node.kind === "reference" ? `Reference (${node.sourceType})` : node.category}
+        </div>
+
+        {node.content && (
+          <div className={styles.section}>
+            <div className={styles.sectionLabel}>Content</div>
+            <p className={styles.content}>{node.content}</p>
+          </div>
+        )}
+
+        {node.tags && node.tags.length > 0 && (
+          <div className={styles.section}>
+            <div className={styles.sectionLabel}>Tags</div>
+            <div className={styles.tags}>
+              {node.tags.map((tag) => (
+                <span key={tag} className={styles.tag}>{tag}</span>
+              ))}
+            </div>
+          </div>
+        )}
+
+        {node.kind === "reference" && node.sourceId && (
+          <div className={styles.section}>
+            <button className={styles.viewLink} onClick={handleViewInGrackle}>
+              View in Grackle &rarr;
+            </button>
+          </div>
+        )}
+
+        {edges.length > 0 && (
+          <div className={styles.section}>
+            <div className={styles.sectionLabel}>Edges ({edges.length})</div>
+            <ul className={styles.edgeList}>
+              {edges.map((edge) => {
+                const otherId: string = edge.fromId === node.id ? edge.toId : edge.fromId;
+                const edgeKey: string = `${edge.fromId}:${edge.toId}:${edge.type}`;
+                return (
+                  <li key={edgeKey} className={styles.edgeItem} data-testid="edge-item">
+                    <span className={styles.edgeType} data-testid="edge-type">{edge.type}</span>
+                    <button
+                      className={styles.edgeNodeLink}
+                      data-testid="edge-node-link"
+                      onClick={() => { onSelectNode(otherId); }}
+                    >
+                      {nodeById.get(otherId)?.label ?? `${otherId.substring(0, 8)}...`}
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        )}
+
+        <div className={styles.timestamps}>
+          {node.createdAt && <div>Created: {new Date(node.createdAt).toLocaleDateString()}</div>}
+          {node.updatedAt && <div>Updated: {new Date(node.updatedAt).toLocaleDateString()}</div>}
+        </div>
+      </div>
+    </div>
+  );
+}