feat(scheduling): coverage chart explainer — split demand vs floor, on-chart SPLH slider, arithmetic receipt - #650

…age chart spec

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Type-only change (task 1.1 of coverage-chart-explainer plan). Adds the
raw pre-floor demand field so downstream code (staffingCalculator,
coverageSummary, coverage chart) can distinguish demand-short from
floor-short hours. Population lands in the next task.

Threads raw demand = ceil(avgSales/targetSplh) (0 when sales/targetSplh
<= 0) through buildHourlyRecommendations and derives recommendedStaff
as max(demand, minStaff) directly, instead of delegating to
calculateRecommendedStaff. Behavior-preserving for recommendedStaff;
demand is new and lets the coverage chart split demand-short from
floor-short later in this feature.

Task 1.2 of coverage-chart-explainer plan.

summarizeCoverageHours now copies rec.demand into CoverageHour.demand
(null when no rec for that hour, back-compat when recs are omitted)
and computes scheduledMax as the per-hour maximum headcount alongside
the existing conservative scheduled=min. Both are additive fields that
lay the groundwork for the demand/floor split in CoverageChart — needed,
delta, and all other CoverageHour semantics are unchanged, so buildVerdict,
mergeUnderStaffedRange, and summarizeAreaCoverage (demand=null path) are
unaffected.

TDD: added 4 RED tests (demand copied per hour; demand null with no
recs; scheduledMax = max of in-hour samples; scheduledMax = 0 with no
coverage), confirmed failing, then GREEN. Full unit suite (7318 tests)
+ typecheck + lint clean on touched files.

New pure module for coverage-chart presentation helpers. classifyHour(h,
minStaff) buckets an hour into crit/floor/spare/ok/nodata: nodata when
h.demand is null; otherwise derives needed = max(demand, minStaff) and
compares against scheduled. Deliberately independent of h.needed so it
stays correct under a hypothetical minStaff (e.g. settings-form preview)
that hasn't round-tripped through the recommendation pipeline.

TDD: 9 RED tests covering the five buckets plus boundaries (scheduled ===
demand, demand < minStaff pulling needed up to the floor, zero/zero/zero),
confirmed failing (module didn't exist), then GREEN. Typecheck + lint
clean on touched files.

impliedLabor({ wage, splh, targetLaborPct }) -> { pct, overTarget } computes
the on-chart SPLH slider's live labor-% readout (pct = wage/splh*100),
flagging overTarget once pct clears targetLaborPct by more than a 0.05-point
tolerance so a target hit within float noise doesn't flash red.

laborConsistentSplh({ wage, targetLaborPct }) = wage / (targetLaborPct/100)
gives the SPLH value at which the slider's track notch is drawn — where a
manager's own labor goal puts the knob.

TDD: 8 RED tests (pct math, overTarget boundary at target+0.05 from both
sides, inverse wage/SPLH relationship, targetLaborPct=100 edge), confirmed
failing (functions didn't exist), then GREEN. Targeted suite
(coverageChartModel + coverageSummary + staffingCalculator, 68 tests),
project-wide typecheck, and lint on touched files all clean.

buildReceipt(h, { minStaff, weekdayKey, wage, lookbackWeeks }) builds the
pinned receipt's ordered ledger rows plus contextual asides for a single
coverage column, per the design doc's worked example.

- nodata (demand === null): no rows, single explanatory aside referencing
  weekdayKey/lookbackWeeks/scheduled (replaces the old "N / 0" reading).
- otherwise: Avg {weekday} sales / ÷ target / = demand / min staff / needed /
  scheduled / kind-specific closing row (Short on demand | Short on floor |
  On target | Covered), each row tagged with a tone (default/critical/
  warning/positive) for the UI to color.
- "÷ target" is the implied target (round(projectedSales/demand)), not the
  live SPLH slider value — CoverageHour doesn't carry that raw value (only
  the already-folded demand), and the implied figure keeps the "sales ÷
  target = demand" line on the receipt exactly self-consistent (no hidden
  Math.ceil to explain). Omitted when demand === 0 (a rec exists but
  avgSales <= 0, so there's nothing to divide).
- Asides: implied SPLH at the scheduled count (skipped at scheduled === 0
  to avoid a divide-by-zero), the mid-hour scheduledMax->scheduled note
  (only when they differ), and the floor-only explainer.

Reuses classifyHour internally so the receipt's kind can never drift from
the chart's own classification.

TDD: 7 RED tests added (nodata; crit/floor/ok/spare row sets incl. the
design doc's own $503/17-people/$30 example, which also validated the
"implied target" derivation against the doc's illustrative numbers;
mid-hour aside presence boundary; demand===0 edge omitting the ÷ target
row), confirmed failing (function didn't exist), then GREEN.

Targeted suite (coverageChartModel + coverageSummary + staffingCalculator +
coverageChart component test, 103 tests), project-wide typecheck, and lint
(touched files) clean. Full 7300+-test unit suite was invoked but stalled
in the sandbox background scheduler without producing output after several
minutes (same intermittent issue noted on commit 31e39de/task 2.2); this
change only adds one new pure export with zero edits to existing exported
behavior, so it was not blocking.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… + windows list

chartSummaryLabel(hours, minStaff) rolls a day's CoverageHour[] into the
chart's accessible summary: an "N short on demand, M at the floor over K
hours" string for the sr-only <p>, plus an ordered understaffedWindows list
(one entry per crit/floor hour) feeding a sr-only <ul aria-label="Understaffed
windows"> — porting CoverageStatusStrip's screen-reader gap enumeration
guarantee onto the new chart (design doc, Phase 2.5 resolutions #1-#2).

Classifies every hour via classifyHour (not h.delta/h.needed) so counts and
windows always agree with the chart/receipt's own minStaff-aware
classification, even under a live settings-form minStaff preview.

TDD: 4 RED tests (rollup counts across crit/floor/ok/spare/nodata; singular
"1 hour" boundary; zero-shorts boundary with empty windows list; per-window
label/order/exclusion), confirmed failing (export didn't exist), then GREEN.
Full unit suite (584 files, 7346 tests passed, 2 skipped) + project-wide
typecheck + lint (touched files) clean.

Stage 3.1 of the coverage chart explainer redesign. CoverageChart.tsx is
now a single SVG chart with a real people y-axis, replacing the old
AreaColumn/DeltaColumn/Legend two-view toggle:

- Per hour: a scheduled bar (--primary), a solid demand slice
  (--destructive) when short of raw demand (crit), a dashed/hatched
  floor slice (--warning) covering the gap up to the minStaff floor
  (crit/floor), and a hatched nodata ghost via an SVG <pattern> for
  hours with no sales history (replacing the old misleading "N / 0").
  A `floor N` rule line marks minStaff across the plot.
- New props: minStaff, selectedStartMin, onSelect, onQuickAdd (type
  only — its UI affordance is Stage 3.3); `view`/`targetSplh` removed.
- Accessibility: role="toolbar" container (not role="img", which would
  flatten the interactive subtree) with role="option" columns, roving
  tabIndex (selected=0, rest=-1), ArrowLeft/ArrowRight to move
  selection, and a pure exported `columnAriaLabel` helper for each
  column's one-line summary. A sr-only <p> carries the
  chartSummaryLabel() rollup and a sr-only
  <ul aria-label="Understaffed windows"> enumerates every crit/floor
  hour, porting CoverageStatusStrip's screen-reader gap guarantee onto
  the new chart.
- All fills/strokes use hsl(var(--token)) semantic colors only; the
  floor slice's dashed stroke and the nodata hatch pattern give each
  state a texture, not just a color.

ShiftTimelineTab.tsx gets the minimal compatibility shim needed for the
new prop contract: a local selectedStartMin state, minStaff via the
existing computeMinStaffFromCrew(min_crew, min_staff), and
onQuickAdd={handleGapClick} (reusing the existing gap-click handler).
The coverageView state, Area/Delta ToggleGroup, and CoverageStatusStrip
render are intentionally left in place — their removal is bundled with
the full Stage 5 wiring (sliderTarget, avgWage, receipt panel) per the
design doc's "E. ShiftTimelineTab.tsx wiring" section, out of scope
here.

TDD: tests/unit/coverageChart.test.tsx fully rewritten (25 tests) to
target the new contract — column layout/alignment, roving-tabindex
keyboard nav, demand/floor SVG slice rendering, the nodata hatch
pattern, the floor rule, semantic-color-only assertion, the sr-only
summary/list, the four-swatch legend, and columnAriaLabel's per-kind
wording. Confirmed RED (23 failed) against the old component, then
GREEN. Full unit suite (584 files, 7343 tests, 2 skipped) + project-wide
typecheck + lint (touched files) clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…melineLane

CoverageChart's y-axis gutter already carried the sticky left-0 z-10
w-[120px] classes from Stage 3.1's SVG rewrite (mirroring TimelineLane's
sticky label column, design doc §Design-review resolutions #3), but no
test pinned that contract. Add a data-testid to the gutter and cover:
the required class set, DOM order (gutter before the scrollable
toolbar/plot region), tick rendering scoped to the gutter, and that the
plot columns remain aligned to minToPct with the wrapper in place.

RED: 3 of 4 new tests failed (data-testid didn't exist) against the
existing markup. GREEN: added the data-testid only, no layout changes.
Full unit suite (585 files, 7347 tests) + typecheck + lint (touched
files) clean.

…umns

CoverageChart tracks hovered/focused startMin and reveals a small "+"
button over crit/floor columns (only when onQuickAdd is supplied),
calling onQuickAdd(startMin) on click without triggering column
selection — preserving the one-click quick-add parity with the old
CoverageStatusStrip gap-click (design doc resolution #5). Omitting
onQuickAdd keeps the affordance hidden entirely (back-compat).

TDD: 5 RED tests (hidden without onQuickAdd; reveals + calls onQuickAdd
for crit; same for floor; never renders for spare/ok/nodata; hides on
mouseleave; accessible label names the hour), confirmed failing, then
GREEN. Full unit suite (585 files, 7353 tests passed, 2 skipped) +
project-wide typecheck + lint (touched files) clean.

Native range input (25-120, step 5) with a live implied-labor readout
(`→ X% labor at $W/hr`) + red/green pill from `impliedLabor`, a notch on
the track at `laborConsistentSplh` labeling where the manager's own
labor goal sits, a Reset button, and a manager-only Save button gated
by a caller-computed `canSave` prop with an `isSaving` pending state.
`aria-valuetext` carries the implied labor % alongside the native
`aria-valuenow`. Purely presentational — holds no staffing state of its
own; `onChange`/`onSave`/`onReset` let the eventual `ShiftTimelineTab`
wiring (Stage 5) own the slider/override/save state and re-run the
staffing pipeline live.

TDD: 11 RED tests (range bounds/value; onChange on drag; readout text;
pill wording+styling at both sides of the target+0.05 threshold; notch
value/label; Reset click; Save hidden for canSave=false, visible+wired
for true; Saving pending state disables the button; aria-valuetext
content), confirmed failing (module didn't exist), then GREEN. Full
unit suite (586 files, 7364 tests passed, 2 skipped) + project-wide
typecheck + lint (touched files) clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…-add + debounced aria-live)

New standalone panel rendering buildReceipt's ledger rows/asides for the
selected coverage-chart hour, with an "Add shift for this hour" action on
crit/floor hours (calls onQuickAdd(startMin); omitted onQuickAdd or an
ok/spare/nodata hour hides it, back-compat with the chart's own hover "+").

The visible ledger redraws live on every prop change (including SPLH-slider
drag frames once wired in Stage 5), but the aria-live="polite" region only
re-announces on commit (window pointerup/keyup) or on an actual hour-selection
change, per design doc §Design-review resolutions #4 — screen readers get one
coherent sentence per commit, not a stream of per-frame updates.

TDD: 11 RED tests (row/value rendering; nodata asides-only path; quick-add
present for crit/floor, calling onQuickAdd with startMin; absent for
ok/spare/nodata and when onQuickAdd is omitted; aria-live region content;
immediate announce on hour-selection change; frozen announce through a
same-hour "drag frame" until pointerup/keyup fires), confirmed failing (module
didn't exist), then GREEN. Full unit suite (587 files, 7375 tests passed, 2
skipped) + project-wide typecheck + lint (touched files) clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…eTab

Adds the SPLH slider's local preview state (design doc §B/§E, plan 5.1):
`sliderTarget` (null = follow saved settings) now feeds
`useWeekStaffingSuggestions`'s `settingsOverrides` argument via a new pure
`resolveSettingsOverrides` helper, replacing the hard-coded `null`. Also
destructures `updateSettings`/`isSaving` from the hook and derives `avgWage`
(computeAvgHourlyRateCents(employees)/100) alongside the existing `minStaff`
derivation — all four feed the SplhSlider/CoverageReceipt wiring landing in
the next task; none are rendered yet.

TDD: 3 RED tests for resolveSettingsOverrides (null passthrough, override
object, 0-is-not-null), confirmed failing (function didn't exist), then
GREEN. Full unit suite (588 files, 7378 tests passed, 2 skipped) +
project-wide typecheck + lint (touched files, 0 errors) clean.

…receipt (Stage 5.2)

ShiftTimelineTab now renders the coverage panel as a flex row: the
scrollable CoverageChart (header folds in CoverageVerdict/CoverageDemandInfo)
on the left, and a pinned CoverageReceipt outside the horizontal scroll on
the right (stacking below on mobile). Removes the coverageView state, the
Area/+/- ToggleGroup, and the CoverageStatusStrip render per design doc §E.

Quick-add entry point relocates from CoverageStatusStrip's gap cells to
CoverageReceipt's "Add shift for this hour" button (crit/floor hours only),
calling the same handleGapClick(startMin) — behavior unchanged, per §D.

Adds two pure helpers backing the receipt's default-hour selection:
- pickDefaultHour(hours, minStaff): worst crit hour by demand deficit
  (demand - scheduled), earliest startMin on ties, else first hour, else
  null for empty input.
- weekdayKeyForDay(day): noon-anchored weekday name for the receipt's
  "Avg {weekday} sales" row, matching the dayStringToDow DST-safety pattern.

Updates the one pre-existing overlay test whose click target was the
removed CoverageStatusStrip gap cell to go through the relocated
CoverageReceipt button instead, adding a `demand` field to its recommendation
fixture so the hour classifies as `crit` under the new demand-driven
classifyHour pipeline (previously only the legacy needed/delta pipeline
saw it as short).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…anager (Stage 5.3)

Mounts <SplhSlider> above the coverage chart in ShiftTimelineTab, wiring live
preview + Reset (available to every role) and Save (gated).

- Add SPLH_SAVE_ROLES = ['owner', 'manager', 'operations_manager'], mirroring
  the existing ad-hoc inline predicate already used in TimePunchesManager.tsx
  and Inventory.tsx (design doc §Design-review resolutions #6 — there's no
  shared role-gate helper for this style of check yet, so this follows the
  established convention rather than introducing a new one).
- canSaveSplhTarget reads selectedRestaurant?.role via useRestaurantContext()
  and is passed to SplhSlider's canSave prop, which hides the Save button
  entirely for non-gated roles while the range input (live preview) and Reset
  stay unconditionally available.
- handleSplhChange/handleSplhSave/handleSplhReset drive a local sliderTarget
  override; Save calls updateSettings({ target_splh }) then clears the
  override so subsequent renders read straight off activeSettings again.
- targetLaborPct sourced from activeSettings.target_labor_pct, falling back
  to the useStaffingSettings DEFAULTS value (22) before settings load.
- Slider is hidden entirely when there's no target to preview yet
  (targetSplh === null), matching the design doc's "No demand configured"
  state.

Tests (RED -> GREEN):
- New describe block in shiftTimelineTab.test.tsx: Save button shown for
  owner/manager/operations_manager, hidden (but preview+Reset kept) for
  staff/chef/kiosk/collaborator_accountant and for no-restaurant-selected,
  slider drag + Reset round-trip, Save persists via updateSettings, and the
  slider not rendering at all when activeSettings hasn't loaded.
- ShiftTimelineTab now calls useRestaurantContext() directly, so
  shiftTimelineTab.mobileLayout.test.tsx and shiftTimelineTabOverlay.test.tsx
  needed a `@/contexts/RestaurantContext` mock (defaulting to 'owner') to
  avoid the "must be used within a RestaurantProvider" throw.

Verified: full unit suite (588 files / 7397 tests, 2 skipped) green,
typecheck clean, lint clean on touched files.

Note for the eventual PR body (design doc requirement): the gated role set is
['owner', 'manager', 'operations_manager'].

…axis/chart/receipt (Stage 5.4)

The loading skeleton previously used generic bars unrelated to the new
coverage-panel layout (slider panel -> chart -> axis -> lanes, plus a
pinned receipt column). Reshaped it to mirror that structure exactly —
same lg:w-[320px] lg:shrink-0 receipt column, same top-to-bottom order
in the scrollable chart column — so nothing jump-shifts once real data
lands, per design doc resolution #9.

TDD: added a RED test asserting dedicated skeleton bands
(skeleton-splh-slider/-coverage-chart/-timeline-axis/-coverage-receipt),
the receipt band living in its own pinned column separate from the
chart/axis column, and slider-before-chart-before-axis DOM order;
confirmed failing against the old generic skeleton, then GREEN. Full
unit suite (589 files, 7398 tests passed, 2 skipped) + project-wide
typecheck + lint (touched files, 0 errors) clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Grep confirmed no production importer remained after Stage 5.2 folded its
gap-click/sr-only-enumeration duties into CoverageChart — only its own
dedicated test file still referenced it. Deleted both the component and
tests/unit/coverageStatusStrip.test.tsx, and cleaned up two now-stale
comments (coverageSummary.ts's formatCoverageHour doc, timelineComponents
.test.tsx's file-header note) that still named it as a live consumer.

TDD: confirmed the dedicated test suite green (14 tests) as baseline,
deleted the source file (RED — the test file's import failed to
resolve), then deleted the obsolete test file itself (GREEN). Full unit
suite (588 files, 7384 tests passed, 2 skipped) + project-wide typecheck
+ lint (touched files) clean.

…eededFor()

Math.max(demand, minStaff) was reimplemented 6 times across
coverageChartModel.ts (classifyHour, buildReceipt, chartSummaryLabel) and
CoverageChart.tsx (computePeak, columnAriaLabel, the SVG render loop).
Extracted a single exported neededFor(demand, minStaff) helper in
coverageChartModel.ts and pointed every call site at it. Pure refactor, no
behavior change — full unit suite (587 files, 7384 tests) unchanged.

Left staffingCalculator.ts's own Math.max(demand, minStaff) untouched: that's
a deliberately independent upstream computation (recommendedStaff), not the
presentation-layer "needed" derivation this helper centralizes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ic, maintainability, codex

- Memoize resolveSettingsOverrides(sliderTarget) so useWeekStaffingSuggestions
  doesn't recompute the whole week's staffing pipeline on every unrelated
  re-render (e.g. rAF drag-draft frames) while an SPLH preview is active
  (performance + sound-logic).
- Feed CoverageChart's selectedStartMin from the resolved selectedHour
  (pickDefaultHour fallback) instead of the raw click state, so the chart's
  roving-tabindex column always agrees with whichever hour the pinned
  receipt is showing, including before any explicit click (sound-logic).
- Fix handleSplhSave to only clear the slider override if it still matches
  the value just persisted, so a newer in-flight drag isn't silently
  discarded by an in-flight Save's resolution (sound-logic).
- Remove the redundant outer pl-[120px] wrapper around CoverageChart —
  CoverageChart already renders its own internal w-[120px] y-axis gutter, so
  the extra wrapper double-offset the chart against the axis ticks/lanes
  below (codex). AreaCoverageStrips has no internal gutter, so its
  pl-[120px] wrapper is unaffected and stays.
- Delete calculateRecommendedStaff (staffingCalculator.ts) and its dedicated
  test block — dead code since task 1.2 inlined its logic at the only call
  site; grep confirms zero remaining production callers (maintainability).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…r 2)

- coverageSummary.ts: a staffing rec with projectedSales <= 0 has no demand
  target to derive from (buildHourlyRecommendations floors its own demand to
  0 in that case). summarizeCoverageHours was passing that 0 through as a
  real "0 people needed" target instead of nodata, contradicting the design
  doc's own nodata definition ("no rec, or projectedSales ≤ 0").
- coverageChartModel.ts: guard impliedLabor/laborConsistentSplh against a 0
  splh/targetLaborPct denominator so a misconfigured or pre-bounds-check
  value degrades to 0 instead of Infinity/NaN in the labor readout.
- tests: cover both fixes, add the missing negative-sales case in
  staffingCalculator.test.ts, and prefix the touched staffing-calculation
  tests with CRITICAL: per coding guidelines. Fixed a stale test fixture in
  shiftTimelineTab.test.tsx (Task 2d wiring rec was missing the required
  `demand` field, which the coverageSummary.ts fix surfaced as NaN render
  warnings).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…sts (CodeRabbit iter 3)

Rename the added demand/floor test descriptions to the "should X when Y"
convention flagged by CodeRabbit for consistency and searchability.

The new SplhSlider renders a persistent "Save" button whose accessible
name collided with the shift-edit popover's own "Save" button, tripping a
Playwright strict-mode violation in timeline-edit-create.spec.ts. Add an
aria-label ("Save sales per labor hour target" / "Saving sales per labor
hour target"); visible text unchanged. Anchor the matching unit assertions
to /^save$/i so they target the popover button, not the slider.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Adds tests/e2e/coverage-chart-explainer.spec.ts covering the redesigned
coverage panel end-to-end against the real staffing pipeline:

- Seeds one $15/hr server + a mid-day shift + ~2 weeks of daily-spread
  sales so today's weekday has demand (~4/hr) against a lone scheduled
  server, guaranteeing demand-short (crit) columns.
- Asserts the single coverage chart (role="toolbar"), crit columns,
  the legend's demand-vs-floor split, the on-chart SPLH slider with its
  live implied-labor readout (default $60 → 25.0% at $15/hr) + over-target
  pill, the owner-visible Save button, and the pinned arithmetic receipt
  with its quick-add.
- Drives the slider via keyboard End/Home ($120 → 12.5% "On target";
  $25 → 60.0% "Over target") to prove the readout + pill update live.

Timezone pinned to UTC and wage fixed at exactly $15.00 for deterministic
percentages.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>