# sinasys/items_selector architecture

> Architecture diagram of the GitHub repository sinasys/items_selector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sinasys/items_selector
- Repository: https://github.com/sinasys/items_selector

## Overview

##### Project Type & Purpose
- This is a Flutter package designed to provide flexible item selection widgets (ListSelector, GridSelector, WrapSelector) with support for both single and multi-selection modes.
- It is built to be generic and adaptable to any data type, complete with customizable UI and state management internally. Furthermore, it includes an “example” application that demonstrates multi-platform usage (Android, iOS, web, Windows), serving both as a demo and integration reference.

##### File Structure Analysis
- The project splits into two major parts:
– The core library (found in the “lib” directory) which includes:
▸ Main entry point (items_selector.dart)
▸ Source code under “lib/src” divided into subdirectories for models, utilities, and widget implementations.
– Cross-platform example projects (located in the “example” directory) with subdirectories for Android, iOS, web, and Windows. This section shows how the package can integrate into a typical Flutter multi-platform application.
- Notable directories: “lib/src/model”, “lib/src/utils”, “lib/src/widget” indicate clear separation of concerns for the business logic (models & configurations) and the UI layer (widgets).
- Presence of configuration files (pubspec.yaml, build.gradle, etc.) confirms standard Flutter project practices and multi-target deployments.

##### Insights from the README
- The README details the package’s features, widget types, configuration options, and usage code snippets.
- It explains how selection behavior is controlled by different option classes (SingleSelectOptions and MultiSelectOptions), and how layout-specific configurations are handled (list, grid, wrap configurations).
- It provides concrete examples which can be visualized as interactions between:
- The widget layer that renders items.
- The state management and option configurations that determine selection behavior.
- The underlying model layer ensuring generic support (overriding equality for custom classes).

##### Key Components
a. Core Package Library:
– Model Components: Represent classes like BaseSelector, GridConfiguration, ListConfiguration, WrapConfiguration, and various options.
– Utility Components: Extensions, mixins (for selection handling), and type definitions.
– Widget Components: ListSelector, GridSelector, and WrapSelector; each with different constructors and corresponding layouts.
b. Example Application:
– Multi-platform wrappers under the “example” directory, which include Android, iOS, web, and Windows projects.
– Integration points where the package’s widgets are demonstrated in actual Flutter apps.
c. External Dependencies & Flutter Framework Integration:
– Emphasize how the package relies on Flutter’s widget system, rendering logic, and state management.
– If applicable, note the integration with the Equatable package (as mentioned in the README) for proper equality checks.

##### Relationships and Interactions
– The “Model” layer and the “Widget” layer: Models provide configuration and behavior that widgets use to render UI and manage selections.
– How the “Example” projects instantiate and use the core widgets and options to render different layouts.
– Interaction with Flutter’s rendering framework and state management (highlighting built-in state changes upon item selection).

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear division into models, utilities, and UI components.
- Layered Architecture: Distinguish between the core library (for selection logic) and the cross-platform example (integration and presentation).
- Customizability & Extensibility: Emphasize that the widget layer is highly customizable (through builder functions) and supports generic data types.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Package Section
    subgraph "Core Package"
        direction TB
        CoreEntry["Entry Point (Core)"]:::core
        subgraph "Models/Configurations"
            direction TB
            BaseSelector["Base Selector"]:::model
            GridConfig["Grid Configuration"]:::model
            ListConfig["List Configuration"]:::model
            WrapConfig["Wrap Configuration"]:::model
            ItemSelector["Item Selector"]:::model
            ItemWrapper["Item Wrapper"]:::model
            SelectOptions["Select Options"]:::model
            SelectionMode["Selection Mode"]:::model
        end
        subgraph "Utilities"
            direction TB
            Extensions["Extensions"]:::utility
            MultiSelectMixin["Multi Select Util Mixin"]:::utility
            SingleSelectMixin["Single Select Util Mixin"]:::utility
            TypeDefs["TypeDefs"]:::utility
        end
        subgraph "Widgets"
            direction TB
            ListSelector["ListSelector"]:::widget
            GridSelector["GridSelector"]:::widget
            WrapSelector["WrapSelector"]:::widget
        end
    end

    %% Example Application Section
    subgraph "Example Application"
        direction TB
        ExampleEntry["Example Root"]:::example
        ListSelectorEx["ListSelector Example"]:::example
        GridSelectorEx["GridSelector Example"]:::example
        WrapSelectorEx["WrapSelector Example"]:::example
        Android["Android"]:::example
        iOS["iOS"]:::example
        Web["Web"]:::example
        Windows["Windows"]:::example
    end

    %% External Dependencies Section
    subgraph "External Dependencies"
        direction TB
        Flutter["Flutter Framework"]:::external
        Equatable["Equatable Package"]:::external
    end

    %% Internal Relationships within Core Package
    CoreEntry -->|"triggers"| BaseSelector
    CoreEntry -->|"initializes"| Extensions

    BaseSelector -->|"extendsTo"| GridConfig
    BaseSelector -->|"extendsTo"| ListConfig
    BaseSelector -->|"extendsTo"| WrapConfig

    BaseSelector -->|"configures"| ListSelector
    BaseSelector -->|"configures"| GridSelector
    BaseSelector -->|"configures"| WrapSelector

    SelectOptions -->|"influences"| ListSelector
    SelectOptions -->|"influences"| GridSelector
    SelectOptions -->|"influences"| WrapSelector

    Extensions --- BaseSelector
    MultiSelectMixin --- SelectOptions
    SingleSelectMixin --- SelectOptions
    TypeDefs --- BaseSelector

    %% External Dependencies Relationships
    Flutter -->|"renders"| ListSelector
    Flutter -->|"renders"| GridSelector
    Flutter -->|"renders"| WrapSelector
    Flutter -->|"supports"| CoreEntry
    Equatable -->|"integratesWith"| BaseSelector

    %% Example Application to Core Package Communication
    ExampleEntry -->|"utilizes"| ListSelector
    ExampleEntry -->|"utilizes"| GridSelector
    ExampleEntry -->|"utilizes"| WrapSelector

    ListSelectorEx -->|"instantiates"| ListSelector
    GridSelectorEx -->|"instantiates"| GridSelector
    WrapSelectorEx -->|"instantiates"| WrapSelector

    Android -->|"hosts"| ExampleEntry
    iOS -->|"hosts"| ExampleEntry
    Web -->|"hosts"| ExampleEntry
    Windows -->|"hosts"| ExampleEntry

    %% User Interaction Flow
    ListSelector -->|"onTapEvent"| CoreEntry
    GridSelector -->|"onTapEvent"| CoreEntry
    WrapSelector -->|"onTapEvent"| CoreEntry

    %% Click Events for Core Package Entry Point & Model Components
    click CoreEntry "https://github.com/sinasys/items_selector/blob/master/lib/items_selector.dart"
    click BaseSelector "https://github.com/sinasys/items_selector/blob/master/lib/src/model/base_selector.dart"
    click GridConfig "https://github.com/sinasys/items_selector/blob/master/lib/src/model/grid_configuration.dart"
    click ListConfig "https://github.com/sinasys/items_selector/blob/master/lib/src/model/list_configuration.dart"
    click WrapConfig "https://github.com/sinasys/items_selector/blob/master/lib/src/model/wrap_configuration.dart"
    click ItemSelector "https://github.com/sinasys/items_selector/blob/master/lib/src/model/item_selector.dart"
    click ItemWrapper "https://github.com/sinasys/items_selector/blob/master/lib/src/model/item_wrapper.dart"
    click SelectOptions "https://github.com/sinasys/items_selector/blob/master/lib/src/model/select_options.dart"
    click SelectionMode "https://github.com/sinasys/items_selector/blob/master/lib/src/model/selection_mode.dart"

    %% Click Events for Utility Components
    click Extensions "https://github.com/sinasys/items_selector/blob/master/lib/src/utils/extensions.dart"
    click MultiSelectMixin "https://github.com/sinasys/items_selector/blob/master/lib/src/utils/multi_select_util_mixin.dart"
    click SingleSelectMixin "https://github.com/sinasys/items_selector/blob/master/lib/src/utils/single_select_util_mixin.dart"
    click TypeDefs "https://github.com/sinasys/items_selector/blob/master/lib/src/utils/typedefs.dart"

    %% Click Events for Widget Components
    click ListSelector "https://github.com/sinasys/items_selector/blob/master/lib/src/widget/list_selector.dart"
    click GridSelector "https://github.com/sinasys/items_selector/blob/master/lib/src/widget/grid_selector.dart"
    click WrapSelector "https://github.com/sinasys/items_selector/blob/master/lib/src/widget/wrap_selector.dart"

    %% Click Events for Example Application Components
    click ExampleEntry "https://github.com/sinasys/items_selector/tree/master/example/"
    click ListSelectorEx "https://github.com/sinasys/items_selector/tree/master/example/lib/list_selector"
    click GridSelectorEx "https://github.com/sinasys/items_selector/tree/master/example/lib/grid_selector"
    click WrapSelectorEx "https://github.com/sinasys/items_selector/tree/master/example/lib/wrap_selector"

    %% Styles
    classDef core fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef model fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef utility fill:#d5f5e3,stroke:#28b463,stroke-width:2px;
    classDef widget fill:#fadbd8,stroke:#c0392b,stroke-width:2px;
    classDef example fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef external fill:#ebdef0,stroke:#8e44ad,stroke-width:2px;
```
