Generate API docs for Toolpad Core

.eslintignore

@@ -4,6 +4,7 @@ pnpm-lock.yaml
 /docs/export
 /docs/schemas
 /packages/**/dist
+/packages/**/build
 /packages/toolpad-studio/.next
 /packages/toolpad-studio/public
 

.eslintrc.js

@@ -77,7 +77,7 @@ module.exports = {
       'error',
       {
         // https://github.com/import-js/eslint-plugin-import/issues/1739
-        ignore: ['\\.md\\?muiMarkdown$'],
+        ignore: ['\\?@mui/markdown$'],
       },
     ],
     'import/no-restricted-paths': [
@@ -129,7 +129,14 @@ module.exports = {
         'packages/toolpad-studio-runtime/**/*',
         'packages/toolpad-utils/**/*',
       ],
-      excludedFiles: ['tsup.config.ts', '*.spec.ts', '*.spec.tsx', 'vitest.config.ts'],
+      excludedFiles: [
+        'tsup.config.ts',
+        '*.spec.ts',
+        '*.spec.tsx',
+        '*.test.ts',
+        '*.test.tsx',
+        'vitest.config.ts',
+      ],
       rules: {
         'import/no-extraneous-dependencies': ['error'],
       },

.gitignore

@@ -48,6 +48,7 @@ lerna-debug.log
 .env
 
 dist/
+build/
 
 packages/toolpad-studio/public/web_modules
 packages/toolpad-studio/public/runtime

.npmrc

@@ -1,5 +1,5 @@
 # Enforce pnpm
 
-engine-strict = true
-auto-install-peers = true
+engine-strict=true
+auto-install-peers=true
 strict-peer-dependencies=false

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Local development
 
-If you would like to hack on Toolpad Studio or want to run the latest version, you can follow these steps:
+If you would like to hack on Toolpad or want to run the latest version, you can follow these steps:
 
 _If you're looking into contributing to the docs, follow the [instructions](#building-and-running-the-documentation) down below_
 
@@ -11,7 +11,7 @@ _If you're looking into contributing to the docs, follow the [instructions](#bui
 - git
 - node.js
 
-### Running apps inside the monorepo (recommended)
+### Running Toolpad Studio apps inside the monorepo (recommended)
 
 This uses the local version of Toolpad Studio as built in the mono-repository.
 This is recommended when your app is in a folder inside of the mono-repository.
@@ -139,6 +139,34 @@ pnpm install
 
 </details>
 
+### Developing on Toolpad Core
+
+This uses the local version of Toolpad Core as built in the mono-repository, and allows for quickly testing out changes and their results.
+
+Some application examples for different JavaScript frameworks (such as Next.js, Vite...) are present in the `playground` folder that can be used to quickly develop on Toolpad Core on a live application.
+
+1. Install dependencies:
+
+   ```bash
+   pnpm install
+   ```
+
+2. Run the built-in watch mode
+
+   ```bash
+   pnpm dev
+   ```
+
+3. Run any application in the `playground` folder in development mode, such as `toolpad-core-nextjs`
+
+   ```bash
+   cd playground/toolpad-core-nextjs
+   ```
+
+   ```bash
+   pnpm dev
+   ```
+
 ## Running integration tests
 
 The playwright tests can be run in one of two modes:
@@ -198,7 +226,7 @@ Use the `--ui` flag to run the tests interactively.
 
 ## Using CodeSandbox CI
 
-Each pull request is built on [CodeSandbox CI](https://codesandbox.io/docs/learn/sandboxes/ci). As a result of that we have a published Toolpad Studio package for ever pull request. To use the package from the pull request, take the following steps:
+Each pull request is built on [CodeSandbox CI](https://codesandbox.io/docs/learn/sandboxes/ci). As a result of that we have a published Toolpad Studio package for every pull request. To use the package from the pull request, take the following steps:
 
 1. In the GitHub PR checks, locate the ci/codesandbox check and make sure it has successfully finished building. Click on "details" to open the CodeSandbox CI user interface.
 

babel.config.js

@@ -0,0 +1,150 @@
+const path = require('path');
+
+const errorCodesPath = path.resolve(__dirname, './docs/public/static/error-codes.json');
+const missingError = process.env.MUI_EXTRACT_ERROR_CODES === 'true' ? 'write' : 'annotate';
+
+function resolveAliasPath(relativeToBabelConf) {
+  const resolvedPath = path.relative(process.cwd(), path.resolve(__dirname, relativeToBabelConf));
+  return `./${resolvedPath.replace('\\', '/')}`;
+}
+
+const productionPlugins = [
+  ['babel-plugin-react-remove-properties', { properties: ['data-mui-test'] }],
+];
+
+module.exports = function getBabelConfig(api) {
+  const useESModules = api.env(['regressions', 'stable', 'rollup']);
+
+  const defaultAlias = {
+    '@toolpad/core': resolveAliasPath('./packages/toolpad-core/src'),
+    docs: resolveAliasPath('./node_modules/@mui/monorepo/docs'),
+    'docs-toolpad': resolveAliasPath('./docs'),
+    test: resolveAliasPath('./test'),
+    '@mui-internal/api-docs-builder': resolveAliasPath(
+      './node_modules/@mui/monorepo/packages/api-docs-builder',
+    ),
+  };
+
+  const presets = [
+    [
+      '@babel/preset-env',
+      {
+        bugfixes: true,
+        browserslistEnv: process.env.BABEL_ENV || process.env.NODE_ENV,
+        debug: process.env.MUI_BUILD_VERBOSE === 'true',
+        modules: useESModules ? false : 'commonjs',
+      },
+    ],
+    [
+      '@babel/preset-react',
+      {
+        runtime: 'automatic',
+      },
+    ],
+    '@babel/preset-typescript',
+  ];
+
+  const plugins = [
+    [
+      'babel-plugin-macros',
+      {
+        muiError: {
+          errorCodesPath,
+          missingError,
+        },
+      },
+    ],
+    'babel-plugin-optimize-clsx',
+    [
+      '@babel/plugin-transform-runtime',
+      {
+        useESModules,
+        // any package needs to declare 7.4.4 as a runtime dependency. default is ^7.0.0
+        version: '^7.4.4',
+      },
+    ],
+    [
+      'babel-plugin-transform-react-remove-prop-types',
+      {
+        mode: 'unsafe-wrap',
+      },
+    ],
+  ];
+
+  if (process.env.NODE_ENV === 'production') {
+    plugins.push(...productionPlugins);
+  }
+
+  return {
+    assumptions: {
+      noDocumentAll: true,
+    },
+    presets,
+    plugins,
+    ignore: [/@babel[\\|/]runtime/], // Fix a Windows issue.
+    overrides: [
+      {
+        exclude: /\.test\.(js|ts|tsx)$/,
+        plugins: ['@babel/plugin-transform-react-constant-elements'],
+      },
+    ],
+    env: {
+      coverage: {
+        plugins: [
+          'babel-plugin-istanbul',
+          [
+            'babel-plugin-module-resolver',
+            {
+              root: ['./'],
+              alias: defaultAlias,
+            },
+          ],
+        ],
+      },
+      development: {
+        plugins: [
+          [
+            'babel-plugin-module-resolver',
+            {
+              root: ['./'],
+              alias: defaultAlias,
+            },
+          ],
+        ],
+      },
+      rollup: {
+        plugins: [
+          [
+            'babel-plugin-module-resolver',
+            {
+              alias: defaultAlias,
+            },
+          ],
+        ],
+      },
+      test: {
+        sourceMaps: 'both',
+        plugins: [
+          [
+            'babel-plugin-module-resolver',
+            {
+              root: ['./'],
+              alias: defaultAlias,
+            },
+          ],
+        ],
+      },
+      benchmark: {
+        plugins: [
+          ...productionPlugins,
+          [
+            'babel-plugin-module-resolver',
+            {
+              alias: defaultAlias,
+            },
+          ],
+        ],
+      },
+    },
+  };
+};

docs/config.d.ts

@@ -0,0 +1,7 @@
+export const LANGUAGES: string[];
+
+export const LANGUAGES_SSR: string[];
+
+export const LANGUAGES_IN_PROGRESS: string[];
+
+export const LANGUAGES_IGNORE_PAGES: (pathname: string) => boolean;

docs/data/toolpad/core/components/app-provider/app-provider.md

@@ -0,0 +1,9 @@
+---
+productId: toolpad-core
+title: App Provider
+components: AppProvider
+---
+
+# App Provider
+
+<p class="description">The app provider component provides the necessary context for a Toolpad application.</p>

docs/data/toolpad/core/components/dashboard-layout/DashboardLayoutBasic.js

@@ -0,0 +1,70 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Typography from '@mui/material/Typography';
+import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
+import BarChartIcon from '@mui/icons-material/BarChart';
+import DescriptionIcon from '@mui/icons-material/Description';
+import LayersIcon from '@mui/icons-material/Layers';
+import { AppProvider } from '@toolpad/core/AppProvider';
+import { DashboardLayout } from '@toolpad/core/DashboardLayout';
+import theme from '../theme';
+
+const NAVIGATION = [
+  {
+    kind: 'header',
+    title: 'Main items',
+  },
+  {
+    title: 'Dashboard',
+    icon: <DashboardIcon />,
+  },
+  {
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
+  {
+    kind: 'divider',
+  },
+  {
+    kind: 'header',
+    title: 'Analytics',
+  },
+  {
+    title: 'Reports',
+    icon: <BarChartIcon />,
+    children: [
+      {
+        title: 'Sales',
+        icon: <DescriptionIcon />,
+      },
+      {
+        title: 'Traffic',
+        icon: <DescriptionIcon />,
+      },
+    ],
+  },
+  {
+    title: 'Integrations',
+    icon: <LayersIcon />,
+  },
+];
+
+export default function DashboardLayoutBasic() {
+  return (
+    <AppProvider theme={theme} navigation={NAVIGATION}>
+      <DashboardLayout>
+        <Box
+          sx={{
+            py: 4,
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+          }}
+        >
+          <Typography>Dashboard content goes here.</Typography>
+        </Box>
+      </DashboardLayout>
+    </AppProvider>
+  );
+}