@anchrd/intel-ui 0.16.0 → 0.17.0

package/src/components/ui/item-gantt.tsx

@@ -0,0 +1,463 @@
+import { DndContext, PointerSensor, useDraggable, useSensor, useSensors } from "@dnd-kit/core";
+import { type ReactNode, useEffect, useId, useRef, useState } from "react";
+import { cn } from "@/lib/utils";
+
+/**
+ * A timeline with bars, arrows between them, and edges you can drag — from the Kibo UI Gantt (MIT)
+ * and changed where it had to be (anchrd/intel#293).
+ *
+ * Registry code is our code. Four dependencies came with the original and none of them survived
+ * contact with this board; the reasoning is below, because "we dropped it" is not a reason anybody
+ * can check later.
+ *
+ * ⚠️ **`jotai` is gone, for the same fault the calendar had.** The original keeps `draggingAtom` and
+ * `scrollXAtom` at MODULE scope. That is not component state stored elsewhere — it is one scroll
+ * position and one drag flag shared by every Gantt the bundle renders, outliving unmount. Two boards
+ * side by side would report each other's scroll, and here that is worse than the calendar's shared
+ * month was: the original computes a resize from `mouseX - ganttLeft + scrollX`, so a second chart
+ * scrolled elsewhere would make the first one commit a date the reader never dragged to. A wrong
+ * picture is a bug; a wrong picture that WRITES is a different kind. The drag state below is one
+ * `useState` in one component.
+ *
+ * ⚠️ **`lodash.throttle` is gone with it.** It threw the scroll handler, and that handler was the
+ * only caller. The original also wraps it in `useCallback(throttle(...), [])` over an empty
+ * dependency list while reading `timelineData` inside — so the infinite-scroll extension it exists
+ * for reads the first render's timeline for ever. This chart has no infinite scroll to throttle: a
+ * board's own dates say how wide it is, which is a bounded window and one that arrows can be drawn
+ * across (the whole point of the ticket) without their coordinates moving underneath them.
+ *
+ * ⚠️ **`@uidotdev/usehooks` is gone.** It supplied `useMouse` for the drag arithmetic — a global
+ * pointer position, corrected afterwards by the container's rectangle and the scroll offset. dnd-kit
+ * already reports the displacement of the drag itself (`delta.x`), which needs no correcting and is
+ * right inside a scrolled container. Reading only `x` is also what `@dnd-kit/modifiers`'
+ * `restrictToHorizontalAxis` was in the dependency list for, so that package is not needed either.
+ *
+ * ⚠️ **`date-fns` is gone**, as it went from the calendar. The dates here are days (`BoardTaskDate`
+ * carries no time and no zone), so every offset is a day count times a day's width — arithmetic that
+ * lives in `board-gantt.ts` where it can be asserted without rendering anything.
+ *
+ * Two more differences from the original, both about writing rather than drawing:
+ *
+ * ⚠️ **A drag reports ONCE, when it is let go.** The original moves the bar by writing to component
+ * state on every pointer move and calls `onMove` at the end with whatever that state reached. Against
+ * a server the risk is the same one #286 found in the date fields: a handler on the wrong event turns
+ * one gesture into a write per frame. The preview here is local, `onEdit` fires once, and the day it
+ * reports is the day the reader saw — the preview snaps to whole days for exactly that reason.
+ *
+ * ⚠️ **`Card` and `ContextMenu` are not pulled in.** They are registry dependencies of the original
+ * for a bar wrapper and a right-click menu this board does not have. Two shadcn primitives added for
+ * decoration are two more files to keep in step with the rest.
+ */
+
+export interface GanttChartBar {
+  // Where the bar starts and how long it is, in whole days from the axis start. Pixels are this
+  // times `dayWidth`, and nothing here computes a date.
+  from: number;
+  days: number;
+  // The status colour, as a class. A colour is never a value in this package (`lint:tokens`), so the
+  // caller resolves it from the board's own ramp and hands the class in.
+  className: string;
+  /**
+   * A bar rolled up from a subtree rather than a task's own dates.
+   *
+   * ⚠️ It is drawn and never dragged. One gesture on a summary bar would have to write every task
+   * under it — several versions, several audit entries, and no way to say which of them was meant.
+   */
+  derived: boolean;
+}
+
+export interface GanttChartRow {
+  id: string;
+  // The left column of this row. The caller draws it: only it knows what a status, a blocked chip or
+  // a click on a title means.
+  sidebar: ReactNode;
+  bar: GanttChartBar | null;
+}
+
+export interface GanttChartLink {
+  id: string;
+  // Already in the timeline's own pixel space — the caller owns the geometry (`board-gantt.ts`), so
+  // the shape of an arrow can be asserted without a browser.
+  path: string;
+  blocking: boolean;
+}
+
+export type GanttChartEdit = "move" | "start" | "end";
+
+interface DragState {
+  rowId: string;
+  edit: GanttChartEdit;
+  days: number;
+}
+
+export function ItemGantt({
+  rows,
+  links,
+  groups,
+  ticks,
+  days,
+  dayWidth,
+  rowHeight,
+  today,
+  labels,
+  onEdit,
+  footer,
+}: {
+  rows: GanttChartRow[];
+  links: GanttChartLink[];
+  // The two header rows, each tick measured in days so a month keeps its own width.
+  groups: { key: string; label: string; days: number }[];
+  ticks: { key: string; label: string; days: number }[];
+  days: number;
+  dayWidth: number;
+  rowHeight: number;
+  today: number | null;
+  labels: {
+    today: string;
+    move(row: string): string;
+    start(row: string): string;
+    end(row: string): string;
+  };
+  onEdit(rowId: string, edit: GanttChartEdit, deltaDays: number): void;
+  footer?: ReactNode;
+}) {
+  const scroller = useRef<HTMLDivElement>(null);
+  const [drag, setDrag] = useState<DragState | null>(null);
+  const markerId = useId();
+  const width = days * dayWidth;
+  // ⚠️ A distance before a drag counts, the same four pixels the kanban needs and for the same
+  // reason: without it every press on a bar is a drag of zero days, and `ganttWrite` would be asked
+  // what a gesture nobody made is worth.
+  const sensors = useSensors(useSensor(PointerSensor, { activationConstraint: { distance: 4 } }));
+
+  // Opening on today rather than on the first day of the window, which is a month of deliberate
+  // air. Once, on mount: a chart that scrolled itself back every time the board changed would take
+  // the reader's place away mid-read.
+  useEffect(() => {
+    const node = scroller.current;
+    if (node === null || today === null) return;
+    node.scrollLeft = Math.max(0, today * dayWidth - node.clientWidth / 3);
+  }, [today, dayWidth]);
+
+  return (
+    <div className="flex min-h-0 flex-1 flex-col">
+      <DndContext
+        sensors={sensors}
+        onDragStart={(event) => {
+          const [edit, rowId] = splitDragId(String(event.active.id));
+          if (edit !== null) setDrag({ rowId, edit, days: 0 });
+        }}
+        // ⚠️ Only `x`. A timeline moves in one direction, and reading `y` would let a bar drift into
+        // a row that means another task.
+        onDragMove={(event) =>
+          setDrag((current) =>
+            current === null ? current : { ...current, days: Math.round(event.delta.x / dayWidth) },
+          )
+        }
+        onDragCancel={() => setDrag(null)}
+        onDragEnd={(event) => {
+          const [edit, rowId] = splitDragId(String(event.active.id));
+          setDrag(null);
+          if (edit === null) return;
+          // The day count the READER saw, recomputed from the same rounding the preview used rather
+          // than carried out of state — so what is written and what was shown cannot come apart.
+          onEdit(rowId, edit, Math.round(event.delta.x / dayWidth));
+        }}
+      >
+        <div ref={scroller} className="min-h-0 flex-1 overflow-auto rounded-lg border">
+          <div className="w-max min-w-full">
+            <div className="sticky top-0 z-20 flex bg-card">
+              <div className="sticky left-0 z-10 w-64 shrink-0 border-r border-b bg-card" />
+              <div style={{ width }}>
+                <div className="flex border-b">
+                  {groups.map((group) => (
+                    <div
+                      key={group.key}
+                      style={{ width: group.days * dayWidth }}
+                      className="shrink-0 border-r py-1 text-xs font-medium"
+                    >
+                      {/* ⚠️ The label sticks to the left edge of what is VISIBLE, not to the left
+                          edge of its own cell. A month is up to 31 columns wide, so scrolled into
+                          the middle of one the reader would see a ruler of day numbers with no
+                          month named anywhere — and a day number without a month is not a date.
+                          The offset clears the sidebar, which is sticky over the same coordinates.
+
+                          ⚠️ No `overflow-hidden` on the cell around it, and that is not a style
+                          choice. An element with a clipping overflow becomes the scrollport its
+                          sticky descendants are measured against, and that box never scrolls — so
+                          the label would sit at a fixed inset instead of following, which is worse
+                          than leaving it alone, because the inset then hides it under the sidebar.
+                          The cell still bounds it: sticky cannot leave its containing block, so the
+                          label stops at the end of its own month. */}
+                      <span className="sticky left-[16.5rem] inline-block max-w-full truncate px-2 align-top">
+                        {group.label}
+                      </span>
+                    </div>
+                  ))}
+                </div>
+                <div className="flex border-b">
+                  {ticks.map((tick) => (
+                    <div
+                      key={tick.key}
+                      style={{ width: tick.days * dayWidth }}
+                      className="shrink-0 truncate border-r px-1 py-1 text-center text-xs text-muted-foreground"
+                    >
+                      {tick.label}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            </div>
+
+            <div className="flex">
+              <div className="sticky left-0 z-10 w-64 shrink-0 border-r bg-card">
+                {rows.map((row) => (
+                  <div
+                    key={row.id}
+                    style={{ height: rowHeight }}
+                    className="flex items-center gap-1 border-b px-2 last:border-b-0"
+                  >
+                    {row.sidebar}
+                  </div>
+                ))}
+              </div>
+
+              <div className="relative" style={{ width, height: rows.length * rowHeight }}>
+                {/* The day grid, drawn from the ticks so a month's own width is what is striped. */}
+                <div className="absolute inset-0 flex">
+                  {ticks.map((tick) => (
+                    <div
+                      key={tick.key}
+                      style={{ width: tick.days * dayWidth }}
+                      className="h-full shrink-0 border-r border-border/60"
+                    />
+                  ))}
+                </div>
+                {rows.map((row, index) => (
+                  <div
+                    key={row.id}
+                    style={{ top: index * rowHeight, height: rowHeight }}
+                    className="absolute right-0 left-0 border-b border-border/60"
+                  />
+                ))}
+                {today === null ? null : (
+                  <div
+                    aria-hidden="true"
+                    style={{ left: today * dayWidth }}
+                    className="absolute top-0 bottom-0 w-px bg-primary"
+                    title={labels.today}
+                  />
+                )}
+
+                {/* ⚠️ The arrows are decoration for a screen reader and information for everybody
+                    else. What they SAY — that this task waits for that one — is in the row beside
+                    them in words, so nothing is only in the picture. */}
+                <svg
+                  aria-hidden="true"
+                  className={cn(
+                    "pointer-events-none absolute inset-0 transition-opacity",
+                    // Stale while a bar is in the air: the bars move and these do not, and a line
+                    // still touching where a bar WAS is a claim about a schedule that no longer
+                    // holds. Faded rather than hidden, so the reader can see they will come back.
+                    drag === null ? "opacity-100" : "opacity-20",
+                  )}
+                  width={width}
+                  height={rows.length * rowHeight}
+                >
+                  <defs>
+                    <marker
+                      id={`${markerId}-open`}
+                      viewBox="0 0 8 8"
+                      refX="7"
+                      refY="4"
+                      markerWidth="6"
+                      markerHeight="6"
+                      orient="auto-start-reverse"
+                    >
+                      <path d="M0 0 L8 4 L0 8 z" className="fill-destructive" />
+                    </marker>
+                    <marker
+                      id={`${markerId}-settled`}
+                      viewBox="0 0 8 8"
+                      refX="7"
+                      refY="4"
+                      markerWidth="6"
+                      markerHeight="6"
+                      orient="auto-start-reverse"
+                    >
+                      <path d="M0 0 L8 4 L0 8 z" className="fill-muted-foreground" />
+                    </marker>
+                  </defs>
+                  {links.map((link) => (
+                    <path
+                      key={link.id}
+                      data-slot="gantt-link"
+                      data-blocking={link.blocking}
+                      d={link.path}
+                      fill="none"
+                      strokeWidth={link.blocking ? 2 : 1}
+                      markerEnd={`url(#${markerId}-${link.blocking ? "open" : "settled"})`}
+                      className={link.blocking ? "stroke-destructive" : "stroke-muted-foreground"}
+                    />
+                  ))}
+                </svg>
+
+                {rows.map((row, index) =>
+                  row.bar === null ? null : (
+                    <Bar
+                      key={row.id}
+                      rowId={row.id}
+                      bar={row.bar}
+                      top={index * rowHeight}
+                      rowHeight={rowHeight}
+                      dayWidth={dayWidth}
+                      drag={drag?.rowId === row.id ? drag : null}
+                      labels={labels}
+                    />
+                  ),
+                )}
+              </div>
+            </div>
+          </div>
+        </div>
+      </DndContext>
+      {footer}
+    </div>
+  );
+}
+
+// `move:task-1` and back. The edit is part of the draggable's id because one context holds three
+// kinds of grab and the difference between them is what gets written.
+function splitDragId(id: string): [GanttChartEdit | null, string] {
+  const at = id.indexOf(":");
+  const edit = id.slice(0, at);
+  if (edit !== "move" && edit !== "start" && edit !== "end") return [null, id];
+  return [edit, id.slice(at + 1)];
+}
+
+function Bar({
+  rowId,
+  bar,
+  top,
+  rowHeight,
+  dayWidth,
+  drag,
+  labels,
+}: {
+  rowId: string;
+  bar: GanttChartBar;
+  top: number;
+  rowHeight: number;
+  dayWidth: number;
+  drag: DragState | null;
+  labels: { move(row: string): string; start(row: string): string; end(row: string): string };
+}) {
+  // ⚠️ The preview clamps at one day, and `ganttWrite` clamps at the same place. A bar that stopped
+  // shrinking while the write carried on past it would save a span the reader never saw.
+  const shift = drag === null ? 0 : drag.days;
+  const from = drag?.edit === "move" || drag?.edit === "start" ? bar.from + shift : bar.from;
+  const length =
+    drag?.edit === "start"
+      ? Math.max(1, bar.days - shift)
+      : drag?.edit === "end"
+        ? Math.max(1, bar.days + shift)
+        : bar.days;
+  // Shrinking from the left cannot push the left edge past the right one.
+  const left = drag?.edit === "start" ? Math.min(from, bar.from + bar.days - 1) : from;
+
+  return (
+    <div
+      data-slot="gantt-bar"
+      data-row={rowId}
+      data-derived={bar.derived}
+      style={{
+        top: top + 4,
+        height: rowHeight - 8,
+        left: left * dayWidth + 1,
+        width: length * dayWidth - 2,
+      }}
+      className="absolute"
+    >
+      <div
+        className={cn(
+          "size-full rounded-md opacity-90",
+          bar.className,
+          // A summary bar reads as a bracket over the work rather than as work of its own, and it
+          // has no grab handles at all — see `derived` above.
+          bar.derived && "h-2 self-center rounded-sm opacity-60",
+        )}
+      />
+      {bar.derived ? null : (
+        <>
+          <Grip
+            id={`move:${rowId}`}
+            edit="move"
+            label={labels.move(rowId)}
+            className="inset-0 cursor-grab"
+          />
+          {/* ⚠️ The two edge grips only exist while there is a bar left between them.
+              They are eight pixels wide and hang a little over each end, so on a bar narrower than
+              that they overlap each other and cover the whole of it — and since the last one drawn
+              wins the pointer, a short bar could then only ever be RESIZED, never moved. At month
+              scale a one-day task is four pixels, so this is the ordinary case there rather than a
+              corner of one. Below the threshold the bar can still be dragged as a whole, and its
+              dates are still typed in the detail panel; above it, both edges are reachable. A
+              control that quietly does something other than what it looks like is worse than one
+              that is not offered. */}
+          {length * dayWidth < 24 ? null : (
+            <>
+              <Grip
+                id={`start:${rowId}`}
+                edit="start"
+                label={labels.start(rowId)}
+                className="top-0 bottom-0 -left-1 w-2 cursor-col-resize rounded-l bg-foreground/0 hover:bg-foreground/20"
+              />
+              <Grip
+                id={`end:${rowId}`}
+                edit="end"
+                label={labels.end(rowId)}
+                className="top-0 -right-1 bottom-0 w-2 cursor-col-resize rounded-r bg-foreground/0 hover:bg-foreground/20"
+              />
+            </>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+/**
+ * One place a bar can be taken hold of.
+ *
+ * ⚠️ Out of the tab order and hidden from a screen reader on purpose, and this is the one decision
+ * here that needs defending rather than explaining. A row already has a tab stop — its title, which
+ * opens the detail panel — and the panel is where a date is TYPED, with the whole keyboard contract
+ * #286 built for it (one write when the field is left, not one per keystroke). Three more stops per
+ * row would put four controls with four names on every task, three of which a keyboard cannot use
+ * for anything the second one does not already do. The drag is a pointer shortcut for an edit that
+ * has a keyboard route, which is the arrangement the kanban settled on for the same reason.
+ */
+function Grip({
+  id,
+  edit,
+  label,
+  className,
+}: {
+  id: string;
+  edit: GanttChartEdit;
+  label: string;
+  className: string;
+}) {
+  const { listeners, setNodeRef } = useDraggable({ id });
+  return (
+    <div
+      ref={setNodeRef}
+      data-slot="gantt-grip"
+      data-edit={edit}
+      aria-hidden="true"
+      title={label}
+      {...listeners}
+      className={cn("absolute touch-none", className)}
+    />
+  );
+}