drawnui-react 0.1.0-preview.10 → 0.1.0-preview.11

package/README.md

@@ -6,6 +6,8 @@ through a custom `react-reconciler` renderer.
 
 Check out latest playbook: [helloreact.drawnui.net](https://helloreact.drawnui.net/) 👈
 
+Playground to use and test live: [drawfiddle.com](https://drawfiddle.com/) 👈
+
 *Work in progress*: the goal is same API surface and semantics as DrawnUi (.NET) — same control names, same PascalCase
 property names, same measure/arrange/paint contract — so knowledge and docs transfer 1:1.
 
@@ -65,6 +67,15 @@ accessibility all live in the engine and would work identically under Vue, Svelt
 That is also why the demo pages describe DrawnUi features, not React ones: the same pages are meant to be reused as
 the showcase for other frameworks on this engine.
 
+## Games
+
+`DrawnGame` (from DrawnUi.Gaming) is ported: a layout with a game loop. Subclass it, build your sprites in the
+constructor, call `StartLoop()`, and override `GameLoop(deltaSeconds)` and `OnKeyDown` / `OnKeyUp` (DOM `event.code`
+names). Move sprites with `Left` / `Top` on cached controls, as in C#. The demo's `#/pong` page is the .NET Pong
+sample (`src/Shared/Samples/Pong.Shared`) ported line for line: the game classes are plain TypeScript in
+`samples/demo/pages/pong`, mounted from `PongPage.tsx` with `AddSubView`, and a small `RescalingLayout` fits the
+360×640 field to any screen by changing the children's rendering scale.
+
 ## Context menu (right click)
 
 A right click on the canvas normally opens the browser's own menu ("Save image as…"). Every mouse button goes

package/SKIPPED.md

@@ -31,7 +31,9 @@ DrawnUi name and semantics; nothing here is a redesign, only an omission.
 | `FillGradient`, `SkiaShape.StrokeGradient` | ported | `SkiaGradient` as a plain object: `Type` Linear (Start/End ratios or CSS `Angle`), Circular / Conical (radius = half the smaller side), Oval (radial scaled to the box), Sweep (around the center, `Value1`/`Value2` angles), `ColorPositions`, `TileMode`, `Light` (< 1 darker, > 1 lighter — HSL lightness, C# uses `MakeDarker/MakeLighter`, exact curve unverified), `Opacity`, `BlendMode`; C# `SetupGradient` paint setup (white base); shaders cached per gradient object and rect (C# `Version` cache: a new React literal replaces the old shaders). `SkiaLabel.FillGradient` paints the glyphs (`GradientByLines` default true = per line bounds, false = the text block) and the background only when `BackgroundColor` is set, like the C# label override. `SkiaLabel` text stroke (`StrokeColor`, `StrokeWidth` points, `StrokeGradient`) and drop shadow (`DropShadowColor`, `DropShadowSize`, `DropShadowOffsetX/Y`) in the C# order shadow → stroke → fill, measurement inflated by stroke × 2 and shadow size + offset like C#. Not ported: `Background` MAUI brushes, `FillBlendMode`. |
 | `SkiaShell` | partial (React-level) | `Routes` (route -> JSX page factory), `GoToAsync(route, animated)` / `GoBackAsync(animated)` / `PopToRootAsync` with the SkiaViewSwitcher slide (`PagesAnimationSpeed` 200 ms, pushed pages opaque over the page below, lower pages hidden when idle), `NavigationStack`, `CanGoBack`, `Route`, nav bar with Back + title, `useShell()`; `OpenPopupAsync(content, { animated, closeWhenBackgroundTapped, showOverlay, backgroundColor })` (C# PopupWrapper: dimmed backdrop, scale 0.5→1 + fade over `PopupsAnimationSpeed`, tap outside the content closes), `ClosePopupAsync`, `CloseAllPopups`; `PushModalAsync(content, { useGestures, animated, freezeBackground })` (C# ModalWrapper: full-screen `SkiaDrawer` FromBottom HeaderSize 0, drag-to-close with `useGestures`), `PopModalAsync`; `ShowToast(text | content, ms)` (C# layout: bottom banner, slide + fade 300/250 ms, `ShellDefaults.Toast*`), `CloseAllToasts`; `PopupsCount`/`ModalsCount`/`ToastsCount`; `ShellDefaults` = the C# statics (`PopupBackgroundColor`, `PopupsBackgroundBlur`, `PopupsAnimationSpeed`, `PopupsCancelAnimationsAfterMs`, `ZIndex*`, `Toast*`, tab colors); popups/modals sit on a `SkiaBackdrop` (blur + tint); `Tabs` (C# SkiaViewSwitcher tabs: bottom tab bar, per-tab page stacks, `SelectedTab`, `SelectTabAsync`, `PopTabToRootAsync`); `GoBackAsync` follows C# `GoBackDefault` (top popup, then modal, then page); React extension `UseBrowserHistory` (default true): pages in the URL hash `#/a/b`, one history entry per page / popup / modal, browser Back unwinds in the same order, deep links restore the page stack. Not ported: engine-level shell / `NavigationLayout` view switcher, frozen-screenshot backgrounds, `pixelsScaleInFrom`, `Navigating`/`Navigated`/`RouteChanged` events, `RegisterRoute` by type with arguments, `IHandleGoBack`, insets, `PushAsync(page instance)`; `AnimateTabs` + `TabsAnimationSpeed` (150) ported with the C# SelectLeftTab/SelectRightTab slide (0.75 width, fade, back-ease 0.55) — only the tab roots animate, pages pushed inside the leaving tab drop instantly. Browser history: a `popstate` at the same depth with another hash (a plain `<a href="#/route">` link, a typed hash) rebuilds the stack like a forward navigation. |
 | Styles / `ConfigureStyles` | ported | `Super.UseDrawnUi().ConfigureStyles(styles => styles.AddStyle({ TargetType, ApplyToDerivedTypes, Setters }))`, the C# `Style` shape with the `Setter` list written as a plain object (`Setters: { FontFamily: "FontText" }`) because controls hold plain properties instead of BindableProperty. Per-class resolution cached, base-type styles applied furthest-first so the nearest wins, exact type last (C# `ResolveStylesForType`). Applied by the reconciler between `new` and the JSX props, so props override; a control built in code-behind is styled on its first `Measure` and keeps values that differ from its class defaults (the React stand-in for C# `ExplicitPropertiesSet`, which needs BindableProperty). Not ported: `BasedOn`, `Class`, `Triggers`, `Behaviors`, the per-control `Style` property, `ConditionalStyle`. |
-| Animators core: `AnimatorBase` / `SkiaValueAnimator` / `RenderingAnimator` (`IOverlayEffect`), `Canvas.RegisterAnimator`/`AnimatingControls`, `PostAnimators` + `ExecutePostAnimators`, `Easing` (Linear/Cubic*) | ported | Frame-driven: a running animator keeps frames coming, idle canvas draws nothing. |
+| Animators core: `AnimatorBase` / `SkiaValueAnimator` / `RenderingAnimator` (`IOverlayEffect`), `Canvas.RegisterAnimator`/`AnimatingControls`, `PostAnimators` + `ExecutePostAnimators`, `Easing` (Linear/Cubic*) | ported | Frame-driven: a running animator keeps frames coming, idle canvas draws nothing. An animator started before its control is attached waits in `PendingUnattachedAnimators` and starts on the control's first arrange (C# starts it in `SuperViewChanged`). Frame time = the frame's vsync timestamp, see PARITY "Animators run on vsync time". |
+| `ActionOnTickAnimator` | ported | Runs an action with the frame time on every frame until stopped. |
+| `DrawnGame` (DrawnUi.Gaming) | ported | `SkiaLayout` subclass: `StartLoop(delayMs)` / `StopLoop`, override `GameLoop(deltaSeconds)`, `OnKeyDown` / `OnKeyUp` (DOM `event.code` names, subscribed through `KeyboardManager` for the game's lifetime), `Pause` / `Resume` / `IsPaused` / `OnPaused` / `OnResumed`, `LastFrameTimeNanos`. Not ported: `FrameTimeInterpolator` (C# disables it on BROWSER too), `IGame`, the `IsPaused` property-changed notification. Demo: `#/pong`, the .NET Pong.Shared sample. |
 | Touch feedback: `AnimationTapped="Ripple"` + `TouchEffectColor` + `AnimationTappedSpeed` on any control, `SkiaButton.ApplyEffect="Ripple"` (on Down), `PlayRippleAnimation`, `RippleAnimator`, `ClipEffects`/`CreateClip` | ported | Same numbers as C#: 500ms CubicIn, radius 300pt, opacity 0.20 fading over 1.15x progress. |
 | `Shimmer` touch animation, `ShimmerAnimator`, `ClippedEffectsWith`, `TransformView`, `DelayCallbackMs`, `removePrevious`, `Pause`/`Resume`, `UseInterpolator`, spring/deceleration timing, `AnimateExtensions` (`FadeToAsync`, `TranslateToAsync`, ...) | skipped | |
 | `VisualEffects` + `SkiaEffect` / `IPostRendererEffect` / `ISkiaGestureProcessor` | partial | `VisualEffects` array on every control (assign a new array; effects attach / detach, dispose with the control, `DisableEffects`, `GetEffectMargin` aggregated into the effects margin); post renderers run after the direct paint (C# `DrawDirectInternal`) or instead of the Image cache blit (C# `DrawRenderObject`, the effect samples `CachedImage`); effects with `ProcessGestures` see the parent's gestures first (C# `EffectsGestureProcessors`). Not ported: `IRenderEffect` chain (`ChainEffectResult`, `Draw(ctx, drawControl)`), `IColorEffect` / `IImageEffect` on VisualEffects (`BlurEffect`, `DropShadowEffect`, `OuterGlowEffect`, `ColorPresetEffect`, `AdjustRGBEffect`, `ChainAdjust*`, `Chain*`), `IStateEffect.UpdateState`, `Tag` lookup. |

package/dist/controls/DrawnGame.d.ts

@@ -0,0 +1,37 @@
+import { type InputKey } from "../core/KeyboardManager";
+import { SkiaLayout } from "./SkiaLayout";
+/**
+ * Mirrors DrawnUi.Gaming DrawnGame (SharedGame/DrawnGame.cs + Game.Input.cs): a layout that runs a game loop.
+ * `StartLoop()` / `StopLoop()`, override `GameLoop(deltaSeconds)` for the game and `OnKeyDown` / `OnKeyUp` for keys
+ * (DOM `event.code` names, e.g. "ArrowLeft", "Space"). The loop is an `ActionOnTickAnimator`, ticked once per drawn
+ * frame; started before the game is attached it waits for the first layout, like C#.
+ * Not ported: `FrameTimeInterpolator` (C# disables it on BROWSER too, the raw frame delta is used).
+ */
+export declare class DrawnGame extends SkiaLayout {
+    private appLoop?;
+    protected LastFrameTimeNanos: number;
+    private isPaused;
+    private readonly onKeyDown;
+    private readonly onKeyChar;
+    private readonly onKeyUp;
+    constructor();
+    protected OnDisposing(): void;
+    protected OnResumed(): void;
+    protected OnPaused(): void;
+    /** Override this for your game. `deltaSeconds` is the time elapsed between the previous frame and this one. */
+    GameLoop(_deltaSeconds: number): void;
+    /** Stops the game loop. */
+    StopLoop(): void;
+    /** Starts the game loop. */
+    StartLoop(delayMs?: number): void;
+    /** Internal, override `GameLoop` for your game. Frame time is in nanoseconds. */
+    protected GameTick(frameTimeNanos: number): void;
+    get IsPaused(): boolean;
+    set IsPaused(value: boolean);
+    Pause(): void;
+    Resume(): void;
+    /** Override this to process game keys. */
+    OnKeyDown(_key: InputKey): void;
+    /** Override this to process game keys. */
+    OnKeyUp(_key: InputKey): void;
+}

package/dist/controls/DrawnGame.js

@@ -0,0 +1,60 @@
+import { ActionOnTickAnimator } from "../core/Animators";
+import { KeyboardManager } from "../core/KeyboardManager";
+import { SkiaLayout } from "./SkiaLayout";
+/**
+ * Mirrors DrawnUi.Gaming DrawnGame (SharedGame/DrawnGame.cs + Game.Input.cs): a layout that runs a game loop.
+ * `StartLoop()` / `StopLoop()`, override `GameLoop(deltaSeconds)` for the game and `OnKeyDown` / `OnKeyUp` for keys
+ * (DOM `event.code` names, e.g. "ArrowLeft", "Space"). The loop is an `ActionOnTickAnimator`, ticked once per drawn
+ * frame; started before the game is attached it waits for the first layout, like C#.
+ * Not ported: `FrameTimeInterpolator` (C# disables it on BROWSER too, the raw frame delta is used).
+ */
+export class DrawnGame extends SkiaLayout {
+    appLoop;
+    LastFrameTimeNanos = 0;
+    isPaused = false;
+    onKeyDown = (key) => this.OnKeyDown(key);
+    onKeyChar = () => { };
+    onKeyUp = (key) => this.OnKeyUp(key);
+    constructor() {
+        super();
+        KeyboardManager.Subscribe(this.onKeyDown, this.onKeyChar, this.onKeyUp);
+    }
+    OnDisposing() {
+        KeyboardManager.Unsubscribe(this.onKeyDown, this.onKeyChar, this.onKeyUp);
+        this.appLoop?.Dispose();
+        this.appLoop = undefined;
+        super.OnDisposing();
+    }
+    OnResumed() { }
+    OnPaused() { }
+    /** Override this for your game. `deltaSeconds` is the time elapsed between the previous frame and this one. */
+    GameLoop(_deltaSeconds) { }
+    /** Stops the game loop. */
+    StopLoop() { this.appLoop?.Stop(); }
+    /** Starts the game loop. */
+    StartLoop(delayMs = 0) {
+        this.appLoop ??= new ActionOnTickAnimator(this, (t) => this.GameTick(t));
+        this.appLoop.Start(delayMs);
+    }
+    /** Internal, override `GameLoop` for your game. Frame time is in nanoseconds. */
+    GameTick(frameTimeNanos) {
+        const deltaSeconds = (frameTimeNanos - this.LastFrameTimeNanos) / 1_000_000_000;
+        this.LastFrameTimeNanos = frameTimeNanos;
+        this.GameLoop(deltaSeconds);
+    }
+    get IsPaused() { return this.isPaused; }
+    set IsPaused(value) { this.isPaused = value; }
+    Pause() {
+        this.IsPaused = true;
+        this.OnPaused();
+    }
+    Resume() {
+        this.LastFrameTimeNanos = Math.round(performance.now() * 1_000_000);
+        this.IsPaused = false;
+        this.OnResumed();
+    }
+    /** Override this to process game keys. */
+    OnKeyDown(_key) { }
+    /** Override this to process game keys. */
+    OnKeyUp(_key) { }
+}

package/dist/core/Animators.d.ts

@@ -29,6 +29,15 @@ export declare class AnimatorBase {
     Dispose(): void;
     private SetRunning;
 }
+/**
+ * DrawnUi ActionOnTickAnimator: runs `action(frameTimeNanos)` on every frame until stopped, a game loop for
+ * DrawnGame or any per-frame work.
+ */
+export declare class ActionOnTickAnimator extends AnimatorBase {
+    private readonly action;
+    constructor(parent: SkiaControl, action: (frameTimeNanos: number) => void);
+    TickFrame(frameTimeNanos: number): boolean;
+}
 /** DrawnUi SkiaValueAnimator: drives mValue from mMinValue to mMaxValue over Speed ms with Easing. */
 export declare class SkiaValueAnimator extends AnimatorBase {
     mValue: number;

package/dist/core/Animators.js

@@ -29,7 +29,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 +49,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) {
@@ -96,6 +106,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;

package/dist/core/Canvas.js

@@ -135,7 +135,12 @@ export class Canvas {
     Draw(canvas) {
         const started = performance.now();
         this.ProcessPendingGestures();
-        const executed = this.ExecuteAnimators(Math.round(started * 1_000_000));
+        // Animators run on the frame's vsync time (inside a rAF callback document.timeline.currentTime is the frame
+        // timestamp), not on when this callback happened to start: callback starts drift by several ms around vsync
+        // (measured 12..23 ms between frames shown 16.7 ms apart), and a game loop moving by speed * delta then
+        // jumps unevenly on screen.
+        const frameTime = Number(document.timeline?.currentTime ?? started);
+        const executed = this.ExecuteAnimators(Math.round(frameTime * 1_000_000));
         const canRender = this.CanRender;
         if (canRender && !this.WasRendered)
             this.WillFirstTimeDraw?.(this, { Canvas: canvas, Surface: this.surface });

package/dist/core/SkiaControl.d.ts

@@ -1,6 +1,6 @@
 import type { Canvas as SkCanvas, Image, Path, SkPicture, Surface } from "canvaskit-wasm";
 import { type Color, type LayoutOptions, SKRect, ScaledSize, type SkiaCacheType, type SkiaGradient, type SkiaTouchAnimation, Thickness } from "./Types";
-import { type IOverlayEffect } from "./Animators";
+import { type AnimatorBase, type IOverlayEffect } from "./Animators";
 import { Easing } from "./Easing";
 import type { Canvas } from "./Canvas";
 import { ContextMenuEventArgs, ControlTappedEventArgs, GestureEventProcessingInfo, type LockTouch, SKPoint, SkiaGesturesInfo, SkiaGesturesParameters } from "./Gestures";
@@ -164,6 +164,11 @@ export declare class SkiaControl {
     AnimationTappedSpeed: number;
     /** Overlay effects drawn above this control's content every frame (ripple etc). */
     readonly PostAnimators: IOverlayEffect[];
+    /**
+     * C# PendingUnattachedAnimators: animators started while no Canvas was above this control yet (e.g. a game loop
+     * started in a constructor). They start on the control's first arrange, where C# starts them in SuperViewChanged.
+     */
+    PendingUnattachedAnimators?: AnimatorBase[];
     private visualEffects;
     /** Post-renderer effects among VisualEffects (C# EffectPostRenderers). */
     EffectPostRenderers: (SkiaEffect & IPostRendererEffect)[];
@@ -220,6 +225,8 @@ export declare class SkiaControl {
     protected MeasureAbsolute(_widthConstraint: number, _heightConstraint: number, scale: number): ScaledSize;
     /** Places MeasuredSize inside destination per Margin + Horizontal/VerticalOptions -> DrawingRect. */
     Arrange(destination: SKRect, _widthRequest: number, _heightRequest: number, scale: number): void;
+    /** C# SuperViewChanged: starts the animators queued before this control was attached. */
+    private StartPendingAnimators;
     private static nextAccessibilityId;
     /** Stable identity for the DOM overlay. */
     readonly AccessibilityId: number;

package/dist/core/SkiaControl.js

@@ -199,6 +199,11 @@ export class SkiaControl {
     AnimationTappedSpeed = 0;
     /** Overlay effects drawn above this control's content every frame (ripple etc). */
     PostAnimators = [];
+    /**
+     * C# PendingUnattachedAnimators: animators started while no Canvas was above this control yet (e.g. a game loop
+     * started in a constructor). They start on the control's first arrange, where C# starts them in SuperViewChanged.
+     */
+    PendingUnattachedAnimators;
     // ---- visual effects (C# VisualEffects: attached SkiaEffect objects) ----
     visualEffects = [];
     /** Post-renderer effects among VisualEffects (C# EffectPostRenderers). */
@@ -363,10 +368,21 @@ export class SkiaControl {
         const y = availT + SkiaControl.Align(this.VerticalOptions, fullH, h);
         this.DrawingRect = SKRect.Create(x, y, w, h);
         this.OnLayoutChanged();
+        if (this.PendingUnattachedAnimators)
+            this.StartPendingAnimators();
         // DrawnUi OnLayoutReady: an accessible control registers itself on its first layout
         if (!this.registeredWithAccessibility && this.IsAccessibilityElement)
             this.NotifyAccessibility();
     }
+    /** C# SuperViewChanged: starts the animators queued before this control was attached. */
+    StartPendingAnimators() {
+        if (!this.Superview)
+            return;
+        const pending = this.PendingUnattachedAnimators;
+        this.PendingUnattachedAnimators = undefined;
+        for (const animator of pending)
+            animator.Start();
+    }
     // ---- accessibility (DrawnUi ISkiaAccessibilityNode) ----
     static nextAccessibilityId = 1;
     /** Stable identity for the DOM overlay. */
@@ -1038,6 +1054,7 @@ export class SkiaControl {
         this.ownAnimations.clear();
         for (const e of [...this.PostAnimators])
             e.Stop?.();
+        this.PendingUnattachedAnimators = undefined;
         this.PostAnimators.length = 0;
         this.DestroyRenderingObject();
         this.compositeSurface?.delete();

package/dist/index.d.ts

@@ -40,6 +40,7 @@ export * from "./controls/SkiaBackdrop";
 export * from "./controls/SkiaEditor";
 export * from "./controls/SkiaSprite";
 export * from "./controls/SkiaSpriteSet";
+export * from "./controls/DrawnGame";
 export * from "./core/KeyboardManager";
 export * from "./controls/AnimatedFramesRenderer";
 export * from "./controls/SkiaLottie";

package/dist/index.js

@@ -40,6 +40,7 @@ export * from "./controls/SkiaBackdrop";
 export * from "./controls/SkiaEditor";
 export * from "./controls/SkiaSprite";
 export * from "./controls/SkiaSpriteSet";
+export * from "./controls/DrawnGame";
 export * from "./core/KeyboardManager";
 export * from "./controls/AnimatedFramesRenderer";
 export * from "./controls/SkiaLottie";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drawnui-react",
-  "version": "0.1.0-preview.10",
+  "version": "0.1.0-preview.11",
   "description": "DrawnUi for React: the DrawnUi (.NET) drawn-UI engine in TypeScript on CanvasKit (Skia WASM). Same controls, same PascalCase API as DrawnUi.Net.",
   "license": "MIT",
   "author": "Nick Kovalsky (AppoMobi)",