diff --git a/.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md b/.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md new file mode 100644 index 0000000..29a065c --- /dev/null +++ b/.planning/phases/09-weight-classification-and-visualization/09-CONTEXT.md @@ -0,0 +1,93 @@ +# 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 + + + + +## 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 + + + + +## 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*