[docs-infra] Add @focus and Linter to Automatically Apply

[dav-is]

Preview Deploy

New: @focus annotation

Adds @focus-start / @focus-end comment annotations that mark the "important" portion of a code demo. When focus annotations are present, the code block becomes collapsible — unfocused regions are hidden behind an Expand/Collapse toggle so users see the relevant code first.

Key behaviors:

• @focus-start / @focus-end mark focused regions; everything outside collapses
• @padding N controls how many context lines surround focused regions (default 2)
• @min N sets the minimum visible lines before collapsing kicks in (default 6)
• Focus interacts correctly with @highlight and @highlight-text — highlighted lines inside a focused region use data-frame-type="focus", outside use data-frame-type="highlighted-unfocused"
• Large focused blocks are capped at focusFramesMaxSize (18 lines) with a fade-out truncation indicator

New: lintJavascriptDemoFocus ESLint plugin

An ESLint rule (@mui/internal-docs-infra/demo-focus) that automatically inserts @focus-start / @focus-end annotations into demo files that export a default React component. It focuses the component body and collapses boilerplate (imports, type definitions, helpers).

enhanceCodeEmphasis improvements

• @highlight-text now renders <mark> elements instead of <span data-hl>
• Focus frames get proper indent tracking (data-frame-indent) for CSS nesting
• Frame restructuring handles padding, truncation, and max-size splitting

Collapsible code UI

• Expand/Collapse toggle with no-JS support (CSS :checked checkbox)
• ResizeObserver-based scroll anchoring keeps focused code stable during expand/collapse transitions
• overflow-anchor: none on changing content prevents browser scroll jumps during tab switches
• Scrollbar gutter animation smooths the horizontal scrollbar appearance/disappearance
• Demos render inside a container with file tabs, copy button, variant selector, and JS/TS toggle

parseSource / calculateFrameRanges updates

• New frame types: focus, focus-unfocused, padding-top, padding-bottom
• Truncation support: data-frame-truncated="visible" / "hidden" for fade-out on large blocks
• Frame splitting at max size boundaries
• Padding frames get correct indent values from adjacent focused content

Other changes

• withDocsInfra: new emphasisOptions option for controlling focus behavior per-site
• loadCodeVariant: passes emphasisConfig through the pipeline
• Pre component: forwards data-collapsible attribute from code elements
• Demo docs page updated with new sections for focus, max-size, and collapsible demos

Breaking changes

• CSS needs to be updated to also support highlighting .frame instead of only .line
• @highlight-text produces <mark> elements

Screenshots

Improved animation

Screencast.From.2026-04-17.20-14-59.webm

Screencast.From.2026-04-13.13-31-07.webm

[code-infra-dashboard]

Deploy preview

• docs/app/docs-infra/pipeline/enhance-code-emphasis/page.mdx
• docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx
• docs/app/docs-infra/pipeline/page.mdx

Performance

Total duration: 15.17 ms ▼-2.02 ms^(-11.8%) | Renders: 4 ⁽⁺⁰⁾ | Paint: 62.90 ms ▼-13.12 ms^(-17.3%)

Test	Duration	Renders
DataGrid mount with paint timing	1.79 ms ▼-1.06 ms(-37.2%)	1 (+0)
HeavyList mount	9.26 ms ▼-0.85 ms(-8.4%)	1 (+0)
Counter click	4.12 ms ▼-0.11 ms(-2.6%)	2 (+0)

Details of benchmark changes

Bundle size

Bundle	Parsed size	Gzip size
@base-ui/react	0B(0.00%)	0B(0.00%)
@mui/x-charts-pro	0B(0.00%)	0B(0.00%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[brijeshb42]

Even if it is about linting docs, this eslint rule should live in code-infra since the package is already configured with dependencies.

[dav-is]

I think docs related eslint custom rules should stay in docs-infra because will depend on other exports and utilities from docs-infra. Otherwise, if it is in code-infra, that would create a dependency on docs-infra. To maintain a separate release process, I don't think code-infra should depend on docs-infra. The code-infra eslint config allows us to extend the code-infra config cleanly.

I think we could improve the way that docs-infra depends on eslint. Maybe we should use optional peer dependancies so it uses the same versions from code-infra?

[brijeshb42]

I dont see any dependencies of docs infra being used in the eslint plugin. Till that time, I think it makes sense to be in code-infra.

[Janpot]

Eslint plugins go in code-infra package: packages/code-infra/src/eslint/docsConfig.mjs
For now they're authored in plain javascript. We want to avoid making docs-infra a dependency of code-infra