# Capstone: Hardening + Take-Home Extensions

// BEFORE: Repeated htmx detection
if (Request.Headers.TryGetValue("HX-Request", out var v) && v == "true")
{
    // ...
}

// AFTER: Use helper method consistently
if (IsHtmx())
{
    // ...
}

// BEFORE: Inline PartialViewResult construction
return new PartialViewResult
{
    ViewName = "Partials/_TaskList",
    ViewData = new ViewDataDictionary(ViewData) { Model = tasks }
};

// AFTER: Use helper method
return Fragment("Partials/_TaskList", tasks);

@*
    Fragment: _TaskList
    Target ID: #task-list
    Swap: outerHTML
    Returned by: OnGetList, OnPostCreate, OnPostDelete
*@
<div id="task-list">
    @* content *@
</div>

public class IndexModel : PageModel
{
    // ═══════════════════════════════════════════════════════════
    // Properties
    // ═══════════════════════════════════════════════════════════

    public IReadOnlyList<TaskItem> Tasks { get; private set; } = Array.Empty<TaskItem>();

    [BindProperty]
    public NewTaskInput Input { get; set; } = new();

    [TempData]
    public string? FlashMessage { get; set; }

    // ═══════════════════════════════════════════════════════════
    // Page Lifecycle
    // ═══════════════════════════════════════════════════════════

    public void OnGet(string? q, int page = 1, int pageSize = 5) { }

    // ═══════════════════════════════════════════════════════════
    // List Fragment Handlers
    // ═══════════════════════════════════════════════════════════

    public IActionResult OnGetList(string? q, int page = 1, int pageSize = 5) { }
    public IActionResult OnGetDetails(int id) { }

    // ═══════════════════════════════════════════════════════════
    // Form Fragment Handlers
    // ═══════════════════════════════════════════════════════════

    public IActionResult OnGetEmptyForm() { }
    public IActionResult OnPostCreate() { }
    public IActionResult OnPostValidateTitle() { }

    // ═══════════════════════════════════════════════════════════
    // Dynamic Form Handlers
    // ═══════════════════════════════════════════════════════════

    public IActionResult OnGetAddTag() { }
    public IActionResult OnGetRemoveTag() { }
    public IActionResult OnGetSubcategories([FromQuery(Name = "Input.Category")] string? category) { }

    // ═══════════════════════════════════════════════════════════
    // CRUD Handlers
    // ═══════════════════════════════════════════════════════════

    public IActionResult OnPostDelete(int id) { }

    // ═══════════════════════════════════════════════════════════
    // Background Job Handlers
    // ═══════════════════════════════════════════════════════════

    public IActionResult OnPostStartJob() { }
    public IActionResult OnGetJobStatus(string jobId) { }
    public IActionResult OnGetResetJob() { }

    // ═══════════════════════════════════════════════════════════
    // Message Handlers
    // ═══════════════════════════════════════════════════════════

    public IActionResult OnGetMessages() { }

    // ═══════════════════════════════════════════════════════════
    // Helper Methods
    // ═══════════════════════════════════════════════════════════

    private bool IsHtmx() =>
        Request.Headers.TryGetValue("HX-Request", out var v) && v == "true";

    private PartialViewResult Fragment(string partialName, object model) =>
        new()
        {
            ViewName = partialName,
            ViewData = new ViewDataDictionary(MetadataProvider, ModelState) { Model = model }
        };
}

# htmx + Razor Pages Conventions

## Fragment Rules

### Naming
- Partial files: `_PascalCase.cshtml` (underscore prefix)
- Fragment IDs: `#kebab-case` (lowercase, hyphens)
- Handlers: `OnGet{Resource}` / `OnPost{Action}`

### Structure
- Every fragment MUST have a stable wrapper element with an ID
- The wrapper ID MUST match the hx-target selector
- Fragments are self-contained (no dependencies on page layout)

### Example
```cshtml
@* Fragment: _TaskList *@
@* Target: #task-list *@
@* Swap: outerHTML *@
<div id="task-list">
    <!-- content -->
</div>

<input hx-post="?handler=ValidateField"
       hx-trigger="keyup changed delay:500ms"
       hx-target="#field-validation"
       hx-swap="outerHTML"
       hx-include="closest form" />

<form hx-post="?handler=Create"
      hx-target="#list"
      hx-swap="outerHTML">

if (IsHtmx())
{
    Response.Headers["HX-Retarget"] = "#messages";
    Response.Headers["HX-Reswap"] = "outerHTML";
    return Fragment("Partials/_Messages", errorMessage);
}

@if (Model.State == "running")
{
    <div hx-get="?handler=Status&id=@Model.Id"
         hx-trigger="every 1s"
         hx-target="#status"
         hx-swap="outerHTML">
        <!-- progress content -->
    </div>
}
else
{
    <div id="status">
        <!-- final content - no polling -->
    </div>
}

<!-- Primary fragment -->
<div id="primary-target">
    <!-- main content -->
</div>

<!-- Out-of-band fragment -->
<div id="secondary-target" hx-swap-oob="true">
    <!-- additional content -->
</div>

### 2.2 Quick Reference Card

Create a printable reference card:

```markdown
# htmx + Razor Pages Quick Reference

## Request → Handler → Response

## The Three Questions

1. **What triggers the request?** (hx-trigger)
2. **Where does the response go?** (hx-target + hx-swap)
3. **What does the server return?** (Fragment or Page)

## Common Patterns

| Pattern | Trigger | Target | Handler Returns |
|---------|---------|--------|-----------------|
| Refresh list | click | #list | _List |
| Submit form | submit | #list | _List (or _Form on error) |
| Validate field | keyup delay:500ms | #field-error | _FieldValidation |
| Load details | click | #details | _Details |
| Delete item | click + confirm | #list | _List |
| Poll status | every 1s | #status | _Status |
| Add row | click | #container beforeend | _Row |
| Cascade dropdown | change | #child-select | _ChildOptions |

## Debugging Checklist

1. Network tab: Is request firing?
2. Request URL: Does handler match?
3. Response body: Is it HTML fragment?
4. Target exists: Is ID in DOM?
5. Swap strategy: Matches fragment structure?

@model RazorHtmxWorkshop.Models.TaskItem

@*
    Task Row Fragment (View Mode)
    =============================

    Purpose: Display a single task in the list
    Swap target: #task-row-{id}

    Design: Clicking Edit fetches the edit form for this row
*@

<li class="list-group-item" id="task-row-@Model.Id">
    <div class="d-flex justify-content-between align-items-center">
        <div>
            <strong>@Model.Title</strong>
            <span class="text-muted small ms-2">
                Created @Model.CreatedUtc.ToLocalTime().ToString("g")
            </span>
        </div>
        <div class="btn-group btn-group-sm">
            <button type="button"
                    class="btn btn-outline-secondary"
                    hx-get="?handler=EditRow&id=@Model.Id"
                    hx-target="#task-row-@Model.Id"
                    hx-swap="outerHTML">
                Edit
            </button>
            <button type="button"
                    class="btn btn-outline-danger"
                    hx-post="?handler=Delete"
                    hx-vals='{"id": @Model.Id}'
                    hx-confirm="Delete this task?"
                    hx-target="#task-list"
                    hx-swap="outerHTML">
                Delete
            </button>
        </div>
    </div>
</li>

@model RazorHtmxWorkshop.Models.TaskItem

@*
    Task Row Fragment (Edit Mode)
    =============================

    Purpose: Inline edit form for a single task
    Swap target: #task-row-{id}

    Design: Save updates the task and returns view mode
            Cancel returns view mode without changes
*@

<li class="list-group-item" id="task-row-@Model.Id">
    <form hx-post="?handler=UpdateRow"
          hx-target="#task-row-@Model.Id"
          hx-swap="outerHTML"
          class="d-flex gap-2 align-items-center">

        @Html.AntiForgeryToken()
        <input type="hidden" name="id" value="@Model.Id" />

        <input type="text"
               name="title"
               value="@Model.Title"
               class="form-control form-control-sm"
               required
               autofocus />

        <div class="btn-group btn-group-sm">
            <button type="submit" class="btn btn-primary">
                Save
            </button>
            <button type="button"
                    class="btn btn-outline-secondary"
                    hx-get="?handler=CancelEdit&id=@Model.Id"
                    hx-target="#task-row-@Model.Id"
                    hx-swap="outerHTML">
                Cancel
            </button>
        </div>
    </form>
</li>

/// <summary>
/// Returns the edit form for a specific row.
/// </summary>
public IActionResult OnGetEditRow(int id)
{
    var task = InMemoryTaskStore.Find(id);
    if (task is null)
    {
        return Content("<li class='list-group-item text-danger'>Task not found</li>", "text/html");
    }

    return Fragment("Partials/_TaskRowEdit", task);
}

/// <summary>
/// Updates a task and returns the view mode row.
/// </summary>
public IActionResult OnPostUpdateRow(int id, string title)
{
    var task = InMemoryTaskStore.Find(id);
    if (task is null)
    {
        return Content("<li class='list-group-item text-danger'>Task not found</li>", "text/html");
    }

    if (string.IsNullOrWhiteSpace(title) || title.Length < 3)
    {
        // Return edit form with error
        return Fragment("Partials/_TaskRowEdit", task);
    }

    // Update the task
    InMemoryTaskStore.Update(id, title.Trim());
    task = InMemoryTaskStore.Find(id)!;

    return Fragment("Partials/_TaskRow", task);
}

/// <summary>
/// Cancels editing and returns the view mode row.
/// </summary>
public IActionResult OnGetCancelEdit(int id)
{
    var task = InMemoryTaskStore.Find(id);
    if (task is null)
    {
        return Content("<li class='list-group-item text-danger'>Task not found</li>", "text/html");
    }

    return Fragment("Partials/_TaskRow", task);
}

public static void Update(int id, string newTitle)
{
    var task = _tasks.FirstOrDefault(t => t.Id == id);
    if (task is not null)
    {
        task.Title = newTitle;
    }
}

/* ═══════════════════════════════════════════════════════════════
   Optimistic UI - Button States
   ═══════════════════════════════════════════════════════════════ */

/* Disable buttons during htmx requests */
button.htmx-request,
.htmx-request button {
    pointer-events: none;
    opacity: 0.65;
    cursor: not-allowed;
}

/* Hide button text during request */
button.htmx-request .btn-text {
    visibility: hidden;
}

/* Show spinner during request */
button .btn-spinner {
    display: none;
}

button.htmx-request .btn-spinner {
    display: inline-block;
    position: absolute;
    left: 50%;
    transform: translateX(-50%);
}

/* Button needs relative positioning for spinner */
button.btn-loading {
    position: relative;
}

/* ═══════════════════════════════════════════════════════════════
   Optimistic UI - Form States
   ═══════════════════════════════════════════════════════════════ */

/* Dim form during submission */
form.htmx-request {
    opacity: 0.7;
    pointer-events: none;
}

/* ═══════════════════════════════════════════════════════════════
   Optimistic UI - List Item States
   ═══════════════════════════════════════════════════════════════ */

/* Highlight newly added items */
.list-group-item.htmx-added {
    animation: highlight-new 1s ease-out;
}

@keyframes highlight-new {
    from {
        background-color: rgba(25, 135, 84, 0.2);
    }
    to {
        background-color: transparent;
    }
}

/* Fade items being deleted */
.list-group-item.htmx-swapping {
    opacity: 0;
    transition: opacity 200ms ease-out;
}

<button type="submit" class="btn btn-primary btn-loading">
    <span class="btn-text">Add Task</span>
    <span class="btn-spinner spinner-border spinner-border-sm" role="status">
        <span class="visually-hidden">Loading...</span>
    </span>
</button>

<button type="button"
        class="btn btn-sm btn-outline-danger btn-loading"
        hx-post="?handler=Delete"
        hx-vals='{"id": @task.Id}'
        hx-confirm="Delete this task?"
        hx-target="#task-list"
        hx-swap="outerHTML">
    <span class="btn-text">Delete</span>
    <span class="btn-spinner spinner-border spinner-border-sm" role="status"></span>
</button>

<!-- In _Layout.cshtml, after htmx script -->
<script src="https://unpkg.com/htmx-ext-sse@2.2.1/sse.js"></script>

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.RazorPages;

namespace RazorHtmxWorkshop.Pages.Tasks;

public class TaskEventsModel : PageModel
{
    /// <summary>
    /// SSE endpoint for task updates.
    /// Sends events when tasks change.
    /// </summary>
    public async Task OnGetAsync(CancellationToken cancellationToken)
    {
        Response.ContentType = "text/event-stream";
        Response.Headers["Cache-Control"] = "no-cache";
        Response.Headers["Connection"] = "keep-alive";

        // In production: subscribe to a message bus or change feed
        // For demo: send heartbeat every 5 seconds

        try
        {
            while (!cancellationToken.IsCancellationRequested)
            {
                // Check for changes (in production: use proper event source)
                var hasChanges = TaskChangeTracker.HasChanges();

                if (hasChanges)
                {
                    // Send event that triggers list refresh
                    await Response.WriteAsync($"event: taskListChanged\n");
                    await Response.WriteAsync($"data: refresh\n\n");
                    await Response.Body.FlushAsync(cancellationToken);

                    TaskChangeTracker.ClearChanges();
                }

                // Heartbeat to keep connection alive
                await Response.WriteAsync($": heartbeat\n\n");
                await Response.Body.FlushAsync(cancellationToken);

                await Task.Delay(5000, cancellationToken);
            }
        }
        catch (OperationCanceledException)
        {
            // Client disconnected
        }
    }
}

/// <summary>
/// Simple change tracker for demo purposes.
/// In production, use a proper event bus.
/// </summary>
public static class TaskChangeTracker
{
    private static bool _hasChanges = false;
    private static readonly object _lock = new();

    public static void NotifyChange()
    {
        lock (_lock) { _hasChanges = true; }
    }

    public static bool HasChanges()
    {
        lock (_lock) { return _hasChanges; }
    }

    public static void ClearChanges()
    {
        lock (_lock) { _hasChanges = false; }
    }
}

<!-- In Index.cshtml, wrap the list in SSE container -->
<div hx-ext="sse" sse-connect="/Tasks/TaskEvents">
    <div id="task-list"
         sse-swap="taskListChanged"
         hx-get="?handler=List"
         hx-trigger="sse:taskListChanged"
         hx-target="#task-list"
         hx-swap="outerHTML">
        @* list content *@
    </div>
</div>

// In OnPostCreate, OnPostDelete, etc.
public IActionResult OnPostCreate()
{
    // ... existing code ...

    // Notify SSE listeners
    TaskChangeTracker.NotifyChange();

    // ... return fragment ...
}

using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.Filters;

public class HtmxAuthorizeAttribute : ActionFilterAttribute
{
    public override void OnActionExecuting(ActionExecutingContext context)
    {
        var user = context.HttpContext.User;

        if (!user.Identity?.IsAuthenticated ?? true)
        {
            var isHtmx = context.HttpContext.Request.Headers
                .TryGetValue("HX-Request", out var v) && v == "true";

            if (isHtmx)
            {
                // For htmx: return 401 with redirect header
                context.HttpContext.Response.StatusCode = 401;
                context.HttpContext.Response.Headers["HX-Redirect"] = "/Identity/Account/Login";
                context.Result = new EmptyResult();
            }
            else
            {
                // For regular requests: redirect normally
                context.Result = new RedirectToPageResult("/Identity/Account/Login");
            }

            return;
        }

        base.OnActionExecuting(context);
    }
}

private IActionResult? CheckPermission(int taskId, string requiredPermission)
{
    // Example: Check if user can modify this task
    var canModify = /* your permission logic */;

    if (!canModify)
    {
        if (IsHtmx())
        {
            Response.StatusCode = 403;
            Response.Headers["HX-Retarget"] = "#messages";
            Response.Headers["HX-Reswap"] = "outerHTML";
            return Fragment("Partials/_Messages", "You don't have permission to modify this task.");
        }

        return Forbid();
    }

    return null; // Permission granted
}

// Usage in handler:
public IActionResult OnPostDelete(int id)
{
    var permissionResult = CheckPermission(id, "delete");
    if (permissionResult is not null) return permissionResult;

    // ... proceed with delete ...
}

// In site.js or inline script
document.body.addEventListener('htmx:responseError', function(event) {
    if (event.detail.xhr.status === 401) {
        // Session expired - redirect to login
        window.location.href = '/Identity/Account/Login';
    }
});

// In site.js
document.addEventListener('DOMContentLoaded', function() {
    // Global shortcuts
    document.addEventListener('keydown', function(e) {
        // Ctrl+N: Focus new task input
        if (e.ctrlKey && e.key === 'n') {
            e.preventDefault();
            document.querySelector('#title')?.focus();
        }

        // Escape: Clear form
        if (e.key === 'Escape') {
            const form = document.querySelector('#task-form form');
            if (form) {
                form.reset();
                document.querySelector('#title')?.blur();
            }
        }

        // Ctrl+Enter: Submit form
        if (e.ctrlKey && e.key === 'Enter') {
            const form = document.querySelector('#task-form form');
            if (form && document.activeElement?.closest('#task-form')) {
                htmx.trigger(form, 'submit');
            }
        }
    });
});

<div class="small text-muted mt-2">
    <kbd>Ctrl</kbd>+<kbd>N</kbd> New task |
    <kbd>Ctrl</kbd>+<kbd>Enter</kbd> Submit |
    <kbd>Esc</kbd> Clear
</div>

┌─────────────────────────────────────────────────────────────┐
│                         Browser                              │
│  ┌─────────┐    htmx     ┌─────────┐    htmx     ┌───────┐ │
│  │ Trigger │ ──────────► │ Request │ ◄────────── │ Swap  │ │
│  │ (click) │             │ (POST)  │             │ (DOM) │ │
│  └─────────┘             └────┬────┘             └───┬───┘ │
│                               │                       ▲     │
└───────────────────────────────┼───────────────────────┼─────┘
                                │                       │
                                ▼                       │
┌───────────────────────────────┼───────────────────────┼─────┐
│                               │        Server         │     │
│  ┌─────────┐    Razor    ┌────┴────┐    Razor    ┌───┴───┐ │
│  │ Handler │ ──────────► │ Partial │ ◄────────── │ Model │ │
│  │ (C#)    │             │ (HTML)  │             │ (C#)  │ │
│  └─────────┘             └─────────┘             └───────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Choose ONE feature to enhance:
├── A simple list with add/remove
├── A form with inline validation
├── A details panel or modal
└── A filter/search component

Goal: Learn the pattern in isolation

Document your patterns:
├── Create fragment naming conventions
├── Define response rules
├── Set up helper methods
└── Build a style guide

Goal: Consistency across features

Apply to more features:
├── Convert existing AJAX to htmx
├── Add real-time validation
├── Implement polling where needed
└── Add OOB swaps for notifications

Goal: htmx becomes the default approach

Optimize and enhance:
├── SSE for live updates
├── Optimistic UI
├── Offline support
└── Performance tuning

Goal: Polish and production-ready