@stacknav/core 0.2.0

package/src/animate.ts

@@ -0,0 +1,80 @@
+// A small animation toolkit: a cubic-bezier solver, a cancellable tween, and
+// the easing curves the iOS transition uses.
+
+export type Easing = (t: number) => number;
+
+export function cubicBezier(x1: number, y1: number, x2: number, y2: number): Easing {
+  const A = (a: number, b: number) => 1 - 3 * b + 3 * a;
+  const B = (a: number, b: number) => 3 * b - 6 * a;
+  const C = (a: number) => 3 * a;
+  const calc = (t: number, a: number, b: number) => ((A(a, b) * t + B(a, b)) * t + C(a)) * t;
+  const slope = (t: number, a: number, b: number) => 3 * A(a, b) * t * t + 2 * B(a, b) * t + C(a);
+  return (x) => {
+    if (x <= 0) return 0;
+    if (x >= 1) return 1;
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+      const s = slope(t, x1, x2);
+      if (s === 0) break;
+      t -= (calc(t, x1, x2) - x) / s;
+    }
+    return calc(t, y1, y2);
+  };
+}
+
+// `#__PURE__` marks the module-load calls as droppable, so a bundler that does
+// not honour the package's `sideEffects` flag can still leave this module out
+// when nothing here is imported.
+export const easings: { linear: Easing; ios: Easing; easeOut: Easing } = {
+  linear: (t) => t,
+  ios: /*#__PURE__*/ cubicBezier(0.32, 0.72, 0, 1), // the common approximation of UIKit's navigation curve
+  easeOut: /*#__PURE__*/ cubicBezier(0.2, 0.8, 0.2, 1),
+};
+
+export interface TweenOptions {
+  from: number;
+  to: number;
+  duration: number;
+  ease?: Easing;
+  onUpdate: (value: number) => void;
+}
+
+export type CancellableTween = Promise<void> & { cancel(): void };
+
+/**
+ * Animates a number from `from` to `to` over `duration` ms, calling `onUpdate`
+ * every frame. Returns a promise that resolves when the tween is done;
+ * `promise.cancel()` stops it early. A duration of 0 or less jumps straight
+ * to `to`.
+ */
+export function tween({ from, to, duration, ease = easings.linear, onUpdate }: TweenOptions): CancellableTween {
+  let raf = 0;
+  let done = false;
+  const promise = new Promise<void>((resolve) => {
+    if (duration <= 0) {
+      onUpdate(to);
+      done = true;
+      return resolve();
+    }
+    const t0 = performance.now();
+    const step = (now: number) => {
+      if (done) return;
+      const k = Math.min(1, (now - t0) / duration);
+      onUpdate(from + (to - from) * ease(k));
+      if (k < 1) raf = requestAnimationFrame(step);
+      else {
+        done = true;
+        resolve();
+      }
+    };
+    raf = requestAnimationFrame(step);
+  }) as CancellableTween;
+  promise.cancel = () => {
+    done = true;
+    cancelAnimationFrame(raf);
+  };
+  return promise;
+}
+
+export const prefersReducedMotion = (): boolean =>
+  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;

package/src/css-vars.ts

@@ -0,0 +1,91 @@
+// Reads the engine's options from CSS custom properties, so the transition can
+// be tuned from a stylesheet (a media query, a theme class, a single container)
+// instead of only from JS. Values are parsed the way CSS reads them: `300ms`,
+// `0.4s`, `30%`, `cubic-bezier(...)`.
+//
+// Every parser returns undefined for anything it does not understand, never
+// NaN, so an unreadable value falls through to its JS option instead of
+// producing an invalid transform.
+
+import { cubicBezier, easings, type Easing } from './animate.ts';
+
+/** Looks a custom property up on an element; `undefined` when it is not set. */
+export type CSSVarReader = (name: string) => string | undefined;
+
+/**
+ * Returns a reader over `el`'s computed custom properties. Custom properties
+ * inherit, so a variable set on `:root` or any ancestor is visible here. When
+ * there is no element or no `getComputedStyle` (SSR, tests), the reader finds
+ * nothing and every caller falls back to its JS option.
+ */
+export function cssVars(el: Element | null | undefined): CSSVarReader {
+  const style = el && typeof getComputedStyle === 'function' ? getComputedStyle(el) : null;
+  if (!style) return () => undefined;
+  return (name) => {
+    const v = style.getPropertyValue(name)?.trim();
+    return v ? v : undefined;
+  };
+}
+
+const NUMBER = /^[-+]?(?:\d+\.?\d*|\.\d+)$/;
+
+/** `500ms`, `0.4s`, or a bare number of milliseconds. */
+export function parseTime(v: string | undefined): number | undefined {
+  const m = v === undefined ? null : /^([-+]?(?:\d+\.?\d*|\.\d+))(ms|s)?$/i.exec(v.trim());
+  if (!m) return undefined;
+  return m[2]?.toLowerCase() === 's' ? Number(m[1]) * 1000 : Number(m[1]);
+}
+
+export function parseNumber(v: string | undefined): number | undefined {
+  const s = v?.trim();
+  return s !== undefined && NUMBER.test(s) ? Number(s) : undefined;
+}
+
+/** A fraction. `0.3` and `30%` are equivalent. */
+export function parseRatio(v: string | undefined): number | undefined {
+  const s = v?.trim();
+  if (s === undefined) return undefined;
+  if (!s.endsWith('%')) return parseNumber(s);
+  const n = parseNumber(s.slice(0, -1));
+  return n === undefined ? undefined : n / 100;
+}
+
+/**
+ * The CSS timing keywords that are cubic curves, plus the two this engine
+ * ships. Null-prototype, so `__proto__` and `constructor` miss like any other
+ * unknown word instead of returning a truthy non-easing value.
+ *
+ * Built on first use rather than at module load: solving four curves here
+ * would be work a bundler cannot prove pointless, which would keep this
+ * module (and `easings`) in bundles that never parse a CSS variable.
+ */
+let easingKeywords: Record<string, Easing> | undefined;
+const easingKeywordsOf = (): Record<string, Easing> =>
+  (easingKeywords ??= Object.assign(Object.create(null), {
+    linear: easings.linear,
+    ease: cubicBezier(0.25, 0.1, 0.25, 1),
+    'ease-in': cubicBezier(0.42, 0, 1, 1),
+    'ease-out': cubicBezier(0, 0, 0.58, 1),
+    'ease-in-out': cubicBezier(0.42, 0, 0.58, 1),
+    ios: easings.ios,
+    'ios-settle': easings.easeOut,
+  }));
+
+/**
+ * A timing keyword or `cubic-bezier(x1, y1, x2, y2)`. The x coordinates must be
+ * within [0, 1], as CSS requires. Outside that range the curve is not a
+ * function of time and the solver would not converge.
+ */
+export function parseEasing(v: string | undefined): Easing | undefined {
+  if (v === undefined) return undefined;
+  const s = v.trim().toLowerCase();
+  const keyword = easingKeywordsOf()[s];
+  if (keyword) return keyword;
+  const m = /^cubic-bezier\(([^)]*)\)$/.exec(s);
+  if (!m) return undefined;
+  const n = m[1].split(',').map((part) => parseNumber(part));
+  if (n.length !== 4 || n.some((x) => x === undefined)) return undefined;
+  const [x1, y1, x2, y2] = n as number[];
+  if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1) return undefined;
+  return cubicBezier(x1, y1, x2, y2);
+}

package/src/direction.ts

@@ -0,0 +1,146 @@
+/**
+ * Direction resolution: given where the app is and where it is going, decide
+ * whether the new page should push over the current one, pop back to it, or
+ * replace it. The engine does not decide this on its own. A host supplies an
+ * ordered list of strategies, and the first one with an answer wins.
+ *
+ * Strategies are plain functions, so a host can add its own (a numbering
+ * scheme, a route-tree walk, a per-navigation hint) without changing the rest.
+ */
+
+export type Direction = 'push' | 'pop' | 'replace';
+
+/** What a strategy may return: a direction, or no answer (`'auto'`, `undefined`, `null`). */
+export type DirectionOpinion = Direction | 'auto' | undefined | null | void;
+
+/** The minimum a strategy needs to know about a page. Hosts may attach more. */
+export interface RouteRef {
+  /** stable identity of the page: its URL, a route id, anything unique */
+  key: string;
+  /** the page's position in the route tree, e.g. URL segments (`['items', '42']`) */
+  segments?: readonly string[];
+  /** an explicit number when the app numbers its screens: bigger is deeper */
+  level?: number | null;
+  /** anything the host wants strategies to see (route data, params) */
+  data?: Record<string, unknown>;
+}
+
+export type NavigationTrigger = 'imperative' | 'history';
+
+export interface NavigationContext {
+  /** the page on screen, or null when the stack is empty */
+  from: RouteRef | null;
+  to: RouteRef;
+  /** `imperative`: the app navigated. `history`: the browser's back/forward. */
+  trigger?: NavigationTrigger;
+  /** for history triggers, when known: negative = back, positive = forward */
+  historyDelta?: number;
+  /** an explicit direction from the caller, if any */
+  hint?: DirectionOpinion;
+  /** keys of the pages currently kept alive, bottom to top */
+  stack?: readonly string[];
+}
+
+export type DirectionStrategy = (ctx: NavigationContext) => DirectionOpinion;
+
+export interface DirectionResolver {
+  (ctx: NavigationContext): Direction;
+  readonly strategies: readonly DirectionStrategy[];
+  readonly fallback: Direction;
+}
+
+const isDirection = (v: DirectionOpinion): v is Direction => v === 'push' || v === 'pop' || v === 'replace';
+
+/** Calls each strategy in turn. The first direction returned wins, else `fallback`. */
+export function resolveDirection(strategies: readonly DirectionStrategy[], ctx: NavigationContext, fallback: Direction = 'push'): Direction {
+  for (const s of strategies) {
+    const d = s(ctx);
+    if (isDirection(d)) return d;
+  }
+  return fallback;
+}
+
+/** Bundles strategies and a fallback into a single resolver function. */
+export function createDirectionResolver(strategies: readonly DirectionStrategy[] = defaultStrategies(), fallback: Direction = 'push'): DirectionResolver {
+  const resolver = ((ctx: NavigationContext) => resolveDirection(strategies, ctx, fallback)) as DirectionResolver;
+  Object.defineProperty(resolver, 'strategies', { value: strategies.slice(), enumerable: true });
+  Object.defineProperty(resolver, 'fallback', { value: fallback, enumerable: true });
+  return resolver;
+}
+
+// ------------------------------------------------------------------ strategies
+
+/** Honors an explicit per-navigation hint, e.g. `{ info: { stacknav: 'pop' } }` in Angular's router. */
+export const fromHint = (): DirectionStrategy => (ctx) => ctx.hint;
+
+/** Browser back is a pop, browser forward is a push. No answer for imperative navigations. */
+export const fromHistory = (): DirectionStrategy => (ctx) => {
+  if (ctx.trigger !== 'history' || !ctx.historyDelta) return undefined;
+  return ctx.historyDelta < 0 ? 'pop' : 'push';
+};
+
+/** Navigating to a page still kept beneath the current one is a pop back to it. */
+export const fromStack = (): DirectionStrategy => (ctx) => {
+  const stack = ctx.stack;
+  if (!stack || stack.length < 2) return undefined;
+  const i = stack.lastIndexOf(ctx.to.key);
+  if (i < 0 || i === stack.length - 1) return undefined;
+  return 'pop';
+};
+
+export interface LevelOptions {
+  /** the direction when both pages carry the same number (default `replace`) */
+  sameLevel?: DirectionOpinion;
+}
+
+/**
+ * For apps that number their screens (`level: 1`, `level: 2`, …): a higher
+ * number pushes, a lower one pops. No answer unless both pages carry a number.
+ */
+export const fromLevel = ({ sameLevel = 'replace' }: LevelOptions = {}): DirectionStrategy => (ctx) => {
+  const a = ctx.from?.level;
+  const b = ctx.to.level;
+  if (typeof a !== 'number' || typeof b !== 'number') return undefined;
+  if (b > a) return 'push';
+  if (b < a) return 'pop';
+  return sameLevel;
+};
+
+export interface TreeOptions {
+  /** the direction for two unrelated pages at the same depth, e.g. siblings (default `replace`) */
+  sameDepth?: DirectionOpinion;
+}
+
+/**
+ * Reads the route tree: a descendant of the current page pushes, an ancestor
+ * pops. Otherwise a deeper page pushes and a shallower one pops. Requires
+ * `segments` on both pages.
+ */
+export const fromTree = ({ sameDepth = 'replace' }: TreeOptions = {}): DirectionStrategy => (ctx) => {
+  const a = ctx.from?.segments;
+  const b = ctx.to.segments;
+  if (!a || !b) return undefined;
+  if (isPrefix(a, b)) return b.length > a.length ? 'push' : sameDepth;
+  if (isPrefix(b, a)) return 'pop';
+  if (b.length > a.length) return 'push';
+  if (b.length < a.length) return 'pop';
+  return sameDepth;
+};
+
+/** Always returns the same direction. Useful as the last entry in a list. */
+export const always = (direction: Direction): DirectionStrategy => () => direction;
+
+/** The default order: an explicit hint, then browser history, then the kept stack, then numbering, then the tree. */
+export const defaultStrategies = (): DirectionStrategy[] => [fromHint(), fromHistory(), fromStack(), fromLevel(), fromTree()];
+
+function isPrefix(prefix: readonly string[], of: readonly string[]): boolean {
+  if (prefix.length > of.length) return false;
+  for (let i = 0; i < prefix.length; i++) if (prefix[i] !== of[i]) return false;
+  return true;
+}
+
+/** Split a URL path into segments, ignoring the query, fragment and empty parts. */
+export function segmentsOf(url: string): string[] {
+  const path = url.split(/[?#]/, 1)[0];
+  return path.split('/').filter(Boolean);
+}

package/src/edge-pan-gesture.ts

@@ -0,0 +1,162 @@
+import type { InteractivePopHandle, NavigationStack } from './navigation-stack.ts';
+
+export interface EdgePanGestureOptions {
+  /** px strip on the leading edge that starts the gesture */
+  edgeWidth: number;
+  /** recognize the drag from anywhere on the page */
+  anywhere: boolean;
+  /** px of horizontal movement before the drag begins */
+  startSlop: number;
+  /** px of vertical movement that hands the touch back to scrolling */
+  verticalCancelSlop: number;
+  /** fraction of the width dragged that completes without velocity */
+  completeThreshold: number;
+  /** px/s toward the trailing edge that completes the pop regardless of distance */
+  completeVelocity: number;
+  /** px/s back toward the leading edge that cancels the pop regardless of distance */
+  cancelVelocity: number;
+  velocitySamples: number;
+}
+
+export interface EdgePanGesture {
+  readonly options: EdgePanGestureOptions;
+  /** Re-reads options changed at runtime, such as `edgeWidth` and `anywhere`. */
+  refresh(): void;
+  attach(stack: NavigationStack): EdgePanGesture;
+  detach(): void;
+}
+
+interface Drag {
+  id: number;
+  target: EventTarget & { setPointerCapture?(id: number): void };
+  x0: number;
+  y0: number;
+  handle: InteractivePopHandle | null;
+  p: number;
+  samples: Array<[number, number]>;
+}
+
+/**
+ * Recognizes a horizontal drag from the leading edge and drives the stack's
+ * 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.
+ */
+export function createEdgePanGesture(options: Partial<EdgePanGestureOptions> = {}): EdgePanGesture {
+  const o: EdgePanGestureOptions = {
+    edgeWidth: 28,
+    anywhere: false,
+    startSlop: 6,
+    verticalCancelSlop: 10,
+    completeThreshold: 0.5,
+    completeVelocity: 500,
+    cancelVelocity: -500,
+    velocitySamples: 6,
+    ...options,
+  };
+
+  let stack: NavigationStack;
+  let strip: HTMLElement | null = null;
+  let drag: Drag | null = null;
+  let suppressClick = false;
+  let offs: Array<() => void> = [];
+
+  const onDown = (ev: PointerEvent) => {
+    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()]] };
+  };
+
+  const onMove = (ev: PointerEvent) => {
+    if (!drag || ev.pointerId !== drag.id) return;
+    const dx = ev.clientX - drag.x0;
+    const dy = ev.clientY - drag.y0;
+    if (!drag.handle) {
+      if (Math.abs(dy) > o.verticalCancelSlop && Math.abs(dy) > Math.abs(dx)) {
+        drag = null;
+        return;
+      }
+      if (dx < o.startSlop) return;
+      const handle = stack.beginInteractivePop();
+      if (!handle) {
+        drag = null;
+        return;
+      }
+      drag.handle = handle;
+      try {
+        drag.target.setPointerCapture?.(ev.pointerId);
+      } catch {
+        /* capture is best-effort */
+      }
+    }
+    drag.samples.push([ev.clientX, performance.now()]);
+    if (drag.samples.length > o.velocitySamples) drag.samples.shift();
+    drag.p = 1 - Math.min(1, Math.max(0, (dx - o.startSlop) / stack.width()));
+    drag.handle.update(drag.p);
+  };
+
+  const onUp = (ev: PointerEvent) => {
+    if (!drag || ev.pointerId !== drag.id) return;
+    const d = drag;
+    drag = null;
+    if (!d.handle) return;
+    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 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.
+    suppressClick = true;
+    setTimeout(() => {
+      suppressClick = false;
+    }, 0);
+    void d.handle.finish({ complete, velocity });
+  };
+
+  const onClick = (ev: Event) => {
+    if (suppressClick) {
+      ev.stopPropagation();
+      ev.preventDefault();
+    }
+  };
+
+  const EVENTS: Record<string, (ev: PointerEvent) => void> = { pointerdown: onDown, pointermove: onMove, pointerup: onUp, pointercancel: onUp };
+  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));
+
+  const refresh = () => {
+    if (!strip) return;
+    strip.style.width = o.edgeWidth + 'px';
+    strip.style.display = o.anywhere || stack.entries.length < 2 ? 'none' : '';
+  };
+
+  const gesture: EdgePanGesture = {
+    options: o,
+    refresh,
+    attach(s) {
+      stack = s;
+      strip = document.createElement('div');
+      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);
+      stack.container.addEventListener('click', onClick, true);
+      offs = (['push', 'pop', 'replace', 'reset'] as const).map((e) => stack.on(e, refresh));
+      refresh();
+      return gesture;
+    },
+    detach() {
+      if (!strip) return;
+      offs.forEach((f) => f());
+      unlisten(strip);
+      unlisten(stack.container);
+      stack.container.removeEventListener('click', onClick, true);
+      strip.remove();
+      strip = null;
+    },
+  };
+  return gesture;
+}

package/src/history-adapter.ts

@@ -0,0 +1,52 @@
+import type { NavigationStack } from './navigation-stack.ts';
+
+export interface BrowserHistoryOptions {
+  /** the `history.state` property that carries the depth */
+  key?: string;
+  /** animate pops triggered by the back button. Off on iOS browsers, which animate their own snapshot */
+  animateHistoryPop?: boolean;
+  /** forward navigation has no page to show. Re-push something here instead of bouncing back */
+  onForward?: ((targetDepth: number) => void) | null;
+}
+
+/**
+ * For apps without a router. Mirrors the stack depth into `history.state`, so
+ * the browser or hardware back button pops the stack and stack pops walk
+ * history back. Returns a function that detaches everything.
+ */
+export function attachBrowserHistory(stack: NavigationStack, { key = 'snDepth', animateHistoryPop = !isIOSBrowser(), onForward = null }: BrowserHistoryOptions = {}): () => void {
+  const depthOf = (state: unknown): number => {
+    const s = state as Record<string, unknown> | null;
+    return s && Number.isInteger(s[key]) ? (s[key] as number) : 0;
+  };
+  const write = (kind: 'pushState' | 'replaceState') => history[kind]({ ...((history.state as object) || {}), [key]: stack.depth - 1 }, '');
+
+  write('replaceState');
+
+  const offPush = stack.on('push', ({ source }) => {
+    if (source !== 'history') write('pushState');
+  });
+  const offPop = stack.on('pop', ({ source, removed }) => {
+    if (source !== 'history') history.go(-removed.length);
+  });
+
+  const onPopState = (ev: PopStateEvent) => {
+    const target = depthOf(ev.state) + 1;
+    if (target === stack.depth) return;
+    if (target < stack.depth) void stack.popTo(target, { animated: animateHistoryPop, source: 'history' });
+    else if (onForward) onForward(target);
+    else history.back();
+  };
+  window.addEventListener('popstate', onPopState);
+
+  return () => {
+    offPush();
+    offPop();
+    window.removeEventListener('popstate', onPopState);
+  };
+}
+
+export function isIOSBrowser(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  return /iP(hone|ad|od)/.test(navigator.platform) || (navigator.platform === 'MacIntel' && navigator.maxTouchPoints > 1);
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+export { NavigationStack } from './navigation-stack.ts';
+export type {
+  StackEntry,
+  Transition,
+  TransitionKind,
+  NavigationSource,
+  MountOptions,
+  NavigationStackOptions,
+  InteractivePopHandle,
+  SettleInput,
+  StackEvents,
+  PushEvent,
+  PopEvent,
+  ReplaceEvent,
+  ResetEvent,
+  TransitionEvent,
+  ProgressEvent,
+} from './navigation-stack.ts';
+export { createIOSTransition, IOS_TRANSITION_CSS_VARS } from './ios-transition.ts';
+export type { IOSTransition, IOSTransitionOptions } from './ios-transition.ts';
+export { cssVars, parseTime, parseNumber, parseRatio, parseEasing } from './css-vars.ts';
+export type { CSSVarReader } from './css-vars.ts';
+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 type { Easing, TweenOptions, CancellableTween } from './animate.ts';
+export {
+  resolveDirection,
+  createDirectionResolver,
+  defaultStrategies,
+  fromHint,
+  fromHistory,
+  fromStack,
+  fromLevel,
+  fromTree,
+  always,
+  segmentsOf,
+} from './direction.ts';
+export type {
+  Direction,
+  DirectionOpinion,
+  DirectionStrategy,
+  DirectionResolver,
+  NavigationContext,
+  NavigationTrigger,
+  RouteRef,
+  LevelOptions,
+  TreeOptions,
+} from './direction.ts';
+export { STACKNAV_CSS, STACKNAV_STYLE_ID, injectStyles } from './styles.ts';
+
+import { NavigationStack } from './navigation-stack.ts';
+import { createIOSTransition, type IOSTransition, type IOSTransitionOptions } from './ios-transition.ts';
+import { createEdgePanGesture, type EdgePanGesture, type EdgePanGestureOptions } from './edge-pan-gesture.ts';
+
+export interface IOSStackOptions {
+  container: HTMLElement;
+  transition?: Partial<IOSTransitionOptions>;
+  gesture?: Partial<EdgePanGestureOptions>;
+}
+
+export interface IOSStack extends NavigationStack {
+  transition: IOSTransition;
+  gesture: EdgePanGesture;
+}
+
+/**
+ * Wires the three pieces together in one call: a stack in `container`, the iOS
+ * transition, and the edge-pan gesture. The gesture is exposed as
+ * `stack.gesture`, and destroying the stack detaches it.
+ */
+export function createIOSStack({ container, transition = {}, gesture = {} }: IOSStackOptions): IOSStack {
+  const t = createIOSTransition(transition);
+  const g = createEdgePanGesture(gesture);
+  const stack = new NavigationStack({ container, transition: t }) as IOSStack;
+  g.attach(stack);
+  stack.gesture = g;
+  const destroy = stack.destroy.bind(stack);
+  stack.destroy = () => {
+    g.detach();
+    destroy();
+  };
+  return stack;
+}