@echothink-ui/todo 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,49 @@
+import type * as React from "react";
+import type { EthAction, EthOperationalStatus } from "@echothink-ui/core";
+export interface TodoTaskItem {
+    id: string;
+    label: string;
+    done: boolean;
+    dueAt?: string;
+    assignee?: string;
+    priority?: string;
+}
+export interface KanbanCard {
+    id: string;
+    title: string;
+    assignee?: string;
+    priority?: string;
+    status?: string;
+    dueAt?: string;
+    labels?: string[];
+}
+export interface KanbanColumnModel {
+    id: string;
+    title: string;
+    status?: string;
+    wipLimit?: number;
+    items: KanbanCard[];
+}
+export interface TaskTableTask extends Record<string, unknown> {
+    id: string;
+    title: string;
+    status?: EthOperationalStatus;
+    assignee?: string;
+    priority?: string;
+    dueAt?: string;
+    labels?: string[];
+}
+export interface TaskDependency {
+    id: string;
+    title: string;
+    status: string;
+    relation: "blocks" | "blocked-by";
+}
+export interface TaskTimelineEvent {
+    id: string;
+    timestamp: string;
+    actor?: string;
+    kind: string;
+    summary: React.ReactNode;
+}
+export type TaskRowActions = (task: TaskTableTask) => EthAction[];

package/dist/utils.d.ts

@@ -0,0 +1,3 @@
+export declare function formatDateTime(value: string | undefined): string;
+export declare function priorityLabel(priority: string | undefined): string;
+export declare function prioritySeverity(priority: string | undefined): "danger" | "warning" | "info" | "neutral";

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@echothink-ui/todo",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18.3.0",
+    "react-dom": ">=18.3.0"
+  },
+  "dependencies": {
+    "@echothink-ui/core": "0.2.0",
+    "@echothink-ui/icons": "0.2.0",
+    "@echothink-ui/data": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.tsx --format esm,cjs --sourcemap --clean --external react --external react-dom && tsc -p tsconfig.json --declaration --emitDeclarationOnly --noEmit false --outDir dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config ../../vitest.config.ts --passWithNoTests",
+    "lint": "eslint src"
+  }
+}

package/src/components/KanbanBoard.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+import type { KanbanCard, KanbanColumnModel } from "../types";
+import { KanbanColumn } from "./KanbanColumn";
+import { TaskCard } from "./TaskCard";
+
+export interface KanbanBoardProps extends React.HTMLAttributes<HTMLDivElement> {
+  columns?: KanbanColumnModel[];
+  onCardMove?: (cardId: string, fromColumn: string, toColumn: string, index: number) => void;
+  onAddCard?: (columnId: string) => void;
+}
+
+interface LiftedCard {
+  cardId: string;
+  fromColumn: string;
+  toColumn: string;
+  index: number;
+}
+
+export function KanbanBoard({
+  columns = [],
+  onCardMove,
+  onAddCard,
+  className,
+  ...props
+}: KanbanBoardProps) {
+  const [announcement, setAnnouncement] = React.useState("");
+  const [lifted, setLifted] = React.useState<LiftedCard | null>(null);
+
+  const findCard = (cardId: string) => {
+    for (const column of columns) {
+      const index = column.items.findIndex((item) => item.id === cardId);
+      if (index >= 0) return { column, index, card: column.items[index] };
+    }
+    return undefined;
+  };
+
+  const announce = (message: string) => setAnnouncement(message);
+
+  const moveLifted = (direction: "left" | "right" | "up" | "down") => {
+    if (!lifted) return;
+    const currentColumnIndex = columns.findIndex((column) => column.id === lifted.toColumn);
+    if (currentColumnIndex < 0) return;
+    if (direction === "left" || direction === "right") {
+      const offset = direction === "left" ? -1 : 1;
+      const nextColumn = columns[currentColumnIndex + offset];
+      if (!nextColumn) return;
+      const nextIndex = Math.min(lifted.index, Math.max(0, nextColumn.items.length));
+      setLifted({ ...lifted, toColumn: nextColumn.id, index: nextIndex });
+      announce(`Moved ${lifted.cardId} to ${nextColumn.title}, position ${nextIndex + 1}`);
+      return;
+    }
+    const currentColumn = columns[currentColumnIndex];
+    const maxIndex = Math.max(0, currentColumn.items.length - 1);
+    const nextIndex =
+      direction === "up" ? Math.max(0, lifted.index - 1) : Math.min(maxIndex, lifted.index + 1);
+    setLifted({ ...lifted, index: nextIndex });
+    announce(`Moved ${lifted.cardId} to position ${nextIndex + 1}`);
+  };
+
+  const handleCardKeyDown = (
+    event: React.KeyboardEvent<HTMLDivElement>,
+    card: KanbanCard,
+    column: KanbanColumnModel,
+    index: number
+  ) => {
+    if (event.key === " ") {
+      event.preventDefault();
+      setLifted({ cardId: card.id, fromColumn: column.id, toColumn: column.id, index });
+      announce(`Lifted ${card.title}`);
+      return;
+    }
+    if (!lifted) return;
+    if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      moveLifted("left");
+    }
+    if (event.key === "ArrowRight") {
+      event.preventDefault();
+      moveLifted("right");
+    }
+    if (event.key === "ArrowUp") {
+      event.preventDefault();
+      moveLifted("up");
+    }
+    if (event.key === "ArrowDown") {
+      event.preventDefault();
+      moveLifted("down");
+    }
+    if (event.key === "Enter") {
+      event.preventDefault();
+      onCardMove?.(lifted.cardId, lifted.fromColumn, lifted.toColumn, lifted.index);
+      announce(`Dropped ${lifted.cardId}`);
+      setLifted(null);
+    }
+    if (event.key === "Escape") {
+      event.preventDefault();
+      announce(`Cancelled move for ${lifted.cardId}`);
+      setLifted(null);
+    }
+  };
+
+  const handleDrop = (event: React.DragEvent, toColumn: KanbanColumnModel, index: number) => {
+    event.preventDefault();
+    const cardId = event.dataTransfer.getData("text/plain");
+    const source = findCard(cardId);
+    if (!source) return;
+    onCardMove?.(cardId, source.column.id, toColumn.id, index);
+    announce(`Moved ${source.card.title} to ${toColumn.title}`);
+  };
+
+  return (
+    <div
+      {...props}
+      className={`eth-kanban-board ${className ?? ""}`}
+      data-eth-component="KanbanBoard"
+    >
+      <div className="eth-kanban-board__columns" role="list" aria-label="Kanban columns">
+        {columns.map((column) => (
+          <KanbanColumn
+            key={column.id}
+            column={column}
+            role="listitem"
+            onAddCard={onAddCard}
+            onDragOver={(event) => event.preventDefault()}
+            onDrop={(event) => handleDrop(event, column, column.items.length)}
+          >
+            {column.items.map((card, index) => (
+              <div
+                key={card.id}
+                className={`eth-kanban-card-shell ${
+                  lifted?.cardId === card.id ? "eth-kanban-card-shell--lifted" : ""
+                }`}
+                draggable
+                tabIndex={0}
+                role="listitem"
+                aria-label={`${card.title}, ${column.title}, position ${index + 1} of ${
+                  column.items.length
+                }`}
+                aria-grabbed={lifted?.cardId === card.id}
+                aria-roledescription="Draggable task card"
+                aria-keyshortcuts="Space ArrowLeft ArrowRight ArrowUp ArrowDown Enter Escape"
+                onDragStart={(event) => {
+                  event.dataTransfer.setData("text/plain", card.id);
+                  event.dataTransfer.effectAllowed = "move";
+                }}
+                onDragOver={(event) => event.preventDefault()}
+                onDrop={(event) => handleDrop(event, column, index)}
+                onKeyDown={(event) => handleCardKeyDown(event, card, column, index)}
+              >
+                <TaskCard card={card} />
+              </div>
+            ))}
+          </KanbanColumn>
+        ))}
+      </div>
+      <div className="eth-kanban-board__live" aria-live="polite" aria-atomic="true">
+        {announcement}
+      </div>
+    </div>
+  );
+}

package/src/components/KanbanColumn.tsx

@@ -0,0 +1,105 @@
+import * as React from "react";
+import { Badge, IconButton } from "@echothink-ui/core";
+import type { KanbanColumnModel } from "../types";
+
+export interface KanbanColumnProps extends React.HTMLAttributes<HTMLDivElement> {
+  column: KanbanColumnModel;
+  children?: React.ReactNode;
+  onAddCard?: (columnId: string) => void;
+}
+
+export function KanbanColumn({
+  column,
+  children,
+  onAddCard,
+  className,
+  "aria-label": ariaLabel,
+  ...props
+}: KanbanColumnProps) {
+  const itemCount = column.items.length;
+  const taskLabel = `${itemCount} ${itemCount === 1 ? "task" : "tasks"}`;
+  const wipLimit = column.wipLimit;
+  const hasWipLimit = typeof wipLimit === "number";
+  const overLimit = hasWipLimit ? itemCount > wipLimit : false;
+  const atLimit = hasWipLimit ? itemCount === wipLimit : false;
+  const hasRenderedChildren = React.Children.count(children) > 0;
+  const titleId = React.useId();
+  const { "aria-labelledby": ariaLabelledBy, ...sectionProps } = props;
+
+  let wipPercent = 0;
+  let wipStatusLabel = "";
+  let wipSeverity: "danger" | "warning" | "neutral" = "neutral";
+
+  if (hasWipLimit) {
+    wipPercent =
+      wipLimit > 0 ? Math.min(100, (itemCount / wipLimit) * 100) : itemCount > 0 ? 100 : 0;
+    const remaining = wipLimit - itemCount;
+    wipStatusLabel = overLimit
+      ? `${Math.abs(remaining)} over limit`
+      : remaining === 0
+        ? "At limit"
+        : `${remaining} ${remaining === 1 ? "slot" : "slots"} open`;
+    if (overLimit) wipSeverity = "danger";
+    else if (atLimit) wipSeverity = "warning";
+  }
+
+  return (
+    <section
+      {...sectionProps}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabel ? undefined : (ariaLabelledBy ?? titleId)}
+      className={`eth-kanban-column ${overLimit ? "eth-kanban-column--over-limit" : ""} ${
+        className ?? ""
+      }`}
+      data-eth-component="KanbanColumn"
+    >
+      <header className="eth-kanban-column__header">
+        <div className="eth-kanban-column__header-main">
+          <div className="eth-kanban-column__heading">
+            <h3 id={titleId}>{column.title}</h3>
+            <span className="eth-kanban-column__count">{taskLabel}</span>
+          </div>
+          {onAddCard ? (
+            <div className="eth-kanban-column__actions">
+              <IconButton
+                className="eth-kanban-column__add"
+                intent="ghost"
+                density="compact"
+                label={`Add task to ${column.title}`}
+                icon={
+                  <span className="eth-kanban-column__add-glyph" aria-hidden="true">
+                    +
+                  </span>
+                }
+                onClick={() => onAddCard(column.id)}
+              />
+            </div>
+          ) : null}
+        </div>
+        {hasWipLimit ? (
+          <div className="eth-kanban-column__metrics">
+            <div
+              className="eth-kanban-column__limit"
+              aria-label={`Work in progress ${itemCount} of ${wipLimit}`}
+            >
+              <div className="eth-kanban-column__limit-row">
+                <Badge severity={wipSeverity}>WIP {itemCount}/{wipLimit}</Badge>
+                <span className="eth-kanban-column__limit-note">{wipStatusLabel}</span>
+              </div>
+              <span className="eth-kanban-column__meter" aria-hidden="true">
+                <span style={{ inlineSize: `${wipPercent}%` }} />
+              </span>
+            </div>
+          </div>
+        ) : null}
+      </header>
+      <div className="eth-kanban-column__body" role="list" aria-label={`${column.title} tasks`}>
+        {hasRenderedChildren ? (
+          children
+        ) : itemCount === 0 ? (
+          <div className="eth-kanban-column__empty">No tasks in this column</div>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/src/components/TaskCard.tsx

@@ -0,0 +1,74 @@
+import * as React from "react";
+import { Badge, Surface, StatusDot, Tag, type EthOperationalStatus } from "@echothink-ui/core";
+import type { KanbanCard } from "../types";
+import { formatDateTime, priorityLabel, prioritySeverity } from "../utils";
+
+export interface TaskCardProps extends React.HTMLAttributes<HTMLElement> {
+  card: KanbanCard;
+}
+
+const operationalStatuses = new Set<string>([
+  "queued",
+  "running",
+  "paused",
+  "blocked",
+  "failed",
+  "succeeded",
+  "warning",
+  "stale",
+  "synced",
+  "pending-approval",
+  "approval-required",
+  "in-progress",
+  "not-started",
+  "completed",
+  "active",
+  "inactive"
+]);
+
+function isOperationalStatus(status: string | undefined): status is EthOperationalStatus {
+  return Boolean(status && operationalStatuses.has(status));
+}
+
+function statusLabel(status: string) {
+  return status.replace(/-/g, " ");
+}
+
+export function TaskCard({ card, className, ...props }: TaskCardProps) {
+  return (
+    <Surface
+      {...props}
+      className={`eth-todo-task-card ${className ?? ""}`}
+      data-priority={card.priority}
+      data-status={card.status}
+      data-eth-component="TaskCard"
+    >
+      <div className="eth-todo-task-card__header">
+        <strong>{card.title}</strong>
+        {card.priority ? (
+          <Badge severity={prioritySeverity(card.priority)}>{priorityLabel(card.priority)}</Badge>
+        ) : null}
+      </div>
+      <div className="eth-todo-task-card__meta">
+        {card.assignee ? <Tag>{card.assignee}</Tag> : null}
+        {isOperationalStatus(card.status) ? (
+          <StatusDot status={card.status} label={statusLabel(card.status)} />
+        ) : card.status ? (
+          <Tag>{card.status}</Tag>
+        ) : null}
+        {card.dueAt ? (
+          <time className="eth-todo-task-card__due" dateTime={card.dueAt}>
+            {formatDateTime(card.dueAt)}
+          </time>
+        ) : null}
+      </div>
+      {card.labels?.length ? (
+        <div className="eth-todo-task-card__labels">
+          {card.labels.map((label) => (
+            <Tag key={label}>{label}</Tag>
+          ))}
+        </div>
+      ) : null}
+    </Surface>
+  );
+}

package/src/components/TaskDependencyList.tsx

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { Badge, Panel } from "@echothink-ui/core";
+import type { TaskDependency } from "../types";
+
+export interface TaskDependencyListProps extends React.HTMLAttributes<HTMLDivElement> {
+  dependencies?: TaskDependency[];
+}
+
+export function TaskDependencyList({
+  dependencies = [],
+  className,
+  ...props
+}: TaskDependencyListProps) {
+  const groups = {
+    "blocked-by": dependencies.filter((dependency) => dependency.relation === "blocked-by"),
+    blocks: dependencies.filter((dependency) => dependency.relation === "blocks")
+  };
+
+  return (
+    <Panel
+      {...props}
+      className={`eth-todo-dependencies ${className ?? ""}`}
+      title="Dependencies"
+      data-eth-component="TaskDependencyList"
+    >
+      <DependencyGroup title="Blocked by" dependencies={groups["blocked-by"]} />
+      <DependencyGroup title="Blocks" dependencies={groups.blocks} />
+    </Panel>
+  );
+}
+
+function DependencyGroup({
+  title,
+  dependencies
+}: {
+  title: string;
+  dependencies: TaskDependency[];
+}) {
+  return (
+    <section className="eth-todo-dependencies__group">
+      <h3>{title}</h3>
+      {dependencies.length ? (
+        <ul>
+          {dependencies.map((dependency) => (
+            <li key={dependency.id}>
+              <span>{dependency.title}</span>
+              <Badge>{dependency.status}</Badge>
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <p>None</p>
+      )}
+    </section>
+  );
+}

package/src/components/TaskTable.tsx

@@ -0,0 +1,69 @@
+import * as React from "react";
+import { Badge, StatusDot, Tag } from "@echothink-ui/core";
+import { DataTable, type DataColumn } from "@echothink-ui/data";
+import type { TaskRowActions, TaskTableTask } from "../types";
+import { formatDateTime } from "../utils";
+
+export interface TaskTableProps extends React.HTMLAttributes<HTMLDivElement> {
+  tasks?: TaskTableTask[];
+  density?: "compact" | "default" | "comfortable";
+  selectable?: boolean;
+  rowActions?: TaskRowActions;
+}
+
+const columns: DataColumn<TaskTableTask>[] = [
+  {
+    key: "title",
+    header: "Task",
+    render: (task) => (
+      <div className="eth-todo-task-table__title">
+        <strong>{task.title}</strong>
+        {task.labels?.map((label) => (
+          <Tag key={label}>{label}</Tag>
+        ))}
+      </div>
+    )
+  },
+  {
+    key: "status",
+    header: "Status",
+    render: (task) => (task.status ? <StatusDot status={task.status} label={task.status} /> : null)
+  },
+  { key: "assignee", header: "Assignee" },
+  {
+    key: "priority",
+    header: "Priority",
+    render: (task) => (task.priority ? <Badge>{task.priority}</Badge> : null)
+  },
+  {
+    key: "dueAt",
+    header: "Due",
+    render: (task) => (task.dueAt ? <time dateTime={task.dueAt}>{formatDateTime(task.dueAt)}</time> : null)
+  }
+];
+
+export function TaskTable({
+  tasks = [],
+  density = "default",
+  selectable,
+  rowActions,
+  className,
+  ...props
+}: TaskTableProps) {
+  return (
+    <div
+      {...props}
+      className={`eth-todo-task-table ${className ?? ""}`}
+      data-eth-component="TaskTable"
+    >
+      <DataTable
+        rows={tasks}
+        columns={columns}
+        rowKey="id"
+        density={density}
+        selectable={selectable}
+        rowActions={rowActions}
+      />
+    </div>
+  );
+}

package/src/components/TaskTimeline.tsx

@@ -0,0 +1,40 @@
+import * as React from "react";
+import { Panel, Tag } from "@echothink-ui/core";
+import type { TaskTimelineEvent } from "../types";
+import { formatDateTime } from "../utils";
+
+export interface TaskTimelineProps extends React.HTMLAttributes<HTMLDivElement> {
+  events?: TaskTimelineEvent[];
+}
+
+export function TaskTimeline({ events = [], className, ...props }: TaskTimelineProps) {
+  const sortedEvents = React.useMemo(
+    () =>
+      [...events].sort(
+        (a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime()
+      ),
+    [events]
+  );
+
+  return (
+    <Panel
+      {...props}
+      className={`eth-todo-timeline ${className ?? ""}`}
+      title="Task timeline"
+      data-eth-component="TaskTimeline"
+    >
+      <ol className="eth-todo-timeline__events">
+        {sortedEvents.map((event) => (
+          <li key={event.id} className="eth-todo-timeline__event">
+            <time dateTime={event.timestamp}>{formatDateTime(event.timestamp)}</time>
+            <div>
+              <Tag>{event.kind}</Tag>
+              {event.actor ? <span>{event.actor}</span> : null}
+              <p>{event.summary}</p>
+            </div>
+          </li>
+        ))}
+      </ol>
+    </Panel>
+  );
+}

package/src/components/TodoItem.test.tsx

@@ -0,0 +1,46 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { TodoItem } from "./TodoItem";
+
+describe("@echothink-ui/todo TodoItem", () => {
+  it("renders a compact actionable task row with structured metadata", () => {
+    const onToggle = vi.fn();
+
+    const { container } = render(
+      <TodoItem
+        item={{
+          id: "brief",
+          label: "Approve campaign brief",
+          done: false,
+          assignee: "MK",
+          priority: "high",
+          dueAt: "2026-05-30T16:00:00Z"
+        }}
+        onToggle={onToggle}
+      />
+    );
+
+    const row = container.querySelector('[data-eth-component="TodoItem"]');
+    const due = container.querySelector(".eth-todo-item__due time");
+
+    expect(row?.getAttribute("data-priority")).toBe("high");
+    expect(screen.getByRole("checkbox", { name: "Approve campaign brief" })).toBeTruthy();
+    expect(screen.getByText("MK")).toBeTruthy();
+    expect(screen.getByText("high").closest(".eth-badge")).toBeTruthy();
+    expect(due?.getAttribute("datetime")).toBe("2026-05-30T16:00:00Z");
+
+    fireEvent.click(screen.getByRole("checkbox", { name: "Approve campaign brief" }));
+    expect(onToggle).toHaveBeenCalledWith("brief");
+  });
+
+  it("does not emit an invalid datetime attribute for relative due labels", () => {
+    const { container } = render(
+      <TodoItem item={{ id: "relative", label: "Approve brief", done: false, dueAt: "today" }} />
+    );
+
+    const due = container.querySelector(".eth-todo-item__due time");
+
+    expect(due?.textContent).toBe("today");
+    expect(due?.hasAttribute("datetime")).toBe(false);
+  });
+});