@autobusal/routes-order 1.32.0 → 1.33.0

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 }