@vectojs/core 1.39.0 → 1.40.0

package/dist/components/VirtualizedSetAggregate.d.ts

@@ -0,0 +1,110 @@
+import { Entity, type A11yAttributes } from '../tree/Entity';
+import type { IRenderer } from '../renderer/IRenderer';
+/**
+ * One item in a {@link VirtualizedSetAggregate}: the stable identity and the
+ * accessible name a hotspot announces for it.
+ */
+export interface VirtualizedSetItem {
+    /** Stable identity across re-binds; survives reordering and filtering. */
+    id: string;
+    /** Accessible name announced for the item. */
+    label: string;
+}
+export interface VirtualizedSetAggregateOptions {
+    /** Full item set; the container label always states this count. Default `[]`. */
+    items?: VirtualizedSetItem[];
+    /** Container name; the count is appended (`'Messages, 10000 items'`). */
+    label?: string;
+    /** Container role. Default `'list'` (owns `listitem` per `A11Y_REQUIRED_OWNED`). */
+    role?: string;
+    /** Hotspot role. Default `'listitem'`. */
+    itemRole?: string;
+    /** Row height in local px; hotspots stack vertically at this stride. Default `28`. */
+    rowHeight?: number;
+    /** Hotspot pool size. Default: enough slots to cover `height`, at least 1. */
+    visibleCapacity?: number;
+    /** Container width in local px. Default `0` (set it — a zero box never projects). */
+    width?: number;
+    /** Container height in local px. Default `0`. */
+    height?: number;
+    /** Called when an item is activated (Enter/Space/click-through). */
+    onActivate?: (item: VirtualizedSetItem, index: number) => void;
+}
+/**
+ * Aggregate semantics for a virtualized set (RFC3 §4.4, CTX-0599).
+ *
+ * One persistent container (`role` + `aria-label` with the count) plus roving
+ * focus plus a small pool of hotspot entities re-bound to whichever items
+ * currently occupy each visible slot — O(viewport) DOM nodes for an
+ * arbitrarily large dataset. The pattern is the `Tree`/`Table` hotspot
+ * precedent (`packages/ui/src/Tree.ts:98-113`, `packages/table/src/Table.ts`):
+ * a transparent, focusable child per visible row with a roving `tabIndex` and
+ * `pointerEvents: 'none'`, while the parent owns the keyboard model and the
+ * pool.
+ *
+ * Pointer ownership: neither the container nor the hotspots take the pointer
+ * (both project `pointer-events: none`), so a real click/drag reaches the
+ * owner's canvas handling or an underlying selectable-text mirror underneath.
+ * Keyboard focus and AT-synthesized `click` still work — the same contract the
+ * `Tree`/`Table` hotspots rely on. A mouse/touch owner forwards its own tap
+ * path into {@link activateItem}; `'onDemand'` alone is deliberately not the
+ * story here (also `content/reference/core-a11y.md:207-214`).
+ *
+ * Painting belongs to the owner: `render` is a no-op (like `RowHotspot`), so
+ * pair this with canvas-painted rows or subclass and override `render`.
+ */
+export declare class VirtualizedSetAggregate extends Entity {
+    private _items;
+    private _label;
+    private _role;
+    private _itemRole;
+    private _rowHeight;
+    private _visibleCapacity;
+    private _onActivate;
+    /** First item index currently bound to the pool (the scroll window). */
+    private _visibleStart;
+    /** Item id owning the roving tab stop / keyboard focus. */
+    private _activeId;
+    private _selectedId;
+    /** One focusable hotspot per visible slot; re-bound, never rebuilt per item. */
+    private _hotspots;
+    constructor(opts?: VirtualizedSetAggregateOptions);
+    /** Full item count — the number the container label states. */
+    get itemCount(): number;
+    /** Live pool size (bounded by the visible capacity, never by the item count). */
+    get poolSize(): number;
+    /** First item index currently bound to the pool. */
+    get visibleStart(): number;
+    getA11yAttributes(): A11yAttributes;
+    render(_renderer: IRenderer): void;
+    /** Axis-aligned hit-test against the container box (the `UIComponent` default). */
+    isPointInside(globalX: number, globalY: number): boolean;
+    /** Replace the item set; the pool re-binds and the label count follows. */
+    setItems(items: VirtualizedSetItem[]): void;
+    /** Move the pool window to start at `start` (the scroll position). */
+    setVisibleStart(start: number): void;
+    /**
+     * Keep one hotspot per visible slot, positioned over it. The pool is sized
+     * to the viewport (capacity), each slot re-bound to whatever item currently
+     * occupies it — the `Tree._syncHotspots` shape, minus tree structure.
+     */
+    private _syncHotspots;
+    /** Whether `id` owns the roving tab stop: active, else selected, else first. */
+    isTabStop(id: string): boolean;
+    isSelected(id: string): boolean;
+    /** Item role the hotspots announce (kept on the parent: one source of truth). */
+    get itemRole(): string;
+    /** Activate an item (pointer tap-through or Enter/Space): selects and notifies. */
+    activateItem(id: string, focusIt?: boolean): void;
+    /** Move keyboard focus to the hotspot currently bound to `id`, if any. */
+    focusItem(id: string): void;
+    /**
+     * Aggregate keyboard model: Up/Down move the active item (scrolling the pool
+     * window so it stays bound), Home/End jump, Enter/Space activate. The active
+     * item is focused as it moves so focus is never stranded on a re-bound slot.
+     */
+    handleItemKey(e: KeyboardEvent, id: string): void;
+    /** Scroll the pool window just enough to keep `index` bound. */
+    private _ensureVisible;
+    update(_dt: number, _time: number): void;
+}

package/dist/index.d.ts

@@ -10,7 +10,12 @@ export * from './renderer/TextRasterCache';
 export * from './performance/UserTiming';
 export * from './tree/Entity';
 export * from './tree/Scene';
+export * from './tree/scene/HitResult';
+export * from './tree/scene/ProjectionBackend';
+export * from './tree/scene/ProjectionPolicy';
+export * from './tree/scene/SemanticProjectionPolicy';
 export * from './components/TextEntity';
+export * from './components/VirtualizedSetAggregate';
 export * from './components/GridTextEntity';
 export * from './components/SplineEntity';
 export * from './components/Rect';