@mui/internal-docs-infra 0.2.3-canary.9 → 0.3.1-canary.0

package/esm/useCode/useVariantSelection.js

@@ -3,16 +3,69 @@ import _typeof from "@babel/runtime/helpers/esm/typeof";
 import * as React from 'react';
 import { usePreference } from "../usePreference/index.js";
 import { useUrlHashState } from "../useUrlHashState/index.js";
-import { isHashRelevantToDemo } from "./useFileNavigation.js";
+import { isHashRelevantToDemo, toKebabCase } from "./useFileNavigation.js";
+
+/**
+ * Parses the variant name from a URL hash
+ * Hash formats:
+ * - slug:file.tsx -> "Default"
+ * - slug:variant:file.tsx -> "variant"
+ * - slug:variant -> "variant"
+ * @param urlHash - The URL hash (without '#')
+ * @param mainSlug - The main slug for the demo (optional, used to determine if hash is relevant for file selection)
+ * @param variantKeys - Available variant keys
+ * @returns The variant name or null if not found/parseable
+ */
+function parseVariantFromHash(urlHash, mainSlug, variantKeys) {
+  if (!urlHash) {
+    return null;
+  }
+  var parts = urlHash.split(':');
+
+  // If there are 3 parts (slug:variant:file), the variant is in the middle
+  if (parts.length === 3) {
+    var variantPart = parts[1];
+    // Find matching variant key (case-insensitive kebab match)
+    var matchingVariant = variantKeys.find(function (key) {
+      return toKebabCase(key) === variantPart.toLowerCase();
+    });
+    return matchingVariant || null;
+  }
+
+  // If there are 2 parts, could be slug:variant or slug:file
+  if (parts.length === 2) {
+    var secondPart = parts[1];
+    // Try to match as a variant first
+    var _matchingVariant = variantKeys.find(function (key) {
+      return toKebabCase(key) === secondPart.toLowerCase();
+    });
+    if (_matchingVariant) {
+      return _matchingVariant;
+    }
+    // If no matching variant and it looks like a filename, assume Default
+    if (secondPart.includes('.')) {
+      return 'Default';
+    }
+  }
+
+  // Just the slug with no other parts, assume Default
+  if (parts.length === 1) {
+    return 'Default';
+  }
+  return null;
+}
 /**
  * Hook for managing variant selection and providing variant-related data
- * Uses React state as source of truth, with localStorage for persistence
+ * Priority: URL hash > localStorage > initialVariant > first variant
+ * When hash has a variant, it overrides localStorage and is saved to localStorage
  */
 export function useVariantSelection(_ref) {
   var effectiveCode = _ref.effectiveCode,
     initialVariant = _ref.initialVariant,
     variantType = _ref.variantType,
-    mainSlug = _ref.mainSlug;
+    mainSlug = _ref.mainSlug,
+    _ref$saveHashVariantT = _ref.saveHashVariantToLocalStorage,
+    saveHashVariantToLocalStorage = _ref$saveHashVariantT === void 0 ? 'on-interaction' : _ref$saveHashVariantT;
   // Get variant keys from effective code
   var variantKeys = React.useMemo(function () {
     return Object.keys(effectiveCode).filter(function (key) {
@@ -21,14 +74,14 @@ export function useVariantSelection(_ref) {
     });
   }, [effectiveCode]);
 
-  // Check if there's a URL hash present that's relevant to this demo
-  // Only override localStorage if hash starts with this demo's slug
+  // Get URL hash and parse variant from it
   var _useUrlHashState = useUrlHashState(),
-    _useUrlHashState2 = _slicedToArray(_useUrlHashState, 1),
-    urlHash = _useUrlHashState2[0];
-  var hasRelevantUrlHash = React.useMemo(function () {
-    return isHashRelevantToDemo(urlHash, mainSlug);
-  }, [urlHash, mainSlug]);
+    _useUrlHashState2 = _slicedToArray(_useUrlHashState, 2),
+    urlHash = _useUrlHashState2[0],
+    setUrlHash = _useUrlHashState2[1];
+  var hashVariant = React.useMemo(function () {
+    return parseVariantFromHash(urlHash, mainSlug, variantKeys);
+  }, [urlHash, mainSlug, variantKeys]);
 
   // Use localStorage hook for variant persistence
   var _usePreference = usePreference('variant', variantType || variantKeys, function () {
@@ -38,73 +91,105 @@ export function useVariantSelection(_ref) {
     storedValue = _usePreference2[0],
     setStoredValue = _usePreference2[1];
 
-  // Initialize state - will be updated by effect if localStorage should be used
+  // Track if the last change was user-initiated (to prevent hash from overriding)
+  var isUserInitiatedChange = React.useRef(false);
+  // Track previous hash variant to detect hash changes
+  var prevHashVariant = React.useRef(hashVariant);
+  // Track previous storedValue to detect localStorage changes
+  var prevStoredValue = React.useRef(storedValue);
+
+  // Determine initial variant: hash > localStorage > initialVariant > first variant
   var _React$useState = React.useState(function () {
-      // Use initial variant if provided and valid
+      // Priority 1: Hash variant
+      if (hashVariant && variantKeys.includes(hashVariant)) {
+        return hashVariant;
+      }
+      // Priority 2: localStorage
+      if (storedValue && variantKeys.includes(storedValue)) {
+        return storedValue;
+      }
+      // Priority 3: initialVariant prop
       if (initialVariant && variantKeys.includes(initialVariant)) {
         return initialVariant;
       }
-
-      // Final fallback: use first available variant
+      // Priority 4: First available variant
       return variantKeys[0] || '';
     }),
     _React$useState2 = _slicedToArray(_React$useState, 2),
     selectedVariantKey = _React$useState2[0],
     setSelectedVariantKeyState = _React$useState2[1];
 
-  // On mount, check if we should restore from localStorage
-  // This needs to be in an effect because we need to check hasRelevantUrlHash which depends on urlHash
-  var _React$useState3 = React.useState(false),
-    _React$useState4 = _slicedToArray(_React$useState3, 2),
-    hasInitialized = _React$useState4[0],
-    setHasInitialized = _React$useState4[1];
+  // Track selected variant key in a ref for use in effect without causing re-runs
+  var selectedVariantKeyRef = React.useRef(selectedVariantKey);
   React.useEffect(function () {
-    if (hasInitialized) {
-      return;
-    }
-    setHasInitialized(true);
+    selectedVariantKeyRef.current = selectedVariantKey;
+  });
 
-    // If there's a relevant URL hash, don't use localStorage - hash takes priority
-    if (hasRelevantUrlHash) {
+  // When hash changes and has a variant, override current selection
+  // When hash is removed, fall back to localStorage
+  React.useEffect(function () {
+    // Skip if this was a user-initiated change
+    if (isUserInitiatedChange.current) {
+      // Only reset the flag once the hash has actually been cleared
+      if (hashVariant === null && urlHash === null) {
+        isUserInitiatedChange.current = false;
+      }
+      prevHashVariant.current = hashVariant;
       return;
     }
 
-    // If we have a stored value, use it (localStorage takes priority over initialVariant)
-    if (storedValue && variantKeys.includes(storedValue)) {
-      setSelectedVariantKeyState(storedValue);
-    }
-  }, [hasInitialized, hasRelevantUrlHash, storedValue, variantKeys]);
-
-  // Sync with localStorage changes (but don't override programmatic changes or when hash is present)
-  // Only sync when storedValue changes, not when selectedVariantKey changes
-  var prevStoredValue = React.useRef(storedValue);
-  React.useEffect(function () {
-    // Don't sync from localStorage when a relevant URL hash is present - hash takes absolute priority
-    if (hasRelevantUrlHash) {
+    // Only apply hash if it actually changed (not just a re-render with same hash)
+    var hashChanged = prevHashVariant.current !== hashVariant;
+    var storedValueChanged = prevStoredValue.current !== storedValue;
+    prevHashVariant.current = hashVariant;
+    prevStoredValue.current = storedValue;
+    if (!hashChanged && !storedValueChanged) {
       return;
     }
-    if (storedValue !== prevStoredValue.current) {
-      prevStoredValue.current = storedValue;
-      if (storedValue && variantKeys.includes(storedValue) && storedValue !== selectedVariantKey) {
-        setSelectedVariantKeyState(storedValue);
+    if (hashVariant && variantKeys.includes(hashVariant) && hashVariant !== selectedVariantKeyRef.current) {
+      // Hash has a variant - use it
+      setSelectedVariantKeyState(hashVariant);
+      // Save hash variant to localStorage based on configuration
+      if (saveHashVariantToLocalStorage === 'on-load' && hashVariant !== storedValue) {
+        setStoredValue(hashVariant);
       }
+    } else if (!hashVariant && !urlHash &&
+    // Only fall back to localStorage when hash is truly empty
+    storedValue && variantKeys.includes(storedValue) && storedValue !== selectedVariantKeyRef.current) {
+      // Hash is empty but localStorage has a variant - use it
+      setSelectedVariantKeyState(storedValue);
     }
-  }, [storedValue, variantKeys, selectedVariantKey, hasRelevantUrlHash]);
+  }, [hashVariant, urlHash, variantKeys,
+  // Note: selectedVariantKey is intentionally NOT in dependencies
+  // to avoid effect running when user manually changes variant
+  storedValue, setStoredValue, saveHashVariantToLocalStorage]);
+
+  // Programmatic setter: doesn't save to localStorage (used for hash-driven changes)
   var setSelectedVariantKeyProgrammatic = React.useCallback(function (value) {
     var resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
     if (variantKeys.includes(resolvedValue)) {
-      // Only update React state, not localStorage
-      // This prevents conflicts with hash-driven navigation
       setSelectedVariantKeyState(resolvedValue);
     }
   }, [selectedVariantKey, variantKeys]);
+
+  // User setter: saves to localStorage (used for user-initiated changes like dropdown)
   var setSelectedVariantKeyAsUser = React.useCallback(function (value) {
     var resolvedValue = typeof value === 'function' ? value(selectedVariantKey) : value;
-    if (variantKeys.includes(resolvedValue)) {
-      setSelectedVariantKeyState(resolvedValue);
-      setStoredValue(resolvedValue);
+    // If value is null, select the first variant (default)
+    var effectiveValue = resolvedValue != null ? resolvedValue : variantKeys[0];
+    if (effectiveValue && variantKeys.includes(effectiveValue)) {
+      // Mark as user-initiated to prevent hash effect from overriding
+      isUserInitiatedChange.current = true;
+      // Clear hash if it exists and is relevant to this demo
+      if (urlHash && mainSlug && isHashRelevantToDemo(urlHash, mainSlug)) {
+        setUrlHash(null);
+        // Update prevHashVariant to reflect that hash is now null
+        prevHashVariant.current = null;
+      }
+      setSelectedVariantKeyState(effectiveValue);
+      setStoredValue(effectiveValue);
     }
-  }, [setStoredValue, selectedVariantKey, variantKeys]);
+  }, [setStoredValue, selectedVariantKey, variantKeys, urlHash, mainSlug, setUrlHash]);
   var selectedVariant = React.useMemo(function () {
     var variant = effectiveCode[selectedVariantKey];
     if (variant && _typeof(variant) === 'object' && 'source' in variant) {
@@ -116,16 +201,23 @@ export function useVariantSelection(_ref) {
   // 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 programmatic setter to avoid localStorage save
       setSelectedVariantKeyProgrammatic(variantKeys[0]);
     }
   }, [selectedVariant, variantKeys, setSelectedVariantKeyProgrammatic]);
+
+  // Function to save variant to localStorage (used for on-interaction mode)
+  var saveVariantToLocalStorage = React.useCallback(function (variant) {
+    if (saveHashVariantToLocalStorage === 'on-interaction' && variant !== storedValue) {
+      setStoredValue(variant);
+    }
+  }, [saveHashVariantToLocalStorage, storedValue, setStoredValue]);
   return {
     variantKeys: variantKeys,
     selectedVariantKey: selectedVariantKey,
     selectedVariant: selectedVariant,
     selectVariant: setSelectedVariantKeyAsUser,
-    selectVariantProgrammatic: setSelectedVariantKeyProgrammatic
+    selectVariantProgrammatic: setSelectedVariantKeyProgrammatic,
+    saveVariantToLocalStorage: saveVariantToLocalStorage,
+    hashVariant: hashVariant
   };
 }

package/esm/useCopier/index.js

@@ -32,7 +32,12 @@ export function useCopier(contents, opts) {
             _context.n = 2;
             return copyToClipboard(content);
           case 2:
+            setRecentlySuccessful(true);
             onCopied == null || onCopied();
+            copyTimeoutRef.current = setTimeout(function () {
+              clearTimeout(copyTimeoutRef.current);
+              setRecentlySuccessful(false);
+            }, timeout);
             _context.n = 4;
             break;
           case 3:
@@ -41,10 +46,6 @@ export function useCopier(contents, opts) {
             onError == null || onError(_t);
           case 4:
             onClick == null || onClick(event);
-            copyTimeoutRef.current = setTimeout(function () {
-              clearTimeout(copyTimeoutRef.current);
-              setRecentlySuccessful(false);
-            }, timeout);
           case 5:
             return _context.a(2);
         }

package/esm/useDemo/createCodeSandbox.d.ts

@@ -1,4 +1,4 @@
-import type { FlattenedFiles } from "./flattenVariant.js";
+import type { FlattenedFiles } from "../pipeline/loadCodeVariant/flattenCodeVariant.js";
 /**
  * Utility function for creating CodeSandbox demos
  * Returns the configuration that can be used with openWithForm

package/esm/useDemo/createStackBlitz.d.ts

@@ -2,7 +2,7 @@
  * Utility function for creating StackBlitz demos
  * Returns the configuration that can be used with openWithForm
  */
-import type { FlattenedFiles } from "./flattenVariant.js";
+import type { FlattenedFiles } from "../pipeline/loadCodeVariant/flattenCodeVariant.js";
 /**
  * Create StackBlitz configuration for use with openWithForm
  */

package/esm/useDemo/exportVariant.js

@@ -7,8 +7,8 @@ import _slicedToArray from "@babel/runtime/helpers/esm/slicedToArray";
 
 import { externalsToPackages } from "../pipeline/loaderUtils/index.js";
 import { getFileNameFromUrl } from "../pipeline/loaderUtils/getFileNameFromUrl.js";
-import { createPathContext } from "../CodeHighlighter/examineVariant.js";
-import { mergeMetadata, extractMetadata } from "../CodeHighlighter/mergeMetadata.js";
+import { examineCodeVariant } from "../pipeline/loadCodeVariant/examineCodeVariant.js";
+import { mergeCodeMetadata, extractCodeMetadata } from "../pipeline/loadCodeVariant/mergeCodeMetadata.js";
 
 /**
  * Merges multiple file objects into a single object.
@@ -162,15 +162,17 @@ export function exportVariant(variantCode) {
   var finalTitle = [titlePrefix, title, titleSuffix].filter(Boolean).join('');
   var finalDescription = [descriptionPrefix, description, descriptionSuffix].filter(Boolean).join('');
 
-  // Use extractMetadata to properly separate metadata and non-metadata files
-  var _extractMetadata = extractMetadata(variantCode),
-    processedVariantCode = _extractMetadata.variant,
-    processedGlobals = _extractMetadata.metadata;
+  // Use extractCodeMetadata to properly separate metadata and non-metadata files
+  var _extractCodeMetadata = extractCodeMetadata(variantCode),
+    processedVariantCode = _extractCodeMetadata.variant,
+    processedGlobals = _extractCodeMetadata.metadata;
+
+  // Run optional transform hook to modify variant and globals before processing
   if (transformVariant) {
     var transformed = transformVariant(processedVariantCode, variantName, processedGlobals);
     if (transformed) {
       // Re-extract metadata after transformation
-      var result = transformed.variant && extractMetadata(transformed.variant);
+      var result = transformed.variant && extractCodeMetadata(transformed.variant);
       processedVariantCode = (result == null ? void 0 : result.variant) || processedVariantCode;
 
       // Start fresh with only the new metadata and explicitly transformed globals
@@ -191,7 +193,7 @@ export function exportVariant(variantCode) {
   var sourceFilename = getFilenameFromVariant(processedVariantCode);
 
   // Get path context to understand navigation
-  var pathContext = createPathContext(variantCode);
+  var pathContext = examineCodeVariant(variantCode);
 
   // Determine if we need to rename the source file
   var ext = useTypescript ? 'tsx' : 'jsx';
@@ -401,7 +403,7 @@ export function exportVariant(variantCode) {
   // Merge all metadata files including framework metadata and globals
   var allMetadataFiles = mergeFiles(processedGlobals || {}, metadataFiles, extraMetadataFiles, frameworkFiles.globals || {});
 
-  // Merge all files using mergeMetadata to properly position everything with 'src/' (sourcePrefix opt) prefix
+  // Merge all files using mergeCodeMetadata to properly position everything with 'src/' (sourcePrefix opt) prefix
   var allSourceFilesWithFramework = mergeFiles(processedVariantCode.extraFiles || {}, generatedFiles, ((_frameworkFiles$varia = frameworkFiles.variant) == null ? void 0 : _frameworkFiles$varia.extraFiles) || {});
 
   // Update the variant with all source files including framework source files
@@ -409,8 +411,8 @@ export function exportVariant(variantCode) {
     extraFiles: allSourceFilesWithFramework
   });
 
-  // Use mergeMetadata to position everything correctly
-  var finalVariant = mergeMetadata(finalVariantWithSources, allMetadataFiles, {
+  // Use mergeCodeMetadata to position everything correctly
+  var finalVariant = mergeCodeMetadata(finalVariantWithSources, allMetadataFiles, {
     metadataPrefix: sourcePrefix
   });
 

package/esm/useDemo/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./useDemo.js";
 export * from "./createStackBlitz.js";
 export * from "./createCodeSandbox.js";
-export * from "./flattenVariant.js";
+export * from "../pipeline/loadCodeVariant/flattenCodeVariant.js";
 export * from "./exportVariant.js";
 export * from "./exportVariantAsCra.js";

package/esm/useDemo/index.js

@@ -1,6 +1,6 @@
 export * from "./useDemo.js";
 export * from "./createStackBlitz.js";
 export * from "./createCodeSandbox.js";
-export * from "./flattenVariant.js";
+export * from "../pipeline/loadCodeVariant/flattenCodeVariant.js";
 export * from "./exportVariant.js";
 export * from "./exportVariantAsCra.js";

package/esm/useDemo/useDemo.d.ts

@@ -3,16 +3,16 @@ import type { UseCodeOpts } from "../useCode/index.js";
 import type { ContentProps } from "../CodeHighlighter/types.js";
 import { type ExportConfig } from "./exportVariant.js";
 /**
- * Demo templates use the exportVariant/exportVariantAsCra with flattenVariant pattern:
+ * Demo templates use the exportVariant/exportVariantAsCra with flattenCodeVariant pattern:
  *
  * For StackBlitz:
  * const { exported: exportedVariant, entrypoint } = exportVariant(variantCode);
- * const flattenedFiles = flattenVariant(exportedVariant);
+ * const flattenedFiles = flattenCodeVariant(exportedVariant);
  * createStackBlitzDemo({ title, description, flattenedFiles, useTypescript, initialFile: entrypoint })
  *
  * For CodeSandbox:
  * const { exported: craExport, entrypoint } = exportVariantAsCra(variantCode, { title, description, useTypescript });
- * const flattenedFiles = flattenVariant(craExport);
+ * const flattenedFiles = flattenCodeVariant(craExport);
  * createCodeSandboxDemo({ title, description, flattenedFiles, useTypescript, initialFile: entrypoint })
  * createCodeSandboxDemo({ title, description, flattenedFiles, useTypescript })
  */
@@ -55,7 +55,7 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   slug: string | undefined;
   variants: string[];
   selectedVariant: string;
-  selectVariant: React.Dispatch<React.SetStateAction<string>>;
+  selectVariant: (variant: string | null) => void;
   files: Array<{
     name: string;
     slug?: string;
@@ -72,7 +72,7 @@ export declare function useDemo<T extends {} = {}>(contentProps: ContentProps<T>
   }>;
   expanded: boolean;
   expand: () => void;
-  setExpanded: React.Dispatch<React.SetStateAction<boolean>>;
+  setExpanded: (expanded: boolean) => void;
   copy: (event: React.MouseEvent<HTMLButtonElement>) => Promise<void>;
   availableTransforms: string[];
   selectedTransform: string | null | undefined;

package/esm/useDemo/useDemo.js

@@ -8,19 +8,19 @@ import { createStackBlitz } from "./createStackBlitz.js";
 import { createCodeSandbox } from "./createCodeSandbox.js";
 import { exportVariant } from "./exportVariant.js";
 import { exportVariantAsCra } from "./exportVariantAsCra.js";
-import { flattenVariant } from "./flattenVariant.js";
+import { flattenCodeVariant } from "../pipeline/loadCodeVariant/flattenCodeVariant.js";
 
 /**
- * Demo templates use the exportVariant/exportVariantAsCra with flattenVariant pattern:
+ * Demo templates use the exportVariant/exportVariantAsCra with flattenCodeVariant pattern:
  *
  * For StackBlitz:
  * const { exported: exportedVariant, entrypoint } = exportVariant(variantCode);
- * const flattenedFiles = flattenVariant(exportedVariant);
+ * const flattenedFiles = flattenCodeVariant(exportedVariant);
  * createStackBlitzDemo({ title, description, flattenedFiles, useTypescript, initialFile: entrypoint })
  *
  * For CodeSandbox:
  * const { exported: craExport, entrypoint } = exportVariantAsCra(variantCode, { title, description, useTypescript });
- * const flattenedFiles = flattenVariant(craExport);
+ * const flattenedFiles = flattenCodeVariant(craExport);
  * createCodeSandboxDemo({ title, description, flattenedFiles, useTypescript, initialFile: entrypoint })
  * createCodeSandboxDemo({ title, description, flattenedFiles, useTypescript })
  */
@@ -133,7 +133,7 @@ export function useDemo(contentProps, opts) {
       rootFile = _exportFunction.rootFile;
 
     // Flatten the variant to get a flat file structure
-    var flattenedFiles = flattenVariant(exported);
+    var flattenedFiles = flattenCodeVariant(exported);
     var stackBlitzDemo = createStackBlitz({
       title: title,
       description: description,
@@ -173,7 +173,7 @@ export function useDemo(contentProps, opts) {
       rootFile = _exportFunction2.rootFile;
 
     // Flatten the variant to get a flat file structure
-    var flattenedFiles = flattenVariant(craExport);
+    var flattenedFiles = flattenCodeVariant(craExport);
     var codeSandboxDemo = createCodeSandbox({
       flattenedFiles: flattenedFiles,
       rootFile: rootFile

package/esm/useErrors/useErrors.d.ts

@@ -1,5 +1,5 @@
 type Errors = {
   errors?: Error[];
 };
-export declare function useErrors(): Errors;
+export declare function useErrors(props?: Errors): Errors;
 export {};

package/esm/useErrors/useErrors.js

@@ -1,7 +1,11 @@
 import { useErrorsContext } from "./ErrorsContext.js";
-export function useErrors() {
+export function useErrors(props) {
   var context = useErrorsContext();
+
+  // Context errors take precedence over prop errors
+  // This ensures client-side errors override server-side errors
+  var errors = (context == null ? void 0 : context.errors) || (props == null ? void 0 : props.errors);
   return {
-    errors: context == null ? void 0 : context.errors
+    errors: errors
   };
 }

package/esm/useSearch/index.d.ts

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

package/esm/useSearch/index.js

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

package/esm/useSearch/types.d.ts

@@ -0,0 +1,165 @@
+import { ElapsedTime, Orama, SearchParams } from '@orama/orama';
+import type { Sitemap, SitemapPage, SitemapSection, SitemapPart, SitemapExport, SitemapSectionData } from "../createSitemap/types.js";
+/**
+ * Base search result structure that can be extended by consumers
+ */
+export interface BaseSearchResult {
+  id?: string;
+  title?: string;
+  description?: string;
+  slug: string;
+  path: string;
+  sectionTitle: string;
+  prefix: string;
+  keywords?: string;
+  score?: number;
+  group?: string;
+}
+/**
+ * Page search result (top-level documentation page)
+ */
+export interface PageSearchResult extends BaseSearchResult {
+  type: 'page';
+  page?: string;
+  pageKeywords?: string;
+  sections?: string;
+  subsections?: string;
+}
+/**
+ * Part search result (component part with API documentation)
+ */
+export interface PartSearchResult extends BaseSearchResult {
+  type: 'part';
+  part: string;
+  export: string;
+  props?: string;
+  dataAttributes?: string;
+  cssVariables?: string;
+}
+/**
+ * Export search result (exported function/component with API documentation)
+ */
+export interface ExportSearchResult extends BaseSearchResult {
+  type: 'export';
+  export: string;
+  props?: string;
+  dataAttributes?: string;
+  cssVariables?: string;
+}
+/**
+ * Section search result (top-level heading within a page)
+ */
+export interface SectionSearchResult extends BaseSearchResult {
+  type: 'section';
+  section: string;
+}
+/**
+ * Subsection search result (nested heading within a page)
+ */
+export interface SubsectionSearchResult extends BaseSearchResult {
+  type: 'subsection';
+  subsection: string;
+}
+/**
+ * Union type of all common search result variants
+ */
+export type SearchResult = PageSearchResult | PartSearchResult | ExportSearchResult | SectionSearchResult | SubsectionSearchResult;
+export type { SitemapPage, SitemapSection, SitemapPart, SitemapExport, SitemapSectionData, Sitemap };
+export type SearchResults = {
+  group: string;
+  items: SearchResult[];
+}[];
+/**
+ * Options for configuring search behavior
+ */
+export interface UseSearchOptions {
+  /** Function that returns a promise resolving to sitemap data */
+  sitemap: () => Promise<{
+    sitemap?: Sitemap;
+  }>;
+  /** Maximum number of default results to show */
+  maxDefaultResults?: number;
+  /** Search tolerance for fuzzy matching */
+  tolerance?: number;
+  /** Maximum number of search results */
+  limit?: number;
+  /** Enable stemming and stopwords (uses English by default) */
+  enableStemming?: boolean;
+  /** Boost values for different result types and fields */
+  boost?: Partial<Record<string, number>>;
+  /** Include page categories in groups: "Overview Pages" vs "Pages" */
+  includeCategoryInGroup?: boolean;
+  /**
+   * When true, excludes `sections` and `subsections` fields from page-type results.
+   * The individual section and subsection entries are still created.
+   * @default false
+   */
+  excludeSections?: boolean;
+  /**
+   * Custom function to convert heading text to URL-friendly slugs.
+   * Use this to match your site's slug generation (e.g., rehype-slug).
+   * Only applied to section/subsection slugs from the sitemap.
+   *
+   * If not provided, the original slugs from the sitemap are used as-is.
+   *
+   * The second parameter `parentTitles` contains the original text of parent headings,
+   * useful for pages that concatenate parent context into child heading IDs
+   * (e.g., Releases pages: `v1.0.0-rc.0-autocomplete` where the version is prepended).
+   *
+   * @example
+   * ```ts
+   * // Simple generateSlug (ignores parent context)
+   * generateSlug: (text) => text.toLowerCase().replace(/[^a-z0-9]+/g, '-')
+   *
+   * // generateSlug with parent concatenation for subsections (e.g., Releases page)
+   * generateSlug: (text, parentTitles) => {
+   *   const slug = stringToUrl(text);
+   *   // If parent is a semver version, prepend it to match rehypeConcatHeadings
+   *   if (parentTitles?.[0]?.match(/^v\d+\.\d+\.\d+/)) {
+   *     return `${parentTitles[0]}-${slug}`;
+   *   }
+   *   return slug;
+   * }
+   * ```
+   */
+  generateSlug?: (text: string, parentTitles?: string[]) => string;
+  /** Custom function to flatten sitemap pages into search results */
+  flattenPage?: (page: SitemapPage, sectionData: SitemapSectionData) => SearchResult[];
+  /** Custom function to format Orama search hits into typed results */
+  formatResult?: <TDocument = unknown>(hit: import('@orama/orama').Result<TDocument>) => SearchResult;
+}
+export type SearchBy<T> = Pick<SearchParams<Orama<T>>, 'facets' | 'groupBy' | 'limit' | 'offset' | 'where'>;
+/**
+ * Return value from useSearch hook
+ */
+export interface UseSearchResult<T> {
+  /**
+   * Current search results
+   */
+  results: {
+    results: SearchResults;
+    count: number;
+    elapsed: ElapsedTime;
+  };
+  /**
+   * Whether the search index is ready
+   */
+  isReady: boolean;
+  /**
+   * Function to update search value and get new results
+   */
+  search: (value: string, by?: SearchBy<T>) => Promise<void>;
+  /**
+   * Default results shown when search is empty
+   */
+  defaultResults: {
+    results: SearchResults;
+    count: number;
+    elapsed: ElapsedTime;
+  };
+  /**
+   * Build a URL from a search result
+   * Handles path normalization and hash fragments for different result types
+   */
+  buildResultUrl: (result: SearchResult) => string;
+}