feat: make NavigationDrawerDestination.label accept custom controls

.agents/skills/docs-conventions/SKILL.md

@@ -5,13 +5,18 @@ description: Use when writing or reviewing Flet documentation, including Python
 
 # Documentation Conventions
 
+Docs live in `website/docs/`. Docusaurus renders them as the website.
+
 ## Python Docstrings
 
 Use **Google style** docstrings with sections: `Args:`, `Returns:`, `Raises:`, `Note:`, `Example:`, `Warning:`.
 
-### Cross-references (reST roles)
+## Cross-references
+
+### reST roles
 
-Use reST roles in Python docstrings. CrocoDocs renders them as links in the API docs.
+Prefer these in Python docstrings. CrocoDocs renders them as links in
+the API docs and they keep authoring terse when the auto-derived label is acceptable.
 
 **Supported roles:** `:class:`, `:attr:`, `:meth:`, `:func:`, `:data:`, `:mod:`
 
@@ -20,9 +25,9 @@ Use reST roles in Python docstrings. CrocoDocs renders them as links in the API
 If a parent is a :class:`~flet.ResponsiveRow`, this property determines
 how many virtual columns the control spans.
 
-See :attr:`value` for the current selection.
+See :attr:`value` or :attr:`flet.Text.size` for the current selection.
 
-Calls :meth:`~flet.Page.update` after modifying controls.
+Calls :meth:`flet.Page.update` after modifying controls.
 """
 ```
 
@@ -38,7 +43,29 @@ Calls :meth:`~flet.Page.update` after modifying controls.
 - Custom labels like `:class:`my label <flet.Page>`` — the label is always auto-derived from the target
 - Roles for symbols not in CrocoDocs API data degrade to inline code
 
-### Admonitions in docstrings
+### Markdown links
+
+Use this syntax when the displayed text must differ from the symbol target or when
+explicitly required by user. This is especially useful in docs-only strings such as the
+`docs_reason` parameter of `@deprecated`, extracted validation messages, or short admonition text
+where you want:
+
+- inline-code labels with punctuation, such as `new_func()` or `local_position.x`,
+- plain-language labels that do not match the target exactly,
+- explicit full targets in the link destination for clarity.
+
+Use relative `.md` paths with dot-format anchors.
+
+Examples:
+
+```markdown
+Control: [`Page`](../controls/page.md)
+Type: [`DragTargetEvent.global_position`](../types/dragtargetevent.md#flet.DragTargetEvent.global_position)
+Plain text: [route](../controls/page.md#flet.Page.route)
+Method: [`Page.update()`](../controls/page.md#flet.Page.update)
+```
+
+## Admonitions in docstrings
 
 Google-style section headers render as Docusaurus admonitions:
 
@@ -56,25 +83,11 @@ Example:
 """
 ```
 
-Supported kinds: `Note`, `Warning`, `Danger`, `Tip`, `Info`. Unsupported kinds (e.g. `Limitation`, `Example`) are normalized to `note`. Empty admonitions are skipped.
-
-## Markdown Docs
-
-Docs live in `website/docs/`. Docusaurus renders them as the website.
-
-### Cross-references
-
-Use relative `.md` paths with dot-format anchors:
-
-```markdown
-See [Page](../controls/page.md) for details.
-
-The [route](../controls/page.md#flet.Page.route) property controls navigation.
-```
-
-Anchor format: `#flet.ClassName.member_name` (dots, not hyphens).
+Supported kinds: `Note`, `Warning`, `Danger`, `Tip`, `Info`.
+Unsupported kinds (e.g. `Limitation`, `Example`) are normalized to `note`.
+Empty admonitions are skipped.
 
-### Admonitions
+## Admonitions
 
 ```markdown
 :::note
@@ -88,7 +101,7 @@ Warning with a custom title.
 
 Supported types: `note`, `info`, `tip`, `warning`, `danger`.
 
-### Front matter
+## Front matter
 
 ```yaml
 ---
@@ -103,7 +116,7 @@ title: "Container"
 - `examples` — root-relative path under `sdk/python/examples/`
 - `example_images` / `example_media` — root-relative under `website/static/docs/`
 
-### Images
+## Images
 
 Use the CrocoDocs `Image` component. Paths without `../` are resolved against `/docs/`:
 
@@ -119,7 +132,7 @@ For absolute paths (one-off assets in `static/`):
 <Image src="/docs/assets/controls/charts/bar-chart-diagram.svg" width="65%" />
 ```
 
-### Code examples
+## Code examples
 
 ```jsx
 import {CodeExample} from '@site/src/components/crocodocs';

.agents/skills/flet-deprecation/SKILL.md

@@ -16,12 +16,9 @@ Do not use this skill for non-deprecation validation logic; use
 
 ## Source Of Truth
 
-- Runtime decorators and warning helpers:
-  `sdk/python/packages/flet/src/flet/utils/deprecated.py`
-- Field-level deprecation rule:
-  `sdk/python/packages/flet/src/flet/utils/validation.py` (`V.deprecated`)
-- Docs extraction/labeling extension:
-  `sdk/python/packages/flet/src/flet/utils/griffe_deprecations.py`
+- Runtime decorators and warning helpers: `sdk/python/packages/flet/src/flet/utils/deprecated.py`
+- Field-level deprecation rule: `sdk/python/packages/flet/src/flet/utils/validation.py` (`V.deprecated`)
+- Docs extraction/labeling extension: `sdk/python/packages/flet/src/flet/utils/griffe_deprecations.py`
 
 ## Deprecation Decision Order
 
@@ -50,45 +47,69 @@ Removal phase:
 - Example: deprecated in `0.82.0` -> remove in `0.85.0`.
 - Use that policy to set `delete_version` unless there is an approved exception.
 
+## Target Release Audit
+
+When working on a release for `{new_version}`, treat deprecations with
+`delete_version == {new_version}` as mandatory audit items.
+
+- Scan Python packages for `@deprecated(...)`, `@deprecated_class(...)`,
+  and `V.deprecated(...)` entries whose `delete_version` equals `{new_version}`.
+- Recommended check command:
+  `rg -n 'delete_version\\s*=\\s*"{new_version}"|delete_version\\s*=\\s*\\x27{new_version}\\x27' -S sdk/python/packages`
+- Treat every match as release-relevant work, not informational output.
+- If matches are found, summarize the findings first and ask the human for approval
+  before editing files or making removals.
+- For each match, decide whether the deprecated API must be removed now,
+  whether a prior removal was missed, or whether the deprecation timeline is incorrect.
+- If removal is due, make the code, docs, and changelog updates in the same change.
+- After the cleanup edits are ready, summarize the resulting diff and ask the human
+  for approval before creating a commit.
+- Once commit approval is received, batch all confirmed `{new_version}` cleanup
+  edits into one grouped commit instead of splitting them across multiple commits.
+  Use commit message format: `release: remove deprecated APIs for {new_version}`
+- Do not consider the release prep complete while unresolved `{new_version}` removals remain.
+
 ## Authoring Rules
 
 1. Always set `version`.
 2. Set `delete_version` using the 3-minor policy by default.
 3. Keep `reason` plain text for runtime warnings.
-4. Use `docs_reason` for docs-only markdown/xref text.
-5. Prefer explicit replacement names in reasons.
+4. Use `docs_reason` for docs-only markdown text.
+5. When a replacement exists, name that replacement API explicitly in `reason` and `docs_reason`.
 
 ### Field Pattern
 
 ```python
 from typing import Annotated, Optional
 from flet.utils.validation import V
 
-old_prop: Annotated[
-    Optional[str],
-    V.deprecated(
-        "new_prop",
-        version="0.17.0",
-        delete_version="0.18.0",
-        reason="Use new_prop instead.",
-        docs_reason="Use [`new_prop`][(c).] instead.",
-    ),
-] = None
+class ExampleControl:
+    old_prop: Annotated[
+        Optional[str],
+        V.deprecated(
+            "new_prop",
+            version="0.17.0",
+            delete_version="0.20.0",
+            reason="Use new_prop instead.",
+            docs_reason="Use :attr:`new_prop` or [`new_prop`](../controls/examplecontrol.md#flet.ExampleControl.new_prop) instead.",
+        ),
+    ] = None
 ```
 
 ### Function/Method Pattern
 
 ```python
 from flet.utils.deprecated import deprecated
 
-@deprecated(
-    reason="Use new_func instead.",
-    docs_reason="Use [`new_func()`][(m).new_func] instead.",
-    version="0.17.0",
-    delete_version="0.18.0",
-)
-def old_func():
-    ...
+class ExampleControl:
+    @deprecated(
+        reason="Use new_func instead.",
+        docs_reason="Use :meth:`new_func` or [`new_func()`](../controls/examplecontrol.md#flet.ExampleControl.new_func) instead.",
+        version="0.17.0",
+        delete_version="0.20.0",
+    )
+    def old_func(self):
+        ...
 ```
 
 ### Class/Control Pattern
@@ -98,22 +119,43 @@ from flet.utils.deprecated import deprecated_class
 
 @deprecated_class(
     reason="Use NewControl instead.",
-    docs_reason="Use [`NewControl`][flet.] instead.",
+    docs_reason="Use :class:`~flet.NewControl` or [`NewControl`](../controls/newcontrol.md)  instead.",
     version="0.17.0",
-    delete_version="0.18.0",
+    delete_version="0.20.0",
 )
 class OldControl:
     ...
 ```
 
+### Deprecated Property Pattern
+
+```python
+from flet.utils.deprecated import deprecated
+
+class ExampleControl:
+    @property
+    @deprecated(
+        reason="Use new_value instead.",
+        docs_reason="Use :attr:`new_value` or [`new_value`](../controls/examplecontrol.md#flet.ExampleControl.new_value) instead.",
+        version="0.17.0",
+        delete_version="0.20.0",
+    )
+    def value(self):
+        ...
+```
+
 ## `reason` vs `docs_reason`
 
 - Runtime warnings always use `reason`.
 - Docs admonitions prefer `docs_reason`; fallback is `reason`.
-- Keep markdown/xref out of `reason` to avoid noisy runtime output.
+- Keep markdown/cross-refs out of `reason` to avoid noisy runtime output.
+
+### Cross-reference Rule Inside `docs_reason`
+
+In `docs_reason`, use reST roles for simple references when the auto-derived label is
+sufficient, and use Markdown links when you need more control over the displayed text.
 
-For cross-reference shape rules, follow:
-[`docs-cross-referencing`](../docs-cross-referencing/SKILL.md)
+See [`docs-conventions`](../docs-conventions/SKILL.md) for details on supported cross-ref patterns and their syntax.
 
 ## Docs Behavior Expectations
 
@@ -129,8 +171,7 @@ is a special case not covered by the extension.
 When adding/changing deprecations, include tests for:
 - runtime warning text (`reason`, versions, optional delete version),
 - docs-only preference (`docs_reason` overrides `reason` in docs),
-- docs rendering extraction for the used pattern (`V.deprecated`,
-  `@deprecated`, `@deprecated_class`),
+- docs rendering extraction for the used pattern (`V.deprecated`, `@deprecated`, `@deprecated_class`),
 - label presence (`deprecated`) in docs extraction tests.
 
 Prefer:
@@ -140,8 +181,8 @@ Prefer:
 
 ## Common Pitfalls
 
-- Putting markdown/xref into runtime `reason`.
+- Putting markdown/cross-refs into runtime `reason`.
 - Forgetting `delete_version` when a removal target is already known.
 - Adding old/new value-copy logic in Python for rename migrations.
 - Duplicating deprecation warnings in multiple lifecycle hooks manually.
-- Broken crossref targets in `docs_reason` (for example malformed `[(c).]` links).
+- Broken cross-refs targets in `docs_reason`.

.agents/skills/flet-validation/SKILL.md

@@ -162,8 +162,8 @@ When a property has validation, document it in that property’s docstring (goog
 
 ## Cross-Referencing Conventions
 
-Follow the dedicated cross-reference guidance in:
-[`docs-cross-referencing` skill](../docs-cross-referencing/SKILL.md).
+Follow the cross-reference guidance in:
+[`docs-conventions`](../docs-conventions/SKILL.md).
 
 Most common pattern to use in control property docstrings:
 - same-class properties: `[\`prop\`][(c).]`

.agents/skills/prepare-flet-release/SKILL.md

@@ -10,11 +10,15 @@ description: Use when asked to prepare new Flet release by bumping versions and
 
 ## Related Skills
 
-Use [`flet-deprecation`](../flet-deprecation/SKILL.md) when release prep includes:
+Always use [`flet-deprecation`](../flet-deprecation/SKILL.md) during release prep
+to audit deprecations for the target version. Also use it when release prep includes:
 - adding new deprecations in this release,
 - removing APIs whose `delete_version` equals this release version,
 - auditing changelog entries that mention deprecations/removals.
 
+Use [`write-changelog-entry`](../write-changelog-entry/SKILL.md) for drafting or refining individual changelog items.
+That skill is the source of truth for item wording, scope selection, and what should or should not be mentioned in a single entry.
+
 ## Steps
 
 * Take latest Flet release version from the repo and
@@ -23,24 +27,13 @@ Use [`flet-deprecation`](../flet-deprecation/SKILL.md) when release prep include
 * Pull the latest `main` and create a new branch named `prepare-release-{new_version}` from `main`.
 * Set new version in packages/flet/pubspec.yaml.
 * Run pub get in /client dir to refresh pubspec.lock with new version.
-* Add a new entry into packages/flet/CHANGELOG.md from a git log since the last release. Go through all commits and collect all mentioned issues and pull requests. There could be several issues done in a single PR (commit) - group them by creating a single descriptive change/fix/feature item and put all issues and PR links in `[#<issue_number>](<issue_url>)` format in braces next to it. Do not add chore/trivial/duplicate items.
-  Every changelog item must include both related issue link(s) and PR link(s) when available (issue first, PR second). If no issue exists, include PR link(s) only.
-  Also include issue-only items when a change was done via direct commit without PR (for example, an issue referenced in commit context but no PR exists).
-  Every changelog item must include author attribution as plain text, not a Markdown link: `by @<github_login>`.
-  Place attribution at the end of each item after links, for example:
-  `* Added feature X ([#123](...), [#456](...)) by @contributor.`
-  Use PR author login for PR-based items. For issue-only direct-commit items, use the commit author GitHub login if available.
-  If one item groups multiple PRs by different authors, attribute all relevant authors:
-  `by @user1, @user2`.
-  Ensure that all inferred PRs and issues in the changelog have `{version}` milestone attached on GitHub.
-  If a related issue or PR is missing the `{version}` milestone, update the milestone on GitHub and keep the link in the changelog; do not omit issue links just because milestone metadata is missing.
-  As it's a Flutter package prefer items having changes on Flutter side.
-* Add a new entry into /CHANGELOG.md. Do not add chore/trivial/duplicate items, add "worth while" items with related issue or PR.
-  Every changelog item must include both related issue link(s) and PR link(s) when available (issue first, PR second). If no issue exists, include PR link(s) only.
-  Also include issue-only items when a change was done via direct commit without PR (for example, an issue referenced in commit context but no PR exists).
-  Every changelog item must include author attribution as plain text, not a Markdown link: `by @<github_login>`.
-  Use PR author login for PR-based items. For issue-only direct-commit items, use the commit author GitHub login if available.
-  If a related issue or PR is missing the `{version}` milestone, update the milestone on GitHub and keep the link in the changelog; do not omit issue links just because milestone metadata is missing.
+* Add new entries into `packages/flet/CHANGELOG.md` and `/CHANGELOG.md` from the git log since the last release.
+  * Use [`write-changelog-entry`](../write-changelog-entry/SKILL.md) for every individual item.
+  * Build the candidate set from relevant commits, PRs, and issues since the last release.
+  * Ensure that all inferred PRs and issues in the changelog have the `{version}` milestone attached on GitHub.
+  * If a related issue or PR is missing the `{version}` milestone, update the milestone on GitHub and keep the link in the changelog.
+  * When selecting candidates for `packages/flet/CHANGELOG.md`, prefer items with meaningful Flutter-side impact.
+  * When selecting candidates for `sdk/python/packages/*/CHANGELOG.md`, prefer published Python-facing changes; do not include extension-internal Flutter implementation work unless it materially changes user-visible Python behavior.
 * Scan all changelogs for `Unreleased` sections, not only the root ones:
   * `/CHANGELOG.md`
   * `packages/flet/CHANGELOG.md`