Documentations added

Co-authored-by: Copilot <copilot@github.com>
2026-05-04 19:57:48 +05:00
parent 40a7d9018c
commit ee8797c142
35 changed files with 6655 additions and 0 deletions
@@ -0,0 +1,148 @@
+# Separator
+
+A thin divider line. Renders as a horizontal `<hr>` or a vertical bar depending on orientation.
+
+---
+
+## HTML structure
+
+**Horizontal:**
+```
+hr.border-t.border-border.my-4.{extraClasses}
+```
+
+**Vertical:**
+```
+span.inline-block.border-l.border-border.mx-2.h-4.{extraClasses}
+```
+
+---
+
+## CSS mechanics
+
+| Class | Effect |
+|---|---|
+| `border-t border-border` | Top border in the theme's border color (horizontal) |
+| `border-l border-border` | Left border in the theme's border color (vertical) |
+| `my-4` | Default vertical margin for horizontal separators |
+| `mx-2` | Default horizontal margin for vertical separators |
+| `h-4` | 16px height for vertical separators |
+
+---
+
+## Constructor signature
+
+```csharp
+public Separator(
+    string orientation  = "horizontal",
+    string extraClasses = "")
+```
+
+| Parameter | Description |
+|---|---|
+| `orientation` | `"horizontal"` (default) or `"vertical"` |
+| `extraClasses` | Additional Tailwind classes on the element |
+
+---
+
+## Usage examples
+
+### Horizontal divider
+
+```csharp
+new Separator()
+```
+
+### Vertical divider in a flex toolbar
+
+```html
+<div class="flex items-center gap-2">
+  <button>Bold</button>
+  $$VertSep$$
+  <button>Italic</button>
+  $$VertSep$$
+  <button>Underline</button>
+</div>
+```
+
+```csharp
+var VertSep = new Separator(orientation: "vertical");
+```
+
+### Custom margin
+
+```csharp
+new Separator(extraClasses: "my-8")       // extra vertical space
+new Separator(extraClasses: "my-0 mt-2")  // override default margin
+```
+
+---
+
+## Tips and tricks
+
+- The horizontal `Separator` is an `<hr>` element — it carries semantic meaning as a thematic break. Use it between content sections.
+- The vertical `Separator` is an inline `<span>` — use it inside `flex` rows (toolbars, breadcrumb rows, stat rows, etc.).
+- Override margins using `extraClasses` when the default `my-4` / `mx-2` doesn't fit the surrounding layout.
+- Override margins using `extraClasses` when the default `my-4` / `mx-2` doesn't fit the surrounding layout.
+
+---
+
+## Complete page example
+
+**`Templates/AboutPage.htmx`**
+```html
+<div class="max-w-2xl mx-auto py-10">
+  <h1 class="text-3xl font-bold mb-2">About BeepBoop</h1>
+  <p class="text-muted-foreground mb-4">A fast AOT-safe HTMX framework for .NET 10.</p>
+  $$SectionSep1$$
+  <h2 class="text-xl font-semibold mb-2">Mission</h2>
+  <p class="text-sm mb-4">$$MissionText$$</p>
+  $$SectionSep2$$
+  <h2 class="text-xl font-semibold mb-2">Team</h2>
+  <div class="flex items-center gap-2 text-sm">
+    <span>Alice</span>
+    $$InlineSep$$
+    <span>Bob</span>
+    $$InlineSep$$
+    <span>Carol</span>
+  </div>
+</div>
+```
+
+**`Templates/AboutPage.htmx.cs`**
+```csharp
+namespace Htmx.ApiDemo.Templates;
+
+public sealed class AboutPage : AboutPageBase
+{
+    private readonly IHtmxComponent _sep1;
+    private readonly IHtmxComponent _sep2;
+    private readonly IHtmxComponent _inline;
+    private readonly byte[] _mission;
+
+    public AboutPage()
+    {
+        _sep1    = new Components.Separator();
+        _sep2    = new Components.Separator();
+        _inline  = new Components.Separator(orientation: "vertical");
+        _mission = "BeepBoop makes building server-rendered HTMX apps as fast and safe as possible.".ToUtf8Bytes();
+    }
+
+    protected override void RenderSectionSep1(HtmxRenderContext ctx) => _sep1.Render(ctx.Next());
+    protected override void RenderSectionSep2(HtmxRenderContext ctx) => _sep2.Render(ctx.Next());
+    protected override void RenderInlineSep(HtmxRenderContext ctx)   => _inline.Render(ctx.Next());
+    protected override void RenderMissionText(HtmxRenderContext ctx) => ctx.Writer.WriteUtf8(_mission);
+}
+```
+
+**GET handler**
+```csharp
+[Handler]
+[MapGet("/about")]
+public static partial class GetAboutHandler
+{
+    public record Query();
+    private static Task<IResult> HandleAsync(Query _, HttpContext ctx, CancellationToken ct)
+        => ctx.WriteHtmxPage(new AboutPage(), title: "About");
+}
+```