gtfs-garage-web 0.0.2 → 0.1.0

package/README.md

@@ -9,19 +9,12 @@ be mounted in another application.
 
 ```sh
 npm install gtfs-garage-web
-```
-
-The map is a separate entry point, and MapLibre an **optional** peer. Install
-it only if you want one:
-
-```sh
 npm install maplibre-gl            # only with the map
 ```
 
-Nothing in the main entry mentions MapLibre, so a viewer without a map neither
-downloads it nor needs it installed to build. That is why the map arrives as an
-import rather than a flag: a bundler resolves `import()` specifiers whether or
-not the branch runs, so a flag would still have made MapLibre mandatory.
+ESM only — a bundler or native ES modules, no `<script>` drop-in. MapLibre is an
+**optional** peer behind its own entry point, so a viewer without a map neither
+downloads it nor needs it installed to build.
 
 ## React
 
@@ -35,14 +28,10 @@ import "maplibre-gl/dist/maplibre-gl.css";
 
 export default function Feed() {
   return <GtfsGarage map={mapPart} baseUrl="https://example.org" style={{ height: "80vh" }} />;
-}```
-
-Drop the two `map` imports and the MapLibre stylesheet for a table-only viewer:
-
-```tsx
-<GtfsGarage baseUrl="https://example.org" style={{ height: "80vh" }} />
+}
 ```
 
+Drop the two `map` imports and the MapLibre stylesheet for a table-only viewer.
 `"use client"` is required: the viewer builds DOM and cannot render on a server.
 
 **Give the container a height.** The viewer fills whatever box it is given, and
@@ -62,12 +51,25 @@ const viewer = await mount(document.querySelector("#feed")!, {
 viewer.destroy(); // releases the map, the history subscription and the markup
 ```
 
+## A dataset that is still being prepared
+
+`GtfsGarageDataset` waits for one, and draws the being-prepared, not-prepared
+and failed states itself — so no host writes a progress bar:
+
+```tsx
+import { GtfsGarageDataset } from "gtfs-garage-web/react";
+
+<GtfsGarageDataset dataset={provider} description="mdb-1210" style={{ height: "80vh" }} />
+```
+
 ## Where the data comes from
 
 By default the viewer talks to a GTFS Garage server at `baseUrl`. To drive it
-from your own backend instead, pass a `source` implementing `ViewerSource` —
-`GtfsSource` for the table, plus `geojsonStream` for the map, which draws a
-large feed's shapes as they arrive rather than all at the end.
+from your own backend, either serve the same API — specified in
+[`docs/GtfsGarageAPI.yaml`](https://github.com/MobilityData/gtfs-garage/blob/main/docs/GtfsGarageAPI.yaml)
+— or pass a `source` implementing `ViewerSource`, which is the escape hatch for
+a backend of any other shape, for authentication, or for reading Parquet in the
+browser with no server at all.
 
 ## Styling
 
@@ -81,6 +83,14 @@ page. The design tokens are declared on that class and are the theming API:
 }
 ```
 
+## Documentation
+
+**[Embedding the viewer](https://github.com/MobilityData/gtfs-garage/blob/main/docs/INTEGRATION.md)**
+— every option, the three ways to supply data, what your server has to provide
+(including CORS and authentication, which the API document deliberately leaves
+to you), the dataset-preparation lifecycle, and a worked adapter for driving the
+viewer from an API of your own.
+
 ## Licence
 
 Apache-2.0

package/dist/dataset.js

@@ -1,4 +1,4 @@
-import { m as h, p as L } from "./mount-CHJb5mxA.js";
+import { m as h, p as L } from "./mount-EvMk5jp_.js";
 function P(e, s) {
   const { description: a, canPrepare: n, asked: c, phrase: f } = s;
   switch (e.state) {

package/dist/{mount-CHJb5mxA.js → mount-EvMk5jp_.js}

@@ -295,7 +295,7 @@ function ie(n) {
     e.push([se[n.kind], `${p(n.acquire_ms)}${t}`]);
   }
   if (n.extract_ms != null && e.push(["Unzip", `${p(n.extract_ms)} · ${f(n.total_bytes)} archive`]), n.register_ms != null && e.push(["Read headers", p(n.register_ms)]), n.convert_ms != null) {
-    const t = n.stored_bytes === null ? "" : ` · ${f(n.stored_bytes)} stored`;
+    const t = n.stored_bytes == null ? "" : ` · ${f(n.stored_bytes)} stored`;
     e.push(["Convert to Parquet", `${p(n.convert_ms)}${t}`]);
   }
   return n.count_ms != null && e.push(["Count rows", p(n.count_ms)]), e;
@@ -306,19 +306,19 @@ function le(n) {
     name: t.name,
     bytes: f(t.bytes),
     share: e === 0 ? 0 : Math.round(t.bytes / e * 100),
-    compressed: t.compressed_bytes === null ? "—" : f(t.compressed_bytes),
-    stored: t.parquet_bytes === null ? "—" : f(t.parquet_bytes),
+    compressed: t.compressed_bytes == null ? "—" : f(t.compressed_bytes),
+    stored: t.parquet_bytes == null ? "—" : f(t.parquet_bytes),
     costMs: re(n, t),
-    rows: t.row_count === null ? "—" : t.row_count.toLocaleString(),
+    rows: t.row_count == null ? "—" : t.row_count.toLocaleString(),
     columns: t.columns
   }));
 }
 function O(n) {
-  return n.convert_ms !== null;
+  return n.convert_ms != null;
 }
 function re(n, e) {
   const t = O(n) ? e.convert_ms : e.count_ms;
-  return t === null ? "—" : p(t);
+  return t == null ? "—" : p(t);
 }
 function de(n) {
   const e = n.phases ? null : O(n) ? {

package/dist/mount.d.ts

@@ -14,6 +14,16 @@ import { type AppState } from "./state";
 import { type HistoryPort } from "./ui/history";
 export type { ViewerParts } from "./markup";
 export type { GtfsSource, ViewerSource } from "./sources/types";
+/**
+ * The payload types, re-exported so a host implementing `ViewerSource` can name
+ * what its methods return. They are generated from `docs/GtfsGarageAPI.yaml`,
+ * so an implementation written against them is checked against the contract at
+ * compile time - which is the whole point of generating them, and is worth
+ * nothing if they stop at the package boundary.
+ */
+export type { AppConfig, ColumnInfo, ConditionOutcome, DatasetManifest, FeatureCollection, FileCondition, FileMetrics, Filter, FilterOperator, GeoFeature, GeoJsonKind, ImpliedValue, LoadMetrics, LoadProgress, MissingFile, PageResponse, RelatedLink, Row, TableInfo, TablesResponse, ValueCount, } from "./sources/types";
+/** `geojsonStream` hands these to its callback, so an implementer names them too. */
+export type { NdjsonMessage } from "./sources/ndjson";
 export { RestSource } from "./sources/rest";
 export { browserHistory, memoryHistory, type HistoryPort } from "./ui/history";
 export interface ViewerOptions {

package/dist/mount.js

@@ -1,4 +1,4 @@
-import { R as s, b as a, a as e, m } from "./mount-CHJb5mxA.js";
+import { R as s, b as a, a as e, m } from "./mount-EvMk5jp_.js";
 export {
   s as RestSource,
   a as browserHistory,

package/dist/react.js

@@ -1,7 +1,7 @@
 import { jsx as f } from "react/jsx-runtime";
 import { useRef as c, useEffect as i } from "react";
 import { mountDataset as m } from "./dataset.js";
-import { m as d } from "./mount-CHJb5mxA.js";
+import { m as d } from "./mount-EvMk5jp_.js";
 function p({ className: l, style: u, ...e }) {
   const o = c(null), n = c(e);
   return n.current = e, i(() => {

package/dist/schema.d.ts

@@ -10,9 +10,9 @@ import type { ColumnInfo, MissingFile } from "./sources/types";
 interface Field {
     type?: string;
     values?: Record<string, string>;
-    required?: string;
+    required?: ColumnInfo["required"];
     condition?: string;
-    conditionScope?: string;
+    conditionScope?: ColumnInfo["condition_scope"];
     primaryKey?: boolean;
     references?: {
         table: string;