@joewinke/jatui 0.1.23 → 0.1.24

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

@@ -1,361 +0,0 @@
-# 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) */
-```