Skip to content

web+api: per-grade low-stock floors so the Dashboard's morning brief and stock ledger can warn #911

Description

@mforce

Component plan: build this from the components named in docs/designs/822-mui-revamp.md. The rule is "reused, never rebuilt" — composing MUI primitives into a screen wrapper is expected; reimplementing behaviour a shared component already has is not. Say in the PR which row of that table covers this screen.

Part of #674, Phase 3 follow-up. Filed by the owner during #906 (2026-09-19).

Why

The approved Operations Desk direction for the Dashboard (#906, Concept B) shows a low-stock fact in the morning brief and a Cracked row "visibly tied to its floor warning" in the Available Stock ledger. No stock floor exists anywhere today: StockResponse carries Available and Restricted only, the farm settings carry no threshold, and Dashboard.tsx records that a stock-floor attention source was proposed on #864 and not taken. #906 therefore omits both elements and records the omission; this issue supplies the data the design assumed.

Scope

  • Setting: a per-grade low-stock floor, in eggs, on the farm's grade catalog (Grades screen, Owner-only like the rest of farm configuration, Farm configuration and identity become Owner-only, matching spec §5.1 #729). Optional per grade; unset means no warning. Stored on the grade, not the account, so a renamed or deactivated grade keeps or drops its floor with it.
  • API: StockResponse gains the grade's floor and a BelowFloor flag computed from Available (not Available + Restricted; restricted eggs cannot be sold). No new endpoint.
  • Dashboard: the morning brief adds the low-stock fact ("N grades below floor", or the one grade by name when it is one) beside the unresolved-house fact; the stock ledger marks each below-floor row without relying on colour alone (a labelled mark plus text for assistive technology), which is what web: redesign Dashboard around the Operations Desk direction #906's design drew for Cracked.
  • Stock page: the same mark on the grade rows.
  • Audit: floor changes write through the existing grade-update audit action; no new vocabulary unless review finds one is needed.
  • Three locales for every new string; product glossary and Help updated for "low-stock floor" per the docs-in-sync rule.

Behaviour that must not change

The six-read Dashboard pipeline and independent panel degradation; the attention line's one-source rule for houses (this adds a second, separately sourced fact to the brief, not to that line, unless #906's shipped composition merged them, in which case follow #906); stock quantity and restriction semantics; role gates.

Acceptance criteria

  • Owner can set and clear a floor per grade; Manager and below cannot.
  • GET /stock reports the floor and the below-floor flag; integration test covers unset, above and below.
  • Dashboard morning brief and stock ledger, and the Stock page, render the warning from real data; unit tests pin the text and the non-colour mark.
  • Before/after captures at 1280x800 and 390x844, light and dark, 1:1, from a rebuilt stack.
  • The PR body contains Closes #NNN and the closing link is verified through GitHub's API.

Out of scope

Reopening #906 or #864; per-lot or per-house floors; notifications outside the Dashboard.

Activity

  1. added this to the SPA revamp milestone on Sep 19, 2026
  2. added
    enhancementNew feature or request
    epic-674SPA revamp — field-first phone, ledger desktop (#674)
    on Sep 19, 2026
  3. mforce commented on Sep 24, 2026

    @mforce
    OwnerAuthor

    Mockups: low-stock floors (design gate)

    These are mockups only. The lab is local at ~/.cluckwork-slices/911-lab/floor-direction-lab.html. The Dashboard side is already designed in #906.

    Sample data:

    • Large: floor 6,000.
    • Medium: no floor.
    • Small: floor 5,000, 680 short.
    • Cracked: floor 2,000, 500 short.

    Grades screen: where the floor is set

    Grades-A: a floor column, edited in the grade's Edit dialog. It adds one field to the existing dialog, and a new grade can get a floor when it is created.

    Grades-A, table, 1280 light
    Grades-A, Edit dialog, 1280 light
    Grades-A, phone

    Grades-B: a floor pill in the table, typed directly in the bottom panel. It is faster when setting many grades at once. It adds a second place to edit a grade, and a new grade has no floor until it is saved.

    Grades-B, table, 1280 light
    Grades-B, editing in the panel, 1280 light
    Grades-B, phone

    Stock screen: the warning

    Stock-A: a "⚠ Below floor" tag on the row, with "680 below the 5,000 floor" beneath it. Every row states its floor.

    Stock-A, 1280 light
    Stock-A, 1280 dark
    Stock-A, phone

    Stock-B: a summary band at the top ("2 grades are below their low-stock floor"), plus the same tag and a tinted row.

    Stock-B, 1280 light
    Stock-B, 1280 dark
    Stock-B, phone

    The design agent recommends Grades-A and Stock-B, with the band shrunk to one line on phones.

  4. mforce commented on Sep 24, 2026

    @mforce
    OwnerAuthor

    Owner decision, 2026-09-24:

    • Grades-A: a "Low-stock floor" column in the table, a read-only field in the inspector, and the floor edited in the existing grade create/edit dialog, where blank means no warning.
    • Stock-B: a board-level band ("N grades are below their low-stock floor", listing each grade and its shortfall), shrunk to its count line below 600px. Each below-floor row gets the "⚠ Below floor" tag, the shortfall line and the warm tint with a 4px --warn bar. The tag must not rely on colour alone.

    The mockups are in the comment above. The Dashboard side follows #906's approved design.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestepic-674SPA revamp — field-first phone, ledger desktop (#674)phase:3-screensScreen conversions

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions