[docs] Add docs-infra Docs

.circleci/config.yml

@@ -56,6 +56,12 @@ jobs:
     steps:
       - checkout
       - install_js
+      - run:
+          name: Docs Infra Build
+          command: pnpm -F './packages/docs-infra' run build
+      - run:
+          name: ESLint
+          command: pnpm eslint:ci
       - run:
           name: ESLint
           command: pnpm eslint:ci

.lintignore

@@ -5,5 +5,7 @@ apps/tools-public/toolpad/**/*.yml
 build
 node_modules
 pnpm-lock.yaml
+.next
+docs/out
 
 __fixtures__

README.md

@@ -3,6 +3,10 @@
 Mono-repository for the MUI organization with code that can be public.
 See https://github.com/mui/mui-private for code that needs to be private.
 
+## Documentation
+
+You can [read the Infra documentation here](./docs/README.md).
+
 ## Applications
 
 ### [tools-public.mui.com](https://tools-public.mui.com/)
@@ -27,6 +31,11 @@ Internal public Toolpad apps that run the operations of MUI, built using https:/
 - Folder: `/packages/docs-infra/`
 - [Docs](./packages/docs-infra/README.md)
 
+### [code-infra](./packages/code-infra/)
+
+- Folder: `/packages/code-infra/`
+- [Docs](./packages/code-infra/README.md)
+
 ## Versioning
 
 Steps:

docs/.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

docs/README.md

@@ -0,0 +1,10 @@
+# MUI Infra Docs
+
+This package contains the documentation for the MUI Infra project, which is responsible for the infrastructure and tooling used in the various MUI documentation sites and libraries.
+
+[Read in Markdown](<./app/(shared)/page.mdx>)
+[Read in Browser](https://infra.mui.com)
+
+For the most immersive experience, we recommend opening this documentation in VSCode, starting with this README and working deeper into the documentation by navigating through the links provided (ctrl + click). You should have [the MDX extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) installed to view the documentation properly.
+
+To see demos live, run `pnpm run dev` and open <http://localhost:3000/>

docs/app/(shared)/layout.tsx

@@ -0,0 +1,20 @@
+import * as React from 'react';
+import type { Metadata } from 'next';
+import styles from '../layout.module.css';
+
+export const metadata: Metadata = {
+  title: 'MUI Infra Documentation',
+  description: 'How to use the MUI Infra packages',
+};
+
+export default function Layout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <div className={styles.root}>
+      <div className={styles.container}>{children}</div>
+    </div>
+  );
+}

docs/app/(shared)/page.mdx

@@ -0,0 +1,9 @@
+# MUI Infra
+
+## Docs Infra
+
+Read more about `docs-infra` [here](../docs-infra/page.mdx).
+
+## Code Infra
+
+Read more about `code-infra` [here](../code-infra/page.mdx).

docs/app/code-infra/layout.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import styles from '../layout.module.css';
+
+export const metadata: Metadata = {
+  title: 'MUI Code Infra Documentation',
+  description: 'How to use the MUI Code-Infra package',
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <div className={styles.root}>
+      <div className={styles.header}>
+        <Link href="/code-infra">MUI Code Infra</Link>
+      </div>
+      <div className={styles.container}>{children}</div>
+    </div>
+  );
+}

docs/app/code-infra/page.mdx

@@ -0,0 +1,21 @@
+# Code Infra
+
+This is the documentation for the MUI Internal Code Infra package.
+
+You can install this package using:
+
+```bash variant=pnpm
+pnpm install @mui/internal-code-infra
+```
+
+```bash variant=yarn
+yarn add @mui/internal-code-infra
+```
+
+```bash variant=npm
+npm install @mui/internal-code-infra
+```
+
+## Usage
+
+TODO

docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeController.tsx

@@ -0,0 +1,15 @@
+'use client';
+
+import * as React from 'react';
+import { CodeControllerContext } from '@mui/internal-docs-infra/CodeControllerContext';
+import type { ControlledCode } from '@mui/internal-docs-infra/CodeHighlighter/types';
+
+export function CodeController({ children }: { children: React.ReactNode }) {
+  const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
+
+  const contextValue = React.useMemo(() => ({ code, setCode }), [code, setCode]);
+
+  return (
+    <CodeControllerContext.Provider value={contextValue}>{children}</CodeControllerContext.Provider>
+  );
+}

docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditor.tsx

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { CodeHighlighter } from '@mui/internal-docs-infra/CodeHighlighter';
+import { createParseSource } from '@mui/internal-docs-infra/pipeline/parseSource';
+
+import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
+import { CodeController } from './CodeController';
+import { CodeEditorContent } from './CodeEditorContent';
+
+const initialCode = {
+  Default: {
+    url: 'file://live-example.js',
+    fileName: 'live-example.js',
+    source: `// Welcome to the live code editor!
+function greet(name) {
+  return \`Hello, \${name}!\`;
+}
+`,
+  },
+};
+
+export function CodeEditor() {
+  return (
+    <CodeProvider>
+      <CodeController>
+        <CodeHighlighter
+          url={initialCode.Default.url}
+          Content={CodeEditorContent}
+          code={initialCode}
+          controlled
+          sourceParser={createParseSource()}
+        />
+      </CodeController>
+    </CodeProvider>
+  );
+}

docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.module.css

@@ -0,0 +1,37 @@
+.container {
+  border: 1px solid #d0cdd7;
+  border-radius: 8px;
+}
+
+.header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 6px 12px;
+  border-bottom: 1px solid #d0cdd7;
+}
+
+.name {
+  color: #65636d;
+  font-size: 13px;
+  font-family: var(--font-geist-mono);
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.switchContainer {
+  display: flex;
+}
+.code {
+  padding: 6px;
+}
+
+.codeBlock {
+  margin: 0;
+  padding: 6px;
+  overflow-x: auto;
+}

docs/app/docs-infra/components/code-controller-context/demos/code-editor/CodeEditorContent.tsx

@@ -0,0 +1,50 @@
+'use client';
+
+import * as React from 'react';
+import { useEditable } from 'use-editable';
+import type { ContentProps } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useCode } from '@mui/internal-docs-infra/useCode';
+import { LabeledSwitch } from '@/components/LabeledSwitch';
+import styles from './CodeEditorContent.module.css';
+
+import '@wooorm/starry-night/style/light'; // load the light theme for syntax highlighting
+
+export function CodeEditorContent(props: ContentProps<object>) {
+  const preRef = React.useRef<HTMLPreElement | null>(null);
+  const code = useCode(props, { preClassName: styles.codeBlock, preRef });
+
+  const hasJsTransform = code.availableTransforms.includes('js');
+  const isJsSelected = code.selectedTransform === 'js';
+  const labels = { false: 'TS', true: 'JS' };
+  const toggleJs = React.useCallback(
+    (checked: boolean) => {
+      code.selectTransform(checked ? 'js' : null);
+    },
+    [code],
+  );
+
+  const onInput = React.useCallback(
+    (text: string) => {
+      code.setSource?.(text);
+    },
+    [code],
+  );
+
+  useEditable(preRef, onInput, { indentation: 2 });
+
+  return (
+    <div className={styles.container}>
+      <div className={styles.header}>
+        <span className={styles.name}>{code.selectedFileName}</span>
+        <div className={styles.headerActions}>
+          {hasJsTransform && (
+            <div className={styles.switchContainer}>
+              <LabeledSwitch checked={isJsSelected} onCheckedChange={toggleJs} labels={labels} />
+            </div>
+          )}
+        </div>
+      </div>
+      <div className={styles.code}>{code.selectedFile}</div>
+    </div>
+  );
+}

docs/app/docs-infra/components/code-controller-context/demos/code-editor/index.ts

@@ -0,0 +1,7 @@
+import { createDemo } from '@/functions/createDemo';
+import { CodeEditor } from './CodeEditor';
+
+export const DemoCodeControllerCodeEditor = createDemo(import.meta.url, CodeEditor, {
+  name: 'Live Code Editor',
+  slug: 'live-code-editor',
+});

docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoController.tsx

@@ -0,0 +1,59 @@
+'use client';
+
+import * as React from 'react';
+import { useRunner } from 'react-runner';
+import { CodeControllerContext } from '@mui/internal-docs-infra/CodeControllerContext';
+import type { ControlledCode } from '@mui/internal-docs-infra/CodeHighlighter/types';
+import { useCodeExternals } from '@mui/internal-docs-infra/CodeExternalsContext';
+
+function Runner({ code }: { code: string }) {
+  const externalsContext = useCodeExternals();
+  const scope = React.useMemo(() => {
+    let externals = externalsContext?.externals;
+    if (!externals) {
+      externals = { imports: { react: React } };
+    }
+
+    return { import: { ...externals } };
+  }, [externalsContext]);
+
+  const { element, error } = useRunner({ code, scope });
+
+  if (error) {
+    return <div>{error}</div>;
+  }
+
+  return element;
+}
+
+export function DemoController({ children }: { children: React.ReactNode }) {
+  const [code, setCode] = React.useState<ControlledCode | undefined>(undefined);
+
+  const components = React.useMemo(
+    () =>
+      code
+        ? Object.keys(code).reduce(
+            (acc, cur) => {
+              const source = code[cur]?.source;
+              if (!source) {
+                return acc;
+              }
+
+              acc[cur] = <Runner code={source} />;
+              return acc;
+            },
+            {} as Record<string, React.ReactNode>,
+          )
+        : undefined,
+    [code],
+  );
+
+  const contextValue = React.useMemo(
+    () => ({ code, setCode, components }),
+    [code, setCode, components],
+  );
+
+  return (
+    <CodeControllerContext.Provider value={contextValue}>{children}</CodeControllerContext.Provider>
+  );
+}

docs/app/docs-infra/components/code-controller-context/demos/demo-live/DemoLive.tsx

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import { CodeProvider } from '@mui/internal-docs-infra/CodeProvider';
+import { DemoController } from './DemoController';
+import { DemoCheckboxBasic } from './demo-basic';
+
+export function DemoLive() {
+  return (
+    <CodeProvider>
+      <DemoController>
+        <DemoCheckboxBasic />
+      </DemoController>
+    </CodeProvider>
+  );
+}