Release Notes

What changed in the ShellUI 0.4 line, and how to upgrade.

The full history is in RELEASE_NOTES.md on GitHub. For 0.3.x, see the v0.3 release notes.

v0.4.0

The 0.4 stable release. Compared with 0.3 it adds 19 components and three sign-in page blocks, compositional parts for eight more, shellui add all, doctor and migrate, .NET 8 and 9 support, and a CLI that keeps your changes on update. This section sums up the whole 0.4 line; the alpha sections below have the details.

New in 0.4

  • Components. Kbd, Aspect Ratio, Button Group, Toggle Group, Input Group, Number Input, Stat Card, Timeline, Tree View, QR Code, Image Viewer and Chat with chat-message and chat-input (0.4.0-alpha.1), and since alpha.3:
    • Prompt Suggestions: clickable suggestion chips for an empty chat.
    • Reasoning: a collapsible block that streams a model's thinking, open while IsStreaming and folded to "Thought for N seconds" after.
    • Tool Call: a tool's name with a pending, running, done or error badge; it opens to show the arguments, result or error.
    • Field: label, control, description and validation message as one unit, vertical or horizontal; For shows the EditForm's messages.
    • JSON Viewer: a highlighted, foldable JSON tree from a string or any object, with a copy button.
    • Resizable is now a real panel group: ResizablePanelGroup, ResizablePanel (DefaultSize, MinSize, MaxSize) and ResizableHandle, dragged with the pointer or moved with the arrow keys, Home and End. The browser moves the panels and reports the sizes once, so dragging doesn't wait on Blazor Server. The old Resizable stays in the package, deprecated.
  • Blocks. init --dashboard 01|02 wires a dashboard layout into the app, and the new auth-01, auth-02 and auth-03 blocks give apps that use ASP.NET Core Identity their own sign-in pages.
  • Compositional parts for Alert Dialog, Breadcrumb, Command, Form, Menubar, Pagination, Sheet and Drawer. Each mode is opt-in, so existing markup keeps working.
  • SonnerService.Clear() and Destructive context menu items.
  • .NET 8 and 9. The CLI runs on .NET 8 or later, and ShellUI.Components targets .NET 8, 9 and 10. The 0.3 line needed .NET 10.

CLI

  • shellui add all installs every component except the page blocks; --except leaves out a component and everything that depends on it.
  • shellui doctor checks the project's setup and says how to fix each problem; it exits 1 on errors, so it can run in CI.
  • shellui migrate rewrites your pages for template API changes after update: Input.InputVariant.X, the DatePicker and TimePicker Selected* parameters and Pagination.OnPageChange. It shows each changed line and asks first (--dry-run, --yes), and points out Calendar handlers that need a DateTime?.
  • update keeps your changes and installs dependencies a component gained since you added it. add never downgrades a NuGet package. remove follows your ComponentsPath.
  • One Tailwind CLI per machine in ~/.shellui/bin, with resumable downloads, instead of a copy in every project.
  • Razor class libraries: init recognises a library shared by several apps. See Razor Class Library.

See the CLI guide for each command.

Fixes since 0.4.0-alpha.3

  • add hung on .NET 8 and 9 apps. The CLI waited for dotnet add package, npm and Tailwind to exit before reading their output, so once a process wrote more than a pipe buffer both sides waited forever. shellui add all stopped on restoring Blazor-ApexCharts. Output is now read while the process runs.
  • The CLI didn't start on a machine with only .NET 9 (or a newer runtime). It now rolls forward to any .NET 8 or later runtime.
  • doctor said app.css was stale right after a build. Tailwind skips writing unchanged output, so the file kept an old timestamp. The build now touches it; update brings the change to projects set up by alpha.2 and alpha.3.
  • list --installed said "0 available" (and --available "0 installed"). The summary now counts every target.
  • Safelist: classes passed to Shell.Cn("…") and literals in ternaries never reached shellui-classes.txt, so 198 classes were missing for apps that build their own Tailwind CSS from the package.
  • Everything fixed in 0.3.5 and 0.3.6 is included.

Breaking changes from 0.3

  • Calendar.SelectedDateChanged is EventCallback<DateTime?>. Handlers that take a DateTime must take a DateTime? (shellui migrate lists them).
  • CLI templates, after shellui update: Input.InputVariant is now InputVariant (new input-variants template); Stepper parts read the stepper's ActiveStep instead of a CurrentStep parameter; ScrollArea drops its scrollbar-* classes; shellui add resizable installs the panel group. shellui migrate fixes the InputVariant uses.
  • Still working but deprecated: Pagination.OnPageChange, DatePicker.SelectedDate, TimePicker.SelectedTime and the old Resizable. shellui migrate moves you off the first three.

Upgrading from 0.3

  • CLI: dotnet tool update -g ShellUI.CLI, then in each project commit, run shellui update, then shellui migrate, and build. shellui doctor checks the result.
  • NuGet package: update ShellUI.Components to 0.4.0. If you handle Calendar.SelectedDateChanged, change the handler's parameter to DateTime?.
  • If you used Class="…!" to beat a component's own classes, you can drop the !.

The same steps upgrade a project on a 0.4 prerelease.

bash
dotnet tool update -g ShellUI.CLI
shellui update
shellui migrate
shellui doctor
bash
dotnet add package ShellUI.Components --version 0.4.0

Full changelog: v0.3.6...v0.4.0

v0.4.0-alpha.3

The third 0.4 prerelease. A component's Class now overrides its own classes, dialogs and sheets keep keyboard focus inside, add never downgrades your NuGet packages, and the CLI templates have been brought in line with the NuGet package, fixing several template bugs on the way. It also adds Razor class library support.

Improvements

  • Class overrides a component's own classes. Shell.Cn used to join strings, so <Card Class="max-w-lg"> on a component that sets max-w-md put both on the element and the stylesheet decided. Now, when two classes set the same CSS property under the same variants, the later one (yours) wins, like tailwind-merge: p-4 replaces an earlier px-2, text colour and text size stay separate, and unknown classes are kept. You no longer need the ! modifier. The NuGet package and the CLI's Shell.cs share the same code.
  • Focus stays inside open overlays. Dialog, Alert Dialog, Sheet and Drawer keep Tab and Shift+Tab inside while they're open, and return focus to where it was when they close. The legacy (non-compositional) Sheet and Drawer panels now also take focus and close on Escape.
  • add never downgrades a NuGet package. It used to set the exact version a component pins, so adding chart to an app on Blazor-ApexCharts 7 moved it back to 6.0.2. Now it reads the project's PackageReference (or Directory.Packages.props), adds a missing package or raises an older one, and leaves the same or newer, floating versions and ranges alone.
  • Razor class libraries. init recognises a library shared by several apps, prints what each app needs with the library's _content path, and adds its @using to a root _Imports.razor. See Razor Class Library.

Fixes: CLI templates now match the package

The CLI templates and the NuGet package had drifted apart. They're reconciled (210 of 217 components identical, the rest differ by design), and a test now compares them. Bugs this fixed:

  • Radio Group (template): clicking an item did nothing, because the group never passed itself to its items. RadioGroupItem also gains Disabled.
  • ScrollArea (template): long content was clipped instead of scrolling. Height and MaxHeight now size the scrolling element.
  • Date Picker (package): day 1 was always drawn under Sunday. It now sits under its real weekday, and the picker opens on the selected month.
  • TimePicker: Step now filters the minutes (it was ignored), the picker opens on the current value, and Cancel or an outside click closes it.
  • DateRangePicker (template) closes on an outside click; EmptyState (template) applies Class.
  • Sheet and Drawer: clicks inside the panel no longer reach parent click handlers; the close button shows when only Description is set; the templates switch to compositional mode by themselves (no Compositional="true" needed).
  • Label renders For as the for attribute; FileUpload uses an inline SVG icon instead of the Material Symbols font; CarouselItem handles zero slides.
  • Pagination supports @bind-CurrentPage in both copies and ignores clicks on the current page; Toast has success and warning variants, Position, auto-dismiss after Duration (0 keeps it open) and a labelled close button; Skeleton has Variant (default, circle, text); NavigationMenuItem is a dropdown when Title is set and a link or button otherwise.
  • Table, Separator, Slider, Navbar, Checkbox, Switch, Tooltip, SidebarMenuButton, Menubar and ThemeToggle templates now match the package's markup and classes.

Breaking changes (CLI templates, after shellui update)

  • Input variants moved out of the component: Input.InputVariant.Error is now InputVariant.Error, from the new input-variants template in Components/UI/Variants (like ButtonVariant). Textarea gains Variant, ReadOnly, OnFocus and OnBlur through textarea-variants.
  • Stepper parts read the stepper's ActiveStep instead of taking a CurrentStep parameter, and the template gains the package's data-driven StepItems mode (StepItem comes from the new stepper-models template).
  • ScrollArea drops its scrollbar-* classes, which needed a Tailwind plugin nobody shipped.
  • Still working but deprecated: Pagination.OnPageChange (use @bind-CurrentPage), DatePicker.SelectedDate and TimePicker.SelectedTime (use Value / @bind-Value).

shellui update installs the new input-variants, textarea-variants and stepper-models templates for you, and skips files you've changed since installing them.

Upgrading from 0.4.0-alpha.2

  • CLI: update the tool, then run shellui update. Commit first so you can review the changes, and fix any Input.InputVariant and Stepper CurrentStep uses (see above).
  • NuGet package: update ShellUI.Components to 0.4.0-alpha.3.
  • If you used Class="…!" to beat a component's own classes, you can drop the !.

Upgrading from 0.3: follow the 0.4.0-alpha.1 and 0.4.0-alpha.2 notes below, then the steps above.

bash
dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.3
dotnet add package ShellUI.Components --version 0.4.0-alpha.3

Full changelog: v0.4.0-alpha.2...v0.4.0-alpha.3

v0.4.0-alpha.2

The second 0.4 prerelease. It fixes shellui update, which could leave a project upgraded from 0.3 unable to build, and makes update keep the files you changed. The Tailwind CLI is now downloaded once per machine instead of into every project, and the download survives slow connections. It also fixes remove, the dark theme and the package TimePicker.

Tailwind CLI: once per machine

  • Projects no longer hold the binary. The standalone Tailwind CLI (about 110 MB) is downloaded once into ~/.shellui/bin (or SHELLUI_CACHE_DIR), and init and the build run it from there. A new project went from about 112 MB to 130 KB, and later projects set up offline. A copy in a project's .shellui/bin still takes precedence. The binary is a build tool and never ships with your app.
  • Nothing in .shellui/ is committed: it now contains a .gitignore of *.
  • Slow connections work. The download streams to a .partial file, resumes after a dropped connection, retries, and only gives up after a minute with no data. The build's own download uses the same cache and retries too.
  • A failed download no longer stops init. It finishes the rest of the setup and warns, and the next build tries again; its warning names the URL and where to save the file.

shellui update and remove

  • update installs new dependencies. Components gain parts between versions; in 0.4, breadcrumb gained breadcrumb-list, -link, -page, -separator and -ellipsis, and tabs gained tab-models. update only rewrote existing files, so a project updated from 0.3 failed to build (BreadcrumbList, TabItem not found). It now installs missing dependencies the way add does, with their NuGet packages and _Imports.razor usings.
  • update keeps your changes. shellui.json now records a hash of each file the CLI writes. update skips files you have changed since and says so; --force overwrites them.
  • remove finds files the way install writes them. It honours a custom ComponentsPath, removes dashboard and auth layouts, lists files that still use a removed layout (usually Routes.razor), and counts what it removed.

Fixes

  • Dark theme: the themes set color-scheme, so the browser draws its own controls (the <input type="date"> calendar, number spinners, scrollbars, autofill, <select> lists) dark on a dark page.
  • NuGet package TimePicker threw a FormatException whenever Value was set. It now shows the time.
  • NuGet package shellui-theme.css no longer logs a 404 when linked directly.
  • NuGet packages have the ShellUI icon and show the logo at the top of their README.
  • Everything fixed in 0.3.3 and 0.3.4 is included.

Upgrading from 0.4.0-alpha.1

  • CLI: update the tool, then run shellui update. Files installed by alpha.1 have no recorded hash, so this first update keeps app-sidebar, sidebar-account and the dashboard and auth layouts if they differ from the template, and rewrites the other components. Commit first so you can review the changes. From then on, every file you edit is kept.
  • Tailwind CLI: the same shellui update replaces Build/ShellUI.targets if you haven't edited it, adds .shellui/.gitignore, and deletes the project's copy of the Tailwind CLI when it's the same as the shared one. An edited targets file is left alone with a note.
  • Existing input.css: update doesn't rewrite it. Add color-scheme: light; inside :root and color-scheme: dark; inside .dark, or run shellui theme apply again if you use a tweakcn theme.
  • NuGet package: update ShellUI.Components to 0.4.0-alpha.2.

Upgrading from 0.3: follow the 0.4.0-alpha.1 notes below, then the steps above.

bash
dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.2
dotnet add package ShellUI.Components --version 0.4.0-alpha.2

Full changelog: v0.4.0-alpha.1...v0.4.0-alpha.2

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.

Prerelease

Installs need --version 0.4.0-alpha.1. The stable release is still 0.3.2. Report issues on GitHub.

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
input-group Input with Prefix and Suffix slots
number-input Stepper input with min, max and step
stat-card KPI tile with a trend badge
timeline Vertical event timeline
tree-view Expandable, selectable tree
qr-code QR code rendered as SVG (adds the QRCoder package)
image-viewer Thumbnail with a zoomable lightbox
chat, chat-message, chat-input Chat panel, message bubbles with a streaming indicator, and a prompt input

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.

  • Alert Dialog: 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.
  • Form: FormField, Item, Label, Control, Description, Message, with live validation inside an EditForm.
  • Menubar: MenubarMenu, Trigger, Content, Separator.
  • 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, or takes --dashboard 01|02|none, and 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. See the dashboard guide.
  • Sample pages restyled: unmodified dotnet new blazor pages get ShellUI's Tailwind classes. Edited pages are listed, not changed.
  • ASP.NET Core Identity apps: the /Account pages render statically while the rest of the app is interactive, the dashboard sidebar shows the sign-in state, and the new auth-01, auth-02 and auth-03 blocks restyle the sign-in pages. See Authentication.
  • 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.
  • Terminal: init shows the ShellUI logo and an animated loader; add, update and the theme commands use a compact spinner.

Component changes

  • Loading is rebuilt with 23 variants, including logo, snake, wave, typing and shimmer. Its animations ship inside the component, so they also work with the NuGet package.
  • Command is rewritten: it filters as you type, supports the arrow keys, Home, End and Enter, and has optional group headings. Selecting an item now runs its CommandItem.Action, then raises CommandSelected. Command Palette 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, and an unknown value fails before init changes the project.
  • shellui update 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

With the CLI, update the tool, then rewrite the installed components from the new templates:

bash
dotnet tool update -g ShellUI.CLI --version 0.4.0-alpha.1
shellui update

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.

With the NuGet package:

bash
dotnet add package ShellUI.Components --version 0.4.0-alpha.1

If you handle Calendar.SelectedDateChanged, change the handler's parameter to DateTime?. If a CommandSelected handler runs the item's Action itself, remove that call.

Full changelog: v0.3.2...v0.4.0-alpha.1

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.