diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 015acb0..1b55eaa 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -53,9 +53,8 @@ jobs: grep -Fq 'px-2\.5' "$BUNDLE" || (echo "ERROR: Badge padding class px-2.5 missing (variant .cs helpers not scanned?)"; exit 1) grep -Fq 'border-transparent' "$BUNDLE" || (echo "ERROR: border-transparent missing (variant .cs helpers not scanned?)"; exit 1) - # Size guard β€” well above the ~77KB current 68 components emit, tight - # enough to catch a runaway (someone disabling minify, dumping the whole - # tailwind base without tree-shake, etc.). + # Size guard β€” keep the threshold above the current component bundle, + # but below runaway output (for example, an unminified full Tailwind base). size=$(wc -c < "$BUNDLE") echo "precompiled bundle size: ${size} bytes" if [ "$size" -gt 150000 ]; then @@ -91,7 +90,10 @@ jobs: grep -q 'Routes @rendermode="InteractiveServer"' Components/App.razor || (echo "init did not patch Routes @rendermode"; exit 1) grep -q 'ShellUI theme bootstrap' Components/App.razor || (echo "init did not inject theme bootstrap"; exit 1) grep -q '' Components/App.razor || (echo "init did not inject shellui.js script tag"; exit 1) - grep -q 'shellui-sidebar.js' Components/App.razor && (echo "init incorrectly injected shellui-sidebar.js script tag (sidebar JS is dynamically imported)"; exit 1) || true + if grep -Fq 'shellui-sidebar.js' Components/App.razor; then + echo "init incorrectly injected a shellui-sidebar.js script tag (sidebar JS lives in the global shellui.js now)" + exit 1 + fi # Assert input.css has the full theme, not just @import "tailwindcss"; grep -q '@theme inline' wwwroot/input.css || (echo "init did not write full theme to input.css"; exit 1) @@ -114,6 +116,22 @@ jobs: test -f wwwroot/css/charts.css || (echo "shellui add chart did not install chart-styles CSS"; exit 1) grep -q '/, not the root. + grep -q 'ShellUI.initSidebar' Components/UI/SidebarProvider.razor || (echo "SidebarProvider did not call ShellUI.initSidebar"; exit 1) + if grep -Fq 'shellui-sidebar.js' Components/UI/SidebarProvider.razor; then + echo "SidebarProvider still dynamically imports shellui-sidebar.js" + exit 1 + fi + + test -f wwwroot/shellui.js || (echo "shellui.js was not installed"; exit 1) + grep -Fq 'initSidebar: function (handle, dotNetRef)' wwwroot/shellui.js || (echo "shellui.js does not expose initSidebar"; exit 1) + grep -Fq 'disposeSidebar: function (handle)' wwwroot/shellui.js || (echo "shellui.js does not expose disposeSidebar"; exit 1) + test ! -e wwwroot/shellui-sidebar.js || (echo "legacy sidebar JS was installed for a fresh sidebar install"; exit 1) + dotnet build -c Debug # Pure-NuGet install path β€” `dotnet add package ShellUI.Components` without diff --git a/README.md b/README.md index 0289c9f..fe096d3 100644 --- a/README.md +++ b/README.md @@ -9,763 +9,193 @@

ShellUI

- A modern, CLI-first Blazor component library inspired by shadcn/ui.
- Copy components directly into your project and customize them to match your needs. + A CLI-first Blazor component library inspired by shadcn/ui.
+ Copy component source into your project or reference the components package.

GitHub stars - NuGet - CLI - License + ShellUI.Components on NuGet + ShellUI.CLI on NuGet + MIT license

-

- - Star History Chart - -

- ---- - -**New here? Check out the [Quick Start](#quick-start) section below!** - -## Vision +## Status -ShellUI transforms Blazor component development with a hybrid approach: -- **CLI-First**: Copy components to YOUR codebase for full control (`shellui add button`) -- **NuGet Option**: Traditional package install for quick starts (`dotnet add package ShellUI.Components`) -- **Choose your workflow**: Use CLI for customization, NuGet for speed, or mix both -- Powered by Tailwind CSS v4.3.1 (standalone CLI - no Node.js required!) -- Best of both worlds: flexibility when you need it, convenience when you want it +| 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 | -## Current Status: 68 Components (Alpha) πŸŽ‰ +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. -**ShellUI is in alpha!** Test and provide feedback before we ship stable. We've completed: -- βœ… **CLI Tool** (`dotnet tool install -g ShellUI.CLI`) -- βœ… **NuGet Package** (`dotnet add package ShellUI.Components`) -- βœ… **68 Installable Components** with Tailwind v4.3.1 *(top-level components you `shellui add` β€” sub-components, variants, models, and services auto-install as dependencies)* -- βœ… **Hybrid Workflow** (CLI + NuGet) -- βœ… **No Node.js Required** (Standalone Tailwind CLI) -- βœ… **Comprehensive Documentation** -- βœ… **Working Demos & Examples** +ShellUI is alpha software. Validate it in your target Blazor and hosting environments before relying on it. -**Ready to use today!** πŸš€ +## Current source capabilities -## What's Working Today πŸš€ +- 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`. +- `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`. -### βœ… CLI Tool + NuGet Package -```bash -# Install CLI globally -dotnet tool install -g ShellUI.CLI +## Requirements -# Initialize in your Blazor project (choose npm or standalone) -shellui init +- .NET 10 SDK for the current source +- A .NET 10 Blazor project +- Tailwind CSS `4.3.2` via either: + - the standalone CLI, which does not require Node.js; or + - npm, which requires Node.js and npm -# For CI/CD or automated environments: -shellui init --yes # Uses standalone Tailwind with default options +## CLI quick start -# Add components -shellui add button input card dialog +The published global tool is named `shellui`: -# List all available components -shellui list +```bash +dotnet tool install --global ShellUI.CLI --version 0.2.1 +shellui --help ``` -**⚠️ Note:** The CLI tool must be installed first. Use `shellui` commands (not `dotnet shellui`). - -## πŸ“¦ Unified Versioning System - -ShellUI uses a **centralized versioning system** where all components, CLI tool, and packages share the same version number. This ensures consistency and simplifies dependency management. - -### Version Update Process - -To update ShellUI version across all components: - -1. **Edit `Directory.Build.props`** in the repository root: - ```xml - 0.3.0 - - ``` +To select the published prerelease instead: -2. **Clean and rebuild** all projects: - ```bash - dotnet clean - dotnet build --configuration Release - ``` - -This single file change updates: -- βœ… All NuGet packages (`ShellUI.CLI`, `ShellUI.Components`) -- βœ… All component templates (68 installable components) -- βœ… Build configurations and metadata - -**Example for pre-release:** -```xml -0.3.0 -alpha.2 +```bash +dotnet tool install --global ShellUI.CLI --version 0.3.0-rc.1 ``` -Results in version: `0.3.0-alpha.2` - -### Component Versioning Strategy - -**By Design:** All components share the same version because they: -- Work together as a cohesive system -- Depend on shared utilities and theming -- Follow consistent design patterns -- Are tested together - -**For Advanced Users:** Future versions may support component-specific versioning for power users who need granular control. - -### βœ… 68 Production-Ready Components - -Counts below are top-level components you can `shellui add` directly. Sub-components (e.g. `SidebarTrigger`, `DialogContent`, `TableRow`), variants (`ButtonVariants`, `AlertVariants`, …), models, and services auto-install as dependencies and are not counted. - -**Form (17):** -Button, Checkbox, Combobox, DatePicker, DateRangePicker, FileUpload, Form, Input, InputOTP, Label, RadioGroup, Select, Slider, Switch, Textarea, TimePicker, Toggle - -**Layout (12):** -Accordion, Breadcrumb, Card, Collapsible, DashboardLayout01, DashboardLayout02, LinkCard, Navbar, Resizable, ScrollArea, Separator, Sidebar - -**Navigation (7):** -ContextMenu, Menubar, NavigationMenu, Pagination, PrevNextNav, Stepper, Tabs - -**Overlay (8):** -AlertDialog, Command, Dialog, Drawer, Dropdown, HoverCard, Popover, Sheet - -**Data Display (13):** -AreaChart, Avatar, Badge, BarChart, Calendar, Carousel, Chart, ChartSeries, DataTable, LineChart, MultiSeriesChart, PieChart, Table - -**Feedback (9):** -Alert, Callout, EmptyState, Loading, Progress, Skeleton, Sonner, Toast, Tooltip - -**Utility (2):** -CopyButton, ThemeToggle -### βœ… Tailwind CSS v4.3.1 Integration +A local .NET tool is invoked as `dotnet shellui`: -**Two Setup Methods:** - -**Method 1: Standalone CLI (No Node.js!)** ```bash -shellui init # Choose "standalone" -# Or: dotnet shellui init +dotnet new tool-manifest +dotnet tool install --local ShellUI.CLI --version 0.3.0-rc.1 +dotnet shellui --help ``` -- Downloads Tailwind CLI binary automatically -- No Node.js or npm required -- Auto-builds on project compile -**Method 2: npm (If you prefer)** -```bash -shellui init # Choose "npm" -# Or: dotnet shellui init -``` -- Installs `tailwindcss@^4.3.1` + `@tailwindcss/cli@^4.3.1` -- Uses `npx @tailwindcss/cli` for builds -- Requires Node.js - -### 🎨 Easy Theme Customization - -**Customize themes instantly with [tweakcn](https://tweakcn.com/):** - -1. Visit tweakcn and design your perfect theme -2. Copy the generated CSS variables -3. Paste into `wwwroot/input.css` -4. All ShellUI components update automatically! - -**Custom fonts?** Add Google Fonts links and update your CSS variables - works seamlessly! πŸ”€ - -## What's Next - -### Phase 1: Additional Components -**Target: Q1 2026** - -- More advanced components -- Enhanced DataTable features (sorting/filtering) -- Charts and data visualization -- VirtualScroll for large lists -- PDFViewer component -- And more... - -### Phase 2: Documentation & Polish -**Target: Q2 2026** - -- Complete documentation website -- Video tutorials -- Migration guides -- Performance optimization -- Testing infrastructure - -## Design Principles - -1. **Copy, Don't Install**: Components are copied to your project, not imported from a package -2. **Tailwind-First**: All styling uses Tailwind CSS v4.3.1 utility classes -3. **Accessible by Default**: WCAG 2.1 AA compliant out of the box -4. **Composable**: Build complex components from simple ones -5. **Customizable**: Modify any component to fit your needs -6. **Type-Safe**: Leverage C# type system for better DX -7. **Performance**: Optimized for both Server and WASM scenarios -8. **No Node.js Required**: Standalone Tailwind CLI for maximum compatibility - -## Architecture Decisions - -### Why Hybrid Approach (CLI + NuGet)? -**CLI Benefits:** -- Full control over component code -- Customize without forking -- Only include what you use (smaller bundles) -- No version lock-in -- Better debugging experience - -**NuGet Benefits:** -- Traditional workflow developers know -- Faster initial setup -- Automatic updates via package manager -- Good for prototyping -- Team familiarity - -**Use both:** Start with NuGet, migrate to CLI for components you customize heavily! - -### Why Tailwind v4.3.1? -- Latest stable version with v4 features -- Better performance than v3 -- Improved dark mode support -- Native CSS variable support -- Smaller output CSS -- Standalone CLI (no Node.js required!) - -### Component Structure - -- `Components/UI/` - ShellUI components (Button.razor, Input.razor, Card.razor, ...) -- `Components/UI/Variants/` - Variant classes (*Variants.cs) -- `wwwroot/` - input.css, app.css (compiled) -- `.shellui/bin/` - Tailwind CLI binary (standalone) -- `tailwind.config.js`, `shellui.json` -- `Build/ShellUI.targets` - MSBuild integration - -## Developer Experience Today - -### Quick Start -```bash -# Install CLI globally -dotnet tool install -g ShellUI.CLI +After building or installing the current source tool, its workflow is: -# Initialize in your Blazor project (choose npm or standalone) +```bash shellui init -# Or: dotnet shellui init - -# Add components -shellui add button input card dialog -# Or: dotnet shellui add button input card dialog - -shellui list # See all 68 available components -# Or: dotnet shellui list -``` - -### Use Components -```razor -@page "/example" - - - - Welcome to ShellUI - Build beautiful Blazor apps - - - - - - +shellui add button card dialog +shellui list +shellui remove button +shellui update ``` -### Customize Components -Simply edit the component file in `Components/UI/` - it's yours to modify! - -## Technical Requirements - -- .NET 8.0 or higher -- **Choice of Tailwind setup:** - - **Standalone CLI** (recommended): No Node.js required - - **npm**: Requires Node.js, uses `tailwindcss@^4.3.1` - -## Comparison with Existing Solutions - -| Feature | ShellUI | MudBlazor | Radzen | Blazorise | -|---------|---------|-----------|--------|-----------| -| CLI Installation | βœ… | ❌ | ❌ | ❌ | -| NuGet Package | βœ… | βœ… | βœ… | βœ… | -| Component Ownership (CLI) | βœ… | ❌ | ❌ | ❌ | -| Tailwind CSS | βœ… (v4.3.1) | ❌ | ❌ | ❌ | -| No Node.js Required | βœ… | N/A | N/A | N/A | -| Hybrid Workflow | βœ… | ❌ | ❌ | ❌ | -| Free & Open Source | βœ… | βœ… | Partial | βœ… | -| Customization | Full | Limited | Limited | Limited | -| Components | 68 | 70+ | 50+ | 80+ | -| Current Status | Production Ready | Mature | Commercial | Mature | +Use the same commands with a `dotnet ` prefix when the tool is installed locally. Do not use `dotnet shellui` for a global installation. -## πŸ“¦ Package Overview +New CLI sidebar installs use the host-loaded `shellui.js`; the legacy `sidebar-js` module remains available only for older generated providers. -ShellUI ships two NuGet packages β€” the CLI is the primary install path; the runtime DLL is optional. +### Command reference -| 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 | - -`ShellUI.Core` and `ShellUI.Templates` are internal to the CLI and not published to NuGet β€” consumers never reference them directly. - -## Installation - -**Four install paths.** Pick one β€” they cover every "shape" of Blazor / static project. - -### 🚦 Quick decision matrix - -| I want to… | Use | +| Command | Purpose | |---|---| -| Ship the fastest β€” one `` tag, no build config | **Path A** β€” NuGet + precompiled bundle | -| Tree-shaken CSS, I already run Tailwind for my own utilities | **Path B** β€” NuGet + safelist | -| Own the component source code, restyle by editing `.razor` files | **Path C** β€” CLI | -| Prototype in a static HTML page or JSFiddle without NuGet at all | **Path D** β€” CDN | - -The four paths coexist cleanly. You can even mix them (use CLI for a few customized components and NuGet for the rest). +| `init` | Set up ShellUI, Tailwind, host wiring, and the generated project structure | +| `add ` | Install one or more direct targets 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 | +| `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` | ---- +The five current source targets can be installed together: -### Path A β€” NuGet + precompiled CSS bundle (simplest, new in 0.4.x) +```bash +shellui add typed-select command-palette data-picker multi-select tag-input +``` -**Who it's for:** you want components on screen with minimum ceremony. No Tailwind config, no npm, no CLI. Just NuGet and a `` tag. +## Components package -**Setup (2 lines of code):** +Published versions can be installed explicitly: ```bash -dotnet add package ShellUI.Components +dotnet add package ShellUI.Components --version 0.2.1 ``` -```razor -@* App.razor *@ - +To select the published prerelease instead: -@* _Imports.razor *@ -@using ShellUI.Components +```bash +dotnet add package ShellUI.Components --version 0.3.0-rc.1 --prerelease ``` -Done. `