Layout API

Reference documentation for the layout model classes: DashboardLayout, DashboardRow, DashboardColumn, ComponentInstance, and DashboardLayoutConstants.

DashboardLayout

Class Signature

Properties

Property	Type	Default	Description
version	String	'2.0.0'	Schema version
rows	List<DashboardRow>	--	Ordered list of rows
metadata	Map<String, dynamic>?	null	Optional metadata (name, apiBaseUrl, etc.)
canAddRow	bool	--	rows.length < maxRows
rowCount	int	--	Number of rows
isEmpty	bool	--	Whether there are no rows
componentCount	int	--	Total filled columns across all rows
totalColumns	int	--	Total columns across all rows
emptySlotCount	int	--	Total empty columns
apiBaseUrl	String?	--	API base URL from metadata
maxRows	int (static)	25	Maximum number of rows allowed

Methods

• DashboardLayout.empty

  factory DashboardLayout.empty()

  Creates an empty layout with no rows.

• DashboardLayout.withRows

  factory DashboardLayout.withRows(List<DashboardRow> rows)

  Creates a layout from rows, sorted by their order field.

• copyWith

  DashboardLayout copyWith({
    String? version,
    List<DashboardRow>? rows,
    Map<String, dynamic>? metadata,
    bool clearMetadata = false,
  })

  Returns a copy with updated fields.

• withApiBaseUrl

  DashboardLayout withApiBaseUrl(String baseUrl)

  Returns a copy with the apiBaseUrl set in metadata.

• fromJson

  factory DashboardLayout.fromJson(Map<String, dynamic> json, {required DashboardEditorRegistry registry})

  Deserializes a layout from JSON and uses the registry to recreate component property collections.

• toJson

  Map<String, dynamic> toJson()

  Serializes the layout to JSON.

Top-level container for the entire dashboard.

---

DashboardRow

Class Signature

Properties

Property	Type	Default	Description
id	String	--	Unique row identifier
columns	List<DashboardColumn>	--	1-6 columns
order	int	--	Display order (0-based)
title	String?	null	Optional display title
height	double?	null	Fixed height in pixels (null = use default 60)
viewportFraction	double?	null	Viewport-relative height (0.1+). Overrides height.
metadata	Map<String, dynamic>?	null	Optional metadata
maxColumns	int (static)	6	Maximum columns per row
usesViewportFraction	bool	--	viewportFraction != null
effectiveHeight	double	--	height ?? 60.0
canAddColumn	bool	--	columns.length < 6
hasEmptyColumns	bool	--	Any column has no component
isCompletelyEmpty	bool	--	All columns are empty
isCompletelyFilled	bool	--	All columns have components
columnCount	int	--	Number of columns
totalFlex	int	--	Sum of all column flex values
emptyColumns	List<DashboardColumn>	--	Columns without components
filledColumns	List<DashboardColumn>	--	Columns with components

Methods

• DashboardRow.single

  factory DashboardRow.single(String id, int order, String columnId)

  Creates a row with one column at full flex (6).

• DashboardRow.withColumns

  factory DashboardRow.withColumns(String id, int order, List<String> columnIds)

  Creates a row with evenly distributed flex.

• distributeFlex

  static List<int> distributeFlex(int count)

  Distributes 6 flex units evenly across count columns. Remainder goes to leading columns.

• normalizedFlex

  DashboardRow normalizedFlex()

  Returns a copy where column flex values are adjusted to sum to 6.

• copyWith

  DashboardRow copyWith({
    String? id,
    List<DashboardColumn>? columns,
    int? order,
    String? title,
    double? height,
    double? viewportFraction,
    Map<String, dynamic>? metadata,
    bool clearTitle = false,
    bool clearHeight = false,
    bool clearViewportFraction = false,
    bool clearMetadata = false,
  })

  Returns a copy with updated fields.

• fromJson

  factory DashboardRow.fromJson(Map<String, dynamic> json, {required DashboardEditorRegistry registry})

  Deserializes a row from JSON and passes the registry to columns/components.

• toJson

  Map<String, dynamic> toJson()

  Serializes the row to JSON.

A horizontal container for 1-6 columns.

---

DashboardColumn

Class Signature

Properties

Property	Type	Default	Description
id	String	--	Unique column identifier
flex	int	1	Flex factor (1-6)
component	ComponentInstance?	null	Component (null if empty)
isEmpty	bool	--	component == null
hasComponent	bool	--	component != null

Methods

• DashboardColumn.empty

  factory DashboardColumn.empty(String id, {int flex = 1})

  Creates an empty column.

• DashboardColumn.withComponent

  factory DashboardColumn.withComponent(String id, ComponentInstance component, {int flex = 1})

  Creates a column pre-populated with a component.

• copyWith

  DashboardColumn copyWith({
    String? id,
    int? flex,
    ComponentInstance? component,
    bool clearComponent = false,
  })

  Returns a copy with updated fields.

• fromJson

  factory DashboardColumn.fromJson(Map<String, dynamic> json, {required DashboardEditorRegistry registry})

  Deserializes a column from JSON and passes the registry to the component instance.

• toJson

  Map<String, dynamic> toJson()

  Serializes the column to JSON.

A vertical slot within a row that holds zero or one component.

---

ComponentInstance

Class Signature

Properties

Property	Type	Default	Description
id	String	--	Unique component identifier
componentKey	String	--	References registered component
title	String?	null	Optional display title
properties	PropertyCollection	--	Type-safe component configuration
metadata	Map<String, dynamic>?	null	Optional metadata

Methods

• ComponentInstance.withDefaults

  factory ComponentInstance.withDefaults({
    required String id,
    required String componentKey,
    String? title,
    required DashboardEditorRegistry registry,
    Map<String, dynamic>? configOverrides,
  })

  Looks up the component in DashboardEditorRegistry, calls createProperties(), and applies overrides via fromJson.

• copyWith

  ComponentInstance copyWith({
    String? id,
    String? componentKey,
    String? title,
    PropertyCollection? properties,
    Map<String, dynamic>? metadata,
    bool clearTitle = false,
    bool clearMetadata = false,
  })

  Returns a copy with updated fields.

• fromJson

  factory ComponentInstance.fromJson(Map<String, dynamic> json, {required DashboardEditorRegistry registry})

  Deserializes a component instance and uses the registry to create the correct PropertyCollection.

• toJson

  Map<String, dynamic> toJson()

  Serializes the component instance to JSON.

A component instance placed inside a column.

---

DashboardLayoutConstants

Class Signature

Properties

Property	Type	Default	Description
cellGap	double	16.0	Gap between rows and columns
minCellHeight	double	60.0	Default minimum row height
maxCellHeight	double	800.0	Maximum row height
fillRowEditorPreviewHeight	double	200.0	Preview height for viewport-fraction rows in editor
toolbarHeight	double	48.0	Editor toolbar height
resizeHandleHeight	double	8.0	Row resize handle height
editorInset	double	12.0	Inset padding around components in editor mode
totalFlexPerRow	int	6	Total flex units per row
minColumnFlex	int	1	Minimum flex per column

Centralized constants for the dashboard editor.

Next Steps

• Components API -- ComponentDescriptor, Registry, Descriptor
• Engine API -- Engine, Commands, Events
• Layout Model Concept -- Detailed explanation