@heyramzi/ui 2.0.1 → 2.2.0

package/src/inbox/inbox.test.ts

@@ -0,0 +1,214 @@
+import { describe, expect, it } from "vite-plus/test";
+import {
+  NO_FILTER,
+  entryLine,
+  filterThreads,
+  inboxKeyOf,
+  resolveInboxLabels,
+  snoozeChoices,
+  threadsOf,
+} from "./logic.js";
+import type { InboxEntry, InboxSubject } from "./types.js";
+import type { InboxItem } from "../tasks/inbox/inbox-types.js";
+
+const tsk7: InboxSubject = { type: "task", id: "7", ref: "TSK-7", title: "Write the pricing page" };
+const tsk9: InboxSubject = { type: "task", id: "9", ref: "TSK-9", title: "Fix the footer" };
+const doc1: InboxSubject = { type: "doc", id: "1", title: "Brief" };
+const ada = { kind: "user", name: "Ada" } as const;
+const bot = { kind: "agent", name: "Scribe" } as const;
+
+function entry(id: string, at: string, extra: Partial<InboxEntry> = {}): InboxEntry {
+  return { id, kind: "comment", subject: tsk7, actor: ada, at, ...extra };
+}
+
+const proposal = (
+  state: InboxItem["state"] = "proposed",
+  tier: InboxItem["tier"] = "ask",
+): InboxItem => ({
+  id: "p",
+  kind: "decision",
+  tier,
+  state,
+  title: "Send the quote",
+  project: { id: "x", name: "X" },
+  proposal: { summary: "Send it" },
+  confidence: { score: 0.9 },
+  trace: { source: { type: "email", label: "Mail", at: "Mon" }, evidence: [], reasoning: "" },
+});
+
+describe("threadsOf", () => {
+  it("makes one thread of an agent comment and a status change on TSK-7", () => {
+    const threads = threadsOf([
+      entry("c1", "2026-10-22T09:00:00Z", { kind: "agent_response", actor: bot, body: "Drafted" }),
+      entry("s1", "2026-10-22T09:05:00Z", {
+        kind: "status",
+        status: { from: "todo", to: "review" },
+      }),
+    ]);
+    expect(threads).toHaveLength(1);
+    expect(threads[0].entries).toHaveLength(2);
+    expect(threads[0].unread).toBe(2);
+    expect(threads[0].subject.ref).toBe("TSK-7");
+    expect(threads[0].latestAt).toBe("2026-10-22T09:05:00Z");
+  });
+
+  it("counts only unread entries", () => {
+    const [thread] = threadsOf([
+      entry("a", "2026-10-22T09:00:00Z", { read: true }),
+      entry("b", "2026-10-22T09:01:00Z"),
+    ]);
+    expect(thread.unread).toBe(1);
+  });
+
+  it("sorts threads by their latest entry, newest first", () => {
+    const threads = threadsOf([
+      entry("a", "2026-10-22T09:00:00Z"),
+      entry("b", "2026-10-22T11:00:00Z", { subject: tsk9 }),
+      entry("c", "2026-10-22T10:00:00Z", { subject: doc1 }),
+    ]);
+    expect(threads.map((t) => t.subject.id)).toEqual(["9", "1", "7"]);
+  });
+
+  it("puts threads with unread entries first on request", () => {
+    const entries = [
+      entry("a", "2026-10-22T09:00:00Z"),
+      entry("b", "2026-10-22T11:00:00Z", { subject: tsk9, read: true }),
+    ];
+    expect(threadsOf(entries).map((t) => t.subject.id)).toEqual(["9", "7"]);
+    expect(threadsOf(entries, { unreadFirst: true }).map((t) => t.subject.id)).toEqual(["7", "9"]);
+  });
+
+  it("drops an entry with no subject id", () => {
+    const threads = threadsOf([
+      entry("a", "2026-10-22T09:00:00Z"),
+      entry("b", "2026-10-22T09:01:00Z", { subject: undefined }),
+      entry("c", "2026-10-22T09:02:00Z", { subject: { ...tsk9, id: "" } }),
+    ]);
+    expect(threads).toHaveLength(1);
+    expect(threads[0].entries.map((e) => e.id)).toEqual(["a"]);
+  });
+
+  it("sorts a malformed timestamp last, among threads and inside one", () => {
+    const threads = threadsOf([
+      entry("bad", "yesterday", { subject: tsk9 }),
+      entry("ok", "2026-10-22T09:00:00Z"),
+      entry("late", "2026-10-22T09:30:00Z"),
+      entry("junk", "??"),
+    ]);
+    expect(threads.map((t) => t.subject.id)).toEqual(["7", "9"]);
+    expect(threads[0].entries.map((e) => e.id)).toEqual(["ok", "late", "junk"]);
+    expect(threads[0].latestAt).toBe("2026-10-22T09:30:00Z");
+  });
+
+  it("keeps a pending proposal and ignores a decided one", () => {
+    const [open] = threadsOf([
+      entry("p", "2026-10-22T09:00:00Z", { kind: "proposal", proposal: proposal() }),
+    ]);
+    expect(open.pending).toHaveLength(1);
+    const [done] = threadsOf([
+      entry("p", "2026-10-22T09:00:00Z", { kind: "proposal", proposal: proposal("approved") }),
+    ]);
+    expect(done.pending).toHaveLength(0);
+  });
+});
+
+describe("filterThreads", () => {
+  const threads = threadsOf([
+    entry("a", "2026-10-22T09:00:00Z", { actor: bot }),
+    entry("b", "2026-10-22T10:00:00Z", { subject: doc1 }),
+    entry("p", "2026-10-22T11:00:00Z", { subject: tsk9, kind: "proposal", proposal: proposal() }),
+  ]);
+
+  it("filters by type, by who and by needs you", () => {
+    expect(filterThreads(threads, { ...NO_FILTER, type: "doc" }).map((t) => t.subject.id)).toEqual([
+      "1",
+    ]);
+    expect(
+      filterThreads(threads, { ...NO_FILTER, who: "Scribe" }).map((t) => t.subject.id),
+    ).toEqual(["7"]);
+    expect(
+      filterThreads(threads, { ...NO_FILTER, needsYou: true }).map((t) => t.subject.id),
+    ).toEqual(["9"]);
+    expect(filterThreads(threads, NO_FILTER)).toHaveLength(3);
+  });
+});
+
+const press = (key: string, target: EventTarget | null = document.body) =>
+  inboxKeyOf({
+    key,
+    metaKey: false,
+    ctrlKey: false,
+    altKey: false,
+    defaultPrevented: false,
+    target,
+  });
+
+describe("keys", () => {
+  it("maps the nine keys", () => {
+    expect(["j", "k", "u", "h", "a", "d", "s", "e"].map((k) => press(k))).toEqual([
+      "next",
+      "previous",
+      "toggleRead",
+      "snooze",
+      "approve",
+      "decline",
+      "steer",
+      "edit",
+    ]);
+    expect(press("x")).toBeNull();
+  });
+
+  it("does nothing for u while typing", () => {
+    for (const tag of ["input", "textarea", "select"]) {
+      expect(press("u", document.createElement(tag))).toBeNull();
+    }
+    const editable = document.createElement("div");
+    Object.defineProperty(editable, "isContentEditable", { value: true });
+    expect(press("u", editable)).toBeNull();
+  });
+
+  it("ignores a held modifier", () => {
+    expect(
+      inboxKeyOf({
+        key: "u",
+        metaKey: true,
+        ctrlKey: false,
+        altKey: false,
+        defaultPrevented: false,
+        target: document.body,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("snoozeChoices", () => {
+  it("offers 3 hours on, tomorrow at 9 and the next Monday at 9", () => {
+    const wed = new Date(2026, 9, 21, 14, 30);
+    const [later, tomorrow, nextWeek] = snoozeChoices(wed);
+    expect(later.until.getTime() - wed.getTime()).toBe(3 * 60 * 60 * 1000);
+    expect([tomorrow.until.getDate(), tomorrow.until.getHours()]).toEqual([22, 9]);
+    expect([nextWeek.until.getDay(), nextWeek.until.getDate(), nextWeek.until.getHours()]).toEqual([
+      1, 26, 9,
+    ]);
+  });
+
+  it("moves a Monday to the following Monday", () => {
+    const mon = new Date(2026, 9, 26, 10, 0);
+    expect(snoozeChoices(mon)[2].until.getDate()).toBe(2);
+  });
+});
+
+describe("entryLine", () => {
+  it("fills the host's own words, French included", () => {
+    const fr = resolveInboxLabels({ statusMoved: "a déplacé ceci de {from} à {to}" });
+    expect(
+      entryLine(
+        entry("s", "2026-10-22T09:00:00Z", {
+          kind: "status",
+          status: { from: "A faire", to: "Revue" },
+        }),
+        fr,
+      ),
+    ).toBe("a déplacé ceci de A faire à Revue");
+  });
+});

package/src/inbox/index.ts

@@ -0,0 +1,31 @@
+export { default as ThreadInbox } from "./thread-inbox.svelte";
+export {
+  NO_FILTER,
+  actorNames,
+  entryLine,
+  filterThreads,
+  inboxKeyOf,
+  isPending,
+  resolveInboxLabels,
+  snoozeChoices,
+  subjectTypes,
+  threadsOf,
+} from "./logic.js";
+export type { SnoozeChoice, ThreadsOptions } from "./logic.js";
+export { ALL, DEFAULT_INBOX_LABELS } from "./types.js";
+export type {
+  InboxActor,
+  InboxActorKind,
+  InboxEntry,
+  InboxEntryKind,
+  InboxFilter,
+  InboxKey,
+  InboxLabels,
+  InboxSnooze,
+  InboxSubject,
+  InboxThread,
+} from "./types.js";
+
+// The approval card a pinned proposal is drawn with, and the types its `proposal` field carries.
+export { default as InboxCard } from "../tasks/inbox/inbox-card.svelte";
+export type { InboxItem, InboxVerdict } from "../tasks/inbox/inbox-types.js";

package/src/inbox/logic.ts

@@ -0,0 +1,169 @@
+import { isOpen, isTyping } from "../tasks/inbox/inbox-logic.js";
+import {
+  ALL,
+  DEFAULT_INBOX_LABELS,
+  type InboxEntry,
+  type InboxFilter,
+  type InboxKey,
+  type InboxLabels,
+  type InboxSubject,
+  type InboxThread,
+} from "./types.js";
+
+/** A timestamp as a number, with NaN for one that doesn't parse. */
+function ms(at: string): number {
+  return Date.parse(at);
+}
+
+function latestOf(thread: InboxThread): number {
+  const time = ms(thread.latestAt);
+  return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;
+}
+
+export type ThreadsOptions = {
+  /** Threads with unread entries come before read ones. */
+  unreadFirst?: boolean;
+};
+
+/** True while a proposal entry still waits for a verdict. */
+export function isPending(entry: InboxEntry): boolean {
+  return entry.kind === "proposal" && !!entry.proposal && isOpen(entry.proposal);
+}
+
+/**
+ * One thread per subject, newest first. An entry with no subject id is dropped, and a malformed
+ * timestamp sorts last.
+ */
+export function threadsOf(entries: InboxEntry[], options: ThreadsOptions = {}): InboxThread[] {
+  type Row = { entry: InboxEntry; subject: InboxSubject; index: number; time: number };
+  const groups = new Map<string, Row[]>();
+  entries.forEach((entry, index) => {
+    const subject = entry.subject;
+    if (!subject?.id) return;
+    const key = `${subject.type}:${subject.id}`;
+    groups.set(key, [...(groups.get(key) ?? []), { entry, subject, index, time: ms(entry.at) }]);
+  });
+
+  const threads: InboxThread[] = [];
+  for (const [key, rows] of groups) {
+    const ordered = rows.toSorted((a, b) => {
+      const aBad = Number.isNaN(a.time);
+      const bBad = Number.isNaN(b.time);
+      if (aBad !== bBad) return aBad ? 1 : -1;
+      return (aBad ? 0 : a.time - b.time) || a.index - b.index;
+    });
+    const newest = ordered.findLast((row) => !Number.isNaN(row.time)) ?? ordered[0];
+    const list = ordered.map((row) => row.entry);
+    threads.push({
+      key,
+      // The newest entry carries the freshest title and status.
+      subject: newest.subject,
+      entries: list,
+      unread: list.filter((entry) => !entry.read).length,
+      latestAt: newest.entry.at,
+      pending: list.filter(isPending).toReversed(),
+    });
+  }
+
+  return threads
+    .map((thread, index) => ({ thread, index }))
+    .toSorted((a, b) => {
+      if (options.unreadFirst) {
+        const unread = Number(b.thread.unread > 0) - Number(a.thread.unread > 0);
+        if (unread) return unread;
+      }
+      const aTime = latestOf(a.thread);
+      const bTime = latestOf(b.thread);
+      if (aTime === bTime) return a.index - b.index;
+      return bTime - aTime;
+    })
+    .map((row) => row.thread);
+}
+
+export const NO_FILTER: InboxFilter = { type: ALL, who: ALL, needsYou: false };
+
+/** Keep a thread when it matches the type, holds an entry from the person or agent, and has a pending proposal if asked. */
+export function filterThreads(threads: InboxThread[], filter: InboxFilter): InboxThread[] {
+  return threads.filter(
+    (thread) =>
+      (filter.type === ALL || thread.subject.type === filter.type) &&
+      (filter.who === ALL || thread.entries.some((entry) => entry.actor.name === filter.who)) &&
+      (!filter.needsYou || thread.pending.length > 0),
+  );
+}
+
+export function subjectTypes(threads: InboxThread[]): string[] {
+  return [...new Set(threads.map((thread) => thread.subject.type))];
+}
+
+export function actorNames(threads: InboxThread[]): string[] {
+  return [...new Set(threads.flatMap((thread) => thread.entries.map((entry) => entry.actor.name)))];
+}
+
+type KeyEventLike = Pick<
+  KeyboardEvent,
+  "key" | "metaKey" | "ctrlKey" | "altKey" | "defaultPrevented" | "target"
+>;
+
+const KEYS: Record<string, InboxKey> = {
+  j: "next",
+  k: "previous",
+  u: "toggleRead",
+  h: "snooze",
+  a: "approve",
+  d: "decline",
+  s: "steer",
+  e: "edit",
+};
+
+/** What a key press asks for, or null when it isn't ours: a modifier is held, or focus is in a text field. */
+export function inboxKeyOf(event: KeyEventLike): InboxKey | null {
+  if (event.defaultPrevented || event.metaKey || event.ctrlKey || event.altKey) return null;
+  if (isTyping(event.target)) return null;
+  return KEYS[event.key] ?? null;
+}
+
+export type SnoozeChoice = { id: "later" | "tomorrow" | "nextWeek"; until: Date };
+
+/** The three times a snooze offers: 3 hours on, tomorrow at 9, next Monday at 9. */
+export function snoozeChoices(now: Date): SnoozeChoice[] {
+  const later = new Date(now.getTime() + 3 * 60 * 60 * 1000);
+  const tomorrow = new Date(now);
+  tomorrow.setDate(tomorrow.getDate() + 1);
+  tomorrow.setHours(9, 0, 0, 0);
+  const nextWeek = new Date(now);
+  nextWeek.setDate(nextWeek.getDate() + ((8 - nextWeek.getDay()) % 7 || 7));
+  nextWeek.setHours(9, 0, 0, 0);
+  return [
+    { id: "later", until: later },
+    { id: "tomorrow", until: tomorrow },
+    { id: "nextWeek", until: nextWeek },
+  ];
+}
+
+export function resolveInboxLabels(overrides?: Partial<InboxLabels>): InboxLabels {
+  return { ...DEFAULT_INBOX_LABELS, ...overrides };
+}
+
+/** One line for an entry, in the host's words. `{from}`, `{to}` and `{assignee}` are filled. */
+export function entryLine(entry: InboxEntry, labels: InboxLabels): string {
+  const fill = (text: string) =>
+    text
+      .replaceAll("{from}", entry.status?.from ?? "")
+      .replaceAll("{to}", entry.status?.to ?? "")
+      .replaceAll("{assignee}", entry.assignee ?? "");
+  switch (entry.kind) {
+    case "status":
+      return fill(entry.status?.from ? labels.statusMoved : labels.statusSet);
+    case "assigned":
+      return fill(labels.assigned);
+    case "mention":
+      return labels.mentioned;
+    case "agent_response":
+      return labels.responded;
+    case "proposal":
+      return labels.proposed;
+    default:
+      return labels.commented;
+  }
+}