drawnui-react 0.1.0-preview.2 → 0.1.0-preview.21

package/dist/core/Animators.js

@@ -16,7 +16,20 @@ export class AnimatorBase {
     StartFrameTimeNanos = 0;
     OnStart;
     OnStop;
+    /** Paused: the canvas does not tick it and it wakes no frames; Resume goes on from where it was (C# Pause / Resume). */
+    IsPaused = false;
+    /** Paused by the canvas because its control is hidden; resumed when it shows again. */
+    PausedWhileHidden = false;
+    /**
+     * Frame time (ns) before which nothing it shows changes: the canvas does not tick it and it keeps no frames coming
+     * until then, a timer wakes the frame loop at that time (a GIF or a sprite between two frames; DrawnUi.Rust frame
+     * animators sleep between changes). 0 = tick every frame.
+     */
+    SleepUntilNanos = 0;
     delayHandle = 0;
+    delayEnd = 0;
+    delayLeft = 0;
+    pausedAt = 0;
     constructor(parent) { this.Parent = parent; }
     Register() {
         const parent = this.Parent;
@@ -29,7 +42,14 @@ export class AnimatorBase {
             if (!parent.PostAnimators.includes(effect))
                 parent.PostAnimators.push(effect);
         }
-        const ok = parent.Superview?.RegisterAnimator(this) ?? false;
+        const superview = parent.Superview;
+        const ok = superview?.RegisterAnimator(this) ?? false;
+        // C# SkiaControl.RegisterAnimator: not attached yet, queue it; the parent starts it on its first arrange
+        if (!superview && !parent.IsDisposed) {
+            const pending = parent.PendingUnattachedAnimators ??= [];
+            if (!pending.includes(this))
+                pending.push(this);
+        }
         parent.Repaint();
         return ok;
     }
@@ -42,6 +62,9 @@ export class AnimatorBase {
             if (i >= 0)
                 parent.PostAnimators.splice(i, 1);
         }
+        const pending = parent.PendingUnattachedAnimators?.indexOf(this) ?? -1;
+        if (pending >= 0)
+            parent.PendingUnattachedAnimators.splice(pending, 1);
         parent.Superview?.UnregisterAnimator(this.Uid);
     }
     Start(delayMs = 0) {
@@ -50,6 +73,8 @@ export class AnimatorBase {
             this.delayHandle = 0;
         }
         if (delayMs > 0) {
+            // the delay waits without frames
+            this.delayEnd = performance.now() + delayMs;
             this.delayHandle = window.setTimeout(() => { this.delayHandle = 0; this.Start(); }, delayMs);
             return;
         }
@@ -62,7 +87,43 @@ export class AnimatorBase {
             }
         }
     }
+    /** Freezes the run (and what is left of a start delay); Resume goes on from there. */
+    Pause() {
+        if (this.IsPaused)
+            return;
+        this.IsPaused = true;
+        this.pausedAt = performance.now();
+        if (this.delayHandle) {
+            clearTimeout(this.delayHandle);
+            this.delayHandle = 0;
+            this.delayLeft = Math.max(0, this.delayEnd - this.pausedAt);
+        }
+    }
+    /** Goes on from where Pause froze it: the paused time is not counted. */
+    Resume() {
+        if (!this.IsPaused)
+            return;
+        this.IsPaused = false;
+        const paused = (performance.now() - this.pausedAt) * 1_000_000;
+        if (this.StartFrameTimeNanos !== 0) {
+            this.StartFrameTimeNanos += paused;
+            this.LastFrameTimeNanos += paused;
+        }
+        if (this.SleepUntilNanos !== 0)
+            this.SleepUntilNanos += paused;
+        if (this.delayLeft > 0) {
+            const left = this.delayLeft;
+            this.delayLeft = 0;
+            this.Start(left);
+            return;
+        }
+        this.Parent?.Repaint(); // frames again
+    }
     Stop() {
+        this.IsPaused = false;
+        this.PausedWhileHidden = false;
+        this.SleepUntilNanos = 0;
+        this.delayLeft = 0;
         if (this.delayHandle) {
             clearTimeout(this.delayHandle);
             this.delayHandle = 0;
@@ -96,6 +157,21 @@ export class AnimatorBase {
             this.OnStop?.();
     }
 }
+/**
+ * DrawnUi ActionOnTickAnimator: runs `action(frameTimeNanos)` on every frame until stopped, a game loop for
+ * DrawnGame or any per-frame work.
+ */
+export class ActionOnTickAnimator extends AnimatorBase {
+    action;
+    constructor(parent, action) {
+        super(parent);
+        this.action = action;
+    }
+    TickFrame(frameTimeNanos) {
+        this.action(frameTimeNanos);
+        return super.TickFrame(frameTimeNanos);
+    }
+}
 /** DrawnUi SkiaValueAnimator: drives mValue from mMinValue to mMaxValue over Speed ms with Easing. */
 export class SkiaValueAnimator extends AnimatorBase {
     mValue = 0;
@@ -130,23 +206,21 @@ export class SkiaValueAnimator extends AnimatorBase {
     }
     /** Passed over mValue; subclasses derive their own reported value here. */
     TransformReportedValue(_deltaT) { return this.mValue; }
-    /** Updates mValue from elapsed time; true when the target was reached. */
+    /**
+     * Updates mValue from elapsed time; true when the run is over. The eased value is not clamped to the range: a spring
+     * easing goes past its ends, and a run whose mMinValue is above mMaxValue (a ping-pong's way back) goes down.
+     */
     UpdateValue(_deltaT, deltaFromStart) {
         const elapsedMs = deltaFromStart / 1_000_000;
         const progress = this.Speed > 0 ? elapsedMs / this.Speed : 1;
         const deltaValue = this.mMaxValue - this.mMinValue;
         const eased = this.Easing.Ease(Math.min(progress, 1));
         this.Progress = eased;
-        const value = deltaValue * eased + this.mMinValue;
-        if (value < this.mMinValue) {
-            this.mValue = this.mMinValue;
-            return false;
-        }
-        if (value >= this.mMaxValue || progress >= 1) {
+        if (progress >= 1) {
             this.mValue = this.mMaxValue;
             return true;
         }
-        this.mValue = value;
+        this.mValue = deltaValue * eased + this.mMinValue;
         return false;
     }
     FinishedRunning() {
@@ -163,6 +237,25 @@ export class SkiaValueAnimator extends AnimatorBase {
         return true;
     }
 }
+/** DrawnUi PingPongAnimator: every repeat runs the other way (Repeat -1 = forever by default). */
+export class PingPongAnimator extends SkiaValueAnimator {
+    /** One way done, the next starts (C# CycleFInished). */
+    CycleFinished;
+    constructor(parent) { super(parent); this.Repeat = -1; }
+    FinishedRunning() {
+        if (this.Repeat !== 0) {
+            this.CycleFinished?.();
+            if (this.Repeat > 0)
+                this.Repeat--;
+            [this.mMinValue, this.mMaxValue] = [this.mMaxValue, this.mMinValue];
+            this.mValue = this.mMinValue;
+            this.LastFrameTimeNanos = 0;
+            this.StartFrameTimeNanos = 0;
+            return false;
+        }
+        return super.FinishedRunning();
+    }
+}
 /** DrawnUi RenderingAnimator: a value animator that paints itself above its Parent (IOverlayEffect). */
 export class RenderingAnimator extends SkiaValueAnimator {
     constructor(parent) { super(parent); }

package/dist/core/Canvas.d.ts

@@ -1,7 +1,8 @@
 import type { Surface } from "canvaskit-wasm";
-import type { SkiaControl } from "./SkiaControl";
+import type { DrawingContext, SkiaControl } from "./SkiaControl";
 import type { AnimatorBase } from "./Animators";
 import { SkiaAccessibilityManager } from "./Accessibility";
+import { HoverManager } from "./Hover";
 import { type Color, type RenderingModeType } from "./Types";
 import { ContextMenuEventArgs, type GesturesMode, SkiaGesturesParameters, TouchActionEventArgs } from "./Gestures";
 /**
@@ -14,6 +15,11 @@ export declare class Canvas {
     readonly Element: HTMLCanvasElement;
     /** Points a pointer may travel between Down and Up and still count as a tap (AppoMobi TouchEffect default). */
     static TappedCancelMoveThresholdPoints: number;
+    /**
+     * A press held this long without moving past TappedCancelMoveThresholdPoints is a LongPressing, at the press point
+     * (AppoMobi TouchEffect, DrawnUi.Rust LONG_PRESS_MS); its release sends no Tapped. A timer, no frames while waiting.
+     */
+    static LongPressTimeMs: number;
     BackgroundColor: Color;
     /** Accelerated = WebGL surface, Default = software. Read once at first frame. */
     RenderingMode: RenderingModeType;
@@ -23,8 +29,22 @@ export declare class Canvas {
     /** Frames per second over the last second of drawn frames. */
     FPS: number;
     private frameTimes;
+    /** DrawnView.WasRendered: a frame has been drawn on a ready surface (set after the first one completes). */
+    WasRendered: boolean;
+    /** DrawnView.CanRender: the surface (and its GPU context when accelerated) is ready to draw. */
+    get CanRender(): boolean;
+    /**
+     * DrawnView.WillFirstTimeDraw: raised once, right before the first frame drawn on a ready surface, with that
+     * frame's drawing context. The engine draws its first frame while it is being constructed (so the page never shows
+     * an unpainted canvas): pass it through the constructor's `init` to receive that frame.
+     */
+    WillFirstTimeDraw?: (sender: Canvas, context: DrawingContext["Context"]) => void;
+    /** DrawnView.WasDrawn: raised after every frame has been drawn (the C# event passes no context). */
+    WasDrawn?: (sender: Canvas) => void;
     /** Registry + rate-limited snapshot of accessible controls, rendered by the DOM overlay (DrawnUi AccessibilityManager). */
     readonly AccessibilityManager: SkiaAccessibilityManager;
+    /** Mouse hover of the controls (drawnui-cross 6m): ReceivesHover / IsHovered / HoverChanged. */
+    readonly Hover: HoverManager;
     private content?;
     get Content(): SkiaControl | undefined;
     set Content(value: SkiaControl | undefined);
@@ -35,7 +55,15 @@ export declare class Canvas {
     private frameId;
     private disposed;
     private readonly observer;
-    constructor(Element: HTMLCanvasElement);
+    /** The WebGL context is lost: no frames until the browser restores it. */
+    private contextLost;
+    /**
+     * Bumped when the WebGL context was restored: every GPU object made before (Image caches, picture caches that may
+     * replay them, kept composite surfaces, effect textures) is remade at its next draw (DrawnUi.Rust Gpu::epoch).
+     */
+    GpuEpoch: number;
+    /** `init` runs before the first frame is drawn: the place to attach `WillFirstTimeDraw` / `WasDrawn` for that frame. */
+    constructor(Element: HTMLCanvasElement, init?: (canvas: Canvas) => void);
     /** Request a redraw (full measure + arrange + render) on the next animation frame. */
     Update(): void;
     /** Deletes the current surface; a pending frame on it is cancelled first (drawing on a deleted surface faults). */
@@ -48,6 +76,17 @@ export declare class Canvas {
      * redrawn content lands in the same paint and no blank frame is ever shown while dragging.
      */
     private OnResized;
+    /** WebGL context lost: keep the browser restoring it (preventDefault) and stop the frames. */
+    private readonly onContextLost;
+    /**
+     * WebGL context restored (as DrawnUi.Rust and the C# Wasm / Blazor heads): every GL object of the lost generation is
+     * gone. The old Skia context is abandoned first, while its own GL handle is current and before the new context makes
+     * any object, so its GL calls reach only lost-generation objects. CanvasKit exposes no `abandonContext`;
+     * `releaseResourcesAndAbandonContext` is its only way to abandon, and after it freeing an old image or surface makes no
+     * GL call. Then the same WebGL object is registered again (the old handle deleted first, which clears the canvas'
+     * context object) with a new GrContext and surface; GpuEpoch makes the old generation's GPU objects remake themselves.
+     */
+    private readonly onContextRestored;
     /** Draws one frame immediately (outside the rAF loop) and presents it. */
     private DrawNow;
     private Draw;
@@ -62,8 +101,20 @@ export declare class Canvas {
     UnregisterAnimator(uid: number): void;
     /** Ticks every registered animator once; returns how many ran. */
     protected ExecuteAnimators(frameTimeNanos: number): number;
+    private wakeTimer;
+    private wakeAtNanos;
+    /** One timer for the earliest sleeping animator: the frame loop wakes then, no frames run in between. */
+    private WakeAt;
     /** Frames drawn so far (SkiaBackdrop uses it to refresh once after a cached record). */
     FrameIndex: number;
+    /**
+     * DrawnView.WheelDeltaPerNotch: the Wheel.Delta one mouse-wheel notch produces, 100 CSS pixels in Chrome and Edge. A
+     * scroll moves by the event's share of a notch, so a touchpad, which sends many small events, scrolls as far as the
+     * fingers moved. 0 = units unknown: every event scrolls one line.
+     */
+    WheelDeltaPerNotch: number;
+    /** Vsync time of the last frame the animators ran on (nanoseconds, the performance.now() timeline). */
+    FrameTimeNanos: number;
     /** On-screen surface (SkiaBackdrop snapshots it). */
     get Surface(): Surface | undefined;
     /**
@@ -87,7 +138,13 @@ export declare class Canvas {
     private readonly previousTouchArgs;
     private readonly pendingGestures;
     private readonly onPointer;
+    /** The mouse left the canvas: hover ends at once, also while content moves. */
+    private readonly onPointerLeave;
     private readonly preventTouch;
+    /** Gestures="Enabled": touch / pen pointers whose Down a control used (see OnTouchAction). */
+    private readonly claimedTouches;
+    /** Gestures="Enabled": while a claimed touch is down the page may not take its drag. */
+    private readonly preventClaimedTouch;
     /** Called when no control handled a context-menu request; return true to suppress the browser's canvas menu. */
     ContextMenu?: (sender: Canvas, e: ContextMenuEventArgs) => boolean | void;
     /** DOM contextmenu (right click / long press / Menu key) -> ContextMenuEventArgs routed through the tree like a tap. */
@@ -95,20 +152,64 @@ export declare class Canvas {
     private cursorPointer;
     /**
      * DrawnUi.Blazor shows `cursor: pointer` over interactive controls through its overlay elements; here the overlay
-     * is pointer-events:none, so the mouse position is tested against the accessibility snapshot (the accessible
-     * controls' rects in points, already sorted and rate-limited), each hit control answering WantsPointerCursor
-     * (itself tappable, or a tappable span of a label), and the canvas element's cursor is switched only when the
-     * answer changes. Mouse moves only, no work without a mouse and none in the frame loop.
+     * is pointer-events:none, so the canvas decides from the hover hit path (Hover.Path: the controls under the mouse by
+     * the routing rules of ProcessGestures, so nothing below a popup that blocks gestures below): a control in the
+     * accessibility tree (it has a role) that answers WantsPointerCursor (itself tappable, or a tappable span of a label)
+     * shows the hand. A popup's close-on-background-tap wrapper has no role, so its backdrop shows none. The canvas
+     * element's cursor is switched only when the answer changes. Mouse moves only, none in the frame loop.
      */
     private UpdateCursor;
-    /** Mouse wheel -> TouchActionResult.Wheel (page scroll suppressed while gestures are enabled). */
+    /**
+     * Mouse wheel -> TouchActionResult.Wheel.
+     * Lock keeps every wheel on the canvas. Enabled shares it with the page, like DrawnUi.Blazor's
+     * TouchHandlingStyle.Manual: the page scrolls unless a control consumed this wheel. The browser needs that answer
+     * inside this handler, so the wheel is processed now instead of at the next frame (Blazor does the same, for the
+     * same reason); pending gestures are flushed first so the event order is kept.
+     */
     private readonly onWheel;
+    /**
+     * Processes one gesture immediately (after whatever is queued) and reports whether a control USED it: a consumer
+     * that marked the event Handled, or any consumer that is not a `BlockGesturesBelow` layer. A blocker returns itself
+     * for every gesture it keeps from the controls below (a shell page, a popup backdrop), which is not a use: counting
+     * it would block the page wheel over every shell app.
+     */
+    private ProcessGestureNow;
+    /**
+     * The page axes a touch pan over the canvas hands to the browser: "pan-y" when the page (or a scrolling ancestor) can
+     * scroll vertically, "pan-x" horizontally, both, or "none". Mirrors MAUI's Gestures="Enabled" inside a native scroll
+     * view, where the parent takes the pans it scrolls in.
+     */
+    private static PageScrollAxes;
+    /**
+     * Gestures="Enabled" shares touch pans with the page like MAUI's Enabled inside a native scroll view: along an axis
+     * the page can scroll, the browser takes the pan (and sends pointercancel), taps and the other axis stay on the
+     * canvas. A page that cannot scroll, and Lock, keep every touch. The browser reads touch-action when a touch starts,
+     * so it is kept current ahead of time: on attach, when the window / html / body resize, and after every touch.
+     */
+    private readonly UpdateTouchAction;
+    private pageObserver?;
     private AttachInput;
+    /** The page's own overscroll-behavior before Lock set it to none (html, body), put back on detach. */
+    private pageOverscroll?;
     private DetachInput;
     /** Port of DrawnUi.Blazor Canvas.OnTouchAction: per-pointer state machine producing Down / Panning / Tapped / Up. */
     OnTouchAction(args: TouchActionEventArgs): void;
+    private readonly longPressTimers;
+    private readonly longPressed;
+    /** The long press of a new press: due LongPressTimeMs later unless the pointer moves away or lets go. */
+    private ArmLongPress;
+    private DisarmLongPress;
     private OnGestureEvent;
     private ProcessPendingGestures;
+    /**
+     * The control that consumed the current gesture keeps it until it lets go (DrawnUi Canvas.HadInput). Without this a
+     * gesture is re-routed by the pointer position on every event, so anything the finger drags away from — a drag
+     * handle, a slider thumb, a button being held — stops receiving Panning the moment the pointer leaves its box.
+     * Single pointer, which is what the web gives us here; C# keeps a set for multi-touch.
+     */
+    private gestureOwner;
+    /** DrawnUi IsSavedGesture: the types replayed to the owner instead of being routed again. */
+    private static IsSavedGesture;
     /** Entry into the control tree, same shape as DrawnUi Canvas.ProcessGestures. */
     protected ProcessGestures(root: SkiaControl, args: SkiaGesturesParameters): SkiaControl | null;
 }