Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

docs: remove completed planning documents

Browse Source 
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
This commit is contained in:
john-okeefe
2026-02-24 21:33:45 -05:00
parent 836f77582b
commit a830e0e2b9
3 changed files with 0 additions and 1498 deletions
Download Patch File Download Diff File Expand all files Collapse all files
THEME_FIX_PLAN.md
-217
View File
@@ -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` → `<body class="theme-tokyo-night">`
- `admin_users.templ` → `<body class="theme-tokyo-night">`
- `bookshelf.templ` → `<body class="theme-tokyo-night">`
- `index.templ` → `<body class="theme-tokyo-night">`
- `login.templ` → `<body class="theme-tokyo-night">`
- `register.templ` → `<body class="theme-tokyo-night">`
2. **Dynamic theme templates** (working correctly):
- `dashboard.templ` → `<body class="theme-{ user.Theme }">`
- `analytics.templ` → `<body class="theme-{ user.Theme }">`
- `collections.templ` → `<body class="theme-{ user.Theme }">`
- `conflicts.templ` → `<body class="theme-{ user.Theme }">`
- `custom_section.templ` → `<body class="theme-{ user.Theme }">`
- `devices.templ` → `<body class="theme-{ user.Theme }">`
- `docs.templ` → `<body class={ "theme-" + user.Theme + ... }`
- `profile.templ` → `<body class="theme-{ user.Theme }">`
- `progress.templ` → `<body class="theme-{ user.Theme }">`
- `queue.templ` → `<body class="theme-{ user.Theme }">`
- `unlinked_books.templ` → `<body class="theme-{ user.Theme }">`
### Why It Breaks
1. Page loads with hardcoded `<body class="theme-tokyo-night">`
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
<!-- Before -->
<body class="theme-tokyo-night">
<!-- After (admin_library.templ, bookshelf.templ) -->
<body class="theme-{ user.Theme }">
<!-- After (admin_users.templ) -->
<body class="theme-{ currentUser.Theme }">
```
**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
<body class="theme-tokyo-night">
<script>
// Progressive enhancement: check localStorage immediately
(function() {
const savedTheme = localStorage.getItem('theme');
if (savedTheme && savedTheme !== 'tokyo-night') {
document.body.className = 'theme-' + savedTheme;
}
})();
</script>
```
#### 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
WOOD_PANELING_FONT_FIX_PLAN.md
-231
View File
@@ -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
WOOD_PANELING_PLAN.md
-1050
View File
File diff suppressed because it is too large Load Diff