@stacknav/core 0.2.0

package/README.md

@@ -0,0 +1,235 @@
+# @stacknav/core
+
+An iOS push/pop navigation transition for any web app. Pages, headers and
+styling stay the app's own; the engine only moves them.
+
+- **Push / pop** with the UIKit curve, parallax and dim on the page beneath, and
+  a shadow on the leading edge of the incoming page.
+- **Interactive pop**: drag from the leading edge (or from anywhere, if
+  configured) and the page follows the pointer. Release past half the width or
+  with a flick to complete; a flick back cancels.
+- **Scroll and state are preserved.** Pages beneath the top stay mounted and
+  hidden. Only `transform` is written, so scroll offsets, form state and focus
+  survive.
+- **Direction resolution** for router-driven apps: composable strategies decide
+  push / pop / replace.
+- **Browser back** for apps without a router, through an optional history
+  adapter. On iOS browsers the pop is instant, because Safari has already
+  animated its own snapshot.
+- **Tunable from CSS.** Duration, curve, parallax, dim and shadow are custom
+  properties on the container, so a media query or theme class can retune the
+  animation without touching the app's JS.
+- **Custom chrome.** Subscribe to `progress` events and drive a fixed header or
+  tab bar from the same `p`.
+- No dependencies. Plain ES modules with type declarations.
+
+## Use
+
+```html
+<div id="app"></div>
+<script type="module">
+  import { createIOSStack, attachBrowserHistory, injectStyles } from '@stacknav/core';
+
+  injectStyles(); // or <link rel="stylesheet" href="@stacknav/core/stacknav.css">
+  const nav = createIOSStack({ container: document.getElementById('app') });
+  await nav.push(homePage(), { animated: false });
+  attachBrowserHistory(nav);
+
+  nav.push(detailPage(item));   // resolves when the animation ends
+  nav.pop();
+  nav.popTo(1);                 // back to the root
+</script>
+```
+
+The container needs a height; it becomes `position: relative; overflow: hidden`.
+Each page is an element you create. The stack gives it
+`position: absolute; inset: 0; overflow-y: auto` and manages its visibility.
+
+## API
+
+### `createIOSStack({ container, transition?, gesture? })`
+
+Builds a `NavigationStack` with the iOS transition and the edge-pan gesture
+attached. `transition` and `gesture` are option objects for the two factories
+below. The gesture is exposed as `stack.gesture`; `stack.destroy()` detaches it.
+
+### `NavigationStack`
+
+| Member | Description |
+| --- | --- |
+| `push(el \| () => el, { animated, data, key, source })` | Mounts and slides in a page. Resolves with the entry `{ el, index, key, data }`. An element already lower in the stack is moved to the top. |
+| `pop({ animated })` | Slides the top page out. Resolves with the removed entry, or `null` at the root. |
+| `popTo(depth, { animated })` | Pops until `depth` pages remain. Intermediate pages are removed without animation. |
+| `popWith(el, opts)` | Pops the top page, revealing `el`. If `el` is mounted beneath, everything above it is removed; if not, it is placed beneath the top first. Used by routers to pop to a page that no longer exists. |
+| `replace(el, opts)` | Swaps the top page for `el`, no animation. |
+| `present(el, direction, opts)` | `push`, `pop` (via `popWith`) or `replace`, for callers that already resolved the direction. |
+| `remove(el)` | Drops a page wherever it sits, no animation. |
+| `reset(elements)` | Replaces the whole stack, no animation. |
+| `beginInteractivePop()` | Returns `{ update(p), finish({ complete, velocity }) }` or `null`. Used by the gesture, and usable by a custom recognizer. |
+| `depth`, `top`, `entries`, `busy`, `canPop()`, `entryOf(el \| key)` | State. |
+| `on(event, fn)` | Events: `push`, `pop`, `replace`, `reset`, `transitionstart`, `progress`, `transitionend`. Returns an unsubscribe function. |
+| `destroy()` | Unmounts everything. |
+
+Operations are serialized: a `push` called during a transition waits its turn.
+
+The `pop` event carries `{ entry, removed, entries, source }`, where `source` is
+`"api"`, `"gesture"`, `"history"` or whatever a caller passed. Removed elements
+are detached, not destroyed.
+
+### Direction resolution
+
+```ts
+import { createDirectionResolver, fromHint, fromHistory, fromStack, fromLevel, fromTree, always } from '@stacknav/core';
+
+const resolve = createDirectionResolver([fromHint(), fromHistory(), fromStack(), fromLevel(), fromTree()], 'push');
+
+resolve({
+  from: { key: '/items', segments: ['items'] },
+  to: { key: '/items/42', segments: ['items', '42'], level: 2 },
+  trigger: 'imperative',      // or 'history'
+  historyDelta: undefined,    // negative = back, positive = forward, when known
+  hint: undefined,            // an explicit 'push' | 'pop' | 'replace'
+  stack: ['/', '/items'],     // keys of the kept pages, bottom to top
+}); // → 'push'
+```
+
+A strategy is
+`(ctx: NavigationContext) => 'push' | 'pop' | 'replace' | 'auto' | undefined`.
+`fromLevel({ sameLevel })` and `fromTree({ sameDepth })` configure what equal
+numbers or unrelated siblings mean (default `replace`). `segmentsOf(url)` splits
+a path into `segments`.
+
+### `createIOSTransition(options)`
+
+| Option | CSS variable | Default | Description |
+| --- | --- | --- | --- |
+| `duration` | `--sn-duration` | `500` | ms for a programmatic push/pop |
+| `ease` | `--sn-easing` | `cubic-bezier(0.32, 0.72, 0, 1)` | the curve push/pop runs on |
+| `parallax` | `--sn-parallax` | `0.3` | fraction of the width the lower page travels |
+| `dimColor`, `dimMax` | `--sn-dim-color`, `--sn-dim-max` | `"#000"`, `0.1` | overlay on the lower page at full open (`0.35` suits dark UIs) |
+| `shadow` | `--sn-shadow` | `-3px 0 14px rgba(0,0,0,0.16)` | box-shadow on the incoming page |
+| `settleMin`, `settleMax` | `--sn-settle-min`, `--sn-settle-max` | `120`, `400` | ms bounds when finishing an interactive pop |
+| `settleEase` | `--sn-settle-easing` | `cubic-bezier(0.2, 0.8, 0.2, 1)` | the curve a released swipe finishes on |
+| `settleVelocityFloor` | `--sn-settle-velocity-floor` | `900` | px/s assumed when the pointer was slower |
+| `timeScale` | `--sn-time-scale` | `1` | multiplies every duration (slow motion, tests) |
+
+`prefers-reduced-motion` sets every duration to 0.
+
+#### Tuning from CSS
+
+Every option is also a custom property, read off the container when a transition
+starts. Custom properties inherit, so set them wherever you like: on `:root`, on
+the container, under a theme class, or inside a media query.
+
+```css
+:root {
+  --sn-duration: 340ms;              /* snappier than iOS */
+  --sn-easing: cubic-bezier(0.4, 0, 0.2, 1);
+}
+.theme-flat {
+  --sn-parallax: 0;                  /* no parallax on the page beneath */
+  --sn-dim-max: 0;
+  --sn-shadow: none;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --sn-dim-max: 35%; }       /* stronger dimming on dark UIs */
+}
+```
+
+Durations accept `ms`, `s` or a bare number of milliseconds. Fractions accept
+`0.3` or `30%`. Easings accept `linear`, `ease`, `ease-in`, `ease-out`,
+`ease-in-out`, `cubic-bezier(…)` with x coordinates within `[0, 1]` as CSS
+requires, or `ios` / `ios-settle` for the two defaults. The `step` and `linear()`
+timing functions are not supported.
+
+Precedence:
+
+1. A variable that is set wins over the JS option, so a stylesheet can retune a
+   transition the app configured in code.
+2. A variable that is unset falls through to the JS option, so nothing needs to
+   be declared to get the defaults.
+3. A variable the engine cannot parse also falls through to the JS option. A bad
+   value degrades to the default rather than breaking the animation, and never
+   reaches the tween. This includes `calc()` and other math: custom properties
+   reach `getComputedStyle` unevaluated, so `--sn-duration: calc(var(--speed) *
+   2)` cannot be read and falls back. Do the arithmetic where you define the
+   variable.
+
+Values are re-read at the start of every transition, which covers media queries
+and class changes. `transition.refresh()` re-reads them on demand, for example
+after changing `transition.options` mid-animation. `transition.resolved` is what
+is currently in force, and `IOS_TRANSITION_CSS_VARS` maps each option to its
+variable name.
+
+A transition is just
+`{ duration, ease, settle(), begin?(), apply(lower, upper, p), end?() }`, so you
+can write a different one (a fade, a vertical sheet) and pass it to
+`new NavigationStack({ container, transition })`. `cssVars()` and the
+`parseTime` / `parseNumber` / `parseRatio` / `parseEasing` helpers are exported
+so a custom transition can read variables the same way. Each returns `undefined`
+rather than `NaN` for anything it cannot parse, so `?? yourDefault` is all the
+handling a value needs.
+
+### `createEdgePanGesture(options)`
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `edgeWidth` | `28` | px strip on the leading edge that starts the gesture |
+| `anywhere` | `false` | recognize the drag from anywhere on the page |
+| `startSlop` | `6` | px of horizontal travel before the drag begins |
+| `verticalCancelSlop` | `10` | px of vertical travel that hands the touch to scrolling |
+| `completeThreshold` | `0.5` | fraction of the width that completes on a slow release |
+| `completeVelocity` | `500` | px/s toward the trailing edge that completes regardless |
+| `cancelVelocity` | `-500` | px/s back toward the leading edge that cancels regardless |
+
+Call `gesture.refresh()` after changing options at runtime.
+
+### `attachBrowserHistory(stack, { key = "snDepth", animateHistoryPop, onForward })`
+
+For apps without a router. Mirrors stack depth into `history.state`. Returns a
+detach function. `animateHistoryPop` defaults to `false` on iOS browsers and
+`true` elsewhere. Forward navigation has no page to show, so by default it
+bounces back; pass `onForward(targetDepth)` to re-push something instead.
+
+### Styles
+
+`injectStyles()` inserts the engine's four rules once. `STACKNAV_CSS` is the same
+CSS as a string, minified because it rides along in your JS bundle, and
+`@stacknav/core/stacknav.css` is the same CSS as a readable file. It covers
+layout only and declares no custom properties: the tuning variables above are
+listed in a comment in the file rather than set, so that leaving one out means
+"use the default".
+
+## Footprint
+
+Plain ES modules, no dependencies, no work at module load: a bundler keeps only what you import, whether or not it honours the package's `sideEffects` flag (the tests bundle each entry point with that flag switched off and check what survives). Minified and gzipped, as measured by `pnpm size`:
+
+| You import | Costs |
+| --- | --- |
+| `createIOSStack` (stack, iOS look, swipe back) | ~4.1 kB |
+| `NavigationStack` with your own transition | ~2.0 kB |
+| the direction strategies | ~0.6 kB |
+| `attachBrowserHistory` | ~0.4 kB |
+| `injectStyles` | ~0.3 kB |
+| everything | ~5.4 kB |
+
+## Develop
+
+```sh
+pnpm test         # node:test with a 68-line DOM stub, no browser; includes the tree-shaking checks
+pnpm build        # tsc → dist/, plus dist/stacknav.css
+pnpm size         # what each entry point costs, minified + gzipped (after a build)
+```
+
+```
+src/
+  animate.ts            cubic-bezier solver, cancellable tween, easings
+  css-vars.ts           reading and parsing the engine's custom properties
+  navigation-stack.ts   the stack: mounting, ordering, transition lifecycle, queueing
+  ios-transition.ts     the look: slide, parallax, dim, shadow, settle timing
+  edge-pan-gesture.ts   pointer-event recognizer that drives the interactive pop
+  direction.ts          push / pop / replace strategies and the resolver
+  history-adapter.ts    history.state mirroring for apps without a router
+  styles.ts             the CSS the engine needs, and injectStyles()
+  index.ts              exports + createIOSStack()
+```

package/dist/animate.d.ts

@@ -0,0 +1,26 @@
+export type Easing = (t: number) => number;
+export declare function cubicBezier(x1: number, y1: number, x2: number, y2: number): Easing;
+export declare const easings: {
+    linear: Easing;
+    ios: Easing;
+    easeOut: Easing;
+};
+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 declare function tween({ from, to, duration, ease, onUpdate }: TweenOptions): CancellableTween;
+export declare const prefersReducedMotion: () => boolean;
+//# sourceMappingURL=animate.d.ts.map

package/dist/animate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animate.d.ts","sourceRoot":"","sources":["../src/animate.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;AAE3C,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAiBlF;AAKD,eAAO,MAAM,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAInE,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG;IAAE,MAAM,IAAI,IAAI,CAAA;CAAE,CAAC;AAElE;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAqB,EAAE,QAAQ,EAAE,EAAE,YAAY,GAAG,gBAAgB,CA2B7G;AAED,eAAO,MAAM,oBAAoB,QAAO,OACoD,CAAC"}

package/dist/animate.js

@@ -0,0 +1,69 @@
+// A small animation toolkit: a cubic-bezier solver, a cancellable tween, and
+// the easing curves the iOS transition uses.
+export function cubicBezier(x1, y1, x2, y2) {
+    const A = (a, b) => 1 - 3 * b + 3 * a;
+    const B = (a, b) => 3 * b - 6 * a;
+    const C = (a) => 3 * a;
+    const calc = (t, a, b) => ((A(a, b) * t + B(a, b)) * t + C(a)) * t;
+    const slope = (t, a, b) => 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: (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),
+};
+/**
+ * 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 }) {
+    let raf = 0;
+    let done = false;
+    const promise = new Promise((resolve) => {
+        if (duration <= 0) {
+            onUpdate(to);
+            done = true;
+            return resolve();
+        }
+        const t0 = performance.now();
+        const step = (now) => {
+            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);
+    });
+    promise.cancel = () => {
+        done = true;
+        cancelAnimationFrame(raf);
+    };
+    return promise;
+}
+export const prefersReducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+//# sourceMappingURL=animate.js.map

package/dist/animate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"animate.js","sourceRoot":"","sources":["../src/animate.ts"],"names":[],"mappings":"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"}

package/dist/css-vars.d.ts

@@ -0,0 +1,22 @@
+import { 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 declare function cssVars(el: Element | null | undefined): CSSVarReader;
+/** `500ms`, `0.4s`, or a bare number of milliseconds. */
+export declare function parseTime(v: string | undefined): number | undefined;
+export declare function parseNumber(v: string | undefined): number | undefined;
+/** A fraction. `0.3` and `30%` are equivalent. */
+export declare function parseRatio(v: string | undefined): number | undefined;
+/**
+ * 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 declare function parseEasing(v: string | undefined): Easing | undefined;
+//# sourceMappingURL=css-vars.d.ts.map

package/dist/css-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-vars.d.ts","sourceRoot":"","sources":["../src/css-vars.ts"],"names":[],"mappings":"AASA,OAAO,EAAwB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEjE,gFAAgF;AAChF,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAOpE;AAID,yDAAyD;AACzD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAInE;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGrE;AAED,kDAAkD;AAClD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAMpE;AAuBD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYrE"}

package/dist/css-vars.js

@@ -0,0 +1,89 @@
+// 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 } from "./animate.js";
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    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;
+const easingKeywordsOf = () => (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) {
+    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;
+    if (x1 < 0 || x1 > 1 || x2 < 0 || x2 > 1)
+        return undefined;
+    return cubicBezier(x1, y1, x2, y2);
+}
+//# sourceMappingURL=css-vars.js.map

package/dist/css-vars.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css-vars.js","sourceRoot":"","sources":["../src/css-vars.ts"],"names":[],"mappings":"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"}

package/dist/direction.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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;
+}
+/** Calls each strategy in turn. The first direction returned wins, else `fallback`. */
+export declare function resolveDirection(strategies: readonly DirectionStrategy[], ctx: NavigationContext, fallback?: Direction): Direction;
+/** Bundles strategies and a fallback into a single resolver function. */
+export declare function createDirectionResolver(strategies?: readonly DirectionStrategy[], fallback?: Direction): DirectionResolver;
+/** Honors an explicit per-navigation hint, e.g. `{ info: { stacknav: 'pop' } }` in Angular's router. */
+export declare const fromHint: () => DirectionStrategy;
+/** Browser back is a pop, browser forward is a push. No answer for imperative navigations. */
+export declare const fromHistory: () => DirectionStrategy;
+/** Navigating to a page still kept beneath the current one is a pop back to it. */
+export declare const fromStack: () => DirectionStrategy;
+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 declare const fromLevel: ({ sameLevel }?: LevelOptions) => DirectionStrategy;
+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 declare const fromTree: ({ sameDepth }?: TreeOptions) => DirectionStrategy;
+/** Always returns the same direction. Useful as the last entry in a list. */
+export declare const always: (direction: Direction) => DirectionStrategy;
+/** The default order: an explicit hint, then browser history, then the kept stack, then numbering, then the tree. */
+export declare const defaultStrategies: () => DirectionStrategy[];
+/** Split a URL path into segments, ignoring the query, fragment and empty parts. */
+export declare function segmentsOf(url: string): string[];
+//# sourceMappingURL=direction.d.ts.map

package/dist/direction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direction.d.ts","sourceRoot":"","sources":["../src/direction.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAEnD,6FAA6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5E,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,mFAAmF;IACnF,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,SAAS,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;IACtB,EAAE,EAAE,QAAQ,CAAC;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,4DAA4D;IAC5D,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,gBAAgB,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAID,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,EAAE,GAAG,EAAE,iBAAiB,EAAE,QAAQ,GAAE,SAAkB,GAAG,SAAS,CAM1I;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,UAAU,GAAE,SAAS,iBAAiB,EAAwB,EAAE,QAAQ,GAAE,SAAkB,GAAG,iBAAiB,CAKvJ;AAID,wGAAwG;AACxG,eAAO,MAAM,QAAQ,QAAO,iBAAsC,CAAC;AAEnE,8FAA8F;AAC9F,eAAO,MAAM,WAAW,QAAO,iBAG9B,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,SAAS,QAAO,iBAM5B,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,gBAA2B,YAAiB,KAAG,iBAOxE,CAAC;AAEF,MAAM,WAAW,WAAW;IAC1B,iGAAiG;IACjG,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,gBAA2B,WAAgB,KAAG,iBAStE,CAAC;AAEF,6EAA6E;AAC7E,eAAO,MAAM,MAAM,GAAI,WAAW,SAAS,KAAG,iBAAoC,CAAC;AAEnF,qHAAqH;AACrH,eAAO,MAAM,iBAAiB,QAAO,iBAAiB,EAAuE,CAAC;AAQ9H,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAGhD"}

package/dist/direction.js

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+const isDirection = (v) => v === 'push' || v === 'pop' || v === 'replace';
+/** Calls each strategy in turn. The first direction returned wins, else `fallback`. */
+export function resolveDirection(strategies, ctx, fallback = 'push') {
+    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 = defaultStrategies(), fallback = 'push') {
+    const resolver = ((ctx) => resolveDirection(strategies, ctx, fallback));
+    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 = () => (ctx) => ctx.hint;
+/** Browser back is a pop, browser forward is a push. No answer for imperative navigations. */
+export const fromHistory = () => (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 = () => (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';
+};
+/**
+ * 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' } = {}) => (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;
+};
+/**
+ * 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' } = {}) => (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;
+/** The default order: an explicit hint, then browser history, then the kept stack, then numbering, then the tree. */
+export const defaultStrategies = () => [fromHint(), fromHistory(), fromStack(), fromLevel(), fromTree()];
+function isPrefix(prefix, of) {
+    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) {
+    const path = url.split(/[?#]/, 1)[0];
+    return path.split('/').filter(Boolean);
+}
+//# sourceMappingURL=direction.js.map