[docs-infra] Add @focus and Linter to Automatically Apply#1303
[docs-infra] Add @focus and Linter to Automatically Apply#1303
@focus and Linter to Automatically Apply#1303Conversation
lintJavascriptDemoFocus ESLint RulelintJavascriptDemoFocus ESLint Rule
Deploy preview
PerformanceTotal duration: 15.75 ms ▼-2.52 ms(-13.8%) | Renders: 4 (+0) | Paint: 68.59 ms ▼-8.88 ms(-11.5%)
Bundle size
Check out the code infra dashboard for more information about this PR. |
lintJavascriptDemoFocus ESLint Rule@focus and Linter to Automatically Apply
There was a problem hiding this comment.
Pull request overview
Adds a new @focus emphasis mechanism and collapsible-code rendering across the docs-infra pipeline, plus an ESLint rule that auto-inserts focus annotations into demo files to keep rendered demos centered on the “important” code.
Changes:
- Introduces
@focus-start/@focus-end(and related sizing controls) into the emphasis pipeline and frame restructuring/rendering. - Adds
lintJavascriptDemoFocusESLint rule and wires it into the repo ESLint config for docs demos. - Threads new “emphasis options” through
withDocsInfra, loaders, and types-highlighting pipelines; updates docs and demo styles/UI accordingly.
Reviewed changes
Copilot reviewed 132 out of 133 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| pnpm-lock.yaml | Adds workspace link for internal docs-infra package and new dependency resolution. |
| packages/docs-infra/src/withDocsInfra/withDocsInfra.ts | Plumbs demo/type/MDX code-block emphasis options into loaders and MDX rehype config. |
| packages/docs-infra/src/withDocsInfra/withDocsInfra.test.ts | Adds test coverage for the new emphasis option wiring. |
| packages/docs-infra/src/useCode/useFileNavigation.tsx | Adjusts <Pre /> keys to force re-render across transform/enhancement phases. |
| packages/docs-infra/src/useCode/useCode.ts | Passes selected transform into file navigation for deterministic re-rendering. |
| packages/docs-infra/src/useCode/Pre.tsx | Computes initial visible frames, fixes frame indexing, and forwards data-collapsible + truncation/description attrs. |
| packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.ts | Adds configurable emphasis defaults for authored code blocks and includes focus comment handling. |
| packages/docs-infra/src/pipeline/transformHtmlCodeBlock/transformHtmlCodeBlock.test.ts | Adds tests verifying default/overridden padding and focus max behavior. |
| packages/docs-infra/src/pipeline/parseSource/restructureFrames.ts | Updates frame indent/truncation handling using region indices and truncation metadata. |
| packages/docs-infra/src/pipeline/parseSource/restructureFrames.test.ts | Updates tests to include required regionIndex in ranges. |
| packages/docs-infra/src/pipeline/parseSource/parseSource.ts | Ensures unsupported grammars still get guttered HAST for enhancer compatibility. |
| packages/docs-infra/src/pipeline/parseSource/parseSource.test.ts | Updates expectations to match guttered output for unsupported content. |
| packages/docs-infra/src/pipeline/parseSource/createFrame.ts | Adds truncation metadata support and expands indent handling to focus frames. |
| packages/docs-infra/src/pipeline/parseSource/calculateFrameRanges.ts | Adds focus frame types, truncation splitting, per-directive overrides, validation, and auto-focus framing. |
| packages/docs-infra/src/pipeline/parseSource/addLineGutters.ts | Stores frame split size in HAST data for downstream reframing consistency. |
| packages/docs-infra/src/pipeline/parseSource/addLineGutters.test.ts | Adds assertions for new frameSize behavior. |
| packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.ts | Fixes line-number accounting after multi-line imports. |
| packages/docs-infra/src/pipeline/loaderUtils/parseImportsAndComments.test.ts | Adds regression test for comment line numbers after multi-line imports. |
| packages/docs-infra/src/pipeline/loadServerTypes/loadServerTypes.ts | Threads codeBlockEmphasisOptions through type highlighting + meta enhancement. |
| packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.ts | Passes emphasis options into HTML code block transform in raw type descriptions/examples. |
| packages/docs-infra/src/pipeline/loadServerTypes/highlightTypesMeta.test.ts | Adds test ensuring emphasis options affect raw property description code blocks. |
| packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.ts | Allows passing emphasis options into code block transforms during types highlighting. |
| packages/docs-infra/src/pipeline/loadServerTypes/highlightTypes.test.ts | Adds test coverage for emphasis options applied to description code blocks. |
| packages/docs-infra/src/pipeline/loadServerTypes/snapshots/highlightTypes.test.ts.snap | Updates snapshots for new default frame typing (e.g. focus). |
| packages/docs-infra/src/pipeline/loadPrecomputedTypes/loadPrecomputedTypes.ts | Threads codeBlockEmphasisOptions to server types pipeline from loader options. |
| packages/docs-infra/src/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.ts | Adds emphasis options support and includes focus directives among notable/removed comment prefixes. |
| packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.ts | Ensures guttered HAST for plain-text path and runs enhancers consistently. |
| packages/docs-infra/src/pipeline/loadCodeVariant/loadCodeVariant.test.ts | Updates tests for guttered HAST behavior and parsing-disabled path. |
| packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.ts | New ESLint rule to auto-insert focus annotations around demo “preview” sections. |
| packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/lintJavascriptDemoFocus.test.ts | Adds extensive RuleTester coverage for rule detection and autofixes. |
| packages/docs-infra/src/pipeline/lintJavascriptDemoFocus/index.ts | Exports the new ESLint rule from the package entrypoint. |
| packages/docs-infra/src/abstractCreateDemo/abstractCreateDemo.tsx | Adds sourceEnhancers plumb-through to demo creation pipeline. |
| packages/docs-infra/src/CodeHighlighter/types.ts | Extends HastRoot.data with collapsible and frameSize metadata. |
| packages/docs-infra/package.json | Exposes new lint rule entrypoint and adds @typescript-eslint/utils dependency. |
| package.json | Adds workspace dependency on @mui/internal-docs-infra for eslint config import. |
| eslint.config.mjs | Registers the new rule for docs demos and enables it with wrapReturn: true. |
| docs/next.config.mjs | Configures demo emphasis defaults for docs site (padding + focus max size). |
| docs/functions/createDemo/index.ts | Updates dogfooding export to point at collapsible demo content. |
| docs/components/Tabs/Tabs.module.css | Minor padding tweak for tabs UI. |
| docs/app/docs-infra/pipeline/with-docs-infra/types.md | Documents new emphasis options on withDocsInfra and MDX options. |
| docs/app/docs-infra/pipeline/with-docs-infra/page.mdx | Adds usage docs for demo and code-block emphasis configuration. |
| docs/app/docs-infra/pipeline/transform-html-code-block/page.mdx | Documents new transform defaults and optional configuration. |
| docs/app/docs-infra/pipeline/page.mdx | Adds new “Lint JavaScript Demo Focus” section and updates emphasis outline. |
| docs/app/docs-infra/pipeline/load-server-types/page.mdx | Documents codeBlockEmphasisOptions for type metadata code blocks. |
| docs/app/docs-infra/pipeline/load-precomputed-types/page.mdx | Documents loader option for code block emphasis configuration. |
| docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.ts | Adds types page backing module for the new lint rule docs. |
| docs/app/docs-infra/pipeline/lint-javascript-demo-focus/types.md | Adds generated API docs for the new lint rule. |
| docs/app/docs-infra/pipeline/lint-javascript-demo-focus/page.mdx | Adds narrative docs for the new lint rule and its autofix behavior. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/types.md | Updates emphasis types docs for new focus/truncation/override capabilities. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/useScrollAnchor.ts | New hook to keep scroll stable during expand/collapse transitions. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/index.ts | Adds new demo entry for focus max-size behavior. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/max-size-code/MaxSizeCode.tsx | Adds demo source using focus/highlight directives for truncation behavior. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/indent-code/IndentCode.tsx | Updates demo to use focus directives and include focus comment prefix handling. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/focus-code/FocusCode.tsx | Updates demo to use focus directives and include focus comment prefix handling. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/index.ts | Adds new collapsible demo entry. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/createDemo.ts | Creates local demo factory for collapsible demo. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-demo/Counter.tsx | Adds demo component with focus + highlight directives. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/collapsible-code/CollapsibleCode.tsx | Wraps parsing section in focus annotations for demo presentation. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.tsx | Hooks expand/collapse to scroll anchoring behavior. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/IndentContent.module.css | Updates styling for frames, truncation fade, and collapsible behavior. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.tsx | Adds full demo UI (tabs/copy/variant/JS toggle) with no-JS expand/collapse + scroll anchoring. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleDemoContent.module.css | Styles the new collapsible demo UI, toggle, and frame behaviors. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.tsx | Adds checkbox-based no-JS toggle and scroll anchoring integration. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CollapsibleContent.module.css | Updates collapsible styles, truncation fade, and frame-level highlighting. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeMaxSize.tsx | Adds a server component demo using focusFramesMaxSize to force truncation behavior. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/CodeIndent.tsx | Wraps rendered demo code in focus annotations for emphasis. |
| docs/app/docs-infra/pipeline/enhance-code-emphasis/demos/Code.tsx | Wraps rendered demo code in focus annotations for emphasis. |
| docs/app/docs-infra/hooks/use-url-hash-state/demos/tab-navigation/TabNavigation.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/data-attr/Component.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/blocks/TypesComponent.tsx | Adds focus annotations around the primary displayed section. |
| docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentRoot.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/blocks/Component/ComponentPart.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/TypesAlertDialog.tsx | Adds focus annotations around the primary displayed section. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogTrigger.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/Dialog/DialogClose.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-inherited/AlertDialog/AlertDialogTrigger.tsx | Wraps return in focus annotation for single-line emphasis. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/TypesComponent.tsx | Adds focus annotations around the primary displayed section. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Root/ComponentRoot.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/blocks-data-attr/Component/Part/ComponentPart.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/basic/Component.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-types/demos/TypesTable.tsx | Adds focus annotations around main hook usage/rendering section. |
| docs/app/docs-infra/hooks/use-preference/demos/variant-selector/VariantSelector.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/hooks/use-copier/demos/text-input-copy/TextInputCopy.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/components/code-provider/demos/fetch-demo/demo-basic/CheckboxBasic.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-provider/demos/fetch-demo/Docs.tsx | Adds focus annotations around provider + demo composition. |
| docs/app/docs-infra/components/code-provider/demos/fetch-demo/CodeProviderGitHub.tsx | Adds focus annotations around CodeProvider wrapper. |
| docs/app/docs-infra/components/code-provider/demos/base/BasicCode.tsx | Adds focus annotations around provider wrapper. |
| docs/app/docs-infra/components/code-provider/demos/Code.tsx | Adds focus annotations around CodeHighlighter wrapper. |
| docs/app/docs-infra/components/code-highlighter/types.md | Updates docs for extended HastRoot.data shape. |
| docs/app/docs-infra/components/code-highlighter/demos/demo/demo-basic/CheckboxBasic.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/tailwind/CheckboxRed.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-variants/demo-default/css-modules/CheckboxRed.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-server-loaded/demo-basic/CheckboxBasic.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/demo-red/CheckboxRed.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback/DemoContentLoading.tsx | Adds focus annotations around primary content block. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/tailwind/CheckboxRed.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/demo-red/css-modules/CheckboxRed.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-variants/DemoContentLoading.tsx | Adds focus annotations around primary content block. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/demo-red/CheckboxRed.tsx | Adds focus annotation around preview return value. |
| docs/app/docs-infra/components/code-highlighter/demos/demo-fallback-all-files/DemoContentLoading.tsx | Adds focus annotations around primary content block. |
| docs/app/docs-infra/components/code-highlighter/demos/code-transformed/Code.tsx | Adds focus annotations around CodeHighlighter wrapper. |
| docs/app/docs-infra/components/code-highlighter/demos/code-transformed/BasicCode.tsx | Adds focus annotation around preview usage. |
| docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/Code.tsx | Adds focus annotations around CodeHighlighter wrapper. |
| docs/app/docs-infra/components/code-highlighter/demos/code-highlight-init/BasicCode.tsx | Adds focus annotation around preview usage. |
| docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/Code.tsx | Adds focus annotations around CodeHighlighter wrapper. |
| docs/app/docs-infra/components/code-highlighter/demos/code-highlight-idle/BasicCode.tsx | Adds focus annotation around preview usage. |
| docs/app/docs-infra/components/code-highlighter/demos/code-basic/BasicCode.tsx | Adds focus annotation around preview usage. |
| docs/app/docs-infra/components/code-highlighter/demos/DemoContent.tsx | Adds focus annotations around main hook usage/rendering section. |
| docs/app/docs-infra/components/code-highlighter/demos/DemoContent.module.css | Updates styling for frame-based emphasis and <mark> highlight rendering. |
| docs/app/docs-infra/components/code-highlighter/demos/CodeContent.tsx | Adds focus annotations around main hook usage/rendering section. |
| docs/app/docs-infra/components/code-highlighter/demos/CodeContent.module.css | Updates styling for frame-based emphasis, <mark> highlights, and truncation rounding. |
| docs/app/docs-infra/components/code-highlighter/demos/CodeBlock.tsx | Adds focus annotations around CodeHighlighter wrapper. |
| docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileEditor.tsx | Adds focus annotations around provider/controller composition. |
| docs/app/docs-infra/components/code-controller-context/demos/multi-file/MultiFileContent.tsx | Adds focus annotations around main code navigation/selection logic. |
| docs/app/docs-infra/components/code-controller-context/demos/demo-live/demo-basic/CheckboxBasic.tsx | Adds JSX focus annotations around the interactive preview region. |
| docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.tsx | Adds focus annotations around main demo logic. |
| docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLiveContent.module.css | Updates styling for frame-based emphasis and block layout. |
| docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx | Adds focus annotations around provider/controller composition. |
| docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx | Adds focus annotations around main controller logic. |
| docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx | Adds focus annotations around main editor logic. |
| docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.module.css | Updates styling for frame-based emphasis and block layout. |
| docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx | Adds focus annotations around provider/controller composition. |
| docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx | Adds focus annotations around main controller logic. |
| docs/app/bench/docs-infra/components/code-highlighter/demos/code/page.tsx | Adds focus annotations around benchmark code highlighter instance. |
| docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContentLoading.tsx | Adds JSX focus annotations around the code preview block. |
| docs/app/bench/docs-infra/components/code-highlighter/demos/CodeContent.tsx | Adds focus annotations around main hook usage/rendering section. |
| .circleci/orbs/code-infra.yml | Ensures docs-infra is built before running ESLint so the new plugin can be imported. |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Let's update dependent repos before merging this so that this isn't breaking anymore? |
After this is merged, this PR fixes the breaking changes: https://github.com/mui/base-ui/pull/4659/changes Other Base UI repos will just have to be synced |
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <copilot@github.com>
| '@next/next/no-img-element': 'off', | ||
| }, | ||
| }, | ||
| { |
There was a problem hiding this comment.
Can you already create a factory function like we do for the base config to distribute docs eslint configuration? We can then migrate the existing createDocConfig to the @mui/internal-docs-infra now or in a follow-up.
There was a problem hiding this comment.
I think we should take care of this in a followup PR since this PR only adds a single lint rule for the time being
Preview Deploy
Downstream Base UI PR
New:
@focusannotationAdds
@focus-start/@focus-endcomment 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-endmark focused regions; everything outside collapses@padding Ncontrols how many context lines surround focused regions (default 2)@min Nsets the minimum visible lines before collapsing kicks in (default 6)@highlightand@highlight-text— highlighted lines inside a focused region usedata-frame-type="focus", outside usedata-frame-type="highlighted-unfocused"focusFramesMaxSize(18 lines) with a fade-out truncation indicatorNew:
lintJavascriptDemoFocusESLint pluginAn ESLint rule (
@mui/internal-docs-infra/demo-focus) that automatically inserts@focus-start/@focus-endannotations into demo files that export a default React component. It focuses the component body and collapses boilerplate (imports, type definitions, helpers).enhanceCodeEmphasisimprovements@highlight-textnow renders<mark>elements instead of<span data-hl>data-frame-indent) for CSS nestingCollapsible code UI
:checkedcheckbox)ResizeObserver-based scroll anchoring keeps focused code stable during expand/collapse transitionsoverflow-anchor: noneon changing content prevents browser scroll jumps during tab switchesparseSource/calculateFrameRangesupdatesfocus,focus-unfocused,padding-top,padding-bottomdata-frame-truncated="visible"/"hidden"for fade-out on large blocksOther changes
withDocsInfra: newemphasisOptionsoption for controlling focus behavior per-siteloadCodeVariant: passesemphasisConfigthrough the pipelinePrecomponent: forwardsdata-collapsibleattribute from code elementsBreaking changes
.frameinstead of only .line@highlight-textproduces<mark>elementsScreenshots
Improved animation
Screencast.From.2026-04-17.20-14-59.webm
Screencast.From.2026-04-13.13-31-07.webm