Compare commits

..
Author SHA1 Message Date
TudorandClaude Opus 5 a75c5ab3c8 docs: revise the spec to the design that survived staging
The spec described the tier system as the design of record. It is gone, so
the document was describing something the code deliberately does not do.

The revision note and the "why not, having built it the other way first"
passage are kept rather than overwritten. The mistake is the instructive part:
treating a preference as a constraint inverted the ranking, and the stopping
rule added to prevent weak distant matches is what guaranteed six Catholic
schools and no community school down the road. A spec that quietly presents the
second design as the plan teaches nobody why the first one failed.

The mockup link is annotated as one revision behind rather than silently left
to look current.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-22 12:00:21 +01:00
TudorandClaude Opus 5 b650df8d93 refactor: rename similar → nearby, so the code says what the section does
The section ranks on distance and is headed "Other schools nearby", but every
identifier still called it "similar" — the exact drift that leaves a later
reader trusting a name over the behaviour.

Mechanical: files, the module, the payload key, the type, the components, the
prop. No behaviour change; the suites are unchanged in count and still green.
Free to do now because #150 has not merged, so the payload key rename needs no
lockstep deploy. Uses of "similar" that are ordinary English — progress
measures compared to similar pupils, and unrelated comments — are untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-22 11:59:27 +01:00
TudorandClaude Opus 5 179b6fec94 fix: order nearby schools by distance, not by how alike they are
Reported from staging: a Catholic primary showed six Catholic primaries, none
of them close enough to be a real option, and omitted the community school
down the road.

Three causes, compounding. Ranking put tier before distance, so a faith match
at 2.9 miles outranked a community school at 0.3. The ENOUGH=3 stopping rule —
added so a cap of six would not drag in weak distant matches — filled the row
from the best tier before it ever widened, which is what made every card
Catholic. And a 3-mile tier-1 radius is sane for a secondary and most of a city
for a primary, whose catchments are routinely under a mile.

The premise was backwards. For a parent, distance is a constraint and intake is
a preference; a school beyond a primary catchment is not a weaker option, it is
not an option. So distance now decides the order and nothing else does. The
hard filters are untouched — they were always where the defensibility lived.
Similarity survives as chips on the card: reported, so a reader applies their
own weighting, rather than ranked, so we apply ours for them.

Reach is capped per phase (primary 2, secondary 6, post-16 10) as a sanity
bound, not a target: ordering already handles density, so the cap only decides
what happens where an area is sparse. A primary with nothing inside two miles
now renders no section, which is the honest answer.

Deleted: the tier system, the stopping rule, the tier-dependent lede, the
`tier` field, the tier-3 fallback chip and its style. select_similar also stops
taking is_secondary — it reads the phase from the subject's own row, so no
caller can hand it one that disagrees with the data.

The heading is now "Other schools nearby". The hard filters still guarantee a
comparable set, but nothing ranks on likeness, so the heading no longer says it
does.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-22 11:58:36 +01:00
3 changed files with 8 additions and 106 deletions

No files matched your search

+7 -87
View File
@@ -1,4 +1,4 @@
import { test, expect, Locator, Page } from '@playwright/test';
import { test, expect, Page } from '@playwright/test';
/**
* Journey tests for SchoolCompare, run against the staging environment as the
@@ -19,31 +19,6 @@ function schoolLinks(page: Page) {
return page.locator('a[href^="/school/"]');
}
/**
* A scroll offset that has stopped moving.
*
* The carousel arrows scroll with `behavior: 'smooth'`, so a reading taken
* straight after a click lands mid-animation. Measured against staging: the
* animation runs ~700ms, and a poll for "has it moved at all" is satisfied
* 50ms in, at 13px of a 1300px journey. A test that then records an offset,
* does something, and records again is measuring the tail of the arrow's
* animation rather than the effect of whatever it did in between.
*
* Two identical readings in a row is the cheapest sound definition of settled.
*/
async function settledScrollLeft(scroller: Locator): Promise<number> {
let previous = -1;
await expect
.poll(async () => {
const current = await scroller.evaluate((node: HTMLElement) => Math.round(node.scrollLeft));
const settled = current === previous;
previous = current;
return settled;
}, { timeout: 10_000 })
.toBe(true);
return previous;
}
/**
* Two URNs guaranteed to be pure-primary (same phase). The compare page's
* phase tabs split all-through schools (which carry KS4 data) onto the
@@ -2801,75 +2776,20 @@ test('nearby schools link on to other schools and into compare', async ({ page }
await expect(back).toBeDisabled();
await forward.click();
expect(await settledScrollLeft(scroller)).toBeGreaterThan(8);
await expect
.poll(() => scroller.evaluate((node: HTMLElement) => node.scrollLeft))
.toBeGreaterThan(8);
await expect(back).toBeEnabled();
}
// The compare hand-off, and the row must not jump back to the start when the
// footer re-renders underneath it.
//
// Click the LAST card's button, not the first. Playwright scrolls a target
// into view before clicking it, so clicking card one while the row is paged
// to the end scrolls the container back to the start — and the assertion
// below then measures Playwright's own scrolling rather than the app's.
// That is what this test did on its first staging run: 537 → 2, reproduced
// afterwards on a static page with no React on it at all.
//
// A few pixels of snap or sub-pixel adjustment are fine; a reset to the
// start is not, which is the whole point of the check.
const offsetBefore = await settledScrollLeft(scroller);
await section.getByRole('button', { name: /Add to compare/ }).last().click();
const offsetBefore = await scroller.evaluate((node: HTMLElement) => node.scrollLeft);
await section.getByRole('button', { name: /Add to compare/ }).first().click();
await expect(
section.getByRole('button', { name: /Added to compare/ }).first(),
).toBeVisible();
const offsetAfter = await settledScrollLeft(scroller);
expect(Math.abs(offsetAfter - offsetBefore)).toBeLessThanOrEqual(8);
});
/**
* Every section in the mobile jump sheet can actually be reached.
*
* The sheet is a fixed bottom sheet, and the app has a fixed bottom tab bar.
* `position: sticky` with a z-index on the sticky nav makes it a stacking
* context, so the sheet's own z-index orders it only within that context —
* against the tab bar, the nav's value is what counts. The last item in the
* sheet was therefore painted over and untappable as soon as the list grew
* long enough to reach the bar, which adding "Nearby schools" is what did.
*
* Bounding boxes are not enough to catch this: the item is in the viewport and
* the right size, it is simply underneath something. So this asks the question
* a thumb asks — what is on top at this point.
*/
test('every section in the mobile jump sheet is tappable, not under the tab bar', async ({ page }) => {
await page.setViewportSize({ width: 390, height: 844 });
await searchByName(page, 'Primary');
await schoolLinks(page).first().click();
await page.waitForURL(/\/school\//);
// Scroll down so the sticky nav is docked and the sheet has somewhere to open.
await page.evaluate(() => window.scrollTo({ top: 1200 }));
// Two controls carry aria-haspopup: the mobile "Section" button and the
// desktop "All" one, which is display:none here but still in the DOM.
await page.locator('[aria-haspopup="menu"]:visible').click();
const sheet = page.locator('[role="menu"]');
await expect(sheet).toBeVisible();
const covered = await sheet.evaluate((panel: HTMLElement) =>
Array.from(panel.querySelectorAll('[role="menuitem"]'))
.map((el) => {
const box = el.getBoundingClientRect();
const hit = document.elementFromPoint(
Math.round(box.left + box.width / 2),
Math.round(box.top + box.height / 2),
);
return { label: (el as HTMLElement).innerText.trim().replace(/\s+/g, ' '), reachable: !!(hit && hit.closest('[role="menuitem"]')) };
})
.filter((item) => !item.reachable)
.map((item) => item.label),
);
expect(covered).toEqual([]);
expect(await scroller.evaluate((node: HTMLElement) => node.scrollLeft)).toBe(offsetBefore);
});
/**
@@ -283,21 +283,6 @@
}
/* `position: sticky` with a z-index makes .sectionNav a stacking context, so
the jump sheet's own z-index only orders it INSIDE that context. Against the
fixed bottom tab bar (Navigation.module.css, z-index 1000) what counts is
.sectionNav's 10 — which is why the sheet's last item was painted over, and
untappable, once the list grew long enough to reach the bar.
Lifted only while the sheet is open, and only to 1100: above the bar, below
the comparison toast (2000), the fullscreen map (5000) and the info popover
(9999). This rule carries the z-index and nothing else; every other
declaration belongs to .sectionNav in both states. */
.sectionNavSheetOpen {
z-index: 1100;
}
.sectionNavBack {
flex: none;
display: inline-flex;
@@ -344,10 +344,7 @@ export function SchoolDetailShell({
</header>
{/* Sticky Section Navigation — docks under the global header */}
<nav
className={`${styles.sectionNav}${sectionsOpen ? ` ${styles.sectionNavSheetOpen}` : ''}`}
aria-label="Page sections"
>
<nav className={styles.sectionNav} aria-label="Page sections">
<button onClick={scrollToTop} className={styles.sectionNavBack} aria-label="Back to top">
<span aria-hidden="true">↑</span>
<span className={styles.sectionNavBackLabel}>Top</span>