References to guides, categories and pages in rich text (#101) #150

Merged
miko merged 3 commits from feature/101-references into development 2026-11-06 14:42:25 +01:00
Owner

Closes #101.

Summary

Authors select words in rich text, choose the bookmark in the inline toolbar and pick a guide, category or page by searching. The reference is stored by id; readers see the target's current title (ADR-0020), with a preview card on hover, and the stored text, unlinked, where the target is gone or hidden from them. Decisions in ADR-0026.

 parseInline                                   # src/richText/inline.ts
+  <span data-ref="guide:<id>">Title</span> → {tag : "ref", kind, id, text}

 page (reading view, step-by-step, category, page, home, PDF route)
+  loadReferences(documents, reader)          # src/references/loadReferences.ts
+    referencedIds → read guides, pages, category tree
+    resolveReferences → only targets the reader may see, by their listed title
   <RichText document images
+            references />                    # link + CSS hover card, else plain text
   <PdfRichText references />                 # absolute links

 Editor.js inline toolbar: bold, italic, link, inlineCode
+  reference                                  # src/richText/referenceTool.ts
+    searchReferenceTargets(query)            # server action, titles readers see
  • Works in guide descriptions and step content, category descriptions and pages.
  • Guide packages and backups keep references unchanged; a missing target shows as plain text.
  • Also fixed: inline toolbar icons turned white on white under the pointer in dark mode (Editor.js hard-codes a light hover background).

Evidence

  • Before: no references; inline tool icons under the pointer in dark mode at contrast 1.05.
    After:
    • e2e/references.spec.ts: author picks a guide by search → reader sees a link with the target's title and the card on hover → an unpublished rename neither shows nor is found by the search → after publishing, the new title shows → a guest sees the internal target as plain text.
    • e2e/richText.spec.ts: each inline tool button keeps a contrast ≥ 3 under the pointer in dark mode (failed at 1.05 before the fix).
    • Unit tests: sanitising (forged kinds/ids, refs inside links), resolving (visibility, drafts, deleted, latest version title), rendering (link + card vs. plain text).
    • typecheck, lint, 623 unit tests, 92 e2e tests green, except pages.spec.ts "keys and paste in a column stay in the column", which is flaky on development too (2 of 12 runs there, 0 of 12 on this branch).

Merge Danger

Door: two-way

No migration; references live in the existing rich text JSON. Stored content without references renders as before.

Blast Radius: rich-text

Every rich text render now passes through the reference resolver (one extra query per kind only when a document has references), and the inline toolbar gains a button in every editor.

🤖 Generated with Claude Code

Closes #101. ## Summary Authors select words in rich text, choose the bookmark in the inline toolbar and pick a guide, category or page by searching. The **reference** is stored by id; readers see the target's current title (ADR-0020), with a preview card on hover, and the stored text, unlinked, where the target is gone or hidden from them. Decisions in ADR-0026. ```diff parseInline # src/richText/inline.ts + <span data-ref="guide:<id>">Title</span> → {tag : "ref", kind, id, text} page (reading view, step-by-step, category, page, home, PDF route) + loadReferences(documents, reader) # src/references/loadReferences.ts + referencedIds → read guides, pages, category tree + resolveReferences → only targets the reader may see, by their listed title <RichText document images + references /> # link + CSS hover card, else plain text <PdfRichText references /> # absolute links Editor.js inline toolbar: bold, italic, link, inlineCode + reference # src/richText/referenceTool.ts + searchReferenceTargets(query) # server action, titles readers see ``` - Works in guide descriptions and step content, category descriptions and pages. - Guide packages and backups keep references unchanged; a missing target shows as plain text. - Also fixed: inline toolbar icons turned white on white under the pointer in dark mode (Editor.js hard-codes a light hover background). ## Evidence - **Before:** no references; inline tool icons under the pointer in dark mode at contrast 1.05. **After:** - `e2e/references.spec.ts`: author picks a guide by search → reader sees a link with the target's title and the card on hover → an unpublished rename neither shows nor is found by the search → after publishing, the new title shows → a guest sees the internal target as plain text. - `e2e/richText.spec.ts`: each inline tool button keeps a contrast ≥ 3 under the pointer in dark mode (failed at 1.05 before the fix). - Unit tests: sanitising (forged kinds/ids, refs inside links), resolving (visibility, drafts, deleted, latest version title), rendering (link + card vs. plain text). - typecheck, lint, 623 unit tests, 92 e2e tests green, except `pages.spec.ts` "keys and paste in a column stay in the column", which is flaky on `development` too (2 of 12 runs there, 0 of 12 on this branch). ## Merge Danger **Door:** two-way No migration; references live in the existing rich text JSON. Stored content without references renders as before. **Blast Radius:** rich-text Every rich text render now passes through the reference resolver (one extra query per kind only when a document has references), and the inline toolbar gains a button in every editor. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Authors select words in a guide's description or step content, a
category's description or a page's content, choose the bookmark in the
inline toolbar and pick a guide, category or page by searching its
title. The reference is stored by id in the inline text, as
<span data-ref="kind:id">, with the title it was written with.

Readers see the target's current title, as lists show it, linked, with a
card of its cover or category image and title on hover (plain CSS). Every
page resolves its references for the reader; a target that is gone or
hidden from them shows the stored text, unlinked. PDFs link to the
absolute address; guide packages and backups keep references as they are.
Decisions in ADR-0026.

The e2e helpers for the rich text editor move to e2e/richTextEditor.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Editor.js hard-codes a light background on its inline tool buttons under
the pointer, so the icons of italic, link, inline code and reference,
drawn in the theme's text colour, turned white on white in dark mode.
They now take the theme's sunken surface.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The editor's reference search matched a guide's working copy title and
any version's, so an author could find a published guide by a rename
that was not published yet, under another title (ADR-0020). It now
offers only what matches the title readers see.

Cleanups from the review: the referenced guides' query and cover mapping
live in one place (readReferencedGuides); a reference's kind and id are
one type (ReferenceTarget); the resolved references' types and the empty
map sit in a module of their own without dependencies, which the client
renderers and the PDF share; alignment and import order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
miko merged commit 4b7e00f05f into development 2026-11-06 14:42:25 +01:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
MassiveDynamic/kataba!150
No description provided.