compact comments

Author: arielvino

src/pages/components/map-related/MapLayers/MapIndexLayer.stories.tsx

@@ -10,11 +10,9 @@ const meta = {
   title: 'Map/Layers/MapIndexLayer',
   component: MapIndexLayer,
   parameters: { layout: 'centered' },
-  // Every legend rule in map.scss is nested under `.map-info` — the wrapper MapShell puts round
-  // a map page — and the box chrome comes from the `.map-legend` slot inside it. Mounted bare,
-  // the legend gets none of it: the grid never applies and the glyphs render at their intrinsic
-  // size rather than 20px. So the decorator reproduces MapShell's two levels, and the wrapper is
-  // given a map-sized box because `.map-legend` is absolutely positioned within it.
+  // Every legend rule in map.scss is nested under `.map-info` and its `.map-legend` slot, so
+  // mounted bare the legend gets no grid and glyphs at their intrinsic size. Reproduce MapShell's
+  // two levels; the wrapper needs a size because `.map-legend` is absolutely positioned in it.
   decorators: [
     (Story) => (
       <div className="map-info" style={{ width: 340, height: 210 }}>

src/pages/components/map-related/MapSpeedIndex.tsx

@@ -9,12 +9,7 @@ import {
 
 /**
  * Key to the ping markers' speed ramp: the compass badge for a bus reported standing, then an
- * arrow per band, growing as it goes faster.
- *
- * Size carries the ramp rung by rung, but it can only run one way — the pings a rider cares
- * about, the slow ones, come out the smallest marks on the map. So colour splits the ramp in
- * half against the grain: red on the slow bands and on the standing badge's rim, the app's
- * colour for a bad result, leaving the fast half in plain ink to recede.
+ * arrow per band, growing as it goes faster and red across the slow half.
  */
 export function MapSpeedIndex() {
   const { t } = useTranslation()

src/pages/components/map-related/map-types.ts

@@ -1,8 +1,8 @@
 import type { SiriVehicleLocationWithRelatedPydanticModel } from '@hasadna/open-bus-api-client'
 import { BusStop } from 'src/model/busStop'
 
-/** One per concurrent ride on the map, cycled. Deliberately no red: red is the ping speed ramp's
- * (`.ping-arrow--slow`), and red arrows over a red line read as neither. */
+/** One per concurrent ride on the map, cycled. Deliberately no red — that belongs to the ping
+ * speed ramp (`.ping-arrow--slow`), and red arrows over a red line read as neither. */
 export const ROUTE_COLORS = ['#f97316', '#3b82f6', '#22c55e', '#a855f7', '#0891b2']
 
 export interface Point {

src/pages/components/map-related/mapMarkers.test.ts

@@ -35,7 +35,6 @@ describe('vehicleBearingMarker', () => {
 
     expect(scale(5)).toBeLessThan(scale(25))
     expect(scale(25)).toBeLessThan(scale(FAST))
-    // colour says it a second way, and the only way that does not shrink with the arrow
     expect(html(0, 5)).toContain('ping-arrow--slow')
     expect(html(0, FAST)).not.toContain('ping-arrow--slow')
   })

src/pages/components/map-related/mapMarkers.ts

@@ -1,11 +1,9 @@
 /**
  * Every Leaflet icon and line colour the map draws with, and nothing that renders.
  *
- * They live here rather than in `MapContent` because the layers `MapContent` renders need them
- * too: with the definitions in `MapContent`, `MapContent → MapLayers/* → MapContent` was an
- * import cycle (two of them, which `madge --circular` fails CI on). A module of leaf values that
- * imports no component breaks it — the layers and `MapContent` both depend on this, and it
- * depends on neither.
+ * Apart from `MapContent` because the layers it renders need these too, which made
+ * `MapContent → MapLayers/* → MapContent` an import cycle — `madge --circular` fails CI on it.
+ * Keep this module free of component imports.
  */
 import { DivIcon, Icon, IconOptions } from 'leaflet'
 import {

src/pages/components/map-related/vehicleBearingGlyph.test.ts

@@ -76,8 +76,6 @@ describe('arrowSvgMarkup', () => {
     expect(arrowSvgMarkup(0, TOP)).not.toContain('ping-arrow--slow')
   })
 
-  // The regression this ramp's floor exists to prevent: the slowest band is both the smallest
-  // arrow and the one worth finding, and below ~0.6 it is a speck between its neighbours.
   it('keeps the slowest arrow big enough to find, not merely big enough to draw', () => {
     const scale = Number(/scale\(([\d.]+)\)/.exec(arrowSvgMarkup(0, 0))![1])
 
@@ -96,7 +94,6 @@ describe('standingSvgMarkup', () => {
     expect(standingSvgMarkup(undefined)).toContain('ping-badge')
   })
 
-  // A parked bus is a speed reading and joins the red family; the end of a ride is not.
   it('rims the parked bus in the slow ramp colour, which the ride-end badge must not take', () => {
     expect(standingSvgMarkup(0)).toContain('ping-badge--standing')
     expect(rideEndSvgMarkup()).not.toContain('ping-badge--standing')

src/pages/components/map-related/vehicleBearingGlyph.tsx

@@ -5,9 +5,8 @@
  *
  * The two badges take the ride-start marker's shape (`.bus-icon-circle`: a white disc in a
  * coloured rim, the same in both themes), so the things that bookend or interrupt a ride read as
- * one family and the arrows stay the only bare shapes on the map. Only the rim colour separates
- * them: the ride-end badge keeps the primary rim, while the standing badge takes the slow arrows'
- * red, because a parked bus is a speed reading and the end of a ride is not.
+ * one family. Only the rim colour separates them — the standing badge takes the slow arrows' red,
+ * the ride-end badge keeps the primary rim.
  *
  * They live apart from `MapContent` so the legend can render them without pulling Leaflet in,
  * and so both renderings — Leaflet's HTML string and the legend's element — come off one set of
@@ -61,23 +60,17 @@ export const STANDING_LABEL = '0'
 /** How the arrow grows across the bands, as a factor of the glyph: evenly spaced, so adding a
  * band re-spaces the ramp instead of squeezing it in at one end. The top of the range keeps the
  * fastest arrow inside the viewBox's inscribed circle, so no bearing clips a corner off it. The
- * bottom is a legibility floor rather than a ramp choice: the ramp would happily start lower,
- * but at 0.46 the slowest arrow came out ~8px across and was lost among the pings either side. */
+ * bottom is a legibility floor, not a ramp choice: at 0.46 the slowest arrow was ~8px across and
+ * lost among the pings either side of it. */
 const BAND_SCALE_MIN = 0.62
 const BAND_SCALE_MAX = 0.96
 const bandScale = (band: number) =>
   BAND_SCALE_MIN + ((BAND_SCALE_MAX - BAND_SCALE_MIN) * band) / (SPEED_BANDS.length - 1)
 
 /**
  * Size alone can't carry six bands at ~14px, so colour splits the ramp in two and the size then
- * places an arrow within its half. The slow half is red — what a bad result is painted
- * everywhere else in the app — and the fast half stays the map's default ink.
- *
- * Colour rather than fill, because size runs against the point of the map here: a bus stuck in
- * traffic is the ping worth finding and also the one drawn smallest, and stacking it on top
- * ({@link bearingZIndex}) only stops it being covered, it does not make it easier to spot.
- * Colour is the one channel that doesn't shrink with the arrow.
- *
+ * places an arrow within its half. Colour rather than fill because it is the one channel that
+ * doesn't shrink with the arrow, and the slow half — the pings worth finding — is the small end.
  * The colours live in `map.scss`; the markup carries geometry alone.
  */
 const bandClass = (band: number) =>
@@ -123,10 +116,8 @@ export const arrowSvgMarkup = (deg: number, band: number) =>
   `<path class="${bandClass(band)}" d="${ARROW_PATH}" transform="${bandTransform(deg, band)}"/>` +
   `</svg>`
 
-/** The standing badge's rim wears the slow ramp's red, so a parked bus reads as part of the same
- * family as the crawling arrows. The ride-end badge keeps the plain rim — it bookends the ride
- * rather than reporting a speed — which is why this is a modifier and not a change to
- * `.ping-badge`. Named here so the legend's element and Leaflet's markup can't drift apart. */
+/** A modifier rather than a change to `.ping-badge`, which the ride-end badge shares. Named so
+ * the legend's element and Leaflet's markup can't drift apart. */
 const STANDING_DISC_CLASS = 'ping-badge ping-badge--standing'
 
 const discMarkup = (

src/resources/map.scss

@@ -3,9 +3,8 @@
 // theme from a stylesheet, so it comes from here.
 $primary: #1976d2;
 
-// The speed ramp's red, worn by the slow arrows and by the standing badge's rim. Red is what the
-// app paints a bad result everywhere else ($terrible-result, the far end of GpsCoverageStrip's
-// gap ramp), and ROUTE_COLORS deliberately holds none, so it can't be read as a ride's own line.
+// The speed ramp's red, worn by the slow arrows and the standing badge's rim. ROUTE_COLORS
+// deliberately holds no red, so it can't be read as a ride's own line colour.
 $slow-ping: #c1121f;
 
 // Shared translucency for map overlay controls so they read consistently across
@@ -334,8 +333,7 @@ pre {
   stroke: $primary;
   stroke-width: 1.8;
 
-  // A parked bus is the slowest reading on the ramp, so its rim joins the slow arrows' red. The
-  // ride-end badge keeps the primary rim: it bookends the ride rather than reporting a speed.
+  // Only the standing badge: the ride-end badge shares `.ping-badge` and keeps the primary rim.
   &--standing {
     stroke: $slow-ping;
   }
@@ -359,8 +357,6 @@ pre {
   // arrows exactly where they are already hardest to see.
   vector-effect: non-scaling-stroke;
 
-  // Every arrow is solid; only the fill colour changes across the ramp, so the slow half is the
-  // one that catches the eye and the fast half recedes into the same ink as the map's own labels.
   &--slow {
     fill: $slow-ping;
   }