low-code-react-app-b/docs/api/HOOK_LIBRARY_REFERENCE.md

Hook Library Reference

Overview

The CodeForge hook library provides a comprehensive set of reusable hooks for managing application state, UI interactions, and business logic. All hooks follow React best practices and are fully typed with TypeScript.

Table of Contents

1. Data Management Hooks
2. Core Utility Hooks
3. UI State Hooks
4. Form Hooks
5. Canvas Hooks
6. AI Hooks
7. Orchestration Hooks

Data Management Hooks

useFiles

Manage project files with full CRUD operations.

import { useFiles } from '@/hooks/data/use-files'

function MyComponent() {
  const {
    files,           // ProjectFile[]
    addFile,         // (file: ProjectFile) => void
    updateFile,      // (id: string, updates: Partial<ProjectFile>) => void
    deleteFile,      // (id: string) => void
    getFile,         // (id: string) => ProjectFile | undefined
    updateFileContent // (id: string, content: string) => void
  } = useFiles()
  
  // Usage
  addFile({
    id: 'new-file',
    name: 'App.tsx',
    path: '/src/App.tsx',
    content: 'export default function App() {}',
    language: 'typescript'
  })
}

useModels

Manage Prisma models.

import { useModels } from '@/hooks/data/use-models'

function ModelDesigner() {
  const {
    models,       // PrismaModel[]
    addModel,     // (model: PrismaModel) => void
    updateModel,  // (id: string, updates: Partial<PrismaModel>) => void
    deleteModel,  // (id: string) => void
    getModel      // (id: string) => PrismaModel | undefined
  } = useModels()
  
  // Add a new model
  addModel({
    id: 'user-model',
    name: 'User',
    fields: [
      { name: 'id', type: 'String', isId: true },
      { name: 'email', type: 'String', isUnique: true }
    ],
    relations: []
  })
}

useComponents

Manage React components.

import { useComponents } from '@/hooks/data/use-components'

function ComponentBuilder() {
  const {
    components,      // ComponentNode[]
    addComponent,    // (component: ComponentNode) => void
    updateComponent, // (id: string, updates: Partial<ComponentNode>) => void
    deleteComponent, // (id: string) => void
    getComponent     // (id: string) => ComponentNode | undefined
  } = useComponents()
}

useWorkflows

Manage n8n-style workflows.

import { useWorkflows } from '@/hooks/data/use-workflows'

function WorkflowDesigner() {
  const {
    workflows,       // Workflow[]
    addWorkflow,     // (workflow: Workflow) => void
    updateWorkflow,  // (id: string, updates: Partial<Workflow>) => void
    deleteWorkflow,  // (id: string) => void
    getWorkflow      // (id: string) => Workflow | undefined
  } = useWorkflows()
}

useLambdas

Manage serverless functions.

import { useLambdas } from '@/hooks/data/use-lambdas'

function LambdaDesigner() {
  const {
    lambdas,       // Lambda[]
    addLambda,     // (lambda: Lambda) => void
    updateLambda,  // (id: string, updates: Partial<Lambda>) => void
    deleteLambda,  // (id: string) => void
    getLambda      // (id: string) => Lambda | undefined
  } = useLambdas()
}

Core Utility Hooks

useKVState

Enhanced KV storage with validation and transformations.

import { useKVState } from '@/hooks/core/use-kv-state'

function MyComponent() {
  const [value, setValue] = useKVState({
    key: 'my-data',
    defaultValue: { count: 0 },
    validate: (data) => data.count >= 0,
    transform: (data) => ({ ...data, lastUpdated: Date.now() })
  })
}

useClipboard

Copy to clipboard with feedback.

import { useClipboard } from '@/hooks/core/use-clipboard'

function CopyButton({ text }: { text: string }) {
  const { copy, copied } = useClipboard()
  
  return (
    <button onClick={() => copy(text)}>
      {copied ? 'Copied!' : 'Copy'}
    </button>
  )
}

useDebouncedSave

Auto-save with debouncing.

import { useDebouncedSave } from '@/hooks/core/use-debounced-save'

function Editor() {
  const [content, setContent] = useState('')
  
  useDebouncedSave(content, async (value) => {
    await saveToServer(value)
  }, 1000) // 1 second delay
  
  return <textarea value={content} onChange={e => setContent(e.target.value)} />
}

UI State Hooks

useDialog

Manage dialog/modal state.

import { useDialog } from '@/hooks/ui/use-dialog'

function MyComponent() {
  const { isOpen, open, close, toggle } = useDialog()
  
  return (
    <>
      <button onClick={open}>Open Dialog</button>
      <Dialog open={isOpen} onOpenChange={close}>
        {/* Dialog content */}
      </Dialog>
    </>
  )
}

useConfirmation

Confirm dangerous actions.

import { useConfirmation } from '@/hooks/ui/use-confirmation'

function DeleteButton({ onDelete }: { onDelete: () => void }) {
  const { confirm, ConfirmDialog } = useConfirmation({
    title: 'Delete Item',
    description: 'Are you sure? This cannot be undone.',
    confirmText: 'Delete',
    variant: 'destructive'
  })
  
  const handleDelete = async () => {
    if (await confirm()) {
      onDelete()
    }
  }
  
  return (
    <>
      <button onClick={handleDelete}>Delete</button>
      <ConfirmDialog />
    </>
  )
}

useSelection

Manage item selection (single or multiple).

import { useSelection } from '@/hooks/ui/use-selection'

function ItemList({ items }: { items: Item[] }) {
  const {
    selected,      // Set<string>
    isSelected,    // (id: string) => boolean
    toggle,        // (id: string) => void
    selectAll,     // () => void
    deselectAll,   // () => void
    selectedCount  // number
  } = useSelection({ multi: true })
  
  return (
    <div>
      {items.map(item => (
        <div
          key={item.id}
          onClick={() => toggle(item.id)}
          className={isSelected(item.id) ? 'selected' : ''}
        >
          {item.name}
        </div>
      ))}
    </div>
  )
}

useModal

Enhanced modal with data passing.

import { useModal } from '@/hooks/ui/use-modal'

function App() {
  const { isOpen, data, open, close } = useModal<{ userId: string }>()
  
  return (
    <>
      <button onClick={() => open({ userId: '123' })}>
        Edit User
      </button>
      {isOpen && <UserModal userId={data?.userId} onClose={close} />}
    </>
  )
}

useTabs

Manage tab state with URL sync.

import { useTabs } from '@/hooks/ui/use-tabs'

function TabbedInterface() {
  const { activeTab, setTab, tabs } = useTabs({
    tabs: ['overview', 'details', 'settings'],
    defaultTab: 'overview',
    syncWithUrl: true
  })
  
  return (
    <Tabs value={activeTab} onValueChange={setTab}>
      {/* Tab content */}
    </Tabs>
  )
}

usePanels

Manage resizable panel state.

import { usePanels } from '@/hooks/ui/use-panels'

function SplitView() {
  const { sizes, setSizes, collapsed, togglePanel } = usePanels({
    defaultSizes: [30, 70],
    minSizes: [20, 50]
  })
  
  return (
    <ResizablePanelGroup sizes={sizes} onResize={setSizes}>
      {/* Panels */}
    </ResizablePanelGroup>
  )
}

Form Hooks

useFormState

Comprehensive form state management.

import { useFormState } from '@/hooks/forms/use-form-state'

function UserForm() {
  const {
    values,         // Current form values
    errors,         // Validation errors
    touched,        // Touched fields
    isValid,        // Form validity
    isDirty,        // Form has changes
    isSubmitting,   // Submission state
    setValue,       // Set single field
    setValues,      // Set multiple fields
    setError,       // Set error
    handleSubmit,   // Submit handler
    reset           // Reset form
  } = useFormState({
    initialValues: {
      name: '',
      email: ''
    },
    validate: (values) => {
      const errors: any = {}
      if (!values.email) errors.email = 'Required'
      return errors
    },
    onSubmit: async (values) => {
      await saveUser(values)
    }
  })
  
  return (
    <form onSubmit={handleSubmit}>
      <input
        value={values.name}
        onChange={e => setValue('name', e.target.value)}
      />
      {errors.name && <span>{errors.name}</span>}
    </form>
  )
}

useValidation

Reusable validation logic.

import { useValidation } from '@/hooks/forms/use-validation'

function PasswordField() {
  const { validate, errors, isValid } = useValidation({
    rules: {
      minLength: 8,
      hasNumber: true,
      hasSpecialChar: true
    }
  })
  
  const handleChange = (value: string) => {
    validate(value)
  }
}

useFieldArray

Manage dynamic form arrays.

import { useFieldArray } from '@/hooks/forms/use-field-array'

function ContactsForm() {
  const {
    fields,    // Array of field values
    append,    // Add new field
    remove,    // Remove field
    move,      // Reorder fields
    update     // Update specific field
  } = useFieldArray({
    name: 'contacts',
    defaultValue: []
  })
  
  return (
    <div>
      {fields.map((field, index) => (
        <div key={index}>
          <input value={field.email} />
          <button onClick={() => remove(index)}>Remove</button>
        </div>
      ))}
      <button onClick={() => append({ email: '' })}>
        Add Contact
      </button>
    </div>
  )
}

Canvas Hooks

useCanvas

Canvas drawing utilities.

import { useCanvas } from '@/hooks/canvas/use-canvas'

function DrawingCanvas() {
  const {
    canvasRef,
    ctx,
    clear,
    drawLine,
    drawRect,
    drawCircle,
    getImageData,
    setImageData
  } = useCanvas({
    width: 800,
    height: 600
  })
  
  return <canvas ref={canvasRef} />
}

useDragDrop

Drag and drop for canvas elements.

import { useDragDrop } from '@/hooks/canvas/use-drag-drop'

function DraggableElements() {
  const {
    elements,        // Array of positioned elements
    draggedId,       // Currently dragged element
    handleMouseDown, // Start drag
    handleMouseMove, // During drag
    handleMouseUp,   // End drag
    updatePosition,  // Programmatic position update
  } = useDragDrop({
    initialElements: [
      { id: '1', x: 100, y: 100, width: 50, height: 50 }
    ]
  })
}

useZoomPan

Zoom and pan for canvas views.

import { useZoomPan } from '@/hooks/canvas/use-zoom-pan'

function ZoomableCanvas() {
  const {
    zoom,           // Current zoom level
    pan,            // Pan offset { x, y }
    zoomIn,         // Increase zoom
    zoomOut,        // Decrease zoom
    resetZoom,      // Reset to default
    setPan,         // Set pan position
    transform       // CSS transform string
  } = useZoomPan({
    minZoom: 0.1,
    maxZoom: 5,
    defaultZoom: 1
  })
  
  return (
    <div style={{ transform }}>
      {/* Canvas content */}
    </div>
  )
}

useConnections

Manage node connections (for diagrams/workflows).

import { useConnections } from '@/hooks/canvas/use-connections'

function FlowDiagram() {
  const {
    connections,      // Array of connections
    addConnection,    // Add new connection
    removeConnection, // Remove connection
    updateConnection, // Update connection
    getConnections    // Get connections for node
  } = useConnections({
    validate: (from, to) => from !== to // No self-connections
  })
}

AI Hooks

useAIGenerate

Generate content with AI.

import { useAIGenerate } from '@/hooks/ai/use-ai-generate'

function AIAssistant() {
  const {
    generate,      // (prompt: string) => Promise<string>
    isGenerating,  // boolean
    result,        // Generated content
    error          // Error if any
  } = useAIGenerate()
  
  const handleGenerate = async () => {
    const code = await generate('Create a React login form')
    console.log(code)
  }
}

useAIComplete

AI code completion.

import { useAIComplete } from '@/hooks/ai/use-ai-complete'

function CodeEditor() {
  const {
    complete,        // (prefix: string) => Promise<string>
    suggestions,     // string[]
    isCompleting,    // boolean
    acceptSuggestion // (index: number) => void
  } = useAIComplete({
    debounce: 300
  })
}

useAISuggestions

Get AI suggestions for improvements.

import { useAISuggestions } from '@/hooks/ai/use-ai-suggestions'

function CodeReview() {
  const {
    getSuggestions,   // (code: string) => Promise<Suggestion[]>
    suggestions,      // Suggestion[]
    applySuggestion,  // (id: string) => void
    dismissSuggestion // (id: string) => void
  } = useAISuggestions()
}

Orchestration Hooks

usePage

Execute a page schema.

import { usePage } from '@/hooks/orchestration/use-page'
import pageSchema from '@/config/pages/my-page.json'

function DynamicPage() {
  const {
    context,     // Data context
    execute,     // Execute action by ID
    isExecuting, // boolean
    handlers,    // Action handlers map
    schema       // Page schema
  } = usePage(pageSchema)
  
  return <PageRenderer schema={schema} />
}

useActions

Execute page actions.

import { useActions } from '@/hooks/orchestration/use-actions'

function ActionButtons() {
  const { execute, isExecuting, handlers } = useActions(
    [
      {
        id: 'save',
        type: 'update',
        params: { target: 'Files' }
      }
    ],
    { files: [], setFiles: () => {} }
  )
  
  return (
    <button onClick={() => execute('save')} disabled={isExecuting}>
      Save
    </button>
  )
}

Hook Composition Patterns

Combining Multiple Hooks

function FeaturePage() {
  const files = useFiles()
  const models = useModels()
  const { isOpen, open, close } = useDialog()
  const { selected, toggle } = useSelection()
  
  // Combine hooks to build complex features
  const handleCreateModel = () => {
    const model = createModelFromFiles(files.files)
    models.addModel(model)
    close()
  }
}

Custom Hook Composition

function useProjectEditor() {
  const files = useFiles()
  const { isOpen, open, close } = useDialog()
  const [activeFileId, setActiveFileId] = useState<string | null>(null)
  
  const openFile = (id: string) => {
    setActiveFileId(id)
    open()
  }
  
  const saveFile = (content: string) => {
    if (activeFileId) {
      files.updateFileContent(activeFileId, content)
    }
  }
  
  return {
    files: files.files,
    activeFile: files.getFile(activeFileId),
    openFile,
    saveFile,
    isEditing: isOpen,
    closeEditor: close
  }
}

Best Practices

1. Always Use Functional Updates

// ❌ Bad - May cause data loss
setFiles([...files, newFile])

// ✅ Good - Always gets current state
setFiles(current => [...current, newFile])

2. Memoize Expensive Computations

const filteredFiles = useMemo(() => {
  return files.filter(f => f.name.includes(search))
}, [files, search])

3. Clean Up Side Effects

useEffect(() => {
  const subscription = subscribe()
  return () => subscription.unsubscribe()
}, [])

4. Type Your Hooks

function useTypedData<T>(key: string, defaultValue: T) {
  const [data, setData] = useKV<T>(key, defaultValue)
  return { data, setData }
}

5. Extract Reusable Logic

// Extract common patterns into custom hooks
function useResource<T>(resourceName: string) {
  const [items, setItems] = useKV<T[]>(`${resourceName}-items`, [])
  
  const add = useCallback((item: T) => {
    setItems(current => [...current, item])
  }, [setItems])
  
  return { items, add }
}

Next Steps

• Explore /src/hooks/ directory for implementations
• Check ../architecture/JSON_ORCHESTRATION_GUIDE.md for page schemas
• See REFACTOR_PHASE3.md for architecture overview
• Read individual hook files for detailed implementation notes