Property<T> and Subclasses

The abstract Property<T> class is the base for all property types. Each subclass binds a Dart type to a default value, a control, and (via the registry) an editor and JSON converter.

Property

abstract

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
key	String	Yes	Unique identifier within the collection
label	String	Yes	Display label for the editor
defaultValue	T	Yes	Initial value
validators	List<PropertyValidator>	No	Validation rules
help	String?	No	Help text shown below the editor
group	String?	No	Group identifier for sectioning
required	bool	No	Adds a required validator automatically
visibleCondition	PropertyCondition?	No	Condition for visibility
enabledCondition	PropertyCondition?	No	Condition for enabled state
customKey	String?	No	Custom registry key for editor/converter lookup
metadata	Map<String, dynamic>?	No	Arbitrary metadata

Properties

Property	Type	Default	Description
control	PropertyControl<T>	--	The reactive control for this property
value	T (get/set)	--	Current value
visible	bool	--	Current visibility state
enabled	bool	--	Current enabled state
visibleNotifier	ValueNotifier<bool>	--	Visibility notifier for ValueListenableBuilder
hasChanged	bool	--	Whether the value differs from the default

Methods

• createEditor

  Widget createEditor({required BuildContext context})

  Creates the editor widget via registry lookup.

• toJson

  dynamic toJson()

  Serializes the value using the registered converter.

• fromJson

  void fromJson(dynamic json)

  Deserializes the value using the registered converter.

• getDisplayValue

  String getDisplayValue()

  Returns a human-readable value representation.

• reset

  void reset()

  Resets to the default value.

• updateVisibility

  void updateVisibility(bool visible)

  Sets visibility (called by the collection).

• updateEnabled

  void updateEnabled(bool enabled)

  Sets enabled state (called by the collection).

• copyWith

  Property<T> copyWith({...})

  Creates a copy with modified parameters.

---

PropertyControl

abstract

Class Signature

Properties

Property	Type	Default	Description
value	T? (get/set)	--	Current value
valueChanges	Stream<T?>	--	Stream of value changes
disabled	bool	--	Whether the control is disabled
valid	bool	--	Whether the control passes validation
hasErrors	bool	--	Whether there are validation errors
errors	Map<String, dynamic>	--	Current validation errors

Methods

• markAsTouched

  void markAsTouched()

  Mark the control as touched (shows errors).

• markAsUntouched

  void markAsUntouched()

  Mark the control as untouched (hides errors).

• markAsDisabled

  void markAsDisabled()

  Disable the control.

• markAsEnabled

  void markAsEnabled()

  Enable the control.

• reset

  void reset({T? value})

  Reset to a value.

• focus

  void focus()

  Request focus.

Reactive wrapper around a typed value. Provides value access, validation state, and enabled/disabled control.

---

PropertyListControl

abstract

Class Signature

Properties

Property	Type	Default	Description
items	List<T>	--	Current items
length	int	--	Number of items
valueChanges	Stream<List<T?>?>	--	Stream of list changes
itemControls	List<PropertyControl<T>>	--	Per-item reactive controls

Methods

• add

  void add(T item)

  Append an item.

• removeAt

  void removeAt(int index)

  Remove the item at the given index.

• insert

  void insert(int index, T item)

  Insert an item at the given position.

• move

  void move(int oldIndex, int newIndex)

  Reorder items.

• clear

  void clear()

  Remove all items.

• replaceAt

  void replaceAt(int index, T item)

  Replace the item at the given position.

Reactive control for list properties.

---

PropertyEditor

abstract

Class Signature

Methods

• createEditor

  Widget createEditor({required BuildContext context, required PropertyControl<T> control, required String label, required String name, String? help})

  Creates a Flutter widget for editing a property value.

Interface for property editor implementations. Each property type has a registered editor in PropertySystem.

---

Built-in Concrete Properties

The following concrete subclasses cover the basic Dart types. Each has a single-argument constructor that omits explicit configuration; the table below summarizes the type, default value, and builder shorthand.

Class	Dart Type	Default Value	Builder Shorthand
StringProperty	String	''	b.string(key, label, ...)
IntProperty	int	0	b.integer(key, label, ...)
DoubleProperty	double	0.0	b.decimal(key, label, ...)
BoolProperty	bool	false	b.boolean(key, label, ...)
DateTimeProperty	DateTime	DateTime.now()	b.dateTime(key, label, ...)

DateTimeProperty overrides getDisplayValue() to return a formatted date string.

Optional Variants

Optional variants accept null and provide a convenience getter that returns a fallback value.

Class	Type	Default	Builder	Fallback Getter
OptionalStringProperty	String?	null	optionalText()	stringValue -> ''
OptionalIntProperty	int?	null	optionalInteger()	intValue -> 0
OptionalDoubleProperty	double?	null	optionalDecimal()	doubleValue -> 0.0
OptionalBoolProperty	bool?	null	optionalBoolean()	--
OptionalDateTimeProperty	DateTime?	null	optionalDateTime()	--

---

EnumProperty

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
options	List<EnumOption<T>>	Yes	List of selectable options
defaultValue	T?	No	Defaults to first option if not specified

EnumOption<T>

Property	Type	Default	Description
value	T	--	The typed value
title	String	--	Display label
description	String?	--	Optional description

Notes

Auto-registers EnumOptionsJsonConverter<T> on construction. Builder shorthand: b.enumeration<T>(key, label, options:, defaultValue:).

A property that constrains the value to one of a typed list of options.

---

ListProperty

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
getItemId	String Function(T)?	No	ID extractor for stable keys
maxItems	int?	No	Maximum number of items
minItems	int?	No	Minimum number of items

Methods

• items

  List<T> get items

  Current list of values.

• listControl

  PropertyListControl<T> get listControl

  Underlying list control for advanced operations.

• add

  void add(T item)

  Append an item.

• remove

  void remove(T item)

  Remove by value.

• removeAt

  void removeAt(int index)

  Remove by index.

• insert

  void insert(int index, T item)

  Insert an item at the given position.

• move

  void move(int oldIndex, int newIndex)

  Reorder items.

• replaceAt

  void replaceAt(int index, T item)

  Replace at position.

• clear

  void clear()

  Remove all items.

A property whose value is a list of typed items.

---

UnionProperty

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
options	List<UnionOption>	Yes	List of union options
defaultSelectedKey	String	Yes	Key of the initially selected option

Properties

Property	Type	Default	Description
selectedKey	String	--	Currently selected option key
selectedProperty	Property?	--	Currently selected option's property
selectedOption	UnionOption?	--	Currently selected option

Methods

• selectOption

  void selectOption(String key)

  Change the selected option.

UnionOption

Property	Type	Default	Description
key	String	--	Unique option key
title	String	--	Display label
description	String?	--	Optional description
property	Property	--	The property for this option
icon	Widget?	--	Optional icon
metadata	Map<String, dynamic>?	--	Arbitrary metadata

JSON Format

A UnionProperty serializes to a map with two keys: "selectedKey" identifying the chosen option and "selectedValue" carrying that option's serialized value, e.g. {"selectedKey": "fixed", "selectedValue": "2026-04-01"}.

A discriminated-union property whose value is the selected option's key. Each option carries its own nested Property.

---

ReadOnlyProperty

Class Signature

Constructor Parameters

Parameter	Type	Required	Description
formatter	String Function(T)?	No	Custom display formatter

Properties

Property	Type	Default	Description
displayValue	String	--	Formatted display string

Notes

Uses a customKey of readonly:<type> (e.g. readonly:string) to select a read-only editor from the registry. Builder shorthand: b.readonly<T>(key, label, defaultValue:).

A property whose value cannot be edited by the user. Useful for derived, computed, or system-set values.

Next Steps

• PropertyCollection API -- Collection, builder, editor
• Conditions API -- All condition types
• Validators API -- Validator reference