Composite Family Deep Dive

selection containers, peer groups, fixed aggregates, recursive trees, and paging companions

Composite Family Deep Dive selection containers, peer groups, fixed aggregates, recursive trees, and paging companions Composite Family Deep Dive selection containers, peer groups, fixed aggregates, recursive trees, and paging companions Container primitives Composition helpers around containers CompositeVM ordered homogeneous children Current designates one selected child select_component / deselect_component ModeledCrudCommands can bind to Current GroupVM same IList surface peer children only group child select command stays disabled good for notification stacks AggregateVM1..6 heterogeneous fixed slots Component1..6 accessors factories invoked on construct() best for shells and workspaces HierarchicalVM recursive nodes with Parent / Depth / Path lazy or eager child materialization TreeStructureChangedMessage on structure changes walk / walk_expanded integrate naturally Selection semantics Current is null or contained children update IsCurrent AsyncSelection is opt-in Collection semantics shared group/composite capability Move preserves child identity one Move or batched Reset Construction semantics Constructed after children settle reference implementations visit children sequentially Tree semantics HierarchicalVM rejects ancestor cycles InvalidateChildren refreshes the child cache lazy boundaries stay explicit SearchableState filter first debounced SearchTerm filtered view source PagedComposition finite page slice implements IPageable decorates iterable source TokenPagedComposition forward-only fetch_next(token) LoadMore / Refresh accumulated Items + HasMore ForwardingCompositeVM wraps ICompositeVM<VM> override single behaviors still forwards disposal Why separate primitives CompositeVM adds Current; both families share VMCollection. AggregateVM owns fixed slots; HierarchicalVM owns trees. Paging helpers sit beside containers, not under them. same IList minus Current fixed heterogeneity recursive domain selection events lifecycle structure filter -> page finite vs token wraps

Choosing a container

  • Use CompositeVM when a current child matters.
  • Use GroupVM when children are peers and selection would be misleading.
  • Use AggregateVM when slots are heterogeneous and fixed at compile time.

Recursive vs paged

  • HierarchicalVM is the tree primitive because it carries structural metadata and mutation messages.
  • PagedComposition and TokenPagedComposition are companion views over an existing source, not alternate container bases.
  • Search/filter is idiomatically applied before finite paging.

Docs emphasis

  • This diagram is the bridge between the family map and the Notes Workspace example.
  • It explains why the framework kept several focused container types instead of flattening them.
  • It also answers the common question about where paging belongs in the architecture.