@autobusal/routes-order 1.12.0 → 1.16.0

package/CHANGELOG.md

@@ -6,6 +6,62 @@ All notable changes to this package are documented here. This project follows
 > Note: 1.8.0 was published without a changelog entry. The gap is left as-is
 > rather than reconstructed after the fact.
 
+## 1.16.0
+
+The crawlable timetable, and a section layout around the wizard.
+
+Every service on the pair as a real `<table>` — departs, arrives, duration,
+stops, operator with its rating, price — sorted by departure time. This is the
+part of Tier 3 that actually ranks: dense, unique to the pair, and made of the
+words somebody types, without a sentence of written copy. No interactivity, so
+a prerendered snapshot shows a non-JS crawler exactly what a reader sees.
+
+A sticky in-page nav (Trips · Facts · Timetable) so somebody who landed from a
+search engine can reach the timetable without scrolling past a booking form
+they have not decided to use. The wizard itself is untouched — this is a
+layout around it, not a change to the funnel.
+
+Facts and the timetable share ONE request. Two components each fetching the
+same response would have doubled what the prerender crawl costs on every pair.
+
+No "type" or "class" column, which the roadmap asked for: every route in this
+system is typed `international` and the bus names are inventory identifiers
+like "A100". A column that says nothing on every row reads as padding.
+
+## 1.15.0
+
+Distance is now measured along the route's own stops rather than as one line
+from origin to destination, and the facts payload carries two numbers instead
+of one: `road`, real driving distance from a routing service, and `approx`,
+the straight lines summed stop by stop.
+
+Real road distance prints plainly. The approximation prints with a caveat,
+because it understates every journey — 309 km against 401 km of actual tarmac
+on Tirana–Thessaloniki via Korça, a 23% shortfall. A straight line is the
+shortest path there is, so no number of extra points can ever close that gap.
+
+## 1.14.0
+
+The facts block on a route-pair page: fares from, journey time, first and last
+departure, how many run, distance and who operates it.
+
+Read off the timetable rather than a dated search, so it does not change with
+the date in the URL — a "from EUR 12" that moved depending on which day a
+crawler arrived would look unstable to a search engine and dishonest to a
+reader who came back.
+
+Distance is labelled "straight line" because that is what it is: we hold city
+coordinates, not routing data, so the figure is always shorter than the road.
+
+Renders nothing at all for a pair with no facts. An empty facts block is worse
+than none — it is the thin content this tier exists to remove.
+
+## 1.13.0
+
+The operator's rating on each result card. The operator's rather than the
+route's: a single route rarely has enough published reviews to clear the
+display threshold, and a card with a rating beats one without.
+
 ## [1.12.0] - 2026-08-01
 
 ### Removed

package/Facts/Facts.tsx

@@ -0,0 +1,119 @@
+import { TFunction } from 'i18next';
+import { Container, Grid, Fact, Label, Value, Note, Operators } from './styles';
+import { FactsData } from './types';
+
+interface Props {
+  id: string
+  // Edited: Ferjolt Ozuni - Date: 2026-08-03
+  // Handed in rather than fetched here. The schedule table is built from the
+  // same response, and two components each running the same query would have
+  // meant the prerender crawl paying for every pair twice.
+  facts: FactsData
+  t: TFunction<'common'>
+}
+
+/**
+ * The facts about this city pair.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ *
+ * Roadmap Tier 3.2. What somebody searching "Tirana to Durres bus" wants
+ * answered before they trust the page: cost, length, when the first and last
+ * coach go, how many there are, how far, and who runs it.
+ *
+ * Everything here is read off the TIMETABLE rather than a dated search, so it
+ * does not change with the date in the URL. That is deliberate: a "from EUR
+ * 12" that moved depending on which day a crawler arrived would look unstable
+ * to a search engine and dishonest to a reader who came back.
+ *
+ * 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.
+ */
+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
+    })
+  );
+
+  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) }`)
+    : null;
+
+  return (
+    <Container id={ id } className="box">
+      <h2>{ t('routes_order.facts.title', { from: facts.from, to: facts.to }) }</h2>
+
+      <Grid>
+        { facts.price_from_display && (
+          <Fact>
+            <Label>{ t('routes_order.facts.price') }</Label>
+            <Value>{ facts.price_from_display }</Value>
+          </Fact>
+        ) }
+
+        { range && (
+          <Fact>
+            <Label>{ t('routes_order.facts.duration') }</Label>
+            <Value>{ range }</Value>
+          </Fact>
+        ) }
+
+        { facts.departure_first && (
+          <Fact>
+            <Label>{ t('routes_order.facts.first') }</Label>
+            <Value>{ facts.departure_first }</Value>
+          </Fact>
+        ) }
+
+        { facts.departure_last && (
+          <Fact>
+            <Label>{ t('routes_order.facts.last') }</Label>
+            <Value>{ facts.departure_last }</Value>
+          </Fact>
+        ) }
+
+        <Fact>
+          <Label>{ t('routes_order.facts.departures') }</Label>
+          <Value>{ facts.departures }</Value>
+        </Fact>
+
+        { facts.distance && (
+          <Fact>
+            <Label>{ t('routes_order.facts.distance') }</Label>
+
+            <Value>
+              { t('routes_order.facts.distance_value', {
+                km: facts.distance.road ?? facts.distance.approx
+              }) }
+
+              { /* The caveat appears only on the approximation. A real road
+                   distance needs no apology; a sum of straight lines does,
+                   because it understates every journey - 309 km against 401
+                   km of tarmac on Tirana-Thessaloniki. Printing that bare, as
+                   though it were the driving distance, would be quietly wrong
+                   on every single pair. */ }
+              { facts.distance.road === null && (
+                <Note>{ t('routes_order.facts.distance_note') }</Note>
+              ) }
+            </Value>
+          </Fact>
+        ) }
+      </Grid>
+
+      { facts.operators.length > 0 && (
+        <Operators>
+          { t('routes_order.facts.operators', { operators: facts.operators.join(', ') }) }
+        </Operators>
+      ) }
+    </Container>
+  );
+};
+
+export default Facts;

package/Facts/services.ts

@@ -0,0 +1,19 @@
+import { UseQueryResult, useQuery } from '@tanstack/react-query';
+import { apiClient } from '@autobusal/providers';
+import { FactsResponse } from './types';
+
+export const useGetFacts = (from?: string, to?: string): UseQueryResult<FactsResponse> => (
+  useQuery({
+    queryKey: ['route-facts', from, to],
+    queryFn: async () => (
+      await apiClient
+        .get('/api/routes/search/facts', {
+          params: { from, to }
+        })
+        .then(response => (
+          response.data
+        ))
+    ),
+    enabled: Boolean(from && to)
+  })
+);

package/Facts/styles.ts

@@ -0,0 +1,48 @@
+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;
+`;

package/Facts/types.ts

@@ -0,0 +1,47 @@
+export interface FactsData {
+  from: string
+  to: string
+  // 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
+  // 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[]
+  // 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
+  minutes: number | null
+  // 0 is a direct service
+  stops: number
+  price: string
+}
+
+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
+}

package/Found/Route/Route.tsx

@@ -4,7 +4,7 @@ import { HiOutlineArrowNarrowRight, HiOutlineDocumentText } from 'react-icons/hi
 import { BiHourglass } from 'react-icons/bi';
 import { RiBus2Line } from 'react-icons/ri';
 import { formatDuration, splitPrice } from '../refine';
-import { Button, RouteFeature, Policy } from '@autobusal/common';
+import { Button, RouteFeature, Policy, Rating } from '@autobusal/common';
 import { Container, SpecialOffer, FavoriteStop, Trip, Company, Location, Stop, Iso, Time, Price, Amount, Decimals, Currency, PriceNotice, LinkCompany, Details, Detail, ButtonPolicy, TitleDetail, LinkRoute, FeaturesItems } from './styles';
 import { FoundData } from '@autobusal/providers/types/routes';
 
@@ -55,6 +55,14 @@ const Route = ({ data, type, passengers, t, onSave, children }: Props): JSX.Elem
       <Trip>
         <Company>
           <LinkCompany to={ bookOnUrl ?? data.operator.link } target="_blank" rel="noopener noreferrer" title={ data.operator.company }><img src={ data.operator.logo_url || LOGO_FALLBACK } onError={ (e) => { e.currentTarget.onerror = null; e.currentTarget.src = LOGO_FALLBACK; } } alt={ data.operator.company } /></LinkCompany>
+
+          { /* Edited: Ferjolt Ozuni - Date: 2026-08-03
+               The OPERATOR's rating rather than this route's: a single route
+               rarely has enough published reviews to clear the display
+               threshold, and a card with a rating beats one without. Renders
+               nothing when there is no rating yet, which is why a brand-new
+               operator does not look like a badly rated one. */ }
+          <Rating rating={ data.operator.rating } size="small" t={ t } />
         </Company>
 
         <Location>

package/Found/Route/styles.ts

@@ -63,6 +63,17 @@ export const Trip = styled.div`
 export const Company = styled.div`
   flex-basis: 100%;
 
+  /**
+   * Edited: Ferjolt Ozuni - Date: 2026-08-03
+   * A column now, because the operator's rating sits under the logo. Left
+   * as a bare block it would have laid the stars out beside the logo and
+   * eaten the 185px this cell gets on desktop.
+   */
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  align-items: flex-start;
+
   @media (min-width: 1024px) {
     flex: 0 0 185px;
   }

package/RoutesOrder.tsx

@@ -8,6 +8,7 @@ import { useGetSettings } from '@autobusal/providers/services';
 import RoutesSearch from '@autobusal/routes-search';
 import { useGetSuggestions } from '@autobusal/routes-search/services';
 import { SearchAgain, SearchInner, SearchToggle, SearchSummary, SearchPanel } from './styles';
+import Sections from './Sections/Sections';
 import Step1 from './Step1/Step1';
 import Step2 from './Step2';
 import Step3 from './Step3';
@@ -163,6 +164,13 @@ const RoutesOrder = ({ t }: Props): JSX.Element => {
         />
       ) }
 
+      { /* Edited: Ferjolt Ozuni - Date: 2026-08-03
+           The anchor the section nav's "Trips" link lands on. A plain
+           wrapper: the wizard inside is untouched, which is the whole point
+           of Tier 3.1 - the funnel keeps working exactly as it did and the
+           new sections sit around it. */ }
+      <div id="trips">
+
       { showStep2 && (
         <Step2
           step1={ step1 }
@@ -184,6 +192,25 @@ const RoutesOrder = ({ t }: Props): JSX.Element => {
         />
       ) }
 
+      { /* Edited: Ferjolt Ozuni - Date: 2026-08-03
+           Roadmap Tier 3.2. Only on the route-choosing screens, and only
+           once the URL names a real pair: this is the page a search engine
+           lands on, and it is the one place the block adds anything. Past
+           step 2 the reader has picked a coach and is filling in passenger
+           details - facts about the pair are noise at that point.
+
+           It renders nothing at all for a pair with no facts, so a page that
+           would only have gained an empty box does not gain a box. */ }
+      { (showStep2 || showStep3) && (
+        <Sections
+          from={ fromCity?.slug ?? params.from }
+          to={ toCity?.slug ?? params.to }
+          t={ t }
+        />
+      ) }
+
+      </div>
+
       { showCheckout && (
         <Checkout
           values={ step4 }

package/Schedule/Schedule.tsx

@@ -0,0 +1,110 @@
+import { TFunction } from 'i18next';
+import { Rating } from '@autobusal/common';
+import { Container, Table, Time, Faded, Price, Operator } from './styles';
+import { ScheduleRow } from '../Facts/types';
+
+interface Props {
+  id: string
+  from: string
+  to: string
+  rows: ScheduleRow[]
+  t: TFunction<'common'>
+}
+
+/**
+ * Every service on this city pair, as a table.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ *
+ * Roadmap Tier 3.3, and the part of this tier that actually ranks. A page
+ * about "Tirana to Durres bus" competes on being dense, unique to the pair,
+ * and made of the words somebody types - and a timetable is all three at
+ * once, without a single sentence of written copy.
+ *
+ * A real <table>, not a grid of divs, because this genuinely is tabular data:
+ * the same structure that makes it readable is what lets a crawler
+ * understand the columns. No interactivity at all, so a prerendered snapshot
+ * shows a non-JS crawler exactly what a reader sees.
+ *
+ * Sorted by departure, server-side. Price order would scatter the day and
+ * make the table useless for the thing people actually do with a timetable,
+ * which is plan around a time.
+ */
+const Schedule = ({ id, from, to, rows, t }: Props): (JSX.Element | null) => {
+  if (rows.length === 0) {
+    return null;
+  }
+
+  const duration = (minutes: number | null): string => {
+    if (minutes === null) {
+      return '-';
+    }
+
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+
+    // "8h 0m" is a number pretending to be a measurement
+    return rest === 0
+      ? t('routes_order.facts.duration_hours', { hours })
+      : t('routes_order.facts.duration_value', { hours, minutes: rest });
+  };
+
+  return (
+    <Container id={ id } className="box">
+      <h2>{ t('routes_order.schedule.title', { from, to }) }</h2>
+
+      <Table>
+        <thead>
+          <tr>
+            <th>{ t('routes_order.schedule.departure') }</th>
+            <th>{ t('routes_order.schedule.arrival') }</th>
+            <th>{ t('routes_order.schedule.duration') }</th>
+            <th>{ t('routes_order.schedule.stops') }</th>
+            <th>{ t('routes_order.schedule.operator') }</th>
+            <th>{ t('routes_order.schedule.price') }</th>
+          </tr>
+        </thead>
+
+        <tbody>
+          { rows.map((row, index) => (
+            <tr key={ index }>
+              <td><Time>{ row.departure ?? '-' }</Time></td>
+              <td><Time>{ row.arrival ?? '-' }</Time></td>
+              <td><Faded>{ duration(row.minutes) }</Faded></td>
+
+              <td>
+                { /* "Direct" is the word people scan for; "0 stops" makes
+                     the reader do that translation themselves.
+                     
+                     Above zero it is the bare NUMBER, not "{{count}} stops":
+                     the column header already says Stops, and an interpolated
+                     noun rendered "1 stops" - this codebase has no i18next
+                     plural forms anywhere, and adding them for one cell would
+                     mean getting three-form Slavic plurals right in fifteen
+                     languages to say something the header already said. */ }
+                <Faded>
+                  { row.stops === 0 ? t('routes_order.schedule.direct') : row.stops }
+                </Faded>
+              </td>
+
+              <td>
+                <Operator>
+                  { row.operator ?? '-' }
+
+                  { /* Renders nothing until the operator has enough
+                       published reviews - see Tier 2. A new operator must
+                       not read as a badly rated one. */ }
+                  <Rating rating={ row.rating } size="small" t={ t } />
+                </Operator>
+              </td>
+
+              <td><Price>{ row.price }</Price></td>
+            </tr>
+          )) }
+        </tbody>
+      </Table>
+    </Container>
+  );
+};
+
+export default Schedule;

package/Schedule/styles.ts

@@ -0,0 +1,53 @@
+import styled from 'styled-components';
+
+export const Container = styled.section`
+  margin-top: 25px;
+  overflow-x: auto;
+`;
+
+/**
+ * A real table, because this IS tabular data - the same reason a crawler
+ * understands it. Scrolls inside its own container on a narrow screen rather
+ * than pushing the page sideways.
+ */
+export const Table = styled.table`
+  width: 100%;
+  border-collapse: collapse;
+  min-width: 620px;
+
+  th, td {
+    padding: 10px 12px;
+    text-align: left;
+    border-bottom: 1px solid ${ props => props.theme.background.neutral };
+    white-space: nowrap;
+  }
+
+  th {
+    font-size: ${ props => props.theme.size.s };
+    color: ${ props => props.theme.font.faded };
+    font-weight: 400;
+  }
+
+  tbody tr:last-child td {
+    border-bottom: none;
+  }
+`;
+
+export const Time = styled.strong`
+  font-weight: 700;
+`;
+
+export const Faded = styled.span`
+  color: ${ props => props.theme.font.faded };
+`;
+
+export const Price = styled.strong`
+  font-weight: 700;
+  white-space: nowrap;
+`;
+
+export const Operator = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+`;

package/Sections/Sections.tsx

@@ -0,0 +1,68 @@
+import { TFunction } from 'i18next';
+import Facts from '../Facts/Facts';
+import Schedule from '../Schedule/Schedule';
+import { useGetFacts } from '../Facts/services';
+import { Nav, Anchor, Anchored } from './styles';
+
+interface Props {
+  from?: string
+  to?: string
+  t: TFunction<'common'>
+}
+
+const TRIPS = 'trips';
+const FACTS = 'facts';
+const SCHEDULE = 'schedule';
+
+/**
+ * Everything on a route-pair page that is not the booking wizard.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-03
+ *
+ * Roadmap Tier 3.1. The wizard stays exactly where it is and keeps working
+ * exactly as it did - this is a layout around it, not a rewrite of the
+ * funnel. Somebody who arrived ready to book still books; somebody who
+ * arrived from a search engine asking "how long does that take" now has an
+ * answer without scrolling through a form first.
+ *
+ * ONE fetch for both sections. Facts and Schedule are built from the same
+ * response, and letting each fetch its own would have doubled what the
+ * prerender crawl costs on every pair in the sitemap.
+ *
+ * The nav renders only when there is more than the wizard to navigate to -
+ * a bar whose only link is "Trips" is furniture.
+ */
+const Sections = ({ from, to, t }: Props): (JSX.Element | null) => {
+  const { data } = useGetFacts(from, to);
+
+  const facts = data?.facts;
+
+  if (!facts) {
+    return null;
+  }
+
+  const schedule = facts.schedule ?? [];
+
+  return (
+    <>
+      <Nav aria-label={ t('routes_order.sections.label') }>
+        <Anchor href={ `#${ TRIPS }` }>{ t('routes_order.sections.trips') }</Anchor>
+        <Anchor href={ `#${ FACTS }` }>{ t('routes_order.sections.facts') }</Anchor>
+
+        { schedule.length > 0 && (
+          <Anchor href={ `#${ SCHEDULE }` }>{ t('routes_order.sections.schedule') }</Anchor>
+        ) }
+      </Nav>
+
+      <Anchored>
+        <Facts id={ FACTS } facts={ facts } t={ t } />
+      </Anchored>
+
+      <Anchored>
+        <Schedule id={ SCHEDULE } from={ facts.from } to={ facts.to } rows={ schedule } t={ t } />
+      </Anchored>
+    </>
+  );
+};
+
+export default Sections;

package/Sections/styles.ts

@@ -0,0 +1,44 @@
+import styled from 'styled-components';
+
+/**
+ * The in-page nav.
+ *
+ * Sticky, because the sections below it are long and the whole point is to
+ * let somebody who landed from a search engine jump to the part they came
+ * for - a timetable, usually - without scrolling past a booking wizard they
+ * have not decided to use yet.
+ */
+export const Nav = styled.nav`
+  position: sticky;
+  top: 0;
+  z-index: 20;
+  display: flex;
+  gap: 6px;
+  overflow-x: auto;
+  margin-top: 25px;
+  padding: 8px 10px;
+  border-radius: ${ props => props.theme.borderRadius };
+  background: ${ props => props.theme.background.normal };
+  box-shadow: 0 2px 10px rgba(0, 0, 0, .06);
+`;
+
+export const Anchor = styled.a`
+  padding: 6px 14px;
+  border-radius: ${ props => props.theme.borderRadius };
+  font-size: ${ props => props.theme.size.s };
+  color: ${ props => props.theme.font.normal };
+  white-space: nowrap;
+
+  &:hover {
+    text-decoration: none;
+    background: ${ props => props.theme.background.neutral };
+  }
+`;
+
+/**
+ * Anchored sections need somewhere to land that is not under the sticky bar
+ * above them.
+ */
+export const Anchored = styled.div`
+  scroll-margin-top: 60px;
+`;

package/package.json

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