docs/mathesar-local-storage-ui-review.md

Rama main · réplica de lectura del repositorio original.

# Mathesar automatic storage UI review

Independent review completed on 2026-10-05 using the
[dashboard checklist](ui-ux-checklist.md). The changed Mathesar storage flow is
approved for the tested presentation and interaction scope. No blocking visual
or interaction finding remains in that scope.

## Change and source coverage

The default **Media storage** choice is **Automatic local storage**. It requires
no storage-class name. **Existing shared storage** reveals a required **Shared
storage class** input. Switching back preserves the class draft while excluding
it from the automatic-storage request.

The former requirement to enter an RWX class before every Mathesar deployment
is historical. It applies only to the explicitly selected shared-storage mode.
The automatic choice creates an RWO media claim and places its consumers on one
node. The catalog and review explain that local disk is not replicated and
requires backups for node or disk loss.

Source inspection covered the Mathesar catalog metadata and blueprint,
`internal/spec/templates.go`, both template routes, `template-form.tsx`,
`template-requirements.ts`, the shared `SelectField`, form layout, help, error
and shell components. No dashboard application source needed changing.

## Evidence

- Successful capture: [Mathesar UI review run 37279102321](https://github.com/hakopod/hakopod/actions/runs/37279102321).
- PR head: `97b2b535eb8a8527edc9f63a8d86980205735302`.
- GitHub pull-request merge checkout recorded by the artifact:
  `1fdcbff1d0f6b72b2d258569bfc299a02d98c067`.
- Template catalog: `07cda41b2ca8e93f463f41c81990b4fd01cf78d5`.
- Artifact: `mathesar-ui-review`; 90 recorded observations, 60 screenshots,
  zero script or page errors.
- Local review copy:
  `.local/mathesar-ui-review/ci-97b2b53/evidence/`. Measurements are in
  `results.json`; original PNGs retain each state and theme in their names.
  Contact sheets and inspection crops are in its `visual-review/` directory.

The harness renders the real dashboard components. Template metadata,
normalized specifications, diffs and canonical TOML are generated by the Go
planner. Identity, project, secret metadata and failures are explicitly
artificial. External requests are blocked and no deployment is performed.

## Rendered coverage

Every row below passed at 1440, 390 and 320 pixels in both dark and Paper
themes. The browser viewport height was 1000 pixels; screenshots include the
full page.

| State | What was checked |
| --- | --- |
| Catalog | Loaded Mathesar card, logo, compact layout and keyboard entry |
| Inspector | Requirements, backup limitation, actions, Escape and focus return |
| Automatic configuration | Local default, no class input, review enabled after required values |
| Shared configuration | Conditional required class, review blocked until entered, visible keyboard focus |
| Existing PostgreSQL configuration | Host, port, database, role and TLS fields with automatic media storage |
| Failed review | Error notification and preservation of database/storage choices and entered values |
| Bundled PostgreSQL, local review | RWO media without a class; required secrets and canonical plan |
| Bundled PostgreSQL, shared review | RWX media with the selected class; required secrets and canonical plan |
| Existing PostgreSQL, local review | RWO media without a class and external database settings |
| Existing PostgreSQL, shared review | RWX media with the selected class and external database settings |

All 60 states were inspected in contact sheets. Full-resolution desktop forms,
mobile shared-storage fields, error states and the lower review/action areas
were inspected separately. The default choice and optional advanced path are
clear. Long help wraps inside the form; narrow selector labels truncate while
their named controls and complete popup choices remain available. Both themes
retain readable text, clear field boundaries and visible focus. Mobile actions
wrap vertically without clipping.

## Standing checklist result

This is the standing checklist scoped to the affected template routes.
Unrelated route or runtime checks are explicitly marked outside this pass.

### Layout and hierarchy

- [x] Shared page inset is 24px on desktop and 16px below 640px; nested wrappers do not add another page inset or width cap. Necessary card padding remains.
- [x] Heading dividers meet the content/viewport edges; titles retain the inset. Document width does not exceed viewport width.
- [x] Existing Tailwind layout is reused; no route-specific padding overrides were added.
- [x] Labels and controls align. Measured field bounds stay inside the viewport. Side-by-side Settings controls are outside this pass.
- [x] Page/form headings retain one title, necessary controls and named help, without decorative heading icons.
- [x] Help is keyboard reachable, opens through initial Shift+Tab focus and explicit Enter, dismisses with Escape, and toggles through touch inside mobile bounds.
- [x] Each loaded route has one h1. Nested back navigation stays in the shared header.
- [ ] Project-home defaults, inaccessible project scopes and cached application navigation are outside this pass; no related source changed.
- [x] Page-heading top and bottom padding are equal in the recorded geometry.
- [x] Catalog navigation uses the shared red text treatment, without a selected underline or background fill; focus remains visible.
- [ ] Deep-link navigation scrolling across unrelated route families is outside this pass.
- [x] Desktop header remains one row. Mobile header reflows without document overflow.
- [x] Catalog layout has no enclosing panel border; the sparse card retains its width and compact summary.
- [x] The existing catalog grid is unchanged and remains within the column cap; no application/service grid source changed.
- [x] Template navigation uses the shared action components. Captured footer/action bounds remain visible and at least 32px high.
- [ ] Application endpoint/alarm-link presentation is outside this pass.

### Components and interaction

- [x] Existing Hatch public components and theme tokens are reused; both dark and Paper were rendered.
- [x] Storage, architecture, database and TLS selection use `SelectField`; no visible native select was found.
- [x] Keyboard focus is visible. Catalog focus returns after Escape; class input and canonical code receive focus through keyboard traversal.
- [x] The configuration form is a dedicated nested page with associated labels and field help. The class becomes required only in shared mode.
- [x] All four combinations reach a distinct review before deployment. Missing secrets keep deployment disabled; failed review preserves values.
- [x] Capture waits for expected controls, loaded queries and fonts, with no unexpected loading, empty or error-boundary content.
- [x] The changed form's failed-request state, long values and narrow wrapping were checked. General loading, catalog-empty, denied and stale-data variants were not newly exercised in this pass.

### Data, safety and cost

- [x] Artificial identity/request states are labeled as development fixtures. Normalized plans are real Go output; screenshots claim no live deployment state.
- [x] No real secret is read or written. Required-secret blocking is exercised; server authorization and credential persistence are covered separately from this UI review.
- [x] The fixture records at most 128 requests and blocks external API calls. No product dependency, polling loop or runtime service was introduced by the UI work.
- [x] Storage choices and their consequences use plain English. Technical class details appear only when the user chooses existing shared storage.

## Findings resolved and limits

The source review found that catalog `notes` are not exposed by the template
API. The local-disk recovery limitation was moved into visible `requirements`,
so both the inspector and review display it.

Early capture attempts exposed harness synchronization mistakes: the URL
input's accessible name includes its help, a focus jump after review could
dismiss help during scrolling, and the script sent keyboard selection before
Radix transferred focus into the popup. The final harness uses the URL control,
natural initial help traversal plus explicit Enter activation, and observable
popup/focus/value waits. Each viewport/theme now reports failures independently;
failures are not skipped or converted to success.

Some full-page screenshots taken while scrolled include the normally offscreen
fixed skip link at the document scroll offset. Its source uses a negative
transform unless focused; the run independently confirms focus on the class
input/code. This full-page capture artifact is not evidence that the skip link
received focus. No screenshot-only product styling was added.

Canonical TOML equality and keyboard focus were checked for all 24 plan
reviews. This pass did not inspect every diff pagination page, operate a real
screen reader, test mobile software keyboards, or repeat the unrelated global
route matrix. It does not establish successful live provisioning, public
ingress, backup restoration or multi-node RWX operation. Runtime evidence and
its limits remain in the Mathesar blueprint acceptance record.

The final screenshots came from CI. The temporary local Vite/Chrome processes
and this review's local dependency/cache files were stopped or removed after
resource pressure prevented a reliable local run; source and evidence remain.