biggus-dickus/docs/superpowers/specs/2026-06-06-objects-table-and-shell-design.md

# Objects Data-Overview Table + Responsive Shell — Design

**Date:** 2026-06-06
**Status:** Approved (brainstorming) — ready for implementation planning.
**Issues:** #44 (object list → table); subsumes #58 (responsive layout) for the shell.

## Context

The Objects screen is where curators triage hundreds of records daily, but today
`web/src/objects/object-list.tsx` renders a **thin 20rem list** (object_number + name +
visibility badge) inside a master/detail grid, with no columns, sort, or filter. The
backend `GET /api/admin/objects` (`list_objects_paged`) takes only `limit`/`offset` and
orders by `object_number`. A *separate* `search-panel.tsx` (Meilisearch full-text, infinite
scroll, visibility filter) is a parallel browse UI with different ergonomics. Goal: a real,
scannable, sortable, filterable **data-overview table** plus a shell that adapts to viewport
width and gives every object a shareable URL.

### Facts established during exploration
- **Timestamps already exist.** The `object` table has `created_at` + `updated_at`
  (`migrations/0003_object.sql`); `updated_at` is set to `now()` on every write; the db layer
  already reads them into `CatalogueObject`. They are simply **not exposed in
  `AdminObjectView`** — so adding an "Updated" column needs *no migration*, just two fields on
  `AdminObjectView::from_object`.
- **Search is best-effort/optional** (`AppState.search: None` → the search endpoint 503s). So
  the **Postgres-backed list must remain the always-available browse surface**; full-text
  search is a layer on top, not a replacement.
- **No new dependencies needed:** `lucide-react` is already installed (nav icons); Base UI
  ships `drawer`, `collapsible`, and `tooltip` primitives (the slide-in detail + sidebar).

### Decisions (from brainstorming)
1. **Layout:** a Linear/email-style shell — collapsible **icon sidebar**; a **full-width
   objects table** as the overview; selecting a row opens detail as a **right-hand pane on
   wide viewports / a slide-in drawer when narrow**; **`/objects/:id` is a canonical,
   shareable URL**.
2. **Search:** **table-first.** The table gets Postgres-backed sort + visibility filter + a
   quick text filter (object number/name). The dedicated Meilisearch Search screen stays as-is;
   folding full-text into the table's search box is a **deferred follow-up**.
3. One milestone, **built in phases** (backend → table → shell/responsive/detail).
4. **Storybook** stories for meaningful new components (per the standing preference).

## 1. Shell: collapsible icon sidebar + responsive frame
`web/src/shell/app-shell.tsx`:
- The sidebar gains a **collapse toggle**; expanded = `w-44` (icon + label), collapsed = an
  icon rail (`~w-14`, icon-only). State persisted in `localStorage` (e.g. `sidebar-collapsed`).
- Each nav item (`objects`, `vocabularies`, `authorities`, `search`, `fields`) gets a
  `lucide-react` icon. When collapsed, the label is shown via a Base UI **`Tooltip`** on hover
  and as the `aria-label`/`title` for AT.
- Below a width breakpoint the sidebar **auto-collapses** to the rail (the user can still
  toggle). Nav `NavLink` active state + focus-visible rings preserved/added.
- This resolves #58 at the shell level (the per-screen master/detail responsiveness is handled
  in §3).

## 2. Objects table (`/objects`)
Replace the narrow list with a **full-width table** filling the main content area.

**Columns (default):** Object № (sortable) · Name (sortable) · Visibility (badge; filterable)
· Current location · # objects · Updated (sortable). Real `<table>` semantics with
`scope="col"` headers and `aria-sort` on the active sort column.

**Toolbar (above the table):**
- A debounced **quick text filter** (`q`) — Postgres `ILIKE` on `object_number` + `object_name`
  (always available; distinct from the Meili Search screen which searches descriptions/fields).
- **Visibility filter chips** (`all` / `draft` / `internal` / `public`), mirroring the search
  panel's pattern (honest `<button aria-pressed>`).
- The **New** button (right-aligned).

**Sorting:** clicking a sortable header toggles sort column + direction (server-side); default
`object_number asc` (today's order). Reflected in `aria-sort`.

**"Updated" rendering:** relative ("2d", "1w") with an absolute tooltip, formatted in the
instance timezone/locale via `Intl` (`useConfig().default_timezone` + active language).

**Pagination (footer):** `from–to of total`, prev/next, and a **page-size selector**
(25/50/100/200 — backend caps at 200). Keep the **offset** model (it supports sort + a true
total cleanly; infinite scroll does not).

**URL-synced state:** `q`, `visibility`, `sort`, `order`, and the page offset live in the URL
query string (the search panel already does this for `q`/`visibility`). This makes the table
shareable, back-button-friendly, and preserves position across the row→detail→back round-trip.

**Row interaction:** click navigates to `/objects/:id` (canonical); the selected row is
highlighted; keyboard-navigable.

## 3. Detail presentation + canonical URL (`/objects/:id`)
- `/objects/:id` is the **canonical, shareable** address — opening the link loads the table and
  reveals that object's detail.
- **Wide viewport:** detail renders as a **right-hand pane** beside the (compressed) table.
  **Narrow viewport:** detail **slides in from the right as a Base UI `Drawer`** over the table,
  with a backdrop. A close affordance returns to `/objects`, table state preserved via the URL.
- Implementation: nested routing — the `/objects` route renders the table; an `:id` child
  controls the pane/drawer (presence of `:id` opens it). The pane-vs-drawer switch is by
  viewport width (CSS breakpoint / a `matchMedia` hook); the `Drawer` is used only at narrow
  widths.
- **Reuses the existing `ObjectDetail`.** Its *content* improvements (resolving
  term/authority/`localized_text` to labels, grouping by field group) are **issue #45** and
  explicitly out of scope here — this milestone changes where/how detail is presented, not its
  internals.

## 4. Backend contract (`crates/api/src/admin_objects.rs`, `crates/db/src/catalog.rs`)
- **Query params on `GET /api/admin/objects`:** `sort` (enum: `object_number` |
  `object_name` | `updated_at` | `created_at` | `visibility`; default `object_number`),
  `order` (`asc` | `desc`; default `asc`), `visibility` (optional filter: draft|internal|public),
  `q` (optional text). All optional; absent → today's behavior.
- **`list_objects_paged`** extended to accept the sort column + direction + filters. Build
  `ORDER BY` from the **whitelisted enum** (never interpolate a raw client string — SQL-injection
  safe) and `WHERE` clauses for `visibility = $` and/or `(object_number ILIKE $q OR object_name
  ILIKE $q)`. **`count_objects`** takes the same filters so the total reflects the filtered set.
- **Expose timestamps:** add `created_at` + `updated_at` (RFC3339 strings) to `AdminObjectView`
  and `AdminObjectView::from_object` (values already present on the domain object). No migration.
- Gated by `ViewInternal` as today. Regenerate `web/src/api/schema.d.ts`.

## 5. Frontend data layer (`web/src/api/queries.ts`)
- `useObjectsPage` gains `{ sort, order, visibility, q, limit, offset }`; the query key includes
  them; use `placeholderData: keepPreviousData` so sorting/paging/filtering doesn't flash empty.
- A small `use-media-query`/`matchMedia` hook for the pane-vs-drawer breakpoint (if one doesn't
  already exist).

## Data flow
`/objects?sort=…&order=…&visibility=…&q=…&offset=…` → `useObjectsPage(params)` →
`GET /api/admin/objects?…` (Postgres, sorted/filtered, with filtered total) → table renders
columns + `aria-sort` + pagination. Row click → `/objects/:id` (URL carries the table state) →
detail pane (wide) or `Drawer` (narrow) over the table → close → `/objects?…` restored.

## Error handling / edges
- List load error / empty: reuse the existing error + empty states (standardized on `Skeleton`
  loading per #53 if convenient, else keep current).
- Invalid `sort`/`order`/`visibility` from a hand-edited URL: backend rejects unknown enum
  values (422) or the handler falls back to defaults; the frontend clamps to known values.
- Quick filter with no matches: empty-state message; pagination shows `0 of 0`.
- Deep-linking `/objects/:id` for a missing/deleted object: existing 404 handling
  (`useObject` → `objects.notFound`); the table still renders behind/beside.
- Narrow→wide resize while detail open: the pane/drawer swaps presentation without losing the
  selected `:id`.

## Testing
**Backend** (`#[sqlx::test]`, mirror `crates/api/tests/admin_catalog.rs`):
- `list_objects` honors `sort`+`order` (e.g. by `object_name desc`, by `updated_at`),
  `visibility` filter, and `q` ILIKE; the `total` reflects the filter; default (no params)
  matches today's `object_number asc`; an unknown `sort` value is rejected/falls back.
- `AdminObjectView` includes `created_at`/`updated_at`.
- OpenAPI regenerated.

**Frontend** (Vitest + RTL + MSW):
- Table renders the columns from a mocked page; a sortable header click updates the URL
  (`sort`/`order`) and re-queries with `aria-sort`; visibility chips + quick filter update the
  URL and query (debounced); pagination + page-size update offset/limit; row click navigates to
  `/objects/:id` and the table state (URL) is preserved on back.
- Sidebar collapse toggles + persists to `localStorage`; collapsed rail shows tooltips/labels.
- Detail presents as a pane vs `Drawer` per a mocked `matchMedia` width.
- en/sv parity for new keys; no `any`/`eslint-disable`; no codename.

**Storybook** (per the standing preference — meaningful interactive components):
- The table **row** (default / selected / various visibility), the **sortable column header**
  (idle / asc / desc), the **pagination control**, and the **collapsible sidebar** (expanded /
  collapsed). Mirror the established story format.

**Bundle:** `pnpm check:size` — index chunk ≤ **165 KB gz** (lucide icons + any newly-used Base
UI primitives land in the always-loaded shell; tree-shaken lucide imports keep this small —
verify).

## Acceptance criteria
1. `/objects` is a full-width, scannable table (№, name, visibility, location, count, updated)
   with server-side sort, a visibility filter, and a quick text filter — all state in the URL.
2. Pagination has prev/next + a page-size selector + a true (filtered) total.
3. The sidebar collapses to an icon rail (persisted) and auto-collapses on narrow viewports.
4. Selecting a row opens detail as a right pane (wide) or slide-in drawer (narrow);
   `/objects/:id` is a canonical shareable URL that opens that object directly.
5. Backend exposes `created_at`/`updated_at` and supports `sort`/`order`/`visibility`/`q`
   (injection-safe, filtered total); OpenAPI regenerated.
6. Storybook stories for the row/header/pagination/sidebar; cargo + web typecheck/lint/test/build
   green; index ≤ 165 KB gz; en/sv parity; no codename.

## Phasing (for the plan)
1. **Backend:** `sort`/`order`/`visibility`/`q` params + filtered count + expose timestamps +
   OpenAPI regen.
2. **Table:** full-width table, columns, sortable headers, filters, pagination + page-size,
   URL-synced state, `useObjectsPage` params (+ stories).
3. **Shell & detail:** collapsible icon sidebar (lucide + tooltip + persistence + auto-collapse),
   responsive detail pane/drawer, canonical `/objects/:id` routing (+ stories).

## Out of scope → follow-ups
- **Meilisearch full-text unified into the table's search box** (graceful fallback when search
  disabled) — deferred; the dedicated Search screen stays for now.
- **Object detail *content*** (term/authority/localized_text → labels, group-by-group) — **#45**.
- Multi-select / bulk actions (e.g. bulk visibility change); saved views/filters.
- Per-screen responsive work beyond the Objects shell (other master/detail screens) — remainder
  of #58.