drawnui-react 0.1.0-preview.7 → 0.1.0-preview.9

package/SKIPPED.md

@@ -47,10 +47,11 @@ DrawnUi name and semantics; nothing here is a redesign, only an omission.
 | Area | Status | Notes |
 |---|---|---|
 | `RenderingMode` | partial | `Accelerated` (WebGL) with automatic fallback to software; read once at first surface creation. |
-| `Gestures` param | ported | Touch: `Lock` applies `touch-action:none`; `Enabled` behaves like MAUI's Enabled inside a native scroll view: `touch-action` is the axes the page (or a scrolling ancestor) can scroll (`pan-y` / `pan-x` / both, `none` when it cannot; inside an iframe the vertical axis always counts, because the embedding page cannot be inspected cross-origin), recomputed on attach, on window / html / body resize and after every touch, so a finger pan along a page axis scrolls the page and the canvas pointer is cancelled (a cancelled pointer never flings a `SkiaScroll`), taps and the other axis stay on the canvas, and a full-page app keeps every touch. `user-select:none` in both. Mouse wheel: `Enabled` shares it with the page like Blazor's `TouchHandlingStyle.Manual` (the wheel is processed in the DOM handler and the browser default is prevented only when a control used it: a scroll that moved, a `ConsumeGestures` handler that consumed, or any other consumer that is not a `BlockGesturesBelow` layer merely blocking the controls below, so an embedded canvas lets the page scroll over anything that does not scroll, including a shell page, and a scroll at its edge hands the wheel to the page; `TouchActionEventArgs.Handled` is the AppoMobi marker for that use); `Lock` prevents every wheel and also blocks `touchmove` default. Not ported: Blazor's pointer capture policy for `Enabled` (capture only while locked, release when a pan is not consumed); React captures every press. |
+| `Gestures` param | ported | Touch: `Lock` applies `touch-action:none`; `Enabled` behaves like MAUI's Enabled inside a native scroll view: `touch-action` is the axes the page (or a scrolling ancestor) can scroll (`pan-y` / `pan-x` / both, `none` when it cannot; inside an iframe the vertical axis always counts, because the embedding page cannot be inspected cross-origin), recomputed on attach, on window / html / body resize and after every touch, so a finger pan along a page axis scrolls the page and the canvas pointer is cancelled (a cancelled pointer never flings a `SkiaScroll`), taps and the other axis stay on the canvas, and a full-page app keeps every touch. `user-select:none` in both. Claimed touches: in `Enabled` a touch or pen Down is processed immediately (queued gestures first) and, when a control used it (same rule as the wheel: marked `Handled`, or a consumer that is not a `BlockGesturesBelow` layer), the touch is claimed and its `touchmove` events are default-prevented until it ends, so the page cannot take that drag mid-gesture (iOS Safari ignores `touch-action` for off-axis drags, w3c/pointerevents#303); unclaimed touches share the page as before. Controls that use a Down: `ConsumeGestures` handlers that set `Consumed`, `SkiaCarousel` (always), `SkiaSlider`, `SkiaEditor`, `SkiaButton` when `OnDown` accepts; `SkiaScroll` and plain `Tapped` controls do not. Mouse wheel: `Enabled` shares it with the page like Blazor's `TouchHandlingStyle.Manual` (the wheel is processed in the DOM handler and the browser default is prevented only when a control used it: a scroll that moved, a `ConsumeGestures` handler that consumed, or any other consumer that is not a `BlockGesturesBelow` layer merely blocking the controls below, so an embedded canvas lets the page scroll over anything that does not scroll, including a shell page, and a scroll at its edge hands the wheel to the page; `TouchActionEventArgs.Handled` is the AppoMobi marker for that use); `Lock` prevents every wheel and also blocks `touchmove` default. Not ported: Blazor's pointer capture policy for `Enabled` (capture only while locked, release when a pan is not consumed); React captures every press. |
 | Mouse cursor over interactive controls (Blazor `Canvas.razor` `.xaml-a11y-interactive { cursor: pointer }`) | ported (differently) | The overlay here is `pointer-events: none`, so `Canvas.UpdateCursor` hit-tests mouse moves with no active pointer against the accessibility snapshot rects (`CanInteract` = has `Tapped`, buttons, links) and asks each hit control `WantsPointerCursor(x, y)` (default `AccessibilityCanInteract`; `SkiaLabel` also answers for its tappable `TextSpan`s), setting the canvas element's `cursor` only when the answer changes. Touch pointers do nothing. Engine hover (`IsHovered` / `OnHover`, `TouchActionResult.Pointer`) stays skipped, see Gestures. |
 | `ContextMenu` (right click / long press / Menu key, React extension) | ported (web-only) | `SkiaControl.ContextMenu` / `Canvas.ContextMenu` handlers with `ContextMenuEventArgs` (`Location` points, `Pixels`, `Local` px in the control, `Source`, `Native`); the DOM `contextmenu` event is routed like a tap (`ProcessContextMenu`: visible non-transparent children top-most first through `TransformPointToLocalSpace`, then the control, then the canvas). `true` = handled, browser menu suppressed; nothing handled = browser menu. Not in DrawnUi.Net. |
 | Keyboard, focus (`FocusedChild`) | skipped | |
+| Canvas draw events | ported | `WillFirstTimeDraw` (once, right before the first frame drawn on a ready surface, with that frame's `{ Canvas, Surface }`), `WasDrawn` (after every frame, no context, like the C# `null`), `WasRendered` (set after the first frame completes, so the first `WasDrawn` still sees `false`, C# order), `CanRender` (surface ready). JSX: `<Canvas WillFirstTimeDraw WasDrawn>`; the engine draws frame 1 in its constructor, so the component hands both callbacks to the constructor's `init`. Not ported: `WillDraw`. |
 | Rendering stats | partial | `Canvas.FPS` (frames drawn over the last second) and `Canvas.FrameTime` (ms of the last measure + arrange + render, GPU flush excluded) are computed every frame and reachable from React through the `<Canvas>` ref. Not ported: the `SkiaLabelFps` control, `Super.EnableRenderingStats`. |
 | Insets / safe areas | ported | `Super.Insets` measures `env(safe-area-inset-*)` off a probe element (once, and again on resize / orientation), `Super.OnInsetsChanged` notifies; `SkiaShell` pads its nav and tab bars with them. Not ported: the C# per-page `IgnoreSafeArea` / MAUI inset plumbing. |
 

package/dist/core/Canvas.d.ts

@@ -1,5 +1,5 @@
 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 { type Color, type RenderingModeType } from "./Types";
@@ -23,6 +23,18 @@ 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;
     private content?;
@@ -35,7 +47,8 @@ export declare class Canvas {
     private frameId;
     private disposed;
     private readonly observer;
-    constructor(Element: HTMLCanvasElement);
+    /** `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). */

package/dist/core/Canvas.js

@@ -21,6 +21,18 @@ export class Canvas {
     /** Frames per second over the last second of drawn frames. */
     FPS = 0;
     frameTimes = [];
+    /** DrawnView.WasRendered: a frame has been drawn on a ready surface (set after the first one completes). */
+    WasRendered = false;
+    /** DrawnView.CanRender: the surface (and its GPU context when accelerated) is ready to draw. */
+    get CanRender() { return !!this.surface && !this.disposed; }
+    /**
+     * 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;
+    /** DrawnView.WasDrawn: raised after every frame has been drawn (the C# event passes no context). */
+    WasDrawn;
     /** Registry + rate-limited snapshot of accessible controls, rendered by the DOM overlay (DrawnUi AccessibilityManager). */
     AccessibilityManager = new SkiaAccessibilityManager();
     content;
@@ -42,10 +54,12 @@ export class Canvas {
     frameId = 0;
     disposed = false;
     observer;
-    constructor(Element) {
+    /** `init` runs before the first frame is drawn: the place to attach `WillFirstTimeDraw` / `WasDrawn` for that frame. */
+    constructor(Element, init) {
         this.Element = Element;
         if (!Super.CK)
             throw new Error("DrawnUi: call Super.UseDrawnUi()...BuildAsync() before creating a Canvas");
+        init?.(this);
         this.observer = new ResizeObserver(() => this.OnResized());
         this.observer.observe(Element);
         this.OnResized();
@@ -122,6 +136,9 @@ export class Canvas {
         const started = performance.now();
         this.ProcessPendingGestures();
         const executed = this.ExecuteAnimators(Math.round(started * 1_000_000));
+        const canRender = this.CanRender;
+        if (canRender && !this.WasRendered)
+            this.WillFirstTimeDraw?.(this, { Canvas: canvas, Surface: this.surface });
         canvas.clear(Super.ParseColor(this.BackgroundColor));
         const root = this.content;
         if (root) {
@@ -141,6 +158,10 @@ export class Canvas {
         this.FPS = this.frameTimes.length;
         if (executed > 0)
             this.Update(); // animators running: keep frames coming
+        // C# order: WasDrawn at the end of the frame, then the frame counts as rendered
+        this.WasDrawn?.(this);
+        if (!this.WasRendered && canRender)
+            this.WasRendered = true;
     }
     // ---- deferred disposal (DrawnUi DisposeObject: never delete Skia objects mid-frame) ----
     disposeQueue = [];
@@ -395,6 +416,10 @@ export class Canvas {
             y = true;
         if (!x && !clips(hs.overflowX) && !clips(bs.overflowX) && root.scrollWidth > root.clientWidth + 1)
             x = true;
+        // a canvas filling a framed document (a widget in an iframe): the page that scrolls is the parent, which a
+        // cross-origin frame cannot inspect, so assume it scrolls vertically; horizontal pans and taps stay on the canvas
+        if (!y && window.self !== window.top)
+            y = true;
         return x && y ? "pan-x pan-y" : y ? "pan-y" : x ? "pan-x" : "none";
     }
     /**

package/dist/react/index.d.ts

@@ -113,12 +113,16 @@ export interface CanvasProps {
     ref?: Ref<CanvasView>;
     /** Context-menu request (right click / long press / Menu key) no control handled; return true to suppress the browser menu. */
     ContextMenu?: CanvasView["ContextMenu"];
+    /** DrawnView.WillFirstTimeDraw: once, right before the first frame is drawn, with its drawing context. */
+    WillFirstTimeDraw?: CanvasView["WillFirstTimeDraw"];
+    /** DrawnView.WasDrawn: after every drawn frame. */
+    WasDrawn?: CanvasView["WasDrawn"];
 }
 /**
  * Mirrors DrawnUi Canvas: the bridge between the DOM (react-dom) and the drawn tree (DrawnUi reconciler).
  * Requires Super.UseDrawnUi()...BuildAsync() to have completed.
  */
-export declare function Canvas({ BackgroundColor, RenderingMode, Gestures, children, style, className, ref: viewRef, ContextMenu }: CanvasProps): import("react").JSX.Element;
+export declare function Canvas({ BackgroundColor, RenderingMode, Gestures, children, style, className, ref: viewRef, ContextMenu, WillFirstTimeDraw, WasDrawn }: CanvasProps): import("react").JSX.Element;
 export type { SkiaControl };
 export * from "../index";
 export * from "./SkiaShell";

package/dist/react/index.js

@@ -66,15 +66,19 @@ function removeStaticContent() {
  * Mirrors DrawnUi Canvas: the bridge between the DOM (react-dom) and the drawn tree (DrawnUi reconciler).
  * Requires Super.UseDrawnUi()...BuildAsync() to have completed.
  */
-export function Canvas({ BackgroundColor, RenderingMode, Gestures, children, style, className, ref: viewRef, ContextMenu }) {
+export function Canvas({ BackgroundColor, RenderingMode, Gestures, children, style, className, ref: viewRef, ContextMenu, WillFirstTimeDraw, WasDrawn }) {
     const ref = useRef(null);
     const view = useRef(null);
     const root = useRef(null);
     const [engine, setEngine] = useState(null);
     useLayoutEffect(() => {
-        const v = new CanvasView(ref.current);
-        if (RenderingMode)
-            v.RenderingMode = RenderingMode;
+        // the engine draws frame 1 inside its constructor: the draw events and the rendering mode must be on it before that
+        const v = new CanvasView(ref.current, (c) => {
+            if (RenderingMode)
+                c.RenderingMode = RenderingMode;
+            c.WillFirstTimeDraw = WillFirstTimeDraw;
+            c.WasDrawn = WasDrawn;
+        });
         view.current = v;
         root.current = createDrawnRoot(v);
         setEngine(v);
@@ -93,6 +97,8 @@ export function Canvas({ BackgroundColor, RenderingMode, Gestures, children, sty
         }
         v.Gestures = Gestures ?? "Disabled";
         v.ContextMenu = ContextMenu;
+        v.WillFirstTimeDraw = WillFirstTimeDraw;
+        v.WasDrawn = WasDrawn;
         root.current.render(children);
     });
     // The drawn surface is aria-hidden; the overlay is the accessibility tree (DrawnUi.Blazor pattern).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drawnui-react",
-  "version": "0.1.0-preview.7",
+  "version": "0.1.0-preview.9",
   "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)",