@jorgerdz/timeview 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+Timeview follows semantic versioning after the first published package. Compatibility rules
+for `TimeviewConfigV1` and `timeview.dataset.v1` are documented in
+`docs/COMPATIBILITY.md`.
+
+## 0.1.0
+
+- Prepare the project for npm publication as `@jorgerdz/timeview`.
+- Add library build outputs, declaration files, CSS token export, and a `timeview` CLI bin.
+- Document contribution, release, and generic agent usage paths.
+- Add basic config validation tests and CI checks.
+- Add complete JSON examples for every visualizer.
+- Add CLI `--json` success/error output and documented exit codes.
+- Upgrade Vite/tooling dependency chain so `npm audit` reports zero vulnerabilities.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timeview contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,263 @@
+# Timeview
+
+A library of reusable, time-based visualization components. Each visualizer renders a
+shared `TimeDataset` (schema `timeview.dataset.v1`) projected by a view-specific `ViewSpec`,
+so the same data can drive any chart.
+
+Current visualizers:
+- **BandedTimeline:** a horizontal day axis with instant-event milestones and colored
+  interval bands in stacked lanes.
+- **LaneCalendar:** the same events and intervals projected onto Mon-start week rows and
+  seven day columns.
+- **DensityHeatmap:** an aggregation view for counts and active duration by day/week and
+  category/total.
+- **MetricTimeline:** logged numeric values over time, such as weight, with contextual
+  state bands for periods like diet, maintenance, and off-plan.
+- **SpanMatrix:** category rows by day/week columns, showing interval presence, continuity,
+  overlap, and milestones as discrete cells.
+
+## Visual examples
+
+These examples are rendered from the default registry configs using the local Timeview
+renderer.
+
+### BandedTimeline
+
+Horizontal interval bands and milestone diamonds on a continuous day axis.
+
+![BandedTimeline example](docs/assets/timeview-examples/bandedTimeline.png)
+
+### LaneCalendar
+
+The same event and interval model projected into week rows and day cells.
+
+![LaneCalendar example](docs/assets/timeview-examples/laneCalendar.png)
+
+### DensityHeatmap
+
+Category-by-time aggregation for spotting count or duration density.
+
+![DensityHeatmap example](docs/assets/timeview-examples/densityHeatmap.png)
+
+### MetricTimeline
+
+Numeric samples over time with contextual state bands, target lines, milestones, and a
+frozen export viewport.
+
+![MetricTimeline example](docs/assets/timeview-examples/metricTimeline.png)
+
+### SpanMatrix
+
+Category rows by day/week buckets, with continuity, overlap counts, milestone markers, and
+today highlighting.
+
+![SpanMatrix example](docs/assets/timeview-examples/spanMatrix.png)
+
+## Quick start
+
+Install the React package in an application:
+
+```bash
+npm install @jorgerdz/timeview
+```
+
+```tsx
+import { BandedTimeline, TV_PALETTES, type TimeDataset } from "@jorgerdz/timeview";
+import "@jorgerdz/timeview/tokens.css";
+
+const dataset: TimeDataset = {
+  schemaVersion: "timeview.dataset.v1",
+  timezone: "UTC",
+  labels: [{ id: "work", name: "Work" }],
+  events: [],
+  intervals: [
+    {
+      id: "focus",
+      title: "Focus block",
+      range: { start: "2026-06-10", end: "2026-06-11" },
+      labelIds: ["work"],
+    },
+  ],
+};
+
+<BandedTimeline
+  dataset={dataset}
+  palette={TV_PALETTES.Studio}
+  spec={{ kind: "bandedTimeline", title: "Launch preparation" }}
+/>;
+```
+
+For local development in this repository:
+
+```bash
+npm install
+npm run dev      # open the printed localhost URL
+```
+
+The dev page is the component studio. It renders all registered visualizers and lets you
+switch datasets, palettes, density, visualizer-specific options, live/frozen date behavior,
+preview width, and dataset/spec JSON. It also supports URL hash share links, copyable JSON
+configs, copyable React snippets, PNG/HTML exports, and a copyable LLM prompt for
+generating valid configs.
+
+```bash
+npm run build      # typecheck (tsc -b) + production bundle to dist/
+npm test           # typecheck + config validation tests
+npm run typecheck  # types only
+```
+
+Complete JSON examples for every visualizer live in `examples/configs`.
+
+## Local agent rendering
+
+Command-running agents such as Hermes can use Timeview locally to create deterministic
+daily dashboard graphics. The agent writes a `TimeviewConfigV1` JSON file, validates it,
+then asks the CLI to render PNG or self-contained HTML artifacts through headless Chromium.
+
+```bash
+npm install
+npx playwright install chromium
+
+npm run --silent timeview -- describe --json
+npm run timeview -- validate ./daily/weight-trend.json --json
+npm run timeview -- render ./daily/weight-trend.json \
+  --format png \
+  --preset 1600x900 \
+  --out ./daily/out/weight-trend.png \
+  --json
+```
+
+For multi-panel daily dashboards, use a dashboard manifest:
+
+```json
+{
+  "v": 1,
+  "title": "Daily Dashboard",
+  "generatedAt": "2026-06-10",
+  "panels": [
+    {
+      "id": "weight-trend",
+      "title": "Weight trend",
+      "format": "png",
+      "preset": "1600x900",
+      "config": {
+        "v": 1,
+        "visualizer": "bandedTimeline",
+        "dataset": {
+          "schemaVersion": "timeview.dataset.v1",
+          "timezone": "UTC",
+          "labels": [{ "id": "work", "name": "Work" }],
+          "events": [],
+          "intervals": [
+            {
+              "id": "focus",
+              "title": "Focus block",
+              "range": { "start": "2026-06-10", "end": "2026-06-11" },
+              "labelIds": ["work"]
+            }
+          ]
+        },
+        "spec": { "kind": "bandedTimeline", "title": "Daily Dashboard" },
+        "palette": ["#2563eb"]
+      }
+    }
+  ]
+}
+```
+
+Render the full dashboard with:
+
+```bash
+npm run timeview -- render-dashboard ./daily/dashboard.json --out ./daily/out --today 2026-06-10
+```
+
+The dashboard command writes individual chart files plus `dashboard.html`,
+`dashboard.md`, and `manifest.json`. For reproducible agent output, set `today` fields to
+an ISO date or `null`; if a config uses `today: "auto"`, the CLI freezes it to `--today`
+or the local date at render time.
+
+See `docs/HERMES-TIMEVIEW-SKILL.md` for the agent-facing guide.
+See `docs/AGENT-USAGE.md` for the generic CLI and automation guide.
+
+## Using the component
+
+```tsx
+import { BandedTimeline, TV_DATA, TV_PALETTES } from "./timeview";
+
+<BandedTimeline
+  dataset={TV_DATA.default}
+  palette={TV_PALETTES.Studio}
+  spec={{
+    title: "Launch preparation timeline",
+    density: "comfortable",            // | "compact"
+    overlapMode: "lanes",              // | "packed" | "layered" | "hatched"
+    legend: { position: "bottom" },    // "top" | "bottom" | "right" | "off"
+    caption: { position: "bottom", text: "Intervals may overlap." },
+    events: { showLabels: true },
+  }}
+/>;
+```
+
+For hosted/studio configs, use the shared runtime helpers:
+
+```ts
+import {
+  decodeTimeviewConfig,
+  encodeTimeviewConfig,
+  normalizeViewSpec,
+  validateTimeDataset,
+} from "./timeview";
+```
+
+`LaneCalendarSpec.today` is explicit: `"auto"` uses the browser-local current date, an ISO
+string freezes the marker, and `null` or omitted disables it.
+
+Color is **data-only**: `palette[i]` maps to `dataset.labels` by index, so the same dataset
+re-themes by swapping the palette. The indigo chrome accent is reserved for selection/focus.
+
+## Layout
+
+```
+src/
+  styles/tokens.css          # the design language — single source of truth (--tv-*)
+  timeview/
+    types.ts                 # TimeDataset + ViewSpec contract
+    config.ts                # validation, spec normalization, URL-safe config helpers
+    registry.ts              # visualizer defaults, supported controls, agent guidance
+    data.ts                  # fixtures, palettes, scale/format helpers
+    BandedTimeline.tsx       # horizontal interval/milestone visualizer
+    LaneCalendar.tsx         # week/day calendar visualizer
+    DensityHeatmap.tsx       # aggregation matrix visualizer
+    MetricTimeline.tsx       # metric line + state-band visualizer
+    SpanMatrix.tsx           # interval presence / continuity matrix visualizer
+    index.ts                 # public surface
+  render.tsx                 # headless CLI render entrypoint
+  demo/
+    Stage.tsx                # component studio
+    studio/                  # studio layout and inspector chrome
+scripts/timeview.ts          # local agent rendering CLI
+docs/DESIGN-NOTES.md         # full handoff: API, states, export, a11y
+docs/COMPATIBILITY.md        # schema/config/API compatibility and versioning policy
+docs/PERSISTENCE.md          # short-link/backend persistence design notes
+docs/HERMES-TIMEVIEW-SKILL.md # command-running agent guide
+CLAUDE.md                    # durable conventions for new visualizers
+```
+
+See `docs/DESIGN-NOTES.md` for component states, interaction models, accessibility, and
+export notes. See `docs/ROADMAP.md` for the product roadmap across library mode, hosted
+renderer mode, agent mode, and future visualizers. See `docs/STUDIO.md` for studio build
+and deployment notes. See `docs/COMPATIBILITY.md` for the schema/config/API compatibility
+policy. See `docs/PERSISTENCE.md` for the future short-link and backend storage contract.
+See `CLAUDE.md` for the conventions every future visualizer must follow.
+
+## Roadmap
+
+The roadmap has two parallel tracks:
+
+- **Foundation and product surface:** package publishing, design system, registry,
+  showcase/studio site, hosted renderer, live browser behavior, and agent capability docs.
+- **Visualizer expansion:** more projections over the same `TimeDataset`, such as
+  `GanttTracks`, `MilestoneMap`, `TimeRibbon`, `RangeTable`, `MonthCalendar`,
+  `ActivityHistogram`, and `OverlapInspector`.
+
+See `docs/ROADMAP.md` for details.