feat(7741): a record reference shows the title of what it cites, before its number
CI & Build / Python lint (push) Successful in 2s
CI & Build / Plugin hooks (push) Successful in 12s
CI & Build / TypeScript typecheck (push) Successful in 32s
CI & Build / Python tests (push) Successful in 1m48s
CI & Build / integration (push) Successful in 2m7s
CI & Build / Build & push image (push) Successful in 36s

A cited #N, milestone N or rule N in a rendered body now reads as the
record's title followed by its number, muted, so a reader knows what is
cited without hovering. The stored text stays #N and the title is read at
render: every existing record benefits and an edited title shows wherever
it is cited. Titles past 60 characters are shortened at a word, with the
full kind, title and status in the tooltip. A reference whose paragraph
already names the record (a batch writes #9 "Step two") keeps the bare
number, as does one the reader cannot open.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-22 17:49:30 -05:00
co-authored by Claude Opus 5.5
parent 08fdabd5e9
commit da7c43aa8a
2 changed files with 66 additions and 8 deletions
+8
View File
@@ -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);
+58 -8
View File
@@ -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<string, NoteInfo>; milestones: Record<string, MilestoneInfo>; rules: Record<string, RuleInfo> };
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}`);
}
}