From a830e0e2b9c1786d3c7bfec5de07ccdb59026e93 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Tue, 24 Feb 2026 21:33:45 -0500 Subject: [PATCH] docs: remove completed planning documents Remove outdated planning documents that have been implemented or are no longer relevant. All features have been completed and documented elsewhere. Removed Files: - THEME_FIX_PLAN.md - WOOD_PANELING_FONT_FIX_PLAN.md - WOOD_PANELING_PLAN.md Reason: - Wood paneling feature is complete and in production - Theme fixes have been implemented - Font color issues resolved - Documentation consolidated into TASKS-scanning-progress.md Migration: - See TASKS-scanning-progress.md for current implementation plans - Wood paneling is documented in code comments - Theme system is functional with multiple color schemes Impact: - Cleaner repository structure - Reduced documentation maintenance burden - Single source of truth for pending work --- THEME_FIX_PLAN.md | 217 ------- WOOD_PANELING_FONT_FIX_PLAN.md | 231 ------- WOOD_PANELING_PLAN.md | 1050 -------------------------------- 3 files changed, 1498 deletions(-) delete mode 100644 THEME_FIX_PLAN.md delete mode 100644 WOOD_PANELING_FONT_FIX_PLAN.md delete mode 100644 WOOD_PANELING_PLAN.md diff --git a/THEME_FIX_PLAN.md b/THEME_FIX_PLAN.md deleted file mode 100644 index 34ba1ed..0000000 --- a/THEME_FIX_PLAN.md +++ /dev/null @@ -1,217 +0,0 @@ -# Theme System Consistency Fix - -## Problem Statement - -When users change themes via the header dropdown, new pages do not consistently apply the selected theme. Some pages flash the wrong theme (tokyo-night) before applying the correct theme, creating a poor user experience. - -## Root Cause Analysis - -### Current Implementation - -**Two types of templates exist:** - -1. **Hardcoded theme templates** (problematic): - - `admin_library.templ` → `` - - `admin_users.templ` → `` - - `bookshelf.templ` → `` - - `index.templ` → `` - - `login.templ` → `` - - `register.templ` → `` - -2. **Dynamic theme templates** (working correctly): - - `dashboard.templ` → `` - - `analytics.templ` → `` - - `collections.templ` → `` - - `conflicts.templ` → `` - - `custom_section.templ` → `` - - `devices.templ` → `` - - `docs.templ` → `` - - `progress.templ` → `` - - `queue.templ` → `` - - `unlinked_books.templ` → `` - -### Why It Breaks - -1. Page loads with hardcoded `` -2. Browser renders initial paint with wrong theme -3. JavaScript (`theme.js`) loads from localStorage -4. JavaScript corrects the theme -5. **User sees flash of tokyo-night → selected theme** - -## Solution Strategy - -### Approach: Server-Side Rendering with Progressive Enhancement - -**Principle:** The server should always render the correct theme in the HTML to prevent flashes. JavaScript provides progressive enhancement for theme switching without page reloads. - -### Implementation Plan - -#### Phase 1: Update Authenticated Pages - -**Files to modify:** -- `templates/admin_library.templ` → `theme-{ user.Theme }` -- `templates/admin_users.templ` → `theme-{ currentUser.Theme }` (note: parameter is `currentUser`, not `user`) -- `templates/bookshelf.templ` → `theme-{ user.Theme }` - -**Change:** -```templ - - - - - - - - -``` - -**Requires:** Verify the correct parameter name in each template (`user` vs `currentUser`). - -#### Phase 2: Update Public Pages with Default Theme - -**Files to modify:** -- `templates/index.templ` -- `templates/login.templ` -- `templates/register.templ` - -- Use default theme since no user context -- Consider reading localStorage via inline JavaScript (progressive enhancement) - -```templ - - -``` - -#### Phase 3: Fix Wood Theme Persistence - -**Files to modify:** -- `web/src/theme.ts` - -**Problem:** Wood theme gradients are only applied in `changeThemeTo()` in `header.ts`, not in `applyTheme()` in `theme.ts`. - -**Solution:** Consolidate wood theme logic into `theme.ts` so it's consistently applied. - -**Add to `theme.ts`:** -```typescript -const applyTheme = (theme: string): void => { - // Handle wood themes with gradients - if (theme.startsWith('wood-')) { - document.body.className = `theme-${theme}`; - - let woodGradient = ''; - switch (theme) { - case 'wood-light': - woodGradient = 'linear-gradient(135deg, #deb887 0%, #d2a679 50%, #c9975b 100%)'; - break; - case 'wood-dark': - woodGradient = 'linear-gradient(135deg, #8b7355 0%, #6b5344 50%, #5a4636 100%)'; - break; - case 'wood-mahogany': - woodGradient = 'linear-gradient(135deg, #a0522d 0%, #8b4513 50%, #7a3c10 100%)'; - break; - default: - woodGradient = ''; - } - - document.body.style.background = woodGradient; - document.body.style.backgroundSize = 'cover'; - document.body.style.backgroundAttachment = 'fixed'; - } else { - // Apply regular theme - document.body.className = `theme-${theme}`; - document.body.style.background = ''; - document.body.style.backgroundSize = ''; - document.body.style.backgroundAttachment = ''; - } - - localStorage.setItem(THEME_STORAGE_KEY, theme); -}; -``` - -**Update `header.ts`:** -- Remove wood theme logic from `changeThemeTo()` -- Call `applyTheme()` from `theme.ts` instead -- Or consolidate wood theme logic into shared utility - -#### Phase 4: Consolidate Theme Functions - -**Problem:** Two separate theme-changing functions: -- `changeThemeTo()` in `header.ts` (handles wood themes) -- `changeTheme()` in `theme.ts` (doesn't handle wood themes) - -**Solution:** Create shared theme utilities - -**Option A:** Move everything to `theme.ts` -- Export `applyTheme()` to window -- Update header to use `window.applyTheme()` - -**Option B:** Create shared theme utility module -- `web/src/themeUtils.ts` with all theme logic -- Both `header.ts` and `theme.ts` import it - -**Recommendation:** Option A (simpler, fewer files) - -## Testing Checklist - -After implementation: - -- [ ] Navigate to `/admin/library` with dracula theme → No flash, loads correctly -- [ ] Navigate to `/admin/users` with nord theme → No flash, loads correctly -- [ ] Navigate to `/bookshelf` with catppuccin-mocha theme → No flash, loads correctly -- [ ] Logout → Visit `/` → Uses tokyyo-night default -- [ ] Login → Visit `/dashboard` → Uses saved theme -- [ ] Change to wood-dark → Navigate to new page → Wood gradient persists -- [ ] Change to wood-light → Navigate to new page → Wood gradient persists -- [ ] Change from wood-dark to dracula → Navigate to new page → Dracula loads correctly -- [ ] Test all theme options across all pages - -## Files Summary - -### Template Changes (Phase 1 & 2) -- `templates/admin_library.templ` -- `templates/admin_users.templ` -- `templates/bookshelf.templ` -- `templates/index.templ` -- `templates/login.templ` -- `templates/register.templ` - -### TypeScript Changes (Phase 3 & 4) -- `web/src/theme.ts` - Add wood theme logic to `applyTheme()` -- `web/src/header.ts` - Simplify `changeThemeTo()` or remove -- Potential: `web/src/themeUtils.ts` - New shared utilities (Phase 4) - -## Migration Notes - -1. **Breaking Changes:** None - purely additive/fixes - -2. **Backward Compatibility:** Full - localStorage still works as fallback - -3. **Database Dependencies:** Requires `user.Theme` field to be populated (already exists) - -4. **Performance:** Improves perceived performance (no theme flash) - -5. **Progressive Enhancement:** Public pages still work if JavaScript fails (default theme) - -## Rollback Plan - -If issues arise: -1. Revert template changes -2. JavaScript theme loading will still work (flash remains but functional) -3. No data loss (theme saved in database and localStorage) - -## Future Improvements - -1. **Theme preview:** Show theme preview before applying -2. **Custom themes:** Allow users to create custom themes -3. **Theme persistence:** Remember theme per device (mobile vs desktop) -4. **System preference:** Detect OS dark mode preference -5. **High contrast mode:** Add accessibility-focused themes diff --git a/WOOD_PANELING_FONT_FIX_PLAN.md b/WOOD_PANELING_FONT_FIX_PLAN.md deleted file mode 100644 index adb252a..0000000 --- a/WOOD_PANELING_FONT_FIX_PLAN.md +++ /dev/null @@ -1,231 +0,0 @@ -# Wood Paneling Smart Font Colors Fix Plan - -## Overview - -Add smart font colors for wood paneling backgrounds on the dashboard. When a wood texture is applied to `#collections-container`, the text color will automatically adjust to ensure readability. - -## Current State - -- Textures exist: `wood-light.png`, `wood-dark.png`, `wood-mahogany.png` -- **Issue**: Current `wood-mahogany.png` is too light (should be darkest) -- **Issue**: Current `wood-dark.png` may also need replacement (verify brightness) -- Wood paneling applies background to `#collections-container` -- Text colors currently use theme CSS variables (`var(--text-primary)`, `var(--text-secondary)`) -- Problem: Theme-based text colors may not contrast well with wood textures - -## Requirements - -1. **Keep existing naming**: `wood-light`, `wood-dark`, `wood-mahogany` (no renaming needed) -2. **Verify texture brightness**: Mahogany must be darkest, dark is medium, light is lightest (DO NOT change wood-light) -3. **Smart font colors**: Dark wood needs light text, light wood needs dark text -4. **Scope**: All text within `#collections-container` when wood is active -5. **Fallback**: When no wood is selected, use theme colors (current behavior) - -## Implementation Plan - -### Step 0: Verify and Replace Mahogany Texture - -The current `wood-mahogany.png` is too light and needs to be replaced with the darkest texture from the source pack. **DO NOT change `wood-light.png`.** - -**Download and extract texture pack:** -```bash -cd /tmp -curl -O https://opengameart.org/sites/default/files/wood_0.zip -unzip wood_0.zip -cd wood_0 -ls -la # Should show wood1.png, wood2.png, etc. -``` - -**Rename extracted textures:** -```bash -# From /tmp/wood_0, copy to bookhoard textures directory -cd web/static/textures -cp /tmp/wood_0/wood1.png wood-dark.png - -# wood2.png → wood-mahogany (darkest) -cp /tmp/wood_0/wood2.png wood-mahogany.png - -# wood-light.png remains unchanged (keep existing file) - -# Verify -ls -lh web/static/textures/ -``` - -**Brightness validation checklist:** -- [ ] `wood-dark` (was wood1.png) is medium-dark brown -- [ ] `wood-mahogany` (was wood2.png) is the darkest, deep reddish-brown -- [ ] `wood-light` remains unchanged (lightest) - -### Step 1: Update `woodPaneling.ts` - -Add `data-wood` attribute to the container when applying backgrounds. This allows CSS selectors to target wood-specific styling. - -**File**: `web/src/woodPaneling.ts` - -**Change 1** - In `applyWoodPaneling()` function, remove wood classes and data attribute: -```typescript -// Before: -container.classList.remove('bg-wood-light', 'bg-wood-dark', 'bg-wood-mahogany'); - -// After: -container.classList.remove('bg-wood-light', 'bg-wood-dark', 'bg-wood-mahogany'); -container.removeAttribute('data-wood'); -``` - -**Change 2** - In `applyWoodPaneling()` function, add wood class and data attribute: -```typescript -// Before: -if (paneling !== 'none') { - container.classList.add(`bg-${paneling}`); -} - -// After: -if (paneling !== 'none') { - container.classList.add(`bg-${paneling}`); - container.setAttribute('data-wood', paneling); -} -``` - -### Step 2: Update `woodPanelingInit.ts` - -Apply the same `data-wood` attribute during early initialization to prevent flash. - -**File**: `web/src/woodPanelingInit.ts` - -**Change** - In `applyPaneling()` function, add data-wood attribute: -```typescript -// Before: -const applyPaneling = () => { - const container = document.getElementById('collections-container'); - if (container) { - container.classList.add(`bg-${woodPaneling}`); - } -}; - -// After: -const applyPaneling = () => { - const container = document.getElementById('collections-container'); - if (container) { - container.classList.add(`bg-${woodPaneling}`); - container.setAttribute('data-wood', woodPaneling); - } -}; -``` - -### Step 3: Add Smart Font Color CSS - -Add CSS variables and selectors for each wood type in `input.css`. - -**File**: `web/static/input.css` - -**Add to `@layer components` section** - Add after the `.bg-wood-inactive` rule (around line 207-208), before the closing `}` of @layer components: - -```css -/* Smart text colors for wood paneling backgrounds */ -/* Wood Light - needs dark text for contrast */ -#collections-container[data-wood="wood-light"] { - --wood-text-primary: #1a1a1a; - --wood-text-secondary: #4a4a4a; - --wood-border: #2a2a2a; -} - -/* Wood Dark - needs medium text */ -#collections-container[data-wood="wood-dark"] { - --wood-text-primary: #d0d0d0; - --wood-text-secondary: #a0a0a0; - --wood-border: #5a4a3a; -} - -/* Wood Mahogany - needs light text (darkest background) */ -#collections-container[data-wood="wood-mahogany"] { - --wood-text-primary: #f5f5f5; - --wood-text-secondary: #c0c0c0; - --wood-border: #5c3317; -} - -/* Apply wood-specific text colors to all text within collections container */ -#collections-container[data-wood] h1, -#collections-container[data-wood] h2, -#collections-container[data-wood] h3, -#collections-container[data-wood] p, -#collections-container[data-wood] span, -#collections-container[data-wood] a, -#collections-container[data-wood] button { - color: var(--wood-text-primary) !important; -} - -#collections-container[data-wood] .text-sm, -#collections-container[data-wood] .text-secondary, -#collections-container[data-wood] p.text-sm { - color: var(--wood-text-secondary) !important; -} - -/* Preserve accent color for links */ -#collections-container[data-wood] a[style*="accent"] { - color: var(--accent) !important; -} - -/* Add subtle borders to book cards on wood backgrounds */ -#collections-container[data-wood] .book-card { - border: 1px solid var(--wood-border); -} -``` - -### Step 4: Build and Verify - -Run build commands to verify changes compile correctly. - -```bash -# Build CSS first (regenerates style.css with new utilities) -npm run build:css - -# Then build TypeScript -npm run build:ts - -# Verify Go templates compile -go build ./... -``` - -## Files Modified - -| File | Changes | -|------|---------| -| `web/static/textures/wood-dark.png` | Rename from extracted wood1.png | -| `web/static/textures/wood-mahogany.png` | Rename from extracted wood2.png | -| `web/static/textures/wood-light.png` | **DO NOT CHANGE** | -| `web/src/woodPaneling.ts` | Add/remove `data-wood` attribute | -| `web/src/woodPanelingInit.ts` | Add `data-wood` attribute | -| `web/static/input.css` | Add smart font color CSS | - -## Testing Checklist - -### Texture Verification -- [ ] Mahogany is visibly the darkest of all three textures -- [ ] Wood-dark is medium brightness -- [ ] Wood-light is lightest (unchanged) -- [ ] All textures are PNG format - -### Font Color Testing - -- [ ] `wood-light` shows dark text (#1a1a1a) -- [ ] `wood-dark` shows light text (#d0d0d0) -- [ ] `wood-mahogany` shows light text (#f5f5f5) -- [ ] "None" option uses theme colors (no `data-wood` attribute) -- [ ] Book cards have subtle borders on wood backgrounds -- [ ] "View All" links preserve accent color -- [ ] No console errors - -## Wood Brightness Reference - -| Source File | Target File | Brightness | Text Color | -|------------|-------------|------------|------------| -| `wood-light.png` | `wood-light.png` | Lightest | Dark (#1a1a1a) | **DO NOT CHANGE** | -| `wood1.png` | `wood-dark.png` | Medium | Medium (#d0d0d0) | -| `wood2.png` | `wood-mahogany.png` | **Darkest** | Light (#f5f5f5) | - -## Notes - -- The `data-wood` attribute is only present when a wood option is selected -- Absence of `data-wood` attribute means theme colors apply (no breaking change) -- CSS `!important` is used to override theme CSS variables within the selector scope -- Book card borders help separate content from wood texture diff --git a/WOOD_PANELING_PLAN.md b/WOOD_PANELING_PLAN.md deleted file mode 100644 index 8c6a647..0000000 --- a/WOOD_PANELING_PLAN.md +++ /dev/null @@ -1,1050 +0,0 @@ -# Wood Paneling & Full-Width Layout Implementation - -## Problem Statement - -The current "wood themes" were implemented as color themes with CSS gradients, but they should be wood paneling textures applied to the dashboard bookshelf background only. Additionally, the app uses constrained width containers (`max-w-7xl`) which limit screen real estate on large monitors, unlike modern bookshelf apps like Audiobookshelf. - -## Implementation Principles - -### Critical Requirements -- ✅ **All JavaScript must be TypeScript** - No inline scripts (use separate .ts files) -- ✅ **Use TailwindCSS only** - No custom CSS, use CSS variables already defined in `input.css` -- ✅ **Post-edit verification mandatory** - Run build after each file edit -- ✅ **Sequential git commits** - No `&&` chaining, explicit verification between commands -- ✅ **Document user-facing changes** - Update `docs/user/` for new features - -## Root Cause Analysis - -### Current Implementation Issues - -1. **Wood themes are misimplemented:** - - Wood themes (`wood-light`, `wood-dark`, `wood-mahogany`) are in the theme dropdown alongside color themes - - Applied via CSS gradients in `header.ts` `changeThemeTo()` - - Gradients applied to entire `` instead of just bookshelf background - - Not integrated with `theme.ts` `applyTheme()` function - -2. **Constrained layout:** - - Header uses `max-w-7xl mx-auto` container - - Dashboard content uses `max-w-7xl mx-auto` container - - Other pages use `max-w-7xl mx-auto` containers - - Wastes horizontal space on large monitors - -3. **No active indicators:** - - Theme dropdown doesn't show which theme/wood option is currently active - - Users can't tell what's selected without remembering - -## Solution Strategy - -### Approach: Separate Concerns - -**Principle:** Wood paneling is a visual treatment for the bookshelf, not a color theme. It should be: -- Separate from color themes -- Applied only to `#collections-container` on dashboard -- Stored in localStorage (not database) -- User-selectable from theme dropdown (but sectioned separately) - -**Layout principle:** Full-width layout for modern app feel, better space utilization. - -**CSS Variable Principle:** Use CSS variables already defined in `web/static/input.css` (`--bg-primary`, `--bg-secondary`, etc.) instead of inline styles. - -## Git Commit Strategy - -**CRITICAL:** All git commands must be run sequentially (no `&&` chaining): -1. `git add ` - Wait for completion -2. `git commit -m ""` - Wait for completion -3. Verify commit succeeded before proceeding - -**Post-Edit Verification (MANDATORY):** -- After each file edit: Run `go build ./...` for Go files, `npm run build:ts` for TypeScript -- Review `git diff` to verify only intended changes -- Never proceed to next file until current edit compiles successfully - -## Implementation Plan - -### Phase 0: Download Wood Textures (Manual) - -**Source URLs:** - -1. **Light Wood:** https://opengameart.org/content/light-wood-1024x1024 - - Author: qubodup - - License: CC0 (no attribution required) - - File: qubodup-light_wood.png (1.9 MB) - - Resolution: 1024x1024 - -2. **Dark & Mahogany Wood:** https://opengameart.org/content/5-wood-textures - - Author: Luke.RUSTLTD - - License: CC0 (no attribution required) - - File: wood_0.zip (6.5 MB) - contains 5 textures - - Select 2 best: darkest and medium/reddish - - Resolution: Likely 512x512 or 1024x1024 - -**Download Steps:** - -```bash -# Create textures directory -mkdir -p web/static/textures - -# Download light wood -cd web/static/textures -curl -O https://opengameart.org/sites/default/files/qubodup-light_wood.png -mv qubodup-light_wood.png wood-light.png - -# Download texture pack (dark & mahogany) -cd /tmp -curl -O https://opengameart.org/sites/default/files/wood_0.zip -unzip wood_0.zip - -# Select and copy best 2 textures (you'll need to review and choose) -# Copy selected ones to web/static/textures/wood-dark.png -# Copy selected ones to web/static/textures/wood-mahogany.png -``` - -**Manual Steps:** -1. Extract `wood_0.zip` -2. Review the 5 textures -3. Select darkest → rename to `wood-dark.png` -4. Select medium/reddish → rename to `wood-mahogany.png` -5. Move both to `web/static/textures/` - -**Optional Optimization:** -```bash -# Use ImageOptim (Mac) or FileOptimizer (Windows/Linux) -# Or use online: TinyPNG.com -# Goal: Keep each under 500 KB for fast loading -``` - -**Final Files:** -- `web/static/textures/wood-light.png` -- `web/static/textures/wood-dark.png` -- `web/static/textures/wood-mahogany.png` - ---- - -### Phase 1: Remove Wood Themes from Core Theme System - -**Goal:** Remove wood themes from the core theme system to prepare for separate wood paneling feature. - -#### Files to Modify: - -**1. `web/src/theme.ts`** -- Remove `wood-light`, `wood-dark`, `wood-mahogany` from `ThemeType` union (lines 15-17) -- Remove wood theme gradient logic from `applyTheme()` function (lines 26-46) -- Keep only regular theme handling - -**Before (theme.ts):** -```typescript -type ThemeType = - | 'tokyo-night' - | 'dracula' - // ... other themes - | 'wood-light' - | 'wood-dark' - | 'wood-mahogany'; -``` - -**After (theme.ts):** -```typescript -type ThemeType = - | 'tokyo-night' - | 'dracula' - // ... other themes (remove wood themes); -``` - -**Before (applyTheme function):** -```typescript -const applyTheme = (theme: string): void => { - // Handle wood themes with gradients - if (theme.startsWith('wood-')) { - document.body.className = `theme-${theme}`; - // ... wood gradient logic - } else { - // Apply regular theme - document.body.className = `theme-${theme}`; - document.body.style.background = ''; - document.body.style.backgroundSize = ''; - document.body.style.backgroundAttachment = ''; - } - localStorage.setItem(THEME_STORAGE_KEY, theme); -}; -``` - -**After (applyTheme function):** -```typescript -const applyTheme = (theme: string): void => { - // Apply regular theme only - document.body.className = `theme-${theme}`; - document.body.style.background = ''; - document.body.style.backgroundSize = ''; - document.body.style.backgroundAttachment = ''; - localStorage.setItem(THEME_STORAGE_KEY, theme); -}; -``` - -**2. `tailwind.config.ts`** -- Remove `theme-wood-light`, `theme-wood-dark`, `theme-wood-mahogany` from safelist (lines 21-23) - -**Before:** -```typescript -safelist: [ - 'theme-tokyo-night', - // ... other themes - 'theme-wood-light', - 'theme-wood-dark', - 'theme-wood-mahogany', -] -``` - -**After:** -```typescript -safelist: [ - 'theme-tokyo-night', - // ... other themes (remove wood theme entries) -] -``` - -**3. `web/static/input.css`** -- Remove `.theme-wood-light`, `.theme-wood-dark`, `.theme-wood-mahogany` blocks (lines 115-140) - -#### Verification Steps: -```bash -# Build TypeScript -npm run build:ts - -# Verify: Build succeeds with no TypeScript errors -# Verify: No references to wood themes remain in theme.ts -``` - -#### Git Commit: -```bash -git add web/src/theme.ts -git commit -m "refactor(theme): remove wood themes from core theme system - -- Remove wood-light, wood-dark, wood-mahogany from ThemeType -- Remove wood theme gradient logic from applyTheme() -- Wood themes will be reimplemented as separate paneling feature -- Paneling will target dashboard bookshelf background only" -``` - -```bash -git add tailwind.config.ts -git commit -m "refactor(tailwind): remove wood themes from safelist - -- Remove theme-wood-light, theme-wood-dark, theme-wood-mahogany -- Wood themes no longer exist as color themes" -``` - -```bash -git add web/static/input.css -git commit -m "refactor(css): remove wood theme CSS variables - -- Remove .theme-wood-light, .theme-wood-dark, .theme-wood-mahogany -- Wood paneling will use separate background utilities" -``` - ---- - -### Phase 1b: Remove Wood Themes from Profile Form - -**Goal:** Remove wood theme options from profile settings form since wood paneling will be browser-only. - -#### File: `templates/profile_form.templ` - -**Remove lines 55-57 (wood theme options):** - -```templ - - - - - - -``` - -**Rationale:** Wood paneling is a browser preference (localStorage only), not a server-synced theme. Users will control wood paneling from the header dropdown's "Bookshelf Background" section, not profile settings. - -#### Verification Steps: -```bash -# Build Go templates -go build ./... - -# Verify: Build succeeds with no template errors -# Verify: Wood options removed from profile theme dropdown -``` - -#### Git Commit: -```bash -git add templates/profile_form.templ -git commit -m "refactor(profile): remove wood themes from profile settings - -- Remove wood-light, wood-dark, wood-mahogany from theme dropdown -- Wood paneling is now browser-only (localStorage preference) -- Users select wood paneling from header dropdown, not profile -- Profile form only controls server-synced color themes" -``` - ---- - -### Phase 2: Create Wood Paneling TypeScript Module - -**Goal:** Create separate wood paneling preference system using localStorage and Tailwind classes. - -#### New File: `web/src/woodPaneling.ts` - -```typescript -// Wood paneling management functionality - -type WoodPanelingType = 'none' | 'wood-light' | 'wood-dark' | 'wood-mahogany'; - -const WOOD_STORAGE_KEY = 'wood-paneling'; - -// Apply wood paneling to collections container -const applyWoodPaneling = (paneling: WoodPanelingType): void => { - const container = document.getElementById('collections-container'); - if (!container) return; - - // Remove all wood background classes - container.classList.remove('bg-wood-light', 'bg-wood-dark', 'bg-wood-mahogany'); - - if (paneling !== 'none') { - // Add selected wood background class - container.classList.add(`bg-${paneling}`); - } - - // Save to localStorage - localStorage.setItem(WOOD_STORAGE_KEY, paneling); -}; - -// Load wood paneling from localStorage on page load -const loadWoodPaneling = (): void => { - const stored = localStorage.getItem(WOOD_STORAGE_KEY) as WoodPanelingType | null; - if (stored) { - applyWoodPaneling(stored); - } else { - // Default to none - applyWoodPaneling('none'); - } -}; - -// Change wood paneling (called from theme dropdown) -const changeWoodPaneling = (paneling: WoodPanelingType): void => { - applyWoodPaneling(paneling); - - // Update active indicators - updateWoodPanelingIndicators(); - - // Close dropdown - const dropdown = document.getElementById('theme-dropdown'); - if (dropdown) { - dropdown.classList.add('hidden'); - } -}; - -// Update visual indicators for wood paneling buttons -const updateWoodPanelingIndicators = (): void => { - const currentWood = localStorage.getItem(WOOD_STORAGE_KEY) || 'none'; - - // Update wood paneling buttons - document.querySelectorAll('.wood-paneling-btn').forEach(btn => { - const wood = btn.getAttribute('data-wood'); - if (wood === currentWood) { - // Active state - use CSS class instead of inline style - btn.classList.add('bg-wood-active'); - btn.classList.remove('bg-wood-inactive'); - } else { - // Inactive state - btn.classList.remove('bg-wood-active'); - btn.classList.add('bg-wood-inactive'); - } - }); -}; - -// Make functions available globally -(window as any).changeWoodPaneling = changeWoodPaneling; -(window as any).loadWoodPaneling = loadWoodPaneling; -(window as any).updateWoodPanelingIndicators = updateWoodPanelingIndicators; - -// Auto-initialize when DOM is ready -if (typeof document !== 'undefined') { - if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', () => { - loadWoodPaneling(); - updateWoodPanelingIndicators(); - }); - } else { - loadWoodPaneling(); - updateWoodPanelingIndicators(); - } -} -``` - -**Note:** This uses Tailwind classes (`bg-wood-light`, etc.) instead of inline styles, and CSS variable classes (`bg-wood-active`, `bg-wood-inactive`) for indicators. - -#### New File: `web/src/woodPanelingInit.ts` - -```typescript -// Early initialization script to prevent flash of wrong background -// Loads before woodPaneling.js to apply paneling immediately - -const WOOD_STORAGE_KEY = 'wood-paneling'; - -// Apply wood paneling immediately (before DOM ready if possible) -(function() { - const woodPaneling = localStorage.getItem(WOOD_STORAGE_KEY) || 'none'; - if (woodPaneling !== 'none') { - const applyPaneling = () => { - const container = document.getElementById('collections-container'); - if (container) { - container.classList.add(`bg-${woodPaneling}`); - } - }; - - // Apply immediately if DOM is ready, otherwise wait - if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', applyPaneling); - } else { - applyPaneling(); - } - } -})(); -``` - -**Note:** This standalone script prevents flash of unstyled content by applying wood paneling as early as possible. It has no dependencies and runs before the main woodPaneling.js module. - -#### Verification Steps: -```bash -# Build TypeScript -npm run build:ts - -# Verify: woodPaneling.js compiled successfully to web/static/ -# Verify: No TypeScript errors -``` - -#### Git Commit: -```bash -git add web/src/woodPaneling.ts web/src/woodPanelingInit.ts -git commit -m "feat(wood-paneling): create wood paneling management system - -- Add woodPaneling.ts with localStorage-based paneling preferences -- Add woodPanelingInit.ts for early initialization (prevents flash) -- Support none, wood-light, wood-dark, wood-mahogany options -- Apply paneling to #collections-container only (not full body) -- Use Tailwind utility classes for backgrounds -- Use CSS variable classes for active indicators -- Export functions for HTML onclick handlers -- Auto-initialize on DOM ready" -``` - ---- - -### Phase 3: Create Active Indicators Module - -**Goal:** Create active indicators for theme dropdown to show which theme/wood option is selected. - -#### New File: `web/src/themeDropdown.ts` - -```typescript -// Theme dropdown active indicator management - -// Update visual indicators for theme buttons -const updateThemeIndicators = (): void => { - const currentTheme = localStorage.getItem('theme') || 'tokyo-night'; - - // Update theme buttons (all buttons with changeThemeTo onclick) - document.querySelectorAll('[onclick^="changeThemeTo"]').forEach(btn => { - const onclick = btn.getAttribute('onclick') || ''; - const match = onclick.match(/changeThemeTo\('(.+?)'\)/); - if (match) { - const theme = match[1]; - if (theme === currentTheme) { - // Active state - use CSS class instead of inline style - btn.classList.add('bg-theme-active'); - btn.classList.remove('bg-theme-inactive'); - } else { - // Inactive state - btn.classList.remove('bg-theme-active'); - btn.classList.add('bg-theme-inactive'); - } - } - }); -}; - -// Make function available globally -(window as any).updateThemeIndicators = updateThemeIndicators; - -// Update on dropdown toggle -const originalToggleThemeDropdown = (window as any).toggleThemeDropdown; -if (originalToggleThemeDropdown) { - (window as any).toggleThemeDropdown = () => { - originalToggleThemeDropdown(); - updateThemeIndicators(); - (window as any).updateWoodPanelingIndicators?.(); - }; -} - -// Update after theme changes -const originalChangeThemeTo = (window as any).changeThemeTo; -if (originalChangeThemeTo) { - (window as any).changeThemeTo = (...args: unknown[]) => { - originalChangeThemeTo(...args); - updateThemeIndicators(); - }; -} - -// Auto-initialize when DOM is ready -if (typeof document !== 'undefined') { - if (document.readyState === 'loading') { - document.addEventListener('DOMContentLoaded', updateThemeIndicators); - } else { - updateThemeIndicators(); - } -} -``` - -**Note:** Uses CSS classes (`bg-theme-active`, `bg-theme-inactive`) instead of inline styles for better separation of concerns. - -#### Verification Steps: -```bash -# Build TypeScript -npm run build:ts - -# Verify: themeDropdown.js compiled successfully to web/static/ -# Verify: No TypeScript errors -``` - -#### Git Commit: -```bash -git add web/src/themeDropdown.ts -git commit -m "feat(theme): add active indicators for theme dropdown - -- Create themeDropdown.ts to manage active state highlighting -- Show which theme/wood option is currently selected -- Use CSS classes instead of inline styles for indicators -- Wrap existing functions to update indicators on toggle -- Auto-initialize indicators on DOM ready" -``` - ---- - -### Phase 4: Update Tailwind Config for Wood Backgrounds - -**Goal:** Add Tailwind utility classes for wood texture backgrounds. - -#### File: `tailwind.config.ts` - -**Add to `theme.extend`:** - -```typescript -export default { - // ... existing config - theme: { - extend: { - // ... existing extensions - backgroundImage: { - 'wood-light': "url('/static/textures/wood-light.png')", - 'wood-dark': "url('/static/textures/wood-dark.png')", - 'wood-mahogany': "url('/static/textures/wood-mahogany.png')", - }, - }, - }, -}; -``` - -#### Verification Steps: -```bash -# Regenerate CSS -npm run build:css - -# Verify: CSS regenerated with wood background utilities -# Verify: No errors in build output - -# Full build -npm run build:ts - -# Verify: Full build succeeds -``` - -#### Git Commit: -```bash -git add tailwind.config.ts -git commit -m "feat(tailwind): add wood texture background utilities - -- Add bg-wood-light, bg-wood-dark, bg-wood-mahogany utilities -- Reference texture files in web/static/textures/ -- Extend theme.backgroundImage for seamless texture support" -``` - ---- - -### Phase 5: Add CSS Classes for Active Indicators - -**Goal:** Add CSS classes for active/inactive states using CSS variables already defined in `input.css`. - -#### File: `web/static/input.css` - -**Add to `@layer components` section (before closing brace, after existing rules):** - -```css -/* Active/inactive states for theme and wood paneling buttons */ -.bg-theme-active, -.bg-wood-active { - background-color: var(--bg-primary) !important; -} - -.bg-theme-inactive, -.bg-wood-inactive { - background-color: var(--bg-secondary) !important; -} -``` - -**Note:** Uses `!important` to override inline styles in template. CSS variables (`--bg-primary`, `--bg-secondary`) are already defined in the `:root` and theme sections of `input.css`. - -#### Verification Steps: -```bash -# Regenerate CSS -npm run build:css - -# Verify: CSS regenerated successfully -# Verify: No errors - -# Full build -npm run build:ts -``` - -#### Git Commit: -```bash -git add web/static/input.css -git commit -m "feat(styles): add active indicator classes for dropdown buttons - -- Add bg-theme-active/inactive for theme buttons -- Add bg-wood-active/inactive for wood paneling buttons -- Use CSS variables already defined in input.css -- Use !important to override inline styles" -``` - ---- - -### Phase 6: Update Header Template - -**Goal:** Remove wood theme buttons, add wood paneling section, remove max-width constraint, and add script includes. - -#### File: `templates/header.templ` - -**Change 1 - Line 5: Remove `max-w-7xl`:** - -```templ - -
- - -
-``` - -**Change 2 - Lines 85-99: Replace wood theme buttons with wood paneling section:** - -```templ -
-

Bookshelf Background

- - - - -
-``` - -**Change 3 - Before closing script tag: Add script includes:** - -```templ - - -``` - -#### Verification Steps: -```bash -# Build Go templates -go build ./... - -# Verify: Build succeeds with no template errors -# Verify: Script tags are properly placed -``` - -#### Git Commit: -```bash -git add templates/header.templ -git commit -m "refactor(header): separate wood paneling from color themes - -- Remove max-w-7xl constraint, use full-width layout -- Replace wood theme buttons with wood paneling section -- Add visual previews for wood textures in dropdown -- Section labeled \"Bookshelf Background\" for clarity -- Include woodPaneling.js and themeDropdown.js scripts" -``` - ---- - -### Phase 7: Apply Full-Width Layout to Dashboard - -**Goal:** Apply full-width layout and include wood paneling initialization script. - -#### File: `templates/dashboard.templ` - -**Change 1 - Line ~27: Library selector - Remove `max-w-7xl`:** - -```templ - -
- - -
-``` - -**Change 2 - Line ~67: Collections container - Remove `max-w-7xl`:** - -```templ - -
- - -
-``` - -**Change 3 - Before closing body tag: Add wood paneling initialization script:** - -```templ - -``` - -**This ensures:** -- Wood paneling applied immediately when script loads (before DOM ready) -- No flash of wrong background -- All JavaScript is TypeScript (follows PROJECT_GUIDELINES.md) - -#### Verification Steps: -```bash -# Build Go templates -go build ./... - -# Verify: Build succeeds -# Verify: Script tag placed before closing body tag -# Verify: woodPanelingInit.js exists in web/static/ -``` - -#### Git Commit: -```bash -git add templates/dashboard.templ -git commit -m "refactor(dashboard): apply full-width layout and wood paneling - -- Remove max-w-7xl constraints from library selector and collections -- Include woodPanelingInit.js script for early paneling application -- Prevent flash of wrong background on page load -- Wood paneling applied only to #collections-container -" -``` - ---- - -### Phase 8: Apply Full-Width Layout to All Remaining Pages - -**Goal:** Remove `max-w-7xl` constraints from all remaining page templates. - -#### Files to Modify: - -**Regular pages:** -- `templates/collections.templ` -- `templates/progress.templ` -- `templates/queue.templ` -- `templates/devices.templ` -- `templates/analytics.templ` -- `templates/conflicts.templ` -- `templates/unlinked_books.templ` -- `templates/bookshelf.templ` -- `templates/profile.templ` -- `templates/docs.templ` - -**Admin pages:** -- `templates/admin.templ` -- `templates/admin_library.templ` -- `templates/admin_users.templ` - -**Pattern:** Replace `class="max-w-7xl mx-auto px-4 ..."` with `class="w-full px-4 ..."` - -**Note:** Keep padding (`px-4`, `py-8`, etc.) for readability. - -**Special note for admin templates:** -Admin templates have sidebar layout wrappers. The structure is: -```templ -
- @AdminSidebar(user, currentPath) -
-
- (or
in some cases) -``` - -Change the inner div in all three admin templates: -```templ - -
(or
) - - -
-``` - -**Do NOT** modify the `main` element or the flex wrapper in admin templates - these are part of the admin sidebar layout. - -#### Verification Steps: -```bash -# Build all templates -go build ./... - -# Verify: All templates compile successfully -# Verify: No template errors -``` - -#### Git Commit: -```bash -git add templates/collections.templ templates/progress.templ templates/queue.templ templates/devices.templ templates/analytics.templ templates/conflicts.templ templates/unlinked_books.templ templates/bookshelf.templ templates/profile.templ templates/docs.templ templates/admin.templ templates/admin_library.templ templates/admin_users.templ -git commit -m "refactor(layout): apply full-width layout to all pages - -- Remove max-w-7xl containers from all page templates -- Replace with w-full for full-screen width utilization -- Maintain padding for readability -- Admin templates: modify inner content div only (preserve sidebar layout)" -``` - ---- - -### Phase 9: Add User Documentation - -**Goal:** Document the wood paneling and theme features for end users. - -#### New File: `docs/user/themes.md` - -```markdown -# Themes and Wood Paneling - -## Color Themes - -Bookhoard includes multiple color themes to suit your preferences: - -- **Tokyo Night** (default) - Dark blue/purple tones -- **Dracula** - Dark purple accent colors -- **Nord** - Arctic, bluish-gray colors -- **Solarized Dark** - Precision contrast for readability -- **Monokai** - Dark theme with vibrant accents -- **One Dark Pro** - Atom's favorite theme -- **Material Dark** - Material Design dark theme -- **Catppuccin Mocha** - Soothing pastel dark theme -- **Catppuccin Macchiato** - Warm mid-tone theme -- **Catppuccin Frappé** - Frothy cool tones -- **Catppuccin Latte** - Warm light theme - -### Changing Your Theme - -1. Click the theme icon (palette) in the header -2. Select your preferred color theme -3. Your choice is saved automatically and synced across devices - -## Wood Paneling - -Wood paneling adds texture to your dashboard bookshelf background, giving it a classic bookshelf feel. - -### Available Wood Textures - -- **None** (default) - Solid color background -- **Wood Light** - Light oak/birch texture -- **Wood Dark** - Dark walnut/mahogany texture -- **Wood Mahogany** - Reddish-brown mahogany texture - -### Applying Wood Paneling - -1. Click the theme icon (palette) in the header -2. Scroll to "Bookshelf Background" section -3. Select your preferred wood texture -4. Texture is applied to dashboard bookshelf only - -**Note:** Wood paneling is a browser preference and is not synced across devices. - -### Tips - -- Wood textures work best with darker color themes (Tokyo Night, Nord, etc.) -- Light wood pairs well with light themes (Catppuccin Latte) -- Wood paneling only affects the dashboard bookshelf area -``` - -#### Verification Steps: -```bash -# Restart server and verify docs render -curl http://localhost:8080/docs - -# Verify: themes.md appears in search -# Verify: Documentation renders correctly -``` - -#### Git Commit: -```bash -git add docs/user/themes.md -git commit -m "docs(user): add themes and wood paneling guide - -- Document all available color themes with descriptions -- Explain wood paneling feature and available textures -- Provide step-by-step instructions for changing themes -- Add tips for theme/texture pairing" -``` - ---- - -### Phase 10: Final Testing and Verification - -**Goal:** Complete end-to-end testing and verification. - -#### Testing Checklist: - -**Wood Paneling:** -- [ ] Wood paneling options appear in theme dropdown -- [ ] "None" option removes texture -- [ ] Wood textures apply to dashboard only (not header/sidebar) -- [ ] Active wood option highlighted -- [ ] Preference persists across page refreshes - -**Full-Width Layout:** -- [ ] All pages use full width -- [ ] Content still readable with proper padding -- [ ] Responsive on mobile devices - -**Theme System:** -- [ ] Wood themes removed from color theme section -- [ ] Color themes still work correctly -- [ ] Active theme highlighted -- [ ] Theme switching saves to server - -**Performance:** -- [ ] Wood textures load quickly (<500 KB each) -- [ ] No flash of wrong background on page load - -#### Final Verification: -```bash -# Build everything -npm run build:ts -npm run build:css -go build ./... - -# Run verification script -bash scripts/verify-guidelines.sh - -# Run tests -go test ./... -v -``` - -#### Final Git Commit: -```bash -git add . -git commit -m "chore: final cleanup for wood paneling and full-width layout - -- All phases complete and tested -- Documentation updated in docs/user/themes.md -- Verification scripts passing -- Ready for testing" -``` - ---- - -## Files Summary -- `web/src/woodPaneling.ts` - Wood paneling management -- `web/src/woodPanelingInit.ts` - Early wood paneling initialization (prevents flash) -- `web/src/themeDropdown.ts` - Active indicator management -- `web/static/textures/wood-light.png` - Light wood texture -- `web/static/textures/wood-dark.png` - Dark wood texture -- `web/static/textures/wood-mahogany.png` - Mahogany texture - -### Files Modified -- `templates/header.templ` - Remove wood themes, add wood paneling section, remove max-width -- `templates/profile_form.templ` - Remove wood theme options from profile settings -- `tailwind.config.ts` - Remove theme-wood-* from safelist, add wood background images -- `templates/dashboard.templ` - Remove max-width, add wood paneling script include -- `templates/*.templ` - Remove `max-w-7xl` from all page templates - ---- - -## Migration Notes - -### Breaking Changes -- Wood themes removed from theme system -- Users with wood theme selected will see tokyo-night (or their last color theme) -- Wood paneling preference starts as "none" (users must opt-in) - -### Backward Compatibility -- Color themes unaffected -- localStorage theme preference still works -- Server-side theme sync still works - -### Database Dependencies -- None (wood paneling is localStorage only) - -### Performance -- Wood textures only loaded when selected -- "None" option = no texture load (fastest) -- Texture size optimized to ~200-500 KB each - -### Progressive Enhancement -- Pages work without wood paneling (default "none") -- Wood paneling degrades gracefully if JS fails -- Color themes work independently of wood paneling - ---- - -## Rollback Plan - -If issues arise: -1. Remove wood paneling section from header -2. Restore `max-w-7xl` containers in templates -3. Delete wood texture files -4. Revert header.ts to include wood theme logic -5. Wood paneling preference in localStorage will be ignored (harmless) - ---- - -## Future Improvements - -1. **Per-page wood paneling:** Allow wood on bookshelf page, not just dashboard -2. **Texture variety:** Add more wood options (oak, pine, walnut) -3. **Texture intensity:** Add opacity slider for subtler effect -4. **Custom textures:** Allow users to upload their own backgrounds -5. **Server-side sync:** Store wood paneling preference in database for cross-device sync -6. **Preview mode:** Show texture preview before applying -7. **High-DPI textures:** Provide 2x versions for retina displays - ---- - -## Attribution - -All wood textures are CC0 licensed (no attribution required): - -- **Light wood:** qubodup - https://opengameart.org/content/light-wood-1024x1024 -- **Dark/Mahogany wood:** Luke.RUSTLTD - https://opengameart.org/content/5-wood-textures - -**Optional:** Add to README.md or about page for documentation purposes.