@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/motion/animatedLayout.ts

@@ -8,11 +8,10 @@
  * @output Exports `createAnimatedLayout` and the opaque `AnimatedLayout`
  *   handle, `reportLayoutChange`, `playLayoutChange`, `holdLayoutExit` /
  *   `releaseLayoutExit`, the in-place swap (`holdLayoutSwap` /
- *   `playLayoutSwap`), `playLayoutFrames` and `applyLayoutChangeTransition`:
- *   the one module
- *   that produces the
- *   size-change glide `spec:AST-105` defines
- *   (`architecture:react-component-runtime` INV12)
+ *   `playLayoutSwap`), the edge reveal's two-state form (`holdLayoutEdge` /
+ *   `playLayoutEdge`), `playLayoutFrames` and `applyLayoutChangeTransition`:
+ *   the one module that produces the size-change glide and the edge reveal
+ *   `spec:AST-105` defines (`architecture:react-component-runtime` INV12)
  * @position Motion foundation, internal to core. A handle comes from the
  *   public `useAnimatedLayout` hook; a component that takes it reports its
  *   size changes through this module.
@@ -45,8 +44,13 @@
  * - A measurement no commit claims by the next frame is dropped.
  * - The changed element plays its own entrance on the same spring, started in
  *   the same frame (`playLayoutChange`), or its exit: kept where it is while
- *   it gives up its space and conceals (`holdLayoutExit`). A disclosure's
- *   indicator turns on the same motion (`applyLayoutChangeTransition`).
+ *   it gives up its space and conceals (`holdLayoutExit`). Both are FR9's
+ *   edge reveal: from its block-end edge by default, or from the block-start
+ *   or an inline edge it is given. Once the content on that edge's side
+ *   glides, the edge rides that glide, frame by frame, so the two never part;
+ *   a reversal (a close while it opens) starts from what the element shows.
+ *   A disclosure's indicator turns on the same motion
+ *   (`applyLayoutChangeTransition`).
  * - A swap holds old content as one transient copy, inert and hidden from
  *   assistive technology, while new content enters in its place, on the same
  *   motion, and removes it when the swap ends (`holdLayoutSwap`,
@@ -54,6 +58,11 @@
  *   the swap's progress and, riding a gliding element, how far it has moved,
  *   so every part keeps to that glide; under Reduce Motion with a coarse
  *   pointer only opacity changes.
+ * - FR9's two-state form holds an element's old state as the swap's copy
+ *   while its edge rides a gliding element, such as a rail beside its
+ *   content (`holdLayoutEdge`, `playLayoutEdge`): the larger state is
+ *   clipped on that edge, from the extent the element shows, and the caller
+ *   adds only its own fades.
  * - Frames on elements the page renders can play on the same motion with no
  *   copy (`playLayoutFrames`), such as a surface reaching over a gap a glide
  *   opens, and are released when the motion ends.
@@ -1147,15 +1156,322 @@ export function reportLayoutChange(
   };
 }
 
+// ---------------------------------------------------------------------------
+// The edge reveal (`spec:AST-105` FR9)
+// ---------------------------------------------------------------------------
+
+/**
+ * The edge an element reveals from or conceals to (`spec:AST-105` FR9): its
+ * block-end edge by default, or its block-start, inline-start or inline-end
+ * edge, such as a panel collapsing beside content. An inline edge follows
+ * the element's direction.
+ */
+export type LayoutEdge =
+  'block-end' | 'block-start' | 'inline-start' | 'inline-end';
+
+/** Whether `element` lays its inline axis out right to left. */
+function isRtl(element: Element): boolean {
+  return (
+    element.ownerDocument.defaultView?.getComputedStyle(element).direction ===
+    'rtl'
+  );
+}
+
+/**
+ * The `clip-path` that hides `side` of an element from `edge`: `inset()`'s
+ * sides are physical (top, right, bottom, left), so an inline edge is
+ * mirrored right to left. `zero` is how the other three are written.
+ */
+function edgeClip(
+  edge: LayoutEdge,
+  side: string,
+  zero: string,
+  rtl: boolean,
+): string {
+  const sides = [zero, zero, zero, zero];
+  const index =
+    edge === 'block-start'
+      ? 0
+      : edge === 'block-end'
+        ? 2
+        : (edge === 'inline-end') !== rtl
+          ? 1
+          : 3;
+  sides[index] = side;
+  return `inset(${sides.join(' ')})`;
+}
+
+/** A hidden fraction of the element, as a percentage clip on `edge`. */
+function fractionClip(edge: LayoutEdge, hidden: number, rtl: boolean): string {
+  return edgeClip(edge, `${round(hidden * 100)}%`, '0', rtl);
+}
+
+/** A hidden length of the element, in its own px, as a clip on `edge`. */
+function pxClip(edge: LayoutEdge, hidden: number, rtl: boolean): string {
+  return edgeClip(edge, `${hidden}px`, '0px', rtl);
+}
+
+/**
+ * The element's size along `edge`'s axis, in its own px (a scaled ancestor
+ * divided out), read from the layout the caller already laid out.
+ */
+function extentOf(element: Element, edge: LayoutEdge): number {
+  const rect = element.getBoundingClientRect();
+  const scale = scaleOf(element, rect);
+  return edge.startsWith('inline')
+    ? rect.width / scale.x
+    : rect.height / scale.y;
+}
+
+/**
+ * The last element before `element` in the area that takes part in layout:
+ * its previous sibling, or its nearest ancestor's below the area (the mirror
+ * of `nextInFlow`, for a start edge).
+ */
+function previousInFlow(element: Element, area: Element): Element | null {
+  const view = element.ownerDocument.defaultView;
+  const lastBox = (from: Element): Element | null => {
+    const style = view?.getComputedStyle(from);
+    if (style == null) {
+      return from;
+    }
+    if (style.display === 'contents') {
+      for (
+        let child = from.lastElementChild;
+        child != null;
+        child = child.previousElementSibling
+      ) {
+        const box = lastBox(child);
+        if (box != null) {
+          return box;
+        }
+      }
+      return null;
+    }
+    return takesPart(from, style) ? from : null;
+  };
+  let node: Element | null = element;
+  while (node != null && node !== area) {
+    for (
+      let sibling = node.previousElementSibling;
+      sibling != null;
+      sibling = sibling.previousElementSibling
+    ) {
+      const box = lastBox(sibling);
+      if (box != null) {
+        return box;
+      }
+    }
+    node = node.parentElement;
+  }
+  return null;
+}
+
+/**
+ * The glide that moves `neighbour`: its own, or that of its nearest gliding
+ * ancestor below the area that does not also hold `element` (one that holds
+ * both moves the two together, so the edge does not ride it).
+ */
+function glideMoving(
+  neighbour: Element,
+  element: Element,
+  area: Element,
+): Glide | null {
+  for (
+    let node: Element | null = neighbour;
+    node != null && node !== area && !node.contains(element);
+    node = node.parentElement
+  ) {
+    const glide = glides.get(node);
+    if (glide != null) {
+      return glide;
+    }
+  }
+  return null;
+}
+
+/** A one-state reveal or conceal running on an element. */
+interface EdgeMotion {
+  readonly animation: Animation;
+  /** The fraction of the element it shows `t` ms in (1: all of it). */
+  shownAt: (t: number) => number;
+}
+
+/** Each element's running one-state reveal or conceal. */
+const edgeMotions = new WeakMap<Element, EdgeMotion>();
+
+/**
+ * What a one-state motion an adopter stopped (`releaseLayoutExit`) showed,
+ * and the timeline time it stopped at: a reveal started in the same frame,
+ * the reversal that stopped it, starts there.
+ */
+const stoppedShown = new WeakMap<
+  Element,
+  {readonly fraction: number; readonly at: number}
+>();
+
+function timelineNow(element: Element): number {
+  return Number(element.ownerDocument.timeline?.currentTime ?? Number.NaN);
+}
+
+/** What `motion` shows now, by its animation's own clock. */
+function shownNow(motion: EdgeMotion): number {
+  const time = Number(motion.animation.currentTime);
+  return motion.shownAt(Number.isFinite(time) ? Math.max(0, time) : 0);
+}
+
+/**
+ * What `element` shows as a reveal or conceal starts: where the one-state
+ * motion this one reverses had got to (it stops there), or `atRest`, all of
+ * it for a conceal and nothing for a reveal.
+ */
+function shownAtStart(element: Element, atRest: number): number {
+  const running = edgeMotions.get(element);
+  if (running != null) {
+    edgeMotions.delete(element);
+    const fraction = shownNow(running);
+    running.animation.cancel();
+    return fraction;
+  }
+  const stopped = stoppedShown.get(element);
+  stoppedShown.delete(element);
+  if (stopped != null && stopped.at === timelineNow(element)) {
+    return stopped.fraction;
+  }
+  return atRest;
+}
+
+/** Records `animation` as `element`'s running one-state motion. */
+function trackEdgeMotion(
+  element: Element,
+  animation: Animation,
+  shownAt: (t: number) => number,
+): EdgeMotion {
+  const motion: EdgeMotion = {animation, shownAt};
+  edgeMotions.set(element, motion);
+  animation.addEventListener?.('finish', () => {
+    if (edgeMotions.get(element) === motion) {
+      edgeMotions.delete(element);
+    }
+  });
+  return motion;
+}
+
+/**
+ * After this commit's glides start (the batch flushes in a microtask queued
+ * before this one), before the frame paints: once the content on `edge`'s
+ * side glides, the moving edge rides that glide, frame by frame, so the two
+ * never part, a reversal included (the glide carries its running motion).
+ * `hiddenAt` turns that content's offset towards the edge's side into the
+ * length the element hides; `frame` turns that length into a keyframe.
+ * Without that glide (nothing on that side in the area, or nothing that
+ * moves) the motion keeps its own curve. The animation is kept, its frames
+ * replaced; `onRide` hears the ridden hidden length over time.
+ */
+function rideNeighbour(
+  element: Element,
+  area: Element,
+  edge: LayoutEdge,
+  rtl: boolean,
+  animation: Animation,
+  isCurrent: () => boolean,
+  hiddenAt: (towards: number) => number,
+  frame: (hidden: number) => Keyframe,
+  onRide: (hidden: (t: number) => number) => void,
+): void {
+  const effect = animation.effect as KeyframeEffect | null;
+  if (effect == null || typeof effect.setKeyframes !== 'function') {
+    return;
+  }
+  queueMicrotask(() => {
+    if (!isCurrent()) {
+      return;
+    }
+    const isEnd = edge.endsWith('end');
+    const neighbour = isEnd
+      ? nextInFlow(element, area)
+      : previousInFlow(element, area);
+    const glide =
+      neighbour == null ? null : glideMoving(neighbour, element, area);
+    if (neighbour == null || glide == null) {
+      return;
+    }
+    // A glide that moves the element itself in the same batch, short of what
+    // it shares with the neighbour (an item above them closing): the edge
+    // rides the neighbour's offset from the element, not from the page.
+    const own = glideMoving(element, neighbour, area);
+    const durationMs = Math.max(glide.durationMs, own?.durationMs ?? 0);
+    // The neighbour's offset from its place relative to the element's,
+    // towards the edge's side.
+    const sign = isEnd ? 1 : -1;
+    const hidden = (t: number): number => {
+      const offset = glide.offsetAt(t);
+      const moved = own?.offsetAt(t) ?? {x: 0, y: 0};
+      return hiddenAt(
+        sign *
+          (edge.startsWith('inline')
+            ? (rtl ? -1 : 1) * (offset.x - moved.x)
+            : offset.y - moved.y),
+      );
+    };
+    effect.setKeyframes(sampleOver(durationMs, t => frame(hidden(t))));
+    effect.updateTiming?.({duration: durationMs});
+    onRide(hidden);
+  });
+}
+
+/**
+ * The one-state reveal or conceal rides the content on its edge's side: the
+ * element shows what lies between its fixed edge and that content, a reveal
+ * less by however far the content still is from its place towards it, a
+ * conceal all of it less however far the content has come, fading with what
+ * it hides.
+ */
+function rideEdge(
+  element: Element,
+  area: Element,
+  edge: LayoutEdge,
+  rtl: boolean,
+  motion: EdgeMotion,
+  isConceal: boolean,
+): void {
+  const extent = extentOf(element, edge);
+  if (!(extent > 0)) {
+    return;
+  }
+  rideNeighbour(
+    element,
+    area,
+    edge,
+    rtl,
+    motion.animation,
+    () => edgeMotions.get(element) === motion,
+    towards =>
+      Math.min(extent, Math.max(0, isConceal ? extent - towards : -towards)),
+    hidden => ({
+      opacity: 1 - hidden / extent,
+      clipPath: pxClip(edge, hidden, rtl),
+    }),
+    hiddenAt => {
+      motion.shownAt = t => 1 - hiddenAt(t) / extent;
+    },
+  );
+}
+
 /**
  * The changed element's own animation, on the same motion as the content
- * after it: content that appears reveals downward from its top edge. Plays
- * only with a handle, inside its area and in the area's visible part.
- * Returns the entrance it started, or null when it played none.
+ * after it (`spec:AST-105` FR4): content that appears reveals from its
+ * block-end edge downward, or from the `edge` it is given (FR9), and its edge
+ * rides the glide of the content on that side once it starts. A reveal that
+ * reverses a running conceal (an adopter opens it again mid-exit, after
+ * `releaseLayoutExit`) starts from what the element shows. Plays only with a
+ * handle, inside its area and in the area's visible part. Returns the
+ * entrance it started, or null when it played none.
  */
 export function playLayoutChange(
   handle: AnimatedLayout | null | undefined,
   element: Element,
+  {edge = 'block-end'}: {edge?: LayoutEdge} = {},
 ): Animation | null {
   if (handle == null) {
     return null;
@@ -1171,26 +1487,40 @@ export function playLayoutChange(
   if (motion.kind === 'instant') {
     return null;
   }
+  const from = shownAtStart(element, 0);
   if (motion.kind === 'fade') {
-    return safeAnimate(element, [{opacity: 0}, {opacity: 1}], {
+    return safeAnimate(element, [{opacity: from}, {opacity: 1}], {
       duration: motion.durationMs,
       easing: motion.easing,
     });
   }
-  return safeAnimate(
+  const {progress} = motion;
+  const rtl = edge.startsWith('inline') && isRtl(element);
+  const animation = safeAnimate(
     element,
-    sampleKeyframes(motion.progress, remaining => ({
-      opacity: 1 - remaining,
-      clipPath: `inset(0 0 ${round(remaining * 100)}% 0)`,
-    })),
-    {duration: motion.progress.durationMs, easing: 'linear'},
+    sampleKeyframes(progress, remaining => {
+      const hidden = (1 - from) * remaining;
+      return {opacity: 1 - hidden, clipPath: fractionClip(edge, hidden, rtl)};
+    }),
+    {duration: progress.durationMs, easing: 'linear'},
   );
+  if (animation != null) {
+    const tracked = trackEdgeMotion(
+      element,
+      animation,
+      t => 1 - (1 - from) * progress.remaining(t),
+    );
+    rideEdge(element, area, edge, rtl, tracked, false);
+  }
+  return animation;
 }
 
 /** The inline properties an exit sets, so a release removes exactly them. */
 const EXIT_PROPERTIES = [
   'margin-block-end',
   'margin-inline-end',
+  'margin-block-start',
+  'margin-inline-start',
   'pointer-events',
 ] as const;
 
@@ -1259,7 +1589,11 @@ function placeOf(
  * so a gap or collapsing margins come out exact. Returns false, setting
  * nothing, when no margin reaches that place.
  */
-function giveUpSpace(element: HTMLElement, area: Element): boolean {
+function giveUpSpace(
+  element: HTMLElement,
+  area: Element,
+  edge: LayoutEdge = 'block-end',
+): boolean {
   const view = element.ownerDocument.defaultView;
   const parent =
     element.parentElement == null
@@ -1270,24 +1604,43 @@ function giveUpSpace(element: HTMLElement, area: Element): boolean {
     parent.display.includes('flex') &&
     parent.flexDirection.startsWith('row');
   const rtl = view?.getComputedStyle(element).direction === 'rtl';
-  const property = isRow ? 'margin-inline-end' : 'margin-block-end';
-  const size = isRow ? element.offsetWidth : element.offsetHeight;
+  // The default block-end exit frees its space at its end, on the axis its
+  // container lays it out on; an exit by another edge frees it on that
+  // edge's side, so the element stays where it shows and the content beyond
+  // that edge moves (FR9).
+  const isStart = edge.endsWith('start');
+  const property =
+    edge === 'block-end'
+      ? isRow
+        ? 'margin-inline-end'
+        : 'margin-block-end'
+      : `margin-${edge}`;
+  const isInline = property.includes('inline');
+  const size = isInline ? element.offsetWidth : element.offsetHeight;
   const next = nextInFlow(element, area);
-  if (next == null) {
+  if (next == null && !isStart) {
     // Nothing after it in the area to land anywhere.
     element.style.setProperty(property, `${-size}px`);
     return true;
   }
   const own = element.style.getPropertyValue(property);
   const ownPriority = element.style.getPropertyPriority(property);
-  const axis = isRow ? 'inline' : 'block';
+  const axis = isInline ? 'inline' : 'block';
   // The content after its container must land too: a flex-row item that
   // sets its row's height moves what follows the row.
   const afterParent =
     element.parentElement == null || element.parentElement === area
       ? null
       : nextInFlow(element.parentElement, area);
-  const checked = afterParent == null ? [next] : [next, afterParent];
+  // By a start edge, what lies before it lands too, and the element itself
+  // stays where it shows.
+  const before = isStart ? previousInFlow(element, area) : null;
+  const checked = [next, afterParent, before, isStart ? element : null].filter(
+    (box): box is Element => box != null,
+  );
+  if (checked.length === 0) {
+    return false;
+  }
   // The element's scale, read in the layout the caller's visibility check
   // already laid out.
   const scale = scaleOf(element, element.getBoundingClientRect());
@@ -1296,8 +1649,11 @@ function giveUpSpace(element: HTMLElement, area: Element): boolean {
   // inside it).
   const position = element.style.getPropertyValue('position');
   const positionPriority = element.style.getPropertyPriority('position');
+  const shown = isStart ? placeOf(element, rtl) : null;
   element.style.setProperty('position', 'absolute', 'important');
-  const targets = checked.map(box => placeOf(box, rtl));
+  const targets = checked.map(box =>
+    box === element && shown != null ? shown : placeOf(box, rtl),
+  );
   const target = targets[0];
   if (position === '') {
     element.style.removeProperty('position');
@@ -1310,7 +1666,7 @@ function giveUpSpace(element: HTMLElement, area: Element): boolean {
   // A first guess (its box), then one correction from the measured result:
   // a gap, a collapsed margin or the element's own margins.
   element.style.setProperty(property, `${-size}px`);
-  const guess = placeOf(next, rtl)[axis];
+  const guess = placeOf(checked[0], rtl)[axis];
   const correction = (target[axis] - guess) / perPx;
   element.style.setProperty(property, `${-size + correction}px`);
   // Everything checked must land on both axes: a flex-row item that sets
@@ -1355,6 +1711,11 @@ const replaced = new WeakMap<Element, Replaced>();
  * element, after the change's `animate()` reported it measured, in the same
  * task: the glide reads the layout once the element has given up its space.
  *
+ * It conceals to its block-end edge by default, or to the `edge` it is given
+ * (`spec:AST-105` FR9), and its edge rides the glide of the content on that
+ * side once it starts; a conceal that reverses a running reveal (a close
+ * while it opens) starts from what the element shows.
+ *
  * Returns false, holding nothing, when the exit lands at once: no handle, a
  * close no change in the area measured, outside the area or its visible part,
  * Reduce Motion with a fine pointer, or a layout no end margin can free (a
@@ -1366,6 +1727,7 @@ export function holdLayoutExit(
   handle: AnimatedLayout | null | undefined,
   element: HTMLElement,
   done: () => void,
+  {edge = 'block-end'}: {edge?: LayoutEdge} = {},
 ): boolean {
   if (handle == null) {
     return false;
@@ -1403,7 +1765,7 @@ export function holdLayoutExit(
         ] as const,
     ),
   };
-  if (!giveUpSpace(element, area)) {
+  if (!giveUpSpace(element, area, edge)) {
     // A layout no end margin can free (a grid track and its gap, a flex-row
     // item that sets its row's height): it hides at once, and the content
     // after it takes its final place at once (`spec:AST-105` out of
@@ -1419,25 +1781,36 @@ export function holdLayoutExit(
   // Out of reach while it conceals: no focus, no pointer, nothing read.
   element.setAttribute('inert', '');
   element.style.setProperty('pointer-events', 'none');
-  const animation =
-    motion.kind === 'fade'
-      ? safeAnimate(element, [{opacity: 1}, {opacity: 0}], {
-          duration: motion.durationMs,
-          easing: motion.easing,
-          fill: 'forwards',
-        })
-      : safeAnimate(
-          element,
-          sampleKeyframes(motion.progress, remaining => ({
-            opacity: remaining,
-            clipPath: `inset(0 0 ${round((1 - remaining) * 100)}% 0)`,
-          })),
-          {
-            duration: motion.progress.durationMs,
-            easing: 'linear',
-            fill: 'forwards',
-          },
-        );
+  // A close while it opens: the reveal stops where it shows, and this starts
+  // there.
+  const from = shownAtStart(element, 1);
+  const rtl = edge.startsWith('inline') && isRtl(element);
+  let animation: Animation | null;
+  if (motion.kind === 'fade') {
+    animation = safeAnimate(element, [{opacity: from}, {opacity: 0}], {
+      duration: motion.durationMs,
+      easing: motion.easing,
+      fill: 'forwards',
+    });
+  } else {
+    const {progress} = motion;
+    animation = safeAnimate(
+      element,
+      sampleKeyframes(progress, remaining => {
+        const shown = from * remaining;
+        return {opacity: shown, clipPath: fractionClip(edge, 1 - shown, rtl)};
+      }),
+      {duration: progress.durationMs, easing: 'linear', fill: 'forwards'},
+    );
+    if (animation != null) {
+      const tracked = trackEdgeMotion(
+        element,
+        animation,
+        t => from * progress.remaining(t),
+      );
+      rideEdge(element, area, edge, rtl, tracked, true);
+    }
+  }
   exits.set(element, animation);
   if (animation == null) {
     // No Web Animations: nothing to wait for.
@@ -1462,6 +1835,16 @@ export function releaseLayoutExit(element: HTMLElement): void {
   if (!exits.has(element)) {
     return;
   }
+  // What the exit showed as it stopped: a reveal in the same frame (opened
+  // again mid-exit) starts there.
+  const running = edgeMotions.get(element);
+  if (running != null) {
+    edgeMotions.delete(element);
+    stoppedShown.set(element, {
+      fraction: shownNow(running),
+      at: timelineNow(element),
+    });
+  }
   exits.get(element)?.cancel();
   exits.delete(element);
   const prior = replaced.get(element);
@@ -1743,6 +2126,555 @@ export function playLayoutFrames(
   return end;
 }
 
+// ---------------------------------------------------------------------------
+// The edge reveal's two-state form (`spec:AST-105` FR9)
+// ---------------------------------------------------------------------------
+
+/**
+ * An element's old state, held before a change commits for FR9's two-state
+ * edge reveal.
+ */
+export interface LayoutEdgeHold {
+  readonly element: HTMLElement;
+  /** Where it showed, in viewport coordinates. */
+  readonly rect: DOMRect;
+  /**
+   * Its size along the edge's axis as it shows: what a running reveal shows
+   * mid-motion, or its box.
+   */
+  readonly extent: number;
+  /** Its old state as one transient copy, or null when it cannot be held. */
+  readonly swap: LayoutSwap | null;
+}
+
+/** A playing two-state edge reveal. */
+export interface LayoutEdgeMotion {
+  /** Ends it at once (a new change, an unmount). */
+  end(): void;
+  /**
+   * What it shows now: its extent along the edge's axis and the motion's
+   * progress (0 → 1), or null once it has settled.
+   */
+  shown(): {readonly extent: number; readonly progress: number} | null;
+}
+
+/** What the caller adds to a two-state edge reveal: only its own fades. */
+export interface LayoutEdgeParts {
+  /** The old state's copy's opacity over the progress (1 when absent). */
+  readonly copyOpacity?: (p: number) => number;
+  /** Its text's opacity, on its own curve, when that differs from the copy's. */
+  readonly copyText?: (p: number) => number;
+  /** Parts the page renders, playing with the reveal (the new state's text). */
+  readonly incoming?: ReadonlyArray<{
+    readonly element: Element;
+    readonly frames: (p: number) => Keyframe;
+  }>;
+}
+
+const SETTLED: LayoutEdgeMotion = {end: () => {}, shown: () => null};
+
+/**
+ * Before a change commits: hold `element`'s old state for FR9's two-state edge
+ * reveal, its box and the extent it shows along `edge`'s axis (`shown`, from a
+ * running reveal, or its box), and its old state as one transient copy (null
+ * when it cannot be copied, or under an immediate change). Returns null
+ * without the element or without Web Animations.
+ */
+export function holdLayoutEdge(
+  handle: AnimatedLayout | null | undefined,
+  element: HTMLElement | null,
+  {
+    edge = 'block-end',
+    shown = null,
+  }: {edge?: LayoutEdge; shown?: number | null} = {},
+): LayoutEdgeHold | null {
+  if (element == null || typeof element.animate !== 'function') {
+    return null;
+  }
+  const rect = element.getBoundingClientRect();
+  return {
+    element,
+    rect,
+    extent: shown ?? (edge.startsWith('inline') ? rect.width : rect.height),
+    swap: holdLayoutSwap(handle, element),
+  };
+}
+
+/**
+ * After the change commits, before paint: FR9's two-state edge reveal, on
+ * FR4's one motion. The state that is larger along `edge`'s axis is clipped
+ * on that edge, from the extent the element showed to the new one: a conceal
+ * covers the old state, held as the swap's copy, with the element raised
+ * above it; a reveal opens the element, under the old state. With
+ * `rideWith`, an element the glide moves after that edge (a rail's content
+ * column), the edge rides its glide, frame by frame, so the two never part,
+ * also when this reverses a running reveal; without it the edge follows the
+ * motion's curve. `parts` gives the caller's own fades, told whether the edge
+ * conceals and the element as it is now. Under Reduce Motion it follows
+ * `design:reduced-motion`: opacity only under a coarse primary pointer (DR2),
+ * an immediate change otherwise (DR3). `current` is the element after the
+ * commit, when it remounted.
+ */
+export function playLayoutEdge(
+  hold: LayoutEdgeHold,
+  current: HTMLElement | null,
+  handle: AnimatedLayout,
+  {
+    edge = 'block-end',
+    rideWith = null,
+    parts,
+  }: {
+    edge?: LayoutEdge;
+    rideWith?: Element | null;
+    parts?: (isConceal: boolean, element: HTMLElement) => LayoutEdgeParts;
+  } = {},
+): LayoutEdgeMotion {
+  const {rect: before, swap, extent: from} = hold;
+  const element = current?.isConnected === true ? current : hold.element;
+  if (!element.isConnected) {
+    return SETTLED;
+  }
+  const motion = layoutMotion(element);
+  const next = element.getBoundingClientRect();
+  const isInline = edge.startsWith('inline');
+  const extentOfBox = (box: DOMRect) => (isInline ? box.width : box.height);
+  const to = extentOfBox(next);
+  if (motion.kind === 'instant' || Math.abs(to - from) < 0.5) {
+    return SETTLED;
+  }
+  const isConceal = to < from;
+  const isEnd = edge.endsWith('end');
+  const rtl = isInline && isRtl(element);
+  // The row that holds the element and the ridden element, or its parent.
+  const host =
+    rideWith?.parentElement != null && rideWith.parentElement.contains(element)
+      ? rideWith.parentElement
+      : element.parentElement;
+  // Riding needs the swap: its frames carry the ridden element's travel.
+  // Without one (old state that cannot be copied) the edge follows the
+  // motion's curve.
+  const rides =
+    host != null &&
+    rideWith != null &&
+    rideWith.parentElement === host &&
+    swap != null;
+  // The ridden element's travel so far, towards the edge's side.
+  const sign = isEnd ? 1 : -1;
+  const towards = (ride: LayoutRide) =>
+    sign * (isInline ? (rtl ? -ride.x : ride.x) : ride.y);
+  const extentAt = (p: number, ride: LayoutRide) =>
+    rides ? from + towards(ride) : from + (to - from) * p;
+  const clip = (hidden: number) => pxClip(edge, hidden, rtl);
+  const now = () => Number(element.ownerDocument.timeline?.currentTime ?? 0);
+  const startedAt = now();
+  const durationMs =
+    motion.kind === 'spring' ? motion.progress.durationMs : motion.durationMs;
+  const shown = (): {extent: number; progress: number} | null => {
+    const elapsed = now() - startedAt;
+    if (elapsed >= durationMs) {
+      return null;
+    }
+    const progress =
+      motion.kind === 'spring' ? 1 - motion.progress.remaining(elapsed) : 0;
+    let extent = from + (to - from) * progress;
+    if (rides && rideWith != null) {
+      // The edge is the ridden element's: read it where it shows.
+      const ridden = rideWith.getBoundingClientRect();
+      const own = element.getBoundingClientRect();
+      extent = !isInline
+        ? isEnd
+          ? ridden.top - own.top
+          : own.bottom - ridden.bottom
+        : isEnd !== rtl
+          ? ridden.left - own.left
+          : own.right - ridden.right;
+    }
+    return {extent, progress};
+  };
+  // The ride, when the ridden element does not glide: its whole travel at
+  // once, physical (its old place less its new).
+  const travel = sign * (from - to);
+  const rideSpec =
+    rides && rideWith != null
+      ? {
+          element: rideWith,
+          travel: isInline
+            ? {x: rtl ? -travel : travel, y: 0}
+            : {x: 0, y: travel},
+          isCopyMoved: false,
+        }
+      : undefined;
+  // The copy keeps the element's fixed edge (the one opposite `edge`) where
+  // the element is now, so it meets the element wherever it sits.
+  const fixedAtStart = isEnd !== (isInline && rtl);
+  const at = new DOMRect(
+    isInline && !fixedAtStart ? next.right - before.width : next.left,
+    !isInline && !isEnd ? next.bottom - before.height : next.top,
+    before.width,
+    before.height,
+  );
+  const own = parts?.(isConceal, element) ?? {};
+  const copyOpacity = own.copyOpacity ?? (() => 1);
+
+  if (isConceal) {
+    // A conceal covers the old state, held by the swap, from the extent it
+    // shows down to the new one; the element, raised above it, shows through.
+    if (swap == null || host == null) {
+      return SETTLED;
+    }
+    let raised: HTMLElement | null = element;
+    while (raised != null && raised.parentElement !== host) {
+      raised = raised.parentElement;
+    }
+    const restore =
+      raised == null
+        ? null
+        : {position: raised.style.position, zIndex: raised.style.zIndex};
+    if (raised != null) {
+      if (getComputedStyle(raised).position === 'static') {
+        raised.style.position = 'relative';
+      }
+      raised.style.zIndex = '2';
+    }
+    const end = playLayoutSwap(
+      {...swap, rect: at},
+      {
+        host,
+        isOpaque: true,
+        copy: (p, ride) => ({
+          clipPath: clip(extentOfBox(before) - extentAt(p, ride)),
+          opacity: copyOpacity(p),
+        }),
+        copyText: own.copyText,
+        rideWith: rideSpec,
+        onEnd: () => {
+          if (raised != null && restore != null) {
+            raised.style.position = restore.position;
+            raised.style.zIndex = restore.zIndex;
+          }
+        },
+        incoming: own.incoming ?? [],
+      },
+    );
+    return {end, shown};
+  }
+
+  // A reveal opens the element from the extent it showed, under the old
+  // state held by the same swap.
+  const incoming = [
+    {
+      element,
+      frames: (p: number, ride: LayoutRide) => ({
+        clipPath: clip(to - extentAt(p, ride)),
+      }),
+    },
+    ...(own.incoming ?? []),
+  ];
+  const end =
+    swap != null && host != null
+      ? playLayoutSwap(
+          {...swap, rect: at},
+          {
+            host,
+            isOpaque: true,
+            copy: p => ({opacity: copyOpacity(p)}),
+            copyText: own.copyText,
+            rideWith: rideSpec,
+            incoming,
+          },
+        )
+      : playLayoutFrames(handle, incoming);
+  return {end, shown};
+}
+
+// ---------------------------------------------------------------------------
+// The edge reveal of a resized element (`spec:AST-105` FR9, no copy)
+// ---------------------------------------------------------------------------
+
+/** A resized element's edge reveal, reported around its change. */
+export interface LayoutEdgeReport {
+  /** Before the change commits: measures the element and what moves. */
+  measureBefore(): void;
+  /**
+   * After the new size is applied, before paint: the element reveals or
+   * conceals by its edge, from the extent it showed to its new one, and the
+   * content beside it glides on the same motion.
+   */
+  animate(): void;
+  /** Ends a running reveal or conceal at once, removing what it holds. */
+  cancel(): void;
+}
+
+/** A running edge reveal of a resized element. */
+interface ResizeReveal {
+  readonly animation: Animation | null;
+  /** The extent it shows `t` ms in, in its own px. */
+  shownAt: (t: number) => number;
+  /** Its extent along the edge's axis as laid out, held or not. */
+  readonly box: number;
+  /** Ends it, putting back what it replaced. */
+  release(): void;
+}
+
+const resizeReveals = new WeakMap<Element, ResizeReveal>();
+
+/** The inline properties a size hold sets, by axis. */
+const HOLD_PROPERTIES = {
+  inline: [
+    'inline-size',
+    'min-inline-size',
+    'max-inline-size',
+    'flex-basis',
+    'flex-grow',
+    'flex-shrink',
+  ],
+  block: [
+    'block-size',
+    'min-block-size',
+    'max-block-size',
+    'flex-basis',
+    'flex-grow',
+    'flex-shrink',
+  ],
+} as const;
+
+/**
+ * Holds `element` at `extent` own px along `edge`'s axis while it conceals to
+ * `keep`, freeing the difference by the margin on that edge's side, so what
+ * lies beyond the edge stays where the new size puts it. Returns what puts
+ * back every value it set, or null when no margin frees it (the content on
+ * that side did not stay put), having set nothing.
+ */
+function holdExtent(
+  element: HTMLElement,
+  area: Element,
+  edge: LayoutEdge,
+  extent: number,
+  keep: number,
+): (() => void) | null {
+  const axis = edge.startsWith('inline') ? 'inline' : 'block';
+  const margin = `margin-${edge}`;
+  const properties = [...HOLD_PROPERTIES[axis], margin];
+  const prior = properties.map(
+    property =>
+      [
+        property,
+        element.style.getPropertyValue(property),
+        element.style.getPropertyPriority(property),
+      ] as const,
+  );
+  const restore = () => {
+    for (const [property, value, priority] of prior) {
+      if (value === '') {
+        element.style.removeProperty(property);
+      } else {
+        element.style.setProperty(property, value, priority);
+      }
+    }
+  };
+  const isEnd = edge.endsWith('end');
+  const rtl = axis === 'inline' && isRtl(element);
+  const beyond = isEnd
+    ? nextInFlow(element, area)
+    : previousInFlow(element, area);
+  const before = beyond == null ? null : placeOf(beyond, rtl);
+  const size = `${extent}px`;
+  element.style.setProperty(`${axis}-size`, size, 'important');
+  element.style.setProperty(`min-${axis}-size`, size, 'important');
+  element.style.setProperty(`max-${axis}-size`, size, 'important');
+  element.style.setProperty('flex-basis', 'auto', 'important');
+  element.style.setProperty('flex-grow', '0', 'important');
+  element.style.setProperty('flex-shrink', '0', 'important');
+  element.style.setProperty(margin, `${keep - extent}px`, 'important');
+  if (beyond != null && before != null) {
+    // One correction from the measured result (a gap, the element's own
+    // margin), then everything beyond the edge must be where it was.
+    const landed = placeOf(beyond, rtl);
+    const scale = scaleOf(element, element.getBoundingClientRect());
+    const perPx = axis === 'inline' ? scale.x : scale.y;
+    const sign = isEnd ? 1 : -1;
+    const drift = (landed[axis] - before[axis]) * sign;
+    if (Math.abs(drift) > 0.5) {
+      element.style.setProperty(
+        margin,
+        `${keep - extent - drift / perPx}px`,
+        'important',
+      );
+    }
+    const settled = placeOf(beyond, rtl);
+    if (
+      Math.abs(settled.block - before.block) > 1 ||
+      Math.abs(settled.inline - before.inline) > 1
+    ) {
+      restore();
+      return null;
+    }
+  }
+  return restore;
+}
+
+/**
+ * Reports a resized element's edge reveal (`spec:AST-105` FR9) with no copy:
+ * a resize controller's pane collapsing or opening beside the content it
+ * shares a row with (`component:Resizable` FR8, `component:LayoutPanel`
+ * FR7). Measure before the change commits and animate after the
+ * new size is applied, as `reportLayoutChange` does; the content beside the
+ * element glides through that report. A larger extent reveals by `edge` from
+ * the extent the element showed. A smaller one conceals: the element is held
+ * at the extent it was laid out at, the difference freed by the margin on
+ * that edge's side so the content beyond it stays where the new size puts it,
+ * and clipped down to its new extent; the hold goes when the motion ends. The
+ * moving edge rides the glide of the content on that side, frame by frame,
+ * and a change made while it runs starts from the extent it shows. It slides:
+ * nothing fades. Under Reduce Motion with a coarse primary pointer a reveal
+ * fades in and a conceal lands at once (`design:reduced-motion` DR2); with a
+ * fine one every change lands at once (DR3).
+ */
+export function reportLayoutEdge(
+  handle: AnimatedLayout | null | undefined,
+  getElement: () => HTMLElement | null,
+  {edge = 'block-end'}: {edge?: LayoutEdge} = {},
+): LayoutEdgeReport {
+  const report = reportLayoutChange(handle, getElement);
+  /**
+   * What the element showed, its laid-out extent and its box, before the
+   * change.
+   */
+  let measured: {shown: number; box: number; rect: DOMRect} | null = null;
+  const release = (element: HTMLElement | null) => {
+    if (element == null) {
+      return;
+    }
+    resizeReveals.get(element)?.release();
+  };
+  return {
+    measureBefore() {
+      const element = getElement();
+      measured = null;
+      if (element != null) {
+        const running = resizeReveals.get(element);
+        const elapsed = Number(running?.animation?.currentTime);
+        const rect = element.getBoundingClientRect();
+        measured =
+          running == null
+            ? {
+                shown: extentOf(element, edge),
+                box: extentOf(element, edge),
+                rect,
+              }
+            : {
+                shown: running.shownAt(Number.isFinite(elapsed) ? elapsed : 0),
+                box: running.box,
+                rect,
+              };
+        running?.release();
+      }
+      report.measureBefore();
+    },
+    animate() {
+      report.animate();
+      const element = getElement();
+      const before = measured;
+      measured = null;
+      if (handle == null || element == null || before == null) {
+        return;
+      }
+      const area = areaOf(handle, element);
+      if (area == null) {
+        return;
+      }
+      const after = extentOf(element, edge);
+      if (Math.abs(after - before.shown) < 0.5) {
+        return;
+      }
+      // In the area's visible part before or after: a pane collapsing to
+      // nothing has no box after.
+      const visible = visibleRect(area);
+      if (
+        !intersects(element.getBoundingClientRect(), visible) &&
+        !intersects(before.rect, visible)
+      ) {
+        return;
+      }
+      const motion = layoutMotion(area);
+      if (motion.kind === 'instant') {
+        return;
+      }
+      const isConceal = after < before.shown;
+      if (motion.kind === 'fade') {
+        if (!isConceal) {
+          safeAnimate(element, [{opacity: 0}, {opacity: 1}], {
+            duration: motion.durationMs,
+            easing: motion.easing,
+          });
+        }
+        return;
+      }
+      const {progress} = motion;
+      const rtl = edge.startsWith('inline') && isRtl(element);
+      // The box the clip works in: the new one for a reveal; for a conceal,
+      // the one it was laid out at, held while it runs.
+      const box = isConceal ? Math.max(before.box, before.shown) : after;
+      const restore = isConceal
+        ? holdExtent(element, area, edge, box, after)
+        : () => {};
+      if (restore == null) {
+        return;
+      }
+      // Hidden at the start and at the end, in the box's own px.
+      const from = box - before.shown;
+      const to = box - after;
+      const curve = (t: number) => to + (from - to) * progress.remaining(t);
+      const animation = safeAnimate(
+        element,
+        sampleOver(progress.durationMs, t => ({
+          clipPath: pxClip(edge, curve(t), rtl),
+        })),
+        {duration: progress.durationMs, easing: 'linear'},
+      );
+      const reveal: ResizeReveal = {
+        animation,
+        shownAt: t => box - curve(t),
+        box,
+        release: () => {
+          if (resizeReveals.get(element) !== reveal) {
+            return;
+          }
+          resizeReveals.delete(element);
+          animation?.cancel();
+          restore();
+        },
+      };
+      if (animation == null) {
+        restore();
+        return;
+      }
+      resizeReveals.set(element, reveal);
+      animation.addEventListener?.('finish', reveal.release);
+      rideNeighbour(
+        element,
+        area,
+        edge,
+        rtl,
+        animation,
+        () => resizeReveals.get(element) === reveal,
+        // Anywhere in its box: the content beside it may carry a running
+        // motion past where this one starts or ends, and the edge follows.
+        towards =>
+          Math.min(box, Math.max(0, isConceal ? to - towards : -towards)),
+        hidden => ({clipPath: pxClip(edge, hidden, rtl)}),
+        hiddenAt => {
+          reveal.shownAt = t => box - hiddenAt(t);
+        },
+      );
+    },
+    cancel() {
+      measured = null;
+      release(getElement());
+    },
+  };
+}
+
 /**
  * A disclosure's indicator (its chevron) turns on the same motion as the
  * glide: its CSS transition takes the spring as a `linear()` easing, and an