@toolr/ui-design 0.1.0

package/components/sections/snippets-editor/use-snippets-editor.ts

@@ -0,0 +1,217 @@
+/**
+ * useSnippetsEditor — Form state and CRUD hook for the snippets editor
+ *
+ * Part of: Sections > Snippets Editor
+ *
+ * Manages selected snippet, form data, edit/add mode, validation, search,
+ * and CRUD operations via the provided API.
+ *
+ * AI agent notes:
+ * - This hook is used internally by SnippetsEditor but can also be used
+ *   standalone for custom UIs
+ * - Validation checks: required fields, SNIPPET_NAME_REGEX, duplicate names
+ * - The hook does NOT hold the snippets array — it receives it as a param
+ *   so the consuming app owns the source of truth
+ */
+
+import { useState, useCallback, useMemo } from 'react'
+import { SNIPPET_NAME_REGEX, type SnippetData, type SnippetsEditorApi } from './types.ts'
+
+interface SnippetFormData {
+  name: string
+  description: string
+  value: string
+}
+
+const EMPTY_FORM: SnippetFormData = { name: '', description: '', value: '' }
+
+export interface UseSnippetsEditorOptions {
+  api: SnippetsEditorApi
+  snippets: SnippetData[]
+}
+
+export interface UseSnippetsEditorReturn {
+  // Selection
+  selectedName: string | null
+  selectSnippet: (name: string | null) => void
+
+  // Search
+  searchQuery: string
+  setSearchQuery: (query: string) => void
+  filteredSnippets: SnippetData[]
+
+  // Form
+  formData: SnippetFormData
+  setFormField: (field: keyof SnippetFormData, value: string) => void
+  formError: string | null
+  isEditing: boolean
+  isAdding: boolean
+
+  // Actions
+  startAdd: () => void
+  startEdit: (snippet: SnippetData) => void
+  cancelForm: () => void
+  save: () => Promise<void>
+  remove: (name: string) => Promise<void>
+  resetForm: () => void
+
+  // State
+  isSaving: boolean
+}
+
+export function useSnippetsEditor({ api, snippets }: UseSnippetsEditorOptions): UseSnippetsEditorReturn {
+  const [selectedName, setSelectedName] = useState<string | null>(null)
+  const [searchQuery, setSearchQuery] = useState('')
+  const [formData, setFormData] = useState<SnippetFormData>(EMPTY_FORM)
+  const [formError, setFormError] = useState<string | null>(null)
+  const [isAdding, setIsAdding] = useState(false)
+  const [editingOriginalName, setEditingOriginalName] = useState<string | null>(null)
+  const [isSaving, setIsSaving] = useState(false)
+
+  const isEditing = editingOriginalName !== null
+
+  const filteredSnippets = useMemo(() => {
+    if (!searchQuery.trim()) return snippets
+    const q = searchQuery.toLowerCase()
+    return snippets.filter(
+      (s) => s.name.toLowerCase().includes(q) || s.description.toLowerCase().includes(q),
+    )
+  }, [snippets, searchQuery])
+
+  const selectSnippet = useCallback((name: string | null) => {
+    setSelectedName(name)
+    setIsAdding(false)
+    setEditingOriginalName(null)
+    setFormError(null)
+    if (name) {
+      const snippet = snippets.find((s) => s.name === name)
+      if (snippet) {
+        setFormData({ name: snippet.name, description: snippet.description, value: snippet.value })
+        setEditingOriginalName(snippet.name)
+      }
+    } else {
+      setFormData(EMPTY_FORM)
+    }
+  }, [snippets])
+
+  const setFormField = useCallback((field: keyof SnippetFormData, value: string) => {
+    setFormData((prev: SnippetFormData) => ({ ...prev, [field]: field === 'name' ? value.toUpperCase() : value }))
+    setFormError(null)
+  }, [])
+
+  const startAdd = useCallback(() => {
+    setIsAdding(true)
+    setEditingOriginalName(null)
+    setSelectedName(null)
+    setFormData(EMPTY_FORM)
+    setFormError(null)
+  }, [])
+
+  const startEdit = useCallback((snippet: SnippetData) => {
+    setSelectedName(snippet.name)
+    setEditingOriginalName(snippet.name)
+    setIsAdding(false)
+    setFormData({ name: snippet.name, description: snippet.description, value: snippet.value })
+    setFormError(null)
+  }, [])
+
+  const cancelForm = useCallback(() => {
+    setIsAdding(false)
+    setEditingOriginalName(null)
+    setSelectedName(null)
+    setFormData(EMPTY_FORM)
+    setFormError(null)
+  }, [])
+
+  const resetForm = useCallback(() => {
+    if (editingOriginalName) {
+      const snippet = snippets.find((s) => s.name === editingOriginalName)
+      if (snippet) {
+        setFormData({ name: snippet.name, description: snippet.description, value: snippet.value })
+        setFormError(null)
+      }
+    } else {
+      setFormData(EMPTY_FORM)
+      setFormError(null)
+    }
+  }, [editingOriginalName, snippets])
+
+  const validate = useCallback((data: SnippetFormData): string | null => {
+    if (!data.name.trim()) return 'Snippet name is required'
+    if (!SNIPPET_NAME_REGEX.test(data.name)) return 'Name must be uppercase with underscores (e.g., MY_SNIPPET)'
+    const isDuplicate = snippets.some(
+      (s) => s.name.toUpperCase() === data.name.toUpperCase() && s.name !== editingOriginalName,
+    )
+    if (isDuplicate) return 'A snippet with this name already exists'
+    if (!data.description.trim()) return 'Description is required'
+    return null
+  }, [snippets, editingOriginalName])
+
+  const save = useCallback(async () => {
+    const error = validate(formData)
+    if (error) {
+      setFormError(error)
+      return
+    }
+
+    const snippet: SnippetData = {
+      name: formData.name.toUpperCase(),
+      description: formData.description.trim(),
+      value: formData.value,
+    }
+
+    setIsSaving(true)
+    try {
+      if (editingOriginalName) {
+        await api.updateSnippet(editingOriginalName, snippet)
+      } else {
+        await api.addSnippet(snippet)
+      }
+      setSelectedName(snippet.name)
+      setEditingOriginalName(snippet.name)
+      setIsAdding(false)
+      setFormError(null)
+    } catch (err) {
+      setFormError(`Failed to save: ${err}`)
+    } finally {
+      setIsSaving(false)
+    }
+  }, [formData, editingOriginalName, api, validate])
+
+  const remove = useCallback(async (name: string) => {
+    setIsSaving(true)
+    try {
+      await api.removeSnippet(name)
+      if (selectedName === name) {
+        setSelectedName(null)
+        setEditingOriginalName(null)
+        setFormData(EMPTY_FORM)
+        setFormError(null)
+      }
+    } catch (err) {
+      setFormError(`Failed to delete: ${err}`)
+    } finally {
+      setIsSaving(false)
+    }
+  }, [api, selectedName])
+
+  return {
+    selectedName,
+    selectSnippet,
+    searchQuery,
+    setSearchQuery,
+    filteredSnippets,
+    formData,
+    setFormField,
+    formError,
+    isEditing,
+    isAdding,
+    startAdd,
+    startEdit,
+    cancelForm,
+    save,
+    remove,
+    resetForm,
+    isSaving,
+  }
+}

package/components/ui/action-dialog.tsx

@@ -0,0 +1,309 @@
+/**
+ * ActionDialog - Standard dialog for AI execution workflows
+ *
+ * Built-in sections:
+ * 1. SelectionGrid - tool/item selection (single/multi) when items provided
+ * 2. Scenarios - second SelectionGrid for scenario selection with "Select All"
+ * 3. children - additional content
+ * 4. ExecutionDetailsPanel - mandatory execution configuration display
+ *
+ * Header: icon, title, subtitle, optional settings button
+ * Footer: FormActions (status text, cancel/submit)
+ */
+
+import { useEffect } from 'react'
+import { createPortal } from 'react-dom'
+import {
+  ArrowLeft, ArrowRight, ArrowUp, ArrowDown,
+  ChevronLeft, ChevronRight, ChevronUp, ChevronDown,
+  Check, X, Plus, Minus, Pencil, Trash2, Copy, Save,
+  RefreshCw, RotateCcw, Undo2, Redo2,
+  Search, Filter, Download, Upload, ExternalLink, Link2,
+  Eye, EyeOff, Lock, Unlock, Settings, MoreHorizontal, MoreVertical,
+  Info, HelpCircle,
+  User, Users, Folder, File, Image, Code, Terminal,
+  Star, Heart, Bell, Bookmark, Tag, Pin, Mail, Send,
+  Globe, Database, Cloud,
+  Wand2, Shield, ShieldCheck, Zap, Sparkles,
+  Play, Pause, Square, StopCircle,
+  Menu, GripVertical, Maximize2, Minimize2,
+  Scan, Webhook, Bot, Puzzle, Plug,
+} from 'lucide-react'
+import type { LucideIcon } from 'lucide-react'
+import { IconButton } from './icon-button.tsx'
+import type { IconName } from './icon-button.tsx'
+import { FormActions } from './form-actions.tsx'
+import { SelectionGrid, type SelectionCardItem, type CodingToolPresetConfig } from './selection-grid.tsx'
+import { ExecutionDetailsPanel, type ExecutionDetailRow } from './execution-details-panel.tsx'
+import { cn } from '../lib/cn.ts'
+
+const dialogIconMap: Record<string, LucideIcon> = {
+  'arrow-left': ArrowLeft, 'arrow-right': ArrowRight, 'arrow-up': ArrowUp, 'arrow-down': ArrowDown,
+  'chevron-left': ChevronLeft, 'chevron-right': ChevronRight, 'chevron-up': ChevronUp, 'chevron-down': ChevronDown,
+  'check': Check, 'x': X, 'plus': Plus, 'minus': Minus, 'pencil': Pencil, 'trash': Trash2, 'copy': Copy, 'save': Save,
+  'refresh': RefreshCw, 'rotate': RotateCcw, 'undo': Undo2, 'redo': Redo2,
+  'search': Search, 'filter': Filter, 'download': Download, 'upload': Upload, 'external-link': ExternalLink, 'link': Link2,
+  'eye': Eye, 'eye-off': EyeOff, 'lock': Lock, 'unlock': Unlock, 'settings': Settings, 'more-h': MoreHorizontal, 'more-v': MoreVertical,
+  'info': Info, 'help': HelpCircle,
+  'user': User, 'users': Users, 'folder': Folder, 'file': File, 'image': Image, 'code': Code, 'terminal': Terminal,
+  'star': Star, 'heart': Heart, 'bell': Bell, 'bookmark': Bookmark, 'tag': Tag, 'pin': Pin, 'mail': Mail, 'send': Send,
+  'globe': Globe, 'database': Database, 'cloud': Cloud,
+  'wand': Wand2, 'shield': Shield, 'shield-check': ShieldCheck, 'zap': Zap, 'sparkles': Sparkles,
+  'play': Play, 'pause': Pause, 'stop': Square, 'stop-circle': StopCircle, 'scan': Scan,
+  'menu': Menu, 'grip': GripVertical, 'maximize': Maximize2, 'minimize': Minimize2,
+  'webhook': Webhook, 'bot': Bot, 'puzzle': Puzzle, 'plug': Plug,
+}
+
+export interface ActionDialogProps {
+  /** Dialog title */
+  title: string
+  /** Subtitle text next to title */
+  subtitle?: string
+  /** Icon displayed before title */
+  icon?: IconName
+  /** Icon color */
+  iconColor?: string
+  /** Settings gear button callback */
+  onSettings?: () => void
+  /** Cancel/close callback */
+  onCancel?: () => void
+  /** Submit/action callback */
+  onSubmit?: () => void
+  /** Submit button label (shown in tooltip) */
+  submitLabel?: string
+  /** Submit button icon */
+  submitIcon?: IconName
+  /** Submit button color variant */
+  submitColor?: string
+  /** Disable submit button */
+  submitDisabled?: boolean
+  /** Status text shown in footer left */
+  statusText?: string
+
+  // ── Selection section (optional) ─────────────────────────────────────────
+  /** Label above the selection grid (e.g. "AI Tool:") */
+  selectionLabel?: string
+  /** Custom selection items - renders SelectionGrid when provided */
+  items?: SelectionCardItem[]
+  /** Built-in AI tool presets. Ignored when `items` is provided. */
+  presets?: CodingToolPresetConfig[]
+  /** Currently selected item IDs */
+  selectedIds?: string[]
+  /** Selection change handler */
+  onSelect?: (ids: string[]) => void
+  /** Single or multiple selection */
+  selectionMode?: 'single' | 'multiple'
+  /** Grid (icon-top cards) or list (icon-left rows) */
+  selectionLayout?: 'grid' | 'list'
+  /** Grid column count (auto if not set) */
+  selectionColumns?: number
+
+  // ── Scenarios section (optional) ─────────────────────────────────────────
+  /** Label above scenarios (e.g. "Select scenarios to run:") */
+  scenarioLabel?: string
+  /** Scenario items - renders second SelectionGrid when provided */
+  scenarios?: SelectionCardItem[]
+  /** Currently selected scenario IDs */
+  selectedScenarioIds?: string[]
+  /** Scenario selection change handler */
+  onSelectScenarios?: (ids: string[]) => void
+  /** Scenario grid layout */
+  scenarioLayout?: 'grid' | 'list'
+  /** Scenario grid column count */
+  scenarioColumns?: number
+
+  // ── Execution details section (mandatory) ────────────────────────────────
+  /** Execution detail rows (Tool, Permissions, Output, CLI Flags, Changes) */
+  executionDetails: ExecutionDetailRow[]
+  /** Whether direct file edits are allowed */
+  allowDirectEdits?: boolean
+  /** Callback to toggle direct edits - shows the toggle when provided */
+  onAllowDirectEditsChange?: (value: boolean) => void
+  /** Warning message shown in the execution details section */
+  executionWarning?: string
+
+  // ── Additional content ───────────────────────────────────────────────────
+  /** Additional content rendered between scenarios and execution details */
+  children?: React.ReactNode
+  /** Additional className */
+  className?: string
+}
+
+export function ActionDialog({
+  title,
+  subtitle,
+  icon,
+  iconColor,
+  onSettings,
+  onCancel,
+  onSubmit,
+  submitLabel = 'Submit',
+  submitIcon = 'chevron-right',
+  submitColor = 'blue',
+  submitDisabled = false,
+  statusText,
+  selectionLabel,
+  items,
+  presets,
+  selectedIds,
+  onSelect,
+  selectionMode = 'multiple',
+  selectionLayout = 'grid',
+  selectionColumns,
+  scenarioLabel = 'Select scenarios to run:',
+  scenarios,
+  selectedScenarioIds,
+  onSelectScenarios,
+  scenarioLayout = 'list',
+  scenarioColumns = 2,
+  executionDetails,
+  allowDirectEdits,
+  onAllowDirectEditsChange,
+  executionWarning,
+  children,
+  className,
+}: ActionDialogProps) {
+  useEffect(() => {
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onCancel?.()
+    }
+    document.addEventListener('keydown', handleEscape)
+    return () => document.removeEventListener('keydown', handleEscape)
+  }, [onCancel])
+
+  useEffect(() => {
+    document.body.style.overflow = 'hidden'
+    return () => { document.body.style.overflow = '' }
+  }, [])
+
+  const Icon = icon ? dialogIconMap[icon] : null
+  const hasSelection = ((items && items.length > 0) || (presets && presets.length > 0)) && selectedIds && onSelect
+  const hasScenarios = scenarios && scenarios.length > 0 && selectedScenarioIds && onSelectScenarios
+  const hasExecutionDetails = executionDetails.length > 0 || onAllowDirectEditsChange || executionWarning
+
+  const allScenariosSelected = hasScenarios && selectedScenarioIds!.length === scenarios!.filter(s => !s.disabled).length
+
+  function handleSelectAllScenarios() {
+    if (!scenarios || !onSelectScenarios) return
+    if (allScenariosSelected) {
+      onSelectScenarios([])
+    } else {
+      onSelectScenarios(scenarios.filter(s => !s.disabled).map(s => s.id))
+    }
+  }
+
+  return createPortal(
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" onClick={onCancel} />
+      <div
+        className={cn(
+          'relative bg-neutral-950 border border-neutral-700 rounded-xl shadow-2xl w-full max-w-[800px] mx-4 flex flex-col',
+          'max-h-[80vh]',
+          className,
+        )}
+      >
+        {/* Header */}
+        <div className="flex items-center gap-3 px-4 py-3 border-b border-neutral-700 flex-shrink-0">
+          {Icon && (
+            <Icon
+              className="w-4 h-4 flex-shrink-0"
+              style={iconColor ? { color: iconColor } : undefined}
+            />
+          )}
+          <div className="flex flex-col">
+            <span className="text-sm font-semibold text-neutral-200">
+              {title}
+            </span>
+            {subtitle && (
+              <span className="text-xs text-neutral-500">{subtitle}</span>
+            )}
+          </div>
+          <div className="flex-1" />
+          {onSettings && (
+            <IconButton
+              icon="settings"
+              size="sm"
+              color="neutral"
+              onClick={onSettings}
+              tooltip={{ description: 'Open settings' }}
+            />
+          )}
+        </div>
+
+        {/* Content */}
+        <div className="px-4 py-4 overflow-y-auto flex-1 min-h-0 space-y-4">
+          {/* Built-in SelectionGrid for tools/items */}
+          {hasSelection && (
+            <div>
+              {selectionLabel && (
+                <div className="text-xs text-neutral-500 mb-2">{selectionLabel}</div>
+              )}
+              <SelectionGrid
+                items={items}
+                presets={!items ? presets : undefined}
+                selectedIds={selectedIds}
+                onSelect={onSelect}
+                mode={selectionMode}
+                layout={selectionLayout}
+                columns={selectionColumns}
+              />
+            </div>
+          )}
+
+          {/* Built-in SelectionGrid for scenarios */}
+          {hasScenarios && (
+            <div>
+              <div className="flex items-center justify-between mb-2">
+                <span className="text-xs text-neutral-500">{scenarioLabel}</span>
+                <button
+                  type="button"
+                  onClick={handleSelectAllScenarios}
+                  className="text-xs text-blue-400 hover:text-blue-300 transition-colors cursor-pointer"
+                >
+                  {allScenariosSelected ? 'Deselect All' : 'Select All'}
+                </button>
+              </div>
+              <SelectionGrid
+                items={scenarios}
+                selectedIds={selectedScenarioIds}
+                onSelect={onSelectScenarios}
+                mode="multiple"
+                layout={scenarioLayout}
+                columns={scenarioColumns}
+              />
+            </div>
+          )}
+
+          {/* Additional content */}
+          {children}
+
+          {/* Built-in ExecutionDetailsPanel */}
+          {hasExecutionDetails && (
+            <ExecutionDetailsPanel
+              details={executionDetails}
+              allowDirectEdits={allowDirectEdits}
+              onAllowDirectEditsChange={onAllowDirectEditsChange}
+              warningMessage={executionWarning}
+            />
+          )}
+        </div>
+
+        {/* Footer */}
+        <div className="flex-shrink-0">
+          <FormActions
+            padding="modal"
+            statusText={statusText}
+            onCancel={onCancel}
+            cancelTooltip="Close this dialog"
+            onConfirm={onSubmit}
+            confirmTooltip={submitLabel}
+            confirmIcon={submitIcon}
+            confirmColor={submitColor as 'blue'}
+            confirmDisabled={submitDisabled}
+          />
+        </div>
+      </div>
+    </div>,
+    document.body,
+  )
+}

package/components/ui/ai-action-button.tsx

@@ -0,0 +1,137 @@
+import { useMemo } from 'react'
+import { IconButton, type IconButtonProps, type IconName } from './icon-button.tsx'
+
+export type AiActionStatus = 'idle' | 'running' | 'completed'
+export type AiCompletionResult = 'success' | 'partial' | 'error'
+
+export interface AiActionButtonProps {
+  /** Current execution status */
+  status?: AiActionStatus
+  /** Result when status is 'completed' */
+  completionResult?: AiCompletionResult
+
+  /** Icon shown in default state */
+  icon: IconName
+  /** Icon shown when running (defaults to 'loader') */
+  runningIcon?: IconName
+  /** Icon shown when completed successfully (defaults to 'check-circle') */
+  completedIcon?: IconName
+
+  /** Base tooltip (title/description modified based on state) */
+  tooltip: { title: string; description: string }
+  /** Tooltip title when running (defaults to "Show {title} Progress") */
+  runningTooltipTitle?: string
+  /** Tooltip title when completed (defaults to "View {title} Results") */
+  completedTooltipTitle?: string
+
+  onClick?: () => void
+
+  /** Force disabled state (in addition to automatic running state) */
+  disabled?: boolean
+  /** Custom reason when force-disabled */
+  disabledReason?: string
+
+  /** Color in default state */
+  color?: IconButtonProps['color']
+  /** Color when completed successfully (defaults to 'green') */
+  completedColor?: IconButtonProps['color']
+
+  size?: IconButtonProps['size']
+  className?: string
+  testId?: string
+}
+
+const COMPLETION_COLORS: Record<AiCompletionResult, IconButtonProps['color']> = {
+  success: 'green',
+  partial: 'amber',
+  error: 'red',
+}
+
+const COMPLETION_ICONS: Record<AiCompletionResult, IconName> = {
+  success: 'check-circle',
+  partial: 'alert-triangle',
+  error: 'x-circle',
+}
+
+export function AiActionButton({
+  status = 'idle',
+  completionResult,
+  icon,
+  runningIcon,
+  completedIcon,
+  tooltip,
+  runningTooltipTitle,
+  completedTooltipTitle,
+  onClick,
+  disabled: forceDisabled = false,
+  disabledReason,
+  color = 'neutral',
+  completedColor = 'green',
+  size = 'sm',
+  className,
+  testId,
+}: AiActionButtonProps) {
+  const isRunning = status === 'running'
+  const isCompleted = status === 'completed'
+
+  const resolvedIcon: IconName = useMemo(() => {
+    if (isRunning) return runningIcon ?? 'loader'
+    if (isCompleted && completionResult) {
+      return completionResult === 'success'
+        ? (completedIcon ?? COMPLETION_ICONS[completionResult])
+        : COMPLETION_ICONS[completionResult]
+    }
+    return icon
+  }, [isRunning, isCompleted, completionResult, icon, runningIcon, completedIcon])
+
+  const resolvedColor = useMemo(() => {
+    if (isCompleted && completionResult) {
+      return completionResult === 'success'
+        ? completedColor
+        : COMPLETION_COLORS[completionResult]
+    }
+    return color
+  }, [isCompleted, completionResult, completedColor, color])
+
+  const resolvedTooltip = useMemo(() => {
+    if (forceDisabled && disabledReason) {
+      return {
+        title: `${tooltip.title} Unavailable`,
+        description: disabledReason,
+      }
+    }
+
+    if (isRunning) {
+      return {
+        title: runningTooltipTitle ?? `Show ${tooltip.title} Progress`,
+        description: 'Click to view current progress',
+      }
+    }
+
+    if (isCompleted) {
+      return {
+        title: completedTooltipTitle ?? `View ${tooltip.title} Results`,
+        description: 'Click to view completed results',
+      }
+    }
+
+    return tooltip
+  }, [tooltip, forceDisabled, disabledReason, isRunning, isCompleted, runningTooltipTitle, completedTooltipTitle])
+
+  const isDisabled = forceDisabled
+  const blinkClass = isCompleted ? 'animate-pulse' : ''
+
+  return (
+    <IconButton
+      icon={resolvedIcon}
+      color={resolvedColor}
+      size={size}
+      disabled={isDisabled}
+      onClick={isDisabled ? () => {} : onClick}
+      tooltip={resolvedTooltip}
+      active={isRunning}
+      className={`${className ?? ''} ${blinkClass}`.trim() || undefined}
+      testId={testId}
+    />
+  )
+}