@etus/ui 0.1.0

package/src/components/workflow/DashboardBuilder/DashboardBuilder.tsx

@@ -0,0 +1,944 @@
+import type {
+  BuilderLayoutConfig,
+  BuilderMode,
+  BuilderPosition,
+  BuilderState,
+  BuilderWidget,
+  BuilderWidgetDefinition,
+  DashboardBuilderCanvasProps,
+  DashboardBuilderPropertiesPanelProps,
+  DashboardBuilderProps,
+  DashboardBuilderToolbarProps,
+  DashboardBuilderWidgetComponentProps,
+  DashboardBuilderWidgetLibraryProps,
+} from "./DashboardBuilder.types"
+import type { DragEvent, KeyboardEvent, ReactNode } from "react"
+
+import {
+  BarChart2,
+  ChevronLeft,
+  ChevronRight,
+  Eye,
+  GripVertical,
+  LayoutGrid,
+  PieChart,
+  Redo2,
+  Save,
+  Table,
+  Trash2,
+  Type,
+  Undo2,
+  X,
+} from "lucide-react"
+import { useCallback, useId, useMemo, useRef, useState } from "react"
+
+import { cn } from "../../../lib/utils"
+import { TextInput } from "../../forms/TextInput"
+import { Button } from "../../primitives/Button"
+import { Label } from "../../primitives/Label"
+import {
+  dashboardBuilderCanvasVariants,
+  dashboardBuilderEmptyStateVariants,
+  dashboardBuilderPropertiesPanelVariants,
+  dashboardBuilderToolbarVariants,
+  dashboardBuilderVariants,
+  dashboardBuilderWidgetCardVariants,
+  dashboardBuilderWidgetLibraryVariants,
+  dashboardBuilderWidgetVariants,
+} from "./DashboardBuilder.variants"
+
+// ============================================
+// DEFAULT WIDGET DEFINITIONS
+// ============================================
+
+/**
+ * Placeholder widget component for demo purposes
+ */
+function PlaceholderWidget({ config, title }: { config: Record<string, unknown>; title: string }): ReactNode {
+  const value = config["value"]
+  const getDisplayValue = (): string => {
+    if (value === null || value === undefined) return ""
+    if (typeof value === "object") return JSON.stringify(value)
+    return String(value as boolean | number | string)
+  }
+  return (
+    <div className="flex h-full flex-col items-center justify-center p-4">
+      <span className="text-sm font-medium">{title}</span>
+      {value !== undefined && value !== null && (
+        <span className="text-2xl font-bold text-primary">
+          {getDisplayValue()}
+        </span>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Default widgets available in the library
+ */
+const defaultWidgets: BuilderWidgetDefinition[] = [
+  {
+    type: "kpi",
+    name: "KPI Card",
+    description: "Display a key performance indicator",
+    icon: <LayoutGrid className="h-4 w-4" />,
+    category: "kpi",
+    defaultSize: { w: 3, h: 2 },
+    minSize: { w: 2, h: 1 },
+    maxSize: { w: 6, h: 4 },
+    configSchema: {
+      fields: [
+        { name: "title", type: "text", label: "Title", defaultValue: "KPI" },
+        { name: "value", type: "text", label: "Value", defaultValue: "0" },
+        { name: "unit", type: "text", label: "Unit", defaultValue: "" },
+      ],
+    },
+    component: PlaceholderWidget,
+  },
+  {
+    type: "chart-line",
+    name: "Line Chart",
+    description: "Display data as a line chart",
+    icon: <BarChart2 className="h-4 w-4" />,
+    category: "charts",
+    defaultSize: { w: 6, h: 4 },
+    minSize: { w: 4, h: 3 },
+    configSchema: {
+      fields: [
+        { name: "title", type: "text", label: "Title", defaultValue: "Chart" },
+        {
+          name: "showLegend",
+          type: "boolean",
+          label: "Show Legend",
+          defaultValue: true,
+        },
+      ],
+    },
+    component: PlaceholderWidget,
+  },
+  {
+    type: "chart-pie",
+    name: "Pie Chart",
+    description: "Display data as a pie chart",
+    icon: <PieChart className="h-4 w-4" />,
+    category: "charts",
+    defaultSize: { w: 4, h: 4 },
+    minSize: { w: 3, h: 3 },
+    configSchema: {
+      fields: [
+        { name: "title", type: "text", label: "Title", defaultValue: "Chart" },
+      ],
+    },
+    component: PlaceholderWidget,
+  },
+  {
+    type: "table",
+    name: "Data Table",
+    description: "Display data in a table format",
+    icon: <Table className="h-4 w-4" />,
+    category: "tables",
+    defaultSize: { w: 6, h: 4 },
+    minSize: { w: 4, h: 3 },
+    configSchema: {
+      fields: [
+        { name: "title", type: "text", label: "Title", defaultValue: "Table" },
+        {
+          name: "pageSize",
+          type: "number",
+          label: "Page Size",
+          defaultValue: 10,
+        },
+      ],
+    },
+    component: PlaceholderWidget,
+  },
+  {
+    type: "text",
+    name: "Text Block",
+    description: "Display formatted text content",
+    icon: <Type className="h-4 w-4" />,
+    category: "text",
+    defaultSize: { w: 4, h: 2 },
+    minSize: { w: 2, h: 1 },
+    configSchema: {
+      fields: [
+        { name: "content", type: "text", label: "Content", defaultValue: "" },
+      ],
+    },
+    component: PlaceholderWidget,
+  },
+]
+
+// ============================================
+// SUB-COMPONENTS
+// ============================================
+
+/**
+ * Toolbar component with save, undo, redo, and preview actions
+ */
+function DashboardBuilderToolbar({
+  canRedo,
+  canUndo,
+  onRedo,
+  onSave,
+  onTogglePreview,
+  onUndo,
+  showPreview,
+  showUndo,
+}: DashboardBuilderToolbarProps): ReactNode {
+  return (
+    <div
+      className={dashboardBuilderToolbarVariants()}
+      data-slot="dashboard-builder-toolbar"
+    >
+      <div className="flex items-center gap-2">
+        <span className="text-sm font-medium">Dashboard Builder</span>
+      </div>
+
+      <div className="flex items-center gap-2">
+        {showUndo && (
+          <>
+            <Button
+              aria-label="Undo"
+              disabled={!canUndo}
+              size="sm"
+              variant="ghost"
+              onClick={onUndo}
+            >
+              <Undo2 className="h-4 w-4" />
+            </Button>
+            <Button
+              aria-label="Redo"
+              disabled={!canRedo}
+              size="sm"
+              variant="ghost"
+              onClick={onRedo}
+            >
+              <Redo2 className="h-4 w-4" />
+            </Button>
+            <div className="mx-2 h-6 w-px bg-border" />
+          </>
+        )}
+
+        {showPreview && (
+          <Button
+            aria-label="Preview dashboard"
+            size="sm"
+            variant="outline"
+            onClick={onTogglePreview}
+          >
+            <Eye className="mr-2 h-4 w-4" />
+            Preview
+          </Button>
+        )}
+
+        <Button size="sm" onClick={onSave}>
+          <Save className="mr-2 h-4 w-4" />
+          Save
+        </Button>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Widget library sidebar showing available widgets
+ */
+function DashboardBuilderWidgetLibrary({
+  widgets,
+}: DashboardBuilderWidgetLibraryProps): ReactNode {
+  const [collapsed, setCollapsed] = useState(false)
+
+  // Group widgets by category
+  const groupedWidgets = useMemo(() => {
+    return widgets.reduce<Record<string, BuilderWidgetDefinition[]>>((acc, widget) => {
+      const category = widget.category || "default"
+      acc[category] ??= []
+      acc[category].push(widget)
+      return acc
+    }, {})
+  }, [widgets])
+
+  const handleDragStart = (e: DragEvent<HTMLDivElement>, widget: BuilderWidgetDefinition): void => {
+    e.dataTransfer.setData("widget-type", widget.type)
+    e.dataTransfer.effectAllowed = "copy"
+  }
+
+  return (
+    <div
+      className={dashboardBuilderWidgetLibraryVariants({ collapsed })}
+      data-slot="dashboard-builder-widget-library"
+    >
+      <div className="flex h-12 items-center justify-between border-b px-4">
+        {!collapsed && (
+          <span className="text-sm font-medium">Widgets</span>
+        )}
+        <Button
+          aria-label={collapsed ? "Expand widget library" : "Collapse widget library"}
+          className="ml-auto"
+          size="icon"
+          variant="ghost"
+          onClick={() => { setCollapsed(!collapsed); }}
+        >
+          {collapsed ? (
+            <ChevronRight className="h-4 w-4" />
+          ) : (
+            <ChevronLeft className="h-4 w-4" />
+          )}
+        </Button>
+      </div>
+
+      {!collapsed && (
+        <div className="flex-1 overflow-y-auto p-4">
+          <div className="space-y-4">
+            {Object.entries(groupedWidgets).map(([category, categoryWidgets]) => (
+              <div key={category}>
+                <span className="mb-2 block text-xs font-medium uppercase text-muted-foreground">
+                  {category}
+                </span>
+                <div className="space-y-2">
+                  {categoryWidgets.map((widget) => (
+                    <div
+                      key={widget.type}
+                      draggable
+                      className={dashboardBuilderWidgetCardVariants({
+                        category: category as "charts" | "default" | "kpi" | "tables" | "text",
+                      })}
+                      aria-label={`Drag ${widget.name} widget`}
+                      role="button"
+                      tabIndex={0}
+                      title={widget.description}
+                      onDragStart={(e: DragEvent<HTMLDivElement>) => { handleDragStart(e, widget); }}
+                    >
+                      <span className="text-muted-foreground">{widget.icon}</span>
+                      <span className="text-sm">{widget.name}</span>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Canvas component - main work area for widgets
+ */
+function DashboardBuilderCanvas({
+  children,
+  columns,
+  onWidgetDrop,
+  rowHeight,
+  showGrid,
+  widgets,
+}: DashboardBuilderCanvasProps & {
+  children?: ReactNode
+  onWidgetClick?: (id: string) => void
+  onWidgetRemove?: (id: string) => void
+  selectedWidgetId?: null | string
+  widgetDefinitions: BuilderWidgetDefinition[]
+}): ReactNode {
+  const canvasRef = useRef<HTMLDivElement>(null)
+  const [isDragOver, setIsDragOver] = useState(false)
+
+  const handleDragOver = (e: DragEvent<HTMLDivElement>): void => {
+    e.preventDefault()
+    e.dataTransfer.dropEffect = "copy"
+    setIsDragOver(true)
+  }
+
+  const handleDragLeave = (): void => {
+    setIsDragOver(false)
+  }
+
+  const handleDrop = (e: DragEvent<HTMLDivElement>): void => {
+    e.preventDefault()
+    setIsDragOver(false)
+
+    const widgetType = e.dataTransfer.getData("widget-type")
+    if (!widgetType || !canvasRef.current) return
+
+    const rect = canvasRef.current.getBoundingClientRect()
+    const gridWidth = rect.width / columns
+    const x = Math.floor((e.clientX - rect.left) / gridWidth)
+    const y = Math.floor((e.clientY - rect.top) / rowHeight)
+
+    onWidgetDrop?.(widgetType, { x, y })
+  }
+
+  const gridSizeStyle = {
+    "--grid-size": `${String(100 / columns)}%`,
+  } as React.CSSProperties
+
+  return (
+    <div
+      ref={canvasRef}
+      className={cn(
+        dashboardBuilderCanvasVariants({ showGrid }),
+        isDragOver && "ring-2 ring-primary ring-offset-2"
+      )}
+      aria-describedby="canvas-instructions"
+      aria-label="Dashboard canvas"
+      data-slot="dashboard-builder-canvas"
+      role="region"
+      style={gridSizeStyle}
+      onDragLeave={handleDragLeave}
+      onDragOver={handleDragOver}
+      onDrop={handleDrop}
+    >
+      <span className="sr-only" id="canvas-instructions">
+        Drag widgets from the library to add them. Use arrow keys to move selected widgets.
+        Press Delete to remove selected widget.
+      </span>
+
+      {widgets.length === 0 ? (
+        <div className={dashboardBuilderEmptyStateVariants()}>
+          <LayoutGrid className="h-12 w-12 opacity-50" />
+          <div className="text-center">
+            <p className="text-sm font-medium">No widgets yet</p>
+            <p className="text-xs text-muted-foreground">
+              Drag widgets from the library to get started
+            </p>
+          </div>
+        </div>
+      ) : (
+        <div
+          style={{
+            display: "grid",
+            gridTemplateColumns: `repeat(${String(columns)}, 1fr)`,
+            gap: "1rem",
+            minHeight: "100%",
+          }}
+          className="relative"
+        >
+          {children}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Properties panel for configuring selected widget
+ */
+function DashboardBuilderPropertiesPanel({
+  onClose,
+  onConfigChange,
+  widget,
+  widgetDefinition,
+}: DashboardBuilderPropertiesPanelProps): ReactNode {
+  const panelId = useId()
+
+  if (!widget || !widgetDefinition) {
+    return (
+      <div
+        className={dashboardBuilderPropertiesPanelVariants({ open: false })}
+        data-slot="dashboard-builder-properties-panel"
+      />
+    )
+  }
+
+  const handleFieldChange = (fieldName: string, value: unknown): void => {
+    const newConfig = { ...widget.config, [fieldName]: value }
+    onConfigChange?.(newConfig)
+  }
+
+  return (
+    <div
+      aria-labelledby={`${panelId}-title`}
+      className={dashboardBuilderPropertiesPanelVariants({ open: true })}
+      data-slot="dashboard-builder-properties-panel"
+      role="region"
+    >
+      <div className="flex h-12 items-center justify-between border-b px-4">
+        <span className="text-sm font-medium" id={`${panelId}-title`}>
+          Properties
+        </span>
+        <Button
+          aria-label="Close properties panel"
+          size="icon"
+          variant="ghost"
+          onClick={onClose}
+        >
+          <X className="h-4 w-4" />
+        </Button>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-4">
+        <div className="space-y-4">
+          <div>
+            <span className="text-xs font-medium uppercase text-muted-foreground">
+              Widget: {widgetDefinition.name}
+            </span>
+          </div>
+
+          <div className="h-px w-full bg-border" />
+
+          <div className="space-y-4">
+            {widgetDefinition.configSchema.fields.map((field) => (
+              <div key={field.name} className="space-y-2">
+                <Label htmlFor={`${panelId}-${field.name}`}>{field.label}</Label>
+                {field.type === "text" && (
+                  <TextInput
+                    value={(() => {
+                      const val = widget.config[field.name] ?? field.defaultValue ?? ""
+                      if (typeof val === "object") return JSON.stringify(val)
+                      return String(val as boolean | number | string)
+                    })()}
+                    id={`${panelId}-${field.name}`}
+                    onChange={(e: React.ChangeEvent<HTMLInputElement>) => { handleFieldChange(field.name, e.target.value); }}
+                  />
+                )}
+                {field.type === "number" && (
+                  <TextInput
+                    value={(() => {
+                      const val = widget.config[field.name] ?? field.defaultValue ?? 0
+                      if (typeof val === "object") return "0"
+                      return String(val as boolean | number | string)
+                    })()}
+                    id={`${panelId}-${field.name}`}
+                    type="number"
+                    onChange={(e: React.ChangeEvent<HTMLInputElement>) => { handleFieldChange(field.name, Number(e.target.value)); }}
+                  />
+                )}
+                {field.type === "boolean" && (
+                  <input
+                    checked={Boolean(widget.config[field.name] ?? field.defaultValue)}
+                    className="h-4 w-4"
+                    id={`${panelId}-${field.name}`}
+                    type="checkbox"
+                    onChange={(e: React.ChangeEvent<HTMLInputElement>) => { handleFieldChange(field.name, e.target.checked); }}
+                  />
+                )}
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Individual widget component on the canvas
+ */
+function DashboardBuilderWidgetComponent({
+  isDragging,
+  isSelected,
+  onClick,
+  onRemove,
+  widget,
+  widgetDefinition,
+}: DashboardBuilderWidgetComponentProps): ReactNode {
+  const WidgetComponent = widgetDefinition?.component
+
+  const state = isSelected ? "selected" : isDragging ? "dragging" : "idle"
+
+  const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>): void => {
+    if (e.key === "Delete" || e.key === "Backspace") {
+      e.preventDefault()
+      onRemove?.()
+    }
+  }
+
+  return (
+    <div
+      style={{
+        gridColumn: `span ${String(widget.w)}`,
+        gridRow: `span ${String(widget.h)}`,
+        minHeight: `${String(widget.h * 100)}px`,
+      }}
+      aria-label={`Widget: ${widget.title}`}
+      aria-selected={isSelected}
+      className={dashboardBuilderWidgetVariants({ state })}
+      data-slot="dashboard-builder-widget"
+      data-widget-id={widget.id}
+      role="button"
+      tabIndex={0}
+      onClick={onClick}
+      onKeyDown={handleKeyDown}
+    >
+      {/* Widget header */}
+      <div className="flex items-center justify-between border-b bg-muted/50 px-3 py-2">
+        <div className="flex items-center gap-2">
+          <GripVertical className="h-4 w-4 cursor-grab text-muted-foreground" />
+          <span className="text-xs font-medium">{widget.title}</span>
+        </div>
+        <Button
+          aria-label={`Remove ${widget.title}`}
+          className="opacity-0 group-hover:opacity-100"
+          size="icon"
+          variant="ghost"
+          onClick={(e) => {
+            e.stopPropagation()
+            onRemove?.()
+          }}
+        >
+          <Trash2 className="h-3 w-3" />
+        </Button>
+      </div>
+
+      {/* Widget content */}
+      <div className="flex-1 overflow-hidden p-2">
+        {WidgetComponent ? (
+          <WidgetComponent
+            config={widget.config}
+            height={widget.h}
+            id={widget.id}
+            title={widget.title}
+            width={widget.w}
+          />
+        ) : (
+          <div className="flex h-full items-center justify-center text-muted-foreground">
+            <span className="text-xs">Unknown widget type</span>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+// ============================================
+// MAIN COMPONENT
+// ============================================
+
+/**
+ * DashboardBuilder - Visual dashboard construction interface.
+ *
+ * Allows users to create, edit and customize dashboards through a drag-and-drop
+ * interface with a widget library and properties panel.
+ *
+ * @example
+ * ```tsx
+ * <DashboardBuilder
+ *   onSave={({ widgets, layout }) => console.log('Saved:', widgets, layout)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const initialWidgets = [
+ *   { id: '1', type: 'kpi', title: 'Sales', x: 0, y: 0, w: 3, h: 2, config: { value: '150k' } }
+ * ];
+ *
+ * <DashboardBuilder
+ *   initialWidgets={initialWidgets}
+ *   columns={12}
+ *   rowHeight={100}
+ * />
+ * ```
+ */
+function DashboardBuilder({
+  "aria-label": ariaLabel = "Dashboard builder",
+  allowOverlap = false,
+  autoSaveInterval = 30000,
+  availableWidgets = defaultWidgets,
+  className,
+  columns = 12,
+  enableAutoSave = false,
+  initialLayout,
+  initialWidgets = [],
+  mode,
+  onLayoutChange,
+  onPreview,
+  onRedo,
+  onSave,
+  onUndo,
+  onWidgetAdd,
+  onWidgetRemove,
+  onWidgetUpdate,
+  rowHeight = 100,
+  showGrid = true,
+  showPreview = true,
+  showUndo = true,
+  size,
+  snapToGrid = true,
+  ...props
+}: DashboardBuilderProps): ReactNode {
+  const builderId = useId()
+
+  // State
+  const [widgets, setWidgets] = useState<BuilderWidget[]>(initialWidgets)
+  const [selectedWidgetId, setSelectedWidgetId] = useState<null | string>(null)
+  const [_builderMode, setBuilderMode] = useState<BuilderMode>("edit")
+  const [_builderState, setBuilderState] = useState<BuilderState>("idle")
+  const [history, setHistory] = useState<BuilderWidget[][]>([initialWidgets])
+  const [historyIndex, setHistoryIndex] = useState(0)
+
+  // Suppress unused variable warnings for future implementation
+  void snapToGrid
+  void allowOverlap
+  void enableAutoSave
+  void autoSaveInterval
+  void initialLayout
+
+  // Computed
+  const selectedWidget = useMemo(
+    () => widgets.find((w) => w.id === selectedWidgetId) ?? null,
+    [widgets, selectedWidgetId]
+  )
+  const selectedWidgetDefinition = useMemo(
+    () =>
+      selectedWidget
+        ? availableWidgets.find((w) => w.type === selectedWidget.type)
+        : undefined,
+    [selectedWidget, availableWidgets]
+  )
+
+  const canUndo = historyIndex > 0
+  const canRedo = historyIndex < history.length - 1
+
+  // Helpers
+  const updateHistory = useCallback((newWidgets: BuilderWidget[]) => {
+    setHistory((prev) => {
+      const newHistory = prev.slice(0, historyIndex + 1)
+      newHistory.push(newWidgets)
+      return newHistory
+    })
+    setHistoryIndex((prev) => prev + 1)
+  }, [historyIndex])
+
+  const generateId = (): string => `widget-${String(Date.now())}-${Math.random().toString(36).slice(2, 9)}`
+
+  const getLayoutConfig = useCallback((): BuilderLayoutConfig => {
+    return {
+      columns,
+      rowHeight,
+      widgets: widgets.map((w) => ({
+        i: w.id,
+        x: w.x,
+        y: w.y,
+        w: w.w,
+        h: w.h,
+      })),
+    }
+  }, [columns, rowHeight, widgets])
+
+  // Event handlers
+  const handleWidgetDrop = useCallback(
+    (widgetType: string, position: BuilderPosition) => {
+      const definition = availableWidgets.find((w) => w.type === widgetType)
+      if (!definition) return
+
+      const newWidget: BuilderWidget = {
+        id: generateId(),
+        type: widgetType,
+        title: definition.name,
+        x: position.x,
+        y: position.y,
+        w: definition.defaultSize.w,
+        h: definition.defaultSize.h,
+        config: definition.configSchema.fields.reduce<Record<string, unknown>>(
+          (acc, field) => {
+            acc[field.name] = field.defaultValue
+            return acc
+          },
+          {}
+        ),
+      }
+
+      const newWidgets = [...widgets, newWidget]
+      setWidgets(newWidgets)
+      updateHistory(newWidgets)
+      setSelectedWidgetId(newWidget.id)
+
+      onWidgetAdd?.({ widget: newWidget, position })
+      onLayoutChange?.(getLayoutConfig())
+    },
+    [availableWidgets, widgets, updateHistory, onWidgetAdd, onLayoutChange, getLayoutConfig]
+  )
+
+  const handleWidgetRemove = useCallback(
+    (widgetId: string) => {
+      const newWidgets = widgets.filter((w) => w.id !== widgetId)
+      setWidgets(newWidgets)
+      updateHistory(newWidgets)
+
+      if (selectedWidgetId === widgetId) {
+        setSelectedWidgetId(null)
+      }
+
+      onWidgetRemove?.({ widgetId })
+      onLayoutChange?.(getLayoutConfig())
+    },
+    [widgets, selectedWidgetId, updateHistory, onWidgetRemove, onLayoutChange, getLayoutConfig]
+  )
+
+  const handleWidgetSelect = useCallback((widgetId: string) => {
+    setSelectedWidgetId(widgetId)
+    setBuilderState("configuring")
+  }, [])
+
+  const handleConfigChange = useCallback(
+    (newConfig: Record<string, unknown>) => {
+      if (!selectedWidgetId) return
+
+      const newWidgets = widgets.map((w) =>
+        w.id === selectedWidgetId ? { ...w, config: newConfig } : w
+      )
+      setWidgets(newWidgets)
+      updateHistory(newWidgets)
+
+      onWidgetUpdate?.({ widgetId: selectedWidgetId, config: newConfig })
+    },
+    [selectedWidgetId, widgets, updateHistory, onWidgetUpdate]
+  )
+
+  const handleSave = useCallback(() => {
+    setBuilderState("saving")
+    onSave?.({ widgets, layout: getLayoutConfig() })
+    setBuilderState("idle")
+  }, [widgets, getLayoutConfig, onSave])
+
+  const handleUndo = useCallback(() => {
+    if (!canUndo) return
+    const newIndex = historyIndex - 1
+    setHistoryIndex(newIndex)
+    setWidgets(history[newIndex] ?? [])
+    onUndo?.()
+  }, [canUndo, historyIndex, history, onUndo])
+
+  const handleRedo = useCallback(() => {
+    if (!canRedo) return
+    const newIndex = historyIndex + 1
+    setHistoryIndex(newIndex)
+    setWidgets(history[newIndex] ?? [])
+    onRedo?.()
+  }, [canRedo, historyIndex, history, onRedo])
+
+  const handlePreview = useCallback(() => {
+    setBuilderMode("preview")
+    onPreview?.()
+  }, [onPreview])
+
+  const handleCloseProperties = useCallback(() => {
+    setSelectedWidgetId(null)
+    setBuilderState("idle")
+  }, [])
+
+  // Keyboard shortcuts
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLDivElement>) => {
+      // Ctrl/Cmd + S: Save
+      if ((e.ctrlKey || e.metaKey) && e.key === "s") {
+        e.preventDefault()
+        handleSave()
+      }
+      // Ctrl/Cmd + Z: Undo
+      if ((e.ctrlKey || e.metaKey) && e.key === "z" && !e.shiftKey) {
+        e.preventDefault()
+        handleUndo()
+      }
+      // Ctrl/Cmd + Shift + Z or Ctrl/Cmd + Y: Redo
+      if ((e.ctrlKey || e.metaKey) && (e.key === "y" || (e.key === "z" && e.shiftKey))) {
+        e.preventDefault()
+        handleRedo()
+      }
+      // Delete: Remove selected widget
+      if ((e.key === "Delete" || e.key === "Backspace") && selectedWidgetId) {
+        e.preventDefault()
+        handleWidgetRemove(selectedWidgetId)
+      }
+    },
+    [handleSave, handleUndo, handleRedo, selectedWidgetId, handleWidgetRemove]
+  )
+
+  return (
+    <div
+      aria-label={ariaLabel}
+      className={cn(dashboardBuilderVariants({ mode, size }), className)}
+      data-slot="dashboard-builder"
+      id={builderId}
+      role="application"
+      tabIndex={-1}
+      onKeyDown={handleKeyDown}
+      {...props}
+    >
+      {/* Toolbar */}
+      <div className="flex flex-col">
+        <DashboardBuilderToolbar
+          canRedo={canRedo}
+          canUndo={canUndo}
+          showPreview={showPreview}
+          showUndo={showUndo}
+          onRedo={handleRedo}
+          onSave={handleSave}
+          onTogglePreview={handlePreview}
+          onUndo={handleUndo}
+        />
+
+        {/* Main content area */}
+        <div className="flex flex-1 overflow-hidden">
+          {/* Widget Library */}
+          <DashboardBuilderWidgetLibrary widgets={availableWidgets} />
+
+          {/* Canvas */}
+          <div className="flex flex-1 flex-col">
+            <DashboardBuilderCanvas
+              columns={columns}
+              rowHeight={rowHeight}
+              selectedWidgetId={selectedWidgetId}
+              showGrid={showGrid}
+              widgetDefinitions={availableWidgets}
+              widgets={widgets}
+              onWidgetClick={handleWidgetSelect}
+              onWidgetDrop={handleWidgetDrop}
+              onWidgetRemove={handleWidgetRemove}
+            >
+              {widgets.map((widget) => {
+                const definition = availableWidgets.find(
+                  (w) => w.type === widget.type
+                )
+                return (
+                  <DashboardBuilderWidgetComponent
+                    key={widget.id}
+                    isSelected={widget.id === selectedWidgetId}
+                    widget={widget}
+                    widgetDefinition={definition}
+                    onClick={() => { handleWidgetSelect(widget.id); }}
+                    onRemove={() => { handleWidgetRemove(widget.id); }}
+                  />
+                )
+              })}
+            </DashboardBuilderCanvas>
+          </div>
+
+          {/* Properties Panel */}
+          <DashboardBuilderPropertiesPanel
+            widget={selectedWidget}
+            widgetDefinition={selectedWidgetDefinition}
+            onClose={handleCloseProperties}
+            onConfigChange={handleConfigChange}
+          />
+        </div>
+      </div>
+    </div>
+  )
+}
+
+DashboardBuilder.displayName = "DashboardBuilder"
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export {
+  DashboardBuilder,
+  DashboardBuilderCanvas,
+  DashboardBuilderPropertiesPanel,
+  DashboardBuilderToolbar,
+  DashboardBuilderWidgetComponent,
+  DashboardBuilderWidgetLibrary,
+  defaultWidgets,
+}
+export type {
+  DashboardBuilderCanvasProps,
+  DashboardBuilderPropertiesPanelProps,
+  DashboardBuilderProps,
+  DashboardBuilderToolbarProps,
+  DashboardBuilderWidgetComponentProps,
+  DashboardBuilderWidgetLibraryProps,
+}