@flemo/core 1.30.0 → 2.1.0

package/dist/transition/compileTransitionStyles.d.ts

@@ -7,9 +7,10 @@ export type CssDecl = {
     value: string;
 };
 export declare const collectAnimatedProperties: (transition: Pick<Transition, "initial" | "variants">) => string[];
-export declare const targetToDecls: (target: TransitionVariantValue["value"] | InitialTarget) => CssDecl[];
+export declare const targetToDecls: (target: TransitionVariantValue["value"] | InitialTarget, ride?: boolean) => CssDecl[];
 export declare const easingToCss: (ease: AnimationOptions["ease"] | undefined) => string;
 export declare const animationName: (scope: "screen" | "decorator" | "part", name: string, variant: TransitionVariant) => string;
+export declare const decoratorAnimationName: (transitionName: string, decoratorName: string, variant: TransitionVariant) => string;
 export declare const HEAD_ANIMATION_SUFFIXES: readonly ["-gov", "-deskhead", "-govcreep"];
 export declare const matchesFlightAnimationName: (eventName: string, expectedName: string) => boolean;
 export declare const compileTransitionStyles: (transitions: Iterable<Transition>, decorators: Iterable<Decorator>, partTransitions?: Iterable<PartTransition>) => string;

package/dist/transition/cubicBezier.d.ts

@@ -1,6 +1,23 @@
 import { AnimationOptions } from './cssTypes';
 export type EasingFunction = (progress: number) => number;
 export declare const cubicBezier: (x1: number, y1: number, x2: number, y2: number) => EasingFunction;
+/**
+ * The INVERSE of a CSS timing function: given the value progress you want to
+ * see, the time progress that produces it.
+ *
+ * A scrubbed animation needs this. Setting an animation's clock to the drag's
+ * fraction moves the CLOCK linearly, and what the eye follows is the curve's
+ * output — with an ease that opens slowly, a finger a tenth of the way across
+ * moves the element a fiftieth, and everything it did not do is left for the
+ * release to rush through. Inverting the curve makes the element track the
+ * finger and leaves the release only what is really left.
+ *
+ * Binary search on y, the same shape as `cubicBezier`'s search on x. An
+ * overshooting curve (`backOut`, `anticipate`) is not monotonic in y, so the
+ * search returns the first crossing — which is the one before the overshoot,
+ * and the only one a drag can mean.
+ */
+export declare const invertEasing: (ease: AnimationOptions["ease"] | undefined) => EasingFunction;
 /**
  * The control points behind an authored ease, named or spelled out — `null`
  * for `linear`, which has no handles to work with.

package/dist/transition/decorator/__tests__/resolveDecoratorClock.test.d.ts

@@ -0,0 +1,14 @@
+declare module '../../typing' {
+    interface RegisterTransition {
+        "clock-long": "clock-long";
+        "clock-short": "clock-short";
+        "clock-directional": "clock-directional";
+    }
+}
+declare module '../typing' {
+    interface RegisterDecorator {
+        "clock-dim": "clock-dim";
+        "clock-fixed": "clock-fixed";
+    }
+}
+export {};

package/dist/transition/decorator/createDecorator.d.ts

@@ -1,12 +1,11 @@
 import { InitialTarget } from '../cssTypes';
-import { TransitionVariantValue } from '../typing';
-import { DecoratorName, Decorator, DecoratorOptions } from './typing';
+import { DecoratorName, Decorator, DecoratorOptions, DecoratorVariantValue } from './typing';
 interface CreateDecoratorProps {
     name: DecoratorName;
     initial: InitialTarget;
-    idle: TransitionVariantValue;
-    enter: TransitionVariantValue;
-    exit: TransitionVariantValue;
+    idle: DecoratorVariantValue;
+    enter: DecoratorVariantValue;
+    exit: DecoratorVariantValue;
     options?: DecoratorOptions;
 }
 export default function createDecorator({ name, initial, idle, enter, exit, options }: CreateDecoratorProps): Decorator;

package/dist/transition/decorator/createRawDecorator.d.ts

@@ -1,18 +1,17 @@
 import { InitialTarget } from '../cssTypes';
-import { TransitionVariantValue } from '../typing';
-import { DecoratorName, Decorator, DecoratorOptions } from './typing';
+import { DecoratorName, Decorator, DecoratorOptions, DecoratorVariantValue } from './typing';
 interface CreateRawDecoratorProps {
     name: DecoratorName;
     initial: InitialTarget;
-    idle: TransitionVariantValue;
-    pushOnEnter: TransitionVariantValue;
-    pushOnExit: TransitionVariantValue;
-    replaceOnEnter: TransitionVariantValue;
-    replaceOnExit: TransitionVariantValue;
-    popOnEnter: TransitionVariantValue;
-    popOnExit: TransitionVariantValue;
-    completedOnEnter: TransitionVariantValue;
-    completedOnExit: TransitionVariantValue;
+    idle: DecoratorVariantValue;
+    pushOnEnter: DecoratorVariantValue;
+    pushOnExit: DecoratorVariantValue;
+    replaceOnEnter: DecoratorVariantValue;
+    replaceOnExit: DecoratorVariantValue;
+    popOnEnter: DecoratorVariantValue;
+    popOnExit: DecoratorVariantValue;
+    completedOnEnter: DecoratorVariantValue;
+    completedOnExit: DecoratorVariantValue;
     options?: DecoratorOptions;
 }
 export default function createRawDecorator({ name, initial, idle, pushOnEnter, pushOnExit, replaceOnEnter, replaceOnExit, popOnEnter, popOnExit, completedOnEnter, completedOnExit, options }: CreateRawDecoratorProps): Decorator;

package/dist/transition/decorator/resolveDecoratorClock.d.ts

@@ -0,0 +1,36 @@
+import { BaseTransition, Transition } from '../typing';
+import { Decorator } from './typing';
+/**
+ * A decorator's variant table with its clock filled in from the screen
+ * transition that names it.
+ *
+ * A decorator is only ever reached through `transition.decoratorName`, so the
+ * flight it dresses already decides how long it has. Authoring the length a
+ * second time is how the two drift apart, and this repository worked around
+ * that three times before removing the duplication:
+ *
+ *   - `overlay` and `cupertino` each restated 0.7s, with a comment on the
+ *     decorator saying the number came from the transition.
+ *   - the playground's `drift` and `recess` share a constants file for no
+ *     other reason than to keep two hand-written clocks equal.
+ *   - `layout` dropped its dim ALTOGETHER rather than inherit `overlay`'s
+ *     0.7s over a 0.4s flight: measured on a pop, the dismissing screen was
+ *     fully gone at 335ms while the screen underneath still carried a 10%
+ *     black wash, which reads as a grey cast appearing from nowhere and then
+ *     lifting for no reason.
+ *
+ * The rule is the SAME VARIANT KEY, which is exactly the mapping those
+ * workarounds were doing by hand: a decorator's `enter` sits at PUSHING-false
+ * with the screen's `exit`, its `exit` at POPPING-false with the screen's
+ * `exitBack`. It therefore also carries direction for free — a preset whose
+ * push and pop differ (material runs 0.35s and 0.25s) gives its dim the same
+ * asymmetry without the author restating it.
+ *
+ * Resolution is COMPILE TIME and produces a literal. It must never become a
+ * `var()` in `animation-duration`: timing that depended on custom properties
+ * lost WebKit's accelerated playback and collapsed to a 2-frame snap under
+ * main-thread starvation (device-bisected 2026-08-13, see
+ * compileTransitionStyles.ts).
+ */
+export declare const resolveDecoratorClock: (transition: Pick<Transition, "variants">, decorator: Pick<Decorator, "initial" | "variants">) => Pick<BaseTransition, "initial" | "variants">;
+export default resolveDecoratorClock;

package/dist/transition/decorator/typing.d.ts

@@ -1,4 +1,5 @@
-import { BaseTransition, SwipeAnimate } from '../typing';
+import { AnimationOptions, TransitionTarget } from '../cssTypes';
+import { BaseTransition, SwipeAnimate, TransitionVariant } from '../typing';
 export interface RegisterDecorator {
 }
 export type DecoratorName = RegisterDecorator[keyof RegisterDecorator] | "overlay";
@@ -19,6 +20,11 @@ export type DecoratorOptions = {
         prevDecorator: HTMLDivElement;
     }) => void;
 };
-export interface Decorator extends Omit<BaseTransition, "name">, DecoratorOptions {
+export type DecoratorVariantValue = {
+    value: TransitionTarget;
+    options?: AnimationOptions;
+};
+export interface Decorator extends Omit<BaseTransition, "name" | "variants">, DecoratorOptions {
     name: DecoratorName;
+    variants: Record<TransitionVariant, DecoratorVariantValue>;
 }

package/dist/transition/morphTransition/__tests__/createMorphTransition.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/transition/morphTransition/createMorphTransition.d.ts

@@ -0,0 +1,13 @@
+import { InitialTarget } from '../cssTypes';
+import { TransitionVariantValue } from '../typing';
+import { MorphTransition, MorphTransitionName, MorphTransitionOptions } from './typing';
+interface CreateMorphProps {
+    name: MorphTransitionName;
+    initial: InitialTarget;
+    idle: TransitionVariantValue;
+    enter: TransitionVariantValue;
+    exit: TransitionVariantValue;
+    options?: MorphTransitionOptions;
+}
+export default function createMorphTransition({ name, initial, idle, enter, exit, options }: CreateMorphProps): MorphTransition;
+export {};

package/dist/transition/morphTransition/createRawMorphTransition.d.ts

@@ -0,0 +1,17 @@
+import { InitialTarget } from '../cssTypes';
+import { TransitionVariantValue } from '../typing';
+import { MorphTransition, MorphTransitionName, MorphTransitionOptions } from './typing';
+interface CreateRawMorphProps {
+    name: MorphTransitionName;
+    initial: InitialTarget;
+    idle: TransitionVariantValue;
+    pushOnEnter: TransitionVariantValue;
+    pushOnExit: TransitionVariantValue;
+    replaceOnEnter: TransitionVariantValue;
+    replaceOnExit: TransitionVariantValue;
+    popOnEnter: TransitionVariantValue;
+    popOnExit: TransitionVariantValue;
+    options?: MorphTransitionOptions;
+}
+export default function createRawMorphTransition({ name, initial, idle, pushOnEnter, pushOnExit, replaceOnEnter, replaceOnExit, popOnEnter, popOnExit, options }: CreateRawMorphProps): MorphTransition;
+export {};

package/dist/transition/morphTransition/morphTransition.d.ts

@@ -0,0 +1,2 @@
+import { MorphTransition, MorphTransitionName } from './typing';
+export declare const morphTransitionMap: Map<MorphTransitionName, MorphTransition>;

package/dist/transition/morphTransition/shared.d.ts

@@ -0,0 +1,2 @@
+declare const shared: import('./typing').MorphTransition;
+export default shared;

package/dist/transition/morphTransition/text.d.ts

@@ -0,0 +1,2 @@
+declare const text: import('./typing').MorphTransition;
+export default text;

package/dist/transition/morphTransition/typing.d.ts

@@ -0,0 +1,72 @@
+import { BaseTransition, TransitionVariant } from '../typing';
+export interface RegisterMorphTransition {
+}
+export type MorphTransitionName = RegisterMorphTransition[keyof RegisterMorphTransition] | "shared" | "text" | "zoom" | (string & {});
+/** The preset every morph falls back to when no name is given. */
+export declare const DEFAULT_MORPH_TRANSITION_NAME = "shared";
+export type MorphTransitionOptions = {
+    /**
+     * The share of the flight over which the GHOST dissolves — the copy of the
+     * element being replaced that the runtime carries inside the flight (0–1,
+     * default 0.55).
+     *
+     * It is what makes a travel show the right thing at both ends: the flight
+     * begins as an exact copy of what was on glass and dissolves into the real
+     * arriving element while the box moves. Set it to 0 to carry no copy, which
+     * cuts straight to the arrival's content on the first frame.
+     *
+     * The arriving element stays opaque underneath throughout. Fading both would
+     * bleed the background through the pair by a(1 - a) — a luminance dip
+     * peaking at 25% in the middle of the hand-over.
+     *
+     * THE WINDOW IS WHAT THE DEPARTURE'S OWN CONTENT LEAVES OVER. This used to be
+     * 0.22 — three frames of a short flight — on the reasoning that holding the
+     * copy longer let the two layouts drift apart underneath it and print as
+     * doubled text. That reasoning was written when the copy painted everything,
+     * including the paired elements. It does not now: a paired descendant is
+     * already invisible in the copy (the real one is morphing underneath it), so
+     * all the copy is holding is content with NO counterpart — a caption, a body
+     * paragraph, a button that exists on one side only. Three frames is not that
+     * content leaving; it is that content being cut, which is exactly what a pop
+     * looked like next to the arrival it was supposed to reverse.
+     */
+    crossFade?: number;
+    /**
+     * Interpolate `border-radius` across the flight (default true). Nothing is
+     * scaled, so the two ends' own values are the whole story.
+     *
+     * It rides the CONTENT animation, never the geometry one: a keyframe that
+     * lists a property the compositor cannot animate drops that whole animation
+     * to the main thread, and the geometry keyframe is the one that must never
+     * leave the compositor.
+     */
+    radius?: boolean;
+    /**
+     * Move the whole screen with the element, not just the element (default off).
+     *
+     * A plain morph flies ALONE: the element crosses while the screens do
+     * whatever their own transition says, which is right when the element is one
+     * thing among many. It is wrong when the element IS the navigation — a grid
+     * cell opening into a full-screen view. There the eye reads the tap as
+     * "the camera moved to this card", and a grid that stays put underneath
+     * reads as the card escaping from it.
+     *
+     * `"screen"` gives the flight a camera: the screen the element is SMALL on
+     * (the grid — the departing screen on a push, the arriving one on a pop) is
+     * scaled and translated by exactly the zoom that takes the element from one
+     * end to the other, so every other card moves as though the viewport had
+     * pushed in on the tapped one. Material calls the pattern a container
+     * transform; iOS 18 calls its version a zoom transition.
+     *
+     * It SUPERSEDES that screen's own transform for the length of the flight —
+     * the camera IS the screen's motion here, and two authors of one transform
+     * is not a thing CSS can compose. Pair it with a transition that does not
+     * move the screen itself (`none`, or an opacity-only one); a slide would be
+     * replaced rather than combined.
+     */
+    carry?: "screen";
+};
+export interface MorphTransition extends Omit<BaseTransition, "name">, MorphTransitionOptions {
+    name: MorphTransitionName;
+}
+export declare const MORPH_FROM_VARIANT: Record<TransitionVariant, "initial" | "IDLE-true" | "self">;

package/dist/transition/morphTransition/zoom.d.ts

@@ -0,0 +1,2 @@
+declare const zoom: import('./typing').MorphTransition;
+export default zoom;

package/dist/transition/registerTransitionDefinitions.d.ts

@@ -1,4 +1,5 @@
 import { Transition } from './typing';
 import { Decorator } from './decorator/typing';
+import { MorphTransition } from './morphTransition/typing';
 import { PartTransition } from './partTransition/typing';
-export default function registerTransitionDefinitions(transitions: Transition[], decorators: Decorator[], partTransitions?: PartTransition[]): () => void;
+export default function registerTransitionDefinitions(transitions: Transition[], decorators: Decorator[], partTransitions?: PartTransition[], morphTransitions?: MorphTransition[]): () => void;

package/dist/transition/rideOffset.d.ts

@@ -0,0 +1,5 @@
+import { TransitionTarget } from './cssTypes';
+export declare const RIDE_HEIGHT_VAR = "--flemo-ride-y";
+export declare const percentRatio: (value: unknown) => number | null;
+export declare const rideLength: (ratio: number) => string;
+export declare const resolveRideTarget: <T extends TransitionTarget>(target: T, screenHeight: number) => T;

package/dist/transition/swipeSettle.d.ts

@@ -29,8 +29,12 @@ export interface SwipeSettleInput {
      * time that curve itself spends on the stretch that is left; without them it
      * falls back to reading the motion as linear, which is what this used to do
      * for every transition.
+     *
+     * `null` is accepted as well as omission, because the callers that build
+     * this read their curve from `easeControlPoints`, which reports "no curve"
+     * as null. Converting at every call site bought nothing but a branch.
      */
-    authoredEase?: readonly [number, number, number, number];
+    authoredEase?: readonly [number, number, number, number] | null;
     minSeconds?: number;
 }
 /**

package/dist/transition/typing.d.ts

@@ -42,7 +42,18 @@ export type TransitionOptions = {
         animate: SwipeAnimate;
         currentScreen: HTMLDivElement;
         prevScreen: HTMLDivElement;
-        onProgress?: (triggered: boolean, progress: number) => void;
+        /**
+         * Report the gesture's VERDICT so the decorator and the parts can
+         * follow it. The controller supplies their progress itself, against
+         * the box the screen is actually dragged over, so a second argument
+         * is accepted for source compatibility and is not read.
+         *
+         * It used to be. A transition's own progress is in the transition's
+         * own unit — material's is a pull in pixels, layout's is a constant
+         * — so what reached a decorator depended on which preset it was
+         * paired with, and could not honour the 0-100 those hooks document.
+         */
+        onProgress?: (triggered: boolean, progress?: number) => void;
     }) => number;
     onSwipeEnd: (event: PointerEvent, info: SwipeInfo, options: {
         animate: SwipeAnimate;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flemo/core",
-  "version": "1.30.0",
+  "version": "2.1.0",
   "description": "Framework-agnostic primitives for flemo: history, navigation, transitions, task manager.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -33,20 +33,20 @@
   "license": "MIT",
   "dependencies": {
     "path-to-regexp": "^8.4.2",
-    "zustand": "^5.0.14"
+    "zustand": "^5.0.15"
   },
   "devDependencies": {
+    "@flemo/eslint-config": "0.0.0",
+    "@flemo/tsconfig": "0.0.0",
     "@types/node": "^24.13.1",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.11",
     "csstype": "^3.2.3",
     "eslint": "^9.39.5",
     "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
-    "vite": "^8.2.1",
+    "vite": "^8.2.2",
     "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10",
-    "@flemo/eslint-config": "0.0.0",
-    "@flemo/tsconfig": "0.0.0"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"