@grackle-ai/web-components 0.107.2

package/src/hooks/useTheme.ts

@@ -0,0 +1,228 @@
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import { THEMES, THEME_IDS, DEFAULT_THEME_ID, getThemeById } from "../themes.js";
+import type { ThemeDefinition } from "../themes.js";
+
+interface ThemeSnapshot {
+  themeId: string;
+  systemDark: boolean;
+  preferSystem: boolean;
+}
+
+const STORAGE_KEY: string = "grackle-theme";
+const PREFER_SYSTEM_KEY: string = "grackle-prefer-system";
+const MEDIA_QUERY: string = "(prefers-color-scheme: dark)";
+
+let listeners: Array<() => void> = [];
+let lastSnapshot: ThemeSnapshot | undefined = undefined;
+
+/** Notify all subscribers of a state change. */
+function emitChange(): void {
+  lastSnapshot = undefined;
+  for (const listener of listeners) {
+    listener();
+  }
+}
+
+/** Check whether the OS prefers dark mode. */
+function getSystemDark(): boolean {
+  if (typeof window === "undefined") {
+    return false;
+  }
+  return window.matchMedia(MEDIA_QUERY).matches;
+}
+
+/** Read the persisted theme ID from localStorage, defaulting to the registry default. */
+function getStored(): string {
+  if (typeof localStorage === "undefined") {
+    return DEFAULT_THEME_ID;
+  }
+  try {
+    const raw: string | null = localStorage.getItem(STORAGE_KEY);
+    if (raw !== null && THEME_IDS.has(raw)) {
+      return raw;
+    }
+  } catch {
+    // localStorage may be unavailable
+  }
+  return DEFAULT_THEME_ID;
+}
+
+/** Read the persisted prefer-system flag from localStorage. */
+function getPreferSystem(): boolean {
+  if (typeof localStorage === "undefined") {
+    return false;
+  }
+  try {
+    return localStorage.getItem(PREFER_SYSTEM_KEY) === "true";
+  } catch {
+    return false;
+  }
+}
+
+/** Find the parent theme for a hidden variant ID (e.g., "grackle-dark" → Grackle). */
+function findParentTheme(variantId: string): ThemeDefinition | undefined {
+  return THEMES.find((t) => t.variantLightId === variantId || t.variantDarkId === variantId);
+}
+
+/** Resolve a theme ID to the data-theme attribute value applied to the document. */
+function resolveDataTheme(themeId: string, preferSystem: boolean): string {
+  const def = getThemeById(themeId);
+  // Parent theme with variants → resolve to light or dark
+  if (def?.variantDarkId) {
+    if (preferSystem && def.variantLightId) {
+      return getSystemDark() ? def.variantDarkId : def.variantLightId;
+    }
+    return def.variantDarkId;
+  }
+  // Concrete variant ID (e.g., "grackle-dark") — if preferSystem, resolve via parent
+  if (def?.hidden && preferSystem) {
+    const parent = findParentTheme(themeId);
+    if (parent?.variantLightId && parent.variantDarkId) {
+      return getSystemDark() ? parent.variantDarkId : parent.variantLightId;
+    }
+  }
+  return themeId;
+}
+
+/** Apply the resolved theme to the document root element. */
+function applyTheme(themeId: string, preferSystem: boolean, suppressTransitions: boolean = false): void {
+  if (suppressTransitions) {
+    document.documentElement.classList.add("no-transitions");
+  }
+
+  document.documentElement.dataset.theme = resolveDataTheme(themeId, preferSystem);
+
+  if (suppressTransitions) {
+    // Force a reflow so the no-transitions class takes effect before removal
+    // eslint-disable-next-line no-unused-expressions
+    document.documentElement.offsetHeight;
+    requestAnimationFrame(() => {
+      document.documentElement.classList.remove("no-transitions");
+    });
+  }
+}
+
+// Apply immediately on module load to prevent flash of wrong theme
+if (typeof document !== "undefined") {
+  applyTheme(getStored(), getPreferSystem());
+}
+
+/** Build the current snapshot for useSyncExternalStore. */
+function getSnapshot(): ThemeSnapshot {
+  if (lastSnapshot === undefined) {
+    lastSnapshot = {
+      themeId: getStored(),
+      systemDark: getSystemDark(),
+      preferSystem: getPreferSystem(),
+    };
+  }
+  return lastSnapshot;
+}
+
+/** Subscribe to snapshot changes. */
+function subscribe(listener: () => void): () => void {
+  listeners = [...listeners, listener];
+  return () => {
+    listeners = listeners.filter((l) => l !== listener);
+  };
+}
+
+/** Result shape for the useTheme hook. */
+export interface UseThemeResult {
+  /** The user's chosen theme ID. */
+  themeId: string;
+  /** The actually-applied data-theme value after resolving system preference. */
+  resolvedThemeId: string;
+  /** Set a new theme by ID. */
+  setTheme: (nextId: string) => void;
+  /** Whether the theme follows the OS light/dark preference. */
+  preferSystem: boolean;
+  /** Toggle the OS preference auto-switch behavior. */
+  setPreferSystem: (prefer: boolean) => void;
+}
+
+/** React hook for reading and setting the application theme. */
+export function useTheme(): UseThemeResult {
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot);
+  const { themeId, preferSystem } = snapshot;
+
+  const resolvedThemeId: string = resolveDataTheme(themeId, preferSystem);
+
+  const setTheme = useCallback((nextId: string) => {
+    if (!THEME_IDS.has(nextId)) {
+      return;
+    }
+    try {
+      localStorage.setItem(STORAGE_KEY, nextId);
+    } catch {
+      // localStorage may be unavailable
+    }
+    applyTheme(nextId, getPreferSystem(), true);
+    emitChange();
+  }, []);
+
+  const setPreferSystem = useCallback((prefer: boolean) => {
+    try {
+      localStorage.setItem(PREFER_SYSTEM_KEY, prefer ? "true" : "false");
+    } catch {
+      // localStorage may be unavailable
+    }
+    // When enabling preferSystem, convert variant ID to parent ID
+    if (prefer) {
+      const stored = getStored();
+      const def = getThemeById(stored);
+      if (def?.hidden) {
+        const parent = findParentTheme(stored);
+        if (parent) {
+          try {
+            localStorage.setItem(STORAGE_KEY, parent.id);
+          } catch {
+            // localStorage may be unavailable
+          }
+        }
+      }
+    }
+    applyTheme(getStored(), prefer, true);
+    emitChange();
+  }, []);
+
+  // Keep DOM in sync on mount/change
+  useEffect(() => {
+    applyTheme(themeId, preferSystem);
+  }, [themeId, preferSystem]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return undefined;
+    }
+
+    const mediaQueryList: MediaQueryList = window.matchMedia(MEDIA_QUERY);
+    const handleChange = (): void => {
+      const stored: string = getStored();
+      const prefer: boolean = getPreferSystem();
+      if (prefer) {
+        const def = getThemeById(stored);
+        // Parent theme with variants
+        if (def?.variantDarkId && def.variantLightId) {
+          applyTheme(stored, prefer);
+        }
+        // Concrete variant — resolve via parent
+        if (def?.hidden) {
+          const parent = findParentTheme(stored);
+          if (parent?.variantDarkId && parent.variantLightId) {
+            applyTheme(stored, prefer);
+          }
+        }
+      }
+      emitChange();
+    };
+
+    mediaQueryList.addEventListener("change", handleChange);
+
+    return () => {
+      mediaQueryList.removeEventListener("change", handleChange);
+    };
+  }, []);
+
+  return { themeId, setTheme, resolvedThemeId, preferSystem, setPreferSystem };
+}

package/src/index.ts

@@ -0,0 +1,210 @@
+/**
+ * @grackle-ai/web-components — Presentational React component library.
+ *
+ * @packageDocumentation
+ */
+
+// ─── Components ──────────────────────────────────────────────────────────────
+
+// Chat
+export { ChatInput } from "./components/chat/index.js";
+export type { ChatInputProps } from "./components/chat/index.js";
+
+// DAG visualization
+export { DagView } from "./components/dag/DagView.js";
+export { TaskNode } from "./components/dag/TaskNode.js";
+export { useDagLayout } from "./components/dag/useDagLayout.js";
+
+// Display primitives
+export {
+  Breadcrumbs, Button, CopyButton, DemoBanner, SplitButton,
+  EventRenderer, ConfirmDialog, Skeleton, SkeletonText, SkeletonCard,
+  Spinner, SplashScreen, Tooltip,
+} from "./components/display/index.js";
+export type { ButtonProps, ButtonVariant, ButtonSize } from "./components/display/index.js";
+export type { TooltipProps, TooltipPlacement } from "./components/display/index.js";
+export { EventStream } from "./components/display/EventStream.js";
+export { EventHoverRow } from "./components/display/EventHoverRow.js";
+export type { EventHoverRowProps } from "./components/display/EventHoverRow.js";
+export { FloatingActionBar } from "./components/display/FloatingActionBar.js";
+export type { FloatingActionBarProps } from "./components/display/FloatingActionBar.js";
+export { SessionAttemptSelector } from "./components/display/SessionAttemptSelector.js";
+export type { SessionAttemptSelectorProps } from "./components/display/SessionAttemptSelector.js";
+export { SessionPicker } from "./components/display/SessionPicker.js";
+export type { SessionPickerProps, SessionPickerEntry } from "./components/display/SessionPicker.js";
+
+// Editable fields
+export {
+  EditableTextField, EditableTextArea, EditableSelect,
+  EditableCheckbox, EnvironmentSelect, useEditableField,
+} from "./components/editable/index.js";
+export type {
+  EditableTextFieldProps, EditableTextAreaProps,
+  EditableSelectProps, SelectOption,
+  EditableCheckboxProps, EnvironmentSelectProps,
+  UseEditableFieldOptions, UseEditableFieldReturn,
+} from "./components/editable/index.js";
+
+// Knowledge graph
+export { KnowledgeGraph, KnowledgeDetailPanel, KnowledgeNav } from "./components/knowledge/index.js";
+
+// Layout
+export { StatusBar, AppNav, Sidebar, BottomStatusBar, TABS } from "./components/layout/index.js";
+export type { AppTab } from "./components/layout/index.js";
+
+// Lists
+export { EnvironmentNav, FindingsNav } from "./components/lists/index.js";
+export { TaskList } from "./components/lists/TaskList.js";
+export { HighlightedText, buildTaskTree, groupTasksByStatus } from "./components/lists/listHelpers.js";
+
+// Notifications
+export { Toast, ToastContainer, Callout } from "./components/notifications/index.js";
+export type { CalloutVariant } from "./components/notifications/index.js";
+export { UpdateBanner } from "./components/notifications/UpdateBanner.js";
+
+// Panels
+export { FindingsPanel, TokensPanel, AppearancePanel, AboutPanel, TaskEditPanel, TaskActionButtons, TaskOverviewPanel, PluginsPanel } from "./components/panels/index.js";
+export type { PluginsPanelProps } from "./components/panels/index.js";
+export type { TaskActionButtonsProps } from "./components/panels/TaskActionButtons.js";
+export type { TaskOverviewPanelProps } from "./components/panels/TaskOverviewPanel.js";
+export { EnvironmentEditPanel } from "./components/panels/EnvironmentEditPanel.js";
+export { KeyboardShortcutsPanel } from "./components/panels/KeyboardShortcutsPanel.js";
+export { WorkpadPanel } from "./components/panels/WorkpadPanel.js";
+export { CredentialProvidersPanel } from "./components/panels/CredentialProvidersPanel.js";
+
+// Personas
+export { PersonaManager } from "./components/personas/PersonaManager.js";
+export { McpToolSelector } from "./components/personas/McpToolSelector.js";
+export type { PersonaManagerProps } from "./components/personas/PersonaManager.js";
+
+// Schedules
+export { ScheduleManager } from "./components/schedules/ScheduleManager.js";
+export type { ScheduleManagerProps } from "./components/schedules/ScheduleManager.js";
+
+// Settings
+export { SettingsNav } from "./components/settings/SettingsNav.js";
+
+// Streams
+export { StreamList, StreamDetailPanel } from "./components/streams/index.js";
+export type { StreamListProps, StreamDetailPanelProps } from "./components/streams/index.js";
+
+// Tools
+export { ToolCard } from "./components/tools/ToolCard.js";
+export { FileEditCard } from "./components/tools/FileEditCard.js";
+export { FileReadCard } from "./components/tools/FileReadCard.js";
+export { ShellCard } from "./components/tools/ShellCard.js";
+export { SearchCard } from "./components/tools/SearchCard.js";
+export { TodoCard } from "./components/tools/TodoCard.js";
+export { MetadataCard } from "./components/tools/MetadataCard.js";
+export { GenericToolCard } from "./components/tools/GenericToolCard.js";
+export { AgentToolCard } from "./components/tools/AgentToolCard.js";
+export { classifyTool } from "./components/tools/classifyTool.js";
+export { parseUnifiedDiff, diffFromOldNew, diffStats } from "./components/tools/parseDiff.js";
+export type { DiffLine, DiffStats } from "./components/tools/parseDiff.js";
+export { parseShellOutput } from "./components/tools/parseShellOutput.js";
+
+// Workspace
+export { WorkspaceBoard } from "./components/workspace/WorkspaceBoard.js";
+export { WorkspaceFormFields, defaultFormValues } from "./components/workspace/WorkspaceFormFields.js";
+export type { WorkspaceFormValues } from "./components/workspace/WorkspaceFormFields.js";
+
+// ─── Contexts ────────────────────────────────────────────────────────────────
+
+export { ToastProvider, useToast } from "./context/ToastContext.js";
+export type { ToastItem, ToastVariant } from "./context/ToastContext.js";
+
+export { ThemeProvider, useThemeContext } from "./context/ThemeContext.js";
+
+export { SidebarProvider, useSidebarContent, useSidebarSetter } from "./context/SidebarContext.js";
+
+export { GrackleContext, useGrackle } from "./context/GrackleContext.js";
+export type { UseGrackleSocketResult, GrackleContextType } from "./context/GrackleContext.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type {
+  Environment, Session, UsageStats, SessionEvent,
+  Workspace, TaskData, FindingData, TokenInfo,
+  CredentialProviderConfig, Codespace, PersonaData,
+  ScheduleData, ScheduleUpdate, UseSchedulesResult,
+  ProvisionStatus, GrackleEvent, WsMessage, SendFunction,
+  GraphNode, GraphLink, NodeDetail, UseKnowledgeResult,
+  UseEnvironmentsResult, UseSessionsResult, UseWorkspacesResult,
+  UseTasksResult, UseFindingsResult, UseTokensResult,
+  UseCredentialsResult, UseCodespacesResult, UsePersonasResult,
+  UsePluginsResult, PluginData,
+  StreamData, StreamSubscriberData, UseStreamsResult,
+  DomainHook,
+  ConnectionStatus,
+} from "./hooks/types.js";
+export {
+  isObject, warnBadPayload, isGrackleEvent, isSessionEvent,
+  isCredentialProviderConfig, parseWsMessage,
+  mapSessionStatus, mapEndReason,
+  WS_RECONNECT_DELAY_MS, MAX_EVENTS, WS_CLOSE_UNAUTHORIZED,
+} from "./hooks/types.js";
+
+// ─── Hooks ───────────────────────────────────────────────────────────────────
+
+export { useSmartScroll } from "./hooks/useSmartScroll.js";
+export { useEventSelection } from "./hooks/useEventSelection.js";
+export type { UseEventSelectionOptions, UseEventSelectionReturn } from "./hooks/useEventSelection.js";
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+export {
+  useAppNavigate, sessionUrl, workspaceUrl, taskUrl, taskEditUrl,
+  newTaskUrl, newChatUrl, ENVIRONMENTS_URL, NEW_ENVIRONMENT_URL,
+  environmentUrl, environmentEditUrl, SETTINGS_URL,
+  SETTINGS_ENVIRONMENTS_URL, SETTINGS_CREDENTIALS_URL,
+  PERSONAS_URL, NEW_PERSONA_URL, personaUrl,
+  SCHEDULES_URL, NEW_SCHEDULE_URL, scheduleUrl,
+  SETTINGS_APPEARANCE_URL, SETTINGS_ABOUT_URL, SETTINGS_SHORTCUTS_URL,
+  PAIR_PATH, NEW_WORKSPACE_URL, KNOWLEDGE_URL, HOME_URL,
+  FINDINGS_URL, findingsUrl, findingUrl,
+  CHAT_URL, chatStreamUrl, TASKS_URL,
+} from "./utils/navigation.js";
+
+export {
+  TASK_STATUS_STYLES, getStatusStyle, STATUS_BADGE_CLASS_MAP,
+  getStatusBadgeClassKey, SIDEBAR_STATUS_ORDER, BOARD_COLUMN_ORDER,
+  resolveStatus, STATUS_CSS_VAR_MAP,
+} from "./utils/taskStatus.js";
+export type { TaskStatusKey, VirtualStatus, DisplayStatus, TaskStatusStyle } from "./utils/taskStatus.js";
+
+export { formatTokens, formatCost } from "./utils/format.js";
+export { formatRelativeTime, formatCountdown } from "./utils/time.js";
+export { CATEGORY_COLORS, getCategoryColor } from "./utils/findingCategory.js";
+export type { CategoryColor } from "./utils/findingCategory.js";
+
+export type { BreadcrumbSegment } from "./utils/breadcrumbs.js";
+export {
+  buildTaskAncestorChain, buildHomeBreadcrumbs, buildSettingsBreadcrumbs,
+  buildEnvironmentsBreadcrumbs, buildNewEnvironmentBreadcrumbs,
+  buildNewChatBreadcrumbs, buildSessionBreadcrumbs,
+  buildWorkspaceBreadcrumbs, buildTaskBreadcrumbs, buildNewTaskBreadcrumbs,
+  buildFindingsBreadcrumbs, buildFindingBreadcrumbs,
+} from "./utils/breadcrumbs.js";
+
+export { groupConsecutiveTextEvents, pairToolEvents } from "./utils/sessionEvents.js";
+export type { DisplayEvent } from "./utils/sessionEvents.js";
+
+export { isContentBearingEvent, getEventCopyText, formatEventsAsMarkdown, formatForwardEnvelope } from "./utils/eventContent.js";
+
+export type { BoardColumn, BoardTask } from "./utils/boardColumns.js";
+export { buildBoardColumns } from "./utils/boardColumns.js";
+
+export type { DashboardKpis, AttentionTask, ActiveSession, WorkspaceSnapshot } from "./utils/dashboard.js";
+export { computeKpis, getAttentionTasks, getActiveSessions, getWorkspaceSnapshots } from "./utils/dashboard.js";
+
+export { isNearAnchor, computeScrollCompensation, SCROLL_ANCHOR_THRESHOLD_PX } from "./utils/scrollUtils.js";
+
+// ─── Themes ──────────────────────────────────────────────────────────────────
+
+export { THEMES, THEME_IDS, DEFAULT_THEME_ID, getThemeById } from "./themes.js";
+export type { ThemeDefinition } from "./themes.js";
+
+// ─── Mocks & Test Utilities ─────────────────────────────────────────────────
+
+export { MockGrackleProvider } from "./mocks/MockGrackleProvider.js";
+export { withMockGrackle, withMockGrackleRoute, makePersona, makeSchedule } from "./test-utils/storybook-helpers.js";