Skip to content

CLAUDE.md

Latest commit

 

History

History
47 lines (33 loc) · 3.25 KB

CLAUDE.md

File metadata and controls

47 lines (33 loc) · 3.25 KB
Raw

CLAUDE.md — react-gtfs-selector

Project overview

React component library for selecting GTFS transit data sources. Provides a tabbed UI with drag-and-drop file import and online feed search. Published as an npm module.

Architecture

  • src/types.ts — Core types: GtfsSelectionResult, GtfsSearchResult, GtfsSource, GtfsTab, GtfsTabComponentProps
  • src/tabs.tsx — Built-in tab exports (fileTab, urlTab) and createSourceTab helper
  • src/sources/ — Source plugins implementing GtfsSource, exported as GtfsTab via createSourceTab
    • transport-data-gouv-fr.ts — French open transit data (fully implemented)
    • mobility-data-csv.ts — Mobility Database CSV source (no token needed)
    • mobility-data.ts — Mobility Database API source (server-side search, requires API token)
  • src/components/ — React components
    • GtfsSelector.tsx — Main component with tabbed layout, renders tabs from tabs prop
    • DropZone.tsx — File drag-and-drop area
    • SourceSearch.tsx — Search UI for any GtfsSource
  • src/style.css — Default styles (opt-out via styled={false})
  • src/index.ts — Library entry point

Commands

  • npm test — Run all tests (Vitest + React Testing Library + jsdom)
  • npm run build — Type-check and build ESM + CJS output to dist/
  • npm run lint — TypeScript type-checking only

Key design decisions

  • Composable tabs: The tabs prop (required) accepts an array of GtfsTab objects that controls which tabs appear and in what order. Built-in tabs (fileTab, urlTab) and source tabs (mobilityDataCsv, transportDataGouvFr) are all uniform GtfsTab objects with id, label, and component. Custom sources implement GtfsSource and are wrapped via createSourceTab().
  • Sync vs async search: Sources can use the default fetchDatasets() + search() pattern (fetch all upfront, filter locally) or provide an optional asyncSearch(query) method for server-side search with debouncing. The SourceSearch component handles both automatically.
  • Single callback: onSelect receives a discriminated union (type: 'file' | 'url') so consumers handle both cases in one place.
  • CSS opt-out: Default styles ship with the component via react-gtfs-selector/style.css. All classes prefixed rgs-. Pass styled={false} to disable class names entirely.
  • transport.data.gouv.fr caching: Datasets cached in localStorage for 24h to avoid repeated API calls.
  • Mobility Database: Default source uses mobilityDataCsv (CSV from files.mobilitydatabase.org, no token needed, cached in localStorage for 24h). The API-based createMobilityDataSource({ apiToken }) factory is still available for server-side search but requires a Bearer token.

Testing

Tests are in *.test.tsx / *.test.ts files colocated with source. Uses Vitest with jsdom environment. The test setup polyfills scrollIntoView for jsdom compatibility.

Changelog

Every user-facing change (feature, fix, breaking change) must be documented in CHANGELOG.md under the [Unreleased] section, following the Keep a Changelog format.

Release process

npm publication is triggered automatically when a GitHub release is created. Do not publish manually.