@thierrynakoa/fire-flow 12.2.1 → 13.0.1

package/skills-library/patterns-standards/THEME_AWARE_CSS_VARIABLES_PATTERN.md

@@ -0,0 +1,209 @@
+# Theme-Aware CSS Variables Pattern - Hardcoded Colors to Dynamic Themes
+
+## The Problem
+
+Components with hardcoded Tailwind color classes (e.g., `bg-white`, `text-slate-600`, `bg-blue-500`) break when the app supports multiple themes. The aurora-borealis dark theme made podcast player text invisible and backgrounds clash because colors were baked into class names.
+
+### Why It Was Hard
+
+- Tailwind utility classes like `bg-slate-100` compile to fixed hex values — no runtime override
+- `<style jsx>` blocks with hardcoded hex colors (e.g., `color: #1e293b`) also ignore themes
+- Can't use Tailwind's `dark:` variant because themes aren't just light/dark — they're custom palettes
+- Need a pattern that works for BOTH Tailwind classes AND custom CSS (like audio player overrides)
+
+### Impact
+
+- PodcastPlayer and Podcasts page were unreadable on aurora-borealis theme
+- Any new component using hardcoded colors would have the same problem
+- Fixing one-off is easy; establishing a consistent pattern is the real value
+
+---
+
+## The Solution
+
+### Root Cause
+
+Tailwind classes compile to fixed colors at build time. Theme CSS files define CSS custom properties (`--color-primary`, `--color-surface`, etc.) at runtime. Components must reference these variables instead of hardcoded values.
+
+### The Pattern: CSS Variables with Fallbacks
+
+Replace all hardcoded colors with `var(--color-name, fallback)` where the fallback is the default theme's color.
+
+**Three contexts where this applies:**
+
+### 1. Inline Styles (for dynamic/theme colors)
+
+```jsx
+// ❌ BEFORE - hardcoded, breaks on dark themes
+<div className="bg-white text-slate-600 border-slate-200">
+
+// ✅ AFTER - theme-aware with fallbacks
+<div
+  className="rounded-xl"
+  style={{
+    background: 'var(--color-surface, #ffffff)',
+    color: 'var(--color-muted, #475569)',
+    borderColor: 'var(--color-border, #e2e8f0)',
+  }}
+>
+```
+
+### 2. CSS-in-JS / Style Blocks (for library overrides)
+
+```jsx
+// ❌ BEFORE - audio player hardcoded
+<style jsx global>{`
+  .rhap_progress-filled {
+    background: linear-gradient(90deg, #3b82f6, #6366f1);
+  }
+  .rhap_time {
+    color: #64748b;
+  }
+`}</style>
+
+// ✅ AFTER - theme-aware
+<style jsx global>{`
+  .rhap_progress-filled {
+    background: linear-gradient(90deg, var(--color-primary, #3b82f6), var(--color-accent, #6366f1));
+  }
+  .rhap_time {
+    color: var(--color-muted, #64748b);
+  }
+`}</style>
+```
+
+### 3. Dynamic Hover/State (JS event handlers)
+
+```jsx
+// ❌ BEFORE - hardcoded hover
+onMouseEnter={(e) => e.currentTarget.style.background = '#f3f4f6'}
+
+// ✅ AFTER - theme-aware hover
+onMouseEnter={(e) => e.currentTarget.style.background = 'var(--color-surface, #f3f4f6)'}
+onMouseLeave={(e) => e.currentTarget.style.background = 'transparent'}
+```
+
+### CSS Variable Reference (Standard Names)
+
+| Variable | Purpose | Default Fallback |
+|----------|---------|-----------------|
+| `--color-primary` | Buttons, links, active states | `#2563eb` |
+| `--color-accent` | Secondary highlights, gradients | `#8b5cf6` |
+| `--color-surface` | Card/panel backgrounds | `#ffffff` |
+| `--color-background` | Page background | `#f9fafb` |
+| `--color-text` | Primary text | `#111827` |
+| `--color-muted` | Secondary/subtle text | `#6b7280` |
+| `--color-border` | Borders, dividers | `#e5e7eb` |
+| `--shadow-md` | Box shadow | (theme-defined) |
+
+### Advanced: `color-mix()` for Opacity
+
+```css
+/* ❌ BEFORE */
+box-shadow: 0 0 6px rgba(59, 130, 246, 0.4);
+
+/* ✅ AFTER - works with any theme's primary color */
+box-shadow: 0 0 6px color-mix(in srgb, var(--color-primary, #3b82f6) 40%, transparent);
+```
+
+### Advanced: Active/Selected State
+
+```jsx
+style={{
+  background: isCurrent
+    ? 'color-mix(in srgb, var(--color-primary, #2563eb) 10%, transparent)'
+    : 'transparent',
+}}
+```
+
+---
+
+## When to Use Each Approach
+
+| Scenario | Approach |
+|----------|----------|
+| Simple colors (bg, text, border) | `style={{ color: 'var(--color-text, #111)' }}` |
+| Tailwind utilities that DON'T change per theme | Keep Tailwind classes (`rounded-xl`, `px-4`, `font-medium`) |
+| Third-party library CSS overrides | `<style jsx global>` with CSS variables |
+| Hover/active states | JS event handlers with CSS variables |
+| Gradients | `linear-gradient(var(--color-primary), var(--color-accent))` |
+| Semi-transparent overlays | `color-mix(in srgb, var(--color-primary) 10%, transparent)` |
+
+---
+
+## Testing the Fix
+
+### Visual Test
+1. Switch theme to aurora-borealis (dark)
+2. Switch theme to default (light)
+3. All text should be readable on both
+4. All backgrounds should match theme palette
+5. Interactive states (hover, active) should use theme colors
+
+### Quick Grep Check
+```bash
+# Find remaining hardcoded colors in a component
+grep -n "bg-white\|bg-slate\|text-slate\|text-gray\|border-slate" client/src/components/YourComponent.jsx
+# Expected: 0 matches for theme-sensitive elements
+
+# Find hardcoded hex in style blocks
+grep -n "#[0-9a-fA-F]\{6\}" client/src/components/YourComponent.jsx
+# Expected: only inside var() fallbacks
+```
+
+---
+
+## Prevention
+
+1. **New components:** Always use `var(--color-name, fallback)` for any color that should change with theme
+2. **Keep Tailwind for layout:** `flex`, `gap-4`, `rounded-xl`, `px-6` — these don't need theming
+3. **Fallbacks are required:** Always provide a fallback value in case CSS variable isn't defined
+4. **Test on aurora-borealis:** It's the dark theme — if it looks good there AND default, you're covered
+
+---
+
+## Real-World Example: PodcastPlayer.jsx
+
+**Files Modified:**
+- `client/src/components/PodcastPlayer.jsx` (35 lines changed)
+- `client/src/pages/Podcasts.jsx` (474 insertions, 273 deletions)
+
+**Commit:** `583f978 feat(podcasts): Spotify-inspired layout with theme-aware styling`
+
+**What Changed:**
+- All `bg-white`, `bg-slate-*`, `text-slate-*` → CSS variable inline styles
+- All hardcoded hex in `<style jsx>` → CSS variables
+- Gradients use `var(--color-primary)` and `var(--color-accent)`
+- Box shadows use `color-mix()` for theme-aware opacity
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Using Tailwind color classes for themed elements** — `bg-white` compiles to `#fff`, not overridable
+- ❌ **Forgetting fallbacks** — `var(--color-primary)` without fallback breaks if variable missing
+- ❌ **Over-converting** — Layout utilities like `rounded-lg`, `px-4`, `flex` don't need theming
+- ❌ **Using `rgba()` with CSS variables** — Use `color-mix()` instead for opacity
+- ❌ **Mixing approaches** — Pick inline styles for theme colors, keep Tailwind for layout. Be consistent.
+
+---
+
+## Resources
+
+- [CSS Custom Properties (MDN)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+- [color-mix() (MDN)](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix)
+- Project theme files: `themes/aurora-borealis/styles/theme.css`
+- Theme guide: `docs/THEME_COMPLETE_DEVELOPER_GUIDE.md`
+
+## Time to Implement
+
+**30-60 minutes** per component (find-and-replace hardcoded colors → CSS variables)
+
+## Difficulty Level
+
+⭐⭐ (2/5) - Simple pattern, just requires discipline and consistency
+
+---
+
+**Author Notes:**
+The key insight is that Tailwind is great for LAYOUT but terrible for THEMING when you have custom themes beyond light/dark. CSS variables bridge the gap perfectly — you get Tailwind's layout utilities plus runtime color switching. The fallback values mean components still look good even without a theme loaded.

package/skills-library/patterns-standards/THEME_USER_OBJECT_PROPERTY_NAMING.md

@@ -0,0 +1,194 @@
+# Theme User Object Property Naming Mismatch - Solution & Prevention
+
+## The Problem
+
+Theme components display "User" instead of the actual user's first name (e.g., "FirstName") in the header navigation. The profile avatar initial also shows "U" instead of the first letter of the name.
+
+### Error/Symptom
+```
+Expected: [Avatar] FirstName ▼
+Actual:   [Avatar] User ▼
+```
+
+No console errors thrown - this is a silent data mismatch.
+
+### Why It Was Hard
+
+- No error messages - the fallback `|| 'User'` silently hides the bug
+- The property naming difference is subtle: `first_name` (snake_case) vs `firstName` (camelCase)
+- Theme components are isolated from the main app (no shared type system)
+- Different themes may use different property names depending on who wrote them
+- The backend auth response and localStorage user object aren't documented in any shared schema
+
+### Impact
+
+- Users see "User" instead of their name across the entire site header
+- Affects all logged-in users on any theme with the wrong property names
+- Professional appearance degraded
+
+---
+
+## The Solution
+
+### Root Cause
+
+The backend `authController.js` login response sends the user object with **camelCase** properties:
+
+```javascript
+// server/controllers/authController.js (login response)
+{
+  id: user.id,
+  name: user.name,           // "Userlastname" (full name)
+  firstName,                  // "FirstName" (parsed from name)
+  lastName,                   // "lastname" (parsed from name)
+  email: user.email,
+  role: user.role,
+  avatar_url: user.avatar_url,
+  isVerified: user.email_verified,
+  email_verified: user.email_verified,
+}
+```
+
+But theme components were written using **snake_case** properties:
+
+```javascript
+// BAD - Theme Header.jsx
+{user?.first_name || 'User'}          // first_name doesn't exist!
+{user?.first_name} {user?.last_name}  // Both undefined!
+```
+
+### How to Fix
+
+Replace snake_case with camelCase, with fallbacks to `name` parsing:
+
+```javascript
+// GOOD - Theme Header.jsx
+
+// Display first name (with fallback to parsing full name)
+{user?.firstName || user?.name?.split(' ')[0] || 'User'}
+
+// Display full name in dropdown
+{user?.firstName || user?.name?.split(' ')[0]} {user?.lastName || user?.name?.split(' ').slice(1).join(' ')}
+
+// Avatar initial
+{user?.firstName?.charAt(0) || user?.name?.charAt(0) || user?.email?.charAt(0) || 'U'}
+
+// Alt text
+alt={user?.firstName || user?.name || 'User'}
+```
+
+### Why the Fallback Pattern
+
+The `user?.name?.split(' ')[0]` fallback handles:
+1. Old user objects cached in localStorage before `firstName` was added
+2. Any code path that stores only `name` without parsing
+3. Edge case where user logs in through a different auth flow
+
+---
+
+## Complete User Object Reference
+
+### From `authController.js` Login Response:
+```javascript
+{
+  id: "uuid",
+  name: "Userlastname",       // Full name (always present)
+  firstName: "FirstName",         // Parsed first name
+  lastName: "lastname",            // Parsed last name
+  email: "FirstName@example.com",
+  role: "admin",                // admin | manager | moderator | student
+  avatar_url: "/uploads/...",   // Profile picture URL
+  isVerified: true,
+  email_verified: true,
+}
+```
+
+### Properties NOT Available (common mistakes):
+- `first_name` (snake_case) - DOES NOT EXIST
+- `last_name` (snake_case) - DOES NOT EXIST
+- `avatarUrl` (camelCase) - exists in some contexts but `avatar_url` is primary
+- `username` - not used in this LMS
+- `displayName` - not used
+
+---
+
+## Testing the Fix
+
+### Before
+```
+Header shows: [green circle with "U"] User ▼
+Dropdown shows: "undefined undefined" and "user@email.com"
+```
+
+### After
+```
+Header shows: [green circle with "T"] User▼
+Dropdown shows: "Userlastname" and "FirstName@email.com"
+```
+
+### Quick Test
+1. Log in as any user
+2. Check header navigation - should show first name
+3. Open dropdown - should show full name and email
+4. Check mobile sidebar - should show first name
+
+---
+
+## Prevention
+
+1. **Always check `authController.js`** for the actual user object shape before using properties in themes
+2. **Use camelCase** for user properties in themes: `firstName`, `lastName`, `avatarUrl`
+3. **Always add fallbacks**: `user?.firstName || user?.name?.split(' ')[0] || 'User'`
+4. **Check ALL themes** when fixing one - there are 8 themes in this project
+5. **Document the user object** in THEME_DEVELOPMENT.md so theme authors know the correct properties
+
+### Themes to Check:
+```
+themes/the-mountain/     (FIXED 2026-02-14)
+themes/eden/
+themes/aurora-borealis/
+themes/celestial/
+themes/melchizedek-order/
+themes/prophetic-academy/
+themes/prosperity/
+themes/royal-priesthood/
+```
+
+---
+
+## Related Patterns
+
+- Theme components use `window.__LMS_AUTH__` or `localStorage.getItem('user')` for auth
+- The `useAuth()` hook in themes reads from these sources
+- Main app header (`client/src/components/layout/Header.jsx`) uses Redux store which has different property access
+
+---
+
+## Common Mistakes to Avoid
+
+- Don't use `user?.first_name` (snake_case) - backend sends `firstName` (camelCase)
+- Don't use `user?.last_name` (snake_case) - backend sends `lastName` (camelCase)
+- Don't assume `firstName` always exists - add `name?.split(' ')[0]` fallback
+- Don't forget theme files are in `.gitignore` - use `git add -f themes/...` to stage
+- Don't fix only one theme - check all 8 themes for the same issue
+
+---
+
+## Resources
+
+- `server/controllers/authController.js` lines 103-129 - Login response user object
+- `themes/THEME_DEVELOPMENT.md` - Theme development guide
+- `docs/THEME_COMPLETE_DEVELOPER_GUIDE.md` - Complete theme developer guide
+
+## Time to Implement
+
+**5 minutes per theme** - Simple find/replace of property names with fallbacks
+
+## Difficulty Level
+
+Stars: 2/5 - Easy fix once you know the root cause, hard to diagnose initially because of silent fallback to 'User'
+
+---
+
+**Author Notes:**
+This cost ~30 minutes to diagnose because "User" appearing instead of a name could have many causes (auth not loading, user object empty, wrong hook, etc.). The silent `|| 'User'` fallback made it invisible. The key insight: always verify the actual shape of the user object from the backend before writing theme code. Run `JSON.stringify(JSON.parse(localStorage.getItem('user')))` in the browser console to see exactly what's there.

package/skills-library/patterns-standards/TOOLTIP_BLOCKING_CLICKS_FIX.md

@@ -0,0 +1,267 @@
+# Tooltip Blocking Clicks - Pointer Events Solution
+
+## The Problem
+
+Clickable elements (like Strong's numbers, buttons, or links) become unclickable when a tooltip appears over them. The tooltip overlay intercepts click events before they reach the underlying interactive element.
+
+### Symptoms
+
+- Hover works (tooltip appears correctly)
+- Click does nothing (no event handler fires)
+- Server logs show API calls from hover (tooltip data fetch)
+- Browser console shows NO click logs (event never reaches handler)
+- User clicks multiple times with no response
+
+### Why It Was Hard
+
+- **Silent failure** - No error messages, clicks just silently fail
+- **Timing-dependent** - Only happens when tooltip is visible (after hover delay)
+- **Z-index confusion** - High z-index tooltip covers clickable area
+- **Event propagation** - Tooltip intercepts events before they bubble down
+
+### Impact
+
+- Feature appears completely broken to users
+- Users think the button/link doesn't work
+- Frustrating UX - "I'm clicking but nothing happens!"
+- Can affect critical workflows (concordance panels, modals, navigation)
+
+---
+
+## The Solution
+
+### Root Cause
+
+The tooltip is absolutely positioned with a high z-index (`z-50`) and appears directly over the clickable element. When the user clicks, the tooltip receives the click event instead of the underlying button/link.
+
+**Bad Code (Blocks Clicks):**
+```tsx
+<span className="tooltip-wrapper relative inline-block">
+  <button onClick={handleClick}>Click Me</button>
+  {showTooltip && (
+    <span className="absolute z-50 px-2 py-1 bg-gray-900 rounded">
+      Tooltip Text
+    </span>
+  )}
+</span>
+```
+
+### How to Fix
+
+Add `pointer-events-none` to the tooltip so mouse events pass through to underlying elements:
+
+**Good Code (Allows Clicks):**
+```tsx
+<span className="tooltip-wrapper relative inline-block">
+  <button onClick={handleClick}>Click Me</button>
+  {showTooltip && (
+    <span className="absolute z-50 px-2 py-1 bg-gray-900 rounded pointer-events-none">
+      Tooltip Text
+    </span>
+  )}
+</span>
+```
+
+### Complete Working Example
+
+```tsx
+import { useState } from 'react';
+
+interface TooltipProps {
+  children: React.ReactNode;
+  content: string;
+}
+
+export function Tooltip({ children, content }: TooltipProps) {
+  const [show, setShow] = useState(false);
+  const [hoverTimeout, setHoverTimeout] = useState<NodeJS.Timeout | null>(null);
+
+  const handleMouseEnter = () => {
+    // 500ms delay before showing tooltip
+    const timeout = setTimeout(() => setShow(true), 500);
+    setHoverTimeout(timeout);
+  };
+
+  const handleMouseLeave = () => {
+    if (hoverTimeout) {
+      clearTimeout(hoverTimeout);
+      setHoverTimeout(null);
+    }
+    setShow(false);
+  };
+
+  return (
+    <span
+      className="tooltip-wrapper relative inline-block"
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+    >
+      {children}
+      {show && (
+        <span className="absolute z-50 px-2 py-1 text-xs font-medium text-white bg-gray-900 rounded shadow-lg whitespace-nowrap -top-8 left-1/2 transform -translate-x-1/2 pointer-events-none">
+          {content}
+          {/* Tooltip arrow (also needs pointer-events-none on parent) */}
+          <span className="absolute w-2 h-2 bg-gray-900 transform rotate-45 -bottom-1 left-1/2 -translate-x-1/2"></span>
+        </span>
+      )}
+    </span>
+  );
+}
+
+// Usage
+<Tooltip content="Click to open concordance">
+  <button onClick={() => console.log('Clicked!')}>
+    Strong's #H7225
+  </button>
+</Tooltip>
+```
+
+---
+
+## Testing the Fix
+
+### Debugging Strategy
+
+1. **Add console.logs to click handler:**
+   ```typescript
+   const handleClick = () => {
+     console.log('Click event fired!'); // Should see this
+     // ... rest of handler
+   };
+   ```
+
+2. **Test with tooltip hidden:**
+   - Click immediately (before tooltip appears)
+   - Should work ✅
+
+3. **Test with tooltip visible:**
+   - Hover until tooltip appears (wait 500ms)
+   - Click while tooltip is visible
+   - Should work ✅ (after adding pointer-events-none)
+
+### Before Fix
+```
+Browser Console: (nothing - click never reaches handler)
+Server Logs: GET /api/tooltip/data (hover working)
+User Action: Click, click, click... (frustrated)
+```
+
+### After Fix
+```
+Browser Console: "Click event fired!"
+Server Logs: GET /api/tooltip/data, POST /api/action (both working)
+User Action: Click (success!)
+```
+
+---
+
+## Prevention
+
+### Checklist for Interactive Tooltips
+
+- ✅ **Always add `pointer-events-none`** to tooltip overlays
+- ✅ **Test clicks while tooltip is visible** (not just when hidden)
+- ✅ **Add console.log debugging** to verify events fire
+- ✅ **Check z-index values** - high z-index means potential click blocking
+- ✅ **Test on different browsers** - event handling can vary
+
+### Code Review Questions
+
+When reviewing tooltip implementations:
+1. Does the tooltip have `pointer-events-none`?
+2. Can you click the underlying element while hovering?
+3. Are there console logs to verify click events?
+4. Is the z-index appropriate (not unnecessarily high)?
+
+---
+
+## Related Patterns
+
+- [Modal Dialog Click Outside Detection](./MODAL_CLICK_OUTSIDE_FIX.md)
+- [Dropdown Menu Event Handling](./DROPDOWN_EVENT_HANDLING.md)
+- [Z-Index Stacking Context Guide](./Z_INDEX_STACKING_MEMORY.md)
+
+---
+
+## Common Mistakes to Avoid
+
+- ❌ **Removing z-index** - Tooltip won't appear on top
+- ❌ **Stopping event propagation** - Breaks other handlers
+- ❌ **Using display: none on hover** - Tooltip flickers
+- ❌ **Not testing with tooltip visible** - Only test when hidden
+- ❌ **Assuming clicks work because hover works** - Different events!
+
+---
+
+## CSS Pointer Events Reference
+
+```css
+/* No pointer events - clicks pass through */
+pointer-events: none;
+
+/* Default - element receives events */
+pointer-events: auto;
+
+/* Only on visible parts (ignores transparent areas) */
+pointer-events: visible;
+
+/* Never receives events (even when visible) */
+pointer-events: none;
+```
+
+**Key insight:** `pointer-events: none` makes the element "invisible" to the mouse cursor for interaction purposes, while still being visually displayed.
+
+---
+
+## Resources
+
+- [MDN: pointer-events](https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events)
+- [React Event Handling](https://react.dev/learn/responding-to-events)
+- [CSS Z-Index and Stacking Context](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_positioned_layout/Understanding_z-index/Stacking_context)
+- [Tooltip Accessibility Best Practices](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)
+
+---
+
+## Time to Implement
+
+**2 minutes** - Just add `pointer-events-none` to tooltip className
+
+## Difficulty Level
+
+⭐ (1/5) - Extremely simple once you know the solution, but hard to diagnose initially
+
+---
+
+## Real-World Example: Ministry LLM Strong's Numbers
+
+**Context:** Bible study app with Strong's numbers (H7225, G430, etc.) that should open a concordance panel when clicked. Hovering shows Hebrew/Greek text in a tooltip.
+
+**Problem:** Clicking Strong's numbers did nothing. Users couldn't access concordances.
+
+**Diagnosis:**
+- Server logs showed tooltip API calls working (`GET /api/strongs/H7225`)
+- Browser console showed NO click logs (handler never fired)
+- This proved the tooltip was blocking clicks
+
+**Solution:** Added `pointer-events-none` to tooltip at line 79 of StrongsTooltip.tsx
+
+**Result:** Clicks now pass through tooltip to underlying `<sup>` element, concordance panel opens correctly.
+
+---
+
+**Author Notes:**
+
+This bug is **deceptively simple** - the fix is one CSS class, but the debugging process requires understanding:
+1. Event propagation and capture
+2. Z-index stacking contexts
+3. The difference between hover events (work) and click events (blocked)
+
+The key diagnostic insight: **Server logs show hover working, browser console shows no click logs = tooltip blocking clicks.**
+
+Always test interactive elements with overlays visible, not just hidden!
+
+---
+
+**Created:** 2026-02-09
+**Last Updated:** 2026-02-09
+**Tested With:** React 18, Tailwind CSS, TypeScript