@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/containers/kanban/kanban.tsx

@@ -0,0 +1,402 @@
+"use client";
+
+import { GripVertical } from "lucide-react";
+import {
+  type KeyboardEvent,
+  type ReactNode,
+  type PointerEvent as ReactPointerEvent,
+  useCallback,
+  useId,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { Avatar } from "../../atoms/avatar/avatar.js";
+import { Chip } from "../../atoms/chip/chip.js";
+import { cn } from "../../utils/cn.js";
+import {
+  dropIndex,
+  type KanbanCardData,
+  type KanbanColumnData,
+  type KanbanKey,
+  type KanbanMove,
+  keyboardTarget,
+  locateCard,
+  moveCard,
+  wipStatus,
+} from "./model.js";
+
+export interface KanbanProps {
+  /** Controlled board. Pair with `onColumnsChange`. */
+  columns?: KanbanColumnData[];
+  defaultColumns?: KanbanColumnData[];
+  /** Called after a drop (pointer release or keyboard drop) with the new board and the move. */
+  onColumnsChange?: (columns: KanbanColumnData[], move: KanbanMove) => void;
+  /** Refuse drops into another column that already reached its WIP limit. */
+  enforceLimit?: boolean;
+  /** Replaces the default card body. */
+  renderCard?: (card: KanbanCardData) => ReactNode;
+  emptyLabel?: string;
+  "aria-label"?: string;
+  className?: string;
+}
+
+const KEYS: readonly string[] = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"];
+const DRAG_THRESHOLD = 4;
+
+interface DragState {
+  cardId: string;
+  x: number;
+  y: number;
+  width: number;
+  offsetX: number;
+  offsetY: number;
+  target: { columnId: string; index: number } | null;
+}
+
+function DefaultCard({ card }: { card: KanbanCardData }) {
+  return (
+    <div className="flex min-w-0 flex-col gap-1.5">
+      <span className="break-words text-row-title text-ink">{card.title}</span>
+      {card.description ? (
+        <span className="line-clamp-2 break-words text-ink-3 text-meta">{card.description}</span>
+      ) : null}
+      {card.tag || card.assignee || card.meta ? (
+        <div className="flex min-w-0 flex-wrap items-center gap-density-sm">
+          {card.tag ? <Chip tone="accent">{card.tag}</Chip> : null}
+          {card.meta ? <span className="text-ink-3 text-meta">{card.meta}</span> : null}
+          {card.assignee ? (
+            <span className="ml-auto">
+              <Avatar name={card.assignee} />
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * Board of columns with draggable cards and WIP limits. Pointer: drag a card (touch: use the
+ * grip). Keyboard: Space or Enter picks a card up, arrows move it, Space or Enter drops it,
+ * Escape cancels. Moves are announced in a live region.
+ */
+export function Kanban({
+  columns: controlled,
+  defaultColumns = [],
+  onColumnsChange,
+  enforceLimit = false,
+  renderCard,
+  emptyLabel = "Sin tarjetas",
+  className,
+  "aria-label": ariaLabel = "Tablero",
+}: KanbanProps) {
+  const [internal, setInternal] = useState(defaultColumns);
+  const columns = controlled ?? internal;
+
+  /** Working copy while a card is held with the keyboard; committed on drop. */
+  const [draft, setDraft] = useState<KanbanColumnData[] | null>(null);
+  const [grabbedId, setGrabbedId] = useState<string | null>(null);
+  const [drag, setDrag] = useState<DragState | null>(null);
+  const [status, setStatus] = useState("");
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const focusId = useRef<string | null>(null);
+  const columnsRef = useRef(columns);
+  columnsRef.current = columns;
+  const instructionsId = useId();
+
+  const shown = draft ?? columns;
+
+  const commit = useCallback(
+    (next: KanbanColumnData[], move: KanbanMove) => {
+      if (controlled === undefined) setInternal(next);
+      onColumnsChange?.(next, move);
+    },
+    [controlled, onColumnsChange],
+  );
+
+  useLayoutEffect(() => {
+    const id = focusId.current;
+    if (!id) return;
+    const el = rootRef.current?.querySelector<HTMLElement>(`[data-card-id="${CSS.escape(id)}"]`);
+    if (el && document.activeElement !== el) el.focus();
+    if (!grabbedId) focusId.current = null;
+  });
+
+  const describe = (cols: KanbanColumnData[], cardId: string, verb: string) => {
+    const at = locateCard(cols, cardId);
+    const column = cols.find((c) => c.id === at?.columnId);
+    const card = column?.cards[at?.index ?? 0];
+    if (!at || !column || !card) return;
+    setStatus(
+      `${verb} ${card.title}: columna ${column.title}, posición ${at.index + 1} de ${column.cards.length}.`,
+    );
+  };
+
+  const onCardKeyDown = (event: KeyboardEvent<HTMLElement>, card: KanbanCardData) => {
+    const { key } = event;
+    if (key === " " || key === "Enter") {
+      event.preventDefault();
+      if (grabbedId === card.id) {
+        const move = draft ? moveFromDraft(columns, draft, card.id) : null;
+        if (draft && move) commit(draft, move);
+        describe(draft ?? columns, card.id, "Soltada");
+        setDraft(null);
+        setGrabbedId(null);
+      } else if (!grabbedId) {
+        setGrabbedId(card.id);
+        setDraft(columns);
+        focusId.current = card.id;
+        describe(columns, card.id, "Tomada");
+      }
+      return;
+    }
+    if (grabbedId !== card.id) return;
+    if (key === "Escape") {
+      event.preventDefault();
+      setDraft(null);
+      setGrabbedId(null);
+      setStatus(`Movimiento cancelado: ${card.title} vuelve a su lugar.`);
+      return;
+    }
+    if (KEYS.includes(key)) {
+      event.preventDefault();
+      const base = draft ?? columns;
+      const target = keyboardTarget(base, card.id, key as KanbanKey);
+      if (!target) return;
+      const result = moveCard(base, card.id, target.columnId, target.index, { enforceLimit });
+      if (!result) {
+        setStatus("Esa columna llegó a su límite.");
+        return;
+      }
+      focusId.current = card.id;
+      setDraft(result.columns);
+      describe(result.columns, card.id, "Movida");
+    }
+  };
+
+  const startPointerDrag = (event: ReactPointerEvent<HTMLElement>, card: KanbanCardData) => {
+    if (event.button !== 0 || grabbedId) return;
+    if (event.pointerType === "touch" && !(event.target as HTMLElement).closest("[data-grip]")) {
+      return;
+    }
+    const element = event.currentTarget;
+    const rect = element.getBoundingClientRect();
+    const startX = event.clientX;
+    const startY = event.clientY;
+    let active = false;
+    let latest: DragState["target"] = null;
+
+    const locate = (x: number, y: number): DragState["target"] => {
+      const column = document.elementFromPoint(x, y)?.closest<HTMLElement>("[data-column-id]");
+      const columnId = column?.dataset.columnId;
+      if (!column || !columnId) return null;
+      const mids = Array.from(column.querySelectorAll<HTMLElement>("[data-card-id]"))
+        .filter((el) => el.dataset.cardId !== card.id)
+        .map((el) => {
+          const r = el.getBoundingClientRect();
+          return r.top + r.height / 2;
+        });
+      return { columnId, index: dropIndex(mids, y) };
+    };
+
+    const onMove = (e: PointerEvent) => {
+      if (!active) {
+        if (Math.hypot(e.clientX - startX, e.clientY - startY) < DRAG_THRESHOLD) return;
+        active = true;
+        setStatus(`Arrastrando ${card.title}.`);
+      }
+      latest = locate(e.clientX, e.clientY);
+      setDrag({
+        cardId: card.id,
+        x: e.clientX,
+        y: e.clientY,
+        width: rect.width,
+        offsetX: startX - rect.left,
+        offsetY: startY - rect.top,
+        target: latest,
+      });
+    };
+    const finish = (apply: boolean) => {
+      window.removeEventListener("pointermove", onMove);
+      window.removeEventListener("pointerup", onUp);
+      window.removeEventListener("pointercancel", onCancel);
+      window.removeEventListener("keydown", onEscape);
+      if (!active) return;
+      setDrag(null);
+      if (apply && latest) {
+        const result = moveCard(columnsRef.current, card.id, latest.columnId, latest.index, {
+          enforceLimit,
+        });
+        if (result) {
+          commit(result.columns, result.move);
+          describe(result.columns, card.id, "Soltada");
+          return;
+        }
+      }
+      setStatus(`Movimiento cancelado: ${card.title} vuelve a su lugar.`);
+    };
+    const onUp = () => finish(true);
+    const onCancel = () => finish(false);
+    const onEscape = (e: globalThis.KeyboardEvent) => {
+      if (e.key === "Escape") finish(false);
+    };
+    window.addEventListener("pointermove", onMove);
+    window.addEventListener("pointerup", onUp);
+    window.addEventListener("pointercancel", onCancel);
+    window.addEventListener("keydown", onEscape);
+  };
+
+  const dragged = drag
+    ? shown.flatMap((c) => c.cards).find((c) => c.id === drag.cardId)
+    : undefined;
+
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: focus leaving the board cancels a held card
+    <div
+      ref={rootRef}
+      className={cn("@container/kanban min-w-0", className)}
+      onBlur={(event) => {
+        const next = event.relatedTarget as Node | null;
+        if (grabbedId && next && !rootRef.current?.contains(next)) {
+          setDraft(null);
+          setGrabbedId(null);
+          setStatus("Movimiento cancelado.");
+        }
+      }}
+    >
+      <p id={instructionsId} className="sr-only">
+        Presiona Espacio para tomar una tarjeta, las flechas para moverla y Espacio para soltarla.
+        Escape cancela.
+      </p>
+      <div role="status" aria-live="assertive" className="sr-only">
+        {status}
+      </div>
+      {/* biome-ignore lint/a11y/useSemanticElements: board of columns, not a form group */}
+      <div
+        role="group"
+        aria-label={ariaLabel}
+        className="flex snap-x snap-mandatory items-start gap-density overflow-x-auto pb-2"
+      >
+        {shown.map((column) => {
+          const state = wipStatus(column.cards.length, column.wipLimit);
+          const targetHere = drag?.target?.columnId === column.id ? drag.target.index : null;
+          let seen = 0;
+          const items: ReactNode[] = [];
+          const indicator = (key: string) => (
+            <li
+              key={key}
+              aria-hidden="true"
+              className="h-1 shrink-0 rounded-badge bg-accent"
+              data-drop-indicator=""
+            />
+          );
+          for (const card of column.cards) {
+            const isDragged = drag?.cardId === card.id;
+            if (!isDragged) {
+              if (targetHere === seen) items.push(indicator(`ind-${seen}`));
+              seen += 1;
+            }
+            const grabbed = grabbedId === card.id;
+            items.push(
+              <li key={card.id} className="min-w-0">
+                {/* biome-ignore lint/a11y/useSemanticElements: draggable card is a custom widget */}
+                <div
+                  role="button"
+                  tabIndex={0}
+                  data-card-id={card.id}
+                  aria-pressed={grabbed}
+                  aria-roledescription="tarjeta arrastrable"
+                  aria-describedby={instructionsId}
+                  onKeyDown={(e) => onCardKeyDown(e, card)}
+                  onPointerDown={(e) => startPointerDrag(e, card)}
+                  className={cn(
+                    "pressable relative flex cursor-grab select-none gap-1 rounded-input border-card surface-card p-density shadow-card focus-visible:focus-ring",
+                    isDragged && "opacity-40",
+                    grabbed && "shadow-selected",
+                  )}
+                >
+                  <span
+                    data-grip=""
+                    aria-hidden="true"
+                    className="-ml-1 flex w-4 shrink-0 touch-none items-start pt-0.5 text-ink-3"
+                  >
+                    <GripVertical className="size-4" />
+                  </span>
+                  <div className="min-w-0 flex-1">
+                    {renderCard ? renderCard(card) : <DefaultCard card={card} />}
+                  </div>
+                </div>
+              </li>,
+            );
+          }
+          if (targetHere !== null && targetHere >= seen) items.push(indicator("ind-end"));
+
+          return (
+            <section
+              key={column.id}
+              data-column-id={column.id}
+              aria-label={column.title}
+              className="flex w-[min(18rem,85cqw)] shrink-0 snap-start flex-col gap-density-sm rounded-card bg-surface-sunken p-density-sm @4xl/kanban:w-auto @4xl/kanban:min-w-56 @4xl/kanban:flex-1"
+            >
+              <header className="flex min-w-0 items-center justify-between gap-density-sm px-1 pt-1">
+                <h3 className="min-w-0 truncate text-card-title text-ink">{column.title}</h3>
+                <Chip
+                  tone={state === "over" ? "danger" : state === "at-limit" ? "warning" : "neutral"}
+                  aria-label={
+                    column.wipLimit === undefined
+                      ? `${column.cards.length} tarjetas`
+                      : `${column.cards.length} de ${column.wipLimit} tarjetas, límite de trabajo en curso`
+                  }
+                >
+                  {column.wipLimit === undefined
+                    ? column.cards.length
+                    : `${column.cards.length}/${column.wipLimit}`}
+                </Chip>
+              </header>
+              <ul className="m-0 flex min-h-16 list-none flex-col gap-density-sm p-0">
+                {items}
+                {column.cards.length === 0 && targetHere === null ? (
+                  <li className="px-1 py-density text-center text-ink-3 text-meta">{emptyLabel}</li>
+                ) : null}
+              </ul>
+            </section>
+          );
+        })}
+      </div>
+      {drag && dragged ? (
+        <div
+          aria-hidden="true"
+          className="pointer-events-none fixed z-90 rotate-1 rounded-input border-card surface-card p-density shadow-overlay"
+          style={{
+            left: drag.x - drag.offsetX,
+            top: drag.y - drag.offsetY,
+            width: drag.width,
+          }}
+        >
+          {renderCard ? renderCard(dragged) : <DefaultCard card={dragged} />}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/** The move implied by a keyboard-held card: from the committed board to the draft. */
+function moveFromDraft(
+  original: KanbanColumnData[],
+  draft: KanbanColumnData[],
+  cardId: string,
+): KanbanMove | null {
+  const from = locateCard(original, cardId);
+  const to = locateCard(draft, cardId);
+  if (!from || !to) return null;
+  if (from.columnId === to.columnId && from.index === to.index) return null;
+  return {
+    cardId,
+    fromColumnId: from.columnId,
+    fromIndex: from.index,
+    toColumnId: to.columnId,
+    toIndex: to.index,
+  };
+}

package/src/containers/kanban/model.ts

@@ -0,0 +1,141 @@
+export interface KanbanCardData {
+  id: string;
+  title: string;
+  description?: string;
+  tag?: string;
+  assignee?: string;
+  meta?: string;
+}
+
+export interface KanbanColumnData {
+  id: string;
+  title: string;
+  /** Work-in-progress limit: the badge warns at the limit and turns red above it. */
+  wipLimit?: number;
+  cards: KanbanCardData[];
+}
+
+export interface KanbanMove {
+  cardId: string;
+  fromColumnId: string;
+  fromIndex: number;
+  toColumnId: string;
+  toIndex: number;
+}
+
+export type WipStatus = "none" | "ok" | "at-limit" | "over";
+
+export function wipStatus(count: number, limit?: number): WipStatus {
+  if (limit === undefined) return "none";
+  if (count > limit) return "over";
+  return count === limit ? "at-limit" : "ok";
+}
+
+export function locateCard(
+  columns: KanbanColumnData[],
+  cardId: string,
+): { columnId: string; index: number } | null {
+  for (const column of columns) {
+    const index = column.cards.findIndex((card) => card.id === cardId);
+    if (index !== -1) return { columnId: column.id, index };
+  }
+  return null;
+}
+
+export interface MoveOptions {
+  /** Refuse drops into a different column that is already at its WIP limit. */
+  enforceLimit?: boolean;
+}
+
+/**
+ * Moves a card. `toIndex` is the position in the target column AFTER the card is removed from
+ * its origin, clamped to the column. Returns null when nothing changes (unknown ids, same spot,
+ * or a blocked drop), so callers can skip the update.
+ */
+export function moveCard(
+  columns: KanbanColumnData[],
+  cardId: string,
+  toColumnId: string,
+  toIndex: number,
+  options: MoveOptions = {},
+): { columns: KanbanColumnData[]; move: KanbanMove } | null {
+  const from = locateCard(columns, cardId);
+  const target = columns.find((column) => column.id === toColumnId);
+  if (!from || !target) return null;
+
+  const sameColumn = from.columnId === toColumnId;
+  if (
+    !sameColumn &&
+    options.enforceLimit &&
+    target.wipLimit !== undefined &&
+    target.cards.length >= target.wipLimit
+  ) {
+    return null;
+  }
+
+  const remaining = sameColumn ? target.cards.length - 1 : target.cards.length;
+  const index = Math.min(Math.max(0, Math.trunc(toIndex)), remaining);
+  if (sameColumn && index === from.index) return null;
+
+  const source = columns.find((column) => column.id === from.columnId);
+  const card = source?.cards[from.index];
+  if (!card) return null;
+
+  const next = columns.map((column) => {
+    if (column.id === from.columnId && !sameColumn) {
+      return { ...column, cards: column.cards.filter((c) => c.id !== cardId) };
+    }
+    if (column.id === toColumnId) {
+      const cards = column.cards.filter((c) => c.id !== cardId);
+      cards.splice(index, 0, card);
+      return { ...column, cards };
+    }
+    return column;
+  });
+
+  return {
+    columns: next,
+    move: {
+      cardId,
+      fromColumnId: from.columnId,
+      fromIndex: from.index,
+      toColumnId,
+      toIndex: index,
+    },
+  };
+}
+
+export type KanbanKey = "ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown";
+
+/** Where a grabbed card goes for an arrow key: sideways keeps the row, vertical reorders. */
+export function keyboardTarget(
+  columns: KanbanColumnData[],
+  cardId: string,
+  key: KanbanKey,
+): { columnId: string; index: number } | null {
+  const at = locateCard(columns, cardId);
+  if (!at) return null;
+  const columnIndex = columns.findIndex((column) => column.id === at.columnId);
+  const column = columns[columnIndex];
+  if (!column) return null;
+
+  if (key === "ArrowUp")
+    return at.index > 0 ? { columnId: at.columnId, index: at.index - 1 } : null;
+  if (key === "ArrowDown") {
+    return at.index < column.cards.length - 1
+      ? { columnId: at.columnId, index: at.index + 1 }
+      : null;
+  }
+  const neighbour = columns[columnIndex + (key === "ArrowRight" ? 1 : -1)];
+  if (!neighbour) return null;
+  return { columnId: neighbour.id, index: Math.min(at.index, neighbour.cards.length) };
+}
+
+/** Insert index for a pointer at `y`, from the vertical midpoints of the cards left in a column. */
+export function dropIndex(midpoints: number[], y: number): number {
+  let index = 0;
+  for (const mid of midpoints) {
+    if (y > mid) index += 1;
+  }
+  return index;
+}

package/src/containers/kpi/index.ts

@@ -0,0 +1 @@
+export * from "./kpi.js";

package/src/containers/kpi/kpi.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import { cn } from "../../utils/cn.js";
+
+export type KpiVariant = "default" | "danger";
+
+export interface KpiProps {
+  /** Short label describing the metric. */
+  label: ReactNode;
+  /** Highlighted number, already formatted by the consumer. */
+  value: ReactNode;
+  /** Small suffix next to the number, e.g. "/12". */
+  suffix?: ReactNode;
+  /** Optional subtext. */
+  description?: ReactNode;
+  variant?: KpiVariant;
+  className?: string;
+}
+
+export function Kpi({
+  label,
+  value,
+  suffix,
+  description,
+  variant = "default",
+  className,
+}: KpiProps) {
+  return (
+    <div
+      className={cn(
+        "@container/kpi flex min-w-0 flex-col gap-0.5 bg-surface px-[18px] py-3.5",
+        className,
+      )}
+    >
+      <span className="break-words font-semibold text-[12px] text-ink-2">{label}</span>
+      <span
+        className={cn(
+          "break-words text-kpi-number tabular-nums @max-[9rem]/kpi:text-[22px]",
+          variant === "danger" ? "text-danger" : "text-ink",
+        )}
+      >
+        {value}
+        {suffix ? (
+          <small className="ml-1 font-semibold text-[14px] text-ink-3 tracking-normal">
+            {suffix}
+          </small>
+        ) : null}
+      </span>
+      {description ? (
+        <span className="break-words text-[12px] text-ink-3">{description}</span>
+      ) : null}
+    </div>
+  );
+}

package/src/containers/kpi-group/index.ts

@@ -0,0 +1 @@
+export { KpiGroup, type KpiGroupItem, type KpiGroupProps } from "./kpi-group.js";

package/src/containers/kpi-group/kpi-group.tsx

@@ -0,0 +1,71 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { NumberFormatConfig } from "../../atoms/number-value/format.js";
+import { NumberValue } from "../../atoms/number-value/number-value.js";
+import { TrendChip } from "../../atoms/trend-chip/trend-chip.js";
+import { cn } from "../../utils/cn.js";
+
+export interface KpiGroupItem {
+  id: string;
+  label: ReactNode;
+  /** A number is formatted (and animated) with `format`; a node is shown as is. */
+  value: number | ReactNode;
+  format?: NumberFormatConfig;
+  /** Change in percent; renders a TrendChip. */
+  trend?: number;
+  trendLabel?: string;
+  /** Lower is better for this metric. */
+  invertTrend?: boolean;
+  description?: ReactNode;
+}
+
+export interface KpiGroupProps extends Omit<ComponentPropsWithoutRef<"dl">, "children"> {
+  items: KpiGroupItem[];
+  /** Animate numeric values counting up. */
+  animate?: boolean;
+}
+
+/**
+ * Metrics that belong together in one card, divided by hairlines. Columns follow the
+ * container width: 1, 2 or 4 across.
+ */
+export function KpiGroup({ items, animate = true, className, ...props }: KpiGroupProps) {
+  return (
+    <div className={cn("@container/kpi-group min-w-0", className)}>
+      <dl
+        className="m-0 grid grid-cols-1 gap-px overflow-hidden rounded-card border-card bg-divider shadow-card @sm/kpi-group:grid-cols-2 @3xl/kpi-group:grid-cols-4"
+        {...props}
+      >
+        {items.map((item) => (
+          <div key={item.id} className="surface-card flex min-w-0 flex-col gap-density-sm p-card">
+            <dt className="truncate font-semibold text-ink-2 text-meta">{item.label}</dt>
+            <dd className="m-0 flex min-w-0 flex-col gap-density-sm">
+              <span className="break-words text-kpi-number text-ink tabular-nums">
+                {typeof item.value === "number" ? (
+                  <NumberValue
+                    value={item.value}
+                    format={item.format}
+                    duration={animate ? 900 : 0}
+                    animateOnMount={animate}
+                  />
+                ) : (
+                  item.value
+                )}
+              </span>
+              {item.trend !== undefined ? (
+                <TrendChip
+                  value={item.trend}
+                  invert={item.invertTrend}
+                  label={item.trendLabel}
+                  className="w-fit"
+                />
+              ) : null}
+              {item.description ? (
+                <span className="break-words text-ink-3 text-meta">{item.description}</span>
+              ) : null}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </div>
+  );
+}

package/src/containers/page-header/index.ts

@@ -0,0 +1 @@
+export * from "./page-header.js";