@mui/internal-docs-infra/useCodeWindow/useCodeWindow.d.mts

MUI Infra - internal documentation creation tools.

import * as React from 'react';
export type UseCodeWindowOptions = {
  /**
   * Duration of the expand transition in ms. Should match the CSS
   * transition on the collapsible container. Used to size the
   * page-scroll compensation window.
   * @default 350
   */
  expandDuration?: number;
  /**
   * Duration of the collapse transition in ms. Should match the CSS
   * transition on the collapsible container.
   * @default 350
   */
  collapseDuration?: number;
  /**
   * Duration of the smooth scroll-back animation that returns the
   * `<code>` element's `scrollLeft` to `0` on collapse. Set to `0`
   * to disable. Honors `prefers-reduced-motion`.
   * @default 300
   */
  scrollBackDuration?: number;
  /**
   * CSS selector(s) used to find the anchor element inside the
   * container. The first match wins. Falls back to the toggle ref
   * when no match exists, or when the match is offscreen on collapse.
   * @default '[data-frame-type="highlighted"], [data-frame-type="focus"]'
   */
  anchorSelector?: string;
  /**
   * CSS selector that, when present inside the `<pre>`, opts the
   * expand transition into the scrollbar-gutter animation. Useful
   * when expansion can reveal previously hidden long lines and the
   * horizontal scrollbar would otherwise appear with a snap.
   * @default '[data-collapsible]'
   */
  collapsibleProbeSelector?: string;
};
export type UseCodeWindowResult<ToggleElement extends HTMLElement = HTMLElement, ScrollElement extends HTMLElement = HTMLElement> = {
  /**
   * Ref to attach to the collapsible container element.
   */
  containerRef: React.RefObject<HTMLDivElement | null>;
  /**
   * Optional ref to attach to a scrollable ancestor that should be
   * compensated instead of the page. Attach it when the code block is
   * rendered as a fixed-height "window" (its own `overflow: auto` region)
   * so the anchor stays put against the panel's own scroll rather than the
   * page. When left unattached, the page is compensated — the right default
   * for code that grows the document flow. Forwarded from `useScrollAnchor`.
   *
   * When attached, this element is also treated as the horizontal scroll
   * owner: the scrollbar-gutter swap (`data-scrollbar-gutter`) and the
   * collapse scroll-back run on it instead of the inner `<pre>`. Use this when
   * the window owns both scroll axes so the horizontal scrollbar sits at the
   * window's edge (in view) rather than at the bottom of the inner `<pre>`,
   * which can extend past the window's height and scroll out of view. Your
   * gutter CSS must then key off this element's attribute.
   */
  scrollContainerRef: React.RefObject<ScrollElement | null>;
  /**
   * Ref to attach to the toggle element. Used as a fallback anchor
   * when the primary anchor is offscreen on collapse.
   */
  toggleRef: React.RefObject<ToggleElement | null>;
  /**
   * Call **just before** flipping the expanded/collapsed state. The
   * page will scroll so the anchor element stays put while the
   * container animates.
   */
  anchorScroll: (direction: 'collapse' | 'expand') => void;
};
/**
 * Layered helper that combines `useScrollAnchor` with the additional
 * choreography needed when expanding/collapsing a syntax-highlighted code
 * block.
 *
 * On top of the page-scroll compensation provided by `useScrollAnchor`, it:
 *
 * - Selects an anchor inside the container (highlighted or focus frame),
 *   falling back to the toggle when the primary anchor is offscreen on
 *   collapse.
 * - Drives a `data-scrollbar-gutter` attribute on the inner `<pre>` so the
 *   consumer's CSS can swap between a real horizontal scrollbar and
 *   equivalent `padding-bottom` without a snap.
 * - Smoothly returns the `<code>` element's `scrollLeft` to `0` on
 *   collapse via a compositor-driven transform, so the focused region
 *   (which usually starts at column 0) is back in view after collapse.
 *
 * The hook expects a structure like:
 *
 * ```jsx
 * <div ref={containerRef}>
 *   <pre>
 *     <code>...</code>
 *   </pre>
 *   <button ref={toggleRef}>Expand</button>
 * </div>
 * ```
 *
 * Anchor selection and the collapsible probe are configurable so it works
 * with any highlighter that marks frames with data attributes.
 */
export declare function useCodeWindow<ToggleElement extends HTMLElement = HTMLElement, ScrollElement extends HTMLElement = HTMLElement>(options?: UseCodeWindowOptions): UseCodeWindowResult<ToggleElement, ScrollElement>;