diff --git a/frontend/src/assets/prose.css b/frontend/src/assets/prose.css index 5a280128..c987a334 100644 --- a/frontend/src/assets/prose.css +++ b/frontend/src/assets/prose.css @@ -164,6 +164,14 @@ text-decoration-color: currentColor; } +/* Drawn with its title: the title reads as the link, the number after it is + the citation, quieter and never split across lines. */ +.record-ref__id { + color: var(--fs-text-secondary); + font-size: 0.85em; + white-space: nowrap; +} + .record-ref:focus-visible { outline: none; box-shadow: var(--fs-focus-ring); diff --git a/frontend/src/directives/recordRefs.ts b/frontend/src/directives/recordRefs.ts index 546d7b95..219587bb 100644 --- a/frontend/src/directives/recordRefs.ts +++ b/frontend/src/directives/recordRefs.ts @@ -11,9 +11,13 @@ import type { RefSpace } from "@/utils/recordRefs"; * * After each render it asks the server, once for the whole body, what every * referenced id is. Each link then gets the route its kind opens at (a `#N` - * may be a task, lesson or snippet), the record's kind and title as a tooltip - * and accessible name, and a "leads nowhere" style when the reader cannot open - * it: missing, trashed and not-shared-with-you look the same, on purpose. + * may be a task, lesson or snippet), the record's title drawn before its + * number — "Fix the cache key #3127" — so a reader knows what is cited + * without hovering, its kind, full title and status as a tooltip, and a + * "leads nowhere" style when the reader cannot open it: missing, trashed and + * not-shared-with-you look the same, on purpose, and keep the bare number. + * The stored text stays `#N`; the title is read at render, so an edited + * title shows everywhere it is cited. * A plain click navigates in the app; a modified click (new tab) keeps the * browser's own behaviour. */ @@ -22,7 +26,8 @@ interface NoteInfo { id: number; title: string; is_task: boolean; note_type: str interface MilestoneInfo { id: number; title: string; project_id: number | null; status: string } interface RuleInfo { id: number; title: string; kind: string } type Resolved = { notes: Record; milestones: Record; rules: Record }; -type Info = { href: string; label: string } | null; +// `title` is drawn in the link; `label` (kind · title (status)) is its tooltip. +type Info = { href: string; title: string; label: string } | null; // A short-lived cache: the same body re-renders on every keystroke in a // preview, and a page of work logs cites the same few records again and again. @@ -37,20 +42,62 @@ function noteInfo(n: NoteInfo): Info { else if (n.note_type === "lesson") kind = "Lesson"; else if (n.note_type === "snippet") kind = "Snippet"; const state = n.is_task && n.status ? ` (${n.status.replace(/_/g, " ")})` : ""; - return { href: recordHref(n), label: `${kind} · ${n.title || "Untitled"}${state}` }; + const title = n.title || "Untitled"; + return { href: recordHref(n), title, label: `${kind} · ${title}${state}` }; } function milestoneInfo(m: MilestoneInfo): Info { if (m.project_id == null) return null; + const title = m.title || "Untitled"; return { href: `/projects/${m.project_id}?milestone=${m.id}`, - label: `Milestone · ${m.title || "Untitled"}${m.status === "done" ? " (done)" : ""}`, + title, + label: `Milestone · ${title}${m.status === "done" ? " (done)" : ""}`, }; } function ruleInfo(r: RuleInfo): Info { const kind = r.kind === "preference" ? "Preference" : "Rule"; - return { href: `/rules?rule=${r.id}`, label: `${kind} · ${r.title || "Untitled"}` }; + const title = r.title || "Untitled"; + return { href: `/rules?rule=${r.id}`, title, label: `${kind} · ${title}` }; +} + +// Titles here are often whole sentences; in running text a reference names its +// record in a few words and the tooltip carries the rest. +const MAX_TITLE = 60; + +function shorten(title: string): string { + if (title.length <= MAX_TITLE) return title; + const cut = title.slice(0, MAX_TITLE); + const space = cut.lastIndexOf(" "); + return (space > MAX_TITLE / 2 ? cut.slice(0, space) : cut).replace(/[\s,.;:—–-]+$/, "") + "…"; +} + +const BLOCK = "p, li, td, th, blockquote, h1, h2, h3, h4, h5, h6"; + +/** Whether the sentence around this link already names the record — a batch + * writes `#9 "Step two"`, and a paragraph citing one record twice names it + * the first time. A short title is drawn regardless: three letters turn up + * in prose by chance. */ +function alreadyNamed(a: HTMLAnchorElement, shown: string, title: string): boolean { + if (title.length < 8) return false; + const text = (a.closest(BLOCK) ?? a.parentElement)?.textContent?.toLowerCase() ?? ""; + return text.includes(title.toLowerCase()) || text.includes(shown.toLowerCase()); +} + +/** Draw the record's title in the link, its number after it, muted. Set as + * text, never as markup: a title is whatever its author typed. */ +function showTitle(a: HTMLAnchorElement, title: string): boolean { + const shown = shorten(title); + if (alreadyNamed(a, shown, title)) return false; + const name = document.createElement("span"); + name.className = "record-ref__title"; + name.textContent = shown; + const ref = document.createElement("span"); + ref.className = "record-ref__id"; + ref.textContent = a.textContent ?? ""; + a.replaceChildren(name, " ", ref); + return true; } function refKey(space: RefSpace, id: number): string { @@ -112,7 +159,10 @@ async function decorate(el: HTMLElement) { a.dataset.refState = "ok"; a.href = info.href; a.title = info.label; - a.setAttribute("aria-label", `${a.textContent}: ${info.label}`); + const bare = a.textContent; + // Drawn with its title, the link's own text is its accessible name; a bare + // number needs the label spoken for it. + if (!showTitle(a, info.title)) a.setAttribute("aria-label", `${bare}: ${info.label}`); } }