@flemo/core 2.3.1 → 2.4.0

package/dist/transition/__tests__/resolveSwipeOptions.test.d.ts

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

package/dist/transition/resolveSwipeOptions.d.ts

@@ -0,0 +1,76 @@
+import { SwipeInfo, SwipeOptions, Transition } from './typing';
+/**
+ * The swipe a transition declares, with its defaults filled in.
+ *
+ * A transition states as little as `{ direction }` and every caller downstream
+ * needs a complete answer: how far to commit, how fast, where the two sides
+ * are. Resolving that at each call site is how the defaults drift, so it
+ * happens once, here, and "a direction is a complete swipe" is a fact about
+ * this function rather than a promise made in a doc comment.
+ */
+export interface ResolvedSwipe {
+    direction: "x" | "y";
+    /** How far the gesture must carry the screen to navigate, in px. */
+    commitDistance: (span: number) => number;
+    /** How fast the finger must still be going to navigate regardless. */
+    commitVelocity: number;
+    /**
+     * Where the drag itself carries each side, when that is not where the pop
+     * does. `undefined` means walk the pop, which is the case for most.
+     */
+    dragTo: {
+        current: SwipeOptions["current"];
+        prev: SwipeOptions["prev"];
+    };
+    /** Where the two sides are along their travel, 0 to 1. */
+    progress: (info: SwipeInfo, span: number, travelled: number) => {
+        current: number;
+        prev: number;
+    };
+    onStart: SwipeOptions["onStart"] | undefined;
+    onMove: SwipeOptions["onMove"] | undefined;
+    onEnd: SwipeOptions["onEnd"] | undefined;
+    /**
+     * Whether flemo drives the screens itself.
+     *
+     * Two drivers on one transform is how a bar drifts from the screen it
+     * rides, so exactly one of the two owns them, and NAMING WHERE THEY GO IS
+     * HOW A TRANSITION CLAIMS THEM. Declaring `current` or `prev` keeps the
+     * screens on the scrub whatever hooks are also written, and the hook's own
+     * writes to them are refused while everything else it animates goes
+     * through.
+     *
+     * That combination is the point rather than a leniency. A gesture that
+     * carries a morphing element about freely needs a hook for the element and
+     * has no reason to give up the screens for it — and the screens are the
+     * expensive half, being two full-screen layers. Writing a hook without
+     * naming a destination still hands them over, which is what a drag that
+     * moves the screens themselves to arbitrary places has to do.
+     *
+     * `onStart` only answers whether the gesture may begin, so it never costs
+     * the screens.
+     */
+    drivesScreens: boolean;
+}
+/**
+ * The distance at which a release navigates, as a fraction of the screen's own
+ * span.
+ *
+ * 50px on the 390px screen it was chosen on — the number cupertino carried
+ * before this was shared — expressed as a fraction so a wider screen asks for
+ * proportionally more rather than the same 50px.
+ */
+export declare const DEFAULT_COMMIT_FRACTION: number;
+/**
+ * The speed at which a release navigates however little it travelled, unless
+ * the transition names its own.
+ *
+ * 20 is what all three presets had written for themselves, and it is their
+ * taste rather than a law: a consumer transition asks for 300, a fifteen times
+ * harder flick. Without a way to name it, a declarative drag that wanted a
+ * different number would have to take over `onEnd` and give up the scrub for
+ * it.
+ */
+export declare const DEFAULT_COMMIT_VELOCITY = 20;
+export declare const resolveSwipeOptions: (transition: Transition) => ResolvedSwipe | null;
+export default resolveSwipeOptions;

package/dist/transition/swipeSettle.d.ts

@@ -33,20 +33,40 @@ export declare const MIN_REVERSAL_SECONDS = 0.28;
  *
  * So the floor scales with what is left to travel: a release may outrun the
  * authored motion, because the finger genuinely was faster, but not without
- * limit. At 3x, a full-width cupertino landing bottoms out near 0.21s against
- * its authored 0.7s — brisk, continuous with the gesture, and still
- * unmistakably motion. Expressed against the author's own clock and span
- * rather than as pixels per second, so it means the same thing on any screen
- * and under any transition.
+ * limit. Expressed against the author's own clock and span rather than as
+ * pixels per second, so it means the same thing on any screen and under any
+ * transition.
  *
- * THE NUMBER IS A CEILING ON THE ARTIFACT, NOT ON THE FINGER. A human flick
- * tops out around six or seven screen-widths a second; the readings that
- * produced the defect were several times that, which is a coalesced pointer
- * pair over a 4ms gap rather than a hand. 3x leaves every honoured release in
- * the device-judged table above exactly where it was — the fastest of them
- * departs at 2.8x — and only clips what no finger did.
+ * IT WAS 3x, AND 3x WAS CHOSEN SO THAT IT WOULD NOT BIND. The argument ran: a
+ * human flick tops out around six or seven screen-widths a second, the
+ * readings that produced the vanishing screen were several times that, so a
+ * ceiling above the hand "only clips what no finger did". Both halves were
+ * true and the conclusion was backwards. A ceiling no hand can reach is not a
+ * ceiling: on cupertino's 390px over 0.7s the floor only starts to bind above
+ * 2674 px/s, so the by-speed term alone decides every release a person can
+ * actually make, and it lets one run at up to 2.9x the authored motion. That
+ * band IS the hand. Device-reported against the 3x floor itself: "조금 빠르게
+ * 하면 휙 그냥 씹히듯 지나간다".
+ *
+ * 1.2 WAS PICKED ON GLASS, from a ladder of builds identical but for this
+ * number (3 / 2 / 1.5 / 1.2, judged on a device against the same gesture). It
+ * is the first value that reaches the speeds a hand produces: 2 moves nothing
+ * below 1783 px/s and 1.5 nothing below 1337, while 1.2 binds from 1070 up. A
+ * full-width cupertino landing then bottoms out at 0.583s against its authored
+ * 0.7s, and a fast release with 30% travelled lands in 0.408s where it used to
+ * take 0.163s.
+ *
+ * WHAT IT DOES NOT TOUCH. A release slower than the ceiling is unchanged — the
+ * by-distance and by-speed terms already ask for longer than the floor, and
+ * that is most of them. A CANCEL is unchanged outright: a reversal contributes
+ * no speed, so its length is the by-distance term, which is `authored x
+ * remaining` and therefore above this floor by construction at any multiplier
+ * over 1.
+ *
+ * A RELEASE STILL OUTRUNS THE BUTTON, by a fifth. What it no longer does is
+ * outrun it threefold.
  */
-export declare const MAX_RELEASE_SPEEDUP = 3;
+export declare const MAX_RELEASE_SPEEDUP = 1.2;
 export interface SwipeSettleInput {
     remainingPx: number;
     spanPx: number;

package/dist/transition/typing.d.ts

@@ -28,43 +28,182 @@ export interface SwipeInfo {
     };
 }
 export type SwipeAnimate = (target: HTMLElement, value: TransitionTarget, options?: AnimationOptions) => Promise<void>;
-export type TransitionOptions = {
-    decoratorName?: DecoratorName;
-    driver?: "native";
-    swipeDirection: "x" | "y";
-    onSwipeStart: (event: PointerEvent, info: SwipeInfo, options: {
+/**
+ * One pose along a drag, and where the drag reaches it.
+ *
+ * A single destination makes every property travel at one rate, because one
+ * progress walks one keyframe. Some drags do not: a screen may finish fading
+ * a third of the way across while it is still sliding out for the rest of it.
+ * Naming the pose at that third is what lets the two rates coexist without
+ * handing the whole drag to a hook.
+ *
+ * `at` is where along the drag this pose is reached, 0 to 1, and the last stop
+ * is the end whether or not it says so. It is spelled `at` rather than
+ * `offset` because `offset` is already a CSS property and `TransitionTarget`
+ * carries the whole CSS vocabulary.
+ */
+export interface SwipeStop {
+    at?: number;
+    value: TransitionTarget;
+}
+/**
+ * Everything a transition says about its swipe, in one place.
+ *
+ * WRITING NOTHING BUT A DIRECTION IS A COMPLETE SWIPE. The drag is this
+ * transition's own pop keyframes walked by the gesture, the release decides on
+ * the distance travelled and the speed at which the finger left, and the
+ * landing runs on the clock the controller already computes. The hooks below
+ * exist for the drag that is NOT that — a screen that shrinks and is carried
+ * about freely, say — and taking one over is what tells flemo to stand aside.
+ */
+export interface SwipeOptions {
+    /**
+     * The axis the gesture travels. Required, and deliberately without a
+     * default: a stack of pages swipes on x and a sheet on y, both are ordinary,
+     * and a silent guess would be wrong half the time. A transition with no
+     * swipe leaves `swipe` off altogether.
+     */
+    direction: "x" | "y";
+    /**
+     * How far the gesture must carry the screen before the release navigates
+     * rather than returning it, in px. A number is that distance; a function is
+     * handed the screen's own span so a transition can ask for a fraction of it.
+     *
+     * The default is the iOS-derived 50px on a 390px screen, expressed as a
+     * fraction so it means the same thing on any width.
+     *
+     * The SPEED half of the same question is not authorable: every preset used
+     * the same "or the finger was still moving" floor, so it is the controller's
+     * and stays out of the way.
+     */
+    threshold?: number | ((span: number) => number);
+    /**
+     * Where the drag carries the screen under the finger, when that is not where
+     * this
+     * transition's pop takes it.
+     *
+     * The drag is this transition's own pop walked by the finger, and for most
+     * transitions that is exactly right. For some it is not: a drag may pull a
+     * screen down that the pop only fades, or dip an opacity the pop takes all
+     * the way to zero. Those differ in SHAPE rather than in rate, so `progress`
+     * cannot express them, and before this the only way to author one was to
+     * take over `onMove` and give up the scrub.
+     *
+     * Only the destination is named. The drag starts where the screen already
+     * is, which is the same pose the pop starts from, so it is read from the
+     * same table (see FROM_VARIANT).
+     *
+     * An empty target means the side does not move at all. A LIST of stops (see
+     * `SwipeStop`) says the drag passes through poses on the way, which is how
+     * two properties travel at different rates.
+     */
+    current?: TransitionTarget | readonly SwipeStop[];
+    /** Where the drag carries the screen underneath. Terms as `current`. */
+    prev?: TransitionTarget | readonly SwipeStop[];
+    /**
+     * The speed at which a release navigates however little it travelled, in the
+     * units of `SwipeInfo.velocity`.
+     *
+     * The distance half of the verdict asks whether the gesture went far enough;
+     * this asks whether it was still going when the finger left. A flick that
+     * covers 20px and lets go at speed reads as "go", and a slow drag parked
+     * short of `threshold` reads as "come back".
+     *
+     * The default is the 20 all three presets had written for themselves, which
+     * is their taste rather than a law: a consumer transition in this repo's own
+     * app asks for 300, a fifteen times harder flick. Without this a declarative
+     * drag has no way to ask for a different one, and taking over `onEnd` to
+     * carry a single number costs it the scrub.
+     */
+    velocity?: number;
+    /**
+     * Where the gesture is along its own travel, 0 to 1, per side.
+     *
+     * The default is geometric: how far the screen has been carried over its own
+     * width or height. A drag that resists, eases or clamps says so here, so the
+     * FEEL stays the author's while the keyframes stay the transition's.
+     *
+     * TWO NUMBERS, NOT ONE, because the two sides legitimately walk at different
+     * rates. `material` is the case that proves it: the screen being pushed away
+     * travels its own height, so its progress keeps growing as the rubber band
+     * stretches, while the screen arriving underneath travels 56px and stops
+     * there. One scalar cannot say both, and a drag driven by the wrong one is a
+     * drag that no longer resists.
+     *
+     * `current` is the screen under the finger and `prev` is the one coming out
+     * from under it, which are the same two the hooks are handed as
+     * `currentScreen` and `prevScreen`.
+     */
+    progress?: (info: SwipeInfo, span: number) => number | {
+        current: number;
+        prev: number;
+    };
+    /**
+     * Whether the gesture may begin at all. Returning false abandons it before
+     * anything moves.
+     */
+    onStart?: (event: PointerEvent, info: SwipeInfo, options: {
         animate: SwipeAnimate;
         currentScreen: HTMLDivElement;
         prevScreen: HTMLDivElement;
         onStart?: (triggered: boolean) => void;
     }) => Promise<boolean>;
-    onSwipe: (event: PointerEvent, info: SwipeInfo, options: {
+    /**
+     * Move the screens yourself, once per follow frame.
+     *
+     * TAKING THIS OVER MEANS FLEMO DOES NOT. The screens are yours for the whole
+     * drag, so the two of you can never be writing one transform between you —
+     * which is what makes a bar drift from the screen it rides. The cost is that
+     * the drag is a style write per frame rather than an animation the
+     * compositor owns, and the release then has to commit one (see the note on
+     * the scrub in createSwipeController for what that measures).
+     */
+    onMove?: (event: PointerEvent, info: SwipeInfo, options: {
         animate: SwipeAnimate;
         currentScreen: HTMLDivElement;
         prevScreen: HTMLDivElement;
         /**
-         * 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.
+         * 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.
          */
         onProgress?: (triggered: boolean, progress?: number) => void;
     }) => number;
-    onSwipeEnd: (event: PointerEvent, info: SwipeInfo, options: {
+    /**
+     * Land what the drag was carrying. Same terms as `onMove`.
+     *
+     * WHOEVER OWNS THE SCREENS OWNS THE VERDICT. A transition that took them
+     * over answers the commit question here, and its answer is the navigation's.
+     * One written beside a declared destination is told the answer instead: it
+     * arrives as `triggered`, the clock every participant lands on is already
+     * settled, and whatever this returns is not read — so a hook that only wants
+     * to land an element of its own does not have to restate a rule it has no
+     * opinion about.
+     */
+    onEnd?: (event: PointerEvent, info: SwipeInfo, options: {
         animate: SwipeAnimate;
         currentScreen: HTMLDivElement;
         prevScreen: HTMLDivElement;
+        /** The verdict, when flemo owns the screens and has already decided. */
+        triggered?: boolean;
         onStart?: (triggered: boolean) => void;
-    }) => Promise<boolean>;
-} | {
+    }) => Promise<boolean | void>;
+}
+/**
+ * A transition's non-keyframe options.
+ *
+ * IT USED TO BE A UNION discriminated on a flat `swipeDirection`, with the
+ * three hooks required alongside it. Every option added to the swipe then had
+ * to be declared absent on the other arm as well (`swipeDirection?: never`) or
+ * a caller holding the union could not read it without narrowing first, and
+ * the padding grew with the surface. One optional object says the same thing,
+ * present is a swipe and absent is not, and says it once.
+ */
+export type TransitionOptions = {
     decoratorName?: DecoratorName;
     driver?: "native";
-    swipeDirection?: never;
+    swipe?: SwipeOptions;
 };
 export interface BaseTransition {
     name: TransitionName;

package/dist/transition/variantMotion.d.ts

@@ -6,6 +6,10 @@ export type MotionTarget = TransitionVariantValue["value"] | InitialTarget;
 export interface VariantMotion {
     from: MotionTarget;
     to: MotionTarget;
+    via?: readonly {
+        at: number;
+        value: MotionTarget;
+    }[];
     duration: number;
     delay: number;
     ease: AnimationOptions["ease"] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flemo/core",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Framework-agnostic primitives for flemo: history, navigation, transitions, task manager.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",
@@ -45,7 +45,7 @@
     "jsdom": "^29.1.1",
     "typescript": "^6.0.3",
     "vite": "^8.2.2",
-    "vite-plugin-dts": "^5.0.3",
+    "vite-plugin-dts": "^5.1.0",
     "vitest": "^4.1.11"
   },
   "publishConfig": {