@ng-native/fabric 0.17.1 → 0.18.1

package/dist/engine.d.ts

@@ -10,7 +10,7 @@
 import { type Conditions, type DeferredDeclaration, type StyleCache, type StyleSheet, type TokenValue } from './css.ts';
 import { type AnimationSpec, type Keyframe, type RunningAnimation, type Transition } from './transition.ts';
 import { type ComposedDrive, type DrivenProperty, type EventFeed, type FollowingTransform, type NativeAnimated, type ScrollAxis, type ScrollDrive, type ScrollRange, type StaticTransform } from './native-drive.ts';
-import type { DrivenChannels } from './scroll-animation.ts';
+import { type DrivenChannels } from './scroll-animation.ts';
 export type FabricNode = {
     readonly __fabricNode: unique symbol;
 } | object;
@@ -18,6 +18,20 @@ export type FabricNode = {
 import type { HostEngine, HostNode, Settling } from './host.ts';
 import { type GridLayout, type Rect } from './grid.ts';
 import { type FlowPlan } from './flow.ts';
+/**
+ * A view whose paint native sets with no commit: see `Engine.paintNatively`. The shadow node
+ * Fabric holds for it can be behind what it paints, by the keys in `stale`.
+ */
+interface PaintState {
+    /** The props native paints on the view. */
+    readonly keys: Set<string>;
+    /** Those native has a newer value of than the shadow node. */
+    readonly stale: Set<string>;
+    /** Set to commit what is stale with the next merge, whatever changed. */
+    sync?: true;
+    /** Set where a transform painted is a move by a share of the box: see `repaintShares`. */
+    shares?: true;
+}
 /** A node's scroll-driven animation: what it plays, what drives it, and the frame it commits. */
 interface ScrollAnimation {
     readonly spec: AnimationSpec;
@@ -214,6 +228,12 @@ export interface EngineNode extends HostNode {
     nodeText: string;
     childList: EngineNode[];
     parent: EngineNode | null;
+    /**
+     * A child of this node that holds what is put in it: `appendChild` and `insertBefore` on this
+     * node put the child there instead, so a component's template lands inside a view its owner
+     * placed in the host element. Only the view itself goes in this node.
+     */
+    contentView?: EngineNode;
     listeners: Map<string, Set<(event: unknown) => void>> | null;
     /** CSS classes on this node, for selector matching. */
     classes: Set<string> | null;
@@ -319,6 +339,8 @@ export interface EngineNode extends HostNode {
      * on, or the root. Unset on every node that is not fixed.
      */
     fixedTo?: EngineNode;
+    /** Set by `markPage`: a `position: fixed` box inside this node is placed against it. */
+    page?: true;
     /**
      * Set once a child of this node has had an `order`: its children are then committed in that
      * order, which Yoga has no property for. Left set, since sorting children with none is nothing.
@@ -407,6 +429,10 @@ export interface EngineNode extends HostNode {
         readonly tag: number;
         readonly keys: Set<string>;
     };
+    /** What native paints on this view with no commit, while it does: see `paintNatively`. */
+    paint?: PaintState;
+    /** Props native painted ahead of the shadow node as the painter let go: see `leavePainting`. */
+    unsynced?: ReadonlySet<string>;
     /**
      * The last `transform` built from the individual transform properties, and what it was built
      * from. Reused while the parts are the same objects, so an unrelated change does not re-send it.
@@ -483,6 +509,8 @@ export interface EngineNode extends HostNode {
      * keeps it for the dismissal animation. See `Engine.withheld`.
      */
     presented?: true;
+    /** Committed and not to be seen or touched yet: see `Engine.hold`. */
+    held?: true;
     /** This node's own props changed. */
     propsDirty: boolean;
     /** This node's child list changed. */
@@ -501,6 +529,15 @@ export declare function declareNativeProps(elementName: string, props: Iterable<
  * host primitive's constructor; see `EngineNode.claimed`.
  */
 export declare function claimHost(node: HostNode): void;
+/**
+ * Make a view the page of what is inside it: a `position: fixed` box there is placed against this
+ * view and not the screen, as it is against a screen of a stack, and follows it as it is given
+ * another size. For a layer that is the window to what it holds and need not be the size of the
+ * screen. Marked before anything fixed is put in it: it is for as long as the view is. Not for
+ * a view that scrolls its overflow: what is fixed in it is committed in what scrolls, and would
+ * scroll with it.
+ */
+export declare function markPage(node: EngineNode): void;
 /**
  * Say that an element scrolls what overflows it, as a browser's does: with `overflow: auto` or
  * `scroll` it is committed as a scroll view, around one view that holds what it holds. For a
@@ -740,6 +777,10 @@ export declare function onFontsSettled(listener: (families: ReadonlySet<string>)
  * `Engine.fontsSettled`.
  */
 export declare function fontsSettled(families: Iterable<string>): void;
+/** Whether a view name is a text input's, for a committed view, which has a name and no node. */
+export declare const isTextInputView: (viewName: string) => boolean;
+/** Whether a node commits as a text input, the view that takes a cursor, on either platform. */
+export declare const isTextInput: (node: ViewNameNode) => boolean;
 /**
  * Commit every `elementName` as a direct child of its nearest `ancestorName`, wherever the
  * template put it, e.g. `registerHoist('native-header', 'screen')`.
@@ -926,6 +967,8 @@ export interface EngineStats {
     worstRenderMs: number;
     createdNodes: number;
     clonedNodes: number;
+    /** Changes of paint native was given in place of a commit: see `paintNatively`. */
+    paintedNatively: number;
 }
 export declare class Engine implements HostEngine {
     /** Scopes the CSS resolver's memo. Bumped once per commit. */
@@ -942,7 +985,8 @@ export declare class Engine implements HostEngine {
     private readonly styles;
     /** Whether to run the development checks, which a release build skips. */
     readonly dev: boolean;
-    private readonly now;
+    /** The clock transitions and animations run on, which a script reads where one has got to. */
+    readonly now: () => number;
     private onDirty;
     private onError;
     /** Nodes with at least one transition in flight, so a frame walks those and nothing else. */
@@ -1177,6 +1221,27 @@ export declare class Engine implements HostEngine {
     private lastConditions;
     updateConditions(next: Conditions): void;
     createElement(name: string, sheet?: StyleSheet | null): EngineNode;
+    /**
+     * Commit a node without it being seen or touched, or let it be again. A browser paints nothing
+     * until a task and its animation frame are over, and native draws each commit as it comes: what
+     * a library inserts, measures and only then styles is held for the frame between. Over every
+     * opacity and `pointerEvents` it has, an eased one included, which it is committed with again
+     * once let go. Nothing it matches changes, so nothing is styled again.
+     */
+    hold(node: EngineNode, held: boolean): void;
+    /**
+     * Stop showing the last frame of a node's finished `@keyframes` animation, where nothing holds
+     * it there any more: script took its hold away after it ended. The node is what the cascade
+     * gives it again with the next commit.
+     */
+    releaseFinished(node: EngineNode): void;
+    /**
+     * End a node's `@keyframes` animation now, as a script's `finish()` or `cancel()` does: at its
+     * end, which is its last frame where it fills forwards and its resting style where it does not,
+     * or with no effect of it at all. Native is stopped where it plays it, and what the view is drawn
+     * at set there too (see `endedNatively`). It stays ended while the node asks for the same one.
+     */
+    endPlaying(node: EngineNode, how: 'finish' | 'cancel'): void;
     addClass(node: EngineNode, name: string): void;
     removeClass(node: EngineNode, name: string): void;
     /**
@@ -1279,8 +1344,8 @@ export declare class Engine implements HostEngine {
     /** Angular's `@if`/`@for`/`ViewContainerRef` markers. Ordered, never committed. */
     createAnchor(): EngineNode;
     createText(value: string): EngineNode;
-    appendChild(parent: EngineNode, child: EngineNode): void;
-    insertBefore(parent: EngineNode, child: EngineNode, ref: EngineNode | null): void;
+    appendChild(into: EngineNode, child: EngineNode): void;
+    insertBefore(into: EngineNode, child: EngineNode, ref: EngineNode | null): void;
     /**
      * A node coming under a parent other than the one it is under, or under any once it has been
      * taken out: what is over it may be other than it was styled under. The resolver sees that for
@@ -1597,6 +1662,11 @@ export declare class Engine implements HostEngine {
      * optimisation.
      */
     commit(): boolean;
+    /**
+     * Whether a commit sent native nothing, every change in it being paint native was given
+     * directly: see `paintNatively`. Nothing was laid out, so nothing is read back.
+     */
+    private paintedOnly;
     /** Count a commit that reached native, and how long it took, in `stats`. */
     private countCommit;
     /** A field went out of view focused, in the commit running: see `undisplayed`. */
@@ -1718,6 +1788,11 @@ export declare class Engine implements HostEngine {
     /** Reconcile what is dirty and hand the tree to Fabric, which lays it out before returning. */
     private commitTree;
     private commitWhole;
+    /** The views the last `completeRoot` was given, and how many there have been. */
+    private sentHandles;
+    /** Set in a commit where a change was given to native to paint in place of being committed. */
+    private paintedInstead;
+    private rootsSent;
     /** The fixed boxes each page, or the root, is committed with. */
     private readonly fixedIn;
     /** Boxes found to be fixed while they were being committed under their parent. */
@@ -1726,6 +1801,45 @@ export declare class Engine implements HostEngine {
     private fingerOn;
     /** Boxes that became fixed or absolute with the finger on them, left under their parents. */
     private readonly fixedUnderFinger;
+    /** Whether a node moved with a finger on it waits for the finger to lift: `holdMovesUnderFinger`. */
+    private holdsMoves;
+    /**
+     * The nodes taken out of the parent they are committed under with a finger on them, each with
+     * that parent and the element that came after it there, which it stays before.
+     */
+    private readonly heldMoves;
+    /**
+     * Have a node that is moved to another parent, or taken out, while the first finger down is on
+     * it or on something in it stay committed where it was until the last finger lifts, and then
+     * go where it is. A native view moved to another parent is a view made again, which loses the
+     * touch on it: a web library that drags an element moves it as the drag begins, out of its list
+     * and on to the body, and its drag stopped there. The tree is moved at once, so what reads it
+     * finds the node where it was put, and only what native is told waits. Off, what is held goes
+     * where it is with the next commit.
+     */
+    holdMovesUnderFinger(on: boolean): void;
+    /** A node is taken out of `parent` from `at`: held there, where a finger is on it. */
+    private holdMove;
+    /** Whether a node is held under a parent other than the one it is in now. */
+    private heldElsewhere;
+    /**
+     * Add to a node's child handles each node held under it that has gone from it, before the
+     * element it came before where that is still there: reconciled where it is in the tree, so it
+     * is drawn as it is styled, and as it was last committed once it is out of the tree.
+     */
+    private heldHandles;
+    /**
+     * Have each parent a node is held under committed with its children again: a change to the node
+     * marks the way up from where it is in the tree, and not from where it is committed.
+     */
+    private markHolders;
+    /**
+     * A node is taken out of the page: each node held under it, or under what it holds, is let go,
+     * as there is nowhere left to draw it where it was. One moved elsewhere is drawn there.
+     */
+    private releaseHeldUnder;
+    /** The last finger is up: each node held goes where it is with the next commit. */
+    private releaseMoves;
     /** Note what a finger comes down on, and once the last has lifted move what waited for it. */
     private trackFinger;
     /** The page a box is on: the nearest view that holds one, or the root. */
@@ -1994,7 +2108,8 @@ export declare class Engine implements HostEngine {
     private unfit;
     /**
      * The boxes inside `node` that Yoga sizes from the room on offer and not from their content:
-     * one with a percentage width, and one that takes a share of a row from a basis of nothing.
+     * one with a percentage width or a percentage basis in a row, and one that takes a share of a
+     * row from a basis of nothing.
      * Nothing under a box with a width of its own in points is looked at: that width is its
      * content's room whatever it holds.
      */
@@ -2295,7 +2410,10 @@ export declare class Engine implements HostEngine {
      * return fresh objects, so diffing their output would re-send every image and shadow on every
      * unrelated change.
      */
-    /** What a touch on an element that keeps a drag holds off, while it lasts: see `holdSwipe`. */
+    /**
+     * What a touch on an element that keeps a drag holds off, while it lasts (see `holdSwipe`), and
+     * a node held unseen (see `hold`).
+     */
     private heldFor;
     /**
      * Exempt from the complexity limit deliberately, as `matchesCompound` is: a flat sequence of
@@ -2586,6 +2704,14 @@ export declare class Engine implements HostEngine {
      * what a pause, other frames or a view made again need, none of which native can be told of.
      */
     private backToScript;
+    /** Each animation started on a node held unseen (see `hold`), to be played once it is let go. */
+    private readonly startsUnheld;
+    /**
+     * Play an animation started on a node held unseen, once it is let go: its clock starts here, as
+     * a browser starts it as it first paints the element. Not where it was paused meanwhile, nor a
+     * second time where it was run again while held, which plays it here already.
+     */
+    private playUnheld;
     /** Start the clock on an animation, unless the node is already playing this one. */
     private startPlaying;
     /** Play an animation that has just started: by native's layout, by native's driver, or here. */
@@ -2740,6 +2866,120 @@ export declare class Engine implements HostEngine {
     private takeBackEased;
     /** Stop a clock native runs, and go on from JavaScript with each transition it was playing. */
     private backToScriptEased;
+    private readonly painter;
+    /** The views native paints, for letting go of those that leave the tree. */
+    private readonly paintedNodes;
+    /** When each prop a view paints with last changed: see `paintedAgain`. */
+    private readonly paintChanges;
+    private quietTimer;
+    /**
+     * Give native the paint a commit would carry, where it is all that changed: a view whose
+     * transform, opacity or background is changed again and again, a progress bar stepped every
+     * 50ms, is painted by a native animated graph and leaves nothing to commit. Answers what is
+     * left of `payload` to commit.
+     *
+     * The first change of a prop is committed as any other. The second within `PAINT_RUN_MS` is
+     * committed too, with `collapsable: false` so the view is kept for native to paint, and from
+     * the next native paints it. The shadow node falls behind what is drawn; it is brought up to
+     * date with the next commit of the view for anything else, once the view has been left alone
+     * for `PAINT_QUIET_MS`, and before anything measures where it is drawn.
+     *
+     * A view a graph of native's has set a transform or an opacity on before is left to
+     * `setOwned`, which sets each later change of those on native: see `Touched`.
+     */
+    private paintNatively;
+    /** The props other graphs of native's set on a view now. */
+    private heldOn;
+    /**
+     * What is left to commit of a payload native was given: nothing, where all it changed is
+     * painted in a run, and otherwise all of it, with what native painted ahead of the shadow node.
+     */
+    private leftOver;
+    /** Set on native what a view paints, of the props no other graph of native's holds. */
+    private paintNow;
+    /**
+     * Whether a run of changes can hand a view to native: a plain view no animation of native's
+     * plays. A transition native plays is played on the painter's graph from then on, and a prop
+     * another graph holds now is committed as before (`heldOn`).
+     */
+    private paintsHere;
+    /** Have native paint a view, with no props yet: `paintRun` adds them. */
+    private paintFrom;
+    /**
+     * Whether a payload changes paint native could paint, and whether each such change is in a
+     * run, where a run can hand the view over. Takes on each prop in a run, and each a graph of
+     * native's has set on the view, which a commit no longer changes (see `Touched`).
+     * A change in no run is committed as well as painted: a fade a press starts and a transition
+     * that ends are a commit each, as they were, and the shadow node is never behind for them.
+     */
+    private paintRun;
+    /**
+     * Nothing to commit of a change native has painted: the view keeps its shadow node, and its
+     * committed props are what the next change is measured from.
+     */
+    private leftToNative;
+    /** A payload with what native painted ahead of the shadow node, which it brings up to date. */
+    private withStale;
+    /** Have native paint a view from the next change, where this one is the second of a run. */
+    private startPainting;
+    /**
+     * Whether a change of a prop a view paints with is the second of a run, soon after the last.
+     * Two at the same moment are one: an animation's last frame and the style it rests at.
+     */
+    private paintedAgain;
+    /** What a view paints for a key: where a transition native eases it is going, if it is. */
+    private paintedValue;
+    /**
+     * What native is to paint for these keys, and those it cannot take: a colour it cannot
+     * parse. A transform the transform node cannot take, a matrix or a move by a share of a box
+     * with no size yet, is painted whole (`PaintValues.transform`).
+     */
+    private paintValues;
+    /**
+     * An opacity as native is to paint it: no lower than what still takes a touch, on a view that
+     * takes presses, as a commit sends it (`stillTouched`).
+     */
+    private touchedOpacity;
+    /** A transform as native is to paint it, and whether it is a share of the view's box. */
+    private transformPainted;
+    /**
+     * Paint again each view painted with a move by a share of its box, after a commit that can
+     * have resized it: the points it was painted with are a share of the box it had.
+     */
+    private repaintShares;
+    /**
+     * Ease a transition on the graph native paints the view by, from where native has it: a
+     * transition aimed somewhere else every 50ms is a value eased on native each time, with no
+     * commit to start it. One native cannot ease this way is eased from JavaScript, and each of
+     * its frames is painted.
+     */
+    private easePainted;
+    /**
+     * Where a transition on a view native paints starts and ends, as native eases them: null
+     * where either is not numbers, which is eased from JavaScript and each frame painted.
+     */
+    private easedEnds;
+    /** Whether a graph of native's has set a prop on the view the node is committed as. */
+    private owns;
+    /**
+     * Let the painter go, for a graph of an animation to move the view: one graph moves a view,
+     * and what the painter eased goes on from JavaScript.
+     */
+    private leavePainting;
+    /** A payload with what native painted before the painter let the view go: see `leavePainting`. */
+    private synced;
+    /** Take back from native every clock it eases on a view but those of `keys`. */
+    private backToScriptAll;
+    /** Native no longer paints a view, which has left the tree. */
+    private stopPainting;
+    /** Bring every view native paints up to date in the shadow tree, once they are left alone. */
+    private quietLater;
+    /**
+     * Commit what native painted ahead of the shadow tree, on every view it paints: where a view
+     * is drawn takes in the transform of each view its native view is in, which is not always
+     * one of its parents here (a hoisted or fixed box is committed elsewhere).
+     */
+    private commitPainted;
     /** A graph of native's was connected to a view: see `Touched`. */
     private touchedNatively;
     /**
@@ -2756,10 +2996,10 @@ export declare class Engine implements HostEngine {
     /** Let go of what native is easing on an element that is going, or gone. */
     private stopEased;
     /**
-     * Whether an animation that has finished goes on holding its last frame. With a forwards fill
-     * it does, for good: without one the element falls back to whatever the cascade gives it, and
-     * 'backwards' fills the start only. Heard, it holds until whoever listens has been told: see
-     * `lettingGo`.
+     * Whether an animation that has finished goes on holding its last frame. With a forwards fill,
+     * or held there by script, it does, for good: without one the element falls back to whatever
+     * the cascade gives it, and 'backwards' fills the start only. Heard, it holds until whoever
+     * listens has been told: see `lettingGo`.
      */
     private keeps;
     /** Whether a node, or an element it is in, is `display: none`. */
@@ -2794,6 +3034,8 @@ export declare class Engine implements HostEngine {
      * undefined key, and Fabric keeps what a clone leaves out.
      */
     private processed;
+    /** Copy a list of colours, each through the host's converter, one it cannot read transparent. */
+    private processColorList;
     /** Copy a list of shadow-like objects, running each `color` through the host's converter. */
     private processNestedColors;
     /**
@@ -3077,6 +3319,13 @@ export declare class Engine implements HostEngine {
      * dropped as a browser drops it. Said once per element name and declaration, in development.
      */
     reportDroppedDeclaration(prop: string, value: string, on: string, why: string): void;
+    private readonly platformColours;
+    /**
+     * Said once per token and props: a colour worked out of a token that holds a platform colour,
+     * which has no channels to work with, is dropped. The compiler says so where one sheet holds
+     * both; a token set in one sheet, or bound, and read in another is only known here.
+     */
+    private reportPlatformColour;
     private readonly unreadDisplays;
     /**
      * Said once per token and value: the compiler refuses `display: grid` written out, but a token
@@ -3216,10 +3465,18 @@ export declare class Engine implements HostEngine {
      * costs the depth of one node, on a touch, and only while something is focused.
      */
     get focused(): EngineNode | null;
+    get focusedField(): EngineNode | null;
+    blurFocused(): void;
     /** Whether a node is still part of the tree, rather than in a subtree that was removed. */
     private isAttached;
     /** The host's `resolveAssetSource`, for a component that needs an asset's size up front. */
     resolveAsset(value: unknown): unknown;
+    /**
+     * A drawing's fill that is no colour the host reads, `contrast` as Highcharts writes one for a
+     * label, as the text's colour: native's own black is lost on a dark shape, and the text's is
+     * seen. A stroke native cannot read is left to be dropped, as a browser drops it.
+     */
+    private fillUnread;
     /** A colour prop as `processed` sends it: one dropped as unreadable is null on an update. */
     private colourProp;
     /**
@@ -3243,12 +3500,24 @@ export declare class Engine implements HostEngine {
     color(value: unknown): unknown;
     /** Root-first, so a capture pass reads forwards and a bubble pass reads backwards. */
     private pathTo;
+    /**
+     * Who asks for the touch: the nodes from the root down to `from`, which is the target, or for a
+     * move while a node holds the touch, the lowest node above both it and the target, as React's
+     * responder plugin walks. A node inside the responder never takes the touch back from it.
+     */
     private negotiate;
     private grant;
     private release;
     private tellNative;
     /** Runs before listener propagation, as React's responder plugin does. */
     private runResponder;
+    /**
+     * Asked on every move, not only while nobody holds the touch: a scroll view or a list row's
+     * swipe actions takes a drag from a pressable inside it this way. The responder answering for
+     * itself keeps the touch, as in React. The move then goes to whoever holds the touch after the
+     * asking, the new responder included.
+     */
+    private moveResponder;
     private registerEventHandler;
     /**
      * Fabric's `(instanceHandle, topLevelType, nativeEvent)` callback.
@@ -3324,7 +3593,10 @@ export declare class Engine implements HostEngine {
      * Stop every scroll view a node is in from scrolling, until the touch ends: one held off hands
      * the drag to the one around it. Telling native who holds the touch does this on Android. On
      * iOS a scroll view is held off only by a responder that is over it, never one inside it, so
-     * each is told not to scroll.
+     * each is told not to scroll. The scroll views are the ones native has the node's view in,
+     * which is where the finger is: an element moved with a finger on it stays there until the
+     * finger lifts (see `holdMove`), and CDK's drag and drop moves the item it drags to the body in
+     * the move whose default it prevents.
      */
     private holdScroll;
     /** Settle which way a drag set off, and hold native's own off one that set off across. */