diff --git a/README.md b/README.md index 1dac508..9fdd77f 100644 --- a/README.md +++ b/README.md @@ -87,10 +87,12 @@ New CLI sidebar installs use the host-loaded `shellui.js`; the legacy `sidebar-j | Command | Purpose | |---|---| | `init` | Set up ShellUI, Tailwind, host wiring, and the generated project structure | -| `add ` | Install one or more direct targets and their hidden dependencies | +| `add ` | Install one or more direct targets (or `all`) and their hidden dependencies | | `list` | List direct targets, installed targets, or targets still available | | `remove ` | Remove named installed components | -| `update [components...]` | Reinstall named or all installed templates | +| `update [components...]` | Reinstall named or all installed templates, skipping files you changed unless `--force` | +| `doctor` | Check the project's setup and say how to fix each problem | +| `migrate [components...]` | Rewrite your pages for template API changes | | `theme init ` | Initialize a project and apply a tweakcn theme | | `theme apply ` | Apply a theme to `wwwroot/input.css` or emit override CSS | | `theme update` | Re-fetch the source recorded in `shellui.theme.lock` | diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md index 0827b99..7a4dfae 100644 --- a/VERSIONING_STRATEGY.md +++ b/VERSIONING_STRATEGY.md @@ -10,7 +10,7 @@ ShellUI uses one centralized version for the source templates, CLI tool, and pac | Target framework | .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) | | Tailwind version | `4.3.2` | -`0.3.0-rc.1` was the last release targeting .NET 9. +`0.3.0-rc.1` was the last release built only for .NET 9. `0.3.0-rc.2` through `0.3.6` and the 0.4 prereleases need .NET 10; `0.4.0` supports .NET 8, 9 and 10. ## Single Source of Truth @@ -59,14 +59,15 @@ The CLI writes the computed version into `shellui.json` for each installed entry "Name": "button", "Version": "0.4.0", "InstalledAt": "2026-01-01T00:00:00Z", - "IsCustomized": false + "IsCustomized": false, + "Hash": "3b1f9c0e7a52d84f6e2c19ab07d4e5f8c6a3b2d1e0f9a8b7c6d5e4f3a2b1c0d9" } ], "ProjectType": 1 } ``` -The timestamp is illustrative. A copied component is source owned by the consumer, so its recorded version identifies the registry release used at install or update time; it does not automatically track a later package publication. +The timestamp and hash are illustrative. A copied component is source owned by the consumer, so its recorded version identifies the registry release used at install or update time; it does not automatically track a later package publication. Theme data has a separate lock file. `shellui.theme.lock` records the theme source URL, content hash, theme name, and application time. That lock controls `theme update` and is independent of the component version. @@ -88,7 +89,7 @@ A local tool manifest can pin the same version for a team. An unversioned instal `ShellUI.Components` is the runtime RCL package. Select its published version explicitly when using NuGet: ```bash -dotnet add package ShellUI.Components --version --prerelease +dotnet add package ShellUI.Components --version ``` Do not add `ShellUI.Core` or `ShellUI.Templates` to a consumer project. They are internal implementation projects. @@ -153,7 +154,7 @@ The unified version applies to the source system and the two packable artifacts. ## Compatibility Boundaries -- The current repository baseline is .NET 10. This strategy does not claim support for an older target framework that is not configured in the current projects. +- The repository builds with the .NET 10 SDK. The CLI, Core and Templates target .NET 8 and .NET 10 (the CLI rolls forward to newer runtimes), and `ShellUI.Components` targets .NET 8, 9 and 10. This strategy does not claim support for a target framework that is not configured in the current projects. - Tailwind CSS `4.3.2` is the current generated-CSS baseline. - The CLI and the NuGet RCL are separate consumption paths, but a project that combines them should use versions from the same ShellUI release line. - CLI-installed files are copied into the consumer project and remain subject to the consumer's own edits. Updating them is an explicit CLI operation, not an automatic package update. @@ -161,4 +162,4 @@ The unified version applies to the source system and the two packable artifacts. ## Summary -The version is centralized in `Directory.Build.props`, targeting .NET 10 and Tailwind CSS `4.3.2`. `ShellUI.CLI` and `ShellUI.Components` are the only packable artifacts. Prerelease versions must be selected explicitly. +The version is centralized in `Directory.Build.props`, targeting .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) and Tailwind CSS `4.3.2`. `ShellUI.CLI` and `ShellUI.Components` are the only packable artifacts. Prerelease versions must be selected explicitly. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 14866df..adadb10 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -77,15 +77,17 @@ The implemented command tree is: | Command | Responsibility | |---|---| | `shellui init` | Detect a Blazor project, configure Tailwind, install bootstrap assets, create `shellui.json`, patch the host, and create the MSBuild integration. | -| `shellui add ` | Install one or more direct targets and recursively install their registry dependencies. | +| `shellui add ` | Install one or more direct targets (or `all`) and recursively install their registry dependencies. | | `shellui list` | List direct targets, with installed/available filtering. | | `shellui remove ` | Remove selected installed source files and update `shellui.json`. | | `shellui update [components...]` | Rewrite selected installed source files, or all installed components with `--all`; skips files changed since install unless `--force`, and installs new dependencies. | +| `shellui doctor` | Check `shellui.json`, Tailwind, the host page, render mode, installed files and usings; print a fix for each problem and exit 1 on errors. | +| `shellui migrate [components...]` | Rewrite the app's own `.razor` and `.cs` files for template API changes, showing a diff and asking first. | | `shellui theme init ` | Initialize a project and apply a fetched theme in one operation. | | `shellui theme apply ` | Apply a theme to `wwwroot/input.css` or emit a standalone override. | | `shellui theme update` | Re-fetch the theme recorded in `shellui.theme.lock`. | -`init` accepts `--force`, `--style`, `--tailwind standalone|npm`, and `--yes`. `add` accepts space- or comma-separated component names and `--force`. The command surface above is the current implementation; commands not listed here are not part of the current CLI. +`init` accepts `--force`, `--style`, `--tailwind standalone|npm`, `--yes`, `--dashboard 01|02|none`, and `--replace-layout`. `add` accepts space- or comma-separated component names, `--force`, `--replace-layout`, and `--except`. The command surface above is the current implementation; commands not listed here are not part of the current CLI. ## Registry Model and Counts @@ -107,10 +109,10 @@ A dependency entry is still real source and is written to the consumer project w 4. The installer walks `Dependencies` recursively before writing the requested target. Hidden entries are installed through this walk rather than being presented as normal public targets. 5. The installer retrieves the template content, substitutes the consumer namespace, and writes it according to the metadata `FilePath` under `Components/UI`, `Components/Layout`, or a project `wwwroot` path. 6. Required NuGet dependencies are collected during the walk and added once per package after source files are written. CSS assets are linked into the host when applicable. -7. The installer records each installed name, computed version, installation time, and customization state in `shellui.json`. +7. The installer records each installed name, computed version, installation time, customization state, and a hash of the written file in `shellui.json`. 8. The generated MSBuild integration runs Tailwind during the consumer build, producing the configured CSS output. -`remove` deletes the selected installed file and removes its record. The current remove path is optimized for regular component targets; layout blocks should be removed manually from `Components/Layout` until layout-aware removal is implemented. `update` rewrites selected source from the current registry and records the installed version. Theme commands use a separate managed CSS region and write `shellui.theme.lock`; theme updates re-fetch the recorded source rather than changing the component version. +`remove` deletes the selected installed file and removes its record. For a layout block it deletes the file from `Components/Layout` and lists the `.razor` files that still reference the layout; it does not undo the layout wiring. `update` rewrites selected source from the current registry and records the installed version. Theme commands use a separate managed CSS region and write `shellui.theme.lock`; theme updates re-fetch the recorded source rather than changing the component version. ## Build and Test Flow diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md index ecf0492..ba0b5dc 100644 --- a/docs/CLI_INSTALLATION.md +++ b/docs/CLI_INSTALLATION.md @@ -43,7 +43,7 @@ The manifest is `.config/dotnet-tools.json` and uses the installed package versi "isRoot": true, "tools": { "shellui.cli": { - "version": "0.3.5", + "version": "0.4.0", "commands": ["shellui"] } } diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md index 040222f..df27788 100644 --- a/docs/CLI_SYNTAX.md +++ b/docs/CLI_SYNTAX.md @@ -308,14 +308,15 @@ Representative fields look like this: "Name": "button", "Version": "0.4.0", "InstalledAt": "2026-01-01T00:00:00Z", - "IsCustomized": false + "IsCustomized": false, + "Hash": "3b1f9c0e7a52d84f6e2c19ab07d4e5f8c6a3b2d1e0f9a8b7c6d5e4f3a2b1c0d9" } ], "ProjectType": 1 } ``` -`ProjectType` is serialized as the enum value; `1` is `BlazorServer`. `IsCustomized` is metadata, not a merge mechanism. `update` still overwrites the file. +`ProjectType` is serialized as the enum value; `1` is `BlazorServer`. `Hash` is what `update` compares the file with to spot your changes (entries written before 0.4.0-alpha.2 have none), and `update` sets `IsCustomized` on a file it skips for that reason. Neither is a merge mechanism; `update --force` still overwrites the file. ## Common workflow diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md index 71eb178..3fa23ea 100644 --- a/docs/COMPARISON.md +++ b/docs/COMPARISON.md @@ -23,7 +23,7 @@ The direct-target count is the number users invoke with `shellui add`. It is not | CLI workflow | Yes | No CLI in this comparison | No CLI in this comparison | No CLI in this comparison | No CLI in this comparison | No CLI in this comparison | | Accessibility status | Semantic markup is used; no current WCAG conformance claim | Not audited here | Not audited here | Not audited here | Not audited here | Not audited here | | Bundle/performance status | No current reproducible benchmark published | No current benchmark published here | No current benchmark published here | No current benchmark published here | No current benchmark published here | No current benchmark published here | -| Community status | Current project is an alpha snapshot; no comparable size claim | See the current project community | See the current project community | See the current project community | See the current project community | See the current project community | +| Community status | Pre-1.0 project; no comparable size claim | See the current project community | See the current project community | See the current project community | See the current project community | See the current project community | The “not audited here” cells are intentional. They avoid presenting stale component counts, community metrics, or performance estimates as if they were current facts. diff --git a/docs/COMPONENT_DEPENDENCIES.md b/docs/COMPONENT_DEPENDENCIES.md index a8f1789..3df247a 100644 --- a/docs/COMPONENT_DEPENDENCIES.md +++ b/docs/COMPONENT_DEPENDENCIES.md @@ -87,7 +87,7 @@ Several entries are deliberately hidden from `shellui list` while remaining part - `button-variants` is hidden and is required by `button`. - `card-header`, `card-title`, `card-description`, `card-content`, and `card-footer` are hidden card sub-components, not independent public card targets. - `shell` is a hidden utility installed during `shellui init` and used by the sidebar graph. -- `shellui-js` is a hidden JavaScript support asset. It is used by `copy-button`, `file-upload`, `input-otp`, `theme-toggle`, `command-palette`, and the hidden `sidebar-provider`; it is not a standalone public component. +- `shellui-js` is a hidden JavaScript support asset. It is used by `copy-button`, `file-upload`, `input-otp`, `theme-toggle`, `command-palette`, `resizable`, and the hidden `sidebar-provider`; it is not a standalone public component. - `data-table-models`, `chart-variants`, `chart-styles`, `context-menu-models`, and similar entries are hidden support templates used by their registered parents. A hidden entry can have an empty `Dependencies` list while still being required by a parent. For example, the metadata for `shellui-js` describes the asset itself; it does not turn every component that uses the asset into a dependency of the asset. diff --git a/docs/COMPONENT_ROADMAP.md b/docs/COMPONENT_ROADMAP.md index b2fe6c3..eddc7ad 100644 --- a/docs/COMPONENT_ROADMAP.md +++ b/docs/COMPONENT_ROADMAP.md @@ -2,14 +2,14 @@ **Goal:** Build the components and tooling needed for a Tailwind-first Blazor design system. -.NET 10 · Tailwind CSS `4.3.2` +.NET 8, 9 and 10 · Tailwind CSS `4.3.2` ## Current inventory -`ComponentRegistry` is the source of truth for component availability, names, and dependencies. The current registry contains **243 entries**: +`ComponentRegistry` is the source of truth for component availability, names, and dependencies. The current registry contains **254 entries**: -- **93 direct CLI targets** shown by `shellui list` -- **150 hidden entries** for sub-components, variants, models, services, and support assets +- **98 direct CLI targets** shown by `shellui list` +- **156 hidden entries** for sub-components, variants, models, services, and support assets - **Packable projects:** `ShellUI.CLI` and `ShellUI.Components` Hidden entries are not counted as direct targets. They can still be installed recursively when a parent target declares them. @@ -81,6 +81,13 @@ The current registry provides explicit sub-components for these parent component - [x] **ContextMenu** — `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuOption` - [x] **NavigationMenu** — `NavList`, `NavItem`, `NavTrigger`, `NavContent` - [x] **Carousel** — `CarouselList`, `CarouselSlide` +- [x] **AlertDialog** — `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogAction`, `AlertDialogCancel` (0.4) +- [x] **Breadcrumb** — `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` (0.4) +- [x] **Command** — `CommandInput`, `CommandList`, `CommandGroup`, `CommandOption`, `CommandEmpty`, `CommandSeparator` (0.4) +- [x] **Form** — `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription`, `FormMessage` (0.4) +- [x] **Menubar** — `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarSeparator` (0.4) +- [x] **Pagination** — `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` (0.4) +- [x] **Resizable** — `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` (0.4; the old `Resizable` is deprecated) The intended pattern is explicit child components, cascaded state and callbacks, value/label parameters, and Tailwind utility classes matching the shadcn-style API. diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index ec5c89c..d77b484 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,10 +1,10 @@ # Contributing to ShellUI -ShellUI targets .NET 8 and .NET 10 and Tailwind CSS `4.3.2`. This guide describes the contribution and verification workflow; releases are covered in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md) and [RELEASING.md](RELEASING.md). +ShellUI targets .NET 8 and .NET 10 (`ShellUI.Components` also .NET 9) and Tailwind CSS `4.3.2`. This guide describes the contribution and verification workflow; releases are covered in [VERSIONING_STRATEGY.md](../VERSIONING_STRATEGY.md) and [RELEASING.md](RELEASING.md). ## Contribution Policy -ShellUI is an active alpha project. Focused bug fixes, documentation corrections, tests, and component or CLI improvements are welcome through GitHub issues and pull requests. +ShellUI is an active pre-1.0 project. Focused bug fixes, documentation corrections, tests, and component or CLI improvements are welcome through GitHub issues and pull requests. Before starting a substantial new component, a new distribution path, or a change to the registry contract: @@ -13,7 +13,7 @@ Before starting a substantial new component, a new distribution path, or a chang 3. Agree on the smallest useful scope before implementing a large change. 4. Keep the change compatible with the current architecture unless the proposal explicitly changes that architecture. -Alpha software can change its APIs and generated source. An issue or pull request is not a promise that a feature will be accepted, scheduled, or released. There is no response-time or adoption target in this policy. +Pre-1.0 software can change its APIs and generated source. An issue or pull request is not a promise that a feature will be accepted, scheduled, or released. There is no response-time or adoption target in this policy. Implemented features should be described as implemented. Ideas that have no implementation or release assignment belong in an issue or in the unscheduled section below, not in current-status documentation. @@ -45,7 +45,7 @@ dotnet restore ShellUI.slnx dotnet build ShellUI.slnx --configuration Release ``` -The CLI supports the implemented commands `init`, `add`, `list`, `remove`, `update`, `theme init`, `theme apply`, and `theme update`. Use a local build when testing changes; do not substitute an older published CLI merely because it is easier to install. +The CLI supports the implemented commands `init`, `add`, `list`, `remove`, `update`, `doctor`, `migrate`, `theme init`, `theme apply`, and `theme update`. Use a local build when testing changes; do not substitute an older published CLI merely because it is easier to install. The precompiled CSS and safelist are generated as part of the CI workflow. When changing component CSS, variant helpers, or safelist inputs, regenerate the safelist and then build the bundle: @@ -93,7 +93,7 @@ For a component change: 1. Update the live component and its generated template together. 2. Update registry metadata, dependencies, `FilePath`, variants, and NuGet dependencies when the public contract changes. -3. Preserve the distinction between direct targets and hidden dependency entries. The current registry has 243 entries, including 93 direct targets and 150 hidden entries. +3. Preserve the distinction between direct targets and hidden dependency entries. The current registry has 254 entries, including 98 direct targets and 156 hidden entries. 4. Use the Tailwind `4.3.2` variable and utility conventions already used by the project. 5. Add or update tests that exercise the changed registry, template, or CLI behavior. 6. Review keyboard and assistive-technology behavior without claiming a blanket accessibility conformance level that the repository does not test. diff --git a/docs/FAQ.md b/docs/FAQ.md index ed93b18..fd0cedc 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -49,7 +49,7 @@ shellui add button,input,card shellui add button,card dialog ``` -Use the exact names printed by `shellui list`. Dependency-only entries are installed automatically and are not counted among the 93 direct targets. +Use the exact names printed by `shellui list`. Dependency-only entries are installed automatically and are not counted among the 98 direct targets. ### Which names should I use? @@ -87,7 +87,7 @@ shellui list --installed shellui list --available ``` -There are 93 direct targets. Use the command output as the authoritative name list. +There are 98 direct targets. Use the command output as the authoritative name list. ### What happens when I update a component? @@ -147,14 +147,15 @@ A representative Tailwind and component record is: "Name": "button", "Version": "0.4.0", "InstalledAt": "2026-01-01T00:00:00Z", - "IsCustomized": false + "IsCustomized": false, + "Hash": "3b1f9c0e7a52d84f6e2c19ab07d4e5f8c6a3b2d1e0f9a8b7c6d5e4f3a2b1c0d9" } ], "ProjectType": 1 } ``` -`IsCustomized` is metadata only. It does not provide a merge workflow, and `update` overwrites the file. +`IsCustomized` is metadata only. It does not provide a merge workflow: `update` skips a file you have changed since the CLI wrote it, and `update --force` overwrites it. ### Which files does `init` create or update? @@ -247,7 +248,7 @@ For standalone mode, check `~/.shellui/bin`. For npm mode, run `npm install`. ### How do I update the NuGet package? -Pass the version explicitly: +Run the same command again; without `--version` it moves the reference to the latest stable release: ```bash dotnet add package ShellUI.Components diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 7e9c282..df0badc 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -33,19 +33,21 @@ add list remove update +doctor +migrate theme init theme apply theme update ``` -`init` configures a Blazor project, Tailwind, host bootstrap assets, `shellui.json`, and MSBuild integration. `add` installs direct targets and their dependencies. `list` exposes the public direct targets. `remove` and `update` operate on installed source. The theme commands fetch themes from tweakcn, update a managed CSS region or an override file, and record `shellui.theme.lock` for `theme update`. +`init` configures a Blazor project, Tailwind, host bootstrap assets, `shellui.json`, and MSBuild integration. `add` installs direct targets and their dependencies. `list` exposes the public direct targets. `remove` and `update` operate on installed source. `doctor` checks the project's setup and `migrate` rewrites the app's own pages for template API changes. The theme commands fetch themes from tweakcn, update a managed CSS region or an override file, and record `shellui.theme.lock` for `theme update`. ### Registry and components -`ComponentRegistry` has 243 entries: +`ComponentRegistry` has 254 entries: -- 93 direct targets with `IsAvailable = true`. -- 150 hidden entries with `IsAvailable = false`, generally installed as dependencies or assets. +- 98 direct targets with `IsAvailable = true`. +- 156 hidden entries with `IsAvailable = false`, generally installed as dependencies or assets. The direct-target count is the number shown by the normal public list. The hidden count is not a second public library; it represents the sub-components, variants, models, services, and assets needed to make the direct targets work. @@ -118,7 +120,7 @@ For a published tool or package, select the version available in the intended ch ```bash dotnet tool install -g ShellUI.CLI --version -dotnet add package ShellUI.Components --version --prerelease +dotnet add package ShellUI.Components --version ``` To test a checkout, build the CLI locally and install that package with the version from `Directory.Build.props`: diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index a42963e..882d549 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -68,7 +68,7 @@ Dependencies are copied automatically. Use `--force` to overwrite an existing co shellui add button --force ``` -Use the exact names shown by `shellui list`. There are 93 direct targets; dependency-only registry entries are not direct targets. +Use the exact names shown by `shellui list`. There are 98 direct targets; dependency-only registry entries are not direct targets. ## Use a component @@ -95,7 +95,8 @@ Edit `wwwroot/input.css`, not the generated `wwwroot/app.css`. The current v4 in @custom-variant dark (&:is(.dark *)); :root { - --primary: oklch(0.55 0.22 264.53); + color-scheme: light; + --primary: oklch(0 0 0); --primary-foreground: oklch(1 0 0); } diff --git a/docs/RELEASING.md b/docs/RELEASING.md index 41a52af..74e4f3b 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -32,38 +32,38 @@ The version rules and the `prepare-release.ps1` dry run are in [VERSIONING_STRAT ```xml 0.4.0 -alpha.3 + ``` Also update the version mentioned in `README.md`, `VERSIONING_STRATEGY.md`, `docs/CLI_INSTALLATION.md`, `docs/CLI_SYNTAX.md`, `docs/FAQ.md`, `docs/QUICKSTART.md`, and the fallback in `src/ShellUI.Templates/VersionHelper.cs` and `src/ShellUI.Core/Models/ComponentMetadata.cs`. `git grep` the previous version to find them all. ### 2. Release notes -Add a `# ShellUI v0.4.0-alpha.3` section at the top of `docs/RELEASE_NOTES.md`: what's new, fixes, breaking changes, and how to upgrade. Each section describes only its own release. Check that the workflow will find it: +Add a `# ShellUI v0.4.0` section at the top of `docs/RELEASE_NOTES.md`: what's new, fixes, breaking changes, and how to upgrade. Each section describes only its own release. Check that the workflow will find it: ```bash -bash scripts/extract-release-notes.sh 0.4.0-alpha.3 +bash scripts/extract-release-notes.sh 0.4.0 ``` ### 3. Check - If component CSS changed, regenerate the safelist (`dotnet run --project tools/ShellUI.SafelistGenerator -- …`, full command in VERSIONING_STRATEGY.md). -- `pwsh ./prepare-release.ps1 -Version 0.4.0 -Suffix alpha.3 -DryRun` builds, tests and checks the notes section. +- `pwsh ./prepare-release.ps1 -Version 0.4.0 -DryRun` (add `-Suffix alpha.1` for a prerelease) builds, tests and checks the notes section. - Pack both projects to a local folder, install the CLI from it into a tool path, and run `shellui init` and `shellui add` in fresh apps on .NET 8, 9 and 10 (all direct targets together, app named `my-app`). - Use the packed `ShellUI.Components` in a fresh app and click through the components the release changed, in light and dark mode. - Delete the local test packages from `~/.nuget/packages` afterwards, so later restores fetch the published ones. ### 4. Merge and tag -Open a `chore(release): v0.4.0-alpha.3` pull request, merge it, then tag the merge commit: +Open a `chore(release): v0.4.0` pull request, merge it, then tag the merge commit: ```bash git switch main && git pull --ff-only -git tag v0.4.0-alpha.3 -git push origin v0.4.0-alpha.3 +git tag v0.4.0 +git push origin v0.4.0 ``` -Watch the **Release** workflow in the Actions tab. If it fails before **Publish to NuGet**, fix it, delete the tag (`git push --delete origin v0.4.0-alpha.3`, `git tag -d v0.4.0-alpha.3`) and tag again. Once a version is on nuget.org it can't be reused, only unlisted. +Watch the **Release** workflow in the Actions tab. If it fails before **Publish to NuGet**, fix it, delete the tag (`git push --delete origin v0.4.0`, `git tag -d v0.4.0`) and tag again. Once a version is on nuget.org it can't be reused, only unlisted. ## 0.3.x patches diff --git a/docs/tailwind-setup.md b/docs/tailwind-setup.md index 27919c9..714c884 100644 --- a/docs/tailwind-setup.md +++ b/docs/tailwind-setup.md @@ -18,7 +18,7 @@ For a production Blazor application, use either the standalone or npm workflow a ## Prerequisites -- .NET 10.0 SDK +- .NET 8 SDK or later - A Blazor project - Node.js and npm only when using the npm method @@ -38,13 +38,13 @@ Run this from the project directory: shellui init ``` -The default standalone method downloads the Tailwind 4.3.2 standalone executable into `.shellui/bin`, creates the CSS entry point and output file, wires an MSBuild target, and creates the ShellUI component folders. To choose npm explicitly: +The default standalone method downloads the Tailwind 4.3.2 standalone executable once per machine into `~/.shellui/bin`, creates the CSS entry point and output file, wires an MSBuild target, and creates the ShellUI component folders. To choose npm explicitly: ```text shellui init --tailwind npm --yes ``` -Other initialization options include `--style`, `--force`, and `--yes`. The current CLI's npm setup invokes npm through `cmd`; use standalone mode on non-Windows systems or run the npm commands manually. +Other initialization options include `--style`, `--force`, `--yes`, `--dashboard` and `--replace-layout`. The current CLI's npm setup invokes npm through `cmd`; use standalone mode on non-Windows systems or run the npm commands manually. ### Add and manage components @@ -56,6 +56,8 @@ shellui add shellui list shellui remove shellui update [components] +shellui doctor +shellui migrate [components] shellui theme init shellui theme apply shellui theme update diff --git a/src/ShellUI.CLI/README.md b/src/ShellUI.CLI/README.md index 7908c11..c9ae49e 100644 --- a/src/ShellUI.CLI/README.md +++ b/src/ShellUI.CLI/README.md @@ -38,10 +38,12 @@ dotnet watch | Command | Purpose | |---|---| | `init` | Set up ShellUI and Tailwind in the current project | -| `add ` | Install components and their dependencies | -| `list` | List the 93 components, with `--installed` or `--available` filters | +| `add ` | Install components and their dependencies (`add all` for the whole library) | +| `list` | List the 98 components and blocks, with `--installed` or `--available` filters | | `remove ` | Delete installed component files | -| `update [names...]` | Rewrite installed components from the current templates (`--all` for every one) | +| `update [names...]` | Rewrite installed components from the current templates (all of them when no names are given) | +| `doctor` | Check the project's ShellUI setup and say how to fix each problem | +| `migrate [names...]` | Rewrite your pages for template API changes, showing a diff and asking first | | `theme init ` | Run `init`, then apply a [tweakcn](https://tweakcn.com) theme | | `theme apply ` | Apply a tweakcn theme to `wwwroot/input.css`, or write an override file with `--emit-override ` | | `theme update` | Re-apply the theme recorded in `shellui.theme.lock` | @@ -55,7 +57,7 @@ dotnet watch - `--replace-layout` switches to the dashboard even when the app has a custom layout. - `--style` is recorded in `shellui.json`. All styles currently install the same templates. -`add` accepts names separated by spaces or commas, and `--force` overwrites existing files. `update` and `add --force` overwrite your copies, so commit customized components first. `add dashboard-01` or `add dashboard-02` also makes the dashboard the default layout and builds its sidebar links from your pages. `remove` does not handle dashboard layouts; delete those from `Components/Layout/` yourself. +`add` accepts names separated by spaces or commas, and `--force` overwrites existing files. `add all` installs every component except the layout blocks (`dashboard-*`, `auth-*`), and `--except ` leaves out components and everything that needs them. `update` skips files you have changed since the CLI wrote them; `update --force` and `add --force` overwrite your copies, so commit customized components first. After `update`, `migrate` rewrites your own pages for template API changes (`--dry-run` to only show them, `--yes` to skip the prompt). `add dashboard-01` or `add dashboard-02` also makes the dashboard the default layout and builds its sidebar links from your pages. `remove` deletes a layout block's file from `Components/Layout/` and lists the files that still use it, such as `Routes.razor`. ## Generated files