@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Layer/modalOutlet.ts

@@ -4,10 +4,11 @@
 
 /**
  * @file modalOutlet.ts
- * @input The open Dialog `<dialog>` elements
+ * @input The open Dialog and scrim BottomSheet `<dialog>` elements
  * @output Exports useModalOutlet (a modal supplies its outlet),
- *   getActiveModalOutlet, and subscribeModalOutlets (a global host follows
- *   the latest one)
+ *   getActiveModalOutlet, subscribeModalOutlets (a global host follows the
+ *   latest one), and notifyTopLayerEntry (a non-modal surface entered the
+ *   top layer above the hosts)
  * @position Private layer infrastructure; spec:AST-003 FR18
  *
  * A native modal makes everything outside it inert and paints over every
@@ -18,29 +19,66 @@
  * fallback) must see modals rendered by the app. Listeners run synchronously,
  * so a host can leave a modal before React removes it from the document.
  *
+ * A non-modal top-layer surface (a `popover="manual"` host shown by
+ * `showPopover()`, such as a `hasScrim={false}` BottomSheet) blocks nothing,
+ * so it is not an outlet, but it still enters the top layer above the hosts
+ * shown before it. It announces the entry here, and a host re-enters the top
+ * layer in place so it paints above the surface again.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/Toast/ToastViewport.modalHost.test.tsx
  * - /docs/architecture/layer-runtime.md
  */
 
-import {useEffect, useLayoutEffect, type RefObject} from 'react';
+import {useEffect, useLayoutEffect, useRef, type RefObject} from 'react';
 
 const outlets: HTMLDialogElement[] = [];
-const listeners = new Set<() => void>();
+// Outlets whose order among themselves is decided by their caller (a stack of
+// bottom sheets), keyed by that caller's group. Reordering stays inside the
+// group: such an outlet never moves above an outlet of another group supplied
+// later (a Dialog opened from a sheet).
+const outletGroups = new WeakMap<HTMLDialogElement, string>();
+
+/**
+ * Why a host is told to place itself: `outlet` when the latest open modal
+ * may have changed (the host moves into it or back out), `entry` when a
+ * non-modal surface entered the top layer above the host (the host stays
+ * where it is and re-enters the top layer).
+ */
+export type ModalOutletChange = 'outlet' | 'entry';
+
+const listeners = new Set<(change: ModalOutletChange) => void>();
 
-function notify(): void {
+function notify(change: ModalOutletChange): void {
   for (const listener of listeners) {
-    listener();
+    listener(change);
   }
 }
 
-function addOutlet(element: HTMLDialogElement): void {
+/**
+ * Supply an outlet. The latest goes on top. One re-supplied beneath its
+ * group's top — a covered switcher flow whose level became a new dialog on a
+ * step change made from code, while a sheet stays on top of it — goes
+ * directly beneath that top, so the sheet on top stays the latest outlet and
+ * a toast raised from it still lands there, not in the covered, inert step.
+ */
+function addOutlet(element: HTMLDialogElement, beneathGroupTop: boolean): void {
   const index = outlets.indexOf(element);
   if (index !== -1) {
     outlets.splice(index, 1);
   }
+  const group = outletGroups.get(element);
+  if (beneathGroupTop && group != null) {
+    for (let other = outlets.length - 1; other >= 0; other -= 1) {
+      if (outletGroups.get(outlets[other]) === group) {
+        outlets.splice(other, 0, element);
+        notify('outlet');
+        return;
+      }
+    }
+  }
   outlets.push(element);
-  notify();
+  notify('outlet');
 }
 
 function removeOutlet(element: HTMLDialogElement): void {
@@ -49,7 +87,39 @@ function removeOutlet(element: HTMLDialogElement): void {
     return;
   }
   outlets.splice(index, 1);
-  notify();
+  outletGroups.delete(element);
+  notify('outlet');
+}
+
+/**
+ * Move `element` to the top of its own group: directly above the highest
+ * outlet of the same group, and never above an outlet of another group that
+ * was supplied later. A sheet revealed beneath an open Dialog stays beneath
+ * the Dialog; a sheet re-shown by its stack stays beneath everything that is
+ * not a sheet.
+ */
+function raiseWithinGroup(element: HTMLDialogElement): void {
+  const group = outletGroups.get(element);
+  const index = outlets.indexOf(element);
+  if (group == null || index === -1) {
+    return;
+  }
+  let target = outlets.length;
+  for (let other = outlets.length - 1; other > index; other -= 1) {
+    if (outletGroups.get(outlets[other]) !== group) {
+      target = other;
+    } else {
+      break;
+    }
+  }
+  // Nothing of another group sits above the group's top: go to the end.
+  // Otherwise land just beneath the lowest foreign outlet above us.
+  if (target - 1 === index) {
+    return;
+  }
+  outlets.splice(index, 1);
+  outlets.splice(target - 1, 0, element);
+  notify('outlet');
 }
 
 /** The latest open native modal, or null when none is open. */
@@ -57,40 +127,111 @@ export function getActiveModalOutlet(): HTMLDialogElement | null {
   return outlets[outlets.length - 1] ?? null;
 }
 
-/** Call `listener` whenever the latest open native modal may have changed. */
-export function subscribeModalOutlets(listener: () => void): () => void {
+/**
+ * Call `listener` whenever the latest open native modal may have changed
+ * (`'outlet'`), or a non-modal surface entered the top layer (`'entry'`).
+ */
+export function subscribeModalOutlets(
+  listener: (change: ModalOutletChange) => void,
+): () => void {
   listeners.add(listener);
   return () => {
     listeners.delete(listener);
   };
 }
 
+/**
+ * A surface was just shown into the top layer above the global hosts: a
+ * non-modal surface shown (`showPopover()` on a `popover="manual"` host), or
+ * a modal dialog closed and shown again by a stack keeping its order, which
+ * carries the host inside it back above the host's own popover. Global hosts
+ * re-enter the top layer so they paint above it, as they do above a modal
+ * that just opened.
+ */
+export function notifyTopLayerEntry(): void {
+  notify('entry');
+}
+
 /**
  * Supply `ref`'s `<dialog>` as the passive global outlet while it is an open
  * modal. Call it after the effect that runs `showModal()`, so the modal is
  * already in the top layer when global hosts move into it.
+ *
+ * `isLatest`, `group`, and `hostKey` are for a caller whose modals are ordered among
+ * themselves by something other than the order they were supplied in (a
+ * stack of bottom sheets that is re-shown to keep open order, or reveals a
+ * sheet by closing the one above it). By default the most recently supplied
+ * outlet is the latest, which is the native top layer's order for modals
+ * opened one after another. Such a caller names its `group` and passes the
+ * ordering's own answer as `isLatest`: when it turns true the outlet is
+ * raised to the top of its group — above the group's other outlets, never
+ * above an outlet of another group supplied later, such as a Dialog opened
+ * from the sheet — and when it turns false the outlet stays supplied (every
+ * open modal supplies one) but is no longer the group's latest.
  */
 export function useModalOutlet(
   ref: RefObject<HTMLDialogElement | null>,
   isActive: boolean,
+  isLatest: boolean = true,
+  group?: string,
+  hostKey?: string | null,
 ): void {
+  // `hostKey` names which element `ref` currently resolves to, for a caller
+  // whose ref moves between dialogs while it stays active (a switcher flow
+  // whose host dialog changes on a handoff): a change re-supplies the outlet
+  // from the new element and withdraws the old one. A re-supply made while
+  // the caller is not its group's latest (read through a ref, so a flip of
+  // `isLatest` alone never re-supplies) goes beneath the group's top: the
+  // sheet covering the flow keeps the outlet. A first supply always goes on
+  // top; the stack's answer arrives a render later and the raise below
+  // settles it.
+  const isLatestRef = useRef(isLatest);
+  isLatestRef.current = isLatest;
+  const suppliedRef = useRef<HTMLDialogElement | null>(null);
   useEffect(() => {
     const element = ref.current;
     if (!isActive || element == null) {
+      suppliedRef.current = null;
       return;
     }
+    const isResupply = suppliedRef.current != null;
+    suppliedRef.current = element;
+    if (group != null) {
+      outletGroups.set(element, group);
+    }
     // A native close (a `method="dialog"` form) ends the modal without a
-    // render.
+    // render. A `close` that arrives while the dialog is open again is stale:
+    // the dialog was closed and re-shown in one task (a stack putting its
+    // dialogs back in order, a sheet reopened during its exit), and the
+    // event queued by that close must not take the outlet away from a modal
+    // that is open.
     const handleClose = () => {
+      if (element.open) {
+        return;
+      }
       removeOutlet(element);
     };
     element.addEventListener('close', handleClose);
-    addOutlet(element);
+    addOutlet(element, isResupply && !isLatestRef.current);
     return () => {
       element.removeEventListener('close', handleClose);
       removeOutlet(element);
     };
-  }, [ref, isActive]);
+  }, [ref, isActive, group, hostKey]);
+
+  // Becoming the latest of its group again (a sheet revealed by the close of
+  // the one above it, or put back on top by its stack) raises the outlet
+  // within that group only: an outlet of another group supplied later (a
+  // Dialog opened from the sheet) stays above it, so a toast raised from
+  // that Dialog keeps landing in the Dialog. The first supply above already
+  // placed the outlet at the end.
+  useEffect(() => {
+    const element = ref.current;
+    if (!isActive || !isLatest || element == null) {
+      return;
+    }
+    raiseWithinGroup(element);
+  }, [ref, isActive, isLatest, hostKey]);
 
   // Unmounting removes the dialog without a close event, and a passive
   // cleanup runs after React has detached it. A layout cleanup runs before,

package/src/Layer/preserveAnimations.ts

@@ -0,0 +1,304 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file preserveAnimations.ts
+ * @input An element whose subtree is about to leave rendering for one forced
+ *   layout, and the function that does it
+ * @output The same CSS animations and transitions afterwards, in the state
+ *   they were in before
+ * @position Layer runtime; the re-placement of a layer that keeps its anchor
+ *   clear (spec:AST-059 FR4)
+ *
+ * Taking an element out of rendering cancels every CSS animation and
+ * transition of it and its subtree. When it returns, the browser creates the
+ * animations again from the stylesheet, at their start, and the transitions
+ * not at all; script-created animations are untouched. `preserveAnimations`
+ * reads every animation's state first and, afterwards, gives each recreated
+ * CSS animation that state and resumes each cancelled transition with a
+ * script animation at the same point.
+ *
+ * The state is read generically, from what the platform exposes: every
+ * accessor with a setter on the animation's and its effect's prototype
+ * chains, every field of the effect's timing, and its keyframes. Only values
+ * that differ from the recreated animation's are written, so a value the
+ * stylesheet controls stays under its control. A few members are not plain
+ * state and are handled in their own step (`ORDERED`); the rest need no
+ * handling (`DERIVED`). What cannot be carried over is the Animation and
+ * effect objects themselves: the old ones are idle, their `addEventListener`
+ * listeners and `finished`/`ready` promises stay with them, and the browser
+ * fires `animationcancel`/`transitioncancel` for them and `animationstart`
+ * for the new ones.
+ */
+
+/**
+ * Animation members written in a fixed order rather than generically: the
+ * timeline before the range that is measured on it, the rate before the
+ * time, and the start time (or, for a paused animation, the current time)
+ * last, once the play state is set. `effect` is not
+ * replaced, because a CSS animation whose effect script replaces leaves the
+ * stylesheet's control; its state is copied onto the new effect instead.
+ */
+const ORDERED = new Set([
+  'effect',
+  'timeline',
+  'rangeStart',
+  'rangeEnd',
+  'playbackRate',
+  'startTime',
+  'currentTime',
+]);
+
+type Writable = Record<string, unknown>;
+
+/** Every accessor with a setter on `object`'s prototype chain. */
+function writableAccessors(object: object): string[] {
+  const names = new Set<string>();
+  for (
+    let proto: object | null = Object.getPrototypeOf(object);
+    proto != null && proto !== Object.prototype;
+    proto = Object.getPrototypeOf(proto)
+  ) {
+    for (const [name, descriptor] of Object.entries(
+      Object.getOwnPropertyDescriptors(proto),
+    )) {
+      if (descriptor.set != null) {
+        names.add(name);
+      }
+    }
+  }
+  return [...names];
+}
+
+/**
+ * A textual form of a value that is compared by content rather than by
+ * identity: a CSS numeric value (as in a timeline range offset) through its
+ * serialization, a plain object (a range) through its members. Anything else
+ * is compared by identity (`null`).
+ */
+function contentOf(value: unknown): string | null {
+  if (
+    typeof CSSNumericValue !== 'undefined' &&
+    value instanceof CSSNumericValue
+  ) {
+    return value.toString();
+  }
+  if (
+    value != null &&
+    typeof value === 'object' &&
+    Object.getPrototypeOf(value) === Object.prototype
+  ) {
+    return Object.entries(value)
+      .map(([key, inner]) => `${key}:${contentOf(inner) ?? String(inner)}`)
+      .join(';');
+  }
+  return null;
+}
+
+function differs(a: unknown, b: unknown): boolean {
+  if (a === b) {
+    return false;
+  }
+  const textA = contentOf(a);
+  return textA == null || textA !== contentOf(b);
+}
+
+interface Saved {
+  animation: Animation;
+  name: string;
+  target: Element | null;
+  pseudoElement: string | null;
+  values: Writable;
+  effectValues: Writable;
+  timing: EffectTiming | null;
+  keyframes: ComputedKeyframe[] | null;
+  playState: AnimationPlayState;
+  replaceState: AnimationReplaceState;
+}
+
+function save(animation: Animation): Saved {
+  const effect = animation.effect as KeyframeEffect | null;
+  const values: Writable = {};
+  for (const name of writableAccessors(animation)) {
+    values[name] = (animation as unknown as Writable)[name];
+  }
+  const effectValues: Writable = {};
+  if (effect != null) {
+    for (const name of writableAccessors(effect)) {
+      effectValues[name] = (effect as unknown as Writable)[name];
+    }
+  }
+  return {
+    animation,
+    name:
+      (animation as Animation & {animationName?: string}).animationName ?? '',
+    target: effect?.target ?? null,
+    pseudoElement: effect?.pseudoElement ?? null,
+    values,
+    effectValues,
+    timing: effect?.getTiming() ?? null,
+    keyframes: effect?.getKeyframes() ?? null,
+    playState: animation.playState,
+    replaceState: animation.replaceState,
+  };
+}
+
+function write(object: object, name: string, value: unknown): void {
+  (object as Writable)[name] = value;
+}
+
+/** Give `next` the effect state `saved` had: every writable member. */
+function restoreEffect(next: KeyframeEffect, saved: Saved): void {
+  for (const name of writableAccessors(next)) {
+    if (
+      name in saved.effectValues &&
+      differs(saved.effectValues[name], (next as unknown as Writable)[name])
+    ) {
+      write(next, name, saved.effectValues[name]);
+    }
+  }
+  if (saved.timing != null) {
+    const timing = next.getTiming() as unknown as Writable;
+    const changed: Writable = {};
+    for (const [field, value] of Object.entries(saved.timing)) {
+      if (differs(value, timing[field])) {
+        changed[field] = value;
+      }
+    }
+    if (Object.keys(changed).length > 0) {
+      next.updateTiming(changed);
+    }
+  }
+  if (
+    saved.keyframes != null &&
+    JSON.stringify(saved.keyframes) !== JSON.stringify(next.getKeyframes())
+  ) {
+    next.setKeyframes(saved.keyframes);
+  }
+}
+
+/** Give `next` the state `saved` had, member by member. */
+function restore(next: Animation, saved: Saved): void {
+  const effect = next.effect as KeyframeEffect | null;
+  if (effect != null) {
+    restoreEffect(effect, saved);
+  }
+  const current = next as unknown as Writable;
+  for (const name of ['timeline', 'rangeStart', 'rangeEnd']) {
+    if (name in saved.values && differs(saved.values[name], current[name])) {
+      write(next, name, saved.values[name]);
+    }
+  }
+  for (const name of writableAccessors(next)) {
+    if (
+      !ORDERED.has(name) &&
+      name in saved.values &&
+      differs(saved.values[name], current[name])
+    ) {
+      write(next, name, saved.values[name]);
+    }
+  }
+  if (saved.replaceState === 'persisted' && next.replaceState !== 'persisted') {
+    next.persist();
+  }
+  const rate = saved.values.playbackRate;
+  if (typeof rate === 'number' && rate !== next.playbackRate) {
+    next.playbackRate = rate;
+  }
+  if (saved.playState === 'paused' && next.playState !== 'paused') {
+    next.pause();
+  } else if (saved.playState !== 'paused' && next.playState === 'paused') {
+    next.play();
+  }
+  // A running animation is anchored to its timeline by its start time, which
+  // carries its current time on exactly. A paused one has none and keeps its
+  // current time. A finished one holds its end: finishing it again holds the
+  // same time, though its start time is then counted from now, since script
+  // cannot set a start time and a held time together.
+  const start = saved.values.startTime as CSSNumberish | null | undefined;
+  const time = saved.values.currentTime as CSSNumberish | null | undefined;
+  if (saved.playState === 'finished') {
+    next.finish();
+  } else if (start != null) {
+    next.startTime = start;
+  } else if (time != null) {
+    next.currentTime = time;
+  }
+}
+
+/** Resume a cancelled CSS transition with a script animation in its state. */
+function resumeTransition(saved: Saved): void {
+  if (saved.target == null || saved.keyframes == null) {
+    return;
+  }
+  const replacement = saved.target.animate(saved.keyframes, {
+    pseudoElement: saved.pseudoElement ?? undefined,
+  });
+  restore(replacement, saved);
+}
+
+function isTransition(animation: Animation): boolean {
+  return (
+    typeof CSSTransition !== 'undefined' && animation instanceof CSSTransition
+  );
+}
+
+/**
+ * Run `reset`, which takes `root` out of rendering and back, and put every
+ * CSS animation and transition of `root` and its subtree back in the state it
+ * was in before. Recreated animations are matched to the ones they replace by
+ * element, pseudo-element and name, in order, and then by name alone (an
+ * effect script moved to another element or pseudo-element); a recreated
+ * animation with no predecessor (an entry animation that had already played
+ * and been dropped) is finished.
+ */
+export function preserveAnimations(root: Element, reset: () => void): void {
+  if (typeof root.getAnimations !== 'function') {
+    reset();
+    return;
+  }
+  const before = root.getAnimations({subtree: true});
+  const saved = before.map(save);
+  reset();
+  const after = root.getAnimations({subtree: true});
+  const current = new Set(after);
+  const survivors = new Set(before);
+  const cancelled: Saved[] = [];
+  for (const state of saved) {
+    if (current.has(state.animation)) {
+      continue;
+    }
+    if (isTransition(state.animation)) {
+      resumeTransition(state);
+    } else {
+      cancelled.push(state);
+    }
+  }
+  const recreated = after.filter(animation => !survivors.has(animation));
+  const unmatched: Animation[] = [];
+  for (const animation of recreated) {
+    const effect = animation.effect as KeyframeEffect | null;
+    const name =
+      (animation as Animation & {animationName?: string}).animationName ?? '';
+    const index = cancelled.findIndex(
+      state =>
+        state.name === name &&
+        state.target === (effect?.target ?? null) &&
+        state.pseudoElement === (effect?.pseudoElement ?? null),
+    );
+    if (index === -1) {
+      unmatched.push(animation);
+    } else {
+      restore(animation, cancelled.splice(index, 1)[0]);
+    }
+  }
+  for (const animation of unmatched) {
+    const name =
+      (animation as Animation & {animationName?: string}).animationName ?? '';
+    const index = cancelled.findIndex(state => state.name === name);
+    if (index === -1) {
+      animation.finish();
+    } else {
+      restore(animation, cancelled.splice(index, 1)[0]);
+    }
+  }
+}

package/src/Layer/useLayer.doc.mjs

@@ -86,7 +86,7 @@ export const docs = {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. Pass `offset` (a CSS length; a number is px) in context mode for clearance from the anchor: it applies to both edges of the placement axis, so the gap survives a flip. Layers are flush by default. Context mode first renders an inert `<template>` marker in matching server and client markup. The final layer stays at that JSX position if its parent is safe; otherwise it is portaled to the nearest ancestor outside paragraphs, links, buttons, inline formatting, and structurally restricted containers. The nearest safe host keeps CSS custom properties inheriting live, while the layer preserves direction and writing mode from its JSX position. By default this resolution occurs after hydration so closed-layer DOM remains available; `lazyMount` defers it until `show()` and unmounts the content again on hide while the marker remains. The Popover API promotes the layer to the top layer when shown, so it escapes ancestor clipping and stacking wherever it is hosted. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. Pass `offset` (a CSS length; a number is px) in context mode for clearance from the anchor: it applies to both edges of the placement axis, so the gap survives a flip. Layers are flush by default. Context mode first renders an inert `<template>` marker in matching server and client markup. The final layer stays at that JSX position if its parent is safe; otherwise it is portaled to the nearest ancestor outside paragraphs, links, buttons, inline formatting, and structurally restricted containers. The nearest safe host keeps CSS custom properties inheriting live, while the layer preserves direction and writing mode from its JSX position. By default this resolution occurs after hydration so closed-layer DOM remains available, and it re-renders only the slot that holds the marker and the layer, not the component that called the hook (which renders again only when a resolved mount is replaced by a render call that moved to another host); `lazyMount` defers it until `show()` and unmounts the content again on hide while the marker remains. The Popover API promotes the layer to the top layer when shown, so it escapes ancestor clipping and stacking wherever it is hosted. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
     },
   ],
   usage: {