feat(ui): markdown reader parity — HTML blocks, GitHub alerts, GFM inline extras#597
Open
backnotprop wants to merge 4 commits intomainfrom
Open
feat(ui): markdown reader parity — HTML blocks, GitHub alerts, GFM inline extras#597backnotprop wants to merge 4 commits intomainfrom
backnotprop wants to merge 4 commits intomainfrom
Conversation
…line extras Brings the in-app markdown reader to parity with GitHub's flavored rendering. Additive across the parser + renderer; no behavior change for existing blocks. Refactor: - Extract InlineMarkdown (262 lines) out of Viewer.tsx into its own file - Extract BlockRenderer + block-type components (CodeBlock, HtmlBlock, AlertBlock, Callout) into components/blocks/ — Viewer drops from 1279 to ~770 lines - Each new block-level feature lands in BlockRenderer or a new blocks/*.tsx, not Viewer Block-level features: - Raw HTML blocks (<details>, <summary>, etc.) via balanced-tag parser branch, rendered through marked + DOMPurify for nested-markdown support; inner innerHTML set imperatively so React reconciliation doesn't collapse open <details> - GitHub alerts (> [!NOTE] / [!TIP] / [!WARNING] / [!CAUTION] / [!IMPORTANT]) with inline Octicons, title-case labels, GitHub's Primer colors (light + dark) - Directive containers (:::kind ... :::) with arbitrary kinds for project-specific callouts (note, tip, warning, danger, info, success, question, etc.) - Heading anchor ids — slugifyHeading() strips inline markdown, preserves unicode Inline features (all in InlineMarkdown, all code-span-safe): - Bare URL autolinks (https://...) with trailing-punctuation trimming - @mentions and #issue-refs — render as clickable links when repo is GitHub, styled spans otherwise; threaded via repoInfo.display through BlockRenderer - Emoji shortcodes (:wave:, :rocket:, 29 curated codes) via transformPlainText() - Smart punctuation (curly quotes, em/en dashes, ellipsis) applied only to plain-text fragments after code spans have been consumed Safety: - Render-time transforms live inside InlineMarkdown's plain-text push, which is only reached after code-span regex consumes code content. Backticks stay literal for shell/regex snippets. - DOMPurify allowlist (no on* handlers, no style attrs, no scripts) gates every raw HTML block. Unsafe link protocols (javascript:/data:/vbscript:/file:) stripped by sanitizeLinkUrl. Tests: +40 (149 total). New files: - utils/slugify.test.ts (10) — unicode, markdown stripping, edge cases - utils/inlineTransforms.test.ts (9) — emoji + smartypants - utils/parser.test.ts — alert detection (5 cases), directives (5 cases), HTML block balancing (5 cases) Fixtures for manual verification: - tests/test-fixtures/11-html-blocks.md - tests/test-fixtures/12-gfm-and-inline-extras.md (release-plan-shaped demo) Known limitations (not blockers): - Bare URL regex doesn't balance parens (https://en.wikipedia.org/wiki/Foo_(bar) drops the trailing ")") - Duplicate heading text → duplicate anchor ids (browser picks first on hash nav) - Directive body is inline-only (no nested headings/lists) For provenance purposes, this commit was AI assisted.
Root-cause fix for the missing-import bug caught in review: the UI package had no tsconfig.json and no typecheck script, so missing references like `getImageSrc` in the extracted InlineMarkdown slipped past vite/esbuild (which only type-strip, they don't resolve imports). Infrastructure: - Added packages/ui/tsconfig.json with proper module resolution, JSX config, and bundler-style paths. - Added globals.d.ts to accept side-effect CSS imports. - Added @types/react, @types/react-dom, @types/bun, @types/dompurify as devDeps on packages/ui so React / Bun / DOMPurify types actually resolve. - Wired `tsc --noEmit -p packages/ui/tsconfig.json` into the top-level `bun run typecheck` script. With the typecheck running, 0 errors remain in this PR's scope. Four pre-existing errors on main (plan-diff SVG type narrowing, sharing.ts SharePayload shape) are unrelated and tracked separately. Review fixes: - InlineMarkdown: import getImageSrc from ImageThumbnail. Was calling the helper without importing it — markdown images with relative paths (``) would throw ReferenceError at render. Regression caused by the InlineMarkdown extraction. - useAnnotationHighlighter: findTextInDOM now retries with the rendered form (transformPlainText) when the raw originalText doesn't match. Annotations made before smart-punctuation / emoji shortcodes shipped (straight quotes, `:wave:` text) still re-bind after reload. - sanitizeHtml: allow the `open` attribute so `<details open>` preserves its default-expanded state instead of always rendering collapsed. - parser.test.ts: narrow a string->AlertKind assertion to satisfy strict typechecking. Deferred (tracked as known limitation in PR description): - HtmlBlock relative URL rewriting for nested <img src="./logo.png"> / <a href="note.md">. New-feature gap, not a regression. For provenance purposes, this commit was AI assisted.
… paths Raw HTML blocks inject sanitized HTML verbatim, so nested <img src="./logo.png"> and <a href="notes.md"> resolved against the plannotator server URL instead of the plan's directory — images 404'd, .md links navigated away instead of opening in the linked-doc overlay. This is the path README.md content hits (hero <img>, YouTube thumbnails, <details> sections with anchors). Fix: after setting innerHTML, walk <img> and <a> elements and apply the same rewriting markdown content uses: - <img> relative src → getImageSrc(src, imageBaseDir), routing through /api/image?path=... with the plan's base directory. - <a> relative href matching .md / .mdx / .html → click handler that calls onOpenLinkedDoc, same pattern as [label](./foo.md) markdown links. - http(s):, data:, blob:, mailto:, tel:, and #anchor hrefs pass through untouched. BlockRenderer now threads imageBaseDir + onOpenLinkedDoc into HtmlBlock. React.memo equality extended to compare those props too, so legitimate changes still re-run the rewrite pass without forcing re-renders on every parent update. Verified against the repo's own README.md — hero image, YouTube thumbnails, and <details> sections all render correctly in annotate mode. For provenance purposes, this commit was AI assisted.
…/filter
Extracts table rendering into blocks/TableBlock and adds two companion
surfaces: a hover toolbar for quick copy, and a full-screen popout dialog
with TanStack-powered sort/filter/copy for power use. No pagination — plan
tables don't get that big.
Hover toolbar (blocks/TableToolbar.tsx):
- Floats above the table on mouse enter via React portal, positioned with
getBoundingClientRect + scroll/resize listeners, entry/exit animations.
Same positional pattern as AnnotationToolbar's top-right mode.
- Debounced hover state in Viewer (100ms leave → 150ms exit animation),
mirroring hoveredCodeBlock's state machine.
- Three actions: Copy markdown (icon), CSV (short uppercase button,
RFC 4180 escaping), Expand (opens popout).
Popout dialog (blocks/TablePopout.tsx):
- Radix Dialog, fullscreen-ish card with ~2rem backdrop visible for
click-to-close. max-w-[min(calc(100vw-4rem),1500px)].
- Portaled into Viewer's containerRef so the annotation hook can walk
into the popout's text nodes — selection-based annotations, text-search
restoration, and shared blockId all work across the collapsed and
popped-out views.
- TanStack Table for the grid: click column headers to sort (asc → desc →
clear), global filter input, no pagination. Row count indicator shows
"15 of 27" when filter reduces the set.
- Copy / CSV buttons in the header row: filter- and sort-aware. When
visible rows < total, tooltips read "Copy 15 rows as markdown" /
"Copy 15 rows as CSV". When no filter, copies whole table (normalized
whitespace). Read is one-shot on click — no derived state to sync.
- Floating X close button (absolute top-right), no header bar.
Chrome stacking while popout is open (CSS-only, via :has()):
- body:has([data-popout="true"]) drops four element types behind the
dialog: annotation sidebar, sticky header lane, app nav header, overlay
scrollbars. :has() observes the dialog's presence directly — when the
dialog unmounts, the selector stops matching and everything returns to
natural stacking. No JS state, no useEffect cleanup.
Shared helpers in TableBlock.tsx (exported):
- parseTableContent — pipe-delimited markdown → { headers, rows }
- buildCsvFromRows / buildMarkdownTable — inverse, from parsed data
- buildCsv — thin wrapper for the hover toolbar's raw-block path
Dependencies added:
- @radix-ui/react-dialog ^1.1.15 (~6 KB gzipped)
- @tanstack/react-table ^8.21.3 (~14 KB gzipped)
Fixture:
- tests/test-fixtures/12-gfm-and-inline-extras.md — added a 27×11
"Detailed feature backlog" table to exercise wide + deep tables,
horizontal scroll in the popout, and the sort/filter flows.
For provenance purposes, this commit was AI assisted.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Brings the in-app markdown reader to parity with GitHub's flavored rendering. Additive across parser + renderer, no behavior change for existing blocks.
What's in it
Refactor (before features — kept Viewer from growing):
InlineMarkdownout ofViewer.tsxinto its own file (262 lines)BlockRenderer+ block-type components intocomponents/blocks/(CodeBlock,HtmlBlock,AlertBlock,Callout)Viewer.tsx: 1279 → 770 lines. New block-level features land inBlockRendereror a newblocks/*.tsx— not Viewer.Block-level features:
<details>,<summary>, etc.) via balanced-tag parser branch. Rendered throughmarked+ DOMPurify for nested-markdown support.innerHTMLset imperatively via ref+useEffect so React reconciliation doesn't collapse open<details>.> [!NOTE]/[!TIP]/[!WARNING]/[!CAUTION]/[!IMPORTANT]) with inline Octicons, title-case labels, GitHub's Primer colors (light + dark viaprefers-color-scheme).:::kind ... :::) with arbitrary kinds for project-specific callouts.slugifyHeading()strips inline markdown, preserves unicode letters.Inline features (all in
InlineMarkdown, all code-span-safe):https://...) with trailing-punctuation trimming.repoInfo.displaythreaded through asgithubRepo), styled spans otherwise.:wave:,:rocket:, 29 curated codes) viatransformPlainText().Safety
InlineMarkdown's plain-text push, which is only reached after code-span regex consumes code content. Backticks stay literal for shell/regex snippets.on*handlers, nostyleattrs, no scripts) gates every raw HTML block.javascript:/data:/vbscript:/file:) stripped bysanitizeLinkUrl.Known limitations (not blockers)
https://en.wikipedia.org/wiki/Foo_(bar)drops the trailing)).Test plan
bun test packages/ui— 149 pass (40 new)bun run build:hook— builds cleanbun run --cwd apps/hook server/index.ts annotate tests/test-fixtures/12-gfm-and-inline-extras.md— demo plan renders cleanly top-to-bottom<details>blocks — nested markdown renders (tables, code, bold)<details>— annotation toolbar appears#rollout-plan→ scrolls to that heading@mention→ opensgithub.com/usernamein new tab (only in a git-linked repo)#123→ opens issue URL in new tabtests/test-fixtures/01-10render identically to main (no regressions)Bundle impact
+1.8KBgzipped (marked was already a dep; DOMPurify already included via other consumers). New assets:slugify(11 LOC),inlineTransforms(30 LOC),AlertBlock(45 LOC + inline SVG paths).