@autobusal/operator-routes 1.10.0 → 1.10.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.10.1 - 2026-08-30
+
+- Staged dynamic pricing (roadmap P5): a per-route screen for the price rules - the opt-in, the operator's own caps, and the rules as a NUMBERED list read top to bottom, because the first rule whose band matches is the only one that applies. Each row says what it will actually do once the cap has had its say.
+
 ## 1.10.0 (2026-08-29)
 
 - Editors offer Save & Close alongside Save & Stay, so correcting a record no longer bounces you back to its list every time (opt-in per page, editing only).

package/Manage.tsx

@@ -4,7 +4,7 @@ import { TFunction } from 'i18next';
 import { useParams, useNavigate } from 'react-router-dom';
 import { RiMoneyEuroCircleLine } from 'react-icons/ri';
 import { FaMapMarkerAlt } from 'react-icons/fa';
-import { IoCalendarClearOutline } from 'react-icons/io5';
+import { IoCalendarClearOutline, IoPricetagsOutline } from 'react-icons/io5';
 import { Meta, BackWithTitle, Viewer } from '@autobusal/common';
 import { usePage, useBreadcrumbs, useRouteFeatures, useOperatorDrivers } from '@autobusal/hooks';
 import { success } from '@autobusal/utilities';
@@ -136,6 +136,25 @@ const Manage = ({ url, t }: Props): JSX.Element => {
             </>
           ),
           url: `/operator/routes/unavailable/${ id }`
+        }, {
+          /*
+           * Claude - 2026-08-30 (roadmap P5): staged dynamic pricing.
+           *
+           * A link, like the schedule and the unavailable dates above it: the
+           * rules are an ordered LIST whose order decides which one sets the
+           * fare, and a list that means something cannot be squeezed into one
+           * row of this form.
+           */
+          label: t('operator_routes.manage.pricing.title', { ns: 'common' }),
+          name: 'pricing',
+          type: 'link',
+          value: (
+            <>
+              <IoPricetagsOutline />
+              { t('operator_routes.manage.pricing.link', { ns: 'common' }) }
+            </>
+          ),
+          url: `/operator/routes/pricing/${ id }`
         }, {}, {
           label: t('operator_routes.manage.features', { ns: 'common' }),
           name: 'features',

package/Pricing/Manage.tsx

@@ -0,0 +1,279 @@
+import { useState } from 'react';
+import { TFunction } from 'i18next';
+import { useParams, Navigate } from 'react-router-dom';
+import { IoArrowDown, IoArrowUp } from 'react-icons/io5';
+import { Meta, BackWithTitle, Box, Button } from '@autobusal/common';
+import { usePage, useBreadcrumbs } from '@autobusal/hooks';
+import { success } from '@autobusal/utilities';
+import { Panel, Row, Note, Rules, Rule, Text, Percent, Clamped, Actions, Small, Field, Choice, Empty } from './styles';
+import { PriceRuleData } from '../types';
+import { useGetPricing, usePostPricingRule, useDeletePricingRule, useReorderPricingRules, useTogglePricing, usePostPricingCaps } from './services';
+
+interface Props {
+  url: string
+  t: TFunction<'common'>
+}
+
+const BLANK: PriceRuleData = { signal: 'days', band_from: 0, band_to: 3, percent: 10, enabled: true };
+
+/**
+ * Staged dynamic pricing for one route (roadmap P5, ruled by Ferjolt).
+ *
+ * Claude - 2026-08-30
+ *
+ * THE LIST IS THE FEATURE. The first rule whose band covers a search is the
+ * only one that applies - they do not stack - so this screen is an ordered
+ * list an operator reads top to bottom, numbered, with the move controls that
+ * decide precedence sitting on each row. Anything prettier would have hidden
+ * the single thing they need to understand about their own prices.
+ *
+ * The caps sit above the list rather than in a settings page elsewhere,
+ * because they are the sentence that makes a percentage mean something: a
+ * rule asking for 40% on an operator capped at 20 moves the fare by 20, and
+ * this screen says so on the row rather than leaving them to discover it in a
+ * search result.
+ */
+const Manage = ({ url, t }: Props): JSX.Element => {
+  const params = useParams();
+
+  const routeId = Number(params.id);
+
+  const baseUrl = url;
+  url = url.replace('[id]', String(routeId));
+
+  usePage('routes');
+
+  const { data, isLoading, refetch } = useGetPricing(routeId);
+
+  const title = t('operator_routes.pricing.title', { ns: 'common' });
+
+  // the route's own name, so the trail reads "... > Tirana - Athens > Dynamic
+  // pricing" rather than leaving `{{name}}` uninterpolated while it loads
+  useBreadcrumbs(title, [{
+    name: t('operator_routes.browse.title.manage', { ns: 'common' }),
+    url: baseUrl.replace('/pricing/[id]', '')
+  }, {
+    name: t('operator_routes.manage.title.update', { ns: 'common', name: data?.name ?? '' }),
+    url: baseUrl.replace('/pricing/[id]', `/manage/${ routeId }`)
+  }]);
+
+  const { mutate: Save, isPending: saving } = usePostPricingRule(routeId);
+  const { mutate: Delete } = useDeletePricingRule(routeId);
+  const { mutate: Reorder } = useReorderPricingRules(routeId);
+  const { mutate: Toggle } = useTogglePricing(routeId);
+  const { mutate: SaveCaps, isPending: savingCaps } = usePostPricingCaps(routeId);
+
+  const [ draft, setDraft ] = useState<PriceRuleData>(BLANK);
+  const [ caps, setCaps ] = useState<{ up: number, down: number } | null>(null);
+
+  if (routeId === 0) {
+    return <Navigate to={ url } />;
+  }
+
+  if (isLoading || !data) {
+    return <Box />;
+  }
+
+  const live = caps ?? { up: data.caps.up, down: data.caps.down };
+
+  const onAdd = (): void => {
+    Save(draft, {
+      onSuccess: () => {
+        success(t('operator_routes.pricing.saved', { ns: 'common' }));
+
+        setDraft(BLANK);
+
+        refetch();
+      }
+    });
+  };
+
+  const onMove = (index: number, by: number): void => {
+    const order = data.rules.map(rule => Number(rule.id));
+
+    const target = index + by;
+
+    if (target < 0 || target >= order.length) {
+      return;
+    }
+
+    [order[index], order[target]] = [order[target], order[index]];
+
+    Reorder(order, { onSuccess: () => refetch() });
+  };
+
+  /**
+   * What a rule will actually do, once the operator's own cap has had its say.
+   */
+  const effective = (percent: number): number => (
+    percent >= 0 ? Math.min(percent, live.up) : Math.max(percent, -live.down)
+  );
+
+  const describe = (rule: PriceRuleData): string => {
+    const band = rule.band_to === null
+      ? t('operator_routes.pricing.band.from', { ns: 'common', from: rule.band_from ?? 0 })
+      : t('operator_routes.pricing.band.between', { ns: 'common', from: rule.band_from ?? 0, to: rule.band_to });
+
+    return t(`operator_routes.pricing.signal.${ rule.signal }`, { ns: 'common', band });
+  };
+
+  return (
+    <Meta title={ title }>
+      <BackWithTitle title={ title } to={ baseUrl.replace('/pricing/[id]', `/manage/${ routeId }`) } t={ t } />
+
+      { /* `box` is the app's own card surface; Box from common is the loading
+           skeleton used above, not a container. */ }
+      <Panel className="box">
+          <Note>{ t('operator_routes.pricing.explain', { ns: 'common' }) }</Note>
+
+          <Row>
+            <label>
+              <input
+                type="checkbox"
+                checked={ data.enabled }
+                onChange={ event => Toggle(event.target.checked, { onSuccess: () => refetch() }) }
+              />
+              { ' ' }
+              { t('operator_routes.pricing.enabled', { ns: 'common' }) }
+            </label>
+          </Row>
+
+          { /* The ceiling, above the rules it governs. `platform_*` is the
+               limit an operator cannot raise - stated as the input's max so
+               the form refuses it rather than the server having to. */ }
+          <Row>
+            <span>{ t('operator_routes.pricing.caps.up', { ns: 'common' }) }</span>
+
+            <Field
+              type="number"
+              min={ 0 }
+              max={ data.caps.platform_up }
+              value={ live.up }
+              onChange={ event => setCaps({ ...live, up: Number(event.target.value) }) }
+            />
+
+            <span>{ t('operator_routes.pricing.caps.down', { ns: 'common' }) }</span>
+
+            <Field
+              type="number"
+              min={ 0 }
+              max={ data.caps.platform_down }
+              value={ live.down }
+              onChange={ event => setCaps({ ...live, down: Number(event.target.value) }) }
+            />
+
+            <Small
+              type="button"
+              disabled={ savingCaps || caps === null }
+              onClick={ () => SaveCaps(live, {
+                onSuccess: () => {
+                  success(t('operator_routes.pricing.saved', { ns: 'common' }));
+
+                  setCaps(null);
+
+                  refetch();
+                }
+              }) }
+            >
+              { t('operator_routes.pricing.caps.save', { ns: 'common' }) }
+            </Small>
+          </Row>
+
+          { data.rules.length === 0 ? (
+            <Empty>{ t('operator_routes.pricing.empty', { ns: 'common' }) }</Empty>
+          ) : (
+            <Rules>
+              { data.rules.map((rule, index) => {
+                const applied = effective(rule.percent);
+
+                return (
+                  <Rule key={ rule.id } $disabled={ rule.enabled === false }>
+                    <Text>{ describe(rule) }</Text>
+
+                    <Percent $up={ rule.percent >= 0 }>
+                      { rule.percent > 0 ? '+' : '' }{ rule.percent }%
+                    </Percent>
+
+                    { applied !== rule.percent && (
+                      <Clamped>{ t('operator_routes.pricing.clamped', { ns: 'common', percent: applied }) }</Clamped>
+                    ) }
+
+                    <Actions>
+                      <Small type="button" disabled={ index === 0 } onClick={ () => onMove(index, -1) } aria-label={ t('operator_routes.pricing.up', { ns: 'common' }) }>
+                        <IoArrowUp />
+                      </Small>
+
+                      <Small type="button" disabled={ index === data.rules.length - 1 } onClick={ () => onMove(index, 1) } aria-label={ t('operator_routes.pricing.down', { ns: 'common' }) }>
+                        <IoArrowDown />
+                      </Small>
+
+                      <Small type="button" onClick={ () => Save({ ...rule, enabled: rule.enabled === false }, { onSuccess: () => refetch() }) }>
+                        { rule.enabled === false
+                          ? t('operator_routes.pricing.enable', { ns: 'common' })
+                          : t('operator_routes.pricing.disable', { ns: 'common' }) }
+                      </Small>
+
+                      <Small type="button" onClick={ () => Delete(Number(rule.id), { onSuccess: () => refetch() }) }>
+                        { t('operator_routes.pricing.remove', { ns: 'common' }) }
+                      </Small>
+                    </Actions>
+                  </Rule>
+                );
+              }) }
+            </Rules>
+          ) }
+
+          { /* One row to add a rule, rather than a separate screen: a rule is
+               four small values and an operator writing a set of them should
+               not be navigating between them. */ }
+          <Row>
+            <Choice
+              value={ draft.signal }
+              aria-label={ t('operator_routes.pricing.new.signal', { ns: 'common' }) }
+              onChange={ event => setDraft({ ...draft, signal: event.target.value as PriceRuleData['signal'] }) }
+            >
+              <option value="days">{ t('operator_routes.pricing.new.days', { ns: 'common' }) }</option>
+              <option value="occupancy">{ t('operator_routes.pricing.new.occupancy', { ns: 'common' }) }</option>
+            </Choice>
+
+            <Field
+              type="number"
+              min={ 0 }
+              value={ draft.band_from ?? 0 }
+              aria-label={ t('operator_routes.pricing.new.from', { ns: 'common' }) }
+              onChange={ event => setDraft({ ...draft, band_from: Number(event.target.value) }) }
+            />
+
+            <Field
+              type="number"
+              min={ 0 }
+              value={ draft.band_to ?? '' }
+              placeholder={ t('operator_routes.pricing.new.open', { ns: 'common' }) }
+              aria-label={ t('operator_routes.pricing.new.to', { ns: 'common' }) }
+              onChange={ event => setDraft({ ...draft, band_to: event.target.value === '' ? null : Number(event.target.value) }) }
+            />
+
+            <Field
+              type="number"
+              min={ -data.caps.platform_down }
+              max={ data.caps.platform_up }
+              value={ draft.percent }
+              aria-label={ t('operator_routes.pricing.new.percent', { ns: 'common' }) }
+              onChange={ event => setDraft({ ...draft, percent: Number(event.target.value) }) }
+            />
+
+            <Button
+              type="button"
+              size="medium"
+              noMargin
+              loading={ saving }
+              text={ t('operator_routes.pricing.new.add', { ns: 'common' }) }
+              onClick={ onAdd }
+            />
+          </Row>
+      </Panel>
+    </Meta>
+  );
+};
+
+export default Manage;

package/Pricing/services.ts

@@ -0,0 +1,76 @@
+import { UseMutationResult, UseQueryResult, useMutation, useQuery } from '@tanstack/react-query';
+import { apiClient } from '@autobusal/providers';
+import { PricingData, PriceRuleData } from '../types';
+
+/**
+ * Staged dynamic pricing for one route (roadmap P5).
+ *
+ * Claude - 2026-08-30. One query returns the whole screen's state - the
+ * opt-in, the rules in the order they are evaluated, and the caps they will be
+ * held to - because a percentage means nothing without the cap beside it: a
+ * form that lets an operator type 40 while their own ceiling is 20 has to say
+ * so as they type, not clamp silently at pricing time.
+ */
+export const useGetPricing = (routeId: number): UseQueryResult<PricingData> => (
+  useQuery({
+    queryKey: ['operator-route-pricing', { routeId }],
+    enabled: routeId > 0,
+    queryFn: async () => (
+      await apiClient
+        .get('/api/routes/operator/pricing/get', { params: { route_id: routeId } })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+export const usePostPricingRule = (routeId: number): UseMutationResult<PriceRuleData, Error, PriceRuleData, unknown> => (
+  useMutation({
+    mutationFn: async (data: PriceRuleData) => (
+      await apiClient
+        .post('/api/routes/operator/pricing/save', { ...data, route_id: routeId })
+        .then(response => (
+          response.data
+        ))
+    )
+  })
+);
+
+export const useDeletePricingRule = (routeId: number): UseMutationResult<void, Error, number, unknown> => (
+  useMutation({
+    mutationFn: async (id: number) => (
+      await apiClient.delete('/api/routes/operator/pricing/delete', {
+        data: { route_id: routeId, id }
+      })
+    )
+  })
+);
+
+/**
+ * Reordering is not a display preference here: the FIRST matching rule is the
+ * only one that applies, so moving a row changes what a fare is.
+ */
+export const useReorderPricingRules = (routeId: number): UseMutationResult<void, Error, number[], unknown> => (
+  useMutation({
+    mutationFn: async (order: number[]) => (
+      await apiClient.post('/api/routes/operator/pricing/reorder', { route_id: routeId, order })
+    )
+  })
+);
+
+export const useTogglePricing = (routeId: number): UseMutationResult<void, Error, boolean, unknown> => (
+  useMutation({
+    mutationFn: async (enabled: boolean) => (
+      await apiClient.post('/api/routes/operator/pricing/toggle', { route_id: routeId, enabled })
+    )
+  })
+);
+
+export const usePostPricingCaps = (routeId: number): UseMutationResult<void, Error, { up: number, down: number }, unknown> => (
+  useMutation({
+    mutationFn: async (caps: { up: number, down: number }) => (
+      await apiClient.post('/api/routes/operator/pricing/caps', { route_id: routeId, ...caps })
+    )
+  })
+);

package/Pricing/styles.ts

@@ -0,0 +1,166 @@
+import styled, { css } from 'styled-components';
+
+/**
+ * The staged-dynamic-pricing screen (roadmap P5).
+ *
+ * Claude - 2026-08-30. Laid out as a LIST THAT IS READ TOP TO BOTTOM, because
+ * that is what the rules mean: the first one whose band covers the search is
+ * the only one that applies. A grid of cards would have hidden the one thing
+ * an operator has to understand about their own pricing.
+ */
+export const Panel = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 16px;
+`;
+
+export const Row = styled.div`
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+`;
+
+export const Note = styled.p`
+  margin: 0;
+  max-width: 70ch;
+  font-size: ${ props => props.theme.size.s };
+  color: ${ props => props.theme.font.faded };
+`;
+
+export const Rules = styled.ol`
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  counter-reset: rule;
+`;
+
+/**
+ * A rule, numbered by its position in the evaluation order. The number is not
+ * decoration - it is the answer to "which one of these decided the fare".
+ */
+export const Rule = styled.li<{ $disabled: boolean }>`
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 12px;
+  background: ${ props => props.theme.background.neutral };
+  border-radius: ${ props => props.theme.borderRadius };
+
+  ${ props => props.$disabled && css`
+    opacity: .55;
+  ` }
+
+  &::before {
+    counter-increment: rule;
+    content: counter(rule);
+    flex: 0 0 auto;
+    width: 22px;
+    height: 22px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: ${ props => props.theme.size.xs };
+    font-weight: 700;
+    color: ${ props => props.theme.primary.contrast };
+    background: ${ props => props.theme.primary.normal };
+    border-radius: 50%;
+  }
+`;
+
+export const Text = styled.span`
+  flex: 1 1 260px;
+  font-size: ${ props => props.theme.size.s };
+`;
+
+/**
+ * The effect, coloured by direction - a rise and a cut are the two things an
+ * operator is scanning this list for.
+ */
+export const Percent = styled.strong<{ $up: boolean }>`
+  flex: 0 0 auto;
+  font-size: ${ props => props.theme.size.m };
+  color: ${ props => (props.$up ? props.theme.font.warning : props.theme.font.success) };
+`;
+
+/**
+ * Said out loud beside the percentage when the operator's own cap is lower
+ * than the rule asks for - the fare will move by the cap, and a screen that
+ * did not say so would leave them wondering why.
+ */
+export const Clamped = styled.span`
+  flex: 0 0 auto;
+  font-size: ${ props => props.theme.size.xs };
+  color: ${ props => props.theme.font.error };
+`;
+
+export const Actions = styled.div`
+  display: flex;
+  gap: 6px;
+  margin-left: auto;
+`;
+
+/**
+ * A row control - it has to READ as a control. Without a border these sat on
+ * the panel as plain text, and "Save limits" in particular looked like a
+ * caption rather than the button that commits a change to what an operator may
+ * charge.
+ */
+export const Small = styled.button`
+  padding: 4px 10px;
+  font-size: ${ props => props.theme.size.xs };
+  color: ${ props => props.theme.font.normal };
+  background: ${ props => props.theme.background.box };
+  border: 1px solid ${ props => props.theme.inputs.border };
+  border-radius: ${ props => props.theme.borderRadius };
+  white-space: nowrap;
+
+  &:hover:not(:disabled) {
+    opacity: .8;
+  }
+
+  &:disabled {
+    opacity: .4;
+    cursor: not-allowed;
+  }
+`;
+
+/**
+ * The add-a-rule inputs are NARROW and sit on one line.
+ *
+ * `width` alone loses to the app's global `input { width: 100% }`, which is
+ * what stacked four small numbers into four full-width rows and made a
+ * four-field form look like a questionnaire. flex-basis with no grow, plus an
+ * explicit width, wins it back without touching the global rule.
+ */
+export const Field = styled.input`
+  && {
+    flex: 0 0 auto;
+    width: 92px;
+  }
+`;
+
+export const Choice = styled.select`
+  && {
+    flex: 0 0 auto;
+    width: auto;
+    min-width: 180px;
+    padding: 6px 10px;
+    border-radius: ${ props => props.theme.borderRadius };
+    background: ${ props => props.theme.inputs.background };
+    border: 1px solid ${ props => props.theme.inputs.border };
+    color: ${ props => props.theme.font.normal };
+    font-size: ${ props => props.theme.size.s };
+  }
+`;
+
+export const Empty = styled.p`
+  margin: 0;
+  font-size: ${ props => props.theme.size.s };
+  color: ${ props => props.theme.font.faded };
+`;

package/index.ts

@@ -3,6 +3,7 @@ import Manage from './Manage';
 import AlternatesBrowse from './Alternates/Browse';
 import LocationsManage from './Locations/Manage';
 import PricesManage from './Prices/Manage';
+import PricingManage from './Pricing/Manage';
 import SchedulesManage from './Schedule/Manage';
 import TransitingManage from './Transiting/Manage';
 import UnavailableBrowse from './Unavailable/Browse';
@@ -14,6 +15,7 @@ export {
   AlternatesBrowse,
   LocationsManage,
   PricesManage,
+  PricingManage,
   SchedulesManage,
   TransitingManage,
   UnavailableBrowse,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@autobusal/operator-routes",
-  "version": "1.10.0",
+  "version": "1.10.1",
   "author": "Ferjolt Ozuni",
   "type": "module",
   "main": "index.ts"

package/types.ts

@@ -3,4 +3,43 @@ export interface SeatingOptionsData {
   bus_id?: number
   blocked_seats?: number
   available_seats?: number
-}
+}
+/**
+ * One staged-dynamic-pricing rule on a route (roadmap P5).
+ *
+ * Claude - 2026-08-30. `percent` is SIGNED: positive raises the fare, negative
+ * lowers it and shows the traveller the standard price struck through. The
+ * band is inclusive at both ends and an absent end is open, which is how an
+ * operator says it out loud ("0 to 2 days out", "over 80% full").
+ */
+export interface PriceRuleData {
+  id?: number
+  signal: 'days' | 'occupancy'
+  band_from: number | null
+  band_to: number | null
+  percent: number
+  position?: number
+  enabled?: boolean
+}
+
+export interface PricingData {
+  /** the route these rules price, for the heading and the breadcrumb */
+  name: string
+
+  /** the route's opt-in - rules do nothing until this is on */
+  enabled: boolean
+  rules: PriceRuleData[]
+
+  /**
+   * What the operator has allowed itself, and the platform's own ceiling
+   * above that. A rule beyond the operator's cap is clamped when a fare is
+   * moved rather than refused when it is saved, so lowering a cap binds every
+   * rule already written underneath it.
+   */
+  caps: {
+    up: number
+    down: number
+    platform_up: number
+    platform_down: number
+  }
+}