Implement Flet Extension

Implement a Flet extension around an external Flutter package using existing flet_* packages as implementation templates.

Inputs

• Control/service name and Python package name (flet_<extension>).
• Target pub.dev package and intended version/range.
• API surface to expose in Python (properties, methods, events, types/enums).

Third-party Dependency Gate

1. Confirm package health: maintenance activity, null-safety, platform support, and open issue risk.
2. Confirm license is compatible with Flet distribution.
3. Select a conservative version strategy:

• Pin exact version when behavior stability is critical.
• Use bounded ranges when required by ecosystem constraints.

4. Record key constraints and reasons in PR notes/commit message.

Control/Service Classification

• Classify wrapped functionality before implementation:

1. LayoutControl for visual controls that participate in page/layout positioning.
2. Base Control for simple visual controls that do not require page positioning or define their own positioning rules/props (for example Draggable, Divider, MenuBar, NavigationRail).
3. Non-visual Service when functionality is not a renderable UI control.

• Inspect the wrapped Flutter package API to determine whether it includes non-visual/service functionality.
• For service patterns, follow existing extension examples: sdk/python/packages/flet-audio, sdk/python/packages/flet-flashlight, sdk/python/packages/flet-secure-storage.

API Mapping Rules

• Expose only stable and useful features first; avoid mirroring every upstream option.
• Keep Python API idiomatic and concise; avoid redundant control-name prefixes.
• Map upstream naming inconsistencies to Flet conventions when needed.
• Add custom enums/types only when they improve correctness and discoverability.

Python-side Rules

• Use LayoutControl, base Control, or Service base class according to classification.
• Implement typed properties, methods, and events exactly for chosen public API.
• Reuse existing serialization/event patterns from sibling controls/services.

Flutter-side Rules

• Use parseEnum() for enums — it's exported from package:flet/flet.dart. Call it as parseEnum(MyEnum.values, widget.control.getString("attr"), MyEnum.defaultVal)!. Do NOT write a custom _parseXxx() switch helper.
• For control attributes, prefer widget.control.getBool()/getDouble()/... accessors.
• For non-control parsing, use shared parseSomething() helpers.
• Do not add one-off private parser utilities when standard helpers exist.
• Put control-specific helpers in utils/<control>.dart; shared helpers in utils/<topic>.dart.
• Prefer parse-prefixed helper names when converting input to Flutter structures.
• Avoid single-use local variables.

Default Value Matching (Critical)

Properties with default values on the Python side are not sent to Flutter when unchanged from the default. Every Dart property read must provide the same default as its Python counterpart:

• control.getDouble("size", 100.0)! when Python has size: float = 100.0
• control.getBool("animate", true)! when Python has animate: bool = True
• parseDuration(value["dur"], const Duration(milliseconds: 500))! when Python has dur: DurationValue = field(default_factory=lambda: Duration(milliseconds=500))
• control.get<List>("items")?.map(...).toList() ?? const [] when Python has items: list[str] = field(default_factory=list)

Without matching defaults, Dart receives null and either crashes or silently uses the wrong value. This applies to all property types: bools, numbers, strings, enums, durations, collections, and nested @ft.value types.

Integration Checklist

• Register in the Flet client app — two files:
  1. client/pubspec.yaml: add flet_<ext>: path: ../sdk/python/packages/flet-<ext>/src/flutter/flet_<ext> under dependencies.
  2. client/lib/main.dart: add import 'package:flet_<ext>/flet_<ext>.dart' as flet_<ext>; and flet_<ext>.Extension() to the extensions list.
• Add extension package to sdk/python/pyproject.toml in two places: the dependencies list and [tool.uv.sources] as { workspace = true }.
• Add extension to sdk/python/packages/flet/pyproject.toml in the [dependency-groups] extensions list.
• Add extension to sdk/python/examples/apps/flet_build_test/pyproject.toml in three places: [project] dependencies, [tool.uv.sources] as { path = "...", editable = true }, and [tool.flet.dev_packages] as a relative path string.
• Add extension to tools/crocodocs/pyproject.toml under [tool.crocodocs.packages] as <pkg_name> = "../../sdk/python/packages/<pkg-dir>/src". This fixes "Missing API entry" errors in the docs. Note: api-data.json is gitignored (generated at build time); only the pyproject.toml change needs committing.
• Add extension to .github/workflows/ci.yml in both places:
  • build_flet_extensions -> PACKAGES list.
  • py_publish -> for pkg in ... publish loop.
• Add .gitignore to Flutter extension project if missing.
• Remove [tool.uv.sources] local path overrides from example pyproject.toml files before opening a PR (they are development-only conveniences).