Shewart · Oct 13, 2026 · Oct 12, 2026 · Oct 12, 2026
diff --git a/docs/COMPONENTS.md b/docs/COMPONENTS.md
@@ -112,6 +112,7 @@ Same names, properties and variants as MAUI, except:
 | Carousel | Swipe, arrows, dots | Drag with the mouse or touch; the arrows are tab stops and Left / Right move while one has focus; with `AspectRatio="0"` set `Height` |
 | Stepper | Shows the active step's view | Every step stays in the tree and only the active one is visible; reached steps are tab stops (Enter / Space) |
 | Pagination | Labels hidden on phones | `ShowLabels` defaults to true; every page and arrow is a tab stop (Enter / Space) |
+| ChatInput | The send button sends | Also Enter sends and Shift+Enter starts a new line |
 | DataTable | Tap a header to sort | Sortable headers are also tab stops (Enter / Space) and keep focus after sorting; a click on a row's checkbox does not raise `RowTapped` |
 | Command | Enter picks the highlighted item (the first match) | Up / Down move the highlight and Enter picks it; `Value`, `Text` and the other strings are nullable; children are collected in `Groups` and `Items` |
 | CommandPalette | Open it from code | Also `Hotkey`, a key gesture that toggles it anywhere in the window (Ctrl+K by default; `Hotkey="{x:Null}"` for none) |
@@ -367,6 +368,39 @@ shellui-native add tag-input   # also installs wrap-layout
 
 ---
 
+### Form
+Fields stacked with even spacing. Each `FormField` is a label, a control, an optional
+description and an error message. Validation is yours: set a field's `Error` and the form
+reports it.
+
+```bash
+shellui-native add form
+```
+
+**Properties (Form):** `Spacing` (24), `IsValid` (no field has an `Error`), `FirstInvalid`
+(read-only) · **Methods:** `FormFields()`, `ClearErrors()`
+
+**Properties (FormField):** `Label`, `Description`, `Error` (two-way; shown in the destructive
+color, and the label turns red), `IsRequired` (a red asterisk), `HasError` (read-only) · its
+child view is the control
+
+```xml
+<ui:Form x:Name="SignUp">
+    <ui:FormField x:Name="EmailField" Label="Email" Description="We never share it." IsRequired="True">
+        <ui:Input x:Name="Email" Placeholder="you@example.com" />
+    </ui:FormField>
+    <ui:Button Text="Create account" Clicked="OnSubmit" />
+</ui:Form>
+```
+
+```csharp
+EmailField.Error = Email.Text.Contains('@') ? "" : "Enter a valid email address.";
+Email.HasError = EmailField.HasError;   // the red border is the control's own property
+if (SignUp.IsValid) { /* submit */ }
+```
+
+---
+
 ### Textarea
 Multi-line text field — min 80px, grows with content.
 
@@ -1237,6 +1271,49 @@ InvoiceTable.Columns[0].Value = item => ((Invoice)item).Number;
 
 ---
 
+### Chat
+A conversation panel: an optional header, a scrolling list of messages that follows the newest
+one, and an optional footer, usually a `ChatInput`. Give it a height.
+
+```bash
+shellui-native add chat
+```
+
+**Properties (Chat):** `Header`, `Footer` (views), `AutoScroll` (true: follows new messages and
+a message that grows, unless the reader has scrolled up), `Messages` · **Methods:**
+`ScrollToEnd()`
+
+**Properties (ChatMessage):** `Role` (Assistant, User, System), `Text`, `Sender`, `Timestamp`,
+`IsStreaming` (three bouncing dots while a reply is arriving), `AvatarText` (initials),
+`Avatar` (a view; replaces the initials), `Actions` (a view under the bubble) · its child view
+goes inside the bubble, under the text
+
+**Properties (ChatInput):** `Text` (two-way), `Placeholder`, `IsLoading` (a spinner in the send
+button; blocks sending), `Actions` (a view before the text) · **Events:** `Submitted` (the
+trimmed text; the box is cleared) · **Methods:** `Submit()`, `Focus()`
+
+```xml
+<ui:Chat x:Name="Conversation" HeightRequest="420">
+    <ui:ChatMessage Role="Assistant" Sender="ShellUI" AvatarText="S" Text="How can I help?" />
+    <ui:ChatMessage Role="User" Text="Show me the button." />
+    <ui:Chat.Footer>
+        <ui:ChatInput Submitted="OnSend" />
+    </ui:Chat.Footer>
+</ui:Chat>
+```
+
+```csharp
+private void OnSend(object? sender, string text)
+{
+    Conversation.Messages.Add(new ChatMessage { Role = ChatRole.User, Text = text });
+    var reply = new ChatMessage { Role = ChatRole.Assistant, IsStreaming = true };
+    Conversation.Messages.Add(reply);
+    // later: reply.Text = "..."; reply.IsStreaming = false;
+}
+```
+
+---
+
 ### Carousel
 One slide at a time in a rounded frame. Swipe, use the round arrow buttons or tap a dot to move.
 Each child view is a slide.

diff --git a/docs/COMPONENTS_ROADMAP.md b/docs/COMPONENTS_ROADMAP.md
@@ -4,7 +4,7 @@ Prioritized list of components to create for ShellUI Native, aligned with [Shell
 
 Last revised: **2026-10-11** (second prerelease, `0.1.0-alpha.2`).
 
-**Status at a glance:** P0–P6 ✅ done · P7 done except chart · `0.1.0-alpha.2`: 63 families, 94 CLI targets, each for MAUI and Avalonia · since then: button-group, input-group, menubar, command, navigation-menu, data-table.
+**Status at a glance:** P0–P6 ✅ done · P7 done except chart · `0.1.0-alpha.2`: 63 families, 94 CLI targets, each for MAUI and Avalonia · since then: button-group, input-group, menubar, command, navigation-menu, data-table, chat, form.
 
 ---
 
@@ -296,8 +296,9 @@ resizable, navbar, sidebar, date-range-picker and file-upload on both platforms
 **After `0.1.0-alpha.2`, from ShellUI's Blazor set** (both platforms): button-group ✅,
 input-group ✅ and menubar ✅ (2026-10-11), then command ✅ (with a command palette) and
 navigation-menu ✅, then data-table ✅ (client-side filter, sort, selection and pages;
-2026-10-12; 69 families, 100 CLI targets).
+2026-10-12), then chat ✅ and form ✅ (2026-10-13; 71 families, 102 CLI targets).
 
-**Backlog:** chart (P7); and the ShellUI Blazor targets not yet ported (chat, form,
-image-viewer, qr-code, …). Not in the native data-table yet: row actions and server-side
+**Backlog:** chart (P7); and the ShellUI Blazor targets not yet ported (image-viewer,
+prev-next-nav, …). qr-code waits, like the icon switch, for NuGet package dependencies in the
+CLI: it needs a QR encoder. Not in the native data-table yet: row actions and server-side
 paging.
diff --git a/docs/DEVELOPMENT_PLAN.md b/docs/DEVELOPMENT_PLAN.md
@@ -19,8 +19,9 @@ into it, not directly into `main`.
 main   ← Phase 1 (PRs #1–#5), release 0.1.0-alpha.1 (PR #6), Phase 2 Avalonia (PRs #7–#13),
          layout, navigation and pickers on both platforms (PR #14) merged
          release 0.1.0-alpha.2 (PR #15), CI action bumps (PR #16), button-group,
-         input-group and menubar (PR #17), command and navigation-menu (PR #18) merged
- └─ feat/data-table                   ← data-table from ShellUI's Blazor set (active)
+         input-group and menubar (PR #17), command and navigation-menu (PR #18),
+         data-table (PR #19) merged
+ └─ feat/chat-form                    ← chat and form from ShellUI's Blazor set (active)
  └─ feat/winui                        ← Phase 3 (conditional)
 ```
 
@@ -37,8 +38,8 @@ main   ← Phase 1 (PRs #1–#5), release 0.1.0-alpha.1 (PR #6), Phase 2 Avaloni
 
 | Branch | Base | Status | Purpose |
 |--------|------|--------|---------|
-| `main` | — | Phase 1, Phase 2 and PR #14 merged; released as `0.1.0-alpha.2`; PRs #17 and #18 merged since | 97 registry entries (94 CLI targets, 63 families), each with MAUI and Avalonia content |
-| `feat/data-table` | `main` | **Active** | data-table for MAUI and Avalonia (103 registry entries, 100 CLI targets, 69 families) |
+| `main` | — | Phase 1, Phase 2 and PR #14 merged; released as `0.1.0-alpha.2`; PRs #17–#19 merged since | 97 registry entries (94 CLI targets, 63 families), each with MAUI and Avalonia content |
+| `feat/chat-form` | `main` | **Active** | chat and form for MAUI and Avalonia (105 registry entries, 102 CLI targets, 71 families) |
 
 ---
 
@@ -532,6 +533,9 @@ Cross-desktop (Windows + macOS + Linux) from one XAML codebase.
 - [x] data-table (`feat/data-table`): DataTable + DataTableColumn on top of `table`, `input`,
   `checkbox` and `button`; columns read item properties by name (reflection, with a `Value`
   function for trimmed apps); no row actions or server-side paging yet
+- [x] chat and form (`feat/chat-form`): Chat, ChatMessage and ChatInput (the message's name
+  property is `Sender` on both platforms, since Avalonia controls already have a `Name`); Form
+  and FormField, where validation stays with the app and the form only reports field errors
 - [ ] Replace the generated `Icon.cs` with the `ShellIcons.Maui` / `ShellIcons.Avalonia` packages
   once they are on NuGet. Their names already match (`IconName`, `Icon`, `Kind` on Avalonia), so
   components change little: token tinting binds the package's `Color` (MAUI) or `Foreground`