docs(plans): typography page titles — 4-task plan (#57)
This commit is contained in:
@@ -0,0 +1,374 @@
|
|||||||
|
# Typography Hierarchy + Page `<h1>` + Per-Route `document.title` Implementation Plan
|
||||||
|
|
||||||
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||||
|
|
||||||
|
**Goal:** Give every AppShell route a consistent semantic page `<h1>` and a distinct browser-tab title (`"{Page} | {AppName}"`), via a small `PageTitle` component and a `useDocumentTitle` hook, and fix the one misused `<h3>` caption.
|
||||||
|
|
||||||
|
**Architecture:** A presentational `PageTitle` (`ui/page-title.tsx`) renders the styled `<h1>`. A `useDocumentTitle(page)` hook (`lib/`) composes `"{page} | {app_name}"` (app_name from `useConfig`), sets `document.title`, and restores the prior title on unmount — which lets a master-detail detail pane override the tab to the object's `object_number` and revert on close. Pages reuse existing i18n keys; no new strings, no new dependency.
|
||||||
|
|
||||||
|
**Tech Stack:** React 19 + TS + pnpm, Tailwind v4, react-i18next, react-router 7, Vitest + RTL + MSW + Storybook. Test runner: `pnpm test` (single pass).
|
||||||
|
|
||||||
|
**Conventions:** pnpm; **no `any`/`eslint-disable`/`@ts-ignore`**; no codename; reuse existing i18n keys (en/sv already in parity); source double-quote/semicolon, stories single-quote/no-semicolon; token classes only; **do not restructure layout/columns — only add the heading element + title hook**; guard `document` for jsdom.
|
||||||
|
|
||||||
|
**Spec:** `docs/superpowers/specs/2026-06-07-typography-page-titles-design.md`
|
||||||
|
|
||||||
|
**File structure:**
|
||||||
|
- `web/src/components/ui/page-title.tsx` (new) — `<PageTitle>` h1.
|
||||||
|
- `web/src/components/ui/page-title.stories.tsx` (new) — story.
|
||||||
|
- `web/src/lib/use-document-title.ts` (new) — the hook.
|
||||||
|
- `web/src/lib/use-document-title.test.tsx` (new) — hook test.
|
||||||
|
- Modify pages: `web/src/objects/objects-page.tsx`, `web/src/objects/object-new-page.tsx`,
|
||||||
|
`web/src/vocab/vocabularies-page.tsx`, `web/src/authorities/authorities-page.tsx`,
|
||||||
|
`web/src/fields/fields-page.tsx`, `web/src/search/search-page.tsx`.
|
||||||
|
- Modify `web/src/objects/object-detail.tsx` (detail title override).
|
||||||
|
- Modify `web/src/vocab/vocabulary-terms.tsx` (h3→div caption fix).
|
||||||
|
- Modify `web/src/auth/login-page.tsx` (document.title = app.name).
|
||||||
|
|
||||||
|
> NOTE: exact page file paths — verify with `git ls-files web/src | grep -E 'objects-page|object-new|vocabularies-page|authorities-page|fields-page|search-page|object-detail|vocabulary-terms|login-page'` before editing; the directory names above are from exploration but confirm.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Task 1: `PageTitle` component + story
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `web/src/components/ui/page-title.tsx`
|
||||||
|
- Create: `web/src/components/ui/page-title.stories.tsx`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Implement** `web/src/components/ui/page-title.tsx`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import type { ComponentProps } from "react";
|
||||||
|
|
||||||
|
import { cn } from "@/lib/utils";
|
||||||
|
|
||||||
|
export function PageTitle({ className, ...props }: ComponentProps<"h1">) {
|
||||||
|
return (
|
||||||
|
<h1
|
||||||
|
data-slot="page-title"
|
||||||
|
className={cn("text-2xl font-semibold tracking-tight", className)}
|
||||||
|
{...props}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Confirm the `cn` import path matches the other `ui/*` files (open `web/src/components/ui/button.tsx`
|
||||||
|
and copy its exact `cn` import — expected `@/lib/utils`).
|
||||||
|
|
||||||
|
- [ ] **Step 2: Write the story** `web/src/components/ui/page-title.stories.tsx`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import type { Meta, StoryObj } from '@storybook/react-vite'
|
||||||
|
import { expect } from 'storybook/test'
|
||||||
|
|
||||||
|
import { PageTitle } from './page-title'
|
||||||
|
|
||||||
|
const meta = {
|
||||||
|
component: PageTitle,
|
||||||
|
args: { children: 'Objects' },
|
||||||
|
tags: ['ai-generated'],
|
||||||
|
} satisfies Meta<typeof PageTitle>
|
||||||
|
|
||||||
|
export default meta
|
||||||
|
type Story = StoryObj<typeof meta>
|
||||||
|
|
||||||
|
export const Default: Story = {
|
||||||
|
play: async ({ canvas }) => {
|
||||||
|
await expect(canvas.getByRole('heading', { level: 1, name: 'Objects' })).toBeInTheDocument()
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
(Match the house story style — single quotes, no semicolons — as in `web/src/components/label-editor.stories.tsx`. Adjust the `Meta` import if that file imports it differently.)
|
||||||
|
|
||||||
|
- [ ] **Step 3: Run the story-as-test + typecheck + lint**
|
||||||
|
|
||||||
|
Run: `cd web && pnpm vitest run src/components/ui/page-title.stories.tsx && pnpm typecheck && pnpm lint`
|
||||||
|
Expected: PASS, clean.
|
||||||
|
|
||||||
|
- [ ] **Step 4: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add web/src/components/ui/page-title.tsx web/src/components/ui/page-title.stories.tsx
|
||||||
|
git commit -m "feat(web): PageTitle h1 component + story (#57)"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Task 2: `useDocumentTitle` hook + test
|
||||||
|
|
||||||
|
**Files:**
|
||||||
|
- Create: `web/src/lib/use-document-title.ts`
|
||||||
|
- Create: `web/src/lib/use-document-title.test.tsx`
|
||||||
|
|
||||||
|
- [ ] **Step 1: Confirm the config hook.** Open `web/src/config/config-context.ts` and confirm the
|
||||||
|
exported hook name and that it returns `app_name` (expected `useConfig()` → `{ app_name, ... }`).
|
||||||
|
Use the exact import path/name in the hook below.
|
||||||
|
|
||||||
|
- [ ] **Step 2: Write the failing test** `web/src/lib/use-document-title.test.tsx`:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { afterEach, expect, test } from "vitest";
|
||||||
|
import { render } from "@testing-library/react";
|
||||||
|
import "../i18n";
|
||||||
|
import { ConfigProvider } from "../config/config-provider";
|
||||||
|
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
|
||||||
|
import { useDocumentTitle } from "./use-document-title";
|
||||||
|
|
||||||
|
function Titled({ page }: { page: string }) {
|
||||||
|
useDocumentTitle(page);
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
function wrap(ui: React.ReactElement) {
|
||||||
|
const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
|
||||||
|
return render(
|
||||||
|
<QueryClientProvider client={qc}>
|
||||||
|
<ConfigProvider>{ui}</ConfigProvider>
|
||||||
|
</QueryClientProvider>,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
afterEach(() => {
|
||||||
|
document.title = "";
|
||||||
|
});
|
||||||
|
|
||||||
|
test("sets document.title to '{page} | {app_name}'", () => {
|
||||||
|
wrap(<Titled page="Objects" />);
|
||||||
|
expect(document.title).toMatch(/^Objects \| .+/);
|
||||||
|
});
|
||||||
|
|
||||||
|
test("restores the previous title on unmount", () => {
|
||||||
|
document.title = "Prev";
|
||||||
|
const { unmount } = wrap(<Titled page="Objects" />);
|
||||||
|
expect(document.title).toMatch(/^Objects \| /);
|
||||||
|
unmount();
|
||||||
|
expect(document.title).toBe("Prev");
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
NOTE: this assumes `ConfigProvider` supplies a default `app_name` synchronously (the spec says
|
||||||
|
`useConfig` defaults to `"Collection Management System"` before `/api/config` resolves). If
|
||||||
|
`ConfigProvider` needs MSW for `/api/config`, instead import `handlers` from `../test/handlers` and
|
||||||
|
set up an MSW server in the test (mirror an existing test that uses ConfigProvider). If a simpler
|
||||||
|
existing wrapper exists (check `web/src/test/render.tsx` — does `renderApp` include ConfigProvider?),
|
||||||
|
prefer that. Do NOT weaken the assertions; adapt the wrapper to provide config.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Run to verify it fails**
|
||||||
|
|
||||||
|
Run: `cd web && pnpm vitest run src/lib/use-document-title.test.tsx`
|
||||||
|
Expected: FAIL — cannot import `useDocumentTitle`.
|
||||||
|
|
||||||
|
- [ ] **Step 4: Implement** `web/src/lib/use-document-title.ts`:
|
||||||
|
|
||||||
|
```ts
|
||||||
|
import { useEffect } from "react";
|
||||||
|
|
||||||
|
import { useConfig } from "../config/config-context";
|
||||||
|
|
||||||
|
export function useDocumentTitle(page: string): void {
|
||||||
|
const { app_name } = useConfig();
|
||||||
|
useEffect(() => {
|
||||||
|
if (typeof document === "undefined") return;
|
||||||
|
const previous = document.title;
|
||||||
|
document.title = `${page} | ${app_name}`;
|
||||||
|
return () => {
|
||||||
|
document.title = previous;
|
||||||
|
};
|
||||||
|
}, [page, app_name]);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
(Adjust the `useConfig` import path/name to match what Step 1 found.)
|
||||||
|
|
||||||
|
- [ ] **Step 5: Run to verify it passes**
|
||||||
|
|
||||||
|
Run: `cd web && pnpm vitest run src/lib/use-document-title.test.tsx`
|
||||||
|
Expected: PASS (2 tests).
|
||||||
|
|
||||||
|
- [ ] **Step 6: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add web/src/lib/use-document-title.ts web/src/lib/use-document-title.test.tsx
|
||||||
|
git commit -m "feat(web): useDocumentTitle hook (restores prior title on unmount) (#57)"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Task 3: Wire `<PageTitle>` + `useDocumentTitle` into the list/form pages
|
||||||
|
|
||||||
|
**Files (modify):** `web/src/objects/objects-page.tsx`, `web/src/objects/object-new-page.tsx`,
|
||||||
|
`web/src/vocab/vocabularies-page.tsx`, `web/src/authorities/authorities-page.tsx`,
|
||||||
|
`web/src/fields/fields-page.tsx`, `web/src/search/search-page.tsx`.
|
||||||
|
|
||||||
|
For EACH page: read it first, add the imports
|
||||||
|
`import { PageTitle } from "@/components/ui/page-title";` (match the file's import style) and
|
||||||
|
`import { useDocumentTitle } from "../lib/use-document-title";` (verify the relative depth), call the
|
||||||
|
hook near the top of the component, and render `<PageTitle>` at the top of the page's content. Use the
|
||||||
|
i18n key from the table. **Do not restructure existing layout/columns** — only add the heading
|
||||||
|
element (and, if the page already has a top action row, place `<PageTitle>` on its left).
|
||||||
|
|
||||||
|
| File | i18n key | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| `objects-page.tsx` | `nav.objects` | Page already has a toolbar (filter, New button, pagination). Put `<PageTitle>` at the top-left of that toolbar row, or in a small header row above the table. |
|
||||||
|
| `object-new-page.tsx` | `objects.new` | Form page; `<PageTitle>` above the form. |
|
||||||
|
| `vocabularies-page.tsx` | `nav.vocabularies` | Two-column; `<PageTitle>` above the columns (full width). |
|
||||||
|
| `authorities-page.tsx` | `nav.authorities` | Tabbed; `<PageTitle>` above the tabs. |
|
||||||
|
| `fields-page.tsx` | `fields.title` | Two-column; `<PageTitle>` above the columns. |
|
||||||
|
| `search-page.tsx` | `nav.search` | Two-column; `<PageTitle>` above the columns. |
|
||||||
|
|
||||||
|
- [ ] **Step 1: objects-page.tsx** — add imports, `const { t } = useTranslation()` (it likely already
|
||||||
|
has `t`), `useDocumentTitle(t("nav.objects"))`, and render `<PageTitle>{t("nav.objects")}</PageTitle>`
|
||||||
|
at the top of the content. Keep all existing markup.
|
||||||
|
|
||||||
|
- [ ] **Step 2: object-new-page.tsx** — same pattern with `objects.new`.
|
||||||
|
- [ ] **Step 3: vocabularies-page.tsx** — same with `nav.vocabularies`.
|
||||||
|
- [ ] **Step 4: authorities-page.tsx** — same with `nav.authorities`.
|
||||||
|
- [ ] **Step 5: fields-page.tsx** — same with `fields.title`.
|
||||||
|
- [ ] **Step 6: search-page.tsx** — same with `nav.search`.
|
||||||
|
|
||||||
|
- [ ] **Step 7: Add/extend a page test.** In the existing test for objects (or create
|
||||||
|
`web/src/objects/objects-page.test.tsx` if none — check first), assert the `<h1>` and title:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
test("renders the page heading and sets the document title", async () => {
|
||||||
|
renderApp(/* the objects page route, mirroring the existing objects test setup */);
|
||||||
|
expect(await screen.findByRole("heading", { level: 1, name: /objects/i })).toBeInTheDocument();
|
||||||
|
await waitFor(() => expect(document.title).toMatch(/objects \| /i));
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
If an objects page/integration test already exists, ADD this assertion there using the same render
|
||||||
|
setup rather than duplicating the harness. Do not weaken existing assertions.
|
||||||
|
|
||||||
|
- [ ] **Step 8: Run the affected tests + typecheck + lint**
|
||||||
|
|
||||||
|
Run: `cd web && pnpm vitest run src/objects src/vocab src/authorities src/fields src/search && pnpm typecheck && pnpm lint`
|
||||||
|
Expected: PASS (existing tests unaffected by the added heading; the new assertion passes). If any
|
||||||
|
existing test breaks because a heading query is now ambiguous, investigate — the page `<h1>` text
|
||||||
|
should be distinct from row/cell content; do NOT weaken the test.
|
||||||
|
|
||||||
|
- [ ] **Step 9: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add web/src/objects/objects-page.tsx web/src/objects/object-new-page.tsx web/src/vocab/vocabularies-page.tsx web/src/authorities/authorities-page.tsx web/src/fields/fields-page.tsx web/src/search/search-page.tsx web/src/objects/*.test.tsx
|
||||||
|
git commit -m "feat(web): page <h1> + document.title on list/form routes (#57)"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# Task 4: Detail-pane title override, caption fix, login title + final gate
|
||||||
|
|
||||||
|
**Files (modify):** `web/src/objects/object-detail.tsx`, `web/src/vocab/vocabulary-terms.tsx`,
|
||||||
|
`web/src/auth/login-page.tsx`.
|
||||||
|
|
||||||
|
- [ ] **Step 1: Object detail title override.** In `web/src/objects/object-detail.tsx`, after the
|
||||||
|
object has loaded, call `useDocumentTitle(object.object_number)`. The hook must receive a real value
|
||||||
|
— only call it once `object` is loaded. Because hooks can't be conditional, call it unconditionally
|
||||||
|
with a guarded value, e.g.:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useDocumentTitle } from "../lib/use-document-title";
|
||||||
|
// ... inside the component, AFTER object data is available:
|
||||||
|
useDocumentTitle(object?.object_number ?? "");
|
||||||
|
```
|
||||||
|
|
||||||
|
But setting `" | App"` (empty page) while loading is undesirable. Prefer: keep the hook call
|
||||||
|
unconditional but pass the object_number only when loaded, and make the component not render/return
|
||||||
|
early before the data is present (check the existing structure — `object-detail.tsx` likely already
|
||||||
|
early-returns a loading/skeleton state). If it early-returns BEFORE the hook, that violates rules-of-
|
||||||
|
hooks. Resolve by either: (a) calling `useDocumentTitle(object_number)` only in the loaded branch by
|
||||||
|
splitting the component into an outer (fetch + loading) and an inner `ObjectDetailLoaded({ object })`
|
||||||
|
that calls the hook — RECOMMENDED; or (b) guarding inside the hook usage so loading sets nothing.
|
||||||
|
Choose (a): create an inner component that receives the loaded `object` and calls
|
||||||
|
`useDocumentTitle(object.object_number)`; the outer handles loading. Keep `object_name` as the
|
||||||
|
existing `<h2>`.
|
||||||
|
|
||||||
|
Verify `object_number` is the right field (read the component / the `AdminObjectView`/object type).
|
||||||
|
|
||||||
|
- [ ] **Step 2: Caption fix.** In `web/src/vocab/vocabulary-terms.tsx` around line 52, change the
|
||||||
|
`<h3 className="mb-2 label-caption">…</h3>` to `<div className="mb-2 label-caption">…</div>` (same
|
||||||
|
className/content; only the element changes). Confirm there is no CSS/test depending on the `h3`.
|
||||||
|
|
||||||
|
- [ ] **Step 3: Login title.** In `web/src/auth/login-page.tsx`, add a small effect:
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
import { useEffect } from "react";
|
||||||
|
// ... inside the component (t from useTranslation already present):
|
||||||
|
useEffect(() => {
|
||||||
|
document.title = t("app.name");
|
||||||
|
}, [t]);
|
||||||
|
```
|
||||||
|
|
||||||
|
(Do not use `useDocumentTitle` here — login is pre-auth/standalone.)
|
||||||
|
|
||||||
|
- [ ] **Step 4: Detail-override test.** Add (or extend an existing object-detail test) asserting the
|
||||||
|
document title reflects the object on the detail route and reverts on unmount. Mirror the existing
|
||||||
|
object-detail test's render/MSW setup (reuse `web/src/test/handlers.ts` + fixtures):
|
||||||
|
|
||||||
|
```tsx
|
||||||
|
test("object detail sets the tab title to the object number and reverts", async () => {
|
||||||
|
document.title = "Base";
|
||||||
|
const { unmount } = renderApp(/* object detail route, per the existing detail test */);
|
||||||
|
await waitFor(() => expect(document.title).toMatch(/<expected object_number from fixture> \| /));
|
||||||
|
unmount();
|
||||||
|
expect(document.title).toBe("Base");
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
Use the actual `object_number` from the existing object fixture (read `web/src/test/fixtures.ts` —
|
||||||
|
the `amphora` fixture). If reverting-on-unmount is awkward to assert through the full route, assert
|
||||||
|
the override (title contains the object_number) at minimum; do not weaken below that.
|
||||||
|
|
||||||
|
- [ ] **Step 5: FULL GATE (single test pass — run tests exactly ONCE):**
|
||||||
|
|
||||||
|
Run:
|
||||||
|
```bash
|
||||||
|
cd web && pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm check:size && pnpm check:colors
|
||||||
|
```
|
||||||
|
Expected: all green. Report test totals, largest chunk, check:colors line.
|
||||||
|
|
||||||
|
- [ ] **Step 6: Codename + status:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd /Users/olsson/Laboratory/biggus-dickus
|
||||||
|
git grep -in 'biggus\|dickus' -- web/src; echo "codename-exit=$?"
|
||||||
|
git status --short
|
||||||
|
```
|
||||||
|
Expected: no codename matches.
|
||||||
|
|
||||||
|
- [ ] **Step 7: Manual smoke (recommended).** `pnpm dev`: each route shows a page `<h1>`; the tab title
|
||||||
|
reads "{Page} | {AppName}"; opening an object changes the tab to the object number and closing it
|
||||||
|
reverts; exactly one `<h1>` per page.
|
||||||
|
|
||||||
|
- [ ] **Step 8: Commit**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add web/src/objects/object-detail.tsx web/src/vocab/vocabulary-terms.tsx web/src/auth/login-page.tsx web/src/objects/*.test.tsx
|
||||||
|
git commit -m "feat(web): object-detail tab title, caption element fix, login title (#57)"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Self-Review (completed)
|
||||||
|
|
||||||
|
**Spec coverage:** PageTitle h1 component (T1); useDocumentTitle hook with restore-on-unmount (T2);
|
||||||
|
per-route h1 + title on objects/object-new/vocabularies/authorities/fields/search reusing existing
|
||||||
|
keys (T3); detail-pane `object_number` override + revert (T4 S1); h3→div caption fix (T4 S2); login
|
||||||
|
title (T4 S3); one h1 per page preserved (list owns h1, detail keeps h2 — T3/T4); tests for component,
|
||||||
|
hook, page, and override (T1/T2/T3/T4); gate + no codename + no new dep + no new strings (T4). All
|
||||||
|
acceptance criteria 1–6 mapped. ✓
|
||||||
|
|
||||||
|
**Placeholder scan:** the only non-literal spots are render-harness reuse ("mirror the existing test
|
||||||
|
setup") and the object fixture's `object_number` ("read fixtures.ts") — these are deliberate "match
|
||||||
|
the existing pattern" instructions with concrete files named, not TODOs. The rules-of-hooks resolution
|
||||||
|
for object-detail (split into inner loaded component) is spelled out. ✓
|
||||||
|
|
||||||
|
**Type consistency:** `PageTitle` is `ComponentProps<"h1">`; `useDocumentTitle(page: string)` defined
|
||||||
|
in T2 and called with `t(key)` (string) in T3 and `object.object_number` (string) in T4;
|
||||||
|
`useConfig().app_name` is the title's app-name source throughout. ✓
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
- No new dependency, no new i18n strings (all keys exist in en/sv).
|
||||||
|
- The restore-on-unmount in `useDocumentTitle` is load-bearing for the master-detail override — keep it.
|
||||||
|
- Verify exact page file paths first (the NOTE under File structure); adjust import depths accordingly.
|
||||||
Reference in New Issue
Block a user