@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/sortable/index.js

@@ -0,0 +1,10 @@
+// Public API of @vamos-ui/react/sortable — reordering + pointer-drag primitives.
+// The drag engine (dnd-kit) is internal: no engine type is exported.
+export { Sortable, SortableItem, SortableHandle, SortableOverlay, SortableMoveMenu, SortableContainer, useSortableItem, useSortableItemContext, useSortableActiveId, useSortableContainerItems, sortableLabels, } from "./sortable.js";
+export { SortableList, SortableGrid, sortableListVariants, sortableRowVariants, } from "./sortable-list.js";
+export { arrayMove, moveTargetIndex, moveBetweenContainers, findContainer, flattenTree, descendantIds, projectTreeMove, moveTreeNode, keepMountedRange, } from "./core.js";
+export { usePointerDrag, snapToGrid, } from "./use-pointer-drag.js";
+export { useTimeScale } from "./use-time-scale.js";
+export { SortableTree, sortableTreeLabels, } from "./sortable-tree.js";
+export { Kanban, KanbanColumnHeader, KanbanCardTitle, KanbanCardMeta, KanbanCardFooter, kanbanLabels, kanbanColumnVariants, } from "./kanban.js";
+export { groupByStage, sumBy, weightedSum, applyKanbanMove, stageToneColor, } from "./kanban-core.js";

package/dist/sortable/kanban-core.d.ts

@@ -0,0 +1,70 @@
+/** Semantic tone or one of the six chart hues. Drives the 3px top edge and the header dot. */
+export type StageTone = "neutral" | "accent" | "success" | "warning" | "danger" | "info" | `chart-${1 | 2 | 3 | 4 | 5 | 6}`;
+/**
+ * A step in a pipeline or workflow. Shared by Kanban, Funnel, Approval flow and Status picker.
+ *
+ * ```ts
+ * const stages: Stage[] = [
+ *   { key: "lead", label: "Lead", tone: "chart-1", category: "open", probability: 0.1 },
+ *   { key: "won", label: "Won", tone: "success", category: "done", probability: 1 },
+ * ];
+ * ```
+ */
+export interface Stage {
+    key: string;
+    label: string;
+    tone?: StageTone;
+    /** What kind of step it is: reporting rolls stages up by category. */
+    category?: "open" | "active" | "done" | "canceled";
+    /** Win probability 0…1, used by `weightedSum`. */
+    probability?: number;
+    /** Work-in-progress limit: the header shows "5/8" and warns above it. */
+    wipLimit?: number;
+    /** Initially collapsed (uncontrolled boards). */
+    collapsed?: boolean;
+}
+/** CSS colour for a stage tone (a token reference). */
+export declare function stageToneColor(tone: StageTone | undefined): string;
+/** Items grouped by stage key, in stage order, keeping the items' own order. Unknown stages are dropped. */
+export declare function groupByStage<T>(items: readonly T[], stages: readonly Stage[], getStageKey: (item: T) => string): Map<string, T[]>;
+/** Exact sum of a decimal-string field: `sumBy(deals, (d) => d.value)` → `"245000.00"`. */
+export declare function sumBy<T>(items: readonly T[], getValue: (item: T) => string | null | undefined, scale?: number): string;
+/** Σ value × stage probability as an exact decimal string (`probability` missing → 0). */
+export declare function weightedSum<T>(items: readonly T[], stage: Stage, getValue: (item: T) => string | null | undefined, scale?: number): string;
+export interface KanbanMoveEvent {
+    id: string;
+    /** Stage keys. Equal for a reorder inside one column. */
+    from: string;
+    to: string;
+    /** Final index in the target column (or lane cell). */
+    index: number;
+    /** Index in the source column before the move. */
+    fromIndex: number;
+    /** Lane keys (swimlanes only). */
+    lane?: string;
+    fromLane?: string;
+}
+/**
+ * Applies a move to a flat item array: changes the stage (and lane) with `update`, and places
+ * the item so it lands at `index` among the items of its new column (and lane).
+ *
+ * ```ts
+ * onMove={(e) => setDeals((d) => applyKanbanMove(d, e, {
+ *   getId: (x) => x.id, getStageKey: (x) => x.stage,
+ *   update: (x, stage) => ({ ...x, stage }),
+ * }))}
+ * ```
+ */
+export declare function applyKanbanMove<T>(items: readonly T[], e: KanbanMoveEvent, o: {
+    getId: (item: T) => string;
+    getStageKey: (item: T) => string;
+    getLaneKey?: (item: T) => string;
+    update: (item: T, stage: string, lane: string | undefined) => T;
+}): T[];
+/** Separator for lane × stage container ids. */
+export declare const KANBAN_CELL_SEP = "\u241F";
+export declare const kanbanCellId: (stage: string, lane?: string) => string;
+export declare function parseKanbanCellId(id: string): {
+    stage: string;
+    lane?: string;
+};

package/dist/sortable/kanban-core.js

@@ -0,0 +1,67 @@
+/**
+ * React-free board math: the shared `Stage` type, grouping, column summaries and the move
+ * helper that applies a Kanban move to a flat item array. Safe in server components and workers.
+ */
+import { addDecimal, multiplyDecimal } from "../format/core.js";
+/** CSS colour for a stage tone (a token reference). */
+export function stageToneColor(tone) {
+    if (!tone || tone === "neutral")
+        return "var(--fg-subtle)";
+    if (tone === "accent")
+        return "var(--accent-ink)";
+    if (tone.startsWith("chart-"))
+        return `var(--${tone})`;
+    return `var(--${tone})`;
+}
+/** Items grouped by stage key, in stage order, keeping the items' own order. Unknown stages are dropped. */
+export function groupByStage(items, stages, getStageKey) {
+    const out = new Map(stages.map((s) => [s.key, []]));
+    for (const it of items)
+        out.get(getStageKey(it))?.push(it);
+    return out;
+}
+/** Exact sum of a decimal-string field: `sumBy(deals, (d) => d.value)` → `"245000.00"`. */
+export function sumBy(items, getValue, scale = 2) {
+    return addDecimal(items.map((i) => getValue(i)).filter((v) => typeof v === "string" && v !== ""), scale);
+}
+/** Σ value × stage probability as an exact decimal string (`probability` missing → 0). */
+export function weightedSum(items, stage, getValue, scale = 2) {
+    const p = stage.probability ?? 0;
+    return multiplyDecimal(sumBy(items, getValue, scale), String(p), scale);
+}
+/**
+ * Applies a move to a flat item array: changes the stage (and lane) with `update`, and places
+ * the item so it lands at `index` among the items of its new column (and lane).
+ *
+ * ```ts
+ * onMove={(e) => setDeals((d) => applyKanbanMove(d, e, {
+ *   getId: (x) => x.id, getStageKey: (x) => x.stage,
+ *   update: (x, stage) => ({ ...x, stage }),
+ * }))}
+ * ```
+ */
+export function applyKanbanMove(items, e, o) {
+    const at = items.findIndex((i) => o.getId(i) === e.id);
+    if (at === -1)
+        return items.slice();
+    const moved = o.update(items[at], e.to, e.lane);
+    const rest = items.filter((_, i) => i !== at);
+    const inCell = (i) => o.getStageKey(i) === e.to && (e.lane === undefined || !o.getLaneKey || o.getLaneKey(i) === e.lane);
+    const cell = rest.map((it, i) => (inCell(it) ? i : -1)).filter((i) => i !== -1);
+    let insertAt;
+    if (cell.length === 0)
+        insertAt = rest.length;
+    else if (e.index >= cell.length)
+        insertAt = cell[cell.length - 1] + 1;
+    else
+        insertAt = cell[Math.max(0, e.index)];
+    rest.splice(insertAt, 0, moved);
+    return rest;
+}
+/** Separator for lane × stage container ids. */
+export const KANBAN_CELL_SEP = "␟";
+export const kanbanCellId = (stage, lane) => (lane === undefined ? stage : `${lane}${KANBAN_CELL_SEP}${stage}`);
+export function parseKanbanCellId(id) {
+    const i = id.indexOf(KANBAN_CELL_SEP);
+    return i === -1 ? { stage: id } : { lane: id.slice(0, i), stage: id.slice(i + KANBAN_CELL_SEP.length) };
+}

package/dist/sortable/kanban.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Kanban: items in stage columns with drag-to-move, column summaries, WIP limits, collapsible
+ * columns, optional swimlanes, quick add and virtualized long columns. Built on `Sortable`
+ * (multi-container) — every move also works without dragging: a card menu ("Move to ▸ stage")
+ * and Alt + arrow shortcuts, all announced.
+ */
+import * as React from "react";
+import { type SortableLabels } from "./sortable.js";
+import { type KanbanMoveEvent, type Stage } from "./kanban-core.js";
+export declare const kanbanLabels: {
+    board: string;
+    column: string;
+    cell: string;
+    lane: string;
+    wip: string;
+    wipExceeded: string;
+    empty: string;
+    filteredEmpty: string;
+    loading: string;
+    addCard: string;
+    addCardTo: string;
+    quickAddLabel: string;
+    quickAddPlaceholder: string;
+    quickAddSubmit: string;
+    quickAddCancel: string;
+    quickAddFailed: string;
+    columnMenu: string;
+    collapse: string;
+    expand: string;
+    moveColumnStart: string;
+    moveColumnEnd: string;
+    collapseLane: string;
+    expandLane: string;
+    cardMenu: string;
+    moveUp: string;
+    moveDown: string;
+    moveToHeading: string;
+    currentStage: string;
+    moved: string;
+    reordered: string;
+    blocked: string;
+    moveFailed: string;
+    retry: string;
+    saving: string;
+};
+export type KanbanLabels = typeof kanbanLabels;
+export interface KanbanCardState {
+    isDragging: boolean;
+    /** `cardSize === "compact"`. */
+    compact: boolean;
+    /** Rendering the dragged clone. */
+    overlay: boolean;
+    /** An async `onMove` for this card is in flight. */
+    saving: boolean;
+    stage: Stage;
+}
+export interface KanbanLane {
+    key: string;
+    label: string;
+    /** Leading visual (an Avatar for an owner lane). */
+    icon?: React.ReactNode;
+}
+export interface KanbanProps<T> {
+    stages: readonly Stage[];
+    items: readonly T[];
+    getId?: (item: T) => string;
+    getStageKey: (item: T) => string;
+    /** Spoken name of a card (announcements, menu names). Default `title` / `name` / `label`. */
+    getLabel?: (item: T) => string;
+    renderCard: (item: T, state: KanbanCardState) => React.ReactNode;
+    /** Called once per drop, menu move or shortcut. A returned promise keeps the card optimistic until it settles; a rejection snaps it back with a Retry toast. */
+    onMove: (event: KanbanMoveEvent) => void | Promise<void>;
+    /** `true` or the reason the move is not allowed ("Value is required to mark as Won"). */
+    canMove?: (event: KanbanMoveEvent) => true | string;
+    /** Last check before `onMove` (open a "Lost reason" dialog). Resolve `false` to cancel. */
+    beforeMove?: (event: KanbanMoveEvent) => boolean | Promise<boolean>;
+    /** Column summary under the header label (Σ value, weighted value). Also the column's accessible description. */
+    summary?: (items: T[], stage: Stage) => React.ReactNode;
+    /** Shows a quick-add row at the bottom of each column. */
+    onQuickAdd?: (stageKey: string, title: string, lane?: string) => void | Promise<void>;
+    /** Enables "Move column left / right" in the column menu. */
+    reorderStages?: (next: Stage[]) => void;
+    /** Swimlanes. */
+    lanes?: readonly KanbanLane[];
+    getLaneKey?: (item: T) => string;
+    collapsedStages?: string[];
+    defaultCollapsedStages?: string[];
+    onCollapsedStagesChange?: (keys: string[]) => void;
+    /** Extra items at the end of each card's menu. */
+    cardMenu?: (item: T) => React.ReactNode;
+    /** Render only the visible cards of long columns. Default threshold 60 cards. */
+    virtualize?: boolean | {
+        estimateSize?: number;
+        threshold?: number;
+    };
+    cardSize?: "compact" | "comfortable";
+    columnWidth?: "sm" | "md" | "lg";
+    /** Board height (scrolling columns). Required for virtualization; default `36rem` when virtualizing. */
+    height?: number | string;
+    /** Items are filtered: empty columns say "No items match". */
+    filtered?: boolean;
+    /** Three skeleton cards per column. */
+    loading?: boolean;
+    /** Filter bar / view switch slot above the board. */
+    toolbar?: React.ReactNode;
+    labels?: Partial<KanbanLabels>;
+    /** Strings of the underlying Sortable (drag announcements). */
+    sortableLabels?: Partial<SortableLabels>;
+    "aria-label"?: string;
+    className?: string;
+}
+export declare const kanbanColumnVariants: (props?: ({
+    width?: "sm" | "md" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/**
+ * A board of items in stage columns.
+ *
+ * ```tsx
+ * <Kanban
+ *   aria-label="Sales pipeline"
+ *   stages={stages}
+ *   items={deals}
+ *   getStageKey={(d) => d.stage}
+ *   renderCard={(d) => <DealCard deal={d} />}
+ *   onMove={(e) => setDeals((all) => applyKanbanMove(all, e, { getId, getStageKey, update: (d, stage) => ({ ...d, stage }) }))}
+ * />
+ * ```
+ */
+export declare function Kanban<T>(props: KanbanProps<T>): React.JSX.Element;
+export interface KanbanColumnHeaderProps {
+    stage: Stage;
+    count: number;
+    summary?: React.ReactNode;
+    collapsed?: boolean;
+    onToggle?: () => void;
+    onAdd?: () => void;
+    onMoveStart?: () => void;
+    onMoveEnd?: () => void;
+}
+/** Label · count · summary · WIP · menu. Collapsed: a vertical label that expands on click. */
+export declare function KanbanColumnHeader({ stage, count, summary, collapsed, onToggle, onAdd, onMoveStart, onMoveEnd }: KanbanColumnHeaderProps): React.JSX.Element;
+/** Card title. Put a link inside for the card's main action. */
+export declare function KanbanCardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>): React.JSX.Element;
+/** A row of secondary facts (company, value, due date). */
+export declare function KanbanCardMeta({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;
+/** Bottom row: badges start, avatars end. */
+export declare function KanbanCardFooter({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): React.JSX.Element;