Skip to content

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

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

'use client';

/**
 * @file useAnimatedLayout.ts
 * @input React (useMemo), motion/animatedLayout.ts
 * @output Exports `useAnimatedLayout` and the opaque `AnimatedLayout` handle
 *   type
 * @position Public hook over the one size-change module
 *
 * SYNC: When modified, update /packages/core/src/motion/animatedLayout.ts
 */

import {useMemo, type RefObject} from 'react';
import {
  createAnimatedLayout,
  type AnimatedLayout,
} from '../motion/animatedLayout';

export type {AnimatedLayout} from '../motion/animatedLayout';

export interface UseAnimatedLayoutOptions {
  /** The container whose content glides: a scroll container or a panel. */
  containerRef: RefObject<HTMLElement | null>;
}

/**
 * Returns a handle to pass to a component whose size changes, such as
 * TreeList or Collapsible. When that component changes size, it and the
 * content after it inside `containerRef` animate together on one shared
 * motion role. Fixed and stuck sticky elements stay put, the glide never
 * scrolls the area, and Reduce Motion is respected.
 *
 * `containerRef` names the area: an app passes the ref it already gives its
 * scroll container or panel (a ScrollableArea's ref reaches its native scroll
 * viewport). The handle has no public members.
 *
 * @example
 * ```
 * const containerRef = useRef<HTMLDivElement>(null);
 * const animatedLayout = useAnimatedLayout({containerRef});
 * return (
 *   <div ref={containerRef}>
 *     <TreeList items={items} animatedLayout={animatedLayout} />
 *     <p>Notes</p>
 *   </div>
 * );
 * ```
 */
export function useAnimatedLayout({
  containerRef,
}: UseAnimatedLayoutOptions): AnimatedLayout {
  // The container is read when a change runs, so the handle stays stable
  // across renders and a later ref assignment is still seen.
  return useMemo(
    () => createAnimatedLayout(() => containerRef.current),
    [containerRef],
  );
}