@skillcdn/console 0.1.10 → 0.1.12

package/src/index.ts

@@ -16,9 +16,11 @@ export {
 export {
   Calendar,
   type CalendarProps,
+  type WeekSegment,
   Workload,
   type WorkloadProps,
   type WorkloadRow,
+  weekSegments,
   workloadOf,
 } from "./components/calendar.js";
 export { CategoryList, type CategoryListProps } from "./components/categories.js";
@@ -64,6 +66,7 @@ export {
   type GoalViewProps,
 } from "./components/goals.js";
 export { Markdown, type MarkdownProps } from "./components/markdown.js";
+export { PAGE_SIZE, ShowMore, usePaged } from "./components/paged.js";
 export { PeopleList, type PeopleListProps } from "./components/people.js";
 export {
   keyOf,
@@ -74,6 +77,7 @@ export {
   type ProjectFormProps,
   ProjectList,
   type ProjectListProps,
+  ProjectMark,
   ProjectRoleBadge,
   VISIBILITY_LABELS,
 } from "./components/projects.js";
@@ -123,6 +127,7 @@ export {
   PRIORITY_LABELS,
   PriorityBadge,
   ProgressBar,
+  personName,
   ROLE_LABELS,
   RoleBadge,
   Spinner,
@@ -136,7 +141,10 @@ export {
   type ConsoleApp,
   type ConsoleComponents,
   type ConsoleConfig,
+  type CustomPage,
+  type CustomPageContext,
   createConsole,
+  customPageLabel,
   DEFAULT_COMPONENTS,
 } from "./console.js";
 export { type ConsoleActions, type ConsoleData, useConsoleData } from "./data.js";
@@ -176,6 +184,7 @@ export {
   boardHref,
   calendarHref,
   connectHref,
+  customPageHref,
   type DocsView,
   decisionHref,
   docHref,

package/src/limits.ts

@@ -64,3 +64,9 @@ export const MAX_CATEGORY_KEY_LENGTH = 40;
 export const MAX_CATEGORY_NAME_LENGTH = 60;
 /** How many categories one workspace may have: a vocabulary, not a tag cloud. */
 export const MAX_CATEGORIES = 50;
+/** A project's mark: a letter or two, or a symbol, shown on its colour; counted in code units. */
+export const MAX_PROJECT_SYMBOL_LENGTH = 8;
+/** How large a project's own image for its mark may be, in bytes. */
+export const MAX_PROJECT_ICON_BYTES = 512 * 1024;
+/** How many items a listing answers with when none is asked for, and the most one may ask for. */
+export const DEFAULT_PAGE_LIMIT = 50;

package/src/marks.ts

@@ -0,0 +1,40 @@
+import { COLOR_NAMES, type ColorName } from "./vocabulary.js";
+
+// A project's mark: a symbol on a colour, so that projects tell apart at a glance. A project
+// that names neither gets a colour from its key, the same everywhere and every time, and the
+// first letter of its name.
+
+/** A small, well-spread hash of a string: enough to pick a colour, nothing more. */
+function hashOf(value: string): number {
+  let hash = 2166136261;
+  for (const char of value) {
+    hash ^= char.codePointAt(0) ?? 0;
+    hash = Math.imul(hash, 16777619) >>> 0;
+  }
+  return hash;
+}
+
+/** The colour of a project's mark: the one it names, else one chosen from its key. */
+export function projectColorOf(project: {
+  readonly key: string;
+  readonly color: ColorName | null;
+}): ColorName {
+  if (project.color !== null) {
+    return project.color;
+  }
+  // Gray is for what has no colour; a project chosen one gets one of the rest.
+  const choices = COLOR_NAMES.filter((name) => name !== "gray");
+  return choices[hashOf(project.key) % choices.length] ?? "gray";
+}
+
+/** The symbol of a project's mark: the one it names, else the first letter of its name. */
+export function projectSymbolOf(project: {
+  readonly name: string;
+  readonly symbol: string | null;
+}): string {
+  if (project.symbol !== null && project.symbol.length > 0) {
+    return project.symbol;
+  }
+  const first = [...project.name.trim()][0];
+  return first === undefined ? "?" : first.toUpperCase();
+}

package/src/router.ts

@@ -52,8 +52,13 @@ export type Route =
   | { readonly name: "decisions"; readonly project: string }
   | { readonly name: "new-decision"; readonly project: string }
   | { readonly name: "decision"; readonly project: string; readonly id: string }
-  /** The calendar of a project: the month shown, or this one when the address names none. */
-  | { readonly name: "calendar"; readonly project: string; readonly month: string | undefined }
+  /** The calendar of a project: the month shown, or this one when the address names none, narrowed as the board is. */
+  | {
+      readonly name: "calendar";
+      readonly project: string;
+      readonly month: string | undefined;
+      readonly filter: BoardFilter;
+    }
   | { readonly name: "roadmap"; readonly project: string }
   | { readonly name: "new-goal"; readonly project: string }
   | {
@@ -79,6 +84,14 @@ export type Route =
   | { readonly name: "connect"; readonly code: string | undefined }
   /** An address that moved: the page takes the person to `to` in its place. */
   | { readonly name: "moved"; readonly to: string }
+  /** A page a console adds of its own (`createConsole({ pages })`): on the workspace, or on a project. */
+  | { readonly name: "custom"; readonly level: "workspace"; readonly page: string }
+  | {
+      readonly name: "custom";
+      readonly level: "project";
+      readonly project: string;
+      readonly page: string;
+    }
   | { readonly name: "not-found" };
 
 /** The pages of a project, after its key. */
@@ -107,6 +120,8 @@ export const PATHS = {
   newToken: "/agents/new",
   /** The categories tasks are sorted into, kept by an administrator. */
   categories: "/categories",
+  /** Where the pages a console adds of its own are: `/pages/<key>`, and `/projects/<key>/pages/<page>` on a project. */
+  pages: "/pages",
   /** Where an agent's connection is approved (ADR-0011): `/connect/<code>`, or the code typed. */
   connect: "/connect",
 } as const;
@@ -218,6 +233,12 @@ export function matchRoute(pathname: string, search = ""): Route {
       ? { name: "person-agents", id }
       : NOT_FOUND;
   }
+  if (path.startsWith(`${PATHS.pages}/`)) {
+    const [page, ...more] = path.slice(PATHS.pages.length + 1).split("/");
+    return page !== undefined && PROJECT_KEY.test(page) && more.length === 0
+      ? { name: "custom", level: "workspace", page }
+      : NOT_FOUND;
+  }
   if (!path.startsWith(`${PATHS.project}/`)) {
     return NOT_FOUND;
   }
@@ -237,6 +258,11 @@ export function matchRoute(pathname: string, search = ""): Route {
     const view = docsViewOf(params, docPath);
     return view === undefined ? NOT_FOUND : { name: "docs", project, path: docPath, view };
   }
+  if (page === "pages") {
+    return third !== undefined && PROJECT_KEY.test(third) && rest.length === 0
+      ? { name: "custom", level: "project", project, page: third }
+      : NOT_FOUND;
+  }
   if (rest.length > 0) {
     return NOT_FOUND;
   }
@@ -280,7 +306,7 @@ export function matchRoute(pathname: string, search = ""): Route {
     if (month !== null && !isMonth(month)) {
       return NOT_FOUND;
     }
-    return { name: "calendar", project, month: month ?? undefined };
+    return { name: "calendar", project, month: month ?? undefined, filter: boardFilterOf(params) };
   }
   if (page === "roadmap") {
     return { name: "roadmap", project };
@@ -307,6 +333,12 @@ export function projectHref(key: string, page?: ProjectPage): string {
 
 /** Where a project's board is, narrowed as the filter says; the plain board for an empty one. */
 export function boardHref(key: string, filter: BoardFilter = {}): string {
+  const parts = filterParts(filter);
+  return parts.length === 0 ? projectHref(key) : `${projectHref(key)}?${parts.join("&")}`;
+}
+
+/** The filter as the query carries it, a part per narrowing; nothing for the plain board. */
+function filterParts(filter: BoardFilter): string[] {
   const parts: string[] = [];
   // An empty value means "none": it keeps its sign; "mine" is a flag and has no value.
   if (filter.category !== undefined) {
@@ -321,7 +353,7 @@ export function boardHref(key: string, filter: BoardFilter = {}): string {
   if (filter.mine === true) {
     parts.push("mine");
   }
-  return parts.length === 0 ? projectHref(key) : `${projectHref(key)}?${parts.join("&")}`;
+  return parts;
 }
 
 /** Where a task is written: the form. */
@@ -345,10 +377,16 @@ export function decisionHref(key: string, id: string): string {
   return `${PATHS.project}/${key}/decisions/${id}`;
 }
 
-/** Where a project's calendar is, on a month, or on this one when none is named. */
-export function calendarHref(key: string, month?: string): string {
+/** Where a project's calendar is, on a month, or on this one when none is named, narrowed as the filter says. */
+export function calendarHref(key: string, month?: string, filter: BoardFilter = {}): string {
   const base = projectHref(key, "calendar");
-  return month === undefined ? base : `${base}?month=${month}`;
+  const parts = [...(month === undefined ? [] : [`month=${month}`]), ...filterParts(filter)];
+  return parts.length === 0 ? base : `${base}?${parts.join("&")}`;
+}
+
+/** Where a page a console adds of its own is: on the workspace, or on a project when its key is given. */
+export function customPageHref(page: string, project?: string): string {
+  return project === undefined ? `${PATHS.pages}/${page}` : `${projectHref(project)}/pages/${page}`;
 }
 
 /** Where a goal is set: the form. */

package/src/routes.ts

@@ -114,3 +114,12 @@ export function projectPath(key: string, collection?: ProjectCollection, id?: st
     ? `${base}/${collection}`
     : `${base}/${collection}/${encodeURIComponent(id)}`;
 }
+
+/**
+ * Where a project's own image for its mark is read, with the hash as a version where the image
+ * is known, so that a browser's copy is asked for again only when the image changes.
+ */
+export function projectIconPath(key: string, icon?: { readonly sha256: string } | null): string {
+  const base = `${projectPath(key)}/icon`;
+  return icon === undefined || icon === null ? base : `${base}?v=${icon.sha256.slice(0, 16)}`;
+}

package/src/schemas.ts

@@ -21,6 +21,7 @@ import {
   MAX_PROJECT_DESCRIPTION_LENGTH,
   MAX_PROJECT_KEY_LENGTH,
   MAX_PROJECT_NAME_LENGTH,
+  MAX_PROJECT_SYMBOL_LENGTH,
   MAX_QUESTION_LENGTH,
   MAX_SECRET_LENGTH,
   MAX_SKILLS_ADDRESS_LENGTH,
@@ -35,10 +36,12 @@ import { hasForbiddenCodePoint } from "./text.js";
 import {
   ARTIFACT_KINDS,
   CATEGORY_COLORS,
+  COLOR_NAMES,
   EVENT_KINDS,
   GOAL_STATES,
   LINK_SOURCES,
   PERSON_ROLES,
+  PROJECT_ICON_TYPES,
   PROJECT_ROLES,
   PROJECT_VISIBILITIES,
   PROVIDER_KEYS,
@@ -160,7 +163,19 @@ const projectKey = z.string().check(
 /** The address of a project's skills, as the standard spells one; the console checks it as one. */
 const skillsAddress = line(MAX_SKILLS_ADDRESS_LENGTH);
 
+/** A project's mark: a letter or two, or a symbol, with no space in it; shown on the project's colour. */
+const projectSymbol = line(MAX_PROJECT_SYMBOL_LENGTH).check(
+  z.refine((value) => !/\s/.test(value), "must have no space in it"),
+);
+
 /** A project of the workspace, as the asker sees it: with what they are in it. */
+/** A project's own image for its mark: the hash it is kept by, which `projectIconPath` reads it with, and its kind. */
+export const restProjectIconSchema = z.object({
+  sha256: z.string().check(z.regex(/^[0-9a-f]{64}$/)),
+  contentType: z.enum(PROJECT_ICON_TYPES),
+});
+export type RestProjectIcon = z.infer<typeof restProjectIconSchema>;
+
 export const restProjectSchema = z.object({
   id: uuid,
   key: projectKey,
@@ -170,6 +185,12 @@ export const restProjectSchema = z.object({
   visibility: z.enum(PROJECT_VISIBILITIES),
   /** The address of the project's skills at the SkillCDN deployment, canonical, or `null` for the organization's. */
   skillsAddress: z.nullable(z.string()),
+  /** The colour of the project's mark, one of the names, or `null` for one chosen from its key. */
+  color: z.nullable(z.enum(COLOR_NAMES)),
+  /** The project's mark, a letter or two or a symbol, or `null` for the first letter of its name. */
+  symbol: z.nullable(z.string()),
+  /** The project's own image for its mark, shown in place of the symbol, or `null` for none. */
+  icon: z.nullable(restProjectIconSchema),
   /** What the asker is in it: an owner configures the project, a member works on it. */
   role: z.enum(PROJECT_ROLES),
   /** How many decisions in it wait for a person. */
@@ -194,6 +215,9 @@ export const restProjectInputSchema = z.object({
   visibility: z.optional(z.enum(PROJECT_VISIBILITIES)),
   /** Left out or `null`: the organization's skills. */
   skillsAddress: z.optional(z.nullable(skillsAddress)),
+  /** Left out or `null`: a colour chosen from the key, and the first letter of the name. */
+  color: z.optional(z.nullable(z.enum(COLOR_NAMES))),
+  symbol: z.optional(z.nullable(projectSymbol)),
 });
 export type RestProjectInput = z.infer<typeof restProjectInputSchema>;
 
@@ -203,6 +227,8 @@ export const restProjectPatchSchema = z.object({
   description: z.optional(paragraphs(MAX_PROJECT_DESCRIPTION_LENGTH)),
   visibility: z.optional(z.enum(PROJECT_VISIBILITIES)),
   skillsAddress: z.optional(z.nullable(skillsAddress)),
+  color: z.optional(z.nullable(z.enum(COLOR_NAMES))),
+  symbol: z.optional(z.nullable(projectSymbol)),
 });
 export type RestProjectPatch = z.infer<typeof restProjectPatchSchema>;
 
@@ -313,8 +339,8 @@ export const restTaskSchema = z.object({
 });
 export type RestTask = z.infer<typeof restTaskSchema>;
 
-/** `GET /api/v1/projects/<key>/tasks`: the board, newest first. */
-export const restTasksSchema = z.object({ items: z.array(restTaskSchema) });
+/** `GET /api/v1/projects/<key>/tasks`: a page of the board, newest first, and whether there is more after it. */
+export const restTasksSchema = z.object({ items: z.array(restTaskSchema), more: z.boolean() });
 export type RestTasks = z.infer<typeof restTasksSchema>;
 
 const taskLinkInput = z.object({
@@ -449,12 +475,21 @@ export const restDecisionSchema = z.object({
 });
 export type RestDecision = z.infer<typeof restDecisionSchema>;
 
-/** `GET /api/v1/projects/<key>/decisions`: the ones that wait first, newest first within each. */
-export const restDecisionsSchema = z.object({ items: z.array(restDecisionSchema) });
+/** `GET /api/v1/projects/<key>/decisions`: a page, the ones that wait first, newest first within each, and whether there is more. */
+export const restDecisionsSchema = z.object({
+  items: z.array(restDecisionSchema),
+  more: z.boolean(),
+});
 export type RestDecisions = z.infer<typeof restDecisionsSchema>;
 
-/** The project a thing on a person's plate belongs to, named for the page to say and link it. */
-const projectRef = z.object({ key: projectKey, name: z.string() });
+/** The project a thing on a person's plate belongs to, named and marked for the page to say, link and show it. */
+const projectRef = z.object({
+  key: projectKey,
+  name: z.string(),
+  color: z.nullable(z.enum(COLOR_NAMES)),
+  symbol: z.nullable(z.string()),
+  icon: z.nullable(restProjectIconSchema),
+});
 
 /**
  * `GET /api/v1/work`: what is on the asker's plate across the projects they may see (ADR-0019):
@@ -598,6 +633,11 @@ export const restRunSchema = z.object({
   status: z.enum(RUN_STATUSES),
   startedAt: instant,
   endedAt: z.nullable(instant),
+  /**
+   * When the agent was last heard from on this run: when it began, reported, handed in or
+   * asked. The board cannot know whether an agent still runs; this is what it knows.
+   */
+  lastHeardAt: instant,
   /** What the agent said when the run ended, in Markdown, or `null`. */
   summary: z.nullable(z.string()),
   /** Oldest first. */
@@ -608,8 +648,8 @@ export const restRunSchema = z.object({
 });
 export type RestRun = z.infer<typeof restRunSchema>;
 
-/** `GET /api/v1/projects/<key>/runs`: the runs, newest first. */
-export const restRunsSchema = z.object({ items: z.array(restRunSchema) });
+/** `GET /api/v1/projects/<key>/runs`: a page of the runs, newest first, and whether there is more. */
+export const restRunsSchema = z.object({ items: z.array(restRunSchema), more: z.boolean() });
 export type RestRuns = z.infer<typeof restRunsSchema>;
 
 /** `GET .../events?after=`: what happened after that number, oldest first. */

package/src/styles/console.css

@@ -1197,6 +1197,7 @@ table {
   flex: 1 1 0;
   grid-auto-flow: column;
   grid-auto-columns: minmax(var(--sc-column-width), 1fr);
+  grid-template-rows: minmax(0, 1fr);
   gap: var(--sc-space-3);
   min-height: 24rem;
   overflow-x: auto;
@@ -1209,6 +1210,8 @@ table {
   display: flex;
   flex-direction: column;
   min-height: 0;
+  /* The body scrolls; the column clips, so that nothing of it reaches the board's own scrolling. */
+  overflow: hidden;
   border-radius: var(--sc-radius-xl);
   scroll-snap-align: start;
 }
@@ -2575,15 +2578,89 @@ table {
   white-space: nowrap;
 }
 
-.sc-calendar-task-over {
+.sc-calendar-over {
   color: var(--sc-color-text-faint);
   text-decoration: line-through;
 }
 
-.sc-calendar-task-late {
+.sc-calendar-late {
   color: var(--sc-color-danger);
 }
 
+/* A task planned across days lies across them: a bar in a lane of its own, in its category's
+   colour, reaching over the gap between the cells so that it reads as one. */
+.sc-calendar-lane,
+.sc-calendar-bar {
+  display: flex;
+  align-items: center;
+  height: 1.125rem;
+  margin-top: 2px;
+}
+
+.sc-calendar-bar {
+  margin-inline: calc(-1 * var(--sc-space-2) - 0.125rem - 1px);
+  padding-inline: var(--sc-space-2);
+  border-block: 1px solid color-mix(in srgb, var(--sc-category-line) 45%, transparent);
+  background: var(--sc-category-fill);
+  color: var(--sc-category-line);
+  font-size: var(--sc-text-xs);
+  line-height: 1;
+  text-decoration: none;
+  overflow: hidden;
+  white-space: nowrap;
+}
+
+.sc-calendar-bar:hover {
+  filter: brightness(1.15);
+}
+
+.sc-calendar-bar-begins {
+  margin-left: 0;
+  border-left: 1px solid color-mix(in srgb, var(--sc-category-line) 45%, transparent);
+  border-start-start-radius: var(--sc-radius-full);
+  border-end-start-radius: var(--sc-radius-full);
+}
+
+.sc-calendar-bar-ends {
+  margin-right: 0;
+  border-right: 1px solid color-mix(in srgb, var(--sc-category-line) 45%, transparent);
+  border-start-end-radius: var(--sc-radius-full);
+  border-end-end-radius: var(--sc-radius-full);
+}
+
+.sc-calendar-bar.sc-calendar-late {
+  border-color: color-mix(in srgb, var(--sc-color-danger) 70%, transparent);
+  color: var(--sc-color-danger);
+}
+
+.sc-calendar-bar.sc-calendar-over {
+  opacity: 0.55;
+}
+
+.sc-calendar-legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--sc-space-1) var(--sc-space-4);
+  margin: 0;
+  color: var(--sc-color-text-muted);
+  font-size: var(--sc-text-xs);
+}
+
+.sc-calendar-legend div {
+  display: flex;
+  align-items: center;
+  gap: var(--sc-space-1);
+}
+
+.sc-calendar-legend dt {
+  display: flex;
+  align-items: center;
+}
+
+.sc-calendar-legend dd {
+  margin: 0;
+}
+
 .sc-calendar-task-start {
   color: var(--sc-color-text-muted);
 }
@@ -2593,6 +2670,69 @@ table {
   color: var(--sc-color-text-faint);
 }
 
+/* The button under a list shown a page at a time. */
+.sc-show-more {
+  margin-top: var(--sc-space-3);
+}
+
+/* A project's mark: its symbol on its colour. */
+.sc-mark {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--sc-radius-sm);
+  background: var(--sc-category-fill);
+  color: var(--sc-category-line);
+  font-weight: var(--sc-weight-bold);
+  line-height: 1;
+  vertical-align: middle;
+}
+
+.sc-mark-sm {
+  width: 1.125rem;
+  height: 1.125rem;
+  margin-right: var(--sc-space-1);
+  font-size: 0.625rem;
+}
+
+.sc-mark-md {
+  width: 2rem;
+  height: 2rem;
+  border-radius: var(--sc-radius-md);
+  font-size: var(--sc-text-sm);
+}
+
+.sc-mark-lg {
+  width: 3rem;
+  height: 3rem;
+  border-radius: var(--sc-radius-lg);
+  font-size: var(--sc-text-xl);
+}
+
+.sc-mark-row {
+  align-items: end;
+}
+
+/* A project's own image, in place of the symbol, filling the mark. */
+.sc-mark-pictured {
+  padding: 0;
+  overflow: hidden;
+  background: var(--sc-color-bg-inset);
+}
+
+.sc-mark-image {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.sc-input-file {
+  padding-block: calc(var(--sc-space-2) - 2px);
+  font-size: var(--sc-text-sm);
+}
+
 .sc-calendar-below {
   display: grid;
   align-items: start;
@@ -2921,6 +3061,13 @@ table {
     display: none;
   }
 
+  .sc-calendar-lane,
+  .sc-calendar-bar {
+    height: 4px;
+    padding: 0;
+    border: 0;
+  }
+
   .sc-feed-item {
     grid-template-columns: 1fr;
     gap: var(--sc-space-1);

package/src/vocabulary.ts

@@ -31,10 +31,10 @@ export const GOAL_STATES = ["planned", "active", "done", "dropped"] as const;
 export type GoalState = (typeof GOAL_STATES)[number];
 
 /**
- * The colours a category may be shown in: names, so that a custom console paints them in its
- * own tokens and no value an administrator typed reaches a stylesheet.
+ * The colours a category, or a project's mark, may be shown in: names, so that a custom console
+ * paints them in its own tokens and no value a person typed reaches a stylesheet.
  */
-export const CATEGORY_COLORS = [
+export const COLOR_NAMES = [
   "gray",
   "blue",
   "green",
@@ -45,7 +45,16 @@ export const CATEGORY_COLORS = [
   "yellow",
 ] as const;
 
-export type CategoryColor = (typeof CATEGORY_COLORS)[number];
+export type ColorName = (typeof COLOR_NAMES)[number];
+
+/** The colours of the categories: the same names. */
+export const CATEGORY_COLORS = COLOR_NAMES;
+
+export type CategoryColor = ColorName;
+
+/** The kinds of image a project's own mark may be: what a browser shows in place, and nothing that can run. */
+export const PROJECT_ICON_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"] as const;
+export type ProjectIconType = (typeof PROJECT_ICON_TYPES)[number];
 
 /** The identity providers people may sign in through: the git host, and Google (Workspace). */
 export const PROVIDER_KEYS = ["gh", "google"] as const;
@@ -132,6 +141,7 @@ export const EVENT_KINDS = [
   "run.started",
   "run.reported",
   "run.handed_in",
+  "run.taken_over",
   "run.ended",
   "document.written",
   "document.archived",