@kb-labs/studio-app 0.6.0

package/src/utils/analytics.ts

@@ -0,0 +1,183 @@
+/**
+ * @module @kb-labs/studio-app/utils/analytics
+ * Analytics helpers for widget events, page views, and performance tracking
+ */
+
+import { createStudioLogger } from './logger';
+
+const analyticsLogger = createStudioLogger('analytics');
+
+/**
+ * Analytics configuration
+ */
+export interface AnalyticsConfig {
+  enabled: boolean;
+  trackPageViews: boolean;
+  trackWidgetEvents: boolean;
+  trackPerformance: boolean;
+  trackErrors: boolean;
+}
+
+let analyticsConfig: AnalyticsConfig = {
+  enabled: true,
+  trackPageViews: true,
+  trackWidgetEvents: true,
+  trackPerformance: true,
+  trackErrors: true,
+};
+
+/**
+ * Set analytics configuration
+ */
+export function setAnalyticsConfig(config: Partial<AnalyticsConfig>): void {
+  analyticsConfig = { ...analyticsConfig, ...config };
+}
+
+/**
+ * Get analytics configuration
+ */
+export function getAnalyticsConfig(): AnalyticsConfig {
+  return { ...analyticsConfig };
+}
+
+/**
+ * Widget event types
+ */
+export type WidgetEventType =
+  | 'mounted'
+  | 'error'
+  | 'interaction'
+  | 'data-loaded'
+  | 'data-error'
+  | 'export'
+  | 'refresh';
+
+/**
+ * Track widget event
+ * Fire-and-forget, analytics failures should not break execution
+ */
+export function trackWidgetEvent(
+  event: WidgetEventType,
+  data: {
+    widgetId: string;
+    pluginId: string;
+    code?: string;
+    event?: string;
+    duration?: number;
+    exportFormat?: string;
+  }
+): void {
+  if (!analyticsConfig.enabled || !analyticsConfig.trackWidgetEvents) {
+    return;
+  }
+
+  try {
+    // TODO: Integrate with @kb-labs/analytics-sdk-node
+    // For now, just log
+    analyticsLogger.info('Widget analytic event', {
+      event,
+      ...data,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (e) {
+    // Silently fail - analytics should not break execution
+    analyticsLogger.warn('Failed to track widget event', {
+      event,
+      data,
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+/**
+ * Track page view
+ */
+export function trackPageView(data: {
+  path: string;
+  title?: string;
+  layoutId?: string;
+  pluginId?: string;
+}): void {
+  if (!analyticsConfig.enabled || !analyticsConfig.trackPageViews) {
+    return;
+  }
+
+  try {
+    analyticsLogger.info('Page view', {
+      ...data,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (e) {
+    // Silently fail
+    analyticsLogger.warn('Failed to track page view', {
+      data,
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+/**
+ * Track performance metric
+ */
+export function trackPerformance(data: {
+  metric: string;
+  value: number;
+  unit?: string;
+  widgetId?: string;
+  pluginId?: string;
+}): void {
+  if (!analyticsConfig.enabled || !analyticsConfig.trackPerformance) {
+    return;
+  }
+
+  try {
+    analyticsLogger.info('Performance metric', {
+      ...data,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (e) {
+    // Silently fail
+    analyticsLogger.warn('Failed to track performance', {
+      data,
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+/**
+ * Track error
+ */
+export function trackError(data: {
+  error: Error | string;
+  context?: string;
+  widgetId?: string;
+  pluginId?: string;
+  metadata?: Record<string, unknown>;
+}): void {
+  if (!analyticsConfig.enabled || !analyticsConfig.trackErrors) {
+    return;
+  }
+
+  try {
+    const errorMessage = data.error instanceof Error ? data.error.message : data.error;
+    const errorStack = data.error instanceof Error ? data.error.stack : undefined;
+
+    analyticsLogger.error('Error tracked', {
+      error: errorMessage,
+      stack: errorStack,
+      context: data.context,
+      widgetId: data.widgetId,
+      pluginId: data.pluginId,
+      metadata: data.metadata,
+      timestamp: new Date().toISOString(),
+    });
+  } catch (e) {
+    // Silently fail
+    analyticsLogger.warn('Failed to track error', {
+      data,
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+

package/src/utils/apply-navigation-categories.ts

@@ -0,0 +1,83 @@
+/**
+ * @module @kb-labs/studio-app/utils/apply-navigation-categories
+ * Pure transform: flat NavigationItem[] + user categories → grouped NavigationItem[]
+ */
+
+import type { NavigationCategory } from '../providers/settings-provider';
+import type { NavigationItem } from '@/components/ui';
+
+const PROTECTED_KEYS = new Set(['settings']);
+
+/**
+ * Apply user's category configuration to the flat navigation items list.
+ *
+ * - Items assigned to a category are grouped under that category's header
+ * - Items not assigned to any category remain as top-level items (original order)
+ * - Categories sorted by `order` field
+ * - "settings" is protected — always last, never categorized
+ * - Missing keys (removed plugin/module) are silently skipped
+ * - Empty categories (all items removed) are omitted
+ */
+export function applyNavigationCategories(
+  items: NavigationItem[],
+  categories: NavigationCategory[],
+): NavigationItem[] {
+  if (categories.length === 0) {
+    return items;
+  }
+
+  // Collect all keys assigned to any category
+  const assignedKeys = new Set<string>();
+  for (const cat of categories) {
+    for (const key of cat.itemKeys) {
+      assignedKeys.add(key);
+    }
+  }
+
+  // Map key → item for quick lookup
+  const itemsByKey = new Map<string, NavigationItem>();
+  for (const item of items) {
+    itemsByKey.set(item.key, item);
+  }
+
+  const result: NavigationItem[] = [];
+
+  // 1. Uncategorized items in original order (except protected)
+  for (const item of items) {
+    if (!assignedKeys.has(item.key) && !PROTECTED_KEYS.has(item.key)) {
+      result.push(item);
+    }
+  }
+
+  // 2. Categories sorted by order
+  const sortedCategories = [...categories].sort((a, b) => a.order - b.order);
+  for (const cat of sortedCategories) {
+    const groupChildren: NavigationItem[] = [];
+    for (const key of cat.itemKeys) {
+      const item = itemsByKey.get(key);
+      if (item && !PROTECTED_KEYS.has(key)) {
+        groupChildren.push(item);
+      }
+    }
+
+    if (groupChildren.length > 0) {
+      result.push({
+        key: `category-${cat.id}`,
+        label: cat.label,
+        type: 'group',
+        children: groupChildren,
+      });
+    }
+  }
+
+  // 3. Divider + protected items last (settings)
+  const protectedItems = items.filter(item => PROTECTED_KEYS.has(item.key));
+  if (protectedItems.length > 0) {
+    result.push({ key: '__settings-divider', label: '', type: 'divider' });
+    for (const item of protectedItems) {
+      result.push(item);
+    }
+  }
+
+  return result;
+}

package/src/utils/commands.ts

@@ -0,0 +1,252 @@
+/**
+ * @module @kb-labs/studio-app/utils/commands
+ * Centralized command registry for Command Palette
+ */
+
+export type CommandCategory = 'recent' | 'navigation' | 'action' | 'plugin' | 'widget' | 'setting';
+
+export interface Command {
+  id: string;
+  title: string;
+  description?: string;
+  category: CommandCategory;
+  path: string;
+  /** Action to execute (alternative to path for navigation) */
+  action?: () => void | Promise<void>;
+  /** Keyboard shortcut */
+  shortcut?: string;
+  /** Tags for better search */
+  tags?: string[];
+  /** Priority for sorting (higher = shown first) */
+  priority?: number;
+}
+
+export interface CommandsConfig {
+  navigate: (path: string) => void;
+  toggleTheme: () => void;
+  refreshRegistry: () => Promise<void>;
+  invalidateCache: () => Promise<void>;
+  openQuickSearch: () => void;
+}
+
+/**
+ * Get all available commands for Command Palette
+ */
+export function getCommands(config: CommandsConfig): Command[] {
+  const { toggleTheme, refreshRegistry, invalidateCache, openQuickSearch } = config;
+
+  return [
+    // ============================================
+    // NAVIGATION COMMANDS
+    // ============================================
+    {
+      id: 'nav-dashboard',
+      title: 'Go to Dashboard',
+      description: 'View main dashboard',
+      category: 'navigation' as const,
+      path: '/',
+      tags: ['home', 'main', 'overview'],
+      priority: 100,
+    },
+    {
+      id: 'nav-observability',
+      title: 'Go to Observability',
+      description: 'View system observability',
+      category: 'navigation' as const,
+      path: '/observability',
+      tags: ['monitoring', 'metrics', 'logs'],
+      priority: 90,
+    },
+    {
+      id: 'nav-observability-events',
+      title: 'Go to System Events',
+      description: 'View system event log',
+      category: 'navigation' as const,
+      path: '/observability/system-events',
+      tags: ['events', 'logs', 'history'],
+      priority: 85,
+    },
+    {
+      id: 'nav-observability-registry',
+      title: 'Go to Registry Browser',
+      description: 'Browse plugin registry',
+      category: 'navigation' as const,
+      path: '/observability/registry',
+      tags: ['plugins', 'registry', 'browse'],
+      priority: 80,
+    },
+    {
+      id: 'nav-settings',
+      title: 'Go to Settings',
+      description: 'Configure application settings',
+      category: 'navigation' as const,
+      path: '/settings',
+      tags: ['preferences', 'config', 'configuration'],
+      shortcut: 'Cmd+,',
+      priority: 95,
+    },
+    {
+      id: 'nav-settings-appearance',
+      title: 'Go to Appearance Settings',
+      description: 'Change theme and appearance',
+      category: 'navigation' as const,
+      path: '/settings?tab=appearance',
+      tags: ['theme', 'dark mode', 'colors'],
+      priority: 70,
+    },
+    {
+      id: 'nav-settings-experimental',
+      title: 'Go to Experimental Features',
+      description: 'Enable experimental features',
+      category: 'navigation' as const,
+      path: '/settings?tab=experimental',
+      tags: ['features', 'flags', 'beta'],
+      priority: 65,
+    },
+    {
+      id: 'nav-settings-developer',
+      title: 'Go to Developer Tools',
+      description: 'Developer settings and tools',
+      category: 'navigation' as const,
+      path: '/settings?tab=developer',
+      tags: ['dev', 'debug', 'tools'],
+      priority: 60,
+    },
+
+    // ============================================
+    // ACTION COMMANDS
+    // ============================================
+    {
+      id: 'action-toggle-theme',
+      title: 'Toggle Dark Mode',
+      description: 'Switch between light and dark theme',
+      category: 'action' as const,
+      path: '',
+      action: toggleTheme,
+      tags: ['theme', 'dark', 'light', 'appearance'],
+      shortcut: 'Cmd+Shift+T',
+      priority: 90,
+    },
+    {
+      id: 'action-refresh-registry',
+      title: 'Refresh Registry',
+      description: 'Fetch latest registry data',
+      category: 'action' as const,
+      path: '',
+      action: refreshRegistry,
+      tags: ['refresh', 'reload', 'update'],
+      shortcut: 'Cmd+R',
+      priority: 85,
+    },
+    {
+      id: 'action-invalidate-cache',
+      title: 'Invalidate Cache & Re-discover',
+      description: 'Force full plugin re-discovery',
+      category: 'action' as const,
+      path: '',
+      action: invalidateCache,
+      tags: ['cache', 'clear', 'discover', 'plugins'],
+      priority: 80,
+    },
+    {
+      id: 'action-quick-search',
+      title: 'Open Quick Search',
+      description: 'Search pages and plugins',
+      category: 'action' as const,
+      path: '',
+      action: openQuickSearch,
+      tags: ['search', 'find'],
+      shortcut: 'Cmd+K',
+      priority: 100,
+    },
+    {
+      id: 'action-copy-registry-url',
+      title: 'Copy Registry URL',
+      description: 'Copy REST API registry endpoint',
+      category: 'action' as const,
+      path: '',
+      action: () => {
+        const url = `${window.location.origin}/api/v1/registry`;
+        navigator.clipboard.writeText(url);
+      },
+      tags: ['copy', 'url', 'api'],
+      priority: 50,
+    },
+
+    // ============================================
+    // SETTING COMMANDS
+    // ============================================
+    {
+      id: 'setting-appearance',
+      title: 'Appearance Settings',
+      description: 'Theme, colors, and visual preferences',
+      category: 'setting' as const,
+      path: '/settings?tab=appearance',
+      tags: ['theme', 'dark mode', 'colors', 'visual'],
+      priority: 70,
+    },
+    {
+      id: 'setting-privacy',
+      title: 'Data & Privacy Settings',
+      description: 'Privacy and data management',
+      category: 'setting' as const,
+      path: '/settings?tab=privacy',
+      tags: ['privacy', 'data', 'security'],
+      priority: 65,
+    },
+    {
+      id: 'setting-system',
+      title: 'System Information',
+      description: 'View system health and status',
+      category: 'setting' as const,
+      path: '/settings?tab=system',
+      tags: ['health', 'status', 'info'],
+      priority: 60,
+    },
+    {
+      id: 'setting-developer',
+      title: 'Developer Settings',
+      description: 'Development tools and debugging',
+      category: 'setting' as const,
+      path: '/settings?tab=developer',
+      tags: ['dev', 'debug', 'tools'],
+      priority: 55,
+    },
+  ];
+}
+
+/**
+ * Get recent commands from localStorage
+ */
+export function getRecentCommands(): string[] {
+  try {
+    const stored = localStorage.getItem('kb-recent-commands');
+    return stored ? JSON.parse(stored) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save command to recent history
+ */
+export function saveRecentCommand(commandId: string): void {
+  try {
+    const recent = getRecentCommands();
+    const updated = [commandId, ...recent.filter((id) => id !== commandId)].slice(0, 5);
+    localStorage.setItem('kb-recent-commands', JSON.stringify(updated));
+  } catch (error) {
+    console.error('Failed to save recent command:', error);
+  }
+}
+
+/**
+ * Clear recent commands history
+ */
+export function clearRecentCommands(): void {
+  try {
+    localStorage.removeItem('kb-recent-commands');
+  } catch (error) {
+    console.error('Failed to clear recent commands:', error);
+  }
+}

package/src/utils/export.ts

@@ -0,0 +1,174 @@
+/**
+ * @module @kb-labs/studio-app/utils/export
+ * Export utilities for widget data (CSV, JSON, PNG)
+ */
+
+/**
+ * Export data to CSV format
+ */
+export function exportToCSV(
+  data: unknown[],
+  filename: string = 'export.csv',
+  options?: {
+    headers?: string[];
+    delimiter?: string;
+  }
+): void {
+  if (!data || data.length === 0) {
+    console.warn('No data to export');
+    return;
+  }
+
+  const delimiter = options?.delimiter || ',';
+  const rows: string[] = [];
+
+  // Get headers
+  let headers: string[] = [];
+  if (options?.headers && options.headers.length > 0) {
+    headers = options.headers;
+  } else if (data.length > 0) {
+    // Auto-detect headers from first object
+    const firstItem = data[0];
+    if (typeof firstItem === 'object' && firstItem !== null) {
+      headers = Object.keys(firstItem as Record<string, unknown>);
+    }
+  }
+
+  // Add header row
+  if (headers.length > 0) {
+    rows.push(headers.map((h) => escapeCSVValue(h)).join(delimiter));
+  }
+
+  // Add data rows
+  for (const item of data) {
+    if (typeof item === 'object' && item !== null) {
+      const values = headers.map((header) => {
+        const value = (item as Record<string, unknown>)[header];
+        return escapeCSVValue(value);
+      });
+      rows.push(values.join(delimiter));
+    } else {
+      rows.push(escapeCSVValue(item));
+    }
+  }
+
+  // Create blob and download
+  const csvContent = rows.join('\n');
+  const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
+  downloadBlob(blob, filename);
+}
+
+/**
+ * Export data to JSON format
+ */
+export function exportToJSON(
+  data: unknown,
+  filename: string = 'export.json',
+  options?: {
+    pretty?: boolean;
+  }
+): void {
+  const jsonContent = options?.pretty
+    ? JSON.stringify(data, null, 2)
+    : JSON.stringify(data);
+
+  const blob = new Blob([jsonContent], { type: 'application/json;charset=utf-8;' });
+  downloadBlob(blob, filename);
+}
+
+/**
+ * Export chart/canvas to PNG
+ */
+export function exportToPNG(
+  element: HTMLElement | HTMLCanvasElement,
+  filename: string = 'export.png',
+  options?: {
+    backgroundColor?: string;
+    scale?: number;
+  }
+): void {
+  let canvas: HTMLCanvasElement;
+
+  if (element instanceof HTMLCanvasElement) {
+    canvas = element;
+  } else {
+    // Try to find canvas inside element
+    const canvasElement = element.querySelector('canvas');
+    if (!canvasElement) {
+      console.error('No canvas element found for PNG export');
+      return;
+    }
+    canvas = canvasElement;
+  }
+
+  // Create a new canvas for export
+  const exportCanvas = document.createElement('canvas');
+  const scale = options?.scale || 2; // Higher scale for better quality
+  exportCanvas.width = canvas.width * scale;
+  exportCanvas.height = canvas.height * scale;
+
+  const ctx = exportCanvas.getContext('2d');
+  if (!ctx) {
+    console.error('Failed to get canvas context');
+    return;
+  }
+
+  // Fill background if specified
+  if (options?.backgroundColor) {
+    ctx.fillStyle = options.backgroundColor;
+    ctx.fillRect(0, 0, exportCanvas.width, exportCanvas.height);
+  }
+
+  // Draw original canvas scaled up
+  ctx.drawImage(canvas, 0, 0, exportCanvas.width, exportCanvas.height);
+
+  // Convert to blob and download
+  exportCanvas.toBlob((blob) => {
+    if (blob) {
+      downloadBlob(blob, filename);
+    } else {
+      console.error('Failed to create PNG blob');
+    }
+  }, 'image/png');
+}
+
+/**
+ * Escape CSV value (handle commas, quotes, newlines)
+ */
+function escapeCSVValue(value: unknown): string {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  const str = String(value);
+  
+  // If value contains delimiter, quote, or newline, wrap in quotes and escape quotes
+  if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+
+  return str;
+}
+
+/**
+ * Download blob as file
+ */
+function downloadBlob(blob: Blob, filename: string): void {
+  const url = URL.createObjectURL(blob);
+  const link = document.createElement('a');
+  link.href = url;
+  link.download = filename;
+  document.body.appendChild(link);
+  link.click();
+  document.body.removeChild(link);
+  URL.revokeObjectURL(url);
+}
+
+/**
+ * Generate filename with timestamp
+ */
+export function generateFilename(prefix: string, extension: string): string {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+  return `${prefix}-${timestamp}.${extension}`;
+}
+