@flemo/core 2.2.0 → 2.2.1

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

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

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

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

package/dist/morph/morphFace.d.ts

@@ -0,0 +1,61 @@
+/** The two ratios a face's height is built from, per em. */
+export interface FaceRatios {
+    ascent: number;
+    descent: number;
+}
+/**
+ * The face's ascent and descent per em, or null where they cannot be had.
+ *
+ * Keyed on the font shorthand, so every element wearing the same type shares
+ * one answer for the session.
+ */
+export declare const faceRatios: (font: {
+    family: string;
+    weight: string | number;
+    style: string;
+}) => FaceRatios | null;
+/** The grids an engine is known to snap the two halves of a face height to. */
+export declare const faceGrids: () => number[];
+/**
+ * The face height the line box will be built from, at one size.
+ *
+ * `scale` is the reciprocal of the grid: 1 for whole pixels, the device pixel
+ * ratio for device pixels.
+ */
+export declare const faceHeightAt: (size: number, ratios: FaceRatios, scale: number) => number;
+/** The two halves of a face's box at one size, as the font reports them. */
+export interface FaceParts {
+    ascent: number;
+    descent: number;
+}
+/**
+ * The face's ascent and descent at one size, as the font reports them.
+ *
+ * The same numbers the line box is built from, got without laying anything out.
+ * The BASELINE sits at the ascent below the inline box's top, so a flight that
+ * holds its half-leading still is only half done: the ascent is on the same
+ * grid and steps just as often (see morphLine).
+ */
+export declare const faceParts: (size: number, font: {
+    family: string;
+    weight: string | number;
+    style: string;
+}, scale: number) => FaceParts | null;
+/** The face's own height at one size: its two halves added up. */
+export declare const faceHeight: (size: number, font: {
+    family: string;
+    weight: string | number;
+    style: string;
+}, scale: number) => number | null;
+/**
+ * Every size in `[from, to]` at which the face height MIGHT change.
+ *
+ * Arithmetic only, and deliberately: each half of the height steps where
+ * `size * ratio` crosses a half of the grid, which gives the candidates. Where
+ * each one really falls is not settled here, because the thing that has to be
+ * exact is the TIME the flight meets it, and only the caller knows the curve
+ * that maps one to the other (see morphLine).
+ */
+export declare const faceAims: (from: number, to: number, ratios: FaceRatios, scale: number) => number[];
+/** Whether two faces are the same height, ascent and descent alike. */
+export declare const sameFace: (a: FaceParts, b: FaceParts) => boolean;

package/dist/morph/morphGeometry.d.ts

@@ -54,8 +54,56 @@ export interface MorphSnapshot {
      * complete as the last thing someone noticed on glass.
      */
     paint: Record<string, string>;
+    /**
+     * Whether this end is ONE LINE of text.
+     *
+     * A flight animates the element's box, and the element in flight is the
+     * ARRIVAL's tree — so it re-wraps at every width on the way, under the
+     * arrival's own line-breaking rules rather than the departure's. Where both
+     * ends are single lines that is always wrong: the label was one line, the
+     * heading is one line, and the flight puts a second one in between. Measured
+     * on the playground's poster grid, on an iPhone: a cell's meta line broke
+     * after the middle dot for the first four frames of a push, because the
+     * detail's span has no `truncate` and the cell's width does not fit it.
+     *
+     * Read for both ends so the flight can hold a single line when it knows the
+     * journey has no honest reason to have two (see `holdsOneLine`).
+     */
+    singleLine: boolean;
+    /**
+     * The height of this end's first line of text, in px — the face's own ascent
+     * plus descent at the size it renders.
+     *
+     * It is the other half of where a line SITS in its box: the half-leading is
+     * `(line-height - this) / 2`, and both engines render that floored to whole
+     * pixels. A flight that interpolates the leading has to know where those
+     * boundaries are to avoid ending on one (see morphLine's `leadingBias`).
+     *
+     * Null for anything that is not one run of text, and for a measurement taken
+     * through an ancestor's scale, which is not the face's own height.
+     */
+    textHeight: number | null;
+    /**
+     * Where this end's line actually SITS: the rendered distance from the box's
+     * top to the top of its text run, in px.
+     *
+     * The engines floor the half-leading to whole pixels, and this is the floored
+     * answer they gave — not a derivation. It is what the landing will paint, and
+     * a correction that cannot reproduce it from `line-height` and `textHeight`
+     * has misread the rule and declines to act (see morphLine's `leadingBias`).
+     */
+    leadOffset: number | null;
 }
 export declare const rectCentre: (rect: MorphRect) => PosePoint;
+/**
+ * Is a box of this height a single line of type?
+ *
+ * Exported because the height to ask about is not always the measured one: a
+ * NESTED arrival is measured inside a container that is already staged at its
+ * from-box, so its staged height is the wrapped one — the very thing the answer
+ * is used to prevent. Its rest height is the honest one.
+ */
+export declare const isSingleLine: (height: number, lineHeight: number | null, fontSize: number | null) => boolean;
 export declare const captureMorphSnapshot: (element: HTMLElement) => MorphSnapshot;
 /**
  * A painted rect mapped back into the space its ancestor's transform is applied

package/dist/morph/morphKeyframes.d.ts

@@ -31,6 +31,30 @@ export interface MorphKeyframeSet {
      * one, the corner where the corner is all that changes.
      */
     geometryName: string;
+    /**
+     * Whether the geometry keyframe is one the COMPOSITOR can run.
+     *
+     * True only where the travel is a transform and nothing else. A keyframe that
+     * also carries a box, a type size or a clip is resolved by the MAIN THREAD,
+     * once per frame it manages to produce — and anything that has to stay
+     * registered with it has to be presented from there too (see the camera).
+     */
+    geometryAccelerated: boolean;
+    /**
+     * The `translate` the caller must set on the element, or null.
+     *
+     * Non-null where the travel is driven through registered properties, which
+     * is what keeps its position on the same thread as its size.
+     */
+    translate: string | null;
+    /**
+     * The `transform` the caller must set on the element, or null.
+     *
+     * Non-null only for a PINNED set, whose keyframes animate the pose's
+     * coordinates rather than the transform itself, and which therefore needs the
+     * transform that reads them (see PINNED_POSE_TRANSFORM).
+     */
+    transform: string | null;
 }
 /**
  * The keyframes and the `animation` shorthand for one side of a morph.
@@ -69,6 +93,37 @@ export declare const buildMorphKeyframes: (input: {
         from: number;
         to: number;
     } | null;
+    /**
+     * The line-height as a STAIRCASE, holding the leading still for the flight.
+     *
+     * Supersedes `lineHeight` where it is given: the two cannot both author the
+     * property, and the staircase is the one that keeps the glyphs from stepping
+     * inside the box (see morphLine). It rides its own animation because it needs
+     * its own timing — each stop HOLDS until the next, which is what a staircase
+     * is, and the geometry keyframe cannot hold one channel while easing the rest.
+     */
+    leading?: {
+        at: number;
+        lineHeight: number;
+    }[] | null;
+    /**
+     * The ascent's staircase, carried backwards on the box so the two cancel.
+     *
+     * A held leading still leaves the BASELINE stepping, because it sits an
+     * ascent below the inline box's top and the ascent is on the same grid. The
+     * two terms are both grid-locked, so nothing done to the line-height can make
+     * their sum smooth. The box under them is not grid-locked, so the flight
+     * sends the box the OTHER way by the same amount and the glyphs come out
+     * still: the box travels to `top + ascent` and a transform takes the ascent
+     * straight back off, exactly at both ends and within half a pixel between.
+     *
+     * A box wobbling half a pixel is nothing to look at; a line of type doing it
+     * is the tremor this exists to remove.
+     */
+    lift?: {
+        at: number;
+        ascent: number;
+    }[] | null;
     /** Type's other two dimensions, so it re-typesets rather than merely re-sizing. */
     fontWeight?: {
         from: number;
@@ -147,15 +202,69 @@ export declare const buildMorphKeyframes: (input: {
         from: string;
         to: string;
     }[];
+    /**
+     * Keep this set on the main thread even where its geometry is a transform the
+     * compositor could have run.
+     *
+     * A flight is one composition, and its parts are placed relative to each
+     * other. The moment one of them travels by its box — which is every flight
+     * where the element GROWS rather than being scaled — the frames it can be
+     * drawn on are the main thread's, and a part that keeps advancing without it
+     * separates from it by however far behind that thread is. A ghost is the
+     * clearest case: it is a copy of the departure whose only job is to sit on
+     * the element it dissolves into, and one that leads prints the card twice.
+     *
+     * So the flight decides once, and every part it emits abides by it. Ignored
+     * where the geometry is already layout-bound, which needs no help.
+     */
+    pinned?: boolean;
+    /**
+     * Drive the travel's own position through registered properties.
+     *
+     * False only where they could not be registered, and there the position goes
+     * back to `left` and `top`: a literal `translate` would be run by WebKit's
+     * compositor while the size it belongs to waits for the main thread.
+     */
+    travelPinned?: boolean;
 }) => MorphKeyframeSet;
 /**
  * The CAMERA: the transform that takes a screen from resting to "zoomed onto
  * this element", for a flight that carries its screen.
  *
- * One uniform scale and one translate, both literal — the same discipline the
- * travel keeps, and for the same reason: a compiled animation whose values come
- * from custom properties was device-bisected off the compositor on WebKit
- * (see the literal-timing note in compileTransitionStyles).
+ * One uniform scale and one translate.
+ *
+ * THE CAMERA IS NOT AN ANIMATION OF ITS OWN. It is defined as exactly the zoom
+ * that carries the element from one end of the flight to the other, and the two
+ * are emitted on one clock: same duration, same delay, same easing, released
+ * together. Measured, they agree to a thousandth of a frame at every sample.
+ *
+ * They still do not agree ON GLASS, because they are not PRESENTED by the same
+ * thread. A transform is one of the few things a compositor can run by itself,
+ * so the camera advances every vsync whatever the page is doing; the element
+ * travels by its box, which no compositor can interpolate, so it advances only
+ * on frames the main thread manages to produce. Isolated on both engines: with
+ * the main thread blocked mid-flight, a transform twin of a box travel ran 146px
+ * (Blink) and 167px (WebKit) ahead of it before the box moved at all. That gap
+ * is the whole defect — a card trailing the grid it is supposed to be opening
+ * out of, reported from iOS Safari as the camera being a beat ahead of the card.
+ *
+ * So where the element it carries is main-thread bound, the camera is too: the
+ * transform is composed from REGISTERED custom properties and the keyframes
+ * animate those, which no compositor can run because the substitution is style
+ * resolution's work. It then advances on exactly the frames the element does,
+ * and the pair is rigid again at whatever rate the device can hold.
+ *
+ * That is the only lever that works. `calc(var())` in the timing — the one this
+ * codebase already knew took a fade off WebKit's compositor — leaves a literal
+ * transform accelerated on both engines, as do constant `left`, `background-color`
+ * and `clip-path` channels alongside it; all four were measured to run away from
+ * the main thread exactly as the plain transform did. It costs nothing: the
+ * screen keeps its layer, so the per-frame work is a style resolution and a
+ * transform update, and frame times were indistinguishable from the literal form
+ * at 1x, 6x and 12x CPU throttle.
+ *
+ * Where the element's own travel IS a transform, the camera stays literal and
+ * accelerated: there is then nothing main-thread bound for it to wait for.
  *
  * The scale comes from WIDTH alone. The element's own box changes aspect across
  * the flight, so no single uniform scale can match both axes, and width is the
@@ -184,6 +293,14 @@ export declare const buildCameraKeyframes: (input: {
     start: number;
     ease: AnimationOptions["ease"];
     selector: string;
+    /**
+     * Emit the literal transform the compositor can run.
+     *
+     * True only where the element this camera carries is itself on the
+     * compositor; false pins the camera to the main thread's cadence, which is
+     * where a box travel lives (see above).
+     */
+    accelerated: boolean;
 }) => {
     rules: string[];
     name: string;

package/dist/morph/morphLine.d.ts

@@ -0,0 +1,73 @@
+import { AnimationOptions } from '../transition/cssTypes';
+/** The properties the hold writes, so a caller can reason about what it costs. */
+export declare const LINE_HOLD: {
+    readonly whiteSpace: "nowrap";
+    readonly overflow: "hidden";
+    readonly textOverflow: "ellipsis";
+};
+/**
+ * Hold the flying element to one line for the duration of a flight.
+ *
+ * Written as inline style, which is what the landing restores wholesale — the
+ * hold needs no undo of its own.
+ */
+export declare const holdOneLine: (element: HTMLElement) => void;
+/** Whether a flight between these two ends should hold a single line. */
+export declare const holdsOneLine: (from: boolean, to: boolean) => boolean;
+/**
+ * Extra leading, in px, for BOTH ends of a flight so the half-leading it
+ * renders never crosses a pixel boundary.
+ *
+ * Zero when either end cannot be measured, and zero when the travel is wider
+ * than one pixel of half-leading — no offset fits it in one, and a step
+ * somewhere is then the honest outcome. Mid-flight is where it belongs.
+ */
+export interface LeadingEnd {
+    lineHeight: number | null;
+    textHeight: number | null;
+    /** What the engine actually rendered for this end (see MorphSnapshot). */
+    leadOffset: number | null;
+}
+export declare const leadingBias: (from: LeadingEnd, to: LeadingEnd) => number;
+export default holdOneLine;
+export interface LeadingEndType {
+    fontSize: number | null;
+    lineHeight: number | null;
+    /** The face height the engine actually reported for this end. */
+    textHeight: number | null;
+}
+export interface LeadingStop {
+    /** Percent of the flight, 0 to 100. */
+    at: number;
+    lineHeight: number;
+    /**
+     * The face's ascent from this stop on.
+     *
+     * A held leading is only half the answer. The BASELINE sits an ascent below
+     * the inline box's top, and the ascent is on the same grid the leading is, so
+     * it steps just as often — device-measured at seventeen steps of half a pixel
+     * across one flight of forty-nine frames, which is a jump every third frame.
+     *
+     * Neither term can be made smooth: both are on the grid, so their sum is too,
+     * and a baseline that has nine and a half pixels of grid to climb must climb
+     * it in steps. What CAN be smooth is the box under them, because a box's
+     * position is not on any grid — so the flight carries the ascent's staircase
+     * BACKWARDS on the box and lets the two cancel (see `lift`).
+     */
+    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;

package/dist/morph/morphPose.d.ts

@@ -40,5 +40,35 @@ export declare const poseToCss: (pose: MorphPose) => string;
  * measured travel and an author's flourish stack on one element instead of
  * needing a wrapper each.
  */
+export declare const composePoses: (poses: MorphPose[]) => MorphPose[];
 export declare const composePosesToCss: (poses: MorphPose[]) => string;
+/** The `translate` an element wears while its travel is pinned. */
+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;
+/** The `transform` an element wears while its pose is pinned. */
+export declare const PINNED_POSE_TRANSFORM: string;
+/**
+ * The registrations the pinned form needs, inserted once per document.
+ *
+ * They have to be REGISTERED: an unregistered custom property is a string to
+ * the engine and animates discretely, which would teleport a pose at its
+ * midpoint instead of interpolating it.
+ *
+ * One set of names for every flight rather than one per participant, because a
+ * registration is document-wide and re-registering invalidates style for the
+ * whole page. `inherits: false` is what makes that safe: each element holds its
+ * own values, so two flights never read each other's and no descendant inherits
+ * a pose meant for its parent.
+ */
+export declare const PINNED_POSE_PROPERTY_RULES: string[];
+/**
+ * One pose as the keyframe declarations that drive `PINNED_POSE_TRANSFORM`.
+ *
+ * Every channel is written at both ends even where it does not change, because
+ * these are the coordinates of one transform rather than five animations: an
+ * end that omitted a channel would interpolate it from its registered initial
+ * value instead of holding it.
+ */
+export declare const pinnedPoseDecls: (pose: MorphPose, indent?: string) => string;
 export declare const interpolatePose: (from: MorphPose, to: MorphPose, progress: number) => MorphPose;

package/dist/morph/morphSheet.d.ts

@@ -7,3 +7,12 @@
  * would by then point at someone else's keyframes.
  */
 export declare const insertMorphRules: (rules: string[]) => (() => void);
+/**
+ * Register the pinned pose's custom properties, and report whether they took.
+ *
+ * A browser that does not understand `@property` refuses the rule, and there
+ * every pose has to stay literal: unregistered, those properties would animate
+ * discretely and teleport a pose at its midpoint rather than interpolating it.
+ * A part that leads the rest of its flight is a flaw; one that jumps is a break.
+ */
+export declare const ensurePinnedPoses: () => boolean;

package/dist/morph/morphSide.d.ts

@@ -22,6 +22,12 @@ export interface MorphSide {
     padding: string;
     margin: string;
     paint: Record<string, string>;
+    /** Whether this end is one line of text (see MorphSnapshot.singleLine). */
+    singleLine: boolean;
+    /** This end's first text run height (see MorphSnapshot.textHeight). */
+    textHeight: number | null;
+    /** Where this end's line was actually rendered (see MorphSnapshot.leadOffset). */
+    leadOffset: number | null;
     /**
      * Whether this screen's transition MOVES it — read from the DEFINITION, not
      * from the element: at the moment a flight is staged the arriving screen is

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

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

package/package.json

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