@visuallyjs/browser-ui 1.2.7 → 1.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visuallyjs/browser-ui",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "license": "Commercial",
   "main": "js/visuallyjs.browser-ui.cjs.js",
   "module": "js/visuallyjs.browser-ui.esm.js",

package/types/browser-ui/components/index.d.ts

@@ -2,4 +2,5 @@ export * from './controls';
 export * from './inspector';
 export * from './palette';
 export * from './edge-type-picker';
+export * from './shape-type-inspector';
 export * from './rotate-manager';

package/types/browser-ui/components/inspector/index.d.ts

@@ -3,4 +3,3 @@ export * from './inspector';
 export * from './vanilla-inspector';
 export * from './color-picker-tag';
 export * from './edge-type-tag';
-export * from './shape-type-inspector';

package/types/browser-ui/components/shape-type-inspector/index.d.ts

@@ -0,0 +1 @@
+export * from './shape-type-inspector';

package/types/browser-ui/components/{inspector → shape-type-inspector}/shape-type-inspector.d.ts

@@ -1,7 +1,7 @@
 import { ShapePropertyDefinition } from "../../shape-library";
-import { VanillaInspector } from "./vanilla-inspector";
+import { VanillaInspector } from "../inspector/vanilla-inspector";
 import { Base } from "../../../core";
-import { VanillaInspectorOptions } from "./definitions";
+import { VanillaInspectorOptions } from "../inspector/definitions";
 import { BrowserUI } from "../../browser-visuallyjs-instance";
 /**
  * Generates an HTML string in the Recado template format for all configurable

package/types/browser-ui/plugins/graph-propagation/index.d.ts

@@ -0,0 +1,26 @@
+import { Calculator, GraphPropagationEngine } from "../../../core/graph-propagation";
+import { BrowserUI } from "../../browser-visuallyjs-instance";
+import { BaseBrowserUIPlugin, BrowserUIPlugin, BrowserUIPluginOptions } from "../browser-ui-plugin";
+/** Plugin type for graph value propagation. */
+export declare const PLUGIN_TYPE_GRAPH_PROPAGATION = "graphPropagation";
+/** Options for the graph propagation plugin. */
+export interface GraphPropagationEnginePluginOptions<ValueType, StateType = unknown> extends BrowserUIPluginOptions {
+    /** Calculator functions keyed by node or group type. */
+    calculators: Record<string, Calculator<ValueType, StateType>>;
+    /** Model property used for propagated values. Defaults to `value`. */
+    property?: string;
+    /** Model property used for calculated node state. Defaults to `computed`. */
+    stateProperty?: string;
+}
+/** Browser UI plugin that runs a GraphPropagationEngine against the UI's model. */
+export declare class GraphPropagationEnginePlugin<ValueType = unknown, StateType = unknown> extends BaseBrowserUIPlugin implements BrowserUIPlugin<GraphPropagationEnginePluginOptions<ValueType, StateType>> {
+    static type: string;
+    id: string;
+    ui: BrowserUI;
+    engine: GraphPropagationEngine<ValueType, StateType>;
+    initialise(ui: BrowserUI, options: GraphPropagationEnginePluginOptions<ValueType, StateType>): boolean;
+    destroy(): void;
+    reset(): void;
+}
+/** Gets the graph propagation plugin attached to a UI, if present. */
+export declare function getGraphPropagationPlugin(ui: BrowserUI): GraphPropagationEnginePlugin | null;

package/types/browser-ui/plugins/index.d.ts

@@ -3,3 +3,4 @@ export * from './background';
 export * from './ui-states';
 export * from './edge-routing';
 export * from './selected-edge-highlight';
+export * from './graph-propagation';

package/types/browser-ui/shape-library/shape-library-definitions.d.ts

@@ -271,6 +271,10 @@ export interface ShapePropertyDefinition {
      * The data type of the property, telling the inspector which UI control to render by default. For properties that include a `values` array (and also properties of type boolean) you can override the choice of UI control via the `editor` option.
      */
     type: ShapePropertyType;
+    /**
+     * If true, inspectors display this property's value without an editable control.
+     */
+    readOnly?: boolean;
     /**
      * The default value for this property if it hasn't been explicitly set.
      */

package/types/browser-ui/surface-renderer/diagrams/definitions.d.ts

@@ -2,6 +2,7 @@ import { LabelBackgroundOptions, LabelPosition, ShapeSet } from "../../shape-lib
 import { Group, ObjectData, PointXY, Size, Vertex, Node, BeforeConnectInterceptor } from "../../../core";
 import { DiagramCell } from "./diagram-cell";
 import { GridOptions, UIExportOptions, UICoreDefaults, EdgeEventOptions, OverlaySpec, ConnectorSpec, NodeEventOptions, GroupMapping, NodeMapping, AnchorSpec, EdgePropertyMappings, MagnetizeOptions, PaintStyle, OverlayVisibility, EdgeDeleteConfirmationFunction, LabelBackgroundStyle, FontSpec } from "../../../ui";
+import type { BindableViewEvent } from "../../../ui";
 import { SurfaceSaveData } from "../definitions";
 import { BrowserElement } from "../../util";
 import { PaletteMode, AutoEdgeConnectOptions, CanDropOnEdgeFilter } from "../../components/palette/palette-options";
@@ -11,6 +12,65 @@ import { EdgeSnapOptions, EdgeInputMethod } from "../../edge-handler-base";
 import { DiagramActionMediator } from "./mediator";
 import { OnVertexAddedCallback } from "../../definitions";
 import { PreparedShape } from "../shape-palette-options";
+import { GraphPropagationEnginePluginOptions } from "../../plugins";
+import type { BrowserUIModel } from "../../browser-ui";
+import type { BrowserUI } from "../../browser-visuallyjs-instance";
+import type { Diagram } from "./diagram";
+/**
+ * Payload passed to a cell template event callback.
+ * @group Diagrams
+ * @category Events
+ */
+export interface DiagramCellTemplateEventCallbackPayload<E extends Event = Event> {
+    /**
+     * The diagram cell whose rendered template contained the matching event target.
+     */
+    cell: DiagramCell;
+    /**
+     * The backing vertex for the cell.
+     */
+    vertex: Node | Group;
+    /**
+     * The original browser event.
+     */
+    event: E;
+    /**
+     * The element inside the rendered shape template that matched the configured selector.
+     */
+    eventTarget: BrowserElement;
+    /**
+     * The diagram that owns the cell.
+     */
+    diagram: Diagram;
+    /**
+     * The underlying VisuallyJs model.
+     */
+    model: BrowserUIModel;
+    /**
+     * The UI that rendered the diagram.
+     */
+    ui: BrowserUI;
+}
+/**
+ * Callback invoked for an event on an element inside a rendered cell template.
+ * @group Diagrams
+ * @category Events
+ */
+export type DiagramCellTemplateEventCallback<E extends Event = Event> = (p: DiagramCellTemplateEventCallbackPayload<E>) => any;
+/**
+ * A map of event names to callbacks for a single selector inside a rendered cell template.
+ * @group Diagrams
+ * @category Events
+ */
+export type DiagramCellTemplateEventMap = {
+    [K in BindableViewEvent]?: DiagramCellTemplateEventCallback;
+} & Record<string, DiagramCellTemplateEventCallback | undefined>;
+/**
+ * A map of CSS selectors to event/callback maps for elements inside rendered cell templates.
+ * @group Diagrams
+ * @category Events
+ */
+export type DiagramCellTemplateEvents = Record<string, DiagramCellTemplateEventMap>;
 /**
  * Options for the {@link Diagram.addLink method}
  * @group Diagrams
@@ -353,6 +413,26 @@ export interface DiagramOptions {
          * Optional event mappings for all cells.
          */
         events?: NodeEventOptions<any>;
+        /**
+         * Optional delegated event mappings for elements inside rendered cell templates. Keys are CSS selectors
+         * that match elements inside a shape template, and values are maps of event names to callbacks.
+         *
+         * The callback receives the {@link DiagramCell} associated with the matching element, plus the backing
+         * vertex, the original browser event, the matching element, the diagram, the model and the UI.
+         *
+         * For example:
+         *
+         * ```ts
+         * cells:{
+         *   templateEvents:{
+         *     ".delete":{
+         *       tap:({cell}) => cell.remove()
+         *     }
+         *   }
+         * }
+         * ```
+         */
+        templateEvents?: DiagramCellTemplateEvents;
         /**
          * Optional behaviour mapping for groups in the diagram. For many setups, you won't need to use this, as the other options in the `cells` config are quite extensive and can be used to configure many things. For some setups you may need to provide config for group behaviour, such as whether or not vertices can be dragged in/out, whether the group should be resizable, etc. You can also provide group-specific event mappings here. Any `events` you provide here will be merged with the internal event registrations made by the diagram, but if you provide a `template` it will be ignored.
          */
@@ -366,6 +446,9 @@ export interface DiagramOptions {
          * Optional mapping for nodes in the diagram. For many setups, you won't need to use this, as the other options in the `cells` config are quite extensive and can be used to configure many things. Any `events` you provide here will be merged with the internal event registrations made by the diagram, but if you provide a `template` it will be ignored.
          */
         nodes?: DiagramNodeMapping;
+        /**
+         * Options controlling how resize functions.
+         */
         resize?: {
             /**
              * Width/height to use for resize handles. Defaults to 20 pixels.
@@ -483,6 +566,10 @@ export interface DiagramOptions {
      * Controls whether line crossings are shown by a visual cue. Defaults to false. You can either supply a boolean and have the panbuttons plugin initialize with its default settings, or supply your own settings.
      */
     lineCrossings?: boolean | LineCrossingsPluginOptions;
+    /**
+     * If provided, a graph propagation engine will be used to propagate changes to the graph.
+     */
+    graphPropagation?: GraphPropagationEnginePluginOptions<any>;
 }
 /**
  * Options for a palette for a diagram.

package/types/browser-ui/surface-renderer/diagrams/diagram.d.ts

@@ -33,6 +33,7 @@ export declare class Diagram {
     _mediator: DiagramActionMediator;
     constructor(model: BrowserUIModel, container: BrowserElement, options: DiagramOptions);
     private _createView;
+    private _bindTemplateEvents;
     /**
      * @internal
      * @param v

package/types/browser-ui/surface-renderer/shape-palette.d.ts

@@ -15,6 +15,7 @@ export declare const ATTRIBUTE_DATA_SHAPE_ID = "data-shape-id";
  */
 export declare class ShapePalette<T extends ObjectData> {
     private ui;
+    _$_iconTemplateEngine: BrowserUiRecado;
     _$_templateEngine: BrowserUiRecado;
     _$_palette: Palette;
     _$_userDataGenerator: DataGeneratorFunction;

package/types/core/graph-propagation/definitions.d.ts

@@ -0,0 +1,41 @@
+import { Node } from "../model/graph";
+/**
+ * Terminal id used when an edge connects directly to a node or group instead of a named port.
+ * For example, junctions and probes use this as their implicit input/output terminal.
+ */
+export declare const DEFAULT_TERMINAL = "default";
+/**
+ * Result returned by a node calculator.
+ * @typeParam ValueType Defines the type of the node's output values.
+ * @typeParam StateType Defines the type of the node's internal state.
+ */
+export type NodeEvaluation<ValueType, StateType = unknown> = {
+    /**
+     * Values made available to downstream edges, keyed by terminal id. Keys are port ids such as"out"`, or `DEFAULT_TERMINAL` for direct node connections
+     */
+    outputs?: Record<string, ValueType | undefined>;
+    /**
+     * Derived node state (such as display text, validation details, or cached intermediate results) written to the node's configured state property.
+     */
+    state?: StateType;
+};
+/**
+ * Helper API passed to calculators so they can read upstream values without knowing graph details.
+ * @typeParam ValueType Defines the type of the node's output values.
+ */
+export interface EvaluationContext<ValueType> {
+    /**
+     * Reads the value connected to one input terminal. Omit `terminalId` or pass `DEFAULT_TERMINAL` for direct node-body connections. Otherwise terminalId is assumed to map to a port ID on the node.
+     */
+    input: (terminalId?: string) => ValueType | undefined;
+    /**
+     * Reads named input terminals in order. When omitted, reads every edge connected directly to the node body, in edge order.
+     */
+    inputs: (terminalIds?: string[]) => Array<ValueType | undefined>;
+}
+/**
+ * Evaluates a node from its current upstream inputs - the function has access to the `input(...)` and `inputs(..)` methods on the evaluation context that is passed in, for resolving the input values on the node.
+ * @typeParam ValueType Defines the type of the node's output values.
+ * @typeParam StateType Defines the type of the node's internal state.
+ */
+export type Calculator<ValueType, StateType = unknown> = (node: Node, context: EvaluationContext<ValueType>) => NodeEvaluation<ValueType, StateType> | undefined;

package/types/core/graph-propagation/engine.d.ts

@@ -0,0 +1,63 @@
+import { VisuallyJsModel } from "../toolkit";
+import { Calculator } from "./definitions";
+/**
+ * Full calculation output before it is written back to the model.
+ */
+type CalculationResult<ValueType, StateType> = {
+    /** Propagated values keyed by concrete vertex id, for example `nodeId.out`. */
+    values: Map<string, ValueType>;
+    /** Computed node states keyed by node or group id. */
+    states: Map<string, StateType>;
+};
+/**
+ * Propagates computed values through a VisuallyJS graph.
+ *
+ * The engine treats each node or group as the unit of computation. A calculator is registered per
+ * vertex type, reads upstream values through an `EvaluationContext`, and returns output terminal
+ * values plus optional internal state for that vertex.
+ *
+ * Output keys are terminal ids: use a port id for named ports, or `DEFAULT_TERMINAL` for edges
+ * connected directly to the node/group body. During propagation, the engine maps those terminal ids
+ * back to concrete graph vertices and writes propagated values to `property` on target vertices.
+ *
+ * Calculator `state` is not propagated across edges. It is written to the owning node/group under
+ * `stateProperty`, making it suitable for display data, validation results, summaries, or cached
+ * derived values.
+ *
+ * To integrate, define calculators keyed by node/group type, construct the engine with a
+ * `VisuallyJsModel`, and read propagated values from vertices using `property` and computed state
+ * from nodes/groups using `stateProperty`.
+ */
+export declare class GraphPropagationEngine<ValueType, StateType = unknown> {
+    private model;
+    private calculators;
+    private _suspended;
+    private _property;
+    private _stateProperty;
+    /**
+     * Creates a propagation engine and binds it to model update events.
+     *
+     * Edge additions/removals and data updates on connected vertices trigger recalculation on the
+     * next animation frame. Updates produced by the engine are applied in one model transaction.
+     *
+     * @param model Model whose nodes, groups, ports, and edges should participate in propagation.
+     * @param calculators Calculator functions keyed by node/group type.
+     * @param property Data property used for propagated vertex values. Defaults to `"value"`.
+     * @param stateProperty Data property used for computed node/group state. Defaults to `"computed"`.
+     */
+    constructor(model: VisuallyJsModel, calculators: Record<string, Calculator<ValueType, StateType>>, property?: string, stateProperty?: string);
+    /**
+     * Runs propagation immediately and writes the result back to the model.
+     *
+     * `knownValues` can seed the value cache for this run. Keys must be concrete vertex ids, such
+     * as a node id or full port id. This is useful when an edited source value is already known and
+     * should be used before the model has been fully re-read.
+     */
+    calculate(knownValues?: Record<string, ValueType>): CalculationResult<ValueType, StateType>;
+    /**
+     * The main entry point for the calculation. Iterates through all nodes, resolves their new state, and updates the model if the state has changed.
+     */
+    private _calculate;
+    private _apply;
+}
+export {};

package/types/core/graph-propagation/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./definitions";
+export * from "./engine";

package/types/core/index.d.ts

@@ -8,6 +8,7 @@ export * from './model/path';
 export * from './model/anchor';
 export * from './datamodel/data-model';
 export * from './datamodel/vertex-definition';
+export * from './graph-propagation';
 export * from './layout';
 export * from "./geom";
 export * from './color-generator';

package/types/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "1.2.7";
+export declare const VERSION = "1.2.8";