feat(code-block): highlight via the CSS Custom Highlight API, add lineNumbers

[tmccoy14]

Context

CodeBlock highlighted through react-syntax-highlighter (Prism + refractor/all), which wraps every token in a <span> and ships its themes as JS objects applied as inline styles. That forced the component to resolve the active theme in JS — the only place in the library doing so — which picked the wrong palette when two themes were on screen and couldn't see the theme at all from inside a shadow root.

What changed

Highlighting engine

Swapped to MicroLighter, which reads TextMate grammars and paints ranges through the CSS Custom Highlight API. No token spans: ranges are registered against the existing text node, so the DOM a user copies is the source string. Grammars load on demand, so a page only pays for the languages it renders.

The palette moved wholly into the stylesheet and now resolves through the cascade, so nested themes and live theme flips are correct with no re-render.

Bundle cost, measured by bundling each library in isolation with esbuild --minify, React external:

	raw	gzip
react-syntax-highlighter (Prism entry)	632.3 KB	223.0 KB
microlighter initial chunk	6.6 KB	3.0 KB

The old import was static, so all 632 KB landed in the initial bundle. MicroLighter's grammars are dynamic imports — esbuild split them into 37 separate chunks, confirming the on-demand behaviour. Per-grammar cost: JSON 304 B gzip, bash 493 B, TypeScript 552 B. A page rendering JSON, TS and bash goes from 223 KB gzip to ~4.4 KB.

New lineNumbers prop

Numbers every line in a sticky gutter that stays put while long lines scroll under it. Numbering and wrapping are mutually exclusive — a wrapped line occupies more rows than its number does — so setting it switches long lines from wrapping to horizontal scrolling.

Accessibility

The scroll region is now focusable (tabIndex={0}, role="region", labelled from title) with the standard focus ring, so the overflow it owns is reachable by keyboard. This closes a pre-existing gap from max-h-64 as well as the new horizontal scrolling.

New public exports

CODE_BLOCK_ATTRIBUTE and scheduleHighlight (from lib/highlight.ts) let an application opt its own <pre> — a diff view, an editor — into the same pass and palette.

Consumer-visible changes

• Token colours change substantially in both themes. Light: strings green → dark red, numbers magenta → green, keywords blue → purple, comments grey → green. Dark: the previous near-neon palette (cyan keywords, lime strings, gold functions) gives way to vscode-plus's muted set. Worth a heads-up to anyone with screenshots in their own docs.
• Bold and italic tokens are gone: ::highlight() accepts only colour and decoration properties, so Markdown **bold**/_italic_ and CSS !important take a colour instead.
• Each code block adds one tab stop to the page's keyboard order.
• Below Baseline (June 2025 — Firefox 140 joining Chrome and Safari) no highlights register and code renders as unstyled monospace. Header, copy button and layout are unaffected; the fallback costs colour only.
• @eqtylab/equality 3.3.1 → 3.4.0.

Docs

code-block.mdx rewritten for the new engine: the 37 shipped grammars and 13 aliases, browser support, ::highlight() styling limits, the lineNumbers section, and a section on highlighting your own markup.

Multi-line samples moved into packages/demo/src/components/demo/code-block.tsx — Prettier's MDX parser reformats template literals embedded in JSX expressions and flattens their indentation, which defeats the point of a line-numbers demo.

Also in this PR

Two unrelated cleanups picked up along the way, each in its own commit:

• chore(lint) — the flat-config ignores: ['dist'] pattern resolves relative to the config file, so it only ever ignored a root-level /dist and pnpm lint failed on packages/ui/dist whenever the library had been built. Globbed to **/dist. Also dropped a variant prop AvatarShapeDemo never read.
• chore(tsconfig) — baseUrl is deprecated and stops functioning in TypeScript 7. Removed from both tsconfigs with every paths mapping rewritten self-relative. Nothing relied on baseUrl's bare-specifier lookup; internal imports all go through the @/, @demo/ and @eqtylab/ aliases or relative paths.

Verification

• pnpm lint → exit 0
• pnpm format:check → clean, whole repo
• tsc --noEmit (ui) → exit 0; astro check (demo) → 0 errors, 0 warnings
• Clean pnpm build from deleted dist dirs → both packages built, 67 demo pages
• Zero stray @/ specifiers in dist/index.js and dist/index.d.ts, confirming tsup/esbuild still resolves aliases without baseUrl
• All 36 highlight categories present in the compiled CSS
• Palette change confirmed visually by rendering the same TSX sample through both engines in light and dark

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The docs contain copy/paste issues and the wrapping behavior for long unbroken tokens appears inconsistent with the intended wrap-vs-scroll UX.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the CodeBlock component in the Equality design system to use MicroLighter + the CSS Custom Highlight API for token coloring (removing Prism token DOM spans and JS-resolved themes), adds optional sticky line numbers, and includes related demo/docs updates plus small lint/tsconfig maintenance.

Changes:

• Replace react-syntax-highlighter with microlighter, introducing a shared scheduleHighlight() pass and CSS-driven syntax palettes.
• Add a lineNumbers?: boolean prop to CodeBlock with a sticky gutter and horizontal scrolling when enabled.
• Update demo documentation and samples; adjust ESLint ignore globs and remove deprecated baseUrl usage from tsconfigs.

File summaries

File	Description
pnpm-lock.yaml	Removes react-syntax-highlighter deps and adds microlighter to the lockfile.
packages/ui/package.json	Bumps @eqtylab/equality to 3.4.0 and swaps highlighting dependency to microlighter.
packages/ui/tsconfig.json	Removes baseUrl and rewrites paths mappings to be self-relative.
packages/demo/tsconfig.json	Removes baseUrl and rewrites paths mappings to be self-relative.
packages/ui/src/types/microlighter.d.ts	Adds a local module declaration for microlighter to type highlightAll.
packages/ui/src/lib/highlight.ts	Introduces shared CODE_BLOCK_ATTRIBUTE and scheduleHighlight() for coalesced rescans.
packages/ui/src/index.ts	Exports CODE_BLOCK_ATTRIBUTE and scheduleHighlight as new public API.
packages/ui/src/components/code-block/code-block.tsx	Rebuilds CodeBlock markup for text-node-based highlighting, adds focusable scroll region + line numbers.
packages/ui/src/components/code-block/code-block.module.css	Moves token palette to CSS ::highlight() rules and adds layout styles for numbered gutter.
packages/demo/src/content/components/code-block.mdx	Rewrites docs for new engine, browser support, line numbers, and custom markup highlighting.
packages/demo/src/components/demo/code-block.tsx	Adds multi-line sample sources for docs demos (esp. line numbers).
packages/demo/src/components/demo/avatar.tsx	Removes an unused variant prop from AvatarShapeDemo.
eslint.config.mjs	Fixes ignore patterns to match dist and node_modules in any package directory.

Review details

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

• Files reviewed: 11/13 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.