makiolaj/GearBox
1
0
Fork 0
Code Issues 8 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

docs(07): create phase plan for weight unit selection

Browse Source
This commit is contained in:
Jean-Luc Makiola
2026-03-16 12:10:22 +01:00
parent 0b30d5a260
commit f1f63eced9
3 changed files with 489 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

238
.planning/phases/07-weight-unit-selection/07-01-PLAN.md Normal file
View File

@@ -0,0 +1,238 @@
---
phase: 07-weight-unit-selection
plan: 01
type: tdd
wave: 1
depends_on: []
files_modified:
- src/client/lib/formatters.ts
- src/client/hooks/useWeightUnit.ts
- tests/lib/formatters.test.ts
autonomous: true
requirements:
- UNIT-02
- UNIT-03
must_haves:
truths:
- "formatWeight converts grams to g, oz, lb, kg with correct precision"
- "formatWeight defaults to grams when no unit is specified (backward compatible)"
- "formatWeight handles null/undefined input for all units"
- "useWeightUnit hook returns a valid WeightUnit from settings, defaulting to 'g'"
artifacts:
- path: "src/client/lib/formatters.ts"
provides: "WeightUnit type export and parameterized formatWeight function"
exports: ["WeightUnit", "formatWeight", "formatPrice"]
contains: "WeightUnit"
- path: "src/client/hooks/useWeightUnit.ts"
provides: "Convenience hook wrapping useSetting for weight unit"
exports: ["useWeightUnit"]
- path: "tests/lib/formatters.test.ts"
provides: "Unit tests for formatWeight with all 4 units and edge cases"
min_lines: 30
key_links:
- from: "src/client/hooks/useWeightUnit.ts"
to: "src/client/hooks/useSettings.ts"
via: "useSetting('weightUnit')"
pattern: "useSetting.*weightUnit"
- from: "src/client/hooks/useWeightUnit.ts"
to: "src/client/lib/formatters.ts"
via: "imports WeightUnit type"
pattern: "import.*WeightUnit.*formatters"
---
<objective>
Create the weight unit conversion core: a parameterized `formatWeight` function with a `WeightUnit` type and a `useWeightUnit` convenience hook, all backed by tests.
Purpose: Establish the conversion contracts (type, function, hook) that Plan 02 will wire into every component. TDD approach ensures the conversion math is correct before any UI work.
Output: Working `formatWeight(grams, unit)` with tests green, `useWeightUnit()` hook ready for consumption.
</objective>
<execution_context>
@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
@/home/jlmak/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/07-weight-unit-selection/07-RESEARCH.md
@src/client/lib/formatters.ts
@src/client/hooks/useSettings.ts
</context>
<interfaces>
<!-- Key types and contracts the executor needs. Extracted from codebase. -->
From src/client/lib/formatters.ts (current):
```typescript
export function formatWeight(grams: number | null | undefined): string {
if (grams == null) return "--";
return `${Math.round(grams)}g`;
}
export function formatPrice(cents: number | null | undefined): string {
if (cents == null) return "--";
return `$${(cents / 100).toFixed(2)}`;
}
```
From src/client/hooks/useSettings.ts:
```typescript
export function useSetting(key: string) {
return useQuery({
queryKey: ["settings", key],
queryFn: async () => {
try {
const result = await apiGet<Setting>(`/api/settings/${key}`);
return result.value;
} catch (err: any) {
if (err?.status === 404) return null;
throw err;
}
},
});
}
export function useUpdateSetting() {
const queryClient = useQueryClient();
return useMutation({
mutationFn: ({ key, value }: { key: string; value: string }) =>
apiPut<Setting>(`/api/settings/${key}`, { value }),
onSuccess: (_data, variables) => {
queryClient.invalidateQueries({ queryKey: ["settings", variables.key] });
},
});
}
```
</interfaces>
<feature>
<name>formatWeight unit conversion</name>
<files>src/client/lib/formatters.ts, tests/lib/formatters.test.ts</files>
<behavior>
Conversion constants: 1 oz = 28.3495g, 1 lb = 453.592g, 1 kg = 1000g
- formatWeight(100, "g") -> "100g"
- formatWeight(100, "oz") -> "3.5 oz"
- formatWeight(1000, "lb") -> "2.20 lb"
- formatWeight(1500, "kg") -> "1.50 kg"
- formatWeight(null, "oz") -> "--"
- formatWeight(undefined, "kg") -> "--"
- formatWeight(100) -> "100g" (default unit, backward compatible)
- formatWeight(0, "oz") -> "0.0 oz"
- formatWeight(5, "lb") -> "0.01 lb" (small weight precision)
- formatWeight(50000, "kg") -> "50.00 kg" (large weight)
</behavior>
<implementation>
1. Add `WeightUnit` type export: `"g" | "oz" | "lb" | "kg"`
2. Add conversion constants as module-level consts (not exported)
3. Modify `formatWeight` signature to `(grams: number | null | undefined, unit: WeightUnit = "g"): string`
4. Keep the null guard as-is at the top
5. Add switch statement for unit-specific formatting:
- g: `Math.round(grams)` + "g" (0 decimals, current behavior)
- oz: `.toFixed(1)` + " oz" (1 decimal)
- lb: `.toFixed(2)` + " lb" (2 decimals)
- kg: `.toFixed(2)` + " kg" (2 decimals)
6. Do NOT modify `formatPrice` — leave it untouched
</implementation>
</feature>
<tasks>
<task type="auto" tdd="true">
<name>Task 1: TDD formatWeight with unit parameter</name>
<files>src/client/lib/formatters.ts, tests/lib/formatters.test.ts</files>
<behavior>
- formatWeight(100, "g") returns "100g"
- formatWeight(100, "oz") returns "3.5 oz"
- formatWeight(1000, "lb") returns "2.20 lb"
- formatWeight(1500, "kg") returns "1.50 kg"
- formatWeight(null) returns "--" for all units
- formatWeight(undefined, "kg") returns "--"
- formatWeight(100) returns "100g" (backward compatible, no second arg)
- formatWeight(0, "oz") returns "0.0 oz"
</behavior>
<action>
RED: Create `tests/lib/formatters.test.ts`. Import `formatWeight` from `@/client/lib/formatters`. Write tests for:
- All 4 units with a known gram value (e.g., 1000g = "1000g", "35.3 oz", "2.20 lb", "1.00 kg")
- Null and undefined input returning "--" for each unit
- Default parameter (no second arg) producing current "g" behavior
- Zero grams producing "0g", "0.0 oz", "0.00 lb", "0.00 kg"
- Precision edge cases (small values like 5g in lb = "0.01 lb")
Run tests — they should fail because formatWeight does not accept a unit parameter yet.
GREEN: Modify `src/client/lib/formatters.ts`:
- Export `type WeightUnit = "g" | "oz" | "lb" | "kg"`
- Add constants: `GRAMS_PER_OZ = 28.3495`, `GRAMS_PER_LB = 453.592`, `GRAMS_PER_KG = 1000`
- Change signature to `formatWeight(grams: number | null | undefined, unit: WeightUnit = "g")`
- Add switch statement after the null guard for unit-specific conversion and formatting
- Leave `formatPrice` completely untouched
Run tests — all should pass.
REFACTOR: None expected — the code is already minimal.
</action>
<verify>
<automated>bun test tests/lib/formatters.test.ts</automated>
</verify>
<done>formatWeight handles all 4 units with correct precision, null handling, and backward-compatible default. WeightUnit type is exported. All tests pass.</done>
</task>
<task type="auto">
<name>Task 2: Create useWeightUnit convenience hook</name>
<files>src/client/hooks/useWeightUnit.ts</files>
<action>
Create `src/client/hooks/useWeightUnit.ts`:
```typescript
import { useSetting } from "./useSettings";
import type { WeightUnit } from "../lib/formatters";
const VALID_UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"];
export function useWeightUnit(): WeightUnit {
const { data } = useSetting("weightUnit");
if (data && VALID_UNITS.includes(data as WeightUnit)) {
return data as WeightUnit;
}
return "g";
}
```
This hook:
- Wraps `useSetting("weightUnit")` for a typed return value
- Validates the stored value is a known unit (protects against bad data)
- Defaults to "g" when no setting exists (backward compatible — UNIT-03 persistence works via existing settings API)
- Returns `WeightUnit` type so components can pass directly to `formatWeight`
</action>
<verify>
<automated>bun run lint</automated>
</verify>
<done>useWeightUnit hook exists, imports from useSettings and formatters, returns typed WeightUnit with "g" default. Lint passes.</done>
</task>
</tasks>
<verification>
- `bun test tests/lib/formatters.test.ts` passes with all unit conversion tests green
- `bun run lint` passes with no errors
- `src/client/lib/formatters.ts` exports `WeightUnit` type and updated `formatWeight` function
- `src/client/hooks/useWeightUnit.ts` exists and exports `useWeightUnit`
- Existing tests still pass: `bun test` (full suite)
</verification>
<success_criteria>
- formatWeight("g") produces identical output to the old function (backward compatible)
- formatWeight with oz/lb/kg produces correct conversions with appropriate decimal precision
- WeightUnit type is exported for use by Plan 02 components
- useWeightUnit hook is ready for components to consume
- All existing tests remain green (no regressions)
</success_criteria>
<output>
After completion, create `.planning/phases/07-weight-unit-selection/07-01-SUMMARY.md`
</output>

247
.planning/phases/07-weight-unit-selection/07-02-PLAN.md Normal file
View File

@@ -0,0 +1,247 @@
---
phase: 07-weight-unit-selection
plan: 02
type: execute
wave: 2
depends_on:
- "07-01"
files_modified:
- src/client/components/TotalsBar.tsx
- src/client/components/ItemCard.tsx
- src/client/components/CandidateCard.tsx
- src/client/components/CategoryHeader.tsx
- src/client/components/SetupCard.tsx
- src/client/components/ItemPicker.tsx
- src/client/routes/index.tsx
- src/client/routes/setups/$setupId.tsx
autonomous: false
requirements:
- UNIT-01
- UNIT-02
- UNIT-03
must_haves:
truths:
- "User can see a unit toggle (g/oz/lb/kg) in the TotalsBar"
- "Clicking a unit in the toggle changes all weight displays across the app"
- "Weight unit selection persists after page refresh"
- "Every weight display in the app uses the selected unit"
artifacts:
- path: "src/client/components/TotalsBar.tsx"
provides: "Unit toggle UI and unit-aware weight display"
contains: "useWeightUnit"
- path: "src/client/components/ItemCard.tsx"
provides: "Unit-aware item weight display"
contains: "useWeightUnit"
- path: "src/client/components/CandidateCard.tsx"
provides: "Unit-aware candidate weight display"
contains: "useWeightUnit"
- path: "src/client/components/CategoryHeader.tsx"
provides: "Unit-aware category total weight display"
contains: "useWeightUnit"
- path: "src/client/components/SetupCard.tsx"
provides: "Unit-aware setup weight display"
contains: "useWeightUnit"
- path: "src/client/components/ItemPicker.tsx"
provides: "Unit-aware item picker weight display"
contains: "useWeightUnit"
- path: "src/client/routes/index.tsx"
provides: "Unit-aware dashboard weight display"
contains: "useWeightUnit"
- path: "src/client/routes/setups/$setupId.tsx"
provides: "Unit-aware setup detail weight display"
contains: "useWeightUnit"
key_links:
- from: "src/client/components/TotalsBar.tsx"
to: "/api/settings/weightUnit"
via: "useUpdateSetting mutation"
pattern: "useUpdateSetting.*weightUnit"
- from: "src/client/components/ItemCard.tsx"
to: "src/client/hooks/useWeightUnit.ts"
via: "useWeightUnit hook import"
pattern: "useWeightUnit"
- from: "src/client/components/TotalsBar.tsx"
to: "src/client/lib/formatters.ts"
via: "formatWeight(grams, unit)"
pattern: "formatWeight\\(.*,\\s*unit"
---
<objective>
Wire weight unit selection through the entire app: add a segmented unit toggle to TotalsBar and update all 8 formatWeight call sites to use the selected unit.
Purpose: Deliver the complete user-facing feature. After this plan, users can select g/oz/lb/kg and see all weights update instantly across collection, planning, setups, and dashboard.
Output: Fully functional weight unit selection with persistent preference.
</objective>
<execution_context>
@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
@/home/jlmak/.claude/get-shit-done/templates/summary.md
</execution_context>
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/07-weight-unit-selection/07-RESEARCH.md
@.planning/phases/07-weight-unit-selection/07-01-SUMMARY.md
</context>
<interfaces>
<!-- Contracts created by Plan 01 that this plan consumes -->
From src/client/lib/formatters.ts (after Plan 01):
```typescript
export type WeightUnit = "g" | "oz" | "lb" | "kg";
export function formatWeight(grams: number | null | undefined, unit?: WeightUnit): string;
export function formatPrice(cents: number | null | undefined): string;
```
From src/client/hooks/useWeightUnit.ts (after Plan 01):
```typescript
export function useWeightUnit(): WeightUnit;
```
From src/client/hooks/useSettings.ts (existing):
```typescript
export function useUpdateSetting(): UseMutationResult<Setting, Error, { key: string; value: string }>;
```
Usage pattern for every component:
```typescript
import { useWeightUnit } from "../hooks/useWeightUnit";
// ...
const unit = useWeightUnit();
// ...
{formatWeight(weightGrams, unit)}
```
</interfaces>
<tasks>
<task type="auto">
<name>Task 1: Add unit toggle to TotalsBar and update all call sites</name>
<files>
src/client/components/TotalsBar.tsx,
src/client/components/ItemCard.tsx,
src/client/components/CandidateCard.tsx,
src/client/components/CategoryHeader.tsx,
src/client/components/SetupCard.tsx,
src/client/components/ItemPicker.tsx,
src/client/routes/index.tsx,
src/client/routes/setups/$setupId.tsx
</files>
<action>
**TotalsBar.tsx** -- Add unit toggle and wire formatWeight:
1. Import `useWeightUnit` from `../hooks/useWeightUnit`, `useUpdateSetting` from `../hooks/useSettings`, and `WeightUnit` type from `../lib/formatters`
2. Inside the component function, call `const unit = useWeightUnit()` and `const updateSetting = useUpdateSetting()`
3. Define `const UNITS: WeightUnit[] = ["g", "oz", "lb", "kg"]`
4. Add a segmented pill toggle to the right side of the TotalsBar, between the title and the stats. The toggle should be a `div` with `flex items-center gap-1 bg-gray-100 rounded-full px-1 py-0.5` containing a button per unit:
```
<button
key={u}
onClick={() => updateSetting.mutate({ key: "weightUnit", value: u })}
className={`px-2 py-0.5 text-xs rounded-full transition-colors ${
unit === u
? "bg-white text-gray-700 shadow-sm font-medium"
: "text-gray-400 hover:text-gray-600"
}`}
>
{u}
</button>
```
5. Update the default stats construction (the `data?.global` branch) to pass `unit` to both `formatWeight` calls:
- `formatWeight(data.global.totalWeight, unit)` and `formatWeight(null, unit)`
6. Position the toggle: place it in the flex container between the title and stats, using a wrapper div that pushes stats to the right. The toggle should be visible but not dominant -- it's a small utility control.
**ItemCard.tsx** -- 3-line change:
1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
2. Inside component: `const unit = useWeightUnit();`
3. Change `{formatWeight(weightGrams)}` to `{formatWeight(weightGrams, unit)}`
**CandidateCard.tsx** -- Same 3-line pattern as ItemCard:
1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
2. Inside component: `const unit = useWeightUnit();`
3. Change `{formatWeight(weightGrams)}` to `{formatWeight(weightGrams, unit)}`
**CategoryHeader.tsx** -- Same 3-line pattern:
1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
2. Inside component: `const unit = useWeightUnit();`
3. Change `{formatWeight(totalWeight)}` to `{formatWeight(totalWeight, unit)}`
**SetupCard.tsx** -- Same 3-line pattern:
1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
2. Inside component: `const unit = useWeightUnit();`
3. Change `{formatWeight(totalWeight)}` to `{formatWeight(totalWeight, unit)}`
**ItemPicker.tsx** -- Same 3-line pattern:
1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
2. Inside component: `const unit = useWeightUnit();`
3. Change `formatWeight(item.weightGrams)` to `formatWeight(item.weightGrams, unit)`
**routes/index.tsx** (Dashboard) -- Same 3-line pattern:
1. Add import: `import { useWeightUnit } from "../hooks/useWeightUnit";`
2. Inside `DashboardPage`: `const unit = useWeightUnit();`
3. Change `formatWeight(global?.totalWeight ?? null)` to `formatWeight(global?.totalWeight ?? null, unit)`
**routes/setups/$setupId.tsx** (Setup Detail) -- Same 3-line pattern:
1. Add import: `import { useWeightUnit } from "../../hooks/useWeightUnit";`
2. Inside `SetupDetailPage`: `const unit = useWeightUnit();`
3. Change `{formatWeight(totalWeight)}` to `{formatWeight(totalWeight, unit)}`
**Completeness check:** After all changes, grep for `formatWeight(` across `src/client/` -- every call must have a second `unit` argument EXCEPT the function definition itself in `formatters.ts`.
</action>
<verify>
<automated>bun test && bun run lint</automated>
</verify>
<done>
- All 8 components pass `unit` to `formatWeight`
- TotalsBar renders a g/oz/lb/kg toggle
- Clicking a toggle button calls `useUpdateSetting` with key "weightUnit"
- No `formatWeight` call site in src/client/ is missing the unit argument (except the definition)
- All tests and lint pass
</done>
</task>
<task type="checkpoint:human-verify" gate="blocking">
<name>Task 2: Verify weight unit selection end-to-end</name>
<action>
Human verifies the complete weight unit selection feature works correctly across all pages.
Start the dev servers: `bun run dev:client` and `bun run dev:server`
Open http://localhost:5173 in a browser and walk through the verification steps below.
</action>
<verify>
1. Navigate to the Collection page -- verify the TotalsBar shows a g/oz/lb/kg toggle
2. The default should be "g" -- weights display as before (e.g., "450g")
3. Click "oz" -- all weight badges on ItemCards, CategoryHeaders, and the TotalsBar total should update to ounces (e.g., "15.9 oz")
4. Click "kg" -- weights should update to kilograms (e.g., "0.45 kg")
5. Click "lb" -- weights should update to pounds (e.g., "0.99 lb")
6. Navigate to the Dashboard (/) -- the Collection card weight should show in the selected unit
7. Navigate to a Setup detail page -- the sticky sub-bar weight total and all ItemCards should show the selected unit
8. Refresh the page -- the selected unit should persist (still showing the last chosen unit)
9. Switch back to "g" -- all weights should return to the original gram display
</verify>
<done>User confirms all weight displays update correctly across all pages, unit toggle is visible and functional, and selection persists across refresh. Type "approved" or describe issues.</done>
</task>
</tasks>
<verification>
- `bun test` passes (full suite, no regressions)
- `bun run lint` passes
- grep `formatWeight(` across `src/client/` shows all call sites have unit parameter
- Unit toggle is visible in TotalsBar on all pages that show it
- Selecting a unit updates all weight displays instantly
- Selected unit persists across page refresh
</verification>
<success_criteria>
- UNIT-01: User can select g/oz/lb/kg from the TotalsBar toggle -- visible and functional
- UNIT-02: Every weight display (ItemCard, CandidateCard, CategoryHeader, SetupCard, ItemPicker, Dashboard, Setup Detail, TotalsBar) reflects the selected unit
- UNIT-03: Weight unit persists across sessions via the existing settings API (PUT/GET /api/settings/weightUnit)
</success_criteria>
<output>
After completion, create `.planning/phases/07-weight-unit-selection/07-02-SUMMARY.md`
</output>