Format entire codebase with Prettier (mechanical, no behavior change)

This commit is contained in:
2026-06-05 01:43:28 +03:00
parent 939950b136
commit 0c7297624e
32 changed files with 1597 additions and 832 deletions
+16 -5
View File
@@ -3,7 +3,7 @@
## The Problem
People who work with [Vega-Lite](https://vega.github.io/vega-lite/) directly — analysts,
educators, chart authors — don't have a fast, private place to *keep* their charts. The
educators, chart authors — don't have a fast, private place to _keep_ their charts. The
official Vega-Lite editor is great for a single spec in a tab, but it forgets everything
when you close it. Notebooks bury charts in code. BI tools hide the spec behind a GUI and
lock you into an account.
@@ -17,7 +17,7 @@ account, no server, and full offline use.**
The central artifact is the **snippet**: a saved Vega-Lite specification plus metadata.
Everything else — the editor, the live preview, the dataset library, the chart builder —
exists to author, organize, and reuse snippets. Astrolabe does not abstract Vega-Lite
away; a snippet *is* a Vega-Lite spec. The chart builder offers a no-JSON on-ramp, but the
away; a snippet _is_ a Vega-Lite spec. The chart builder offers a no-JSON on-ramp, but the
JSON is always the source of truth and always editable.
Reusable **datasets** are stored once and referenced by name from many snippets, so the
@@ -26,38 +26,44 @@ data lives in one place and the specs stay lean.
## Core Values
### 1. Local-Only by Default
Everything runs in the browser. Snippets, datasets, and settings never leave the machine.
No accounts, no uploads, no tracking. The only outbound requests are user-created
URL-dataset fetches.
### 2. Vega-Lite Native, Not Vega-Lite Hidden
The product domain *is* Vega-Lite. We validate, render, and reason about specs as
The product domain _is_ Vega-Lite. We validate, render, and reason about specs as
Vega-Lite, and we surface its real vocabulary (marks, encodings, field types). We don't
invent a parallel chart abstraction. The chart builder is an on-ramp, not a replacement
for the spec.
### 3. Experiment Safely
A snippet carries a stable **published** spec and an editable **draft**. You can tinker
freely without losing a known-good version. Auto-save protects in-progress work; publish
promotes it deliberately.
### 4. Beginner On-Ramp, Power-User Ceiling
The chart builder lets someone produce a chart without writing JSON. The editor — with
schema-aware autocomplete and live validation — lets a power user do anything Vega-Lite
can. Neither caps the other.
### 5. Own Your Data
Fully local and offline-capable, with import/export for backup and transfer. Your library
is a file you control, not a row in someone's database.
### 6. Predictable, Not Clever
When a behavior could go several ways, pick the one closest to the user's existing mental
model (the Vega-Lite editor, JSON tooling, file-based apps). Least surprise beats most
clever.
## What We're Not
- **Not a BI/dashboarding tool.** A snippet is *one* visualization, not a composed report
- **Not a BI/dashboarding tool.** A snippet is _one_ visualization, not a composed report
with cross-filters and layout. Dashboards are a different product.
- **Not a data-wrangling tool.** Datasets are stored and referenced, not cleaned or
transformed. (That's [Syto](https://github.com/) territory — Astrolabe's sibling in
@@ -69,29 +75,34 @@ clever.
## Technical Philosophy
### Spec-Driven, Clean Implementation
The behavioral contract lives in `docs/spec/`. Astrolabe is a deliberate rebuild on a
robust architecture (adapted from Syto): we implement *to the spec*, not by porting old
robust architecture (adapted from Syto): we implement _to the spec_, not by porting old
code. When the spec and convenience conflict, the spec wins or the spec changes — never
silent drift.
### Portable Core, Thin Browser Shell
`src/core/` is pure and portable — no browser APIs, no UI framework. Spec operations
(detection, profiling, reference resolution, fit transforms, validation, import
normalization) live there and are tested hardest. The UI is a thin, replaceable shell over
that core.
### Leverage Existing Libraries
Vega-Lite renders. Monaco edits. vega-embed mounts charts. React + Zustand drive the UI.
We wrap these with thin integration layers rather than reinventing them. Custom code
focuses on what's unique to Astrolabe: the snippet/dataset model, the rendering contract,
and the workspace that ties it together.
### No Parallel Systems
Each fact lives in one place. A snippet↔dataset link, a setting, a schema — one source of
truth, others derived. If you're writing the same logic twice, one should import or be
generated from the other.
### Test the Core, Trust the UI
High coverage on the portable engine (where a bug corrupts data or breaks rendering);
lighter coverage on components (where a bug is a cosmetic annoyance).