## What kind of change does this PR introduce?
follow-up to #50235 to reduce reference page payloads and cold rendering
overhead
## What is the current behavior?
reference pages ship a large rsc payload inside the html _ most of it is
duplication rather than content along with shiki that writes ~30
character css variable name for every syntax token making the page heavy
in some cases
## What is the new behavior?
- moves repeated styles into shared css and uses compact, namespaced
token classes
- renders details icons inside the client trigger
- follows shiki’s guidance to [reuse one
highlighter](https://shiki.style/guide/best-performance#cache-the-highlighter-instance)
and [load languages on
demand](https://shiki.style/guide/best-performance#use-shorthands)
`page size`
page | before | after | change
-- | -- | -- | --
javascript | 10.61 mb | 8.28 mb | -21.9%
dart | 4.59 mb | 4.13 mb | -10.1%
python | 4.38 mb | 3.73 mb | -14.9%
swift | 2.87 mb | 2.56 mb | -10.9%
server | 1.59 mb | 1.35 mb | -15.2%
kotlin | 3.42 mb | 3.17 mb | -7.2%
`cold initialization`
language | before | after | reduction
-- | -- | -- | --
bash | 2,180 ms | 23 ms | 98.95%
javascript | 2,245 ms | 38 ms | 98.29%
## Additional context
measured on a local production build which uses the checked in generated
content _ production has larger sdk data, so absolute sizes there will
be higher
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added reusable expand/collapse controls for API reference details,
with updated icons, labels, and styling.
* Improved code block rendering with class-based syntax highlighting,
wrapped-code support, responsive layouts, and lazy language loading.
* **Style**
* Added theme-aware syntax-token colors, line-number styling, and
configurable code-block shadows.
* Consolidated expandable reference panel and item styling.
* **Tests**
* Added coverage for syntax highlighting, code block rendering, language
support, token stability, and reference details.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Closes DOCS-1283
https://github.com/user-attachments/assets/6e55a27f-6f73-453b-b98f-e91d3c14a9e4
## Problem
Three defects in the docs code block:
- The scroll container has no `tabindex`. On `/guides/database/tables`,
18 blocks, none focusable, 2 overflowing at 1280px. Tab skips the scroll
region, so a keyboard-only user cannot scroll code that runs off the
edge.
- The container has `role="group"` with no accessible name, so it
announces as bare "group".
- The line-number gutter has no `aria-hidden`, so digits are read inline
with the code. A block linearizes as `1import { createClient } from
'@supabase/supabase-js'23const supabase = ...`, with lines 2 and 3
collapsing into "23".
Four more surfaced while testing the fix:
- The wrap and copy buttons were absolutely positioned inside the
element that scrolls, so `right-2` measured against the scrollable
content box. Scrolling dragged them out of the corner into the middle of
the code. This one predates the PR.
- The buttons preceded the code in the DOM, so a screen reader read two
actions before naming what they act on.
- `focus-within` only fired for the buttons, so focusing the block left
the controls invisible.
- Both buttons set an `aria-label` identical to their tooltip text, and
Radix points `aria-describedby` at the tooltip on focus, producing "Copy
code, button, Copy code".
## Solution
Keyboard:
- Split the scroll region out of the positioning container, so the
controls stay pinned.
- Give the scroll region a `tabIndex` and a focus ring.
- Reveal the controls on `group-focus-within`.
Screen reader:
- Name the region `<language>, <n> lines`. Code content stays readable;
the summary goes in the name so the group can be skipped or stepped
into.
- Map fence aliases to spoken names, so `ts` announces as TypeScript.
Only the ambiguous ones; `bash`, `python`, `kotlin`, `dart`, `swift`
already read fine.
- `aria-hidden` the gutter. The numbers are already `select-none`, and
copy takes its content from the source string rather than the DOM, so
copy behavior is unchanged.
- Order the controls after the code.
- Announce the word wrap toggle through a live region, matching the copy
button.
- Opt both buttons out of Radix's generated description.
Also moved the `data-wrapped` side effect out of the `setIsWrapped`
updater, since React calls updaters twice under StrictMode.
## Manual testing
1. Open `/docs/guides/database/tables`.
2. Run `document.querySelectorAll('.code-scroll[tabindex="0"]').length`
in the console. Expect `18`.
3. Run `[...document.querySelectorAll('.code-scroll')].map(b =>
b.getAttribute('aria-label'))`. Expect entries like `SQL, 11 lines` and
`bash, 2 lines`, plus one bare `2 lines` for the fence with no language.
4. Tab to a code block. Expect a visible focus ring, and the wrap and
copy buttons to appear.
5. Press ArrowRight on the block under "Basic data loading", which
overflows. Expect it to scroll, and the buttons to stay in the top-right
corner.
6. Press Enter on the wrap button. Expect the code to wrap and a screen
reader to announce "Word wrap enabled".
7. With VoiceOver on, focus a code block. Expect "SQL, 11 lines, code
block", then the code read without line numbers interleaved. Focus each
button and expect its name once, not twice.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Accessibility**
- Improved code block labels for screen readers, including programming
language and line count.
- Added announcements when word wrap is enabled or disabled.
- Enhanced keyboard focus behavior for code block controls.
- **Usability**
- Kept code block controls visible while scrolling through code.
- Improved wrapped-code overflow handling.
- Removed redundant tooltip descriptions for copy and word-wrap
controls.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
strictNullChecks was off for docs, which lets errors slip through and
leads to incorrect required/optional typing on Zod-inferred types. This
PR enables strictNullChecks and fixes all the existing violations.
Anthony Lio