@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/Resizable/createResizable.ts

@@ -0,0 +1,1046 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file createResizable.ts
+ * @input A handle element, or null for a region with no handle yet, and the
+ *   region's options
+ * @output createResizable; readInitialResizableState for the hook's first
+ *   render; createResizableAs and the internal channel for the hooks
+ * @position The Resizable family's factory, internal to the package. Its
+ *   input is resizeGesture.ts: it listens with it on a plain handle, and
+ *   ResizeHandle drives the region through its model. The
+ *   configuration-object useResizable builds on it. No DOM work on import
+ */
+
+import {registerEnglishFallback} from '../i18n/englishFallback';
+import english from '../i18n/generated-english/Resizable/createResizable.generated';
+import {observeResize} from '../utils/sharedResizeObserver';
+import {devWarn} from '../utils/devWarning';
+import type {SizeValue} from '../utils/types';
+import {
+  DEFAULT_COLLAPSED_SIZE,
+  DEFAULT_MIN,
+  DEFAULT_SIZE_FALLBACK,
+  RESIZABLE_SIZE_GUIDANCE,
+  SERVER_BASIS,
+  clampSize,
+  dependsOnBasis,
+  loadPersistedState,
+  measureContentBox,
+  parseSize,
+  persistState,
+  resolveBound,
+  type PersistedResizableState,
+  type ResizableDirection,
+} from './resizableModel';
+import {
+  createResizeGesture,
+  type ResizeGesture,
+  type ResizeGestureModel,
+  type ResizeGestureState,
+} from './resizeGesture';
+import {separatorAttributes} from './separatorAttributes';
+import type {ResizableSize} from './utils';
+
+// The English for the two messages it names, and nothing more of the catalog.
+registerEnglishFallback(english);
+
+/**
+ * The catalog's messages for a plain handle: its name and what it announces
+ * while collapsed, when the options give neither `label` nor
+ * `collapsedLabel`. The factory uses the shipped English messages.
+ */
+const LABEL_KEY = '@astryx.resizable.handle.label';
+const COLLAPSED_LABEL_KEY = '@astryx.resizable.collapsed';
+
+export interface CreateResizableOptions {
+  /**
+   * Initial size. A number or an exact `Npx` is pixels, and an exact `N%` is
+   * a share of the basis. `percent(value, {min | max: pixel(value)})` adds one
+   * pixel floor or ceiling. A value that depends on the basis resolves once
+   * into pixels. @default 250
+   */
+  defaultSize?: ResizableSize | SizeValue;
+  /** The minimum size, in the same forms. @default 50 */
+  minSize?: ResizableSize;
+  /** The maximum size, in the same forms. Unbounded when omitted. */
+  maxSize?: ResizableSize;
+  /** Pixel values the region rests on; it can rest only on one of them. */
+  snaps?: number[];
+  /** Whether the region can collapse to 0. @default false */
+  collapsible?: boolean;
+  /** Size in px under which a drag collapses the region. @default 40 */
+  collapsedSize?: number;
+  /**
+   * The element a percentage is a share of, read as `containerRef.current`.
+   * Omitted, percentages are a share of the viewport. A plain `{current}`
+   * object serves outside React.
+   */
+  containerRef?: {readonly current: HTMLElement | null};
+  /** The axis the region resizes along. @default 'horizontal' */
+  direction?: ResizableDirection;
+  /** Key under which the size and collapse state persist in localStorage. */
+  autoSaveId?: string;
+  /** Initial collapse state; a persisted entry wins over it. */
+  defaultIsCollapsed?: boolean;
+  /**
+   * Controlled collapse state. When set, the caller owns collapse. A collapse
+   * or expand request reports through `onCollapseChange`. Nothing changes
+   * until the caller passes the new value through `update`.
+   */
+  isCollapsed?: boolean;
+  /** Called when an interaction changes the size. */
+  onSizeChange?: (size: number) => void;
+  /** Called when an interaction collapses or expands the region. */
+  onCollapseChange?: (isCollapsed: boolean) => void;
+  /**
+   * The handle sits before the panel it resizes (the panel is at the end), so
+   * a drag toward the start grows it.
+   * @default false
+   */
+  isReversed?: boolean;
+  /**
+   * Ignores pointer and keyboard input and says so; a plain element keeps its
+   * tab stop.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * A plain element's accessible name, when it has none of its own. Without
+   * it, the factory uses the message catalog's English message.
+   * @default 'Resize handle'
+   */
+  label?: string;
+  /**
+   * Replaces the catalog's "Collapsed" that the handle announces as its
+   * `aria-valuetext` while the region is collapsed. Absent, the factory
+   * announces the shipped English message.
+   * @default 'Collapsed'
+   */
+  collapsedLabel?: string;
+}
+
+export interface ResizableController {
+  /** The region's size in px, 0 while collapsed. */
+  readonly size: number;
+  readonly isCollapsed: boolean;
+  /** Collapses the region, when it is collapsible. */
+  collapse(): void;
+  /** Expands the region to the size it had before it collapsed. */
+  expand(): void;
+  /** Resizes the region to `size` px, within its bounds. */
+  resize(size: number): void;
+  /**
+   * Takes the full set of options, as a new render does: an option left out
+   * returns to its default. The region keeps its size and collapse state,
+   * within the new options.
+   */
+  update(options: CreateResizableOptions): void;
+  /**
+   * Calls `listener` after every change to `size` or `isCollapsed`, a
+   * correction a newly measured basis makes included. Returns the function
+   * that stops it.
+   */
+  subscribe(listener: () => void): () => void;
+  /**
+   * Removes every listener, observer and attribute the factory added and the
+   * body's drag cursor; a drag in flight ends as cancelled.
+   */
+  destroy(): void;
+}
+
+/** The viewport width, the basis without a container. */
+function readViewportBasis(): number {
+  return typeof window === 'undefined' ? SERVER_BASIS : window.innerWidth;
+}
+
+/** The window's extent along the axis, for an unbounded region's maximum. */
+function readWindowExtent(direction: ResizableDirection): number | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  return direction === 'vertical' ? window.innerHeight : window.innerWidth;
+}
+
+/** Starts as warned: the factory warns, and this first-render read does not. */
+const QUIET = {current: true};
+
+/**
+ * The state a region with `options` starts in, before its handle exists: the
+ * server's render and a hook's first render. A container is not measured
+ * yet, so a percentage of it resolves against the deterministic 1200px basis
+ * until the factory measures it. `'server'` reads the state the server
+ * rendered, for a render that hydrates it: the 1200px basis for a viewport
+ * percentage too, and nothing saved.
+ */
+export function readInitialResizableState(
+  options: CreateResizableOptions = {},
+  environment: 'client' | 'server' = 'client',
+): ResizableSnapshot {
+  const {
+    defaultSize,
+    minSize,
+    maxSize,
+    containerRef,
+    collapsible = false,
+    snaps = [],
+    autoSaveId,
+    defaultIsCollapsed,
+    isCollapsed: controlled,
+  } = options;
+  const isServer = environment === 'server';
+  const persisted =
+    autoSaveId && !isServer ? loadPersistedState(autoSaveId) : null;
+  const parsedDefault = parseSize(defaultSize);
+  const parsedMin = parseSize(minSize);
+  const parsedMax = parseSize(maxSize);
+  const hasContainer = containerRef != null;
+  const needsContainer =
+    hasContainer &&
+    (dependsOnBasis(parsedMin) ||
+      dependsOnBasis(parsedMax) ||
+      (persisted?.size == null && dependsOnBasis(parsedDefault)));
+  const basis = hasContainer || isServer ? SERVER_BASIS : readViewportBasis();
+  const min = resolveBound(
+    minSize,
+    parsedMin,
+    basis,
+    DEFAULT_MIN,
+    'minSize',
+    RESIZABLE_SIZE_GUIDANCE,
+    QUIET,
+  );
+  const max = resolveBound(
+    maxSize,
+    parsedMax,
+    basis,
+    Infinity,
+    'maxSize',
+    RESIZABLE_SIZE_GUIDANCE,
+    QUIET,
+  );
+  const defaultPx = resolveBound(
+    defaultSize,
+    parsedDefault,
+    basis,
+    DEFAULT_SIZE_FALLBACK,
+    'defaultSize',
+    RESIZABLE_SIZE_GUIDANCE,
+    QUIET,
+  );
+  const chosen =
+    persisted?.size ??
+    (needsContainer ? null : clampSize(defaultPx, min, max, snaps));
+  const size = clampSize(chosen ?? defaultPx, min, max, snaps);
+  const isCollapsed =
+    collapsible &&
+    (controlled !== undefined
+      ? controlled
+      : (persisted?.isCollapsed ?? defaultIsCollapsed ?? false));
+  // A container is not measured yet; without one the window's extent stands
+  // in for a missing maximum, as the factory reports it.
+  const windowExtent =
+    hasContainer || isServer
+      ? null
+      : readWindowExtent(options.direction ?? 'horizontal');
+  return {
+    size: isCollapsed ? 0 : size,
+    isCollapsed,
+    expandedSize: size,
+    minPx: min,
+    maxPx: max,
+    effectiveMaxPx:
+      max !== Infinity
+        ? max
+        : windowExtent == null
+          ? undefined
+          : Math.max(windowExtent, isCollapsed ? min : size),
+  };
+}
+
+/**
+ * What a React form of the region renders. A change to any part replaces it
+ * as a whole. It holds the size (0 while collapsed), the collapse state, the
+ * size as expanded, and the bounds the handle announces.
+ */
+export interface ResizableSnapshot {
+  readonly size: number;
+  readonly isCollapsed: boolean;
+  readonly expandedSize: number;
+  readonly minPx: number;
+  readonly maxPx: number;
+  /** The maximum the handle reports: a configured one, or a measured extent. */
+  readonly effectiveMaxPx: number | undefined;
+}
+
+/**
+ * The package's own channel into a factory, for useResizable: kept off the
+ * exported ResizableController, so it adds no public member.
+ */
+interface ResizableInternals {
+  snapshot(): ResizableSnapshot;
+  /** Calls `listener` after every change to the snapshot. */
+  subscribeSnapshot(listener: () => void): () => void;
+  /**
+   * Follows the element behind `containerRef` when it has changed without
+   * new options, as a React caller's commit may have swapped it.
+   */
+  syncContainer(): void;
+  /**
+   * Lets go of the page and keeps the region. A gesture in flight ends as
+   * cancelled, and the handle's listeners, its attributes and the observers
+   * go. Collapse, expand and resize still apply and report. For a React caller
+   * whose component unmounts or an `<Activity>` hides.
+   */
+  suspend(): void;
+  /** Takes the page back after `suspend`: the handle, and the observers. */
+  resume(): void;
+  /**
+   * The region's side of a gesture the factory does not own: the drag and
+   * keys of a ResizeHandle given the configuration object's props.
+   */
+  model: ResizeGestureModel;
+}
+
+const internals = new WeakMap<ResizableController, ResizableInternals>();
+
+/** The factory's internal channel, or undefined for anything else. */
+export function readResizableInternals(
+  controller: ResizableController,
+): ResizableInternals | undefined {
+  return internals.get(controller);
+}
+
+/** An attribute's value as the DOM takes it; undefined removes it. */
+function toAttribute(
+  value: string | number | boolean | undefined,
+): string | null {
+  return value == null ? null : String(value);
+}
+
+/** The attributes the factory writes on a handle, restored by `destroy`. */
+const MANAGED_ATTRIBUTES = [
+  'role',
+  'tabindex',
+  'aria-label',
+  'aria-orientation',
+  'aria-valuenow',
+  'aria-valuemin',
+  'aria-valuemax',
+  'aria-valuetext',
+  'aria-disabled',
+  'data-resizing',
+] as const;
+
+/**
+ * Make `handle` a window splitter that resizes a region. The factory never
+ * sizes the panel: it reports the size, and the caller applies it.
+ *
+ * It gives the handle `role="separator"`, its orientation and its value. It
+ * adds a tab stop and an accessible name when the handle has none. It answers
+ * a pointer drag, the arrow keys, Home and End, and holds the pointer for a
+ * whole drag. Enter and a double-click collapse and restore. A horizontal
+ * region resizes along the inline axis, and under right-to-left the drag
+ * follows the pointer. `destroy` takes all of it away. With a null handle the
+ * region still answers collapse, expand, resize and subscribe, and touches no
+ * element. Outside a provider, its name and its collapsed text are the
+ * shipped English messages. `label` names it, and `collapsedLabel` replaces
+ * its collapsed text in another language.
+ *
+ * @example
+ * ```
+ * const sidebar = document.querySelector('#sidebar');
+ * const resizable = createResizable(document.querySelector('#divider'), {
+ *   defaultSize: 260,
+ *   minSize: 180,
+ *   maxSize: 480,
+ *   collapsible: true,
+ *   autoSaveId: 'sidebar',
+ * });
+ * const paint = () => {
+ *   sidebar.style.width = `${resizable.size}px`;
+ * };
+ * paint();
+ * resizable.subscribe(paint);
+ * ```
+ */
+export function createResizable(
+  handle: HTMLElement | null,
+  options: CreateResizableOptions = {},
+): ResizableController {
+  return createResizableAs('createResizable', handle, options);
+}
+
+/**
+ * Who a factory's development warnings speak for: the bare factory, or the
+ * configuration-object useResizable built on it, whose warnings keep the
+ * hook's name and words.
+ */
+export type ResizableWarningSource = 'createResizable' | 'useResizable';
+
+/**
+ * createResizable, with its development warnings in the words of `source`:
+ * the package's own entry, for useResizable.
+ */
+export function createResizableAs(
+  source: ResizableWarningSource,
+  handle: HTMLElement | null,
+  options: CreateResizableOptions = {},
+): ResizableController {
+  // The configuration-object useResizable keeps its warnings word for word.
+  const isHook = source === 'useResizable';
+  let opts = options;
+  let isDestroyed = false;
+  // Let go of the page by `suspend`, with the region kept.
+  let isSuspended = false;
+  const listeners = new Set<() => void>();
+  const isReversed = (): boolean => opts.isReversed ?? false;
+  const isDisabled = (): boolean => opts.isDisabled ?? false;
+  const didWarn = {
+    min: {current: false},
+    max: {current: false},
+    defaultSize: {current: false},
+    inverted: false,
+  };
+
+  let persistedKey = opts.autoSaveId;
+  let persisted: PersistedResizableState | null = persistedKey
+    ? loadPersistedState(persistedKey)
+    : null;
+
+  // The percentage basis. The container is followed through the shared
+  // observer only while some option needs it; the viewport only while a
+  // percentage bound needs it.
+  let containerElement: HTMLElement | null = null;
+  let observedDirection: ResizableDirection | null = null;
+  let containerBasis: number | null = null;
+  let stopObservingContainer: (() => void) | null = null;
+  let isSubscribing = false;
+  let isObservingViewport = false;
+
+  // One stable basis per gesture: a container that resizes mid-drag would
+  // otherwise move the bound under the pointer.
+  let gestureBasis: number | null = null;
+  let isGestureActive = false;
+  let dragStartSize = 0;
+
+  let initialDefault: {px: number; isFinal: boolean} | null = null;
+  let chosenSize: number | null | undefined;
+  let committedBounds: {min: number; max: number} | null = null;
+  let uncontrolledIsCollapsed =
+    persisted?.isCollapsed ?? opts.defaultIsCollapsed ?? false;
+
+  let derived = {
+    size: 0,
+    isCollapsed: false,
+    min: DEFAULT_MIN,
+    max: Infinity,
+    effectiveMax: undefined as number | undefined,
+    isBasisMeasured: true,
+  };
+  let notified: {size: number; isCollapsed: boolean} | null = null;
+  let written: {key: string; size: number; isCollapsed: boolean} | null = null;
+  let mustWrite = false;
+  let snapshot: ResizableSnapshot | null = null;
+  const snapshotListeners = new Set<() => void>();
+
+  const direction = (): ResizableDirection => opts.direction ?? 'horizontal';
+  const collapsible = (): boolean => opts.collapsible ?? false;
+  const isControlled = (): boolean => opts.isCollapsed !== undefined;
+  const snaps = (): number[] => opts.snaps ?? [];
+
+  const onViewportResize = () => {
+    commit();
+  };
+
+  /** Which bases the options need followed right now. */
+  function observation() {
+    const parsedDefault = parseSize(opts.defaultSize);
+    const boundsDependOnBasis =
+      dependsOnBasis(parseSize(opts.minSize)) ||
+      dependsOnBasis(parseSize(opts.maxSize));
+    const defaultNeedsInitialBasis =
+      persisted?.size == null &&
+      dependsOnBasis(parsedDefault) &&
+      initialDefault?.isFinal !== true;
+    const hasContainer = opts.containerRef != null;
+    return {
+      hasContainer,
+      container:
+        hasContainer && (boundsDependOnBasis || defaultNeedsInitialBasis),
+      viewport: !hasContainer && boundsDependOnBasis,
+    };
+  }
+
+  /** Follow the bases `observation()` names, and nothing else. */
+  function syncObservation(): void {
+    const needs = observation();
+    const element = needs.container
+      ? (opts.containerRef?.current ?? null)
+      : null;
+    if (element !== containerElement || observedDirection !== direction()) {
+      stopObservingContainer?.();
+      stopObservingContainer = null;
+      containerElement = element;
+      containerBasis = null;
+      observedDirection = direction();
+      if (element != null) {
+        // The observer measures once as it registers; that measurement is
+        // read by the computation this call is part of.
+        isSubscribing = true;
+        const observed = element;
+        stopObservingContainer = observeResize(observed, entry => {
+          containerBasis = measureContentBox(observed, direction(), entry);
+          if (!isSubscribing) {
+            commit();
+          }
+        });
+        isSubscribing = false;
+      }
+    }
+    const watchViewport = needs.viewport && typeof window !== 'undefined';
+    if (watchViewport && !isObservingViewport) {
+      window.addEventListener('resize', onViewportResize);
+      isObservingViewport = true;
+    } else if (!watchViewport && isObservingViewport) {
+      window.removeEventListener('resize', onViewportResize);
+      isObservingViewport = false;
+    }
+  }
+
+  /** The region's state from its options, its basis and its selection. */
+  function compute(): void {
+    const needs = observation();
+    const hasPositiveMeasurement = containerBasis != null && containerBasis > 0;
+    // Before a supplied container is measured, the deterministic 1200px
+    // stands in. It also stands in while the container measures 0, as a
+    // hidden or detached one does. The first real measurement replaces it.
+    const liveBasis = needs.hasContainer
+      ? hasPositiveMeasurement
+        ? (containerBasis as number)
+        : SERVER_BASIS
+      : readViewportBasis();
+    const isBasisMeasured = needs.container ? hasPositiveMeasurement : true;
+    const basis = gestureBasis ?? liveBasis;
+
+    const min = resolveBound(
+      opts.minSize,
+      parseSize(opts.minSize),
+      basis,
+      DEFAULT_MIN,
+      'minSize',
+      RESIZABLE_SIZE_GUIDANCE,
+      didWarn.min,
+      source,
+    );
+    const max = resolveBound(
+      opts.maxSize,
+      parseSize(opts.maxSize),
+      basis,
+      Infinity,
+      'maxSize',
+      RESIZABLE_SIZE_GUIDANCE,
+      didWarn.max,
+      source,
+    );
+    // A basis-dependent default resolves ONCE into a pixel size; it is final
+    // once its basis is real.
+    if (initialDefault == null || !initialDefault.isFinal) {
+      initialDefault = {
+        px: resolveBound(
+          opts.defaultSize,
+          parseSize(opts.defaultSize),
+          basis,
+          DEFAULT_SIZE_FALLBACK,
+          'defaultSize',
+          RESIZABLE_SIZE_GUIDANCE,
+          didWarn.defaultSize,
+          source,
+        ),
+        isFinal: isBasisMeasured,
+      };
+    }
+    const defaultPx = initialDefault.px;
+    if (chosenSize === undefined) {
+      chosenSize =
+        persisted?.size ??
+        (isBasisMeasured ? clampSize(defaultPx, min, max, snaps()) : null);
+    }
+    if (isBasisMeasured && chosenSize == null) {
+      // The container is measured now: the selection the temporary basis
+      // stood in for is made against the real one. Not an interaction, so it
+      // reports nothing through onSizeChange.
+      chosenSize = clampSize(defaultPx, min, max, snaps());
+    }
+    // A re-resolved bound clamps the SELECTION, once the basis is final and
+    // no gesture holds it.
+    if (
+      isBasisMeasured &&
+      gestureBasis == null &&
+      (committedBounds == null ||
+        committedBounds.min !== min ||
+        committedBounds.max !== max)
+    ) {
+      committedBounds = {min, max};
+      if (chosenSize != null) {
+        chosenSize = clampSize(chosenSize, min, max, snaps());
+      }
+    }
+    const size = clampSize(chosenSize ?? defaultPx, min, max, snaps());
+    const isCollapsed =
+      collapsible() &&
+      (isControlled() ? Boolean(opts.isCollapsed) : uncontrolledIsCollapsed);
+
+    if (min > max && !didWarn.inverted) {
+      didWarn.inverted = true;
+      devWarn(
+        source,
+        `the resolved minimum (${min}px) is above the resolved maximum ` +
+          `(${max}px). The maximum wins${isHook ? ', as it always has' : ''}.`,
+      );
+    }
+
+    // The maximum the handle REPORTS: a configured maximum, or a measured
+    // extent standing in for it, never below what the handle announces.
+    const measuredForMax = needs.hasContainer
+      ? hasPositiveMeasurement && needs.container
+        ? containerBasis
+        : null
+      : readWindowExtent(direction());
+    const effectiveMax =
+      max !== Infinity
+        ? max
+        : measuredForMax == null
+          ? undefined
+          : Math.max(measuredForMax, isCollapsed ? min : size);
+
+    derived = {size, isCollapsed, min, max, effectiveMax, isBasisMeasured};
+  }
+
+  /** Recompute, then bring the observers, the handle, storage and subscribers along. */
+  function commit(): void {
+    if (isDestroyed) {
+      return;
+    }
+    if (isSuspended) {
+      // No observers and no handle: the last measured basis stands.
+      compute();
+    } else {
+      // The observation a computation needs can change with it (a default
+      // made final stops following its container): settle both.
+      for (let pass = 0; pass < 3; pass++) {
+        const before = observation();
+        syncObservation();
+        compute();
+        const after = observation();
+        if (
+          before.container === after.container &&
+          before.viewport === after.viewport
+        ) {
+          break;
+        }
+      }
+    }
+    if (handle != null && !isSuspended) {
+      announce();
+    }
+    persist();
+    const reported = {
+      size: derived.isCollapsed ? 0 : derived.size,
+      isCollapsed: derived.isCollapsed,
+    };
+    const next: ResizableSnapshot = {
+      size: reported.size,
+      isCollapsed: reported.isCollapsed,
+      expandedSize: derived.size,
+      minPx: derived.min,
+      maxPx: derived.max,
+      effectiveMaxPx: derived.effectiveMax,
+    };
+    const isSnapshotChanged =
+      snapshot == null ||
+      (Object.keys(next) as (keyof ResizableSnapshot)[]).some(
+        key => snapshot?.[key] !== next[key],
+      );
+    if (isSnapshotChanged) {
+      snapshot = next;
+    }
+    if (
+      notified == null ||
+      notified.size !== reported.size ||
+      notified.isCollapsed !== reported.isCollapsed
+    ) {
+      const isFirst = notified == null;
+      notified = reported;
+      if (!isFirst) {
+        for (const listener of [...listeners]) {
+          listener();
+        }
+      }
+    }
+    if (isSnapshotChanged) {
+      for (const listener of [...snapshotListeners]) {
+        listener();
+      }
+    }
+  }
+
+  /** Nothing is written while the basis stands in, nor while a gesture runs. */
+  function persist(): void {
+    const key = opts.autoSaveId;
+    if (key == null || key === '' || !derived.isBasisMeasured) {
+      return;
+    }
+    if (isGestureActive) {
+      return;
+    }
+    const next = {key, size: derived.size, isCollapsed: derived.isCollapsed};
+    if (
+      mustWrite ||
+      written == null ||
+      written.key !== next.key ||
+      written.size !== next.size ||
+      written.isCollapsed !== next.isCollapsed
+    ) {
+      mustWrite = false;
+      written = next;
+      persistState(key, {size: next.size, isCollapsed: next.isCollapsed});
+    }
+  }
+
+  const original = new Map<string, string | null>();
+  if (handle != null) {
+    for (const name of MANAGED_ATTRIBUTES) {
+      original.set(name, handle.getAttribute(name));
+    }
+  }
+  const hasOwnName =
+    handle != null &&
+    (handle.hasAttribute('aria-label') ||
+      handle.hasAttribute('aria-labelledby'));
+
+  const setAttribute = (name: string, value: string | null) => {
+    if (handle == null) {
+      return;
+    }
+    if (value == null) {
+      handle.removeAttribute(name);
+    } else if (handle.getAttribute(name) !== value) {
+      handle.setAttribute(name, value);
+    }
+  };
+
+  function announce(): void {
+    if (original.get('role') == null) {
+      setAttribute('role', 'separator');
+    }
+    if (!hasOwnName) {
+      setAttribute('aria-label', opts.label ?? english[LABEL_KEY]);
+    }
+    const {size, isCollapsed, min, effectiveMax} = derived;
+    // The attributes ResizeHandle renders, from the same derivation.
+    const aria = separatorAttributes({
+      direction: direction(),
+      isDisabled: isDisabled(),
+      value: {
+        size: isCollapsed ? 0 : size,
+        minPx: min,
+        maxPx: effectiveMax,
+        isCollapsed,
+        collapsedText: opts.collapsedLabel ?? english[COLLAPSED_LABEL_KEY],
+      },
+    });
+    if (original.get('tabindex') == null) {
+      setAttribute('tabindex', String(aria.tabIndex));
+    }
+    setAttribute('aria-orientation', aria['aria-orientation']);
+    setAttribute('aria-valuenow', toAttribute(aria['aria-valuenow']));
+    setAttribute('aria-valuemin', toAttribute(aria['aria-valuemin']));
+    setAttribute('aria-valuemax', toAttribute(aria['aria-valuemax']));
+    setAttribute('aria-valuetext', toAttribute(aria['aria-valuetext']));
+    setAttribute('aria-disabled', toAttribute(aria['aria-disabled']));
+  }
+
+  const setCollapsed = (value: boolean) => {
+    if (!isControlled()) {
+      uncontrolledIsCollapsed = value;
+    }
+  };
+
+  function collapse(): void {
+    if (isDestroyed || !collapsible() || derived.isCollapsed) {
+      return;
+    }
+    setCollapsed(true);
+    commit();
+    opts.onCollapseChange?.(true);
+    opts.onSizeChange?.(0);
+  }
+
+  function expand(): void {
+    if (isDestroyed) {
+      return;
+    }
+    const wasCollapsed = derived.isCollapsed;
+    setCollapsed(false);
+    commit();
+    if (wasCollapsed) {
+      opts.onCollapseChange?.(false);
+    }
+    opts.onSizeChange?.(derived.size);
+  }
+
+  function resize(next: number): void {
+    if (isDestroyed) {
+      return;
+    }
+    // An invalid size repairs nothing: it must not replace a legal selection
+    // with NaN, which would reach storage and aria-valuenow.
+    if (!Number.isFinite(next) || next < 0) {
+      devWarn(
+        source,
+        `resize(${String(next)}) is not a pixel size. Keeping the current ` +
+          `size. Percentages configure the ${isHook ? 'hook' : 'region'}; ` +
+          'they are not a programmatic input.',
+      );
+      return;
+    }
+    const clamped = clampSize(next, derived.min, derived.max, snaps());
+    const wasCollapsed = derived.isCollapsed;
+    chosenSize = clamped;
+    setCollapsed(false);
+    commit();
+    // Resizing out of the collapsed state is an implicit expand.
+    if (wasCollapsed) {
+      opts.onCollapseChange?.(false);
+    }
+    opts.onSizeChange?.(clamped);
+  }
+
+  const model: ResizeGestureModel = {
+    state(): ResizeGestureState {
+      return {
+        size: derived.isCollapsed ? 0 : derived.size,
+        isCollapsed: derived.isCollapsed,
+        minPx: derived.min,
+        maxPx: derived.max,
+        snaps: snaps(),
+        collapsedSize: opts.collapsedSize ?? DEFAULT_COLLAPSED_SIZE,
+        collapsible: collapsible(),
+      };
+    },
+    start() {
+      // The basis holds still for the whole gesture.
+      gestureBasis = readLiveBasis();
+      isGestureActive = true;
+      dragStartSize = derived.isCollapsed ? 0 : derived.size;
+    },
+    move(delta) {
+      const raw = dragStartSize + delta;
+      const collapsedSize = opts.collapsedSize ?? DEFAULT_COLLAPSED_SIZE;
+      if (collapsible() && raw < collapsedSize) {
+        if (!derived.isCollapsed) {
+          setCollapsed(true);
+          commit();
+          opts.onCollapseChange?.(true);
+          opts.onSizeChange?.(0);
+        }
+        return;
+      }
+      const reopens = derived.isCollapsed && raw >= collapsedSize;
+      if (reopens) {
+        setCollapsed(false);
+      }
+      const clamped = clampSize(raw, derived.min, derived.max, snaps());
+      chosenSize = clamped;
+      commit();
+      if (reopens) {
+        opts.onCollapseChange?.(false);
+      }
+      opts.onSizeChange?.(clamped);
+    },
+    end() {
+      endGesture();
+    },
+    // A cancelled gesture is still over: the basis it held comes back, and
+    // the size it reached is saved once, like a completed one.
+    cancel() {
+      endGesture();
+    },
+    collapse,
+    expand,
+  };
+
+  function readLiveBasis(): number {
+    const needs = observation();
+    if (!needs.hasContainer) {
+      return readViewportBasis();
+    }
+    return containerBasis != null && containerBasis > 0
+      ? containerBasis
+      : SERVER_BASIS;
+  }
+
+  function endGesture(): void {
+    if (!isGestureActive) {
+      return;
+    }
+    gestureBasis = null;
+    isGestureActive = false;
+    mustWrite = true;
+    commit();
+  }
+
+  const gesture: ResizeGesture = createResizeGesture(
+    () => handle,
+    model,
+    () => ({
+      direction: direction(),
+      isReversed: isReversed(),
+      isDisabled: isDisabled(),
+    }),
+    dragging => {
+      setAttribute('data-resizing', dragging ? '' : null);
+    },
+  );
+
+  const onPointerDown = (event: PointerEvent) => {
+    gesture.pointerDown(event);
+  };
+  const onPointerMove = (event: PointerEvent) => {
+    gesture.pointerMove(event);
+  };
+  const onPointerUp = (event: PointerEvent) => {
+    gesture.pointerUp(event);
+  };
+  const onPointerCancel = (event: PointerEvent) => {
+    gesture.pointerCancel(event);
+  };
+  const onKeyDown = (event: KeyboardEvent) => {
+    gesture.keyDown(event);
+  };
+  const onDoubleClick = () => {
+    gesture.doubleClick();
+  };
+  function bindHandle(): void {
+    handle?.addEventListener('pointerdown', onPointerDown);
+    handle?.addEventListener('pointermove', onPointerMove);
+    handle?.addEventListener('pointerup', onPointerUp);
+    handle?.addEventListener('pointercancel', onPointerCancel);
+    handle?.addEventListener('lostpointercapture', onPointerCancel);
+    handle?.addEventListener('keydown', onKeyDown);
+    handle?.addEventListener('dblclick', onDoubleClick);
+  }
+
+  /**
+   * The handle's listeners and the observers go, and the handle gets its own
+   * attributes back; a gesture in flight has ended first.
+   */
+  function letGoOfPage(): void {
+    handle?.removeEventListener('pointerdown', onPointerDown);
+    handle?.removeEventListener('pointermove', onPointerMove);
+    handle?.removeEventListener('pointerup', onPointerUp);
+    handle?.removeEventListener('pointercancel', onPointerCancel);
+    handle?.removeEventListener('lostpointercapture', onPointerCancel);
+    handle?.removeEventListener('keydown', onKeyDown);
+    handle?.removeEventListener('dblclick', onDoubleClick);
+    stopObservingContainer?.();
+    stopObservingContainer = null;
+    containerElement = null;
+    if (isObservingViewport) {
+      window.removeEventListener('resize', onViewportResize);
+      isObservingViewport = false;
+    }
+    for (const [name, value] of original) {
+      setAttribute(name, value);
+    }
+  }
+
+  bindHandle();
+  commit();
+
+  const controller: ResizableController = {
+    get size() {
+      return derived.isCollapsed ? 0 : derived.size;
+    },
+    get isCollapsed() {
+      return derived.isCollapsed;
+    },
+    collapse,
+    expand,
+    resize,
+    update(next) {
+      if (isDestroyed) {
+        return;
+      }
+      opts = next;
+      if (opts.autoSaveId !== persistedKey) {
+        persistedKey = opts.autoSaveId;
+        persisted = persistedKey ? loadPersistedState(persistedKey) : null;
+      }
+      commit();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      if (isDestroyed) {
+        return;
+      }
+      // A drag in flight ends first, as cancelled, so the size it reached is
+      // saved and the pointer and the body's cursor are released.
+      gesture.interrupt();
+      // A gesture a ResizeHandle drove through the region's model, rather
+      // than the factory's own, ends the same way.
+      endGesture();
+      isDestroyed = true;
+      if (!isSuspended) {
+        letGoOfPage();
+      }
+      listeners.clear();
+      snapshotListeners.clear();
+    },
+  };
+  internals.set(controller, {
+    snapshot: () => snapshot as ResizableSnapshot,
+    subscribeSnapshot(listener) {
+      snapshotListeners.add(listener);
+      return () => {
+        snapshotListeners.delete(listener);
+      };
+    },
+    model,
+    suspend() {
+      if (isDestroyed || isSuspended) {
+        return;
+      }
+      gesture.interrupt();
+      endGesture();
+      isSuspended = true;
+      letGoOfPage();
+    },
+    resume() {
+      if (isDestroyed || !isSuspended) {
+        return;
+      }
+      isSuspended = false;
+      bindHandle();
+      commit();
+    },
+    syncContainer() {
+      if (isDestroyed || isSuspended) {
+        return;
+      }
+      const element = observation().container
+        ? (opts.containerRef?.current ?? null)
+        : null;
+      if (element !== containerElement) {
+        commit();
+      }
+    },
+  });
+  return controller;
+}