GearBox/.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md

Phase 9: Weight Classification and Visualization - Context

Gathered: 2026-03-16 Status: Ready for planning

## Phase Boundary

Users can classify each item within a setup as base weight, worn, or consumable (same item can differ across setups). Setup detail view shows weight subtotals by classification and a donut chart for weight distribution, toggleable between category and classification breakdowns. Side-by-side comparison, ranking, and impact preview are separate phases.

## Implementation Decisions

Classification UI

• Click-to-cycle badge on each item card within a setup — clicks cycle through base weight → worn → consumable → base weight
• Follows the StatusBadge pattern from Phase 8 (pill badge, click interaction)
• Default classification is "base weight" when an item is added to a setup
• Badge always visible on every item card in the setup (not hidden for default)
• Muted gray color scheme for all classification badges (bg-gray-100 text-gray-600), consistent with Phase 8 status badges
• Classification stored on setup_items join table (already decided in prior phases)

Weight subtotals display

• Summary section below the setup sticky bar, always visible when setup has items
• Card with columns layout: Base | Worn | Consumable | Total — each as a labeled column with weight value
• Sticky bar keeps its existing simple stats (item count, total weight, total cost)
• Summary card is a separate visual element, not inline text

Chart placement & style

• Donut chart sits inside the summary card alongside the weight subtotals — chart + numbers as one visual unit
• Pill toggle above the chart for switching between "Category" and "Classification" views (same style as weight unit selector)
• Total weight displayed in the center of the donut hole (e.g., "2.87kg")
• Hover tooltips show segment name, weight (in selected unit), and percentage
• Chart library: Recharts (PieChart + Pie with innerRadius for donut shape)

Claude's Discretion

• Summary card exact layout (chart left/right, column arrangement)
• Chart color palette for segments (should work with both category and classification views)
• Minimum item threshold for showing chart vs a placeholder message
• Donut chart sizing and proportions
• Tooltip styling
• Keyboard accessibility for classification cycling
• Animation on chart transitions between category/classification views

<code_context>

Existing Code Insights

Reusable Assets

• StatusBadge (src/client/components/StatusBadge.tsx): Click-to-cycle pattern with popup — direct pattern reference for classification badge
• formatWeight() in src/client/lib/formatters.ts: Handles unit conversion, reuse for subtotals and chart tooltips
• useWeightUnit() hook: Gets current weight unit setting for display
• getSetupWithItems() in src/server/services/setup.service.ts: Fetches setup items with category joins — needs to include classification field
• syncSetupItems(): Delete-all + re-insert pattern — needs to preserve classification values

Established Patterns

• Settings stored as key/value strings in SQLite settings table
• React Query for server data, Zustand for UI-only state (panels/dialogs)
• Pill badges: blue-50/blue-400 for weight, green-50/green-500 for price, gray-50/gray-600 for metadata
• Weight unit pill toggle in TotalsBar — same pattern for chart category/classification toggle
• Click-outside + Escape dismiss pattern for popups (CategoryPicker, StatusBadge)

Integration Points

• setup_items table (src/db/schema.ts): Add classification column with default "base"
• getSetupWithItems(): Include classification in query results
• syncSetupItems(): Must handle classification when syncing (preserve during re-insert)
• Setup detail page (src/client/routes/setups/$setupId.tsx): Add summary card section, classification badges on ItemCards, donut chart
• ItemCard component: Needs optional classification prop and badge (only rendered in setup context)
• Setup routes (src/server/routes/setups.ts): API needs to accept/return classification data
• Test helper (tests/helpers/db.ts): Update CREATE TABLE for setup_items to include classification column

</code_context>

## Specific Ideas

No specific requirements — user gave clear structural decisions. Standard gear app patterns apply (LighterPack-style classification).

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 09-weight-classification-and-visualization Context gathered: 2026-03-16