@primer/react/dist/PageLayout/usePaneWidth.d.ts

An implementation of GitHub's Primer Design System using React

import React from 'react';
type Measurement = `${number}px`;
export type CustomWidthOptions = {
    min: Measurement;
    default: Measurement;
    max: Measurement;
};
export type PaneWidth = 'small' | 'medium' | 'large';
/**
 * Width value for the pane - defines constraints and defaults only.
 * - `PaneWidth`: Preset size ('small' | 'medium' | 'large')
 * - `CustomWidthOptions`: Explicit min/default/max constraints
 */
export type PaneWidthValue = PaneWidth | CustomWidthOptions;
export type UsePaneWidthOptions = {
    width: PaneWidthValue;
    minWidth: number;
    resizable: boolean;
    /** localStorage key for persisting width. When undefined, localStorage is not used. */
    widthStorageKey?: string;
    paneRef: React.RefObject<HTMLDivElement | null>;
    handleRef: React.RefObject<HTMLDivElement | null>;
    contentWrapperRef: React.RefObject<HTMLDivElement | null>;
    /**
     * When true, custom max width values are capped to the viewport-based max.
     * This prevents overflow in non-wrapping flex layouts (e.g., Sidebar).
     * @default false
     */
    constrainToViewport?: boolean;
    /** Callback fired when a resize operation ends (drag release or keyboard key up) */
    onResizeEnd?: (width: number) => void;
    /** Current/controlled width value in pixels (used instead of internal state; default from `width` is still used for reset) */
    currentWidth?: number;
};
export type UsePaneWidthResult = {
    /** Current width for React state (used in ARIA attributes) */
    currentWidth: number;
    /** Mutable ref tracking width during drag operations */
    currentWidthRef: React.MutableRefObject<number>;
    /** Minimum allowed pane width */
    minPaneWidth: number;
    /** Maximum allowed pane width (updates on viewport resize) */
    maxPaneWidth: number;
    /** Calculate current max width constraint */
    getMaxPaneWidth: () => number;
    /** Persist width to localStorage and sync React state */
    saveWidth: (value: number) => void;
    /** Reset to default width */
    getDefaultWidth: () => number;
};
/**
 * Default value for --pane-max-width-diff CSS variable.
 * Imported from CSS to ensure JS fallback matches the CSS default.
 */
export declare const DEFAULT_MAX_WIDTH_DIFF: number;
/**
 * Default value for --sidebar-max-width-diff CSS variable.
 * Unlike --pane-max-width-diff, this is constant across all viewport sizes.
 */
export declare const DEFAULT_SIDEBAR_MAX_WIDTH_DIFF: number;
/**
 * Default max pane width for SSR when viewport is unknown.
 * Updated to actual value in layout effect before paint.
 */
export declare const SSR_DEFAULT_MAX_WIDTH = 600;
/**
 * Pixel increment for keyboard arrow key resizing.
 * @see https://github.com/github/accessibility/issues/5101#issuecomment-1822870655
 */
export declare const ARROW_KEY_STEP = 3;
/** Default widths for preset size options */
export declare const defaultPaneWidth: Record<PaneWidth, number>;
export declare const isCustomWidthOptions: (width: PaneWidthValue) => width is CustomWidthOptions;
export declare const isPaneWidth: (width: PaneWidthValue) => width is PaneWidth;
export declare const getDefaultPaneWidth: (w: PaneWidthValue) => number;
/**
 * Derives the --pane-max-width-diff value from viewport width alone.
 * Avoids the expensive getComputedStyle call that forces a synchronous layout recalc.
 * The CSS only defines two breakpoint-dependent values, so a simple width check is equivalent.
 */
export declare function getMaxWidthDiffFromViewport(): number;
export declare const updateAriaValues: (handle: HTMLElement | null, values: {
    current?: number;
    min?: number;
    max?: number;
}) => void;
/**
 * Manages pane width state with storage persistence and viewport constraints.
 * Handles initialization from storage, clamping on viewport resize, and provides
 * functions to save and reset width.
 *
 * Storage behavior:
 * - When `resizable` is `true` and `onResizeEnd` is not provided: Uses localStorage
 * - When `onResizeEnd` is provided: Calls the callback instead of localStorage
 * - When `resizable` is `false` or `undefined`: Not resizable, no persistence
 */
export declare function usePaneWidth({ width, minWidth, resizable, widthStorageKey, paneRef, handleRef, contentWrapperRef, constrainToViewport, onResizeEnd, currentWidth: controlledWidth, }: UsePaneWidthOptions): UsePaneWidthResult;
export {};
//# sourceMappingURL=usePaneWidth.d.ts.map