@vectojs/core 0.1.0 → 0.2.0

package/dist/Entity-D-rfAFCf.d.ts

@@ -1,572 +0,0 @@
-/**
- * Renderer abstraction consumed by every {@link Entity}.
- *
- * Implementations wrap a concrete drawing backend (Canvas 2D, WebGL, …) and
- * expose a path-based drawing API.  Entities must only depend on `IRenderer`
- * so they remain backend-agnostic.
- *
- * @example
- * // Inside an Entity.render() implementation:
- * render(r: IRenderer) {
- *   r.beginPath();
- *   r.fill('#38bdf8');
- * }
- */
-interface IRenderer {
-    /** Clear the entire drawing surface to transparent / background color. */
-    clear(): void;
-    /** Push the current transform + state onto the renderer's stack. */
-    save(): void;
-    /** Pop the last saved transform + state from the renderer's stack. */
-    restore(): void;
-    /**
-     * Apply a translation to the current transform matrix.
-     *
-     * @param x - Horizontal offset in pixels.
-     * @param y - Vertical offset in pixels.
-     */
-    translate(x: number, y: number): void;
-    /**
-     * Apply a scale to the current transform matrix.
-     *
-     * @param x - Horizontal scale factor.
-     * @param y - Vertical scale factor.
-     */
-    scale(x: number, y: number): void;
-    /**
-     * Apply a clockwise rotation to the current transform matrix.
-     *
-     * @param angle - Rotation angle in radians.
-     */
-    rotate(angle: number): void;
-    /**
-     * Set the global opacity applied to all subsequent draw calls.
-     *
-     * @param alpha - Opacity in the range `[0, 1]`.
-     */
-    setGlobalAlpha(alpha: number): void;
-    /**
-     * Intersect the current clip region with a rectangle. Affects all subsequent
-     * draws until the next {@link restore}; wrap in {@link save}/{@link restore}.
-     *
-     * @param x - Left edge.
-     * @param y - Top edge.
-     * @param width - Rectangle width.
-     * @param height - Rectangle height.
-     */
-    clip(x: number, y: number, width: number, height: number): void;
-    /** Begin a new sub-path, discarding the current path. */
-    beginPath(): void;
-    /**
-     * Move the pen to the given point without drawing a line.
-     *
-     * @param x - Target X coordinate.
-     * @param y - Target Y coordinate.
-     */
-    moveTo(x: number, y: number): void;
-    /**
-     * Add a straight line segment from the current pen position to the given point.
-     *
-     * @param x - Target X coordinate.
-     * @param y - Target Y coordinate.
-     */
-    lineTo(x: number, y: number): void;
-    /**
-     * Add a cubic Bézier curve to the current path.
-     *
-     * @param cp1x - X of the first control point.
-     * @param cp1y - Y of the first control point.
-     * @param cp2x - X of the second control point.
-     * @param cp2y - Y of the second control point.
-     * @param x - X of the end point.
-     * @param y - Y of the end point.
-     */
-    bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
-    /** Close the current sub-path by drawing a line back to its starting point. */
-    closePath(): void;
-    /**
-     * Add a circular arc to the current path.
-     *
-     * @param x - X of the arc center.
-     * @param y - Y of the arc center.
-     * @param radius - Arc radius in pixels.
-     * @param startAngle - Start angle in radians (0 = 3 o'clock).
-     * @param endAngle - End angle in radians.
-     * @param counterclockwise - If `true`, draws the arc counter-clockwise.
-     */
-    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
-    /**
-     * Add a rounded rectangle to the current path.
-     *
-     * @param x - Left edge.
-     * @param y - Top edge.
-     * @param width - Rectangle width.
-     * @param height - Rectangle height.
-     * @param radii - Corner radius (uniform) or per-corner array as accepted by `CanvasRenderingContext2D.roundRect()`.
-     */
-    roundRect(x: number, y: number, width: number, height: number, radii: number | number[]): void;
-    /**
-     * Draw an image or video frame into the canvas.
-     *
-     * @param source - The image source (HTMLImageElement, HTMLVideoElement, HTMLCanvasElement, etc.).
-     * @param dx - Destination X.
-     * @param dy - Destination Y.
-     * @param dw - Destination width.
-     * @param dh - Destination height.
-     */
-    drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
-    /**
-     * Fill the current path with the given color or gradient.
-     *
-     * @param colorOrGradient - CSS color string or a gradient object.
-     */
-    fill(colorOrGradient: string | any): void;
-    /**
-     * Stroke the current path with the given color or gradient.
-     *
-     * @param colorOrGradient - CSS color string or a gradient object.
-     * @param lineWidth - Stroke width in pixels (default: `1`).
-     */
-    stroke(colorOrGradient: string | any, lineWidth?: number): void;
-    /**
-     * Render a text string at the given position.
-     *
-     * @param text - The string to draw.
-     * @param x - Left edge of the text baseline.
-     * @param y - Baseline Y coordinate.
-     * @param font - CSS font shorthand, e.g. `'16px monospace'`.
-     * @param color - CSS color string or gradient.
-     */
-    fillText(text: string, x: number, y: number, font: string, color: string | any): void;
-    /**
-     * Draw a filled circle through the order-preserving batch.
-     *
-     * Consecutive calls sharing the same `color` and `alpha` are coalesced into a
-     * single path and committed with one `fill()` on {@link flush} (or when the
-     * style changes / another draw call intervenes). Coordinates are in the
-     * current transform space. This collapses the per-entity
-     * `beginPath`/`arc`/`fill` of large point clouds into a handful of draw calls
-     * while preserving painter's-order semantics.
-     *
-     * @param cx - Center X in the current transform space.
-     * @param cy - Center Y in the current transform space.
-     * @param radius - Circle radius.
-     * @param color - CSS color string.
-     * @param alpha - Opacity in `[0, 1]` (default `1`).
-     */
-    fillCircle(cx: number, cy: number, radius: number, color: string, alpha?: number): void;
-    /**
-     * Commit any pending batched draws (see {@link fillCircle}). Safe to call when
-     * no batch is active (no-op). The {@link Scene} flushes at the end of each
-     * sibling group and frame.
-     */
-    flush(): void;
-    /**
-     * Create a linear gradient between two points with the given color stops.
-     *
-     * @param x0 - X of the gradient start point.
-     * @param y0 - Y of the gradient start point.
-     * @param x1 - X of the gradient end point.
-     * @param y1 - Y of the gradient end point.
-     * @param colorStops - Array of `{ stop, color }` pairs where `stop` is in `[0, 1]`.
-     * @returns An opaque gradient object suitable for {@link fill} or {@link stroke}.
-     */
-    createLinearGradient(x0: number, y0: number, x1: number, y1: number, colorStops: {
-        stop: number;
-        color: string;
-    }[]): any;
-}
-
-/**
- * A 2-D coordinate in canvas/world space.
- */
-interface Point {
-    x: number;
-    y: number;
-}
-/**
- * An axis-aligned bounding box in an entity's local coordinate space.
- *
- * Returned from {@link Entity.getBounds} to enable viewport culling.
- */
-interface Bounds {
-    x: number;
-    y: number;
-    width: number;
-    height: number;
-}
-/**
- * Describes an entity that renders as a single filled circle at its local
- * origin, returned from {@link Entity.getBatchCircle} to opt into the renderer's
- * draw-call batching fast-path.
- */
-interface BatchCircle {
-    /** Circle radius in the entity's local space. */
-    radius: number;
-    /** CSS fill color. */
-    color: string;
-}
-/**
- * Describes an entity that renders as a single filled rectangle from its local
- * origin, returned from {@link Entity.getBatchRect} to opt into the GPU
- * instanced-rectangle fast-path (WebGL `pointBackend` only).
- */
-interface BatchRect {
-    /** Rectangle width in the entity's local space. */
-    width: number;
-    /** Rectangle height in the entity's local space. */
-    height: number;
-    /** CSS fill color. */
-    color: string;
-}
-/**
- * Semantic attributes an {@link Entity} can project into the accessibility /
- * automation shadow layer maintained by {@link Scene}.
- *
- * Returned from {@link Entity.getA11yAttributes}; consumed by `Scene.syncA11y`
- * to create and label the shadow DOM node (e.g. a real `<button>` or `<a href>`)
- * so the canvas stays accessible and clickable by automation/agents.
- */
-interface A11yAttributes {
-    /** Shadow element tag to create. Defaults to `'div'`. */
-    tag?: 'div' | 'a' | 'button' | 'img' | 'input' | 'textarea';
-    /** ARIA role applied via the `role` attribute. */
-    role?: string;
-    /** Accessible name applied via `aria-label`. */
-    label?: string;
-    /** Destination URL; only meaningful for `tag: 'a'`. */
-    href?: string;
-    /** Image source; only meaningful for `tag: 'img'`. */
-    src?: string;
-    /** Alternative text; only meaningful for `tag: 'img'`. */
-    alt?: string;
-    /** Input type (e.g. `'text'`, `'checkbox'`); only meaningful for `tag: 'input'`. */
-    inputType?: string;
-    /** Placeholder text; only meaningful for `tag: 'input'`. */
-    placeholder?: string;
-    /** Current value; refreshed each frame for `tag: 'input'` (text fields). */
-    value?: string;
-    /**
-     * Checked state — sets `input.checked` for checkbox inputs and `aria-checked`
-     * for `role: 'switch'`/`'checkbox'`. Refreshed each frame.
-     */
-    checked?: boolean;
-    disabled?: boolean;
-    expanded?: boolean;
-    controls?: string;
-    haspopup?: string;
-    selected?: boolean;
-    activedescendant?: string;
-    valuemin?: string;
-    valuemax?: string;
-}
-/**
- * Union of all pointer/interaction events that can be emitted by an {@link Entity}.
- */
-type VectoEvent = 'click' | 'hover' | 'pointerdown' | 'pointerup' | 'pointermove' | 'pointerleave' | 'change' | 'focus' | 'blur' | 'wheel' | 'keydown' | 'keyup';
-/** Options for {@link Entity.on} / {@link Entity.off}. */
-interface ListenerOptions {
-    /** Register the listener for the capture phase (root→target) instead of bubble. */
-    capture?: boolean;
-}
-/**
- * A propagating event dispatched through the entity tree by
- * {@link Entity.dispatchEvent} (DOM-like capture + bubble).
- *
- * It wraps the originating browser event (`nativeEvent`) and adds tree-aware
- * fields: `target` (where it originated), `currentTarget` (the node currently
- * handling it), and `stopPropagation()`. Common native fields (`deltaY`,
- * `clientX`, `key`, …) and `preventDefault()` pass through to `nativeEvent`, so
- * handlers written against the raw DOM event keep working.
- */
-declare class VectoJSEvent<N = unknown> {
-    /** The event name. */
-    readonly type: VectoEvent;
-    /** The entity the event originated on. */
-    readonly target: Entity;
-    /** The entity whose listeners are currently running (updated per node). */
-    currentTarget: Entity;
-    /** The wrapped browser event, if any. */
-    readonly nativeEvent: N | undefined;
-    /** Whether the event bubbles past its target (capture always runs). */
-    readonly bubbles: boolean;
-    private stopped;
-    private stoppedImmediate;
-    constructor(type: VectoEvent, target: Entity, nativeEvent?: N, bubbles?: boolean);
-    /** Stop the event from reaching the next node in the propagation path. */
-    stopPropagation(): void;
-    /** Stop propagation AND skip any remaining listeners on the current node. */
-    stopImmediatePropagation(): void;
-    /** Forward to the native event's `preventDefault` (e.g. stop page scroll). */
-    preventDefault(): void;
-    /** Whether {@link stopPropagation} has been called. */
-    get propagationStopped(): boolean;
-    /** Whether {@link stopImmediatePropagation} has been called. */
-    get immediatePropagationStopped(): boolean;
-    /** Whether the native event's default action was prevented. */
-    get defaultPrevented(): boolean;
-    /** Native horizontal wheel delta, if this wraps a `WheelEvent`. */
-    get deltaX(): number | undefined;
-    /** Native vertical wheel delta, if this wraps a `WheelEvent`. */
-    get deltaY(): number | undefined;
-    /** Native pointer X, if this wraps a pointer/mouse event. */
-    get clientX(): number | undefined;
-    /** Native pointer Y, if this wraps a pointer/mouse event. */
-    get clientY(): number | undefined;
-    /** Native key, if this wraps a keyboard event. */
-    get key(): string | undefined;
-}
-/**
- * Base class for every node in the Virtual Math Tree (VMT).
- *
- * Subclass `Entity` and implement {@link isPointInside} and {@link render} to
- * create custom drawable objects.  Entities form a scene-graph: each node may
- * own child entities, inheriting the parent's transform.
- *
- * @example
- * class CircleEntity extends Entity {
- *   isPointInside(x: number, y: number) {
- *     return Math.hypot(x - this.x, y - this.y) < 50;
- *   }
- *   render(r: IRenderer) {
- *     r.beginPath();
- *     r.fill('#38bdf8');
- *   }
- * }
- */
-declare abstract class Entity {
-    id: string;
-    children: Entity[];
-    parent: Entity | null;
-    /**
-     * Walk up the parent chain to find the scene this entity is currently attached to.
-     */
-    get scene(): any;
-    x: number;
-    y: number;
-    scaleX: number;
-    scaleY: number;
-    rotation: number;
-    opacity: number;
-    isDOMPortal: boolean;
-    private _interactive;
-    get interactive(): boolean;
-    set interactive(val: boolean);
-    width: number;
-    height: number;
-    a11yOffsetX: number;
-    a11yOffsetY: number;
-    /**
-     * Opt in to a viewport-filling accessibility/automation shadow node even when
-     * this entity has no intrinsic box (`width`/`height` of `0`). Use for
-     * full-screen, boundless interaction surfaces (e.g. an infinite-canvas graph)
-     * that need global pointer events. The node is mounted behind all other shadow
-     * nodes, so on-top components stay clickable.
-     */
-    a11yFullViewport: boolean;
-    /**
-     * Clip this node's children to its local box (`[0,0]–[width,height]`) while
-     * rendering. Combined with translating a content child, this is how
-     * scroll/overflow containers (e.g. `ScrollView`) keep their content inside a
-     * fixed viewport. Off by default (children render unclipped). Canvas2D only.
-     */
-    clipChildren: boolean;
-    protected listeners: Map<VectoEvent, Array<(e: any) => void>>;
-    /** Capture-phase listeners (fired root→target before bubble). */
-    protected captureListeners: Map<VectoEvent, Array<(e: any) => void>>;
-    private animations;
-    constructor(id?: string);
-    /**
-     * Append a child entity to this node's children array.
-     *
-     * @param child - The entity to add as a child.
-     * @returns `this` for method chaining.
-     */
-    add(child: Entity): this;
-    /**
-     * Remove a child entity from this node.
-     *
-     * @param child - The entity to remove.
-     * @returns `this` for method chaining.
-     */
-    remove(child: Entity): this;
-    /**
-     * Set the local position of this entity.
-     *
-     * @param x - Horizontal position in local space.
-     * @param y - Vertical position in local space.
-     * @returns `this` for method chaining.
-     * @example entity.setPosition(100, 200);
-     */
-    setPosition(x: number, y: number): this;
-    /**
-     * Queue a tween animation toward the specified target property values.
-     *
-     * Multiple calls chain animations sequentially.  Only numeric properties
-     * are interpolated; non-numeric values are ignored.
-     *
-     * @param targetProps - Partial set of numeric properties to tween to.
-     * @param durationMs - Duration of the tween in milliseconds.
-     * @returns `this` for method chaining.
-     * @example entity.animate({ x: 400, opacity: 0 }, 500);
-     */
-    animate(targetProps: Partial<this>, durationMs: number): this;
-    /**
-     * Advance the entity's internal state for one frame.
-     *
-     * Called automatically by the {@link Scene} render loop — override in
-     * subclasses to implement custom per-frame logic.
-     *
-     * @param dt - Elapsed time since the last frame in milliseconds.
-     * @param time - Absolute timestamp from `performance.now()`.
-     */
-    update(_dt: number, time: number): void;
-    /**
-     * Register a listener for a {@link VectoEvent}.
-     *
-     * Listeners run in the bubble phase by default; pass `{ capture: true }` for the
-     * capture phase (root→target). Bubble listeners also fire for the legacy
-     * {@link emit} (direct, self-only) path.
-     *
-     * @param event - The event name to listen for.
-     * @param callback - Handler invoked when the event fires.
-     * @param options - `{ capture }` to register for the capture phase.
-     * @returns `this` for method chaining.
-     * @example entity.on('click', (e) => console.log('clicked', e));
-     */
-    on(event: VectoEvent, callback: (e: any) => void, options?: ListenerOptions): this;
-    /**
-     * Remove a previously registered event listener.
-     *
-     * @param event - The event name to stop listening to.
-     * @param callback - The exact handler reference passed to {@link on}.
-     * @param options - Must match the phase the listener was registered with.
-     * @returns `this` for method chaining.
-     */
-    off(event: VectoEvent, callback: (e: any) => void, options?: ListenerOptions): this;
-    /**
-     * Tear down this entity: clear all animations, event listeners, and detach
-     * from parent. Call before discarding an entity to prevent memory leaks.
-     */
-    destroy(): void;
-    /**
-     * Dispatch a {@link VectoEvent} directly to this entity's bubble-phase listeners
-     * only — no tree propagation. Kept for component-internal/self events (e.g. a
-     * form control emitting its own `change`); use {@link dispatchEvent} for the
-     * capture/bubble path.
-     *
-     * @param event - The event name to dispatch.
-     * @param payload - Arbitrary data forwarded to each listener.
-     */
-    emit(event: VectoEvent, payload: any): void;
-    /** Run one node's listeners for the event, honoring stopImmediatePropagation. */
-    private fireListeners;
-    /**
-     * Dispatch a {@link VectoJSEvent} through the entity tree, DOM-style: a capture
-     * phase from the root down to `event.target`, then a bubble phase back up to the
-     * root. `event.stopPropagation()` halts the walk; `stopImmediatePropagation()`
-     * also skips the remaining listeners on the current node. A non-bubbling event
-     * only fires its target in the bubble phase (capture still runs).
-     *
-     * @param event - The event to propagate (its `target` defines the path).
-     */
-    dispatchEvent(event: VectoJSEvent): void;
-    /**
-     * Compute the entity's position in world/canvas space by accumulating
-     * local offsets up the scene-graph hierarchy using affine transformations (scale and rotation).
-     *
-     * @returns World-space {@link Point} for this entity.
-     */
-    getGlobalPosition(): Point;
-    /**
-     * Accumulated world scale factors: this entity's own `scaleX`/`scaleY` times
-     * those of every ancestor (excluding the scene root). Useful for mapping a
-     * world-space point back into local space for hit-testing.
-     *
-     * @returns The world scale `{ x, y }`.
-     */
-    getWorldScale(): {
-        x: number;
-        y: number;
-    };
-    /**
-     * Accumulated world rotation: this entity's own `rotation` plus
-     * that of every ancestor (excluding the scene root).
-     *
-     * @returns The accumulated world rotation in radians.
-     */
-    getWorldRotation(): number;
-    /**
-     * Return `true` when the given world-space point lies within this entity's
-     * interactive hit area.
-     *
-     * @param globalX - World-space X coordinate.
-     * @param globalY - World-space Y coordinate.
-     * @returns Whether the point is inside this entity.
-     */
-    /**
-     * Describe this entity's semantics for the accessibility / automation shadow
-     * layer. Override in components to project a real `<button>`, `<a href>`, etc.
-     *
-     * The default returns `{}`, which `Scene.syncA11y` maps to a plain `div`
-     * (preserving the historical behavior of interactive entities).
-     *
-     * @returns The {@link A11yAttributes} for this entity's shadow node.
-     */
-    getA11yAttributes(): A11yAttributes;
-    /**
-     * Local-space axis-aligned bounding box of what this entity's {@link render}
-     * draws, used by {@link Scene} for viewport culling.
-     *
-     * Returns `null` by default, meaning "unknown bounds" — the entity is then
-     * never culled (always rendered). Override to return a {@link Bounds} so the
-     * scene can skip rendering it when it lies outside the viewport.
-     *
-     * @returns The local bounds, or `null` to opt out of culling.
-     */
-    getBounds(): Bounds | null;
-    /**
-     * Opt into the renderer's draw-call batching fast-path for point-cloud /
-     * particle entities that draw as a single filled circle at their local origin.
-     *
-     * When a leaf entity returns a {@link BatchCircle} and has uniform scale, the
-     * {@link Scene} skips its per-entity `save`/`translate`/`scale`/`rotate`/
-     * `restore` and {@link render}, emitting the circle through
-     * {@link IRenderer.fillCircle} so runs of same-color siblings coalesce into a
-     * single `fill()`. Returns `null` by default (normal render path). Read each
-     * frame, so an animated color/radius is honored.
-     *
-     * @returns The circle to batch, or `null` to use the normal {@link render} path.
-     */
-    getBatchCircle(): BatchCircle | null;
-    /**
-     * Opt into the GPU instanced-rectangle fast-path for a leaf entity that draws
-     * as a single filled rectangle from its local origin. Only used when the
-     * {@link Scene} runs a WebGL `pointBackend`; otherwise the entity renders
-     * normally via {@link render}. Returns `null` by default. Read each frame.
-     *
-     * @returns The rectangle to batch, or `null` for the normal render path.
-     */
-    getBatchRect(): BatchRect | null;
-    /**
-     * Whether this entity still has a queued/running tween animation.
-     *
-     * Used by {@link Scene}'s `onDemand` render mode to keep redrawing while an
-     * animation is in flight.
-     *
-     * @returns `true` if at least one animation remains.
-     */
-    hasPendingAnimations(): boolean;
-    abstract isPointInside(globalX: number, globalY: number): boolean;
-    /**
-     * Draw this entity using the provided renderer.
-     *
-     * Called each frame after the entity's transform has been pushed onto the
-     * renderer's matrix stack.
-     *
-     * @param renderer - The active renderer instance.
-     */
-    abstract render(renderer: any): void;
-}
-
-export { type A11yAttributes as A, type Bounds as B, Entity as E, type IRenderer as I, type ListenerOptions as L, type Point as P, type VectoEvent as V, type BatchCircle as a, type BatchRect as b, VectoJSEvent as c };