diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 35d2f36..ba4dd60 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -45,16 +45,15 @@ jobs: - name: Pack NuGet packages run: dotnet pack ShellUI.sln --no-build --configuration Release -p:ContinuousIntegrationBuild=true + # ShellUI.Core and ShellUI.Templates are internal-only โ€” they have no public API + # surface that consumers reference. Only the CLI tool and the Components runtime + # library are pushed to NuGet. - name: Publish to NuGet run: | dotnet nuget push src/ShellUI.CLI/bin/Release/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate if ls src/ShellUI.CLI/bin/Release/*.snupkg 1> /dev/null 2>&1; then dotnet nuget push src/ShellUI.CLI/bin/Release/*.snupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate fi - dotnet nuget push src/ShellUI.Core/bin/Release/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate - if ls src/ShellUI.Core/bin/Release/*.snupkg 1> /dev/null 2>&1; then - dotnet nuget push src/ShellUI.Core/bin/Release/*.snupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate - fi dotnet nuget push src/ShellUI.Components/bin/Release/*.nupkg --api-key ${{ secrets.NUGET_API_KEY }} --source https://api.nuget.org/v3/index.json --skip-duplicate if ls src/ShellUI.Components/bin/Release/*.snupkg 1> /dev/null 2>&1; then 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 @@ -73,7 +72,6 @@ jobs: prerelease: ${{ contains(github.ref, '-') }} files: | src/ShellUI.CLI/bin/Release/*.nupkg - src/ShellUI.Core/bin/Release/*.nupkg src/ShellUI.Components/bin/Release/*.nupkg env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/Directory.Build.props b/Directory.Build.props index 3718fa6..ca2262c 100644 --- a/Directory.Build.props +++ b/Directory.Build.props @@ -3,7 +3,7 @@ 0.3.0 - alpha.3 + rc.1 diff --git a/README.md b/README.md index f7108da..ae51ab5 100644 --- a/README.md +++ b/README.md @@ -304,67 +304,43 @@ Simply edit the component file in `Components/UI/` - it's yours to modify! ## ๐Ÿ“ฆ Package Overview -ShellUI consists of 2 packages: +ShellUI ships two NuGet packages โ€” the CLI is the primary install path; the runtime DLL is optional. -| Package | Type | Purpose | When to Use | -|---------|------|---------|-------------| -| `ShellUI.CLI` | Global Tool | Command-line tool for component installation | Development tool, install globally | -| `ShellUI.Components` | NuGet Package | Blazor components and variants | Runtime dependency for your app | +| Package | Type | Required? | Purpose | +|---------|------|-----------|---------| +| `ShellUI.CLI` | .NET global tool | โœ… Yes โ€” primary install path | Sets up Tailwind, theme CSS, patches `App.razor`, and copies component source so Tailwind can scan it | +| `ShellUI.Components` | Razor class library | Optional | Runtime DLL with the same components + `shellui.js` interop + `Shell.Cn` helper. Useful when you want to reference component types from your own code or build a library on top of ShellUI | -**For Users:** -- Install `ShellUI.CLI` as a global tool: `dotnet tool install -g ShellUI.CLI` -- Install `ShellUI.Components` in your project: `dotnet add package ShellUI.Components` +`ShellUI.Core` and `ShellUI.Templates` are internal to the CLI and not published to NuGet โ€” consumers never reference them directly. -## Installation Options +## Installation + +ShellUI is a **CLI-first** library. The CLI is what wires up Tailwind, drops the theme into `wwwroot/input.css`, patches `App.razor` with the render mode and theme bootstrap, and copies component source into your project so Tailwind can scan it. -### Option 1: CLI Tool (Recommended) ```bash dotnet tool install -g ShellUI.CLI -shellui init # Choose your Tailwind method -shellui add button input card dialog -# Note: CLI tool must be installed first with 'dotnet tool install -g ShellUI.CLI' +shellui init # one-time setup +shellui add button card dialog # any time you want more components ``` -### Option 2: NuGet Package -```bash -# Add the component package -dotnet add package ShellUI.Components +That's it. Components render styled out of the box. Re-run `shellui add` whenever you want more. -# Manual setup required - detailed steps below -``` +### Where does `ShellUI.Components` (the NuGet package) fit? -**๐Ÿ“‹ NuGet Package Setup Guide:** +The NuGet package ships the same component DLLs, the JS interop (`shellui.js`), and helpers like `Shell.Cn`. It's useful when you want the runtime types referenced directly โ€” e.g. consuming `Shell.Cn` from your own code, or shipping a library that re-exports ShellUI components. -#### 1. **Install Tailwind CSS v4.1.18** -```bash -# Download the standalone Tailwind CLI -curl -L https://github.com/tailwindlabs/tailwindcss/releases/download/v4.1.18/tailwindcss-linux-x64 -o tailwindcss -chmod +x tailwindcss -sudo mv tailwindcss /usr/local/bin/ -``` +**The NuGet package alone does not produce styled components.** Tailwind v4 builds the CSS at compile time by scanning `.razor` source files. The component source lives inside the DLL, so Tailwind never sees the utility classes used inside ShellUI components and emits no rules for them. The result: components render with the right HTML structure but with most styling missing. -#### 2. **Remove Bootstrap Files** -Delete these files/folders from your `wwwroot` directory: -```bash -# Remove Bootstrap CSS/JS -rm -rf wwwroot/lib/bootstrap/ -rm wwwroot/css/bootstrap*.css -rm wwwroot/css/bootstrap*.min.css -``` +The supported way to get styled components is: -#### 3. **Include ShellUI Theme CSS** -Add this link to your main layout file (usually `Shared/MainLayout.razor` or similar): -```html - -``` +1. `dotnet tool install -g ShellUI.CLI` +2. `shellui init` โ€” sets up Tailwind, theme CSS, and patches `App.razor` +3. `shellui add ` for every component you want styled โ€” this copies the `.razor` source into your project so Tailwind can scan it +4. *(Optional)* `dotnet add package ShellUI.Components --prerelease` if you also want the runtime DLL on hand (most projects don't need both โ€” pick one) -#### 4. **Update _Imports.razor** -Add this line to your `Pages/_Imports.razor` or `Components/_Imports.razor`: -```razor -@using ShellUI.Components -``` +We're tracking a proper "NuGet-only with auto-CSS" path for a future release (`v0.4.x`). Until then, run the CLI. -#### 5. **Configure Tailwind CSS** +### Configure Tailwind CSS manually (advanced) Create/update `wwwroot/tailwind.config.js`: ```javascript /** @type {import('tailwindcss').Config} */ @@ -554,27 +530,15 @@ Update `wwwroot/app.css` (or create it): @import "./input.css"; ``` -#### 5. **Update _Layout.cshtml or MainLayout.razor** -Add Tailwind CSS to your layout: +#### 5. **Reference the compiled CSS** +Add the link to your layout (`_Layout.cshtml` or `MainLayout.razor`): ```html - - - - ``` -**๐Ÿ“‹ NuGet Package Checklist:** -- โœ… Install package: `dotnet add package ShellUI.Components` -- โœ… **Remove Bootstrap**: Delete `wwwroot/lib/bootstrap/` folder and `wwwroot/css/bootstrap*.css` files -- โœ… **Install Tailwind**: Download Tailwind CLI v4.1.18 -- โœ… **Include theme CSS**: Add ShellUI theme CSS link to your main layout -- โœ… **Add using**: `@using ShellUI.Components` in `_Imports.razor` -- โœ… **Create config**: `wwwroot/tailwind.config.js` -- โœ… **Create CSS**: `wwwroot/input.css` and `wwwroot/app.css` -- โœ… **Update layout**: Add CSS link to your main layout file - -**โš ๏ธ Important:** ShellUI components require Tailwind CSS. The NuGet package includes components only - you'll need to set up Tailwind separately. +This is what `shellui init` does for you automatically; documented here for the manual path. + +**โš ๏ธ Reminder:** even with all the manual setup above, you still need to copy each component's `.razor` source into your project (`shellui add `) so Tailwind sees the classes it uses. There's no way around this for Tailwind v4 short of pre-compiling a complete CSS bundle and shipping it with the package โ€” which is what the [v0.4.x NuGet-only path](https://github.com/shellui-dev/shellui/issues) will deliver. ## Contributing diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index 90139ea..f85ed0e 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -1,3 +1,114 @@ +# ShellUI v0.3.0-rc.1 ๐Ÿšฆ + +> Release candidate for v0.3.0. Five branches of integration-tested fixes against the alpha series, surfaced from real-world Blazor Server consumer use. If no critical reports come in during the soak window, this code ships as `v0.3.0` stable with the suffix dropped โ€” no further code changes. Report issues via [GitHub Issues](https://github.com/shellui-dev/shellui/issues). + +## TL;DR + +`shellui init` + `shellui add` now produce a project that compiles and runs end-to-end without manual host patching. Every alpha.3 install-time papercut documented in the integration notes is fixed and guarded by tests + CI: + +- Three chart/dashboard templates no longer ship uncompilable C# verbatim strings +- `SidebarTrigger` mobile hamburger renders (was an invisible FontAwesome class) +- `ThemeToggle` no longer uses `eval` and no longer crashes during Blazor Server prerender +- `shellui init` patches `App.razor` with `@rendermode`, theme bootstrap script, and `shellui.js` link tag โ€” and writes the full default theme to `input.css` instead of just `@import "tailwindcss";` +- `shellui add data-table` actually installs `DataTableModels.cs` and auto-runs `dotnet add package System.Linq.Dynamic.Core` +- `shellui add chart` auto-runs `dotnet add package Blazor-ApexCharts` and the chart tooltip CSS finally renders readable text instead of invisible white-on-white +- New `did you mean โ€ฆ?` typo suggestion (`shellui add datatable` โ†’ `Did you mean 'data-table'?`) + +Component count corrected across docs: **68 installable** top-level components (not the 100 previously claimed; sub-components and variants ship as auto-installed dependencies). + +## ๐Ÿ› Critical fixes + +### Templates that shipped uncompilable C# +- **`ChartVariants`** โ€” every JS-attribute quote inside the tooltip `Custom = @"..."` block now escapes as `""x""` (the verbatim-string form) instead of bare `"x"` (which terminated the outer string) +- **`PieChart`** โ€” same class of bug but using `\"x\"` (which decoded to literal backslashes in rendered HTML); fixed to `""x""` +- **`DashboardLayout02`** โ€” unterminated empty-string literal in `BuildBreadcrumb` (`segments[0] == ""))` โ†’ `segments[0] == """"))`) +- Live `PieChart.razor` in the library had the same backslash bug; fixed to remove visible `\"` from rendered tooltip HTML + +### SidebarTrigger + ThemeToggle runtime +- **`SidebarTrigger`** โ€” `` swapped for inline SVG hamburger. FontAwesome is not a ShellUI dependency, so mobile users on a fresh install previously saw an invisible toggle button +- **`ThemeToggle`** โ€” `JSRuntime.InvokeVoidAsync("eval", โ€ฆ)` dropped in favor of the `ShellUI.addClassToDocument` / `ShellUI.removeClassFromDocument` helpers already shipped in `shellui.js`. No more CSP-blockable `eval`, no new JS surface area +- **`ThemeToggle`** โ€” localStorage read moved from `OnInitializedAsync` (where `IJSRuntime` is unavailable during Blazor Server prerender) to `OnAfterRenderAsync(firstRender)` +- **`InputOTP`** โ€” same `eval` removal applied; now uses `ShellUI.focusElement` for digit-to-digit focus +- **`ThemeService`** โ€” same `eval` cleanup as `ThemeToggle` + +### `shellui init` produces a working host +- **App.razor patching** โ€” `` โ†’ ``, same for ``. Existing `@rendermode` values are preserved (won't overwrite `InteractiveAuto`/`InteractiveWebAssembly`) +- **Theme bootstrap `