@skillcdn/console 0.1.8 → 0.1.10

package/src/data.ts

@@ -6,6 +6,9 @@ import {
   EVENT_KINDS,
   type FileUpload,
   type RestAnswerInput,
+  type RestCategory,
+  type RestCategoryInput,
+  type RestCategoryPatch,
   type RestConnectRequest,
   type RestDecision,
   type RestDecisionInput,
@@ -14,6 +17,9 @@ import {
   type RestDocumentInput,
   type RestDocuments,
   type RestEvent,
+  type RestGoal,
+  type RestGoalInput,
+  type RestGoalPatch,
   type RestMe,
   type RestMember,
   type RestMemberInput,
@@ -35,6 +41,7 @@ import {
   type RestTokens,
   type RestVersion,
   type RestVersions,
+  type RestWork,
   restEventSchema,
 } from "./api.js";
 
@@ -64,6 +71,15 @@ export interface ConsoleActions {
   answerDecision(id: string, input: RestAnswerInput): Promise<RestDecision>;
   /** Grows a decision's record: its context, or what followed. */
   updateDecision(id: string, patch: RestDecisionPatch): Promise<RestDecision>;
+  /** Sets a goal on the roadmap of the project the page is on; for an owner. */
+  createGoal(input: RestGoalInput): Promise<RestGoal>;
+  updateGoal(id: string, patch: RestGoalPatch): Promise<RestGoal>;
+  /** What is on the person's plate across their projects, read when the page asks. */
+  work(signal?: AbortSignal): Promise<RestWork>;
+  /** The categories tasks are sorted into: kept by an administrator. */
+  createCategory(input: RestCategoryInput): Promise<RestCategory>;
+  updateCategory(key: string, patch: RestCategoryPatch): Promise<RestCategory>;
+  removeCategory(key: string): Promise<void>;
   /** A folder's pages and folders, or the pages a search finds, in the project the page is on. */
   documents(filter?: DocumentFilter, signal?: AbortSignal): Promise<RestDocuments>;
   document(path: string, signal?: AbortSignal): Promise<RestDocument>;
@@ -104,6 +120,8 @@ export interface ConsoleData {
   /** The projects the person may see, by name. */
   readonly projects: readonly RestProject[];
   readonly people: readonly RestPerson[];
+  /** The categories tasks are sorted into, by name. */
+  readonly categories: readonly RestCategory[];
   /** The tokens of whoever is signed in, newest first. */
   readonly tokens: readonly RestToken[];
   /** The project the page is on, once loaded; `undefined` while loading, or when the page is on none. */
@@ -116,6 +134,8 @@ export interface ConsoleData {
   readonly live: boolean;
   readonly tasks: readonly RestTask[];
   readonly decisions: readonly RestDecision[];
+  /** The roadmap of the project: its goals, the active first. */
+  readonly goals: readonly RestGoal[];
   /** The runs of the project, newest first. */
   readonly runs: readonly RestRun[];
   /** The project's events, oldest first. */
@@ -161,6 +181,7 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
   const [loaded, setLoaded] = useState(false);
   const [projects, setProjects] = useState<readonly RestProject[]>([]);
   const [people, setPeople] = useState<readonly RestPerson[]>([]);
+  const [categories, setCategories] = useState<readonly RestCategory[]>([]);
   const [tokens, setTokens] = useState<readonly RestToken[]>([]);
   const [project, setProject] = useState<RestProject | undefined>(undefined);
   const [projectLoaded, setProjectLoaded] = useState(false);
@@ -168,6 +189,7 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
   const [live, setLive] = useState(false);
   const [tasks, setTasks] = useState<readonly RestTask[]>([]);
   const [decisions, setDecisions] = useState<readonly RestDecision[]>([]);
+  const [goals, setGoals] = useState<readonly RestGoal[]>([]);
   const [runs, setRuns] = useState<readonly RestRun[]>([]);
   const [events, setEvents] = useState<readonly RestEvent[]>([]);
   const [members, setMembers] = useState<readonly RestMember[]>([]);
@@ -181,15 +203,17 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
   /** Loads the workspace's lists again. What fails stays as it was. */
   const refreshWorkspace = useCallback(
     async (signal?: AbortSignal) => {
-      const [nextProjects, nextPeople] = await Promise.all([
+      const [nextProjects, nextPeople, nextCategories] = await Promise.all([
         client.projects(signal),
         client.people(signal),
+        client.categories(signal),
       ]);
       if (signal?.aborted === true) {
         return;
       }
       setProjects(nextProjects.items);
       setPeople(nextPeople.items);
+      setCategories(nextCategories.items);
     },
     [client],
   );
@@ -201,19 +225,22 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
         return;
       }
       const scope = client.project(projectKey);
-      const [nextProject, nextTasks, nextDecisions, nextRuns, nextMembers] = await Promise.all([
-        scope.get(signal),
-        scope.tasks(undefined, signal),
-        scope.decisions(undefined, signal),
-        scope.runs(undefined, signal),
-        scope.members(signal),
-      ]);
+      const [nextProject, nextTasks, nextDecisions, nextGoals, nextRuns, nextMembers] =
+        await Promise.all([
+          scope.get(signal),
+          scope.tasks(undefined, signal),
+          scope.decisions(undefined, signal),
+          scope.goals(signal),
+          scope.runs(undefined, signal),
+          scope.members(signal),
+        ]);
       if (signal?.aborted === true) {
         return;
       }
       setProject(nextProject);
       setTasks(nextTasks.items);
       setDecisions(nextDecisions.items);
+      setGoals(nextGoals.items);
       setRuns(nextRuns.items);
       setMembers(nextMembers.items);
     },
@@ -274,6 +301,7 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
     setProjectError(undefined);
     setTasks([]);
     setDecisions([]);
+    setGoals([]);
     setRuns([]);
     setEvents([]);
     setMembers([]);
@@ -411,6 +439,31 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
         );
         return decision;
       },
+      async createGoal(input) {
+        const goal = await scope().createGoal(input);
+        await refreshProject();
+        return goal;
+      },
+      async updateGoal(id, patch) {
+        const goal = await scope().updateGoal(id, patch);
+        setGoals((current) => current.map((candidate) => (candidate.id === id ? goal : candidate)));
+        return goal;
+      },
+      work: (signal) => client.work(signal),
+      async createCategory(input) {
+        const category = await client.createCategory(input);
+        setCategories((await client.categories()).items);
+        return category;
+      },
+      async updateCategory(key, patch) {
+        const category = await client.updateCategory(key, patch);
+        setCategories((await client.categories()).items);
+        return category;
+      },
+      async removeCategory(key) {
+        await client.removeCategory(key);
+        setCategories((current) => current.filter((category) => category.key !== key));
+      },
       documents: (filter, signal) => scope().documents(filter, signal),
       document: (path, signal) => scope().document(path, signal),
       writeDocument: (path, input) => scope().writeDocument(path, input),
@@ -476,6 +529,7 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
     loaded,
     projects,
     people,
+    categories,
     tokens,
     project,
     projectLoaded,
@@ -483,6 +537,7 @@ export function useConsoleData(client: ConsoleClient, projectKey: string | undef
     live,
     tasks,
     decisions,
+    goals,
     runs,
     events,
     members,

package/src/dates.ts

@@ -0,0 +1,143 @@
+// Days, as the plan is made in (ADR-0019): `2026-10-20`, read and written as the strings they
+// are, so that a deadline is the same day wherever the people are. The browser's own clock says
+// which day is today; nothing here looks at it unless asked.
+
+const DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+/** Whether a string is a day as the API spells one. */
+export function isDay(value: string | null | undefined): value is string {
+  return value !== null && value !== undefined && DAY.test(value);
+}
+
+/** A day from a local date: the date the browser's clock shows, not the UTC one. */
+export function dayOf(date: Date): string {
+  const year = String(date.getFullYear()).padStart(4, "0");
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/** Today, by the browser's clock. */
+export function today(now: Date = new Date()): string {
+  return dayOf(now);
+}
+
+/** A local date at noon of the day, so that a daylight-saving change never moves it a day. */
+export function dateOf(day: string): Date {
+  const match = DAY.exec(day);
+  if (match === null) {
+    return new Date(Number.NaN);
+  }
+  return new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]), 12);
+}
+
+/** The day `count` days after `day`; negative counts go back. */
+export function addDays(day: string, count: number): string {
+  const date = dateOf(day);
+  date.setDate(date.getDate() + count);
+  return dayOf(date);
+}
+
+/** How many days `to` is after `from`; negative when it is before. */
+export function daysBetween(from: string, to: string): number {
+  const millis = dateOf(to).getTime() - dateOf(from).getTime();
+  return Math.round(millis / 86_400_000);
+}
+
+/** The month a day is in: `2026-10`. */
+export function monthOf(day: string): string {
+  return day.slice(0, 7);
+}
+
+/** Whether a string is a month as the calendar's address spells one. */
+export function isMonth(value: string | null | undefined): value is string {
+  return value !== null && value !== undefined && /^\d{4}-(0[1-9]|1[0-2])$/.test(value);
+}
+
+/** The month `count` months after `month`; negative counts go back. */
+export function addMonths(month: string, count: number): string {
+  const year = Number(month.slice(0, 4));
+  const index = Number(month.slice(5, 7)) - 1 + count;
+  const date = new Date(year, index, 1, 12);
+  return `${String(date.getFullYear()).padStart(4, "0")}-${String(date.getMonth() + 1).padStart(2, "0")}`;
+}
+
+/** The weekday a week begins on where the language is spoken: 1 for Monday, 7 for Sunday. */
+export function firstDayOfWeek(language: string): number {
+  try {
+    const locale = new Intl.Locale(language) as Intl.Locale & {
+      readonly weekInfo?: { readonly firstDay: number };
+      readonly getWeekInfo?: () => { readonly firstDay: number };
+    };
+    const info = locale.getWeekInfo?.() ?? locale.weekInfo;
+    if (info !== undefined && info.firstDay >= 1 && info.firstDay <= 7) {
+      return info.firstDay;
+    }
+  } catch {
+    // A tag the browser does not know: the week begins on Monday.
+  }
+  return 1;
+}
+
+/** One cell of a month's grid: the day, and whether it is of the month shown or a neighbour's. */
+export interface GridDay {
+  readonly day: string;
+  readonly inMonth: boolean;
+}
+
+/**
+ * The weeks of a month as a calendar shows them: full weeks, beginning on `firstDay` (1 for
+ * Monday, 7 for Sunday), with the neighbouring months' days filling the first and the last.
+ */
+export function monthGrid(month: string, firstDay = 1): GridDay[][] {
+  const first = `${month}-01`;
+  const start = dateOf(first);
+  // getDay: 0 for Sunday; the grid counts Monday as 1 and Sunday as 7.
+  const weekday = start.getDay() === 0 ? 7 : start.getDay();
+  const back = (weekday - firstDay + 7) % 7;
+  let cursor = addDays(first, -back);
+  const weeks: GridDay[][] = [];
+  do {
+    const week: GridDay[] = [];
+    for (let column = 0; column < 7; column += 1) {
+      week.push({ day: cursor, inMonth: monthOf(cursor) === month });
+      cursor = addDays(cursor, 1);
+    }
+    weeks.push(week);
+  } while (monthOf(cursor) === month);
+  return weeks;
+}
+
+/** The weekdays in the order a week is shown, from `firstDay`, as the grid counts them. */
+export function weekdays(firstDay = 1): number[] {
+  return Array.from({ length: 7 }, (_, index) => ((firstDay - 1 + index) % 7) + 1);
+}
+
+/** A day as people read one in a language: the month and the day, with the year when it is not this year's. */
+export function formatDay(day: string, language?: string, now: Date = new Date()): string {
+  const date = dateOf(day);
+  if (Number.isNaN(date.getTime())) {
+    return day;
+  }
+  return date.toLocaleDateString(language, {
+    month: "short",
+    day: "numeric",
+    ...(date.getFullYear() === now.getFullYear() ? {} : { year: "numeric" }),
+  });
+}
+
+/** A month as people read one: the month and the year. */
+export function formatMonth(month: string, language?: string): string {
+  const date = dateOf(`${month}-01`);
+  if (Number.isNaN(date.getTime())) {
+    return month;
+  }
+  return date.toLocaleDateString(language, { month: "long", year: "numeric" });
+}
+
+/** A weekday as people read one, short, as the grid counts them: 1 for Monday, 7 for Sunday. */
+export function formatWeekday(weekday: number, language?: string): string {
+  // The week of 2024-01-01 began on a Monday.
+  const date = new Date(2024, 0, weekday, 12);
+  return date.toLocaleDateString(language, { weekday: "short" });
+}

package/src/i18n/en.ts

@@ -1,5 +1,7 @@
 import type { SignInFailure } from "../routes.js";
 import type {
+  CategoryColor,
+  GoalState,
   PersonRole,
   ProjectRole,
   ProjectVisibility,
@@ -47,6 +49,22 @@ export const en = {
       failed: "Failed",
       abandoned: "Abandoned",
     } satisfies Record<RunStatus, string>,
+    goalState: {
+      planned: "Planned",
+      active: "Active",
+      done: "Reached",
+      dropped: "Dropped",
+    } satisfies Record<GoalState, string>,
+    categoryColor: {
+      gray: "Gray",
+      blue: "Blue",
+      green: "Green",
+      orange: "Orange",
+      pink: "Pink",
+      purple: "Purple",
+      teal: "Teal",
+      yellow: "Yellow",
+    } satisfies Record<CategoryColor, string>,
   },
 
   common: {
@@ -81,9 +99,13 @@ export const en = {
 
   nav: {
     projects: "Projects",
+    work: "My work",
     people: "People",
     agents: "Agents",
+    categories: "Categories",
     board: "Board",
+    roadmap: "Roadmap",
+    calendar: "Calendar",
     docs: "Docs",
     decisions: "Decisions",
     feed: "Feed",
@@ -187,7 +209,25 @@ export const en = {
     decisionsTitle: "Decisions waiting for a person",
     agentAtWork: "agent at work",
     agentAtWorkTitle: "An agent is at work on it",
-    links: (n: number) => count(n, "link", "links"),
+    agentSince: (agent: string, since: string) => `${agent}, at work since ${since}`,
+    filters: {
+      aria: "Narrow the board",
+      everyone: "Everyone",
+      mine: "Mine",
+      anyCategory: "Any category",
+      noCategory: "No category",
+      anyGoal: "Any goal",
+      noGoal: "No goal",
+      clear: "Show everything",
+      showing: (n: number, of: number) => `${n} of ${count(of, "task", "tasks")}`,
+    },
+    due: {
+      overdue: (days: number) => `${count(days, "day", "days")} overdue`,
+      today: "Due today",
+      tomorrow: "Due tomorrow",
+      inDays: (days: number) => `Due in ${count(days, "day", "days")}`,
+      on: (day: string) => `Due ${day}`,
+    },
   },
 
   task: {
@@ -213,6 +253,19 @@ export const en = {
     history: "What happened",
     subtasks: "Subtasks",
     partOfIt: "Part of it",
+    category: "Category",
+    goal: "Goal",
+    plan: "Plan",
+    planned: (from: string | undefined, to: string | undefined) =>
+      from !== undefined && to !== undefined
+        ? `${from} to ${to}`
+        : from !== undefined
+          ? `from ${from}`
+          : to !== undefined
+            ? `by ${to}`
+            : "",
+    started: "Started",
+    done: "Done",
     form: {
       title: "Title",
       body: "Body",
@@ -221,6 +274,12 @@ export const en = {
       priority: "Priority",
       assignee: "Assignee",
       partOf: "Part of",
+      category: "Category",
+      noCategory: "No category",
+      goal: "Goal",
+      noGoal: "No goal",
+      startsOn: "Starts on",
+      dueOn: "Due on",
       links: "Links",
       label: "Label",
       addLink: "Add a link",
@@ -244,6 +303,10 @@ export const en = {
     },
     waiting: "Waiting",
     answered: "Answered",
+    record: "The record",
+    recordLead:
+      "Every decision answered, newest first: what was asked, what was chosen, by whom. Open one for its context, its rationale and what followed.",
+    openRecord: "Open",
     waitingForPerson: "Waiting for a person.",
     options: "Options",
     notePlaceholder: "A word about it, if any",
@@ -271,6 +334,112 @@ export const en = {
     },
   },
 
+  calendar: {
+    title: "Calendar",
+    lead: "The tasks by the day they are due. A task with a start is shown from it; one with no day waits at the bottom to be given one.",
+    grid: "The month",
+    previous: "The month before",
+    next: "The month after",
+    thisMonth: "This month",
+    nothingDue: "Nothing is due this month.",
+    overdue: "Overdue",
+    nothingOverdue: "Nothing is overdue.",
+    unscheduled: "No day set",
+    allScheduled: "Every open task has a day.",
+    starts: "starts",
+    workload: {
+      title: "Who has what",
+      lead: "The open tasks of each person, and what of them is late or due within the week.",
+      person: "Person",
+      open: "Open",
+      inProgress: "In progress",
+      dueSoon: "Due in 7 days",
+      overdue: "Overdue",
+      unassigned: "Nobody's yet",
+    },
+  },
+
+  roadmap: {
+    title: "Roadmap",
+    lead: "What the project works towards: each goal with the day it is meant to be reached by, and how far its tasks are. Progress is read from the board as it stands.",
+    setGoal: "Set a goal",
+    setGoalAria: "Set a goal",
+    editAria: "Change the goal",
+    one: "Goal",
+    all: "All goals",
+    empty: {
+      title: "No goal is set yet",
+      body: "An owner sets the first one: what to reach, and by when. Tasks are then written towards it.",
+    },
+    noSuch: {
+      title: "No such goal",
+      body: "It may belong to another project, or the link is wrong.",
+    },
+    onlyOwner: {
+      title: "Only an owner sets the roadmap",
+      body: "Ask one of the project's owners, or a workspace administrator.",
+    },
+    progress: (done: number, of: number) => `${done} of ${count(of, "task", "tasks")} done`,
+    inProgress: (n: number) => `${n} in progress`,
+    noTasks: "No task works towards it yet.",
+    tasks: "Tasks",
+    target: "Target",
+    noTarget: "No target day",
+    setBy: "Set by",
+    state: "State",
+    nothingMore: "Nothing more was written about it.",
+    form: {
+      title: "Title",
+      body: "What reaching it means",
+      bodyPlaceholder: "What is true once the goal is reached, in Markdown.",
+      state: "State",
+      dueOn: "Target day",
+      set: "Set the goal",
+    },
+  },
+
+  work: {
+    title: "My work",
+    lead: "What is on your plate across your projects: the open tasks assigned to you, by the day they are due, and the decisions that wait for a person.",
+    loading: "Loading your work",
+    couldNotLoad: "Your work could not be loaded.",
+    empty: {
+      title: "Nothing is assigned to you",
+      body: "A task assigned to you in any project you may see shows up here.",
+    },
+    overdue: "Overdue",
+    thisWeek: "Due this week",
+    later: "Later",
+    noDay: "No day set",
+    decisions: "Decisions waiting for a person",
+    noDecisions: "No decision waits.",
+    inProject: (project: string) => `in ${project}`,
+  },
+
+  categories: {
+    title: "Categories",
+    lead: "The kinds of work tasks are sorted into, the same in every project. A task carries one, the board is narrowed by one, and an administrator keeps the list.",
+    onlyAdmin: "An administrator adds, changes and removes them; everyone else reads them here.",
+    list: "Categories",
+    add: "Add a category",
+    addAria: "Add a category",
+    empty: {
+      title: "No categories",
+      body: "An administrator adds the first one here.",
+    },
+    inUse: "A category tasks are sorted into cannot be removed until they are moved out of it.",
+    form: {
+      name: "Name",
+      key: "Key",
+      keyHint:
+        "Lowercase letters, digits and hyphens: what the command and the filters say. It does not change.",
+      color: "Colour",
+      add: "Add",
+    },
+    nameOf: (key: string) => `Name of ${key}`,
+    colorOf: (key: string) => `Colour of ${key}`,
+  },
+
   feed: {
     title: "What happened",
     list: "What happened",
@@ -284,6 +453,8 @@ export const en = {
     something: "something",
     aQuestion: "a question",
     aFile: "a file",
+    aGoal: "a goal",
+    aCategory: "a category",
     thePage: (name: string) => `the page ${name}`.trimEnd(),
     role: {
       admin: "an administrator",
@@ -303,6 +474,12 @@ export const en = {
       visibility: "who is a member",
       skillsAddress: "the skills address",
       outcome: "what followed",
+      category: "the category",
+      goalId: "the goal",
+      startsOn: "the start",
+      dueOn: "the due date",
+      state: "the state",
+      color: "the colour",
     } as Readonly<Record<string, string>>,
     event: {
       personJoined: () => "joined the board",
@@ -315,6 +492,12 @@ export const en = {
       memberChanged: (login: string, role: string, project: string) =>
         `made ${login} ${role} of ${project}`,
       memberRemoved: (login: string, project: string) => `removed ${login} from ${project}`,
+      categoryCreated: (category: string) => `made the category ${category}`,
+      categoryUpdated: (fields: string, category: string) =>
+        `changed ${fields} of the category ${category}`,
+      categoryRemoved: (category: string) => `removed the category ${category}`,
+      goalCreated: (goal: string) => `set the goal ${goal}`,
+      goalUpdated: (fields: string, goal: string) => `changed ${fields} of the goal ${goal}`,
       taskCreated: (task: string) => `wrote ${task}`,
       taskMoved: (task: string, from: string, to: string) => `moved ${task} from ${from} to ${to}`,
       taskUpdated: (fields: string, task: string) => `changed ${fields} of ${task}`,