@mui/internal-docs-infra 0.1.1-canary.9 → 0.2.0-alpha.2

package/esm/createDemoData/createDemoData.d.ts

@@ -0,0 +1,44 @@
+import { CreateDemoDataMeta, DemoData, DemoGlobalData, DemoGlobalProvider } from "./types.js";
+/**
+ * Creates demo data for displaying code examples with syntax highlighting.
+ * A variant is a different implementation style of the same component.
+ * Returns a data object containing demo metadata and components instead of a complete demo component.
+ * Note: It is recommended to use abstractCreateDemo to create a complete demo component rather than just demo data.
+ * @param url Depends on `import.meta.url` to determine the source file location.
+ * @param variants The variants of the component to be rendered in the demo.
+ * @param meta Additional meta for the demo.
+ */
+export declare function createDemoDataWithVariants<T extends React.ComponentType<any> = React.ComponentType>(url: string, variants: {
+  Default: T;
+} | {
+  [key: string]: T;
+}, meta?: CreateDemoDataMeta): DemoData<T>;
+/**
+ * Creates demo data for displaying code examples with syntax highlighting.
+ * Returns a data object containing demo metadata and components instead of a complete demo component.
+ * Note: It is recommended to use abstractCreateDemo to create a complete demo component rather than just demo data.
+ * @param url Depends on `import.meta.url` to determine the source file location.
+ * @param component The component to be rendered in the demo.
+ * @param meta Additional meta for the demo.
+ */
+export declare function createDemoData<T extends React.ComponentType<any> = React.ComponentType>(url: string, component: T, meta?: CreateDemoDataMeta): DemoData<T>;
+/**
+ * Creates a demo data object for a global provider component with different variants.
+ *
+ * @param url The URL of the demo file.
+ * @param globalProviders The variants of the global provider to be rendered in the demo.
+ * @param meta Additional metadata for the demo data.
+ * @returns Demo data object.
+ */
+export declare function createDemoGlobalWithVariants(url: string, globalProviders: {
+  [variant: string]: DemoGlobalProvider;
+}, meta?: CreateDemoDataMeta): DemoGlobalData;
+/**
+ * Creates a demo data object for a global provider component.
+ *
+ * @param url The URL of the demo file.
+ * @param globalProvider The global provider to be rendered in the demo.
+ * @param meta Additional metadata for the demo data.
+ * @returns Demo data object.
+ */
+export declare function createDemoGlobal(url: string, globalProvider: DemoGlobalProvider, meta?: CreateDemoDataMeta): DemoGlobalData;

package/esm/createDemoData/createDemoData.js

@@ -0,0 +1,74 @@
+import { extractNameAndSlugFromUrl } from "../pipeline/loaderUtils/index.js";
+/**
+ * Creates demo data for displaying code examples with syntax highlighting.
+ * A variant is a different implementation style of the same component.
+ * Returns a data object containing demo metadata and components instead of a complete demo component.
+ * Note: It is recommended to use abstractCreateDemo to create a complete demo component rather than just demo data.
+ * @param url Depends on `import.meta.url` to determine the source file location.
+ * @param variants The variants of the component to be rendered in the demo.
+ * @param meta Additional meta for the demo.
+ */
+export function createDemoDataWithVariants(url, variants, meta) {
+  var _meta$name, _meta$slug;
+  if (!url.startsWith('file:')) {
+    throw new Error('createDemoData() requires the `url` argument to be a file URL. Use `import.meta.url` to get the current file URL.');
+  }
+  if (!meta || !meta.precompute && !meta.skipPrecompute) {
+    throw new Error("createDemoData() was unable to precompute the code in ".concat(url, ". Ensure the createDemoData() function is called within a path used for demo indexes. This is typically app/**/demos/*/index.ts but may be overridden in next.config.js"));
+  }
+  var precompute = meta.precompute;
+
+  // Generate name and slug from URL if not provided in meta
+  var generatedMeta = extractNameAndSlugFromUrl(url);
+  var name = (_meta$name = meta.name) != null ? _meta$name : generatedMeta.name;
+  var slug = (_meta$slug = meta.slug) != null ? _meta$slug : generatedMeta.slug;
+  var displayName = (meta == null ? void 0 : meta.displayName) || "".concat(name.replace(/ /g, ''), "Demo");
+  return {
+    name: name,
+    slug: slug,
+    displayName: displayName,
+    precompute: precompute,
+    url: url,
+    components: variants
+  };
+}
+
+/**
+ * Creates demo data for displaying code examples with syntax highlighting.
+ * Returns a data object containing demo metadata and components instead of a complete demo component.
+ * Note: It is recommended to use abstractCreateDemo to create a complete demo component rather than just demo data.
+ * @param url Depends on `import.meta.url` to determine the source file location.
+ * @param component The component to be rendered in the demo.
+ * @param meta Additional meta for the demo.
+ */
+export function createDemoData(url, component, meta) {
+  return createDemoDataWithVariants(url, {
+    Default: component
+  }, meta);
+}
+
+/**
+ * Creates a demo data object for a global provider component with different variants.
+ *
+ * @param url The URL of the demo file.
+ * @param globalProviders The variants of the global provider to be rendered in the demo.
+ * @param meta Additional metadata for the demo data.
+ * @returns Demo data object.
+ */
+export function createDemoGlobalWithVariants(url, globalProviders, meta) {
+  return createDemoDataWithVariants(url, globalProviders, meta);
+}
+
+/**
+ * Creates a demo data object for a global provider component.
+ *
+ * @param url The URL of the demo file.
+ * @param globalProvider The global provider to be rendered in the demo.
+ * @param meta Additional metadata for the demo data.
+ * @returns Demo data object.
+ */
+export function createDemoGlobal(url, globalProvider, meta) {
+  return createDemoGlobalWithVariants(url, {
+    Default: globalProvider
+  }, meta);
+}

package/esm/createDemoData/index.d.ts

@@ -0,0 +1 @@
+export * from "./createDemoData.js";

package/esm/createDemoData/index.js

@@ -0,0 +1 @@
+export * from "./createDemoData.js";

package/esm/createDemoData/types.d.ts

@@ -0,0 +1,25 @@
+import type { Code } from "../CodeHighlighter/types.js";
+export type CreateDemoDataMeta = {
+  name?: string;
+  slug?: string;
+  displayName?: string;
+  skipPrecompute?: boolean;
+  precompute?: Code;
+  client?: React.ComponentType<{
+    children: React.ReactNode;
+  }>;
+};
+export type DemoData<T extends React.ComponentType<any> = React.ComponentType> = {
+  name: string;
+  slug: string;
+  displayName: string;
+  precompute: Code | undefined;
+  url: string;
+  components: {
+    [key: string]: T;
+  };
+};
+export type DemoGlobalProvider = React.ComponentType<{
+  children: React.ReactNode;
+}>;
+export type DemoGlobalData = DemoData<DemoGlobalProvider>;

package/esm/createDemoData/types.js

@@ -0,0 +1 @@
+export {};

package/esm/pipeline/hastUtils/hastUtils.d.ts

@@ -0,0 +1,11 @@
+import type { Nodes as HastNodes } from 'hast';
+export declare function hastToJsx(hast: HastNodes): React.ReactNode;
+export declare function hastOrJsonToJsx(hastOrJson: HastNodes | {
+  hastJson: string;
+}): React.ReactNode;
+export declare function stringOrHastToString(source: string | HastNodes | {
+  hastJson: string;
+}): string;
+export declare function stringOrHastToJsx(source: string | HastNodes | {
+  hastJson: string;
+}, highlighted?: boolean): React.ReactNode;

package/esm/pipeline/hastUtils/hastUtils.js

@@ -0,0 +1,67 @@
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
+import { toText } from 'hast-util-to-text';
+import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
+export function hastToJsx(hast) {
+  return toJsxRuntime(hast, {
+    Fragment: Fragment,
+    jsx: jsx,
+    jsxs: jsxs
+  });
+}
+export function hastOrJsonToJsx(hastOrJson) {
+  var hast;
+  if ('hastJson' in hastOrJson) {
+    try {
+      hast = JSON.parse(hastOrJson.hastJson);
+    } catch (error) {
+      throw new Error("Failed to parse hastJson: ".concat(JSON.stringify(error)));
+    }
+  } else {
+    hast = hastOrJson;
+  }
+  return toJsxRuntime(hast, {
+    Fragment: Fragment,
+    jsx: jsx,
+    jsxs: jsxs
+  });
+}
+export function stringOrHastToString(source) {
+  if (typeof source === 'string') {
+    return source;
+  }
+  var hast;
+  if ('hastJson' in source) {
+    try {
+      hast = JSON.parse(source.hastJson);
+    } catch (error) {
+      throw new Error("Failed to parse hastJson: ".concat(JSON.stringify(error)));
+    }
+  } else {
+    hast = source;
+  }
+  return toText(hast, {
+    whitespace: 'pre'
+  });
+}
+export function stringOrHastToJsx(source, highlighted) {
+  if (typeof source === 'string') {
+    return source;
+  }
+  var hast;
+  if ('hastJson' in source) {
+    try {
+      hast = JSON.parse(source.hastJson);
+    } catch (error) {
+      throw new Error("Failed to parse hastJson: ".concat(JSON.stringify(error)));
+    }
+  } else {
+    hast = source;
+  }
+  if (highlighted && _typeof(hast) === 'object') {
+    return hastToJsx(hast);
+  }
+  return toText(hast, {
+    whitespace: 'pre'
+  });
+}

package/esm/pipeline/hastUtils/index.d.ts

@@ -0,0 +1 @@
+export * from "./hastUtils.js";

package/esm/pipeline/hastUtils/index.js

@@ -0,0 +1 @@
+export * from "./hastUtils.js";

package/esm/pipeline/loadPrecomputedCodeHighlighter/index.d.ts

@@ -0,0 +1,2 @@
+import { loadPrecomputedCodeHighlighter } from "./loadPrecomputedCodeHighlighter.js";
+export default loadPrecomputedCodeHighlighter;

package/esm/pipeline/loadPrecomputedCodeHighlighter/index.js

@@ -0,0 +1,4 @@
+// This is export format a Webpack / Turbopack loader expects
+
+import { loadPrecomputedCodeHighlighter } from "./loadPrecomputedCodeHighlighter.js";
+export default loadPrecomputedCodeHighlighter;

package/esm/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.d.ts

@@ -0,0 +1,14 @@
+import type { LoaderContext } from 'webpack';
+export type LoaderOptions = {};
+/**
+ * Webpack loader that processes demo files and precomputes variant data.
+ *
+ * Finds createDemo calls, loads and processes all variants with syntax highlighting
+ * and TypeScript transformation, then injects the precomputed data back into the source.
+ *
+ * Supports single component syntax: createDemo(import.meta.url, Component)
+ * And object syntax: createDemo(import.meta.url, { Component1, Component2 })
+ *
+ * Automatically skips processing if skipPrecompute: true is set.
+ */
+export declare function loadPrecomputedCodeHighlighter(this: LoaderContext<LoaderOptions>, source: string): Promise<void>;

package/esm/pipeline/loadPrecomputedCodeHighlighter/loadPrecomputedCodeHighlighter.js

@@ -0,0 +1,178 @@
+import _createForOfIteratorHelper from "@babel/runtime/helpers/esm/createForOfIteratorHelper";
+import _regenerator from "@babel/runtime/helpers/esm/regenerator";
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _asyncToGenerator from "@babel/runtime/helpers/esm/asyncToGenerator";
+import { loadVariant } from "../../CodeHighlighter/loadVariant.js";
+import { createParseSource } from "../parseSource/index.js";
+// TODO: re-enable following benchmarking
+// import { TypescriptToJavascriptTransformer } from '../transformTypescriptToJavascript';
+
+import { parseCreateFactoryCall } from "./parseCreateFactoryCall.js";
+import { resolveVariantPathsWithFs } from "../loaderUtils/resolveModulePathWithFs.js";
+import { replacePrecomputeValue } from "./replacePrecomputeValue.js";
+import { createLoadServerSource } from "../loadServerSource/index.js";
+import { getFileNameFromUrl } from "../loaderUtils/index.js";
+/**
+ * Webpack loader that processes demo files and precomputes variant data.
+ *
+ * Finds createDemo calls, loads and processes all variants with syntax highlighting
+ * and TypeScript transformation, then injects the precomputed data back into the source.
+ *
+ * Supports single component syntax: createDemo(import.meta.url, Component)
+ * And object syntax: createDemo(import.meta.url, { Component1, Component2 })
+ *
+ * Automatically skips processing if skipPrecompute: true is set.
+ */
+export function loadPrecomputedCodeHighlighter(_x) {
+  return _loadPrecomputedCodeHighlighter.apply(this, arguments);
+}
+function _loadPrecomputedCodeHighlighter() {
+  _loadPrecomputedCodeHighlighter = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2(source) {
+    var _this = this;
+    var callback, demoCall, variantData, allDependencies, resolvedVariantMap, loadSource, sourceTransformers, sourceParser, variantPromises, variantResults, _iterator, _step, result, modifiedSource, _t2;
+    return _regenerator().w(function (_context2) {
+      while (1) switch (_context2.p = _context2.n) {
+        case 0:
+          callback = this.async();
+          this.cacheable();
+          _context2.p = 1;
+          _context2.n = 2;
+          return parseCreateFactoryCall(source, this.resourcePath);
+        case 2:
+          demoCall = _context2.v;
+          if (demoCall) {
+            _context2.n = 3;
+            break;
+          }
+          callback(null, source);
+          return _context2.a(2);
+        case 3:
+          if (!demoCall.options.skipPrecompute) {
+            _context2.n = 4;
+            break;
+          }
+          callback(null, source);
+          return _context2.a(2);
+        case 4:
+          // Load variant data for all variants
+          variantData = {};
+          allDependencies = []; // Resolve all variant entry point paths using resolveVariantPathsWithFs
+          _context2.n = 5;
+          return resolveVariantPathsWithFs(demoCall.variants || {});
+        case 5:
+          resolvedVariantMap = _context2.v;
+          // Create loader functions
+          loadSource = createLoadServerSource({
+            includeDependencies: true,
+            storeAt: 'flat' // TODO: this should be configurable
+          }); // Setup source transformers for TypeScript to JavaScript conversion
+          // const sourceTransformers: SourceTransformers = [TypescriptToJavascriptTransformer];
+          // TODO: maybe we should have `loadPrecomputedCodeHighlighterWithJsToTs`
+          sourceTransformers = []; // Create sourceParser promise for syntax highlighting
+          sourceParser = createParseSource(); // Process variants in parallel
+          variantPromises = Array.from(resolvedVariantMap.entries()).map(/*#__PURE__*/function () {
+            var _ref2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(_ref) {
+              var _demoCall$namedExport;
+              var _ref3, variantName, fileUrl, namedExport, variant, _getFileNameFromUrl, fileName, _yield$loadVariant, processedVariant, dependencies, _t;
+              return _regenerator().w(function (_context) {
+                while (1) switch (_context.p = _context.n) {
+                  case 0:
+                    _ref3 = _slicedToArray(_ref, 2), variantName = _ref3[0], fileUrl = _ref3[1];
+                    namedExport = (_demoCall$namedExport = demoCall.namedExports) == null ? void 0 : _demoCall$namedExport[variantName];
+                    variant = fileUrl;
+                    if (!namedExport) {
+                      _context.n = 2;
+                      break;
+                    }
+                    _getFileNameFromUrl = getFileNameFromUrl(variant), fileName = _getFileNameFromUrl.fileName;
+                    if (fileName) {
+                      _context.n = 1;
+                      break;
+                    }
+                    throw new Error("Cannot determine fileName from URL \"".concat(variant, "\" for variant \"").concat(variantName, "\". ") + "Please ensure the URL has a valid file extension.");
+                  case 1:
+                    variant = {
+                      url: fileUrl,
+                      fileName: fileName,
+                      namedExport: namedExport
+                    };
+                  case 2:
+                    _context.p = 2;
+                    _context.n = 3;
+                    return loadVariant(fileUrl,
+                    // URL for the variant entry point (already includes file://)
+                    variantName, variant, {
+                      sourceParser: sourceParser,
+                      // For syntax highlighting
+                      loadSource: loadSource,
+                      // For loading source files and dependencies
+                      loadVariantMeta: undefined,
+                      sourceTransformers: sourceTransformers,
+                      // For TypeScript to JavaScript conversion
+                      maxDepth: 5
+                    });
+                  case 3:
+                    _yield$loadVariant = _context.v;
+                    processedVariant = _yield$loadVariant.code;
+                    dependencies = _yield$loadVariant.dependencies;
+                    return _context.a(2, {
+                      variantName: variantName,
+                      variantData: processedVariant,
+                      // processedVariant is a complete VariantCode
+                      dependencies: dependencies // All files that were loaded
+                    });
+                  case 4:
+                    _context.p = 4;
+                    _t = _context.v;
+                    throw new Error("Failed to load variant ".concat(variantName, " from ").concat(fileUrl, ": ").concat(_t));
+                  case 5:
+                    return _context.a(2);
+                }
+              }, _callee, null, [[2, 4]]);
+            }));
+            return function (_x2) {
+              return _ref2.apply(this, arguments);
+            };
+          }());
+          _context2.n = 6;
+          return Promise.all(variantPromises);
+        case 6:
+          variantResults = _context2.v;
+          // Process results and collect dependencies
+          _iterator = _createForOfIteratorHelper(variantResults);
+          try {
+            for (_iterator.s(); !(_step = _iterator.n()).done;) {
+              result = _step.value;
+              if (result) {
+                variantData[result.variantName] = result.variantData;
+                result.dependencies.forEach(function (file) {
+                  allDependencies.push(file);
+                });
+              }
+            }
+
+            // Replace the factory function call with the actual precomputed data
+          } catch (err) {
+            _iterator.e(err);
+          } finally {
+            _iterator.f();
+          }
+          modifiedSource = replacePrecomputeValue(source, variantData, demoCall); // Add all dependencies to webpack's watch list
+          allDependencies.forEach(function (dep) {
+            // Strip 'file://' prefix if present before adding to webpack's dependency tracking
+            _this.addDependency(dep.startsWith('file://') ? dep.slice(7) : dep);
+          });
+          callback(null, modifiedSource);
+          _context2.n = 8;
+          break;
+        case 7:
+          _context2.p = 7;
+          _t2 = _context2.v;
+          callback(_t2 instanceof Error ? _t2 : new Error(String(_t2)));
+        case 8:
+          return _context2.a(2);
+      }
+    }, _callee2, this, [[1, 7]]);
+  }));
+  return _loadPrecomputedCodeHighlighter.apply(this, arguments);
+}

package/esm/pipeline/loadPrecomputedCodeHighlighter/parseCreateFactoryCall.d.ts

@@ -0,0 +1,47 @@
+import { type ParseImportsResult } from "../loaderUtils/index.js";
+import { type SplitArguments } from "./parseFunctionArguments.js";
+import type { Externals } from "../../CodeHighlighter/types.js";
+/**
+ * Parse options for create* factory call parsing
+ */
+export interface ParseOptions {
+  metadataOnly?: boolean;
+  allowExternalVariants?: boolean;
+  allowMultipleFactories?: boolean;
+}
+export interface FactoryOptions {
+  name?: string;
+  slug?: string;
+  skipPrecompute?: boolean;
+  precompute?: any;
+}
+export interface ParsedCreateFactory {
+  functionName: string;
+  url: string;
+  variants: Record<string, string> | undefined;
+  namedExports: Record<string, string | undefined> | undefined;
+  options: FactoryOptions;
+  fullMatch: string;
+  hasOptions: boolean;
+  externals: Externals;
+  argumentsStartIndex: number;
+  argumentsEndIndex: number;
+  structuredUrl: string;
+  structuredVariants: string | SplitArguments | Record<string, string> | undefined;
+  structuredOptions?: Record<string, any>;
+  remaining?: string;
+  parseImportsResult?: ParseImportsResult;
+}
+/**
+ * Parses a file to extract a single create* factory call and its variants and options
+ * Returns the parsed result with remaining content included
+ * Returns null if no create* call is found
+ */
+export declare function parseCreateFactoryCall(code: string, filePath: string, parseOptions?: ParseOptions, parseImportsResult?: ParseImportsResult): Promise<(ParsedCreateFactory & {
+  parseImportsResult?: ParseImportsResult;
+}) | null>;
+/**
+ * Parses all create* factory calls in a file sequentially
+ * Returns a record of export names mapped to their parsed factory calls
+ */
+export declare function parseAllCreateFactoryCalls(code: string, filePath: string, parseOptions?: Omit<ParseOptions, 'allowMultipleFactories'>): Promise<Record<string, ParsedCreateFactory>>;