05 - Screen Inventory (Houses Module)
- 1. House List Screen (
/houses) - 2. House Detail Screen (
/houses/:id) - 3. House Editor (bottom sheet / dialog)
- 4. Member assignment surfaces (student module, cross-reference)
- Shared components used
- Analytics events (proposed)
- Keyboard, landscape, tablet, desktop
Every screen of the Houses module, its intent, route, composition, states, permissions, platform behavior and events. Authoritative components in 00-shared/03; this file enumerates which ones each screen uses with module specifics. States = idle / loading / success / empty / error(offline, conflict) / disabled / permission. Analytics events follow
{module}.{screen}.{action}(proposed; SDK open - 00-shared/10 §8).
1. House List Screen (/houses)
| Field | Detail |
|---|---|
| Purpose | Browse all houses as color-coded cards |
| Entry | Settings → School setup → Houses; deep link /houses |
| Exit | tap card → /houses/:id; "New house" → editor sheet; swipe-to-refresh |
| Source | GET /houses?page=1&limit=20 (houses.controller.ts:30-34) |
| Widgets | AppListPage shell, HouseColorCard grid (2-col phone / 3-col tablet), FAB "New house", AppSkeleton, AppEmptyState, AppOfflineBanner, AppPagination footer |
| States | loading skeletons; empty ("No houses yet - create your first"); error (offline banner + retry); conflict (409 inline toast from create) |
| Row actions | card tap → detail; AppMenu (ellipsis) → Edit / Delete on card (admin) |
| Permission | houses.read list; houses.create FAB; houses.update/delete menu (permissions.constants.ts:46-49) |
| Analytics | houses.list.open, houses.list.load, houses.list.error (proposed) |
| Notes | No server sort - display in createdAt order; color shown from color field, fallback default token (11 §3) |
2. House Detail Screen (/houses/:id)
| Field | Detail |
|---|---|
| Purpose | Full house identity + member roster |
| Entry | house list card tap |
| Exit | back; Edit → editor sheet; Delete → confirm; member tap → student detail (cross-module) |
| Source | GET /houses/:id (houses.controller.ts:36-40); members from students list (client join, (planned) GET /houses/:id/members) |
| Widgets | HouseHeader (color banner + name + code chip + motto), MemberTile list w/ count header, AppListTile, AppMenu (Edit/Delete), AppSkeleton, AppEmptyState ("No members") |
| States | loading; 404 ("House not found" → back + snackbar); members loading/empty/error (independent per-section state, 13 §4) |
| Permission | houses.read; edit/delete menu gated on houses.update/delete |
| Analytics | houses.detail.open, houses.detail.members.load (proposed) |
| Notes | Member section shows server-unsupported join: must render count as "unverified" until (planned) endpoint lands (09 §G1); delete warns about members (14 §4) |
3. House Editor (bottom sheet / dialog)
| Field | Detail |
|---|---|
| Purpose | Create or edit a house (single form, 08) |
| Entry | FAB (create) or Edit menu (update); never a route (00-shared/03) |
| Exit | Save → success → list/detail refresh; Cancel/dismiss → discard (confirm if dirty) |
| Source | POST /houses (houses.controller.ts:24-28) / PATCH /houses/:id (:42-46) |
| Widgets | AppFormField name/code, ColorPickerField, AppTextField motto, AppButton submit, AppBottomSheet/AppDialog |
| States | idle; submitting (button spinner); 409 conflict inline on code; 404 on update (house deleted meanwhile); offline → mutation blocked (00-shared/10 §2) |
| Permission | houses.create / houses.update |
| Analytics | houses.editor.open, houses.editor.submit, houses.editor.conflict (proposed) |
| Notes | PATCH quirk: body DTO is CreateHouseDto - name+code required on edit too (create-house.dto.ts:4-11); client prefills and submits full set (03 J1 step 5) |
4. Member assignment surfaces (student module, cross-reference)
Assignment is done in Students, not Houses (student.schema.ts:41-42):
- Student create form: house picker (optional,
create-student.dto.ts:39-42). - Student edit: house picker →
PATCH /students/:id(update-student.dto.ts:45-48). - No bulk-assign screen exists
(planned)(03 J2 frustration).
Shared components used
AppTextField, AppButton, AppSnackbar, AppCard, AppListTile, AppBottomSheet,
AppDialog, AppMenu, AppSkeleton, AppEmptyState, AppOfflineBanner, AppFAB,
AppChips, AppBadge, AppAvatar, AppPagination, AppListPage.
Module-specific: HouseColorCard, HouseHeader, MemberTile, ColorPickerField -
defined in 07_Component_Library.md.
Analytics events (proposed)
houses.list.{open,load,error}, houses.detail.{open,members_load},
houses.editor.{open,submit,conflict,delete} - all (proposed).
Keyboard, landscape, tablet, desktop
- Editor sheet scrolls with keyboard (
resizeToAvoidBottomInset); color picker wraps on landscape. - Tablet/desktop: master-detail list/detail; editor as dialog; color cards 3+ per row.
- List supports mouse hover highlight; detail members section max-width 720 dp.