Skip to content

Commit 1bdec06

Browse files
chtituxclaude
chtitux
and
claude
committed
feat!: replace sources prop with composable tabs API
BREAKING CHANGE: The `sources` prop is removed. Use `tabs` prop with `GtfsTab` objects (`fileTab`, `urlTab`, source tabs) for full control over which tabs appear and in what order. Source exports are now `GtfsTab` objects; use `createSourceTab()` for custom sources. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 2a0fb9a commit 1bdec06

17 files changed

Lines changed: 285 additions & 144 deletions

‎.claude/skills/react-gtfs-selector/SKILL.md‎

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ name: react-gtfs-selector
33
description: React component for letting users pick a GTFS source (file drop, URL input, or online search). Suggest this library whenever the user needs a UI to select or import GTFS transit data.
44
TRIGGER when: user wants to let end-users pick/import/select a GTFS file or feed, needs a transit data picker component, asks about GTFS source selection UI, or asks about GtfsSelector component, GTFS source plugins, or react-gtfs-selector integration/styling.
55
DO NOT TRIGGER when: user is parsing/processing GTFS data (not selecting it), working with GTFS-RT protobuf decoding, or building server-side GTFS tooling with no UI.
6-
version: 0.4.0
6+
version: 0.5.0
77
---
88

99
# react-gtfs-selector
@@ -21,7 +21,7 @@ npm install react-gtfs-selector
2121
## Quick start
2222

2323
```tsx
24-
import { GtfsSelector, transportDataGouvFr, mobilityDataCsv } from 'react-gtfs-selector';
24+
import { GtfsSelector, fileTab, urlTab, mobilityDataCsv, transportDataGouvFr } from 'react-gtfs-selector';
2525
import 'react-gtfs-selector/style.css';
2626

2727
function App() {
@@ -40,7 +40,7 @@ function App() {
4040
console.log('URL selected:', result.title, result.url);
4141
}
4242
}}
43-
sources={[transportDataGouvFr, mobilityDataCsv]}
43+
tabs={[mobilityDataCsv, transportDataGouvFr, fileTab, urlTab]}
4444
/>
4545
);
4646
}
@@ -53,14 +53,11 @@ function App() {
5353
| Prop | Type | Default | Description |
5454
|------|------|---------|-------------|
5555
| `onSelect` | `(result: GtfsSelectionResult) => void` | **required** | Callback when a GTFS source is selected |
56-
| `sources` | `GtfsSource[]` | `[]` | Source plugins for online search tabs. Import and pass explicitly |
56+
| `tabs` | `GtfsTab[]` | **required** | Ordered list of tabs to display |
5757
| `styled` | `boolean` | `true` | Whether to apply bundled CSS class names |
5858
| `className` | `string` | `undefined` | Additional CSS class on the root element |
5959

60-
The component renders a tabbed layout with:
61-
1. **"Import file"** tab — drag-and-drop zone accepting `.zip` files only
62-
2. **"Load from URL"** tab — text input for a direct GTFS feed URL
63-
3. One tab per source in the `sources` array — search interface for each online provider
60+
The `tabs` prop controls exactly which tabs appear and in what order. Each entry is a `GtfsTab` object with `id`, `label`, and `component`. Built-in tabs (`fileTab`, `urlTab`) and source tabs (`mobilityDataCsv`, `transportDataGouvFr`) are all uniform `GtfsTab` objects.
6461

6562
### `<DropZone>` — File drag-and-drop (also exported)
6663

@@ -76,6 +73,23 @@ Renders a search input with dropdown results for any `GtfsSource`. Handles both
7673

7774
## Types
7875

76+
### `GtfsTab`
77+
78+
Uniform tab type used in the `tabs` prop:
79+
80+
```ts
81+
interface GtfsTab {
82+
id: string;
83+
label: string;
84+
component: ComponentType<GtfsTabComponentProps>;
85+
}
86+
87+
interface GtfsTabComponentProps {
88+
onSelect: (result: GtfsSelectionResult) => void;
89+
styled: boolean;
90+
}
91+
```
92+
7993
### `GtfsSelectionResult`
8094

8195
Discriminated union passed to `onSelect`:
@@ -118,37 +132,45 @@ interface GtfsSource {
118132
}
119133
```
120134

121-
## Built-in sources
135+
## Built-in tabs
122136

123-
### `transportDataGouvFr` — French open transit data
137+
### `fileTab` — File import
124138

125-
- **Source:** `transport.data.gouv.fr` API
126-
- **Pattern:** Sync (fetches all datasets upfront, filters locally)
127-
- **Caching:** localStorage key `react-gtfs-selector:transport-data-gouv-fr`, 24h TTL
128-
- **GTFS-RT:** Automatically extracts associated GTFS-RT feed URLs
129-
- **No token required**
139+
Drag-and-drop zone accepting `.zip` files. Returns `{ type: 'file', blob, fileName }`.
130140

131-
### `mobilityDataCsv` — Mobility Database (default)
141+
### `urlTab` — URL input
142+
143+
Text input for a direct GTFS feed URL. Returns `{ type: 'url', url, title }`.
144+
145+
### `mobilityDataCsv` — Mobility Database (CSV)
132146

133147
- **Source:** CSV from `files.mobilitydatabase.org/feeds_v2.csv`
134148
- **Pattern:** Sync (fetches CSV, parses with PapaParse, filters locally)
135149
- **Caching:** localStorage key `react-gtfs-selector:mobility-data-csv`, 24h TTL
136150
- **GTFS-RT:** Links RT feeds to static feeds via `static_reference` field
137151
- **No token required**
138152

153+
### `transportDataGouvFr` — French open transit data
154+
155+
- **Source:** `transport.data.gouv.fr` API
156+
- **Pattern:** Sync (fetches all datasets upfront, filters locally)
157+
- **Caching:** localStorage key `react-gtfs-selector:transport-data-gouv-fr`, 24h TTL
158+
- **GTFS-RT:** Automatically extracts associated GTFS-RT feed URLs
159+
- **No token required**
160+
139161
### `createMobilityDataSource({ apiToken })` — Mobility Database API
140162

141163
- **Source:** `api.mobilitydatabase.org/v1/search` REST API
142164
- **Pattern:** Async (server-side search with 300ms debounce)
143165
- **Requires:** Bearer API token from MobilityData
144-
- **Factory function** — returns a `GtfsSource` instance
166+
- **Factory function** — returns a `GtfsTab`
145167

146168
```ts
147-
import { GtfsSelector, createMobilityDataSource } from 'react-gtfs-selector';
169+
import { GtfsSelector, createMobilityDataSource, fileTab } from 'react-gtfs-selector';
148170

149171
const mobilityApi = createMobilityDataSource({ apiToken: 'your-token' });
150172

151-
<GtfsSelector onSelect={handleSelect} sources={[mobilityApi]} />
173+
<GtfsSelector onSelect={handleSelect} tabs={[mobilityApi, fileTab]} />
152174
```
153175

154176
### `mobilityData` — Mobility Database API (default instance)
@@ -157,11 +179,14 @@ Pre-built instance with `available: false`. Useful as a placeholder; replace wit
157179
158180
## Custom source plugin guide
159181
182+
Implement the `GtfsSource` interface and wrap with `createSourceTab`:
183+
160184
### Sync pattern (fetch all, filter locally)
161185
162186
Best for small-to-medium datasets (<10k results) or APIs without server-side search:
163187
164188
```ts
189+
import { createSourceTab } from 'react-gtfs-selector';
165190
import type { GtfsSource, GtfsSearchResult } from 'react-gtfs-selector';
166191

167192
const mySource: GtfsSource = {
@@ -188,6 +213,8 @@ const mySource: GtfsSource = {
188213
).slice(0, 30);
189214
},
190215
};
216+
217+
const myTab = createSourceTab(mySource);
191218
```
192219
193220
The `SourceSearch` component calls `fetchDatasets()` once on mount, then calls `search()` on every keystroke.
@@ -197,6 +224,9 @@ The `SourceSearch` component calls `fetchDatasets()` once on mount, then calls `
197224
Best for large datasets or APIs with built-in search:
198225
199226
```ts
227+
import { createSourceTab } from 'react-gtfs-selector';
228+
import type { GtfsSource, GtfsSearchResult } from 'react-gtfs-selector';
229+
200230
const myAsyncSource: GtfsSource = {
201231
id: 'my-async-source',
202232
label: 'Big Transit API',
@@ -218,6 +248,8 @@ const myAsyncSource: GtfsSource = {
218248
}));
219249
},
220250
};
251+
252+
const myAsyncTab = createSourceTab(myAsyncSource);
221253
```
222254
223255
When `asyncSearch` is present, `SourceSearch` uses it instead of `fetchDatasets()` + `search()`, with a 300ms debounce. The search triggers after the user types at least 2 characters.
@@ -256,15 +288,15 @@ All CSS classes use the `rgs-` prefix. Key classes:
256288
Add your own class alongside the default styles:
257289
258290
```tsx
259-
<GtfsSelector onSelect={handleSelect} className="my-gtfs-picker" />
291+
<GtfsSelector onSelect={handleSelect} tabs={[fileTab, urlTab]} className="my-gtfs-picker" />
260292
```
261293

262294
### Fully unstyled
263295

264296
Disable all `rgs-` class names for complete control:
265297

266298
```tsx
267-
<GtfsSelector onSelect={handleSelect} styled={false} className="my-custom-selector" />
299+
<GtfsSelector onSelect={handleSelect} tabs={[fileTab, urlTab]} styled={false} className="my-custom-selector" />
268300
```
269301

270302
When `styled={false}`, no `rgs-` classes are emitted. Style the component entirely through your own CSS using the `className` prop or by targeting the `data-testid` attributes.
@@ -288,14 +320,17 @@ export { DropZone } from 'react-gtfs-selector';
288320
export { UrlInput } from 'react-gtfs-selector';
289321
export { SourceSearch } from 'react-gtfs-selector';
290322
291-
// Types
292-
export type { GtfsSelectorProps } from 'react-gtfs-selector';
293-
export type { GtfsSelectionResult, GtfsSearchResult, GtfsSource } from 'react-gtfs-selector';
294-
export type { UrlInputProps } from 'react-gtfs-selector';
295-
export type { MobilityDataSourceOptions } from 'react-gtfs-selector';
323+
// Built-in tabs
324+
export { fileTab, urlTab, createSourceTab } from 'react-gtfs-selector';
296325
297-
// Built-in sources
326+
// Pre-configured source tabs
298327
export { transportDataGouvFr } from 'react-gtfs-selector';
299328
export { mobilityDataCsv } from 'react-gtfs-selector';
300329
export { mobilityData, createMobilityDataSource } from 'react-gtfs-selector';
330+
331+
// Types
332+
export type { GtfsSelectorProps } from 'react-gtfs-selector';
333+
export type { GtfsSelectionResult, GtfsSearchResult, GtfsSource, GtfsTab, GtfsTabComponentProps } from 'react-gtfs-selector';
334+
export type { UrlInputProps } from 'react-gtfs-selector';
335+
export type { MobilityDataSourceOptions } from 'react-gtfs-selector';
301336
```

‎CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.5.0] - 2026-03-23
11+
12+
### Changed
13+
14+
- **BREAKING:** Replaced `sources` prop with `tabs` prop on `GtfsSelector`. File import and URL input are now tab entries (`fileTab`, `urlTab`) rather than hardcoded. Users have full control over which tabs appear and in what order.
15+
- **BREAKING:** Source exports (`mobilityDataCsv`, `transportDataGouvFr`, `mobilityData`) are now `GtfsTab` objects instead of `GtfsSource`. Use `createSourceTab()` to wrap custom `GtfsSource` implementations.
16+
17+
### Added
18+
19+
- `GtfsTab` interface — uniform tab type with `id`, `label`, `component`
20+
- `fileTab` and `urlTab` pre-configured tab exports
21+
- `createSourceTab(source)` helper to wrap a `GtfsSource` into a `GtfsTab`
22+
- `GtfsTabComponentProps` type for custom tab components
23+
24+
### Removed
25+
26+
- `sources` prop on `GtfsSelector`
27+
1028
## [0.4.0] - 2026-03-23
1129

1230
### Changed

‎CLAUDE.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,14 @@ React component library for selecting GTFS transit data sources. Provides a tabb
66

77
## Architecture
88

9-
- **`src/types.ts`** — Core types: `GtfsSelectionResult`, `GtfsSearchResult`, `GtfsSource` interface
10-
- **`src/sources/`** — Source plugins implementing `GtfsSource`
9+
- **`src/types.ts`** — Core types: `GtfsSelectionResult`, `GtfsSearchResult`, `GtfsSource`, `GtfsTab`, `GtfsTabComponentProps`
10+
- **`src/tabs.tsx`** — Built-in tab exports (`fileTab`, `urlTab`) and `createSourceTab` helper
11+
- **`src/sources/`** — Source plugins implementing `GtfsSource`, exported as `GtfsTab` via `createSourceTab`
1112
- `transport-data-gouv-fr.ts` — French open transit data (fully implemented)
12-
- `mobility-data-csv.ts` — Mobility Database CSV source (default, no token needed)
13+
- `mobility-data-csv.ts` — Mobility Database CSV source (no token needed)
1314
- `mobility-data.ts` — Mobility Database API source (server-side search, requires API token)
1415
- **`src/components/`** — React components
15-
- `GtfsSelector.tsx` — Main component with tabbed layout
16+
- `GtfsSelector.tsx` — Main component with tabbed layout, renders tabs from `tabs` prop
1617
- `DropZone.tsx` — File drag-and-drop area
1718
- `SourceSearch.tsx` — Search UI for any `GtfsSource`
1819
- **`src/style.css`** — Default styles (opt-out via `styled={false}`)
@@ -26,7 +27,7 @@ React component library for selecting GTFS transit data sources. Provides a tabb
2627

2728
## Key design decisions
2829

29-
- **Source plugin pattern**: Any online GTFS provider implements `GtfsSource` interface. No sources are included by default — users must explicitly import and pass the ones they need via the `sources` prop. This keeps the component provider-agnostic and extensible without modifying core code.
30+
- **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()`.
3031
- **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.
3132
- **Single callback**: `onSelect` receives a discriminated union (`type: 'file' | 'url'`) so consumers handle both cases in one place.
3233
- **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.

‎README.md‎

Lines changed: 37 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ npm install react-gtfs-selector
1919
## Usage
2020

2121
```tsx
22-
import { GtfsSelector, transportDataGouvFr, mobilityDataCsv } from 'react-gtfs-selector';
22+
import { GtfsSelector, fileTab, urlTab, mobilityDataCsv, transportDataGouvFr } from 'react-gtfs-selector';
2323
import 'react-gtfs-selector/style.css'; // optional — bundled default styles
2424

2525
function App() {
@@ -32,24 +32,41 @@ function App() {
3232
console.log('Got URL:', result.title, result.url);
3333
}
3434
}}
35-
sources={[transportDataGouvFr, mobilityDataCsv]}
35+
tabs={[mobilityDataCsv, transportDataGouvFr, fileTab, urlTab]}
3636
/>
3737
);
3838
}
3939
```
4040

41-
The component shows a **tabbed interface**:
41+
The `tabs` prop controls exactly which tabs appear and in what order. Each entry is a `GtfsTab` object with `id`, `label`, and `component`.
4242

43-
1. **Import file** — drag & drop or click to browse for a GTFS `.zip` file
44-
2. **Load from URL** — paste a direct GTFS feed URL
45-
3. One tab per source plugin passed via the `sources` prop
43+
### Built-in tabs
44+
45+
- **`fileTab`** — drag & drop or click to browse for a GTFS `.zip` file
46+
- **`urlTab`** — paste a direct GTFS feed URL
47+
- **`mobilityDataCsv`** — search the Mobility Database (CSV, no token needed)
48+
- **`transportDataGouvFr`** — search French public transit feeds
49+
- **`mobilityData`** — Mobility Database API (unavailable by default, needs token)
50+
51+
### Examples
52+
53+
```tsx
54+
// Only file import and URL input
55+
<GtfsSelector onSelect={handleSelect} tabs={[fileTab, urlTab]} />
56+
57+
// Only Mobility Database search
58+
<GtfsSelector onSelect={handleSelect} tabs={[mobilityDataCsv]} />
59+
60+
// Custom order: sources first, then file, then URL
61+
<GtfsSelector onSelect={handleSelect} tabs={[mobilityDataCsv, transportDataGouvFr, fileTab, urlTab]} />
62+
```
4663

4764
## Props
4865

4966
| Prop | Type | Default | Description |
5067
|------|------|---------|-------------|
5168
| `onSelect` | `(result: GtfsSelectionResult) => void` | *required* | Callback when a source is selected |
52-
| `sources` | `GtfsSource[]` | `[]` | Source plugins for online search tabs |
69+
| `tabs` | `GtfsTab[]` | *required* | Ordered list of tabs to display |
5370
| `styled` | `boolean` | `true` | Set to `false` to disable default CSS class names |
5471
| `className` | `string` | — | Additional CSS class on the root element |
5572

@@ -66,36 +83,37 @@ type GtfsSelectionResult =
6683
French public transit GTFS feeds. Datasets are cached in localStorage for 24h.
6784

6885
```tsx
69-
import { GtfsSelector, transportDataGouvFr } from 'react-gtfs-selector';
86+
import { GtfsSelector, transportDataGouvFr, fileTab } from 'react-gtfs-selector';
7087

71-
<GtfsSelector onSelect={handleSelect} sources={[transportDataGouvFr]} />
88+
<GtfsSelector onSelect={handleSelect} tabs={[transportDataGouvFr, fileTab]} />
7289
```
7390

7491
## Mobility Database sources
7592

7693
The CSV source works out of the box with no configuration:
7794

7895
```tsx
79-
import { GtfsSelector, mobilityDataCsv } from 'react-gtfs-selector';
96+
import { GtfsSelector, mobilityDataCsv, fileTab } from 'react-gtfs-selector';
8097

81-
<GtfsSelector onSelect={handleSelect} sources={[mobilityDataCsv]} />
98+
<GtfsSelector onSelect={handleSelect} tabs={[mobilityDataCsv, fileTab]} />
8299
```
83100

84101
To use the API source, pass a configured instance with your token:
85102

86103
```tsx
87-
import { GtfsSelector, createMobilityDataSource } from 'react-gtfs-selector';
104+
import { GtfsSelector, createMobilityDataSource, fileTab } from 'react-gtfs-selector';
88105

89106
const mobilityApi = createMobilityDataSource({ apiToken: 'your-token' });
90107

91-
<GtfsSelector onSelect={handleSelect} sources={[mobilityApi]} />
108+
<GtfsSelector onSelect={handleSelect} tabs={[mobilityApi, fileTab]} />
92109
```
93110

94111
## Custom sources
95112

96-
You can implement the `GtfsSource` interface to add your own GTFS feed providers:
113+
Implement the `GtfsSource` interface and wrap it with `createSourceTab`:
97114

98115
```ts
116+
import { createSourceTab, fileTab } from 'react-gtfs-selector';
99117
import type { GtfsSource } from 'react-gtfs-selector';
100118

101119
const mySource: GtfsSource = {
@@ -106,15 +124,17 @@ const mySource: GtfsSource = {
106124
search(datasets, query) { /* ... */ },
107125
};
108126

109-
<GtfsSelector onSelect={handleSelect} sources={[mySource]} />
127+
const myTab = createSourceTab(mySource);
128+
129+
<GtfsSelector onSelect={handleSelect} tabs={[myTab, fileTab]} />
110130
```
111131

112132
## Loading GTFS data
113133

114134
Once the user selects a source, use [`gtfs-sqljs`](https://www.npmjs.com/package/gtfs-sqljs) to load and query the GTFS data:
115135

116136
```tsx
117-
import { GtfsSelector } from 'react-gtfs-selector';
137+
import { GtfsSelector, fileTab, urlTab } from 'react-gtfs-selector';
118138
import { GtfsSqlJs } from 'gtfs-sqljs';
119139
import type { GtfsSelectionResult } from 'react-gtfs-selector';
120140
@@ -135,7 +155,7 @@ function App() {
135155
gtfs.close();
136156
};
137157
138-
return <GtfsSelector onSelect={handleSelect} />;
158+
return <GtfsSelector onSelect={handleSelect} tabs={[fileTab, urlTab]} />;
139159
}
140160
```
141161

0 commit comments

Comments
 (0)