makersclaw 0.7.0 → 0.8.1

package/registry/blocks/margin-notes/margin-model.js

@@ -0,0 +1,224 @@
+// The margin-notes block's pure model — no React, no DOM.
+//
+// A passage is a stretch of words with an id. A note belongs to one passage
+// (note.passage) and says something about it: where it came from, that it
+// needs checking, that it was cut, a comment. This file holds the rules the
+// component and its tests share: which kinds exist and how each looks and
+// acts, which notes sit by which passage, which words of a passage a note
+// marks, what J and K walk to, and the counts.
+//
+// README.md beside this file is the contract; this file is the proof.
+
+/** The tones a kind or a note may use (the kit's status tones). */
+export const TONES = ["neutral", "primary", "info", "success", "warning", "danger"];
+
+/** How the words a note is about are drawn in the passage. */
+export const MARKS = ["underline", "wavy", "strike", "highlight", "none"];
+
+/**
+ * The four kinds a margin knows. An app may change any field of one, or add
+ * its own kind, through the block's `kinds` prop.
+ *
+ *   label     the chip's words
+ *   icon      a kit icon name
+ *   tone      neutral · primary · info · success · warning · danger
+ *   mark      underline · wavy · strike · highlight · none: the words in the
+ *             passage that the note is about
+ *   actions   [{ id, label, variant?, icon? }]: the buttons on an open note
+ *   reopen    the button on a settled note (false: none)
+ */
+export const MARGIN_KINDS = {
+  source: { label: "Source", icon: "link", tone: "neutral", mark: "underline", actions: [], reopen: false },
+  flag: {
+    label: "Check this line",
+    icon: "flag",
+    tone: "warning",
+    mark: "wavy",
+    actions: [
+      { id: "confirm", label: "It’s true", icon: "check", variant: "secondary" },
+      { id: "cut", label: "Cut it", icon: "x", variant: "secondary" },
+      { id: "ask", label: "Ask where it came from", variant: "quiet" },
+    ],
+    reopen: { label: "Reopen" },
+  },
+  cut: {
+    label: "Cut",
+    icon: "eraser",
+    tone: "danger",
+    mark: "strike",
+    actions: [{ id: "putback", label: "Put back", icon: "undo", variant: "secondary" }],
+    reopen: false,
+  },
+  comment: { label: "Comment", icon: "message-square", tone: "info", mark: "highlight", actions: [], reopen: false },
+};
+
+const FALLBACK = { label: "Note", icon: "message-circle", tone: "neutral", mark: "highlight", actions: [], reopen: false };
+
+/** "needs_review" -> "Needs review". */
+export function humanize(id) {
+  const words = String(id ?? "").replace(/[_-]+/g, " ").trim();
+  return words ? words[0].toUpperCase() + words.slice(1) : "";
+}
+
+/** The built-in kinds with an app's changes laid over them, field by field. */
+export function resolveKinds(overrides) {
+  const out = {};
+  for (const [id, def] of Object.entries(MARGIN_KINDS)) out[id] = { ...def };
+  for (const [id, def] of Object.entries(overrides ?? {})) {
+    if (!def || typeof def !== "object") continue;
+    out[id] = { ...(out[id] ?? { ...FALLBACK, label: humanize(id) }), ...def };
+  }
+  return out;
+}
+
+/** What a note looks like and offers: its kind's definition with the note's own words over it. */
+export function noteLook(note, kinds) {
+  const kind = kinds?.[note?.kind] ?? { ...FALLBACK, label: humanize(note?.kind) || FALLBACK.label };
+  const tone = TONES.includes(note?.tone) ? note.tone : TONES.includes(kind.tone) ? kind.tone : "neutral";
+  const hue = Number.isInteger(note?.hue) && note.hue >= 1 && note.hue <= 5 ? note.hue : null;
+  const mark = MARKS.includes(note?.mark) ? note.mark : MARKS.includes(kind.mark) ? kind.mark : "highlight";
+  return {
+    label: note?.label || kind.label,
+    icon: kind.icon || FALLBACK.icon,
+    tone,
+    hue,
+    mark,
+    actions: Array.isArray(note?.actions) ? note.actions : kind.actions ?? [],
+    reopen: kind.reopen,
+  };
+}
+
+/** A note nobody needs to act on any more. */
+export const isSettled = (note) => note?.state === "settled";
+
+/** The buttons an open note shows; none when it is locked, settled or read-only. */
+export function actionsOf(note, kinds, { readOnly = false } = {}) {
+  if (readOnly || isSettled(note) || note?.locked) return [];
+  return noteLook(note, kinds).actions.filter((a) => a && a.id && a.label);
+}
+
+/**
+ * Which notes sit by which passage.
+ *   byPassage  Map: passage id -> its notes, in the order given
+ *   ordered    every note, in the passages' order (a passage's notes keep their order)
+ *   orphans    notes whose passage is not in the list
+ */
+export function arrangeNotes(passages, notes) {
+  const byPassage = new Map();
+  for (const p of passages ?? []) {
+    if (!p || p.id == null || byPassage.has(p.id)) continue;
+    byPassage.set(p.id, []);
+  }
+  const orphans = [];
+  const seen = new Set();
+  for (const n of notes ?? []) {
+    if (!n || n.id == null || seen.has(n.id)) continue;
+    seen.add(n.id);
+    if (byPassage.has(n.passage)) byPassage.get(n.passage).push(n);
+    else orphans.push(n);
+  }
+  const ordered = [];
+  for (const list of byPassage.values()) ordered.push(...list);
+  ordered.push(...orphans);
+  return { byPassage, ordered, orphans };
+}
+
+/**
+ * What J (dir 1) and K (dir -1) walk to: the next note that still needs a
+ * person, after the selected one. With nothing selected, the first (or the
+ * last, going back). At the end it stays where it is. Null when no note is
+ * left to walk.
+ */
+export function walkNext(ordered, currentId, dir = 1) {
+  const list = ordered ?? [];
+  const step = dir < 0 ? -1 : 1;
+  const open = (n) => !isSettled(n);
+  if (!list.some(open)) return null;
+  const at = list.findIndex((n) => n.id === currentId);
+  if (at < 0) {
+    const pick = step > 0 ? list.find(open) : [...list].reverse().find(open);
+    return pick.id;
+  }
+  for (let i = at + step; i >= 0 && i < list.length; i += step) if (open(list[i])) return list[i].id;
+  return currentId;
+}
+
+/** A press on a passage: its first note; pressed again, its next; after the last, none. */
+export function cycleNote(passageNotes, currentId) {
+  const list = passageNotes ?? [];
+  if (!list.length) return null;
+  const at = list.findIndex((n) => n.id === currentId);
+  if (at < 0) return list[0].id;
+  return list[at + 1]?.id ?? null;
+}
+
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** Where a quote sits in a text, ignoring case: [start, end] or null. */
+export function findQuote(text, quote) {
+  const q = typeof quote === "string" ? quote.trim() : "";
+  if (!q || typeof text !== "string") return null;
+  const m = new RegExp(escapeRe(q).replace(/\s+/g, "\\s+"), "iu").exec(text);
+  return m ? [m.index, m.index + m[0].length] : null;
+}
+
+/**
+ * The words of a passage, cut into pieces by the notes that mark them.
+ *
+ *   segments  [{ text, ids }]: in order, joined they are the text; ids are
+ *             the notes whose quote covers the piece (empty: plain words)
+ *   whole     the first open note whose mark is "strike" and whose quote
+ *             is empty or not in the text: it strikes the whole passage
+ *             (then `segments` is that one piece)
+ *
+ * `markOf(note)` names how a note marks its words; a settled note marks
+ * nothing (a cut that was put back reads as plain words again).
+ */
+export function inlineMarks(text, notes, markOf = () => "highlight") {
+  const body = typeof text === "string" ? text : "";
+  const ranges = [];
+  let whole = null;
+  for (const n of notes ?? []) {
+    if (isSettled(n)) continue;
+    const mark = markOf(n);
+    if (mark === "none") continue;
+    const at = findQuote(body, n.quote);
+    if (at) ranges.push({ id: n.id, from: at[0], to: at[1] });
+    else if (mark === "strike" && !whole) whole = n;
+  }
+  if (whole) return { segments: [{ text: body, ids: [whole.id] }], whole };
+  if (!ranges.length) return { segments: [{ text: body, ids: [] }], whole: null };
+  const cuts = [...new Set([0, body.length, ...ranges.flatMap((r) => [r.from, r.to])])].sort((a, b) => a - b);
+  const segments = [];
+  for (let i = 0; i < cuts.length - 1; i++) {
+    const [a, b] = [cuts[i], cuts[i + 1]];
+    if (a === b) continue;
+    segments.push({ text: body.slice(a, b), ids: ranges.filter((r) => r.from <= a && r.to >= b).map((r) => r.id) });
+  }
+  return { segments, whole: null };
+}
+
+/** How many notes there are, how many still need a person, and by kind. */
+export function countNotes(notes) {
+  const out = { total: 0, open: 0, settled: 0, byKind: {} };
+  for (const n of notes ?? []) {
+    if (!n) continue;
+    out.total += 1;
+    if (isSettled(n)) out.settled += 1;
+    else out.open += 1;
+    const k = (out.byKind[n.kind] ??= { total: 0, open: 0 });
+    k.total += 1;
+    if (!isSettled(n)) k.open += 1;
+  }
+  return out;
+}
+
+/** "3 open · 1 settled" — the margin's count line. */
+export function countWords(counts, words = {}) {
+  const open = words.open ?? "open";
+  const settled = words.settled ?? "settled";
+  const parts = [];
+  if (counts.open) parts.push(`${counts.open} ${open}`);
+  if (counts.settled) parts.push(`${counts.settled} ${settled}`);
+  return parts.join(" · ");
+}