tom_flutter_ui

> Part of the Tom Framework. © Peter Nicolai Alexis Kyaw — proprietary and > confidential.

The Flutter widget library of the Tom Framework: authorization-aware, resource-bound, observable widgets, a declarative form system, the Tom Action system, and a fluent row-based layout engine over tom_core_kernel.

Overview

tom_flutter_ui pairs the platform-neutral state, security, and resource primitives in tom_core_kernel with a Material- and Cupertino-aware widget set, a declarative form system, a behavioural action system, and a fluent row-based layout engine — so an application is assembled from authorization-aware, observable, resource-bound widgets rather than hand-wired Flutter ones.

Every Tom widget understands the kernel's cross-cutting concerns:

• a tomId / tomGroup for collective visibility control;
• the kernel's four-state TomAuthState

authorization model (hidden / disabled / read-only / editable) — the UI honours all four distinctly, eliding hidden elements from the tree, greying disabled ones, and locking read-only ones; - resource-driven colours / icons / config resolved by tomId; - observable state binding to the kernel's TomObject<T> family.

You opt into as much or as little of that as you need: the general widget kit renders with nothing but an app-level resource provider, while the form and ACL layers add reflection-backed binding and authorization on top.

Installation

dependencies:
  tom_flutter_ui:
    path: ../tom_flutter_ui

Or:

flutter pub add tom_flutter_ui --path ../tom_flutter_ui

This package is internal to the Tom workspace (publish_to: none) and is consumed by path. It targets Dart SDK ^3.11.0 / Flutter >=1.17.0 and depends on the sibling tom_core_kernel (state, security, resources, reflection). A single barrel re-exports every module:

import 'package:tom_flutter_ui/tom_flutter_ui.dart';

Features

Widget kit (widgets/)

The general-purpose widget toolkit — every common Flutter widget given a Tom wrapper that adds tomId, authorization, and resource resolution.

Type	What it is
TomElevatedButton, TomTextButton, TomIconButton	Authorization-aware buttons
TomText, TomLabel, TomBadge, TomChip	Resource-bound display widgets
TomCard , TomListTile , TomColumn , TomCenter , TomAlign	Containers & layout
TomCheckbox , TomSwitch , TomSlider , TomAutocomplete	Inputs & toggles
TomLinearProgressIndicator, TomCircularProgressIndicator	Progress
TomAlertDialog , TomAboutDialog , TomBottomSheet , TomBanner	Dialogs & surfaces
TomAnimated* (TomAnimatedContainer, TomAnimatedOpacity, …)	Animated variants
TomAclBuilder	Widget-level entry point into the ACL layout engine

ACL — advanced container layout (advanced_container_layout/)

A fluent, row-based layout engine modelled on the Java Swing StdAdvancedContainer / AdvancedContainerLike API, with first-class authorization integration.

Type	Responsibility
AclBuilder	Fluent builder — append, newRow, sizing, growth, variants
Acl / AclLayout / AclContainer	The rendered layout widgets
AclFlags	expandX / expandY / expand growth flags
AclBorderStyle, AclBorderKind, AclTitlePosition	Border & titled-group styling
AclVariant, AclRowBreakpoint, AclVariantDetector	Responsive variants & breakpoints
AclGroupVisibilityController, AclBinaryVisibilityController	Group show/hide control
AclDeviceContext, AclFormFactor, AclDensity	Adaptive device sizing inputs

Forms (forms/)

The declarative form system: the TomForm data model, validators, selectable sources, the form event bus, the Material+Cupertino style/decoration system, and the full field catalogue behind a FormFieldFamily factory.

Type	Responsibility
TomForm<T>	The form base — bind / save / discard, validation, authorization
FormFieldFamily	Factory selecting the Material or Cupertino concrete per field
TomFormStyle, TomFormStyleScope	Presets (material3, compact, bordered) + inherited scoping
LabelPlacement, DescriptionPlacement, RequiredIndicator	Field decoration controls
TomSelectableSource	Pluggable option sources (sync / async / filtered)
TomFormEvent, TomFormEventSource, TomFormEventListener	The form event bus
TomListForm, TomMasterDetailListForm, TomListFormToolbar	Collection / master-detail forms
TomFormErrorBanner, TomFormInspector	Error surfacing & debug inspection

The field catalogue spans a parallel Material/Cupertino set: string (TomFormStringInput, TomFormStringDropdown, TomFormStringRadioGroup, TomFormStringFilterChips, TomFormStringListField), boolean (TomFormBoolSwitch, TomFormBoolCheckbox, TomFormBoolToggle), numeric (TomFormIntInput, TomFormIntStepper, TomFormDoubleSlider, TomFormIntRangeField, TomFormIntListField), date/time (TomFormDateField, TomFormTimeField, TomFormDateTimeField, TomFormDurationField, TomFormDateRangeField), enum/object (TomFormEnumDropdown, TomFormEnumSegmented, TomFormObjectField, TomFormLookupField, TomFormSearchField), file (TomFormFileField, TomFormFileUpload, TomFormFileDropzone), and nullable wrappers (TomFormNStringInput, TomFormNIntInput, TomFormNDateInput, TomFormNEnumDropdown).

Theming (theme/)

Type	Responsibility
TomTheme, TomThemeScope	The Tom theme and its inherited scope
TomReadonlyStyle	The read-only field styling
TomButtonVariants	Button style-variant set

Resource & authorization inputs (resource_auth/)

Type	Responsibility
TomUIColors, TomUIIcons	Resource-resolved colour / icon namespaces
TomUIColorAdapter, TomUIIconAdapter, AllColorsAdapter	Pluggable resource adapters
TomUIAuthorization, TomUIAuthorizationAdapter	The UI authorization bridge
TomConfigProvider, TomEnvironment, TomPlatform	Config / environment inputs

Actions (actions/)

The behavioural counterpart to widgets — typed, authorization-aware actions with atomic transactions, undo/redo history, composites, and widget triggers.

Type	Responsibility
TomAction, TomSimpleAction, TomDualAction	The action base & primitives
TomActionController, TomActionContext	Action dispatch & context
TomActionTransaction, TomUndoHistory, TomUndoRedoContext	Atomicity & undo/redo
TomCompositeAction, TomCompositeStep	Composed multi-step actions
TomActionTrigger	Widget trigger binding

Foundation & groups (widget_base/, groups/, custom/)

Type	Responsibility
TomNodeBase, TomPolicyNodeBase, TomWidgetFamily	The widget / family base classes
TomStatelessWidget, TomStatefulWidget, TomState	Construction-time helpers
TomScreenElementsProviderBase, TomStyleResolvers, TomCtr	Element provider & resolvers
TomUIGroup	Collective visibility control without an id on every leaf
TomAuthGuard , TomAuthTreeView , TomEmptyState , TomErrorBoundary	Non-form composites
TomInfiniteScroll , TomLoadingOverlay , TomRadioGroup , TomSkeletonLoader	More composites

Quick start

The general widget kit renders with nothing but an app-level resource provider — no reflection or codegen required:

import 'package:flutter/material.dart';
import 'package:tom_core_kernel/tom_core_kernel.dart';
import 'package:tom_flutter_ui/tom_flutter_ui.dart';

void main() {
  // Tom widgets resolve labels/colours through the resource layer; install a
  // provider and the all-colours adapter so the kit renders with its explicit
  // values rather than failing a resource lookup.
  TomTextResourceProvider.setAppResourceProvider(
    TomTextResourceProvider.from(const {}),
  );
  TomUIColors.adapter = AllColorsAdapter();
  runApp(const MaterialApp(home: Scaffold(body: Center(child: _Demo()))));
}

class _Demo extends StatelessWidget {
  const _Demo();
  @override
  Widget build(BuildContext context) {
    // A two-row ACL layout: label + badge, then a button. Explicit text/child
    // values render without any resource entries in the provider.
    return AclBuilder()
        .append(TomText(text: 'Hello, Tom'))
        .append(TomBadge(labelText: '3', child: const Icon(Icons.star)))
        .newRow()
        .append(TomElevatedButton(
          onPressed: () {},
          child: const Text('Save'),
        ))
        .build(); // returns an Acl widget (a StatelessWidget)
  }
}

Run it with flutter run example/phase1_demo.dart for the full gallery.

Example projects

Sample	Demonstrates
example/phase1_demo.dart	A single runApp demo paging the three pillars — widget kit, custom composites, and the full Phase-1 form feature set (lifecycle, four authorization states, authorizers, nesting, validation)
example/widgets/	Per-widget usage snippets for the general kit
example/advanced_container_layout/	ACL sizing, growth, borders, variants, breakpoints
example/forms/	Form fields, validation, styles, list / master-detail forms
example/actions/	Actions, transactions, undo/redo, triggers
example/theme/ · example/resource_auth/ · example/groups/ · example/custom/ · example/widget_base/	Per-module samples

The companion demo/test apps tom_flutter_form_test and tom_flutter_ui_test exercise the whole library across dozens of interactive demos — see their demo catalogues.

> Cross-package samples. The forthcoming tom_core_samples showcases — > core_flutter_ui_showcase, core_flutter_form_showcase, > core_flutter_acl_sample, and core_flutter_acl_responsive — teach this > library surface by surface against one todo-management domain. See the > samples map for the full learning path.

Usage

A form

A TomForm is subclassed for each data model: declare the fields, build them in createFormElements(), and the form drives bind / save / discard, validation, authorization, and resource resolution for every field it owns.

@tomReflector
class AddressForm extends TomForm<AddressData> {
  AddressForm({super.parentForm}) : super(formId: 'address');

  late final TomFormStringInput street;
  late final TomFormStringInput city;

  @override
  void createFormElements() {
    // build the concrete fields and bind them to the model …
  }
}

Styling forms

TomFormStyle carries three presets — material3 (default), compact (floating labels, tighter gaps), and bordered — applied to a subtree via TomFormStyleScope. Fields below the scope resolve their decoration through it; LabelPlacement, DescriptionPlacement, and RequiredIndicator tune individual field chrome.

The ACL layout engine

AclBuilder is fluent: append() adds a component to the current row, newRow() starts a new one, setPSize / setMSize set preferred / minimum sizes, and expandX() distributes surplus width. addVariant / addRowBreakpoint make the layout responsive; AclBorderStyle + AclTitlePosition draw titled groups. build() returns an Acl widget you drop into any Flutter tree.

Actions

A TomAction is dispatched through a TomActionController; wrap mutations in a TomActionTransaction to make them atomic and undoable via the controller's TomUndoHistory, and bind an action to a widget with a TomActionTrigger.

Architecture

tom_flutter_ui
├── widget_base/                 # TomNodeBase / TomPolicyNodeBase / TomWidgetFamily,
│                                #   scope widgets, screen-elements provider, resolvers
├── theme/                       # TomTheme + style-variant system
├── resource_auth/               # TomUIColors / TomUIIcons / TomUIAuthorization adapters
├── groups/                      # TomUIGroup collective visibility
├── actions/                     # TomAction system (transactions, undo/redo, triggers)
├── advanced_container_layout/   # AclBuilder fluent row engine + Acl render widgets
├── forms/                       # TomForm model + FormFieldFamily field catalogue + styles
├── widgets/                     # general widget kit (buttons … trees, animated variants)
└── custom/                      # non-form composites (auth guard/tree, overlays, skeleton)

Every layer rests on widget_base (the TomAuthorizable contract + base classes) and resolves cross-cutting concerns through resource_auth (resources + authorization) and theme (appearance). forms, widgets, and advanced_container_layout are the three feature surfaces an app composes.

Type	Responsibility
TomNodeBase / TomPolicyNodeBase	Base widget classes carrying tomId + authorization
TomWidgetFamily	Material/Cupertino family selection
TomForm<T>	The form data model + lifecycle
FormFieldFamily	Per-field Material/Cupertino concrete factory
AclBuilder / Acl	The fluent layout builder and its rendered widget
TomAction / TomActionController	The action system entry points
TomUIColors / TomUIIcons	Resource-resolved colour / icon namespaces
TomUIGroup	Collective visibility control

Ecosystem

        tom_core_kernel  (state · security · resources · reflection)
                 │
   ┌─────────────┼──────────────────────┐
   │             │                       │
tom_core_flutter │                 tom_flutter_ui   ← this package
 (kernel-on-     │              (widget kit · forms ·
  Flutter        │               ACL · actions · theme)
  binding)       │
                 ▼
          tom_core_server / tom_core_d4rt

tom_flutter_ui is the rich UI toolkit; the lower-level kernel-on-Flutter binding lives in tom_core_flutter. Both demo harnesses (tom_flutter_form_test, tom_flutter_ui_test) target tom_flutter_ui + tom_core_kernel and do not depend on tom_core_flutter. See the repository map at ../README.md.

Further documentation

Per-module guides live in doc/: widget_base.md, theme.md, actions.md (+ tom_action_integration.md), resource_auth.md, forms.md (+ form_authorizers.md, formstyle_migration.md), groups.md, advanced_container_layout.md (+ flutter_alignments_improvements.md), widgets.md, custom.md, and debug_and_inspection_system.md. Development guidelines live in _copilot_guidelines/.

Status

• Version: 1.0.0 (publish_to: none)
• Tests: 519 test cases across 33 suites