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

package/dist/core/SkiaControl.d.ts

@@ -1,8 +1,9 @@
 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 type { InputKey } from "./KeyboardManager";
 import { ContextMenuEventArgs, ControlTappedEventArgs, GestureEventProcessingInfo, type LockTouch, SKPoint, SkiaGesturesInfo, SkiaGesturesParameters } from "./Gestures";
 import { type CachedTexture, type IPostRendererEffect, type SkiaEffect } from "./SkiaEffect";
 /** Mirrors DrawnUi DrawingContext: ctx.Context.Canvas / Surface, ctx.Destination (pixels), ctx.Scale. */
@@ -20,6 +21,10 @@ export interface DrawingContext {
             Y: number;
         };
         Recording?: boolean;
+        /** The picture being recorded is drawn scaled, turned, skewed or projected: images blitted into it sample smoothly (C#). */
+        PlaybackDistorted?: boolean;
+        /** An image cache (or a picture holding one) was blitted here (C#): the picture is recorded again when its playback distortion changes. */
+        HasImageBlits?: boolean;
     };
     Destination: SKRect;
     Scale: number;
@@ -35,8 +40,27 @@ export declare class CachedObject {
     constructor(Type: SkiaCacheType, 
     /** Rect the content was recorded for, canvas pixels at recording time. */
     Bounds: SKRect, Scale: number, Picture?: SkPicture | undefined, Image?: Image | undefined);
-    /** Replays the cache with its top-left moved to (left, top). */
-    Draw(canvas: SkCanvas, left: number, top: number): void;
+    /** Canvas.GpuEpoch it was made in: after a WebGL context restore it is remade (a picture may replay old GPU images). */
+    Epoch: number;
+    /** A picture recorded to be drawn distorted: the images in it sample smoothly (C# CachedObject.PlaybackDistorted). */
+    PlaybackDistorted: boolean;
+    /** A picture holding image blits, whose sampling was fixed when it was recorded (C# CachedObject.HasImageBlits). */
+    HasImageBlits: boolean;
+    /** C# PaintRenderObject: the blit paint is antialiased (else a turned bitmap keeps stair steps along its own border), dithered when distorted. */
+    private static blitPaint?;
+    private static blitPaintDithered?;
+    private static BlitPaint;
+    /** Replays the cache with its top-left moved to (left, top); `smooth` = an image drawn distorted (linear + mipmaps). */
+    Draw(canvas: SkCanvas, left: number, top: number, smooth?: boolean): void;
+    /**
+     * C# GetPictureImage: the picture of a picture cache (Operations, OperationsFull) drawn into an image, made on the
+     * first call (on `main`'s GPU context when given) and kept as long as this cache lives. Shader effects read it as
+     * their input, so on such a control they work on its own content, as on an Image cache.
+     */
+    GetPictureImage(main?: Surface): Image | undefined;
+    private pictureImage?;
+    /** The picture drawn into an image, once GetPictureImage made it. */
+    get PictureImage(): Image | undefined;
     Dispose(): void;
 }
 /**
@@ -83,6 +107,14 @@ export declare class SkiaControl {
     /** Degrees. */
     SkewX: number;
     SkewY: number;
+    /** Degrees, a 3D turn around the horizontal axis through the pivot, seen with perspective (C# RotationX). */
+    RotationX: number;
+    /** Degrees, a 3D turn around the vertical axis through the pivot (C# RotationY). */
+    RotationY: number;
+    /** Degrees, a 3D turn around the axis facing the viewer, after RotationX and RotationY (C# RotationZ). */
+    RotationZ: number;
+    /** Depth: toward the viewer (+, bigger) or away (−, smaller), turned or flat; draws at 576 / (576 − TranslationZ) (C# TranslationZ). */
+    TranslationZ: number;
     /** Pivot for Rotation/Scale/Skew as a fraction of the box (MAUI default 0.5). */
     AnchorX: number;
     AnchorY: number;
@@ -106,6 +138,7 @@ export declare class SkiaControl {
     get Scale(): number;
     set Scale(v: number);
     get HasTransform(): boolean;
+    private get Has3d();
     /** Matrix applied at the last render (canvas space), undefined when none; gestures map through its inverse. */
     RenderTransformMatrix?: number[];
     /** Generic numeric parameters (DrawnUi Value1/Value2): SkiaShape Arc uses start angle / sweep angle in degrees. */
@@ -124,6 +157,11 @@ export declare class SkiaControl {
     /** What to cache for this subtree; see SkiaCacheType. Layouts default to None, SkiaLabel/SkiaSvg to Operations. */
     UseCache: SkiaCacheType;
     /** The cache type actually applied (None while caching is disabled globally). */
+    /**
+     * C# HostsBackdrop: a SkiaBackdrop inside asked this picture-cached control to draw live (a picture would replay
+     * the backdrop's screen copy frozen). Stays set after the backdrop is removed: the control just keeps drawing live.
+     */
+    HostsBackdrop: boolean;
     get UsingCacheType(): SkiaCacheType;
     /** C# IsCacheComposite: the offscreen surface is kept and only the changed children are re-recorded. */
     get IsCacheComposite(): boolean;
@@ -135,18 +173,43 @@ export declare class SkiaControl {
     private compositeSurface?;
     /** Own content or structure changed: the next composite record is a full one. */
     private compositeFull;
+    /** Where the kept composite surface starts relative to DrawingRect (the effects margin it was laid out with). */
+    private compositeInsetX;
+    private compositeInsetY;
     /** Canvas-pixel bounds this control covered when its parent last recorded it (composite erase region). */
     private lastCompositeBounds?;
-    /** What the last composite record did (diagnostics): "full" or "partial", the number of children re-recorded and which ones. */
+    /**
+     * What the last composite record did (diagnostics): "full" or "partial", the number of children re-recorded and which
+     * ones; Areas: the pixels erased and drawn again for changes deeper than a child (C# Areas), Changed: the controls
+     * those areas belong to (C# Changed).
+     */
     LastCompositeRecord: {
         Mode: "full" | "partial";
         Children: number;
         Dirty: readonly SkiaControl[];
+        Areas: readonly SKRect[];
+        Changed: readonly SkiaControl[];
     };
+    /** C# MaxCompositionAreas: more areas than this in one composite record draw it whole instead. */
+    static MaxCompositionAreas: number;
+    /** C# MaxCompositionShare: areas covering more than this share of a composite draw it whole instead. */
+    static MaxCompositionShare: number;
+    /**
+     * Changes deeper than a direct child since the last composite record (drawnui-cross 6m): the control, the direct child
+     * it is in, where it was drawn before the change (its own drawn bounds, as drawn) and its rect then.
+     */
+    private compositeDeep?;
+    /** Set while an UpdateDraw climbs: the ancestors re-measure but an ImageComposite among them keeps its partial record. */
+    private static drawOrigin;
     /** The children a composite record can re-record individually; layouts return their views. */
     protected GetCompositeChildren(): readonly SkiaControl[];
     /** C# TrackChildAsDirty (DirtyChildrenTracker): the child changed without a remeasure of this control. */
     TrackChildAsDirty(child: SkiaControl): void;
+    private static readonly rejectRect;
+    /** Its cache must be recorded before it can be drawn (none, dirty, another type, scale, size or GPU context). */
+    private CacheStale;
+    /** Its rect grown by its effects margin, through the matrix it is drawn with, lies outside the canvas clip. */
+    private OutsideClip;
     /** Drawn bounds in canvas pixels including transforms and effects margins (C# GetTransformedDirtyBounds). */
     GetTransformedDirtyBounds(): SKRect;
     /** Current cache, if any. */
@@ -157,6 +220,36 @@ export declare class SkiaControl {
     /** Consume every gesture that lands on this control so nothing below (z-order) receives it. */
     BlockGesturesBelow: boolean;
     LockChildrenGestures: LockTouch;
+    private receivesHover?;
+    /**
+     * Whether this control takes mouse hover: the canvas sets IsHovered while the mouse is over it. Opt-in: false by
+     * default, true by default only in the controls that always had hover (SkiaButton, SkiaSlider, the toggles,
+     * SkiaRadioButton, SkiaCarousel, SkiaDrawer), never because a control has a tap handler. A HoverChanged handler turns
+     * it on (C# fluent OnHovered) unless it is set.
+     */
+    get ReceivesHover(): boolean;
+    set ReceivesHover(value: boolean);
+    /** The value of ReceivesHover until it is set. */
+    protected ReceivesHoverByDefault(): boolean;
+    private isHovered;
+    /**
+     * True while the mouse is over this control and it takes hover. Every such control under the pointer is hovered at
+     * once (a card and the button inside it, as CSS :hover); it stays as it is while content moves under the pointer and
+     * is checked again when that stops. Touch never hovers.
+     */
+    get IsHovered(): boolean;
+    /** IsHovered changed: true when the mouse came over this control, false when it left (C# HoverChanged / OnHovered). */
+    HoverChanged?: (sender: SkiaControl, hovered: boolean) => void;
+    /** Set by the canvas's HoverManager. */
+    ApplyHover(on: boolean): void;
+    /** A scroll, carousel or drawer moving its content right now: hover waits until it stops (C# IsScrolling / InTransition). */
+    MovesContent(): boolean;
+    /**
+     * Hover hit path (HoverManager): this control is under the point (in its own space), its children under it follow,
+     * top-most first, by the routing rules of ProcessGestures. True when this subtree blocks gestures below it, so the
+     * controls under it get no hover (a popup over a list).
+     */
+    CollectHovered(point: SKPoint, into: SkiaControl[], xs?: number[], ys?: number[]): boolean;
     TouchEffectColor: Color;
     /** Plays a ripple (from the tap point) when Tapped fires. */
     AnimationTapped: SkiaTouchAnimation;
@@ -164,6 +257,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)[];
@@ -175,7 +273,12 @@ export declare class SkiaControl {
     protected OnVisualEffectsChanged(): void;
     /** Post renderers that can render this frame (compiled shaders); an unready effect leaves the control drawn plainly. */
     private ActivePostRenderers;
-    /** C# CachedImage: the cached texture and the canvas rect it was rasterized over (Image caches only). */
+    /**
+     * C# CachedImage: the cached texture (Image caches only) and the canvas rect it covers NOW. Scrolled content is
+     * re-arranged here, not drawn through a translated canvas, so a cache recorded before its control moved is blitted
+     * at the control's current aligned rect (RenderContent) and its record-time Bounds are stale: an effect sampling it
+     * there (the slides of a SkiaShaderCarousel after the page scrolled) was off by the scroll amount.
+     */
     get CachedImage(): CachedTexture | undefined;
     /** Clip overlay effects to the control's shape (CreateClip). */
     ClipEffects: boolean;
@@ -191,6 +294,18 @@ export declare class SkiaControl {
     ConsumeGestures?: (sender: SkiaControl, e: SkiaGesturesInfo) => void;
     Parent?: SkiaControl;
     /** Containers override; a leaf control cannot host children. */
+    private styledInitially;
+    /**
+     * C# ApplyInitialStyles: takes the property defaults registered with `ConfigureStyles` for this control's class.
+     * The reconciler calls it with `atConstruction` right after `new`, before the JSX props, so props win; a control
+     * built in code-behind is styled on its first measure and keeps whatever the code already set.
+     */
+    ApplyInitialStyles(atConstruction?: boolean): void;
+    /**
+     * C# IsChildrenItem: added by the app (JSX children or the `Children` list), not a part the control made itself. A new
+     * `Children` list drops only these, so a control's own parts keep their place.
+     */
+    IsChildrenItem: boolean;
     AddSubView(_control: SkiaControl): void;
     InsertSubView(_index: number, control: SkiaControl): void;
     RemoveSubView(_control: SkiaControl): void;
@@ -213,6 +328,14 @@ 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;
+    /**
+     * A cached ancestor replays its picture where a re-arrange moved it (a scroll) without rendering this control again,
+     * so the matrix made at its last Render moves with its rect: taps, hover and the accessibility rect stay on what is
+     * drawn (C# offsets the cached render tree instead). A control that renders again gets a fresh matrix there.
+     */
+    private FollowMatrix;
+    /** 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;
@@ -237,7 +360,11 @@ export declare class SkiaControl {
     protected DefaultAccessibilityLabel(): string | undefined;
     get AccessibilityHint(): string | undefined;
     set AccessibilityHint(v: string | undefined);
-    /** Tab stop + activation; unset = true when the control handles Tapped. */
+    /**
+     * Whether keyboard navigation and assistive technology may focus and use this node: the explicit value, else the class
+     * default (true when the control handles Tapped), and in both cases only while a tap could reach the control
+     * (CanReceiveGesture), so Tab, Enter / Space and screen-reader activation never use a control the pointer cannot.
+     */
     get AccessibilityCanInteract(): boolean;
     set AccessibilityCanInteract(v: boolean);
     protected DefaultAccessibilityCanInteract(): boolean;
@@ -246,6 +373,8 @@ export declare class SkiaControl {
      * host's pointer cursor. Default: the control as a whole (AccessibilityCanInteract); SkiaLabel adds its tappable spans.
      */
     WantsPointerCursor(_x: number, _y: number): boolean;
+    /** A range control's value for screen readers (slider, progress); undefined for everything else (drawnui-cross 6c). */
+    get AccessibilityValue(): import("./Accessibility").AccessibilityValue | undefined;
     /** aria-pressed for toggles; undefined = not a toggle. */
     get AccessibilityIsPressed(): boolean | undefined;
     set AccessibilityIsPressed(v: boolean | undefined);
@@ -274,6 +403,30 @@ export declare class SkiaControl {
     OnAccessibilityActivated(): void;
     /** Overlay focus arrives on / leaves this node (inputs may activate their sink here). */
     OnAccessibilityFocused(_focused: boolean): void;
+    /**
+     * Keyboard navigation hands this control the keys it may use while it holds keyboard focus (ArrowLeft / Right / Up /
+     * Down, Home, End, PageUp, PageDown, DOM `event.code` names). Return true when the key was used; the default uses none,
+     * so the key moves focus inside the arrow-key group around the control.
+     */
+    OnAccessibilityKey(_key: InputKey): boolean;
+    /**
+     * Whether a pointer gesture of this kind would reach this control, by the rules the gesture dispatch applies: the
+     * control and every ancestor draw, none of them is InputTransparent, no ancestor keeps this gesture from its children
+     * (LockChildrenGestures, PassNone included) and the control accepts input (AcceptsInput). Opacity does not count, as
+     * for the pointer. Keyboard navigation uses it: Tapped for Tab and Enter / Space, Panning for the arrow keys.
+     */
+    CanReceiveGesture(gesture: SkiaGesturesParameters["Type"]): boolean;
+    /**
+     * False while the control ignores input itself: RespondsToGestures = false on a button, toggle, slider, scroll...
+     * Taps, keyboard and the accessibility state (reported disabled) all follow it (drawnui-cross 6w). Default true.
+     */
+    protected AcceptsInput(): boolean;
+    /**
+     * What a control that takes no input returns for a gesture that reached it (C# BlockedGestureResult): it keeps a
+     * press, tap or long press, so nothing under it reacts to them, and lets moves and wheel go on to the controls around
+     * it (a scroll behind it still scrolls).
+     */
+    protected BlockedGestureResult(args: SkiaGesturesParameters): SkiaControl | null;
     NotifyAccessibilityFocused(focused: boolean): void;
     /** DrawnUi SmartMax: larger of two sizes, an infinite one loses. */
     protected static SmartMax(a: number, b: number): number;
@@ -296,8 +449,22 @@ export declare class SkiaControl {
     /** DrawingRect grown by the effects margin, in pixels — the rect a cache is recorded for. */
     protected ExpandedCacheRect(scale: number): SKRect;
     Render(ctx: DrawingContext): void;
-    /** Port of DrawnUi ApplyTransforms: T(-pivot) · rotation · scale/skew · T(pivot) · translation, in canvas pixels. */
+    /** Port of DrawnUi ApplyTransforms: T(-pivot) · rotation · scale/skew · 3D · T(pivot) · translation, in canvas pixels. */
     protected CreateRenderTransformMatrix(destination: SKRect, scale: number): number[];
+    /** C# camera distance of the 3D transforms (Sk3dView.CameraDistance): 8 inches at 72 dpi, in canvas pixels. */
+    static readonly CameraDistance = 576;
+    /**
+     * C# Create3dMatrix (Sk3dView): RotationX, then RotationY, then RotationZ (negated) around the pivot, projected from
+     * the camera; TranslationZ is depth, a flat control at depth z draws at camera / (camera − z).
+     */
+    static Create3dMatrix(rotationX: number, rotationY: number, rotationZ: number, translationZ: number): number[];
+    /** C# SkiaSamplingOptions.IsMoveOnly: the matrix only moves (or mirrors), so a bitmap keeps its pixels 1:1. */
+    static IsMoveOnly(m: ArrayLike<number>): boolean;
+    /**
+     * C# WillDrawDistorted: what this control draws here ends up scaled, turned, skewed or projected, by its own transforms
+     * or a live ancestor's (both in the canvas matrix) or by the picture it is recorded into. Images then sample smoothly.
+     */
+    protected WillDrawDistorted(ctx: DrawingContext): boolean;
     /** Maps a point given in the parent's space into this control's untransformed space (DrawnUi TransformPointToLocalSpace). */
     TransformPointToLocalSpace(point: SKPoint): SKPoint;
     /**
@@ -307,6 +474,8 @@ export declare class SkiaControl {
     private AlignedCacheRect;
     /** Cache blit or live paint, then post animators — the part a transform/opacity layer wraps. */
     private RenderContent;
+    /** Blits a cache: an image samples smoothly when drawn distorted; a picture being recorded learns it holds image blits. */
+    private DrawCache;
     /** Background + Paint(): the part of the control that a cache captures. */
     protected PaintContent(ctx: DrawingContext): void;
     /** Subclasses whose PaintBackground has something to draw without a BackgroundColor (shape shadows). */
@@ -370,11 +539,51 @@ export declare class SkiaControl {
     Update(): void;
     /** Redraw without remeasure and WITHOUT dropping caches (position/overlay changes). */
     Repaint(): void;
+    /**
+     * A parent (not the control itself) is hidden: a change here asks for no frame and the latest state shows when the
+     * parent is shown again (C# 329f6c44 HiddenUpdateTests, DrawnUi.Rust hidden_updates). The control's own visibility
+     * change still draws: it is the one that hides or shows it.
+     */
+    UnderHiddenParent(): boolean;
+    /** The control or a parent is hidden: its animators pause until it shows again. */
+    HiddenInTree(): boolean;
+    /** The control an invalidation started at while it climbs (InvalidateMeasure): a hidden parent of it wakes no frame. */
+    private static invalidateOrigin;
     /**
      * Transform / Opacity changed: this control's own cache is still valid (content unchanged) but every ancestor
      * cache holds its composited output, so those are staled before redrawing (DrawnUi RedrawCanvas + parent invalidation).
      */
     RepaintComposition(): void;
+    /**
+     * Update() for a change of how this control looks, not of its size (a color set through props, C# NeedDraw): the same
+     * re-measure and cache invalidation, but an ImageComposite above redraws only this control's area instead of
+     * recording whole (drawnui-cross 6m). The record still goes whole when the control's rect changed after all.
+     */
+    UpdateDraw(): void;
+    /**
+     * A change of this control that keeps its layout, to every ImageComposite above: a direct child is drawn again whole
+     * (C# TrackChildAsDirty), a deeper control by its area, read now as it was drawn (its last matrix and effects margin).
+     */
+    private ReportToComposites;
+    /** The matrix this control will be drawn with (Render), from its current properties; undefined when none. */
+    private CurrentMatrix;
+    /** Where this control will be drawn: its rect grown by its effects margin, through its current matrix. */
+    private DrawnBoundsNow;
+    private static MapRect;
+    /** Its output depends on all of its content (a visual effect; a backdrop samples below): a change inside redraws it whole. */
+    protected get SamplesContent(): boolean;
+    /**
+     * Where a deep change shows inside the composite (drawnui-cross 6m rule b): the control as drawn before and as drawn
+     * now, then through the transform of every ancestor up to the composite. undefined: draw the child whole (an effect
+     * or a backdrop on the way, the control gone from the child); null: the layout changed, record whole.
+     */
+    private static DeepArea;
+    /**
+     * DrawnUi IsParentIndependent: this control's size never changes the layout around it, so its own invalidation
+     * stops here (ancestors composite again, nothing above re-measures). The parent re-measures it on draw when
+     * NeedMeasure is set. Used by SkiaScroll for its scroll bars.
+     */
+    IsParentIndependent: boolean;
     /** Size or content may have changed: this control and all ancestors remeasure and re-record. */
     InvalidateMeasure(): void;
     /** Hit rect in pixels (no transforms in this port, so it is DrawingRect). */