@joewinke/jatui 0.1.0 → 0.1.1

package/src/lib/components/pipeline/DESIGN.md

@@ -0,0 +1,361 @@
+# Pipeline Component API Design
+
+Component prop signatures for `<Pipeline>`, `<PipelineColumn>`, `<PipelineCard>`.
+Types are defined in `src/lib/types/pipeline.ts`.
+
+## Component Hierarchy
+
+```
+<Pipeline>                    ← Top-level: metrics bar, view toggle, columns layout
+  <PipelineColumn>            ← Per-stage column: header, drop zone, card list
+    <PipelineCard>            ← Per-item card: default layout + custom snippet
+```
+
+Consumers typically only use `<Pipeline>` directly. The sub-components are exported
+for advanced layouts but `<Pipeline>` renders them internally by default.
+
+---
+
+## `<Pipeline>`
+
+The main entry point. Accepts items + stages, handles grouping, filtering, view toggle, and drag-drop orchestration.
+
+```svelte
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type {
+    PipelineStage,
+    PipelineItem,
+    PipelineMetric,
+    PipelineConfig,
+    PipelineStageChangeEvent,
+    PipelineItemClickEvent,
+    PipelineViewMode
+  } from '$lib/types/pipeline';
+
+  interface Props {
+    /** Array of stage definitions (columns). Order determines display order. */
+    stages: PipelineStage[];
+    /** All items across all stages. Grouped by item.stageId internally. */
+    items: PipelineItem[];
+    /** Pipeline-wide metrics displayed above the board */
+    metrics?: PipelineMetric[];
+    /** Configuration overrides (views, drag, collapsible, etc.) */
+    config?: Partial<PipelineConfig>;
+
+    // ─── View State (bindable) ───
+    /** Current view mode. Bindable for external control. */
+    viewMode?: PipelineViewMode;
+    /** Set of collapsed stage IDs. Bindable. */
+    collapsedStages?: Set<string>;
+
+    // ─── Events ───
+    /** Fired after drag-drop completes (optimistic). Return a promise; rejection reverts. */
+    onStageChange?: (event: PipelineStageChangeEvent) => Promise<void>;
+    /** Fired when a card is clicked */
+    onItemClick?: (event: PipelineItemClickEvent) => void;
+
+    // ─── Snippets (card customization) ───
+    /** Custom card body. Receives { item, stage }. Falls back to default PipelineCard. */
+    card?: Snippet<[{ item: PipelineItem; stage: PipelineStage }]>;
+    /** Custom column header. Receives { stage, count, totalValue }. */
+    columnHeader?: Snippet<[{ stage: PipelineStage; count: number; totalValue: number }]>;
+    /** Custom empty state per column. Receives { stage }. */
+    emptyState?: Snippet<[{ stage: PipelineStage }]>;
+
+    // ─── Styling ───
+    class?: string;
+  }
+
+  let {
+    stages,
+    items,
+    metrics,
+    config,
+    viewMode = $bindable('kanban'),
+    collapsedStages = $bindable(new Set()),
+    onStageChange,
+    onItemClick,
+    card,
+    columnHeader,
+    emptyState,
+    class: className
+  }: Props = $props();
+</script>
+```
+
+### Usage Example
+
+```svelte
+<script>
+  import { Pipeline } from '@joewinke/jatui';
+
+  const stages = [
+    { id: 'new', label: 'New', order: 0, semantic: 'info' },
+    { id: 'qualified', label: 'Qualified', order: 1, color: 'oklch(0.70 0.18 240)' },
+    { id: 'won', label: 'Won', order: 2, semantic: 'success' },
+  ];
+
+  let items = $state([...]);
+
+  async function handleStageChange(e) {
+    await fetch(`/api/items/${e.itemId}/stage`, {
+      method: 'PATCH',
+      body: JSON.stringify({ stage: e.toStageId })
+    });
+  }
+</script>
+
+<Pipeline {stages} {items} onStageChange={handleStageChange}>
+  {#snippet card({ item, stage })}
+    <div class="font-bold">{item.title}</div>
+    <div class="text-sm opacity-60">{item.meta?.clientName}</div>
+  {/snippet}
+</Pipeline>
+```
+
+---
+
+## `<PipelineColumn>`
+
+A single stage column. Rendered by `<Pipeline>` internally but exported for custom layouts.
+
+```svelte
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import type { PipelineStage, PipelineItem, StageColors, PipelineDragConfig } from '$lib/types/pipeline';
+
+  interface Props {
+    stage: PipelineStage;
+    items: PipelineItem[];
+    colors: StageColors;
+    /** Drag-drop config (passed down from Pipeline) */
+    drag?: PipelineDragConfig;
+    /** Whether column is collapsed */
+    collapsed?: boolean;
+    /** Min-height in px */
+    minHeight?: number;
+
+    // ─── Events ───
+    onToggleCollapse?: () => void;
+    /** svelte-dnd-action consider handler */
+    onDndConsider?: (e: CustomEvent) => void;
+    /** svelte-dnd-action finalize handler */
+    onDndFinalize?: (e: CustomEvent) => void;
+    onItemClick?: (item: PipelineItem) => void;
+
+    // ─── Snippets ───
+    /** Custom header content */
+    header?: Snippet<[{ stage: PipelineStage; count: number; totalValue: number }]>;
+    /** Custom card rendering */
+    card?: Snippet<[{ item: PipelineItem; stage: PipelineStage }]>;
+    /** Custom empty state */
+    emptyState?: Snippet<[{ stage: PipelineStage }]>;
+
+    class?: string;
+  }
+</script>
+```
+
+### Internal Structure
+
+```
+┌─────────────────────────────┐
+│ [icon] Stage Label    [3] ▾ │  ← Header (count badge, collapse toggle)
+│ $12.5K total                │  ← Aggregate value (if items have .value)
+├─────────────────────────────┤
+│                             │
+│  ┌───────────────────────┐  │
+│  │ Card 1                │  │  ← PipelineCard (draggable)
+│  └───────────────────────┘  │
+│  ┌───────────────────────┐  │
+│  │ Card 2                │  │
+│  └───────────────────────┘  │
+│                             │
+│  - - - - - - - - - - - - -  │  ← Drop zone (dashed border on drag)
+│                             │
+└─────────────────────────────┘
+```
+
+---
+
+## `<PipelineCard>`
+
+Default card rendered for each item. Consumers can replace entirely via the `card` snippet on `<Pipeline>`.
+
+```svelte
+<script lang="ts">
+  import type { PipelineItem, PipelineStage, StageColors } from '$lib/types/pipeline';
+
+  interface Props {
+    item: PipelineItem;
+    stage: PipelineStage;
+    colors: StageColors;
+    /** Whether this card is currently being dragged */
+    isDragging?: boolean;
+
+    onclick?: (item: PipelineItem) => void;
+
+    class?: string;
+  }
+</script>
+```
+
+### Default Card Layout
+
+```
+┌─────────────────────────────┐
+│ Title                  $25K │  ← title + formatted value
+│ Subtitle                    │  ← subtitle (if present)
+│ [P0] [label1] [label2]     │  ← priority badge + labels
+│ @assignee        3 days ago │  ← assignee + stage duration
+└─────────────────────────────┘
+```
+
+---
+
+## Data Flow
+
+```
+Consumer provides:            Pipeline computes:              Sub-components receive:
+─────────────────            ─────────────────               ────────────────────────
+stages[]          ──────►    stageColors: Map<id, StageColors>  ──► PipelineColumn.colors
+items[]           ──────►    itemsByStage: Map<id, Item[]>      ──► PipelineColumn.items
+config            ──────►    resolvedConfig (merged w/ defaults) ──► PipelineColumn.drag
+                             stageMetrics: StageMetrics[]        ──► column headers
+```
+
+### Grouping (derived)
+
+```typescript
+const itemsByStage = $derived.by(() => {
+  // Pre-initialize all stages (even empty ones show as columns)
+  const groups = new Map<string, PipelineItem[]>();
+  for (const stage of stages) {
+    groups.set(stage.id, []);
+  }
+  for (const item of items) {
+    const list = groups.get(item.stageId);
+    if (list) list.push(item);
+    else groups.get(stages[0].id)?.push(item); // fallback to first stage
+  }
+  return groups;
+});
+```
+
+### Color Resolution
+
+```typescript
+function resolveStageColors(stage: PipelineStage): StageColors {
+  if (stage.color) {
+    // oklch: derive bg/text/border/accent from the base color
+    return {
+      bg: `color-mix(in oklch, ${stage.color} 10%, transparent)`,
+      text: stage.color,
+      border: `color-mix(in oklch, ${stage.color} 40%, transparent)`,
+      accent: stage.color
+    };
+  }
+  // DaisyUI semantic fallback
+  const sem = stage.semantic || 'primary';
+  return {
+    bg: `oklch(from var(--${sem === 'info' ? 'in' : sem === 'success' ? 'su' : sem === 'warning' ? 'wa' : sem === 'error' ? 'er' : 'p'}) l c h / 0.1)`,
+    text: `var(--${sem})`,
+    border: `oklch(from var(--${sem === 'info' ? 'in' : sem === 'success' ? 'su' : sem === 'warning' ? 'wa' : sem === 'error' ? 'er' : 'p'}) l c h / 0.4)`,
+    accent: `var(--${sem})`
+  };
+}
+```
+
+---
+
+## Drag-Drop Integration
+
+Uses `svelte-dnd-action` — same pattern as Steelbridge pipeline.
+
+```svelte
+<!-- Inside PipelineColumn -->
+<div
+  use:dndzone={{
+    items: columnItems,
+    flipDurationMs: drag.flipDurationMs,
+    dropTargetStyle: {},
+    dropTargetClasses: [drag.dropTargetClass]
+  }}
+  onconsider={handleConsider}
+  onfinalize={handleFinalize}
+>
+  {#each columnItems as item (item.id)}
+    <div animate:flip={{ duration: drag.flipDurationMs }}>
+      <!-- card snippet or default PipelineCard -->
+    </div>
+  {/each}
+</div>
+```
+
+### Optimistic Update + Rollback
+
+```typescript
+// In Pipeline component
+async function handleStageFinalize(stageId: string, e: CustomEvent) {
+  const prevItems = [...items]; // snapshot for rollback
+  // Apply optimistic update to local state
+  items = applyDrop(items, stageId, e.detail);
+
+  if (onStageChange) {
+    try {
+      await onStageChange({
+        itemId: e.detail.info.id,
+        fromStageId: findPreviousStage(e.detail.info.id, prevItems),
+        toStageId: stageId,
+        newIndex: e.detail.items.findIndex(i => i.id === e.detail.info.id)
+      });
+    } catch {
+      items = prevItems; // rollback on rejection
+    }
+  }
+}
+```
+
+---
+
+## Table View
+
+When `viewMode === 'table'`, renders a DaisyUI table using `config.tableColumns`.
+
+```
+┌──────────┬──────────┬─────────┬────────┬──────────┐
+│ Name     │ Stage    │ Value   │ Assign │ Date     │
+├──────────┼──────────┼─────────┼────────┼──────────┤
+│ Item 1   │ [badge]  │ $25K    │ @joe   │ Mar 28   │
+│ Item 2   │ [badge]  │ $12K    │ @sam   │ Apr 02   │
+└──────────┴──────────┴─────────┴────────┴──────────┘
+```
+
+Default table columns (when `config.tableColumns` not provided):
+```typescript
+const defaultTableColumns: PipelineTableColumn[] = [
+  { key: 'title', label: 'Name', width: 'flex', sortable: true },
+  { key: 'stageId', label: 'Stage', width: 'md', sortable: true },
+  { key: 'value', label: 'Value', width: 'sm', sortable: true },
+  { key: 'assignee', label: 'Assignee', width: 'md', sortable: true },
+  { key: 'expectedDate', label: 'Date', width: 'md', sortable: true }
+];
+```
+
+---
+
+## Responsive Behavior
+
+```css
+/* Kanban: horizontal scroll on mobile, fixed columns on desktop */
+.pipeline-board {
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: minmax(240px, 1fr);
+  overflow-x: auto;
+  gap: 0.75rem;
+}
+
+/* Table: switches to card-based on mobile (DaisyUI responsive table) */
+```