@mui/internal-docs-infra/useCode/useFileNavigation.d.mts

MUI Infra - internal documentation creation tools.

import * as React from 'react';
import type { Fallbacks, VariantCode, VariantSource, Code, SourceEnhancers } from "../CodeHighlighter/types.mjs";
import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs";
import type { TransformedFiles } from "./useCodeUtils.mjs";
import type { SetSource } from "./useSourceEditing.mjs";
/**
 * Checks if the URL hash is relevant to a specific demo
 * Hash format is: {mainSlug}:{variantName}:{fileName} or {mainSlug}:{fileName}
 * @param urlHash - The URL hash (without '#')
 * @param mainSlug - The main slug for the demo
 * @returns true if the hash starts with the demo's slug
 */
export declare function isHashRelevantToDemo(urlHash: string | null, mainSlug?: string): boolean;
interface UseFileNavigationProps {
  selectedVariant: VariantCode | null;
  transformedFiles: TransformedFiles | undefined;
  selectedTransform?: string | null;
  mainSlug?: string;
  selectedVariantKey?: string;
  variantKeys?: string[];
  shouldHighlight: boolean;
  preClassName?: string;
  setSource?: SetSource;
  /**
   * Forwarded to `<Pre>` / `useEditable`: when the editing engine loads for an
   * editable block. `'eager'` (default) loads on mount; `'interaction'` defers
   * until the user hovers/focuses/clicks. Sourced from the `editActivation`
   * prop on `CodeHighlighter` (via `CodeHighlighterContext`).
   */
  editActivation?: 'eager' | 'interaction';
  /** Forwarded to `<Pre>` / `useEditable`: fired once when the block engages for editing. */
  onActivate?: () => void;
  effectiveCode?: Code;
  selectVariant?: React.Dispatch<React.SetStateAction<string>>;
  fileHashMode?: 'remove-hash' | 'remove-filename';
  saveHashVariantToLocalStorage?: 'on-load' | 'on-interaction' | 'never';
  saveVariantToLocalStorage?: (variant: string) => void;
  hashVariant?: string | null;
  /**
   * Array of enhancer functions to apply to parsed HAST sources.
   * Enhancers receive the HAST root, comments extracted from source, and filename.
   */
  sourceEnhancers?: SourceEnhancers;
  /**
   * Compact fallback data for the active variant, keyed by filename.
   */
  fallbacks?: Fallbacks;
  /**
   * Whether the surrounding code block is currently expanded. Forwarded to
   * `<Pre>` so it can disable collapsed-state behaviors (e.g. `minColumn`).
   */
  expanded?: boolean;
  /**
   * Render-time "collapse to empty". Forwarded to `<Pre>`: collapses the block to an
   * empty window (whole block hidden until expanded) by demoting collapsed-
   * visible frame types at render. Orthogonal to `expanded`.
   */
  collapseToEmpty?: boolean;
  /**
   * Called when the user attempts to navigate the caret past the visible
   * region of a collapsed code block. Forwarded to `<Pre>`.
   */
  expand?: () => void;
  /**
   * State of an in-flight transform animation, or `null` when
   * settled. Forwarded to `<Pre>` so it can expose a
   * `data-transforming` attribute (`'collapsed'` / `'expanding'` /
   * `'expanded'` / `'collapsing'`) for CSS-driven exit/entry
   * animations gated on a paused-then-active handshake.
   */
  transforming?: 'collapsed' | 'expanding' | 'expanded' | 'collapsing' | null;
  /**
   * Forwarded to `<Pre>` as `onTransitionReady`. Fired once the
   * paused `transforming` value has fully reconciled — highlighted
   * HAST committed and the visible-frame set settled — plus one
   * animation frame, so the caller can advance to the matching
   * active value.
   */
  onPreTransitionReady?: () => void;
  /**
   * Controls which line-count metric `<Pre>` uses when computing the
   * variant bridge `.collapse` delta:
   *   - `'focus'`: while collapsed, compare `focusedLines`; while
   *     expanded, compare `totalLines`.
   *   - `'total'`: always compare `totalLines` regardless of
   *     collapsed/expanded state.
   */
  variantBridgeLineMode?: 'focus' | 'total';
  /**
   * Partner variant whose per-file line counts feed `<Pre>`'s
   * bridge `.collapse` placeholder during a variant swap. When set,
   * each rendered `<Pre>` receives a `swapTarget` prop derived from
   * the matching file in this variant; when `null`, `swapTarget` is
   * `null` and `<Pre>` falls back to its normal render path.
   *
   * The partner is the *other* side of the in-flight swap:
   *   - During `'collapsed'` / `'expanding'`: the incoming variant.
   *   - During `'expanded'` / `'collapsing'`: the outgoing variant we just left.
   */
  swapPartnerVariant?: VariantCode | null;
  /**
   * Currently-selected file name. The hook is always controlled —
   * callers (typically `useCode`) own the state so it can be read
   * upstream of `useFileNavigation` to drive transform-management
   * decisions.
   */
  selectedFileName: string | undefined;
  /**
   * Setter for `selectedFileName`. Called by the hook in response to
   * hash changes, variant switches, and `selectFileName` invocations.
   */
  setSelectedFileName: React.Dispatch<React.SetStateAction<string | undefined>>;
}
export interface UseFileNavigationResult {
  selectedFileName: string | undefined;
  selectedFileUrl: string | undefined;
  /**
   * Slug for the currently selected file, derived from the canonical
   * (original) file name. Transforms are a view preference applied after
   * navigation, so transformed files do not get their own slug — the slug
   * for `Counter.tsx` remains the same whether the `js` transform is
   * active or not.
   */
  selectedFileSlug: string | undefined;
  selectedFile: VariantSource | null;
  /** DEFLATE dictionary for the selected file's `hastCompressed` source. */
  selectedFileFallback: FallbackNode[] | undefined;
  selectedFileComponent: React.ReactNode;
  selectedFileLines: number;
  files: Array<{
    name: string;
    slug?: string;
    component: React.ReactNode;
  }>;
  selectFileName: (fileName: string) => void;
  allFilesSlugs: Array<{
    fileName: string;
    slug: string;
    variantName: string;
  }>;
}
/**
 * Hook for managing file selection and navigation within a code variant
 */
export declare function useFileNavigation({
  selectedVariant,
  transformedFiles,
  mainSlug,
  selectedVariantKey,
  variantKeys,
  shouldHighlight,
  preClassName,
  setSource,
  editActivation,
  onActivate,
  effectiveCode,
  selectVariant,
  fileHashMode,
  saveHashVariantToLocalStorage,
  saveVariantToLocalStorage,
  hashVariant,
  sourceEnhancers,
  fallbacks,
  expanded,
  collapseToEmpty,
  expand,
  transforming,
  onPreTransitionReady,
  variantBridgeLineMode,
  swapPartnerVariant,
  selectedFileName: selectedFileNameInternal,
  setSelectedFileName: setSelectedFileNameInternal
}: UseFileNavigationProps): UseFileNavigationResult;
export {};