Initial scaffold

Author: nabeelre

.env.example

@@ -0,0 +1,13 @@
+# Copy to .env.local for local overrides. Vite only exposes vars prefixed VITE_.
+
+# Which data source to use: "local" or "hf".
+# Defaults: "local" in dev, "hf" in production builds.
+VITE_DATA_SOURCE=local
+
+# Path to the local dataset (relative to public/). JSON Lines format.
+VITE_LOCAL_DATA_PATH=data/sample.jsonl
+
+# HuggingFace dataset coordinates. Used when VITE_DATA_SOURCE=hf.
+VITE_HF_DATASET=username/your-dataset
+VITE_HF_CONFIG=default
+VITE_HF_SPLIT=train

.github/workflows/deploy.yml

@@ -0,0 +1,58 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Cancel in-flight runs but always finish the latest one.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        env:
+          # GitHub Pages serves the site from /<repo-name>/
+          BASE_PATH: /${{ github.event.repository.name }}/
+          # Production build: read from the HuggingFace API.
+          # Set HF_DATASET as a repository variable (Settings → Variables → Actions).
+          VITE_DATA_SOURCE: hf
+          VITE_HF_DATASET: ${{ vars.HF_DATASET }}
+          VITE_HF_CONFIG: ${{ vars.HF_CONFIG || 'default' }}
+          VITE_HF_SPLIT: ${{ vars.HF_SPLIT || 'train' }}
+        run: npm run build
+
+      - uses: actions/configure-pages@v4
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -0,0 +1,14 @@
+node_modules
+dist
+dist-ssr
+.vite
+*.log
+.DS_Store
+.env
+.env.local
+.env.*.local
+
+# Larger exported datasets — keep the small sample committed but
+# avoid checking in big exports. Uncomment if needed.
+# public/data/*.jsonl
+# !public/data/sample.jsonl

README.md

@@ -0,0 +1,124 @@
+# Time Series Explorer
+
+Static web UI for exploring a HuggingFace time-series dataset. Reads from a
+local JSONL file during development and from the HuggingFace Datasets Server
+API in production. Deploys to GitHub Pages.
+
+This is the **scaffolding phase** — the UI is intentionally a bare placeholder
+that just confirms the data pipeline works end to end. Real exploration UI
+lands in the design phase.
+
+## Stack
+
+- **Vite + React** — fast dev loop, builds to static files for GitHub Pages.
+- **Plotly.js** (via `react-plotly.js` factory + `plotly.js-dist-min`) — zoom,
+  pan, and rangeslider come built in.
+- Plain JavaScript (no TypeScript) — easy to add later if it earns its keep.
+
+## Project layout
+
+```
+.
+├── index.html                  # Vite entry
+├── vite.config.js              # base path is configurable for GH Pages
+├── package.json
+├── public/
+│   └── data/
+│       └── sample.jsonl        # tiny synthetic dataset for the dev loop
+├── src/
+│   ├── main.jsx                # React mount
+│   ├── App.jsx                 # placeholder UI (loads data, plots row 0)
+│   ├── index.css
+│   ├── config.js               # reads VITE_* env vars, picks data source
+│   ├── components/
+│   │   └── Plot.jsx            # Plotly wrapper (factory + dist-min)
+│   └── data/
+│       ├── DataSource.js       # abstract interface
+│       ├── LocalDataSource.js  # fetches JSONL from public/
+│       ├── HFDataSource.js     # hits datasets-server.huggingface.co
+│       └── index.js            # factory: returns the right one for the env
+├── scripts/
+│   └── export_to_json.py       # HF dataset → JSONL for local dev
+└── .github/workflows/
+    └── deploy.yml              # build + deploy to GitHub Pages
+```
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+Opens at http://localhost:5173 reading `public/data/sample.jsonl` (5 short
+synthetic series). You should see metadata up top and a Plotly preview of the
+first row.
+
+## Switching data sources
+
+Two modes, controlled by `VITE_DATA_SOURCE`:
+
+| Mode    | Reads from                                  | When        |
+| ------- | ------------------------------------------- | ----------- |
+| `local` | `public/<VITE_LOCAL_DATA_PATH>` (JSONL)     | dev default |
+| `hf`    | HuggingFace Datasets Server API (no auth, public datasets) | prod default |
+
+### Use your real dataset locally
+
+Convert the on-disk HF dataset to JSONL once:
+
+```bash
+pip install datasets
+python scripts/export_to_json.py \
+    --dataset /path/to/your/saved/dataset \
+    --output public/data/dataset.jsonl
+```
+
+Then in `.env.local`:
+
+```
+VITE_LOCAL_DATA_PATH=data/dataset.jsonl
+```
+
+For fast iteration while developing, pass `--limit 200` to export a subset.
+
+### Point at the HuggingFace Hub instead
+
+Once your dataset is uploaded:
+
+```
+VITE_DATA_SOURCE=hf
+VITE_HF_DATASET=your-username/your-dataset
+VITE_HF_CONFIG=default
+VITE_HF_SPLIT=train
+```
+
+The `HFDataSource` paginates the `/rows` endpoint (which caps at 100 rows per
+request).
+
+## Deploying to GitHub Pages
+
+1. Push this repo to GitHub.
+2. **Settings → Pages**: set source to **GitHub Actions**.
+3. **Settings → Secrets and variables → Actions → Variables**: add
+   `HF_DATASET` (and optionally `HF_CONFIG`, `HF_SPLIT`).
+4. Push to `main`. The workflow builds with `BASE_PATH=/<repo-name>/` and
+   deploys.
+
+The site URL will be `https://<your-username>.github.io/<repo-name>/`.
+
+> Static-site limitation: any HF token shipped with the build is public, so
+> the dataset must remain **public** on HuggingFace for this deployment model.
+
+## What's intentionally not here yet
+
+- Schema-aware exploration (filtering, multi-series overlay, search) — design
+  phase.
+- Styling beyond a minimal reset — design phase.
+- Tests — once the data layer firms up.
+- TypeScript — straightforward to add when the surface is bigger.
+
+## Next step
+
+Share a sample row (or the dataset schema) and we'll lock in the data shape
+the rest of the UI will be built around.

index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Time Series Explorer</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>