Merge branch 'main' into copilot/identify-memory-leaks

Author: Vetle444

.github/copilot-instructions.md

@@ -9,6 +9,11 @@
 
 Add corrections to the relevant section (Critical Patterns, Common Pitfalls, etc.) or create a new section if needed.
 
+## Skills
+**IMPORTANT**: Before performing any task, always check `.github/skills/` and `.github/agents/` for applicable skill and agent files. Each subfolder contains a `SKILL.md` or agent definition with specific workflows, templates, trigger phrases, and rules that MUST be followed when their trigger conditions match.
+
+**Workflow**: List all folders in `.github/skills/` and `.github/agents/` (if they exist), read each definition file to check if it applies to the current task, and follow its steps exactly.
+
 ## Project Overview
 DIPS.Mobile.UI is a .NET MAUI component library for iOS and Android mobile apps in the healthcare domain. Components follow a design system with resources (colors, sizes, icons) auto-generated from Figma via DIPS.Mobile.DesignTokens pipeline.
 
@@ -228,6 +233,17 @@ Example divider usage:
 
 Format: `[Component/Feature] Description` (see existing entries for style)
 
+**Changelog rules (strictly enforced):**
+- Only include **public-facing changes**: new APIs, changed behavior, bug fixes visible to consumers
+- Do **not** include internal refactorings, code cleanup, sample changes, or test changes
+- Do **not** include changes to non-public (`internal`/`private`) APIs
+
+**Documentation rules (strictly enforced):**
+- Every new **public** type, property, method, or component MUST have XML doc comments
+- Every new **component or feature** MUST have a `wiki/<FeatureName>.md` page added in the same PR
+- Changed behavior or API MUST update existing wiki pages — cross-reference changed code against `wiki/` to catch stale docs
+- Breaking changes MUST update all affected wiki pages
+
 ## Common Pitfalls
 
 1. **Don't** manually append "Button" to accessibility strings - `TouchPlatformEffect` handles this
@@ -236,7 +252,8 @@ Format: `[Component/Feature] Description` (see existing entries for style)
 4. **Don't** create new colors/sizes - use design token resources or request from designers
 5. **Don't** use invalid style names like `Body500` - use `SectionHeader`, `UI100-300`, etc.
 6. **Don't** use `FontFamily="monospace"` - use `FontFamily="Body"`, `"UI"`, or `"Header"`
-5. **Don't** forget to test on both platforms - behavior often differs
+7. **Don't** forget to test on both platforms - behavior often differs
+8. **When reusing an existing component in a new context** (e.g. embedding a component inside a new handler, effect, or renderer), always read the component's existing canonical platform consumer first and replicate **all** of its event subscriptions, lifecycle hooks, and teardown logic. Never assume that rendering the component is sufficient. Components often have additional contracts (update events, binding context propagation, etc.) that only the canonical consumer reveals. Missing these causes silent regressions where the component renders correctly initially but fails to update afterwards.
 
 ## Key Files to Reference
 - `API/Builder/AppHostBuilderExtensions.cs` - Library initialization and handler registration
@@ -248,4 +265,6 @@ Format: `[Component/Feature] Description` (see existing entries for style)
 All code uses `DIPS.Mobile.UI.*` namespace. Platform folders (iOS/Android/dotnet) use same namespace as parent - no `.iOS` suffix.
 
 ## Wiki
-The codebase is documented in https://github.com/DIPSAS/DIPS.Mobile.UI/wiki
+The codebase is documented in https://github.com/DIPSAS/DIPS.Mobile.UI/wiki
+
+Documentation source lives in the `wiki/` folder in the main repository and is auto-synced to the GitHub wiki via a GitHub Action on pushes to `main`. The `_Sidebar.md` is auto-generated alphabetically from all wiki pages — no manual sidebar edits needed.

.github/instructions/create_pr.instructions.md

@@ -0,0 +1,132 @@
+---
+name: Write Component Documentation
+description: Generates wiki documentation for new DIPS.Mobile.UI components following established patterns and conventions.
+---
+
+# Write Component Documentation
+
+When asked to write documentation for a new component, generate a `wiki/<ComponentName>.md` page following the template and rules below.
+
+## Trigger Phrases
+
+- "Document this component"
+- "Write wiki page"
+- "Add documentation"
+- "Create wiki doc"
+
+## Before Writing
+
+1. **Read the component source code** — understand all public properties, bindable properties, events, commands, and options classes
+2. **Check for sub-components or variants** — e.g., `NavigationListItem` alongside `ListItem`, `FilledCheckBox` alongside `CheckBox`
+3. **Check for platform differences** — look at iOS/Android partial classes for behavioral differences
+4. **Check accessibility support** — does the component set semantic properties, use `TouchPlatformEffect`, or have accessibility-specific features?
+5. **Look at the sample app** — check `ComponentsSamples/` or `AccessibilitySamples/` for usage examples
+
+## Template
+
+Use the following structure. Sections marked **(if applicable)** should only be included when relevant.
+
+```markdown
+<Short description of what the component is — 1-2 sentences. Written before any heading. Explain the purpose and when to use it.>
+
+# Inspiration **(if applicable)**
+
+<Links to design guidelines that inspired the component, e.g., Material Design, Apple Human Interface Guidelines.>
+
+# Usage
+
+<XAML example showing the most common/basic usage of the component.>
+
+> <Any important notes about defaults, required properties, or common gotchas.>
+
+# Styles **(if applicable)**
+
+<List available styles/variants with a brief description of each.>
+
+# Tips and tricks **(if applicable)**
+
+<Practical guidance: recommended patterns, common combinations with other components, or things to watch out for.>
+
+# Accessibility **(if applicable)**
+
+<How the component behaves with VoiceOver/TalkBack. Any required semantic properties. Special accessibility features.>
+
+# Properties
+
+Inspect the [components properties class](<GitHub URL to .Properties.cs file>) to further customise and use it.
+```
+
+### Sub-Component Pattern
+
+When the component has variants or related sub-components, add them as `##` sections after the main component, each with their own `### Usage` and `### Properties`:
+
+```markdown
+## SubComponentName
+
+<Brief description of the sub-component.>
+
+### Usage
+
+<XAML example>
+
+### Properties
+
+Inspect the [components properties class](<GitHub URL>) to further customise and use it.
+```
+
+## Writing Rules
+
+### Intro
+- Start with a plain-text paragraph **before any heading** — describe what the component is and when people would use it
+- Keep it to 1-2 sentences
+
+### Usage Sections
+- Always include at least one XAML code block with `xml` as the language tag
+- Use the `dui:` XML namespace prefix — do not show `xmlns` declarations (readers already know this)
+- Show the simplest working example first, then more advanced configurations
+- If C# code-behind is needed (e.g., ViewModel bindings, event handlers), include it after the XAML block using `csharp` as the language tag
+
+### Properties
+- Always link to the `.Properties.cs` file on GitHub: `https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/<path>/<Component>.Properties.cs`
+- Use the standard phrasing: *"Inspect the [components properties class](URL) to further customise and use it."*
+- This should be the **last section** (or last sub-section per component)
+
+### Callouts
+- Use blockquotes (`>`) for notes, warnings, and platform-specific differences
+- Bold the callout type: `> **NB!**`, `> **NOTE:**`, `> **Important:**`
+- Use callouts for: default values, platform differences (iOS vs Android), UX warnings, required configurations
+
+### Style
+- Use `#` (h1) for major sections
+- Use `##` (h2) for sub-components
+- Use `###` (h3) for sections within a sub-component
+- Be concise — developers scan documentation, not read it cover-to-cover
+- Write in present tense: *"The component displays..."* not *"The component will display..."*
+- Address the reader as *"you"*: *"Use this when you need..."*
+- Refer to end-users as *"people"*: *"People can tap to..."*
+
+### What NOT to Include
+- No namespace/xmlns declarations (unless the component requires a non-standard namespace)
+- No installation or NuGet instructions
+- No `_Sidebar.md` references — it is auto-generated
+- No Figma links (designers maintain those separately)
+- Do not document internal/private APIs — only public-facing properties and usage
+
+### File Placement (wiki/ folder structure)
+
+The `wiki/` folder is organized into group folders. Place new documentation in the appropriate group:
+
+| Folder | What goes here |
+|--------|---------------|
+| `Components/` | UI elements: buttons, labels, list items, pickers, checkboxes, etc. |
+| `Layout & Navigation/` | Page structure, navigation, sheets, tabs, search |
+| `Media/` | Camera, images, audio |
+| `Feedback & State/` | Alerts, dialogs, loading indicators, state views |
+| `Styling & Resources/` | Colors, icons, sizes, animations, converters |
+| `Interaction & Accessibility/` | Touch, accessibility, input behaviors |
+| `Guides/` | How-to guides, performance tips, general patterns |
+
+- **New component?** → Place in the matching group folder (most likely `Components/`)
+- **Nothing fits?** → Create a new group folder and place the file there
+- **Root-level files** (`Home.md`, `Getting-Started.md`) are reserved for top-level pages only
+- The sidebar and wiki sync are handled automatically — just add the `.md` file to the right folder

.github/skills/doc-write-component/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: Create PR
+description: Creates a pull request with proper title, description, changelog updates, and wiki documentation checks.
+---
+
+# Pull Request Creation Instructions
+
+## Trigger Phrases
+When I say **any** of these:
+- "Create PR"
+- "Make PR"
+- "PR"
+- "Create Pull Request"
+- "Make a PR"
+- "Generate PR"
+- "Generate PR description"
+
+## Action Steps
+1. **Check changes**: Get the diff between main branch and current branch
+2. **Update CHANGELOG.md** (only if `src/` has changes): Determine if Major/Minor/Patch bump is needed based on:
+   - **Major**: Breaking changes (removed/changed public APIs)
+   - **Minor**: New features (new components, properties, methods)
+   - **Patch**: Bug fixes, internal improvements, accessibility fixes
+   - Follow existing CHANGELOG.md format: `[Component/Feature] Description`
+   - **Skip** if the PR has no changes under `src/` — documentation-only, build scripts, CI/CD, and config changes do not require a changelog entry
+3. **Wiki documentation**: Check if documentation in `wiki/` needs to be added or updated:
+   - **New feature?** → **MUST** add a new `wiki/<FeatureName>.md` page
+   - **Changed behavior/API?** → **MUST** update the relevant existing wiki page
+   - **Breaking change?** → **MUST** update wiki to reflect the new behavior
+   - The sidebar is auto-generated — just add the `.md` file to `wiki/`
+4. **Generate PR**: Create pull request with title and body, **always** using the PR template from `.github/pull_request_template.md` as the body structure. Read the template file first and fill in each section — never invent a different structure.
+
+## PR Format Requirements
+
+### Title
+- Short and imperative (e.g., "Add accessibility support to Touch effect")
+- No "Fixed" or past tense - use present tense
+- Mention component/area if applicable
+
+### Body
+**Always** use `.github/pull_request_template.md` as the base. Read it before writing the body. Fill in every section — do not skip or reorder sections, do not add sections not in the template.
+
+## Additional Considerations
+
+### Wiki Documentation
+Documentation lives in the `wiki/` folder and is auto-synced to the GitHub wiki on merge to main.
+- **New features**: A wiki page in `wiki/` is **required** — not optional. Add it in the PR.
+- **Changed behavior**: Update the relevant `wiki/*.md` page in the same PR.
+- **Breaking changes**: Wiki must reflect the new API/behavior.
+- The `_Sidebar.md` is auto-generated from filenames — no manual sidebar edits needed.
+
+### Tone and Style
+- **Clear**: Easy to understand what changed
+- **Professional**: No informal language
+- **Concise**: Avoid unnecessary context or repetition
+- **Specific**: Reference actual files, components, and patterns