PropertyCollection, Builder, Editor, Derivation

PropertyCollection

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
groups	List<PropertyGroup>	No	Initial groups (an auto-created general group is added if needed)
properties	List<Property>	No	Initial properties — validated against declared groups on construction

Properties

Property	Type	Default	Description
properties	List<Property>	--	All properties in insertion order
groups	List<PropertyGroup>	--	All groups (including the auto-created general group)
values	Map<String, dynamic>	--	Current values snapshot
valueChanges	Stream<Map<String, dynamic>?>	--	Stream of all value changes
length	int	--	Property count
isEmpty	bool	--	Whether the collection has no properties
isNotEmpty	bool	--	Whether the collection has properties
isValid	bool	--	Whether all properties pass validation
hasChanges	bool	--	Whether any value differs from its default
validationErrors	List<String>	--	Error messages for invalid properties

Methods

• getProperty

  Property? getProperty(String key)

  Get a property by key.

• hasProperty

  bool hasProperty(String key)

  Check whether a property exists.

• getValue

  T getValue<T>(String key)

  Type-safe value access (throws on type mismatch).

• setValue

  void setValue<T>(String key, T value)

  Type-safe value set.

• getPropertiesByGroup

  List<Property> getPropertiesByGroup(String value)

  Get the properties belonging to a group.

• getGroupByValue

  PropertyGroup? getGroupByValue(String value)

  Get a specific group.

• hasGroup

  bool hasGroup(String groupValue)

  Check whether a group exists.

• addProperty

  void addProperty(Property property)

  Add a single property.

• addProperties

  void addProperties(List<Property> properties)

  Add multiple properties efficiently — sets up reactions once.

• removeProperty

  void removeProperty(String key)

  Remove a property by key.

• addGroup

  void addGroup(PropertyGroup group)

  Add a group.

• addGroups

  void addGroups(List<PropertyGroup> groups)

  Add multiple groups.

• removeGroup

  void removeGroup(String groupValue)

  Remove a group.

• clearGroups

  void clearGroups()

  Remove all groups.

• clear

  void clear()

  Remove all properties and dispose reactions.

• validateAll

  Map<String, String> validateAll()

  Returns error messages keyed by property key.

• toJson

  Map<String, dynamic> toJson()

  Returns a map of all property values.

• fromJson

  void fromJson(Map<String, dynamic> json)

  Restore values from a JSON map.

• resetAll

  void resetAll()

  Reset all properties to their default values.

• clone

  PropertyCollection clone()

  Deep clone the collection.

• copyFrom

  void copyFrom(PropertyCollection other)

  Replace contents with those of another collection.

• addDerivations

  void addDerivations(List<PropertyDerivation> list)

  Register derivation rules and wire subscriptions.

• markDerivationsAsDirty

  void markDerivationsAsDirty()

  Mark all derivations as user-edited (skips auto-derivation).

• createEditor

  PropertyCollectionEditor createEditor({required BuildContext context, bool showGroups, bool shrinkwrap, bool scrollable, bool disposeCollection})

  Create a PropertyCollectionEditor widget.

• createSingleLineEditor

  Widget createSingleLineEditor({required BuildContext context, List<int>? flexValues})

  Create a horizontal row of editors.

• setupReactions

  void setupReactions()

  Set up condition evaluation (called automatically).

• dispose

  void dispose()

  Cancel all subscriptions.

Container for properties with shared validation, condition evaluation, serialization, and UI rendering.

---

PropertyGroup

Class Signature

Properties

Property	Type	Default	Description
value	String	--	Unique identifier
title	String	--	Display title
collapsible	bool	true	Whether the group can be collapsed
initiallyCollapsed	bool	false	Whether to start collapsed
showHeader	bool	true	Whether to show the group header

Factory Constructors

• PropertyGroup.collapsible

  PropertyGroup.collapsible({required String value, required String title, bool initiallyCollapsed = false})

  Collapsible group rendered as an ExpansionTile.

• PropertyGroup.fixed

  PropertyGroup.fixed({required String value, required String title, bool showHeader = true})

  Non-collapsible group.

• PropertyGroup.general

  PropertyGroup.general({String title = 'General', bool showHeader = true})

  Auto-created group for ungrouped properties.

Configuration for how a property group is displayed.

---

PropertyCollectionBuilder

Class Signature

Methods

• group

  PropertyCollectionBuilder group(String value, String title, {bool collapsible, bool initiallyCollapsed})

  Start a group context — subsequent properties belong to this group until endGroup().

• endGroup

  PropertyCollectionBuilder endGroup()

  End the current group context.

• string

  StringProperty string(String key, String label, {...})

  Add a string property.

• optionalText

  OptionalStringProperty optionalText(String key, String label, {...})

  Add a nullable string property.

• integer

  IntProperty integer(String key, String label, {...})

  Add an integer property.

• optionalInteger

  OptionalIntProperty optionalInteger(String key, String label, {...})

  Add a nullable integer property.

• decimal

  DoubleProperty decimal(String key, String label, {...})

  Add a double property.

• optionalDecimal

  OptionalDoubleProperty optionalDecimal(String key, String label, {...})

  Add a nullable double property.

• boolean

  BoolProperty boolean(String key, String label, {...})

  Add a boolean property.

• optionalBoolean

  OptionalBoolProperty optionalBoolean(String key, String label, {...})

  Add a nullable boolean property.

• dateTime

  DateTimeProperty dateTime(String key, String label, {...})

  Add a DateTime property.

• optionalDateTime

  OptionalDateTimeProperty optionalDateTime(String key, String label, {...})

  Add a nullable DateTime property.

• enumeration

  EnumProperty<T> enumeration<T>(String key, String label, {required List<EnumOption<T>> options, T? defaultValue, ...})

  Add an enum property.

• list

  ListProperty<T> list<T>(String key, String label, {...})

  Add a list property.

• readonly

  ReadOnlyProperty<T> readonly<T>(String key, String label, {required T defaultValue, ...})

  Add a read-only property.

• derivedProperty

  PropertyCollectionBuilder derivedProperty(String target, {required Set<String> from, required Function transformer, bool initiallyDirty = false})

  Add a derivation rule that auto-computes the target property from source properties.

• buildCollection

  PropertyCollection buildCollection()

  Build the complete collection with groups and derivations.

• buildList

  List<Property> buildList()

  Build only the property list (without groups).

Static Condition Helpers

• when

  static EqualsCondition<T> when<T>(String key, T value)

  Equals condition shorthand.

• whenNot

  static NotEqualsCondition<T> whenNot<T>(String key, T value)

  Not-equals condition shorthand.

• whenIn

  static InCondition<T> whenIn<T>(String key, Set<T> values)

  In-set condition shorthand.

• whenNotIn

  static NotInCondition<T> whenNotIn<T>(String key, Set<T> values)

  Not-in-set condition shorthand.

• whenTrue

  static EqualsCondition<bool> whenTrue(String key)

  Equals true (boolean) condition.

• whenFalse

  static EqualsCondition<bool> whenFalse(String key)

  Equals false (boolean) condition.

• whenHasValue

  static HasValueCondition whenHasValue(String key)

  Property has a non-null value.

• whenAll

  static AndCondition whenAll(List<PropertyCondition> conditions)

  All child conditions must be true.

• whenAny

  static OrCondition whenAny(List<PropertyCondition> conditions)

  Any child condition must be true.

• whenGreaterThan

  static ComparisonCondition<T> whenGreaterThan<T extends num>(String key, T value)

  Numeric greater-than condition.

• whenLessThan

  static ComparisonCondition<T> whenLessThan<T extends num>(String key, T value)

  Numeric less-than condition.

• whenCustom

  static CustomCondition whenCustom({required List<String> dependencies, required bool Function(PropertyCollection) evaluator})

  Custom condition with explicit dependencies.

Fluent builder for constructing PropertyCollection instances.

---

PropertyCollectionEditor

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
collection	PropertyCollection	Yes	The collection to render
onChanged	VoidCallback?	No	Called on any value change
showGroups	bool	No	Whether to render group headers
shrinkWrap	bool	No	Whether to shrink-wrap the list
scrollable	bool	No	Whether to enable scrolling
disposeCollection	bool	No	Whether to dispose the collection on widget dispose

Widget that renders a PropertyCollection as an editable form.

---

PropertyDerivation

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
targetProperty	String	Yes	Key of the property to auto-compute
sourceProperties	Set<String>	Yes	Keys of source properties to watch
transformer	dynamic Function(Map<String, dynamic>)	Yes	Computes the target value from current source values
initiallyDirty	bool	No	Skip derivation on initialization

Behavior

A change in any source property triggers the transformer. If the user manually edits the target, derivation stops (the property becomes "dirty"). Clearing the target resumes derivation. Call collection.markDerivationsAsDirty() after loading data to prevent auto-derivation from overwriting loaded values.

Defines how a target property's value is auto-computed from source properties.

Next Steps

• Property<T> API -- Property and control reference
• Conditions API -- All condition types
• Glossary -- Terms and definitions