feat(web,analytics): /analytics route shell — date-range toolbar, trust header

[jakubretajczykBD]

Summary

Implements #1986: the /analytics route shell — page scaffold, date-range control, trust header, degradation banner. Zero revenue/order metrics (out of scope for this issue).

Plan: docs/plans/implementation-plan-analytics-page-shell.md
Pre-implementation gate: docs/plans/analysis/ANALYSIS-analytics-page-shell.md (READY)

Base branch is intentionally 1985-order-analytics-read-model, not main — see the plan's Decisions 3a/4, which reference #1985's schema and are pinned to be revisited once follow-up #1990 lands. (Decision 3's own dependency, #2083, has since shipped — see below.)

What's here

• New /analytics route + nav item, features/analytics module (API/types/hook/components), full test coverage
• Date-range toolbar: 7d/30d/90d/Custom presets (apply immediately) + From/To with a draft-buffered Apply (Decision 1)
• Trust header: per-connection freshness + "Data from" coverage window (real earliestOrderDate, [TASK] Backend — real per-connection earliest-order-date read for analytics-trust coverage window #2083) + status, with a click-triggered info popover
• Degradation banner: status-only for v1 (Decision 4) — the mockup's range-gated "sold in this selected range" refinement is a known, documented gap, deferred until [IMPL] Frontend — /analytics KPI strip + by-channel table #1990 gives an honest per-channel sales fact instead of an approximation. Tracked to be picked up once that backend work lands — not silently dropped.
• Fresh-instance / still-arriving / loading / error states

Known, deliberate gaps (see plan Decisions 3a/4 for full rationale)

• No "Backfilling" state — never-ingested is used as an approximation for "still arriving"
• Degradation banner does not yet check whether a stalled/disconnected connection actually sold anything in the visible date range — an operator-disabled connection with old, out-of-range sales will currently still surface a banner. Deferred to the same [IMPL] Frontend — /analytics KPI strip + by-channel table #1990 follow-up as above.

Test plan

• pnpm --filter @openlinker/web type-check clean
• pnpm --filter @openlinker/web lint clean (0 errors in touched files)
• pnpm --filter @openlinker/web test — not run this session, left for CI (per project convention)

Note

Open (not draft) — stacked on #2098, which is stacked on #1985. Not closing #1986 yet: this shell has no revenue/order metrics, and every other /analytics section (#1989/#1990/#1991) mounts on top of it.

[piotrswierzy]

Tech-lead review — ❌ Request changes (documentation obligations, not code defects)

Scope assessed: diffed against origin/1986-analytics-page-shell-plan — this PR's own base, not main. That isolates 32 files / ~1.7k lines: the /analytics route, the features/analytics slice, 101 lines of index.css, and plan docs. The 1985-… migration rename and order-record spec churn visible in the raw stat come from the base stack and are not assessed here.

A genuinely well-built route shell. Date range is URL state, the trust read is consumed honestly, tests are real, architectural hygiene is clean. What blocks is documentation-of-record.

BLOCKING

1. The cited mockup isn't reachable from this branch. analytics-date-range-toolbar.tsx:118 and the index.css trust-header block both cite docs/plans/mockups/analytics-ledger-2003.html as normative ("matches the mockup's own .gap-mark treatment verbatim", "frame 01"). That file is on neither main nor pr2115 — it's added by #2018, which is still open.

So this isn't a fabricated reference, it's a merge-order dependency — but as it stands the conformance claims are unverifiable by any reviewer, and I couldn't check the implementation against the Ledger package as I intended to. Either sequence #2018 first and rebase, or re-point the comments at what actually lands.

Worth knowing: I have open findings on #2018 that this PR is about to bake in. The sharpest is that DataTable's footer has no card-view answer, so on mobile the Total row and per-currency subtotals disappear entirely. If that's still unresolved when this builds, it ships that way.

2. docs/frontend-ui-style-guide.md isn't updated. § Density & Row Heights is explicit: "Never introduce a row height that isn't on this list without updating the guide first." index.css adds .trust-header__row — an auto-height grid row at var(--space-3) var(--space-4) padding, a new list-row surface with no entry (nearest neighbours are DataTable 36 px and Status banner ~64 px).

Two further additions are un-namespaced, generically-named and reusable, which makes them de-facto primitives with no catalogue entry: .info-popover-trigger (a 20×20 icon button with its own hover/focus treatment) and .gap-mark (the † marker). Either namespace them .analytics-* or document them.

IMPORTANT

3. analytics-page.tsx:33-40 — empty-dependency useEffect closing over from/to. The effect reads from, to, searchParams, setSearchParams but declares []. There's a prose comment ("Runs once on mount only") but no eslint suppression — and CLAUDE.md forbids a bare disable, so the fix is a disable with its reason inline. I couldn't confirm whether react-hooks/exhaustive-deps is error-level here because no CI has reported; worth running pnpm lint locally.

4. analytics-trust-header.tsx:47 — inline style={{ display: 'flex', … }}. The style guide's posture is that every surface is styled via index.css; this one-off escapes both the stylesheet and any future theme audit. Give it a class alongside the other new rules.

Suggestions

• date-range.lib.ts:48 — toUtcRangeInstants is exported with zero call sites (only the plan docs mention it). Dead code shipped ahead of #1990; drop it or leave it unexported until a consumer exists.
• AnalyticsTrustSnapshot.worstStatus is typed but never read. The per-connection banner covers the same ground, but a page-level one-line verdict is the cheapest possible use of a field the backend already computes.
• analytics-trust-header.tsx:97 — a trailing <span /> purely to fill the 4th grid column; a 3-column template says the same without a phantom element.

Worth calling out

• Date range is genuinely URL state (useSearchParams, :23), including writing resolved defaults back with { replace: true } so the resting state is a shareable link. Exactly right, and the thing most likely to have been done with useState.
• Honest states, no green default. STATUS_TONE maps disconnected → error, unknown → neutral, never-ingested → neutral — nothing falls back to success. Absent-data paths render distinct copy ("First orders are still arriving… Nothing is missing; it is not here yet"), and the #2083 earliest-order-date gap is disclosed in the header's own JSDoc rather than papered over with connectionCreatedAt — the popover copy even states connected-since "is not a claim about how far back its order history goes". That's the same conflation #2037 was blocked on, and it's pre-empted here.
• Colour never the only signal (StatusBadge withDot + text on every row); tokens throughout with zero raw hex in 101 new CSS lines; 0.8125rem / 0.6875rem are the guide's canonical body and eyebrow steps; mobile ≤767 collapses .trust-header__row to one column and wraps the toolbar.
• Dependency direction clean, feature barrel present, no raw fetch, no platformType dispatch, no any, lazy route split, six page-level tests plus per-component and per-lib tests.

CI: nothing has reported on a3e785e9 (total_count: 0). Nothing red — nothing run. Given finding 3, get lint + apps/web tests green on Node 22 before merge (Node 25 breaks ~63 of them via localStorage/happy-dom, and the suite flakes under full-suite parallelism — neither would be this PR's fault).

Merge readiness: ❌ Blocked on the style-guide entries and the mockup reference — both same-PR documentation obligations rather than code defects. Expect a small follow-up commit, not a rework. Targets 1986-analytics-page-shell-plan, so the stack lands in order.

[piotrswierzy]

Tech Lead re-review (head 83fce35d) — ❌ Request changes

Both of my prior blockers are genuinely resolved, and the way the first one was resolved is better than I asked for. But the branch has picked up new blockers, so I can't approve yet.

Blocker 1 (fabricated placeholder UI) — resolved, confirmed. Every hardcoded metric, mock series and fake delta is gone. The page now renders only the date-range toolbar plus states derived from one real read, GET /analytics/trust (shipped in #1982). I grepped the whole web delta for percentages, currency amounts, mock/sample/placeholder/dummy/TODO — every remaining hit is inside a *.test.tsx. No chart, no invented number. The empty states make no claims about the operator's data: "Connect a sales channel to see figures here" and "First orders are still arriving / Nothing is missing; it is not here yet." That second one is exactly the right register.

Blocker 2 (route/nav conventions) — resolved, confirmed. analytics.route.tsx follows the convention with lazy() + RouteCrumbHandle, is registered in coreChildren under AuthenticatedAppLayout like its siblings, and EXPECTED_LAZY_ROUTE_COUNT was updated 50 → 51 with the comment amended. The nav item is defensible now that the page shows a real read.

Blocker 3 (tests) — not resolved. The tests were written — 6 page tests covering loading / empty / still-arriving / healthy / degraded / error-with-retry, plus component, hook and lib suites — but two fail, and CI has never run on this PR at all (total_count: 0).

BLOCKING

1. The branch is red — 2 failing tests. Reproduced locally on Node 22.22.1, both failing in isolation, so this is neither the Node-25 happy-dom issue nor the full-suite parallelism flake:

• features/analytics/lib/date-range.lib.test.ts:16 — expects computePresetRange('90d', 2026-08-14) → from: '2026-05-16', gets '2026-05-17'. The implementation is right and the test is wrong: 2026-05-17 … 2026-08-14 inclusive is exactly 90 days; 2026-05-16 is 91. Consistent with the passing 7d/30d cases. Fix the expectation, not date-range.lib.ts.
• analytics-date-range-toolbar.test.tsx:72 — getByText('Order date †') fails because the chip splits that string across a text node and a nested <span>†</span> (analytics-date-range-toolbar.tsx:121-123). Needs a normalizer function matcher or a scoped textContent assertion.

(Four further suites errored on collection in my sandbox on an unresolvable posthog-js. That's an artefact of how the throwaway worktree symlinked node_modules, not a defect here — but it does leave those four unverified, which CI would settle.)

2. CI has produced zero check runs. The PR body's checklist leaves pnpm test unticked "for CI", and CI didn't pick it up — so nothing has ever executed this code. Please land a green run; the two failures above are exactly what it exists to catch.

IMPORTANT

3. analytics-date-range-toolbar.tsx:33 leaks schema jargon into operator-facing copy. ORDER_DATE_CAVEAT = 'placedAt is not a column and cannot be filtered today' reaches end users twice — as the † glyph's title, and inside the chip's aria-label, so a screen-reader user hears "Order date. placedAt is not a column and cannot be filtered today" as the control's name. An operator doesn't know what placedAt is. This is developer rationale; it belongs in the file header (where the same fact is already recorded), or rephrased for an operator if it must be visible.

4. "Current to" and "has not ingested since" are labelled off lastPollAt, which the backend explicitly says does not mean that. analytics-trust-header.tsx:72 renders lastPollAt under "Current to", and analytics-degradation-banner.tsx:38 renders "{name} has not ingested since {lastPollAt}". The DTO being mirrored is unambiguous (analytics-trust-response.dto.ts:50-53): lastPollAt is "a liveness signal for the ingestion pipe itself, not proof that any order data has arrived — see lastOrderIngestedAt for that." The honest field is fetched and typed (analytics-trust.types.ts:26) and never rendered. As written the header asserts data currency from a pipe-liveness value — the same class of false claim about the operator's data as the original placeholder-metrics blocker, just smaller. Either relabel to "Last polled" or render lastOrderIngestedAt on the recency row.

SUGGESTION

• :122 — the caveat sits on a bare title, not keyboard- or touch-reachable. shared/ui exports a Tooltip.
• analytics-page.tsx:24 / toolbar :40 — useRef(new Date()).current freezes "today" at mount, so a dashboard left open across midnight lights the wrong preset.
• date-range.lib.ts:5 — the header advertises "UTC-widening math"; the file has none (all formatting is local-time via formatDate). Stale from an earlier draft.
• The date range is written to the URL but consumed by nothing, so the presets and Apply look functional while changing no output. Acceptable for a shell, and the † gestures at it — but a plain-language line in the page description beats schema jargon in a tooltip.

Epic-shape check against #2018

I couldn't read #2018 (404 via the API), but on substance there's no premature commitment: analytics-trust.types.ts mirrors the already-shipped AnalyticsTrustResponseDto field-for-field (all 10 match, including connectionCreatedAt, expectedIntervalMs, staleAfterMs) and invents no metrics shape. No duplicate query layer either — analyticsTrust is one more namespace on the existing CoreApiClient, read through TanStack Query with a keyed factory. Whatever #2018 specifies for revenue/order series stays unconstrained.

Conventions

Clean throughout. Server state → TanStack Query; URL state → useSearchParams with resolved defaults written back via replace: true so the resting state is a shareable link; no ad-hoc global store; no raw fetch(); loading, error-with-Retry and two distinct empty states present; tokens only, zero raw hex; no any.

Merge readiness

❌ Not ready, and two of the reasons are outside the code. The base branch is 1986-analytics-page-shell-plan — not main, and not the 1985-order-analytics-read-model the body claims — so this cannot reach main until its base does, and the body is stale. The body also still reads "Draft PR — not closing #1986 yet, waiting for #1985 update" while the PR is open, non-draft, and carries no Closes #1986.

Fix the two test defects, land a green CI run, address findings 3 and 4, and reconcile the base/closing statement. Once those are done this is a genuinely good shell — the fabricated-UI problem is fully and thoughtfully resolved, which was the hard part.

[piotrswierzy]

Delta re-review (83fce35d → c9673175) — ❌ Request changes

Every code-level finding from the last round is genuinely fixed in the source. What's left is entirely process: CI has still never run, and the base/body state is unmergeable in any reading.

#	Status	Evidence
B1(a) 90d expectation	✅ and they fixed the correct side	date-range.lib.test.ts:16 changed '2026-05-16' → '2026-05-17'; date-range.lib.ts arithmetic untouched. Both previously-failing files run clean locally, 13/13
B1(b) split-text-node chip query	✅	Now getByText((_c, el) => el?.textContent === 'Order date †')
B2 zero CI check runs	❌ Not resolved	get_check_runs on c9673175 → total_count: 0; combined status pending, total_count: 0
I1 schema jargon in the a11y name	✅	ORDER_DATE_CAVEAT is now "This range doesn't filter results yet — coming soon"; the placedAt fact moved to a code comment tracked to #1990
I2 lastPollAt mislabelled	✅	Current to → Last polled; banner → has not been polled since / has never been polled; the popover now states outright it "is not proof that new order data has arrived". lastOrderIngestedAt stays fetched-and-unrendered, which the relabel makes honest rather than misleading
S bare title	✅	Replaced with the shared/ui Tooltip, tabIndex={0}, :focus-visible ring via var(--shadow-focus)
S stale "UTC-widening math" header	✅	Rewritten to "local-time, inclusive day ranges"
S frozen "today"	⬜ Not resolved	Still in two places now
Base branch	❌ Not resolved	Still 1986-analytics-page-shell-plan @ fd8a5ad2
PR body	❌ Not resolved	Still ends "Draft PR — not closing #1986 yet, waiting for #1985 update"

Spot-checked the two blockers resolved last round: both held. No fabricated UI reappeared — every rendered fact traces to ConnectionIngestionTrust. Route/nav conventions intact. Sweep for any, raw fetch(, raw hex across features/analytics and pages/analytics: zero hits. State ownership correct.

BLOCKING

1. CI has still never run on this PR, on any head. Two rounds of "left for CI (per project convention)" against a PR where CI produces nothing means nothing has ever been verified by the pipeline. I confirmed the two specific specs locally, but I ran on Node 25 — precisely the configuration known to break ~63 apps/web tests via localStorage shadowing — so my local run is not a substitute for a green suite. This needs a real signal before merge.

2. Base and body are unreconciled, and it's worse than a stale note. The diff against fd8a5ad2 carries commit 12e843d2 — "fix(orders): resolve migration timestamp collision and merge-broken tests (#1985)" — a migration rename plus two backend spec files. So this PR isn't only based on unlanded work, it's carrying a fix to it. The current state (non-draft, open, targeting a plan branch, body saying "Draft") can't merge under any reading. Pick one: retarget to main once #1985 lands, or return this to draft while it's stacked.

SUGGESTION

• analytics-date-range-toolbar.tsx:13 deep-imports the tooltip parts from ../../../shared/ui/tooltip because shared/ui/index.ts:58 re-exports only Tooltip. Widen the barrel and import like the neighbouring Button, SegmentedControl on the line above.
• useRef(new Date()).current is now duplicated in pages/analytics/analytics-page.tsx:24 and features/analytics/components/analytics-date-range-toolbar.tsx:45. Beyond freezing "today" at mount, the two mounts can now disagree with each other. Hoist to one source if it stays.
• The tooltip trigger is a <span tabIndex={0}> with no role, inside a chip that already carries the full aria-label — keyboard-focusable now, but a screen-reader user lands on an unlabelled stop. Either <button type="button"> styled flat, or aria-hidden on the glyph since the parent label already carries the caveat.
• The delta strips trailing commas from multi-line call arguments across four files. That matches .prettierrc ("trailingComma": "es5") but not how the rest of the repo's .tsx is committed — and format:check only globs {ts,js,json,md}, so .tsx is unchecked either way. Harmless and contained, but worth knowing before anyone runs Prettier more widely: this repo reformats ~1000 files on a broad glob.

CI: none — total_count: 0 on c9673175.

Merge readiness: ❌ three gates, none of them code: green CI, base retargeted (or back to draft), body rewritten to drop the stale "Draft PR" note and state the closing intent for #1986. The code itself is in good shape.

[piotrswierzy]

Delta re-review (c9673175 → 63ac38d9) — ❌ Request changes

Every code finding from the prior round is fixed, and the delta is a real improvement. I'm blocking on one non-code reason only, and it's the same one as last time.

Prior gate	Status	Evidence
G1 CI has produced zero check runs	❌ Not resolved	total_count: 0 on 63ac38d9; status pending, zero contexts. Third consecutive head with nothing ever verified
G2a base not main, body claimed the wrong branch	✅ documented	Base is still 1986-analytics-page-shell-plan, and the body now says so explicitly and correctly
G2b diff carried a fix to its own unlanded base	✅	12e843d2 is an ancestor of neither head nor base; the equivalent fix now lives in the base branch (183f1de4). The PR's diff is web + docs only — zero migrations, zero backend specs. Correctly relocated
G3 stale "Draft PR" note	✅	Now reads "Open (not draft) — stacked on #2098, which is stacked on #1985. Not closing #1986 yet…" — accurate and self-explaining
Original: fabricated placeholder metrics	✅ stays fixed	Grepped the full web diff for mock|sample|placeholder|dummy, percentages, currency amounts — every hit is test scaffolding or prose. No metric rendered anywhere
Original: route/nav conventions	✅ stays fixed	lazy(), RouteCrumbHandle, registered in root.route.tsx + nav-registry.ts, covered by route-lazy.test.ts

The delta itself is right. ConnectionIngestionTrust.earliestOrderDate replaces the connectionCreatedAt approximation in the "Data from" row, the popover copy was rewritten to describe the real fact rather than the old disclaimer, and the null case renders 'No orders yet' instead of a fabricated date — with a test pinning that branch. That's the same instinct as the lastPollAt relabel last round: state an ingested fact, not a proxy for one.

Consistency with the now-landed #2018 design package: checked, consistent. The mockup is on main and the shell's primitives line up — trust-header* class names, the "Data from" coverage row, the "About these dates" popover, the preset/Custom toolbar. Nothing needs reshaping.

BLOCKING

1. Nothing has ever run in CI, across three heads. The body's own test plan still shows pnpm --filter @openlinker/web test unchecked and "left for CI (per project convention)" — so the ~9 web test files this PR adds, including the new earliestOrderDate branch test, have not been executed by anyone, by your own account.

The likely cause is workflow branch/path filtering: every sibling PR that produces runs is based on main, and this one is based on a topic branch. That's a CI-configuration problem rather than a code problem — but it means this PR's correctness is unverified, which is exactly what I blocked on last round. Either get the workflow to trigger on this base, or retarget once the stack lands and let main's pipeline run it (which finding 2 requires anyway).

IMPORTANT

2. The merge-order dependency is now load-bearing on a type, not just on the plan. earliestOrderDate is a required, non-optional field on the FE ConnectionIngestionTrust (analytics-trust.types.ts:28), and the backend supplying it exists only in this PR's base chain — git grep earliestOrderDate origin/main -- apps/api libs/core returns nothing, while the same grep against the base hits the DTO, controller, core service and domain type.

So merging this shell ahead of the #1985 → #2098 → #2083 stack would render a "Data from" row backed by an absent field. That's a correct consequence of stacking rather than a defect, but it now has to be enforced at merge time — worth stating in the body beside the existing stacking note, since a reader of the body currently learns the stack order but not that it is a hard requirement.

SUGGESTION (all four prior items still open, all non-blocking)

3. analytics-page.tsx:24 and analytics-date-range-toolbar.tsx:45 both hold useRef(new Date()).current — two independently frozen "today" values that can disagree across midnight or if the toolbar remounts while the page doesn't. One owner passing today down removes the class of bug.
4. analytics-date-range-toolbar.tsx:13 deep-imports the tooltip parts because shared/ui/index.ts:58 re-exports only Tooltip. One-line barrel widening keeps the boundary honest.
5. :131 — the tooltip trigger is a <span tabIndex={0}> with no role, inside a chip that already carries the full aria-label, so a keyboard user tabs onto an unlabelled role-less stop. Dropping tabIndex is cleanest unless the tooltip carries content the chip label doesn't.
6. The URL range restores from/to on mount, but the toolbar derives no preset from it — so /analytics?from=…&to=… matching 30d exactly still lands on Custom rather than lighting 30d. Cosmetic; noting it so it's a decision rather than an oversight.

CI: none — total_count: 0 on 63ac38d9. I ran nothing locally: this machine is on Node 25, where apps/web has a known ~63-failure localStorage/happy-dom incompatibility, so a local result would carry no signal either way.

Merge readiness: ❌ not ready, for one non-code reason. Get a single green run — retargeting after the #1985/#2098/#2083 stack lands is the simplest route and is required anyway per finding 2 — and this flips to approve with the four suggestions optional.