@flemo/core 2.2.1 → 2.2.2

package/dist/morph/__tests__/morphContents.test.d.ts

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

package/dist/morph/__tests__/pinParts.test.d.ts

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

package/dist/morph/attachMorph.d.ts

@@ -8,6 +8,18 @@ export interface AttachMorphOptions {
     name?: MorphTransitionName;
     /** The navigate store of the Router scope this element belongs to. */
     navigateStore: NavigateStoreApi;
+    /**
+     * Which side of which flight this end is on, from the binding.
+     *
+     * Only ever needed where the DOM cannot answer: a shared bar is rendered
+     * outside the screen scope it belongs to, so walking up from a morph in one
+     * leaves the screen entirely or lands on an enclosing Router's. Everything
+     * written inside a screen is answered by the walk and needs none of this.
+     */
+    ownership?: {
+        status: NavigateStatus;
+        active: boolean;
+    } | null;
 }
 interface MorphFlight {
     finish: () => void;
@@ -15,6 +27,8 @@ interface MorphFlight {
     element: HTMLElement;
     duration: number;
     start: number;
+    /** The flat lead-in inside `start`, so a nested set bakes the same one. */
+    head: number;
     ease: AnimationOptions["ease"];
     /**
      * Put the landing's safety net away, and set it again.

package/dist/morph/morphContents.d.ts

@@ -0,0 +1,36 @@
+/**
+ * WHETHER A BOX'S CONTENTS MOVE WHEN THE BOX CHANGES SIZE.
+ *
+ * Animating a morph's box is what makes it a growth rather than a stretch: the
+ * subtree lays itself out at every size on the way, which is the only way text
+ * can re-wrap into its new shape. That is a layout and a fresh raster of the
+ * subtree on every frame, and WebKit re-snaps the backing to the device grid
+ * each time, so a subtree that does not need to move gets carried a device
+ * pixel back and forth for the whole flight anyway.
+ *
+ * Measured on a consumer's pill: every descendant held ONE position for all
+ * twenty-three frames of the flight, and only the box's own near edge moved.
+ * Right-aligned contents in a box that grows leftward do not go anywhere. The
+ * per-frame layout produced no layout change at all, and the tremble was the
+ * whole of what it bought.
+ *
+ * Where that is TRUE, holding the box at the size that contains both ends and
+ * cutting the near edge back with a clip is the same picture, drawn once. Where
+ * it is FALSE the flight must animate the box for real, because something
+ * inside genuinely has a different place at the two ends.
+ *
+ * This is the difference between measuring that and guessing it from the box's
+ * shape. A shape says nothing about a consumer's subtree; two laid-out ends do.
+ */
+/** The corner a flight's box is anchored on, and grows away from. */
+export interface MorphAnchor {
+    x: "left" | "right";
+    y: "top" | "bottom";
+}
+export declare const contentsHoldAcrossBox: (element: HTMLElement, from: {
+    width: number;
+    height: number;
+}, to: {
+    width: number;
+    height: number;
+}, anchor: MorphAnchor) => boolean;

package/dist/morph/morphFace.d.ts

@@ -41,6 +41,11 @@ export declare const faceParts: (size: number, font: {
     weight: string | number;
     style: string;
 }, scale: number) => FaceParts | null;
+export declare const runAdvance: (text: string, size: number, font: {
+    family: string;
+    weight: string | number;
+    style: string;
+}) => number | null;
 /** The face's own height at one size: its two halves added up. */
 export declare const faceHeight: (size: number, font: {
     family: string;

package/dist/morph/morphKeyframes.d.ts

@@ -19,6 +19,24 @@ export interface MorphTravel {
     duration: number;
     /** Seconds from the release, platform head included. */
     start: number;
+    /**
+     * The platform's flat lead-in, ALREADY COUNTED IN `start`.
+     *
+     * A HEAD IS NOT A DELAY. Waiting it out as a delay leaves the animation
+     * uncommitted until the instant it must move, so a first frame that arrives
+     * late arrives PARTWAY THROUGH — the curve is entered wherever the clock
+     * says and everything before that is never drawn. Given here, the same
+     * seconds are baked into the keyframes as a flat stop instead: the animation
+     * is running and still, a late first frame lands inside the lead-in, and the
+     * curve plays from 0. The screens have ridden it this way since the head was
+     * invented; this is the flight riding it the same way.
+     *
+     * Painted frames off a consumer's phone, 60fps: the first frame the box was
+     * drawn on was already 67% of the way through its travel. The computed value
+     * ramped correctly throughout, which is why every main-thread probe called it
+     * healthy.
+     */
+    head?: number;
     ease: AnimationOptions["ease"];
 }
 export interface MorphKeyframeSet {
@@ -47,6 +65,30 @@ export interface MorphKeyframeSet {
      * is what keeps its position on the same thread as its size.
      */
     translate: string | null;
+    /**
+     * The `width` and `height` the caller must set on the element, or null.
+     *
+     * Non-null where the box's size is driven through registered properties,
+     * which is what keeps an engine from dropping it (see morphPose).
+     */
+    size: {
+        width: string;
+        height: string;
+    } | null;
+    /**
+     * The width the box is HELD at for the whole flight, or null.
+     *
+     * The viewport x of a far edge both ends agree on, when there is one.
+     *
+     * The element is placed FROM it — `left: calc(<edge>px - var(--flemo-box-w))`
+     * — so the edge is derived from the very channel the width animates on and
+     * the two round together. Reached as position + size instead, the engine
+     * rounds each to its own layout unit and their sum oscillates: measured on a
+     * consumer's pill, 366.000 with the anchor against 365.985 ± 0.015 without,
+     * reversing six times in twenty-three frames, and every right-aligned thing
+     * inside it followed.
+     */
+    heldEdge: number | null;
     /**
      * The `transform` the caller must set on the element, or null.
      *
@@ -55,6 +97,13 @@ export interface MorphKeyframeSet {
      * transform that reads them (see PINNED_POSE_TRANSFORM).
      */
     transform: string | null;
+    /**
+     * The `letter-spacing` the caller must set on the element, or null.
+     *
+     * Non-null where the tracking carries a correction, which is written as a sum
+     * of the author's own and the correction's, each on its own clock.
+     */
+    letterSpacing: string | null;
 }
 /**
  * The keyframes and the `animation` shorthand for one side of a morph.
@@ -88,6 +137,17 @@ export declare const buildMorphKeyframes: (input: {
         from: MorphRect;
         to: MorphRect;
     } | null;
+    /**
+     * Whether the two ends lay their CONTENTS out in the same places, measured.
+     *
+     * A box animates for real wherever this is false, because something inside
+     * has a different place at the two ends and only a layout per frame can take
+     * it there. Where it is true the subtree is the same picture at every size on
+     * the way, so the box is laid out ONCE and the near edge is cut back with a
+     * clip instead (see the reveal below). It is measured rather than inferred
+     * from the box's shape: a shape says nothing about a consumer's subtree.
+     */
+    contentsHold?: boolean;
     /** Type morphs by growing, not by being scaled: px at each end. */
     fontSize?: {
         from: number;
@@ -124,6 +184,29 @@ export declare const buildMorphKeyframes: (input: {
         at: number;
         ascent: number;
     }[] | null;
+    /**
+     * What the baseline owes at the START, in px, because the staircase holds the
+     * ARRIVAL's leading from the first frame (see attachMorph).
+     *
+     * Paid on the same channel as the ascent's cancellation and with the same
+     * shape: the whole amount at the departure, nothing at the landing, so what
+     * the flight travels is unchanged and only its first frame moves.
+     */
+    leadStart?: number | null;
+    /**
+     * The correction that keeps a growing run of glyphs from drifting apart.
+     *
+     * A run's width against its size is one curve, and where it leaves the
+     * straight line between its ends every glyph carries the error that piled up
+     * before it. Spread the negative of that over the gaps and it cancels (see
+     * morphLine). It rides `letter-spacing` beside the author's own tracking, on
+     * its own clock, and is RAMPED rather than held because what it cancels is a
+     * curve rather than a staircase.
+     */
+    track?: {
+        at: number;
+        fix: number;
+    }[] | null;
     /** Type's other two dimensions, so it re-typesets rather than merely re-sizing. */
     fontWeight?: {
         from: number;
@@ -186,12 +269,32 @@ export declare const buildMorphKeyframes: (input: {
         from: MorphClipInset;
         to: MorphClipInset;
     } | null;
+    /**
+     * The corner the box wears, so a clip that reveals it cuts a rounded shape
+     * rather than a square one (see the reveal below).
+     */
+    radius?: string | null;
     fade: {
         from: TransitionTarget | null;
         to: TransitionTarget | null;
         duration: number;
         /** Seconds to hold the from-pose before the fade runs, on top of `travel.start`. */
         delay?: number;
+        /**
+         * The curve, where the flight's own is not the right one.
+         *
+         * A HAND-OVER IS A STEP, NOT A RAMP. Two opacity ramps crossing never
+         * compose back to what they replaced: at the midpoint of a 1-to-0 against a
+         * 0-to-1, alpha compositing leaves 1 - (1 - 0.5) * 0.5 = 0.75 of the pair,
+         * and the engines do not even sample the two on the same phase. Device-read
+         * on a consumer's tab switch: the copy at 0.48 against the arrival at 0.33,
+         * two frames of a washed-out box mid-travel — read as a blink.
+         *
+         * A step at the same instant on both sides has no such midpoint. Both are
+         * pure functions of one timeline, so every frame that renders at all
+         * renders exactly one of them, and a missed frame cannot land between.
+         */
+        easing?: string;
     } | null;
     /**
      * Everything the two ends paint differently — corner, surface, border,
@@ -291,6 +394,8 @@ export declare const buildCameraKeyframes: (input: {
     settling: boolean;
     duration: number;
     start: number;
+    /** The flight's flat lead-in, baked here too: the camera is one of its parts. */
+    head?: number;
     ease: AnimationOptions["ease"];
     selector: string;
     /**

package/dist/morph/morphLine.d.ts

@@ -28,6 +28,23 @@ export interface LeadingEnd {
     /** What the engine actually rendered for this end (see MorphSnapshot). */
     leadOffset: number | null;
 }
+/**
+ * The half-leading a flight owes at its START, in px.
+ *
+ * The staircase holds ONE leading for the whole flight so the rendered
+ * half-leading cannot step, and the one it holds is the ARRIVAL's, because that
+ * is the value the landing has to restore. At the other end that makes the
+ * first frame render a line-height the departure never had, and half of that
+ * difference is where the departure's baseline sat.
+ *
+ * Half of the difference is not the answer, though: the engine puts the
+ * half-leading on a grid, so a line-height a pixel apart can render a whole
+ * pixel apart rather than half of one. Both ends reported where their line was
+ * actually put, so the grid is the one that reproduces both — the same
+ * authority `leadingBias` answers to — and where no candidate does, the
+ * arithmetic difference is the honest fallback.
+ */
+export declare const leadingOwed: (from: LeadingEnd, to: LeadingEnd, stops: LeadingStop[] | null) => number;
 export declare const leadingBias: (from: LeadingEnd, to: LeadingEnd) => number;
 export default holdOneLine;
 export interface LeadingEndType {
@@ -56,18 +73,24 @@ export interface LeadingStop {
      */
     ascent: number;
 }
-/**
- * The line-height stops that hold a type morph's leading still, or null.
- *
- * Null wherever the correction cannot be justified: a face whose metrics cannot
- * be read, an end that was never measured, a flight whose type does not change
- * size, and — the one that matters — a prediction that does not reproduce what
- * the engine actually reported at BOTH ends. That last is what stands in for a
- * browser check: an engine that does not quantise its face heights fails it at
- * every size, and is left alone.
- */
 export declare const leadingStops: (from: LeadingEndType, to: LeadingEndType, font: {
     family: string;
     weight: string | number;
     style: string;
 } | null, ease: AnimationOptions["ease"]) => LeadingStop[] | null;
+export interface TrackStop {
+    /** Percent of the flight, 0 to 100. */
+    at: number;
+    /** The correction, in px, to add to every gap between the glyphs. */
+    fix: number;
+}
+/** The tracking correction for a growing run, or null where there is none to make. */
+export declare const trackStops: (text: string, from: {
+    fontSize: number | null;
+}, to: {
+    fontSize: number | null;
+}, font: {
+    family: string;
+    weight: string | number;
+    style: string;
+} | null, ease: AnimationOptions["ease"]) => TrackStop[] | null;

package/dist/morph/morphPose.d.ts

@@ -42,10 +42,27 @@ export declare const poseToCss: (pose: MorphPose) => string;
  */
 export declare const composePoses: (poses: MorphPose[]) => MorphPose[];
 export declare const composePosesToCss: (poses: MorphPose[]) => string;
-/** The `translate` an element wears while its travel is pinned. */
+/** The size an element wears while its box is driven through the channel. */
+/** The channel a travelling box carries its width on, for anything placed from it. */
+export declare const BOX_WIDTH_PROPERTY: "--flemo-box-w";
+export declare const PINNED_BOX: string;
+export declare const PINNED_BOX_HEIGHT: string;
+/** One end of a pinned box, as the keyframe declarations that drive it. */
+export declare const pinnedBoxDecls: (width: number, height: number, indent?: string) => string;
+export declare const RULER: number;
+export declare const onRuler: (value: number) => number;
+export declare const pinnedBoxDeclsOnRuler: (width: number, height: number, indent?: string) => string;
+/** The `letter-spacing` an element wears while its tracking is corrected. */
+export declare const PINNED_TRACK: string;
+/** One end of the authored tracking. */
+export declare const pinnedTrackDecl: (value: number, indent?: string) => string;
+/** One stop of the correction that keeps a run from drifting apart. */
+export declare const pinnedTrackFixDecl: (value: number, indent?: string) => string;
 export declare const PINNED_TRAVEL: string;
 /** One end of a pinned travel, as the keyframe declarations that drive it. */
 export declare const pinnedTravelDecls: (x: number, y: number, indent?: string) => string;
+/** One stop of the ascent's staircase, on the half of the pair that holds. */
+export declare const pinnedLiftDecl: (ascent: number, indent?: string) => string;
 /** The `transform` an element wears while its pose is pinned. */
 export declare const PINNED_POSE_TRANSFORM: string;
 /**

package/dist/morph/morphSide.d.ts

@@ -39,11 +39,4 @@ export interface MorphSide {
     screenDuration: number;
     screenEase: AnimationOptions["ease"];
 }
-/**
- * Where one side of a morph really is, and how long its screen takes.
- *
- * The screen is read from the DOM PROTOCOL — its transition name is an
- * attribute — rather than from a store, so a morph works the same for any
- * binding and needs nothing threaded through from the consumer's tree.
- */
-export declare const resolveMorphSide: (element: HTMLElement, screen: HTMLElement, variant: TransitionVariant) => MorphSide;
+export declare const resolveMorphSide: (element: HTMLElement, owner: HTMLElement | null, variant: TransitionVariant) => MorphSide;

package/dist/morph/pinParts.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A PART IS NOT LAID OUT AT THE SIZES THE BOX PASSES THROUGH.
+ *
+ * A morph's box animates so that the subtree can lay itself out at every size
+ * on the way, which is what makes the artwork and the paired type GROW. A
+ * `<Part>` is the opposite declaration: it is the content that is NOT paired,
+ * that the flight hides and brings back on its own clock, precisely because it
+ * has no business being laid out at a cell's width.
+ *
+ * It was laid out there anyway. The part's own box still rode the growing box,
+ * so a page of copy inside a card re-wrapped the whole way up, and the part is
+ * brought back before the box has finished growing. Measured on the reference
+ * detail, frame by frame: the body copy stood at 147.88px tall for the first
+ * twenty frames of the flight, dropped a line to 126.75px on the twenty-first,
+ * and the facts list and the buy button under it jumped 23.55px up the screen
+ * in that one frame, with the copy already at full opacity.
+ *
+ * So a part is laid out ONCE, at the width it will rest at, and the box's
+ * growth is a clip over it rather than a re-wrap of it. Nothing is lost: the
+ * part is not on glass at those sizes, and where it is on glass the width is
+ * the one it lands at.
+ *
+ * The width alone. A part's HEIGHT is where the growth actually shows through
+ * to the parts below it, and holding that would pin a subtree to a height its
+ * own copy no longer needs.
+ */
+export declare const pinPartWidths: (element: HTMLElement) => (() => void);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flemo/core",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "description": "Framework-agnostic primitives for flemo: history, navigation, transitions, task manager.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",