@autobusal/routes-order 1.8.0 → 1.9.1

package/Found/refine.ts

@@ -0,0 +1,652 @@
+import { TFunction } from 'i18next';
+import { FoundData } from '@autobusal/providers/types/routes';
+
+/**
+ * Sorting, filtering and facet counting for the results list.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * All of it runs client-side against the array the search already returned:
+ * every field needed is on `FoundData`, so refining the list costs no extra
+ * request and stays instant while the user plays with the controls.
+ *
+ * One rule runs through the whole file: **an external-provider offer must
+ * never be filtered out by a facet it cannot report.** Those rows carry an
+ * operator and a price but no local stop ids, no `stops_count` and no
+ * amenity list, so a naive predicate would quietly delete paid partner
+ * inventory from the results. Every predicate below treats "the row cannot
+ * answer this question" as a pass, not a fail.
+ */
+
+export type SortKey = 'recommended' | 'cheapest' | 'fastest' | 'earliest' | 'latest';
+
+export type BucketKey = '0' | '6' | '12' | '18';
+
+export const SORTS: SortKey[] = [ 'recommended', 'cheapest', 'fastest', 'earliest', 'latest' ];
+
+export const BUCKETS: BucketKey[] = [ '0', '6', '12', '18' ];
+
+export interface Refinement {
+  sort: SortKey
+  operators: number[]
+  buckets: BucketKey[]
+  direct: boolean
+  fromStops: number[]
+  toStops: number[]
+  features: number[]
+  maxPrice: number | null
+}
+
+export interface FacetValue {
+  value: number
+  label: string
+  count: number
+  from: number | null
+  fromDisplay: string | null
+}
+
+export interface Facets {
+  operators: FacetValue[]
+  buckets: FacetValue[]
+  fromStops: FacetValue[]
+  toStops: FacetValue[]
+  features: FacetValue[]
+  direct: number
+  hasDirect: boolean
+}
+
+export const EMPTY: Refinement = {
+  sort: 'recommended',
+  operators: [],
+  buckets: [],
+  direct: false,
+  fromStops: [],
+  toStops: [],
+  features: [],
+  maxPrice: null
+};
+
+/**
+ * "HH:MM" as minutes past midnight. Anything unparseable is 0 rather than
+ * NaN, which would poison every comparison it touched.
+ */
+export const minutesOf = (time?: string): number => {
+  const [ hours, minutes ] = (time ?? '').split(':');
+
+  const value = Number(hours) * 60 + Number(minutes);
+
+  return Number.isFinite(value) ? value : 0;
+};
+
+export const departureOf = (item: FoundData): number => (
+  minutesOf(item.locations.from.departure)
+);
+
+/**
+ * Trip length in minutes, or null when obtapi could not compute one.
+ *
+ * `Locations::duration()` emits a literal "-" when the arithmetic comes out
+ * negative (bad location times on the route). Parsing that as 0 would make
+ * a broken route the "fastest" trip on the page and float it to the top of
+ * the list, so it stays null and sorts last.
+ */
+export const durationOf = (item: FoundData): number | null => {
+  if (!item.duration || item.duration === '-') {
+    return null;
+  }
+
+  return minutesOf(item.duration);
+};
+
+/**
+ * Turn obtapi's "HH:MM" trip length into something that reads as a
+ * duration rather than a clock time.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * "08:30" sitting between two departure times is genuinely ambiguous -
+ * nothing about it says "eight and a half hours" rather than "half past
+ * eight", and on this card it sits directly between 09:00 and 16:30. The
+ * unit labels come from the translation files because "h"/"m" are not
+ * universal; Greek and the Cyrillic locales carry their own.
+ *
+ * The "-" sentinel (obtapi could not compute a duration) passes straight
+ * through - it must not become "0h 0m", which would read as a real answer.
+ */
+export const formatDuration = (duration: string, t: TFunction<'common'>): string => {
+  if (!duration || duration === '-') {
+    return duration;
+  }
+
+  const total = minutesOf(duration);
+
+  const hours = Math.floor(total / 60);
+  const minutes = total % 60;
+
+  const pad = (value: number): string => (value <= 9 ? `0${ value }` : String(value));
+
+  const parts: string[] = [];
+
+  if (hours > 0) {
+    parts.push(t('routes_order.step2.route.duration.hours', { value: pad(hours) }));
+  }
+
+  // a trip under an hour still needs a number, and so does an exact
+  // number of hours - but "08h 00m" is noise, so zero minutes are dropped
+  if (minutes > 0 || hours === 0) {
+    parts.push(t('routes_order.step2.route.duration.minutes', { value: pad(minutes) }));
+  }
+
+  return parts.join(' ');
+};
+
+/**
+ * Split obtapi's formatted price into its parts so the decimals can be set
+ * as superscript.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * obtapi sends a rendered string ("1,048.00 EUR" - number_format, so the
+ * thousands separator is a comma and the decimal point a dot). Splitting it
+ * here rather than reformatting from `price.value` keeps the label's own
+ * currency and formatting as the single source of truth; we only decide how
+ * big each piece is drawn.
+ *
+ * Anything that does not match the expected shape is returned whole, so an
+ * unusual currency format degrades to today's rendering instead of being
+ * mangled.
+ */
+export const splitPrice = (display: string): { whole: string, decimals: string | null, currency: string | null } => {
+  const match = /^(.+)\.(\d{2})\s+(\S+)$/.exec(display ?? '');
+
+  if (match === null) {
+    return { whole: display ?? '', decimals: null, currency: null };
+  }
+
+  return { whole: match[1], decimals: match[2], currency: match[3] };
+};
+
+export const bucketOf = (item: FoundData): BucketKey => {
+  const hour = Math.floor(departureOf(item) / 60);
+
+  if (hour < 6) {
+    return '0';
+  }
+
+  if (hour < 12) {
+    return '6';
+  }
+
+  if (hour < 18) {
+    return '12';
+  }
+
+  return '18';
+};
+
+const featuresOf = (item: FoundData): number[] | null => {
+  const features = item.trip?.features_data;
+
+  // null = the row cannot answer, so amenity filters must not judge it
+  return Array.isArray(features) ? features.map(feature => feature.id) : null;
+};
+
+/**
+ * Read the refinement out of the URL so a filtered result set survives a
+ * reload and can be pasted to somebody else.
+ */
+export const fromParams = (params: URLSearchParams): Refinement => {
+  const numbers = (name: string): number[] => (
+    (params.get(name) ?? '')
+      .split(',')
+      .map(Number)
+      .filter(value => Number.isFinite(value) && value > 0)
+  );
+
+  const sort = params.get('sort') as SortKey | null;
+
+  const maxPrice = Number(params.get('max_price'));
+
+  return {
+    sort: sort && SORTS.includes(sort) ? sort : 'recommended',
+    operators: numbers('operators'),
+    buckets: (params.get('times') ?? '').split(',').filter(value => BUCKETS.includes(value as BucketKey)) as BucketKey[],
+    direct: params.get('direct') === '1',
+    fromStops: numbers('from_stops'),
+    toStops: numbers('to_stops'),
+    features: numbers('features'),
+    maxPrice: Number.isFinite(maxPrice) && maxPrice > 0 ? maxPrice : null
+  };
+};
+
+/**
+ * Only non-default values are written, so an untouched page keeps a clean
+ * URL and the search's own query parameters stay readable.
+ */
+export const toParams = (refinement: Refinement): Record<string, string> => {
+  const params: Record<string, string> = {};
+
+  if (refinement.sort !== 'recommended') {
+    params.sort = refinement.sort;
+  }
+
+  if (refinement.operators.length > 0) {
+    params.operators = refinement.operators.join(',');
+  }
+
+  if (refinement.buckets.length > 0) {
+    params.times = refinement.buckets.join(',');
+  }
+
+  if (refinement.direct) {
+    params.direct = '1';
+  }
+
+  if (refinement.fromStops.length > 0) {
+    params.from_stops = refinement.fromStops.join(',');
+  }
+
+  if (refinement.toStops.length > 0) {
+    params.to_stops = refinement.toStops.join(',');
+  }
+
+  if (refinement.features.length > 0) {
+    params.features = refinement.features.join(',');
+  }
+
+  if (refinement.maxPrice !== null) {
+    params.max_price = String(refinement.maxPrice);
+  }
+
+  return params;
+};
+
+export const isRefined = (refinement: Refinement): boolean => (
+  Object.keys(toParams({ ...refinement, sort: 'recommended' })).length > 0
+);
+
+type Facet = 'operators' | 'buckets' | 'direct' | 'fromStops' | 'toStops' | 'features' | 'maxPrice';
+
+/**
+ * Whether a row survives the refinement. `except` drops one facet from the
+ * test, which is how each facet's own counts are computed against the
+ * *other* active filters - the behaviour people expect from faceted search,
+ * where ticking one operator doesn't zero out every other operator's count.
+ */
+export const matches = (item: FoundData, refinement: Refinement, except?: Facet): boolean => {
+  if (except !== 'operators' && refinement.operators.length > 0) {
+    if (!refinement.operators.includes(item.operator.id)) {
+      return false;
+    }
+  }
+
+  if (except !== 'buckets' && refinement.buckets.length > 0) {
+    if (!refinement.buckets.includes(bucketOf(item))) {
+      return false;
+    }
+  }
+
+  // undefined stops_count = an external offer that doesn't report stops
+  if (except !== 'direct' && refinement.direct && item.stops_count !== undefined) {
+    if (item.stops_count > 0) {
+      return false;
+    }
+  }
+
+  if (except !== 'fromStops' && refinement.fromStops.length > 0) {
+    const stop = item.locations.from.stop?.id;
+
+    if (stop !== undefined && !refinement.fromStops.includes(stop)) {
+      return false;
+    }
+  }
+
+  if (except !== 'toStops' && refinement.toStops.length > 0) {
+    const stop = item.locations.to.stop?.id;
+
+    if (stop !== undefined && !refinement.toStops.includes(stop)) {
+      return false;
+    }
+  }
+
+  if (except !== 'features' && refinement.features.length > 0) {
+    const features = featuresOf(item);
+
+    // every ticked amenity must be present - narrowing, not widening
+    if (features !== null && !refinement.features.every(id => features.includes(id))) {
+      return false;
+    }
+  }
+
+  if (except !== 'maxPrice' && refinement.maxPrice !== null) {
+    if (item.price.value > refinement.maxPrice) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Duration comparison that sinks routes with no computable duration to the
+ * bottom, rather than letting obtapi's "-" sentinel pose as a zero-minute
+ * trip and win "fastest".
+ */
+const byDuration = (a: FoundData, b: FoundData): number => {
+  const first = durationOf(a);
+  const second = durationOf(b);
+
+  if (first === null && second === null) {
+    return 0;
+  }
+
+  if (first === null) {
+    return 1;
+  }
+
+  if (second === null) {
+    return -1;
+  }
+
+  return first - second;
+};
+
+/**
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * Every sort carries a tiebreak on the other axis, because the head of the
+ * list is also what the quick-pick cards advertise. Without it, three trips
+ * tied at the same journey time meant "fastest" could headline the dearest
+ * of them - true, but a useless thing to show somebody.
+ */
+const compare = (sort: SortKey) => (a: FoundData, b: FoundData): number => {
+  switch (sort) {
+    case 'cheapest':
+      return (a.price.value - b.price.value) || byDuration(a, b);
+
+    case 'earliest':
+      return (departureOf(a) - departureOf(b)) || (a.price.value - b.price.value);
+
+    case 'latest':
+      return (departureOf(b) - departureOf(a)) || (a.price.value - b.price.value);
+
+    case 'fastest':
+      return byDuration(a, b) || (a.price.value - b.price.value);
+
+    default:
+      return 0;
+  }
+};
+
+/**
+ * Dense rank of each item under a scoring function, best (lowest) first.
+ * Equal values share a rank, so ten identically priced trips are all "the
+ * cheapest" rather than being arbitrarily spread over ten positions.
+ */
+const rankBy = (items: FoundData[], score: (item: FoundData) => number | null): Map<FoundData, number> => {
+  const known = items.filter(item => score(item) !== null);
+
+  const values = [ ...new Set(known.map(item => score(item) as number)) ].sort((a, b) => a - b);
+
+  const ranks = new Map<FoundData, number>();
+
+  items.forEach(item => {
+    const value = score(item);
+
+    // an unscoreable item ranks below every scoreable one
+    ranks.set(item, value === null ? values.length : values.indexOf(value));
+  });
+
+  return ranks;
+};
+
+/**
+ * "Recommended" ordering.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * Merit first: a trip's standing is its price rank plus its duration rank,
+ * both computed across the current result set. The operator's paid
+ * subscription priority is only a TIEBREAK between trips that are already
+ * equal on both - it cannot buy its way past a cheaper or faster
+ * competitor. That is a deliberate commercial decision (Ferjolt, 2026-08-01)
+ * and it is the answer if anyone asks what the word means on this page.
+ *
+ * Departure time is the final tiebreak, so the order stays stable and
+ * predictable rather than depending on the array's incoming arrangement.
+ */
+const recommend = (items: FoundData[]): FoundData[] => {
+  const price = rankBy(items, item => item.price.value);
+  const duration = rankBy(items, item => durationOf(item));
+
+  const score = (item: FoundData): number => (price.get(item) ?? 0) + (duration.get(item) ?? 0);
+
+  return [ ...items ].sort((a, b) => (
+    score(a) - score(b)
+      || (b.priority ?? 0) - (a.priority ?? 0)
+      || departureOf(a) - departureOf(b)
+  ));
+};
+
+/**
+ * Sort a list without touching the caller's array.
+ */
+export const sortItems = (items: FoundData[], sort: SortKey): FoundData[] => {
+  if (sort === 'recommended') {
+    return recommend(items);
+  }
+
+  return [ ...items ].sort(compare(sort));
+};
+
+export const filterItems = (items: FoundData[], refinement: Refinement): FoundData[] => (
+  items.filter(item => matches(item, refinement))
+);
+
+/**
+ * Collapse interchangeable departures into one entry.
+ *
+ * Edited: Ferjolt Ozuni - Date: 2026-08-01
+ *
+ * Hourly shuttle service is the dominant Albanian intercity pattern, so a
+ * busy pair renders a wall of rows that differ only in the departure time -
+ * the same operator, the same two stops, the same fare, the same journey
+ * length. Those are one product with a choice of time, and reading them as
+ * twenty separate options is what makes the page tiring.
+ *
+ * Duration and price are BOTH in the key on purpose: without them a slower
+ * or dearer trip would hide inside a group under a headline it doesn't
+ * honour. External offers are keyed by their own id so they never merge
+ * with anything - they carry no stop ids, and grouping on missing values
+ * would fuse unrelated partner inventory into a single row.
+ *
+ * Input order is preserved, so a group lands wherever its best member
+ * sorted to and the caller does not have to re-sort.
+ */
+export const groupItems = (items: FoundData[]): FoundData[][] => {
+  const groups = new Map<string, FoundData[]>();
+  const order: string[] = [];
+
+  items.forEach(item => {
+    const key = item.external
+      ? `ext:${ item.id }`
+      : [
+          item.operator.id,
+          item.locations.from.stop?.id ?? '-',
+          item.locations.to.stop?.id ?? '-',
+          item.price.value,
+          item.duration
+        ].join('|');
+
+    if (!groups.has(key)) {
+      groups.set(key, []);
+      order.push(key);
+    }
+
+    groups.get(key)?.push(item);
+  });
+
+  return order.map(key => groups.get(key) as FoundData[]);
+};
+
+const countBy = (
+  items: FoundData[],
+  refinement: Refinement,
+  except: Facet,
+  keys: (item: FoundData) => { value: number, label: string }[]
+): FacetValue[] => {
+  const found = new Map<number, FacetValue>();
+
+  // Pass one establishes the value universe from the WHOLE result set, so a
+  // facet keeps its shape as boxes get ticked. Building it only from
+  // matching rows instead made options vanish mid-interaction - narrow to
+  // one operator and the operator group disappeared entirely, taking the
+  // way back out with it.
+  items.forEach(item => {
+    keys(item).forEach(({ value, label }) => {
+      if (!found.has(value)) {
+        found.set(value, { value, label, count: 0, from: null, fromDisplay: null });
+      }
+    });
+  });
+
+  // pass two counts against the other active filters, leaving impossible
+  // values at zero to be rendered disabled rather than removed
+  items.forEach(item => {
+    if (!matches(item, refinement, except)) {
+      return;
+    }
+
+    keys(item).forEach(({ value }) => {
+      const existing = found.get(value);
+
+      if (existing === undefined) {
+        return;
+      }
+
+      existing.count += 1;
+
+      if (existing.from === null || item.price.value < existing.from) {
+        existing.from = item.price.value;
+        existing.fromDisplay = item.price.display;
+      }
+    });
+  });
+
+  return [ ...found.values() ].sort((a, b) => a.label.localeCompare(b.label));
+};
+
+/**
+ * Every facet value present in the result set, each with how many rows it
+ * would leave and the cheapest fare behind it. Values are kept even at a
+ * count of zero so the panel doesn't reshuffle under the cursor as boxes
+ * get ticked - they render disabled instead of vanishing.
+ */
+export const buildFacets = (items: FoundData[], refinement: Refinement, bucketLabel: (key: BucketKey) => string): Facets => {
+  const operators = countBy(items, refinement, 'operators', item => [
+    { value: item.operator.id, label: item.operator.company }
+  ]);
+
+  // same two-pass shape as countBy: a bucket is listed when the unfiltered
+  // result set has anything in it, and counted against the other filters
+  const buckets = BUCKETS
+    .filter(key => items.some(item => bucketOf(item) === key))
+    .map(key => {
+      const inBucket = items.filter(item => bucketOf(item) === key && matches(item, refinement, 'buckets'));
+
+      const cheapest = inBucket.reduce<FoundData | null>((best, item) => (
+        best === null || item.price.value < best.price.value ? item : best
+      ), null);
+
+      return {
+        value: Number(key),
+        label: bucketLabel(key),
+        count: inBucket.length,
+        from: cheapest?.price.value ?? null,
+        fromDisplay: cheapest?.price.display ?? null
+      };
+    });
+
+  const fromStops = countBy(items, refinement, 'fromStops', item => (
+    item.locations.from.stop ? [ { value: item.locations.from.stop.id, label: item.locations.from.stop.name } ] : []
+  ));
+
+  const toStops = countBy(items, refinement, 'toStops', item => (
+    item.locations.to.stop ? [ { value: item.locations.to.stop.id, label: item.locations.to.stop.name } ] : []
+  ));
+
+  /**
+   * Amenities are the one AND group: every ticked box must be present on
+   * the row, so "how many if I drop this whole group" - the right question
+   * for the OR groups above - would advertise 8 results next to WC while
+   * the page shows 1. These count what ticking the box would actually
+   * leave, which is the number the user is really asking for.
+   */
+  const features = (() => {
+    const universe = new Map<number, string>();
+
+    items.forEach(item => {
+      (item.trip?.features_data ?? []).forEach(feature => {
+        if (!universe.has(feature.id)) {
+          universe.set(feature.id, feature.name);
+        }
+      });
+    });
+
+    return [ ...universe.entries() ].map(([ value, label ]) => {
+      const selected = refinement.features.includes(value);
+
+      const candidate = selected ? refinement : { ...refinement, features: [ ...refinement.features, value ] };
+
+      const matching = items.filter(item => matches(item, candidate));
+
+      const cheapest = matching.reduce<FoundData | null>((best, item) => (
+        best === null || item.price.value < best.price.value ? item : best
+      ), null);
+
+      return {
+        value,
+        label,
+        count: matching.length,
+        from: cheapest?.price.value ?? null,
+        fromDisplay: cheapest?.price.display ?? null
+      };
+    }).sort((a, b) => a.label.localeCompare(b.label));
+  })();
+
+  const direct = items.filter(item => item.stops_count === 0 && matches(item, refinement, 'direct')).length;
+
+  // whether to OFFER the control at all, as opposed to what it would leave -
+  // the group stays put at a count of zero, like every other facet
+  const hasDirect = items.some(item => item.stops_count === 0);
+
+  return { operators, buckets, fromStops, toStops, features, direct, hasDirect };
+};
+
+export const priceRange = (items: FoundData[]): { min: number, max: number, minDisplay: string, maxDisplay: string } | null => {
+  if (items.length === 0) {
+    return null;
+  }
+
+  const sorted = [ ...items ].sort((a, b) => a.price.value - b.price.value);
+
+  const cheapest = sorted[0];
+  const dearest = sorted[sorted.length - 1];
+
+  return {
+    min: cheapest.price.value,
+    max: dearest.price.value,
+    minDisplay: cheapest.price.display,
+    maxDisplay: dearest.price.display
+  };
+};
+
+/**
+ * The label's currency as obtapi formats it ("50.00 EUR" -> "EUR"), taken
+ * from a price the server already rendered rather than re-deriving it in
+ * the client. Used for values the server never formatted, like the position
+ * of the price slider.
+ */
+export const currencyOf = (items: FoundData[]): string => (
+  (items[0]?.price.display ?? '').replace(/[\d.,]/g, '').trim()
+);