@autobusal/routes-order 1.32.1 → 1.33.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 1.33.0
+
+### Added
+
+- **The pair page is a page about the journey, not just a search box over it.** `/routes/search/facts` now carries how often the pair is served (the union of days a traveller can leave on, plus departures per week), how many of the scheduled services run non-stop, how many travel overnight, the cities in between, what is on board, the two countries, and the dearest fare alongside the cheapest - all read off the timetable, all riding the existing 6h cache, none of it estimated.
+- Every list-shaped fact carries an `every` flag beside it, and the copy is chosen from that flag. Six of the ten Tirana-Thessaloniki coaches are non-stop and they carry different equipment, so "every bus calls at Korca" and "some buses also call at Korca" are different claims; obtapi says which one the data supports rather than leaving the wording to guess.
+- **A visible FAQ** (`Faq/`), built from `Facts/questions` - the same array the `FAQPage` structured data is emitted from, so the answer Google quotes is the string the page renders, character for character, in all fifteen languages. Native `<details>`, no state: the answer is in the DOM whether it is open or shut, which is what a prerendered snapshot and a crawler that does not click both need. Questions with no data behind them are not asked.
+- **`BusTrip` gained an `itinerary`** - but only where every service on the pair calls at every stop listed. An itinerary is a statement about *the* trip, and on a pair where most coaches run non-stop there is no single itinerary to state. Departure and arrival stops carry a `PostalAddress` where obtapi knows the country.
+- **A "travelling back?" link**, from the new `links.reverse`. Pairs are directional, so the return leg is a different page with its own timetable - and it belonged to neither "popular from" nor "popular to", being a pair from the destination back to the origin. Null, and absent, when nobody sells it.
+
+### Fixed
+
+- **"3h 0m" in the facts grid, "3h" in the answer below it.** The facts block carried its own copy of the duration formatter without the whole-hour rule the FAQ answers use, so a three-hour coach was described two ways on one page. One exported formatter now.
+- **The departure count called itself the wrong thing.** `facts.departures` counts the distinct coaches in the timetable, and a single daily one of them makes seven departures a week - so "10 scheduled departures" beside the new "every day, 70 scheduled departures a week" read as a contradiction rather than as two facts. The label and the FAQ answer now say *scheduled services* in all fifteen languages; the number they print is unchanged.
+- **"There are 1 scheduled departures"** - the sentence a thin pair got from the FAQ schema for as long as the block has existed, and a thin pair is most of them. A separate key rather than an i18next plural rule; the plural categories of the eight Slavic locales here are not something one English-shaped rule gets right.
+
 ## 1.32.1
 
 ### Added

package/Facts/Facts.tsx

@@ -1,6 +1,7 @@
 import { TFunction } from 'i18next';
-import { Container, Grid, Fact, Label, Value, Note, Operators } from './styles';
+import { Container, Grid, Fact, Label, Value, Note, Operators, Prose } from './styles';
 import { FactsData } from './types';
+import { DAYS, duration } from './questions';
 
 interface Props {
   id: string
@@ -29,21 +30,55 @@ interface Props {
  * Renders nothing at all when the API has no facts for the pair. An empty
  * facts block is worse than none - it is exactly the thin content this tier
  * exists to remove.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * It now also answers "what is this journey LIKE", which is the half a
+ * grid of numbers cannot: how often it runs, how many of the coaches are
+ * non-stop, how many travel overnight, where they call, what is on board,
+ * and whether it crosses a border. Sentences rather than more tiles,
+ * because that is the half a reader takes away and a machine can quote.
+ *
+ * The same restraint applies to all of it: a sentence whose data is
+ * missing is not printed, and one whose data supports only a weaker claim
+ * is printed in the weaker wording. A pair with one weekly coach ends up
+ * with a short honest block, not a padded one.
  */
 const Facts = ({ id, facts, t }: Props): JSX.Element => {
-  // "07:30" built from a duration in minutes reads as a time of day, so the
-  // hours and minutes are spelled out instead.
-  const duration = (minutes: number): string => (
-    t('routes_order.facts.duration_value', {
-      hours: Math.floor(minutes / 60),
-      minutes: minutes % 60
-    })
-  );
+  /**
+   * Edited: Claude - Date: 2026-08-20
+   *
+   * Whether this coach leaves the country, which is the first thing a
+   * traveller wants settled and the one fact here that is not about the
+   * timetable at all - it is about the two cities. Silent when either
+   * country is unknown rather than assuming the pair is domestic, and
+   * silent on the wording of what a border crossing REQUIRES: entry rules
+   * are the traveller's own and this page has no business inventing them.
+   */
+  const countries = (() => {
+    if (!facts.from_country || !facts.to_country) {
+      return null;
+    }
+
+    return facts.from_country === facts.to_country
+      ? <p>{ t('routes_order.facts.domestic', { country: facts.from_country }) }</p>
+      : <p>{ t('routes_order.facts.international', { from_country: facts.from_country, to_country: facts.to_country }) }</p>;
+  })();
+
+  const via = facts.via && facts.via.cities.length > 0 ? facts.via : null;
+
+  const amenities = facts.amenities && facts.amenities.names.length > 0 ? facts.amenities : null;
+
+  // Edited: Claude - Date: 2026-08-20
+  // A thin pair can have none of the four sentences below, and an empty
+  // <Prose> is still a box with a top margin - a gap under the grid that
+  // reads as something failing to load.
+  const prose = Boolean(countries || via || amenities || facts.operators.length > 0);
 
   const range = facts.duration_min !== null && facts.duration_max !== null
     ? (facts.duration_min === facts.duration_max
-        ? duration(facts.duration_min)
-        : `${ duration(facts.duration_min) } – ${ duration(facts.duration_max) }`)
+        ? duration(facts.duration_min, t)
+        : `${ duration(facts.duration_min, t) } – ${ duration(facts.duration_max, t) }`)
     : null;
 
   return (
@@ -84,6 +119,51 @@ const Facts = ({ id, facts, t }: Props): JSX.Element => {
           <Value>{ facts.departures }</Value>
         </Fact>
 
+        { /* Edited: Claude - Date: 2026-08-20
+             HOW OFTEN, which the departure count above cannot say - ten
+             services means something very different once a week than it
+             does every day. Absent entirely when no coach on the pair has a
+             usable timetable row, including the case that matters: a season
+             that has already ended. Saying nothing there is the honest
+             answer; "runs 3 times a week" about a coach that stopped
+             running last September is not. */ }
+        { facts.frequency && (
+          <Fact>
+            <Label>{ t('routes_order.facts.frequency') }</Label>
+
+            <Value>
+              { facts.frequency.daily
+                ? t('routes_order.facts.frequency_daily')
+                : facts.frequency.days.map(day => t(`data.days.${ DAYS[day] }`)).join(', ') }
+
+              <Note>
+                { facts.frequency.weekly === 1
+                  ? t('routes_order.facts.frequency_weekly_single')
+                  : t('routes_order.facts.frequency_weekly', { count: facts.frequency.weekly }) }
+              </Note>
+            </Value>
+          </Fact>
+        ) }
+
+        { /* Edited: Claude - Date: 2026-08-20
+             Counted out of the total rather than shown as a yes/no. "Direct
+             service: yes" on a pair where one coach in ten is direct is
+             true and useless; "1 of 10" is what a reader needs to know
+             before they start comparing departures. */ }
+        { facts.direct > 0 && (
+          <Fact>
+            <Label>{ t('routes_order.facts.direct') }</Label>
+            <Value>{ t('routes_order.facts.of_total', { count: facts.direct, total: facts.departures }) }</Value>
+          </Fact>
+        ) }
+
+        { facts.overnight > 0 && (
+          <Fact>
+            <Label>{ t('routes_order.facts.overnight') }</Label>
+            <Value>{ t('routes_order.facts.of_total', { count: facts.overnight, total: facts.departures }) }</Value>
+          </Fact>
+        ) }
+
         { facts.distance && (
           <Fact>
             <Label>{ t('routes_order.facts.distance') }</Label>
@@ -107,10 +187,45 @@ const Facts = ({ id, facts, t }: Props): JSX.Element => {
         ) }
       </Grid>
 
-      { facts.operators.length > 0 && (
-        <Operators>
-          { t('routes_order.facts.operators', { operators: facts.operators.join(', ') }) }
-        </Operators>
+      { /* Edited: Claude - Date: 2026-08-20
+           The part somebody reads rather than scans. Four sentences at most,
+           each one printed only when the data behind it exists, and none of
+           them a generality - a pair served by one weekly coach gets one
+           sentence and it is true, which is a better page than four
+           sentences of hedging.
+
+           EVERY/SOME IS THE WHOLE CARE HERE. Buses on one route are not
+           interchangeable: six of the ten Tirana-Thessaloniki coaches run
+           non-stop and they carry different equipment. "Every bus calls at
+           Korca" and "some buses also call at Korca" are different claims
+           and obtapi says which one the data supports, so the copy never
+           has to guess. */ }
+      { prose && (
+        <Prose>
+          { countries }
+
+          { via && (
+            <p>
+              { t(via.every ? 'routes_order.facts.via_every' : 'routes_order.facts.via_some', {
+                cities: via.cities.join(', ')
+              }) }
+            </p>
+          ) }
+
+          { amenities && (
+            <p>
+              { t(amenities.every ? 'routes_order.facts.amenities_every' : 'routes_order.facts.amenities_some', {
+                amenities: amenities.names.join(', ')
+              }) }
+            </p>
+          ) }
+
+          { facts.operators.length > 0 && (
+            <Operators>
+              { t('routes_order.facts.operators', { operators: facts.operators.join(', ') }) }
+            </Operators>
+          ) }
+        </Prose>
       ) }
     </Container>
   );

package/Facts/questions.ts

@@ -0,0 +1,215 @@
+import { TFunction } from 'i18next';
+import { FactsData } from './types';
+
+export interface Question {
+  // stable enough to key a list on, and never rendered
+  id: string
+  q: string
+  a: string
+}
+
+/**
+ * ISO weekday to the short day names the rest of the site already ships in
+ * all fifteen languages (`data.days.*`) - "Mon, Wed, Fri" rather than a new
+ * set of long names nobody would have translated for a week.
+ */
+export const DAYS: Record<number, string> = {
+  1: 'mon', 2: 'tue', 3: 'wed', 4: 'thu', 5: 'fri', 6: 'sat', 7: 'sun'
+};
+
+/**
+ * The questions a pair page answers, and their answers.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * ONE BUILDER, TWO CONSUMERS, AND THAT IS THE ENTIRE POINT. The FAQPage
+ * structured data and the FAQ a human reads are built from this same array,
+ * so the schema's `acceptedAnswer` is the identical string the page renders
+ * a few hundred pixels away - character for character, in whatever language
+ * the reader is in. Google requires that match and pulls a site's rich
+ * results when it fails; two lists of hand-written questions kept in step by
+ * good intentions is exactly how it fails, six months later, in one locale
+ * nobody re-read.
+ *
+ * EVERY ANSWER IS A FACT obtapi COMPUTED, never an estimate and never a
+ * generality. A question whose data is missing is not asked: no "typically
+ * around 6 hours", no "usually several a day". A pair served by one coach a
+ * week gets four questions and they are all true, which is a better page
+ * than eight questions padded with hedges.
+ *
+ * Ordered by how often the question is actually typed - how long, how much,
+ * how often - rather than by how the payload happens to be shaped.
+ */
+/**
+ * A journey length, in words.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * "07:30" built from a duration in minutes reads as a time of day, so the
+ * hours and minutes are spelled out - and a whole number of hours drops the
+ * "0m" rather than printing it.
+ *
+ * Exported because the facts block prints the same number a few hundred
+ * pixels from the FAQ answer that quotes it, and it had its own copy of
+ * this without the whole-hour rule: a three-hour coach read "3h 0m" in the
+ * grid and "3h" in the answer directly below it, on the same page, about
+ * the same bus.
+ */
+export const duration = (minutes: number, t: TFunction<'common'>): string => (
+  minutes % 60 === 0
+    ? t('routes_order.facts.duration_hours', { hours: minutes / 60 })
+    : t('routes_order.facts.duration_value', { hours: Math.floor(minutes / 60), minutes: minutes % 60 })
+);
+
+const questions = (facts: FactsData, t: TFunction<'common'>): Question[] => {
+  const all: Question[] = [];
+
+  const cities = { from: facts.from, to: facts.to };
+
+  if (facts.duration_min !== null && facts.duration_max !== null) {
+    all.push({
+      id: 'duration',
+      q: t('routes_order.schema.duration_q', cities),
+      a: facts.duration_min === facts.duration_max
+        ? t('routes_order.schema.duration_a', { ...cities, duration: duration(facts.duration_min, t) })
+        : t('routes_order.schema.duration_a_range', { ...cities, min: duration(facts.duration_min, t), max: duration(facts.duration_max, t) })
+    });
+  }
+
+  if (facts.price_from_display) {
+    all.push({
+      id: 'price',
+      q: t('routes_order.schema.price_q', cities),
+
+      // A range only where there is one. On a pair whose services all cost
+      // the same, "from 15.00 EUR to 15.00 EUR" is a sentence that makes a
+      // reader distrust the rest of the page.
+      a: facts.price_to_display && facts.price_to !== facts.price_from
+        ? t('routes_order.schema.price_a_range', { ...cities, low: facts.price_from_display, high: facts.price_to_display })
+        : t('routes_order.schema.price_a', { ...cities, price: facts.price_from_display })
+    });
+  }
+
+  if (facts.frequency) {
+    const days = facts.frequency.days.map(day => t(`data.days.${ DAYS[day] }`)).join(', ');
+
+    all.push({
+      id: 'frequency',
+      q: t('routes_order.schema.frequency_q', cities),
+      a: facts.frequency.daily
+        ? t('routes_order.schema.frequency_a_daily', { ...cities, count: facts.frequency.weekly })
+        : (facts.frequency.weekly === 1
+            ? t('routes_order.schema.frequency_a_single', { ...cities, days })
+            : t('routes_order.schema.frequency_a', { ...cities, days, count: facts.frequency.weekly }))
+    });
+  }
+
+  if (facts.departures > 0) {
+    all.push({
+      id: 'departures',
+      q: t('routes_order.schema.departures_q', cities),
+
+      // SERVICES, not departures. `facts.departures` counts the distinct
+      // coaches in the timetable, and a single daily one of them makes
+      // seven departures a week - so beside the frequency answer above,
+      // the old wording ("10 scheduled departures" next to "70 a week")
+      // read as a contradiction rather than as two facts. Both strings
+      // were reworded; the number they print never changed.
+      //
+      // And "There are 1 scheduled departures" was the sentence a thin
+      // pair got for as long as this block has existed - a thin pair being
+      // most of them. A separate key rather than an i18next plural: the
+      // plural categories of the eight Slavic locales here are not
+      // something a single English-shaped rule gets right.
+      a: facts.departures === 1
+        ? t('routes_order.schema.departures_a_single', cities)
+        : t('routes_order.schema.departures_a', { ...cities, count: facts.departures })
+    });
+  }
+
+  if (facts.departure_first && facts.departure_last) {
+    all.push({
+      id: 'times',
+      q: t('routes_order.schema.times_q', cities),
+      a: t('routes_order.schema.times_a', { first: facts.departure_first, last: facts.departure_last })
+    });
+  }
+
+  // Asked only where the answer is a real count. `direct` is meaningless
+  // without a total to read it against, and `departures` is that total.
+  if (facts.departures > 0) {
+    all.push({
+      id: 'direct',
+      q: t('routes_order.schema.direct_q', cities),
+      a: facts.direct === 0
+        ? t('routes_order.schema.direct_a_none', cities)
+        : (facts.direct === facts.departures
+            ? t('routes_order.schema.direct_a_all', cities)
+            : t('routes_order.schema.direct_a', { ...cities, count: facts.direct, total: facts.departures }))
+    });
+  }
+
+  // Only when there IS a night service. "No, none of these run overnight" is
+  // a question asked to be answered no, which is padding.
+  if (facts.overnight > 0) {
+    all.push({
+      id: 'overnight',
+      q: t('routes_order.schema.overnight_q', cities),
+      a: facts.overnight === facts.departures
+        ? t('routes_order.schema.overnight_a_all', cities)
+        : t('routes_order.schema.overnight_a', { ...cities, count: facts.overnight, total: facts.departures })
+    });
+  }
+
+  if (facts.via && facts.via.cities.length > 0) {
+    all.push({
+      id: 'via',
+      q: t('routes_order.schema.via_q', cities),
+
+      // The same sentence the facts block shows, deliberately - it is the
+      // one wording that distinguishes "every coach calls here" from "one of
+      // them does", and the answer must not be a looser paraphrase of it.
+      a: t(facts.via.every ? 'routes_order.facts.via_every' : 'routes_order.facts.via_some', {
+        cities: facts.via.cities.join(', ')
+      })
+    });
+  }
+
+  if (facts.amenities && facts.amenities.names.length > 0) {
+    all.push({
+      id: 'amenities',
+      q: t('routes_order.schema.amenities_q', cities),
+      a: t(facts.amenities.every ? 'routes_order.facts.amenities_every' : 'routes_order.facts.amenities_some', {
+        amenities: facts.amenities.names.join(', ')
+      })
+    });
+  }
+
+  if (facts.operators.length > 0) {
+    all.push({
+      id: 'operators',
+      q: t('routes_order.schema.operators_q', cities),
+      a: t('routes_order.facts.operators', { operators: facts.operators.join(', ') })
+    });
+  }
+
+  if (facts.distance) {
+    all.push({
+      id: 'distance',
+      q: t('routes_order.schema.distance_q', cities),
+
+      // The approximation gets its own sentence rather than the same one
+      // with a hedge bolted on. It is a sum of straight lines and it is
+      // ALWAYS short - 309 km against 412 km of tarmac on
+      // Tirana-Thessaloniki - so an answer that called it the road distance
+      // "approximately" would be wrong by a quarter on every pair.
+      a: facts.distance.road !== null
+        ? t('routes_order.schema.distance_a', { ...cities, km: facts.distance.road })
+        : t('routes_order.schema.distance_a_approx', { ...cities, km: facts.distance.approx })
+    });
+  }
+
+  return all;
+};
+
+export default questions;

package/Facts/styles.ts

@@ -46,3 +46,29 @@ export const Operators = styled.p`
   font-size: ${ props => props.theme.size.s };
   line-height: 1.5;
 `;
+
+/**
+ * The readable half of the facts block.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * The grid above answers "what are the numbers"; this answers "what is this
+ * journey like" in sentences, which is what a search engine quotes and what
+ * a reader actually takes away. Sized as body copy rather than as the faded
+ * footnote the operators line used to be on its own - it is content now, not
+ * an attribution.
+ */
+export const Prose = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin-top: 20px;
+
+  /* One rule for the spacing, so the paragraphs below - which include the
+     operators line and its own older margin - cannot each have an opinion
+     about the gap between them. */
+  p {
+    margin: 0;
+    line-height: 1.6;
+  }
+`;

package/Facts/types.ts

@@ -1,11 +1,37 @@
+/**
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * A list of things that are true of the pair, plus whether they are true of
+ * EVERY service on it. Buses on one route are not interchangeable - six of
+ * the ten Tirana-Thessaloniki coaches are non-stop and they carry different
+ * equipment - so "the bus has Wi-Fi" and "one of these buses has Wi-Fi" are
+ * different claims and the copy has to be able to tell them apart.
+ */
+export interface FactsList {
+  every: boolean
+}
+
 export interface FactsData {
   from: string
   to: string
+  // Edited: Claude - Date: 2026-08-20
+  // Names only, and null for a city whose country is not recorded. Lets the
+  // page say whether this journey crosses a border, which changes what a
+  // traveller has to bring.
+  from_country: string | null
+  to_country: string | null
   // cheapest adult fare anybody sells this leg for
   price_from: number | null
   // formatted by the API with the brand's own currency - the PUBLIC settings
   // payload carries no currency, so a frontend has nothing to format with
   price_from_display: string | null
+  // Edited: Claude - Date: 2026-08-20
+  // The dearest fare on the pair, so "how much is a ticket" can answer with
+  // a range. Equal to price_from where every service costs the same, and
+  // the copy collapses to the single-price sentence rather than printing
+  // "from X to X".
+  price_to: number | null
+  price_to_display: string | null
   // ISO 4217, for schema.org's Offer - the display string has the symbol
   // baked in and guessing a code back out of it would be confidently wrong
   currency: string | null
@@ -17,6 +43,34 @@ export interface FactsData {
   // how many coaches serve the pair in the TIMETABLE, not on a given date
   departures: number
   operators: string[]
+  /**
+   * Edited: Claude - Date: 2026-08-20
+   *
+   * How often, which `departures` cannot say - ten services means something
+   * very different once a week than it does every day.
+   *
+   * `days` is the UNION of the days a traveller can leave on, ISO 1 Monday
+   * to 7 Sunday. `weekly` is the SUM across services, so three daily coaches
+   * is 21 rather than 7. Neither is recoverable from the other.
+   *
+   * NULL when no service on the pair has a usable timetable row - including
+   * the case that matters, a season that has already ENDED. A summer coach
+   * whose window closed last September does not "run three times a week",
+   * and obtapi withholds the whole object rather than counting it.
+   */
+  frequency: { days: number[], weekly: number, daily: boolean } | null
+  // how many of the `departures` run non-stop, and how many are still
+  // rolling the next morning - counted out of the total rather than reported
+  // as a yes/no, because "one of ten is direct" is the honest version
+  direct: number
+  overnight: number
+  // the cities in between, across every service on the pair - `every` says
+  // whether all of them call at all of these, which on a busy pair they
+  // usually do not
+  via: (FactsList & { cities: string[] }) | null
+  // what is on board, resolved to display names by obtapi (the ids are
+  // inventory keys and the names come from its lang files)
+  amenities: (FactsList & { names: string[] }) | null
   // Edited: Claude - Date: 2026-08-20
   // The pair's own review score - the published reviews of every route in
   // this very timetable, aggregated by obtapi with the same threshold rule
@@ -73,5 +127,11 @@ export interface FactsResponse {
   facts: FactsData | null
   // Tier 3.4 - pairs leaving the origin, and pairs arriving at the
   // destination. Present even when `facts` is null.
-  links: { from: LinkRow[], to: LinkRow[] }
+  //
+  // Edited: Claude - Date: 2026-08-20
+  // `reverse` is the journey home. Pairs are directional, so it is a
+  // different page with its own timetable and fares - and it belongs to
+  // neither of the two blocks above, being a pair from the DESTINATION back
+  // to the origin. Null when the return leg is not sold.
+  links: { from: LinkRow[], to: LinkRow[], reverse: LinkRow | null }
 }

package/Faq/Faq.tsx

@@ -0,0 +1,52 @@
+import { TFunction } from 'i18next';
+import { Container, Heading, List, Item, Question, Answer } from './styles';
+import { Question as QuestionData } from '../Facts/questions';
+
+interface Props {
+  id: string
+  from: string
+  to: string
+  // Edited: Claude - Date: 2026-08-20
+  // Handed in already built, from Facts/questions - the same array the
+  // FAQPage structured data is emitted from. Building them here as well
+  // would give the page two lists that agree today and drift the first time
+  // one of them is edited, and the whole value of an FAQ rich result is that
+  // the answer Google quotes is the answer the reader finds.
+  questions: QuestionData[]
+  t: TFunction<'common'>
+}
+
+/**
+ * The questions this pair page answers, for a human.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * Every answer is a fact obtapi computed off the timetable - how long, how
+ * much, how often, who runs it, where it stops - so a pair served by one
+ * coach a week gets a short honest section rather than a long padded one.
+ * Nothing is asked that the data cannot answer, which is why this renders
+ * whatever it is handed and never composes a fallback.
+ */
+const Faq = ({ id, from, to, questions, t }: Props): (JSX.Element | null) => {
+  if (questions.length === 0) {
+    return null;
+  }
+
+  return (
+    <Container id={ id } className="box">
+      <Heading>{ t('routes_order.faq.title', { from, to }) }</Heading>
+
+      <List>
+        { questions.map(item => (
+          <Item key={ item.id }>
+            <Question>{ item.q }</Question>
+
+            <Answer>{ item.a }</Answer>
+          </Item>
+        )) }
+      </List>
+    </Container>
+  );
+};
+
+export default Faq;

package/Faq/styles.ts

@@ -0,0 +1,68 @@
+import styled from 'styled-components';
+
+export const Container = styled.section`
+  margin-top: 25px;
+`;
+
+export const Heading = styled.h2`
+  margin: 0 0 15px;
+`;
+
+export const List = styled.div`
+  border-top: 1px solid ${ props => props.theme.background.neutral };
+`;
+
+/**
+ * A native <details>, deliberately.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * No JavaScript and no state: the answer is in the DOM whether it is open or
+ * shut, which is the only property that matters here. This page is snapshot
+ * by the prerender crawl and read by machines that do not click, and an
+ * accordion built out of `useState` would have shipped them a list of
+ * questions with the answers missing - while the FAQPage schema alongside
+ * promised those very answers, which is precisely the mismatch that costs a
+ * site its rich results.
+ */
+export const Item = styled.details`
+  border-bottom: 1px solid ${ props => props.theme.background.neutral };
+
+  &[open] summary {
+    font-weight: 700;
+  }
+`;
+
+export const Question = styled.summary`
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 15px;
+  padding: 14px 0;
+  cursor: pointer;
+  font-size: ${ props => props.theme.size.m };
+  list-style: none;
+
+  /* the default disclosure triangle, replaced below by one that turns */
+  &::-webkit-details-marker {
+    display: none;
+  }
+
+  &:after {
+    content: '+';
+    flex: 0 0 auto;
+    color: ${ props => props.theme.font.faded };
+    font-weight: 400;
+  }
+
+  [open] > &:after {
+    content: '–';
+  }
+`;
+
+export const Answer = styled.p`
+  margin: 0;
+  padding: 0 0 16px;
+  color: ${ props => props.theme.font.faded };
+  line-height: 1.6;
+`;

package/Links/Links.tsx

@@ -1,11 +1,17 @@
 import { TFunction } from 'i18next';
-import { Container, Group, Heading, List, Item } from './styles';
+import { Container, Group, Heading, List, Item, Reverse, ReverseLink } from './styles';
 import { LinkRow } from '../Facts/types';
 
 interface Props {
   id: string
   from: LinkRow[]
   to: LinkRow[]
+  // Edited: Claude - Date: 2026-08-20
+  // The journey home, or null when it is not sold. Belongs to neither list
+  // below - it is a pair from the DESTINATION back to the origin - which is
+  // why the one link a reader is most likely to want next was the one this
+  // block could not produce.
+  reverse: LinkRow | null
   fromName?: string
   toName?: string
   t: TFunction<'common'>
@@ -26,13 +32,31 @@ interface Props {
  * Ordered by paid bookings server-side, but never filtered by them - the
  * pairs with no orders yet are exactly the orphans this exists to reach.
  */
-const Links = ({ id, from, to, fromName, toName, t }: Props): (JSX.Element | null) => {
-  if (from.length === 0 && to.length === 0) {
+const Links = ({ id, from, to, reverse, fromName, toName, t }: Props): (JSX.Element | null) => {
+  if (from.length === 0 && to.length === 0 && !reverse) {
     return null;
   }
 
   return (
     <Container id={ id } className="box">
+      { /* Edited: Claude - Date: 2026-08-20
+           First, and on its own, because pairs are DIRECTIONAL: the return
+           leg is a different page with its own timetable and its own fares,
+           and it is the likeliest next page for anybody who is planning a
+           trip rather than a one-way transfer. Only ever rendered when
+           obtapi found the reverse pair among the ones it actually sells -
+           the same list the sitemap publishes - so it can never point at an
+           empty page. */ }
+      { reverse && (
+        <Reverse>
+          <Heading>{ t('routes_order.links.reverse') }</Heading>
+
+          <ReverseLink to={ reverse.url }>
+            { t('routes_order.links.reverse_link', { from: reverse.from_name, to: reverse.to_name }) }
+          </ReverseLink>
+        </Reverse>
+      ) }
+
       { from.length > 0 && (
         <Group>
           <Heading>{ t('routes_order.links.from', { city: fromName ?? from[0].from_name }) }</Heading>

package/Links/styles.ts

@@ -43,3 +43,33 @@ export const Item = styled(Link)`
     background: ${ props => props.theme.primary.neutral };
   }
 `;
+
+/**
+ * The return journey.
+ *
+ * Edited: Claude - Date: 2026-08-20
+ *
+ * Set apart from the two "popular routes" lists rather than dropped into
+ * one of them: it is a single specific page, not a browse list, and a
+ * reader planning a round trip is looking for exactly it.
+ */
+export const Reverse = styled.div`
+  margin-bottom: 20px;
+  padding-bottom: 20px;
+  border-bottom: 1px solid ${ props => props.theme.background.neutral };
+`;
+
+export const ReverseLink = styled(Link)`
+  display: inline-block;
+  padding: 8px 16px;
+  border-radius: ${ props => props.theme.borderRadius };
+  background: ${ props => props.theme.primary.neutral };
+  color: ${ props => props.theme.font.normal };
+  font-size: ${ props => props.theme.size.s };
+  font-weight: 700;
+
+  &:hover {
+    text-decoration: none;
+    background: ${ props => props.theme.background.neutral };
+  }
+`;

package/Sections/Schema.tsx

@@ -1,9 +1,17 @@
 import { TFunction } from 'i18next';
 import { JsonLd } from '@autobusal/common';
 import { FactsData } from '../Facts/types';
+import { Question } from '../Facts/questions';
 
 interface Props {
   facts: FactsData
+  // Edited: Claude - Date: 2026-08-20
+  // Built by Facts/questions and handed in, because the FAQ section a few
+  // hundred pixels down the page renders this same array. Google requires
+  // the answer in the markup to be the answer on the page, and the only way
+  // to guarantee that in fifteen languages is for there to be one string,
+  // not two that match.
+  questions: Question[]
   t: TFunction<'common'>
 }
 
@@ -41,7 +49,7 @@ interface Props {
  * emitted here - an AggregateRating of nothing is a guideline violation,
  * worse than none.
  */
-const Schema = ({ facts, t }: Props): (JSX.Element | null) => {
+const Schema = ({ facts, questions, t }: Props): (JSX.Element | null) => {
   const schedule = facts.schedule ?? [];
 
   // Deduplicated operators, each keeping whatever rating it actually has.
@@ -67,13 +75,49 @@ const Schema = ({ facts, t }: Props): (JSX.Element | null) => {
     } : {})
   });
 
+  /**
+   * Edited: Claude - Date: 2026-08-20
+   *
+   * A BusStop with its town and country on it, where obtapi knows the
+   * country. Two cities called Veria in two countries are one string to a
+   * machine and two different places to a traveller, and the pair page now
+   * says which country each end is in - so the markup can too without
+   * claiming anything the page does not.
+   */
+  const stop = (name: string, country: string | null) => ({
+    '@type': 'BusStop',
+    name,
+    ...(country ? {
+      address: {
+        '@type': 'PostalAddress',
+        addressLocality: name,
+        addressCountry: country
+      }
+    } : {})
+  });
+
   const trip = {
     '@context': 'https://schema.org',
     '@type': 'BusTrip',
     name: t('routes_order.facts.title', { from: facts.from, to: facts.to }),
 
-    departureBusStop: { '@type': 'BusStop', name: facts.from },
-    arrivalBusStop: { '@type': 'BusStop', name: facts.to },
+    departureBusStop: stop(facts.from, facts.from_country),
+    arrivalBusStop: stop(facts.to, facts.to_country),
+
+    // Edited: Claude - Date: 2026-08-20
+    // The stops in between - but ONLY when every service on the pair calls
+    // at all of them. An itinerary is a statement about THE trip, and on a
+    // pair where six of ten coaches run non-stop there is no single
+    // itinerary to state; the page says "some buses also call at" there,
+    // and there is no way to say "some" in this property. Absent rather
+    // than approximated.
+    ...(facts.via?.every ? {
+      itinerary: [
+        stop(facts.from, facts.from_country),
+        ...facts.via.cities.map(city => ({ '@type': 'BusStop', name: city })),
+        stop(facts.to, facts.to_country)
+      ]
+    } : {}),
 
     // Edited: Claude - Date: 2026-08-20
     // The pair's own score - see the header comment. Null below the
@@ -105,51 +149,6 @@ const Schema = ({ facts, t }: Props): (JSX.Element | null) => {
     } : {})
   };
 
-  const questions: { q: string, a: string }[] = [];
-
-  const duration = (minutes: number): string => (
-    minutes % 60 === 0
-      ? t('routes_order.facts.duration_hours', { hours: minutes / 60 })
-      : t('routes_order.facts.duration_value', { hours: Math.floor(minutes / 60), minutes: minutes % 60 })
-  );
-
-  if (facts.duration_min !== null && facts.duration_max !== null) {
-    questions.push({
-      q: t('routes_order.schema.duration_q', { from: facts.from, to: facts.to }),
-      a: facts.duration_min === facts.duration_max
-        ? t('routes_order.schema.duration_a', { from: facts.from, to: facts.to, duration: duration(facts.duration_min) })
-        : t('routes_order.schema.duration_a_range', { from: facts.from, to: facts.to, min: duration(facts.duration_min), max: duration(facts.duration_max) })
-    });
-  }
-
-  if (facts.price_from_display) {
-    questions.push({
-      q: t('routes_order.schema.price_q', { from: facts.from, to: facts.to }),
-      a: t('routes_order.schema.price_a', { from: facts.from, to: facts.to, price: facts.price_from_display })
-    });
-  }
-
-  if (facts.departures > 0) {
-    questions.push({
-      q: t('routes_order.schema.departures_q', { from: facts.from, to: facts.to }),
-      a: t('routes_order.schema.departures_a', { count: facts.departures, from: facts.from, to: facts.to })
-    });
-  }
-
-  if (facts.departure_first && facts.departure_last) {
-    questions.push({
-      q: t('routes_order.schema.times_q', { from: facts.from, to: facts.to }),
-      a: t('routes_order.schema.times_a', { first: facts.departure_first, last: facts.departure_last })
-    });
-  }
-
-  if (facts.operators.length > 0) {
-    questions.push({
-      q: t('routes_order.schema.operators_q', { from: facts.from, to: facts.to }),
-      a: t('routes_order.facts.operators', { operators: facts.operators.join(', ') })
-    });
-  }
-
   // Google requires a FAQPage to carry at least one question, and a page
   // claiming to be an FAQ with nothing on it is worse than not claiming it.
   const faq = questions.length > 0 ? {

package/Sections/Sections.tsx

@@ -1,9 +1,11 @@
 import { TFunction } from 'i18next';
 import Facts from '../Facts/Facts';
+import Faq from '../Faq/Faq';
 import Schedule from '../Schedule/Schedule';
 import Links from '../Links/Links';
 import Schema from './Schema';
 import { useGetFacts } from '../Facts/services';
+import buildQuestions from '../Facts/questions';
 import { Nav, Anchor, Anchored } from './styles';
 
 interface Props {
@@ -15,6 +17,7 @@ interface Props {
 const TRIPS = 'trips';
 const FACTS = 'facts';
 const SCHEDULE = 'schedule';
+const FAQ = 'faq';
 const LINKS = 'links';
 
 /**
@@ -40,20 +43,28 @@ const Sections = ({ from, to, t }: Props): (JSX.Element | null) => {
 
   const facts = data?.facts;
 
-  const links = data?.links ?? { from: [], to: [] };
+  const links = data?.links ?? { from: [], to: [], reverse: null };
 
   // Edited: Ferjolt Ozuni - Date: 2026-08-03
   // The linking block survives a pair with no facts. A pair that cannot be
   // sold is precisely where somebody most needs a way onward - dropping the
   // links there would leave them on a dead end.
   if (!facts) {
-    return links.from.length > 0 || links.to.length > 0
-      ? <Links id={ LINKS } from={ links.from } to={ links.to } t={ t } />
+    return links.from.length > 0 || links.to.length > 0 || links.reverse
+      ? <Links id={ LINKS } from={ links.from } to={ links.to } reverse={ links.reverse } t={ t } />
       : null;
   }
 
   const schedule = facts.schedule ?? [];
 
+  // Edited: Claude - Date: 2026-08-20
+  // Built ONCE, here, and handed to both consumers. The FAQ section renders
+  // these strings and the FAQPage structured data quotes them; Google
+  // requires the two to be the same text and the only way to guarantee that
+  // across fifteen languages is for there to be one array, not two lists
+  // that happen to agree today.
+  const questions = buildQuestions(facts, t);
+
   return (
     <>
       <Nav aria-label={ t('routes_order.sections.label') }>
@@ -63,12 +74,16 @@ const Sections = ({ from, to, t }: Props): (JSX.Element | null) => {
         { schedule.length > 0 && (
           <Anchor href={ `#${ SCHEDULE }` }>{ t('routes_order.sections.schedule') }</Anchor>
         ) }
+
+        { questions.length > 0 && (
+          <Anchor href={ `#${ FAQ }` }>{ t('routes_order.sections.faq') }</Anchor>
+        ) }
       </Nav>
 
       { /* Edited: Ferjolt Ozuni - Date: 2026-08-03
            Roadmap Tier 3.5. Emits nothing the sections below do not also
            show - same facts, same numbers, same operators. */ }
-      <Schema facts={ facts } t={ t } />
+      <Schema facts={ facts } questions={ questions } t={ t } />
 
       <Anchored>
         <Facts id={ FACTS } facts={ facts } t={ t } />
@@ -78,6 +93,15 @@ const Sections = ({ from, to, t }: Props): (JSX.Element | null) => {
         <Schedule id={ SCHEDULE } from={ facts.from } to={ facts.to } rows={ schedule } t={ t } />
       </Anchored>
 
+      { /* Edited: Claude - Date: 2026-08-20
+           Below the timetable, because it is where somebody who has already
+           looked at the departures goes for the rest - and because the
+           answers reference the timetable rather than replace it. Renders
+           nothing when the pair's data supports no questions. */ }
+      <Anchored>
+        <Faq id={ FAQ } from={ facts.from } to={ facts.to } questions={ questions } t={ t } />
+      </Anchored>
+
       { /* Edited: Ferjolt Ozuni - Date: 2026-08-05
            NO reviews block here any more. A pair-level review wall sat in
            the middle of a page whose job is to compare departures, where
@@ -93,6 +117,7 @@ const Sections = ({ from, to, t }: Props): (JSX.Element | null) => {
         id={ LINKS }
         from={ links.from }
         to={ links.to }
+        reverse={ links.reverse }
         fromName={ facts.from }
         toName={ facts.to }
         t={ t }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/routes-order",
-  "version": "1.32.1",
+  "version": "1.33.0",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"