flocc 0.5.21 → 0.5.23

package/dist/helpers/Rule.d.ts

@@ -3,6 +3,23 @@ import { Agent } from "../agents/Agent";
 declare type StepToken = number | string | Step;
 interface Step extends Array<StepToken> {
 }
+interface RuleDiagnostic {
+    path: string;
+    level: "error" | "warning";
+    message: string;
+}
+interface RuleFormatOptions {
+    indent?: string;
+    maxLineWidth?: number;
+}
+/**
+ * Operator info: maps operator names to their expected argument counts.
+ * `min` and `max` define the valid range. If `max` is Infinity, the operator is variadic.
+ */
+interface OperatorArity {
+    min: number;
+    max: number;
+}
 /**
  * The `Rule` class is an experimental interface for adding behavior to {@linkcode Agent}s. A `Rule` object may be used in place of a `tick` function to be added as `Agent` behavior using `agent.set('tick', tickRule)`. As a trivial example, consider the following `Rule`, which increments the `Agent`'s `x` value with every time step:
  *
@@ -36,6 +53,23 @@ declare class Rule {
     locals: {
         [key: string]: any;
     };
+    /**
+     * When true, evaluation traces are logged and captured.
+     */
+    trace: boolean;
+    traceLog: string[];
+    /** @hidden */
+    private _traceDepth;
+    /**
+     * Static operator info mapping operator names to their expected argument counts.
+     */
+    static operatorInfo: {
+        [key: string]: OperatorArity;
+    };
+    /**
+     * Format arbitrary steps as pretty-printed S-expressions.
+     */
+    static formatSteps(steps: any[], options?: RuleFormatOptions): string;
     /**
      * A single step may be as simple as `["get", "x"]`. This returns the `Agent`'s `"x"` value to the outer step that contains it. So, for example, the step `["add", 1, ["get", "x"]]`, working from the inside out, retrieves the `"x"` value and then adds `1` to it. More complex steps function similarly, always traversing to the deepest nested step, evaluating it, and 'unwrapping' until all steps have been executed.
      *
@@ -67,18 +101,39 @@ declare class Rule {
      * |`"agent"`|`0`|No arguments; returns the `Agent`|
      * |`"environment"`|`0`|No arguments, returns the `Environment`|
      * |`"vector"`|`any`|Creates an n-dimensional {@linkcode Vector} from the supplied arguments|
+     * |`"log"`|`any`|Logs expression(s) and returns the last evaluated value|
      */
     constructor(environment: Environment, steps: Step[]);
+    /**
+     * Pretty-print the rule's step tree as S-expressions.
+     */
+    format(options?: RuleFormatOptions): string;
+    /**
+     * Returns a formatted S-expression representation of the rule.
+     */
+    toString(): string;
+    /**
+     * Validate the rule's step tree and return an array of diagnostics.
+     * Does not throw — returns diagnostics for inspection.
+     * @since 0.6.0
+     */
+    validate(): RuleDiagnostic[];
+    /** @hidden */
+    private _validateStep;
     /**
      * interpret single array step
      * @since 0.3.0
      * @hidden
      */
+    /** @hidden */
+    private _traceLogEntry;
     evaluate: (agent: Agent, step: any[]) => any;
+    /** @hidden */
+    private _evaluateOp;
     /**
      * @since 0.3.0
      * @hidden
      */
     call(agent: Agent): any;
 }
-export { Rule };
+export { Rule, RuleDiagnostic, RuleFormatOptions };

package/dist/main.d.ts

@@ -1,7 +1,7 @@
 export { Agent } from "./agents/Agent";
 export { Vector } from "./helpers/Vector";
 export { Network } from "./helpers/Network";
-export { Rule } from "./helpers/Rule";
+export { Rule, RuleDiagnostic, RuleFormatOptions } from "./helpers/Rule";
 export { KDTree } from "./helpers/KDTree";
 export { NumArray } from "./helpers/NumArray";
 export { Colors, Terrain } from "./helpers/Terrain";

package/dist/renderers/CanvasRenderer.d.ts

@@ -1,6 +1,11 @@
 /// <reference path="../src/renderers/CanvasRendererOptions.d.ts" />
 import { AbstractRenderer } from "./AbstractRenderer";
 import type { Environment } from "../environments/Environment";
+import type { Agent } from "../agents/Agent";
+/** @hidden */
+declare type InteractiveEventName = "click" | "hover" | "unhover";
+/** @hidden */
+declare type InteractiveCallback = (agent: Agent, event: MouseEvent) => void;
 /**
  * A `CanvasRenderer` renders an {@linkcode Environment} spatially in two dimensions.
  * Importantly, it expects that all {@linkcode Agent}s in the `Environment`
@@ -19,6 +24,12 @@ import type { Environment } from "../environments/Environment";
  * - `"triangle"` &mdash; Draws a triangle centered at the `Agent`'s `"x"` / `"y"` values.
  *   - Also uses the `"size"` value.
  *
+ * When `interactive` is set to `true` in the options, the renderer supports:
+ * - **Click/hover detection** &mdash; Use {@linkcode on} to listen for `"click"`, `"hover"`, and `"unhover"` events on agents.
+ * - **Agent selection** &mdash; Clicking an agent selects it (highlighted with a stroke). Access selected agents via {@linkcode selected}.
+ * - **Pan** &mdash; Click and drag on empty space to pan.
+ * - **Zoom** &mdash; Scroll to zoom in/out (bounded by `zoomMin` / `zoomMax`).
+ *
  * @since 0.0.11
  */
 declare class CanvasRenderer extends AbstractRenderer {
@@ -28,6 +39,20 @@ declare class CanvasRenderer extends AbstractRenderer {
     buffer: HTMLCanvasElement;
     /** @hidden */
     terrainBuffer: HTMLCanvasElement;
+    /** The currently selected agents (only used when `interactive` is `true`). */
+    selected: Agent[];
+    /** @hidden */
+    private _listeners;
+    /** @hidden */
+    private _hoveredAgent;
+    /** @hidden */
+    private _isPanning;
+    /** @hidden */
+    private _panStart;
+    /** @hidden */
+    private _panOriginStart;
+    /** @hidden */
+    private _boundHandlers;
     /**
      * The first parameter must be the {@linkcode Environment} that this
      * `CanvasRenderer` will render.
@@ -39,12 +64,40 @@ declare class CanvasRenderer extends AbstractRenderer {
      * - `connectionOpacity` (*number* = `1`) &mdash; For `Environment`s using a `Network`, the opacity of lines
      * - `connectionWidth` (*number* = `1`) &mdash; For `Environment`s using a `Network`, the width of lines
      * - `height` (*number* = `500`) &mdash; The height, in pixels, of the canvas on which to render
+     * - `interactive` (*boolean* = `false`) &mdash; Enables interactive features (click/hover detection, selection, pan, zoom)
+     * - `onSelect` (*function*) &mdash; Optional callback when an agent is selected or deselected
      * - `origin` (*{ x: number; y: number }* = `{ x: 0, y: 0 }`) &mdash; The coordinate of the upper-left point of the space to be rendered
      * - `scale` (*number* = `1`) &mdash; The scale at which to render (the larger the scale, the smaller the size of the space that is actually rendered)
      * - `trace` (*boolean* = `false`) &mdash; If `true`, the renderer will not clear old drawings, causing the `Agent`s to appear to *trace* their paths across space
      * - `width` (*number* = `500`) &mdash; The width, in pixels, of the canvas on which to render
+     * - `zoomMin` (*number* = `0.1`) &mdash; Minimum scale when zooming
+     * - `zoomMax` (*number* = `10`) &mdash; Maximum scale when zooming
      */
     constructor(environment: Environment, opts: CanvasRendererOptions);
+    /**
+     * Register a callback for an interactive event.
+     * Supported event names: `"click"`, `"hover"`, `"unhover"`.
+     *
+     * ```js
+     * renderer.on("click", (agent, event) => {
+     *   console.log("Clicked agent:", agent.id);
+     * });
+     * ```
+     *
+     * @param eventName - The event to listen for.
+     * @param callback - The callback, invoked with the `Agent` and the `MouseEvent`.
+     */
+    on(eventName: InteractiveEventName, callback: InteractiveCallback): void;
+    /** @hidden */
+    private _emit;
+    /**
+     * Given a mouse event, return the agent at that position (if any).
+     * Hit-testing accounts for the agent's shape and size.
+     * @hidden
+     */
+    _agentAtPoint(clientX: number, clientY: number): Agent | null;
+    /** @hidden */
+    private _setupInteractiveListeners;
     /** @hidden */
     x(v: number): number;
     /** @hidden */
@@ -67,6 +120,11 @@ declare class CanvasRenderer extends AbstractRenderer {
     drawRect(x: number, y: number, width: number, height: number): void;
     /** @hidden */
     drawRectWrap(x: number, y: number, w: number, h: number): void;
+    /**
+     * Draw a selection highlight around the given agent.
+     * @hidden
+     */
+    private _drawSelectionHighlight;
     render(): void;
 }
 export { CanvasRenderer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flocc",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "description": "Agent-based modeling in JavaScript in the browser or server.",
   "main": "dist/flocc.js",
   "module": "dist/flocc.es.js",

package/dist/environments/NewEnvironment.d.ts

@@ -1,76 +0,0 @@
-/// <reference path="../src/agents/Agent.d.ts" />
-/// <reference path="../src/types/Data.d.ts" />
-/// <reference path="../src/renderers/Renderer.d.ts" />
-/// <reference path="../src/environments/EnvironmentHelper.d.ts" />
-/// <reference path="../src/environments/EnvironmentOptions.d.ts" />
-declare type NewRule = (agent: Agent) => Data;
-interface Helpers {
-    kdtree: EnvironmentHelper;
-    network: EnvironmentHelper;
-}
-export interface TickOptions {
-    count?: number;
-    randomizeOrder?: boolean;
-}
-export declare const defaultTickOptions: TickOptions;
-/**
- * From the parameter passed to .tick, get a structured TickOptions object.
- * @param {number | TickOptions} opts
- */
-export declare const getTickOptions: (opts?: number | TickOptions) => TickOptions;
-interface MemoValue {
-    value: any;
-    time: number;
-}
-declare class NewEnvironment {
-    agents: number;
-    cache: Map<string, MemoValue>;
-    current: number;
-    data: Map<string, any[]>;
-    ids: string[];
-    idsToIndices: {
-        [key: string]: number;
-    };
-    helpers: Helpers;
-    opts: EnvironmentOptions;
-    nextData: Map<string, any[]>;
-    rule: NewRule;
-    renderers: Renderer[];
-    width: number;
-    height: number;
-    time: number;
-    constructor(opts?: EnvironmentOptions);
-    static isAgent(a: any): a is Agent;
-    addAgent(data: Data): Agent;
-    /**
-     * Remove an agent from the environment.
-     * @param {Agent} agent
-     */
-    removeAgent(agent: Agent): void;
-    /**
-     * Remove an agent from the environment by its ID.
-     * @param {string} id
-     */
-    removeAgentById(id: string): void;
-    _get(i: number, key: string): any;
-    _getData(i: number): Data;
-    _set(i: number, key: string | Data, value?: any): void;
-    increment(i: number, key: string, n: number): void;
-    decrement(i: number, key: string, n: number): void;
-    enqueue(i: number, data: Data): void;
-    getAgent(i: number): Agent;
-    getAgents(): Agent[];
-    getAgentById(id: string): Agent;
-    /**
-     * Removes all agents from the environment.
-     */
-    clear(): void;
-    addRule(rule: NewRule): void;
-    tick(opts?: number | TickOptions): void;
-    /**
-     * Use a helper with this environment.
-     * @param {EnvironmentHelper} e
-     */
-    use(e: EnvironmentHelper): void;
-}
-export { NewEnvironment };

package/dist/helpers/BS.d.ts

@@ -1,6 +0,0 @@
-declare class BS {
-    size: number;
-    m: number;
-    constructor(size: number);
-}
-export { BS };

package/dist/types/instanceOfPoint.d.ts

@@ -1,2 +0,0 @@
-/// <reference path="../src/types/Point.d.ts" />
-export default function instanceOfPoint(obj: any): obj is Point;

package/dist/types/isAgent.d.ts

@@ -1,2 +0,0 @@
-/// <reference path="../src/agents/Agent.d.ts" />
-export default function isAgent(a: any): a is Agent;

package/dist/utils/copyArray.d.ts

@@ -1,10 +0,0 @@
-/**
- * Copies the values of `source` to `arr`
- * or to a new Array.
- *
- * @private
- * @param {Array} source The Array to copy values from.
- * @param {Array} [arr=[]] The Array to copy values to.
- * @returns {Array}
- */
-export default function copyArray<T>(source: T[], arr?: T[]): T[];

package/dist/utils/lcg.d.ts

@@ -1 +0,0 @@
-export default function lcg(modulus: number, a: number, c: number, seed: number): Generator<number>;

package/dist/utils/randomizeOrder.d.ts

@@ -1,12 +0,0 @@
-export default class Randomizer {
-    index: number;
-    maxrange: number;
-    offset: number;
-    prime: number;
-    runningvalue: number;
-    constructor(maxrange: number);
-    reset(): void;
-    getCurrentValue(): number;
-    hasNext(): boolean;
-    next(): number;
-}