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

package/dist/core/Accessibility.d.ts

@@ -1,3 +1,4 @@
+import type { InputKey } from "./KeyboardManager";
 import type { SkiaControl } from "./SkiaControl";
 import { SKRect } from "./Types";
 /** ARIA role constants (DrawnUi.Models.Aria) for `AccessibilityRole`. */
@@ -38,10 +39,25 @@ export declare const Aria: {
     readonly RoleRegion: "region";
     readonly RoleNavigation: "navigation";
     readonly RoleMain: "main";
+    readonly RoleGrid: "grid";
+    readonly RoleToolbar: "toolbar";
+    readonly RoleRadioGroup: "radiogroup";
+    readonly RoleMenuBar: "menubar";
     /** Removes the control from the accessibility tree even when a default role would apply (inner label of a button). */
     readonly RolePresentation: "presentation";
     readonly LivePolite: "polite";
     readonly LiveAssertive: "assertive";
+    /**
+     * Container roles whose items the arrow keys walk (C# Aria.IsCompositeRole): a layout with one of them is one Tab stop,
+     * its current item, and the arrow keys move between its items.
+     */
+    readonly IsCompositeRole: (role?: string) => boolean;
+    /**
+     * Roles a user operates (C# Aria.IsInteractiveRole, as DrawnUi.Rust is_control_role): a node with one of them that
+     * cannot take input is read as disabled (aria-disabled). C# also lists listbox and scrollbar; here a listbox is an
+     * arrow-key group and groups are never disabled.
+     */
+    readonly IsInteractiveRole: (role?: string) => boolean;
 };
 /** One laid-out text line exposed for native selection (AccessibilityTextSelectable): CSS px relative to the node. */
 export interface AccessibilityTextLine {
@@ -54,6 +70,17 @@ export interface AccessibilityTextLine {
     FontWeight: number;
     FontSize: number;
 }
+/**
+ * The value of a range control (a slider, a progress bar): what a screen reader reads and adjusts (drawnui-cross 6c,
+ * C# AccessibilityValue): aria-valuenow / min / max, and aria-valuetext when Text is not empty ("65%", "20 – 80").
+ */
+export interface AccessibilityValue {
+    Now: number;
+    Min: number;
+    Max: number;
+    Step: number;
+    Text: string;
+}
 /** One entry of the accessibility snapshot (DrawnUi AccessibilityNode). Rect is CSS pixels relative to the canvas. */
 export interface AccessibilityNode {
     Id: number;
@@ -62,9 +89,13 @@ export interface AccessibilityNode {
     Role: string;
     Rect: SKRect;
     CanInteract: boolean;
+    /** A role a user operates (Aria.IsInteractiveRole) that cannot take input: aria-disabled, no tab stop. */
+    Disabled: boolean;
     IsPressed?: boolean;
     Live?: string;
     Source: SkiaControl;
+    /** A range control's value (aria-valuenow / min / max / valuetext); its name stays the app's label. */
+    Value?: AccessibilityValue;
     /** Real text lines rendered into the overlay so the browser can select / copy them (opt-in per control). */
     TextLines?: AccessibilityTextLine[];
 }
@@ -81,6 +112,7 @@ export declare class SkiaAccessibilityManager {
     private pending;
     private readonly changed;
     private readonly liveUpdated;
+    private readonly keyboardFocusRequested;
     /** Minimum milliseconds between snapshot rebuilds. */
     MinUpdateIntervalMs: number;
     Snapshot: AccessibilityNode[];
@@ -89,7 +121,54 @@ export declare class SkiaAccessibilityManager {
     OnChanged(cb: () => void): () => void;
     /** Fired immediately (bypassing the rate limit) when a live-region node's value changes. */
     OnLiveRegionUpdated(cb: (node: SkiaControl) => void): () => void;
+    /**
+     * Keyboard focus moved by the manager itself (arrow keys in a group): the overlay moves DOM focus to that node's
+     * element (C# KeyboardFocusRequested). Returns the unsubscribe function.
+     */
+    OnKeyboardFocusRequested(cb: (node: SkiaControl) => void): () => void;
     NotifyFocused(node?: SkiaControl): void;
+    /**
+     * Enter / Space from keyboard navigation or a screen reader: activates the node only while a tap could reach it
+     * (AccessibilityCanInteract), the rule every head applies.
+     */
+    static Activate(node?: SkiaControl): boolean;
+    /**
+     * Arrow keys, Home / End, PageUp / PageDown for the node in keyboard focus: the control gets them first, only while a
+     * pan could reach it (a slider steps its value); keys it does not use move keyboard focus between the items of the
+     * group around it (MoveInGroup). True when the key was used.
+     */
+    static Key(node: SkiaControl | undefined, key: InputKey): boolean;
+    /** Last focused node of each group: where Tab enters the group. */
+    private readonly groupFocus;
+    private groupRequest?;
+    /**
+     * The arrow-key group around `control`: its nearest ancestor with a composite role (Aria.IsCompositeRole, e.g.
+     * Aria.RoleList on a SkiaStack), and the item of that group holding the control (one of its children, a cell).
+     */
+    static TryFindGroup(control: SkiaControl): {
+        Group: SkiaControl;
+        Item: SkiaControl;
+    } | undefined;
+    /** Remembers where keyboard focus is inside its group, so the next Tab into the group lands there. */
+    private NoteFocus;
+    /**
+     * Whether Tab / Shift+Tab stop on this node. A group of items is one Tab stop, like a native list: its current item
+     * (the one keyboard focus last had there, else the group's first usable node) plus the controls inside that same
+     * item; the arrow keys move between items. Every node outside a group is a stop.
+     */
+    IsTabStop(node: SkiaControl): boolean;
+    /**
+     * Moves keyboard focus between the items of the group around `focused`, by item index like a native list: Down / Up in
+     * a Column, Right / Left in a Row, all four in a Wrap, a Grid or a Split layout (Up / Down by one row), Home / End to the
+     * first / last item, PageDown / PageUp by one viewport of the scroll around it. No wrap at the ends. The target is the
+     * item itself when it is an interactive node, else its first interactive node; items the pointer cannot use are
+     * skipped. An item not realized (recycled cells) is scrolled in with ScrollToIndex when the group is the scroll's
+     * content, and focused once drawn. True when the key belongs to the group.
+     */
+    MoveInGroup(focused: SkiaControl, key: InputKey): boolean;
+    /** Frame end: focus the requested item once it is drawn, skipping items that cannot take input. */
+    private ProcessGroupFocus;
+    private FocusFromKeyboard;
     Register(node: SkiaControl): void;
     NotifyUpdated(node: SkiaControl): void;
     ForceRebuildOnNextFrame(): void;
@@ -100,5 +179,6 @@ export declare class SkiaAccessibilityManager {
      * per MinUpdateIntervalMs otherwise (keeps rects in sync with scrolling); notifies only when the snapshot differs.
      */
     OnFrameEnd(scale: number, canvasWidthPx: number, canvasHeightPx: number, requestFrame: () => void): void;
+    private Rebuild;
     private static Same;
 }

package/dist/core/Accessibility.js

@@ -12,11 +12,33 @@ export const Aria = {
     RoleSeparator: "separator", RoleProgressBar: "progressbar", RoleTooltip: "tooltip", RoleDialog: "dialog",
     RoleAlertDialog: "alertdialog", RoleStatus: "status", RoleAlert: "alert", RoleGroup: "group", RoleRegion: "region",
     RoleNavigation: "navigation", RoleMain: "main",
+    // containers of items: with one of these roles a layout is an arrow-key group (IsCompositeRole)
+    RoleGrid: "grid", RoleToolbar: "toolbar", RoleRadioGroup: "radiogroup", RoleMenuBar: "menubar",
     /** Removes the control from the accessibility tree even when a default role would apply (inner label of a button). */
     RolePresentation: "presentation",
     // live regions
     LivePolite: "polite", LiveAssertive: "assertive",
+    /**
+     * Container roles whose items the arrow keys walk (C# Aria.IsCompositeRole): a layout with one of them is one Tab stop,
+     * its current item, and the arrow keys move between its items.
+     */
+    IsCompositeRole(role) {
+        return role === "list" || role === "listbox" || role === "grid" || role === "toolbar" || role === "radiogroup"
+            || role === "tablist" || role === "menu" || role === "menubar";
+    },
+    /**
+     * Roles a user operates (C# Aria.IsInteractiveRole, as DrawnUi.Rust is_control_role): a node with one of them that
+     * cannot take input is read as disabled (aria-disabled). C# also lists listbox and scrollbar; here a listbox is an
+     * arrow-key group and groups are never disabled.
+     */
+    IsInteractiveRole(role) {
+        return role === "button" || role === "link" || role === "checkbox" || role === "radio" || role === "switch"
+            || role === "slider" || role === "spinbutton" || role === "textbox" || role === "searchbox" || role === "combobox"
+            || role === "option" || role === "tab" || role === "menuitem" || role === "menuitemcheckbox" || role === "menuitemradio";
+    },
 };
+const asLayout = (c) => ("ChildrenFactory" in c && "Split" in c ? c : undefined);
+const asScroll = (c) => ("ScrollToIndex" in c && "ViewportOffsetY" in c ? c : undefined);
 /**
  * Mirrors DrawnUi SkiaAccessibilityManager: registry of accessible controls + a rate-limited snapshot
  * (at most one rebuild per MinUpdateIntervalMs, taken at frame end) that the DOM overlay renders.
@@ -30,6 +52,7 @@ export class SkiaAccessibilityManager {
     pending = 0;
     changed = new Set();
     liveUpdated = new Set();
+    keyboardFocusRequested = new Set();
     /** Minimum milliseconds between snapshot rebuilds. */
     MinUpdateIntervalMs = 1000;
     Snapshot = [];
@@ -38,8 +61,194 @@ export class SkiaAccessibilityManager {
     OnChanged(cb) { this.changed.add(cb); return () => this.changed.delete(cb); }
     /** Fired immediately (bypassing the rate limit) when a live-region node's value changes. */
     OnLiveRegionUpdated(cb) { this.liveUpdated.add(cb); return () => this.liveUpdated.delete(cb); }
-    NotifyFocused(node) { if (this.FocusedNode !== node)
-        this.FocusedNode = node; }
+    /**
+     * Keyboard focus moved by the manager itself (arrow keys in a group): the overlay moves DOM focus to that node's
+     * element (C# KeyboardFocusRequested). Returns the unsubscribe function.
+     */
+    OnKeyboardFocusRequested(cb) { this.keyboardFocusRequested.add(cb); return () => this.keyboardFocusRequested.delete(cb); }
+    NotifyFocused(node) {
+        if (this.FocusedNode === node)
+            return;
+        this.NoteFocus(node);
+        this.FocusedNode = node;
+    }
+    /**
+     * Enter / Space from keyboard navigation or a screen reader: activates the node only while a tap could reach it
+     * (AccessibilityCanInteract), the rule every head applies.
+     */
+    static Activate(node) {
+        if (!node || !node.AccessibilityCanInteract)
+            return false;
+        node.OnAccessibilityActivated();
+        node.Superview?.AccessibilityManager.ForceRebuildOnNextFrame(); // a screen reader reads the new state right back
+        return true;
+    }
+    /**
+     * Arrow keys, Home / End, PageUp / PageDown for the node in keyboard focus: the control gets them first, only while a
+     * pan could reach it (a slider steps its value); keys it does not use move keyboard focus between the items of the
+     * group around it (MoveInGroup). True when the key was used.
+     */
+    static Key(node, key) {
+        if (!node)
+            return false;
+        if (node.CanReceiveGesture("Panning") && node.OnAccessibilityKey(key)) {
+            node.Superview?.AccessibilityManager.ForceRebuildOnNextFrame(); // the new value is read right back, not a second later
+            return true;
+        }
+        return node.Superview?.AccessibilityManager.MoveInGroup(node, key) ?? false;
+    }
+    // ---- arrow-key groups (C# SkiaAccessibilityManager, "Arrow-key groups") ----
+    /** Last focused node of each group: where Tab enters the group. */
+    groupFocus = new WeakMap();
+    groupRequest;
+    /**
+     * The arrow-key group around `control`: its nearest ancestor with a composite role (Aria.IsCompositeRole, e.g.
+     * Aria.RoleList on a SkiaStack), and the item of that group holding the control (one of its children, a cell).
+     */
+    static TryFindGroup(control) {
+        for (let child = control, parent = control.Parent; parent; child = parent, parent = parent.Parent) {
+            if (Aria.IsCompositeRole(parent.AccessibilityRole))
+                return { Group: parent, Item: child };
+        }
+        return undefined;
+    }
+    /** Remembers where keyboard focus is inside its group, so the next Tab into the group lands there. */
+    NoteFocus(node) {
+        const found = node && SkiaAccessibilityManager.TryFindGroup(node);
+        if (found)
+            this.groupFocus.set(found.Group, node);
+    }
+    /**
+     * Whether Tab / Shift+Tab stop on this node. A group of items is one Tab stop, like a native list: its current item
+     * (the one keyboard focus last had there, else the group's first usable node) plus the controls inside that same
+     * item; the arrow keys move between items. Every node outside a group is a stop.
+     */
+    IsTabStop(node) {
+        const found = SkiaAccessibilityManager.TryFindGroup(node);
+        if (!found)
+            return true;
+        let stopItem;
+        const remembered = this.groupFocus.get(found.Group);
+        const current = remembered && !remembered.IsDisposed && remembered.AccessibilityCanInteract && this.Snapshot.some((n) => n.Source === remembered)
+            ? SkiaAccessibilityManager.TryFindGroup(remembered) : undefined;
+        if (current && current.Group === found.Group)
+            stopItem = current.Item;
+        else {
+            for (const n of this.Snapshot) {
+                if (!n.Source.AccessibilityCanInteract)
+                    continue;
+                const g = SkiaAccessibilityManager.TryFindGroup(n.Source);
+                if (g && g.Group === found.Group) {
+                    stopItem = g.Item;
+                    break;
+                }
+            }
+        }
+        return !stopItem || stopItem === found.Item;
+    }
+    /**
+     * Moves keyboard focus between the items of the group around `focused`, by item index like a native list: Down / Up in
+     * a Column, Right / Left in a Row, all four in a Wrap, a Grid or a Split layout (Up / Down by one row), Home / End to the
+     * first / last item, PageDown / PageUp by one viewport of the scroll around it. No wrap at the ends. The target is the
+     * item itself when it is an interactive node, else its first interactive node; items the pointer cannot use are
+     * skipped. An item not realized (recycled cells) is scrolled in with ScrollToIndex when the group is the scroll's
+     * content, and focused once drawn. True when the key belongs to the group.
+     */
+    MoveInGroup(focused, key) {
+        const found = SkiaAccessibilityManager.TryFindGroup(focused);
+        if (!found)
+            return false;
+        const { Group: group, Item: item } = found;
+        const scroll = FindScroll(group), axis = AxisOf(group), count = ItemCount(group);
+        const current = this.groupRequest?.Group === group ? this.groupRequest.Index : IndexOf(group, item);
+        if (current < 0 || count < 1)
+            return false;
+        const row = axis === "Both" ? RowLength(group) : 1;
+        const vertical = axis !== "Horizontal";
+        const page = () => PageSize(scroll, item, vertical) * row;
+        let target, step;
+        if ((key === "ArrowDown" && axis === "Vertical") || (key === "ArrowRight" && axis !== "Vertical")) {
+            target = current + 1;
+            step = 1;
+        }
+        else if ((key === "ArrowUp" && axis === "Vertical") || (key === "ArrowLeft" && axis !== "Vertical")) {
+            target = current - 1;
+            step = -1;
+        }
+        else if (key === "ArrowDown" && axis === "Both") {
+            target = Math.min(count - 1, current + row);
+            step = 1;
+        }
+        else if (key === "ArrowUp" && axis === "Both") {
+            target = Math.max(0, current - row);
+            step = -1;
+        }
+        else if (key === "Home") {
+            target = 0;
+            step = 1;
+        }
+        else if (key === "End") {
+            target = count - 1;
+            step = -1;
+        }
+        else if (key === "PageDown" && scroll) {
+            target = Math.min(count - 1, current + page());
+            step = 1;
+        }
+        else if (key === "PageUp" && scroll) {
+            target = Math.max(0, current - page());
+            step = -1;
+        }
+        else
+            return false;
+        if (target < 0 || target >= count || target === current)
+            return true; // at the end of the group nothing happens, the key still belongs to it
+        this.groupRequest = { Group: group, Scroll: scroll, Index: target, Step: step, Deadline: performance.now() + 3000, ScrollIssued: false };
+        group.Superview?.Update(); // resolved at the end of the next frame, together with the snapshot
+        return true;
+    }
+    /** Frame end: focus the requested item once it is drawn, skipping items that cannot take input. */
+    ProcessGroupFocus(scale, w, h, requestFrame) {
+        const request = this.groupRequest;
+        if (!request)
+            return;
+        const cell = ItemAt(request.Group, request.Index);
+        if (cell && IsDrawn(cell)) {
+            const node = FindTarget(cell);
+            if (node) {
+                this.groupRequest = undefined;
+                this.FocusFromKeyboard(node, scale, w, h);
+                return;
+            }
+            // this item cannot take input: go on to the next one in the same direction
+            request.Index += request.Step;
+            if (request.Index < 0 || request.Index >= ItemCount(request.Group)) {
+                this.groupRequest = undefined;
+                return;
+            }
+            request.Deadline = performance.now() + 3000;
+            request.ScrollIssued = false;
+        }
+        else if (performance.now() > request.Deadline || request.Group.IsDisposed) {
+            this.groupRequest = undefined;
+            return;
+        }
+        if (!request.ScrollIssued) {
+            request.ScrollIssued = true;
+            const next = ItemAt(request.Group, request.Index);
+            if ((!next || !IsDrawn(next)) && request.Scroll && request.Scroll.Content === request.Group) {
+                request.Scroll.ScrollToIndex(request.Index, true, request.Step > 0 ? "End" : "Start");
+            }
+        }
+        requestFrame(); // keep frames coming until the item is drawn
+    }
+    FocusFromKeyboard(node, scale, w, h) {
+        this.Rebuild(scale, w, h); // the overlay looks the node up in the snapshot: make sure it is there now
+        this.NoteFocus(node);
+        this.FocusedNode = node;
+        for (const cb of this.keyboardFocusRequested)
+            cb(node);
+    }
     Register(node) { this.nodes.add(node); this.dirty = true; }
     NotifyUpdated(node) {
         if (!this.nodes.has(node))
@@ -49,7 +258,7 @@ export class SkiaAccessibilityManager {
             for (const cb of this.liveUpdated)
                 cb(node);
     }
-    ForceRebuildOnNextFrame() { this.lastRebuild = 0; this.dirty = true; }
+    ForceRebuildOnNextFrame() { this.lastRebuild = -Infinity; this.dirty = true; }
     Unregister(node) {
         if (this.nodes.delete(node)) {
             node.OnAccessibilityUnregistered();
@@ -70,6 +279,7 @@ export class SkiaAccessibilityManager {
      * per MinUpdateIntervalMs otherwise (keeps rects in sync with scrolling); notifies only when the snapshot differs.
      */
     OnFrameEnd(scale, canvasWidthPx, canvasHeightPx, requestFrame) {
+        this.ProcessGroupFocus(scale, canvasWidthPx, canvasHeightPx, requestFrame);
         if (this.nodes.size === 0 && this.Snapshot.length === 0)
             return;
         const now = performance.now();
@@ -80,9 +290,12 @@ export class SkiaAccessibilityManager {
                 this.pending = window.setTimeout(() => { this.pending = 0; requestFrame(); }, wait);
             return;
         }
+        this.Rebuild(scale, canvasWidthPx, canvasHeightPx);
+    }
+    Rebuild(scale, canvasWidthPx, canvasHeightPx) {
         this.dirty = false;
-        this.lastRebuild = now;
-        const list = [];
+        this.lastRebuild = performance.now();
+        let list = [];
         for (const n of this.nodes) {
             if (!n.Superview) {
                 this.nodes.delete(n);
@@ -101,13 +314,30 @@ export class SkiaAccessibilityManager {
             if (px.Right < -canvasWidthPx || px.Bottom < -canvasHeightPx || px.Left > 2 * canvasWidthPx || px.Top > 2 * canvasHeightPx)
                 continue;
             list.push({
-                Id: n.AccessibilityId, Label: n.AccessibilityLabel, Hint: n.AccessibilityHint, Role: n.AccessibilityRole,
+                Id: n.AccessibilityId, Label: n.AccessibilityLabel, Hint: n.AccessibilityHint, Role: n.AccessibilityRole, Value: n.AccessibilityValue,
                 Rect: new SKRect(px.Left / scale, px.Top / scale, px.Right / scale, px.Bottom / scale),
                 CanInteract: n.AccessibilityCanInteract, IsPressed: n.AccessibilityIsPressed, Live: n.AccessibilityLive, Source: n,
+                Disabled: !n.AccessibilityCanInteract && Aria.IsInteractiveRole(n.AccessibilityRole),
                 TextLines: n.AccessibilityTextSelectable ? n.GetAccessibilityTextLines(scale) : undefined,
             });
         }
+        list = SayNamesOnce(list);
         list.sort((a, b) => a.Rect.Top - b.Rect.Top || a.Rect.Left - b.Rect.Left);
+        // reading order: nodes whose tops are within half the smaller height form one row, read left to right, so a row of
+        // vertically centered controls of different heights keeps its visual order (C# RectComparer + LeftComparer)
+        for (let start = 0, i = 1; i <= list.length; i++) {
+            if (i < list.length) {
+                const first = list[start].Rect, next = list[i].Rect;
+                if (next.Top - first.Top < Math.min(first.Height, next.Height) / 2)
+                    continue;
+            }
+            if (i - start > 1) {
+                const row = list.slice(start, i).sort((a, b) => a.Rect.Left - b.Rect.Left);
+                for (let k = 0; k < row.length; k++)
+                    list[start + k] = row[k];
+            }
+            start = i;
+        }
         if (SkiaAccessibilityManager.Same(list, this.Snapshot))
             return;
         this.Snapshot = list;
@@ -119,8 +349,8 @@ export class SkiaAccessibilityManager {
             return false;
         for (let i = 0; i < a.length; i++) {
             const x = a[i], y = b[i];
-            if (x.Source !== y.Source || x.Label !== y.Label || x.Hint !== y.Hint || x.Role !== y.Role || x.CanInteract !== y.CanInteract
-                || x.IsPressed !== y.IsPressed || x.Live !== y.Live
+            if (x.Source !== y.Source || x.Label !== y.Label || x.Hint !== y.Hint || x.Role !== y.Role || x.CanInteract !== y.CanInteract || x.Disabled !== y.Disabled
+                || x.IsPressed !== y.IsPressed || x.Live !== y.Live || !SameValue(x.Value, y.Value)
                 || Math.abs(x.Rect.Left - y.Rect.Left) > 0.5 || Math.abs(x.Rect.Top - y.Rect.Top) > 0.5
                 || Math.abs(x.Rect.Right - y.Rect.Right) > 0.5 || Math.abs(x.Rect.Bottom - y.Rect.Bottom) > 0.5)
                 return false;
@@ -138,6 +368,133 @@ export class SkiaAccessibilityManager {
         return true;
     }
 }
+/**
+ * Each name is said once in the flat overlay (DrawnUi.Rust said_by_child): a text or a heading whose label repeats the
+ * label of the node it is in (its nearest ancestor node) is said by one of them. Under an interactive node (a card
+ * button) the child is left out, the button keeps its name; under any other node (a group card and its title) the
+ * node loses its name and the heading says it. Selectable text (TextLines) always stays.
+ */
+function SayNamesOnce(list) {
+    const bySource = new Map(list.map((x) => [x.Source, x]));
+    const said = new Set();
+    for (const x of list) {
+        if (!x.Label || x.TextLines || (x.Role !== Aria.RoleText && x.Role !== Aria.RoleHeading))
+            continue;
+        let owner;
+        for (let p = x.Source.Parent; p && !owner; p = p.Parent)
+            owner = bySource.get(p);
+        if (!owner || owner.Label !== x.Label)
+            continue;
+        if (owner.CanInteract)
+            said.add(x);
+        else
+            owner.Label = undefined;
+    }
+    return said.size ? list.filter((x) => !said.has(x)) : list;
+}
+function SameValue(a, b) {
+    return a === b || (!!a && !!b && a.Now === b.Now && a.Min === b.Min && a.Max === b.Max && a.Step === b.Step && a.Text === b.Text);
+}
+// ---- group helpers (duck-typed layouts and scrolls) ----
+/** Children of a control (a layout's Views, a scroll's Content). */
+function ViewsOf(c) {
+    if ("Views" in c)
+        return c.Views;
+    const content = c.Content;
+    return content ? [content] : [];
+}
+function FindScroll(group) {
+    for (let p = group.Parent; p; p = p.Parent) {
+        const s = asScroll(p);
+        if (s)
+            return s;
+    }
+    return undefined;
+}
+/** Down / Up in a Column, Right / Left in a Row, all four in a Wrap, a Grid or a Split layout. */
+function AxisOf(group) {
+    const l = asLayout(group);
+    if (!l)
+        return "Vertical";
+    if (l.Type === "Column")
+        return l.Split <= 1 ? "Vertical" : "Both";
+    if (l.Type === "Row")
+        return "Horizontal";
+    if (l.Type === "Absolute")
+        return "Vertical";
+    return "Both";
+}
+/** Items per row of a 2D group: Split when set, else the items sharing the row of `item`. */
+/**
+ * Items per row of a 2D group: the Split, else the items on the row of the group's first item. C# counts the focused
+ * item's row, which the short last row of a wrap leaves short (Up from it skipped items); DrawnUi.Rust afef66f.
+ */
+function RowLength(group) {
+    const l = asLayout(group);
+    if (l && l.Split > 1)
+        return l.Split;
+    const first = ItemAt(group, 0) ?? FirstRealized(group);
+    if (!first)
+        return 1;
+    const top = first.GetAccessibilityPixelRect();
+    if (top.Height <= 0)
+        return 1;
+    const mid = (top.Top + top.Bottom) / 2;
+    let count = 0;
+    for (const child of ViewsOf(group)) {
+        const r = child.GetAccessibilityPixelRect();
+        if (r.Height > 0 && Math.abs((r.Top + r.Bottom) / 2 - mid) < top.Height / 2)
+            count++;
+    }
+    return Math.max(1, count);
+}
+function ItemCount(group) {
+    const l = asLayout(group);
+    return l?.IsTemplated ? l.ItemsSource?.length ?? 0 : ViewsOf(group).length;
+}
+function IndexOf(group, item) {
+    const l = asLayout(group);
+    return l?.IsTemplated ? item.ContextIndex : ViewsOf(group).indexOf(item);
+}
+/** The view of an item: the realized cell of a templated layout (none when its cell is not in use), else the child. */
+function ItemAt(group, index) {
+    const l = asLayout(group);
+    if (l?.IsTemplated) {
+        const v = l.ChildrenFactory.GetViewForIndex(index);
+        return v && v.ContextIndex === index ? v : undefined;
+    }
+    return index >= 0 && index < ViewsOf(group).length ? ViewsOf(group)[index] : undefined;
+}
+/** The realized item with the lowest index (item 0 of a scrolled recycled group may not be realized). */
+function FirstRealized(group) {
+    let best;
+    for (const v of ViewsOf(group))
+        if (!best || IndexOf(group, v) < IndexOf(group, best))
+            best = v;
+    return best;
+}
+/** Arranged on the canvas: realized and laid out (a templated layout keeps only the cells it draws in use). */
+function IsDrawn(control) {
+    const r = control.GetAccessibilityPixelRect();
+    return !!control.Superview && r.Width > 0 && r.Height > 0;
+}
+/** Items per viewport of the scroll around the group. */
+function PageSize(scroll, item, vertical) {
+    const v = scroll.DrawingRect, size = item.MeasuredSize.Pixels;
+    const viewport = vertical ? v.Height : v.Width, s = vertical ? size.Height : size.Width;
+    return s > 0 ? Math.max(1, Math.floor(viewport / s)) : 1;
+}
+/** The item itself when it is an interactive node, else its first interactive node in tree order. */
+function FindTarget(item) {
+    if (item.IsAccessibilityElement && item.AccessibilityCanInteract)
+        return item;
+    for (const child of ViewsOf(item)) {
+        const found = FindTarget(child);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
 /** True when any ancestor is hidden (IsVisible false or Opacity 0): the subtree is not drawn, so it gets no nodes. */
 function AccessibilityManagerHiddenByAncestor(control) {
     let p = control.Parent;

package/dist/core/Animators.d.ts

@@ -18,17 +18,43 @@ export declare class AnimatorBase {
     StartFrameTimeNanos: number;
     OnStart?: () => void;
     OnStop?: () => void;
+    /** Paused: the canvas does not tick it and it wakes no frames; Resume goes on from where it was (C# Pause / Resume). */
+    IsPaused: boolean;
+    /** Paused by the canvas because its control is hidden; resumed when it shows again. */
+    PausedWhileHidden: boolean;
+    /**
+     * 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: number;
     private delayHandle;
+    private delayEnd;
+    private delayLeft;
+    private pausedAt;
     constructor(parent: SkiaControl);
     protected Register(): boolean;
     protected Unregister(): void;
     Start(delayMs?: number): void;
+    /** Freezes the run (and what is left of a start delay); Resume goes on from there. */
+    Pause(): void;
+    /** Goes on from where Pause froze it: the paused time is not counted. */
+    Resume(): void;
     Stop(): void;
     /** Returns true when there is nothing more to do (not running / finished). */
     TickFrame(frameTimeNanos: number): boolean;
     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;
@@ -46,10 +72,20 @@ export declare class SkiaValueAnimator extends AnimatorBase {
     TickFrame(frameTimeNanos: number): boolean;
     /** Passed over mValue; subclasses derive their own reported value here. */
     protected TransformReportedValue(_deltaT: number): number;
-    /** 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.
+     */
     protected UpdateValue(_deltaT: number, deltaFromStart: number): boolean;
     protected FinishedRunning(): boolean;
 }
+/** DrawnUi PingPongAnimator: every repeat runs the other way (Repeat -1 = forever by default). */
+export declare class PingPongAnimator extends SkiaValueAnimator {
+    /** One way done, the next starts (C# CycleFInished). */
+    CycleFinished?: () => void;
+    constructor(parent: SkiaControl);
+    protected FinishedRunning(): boolean;
+}
 /** DrawnUi RenderingAnimator: a value animator that paints itself above its Parent (IOverlayEffect). */
 export declare class RenderingAnimator extends SkiaValueAnimator implements IOverlayEffect {
     constructor(parent: SkiaControl);