CodeHighlight

Installation

CodeHighlight ships from the `@protocore/pds/code` subpath so its highlighter (Shiki, plus the language grammars) never enters the core bundle — the same way charts keep recharts out and the editor keeps tiptap out. shiki (>=4) is an optional peer; install it in any app that renders CodeHighlight.

pnpm add shiki

import { CodeHighlight } from "@protocore/pds/code";

Shiki is loaded through a lazy dynamic import inside the component, so it costs nothing until a CodeHighlight actually mounts. Until the async highlight resolves — and if JavaScript is disabled — the component renders a fully-styled plain-text <pre> with identical metrics, so there is no layout shift and it degrades gracefully.

TypeScript

Pass code and a language. The surface is a sunken, hairline-bordered mono panel; the header carries a filename (mono), the language chip, and a copy button. Highlight colours are dual-theme — they flip with the design system's data-theme.

import { createServer } from "node:http";

const server = createServer((req, res) => {
  res.writeHead(200, { "content-type": "application/json" });
  res.end(JSON.stringify({ ok: true, path: req.url }));
});

server.listen(3000, () => console.log("listening on :3000"));

Shell

Use bash/shell for terminal snippets. Drop the filename and pass a label instead to caption the block without implying a file on disk.

# install and start the dev server
pnpm add @protocore/pds shiki
pnpm --filter web dev

# tail the logs
pnpm --filter web logs --since 5m | grep -i error

JSON

json (and jsonc) for payloads and config. Turn on showLineNumbers for a counter gutter over the highlighted lines.

{
  "id": "evt_01H8Z",
  "type": "payment.settled",
  "amount": 4200,
  "currency": "eur",
  "livemode": true,
  "tags": ["region:eu-central-1", "priority"]
}

Python

The component advertises first-class support for the major languages — python, go, rust, java, kotlin, swift, ruby, php, sql, c, cpp, csharp, and more — so docs and product surfaces highlight consistently.

from dataclasses import dataclass


@dataclass
class Point:
    x: float
    y: float

    def distance_to(self, other: "Point") -> float:
        return ((self.x - other.x) ** 2 + (self.y - other.y) ** 2) ** 0.5


origin = Point(0, 0)
print(origin.distance_to(Point(3, 4)))  # 5.0

Go

Long lines scroll horizontally inside the region by default; pass wrap to soft-wrap instead. The code region is keyboard-focusable so it can be scrolled without a mouse.

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Now()
	total := 0
	for i := 0; i < 1_000_000; i++ {
		total += i
	}
	fmt.Printf("sum=%d elapsed=%s\n", total, time.Since(start))
}

CSS

Set withCopy={false} to drop the copy button; with no filename/label either, the header is omitted entirely and only the code shows.

.pds-Button {
  height: var(--pds-control-h-md);
  padding-inline: var(--pds-space-4);
  font-family: var(--pds-font-mono);
  text-transform: uppercase;
  letter-spacing: var(--pds-tracking-btn);
  border: 1px solid var(--pds-btn-bg);
  background: var(--pds-btn-bg);
  color: var(--pds-btn-fg);
}

CodeHighlight vs CodeBlock vs CodeRef

Three code surfaces, three jobs:

• CodeHighlight — *real syntax highlighting* for arbitrary source in any major language, via Shiki (optional peer, subpath). Reach for it when the language matters and you want tokens coloured.
• CodeBlock — a *static, dependency-free* mono panel in the core entry. Hand-authored spans (CodeComment, CodeLiteral) for the rare highlighted line; no grammar engine.
• CodeRef — an *inline* mono reference for a symbol, path, or key inside prose — not a block.

Accessibility

• The surface is a labelled `region` (`aria-label` derived from the filename/label and language), and the scrollable `<pre>` is `tabIndex=0` so keyboard users can scroll overflowing code.
• The copy button is a real `<button>` with an accessible name and announces its 'Copied' state politely to assistive tech.
• Before the async Shiki highlight resolves — and with JS disabled — the same code renders as styled plain text with identical metrics, so the content is always present and never shifts.
• Token colours are dual-theme via per-token CSS variables switched on `data-theme`; because the code text is always present regardless of colour, snippets stay legible for colour-blind and monochrome readers.