Skip to content

Commit db3cd5f

Browse files
EricFeng9EricFeng9
authored
Merge branch 'main' into fix-6312
2 parents c0fdc60 + 189472f commit db3cd5f

File tree

3,685 files changed

+110623
-44430
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

3,685 files changed

+110623
-44430
lines changed

‎.codex/skills/create-flet-example-projects/SKILL.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
---
2+
name: create-flet-example-projects
3+
description: Use when asked to create Flet example projects from flat .py files with main.py and pyproject.toml metadata for Gallery/MCP indexing.
4+
---
5+
6+
## When to use
7+
8+
Use this skill when a user asks to:
9+
- create one control/example folder (for example `examples/controls/chip`) in the project-per-example format
10+
- migrate existing flat examples to the project-per-example format
11+
- normalize a partially converted folder so all examples follow the same structure
12+
13+
## Goal
14+
15+
Ensure each runnable example is a standalone project containing:
16+
17+
- `main.py`
18+
- `pyproject.toml` with Gallery/MCP metadata
19+
- `assets/` (if the example uses local assets)
20+
21+
## Workflow
22+
23+
1. Inspect source folder.
24+
- Detect current state per example:
25+
- flat file: `foo.py`
26+
- project folder: `foo/main.py`
27+
- mixed/partial conversion: both styles present or missing metadata files
28+
- Find candidate flat modules: `*.py` in the target folder (exclude helper files such as `__init__.py`).
29+
- Keep existing `media/` unless an example needs local assets copied into its own `assets/`.
30+
31+
2. Convert or normalize examples.
32+
- For `foo.py`, create `foo/` and move file to `foo/main.py`.
33+
- If `foo/main.py` already exists, keep it and do not recreate/move files.
34+
- If folder exists but `main.py` is missing, repair structure only when there is a clear source file.
35+
- Do not create `foo/__init__.py`; import example modules directly in tests/docs (for example `import examples.controls.foo.bar.main as bar` or `import examples.controls.foo.bar as bar` when using namespace-package imports).
36+
- When a control folder has been fully converted to project-per-example layout, delete the control-level `examples/controls/<control>/__init__.py` too. The converted folders should behave like namespace packages, matching prior migrations such as commit `7e65ad566`.
37+
38+
3. Add `pyproject.toml` for each example project.
39+
- Infer from path and code.
40+
- Create missing `pyproject.toml` files for existing project folders.
41+
- Update obviously stale metadata when migrating existing examples (for example wrong title/description/categories).
42+
- Verify platform support before adding or omitting `[tool.flet].platforms`:
43+
- Check the local implementation and docs for explicit platform guards, support tables, or platform-specific exceptions.
44+
- If support is limited, add `[tool.flet].platforms` with only the supported platforms.
45+
- If support is broad/all-platform, omit `[tool.flet].platforms`.
46+
- Required fields:
47+
- `[project]`: `name`, `version`, `description`, `requires-python`, `keywords`, `authors`, `dependencies`
48+
- `[dependency-groups].dev`: include `flet-cli`, `flet-desktop`, `flet-web`
49+
- `[tool.flet.gallery].categories`
50+
- `[tool.flet.metadata]`: `title`, `controls`, `layout_pattern`, `complexity`, `features`
51+
- `[tool.flet]`: `org`, `company`, `copyright`
52+
- Add `[tool.flet].platforms` only when the example is platform-limited.
53+
- Add permissions blocks only when code actually needs them.
54+
55+
4. Infer metadata.
56+
- Title: readable version of file/folder intent.
57+
- Short description: one line of what the example demonstrates.
58+
- `[project].description` must be meaningful and example-specific; avoid generic placeholders like "Example N" or "<name> example for <control>".
59+
- Description should mention the concrete behavior or interaction shown (for example: hover highlight, live updates, custom axes, event handling).
60+
- Categories: typically control-based, e.g. `Input/Chip`, plus optional `Apps/Basic controls`.
61+
- Tags: from control/topic/behavior words.
62+
- Controls used: list key controls from code.
63+
- Layout pattern: choose closest practical value (e.g. `filter-bar`, `inline-actions`, `dashboard`, `list-detail`).
64+
- Complexity: `basic` unless logic/state/architecture is non-trivial.
65+
- Features: notable behaviors only (click handling, selection, async loading, drag-and-drop, etc.).
66+
- If an example supports exporting or downloading output, include `"save to file"` in `[tool.flet.metadata].features`.
67+
- If an example module contains `async def` handlers or async control flow, append `"async"` to `keywords`.
68+
69+
70+
5. Infer dependencies from imports.
71+
- Always include `flet` for standard examples.
72+
- Include extra packages if imported (for example extension packages).
73+
- Do not add unused dependencies.
74+
75+
6. Make examples mobile-safe.
76+
- If `ft.context.disable_auto_update()` is not used, do not add explicit `page.update()` unless strictly necessary.
77+
- Apply this `page.update()` rule to all examples in the touched folder (new, migrated, and already converted).
78+
- Wrap app content in `ft.SafeArea` so example renders correctly on mobile.
79+
- Add `expand=True` to `ft.SafeArea` only when needed for correct layout/sizing (for example to avoid Infinity/NaN sizing issues), and avoid adding it when not necessary.
80+
- When converting legacy `page.add(a, b, ...)` style examples, wrap the controls in `ft.Column(controls=[...])` inside `ft.SafeArea(content=...)` rather than `ft.Row`, unless the original code explicitly used a row layout.
81+
82+
- Apply this to all examples in the touched folder (new, migrated, and already converted), not only files changed by moves.
83+
- During validation, confirm every `<example>/main.py` in scope includes a top-level `ft.SafeArea` around rendered content.
84+
- For declarative examples using `@ft.component`, do not pass component instances as regular control children (for example `SafeArea(content=App())`) because this can raise runtime attribute errors.
85+
- In declarative examples, ensure the component itself returns regular controls (including `SafeArea` when needed) and render it at page level with `page.render(App)` in `main()`.
86+
87+
7. Prefer `@ft.control` for custom controls in examples.
88+
- If an example defines a custom control class inheriting from a Flet control (for example `class MyThing(ft.Column)`), prefer `@ft.control` style.
89+
- Move constructor-style setup to declarative fields + `init()` where practical.
90+
- Keep behavior unchanged and avoid refactors that alter public usage unless needed for compatibility.
91+
92+
8. Remove deprecated Material 3 toggle usage.
93+
- If `use_material3` appears in example code, remove it and simplify the example to current API usage.
94+
- Remove related Material 3 toggle logic/UI that exists only to switch `use_material3`.
95+
- Update example metadata (`pyproject.toml`) to remove stale Material 3 references when code is changed.
96+
97+
9. Ensure runnable entrypoint.
98+
- Every example `main.py` should end with:
99+
- `if __name__ == "__main__":`
100+
- ` ft.run(main)`
101+
- Apply this to all examples in the touched folder (new, migrated, and already converted).
102+
103+
10. Update references.
104+
- Docs code includes: change from `.../example.py` to `.../example/main.py`.
105+
- Inspect the relevant docs pages for each touched control/service/example area (for example `sdk/python/packages/flet/docs/controls/<control>.md`) and update any `--8<--` includes or direct file-path references to the new `main.py` path.
106+
- Tests/imports: use direct module imports and avoid relying on package-level `__init__.py` re-exports.
107+
- For already-converted examples, only update references that are stale; avoid unnecessary churn.
108+
- If removing a control-level `__init__.py`, confirm no remaining imports rely on `from examples.controls.<control> import ...`.
109+
110+
11. Validate.
111+
- Run `python -m compileall` on changed `main.py` files.
112+
- Run `uv run ruff check` on changed example files and fix violations until it passes (respecting repository `pyproject.toml` under `[tool.ruff]`).
113+
- Search for stale paths to old flat files.
114+
- Search docs and package sources for stale references to the migrated flat example paths and fix any hits in scope.
115+
- Check `git status` to confirm expected moves and edits.
116+
- When integration tests exist for the touched control, run the targeted test file(s).
117+
- Confirm all in-scope `main.py` files include both top-level `ft.SafeArea` wrapping and the `if __name__ == "__main__": ft.run(main)` entrypoint.
118+
- Confirm in-scope `ft.SafeArea` wrappers use `expand=True` only where needed for correct behavior and sizing; avoid forcing it by default.
119+
- Confirm there are no unnecessary `page.update()` calls in in-scope examples (unless explicitly required by isolated-control or non-auto-update behavior).
120+
- Confirm no in-scope examples use `use_material3`.
121+
- Confirm each in-scope `pyproject.toml` has a meaningful, example-specific `[project].description` (not generic or templated text).
122+
- Confirm metadata features include `"save to file"` when the example code supports file export/save behavior.
123+
- Confirm there is no stale control-level `__init__.py` left behind once a touched control folder has been fully converted.
124+
- Confirm the relevant docs pages were updated to reference `main.py` and that no stale doc includes remain for the touched examples.
125+
126+
127+
## Code style
128+
129+
- When writing wrapped controls (`SafeArea`, `Column`, `Row`, `Container`, etc.), keep `content=` or `controls=` as the last named argument in that control call.
130+
- Apply this ordering consistently when creating or refactoring examples.
131+
- Follow code style and linting rules defined in the repository `pyproject.toml` under `[tool.ruff]` for all edits.
132+
133+
## Command checklist
134+
135+
- Discover files: `rg --files <target_dir>`
136+
- Find docs links/imports: `rg -n "<old_path_or_module>" packages examples`
137+
- Syntax check: `python -m compileall <changed_main_files>`
138+
- Ruff check: `uv run ruff check <changed_example_files>`
139+
140+
## Output expectations
141+
142+
Report:
143+
- created example projects
144+
- metadata added
145+
- docs/tests updates
146+
- validation results

‎.codex/skills/docs-build-and-verify/SKILL.md‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
name: docs-build-and-verify
3+
description: Use when asked to build, preview, or verify the Flet documentation website, including checking for broken links, broken images, and unresolved reST cross-references.
4+
---
5+
6+
# Docs Build and Verification
7+
8+
## Prerequisites
9+
10+
Node.js 20 is required:
11+
12+
```bash
13+
nvm use 20
14+
```
15+
16+
## Build
17+
18+
Full production build (includes broken link detection):
19+
20+
```bash
21+
cd website && yarn build
22+
```
23+
24+
Dev server with hot reload:
25+
26+
```bash
27+
cd website && yarn start
28+
```
29+
30+
Regenerate API data and sidebars only (no Docusaurus build):
31+
32+
```bash
33+
cd website && yarn crocodocs:generate
34+
```
35+
36+
## Check Broken Links
37+
38+
`yarn build` automatically reports broken links and anchors. The build fails if any are found.
39+
40+
## Check Broken Images
41+
42+
Run this after `yarn build` to find images referenced in HTML that don't exist:
43+
44+
```bash
45+
cd website && python3 -c "
46+
import re, os, glob
47+
48+
build_dir = 'build'
49+
img_re = re.compile(r'<img[^>]+src=\"(/[^\"]+)\"', re.IGNORECASE)
50+
broken = []
51+
52+
for html_file in sorted(glob.glob(f'{build_dir}/docs/**/index.html', recursive=True)):
53+
page = html_file.replace(build_dir + '/', '').replace('/index.html', '')
54+
content = open(html_file).read()
55+
for match in img_re.finditer(content):
56+
src = match.group(1)
57+
if src.startswith('http') or src.startswith('data:'):
58+
continue
59+
file_path = os.path.join(build_dir, src.lstrip('/'))
60+
if not os.path.exists(file_path):
61+
broken.append((page, src))
62+
63+
if broken:
64+
print(f'Found {len(broken)} broken images:')
65+
for page, src in broken:
66+
print(f' {page}: {src}')
67+
else:
68+
print('No broken images found!')
69+
"
70+
```
71+
72+
## Check Unresolved reST Cross-References
73+
74+
After building, check for reST roles that failed to resolve and appear as raw text:
75+
76+
```bash
77+
cd website && grep -r ':attr:\|:class:\|:meth:\|:func:' build/docs/ --include='*.html' -l
78+
```
79+
80+
If any files are listed, those pages have unresolved cross-references that render as plain text instead of links.

‎.codex/skills/docs-conventions/SKILL.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
name: docs-conventions
3+
description: Use when writing or reviewing Flet documentation, including Python docstrings (Google style, reST roles, admonitions), Markdown docs (cross-references, images, code examples), and sidebar navigation.
4+
---
5+
6+
# Documentation Conventions
7+
8+
## Python Docstrings
9+
10+
Use **Google style** docstrings with sections: `Args:`, `Returns:`, `Raises:`, `Note:`, `Example:`, `Warning:`.
11+
12+
### Cross-references (reST roles)
13+
14+
Use reST roles in Python docstrings. CrocoDocs renders them as links in the API docs.
15+
16+
**Supported roles:** `:class:`, `:attr:`, `:meth:`, `:func:`, `:data:`, `:mod:`
17+
18+
```python
19+
"""
20+
If a parent is a :class:`~flet.ResponsiveRow`, this property determines
21+
how many virtual columns the control spans.
22+
23+
See :attr:`value` for the current selection.
24+
25+
Calls :meth:`~flet.Page.update` after modifying controls.
26+
"""
27+
```
28+
29+
**Rules:**
30+
31+
- **Qualified reference:** `:class:`flet.Page`` — links to Page, displays `flet.Page`
32+
- **Short display with `~`:** `:class:`~flet.Page`` — links to Page, displays just `Page`
33+
- **Local member (same class):** `:attr:`value`` — no qualifier needed
34+
- **Method with parens:** `:meth:`update`` — do NOT include `()` in the target
35+
36+
**Not supported:**
37+
38+
- Custom labels like `:class:`my label <flet.Page>`` — the label is always auto-derived from the target
39+
- Roles for symbols not in CrocoDocs API data degrade to inline code
40+
41+
### Admonitions in docstrings
42+
43+
Google-style section headers render as Docusaurus admonitions:
44+
45+
```python
46+
"""
47+
Note:
48+
Has effect only if the direct parent is a :class:`~flet.Column`.
49+
50+
Warning:
51+
This property is deprecated. Use :attr:`new_prop` instead.
52+
53+
Example:
54+
Setting up a basic layout:
55+
``ft.Column(controls=[ft.Text("Hello")])``
56+
"""
57+
```
58+
59+
Supported kinds: `Note`, `Warning`, `Danger`, `Tip`, `Info`. Unsupported kinds (e.g. `Limitation`, `Example`) are normalized to `note`. Empty admonitions are skipped.
60+
61+
## Markdown Docs
62+
63+
Docs live in `website/docs/`. Docusaurus renders them as the website.
64+
65+
### Cross-references
66+
67+
Use relative `.md` paths with dot-format anchors:
68+
69+
```markdown
70+
See [Page](../controls/page.md) for details.
71+
72+
The [route](../controls/page.md#flet.Page.route) property controls navigation.
73+
```
74+
75+
Anchor format: `#flet.ClassName.member_name` (dots, not hyphens).
76+
77+
### Admonitions
78+
79+
```markdown
80+
:::note
81+
Basic note without title.
82+
:::
83+
84+
:::warning[Important]
85+
Warning with a custom title.
86+
:::
87+
```
88+
89+
Supported types: `note`, `info`, `tip`, `warning`, `danger`.
90+
91+
### Front matter
92+
93+
```yaml
94+
---
95+
class_name: "flet.Container"
96+
examples: "controls/container"
97+
example_images: "test-images/examples/material/golden/macos/container"
98+
example_media: "examples/controls/container/media"
99+
title: "Container"
100+
---
101+
```
102+
103+
- `examples` — root-relative path under `sdk/python/examples/`
104+
- `example_images` / `example_media` — root-relative under `website/static/docs/`
105+
106+
### Images
107+
108+
Use the CrocoDocs `Image` component. Paths without `../` are resolved against `/docs/`:
109+
110+
```jsx
111+
import {Image} from '@site/src/components/crocodocs';
112+
113+
<Image src={frontMatter.example_images + '/image_for_docs.png'} width="55%" />
114+
```
115+
116+
For absolute paths (one-off assets in `static/`):
117+
118+
```jsx
119+
<Image src="/docs/assets/controls/charts/bar-chart-diagram.svg" width="65%" />
120+
```
121+
122+
### Code examples
123+
124+
```jsx
125+
import {CodeExample} from '@site/src/components/crocodocs';
126+
127+
<CodeExample path={frontMatter.examples + '/example_1.py'} />
128+
```
129+
130+
Paths are relative to the configured `examples_root` (`sdk/python/examples/`).
131+
132+
## Sidebar Navigation
133+
134+
Edit `website/sidebars.yml` to change navigation structure:
135+
136+
```yaml
137+
docs:
138+
Getting started:
139+
- getting-started/installation.md
140+
Controls:
141+
_generated_index:
142+
title: Controls
143+
slug: /controls
144+
description: Browse the complete catalog of controls.
145+
AlertDialog: controls/alertdialog.md
146+
```
147+
148+
After editing, regenerate `sidebars.js`:
149+
150+
```bash
151+
cd website && yarn crocodocs:generate
152+
```

0 commit comments

Comments
 (0)