diff --git a/.gitattributes b/.gitattributes index 1ff0c42..ef82812 100644 --- a/.gitattributes +++ b/.gitattributes @@ -2,6 +2,7 @@ # Set default behavior to automatically normalize line endings. ############################################################################### * text=auto +*.sh text eol=lf ############################################################################### # Set default behavior for command prompt diff. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 823d79b..fa558cb 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -20,11 +20,28 @@ jobs: steps: - uses: actions/checkout@v4 + - name: Extract version from tag + id: version + run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT + + - name: Extract release notes for this version + run: bash scripts/extract-release-notes.sh "${{ steps.version.outputs.VERSION }}" > "$RUNNER_TEMP/release-body.md" + - name: Setup .NET uses: actions/setup-dotnet@v4 with: dotnet-version: '10.0.x' + - name: Check package version matches tag + run: | + for proj in src/ShellUI.CLI/ShellUI.CLI.csproj src/ShellUI.Components/ShellUI.Components.csproj; do + v=$(dotnet msbuild "$proj" -getProperty:Version) + if [ "$v" != "${{ steps.version.outputs.VERSION }}" ]; then + echo "::error::$proj builds version $v but the tag is v${{ steps.version.outputs.VERSION }}. Update Directory.Build.props." + exit 1 + fi + done + - name: Cache NuGet packages uses: actions/cache@v4 with: @@ -72,15 +89,11 @@ jobs: dotnet nuget push src/ShellUI.Components/bin/Release/*.snupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate fi - - name: Extract version from tag - id: version - run: echo "VERSION=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT - - name: Create GitHub Release uses: softprops/action-gh-release@v2 with: name: ShellUI v${{ steps.version.outputs.VERSION }} - body_path: docs/RELEASE_NOTES.md + body_path: ${{ runner.temp }}/release-body.md draft: false prerelease: ${{ contains(github.ref, '-') }} files: | diff --git a/Directory.Build.props b/Directory.Build.props index 9a0221f..d37bcbd 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -2,8 +2,8 @@ - 0.4.0 - alpha.1 + 0.3.0 + rc.2 diff --git a/NET10/BlazorInteractiveServer/Components/UI/RadarChart.razor b/NET10/BlazorInteractiveServer/Components/UI/RadarChart.razor index cd474e4..a62d761 100644 --- a/NET10/BlazorInteractiveServer/Components/UI/RadarChart.razor +++ b/NET10/BlazorInteractiveServer/Components/UI/RadarChart.razor @@ -23,4 +23,15 @@ [Parameter] public string Name { get; set; } = "Data"; [Parameter] public Func? XValue { get; set; } [Parameter] public Func? YValue { get; set; } + + protected override void OnParametersSet() + { + base.OnParametersSet(); + // Radar tooltips only trigger per point, not in shared mode. + if (ChartOptions.Tooltip != null) + { + ChartOptions.Tooltip.Shared = false; + ChartOptions.Tooltip.Intersect = true; + } + } } diff --git a/NET10/BlazorInteractiveServer/Components/UI/Variants/ChartVariants.cs b/NET10/BlazorInteractiveServer/Components/UI/Variants/ChartVariants.cs index 73d3abb..730b7ef 100644 --- a/NET10/BlazorInteractiveServer/Components/UI/Variants/ChartVariants.cs +++ b/NET10/BlazorInteractiveServer/Components/UI/Variants/ChartVariants.cs @@ -133,10 +133,11 @@ public static ApexCharts.ApexChartOptions GetOptions(ChartTheme th // Resolve x-axis label from the first source that has a real string. // ApexCharts stashes category names in different globals depending on axis type. function xLabelAt(i) { - const cats = (w.globals.categoryLabels && w.globals.categoryLabels.length ? w.globals.categoryLabels - : (w.config.xaxis && w.config.xaxis.categories) || w.globals.labels || []); - const v = cats[i]; - return v !== undefined && v !== null ? String(v) : ''; + const sources = [w.globals.categoryLabels, w.config.xaxis && w.config.xaxis.categories, w.globals.labels]; + for (const s of sources) { + if (s && s[i] !== undefined && s[i] !== null && s[i] !== '') return String(s[i]); + } + return ''; } let html = '
'; diff --git a/README.md b/README.md index fe096d3..240a708 100644 --- a/README.md +++ b/README.md @@ -24,26 +24,25 @@ | Channel | Version | Notes | |---|---|---| -| Repository source | `0.4.0-alpha.1` | Current source; targets .NET 10 and Tailwind CSS `4.3.2` | -| Latest published stable packages | `0.2.1` | Stable CLI and components packages on NuGet | -| Latest published prerelease packages | `0.3.0-rc.1` | Published release candidate; older than this source checkout | +| Latest prerelease (recommended) | `0.3.0-rc.2` | .NET 10, Tailwind CSS `4.3.2` | +| Latest stable | `0.2.1` | Older release; superseded once `0.3.0` ships | -The repository is ahead of NuGet. Features described as **current source** require a local build or package and are not present in the published `0.2.1` or `0.3.0-rc.1` packages. The published prerelease targets .NET 9; the current source targets .NET 10. +Prereleases are not picked up by a plain install, so pass `--version 0.3.0-rc.2` explicitly. Projects still on .NET 9 can use `0.3.0-rc.1`, the last release that targets .NET 9. -ShellUI is alpha software. Validate it in your target Blazor and hosting environments before relying on it. +ShellUI is prerelease software. Validate it in your target Blazor and hosting environments before relying on it. -## Current source capabilities +## Capabilities - The CLI commands are `init`, `add`, `list`, `remove`, and `update`, plus `theme init`, `theme apply`, and `theme update`. -- The component registry has **173 entries**: **73 direct install targets** and **100 hidden dependency entries**. `list` shows direct targets; `add` resolves hidden dependencies. -- Current additions include `typed-select`, `command-palette`, `data-picker`, `multi-select`, and `tag-input`. +- The component registry has **176 entries**: **76 direct install targets** and **100 hidden dependency entries**. `list` shows direct targets; `add` resolves hidden dependencies. +- `0.3.0-rc.2` adds `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`. - The repository and demo have migrated to .NET 10. The demo is `NET10/BlazorInteractiveServer`. ## Requirements -- .NET 10 SDK for the current source +- .NET 10 SDK - A .NET 10 Blazor project - Tailwind CSS `4.3.2` via either: - the standalone CLI, which does not require Node.js; or @@ -54,25 +53,19 @@ ShellUI is alpha software. Validate it in your target Blazor and hosting environ The published global tool is named `shellui`: ```bash -dotnet tool install --global ShellUI.CLI --version 0.2.1 +dotnet tool install --global ShellUI.CLI --version 0.3.0-rc.2 shellui --help ``` -To select the published prerelease instead: - -```bash -dotnet tool install --global ShellUI.CLI --version 0.3.0-rc.1 -``` - A local .NET tool is invoked as `dotnet shellui`: ```bash dotnet new tool-manifest -dotnet tool install --local ShellUI.CLI --version 0.3.0-rc.1 +dotnet tool install --local ShellUI.CLI --version 0.3.0-rc.2 dotnet shellui --help ``` -After building or installing the current source tool, its workflow is: +The workflow is: ```bash shellui init @@ -99,29 +92,21 @@ New CLI sidebar installs use the host-loaded `shellui.js`; the legacy `sidebar-j | `theme apply ` | Apply a theme to `wwwroot/input.css` or emit override CSS | | `theme update` | Re-fetch the source recorded in `shellui.theme.lock` | -The five current source targets can be installed together: +The targets added in `0.3.0-rc.2` can be installed together: ```bash -shellui add typed-select command-palette data-picker multi-select tag-input +shellui add typed-select command-palette data-picker multi-select tag-input donut-chart radar-chart radial-chart ``` ## Components package -Published versions can be installed explicitly: - -```bash -dotnet add package ShellUI.Components --version 0.2.1 -``` - -To select the published prerelease instead: - ```bash -dotnet add package ShellUI.Components --version 0.3.0-rc.1 --prerelease +dotnet add package ShellUI.Components --version 0.3.0-rc.2 ``` -`0.4.0-alpha.1` is not currently published. To consume that source version, pack `src/ShellUI.Components/ShellUI.Components.csproj` and use it from a local package feed. `ShellUI.Core` and `ShellUI.Templates` are internal projects and must not be installed by consumers. +`ShellUI.Core` and `ShellUI.Templates` are internal projects and must not be installed by consumers. -The current-source package supports two CSS workflows. +The package supports two CSS workflows. ### Precompiled bundle @@ -135,7 +120,7 @@ Release packaging generates `shellui-all.css`, so the consuming project does not @using ShellUI.Components ``` -The generated bundle is not checked into the repository. Before packing the current source locally, run `bash scripts/rebuild-precompiled-css.sh`; the release pipeline runs the same script automatically. +The generated bundle is not checked into the repository. Before packing locally, run `bash scripts/rebuild-precompiled-css.sh`; the release pipeline runs the same script automatically. ### Tailwind safelist @@ -150,7 +135,7 @@ The safelist lets Tailwind emit the classes used by ShellUI components even when ## Theme commands -The current-source CLI can fetch public themes from [tweakcn](https://tweakcn.com): +The CLI can fetch public themes from [tweakcn](https://tweakcn.com): ```bash shellui theme init https://tweakcn.com/themes/THEME_ID @@ -177,7 +162,7 @@ The .NET 10 Blazor Interactive Server demo is outside that solution: dotnet run --project NET10/BlazorInteractiveServer/BlazorInteractiveServer.csproj ``` -`Directory.Build.props` is the source of the centralized version, currently `0.4.0-alpha.1`. Only `ShellUI.CLI` and `ShellUI.Components` are packable; `ShellUI.Core`, `ShellUI.Templates`, the test project, and the safelist generator are not published packages. +`Directory.Build.props` holds the single version used by every project. Only `ShellUI.CLI` and `ShellUI.Components` are packable; `ShellUI.Core`, `ShellUI.Templates`, the test project, and the safelist generator are not published packages. ShellUI uses semantic Blazor and Tailwind patterns, but accessibility depends on the component, configuration, and host application. Test keyboard use, focus behavior, contrast, and assistive-technology output in the consuming application. @@ -189,7 +174,7 @@ ShellUI uses semantic Blazor and Tailwind patterns, but accessibility depends on - [Contributing](docs/CONTRIBUTING.md) - [Release notes](docs/RELEASE_NOTES.md) -Release notes contain historical release records plus a separate current-source section for `0.4.0-alpha.1`; older version sections describe only the release they document. +Each section of the release notes describes only the release it is named after. ## License diff --git a/SHELLUI-FIXES.md b/SHELLUI-FIXES.md new file mode 100644 index 0000000..c9d305a --- /dev/null +++ b/SHELLUI-FIXES.md @@ -0,0 +1,32 @@ +# ShellUI fixes + +Problems hit while adding ShellUI 0.3.0-rc.1 components to `src/FDMS.UI` and how each was handled. The fixes now live in the current `0.4.0-alpha.1` source templates; they are not all present in the published `0.3.0-rc.1` package. The legacy `sidebar-js` module remains only for projects that still contain an old generated provider. + +## Edits to generated components + +1. `Tabs.razor` **does not compile.** The template emits `private string _effectiveValue = ";` (an unterminated string). Fixed to `= "";`. +2. `Select.razor` **depends on an icon font nothing loads.** It draws the chevron with `expand_more`, which needs the Material Symbols font, so without it the arrow would render as the plain text "expand_more". Replaced with an inline SVG chevron. +3. `SidebarProvider.razor` **never detects mobile.** The old template imported `./shellui-sidebar.js`, which resolves against the page URL and fails when the component is compiled into a Razor class library. New CLI installs use the host-loaded `shellui.js` and call `ShellUI.initSidebar`; no library-specific path is required. The legacy `shellui-sidebar.js` module remains available only for projects that still use the old generated provider. +4. `SidebarInset.razor` **lets wide content push the page sideways.** The `
` is a flex child without `min-w-0`, so a wide table stretches it past the viewport instead of scrolling inside its own container. Added `min-w-0`. +5. `Skeleton.razor` **uses `ClassName` while the component API and demo use `Class`.** Calls such as `` therefore pass `Class` through unmatched attributes instead of merging it with the skeleton classes, which can remove the pulse/background styling. The component now exposes `Class`, retains `ClassName` for compatibility, and renders `ChildContent` like the ShellUI demo. + + + +## Customised from the dashboard-02 template + +- `Components/Layout/DashboardLayout02.razor`: breadcrumb labels, redirect to the account page while a password change is pending, `min-w-0` on the content area. +- `Components/UI/AppSidebar.razor`: FDMS navigation, admin-only Users link, account and sign-out entries. + + + +## Things to know when using it + +- **Class overrides do not merge.** `Shell.Cn` joins class strings and does not resolve conflicts like tailwind-merge does. Passing `Class="max-w-2xl"` to something that already sets `max-w-lg` or `sm:max-w-sm` is a coin toss. Use the important modifier, for example `sm:max-w-2xl!` (see `InvoiceDetailSheet.razor`). +- **Styles and scripts come from the library.** `FDMS.UI` builds `wwwroot/app.css` with the Tailwind CLI (`Build/ShellUI.targets`, needs Node). Hosts must reference `_content/FDMS.UI/app.css` and `_content/FDMS.UI/shellui.js` and must not copy the CSS into their own `wwwroot`. +- **Tailwind only scans** `FDMS.UI` **by default.** Classes used in a host's own markup (for example `FDMS.Web/Components`) are not generated unless the host is listed with `@source` in `wwwroot/input.css`. +- **Theme flash.** `ThemeToggle` assumes dark when nothing is stored, and it only touches the `dark` class after the first render. The host needs the small inline script in `FDMS.Web/Components/App.razor` that sets a default and adds `dark` before Blazor starts. +- **No prerender with browser storage.** The signed-in session lives in browser storage, so `FDMS.Web` renders `Routes` and `HeadOutlet` with `prerender: false`. `ThemeToggle` and `SidebarProvider` also need JS interop and skip it during prerender. +- `data-table` pulls in `System.Linq.Dynamic.Core`. It filters and sorts by property name, so columns need a real `PropertyName`. +- **Icons.** The `ShellIcons.Blazor` package (Lucide names, for example ``) is used for icons rather than inline SVGs. +- **Run the CLI from** `src/FDMS.UI`, next to `shellui.json`. + diff --git a/ShellUI.Tests/ClassParameterTests.cs b/ShellUI.Tests/ClassParameterTests.cs new file mode 100644 index 0000000..784a9e3 --- /dev/null +++ b/ShellUI.Tests/ClassParameterTests.cs @@ -0,0 +1,58 @@ +using System.IO; +using System.Linq; +using System.Runtime.CompilerServices; +using System.Text.RegularExpressions; +using ShellUI.Templates; +using Xunit; + +namespace ShellUI.Tests; + +public class ClassParameterTests +{ + private static readonly Regex DeclaresClassName = new(@"public string\?? ClassName\b"); + private static readonly Regex DeclaresClass = new(@"public string\? Class \{"); + private static readonly Regex RendersClass = new(@"@Class\b|[,+]\s*Class\)"); + + [Fact] + public void EveryTemplateWithClassName_AlsoAcceptsAndRendersClass() + { + var offenders = new List(); + foreach (var (name, _) in ComponentRegistry.Components) + { + var content = ComponentRegistry.GetComponentContent(name); + if (content is null || !DeclaresClassName.IsMatch(content)) continue; + + if (!DeclaresClass.IsMatch(content)) offenders.Add($"{name}: no `Class` parameter"); + else if (!RendersClass.IsMatch(content)) offenders.Add($"{name}: `Class` declared but never rendered"); + } + + Assert.True(offenders.Count == 0, + "Templates that expose ClassName must also accept and render Class:\n " + + string.Join("\n ", offenders)); + } + + [Fact] + public void EveryPackageComponentWithClassName_AlsoAcceptsAndRendersClass() + { + var offenders = new List(); + foreach (var path in Directory.GetFiles(GetComponentsDirectory(), "*.razor")) + { + var content = File.ReadAllText(path); + if (!DeclaresClassName.IsMatch(content)) continue; + + var file = Path.GetFileName(path); + if (!DeclaresClass.IsMatch(content)) offenders.Add($"{file}: no `Class` parameter"); + else if (!RendersClass.IsMatch(content)) offenders.Add($"{file}: `Class` declared but never rendered"); + } + + Assert.True(offenders.Count == 0, + "Package components that expose ClassName must also accept and render Class:\n " + + string.Join("\n ", offenders)); + } + + private static string GetComponentsDirectory([CallerFilePath] string thisFile = "") + { + var testDir = Path.GetDirectoryName(thisFile) ?? throw new InvalidOperationException("CallerFilePath is empty"); + return Path.GetFullPath(Path.Combine(testDir, "..", "src", "ShellUI.Components", "Components")); + } +} diff --git a/ShellUI.Tests/NuGetDepsAndSuggestionsTests.cs b/ShellUI.Tests/NuGetDepsAndSuggestionsTests.cs index e97891f..db68bcb 100644 --- a/ShellUI.Tests/NuGetDepsAndSuggestionsTests.cs +++ b/ShellUI.Tests/NuGetDepsAndSuggestionsTests.cs @@ -71,6 +71,9 @@ public void Chart_DeclaresBlazorApexCharts() [Theory] [InlineData("pie-chart")] + [InlineData("donut-chart")] + [InlineData("radar-chart")] + [InlineData("radial-chart")] [InlineData("bar-chart")] [InlineData("area-chart")] [InlineData("line-chart")] diff --git a/ShellUI.Tests/TemplateSyncTests.cs b/ShellUI.Tests/TemplateSyncTests.cs index ad466f1..1467234 100644 --- a/ShellUI.Tests/TemplateSyncTests.cs +++ b/ShellUI.Tests/TemplateSyncTests.cs @@ -32,6 +32,9 @@ public class TemplateSyncTests [InlineData("multi-select", "MultiSelect.razor")] [InlineData("tag-input", "TagInput.razor")] [InlineData("command-palette", "CommandPalette.razor")] + [InlineData("donut-chart", "DonutChart.razor")] + [InlineData("radar-chart", "RadarChart.razor")] + [InlineData("radial-chart", "RadialChart.razor")] public void TemplateCodeBlock_MatchesLiveLibrary(string templateName, string razorFileName) { if (AllowedDrift.ContainsKey(templateName)) return; @@ -55,6 +58,19 @@ public void TemplateCodeBlock_MatchesLiveLibrary(string templateName, string raz DiffSummary(normalizedLive, normalizedTemplate)); } + [Fact] + public void ChartVariantsTemplate_MatchesLiveLibrary() + { + var livePath = Path.Combine(Path.GetDirectoryName(GetLiveRazorPath("Chart.razor"))!, "..", "Variants", "ChartVariants.cs"); + var template = ComponentRegistry.GetComponentContent("chart-variants") + ?? throw new InvalidOperationException("Template 'chart-variants' not found in registry"); + + var live = Normalize(File.ReadAllText(livePath)); + var generated = Normalize(template.Replace("namespace YourProjectNamespace.Components.UI.Variants;", "namespace ShellUI.Components;")); + + Assert.True(live == generated, "Drift detected between live ChartVariants.cs and template chart-variants.\n\n" + DiffSummary(live, generated)); + } + // [CallerFilePath] captures the absolute path of this source file at compile time, // so the test resolves the live components directory regardless of cwd on CI. private static string GetLiveRazorPath(string razorFileName, [CallerFilePath] string thisFile = "") diff --git a/VERSIONING_STRATEGY.md b/VERSIONING_STRATEGY.md index 19b1b56..39259a2 100644 --- a/VERSIONING_STRATEGY.md +++ b/VERSIONING_STRATEGY.md @@ -1,20 +1,16 @@ # ShellUI Versioning Strategy -## Current Version and Publication Boundary +## Current Version ShellUI uses one centralized version for the source templates, CLI tool, and packable runtime components. -| Scope | Current fact | +| Scope | Value | |---|---| -| Current source | `0.4.0-alpha.1` | -| Base version in `Directory.Build.props` | `0.4.0` | -| Prerelease suffix | `alpha.1` | -| Current target framework | .NET 10 | -| Current Tailwind version | `4.3.2` | -| Latest tag present in this checkout | `v0.3.0-rc.1` (historical) | -| Published package status | Not implied by the current source version; verify the package channel and pin an explicit version | +| Version | `0.3.0-rc.2` | +| Target framework | .NET 10 | +| Tailwind version | `4.3.2` | -`0.4.0-alpha.1` describes this checkout. It must not be described as a published NuGet or GitHub release unless a matching release has actually been published. The historical `v0.3.0-rc.1` tag is retained as release history, not as the current source version. The published prerelease targets .NET 9; the current source targets .NET 10. +`0.3.0-rc.1` was the last release targeting .NET 9. ## Single Source of Truth @@ -22,15 +18,15 @@ The root `Directory.Build.props` supplies the version: ```xml - 0.4.0 - alpha.1 + 0.3.0 + rc.2 ``` `Directory.Build.props` composes the package and assembly metadata: -- `Version` becomes `0.4.0-alpha.1` when a suffix is present. -- `AssemblyVersion` and `FileVersion` use the numeric base `0.4.0`. +- `Version` becomes `0.3.0-rc.2` when a suffix is present. +- `AssemblyVersion` and `FileVersion` use the numeric base `0.3.0`. - `InformationalVersion` includes the prerelease suffix. - Component metadata reads the centralized properties when running from the repository. `VersionHelper` uses assembly metadata as a fallback when its repository search does not find the solution file. @@ -61,7 +57,7 @@ The CLI writes the computed version into `shellui.json` for each installed entry "InstalledComponents": [ { "Name": "button", - "Version": "0.4.0-alpha.1", + "Version": "0.3.0-rc.2", "InstalledAt": "2026-01-01T00:00:00Z", "IsCustomized": false } @@ -85,7 +81,7 @@ dotnet tool install -g ShellUI.CLI --version dotnet tool update -g ShellUI.CLI --version ``` -A local tool manifest can pin the same version for a team. The current source version is not automatically selected by an unversioned global install. +A local tool manifest can pin the same version for a team. An unversioned install only selects stable releases, never a prerelease. ### Published Components package @@ -95,32 +91,29 @@ A local tool manifest can pin the same version for a team. The current source ve dotnet add package ShellUI.Components --version --prerelease ``` -Do not add `ShellUI.Core` or `ShellUI.Templates` to a consumer project. They are internal implementation projects in the current source. +Do not add `ShellUI.Core` or `ShellUI.Templates` to a consumer project. They are internal implementation projects. -### Current source checkout +### Local checkout -To test the checkout itself, pack the solution and install the locally produced CLI package: +To test a checkout, pack the solution and install the locally produced CLI package with the version from `Directory.Build.props`: ```bash dotnet pack ShellUI.slnx --configuration Release -dotnet tool install -g ShellUI.CLI --add-source "./src/ShellUI.CLI/bin/Release" --version 0.4.0-alpha.1 +dotnet tool install -g ShellUI.CLI --add-source "./src/ShellUI.CLI/bin/Release" --version ``` -This local package is a build artifact, not evidence of publication to NuGet. +### Tags -### Source tags and documentation +Release tags use the `v` prefix, for example `v0.3.0-rc.2`. Pushing a `v*` tag runs the release workflow, which publishes to NuGet and creates the GitHub release. [RELEASE_NOTES.md](docs/RELEASE_NOTES.md) has one section per release. -Release tags use the `v` prefix, for example `v0.4.0-alpha.1`. A tag is a source-control reference; publication is performed separately by the release workflow. Current documentation describes the checkout, while [RELEASE_NOTES.md](docs/RELEASE_NOTES.md) preserves historical release records. There are no versioned documentation directories in this repository to maintain. +## Release Workflow -## Version Update Workflow +1. In a pull request, edit `ShellUIVersion` and `ShellUIVersionSuffix` in `Directory.Build.props` and add a `# ShellUI v` section to `docs/RELEASE_NOTES.md`. +2. Regenerate the precompiled CSS and safelist when the change affects component CSS. +3. Merge, then on an up-to-date `main` run `pwsh ./prepare-release.ps1 -Version -Suffix -DryRun` (builds, tests and checks the notes section). +4. Tag the merged commit and push the tag: `git tag v` then `git push origin v`. -For a maintainer changing the version: - -1. Edit `ShellUIVersion` and `ShellUIVersionSuffix` in `Directory.Build.props`. -2. Run the repository build and tests against `ShellUI.slnx`. -3. Regenerate the precompiled CSS and safelist when the change affects component CSS. -4. Pack the solution and verify that only the CLI and Components packages are produced. -5. Create a matching `v` tag and let the release workflow publish the packable artifacts. +The release workflow fails before publishing when the tag does not match the version in `Directory.Build.props` or when the notes section is missing. NuGet versions cannot be deleted, only unlisted, so the version must be merged before tagging. The verification commands are: @@ -149,7 +142,7 @@ ShellUI versions use: MAJOR.MINOR.PATCH[-PRERELEASE] ``` -Examples in the current version line are `0.4.0-alpha.1` and a numeric `0.4.0` value only if the suffix is removed for a stable release. The suffix communicates prerelease status; it is not a component-specific version. +For example, `0.3.0-rc.2` is a prerelease and `0.3.0` is the stable release with the suffix removed. The suffix communicates prerelease status; it is not a component-specific version. - Increase the major version for a deliberate breaking version boundary. - Increase the minor version for compatible feature work within the current version line. @@ -166,10 +159,6 @@ The unified version applies to the source system and the two packable artifacts. - 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. - Theme lock files track theme sources, not package versions. -## Historical Release Information - -The [historical release notes](docs/RELEASE_NOTES.md) contain older release headings, fixes, and install examples. They are preserved as history and should be read with the version they describe. They do not override the current source facts in this document. - ## Summary -The current source is `0.4.0-alpha.1`, centralized in `Directory.Build.props`, targeting .NET 10 and Tailwind CSS `4.3.2`. `ShellUI.CLI` and `ShellUI.Components` are the only packable artifacts. Published versions must be selected explicitly; the source version and the latest historical tag are not interchangeable. +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. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 110f031..6784220 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,17 +1,17 @@ # ShellUI Architecture -This document describes the current ShellUI source tree. The current source version is `0.4.0-alpha.1`; source version, local build output, and published package availability are separate concerns. +This document describes the ShellUI source tree. ## Current Baseline | Area | Current value | |---|---| -| Source version | `0.4.0-alpha.1` | +| Version | See `Directory.Build.props` | | Target framework | .NET 10 (`net10.0`) | | Tailwind CSS | `4.3.2` | | Solution | `ShellUI.slnx` | | Solution projects | 6 | -| Registry | 173 entries: 73 direct targets and 100 hidden dependency entries | +| Registry | 176 entries: 76 direct targets and 100 hidden dependency entries | ShellUI is a CLI-first Blazor component library. The CLI copies source into a consumer project, while `ShellUI.Components` is an independent Razor class library (RCL) for consumers who prefer NuGet. @@ -89,13 +89,13 @@ The implemented command tree is: ## Registry Model and Counts -`ComponentRegistry` contains 173 metadata entries: +`ComponentRegistry` contains 176 metadata entries: | Registry classification | Count | Meaning | |---|---:|---| -| Direct targets | 73 | Entries with `IsAvailable = true`; these are the normal targets shown by `shellui list`. | +| Direct targets | 76 | Entries with `IsAvailable = true`; these are the normal targets shown by `shellui list`. | | Hidden entries | 100 | Entries with `IsAvailable = false`; these are generally installed through a parent target. | -| **Total** | **173** | All registered templates, sub-components, variants, models, services, and assets. | +| **Total** | **176** | All registered templates, sub-components, variants, models, services, and assets. | A dependency entry is still real source and is written to the consumer project when the dependency walk reaches it. The two counts describe registry visibility, not two different component libraries. diff --git a/docs/CLI_INSTALLATION.md b/docs/CLI_INSTALLATION.md index 458b023..0883d51 100644 --- a/docs/CLI_INSTALLATION.md +++ b/docs/CLI_INSTALLATION.md @@ -1,50 +1,37 @@ # ShellUI CLI Installation -This guide covers the current source and the packages that are currently published. - ## Version guide | Context | Version | |---|---| -| Current source | `0.4.0-alpha.1`, targeting .NET 10 | -| Published stable package | `0.2.1` | -| Published prerelease package | `0.3.0-rc.1` | -| Tailwind used by current source | `4.3.2` | +| Latest prerelease (recommended) | `0.3.0-rc.2`, needs the .NET 10 runtime | +| Latest stable | `0.2.1` | +| Tailwind | `4.3.2` | -The current source is not available as a `0.4.0-alpha.1` NuGet tool. A plain tool install resolves the published stable `0.2.1`; the prerelease must be selected explicitly. The published `0.3.0-rc.1` tool targets .NET 9, while the current source targets .NET 10. +A plain tool install only selects stable releases, so pass `--version` for the prerelease. `0.3.0-rc.1` was the last release targeting .NET 9. ## Global installation A global tool is available as `shellui`: ```bash -dotnet tool install -g ShellUI.CLI -shellui --version -``` - -To pin the published stable version: - -```bash -dotnet tool install -g ShellUI.CLI --version 0.2.1 +dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.2 shellui --version ``` -To install the published prerelease: +If a global tool is already installed, update it to the same version: ```bash -dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.1 --prerelease -shellui --version +dotnet tool update -g ShellUI.CLI --version 0.3.0-rc.2 ``` -If a global tool is already installed, use `dotnet tool update -g ShellUI.CLI` for the stable channel or specify the published prerelease version with `--version 0.3.0-rc.1 --prerelease`. - ## Local installation A local tool is recorded in the repository and invoked as `dotnet shellui` after the manifest exists. ```bash dotnet new tool-manifest -dotnet tool install ShellUI.CLI --version 0.2.1 +dotnet tool install ShellUI.CLI --version 0.3.0-rc.2 dotnet shellui --version ``` @@ -56,14 +43,14 @@ The manifest is `.config/dotnet-tools.json` and uses the installed package versi "isRoot": true, "tools": { "shellui.cli": { - "version": "0.2.1", + "version": "0.3.0-rc.2", "commands": ["shellui"] } } } ``` -To select the prerelease for a local tool, install `ShellUI.CLI` with `--version 0.3.0-rc.1 --prerelease` and commit the resulting manifest. Commit the manifest so every developer and CI job uses the same tool version. +Commit the manifest so every developer and CI job uses the same tool version. ## Global or local? @@ -75,9 +62,9 @@ To select the prerelease for a local tool, install `ShellUI.CLI` with `--version | CI setup | Install the tool in each job | `dotnet tool restore` | | Best fit | Personal projects and quick trials | Teams and reproducible builds | -## Working with the current source +## Building from source -The repository source is `0.4.0-alpha.1` and targets `net10.0`. Build it from the repository with the .NET 10 SDK: +The repository targets `net10.0`. Build it with the .NET 10 SDK: ```bash dotnet --version @@ -89,10 +76,10 @@ To install the source build as a local tool package, generate the precompiled bu ```bash bash scripts/rebuild-precompiled-css.sh dotnet pack ShellUI.slnx --configuration Release -dotnet tool install -g ShellUI.CLI --add-source "./src/ShellUI.CLI/bin/Release" --version 0.4.0-alpha.1 +dotnet tool install -g ShellUI.CLI --add-source "./src/ShellUI.CLI/bin/Release" --version ``` -Do not use `0.4.0-alpha.1` as a NuGet package version until it is published. The published `0.2.1` and `0.3.0-rc.1` packages are separate installations. +Use the version from `Directory.Build.props`. ## Updating and removing tools @@ -127,7 +114,7 @@ jobs: - uses: actions/setup-dotnet@v4 with: dotnet-version: 10.0.x - - run: dotnet tool install -g ShellUI.CLI --version 0.2.1 + - run: dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.2 - run: dotnet new blazor -n App - working-directory: App run: shellui init --yes --tailwind standalone @@ -194,7 +181,7 @@ dotnet tool list -g shellui --version ``` -A plain install selects stable `0.2.1`. Use an explicit `--version 0.3.0-rc.1 --prerelease` when the published prerelease is required. +A plain install selects the latest stable release (`0.2.1`). Pass `--version 0.3.0-rc.2` for the prerelease. ## Related documentation diff --git a/docs/CLI_SYNTAX.md b/docs/CLI_SYNTAX.md index 2a2aa25..75ac3ed 100644 --- a/docs/CLI_SYNTAX.md +++ b/docs/CLI_SYNTAX.md @@ -1,6 +1,6 @@ # ShellUI CLI Syntax -This reference follows the current source: `0.4.0-alpha.1`, `net10.0`, Tailwind CSS `4.3.2`, and 73 direct component targets. The current source is not a published package. The published CLI versions are stable `0.2.1` and prerelease `0.3.0-rc.1`; their command surface may differ from the source described here. +This reference covers CLI `0.3.0-rc.2`: `net10.0`, Tailwind CSS `4.3.2`, and 76 direct component targets. Older versions, including the stable `0.2.1`, lack some of these commands. ## Command prefix @@ -78,7 +78,7 @@ shellui add button --force ## `list` -Lists the direct targets in the current source and their installation status. +Lists the direct targets and their installation status. ```bash shellui list @@ -86,7 +86,7 @@ shellui list --installed shellui list --available ``` -The current source has 73 direct targets. Registry entries used only as dependencies are not counted as direct targets. Choose either `--installed` or `--available` to filter the output. +There are 76 direct targets. Registry entries used only as dependencies are not counted as direct targets. Choose either `--installed` or `--available` to filter the output. ## `remove` @@ -205,7 +205,7 @@ Representative fields look like this: "InstalledComponents": [ { "Name": "button", - "Version": "0.4.0-alpha.1", + "Version": "0.3.0-rc.2", "InstalledAt": "2026-01-01T00:00:00Z", "IsCustomized": false } @@ -214,7 +214,7 @@ Representative fields look like this: } ``` -`ProjectType` is serialized as the enum value; `1` is `BlazorServer` in the current source. `IsCustomized` is metadata, not a merge mechanism. `update` still overwrites the file. +`ProjectType` is serialized as the enum value; `1` is `BlazorServer`. `IsCustomized` is metadata, not a merge mechanism. `update` still overwrites the file. ## Common workflow diff --git a/docs/COMPARISON.md b/docs/COMPARISON.md index 24eb660..6d42c2b 100644 --- a/docs/COMPARISON.md +++ b/docs/COMPARISON.md @@ -4,10 +4,9 @@ This is a qualitative comparison, not a benchmark report. Library features, pack ## Current ShellUI snapshot -- **Source version:** `0.4.0-alpha.1` - **Target framework:** .NET 10 - **Tailwind CSS:** `4.3.2` -- **CLI inventory:** 73 direct targets, 173 registry entries, and 100 hidden entries +- **CLI inventory:** 76 direct targets, 176 registry entries, and 100 hidden entries - **Distribution:** the CLI copies source into an application; the repository also contains the packable `ShellUI.Components` package - **Packaging boundary:** only `ShellUI.CLI` and `ShellUI.Components` are packable. `ShellUI.Core` and `ShellUI.Templates` are internal/non-packable projects. @@ -19,7 +18,7 @@ The direct-target count is the number users invoke with `shellui add`. It is not |---|---|---|---|---|---|---| | Distribution | CLI source-copy workflow; `ShellUI.Components` is packable | NuGet package | NuGet package | NuGet package | NuGet package | NuGet package | | CSS model | Tailwind CSS `4.3.2` | Material-oriented component styling | Project-specific component styling | Provider-based CSS options | Ant Design styling | Project-specific styling | -| Direct component count | 73 CLI targets; 173 registry entries; 100 hidden | Not audited here | Not audited here | Not audited here | Not audited here | Not audited here | +| Direct component count | 76 CLI targets; 176 registry entries; 100 hidden | Not audited here | Not audited here | Not audited here | Not audited here | Not audited here | | Source customization | Copied component source can be edited | Package/API customization | Package/API customization | Package/API customization | Package/API customization | Package/API customization | | 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 | @@ -36,11 +35,11 @@ The “not audited here” cells are intentional. They avoid presenting stale co ### Tailwind-first composition -ShellUI templates use Tailwind utility classes and CSS variables. The current source pins Tailwind CSS `4.3.2`; the generated Tailwind setup uses the v4 CSS entry point rather than the older v3 `@import` layer sequence. +ShellUI templates use Tailwind utility classes and CSS variables. ShellUI pins Tailwind CSS `4.3.2`; the generated Tailwind setup uses the v4 CSS entry point rather than the older v3 `@import` layer sequence. ### Registry-driven dependencies -`ComponentRegistry` is authoritative for the 73 direct targets, 100 hidden support entries, source dependencies, and NuGet dependencies. A component's visible sub-components or support files do not imply that it is a standalone package. +`ComponentRegistry` is authoritative for the 76 direct targets, 100 hidden support entries, source dependencies, and NuGet dependencies. A component's visible sub-components or support files do not imply that it is a standalone package. ### Compositional APIs @@ -97,7 +96,7 @@ The CLI's copy-based model can avoid installing unused component source, but it Community size is not a stable, comparable metric. Stars, forum activity, Discord membership, and commercial support change over time, and no current comparable dataset is maintained here. Check the official project repositories and support channels directly. -ShellUI is currently an alpha snapshot (`0.4.0-alpha.1`). Treat the current source as an actively changing implementation and validate the specific release or commit you plan to use. +ShellUI is prerelease software. Validate the specific release you plan to use. ## Migration considerations diff --git a/docs/COMPONENT_DEPENDENCIES.md b/docs/COMPONENT_DEPENDENCIES.md index 279e154..183f2d6 100644 --- a/docs/COMPONENT_DEPENDENCIES.md +++ b/docs/COMPONENT_DEPENDENCIES.md @@ -4,10 +4,10 @@ ## Registry snapshot -- **173** total registry entries -- **73** direct CLI targets (`IsAvailable = true`) +- **176** total registry entries +- **76** direct CLI targets (`IsAvailable = true`) - **100** hidden entries (`IsAvailable = false`) -- `shellui list` displays the 73 direct targets; hidden sub-components, variants, models, services, and support assets are omitted from the public list. +- `shellui list` displays the 76 direct targets; hidden sub-components, variants, models, services, and support assets are omitted from the public list. `Dependencies` contains registry-declared source/template dependencies. `NuGetDependencies` is separate and is used by the installer to add package references. A relationship visible in rendered markup is not automatically a registry dependency, so do not infer a dependency graph from component names or visual composition. @@ -39,6 +39,7 @@ The following table summarizes the non-empty `Dependencies` declared by the curr | `dashboard-02` | `sidebar`, `breadcrumb`, `separator`, `theme-toggle`, `app-sidebar` | — | | `data-table` | `data-table-models` | `System.Linq.Dynamic.Core` `1.7.1` | | `dialog` | `dialog-trigger`, `dialog-content`, `dialog-header`, `dialog-footer`, `dialog-title`, `dialog-description`, `dialog-close` | — | +| `donut-chart` | `chart` | — | | `drawer` | `drawer-variants`, `drawer-trigger`, `drawer-content` | — | | `empty-state` | `button` | — | | `file-upload` | `shellui-js` | — | @@ -49,6 +50,8 @@ The following table summarizes the non-empty `Dependencies` declared by the curr | `multi-series-chart` | `chart`, `chart-series` | — | | `navigation-menu` | `navigation-menu-item` | — | | `pie-chart` | `chart` | — | +| `radar-chart` | `chart` | — | +| `radial-chart` | `chart` | — | | `radio-group` | `radio-group-item` | — | | `sheet` | `sheet-variants`, `sheet-trigger`, `sheet-content` | — | | `sidebar` | `shell`, `sidebar-models`, `sidebar-provider`, `sidebar-header`, `sidebar-content`, `sidebar-footer`, `sidebar-group`, `sidebar-group-label`, `sidebar-group-content`, `sidebar-menu`, `sidebar-menu-item`, `sidebar-menu-button`, `sidebar-menu-sub`, `sidebar-menu-sub-item`, `sidebar-menu-sub-button`, `sidebar-menu-action`, `sidebar-menu-badge`, `sidebar-separator`, `sidebar-trigger`, `sidebar-inset`, `sidebar-rail` | — | diff --git a/docs/COMPONENT_ROADMAP.md b/docs/COMPONENT_ROADMAP.md index 839c4b5..d0096e2 100644 --- a/docs/COMPONENT_ROADMAP.md +++ b/docs/COMPONENT_ROADMAP.md @@ -2,19 +2,19 @@ **Goal:** Build the components and tooling needed for a Tailwind-first Blazor design system, including the foundations for ShellDocs. -**Current source:** `0.4.0-alpha.1` · .NET 10 · Tailwind CSS `4.3.2` +.NET 10 · Tailwind CSS `4.3.2` ## Current inventory -`ComponentRegistry` is the source of truth for component availability, names, and dependencies. The current registry contains **173 entries**: +`ComponentRegistry` is the source of truth for component availability, names, and dependencies. The current registry contains **176 entries**: -- **73 direct CLI targets** shown by `shellui list` +- **76 direct CLI targets** shown by `shellui list` - **100 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. -### Implemented direct targets (73) +### Implemented direct targets (76) The following categories describe the direct targets in the current registry, not a promise about future scope. @@ -23,7 +23,7 @@ The following categories describe the direct targets in the current registry, no - [x] **Feedback (9):** Alert, Callout, EmptyState, Loading, Progress, Skeleton, Sonner, Toast, Tooltip - [x] **Overlay (9):** AlertDialog, Command, CommandPalette, Dialog, Drawer, Dropdown, HoverCard, Popover, Sheet - [x] **Navigation (7):** ContextMenu, Menubar, NavigationMenu, Pagination, PrevNextNav, Stepper, Tabs -- [x] **Data Display (13):** AreaChart, Avatar, Badge, BarChart, Calendar, Carousel, Chart, ChartSeries, DataTable, LineChart, MultiSeriesChart, PieChart, Table +- [x] **Data Display (16):** AreaChart, Avatar, Badge, BarChart, Calendar, Carousel, Chart, ChartSeries, DataTable, DonutChart, LineChart, MultiSeriesChart, PieChart, RadarChart, RadialChart, Table - [x] **Utility (2):** CopyButton, ThemeToggle ### Implemented ShellDocs building blocks diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b9b766f..7b7d7cb 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to ShellUI -This guide applies to the current source version `0.4.0-alpha.1`, which targets .NET 10 and Tailwind CSS `4.3.2`. It describes the current contribution and verification workflow rather than a planned release process. +ShellUI targets .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). ## Contribution Policy @@ -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 the current source build when testing local 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`, `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 173 entries, including 73 direct targets and 100 hidden entries. +3. Preserve the distinction between direct targets and hidden dependency entries. The current registry has 176 entries, including 76 direct targets and 100 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. @@ -115,12 +115,12 @@ For a new command or option: Documentation in this repository should be verifiable against the checkout: -- Use `0.4.0-alpha.1` for the current source and identify published releases separately. +- Refer to `Directory.Build.props` for the version instead of repeating it; install commands may pin the latest release. - Use `ShellUI.slnx` and the six solution project paths; do not point contributors at paths that are not in the checkout. - Distinguish the demo at `NET10/BlazorInteractiveServer` from solution membership. - Use the actual CLI command names and current test packages. - Link only to files that exist in the repository. -- Treat `RELEASE_NOTES.md` as historical release information when it is referenced; do not rewrite historical entries to describe the current source. +- Add a `# ShellUI v` section to `RELEASE_NOTES.md` for each release; do not rewrite earlier sections. - Label unimplemented ideas as unscheduled proposals. Do not add dates, adoption targets, performance promises, or unsupported accessibility compliance claims. ## Style and Review Expectations diff --git a/docs/FAQ.md b/docs/FAQ.md index 8c88e24..622f7d1 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -6,15 +6,13 @@ Answers for the current ShellUI source and the currently published packages. ### Which version should I use? -The current source is `0.4.0-alpha.1`, targets `net10.0`, uses Tailwind CSS `4.3.2`, and exposes 73 direct component targets. - -The published packages are stable `0.2.1` and prerelease `0.3.0-rc.1`. A plain install selects stable `0.2.1`; select the prerelease explicitly: +Use `0.3.0-rc.2`. It targets `net10.0`, uses Tailwind CSS `4.3.2`, and exposes 76 direct component targets. A plain install selects the older stable `0.2.1`, so select the prerelease explicitly: ```bash -dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.1 --prerelease +dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.2 ``` -The current source is not a published `0.4.0-alpha.1` package. The command examples in this FAQ describe the current source; check the installed package's `--help` output when using a published tool. +Projects still on .NET 9 can use `0.3.0-rc.1`, the last release targeting .NET 9. ### Which command prefix should I use? @@ -51,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 73 direct targets. +Use the exact names printed by `shellui list`. Dependency-only entries are installed automatically and are not counted among the 76 direct targets. ### Which names should I use? @@ -89,7 +87,7 @@ shellui list --installed shellui list --available ``` -The current source has 73 direct targets. Use the command output as the authoritative name list. +There are 76 direct targets. Use the command output as the authoritative name list. ### What happens when I update a component? @@ -147,7 +145,7 @@ A representative Tailwind and component record is: "InstalledComponents": [ { "Name": "button", - "Version": "0.4.0-alpha.1", + "Version": "0.3.0-rc.2", "InstalledAt": "2026-01-01T00:00:00Z", "IsCustomized": false } @@ -235,14 +233,13 @@ For standalone mode, check `.shellui/bin/`. For npm mode, run `npm install`. ### How do I update the NuGet package? -Use the published package version explicitly when needed: +Pass the version explicitly: ```bash -dotnet add package ShellUI.Components --version 0.2.1 -dotnet add package ShellUI.Components --version 0.3.0-rc.1 --prerelease +dotnet add package ShellUI.Components --version 0.3.0-rc.2 ``` -Then restore and build the project. The current source version `0.4.0-alpha.1` should not be used as a package version until it is published. +Then restore and build the project. ### What license does ShellUI use? diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index 03bbafb..d99e34d 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -1,23 +1,19 @@ # ShellUI Project Status -## Current source: `0.4.0-alpha.1` - -This page reports the checked-out source. A source version is not automatically the same as a published NuGet package or GitHub release. +## Overview | Area | Current fact | |---|---| -| Source version | `0.4.0-alpha.1` from `Directory.Build.props` | +| Version | See `Directory.Build.props` | | Framework | .NET 10 (`net10.0`) | | Tailwind CSS | `4.3.2` | | Solution | `ShellUI.slnx` with six projects | | Demo | `NET10/BlazorInteractiveServer/BlazorInteractiveServer.csproj`, outside the solution | | Packable artifacts | `ShellUI.CLI` and `ShellUI.Components` only | -| Latest tag present in this checkout | `v0.3.0-rc.1`, historical | -| Published status | A matching `0.4.0-alpha.1` package is not implied by the source version; pin and verify the published channel explicitly. | -The distinction matters when installing tools. An unversioned global-tool install can select a different channel from the source checkout. Use an explicit version for published artifacts, or pack and install the current source locally. +An unversioned install only selects stable releases, so pin prereleases with `--version`. -## Implemented in the Current Source +## Implemented ### Solution and distribution @@ -46,9 +42,9 @@ theme update ### Registry and components -`ComponentRegistry` has 173 entries: +`ComponentRegistry` has 176 entries: -- 73 direct targets with `IsAvailable = true`. +- 76 direct targets with `IsAvailable = true`. - 100 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. @@ -71,10 +67,9 @@ CI restores `ShellUI.slnx`, regenerates the precompiled CSS bundle, builds the s ## Current Boundaries -- The source is alpha and its APIs, templates, and generated output may change. +- ShellUI is prerelease software and its APIs, templates, and generated output may change. - Only `ShellUI.CLI` and `ShellUI.Components` are packable in the current project configuration. - `ShellUI.Core` and `ShellUI.Templates` are internal; they are not consumer installation targets. -- A local `0.4.0-alpha.1` build is not proof that the version is published. - No stable release date, adoption target, or guaranteed delivery schedule is stated here. - The current test stack does not provide a browser or rendered-component test harness. @@ -126,18 +121,16 @@ dotnet tool install -g ShellUI.CLI --version dotnet add package ShellUI.Components --version --prerelease ``` -For the current checkout, build the CLI locally and install that package explicitly: +To test a checkout, build the CLI locally and install that package with the version from `Directory.Build.props`: ```bash dotnet pack ShellUI.slnx --configuration Release -dotnet tool install -g ShellUI.CLI --add-source "./src/ShellUI.CLI/bin/Release" --version 0.4.0-alpha.1 +dotnet tool install -g ShellUI.CLI --add-source "./src/ShellUI.CLI/bin/Release" --version ``` -The exact published version must be checked independently; a source build is not a publication channel. - ## Documentation and History -The [historical release notes](RELEASE_NOTES.md) preserve records for older releases. They are useful for understanding prior changes, but headings and version claims in that file do not describe the current `0.4.0-alpha.1` source by default. +The [release notes](RELEASE_NOTES.md) have one section per release. - [Project overview](../README.md) - [Architecture](ARCHITECTURE.md) diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index a69c46e..ad6d1f1 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -1,6 +1,6 @@ # ShellUI Quick Start -This quick start follows the current source: `0.4.0-alpha.1`, .NET 10, Tailwind CSS `4.3.2`, and 73 direct component targets. The source is not published as `0.4.0-alpha.1`; the published stable package is `0.2.1` and the published prerelease is `0.3.0-rc.1`. The published prerelease targets .NET 9; use the matching SDK/runtime when following a published package instead. +This quick start uses ShellUI `0.3.0-rc.2`: .NET 10, Tailwind CSS `4.3.2`, and 76 direct component targets. ## Prerequisites @@ -20,17 +20,11 @@ dotnet --version A global tool is invoked as `shellui`: ```bash -dotnet tool install -g ShellUI.CLI +dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.2 shellui --version ``` -The plain install selects the published stable `0.2.1`. To use the published prerelease, select it explicitly: - -```bash -dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.1 --prerelease -``` - -The workflow below follows the current source. Published `0.2.1` and `0.3.0-rc.1` tools are older packages and may not expose source-only commands; check `shellui --help` or build the current source when using the syntax in this guide. +A plain install without `--version` selects the older stable `0.2.1`, which lacks several commands in this guide. If the project has a .NET tool manifest, use `dotnet shellui` instead. See [CLI installation](CLI_INSTALLATION.md). @@ -42,7 +36,7 @@ cd MyBlazorApp shellui init --yes --tailwind standalone ``` -The current source detects the project type and sets up: +`init` detects the project type and sets up: - `Components/UI/` - `wwwroot/input.css` and `wwwroot/app.css` @@ -76,7 +70,7 @@ Dependencies are copied automatically. Use `--force` to overwrite an existing co shellui add button --force ``` -Use the exact names shown by `shellui list`. The current source exposes 73 direct targets; dependency-only registry entries are not direct targets. +Use the exact names shown by `shellui list`. There are 76 direct targets; dependency-only registry entries are not direct targets. ## Use a component @@ -144,7 +138,7 @@ shellui remove button card ## Apply a theme -The current source supports tweakcn themes: +The CLI supports tweakcn themes: ```bash shellui theme init --yes --tailwind standalone diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index 4e7e4ea..e0b25b6 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -1,36 +1,54 @@ # ShellUI Release Notes -> [!IMPORTANT] -> **Historical releases:** The `v0.3.0-rc.1` section and all older sections below are preserved as historical release records. They are not the current source snapshot. The current source baseline is `0.4.0-alpha.1`. +# ShellUI v0.3.0-rc.2 🚦 -## Unreleased / Current Source: `0.4.0-alpha.1` +> Second release candidate for v0.3.0. It moves ShellUI to .NET 10, adds new components, and fixes bugs found in real projects using rc.1. If nothing critical comes up during testing, v0.3.0 ships from this code with the suffix dropped. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues). -This section describes the current working source; it is not a published stable-release announcement. +## ⚠️ Breaking: .NET 10 required -### Current baseline +- `ShellUI.Components` now targets `net10.0` (rc.1 targeted `net9.0`). Projects on .NET 9 should stay on rc.1 until they upgrade. +- The `shellui` CLI tool needs the .NET 10 runtime to run. +- Tailwind CSS goes from `4.1.18` to `4.3.2`. -- Version: `0.4.0-alpha.1` -- Target framework: .NET 10 -- Tailwind CSS: `4.3.2` -- Component inventory: **73 direct CLI targets**, **173 registry entries**, and **100 hidden entries** -- Packaging: only `ShellUI.CLI` and `ShellUI.Components` are packable in the current project configuration. `ShellUI.Core` and `ShellUI.Templates` are internal/non-packable in this checkout; older release sections below record their historical publication state. +## ✨ New -### Current CLI surface +- **Components:** `command-palette`, `data-picker`, `multi-select`, `tag-input`, `typed-select` (#25, #27) +- **Charts:** new `donut-chart`, `radar-chart` and `radial-chart`, in both the CLI and the NuGet package. All charts are restyled to match shadcn (#26) +- **DataTable:** server-side mode via `DataTableRequest` / `DataTableResponse` (#27) +- **Sonner:** toast variants and per-toast duration (#27) +- **Themes:** `shellui theme init | apply | update` bake a [tweakcn](https://tweakcn.com) theme into `wwwroot/input.css` and record it in `shellui.theme.lock` (#23, #24) +- **NuGet package:** ships a precompiled `shellui-all.css` bundle and a Tailwind safelist, so it works without a Tailwind build step (#20, #22) -```text -shellui init -shellui add -shellui list -shellui remove -shellui update [components] -shellui theme init -shellui theme apply -shellui theme update +## 🐛 Fixes + +- `shellui add accordion` failed because `accordion-type` was not registered (#29) +- `Tabs` generated an unterminated string and did not compile (#29) +- `Select` and `FileUpload` showed icon names such as `expand_more` as text, because they relied on the Material Symbols font. Both now use inline SVG (#29) +- `DashboardLayout01` breadcrumb code did not compile (#29) +- `context-menu` referenced a `ContextMenuItem` model that was never installed (#29) +- `SidebarInset`: wide content no longer pushes the page sideways (#29) +- Sidebar mobile detection and Ctrl/Cmd+B now work when components are compiled into a Razor Class Library (#30) +- `Class` is now accepted by the 30 templates and 8 package components that only took `ClassName`. Before, `Class="..."` could drop a component's base styling. `ClassName` still works but is deprecated +- `shellui add` exits with 1 when any component, dependency or NuGet package fails. `init` fails loudly if its base files can't be written, and `update` records the new version in `shellui.json` (#30) +- Chart tooltips: pie, donut and radial tooltips showed empty rows, radar charts showed none, and bar/line tooltips lost their x-axis label. CLI-installed charts also used an outdated copy of the chart options (palette, animations, legend). The CLI templates now match the NuGet package +- Overlays close on dismiss, lock body scroll, and clean up asynchronously (#27) +- Stepper highlights the active step correctly + +## 📦 Installation + +```bash +# CLI (prerelease: the version is required) +dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.2 +# or upgrade an existing install +dotnet tool update -g ShellUI.CLI --version 0.3.0-rc.2 ``` -`ComponentRegistry` metadata is authoritative for the current inventory and dependency graph. `IsAvailable` distinguishes the 73 public direct targets from the 100 hidden support entries; `Dependencies` and `NuGetDependencies` are separate metadata fields used by the installer. Hidden entries such as `button-variants`, card sub-components, and `shellui-js` are not standalone public components. +```bash +# NuGet package +dotnet add package ShellUI.Components --version 0.3.0-rc.2 +``` -The current direct inventory includes `command-palette`, `data-picker`, `multi-select`, `tag-input`, and `typed-select` targets. New CLI sidebar installs use the host-loaded `shellui.js` and `ShellUI.initSidebar`; the legacy `sidebar-js` module remains only for older generated providers. See [COMPONENT_ROADMAP.md](COMPONENT_ROADMAP.md) and [COMPONENT_DEPENDENCIES.md](COMPONENT_DEPENDENCIES.md) for the current scope and registry-backed relationships. +**Full Changelog**: https://github.com/shellui-dev/shellui/compare/v0.3.0-rc.1...v0.3.0-rc.2 --- diff --git a/docs/tailwind-setup.md b/docs/tailwind-setup.md index 8adee5a..f0c0dd0 100644 --- a/docs/tailwind-setup.md +++ b/docs/tailwind-setup.md @@ -1,6 +1,6 @@ # Tailwind CSS Setup Guide for Blazor -This guide targets **Tailwind CSS 4.3.2**, the version used by the current ShellUI `0.4.0-alpha.1` source. +This guide targets **Tailwind CSS 4.3.2**, the version ShellUI uses. ## Installation methods @@ -25,15 +25,10 @@ For a production Blazor application, use either the standalone or npm workflow a ### Install the CLI ```text -dotnet tool install -g ShellUI.CLI +dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.2 ``` -For a local build, run the pack command from the ShellUI repository root, then install that package explicitly. A plain global install resolves the published stable `0.2.1`; the current `0.4.0-alpha.1` source is not published. - -```text -dotnet pack ShellUI.slnx --configuration Release -dotnet tool install -g ShellUI.CLI --add-source ./src/ShellUI.CLI/bin/Release --version 0.4.0-alpha.1 -``` +A plain install without `--version` selects the older stable `0.2.1`. ### Initialize a project diff --git a/prepare-release.ps1 b/prepare-release.ps1 index c8613f7..1507b79 100644 --- a/prepare-release.ps1 +++ b/prepare-release.ps1 @@ -67,6 +67,14 @@ if ($LASTEXITCODE -ne 0) { } Write-Host "✅ All tests passed" -ForegroundColor Green +$fullVersion = if ($Suffix) { "$Version-$Suffix" } else { $Version } +$notesHeading = "^# ShellUI v$([regex]::Escape($fullVersion))(\s|$)" +if (-not (Select-String -Path "docs/RELEASE_NOTES.md" -Pattern $notesHeading -Quiet)) { + Write-Host "❌ docs/RELEASE_NOTES.md has no '# ShellUI v$fullVersion' section" -ForegroundColor Red + exit 1 +} +Write-Host "✅ Release notes section found for v$fullVersion" -ForegroundColor Green + if ($DryRun) { Write-Host "`n🔍 DRY RUN COMPLETE" -ForegroundColor Cyan Write-Host "Run without -DryRun to apply changes" -ForegroundColor Yellow diff --git a/scripts/extract-release-notes.sh b/scripts/extract-release-notes.sh new file mode 100755 index 0000000..34b76ce --- /dev/null +++ b/scripts/extract-release-notes.sh @@ -0,0 +1,28 @@ +#!/usr/bin/env bash +# Usage: scripts/extract-release-notes.sh [notes-file] +set -euo pipefail + +version="${1:?usage: extract-release-notes.sh [notes-file]}" +file="${2:-docs/RELEASE_NOTES.md}" + +if ! awk -v ver="v$version" ' + { line = $0; sub(/\r$/, "", line) } + line ~ /^```/ { fence = !fence } + !fence && line ~ /^# ShellUI v/ { + if (found) exit + split(line, parts, " ") + if (parts[3] == ver) found = 1 + } + found { buf[++n] = $0 } + END { + if (!found) exit 1 + while (n > 0) { + last = buf[n]; sub(/\r$/, "", last) + if (last ~ /^[[:space:]]*(---)?[[:space:]]*$/) n--; else break + } + for (i = 1; i <= n; i++) print buf[i] + } +' "$file"; then + echo "No '# ShellUI v$version' section in $file — add release notes before tagging." >&2 + exit 1 +fi diff --git a/shellui-integration-notes.md b/shellui-integration-notes.md new file mode 100644 index 0000000..8ed77a4 --- /dev/null +++ b/shellui-integration-notes.md @@ -0,0 +1,297 @@ +# ShellUI + ShellIcons integration notes + +> [!NOTE] +> These are dated consumer-project notes captured against published `0.3.0-rc.1`. They are not the current product documentation. Current source facts and workflows are maintained in `README.md` and `docs/`. + +Notes captured while wiring the `SageEvolutionApi.Dashboard` Blazor Server project on `feat/dashboard`. Written for whoever picks this up next — either to reproduce, or to hand upstream to `shellui-dev`. + +Ground truth used: +- Local ShellUI source: `C:\Users\Shewatipa\source\repos\Shell\shellui\shellui\shellui` (`0.4.0-alpha.1` in `Directory.Build.props`) +- Published, installed, and used in this project: + - **`ShellUI.CLI` 0.3.0-rc.1** (`dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.1`) + - **Component templates 0.3.0-rc.1** (delivered by the CLI as `.razor` sources into `Components/UI/`) + - **`ShellIcons.Blazor` 0.1.0-alpha** (NuGet) + +--- + +## Install-channel gotcha (this bit us first) + +`dotnet tool install -g ShellUI.CLI` — no version — grabs stable-latest, which is **0.2.1**. All the fixes in `docs/RELEASE_NOTES.md` under the 0.3.0-rc.1 heading are trapped behind that: `App.razor` isn't patched with `@rendermode` / theme bootstrap / `shellui.js`, `input.css` is written as a single `@import "tailwindcss";` line so every `bg-background` class resolves to nothing, `data-table-models` fails to install, `ThemeToggle` uses `eval` and crashes during prerender. + +**Do this instead:** +```powershell +dotnet tool install -g ShellUI.CLI --version 0.3.0-rc.1 +# or upgrade an existing 0.2.1 +dotnet tool update -g ShellUI.CLI --version 0.3.0-rc.1 +``` +Then `shellui --version` should report `0.3.0-rc.1+…`. + +**Upstream ask.** Either (a) mark 0.3.0-rc.1 as the recommended install in the README quickstart (right now it says `dotnet tool install -g ShellUI.CLI` with no channel), or (b) publish 0.3.0 stable so plain-install lands on the fixes. Also worth: an `--allow-prerelease` reminder printed by `shellui --version` when a newer prerelease exists on NuGet. + +--- + +## Bugs still shipping in 0.3.0-rc.1 CLI + +After re-installing at 0.3.0-rc.1 and re-running `shellui init --yes --tailwind npm` + `shellui add `, three real bugs remained. + +### 1. `accordion-type` sub-dep not registered (same class as the 0.2.1 `data-table-models` bug) + +**Symptom.** `shellui add accordion` reports `Failed: accordion-type`. `Accordion.razor` compiles-in `[Parameter] public AccordionType Type { get; set; } = AccordionType.Single;` but `AccordionType.cs` never lands, so the project doesn't compile. + +**Verified in source.** `src/ShellUI.Templates/Templates/AccordionTypeTemplate.cs` exists with `Name = "accordion-type"`, `FilePath = "AccordionType.cs"`, `IsAvailable = false`, and `AccordionTemplate.cs:16` declares `Dependencies = new List { "accordion-type", "accordion-item" }`. So the template is there and the dep is declared — the wiring inside `ComponentRegistry.cs` is presumably what's missing (same shape as `data-table-models` and `chart-styles` were before). The RELEASE_NOTES fix that landed `data-table-models` didn't cover this case. + +**Workaround.** Hand-write `Components/UI/AccordionType.cs`: +```csharp +namespace SageEvolutionApi.Dashboard.Components.UI; +public enum AccordionType { Single, Multiple } +``` + +**Upstream ask.** Add a test in `NuGetDepsAndSuggestionsTests.cs` that walks *every* component's `Dependencies` list and asserts each name resolves via `ComponentRegistry.GetMetadata(...)`. That catches this bug class once and for all. + +### 2. `Tabs.razor` template ships with a mangled string literal + +**Symptom.** `Components/UI/Tabs.razor(18,38): error RZ1000: Unterminated string literal.` + +**Cause.** The installed Tabs.razor line 18 reads `private string _effectiveValue = ";` — three chars where four (`"";`) should be. The template source (`src/ShellUI.Templates/Templates/TabsTemplate.cs:35`) declares it as `private string _effectiveValue = "";` inside a `@"...""..."` verbatim block, so one of the two escape-doubled `""` gets clipped by the CLI's placeholder substitution or by the verbatim-decoder before write-out. `TemplateCompileTests` (per RELEASE_NOTES) should have caught this — it seems the compile pass is running against the raw template source, not against the CLI's *output* after placeholder substitution. + +**Workaround.** +```razor +private string _effectiveValue = ""; +``` + +**Upstream ask.** Add a `TemplateOutputCompileTest` variant that (a) runs each template through the placeholder substitution the CLI uses, then (b) `CSharpSyntaxTree.ParseText` on the substituted result. That's the surface consumers actually see. + +### 3. `Select.razor` renders "expand_more" as literal text + +**Symptom.** The Select dropdown shows the raw string `expand_more` in the corner where a chevron should be. + +**Cause.** Line 12: `expand_more`. This depends on Google Material Symbols being loaded via `` — which ShellUI never adds to `App.razor` and doesn't list as a required host resource. Every other ShellUI component uses inline SVG for its chrome (see DataTable's sort arrow, ThemeToggle's sun/moon, Sheet's close X, Accordion's chevron), so this is the odd one out. + +**Workaround.** +```razor + + + +``` + +**Upstream ask.** Replace the Material Symbols span with the inline chevron SVG — matches every other component in the library and drops a hidden network dependency. + +--- + +## 0.2.1 branch — fix candidates (backport from 0.3.0-rc.1) + +Each of these was hit on a real `dotnet tool install -g ShellUI.CLI` (stable-latest = 0.2.1) + `dotnet new blazor --interactivity Server --empty` + `shellui init --yes --tailwind npm` + `shellui add …` run in this project on 2026-09-04. All are fixed in `main` / 0.3.0-rc.1. If you want to cut a `hotfix/v0.2.1.1` branch off the `v0.2.1` tag, this section is the punch list — each item lists the symptom I saw, a minimal repro, the file(s) to touch in the source, and the pattern the fix in `main` took so you can cherry-forward it. + +Reference for every "the fix pattern in main is…" line below: `docs/RELEASE_NOTES.md` §"🐛 Critical fixes" under the 0.3.0-rc.1 heading. + +### B1. `input.css` written as one-line `@import "tailwindcss";` + +**Symptom.** Every ShellUI component renders unstyled. `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-card` etc. all resolve to nothing because Tailwind v4 needs the tokens declared under `@theme inline`, and none of them are there. + +**Repro.** After `shellui init` on 0.2.1, `wc -l wwwroot/input.css` → `1`. + +**Files.** `src/ShellUI.CLI/Services/ThemeService.cs` (writes `input.css`). + +**Fix pattern.** `main` writes ~193 lines: `:root {…light HSL vars…}`, `.dark {…dark HSL vars…}`, `@theme inline {…Tailwind color-token mapping…}`, `@custom-variant dark`, `@layer base {…}`, and Loading-component keyframes. Read the current `input.css` template out of `main`'s `ThemeService` and drop it verbatim. + +**Consumer-side test to pin the fix.** After init, assert the file contains at minimum: `@theme inline`, `--background`, and `.dark { --background`. Anything less is a broken install. + +### B2. `App.razor` not patched with `@rendermode`, theme bootstrap, or `shellui.js` + +**Symptom.** No JS interop reaches any component (ThemeToggle silently no-ops, InputOTP focus-forward doesn't work, Sonner toasts don't appear). `` renders SSR-only markup so the head never hydrates. On dark-preference machines, the page flashes light before the theme applies (FOUC). + +**Repro.** After `shellui init` on 0.2.1, open `Components/App.razor` — the file the template produced is identical to `dotnet new blazor`'s default: no `@rendermode`, no `