Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
10.6 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file resizableModel.ts
 * @input Size values (pixels, `Npx`, `N%`, pixel() and percent()), a basis,
 *   bounds, snap points, and a storage key
 * @output The resize model's pure parts: size parsing and resolution against a
 *   basis, clamping and snapping, persistence, and the content-box measurement
 *   of a percentage basis
 * @position Shared by useResizable and createResizable, so both resolve,
 *   clamp, snap and persist alike; no React, and no DOM work on import
 */

import type {DevWarnings} from '../utils/devWarning';

export type ResizableDirection = 'horizontal' | 'vertical';

export const DEFAULT_MIN = 50;
export const DEFAULT_COLLAPSED_SIZE = 40;
export const STORAGE_PREFIX = 'astryx-resizable:';

export function clampSize(
  size: number,
  min: number,
  max: number,
  snaps: number[],
): number {
  const clamped = Math.min(max, Math.max(min, size));

  // When snap points are defined, always snap to the nearest one.
  // No intermediate positions — the panel can only rest at snap values.
  if (snaps.length > 0) {
    let nearest = snaps[0];
    let nearestDist = Math.abs(clamped - nearest);
    for (let i = 1; i < snaps.length; i++) {
      const dist = Math.abs(clamped - snaps[i]);
      if (dist < nearestDist) {
        nearest = snaps[i];
        nearestDist = dist;
      }
    }
    return Math.min(max, Math.max(min, nearest));
  }

  return clamped;
}

export interface PersistedResizableState {
  /** Expanded size in px, or null when the entry carries no usable size. */
  size: number | null;
  /**
   * Collapse state when the entry was written, or null when the entry
   * predates collapse persistence and says nothing about it.
   */
  isCollapsed: boolean | null;
}

/**
 * Reads a persisted entry. Three formats exist in storage:
 * - `{size, isCollapsed}` — the current format; `size` is the expanded size,
 *   so the pre-collapse width survives a collapsed session
 * - a plain non-zero number — a legacy width-only entry that never recorded
 *   collapse, so `isCollapsed` is null (unknown)
 * - a plain `0` — written by legacy collapse, which restored the region as a
 *   zero-width expanded panel (#4790); read as "collapsed, no saved size"
 */
export function loadPersistedState(
  key: string,
): PersistedResizableState | null {
  if (typeof window === 'undefined') {
    return null;
  }
  try {
    const raw = localStorage.getItem(STORAGE_PREFIX + key);
    if (raw == null) {
      return null;
    }
    const parsed: unknown = JSON.parse(raw);
    if (typeof parsed === 'number') {
      if (!Number.isFinite(parsed)) {
        return null;
      }
      return parsed === 0
        ? {size: null, isCollapsed: true}
        : {size: parsed, isCollapsed: null};
    }
    if (typeof parsed === 'object' && parsed != null) {
      const {size, isCollapsed} = parsed as {
        size?: unknown;
        isCollapsed?: unknown;
      };
      const hasSize =
        typeof size === 'number' && Number.isFinite(size) && size > 0;
      if (hasSize || isCollapsed === true) {
        return {
          size: hasSize ? size : null,
          isCollapsed: isCollapsed === true,
        };
      }
    }
  } catch {
    /* ignore */
  }
  return null;
}

export function persistState(
  key: string,
  state: PersistedResizableState,
): void {
  if (typeof window === 'undefined') {
    return;
  }
  try {
    localStorage.setItem(STORAGE_PREFIX + key, JSON.stringify(state));
  } catch {
    /* ignore */
  }
}

/** The released compatibility basis when there is no window to measure. */
export const SERVER_BASIS = 1200;

export const DEFAULT_SIZE_FALLBACK = 250;
export const RESIZABLE_SIZE_GUIDANCE =
  'Use a non-negative number of pixels, an exact "Npx" string, an exact ' +
  '"N%" string from 0% to 100%, pixel(value), or ' +
  'percent(value, {min: pixel(value)}) / percent(value, {max: pixel(value)}).';

/** Parsed, validated input. */
export type ParsedSize =
  | {kind: 'px'; value: number}
  | {kind: 'percent'; value: number; min?: number; max?: number};

const PX_PATTERN = /^(\d+(?:\.\d+)?)px$/;
const PERCENT_PATTERN = /^(\d+(?:\.\d+)?)%$/;

function parseSizeString(value: string): ParsedSize | null {
  // Preserve the released atomic fast path exactly.
  const px = PX_PATTERN.exec(value);
  if (px) {
    const parsed = Number(px[1]);
    return Number.isFinite(parsed) ? {kind: 'px', value: parsed} : null;
  }
  const percentValue = PERCENT_PATTERN.exec(value);
  if (percentValue) {
    const parsed = Number(percentValue[1]);
    return Number.isFinite(parsed) && parsed <= 100
      ? {kind: 'percent', value: parsed}
      : null;
  }
  return null;
}

function parsePixelSize(value: unknown): number | null {
  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
    return null;
  }
  const candidate = value as {type?: unknown; value?: unknown};
  return candidate.type === 'pixel' &&
    typeof candidate.value === 'number' &&
    Number.isFinite(candidate.value) &&
    candidate.value >= 0
    ? candidate.value
    : null;
}

function parsePercentSize(value: object): ParsedSize | null {
  if (Array.isArray(value)) {
    return null;
  }
  const candidate = value as {
    type?: unknown;
    value?: unknown;
    min?: unknown;
    max?: unknown;
  };
  if (
    candidate.type !== 'percent' ||
    typeof candidate.value !== 'number' ||
    !Number.isFinite(candidate.value) ||
    candidate.value < 0 ||
    candidate.value > 100
  ) {
    return null;
  }

  const hasMin = candidate.min !== undefined;
  const hasMax = candidate.max !== undefined;
  // Exactly one bound is required. The helper's public type enforces this for
  // typed callers; this branch preserves it for JavaScript and `any`.
  if (hasMin === hasMax) {
    return null;
  }
  if (hasMin) {
    const min = parsePixelSize(candidate.min);
    return min == null ? null : {kind: 'percent', value: candidate.value, min};
  }
  const max = parsePixelSize(candidate.max);
  return max == null ? null : {kind: 'percent', value: candidate.value, max};
}

export function parseSize(value: unknown): ParsedSize | null {
  if (typeof value === 'number') {
    return Number.isFinite(value) && value >= 0 ? {kind: 'px', value} : null;
  }
  if (typeof value === 'string') {
    return parseSizeString(value);
  }
  if (typeof value === 'object' && value != null) {
    const pixelValue = parsePixelSize(value);
    return pixelValue == null
      ? parsePercentSize(value)
      : {kind: 'px', value: pixelValue};
  }
  return null;
}

/** Whether this parsed value must be recomputed when its basis changes. */
export function dependsOnBasis(parsed: ParsedSize | null): boolean {
  return parsed?.kind === 'percent';
}

/** Resolve a parsed size against its basis, then apply its one pixel bound. */
export function toPixels(
  parsed: ParsedSize,
  basis: number | null,
): number | null {
  if (parsed.kind === 'px') {
    return parsed.value;
  }
  if (basis == null) {
    return null;
  }
  const percentagePx = Math.round((parsed.value / 100) * basis);
  if (parsed.min !== undefined) {
    return Math.max(percentagePx, parsed.min);
  }
  if (parsed.max !== undefined) {
    return Math.min(percentagePx, parsed.max);
  }
  return percentagePx;
}

function describeUnknown(value: unknown): string {
  if (typeof value === 'number' && !Number.isFinite(value)) {
    return String(value);
  }
  try {
    return JSON.stringify(value) ?? String(value);
  } catch {
    return String(value);
  }
}

function describePixelCandidate(value: unknown): string {
  if (typeof value !== 'object' || value == null || Array.isArray(value)) {
    return describeUnknown(value);
  }
  const candidate = value as {type?: unknown; value?: unknown};
  return candidate.type === 'pixel'
    ? `{"type":"pixel","value":${describeUnknown(candidate.value)}}`
    : describeUnknown(value);
}

function describeSize(value: unknown): string {
  if (typeof value === 'object' && value != null && !Array.isArray(value)) {
    const candidate = value as {
      type?: unknown;
      value?: unknown;
      min?: unknown;
      max?: unknown;
    };
    if (candidate.type === 'pixel') {
      return describePixelCandidate(value);
    }
    if (candidate.type === 'percent') {
      const fields = [
        '"type":"percent"',
        `"value":${describeUnknown(candidate.value)}`,
      ];
      if (candidate.min !== undefined) {
        fields.push(`"min":${describePixelCandidate(candidate.min)}`);
      }
      if (candidate.max !== undefined) {
        fields.push(`"max":${describePixelCandidate(candidate.max)}`);
      }
      return `{${fields.join(',')}}`;
    }
  }
  return describeUnknown(value);
}

/**
 * Resolves one configured value, applying its role's fallback when the input is
 * not accepted. The warning remains development-only through `devWarn`; every
 * build takes the same deterministic fallback.
 */
export function resolveBound(
  raw: unknown,
  parsed: ParsedSize | null,
  basis: number | null,
  fallback: number,
  label: string,
  accepted: string,
  warn: DevWarnings | null,
  source = 'useResizable',
): number {
  if (raw === undefined) {
    return fallback;
  }
  // Preserve the released explicit unbounded maximum. Other roles still
  // reject non-finite numbers.
  if (raw === Infinity && fallback === Infinity) {
    return Infinity;
  }
  if (parsed == null) {
    warn?.(
      source,
      `${label}: ${describeSize(raw)} is not a size. ${accepted} ` +
        `Falling back to ${fallback}.`,
      label,
    );
    return fallback;
  }
  return toPixels(parsed, basis) ?? fallback;
}

/**
 * The container's content-box size on the active axis.
 *
 * Content box, not border box: a bordered or padded container would otherwise
 * report a basis a few pixels larger than the space a percentage is actually a
 * share of, and that error lands in `aria-valuemax`. The observer entry
 * carries `contentBoxSize` natively, which is already writing-mode aware;
 * measuring the element is the fallback for the synthetic entry
 * `observeResize` fires on registration.
 */
export function measureContentBox(
  element: HTMLElement,
  direction: ResizableDirection,
  entry?: ResizeObserverEntry,
): number | null {
  const box = entry?.contentBoxSize?.[0];
  if (box) {
    return direction === 'vertical' ? box.blockSize : box.inlineSize;
  }
  const style =
    typeof window === 'undefined' ? null : window.getComputedStyle(element);
  if (style == null) {
    return null;
  }
  const size =
    direction === 'vertical'
      ? element.clientHeight -
        parseFloat(style.paddingTop) -
        parseFloat(style.paddingBottom)
      : element.clientWidth -
        parseFloat(style.paddingLeft) -
        parseFloat(style.paddingRight);
  return Number.isFinite(size) ? size : null;
}