Engine API

Reference documentation for the engine layer: DashboardEngine, DashboardCommand, CommandHistory, event types, DashboardExtension, and DashboardEditorController.

DashboardEngine

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
initialLayout	DashboardLayout?	No	Starting layout. If null, starts with DashboardLayout.empty(). Row flex values are normalized on construction.
registry	DashboardEditorRegistry?	No	Registry used to resolve component instances. Defaults to an empty scoped registry.

Properties

Property	Type	Default	Description
layoutObservable	Observable<DashboardLayout>	--	Reactive layout state
layout	DashboardLayout	--	Current layout value
registry	DashboardEditorRegistry	--	Component registry
extensions	List<DashboardExtension>	--	Unmodifiable list of extensions

Methods

• addExtension

  void addExtension(DashboardExtension extension)

  Registers an extension. Throws StateError if an extension with the same ID is already registered.

• removeExtension

  void removeExtension(String id)

  Removes an extension by ID.

• getExtension returns E?

  E? getExtension<E extends DashboardExtension>()

  Returns the registered extension of type E if any.

• hasExtension returns bool

  bool hasExtension(String id)

  Whether an extension with the given ID is registered.

• executeCommand

  Future<void> executeCommand(DashboardCommand command)

  Executes a command, wrapping mutations in MobX runInAction and emitting events.

• applyUndo

  Future<void> applyUndo(DashboardCommand command)

  Applies a previously executed command in reverse.

• applyRedo

  Future<void> applyRedo(DashboardCommand command)

  Re-applies a previously undone command.

• replaceLayout

  void replaceLayout(DashboardLayout newLayout)

  Normalizes flex values and replaces the layout. Emits DashboardLayoutChanged.

• emitEvent

  void emitEvent(DashboardEvent event)

  Emits an event to all registered extensions.

• batch

  void batch(String reason, void Function() operations)

  Emits DashboardBatchStarted/DashboardBatchEnded around a group of operations. Supports nesting.

• dispose

  void dispose()

  Detaches all extensions and clears the list.

Mutation API

• addRow

  Future<String> addRow({int? position})

  AddRowCommand: Adds a row, returns the new row ID.

• removeRow

  Future<void> removeRow(String rowId)

  RemoveRowCommand: Removes a row.

• reorderRow

  Future<void> reorderRow(int oldIndex, int newIndex)

  ReorderRowsCommand: Moves a row.

• splitRow

  Future<void> splitRow(String rowId, int numColumns)

  SplitRowCommand: Replaces all columns with N equal columns.

• addColumn

  Future<void> addColumn(String rowId)

  AddColumnCommand: Adds a column to a row.

• removeColumn

  Future<void> removeColumn(String rowId, String columnId)

  RemoveColumnCommand: Removes a column.

• reorderColumns

  Future<void> reorderColumns(String rowId, int oldIndex, int newIndex)

  ReorderColumnsCommand: Reorders columns within a row.

• updateColumnFlex

  Future<void> updateColumnFlex({required String rowId, required String columnId, required int flex})

  UpdateColumnFlexCommand: Sets a single column flex value.

• resizeAdjacentColumns

  Future<void> resizeAdjacentColumns({required String rowId, required String leftColumnId, required String rightColumnId, required int leftFlex, required int rightFlex})

  ResizeAdjacentColumnsCommand: Resizes two adjacent columns together.

• updateRowFlex

  Future<void> updateRowFlex({required String rowId, required Map<String, int> flexByColumnId})

  UpdateRowFlexCommand: Sets all column flex values.

• updateRowTitle

  Future<void> updateRowTitle({required String rowId, required String? title})

  UpdateRowTitleCommand: Sets or clears the title.

• updateRowHeight

  Future<void> updateRowHeight({required String rowId, required double? height})

  UpdateRowHeightCommand: Sets the row height.

• updateRowViewportFraction

  Future<void> updateRowViewportFraction({required String rowId, required double? viewportFraction})

  UpdateRowViewportFractionCommand: Sets the viewport-relative row height.

• addComponent

  Future<void> addComponent({required String rowId, required String columnId, required ComponentInstance component})

  AddComponentCommand: Places a component in an empty column.

• removeComponent

  Future<void> removeComponent({required String rowId, required String columnId})

  RemoveComponentCommand: Clears a column's component.

• replaceComponent

  Future<void> replaceComponent({required String rowId, required String columnId, required ComponentInstance newComponent})

  ReplaceComponentCommand: Replaces one component with another.

• swapComponents

  Future<void> swapComponents({required String sourceRowId, required String sourceColumnId, required String targetRowId, required String targetColumnId})

  SwapComponentsCommand: Swaps two components.

• duplicateComponent

  Future<void> duplicateComponent({required String sourceRowId, required String sourceColumnId})

  DuplicateComponentCommand: Copies a component to the nearest empty slot.

• updateComponentConfig

  Future<void> updateComponentConfig({required String componentId, required PropertyCollection newProperties})

  UpdateComponentConfigCommand: Updates a component's properties.

• updateLayoutMetadata

  Future<void> updateLayoutMetadata(Map<String, dynamic> patch)

  UpdateDashboardMetadataCommand: Patches the dashboard metadata.

MobX-based state kernel for the dashboard system. Owns the reactive layout and emits structured events to extensions.

---

DashboardEngineApi

abstract

Class Signature

Forward declaration interface used by extensions to access the engine without circular imports.

---

DashboardCommand

abstract

Class Signature

Abstract interface for reversible commands.

Built-in Commands

Row Commands:

Command	Description
AddRowCommand	Add a row at a specific position
RemoveRowCommand	Remove a row and reorder remaining rows
ReorderRowsCommand	Move a row from one position to another
SplitRowCommand	Replace all columns with N equal columns
UpdateRowTitleCommand	Set or clear the row title
UpdateRowHeightCommand	Set the row height in pixels
UpdateRowViewportFractionCommand	Set the viewport-relative row height

Column Commands:

Command	Description
AddColumnCommand	Add an empty column to a row
RemoveColumnCommand	Remove a column and normalize flex
ReorderColumnsCommand	Swap column positions within a row
UpdateColumnFlexCommand	Change a single column's flex value
ResizeAdjacentColumnsCommand	Resize two adjacent columns together
UpdateRowFlexCommand	Set flex values for all columns in a row

Component Commands:

Command	Description
AddComponentCommand	Place a component in an empty column
RemoveComponentCommand	Clear a column's component
ReplaceComponentCommand	Replace one component with another
SwapComponentsCommand	Swap components between two columns
DuplicateComponentCommand	Copy a component to the nearest empty slot
UpdateComponentConfigCommand	Update a component's PropertyCollection

Dashboard Commands:

Command	Description
UpdateDashboardMetadataCommand	Merge a patch into dashboard metadata

---

CommandHistory

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
maxHistorySize	int	No	Maximum commands kept in history (default: 50)

Properties

Property	Type	Default	Description
maxHistorySize	int	--	Maximum commands in history
canUndo	bool	--	Whether undo is available
canRedo	bool	--	Whether redo is available
currentCommand	DashboardCommand?	--	Current undo target
nextCommand	DashboardCommand?	--	Next redo target
historySize	int	--	Total commands in stack
currentPosition	int	--	Current position (1-based)

Methods

• execute

  void execute(DashboardCommand command)

  Adds a command and discards the redo stack.

• undo returns DashboardCommand?

  DashboardCommand? undo()

  Moves back, returning the command that was undone.

• redo returns DashboardCommand?

  DashboardCommand? redo()

  Moves forward, returning the command that was redone.

• clear

  void clear()

  Clears all history.

Manages the undo/redo stack.

---

DashboardEvent Types

All events extend DashboardEvent:

abstract class DashboardEvent { const DashboardEvent(); }

Event	Fields	Emitted When
DashboardLayoutChanged	previous, current (both DashboardLayout)	Layout observable is updated
DashboardCommandExecuted	command (DashboardCommand)	A command is first executed
DashboardCommandUndone	command (DashboardCommand)	A command is undone
DashboardCommandRedone	command (DashboardCommand)	A command is redone
DashboardBatchStarted	reason (String)	Batch operation begins
DashboardBatchEnded	(none)	Batch operation ends

---

DashboardExtension

abstract

Class Signature

Abstract interface for engine extensions.

Built-in Extensions

DashboardHistoryExtension

Class Signature

Properties

Property	Type	Default	Description
extensionId	String (static)	'dashboard-history'	Unique extension identifier
canUndo	bool	--	Whether undo is available (reactive)
canRedo	bool	--	Whether redo is available (reactive)

Methods

• undo

  Future<void> undo()

  Undoes the last command.

• redo

  Future<void> redo()

  Redoes the last undone command.

• clear

  void clear()

  Clears the history stack.

---

DashboardPersistenceExtension

Class Signature

Properties

Property	Type	Default	Description
extensionId	String (static)	'dashboard-persistence'	Unique extension identifier
isDirty	Observable<bool>	--	Whether layout has unsaved changes

Methods

• markClean

  void markClean()

  Resets the dirty flag.

• markDirty

  void markDirty()

  Sets the dirty flag.

• toJson returns Map<String, dynamic>

  Map<String, dynamic> toJson()

  Serializes the current layout.

• fromJson

  void fromJson(Map<String, dynamic> json)

  Deserializes JSON with the registry and replaces the layout.

• loadLayout

  void loadLayout(DashboardLayout layout)

  Replaces the layout directly.

Constructor requires the scoped DashboardEditorRegistry so JSON imports can recreate each component's PropertyCollection.

---

DashboardSelectionExtension

Class Signature

Properties

Property	Type	Default	Description
extensionId	String (static)	'dashboard-selection'	Unique extension identifier
selectedCellRowId	Observable<String?>	--	Selected row ID
selectedCellColumnId	Observable<String?>	--	Selected column ID
showConfigPanel	Observable<bool>	--	Whether config panel is visible
rightPanelMode	Observable<DashboardRightPanelMode>	--	Panel mode
hoveredRowId	Observable<String?>	--	Hovered row
selectedCellComponent	ComponentInstance?	--	Component in selected cell
selectedRow	DashboardRow?	--	Selected row
selectedColumn	DashboardColumn?	--	Selected column
selectedCellHasComponent	bool	--	Whether selected cell has a component

Selection methods: selectCell, selectCellOnly, selectCellWithComponent, selectRow, selectDashboard, selectComponent, clearSelection, openConfigPanel, closeConfigPanel.

---

DashboardAnalyticsExtension

Class Signature

Properties

Property	Type	Default	Description
extensionId	String (static)	'dashboard-analytics'	Unique extension identifier

Tracks AddComponentCommand executions with a lightweight debug hook. Replace or augment it with an app-specific extension when you need production telemetry.

---

DashboardEditorController

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
initialLayout	DashboardLayout?	No	Optional starting layout
registry	DashboardEditorRegistry	Yes	Scoped registry used by the engine, persistence, palette, editor, and runtime view

Properties

Property	Type	Default	Description
engine	DashboardEngine	--	The underlying engine
history	DashboardHistoryExtension	--	History extension
persistence	DashboardPersistenceExtension	--	Persistence extension
selection	DashboardSelectionExtension	--	Selection extension
analytics	DashboardAnalyticsExtension	--	Analytics extension
layout	Observable<DashboardLayout>	--	Reactive layout
isDirty	Observable<bool>	--	Dirty flag
editingComponentId	Observable<String?>	--	Component being edited
editingProperties	Observable<PropertyCollection?>	--	Draft properties for config panel
canUndo	bool	--	History can undo (computed)
canRedo	bool	--	History can redo (computed)
isEmpty	bool	--	No rows (computed)
canAddRow	bool	--	Under max rows (computed)
rowCount	int	--	Number of rows (computed)
componentCount	int	--	Total components (computed)
selectedComponent	ComponentInstance?	--	Currently selected component (computed)
selectedRow	DashboardRow?	--	Currently selected row (computed)
selectedColumn	DashboardColumn?	--	Currently selected column (computed)

Methods

• loadLayout

  void loadLayout(DashboardLayout newLayout)

  Clears history/selection, replaces the layout, and marks it clean.

• markDirty

  void markDirty()

  Marks the layout as having unsaved changes.

• markClean

  void markClean()

  Clears the dirty flag.

• validate

  List<String> validate()

  Returns validation errors for the current layout.

• toJson returns Map<String, dynamic>

  Map<String, dynamic> toJson()

  Serializes the current layout.

• fromJson

  void fromJson(Map<String, dynamic> json)

  Clears history/selection and loads layout JSON via the persistence extension.

• undo

  Future<void> undo()

  Delegates to the history extension.

• redo

  Future<void> redo()

  Delegates to the history extension.

• dispose

  void dispose()

  Disposes the selection-to-editing reaction, canvas focus node, scroll controller, JSON panel, and engine.

Facade composing the engine with all four extensions. The controller delegates all layout mutations, selection operations, undo/redo, and persistence to the respective engine methods and extensions.

Next Steps

• Layout API -- DashboardLayout, Row, Column, ComponentInstance
• Components API -- ComponentDescriptor, Registry
• Glossary -- Term definitions