Files

T

john-okeefe 79d10b5b37 docs: add theme fix and admin sidebar implementation plans

- Add THEME_FIX_PLAN.md: comprehensive plan for theme system consistency
- Add ADMIN_SIDEBAR_PLAN.md: reusable admin sidebar component plan
- Add WOOD_PANELING_PLAN.md: wood paneling and full-width layout plan

2026-02-24 10:24:05 -05:00

9.3 KiB

Raw Blame History

Admin Panel Sidebar Reusable Component Plan

Problem Statement

The admin panel sidebar is currently implemented with code duplication and inconsistencies:

Current Issues

Code Duplication: Sidebar markup is duplicated across templates:
- admin.templ (lines 17-32)
- admin_library.templ (lines 14-29)
Inconsistent Navigation Links:
- admin.templ: Dashboard → "User Administration" → Library Management
- admin_library.templ: Dashboard → "Profile Settings" → Library Management
- "Profile Settings" link points to /admin/profile (doesn't exist)
- "User Administration" link points to /admin/users (correct)
Missing Sidebar: admin_users.templ has no sidebar at all - only uses main @Header component
Inconsistent Layouts:
- admin.templ & admin_library.templ: Full sidebar layout with <aside> + <main> in flex container
- admin_users.templ: Regular layout without sidebar, just @Header + <main>

Root Cause

Each admin template implements its own sidebar inline instead of using a shared component, leading to:

Maintenance burden (changes require updating multiple files)
Inconsistency (different links, different styling)
Missing features (admin_users has no sidebar)

Solution Strategy

Create a reusable AdminSidebar component that:

Can be included in all admin pages with a single line
Accepts user and currentPath parameters
Automatically highlights the active page
Provides consistent, maintainable navigation

Implementation Plan

Phase 1: Create AdminSidebar Component

New file: templates/admin_sidebar.templ

package templates

templ AdminSidebar(user User, currentPath string) {
	<aside class="w-64 border-r" style="background-color: var(--bg-secondary); border-color: var(--border)">
		<div class="p-6">
			<h2 class="text-lg font-semibold mb-6" style="color: var(--text-primary)">Admin Panel</h2>
			<nav class="space-y-2">
				<a href="/admin"
				   class={"block px-4 py-2 rounded-lg " +
					   ("bg-accent text-bg-primary" if currentPath == "/admin" else "hover:opacity-80")}
				   style="color: var(--text-primary)">
					🏠 Dashboard
				</a>
				<a href="/admin/users"
				   class={"block px-4 py-2 rounded-lg " +
					   ("bg-accent text-bg-primary" if currentPath == "/admin/users" else "hover:opacity-80")}
				   style="color: var(--text-primary)">
					👤 User Administration
				</a>
				<a href="/admin/library"
				   class={"block px-4 py-2 rounded-lg " +
					   ("bg-accent text-bg-primary" if currentPath == "/admin/library" else "hover:opacity-80")}
				   style="color: var(--text-primary)">
					📚 Library Management
				</a>
			</nav>
		</div>
	</aside>
}

Key Features:

Single source of truth for admin navigation
Dynamic active state highlighting based on currentPath
Consistent link labels and destinations
Icon + text format for clarity
No code duplication

Phase 2: Update admin.templ

File: templates/admin.templ

Replace sidebar section (lines 17-32) with component call:

Before:

<aside class="w-64 border-r" style="background-color: var(--bg-secondary); border-color: var(--border)">
    <div class="p-6">
        <h2 class="text-lg font-semibold mb-6" style="color: var(--text-primary)">Admin Panel</h2>
        <nav class="space-y-2">
            <a href="/admin" class="block px-4 py-2 rounded-lg bg-accent text-bg-primary" style="color: var(--text-primary)">
                🏠 Dashboard
            </a>
            <a href="/admin/users" class="block px-4 py-2 rounded-lg hover:opacity-80" style="color: var(--text-primary)">
				👤 User Administration
			</a>
            <a href="/admin/library" class="block px-4 py-2 rounded-lg hover:opacity-80" style="color: var(--text-primary)">
                📚 Library Management
            </a>
        </nav>
    </div>
</aside>

After:

@AdminSidebar(user, "/admin")

Also update theme on line 13:

<body class="theme-{ user.Theme }">

Phase 3: Update admin_library.templ

File: templates/admin_library.templ

Replace sidebar section (lines 14-29) with component call:

Before:

<aside class="w-64 border-r" style="background-color: var(--bg-secondary); border-color: var(--border)">
    <div class="p-6">
        <h2 class="text-lg font-semibold mb-6" style="color: var(--text-primary)">Admin Panel</h2>
        <nav class="space-y-2">
            <a href="/admin" class="block px-4 py-2 rounded-lg hover:opacity-80" style="color: var(--text-primary)">
                🏠 Dashboard
            </a>
            <a href="/admin/profile" class="block px-4 py-2 rounded-lg hover:opacity-80" style="color: var(--text-primary)">
                👤 Profile Settings
            </a>
            <a href="/admin/library" class="block px-4 py-2 rounded-lg bg-accent text-bg-primary" style="color: var(--text-primary)">
                📚 Library Management
            </a>
        </nav>
    </div>
</aside>

After:

@AdminSidebar(user, "/admin/library")

Phase 4: Add Sidebar to admin_users.templ

File: templates/admin_users.templ

Current state: Page has no sidebar, just @Header and <main>

Add sidebar layout wrapper:

Before:

<body class="theme-{ currentUser.Theme }">
    @Header(currentUser, "/admin/users")

    <!-- Modal Container -->
    <div id="modal-container"></div>

    <main class="max-w-7xl mx-auto px-4 py-8">

After:

<body class="theme-{ currentUser.Theme }">
    @Header(currentUser, "/admin/users")

    <!-- Modal Container -->
    <div id="modal-container"></div>

    <div class="flex min-h-screen" style="background-color: var(--bg-primary)">
        @AdminSidebar(currentUser, "/admin/users")

        <main class="flex-1 p-8">
            <div class="max-w-7xl">

Also need to close the new div wrapper at the end of the file (before closing </body>):

            </div>
        </main>
    </div>

Phase 5: Fix Layout Inconsistency in admin_users.templ

File: templates/admin_users.templ

Remove max-width and padding from main element (now handled by sidebar layout):

Current line 21:

<main class="max-w-7xl mx-auto px-4 py-8">

Change to:

<main class="flex-1 p-8">
    <div class="max-w-7xl">

This wraps the content in a max-width container to match other admin pages.

DECISION: Use exact links from admin.templ

The AdminSidebar component will use the same 3 navigation links as admin.templ:

🏠 Dashboard → /admin
👤 User Administration → /admin/users
📚 Library Management → /admin/library

Rationale:

These links already exist and work correctly
Consistent with current admin.templ implementation
"Profile Settings" link in admin_library.templ pointed to non-existent /admin/profile
Clean, functional navigation without broken links

Benefits of This Approach

Maintainability: Update sidebar in one place, all pages benefit
Consistency: All admin pages have identical navigation
Active States: Automatic highlighting of current page
DRY Principle: No code duplication
Scalability: Easy to add new admin pages - just include component
User Experience: Clear visual indication of current location

Testing Checklist

After implementation:

Visit /admin → Dashboard link highlighted
Visit /admin/users → User Administration link highlighted
Visit /admin/library → Library Management link highlighted
Click each link → navigates to correct page
All three pages have consistent sidebar appearance
admin_users page now has sidebar (previously missing)
No broken links (removed /admin/profile)
Hover states work on all links
Active state has different styling (bg-accent)
Layout consistent across all admin pages
Templates compile successfully

Files Summary

New Files Created

templates/admin_sidebar.templ - Reusable admin sidebar component

Files Modified

templates/admin.templ - Replace inline sidebar with component, fix theme
templates/admin_library.templ - Replace inline sidebar with component
templates/admin_users.templ - Add sidebar (previously missing), fix layout wrapper

Migration Notes

Breaking Changes

None - purely refactoring, same functionality

Backward Compatibility

Full - all URLs and functionality remain the same

Database Dependencies

None

Performance

No impact - same HTML rendered, just defined once instead of duplicated

Rollback Plan

If issues arise:

Revert individual template changes
Delete admin_sidebar.templ
Each admin page returns to its previous standalone state
No data loss (purely visual component refactoring)

Future Improvements

Collapsible sidebar: Add toggle to hide/show sidebar
Badge notifications: Show counts (e.g., "3 pending users")
Dropdown menus: Group related admin functions
Permission-based links: Hide/show links based on user role
Breadcrumbs: Add breadcrumb navigation for admin section
Additional admin pages: Easy to extend - just include @AdminSidebar with new path

9.3 KiB Raw Blame History

Admin Panel Sidebar Reusable Component Plan

Problem Statement

Current Issues

Root Cause

Solution Strategy

Implementation Plan

Phase 1: Create AdminSidebar Component

Phase 2: Update admin.templ

Phase 3: Update admin_library.templ

Phase 4: Add Sidebar to admin_users.templ

Phase 5: Fix Layout Inconsistency in admin_users.templ

Navigation Links Decision

Benefits of This Approach

Testing Checklist

Files Summary

New Files Created

Files Modified

Migration Notes

Breaking Changes

Backward Compatibility

Database Dependencies

Performance

Rollback Plan

Future Improvements

9.3 KiB

Raw Blame History