osamaalhimyari/frappe_form

1. Repository purpose

- This is a Flutter package named around frappe_form that renders a Frappe DocType form UI, applies field-level behavior/validation, and converts user input into a response payload.

- It is not a full app; the real product is the reusable library in lib/, with a separate example/ Flutter app used to demonstrate and validate behavior across platforms.

2. Public package boundary

- The main package entrypoint is lib/frappe_form.dart.

- The package exposes a form-rendering surface centered on DocFormView, plus supporting entities, controllers, and widget overrides so consumers can embed the form into their own app and customize some field behaviors.

3. Core data model layer

- lib/src/entity/ contains the schema objects that represent the Frappe form definition: DocForm, DocField, DocType, DocGeolocation, and enumerations for field/type metadata.

- lib/src/model/ holds runtime/user-input models such as DocFieldAnswer, DocFieldBundle, attachments, dependency controllers, render rules, and some newer domain models like dashboard and transaction objects.

- The presence of *.g.dart files indicates code generation is used for serialization and/or boilerplate reduction.

4. Form orchestration and business logic

- lib/src/logic/doc_form_controller.dart and doc_field_group_controller.dart coordinate the form lifecycle, field grouping, dependency evaluation, and response assembly.

- The logic/enumerator/ folder defines how dependency expressions are interpreted, including arithmetic, behavior, condition, and operator handling for “depends on” rules.

- Utility helpers under logic/utils/ provide reusable conversion and evaluation support for booleans, dates, numbers, text, time, iteration, and parameter handling.

5. Presentation layer architecture

- lib/src/presentation/widgets/ contains the actual UI for the form and its field renderers.

- doc_form_view.dart is the main composite widget; doc_form_loading_view.dart handles loading state.

- Field rendering is split by capability and field family: base, text input, choice, date, boolean, attachment, location, display, group, and the newer custom field set.

6. Field-to-widget mapping

- The architecture is essentially a dispatcher: each DocField.type maps to a dedicated widget implementation.

- Examples include text editors, phone input, date/time pickers, HTML rendering, select/radio/check controls, geolocation, signatures, attachments, and table/group layouts.

- This makes the form renderer extensible without changing the entire form container.

7. Customization hook for unsupported or special fields

- DocFormController exposes an onBuildFieldView hook used to override or inject custom widgets for specific field types.

- The README example shows this being used for dashboard-style custom fields like heatmaps and connections, which are not part of the core Frappe field set but are supported through application-level overrides.

8. Localization and validation

- lib/src/presentation/localization/ provides English and Spanish defaults plus a base localization contract for extension.

- Validation and formatting utilities live under presentation/utils/, keeping input formatting, keyboard behavior, phone formatting, and validation messages separate from field widgets.

- The form view uses these utilities to enforce required fields, read-only behavior, and dependency-based visibility/mandatory rules.

9. External capability boundaries

- Some functionality is intentionally delegated to the host app rather than embedded in the package, especially attachment loading and dynamic link suggestion lookup.

- The README also shows link and HTML rendering can rely on external plugins/services such as url_launcher and webview-based editors, but the package keeps those as UI integrations rather than owning backend access.

10. Platform strategy

- The package is designed for Flutter’s cross-platform runtime and is exercised on Android, iOS, web, macOS, Linux, and Windows via the example/ app.

- The repo includes generated platform scaffolding plus web build artifacts under docs/, suggesting the package is also published with a Flutter web documentation/demo build.

11. Example application as the integration reference

- example/lib/main.dart and its helper files show the intended consumption pattern: load a DocForm, provide callbacks like onSubmit, onCancel, onResponse, fetchSuggestions, and custom field builders, then render DocFormView.

- This example app is effectively the architecture reference for consumers, demonstrating how dynamic link resolution, attachment handling, and custom field rendering flow through the package API.

12. Generated and build support

- build.yaml, analysis_options.yaml, and the *.g.dart files indicate a codegen-oriented workflow.

- The docs/ directory contains compiled Flutter web assets and service worker/bootstrap files, which are deployment artifacts rather than source architecture, but they confirm the package is built and distributed with a web demo/documentation target in mind.