@startsimpli/ui 0.4.40 → 0.4.43

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.40",
+  "version": "0.4.43",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./catalog": "./src/catalog/index.ts",
     "./table": "./src/components/unified-table/index.ts",
     "./gantt": "./src/components/gantt/index.ts",
     "./gantt/styles": "./src/components/gantt/gantt.css",
@@ -34,7 +35,7 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "0.5.39",
+    "@startsimpli/api": "0.5.42",
     "@startsimpli/auth": "0.4.29"
   },
   "peerDependenciesMeta": {

package/src/catalog/__tests__/catalog.test.ts

@@ -0,0 +1,101 @@
+import {
+  UI_CATALOG,
+  getCatalogEntry,
+  catalogByCategory,
+  builtInWidgets,
+  renderCatalogForPrompt,
+  renderDashboardConfig,
+  widgetsNeedingScaffold,
+} from '../index';
+
+describe('UI_CATALOG', () => {
+  it('has unique ids', () => {
+    const ids = UI_CATALOG.map((e) => e.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('gives every entry the fields the AI builder + scaffolder need', () => {
+    for (const e of UI_CATALOG) {
+      expect(e.id).toMatch(/^[a-z][a-z0-9-]*$/);
+      expect(['widget', 'view', 'component']).toContain(e.category);
+      expect(e.title.length).toBeGreaterThan(0);
+      expect(e.description.length).toBeGreaterThan(0);
+      expect(e.dataNeeds.length).toBeGreaterThan(0);
+      expect(e.source.export.length).toBeGreaterThan(0);
+      expect(e.source.from.startsWith('@startsimpli/ui')).toBe(true);
+    }
+  });
+
+  it('exposes the five template built-in widgets as config-only widgets', () => {
+    const builtIns = builtInWidgets().map((e) => e.id).sort();
+    expect(builtIns).toEqual(['metrics', 'pipeline', 'quick-create', 'recent', 'type-grid']);
+    for (const e of builtInWidgets()) expect(e.category).toBe('widget');
+  });
+
+  it('built-in widgets ship an example config whose kind matches their id', () => {
+    for (const e of builtInWidgets()) {
+      expect(e.configExample).toBeDefined();
+      expect(e.configExample!.kind).toBe(e.id);
+    }
+  });
+
+  it('flags heavy blocks so the AI can avoid them by default', () => {
+    // The bundle-costly ones (dnd/xlsx/calendar/gantt) must be marked heavy.
+    for (const id of ['kanban-board', 'data-table', 'calendar', 'gantt']) {
+      expect(getCatalogEntry(id)?.heavy).toBe(true);
+    }
+    // The lightweight defaults must NOT be heavy.
+    for (const id of ['metrics', 'quick-create', 'recent', 'type-grid']) {
+      expect(getCatalogEntry(id)?.heavy).toBeFalsy();
+    }
+  });
+
+  it('renderCatalogForPrompt lists every block with its heavy/built-in flags', () => {
+    const text = renderCatalogForPrompt();
+    for (const e of UI_CATALOG) expect(text).toContain(e.id);
+    expect(text).toContain('⚠ heavy');
+    expect(text).toContain('built-in');
+    expect(text).toContain('scaffolded');
+  });
+
+  it('catalogByCategory partitions the catalog', () => {
+    const total =
+      catalogByCategory('widget').length +
+      catalogByCategory('view').length +
+      catalogByCategory('component').length;
+    expect(total).toBe(UI_CATALOG.length);
+  });
+});
+
+describe('renderDashboardConfig', () => {
+  it('renders a valid foundry.dashboard.ts for known widgets', () => {
+    const r = renderDashboardConfig([
+      { kind: 'metrics', title: 'Overview' },
+      { kind: 'pipeline', type: 'topic', title: 'Pipeline' },
+      { kind: 'recent', limit: 8 },
+    ]);
+    expect(r.ok).toBe(true);
+    expect(r.errors).toEqual([]);
+    expect(r.file?.path).toBe('src/foundry.dashboard.ts');
+    expect(r.file?.content).toContain('export const dashboard: DashboardConfig = [');
+    expect(r.file?.content).toContain('"kind":"metrics"');
+    expect(r.file?.content).toContain('"type":"topic"');
+    expect(r.file?.content).toContain("import type { DashboardConfig } from '@/components/dashboard/config'");
+  });
+
+  it('rejects an unknown widget kind (never writes a config the app cannot render)', () => {
+    const r = renderDashboardConfig([{ kind: 'metrics' }, { kind: 'teleporter' }]);
+    expect(r.ok).toBe(false);
+    expect(r.file).toBeUndefined();
+    expect(r.errors.join(' ')).toContain('teleporter');
+  });
+
+  it('rejects an empty layout', () => {
+    expect(renderDashboardConfig([]).ok).toBe(false);
+  });
+
+  it('flags chosen widgets that are not built into the template', () => {
+    expect(widgetsNeedingScaffold([{ kind: 'metrics' }, { kind: 'kanban-board' }])).toEqual(['kanban-board']);
+    expect(widgetsNeedingScaffold([{ kind: 'metrics' }, { kind: 'recent' }])).toEqual([]);
+  });
+});

package/src/catalog/catalog.ts

@@ -0,0 +1,138 @@
+import type { CatalogEntry } from './types';
+
+/**
+ * The curated Foundry app-UI catalog. Order is roughly "reach for these first" →
+ * heavier/nicher last. Keep it small and honest: every entry must be genuinely
+ * useful in a data-driven tenant app and cheap to explain to a non-technical
+ * owner. `builtIn` blocks ship in the template today; the rest are scaffolded in
+ * on demand so the base template stays thin.
+ */
+export const UI_CATALOG: CatalogEntry[] = [
+  {
+    id: 'metrics',
+    category: 'widget',
+    title: 'Metrics row',
+    description:
+      'A row of big-number tiles, one per entity type, each linking to its section. The default at-a-glance overview — good on almost every app.',
+    dataNeeds: 'Any types (uses record counts).',
+    builtIn: true,
+    source: { export: 'MetricCard', from: '@startsimpli/ui' },
+    configExample: { kind: 'metrics', title: 'Overview' },
+  },
+  {
+    id: 'quick-create',
+    category: 'widget',
+    title: 'Quick add',
+    description:
+      'One-click "New <type>" buttons that open the create form in a dialog. The fast path from an empty app to its first records.',
+    dataNeeds: 'Any types.',
+    builtIn: true,
+    source: { export: 'BaseDialog', from: '@startsimpli/ui' },
+    configExample: { kind: 'quick-create', title: 'Quick add' },
+  },
+  {
+    id: 'pipeline',
+    category: 'widget',
+    title: 'Pipeline funnel',
+    description:
+      'A funnel of one type\'s records across the stages of its status field, with per-stage counts and conversion. Best for a clear forward workflow (e.g. lead → won). Reads oddly for branch statuses like "rejected".',
+    dataNeeds: 'A type with a status/enum field whose stages flow forward.',
+    builtIn: true,
+    source: { export: 'PipelineFunnel', from: '@startsimpli/ui' },
+    configExample: { kind: 'pipeline', type: '<typeKey>', title: 'Pipeline' },
+  },
+  {
+    id: 'recent',
+    category: 'widget',
+    title: 'Recent activity',
+    description:
+      'A live feed of the most recently created records — across all types or one — with type badges and relative timestamps.',
+    dataNeeds: 'Any types (uses created_at).',
+    builtIn: true,
+    source: { export: 'Card', from: '@startsimpli/ui' },
+    configExample: { kind: 'recent', limit: 8, title: 'Recent activity' },
+  },
+  {
+    id: 'type-grid',
+    category: 'widget',
+    title: 'Section cards',
+    description:
+      'The classic per-type card grid: count + status breakdown, each card links into its section. A compact index of the whole app.',
+    dataNeeds: 'Any types.',
+    builtIn: true,
+    source: { export: 'Card', from: '@startsimpli/ui' },
+    configExample: { kind: 'type-grid', title: 'All sections' },
+  },
+  {
+    id: 'kanban-board',
+    category: 'widget',
+    title: 'Kanban board preview',
+    description:
+      'A drag-to-move board that lays a status type\'s records into lanes. Use as a home widget for the primary workflow type, or as the full section for it.',
+    dataNeeds: 'A type with a status/enum field.',
+    heavy: true,
+    source: { export: 'KanbanBoard', from: '@startsimpli/ui' },
+    configExample: { kind: 'kanban-board', type: '<typeKey>', title: 'Board' },
+  },
+  {
+    id: 'data-table',
+    category: 'view',
+    title: 'Data table',
+    description:
+      'An enterprise table for one type — sortable columns, column picker, server pagination, Excel export. Use for dense list types the owner scans and exports.',
+    dataNeeds: 'Any type (renders its fields as columns).',
+    heavy: true,
+    source: { export: 'UnifiedTable', from: '@startsimpli/ui/table' },
+    configExample: { kind: 'data-table', type: '<typeKey>', title: 'Records' },
+  },
+  {
+    id: 'calendar',
+    category: 'view',
+    title: 'Calendar',
+    description:
+      'A month/week calendar of a type\'s records placed by one of its date fields. Use for anything time-anchored — events, posts, deadlines.',
+    dataNeeds: 'A type with a date field.',
+    heavy: true,
+    source: { export: 'CalendarView', from: '@startsimpli/ui' },
+    configExample: { kind: 'calendar', type: '<typeKey>', dateField: '<fieldName>', title: 'Calendar' },
+  },
+  {
+    id: 'gantt',
+    category: 'view',
+    title: 'Gantt timeline',
+    description:
+      'A timeline of records with start/end dates as bars, with board and timeline modes. Use for scheduling/project types spanning ranges.',
+    dataNeeds: 'A type with a start-date and an end-date field.',
+    heavy: true,
+    source: { export: 'GanttChart', from: '@startsimpli/ui/gantt' },
+    configExample: { kind: 'gantt', type: '<typeKey>', startField: '<start>', endField: '<end>', title: 'Timeline' },
+  },
+  {
+    id: 'metric-trend',
+    category: 'widget',
+    title: 'Trend metric',
+    description:
+      'A single metric tile with a sparkline and up/down trend. Use to headline one number that matters (this week\'s new records, a running total).',
+    dataNeeds: 'Any type, or a numeric field tracked over time.',
+    source: { export: 'MetricCard', from: '@startsimpli/ui' },
+    configExample: { kind: 'metric-trend', type: '<typeKey>', title: 'This week' },
+  },
+  {
+    id: 'command-palette',
+    category: 'component',
+    title: 'Command palette',
+    description:
+      'A ⌘K global search/jump over the app\'s sections and records. An app-shell add-on, not a home widget — enable it once for the whole app.',
+    dataNeeds: 'Any types.',
+    source: { export: 'CommandPalette', from: '@startsimpli/ui' },
+  },
+  {
+    id: 'chat',
+    category: 'component',
+    title: 'Chat thread',
+    description:
+      'A threaded message view with a composer and attachments. Use only when the app genuinely models conversations (a messages type with a thread). Niche — do not add by default.',
+    dataNeeds: 'A messages/thread type.',
+    source: { export: 'ChatThread', from: '@startsimpli/ui' },
+  },
+];

package/src/catalog/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Foundry app-UI catalog — public surface.
+ *
+ * Import from `@startsimpli/ui/catalog` (a pure-data subpath; no component code).
+ * The AI app builder uses `renderCatalogForPrompt()` to "see" what it can build;
+ * `getCatalogEntry`/`UI_CATALOG` back the scaffolder and any component picker UI.
+ */
+export { UI_CATALOG } from './catalog';
+export type { CatalogEntry, CatalogCategory, ScaffoldFile } from './types';
+export {
+  renderDashboardConfig,
+  widgetsNeedingScaffold,
+  type DashboardWidgetConfig,
+  type RenderResult,
+} from './scaffold';
+
+import { UI_CATALOG } from './catalog';
+import type { CatalogCategory, CatalogEntry } from './types';
+
+/** Look up one block by id (the foundry.dashboard.ts `kind` for widgets). */
+export function getCatalogEntry(id: string): CatalogEntry | undefined {
+  return UI_CATALOG.find((e) => e.id === id);
+}
+
+/** All blocks in a category. */
+export function catalogByCategory(category: CatalogCategory): CatalogEntry[] {
+  return UI_CATALOG.filter((e) => e.category === category);
+}
+
+/** The blocks the base template already ships (config-only, no scaffolding). */
+export function builtInWidgets(): CatalogEntry[] {
+  return UI_CATALOG.filter((e) => e.builtIn);
+}
+
+/**
+ * A compact, token-frugal rendering of the catalog for an LLM system prompt: one
+ * line per block — id, category, a ⚠ heavy marker, what it needs, and the gist.
+ * Deterministic (catalog order) so prompts stay cache-stable.
+ */
+export function renderCatalogForPrompt(): string {
+  const line = (e: CatalogEntry) => {
+    const flags = [e.builtIn ? 'built-in' : 'scaffolded', e.heavy ? '⚠ heavy' : null]
+      .filter(Boolean)
+      .join(', ');
+    return `- ${e.id} (${e.category}${flags ? `; ${flags}` : ''}) — ${e.title}: ${e.description} Needs: ${e.dataNeeds}`;
+  };
+  return UI_CATALOG.map(line).join('\n');
+}

package/src/catalog/scaffold.ts

@@ -0,0 +1,64 @@
+/**
+ * Fork-authoring helpers: turn a chosen set of catalog blocks into the concrete
+ * files that go into a tenant's forked app repo. The AI app builder calls these
+ * to produce a reviewable change (applied as a PR), so the base template stays
+ * thin — only what's chosen lands in a fork.
+ *
+ * Today: `renderDashboardConfig` writes the home layout (foundry.dashboard.ts)
+ * from built-in widgets. Per-component scaffolding of heavier blocks (calendar,
+ * gantt, …) layers on next, emitting additional ScaffoldFiles.
+ */
+import { UI_CATALOG } from './catalog';
+import type { ScaffoldFile } from './types';
+
+/** One home widget: a catalog widget id + its per-widget params (type, title…). */
+export interface DashboardWidgetConfig {
+  kind: string;
+  [param: string]: unknown;
+}
+
+const WIDGET_IDS = new Set(UI_CATALOG.filter((e) => e.category === 'widget').map((e) => e.id));
+
+/** Which of the chosen widgets are NOT built into the base template (need scaffolding). */
+export function widgetsNeedingScaffold(widgets: DashboardWidgetConfig[]): string[] {
+  const builtIn = new Set(UI_CATALOG.filter((e) => e.builtIn).map((e) => e.id));
+  return [...new Set(widgets.map((w) => w.kind))].filter((k) => WIDGET_IDS.has(k) && !builtIn.has(k));
+}
+
+export interface RenderResult {
+  ok: boolean;
+  /** Unknown/invalid widget kinds — the AI should fix these before applying. */
+  errors: string[];
+  file?: ScaffoldFile;
+}
+
+/**
+ * Render `src/foundry.dashboard.ts` for the given home layout. Validates each
+ * widget `kind` against the catalog's widget blocks; an unknown kind fails the
+ * whole render (so we never write a config referencing a widget the app can't
+ * render). Serializes params as a plain literal — valid TS the owner can hand-edit.
+ */
+export function renderDashboardConfig(widgets: DashboardWidgetConfig[]): RenderResult {
+  const errors: string[] = [];
+  if (widgets.length === 0) errors.push('layout is empty — choose at least one widget');
+  for (const w of widgets) {
+    if (!w.kind) errors.push('a widget is missing its "kind"');
+    else if (!WIDGET_IDS.has(w.kind)) errors.push(`unknown widget kind "${w.kind}"`);
+  }
+  if (errors.length > 0) return { ok: false, errors };
+
+  const body = widgets.map((w) => `  ${JSON.stringify(w)},`).join('\n');
+  const content = `/**
+ * Your app's home, as data. Generated by the Foundry app builder — safe to
+ * hand-edit. Each entry is a widget (see components/dashboard for the registry);
+ * add/remove/reorder them, or set this to 'auto' to derive a layout from your
+ * schema. Widget shapes live in components/dashboard/config.
+ */
+import type { DashboardConfig } from '@/components/dashboard/config';
+
+export const dashboard: DashboardConfig = [
+${body}
+];
+`;
+  return { ok: true, errors: [], file: { path: 'src/foundry.dashboard.ts', content } };
+}

package/src/catalog/types.ts

@@ -0,0 +1,65 @@
+/**
+ * The Foundry app-UI component catalog (startsim app-builder).
+ *
+ * A curated, machine-readable index of the @startsimpli/ui building blocks a
+ * Foundry tenant app can use on its home / sections — the surface the AI app
+ * builder reads to decide what to compose, and the source of truth for how each
+ * gets scaffolded into a tenant's forked repo.
+ *
+ * This module is PURE DATA (no React imports) so it's cheap to pull into an LLM
+ * route or a Node scaffolder without dragging component code. The heavy, curated
+ * catalog is deliberately SMALL — the ~dozen blocks that make sense in a
+ * data-driven tenant app, not the ~300 exports of the kit. The AI is told to
+ * reach past it only when asked.
+ */
+
+/**
+ * How a block is used in a tenant app:
+ * - `widget`: a home-dashboard block, referenced by `kind` in foundry.dashboard.ts.
+ * - `view`:   a full section/page for one entity type (board, table, calendar…).
+ * - `component`: an app-shell/embeddable primitive (command palette, chat…).
+ */
+export type CatalogCategory = 'widget' | 'view' | 'component';
+
+export interface CatalogEntry {
+  /** Stable id. For widgets this IS the foundry.dashboard.ts `kind`. */
+  id: string;
+  category: CatalogCategory;
+  /** Human title shown to the owner. */
+  title: string;
+  /** What it is + when to reach for it — written for the AI builder to reason over. */
+  description: string;
+  /**
+   * The schema shape this block wants, in one plain phrase (e.g. "a type with a
+   * status/enum field", "a type with a date field"). The AI only offers a block
+   * when the tenant's live schema satisfies this.
+   */
+  dataNeeds: string;
+  /**
+   * Pulls a big transitive dependency (calendar, kanban dnd, xlsx, gantt). The AI
+   * is instructed to avoid heavy blocks unless the user explicitly asks — this is
+   * how "don't just throw every component in" is enforced at the catalog level.
+   */
+  heavy?: boolean;
+  /**
+   * Already shipped in the base template's widget registry — configuring it needs
+   * only a foundry.dashboard.ts entry (no new files). Absent = must be scaffolded
+   * into the fork on demand (keeps the base template thin).
+   */
+  builtIn?: boolean;
+  /** Where the underlying component comes from, for a scaffolded wrapper's import. */
+  source: { export: string; from: string };
+  /**
+   * An example foundry.dashboard.ts entry for this block, so the AI emits valid
+   * config. `kind` matches `id` for widgets.
+   */
+  configExample?: Record<string, unknown>;
+}
+
+/** A block plus the concrete files to add to a fork to enable it (scaffolding). */
+export interface ScaffoldFile {
+  /** Repo-relative path within the tenant fork, e.g. src/components/dashboard/calendar-widget.tsx */
+  path: string;
+  /** Full file contents. */
+  content: string;
+}

package/src/components/kanban/KanbanBoard.tsx

@@ -1,6 +1,12 @@
 'use client'
 
 import * as React from 'react'
+import {
+  DragDropContext,
+  Droppable,
+  Draggable,
+  type DropResult,
+} from '@hello-pangea/dnd'
 import { cn } from '../../lib/utils'
 
 export interface KanbanColumnConfig {
@@ -9,6 +15,36 @@ export interface KanbanColumnConfig {
   color?: string
 }
 
+/** A resolved card move derived from a drag, in board terms (not DnD terms). */
+export interface KanbanMove {
+  cardId: string
+  fromColumnId: string
+  toColumnId: string
+  toIndex: number
+}
+
+/**
+ * Pure resolver: turn a @hello-pangea/dnd DropResult into a KanbanMove, or null
+ * when the drag is a no-op (dropped outside any column, or back onto the same slot).
+ * Exported so consumers and tests can reason about a move without a DOM.
+ */
+export function resolveKanbanMove(result: DropResult): KanbanMove | null {
+  const { draggableId, source, destination } = result
+  if (!destination) return null
+  if (
+    source.droppableId === destination.droppableId &&
+    source.index === destination.index
+  ) {
+    return null
+  }
+  return {
+    cardId: draggableId,
+    fromColumnId: source.droppableId,
+    toColumnId: destination.droppableId,
+    toIndex: destination.index,
+  }
+}
+
 export interface KanbanBoardProps<T> {
   columns: KanbanColumnConfig[]
   items: Record<string, T[]>
@@ -20,6 +56,15 @@ export interface KanbanBoardProps<T> {
   columnRef?: (columnId: string) => React.Ref<HTMLDivElement> | undefined
   isColumnOver?: (columnId: string) => boolean
   className?: string
+  /**
+   * DnD (opt-in). Provide BOTH `getCardId` and `onCardMove` to make cards draggable
+   * between columns via @hello-pangea/dnd — all drag mechanics live here in
+   * @startsimpli/ui; consumers stay dnd-agnostic and just persist the move in
+   * `onCardMove`. Omit either and the board renders exactly as before (no DnD;
+   * `columnRef`/`isColumnOver` honored for a parent's own manual wiring).
+   */
+  getCardId?: (item: T) => string
+  onCardMove?: (move: KanbanMove) => void
 }
 
 export function KanbanBoard<T>({
@@ -33,71 +78,135 @@ export function KanbanBoard<T>({
   columnRef,
   isColumnOver,
   className,
+  getCardId,
+  onCardMove,
 }: KanbanBoardProps<T>) {
-  return (
-    <div className={cn('flex gap-4 overflow-x-auto pb-4', className)}>
-      {columns.map((column) => {
-        const columnItems = items[column.id] ?? []
-        const ref = columnRef?.(column.id)
-        const isOver = isColumnOver?.(column.id) ?? false
+  const dndEnabled = !!(getCardId && onCardMove)
 
-        return (
-          <div
-            key={column.id}
-            ref={ref}
-            style={{ minWidth: columnWidth, maxWidth: columnWidth }}
-            className={cn(
-              'flex flex-col rounded-lg border bg-muted/50 transition-colors',
-              isOver && 'border-primary ring-2 ring-primary/20',
-            )}
-          >
-            {/* Column Header */}
-            {renderColumnHeader ? (
-              renderColumnHeader(column, columnItems)
-            ) : (
-              <div className="flex items-center justify-between px-3 py-2 border-b">
-                <div className="flex items-center gap-2">
-                  {column.color && (
-                    <span
-                      className="w-2.5 h-2.5 rounded-full shrink-0"
-                      style={{ backgroundColor: column.color }}
-                      aria-hidden="true"
-                    />
-                  )}
-                  <h3 className="text-sm font-semibold text-foreground truncate">
-                    {column.label}
-                  </h3>
-                </div>
-                <span className="inline-flex items-center justify-center rounded-full bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground">
-                  {columnItems.length}
-                </span>
-              </div>
-            )}
+  const handleDragEnd = React.useCallback(
+    (result: DropResult) => {
+      const move = resolveKanbanMove(result)
+      if (move) onCardMove?.(move)
+    },
+    [onCardMove],
+  )
+
+  const columnHeader = (column: KanbanColumnConfig, columnItems: T[]) =>
+    renderColumnHeader ? (
+      renderColumnHeader(column, columnItems)
+    ) : (
+      <div className="flex items-center justify-between px-3 py-2 border-b">
+        <div className="flex items-center gap-2">
+          {column.color && (
+            <span
+              className="w-2.5 h-2.5 rounded-full shrink-0"
+              style={{ backgroundColor: column.color }}
+              aria-hidden="true"
+            />
+          )}
+          <h3 className="text-sm font-semibold text-foreground truncate">
+            {column.label}
+          </h3>
+        </div>
+        <span className="inline-flex items-center justify-center rounded-full bg-muted px-2 py-0.5 text-xs font-medium text-muted-foreground">
+          {columnItems.length}
+        </span>
+      </div>
+    )
+
+  const emptyState = (
+    <p className="text-xs text-muted-foreground text-center py-8">
+      {emptyColumnMessage}
+    </p>
+  )
 
-            {/* Column Body */}
-            <div className="flex-1 overflow-y-auto p-2 space-y-2">
-              {columnItems.length === 0 ? (
-                <p className="text-xs text-muted-foreground text-center py-8">
-                  {emptyColumnMessage}
-                </p>
-              ) : (
-                columnItems.map((item, index) => (
-                  <React.Fragment key={index}>
-                    {renderCard(item)}
-                  </React.Fragment>
-                ))
-              )}
-            </div>
+  const renderColumn = (column: KanbanColumnConfig) => {
+    const columnItems = items[column.id] ?? []
+    const footer = renderColumnFooter && (
+      <div className="border-t px-3 py-2">{renderColumnFooter(column)}</div>
+    )
 
-            {/* Column Footer */}
-            {renderColumnFooter && (
-              <div className="border-t px-3 py-2">
-                {renderColumnFooter(column)}
+    if (dndEnabled) {
+      return (
+        <div
+          key={column.id}
+          style={{ minWidth: columnWidth, maxWidth: columnWidth }}
+          className="flex flex-col rounded-lg border bg-muted/50 transition-colors"
+        >
+          {columnHeader(column, columnItems)}
+          <Droppable droppableId={column.id}>
+            {(provided, snapshot) => (
+              <div
+                ref={provided.innerRef}
+                {...provided.droppableProps}
+                className={cn(
+                  'flex-1 overflow-y-auto p-2 space-y-2 transition-colors',
+                  snapshot.isDraggingOver && 'bg-primary/5',
+                )}
+              >
+                {columnItems.length === 0 && !snapshot.isDraggingOver
+                  ? emptyState
+                  : columnItems.map((item, index) => {
+                      const id = getCardId!(item)
+                      return (
+                        <Draggable key={id} draggableId={id} index={index}>
+                          {(dp, ds) => (
+                            <div
+                              ref={dp.innerRef}
+                              {...dp.draggableProps}
+                              {...dp.dragHandleProps}
+                              className={cn(ds.isDragging && 'opacity-80')}
+                            >
+                              {renderCard(item)}
+                            </div>
+                          )}
+                        </Draggable>
+                      )
+                    })}
+                {provided.placeholder}
               </div>
             )}
-          </div>
-        )
-      })}
+          </Droppable>
+          {footer}
+        </div>
+      )
+    }
+
+    // Non-DnD (backward compatible): honor columnRef/isColumnOver for a parent's own
+    // manual drag wiring, render cards keyed by index as before.
+    const ref = columnRef?.(column.id)
+    const isOver = isColumnOver?.(column.id) ?? false
+    return (
+      <div
+        key={column.id}
+        ref={ref}
+        style={{ minWidth: columnWidth, maxWidth: columnWidth }}
+        className={cn(
+          'flex flex-col rounded-lg border bg-muted/50 transition-colors',
+          isOver && 'border-primary ring-2 ring-primary/20',
+        )}
+      >
+        {columnHeader(column, columnItems)}
+        <div className="flex-1 overflow-y-auto p-2 space-y-2">
+          {columnItems.length === 0
+            ? emptyState
+            : columnItems.map((item, index) => (
+                <React.Fragment key={index}>{renderCard(item)}</React.Fragment>
+              ))}
+        </div>
+        {footer}
+      </div>
+    )
+  }
+
+  const board = (
+    <div className={cn('flex gap-4 overflow-x-auto pb-4', className)}>
+      {columns.map(renderColumn)}
     </div>
   )
+
+  if (dndEnabled) {
+    return <DragDropContext onDragEnd={handleDragEnd}>{board}</DragDropContext>
+  }
+  return board
 }

package/src/components/kanban/__tests__/kanban.test.tsx

@@ -1,5 +1,6 @@
 import { render, screen } from '@testing-library/react'
-import { KanbanBoard } from '../KanbanBoard'
+import type { DropResult } from '@hello-pangea/dnd'
+import { KanbanBoard, resolveKanbanMove } from '../KanbanBoard'
 
 interface Card {
   id: string
@@ -154,4 +155,66 @@ describe('KanbanBoard', () => {
     const firstCol = container.querySelector('[style*="320"]')
     expect(firstCol).toHaveClass('ring-2')
   })
+
+  it('renders draggable cards when getCardId + onCardMove are provided (DnD enabled)', () => {
+    const onCardMove = jest.fn()
+    render(
+      <KanbanBoard
+        columns={columns}
+        items={items}
+        renderCard={renderCard}
+        getCardId={(c) => c.id}
+        onCardMove={onCardMove}
+      />
+    )
+    // cards still render through the @hello-pangea/dnd path without crashing
+    expect(screen.getByTestId('card-1')).toBeInTheDocument()
+    expect(screen.getByTestId('card-3')).toBeInTheDocument()
+    expect(screen.getByText('To Do')).toBeInTheDocument()
+  })
+})
+
+describe('resolveKanbanMove', () => {
+  const drop = (
+    draggableId: string,
+    from: string,
+    fromIndex: number,
+    to?: string,
+    toIndex?: number,
+  ): DropResult =>
+    ({
+      draggableId,
+      type: 'DEFAULT',
+      source: { droppableId: from, index: fromIndex },
+      destination: to === undefined ? null : { droppableId: to, index: toIndex ?? 0 },
+      reason: 'DROP',
+      mode: 'FLUID',
+      combine: null,
+    } as unknown as DropResult)
+
+  it('resolves a cross-column move', () => {
+    expect(resolveKanbanMove(drop('c1', 'new', 0, 'surfaced', 2))).toEqual({
+      cardId: 'c1',
+      fromColumnId: 'new',
+      toColumnId: 'surfaced',
+      toIndex: 2,
+    })
+  })
+
+  it('returns null when dropped outside any column', () => {
+    expect(resolveKanbanMove(drop('c1', 'new', 0))).toBeNull()
+  })
+
+  it('returns null when dropped back onto the same slot', () => {
+    expect(resolveKanbanMove(drop('c1', 'new', 1, 'new', 1))).toBeNull()
+  })
+
+  it('resolves a within-column reorder', () => {
+    expect(resolveKanbanMove(drop('c1', 'new', 0, 'new', 3))).toEqual({
+      cardId: 'c1',
+      fromColumnId: 'new',
+      toColumnId: 'new',
+      toIndex: 3,
+    })
+  })
 })

package/src/components/kanban/index.ts

@@ -1,2 +1,2 @@
-export { KanbanBoard } from './KanbanBoard'
-export type { KanbanBoardProps, KanbanColumnConfig } from './KanbanBoard'
+export { KanbanBoard, resolveKanbanMove } from './KanbanBoard'
+export type { KanbanBoardProps, KanbanColumnConfig, KanbanMove } from './KanbanBoard'