SARtale Guide

Web app

A static single-page site in TypeScript, built with Vite. It reads data/lakes.json at start-up and draws everything from it; nothing is computed on a server.

Commands#

CommandWhat it does
npm --prefix app run devDev server on http://localhost:5173
npm --prefix app test -- --runVitest, once. Drop --run to watch
npm --prefix app run buildtsc --noEmit, then a production build in app/dist/
npm --prefix app run previewServes app/dist/ locally to check a build

How it is put together#

main.ts loads lakes.json, then mountApp in app.ts builds the shell (header, the four views, footer) and wires the views to each other. Each view is a plain function that takes a root element and returns a small handle, so tests can mount it in jsdom without a browser.

FileJob
app.ts, navLink.tsShell, header links and routing; header links are real links, so a modified click opens a new tab
storyPage.ts, storyPage.cssThe story page (the front page): the opening, the seven numbered sections, the Alert banner and the "Add a lake" section
lakeStory.tsThe guided story, beat by beat (#story)
overview/Lake Watch: overviewView.ts (desktop table and count tiles), overviewPhone.ts (phone cards, chips and the List / Map bar), model.ts (filters, sort and the #lakes?… query), statusKey.ts (What the statuses mean), mapDrawer.ts and drawerPanel.ts (the map and its panel), mappedLakes.ts (reads mapped_lakes.json) and marks.ts (marker shapes)
lakePage/A lake's page: lakePage.ts (header, message, What to do and the blocks), gauge.ts (change against baseline), extent.ts (against the largest mapped outline), history.ts (status-track chart and readings) and sources.ts (sources and limits). compare.ts is a placeholder for comparing two passes, not yet available
lakeWatchView.tsShared lake helpers: the status track, chart data, the message box and the factory types for the chart and map
lakeLocator.tsThe MapLibre style, MODIS picture bounds and status slugs the map uses; MapLibre is loaded on first use
chart.tsThe uPlot area chart
lakeBrief.tsThe printable one-page brief
evidenceView.tsHow we know
lakeRequests.tsThe "Add a lake" form (its button is Request a lake): checks the input, then opens the GitHub issue form; also reads requests.json
lakes.tsTypes for lakes.json, loading, sorting and status sentences
statusDisplay.ts, statusMarkers.tsThe status families shown on the site (for example, both frozen statuses as Frozen) and their markers
contacts.ts, links.ts, provinces.tsThe provincial authority for each lake, the Sentinel-2 imagery link, and province names
plainLimits.tsRewrites the pipeline's technical limit wording in plain words
content.ts, content/*.jsonAll page text, and the banned-wording list
vtt.ts, vite.config.tsThe videos: the build copies media/*.mp4 and the posters into dist/media/ and writes each .srt as WebVTT captions; the dev server serves the same files

Routing#

The view lives in the URL hash, so every view can be linked and Back works.

HashOpens
none, or #startThe story page
#lakesLake Watch, the table of every watched lake
#lakes?<filters>Lake Watch with its state: show (a tile filter), district, q (search), sort, map=1 and sel, for example #lakes?show=attention&map=1
#lakes/<id>That lake's page, for example #lakes/attabad
#storyThe guided story
#evidenceHow we know

Any other hash, such as the skip link's #main, is treated as an in-page anchor and leaves the view alone.

Text and wording#

Page text is in app/src/content/, not in the code. Numbers in it are tokens such as {lakes} or {minLooks}, filled from lakes.json at run time, so the text cannot drift from the data. Write a number into the copy only when it is not in the data, and then cite it.

SARtale is screening, not warning, so content.ts keeps a list of phrases the app must never use, among them "early warning", "flood detected", "predict", "safe" and "risk score". A test fails if any page text uses one. If you need a new phrase, check it against that list and against the method's limits.

Testing#

Tests sit next to the code as *.test.ts and run in jsdom. MapLibre and uPlot are replaced by small fakes through the factory options (createLocator, createChart), so tests check what the app shows, not how the libraries draw. publicData.test.ts checks that every picture lakes.json names is in app/public/data/.

Configuration#

The app has no build-time settings and no server to reach. The "Add a lake" form opens the repository's issue form on GitHub, and the app reads data/lakes.json, data/requests.json and, when the map opens, data/mapped_lakes.json as static files. See Lake requests.