TolyUI Documentation

The tolyui_rx_layout module provides responsive layout capabilities for Flutter. It extends standard layout widgets with reactive properties and responsive design features, including:

• Enhanced Row Support: Includes properties for gutter, verticalGutter, padding, align, and justify.
• Cell Manipulation: Supports offset, push, and pull for fine-grained positioning.
• Responsive Sizing and Padding: Provides Size$ and Padding$ abstractions for reactive dimension management.
• Window-based Responsiveness: Includes WindowRespondBuilder to build UIs that react to window/screen size changes.
• Theme Integration: Supports setting RxParserStrategy via ThemeData to control how reactive values are parsed and applied.

TolyUI is a modern responsive UI component library for Flutter, designed for multi-platform use. It follows a Monorepo + Modular architecture, meaning UI components are split into independent Flutter Packages that can be published to pub.dev and imported individually. This allows for on-demand inclusion to keep application sizes small.

Key Characteristics:

• Modular: Components are organized into independent packages (e.g., tolyui_text, tolyui_table).
• Responsive: Built with a 5-level breakpoint system to support everything from mobile phones to large desktop screens.
• Type-Safe: Designed with Flutter/Dart best practices for reliability.
• Showcase App: Includes an interactive application for online previews and documentation.

TolyUI is designed with a modular architecture where components are organized into independent Flutter packages. This allows for on-demand imports, meaning you only include the code for the components you actually use, which helps minimize the final application size.

Modules are categorized as follows:

• Basic: Core components like Buttons, Icons, and Layouts.
• Form: Input fields, Selectors, Checkboxes, etc.
• Navigation: Tabs, Steps, Breadcrumbs, and Menus.
• Data: Complex data displays like Trees (supporting virtual scrolling and drag-and-drop), Tables, Cards, and Pagination.
• Feedback: Messages, Notifications, Loading indicators, and Tooltips.
• Advanced: Specialized components like Color pickers and Device frames.

TolySheet uses a reactive data stream design. Data changes automatically trigger UI updates through the following flow:

SheetDataProvider $\rightarrow$ Stream<SheetDataSnapshot> $\rightarrow$ TolySheet $\rightarrow$ UI

This design natively supports asynchronous data loading and real-time updates because the component listens to the stream emitted by the provider.

TolySheet uses a unique naming convention and a layered architecture to manage data-heavy tables. Instead of traditional 'Grid' or 'Table' terms, it uses a 'Sheet' concept.

Core Terminology

• Sheet: The data table itself.
• Field: A data column.
• Pick: Data selection (e.g., single/multiple selection).
• Pin: Pinning a field (freezing columns).
• Provider: The data source (local, remote, or stream).
• Strategy: Behavioral configurations (e.g., how scrolling or editing works).
• Capability: Field-specific features (e.g., sorting or filtering).
• Spec: The definition of a field.

Layered Architecture

1. TolySheet (View): The presentation layer.
2. SheetController (Control): The control layer.
3. SheetDataProvider (Data): The data layer.
4. Strategy/Capability (Behavior): The behavior layer.

The transition from TolyTable to TolySheet represents a shift toward a more decoupled architecture using the Provider pattern.

• Data Management: TolyTable uses a direct dataSource property. TolySheet uses a provider property (typically LocalSheetProvider) to manage data flow.
• Column Definition: TableColumn is replaced by FieldSpec.
• Rendering Logic: Instead of dataIndex or render, TolySheet uses a builder function that provides a context (ctx) to access the current row's data (ctx.data).
• Separation of Concerns: Visual styling (like borders) is moved to appearance, and interactive logic (like selection) is moved to behavior.

Instead of deep inheritance, TolySheet uses the Strategy Pattern to define how the table interacts with users. You can compose different strategies to achieve complex requirements.

Available strategies include:

• PickStrategy: Defines selection modes (e.g., single, multiple, or range selection).
• ScrollStrategy: Defines scrolling behavior (e.g., virtualization/buffering).
• ExpandStrategy: Defines how rows expand (e.g., master-detail or nested tables).
• EditStrategy: Defines editing modes (e.g., cell-level or row-level editing).
• GroupStrategy: Defines data grouping and folding logic.

TolyUI uses go_router for declarative routing. Routes are managed centrally, typically within the lib/navigation directory. This allows for structured navigation patterns such as:

• Path-based routing (e.g., /home)
• Parameterized routes (e.g., /details/:id)
• Settings or configuration routes (e.g., /settings)

TolyUI provides two distinct modes for handling list scrolling and jumping to specific indices, depending on your precision requirements:

1. Standard Mode: Designed for use with existing native ListView widgets. It uses a "blind jump + correction" approach. It performs an approximate jump based on estimated heights and then performs a secondary alignment once the actual components are loaded and their real heights are reported.
2. Enhanced Mode (Strict Mode / TolyPositionedList): Designed for professional, massive long lists where 100% jump precision is required without visual jitter. It implements a "Logical Anchor Layout" using a two-way Sliver architecture (one Sliver for items after the target index and one for items before it) and maintains a logical coordinate system of (Index, Offset) rather than relying solely on physical pixels.