From 59c7fbf93cbc216f10c84bd6928d6a8a4a3ac434 Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Sat, 3 Oct 2026 18:02:20 +0200
Subject: [PATCH 1/2] docs: add the 0.3.1 and 0.3.2 release notes to main

They were only on release/v0.3.
---
 docs/RELEASE_NOTES.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
index e67adbd..7ab8084 100644
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -1,5 +1,37 @@
 # ShellUI Release Notes
 
+# ShellUI v0.3.2
+
+> A patch release with component fixes for both the `ShellUI.Components` NuGet package and the CLI templates.
+
+## 🐛 Fixes
+
+- `MultiSeriesChart` threw on every render in the NuGet package. It now renders, inside the same card as `Chart`.
+- NuGet package: `ThemeToggle` flipped its icon but did not change the theme, dialogs, sheets and drawers did not lock page scrolling, and close-on-scroll dropdowns stayed open. The package's `shellui.js` now loads automatically through a Blazor JS initializer, with no `<script>` tag needed, and includes the functions `ThemeToggle`, `ThemeService` and `FileUpload` call.
+- `ThemeToggle` kept a list of instances shared by every user on Blazor Server, so one user's toggle tried to re-render other users' components. Toggles now follow the page's `dark` class, so all toggles on a page stay in sync and start from the page's actual theme.
+- `DatePicker` and `DateRangePicker`: the calendar popover has a width, so it is no longer squeezed in a flex row.
+- `DataPicker` and `MultiSelect`: option rows are left-aligned, so custom `OptionTemplate`s no longer render centered.
+- Removed leftover files from the Razor class library template (`Component1`, `ExampleJsInterop`, `background.png`) from the package.
+
+A new test renders every package component and fails on parameter errors like the `MultiSeriesChart` one.
+
+## ⬆️ Upgrading
+
+- **NuGet package:** update to `0.3.2`.
+- **CLI:** update the tool, then run `shellui update` to rewrite installed components, including `shellui.js`, from the new templates. `update` overwrites the files, so commit or back up any components you customized first.
+
+# ShellUI v0.3.1
+
+> A patch release for the `ShellUI.Components` NuGet package. The CLI and its templates have no changes beyond the version number.
+
+## 🐛 Fixes
+
+- `Calendar`, `Command`, `DataTable`, `FileUpload`, `CarouselContent`, `CarouselDots`, `CarouselNext` and `CarouselPrevious` compiled into the `ShellUI.Components.Components` namespace, so `@using ShellUI.Components` did not find them. They are now in `ShellUI.Components` like every other component, and a test checks that every package component declares that namespace.
+
+## ⬆️ Upgrading
+
+Update the package to `0.3.1`. If you added `@using ShellUI.Components.Components` to work around this, remove it: that namespace no longer exists, so the line now fails the build.
+
 # ShellUI v0.3.0 🎉
 
 > The first stable release of the 0.3 line. It builds on .NET 10 and Tailwind CSS 4.3.2 and ships everything from the 0.3.0 alphas and release candidates. A plain `dotnet tool install` now picks it up, so `--version` is no longer needed. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues).

From 02fafb2b7d7a5ed11be3b9bfe0c098298827a812 Mon Sep 17 00:00:00 2001
From: Shewatipa Tseisi <shewatipa@chips.co.zw>
Date: Sat, 3 Oct 2026 18:02:22 +0200
Subject: [PATCH 2/2] chore(release): v0.4.0-alpha.1

Release notes for 0.4.0-alpha.1, and docs that now name 0.3.2 as the latest stable release and 0.4.0-alpha.1 as a prerelease installed with --version.
---
 README.md                |  7 ++--
 VERSIONING_STRATEGY.md   |  4 +-
 docs/CLI_INSTALLATION.md |  5 ++-
 docs/CLI_SYNTAX.md       |  4 +-
 docs/FAQ.md              |  4 +-
 docs/QUICKSTART.md       |  4 +-
 docs/RELEASE_NOTES.md    | 84 ++++++++++++++++++++++++++++++++++++++++
 7 files changed, 99 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 22961b7..5ccefb2 100644
--- a/README.md
+++ b/README.md
@@ -24,12 +24,12 @@
 
 | Channel | Version | Notes |
 |---|---|---|
-| Latest stable (recommended) | `0.3.0` | Tailwind CSS `4.3.2` |
-| In development | `0.4.0` | This branch; not published yet |
+| Latest stable (recommended) | `0.3.2` | Tailwind CSS `4.3.2` |
+| Prerelease | `0.4.0-alpha.1` | This branch; install with `--version 0.4.0-alpha.1` |
 
 The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10. The `ShellUI.Components` NuGet package targets .NET 10 only; on .NET 8 or 9, use the CLI.
 
-`main` is where 0.4 is being built, so this README and `docs/` include features that are not released yet, such as `shellui init --dashboard`. For the released version, read the [v0.3.0 docs](https://github.com/shellui-dev/shellui/tree/v0.3.0). Prereleases, when published, need `--version` to install.
+`main` is the 0.4 line, so this README and `docs/` describe `0.4.0-alpha.1`, including features that are not in a stable release yet, such as `shellui init --dashboard` and the auth blocks. For the stable version, read the [v0.3.2 docs](https://github.com/shellui-dev/shellui/tree/v0.3.2). Prereleases need `--version` to install.
 
 ShellUI is pre-1.0, so APIs and generated output can still change between minor versions. Validate it in your target Blazor and hosting environments before relying on it.
 
@@ -37,6 +37,7 @@ ShellUI is pre-1.0, so APIs and generated output can still change between minor
 
 - The CLI commands are `init`, `add`, `list`, `remove`, and `update`, plus `theme init`, `theme apply`, and `theme update`.
 - The component registry has **243 entries**: **93 direct install targets** and **150 hidden dependency entries**. `list` shows direct targets; `add` resolves hidden dependencies.
+- `0.4.0-alpha.1` adds `kbd`, `aspect-ratio`, `button-group`, `toggle-group`, `input-group`, `number-input`, `stat-card`, `timeline`, `tree-view`, `qr-code`, `image-viewer`, `chat`, `chat-message`, `chat-input`, and the `auth-01`, `auth-02` and `auth-03` blocks.
 - `0.3.0` added `typed-select`, `command-palette`, `data-picker`, `multi-select`, `tag-input`, `donut-chart`, `radar-chart`, and `radial-chart`.
 - `ShellUI.Components` supports a release-generated precompiled CSS bundle and a generated safelist for existing Tailwind builds.
 - The CLI can install source with Tailwind's standalone executable or an npm-based build. The current Tailwind baseline is `4.3.2`.
diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md
index 21659ad..a1f0650 100644
--- a/VERSIONING_STRATEGY.md
+++ b/VERSIONING_STRATEGY.md
@@ -6,7 +6,7 @@ ShellUI uses one centralized version for the source templates, CLI tool, and pac
 
 | Scope | Value |
 |---|---|
-| Version | `0.4.0-alpha.1` (in development; latest release `0.3.0`) |
+| Version | `0.4.0-alpha.1` (prerelease; latest stable `0.3.2`) |
 | Target framework | .NET 10 |
 | Tailwind version | `4.3.2` |
 
@@ -57,7 +57,7 @@ The CLI writes the computed version into `shellui.json` for each installed entry
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0",
+      "Version": "0.4.0-alpha.1",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md
index f770229..1931dc4 100644
--- a/docs/CLI_INSTALLATION.md
+++ b/docs/CLI_INSTALLATION.md
@@ -4,7 +4,8 @@
 
 | Context | Version |
 |---|---|
-| Latest stable (recommended) | `0.3.0`, needs the .NET 10 runtime |
+| Latest stable (recommended) | `0.3.2`, needs the .NET 10 runtime |
+| Prerelease | `0.4.0-alpha.1`, install with `--version 0.4.0-alpha.1` |
 | Previous stable | `0.2.1` |
 | Tailwind | `4.3.2` |
 
@@ -43,7 +44,7 @@ The manifest is `.config/dotnet-tools.json` and uses the installed package versi
   "isRoot": true,
   "tools": {
     "shellui.cli": {
-      "version": "0.3.0",
+      "version": "0.3.2",
       "commands": ["shellui"]
     }
   }
diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md
index 246622f..67a2e79 100644
--- a/docs/CLI_SYNTAX.md
+++ b/docs/CLI_SYNTAX.md
@@ -1,6 +1,6 @@
 # ShellUI CLI Syntax
 
-This reference covers the CLI on `main` (0.4, in development): it runs on .NET 10, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 93 direct component targets. Some options, such as `--dashboard`, are not in the released 0.3.0; see the [v0.3.0 reference](https://github.com/shellui-dev/shellui/blob/v0.3.0/docs/CLI_SYNTAX.md) for that version.
+This reference covers CLI `0.4.0-alpha.1` (prerelease): it runs on .NET 10, sets up Blazor projects on .NET 8, 9 and 10, uses Tailwind CSS `4.3.2`, and has 93 direct component targets. Some options, such as `--dashboard`, are not in the released 0.3.0; see the [v0.3.0 reference](https://github.com/shellui-dev/shellui/blob/v0.3.0/docs/CLI_SYNTAX.md) for that version.
 
 ## Command prefix
 
@@ -250,7 +250,7 @@ Representative fields look like this:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.4.0",
+      "Version": "0.4.0-alpha.1",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 3fba5df..65e8874 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -6,7 +6,7 @@ Answers for the current ShellUI source and the currently published packages.
 
 ### Which version should I use?
 
-Use the latest stable release, `0.3.0`. It uses Tailwind CSS `4.3.2`. The 0.4 work on `main`, with 93 direct component targets, is not published yet:
+Use the latest stable release, `0.3.2`. It uses Tailwind CSS `4.3.2`. The `0.4.0-alpha.1` prerelease, with 93 direct component targets, needs `--version 0.4.0-alpha.1`:
 
 ```bash
 dotnet tool install -g ShellUI.CLI
@@ -145,7 +145,7 @@ A representative Tailwind and component record is:
   "InstalledComponents": [
     {
       "Name": "button",
-      "Version": "0.3.0",
+      "Version": "0.4.0-alpha.1",
       "InstalledAt": "2026-01-01T00:00:00Z",
       "IsCustomized": false
     }
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 7bd9ccd..dcc8cb0 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -1,6 +1,6 @@
 # ShellUI Quick Start
 
-This quick start uses ShellUI `0.3.0`: Tailwind CSS `4.3.2`. The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10.
+This quick start uses ShellUI `0.4.0-alpha.1`, a prerelease, with Tailwind CSS `4.3.2`. The CLI needs the .NET 10 SDK and works in Blazor projects on .NET 8, 9 and 10.
 
 ## Prerequisites
 
@@ -20,7 +20,7 @@ dotnet --version
 A global tool is invoked as `shellui`:
 
 ```bash
-dotnet tool install -g ShellUI.CLI
+dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.1
 shellui --version
 ```
 
diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md
index 7ab8084..74c3a56 100644
--- a/docs/RELEASE_NOTES.md
+++ b/docs/RELEASE_NOTES.md
@@ -1,5 +1,89 @@
 # ShellUI Release Notes
 
+# ShellUI v0.4.0-alpha.1 🧪
+
+> The first 0.4 prerelease. It adds 14 components, compositional parts for eight existing ones, dashboard and sign-in page blocks, and support for apps that use ASP.NET Core Identity. It is a prerelease, so installs need `--version`. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues).
+
+## ✨ New components
+
+The CLI now has 93 direct targets, up from 76 in 0.3.
+
+| Target | What it is |
+|---|---|
+| `kbd` | Keyboard key hint |
+| `aspect-ratio` | Fixed-ratio container |
+| `button-group` | Joined buttons, horizontal or vertical |
+| `toggle-group` | Single- or multi-select toggles (`@bind-Value` / `@bind-Values`) |
+| `input-group` | Input with `Prefix` / `Suffix` slots |
+| `number-input` | −/+ input with min, max and step |
+| `stat-card` | KPI tile with a trend badge |
+| `timeline` | Vertical event timeline |
+| `tree-view` | Expandable, selectable tree (`@bind-SelectedValue`) |
+| `qr-code` | QR code rendered as SVG (adds the `QRCoder` package) |
+| `image-viewer` | Thumbnail with a zoomable lightbox |
+| `chat`, `chat-message`, `chat-input` | AI chat panel, message bubbles with a streaming indicator, and a prompt input (Enter sends, Shift+Enter adds a line) |
+
+## 🧩 Compositional parts
+
+Eight more components can be built from parts, shadcn-style. Each mode is opt-in, so existing markup keeps working, and the parts install with their parent.
+
+- **AlertDialog:** `AlertDialogTrigger`, `Content`, `Header`, `Title`, `Description`, `Footer`, `Action`, `Cancel`. Escape acts as Cancel.
+- **Breadcrumb:** `BreadcrumbList`, `Link`, `Page`, `Separator`, `Ellipsis`.
+- **Command:** `CommandInput`, `List`, `Group`, `CommandOption`, `Empty`, `Separator`. The part is `CommandOption` because `CommandItem` is the model.
+- **Form:** `FormField`, `Item`, `Label`, `Control`, `Description`, `Message`, with live validation inside an `EditForm`.
+- **Menubar:** `MenubarMenu`, `Trigger`, `Content`, `Separator`. A `MenubarItem` with a `Title` is a dropdown; without one it is a clickable item.
+- **Pagination:** `PaginationContent`, `Item`, `Link`, `Previous`, `Next`, `Ellipsis`.
+- **Sheet and Drawer:** `Header`, `Title`, `Description`, `Footer`, `Close`. CLI templates use them with `Compositional="true"`.
+
+## 🧱 Blocks and `shellui init`
+
+- **Dashboard setup in `init`:** `init` asks for a layout (sticky header `dashboard-02`, scrolling header `dashboard-01`, or none), or takes `--dashboard 01|02|none`. Adding a dashboard wires it in: `Routes.razor` uses it, the stock `MainLayout` and `NavMenu` are removed when unmodified, the error bar moves to `App.razor`, and the sidebar links come from your pages. A custom layout is only replaced after you confirm or pass `--replace-layout`.
+- **Sample pages restyled:** unmodified `dotnet new blazor` pages (Home, Counter, Weather, Error, NotFound, Auth) get ShellUI's Tailwind classes, and Home becomes a short guide to themes and components. Edited pages are listed, not changed.
+- **ASP.NET Core Identity apps (`--auth Individual`):**
+  - The `/Account` pages render statically while the rest of the app is interactive. Before, `init` made every page interactive and the Identity pages returned Not Found.
+  - The dashboard sidebar shows Log in and Register, or the signed-in user and Log out.
+  - New blocks `auth-01` (centered card), `auth-02` (split screen) and `auth-03` (minimal) give the sign-in, sign-up and recovery pages their own layout and restyle the stock Identity pages for .NET 8, 9 and 10.
+- **Tailwind CLI:** in projects set up by this version, the build downloads the pinned Tailwind CLI when `.shellui/bin` has none, for example after a fresh clone, and warns if it can't instead of silently skipping Tailwind.
+- **Terminal:** `init` shows the ShellUI logo and an animated logo loader; `add`, `update` and theme commands use a compact spinner. Both fall back to plain lines without an interactive terminal.
+
+## 🎨 Component changes
+
+- **Loading** is rebuilt with 23 variants, including `logo`, `snake`, `wave`, `typing` and `shimmer`. Its keyframes ship inside the component, so the animations also work with the NuGet package. It follows `currentColor`, has `role="status"`, and slows down under reduced motion.
+- **Command** is rewritten: it filters as you type, supports ↑/↓/Home/End/Enter, optional `Group` headings and a footer with key hints. Selecting an item now runs its `CommandItem.Action`, then raises `CommandSelected`; before, `Action` was ignored. `CommandPalette` gets the same behavior and a bindable `IsOpen`.
+- **Dropdown and Popover** close on Escape.
+
+## 🐛 Fixes
+
+- The CLI's `SidebarProvider` logged `JSDisconnectedException` twice on every page reload. It no longer does.
+- `init --tailwind standalone|npm` now skips the Tailwind prompt, which ignored the flag. An unknown value fails before `init` changes the project, and `--yes` says that standalone is the default.
+- `shellui update` reported every requested component as updated. It now counts updated, skipped and failed components separately.
+- Everything fixed in 0.3.1 and 0.3.2 is included.
+
+## ⚠️ Breaking changes
+
+- **Calendar:** `SelectedDateChanged` is now `EventCallback<DateTime?>`, so `@bind-SelectedDate` works with a `DateTime?` field. Handlers that take a `DateTime` must take a `DateTime?`.
+
+## ⬆️ Upgrading from 0.3
+
+- **CLI:** update the tool to this version, then run `shellui update` to rewrite installed components from the new templates. `update` overwrites the files, so commit or back up any components you customized first. `Build/ShellUI.targets` is only written by `init`, so projects set up with 0.3 keep the old Tailwind build step.
+- **NuGet package:** update `ShellUI.Components` to `0.4.0-alpha.1`. If you handle `Calendar.SelectedDateChanged`, change the handler's parameter to `DateTime?`.
+
+## 📦 Installation
+
+```bash
+# CLI (prerelease: the version is required)
+dotnet tool install -g ShellUI.CLI --version 0.4.0-alpha.1
+# or upgrade an existing install
+dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.1
+```
+
+```bash
+# NuGet package
+dotnet add package ShellUI.Components --version 0.4.0-alpha.1
+```
+
+**Full Changelog**: https://github.com/shellui-dev/shellui/compare/v0.3.2...v0.4.0-alpha.1
+
 # ShellUI v0.3.2
 
 > A patch release with component fixes for both the `ShellUI.Components` NuGet package and the CLI templates.