Added docs

2026-04-13 18:57:47 +05:00
parent b323862e03
commit 5668cf20d9
9 changed files with 1421 additions and 1 deletions
@@ -0,0 +1,209 @@
+# Getting Started
+
+This guide walks you through adding **Enciphered.Blazor.UIComponents** to a new or existing Blazor Web App and building a fully static SSR application with htmx-powered form validation.
+
+---
+
+## Prerequisites
+
+| Tool | Version |
+|---|---|
+| .NET SDK | 9.0+ |
+| Node.js | 18+ (for Tailwind CSS CLI) |
+
+---
+
+## 1. Create a Blazor Web App
+
+```bash
+dotnet new blazor -n MyApp --interactivity None
+cd MyApp
+```
+
+> The `--interactivity None` flag creates a pure static SSR app — no SignalR or WebAssembly.
+
+---
+
+## 2. Install the Library
+
+```bash
+dotnet add reference path/to/Enciphered.Blazor.UIComponents.csproj
+```
+
+Or, if published as a NuGet package:
+
+```bash
+dotnet add package Enciphered.Blazor.UIComponents
+```
+
+---
+
+## 3. Install Tailwind CSS v4
+
+From your solution root, initialize npm and install Tailwind:
+
+```bash
+npm init -y
+npm install tailwindcss @tailwindcss/cli
+```
+
+Create `Styles/app.css` in your app project:
+
+```css
+@import "tailwindcss";
+
+@custom-variant dark (&:where(.dark, .dark *));
+```
+
+Add the library's design tokens by importing or copying the token definitions from `Enciphered.Blazor.UIComponents/Styles/app.css`. At minimum you need the `:root` and `.dark` token blocks and the `@theme` mapping.
+
+Add a build step to your `.csproj`:
+
+```xml
+<Target Name="TailwindBuild" BeforeTargets="Build">
+  <Exec Command="npx @tailwindcss/cli -i Styles/app.css -o wwwroot/css/app.css --minify" />
+</Target>
+```
+
+---
+
+## 4. Configure `App.razor`
+
+Your root `App.razor` needs three things:
+
+1. **Stylesheet references** — the library CSS and your app CSS
+2. **htmx CDN** — loaded after `blazor.web.js`
+3. **JS module imports** — initialize the library's interactive modules
+
+```razor
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <base href="/" />
+
+    <!-- Dark-mode bootstrap: prevents flash of wrong theme -->
+    <script>
+        (function () {
+            try {
+                if (localStorage.getItem('theme') === 'dark')
+                    document.documentElement.classList.add('dark');
+            } catch (e) { }
+        })();
+    </script>
+
+    <!-- Library stylesheet (design tokens + component styles) -->
+    <link rel="stylesheet" href="_content/Enciphered.Blazor.UIComponents/css/app.css" />
+
+    <!-- Your app stylesheet -->
+    <link rel="stylesheet" href="css/app.css" />
+
+    <HeadOutlet />
+</head>
+<body class="min-h-svh antialiased bg-background text-foreground">
+    <Routes />
+
+    <!-- Blazor framework script -->
+    <script src="_framework/blazor.web.js"></script>
+
+    <!-- htmx (required for form validation/submission) -->
+    <script src="https://unpkg.com/htmx.org@2.0.4"
+            integrity="sha384-HGfztofotfshcF7+8n44JQL2oJmowVChPTg48S+jvZoztPfvwD79OC/LTtG6dMp+"
+            crossorigin="anonymous"></script>
+
+    <!-- Initialize library JS modules -->
+    <script type="module">
+        import { init as initDarkMode } from '/_content/Enciphered.Blazor.UIComponents/js/darkmode.js';
+        import { init as initSidebar } from '/_content/Enciphered.Blazor.UIComponents/js/sidebar.js';
+        import { init as initForms } from '/_content/Enciphered.Blazor.UIComponents/js/forms.js';
+        initDarkMode();
+        initSidebar();
+        initForms();
+    </script>
+</body>
+</html>
+```
+
+> **Note**: Only import the modules you need. If you don't use the sidebar, skip `initSidebar()`. If you don't use forms, skip `initForms()`. If you don't need dark mode, skip `initDarkMode()` and the bootstrap script.
+
+---
+
+## 5. Configure `Program.cs`
+
+Register Razor Components and map the library assembly:
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddRazorComponents();
+builder.Services.AddAntiforgery();
+
+var app = builder.Build();
+
+app.UseHttpsRedirection();
+app.UseAntiforgery();
+app.MapStaticAssets();
+
+app.MapRazorComponents<App>()
+    .AddAdditionalAssemblies(
+        typeof(Enciphered.Blazor.UIComponents.SidebarProvider).Assembly);
+
+app.Run();
+```
+
+> The `AddAdditionalAssemblies` call registers the library's components for routing discovery.
+
+---
+
+## 6. Add `_Imports.razor`
+
+In your app's `Components/_Imports.razor`, add:
+
+```razor
+@using Enciphered.Blazor.UIComponents
+```
+
+This makes all library components available without per-file `@using` directives.
+
+---
+
+## 7. Verify the Setup
+
+Create a simple page to test:
+
+```razor
+@page "/test"
+
+<Card>
+    <CardHeader>
+        <CardTitle>It Works!</CardTitle>
+        <CardDescription>The library is installed correctly.</CardDescription>
+    </CardHeader>
+    <CardContent>
+        <p>If you can see this styled card, everything is set up.</p>
+    </CardContent>
+    <CardFooter>
+        <Button>Click Me</Button>
+    </CardFooter>
+</Card>
+```
+
+Run the app:
+
+```bash
+dotnet run
+```
+
+You should see a styled card with a button. If the styles aren't applied, verify:
+- The Tailwind build step ran (check `wwwroot/css/app.css` exists)
+- The stylesheet links in `App.razor` are correct
+- The design tokens are present in your `Styles/app.css`
+
+---
+
+## Next Steps
+
+- [Set up a sidebar layout →](components/sidebar.md)
+- [Add form validation with htmx →](forms/validation.md)
+- [Browse all components →](components/button.md)