drawnui-react 0.1.0-preview.1

package/dist/core/SkiaControl.d.ts

@@ -0,0 +1,401 @@
+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 { Easing } from "./Easing";
+import type { Canvas } from "./Canvas";
+import { 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. */
+export interface DrawingContext {
+    /**
+     * Surface = where the pixels end up (an Image cache surface or the on-screen one), Origin = that surface's top-left
+     * in canvas pixels (caches are translated to their own origin), Recording = the canvas records a picture
+     * (Operations cache) that is replayed on Surface later.
+     */
+    Context: {
+        Canvas: SkCanvas;
+        Surface?: Surface;
+        Origin?: {
+            X: number;
+            Y: number;
+        };
+        Recording?: boolean;
+    };
+    Destination: SKRect;
+    Scale: number;
+}
+/** Mirrors DrawnUi CachedObject: what a cached control replays instead of repainting. */
+export declare class CachedObject {
+    readonly Type: SkiaCacheType;
+    /** Rect the content was recorded for, canvas pixels at recording time. */
+    readonly Bounds: SKRect;
+    readonly Scale: number;
+    readonly Picture?: SkPicture | undefined;
+    readonly Image?: Image | undefined;
+    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;
+    Dispose(): void;
+}
+/**
+ * Base of every drawn control. Same contract as DrawnUi SkiaControl:
+ * Measure(constraints px, scale) -> MeasuredSize (includes Margin),
+ * Arrange(destination px) -> DrawingRect,
+ * Render(ctx) -> background + Paint(ctx),
+ * ProcessGestures(args, apply) -> consumer or null.
+ */
+export declare class SkiaControl {
+    HorizontalOptions: LayoutOptions;
+    VerticalOptions: LayoutOptions;
+    /** -1 = auto. */
+    WidthRequest: number;
+    HeightRequest: number;
+    /** Caps the available size (points); a Fill control fills only up to it and stays start-aligned, like DrawnUi. -1 = none. */
+    MaximumWidthRequest: number;
+    MaximumHeightRequest: number;
+    /** Floors the measured size (points). -1 = none. */
+    MinimumWidthRequest: number;
+    MinimumHeightRequest: number;
+    /** Grid placement (C# attached properties SkiaLayout.Column/Row/ColumnSpan/RowSpan). */
+    Column: number;
+    Row: number;
+    ColumnSpan: number;
+    RowSpan: number;
+    Margin: Thickness;
+    /**
+     * DrawnUi LockRatio: 0 = off; positive = square of the LARGER of the two sizes (requests or constraints),
+     * negative = square of the SMALLER one. Infinite sides are ignored, so WidthRequest=150 + LockRatio=1 = 150x150.
+     */
+    LockRatio: number;
+    BackgroundColor?: Color;
+    /** Gradient painted as the background (over BackgroundColor). */
+    FillGradient?: SkiaGradient;
+    IsVisible: boolean;
+    Tag?: string;
+    TranslationX: number;
+    TranslationY: number;
+    /** Degrees, around (AnchorX, AnchorY). */
+    Rotation: number;
+    ScaleX: number;
+    ScaleY: number;
+    /** Degrees. */
+    SkewX: number;
+    SkewY: number;
+    /** Pivot for Rotation/Scale/Skew as a fraction of the box (MAUI default 0.5). */
+    AnchorX: number;
+    AnchorY: number;
+    /** 0..1, applied as a layer alpha over the whole subtree (MAUI VisualElement.Opacity). */
+    Opacity: number;
+    /** Clip everything this control draws (content, children, effects per ClipEffects) to its DrawingRect. */
+    IsClippedToBounds: boolean;
+    /** Paint-time offset in points (C# Left/Top: moves the cached output without a matrix; here a plain translate). */
+    Left: number;
+    Top: number;
+    private zIndex;
+    /** Drawing order among siblings: higher draws later (on top) and receives gestures first (C# ZIndex). */
+    get ZIndex(): number;
+    set ZIndex(v: number);
+    /** A layout re-sorts its children by ZIndex on the next draw (C# _orderedChildren reset). */
+    InvalidateViewsOrder(): void;
+    /** Fraction of the available box a Fill control takes (C# DefineAvailableSize); alignment stays inside the full box. */
+    HorizontalFillRatio: number;
+    VerticalFillRatio: number;
+    /** Sets ScaleX and ScaleY together (MAUI Scale). */
+    get Scale(): number;
+    set Scale(v: number);
+    get HasTransform(): boolean;
+    /** 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. */
+    Value1: number;
+    Value2: number;
+    /** Extra points beyond the viewport a virtualized layout keeps realized (DrawnUi VirtualisationInflated). */
+    VirtualisationInflated: number;
+    private bindingContext;
+    /** Bound item; recycled cells get a new one on every rebind. */
+    get BindingContext(): unknown;
+    set BindingContext(value: unknown);
+    /** Index of the bound item inside its ItemsSource, -1 when not templated. */
+    ContextIndex: number;
+    /** Override to react to a new BindingContext (DrawnUi ContextPropertyChanged / cell SetContent). */
+    protected OnBindingContextChanged(): void;
+    /** 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). */
+    get UsingCacheType(): SkiaCacheType;
+    /** C# IsCacheComposite: the offscreen surface is kept and only the changed children are re-recorded. */
+    get IsCacheComposite(): boolean;
+    /** Children reported dirty since the last composite record (C# DirtyChildrenInternal, filled by RepaintComposition). */
+    readonly DirtyChildrenInternal: Set<SkiaControl>;
+    /** True while a composite re-record paints only the dirty children (C# IsRenderingWithComposition). */
+    IsRenderingWithComposition: boolean;
+    /** Composite surface kept across records; its size follows the expanded cache rect. */
+    private compositeSurface?;
+    /** Own content or structure changed: the next composite record is a full one. */
+    private compositeFull;
+    /** 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. */
+    LastCompositeRecord: {
+        Mode: "full" | "partial";
+        Children: number;
+        Dirty: readonly SkiaControl[];
+    };
+    /** 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;
+    /** Drawn bounds in canvas pixels including transforms and effects margins (C# GetTransformedDirtyBounds). */
+    GetTransformedDirtyBounds(): SKRect;
+    /** Current cache, if any. */
+    RenderObject?: CachedObject;
+    private cacheDirty;
+    /** Control itself ignores input (things below it still get it). */
+    InputTransparent: boolean;
+    /** Consume every gesture that lands on this control so nothing below (z-order) receives it. */
+    BlockGesturesBelow: boolean;
+    LockChildrenGestures: LockTouch;
+    TouchEffectColor: Color;
+    /** Plays a ripple (from the tap point) when Tapped fires. */
+    AnimationTapped: SkiaTouchAnimation;
+    /** Ripple duration ms, 0 = animator default (500). */
+    AnimationTappedSpeed: number;
+    /** Overlay effects drawn above this control's content every frame (ripple etc). */
+    readonly PostAnimators: IOverlayEffect[];
+    private visualEffects;
+    /** Post-renderer effects among VisualEffects (C# EffectPostRenderers). */
+    EffectPostRenderers: (SkiaEffect & IPostRendererEffect)[];
+    /** Skip every attached effect (C# DisableEffects). */
+    DisableEffects: boolean;
+    /** Effects attached to this control; assign a new array to change them (they are attached/detached here). */
+    get VisualEffects(): readonly SkiaEffect[];
+    set VisualEffects(v: readonly SkiaEffect[] | undefined);
+    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). */
+    get CachedImage(): CachedTexture | undefined;
+    /** Clip overlay effects to the control's shape (CreateClip). */
+    ClipEffects: boolean;
+    Tapped?: (sender: SkiaControl, e: ControlTappedEventArgs) => void;
+    ChildTapped?: (sender: SkiaControl, e: ControlTappedEventArgs) => void;
+    /** Raw gesture hook: set e.Consumed = true to stop propagation (not for Up). */
+    ConsumeGestures?: (sender: SkiaControl, e: SkiaGesturesInfo) => void;
+    Parent?: SkiaControl;
+    /** Containers override; a leaf control cannot host children. */
+    AddSubView(_control: SkiaControl): void;
+    InsertSubView(_index: number, control: SkiaControl): void;
+    RemoveSubView(_control: SkiaControl): void;
+    /** Set by Canvas on its Content. Children resolve through Parent. */
+    _superview?: Canvas;
+    get Superview(): Canvas | undefined;
+    MeasuredSize: ScaledSize;
+    DrawingRect: SKRect;
+    RenderingScale: number;
+    NeedMeasure: boolean;
+    private lastWidthConstraint;
+    private lastHeightConstraint;
+    /**
+     * Public non-virtual entry like DrawnUi: applies Margin/requests, then MeasureAbsolute for content.
+     * A control that was not invalidated and gets the same constraints + scale returns its previous size —
+     * this is what keeps a cached tree from re-measuring text every frame.
+     */
+    Measure(widthConstraint: number, heightConstraint: number, scale: number): ScaledSize;
+    /** Override to measure own content, constraints already exclude Margin. */
+    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;
+    private static nextAccessibilityId;
+    /** Stable identity for the DOM overlay. */
+    readonly AccessibilityId: number;
+    private registeredWithAccessibility;
+    private accessibilityRole?;
+    private accessibilityLabel?;
+    private accessibilityHint?;
+    private accessibilityCanInteract?;
+    private accessibilityIsPressed?;
+    private accessibilityLive?;
+    /**
+     * ARIA role; setting it exposes the control to assistive technology (use `Aria` constants). Unset = the class
+     * default (`SkiaLabel.DefaultAccessibilityRole` etc.), which is itself unset unless the app opts in.
+     */
+    get AccessibilityRole(): string | undefined;
+    set AccessibilityRole(v: string | undefined);
+    /** Per-class default role (React extension): e.g. `SkiaLabel.DefaultAccessibilityRole = Aria.RoleText` reads every label. */
+    static DefaultAccessibilityRole?: string;
+    /** Spoken label; unset = the control's own text (SkiaLabel.Text, SkiaButton.Text). */
+    get AccessibilityLabel(): string | undefined;
+    set AccessibilityLabel(v: string | undefined);
+    protected DefaultAccessibilityLabel(): string | undefined;
+    get AccessibilityHint(): string | undefined;
+    set AccessibilityHint(v: string | undefined);
+    /** Tab stop + activation; unset = true when the control handles Tapped. */
+    get AccessibilityCanInteract(): boolean;
+    set AccessibilityCanInteract(v: boolean);
+    protected DefaultAccessibilityCanInteract(): boolean;
+    /** aria-pressed for toggles; undefined = not a toggle. */
+    get AccessibilityIsPressed(): boolean | undefined;
+    set AccessibilityIsPressed(v: boolean | undefined);
+    /** aria-live: `Aria.LivePolite` / `Aria.LiveAssertive`; changes are announced immediately. */
+    get AccessibilityLive(): string | undefined;
+    set AccessibilityLive(v: string | undefined);
+    get IsAccessibilityElement(): boolean;
+    private accessibilityTextSelectable;
+    /**
+     * Opt-in (React extension, off by default): the control's text is rendered as real, invisible DOM text in the
+     * accessibility overlay with pointer events, so the browser selects / copies it like HTML. Pointer input over the
+     * text then goes to the selection, not to the drawn control — never enable it on gesture-driven controls.
+     */
+    get AccessibilityTextSelectable(): boolean;
+    set AccessibilityTextSelectable(v: boolean);
+    /** Text lines for AccessibilityTextSelectable in CSS px relative to the node (SkiaLabel implements it). */
+    GetAccessibilityTextLines(_scale: number): import("./Accessibility").AccessibilityTextLine[];
+    /** Hit rect in canvas pixels used to position the overlay element: the drawn (transformed) bounds, like C# HitBoxWithTransforms. */
+    GetAccessibilityPixelRect(): SKRect;
+    /** Registers on first call, marks the snapshot dirty afterwards. */
+    NotifyAccessibility(): void;
+    UnregisterAccessibility(): void;
+    AccessibilityChanged(): void;
+    OnAccessibilityUnregistered(): void;
+    /** Platform layer (overlay click / Enter): injects a synthetic Tapped at the control's center into the gesture pipeline. */
+    OnAccessibilityActivated(): void;
+    /** Overlay focus arrives on / leaves this node (inputs may activate their sink here). */
+    OnAccessibilityFocused(_focused: boolean): void;
+    NotifyAccessibilityFocused(focused: boolean): void;
+    /** DrawnUi SmartMax: larger of two sizes, an infinite one loses. */
+    protected static SmartMax(a: number, b: number): number;
+    /** DrawnUi SmartMin: smaller of two sizes, an infinite one loses. */
+    protected static SmartMin(a: number, b: number): number;
+    private static Align;
+    /** Called after DrawingRect changed; layouts arrange children here. */
+    protected OnLayoutChanged(): void;
+    /** Part of DrawingRect that can actually be seen: intersected with every ancestor (a scroll's box clips its content). */
+    GetVisibleViewport(): SKRect;
+    /** Draws the control: from its cache when it has one, else background + Paint(); overlays always live. */
+    /**
+     * Pixels the control paints OUTSIDE its DrawingRect (shadows, effects): caches record that much more and the
+     * blit is offset accordingly (DrawnUi ComputeEffectsMargin / GetRenderingExpandPixels). Base: nothing.
+     */
+    ComputeEffectsMargin(_scale: number): Thickness;
+    private effectsMarginCache?;
+    /** Cached ComputeEffectsMargin (reset by InvalidateMeasure) — C# AggregatedEffectsMarginPixels. */
+    EffectsMargin(scale: number): Thickness;
+    /** 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. */
+    protected CreateRenderTransformMatrix(destination: SKRect, scale: number): number[];
+    /** Maps a point given in the parent's space into this control's untransformed space (DrawnUi TransformPointToLocalSpace). */
+    TransformPointToLocalSpace(point: SKPoint): SKPoint;
+    /**
+     * Image caches are rasterized over whole device pixels: the expanded rect snapped outward to integers, so the blit
+     * lands 1:1 (no sub-pixel resample) and effects sampling the cache at `fragCoord - iOffset` hit texel centers.
+     */
+    private AlignedCacheRect;
+    /** Cache blit or live paint, then post animators — the part a transform/opacity layer wraps. */
+    private RenderContent;
+    /** 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). */
+    protected PaintsBackgroundWithoutColor(): boolean;
+    /**
+     * ImageDoubleBuffered: the last cache is kept while a new one is produced and shown when producing fails
+     * (no surface yet); no background thread in the browser, so recording itself stays synchronous like DrawnUi.Blazor.
+     */
+    RenderObjectPrevious?: CachedObject;
+    /** Drawn when a cache is expected but none exists yet (DrawnUi DrawPlaceholder, ImageDoubleBuffered only). Default: nothing. */
+    protected DrawPlaceholder(_ctx: DrawingContext): void;
+    /** Records/renders the content into a new CachedObject for the current DrawingRect. */
+    protected CreateRenderingObject(ctx: DrawingContext, cacheType: SkiaCacheType): void;
+    /**
+     * C# ImageComposite (SetupRenderingWithComposition + CreateRenderingObject reuse): the offscreen surface survives
+     * between records; when only some children changed (RepaintComposition from a child, no remeasure of this control)
+     * their old and new bounds — plus every sibling they overlap — are erased and just those children are painted
+     * again. Anything else (own content, structure, size, scale) records fully.
+     */
+    private CreateCompositeRenderingObject;
+    private DisposePrevious;
+    /** Drops the cache (disposed after the frame, never mid-draw). */
+    DestroyRenderingObject(): void;
+    /** Marks the cache stale; re-recorded on the next frame (a composite records fully: its own content changed). */
+    InvalidateCache(): void;
+    /** Effects margin recomputed on the next use (C# InvalidateEffectsMargin). */
+    InvalidateEffectsMargin(): void;
+    /** Draws PostAnimators above content; an effect returning true asks for another frame. */
+    ExecutePostAnimators(ctx: DrawingContext): void;
+    /** Clip path of this control in canvas pixels (rect; shapes override). Caller deletes it. */
+    CreateClip(): Path;
+    /** Fills DrawingRect with BackgroundColor / FillGradient; shapes override for rounded corners etc. */
+    protected PaintBackground(ctx: DrawingContext): void;
+    /** Paint for the background: solid BackgroundColor, or FillGradient shader over the given rect. Caller deletes. */
+    protected CreateBackgroundPaint(rect: SKRect): import("canvaskit-wasm").Paint;
+    /** Whether FillGradient fills the background (C# base: yes, even without BackgroundColor; SkiaLabel: only the glyphs unless BackgroundColor is set). */
+    protected FillGradientPaintsBackground(): boolean;
+    /** Shaders built for a gradient object, keyed by the rect they were built for (C# cached SetupGradient overload). */
+    private gradientShaders?;
+    /** C# SetupGradient: white base color, the gradient's BlendMode and a (cached) shader on the paint. */
+    SetupGradient(paint: import("canvaskit-wasm").Paint, gradient: SkiaGradient, rect: SKRect): boolean;
+    /** Port of C# CreateGradient: Linear / Circular / Oval / Sweep shader over the rect (pixels); null for None. */
+    CreateGradient(rect: SKRect, g: SkiaGradient): import("canvaskit-wasm").Shader | null;
+    /** C# SkiaGradient.LinearGradientAngleToPoints (CSS angle -> start/end ratios). */
+    static LinearGradientAngleToPoints(direction: number): [number, number, number, number];
+    /** C# MakeDarker / MakeLighter: HSL lightness scaled down (light < 1) or pushed toward white (light > 1). */
+    static AdjustLightness(rgb: [number, number, number], light: number): [number, number, number];
+    /** Override to draw own content into ctx.Destination. */
+    protected Paint(_ctx: DrawingContext): void;
+    IsDisposed: boolean;
+    /**
+     * Frees what the control owns: caches, gradient shaders, running animations and overlay effects, the accessibility
+     * node, then the children. Called by the React renderer when the element leaves the tree (detachDeletedInstance).
+     */
+    Dispose(): void;
+    /** Subclasses release their own native objects here (before the base frees caches and children). */
+    protected OnDisposing(): void;
+    /** Layouts dispose their children here. */
+    protected DisposeChildren(): void;
+    /** Content changed: cache invalidated + remeasure + redraw (bubbles to every ancestor, whose caches go stale too). */
+    Update(): void;
+    /** Redraw without remeasure and WITHOUT dropping caches (position/overlay changes). */
+    Repaint(): void;
+    /**
+     * 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;
+    /** 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). */
+    get HitBoxAuto(): SKRect;
+    HitIsInside(x: number, y: number): boolean;
+    IsGestureForChild(child: SkiaControl, point: SKPoint): boolean;
+    /** Children that may receive gestures, top-most LAST (layouts return their Views). */
+    protected GetGestureListeners(): readonly SkiaControl[];
+    private static readonly NoListeners;
+    /** ISkiaGestureListener entry, same as DrawnUi: routes to ProcessGestures. */
+    OnSkiaGestureEvent(args: SkiaGesturesParameters, apply: GestureEventProcessingInfo): SkiaControl | null;
+    protected CheckChildrenGesturesLocked(type: SkiaGesturesParameters["Type"]): boolean;
+    /**
+     * Port of DrawnUi SkiaControl.ProcessGestures (non-render-tree branch):
+     * ConsumeGestures hook -> children top-most first -> own Tapped. Returns the consumer or null.
+     */
+    ProcessGestures(args: SkiaGesturesParameters, apply: GestureEventProcessingInfo): SkiaControl | null;
+    /** Fires Tapped (after AnimationTapped feedback); true when a handler existed (= consumed), like DrawnUi SendTapped. */
+    protected SendTapped(args: SkiaGesturesParameters, apply: GestureEventProcessingInfo): boolean;
+    /** Canvas-pixel touch location -> points relative to this control's top-left. */
+    GetOffsetInsideControlInPoints(location: SKPoint, childOffset: SKPoint): SKPoint;
+    private ownAnimations;
+    /** Runs callback(0..1) over ms with easing on the canvas frame loop; rejects with AbortError when cancelled. */
+    AnimateAsync(callback: (value: number) => void, onCancel?: () => void, ms?: number, easing?: Easing, cancel?: AbortSignal): Promise<void>;
+    /** callback(start..end) over ms. */
+    AnimateRangeAsync(callback: (value: number) => void, start: number, end: number, ms?: number, easing?: Easing, cancel?: AbortSignal): Promise<void>;
+    /** One running animation per kind, like the per-property CancellationTokenSources in C#. */
+    private RunOwnAnimation;
+    FadeToAsync(end: number, ms?: number, easing?: Easing, cancel?: AbortSignal): Promise<void>;
+    ScaleToAsync(x: number, y: number, ms?: number, easing?: Easing, cancel?: AbortSignal): Promise<void>;
+    TranslateToAsync(x: number, y: number, ms?: number, easing?: Easing, cancel?: AbortSignal): Promise<void>;
+    RotateToAsync(end: number, ms?: number, easing?: Easing, cancel?: AbortSignal): Promise<void>;
+    /** Starts a ripple at (x, y) points inside this control; speedMs 0 = RippleAnimator default. */
+    PlayRippleAnimation(color: Color, x: number, y: number, _removePrevious?: boolean, speedMs?: number): void;
+}