Migrating examples to projects

[FeodorFitsner]

Why?

• Metadata for better discovery by users and AI: categories, description, keywords, readme (if more information should be provided).
  We need that data for building Gallery v2, used on website and in Flet app, and building index for Flet MCP.
• Easier built/run/debug with Flet CLI. Right now I have my own ABC project somewhere, copy example to my main.py and then build with Flet CLI.
• Every example must be runnable and clonable "as is" - it should contain all dependencies (flet_charts, etc.), permissions, bundle IDs, etc, to successfully build and run.

For Gallery and MCP we need the following metadata:

• Title
• Short description
• Categories
• Tags
• Supported platforms
• Long description
• Controls used
• Layout pattern: master-detail, sidebar-dashboard, settings-page, login-form, wizard, tabbed-layout, grid-cards, list-detail, modal-flow, etc.
• Complexity: basic, intermediate, advanced
• Features (behaviours) - capture notable behaviours like: form validation, sorting, filtering, search, pagination, drag-and-drop, chart zoom, async loading, theme switching, etc.

How?

Right now we have a bunch of examples in a control directory, for example in examples/controls/column:

scroll.py
alignment.py            scroll_events.py
custom_scrollbar.py     scroll_to_key.py
horizontal_alignment.py spacing.py
infinite_scrolling.py   storage
media                   wrap.py
programmatic_scroll.py

It's unclear what each example does, what technics demonstrates, etc.
There is temption to add this meta-data to a header comments inside each file, but it's non-standard and hard to parse.

I propose to turn each example into a separate project: we put example into its own directory, rename it to main.py and add pyproject.toml.

For example, scroll.py will be moved into a new directory examples/controls/column/scroll with the following contents:

• main.py - example itself.
• pyproject.toml - standard stuff + gallery-specific data + project metadata.
• assets - if there are media or other assets used in the example.

pyproject.toml

[project]
name = "{project_name}"
version = "1.0.0"
description = "{project description in one line}"
readme = "README.md" # if exists
requires-python = ">=3.10"
keywords = ["game", "declarative", "drag-n-drop", "layout", "navigation", "form", "table", "chart", "dialog", "theme", "responsive", "async", "auth", "media", "canvas", "gesture"]
authors = [
    { name = "Flet team", email = "hello@flet.dev" }
]
dependencies = [
    "flet",
    "flet-extension-a",
    "flet-extension-b",
    ...
]

[dependency-groups]
dev = [
    "flet-cli",
    "flet-desktop",
    "flet-web",
]

[tool.flet.gallery]
categories = ["Layout/Column", "Apps/Basic controls"]

[tool.flet.metadata]
title = "Responsive dashboard" # fallback to [tool.flet.product], then to [project.name]
controls = ["SafeArea", "Column", "Row", "Button"]
layout_pattern = "dashboard"
complexity = "basic" # intermediate, advanced
features = ["sorting", "filtering"]

[tool.flet]
platforms = ["web", "android"] # if not specified - a project supports all platforms
org = "dev.flet"
company = "Flet"
copyright = "Copyright (C) 2023-2026 by Flet"

[tool.flet.ios.info]
# any iOS entitlements required to run the app, like camera

[tool.flet.android.permission]
# any Android permissions required to run the app, like camera, photo library, etc.

# alternatively, a cross-platform permission could be provided
[tool.flet]
permissions = ["camera"]

# other settings to make project runnable "as is"...

Mapping to metadata

• Title - tool.flet.metadata.title or tool.flet.product or project.name.
• Short description - project.description.
• Category - tool.gallery.categories (project could belong to multiple categories) - the list of categories in the format A/B/C the project belongs to. Unlisted project has empty list of categories.
• Tags - project.keywords.
• Supported platforms - tool.flet.platforms - the list of platforms the project supports: web, ios, android, macos, windows, linux. If not specified - all platforms are supported.
• Long description - from README.md, if exists.
• Controls - tool.flet.metadata.controls - the list of controls used in a project.
• Layout pattern of the app - tool.flet.metadata.layout_pattern
• Complexity - tool.flet.metadata.complexity. Options: basic, intermediate, advanced.
• Features - tool.flet.metadata.features.

Notes for AI

Agent should do the best to infer project name, title, description, tags and other metadata from a) directory names the example resides and b) code of the example.
Agent should do the best to infer project dependencies from imports in .py file.
Links to examples in docs must be updated to point to main.py of example project.
Add __init__.py if example has tests.
Example code must be wrapped into SafeArea control to make sure it's properly rendered on mobile.