@stacknav/core 0.2.0 → 0.3.0

package/src/edge-pan-gesture.ts

@@ -31,6 +31,8 @@ interface Drag {
   target: EventTarget & { setPointerCapture?(id: number): void };
   x0: number;
   y0: number;
+  /** +1 when back is a drag to the right, -1 when the container reads right-to-left */
+  dir: number;
   handle: InteractivePopHandle | null;
   p: number;
   samples: Array<[number, number]>;
@@ -41,6 +43,9 @@ interface Drag {
  * interactive pop from it. Built on pointer events, so it handles both mouse
  * and touch. Vertical movement early in the gesture hands the touch back to
  * native scrolling.
+ *
+ * "Leading" is whichever edge the container reads from, so in a right-to-left
+ * container the strip sits on the right and back is a drag to the left.
  */
 export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {}): EdgePanGesture {
   const o: EdgePanGestureOptions = {
@@ -57,6 +62,20 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
 
   let stack: NavigationStack;
   let strip: HTMLElement | null = null;
+
+  /**
+   * Which way forward is, read the same way the pages read it: `--sn-dir` when
+   * the stylesheet sets it, the container's reading direction otherwise. Taking
+   * it from one place is what keeps the drag and the transition from disagreeing
+   * about which edge is the back edge.
+   */
+  const direction = (): number => {
+    const style = typeof getComputedStyle === 'function' ? getComputedStyle(stack.container) : null;
+    const declared = Number(style?.getPropertyValue('--sn-dir'));
+    if (declared < 0) return -1;
+    if (declared > 0) return 1;
+    return style?.direction === 'rtl' ? -1 : 1;
+  };
   let drag: Drag | null = null;
   let suppressClick = false;
   let offs: Array<() => void> = [];
@@ -65,12 +84,14 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
     if (drag || !stack.canPop()) return;
     if (ev.pointerType === 'mouse' && ev.button !== 0) return;
     if (ev.currentTarget === stack.container && !o.anywhere) return;
-    drag = { id: ev.pointerId, target: ev.currentTarget as Drag['target'], x0: ev.clientX, y0: ev.clientY, handle: null, p: 1, samples: [[ev.clientX, performance.now()]] };
+    drag = { id: ev.pointerId, target: ev.currentTarget as Drag['target'], x0: ev.clientX, y0: ev.clientY, dir: direction(), handle: null, p: 1, samples: [[ev.clientX, performance.now()]] };
   };
 
   const onMove = (ev: PointerEvent) => {
     if (!drag || ev.pointerId !== drag.id) return;
-    const dx = ev.clientX - drag.x0;
+    // Signed so that "forward along the drag" is always positive, whichever
+    // edge the container calls leading.
+    const dx = (ev.clientX - drag.x0) * drag.dir;
     const dy = ev.clientY - drag.y0;
     if (!drag.handle) {
       if (Math.abs(dy) > o.verticalCancelSlop && Math.abs(dy) > Math.abs(dx)) {
@@ -104,7 +125,7 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
     const s = d.samples;
     const [x1, t1] = s[0];
     const [x2, t2] = s[s.length - 1];
-    const velocity = t2 > t1 ? ((x2 - x1) / (t2 - t1)) * 1000 : 0;
+    const velocity = (t2 > t1 ? ((x2 - x1) / (t2 - t1)) * 1000 : 0) * d.dir;
     const cancelled = ev.type === 'pointercancel';
     const complete = !cancelled && (velocity > o.completeVelocity || (d.p < 1 - o.completeThreshold && velocity > o.cancelVelocity));
     // The click that follows a drag release must not activate whatever is under the pointer.
@@ -126,10 +147,16 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
   const listen = (el: HTMLElement) => Object.entries(EVENTS).forEach(([k, f]) => el.addEventListener(k, f as EventListener));
   const unlisten = (el: HTMLElement) => Object.entries(EVENTS).forEach(([k, f]) => el.removeEventListener(k, f as EventListener));
 
+  /**
+   * Whether the strip is shown at all is a CSS question — the stylesheet hides
+   * it when there is nothing to go back to, or when the whole page is the
+   * target — so this only has to say what is true.
+   */
   const refresh = () => {
     if (!strip) return;
     strip.style.width = o.edgeWidth + 'px';
-    strip.style.display = o.anywhere || stack.entries.length < 2 ? 'none' : '';
+    stack.container.classList.toggle('sn-anywhere', o.anywhere);
+    stack.container.classList.toggle('sn-can-pop', stack.entries.length > 1);
   };
 
   const gesture: EdgePanGesture = {
@@ -138,8 +165,8 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
     attach(s) {
       stack = s;
       strip = document.createElement('div');
+      strip.className = 'sn-edge';
       strip.setAttribute('aria-hidden', 'true');
-      Object.assign(strip.style, { position: 'absolute', left: '0', top: '0', bottom: '0', zIndex: '10', touchAction: 'none' });
       stack.container.append(strip);
       listen(strip);
       listen(stack.container);
@@ -154,6 +181,7 @@ export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {
       unlisten(strip);
       unlisten(stack.container);
       stack.container.removeEventListener('click', onClick, true);
+      stack.container.classList.remove('sn-anywhere', 'sn-can-pop');
       strip.remove();
       strip = null;
     },

package/src/index.ts

@@ -24,7 +24,7 @@ export { createEdgePanGesture } from './edge-pan-gesture.ts';
 export type { EdgePanGesture, EdgePanGestureOptions } from './edge-pan-gesture.ts';
 export { attachBrowserHistory, isIOSBrowser } from './history-adapter.ts';
 export type { BrowserHistoryOptions } from './history-adapter.ts';
-export { cubicBezier, easings, tween, prefersReducedMotion } from './animate.ts';
+export { cubicBezier, easings, cssEasing, cssDuration, tween, commitStyles, animationsFinished, prefersReducedMotion } from './animate.ts';
 export type { Easing, TweenOptions, CancellableTween } from './animate.ts';
 export {
   resolveDirection,

package/src/ios-transition.ts

@@ -5,7 +5,13 @@ import type { SettleInput, StackEntry, Transition } from './navigation-stack.ts'
 export interface IOSTransitionOptions {
   /** ms, programmatic push/pop */
   duration: number;
-  /** the curve a programmatic push/pop runs on */
+  /**
+   * the curve a programmatic push/pop runs on. CSS runs it, so it has to be
+   * one CSS can spell: everything `cubicBezier()` and `parseEasing()` build
+   * carries a `css` property. A bare `(t) => number` of your own has none, so
+   * the pages would run `linear` while `progress` reported your curve; give it
+   * a `css` property, or write the whole transition yourself.
+   */
   ease: Easing;
   /** fraction of the width the lower page travels */
   parallax: number;
@@ -17,7 +23,7 @@ export interface IOSTransitionOptions {
   /** ms bounds for finishing an interactive pop */
   settleMin: number;
   settleMax: number;
-  /** the curve the remaining distance of an interactive pop runs on */
+  /** the curve the remaining distance of an interactive pop runs on; see `ease` */
   settleEase: Easing;
   /** px/s assumed when the pointer was slower than this */
   settleVelocityFloor: number;
@@ -53,9 +59,6 @@ export interface IOSTransition extends Transition {
   refresh(el?: Element | null): void;
 }
 
-const DIM = /*#__PURE__*/ Symbol('dim');
-type Dimmable = StackEntry & { [DIM]?: HTMLElement };
-
 /**
  * The iOS navigation transition: the upper page slides in from the trailing
  * edge with a shadow on its leading edge, while the lower page parallaxes
@@ -65,6 +68,11 @@ type Dimmable = StackEntry & { [DIM]?: HTMLElement };
  * `IOS_TRANSITION_CSS_VARS`), read when a transition starts. A variable that
  * is set wins over the JS option, so a stylesheet can slow the animation down
  * or restyle it per theme without the app rebuilding the transition.
+ *
+ * p is only ever written at the ends of a phase. The stack puts that phase's
+ * duration and curve in `--sn-t` / `--sn-e` and CSS interpolates between the
+ * two writes, so the animation costs a handful of style writes rather than one
+ * per page per frame, and runs on the compositor rather than the main thread.
  */
 export function createIOSTransition(options: Partial<IOSTransitionOptions> = {}): IOSTransition {
   const o: IOSTransitionOptions = {
@@ -104,19 +112,25 @@ export function createIOSTransition(options: Partial<IOSTransitionOptions> = {})
     };
   };
 
-  const dimOf = (entry: Dimmable): HTMLElement => {
-    let d = entry[DIM];
-    if (!d) {
-      d = document.createElement('div');
-      d.setAttribute('aria-hidden', 'true');
-      Object.assign(d.style, { position: 'fixed', inset: '0', pointerEvents: 'none', opacity: '0', zIndex: '2147483647' });
-      entry[DIM] = d;
+  // One overlay, moved to whichever page is underneath. Everything about it
+  // except its colour and its opacity is a rule in the stylesheet.
+  let dim: HTMLElement | null = null;
+  const dimOf = (lower: StackEntry): HTMLElement => {
+    if (!dim) {
+      dim = document.createElement('div');
+      dim.className = 'sn-dim';
+      dim.setAttribute('aria-hidden', 'true');
     }
-    d.style.background = r.dimColor;
-    if (d.parentElement !== entry.el) entry.el.append(d);
-    return d;
+    dim.style.background = r.dimColor;
+    if (dim.parentElement !== lower.el) lower.el.append(dim);
+    return dim;
   };
 
+  /** Four decimals is well past a subpixel, and keeps the style strings short. */
+  const round = (n: number): number => Math.round(n * 1e4) / 1e4 || 0;
+  /** A share of the page's own width, signed by the stylesheet's reading direction. */
+  const shift = (fraction: number): string => `translate3d(calc(${round(fraction * 100)}% * var(--sn-dir,1)),0,0)`;
+
   return {
     options: o,
     get resolved(): Readonly<IOSTransitionOptions> {
@@ -142,22 +156,24 @@ export function createIOSTransition(options: Partial<IOSTransitionOptions> = {})
       upper.el.style.boxShadow = r.shadow;
       if (lower) dimOf(lower);
     },
+    /**
+     * The state at p, written declaratively. Two calls with `--sn-t` set to a
+     * duration make an animation; a call per pointer move with `--sn-t: 0s`
+     * makes a drag. Nothing here measures layout: the travel is a share of the
+     * page, so a resize mid-transition stays honest.
+     */
     apply(lower, upper, p) {
-      const w = upper.el.parentElement?.clientWidth ?? 0;
-      upper.el.style.transform = `translate3d(${(1 - p) * w}px,0,0)`;
+      upper.el.style.transform = shift(1 - p);
       if (lower) {
-        lower.el.style.transform = `translate3d(${-p * r.parallax * w}px,0,0)`;
+        lower.el.style.transform = shift(-p * r.parallax);
         dimOf(lower).style.opacity = String(p * r.dimMax);
       }
     },
     end(lower, upper) {
       upper.el.style.boxShadow = '';
       upper.el.style.transform = '';
-      if (lower) {
-        lower.el.style.transform = '';
-        const d = (lower as Dimmable)[DIM];
-        if (d) d.remove();
-      }
+      if (lower) lower.el.style.transform = '';
+      dim?.remove();
     },
   };
 }

package/src/navigation-stack.ts

@@ -1,4 +1,4 @@
-import { tween, type Easing } from './animate.ts';
+import { animationsFinished, commitStyles, cssDuration, cssEasing, tween, type CancellableTween, type Easing } from './animate.ts';
 
 /** One mounted page. `key` and `data` belong to the caller; the stack only carries them. */
 export interface StackEntry<T = unknown> {
@@ -17,9 +17,17 @@ export interface SettleInput {
  * Describes what the pages look like at any progress p (1 = upper page fully
  * open, 0 = upper page fully off-screen). Push runs p from 0 to 1, pop from
  * 1 to 0.
+ *
+ * `apply` is a declarative write, not a frame. For a timed phase the stack
+ * calls it twice, once at each end, and CSS interpolates between them: the
+ * stack puts that phase's duration and curve in `--sn-t` / `--sn-e` on the
+ * container, which the stylesheet's `transition` rules read. During a drag
+ * `--sn-t` is `0s`, so the same write lands instantly. Keep `apply` to
+ * `transform` and `opacity` and the browser keeps it off the main thread.
  */
 export interface Transition {
   readonly duration: number;
+  /** Sampled to report `progress`; its `css` spelling is what drives the pixels. */
   readonly ease: Easing;
   settle(input: SettleInput): { duration: number; ease: Easing };
   begin?(lower: StackEntry | null, upper: StackEntry): void;
@@ -249,7 +257,7 @@ export class NavigationStack {
       finish: async ({ complete, velocity = 0 }) => {
         const remainingPx = (complete ? p : 1 - p) * this.width();
         const { duration, ease } = this.transition.settle({ remainingPx, velocity });
-        await tween({ from: p, to: complete ? 0 : 1, duration, ease, onUpdate: (v) => this._apply(lower, upper, v) });
+        await this._animate(lower, upper, p, complete ? 0 : 1, duration, ease);
         this._end(lower, upper, 'interactive');
         if (complete) {
           this.entries.pop();
@@ -265,7 +273,9 @@ export class NavigationStack {
 
   destroy(): void {
     while (this.entries.length) this._unmount(this.entries.pop()!);
-    this.container.classList.remove('sn-container');
+    this.container.classList.remove('sn-container', 'sn-busy');
+    this.container.style.removeProperty('--sn-t');
+    this.container.style.removeProperty('--sn-e');
   }
 
   // -------------------------------------------------------------- internals
@@ -315,7 +325,7 @@ export class NavigationStack {
     return { el, index, key, data };
   }
   private _unmount(entry: StackEntry): StackEntry {
-    entry.el.classList.remove(this.pageClass, 'sn-page-visible');
+    entry.el.classList.remove(this.pageClass, 'sn-page-visible', 'sn-page-upper', 'sn-page-lower');
     entry.el.style.transform = '';
     entry.el.remove();
     return entry;
@@ -328,35 +338,82 @@ export class NavigationStack {
     return this._unmount(entry);
   }
 
+  /**
+   * The duration and curve of the phase in flight, as CSS reads them. `0s`
+   * means land where you are told, now, which is what a drag wants and what
+   * `prefers-reduced-motion` reduces every phase to.
+   */
+  private _timing(duration: number, ease?: Easing): void {
+    this.container.style.setProperty('--sn-t', cssDuration(duration));
+    this.container.style.setProperty('--sn-e', cssEasing(ease));
+  }
+
   private _begin(lower: StackEntry | null, upper: StackEntry, kind: TransitionKind): void {
-    if (lower) lower.el.classList.add('sn-page-visible');
-    upper.el.classList.add('sn-page-visible');
+    this._timing(0);
+    lower?.el.classList.add('sn-page-visible', 'sn-page-lower');
+    upper.el.classList.add('sn-page-visible', 'sn-page-upper');
     this.transition.begin?.(lower, upper);
     this._emit('transitionstart', { lower, upper, kind });
   }
-  private _apply(lower: StackEntry | null, upper: StackEntry, p: number): void {
+  /** Writes the state at p without announcing it: the ticker reports the way there. */
+  private _write(lower: StackEntry | null, upper: StackEntry, p: number): void {
     this.transition.apply(lower, upper, p);
+  }
+  private _apply(lower: StackEntry | null, upper: StackEntry, p: number): void {
+    this._write(lower, upper, p);
     this._emit('progress', { lower, upper, p });
   }
   private _end(lower: StackEntry | null, upper: StackEntry, kind: TransitionKind): void {
+    this._timing(0);
+    upper.el.classList.remove('sn-page-upper');
+    lower?.el.classList.remove('sn-page-lower');
     this.transition.end?.(lower, upper);
     this._emit('transitionend', { lower, upper, kind });
   }
+
+  /**
+   * Hands the run from `from` to `to` over to the browser: commit where the
+   * pages are, say how long and on what curve, write where they are going,
+   * then wait to be told they arrived. No frame of it is ours.
+   */
+  private async _animate(lower: StackEntry | null, upper: StackEntry, from: number, to: number, duration: number, ease: Easing): Promise<void> {
+    if (duration <= 0) return this._apply(lower, upper, to);
+    commitStyles(upper.el);
+    this._timing(duration, ease);
+    this._write(lower, upper, to);
+    const ticker = this._ticker(lower, upper, from, to, duration, ease);
+    await animationsFinished([upper.el, lower?.el]);
+    ticker?.cancel();
+    this._timing(0);
+    this._emit('progress', { lower, upper, p: to });
+  }
+
+  /**
+   * `progress` used to be a by-product of animating in JS. Now that CSS
+   * animates, reporting it costs a frame loop, so one only runs while someone
+   * is subscribed. Chrome that just has to move with the pages is better off
+   * reading `--sn-t` / `--sn-e` and the `sn-page-upper` / `sn-page-lower`
+   * classes in CSS, which keeps it on the compositor too.
+   */
+  private _ticker(lower: StackEntry | null, upper: StackEntry, from: number, to: number, duration: number, ease: Easing): CancellableTween | null {
+    if (!this._listeners.get('progress')?.size) return null;
+    return tween({ from, to, duration, ease, onUpdate: (p) => this._emit('progress', { lower, upper, p }) });
+  }
+
   private async _transition(lower: StackEntry | null, upper: StackEntry, from: number, to: number, animated: boolean, kind: TransitionKind): Promise<void> {
     this._begin(lower, upper, kind);
     this._apply(lower, upper, from);
-    const duration = animated ? this.transition.duration : 0;
-    await tween({ from, to, duration, ease: this.transition.ease, onUpdate: (p) => this._apply(lower, upper, p) });
+    await this._animate(lower, upper, from, to, animated ? this.transition.duration : 0, this.transition.ease);
     this._end(lower, upper, kind);
   }
 
-  /** Makes only the top page visible, resets every transform, renumbers the indexes. */
+  /** Makes only the top page visible, returns every page to its resting state, renumbers the indexes. */
   private _settle(): void {
     const top = this.top;
     this.entries.forEach((e, i) => {
       e.index = i;
       e.el.classList.toggle('sn-page-visible', e === top);
-      e.el.style.transform = e === top ? 'translate3d(0,0,0)' : '';
+      e.el.style.transform = '';
     });
   }
 }

package/src/styles.ts

@@ -1,27 +1,56 @@
 /**
- * The only styles the engine needs. These cover layout, not appearance: the
- * look lives in the transition and is tuned through the `--sn-*` custom
- * properties (see `IOS_TRANSITION_CSS_VARS` and the README). Those properties
- * are documented but deliberately not declared, because leaving one unset is
- * what makes its JS default apply.
+ * The only styles the engine needs. These cover layout and the motion itself,
+ * not appearance: the look lives in the transition and is tuned through the
+ * `--sn-*` custom properties (see `IOS_TRANSITION_CSS_VARS` and the README).
+ * Those properties are documented but deliberately not declared, because
+ * leaving one unset is what makes its JS default apply.
+ *
+ * The engine does not animate the pages; the browser does. Each phase it
+ * writes `--sn-t` and `--sn-e` on the container — the duration and curve in
+ * force right now — and then writes where the pages should end up. While a
+ * pointer is down `--sn-t` is `0s`, so the page lands exactly where the
+ * pointer puts it; for a push, a pop or the settle after a release it is that
+ * phase's length and `transition` runs it out, on the compositor.
  *
  * The string is kept minified because it ships inside every consumer's JS
  * bundle (`injectStyles()` is the default path); `scripts/write-css.mjs`
  * expands it into the readable `dist/stacknav.css`. What each rule is for:
  *
  * - `.sn-container`: the stack's scroll-clipping frame.
+ * - `.sn-container:dir(rtl)`: reading direction is a CSS question, so the
+ *   transform the engine writes is signed by `--sn-dir` rather than by JS.
  * - `.sn-page`: absolutely fills the container and is its own scroll container.
  *   `touch-action: pan-y` keeps vertical scrolling native while horizontal
  *   drags reach the gesture; `visibility: hidden` keeps pages beneath the top
  *   mounted (scroll position, form state) but out of sight and out of the
- *   accessibility tree.
+ *   accessibility tree. The identity transform is the resting state, and the
+ *   containing block the dim overlay is positioned against.
  * - `.sn-page-visible`: the top page, and both pages during a transition.
- * - `.sn-busy .sn-page`: no clicks land on a page that is mid-transition.
+ * - `.sn-page-upper` / `.sn-page-lower`: the two pages taking part in the
+ *   transition in flight. Only these transition, and only these are promoted,
+ *   so a deep stack costs nothing at rest. Both `transform` and `opacity` are
+ *   listed, so a transition of your own can fade a page as well as move it and
+ *   still be run by the browser; the iOS look only ever changes `transform`,
+ *   and a property that does not change starts no transition.
+ * - `.sn-dim`: the overlay the lower page dims behind. Its colour and its
+ *   opacity are written by the transition; everything else is here.
+ * - `.sn-edge`: the strip the swipe-back gesture listens on. `inset-inline-start`
+ *   puts it on the leading edge in either reading direction; its width is the
+ *   gesture's `edgeWidth` option, and whether it is shown at all follows from
+ *   the container's classes.
+ * - `.sn-busy`: no clicks land on a page that is mid-transition, and a drag
+ *   does not select the text under it.
  */
 export const STACKNAV_CSS =
   '.sn-container{position:relative;overflow:hidden}' +
-  '.sn-page{position:absolute;inset:0;overflow-y:auto;overflow-x:hidden;-webkit-overflow-scrolling:touch;overscroll-behavior-y:contain;touch-action:pan-y;visibility:hidden;will-change:transform}' +
+  '.sn-container:dir(rtl){--sn-dir:-1}' +
+  '.sn-page{position:absolute;inset:0;overflow-y:auto;overflow-x:hidden;-webkit-overflow-scrolling:touch;overscroll-behavior-y:contain;touch-action:pan-y;visibility:hidden;transform:translate3d(0,0,0)}' +
   '.sn-page-visible{visibility:visible}' +
+  '.sn-page-upper,.sn-page-lower{will-change:transform;transition-property:transform,opacity;transition-duration:var(--sn-t,0s);transition-timing-function:var(--sn-e,linear)}' +
+  '.sn-dim{position:fixed;inset:0;z-index:2147483647;pointer-events:none;opacity:0;transition:opacity var(--sn-t,0s) var(--sn-e,linear)}' +
+  '.sn-edge{position:absolute;inset-block:0;inset-inline-start:0;z-index:10;touch-action:none}' +
+  '.sn-container:not(.sn-can-pop) .sn-edge,.sn-container.sn-anywhere .sn-edge{display:none}' +
+  '.sn-busy{user-select:none;-webkit-user-select:none}' +
   '.sn-busy .sn-page{pointer-events:none}';
 
 export const STACKNAV_STYLE_ID = 'stacknav-styles';