[docs-infra] Migrate demos to docs-infra

.circleci/config.yml

@@ -111,8 +111,6 @@ jobs:
     steps:
       - checkout
       - code-infra/install-deps
-      - code-infra/check-generated:
-          command: pnpm docs:typescript:formatted
       - run:
           name: Tests TypeScript definitions
           command: pnpm typescript:ci

AGENTS.md

@@ -58,12 +58,39 @@ pnpm proptypes && pnpm docs:api
 
 ### Docs demos
 
-Always author the TypeScript version of the demos. To generate the JavaScript variant, run:
+Demos live next to their page under `docs/data/<product>/components/<component>/demos/<demo-name>/`. Each demo folder contains three files:
 
-```bash
-pnpm docs:typescript:formatted
+- `<ComponentName>.tsx` — the demo source, authored as TypeScript (`.tsx`).
+- `client.ts` — marks the demo's client boundary:
+
+  ```ts
+  'use client';
+
+  import { createDemoClient } from '@mui/internal-core-docs/utils/createDemoClient';
+
+  export default createDemoClient(import.meta.url);
+  ```
+
+- `index.ts` — wires the demo into the docs pipeline:
+
+  ```ts
+  import { createDemo } from '@mui/internal-core-docs/utils/createDemo';
+  import ClientProvider from './client';
+  import BasicButtons from './BasicButtons';
+
+  export default createDemo(import.meta.url, BasicButtons, { ClientProvider });
+  ```
+
+Reference the demo from the page's markdown via the `component` field. Use a `file://` URL with a path relative to the markdown file:
+
+```md
+{{"component": "file://./demos/basic/index.ts"}}
 ```
 
+Demo options (`bg`, `hideToolbar`, `initialExpanded`, `collapseToEmpty`, `isolated`, `iframe`, `maxWidth`, `height`, `disableAd`, `disableLiveEdit`, `hideEditButton`, `aiSuggestion`, `anchorId`; `defaultCodeOpen` is a legacy alias for `initialExpanded`/`collapseToEmpty`) are defined by the `DemoOptions` interface in `packages-internal/core-docs/src/DemoContent/DemoContent.tsx`. Use `{/* @focus-start */}` / `{/* @focus-end */}` JSX comments inside the demo to highlight regions in the rendered code viewer.
+
+The demo infrastructure itself is documented at <https://mui-internal.netlify.app/docs-infra/>.
+
 ## Architecture
 
 This is a monorepo managed by Lerna with Nx for caching. Key packages:
@@ -228,8 +255,7 @@ Read the relevant `AGENTS.md` when helping users with those topics.
 3. `pnpm typescript` - Pass type checking
 4. `pnpm test:unit` - Pass unit tests
 5. If API changed: `pnpm proptypes && pnpm docs:api`
-6. If demos changed: `pnpm docs:typescript:formatted`
-7. If `.md` files changed: `pnpm vale <file1> <file2> ...` - Check prose style and grammar
+6. If `.md` files changed: `pnpm vale <file1> <file2> ...` - Check prose style and grammar
 
 ## PR Title Format
 

CONTRIBUTING.md

@@ -14,11 +14,28 @@ Here are a few guidelines that will help you along the way.
   - [Trying changes on the playground](#trying-changes-on-the-playground)
   - [How to increase the chances of being accepted](#how-to-increase-the-chances-of-being-accepted)
   - [CI checks and how to fix them](#ci-checks-and-how-to-fix-them)
+    - [Continuous Releases](#continuous-releases)
+    - [ci/circleci: checkout](#cicircleci-checkout)
+    - [ci/circleci: test_static](#cicircleci-test_static)
+    - [ci/circleci: test_unit-1](#cicircleci-test_unit-1)
+    - [ci/circleci: test_browser](#cicircleci-test_browser)
+    - [ci/circleci: test_regressions](#cicircleci-test_regressions)
+    - [ci/circleci: test_types](#cicircleci-test_types)
+    - [ci/circleci: test_bundle_size_monitor](#cicircleci-test_bundle_size_monitor)
+    - [argos](#argos)
+    - [deploy/netlify](#deploynetlify)
+    - [codecov/project](#codecovproject)
+    - [Misc](#misc)
   - [Updating the component API documentation](#updating-the-component-api-documentation)
   - [Coding style](#coding-style)
 - [Contributing to the documentation](#contributing-to-the-documentation)
   - [How to find docs issues to work on](#how-to-find-docs-issues-to-work-on)
   - [How to add a new demo to the docs](#how-to-add-a-new-demo-to-the-docs)
+    - [1. Create the demo folder](#1-create-the-demo-folder)
+    - [2. Write the demo code](#2-write-the-demo-code)
+    - [3. Add `client.ts` and `index.ts`](#3-add-clientts-and-indexts)
+    - [4. Reference the demo from Markdown](#4-reference-the-demo-from-markdown)
+    - [5. Submit your PR](#5-submit-your-pr)
 - [How can I use a change that hasn't been released yet?](#how-can-i-use-a-change-that-hasnt-been-released-yet)
 - [Roadmap](#roadmap)
 - [License](#license)
@@ -162,7 +179,6 @@ The following statements must be true:
 - The code is linted. If the code was changed, run `pnpm eslint`.
 - The code is type-safe. If TypeScript sources or declarations were changed, run `pnpm typescript` to confirm that the check passes.
 - The API docs are up to date. If API was changed, run `pnpm proptypes && pnpm docs:api`.
-- The demos are up to date. If demos were changed, run `pnpm docs:typescript:formatted`. See [about writing demos](#2-write-the-demo-code).
 - The pull request title follows the pattern `[product-name][Component] Imperative commit message`. (See: [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/) for a great explanation).
 
 Don't worry if you miss a step—the Continuous Integration will run a thorough set of tests on your commits, and the maintainers of the project can assist you if you run into problems.
@@ -286,47 +302,69 @@ Or [follow this link directly to the results of that search](https://github.com/
 
 ### How to add a new demo to the docs
 
-The following steps explain how to add a new demo to the docs using the Button component as an example:
+Demos are powered by [`@mui/internal-docs-infra`](https://mui-internal.netlify.app/docs-infra/). The following steps explain how to add a new demo using the Button component as an example.
 
-#### 1. Add a new component file to the directory
+#### 1. Create the demo folder
 
-Add the new file to the component's corresponding directory:
+Each demo lives in its own kebab-cased folder next to the component's markdown page:
 
 ```bash
-docs/src/pages/components/buttons/
+docs/data/material/components/buttons/demos/super/
 ```
 
-and give it a name: how about `SuperButtons.tsx`?
-
 #### 2. Write the demo code
 
-We use TypeScript to document our components.
-We prefer demos written in TypeScript (using the `.tsx` file format).
+Demos are authored as TypeScript (`.tsx`).
+
+```tsx
+// docs/data/material/components/buttons/demos/super/SuperButtons.tsx
+import * as React from 'react';
+import Button from '@mui/material/Button';
+
+export default function SuperButtons() {
+  return <Button>Super</Button>;
+}
+```
+
+Use `{/* @focus-start */}` / `{/* @focus-end */}` JSX comments inside the demo to highlight regions in the rendered code viewer.
+
+#### 3. Add `client.ts` and `index.ts`
 
-After creating a TypeScript demo, run `pnpm docs:typescript:formatted` to automatically create the JavaScript version, which is also required.
+```ts
+// docs/data/material/components/buttons/demos/super/client.ts
+'use client';
 
-If you're not familiar with TypeScript, you can write the demo in JavaScript, and a core contributor may help you migrate it to TypeScript.
+import { createDemoClient } from '@mui/internal-core-docs/utils/createDemoClient';
 
-#### 3. Edit the page's Markdown file
+export default createDemoClient(import.meta.url);
+```
+
+```ts
+// docs/data/material/components/buttons/demos/super/index.ts
+import { createDemo } from '@mui/internal-core-docs/utils/createDemo';
+import ClientProvider from './client';
+import SuperButtons from './SuperButtons';
+
+export default createDemo(import.meta.url, SuperButtons, { ClientProvider });
+```
 
-The Markdown file in the component's respective folder—in this case, `/buttons/buttons.md`—is the source of content for the document.
-Any changes you make there will be reflected on the website.
+#### 4. Reference the demo from Markdown
 
-Add a header and a brief description of the demo and its use case, along with the `"demo"` code snippet to inject it into the page:
+The Markdown file in the component's respective folder—in this case, `buttons.md`—is the source of content for the document. The `component` field is a `file://` URL relative to the Markdown file:
 
 ```diff
 +### Super buttons
 +
 +To create a super button for a specific use case, add the `super` prop:
 +
-+{{"demo": "pages/components/buttons/SuperButtons.js"}}
++{{"component": "file://./demos/super/index.ts"}}
 ```
 
-#### 4. Submit your PR
+Demo options (`bg`, `hideToolbar`, `isolated`, `iframe`, `defaultCodeOpen`, `maxWidth`, `height`, `disableAd`, `disableLiveEdit`, `hideEditButton`, `aiSuggestion`, `anchorId`) are defined by the `DemoOptions` interface in [`packages-internal/core-docs/src/DemoContent/DemoContent.tsx`](packages-internal/core-docs/src/DemoContent/DemoContent.tsx). See the [demo variants experiment page](docs/pages/experiments/docs/demos.md) for live examples.
 
-Now you're ready to [open a PR](#sending-a-pull-request) to add your new demo to the docs.
+#### 5. Submit your PR
 
-Check out [this Toggle Button demo PR](https://github.com/mui/material-ui/pull/19582/files) for an example of what your new and edited files should look like when opening your own demo PR.
+Now you're ready to [open a PR](#sending-a-pull-request) to add your new demo to the docs.
 
 ## How can I use a change that hasn't been released yet?