@skillcdn/console 0.1.17 → 0.1.19

package/src/compat.ts

@@ -0,0 +1,173 @@
+// Whether the command and the console go together (ADR-0025). The command names its version on
+// every request, in the product token of its user-agent; the console answers every request of
+// the API with its own version and the range of command versions it takes, and refuses a
+// command outside the range with `426` and the words to update. One rule for both sides, kept
+// here so that the command and the console read the same one, and narrowed by the console's
+// policy below only, never widened: what the rule promises stays predictable.
+
+/** The product token the command names itself with: `skillcdn-console/<version>`. */
+export const CLIENT_PRODUCT = "skillcdn-console";
+/** On every answer of the API: the console's version. */
+export const VERSION_HEADER = "console-version";
+/** On every answer of the API: the range of command versions the console takes, as npm spells one. */
+export const CLIENT_RANGE_HEADER = "console-client-range";
+
+export interface Version {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+}
+
+/** `x.y.z`, each a number of at most nine digits without a leading zero; no tag, no build. */
+const VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+const MAX_VERSION_LENGTH = 32;
+
+/** A version as the package spells one, or nothing for any other text. */
+export function parseVersion(text: string | null | undefined): Version | undefined {
+  if (typeof text !== "string" || text.length > MAX_VERSION_LENGTH) {
+    return undefined;
+  }
+  const match = VERSION.exec(text);
+  return match === null
+    ? undefined
+    : { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function formatVersion(version: Version): string {
+  return `${version.major}.${version.minor}.${version.patch}`;
+}
+
+/** Negative when `a` is the older, zero when they are the same, positive when `a` is the newer. */
+export function compareVersions(a: Version, b: Version): number {
+  return a.major - b.major || a.minor - b.minor || a.patch - b.patch;
+}
+
+/** A half-open range of versions: from `atLeast` on, and before `below`. */
+export interface VersionRange {
+  readonly atLeast: Version;
+  readonly below: Version;
+}
+
+/** The range as npm spells one: `>=0.1.18 <0.2.0`. */
+export function formatRange(range: VersionRange): string {
+  return `>=${formatVersion(range.atLeast)} <${formatVersion(range.below)}`;
+}
+
+const RANGE = /^>=(\S+) <(\S+)$/;
+const MAX_RANGE_LENGTH = 2 * MAX_VERSION_LENGTH + 4;
+
+/** A range as `formatRange` spells one, or nothing for any other text. */
+export function parseRange(text: string | null | undefined): VersionRange | undefined {
+  if (typeof text !== "string" || text.length > MAX_RANGE_LENGTH) {
+    return undefined;
+  }
+  const match = RANGE.exec(text);
+  const atLeast = parseVersion(match?.[1]);
+  const below = parseVersion(match?.[2]);
+  return atLeast !== undefined && below !== undefined && compareVersions(atLeast, below) < 0
+    ? { atLeast, below }
+    : undefined;
+}
+
+export function inRange(version: Version, range: VersionRange): boolean {
+  return compareVersions(version, range.atLeast) >= 0 && compareVersions(version, range.below) < 0;
+}
+
+/**
+ * The common rule. Before 1.0, a command from the console's own version on and within the
+ * console's minor (`^0.1.18`): any release may change the contract until then (ADR-0007), so the
+ * console's own version is the floor, and the minor is the line. From 1.0, the console's major
+ * and a minor within one of the console's, either way, whatever the patch: a minor adds and a
+ * major breaks, as the version promises from then on.
+ */
+export function commonRange(server: Version): VersionRange {
+  if (server.major === 0) {
+    return { atLeast: server, below: { major: 0, minor: server.minor + 1, patch: 0 } };
+  }
+  return {
+    atLeast: { major: server.major, minor: Math.max(0, server.minor - 1), patch: 0 },
+    below: { major: server.major, minor: server.minor + 2, patch: 0 },
+  };
+}
+
+/**
+ * What the console narrows the common rule by, and nothing it widens it by: a floor above the
+ * rule's, for a contract that moved within what the rule still allows, and versions refused
+ * whatever the rule says, for a release whose command is wrong. Changed with a changeset that
+ * says why.
+ */
+export interface ClientPolicy {
+  /** The oldest command this console answers, when the common rule's floor is too low. */
+  readonly atLeast?: string | undefined;
+  /** Versions of the command refused outright. */
+  readonly refused?: readonly string[] | undefined;
+}
+
+/** The console's policy today: the common rule as it is. */
+export const CLIENT_POLICY: ClientPolicy = {};
+
+/** The range of command versions a console of `server` takes: the common rule, narrowed by the policy's floor where that floor is within it. */
+export function clientRange(server: Version, policy: ClientPolicy = CLIENT_POLICY): VersionRange {
+  const common = commonRange(server);
+  const floor = parseVersion(policy.atLeast);
+  return floor !== undefined &&
+    compareVersions(floor, common.atLeast) > 0 &&
+    compareVersions(floor, common.below) < 0
+    ? { atLeast: floor, below: common.below }
+    : common;
+}
+
+/**
+ * What a command of one version is to a console of another: within the range and the same
+ * (`current`), older (`behind`) or newer (`ahead`), which the console answers; or outside it,
+ * older (`outdated`) or newer (`too_new`), which the console refuses.
+ */
+export type ClientVerdict = "current" | "behind" | "ahead" | "outdated" | "too_new";
+
+export interface ClientJudgement {
+  readonly verdict: ClientVerdict;
+  readonly range: VersionRange;
+}
+
+export function judgeClient(
+  client: Version,
+  server: Version,
+  policy: ClientPolicy = CLIENT_POLICY,
+): ClientJudgement {
+  const range = clientRange(server, policy);
+  const order = compareVersions(client, server);
+  const refused = (policy.refused ?? []).some((text) => {
+    const version = parseVersion(text);
+    return version !== undefined && compareVersions(version, client) === 0;
+  });
+  if (refused) {
+    return { verdict: order > 0 ? "too_new" : "outdated", range };
+  }
+  if (compareVersions(client, range.atLeast) < 0) {
+    return { verdict: "outdated", range };
+  }
+  if (compareVersions(client, range.below) >= 0) {
+    return { verdict: "too_new", range };
+  }
+  return { verdict: order === 0 ? "current" : order < 0 ? "behind" : "ahead", range };
+}
+
+/** What the command sends as its user-agent: its product token, and, in a comment, where it runs. */
+export function userAgentOf(version: string, comment?: string): string {
+  // A comment holds printable ASCII without parentheses or backslashes; nothing else is said.
+  const safe = comment?.replaceAll(/[^\x20-\x27\x2a-\x5b\x5d-\x7e]/g, "").trim();
+  return `${CLIENT_PRODUCT}/${version}${safe === undefined || safe.length === 0 ? "" : ` (${safe})`}`;
+}
+
+const MAX_USER_AGENT_LENGTH = 512;
+const CLIENT_TOKEN = new RegExp(
+  `(?:^|\\s)${CLIENT_PRODUCT}/(\\d{1,9}\\.\\d{1,9}\\.\\d{1,9})(?![\\w.-])`,
+);
+
+/** The version of the command a request's user-agent names, or nothing for any other client. */
+export function clientVersionOf(userAgent: string | null | undefined): Version | undefined {
+  if (typeof userAgent !== "string") {
+    return undefined;
+  }
+  return parseVersion(CLIENT_TOKEN.exec(userAgent.slice(0, MAX_USER_AGENT_LENGTH))?.[1]);
+}

package/src/components/board.tsx

@@ -1,4 +1,11 @@
-import type { ReactNode } from "react";
+import {
+  type ReactNode,
+  type PointerEvent as ReactPointerEvent,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
 import {
   type RestCategory,
   type RestGoal,
@@ -23,8 +30,10 @@ import {
 // The board: one column per state, the tasks in it, the sooner due first and the newest after.
 // A card says what a person needs at a glance and nothing more: the number and the title, the
 // category, what is due, who is on it, and what blocks it. Whether an agent is at it is not
-// said, since the board cannot know (ADR-0020); the task's page shows its runs. It takes its
-// data as props and nothing from the network; what it is told on a click goes back up.
+// said, since the board cannot know (ADR-0020); the task's page shows its runs. A card is moved
+// to another column by its grip, with a mouse or a finger, and by the select on it with the
+// keyboard; either way the move goes back up and the board is told. It takes its data as props
+// and nothing from the network; what it is told on a click goes back up.
 
 export interface BoardProps {
   readonly tasks: readonly RestTask[];
@@ -37,6 +46,31 @@ export interface BoardProps {
   readonly today?: string | undefined;
   /** What a column shows when it has nothing; the way to write the first task, for example. */
   readonly empty?: ReactNode;
+  /** Where the tasks put away are (ADR-0029); given, the done and dropped columns lead there. */
+  readonly archiveHref?: string | undefined;
+}
+
+/** How far a pointer travels on the grip before the card is dragged, and not pressed. */
+const DRAG_SLACK = 4;
+/** How near the pointer comes to the board's edge before the board scrolls to show more columns. */
+const EDGE = 48;
+const EDGE_STEP = 12;
+
+/** The state a column stands for, read off its `data-column`; nothing for a value that is not one. */
+export function columnStateOf(value: string | null | undefined): TaskState | undefined {
+  return TASK_STATES.find((state) => state === value);
+}
+
+/** A card on its way to another column. */
+interface Drag {
+  readonly task: RestTask;
+  readonly from: { readonly x: number; readonly y: number };
+  readonly x: number;
+  readonly y: number;
+  /** Whether the pointer has travelled far enough for this to be a drag. */
+  readonly moving: boolean;
+  /** The column under the pointer, or none. */
+  readonly over: TaskState | undefined;
 }
 
 export function TaskCard(props: {
@@ -45,11 +79,30 @@ export function TaskCard(props: {
   readonly onOpen: (task: RestTask) => void;
   readonly onMove?: ((task: RestTask, state: TaskState) => void) | undefined;
   readonly today?: string | undefined;
+  /** Called when the card's grip is pressed, to drag it to another column; left out, the card has no grip. */
+  readonly onGrip?: ((task: RestTask, event: ReactPointerEvent<HTMLElement>) => void) | undefined;
+  /** Whether the card is on its way to another column. */
+  readonly dragging?: boolean | undefined;
 }) {
   const words = useWords();
   const { task } = props;
   return (
-    <article className="sc-card" aria-label={`#${task.number} ${task.title}`}>
+    <article
+      className={cx("sc-card", props.dragging === true && "sc-card-dragging")}
+      aria-label={`#${task.number} ${task.title}`}
+    >
+      {props.onGrip !== undefined && (
+        <button
+          type="button"
+          className="sc-card-grip"
+          title={words.board.grip}
+          aria-hidden="true"
+          tabIndex={-1}
+          onPointerDown={(event) => props.onGrip?.(task, event)}
+        >
+          ⋮⋮
+        </button>
+      )}
       <a
         className="sc-card-title"
         href={props.href}
@@ -111,19 +164,101 @@ export function byDue(a: RestTask, b: RestTask): number {
 
 export function Board(props: BoardProps) {
   const words = useWords();
+  const { onMove } = props;
+  const board = useRef<HTMLDivElement>(null);
+  const [drag, setDrag] = useState<Drag | null>(null);
+  // What the pointer's release reads, so that the move is made outside a state update.
+  const current = useRef<Drag | null>(null);
+  current.current = drag;
+
+  const grip = useCallback((task: RestTask, event: ReactPointerEvent<HTMLElement>) => {
+    if (event.pointerType === "mouse" && event.button !== 0) {
+      return;
+    }
+    // The press is the drag's beginning and nothing else: no text is selected on the way.
+    event.preventDefault();
+    const from = { x: event.clientX, y: event.clientY };
+    setDrag({ task, from, x: from.x, y: from.y, moving: false, over: undefined });
+  }, []);
+
+  // While a card is held, the pointer is followed over the whole document: the column under it
+  // is marked, the board scrolls when the pointer nears its edge, and the release moves the task.
+  const held = drag !== null;
+  useEffect(() => {
+    if (!held) {
+      return;
+    }
+    const follow = (event: PointerEvent) => {
+      const { clientX: x, clientY: y } = event;
+      const under = document.elementFromPoint(x, y)?.closest<HTMLElement>("[data-column]");
+      setDrag((before) => {
+        if (before === null) {
+          return before;
+        }
+        const moving =
+          before.moving || Math.hypot(x - before.from.x, y - before.from.y) > DRAG_SLACK;
+        return {
+          ...before,
+          x,
+          y,
+          moving,
+          over: moving ? columnStateOf(under?.dataset.column) : undefined,
+        };
+      });
+      const element = board.current;
+      if (element !== null) {
+        const rect = element.getBoundingClientRect();
+        if (x < rect.left + EDGE) {
+          element.scrollLeft -= EDGE_STEP;
+        } else if (x > rect.right - EDGE) {
+          element.scrollLeft += EDGE_STEP;
+        }
+      }
+    };
+    const release = () => {
+      const last = current.current;
+      if (last?.moving === true && last.over !== undefined && last.over !== last.task.state) {
+        onMove?.(last.task, last.over);
+      }
+      setDrag(null);
+    };
+    window.addEventListener("pointermove", follow);
+    window.addEventListener("pointerup", release);
+    window.addEventListener("pointercancel", release);
+    return () => {
+      window.removeEventListener("pointermove", follow);
+      window.removeEventListener("pointerup", release);
+      window.removeEventListener("pointercancel", release);
+    };
+  }, [held, onMove]);
+
+  /** The drag under way, once the pointer has travelled; nothing while a card is merely pressed. */
+  const dragging = drag?.moving === true ? drag : null;
   return (
-    <div className="sc-board">
+    <div ref={board} className={cx("sc-board", dragging !== null && "sc-board-dragging")}>
       {TASK_STATES.map((state) => {
         const tasks = props.tasks.filter((task) => task.state === state).sort(byDue);
         return (
           <section
             key={state}
-            className={cx("sc-column", `sc-column-${state}`)}
+            className={cx(
+              "sc-column",
+              `sc-column-${state}`,
+              dragging?.over === state && "sc-column-over",
+            )}
             aria-label={words.vocabulary.state[state]}
+            data-column={state}
           >
             <header className="sc-column-header">
               <h2 className="sc-column-title">{words.vocabulary.state[state]}</h2>
-              <span className="sc-column-count">{tasks.length}</span>
+              <span className="sc-column-meta">
+                {props.archiveHref !== undefined && (state === "done" || state === "dropped") && (
+                  <a className="sc-column-archive" href={props.archiveHref}>
+                    {words.board.archive}
+                  </a>
+                )}
+                <span className="sc-column-count">{tasks.length}</span>
+              </span>
             </header>
             <div className="sc-column-body">
               {tasks.map((task) => (
@@ -132,8 +267,10 @@ export function Board(props: BoardProps) {
                   task={task}
                   href={props.taskHref(task)}
                   onOpen={props.onOpen}
-                  onMove={props.onMove}
+                  onMove={onMove}
                   today={props.today}
+                  onGrip={onMove === undefined ? undefined : grip}
+                  dragging={dragging?.task.id === task.id}
                 />
               ))}
               {tasks.length === 0 && state === "idea" && props.empty}
@@ -141,6 +278,15 @@ export function Board(props: BoardProps) {
           </section>
         );
       })}
+      {dragging !== null && (
+        <div
+          className="sc-drag-ghost"
+          aria-hidden="true"
+          style={{ transform: `translate(${dragging.x + 12}px, ${dragging.y + 12}px)` }}
+        >
+          <span className="sc-card-number">#{dragging.task.number}</span> {dragging.task.title}
+        </div>
+      )}
     </div>
   );
 }

package/src/components/calendar.tsx

@@ -48,9 +48,11 @@ export interface CalendarProps {
   readonly today?: string | undefined;
   /** The workspace's categories, for the legend to say what the colours mean. */
   readonly categories?: readonly RestCategory[] | undefined;
-  /** The project's goals, so that the task under the pointer is shown with its goal's title. */
+  /** The project's goals, so that the task under the pointer is shown with its goal's title, and, given `goalHref`, so that each goal marks its target day. */
   readonly goals?: readonly RestGoal[] | undefined;
   readonly taskHref: (task: RestTask) => string;
+  /** Where a goal's page is: given, the goals mark their target days on the month (ADR-0026). */
+  readonly goalHref?: ((goal: RestGoal) => string) | undefined;
   /** Where the calendar is on another month. */
   readonly monthHref: (month: string) => string;
 }
@@ -324,12 +326,32 @@ interface WeekRowProps {
   readonly pointed: Pointed | null;
   /** The project's goals, so that the item under the pointer names its goal; none across projects. */
   readonly goals?: readonly RestGoal[] | undefined;
+  /** The goals whose target day is each day, where the goals mark the month. */
+  readonly goalsOn?: ReadonlyMap<string, readonly RestGoal[]> | undefined;
+  readonly goalHref?: ((goal: RestGoal) => string) | undefined;
   /** The pointer, or the focus, arrived on a task's item on a day. */
   readonly onPoint: (task: RestTask, day: string, item: HTMLElement) => void;
   /** It left. */
   readonly onLeave: () => void;
 }
 
+/** The goals that aim at each day, by day: those with a target day, still planned or worked towards. */
+function goalsOnDays(goals: readonly RestGoal[]): ReadonlyMap<string, readonly RestGoal[]> {
+  const on = new Map<string, RestGoal[]>();
+  for (const goal of goals) {
+    if (goal.dueOn === null || goal.state === "dropped") {
+      continue;
+    }
+    const list = on.get(goal.dueOn);
+    if (list === undefined) {
+      on.set(goal.dueOn, [goal]);
+    } else {
+      list.push(goal);
+    }
+  }
+  return on;
+}
+
 /** One week as a row of cells: the bars across the days in their lanes, then the tasks on each day. */
 function WeekRow(props: WeekRowProps) {
   const { week, segments, now } = props;
@@ -361,6 +383,21 @@ function WeekRow(props: WeekRowProps) {
           )}
         >
           <span className="sc-calendar-day">{Number(cell.day.slice(8))}</span>
+          {props.goalHref !== undefined &&
+            (props.goalsOn?.get(cell.day) ?? []).map((goal) => (
+              <a
+                key={goal.id}
+                className={cx(
+                  "sc-calendar-goal",
+                  `sc-category-${goal.category?.color ?? "gray"}`,
+                  goal.state === "done" && "sc-calendar-over",
+                )}
+                href={props.goalHref?.(goal)}
+              >
+                <span className="sc-calendar-flag" aria-hidden="true" />
+                <span className="sc-calendar-task-title">{goal.title}</span>
+              </a>
+            ))}
           {Array.from({ length: lanes }, (_, lane) => {
             const segment = segments.find(
               (candidate) =>
@@ -435,6 +472,7 @@ export function Calendar(props: CalendarProps) {
   const firstDay = firstDayOfWeek(tag);
   const weeks = monthGrid(props.month, firstDay);
   const on = onDays(props.tasks);
+  const goalsOn = props.goalHref === undefined ? undefined : goalsOnDays(props.goals ?? []);
   const inMonth = (day: string) => monthOf(day) === props.month;
   const monthWeeks = weeks.map((week) => ({ week, segments: weekSegments(week, props.tasks) }));
   const nothing =
@@ -492,6 +530,8 @@ export function Calendar(props: CalendarProps) {
               taskHref={props.taskHref}
               pointed={pointed}
               goals={props.goals}
+              goalsOn={goalsOn}
+              goalHref={props.goalHref}
               onPoint={point}
               onLeave={leave}
               people

package/src/components/comments.tsx

@@ -12,12 +12,14 @@ import {
 import { useWords } from "../i18n/index.js";
 import { DecisionCard, type DecisionCardProps } from "./decision-list.js";
 import { Markdown } from "./markdown.js";
+import { Lightbox, PictureThumb, usePicture } from "./pictures.js";
 import { RunCard } from "./runs.js";
 import { Button, formatBytes, PersonChip, personName, Time } from "./ui.js";
 
 // The discussion on a task (ADR-0024): what people and agents said about it, each word with
 // the files put in it, read in one thread with the runs on the task and the decisions about
-// it, in the order they came. Takes its data as props and nothing from the network.
+// it, in the order they came. A picture is a thumbnail that opens large over the page. Takes
+// its data as props and nothing from the network.
 
 /** The kinds of picture the pages show in place: what a browser renders and cannot run. */
 const PICTURE_TYPES: ReadonlySet<string> = new Set([
@@ -48,6 +50,7 @@ export interface CommentCardProps {
 export function CommentCard(props: CommentCardProps) {
   const words = useWords();
   const { comment } = props;
+  const pictures = usePicture();
   const hrefOf = (file: RestCommentFile) => props.fileHref?.(file);
   // A picture the text names by its file name is shown where the text puts it; the rest of
   // the files follow the text, pictures in place and everything else as a link.
@@ -77,7 +80,12 @@ export function CommentCard(props: CommentCardProps) {
         </span>
       </header>
       {comment.body.trim().length > 0 && (
-        <Markdown source={comment.body} docHref={props.docHref} fileSrc={named} />
+        <Markdown
+          source={comment.body}
+          docHref={props.docHref}
+          fileSrc={named}
+          onOpenPicture={pictures.open}
+        />
       )}
       {following.length > 0 && (
         <ul className="sc-comment-files" aria-label={words.comments.files}>
@@ -87,14 +95,15 @@ export function CommentCard(props: CommentCardProps) {
             if (href !== undefined && isPicture(file.contentType)) {
               return (
                 <li key={attached.id} className="sc-comment-picture">
-                  <a href={href} rel="noopener nofollow ugc" target="_blank">
-                    <img
-                      src={href}
-                      alt={words.comments.picture(file.name)}
-                      loading="lazy"
-                      decoding="async"
-                    />
-                  </a>
+                  <PictureThumb
+                    picture={{
+                      src: href,
+                      alt: words.comments.picture(file.name),
+                      name: file.name,
+                      size: file.size,
+                    }}
+                    onOpen={pictures.open}
+                  />
                   <span className="sc-muted">
                     {file.name}, {formatBytes(file.size)}
                   </span>
@@ -116,6 +125,7 @@ export function CommentCard(props: CommentCardProps) {
           })}
         </ul>
       )}
+      <Lightbox picture={pictures.shown} onClose={pictures.close} />
     </article>
   );
 }

package/src/components/event-feed.tsx

@@ -78,6 +78,10 @@ export function describeEvent(event: RestEvent, words: Messages = en): string {
       return feed.event.taskUpdated(fields, task);
     case "task.commented":
       return feed.event.taskCommented(task, data.excerpt);
+    case "task.archived":
+      return feed.event.taskArchived(task);
+    case "task.restored":
+      return feed.event.taskRestored(task);
     case "decision.raised":
       return feed.event.decisionRaised(question);
     case "decision.answered":