@mui/internal-docs-infra 0.1.0 → 0.1.1-alpha.0

package/build/CodeHighlighter/transformSource.d.ts

@@ -0,0 +1,2 @@
+import type { VariantSource, SourceTransformers, Transforms } from "./types.js";
+export declare function transformSource(source: VariantSource, fileName: string, sourceTransformers: SourceTransformers): Promise<Transforms | undefined>;

package/build/CodeHighlighter/transformSource.js

@@ -0,0 +1,114 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault")["default"];
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.transformSource = transformSource;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var _regeneratorRuntime2 = _interopRequireDefault(require("@babel/runtime/helpers/regeneratorRuntime"));
+var _asyncToGenerator2 = _interopRequireDefault(require("@babel/runtime/helpers/asyncToGenerator"));
+var _jsondiffpatch = require("jsondiffpatch");
+var _hastUtilToText = require("hast-util-to-text");
+var differ = (0, _jsondiffpatch.create)({
+  omitRemovedValues: true,
+  cloneDiffValues: true
+});
+function transformSource(_x, _x2, _x3) {
+  return _transformSource.apply(this, arguments);
+}
+function _transformSource() {
+  _transformSource = (0, _asyncToGenerator2["default"])(/*#__PURE__*/(0, _regeneratorRuntime2["default"])().mark(function _callee2(source, fileName, sourceTransformers) {
+    var transforms;
+    return (0, _regeneratorRuntime2["default"])().wrap(function _callee2$(_context2) {
+      while (1) switch (_context2.prev = _context2.next) {
+        case 0:
+          _context2.next = 2;
+          return Promise.all(sourceTransformers.map(/*#__PURE__*/function () {
+            var _ref2 = (0, _asyncToGenerator2["default"])(/*#__PURE__*/(0, _regeneratorRuntime2["default"])().mark(function _callee(_ref) {
+              var extensions, transformer, sourceString, transformed, splitSource;
+              return (0, _regeneratorRuntime2["default"])().wrap(function _callee$(_context) {
+                while (1) switch (_context.prev = _context.next) {
+                  case 0:
+                    extensions = _ref.extensions, transformer = _ref.transformer;
+                    if (extensions.some(function (ext) {
+                      return fileName.endsWith(".".concat(ext));
+                    })) {
+                      _context.next = 3;
+                      break;
+                    }
+                    return _context.abrupt("return", undefined);
+                  case 3:
+                    _context.prev = 3;
+                    if (typeof source === 'string') {
+                      sourceString = source;
+                    } else if ('hastJson' in source) {
+                      sourceString = (0, _hastUtilToText.toText)(JSON.parse(source.hastJson));
+                    } else {
+                      sourceString = (0, _hastUtilToText.toText)(source);
+                    }
+                    _context.next = 7;
+                    return transformer(sourceString, fileName);
+                  case 7:
+                    transformed = _context.sent;
+                    if (!transformed) {
+                      _context.next = 11;
+                      break;
+                    }
+                    splitSource = sourceString.split('\n');
+                    return _context.abrupt("return", Object.keys(transformed).reduce(function (acc, key) {
+                      var delta = differ.diff(splitSource, transformed[key].source.split('\n'));
+                      acc[key] = {
+                        delta: delta,
+                        fileName: transformed[key].fileName
+                      };
+                      return acc;
+                    }, {}));
+                  case 11:
+                    return _context.abrupt("return", undefined);
+                  case 14:
+                    _context.prev = 14;
+                    _context.t0 = _context["catch"](3);
+                    throw new Error("Failed to transform source code (file: ".concat(fileName, "): ").concat(_context.t0 instanceof Error && _context.t0.message));
+                  case 17:
+                  case "end":
+                    return _context.stop();
+                }
+              }, _callee, null, [[3, 14]]);
+            }));
+            return function (_x4) {
+              return _ref2.apply(this, arguments);
+            };
+          }()));
+        case 2:
+          transforms = _context2.sent;
+          if (!(transforms.length === 0 || transforms.every(function (t) {
+            return t === undefined;
+          }))) {
+            _context2.next = 5;
+            break;
+          }
+          return _context2.abrupt("return", undefined);
+        case 5:
+          return _context2.abrupt("return", transforms.reduce(function (acc, transform) {
+            if (transform) {
+              Object.entries(transform).forEach(function (_ref3) {
+                var _ref4 = (0, _slicedToArray2["default"])(_ref3, 2),
+                  key = _ref4[0],
+                  value = _ref4[1];
+                if (acc[key]) {
+                  throw new Error("Duplicate key found in source transformations: ".concat(key));
+                }
+                acc[key] = value;
+              });
+            }
+            return acc;
+          }, {}));
+        case 6:
+        case "end":
+          return _context2.stop();
+      }
+    }, _callee2);
+  }));
+  return _transformSource.apply(this, arguments);
+}

package/build/CodeHighlighter/types.d.ts

@@ -0,0 +1,138 @@
+import type { Nodes as HastNodes } from 'hast';
+import type { Delta } from 'jsondiffpatch';
+export type Components = {
+  [key: string]: React.ReactNode;
+};
+type CodeMeta = {
+  fileName: string;
+};
+export type Transforms = Record<string, {
+  delta: Delta;
+  fileName?: string;
+}>;
+export type VariantSource = string | HastNodes | {
+  hastJson: string;
+};
+export type VariantExtraFiles = {
+  [fileName: string]: string | {
+    source?: VariantSource;
+    transforms?: Transforms;
+  };
+};
+export type VariantCode = CodeMeta & {
+  url: string;
+  source?: VariantSource;
+  extraFiles?: VariantExtraFiles;
+  filesOrder?: string[];
+  transforms?: Transforms;
+  allFilesListed?: boolean;
+};
+export type Code = {
+  [key: string]: undefined | string | VariantCode;
+};
+export type ControlledVariantExtraFiles = {
+  [fileName: string]: {
+    source: string | null;
+  };
+};
+export type ControlledVariantCode = CodeMeta & {
+  url: string;
+  source?: string | null;
+  extraFiles?: ControlledVariantExtraFiles;
+  filesOrder?: string[];
+};
+export type ControlledCode = {
+  [key: string]: undefined | null | ControlledVariantCode;
+};
+type Options = {
+  name?: string;
+  slug?: string;
+  description?: string;
+};
+export type ContentProps = {
+  code?: Code;
+  components?: Components;
+} & Options;
+export type ContentLoadingVariant = {
+  fileNames?: string[];
+  source?: React.ReactNode;
+  extraSource?: {
+    [fileName: string]: React.ReactNode;
+  };
+};
+export type ContentLoadingProps = ContentLoadingVariant & {
+  extraVariants?: Record<string, ContentLoadingVariant>;
+} & Options;
+type ErrorHandler = React.ComponentType<{
+  error: Error;
+}>;
+interface CodeHighlighterBaseProps extends Options {
+  code?: Code;
+  components?: Components;
+  variants?: string[];
+  variant?: string;
+  fileName?: string;
+  initialVariant?: string;
+  defaultVariant?: string;
+  precompute?: boolean | Code;
+  fallbackUsesExtraFiles?: boolean;
+  fallbackUsesAllVariants?: boolean;
+  url: string;
+  controlled?: boolean;
+}
+export interface CodeHighlighterClientProps extends CodeHighlighterBaseProps {
+  children: React.ReactNode;
+  errorHandler?: React.ReactNode;
+  fallback?: React.ReactNode;
+  skipFallback?: boolean;
+  /**
+   * @default 'hydration'
+   */
+  highlightAt?: 'init' | 'hydration' | 'idle';
+}
+export type LoadCodeMeta = (url: string) => Promise<Code>;
+export type LoadVariantMeta = (variantName: string, url: string) => Promise<VariantCode>;
+export type LoadSource = (url: string) => Promise<{
+  source: string;
+  extraFiles?: VariantExtraFiles;
+  extraDependencies?: string[];
+}>;
+export type TransformSource = (source: string, fileName: string) => Promise<Record<string, {
+  source: string;
+  fileName?: string;
+}> | undefined>;
+export type ParseSource = (source: string, fileName: string) => HastNodes;
+export type SourceTransformer = {
+  extensions: string[];
+  transformer: TransformSource;
+};
+export type SourceTransformers = Array<SourceTransformer>;
+/**
+ * Options for controlling file loading behavior
+ */
+export interface LoadFileOptions {
+  /** Disable applying source transformers */
+  disableTransforms?: boolean;
+  /** Disable parsing source strings to AST */
+  disableParsing?: boolean;
+  /** Maximum recursion depth for loading nested extra files */
+  maxDepth?: number;
+  /** Set of already loaded file URLs to prevent circular dependencies */
+  loadedFiles?: Set<string>;
+}
+export interface CodeHighlighterProps extends CodeHighlighterBaseProps {
+  Content: React.ComponentType<ContentProps>;
+  ErrorHandler?: ErrorHandler;
+  ContentLoading?: React.ComponentType<ContentLoadingProps>;
+  /**
+   * @default 'stream'
+   */
+  highlightAt?: 'init' | 'stream' | 'hydration' | 'idle';
+  forceClient?: boolean;
+  loadCodeMeta?: LoadCodeMeta;
+  loadVariantMeta?: LoadVariantMeta;
+  loadSource?: LoadSource;
+  sourceTransformers?: SourceTransformers;
+  sourceParser?: Promise<ParseSource>;
+}
+export {};

package/build/CodeHighlighter/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/build/CodeProvider/CodeContext.d.ts

@@ -0,0 +1,12 @@
+import * as React from 'react';
+import type { LoadCodeMeta, LoadSource, LoadVariantMeta, ParseSource, SourceTransformers } from "../CodeHighlighter/index.js";
+export interface CodeContext {
+  sourceParser?: Promise<ParseSource>;
+  parseSource?: ParseSource;
+  sourceTransformers?: SourceTransformers;
+  loadSource?: LoadSource;
+  loadVariantMeta?: LoadVariantMeta;
+  loadCodeMeta?: LoadCodeMeta;
+}
+export declare const CodeContext: React.Context<CodeContext>;
+export declare const useCodeContext: () => CodeContext;

package/build/CodeProvider/CodeContext.js

@@ -0,0 +1,14 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard")["default"];
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useCodeContext = exports.CodeContext = void 0;
+var React = _interopRequireWildcard(require("react"));
+var CodeContext = exports.CodeContext = /*#__PURE__*/React.createContext({});
+var useCodeContext = exports.useCodeContext = function useCodeContext() {
+  var context = React.useContext(CodeContext);
+  return context;
+};

package/build/CodeProvider/CodeProvider.d.ts

@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { LoadCodeMeta, LoadSource, LoadVariantMeta } from "../CodeHighlighter/index.js";
+export declare function CodeProvider({
+  children,
+  loadCodeMeta,
+  loadVariantMeta,
+  loadSource
+}: {
+  children: React.ReactNode;
+  loadCodeMeta?: LoadCodeMeta;
+  loadVariantMeta?: LoadVariantMeta;
+  loadSource?: LoadSource;
+}): import("react/jsx-runtime").JSX.Element;

package/build/CodeProvider/CodeProvider.js

@@ -0,0 +1,57 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard")["default"];
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault")["default"];
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CodeProvider = CodeProvider;
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime/helpers/slicedToArray"));
+var React = _interopRequireWildcard(require("react"));
+var _starryNight = require("@wooorm/starry-night");
+var _CodeContext = require("./CodeContext");
+var _grammars = require("../parseSource/grammars");
+var _jsxRuntime = require("react/jsx-runtime");
+function CodeProvider(_ref) {
+  var children = _ref.children,
+    loadCodeMeta = _ref.loadCodeMeta,
+    loadVariantMeta = _ref.loadVariantMeta,
+    loadSource = _ref.loadSource;
+  var _React$useState = React.useState(undefined),
+    _React$useState2 = (0, _slicedToArray2["default"])(_React$useState, 2),
+    parseSource = _React$useState2[0],
+    setParseSource = _React$useState2[1];
+  var sourceParser = React.useMemo(function () {
+    // Only initialize Starry Night in the browser, not during SSR
+    if (typeof window === 'undefined') {
+      return Promise.resolve(function () {
+        throw new Error('parseSource not available during SSR');
+      });
+    }
+    return (0, _starryNight.createStarryNight)(_grammars.grammars).then(function (starryNight) {
+      var parseSourceFn = function parseSourceFn(source, fileName) {
+        var fileType = fileName.slice(fileName.lastIndexOf('.')) || 'plaintext';
+        return starryNight.highlight(source, _grammars.extensionMap[fileType] || 'plaintext');
+      };
+
+      // Update the sync version when available
+      setParseSource(parseSourceFn);
+      return parseSourceFn;
+    });
+  }, []);
+  var context = React.useMemo(function () {
+    return {
+      sourceParser: sourceParser,
+      parseSource: parseSource,
+      // Sync version when available
+      loadSource: loadSource,
+      loadVariantMeta: loadVariantMeta,
+      loadCodeMeta: loadCodeMeta
+    };
+  }, [sourceParser, parseSource, loadSource, loadVariantMeta, loadCodeMeta]);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_CodeContext.CodeContext.Provider, {
+    value: context,
+    children: children
+  });
+}

package/build/CodeProvider/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./CodeProvider.js";
+export * from "./CodeContext.js";

package/build/CodeProvider/index.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _CodeProvider = require("./CodeProvider");
+Object.keys(_CodeProvider).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _CodeProvider[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _CodeProvider[key];
+    }
+  });
+});
+var _CodeContext = require("./CodeContext");
+Object.keys(_CodeContext).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _CodeContext[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _CodeContext[key];
+    }
+  });
+});

package/build/README.md

@@ -0,0 +1,19 @@
+# @mui/internal-docs-infra
+
+This package hosts the tools that help create the documentation.
+
+## Installation
+
+Install the package in your project directory with:
+
+<!-- #npm-tag-reference -->
+
+```bash
+npm install @mui/internal-docs-infra
+```
+
+## Documentation
+
+This is stored in the `docs` directory.
+
+[Read More](./docs/README.md)

package/build/esm/CodeControllerContext/CodeControllerContext.d.ts

@@ -0,0 +1,22 @@
+import * as React from 'react';
+import { ControlledCode } from "../CodeHighlighter/types.js";
+export type Selection = {
+  variant: string;
+  fileName?: string;
+  transformKey?: string;
+};
+export interface CodeControllerContext {
+  code?: ControlledCode;
+  selection?: Selection;
+  setCode?: React.Dispatch<React.SetStateAction<ControlledCode | undefined>>;
+  setSelection?: React.Dispatch<React.SetStateAction<Selection>>;
+  components?: Record<string, React.ReactNode> | undefined;
+}
+export declare const CodeControllerContext: React.Context<CodeControllerContext | undefined>;
+export declare function useControlledCode(): {
+  controlledCode: ControlledCode | undefined;
+  controlledSelection: Selection | undefined;
+  controlledSetCode: React.Dispatch<React.SetStateAction<ControlledCode | undefined>> | undefined;
+  controlledSetSelection: React.Dispatch<React.SetStateAction<Selection>> | undefined;
+  controlledComponents: Record<string, React.ReactNode> | undefined;
+};

package/build/esm/CodeControllerContext/CodeControllerContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeControllerContext.d.ts","sourceRoot":"","sources":["../../../src/CodeControllerContext/CodeControllerContext.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE1D,MAAM,MAAM,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtF,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,OAAO,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3E,YAAY,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;CAC1D;AAED,eAAO,MAAM,qBAAqB,kDAEjC,CAAC;AAEF,wBAAgB,iBAAiB;;;;;;EAShC"}

package/build/esm/CodeControllerContext/CodeControllerContext.js

@@ -0,0 +1,14 @@
+'use client';
+
+import * as React from 'react';
+export var CodeControllerContext = /*#__PURE__*/React.createContext(undefined);
+export function useControlledCode() {
+  var context = React.useContext(CodeControllerContext);
+  return {
+    controlledCode: context == null ? void 0 : context.code,
+    controlledSelection: context == null ? void 0 : context.selection,
+    controlledSetCode: context == null ? void 0 : context.setCode,
+    controlledSetSelection: context == null ? void 0 : context.setSelection,
+    controlledComponents: context == null ? void 0 : context.components
+  };
+}

package/build/esm/CodeControllerContext/index.d.ts

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

package/build/esm/CodeControllerContext/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/CodeControllerContext/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC"}

package/build/esm/CodeControllerContext/index.js

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

package/build/esm/CodeHighlighter/CodeHighlighter.d.ts

@@ -0,0 +1,2 @@
+import type { CodeHighlighterProps } from "./types.js";
+export declare function CodeHighlighter(props: CodeHighlighterProps): import("react/jsx-runtime").JSX.Element;

package/build/esm/CodeHighlighter/CodeHighlighter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeHighlighter.d.ts","sourceRoot":"","sources":["../../../src/CodeHighlighter/CodeHighlighter.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,oBAAoB,EAIrB,MAAM,SAAS,CAAC;AAkRjB,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,2CA4F1D"}