docs(06-01): complete category icon data layer plan

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-15 17:52:18 +01:00
parent fca1eb7d34
commit 7d4777a4a4
3 changed files with 147 additions and 13 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -27,7 +27,7 @@ Requirements for v1.1 Fixes & Polish. Each maps to roadmap phases.

 - [ ] **CAT-01**: User can select a Lucide icon when creating/editing a category (icon picker)
 - [ ] **CAT-02**: Category icons display as Lucide icons throughout the app (cards, headers, lists)
- [ ] **CAT-03**: Existing emoji categories are migrated to equivalent Lucide icons
+- [x] **CAT-03**: Existing emoji categories are migrated to equivalent Lucide icons

 ## Future Requirements

@@ -83,7 +83,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 | PLAN-02 | Phase 4 | Complete |
 | CAT-01 | Phase 6 | Pending |
 | CAT-02 | Phase 6 | Pending |
-| CAT-03 | Phase 6 | Pending |
+| CAT-03 | Phase 6 | Complete |

 **Coverage:**
 - v1.1 requirements: 10 total
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,15 +3,15 @@ gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Fixes & Polish
 status: executing
-stopped_at: Phase 6 context gathered
-last_updated: "2026-03-15T16:37:00.689Z"
-last_activity: 2026-03-15 -- Completed 05-02 image placeholders and thumbnails
+stopped_at: Completed 06-01 category icon data layer
+last_updated: "2026-03-15T16:50:15.000Z"
+last_activity: 2026-03-15 -- Completed 06-01 category icon data layer
 progress:
  total_phases: 3
  completed_phases: 2
-  total_plans: 4
-  completed_plans: 4
-  percent: 100
+  total_plans: 7
+  completed_plans: 5
+  percent: 71
 ---

 # Project State
@@ -26,9 +26,9 @@ See: .planning/PROJECT.md (updated 2026-03-15)
 ## Current Position

 Phase: 6 of 6 (Category Icons)
-Plan: 0 of ? in current phase
+Plan: 1 of 3 in current phase
 Status: In Progress
-Last activity: 2026-03-15 -- Completed 05-02 image placeholders and thumbnails
+Last activity: 2026-03-15 -- Completed 06-01 category icon data layer

 Progress: [██████████] 100% (v1.1 phases)

@@ -45,6 +45,9 @@ Progress: [██████████] 100% (v1.1 phases)
 - [Phase 05]: Image bug root cause: Zod schemas missing imageFilename -- validator silently stripped it from payloads
 - [Phase 05]: Inline SVGs instead of lucide-react -- only 3 icons needed, avoids dependency
 - [Phase 05]: Setup detail page only uses ItemCard grid -- no separate thumbnail component needed
+- [Phase 06]: ALTER TABLE RENAME COLUMN for SQLite migration instead of table recreation
+- [Phase 06]: Applied migration via Bun SQLite API since drizzle-kit requires interactive input
+- [Phase 06]: 119 curated Lucide icons across 8 groups for gear coverage

 ### Pending Todos

@@ -58,6 +61,6 @@ None.

 ## Session Continuity

-Last session: 2026-03-15T16:37:00.687Z
-Stopped at: Phase 6 context gathered
-Resume file: .planning/phases/06-category-icons/06-CONTEXT.md
+Last session: 2026-03-15T16:50:15.000Z
+Stopped at: Completed 06-01 category icon data layer
+Resume file: .planning/phases/06-category-icons/06-01-SUMMARY.md
--- a/.planning/phases/06-category-icons/06-01-SUMMARY.md
+++ b/.planning/phases/06-category-icons/06-01-SUMMARY.md
@@ -0,0 +1,131 @@
+---
+phase: 06-category-icons
+plan: 01
+subsystem: database, api, ui
+tags: [drizzle, sqlite, lucide-react, icons, migration]
+
+requires:
+  - phase: none
+    provides: existing emoji-based categories schema
+provides:
+  - Categories table with icon column (Lucide icon names)
+  - Zod schemas validating icon field
+  - All services returning categoryIcon instead of categoryEmoji
+  - LucideIcon render component for dynamic icon display
+  - Curated icon data with 119 icons across 8 groups
+  - EMOJI_TO_ICON_MAP for migration compatibility
+affects: [06-02, 06-03]
+
+tech-stack:
+  added: [lucide-react]
+  patterns: [kebab-case icon names with PascalCase runtime lookup]
+
+key-files:
+  created:
+    - src/client/lib/iconData.ts
+    - drizzle/0001_rename_emoji_to_icon.sql
+  modified:
+    - src/db/schema.ts
+    - src/shared/schemas.ts
+    - src/server/services/category.service.ts
+    - src/server/services/item.service.ts
+    - src/server/services/thread.service.ts
+    - src/server/services/setup.service.ts
+    - src/server/services/totals.service.ts
+    - src/db/seed.ts
+    - tests/helpers/db.ts
+
+key-decisions:
+  - "Used ALTER TABLE RENAME COLUMN for SQLite migration instead of table recreation"
+  - "Applied migration directly via Bun SQLite API since drizzle-kit requires interactive input"
+  - "119 curated icons across 8 groups for comprehensive gear coverage"
+
+patterns-established:
+  - "LucideIcon component: render any Lucide icon by kebab-case name string"
+  - "Icon names stored as kebab-case strings in database and API"
+
+requirements-completed: [CAT-03]
+
+duration: 5min
+completed: 2026-03-15
+---
+
+# Phase 6 Plan 1: Category Icon Data Layer Summary
+
+**Migrated categories from emoji to Lucide icon names with curated 119-icon data set and LucideIcon render component**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-03-15T16:45:02Z
+- **Completed:** 2026-03-15T16:50:15Z
+- **Tasks:** 2
+- **Files modified:** 18
+
+## Accomplishments
+- Renamed emoji column to icon across DB schema, Zod schemas, and all 5 services
+- Created Drizzle migration with emoji-to-icon data conversion for existing categories
+- Built iconData.ts with 119 curated gear-relevant Lucide icons across 8 groups
+- Added LucideIcon component with kebab-to-PascalCase conversion and Package fallback
+- All 87 tests pass, build succeeds
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Migrate schema, Zod schemas, services, test helper, and seed to icon field** - `546dff1` (feat)
+2. **Task 2: Install lucide-react and create icon data file with LucideIcon component** - `fca1eb7` (feat)
+
+## Files Created/Modified
+- `src/db/schema.ts` - Categories table now uses icon column with "package" default
+- `src/shared/schemas.ts` - Zod schemas validate icon as string(1-50)
+- `src/server/services/category.service.ts` - Parameter types use icon instead of emoji
+- `src/server/services/item.service.ts` - Returns categoryIcon instead of categoryEmoji
+- `src/server/services/thread.service.ts` - Returns categoryIcon in both list and detail
+- `src/server/services/setup.service.ts` - Returns categoryIcon in setup item list
+- `src/server/services/totals.service.ts` - Returns categoryIcon in category totals
+- `src/db/seed.ts` - Seeds Uncategorized with icon "package"
+- `tests/helpers/db.ts` - Test helper creates icon column, seeds with "package"
+- `src/client/lib/iconData.ts` - Curated icon groups, LucideIcon component, emoji-to-icon map
+- `drizzle/0001_rename_emoji_to_icon.sql` - Migration SQL with data conversion
+- `package.json` - Added lucide-react dependency
+
+## Decisions Made
+- Used ALTER TABLE RENAME COLUMN for SQLite migration -- simpler than table recreation, supported in SQLite 3.25+
+- Applied migration directly via Bun SQLite API since drizzle-kit push/generate requires interactive input for column renames
+- Included 119 icons (slightly under the upper bound) for comprehensive gear coverage without bloat
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Updated all test files referencing emoji/categoryEmoji**
+- **Found during:** Task 1 (schema migration)
+- **Issue:** Test files referenced emoji field and categoryEmoji property which no longer exist after schema rename
+- **Fix:** Updated 6 test files to use icon/categoryIcon
+- **Files modified:** tests/services/category.service.test.ts, tests/routes/categories.test.ts, tests/services/item.service.test.ts, tests/services/totals.test.ts, tests/services/setup.service.test.ts, tests/services/thread.service.test.ts
+- **Verification:** All 87 tests pass
+- **Committed in:** 546dff1 (Task 1 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Test updates were necessary for correctness. No scope creep.
+
+## Issues Encountered
+- drizzle-kit generate/push commands require interactive input for column renames -- applied migration SQL directly via Bun SQLite API instead
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Icon data infrastructure complete, ready for UI component work (06-02: IconPicker, 06-03: display integration)
+- Client-side still references categoryEmoji -- will be updated in subsequent plans
+
+## Self-Check: PASSED
+
+All created files verified, all commits found, all key exports confirmed.
+
+---
+*Phase: 06-category-icons*
+*Completed: 2026-03-15*