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

package/esm/useCode/useTransformManagement.js

@@ -0,0 +1,72 @@
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import * as React from 'react';
+import { getAvailableTransforms, createTransformedFiles } from "./useCodeUtils.js";
+import { usePreference } from "../usePreference/index.js";
+/**
+ * Hook for managing code transforms and their application
+ * Uses the useLocalStorage hook for local storage persistence of transform preferences
+ */
+export function useTransformManagement(_ref) {
+  var context = _ref.context,
+    effectiveCode = _ref.effectiveCode,
+    selectedVariantKey = _ref.selectedVariantKey,
+    selectedVariant = _ref.selectedVariant,
+    initialTransform = _ref.initialTransform,
+    shouldHighlight = _ref.shouldHighlight;
+  // Transform state - get available transforms from context or from the effective code data
+  var availableTransforms = React.useMemo(function () {
+    // First try to get from context
+    if (context != null && context.availableTransforms && context.availableTransforms.length > 0) {
+      return context.availableTransforms;
+    }
+
+    // Otherwise, get from the effective code data using the utility function
+    return getAvailableTransforms(effectiveCode, selectedVariantKey);
+  }, [context == null ? void 0 : context.availableTransforms, effectiveCode, selectedVariantKey]);
+
+  // Use localStorage hook for transform persistence - this is our single source of truth
+  var _usePreference = usePreference('transform', availableTransforms.length === 1 ? availableTransforms[0] : availableTransforms, function () {
+      // Don't use initialTransform as the fallback - localStorage should always take precedence
+      // We'll handle the initial transform separately below
+      return null;
+    }),
+    _usePreference2 = _slicedToArray(_usePreference, 2),
+    storedValue = _usePreference2[0],
+    setStoredValue = _usePreference2[1];
+
+  // Handle validation manually - empty string means "no transform selected"
+  var selectedTransform = React.useMemo(function () {
+    // If we have a stored value (including empty string), use it
+    if (storedValue !== null) {
+      if (storedValue === '') {
+        return null;
+      }
+      // Validate the stored value
+      if (!availableTransforms.includes(storedValue)) {
+        return null;
+      }
+      return storedValue;
+    }
+
+    // If no stored value and we have an initial transform, use it (but don't store it yet)
+    if (initialTransform && availableTransforms.includes(initialTransform)) {
+      return initialTransform;
+    }
+    return null;
+  }, [storedValue, availableTransforms, initialTransform]);
+  var setSelectedTransformAsUser = React.useCallback(function (value) {
+    var valueToStore = value === null ? '' : value;
+    setStoredValue(valueToStore);
+  }, [setStoredValue]);
+
+  // Memoize all transformed files based on selectedTransform
+  var transformedFiles = React.useMemo(function () {
+    return createTransformedFiles(selectedVariant, selectedTransform, shouldHighlight);
+  }, [selectedVariant, selectedTransform, shouldHighlight]);
+  return {
+    availableTransforms: availableTransforms,
+    selectedTransform: selectedTransform,
+    transformedFiles: transformedFiles,
+    selectTransform: setSelectedTransformAsUser
+  };
+}

package/esm/useCode/useUIState.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+interface UseUIStateProps {
+  defaultOpen?: boolean;
+}
+export interface UseUIStateResult {
+  expanded: boolean;
+  expand: () => void;
+  setExpanded: React.Dispatch<React.SetStateAction<boolean>>;
+}
+/**
+ * Hook for managing UI state like expansion and focus
+ */
+export declare function useUIState({
+  defaultOpen
+}: UseUIStateProps): UseUIStateResult;
+export {};

package/esm/useCode/useUIState.js

@@ -0,0 +1,21 @@
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import * as React from 'react';
+/**
+ * Hook for managing UI state like expansion and focus
+ */
+export function useUIState(_ref) {
+  var _ref$defaultOpen = _ref.defaultOpen,
+    defaultOpen = _ref$defaultOpen === void 0 ? false : _ref$defaultOpen;
+  var _React$useState = React.useState(defaultOpen),
+    _React$useState2 = _slicedToArray(_React$useState, 2),
+    expanded = _React$useState2[0],
+    setExpanded = _React$useState2[1];
+  var expand = React.useCallback(function () {
+    return setExpanded(true);
+  }, []);
+  return {
+    expanded: expanded,
+    expand: expand,
+    setExpanded: setExpanded
+  };
+}

package/esm/useCode/useVariantSelection.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+import type { Code, VariantCode } from "../CodeHighlighter/types.js";
+interface UseVariantSelectionProps {
+  effectiveCode: Code;
+  initialVariant?: string;
+  variantType?: string;
+}
+export interface UseVariantSelectionResult {
+  variantKeys: string[];
+  selectedVariantKey: string;
+  selectedVariant: VariantCode | null;
+  selectVariant: React.Dispatch<React.SetStateAction<string>>;
+}
+/**
+ * Hook for managing variant selection and providing variant-related data
+ * Uses the useLocalStorage hook for local storage persistence of variant preferences
+ */
+export declare function useVariantSelection({
+  effectiveCode,
+  initialVariant,
+  variantType
+}: UseVariantSelectionProps): UseVariantSelectionResult;
+export {};

package/esm/useCode/useVariantSelection.js

@@ -0,0 +1,75 @@
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import _typeof from "@babel/runtime/helpers/esm/typeof";
+import * as React from 'react';
+import { usePreference } from "../usePreference/index.js";
+/**
+ * Hook for managing variant selection and providing variant-related data
+ * Uses the useLocalStorage hook for local storage persistence of variant preferences
+ */
+export function useVariantSelection(_ref) {
+  var effectiveCode = _ref.effectiveCode,
+    initialVariant = _ref.initialVariant,
+    variantType = _ref.variantType;
+  // Get variant keys from effective code
+  var variantKeys = React.useMemo(function () {
+    return Object.keys(effectiveCode).filter(function (key) {
+      var variant = effectiveCode[key];
+      return variant && _typeof(variant) === 'object' && 'source' in variant;
+    });
+  }, [effectiveCode]);
+
+  // Use localStorage hook for variant persistence - this is our single source of truth
+  var _usePreference = usePreference('variant', variantType || variantKeys, function () {
+      // Don't use initialVariant as the fallback - localStorage should take precedence
+      // We'll handle the initial variant separately in the selectedVariantKey logic
+      return null;
+    }),
+    _usePreference2 = _slicedToArray(_usePreference, 2),
+    storedValue = _usePreference2[0],
+    setStoredValue = _usePreference2[1];
+
+  // Handle validation manually - localStorage should take precedence over initialVariant
+  var selectedVariantKey = React.useMemo(function () {
+    // First priority: use stored value if it exists and is valid
+    if (storedValue && variantKeys.includes(storedValue)) {
+      return storedValue;
+    }
+
+    // Second priority: use initial variant if provided and valid (only when no localStorage value)
+    if (initialVariant && variantKeys.includes(initialVariant)) {
+      return initialVariant;
+    }
+
+    // Final fallback: use first available variant
+    return variantKeys[0] || '';
+  }, [storedValue, variantKeys, initialVariant]);
+  var setSelectedVariantKey = React.useCallback(function (value) {
+    setStoredValue(value);
+  }, [setStoredValue]);
+  var setSelectedVariantKeyAsUser = React.useCallback(function (value) {
+    var resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
+    setStoredValue(resolvedValue);
+  }, [setStoredValue, selectedVariantKey]);
+  var selectedVariant = React.useMemo(function () {
+    var variant = effectiveCode[selectedVariantKey];
+    if (variant && _typeof(variant) === 'object' && 'source' in variant) {
+      return variant;
+    }
+    return null;
+  }, [effectiveCode, selectedVariantKey]);
+
+  // Safety check: if selectedVariant doesn't exist, fall back to first variant
+  React.useEffect(function () {
+    if (!selectedVariant && variantKeys.length > 0) {
+      // Don't mark this as a user selection - it's just a fallback
+      // Use setValue instead of setValueAsUserSelection to avoid localStorage save
+      setSelectedVariantKey(variantKeys[0]);
+    }
+  }, [selectedVariant, variantKeys, setSelectedVariantKey]);
+  return {
+    variantKeys: variantKeys,
+    selectedVariantKey: selectedVariantKey,
+    selectedVariant: selectedVariant,
+    selectVariant: setSelectedVariantKeyAsUser
+  };
+}

package/esm/useCopier/index.d.ts

@@ -10,6 +10,6 @@ export type UseCopierOpts = {
 };
 export declare function useCopier(contents: (() => string | undefined) | string, opts?: UseCopierOpts): {
   copy: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void>;
-  disabled: boolean;
+  recentlySuccessful: boolean;
 };
 export {};

package/esm/useCopier/index.js

@@ -13,8 +13,8 @@ export function useCopier(contents, opts) {
   var copyTimeoutRef = React.useRef(undefined);
   var _React$useState = React.useState(false),
     _React$useState2 = _slicedToArray(_React$useState, 2),
-    disabled = _React$useState2[0],
-    setDisabled = _React$useState2[1];
+    recentlySuccessful = _React$useState2[0],
+    setRecentlySuccessful = _React$useState2[1];
   var copy = React.useCallback(/*#__PURE__*/function () {
     var _ref2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(event) {
       var content, _t;
@@ -22,7 +22,7 @@ export function useCopier(contents, opts) {
         while (1) switch (_context.p = _context.n) {
           case 0:
             clearTimeout(copyTimeoutRef.current);
-            setDisabled(true);
+            setRecentlySuccessful(false);
             _context.p = 1;
             content = typeof contents === 'function' ? contents() : contents;
             if (!content) {
@@ -43,7 +43,7 @@ export function useCopier(contents, opts) {
             onClick == null || onClick(event);
             copyTimeoutRef.current = setTimeout(function () {
               clearTimeout(copyTimeoutRef.current);
-              setDisabled(false);
+              setRecentlySuccessful(false);
             }, timeout);
           case 5:
             return _context.a(2);
@@ -56,6 +56,6 @@ export function useCopier(contents, opts) {
   }(), [contents, timeout, onCopied, onError, onClick]);
   return {
     copy: copy,
-    disabled: disabled
+    recentlySuccessful: recentlySuccessful
   };
 }

package/esm/useDemo/createCodeSandbox.d.ts

@@ -0,0 +1,15 @@
+import type { FlattenedFiles } from "./flattenVariant.js";
+/**
+ * Utility function for creating CodeSandbox demos
+ * Returns the configuration that can be used with openWithForm
+ */
+export declare function createCodeSandbox({
+  flattenedFiles,
+  rootFile
+}: {
+  flattenedFiles: FlattenedFiles;
+  rootFile: string;
+}): {
+  url: string;
+  formData: Record<string, string>;
+};

package/esm/useDemo/createCodeSandbox.js

@@ -0,0 +1,42 @@
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+import LZString from 'lz-string';
+/**
+ * Compress object for CodeSandbox API
+ */
+function compress(object) {
+  return LZString.compressToBase64(JSON.stringify(object)).replace(/\+/g, '-') // Convert '+' to '-'
+  .replace(/\//g, '_') // Convert '/' to '_'
+  .replace(/=+$/, ''); // Remove ending '='
+}
+
+/**
+ * Utility function for creating CodeSandbox demos
+ * Returns the configuration that can be used with openWithForm
+ */
+export function createCodeSandbox(_ref) {
+  var flattenedFiles = _ref.flattenedFiles,
+    rootFile = _ref.rootFile;
+  // Convert flattened files to string format
+  var files = {};
+  Object.entries(flattenedFiles).forEach(function (_ref2) {
+    var _ref3 = _slicedToArray(_ref2, 2),
+      filePath = _ref3[0],
+      fileData = _ref3[1];
+    files[filePath] = {
+      content: fileData.source
+    };
+  });
+  var parameters = compress({
+    files: files
+  });
+
+  // ref: https://codesandbox.io/docs/learn/browser-sandboxes/cli-api#supported-parameters
+  var formData = {
+    parameters: parameters,
+    query: "file=".concat(rootFile)
+  };
+  return {
+    url: 'https://codesandbox.io/api/v1/sandboxes/define',
+    formData: formData
+  };
+}

package/esm/useDemo/createStackBlitz.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Utility function for creating StackBlitz demos
+ * Returns the configuration that can be used with openWithForm
+ */
+import type { FlattenedFiles } from "./flattenVariant.js";
+/**
+ * Create StackBlitz configuration for use with openWithForm
+ */
+export declare function createStackBlitz({
+  title,
+  description,
+  flattenedFiles,
+  rootFile
+}: {
+  title: string;
+  description: string;
+  flattenedFiles: FlattenedFiles;
+  rootFile: string;
+}): {
+  url: string;
+  formData: Record<string, string>;
+};

package/esm/useDemo/createStackBlitz.js

@@ -0,0 +1,38 @@
+import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
+/**
+ * Utility function for creating StackBlitz demos
+ * Returns the configuration that can be used with openWithForm
+ */
+
+/**
+ * Create StackBlitz configuration for use with openWithForm
+ */
+export function createStackBlitz(_ref) {
+  var title = _ref.title,
+    description = _ref.description,
+    flattenedFiles = _ref.flattenedFiles,
+    rootFile = _ref.rootFile;
+  // Convert flattened files to string format
+  var files = {};
+  Object.entries(flattenedFiles).forEach(function (_ref2) {
+    var _ref3 = _slicedToArray(_ref2, 2),
+      filePath = _ref3[0],
+      fileData = _ref3[1];
+    files[filePath] = fileData.source;
+  });
+  var formData = {
+    'project[template]': 'node',
+    'project[title]': title,
+    'project[description]': "# ".concat(title, "\n").concat(description)
+  };
+  Object.entries(files).forEach(function (_ref4) {
+    var _ref5 = _slicedToArray(_ref4, 2),
+      key = _ref5[0],
+      value = _ref5[1];
+    formData["project[files][".concat(key, "]")] = value;
+  });
+  return {
+    url: "https://stackblitz.com/run?file=".concat(rootFile),
+    formData: formData
+  };
+}

package/esm/useDemo/exportVariant.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Export variant functionality to add extra files like package.json, tsconfig, etc.
+ * Users can pass configuration options that vary the output here.
+ */
+import type { VariantCode, VariantExtraFiles } from "../CodeHighlighter/types.js";
+/**
+ * Extract filename from URL or return undefined if not available
+ */
+export declare function getFilenameFromVariant(variantCode: VariantCode): string | undefined;
+/**
+ * Generate a unique entrypoint filename that doesn't conflict with existing files
+ */
+export declare function generateEntrypointFilename(existingFiles: VariantExtraFiles, sourceFilename: string | undefined, useTypescript: boolean, pathPrefix?: string): string;
+/**
+ * Generate the relative import path from entrypoint to source file
+ */
+export declare function getRelativeImportPath(sourceFilename: string | undefined): string;
+/**
+ * Default HTML template function for Vite-based demos
+ */
+export declare function defaultHtmlTemplate({
+  language,
+  title,
+  description,
+  head,
+  entrypoint
+}: {
+  language: string;
+  title: string;
+  description: string;
+  head?: string;
+  entrypoint?: string;
+}): string;
+export interface ExportConfig {
+  /** The title for the demo (used in HTML title and package.json name) */
+  title?: string;
+  /** Optional prefix to add before the title */
+  titlePrefix?: string;
+  /** Optional suffix to add after the title */
+  titleSuffix?: string;
+  /** Description for package.json */
+  description?: string;
+  /** Optional prefix to add before the description */
+  descriptionPrefix?: string;
+  /** Optional suffix to add after the description */
+  descriptionSuffix?: string;
+  /** The variant name/identifier for this specific code variant */
+  variantName?: string;
+  /**
+   * Language for the HTML document (default is 'en')
+   */
+  language?: string;
+  /**
+   * Prefix for output file paths (e.g., 'public/' for CRA, '' for Vite)
+   * @example
+   * htmlPrefix: 'public/' // outputs index.html to correct depth + public/index.html
+   */
+  htmlPrefix?: string;
+  /**
+   * Prefix for asset files (e.g., 'assets/' for CRA)
+   */
+  assetPrefix?: string;
+  /**
+   * Prefix for code files (e.g., 'src/' for Vite)
+   */
+  sourcePrefix?: string;
+  /**
+   * Custom HTML template function
+   * @example
+   * htmlTemplate: ({ language, title, description, head, entrypoint, variant, variantName }) =>
+   *   `<!doctype html><html><head><title>${title}</title>${head || ''}</head><body><div id="root"></div><script src="${entrypoint}"></script></body></html>`
+   */
+  htmlTemplate?: (params: {
+    language: string;
+    title: string;
+    description: string;
+    head?: string;
+    entrypoint?: string;
+    variant?: VariantCode;
+    variantName?: string;
+  }) => string;
+  /**
+   * Custom head template function for generating additional head content
+   * @example
+   * headTemplate: ({ sourcePrefix, assetPrefix, variant, variantName }) =>
+   *   `<link rel="stylesheet" href="${assetPrefix}/styles.css" />\n<meta name="theme-color" content="#000000" />`
+   */
+  headTemplate?: (params: {
+    sourcePrefix: string;
+    assetPrefix: string;
+    variant?: VariantCode;
+    variantName?: string;
+  }) => string;
+  /** Custom React root index template function */
+  rootIndexTemplate?: (params: {
+    importString: string;
+    useTypescript: boolean;
+  }) => string;
+  /** Extra package.json dependencies to add */
+  dependencies?: Record<string, string>;
+  /** Extra package.json devDependencies to add */
+  devDependencies?: Record<string, string>;
+  /** Extra package.json scripts to add */
+  scripts?: Record<string, string>;
+  /** Package type: 'module' for ESM, 'commonjs' for CJS, undefined to omit */
+  packageType?: 'module' | 'commonjs';
+  /** Custom package.json fields to merge */
+  packageJsonFields?: Record<string, any>;
+  /** Extra tsconfig.json options to merge */
+  tsconfigOptions?: Record<string, any>;
+  /** Vite configuration options */
+  viteConfig?: Record<string, any>;
+  /** Whether to include TypeScript configuration files */
+  useTypescript?: boolean;
+  /** Custom metadata files to add */
+  extraMetadataFiles?: Record<string, {
+    source: string;
+  }>;
+  /**
+   * Whether the framework handles entrypoint and HTML generation (e.g., CRA with webpack)
+   * When true, skips generating index.html and entrypoint files
+   */
+  frameworkHandlesEntrypoint?: boolean;
+  /**
+   * Whether to skip adding the JavaScript link in the HTML
+   */
+  htmlSkipJsLink?: boolean;
+  /** Framework-specific files that override default files (index.html, entrypoint, etc.) */
+  frameworkFiles?: {
+    variant?: VariantCode;
+    globals?: VariantExtraFiles;
+  };
+  /**
+   * Custom export function to use instead of the default exportVariant or exportVariantAsCra
+   * @example
+   * exportFunction: (variantCode, config) => ({ exported: customProcessedCode, rootFile: 'custom-entry.js' })
+   */
+  exportFunction?: (variantCode: VariantCode, config: ExportConfig) => {
+    exported: VariantCode;
+    rootFile: string;
+  };
+  /**
+   * Transform function that runs at the very start of the export process
+   * Can modify the variant code and metadata before any other processing happens
+   * @example
+   * transformVariant: (variant, globals, variantName) => ({
+   *   variant: { ...variant, source: modifiedSource },
+   *   globals: { ...globals, extraFiles: { ...globals.extraFiles, 'theme.css': { source: '.new {}', metadata: true } } }
+   * })
+   */
+  transformVariant?: (variant: VariantCode, variantName?: string, globals?: VariantExtraFiles) => {
+    variant?: VariantCode;
+    globals?: VariantExtraFiles;
+  } | undefined;
+  /**
+   * Version overrides for core packages (react, react-dom, @types/react, @types/react-dom)
+   * @example
+   * versions: {
+   *   '@types/react': '^19',
+   *   '@types/react-dom': '^19',
+   *   react: '^19',
+   *   'react-dom': '^19',
+   * }
+   */
+  versions?: Record<string, string>;
+  /**
+   * Custom dependency resolution function
+   * @example
+   * resolveDependencies: (packageName, envVars) => {
+   *   if (packageName === '@mui/material') {
+   *     return { '@mui/material': 'latest', '@emotion/react': 'latest' };
+   *   }
+   *   return { [packageName]: 'latest' };
+   * }
+   */
+  resolveDependencies?: (packageName: string, envVars?: Record<string, string>) => Record<string, string>;
+}
+/**
+ * Export a variant as a standalone project with metadata files properly scoped
+ */
+export declare function exportVariant(variantCode: VariantCode, config?: ExportConfig): {
+  exported: VariantCode;
+  rootFile: string;
+};