@autobusal/routes-order 1.8.0 → 1.9.1

package/Facts/styles.ts

@@ -0,0 +1,112 @@
+import styled from 'styled-components';
+
+export const Container = styled.section`
+  margin-top: 25px;
+`;
+
+export const Grid = styled.dl`
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+  gap: 18px;
+  margin: 0;
+`;
+
+export const Fact = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+`;
+
+export const Label = styled.dt`
+  font-size: ${ props => props.theme.size.s };
+  color: ${ props => props.theme.font.faded };
+`;
+
+export const Value = styled.dd`
+  margin: 0;
+  font-size: ${ props => props.theme.size.l };
+  font-weight: 700;
+  line-height: 1.2;
+`;
+
+/**
+ * Qualifies a value that is not quite what its label implies - the straight
+ * line distance, which is always shorter than the road.
+ */
+export const Note = styled.span`
+  display: block;
+  font-size: ${ props => props.theme.size.xs };
+  font-weight: 400;
+  color: ${ props => props.theme.font.faded };
+`;
+
+export const Operators = styled.p`
+  margin: 20px 0 0;
+  color: ${ props => props.theme.font.faded };
+  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;
+  }
+`;
+
+/**
+ * The pair is published but nothing on it runs.
+ *
+ * Edited: Claude - Date: 2026-08-21
+ *
+ * ABOVE the grid and inside the same box, because it changes how every
+ * number below it is to be read: those fares and times are what the
+ * operator last published, not what is on sale this morning. A banner
+ * floating outside the block would leave the grid looking like a live
+ * offer with a disclaimer somewhere else on the page.
+ *
+ * Informational, not an error - `font.info` rather than `font.error`. A
+ * seasonal coach is a normal thing that has happened, and dressing it as a
+ * fault would push a reader to leave rather than to look at the routes that
+ * ARE running a few hundred pixels down.
+ */
+export const Notice = styled.div`
+  margin: 0 0 22px;
+  padding: 14px 16px;
+  border-left: 3px solid ${ props => props.theme.font.info };
+  border-radius: ${ props => props.theme.borderRadius };
+  background: ${ props => props.theme.background.neutral };
+  line-height: 1.6;
+
+  p {
+    margin: 0;
+  }
+
+  /* The headline claim, in the reader's weight rather than a heading level:
+     the block already owns an <h2> and a second one here would put "not
+     currently scheduled" into the document outline above the facts it
+     qualifies. */
+  strong {
+    display: block;
+    font-weight: 700;
+  }
+`;

package/Facts/types.ts

@@ -0,0 +1,167 @@
+/**
+ * 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
+  // both ends of the range, in minutes
+  duration_min: number | null
+  duration_max: number | null
+  departure_first: string | null
+  departure_last: string | null
+  // 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
+  /**
+   * Edited: Claude - Date: 2026-08-21
+   *
+   * WHETHER ANY OF THIS IS STILL ON OFFER. A route is published to the
+   * sitemap on a `searchable` flag that nothing re-checks, so a season
+   * ending never un-publishes the page - and the page had no way to know.
+   * It rendered a facts block quietly missing its frequency and a departure
+   * list that came back empty for every date the visitor tried.
+   *
+   * `scheduled` false means NO leg on this pair has a timetable window that
+   * is still open, which is the same test the search applies - so nothing
+   * can be bought here on any date. `last` is then the day the last of them
+   * ran, or NULL when no leg ever had a window at all (a route published
+   * before anybody gave it a timetable). Those two want different
+   * sentences: one has a date to name and the other does not, and inventing
+   * one would be a lie.
+   *
+   * `last` is deliberately null while `scheduled` is true - there it would
+   * be some other leg's season ending, printed where a reader reads "the
+   * last day this ran".
+   *
+   * OPTIONAL, and that is not laziness: obtapi caches this payload for six
+   * hours, so for six hours after a deploy the field is simply absent from
+   * warm entries. Absent means WE DID NOT COMPUTE IT and the page says
+   * nothing - which is also the honest reading of `frequency: null` with
+   * `scheduled: true`, a pair whose windows are open but whose operators
+   * never listed their days. "We cannot say how often" and "it does not
+   * run" are different claims and only the second one gets the notice.
+   */
+  service?: { scheduled: boolean, last: string | 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
+  // as everything else (null until there is enough to say something honest).
+  // For structured data; note ScheduleRow.rating below is the OPERATOR's
+  // company-wide number, a different thing.
+  rating: { average: number, count: number } | null
+  // Two numbers that must never be conflated.
+  //
+  // `road` is real driving distance from a routing service and is null unless
+  // one is configured. `approx` sums straight lines stop by stop - always
+  // available, and ALWAYS SHORT, because a straight line is the shortest path
+  // there is. Measured on Tirana-Thessaloniki via Korca: approx 309 km
+  // against 401 km of actual road, a 23% understatement. Show `road` plainly
+  // when it exists; show `approx` only with its caveat attached.
+  distance: { road: number | null, approx: number } | null
+  // every service on the pair, sorted by departure - Tier 3.3
+  schedule: ScheduleRow[]
+}
+
+export interface ScheduleRow {
+  route: string
+  operator: string | null
+  // null until the operator has enough published reviews - see Tier 2
+  rating: { average: number, count: number } | null
+  departure: string | null
+  arrival: string | null
+  /**
+   * Edited: Ferjolt Ozuni - Date: 2026-08-05
+   * Days between boarding and arriving - 0 same day, 1 the next morning.
+   * A timetable of two clock times per row cannot show an overnight service
+   * without it.
+   */
+  offset?: number
+  minutes: number | null
+  // 0 is a direct service
+  stops: number
+  price: string
+}
+
+export interface LinkRow {
+  from: string
+  to: string
+  from_name: string
+  to_name: string
+  url: string
+  // paid orders in the last year - ranks the list, never gates membership
+  orders: number
+}
+
+export interface FactsResponse {
+  // null for a pair that is not sold - an envelope rather than a bare null,
+  // because `{}` is truthy in JavaScript
+  facts: FactsData | null
+  // Tier 3.4 - pairs leaving the origin, and pairs arriving at the
+  // destination. Present even when `facts` is null.
+  //
+  // 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/Found/Dates/Dates.tsx

@@ -2,9 +2,10 @@ import { useState } from 'react';
 import { TFunction } from 'i18next';
 import { AiOutlineCaretLeft, AiOutlineCaretRight } from 'react-icons/ai';
 import { Button } from '@autobusal/common';
-import { createDate, getFormattedShort } from '@autobusal/utilities';
+import { useMediaQuery } from '@autobusal/hooks';
+import { createDate, getDayParts } from '@autobusal/utilities';
 import Loading from './Loading';
-import { Container, Inner, ButtonDay } from './styles';
+import { Container, Inner, ButtonDay, DayPrice, Cheapest, Weekday, DayNumber, Month } from './styles';
 import { RoutesSearchForm } from '@autobusal/routes-search/types';
 import { FoundDay } from '../../types';
 import { useGetDates } from '../../services';
@@ -19,6 +20,24 @@ interface Props {
 const Dates = ({ type, step1, t, onSearch }: Props): JSX.Element => {
   const [number, setNumber] = useState<number>(0);
 
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Three days on a phone, five on a tablet, seven on a desktop.
+  //
+  // Seven fit on a phone without a scroller once the labels were trimmed,
+  // but only at about 36px a cell - enough to read, not enough to be
+  // comfortable to hit with a thumb, and with the price wrapping to three
+  // lines underneath. Each step up in width buys two more days rather than
+  // squeezing the same seven.
+  //
+  // This is one of the few things CSS genuinely cannot do: hiding cells
+  // would mean hiding FIXED positions, and the days that matter least are
+  // the ones furthest from the selected date, which moves.
+  const phone = useMediaQuery('(max-width: 639px)');
+
+  const tablet = useMediaQuery('(max-width: 1023px)');
+
+  const visible = phone ? 3 : (tablet ? 5 : 7);
+
   const { data, isLoading } = useGetDates(step1, type, number);
 
   if (isLoading) {
@@ -43,16 +62,87 @@ const Dates = ({ type, step1, t, onSearch }: Props): JSX.Element => {
 
   const today = new Date();
 
-  const items = data?.map(item => {
+  /**
+   * Edited: Ferjolt Ozuni - Date: 2026-08-01
+   *
+   * The cheapest fare in the visible window, so it can be called out.
+   *
+   * Two guards, both learned by looking at it: the badge is pointless when
+   * every day costs the same, and it is worse than pointless when most days
+   * tie at the minimum - badging six of seven days trains people to ignore
+   * the badge entirely. It only appears when the cheap days are genuinely
+   * the minority, which is when shifting a date is actually worth telling
+   * somebody about.
+   */
+  const prices = (data ?? [])
+    .filter(item => typeof item.from_price === 'number')
+    .map(item => item.from_price as number);
+
+  const lowest = prices.length > 0 ? Math.min(...prices) : null;
+
+  const atLowest = prices.filter(price => price === lowest).length;
+
+  const varies = prices.length > 1
+    && Math.max(...prices) > (lowest as number)
+    && atLowest * 2 <= prices.length;
+
+  /**
+   * The days actually shown.
+   *
+   * Centred on the selected day where the window allows, so shrinking to
+   * five never hides the day somebody is looking at - and clamped at both
+   * ends, so a selection sitting at the very start or end of the week still
+   * yields five days rather than three.
+   */
+  const shown = (() => {
+    const days = data ?? [];
+
+    if (days.length <= visible) {
+      return days;
+    }
+
+    const selected = days.findIndex(item => item.day === step1[type]);
+
+    // Centre on the selected day, then clamp - so a selection at either end
+    // of the week still yields a full window rather than a short one.
+    const start = Math.min(
+      Math.max(0, (selected === -1 ? 0 : selected) - Math.floor(visible / 2)),
+      days.length - visible
+    );
+
+    return days.slice(start, start + visible);
+  })();
+
+  const items = shown.map(item => {
     const date = createDate(item.day);
 
     // if date in the future, and we have routes available
     const isAvailable = today.getTime() <= date.getTime() && item.routes;
 
+    const isCheapest = varies && lowest !== null && item.from_price === lowest;
+
     return (
-      <ButtonDay key={ item.id } $available={ isAvailable } $selected={ step1[type] === item.day } onClick={ () => onClick(item, isAvailable) }>{ getFormattedShort(date, t) }</ButtonDay>
+      <ButtonDay key={ item.id } $available={ isAvailable } $selected={ step1[type] === item.day } onClick={ () => onClick(item, isAvailable) }>
+        { /* Edited: Ferjolt Ozuni - Date: 2026-08-03
+             In parts, so a phone can drop the month and fit seven days
+             without a horizontal scroller - see Month in styles. */ }
+        <Weekday>{ getDayParts(date, t).weekday }</Weekday>
+
+        <DayNumber>
+          { getDayParts(date, t).day }
+          <Month>{ ' ' + getDayParts(date, t).month }</Month>
+        </DayNumber>
+
+        { isAvailable && item.from_price_display && (
+          <DayPrice $cheapest={ isCheapest }>{ item.from_price_display }</DayPrice>
+        ) }
+
+        { isCheapest && isAvailable && (
+          <Cheapest $selected={ step1[type] === item.day }>{ t('routes_order.step2.dates.cheapest') }</Cheapest>
+        ) }
+      </ButtonDay>
     );
-  })
+  });
 
   return (
     <Container>