From 1a961a38bcf253222edfde2a27dc29f27da4ca7e Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 2 Nov 2026 13:42:34 -0500 Subject: [PATCH 01/16] feat: add feed location directory Turn the Feeds header item into a dropdown (Search, Locations), add a Locations footer link, and add the /locations directory: continent > country > subdivision > municipality with GTFS / GTFS-RT / GBFS counts, breadcrumbs, and a paginated, relevance-sorted feed list using the search page's compact view. Also move the translation hook in SearchTable's data type cell into a component, so changing the number of rows no longer breaks the hook order. Co-Authored-By: Claude Opus 5.5 --- messages/en.json | 39 +- messages/fr.json | 39 +- .../locations/[[...location]]/page.tsx | 241 ++++++++ .../locations/components/FeedCountSummary.tsx | 85 +++ .../components/LocationBreadcrumbs.tsx | 60 ++ .../components/LocationChildrenGrid.tsx | 145 +++++ .../components/LocationFeedsList.tsx | 86 +++ .../locations/lib/location-directory-data.ts | 146 +++++ .../locations/lib/location-directory.spec.ts | 178 ++++++ .../locations/lib/location-directory.ts | 184 ++++++ src/app/components/Footer.tsx | 1 + src/app/components/Header.tsx | 60 +- src/app/components/HeaderFeedsMenu.tsx | 124 ++++ src/app/components/HeaderMobileDrawer.tsx | 65 ++- src/app/constants/Navigation.ts | 16 + src/app/screens/Feeds/SearchTable.tsx | 56 +- src/app/services/feeds/index.ts | 74 ++- src/app/services/feeds/types.ts | 189 +++++++ src/mocks/handlers.ts | 23 + src/mocks/locationDirectory.spec.ts | 77 +++ src/mocks/locationDirectory.ts | 532 ++++++++++++++++++ 21 files changed, 2351 insertions(+), 69 deletions(-) create mode 100644 src/app/[locale]/locations/[[...location]]/page.tsx create mode 100644 src/app/[locale]/locations/components/FeedCountSummary.tsx create mode 100644 src/app/[locale]/locations/components/LocationBreadcrumbs.tsx create mode 100644 src/app/[locale]/locations/components/LocationChildrenGrid.tsx create mode 100644 src/app/[locale]/locations/components/LocationFeedsList.tsx create mode 100644 src/app/[locale]/locations/lib/location-directory-data.ts create mode 100644 src/app/[locale]/locations/lib/location-directory.spec.ts create mode 100644 src/app/[locale]/locations/lib/location-directory.ts create mode 100644 src/app/components/HeaderFeedsMenu.tsx create mode 100644 src/mocks/locationDirectory.spec.ts create mode 100644 src/mocks/locationDirectory.ts diff --git a/messages/en.json b/messages/en.json index 8990e62d..3a7876ad 100644 --- a/messages/en.json +++ b/messages/en.json @@ -125,7 +125,9 @@ "metricsAdminOnly": "Metrics - Admin Only", "languageSelect": "Language select", "transitFeedsRedirectTitle": "You've been redirected from TransitFeeds", - "transitFeedsRedirectBody": "This page now lives on MobilityDatabase.org, where you'll find the most up-to-date transit data." + "transitFeedsRedirectBody": "This page now lives on MobilityDatabase.org, where you'll find the most up-to-date transit data.", + "locations": "Locations", + "feedsMenu": "Feeds menu" }, "emailVerification": { "loadingTitle": "Verifying your email", @@ -1254,7 +1256,8 @@ "contactUs": "Contact Us", "shareFeedback": "Share Feedback", "privacyPolicy": "Privacy Policy", - "termsAndConditions": "Terms and Conditions" + "termsAndConditions": "Terms and Conditions", + "locations": "Locations" }, "aria": { "github": "GitHub", @@ -1262,5 +1265,37 @@ "linkedin": "LinkedIn", "logo": "Mobility Database logo" } + }, + "locations": { + "root": "Locations", + "title": "Feeds by location", + "rootIntro": "Browse open GTFS Schedule, GTFS Realtime and GBFS feeds by continent, country, region and municipality.", + "nodeIntro": "{total, plural, =0 {No feeds are} one {# feed is} other {# feeds are}} located in {place}.", + "breadcrumbAria": "Location breadcrumb", + "feedCountsAria": "Feed counts by data type", + "shortLabels": { + "gtfs": "GTFS", + "gtfs_rt": "GTFS-RT", + "gbfs": "GBFS" + }, + "childrenHeading": { + "continent": "Continents", + "country": "Countries", + "subdivision": "Regions", + "municipality": "Municipalities" + }, + "childFeedTotal": "{count, plural, one {# feed} other {# feeds}}", + "feedsHeading": "Feeds in {place}", + "allFeedsHeading": "All feeds", + "resultsRange": "Showing {start}–{end} of {total} feeds", + "noFeeds": "No feeds are listed for this location yet.", + "paginationAria": "Feed list pages", + "meta": { + "rootTitle": "Transit Feeds by Location | Mobility Database", + "rootDescription": "Browse open GTFS Schedule, GTFS Realtime and GBFS transit and mobility feeds by continent, country, region and municipality.", + "nodeTitle": "{place} Transit Feeds | Mobility Database", + "nodeTitlePaged": "{place} Transit Feeds, Page {page} | Mobility Database", + "nodeDescription": "Browse {total} open transit and mobility feeds located in {place}: {gtfs} GTFS Schedule, {gtfs_rt} GTFS Realtime and {gbfs} GBFS." + } } } diff --git a/messages/fr.json b/messages/fr.json index 81336666..8c14b11c 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -125,7 +125,9 @@ "metricsAdminOnly": "Métriques - Admin uniquement", "languageSelect": "Sélection de la langue", "transitFeedsRedirectTitle": "Vous avez été redirigé depuis TransitFeeds", - "transitFeedsRedirectBody": "Cette page se trouve désormais sur MobilityDatabase.org, où vous trouverez les données de transit les plus récentes." + "transitFeedsRedirectBody": "Cette page se trouve désormais sur MobilityDatabase.org, où vous trouverez les données de transit les plus récentes.", + "locations": "Lieux", + "feedsMenu": "Menu des flux" }, "emailVerification": { "loadingTitle": "Vérification de votre e-mail", @@ -1254,7 +1256,8 @@ "contactUs": "Contactez-nous", "shareFeedback": "Donner un avis", "privacyPolicy": "Politique de confidentialité", - "termsAndConditions": "Conditions d'utilisation" + "termsAndConditions": "Conditions d'utilisation", + "locations": "Lieux" }, "aria": { "github": "GitHub", @@ -1262,5 +1265,37 @@ "linkedin": "LinkedIn", "logo": "Logo Mobility Database" } + }, + "locations": { + "root": "Lieux", + "title": "Flux par lieu", + "rootIntro": "Parcourez les flux ouverts GTFS Schedule, GTFS Realtime et GBFS par continent, pays, région et municipalité.", + "nodeIntro": "{total, plural, =0 {Aucun flux n’est situé} one {# flux est situé} other {# flux sont situés}} dans : {place}.", + "breadcrumbAria": "Fil d’Ariane des lieux", + "feedCountsAria": "Nombre de flux par type de données", + "shortLabels": { + "gtfs": "GTFS", + "gtfs_rt": "GTFS-RT", + "gbfs": "GBFS" + }, + "childrenHeading": { + "continent": "Continents", + "country": "Pays", + "subdivision": "Régions", + "municipality": "Municipalités" + }, + "childFeedTotal": "{count, plural, one {# flux} other {# flux}}", + "feedsHeading": "Flux dans : {place}", + "allFeedsHeading": "Tous les flux", + "resultsRange": "{start}–{end} sur {total} flux", + "noFeeds": "Aucun flux n’est encore répertorié pour ce lieu.", + "paginationAria": "Pages de la liste des flux", + "meta": { + "rootTitle": "Flux de transport par lieu | Mobility Database", + "rootDescription": "Parcourez les flux ouverts de transport et de mobilité GTFS Schedule, GTFS Realtime et GBFS par continent, pays, région et municipalité.", + "nodeTitle": "Flux de transport : {place} | Mobility Database", + "nodeTitlePaged": "Flux de transport : {place}, page {page} | Mobility Database", + "nodeDescription": "Parcourez {total} flux ouverts de transport et de mobilité situés dans : {place}. {gtfs} GTFS Schedule, {gtfs_rt} GTFS Realtime et {gbfs} GBFS." + } } } diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx new file mode 100644 index 00000000..4f62ee40 --- /dev/null +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -0,0 +1,241 @@ +import { type ReactElement } from 'react'; +import { type Metadata } from 'next'; +import { notFound } from 'next/navigation'; +import { Box, Container, Typography } from '@mui/material'; +import { getTranslations, setRequestLocale } from 'next-intl/server'; +import LocationBreadcrumbs, { + type LocationCrumb, +} from '../components/LocationBreadcrumbs'; +import FeedCountSummary from '../components/FeedCountSummary'; +import LocationChildrenGrid from '../components/LocationChildrenGrid'; +import LocationFeedsList from '../components/LocationFeedsList'; +import { + buildLocationHref, + buildPlaceName, + FEEDS_SECTION_ID, + getBreadcrumbSlugs, + getChildLevel, + getPageCount, + getTotalFeedCount, + type LocationQuery, + parseLocationSegments, + parsePageParam, +} from '../lib/location-directory'; +import { + fetchLocationDirectory, + fetchLocationDirectoryFeeds, +} from '../lib/location-directory-data'; + +const SITE_URL = 'https://mobilitydatabase.org'; + +interface PageProps { + params: Promise<{ locale: string; location?: string[] }>; + searchParams: Promise>; +} + +interface ParsedRequest { + query: LocationQuery; + page: number; +} + +async function parseRequest({ + params, + searchParams, +}: PageProps): Promise<{ locale: string } & (ParsedRequest | { query: null })> { + const [{ locale, location }, { page: rawPage }] = await Promise.all([ + params, + searchParams, + ]); + const query = parseLocationSegments(location); + const page = parsePageParam(rawPage); + if (query === null || page === null) return { locale, query: null }; + return { locale, query, page }; +} + +function fetchDirectory( + query: LocationQuery, +): ReturnType { + return fetchLocationDirectory( + query.continent, + query.country_code, + query.subdivision, + query.municipality, + ); +} + +function fetchFeedsPage( + query: LocationQuery, + page: number, +): ReturnType { + return fetchLocationDirectoryFeeds( + page, + query.continent, + query.country_code, + query.subdivision, + query.municipality, + ); +} + +export async function generateMetadata(props: PageProps): Promise { + const request = await parseRequest(props); + if (request.query === null) return {}; + const { query, page } = request; + // Same calls as the page: deduped by React cache() within the request. + const [directory, feeds, t] = await Promise.all([ + fetchDirectory(query), + fetchFeedsPage(query, page), + getTranslations({ locale: request.locale, namespace: 'locations.meta' }), + ]); + if ( + directory === null || + feeds === null || + page > getPageCount(feeds.total ?? 0) + ) { + return {}; + } + + const place = buildPlaceName(directory.breadcrumb); + const counts = directory.feed_counts; + const isRoot = place === ''; + const title = isRoot + ? t('rootTitle') + : page > 1 + ? t('nodeTitlePaged', { place, page }) + : t('nodeTitle', { place }); + const description = isRoot + ? t('rootDescription') + : t('nodeDescription', { + place, + total: getTotalFeedCount(counts), + gtfs: counts?.gtfs ?? 0, + gtfs_rt: counts?.gtfs_rt ?? 0, + gbfs: counts?.gbfs ?? 0, + }); + const url = `${SITE_URL}${buildLocationHref( + getBreadcrumbSlugs(directory.breadcrumb), + page, + )}`; + + return { + title, + description, + alternates: { canonical: url }, + openGraph: { + title, + description, + url, + siteName: 'Mobility Database', + type: 'website', + }, + }; +} + +export default async function LocationsPage( + props: PageProps, +): Promise { + const request = await parseRequest(props); + if (request.query === null) notFound(); + const { locale, query, page } = request; + setRequestLocale(locale); + + // Directory node and feed page are independent: fetch them in parallel. + const [directory, feeds, t] = await Promise.all([ + fetchDirectory(query), + fetchFeedsPage(query, page), + getTranslations('locations'), + ]); + if (directory === null || feeds === null) notFound(); + + const total = feeds.total ?? 0; + const pageCount = getPageCount(total); + if (page > pageCount) notFound(); + + const breadcrumb = directory.breadcrumb ?? []; + const slugs = getBreadcrumbSlugs(breadcrumb); + const place = buildPlaceName(breadcrumb); + const isRoot = breadcrumb.length === 0; + const children = directory.children ?? []; + const childLevel = getChildLevel(directory.level); + + const crumbs: LocationCrumb[] = [ + { label: t('root'), href: isRoot ? undefined : buildLocationHref([]) }, + ...breadcrumb.map((node, index) => ({ + label: node.name ?? node.slug ?? '', + href: + index === breadcrumb.length - 1 + ? undefined + : buildLocationHref(slugs.slice(0, index + 1)), + })), + ]; + + return ( + + + + {isRoot ? t('title') : breadcrumb[breadcrumb.length - 1]?.name} + + + {isRoot + ? t('rootIntro') + : t('nodeIntro', { + total: getTotalFeedCount(directory.feed_counts), + place, + })} + + + + + {childLevel !== null && children.length > 0 ? ( + + + {t(`childrenHeading.${childLevel}`)}{' '} + + ({children.length}) + + + + + ) : null} + + + + {isRoot ? t('allFeedsHeading') : t('feedsHeading', { place })} + + + + + ); +} diff --git a/src/app/[locale]/locations/components/FeedCountSummary.tsx b/src/app/[locale]/locations/components/FeedCountSummary.tsx new file mode 100644 index 00000000..16580e77 --- /dev/null +++ b/src/app/[locale]/locations/components/FeedCountSummary.tsx @@ -0,0 +1,85 @@ +import { type ReactElement } from 'react'; +import { Box, Typography } from '@mui/material'; +import { getTranslations } from 'next-intl/server'; +import { + formatCount, + getFeedCountEntries, + type FeedCountDataType, + type LocationDirectoryFeedCounts, +} from '../lib/location-directory'; + +interface Props { + counts: LocationDirectoryFeedCounts | undefined; + locale: string; +} + +const LABEL_KEYS: Record = { + gtfs: 'gtfsSchedule', + gtfs_rt: 'gtfsRealtime', + gbfs: 'gbfs', +}; + +/** The node's feed totals split by GTFS Schedule / GTFS Realtime / GBFS. */ +export default async function FeedCountSummary({ + counts, + locale, +}: Props): Promise { + const [tCommon, t] = await Promise.all([ + getTranslations('common'), + getTranslations('locations'), + ]); + + return ( + + {getFeedCountEntries(counts).map(({ dataType, count }) => ( + + + {tCommon(LABEL_KEYS[dataType])} + + 0 ? 'primary.main' : 'text.disabled', + }} + > + {formatCount(count, locale)} + + + ))} + + ); +} diff --git a/src/app/[locale]/locations/components/LocationBreadcrumbs.tsx b/src/app/[locale]/locations/components/LocationBreadcrumbs.tsx new file mode 100644 index 00000000..27e62281 --- /dev/null +++ b/src/app/[locale]/locations/components/LocationBreadcrumbs.tsx @@ -0,0 +1,60 @@ +import { type ReactElement } from 'react'; +import { Breadcrumbs, Typography } from '@mui/material'; +import NavigateNextIcon from '@mui/icons-material/NavigateNext'; +import { Link } from '../../../../i18n/navigation'; + +export interface LocationCrumb { + label: string; + /** Omitted on the trailing crumb, the page the user is on. */ + href?: string; +} + +interface Props { + crumbs: LocationCrumb[]; + ariaLabel: string; +} + +export default function LocationBreadcrumbs({ + crumbs, + ariaLabel, +}: Props): ReactElement { + return ( + } + data-testid='location-breadcrumbs' + sx={{ + mb: 1, + '& .MuiBreadcrumbs-ol': { rowGap: 0.5 }, + '& a': { + color: 'text.secondary', + textDecoration: 'none', + borderRadius: '4px', + }, + '& a:hover': { color: 'primary.main', textDecoration: 'underline' }, + '& a:focus-visible': { + outline: '2px solid', + outlineColor: 'primary.main', + outlineOffset: '2px', + }, + }} + > + {crumbs.map((crumb) => + crumb.href != undefined ? ( + + {crumb.label} + + ) : ( + + {crumb.label} + + ), + )} + + ); +} diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx new file mode 100644 index 00000000..d69724b0 --- /dev/null +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -0,0 +1,145 @@ +import { type ReactElement } from 'react'; +import { Box, Typography } from '@mui/material'; +import { getTranslations } from 'next-intl/server'; +import { getEmojiFlag, type TCountryCode } from 'countries-list'; +import { Link } from '../../../../i18n/navigation'; +import { + buildLocationHref, + formatCount, + getFeedCountEntries, + getTotalFeedCount, + type LocationDirectoryNode, +} from '../lib/location-directory'; + +interface Props { + nodes: LocationDirectoryNode[]; + /** Slugs of the current node; each child links one level deeper. */ + parentSlugs: string[]; + locale: string; +} + +function getDisplayName(node: LocationDirectoryNode): string { + const name = node.name ?? node.slug ?? ''; + if (node.level === 'country' && node.code != undefined) { + const flag = getEmojiFlag(node.code.toUpperCase() as TCountryCode); + return flag !== '' ? `${flag} ${name}` : name; + } + return name; +} + +/** Child nodes as link tiles, each with its GTFS / GTFS-RT / GBFS counts. */ +export default async function LocationChildrenGrid({ + nodes, + parentSlugs, + locale, +}: Props): Promise { + const t = await getTranslations('locations'); + + return ( + + {nodes.map((node) => { + const counts = getFeedCountEntries(node.feed_counts); + const href = buildLocationHref([...parentSlugs, node.slug ?? '']); + return ( +
  • + + + + {getDisplayName(node)} + + + {t('childFeedTotal', { + count: getTotalFeedCount(node.feed_counts), + })} + + + + {counts.map(({ dataType, count }) => ( + 0 ? 'text.secondary' : 'text.disabled', + whiteSpace: 'nowrap', + }} + > + {t(`shortLabels.${dataType}`)}{' '} + 0 ? 'text.primary' : 'inherit', + }} + > + {formatCount(count, locale)} + + + ))} + + +
  • + ); + })} +
    + ); +} diff --git a/src/app/[locale]/locations/components/LocationFeedsList.tsx b/src/app/[locale]/locations/components/LocationFeedsList.tsx new file mode 100644 index 00000000..257430de --- /dev/null +++ b/src/app/[locale]/locations/components/LocationFeedsList.tsx @@ -0,0 +1,86 @@ +'use client'; + +import { type ReactElement } from 'react'; +import { Box, Pagination, PaginationItem, Typography } from '@mui/material'; +import { useTranslations } from 'next-intl'; +import SearchTable from '../../../screens/Feeds/SearchTable'; +import { useSealOfReliabilityFilterAccess } from '../../../hooks/useSealOfReliabilityFilterAccess'; +import { type SearchFeedItem } from '../../../services/feeds/utils'; +import { Link } from '../../../../i18n/navigation'; +import { + buildLocationHref, + FEEDS_SECTION_ID, + getPageOffset, + LOCATION_FEEDS_PAGE_SIZE, +} from '../lib/location-directory'; + +interface Props { + feeds: SearchFeedItem[]; + total: number; + page: number; + pageCount: number; + /** Slugs of the current node, used to build the page links. */ + slugs: string[]; +} + +/** + * The feeds of a directory node in the same compact table as the /feeds + * search (simple view), paginated with real links so every page is + * crawlable and reflected in the URL. + */ +export default function LocationFeedsList({ + feeds, + total, + page, + pageCount, + slugs, +}: Props): ReactElement { + const t = useTranslations('locations'); + // Same flag the /feeds search uses to show the seal badge on rows. + const { isFeatureLive: isSealEnabled } = useSealOfReliabilityFilterAccess(); + + if (feeds.length === 0) { + return {t('noFeeds')}; + } + + const start = getPageOffset(page) + 1; + const end = Math.min(start + LOCATION_FEEDS_PAGE_SIZE - 1, total); + + return ( + <> + + {t('resultsRange', { start, end, total })} + + + + + {pageCount > 1 ? ( + ( + + )} + /> + ) : null} + + ); +} diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts new file mode 100644 index 00000000..da3957fe --- /dev/null +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -0,0 +1,146 @@ +/** + * Cacheable data fetching for the /locations directory. + * + * The directory is public, catalog-wide data, so these functions use the + * shared guest token and must NOT call cookies() or headers() directly or + * indirectly (same rule as the guest feed pages, see guest-feed-data.ts). + */ +import 'server-only'; +import { cache } from 'react'; +import { unstable_cache } from 'next/cache'; +import { getGuestGcipIdToken } from '../../../utils/auth-server'; +import { + ApiError, + getLocationDirectory, + getLocationDirectoryFeeds, + type LocationDirectoryFeedsResponse, + type LocationDirectoryResponse, +} from '../../../services/feeds'; +import { + getPageOffset, + LOCATION_FEEDS_PAGE_SIZE, + type LocationQuery, +} from './location-directory'; + +/** 1 day; also flushed on demand with the existing `guest-feeds` tag. */ +export const LOCATION_DIRECTORY_REVALIDATE_SECONDS = 86400; +const CACHE_TAGS = ['location-directory', 'guest-feeds']; + +/** + * 400 (invalid hierarchy) and 404 (nothing located there) both mean the URL + * does not exist; they resolve to null so the page can call notFound(). Any + * other failure is rethrown so an error is never cached. + */ +async function nullWhenMissing( + request: () => Promise, +): Promise { + try { + const data = await request(); + if (data == undefined) { + throw new Error('Empty response from the location directory API'); + } + return data; + } catch (error) { + if ( + error instanceof ApiError && + (error.status === 400 || error.status === 404) + ) { + return null; + } + throw error; + } +} + +function toQuery( + continent: string | undefined, + countryCode: string | undefined, + subdivision: string | undefined, + municipality: string | undefined, +): LocationQuery { + const query: LocationQuery = {}; + if (continent != undefined) query.continent = continent; + if (countryCode != undefined) query.country_code = countryCode; + if (subdivision != undefined) query.subdivision = subdivision; + if (municipality != undefined) query.municipality = municipality; + return query; +} + +// unstable_cache keys on the key parts plus the call arguments, so the +// arguments are kept primitive. +const cachedDirectory = unstable_cache( + async ( + continent?: string, + countryCode?: string, + subdivision?: string, + municipality?: string, + ): Promise => { + const accessToken = await getGuestGcipIdToken(); + return await nullWhenMissing( + async () => + await getLocationDirectory( + toQuery(continent, countryCode, subdivision, municipality), + accessToken, + ), + ); + }, + ['location-directory'], + { tags: CACHE_TAGS, revalidate: LOCATION_DIRECTORY_REVALIDATE_SECONDS }, +); + +const cachedDirectoryFeeds = unstable_cache( + async ( + offset: number, + continent?: string, + countryCode?: string, + subdivision?: string, + municipality?: string, + ): Promise => { + const accessToken = await getGuestGcipIdToken(); + return await nullWhenMissing( + async () => + await getLocationDirectoryFeeds( + { + ...toQuery(continent, countryCode, subdivision, municipality), + limit: LOCATION_FEEDS_PAGE_SIZE, + offset, + }, + accessToken, + ), + ); + }, + ['location-directory-feeds'], + { tags: CACHE_TAGS, revalidate: LOCATION_DIRECTORY_REVALIDATE_SECONDS }, +); + +/** + * Directory node (breadcrumb, counts, children), or null when the location + * does not exist. React cache() dedupes the generateMetadata + page calls + * within one request; it compares arguments by identity, hence primitives. + */ +export const fetchLocationDirectory = cache( + async ( + continent?: string, + countryCode?: string, + subdivision?: string, + municipality?: string, + ): Promise => + await cachedDirectory(continent, countryCode, subdivision, municipality), +); + +/** One page (1-based) of the feeds located in a node, or null if missing. */ +export const fetchLocationDirectoryFeeds = cache( + async ( + page: number, + continent?: string, + countryCode?: string, + subdivision?: string, + municipality?: string, + ): Promise => + await cachedDirectoryFeeds( + getPageOffset(page), + continent, + countryCode, + subdivision, + municipality, + ), +); diff --git a/src/app/[locale]/locations/lib/location-directory.spec.ts b/src/app/[locale]/locations/lib/location-directory.spec.ts new file mode 100644 index 00000000..b954f6c2 --- /dev/null +++ b/src/app/[locale]/locations/lib/location-directory.spec.ts @@ -0,0 +1,178 @@ +import { + buildLocationHref, + buildPlaceName, + formatCount, + getBreadcrumbSlugs, + getChildLevel, + getFeedCountEntries, + getPageCount, + getPageOffset, + getTotalFeedCount, + type LocationDirectoryNode, + parseLocationSegments, + parsePageParam, +} from './location-directory'; + +const breadcrumb: LocationDirectoryNode[] = [ + { + level: 'continent', + slug: 'north-america', + code: 'NA', + name: 'North America', + }, + { level: 'country', slug: 'ca', code: 'CA', name: 'Canada' }, + { level: 'subdivision', slug: 'quebec', code: null, name: 'Québec' }, + { level: 'municipality', slug: 'montreal', code: null, name: 'Montréal' }, +]; + +describe('parseLocationSegments', () => { + it('returns an empty query at the root', () => { + expect(parseLocationSegments(undefined)).toEqual({}); + expect(parseLocationSegments([])).toEqual({}); + }); + + it('maps each segment to its API parameter, untouched', () => { + expect(parseLocationSegments(['north-america'])).toEqual({ + continent: 'north-america', + }); + expect( + parseLocationSegments(['north-america', 'ca', 'quebec', 'montreal']), + ).toEqual({ + continent: 'north-america', + country_code: 'ca', + subdivision: 'quebec', + municipality: 'montreal', + }); + }); + + it('rejects paths deeper than a municipality', () => { + expect( + parseLocationSegments(['north-america', 'ca', 'quebec', 'montreal', 'x']), + ).toBeNull(); + }); + + it('rejects empty segments', () => { + expect(parseLocationSegments(['north-america', ' '])).toBeNull(); + }); +}); + +describe('parsePageParam', () => { + it('defaults to page 1 when absent', () => { + expect(parsePageParam(undefined)).toBe(1); + }); + + it('accepts positive integers', () => { + expect(parsePageParam('1')).toBe(1); + expect(parsePageParam('2')).toBe(2); + expect(parsePageParam('120')).toBe(120); + }); + + it.each(['', '0', '-1', '+2', '01', '1.5', '1e3', 'abc', ' 2', '2 '])( + 'rejects %p', + (raw) => { + expect(parsePageParam(raw)).toBeNull(); + }, + ); + + it('rejects repeated params and unsafe integers', () => { + expect(parsePageParam(['1', '2'])).toBeNull(); + expect(parsePageParam('99999999999999999999')).toBeNull(); + }); +}); + +describe('pagination math', () => { + it('computes the page count with a floor of 1', () => { + expect(getPageCount(0)).toBe(1); + expect(getPageCount(1)).toBe(1); + expect(getPageCount(20)).toBe(1); + expect(getPageCount(21)).toBe(2); + expect(getPageCount(45, 10)).toBe(5); + }); + + it('computes the API offset of a 1-based page', () => { + expect(getPageOffset(1)).toBe(0); + expect(getPageOffset(2)).toBe(20); + expect(getPageOffset(3, 10)).toBe(20); + }); +}); + +describe('buildLocationHref', () => { + it('builds the root and nested paths', () => { + expect(buildLocationHref([])).toBe('/locations'); + expect( + buildLocationHref(['north-america', 'ca', 'quebec', 'montreal']), + ).toBe('/locations/north-america/ca/quebec/montreal'); + }); + + it('adds ?page only after the first page', () => { + expect(buildLocationHref(['europe'], 1)).toBe('/locations/europe'); + expect(buildLocationHref(['europe'], 2)).toBe('/locations/europe?page=2'); + expect(buildLocationHref([], 3)).toBe('/locations?page=3'); + }); + + it('encodes unsafe characters in segments', () => { + expect(buildLocationHref(['a b', 'c/d'])).toBe('/locations/a%20b/c%2Fd'); + }); + + it('round-trips with the breadcrumb slugs', () => { + expect(buildLocationHref(getBreadcrumbSlugs(breadcrumb), 2)).toBe( + '/locations/north-america/ca/quebec/montreal?page=2', + ); + expect(getBreadcrumbSlugs(undefined)).toEqual([]); + }); +}); + +describe('feed counts', () => { + it('lists GTFS, GTFS-RT and GBFS in order, defaulting to 0', () => { + expect(getFeedCountEntries({ gtfs: 4, gbfs: 1 })).toEqual([ + { dataType: 'gtfs', count: 4 }, + { dataType: 'gtfs_rt', count: 0 }, + { dataType: 'gbfs', count: 1 }, + ]); + expect(getFeedCountEntries(undefined).map((e) => e.count)).toEqual([ + 0, 0, 0, + ]); + }); + + it('prefers the distinct total over the per-type sum', () => { + expect(getTotalFeedCount({ gtfs: 2, gtfs_rt: 2, gbfs: 1, total: 4 })).toBe( + 4, + ); + expect(getTotalFeedCount({ gtfs: 2, gtfs_rt: 2, gbfs: 1 })).toBe(5); + expect(getTotalFeedCount(undefined)).toBe(0); + }); + + it('formats counts for the locale', () => { + expect(formatCount(1234, 'en')).toBe('1,234'); + expect(formatCount(undefined, 'en')).toBe('0'); + // fr groups with a narrow no-break space + expect(formatCount(1234, 'fr').replace(/\s/g, ' ')).toBe('1 234'); + }); +}); + +describe('getChildLevel', () => { + it('walks one level down and stops at municipalities', () => { + expect(getChildLevel('root')).toBe('continent'); + expect(getChildLevel(undefined)).toBe('continent'); + expect(getChildLevel('continent')).toBe('country'); + expect(getChildLevel('country')).toBe('subdivision'); + expect(getChildLevel('subdivision')).toBe('municipality'); + expect(getChildLevel('municipality')).toBeNull(); + }); +}); + +describe('buildPlaceName', () => { + it('is empty at the root', () => { + expect(buildPlaceName([])).toBe(''); + expect(buildPlaceName(undefined)).toBe(''); + }); + + it('names a continent on its own', () => { + expect(buildPlaceName(breadcrumb.slice(0, 1))).toBe('North America'); + }); + + it('lists the most specific place first, without the continent', () => { + expect(buildPlaceName(breadcrumb.slice(0, 2))).toBe('Canada'); + expect(buildPlaceName(breadcrumb)).toBe('Montréal, Québec, Canada'); + }); +}); diff --git a/src/app/[locale]/locations/lib/location-directory.ts b/src/app/[locale]/locations/lib/location-directory.ts new file mode 100644 index 00000000..010d8912 --- /dev/null +++ b/src/app/[locale]/locations/lib/location-directory.ts @@ -0,0 +1,184 @@ +/** + * Pure helpers for the /locations directory: URL segment and page parsing, + * URL building and count formatting. Safe to import from server and client + * components; holds no data fetching. + */ +import type { components } from '../../../services/feeds/types'; + +export type LocationDirectoryNode = + components['schemas']['LocationDirectoryNode']; +export type LocationDirectoryLevel = + components['schemas']['LocationDirectoryLevel']; +export type LocationDirectoryFeedCounts = + components['schemas']['LocationDirectoryFeedCounts']; + +export const LOCATIONS_BASE_PATH = '/locations'; +export const LOCATION_FEEDS_PAGE_SIZE = 20; +/** continent > country > subdivision > municipality */ +export const MAX_LOCATION_DEPTH = 4; +/** Anchor of the feed list; pagination links jump back to it. */ +export const FEEDS_SECTION_ID = 'feeds'; + +/** Query parameters shared by both directory endpoints. */ +export interface LocationQuery { + continent?: string; + country_code?: string; + subdivision?: string; + municipality?: string; +} + +const QUERY_KEYS_BY_DEPTH = [ + 'continent', + 'country_code', + 'subdivision', + 'municipality', +] as const; + +/** + * Maps the optional catch-all segments to the directory query. Segments are + * passed through untouched: API slugs are exactly the URL segments. + * + * @returns the query (empty at the root), or null when the path is deeper + * than a municipality or contains an empty segment. + */ +export function parseLocationSegments( + segments: readonly string[] | undefined, +): LocationQuery | null { + if (segments == undefined) return {}; + if (segments.length > MAX_LOCATION_DEPTH) return null; + const query: LocationQuery = {}; + for (let depth = 0; depth < segments.length; depth++) { + const segment = segments[depth].trim(); + if (segment === '') return null; + query[QUERY_KEYS_BY_DEPTH[depth]] = segment; + } + return query; +} + +const PAGE_PATTERN = /^[1-9]\d*$/; + +/** + * Parses the 1-based `?page=` search param. + * + * @returns 1 when absent, the page number when it is a positive integer + * written without leading zeros or signs, otherwise null. + */ +export function parsePageParam( + raw: string | string[] | undefined, +): number | null { + if (raw == undefined) return 1; + if (typeof raw !== 'string' || !PAGE_PATTERN.test(raw)) return null; + const page = Number(raw); + return Number.isSafeInteger(page) ? page : null; +} + +/** Number of pages needed for `total` items; never less than 1. */ +export function getPageCount( + total: number, + pageSize: number = LOCATION_FEEDS_PAGE_SIZE, +): number { + if (total <= 0) return 1; + return Math.ceil(total / pageSize); +} + +/** API offset of the first item of a 1-based page. */ +export function getPageOffset( + page: number, + pageSize: number = LOCATION_FEEDS_PAGE_SIZE, +): number { + return (page - 1) * pageSize; +} + +/** + * Locale-less path to a directory node, e.g. + * `/locations/north-america/ca/quebec?page=2`. Page 1 has no query string so + * that it stays the canonical URL of the node. Pass the result to the + * next-intl `Link`, which adds the locale prefix. + */ +export function buildLocationHref( + slugs: readonly string[], + page: number = 1, +): string { + const path = [LOCATIONS_BASE_PATH, ...slugs.map(encodeURIComponent)].join( + '/', + ); + return page > 1 ? `${path}?page=${page}` : path; +} + +/** Slugs of every breadcrumb node, from the continent down. */ +export function getBreadcrumbSlugs( + breadcrumb: readonly LocationDirectoryNode[] | undefined, +): string[] { + return (breadcrumb ?? []).map((node) => node.slug ?? ''); +} + +export const FEED_COUNT_DATA_TYPES = ['gtfs', 'gtfs_rt', 'gbfs'] as const; +export type FeedCountDataType = (typeof FEED_COUNT_DATA_TYPES)[number]; + +export interface FeedCountEntry { + dataType: FeedCountDataType; + count: number; +} + +/** GTFS, GTFS-RT and GBFS counts in display order; missing counts are 0. */ +export function getFeedCountEntries( + counts: LocationDirectoryFeedCounts | undefined, +): FeedCountEntry[] { + return FEED_COUNT_DATA_TYPES.map((dataType) => ({ + dataType, + count: counts?.[dataType] ?? 0, + })); +} + +/** Total distinct feeds of a node, falling back to the sum by data type. */ +export function getTotalFeedCount( + counts: LocationDirectoryFeedCounts | undefined, +): number { + if (counts?.total != undefined) return counts.total; + return getFeedCountEntries(counts).reduce( + (sum, entry) => sum + entry.count, + 0, + ); +} + +/** Locale-aware integer formatting, e.g. 1234 -> "1,234" (en). */ +export function formatCount(value: number | undefined, locale: string): string { + return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format( + value ?? 0, + ); +} + +const CHILD_LEVEL: Record< + LocationDirectoryLevel, + LocationDirectoryLevel | null +> = { + root: 'continent', + continent: 'country', + country: 'subdivision', + subdivision: 'municipality', + municipality: null, +}; + +/** The level of a node's children, or null for municipalities. */ +export function getChildLevel( + level: LocationDirectoryLevel | undefined, +): LocationDirectoryLevel | null { + return CHILD_LEVEL[level ?? 'root']; +} + +/** + * Human-readable place for titles, most specific first: + * `Montréal, Québec, Canada`. The continent is dropped once a country is + * known; a continent on its own is returned as is. Empty at the root. + */ +export function buildPlaceName( + breadcrumb: readonly LocationDirectoryNode[] | undefined, +): string { + const names = (breadcrumb ?? []) + .filter( + (node, index, all) => !(node.level === 'continent' && all.length > 1), + ) + .map((node) => node.name ?? node.slug ?? '') + .filter((name) => name !== ''); + return names.reverse().join(', '); +} diff --git a/src/app/components/Footer.tsx b/src/app/components/Footer.tsx index 35606b1e..5846b895 100644 --- a/src/app/components/Footer.tsx +++ b/src/app/components/Footer.tsx @@ -73,6 +73,7 @@ const Footer: React.FC = () => { {t('columns.platform')} {t('links.feeds')} + {t('links.locations')} {t('links.addFeed')} - {navigationItems.map((item) => ( - - - - ))} + + + ), + )} (null); + const [openedByKeyboard, setOpenedByKeyboard] = React.useState(false); + const closeTimer = React.useRef>(undefined); + + React.useEffect(() => { + return () => { + clearTimeout(closeTimer.current); + }; + }, []); + + const handleOpen = (e: React.MouseEvent): void => { + clearTimeout(closeTimer.current); + setOpenedByKeyboard(false); + setAnchorEl(e.currentTarget); + }; + + const handleClose = (): void => { + closeTimer.current = setTimeout(() => { + setAnchorEl(null); + }, 80); + }; + + const closeNow = (): void => { + clearTimeout(closeTimer.current); + setAnchorEl(null); + }; + + return ( + + + { + clearTimeout(closeTimer.current); + }, + onMouseLeave: handleClose, + sx: { pointerEvents: 'auto', minWidth: 200 }, + }, + }} + > + + {feedsMenuItems.map((item) => ( + + {t(item.titleKey)} + + ))} + + + + ); +} diff --git a/src/app/components/HeaderMobileDrawer.tsx b/src/app/components/HeaderMobileDrawer.tsx index 962f3dbe..f0e3984f 100644 --- a/src/app/components/HeaderMobileDrawer.tsx +++ b/src/app/components/HeaderMobileDrawer.tsx @@ -21,6 +21,7 @@ import { useColorScheme } from '@mui/material/styles'; import { useRouter } from 'next/navigation'; import { ACCOUNT_TARGET, + feedsMenuItems, gbfsMetricsNavItems, gtfsMetricsNavItems, SIGN_IN_TARGET, @@ -140,20 +141,56 @@ export default function DrawerContent({ - {navigationItems.map((item) => ( - - ))} + {navigationItems.map((item) => + item.target === 'feeds' ? ( + + } + aria-controls='feeds-content' + id='feeds-header' + data-cy='drawer-feeds' + > + + {item.title} + + + + {feedsMenuItems.map((subItem) => ( + + ))} + + + ) : ( + + ), + )} diff --git a/src/app/constants/Navigation.ts b/src/app/constants/Navigation.ts index 77d4454e..c3c65a48 100644 --- a/src/app/constants/Navigation.ts +++ b/src/app/constants/Navigation.ts @@ -15,6 +15,22 @@ export const MOBILITY_DATA_LINKS = { github: 'https://github.com/MobilityData/mobility-database-catalogs', }; +export const FEEDS_TARGET = '/feeds'; +export const LOCATIONS_TARGET = '/locations'; + +/** + * Sub-items of the "Feeds" header menu (desktop dropdown and mobile drawer). + * `titleKey` is a key of the `common` messages namespace. + */ +export const feedsMenuItems = [ + { titleKey: 'search', target: FEEDS_TARGET, dataCy: 'header-feeds-search' }, + { + titleKey: 'locations', + target: LOCATIONS_TARGET, + dataCy: 'header-feeds-locations', + }, +] as const; + export const WEB_VALIDATOR_LINK = 'https://gtfs-validator.mobilitydata.org'; export const GTFS_ORG_LINK = 'https://gtfs.org'; export const GBFS_LINK = 'https://github.com/MobilityData/gbfs'; diff --git a/src/app/screens/Feeds/SearchTable.tsx b/src/app/screens/Feeds/SearchTable.tsx index 2e990d4b..130b9fad 100644 --- a/src/app/screens/Feeds/SearchTable.tsx +++ b/src/app/screens/Feeds/SearchTable.tsx @@ -39,35 +39,37 @@ const HeaderTableCell = styled(TableCell)(() => ({ border: 'none', })); +const DATA_TYPE_LABEL_KEYS = { + gtfs: 'gtfsSchedule', + gtfs_rt: 'gtfsRealtime', + gbfs: 'gbfs', +} as const; + +function DataTypeElement({ + dataType, +}: { + dataType: 'gtfs' | 'gtfs_rt' | 'gbfs'; +}): React.ReactElement { + const tCommon = useTranslations('common'); + return ( + + {tCommon(DATA_TYPE_LABEL_KEYS[dataType])} + + ); +} + +// The translation hook lives in DataTypeElement, not here: this is called once +// per row, and a hook called in a loop breaks when the row count changes +// between renders of the same table (e.g. paging to a partial last page). export const getDataTypeElement = ( dataType: 'gtfs' | 'gtfs_rt' | 'gbfs', -): React.ReactElement => { - const tCommon = useTranslations('common'); - const DataTypeHolder = ({ - children, - }: { - children: React.ReactNode; - }): React.ReactElement => { - return ( - - {children} - - ); - }; - if (dataType === 'gtfs') { - return {tCommon('gtfsSchedule')}; - } else if (dataType === 'gtfs_rt') { - return {tCommon('gtfsRealtime')}; - } else { - return {tCommon('gbfs')}; - } -}; +): React.ReactElement => ; export default function SearchTable({ feedsData, diff --git a/src/app/services/feeds/index.ts b/src/app/services/feeds/index.ts index 50b726c2..ab8ff846 100644 --- a/src/app/services/feeds/index.ts +++ b/src/app/services/feeds/index.ts @@ -17,6 +17,21 @@ const client = createClient({ }, }); +/** + * Error thrown for any API response with a status >= 400. Extends `Error` + * with the same message as before, adding the HTTP status so callers can + * tell a 404 apart from a server failure. + */ +export class ApiError extends Error { + readonly status: number; + + constructor(message: string, status: number) { + super(message); + this.name = 'ApiError'; + this.status = status; + } +} + const throwOnError: Middleware = { async onResponse(res) { if (res.status >= 400) { @@ -26,7 +41,7 @@ const throwOnError: Middleware = { } const errorMessage = typeof body === 'string' ? body : JSON.stringify(body); - throw new Error(errorMessage); + throw new ApiError(errorMessage, res.status); } return undefined; }, @@ -351,6 +366,63 @@ export const searchFeeds = async ( }); }; +export type LocationDirectoryParams = NonNullable< + paths['/v1/locations/directory']['get']['parameters']['query'] +>; + +export type LocationDirectoryFeedsParams = NonNullable< + paths['/v1/locations/directory/feeds']['get']['parameters']['query'] +>; + +export type LocationDirectoryResponse = + paths['/v1/locations/directory']['get']['responses'][200]['content']['application/json']; + +export type LocationDirectoryFeedsResponse = + paths['/v1/locations/directory/feeds']['get']['responses'][200]['content']['application/json']; + +/** + * One level of the feed location directory: the node's breadcrumb, feed + * counts and children. Throws an `ApiError` with status 400 (invalid + * hierarchy) or 404 (no feed located there). + */ +export const getLocationDirectory = async ( + params: LocationDirectoryParams, + accessToken: string, + userContextJwt?: string, +): Promise => { + const authMiddleware = generateAuthMiddlewareWithToken( + accessToken, + userContextJwt, + ); + return await withAuthMiddleware(authMiddleware, async () => { + const response = await client.GET('/v1/locations/directory', { + params: { query: params }, + }); + return response.data; + }); +}; + +/** + * A page of the feeds located within a location directory node, already + * sorted by relevance to that node. + */ +export const getLocationDirectoryFeeds = async ( + params: LocationDirectoryFeedsParams, + accessToken: string, + userContextJwt?: string, +): Promise => { + const authMiddleware = generateAuthMiddlewareWithToken( + accessToken, + userContextJwt, + ); + return await withAuthMiddleware(authMiddleware, async () => { + const response = await client.GET('/v1/locations/directory/feeds', { + params: { query: params }, + }); + return response.data; + }); +}; + export const getLicense = async ( id: string, accessToken: string, diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index c3be5015..585c159b 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -359,6 +359,40 @@ export interface paths { patch?: never; trace?: never; }; + '/v1/locations/directory': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description Browse the feed location directory one level at a time: continent > country > subdivision > municipality. The level is selected by the most specific parameter provided; with no parameters the response lists continents.
    Feed counts are based on the feeds' declared locations, only include feeds with a status of `active`, `inactive`, `development` or `future`, and roll up to every ancestor level (a feed located in Montréal counts toward Québec, Canada and North America). A feed is counted at most once per node, even when it declares several locations within that node.
    Each parameter requires its parent: `country_code` requires `continent`, `subdivision` requires `country_code`, and `municipality` requires `subdivision`. */ + get: operations['getLocationDirectory']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/v1/locations/directory/feeds': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description List the feeds located within a location directory node, using the same location parameters, status rules and validation as `/v1/locations/directory`.
    Feeds are sorted by relevance to the requested node: feeds whose most specific matching declared location is closest to the requested level come first (in the Québec node, a feed located in "Canada, Québec" ranks above one located in "Canada, Québec, Montréal"). Ties are broken by provider, feed name and feed id. */ + get: operations['getLocationDirectoryFeeds']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; '/v1/licenses': { parameters: { query?: never; @@ -1308,6 +1342,68 @@ export interface components { */ municipality?: string; }; + /** + * @description A level of the location directory: + * * `root` - the whole world; its children are continents. + * * `continent` - a continent, derived from the ISO 3166-1 country code. + * * `country` - a country, identified by its ISO 3166-1 alpha-2 code. + * * `subdivision` - a first-level subdivision as declared on the feed (e.g. a state or province). + * * `municipality` - a municipality as declared on the feed. + * @example subdivision + * @enum {string} + */ + LocationDirectoryLevel: + | 'root' + | 'continent' + | 'country' + | 'subdivision' + | 'municipality'; + /** @description Number of distinct feeds per data type within a directory node. */ + LocationDirectoryFeedCounts: { + /** @example 42 */ + gtfs?: number; + /** @example 18 */ + gtfs_rt?: number; + /** @example 7 */ + gbfs?: number; + /** + * @description Number of distinct feeds of any data type. + * @example 67 + */ + total?: number; + }; + LocationDirectoryNode: { + level?: components['schemas']['LocationDirectoryLevel']; + /** + * @description URL-safe identifier of the node, used as the matching request parameter. Continents use a fixed slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`), countries use their lowercase ISO 3166-1 alpha-2 code, and subdivisions and municipalities use their name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Québec` -> `quebec`, `Saint-Jean-sur-Richelieu` -> `saint-jean-sur-richelieu`). + * @example quebec + */ + slug?: string; + /** + * @description The continent code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`) or the ISO 3166-1 alpha-2 country code. Null for subdivisions and municipalities. + * @example null + */ + code?: string | null; + /** + * @description Display name of the node in English. + * @example Québec + */ + name?: string; + feed_counts?: components['schemas']['LocationDirectoryFeedCounts']; + }; + LocationDirectoryResponse: { + level?: components['schemas']['LocationDirectoryLevel']; + /** @description The path from the continent down to the requested node, inclusive. Empty at the `root` level. */ + breadcrumb?: components['schemas']['LocationDirectoryNode'][]; + feed_counts?: components['schemas']['LocationDirectoryFeedCounts']; + /** @description The nodes one level below the requested node that contain at least one feed, sorted by name. Empty at the `municipality` level. */ + children?: components['schemas']['LocationDirectoryNode'][]; + }; + LocationDirectoryFeedsResponse: { + /** @description The total number of feeds within the node regardless of limit and offset. */ + total?: number; + results?: components['schemas']['SearchFeedItemResult'][]; + }; LocationSearchResponse: { /** @description The total number of matching locations regardless of limit and offset. */ total?: number; @@ -1822,6 +1918,16 @@ export interface components { is_official_query_param: boolean; /** @description If true, only return feeds that currently hold the Seal of Reliability; if false, only feeds without it. Viewing a feed's seal is public, but filtering the catalogue by it is granted per user and requires the `isSealFilterEnabled` feature flag - other callers receive a 403. To request access or learn more, contact us at api@mobilitydata.org. */ has_seal_query_param: boolean; + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ + location_directory_continent: string; + /** @description ISO 3166-1 alpha-2 country code. Case-insensitive. Requires `continent`. */ + location_directory_country_code: string; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country_code`. */ + location_directory_subdivision: string; + /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ + location_directory_municipality: string; + /** @description The number of items to be returned. */ + limit_query_param_location_directory_feeds_endpoint: number; /** @description The number of items to be returned. */ limit_query_param_locations_endpoint: number; /** @description The number of items to be returned. */ @@ -2559,6 +2665,89 @@ export interface operations { }; }; }; + getLocationDirectory: { + parameters: { + query?: { + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ + continent?: components['parameters']['location_directory_continent']; + /** @description ISO 3166-1 alpha-2 country code. Case-insensitive. Requires `continent`. */ + country_code?: components['parameters']['location_directory_country_code']; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country_code`. */ + subdivision?: components['parameters']['location_directory_subdivision']; + /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ + municipality?: components['parameters']['location_directory_municipality']; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The requested directory node, its breadcrumb and its children. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['LocationDirectoryResponse']; + }; + }; + /** @description A parameter was provided without its parent, or the country does not belong to the continent. */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description No feed is located at the requested location. */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + getLocationDirectoryFeeds: { + parameters: { + query?: { + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ + continent?: components['parameters']['location_directory_continent']; + /** @description ISO 3166-1 alpha-2 country code. Case-insensitive. Requires `continent`. */ + country_code?: components['parameters']['location_directory_country_code']; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country_code`. */ + subdivision?: components['parameters']['location_directory_subdivision']; + /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ + municipality?: components['parameters']['location_directory_municipality']; + /** @description The number of items to be returned. */ + limit?: components['parameters']['limit_query_param_location_directory_feeds_endpoint']; + /** @description Offset of the first item to return. */ + offset?: components['parameters']['offset']; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The page of feeds located within the requested node. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['LocationDirectoryFeedsResponse']; + }; + }; + /** @description A parameter was provided without its parent, or the country does not belong to the continent. */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; getLicenses: { parameters: { query?: { diff --git a/src/mocks/handlers.ts b/src/mocks/handlers.ts index 0f826fe3..8adffae9 100644 --- a/src/mocks/handlers.ts +++ b/src/mocks/handlers.ts @@ -7,8 +7,31 @@ import datasetsFeedJson from '../../cypress/fixtures/feed_datasets_test-516.json import feed2947 from '../../cypress/fixtures/feed_mdb-2947.json'; import gtfsFeed2947 from '../../cypress/fixtures/gtfs_feed_mdb-2947.json'; import datasets2947 from '../../cypress/fixtures/feed_datasets_mdb-2947.json'; +import { + getMockDirectory, + getMockDirectoryFeeds, + readDirectoryQuery, +} from './locationDirectory'; export const handlers = [ + // Location directory: feeds of a node (paginated, relevance-sorted) + http.get(`*/v1/locations/directory/feeds`, ({ request }) => { + const params = new URL(request.url).searchParams; + const limit = Number(params.get('limit') ?? '20'); + const offset = Number(params.get('offset') ?? '0'); + const { status, body } = getMockDirectoryFeeds( + readDirectoryQuery(params), + Number.isFinite(limit) ? limit : 20, + Number.isFinite(offset) ? offset : 0, + ); + return HttpResponse.json(body, { status }); + }), + // Location directory: breadcrumb, counts and children of a node + http.get(`*/v1/locations/directory`, ({ request }) => { + const params = new URL(request.url).searchParams; + const { status, body } = getMockDirectory(readDirectoryQuery(params)); + return HttpResponse.json(body, { status }); + }), // Mock search endpoint: return a list including test-516 and mdb-2947 http.get(`*/v1/search`, () => { return HttpResponse.json({ diff --git a/src/mocks/locationDirectory.spec.ts b/src/mocks/locationDirectory.spec.ts new file mode 100644 index 00000000..00907ef7 --- /dev/null +++ b/src/mocks/locationDirectory.spec.ts @@ -0,0 +1,77 @@ +import { + getMockDirectory, + getMockDirectoryFeeds, + readDirectoryQuery, + slugify, +} from './locationDirectory'; + +describe('location directory mocks', () => { + it('slugifies names like the API', () => { + expect(slugify('Québec')).toBe('quebec'); + expect(slugify('Saint-Jean-sur-Richelieu')).toBe( + 'saint-jean-sur-richelieu', + ); + expect(slugify('Île-de-France')).toBe('ile-de-france'); + }); + + it('lists continents at the root', () => { + const result = getMockDirectory({}); + expect(result.status).toBe(200); + if (result.status !== 200) return; + expect(result.body.level).toBe('root'); + expect(result.body.breadcrumb).toEqual([]); + expect(result.body.children?.map((node) => node.slug)).toEqual([ + 'africa', + 'europe', + 'north-america', + 'oceania', + ]); + }); + + it('resolves the Montréal breadcrumb and rolls counts up', () => { + const query = readDirectoryQuery( + new URLSearchParams( + 'continent=north-america&country_code=ca&subdivision=quebec&municipality=montreal', + ), + ); + const result = getMockDirectory(query); + expect(result.status).toBe(200); + if (result.status !== 200) return; + expect(result.body.breadcrumb?.map((node) => node.name)).toEqual([ + 'North America', + 'Canada', + 'Québec', + 'Montréal', + ]); + expect(result.body.children).toEqual([]); + const montreal = result.body.feed_counts?.total ?? 0; + const quebec = result.body.breadcrumb?.[2].feed_counts?.total ?? 0; + expect(montreal).toBeGreaterThan(20); + expect(quebec).toBeGreaterThan(montreal); + }); + + it('returns 400 on a broken hierarchy and 404 when nothing is there', () => { + expect(getMockDirectory({ country_code: 'ca' }).status).toBe(400); + expect( + getMockDirectory({ continent: 'europe', country_code: 'ca' }).status, + ).toBe(400); + expect(getMockDirectory({ continent: 'antarctica' }).status).toBe(404); + }); + + it('paginates feeds, most relevant to the node first', () => { + const query = { + continent: 'north-america', + country_code: 'ca', + subdivision: 'quebec', + }; + const first = getMockDirectoryFeeds(query, 20, 0); + const second = getMockDirectoryFeeds(query, 20, 20); + if (first.status !== 200 || second.status !== 200) { + throw new Error('expected 200'); + } + expect(first.body.results).toHaveLength(20); + expect(second.body.results?.length).toBe((first.body.total ?? 0) - 20); + // Feeds declared at the Québec level outrank municipality-level ones. + expect(first.body.results?.[0].locations?.[0].municipality).toBeUndefined(); + }); +}); diff --git a/src/mocks/locationDirectory.ts b/src/mocks/locationDirectory.ts new file mode 100644 index 00000000..3d0f58fc --- /dev/null +++ b/src/mocks/locationDirectory.ts @@ -0,0 +1,532 @@ +/** + * Mock data and logic for the location directory endpoints: + * GET /v1/locations/directory + * GET /v1/locations/directory/feeds + * + * The directory tree, the rolled-up counts, the breadcrumb and the children + * are all derived from MOCK_FEEDS' declared locations, so the mock behaves + * like the API: a feed counts once per node, 400 on a broken hierarchy, 404 + * when nothing is located there, feeds sorted by relevance to the node. + * Feed ids, URLs and names are fictional mock data. + */ +import type { components } from '../app/services/feeds/types'; + +type Feed = components['schemas']['SearchFeedItemResult']; +type DirectoryNode = components['schemas']['LocationDirectoryNode']; +type DirectoryLevel = components['schemas']['LocationDirectoryLevel']; +type FeedCounts = components['schemas']['LocationDirectoryFeedCounts']; +type DirectoryResponse = components['schemas']['LocationDirectoryResponse']; +type FeedsResponse = components['schemas']['LocationDirectoryFeedsResponse']; + +const CONTINENTS: Record = { + africa: { code: 'AF', name: 'Africa' }, + europe: { code: 'EU', name: 'Europe' }, + 'north-america': { code: 'NA', name: 'North America' }, + oceania: { code: 'OC', name: 'Oceania' }, +}; + +const COUNTRIES: Record = { + AU: { name: 'Australia', continent: 'oceania' }, + CA: { name: 'Canada', continent: 'north-america' }, + DE: { name: 'Germany', continent: 'europe' }, + FR: { name: 'France', continent: 'europe' }, + US: { name: 'United States', continent: 'north-america' }, + ZA: { name: 'South Africa', continent: 'africa' }, +}; + +/** Same slug rule as the API: `Québec` -> `quebec`. */ +export function slugify(name: string): string { + return name + .normalize('NFD') + .replace(/[̀-ͯ]/g, '') + .toLowerCase() + .replace(/[^a-z0-9]+/g, '-') + .replace(/^-+|-+$/g, ''); +} + +type Place = [countryCode: string, subdivision?: string, municipality?: string]; +type FeedSeed = [ + dataType: Feed['data_type'], + provider: string, + feedName: string, + places: Place[], +]; + +const MONTREAL: Place = ['CA', 'Québec', 'Montréal']; +const EXO_SECTORS = [ + 'Chambly-Richelieu-Carignan', + 'Haut-Saint-Laurent', + 'Laurentides', + 'Le Richelain', + 'Roussillon', + 'Sorel-Varennes', + 'Sud-Ouest', + 'Terrebonne-Mascouche', + 'Vallée du Richelieu', + 'La Presqu’Île', + 'L’Assomption', + 'Deux-Montagnes', +]; + +const FEED_SEEDS: FeedSeed[] = [ + // Canada-wide + ['gtfs', 'Example Intercity Rail', 'National rail network', [['CA']]], + // Québec (subdivision level only) + ['gtfs', 'Example Coach Lines', 'Intercity coaches', [['CA', 'Québec']]], + ['gtfs_rt', 'Example Coach Lines', 'Trip updates', [['CA', 'Québec']]], + // Montréal: more than one page of feeds + ['gtfs', 'Société de transport de Montréal', 'Bus and metro', [MONTREAL]], + ['gtfs_rt', 'Société de transport de Montréal', 'Trip updates', [MONTREAL]], + ['gtfs_rt', 'Société de transport de Montréal', 'Alerts', [MONTREAL]], + ['gtfs', 'Réseau express métropolitain', 'REM light metro', [MONTREAL]], + [ + 'gtfs', + 'exo', + 'Commuter trains', + [MONTREAL, ['CA', 'Québec', 'Laval'], ['CA', 'Québec', 'Longueuil']], + ], + ['gtfs_rt', 'exo', 'Commuter trains - trip updates', [MONTREAL]], + ...EXO_SECTORS.map( + (sector): FeedSeed => ['gtfs', 'exo', `Buses - ${sector}`, [MONTREAL]], + ), + ['gbfs', 'BIXI Montréal', 'Bike share', [MONTREAL]], + ['gbfs', 'Example Scooters', 'Montréal e-scooters', [MONTREAL]], + ['gbfs', 'Example Car Share', 'Montréal car share', [MONTREAL]], + ['gtfs_rt', 'exo', 'Commuter trains - vehicle positions', [MONTREAL]], + // Elsewhere in Québec + [ + 'gtfs', + 'Société de transport de Laval', + 'Buses', + [['CA', 'Québec', 'Laval']], + ], + [ + 'gtfs', + 'Réseau de transport de Longueuil', + 'Buses', + [['CA', 'Québec', 'Longueuil']], + ], + [ + 'gtfs', + 'Réseau de transport de la Capitale', + 'Buses', + [['CA', 'Québec', 'Québec']], + ], + [ + 'gtfs_rt', + 'Réseau de transport de la Capitale', + 'Vehicle positions', + [['CA', 'Québec', 'Québec']], + ], + // Ontario + [ + 'gtfs', + 'Example Regional Transit', + 'Regional rail and buses', + [['CA', 'Ontario']], + ], + [ + 'gtfs', + 'Toronto Transit Commission', + 'Surface and subway', + [['CA', 'Ontario', 'Toronto']], + ], + [ + 'gtfs_rt', + 'Toronto Transit Commission', + 'Trip updates', + [['CA', 'Ontario', 'Toronto']], + ], + ['gbfs', 'Bike Share Toronto', 'Bike share', [['CA', 'Ontario', 'Toronto']]], + // British Columbia + [ + 'gtfs', + 'Example Coast Transit', + 'Buses and SkyTrain', + [['CA', 'British Columbia', 'Vancouver']], + ], + // United States + [ + 'gtfs', + 'Example Metro Los Angeles', + 'Bus', + [['US', 'California', 'Los Angeles']], + ], + [ + 'gtfs', + 'Example Bay Area Rail', + 'Rapid transit', + [ + ['US', 'California', 'San Francisco'], + ['US', 'California', 'Oakland'], + ], + ], + [ + 'gtfs_rt', + 'Example Bay Area Rail', + 'Trip updates', + [['US', 'California', 'San Francisco']], + ], + [ + 'gbfs', + 'Example Bikes SF', + 'Bike share', + [['US', 'California', 'San Francisco']], + ], + [ + 'gtfs', + 'Example Metropolitan Transit', + 'Subway', + [['US', 'New York', 'New York']], + ], + [ + 'gtfs_rt', + 'Example Metropolitan Transit', + 'Subway trip updates', + [['US', 'New York', 'New York']], + ], + // Europe + [ + 'gtfs', + 'Example Île-de-France Mobilités', + 'Regional network', + [['FR', 'Île-de-France', 'Paris']], + ], + [ + 'gbfs', + 'Example Vélo Paris', + 'Bike share', + [['FR', 'Île-de-France', 'Paris']], + ], + [ + 'gtfs', + 'Example Verkehrsverbund Berlin', + 'Regional network', + [['DE', 'Berlin', 'Berlin']], + ], + // Oceania + [ + 'gtfs', + 'Example Transport NSW', + 'Sydney network', + [['AU', 'New South Wales', 'Sydney']], + ], + [ + 'gtfs_rt', + 'Example Transport NSW', + 'Trip updates', + [['AU', 'New South Wales', 'Sydney']], + ], + // Africa + [ + 'gtfs', + 'Example Cape Town Bus', + 'Bus rapid transit', + [['ZA', 'Western Cape', 'Cape Town']], + ], +]; + +function toFeed( + [dataType, provider, feedName, places]: FeedSeed, + index: number, +): Feed { + const id = `mock-loc-${String(index + 1).padStart(3, '0')}`; + return { + id, + data_type: dataType, + status: 'active', + official: index % 3 === 0, + seasonal: false, + provider, + feed_name: feedName, + external_ids: [{ external_id: id, source: 'mdb' }], + source_info: { + producer_url: `https://example.com/${id}/${dataType}`, + authentication_type: 0, + }, + locations: places.map(([countryCode, subdivision, municipality]) => ({ + country_code: countryCode, + country: COUNTRIES[countryCode].name, + subdivision_name: subdivision, + municipality, + })), + entity_types: dataType === 'gtfs_rt' ? ['tu', 'vp'] : undefined, + versions: dataType === 'gbfs' ? ['2.3'] : undefined, + }; +} + +export const MOCK_FEEDS: Feed[] = FEED_SEEDS.map(toFeed); + +export interface DirectoryQuery { + continent?: string; + country_code?: string; + subdivision?: string; + municipality?: string; +} + +type FeedLocation = NonNullable[number]; + +/** Depth of a declared location: 1 country, 2 subdivision, 3 municipality. */ +function locationDepth(location: FeedLocation): number { + if (location.municipality != undefined) return 3; + if (location.subdivision_name != undefined) return 2; + return 1; +} + +function matches(location: FeedLocation, query: DirectoryQuery): boolean { + const country = COUNTRIES[location.country_code ?? '']; + if (country == undefined) return false; + if (query.continent != undefined && country.continent !== query.continent) + return false; + if ( + query.country_code != undefined && + location.country_code?.toLowerCase() !== query.country_code.toLowerCase() + ) + return false; + if ( + query.subdivision != undefined && + slugify(location.subdivision_name ?? '') !== query.subdivision + ) + return false; + if ( + query.municipality != undefined && + slugify(location.municipality ?? '') !== query.municipality + ) + return false; + return true; +} + +function feedsIn(query: DirectoryQuery): Feed[] { + return MOCK_FEEDS.filter((feed) => + (feed.locations ?? []).some((location) => matches(location, query)), + ); +} + +function countFeeds(feeds: Feed[]): FeedCounts { + return { + gtfs: feeds.filter((feed) => feed.data_type === 'gtfs').length, + gtfs_rt: feeds.filter((feed) => feed.data_type === 'gtfs_rt').length, + gbfs: feeds.filter((feed) => feed.data_type === 'gbfs').length, + total: feeds.length, + }; +} + +function levelOf(query: DirectoryQuery): DirectoryLevel { + if (query.municipality != undefined) return 'municipality'; + if (query.subdivision != undefined) return 'subdivision'; + if (query.country_code != undefined) return 'country'; + if (query.continent != undefined) return 'continent'; + return 'root'; +} + +/** 400 when a parameter is missing its parent or the country is elsewhere. */ +function isValidHierarchy(query: DirectoryQuery): boolean { + if (query.country_code != undefined && query.continent == undefined) + return false; + if (query.subdivision != undefined && query.country_code == undefined) + return false; + if (query.municipality != undefined && query.subdivision == undefined) + return false; + if (query.country_code != undefined) { + const country = COUNTRIES[query.country_code.toUpperCase()]; + if (country != undefined && country.continent !== query.continent) + return false; + } + return true; +} + +function makeNode( + level: DirectoryLevel, + slug: string, + code: string | null, + name: string, + query: DirectoryQuery, +): DirectoryNode { + return { + level, + slug, + code, + name, + feed_counts: countFeeds(feedsIn(query)), + }; +} + +function nodeFor( + query: DirectoryQuery, + displayName?: string, +): DirectoryNode | undefined { + const level = levelOf(query); + switch (level) { + case 'continent': { + const slug = query.continent ?? ''; + const continent = CONTINENTS[slug]; + return continent == undefined + ? undefined + : makeNode(level, slug, continent.code, continent.name, query); + } + case 'country': { + const code = (query.country_code ?? '').toUpperCase(); + const country = COUNTRIES[code]; + return country == undefined + ? undefined + : makeNode(level, code.toLowerCase(), code, country.name, query); + } + case 'subdivision': + return makeNode( + level, + query.subdivision ?? '', + null, + displayName ?? query.subdivision ?? '', + query, + ); + case 'municipality': + return makeNode( + level, + query.municipality ?? '', + null, + displayName ?? query.municipality ?? '', + query, + ); + default: + return undefined; + } +} + +/** Original (accented) names of a subdivision/municipality, by slug. */ +function displayNameOf( + feeds: Feed[], + field: 'subdivision_name' | 'municipality', + slug: string, +): string | undefined { + for (const feed of feeds) { + for (const location of feed.locations ?? []) { + const value = location[field]; + if (value != undefined && slugify(value) === slug) return value; + } + } + return undefined; +} + +function childrenOf(query: DirectoryQuery): DirectoryNode[] { + const level = levelOf(query); + const children = new Map(); + for (const feed of feedsIn(query)) { + for (const location of feed.locations ?? []) { + if (!matches(location, query)) continue; + const countryCode = location.country_code ?? ''; + let childQuery: DirectoryQuery | undefined; + let name: string | undefined; + if (level === 'root') { + childQuery = { continent: COUNTRIES[countryCode].continent }; + } else if (level === 'continent') { + childQuery = { ...query, country_code: countryCode.toLowerCase() }; + } else if (level === 'country' && location.subdivision_name != null) { + name = location.subdivision_name; + childQuery = { ...query, subdivision: slugify(name) }; + } else if (level === 'subdivision' && location.municipality != null) { + name = location.municipality; + childQuery = { ...query, municipality: slugify(name) }; + } + if (childQuery == undefined) continue; + const key = JSON.stringify(childQuery); + if (!children.has(key)) { + const node = nodeFor(childQuery, name); + if (node != undefined) children.set(key, node); + } + } + } + return [...children.values()].sort((a, b) => + (a.name ?? '').localeCompare(b.name ?? ''), + ); +} + +function breadcrumbOf(query: DirectoryQuery): DirectoryNode[] { + const all = feedsIn(query); + const steps: DirectoryQuery[] = []; + if (query.continent != undefined) steps.push({ continent: query.continent }); + if (query.country_code != undefined) + steps.push({ ...steps[0], country_code: query.country_code }); + if (query.subdivision != undefined) + steps.push({ ...steps[1], subdivision: query.subdivision }); + if (query.municipality != undefined) + steps.push({ ...steps[2], municipality: query.municipality }); + return steps.flatMap((step) => { + const level = levelOf(step); + const name = + level === 'subdivision' + ? displayNameOf(all, 'subdivision_name', step.subdivision ?? '') + : level === 'municipality' + ? displayNameOf(all, 'municipality', step.municipality ?? '') + : undefined; + const node = nodeFor(step, name); + return node == undefined ? [] : [node]; + }); +} + +export type MockResult = + | { status: 200; body: T } + | { status: 400 | 404; body: { detail: string } }; + +export function readDirectoryQuery(params: URLSearchParams): DirectoryQuery { + const read = (key: string): string | undefined => { + const value = params.get(key); + return value == null || value === '' ? undefined : value; + }; + return { + continent: read('continent'), + country_code: read('country_code'), + subdivision: read('subdivision'), + municipality: read('municipality'), + }; +} + +export function getMockDirectory( + query: DirectoryQuery, +): MockResult { + if (!isValidHierarchy(query)) { + return { status: 400, body: { detail: 'Invalid location hierarchy.' } }; + } + const feeds = feedsIn(query); + if (feeds.length === 0) { + return { status: 404, body: { detail: 'No feed located there.' } }; + } + return { + status: 200, + body: { + level: levelOf(query), + breadcrumb: breadcrumbOf(query), + feed_counts: countFeeds(feeds), + children: childrenOf(query), + }, + }; +} + +export function getMockDirectoryFeeds( + query: DirectoryQuery, + limit: number, + offset: number, +): MockResult { + if (!isValidHierarchy(query)) { + return { status: 400, body: { detail: 'Invalid location hierarchy.' } }; + } + const relevance = (feed: Feed): number => + Math.max( + ...(feed.locations ?? []) + .filter((location) => matches(location, query)) + .map(locationDepth), + ); + const sorted = feedsIn(query).sort( + (a, b) => + relevance(a) - relevance(b) || + (a.provider ?? '').localeCompare(b.provider ?? '') || + (a.feed_name ?? '').localeCompare(b.feed_name ?? '') || + a.id.localeCompare(b.id), + ); + return { + status: 200, + body: { + total: sorted.length, + results: sorted.slice(offset, offset + limit), + }, + }; +} From 0d9253a123599cf047b4f73651a219ee8e98b9c4 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 2 Nov 2026 14:07:20 -0500 Subject: [PATCH 02/16] fix: do not cache missing locations in the directory A 400 or 404 from the location directory API was cached as a missing location for a day, so a page requested before the API route was deployed kept returning 404 after it was. Throw on a miss inside the cached functions, which unstable_cache never stores, and resolve it to null outside the cache. Co-Authored-By: Claude Opus 5.5 --- .../lib/location-directory-data.spec.ts | 108 ++++++++++++++++++ .../locations/lib/location-directory-data.ts | 59 +++++++--- 2 files changed, 151 insertions(+), 16 deletions(-) create mode 100644 src/app/[locale]/locations/lib/location-directory-data.spec.ts diff --git a/src/app/[locale]/locations/lib/location-directory-data.spec.ts b/src/app/[locale]/locations/lib/location-directory-data.spec.ts new file mode 100644 index 00000000..9c9b0bd3 --- /dev/null +++ b/src/app/[locale]/locations/lib/location-directory-data.spec.ts @@ -0,0 +1,108 @@ +/** + * @jest-environment node + */ + +import { ApiError } from '../../../services/feeds'; +import { + fetchLocationDirectory, + fetchLocationDirectoryFeeds, +} from './location-directory-data'; + +jest.mock('server-only', () => ({})); + +jest.mock('react', () => ({ + ...jest.requireActual('react'), + cache: (fn: unknown) => fn, +})); + +// Behaves like unstable_cache: a resolved value is stored per arguments, a +// thrown error is not. +jest.mock('next/cache', () => ({ + unstable_cache: ( + fn: (...args: A) => Promise, + ): ((...args: A) => Promise) => { + const store = new Map(); + return async (...args: A): Promise => { + const key = JSON.stringify(args); + if (store.has(key)) return store.get(key) as R; + const value = await fn(...args); + store.set(key, value); + return value; + }; + }, +})); + +const mockGetLocationDirectory = jest.fn(); +const mockGetLocationDirectoryFeeds = jest.fn(); + +jest.mock('../../../services/feeds', () => ({ + ApiError: class ApiError extends Error { + readonly status: number; + constructor(message: string, status: number) { + super(message); + this.status = status; + } + }, + getLocationDirectory: (...args: unknown[]) => + mockGetLocationDirectory(...args), + getLocationDirectoryFeeds: (...args: unknown[]) => + mockGetLocationDirectoryFeeds(...args), +})); + +jest.mock('../../../utils/auth-server', () => ({ + getGuestGcipIdToken: async () => 'guest-token', +})); + +const directory = { + level: 'continent', + breadcrumb: [], + feed_counts: { gtfs: 1, gtfs_rt: 0, gbfs: 0, total: 1 }, + children: [], +}; + +describe('location directory data', () => { + beforeEach(() => { + mockGetLocationDirectory.mockReset(); + mockGetLocationDirectoryFeeds.mockReset(); + }); + + it('resolves a 404 to null without caching it', async () => { + mockGetLocationDirectory + .mockRejectedValueOnce(new ApiError('Not Found', 404)) + .mockResolvedValueOnce(directory); + + await expect(fetchLocationDirectory('europe')).resolves.toBeNull(); + await expect(fetchLocationDirectory('europe')).resolves.toEqual(directory); + expect(mockGetLocationDirectory).toHaveBeenCalledTimes(2); + }); + + it('resolves a 400 on the feeds page to null without caching it', async () => { + const feeds = { total: 0, results: [] }; + mockGetLocationDirectoryFeeds + .mockRejectedValueOnce(new ApiError('Bad Request', 400)) + .mockResolvedValueOnce(feeds); + + await expect(fetchLocationDirectoryFeeds(1, 'asia')).resolves.toBeNull(); + await expect(fetchLocationDirectoryFeeds(1, 'asia')).resolves.toEqual( + feeds, + ); + }); + + it('caches a found location', async () => { + mockGetLocationDirectory.mockResolvedValue(directory); + + await fetchLocationDirectory('oceania'); + await fetchLocationDirectory('oceania'); + expect(mockGetLocationDirectory).toHaveBeenCalledTimes(1); + }); + + it('rethrows other API errors', async () => { + mockGetLocationDirectory.mockRejectedValueOnce( + new ApiError('Server Error', 500), + ); + + await expect(fetchLocationDirectory('africa')).rejects.toThrow( + 'Server Error', + ); + }); +}); diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index da3957fe..4b387d3c 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -28,12 +28,16 @@ const CACHE_TAGS = ['location-directory', 'guest-feeds']; /** * 400 (invalid hierarchy) and 404 (nothing located there) both mean the URL - * does not exist; they resolve to null so the page can call notFound(). Any - * other failure is rethrown so an error is never cached. + * does not exist. They are thrown as this error inside the cached functions, + * because unstable_cache never stores a thrown error: caching the miss would + * keep a location missing for a whole day after it starts to exist (e.g. a + * 404 served before the API route was deployed). */ -async function nullWhenMissing( +class LocationNotFoundError extends Error {} + +async function requireData( request: () => Promise, -): Promise { +): Promise { try { const data = await request(); if (data == undefined) { @@ -45,12 +49,24 @@ async function nullWhenMissing( error instanceof ApiError && (error.status === 400 || error.status === 404) ) { - return null; + throw new LocationNotFoundError(error.message); } throw error; } } +/** Resolves a missing location to null so the page can call notFound(). */ +async function nullWhenMissing( + request: () => Promise, +): Promise { + try { + return await request(); + } catch (error) { + if (error instanceof LocationNotFoundError) return null; + throw error; + } +} + function toQuery( continent: string | undefined, countryCode: string | undefined, @@ -73,9 +89,9 @@ const cachedDirectory = unstable_cache( countryCode?: string, subdivision?: string, municipality?: string, - ): Promise => { + ): Promise => { const accessToken = await getGuestGcipIdToken(); - return await nullWhenMissing( + return await requireData( async () => await getLocationDirectory( toQuery(continent, countryCode, subdivision, municipality), @@ -94,9 +110,9 @@ const cachedDirectoryFeeds = unstable_cache( countryCode?: string, subdivision?: string, municipality?: string, - ): Promise => { + ): Promise => { const accessToken = await getGuestGcipIdToken(); - return await nullWhenMissing( + return await requireData( async () => await getLocationDirectoryFeeds( { @@ -124,7 +140,15 @@ export const fetchLocationDirectory = cache( subdivision?: string, municipality?: string, ): Promise => - await cachedDirectory(continent, countryCode, subdivision, municipality), + await nullWhenMissing( + async () => + await cachedDirectory( + continent, + countryCode, + subdivision, + municipality, + ), + ), ); /** One page (1-based) of the feeds located in a node, or null if missing. */ @@ -136,11 +160,14 @@ export const fetchLocationDirectoryFeeds = cache( subdivision?: string, municipality?: string, ): Promise => - await cachedDirectoryFeeds( - getPageOffset(page), - continent, - countryCode, - subdivision, - municipality, + await nullWhenMissing( + async () => + await cachedDirectoryFeeds( + getPageOffset(page), + continent, + countryCode, + subdivision, + municipality, + ), ), ); From d90beff71fd0f88e4a566626b64af1f35cd51f54 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 2 Nov 2026 15:10:57 -0500 Subject: [PATCH 03/16] feat: align location pages with the feed detail page style Use the feed detail page's container and breadcrumb navigation, with its back button, and show GTFS / GTFS-RT / GBFS counts as chips. Child locations are now sorted by feed count, shown as shadowed cards like the advanced search results, and listed in a scrollable box with a search field that filters them by name, ignoring accents and case. Co-Authored-By: Claude Opus 5.5 --- messages/en.json | 5 +- messages/fr.json | 5 +- .../locations/[[...location]]/page.tsx | 138 ++++++++------- .../locations/components/FeedCountChips.tsx | 46 +++++ .../locations/components/FeedCountSummary.tsx | 63 ++----- .../components/LocationBreadcrumbs.tsx | 60 ------- .../components/LocationChildrenGrid.tsx | 150 ++++------------ .../components/LocationChildrenList.tsx | 162 ++++++++++++++++++ .../locations/lib/location-directory.spec.ts | 56 ++++++ .../locations/lib/location-directory.ts | 34 ++++ 10 files changed, 427 insertions(+), 292 deletions(-) create mode 100644 src/app/[locale]/locations/components/FeedCountChips.tsx delete mode 100644 src/app/[locale]/locations/components/LocationBreadcrumbs.tsx create mode 100644 src/app/[locale]/locations/components/LocationChildrenList.tsx diff --git a/messages/en.json b/messages/en.json index 3a7876ad..b3116032 100644 --- a/messages/en.json +++ b/messages/en.json @@ -1271,7 +1271,6 @@ "title": "Feeds by location", "rootIntro": "Browse open GTFS Schedule, GTFS Realtime and GBFS feeds by continent, country, region and municipality.", "nodeIntro": "{total, plural, =0 {No feeds are} one {# feed is} other {# feeds are}} located in {place}.", - "breadcrumbAria": "Location breadcrumb", "feedCountsAria": "Feed counts by data type", "shortLabels": { "gtfs": "GTFS", @@ -1285,6 +1284,10 @@ "municipality": "Municipalities" }, "childFeedTotal": "{count, plural, one {# feed} other {# feeds}}", + "childrenSearchPlaceholder": "Search locations", + "childrenSearchAria": "Filter the locations below by name", + "childrenSearchResults": "{count, plural, =0 {No matching locations} one {# matching location} other {# matching locations}}", + "childrenSearchEmpty": "No location matches “{query}”.", "feedsHeading": "Feeds in {place}", "allFeedsHeading": "All feeds", "resultsRange": "Showing {start}–{end} of {total} feeds", diff --git a/messages/fr.json b/messages/fr.json index 8c14b11c..bd6e12fe 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -1271,7 +1271,6 @@ "title": "Flux par lieu", "rootIntro": "Parcourez les flux ouverts GTFS Schedule, GTFS Realtime et GBFS par continent, pays, région et municipalité.", "nodeIntro": "{total, plural, =0 {Aucun flux n’est situé} one {# flux est situé} other {# flux sont situés}} dans : {place}.", - "breadcrumbAria": "Fil d’Ariane des lieux", "feedCountsAria": "Nombre de flux par type de données", "shortLabels": { "gtfs": "GTFS", @@ -1285,6 +1284,10 @@ "municipality": "Municipalités" }, "childFeedTotal": "{count, plural, one {# flux} other {# flux}}", + "childrenSearchPlaceholder": "Rechercher un lieu", + "childrenSearchAria": "Filtrer les lieux ci-dessous par nom", + "childrenSearchResults": "{count, plural, =0 {Aucun lieu correspondant} one {# lieu correspondant} other {# lieux correspondants}}", + "childrenSearchEmpty": "Aucun lieu ne correspond à « {query} ».", "feedsHeading": "Flux dans : {place}", "allFeedsHeading": "Tous les flux", "resultsRange": "{start}–{end} sur {total} flux", diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx index 4f62ee40..53d64cd7 100644 --- a/src/app/[locale]/locations/[[...location]]/page.tsx +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -3,9 +3,10 @@ import { type Metadata } from 'next'; import { notFound } from 'next/navigation'; import { Box, Container, Typography } from '@mui/material'; import { getTranslations, setRequestLocale } from 'next-intl/server'; -import LocationBreadcrumbs, { - type LocationCrumb, -} from '../components/LocationBreadcrumbs'; +import BreadcrumbNavigation, { + type Crumb, +} from '../../../components/BreadcrumbNavigation'; +import SectionContainer from '../../../components/SectionContainer'; import FeedCountSummary from '../components/FeedCountSummary'; import LocationChildrenGrid from '../components/LocationChildrenGrid'; import LocationFeedsList from '../components/LocationFeedsList'; @@ -139,10 +140,11 @@ export default async function LocationsPage( setRequestLocale(locale); // Directory node and feed page are independent: fetch them in parallel. - const [directory, feeds, t] = await Promise.all([ + const [directory, feeds, t, tCommon] = await Promise.all([ fetchDirectory(query), fetchFeedsPage(query, page), getTranslations('locations'), + getTranslations('common'), ]); if (directory === null || feeds === null) notFound(); @@ -157,7 +159,8 @@ export default async function LocationsPage( const children = directory.children ?? []; const childLevel = getChildLevel(directory.level); - const crumbs: LocationCrumb[] = [ + const crumbs: Crumb[] = [ + { label: tCommon('feeds'), href: '/feeds' }, { label: t('root'), href: isRoot ? undefined : buildLocationHref([]) }, ...breadcrumb.map((node, index) => ({ label: node.name ?? node.slug ?? '', @@ -167,75 +170,88 @@ export default async function LocationsPage( : buildLocationHref(slugs.slice(0, index + 1)), })), ]; + // Without history to pop, back goes one level up the directory. + const backFallbackHref = isRoot + ? '/feeds' + : buildLocationHref(slugs.slice(0, -1)); return ( - - - - {isRoot ? t('title') : breadcrumb[breadcrumb.length - 1]?.name} - - - {isRoot - ? t('rootIntro') - : t('nodeIntro', { - total: getTotalFeedCount(directory.feed_counts), - place, - })} - - - - - {childLevel !== null && children.length > 0 ? ( + + + + + {isRoot ? t('title') : breadcrumb[breadcrumb.length - 1]?.name} + + + {isRoot + ? t('rootIntro') + : t('nodeIntro', { + total: getTotalFeedCount(directory.feed_counts), + place, + })} + + + + + {childLevel !== null && children.length > 0 ? ( + + + {t(`childrenHeading.${childLevel}`)}{' '} + + ({children.length}) + + + + + ) : null} + - {t(`childrenHeading.${childLevel}`)}{' '} - - ({children.length}) - + {isRoot ? t('allFeedsHeading') : t('feedsHeading', { place })} - - ) : null} - - - - {isRoot ? t('allFeedsHeading') : t('feedsHeading', { place })} - - - + ); } diff --git a/src/app/[locale]/locations/components/FeedCountChips.tsx b/src/app/[locale]/locations/components/FeedCountChips.tsx new file mode 100644 index 00000000..9e673cd7 --- /dev/null +++ b/src/app/[locale]/locations/components/FeedCountChips.tsx @@ -0,0 +1,46 @@ +import { type ReactElement } from 'react'; +import { Box, Chip } from '@mui/material'; +import { type FeedCountDataType } from '../lib/location-directory'; + +export interface FeedCountChip { + dataType: FeedCountDataType; + count: number; + /** Already formatted, e.g. "42 GTFS Schedule". */ + label: string; +} + +interface Props { + chips: FeedCountChip[]; + size?: 'small' | 'medium'; + ariaLabel?: string; +} + +/** + * GTFS / GTFS-RT / GBFS counts as outlined chips. Hook-free, so it renders in + * both server and client components. + */ +export default function FeedCountChips({ + chips, + size = 'medium', + ariaLabel, +}: Props): ReactElement { + return ( + + {chips.map(({ dataType, count, label }) => ( + 0 ? 'primary' : 'default'} + sx={count > 0 ? { fontWeight: 700 } : { color: 'text.disabled' }} + /> + ))} + + ); +} diff --git a/src/app/[locale]/locations/components/FeedCountSummary.tsx b/src/app/[locale]/locations/components/FeedCountSummary.tsx index 16580e77..5ce5463b 100644 --- a/src/app/[locale]/locations/components/FeedCountSummary.tsx +++ b/src/app/[locale]/locations/components/FeedCountSummary.tsx @@ -1,6 +1,6 @@ import { type ReactElement } from 'react'; -import { Box, Typography } from '@mui/material'; import { getTranslations } from 'next-intl/server'; +import FeedCountChips from './FeedCountChips'; import { formatCount, getFeedCountEntries, @@ -30,56 +30,15 @@ export default async function FeedCountSummary({ ]); return ( - - {getFeedCountEntries(counts).map(({ dataType, count }) => ( - - - {tCommon(LABEL_KEYS[dataType])} - - 0 ? 'primary.main' : 'text.disabled', - }} - > - {formatCount(count, locale)} - - - ))} - +
    + ({ + dataType, + count, + label: `${formatCount(count, locale)} ${tCommon(LABEL_KEYS[dataType])}`, + }))} + /> +
    ); } diff --git a/src/app/[locale]/locations/components/LocationBreadcrumbs.tsx b/src/app/[locale]/locations/components/LocationBreadcrumbs.tsx deleted file mode 100644 index 27e62281..00000000 --- a/src/app/[locale]/locations/components/LocationBreadcrumbs.tsx +++ /dev/null @@ -1,60 +0,0 @@ -import { type ReactElement } from 'react'; -import { Breadcrumbs, Typography } from '@mui/material'; -import NavigateNextIcon from '@mui/icons-material/NavigateNext'; -import { Link } from '../../../../i18n/navigation'; - -export interface LocationCrumb { - label: string; - /** Omitted on the trailing crumb, the page the user is on. */ - href?: string; -} - -interface Props { - crumbs: LocationCrumb[]; - ariaLabel: string; -} - -export default function LocationBreadcrumbs({ - crumbs, - ariaLabel, -}: Props): ReactElement { - return ( - } - data-testid='location-breadcrumbs' - sx={{ - mb: 1, - '& .MuiBreadcrumbs-ol': { rowGap: 0.5 }, - '& a': { - color: 'text.secondary', - textDecoration: 'none', - borderRadius: '4px', - }, - '& a:hover': { color: 'primary.main', textDecoration: 'underline' }, - '& a:focus-visible': { - outline: '2px solid', - outlineColor: 'primary.main', - outlineOffset: '2px', - }, - }} - > - {crumbs.map((crumb) => - crumb.href != undefined ? ( - - {crumb.label} - - ) : ( - - {crumb.label} - - ), - )} - - ); -} diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx index d69724b0..af197e45 100644 --- a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -1,13 +1,15 @@ import { type ReactElement } from 'react'; -import { Box, Typography } from '@mui/material'; import { getTranslations } from 'next-intl/server'; import { getEmojiFlag, type TCountryCode } from 'countries-list'; -import { Link } from '../../../../i18n/navigation'; +import LocationChildrenList, { + type LocationChildItem, +} from './LocationChildrenList'; import { buildLocationHref, formatCount, getFeedCountEntries, getTotalFeedCount, + sortByFeedCount, type LocationDirectoryNode, } from '../lib/location-directory'; @@ -18,16 +20,17 @@ interface Props { locale: string; } -function getDisplayName(node: LocationDirectoryNode): string { - const name = node.name ?? node.slug ?? ''; - if (node.level === 'country' && node.code != undefined) { - const flag = getEmojiFlag(node.code.toUpperCase() as TCountryCode); - return flag !== '' ? `${flag} ${name}` : name; - } - return name; +function getFlag(node: LocationDirectoryNode): string | undefined { + if (node.level !== 'country' || node.code == undefined) return undefined; + const flag = getEmojiFlag(node.code.toUpperCase() as TCountryCode); + return flag !== '' ? flag : undefined; } -/** Child nodes as link tiles, each with its GTFS / GTFS-RT / GBFS counts. */ +/** + * Child nodes, most feeds first. Everything that needs the server (flags, + * translations, number formatting) is resolved here so the client list only + * filters plain data. + */ export default async function LocationChildrenGrid({ nodes, parentSlugs, @@ -35,111 +38,24 @@ export default async function LocationChildrenGrid({ }: Props): Promise { const t = await getTranslations('locations'); - return ( - - {nodes.map((node) => { - const counts = getFeedCountEntries(node.feed_counts); - const href = buildLocationHref([...parentSlugs, node.slug ?? '']); - return ( -
  • - - - - {getDisplayName(node)} - - - {t('childFeedTotal', { - count: getTotalFeedCount(node.feed_counts), - })} - - - - {counts.map(({ dataType, count }) => ( - 0 ? 'text.secondary' : 'text.disabled', - whiteSpace: 'nowrap', - }} - > - {t(`shortLabels.${dataType}`)}{' '} - 0 ? 'text.primary' : 'inherit', - }} - > - {formatCount(count, locale)} - - - ))} - - -
  • - ); - })} -
    - ); + const items: LocationChildItem[] = sortByFeedCount( + nodes.map((node) => ({ + node, + name: node.name ?? node.slug ?? '', + counts: node.feed_counts, + })), + ).map(({ node, name, counts }) => ({ + slug: node.slug ?? '', + name, + flag: getFlag(node), + href: buildLocationHref([...parentSlugs, node.slug ?? '']), + totalLabel: t('childFeedTotal', { count: getTotalFeedCount(counts) }), + chips: getFeedCountEntries(counts).map(({ dataType, count }) => ({ + dataType, + count, + label: `${formatCount(count, locale)} ${t(`shortLabels.${dataType}`)}`, + })), + })); + + return ; } diff --git a/src/app/[locale]/locations/components/LocationChildrenList.tsx b/src/app/[locale]/locations/components/LocationChildrenList.tsx new file mode 100644 index 00000000..25b88e01 --- /dev/null +++ b/src/app/[locale]/locations/components/LocationChildrenList.tsx @@ -0,0 +1,162 @@ +'use client'; + +import { useMemo, useState, type ReactElement } from 'react'; +import { + Box, + Card, + CardActionArea, + InputAdornment, + TextField, + Typography, +} from '@mui/material'; +import SearchIcon from '@mui/icons-material/Search'; +import { useTranslations } from 'next-intl'; +import { Link } from '../../../../i18n/navigation'; +import FeedCountChips, { type FeedCountChip } from './FeedCountChips'; +import { filterByName } from '../lib/location-directory'; + +export interface LocationChildItem { + slug: string; + name: string; + /** Emoji flag, countries only. */ + flag?: string; + href: string; + totalLabel: string; + chips: FeedCountChip[]; +} + +interface Props { + /** Already sorted, most feeds first. */ + items: LocationChildItem[]; +} + +/** Searchable, scrollable grid of child locations. */ +export default function LocationChildrenList({ items }: Props): ReactElement { + const t = useTranslations('locations'); + const [query, setQuery] = useState(''); + const visibleItems = useMemo( + () => filterByName(items, query), + [items, query], + ); + + return ( + <> + { + setQuery(event.target.value); + }} + placeholder={t('childrenSearchPlaceholder')} + slotProps={{ + htmlInput: { + 'aria-label': t('childrenSearchAria'), + 'aria-controls': 'location-children', + 'data-testid': 'location-children-search', + }, + input: { + startAdornment: ( + + + + ), + }, + }} + sx={{ mb: 1, maxWidth: { md: 480 } }} + /> + + {query.trim() !== '' + ? t('childrenSearchResults', { count: visibleItems.length }) + : null} + + + {visibleItems.length > 0 ? ( + + {visibleItems.map((item) => ( +
  • + + + + + {item.flag != undefined + ? `${item.flag} ${item.name}` + : item.name} + + + {item.totalLabel} + + + + + +
  • + ))} +
    + ) : ( + + {t('childrenSearchEmpty', { query: query.trim() })} + + )} +
    + + ); +} diff --git a/src/app/[locale]/locations/lib/location-directory.spec.ts b/src/app/[locale]/locations/lib/location-directory.spec.ts index b954f6c2..fcb2b989 100644 --- a/src/app/[locale]/locations/lib/location-directory.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory.spec.ts @@ -1,6 +1,7 @@ import { buildLocationHref, buildPlaceName, + filterByName, formatCount, getBreadcrumbSlugs, getChildLevel, @@ -8,9 +9,11 @@ import { getPageCount, getPageOffset, getTotalFeedCount, + normalizeLocationName, type LocationDirectoryNode, parseLocationSegments, parsePageParam, + sortByFeedCount, } from './location-directory'; const breadcrumb: LocationDirectoryNode[] = [ @@ -176,3 +179,56 @@ describe('buildPlaceName', () => { expect(buildPlaceName(breadcrumb)).toBe('Montréal, Québec, Canada'); }); }); + +describe('normalizeLocationName', () => { + it('drops accents and case', () => { + expect(normalizeLocationName(' Québec ')).toBe('quebec'); + expect(normalizeLocationName('São Paulo')).toBe('sao paulo'); + }); +}); + +describe('sortByFeedCount', () => { + const item = ( + name: string, + total: number, + ): { name: string; counts: { total: number } } => ({ + name, + counts: { total }, + }); + + it('puts the most feeds first, then sorts by name', () => { + const sorted = sortByFeedCount([ + item('Laval', 3), + item('Montréal', 22), + item('Québec', 3), + item('Gatineau', 1), + item('Lévis', 3), + ]); + expect(sorted.map(({ name }) => name)).toEqual([ + 'Montréal', + 'Laval', + 'Lévis', + 'Québec', + 'Gatineau', + ]); + }); + + it('does not mutate its input', () => { + const items = [item('B', 1), item('A', 2)]; + sortByFeedCount(items); + expect(items.map(({ name }) => name)).toEqual(['B', 'A']); + }); +}); + +describe('filterByName', () => { + const items = [{ name: 'Montréal' }, { name: 'Québec' }, { name: 'Laval' }]; + + it('matches anywhere in the name, ignoring accents and case', () => { + expect(filterByName(items, 'MONTRE')).toEqual([{ name: 'Montréal' }]); + expect(filterByName(items, 'bec')).toEqual([{ name: 'Québec' }]); + }); + + it('returns every item for a blank query', () => { + expect(filterByName(items, ' ')).toEqual(items); + }); +}); diff --git a/src/app/[locale]/locations/lib/location-directory.ts b/src/app/[locale]/locations/lib/location-directory.ts index 010d8912..cdce6d46 100644 --- a/src/app/[locale]/locations/lib/location-directory.ts +++ b/src/app/[locale]/locations/lib/location-directory.ts @@ -141,6 +141,40 @@ export function getTotalFeedCount( ); } +/** Lowercased and without accents, so "Québec" matches "quebec". */ +export function normalizeLocationName(name: string): string { + return name + .normalize('NFD') + .replace(/\p{Diacritic}/gu, '') + .toLowerCase() + .trim(); +} + +/** Most feeds first; ties by name, ignoring accents and case. */ +export function sortByFeedCount< + T extends { name: string; counts: LocationDirectoryFeedCounts | undefined }, +>(items: readonly T[]): T[] { + return [...items].sort( + (a, b) => + getTotalFeedCount(b.counts) - getTotalFeedCount(a.counts) || + normalizeLocationName(a.name).localeCompare( + normalizeLocationName(b.name), + ), + ); +} + +/** Items whose name contains the query, ignoring accents and case. */ +export function filterByName( + items: readonly T[], + query: string, +): T[] { + const normalizedQuery = normalizeLocationName(query); + if (normalizedQuery === '') return [...items]; + return items.filter((item) => + normalizeLocationName(item.name).includes(normalizedQuery), + ); +} + /** Locale-aware integer formatting, e.g. 1234 -> "1,234" (en). */ export function formatCount(value: number | undefined, locale: string): string { return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format( From 4374d1df4702025c7918f5bdb871de86c0e55625 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Tue, 3 Nov 2026 08:12:20 -0500 Subject: [PATCH 04/16] feat: use country names in location URLs and refine directory cards - Country segments use name slugs (/locations/europe/portugal) through the API's new `country` parameter; API types regenerated. - Child cards show per-type feed counts as plain text instead of chips. - Child search field gets a white background. - No viewport prefetch on child cards and pagination links. - Directory data cache lowered from 1 day to 6 hours. Co-Authored-By: Claude Opus 5.5 --- .../locations/[[...location]]/page.tsx | 4 +- .../components/LocationChildrenGrid.tsx | 2 +- .../components/LocationChildrenList.tsx | 36 ++++++++++++++-- .../components/LocationFeedsList.tsx | 1 + .../locations/lib/location-directory-data.ts | 31 ++++++------- .../locations/lib/location-directory.spec.ts | 20 ++++++--- .../locations/lib/location-directory.ts | 7 +-- src/app/services/feeds/types.ts | 22 +++++----- src/mocks/locationDirectory.spec.ts | 8 ++-- src/mocks/locationDirectory.ts | 43 +++++++++++-------- 10 files changed, 107 insertions(+), 67 deletions(-) diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx index 53d64cd7..97d6c089 100644 --- a/src/app/[locale]/locations/[[...location]]/page.tsx +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -58,7 +58,7 @@ function fetchDirectory( ): ReturnType { return fetchLocationDirectory( query.continent, - query.country_code, + query.country, query.subdivision, query.municipality, ); @@ -71,7 +71,7 @@ function fetchFeedsPage( return fetchLocationDirectoryFeeds( page, query.continent, - query.country_code, + query.country, query.subdivision, query.municipality, ); diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx index af197e45..04ee1d69 100644 --- a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -50,7 +50,7 @@ export default async function LocationChildrenGrid({ flag: getFlag(node), href: buildLocationHref([...parentSlugs, node.slug ?? '']), totalLabel: t('childFeedTotal', { count: getTotalFeedCount(counts) }), - chips: getFeedCountEntries(counts).map(({ dataType, count }) => ({ + counts: getFeedCountEntries(counts).map(({ dataType, count }) => ({ dataType, count, label: `${formatCount(count, locale)} ${t(`shortLabels.${dataType}`)}`, diff --git a/src/app/[locale]/locations/components/LocationChildrenList.tsx b/src/app/[locale]/locations/components/LocationChildrenList.tsx index 25b88e01..2d160ff7 100644 --- a/src/app/[locale]/locations/components/LocationChildrenList.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenList.tsx @@ -12,7 +12,7 @@ import { import SearchIcon from '@mui/icons-material/Search'; import { useTranslations } from 'next-intl'; import { Link } from '../../../../i18n/navigation'; -import FeedCountChips, { type FeedCountChip } from './FeedCountChips'; +import { type FeedCountChip } from './FeedCountChips'; import { filterByName } from '../lib/location-directory'; export interface LocationChildItem { @@ -22,7 +22,8 @@ export interface LocationChildItem { flag?: string; href: string; totalLabel: string; - chips: FeedCountChip[]; + /** Plain-text counts; chips are kept for the page summary. */ + counts: FeedCountChip[]; } interface Props { @@ -64,7 +65,12 @@ export default function LocationChildrenList({ items }: Props): ReactElement { ), }, }} - sx={{ mb: 1, maxWidth: { md: 480 } }} + sx={{ + mb: 1, + maxWidth: { md: 480 }, + // White in light mode, like the cards below; the section is paper. + '& .MuiInputBase-root': { bgcolor: 'background.default' }, + }} />
    - + + {item.counts.map(({ dataType, count, label }) => ( + 0 ? 'text.secondary' : 'text.disabled'} + > + {label} + + ))} + diff --git a/src/app/[locale]/locations/components/LocationFeedsList.tsx b/src/app/[locale]/locations/components/LocationFeedsList.tsx index 257430de..7b81285f 100644 --- a/src/app/[locale]/locations/components/LocationFeedsList.tsx +++ b/src/app/[locale]/locations/components/LocationFeedsList.tsx @@ -76,6 +76,7 @@ export default function LocationFeedsList({ slugs, Math.min(Math.max(item.page ?? 1, 1), pageCount), )}#${FEEDS_SECTION_ID}`} + prefetch={false} {...item} /> )} diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index 4b387d3c..27838a86 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -22,15 +22,15 @@ import { type LocationQuery, } from './location-directory'; -/** 1 day; also flushed on demand with the existing `guest-feeds` tag. */ -export const LOCATION_DIRECTORY_REVALIDATE_SECONDS = 86400; +/** 6 hours; also flushed on demand with the existing `guest-feeds` tag. */ +export const LOCATION_DIRECTORY_REVALIDATE_SECONDS = 21600; const CACHE_TAGS = ['location-directory', 'guest-feeds']; /** * 400 (invalid hierarchy) and 404 (nothing located there) both mean the URL * does not exist. They are thrown as this error inside the cached functions, * because unstable_cache never stores a thrown error: caching the miss would - * keep a location missing for a whole day after it starts to exist (e.g. a + * keep a location missing for hours after it starts to exist (e.g. a * 404 served before the API route was deployed). */ class LocationNotFoundError extends Error {} @@ -69,13 +69,13 @@ async function nullWhenMissing( function toQuery( continent: string | undefined, - countryCode: string | undefined, + country: string | undefined, subdivision: string | undefined, municipality: string | undefined, ): LocationQuery { const query: LocationQuery = {}; if (continent != undefined) query.continent = continent; - if (countryCode != undefined) query.country_code = countryCode; + if (country != undefined) query.country = country; if (subdivision != undefined) query.subdivision = subdivision; if (municipality != undefined) query.municipality = municipality; return query; @@ -86,7 +86,7 @@ function toQuery( const cachedDirectory = unstable_cache( async ( continent?: string, - countryCode?: string, + country?: string, subdivision?: string, municipality?: string, ): Promise => { @@ -94,7 +94,7 @@ const cachedDirectory = unstable_cache( return await requireData( async () => await getLocationDirectory( - toQuery(continent, countryCode, subdivision, municipality), + toQuery(continent, country, subdivision, municipality), accessToken, ), ); @@ -107,7 +107,7 @@ const cachedDirectoryFeeds = unstable_cache( async ( offset: number, continent?: string, - countryCode?: string, + country?: string, subdivision?: string, municipality?: string, ): Promise => { @@ -116,7 +116,7 @@ const cachedDirectoryFeeds = unstable_cache( async () => await getLocationDirectoryFeeds( { - ...toQuery(continent, countryCode, subdivision, municipality), + ...toQuery(continent, country, subdivision, municipality), limit: LOCATION_FEEDS_PAGE_SIZE, offset, }, @@ -136,18 +136,13 @@ const cachedDirectoryFeeds = unstable_cache( export const fetchLocationDirectory = cache( async ( continent?: string, - countryCode?: string, + country?: string, subdivision?: string, municipality?: string, ): Promise => await nullWhenMissing( async () => - await cachedDirectory( - continent, - countryCode, - subdivision, - municipality, - ), + await cachedDirectory(continent, country, subdivision, municipality), ), ); @@ -156,7 +151,7 @@ export const fetchLocationDirectoryFeeds = cache( async ( page: number, continent?: string, - countryCode?: string, + country?: string, subdivision?: string, municipality?: string, ): Promise => @@ -165,7 +160,7 @@ export const fetchLocationDirectoryFeeds = cache( await cachedDirectoryFeeds( getPageOffset(page), continent, - countryCode, + country, subdivision, municipality, ), diff --git a/src/app/[locale]/locations/lib/location-directory.spec.ts b/src/app/[locale]/locations/lib/location-directory.spec.ts index fcb2b989..ff0c6640 100644 --- a/src/app/[locale]/locations/lib/location-directory.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory.spec.ts @@ -23,7 +23,7 @@ const breadcrumb: LocationDirectoryNode[] = [ code: 'NA', name: 'North America', }, - { level: 'country', slug: 'ca', code: 'CA', name: 'Canada' }, + { level: 'country', slug: 'canada', code: 'CA', name: 'Canada' }, { level: 'subdivision', slug: 'quebec', code: null, name: 'Québec' }, { level: 'municipality', slug: 'montreal', code: null, name: 'Montréal' }, ]; @@ -39,10 +39,10 @@ describe('parseLocationSegments', () => { continent: 'north-america', }); expect( - parseLocationSegments(['north-america', 'ca', 'quebec', 'montreal']), + parseLocationSegments(['north-america', 'canada', 'quebec', 'montreal']), ).toEqual({ continent: 'north-america', - country_code: 'ca', + country: 'canada', subdivision: 'quebec', municipality: 'montreal', }); @@ -50,7 +50,13 @@ describe('parseLocationSegments', () => { it('rejects paths deeper than a municipality', () => { expect( - parseLocationSegments(['north-america', 'ca', 'quebec', 'montreal', 'x']), + parseLocationSegments([ + 'north-america', + 'canada', + 'quebec', + 'montreal', + 'x', + ]), ).toBeNull(); }); @@ -103,8 +109,8 @@ describe('buildLocationHref', () => { it('builds the root and nested paths', () => { expect(buildLocationHref([])).toBe('/locations'); expect( - buildLocationHref(['north-america', 'ca', 'quebec', 'montreal']), - ).toBe('/locations/north-america/ca/quebec/montreal'); + buildLocationHref(['north-america', 'canada', 'quebec', 'montreal']), + ).toBe('/locations/north-america/canada/quebec/montreal'); }); it('adds ?page only after the first page', () => { @@ -119,7 +125,7 @@ describe('buildLocationHref', () => { it('round-trips with the breadcrumb slugs', () => { expect(buildLocationHref(getBreadcrumbSlugs(breadcrumb), 2)).toBe( - '/locations/north-america/ca/quebec/montreal?page=2', + '/locations/north-america/canada/quebec/montreal?page=2', ); expect(getBreadcrumbSlugs(undefined)).toEqual([]); }); diff --git a/src/app/[locale]/locations/lib/location-directory.ts b/src/app/[locale]/locations/lib/location-directory.ts index cdce6d46..c3dc11e2 100644 --- a/src/app/[locale]/locations/lib/location-directory.ts +++ b/src/app/[locale]/locations/lib/location-directory.ts @@ -22,14 +22,15 @@ export const FEEDS_SECTION_ID = 'feeds'; /** Query parameters shared by both directory endpoints. */ export interface LocationQuery { continent?: string; - country_code?: string; + /** Country slug, e.g. `canada`. */ + country?: string; subdivision?: string; municipality?: string; } const QUERY_KEYS_BY_DEPTH = [ 'continent', - 'country_code', + 'country', 'subdivision', 'municipality', ] as const; @@ -91,7 +92,7 @@ export function getPageOffset( /** * Locale-less path to a directory node, e.g. - * `/locations/north-america/ca/quebec?page=2`. Page 1 has no query string so + * `/locations/north-america/canada/quebec?page=2`. Page 1 has no query string so * that it stays the canonical URL of the node. Pass the result to the * next-intl `Link`, which adds the locale prefix. */ diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index 585c159b..bee0a805 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -366,7 +366,7 @@ export interface paths { path?: never; cookie?: never; }; - /** @description Browse the feed location directory one level at a time: continent > country > subdivision > municipality. The level is selected by the most specific parameter provided; with no parameters the response lists continents.
    Feed counts are based on the feeds' declared locations, only include feeds with a status of `active`, `inactive`, `development` or `future`, and roll up to every ancestor level (a feed located in Montréal counts toward Québec, Canada and North America). A feed is counted at most once per node, even when it declares several locations within that node.
    Each parameter requires its parent: `country_code` requires `continent`, `subdivision` requires `country_code`, and `municipality` requires `subdivision`. */ + /** @description Browse the feed location directory one level at a time: continent > country > subdivision > municipality. The level is selected by the most specific parameter provided; with no parameters the response lists continents.
    Feed counts are based on the feeds' declared locations, only include feeds with a status of `active`, `inactive`, `development` or `future`, and roll up to every ancestor level (a feed located in Montréal counts toward Québec, Canada and North America). A feed is counted at most once per node, even when it declares several locations within that node.
    Each parameter requires its parent: `country` requires `continent`, `subdivision` requires `country`, and `municipality` requires `subdivision`. */ get: operations['getLocationDirectory']; put?: never; post?: never; @@ -1375,7 +1375,7 @@ export interface components { LocationDirectoryNode: { level?: components['schemas']['LocationDirectoryLevel']; /** - * @description URL-safe identifier of the node, used as the matching request parameter. Continents use a fixed slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`), countries use their lowercase ISO 3166-1 alpha-2 code, and subdivisions and municipalities use their name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Québec` -> `quebec`, `Saint-Jean-sur-Richelieu` -> `saint-jean-sur-richelieu`). + * @description URL-safe identifier of the node, used as the matching request parameter. Continents use a fixed slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`), countries use a fixed slug of their short English name (`portugal`, `united-states`, `cote-d-ivoire`), and subdivisions and municipalities use their name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Québec` -> `quebec`, `Saint-Jean-sur-Richelieu` -> `saint-jean-sur-richelieu`). * @example quebec */ slug?: string; @@ -1920,9 +1920,9 @@ export interface components { has_seal_query_param: boolean; /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ location_directory_continent: string; - /** @description ISO 3166-1 alpha-2 country code. Case-insensitive. Requires `continent`. */ - location_directory_country_code: string; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country_code`. */ + /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ + location_directory_country: string; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ location_directory_subdivision: string; /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ location_directory_municipality: string; @@ -2670,9 +2670,9 @@ export interface operations { query?: { /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ continent?: components['parameters']['location_directory_continent']; - /** @description ISO 3166-1 alpha-2 country code. Case-insensitive. Requires `continent`. */ - country_code?: components['parameters']['location_directory_country_code']; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country_code`. */ + /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ + country?: components['parameters']['location_directory_country']; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ subdivision?: components['parameters']['location_directory_subdivision']; /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ municipality?: components['parameters']['location_directory_municipality']; @@ -2713,9 +2713,9 @@ export interface operations { query?: { /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ continent?: components['parameters']['location_directory_continent']; - /** @description ISO 3166-1 alpha-2 country code. Case-insensitive. Requires `continent`. */ - country_code?: components['parameters']['location_directory_country_code']; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country_code`. */ + /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ + country?: components['parameters']['location_directory_country']; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ subdivision?: components['parameters']['location_directory_subdivision']; /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ municipality?: components['parameters']['location_directory_municipality']; diff --git a/src/mocks/locationDirectory.spec.ts b/src/mocks/locationDirectory.spec.ts index 00907ef7..6ccc6bb5 100644 --- a/src/mocks/locationDirectory.spec.ts +++ b/src/mocks/locationDirectory.spec.ts @@ -31,7 +31,7 @@ describe('location directory mocks', () => { it('resolves the Montréal breadcrumb and rolls counts up', () => { const query = readDirectoryQuery( new URLSearchParams( - 'continent=north-america&country_code=ca&subdivision=quebec&municipality=montreal', + 'continent=north-america&country=canada&subdivision=quebec&municipality=montreal', ), ); const result = getMockDirectory(query); @@ -51,9 +51,9 @@ describe('location directory mocks', () => { }); it('returns 400 on a broken hierarchy and 404 when nothing is there', () => { - expect(getMockDirectory({ country_code: 'ca' }).status).toBe(400); + expect(getMockDirectory({ country: 'canada' }).status).toBe(400); expect( - getMockDirectory({ continent: 'europe', country_code: 'ca' }).status, + getMockDirectory({ continent: 'europe', country: 'canada' }).status, ).toBe(400); expect(getMockDirectory({ continent: 'antarctica' }).status).toBe(404); }); @@ -61,7 +61,7 @@ describe('location directory mocks', () => { it('paginates feeds, most relevant to the node first', () => { const query = { continent: 'north-america', - country_code: 'ca', + country: 'canada', subdivision: 'quebec', }; const first = getMockDirectoryFeeds(query, 20, 0); diff --git a/src/mocks/locationDirectory.ts b/src/mocks/locationDirectory.ts index 3d0f58fc..4a662629 100644 --- a/src/mocks/locationDirectory.ts +++ b/src/mocks/locationDirectory.ts @@ -44,6 +44,13 @@ export function slugify(name: string): string { .replace(/^-+|-+$/g, ''); } +/** ISO code of a country slug (`united-states` -> `US`), like the API. */ +function countryCodeOf(slug: string): string | undefined { + return Object.keys(COUNTRIES).find( + (code) => slugify(COUNTRIES[code].name) === slug.toLowerCase(), + ); +} + type Place = [countryCode: string, subdivision?: string, municipality?: string]; type FeedSeed = [ dataType: Feed['data_type'], @@ -259,7 +266,8 @@ export const MOCK_FEEDS: Feed[] = FEED_SEEDS.map(toFeed); export interface DirectoryQuery { continent?: string; - country_code?: string; + /** Country slug, e.g. `canada`. */ + country?: string; subdivision?: string; municipality?: string; } @@ -279,8 +287,8 @@ function matches(location: FeedLocation, query: DirectoryQuery): boolean { if (query.continent != undefined && country.continent !== query.continent) return false; if ( - query.country_code != undefined && - location.country_code?.toLowerCase() !== query.country_code.toLowerCase() + query.country != undefined && + slugify(country.name) !== query.country.toLowerCase() ) return false; if ( @@ -314,21 +322,20 @@ function countFeeds(feeds: Feed[]): FeedCounts { function levelOf(query: DirectoryQuery): DirectoryLevel { if (query.municipality != undefined) return 'municipality'; if (query.subdivision != undefined) return 'subdivision'; - if (query.country_code != undefined) return 'country'; + if (query.country != undefined) return 'country'; if (query.continent != undefined) return 'continent'; return 'root'; } /** 400 when a parameter is missing its parent or the country is elsewhere. */ function isValidHierarchy(query: DirectoryQuery): boolean { - if (query.country_code != undefined && query.continent == undefined) - return false; - if (query.subdivision != undefined && query.country_code == undefined) + if (query.country != undefined && query.continent == undefined) return false; + if (query.subdivision != undefined && query.country == undefined) return false; if (query.municipality != undefined && query.subdivision == undefined) return false; - if (query.country_code != undefined) { - const country = COUNTRIES[query.country_code.toUpperCase()]; + if (query.country != undefined) { + const country = COUNTRIES[countryCodeOf(query.country) ?? '']; if (country != undefined && country.continent !== query.continent) return false; } @@ -365,11 +372,10 @@ function nodeFor( : makeNode(level, slug, continent.code, continent.name, query); } case 'country': { - const code = (query.country_code ?? '').toUpperCase(); + const code = countryCodeOf(query.country ?? ''); + if (code == undefined) return undefined; const country = COUNTRIES[code]; - return country == undefined - ? undefined - : makeNode(level, code.toLowerCase(), code, country.name, query); + return makeNode(level, slugify(country.name), code, country.name, query); } case 'subdivision': return makeNode( @@ -419,7 +425,10 @@ function childrenOf(query: DirectoryQuery): DirectoryNode[] { if (level === 'root') { childQuery = { continent: COUNTRIES[countryCode].continent }; } else if (level === 'continent') { - childQuery = { ...query, country_code: countryCode.toLowerCase() }; + childQuery = { + ...query, + country: slugify(COUNTRIES[countryCode].name), + }; } else if (level === 'country' && location.subdivision_name != null) { name = location.subdivision_name; childQuery = { ...query, subdivision: slugify(name) }; @@ -444,8 +453,8 @@ function breadcrumbOf(query: DirectoryQuery): DirectoryNode[] { const all = feedsIn(query); const steps: DirectoryQuery[] = []; if (query.continent != undefined) steps.push({ continent: query.continent }); - if (query.country_code != undefined) - steps.push({ ...steps[0], country_code: query.country_code }); + if (query.country != undefined) + steps.push({ ...steps[0], country: query.country }); if (query.subdivision != undefined) steps.push({ ...steps[1], subdivision: query.subdivision }); if (query.municipality != undefined) @@ -474,7 +483,7 @@ export function readDirectoryQuery(params: URLSearchParams): DirectoryQuery { }; return { continent: read('continent'), - country_code: read('country_code'), + country: read('country'), subdivision: read('subdivision'), municipality: read('municipality'), }; From aa7ef320891ffacda67072e091c5510281e3d607 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Tue, 3 Nov 2026 08:59:55 -0500 Subject: [PATCH 05/16] feat: add loading states and bold counts to location directory cards - Clicking a child location shows a pending bar on its card (useLinkStatus, delayed 150ms to avoid flashing on fast navigations). - loading.tsx renders a skeleton of the location page while it streams. - Feed counts on child cards show their numbers in bold. Co-Authored-By: Claude Opus 5.5 --- messages/en.json | 3 +- messages/fr.json | 3 +- .../locations/[[...location]]/loading.tsx | 99 +++++++++++++++++++ .../components/LinkPendingIndicator.tsx | 42 ++++++++ .../components/LocationChildrenGrid.tsx | 8 +- .../components/LocationChildrenList.tsx | 61 ++++++++---- 6 files changed, 195 insertions(+), 21 deletions(-) create mode 100644 src/app/[locale]/locations/[[...location]]/loading.tsx create mode 100644 src/app/[locale]/locations/components/LinkPendingIndicator.tsx diff --git a/messages/en.json b/messages/en.json index b3116032..357520b9 100644 --- a/messages/en.json +++ b/messages/en.json @@ -1283,9 +1283,10 @@ "subdivision": "Regions", "municipality": "Municipalities" }, - "childFeedTotal": "{count, plural, one {# feed} other {# feeds}}", + "childFeedTotal": "{count, plural, one {# feed} other {# feeds}}", "childrenSearchPlaceholder": "Search locations", "childrenSearchAria": "Filter the locations below by name", + "childLoadingAria": "Loading {name}", "childrenSearchResults": "{count, plural, =0 {No matching locations} one {# matching location} other {# matching locations}}", "childrenSearchEmpty": "No location matches “{query}”.", "feedsHeading": "Feeds in {place}", diff --git a/messages/fr.json b/messages/fr.json index bd6e12fe..b19d46ad 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -1283,9 +1283,10 @@ "subdivision": "Régions", "municipality": "Municipalités" }, - "childFeedTotal": "{count, plural, one {# flux} other {# flux}}", + "childFeedTotal": "{count, plural, one {# flux} other {# flux}}", "childrenSearchPlaceholder": "Rechercher un lieu", "childrenSearchAria": "Filtrer les lieux ci-dessous par nom", + "childLoadingAria": "Chargement de {name}", "childrenSearchResults": "{count, plural, =0 {Aucun lieu correspondant} one {# lieu correspondant} other {# lieux correspondants}}", "childrenSearchEmpty": "Aucun lieu ne correspond à « {query} ».", "feedsHeading": "Flux dans : {place}", diff --git a/src/app/[locale]/locations/[[...location]]/loading.tsx b/src/app/[locale]/locations/[[...location]]/loading.tsx new file mode 100644 index 00000000..4f26a04e --- /dev/null +++ b/src/app/[locale]/locations/[[...location]]/loading.tsx @@ -0,0 +1,99 @@ +import { type ReactElement } from 'react'; +import { Box, Container, Skeleton } from '@mui/material'; +import SectionContainer from '../../../components/SectionContainer'; + +const CARD_COUNT = 8; +const ROW_COUNT = 8; + +/** + * Shown while a location page streams in, e.g. after clicking a child + * location; same layout as page.tsx so nothing jumps when it resolves. + * ref: https://nextjs.org/docs/app/api-reference/file-conventions/loading + */ +export default function Loading(): ReactElement { + return ( + + + {/* Back button and breadcrumb */} + + {/* Title and intro */} + + + {/* Feed count chips */} + + {[150, 140, 100].map((width) => ( + + ))} + + + {/* Child locations */} + + + {Array.from({ length: CARD_COUNT }, (_, index) => ( + + ))} + + + {/* Feeds table */} + + {Array.from({ length: ROW_COUNT }, (_, index) => ( + + ))} + + + ); +} diff --git a/src/app/[locale]/locations/components/LinkPendingIndicator.tsx b/src/app/[locale]/locations/components/LinkPendingIndicator.tsx new file mode 100644 index 00000000..f1df17e4 --- /dev/null +++ b/src/app/[locale]/locations/components/LinkPendingIndicator.tsx @@ -0,0 +1,42 @@ +'use client'; + +import { type ReactElement } from 'react'; +import { LinearProgress } from '@mui/material'; +import { keyframes } from '@mui/material/styles'; +// useLinkStatus is not re-exported by i18n/navigation; it reads the status of +// the nearest enclosing Link, which next-intl's Link renders under the hood. +import { useLinkStatus } from 'next/link'; + +// Fast navigations finish before the bar shows, so it never flashes. +const appearAfterDelay = keyframes` + to { opacity: 1; } +`; + +interface Props { + ariaLabel: string; +} + +/** + * Thin bar along the bottom of the enclosing Link while its navigation is + * pending. Must render inside a Link; the Link needs `position: relative`. + */ +export default function LinkPendingIndicator({ + ariaLabel, +}: Props): ReactElement | null { + const { pending } = useLinkStatus(); + if (!pending) return null; + return ( + + ); +} diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx index 04ee1d69..493ed546 100644 --- a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -49,11 +49,15 @@ export default async function LocationChildrenGrid({ name, flag: getFlag(node), href: buildLocationHref([...parentSlugs, node.slug ?? '']), - totalLabel: t('childFeedTotal', { count: getTotalFeedCount(counts) }), + totalLabel: t.rich('childFeedTotal', { + count: getTotalFeedCount(counts), + b: (chunks) => {chunks}, + }), counts: getFeedCountEntries(counts).map(({ dataType, count }) => ({ dataType, count, - label: `${formatCount(count, locale)} ${t(`shortLabels.${dataType}`)}`, + formattedCount: formatCount(count, locale), + typeLabel: t(`shortLabels.${dataType}`), })), })); diff --git a/src/app/[locale]/locations/components/LocationChildrenList.tsx b/src/app/[locale]/locations/components/LocationChildrenList.tsx index 2d160ff7..ee2f03f5 100644 --- a/src/app/[locale]/locations/components/LocationChildrenList.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenList.tsx @@ -1,6 +1,6 @@ 'use client'; -import { useMemo, useState, type ReactElement } from 'react'; +import { useMemo, useState, type ReactElement, type ReactNode } from 'react'; import { Box, Card, @@ -12,8 +12,20 @@ import { import SearchIcon from '@mui/icons-material/Search'; import { useTranslations } from 'next-intl'; import { Link } from '../../../../i18n/navigation'; -import { type FeedCountChip } from './FeedCountChips'; -import { filterByName } from '../lib/location-directory'; +import LinkPendingIndicator from './LinkPendingIndicator'; +import { + filterByName, + type FeedCountDataType, +} from '../lib/location-directory'; + +export interface LocationChildCount { + dataType: FeedCountDataType; + count: number; + /** Locale-formatted, rendered bold. */ + formattedCount: string; + /** e.g. "GTFS-RT". */ + typeLabel: string; +} export interface LocationChildItem { slug: string; @@ -21,11 +33,17 @@ export interface LocationChildItem { /** Emoji flag, countries only. */ flag?: string; href: string; - totalLabel: string; + /** e.g. "8 feeds", with the number in a . */ + totalLabel: ReactNode; /** Plain-text counts; chips are kept for the page summary. */ - counts: FeedCountChip[]; + counts: LocationChildCount[]; } +// Bold, primary-colored numbers stand out from their secondary-colored labels. +const countNumberSx = { + '& strong': { fontWeight: 700, color: 'text.primary' }, +} as const; + interface Props { /** Already sorted, most feeds first. */ items: LocationChildItem[]; @@ -149,7 +167,7 @@ export default function LocationChildrenList({ items }: Props): ReactElement { component='span' variant='body2' color='text.secondary' - sx={{ whiteSpace: 'nowrap' }} + sx={{ whiteSpace: 'nowrap', ...countNumberSx }} > {item.totalLabel} @@ -162,18 +180,27 @@ export default function LocationChildrenList({ items }: Props): ReactElement { rowGap: 0.5, }} > - {item.counts.map(({ dataType, count, label }) => ( - 0 ? 'text.secondary' : 'text.disabled'} - > - {label} - - ))} + {item.counts.map( + ({ dataType, count, formattedCount, typeLabel }) => ( + 0 ? 'text.secondary' : 'text.disabled' + } + // Zero counts stay fully disabled. + sx={count > 0 ? countNumberSx : undefined} + > + {formattedCount} {typeLabel} + + ), + )} + From 194f056cad2666a0eb7b0070e56278bb27e485c4 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Tue, 3 Nov 2026 09:44:25 -0500 Subject: [PATCH 06/16] feat: list location directory feeds through the search endpoint The feeds of a location node come from /v1/search with the node's location parameters, the directory statuses and sort=location, replacing the removed /v1/locations/directory/feeds endpoint. The root page has no location, so it lists the newest feeds first. API types regenerated and the search mock serves directory feeds for location queries. Co-Authored-By: Claude Opus 5.5 --- .../lib/location-directory-data.spec.ts | 39 +++++++- .../locations/lib/location-directory-data.ts | 27 ++++-- src/app/services/feeds/index.ts | 40 ++------ src/app/services/feeds/types.ts | 93 ++++++------------- src/mocks/handlers.ts | 29 +++--- src/mocks/locationDirectory.ts | 7 +- 6 files changed, 109 insertions(+), 126 deletions(-) diff --git a/src/app/[locale]/locations/lib/location-directory-data.spec.ts b/src/app/[locale]/locations/lib/location-directory-data.spec.ts index 9c9b0bd3..037f36f0 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.spec.ts @@ -33,7 +33,7 @@ jest.mock('next/cache', () => ({ })); const mockGetLocationDirectory = jest.fn(); -const mockGetLocationDirectoryFeeds = jest.fn(); +const mockSearchFeeds = jest.fn(); jest.mock('../../../services/feeds', () => ({ ApiError: class ApiError extends Error { @@ -45,8 +45,7 @@ jest.mock('../../../services/feeds', () => ({ }, getLocationDirectory: (...args: unknown[]) => mockGetLocationDirectory(...args), - getLocationDirectoryFeeds: (...args: unknown[]) => - mockGetLocationDirectoryFeeds(...args), + searchFeeds: (...args: unknown[]) => mockSearchFeeds(...args), })); jest.mock('../../../utils/auth-server', () => ({ @@ -63,7 +62,7 @@ const directory = { describe('location directory data', () => { beforeEach(() => { mockGetLocationDirectory.mockReset(); - mockGetLocationDirectoryFeeds.mockReset(); + mockSearchFeeds.mockReset(); }); it('resolves a 404 to null without caching it', async () => { @@ -78,7 +77,7 @@ describe('location directory data', () => { it('resolves a 400 on the feeds page to null without caching it', async () => { const feeds = { total: 0, results: [] }; - mockGetLocationDirectoryFeeds + mockSearchFeeds .mockRejectedValueOnce(new ApiError('Bad Request', 400)) .mockResolvedValueOnce(feeds); @@ -88,6 +87,36 @@ describe('location directory data', () => { ); }); + it('lists the feeds of a node with search, most relevant first', async () => { + mockSearchFeeds.mockResolvedValue({ total: 0, results: [] }); + + await fetchLocationDirectoryFeeds(2, 'europe', 'portugal'); + expect(mockSearchFeeds).toHaveBeenCalledWith( + { + query: { + continent: 'europe', + country: 'portugal', + status: ['active', 'inactive', 'development', 'future'], + sort: 'location', + limit: 20, + offset: 20, + }, + }, + 'guest-token', + ); + }); + + it('lists the newest feeds at the root, which has no location', async () => { + mockSearchFeeds.mockResolvedValue({ total: 0, results: [] }); + + await fetchLocationDirectoryFeeds(1); + const [{ query }] = mockSearchFeeds.mock.calls[0] as [ + { query: Record }, + ]; + expect(query.sort).toBeUndefined(); + expect(query.continent).toBeUndefined(); + }); + it('caches a found location', async () => { mockGetLocationDirectory.mockResolvedValue(directory); diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index 27838a86..831792ef 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -12,9 +12,9 @@ import { getGuestGcipIdToken } from '../../../utils/auth-server'; import { ApiError, getLocationDirectory, - getLocationDirectoryFeeds, - type LocationDirectoryFeedsResponse, + searchFeeds, type LocationDirectoryResponse, + type SearchFeedsResponse, } from '../../../services/feeds'; import { getPageOffset, @@ -26,6 +26,11 @@ import { export const LOCATION_DIRECTORY_REVALIDATE_SECONDS = 21600; const CACHE_TAGS = ['location-directory', 'guest-feeds']; +/** The statuses the directory counts, so a node lists as many feeds. */ +const DIRECTORY_FEED_STATUSES: Array< + 'active' | 'inactive' | 'development' | 'future' +> = ['active', 'inactive', 'development', 'future']; + /** * 400 (invalid hierarchy) and 404 (nothing located there) both mean the URL * does not exist. They are thrown as this error inside the cached functions, @@ -110,15 +115,21 @@ const cachedDirectoryFeeds = unstable_cache( country?: string, subdivision?: string, municipality?: string, - ): Promise => { + ): Promise => { const accessToken = await getGuestGcipIdToken(); return await requireData( async () => - await getLocationDirectoryFeeds( + await searchFeeds( { - ...toQuery(continent, country, subdivision, municipality), - limit: LOCATION_FEEDS_PAGE_SIZE, - offset, + query: { + ...toQuery(continent, country, subdivision, municipality), + status: DIRECTORY_FEED_STATUSES, + // Most relevant location first; the API rejects it without a + // location, so the root lists the newest feeds first. + sort: continent != undefined ? 'location' : undefined, + limit: LOCATION_FEEDS_PAGE_SIZE, + offset, + }, }, accessToken, ), @@ -154,7 +165,7 @@ export const fetchLocationDirectoryFeeds = cache( country?: string, subdivision?: string, municipality?: string, - ): Promise => + ): Promise => await nullWhenMissing( async () => await cachedDirectoryFeeds( diff --git a/src/app/services/feeds/index.ts b/src/app/services/feeds/index.ts index ab8ff846..edd343d5 100644 --- a/src/app/services/feeds/index.ts +++ b/src/app/services/feeds/index.ts @@ -348,14 +348,18 @@ export const getMetadata = async (): Promise< }); }; +export type SearchFeedsResponse = + paths['/v1/search']['get']['responses'][200]['content']['application/json']; + +/** + * Also lists the feeds of a location directory node, with its location + * parameters and `sort: 'location'`. + */ export const searchFeeds = async ( params: AllFeedsParams, accessToken: string, userContextJwt?: string, -): Promise< - | paths['/v1/search']['get']['responses'][200]['content']['application/json'] - | undefined -> => { +): Promise => { const authMiddleware = generateAuthMiddlewareWithToken( accessToken, userContextJwt, @@ -370,16 +374,9 @@ export type LocationDirectoryParams = NonNullable< paths['/v1/locations/directory']['get']['parameters']['query'] >; -export type LocationDirectoryFeedsParams = NonNullable< - paths['/v1/locations/directory/feeds']['get']['parameters']['query'] ->; - export type LocationDirectoryResponse = paths['/v1/locations/directory']['get']['responses'][200]['content']['application/json']; -export type LocationDirectoryFeedsResponse = - paths['/v1/locations/directory/feeds']['get']['responses'][200]['content']['application/json']; - /** * One level of the feed location directory: the node's breadcrumb, feed * counts and children. Throws an `ApiError` with status 400 (invalid @@ -402,27 +399,6 @@ export const getLocationDirectory = async ( }); }; -/** - * A page of the feeds located within a location directory node, already - * sorted by relevance to that node. - */ -export const getLocationDirectoryFeeds = async ( - params: LocationDirectoryFeedsParams, - accessToken: string, - userContextJwt?: string, -): Promise => { - const authMiddleware = generateAuthMiddlewareWithToken( - accessToken, - userContextJwt, - ); - return await withAuthMiddleware(authMiddleware, async () => { - const response = await client.GET('/v1/locations/directory/feeds', { - params: { query: params }, - }); - return response.data; - }); -}; - export const getLicense = async ( id: string, accessToken: string, diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index bee0a805..113ed5bd 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -331,6 +331,14 @@ export interface paths { * Query: New York Transit *
    * Search Executed: 'new' & york & 'transit' + *

    + * Location filters: + *
    + * - `continent`, `country`, `subdivision` and `municipality` restrict the results to feeds with a declared + * location within that node of `/v1/locations/directory`, using the same slugs, parent requirements and + * validation. Unknown slugs return no feed. + * - To list the same feeds as a directory node's counts, also pass `status=active,inactive,development,future`. + * - `sort=location` orders the results by relevance to the requested location instead of by creation date. *
    */ get: operations['searchFeeds']; @@ -366,7 +374,7 @@ export interface paths { path?: never; cookie?: never; }; - /** @description Browse the feed location directory one level at a time: continent > country > subdivision > municipality. The level is selected by the most specific parameter provided; with no parameters the response lists continents.
    Feed counts are based on the feeds' declared locations, only include feeds with a status of `active`, `inactive`, `development` or `future`, and roll up to every ancestor level (a feed located in Montréal counts toward Québec, Canada and North America). A feed is counted at most once per node, even when it declares several locations within that node.
    Each parameter requires its parent: `country` requires `continent`, `subdivision` requires `country`, and `municipality` requires `subdivision`. */ + /** @description Browse the feed location directory one level at a time: continent > country > subdivision > municipality. The level is selected by the most specific parameter provided; with no parameters the response lists continents.
    Feed counts are based on the feeds' declared locations, only include feeds with a status of `active`, `inactive`, `development` or `future`, and roll up to every ancestor level (a feed located in Montréal counts toward Québec, Canada and North America). A feed is counted at most once per node, even when it declares several locations within that node.
    Each parameter requires its parent: `country` requires `continent`, `subdivision` requires `country`, and `municipality` requires `subdivision`.
    To list the feeds of a node, call `/v1/search` with the same parameters, `status=active,inactive,development,future` and `sort=location`. */ get: operations['getLocationDirectory']; put?: never; post?: never; @@ -376,23 +384,6 @@ export interface paths { patch?: never; trace?: never; }; - '/v1/locations/directory/feeds': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** @description List the feeds located within a location directory node, using the same location parameters, status rules and validation as `/v1/locations/directory`.
    Feeds are sorted by relevance to the requested node: feeds whose most specific matching declared location is closest to the requested level come first (in the Québec node, a feed located in "Canada, Québec" ranks above one located in "Canada, Québec, Montréal"). Ties are broken by provider, feed name and feed id. */ - get: operations['getLocationDirectoryFeeds']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; '/v1/licenses': { parameters: { query?: never; @@ -1399,11 +1390,6 @@ export interface components { /** @description The nodes one level below the requested node that contain at least one feed, sorted by name. Empty at the `municipality` level. */ children?: components['schemas']['LocationDirectoryNode'][]; }; - LocationDirectoryFeedsResponse: { - /** @description The total number of feeds within the node regardless of limit and offset. */ - total?: number; - results?: components['schemas']['SearchFeedItemResult'][]; - }; LocationSearchResponse: { /** @description The total number of matching locations regardless of limit and offset. */ total?: number; @@ -1927,8 +1913,6 @@ export interface components { /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ location_directory_municipality: string; /** @description The number of items to be returned. */ - limit_query_param_location_directory_feeds_endpoint: number; - /** @description The number of items to be returned. */ limit_query_param_locations_endpoint: number; /** @description The number of items to be returned. */ limit_query_param_feeds_endpoint: number; @@ -1948,6 +1932,8 @@ export interface components { offset: number; /** @description General search query to match against transit provider, location, and feed name. */ search_text_query_param: string; + /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent`. Feeds whose most specific matching declared location is closest to the requested level come first (when filtering on Québec, a feed located in "Canada, Québec" ranks above one located in "Canada, Québec, Montréal"); ties are broken by provider, feed name and feed id. */ + search_sort: 'created_at' | 'location'; /** @description Comma separated list of GBFS versions to filter by. */ version_query_param: string; /** @description Comma separated list of data types to filter by. Valid values are gtfs, gtfs_rt and gbfs. */ @@ -2598,6 +2584,16 @@ export interface operations { license_is_spdx?: components['parameters']['license_is_spdx']; /** @description Comma separated list of tags to filter feeds by their license tags. */ license_tags?: components['parameters']['license_tags']; + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ + continent?: components['parameters']['location_directory_continent']; + /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ + country?: components['parameters']['location_directory_country']; + /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ + subdivision?: components['parameters']['location_directory_subdivision']; + /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ + municipality?: components['parameters']['location_directory_municipality']; + /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent`. Feeds whose most specific matching declared location is closest to the requested level come first (when filtering on Québec, a feed located in "Canada, Québec" ranks above one located in "Canada, Québec, Montréal"); ties are broken by provider, feed name and feed id. */ + sort?: components['parameters']['search_sort']; }; header?: never; path?: never; @@ -2618,6 +2614,13 @@ export interface operations { }; }; }; + /** @description A location parameter was provided without its parent, the country does not belong to the continent, or `sort=location` was requested without a location. */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; /** @description Filtering by Seal of Reliability status is not available to this caller. */ 403: { headers: { @@ -2708,46 +2711,6 @@ export interface operations { }; }; }; - getLocationDirectoryFeeds: { - parameters: { - query?: { - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ - continent?: components['parameters']['location_directory_continent']; - /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ - country?: components['parameters']['location_directory_country']; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ - subdivision?: components['parameters']['location_directory_subdivision']; - /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ - municipality?: components['parameters']['location_directory_municipality']; - /** @description The number of items to be returned. */ - limit?: components['parameters']['limit_query_param_location_directory_feeds_endpoint']; - /** @description Offset of the first item to return. */ - offset?: components['parameters']['offset']; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description The page of feeds located within the requested node. */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['LocationDirectoryFeedsResponse']; - }; - }; - /** @description A parameter was provided without its parent, or the country does not belong to the continent. */ - 400: { - headers: { - [name: string]: unknown; - }; - content?: never; - }; - }; - }; getLicenses: { parameters: { query?: { diff --git a/src/mocks/handlers.ts b/src/mocks/handlers.ts index 8adffae9..da4a4ccf 100644 --- a/src/mocks/handlers.ts +++ b/src/mocks/handlers.ts @@ -14,26 +14,27 @@ import { } from './locationDirectory'; export const handlers = [ - // Location directory: feeds of a node (paginated, relevance-sorted) - http.get(`*/v1/locations/directory/feeds`, ({ request }) => { - const params = new URL(request.url).searchParams; - const limit = Number(params.get('limit') ?? '20'); - const offset = Number(params.get('offset') ?? '0'); - const { status, body } = getMockDirectoryFeeds( - readDirectoryQuery(params), - Number.isFinite(limit) ? limit : 20, - Number.isFinite(offset) ? offset : 0, - ); - return HttpResponse.json(body, { status }); - }), // Location directory: breadcrumb, counts and children of a node http.get(`*/v1/locations/directory`, ({ request }) => { const params = new URL(request.url).searchParams; const { status, body } = getMockDirectory(readDirectoryQuery(params)); return HttpResponse.json(body, { status }); }), - // Mock search endpoint: return a list including test-516 and mdb-2947 - http.get(`*/v1/search`, () => { + // Mock search endpoint. With location parameters (location directory + // pages): the feeds of that node, paginated and relevance-sorted. + // Otherwise: a list including test-516 and mdb-2947. + http.get(`*/v1/search`, ({ request }) => { + const params = new URL(request.url).searchParams; + if (params.has('continent') || params.get('sort') === 'location') { + const limit = Number(params.get('limit') ?? '20'); + const offset = Number(params.get('offset') ?? '0'); + const { status, body } = getMockDirectoryFeeds( + readDirectoryQuery(params), + Number.isFinite(limit) ? limit : 20, + Number.isFinite(offset) ? offset : 0, + ); + return HttpResponse.json(body, { status }); + } return HttpResponse.json({ total: 2, results: [ diff --git a/src/mocks/locationDirectory.ts b/src/mocks/locationDirectory.ts index 4a662629..56d6601f 100644 --- a/src/mocks/locationDirectory.ts +++ b/src/mocks/locationDirectory.ts @@ -1,7 +1,7 @@ /** * Mock data and logic for the location directory endpoints: * GET /v1/locations/directory - * GET /v1/locations/directory/feeds + * GET /v1/search with location parameters (the feeds of a node) * * The directory tree, the rolled-up counts, the breadcrumb and the children * are all derived from MOCK_FEEDS' declared locations, so the mock behaves @@ -16,7 +16,10 @@ type DirectoryNode = components['schemas']['LocationDirectoryNode']; type DirectoryLevel = components['schemas']['LocationDirectoryLevel']; type FeedCounts = components['schemas']['LocationDirectoryFeedCounts']; type DirectoryResponse = components['schemas']['LocationDirectoryResponse']; -type FeedsResponse = components['schemas']['LocationDirectoryFeedsResponse']; +interface FeedsResponse { + total: number; + results: Feed[]; +} const CONTINENTS: Record = { africa: { code: 'AF', name: 'Africa' }, From d707a35a94aafa31d257cc1225e4f7a88b61fbea Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Wed, 4 Nov 2026 12:44:43 -0500 Subject: [PATCH 07/16] feat: browse locations from the geopolygon hierarchy - Pages use /v1/locations (continents, countries of a continent, a location by path, its children by parent_location_id) and /v1/search with continent or location_id, replacing /v1/locations/directory. - /locations/{continent}/{path...} works at any depth; segments are the API slugs, and the breadcrumb comes from path_names and path_slugs. - Children are fetched page by page on the server (100 per call). - Mocks cover variable depth and suffixed slugs; level-specific wording is now level-agnostic. Co-Authored-By: Claude Opus 5.5 --- messages/en.json | 11 +- messages/fr.json | 11 +- .../locations/[[...location]]/page.tsx | 191 ++-- .../locations/components/FeedCountSummary.tsx | 4 +- .../components/LocationChildrenGrid.tsx | 78 +- .../components/LocationChildrenList.tsx | 5 +- .../components/LocationFeedsList.tsx | 10 +- .../lib/location-directory-data.spec.ts | 305 +++++-- .../locations/lib/location-directory-data.ts | 242 +++-- .../locations/lib/location-directory.spec.ts | 311 +++++-- .../locations/lib/location-directory.ts | 249 ++++-- src/app/services/feeds/index.ts | 26 +- src/app/services/feeds/types.ts | 207 ++--- src/mocks/handlers.ts | 26 +- src/mocks/locationDirectory.spec.ts | 160 +++- src/mocks/locationDirectory.ts | 842 +++++++++--------- 16 files changed, 1608 insertions(+), 1070 deletions(-) diff --git a/messages/en.json b/messages/en.json index 357520b9..832e30ef 100644 --- a/messages/en.json +++ b/messages/en.json @@ -1269,7 +1269,7 @@ "locations": { "root": "Locations", "title": "Feeds by location", - "rootIntro": "Browse open GTFS Schedule, GTFS Realtime and GBFS feeds by continent, country, region and municipality.", + "rootIntro": "Browse open GTFS Schedule, GTFS Realtime and GBFS feeds by location, from continents down to cities.", "nodeIntro": "{total, plural, =0 {No feeds are} one {# feed is} other {# feeds are}} located in {place}.", "feedCountsAria": "Feed counts by data type", "shortLabels": { @@ -1278,10 +1278,9 @@ "gbfs": "GBFS" }, "childrenHeading": { - "continent": "Continents", - "country": "Countries", - "subdivision": "Regions", - "municipality": "Municipalities" + "continents": "Continents", + "countries": "Countries", + "places": "Places" }, "childFeedTotal": "{count, plural, one {# feed} other {# feeds}}", "childrenSearchPlaceholder": "Search locations", @@ -1296,7 +1295,7 @@ "paginationAria": "Feed list pages", "meta": { "rootTitle": "Transit Feeds by Location | Mobility Database", - "rootDescription": "Browse open GTFS Schedule, GTFS Realtime and GBFS transit and mobility feeds by continent, country, region and municipality.", + "rootDescription": "Browse open GTFS Schedule, GTFS Realtime and GBFS transit and mobility feeds by location, from continents down to cities.", "nodeTitle": "{place} Transit Feeds | Mobility Database", "nodeTitlePaged": "{place} Transit Feeds, Page {page} | Mobility Database", "nodeDescription": "Browse {total} open transit and mobility feeds located in {place}: {gtfs} GTFS Schedule, {gtfs_rt} GTFS Realtime and {gbfs} GBFS." diff --git a/messages/fr.json b/messages/fr.json index b19d46ad..28a7ebe6 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -1269,7 +1269,7 @@ "locations": { "root": "Lieux", "title": "Flux par lieu", - "rootIntro": "Parcourez les flux ouverts GTFS Schedule, GTFS Realtime et GBFS par continent, pays, région et municipalité.", + "rootIntro": "Parcourez les flux ouverts GTFS Schedule, GTFS Realtime et GBFS par lieu, des continents jusqu’aux villes.", "nodeIntro": "{total, plural, =0 {Aucun flux n’est situé} one {# flux est situé} other {# flux sont situés}} dans : {place}.", "feedCountsAria": "Nombre de flux par type de données", "shortLabels": { @@ -1278,10 +1278,9 @@ "gbfs": "GBFS" }, "childrenHeading": { - "continent": "Continents", - "country": "Pays", - "subdivision": "Régions", - "municipality": "Municipalités" + "continents": "Continents", + "countries": "Pays", + "places": "Lieux" }, "childFeedTotal": "{count, plural, one {# flux} other {# flux}}", "childrenSearchPlaceholder": "Rechercher un lieu", @@ -1296,7 +1295,7 @@ "paginationAria": "Pages de la liste des flux", "meta": { "rootTitle": "Flux de transport par lieu | Mobility Database", - "rootDescription": "Parcourez les flux ouverts de transport et de mobilité GTFS Schedule, GTFS Realtime et GBFS par continent, pays, région et municipalité.", + "rootDescription": "Parcourez les flux ouverts de transport et de mobilité GTFS Schedule, GTFS Realtime et GBFS par lieu, des continents jusqu’aux villes.", "nodeTitle": "Flux de transport : {place} | Mobility Database", "nodeTitlePaged": "Flux de transport : {place}, page {page} | Mobility Database", "nodeDescription": "Parcourez {total} flux ouverts de transport et de mobilité situés dans : {place}. {gtfs} GTFS Schedule, {gtfs_rt} GTFS Realtime et {gbfs} GBFS." diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx index 97d6c089..4e3b356a 100644 --- a/src/app/[locale]/locations/[[...location]]/page.tsx +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -11,20 +11,21 @@ import FeedCountSummary from '../components/FeedCountSummary'; import LocationChildrenGrid from '../components/LocationChildrenGrid'; import LocationFeedsList from '../components/LocationFeedsList'; import { + buildBreadcrumbSteps, buildLocationHref, buildPlaceName, FEEDS_SECTION_ID, - getBreadcrumbSlugs, - getChildLevel, + getLocationName, + getLocationSegments, getPageCount, getTotalFeedCount, - type LocationQuery, + type LocationPath, parseLocationSegments, parsePageParam, } from '../lib/location-directory'; import { - fetchLocationDirectory, - fetchLocationDirectoryFeeds, + fetchLocationPage, + type LocationPageData, } from '../lib/location-directory-data'; const SITE_URL = 'https://mobilitydatabase.org'; @@ -35,87 +36,79 @@ interface PageProps { } interface ParsedRequest { - query: LocationQuery; + locale: string; + location: LocationPath; page: number; } +/** The request, or null when the URL or the page number is malformed. */ async function parseRequest({ params, searchParams, -}: PageProps): Promise<{ locale: string } & (ParsedRequest | { query: null })> { - const [{ locale, location }, { page: rawPage }] = await Promise.all([ - params, - searchParams, - ]); - const query = parseLocationSegments(location); - const page = parsePageParam(rawPage); - if (query === null || page === null) return { locale, query: null }; - return { locale, query, page }; -} - -function fetchDirectory( - query: LocationQuery, -): ReturnType { - return fetchLocationDirectory( - query.continent, - query.country, - query.subdivision, - query.municipality, +}: PageProps): Promise { + const [{ locale, location: segments }, { page: rawPage }] = await Promise.all( + [params, searchParams], ); + const location = parseLocationSegments(segments); + const page = parsePageParam(rawPage); + if (location === null || page === null) return null; + return { locale, location, page }; } -function fetchFeedsPage( - query: LocationQuery, - page: number, -): ReturnType { - return fetchLocationDirectoryFeeds( +/** + * The page data, or null when the location does not exist or the page is + * past the last one. Deduped by React cache() between generateMetadata and + * the page. + */ +async function fetchPageData({ + location, + page, +}: ParsedRequest): Promise { + const data = await fetchLocationPage( page, - query.continent, - query.country, - query.subdivision, - query.municipality, + location.continent, + location.path.join('/'), ); + if (data === null || page > getPageCount(data.feeds.total ?? 0)) { + return null; + } + return data; } export async function generateMetadata(props: PageProps): Promise { const request = await parseRequest(props); - if (request.query === null) return {}; - const { query, page } = request; - // Same calls as the page: deduped by React cache() within the request. - const [directory, feeds, t] = await Promise.all([ - fetchDirectory(query), - fetchFeedsPage(query, page), + if (request === null) return {}; + const [data, t] = await Promise.all([ + fetchPageData(request), getTranslations({ locale: request.locale, namespace: 'locations.meta' }), ]); - if ( - directory === null || - feeds === null || - page > getPageCount(feeds.total ?? 0) - ) { - return {}; - } - - const place = buildPlaceName(directory.breadcrumb); - const counts = directory.feed_counts; - const isRoot = place === ''; - const title = isRoot - ? t('rootTitle') - : page > 1 - ? t('nodeTitlePaged', { place, page }) - : t('nodeTitle', { place }); - const description = isRoot - ? t('rootDescription') - : t('nodeDescription', { - place, - total: getTotalFeedCount(counts), - gtfs: counts?.gtfs ?? 0, - gtfs_rt: counts?.gtfs_rt ?? 0, - gbfs: counts?.gbfs ?? 0, - }); - const url = `${SITE_URL}${buildLocationHref( - getBreadcrumbSlugs(directory.breadcrumb), - page, - )}`; + if (data === null) return {}; + + const { location } = data; + const { page } = request; + const place = buildPlaceName(location); + const counts = location?.feed_counts; + const title = + location === null + ? t('rootTitle') + : page > 1 + ? t('nodeTitlePaged', { place, page }) + : t('nodeTitle', { place }); + const description = + location === null + ? t('rootDescription') + : t('nodeDescription', { + place, + total: getTotalFeedCount(counts), + gtfs: counts?.gtfs ?? 0, + gtfs_rt: counts?.gtfs_rt ?? 0, + gbfs: counts?.gbfs ?? 0, + }); + const segments = + location === null || request.location.continent === undefined + ? [] + : getLocationSegments(request.location.continent, location); + const url = `${SITE_URL}${buildLocationHref(segments, page)}`; return { title, @@ -135,45 +128,46 @@ export default async function LocationsPage( props: PageProps, ): Promise { const request = await parseRequest(props); - if (request.query === null) notFound(); - const { locale, query, page } = request; + if (request === null) notFound(); + const { locale, page } = request; setRequestLocale(locale); - // Directory node and feed page are independent: fetch them in parallel. - const [directory, feeds, t, tCommon] = await Promise.all([ - fetchDirectory(query), - fetchFeedsPage(query, page), + const [data, t, tCommon] = await Promise.all([ + fetchPageData(request), getTranslations('locations'), getTranslations('common'), ]); - if (directory === null || feeds === null) notFound(); + if (data === null) notFound(); + const { location, children, feeds } = data; + const continent = request.location.continent ?? ''; + const isRoot = location === null; const total = feeds.total ?? 0; const pageCount = getPageCount(total); - if (page > pageCount) notFound(); - - const breadcrumb = directory.breadcrumb ?? []; - const slugs = getBreadcrumbSlugs(breadcrumb); - const place = buildPlaceName(breadcrumb); - const isRoot = breadcrumb.length === 0; - const children = directory.children ?? []; - const childLevel = getChildLevel(directory.level); + const segments = isRoot ? [] : getLocationSegments(continent, location); + const place = buildPlaceName(location); + const steps = buildBreadcrumbSteps(continent, location); const crumbs: Crumb[] = [ { label: tCommon('feeds'), href: '/feeds' }, { label: t('root'), href: isRoot ? undefined : buildLocationHref([]) }, - ...breadcrumb.map((node, index) => ({ - label: node.name ?? node.slug ?? '', + ...steps.map((step, index) => ({ + label: step.label, href: - index === breadcrumb.length - 1 + index === steps.length - 1 ? undefined - : buildLocationHref(slugs.slice(0, index + 1)), + : buildLocationHref(step.segments), })), ]; // Without history to pop, back goes one level up the directory. const backFallbackHref = isRoot ? '/feeds' - : buildLocationHref(slugs.slice(0, -1)); + : buildLocationHref(segments.slice(0, -1)); + const childrenHeading = isRoot + ? t('childrenHeading.continents') + : location.location_type === 'continent' + ? t('childrenHeading.countries') + : t('childrenHeading.places'); return ( - {isRoot ? t('title') : breadcrumb[breadcrumb.length - 1]?.name} + {isRoot ? t('title') : getLocationName(location)} - + {/* No catalog-wide counts by data type at the root. */} + {isRoot ? null : ( + + )} - {childLevel !== null && children.length > 0 ? ( + {children.length > 0 ? ( - {t(`childrenHeading.${childLevel}`)}{' '} + {childrenHeading}{' '} ({children.length}) @@ -248,7 +245,7 @@ export default async function LocationsPage( total={total} page={page} pageCount={pageCount} - slugs={slugs} + segments={segments} /> diff --git a/src/app/[locale]/locations/components/FeedCountSummary.tsx b/src/app/[locale]/locations/components/FeedCountSummary.tsx index 5ce5463b..55b90eab 100644 --- a/src/app/[locale]/locations/components/FeedCountSummary.tsx +++ b/src/app/[locale]/locations/components/FeedCountSummary.tsx @@ -5,11 +5,11 @@ import { formatCount, getFeedCountEntries, type FeedCountDataType, - type LocationDirectoryFeedCounts, + type LocationFeedCounts, } from '../lib/location-directory'; interface Props { - counts: LocationDirectoryFeedCounts | undefined; + counts: LocationFeedCounts | undefined; locale: string; } diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx index 493ed546..13f110f2 100644 --- a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -8,58 +8,72 @@ import { buildLocationHref, formatCount, getFeedCountEntries, + getLocationName, + getLocationSegments, getTotalFeedCount, sortByFeedCount, - type LocationDirectoryNode, + type LocationResult, } from '../lib/location-directory'; interface Props { - nodes: LocationDirectoryNode[]; - /** Slugs of the current node; each child links one level deeper. */ - parentSlugs: string[]; + locations: LocationResult[]; + /** + * Continent slug of the current page; empty at the root, where the + * children are the continents themselves. + */ + continent: string; locale: string; } -function getFlag(node: LocationDirectoryNode): string | undefined { - if (node.level !== 'country' || node.code == undefined) return undefined; - const flag = getEmojiFlag(node.code.toUpperCase() as TCountryCode); +function getFlag(location: LocationResult): string | undefined { + if ( + location.location_type !== 'country' || + location.country_code == undefined + ) + return undefined; + const flag = getEmojiFlag( + location.country_code.toUpperCase() as TCountryCode, + ); return flag !== '' ? flag : undefined; } /** - * Child nodes, most feeds first. Everything that needs the server (flags, - * translations, number formatting) is resolved here so the client list only - * filters plain data. + * Child locations, most feeds first. Everything that needs the server + * (flags, translations, number formatting, links) is resolved here so the + * client list only filters plain data. */ export default async function LocationChildrenGrid({ - nodes, - parentSlugs, + locations, + continent, locale, }: Props): Promise { const t = await getTranslations('locations'); const items: LocationChildItem[] = sortByFeedCount( - nodes.map((node) => ({ - node, - name: node.name ?? node.slug ?? '', - counts: node.feed_counts, + locations.map((location) => ({ + location, + name: getLocationName(location), + counts: location.feed_counts, })), - ).map(({ node, name, counts }) => ({ - slug: node.slug ?? '', - name, - flag: getFlag(node), - href: buildLocationHref([...parentSlugs, node.slug ?? '']), - totalLabel: t.rich('childFeedTotal', { - count: getTotalFeedCount(counts), - b: (chunks) => {chunks}, - }), - counts: getFeedCountEntries(counts).map(({ dataType, count }) => ({ - dataType, - count, - formattedCount: formatCount(count, locale), - typeLabel: t(`shortLabels.${dataType}`), - })), - })); + ).map(({ location, name, counts }) => { + const href = buildLocationHref(getLocationSegments(continent, location)); + return { + key: href, + name, + flag: getFlag(location), + href, + totalLabel: t.rich('childFeedTotal', { + count: getTotalFeedCount(counts), + b: (chunks) => {chunks}, + }), + counts: getFeedCountEntries(counts).map(({ dataType, count }) => ({ + dataType, + count, + formattedCount: formatCount(count, locale), + typeLabel: t(`shortLabels.${dataType}`), + })), + }; + }); return ; } diff --git a/src/app/[locale]/locations/components/LocationChildrenList.tsx b/src/app/[locale]/locations/components/LocationChildrenList.tsx index ee2f03f5..51b3fadd 100644 --- a/src/app/[locale]/locations/components/LocationChildrenList.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenList.tsx @@ -28,7 +28,8 @@ export interface LocationChildCount { } export interface LocationChildItem { - slug: string; + /** Unique among siblings (the href). */ + key: string; name: string; /** Emoji flag, countries only. */ flag?: string; @@ -129,7 +130,7 @@ export default function LocationChildrenList({ items }: Props): ReactElement { }} > {visibleItems.map((item) => ( -
  • +
  • ({})); @@ -15,24 +12,25 @@ jest.mock('react', () => ({ cache: (fn: unknown) => fn, })); -// Behaves like unstable_cache: a resolved value is stored per arguments, a -// thrown error is not. +// Behaves like unstable_cache: a resolved value is stored per key parts and +// arguments, a thrown error is not. Tests reset the store between them. +const mockCacheStore = new Map(); jest.mock('next/cache', () => ({ unstable_cache: ( fn: (...args: A) => Promise, + keyParts: string[], ): ((...args: A) => Promise) => { - const store = new Map(); return async (...args: A): Promise => { - const key = JSON.stringify(args); - if (store.has(key)) return store.get(key) as R; + const key = JSON.stringify([keyParts, args]); + if (mockCacheStore.has(key)) return mockCacheStore.get(key) as R; const value = await fn(...args); - store.set(key, value); + mockCacheStore.set(key, value); return value; }; }, })); -const mockGetLocationDirectory = jest.fn(); +const mockGetLocations = jest.fn(); const mockSearchFeeds = jest.fn(); jest.mock('../../../services/feeds', () => ({ @@ -43,8 +41,7 @@ jest.mock('../../../services/feeds', () => ({ this.status = status; } }, - getLocationDirectory: (...args: unknown[]) => - mockGetLocationDirectory(...args), + getLocations: (...args: unknown[]) => mockGetLocations(...args), searchFeeds: (...args: unknown[]) => mockSearchFeeds(...args), })); @@ -52,86 +49,260 @@ jest.mock('../../../utils/auth-server', () => ({ getGuestGcipIdToken: async () => 'guest-token', })); -const directory = { - level: 'continent', - breadcrumb: [], - feed_counts: { gtfs: 1, gtfs_rt: 0, gbfs: 0, total: 1 }, - children: [], +const STATUSES = ['active', 'inactive', 'development', 'future']; + +const northAmerica = { + location_id: null, + location_type: 'continent', + name: 'North America', + slug: 'north-america', + continent_slug: 'north-america', + path_slugs: [], + feed_counts: { total: 30 }, +}; +const antarctica = { + ...northAmerica, + name: 'Antarctica', + slug: 'antarctica', + continent_slug: 'antarctica', + feed_counts: { total: 0 }, +}; +const montreal = { + location_id: 175905, + location_type: 'municipality', + name: 'Montréal', + slug: 'montreal', + continent_slug: 'north-america', + path_slugs: ['canada', 'quebec', 'montreal'], + feed_counts: { total: 22 }, }; +const feeds = { total: 22, results: [] }; + +/** getLocations answers by query shape. */ +function answerLocations( + byQuery: (query: Record) => unknown, +): void { + mockGetLocations.mockImplementation(async (query: Record) => + byQuery(query), + ); +} + +function locationQueries(): Array> { + return mockGetLocations.mock.calls.map( + ([query]) => query as Record, + ); +} + +function searchQueries(): Array> { + return mockSearchFeeds.mock.calls.map( + ([params]) => (params as { query: Record }).query, + ); +} -describe('location directory data', () => { +describe('fetchLocationPage', () => { beforeEach(() => { - mockGetLocationDirectory.mockReset(); + mockCacheStore.clear(); + mockGetLocations.mockReset(); mockSearchFeeds.mockReset(); + mockSearchFeeds.mockResolvedValue(feeds); }); - it('resolves a 404 to null without caching it', async () => { - mockGetLocationDirectory - .mockRejectedValueOnce(new ApiError('Not Found', 404)) - .mockResolvedValueOnce(directory); + it('lists the continents with feeds and the newest feeds at the root', async () => { + answerLocations(() => ({ total: 2, results: [northAmerica, antarctica] })); - await expect(fetchLocationDirectory('europe')).resolves.toBeNull(); - await expect(fetchLocationDirectory('europe')).resolves.toEqual(directory); - expect(mockGetLocationDirectory).toHaveBeenCalledTimes(2); - }); + const data = await fetchLocationPage(2); - it('resolves a 400 on the feeds page to null without caching it', async () => { - const feeds = { total: 0, results: [] }; - mockSearchFeeds - .mockRejectedValueOnce(new ApiError('Bad Request', 400)) - .mockResolvedValueOnce(feeds); + expect(data).toEqual({ location: null, children: [northAmerica], feeds }); + expect(locationQueries()).toEqual([ + { + location_type: 'continent', + include_feed_counts: true, + limit: 100, + offset: 0, + }, + ]); + expect(mockGetLocations.mock.calls[0][1]).toBe('guest-token'); + expect(searchQueries()).toEqual([ + { status: STATUSES, limit: 20, offset: 20 }, + ]); + }); - await expect(fetchLocationDirectoryFeeds(1, 'asia')).resolves.toBeNull(); - await expect(fetchLocationDirectoryFeeds(1, 'asia')).resolves.toEqual( - feeds, + it('lists the countries and feeds of a continent', async () => { + const canada = { ...montreal, location_type: 'country', slug: 'canada' }; + answerLocations((query) => + query.location_type === 'continent' + ? { total: 1, results: [northAmerica] } + : { total: 1, results: [canada] }, ); + + const data = await fetchLocationPage(1, 'north-america', ''); + + expect(data).toEqual({ location: northAmerica, children: [canada], feeds }); + expect(locationQueries()[1]).toEqual({ + continent: 'north-america', + location_type: 'country', + has_feeds: true, + include_feed_counts: true, + sort: 'feed_count', + limit: 100, + offset: 0, + }); + expect(searchQueries()).toEqual([ + { + continent: 'north-america', + sort: 'location', + status: STATUSES, + limit: 20, + offset: 0, + }, + ]); }); - it('lists the feeds of a node with search, most relevant first', async () => { - mockSearchFeeds.mockResolvedValue({ total: 0, results: [] }); + it('is null for an unknown continent, without listing anything', async () => { + answerLocations(() => ({ total: 1, results: [northAmerica] })); + + await expect(fetchLocationPage(1, 'atlantis', '')).resolves.toBeNull(); + expect(mockGetLocations).toHaveBeenCalledTimes(1); + expect(mockSearchFeeds).not.toHaveBeenCalled(); + }); + + it('resolves a deeper location by path, then its children and feeds', async () => { + const child = { ...montreal, location_id: 1, slug: 'ville-marie' }; + answerLocations((query) => + query.path !== undefined + ? { total: 1, results: [montreal] } + : { total: 1, results: [child] }, + ); + + const data = await fetchLocationPage( + 3, + 'north-america', + 'canada/quebec/montreal', + ); - await fetchLocationDirectoryFeeds(2, 'europe', 'portugal'); - expect(mockSearchFeeds).toHaveBeenCalledWith( + expect(data).toEqual({ location: montreal, children: [child], feeds }); + expect(locationQueries()).toEqual([ { - query: { - continent: 'europe', - country: 'portugal', - status: ['active', 'inactive', 'development', 'future'], - sort: 'location', - limit: 20, - offset: 20, - }, + continent: 'north-america', + path: 'canada/quebec/montreal', + include_feed_counts: true, + limit: 1, }, - 'guest-token', + { + parent_location_id: 175905, + has_feeds: true, + include_feed_counts: true, + sort: 'feed_count', + limit: 100, + offset: 0, + }, + ]); + expect(searchQueries()).toEqual([ + { + location_id: 175905, + sort: 'location', + status: STATUSES, + limit: 20, + offset: 40, + }, + ]); + }); + + it('pages through every child location', async () => { + const children = Array.from({ length: 230 }, (_, index) => ({ + ...montreal, + location_id: index + 1, + slug: `child-${index + 1}`, + })); + answerLocations((query) => { + if (query.path !== undefined) return { total: 1, results: [montreal] }; + const offset = query.offset as number; + const limit = query.limit as number; + return { total: 230, results: children.slice(offset, offset + limit) }; + }); + + const data = await fetchLocationPage( + 1, + 'north-america', + 'canada/quebec/montreal', + ); + + expect(data?.children).toEqual(children); + expect( + locationQueries() + .slice(1) + .map(({ offset, limit }) => [offset, limit]), + ).toEqual([ + [0, 100], + [100, 100], + [200, 100], + ]); + }); + + it('is null when no location has the path, and never caches the miss', async () => { + answerLocations(() => ({ total: 0, results: [] })); + await expect( + fetchLocationPage(1, 'north-america', 'canada/quebec/montreal'), + ).resolves.toBeNull(); + expect(mockSearchFeeds).not.toHaveBeenCalled(); + + answerLocations((query) => + query.path !== undefined + ? { total: 1, results: [montreal] } + : { total: 0, results: [] }, ); + await expect( + fetchLocationPage(1, 'north-america', 'canada/quebec/montreal'), + ).resolves.toMatchObject({ location: montreal }); }); - it('lists the newest feeds at the root, which has no location', async () => { - mockSearchFeeds.mockResolvedValue({ total: 0, results: [] }); + it('is null when the result is not at the requested continent or path', async () => { + answerLocations(() => ({ total: 1, results: [montreal] })); - await fetchLocationDirectoryFeeds(1); - const [{ query }] = mockSearchFeeds.mock.calls[0] as [ - { query: Record }, - ]; - expect(query.sort).toBeUndefined(); - expect(query.continent).toBeUndefined(); + // The API accepts continent codes too; only slugs are valid URLs. + await expect( + fetchLocationPage(1, 'na', 'canada/quebec/montreal'), + ).resolves.toBeNull(); + await expect( + fetchLocationPage(1, 'north-america', 'canada/quebec'), + ).resolves.toBeNull(); + }); + + it('resolves a 400 or 404 to null without caching it', async () => { + mockGetLocations + .mockRejectedValueOnce(new ApiError('Bad Request', 400)) + .mockResolvedValue({ total: 1, results: [northAmerica] }); + + await expect(fetchLocationPage(1)).resolves.toBeNull(); + await expect(fetchLocationPage(1)).resolves.toMatchObject({ + children: [northAmerica], + }); + + mockSearchFeeds.mockReset(); + mockSearchFeeds + .mockRejectedValueOnce(new ApiError('Not Found', 404)) + .mockResolvedValueOnce(feeds); + await expect(fetchLocationPage(2)).resolves.toBeNull(); + await expect(fetchLocationPage(2)).resolves.toMatchObject({ feeds }); }); it('caches a found location', async () => { - mockGetLocationDirectory.mockResolvedValue(directory); + answerLocations((query) => + query.path !== undefined + ? { total: 1, results: [montreal] } + : { total: 0, results: [] }, + ); - await fetchLocationDirectory('oceania'); - await fetchLocationDirectory('oceania'); - expect(mockGetLocationDirectory).toHaveBeenCalledTimes(1); + await fetchLocationPage(1, 'north-america', 'canada/quebec/montreal'); + await fetchLocationPage(2, 'north-america', 'canada/quebec/montreal'); + // Location and children once; one feed page each. + expect(mockGetLocations).toHaveBeenCalledTimes(2); + expect(mockSearchFeeds).toHaveBeenCalledTimes(2); }); it('rethrows other API errors', async () => { - mockGetLocationDirectory.mockRejectedValueOnce( - new ApiError('Server Error', 500), - ); + mockGetLocations.mockRejectedValueOnce(new ApiError('Server Error', 500)); - await expect(fetchLocationDirectory('africa')).rejects.toThrow( - 'Server Error', - ); + await expect(fetchLocationPage(1)).rejects.toThrow('Server Error'); }); }); diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index 831792ef..4711ce50 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -11,32 +11,39 @@ import { unstable_cache } from 'next/cache'; import { getGuestGcipIdToken } from '../../../utils/auth-server'; import { ApiError, - getLocationDirectory, + getLocations, searchFeeds, - type LocationDirectoryResponse, + type LocationsParams, type SearchFeedsResponse, } from '../../../services/feeds'; import { + fetchAllPages, + getContinentSlug, getPageOffset, + getTotalFeedCount, + isLocationAtPath, LOCATION_FEEDS_PAGE_SIZE, - type LocationQuery, + type LocationResult, } from './location-directory'; /** 6 hours; also flushed on demand with the existing `guest-feeds` tag. */ export const LOCATION_DIRECTORY_REVALIDATE_SECONDS = 21600; const CACHE_TAGS = ['location-directory', 'guest-feeds']; +const CACHE_OPTIONS = { + tags: CACHE_TAGS, + revalidate: LOCATION_DIRECTORY_REVALIDATE_SECONDS, +}; -/** The statuses the directory counts, so a node lists as many feeds. */ +/** The statuses `feed_counts` counts, so a location lists as many feeds. */ const DIRECTORY_FEED_STATUSES: Array< 'active' | 'inactive' | 'development' | 'future' > = ['active', 'inactive', 'development', 'future']; /** - * 400 (invalid hierarchy) and 404 (nothing located there) both mean the URL - * does not exist. They are thrown as this error inside the cached functions, - * because unstable_cache never stores a thrown error: caching the miss would - * keep a location missing for hours after it starts to exist (e.g. a - * 404 served before the API route was deployed). + * A URL that does not exist: a 400/404 from the API, or no location at the + * requested path. Thrown inside the cached functions because unstable_cache + * never stores a thrown error: caching the miss would keep a location missing + * for hours after it starts to exist. */ class LocationNotFoundError extends Error {} @@ -46,7 +53,7 @@ async function requireData( try { const data = await request(); if (data == undefined) { - throw new Error('Empty response from the location directory API'); + throw new Error('Empty response from the locations API'); } return data; } catch (error) { @@ -72,61 +79,114 @@ async function nullWhenMissing( } } -function toQuery( - continent: string | undefined, - country: string | undefined, - subdivision: string | undefined, - municipality: string | undefined, -): LocationQuery { - const query: LocationQuery = {}; - if (continent != undefined) query.continent = continent; - if (country != undefined) query.country = country; - if (subdivision != undefined) query.subdivision = subdivision; - if (municipality != undefined) query.municipality = municipality; - return query; +/** Every page of `GET /v1/locations` for the query (100 per call). */ +async function getAllLocations( + query: LocationsParams, + accessToken: string, +): Promise { + return await fetchAllPages( + async (offset, limit) => + await requireData( + async () => + await getLocations({ ...query, limit, offset }, accessToken), + ), + ); } // unstable_cache keys on the key parts plus the call arguments, so the // arguments are kept primitive. -const cachedDirectory = unstable_cache( - async ( - continent?: string, - country?: string, - subdivision?: string, - municipality?: string, - ): Promise => { + +const cachedContinents = unstable_cache( + async (): Promise => { const accessToken = await getGuestGcipIdToken(); - return await requireData( + return await getAllLocations( + { location_type: 'continent', include_feed_counts: true }, + accessToken, + ); + }, + ['location-directory-continents'], + CACHE_OPTIONS, +); + +/** The location at `continent/path`; throws when there is none. */ +const cachedLocation = unstable_cache( + async (continent: string, path: string): Promise => { + const accessToken = await getGuestGcipIdToken(); + const response = await requireData( async () => - await getLocationDirectory( - toQuery(continent, country, subdivision, municipality), + await getLocations( + { continent, path, include_feed_counts: true, limit: 1 }, accessToken, ), ); + const location = response.results?.[0]; + if ( + location == undefined || + location.location_id == undefined || + !isLocationAtPath(location, continent, path.split('/')) + ) { + throw new LocationNotFoundError(`No location at ${continent}/${path}`); + } + return location; }, - ['location-directory'], - { tags: CACHE_TAGS, revalidate: LOCATION_DIRECTORY_REVALIDATE_SECONDS }, + ['location-directory-location'], + CACHE_OPTIONS, ); -const cachedDirectoryFeeds = unstable_cache( +const CHILDREN_QUERY = { + has_feeds: true, + include_feed_counts: true, + sort: 'feed_count', +} as const satisfies LocationsParams; + +const cachedCountries = unstable_cache( + async (continent: string): Promise => { + const accessToken = await getGuestGcipIdToken(); + return await getAllLocations( + { ...CHILDREN_QUERY, continent, location_type: 'country' }, + accessToken, + ); + }, + ['location-directory-countries'], + CACHE_OPTIONS, +); + +const cachedSubLocations = unstable_cache( + async (parentLocationId: number): Promise => { + const accessToken = await getGuestGcipIdToken(); + return await getAllLocations( + { ...CHILDREN_QUERY, parent_location_id: parentLocationId }, + accessToken, + ); + }, + ['location-directory-sub-locations'], + CACHE_OPTIONS, +); + +/** + * One page of feeds: newest first at the root (no location), otherwise most + * relevant to the continent or location first. + */ +const cachedFeeds = unstable_cache( async ( offset: number, - continent?: string, - country?: string, - subdivision?: string, - municipality?: string, + continent: string | null, + locationId: number | null, ): Promise => { const accessToken = await getGuestGcipIdToken(); + const location = + locationId !== null + ? { location_id: locationId, sort: 'location' as const } + : continent !== null + ? { continent, sort: 'location' as const } + : {}; return await requireData( async () => await searchFeeds( { query: { - ...toQuery(continent, country, subdivision, municipality), + ...location, status: DIRECTORY_FEED_STATUSES, - // Most relevant location first; the API rejects it without a - // location, so the root lists the newest feeds first. - sort: continent != undefined ? 'location' : undefined, limit: LOCATION_FEEDS_PAGE_SIZE, offset, }, @@ -136,44 +196,78 @@ const cachedDirectoryFeeds = unstable_cache( ); }, ['location-directory-feeds'], - { tags: CACHE_TAGS, revalidate: LOCATION_DIRECTORY_REVALIDATE_SECONDS }, + CACHE_OPTIONS, ); +export interface LocationPageData { + /** The current location; null at the root. */ + location: LocationResult | null; + /** Continents at the root, otherwise the locations with feeds one level down. */ + children: LocationResult[]; + /** The requested page of feeds located there. */ + feeds: SearchFeedsResponse; +} + +async function loadLocationPage( + page: number, + continent: string | undefined, + path: string, +): Promise { + const offset = getPageOffset(page); + + if (continent === undefined) { + const [continents, feeds] = await Promise.all([ + cachedContinents(), + cachedFeeds(offset, null, null), + ]); + // Children deeper down are fetched with `has_feeds`; continents are not, + // so that an empty continent still resolves. + const children = continents.filter( + (continent) => getTotalFeedCount(continent.feed_counts) > 0, + ); + return { location: null, children, feeds }; + } + + if (path === '') { + // Resolve the continent before listing its countries and feeds, so an + // unknown slug is a 404 and never adds entries to the data cache. + const continents = await cachedContinents(); + const location = continents.find( + (candidate) => getContinentSlug(candidate) === continent, + ); + if (location == undefined) { + throw new LocationNotFoundError(`Unknown continent ${continent}`); + } + const [children, feeds] = await Promise.all([ + cachedCountries(continent), + cachedFeeds(offset, continent, null), + ]); + return { location, children, feeds }; + } + + const location = await cachedLocation(continent, path); + const locationId = location.location_id ?? 0; + const [children, feeds] = await Promise.all([ + cachedSubLocations(locationId), + cachedFeeds(offset, null, locationId), + ]); + return { location, children, feeds }; +} + /** - * Directory node (breadcrumb, counts, children), or null when the location - * does not exist. React cache() dedupes the generateMetadata + page calls - * within one request; it compares arguments by identity, hence primitives. + * Everything a directory page shows, or null when the location does not + * exist. `path` is the location's path slugs joined with `/` (empty at the + * root and on a continent page). React cache() dedupes the generateMetadata + * and page calls within one request; it compares arguments by identity, + * hence primitives. */ -export const fetchLocationDirectory = cache( - async ( - continent?: string, - country?: string, - subdivision?: string, - municipality?: string, - ): Promise => - await nullWhenMissing( - async () => - await cachedDirectory(continent, country, subdivision, municipality), - ), -); - -/** One page (1-based) of the feeds located in a node, or null if missing. */ -export const fetchLocationDirectoryFeeds = cache( +export const fetchLocationPage = cache( async ( page: number, continent?: string, - country?: string, - subdivision?: string, - municipality?: string, - ): Promise => + path: string = '', + ): Promise => await nullWhenMissing( - async () => - await cachedDirectoryFeeds( - getPageOffset(page), - continent, - country, - subdivision, - municipality, - ), + async () => await loadLocationPage(page, continent, path), ), ); diff --git a/src/app/[locale]/locations/lib/location-directory.spec.ts b/src/app/[locale]/locations/lib/location-directory.spec.ts index ff0c6640..063996d6 100644 --- a/src/app/[locale]/locations/lib/location-directory.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory.spec.ts @@ -1,67 +1,113 @@ import { + buildBreadcrumbSteps, buildLocationHref, buildPlaceName, + fetchAllPages, filterByName, formatCount, - getBreadcrumbSlugs, - getChildLevel, + getContinentSlug, getFeedCountEntries, + getLocationName, + getLocationSegments, getPageCount, getPageOffset, getTotalFeedCount, + isLocationAtPath, + type LocationResult, normalizeLocationName, - type LocationDirectoryNode, parseLocationSegments, parsePageParam, sortByFeedCount, } from './location-directory'; -const breadcrumb: LocationDirectoryNode[] = [ - { - level: 'continent', - slug: 'north-america', - code: 'NA', - name: 'North America', - }, - { level: 'country', slug: 'canada', code: 'CA', name: 'Canada' }, - { level: 'subdivision', slug: 'quebec', code: null, name: 'Québec' }, - { level: 'municipality', slug: 'montreal', code: null, name: 'Montréal' }, -]; +const northAmerica: LocationResult = { + location_id: null, + parent_location_id: null, + location_type: 'continent', + name: 'North America', + slug: 'north-america', + continent_slug: 'north-america', + continent_name: 'North America', + path_slugs: [], + path_names: [], +}; + +// Variable depth: Montréal sits under an intermediate region. +const montreal: LocationResult = { + location_id: 175905, + parent_location_id: 161950, + location_type: 'municipality', + name: 'Montréal', + slug: 'montreal', + continent_slug: 'north-america', + continent_name: 'North America', + path_slugs: ['canada', 'quebec', 'montreal-region', 'montreal'], + path_names: ['Canada', 'Québec', 'Montréal (region)', 'Montréal'], +}; + +const canada: LocationResult = { + location_id: 1, + parent_location_id: null, + location_type: 'country', + name: 'Canada', + slug: 'canada', + continent_slug: 'north-america', + continent_name: 'North America', + path_slugs: ['canada'], + path_names: ['Canada'], +}; describe('parseLocationSegments', () => { - it('returns an empty query at the root', () => { - expect(parseLocationSegments(undefined)).toEqual({}); - expect(parseLocationSegments([])).toEqual({}); + it('returns an empty path at the root', () => { + expect(parseLocationSegments(undefined)).toEqual({ path: [] }); + expect(parseLocationSegments([])).toEqual({ path: [] }); }); - it('maps each segment to its API parameter, untouched', () => { + it('splits the continent from the path slugs, at any depth', () => { expect(parseLocationSegments(['north-america'])).toEqual({ continent: 'north-america', + path: [], }); - expect( - parseLocationSegments(['north-america', 'canada', 'quebec', 'montreal']), - ).toEqual({ + expect(parseLocationSegments(['north-america', 'canada'])).toEqual({ + continent: 'north-america', + path: ['canada'], + }); + const deep = ['canada', 'quebec', 'montreal-region', 'montreal', 'a', 'b']; + expect(parseLocationSegments(['north-america', ...deep])).toEqual({ continent: 'north-america', - country: 'canada', - subdivision: 'quebec', - municipality: 'montreal', + path: deep, }); }); - it('rejects paths deeper than a municipality', () => { + it('accepts collision suffixes and non-Latin lowercase slugs', () => { expect( parseLocationSegments([ 'north-america', - 'canada', - 'quebec', - 'montreal', - 'x', - ]), - ).toBeNull(); + 'united-states', + 'ohio', + 'washington-township-123456', + ])?.path, + ).toEqual(['united-states', 'ohio', 'washington-township-123456']); + expect(parseLocationSegments(['asia', '東京'])?.path).toEqual(['東京']); }); - it('rejects empty segments', () => { - expect(parseLocationSegments(['north-america', ' '])).toBeNull(); + it('decodes percent-encoded segments', () => { + expect( + parseLocationSegments(['asia', encodeURIComponent('東京')])?.path, + ).toEqual(['東京']); + }); + + it.each([ + [['north-america', '']], + [['north-america', ' ']], + [['North-America']], + [['north-america', 'Canada']], + [['north-america', 'can ada']], + [['north-america', 'can%20ada']], + [['north-america', 'canada.json']], + [['north-america', '%E0%A4%A']], + ])('rejects malformed segments %p', (segments) => { + expect(parseLocationSegments(segments)).toBeNull(); }); }); @@ -122,12 +168,176 @@ describe('buildLocationHref', () => { it('encodes unsafe characters in segments', () => { expect(buildLocationHref(['a b', 'c/d'])).toBe('/locations/a%20b/c%2Fd'); }); +}); + +describe('location segments and names', () => { + it('links a location through its path slugs under the continent', () => { + expect(getLocationSegments('north-america', montreal)).toEqual([ + 'north-america', + 'canada', + 'quebec', + 'montreal-region', + 'montreal', + ]); + expect( + buildLocationHref(getLocationSegments('north-america', canada)), + ).toBe('/locations/north-america/canada'); + }); + + it('links a continent through its own slug', () => { + expect(getLocationSegments('', northAmerica)).toEqual(['north-america']); + expect(getContinentSlug({ ...northAmerica, continent_slug: null })).toBe( + 'north-america', + ); + }); + + it('round-trips with URL parsing', () => { + const href = buildLocationHref( + getLocationSegments('north-america', montreal), + 2, + ); + expect(href).toBe( + '/locations/north-america/canada/quebec/montreal-region/montreal?page=2', + ); + const segments = href.split('?')[0].split('/').slice(2); + const parsed = parseLocationSegments(segments); + expect(parsed).toEqual({ + continent: 'north-america', + path: montreal.path_slugs, + }); + expect( + isLocationAtPath(montreal, 'north-america', parsed?.path ?? []), + ).toBe(true); + }); + + it('checks the result is the requested location', () => { + expect(isLocationAtPath(canada, 'north-america', ['canada'])).toBe(true); + // The API also accepts continent codes: only the slug is canonical. + expect(isLocationAtPath(canada, 'na', ['canada'])).toBe(false); + expect(isLocationAtPath(canada, 'north-america', ['mexico'])).toBe(false); + }); + + it('names a location, falling back to its slug', () => { + expect(getLocationName(montreal)).toBe('Montréal'); + expect(getLocationName({ ...montreal, name: null })).toBe('montreal'); + expect(getLocationName({ ...northAmerica, name: null })).toBe( + 'North America', + ); + }); +}); + +describe('buildBreadcrumbSteps', () => { + it('is empty at the root', () => { + expect(buildBreadcrumbSteps('', null)).toEqual([]); + }); + + it('has a single step on a continent', () => { + expect(buildBreadcrumbSteps('north-america', northAmerica)).toEqual([ + { label: 'North America', segments: ['north-america'] }, + ]); + }); + + it('adds one step per path name, linked by the path slug prefix', () => { + expect(buildBreadcrumbSteps('north-america', montreal)).toEqual([ + { label: 'North America', segments: ['north-america'] }, + { label: 'Canada', segments: ['north-america', 'canada'] }, + { label: 'Québec', segments: ['north-america', 'canada', 'quebec'] }, + { + label: 'Montréal (region)', + segments: ['north-america', 'canada', 'quebec', 'montreal-region'], + }, + { + label: 'Montréal', + segments: [ + 'north-america', + 'canada', + 'quebec', + 'montreal-region', + 'montreal', + ], + }, + ]); + }); + + it('falls back to the continent slug and ignores unaligned names', () => { + const steps = buildBreadcrumbSteps('north-america', { + ...canada, + continent_name: null, + path_names: ['Canada', 'Extra'], + }); + expect(steps.map((step) => step.label)).toEqual([ + 'north-america', + 'Canada', + ]); + }); +}); + +describe('buildPlaceName', () => { + it('is empty at the root', () => { + expect(buildPlaceName(null)).toBe(''); + }); + + it('names a continent on its own', () => { + expect(buildPlaceName(northAmerica)).toBe('North America'); + }); + + it('lists the most specific place first, without the continent', () => { + expect(buildPlaceName(canada)).toBe('Canada'); + expect(buildPlaceName(montreal)).toBe( + 'Montréal, Montréal (region), Québec, Canada', + ); + }); +}); + +describe('fetchAllPages', () => { + const pageOf = ( + total: number, + offset: number, + limit: number, + ): { total: number; results: number[] } => ({ + total, + results: Array.from( + { length: Math.max(0, Math.min(limit, total - offset)) }, + (_, index) => offset + index, + ), + }); + + it('stops after the first page when it holds everything', async () => { + const fetchPage = jest.fn(async (offset: number, limit: number) => + pageOf(42, offset, limit), + ); + await expect(fetchAllPages(fetchPage)).resolves.toHaveLength(42); + expect(fetchPage).toHaveBeenCalledTimes(1); + expect(fetchPage).toHaveBeenCalledWith(0, 100); + }); - it('round-trips with the breadcrumb slugs', () => { - expect(buildLocationHref(getBreadcrumbSlugs(breadcrumb), 2)).toBe( - '/locations/north-america/canada/quebec/montreal?page=2', + it('fetches the remaining pages in order', async () => { + const fetchPage = jest.fn(async (offset: number, limit: number) => + pageOf(250, offset, limit), ); - expect(getBreadcrumbSlugs(undefined)).toEqual([]); + const results = await fetchAllPages(fetchPage); + expect(results).toEqual(Array.from({ length: 250 }, (_, index) => index)); + expect(fetchPage.mock.calls).toEqual([ + [0, 100], + [100, 100], + [200, 100], + ]); + }); + + it('follows a server that returns fewer results than asked', async () => { + const fetchPage = jest.fn(async (offset: number) => pageOf(25, offset, 10)); + await expect(fetchAllPages(fetchPage)).resolves.toHaveLength(25); + expect(fetchPage.mock.calls.map(([offset]) => offset)).toEqual([0, 10, 20]); + }); + + it('handles empty and total-less responses', async () => { + await expect( + fetchAllPages(async () => ({ total: 0, results: [] })), + ).resolves.toEqual([]); + await expect(fetchAllPages(async () => ({}))).resolves.toEqual([]); + await expect( + fetchAllPages(async () => ({ results: [1, 2] })), + ).resolves.toEqual([1, 2]); }); }); @@ -159,33 +369,6 @@ describe('feed counts', () => { }); }); -describe('getChildLevel', () => { - it('walks one level down and stops at municipalities', () => { - expect(getChildLevel('root')).toBe('continent'); - expect(getChildLevel(undefined)).toBe('continent'); - expect(getChildLevel('continent')).toBe('country'); - expect(getChildLevel('country')).toBe('subdivision'); - expect(getChildLevel('subdivision')).toBe('municipality'); - expect(getChildLevel('municipality')).toBeNull(); - }); -}); - -describe('buildPlaceName', () => { - it('is empty at the root', () => { - expect(buildPlaceName([])).toBe(''); - expect(buildPlaceName(undefined)).toBe(''); - }); - - it('names a continent on its own', () => { - expect(buildPlaceName(breadcrumb.slice(0, 1))).toBe('North America'); - }); - - it('lists the most specific place first, without the continent', () => { - expect(buildPlaceName(breadcrumb.slice(0, 2))).toBe('Canada'); - expect(buildPlaceName(breadcrumb)).toBe('Montréal, Québec, Canada'); - }); -}); - describe('normalizeLocationName', () => { it('drops accents and case', () => { expect(normalizeLocationName(' Québec ')).toBe('quebec'); diff --git a/src/app/[locale]/locations/lib/location-directory.ts b/src/app/[locale]/locations/lib/location-directory.ts index c3dc11e2..d9af3aba 100644 --- a/src/app/[locale]/locations/lib/location-directory.ts +++ b/src/app/[locale]/locations/lib/location-directory.ts @@ -1,59 +1,62 @@ /** * Pure helpers for the /locations directory: URL segment and page parsing, - * URL building and count formatting. Safe to import from server and client - * components; holds no data fetching. + * URL and breadcrumb building, paging and count formatting. Safe to import + * from server and client components; holds no data fetching. */ import type { components } from '../../../services/feeds/types'; -export type LocationDirectoryNode = - components['schemas']['LocationDirectoryNode']; -export type LocationDirectoryLevel = - components['schemas']['LocationDirectoryLevel']; -export type LocationDirectoryFeedCounts = - components['schemas']['LocationDirectoryFeedCounts']; +export type LocationResult = components['schemas']['LocationSearchResult']; +export type LocationFeedCounts = components['schemas']['LocationFeedCounts']; export const LOCATIONS_BASE_PATH = '/locations'; export const LOCATION_FEEDS_PAGE_SIZE = 20; -/** continent > country > subdivision > municipality */ -export const MAX_LOCATION_DEPTH = 4; +/** Maximum `limit` of `GET /v1/locations`. */ +export const LOCATIONS_API_PAGE_SIZE = 100; /** Anchor of the feed list; pagination links jump back to it. */ export const FEEDS_SECTION_ID = 'feeds'; -/** Query parameters shared by both directory endpoints. */ -export interface LocationQuery { +/** + * A directory location as addressed by its URL: the continent slug, then the + * `path_slugs` of the location from the country down. Both are empty at the + * root; `path` is empty on a continent page. + */ +export interface LocationPath { continent?: string; - /** Country slug, e.g. `canada`. */ - country?: string; - subdivision?: string; - municipality?: string; + path: string[]; } -const QUERY_KEYS_BY_DEPTH = [ - 'continent', - 'country', - 'subdivision', - 'municipality', -] as const; +// API slugs: lowercase letters (any script), digits and hyphens, e.g. +// `north-america`, `montreal`, `washington-township-123456`. +const SLUG_PATTERN = /^[\p{Ll}\p{Lo}\p{M}\p{Nd}-]+$/u; + +function decodeSegment(segment: string): string | null { + if (!segment.includes('%')) return segment; + try { + return decodeURIComponent(segment); + } catch { + return null; + } +} /** - * Maps the optional catch-all segments to the directory query. Segments are - * passed through untouched: API slugs are exactly the URL segments. + * Maps the optional catch-all segments to a location path: the first segment + * is the continent, the others are the location's path slugs, at any depth. * - * @returns the query (empty at the root), or null when the path is deeper - * than a municipality or contains an empty segment. + * @returns the path (empty at the root), or null when a segment is not a + * valid slug (empty, uppercase, spaces, punctuation other than `-`). */ export function parseLocationSegments( segments: readonly string[] | undefined, -): LocationQuery | null { - if (segments == undefined) return {}; - if (segments.length > MAX_LOCATION_DEPTH) return null; - const query: LocationQuery = {}; - for (let depth = 0; depth < segments.length; depth++) { - const segment = segments[depth].trim(); - if (segment === '') return null; - query[QUERY_KEYS_BY_DEPTH[depth]] = segment; +): LocationPath | null { + if (segments == undefined || segments.length === 0) return { path: [] }; + const slugs: string[] = []; + for (const segment of segments) { + const slug = decodeSegment(segment); + if (slug === null || !SLUG_PATTERN.test(slug)) return null; + slugs.push(slug); } - return query; + const [continent, ...path] = slugs; + return { continent, path }; } const PAGE_PATTERN = /^[1-9]\d*$/; @@ -91,26 +94,141 @@ export function getPageOffset( } /** - * Locale-less path to a directory node, e.g. - * `/locations/north-america/canada/quebec?page=2`. Page 1 has no query string so - * that it stays the canonical URL of the node. Pass the result to the + * Locale-less path to a directory location, e.g. + * `/locations/north-america/canada/quebec?page=2`. Page 1 has no query string + * so that it stays the canonical URL of the location. Pass the result to the * next-intl `Link`, which adds the locale prefix. */ export function buildLocationHref( - slugs: readonly string[], + segments: readonly string[], page: number = 1, ): string { - const path = [LOCATIONS_BASE_PATH, ...slugs.map(encodeURIComponent)].join( + const path = [LOCATIONS_BASE_PATH, ...segments.map(encodeURIComponent)].join( '/', ); return page > 1 ? `${path}?page=${page}` : path; } -/** Slugs of every breadcrumb node, from the continent down. */ -export function getBreadcrumbSlugs( - breadcrumb: readonly LocationDirectoryNode[] | undefined, +/** URL slug of a continent row; continents have no geopolygon path. */ +export function getContinentSlug(continent: LocationResult): string { + return continent.continent_slug ?? continent.slug ?? ''; +} + +/** Display name of a location, falling back to its slug. */ +export function getLocationName(location: LocationResult): string { + if (location.location_type === 'continent') { + return ( + location.name ?? location.continent_name ?? getContinentSlug(location) + ); + } + return location.name ?? location.slug ?? ''; +} + +/** + * URL segments of a location under the continent of the current page: + * `[continent, ...path_slugs]`. A continent row links to its own slug. + */ +export function getLocationSegments( + continentSlug: string, + location: LocationResult, ): string[] { - return (breadcrumb ?? []).map((node) => node.slug ?? ''); + if (location.location_type === 'continent') { + return [getContinentSlug(location)]; + } + return [continentSlug, ...(location.path_slugs ?? [])]; +} + +export interface BreadcrumbStep { + label: string; + /** URL segments of this step, continent first. */ + segments: string[]; +} + +/** + * The continent, then one step per `path_names` entry, each linked through + * the matching prefix of `path_slugs`. Empty at the root. + */ +export function buildBreadcrumbSteps( + continentSlug: string, + location: LocationResult | null, +): BreadcrumbStep[] { + if (location === null) return []; + const continentStep: BreadcrumbStep = { + label: + location.continent_name ?? + (location.location_type === 'continent' + ? getLocationName(location) + : continentSlug), + segments: [continentSlug], + }; + if (location.location_type === 'continent') return [continentStep]; + const names = location.path_names ?? []; + const slugs = location.path_slugs ?? []; + const depth = Math.min(names.length, slugs.length); + const steps = [continentStep]; + for (let index = 0; index < depth; index++) { + steps.push({ + label: names[index], + segments: [continentSlug, ...slugs.slice(0, index + 1)], + }); + } + return steps; +} + +/** + * Human-readable place for titles, most specific first: + * `Montréal, Québec, Canada`. A continent is named on its own; empty at the + * root. + */ +export function buildPlaceName(location: LocationResult | null): string { + if (location === null) return ''; + if (location.location_type === 'continent') return getLocationName(location); + const names = location.path_names ?? []; + if (names.length === 0) return getLocationName(location); + return [...names].reverse().join(', '); +} + +/** True when the API result is the location the URL asked for. */ +export function isLocationAtPath( + location: LocationResult, + continentSlug: string, + path: readonly string[], +): boolean { + return ( + location.continent_slug === continentSlug && + (location.path_slugs ?? []).join('/') === path.join('/') + ); +} + +export interface ResultsPage { + total?: number; + results?: T[]; +} + +/** + * Fetches every result of an offset-paginated endpoint: the first page tells + * the total and the effective page size, the remaining pages are then + * fetched in parallel. + */ +export async function fetchAllPages( + fetchPage: (offset: number, limit: number) => Promise>, + pageSize: number = LOCATIONS_API_PAGE_SIZE, +): Promise { + const first = await fetchPage(0, pageSize); + const results = [...(first.results ?? [])]; + const total = first.total ?? results.length; + // A server that caps `limit` lower than asked still pages consistently. + const step = results.length; + if (step === 0 || step >= total) return results; + const offsets: number[] = []; + for (let offset = step; offset < total; offset += step) { + offsets.push(offset); + } + const rest = await Promise.all( + offsets.map(async (offset) => await fetchPage(offset, pageSize)), + ); + for (const page of rest) results.push(...(page.results ?? [])); + return results; } export const FEED_COUNT_DATA_TYPES = ['gtfs', 'gtfs_rt', 'gbfs'] as const; @@ -123,7 +241,7 @@ export interface FeedCountEntry { /** GTFS, GTFS-RT and GBFS counts in display order; missing counts are 0. */ export function getFeedCountEntries( - counts: LocationDirectoryFeedCounts | undefined, + counts: LocationFeedCounts | undefined, ): FeedCountEntry[] { return FEED_COUNT_DATA_TYPES.map((dataType) => ({ dataType, @@ -131,9 +249,9 @@ export function getFeedCountEntries( })); } -/** Total distinct feeds of a node, falling back to the sum by data type. */ +/** Total distinct feeds of a location, falling back to the sum by type. */ export function getTotalFeedCount( - counts: LocationDirectoryFeedCounts | undefined, + counts: LocationFeedCounts | undefined, ): number { if (counts?.total != undefined) return counts.total; return getFeedCountEntries(counts).reduce( @@ -153,7 +271,7 @@ export function normalizeLocationName(name: string): string { /** Most feeds first; ties by name, ignoring accents and case. */ export function sortByFeedCount< - T extends { name: string; counts: LocationDirectoryFeedCounts | undefined }, + T extends { name: string; counts: LocationFeedCounts | undefined }, >(items: readonly T[]): T[] { return [...items].sort( (a, b) => @@ -182,38 +300,3 @@ export function formatCount(value: number | undefined, locale: string): string { value ?? 0, ); } - -const CHILD_LEVEL: Record< - LocationDirectoryLevel, - LocationDirectoryLevel | null -> = { - root: 'continent', - continent: 'country', - country: 'subdivision', - subdivision: 'municipality', - municipality: null, -}; - -/** The level of a node's children, or null for municipalities. */ -export function getChildLevel( - level: LocationDirectoryLevel | undefined, -): LocationDirectoryLevel | null { - return CHILD_LEVEL[level ?? 'root']; -} - -/** - * Human-readable place for titles, most specific first: - * `Montréal, Québec, Canada`. The continent is dropped once a country is - * known; a continent on its own is returned as is. Empty at the root. - */ -export function buildPlaceName( - breadcrumb: readonly LocationDirectoryNode[] | undefined, -): string { - const names = (breadcrumb ?? []) - .filter( - (node, index, all) => !(node.level === 'continent' && all.length > 1), - ) - .map((node) => node.name ?? node.slug ?? '') - .filter((name) => name !== ''); - return names.reverse().join(', '); -} diff --git a/src/app/services/feeds/index.ts b/src/app/services/feeds/index.ts index edd343d5..3a9644b8 100644 --- a/src/app/services/feeds/index.ts +++ b/src/app/services/feeds/index.ts @@ -352,8 +352,8 @@ export type SearchFeedsResponse = paths['/v1/search']['get']['responses'][200]['content']['application/json']; /** - * Also lists the feeds of a location directory node, with its location - * parameters and `sort: 'location'`. + * Also lists the feeds of a location directory page, with `continent` or + * `location_id` and `sort: 'location'`. */ export const searchFeeds = async ( params: AllFeedsParams, @@ -370,29 +370,29 @@ export const searchFeeds = async ( }); }; -export type LocationDirectoryParams = NonNullable< - paths['/v1/locations/directory']['get']['parameters']['query'] +export type LocationsParams = NonNullable< + paths['/v1/locations']['get']['parameters']['query'] >; -export type LocationDirectoryResponse = - paths['/v1/locations/directory']['get']['responses'][200]['content']['application/json']; +export type LocationsResponse = + paths['/v1/locations']['get']['responses'][200]['content']['application/json']; /** - * One level of the feed location directory: the node's breadcrumb, feed - * counts and children. Throws an `ApiError` with status 400 (invalid - * hierarchy) or 404 (no feed located there). + * Searches locations (continents, countries, subdivisions, municipalities). + * Returns at most 100 results per call: page with `limit` and `offset`. + * Throws an `ApiError` with status 400 on an unsupported `sort`. */ -export const getLocationDirectory = async ( - params: LocationDirectoryParams, +export const getLocations = async ( + params: LocationsParams, accessToken: string, userContextJwt?: string, -): Promise => { +): Promise => { const authMiddleware = generateAuthMiddlewareWithToken( accessToken, userContextJwt, ); return await withAuthMiddleware(authMiddleware, async () => { - const response = await client.GET('/v1/locations/directory', { + const response = await client.GET('/v1/locations', { params: { query: params }, }); return response.data; diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index 113ed5bd..c95abba7 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -334,11 +334,12 @@ export interface paths { *

    * Location filters: *
    - * - `continent`, `country`, `subdivision` and `municipality` restrict the results to feeds with a declared - * location within that node of `/v1/locations/directory`, using the same slugs, parent requirements and - * validation. Unknown slugs return no feed. - * - To list the same feeds as a directory node's counts, also pass `status=active,inactive,development,future`. - * - `sort=location` orders the results by relevance to the requested location instead of by creation date. + * - `continent` restricts the results to feeds with stops in that continent, and `location_id` to feeds with + * stops in that location of `/v1/locations`, sub-areas included. Feeds are matched through their + * reverse-geolocated stops, so a feed that was never geolocated does not match. Unknown values return no feed. + * - To list the same feeds as a location's `feed_counts`, also pass `status=active,inactive,development,future`. + * - `sort=location` orders the results by the share of each feed's stops inside the requested location instead + * of by creation date. *
    */ get: operations['searchFeeds']; @@ -357,7 +358,7 @@ export interface paths { path?: never; cookie?: never; }; - /** @description Search locations (countries, subdivisions and municipalities). Results can be filtered by a free-text query and narrowed to a specific country, subdivision or location type. Matches are ordered from the broadest area to the most specific, and by relevance within each level. */ + /** @description Search locations (continents, countries, subdivisions and municipalities). Results can be filtered by a free-text query and narrowed to a specific continent, country, subdivision, parent location, path or location type. Matches are ordered from the broadest area to the most specific, and by relevance within each level, unless `sort=feed_count` is given.
    Feed counts (`include_feed_counts`, `has_feeds`, `sort=feed_count`) count distinct feeds with a status of `active`, `inactive`, `development` or `future` that have reverse-geolocated stops in the location, sub-areas included. Work-in-progress feeds are counted only for callers allowed to see them, as in `/v1/search`. To list a location's feeds, call `/v1/search` with its `location_id` (or `continent` for a continent), `status=active,inactive,development,future` and `sort=location`.
    Continents come from a fixed classification and are not geopolygons. They are only returned with `location_type=continent`; their `location_id`, `parent_location_id` and ISO fields are null, `slug` and `continent_slug` both hold the continent slug, and `path_names` and `path_slugs` are empty. */ get: operations['getLocations']; put?: never; post?: never; @@ -367,23 +368,6 @@ export interface paths { patch?: never; trace?: never; }; - '/v1/locations/directory': { - parameters: { - query?: never; - header?: never; - path?: never; - cookie?: never; - }; - /** @description Browse the feed location directory one level at a time: continent > country > subdivision > municipality. The level is selected by the most specific parameter provided; with no parameters the response lists continents.
    Feed counts are based on the feeds' declared locations, only include feeds with a status of `active`, `inactive`, `development` or `future`, and roll up to every ancestor level (a feed located in Montréal counts toward Québec, Canada and North America). A feed is counted at most once per node, even when it declares several locations within that node.
    Each parameter requires its parent: `country` requires `continent`, `subdivision` requires `country`, and `municipality` requires `subdivision`.
    To list the feeds of a node, call `/v1/search` with the same parameters, `status=active,inactive,development,future` and `sort=location`. */ - get: operations['getLocationDirectory']; - put?: never; - post?: never; - delete?: never; - options?: never; - head?: never; - patch?: never; - trace?: never; - }; '/v1/licenses': { parameters: { query?: never; @@ -1333,24 +1317,8 @@ export interface components { */ municipality?: string; }; - /** - * @description A level of the location directory: - * * `root` - the whole world; its children are continents. - * * `continent` - a continent, derived from the ISO 3166-1 country code. - * * `country` - a country, identified by its ISO 3166-1 alpha-2 code. - * * `subdivision` - a first-level subdivision as declared on the feed (e.g. a state or province). - * * `municipality` - a municipality as declared on the feed. - * @example subdivision - * @enum {string} - */ - LocationDirectoryLevel: - | 'root' - | 'continent' - | 'country' - | 'subdivision' - | 'municipality'; - /** @description Number of distinct feeds per data type within a directory node. */ - LocationDirectoryFeedCounts: { + /** @description Number of distinct feeds per data type with stops in a location, sub-areas included. */ + LocationFeedCounts: { /** @example 42 */ gtfs?: number; /** @example 18 */ @@ -1363,33 +1331,6 @@ export interface components { */ total?: number; }; - LocationDirectoryNode: { - level?: components['schemas']['LocationDirectoryLevel']; - /** - * @description URL-safe identifier of the node, used as the matching request parameter. Continents use a fixed slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`), countries use a fixed slug of their short English name (`portugal`, `united-states`, `cote-d-ivoire`), and subdivisions and municipalities use their name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Québec` -> `quebec`, `Saint-Jean-sur-Richelieu` -> `saint-jean-sur-richelieu`). - * @example quebec - */ - slug?: string; - /** - * @description The continent code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`) or the ISO 3166-1 alpha-2 country code. Null for subdivisions and municipalities. - * @example null - */ - code?: string | null; - /** - * @description Display name of the node in English. - * @example Québec - */ - name?: string; - feed_counts?: components['schemas']['LocationDirectoryFeedCounts']; - }; - LocationDirectoryResponse: { - level?: components['schemas']['LocationDirectoryLevel']; - /** @description The path from the continent down to the requested node, inclusive. Empty at the `root` level. */ - breadcrumb?: components['schemas']['LocationDirectoryNode'][]; - feed_counts?: components['schemas']['LocationDirectoryFeedCounts']; - /** @description The nodes one level below the requested node that contain at least one feed, sorted by name. Empty at the `municipality` level. */ - children?: components['schemas']['LocationDirectoryNode'][]; - }; LocationSearchResponse: { /** @description The total number of matching locations regardless of limit and offset. */ total?: number; @@ -1398,12 +1339,12 @@ export interface components { }; LocationSearchResult: { /** - * @description Stable location identifier. + * @description Stable location identifier. Null for continents. * @example 175905 */ - location_id?: number; + location_id?: number | null; /** - * @description Stable identifier of the nearest containing location. + * @description Stable identifier of the nearest containing location. Null for continents and countries. * @example 161950 */ parent_location_id?: number | null; @@ -1418,11 +1359,42 @@ export interface components { */ alt_name?: string | null; /** - * @description The type of location: `country` (has an ISO 3166-1 code), `subdivision` (has an ISO 3166-2 code) or `municipality` (a locality below the subdivision level). + * @description The type of location: `continent`, `country` (has an ISO 3166-1 code), `subdivision` (has an ISO 3166-2 code) or `municipality` (a locality below the subdivision level). * @example municipality * @enum {string} */ - location_type?: 'country' | 'subdivision' | 'municipality'; + location_type?: 'continent' | 'country' | 'subdivision' | 'municipality'; + /** + * @description Code of the continent that contains this location (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Null when the country has no continent in the classification. + * @example NA + */ + continent_code?: string | null; + /** + * @description URL-safe identifier of the continent, as accepted by the `continent` parameter. + * @example north-america + */ + continent_slug?: string | null; + /** + * @description English name of the continent. + * @example North America + */ + continent_name?: string | null; + /** + * @description URL-safe identifier of the location among its siblings: its name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Montréal` -> `montreal`). When siblings under the same parent would share a slug, each of them gets `-` appended. A name without any ASCII letter or digit uses its `location_id` as the slug. + * @example montreal + */ + slug?: string | null; + /** + * @description The slugs of the locations in `path_names`, in the same order; joined with `/` they form the `path` parameter. Empty for continents. + * @example [ + * "canada", + * "quebec", + * "montreal-region", + * "montreal" + * ] + */ + path_slugs?: string[]; + feed_counts?: components['schemas']['LocationFeedCounts']; /** * @description The name of the country that contains this location. * @example Canada @@ -1904,14 +1876,12 @@ export interface components { is_official_query_param: boolean; /** @description If true, only return feeds that currently hold the Seal of Reliability; if false, only feeds without it. Viewing a feed's seal is public, but filtering the catalogue by it is granted per user and requires the `isSealFilterEnabled` feature flag - other callers receive a 403. To request access or learn more, contact us at api@mobilitydata.org. */ has_seal_query_param: boolean; - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ - location_directory_continent: string; - /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ - location_directory_country: string; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ - location_directory_subdivision: string; - /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ - location_directory_municipality: string; + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ + location_continent: string; + /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. */ + location_id_query_param: number; + /** @description Sort order of the results. `admin_level` (default): from the broadest area to the most specific, then by relevance to `search_query` when one is given, then by display name. `feed_count`: most feeds first, then by display name. */ + locations_sort: 'admin_level' | 'feed_count'; /** @description The number of items to be returned. */ limit_query_param_locations_endpoint: number; /** @description The number of items to be returned. */ @@ -1932,7 +1902,7 @@ export interface components { offset: number; /** @description General search query to match against transit provider, location, and feed name. */ search_text_query_param: string; - /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent`. Feeds whose most specific matching declared location is closest to the requested level come first (when filtering on Québec, a feed located in "Canada, Québec" ranks above one located in "Canada, Québec, Montréal"); ties are broken by provider, feed name and feed id. */ + /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent` or `location_id`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ search_sort: 'created_at' | 'location'; /** @description Comma separated list of GBFS versions to filter by. */ version_query_param: string; @@ -2584,15 +2554,11 @@ export interface operations { license_is_spdx?: components['parameters']['license_is_spdx']; /** @description Comma separated list of tags to filter feeds by their license tags. */ license_tags?: components['parameters']['license_tags']; - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ - continent?: components['parameters']['location_directory_continent']; - /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ - country?: components['parameters']['location_directory_country']; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ - subdivision?: components['parameters']['location_directory_subdivision']; - /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ - municipality?: components['parameters']['location_directory_municipality']; - /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent`. Feeds whose most specific matching declared location is closest to the requested level come first (when filtering on Québec, a feed located in "Canada, Québec" ranks above one located in "Canada, Québec, Montréal"); ties are broken by provider, feed name and feed id. */ + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ + continent?: components['parameters']['location_continent']; + /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. */ + location_id?: components['parameters']['location_id_query_param']; + /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent` or `location_id`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ sort?: components['parameters']['search_sort']; }; header?: never; @@ -2614,7 +2580,7 @@ export interface operations { }; }; }; - /** @description A location parameter was provided without its parent, the country does not belong to the continent, or `sort=location` was requested without a location. */ + /** @description `sort=location` was requested without `continent` or `location_id`, or `sort` has an unsupported value. */ 400: { headers: { [name: string]: unknown; @@ -2645,11 +2611,28 @@ export interface operations { subdivision_code?: string; /** * @description Filter by the type of location: + * * `continent` - a continent, from a fixed country-to-continent classification. * * `country` - a sovereign country, identified by an ISO 3166-1 code. * * `subdivision` - a first-level subdivision (e.g. state or province), identified by an ISO 3166-2 code. * * `municipality` - a locality below the subdivision level (e.g. a city or town). */ - location_type?: 'country' | 'subdivision' | 'municipality'; + location_type?: + | 'continent' + | 'country' + | 'subdivision' + | 'municipality'; + /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ + continent?: components['parameters']['location_continent']; + /** @description Limit results to the direct children of this location (the next level down). */ + parent_location_id?: number; + /** @description Return the location at this path: its `path_slugs` joined with `/`, from the country down, e.g. `canada/quebec/montreal`. Case-insensitive. Returns no result when no location has that path. */ + path?: string; + /** @description When true, only return locations with at least one feed (see the feed count rules above). */ + has_feeds?: boolean; + /** @description When true, include `feed_counts` in each result. */ + include_feed_counts?: boolean; + /** @description Sort order of the results. `admin_level` (default): from the broadest area to the most specific, then by relevance to `search_query` when one is given, then by display name. `feed_count`: most feeds first, then by display name. */ + sort?: components['parameters']['locations_sort']; }; header?: never; path?: never; @@ -2666,49 +2649,13 @@ export interface operations { 'application/json': components['schemas']['LocationSearchResponse']; }; }; - }; - }; - getLocationDirectory: { - parameters: { - query?: { - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`). */ - continent?: components['parameters']['location_directory_continent']; - /** @description Country slug as returned by `/v1/locations/directory`, e.g. `portugal`. Case-insensitive. Requires `continent`. */ - country?: components['parameters']['location_directory_country']; - /** @description Subdivision slug as returned by `/v1/locations/directory`. Requires `country`. */ - subdivision?: components['parameters']['location_directory_subdivision']; - /** @description Municipality slug as returned by `/v1/locations/directory`. Requires `subdivision`. */ - municipality?: components['parameters']['location_directory_municipality']; - }; - header?: never; - path?: never; - cookie?: never; - }; - requestBody?: never; - responses: { - /** @description The requested directory node, its breadcrumb and its children. */ - 200: { - headers: { - [name: string]: unknown; - }; - content: { - 'application/json': components['schemas']['LocationDirectoryResponse']; - }; - }; - /** @description A parameter was provided without its parent, or the country does not belong to the continent. */ + /** @description `sort` has an unsupported value. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; - /** @description No feed is located at the requested location. */ - 404: { - headers: { - [name: string]: unknown; - }; - content?: never; - }; }; }; getLicenses: { diff --git a/src/mocks/handlers.ts b/src/mocks/handlers.ts index da4a4ccf..9225ba1d 100644 --- a/src/mocks/handlers.ts +++ b/src/mocks/handlers.ts @@ -8,31 +8,25 @@ import feed2947 from '../../cypress/fixtures/feed_mdb-2947.json'; import gtfsFeed2947 from '../../cypress/fixtures/gtfs_feed_mdb-2947.json'; import datasets2947 from '../../cypress/fixtures/feed_datasets_mdb-2947.json'; import { - getMockDirectory, - getMockDirectoryFeeds, - readDirectoryQuery, + getMockLocationFeeds, + getMockLocations, + isLocationSearch, } from './locationDirectory'; export const handlers = [ - // Location directory: breadcrumb, counts and children of a node - http.get(`*/v1/locations/directory`, ({ request }) => { + // Locations: continents, children by parent, path lookup, feed counts + http.get(`*/v1/locations`, ({ request }) => { const params = new URL(request.url).searchParams; - const { status, body } = getMockDirectory(readDirectoryQuery(params)); + const { status, body } = getMockLocations(params); return HttpResponse.json(body, { status }); }), - // Mock search endpoint. With location parameters (location directory - // pages): the feeds of that node, paginated and relevance-sorted. + // Mock search endpoint. With `continent` or `location_id` (location + // directory pages): the feeds located there, paginated and sorted. // Otherwise: a list including test-516 and mdb-2947. http.get(`*/v1/search`, ({ request }) => { const params = new URL(request.url).searchParams; - if (params.has('continent') || params.get('sort') === 'location') { - const limit = Number(params.get('limit') ?? '20'); - const offset = Number(params.get('offset') ?? '0'); - const { status, body } = getMockDirectoryFeeds( - readDirectoryQuery(params), - Number.isFinite(limit) ? limit : 20, - Number.isFinite(offset) ? offset : 0, - ); + if (isLocationSearch(params)) { + const { status, body } = getMockLocationFeeds(params); return HttpResponse.json(body, { status }); } return HttpResponse.json({ diff --git a/src/mocks/locationDirectory.spec.ts b/src/mocks/locationDirectory.spec.ts index 6ccc6bb5..4f632e67 100644 --- a/src/mocks/locationDirectory.spec.ts +++ b/src/mocks/locationDirectory.spec.ts @@ -1,10 +1,37 @@ import { - getMockDirectory, - getMockDirectoryFeeds, - readDirectoryQuery, + getMockLocationFeeds, + getMockLocations, + isLocationSearch, slugify, } from './locationDirectory'; +type Locations = ReturnType; +type Feeds = ReturnType; + +function locations( + query: string, +): NonNullable['body']> { + const result = getMockLocations(new URLSearchParams(query)); + if (result.status !== 200) throw new Error(`expected 200 for ${query}`); + return result.body; +} + +function feeds(query: string): Extract['body'] { + const result = getMockLocationFeeds(new URLSearchParams(query)); + if (result.status !== 200) throw new Error(`expected 200 for ${query}`); + return result.body; +} + +function at( + path: string, +): NonNullable['results']>[number] { + const [location] = + locations( + `continent=north-america&path=${path}&include_feed_counts=true&limit=1`, + ).results ?? []; + return location; +} + describe('location directory mocks', () => { it('slugifies names like the API', () => { expect(slugify('Québec')).toBe('quebec'); @@ -14,64 +41,101 @@ describe('location directory mocks', () => { expect(slugify('Île-de-France')).toBe('ile-de-france'); }); - it('lists continents at the root', () => { - const result = getMockDirectory({}); - expect(result.status).toBe(200); - if (result.status !== 200) return; - expect(result.body.level).toBe('root'); - expect(result.body.breadcrumb).toEqual([]); - expect(result.body.children?.map((node) => node.slug)).toEqual([ + it('lists continents with counts, empty ones included', () => { + const { results } = locations( + 'location_type=continent&include_feed_counts=true', + ); + expect(results?.map((row) => row.continent_slug)).toEqual([ 'africa', + 'antarctica', 'europe', 'north-america', 'oceania', ]); + const antarctica = results?.find((row) => row.slug === 'antarctica'); + expect(antarctica?.location_id).toBeNull(); + expect(antarctica?.path_slugs).toEqual([]); + expect(antarctica?.feed_counts?.total).toBe(0); }); - it('resolves the Montréal breadcrumb and rolls counts up', () => { - const query = readDirectoryQuery( - new URLSearchParams( - 'continent=north-america&country=canada&subdivision=quebec&municipality=montreal', - ), + it('lists the countries of a continent with feeds, most feeds first', () => { + const { results } = locations( + 'continent=NA&location_type=country&has_feeds=true&include_feed_counts=true&sort=feed_count', ); - const result = getMockDirectory(query); - expect(result.status).toBe(200); - if (result.status !== 200) return; - expect(result.body.breadcrumb?.map((node) => node.name)).toEqual([ - 'North America', - 'Canada', - 'Québec', - 'Montréal', + expect(results?.map((row) => row.path_slugs)).toEqual([ + ['canada'], + ['united-states'], ]); - expect(result.body.children).toEqual([]); - const montreal = result.body.feed_counts?.total ?? 0; - const quebec = result.body.breadcrumb?.[2].feed_counts?.total ?? 0; - expect(montreal).toBeGreaterThan(20); - expect(quebec).toBeGreaterThan(montreal); + expect(results?.[0].feed_counts?.total).toBeGreaterThan( + results?.[1].feed_counts?.total ?? 0, + ); }); - it('returns 400 on a broken hierarchy and 404 when nothing is there', () => { - expect(getMockDirectory({ country: 'canada' }).status).toBe(400); + it('resolves a path and rolls counts up', () => { + const montreal = at('canada/quebec/montreal'); + expect(montreal.path_names).toEqual(['Canada', 'Québec', 'Montréal']); + expect(montreal.feed_counts?.total).toBe(22); + expect(at('canada/quebec').feed_counts?.total).toBeGreaterThan(22); + expect(at('canada/quebec/nowhere')).toBeUndefined(); + expect(locations('continent=europe&path=canada').results).toEqual([]); + }); + + it('has a variable depth and collision-suffixed slugs', () => { + const losAngeles = at( + 'united-states/california/los-angeles-county/los-angeles', + ); + expect(losAngeles.path_names).toHaveLength(4); expect( - getMockDirectory({ continent: 'europe', country: 'canada' }).status, - ).toBe(400); - expect(getMockDirectory({ continent: 'antarctica' }).status).toBe(404); + at('united-states/california/san-francisco').path_slugs, + ).toHaveLength(3); + const ohio = at('united-states/ohio'); + const { results } = locations( + `parent_location_id=${ohio.location_id}&has_feeds=true`, + ); + expect(results?.map((row) => row.slug)).toEqual([ + 'washington-township-123456', + 'washington-township-123457', + ]); + }); + + it('pages children and rejects unsupported parameters', () => { + const quebec = at('canada/quebec'); + const all = locations(`parent_location_id=${quebec.location_id}`); + const second = locations( + `parent_location_id=${quebec.location_id}&limit=2&offset=2`, + ); + expect(second.total).toBe(all.total); + expect(second.results).toEqual(all.results?.slice(2, 4)); + expect(all.results?.[0].feed_counts).toBeUndefined(); + expect(getMockLocations(new URLSearchParams('sort=name')).status).toBe(400); + expect(getMockLocations(new URLSearchParams('limit=101')).status).toBe(400); }); - it('paginates feeds, most relevant to the node first', () => { - const query = { - continent: 'north-america', - country: 'canada', - subdivision: 'quebec', - }; - const first = getMockDirectoryFeeds(query, 20, 0); - const second = getMockDirectoryFeeds(query, 20, 20); - if (first.status !== 200 || second.status !== 200) { - throw new Error('expected 200'); - } - expect(first.body.results).toHaveLength(20); - expect(second.body.results?.length).toBe((first.body.total ?? 0) - 20); - // Feeds declared at the Québec level outrank municipality-level ones. - expect(first.body.results?.[0].locations?.[0].municipality).toBeUndefined(); + it('routes location searches only', () => { + expect(isLocationSearch(new URLSearchParams('location_id=1'))).toBe(true); + expect(isLocationSearch(new URLSearchParams('continent=europe'))).toBe( + true, + ); + expect(isLocationSearch(new URLSearchParams('status=active'))).toBe(false); + }); + + it('paginates the feeds of a location, most relevant first', () => { + const montreal = at('canada/quebec/montreal'); + const query = `location_id=${montreal.location_id}&sort=location&limit=20`; + const first = feeds(query); + const second = feeds(`${query}&offset=20`); + expect(first.total).toBe(22); + expect(first.results).toHaveLength(20); + expect(second.results).toHaveLength(2); + // The commuter train also serves Laval and Longueuil: least relevant. + expect(second.results[1].feed_name).toBe('Commuter trains'); + }); + + it('lists the feeds of a continent and rejects sort=location alone', () => { + expect(feeds('continent=europe&sort=location').total).toBe(3); + expect(feeds('continent=asia').total).toBe(0); + expect( + getMockLocationFeeds(new URLSearchParams('sort=location')).status, + ).toBe(400); }); }); diff --git a/src/mocks/locationDirectory.ts b/src/mocks/locationDirectory.ts index 56d6601f..04ec71e4 100644 --- a/src/mocks/locationDirectory.ts +++ b/src/mocks/locationDirectory.ts @@ -1,68 +1,165 @@ /** * Mock data and logic for the location directory endpoints: - * GET /v1/locations/directory - * GET /v1/search with location parameters (the feeds of a node) + * GET /v1/locations (continents and geopolygon locations) + * GET /v1/search with `continent` / `location_id` (the feeds of a location) * - * The directory tree, the rolled-up counts, the breadcrumb and the children - * are all derived from MOCK_FEEDS' declared locations, so the mock behaves - * like the API: a feed counts once per node, 400 on a broken hierarchy, 404 - * when nothing is located there, feeds sorted by relevance to the node. - * Feed ids, URLs and names are fictional mock data. + * Locations form a tree of variable depth (Los Angeles sits under a county, + * San Francisco directly under California). Feed counts, `has_feeds` and the + * `sort=location` relevance are derived from MOCK_FEEDS' stop locations, so + * the mock behaves like the API: a feed counts once per location, sub-areas + * included. Location ids, feed ids, URLs and names are fictional mock data. */ import type { components } from '../app/services/feeds/types'; type Feed = components['schemas']['SearchFeedItemResult']; -type DirectoryNode = components['schemas']['LocationDirectoryNode']; -type DirectoryLevel = components['schemas']['LocationDirectoryLevel']; -type FeedCounts = components['schemas']['LocationDirectoryFeedCounts']; -type DirectoryResponse = components['schemas']['LocationDirectoryResponse']; +type LocationResult = components['schemas']['LocationSearchResult']; +type FeedCounts = components['schemas']['LocationFeedCounts']; +type LocationsResponse = components['schemas']['LocationSearchResponse']; interface FeedsResponse { total: number; results: Feed[]; } -const CONTINENTS: Record = { - africa: { code: 'AF', name: 'Africa' }, - europe: { code: 'EU', name: 'Europe' }, - 'north-america': { code: 'NA', name: 'North America' }, - oceania: { code: 'OC', name: 'Oceania' }, -}; - -const COUNTRIES: Record = { - AU: { name: 'Australia', continent: 'oceania' }, - CA: { name: 'Canada', continent: 'north-america' }, - DE: { name: 'Germany', continent: 'europe' }, - FR: { name: 'France', continent: 'europe' }, - US: { name: 'United States', continent: 'north-america' }, - ZA: { name: 'South Africa', continent: 'africa' }, -}; +interface Continent { + slug: string; + code: string; + name: string; +} + +const CONTINENTS: Continent[] = [ + { slug: 'africa', code: 'AF', name: 'Africa' }, + { slug: 'antarctica', code: 'AN', name: 'Antarctica' }, + { slug: 'europe', code: 'EU', name: 'Europe' }, + { slug: 'north-america', code: 'NA', name: 'North America' }, + { slug: 'oceania', code: 'OC', name: 'Oceania' }, +]; + +type PlaceType = 'country' | 'subdivision' | 'municipality'; + +interface Place { + id: number; + parent: number | null; + type: PlaceType; + name: string; + /** ISO 3166-1 (countries) or ISO 3166-2 (subdivisions) code. */ + code?: string; + /** Countries only. */ + continent?: string; +} + +const country = ( + id: number, + name: string, + code: string, + continent: string, +): Place => ({ id, parent: null, type: 'country', name, code, continent }); +const subdivision = ( + id: number, + parent: number, + name: string, + code: string, +): Place => ({ id, parent, type: 'subdivision', name, code }); +const municipality = (id: number, parent: number, name: string): Place => ({ + id, + parent, + type: 'municipality', + name, +}); + +export const MOCK_PLACES: Place[] = [ + country(100, 'Canada', 'CA', 'north-america'), + subdivision(110, 100, 'Québec', 'CA-QC'), + municipality(111, 110, 'Montréal'), + municipality(112, 110, 'Laval'), + municipality(113, 110, 'Longueuil'), + municipality(114, 110, 'Québec'), + subdivision(120, 100, 'Ontario', 'CA-ON'), + municipality(121, 120, 'Toronto'), + subdivision(130, 100, 'British Columbia', 'CA-BC'), + municipality(131, 130, 'Vancouver'), + country(200, 'United States', 'US', 'north-america'), + subdivision(210, 200, 'California', 'US-CA'), + // Extra intermediate level: county > city. + municipality(211, 210, 'Los Angeles County'), + municipality(212, 211, 'Los Angeles'), + municipality(213, 211, 'Pasadena'), + municipality(214, 210, 'San Francisco'), + subdivision(220, 200, 'New York', 'US-NY'), + municipality(221, 220, 'New York'), + subdivision(230, 200, 'Ohio', 'US-OH'), + // Siblings sharing a name: both slugs get `-`. + municipality(123456, 230, 'Washington Township'), + municipality(123457, 230, 'Washington Township'), + country(300, 'France', 'FR', 'europe'), + subdivision(310, 300, 'Île-de-France', 'FR-IDF'), + municipality(311, 310, 'Paris'), + country(400, 'Germany', 'DE', 'europe'), + subdivision(410, 400, 'Berlin', 'DE-BE'), + municipality(411, 410, 'Berlin'), + country(500, 'Australia', 'AU', 'oceania'), + subdivision(510, 500, 'New South Wales', 'AU-NSW'), + municipality(511, 510, 'Sydney'), + country(600, 'South Africa', 'ZA', 'africa'), + subdivision(610, 600, 'Western Cape', 'ZA-WC'), + municipality(611, 610, 'Cape Town'), +]; + +const PLACES_BY_ID = new Map(MOCK_PLACES.map((place) => [place.id, place])); /** Same slug rule as the API: `Québec` -> `quebec`. */ export function slugify(name: string): string { return name .normalize('NFD') - .replace(/[̀-ͯ]/g, '') + .replace(/\p{Diacritic}/gu, '') .toLowerCase() - .replace(/[^a-z0-9]+/g, '-') - .replace(/^-+|-+$/g, ''); + .replace(/[^a-z0-9]+/g, '-'); } -/** ISO code of a country slug (`united-states` -> `US`), like the API. */ -function countryCodeOf(slug: string): string | undefined { - return Object.keys(COUNTRIES).find( - (code) => slugify(COUNTRIES[code].name) === slug.toLowerCase(), +/** Slug among siblings, with `-` when a sibling shares it. */ +function slugOf(place: Place): string { + const slug = slugify(place.name); + const collides = MOCK_PLACES.some( + (other) => + other.id !== place.id && + other.parent === place.parent && + slugify(other.name) === slug, + ); + return collides ? `${slug}-${place.id}` : slug; +} + +/** The place and its ancestors, from the country down. */ +function chainOf(place: Place): Place[] { + const chain: Place[] = []; + let current: Place | undefined = place; + while (current != undefined) { + chain.unshift(current); + current = + current.parent === null ? undefined : PLACES_BY_ID.get(current.parent); + } + return chain; +} + +function continentOf(place: Place): Continent | undefined { + const slug = chainOf(place)[0].continent; + return CONTINENTS.find((continent) => continent.slug === slug); +} + +function isWithin(placeId: number, ancestorId: number): boolean { + const place = PLACES_BY_ID.get(placeId); + return ( + place != undefined && chainOf(place).some(({ id }) => id === ancestorId) ); } -type Place = [countryCode: string, subdivision?: string, municipality?: string]; type FeedSeed = [ dataType: Feed['data_type'], provider: string, feedName: string, - places: Place[], + /** One entry per group of stops, all of equal weight. */ + stopPlaces: number[], ]; -const MONTREAL: Place = ['CA', 'Québec', 'Montréal']; +const MONTREAL = 111; const EXO_SECTORS = [ 'Chambly-Richelieu-Carignan', 'Haut-Saint-Laurent', @@ -80,21 +177,16 @@ const EXO_SECTORS = [ const FEED_SEEDS: FeedSeed[] = [ // Canada-wide - ['gtfs', 'Example Intercity Rail', 'National rail network', [['CA']]], - // Québec (subdivision level only) - ['gtfs', 'Example Coach Lines', 'Intercity coaches', [['CA', 'Québec']]], - ['gtfs_rt', 'Example Coach Lines', 'Trip updates', [['CA', 'Québec']]], - // Montréal: more than one page of feeds + ['gtfs', 'Example Intercity Rail', 'National rail network', [110, 120, 130]], + // Québec, stops not geolocated to a municipality + ['gtfs', 'Example Coach Lines', 'Intercity coaches', [110]], + ['gtfs_rt', 'Example Coach Lines', 'Trip updates', [110]], + // Montréal: 22 feeds, more than one page ['gtfs', 'Société de transport de Montréal', 'Bus and metro', [MONTREAL]], ['gtfs_rt', 'Société de transport de Montréal', 'Trip updates', [MONTREAL]], ['gtfs_rt', 'Société de transport de Montréal', 'Alerts', [MONTREAL]], ['gtfs', 'Réseau express métropolitain', 'REM light metro', [MONTREAL]], - [ - 'gtfs', - 'exo', - 'Commuter trains', - [MONTREAL, ['CA', 'Québec', 'Laval'], ['CA', 'Québec', 'Longueuil']], - ], + ['gtfs', 'exo', 'Commuter trains', [MONTREAL, 112, 113]], ['gtfs_rt', 'exo', 'Commuter trains - trip updates', [MONTREAL]], ...EXO_SECTORS.map( (sector): FeedSeed => ['gtfs', 'exo', `Buses - ${sector}`, [MONTREAL]], @@ -104,441 +196,341 @@ const FEED_SEEDS: FeedSeed[] = [ ['gbfs', 'Example Car Share', 'Montréal car share', [MONTREAL]], ['gtfs_rt', 'exo', 'Commuter trains - vehicle positions', [MONTREAL]], // Elsewhere in Québec - [ - 'gtfs', - 'Société de transport de Laval', - 'Buses', - [['CA', 'Québec', 'Laval']], - ], - [ - 'gtfs', - 'Réseau de transport de Longueuil', - 'Buses', - [['CA', 'Québec', 'Longueuil']], - ], - [ - 'gtfs', - 'Réseau de transport de la Capitale', - 'Buses', - [['CA', 'Québec', 'Québec']], - ], - [ - 'gtfs_rt', - 'Réseau de transport de la Capitale', - 'Vehicle positions', - [['CA', 'Québec', 'Québec']], - ], - // Ontario - [ - 'gtfs', - 'Example Regional Transit', - 'Regional rail and buses', - [['CA', 'Ontario']], - ], - [ - 'gtfs', - 'Toronto Transit Commission', - 'Surface and subway', - [['CA', 'Ontario', 'Toronto']], - ], - [ - 'gtfs_rt', - 'Toronto Transit Commission', - 'Trip updates', - [['CA', 'Ontario', 'Toronto']], - ], - ['gbfs', 'Bike Share Toronto', 'Bike share', [['CA', 'Ontario', 'Toronto']]], - // British Columbia - [ - 'gtfs', - 'Example Coast Transit', - 'Buses and SkyTrain', - [['CA', 'British Columbia', 'Vancouver']], - ], + ['gtfs', 'Société de transport de Laval', 'Buses', [112]], + ['gtfs', 'Réseau de transport de Longueuil', 'Buses', [113]], + ['gtfs', 'Réseau de transport de la Capitale', 'Buses', [114]], + ['gtfs_rt', 'Réseau de transport de la Capitale', 'Vehicle positions', [114]], + // Ontario and British Columbia + ['gtfs', 'Example Regional Transit', 'Regional rail and buses', [120, 121]], + ['gtfs', 'Toronto Transit Commission', 'Surface and subway', [121]], + ['gtfs_rt', 'Toronto Transit Commission', 'Trip updates', [121]], + ['gbfs', 'Bike Share Toronto', 'Bike share', [121]], + ['gtfs', 'Example Coast Transit', 'Buses and SkyTrain', [131]], // United States - [ - 'gtfs', - 'Example Metro Los Angeles', - 'Bus', - [['US', 'California', 'Los Angeles']], - ], - [ - 'gtfs', - 'Example Bay Area Rail', - 'Rapid transit', - [ - ['US', 'California', 'San Francisco'], - ['US', 'California', 'Oakland'], - ], - ], - [ - 'gtfs_rt', - 'Example Bay Area Rail', - 'Trip updates', - [['US', 'California', 'San Francisco']], - ], - [ - 'gbfs', - 'Example Bikes SF', - 'Bike share', - [['US', 'California', 'San Francisco']], - ], - [ - 'gtfs', - 'Example Metropolitan Transit', - 'Subway', - [['US', 'New York', 'New York']], - ], - [ - 'gtfs_rt', - 'Example Metropolitan Transit', - 'Subway trip updates', - [['US', 'New York', 'New York']], - ], + ['gtfs', 'Example Metro Los Angeles', 'Bus', [212, 213]], + ['gtfs_rt', 'Example Metro Los Angeles', 'Trip updates', [212]], + ['gtfs', 'Example County Transit', 'County buses', [211]], + ['gtfs', 'Example Bay Area Rail', 'Rapid transit', [214]], + ['gbfs', 'Example Bikes SF', 'Bike share', [214]], + ['gtfs', 'Example Metropolitan Transit', 'Subway', [221]], + ['gtfs_rt', 'Example Metropolitan Transit', 'Subway trip updates', [221]], + ['gtfs', 'Example Township Shuttle', 'Shuttle', [123456]], + ['gtfs', 'Example Township Dial-a-Ride', 'Dial-a-ride', [123457]], // Europe - [ - 'gtfs', - 'Example Île-de-France Mobilités', - 'Regional network', - [['FR', 'Île-de-France', 'Paris']], - ], - [ - 'gbfs', - 'Example Vélo Paris', - 'Bike share', - [['FR', 'Île-de-France', 'Paris']], - ], - [ - 'gtfs', - 'Example Verkehrsverbund Berlin', - 'Regional network', - [['DE', 'Berlin', 'Berlin']], - ], + ['gtfs', 'Example Île-de-France Mobilités', 'Regional network', [311]], + ['gbfs', 'Example Vélo Paris', 'Bike share', [311]], + ['gtfs', 'Example Verkehrsverbund Berlin', 'Regional network', [411]], // Oceania - [ - 'gtfs', - 'Example Transport NSW', - 'Sydney network', - [['AU', 'New South Wales', 'Sydney']], - ], - [ - 'gtfs_rt', - 'Example Transport NSW', - 'Trip updates', - [['AU', 'New South Wales', 'Sydney']], - ], + ['gtfs', 'Example Transport NSW', 'Sydney network', [511]], + ['gtfs_rt', 'Example Transport NSW', 'Trip updates', [511]], // Africa - [ - 'gtfs', - 'Example Cape Town Bus', - 'Bus rapid transit', - [['ZA', 'Western Cape', 'Cape Town']], - ], + ['gtfs', 'Example Cape Town Bus', 'Bus rapid transit', [611]], ]; -function toFeed( - [dataType, provider, feedName, places]: FeedSeed, +interface MockFeed { + feed: Feed; + stopPlaces: number[]; +} + +function declaredLocation( + placeId: number, +): NonNullable[number] { + const chain = chainOf(PLACES_BY_ID.get(placeId) as Place); + const municipalities = chain.filter(({ type }) => type === 'municipality'); + return { + country_code: chain[0].code, + country: chain[0].name, + subdivision_name: chain.find(({ type }) => type === 'subdivision')?.name, + municipality: municipalities[municipalities.length - 1]?.name, + }; +} + +function toMockFeed( + [dataType, provider, feedName, stopPlaces]: FeedSeed, index: number, -): Feed { +): MockFeed { const id = `mock-loc-${String(index + 1).padStart(3, '0')}`; return { - id, - data_type: dataType, - status: 'active', - official: index % 3 === 0, - seasonal: false, - provider, - feed_name: feedName, - external_ids: [{ external_id: id, source: 'mdb' }], - source_info: { - producer_url: `https://example.com/${id}/${dataType}`, - authentication_type: 0, + stopPlaces, + feed: { + id, + data_type: dataType, + status: 'active', + official: index % 3 === 0, + seasonal: false, + provider, + feed_name: feedName, + external_ids: [{ external_id: id, source: 'mdb' }], + source_info: { + producer_url: `https://example.com/${id}/${dataType}`, + authentication_type: 0, + }, + locations: stopPlaces.map(declaredLocation), + entity_types: dataType === 'gtfs_rt' ? ['tu', 'vp'] : undefined, + versions: dataType === 'gbfs' ? ['2.3'] : undefined, }, - locations: places.map(([countryCode, subdivision, municipality]) => ({ - country_code: countryCode, - country: COUNTRIES[countryCode].name, - subdivision_name: subdivision, - municipality, - })), - entity_types: dataType === 'gtfs_rt' ? ['tu', 'vp'] : undefined, - versions: dataType === 'gbfs' ? ['2.3'] : undefined, }; } -export const MOCK_FEEDS: Feed[] = FEED_SEEDS.map(toFeed); +const MOCK_FEEDS: MockFeed[] = FEED_SEEDS.map(toMockFeed); -export interface DirectoryQuery { +/** Where to look for feeds: a continent slug and/or a location id. */ +interface FeedScope { continent?: string; - /** Country slug, e.g. `canada`. */ - country?: string; - subdivision?: string; - municipality?: string; + locationId?: number; } -type FeedLocation = NonNullable[number]; - -/** Depth of a declared location: 1 country, 2 subdivision, 3 municipality. */ -function locationDepth(location: FeedLocation): number { - if (location.municipality != undefined) return 3; - if (location.subdivision_name != undefined) return 2; - return 1; -} - -function matches(location: FeedLocation, query: DirectoryQuery): boolean { - const country = COUNTRIES[location.country_code ?? '']; - if (country == undefined) return false; - if (query.continent != undefined && country.continent !== query.continent) - return false; - if ( - query.country != undefined && - slugify(country.name) !== query.country.toLowerCase() - ) - return false; - if ( - query.subdivision != undefined && - slugify(location.subdivision_name ?? '') !== query.subdivision - ) - return false; - if ( - query.municipality != undefined && - slugify(location.municipality ?? '') !== query.municipality - ) - return false; - return true; +/** Share of a feed's stop groups inside the scope, 0 when outside. */ +function shareIn({ stopPlaces }: MockFeed, scope: FeedScope): number { + const inside = stopPlaces.filter((placeId) => { + const place = PLACES_BY_ID.get(placeId) as Place; + if ( + scope.continent != undefined && + continentOf(place)?.slug !== scope.continent + ) { + return false; + } + return scope.locationId == undefined || isWithin(placeId, scope.locationId); + }); + return inside.length / stopPlaces.length; } -function feedsIn(query: DirectoryQuery): Feed[] { - return MOCK_FEEDS.filter((feed) => - (feed.locations ?? []).some((location) => matches(location, query)), - ); +function feedsIn(scope: FeedScope): MockFeed[] { + return MOCK_FEEDS.filter((feed) => shareIn(feed, scope) > 0); } -function countFeeds(feeds: Feed[]): FeedCounts { +function countFeeds(feeds: MockFeed[]): FeedCounts { + const count = (dataType: Feed['data_type']): number => + feeds.filter(({ feed }) => feed.data_type === dataType).length; return { - gtfs: feeds.filter((feed) => feed.data_type === 'gtfs').length, - gtfs_rt: feeds.filter((feed) => feed.data_type === 'gtfs_rt').length, - gbfs: feeds.filter((feed) => feed.data_type === 'gbfs').length, + gtfs: count('gtfs'), + gtfs_rt: count('gtfs_rt'), + gbfs: count('gbfs'), total: feeds.length, }; } -function levelOf(query: DirectoryQuery): DirectoryLevel { - if (query.municipality != undefined) return 'municipality'; - if (query.subdivision != undefined) return 'subdivision'; - if (query.country != undefined) return 'country'; - if (query.continent != undefined) return 'continent'; - return 'root'; +interface Row { + result: LocationResult; + scope: FeedScope; + depth: number; } -/** 400 when a parameter is missing its parent or the country is elsewhere. */ -function isValidHierarchy(query: DirectoryQuery): boolean { - if (query.country != undefined && query.continent == undefined) return false; - if (query.subdivision != undefined && query.country == undefined) - return false; - if (query.municipality != undefined && query.subdivision == undefined) - return false; - if (query.country != undefined) { - const country = COUNTRIES[countryCodeOf(query.country) ?? '']; - if (country != undefined && country.continent !== query.continent) - return false; - } - return true; +function continentRow(continent: Continent): Row { + return { + depth: 0, + scope: { continent: continent.slug }, + result: { + location_id: null, + parent_location_id: null, + name: continent.name, + alt_name: null, + location_type: 'continent', + continent_code: continent.code, + continent_slug: continent.slug, + continent_name: continent.name, + slug: continent.slug, + path_slugs: [], + path_names: [], + country_name: null, + country_code: null, + subdivision_name: null, + subdivision_code: null, + display_name: continent.name, + }, + }; } -function makeNode( - level: DirectoryLevel, - slug: string, - code: string | null, - name: string, - query: DirectoryQuery, -): DirectoryNode { +function placeRow(place: Place): Row { + const chain = chainOf(place); + const continent = continentOf(place); + const placeSubdivision = chain.find(({ type }) => type === 'subdivision'); return { - level, - slug, - code, - name, - feed_counts: countFeeds(feedsIn(query)), + depth: chain.length, + scope: { locationId: place.id }, + result: { + location_id: place.id, + parent_location_id: place.parent, + name: place.name, + alt_name: null, + location_type: place.type, + continent_code: continent?.code ?? null, + continent_slug: continent?.slug ?? null, + continent_name: continent?.name ?? null, + slug: slugOf(place), + path_slugs: chain.map(slugOf), + path_names: chain.map(({ name }) => name), + country_name: chain[0].name, + country_code: chain[0].code ?? null, + subdivision_name: placeSubdivision?.name ?? null, + subdivision_code: placeSubdivision?.code ?? null, + display_name: chain.map(({ name }) => name).join(', '), + }, }; } -function nodeFor( - query: DirectoryQuery, - displayName?: string, -): DirectoryNode | undefined { - const level = levelOf(query); - switch (level) { - case 'continent': { - const slug = query.continent ?? ''; - const continent = CONTINENTS[slug]; - return continent == undefined - ? undefined - : makeNode(level, slug, continent.code, continent.name, query); - } - case 'country': { - const code = countryCodeOf(query.country ?? ''); - if (code == undefined) return undefined; - const country = COUNTRIES[code]; - return makeNode(level, slugify(country.name), code, country.name, query); - } - case 'subdivision': - return makeNode( - level, - query.subdivision ?? '', - null, - displayName ?? query.subdivision ?? '', - query, - ); - case 'municipality': - return makeNode( - level, - query.municipality ?? '', - null, - displayName ?? query.municipality ?? '', - query, - ); - default: - return undefined; - } -} +const ROWS: Row[] = [ + ...CONTINENTS.map(continentRow), + ...MOCK_PLACES.map(placeRow), +]; -/** Original (accented) names of a subdivision/municipality, by slug. */ -function displayNameOf( - feeds: Feed[], - field: 'subdivision_name' | 'municipality', - slug: string, -): string | undefined { - for (const feed of feeds) { - for (const location of feed.locations ?? []) { - const value = location[field]; - if (value != undefined && slugify(value) === slug) return value; - } - } - return undefined; +export type MockResult = + | { status: 200; body: T } + | { status: 400; body: { detail: string } }; + +const badRequest = (detail: string): MockResult => ({ + status: 400, + body: { detail }, +}); + +function readPaging( + params: URLSearchParams, + maxLimit: number, +): { limit: number; offset: number } | null { + const limit = Number(params.get('limit') ?? String(maxLimit)); + const offset = Number(params.get('offset') ?? '0'); + if (!Number.isInteger(limit) || limit < 0 || limit > maxLimit) return null; + if (!Number.isInteger(offset) || offset < 0) return null; + return { limit, offset }; } -function childrenOf(query: DirectoryQuery): DirectoryNode[] { - const level = levelOf(query); - const children = new Map(); - for (const feed of feedsIn(query)) { - for (const location of feed.locations ?? []) { - if (!matches(location, query)) continue; - const countryCode = location.country_code ?? ''; - let childQuery: DirectoryQuery | undefined; - let name: string | undefined; - if (level === 'root') { - childQuery = { continent: COUNTRIES[countryCode].continent }; - } else if (level === 'continent') { - childQuery = { - ...query, - country: slugify(COUNTRIES[countryCode].name), - }; - } else if (level === 'country' && location.subdivision_name != null) { - name = location.subdivision_name; - childQuery = { ...query, subdivision: slugify(name) }; - } else if (level === 'subdivision' && location.municipality != null) { - name = location.municipality; - childQuery = { ...query, municipality: slugify(name) }; - } - if (childQuery == undefined) continue; - const key = JSON.stringify(childQuery); - if (!children.has(key)) { - const node = nodeFor(childQuery, name); - if (node != undefined) children.set(key, node); - } - } - } - return [...children.values()].sort((a, b) => - (a.name ?? '').localeCompare(b.name ?? ''), +function readContinent(params: URLSearchParams): string | undefined { + const value = params.get('continent')?.toLowerCase(); + if (value == undefined || value === '') return undefined; + // Slug or code, case-insensitive; unknown values match nothing. + return ( + CONTINENTS.find(({ slug, code }) => + [slug, code.toLowerCase()].includes(value), + )?.slug ?? `unknown:${value}` ); } -function breadcrumbOf(query: DirectoryQuery): DirectoryNode[] { - const all = feedsIn(query); - const steps: DirectoryQuery[] = []; - if (query.continent != undefined) steps.push({ continent: query.continent }); - if (query.country != undefined) - steps.push({ ...steps[0], country: query.country }); - if (query.subdivision != undefined) - steps.push({ ...steps[1], subdivision: query.subdivision }); - if (query.municipality != undefined) - steps.push({ ...steps[2], municipality: query.municipality }); - return steps.flatMap((step) => { - const level = levelOf(step); - const name = - level === 'subdivision' - ? displayNameOf(all, 'subdivision_name', step.subdivision ?? '') - : level === 'municipality' - ? displayNameOf(all, 'municipality', step.municipality ?? '') - : undefined; - const node = nodeFor(step, name); - return node == undefined ? [] : [node]; - }); -} +const normalize = (text: string): string => + text + .normalize('NFD') + .replace(/\p{Diacritic}/gu, '') + .toLowerCase(); -export type MockResult = - | { status: 200; body: T } - | { status: 400 | 404; body: { detail: string } }; +/** GET /v1/locations */ +export function getMockLocations( + params: URLSearchParams, +): MockResult { + const sort = params.get('sort') ?? 'admin_level'; + if (sort !== 'admin_level' && sort !== 'feed_count') { + return badRequest('Unsupported sort.'); + } + const paging = readPaging(params, 100); + if (paging === null) return badRequest('Invalid limit or offset.'); -export function readDirectoryQuery(params: URLSearchParams): DirectoryQuery { - const read = (key: string): string | undefined => { - const value = params.get(key); - return value == null || value === '' ? undefined : value; - }; - return { - continent: read('continent'), - country: read('country'), - subdivision: read('subdivision'), - municipality: read('municipality'), - }; -} + const locationType = params.get('location_type'); + const continent = readContinent(params); + const parentId = params.get('parent_location_id'); + const path = params.get('path')?.toLowerCase(); + const countryCode = params.get('country_code')?.toUpperCase(); + const subdivisionCode = params.get('subdivision_code')?.toUpperCase(); + const words = normalize(params.get('search_query') ?? '') + .split(/\s+/) + .filter((word) => word !== ''); + const hasFeeds = params.get('has_feeds') === 'true'; + const includeCounts = params.get('include_feed_counts') === 'true'; + + const rows = ROWS.map((row) => ({ + row, + counts: countFeeds(feedsIn(row.scope)), + })).filter(({ row: { result }, counts }) => { + if (locationType != null && result.location_type !== locationType) + return false; + if (continent != undefined && result.continent_slug !== continent) + return false; + if (parentId != null && String(result.parent_location_id) !== parentId) + return false; + if (path != undefined && (result.path_slugs ?? []).join('/') !== path) + return false; + if (countryCode != undefined && result.country_code !== countryCode) + return false; + if ( + subdivisionCode != undefined && + result.subdivision_code !== subdivisionCode + ) + return false; + const haystack = normalize(result.display_name ?? ''); + if (!words.every((word) => haystack.includes(word))) return false; + return !hasFeeds || (counts.total ?? 0) > 0; + }); + + rows.sort( + (a, b) => + (sort === 'feed_count' + ? (b.counts.total ?? 0) - (a.counts.total ?? 0) + : a.row.depth - b.row.depth) || + (a.row.result.display_name ?? '').localeCompare( + b.row.result.display_name ?? '', + ), + ); -export function getMockDirectory( - query: DirectoryQuery, -): MockResult { - if (!isValidHierarchy(query)) { - return { status: 400, body: { detail: 'Invalid location hierarchy.' } }; - } - const feeds = feedsIn(query); - if (feeds.length === 0) { - return { status: 404, body: { detail: 'No feed located there.' } }; - } return { status: 200, body: { - level: levelOf(query), - breadcrumb: breadcrumbOf(query), - feed_counts: countFeeds(feeds), - children: childrenOf(query), + total: rows.length, + results: rows + .slice(paging.offset, paging.offset + paging.limit) + .map(({ row, counts }) => + includeCounts ? { ...row.result, feed_counts: counts } : row.result, + ), }, }; } -export function getMockDirectoryFeeds( - query: DirectoryQuery, - limit: number, - offset: number, +/** True when a /v1/search request targets a location. */ +export function isLocationSearch(params: URLSearchParams): boolean { + return ( + params.has('continent') || + params.has('location_id') || + params.get('sort') === 'location' + ); +} + +/** GET /v1/search with `continent` and/or `location_id`. */ +export function getMockLocationFeeds( + params: URLSearchParams, ): MockResult { - if (!isValidHierarchy(query)) { - return { status: 400, body: { detail: 'Invalid location hierarchy.' } }; + const sort = params.get('sort') ?? 'created_at'; + const continent = readContinent(params); + const rawLocationId = params.get('location_id'); + const locationId = rawLocationId == null ? undefined : Number(rawLocationId); + if (locationId != undefined && !Number.isInteger(locationId)) { + return badRequest('Invalid location_id.'); } - const relevance = (feed: Feed): number => - Math.max( - ...(feed.locations ?? []) - .filter((location) => matches(location, query)) - .map(locationDepth), - ); - const sorted = feedsIn(query).sort( - (a, b) => - relevance(a) - relevance(b) || - (a.provider ?? '').localeCompare(b.provider ?? '') || - (a.feed_name ?? '').localeCompare(b.feed_name ?? '') || - a.id.localeCompare(b.id), + if (sort !== 'created_at' && sort !== 'location') { + return badRequest('Unsupported sort.'); + } + if ( + sort === 'location' && + continent == undefined && + locationId == undefined + ) { + return badRequest('sort=location requires continent or location_id.'); + } + const paging = readPaging(params, 3500); + if (paging === null) return badRequest('Invalid limit or offset.'); + + const scope: FeedScope = { continent, locationId }; + const sorted = feedsIn(scope).sort((a, b) => + sort === 'location' + ? shareIn(b, scope) - shareIn(a, scope) || + (a.feed.provider ?? '').localeCompare(b.feed.provider ?? '') || + (a.feed.feed_name ?? '').localeCompare(b.feed.feed_name ?? '') || + a.feed.id.localeCompare(b.feed.id) + : // Newest first: the mock ids grow with the creation order. + b.feed.id.localeCompare(a.feed.id), ); return { status: 200, body: { total: sorted.length, - results: sorted.slice(offset, offset + limit), + results: sorted + .slice(paging.offset, paging.offset + paging.limit) + .map(({ feed }) => feed), }, }; } From fe94bc210bddfc0099dcc12321f7d12934d68a83 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Thu, 5 Nov 2026 07:29:17 -0500 Subject: [PATCH 08/16] chore: regenerate API types for realtime feed locations The location filters and feed counts now locate GTFS Realtime feeds through the schedule feeds they reference; only the descriptions change. Co-Authored-By: Claude Opus 5.5 --- src/app/services/feeds/types.ts | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index c95abba7..8293329f 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -336,7 +336,8 @@ export interface paths { *
    * - `continent` restricts the results to feeds with stops in that continent, and `location_id` to feeds with * stops in that location of `/v1/locations`, sub-areas included. Feeds are matched through their - * reverse-geolocated stops, so a feed that was never geolocated does not match. Unknown values return no feed. + * reverse-geolocated stops, so a feed that was never geolocated does not match. A GTFS Realtime feed that was + * never geolocated matches the locations of the schedule feeds it references. Unknown values return no feed. * - To list the same feeds as a location's `feed_counts`, also pass `status=active,inactive,development,future`. * - `sort=location` orders the results by the share of each feed's stops inside the requested location instead * of by creation date. @@ -358,7 +359,7 @@ export interface paths { path?: never; cookie?: never; }; - /** @description Search locations (continents, countries, subdivisions and municipalities). Results can be filtered by a free-text query and narrowed to a specific continent, country, subdivision, parent location, path or location type. Matches are ordered from the broadest area to the most specific, and by relevance within each level, unless `sort=feed_count` is given.
    Feed counts (`include_feed_counts`, `has_feeds`, `sort=feed_count`) count distinct feeds with a status of `active`, `inactive`, `development` or `future` that have reverse-geolocated stops in the location, sub-areas included. Work-in-progress feeds are counted only for callers allowed to see them, as in `/v1/search`. To list a location's feeds, call `/v1/search` with its `location_id` (or `continent` for a continent), `status=active,inactive,development,future` and `sort=location`.
    Continents come from a fixed classification and are not geopolygons. They are only returned with `location_type=continent`; their `location_id`, `parent_location_id` and ISO fields are null, `slug` and `continent_slug` both hold the continent slug, and `path_names` and `path_slugs` are empty. */ + /** @description Search locations (continents, countries, subdivisions and municipalities). Results can be filtered by a free-text query and narrowed to a specific continent, country, subdivision, parent location, path or location type. Matches are ordered from the broadest area to the most specific, and by relevance within each level, unless `sort=feed_count` is given.
    Feed counts (`include_feed_counts`, `has_feeds`, `sort=feed_count`) count distinct feeds with a status of `active`, `inactive`, `development` or `future` that have reverse-geolocated stops in the location, sub-areas included. A GTFS Realtime feed that was never geolocated is counted in the locations of the schedule feeds it references. Work-in-progress feeds are counted only for callers allowed to see them, as in `/v1/search`. To list a location's feeds, call `/v1/search` with its `location_id` (or `continent` for a continent), `status=active,inactive,development,future` and `sort=location`.
    Continents come from a fixed classification and are not geopolygons. They are only returned with `location_type=continent`; their `location_id`, `parent_location_id` and ISO fields are null, `slug` and `continent_slug` both hold the continent slug, and `path_names` and `path_slugs` are empty. */ get: operations['getLocations']; put?: never; post?: never; @@ -1878,7 +1879,7 @@ export interface components { has_seal_query_param: boolean; /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ location_continent: string; - /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. */ + /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. A GTFS Realtime feed that was never geolocated takes the locations of the schedule feeds it references. */ location_id_query_param: number; /** @description Sort order of the results. `admin_level` (default): from the broadest area to the most specific, then by relevance to `search_query` when one is given, then by display name. `feed_count`: most feeds first, then by display name. */ locations_sort: 'admin_level' | 'feed_count'; @@ -2556,7 +2557,7 @@ export interface operations { license_tags?: components['parameters']['license_tags']; /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ continent?: components['parameters']['location_continent']; - /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. */ + /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. A GTFS Realtime feed that was never geolocated takes the locations of the schedule feeds it references. */ location_id?: components['parameters']['location_id_query_param']; /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent` or `location_id`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ sort?: components['parameters']['search_sort']; From c52c870699bf7b350b0d0909e412860526de44e0 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Thu, 5 Nov 2026 07:37:04 -0500 Subject: [PATCH 09/16] ci: bump cypress-io/github-action to v7 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/preview-pr.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/preview-pr.yml b/.github/workflows/preview-pr.yml index 6d80a398..8bb402cc 100644 --- a/.github/workflows/preview-pr.yml +++ b/.github/workflows/preview-pr.yml @@ -86,7 +86,7 @@ jobs: VERCEL_PROJECT_ID: ${{ env.VERCEL_PROJECT_ID }} - name: Cypress test - uses: cypress-io/github-action@v6 + uses: cypress-io/github-action@v7 with: start: yarn e2e:setup command: yarn e2e:run From 5e00f83d7705b587acddd11d5cd7116e4a6dc6d1 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Thu, 5 Nov 2026 08:51:34 -0500 Subject: [PATCH 10/16] chore: regenerate API types for the locations path description Co-Authored-By: Claude Opus 5.5 --- src/app/services/feeds/types.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index 8293329f..57d9ebdc 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -2626,7 +2626,7 @@ export interface operations { continent?: components['parameters']['location_continent']; /** @description Limit results to the direct children of this location (the next level down). */ parent_location_id?: number; - /** @description Return the location at this path: its `path_slugs` joined with `/`, from the country down, e.g. `canada/quebec/montreal`. Case-insensitive. Returns no result when no location has that path. */ + /** @description Return the location at this path: its `path_slugs` joined with `/`, from the country down, e.g. `canada/quebec/montreal`. Case-insensitive; leading and trailing slashes are ignored. Returns no result when no location has that path. */ path?: string; /** @description When true, only return locations with at least one feed (see the feed count rules above). */ has_feeds?: boolean; From d5cc04819e8d8f48f4acc1974f07955e4a07477b Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Fri, 6 Nov 2026 08:38:01 -0500 Subject: [PATCH 11/16] feat: build directory pages from the location lookup endpoint Every directory page now resolves its URL with /v1/locations/lookup?path=...&include=feed_counts,children and lists its feeds with /v1/search?location_path=..., both sent at the same time, so a page waits for one round trip. Continents are ordinary locations with negative ids, and a location's path is its URL after /locations/, so the continent special cases are gone. Empty feed pages are never cached, so an unknown URL leaves nothing in the data cache. Co-Authored-By: Claude Opus 5.5 --- .../locations/[[...location]]/page.tsx | 38 +- .../components/LocationChildrenGrid.tsx | 8 +- .../lib/location-directory-data.spec.ts | 294 ++++++------ .../locations/lib/location-directory-data.ts | 226 +++++---- .../locations/lib/location-directory.spec.ts | 196 ++++---- .../locations/lib/location-directory.ts | 126 ++--- src/app/services/feeds/index.ts | 90 +++- src/app/services/feeds/types.ts | 301 ++++++++++-- src/mocks/handlers.ts | 27 +- src/mocks/locationDirectory.spec.ts | 225 ++++++--- src/mocks/locationDirectory.ts | 429 +++++++++++------- 11 files changed, 1210 insertions(+), 750 deletions(-) diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx index 4e3b356a..f7b3fd63 100644 --- a/src/app/[locale]/locations/[[...location]]/page.tsx +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -16,10 +16,8 @@ import { buildPlaceName, FEEDS_SECTION_ID, getLocationName, - getLocationSegments, getPageCount, getTotalFeedCount, - type LocationPath, parseLocationSegments, parsePageParam, } from '../lib/location-directory'; @@ -37,7 +35,8 @@ interface PageProps { interface ParsedRequest { locale: string; - location: LocationPath; + /** URL segments: the location's API path slugs, continent first. */ + segments: string[]; page: number; } @@ -49,10 +48,10 @@ async function parseRequest({ const [{ locale, location: segments }, { page: rawPage }] = await Promise.all( [params, searchParams], ); - const location = parseLocationSegments(segments); + const slugs = parseLocationSegments(segments); const page = parsePageParam(rawPage); - if (location === null || page === null) return null; - return { locale, location, page }; + if (slugs === null || page === null) return null; + return { locale, segments: slugs, page }; } /** @@ -61,14 +60,10 @@ async function parseRequest({ * the page. */ async function fetchPageData({ - location, + segments, page, }: ParsedRequest): Promise { - const data = await fetchLocationPage( - page, - location.continent, - location.path.join('/'), - ); + const data = await fetchLocationPage(page, segments.join('/')); if (data === null || page > getPageCount(data.feeds.total ?? 0)) { return null; } @@ -104,11 +99,8 @@ export async function generateMetadata(props: PageProps): Promise { gtfs_rt: counts?.gtfs_rt ?? 0, gbfs: counts?.gbfs ?? 0, }); - const segments = - location === null || request.location.continent === undefined - ? [] - : getLocationSegments(request.location.continent, location); - const url = `${SITE_URL}${buildLocationHref(segments, page)}`; + // The URL is the location's API path. + const url = `${SITE_URL}${buildLocationHref(request.segments, page)}`; return { title, @@ -129,7 +121,7 @@ export default async function LocationsPage( ): Promise { const request = await parseRequest(props); if (request === null) notFound(); - const { locale, page } = request; + const { locale, page, segments } = request; setRequestLocale(locale); const [data, t, tCommon] = await Promise.all([ @@ -140,13 +132,11 @@ export default async function LocationsPage( if (data === null) notFound(); const { location, children, feeds } = data; - const continent = request.location.continent ?? ''; const isRoot = location === null; const total = feeds.total ?? 0; const pageCount = getPageCount(total); - const segments = isRoot ? [] : getLocationSegments(continent, location); const place = buildPlaceName(location); - const steps = buildBreadcrumbSteps(continent, location); + const steps = buildBreadcrumbSteps(location); const crumbs: Crumb[] = [ { label: tCommon('feeds'), href: '/feeds' }, @@ -218,11 +208,7 @@ export default async function LocationsPage( ({children.length}) - + ) : null} diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx index 13f110f2..e5eeb472 100644 --- a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -17,11 +17,6 @@ import { interface Props { locations: LocationResult[]; - /** - * Continent slug of the current page; empty at the root, where the - * children are the continents themselves. - */ - continent: string; locale: string; } @@ -44,7 +39,6 @@ function getFlag(location: LocationResult): string | undefined { */ export default async function LocationChildrenGrid({ locations, - continent, locale, }: Props): Promise { const t = await getTranslations('locations'); @@ -56,7 +50,7 @@ export default async function LocationChildrenGrid({ counts: location.feed_counts, })), ).map(({ location, name, counts }) => { - const href = buildLocationHref(getLocationSegments(continent, location)); + const href = buildLocationHref(getLocationSegments(location)); return { key: href, name, diff --git a/src/app/[locale]/locations/lib/location-directory-data.spec.ts b/src/app/[locale]/locations/lib/location-directory-data.spec.ts index c95cbc80..671863be 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.spec.ts @@ -31,6 +31,8 @@ jest.mock('next/cache', () => ({ })); const mockGetLocations = jest.fn(); +const mockGetLocationByPath = jest.fn(); +const mockGetLocationChildren = jest.fn(); const mockSearchFeeds = jest.fn(); jest.mock('../../../services/feeds', () => ({ @@ -42,6 +44,8 @@ jest.mock('../../../services/feeds', () => ({ } }, getLocations: (...args: unknown[]) => mockGetLocations(...args), + getLocationByPath: (...args: unknown[]) => mockGetLocationByPath(...args), + getLocationChildren: (...args: unknown[]) => mockGetLocationChildren(...args), searchFeeds: (...args: unknown[]) => mockSearchFeeds(...args), })); @@ -50,47 +54,45 @@ jest.mock('../../../utils/auth-server', () => ({ })); const STATUSES = ['active', 'inactive', 'development', 'future']; +const MONTREAL_PATH = 'north-america/canada/quebec/montreal'; const northAmerica = { - location_id: null, + location_id: -5, location_type: 'continent', name: 'North America', slug: 'north-america', - continent_slug: 'north-america', - path_slugs: [], + path: 'north-america', + path_slugs: ['north-america'], feed_counts: { total: 30 }, }; -const antarctica = { - ...northAmerica, - name: 'Antarctica', - slug: 'antarctica', - continent_slug: 'antarctica', - feed_counts: { total: 0 }, -}; const montreal = { location_id: 175905, location_type: 'municipality', name: 'Montréal', slug: 'montreal', - continent_slug: 'north-america', - path_slugs: ['canada', 'quebec', 'montreal'], + path: MONTREAL_PATH, + path_slugs: ['north-america', 'canada', 'quebec', 'montreal'], feed_counts: { total: 22 }, }; -const feeds = { total: 22, results: [] }; - -/** getLocations answers by query shape. */ -function answerLocations( - byQuery: (query: Record) => unknown, -): void { - mockGetLocations.mockImplementation(async (query: Record) => - byQuery(query), - ); +const feeds = { total: 22, results: [{ id: 'mdb-1' }] }; +const emptyFeeds = { total: 0, results: [] }; + +function child(index: number): typeof montreal { + return { + ...montreal, + location_id: index + 1, + slug: `child-${index + 1}`, + path: `${MONTREAL_PATH}/child-${index + 1}`, + }; } -function locationQueries(): Array> { - return mockGetLocations.mock.calls.map( - ([query]) => query as Record, - ); +/** The lookup answer: the location and the first page of its children. */ +function detail( + location: Record, + children: unknown[], + total: number = children.length, +): Record { + return { ...location, children: { total, results: children } }; } function searchQueries(): Array> { @@ -103,169 +105,164 @@ describe('fetchLocationPage', () => { beforeEach(() => { mockCacheStore.clear(); mockGetLocations.mockReset(); + mockGetLocationByPath.mockReset(); + mockGetLocationChildren.mockReset(); mockSearchFeeds.mockReset(); mockSearchFeeds.mockResolvedValue(feeds); }); it('lists the continents with feeds and the newest feeds at the root', async () => { - answerLocations(() => ({ total: 2, results: [northAmerica, antarctica] })); + mockGetLocations.mockResolvedValue({ total: 1, results: [northAmerica] }); const data = await fetchLocationPage(2); expect(data).toEqual({ location: null, children: [northAmerica], feeds }); - expect(locationQueries()).toEqual([ - { - location_type: 'continent', - include_feed_counts: true, - limit: 100, - offset: 0, - }, + expect(mockGetLocations.mock.calls).toEqual([ + [ + { + location_type: 'continent', + has_feeds: true, + include: ['feed_counts'], + sort: 'feed_count', + limit: 100, + offset: 0, + }, + 'guest-token', + ], ]); - expect(mockGetLocations.mock.calls[0][1]).toBe('guest-token'); expect(searchQueries()).toEqual([ { status: STATUSES, limit: 20, offset: 20 }, ]); + expect(mockGetLocationByPath).not.toHaveBeenCalled(); }); - it('lists the countries and feeds of a continent', async () => { + it('looks a continent up by path, like any other location', async () => { const canada = { ...montreal, location_type: 'country', slug: 'canada' }; - answerLocations((query) => - query.location_type === 'continent' - ? { total: 1, results: [northAmerica] } - : { total: 1, results: [canada] }, - ); + mockGetLocationByPath.mockResolvedValue(detail(northAmerica, [canada])); - const data = await fetchLocationPage(1, 'north-america', ''); + const data = await fetchLocationPage(1, 'north-america'); expect(data).toEqual({ location: northAmerica, children: [canada], feeds }); - expect(locationQueries()[1]).toEqual({ - continent: 'north-america', - location_type: 'country', - has_feeds: true, - include_feed_counts: true, - sort: 'feed_count', - limit: 100, - offset: 0, - }); expect(searchQueries()).toEqual([ { - continent: 'north-america', + location_path: 'north-america', sort: 'location', status: STATUSES, limit: 20, offset: 0, }, ]); + expect(mockGetLocations).not.toHaveBeenCalled(); }); - it('is null for an unknown continent, without listing anything', async () => { - answerLocations(() => ({ total: 1, results: [northAmerica] })); - - await expect(fetchLocationPage(1, 'atlantis', '')).resolves.toBeNull(); - expect(mockGetLocations).toHaveBeenCalledTimes(1); - expect(mockSearchFeeds).not.toHaveBeenCalled(); - }); - - it('resolves a deeper location by path, then its children and feeds', async () => { - const child = { ...montreal, location_id: 1, slug: 'ville-marie' }; - answerLocations((query) => - query.path !== undefined - ? { total: 1, results: [montreal] } - : { total: 1, results: [child] }, + it('fetches the location, its children and its feeds in parallel', async () => { + let resolveLookup: (value: unknown) => void = () => {}; + mockGetLocationByPath.mockReturnValue( + new Promise((resolve) => { + resolveLookup = resolve; + }), ); - const data = await fetchLocationPage( - 3, - 'north-america', - 'canada/quebec/montreal', - ); - - expect(data).toEqual({ location: montreal, children: [child], feeds }); - expect(locationQueries()).toEqual([ - { - continent: 'north-america', - path: 'canada/quebec/montreal', - include_feed_counts: true, - limit: 1, - }, - { - parent_location_id: 175905, - has_feeds: true, - include_feed_counts: true, - sort: 'feed_count', - limit: 100, - offset: 0, - }, - ]); + const pending = fetchLocationPage(3, MONTREAL_PATH); + // The feeds are requested before the lookup answers. + await new Promise((resolve) => setTimeout(resolve, 0)); expect(searchQueries()).toEqual([ { - location_id: 175905, + location_path: MONTREAL_PATH, sort: 'location', status: STATUSES, limit: 20, offset: 40, }, ]); - }); + resolveLookup(detail(montreal, [child(0)])); - it('pages through every child location', async () => { - const children = Array.from({ length: 230 }, (_, index) => ({ - ...montreal, - location_id: index + 1, - slug: `child-${index + 1}`, - })); - answerLocations((query) => { - if (query.path !== undefined) return { total: 1, results: [montreal] }; - const offset = query.offset as number; - const limit = query.limit as number; - return { total: 230, results: children.slice(offset, offset + limit) }; + await expect(pending).resolves.toEqual({ + location: montreal, + children: [child(0)], + feeds, }); + expect(mockGetLocationByPath.mock.calls).toEqual([ + [ + { + path: MONTREAL_PATH, + include: ['feed_counts', 'children'], + has_feeds: true, + sort: 'feed_count', + limit: 100, + }, + 'guest-token', + ], + ]); + expect(mockGetLocationChildren).not.toHaveBeenCalled(); + }); - const data = await fetchLocationPage( - 1, - 'north-america', - 'canada/quebec/montreal', + it('pages through the children beyond the first 100', async () => { + const children = Array.from({ length: 230 }, (_, index) => child(index)); + mockGetLocationByPath.mockResolvedValue( + detail(montreal, children.slice(0, 100), 230), + ); + mockGetLocationChildren.mockImplementation( + async (_id: number, query: { offset: number; limit: number }) => ({ + total: 230, + results: children.slice(query.offset, query.offset + query.limit), + }), ); + const data = await fetchLocationPage(1, MONTREAL_PATH); + expect(data?.children).toEqual(children); - expect( - locationQueries() - .slice(1) - .map(({ offset, limit }) => [offset, limit]), - ).toEqual([ - [0, 100], - [100, 100], - [200, 100], + expect(mockGetLocationChildren.mock.calls).toEqual([ + [ + 175905, + { + has_feeds: true, + include: ['feed_counts'], + sort: 'feed_count', + limit: 100, + offset: 100, + }, + 'guest-token', + ], + [ + 175905, + { + has_feeds: true, + include: ['feed_counts'], + sort: 'feed_count', + limit: 100, + offset: 200, + }, + 'guest-token', + ], ]); }); - it('is null when no location has the path, and never caches the miss', async () => { - answerLocations(() => ({ total: 0, results: [] })); - await expect( - fetchLocationPage(1, 'north-america', 'canada/quebec/montreal'), - ).resolves.toBeNull(); - expect(mockSearchFeeds).not.toHaveBeenCalled(); - - answerLocations((query) => - query.path !== undefined - ? { total: 1, results: [montreal] } - : { total: 0, results: [] }, - ); - await expect( - fetchLocationPage(1, 'north-america', 'canada/quebec/montreal'), - ).resolves.toMatchObject({ location: montreal }); + it('is null when the lookup is a 404, and never caches the miss', async () => { + mockSearchFeeds.mockResolvedValue(emptyFeeds); + mockGetLocationByPath.mockRejectedValueOnce(new ApiError('Not Found', 404)); + await expect(fetchLocationPage(1, MONTREAL_PATH)).resolves.toBeNull(); + // Nothing cached for the unknown path, not even its empty feed page. + expect(mockCacheStore.size).toBe(0); + + mockSearchFeeds.mockResolvedValue(feeds); + mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); + await expect(fetchLocationPage(1, MONTREAL_PATH)).resolves.toMatchObject({ + location: montreal, + feeds, + }); }); - it('is null when the result is not at the requested continent or path', async () => { - answerLocations(() => ({ total: 1, results: [montreal] })); + it('never caches an empty feed page', async () => { + mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); + mockSearchFeeds.mockResolvedValue(emptyFeeds); - // The API accepts continent codes too; only slugs are valid URLs. - await expect( - fetchLocationPage(1, 'na', 'canada/quebec/montreal'), - ).resolves.toBeNull(); - await expect( - fetchLocationPage(1, 'north-america', 'canada/quebec'), - ).resolves.toBeNull(); + await expect(fetchLocationPage(9, MONTREAL_PATH)).resolves.toMatchObject({ + feeds: emptyFeeds, + }); + await fetchLocationPage(9, MONTREAL_PATH); + expect(mockSearchFeeds).toHaveBeenCalledTimes(2); + expect(mockGetLocationByPath).toHaveBeenCalledTimes(1); }); it('resolves a 400 or 404 to null without caching it', async () => { @@ -287,22 +284,25 @@ describe('fetchLocationPage', () => { }); it('caches a found location', async () => { - answerLocations((query) => - query.path !== undefined - ? { total: 1, results: [montreal] } - : { total: 0, results: [] }, - ); + mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); - await fetchLocationPage(1, 'north-america', 'canada/quebec/montreal'); - await fetchLocationPage(2, 'north-america', 'canada/quebec/montreal'); - // Location and children once; one feed page each. - expect(mockGetLocations).toHaveBeenCalledTimes(2); + await fetchLocationPage(1, MONTREAL_PATH); + await fetchLocationPage(2, MONTREAL_PATH); + await fetchLocationPage(2, MONTREAL_PATH); + // The location once; one call per feed page. + expect(mockGetLocationByPath).toHaveBeenCalledTimes(1); expect(mockSearchFeeds).toHaveBeenCalledTimes(2); }); it('rethrows other API errors', async () => { mockGetLocations.mockRejectedValueOnce(new ApiError('Server Error', 500)); - await expect(fetchLocationPage(1)).rejects.toThrow('Server Error'); + + mockGetLocationByPath.mockRejectedValueOnce( + new ApiError('Server Error', 500), + ); + await expect(fetchLocationPage(1, MONTREAL_PATH)).rejects.toThrow( + 'Server Error', + ); }); }); diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index 4711ce50..09ca4544 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -11,18 +11,19 @@ import { unstable_cache } from 'next/cache'; import { getGuestGcipIdToken } from '../../../utils/auth-server'; import { ApiError, + getLocationByPath, + getLocationChildren, getLocations, searchFeeds, - type LocationsParams, + type LocationChildrenParams, type SearchFeedsResponse, } from '../../../services/feeds'; import { fetchAllPages, - getContinentSlug, + fetchRemainingPages, getPageOffset, - getTotalFeedCount, - isLocationAtPath, LOCATION_FEEDS_PAGE_SIZE, + LOCATIONS_API_PAGE_SIZE, type LocationResult, } from './location-directory'; @@ -40,10 +41,10 @@ const DIRECTORY_FEED_STATUSES: Array< > = ['active', 'inactive', 'development', 'future']; /** - * A URL that does not exist: a 400/404 from the API, or no location at the - * requested path. Thrown inside the cached functions because unstable_cache - * never stores a thrown error: caching the miss would keep a location missing - * for hours after it starts to exist. + * A URL that does not exist: a 400/404 from the API (an unknown path is a + * 404 from the lookup). Thrown inside the cached functions because + * unstable_cache never stores a thrown error: caching the miss would keep a + * location missing for hours after it starts to exist. */ class LocationNotFoundError extends Error {} @@ -79,108 +80,105 @@ async function nullWhenMissing( } } -/** Every page of `GET /v1/locations` for the query (100 per call). */ -async function getAllLocations( - query: LocationsParams, - accessToken: string, -): Promise { - return await fetchAllPages( - async (offset, limit) => - await requireData( - async () => - await getLocations({ ...query, limit, offset }, accessToken), - ), - ); +/** Children with feeds, most feeds first, with their counts. */ +function childrenQuery(): Required< + Pick +> { + return { has_feeds: true, include: ['feed_counts'], sort: 'feed_count' }; } // unstable_cache keys on the key parts plus the call arguments, so the // arguments are kept primitive. +/** The continents with feeds, most feeds first (every page). */ const cachedContinents = unstable_cache( async (): Promise => { const accessToken = await getGuestGcipIdToken(); - return await getAllLocations( - { location_type: 'continent', include_feed_counts: true }, - accessToken, + return await fetchAllPages( + async (offset, limit) => + await requireData( + async () => + await getLocations( + { ...childrenQuery(), location_type: 'continent', limit, offset }, + accessToken, + ), + ), ); }, ['location-directory-continents'], CACHE_OPTIONS, ); -/** The location at `continent/path`; throws when there is none. */ +interface LocationWithChildren { + location: LocationResult; + /** Every direct child with feeds, most feeds first. */ + children: LocationResult[]; +} + +/** + * The location at `path` and its children with feeds: one lookup holds the + * location and the first 100 children, the remaining children pages are + * then fetched in parallel. Throws when no location has that path. + */ const cachedLocation = unstable_cache( - async (continent: string, path: string): Promise => { + async (path: string): Promise => { const accessToken = await getGuestGcipIdToken(); - const response = await requireData( + const { children: firstPage, ...location } = await requireData( async () => - await getLocations( - { continent, path, include_feed_counts: true, limit: 1 }, + await getLocationByPath( + { + ...childrenQuery(), + path, + include: ['feed_counts', 'children'], + limit: LOCATIONS_API_PAGE_SIZE, + }, accessToken, ), ); - const location = response.results?.[0]; - if ( - location == undefined || - location.location_id == undefined || - !isLocationAtPath(location, continent, path.split('/')) - ) { - throw new LocationNotFoundError(`No location at ${continent}/${path}`); - } - return location; + const locationId = location.location_id; + const children = await fetchRemainingPages( + firstPage ?? {}, + async (offset, limit) => + await requireData( + async () => + await getLocationChildren( + locationId, + { ...childrenQuery(), limit, offset }, + accessToken, + ), + ), + ); + return { location, children }; }, ['location-directory-location'], CACHE_OPTIONS, ); -const CHILDREN_QUERY = { - has_feeds: true, - include_feed_counts: true, - sort: 'feed_count', -} as const satisfies LocationsParams; - -const cachedCountries = unstable_cache( - async (continent: string): Promise => { - const accessToken = await getGuestGcipIdToken(); - return await getAllLocations( - { ...CHILDREN_QUERY, continent, location_type: 'country' }, - accessToken, - ); - }, - ['location-directory-countries'], - CACHE_OPTIONS, -); +/** + * Carries a feed page without results out of unstable_cache without storing + * it: an unknown path, a page past the last one or a location without feeds. + * The feeds are fetched in parallel with the location, so caching empty + * pages would let any URL add entries to the data cache. + */ +class UncachedFeedsPage extends Error { + readonly feeds: SearchFeedsResponse; -const cachedSubLocations = unstable_cache( - async (parentLocationId: number): Promise => { - const accessToken = await getGuestGcipIdToken(); - return await getAllLocations( - { ...CHILDREN_QUERY, parent_location_id: parentLocationId }, - accessToken, - ); - }, - ['location-directory-sub-locations'], - CACHE_OPTIONS, -); + constructor(feeds: SearchFeedsResponse) { + super('Empty feed page'); + this.feeds = feeds; + } +} /** - * One page of feeds: newest first at the root (no location), otherwise most - * relevant to the continent or location first. + * One page of feeds: newest first at the root (`path` null), otherwise most + * relevant to the location at `path` first. */ const cachedFeeds = unstable_cache( - async ( - offset: number, - continent: string | null, - locationId: number | null, - ): Promise => { + async (offset: number, path: string | null): Promise => { const accessToken = await getGuestGcipIdToken(); const location = - locationId !== null - ? { location_id: locationId, sort: 'location' as const } - : continent !== null - ? { continent, sort: 'location' as const } - : {}; - return await requireData( + path !== null ? { location_path: path, sort: 'location' as const } : {}; + const feeds = await requireData( async () => await searchFeeds( { @@ -194,11 +192,25 @@ const cachedFeeds = unstable_cache( accessToken, ), ); + if ((feeds.results ?? []).length === 0) throw new UncachedFeedsPage(feeds); + return feeds; }, ['location-directory-feeds'], CACHE_OPTIONS, ); +async function fetchFeeds( + offset: number, + path: string | null, +): Promise { + try { + return await cachedFeeds(offset, path); + } catch (error) { + if (error instanceof UncachedFeedsPage) return error.feeds; + throw error; + } +} + export interface LocationPageData { /** The current location; null at the root. */ location: LocationResult | null; @@ -208,66 +220,38 @@ export interface LocationPageData { feeds: SearchFeedsResponse; } +/** + * The location (with its children) and the feed page are fetched in + * parallel from the path alone, in one round trip. + */ async function loadLocationPage( page: number, - continent: string | undefined, path: string, ): Promise { const offset = getPageOffset(page); - if (continent === undefined) { + if (path === '') { const [continents, feeds] = await Promise.all([ cachedContinents(), - cachedFeeds(offset, null, null), - ]); - // Children deeper down are fetched with `has_feeds`; continents are not, - // so that an empty continent still resolves. - const children = continents.filter( - (continent) => getTotalFeedCount(continent.feed_counts) > 0, - ); - return { location: null, children, feeds }; - } - - if (path === '') { - // Resolve the continent before listing its countries and feeds, so an - // unknown slug is a 404 and never adds entries to the data cache. - const continents = await cachedContinents(); - const location = continents.find( - (candidate) => getContinentSlug(candidate) === continent, - ); - if (location == undefined) { - throw new LocationNotFoundError(`Unknown continent ${continent}`); - } - const [children, feeds] = await Promise.all([ - cachedCountries(continent), - cachedFeeds(offset, continent, null), + fetchFeeds(offset, null), ]); - return { location, children, feeds }; + return { location: null, children: continents, feeds }; } - const location = await cachedLocation(continent, path); - const locationId = location.location_id ?? 0; - const [children, feeds] = await Promise.all([ - cachedSubLocations(locationId), - cachedFeeds(offset, null, locationId), + const [{ location, children }, feeds] = await Promise.all([ + cachedLocation(path), + fetchFeeds(offset, path), ]); return { location, children, feeds }; } /** * Everything a directory page shows, or null when the location does not - * exist. `path` is the location's path slugs joined with `/` (empty at the - * root and on a continent page). React cache() dedupes the generateMetadata - * and page calls within one request; it compares arguments by identity, - * hence primitives. + * exist. `path` is the location's API path, continent first (empty at the + * root). React cache() dedupes the generateMetadata and page calls within + * one request; it compares arguments by identity, hence primitives. */ export const fetchLocationPage = cache( - async ( - page: number, - continent?: string, - path: string = '', - ): Promise => - await nullWhenMissing( - async () => await loadLocationPage(page, continent, path), - ), + async (page: number, path: string = ''): Promise => + await nullWhenMissing(async () => await loadLocationPage(page, path)), ); diff --git a/src/app/[locale]/locations/lib/location-directory.spec.ts b/src/app/[locale]/locations/lib/location-directory.spec.ts index 063996d6..99c03998 100644 --- a/src/app/[locale]/locations/lib/location-directory.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory.spec.ts @@ -3,16 +3,15 @@ import { buildLocationHref, buildPlaceName, fetchAllPages, + fetchRemainingPages, filterByName, formatCount, - getContinentSlug, getFeedCountEntries, getLocationName, getLocationSegments, getPageCount, getPageOffset, getTotalFeedCount, - isLocationAtPath, type LocationResult, normalizeLocationName, parseLocationSegments, @@ -21,15 +20,15 @@ import { } from './location-directory'; const northAmerica: LocationResult = { - location_id: null, + location_id: -5, parent_location_id: null, location_type: 'continent', + continent_code: 'NA', name: 'North America', slug: 'north-america', - continent_slug: 'north-america', - continent_name: 'North America', - path_slugs: [], - path_names: [], + path: 'north-america', + path_slugs: ['north-america'], + path_names: ['North America'], }; // Variable depth: Montréal sits under an intermediate region. @@ -37,46 +36,69 @@ const montreal: LocationResult = { location_id: 175905, parent_location_id: 161950, location_type: 'municipality', + continent_code: 'NA', name: 'Montréal', slug: 'montreal', - continent_slug: 'north-america', - continent_name: 'North America', - path_slugs: ['canada', 'quebec', 'montreal-region', 'montreal'], - path_names: ['Canada', 'Québec', 'Montréal (region)', 'Montréal'], + path: 'north-america/canada/quebec/montreal-region/montreal', + path_slugs: [ + 'north-america', + 'canada', + 'quebec', + 'montreal-region', + 'montreal', + ], + path_names: [ + 'North America', + 'Canada', + 'Québec', + 'Montréal (region)', + 'Montréal', + ], }; const canada: LocationResult = { location_id: 1, - parent_location_id: null, + parent_location_id: -5, location_type: 'country', + continent_code: 'NA', name: 'Canada', slug: 'canada', - continent_slug: 'north-america', - continent_name: 'North America', - path_slugs: ['canada'], - path_names: ['Canada'], + path: 'north-america/canada', + path_slugs: ['north-america', 'canada'], + path_names: ['North America', 'Canada'], +}; + +// A country without continent in the classification. +const clipperton: LocationResult = { + location_id: 2, + parent_location_id: null, + location_type: 'country', + continent_code: null, + name: 'Clipperton', + slug: 'clipperton', + path: 'clipperton', + path_slugs: ['clipperton'], + path_names: ['Clipperton'], }; describe('parseLocationSegments', () => { - it('returns an empty path at the root', () => { - expect(parseLocationSegments(undefined)).toEqual({ path: [] }); - expect(parseLocationSegments([])).toEqual({ path: [] }); + it('returns no slugs at the root', () => { + expect(parseLocationSegments(undefined)).toEqual([]); + expect(parseLocationSegments([])).toEqual([]); }); - it('splits the continent from the path slugs, at any depth', () => { - expect(parseLocationSegments(['north-america'])).toEqual({ - continent: 'north-america', - path: [], - }); - expect(parseLocationSegments(['north-america', 'canada'])).toEqual({ - continent: 'north-america', - path: ['canada'], - }); - const deep = ['canada', 'quebec', 'montreal-region', 'montreal', 'a', 'b']; - expect(parseLocationSegments(['north-america', ...deep])).toEqual({ - continent: 'north-america', - path: deep, - }); + it('keeps every slug, continent first, at any depth', () => { + expect(parseLocationSegments(['north-america'])).toEqual(['north-america']); + const deep = [ + 'north-america', + 'canada', + 'quebec', + 'montreal-region', + 'montreal', + 'a', + ]; + expect(parseLocationSegments(deep)).toEqual(deep); + expect(parseLocationSegments(['clipperton'])).toEqual(['clipperton']); }); it('accepts collision suffixes and non-Latin lowercase slugs', () => { @@ -86,15 +108,20 @@ describe('parseLocationSegments', () => { 'united-states', 'ohio', 'washington-township-123456', - ])?.path, - ).toEqual(['united-states', 'ohio', 'washington-township-123456']); - expect(parseLocationSegments(['asia', '東京'])?.path).toEqual(['東京']); + ]), + ).toEqual([ + 'north-america', + 'united-states', + 'ohio', + 'washington-township-123456', + ]); + expect(parseLocationSegments(['asia', '東京'])).toEqual(['asia', '東京']); }); it('decodes percent-encoded segments', () => { - expect( - parseLocationSegments(['asia', encodeURIComponent('東京')])?.path, - ).toEqual(['東京']); + expect(parseLocationSegments(['asia', encodeURIComponent('東京')])).toEqual( + ['asia', '東京'], + ); }); it.each([ @@ -171,74 +198,54 @@ describe('buildLocationHref', () => { }); describe('location segments and names', () => { - it('links a location through its path slugs under the continent', () => { - expect(getLocationSegments('north-america', montreal)).toEqual([ + it('links a location through its API path', () => { + expect(getLocationSegments(montreal)).toEqual([ 'north-america', 'canada', 'quebec', 'montreal-region', 'montreal', ]); - expect( - buildLocationHref(getLocationSegments('north-america', canada)), - ).toBe('/locations/north-america/canada'); - }); - - it('links a continent through its own slug', () => { - expect(getLocationSegments('', northAmerica)).toEqual(['north-america']); - expect(getContinentSlug({ ...northAmerica, continent_slug: null })).toBe( - 'north-america', + expect(buildLocationHref(getLocationSegments(canada))).toBe( + '/locations/north-america/canada', + ); + expect(buildLocationHref(getLocationSegments(northAmerica))).toBe( + '/locations/north-america', + ); + expect(buildLocationHref(getLocationSegments(clipperton))).toBe( + '/locations/clipperton', ); }); it('round-trips with URL parsing', () => { - const href = buildLocationHref( - getLocationSegments('north-america', montreal), - 2, - ); + const href = buildLocationHref(getLocationSegments(montreal), 2); expect(href).toBe( '/locations/north-america/canada/quebec/montreal-region/montreal?page=2', ); const segments = href.split('?')[0].split('/').slice(2); - const parsed = parseLocationSegments(segments); - expect(parsed).toEqual({ - continent: 'north-america', - path: montreal.path_slugs, - }); - expect( - isLocationAtPath(montreal, 'north-america', parsed?.path ?? []), - ).toBe(true); - }); - - it('checks the result is the requested location', () => { - expect(isLocationAtPath(canada, 'north-america', ['canada'])).toBe(true); - // The API also accepts continent codes: only the slug is canonical. - expect(isLocationAtPath(canada, 'na', ['canada'])).toBe(false); - expect(isLocationAtPath(canada, 'north-america', ['mexico'])).toBe(false); + expect(parseLocationSegments(segments)?.join('/')).toBe(montreal.path); }); it('names a location, falling back to its slug', () => { expect(getLocationName(montreal)).toBe('Montréal'); expect(getLocationName({ ...montreal, name: null })).toBe('montreal'); - expect(getLocationName({ ...northAmerica, name: null })).toBe( - 'North America', - ); + expect(getLocationName(northAmerica)).toBe('North America'); }); }); describe('buildBreadcrumbSteps', () => { it('is empty at the root', () => { - expect(buildBreadcrumbSteps('', null)).toEqual([]); + expect(buildBreadcrumbSteps(null)).toEqual([]); }); it('has a single step on a continent', () => { - expect(buildBreadcrumbSteps('north-america', northAmerica)).toEqual([ + expect(buildBreadcrumbSteps(northAmerica)).toEqual([ { label: 'North America', segments: ['north-america'] }, ]); }); it('adds one step per path name, linked by the path slug prefix', () => { - expect(buildBreadcrumbSteps('north-america', montreal)).toEqual([ + expect(buildBreadcrumbSteps(montreal)).toEqual([ { label: 'North America', segments: ['north-america'] }, { label: 'Canada', segments: ['north-america', 'canada'] }, { label: 'Québec', segments: ['north-america', 'canada', 'quebec'] }, @@ -259,14 +266,19 @@ describe('buildBreadcrumbSteps', () => { ]); }); - it('falls back to the continent slug and ignores unaligned names', () => { - const steps = buildBreadcrumbSteps('north-america', { + it('starts at the country without continent', () => { + expect(buildBreadcrumbSteps(clipperton)).toEqual([ + { label: 'Clipperton', segments: ['clipperton'] }, + ]); + }); + + it('ignores unaligned names', () => { + const steps = buildBreadcrumbSteps({ ...canada, - continent_name: null, - path_names: ['Canada', 'Extra'], + path_names: ['North America', 'Canada', 'Extra'], }); expect(steps.map((step) => step.label)).toEqual([ - 'north-america', + 'North America', 'Canada', ]); }); @@ -287,6 +299,14 @@ describe('buildPlaceName', () => { 'Montréal, Montréal (region), Québec, Canada', ); }); + + it('keeps the country of a location without continent', () => { + expect(buildPlaceName(clipperton)).toBe('Clipperton'); + }); + + it('falls back to the name without path names', () => { + expect(buildPlaceName({ ...canada, path_names: [] })).toBe('Canada'); + }); }); describe('fetchAllPages', () => { @@ -330,6 +350,22 @@ describe('fetchAllPages', () => { expect(fetchPage.mock.calls.map(([offset]) => offset)).toEqual([0, 10, 20]); }); + it('completes a first page fetched elsewhere', async () => { + const fetchPage = jest.fn(async (offset: number, limit: number) => + pageOf(230, offset, limit), + ); + const results = await fetchRemainingPages(pageOf(230, 0, 100), fetchPage); + expect(results).toEqual(Array.from({ length: 230 }, (_, index) => index)); + expect(fetchPage.mock.calls).toEqual([ + [100, 100], + [200, 100], + ]); + await expect( + fetchRemainingPages(pageOf(42, 0, 100), fetchPage), + ).resolves.toHaveLength(42); + expect(fetchPage).toHaveBeenCalledTimes(2); + }); + it('handles empty and total-less responses', async () => { await expect( fetchAllPages(async () => ({ total: 0, results: [] })), diff --git a/src/app/[locale]/locations/lib/location-directory.ts b/src/app/[locale]/locations/lib/location-directory.ts index d9af3aba..7572b6c5 100644 --- a/src/app/[locale]/locations/lib/location-directory.ts +++ b/src/app/[locale]/locations/lib/location-directory.ts @@ -10,21 +10,11 @@ export type LocationFeedCounts = components['schemas']['LocationFeedCounts']; export const LOCATIONS_BASE_PATH = '/locations'; export const LOCATION_FEEDS_PAGE_SIZE = 20; -/** Maximum `limit` of `GET /v1/locations`. */ +/** Maximum `limit` of the `/v1/locations` endpoints. */ export const LOCATIONS_API_PAGE_SIZE = 100; /** Anchor of the feed list; pagination links jump back to it. */ export const FEEDS_SECTION_ID = 'feeds'; -/** - * A directory location as addressed by its URL: the continent slug, then the - * `path_slugs` of the location from the country down. Both are empty at the - * root; `path` is empty on a continent page. - */ -export interface LocationPath { - continent?: string; - path: string[]; -} - // API slugs: lowercase letters (any script), digits and hyphens, e.g. // `north-america`, `montreal`, `washington-township-123456`. const SLUG_PATTERN = /^[\p{Ll}\p{Lo}\p{M}\p{Nd}-]+$/u; @@ -39,24 +29,24 @@ function decodeSegment(segment: string): string | null { } /** - * Maps the optional catch-all segments to a location path: the first segment - * is the continent, the others are the location's path slugs, at any depth. + * Maps the optional catch-all segments to the slugs of a location's API + * `path`, continent first, at any depth: `/locations/` is the + * location's `path`. * - * @returns the path (empty at the root), or null when a segment is not a + * @returns the slugs (empty at the root), or null when a segment is not a * valid slug (empty, uppercase, spaces, punctuation other than `-`). */ export function parseLocationSegments( segments: readonly string[] | undefined, -): LocationPath | null { - if (segments == undefined || segments.length === 0) return { path: [] }; +): string[] | null { + if (segments == undefined) return []; const slugs: string[] = []; for (const segment of segments) { const slug = decodeSegment(segment); if (slug === null || !SLUG_PATTERN.test(slug)) return null; slugs.push(slug); } - const [continent, ...path] = slugs; - return { continent, path }; + return slugs; } const PAGE_PATTERN = /^[1-9]\d*$/; @@ -109,33 +99,18 @@ export function buildLocationHref( return page > 1 ? `${path}?page=${page}` : path; } -/** URL slug of a continent row; continents have no geopolygon path. */ -export function getContinentSlug(continent: LocationResult): string { - return continent.continent_slug ?? continent.slug ?? ''; -} - /** Display name of a location, falling back to its slug. */ export function getLocationName(location: LocationResult): string { - if (location.location_type === 'continent') { - return ( - location.name ?? location.continent_name ?? getContinentSlug(location) - ); - } return location.name ?? location.slug ?? ''; } /** - * URL segments of a location under the continent of the current page: - * `[continent, ...path_slugs]`. A continent row links to its own slug. + * URL segments of a location: its `path_slugs`, continent first + * (`['north-america', 'canada', 'quebec']`), so that its directory URL is + * `/locations/`. */ -export function getLocationSegments( - continentSlug: string, - location: LocationResult, -): string[] { - if (location.location_type === 'continent') { - return [getContinentSlug(location)]; - } - return [continentSlug, ...(location.path_slugs ?? [])]; +export function getLocationSegments(location: LocationResult): string[] { + return location.path_slugs; } export interface BreadcrumbStep { @@ -145,59 +120,40 @@ export interface BreadcrumbStep { } /** - * The continent, then one step per `path_names` entry, each linked through - * the matching prefix of `path_slugs`. Empty at the root. + * One step per `path_names` entry, continent first, each linked through the + * matching prefix of `path_slugs`. Empty at the root. */ export function buildBreadcrumbSteps( - continentSlug: string, location: LocationResult | null, ): BreadcrumbStep[] { if (location === null) return []; - const continentStep: BreadcrumbStep = { - label: - location.continent_name ?? - (location.location_type === 'continent' - ? getLocationName(location) - : continentSlug), - segments: [continentSlug], - }; - if (location.location_type === 'continent') return [continentStep]; - const names = location.path_names ?? []; - const slugs = location.path_slugs ?? []; + const names = location.path_names; + const slugs = location.path_slugs; const depth = Math.min(names.length, slugs.length); - const steps = [continentStep]; + const steps: BreadcrumbStep[] = []; for (let index = 0; index < depth; index++) { steps.push({ label: names[index], - segments: [continentSlug, ...slugs.slice(0, index + 1)], + segments: slugs.slice(0, index + 1), }); } return steps; } /** - * Human-readable place for titles, most specific first: - * `Montréal, Québec, Canada`. A continent is named on its own; empty at the - * root. + * Human-readable place for titles, most specific first and without the + * continent: `Montréal, Québec, Canada`. A continent is named on its own; + * empty at the root. */ export function buildPlaceName(location: LocationResult | null): string { if (location === null) return ''; if (location.location_type === 'continent') return getLocationName(location); - const names = location.path_names ?? []; - if (names.length === 0) return getLocationName(location); - return [...names].reverse().join(', '); -} - -/** True when the API result is the location the URL asked for. */ -export function isLocationAtPath( - location: LocationResult, - continentSlug: string, - path: readonly string[], -): boolean { - return ( - location.continent_slug === continentSlug && - (location.path_slugs ?? []).join('/') === path.join('/') - ); + const names = location.path_names; + // `path_names` starts with the continent, when the country has one. + const placeNames = + location.continent_code != undefined ? names.slice(1) : names; + if (placeNames.length === 0) return getLocationName(location); + return [...placeNames].reverse().join(', '); } export interface ResultsPage { @@ -205,16 +161,21 @@ export interface ResultsPage { results?: T[]; } +export type PageFetcher = ( + offset: number, + limit: number, +) => Promise>; + /** - * Fetches every result of an offset-paginated endpoint: the first page tells - * the total and the effective page size, the remaining pages are then - * fetched in parallel. + * Completes the first page of an offset-paginated endpoint: it tells the + * total and the effective page size, the remaining pages are then fetched + * in parallel. */ -export async function fetchAllPages( - fetchPage: (offset: number, limit: number) => Promise>, +export async function fetchRemainingPages( + first: ResultsPage, + fetchPage: PageFetcher, pageSize: number = LOCATIONS_API_PAGE_SIZE, ): Promise { - const first = await fetchPage(0, pageSize); const results = [...(first.results ?? [])]; const total = first.total ?? results.length; // A server that caps `limit` lower than asked still pages consistently. @@ -231,6 +192,15 @@ export async function fetchAllPages( return results; } +/** Every result of an offset-paginated endpoint; see fetchRemainingPages. */ +export async function fetchAllPages( + fetchPage: PageFetcher, + pageSize: number = LOCATIONS_API_PAGE_SIZE, +): Promise { + const first = await fetchPage(0, pageSize); + return await fetchRemainingPages(first, fetchPage, pageSize); +} + export const FEED_COUNT_DATA_TYPES = ['gtfs', 'gtfs_rt', 'gbfs'] as const; export type FeedCountDataType = (typeof FEED_COUNT_DATA_TYPES)[number]; diff --git a/src/app/services/feeds/index.ts b/src/app/services/feeds/index.ts index 3a9644b8..4dc6dc23 100644 --- a/src/app/services/feeds/index.ts +++ b/src/app/services/feeds/index.ts @@ -1,5 +1,5 @@ import createClient, { type Middleware } from 'openapi-fetch'; -import type { paths } from './types'; +import type { components, paths } from './types'; import { type AllFeedsParams, type AllFeedType } from './utils'; import { type GtfsRoute } from '../../types'; import { getFeedFilesBaseUrl } from '../../utils/config'; @@ -352,8 +352,8 @@ export type SearchFeedsResponse = paths['/v1/search']['get']['responses'][200]['content']['application/json']; /** - * Also lists the feeds of a location directory page, with `continent` or - * `location_id` and `sort: 'location'`. + * Also lists the feeds of a location directory page, with `location_path` + * (or `location_id`) and `sort: 'location'`. */ export const searchFeeds = async ( params: AllFeedsParams, @@ -380,7 +380,7 @@ export type LocationsResponse = /** * Searches locations (continents, countries, subdivisions, municipalities). * Returns at most 100 results per call: page with `limit` and `offset`. - * Throws an `ApiError` with status 400 on an unsupported `sort`. + * Throws an `ApiError` with status 400 on an unsupported `sort` or `include`. */ export const getLocations = async ( params: LocationsParams, @@ -399,6 +399,88 @@ export const getLocations = async ( }); }; +export type LocationDetail = components['schemas']['LocationDetail']; + +export type LocationLookupParams = + paths['/v1/locations/lookup']['get']['parameters']['query']; + +/** + * One location from its `path` (e.g. `north-america/canada/quebec`), with + * the first page of its children when `include` has `children`; `has_feeds`, + * `sort`, `limit` and `offset` then apply to the children. + * Throws an `ApiError` with status 404 when no location has that path. + */ +export const getLocationByPath = async ( + params: LocationLookupParams, + accessToken: string, + userContextJwt?: string, +): Promise => { + const authMiddleware = generateAuthMiddlewareWithToken( + accessToken, + userContextJwt, + ); + return await withAuthMiddleware(authMiddleware, async () => { + const response = await client.GET('/v1/locations/lookup', { + params: { query: params }, + }); + return response.data; + }); +}; + +export type LocationParams = NonNullable< + paths['/v1/locations/{location_id}']['get']['parameters']['query'] +>; + +/** + * One location from its `location_id` (negative for a continent), same + * response as `getLocationByPath`. + * Throws an `ApiError` with status 404 when no location has that id. + */ +export const getLocation = async ( + locationId: number, + params: LocationParams, + accessToken: string, + userContextJwt?: string, +): Promise => { + const authMiddleware = generateAuthMiddlewareWithToken( + accessToken, + userContextJwt, + ); + return await withAuthMiddleware(authMiddleware, async () => { + const response = await client.GET('/v1/locations/{location_id}', { + params: { path: { location_id: locationId }, query: params }, + }); + return response.data; + }); +}; + +export type LocationChildrenParams = NonNullable< + paths['/v1/locations/{location_id}/children']['get']['parameters']['query'] +>; + +/** + * The direct children of a location, at most 100 per call: page with + * `limit` and `offset`. + * Throws an `ApiError` with status 404 when no location has that id. + */ +export const getLocationChildren = async ( + locationId: number, + params: LocationChildrenParams, + accessToken: string, + userContextJwt?: string, +): Promise => { + const authMiddleware = generateAuthMiddlewareWithToken( + accessToken, + userContextJwt, + ); + return await withAuthMiddleware(authMiddleware, async () => { + const response = await client.GET('/v1/locations/{location_id}/children', { + params: { path: { location_id: locationId }, query: params }, + }); + return response.data; + }); +}; + export const getLicense = async ( id: string, accessToken: string, diff --git a/src/app/services/feeds/types.ts b/src/app/services/feeds/types.ts index 57d9ebdc..83f7a47d 100644 --- a/src/app/services/feeds/types.ts +++ b/src/app/services/feeds/types.ts @@ -334,10 +334,11 @@ export interface paths { *

    * Location filters: *
    - * - `continent` restricts the results to feeds with stops in that continent, and `location_id` to feeds with - * stops in that location of `/v1/locations`, sub-areas included. Feeds are matched through their - * reverse-geolocated stops, so a feed that was never geolocated does not match. A GTFS Realtime feed that was - * never geolocated matches the locations of the schedule feeds it references. Unknown values return no feed. + * - `location_id` (any location of `/v1/locations`, continents included) or `location_path` (its `path`) + * restricts the results to feeds with stops in that location, sub-areas included. Feeds are matched through + * their reverse-geolocated stops, so a feed that was never geolocated does not match. A GTFS Realtime feed that + * was never geolocated matches the locations of the schedule feeds it references. Unknown values return no + * feed. Pass one of the two, not both. * - To list the same feeds as a location's `feed_counts`, also pass `status=active,inactive,development,future`. * - `sort=location` orders the results by the share of each feed's stops inside the requested location instead * of by creation date. @@ -359,7 +360,7 @@ export interface paths { path?: never; cookie?: never; }; - /** @description Search locations (continents, countries, subdivisions and municipalities). Results can be filtered by a free-text query and narrowed to a specific continent, country, subdivision, parent location, path or location type. Matches are ordered from the broadest area to the most specific, and by relevance within each level, unless `sort=feed_count` is given.
    Feed counts (`include_feed_counts`, `has_feeds`, `sort=feed_count`) count distinct feeds with a status of `active`, `inactive`, `development` or `future` that have reverse-geolocated stops in the location, sub-areas included. A GTFS Realtime feed that was never geolocated is counted in the locations of the schedule feeds it references. Work-in-progress feeds are counted only for callers allowed to see them, as in `/v1/search`. To list a location's feeds, call `/v1/search` with its `location_id` (or `continent` for a continent), `status=active,inactive,development,future` and `sort=location`.
    Continents come from a fixed classification and are not geopolygons. They are only returned with `location_type=continent`; their `location_id`, `parent_location_id` and ISO fields are null, `slug` and `continent_slug` both hold the continent slug, and `path_names` and `path_slugs` are empty. */ + /** @description Search and filter locations: continents, countries, subdivisions and municipalities. Results can be filtered by a free-text query, a continent, a country, a subdivision or a location type. Matches are ordered from the broadest area to the most specific, and by relevance within each level, unless `sort=feed_count` is given.
    To get one location, use `/v1/locations/{location_id}` or, from its path, `/v1/locations/lookup`; to list a location's direct children, use `/v1/locations/{location_id}/children` or `include=children` on those two endpoints. To list a location's feeds, call `/v1/search` with its `location_id` (or its `path` as `location_path`), `status=active,inactive,development,future` and `sort=location`.
    Every location has a `location_id` and a `path`. Countries, subdivisions and municipalities are OpenStreetMap administrative areas and their `location_id` is the OSM id. Continents come from a fixed country-to-continent classification; their `location_id` is negative (`-1` Africa, `-2` Antarctica, `-3` Asia, `-4` Europe, `-5` North America, `-6` Oceania, `-7` South America) and they are the parent of their countries.
    Feed counts (`include=feed_counts`, `has_feeds`, `sort=feed_count`) count distinct feeds with a status of `active`, `inactive`, `development` or `future` that have reverse-geolocated stops in the location, sub-areas included. A GTFS Realtime feed that was never geolocated is counted in the locations of the schedule feeds it references. Work-in-progress feeds are counted only for callers allowed to see them, as in `/v1/search`. */ get: operations['getLocations']; put?: never; post?: never; @@ -369,6 +370,57 @@ export interface paths { patch?: never; trace?: never; }; + '/v1/locations/lookup': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description Get one location from its `path`: the slugs of the location and of every area containing it, from the continent down, joined with `/` (e.g. `north-america/canada/quebec`). A continent's path is its slug (`north-america`); a country without continent in the classification starts at the country. This is the same location as `/v1/locations/{location_id}`, addressed by path instead of id.
    With `include=children`, the response also holds the first page of the location's direct children; `has_feeds`, `sort`, `limit` and `offset` then apply to the children. Paths follow OpenStreetMap names and can change when a place is renamed; store the `location_id` rather than the path. */ + get: operations['getLocationByPath']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/v1/locations/{location_id}': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description Get one location by its `location_id`. With `include=children`, the response also holds the first page of the location's direct children; `has_feeds`, `sort`, `limit` and `offset` then apply to the children. */ + get: operations['getLocation']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + '/v1/locations/{location_id}/children': { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description List the direct children of a location, one level down: the countries of a continent, the subdivisions of a country, and so on. Depth varies by country, so the children of a subdivision can be regions or municipalities. */ + get: operations['getLocationChildren']; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; '/v1/licenses': { parameters: { query?: never; @@ -1334,18 +1386,18 @@ export interface components { }; LocationSearchResponse: { /** @description The total number of matching locations regardless of limit and offset. */ - total?: number; + total: number; /** @description The page of matching locations, ordered from the broadest area to the most specific and by relevance within each level. */ - results?: components['schemas']['LocationSearchResult'][]; + results: components['schemas']['LocationSearchResult'][]; }; LocationSearchResult: { /** - * @description Stable location identifier. Null for continents. + * @description Stable location identifier: the OpenStreetMap id of the area, or a negative id for a continent (`-1` to `-7`). * @example 175905 */ - location_id?: number | null; + location_id: number; /** - * @description Stable identifier of the nearest containing location. Null for continents and countries. + * @description Identifier of the nearest containing location; for a country, its continent. Null for continents and for countries without continent in the classification. * @example 161950 */ parent_location_id?: number | null; @@ -1364,37 +1416,33 @@ export interface components { * @example municipality * @enum {string} */ - location_type?: 'continent' | 'country' | 'subdivision' | 'municipality'; + location_type: 'continent' | 'country' | 'subdivision' | 'municipality'; /** * @description Code of the continent that contains this location (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Null when the country has no continent in the classification. * @example NA */ continent_code?: string | null; /** - * @description URL-safe identifier of the continent, as accepted by the `continent` parameter. - * @example north-america - */ - continent_slug?: string | null; - /** - * @description English name of the continent. - * @example North America + * @description URL-safe identifier of the location among its siblings: its name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Montréal` -> `montreal`). When siblings under the same parent would share a slug, each of them gets `-` appended. A name without any ASCII letter or digit uses its `location_id` as the slug. A continent's slug is fixed (`north-america`). + * @example montreal */ - continent_name?: string | null; + slug: string; /** - * @description URL-safe identifier of the location among its siblings: its name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Montréal` -> `montreal`). When siblings under the same parent would share a slug, each of them gets `-` appended. A name without any ASCII letter or digit uses its `location_id` as the slug. - * @example montreal + * @description The location's `path_slugs` joined with `/`, from the continent down, as accepted by `/v1/locations/lookup` and by the `location_path` parameter of `/v1/search`. Paths follow OpenStreetMap names and can change when a place is renamed; store the `location_id` instead. + * @example north-america/canada/quebec/montreal-region/montreal */ - slug?: string | null; + path: string; /** - * @description The slugs of the locations in `path_names`, in the same order; joined with `/` they form the `path` parameter. Empty for continents. + * @description The slugs of the locations in `path_names`, in the same order. * @example [ + * "north-america", * "canada", * "quebec", * "montreal-region", * "montreal" * ] */ - path_slugs?: string[]; + path_slugs: string[]; feed_counts?: components['schemas']['LocationFeedCounts']; /** * @description The name of the country that contains this location. @@ -1417,21 +1465,25 @@ export interface components { */ subdivision_code?: string | null; /** - * @description The ordered list of location names from the broadest containing area down to this location. + * @description The ordered list of location names from the broadest containing area, the continent, down to this location. A country without continent in the classification starts at the country. * @example [ + * "North America", * "Canada", * "Quebec", * "Montréal (region)", * "Montréal" * ] */ - path_names?: string[]; + path_names: string[]; /** - * @description A human-readable representation of the full location hierarchy, joined from the broadest area to this location. + * @description A human-readable representation of the location hierarchy, joined from the country (or, for a continent, the continent itself) down to this location. * @example Canada, Quebec, Montréal (region), Montréal */ display_name?: string | null; }; + LocationDetail: components['schemas']['LocationSearchResult'] & { + children?: components['schemas']['LocationSearchResponse']; + }; BasicDataset: { /** * @description Unique identifier used as a key for the datasets table. @@ -1877,10 +1929,24 @@ export interface components { is_official_query_param: boolean; /** @description If true, only return feeds that currently hold the Seal of Reliability; if false, only feeds without it. Viewing a feed's seal is public, but filtering the catalogue by it is granted per user and requires the `isSealFilterEnabled` feature flag - other callers receive a 403. To request access or learn more, contact us at api@mobilitydata.org. */ has_seal_query_param: boolean; - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ + /** @description Limit results to locations in this continent, the continent included, given as its slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ location_continent: string; - /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. A GTFS Realtime feed that was never geolocated takes the locations of the schedule feeds it references. */ + /** @description A `location_id` from `/v1/locations`, continents included: only feeds with reverse-geolocated stops in that location, sub-areas included. A GTFS Realtime feed that was never geolocated takes the locations of the schedule feeds it references. */ location_id_query_param: number; + /** @description A location's `path` (e.g. `north-america/canada/quebec`), as an alternative to `location_id`: only feeds with reverse-geolocated stops in that location, sub-areas included. Case-insensitive; leading and trailing slashes are ignored. */ + location_path_query_param: string; + /** @description The location's `location_id`; negative for a continent. */ + location_id_path_param: number; + /** @description When true, only return locations with at least one feed (see the feed count rules of `/v1/locations`). */ + has_feeds_query_param: boolean; + /** @description With `include=children`, only return the children with at least one feed. */ + children_has_feeds_query_param: boolean; + /** @description Optional data to add to each location: `feed_counts`, the location's feed counts per data type. */ + locations_include: 'feed_counts'[]; + /** @description Optional data to add, comma-separated: `feed_counts`, the feed counts of the location (and of its children when they are included); `children`, the first page of the location's direct children. */ + location_include: ('feed_counts' | 'children')[]; + /** @description With `include=children`, the sort order of the children. `admin_level` (default): from the broadest area to the most specific, then by display name. `feed_count`: most feeds first, then by display name. */ + children_sort: 'admin_level' | 'feed_count'; /** @description Sort order of the results. `admin_level` (default): from the broadest area to the most specific, then by relevance to `search_query` when one is given, then by display name. `feed_count`: most feeds first, then by display name. */ locations_sort: 'admin_level' | 'feed_count'; /** @description The number of items to be returned. */ @@ -1903,7 +1969,7 @@ export interface components { offset: number; /** @description General search query to match against transit provider, location, and feed name. */ search_text_query_param: string; - /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent` or `location_id`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ + /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `location_id` or `location_path`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ search_sort: 'created_at' | 'location'; /** @description Comma separated list of GBFS versions to filter by. */ version_query_param: string; @@ -2555,11 +2621,11 @@ export interface operations { license_is_spdx?: components['parameters']['license_is_spdx']; /** @description Comma separated list of tags to filter feeds by their license tags. */ license_tags?: components['parameters']['license_tags']; - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ - continent?: components['parameters']['location_continent']; - /** @description A `location_id` from `/v1/locations`: only feeds with reverse-geolocated stops in that location, sub-areas included. A GTFS Realtime feed that was never geolocated takes the locations of the schedule feeds it references. */ + /** @description A `location_id` from `/v1/locations`, continents included: only feeds with reverse-geolocated stops in that location, sub-areas included. A GTFS Realtime feed that was never geolocated takes the locations of the schedule feeds it references. */ location_id?: components['parameters']['location_id_query_param']; - /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `continent` or `location_id`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ + /** @description A location's `path` (e.g. `north-america/canada/quebec`), as an alternative to `location_id`: only feeds with reverse-geolocated stops in that location, sub-areas included. Case-insensitive; leading and trailing slashes are ignored. */ + location_path?: components['parameters']['location_path_query_param']; + /** @description Sort order of the results. `created_at` (default): newest feeds first, then by relevance to `search_query` when one is given. `location`: by relevance to the requested location, which requires `location_id` or `location_path`. Feeds with the largest share of their reverse-geolocated stops inside the location come first (on Montréal, a city bus feed with all its stops in Montréal ranks above a regional train with a fifth of them there); ties are broken by provider, feed name and feed id. */ sort?: components['parameters']['search_sort']; }; header?: never; @@ -2581,7 +2647,7 @@ export interface operations { }; }; }; - /** @description `sort=location` was requested without `continent` or `location_id`, or `sort` has an unsupported value. */ + /** @description `sort=location` was requested without `location_id` or `location_path`, both `location_id` and `location_path` were given, or `sort` has an unsupported value. */ 400: { headers: { [name: string]: unknown; @@ -2606,9 +2672,11 @@ export interface operations { offset?: components['parameters']['offset']; /** @description Free-text search matched against the location name, alternate name and its full hierarchy (e.g. "Canada, Quebec, Montréal"). Matching is accent-insensitive and supports typeahead-style prefix matching, so "mon" matches "Montréal". When several words are provided, all of them must match. */ search_query?: string; - /** @description Limit results to locations contained within this country, given as its ISO 3166-1 alpha-2 code. Case-insensitive. */ + /** @description Limit results to locations in this continent, the continent included, given as its slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ + continent?: components['parameters']['location_continent']; + /** @description Limit results to locations contained within this country, the country included, given as its ISO 3166-1 alpha-2 code. Case-insensitive. */ country_code?: string; - /** @description Limit results to locations contained within this subdivision, given as its ISO 3166-2 code. Case-insensitive. */ + /** @description Limit results to locations contained within this subdivision, the subdivision included, given as its ISO 3166-2 code. Case-insensitive. */ subdivision_code?: string; /** * @description Filter by the type of location: @@ -2622,16 +2690,10 @@ export interface operations { | 'country' | 'subdivision' | 'municipality'; - /** @description Continent slug (`africa`, `antarctica`, `asia`, `europe`, `north-america`, `oceania`, `south-america`) or code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). Case-insensitive. */ - continent?: components['parameters']['location_continent']; - /** @description Limit results to the direct children of this location (the next level down). */ - parent_location_id?: number; - /** @description Return the location at this path: its `path_slugs` joined with `/`, from the country down, e.g. `canada/quebec/montreal`. Case-insensitive; leading and trailing slashes are ignored. Returns no result when no location has that path. */ - path?: string; - /** @description When true, only return locations with at least one feed (see the feed count rules above). */ - has_feeds?: boolean; - /** @description When true, include `feed_counts` in each result. */ - include_feed_counts?: boolean; + /** @description When true, only return locations with at least one feed (see the feed count rules of `/v1/locations`). */ + has_feeds?: components['parameters']['has_feeds_query_param']; + /** @description Optional data to add to each location: `feed_counts`, the location's feed counts per data type. */ + include?: components['parameters']['locations_include']; /** @description Sort order of the results. `admin_level` (default): from the broadest area to the most specific, then by relevance to `search_query` when one is given, then by display name. `feed_count`: most feeds first, then by display name. */ sort?: components['parameters']['locations_sort']; }; @@ -2650,13 +2712,156 @@ export interface operations { 'application/json': components['schemas']['LocationSearchResponse']; }; }; - /** @description `sort` has an unsupported value. */ + /** @description `sort` or `include` has an unsupported value. */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + getLocationByPath: { + parameters: { + query: { + /** @description The location's `path`. Case-insensitive; leading and trailing slashes are ignored. */ + path: string; + /** @description Optional data to add, comma-separated: `feed_counts`, the feed counts of the location (and of its children when they are included); `children`, the first page of the location's direct children. */ + include?: components['parameters']['location_include']; + /** @description With `include=children`, only return the children with at least one feed. */ + has_feeds?: components['parameters']['children_has_feeds_query_param']; + /** @description With `include=children`, the sort order of the children. `admin_level` (default): from the broadest area to the most specific, then by display name. `feed_count`: most feeds first, then by display name. */ + sort?: components['parameters']['children_sort']; + /** @description The number of items to be returned. */ + limit?: components['parameters']['limit_query_param_locations_endpoint']; + /** @description Offset of the first item to return. */ + offset?: components['parameters']['offset']; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The location at that path. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['LocationDetail']; + }; + }; + /** @description `path` is empty, or `sort` or `include` has an unsupported value. */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description No location has that path. */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + getLocation: { + parameters: { + query?: { + /** @description Optional data to add, comma-separated: `feed_counts`, the feed counts of the location (and of its children when they are included); `children`, the first page of the location's direct children. */ + include?: components['parameters']['location_include']; + /** @description With `include=children`, only return the children with at least one feed. */ + has_feeds?: components['parameters']['children_has_feeds_query_param']; + /** @description With `include=children`, the sort order of the children. `admin_level` (default): from the broadest area to the most specific, then by display name. `feed_count`: most feeds first, then by display name. */ + sort?: components['parameters']['children_sort']; + /** @description The number of items to be returned. */ + limit?: components['parameters']['limit_query_param_locations_endpoint']; + /** @description Offset of the first item to return. */ + offset?: components['parameters']['offset']; + }; + header?: never; + path: { + /** @description The location's `location_id`; negative for a continent. */ + location_id: components['parameters']['location_id_path_param']; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The location. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['LocationDetail']; + }; + }; + /** @description `sort` or `include` has an unsupported value. */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description No location has that id. */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + getLocationChildren: { + parameters: { + query?: { + /** @description The number of items to be returned. */ + limit?: components['parameters']['limit_query_param_locations_endpoint']; + /** @description Offset of the first item to return. */ + offset?: components['parameters']['offset']; + /** @description When true, only return locations with at least one feed (see the feed count rules of `/v1/locations`). */ + has_feeds?: components['parameters']['has_feeds_query_param']; + /** @description Optional data to add to each location: `feed_counts`, the location's feed counts per data type. */ + include?: components['parameters']['locations_include']; + /** @description Sort order of the results. `admin_level` (default): from the broadest area to the most specific, then by relevance to `search_query` when one is given, then by display name. `feed_count`: most feeds first, then by display name. */ + sort?: components['parameters']['locations_sort']; + }; + header?: never; + path: { + /** @description The location's `location_id`; negative for a continent. */ + location_id: components['parameters']['location_id_path_param']; + }; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description The children of the location. */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + 'application/json': components['schemas']['LocationSearchResponse']; + }; + }; + /** @description `sort` or `include` has an unsupported value. */ 400: { headers: { [name: string]: unknown; }; content?: never; }; + /** @description No location has that id. */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; }; }; getLicenses: { diff --git a/src/mocks/handlers.ts b/src/mocks/handlers.ts index 9225ba1d..260753b9 100644 --- a/src/mocks/handlers.ts +++ b/src/mocks/handlers.ts @@ -8,19 +8,42 @@ import feed2947 from '../../cypress/fixtures/feed_mdb-2947.json'; import gtfsFeed2947 from '../../cypress/fixtures/gtfs_feed_mdb-2947.json'; import datasets2947 from '../../cypress/fixtures/feed_datasets_mdb-2947.json'; import { + getMockLocation, + getMockLocationByPath, + getMockLocationChildren, getMockLocationFeeds, getMockLocations, isLocationSearch, } from './locationDirectory'; export const handlers = [ - // Locations: continents, children by parent, path lookup, feed counts + // Locations: list and search, with feed counts http.get(`*/v1/locations`, ({ request }) => { const params = new URL(request.url).searchParams; const { status, body } = getMockLocations(params); return HttpResponse.json(body, { status }); }), - // Mock search endpoint. With `continent` or `location_id` (location + // One location by path, with its first page of children; before the + // `{location_id}` route so that `lookup` is not read as an id. + http.get(`*/v1/locations/lookup`, ({ request }) => { + const params = new URL(request.url).searchParams; + const { status, body } = getMockLocationByPath(params); + return HttpResponse.json(body, { status }); + }), + http.get(`*/v1/locations/:locationId/children`, ({ request, params }) => { + const query = new URL(request.url).searchParams; + const { status, body } = getMockLocationChildren( + String(params.locationId), + query, + ); + return HttpResponse.json(body, { status }); + }), + http.get(`*/v1/locations/:locationId`, ({ request, params }) => { + const query = new URL(request.url).searchParams; + const { status, body } = getMockLocation(String(params.locationId), query); + return HttpResponse.json(body, { status }); + }), + // Mock search endpoint. With `location_id` or `location_path` (location // directory pages): the feeds located there, paginated and sorted. // Otherwise: a list including test-516 and mdb-2947. http.get(`*/v1/search`, ({ request }) => { diff --git a/src/mocks/locationDirectory.spec.ts b/src/mocks/locationDirectory.spec.ts index 4f632e67..72d9b2b2 100644 --- a/src/mocks/locationDirectory.spec.ts +++ b/src/mocks/locationDirectory.spec.ts @@ -1,4 +1,7 @@ import { + getMockLocation, + getMockLocationByPath, + getMockLocationChildren, getMockLocationFeeds, getMockLocations, isLocationSearch, @@ -6,30 +9,38 @@ import { } from './locationDirectory'; type Locations = ReturnType; +type Detail = ReturnType; type Feeds = ReturnType; -function locations( - query: string, -): NonNullable['body']> { - const result = getMockLocations(new URLSearchParams(query)); - if (result.status !== 200) throw new Error(`expected 200 for ${query}`); - return result.body; +function ok(result: { status: number; body: unknown }, label: string): T { + if (result.status !== 200) throw new Error(`expected 200 for ${label}`); + return result.body as T; } -function feeds(query: string): Extract['body'] { - const result = getMockLocationFeeds(new URLSearchParams(query)); - if (result.status !== 200) throw new Error(`expected 200 for ${query}`); - return result.body; +type LocationsBody = Extract['body']; +type DetailBody = Extract['body']; +type FeedsBody = Extract['body']; + +function locations(query: string): LocationsBody { + return ok(getMockLocations(new URLSearchParams(query)), query); +} + +function lookup(path: string, query: string = ''): DetailBody { + return ok( + getMockLocationByPath(new URLSearchParams(`path=${path}&${query}`)), + path, + ); +} + +function children(id: number | undefined, query: string = ''): LocationsBody { + return ok( + getMockLocationChildren(String(id), new URLSearchParams(query)), + String(id), + ); } -function at( - path: string, -): NonNullable['results']>[number] { - const [location] = - locations( - `continent=north-america&path=${path}&include_feed_counts=true&limit=1`, - ).results ?? []; - return location; +function feeds(query: string): FeedsBody { + return ok(getMockLocationFeeds(new URLSearchParams(query)), query); } describe('location directory mocks', () => { @@ -41,87 +52,148 @@ describe('location directory mocks', () => { expect(slugify('Île-de-France')).toBe('ile-de-france'); }); - it('lists continents with counts, empty ones included', () => { + it('lists the continents with feeds, most feeds first', () => { + const all = locations('location_type=continent&include=feed_counts'); + expect(all.total).toBe(7); + const antarctica = all.results?.find((row) => row.slug === 'antarctica'); + expect(antarctica).toMatchObject({ + location_id: -2, + parent_location_id: null, + path: 'antarctica', + path_slugs: ['antarctica'], + path_names: ['Antarctica'], + feed_counts: { total: 0 }, + }); + const { results } = locations( - 'location_type=continent&include_feed_counts=true', + 'location_type=continent&has_feeds=true&include=feed_counts&sort=feed_count', ); - expect(results?.map((row) => row.continent_slug)).toEqual([ - 'africa', - 'antarctica', - 'europe', - 'north-america', - 'oceania', - ]); - const antarctica = results?.find((row) => row.slug === 'antarctica'); - expect(antarctica?.location_id).toBeNull(); - expect(antarctica?.path_slugs).toEqual([]); - expect(antarctica?.feed_counts?.total).toBe(0); + expect(results?.map((row) => row.location_id)).toEqual([-5, -4, -6, -1]); + expect(results?.[0].path).toBe('north-america'); }); - it('lists the countries of a continent with feeds, most feeds first', () => { - const { results } = locations( - 'continent=NA&location_type=country&has_feeds=true&include_feed_counts=true&sort=feed_count', + it('starts every path at the continent', () => { + const quebec = lookup('north-america/canada/quebec'); + expect(quebec).toMatchObject({ + location_id: 110, + parent_location_id: 100, + continent_code: 'NA', + path: 'north-america/canada/quebec', + path_slugs: ['north-america', 'canada', 'quebec'], + path_names: ['North America', 'Canada', 'Québec'], + display_name: 'Canada, Québec', + }); + expect(lookup('north-america/canada').parent_location_id).toBe(-5); + expect(lookup('clipperton')).toMatchObject({ + parent_location_id: null, + continent_code: null, + path_slugs: ['clipperton'], + }); + }); + + it('looks a path up with its children and rolls counts up', () => { + const montreal = lookup( + 'north-america/canada/quebec/montreal', + 'include=feed_counts', + ); + expect(montreal.feed_counts?.total).toBe(22); + expect(montreal.children).toBeUndefined(); + + const quebec = lookup( + '/North-America/canada/quebec/', + 'include=feed_counts,children&has_feeds=true&sort=feed_count&limit=2', ); - expect(results?.map((row) => row.path_slugs)).toEqual([ - ['canada'], - ['united-states'], + expect(quebec.feed_counts?.total).toBeGreaterThan(22); + expect(quebec.children?.total).toBe(4); + // Laval and Québec tie on 2 feeds: by display name. + expect(quebec.children?.results?.map((row) => row.slug)).toEqual([ + 'montreal', + 'laval', ]); - expect(results?.[0].feed_counts?.total).toBeGreaterThan( - results?.[1].feed_counts?.total ?? 0, + expect(quebec.children?.results?.[0].feed_counts?.total).toBe(22); + }); + + it('answers unknown paths and ids with a 404', () => { + const notFound = (params: string): number => + getMockLocationByPath(new URLSearchParams(params)).status; + expect(notFound('path=north-america/canada/nowhere')).toBe(404); + // Paths start at the continent. + expect(notFound('path=canada')).toBe(404); + expect(notFound('path=')).toBe(400); + expect(notFound('path=europe&include=everything')).toBe(400); + expect(getMockLocation('42', new URLSearchParams()).status).toBe(404); + expect(getMockLocationChildren('42', new URLSearchParams()).status).toBe( + 404, ); }); - it('resolves a path and rolls counts up', () => { - const montreal = at('canada/quebec/montreal'); - expect(montreal.path_names).toEqual(['Canada', 'Québec', 'Montréal']); - expect(montreal.feed_counts?.total).toBe(22); - expect(at('canada/quebec').feed_counts?.total).toBeGreaterThan(22); - expect(at('canada/quebec/nowhere')).toBeUndefined(); - expect(locations('continent=europe&path=canada').results).toEqual([]); + it('gets a location by id, continents included', () => { + const europe = ok( + getMockLocation('-4', new URLSearchParams('include=children')), + 'europe', + ); + expect(europe.path).toBe('europe'); + expect(europe.children?.results?.map((row) => row.slug)).toEqual([ + 'france', + 'germany', + ]); }); it('has a variable depth and collision-suffixed slugs', () => { - const losAngeles = at( - 'united-states/california/los-angeles-county/los-angeles', - ); - expect(losAngeles.path_names).toHaveLength(4); expect( - at('united-states/california/san-francisco').path_slugs, - ).toHaveLength(3); - const ohio = at('united-states/ohio'); - const { results } = locations( - `parent_location_id=${ohio.location_id}&has_feeds=true`, - ); - expect(results?.map((row) => row.slug)).toEqual([ - 'washington-township-123456', - 'washington-township-123457', + lookup( + 'north-america/united-states/california/los-angeles-county/los-angeles', + ).path_names, + ).toHaveLength(5); + expect( + lookup('north-america/united-states/california/san-francisco').path_slugs, + ).toHaveLength(4); + const ohio = lookup('north-america/united-states/ohio'); + expect( + children(ohio.location_id, 'has_feeds=true').results?.map( + (row) => row.path, + ), + ).toEqual([ + 'north-america/united-states/ohio/washington-township-123456', + 'north-america/united-states/ohio/washington-township-123457', ]); }); it('pages children and rejects unsupported parameters', () => { - const quebec = at('canada/quebec'); - const all = locations(`parent_location_id=${quebec.location_id}`); - const second = locations( - `parent_location_id=${quebec.location_id}&limit=2&offset=2`, - ); + const quebec = lookup('north-america/canada/quebec'); + const all = children(quebec.location_id); + const second = children(quebec.location_id, 'limit=2&offset=2'); expect(second.total).toBe(all.total); expect(second.results).toEqual(all.results?.slice(2, 4)); expect(all.results?.[0].feed_counts).toBeUndefined(); expect(getMockLocations(new URLSearchParams('sort=name')).status).toBe(400); expect(getMockLocations(new URLSearchParams('limit=101')).status).toBe(400); + expect( + getMockLocations(new URLSearchParams('include=children')).status, + ).toBe(400); + }); + + it('filters the list by continent, slug or code', () => { + const bySlug = locations('continent=europe&location_type=country'); + const byCode = locations('continent=EU&location_type=country'); + expect(bySlug.results?.map((row) => row.slug)).toEqual([ + 'france', + 'germany', + ]); + expect(byCode).toEqual(bySlug); }); it('routes location searches only', () => { expect(isLocationSearch(new URLSearchParams('location_id=1'))).toBe(true); - expect(isLocationSearch(new URLSearchParams('continent=europe'))).toBe( + expect(isLocationSearch(new URLSearchParams('location_path=europe'))).toBe( true, ); expect(isLocationSearch(new URLSearchParams('status=active'))).toBe(false); }); it('paginates the feeds of a location, most relevant first', () => { - const montreal = at('canada/quebec/montreal'); - const query = `location_id=${montreal.location_id}&sort=location&limit=20`; + const query = + 'location_path=north-america/canada/quebec/montreal&sort=location&limit=20'; const first = feeds(query); const second = feeds(`${query}&offset=20`); expect(first.total).toBe(22); @@ -129,13 +201,20 @@ describe('location directory mocks', () => { expect(second.results).toHaveLength(2); // The commuter train also serves Laval and Longueuil: least relevant. expect(second.results[1].feed_name).toBe('Commuter trains'); + expect(feeds('location_id=111&sort=location&limit=20')).toEqual(first); }); - it('lists the feeds of a continent and rejects sort=location alone', () => { - expect(feeds('continent=europe&sort=location').total).toBe(3); - expect(feeds('continent=asia').total).toBe(0); - expect( - getMockLocationFeeds(new URLSearchParams('sort=location')).status, - ).toBe(400); + it('lists the feeds of a continent by id or path', () => { + expect(feeds('location_path=europe&sort=location').total).toBe(3); + expect(feeds('location_id=-4&sort=location').total).toBe(3); + expect(feeds('location_path=asia').total).toBe(0); + expect(feeds('location_path=atlantis').total).toBe(0); + }); + + it('rejects sort=location alone and both location parameters', () => { + const status = (query: string): number => + getMockLocationFeeds(new URLSearchParams(query)).status; + expect(status('sort=location')).toBe(400); + expect(status('location_id=-4&location_path=europe')).toBe(400); }); }); diff --git a/src/mocks/locationDirectory.ts b/src/mocks/locationDirectory.ts index 04ec71e4..2474e71d 100644 --- a/src/mocks/locationDirectory.ts +++ b/src/mocks/locationDirectory.ts @@ -1,13 +1,17 @@ /** * Mock data and logic for the location directory endpoints: - * GET /v1/locations (continents and geopolygon locations) - * GET /v1/search with `continent` / `location_id` (the feeds of a location) + * GET /v1/locations (list and search) + * GET /v1/locations/lookup (one location by path, with its children) + * GET /v1/locations/{location_id} and /v1/locations/{location_id}/children + * GET /v1/search with `location_id` / `location_path` (a location's feeds) * - * Locations form a tree of variable depth (Los Angeles sits under a county, - * San Francisco directly under California). Feed counts, `has_feeds` and the - * `sort=location` relevance are derived from MOCK_FEEDS' stop locations, so - * the mock behaves like the API: a feed counts once per location, sub-areas - * included. Location ids, feed ids, URLs and names are fictional mock data. + * Locations form a tree of variable depth under the continents (Los Angeles + * sits under a county, San Francisco directly under California). Continents + * have negative ids and parent their countries; a country without continent + * starts its own path. Feed counts, `has_feeds` and the `sort=location` + * relevance are derived from MOCK_FEEDS' stop locations, so the mock behaves + * like the API: a feed counts once per location, sub-areas included. + * Location ids, feed ids, URLs and names are fictional mock data. */ import type { components } from '../app/services/feeds/types'; @@ -15,44 +19,45 @@ type Feed = components['schemas']['SearchFeedItemResult']; type LocationResult = components['schemas']['LocationSearchResult']; type FeedCounts = components['schemas']['LocationFeedCounts']; type LocationsResponse = components['schemas']['LocationSearchResponse']; +type LocationDetail = components['schemas']['LocationDetail']; interface FeedsResponse { total: number; results: Feed[]; } -interface Continent { - slug: string; - code: string; - name: string; -} - -const CONTINENTS: Continent[] = [ - { slug: 'africa', code: 'AF', name: 'Africa' }, - { slug: 'antarctica', code: 'AN', name: 'Antarctica' }, - { slug: 'europe', code: 'EU', name: 'Europe' }, - { slug: 'north-america', code: 'NA', name: 'North America' }, - { slug: 'oceania', code: 'OC', name: 'Oceania' }, -]; - -type PlaceType = 'country' | 'subdivision' | 'municipality'; +type PlaceType = 'continent' | 'country' | 'subdivision' | 'municipality'; interface Place { id: number; parent: number | null; type: PlaceType; name: string; - /** ISO 3166-1 (countries) or ISO 3166-2 (subdivisions) code. */ + /** + * Continent code, ISO 3166-1 (countries) or ISO 3166-2 (subdivisions) + * code. + */ code?: string; - /** Countries only. */ - continent?: string; } +/** Fixed ids, as in the API; Asia and South America have no feeds here. */ +const continent = (id: number, name: string, code: string): Place => ({ + id, + parent: null, + type: 'continent', + name, + code, +}); +const AFRICA = -1; +const EUROPE = -4; +const NORTH_AMERICA = -5; +const OCEANIA = -6; + const country = ( id: number, name: string, code: string, - continent: string, -): Place => ({ id, parent: null, type: 'country', name, code, continent }); + continentId: number | null, +): Place => ({ id, parent: continentId, type: 'country', name, code }); const subdivision = ( id: number, parent: number, @@ -67,7 +72,14 @@ const municipality = (id: number, parent: number, name: string): Place => ({ }); export const MOCK_PLACES: Place[] = [ - country(100, 'Canada', 'CA', 'north-america'), + continent(AFRICA, 'Africa', 'AF'), + continent(-2, 'Antarctica', 'AN'), + continent(-3, 'Asia', 'AS'), + continent(EUROPE, 'Europe', 'EU'), + continent(NORTH_AMERICA, 'North America', 'NA'), + continent(OCEANIA, 'Oceania', 'OC'), + continent(-7, 'South America', 'SA'), + country(100, 'Canada', 'CA', NORTH_AMERICA), subdivision(110, 100, 'Québec', 'CA-QC'), municipality(111, 110, 'Montréal'), municipality(112, 110, 'Laval'), @@ -77,7 +89,7 @@ export const MOCK_PLACES: Place[] = [ municipality(121, 120, 'Toronto'), subdivision(130, 100, 'British Columbia', 'CA-BC'), municipality(131, 130, 'Vancouver'), - country(200, 'United States', 'US', 'north-america'), + country(200, 'United States', 'US', NORTH_AMERICA), subdivision(210, 200, 'California', 'US-CA'), // Extra intermediate level: county > city. municipality(211, 210, 'Los Angeles County'), @@ -90,18 +102,20 @@ export const MOCK_PLACES: Place[] = [ // Siblings sharing a name: both slugs get `-`. municipality(123456, 230, 'Washington Township'), municipality(123457, 230, 'Washington Township'), - country(300, 'France', 'FR', 'europe'), + country(300, 'France', 'FR', EUROPE), subdivision(310, 300, 'Île-de-France', 'FR-IDF'), municipality(311, 310, 'Paris'), - country(400, 'Germany', 'DE', 'europe'), + country(400, 'Germany', 'DE', EUROPE), subdivision(410, 400, 'Berlin', 'DE-BE'), municipality(411, 410, 'Berlin'), - country(500, 'Australia', 'AU', 'oceania'), + country(500, 'Australia', 'AU', OCEANIA), subdivision(510, 500, 'New South Wales', 'AU-NSW'), municipality(511, 510, 'Sydney'), - country(600, 'South Africa', 'ZA', 'africa'), + country(600, 'South Africa', 'ZA', AFRICA), subdivision(610, 600, 'Western Cape', 'ZA-WC'), municipality(611, 610, 'Cape Town'), + // No continent in the classification: its path starts at the country. + country(700, 'Clipperton', 'CP', null), ]; const PLACES_BY_ID = new Map(MOCK_PLACES.map((place) => [place.id, place])); @@ -127,7 +141,7 @@ function slugOf(place: Place): string { return collides ? `${slug}-${place.id}` : slug; } -/** The place and its ancestors, from the country down. */ +/** The place and its ancestors, from the continent down. */ function chainOf(place: Place): Place[] { const chain: Place[] = []; let current: Place | undefined = place; @@ -139,9 +153,8 @@ function chainOf(place: Place): Place[] { return chain; } -function continentOf(place: Place): Continent | undefined { - const slug = chainOf(place)[0].continent; - return CONTINENTS.find((continent) => continent.slug === slug); +function ancestorOfType(place: Place, type: PlaceType): Place | undefined { + return chainOf(place).find((ancestor) => ancestor.type === type); } function isWithin(placeId: number, ancestorId: number): boolean { @@ -225,6 +238,8 @@ const FEED_SEEDS: FeedSeed[] = [ ['gtfs_rt', 'Example Transport NSW', 'Trip updates', [511]], // Africa ['gtfs', 'Example Cape Town Bus', 'Bus rapid transit', [611]], + // No continent + ['gtfs', 'Example Island Boats', 'Supply boats', [700]], ]; interface MockFeed { @@ -235,12 +250,14 @@ interface MockFeed { function declaredLocation( placeId: number, ): NonNullable[number] { - const chain = chainOf(PLACES_BY_ID.get(placeId) as Place); + const place = PLACES_BY_ID.get(placeId) as Place; + const chain = chainOf(place); + const placeCountry = ancestorOfType(place, 'country'); const municipalities = chain.filter(({ type }) => type === 'municipality'); return { - country_code: chain[0].code, - country: chain[0].name, - subdivision_name: chain.find(({ type }) => type === 'subdivision')?.name, + country_code: placeCountry?.code, + country: placeCountry?.name, + subdivision_name: ancestorOfType(place, 'subdivision')?.name, municipality: municipalities[municipalities.length - 1]?.name, }; } @@ -274,29 +291,14 @@ function toMockFeed( const MOCK_FEEDS: MockFeed[] = FEED_SEEDS.map(toMockFeed); -/** Where to look for feeds: a continent slug and/or a location id. */ -interface FeedScope { - continent?: string; - locationId?: number; -} - -/** Share of a feed's stop groups inside the scope, 0 when outside. */ -function shareIn({ stopPlaces }: MockFeed, scope: FeedScope): number { - const inside = stopPlaces.filter((placeId) => { - const place = PLACES_BY_ID.get(placeId) as Place; - if ( - scope.continent != undefined && - continentOf(place)?.slug !== scope.continent - ) { - return false; - } - return scope.locationId == undefined || isWithin(placeId, scope.locationId); - }); +/** Share of a feed's stop groups inside the location, 0 when outside. */ +function shareIn({ stopPlaces }: MockFeed, locationId: number): number { + const inside = stopPlaces.filter((placeId) => isWithin(placeId, locationId)); return inside.length / stopPlaces.length; } -function feedsIn(scope: FeedScope): MockFeed[] { - return MOCK_FEEDS.filter((feed) => shareIn(feed, scope) > 0); +function feedsIn(locationId: number): MockFeed[] { + return MOCK_FEEDS.filter((feed) => shareIn(feed, locationId) > 0); } function countFeeds(feeds: MockFeed[]): FeedCounts { @@ -312,77 +314,63 @@ function countFeeds(feeds: MockFeed[]): FeedCounts { interface Row { result: LocationResult; - scope: FeedScope; depth: number; + counts: FeedCounts; } -function continentRow(continent: Continent): Row { - return { - depth: 0, - scope: { continent: continent.slug }, - result: { - location_id: null, - parent_location_id: null, - name: continent.name, - alt_name: null, - location_type: 'continent', - continent_code: continent.code, - continent_slug: continent.slug, - continent_name: continent.name, - slug: continent.slug, - path_slugs: [], - path_names: [], - country_name: null, - country_code: null, - subdivision_name: null, - subdivision_code: null, - display_name: continent.name, - }, - }; -} - -function placeRow(place: Place): Row { +function toRow(place: Place): Row { const chain = chainOf(place); - const continent = continentOf(place); - const placeSubdivision = chain.find(({ type }) => type === 'subdivision'); + const placeContinent = ancestorOfType(place, 'continent'); + const placeCountry = ancestorOfType(place, 'country'); + const placeSubdivision = ancestorOfType(place, 'subdivision'); + const pathSlugs = chain.map(slugOf); + // From the country down, or the continent itself. + const displayChain = + place.type === 'continent' + ? chain + : chain.filter(({ type }) => type !== 'continent'); return { depth: chain.length, - scope: { locationId: place.id }, + counts: countFeeds(feedsIn(place.id)), result: { location_id: place.id, parent_location_id: place.parent, name: place.name, alt_name: null, location_type: place.type, - continent_code: continent?.code ?? null, - continent_slug: continent?.slug ?? null, - continent_name: continent?.name ?? null, + continent_code: placeContinent?.code ?? null, slug: slugOf(place), - path_slugs: chain.map(slugOf), + path: pathSlugs.join('/'), + path_slugs: pathSlugs, path_names: chain.map(({ name }) => name), - country_name: chain[0].name, - country_code: chain[0].code ?? null, + country_name: placeCountry?.name ?? null, + country_code: placeCountry?.code ?? null, subdivision_name: placeSubdivision?.name ?? null, subdivision_code: placeSubdivision?.code ?? null, - display_name: chain.map(({ name }) => name).join(', '), + display_name: displayChain.map(({ name }) => name).join(', '), }, }; } -const ROWS: Row[] = [ - ...CONTINENTS.map(continentRow), - ...MOCK_PLACES.map(placeRow), -]; +const ROWS: Row[] = MOCK_PLACES.map(toRow); +const ROWS_BY_ID = new Map( + ROWS.map((row) => [row.result.location_id as number, row]), +); export type MockResult = | { status: 200; body: T } - | { status: 400; body: { detail: string } }; + | { status: 400 | 404; body: { detail: string } }; const badRequest = (detail: string): MockResult => ({ status: 400, body: { detail }, }); +const notFound = (detail: string): MockResult => ({ + status: 404, + body: { detail }, +}); + function readPaging( params: URLSearchParams, maxLimit: number, @@ -394,14 +382,35 @@ function readPaging( return { limit, offset }; } -function readContinent(params: URLSearchParams): string | undefined { +/** The comma-separated `include` values, or null when one is unsupported. */ +function readInclude( + params: URLSearchParams, + allowed: readonly string[], +): Set | null { + const values = (params.get('include') ?? '') + .split(',') + .filter((value) => value !== ''); + if (values.some((value) => !allowed.includes(value))) return null; + return new Set(values); +} + +function readSort( + params: URLSearchParams, +): 'admin_level' | 'feed_count' | null { + const sort = params.get('sort') ?? 'admin_level'; + return sort === 'admin_level' || sort === 'feed_count' ? sort : null; +} + +function readContinent(params: URLSearchParams): number | undefined { const value = params.get('continent')?.toLowerCase(); if (value == undefined || value === '') return undefined; // Slug or code, case-insensitive; unknown values match nothing. return ( - CONTINENTS.find(({ slug, code }) => - [slug, code.toLowerCase()].includes(value), - )?.slug ?? `unknown:${value}` + ROWS.find( + ({ result }) => + result.location_type === 'continent' && + [result.slug, result.continent_code?.toLowerCase()].includes(value), + )?.result.location_id ?? Number.NaN ); } @@ -411,40 +420,70 @@ const normalize = (text: string): string => .replace(/\p{Diacritic}/gu, '') .toLowerCase(); -/** GET /v1/locations */ -export function getMockLocations( +function sortRows(rows: Row[], sort: 'admin_level' | 'feed_count'): Row[] { + return [...rows].sort( + (a, b) => + (sort === 'feed_count' + ? (b.counts.total ?? 0) - (a.counts.total ?? 0) + : a.depth - b.depth) || + (a.result.display_name ?? '').localeCompare(b.result.display_name ?? ''), + ); +} + +/** + * Filters, sorts and pages rows like the list endpoints; `include` adds the + * feed counts. + */ +function listRows( + rows: Row[], params: URLSearchParams, + include: Set, ): MockResult { - const sort = params.get('sort') ?? 'admin_level'; - if (sort !== 'admin_level' && sort !== 'feed_count') { - return badRequest('Unsupported sort.'); - } + const sort = readSort(params); + if (sort === null) return badRequest('Unsupported sort.'); const paging = readPaging(params, 100); if (paging === null) return badRequest('Invalid limit or offset.'); + const hasFeeds = params.get('has_feeds') === 'true'; + const matching = sortRows( + rows.filter(({ counts }) => !hasFeeds || (counts.total ?? 0) > 0), + sort, + ); + return { + status: 200, + body: { + total: matching.length, + results: matching + .slice(paging.offset, paging.offset + paging.limit) + .map(({ result, counts }) => + include.has('feed_counts') + ? { ...result, feed_counts: counts } + : result, + ), + }, + }; +} +/** GET /v1/locations */ +export function getMockLocations( + params: URLSearchParams, +): MockResult { + const include = readInclude(params, ['feed_counts']); + if (include === null) return badRequest('Unsupported include.'); const locationType = params.get('location_type'); - const continent = readContinent(params); - const parentId = params.get('parent_location_id'); - const path = params.get('path')?.toLowerCase(); + const continentId = readContinent(params); const countryCode = params.get('country_code')?.toUpperCase(); const subdivisionCode = params.get('subdivision_code')?.toUpperCase(); const words = normalize(params.get('search_query') ?? '') .split(/\s+/) .filter((word) => word !== ''); - const hasFeeds = params.get('has_feeds') === 'true'; - const includeCounts = params.get('include_feed_counts') === 'true'; - const rows = ROWS.map((row) => ({ - row, - counts: countFeeds(feedsIn(row.scope)), - })).filter(({ row: { result }, counts }) => { + const rows = ROWS.filter(({ result }) => { if (locationType != null && result.location_type !== locationType) return false; - if (continent != undefined && result.continent_slug !== continent) - return false; - if (parentId != null && String(result.parent_location_id) !== parentId) - return false; - if (path != undefined && (result.path_slugs ?? []).join('/') !== path) + if ( + continentId != undefined && + !isWithin(result.location_id as number, continentId) + ) return false; if (countryCode != undefined && result.country_code !== countryCode) return false; @@ -454,70 +493,132 @@ export function getMockLocations( ) return false; const haystack = normalize(result.display_name ?? ''); - if (!words.every((word) => haystack.includes(word))) return false; - return !hasFeeds || (counts.total ?? 0) > 0; + return words.every((word) => haystack.includes(word)); }); + return listRows(rows, params, include); +} - rows.sort( - (a, b) => - (sort === 'feed_count' - ? (b.counts.total ?? 0) - (a.counts.total ?? 0) - : a.row.depth - b.row.depth) || - (a.row.result.display_name ?? '').localeCompare( - b.row.result.display_name ?? '', - ), +function childRows(locationId: number): Row[] { + return ROWS.filter(({ result }) => result.parent_location_id === locationId); +} + +/** The location of `row`, with its children when `include` has them. */ +function detailOf( + row: Row, + params: URLSearchParams, +): MockResult { + const include = readInclude(params, ['feed_counts', 'children']); + if (include === null) return badRequest('Unsupported include.'); + const location: LocationDetail = include.has('feed_counts') + ? { ...row.result, feed_counts: row.counts } + : { ...row.result }; + if (!include.has('children')) return { status: 200, body: location }; + const children = listRows( + childRows(row.result.location_id as number), + params, + include, ); + if (children.status !== 200) return children; + return { status: 200, body: { ...location, children: children.body } }; +} - return { - status: 200, - body: { - total: rows.length, - results: rows - .slice(paging.offset, paging.offset + paging.limit) - .map(({ row, counts }) => - includeCounts ? { ...row.result, feed_counts: counts } : row.result, - ), - }, - }; +function normalizePath(path: string): string { + return path.toLowerCase().replace(/^\/+|\/+$/g, ''); +} + +/** GET /v1/locations/lookup */ +export function getMockLocationByPath( + params: URLSearchParams, +): MockResult { + const path = normalizePath(params.get('path') ?? ''); + if (path === '') return badRequest('Missing path.'); + const row = ROWS.find(({ result }) => result.path === path); + if (row == undefined) return notFound(`No location at ${path}.`); + return detailOf(row, params); +} + +function readLocationId(raw: string): number | undefined { + const id = Number(raw); + return Number.isInteger(id) ? id : undefined; +} + +/** GET /v1/locations/{location_id} */ +export function getMockLocation( + rawId: string, + params: URLSearchParams, +): MockResult { + const id = readLocationId(rawId); + if (id === undefined) return badRequest('Invalid location_id.'); + const row = ROWS_BY_ID.get(id); + if (row == undefined) return notFound(`No location ${id}.`); + return detailOf(row, params); +} + +/** GET /v1/locations/{location_id}/children */ +export function getMockLocationChildren( + rawId: string, + params: URLSearchParams, +): MockResult { + const id = readLocationId(rawId); + if (id === undefined) return badRequest('Invalid location_id.'); + if (!ROWS_BY_ID.has(id)) return notFound(`No location ${id}.`); + const include = readInclude(params, ['feed_counts']); + if (include === null) return badRequest('Unsupported include.'); + return listRows(childRows(id), params, include); } /** True when a /v1/search request targets a location. */ export function isLocationSearch(params: URLSearchParams): boolean { return ( - params.has('continent') || params.has('location_id') || + params.has('location_path') || params.get('sort') === 'location' ); } -/** GET /v1/search with `continent` and/or `location_id`. */ +/** GET /v1/search with `location_id` or `location_path`. */ export function getMockLocationFeeds( params: URLSearchParams, ): MockResult { const sort = params.get('sort') ?? 'created_at'; - const continent = readContinent(params); const rawLocationId = params.get('location_id'); - const locationId = rawLocationId == null ? undefined : Number(rawLocationId); - if (locationId != undefined && !Number.isInteger(locationId)) { - return badRequest('Invalid location_id.'); + const rawPath = params.get('location_path'); + if (rawLocationId != null && rawPath != null) { + return badRequest('Pass location_id or location_path, not both.'); + } + let locationId: number | undefined; + if (rawLocationId != null) { + locationId = readLocationId(rawLocationId); + if (locationId === undefined) return badRequest('Invalid location_id.'); } if (sort !== 'created_at' && sort !== 'location') { return badRequest('Unsupported sort.'); } - if ( - sort === 'location' && - continent == undefined && - locationId == undefined - ) { - return badRequest('sort=location requires continent or location_id.'); + if (sort === 'location' && rawLocationId == null && rawPath == null) { + return badRequest('sort=location requires location_id or location_path.'); } const paging = readPaging(params, 3500); if (paging === null) return badRequest('Invalid limit or offset.'); - const scope: FeedScope = { continent, locationId }; - const sorted = feedsIn(scope).sort((a, b) => - sort === 'location' - ? shareIn(b, scope) - shareIn(a, scope) || + if (rawPath != null) { + const path = normalizePath(rawPath); + locationId = ROWS.find(({ result }) => result.path === path)?.result + .location_id; + // Unknown values return no feed. + if (locationId == undefined) { + return { status: 200, body: { total: 0, results: [] } }; + } + } + + const scoped = + locationId == undefined + ? MOCK_FEEDS + : ROWS_BY_ID.has(locationId) + ? feedsIn(locationId) + : []; + const sorted = [...scoped].sort((a, b) => + sort === 'location' && locationId != undefined + ? shareIn(b, locationId) - shareIn(a, locationId) || (a.feed.provider ?? '').localeCompare(b.feed.provider ?? '') || (a.feed.feed_name ?? '').localeCompare(b.feed.feed_name ?? '') || a.feed.id.localeCompare(b.feed.id) From 096a436d218c4ea37cc8cbf0df20354d9619424a Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 9 Nov 2026 08:28:48 -0500 Subject: [PATCH 12/16] fix: redirect mixed-case location URLs to their lowercase path Location slugs are lowercase, so /locations/north-america/canada/Ontario rendered the not-found page. The proxy now answers a 308 redirect to the lowercase path (locale prefix and query kept), so each place keeps a single URL. Co-Authored-By: Claude Opus 5.5 --- src/app/utils/proxy-helpers.spec.ts | 38 +++++++++++++++++++++++++++++ src/app/utils/proxy-helpers.ts | 35 ++++++++++++++++++++++++++ src/proxy.ts | 15 ++++++++++-- 3 files changed, 86 insertions(+), 2 deletions(-) diff --git a/src/app/utils/proxy-helpers.spec.ts b/src/app/utils/proxy-helpers.spec.ts index 72defd43..1d346ac6 100644 --- a/src/app/utils/proxy-helpers.spec.ts +++ b/src/app/utils/proxy-helpers.spec.ts @@ -1,4 +1,5 @@ import { + getLowercaseLocationPathname, isFeedDetailPage, rewriteFeedRequest, hasLocaleInPathname, @@ -293,3 +294,40 @@ describe('proxy-helpers', () => { }); }); }); + +describe('getLowercaseLocationPathname', () => { + it('lowercases location paths with uppercase letters', () => { + expect( + getLowercaseLocationPathname('/locations/north-america/canada/Ontario'), + ).toBe('/locations/north-america/canada/ontario'); + expect(getLowercaseLocationPathname('/fr/locations/North-America')).toBe( + '/fr/locations/north-america', + ); + expect(getLowercaseLocationPathname('/Locations/Europe')).toBe( + '/locations/europe', + ); + expect(getLowercaseLocationPathname('/FR/locations/europe')).toBe( + '/fr/locations/europe', + ); + }); + + it('keeps encoded characters encoded', () => { + expect(getLowercaseLocationPathname('/locations/%C3%89TATS')).toBe( + '/locations/%C3%A9tats', + ); + }); + + it('ignores lowercase paths and other routes', () => { + expect( + getLowercaseLocationPathname('/locations/north-america/canada/ontario'), + ).toBeNull(); + expect(getLowercaseLocationPathname('/locations')).toBeNull(); + expect(getLowercaseLocationPathname('/fr/locations')).toBeNull(); + expect(getLowercaseLocationPathname('/feeds/gtfs/MDB-1')).toBeNull(); + expect(getLowercaseLocationPathname('/locationsX/Foo')).toBeNull(); + }); + + it('ignores malformed encodings', () => { + expect(getLowercaseLocationPathname('/locations/%E0%A4%A')).toBeNull(); + }); +}); diff --git a/src/app/utils/proxy-helpers.ts b/src/app/utils/proxy-helpers.ts index afbfcd98..66e44d65 100644 --- a/src/app/utils/proxy-helpers.ts +++ b/src/app/utils/proxy-helpers.ts @@ -47,6 +47,41 @@ export function isFeedDetailPage(pathname: string): FeedDetailPageInfo { }; } +// ============================================================================ +// Location Directory +// ============================================================================ + +const LOCATION_PATH_REGEX = /^(\/(?:en|fr))?(\/locations(?:\/.*)?)$/i; + +/** + * The lowercase form of a location directory path, or null when the path is + * not under /locations or is already lowercase. + * + * Location slugs are lowercase, so `/locations/north-america/canada/Ontario` + * would otherwise render the not-found page; it is redirected to + * `/locations/north-america/canada/ontario` instead, keeping one URL per place. + */ +export function getLowercaseLocationPathname(pathname: string): string | null { + const match = pathname.match(LOCATION_PATH_REGEX); + if (match == null) return null; + const localePrefix = (match[1] ?? '').toLowerCase(); + let decodedPath: string; + try { + decodedPath = decodeURIComponent(match[2]); + } catch { + return null; + } + const lowercasePath = decodedPath.toLowerCase(); + if (lowercasePath === decodedPath && localePrefix === (match[1] ?? '')) { + return null; + } + const encodedPath = lowercasePath + .split('/') + .map((segment) => encodeURIComponent(segment)) + .join('/'); + return `${localePrefix}${encodedPath}`; +} + // ============================================================================ // Auth State Detection // ============================================================================ diff --git a/src/proxy.ts b/src/proxy.ts index 2bfbf3c7..9b4ff162 100644 --- a/src/proxy.ts +++ b/src/proxy.ts @@ -1,5 +1,6 @@ import { NextResponse, type NextRequest } from 'next/server'; import { + getLowercaseLocationPathname, isFeedDetailPage, isAuthenticatedNotGuest, rewriteFeedRequest, @@ -19,8 +20,9 @@ import { * 2. Direct access to /static/ routes without proxy header → returns 404 * 3. Feed detail pages with auth session → rewrite to /authed route (dynamic, non-cached) * 4. Feed detail pages without auth → rewrite to /static route (dynamic, ISR-cacheable) - * 5. If supported locale exists in pathname → pass through unchanged - * 6. Otherwise → internally rewrite to include default locale + * 5. Location directory paths with uppercase letters → 308 redirect to the lowercase path + * 6. If supported locale exists in pathname → pass through unchanged + * 7. Otherwise → internally rewrite to include default locale * * See src/app/utils/proxy-helpers.ts for routing helper functions. */ @@ -85,6 +87,15 @@ export default function proxy(request: NextRequest): NextResponse { }); } + // === Location directory: one lowercase URL per place === + + const lowercaseLocationPathname = getLowercaseLocationPathname(pathname); + if (lowercaseLocationPathname !== null) { + const url = request.nextUrl.clone(); + url.pathname = lowercaseLocationPathname; + return NextResponse.redirect(url, 308); + } + // === Locale routing === // If locale already in path, continue as-is From 9ad8e0a70e7712ad36be8826b144d2a3ebb550b2 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 9 Nov 2026 08:52:53 -0500 Subject: [PATCH 13/16] fix: localize directory links and canonical URLs, refresh empty feed pages - Canonical and OpenGraph URLs of location pages include the request's locale, so French pages are self-canonical. - Footer links to internal pages keep the current locale. - The hover-opened Feeds menu no longer takes focus; the keyboard-opened menu still moves focus in and restores it. - The empty feed page of an existing location is cached, so it replaces a page that had feeds; unknown paths and pages past the last one are still never cached. - Regenerate the API types for the new slug suffix description. Co-Authored-By: Claude Opus 5.5 --- .../locations/[[...location]]/page.tsx | 12 +++++-- .../lib/location-directory-data.spec.ts | 25 ++++++++++++-- .../locations/lib/location-directory-data.ts | 34 ++++++++++++++++--- src/app/components/FooterElements.tsx | 4 ++- src/app/components/HeaderFeedsMenu.tsx | 3 ++ src/app/services/feeds/types.ts | 2 +- 6 files changed, 69 insertions(+), 11 deletions(-) diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx index f7b3fd63..c03f9847 100644 --- a/src/app/[locale]/locations/[[...location]]/page.tsx +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -7,6 +7,7 @@ import BreadcrumbNavigation, { type Crumb, } from '../../../components/BreadcrumbNavigation'; import SectionContainer from '../../../components/SectionContainer'; +import { getPathname } from '../../../../i18n/navigation'; import FeedCountSummary from '../components/FeedCountSummary'; import LocationChildrenGrid from '../components/LocationChildrenGrid'; import LocationFeedsList from '../components/LocationFeedsList'; @@ -99,8 +100,15 @@ export async function generateMetadata(props: PageProps): Promise { gtfs_rt: counts?.gtfs_rt ?? 0, gbfs: counts?.gbfs ?? 0, }); - // The URL is the location's API path. - const url = `${SITE_URL}${buildLocationHref(request.segments, page)}`; + // The URL is the location's API path, in the request's locale (`/fr/...` in French). + const [pathname, query] = buildLocationHref(request.segments, page).split( + '?', + ); + const localizedPathname = getPathname({ + href: pathname, + locale: request.locale, + }); + const url = `${SITE_URL}${localizedPathname}${query !== undefined ? `?${query}` : ''}`; return { title, diff --git a/src/app/[locale]/locations/lib/location-directory-data.spec.ts b/src/app/[locale]/locations/lib/location-directory-data.spec.ts index 671863be..ce3765e3 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.spec.ts @@ -240,7 +240,10 @@ describe('fetchLocationPage', () => { it('is null when the lookup is a 404, and never caches the miss', async () => { mockSearchFeeds.mockResolvedValue(emptyFeeds); - mockGetLocationByPath.mockRejectedValueOnce(new ApiError('Not Found', 404)); + // The lookup, then the existence check of the empty feed page. + mockGetLocationByPath + .mockRejectedValueOnce(new ApiError('Not Found', 404)) + .mockRejectedValueOnce(new ApiError('Not Found', 404)); await expect(fetchLocationPage(1, MONTREAL_PATH)).resolves.toBeNull(); // Nothing cached for the unknown path, not even its empty feed page. expect(mockCacheStore.size).toBe(0); @@ -253,15 +256,31 @@ describe('fetchLocationPage', () => { }); }); - it('never caches an empty feed page', async () => { + it('caches the empty feed page of a location without feeds', async () => { + // Stored, so that it replaces a page that had feeds before. mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); mockSearchFeeds.mockResolvedValue(emptyFeeds); - await expect(fetchLocationPage(9, MONTREAL_PATH)).resolves.toMatchObject({ + await expect(fetchLocationPage(1, MONTREAL_PATH)).resolves.toMatchObject({ feeds: emptyFeeds, }); + await fetchLocationPage(1, MONTREAL_PATH); + expect(mockSearchFeeds).toHaveBeenCalledTimes(1); + // The lookup and one existence check. + expect(mockGetLocationByPath).toHaveBeenCalledTimes(2); + }); + + it('never caches a page past the last one', async () => { + mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); + mockSearchFeeds.mockResolvedValue({ total: 22, results: [] }); + + // The page turns it into a 404 (page > page count); the data layer just does not store it. + await expect(fetchLocationPage(9, MONTREAL_PATH)).resolves.toMatchObject({ + feeds: { total: 22, results: [] }, + }); await fetchLocationPage(9, MONTREAL_PATH); expect(mockSearchFeeds).toHaveBeenCalledTimes(2); + // No existence check: the total says the location has feeds. expect(mockGetLocationByPath).toHaveBeenCalledTimes(1); }); diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index 09ca4544..3b268da3 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -156,9 +156,10 @@ const cachedLocation = unstable_cache( /** * Carries a feed page without results out of unstable_cache without storing - * it: an unknown path, a page past the last one or a location without feeds. - * The feeds are fetched in parallel with the location, so caching empty - * pages would let any URL add entries to the data cache. + * it: an unknown path or a page past the last one. The feeds are fetched in + * parallel with the location, so caching those would let any URL add entries + * to the data cache. The empty page of an existing location is stored, so that + * it replaces a page that had feeds: a refresh that throws keeps the old entry. */ class UncachedFeedsPage extends Error { readonly feeds: SearchFeedsResponse; @@ -169,6 +170,24 @@ class UncachedFeedsPage extends Error { } } +/** Whether a location has this path; only asked when its feed page is empty. */ +async function locationExists( + path: string, + accessToken: string, +): Promise { + try { + return (await getLocationByPath({ path }, accessToken)) !== undefined; + } catch (error) { + if ( + error instanceof ApiError && + (error.status === 400 || error.status === 404) + ) { + return false; + } + throw error; + } +} + /** * One page of feeds: newest first at the root (`path` null), otherwise most * relevant to the location at `path` first. @@ -192,7 +211,14 @@ const cachedFeeds = unstable_cache( accessToken, ), ); - if ((feeds.results ?? []).length === 0) throw new UncachedFeedsPage(feeds); + if ( + (feeds.results ?? []).length === 0 && + ((feeds.total ?? 0) > 0 || + path === null || + !(await locationExists(path, accessToken))) + ) { + throw new UncachedFeedsPage(feeds); + } return feeds; }, ['location-directory-feeds'], diff --git a/src/app/components/FooterElements.tsx b/src/app/components/FooterElements.tsx index e670d660..0a666e2c 100644 --- a/src/app/components/FooterElements.tsx +++ b/src/app/components/FooterElements.tsx @@ -2,6 +2,7 @@ import React from 'react'; import { Link, Typography, useTheme } from '@mui/material'; import NextLink from 'next/link'; +import { Link as LocaleLink } from '../../i18n/navigation'; import { fontFamily } from '../Theme'; interface FooterLinkProps { @@ -18,7 +19,8 @@ export const FooterLink: React.FC = ({ const theme = useTheme(); return ( `montreal`). When siblings under the same parent would share a slug, each of them gets `-` appended. A name without any ASCII letter or digit uses its `location_id` as the slug. A continent's slug is fixed (`north-america`). + * @description URL-safe identifier of the location among its siblings: its name lowercased, without accents, with every run of non-alphanumeric characters replaced by a single hyphen (`Montréal` -> `montreal`). A name without any ASCII letter or digit uses its `location_id` as the slug. When siblings under the same parent would share a slug, each of them gets `--` appended (`springfield--1234`); a name never produces `--`, so siblings never share a slug. A continent's slug is fixed (`north-america`). * @example montreal */ slug: string; From 54255f9e110c53d889aaa46ea25f030887d30aaa Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 9 Nov 2026 09:13:41 -0500 Subject: [PATCH 14/16] fix: never cache out-of-range feed pages of locations without feeds Any page number of a location without feeds returned an empty page with total 0, which was cached once the location was found to exist: a URL could add unlimited cache entries by changing ?page=. Only the first page of such a location is cached now, and later empty pages skip the existence check. Co-Authored-By: Claude Opus 5.5 --- .../locations/lib/location-directory-data.spec.ts | 13 +++++++++++++ .../locations/lib/location-directory-data.ts | 12 +++++++++--- 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/src/app/[locale]/locations/lib/location-directory-data.spec.ts b/src/app/[locale]/locations/lib/location-directory-data.spec.ts index ce3765e3..a61cb7ee 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.spec.ts @@ -270,6 +270,19 @@ describe('fetchLocationPage', () => { expect(mockGetLocationByPath).toHaveBeenCalledTimes(2); }); + it('never caches a later page of a location without feeds', async () => { + // Any page number would otherwise add a cache entry. + mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); + mockSearchFeeds.mockResolvedValue(emptyFeeds); + + await fetchLocationPage(2, MONTREAL_PATH); + await fetchLocationPage(2, MONTREAL_PATH); + await fetchLocationPage(3, MONTREAL_PATH); + expect(mockSearchFeeds).toHaveBeenCalledTimes(3); + // The location lookup only: no existence check for a page after the first. + expect(mockGetLocationByPath).toHaveBeenCalledTimes(1); + }); + it('never caches a page past the last one', async () => { mockGetLocationByPath.mockResolvedValue(detail(montreal, [])); mockSearchFeeds.mockResolvedValue({ total: 22, results: [] }); diff --git a/src/app/[locale]/locations/lib/location-directory-data.ts b/src/app/[locale]/locations/lib/location-directory-data.ts index 3b268da3..ed6d59aa 100644 --- a/src/app/[locale]/locations/lib/location-directory-data.ts +++ b/src/app/[locale]/locations/lib/location-directory-data.ts @@ -156,9 +156,10 @@ const cachedLocation = unstable_cache( /** * Carries a feed page without results out of unstable_cache without storing - * it: an unknown path or a page past the last one. The feeds are fetched in - * parallel with the location, so caching those would let any URL add entries - * to the data cache. The empty page of an existing location is stored, so that + * it: an unknown path or a page past the last one, including any page after + * the first of a location without feeds. The feeds are fetched in parallel + * with the location, so caching those would let any URL add entries to the + * data cache. The first, empty page of an existing location is stored, so that * it replaces a page that had feeds: a refresh that throws keeps the old entry. */ class UncachedFeedsPage extends Error { @@ -211,9 +212,14 @@ const cachedFeeds = unstable_cache( accessToken, ), ); + // An empty page is stored only when it is the first page of an existing + // location: any other empty page (an unknown path, a page past the last + // one, any page number of a location without feeds) would let a URL add + // cache entries. if ( (feeds.results ?? []).length === 0 && ((feeds.total ?? 0) > 0 || + offset > 0 || path === null || !(await locationExists(path, accessToken))) ) { From 4daa4edce65a5bc60672621e1e5a9fdd364ec843 Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Wed, 11 Nov 2026 09:45:21 -0500 Subject: [PATCH 15/16] fix: name the location search box after the level it filters The search above the child locations now reads "Search continents", "Search countries" or "Search places", matching the section heading, so it is clear the filter only covers the locations of the current level. Co-Authored-By: Claude Opus 5.5 --- messages/en.json | 6 +++++- messages/fr.json | 6 +++++- .../[locale]/locations/[[...location]]/page.tsx | 15 ++++++++------- .../components/LocationChildrenGrid.tsx | 5 ++++- .../components/LocationChildrenList.tsx | 10 ++++++++-- .../locations/lib/location-directory.spec.ts | 16 ++++++++++++++++ .../[locale]/locations/lib/location-directory.ts | 9 +++++++++ 7 files changed, 55 insertions(+), 12 deletions(-) diff --git a/messages/en.json b/messages/en.json index 832e30ef..6289b7f2 100644 --- a/messages/en.json +++ b/messages/en.json @@ -1283,7 +1283,11 @@ "places": "Places" }, "childFeedTotal": "{count, plural, one {# feed} other {# feeds}}", - "childrenSearchPlaceholder": "Search locations", + "childrenSearchPlaceholder": { + "continents": "Search continents", + "countries": "Search countries", + "places": "Search places" + }, "childrenSearchAria": "Filter the locations below by name", "childLoadingAria": "Loading {name}", "childrenSearchResults": "{count, plural, =0 {No matching locations} one {# matching location} other {# matching locations}}", diff --git a/messages/fr.json b/messages/fr.json index 28a7ebe6..f496cb4d 100644 --- a/messages/fr.json +++ b/messages/fr.json @@ -1283,7 +1283,11 @@ "places": "Lieux" }, "childFeedTotal": "{count, plural, one {# flux} other {# flux}}", - "childrenSearchPlaceholder": "Rechercher un lieu", + "childrenSearchPlaceholder": { + "continents": "Rechercher un continent", + "countries": "Rechercher un pays", + "places": "Rechercher un lieu" + }, "childrenSearchAria": "Filtrer les lieux ci-dessous par nom", "childLoadingAria": "Chargement de {name}", "childrenSearchResults": "{count, plural, =0 {Aucun lieu correspondant} one {# lieu correspondant} other {# lieux correspondants}}", diff --git a/src/app/[locale]/locations/[[...location]]/page.tsx b/src/app/[locale]/locations/[[...location]]/page.tsx index c03f9847..c99952de 100644 --- a/src/app/[locale]/locations/[[...location]]/page.tsx +++ b/src/app/[locale]/locations/[[...location]]/page.tsx @@ -16,6 +16,7 @@ import { buildLocationHref, buildPlaceName, FEEDS_SECTION_ID, + getChildrenKind, getLocationName, getPageCount, getTotalFeedCount, @@ -161,11 +162,7 @@ export default async function LocationsPage( const backFallbackHref = isRoot ? '/feeds' : buildLocationHref(segments.slice(0, -1)); - const childrenHeading = isRoot - ? t('childrenHeading.continents') - : location.location_type === 'continent' - ? t('childrenHeading.countries') - : t('childrenHeading.places'); + const childrenKind = getChildrenKind(location); return ( - {childrenHeading}{' '} + {t(`childrenHeading.${childrenKind}`)}{' '} ({children.length}) - + ) : null} diff --git a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx index e5eeb472..82664e0e 100644 --- a/src/app/[locale]/locations/components/LocationChildrenGrid.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenGrid.tsx @@ -12,11 +12,13 @@ import { getLocationSegments, getTotalFeedCount, sortByFeedCount, + type ChildrenKind, type LocationResult, } from '../lib/location-directory'; interface Props { locations: LocationResult[]; + kind: ChildrenKind; locale: string; } @@ -39,6 +41,7 @@ function getFlag(location: LocationResult): string | undefined { */ export default async function LocationChildrenGrid({ locations, + kind, locale, }: Props): Promise { const t = await getTranslations('locations'); @@ -69,5 +72,5 @@ export default async function LocationChildrenGrid({ }; }); - return ; + return ; } diff --git a/src/app/[locale]/locations/components/LocationChildrenList.tsx b/src/app/[locale]/locations/components/LocationChildrenList.tsx index 51b3fadd..6fda078f 100644 --- a/src/app/[locale]/locations/components/LocationChildrenList.tsx +++ b/src/app/[locale]/locations/components/LocationChildrenList.tsx @@ -15,6 +15,7 @@ import { Link } from '../../../../i18n/navigation'; import LinkPendingIndicator from './LinkPendingIndicator'; import { filterByName, + type ChildrenKind, type FeedCountDataType, } from '../lib/location-directory'; @@ -48,10 +49,15 @@ const countNumberSx = { interface Props { /** Already sorted, most feeds first. */ items: LocationChildItem[]; + /** Names the search box after the level it filters. */ + kind: ChildrenKind; } /** Searchable, scrollable grid of child locations. */ -export default function LocationChildrenList({ items }: Props): ReactElement { +export default function LocationChildrenList({ + items, + kind, +}: Props): ReactElement { const t = useTranslations('locations'); const [query, setQuery] = useState(''); const visibleItems = useMemo( @@ -69,7 +75,7 @@ export default function LocationChildrenList({ items }: Props): ReactElement { onChange={(event) => { setQuery(event.target.value); }} - placeholder={t('childrenSearchPlaceholder')} + placeholder={t(`childrenSearchPlaceholder.${kind}`)} slotProps={{ htmlInput: { 'aria-label': t('childrenSearchAria'), diff --git a/src/app/[locale]/locations/lib/location-directory.spec.ts b/src/app/[locale]/locations/lib/location-directory.spec.ts index 99c03998..059261b6 100644 --- a/src/app/[locale]/locations/lib/location-directory.spec.ts +++ b/src/app/[locale]/locations/lib/location-directory.spec.ts @@ -6,6 +6,7 @@ import { fetchRemainingPages, filterByName, formatCount, + getChildrenKind, getFeedCountEntries, getLocationName, getLocationSegments, @@ -309,6 +310,21 @@ describe('buildPlaceName', () => { }); }); +describe('getChildrenKind', () => { + it('lists continents at the root', () => { + expect(getChildrenKind(null)).toBe('continents'); + }); + + it('lists countries in a continent', () => { + expect(getChildrenKind(northAmerica)).toBe('countries'); + }); + + it('lists places below a country', () => { + expect(getChildrenKind(canada)).toBe('places'); + expect(getChildrenKind(montreal)).toBe('places'); + }); +}); + describe('fetchAllPages', () => { const pageOf = ( total: number, diff --git a/src/app/[locale]/locations/lib/location-directory.ts b/src/app/[locale]/locations/lib/location-directory.ts index 7572b6c5..36929095 100644 --- a/src/app/[locale]/locations/lib/location-directory.ts +++ b/src/app/[locale]/locations/lib/location-directory.ts @@ -113,6 +113,15 @@ export function getLocationSegments(location: LocationResult): string[] { return location.path_slugs; } +/** What the children of a directory page are, for their heading and search. */ +export type ChildrenKind = 'continents' | 'countries' | 'places'; + +/** Continents at the root, countries in a continent, places below. */ +export function getChildrenKind(location: LocationResult | null): ChildrenKind { + if (location === null) return 'continents'; + return location.location_type === 'continent' ? 'countries' : 'places'; +} + export interface BreadcrumbStep { label: string; /** URL segments of this step, continent first. */ From d04d0ce75af1bb85ba505fb426cbdf08754a840d Mon Sep 17 00:00:00 2001 From: Alessandro Kreslin Date: Mon, 16 Nov 2026 11:22:15 -0500 Subject: [PATCH 16/16] fix: polish the location directory copy Capitalize the directory title ("Feeds by Location") and describe the nesting as "from continents down to specific places", matching the Continents, Countries and Places levels. The French copy keeps "villes", which already reads as open-ended. Co-Authored-By: Claude Opus 5.5 --- messages/en.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/messages/en.json b/messages/en.json index 6289b7f2..244eaa43 100644 --- a/messages/en.json +++ b/messages/en.json @@ -1268,8 +1268,8 @@ }, "locations": { "root": "Locations", - "title": "Feeds by location", - "rootIntro": "Browse open GTFS Schedule, GTFS Realtime and GBFS feeds by location, from continents down to cities.", + "title": "Feeds by Location", + "rootIntro": "Browse open GTFS Schedule, GTFS Realtime and GBFS feeds by location, from continents down to specific places.", "nodeIntro": "{total, plural, =0 {No feeds are} one {# feed is} other {# feeds are}} located in {place}.", "feedCountsAria": "Feed counts by data type", "shortLabels": { @@ -1299,7 +1299,7 @@ "paginationAria": "Feed list pages", "meta": { "rootTitle": "Transit Feeds by Location | Mobility Database", - "rootDescription": "Browse open GTFS Schedule, GTFS Realtime and GBFS transit and mobility feeds by location, from continents down to cities.", + "rootDescription": "Browse open GTFS Schedule, GTFS Realtime and GBFS transit and mobility feeds by location, from continents down to specific places.", "nodeTitle": "{place} Transit Feeds | Mobility Database", "nodeTitlePaged": "{place} Transit Feeds, Page {page} | Mobility Database", "nodeDescription": "Browse {total} open transit and mobility feeds located in {place}: {gtfs} GTFS Schedule, {gtfs_rt} GTFS Realtime and {gbfs} GBFS."