Bootstrap Helpers

HeimdallFramework.Bootstrap is a strongly typed Bootstrap vocabulary for server-rendered HTML. It gives you discoverable class helpers without turning Bootstrap into a component framework.

The package keeps the same Heimdall philosophy: HTML stays explicit, composition stays on the server, and helpers map directly to real Bootstrap classes.

1. What the Package Is

The Bootstrap package is a typed class helper layer. It is not a renderer, not a theme system, and not a replacement for Bootstrap itself.

HeimdallFramework.Bootstrap
-> typed constants and helpers
-> real Bootstrap class strings
-> used with FluentHtml, Html, and HeimdallHtml

2. Install

Add the package alongside HeimdallFramework.Server when you want typed Bootstrap class helpers in server rendering code.

dotnet add package HeimdallFramework.Bootstrap

3. Basic Usage

Use Bootstrap helpers anywhere you would normally pass class names to an HTML builder.

FluentHtml.Div(row =>
{
    row.Class(
        Bootstrap.Layout.Row,
        Bootstrap.Spacing.Mb(3),
        Bootstrap.Spacing.Mt(3));

    row.Div(col =>
    {
        col.Class(Bootstrap.Layout.ColSpan(6, Bootstrap.Breakpoint.Md));
        col.P(p => p.Class(Bootstrap.Text.Lead)
                    .Text("Hello from Heimdall"));
    });
});

4. Direct Mapping

Every helper maps to the Bootstrap class you would have written by hand. That makes the output predictable and keeps debugging simple.

Bootstrap.Spacing.Mb(3)          -> "mb-3"
Bootstrap.Layout.ColSpan(6, Md)  -> "col-md-6"
Bootstrap.Btn.Primary            -> "btn-primary"
Bootstrap.Table.Hover            -> "table-hover"

5. Common Helper Areas

The package covers the common Bootstrap surface you tend to repeat in server-rendered UI.

Buttons:   Bootstrap.Btn.Base, Bootstrap.Btn.Primary
Forms:     Bootstrap.Form.Control, Bootstrap.Form.Select
Tables:    Bootstrap.Table.Base, Bootstrap.Table.Hover
Layout:    Bootstrap.Layout.Row, Bootstrap.Layout.Container
Spacing:   Bootstrap.Spacing.Mb(3), Bootstrap.Spacing.P(4)
Utilities: Bootstrap.Display.Flex, Bootstrap.Flex.AlignItemsCenter

6. Why It Exists

Bootstrap class strings are easy to mistype and hard to discover. Typed helpers give autocomplete and refactoring support while still leaving the final markup obvious.

Instead of:
div.Class("row mb-3 mt-3");

Prefer:
div.Class(
    Bootstrap.Layout.Row,
    Bootstrap.Spacing.Mb(3),
    Bootstrap.Spacing.Mt(3));

7. Composition Over Components

The Bootstrap package intentionally avoids large component abstractions. You still build the markup shape yourself, then apply typed Bootstrap classes to that shape.

card.Div(header =>
{
    header.Class(Bootstrap.Card.Header)
          .Text("Live Data");
});

card.Div(body =>
{
    body.Class(Bootstrap.Card.Body);
});

8. Heimdall Integration

Bootstrap helpers compose naturally with Heimdall behavior because both are just attributes and HTML content.

body.Class(Bootstrap.Card.Body)
    .Heimdall()
    .Sse("metrics-stream", "#metrics-body", HeimdallHtml.Swap.Inner);

button.Class(Bootstrap.Btn.Base, Bootstrap.Btn.Primary)
      .Heimdall()
      .Click("Orders.Refresh")
      .Target("#orders")
      .SwapInner();

9. What It Is Not

This package is deliberately small in concept. It does not hide HTML, own layout decisions, or create a second UI architecture.

Not a component framework
Not a replacement for Bootstrap
Not a CSS-in-C# styling engine
Not tied to a frontend framework

10. When to Use It

Use the helpers when you are already rendering HTML on the server and want Bootstrap classes to be discoverable, typed, and consistent.

Good fit:
- dashboards
- forms
- admin tools
- documentation pages
- server-rendered application shells

Next Steps

Once the typed class layer is clear, the next useful pages are the rendering inputs that produce HTML and the runtime layer that makes those boundaries interactive.