fjader 0.2.0__tar.gz

fjader-0.2.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025-2026, the fjader authors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

fjader-0.2.0/NOTICE

@@ -0,0 +1,114 @@
+================================================================================
+THIRD-PARTY NOTICES
+================================================================================
+
+The projects below shaped fjader's design, and parts of its code are adapted
+from Mosaic. Their licenses follow in full.
+
+--------------------------------------------------------------------------------
+Mosaic, by the UW Interactive Data Lab
+https://github.com/uwdata/mosaic
+--------------------------------------------------------------------------------
+
+fjader began as a Mosaic client, with @uwdata/mosaic-core as a dependency, and
+its query layer is built on what Mosaic showed works. It now has its own query
+layer, still builds every query with @uwdata/mosaic-sql, a direct dependency,
+and kept Mosaic's ideas and, in places, the structure of Mosaic's code:
+
+- Pre-aggregation with sufficient statistics. The preaggregation code in
+  src/lib/query-engine/ (sufficient-statistics.ts and preagg/) follows
+  mosaic-core's preagg module: aggregates rewritten into partial statistics,
+  FILTER clauses carried onto them, and preaggregated tables named by a hash
+  of their query.
+- The crossfilter selection model, in which a selection clause filters every
+  mark except those its source excludes.
+- vgplot's API style, its interactors (interval brushes, toggles) and its
+  JSON spec layout (hconcat, vconcat), without being compatible with vgplot.
+
+Mosaic's license, reproduced in full, including its own notice for the parts
+it derives from Observable Plot:
+
+BSD 3-Clause License
+
+Copyright (c) 2023-2025, UW Interactive Data Lab
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+---
+
+Portions of this software are derived from Observable Plot, which is released
+under the ISC license.
+
+Copyright 2020-2023 Observable, Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+--------------------------------------------------------------------------------
+Observable Plot, by Observable, Inc.
+https://github.com/observablehq/plot
+--------------------------------------------------------------------------------
+
+fjader's mark API borrows from Observable Plot, though it is its own API and
+not compatible with Plot's: mark names and channels, the shorthands that imply
+stacking (x for x1/x2, y for y1/y2), the stackX/stackY conventions, z as the
+series grouping channel, and many defaults.
+
+fjader contains no code from Observable Plot; its license is included as a
+courtesy. Observable Plot's license (ISC):
+
+Copyright 2020-2025 Observable, Inc.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+--------------------------------------------------------------------------------
+Bundled dependencies
+--------------------------------------------------------------------------------
+
+The Python package ships prebuilt JavaScript bundles that include third-party
+packages, among them Svelte, d3, Flechette, mosaic-sql, Apache Arrow and
+DuckDB-WASM. Each bundle sits next to a THIRD_PARTY_LICENSES.txt listing every
+package compiled into it, with its license in full. The npm package bundles
+nothing: its dependencies install with their own licenses.

fjader-0.2.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: fjader
+Version: 0.2.0
+Summary: An experimental, declarative charting library for Svelte and Python that queries DuckDB and renders with WebGPU
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: narwhals>=1.0
+Requires-Dist: anywidget>=0.9
+Requires-Dist: pytest>=7.0 ; extra == 'dev'
+Requires-Dist: mypy>=1.0 ; extra == 'dev'
+Requires-Dist: pyarrow>=14.0 ; extra == 'pyarrow'
+Requires-Dist: streamlit>=1.0 ; extra == 'streamlit'
+Requires-Dist: pyarrow>=14.0 ; extra == 'streamlit'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/dlyngman/fjader
+Provides-Extra: dev
+Provides-Extra: pyarrow
+Provides-Extra: streamlit
+Description-Content-Type: text/markdown
+
+# fjader
+
+An experimental charting library for Svelte and Python with a declarative, grammar-of-graphics API, that queries DuckDB and renders with WebGPU. It is not feature complete, and the API may still change.
+
+fjader builds on the ideas of [Mosaic](https://github.com/uwdata/mosaic): charts are described as marks whose data comes from SQL queries run in DuckDB, and linked charts filter each other through selections. Its marks and channels borrow from [Observable Plot](https://observablehq.com/plot/), but the API is its own and not compatible with Plot's. Query results arrive as Arrow and are drawn with WebGPU.
+
+There are three ways to use it: Svelte components; a JSON spec, rendered from JavaScript with `Fjader.render(element, spec)`; and a Python package that builds specs and renders them in Jupyter, marimo or Streamlit.
+
+The name comes from Swedish _fjäder_ (say "fyeh-der"), which means both spring and feather.
+
+## Install
+
+```bash
+npm install @fjader/svelte @uwdata/mosaic-sql   # Svelte 5 components, and the SQL builder the examples use
+pip install fjader                 # Python: marimo and Jupyter
+pip install "fjader[streamlit]"    # Python: Streamlit
+```
+
+fjader needs Chrome 149 or later, or another Chromium browser on that version. It relies on two recent features other browsers don't ship yet: WebGPU's `immediate_address_space`, through which every chart passes its scales to the shaders (so every zoom and pan uses it), and the `Temporal` API, used for calendar offsets. There is no fallback renderer.
+
+Three things to know before using it in a deployed app:
+
+- **Data goes to the browser in full.** The Python widget and the Streamlit component send every column of a DataFrame to the browser, where DuckDB-WASM queries it. Anyone viewing the app can extract it, so pass only the columns you mean to show. In Jupyter, saved widget state can also store the data in the notebook file.
+- **DuckDB-WASM loads from jsDelivr at runtime.** The browser fetches it from the CDN, so locked-down networks that block it cannot render charts.
+- **Specs are trusted input.** A spec's `{ "sql": "…" }` field runs as raw SQL in the viewer's DuckDB-WASM. Don't build specs from untrusted input.
+
+## Svelte
+
+```svelte
+<script>
+	import {
+		initFjader,
+		ChartContainer,
+		WebGPUCanvas,
+		AxisLeft,
+		AxisBottom,
+		Grid,
+		BarMarkY,
+		stack
+	} from '@fjader/svelte';
+	import { count, loadParquet } from '@uwdata/mosaic-sql';
+	import { onMount } from 'svelte';
+
+	const { queryEngine } = initFjader();
+	let loaded = $state(false);
+
+	// DuckDB-WASM fetches only full URLs; a bare path means its own file system.
+	onMount(async () => {
+		const url = new URL('/data/penguins.parquet', location.href).href;
+		await queryEngine.exec([loadParquet('penguins', url).toString()]);
+		loaded = true;
+	});
+</script>
+
+{#if loaded}
+	<div style="height: 400px">
+		<ChartContainer xLabel="island" yLabel="count">
+			{#snippet background()}
+				<AxisLeft />
+				<AxisBottom />
+			{/snippet}
+			{#snippet canvas()}
+				<WebGPUCanvas>
+					{#snippet canvasComponents()}
+						<Grid />
+						<BarMarkY
+							table="penguins"
+							x="island"
+							y={count()}
+							fill="species"
+							transforms={[stack()]}
+						/>
+					{/snippet}
+				</WebGPUCanvas>
+			{/snippet}
+		</ChartContainer>
+	</div>
+{/if}
+```
+
+A chart is a container with layers: axes in the background, marks on the GPU canvas. It fills its parent, so give the parent a height; the Python widget and Streamlit set one for you (400 and 500 px). The same chart can be written as a JSON spec and rendered with `Fjader.render(element, spec)`; the npm package ships Svelte source, so this needs a build that compiles Svelte, such as Vite with the Svelte plugin.
+
+## Python
+
+```python
+import polars as pl
+import fjader as fj
+
+weather = pl.read_parquet("seattle-weather.parquet")
+
+fj.plot(
+    fj.dot(data=weather, x="date", y="temp_max", fill="weather", r="precipitation"),
+    x_label="Date",
+    y_label="Max temperature (°F)",
+)
+```
+
+Charts display on their own in marimo and Jupyter; in Streamlit, call `fj.streamlit.render(chart)`. polars DataFrames need nothing more; pandas ones need pyarrow (`pip install "fjader[pyarrow]"`). Marks compose: `*` overlays two marks in one chart, `+` places charts side by side, and `df.fj.dot(x=..., y=...)` works straight from a pandas or polars DataFrame.
+
+## How it works
+
+**Queries.** Aggregation, binning, filtering, top-N, stacking and normalization compile to SQL and run in DuckDB-WASM in the browser. What reaches JavaScript is sized by the chart, not by the data.
+
+**Selections.** As in Mosaic, brushes crossfilter the other charts, and pre-aggregated tables binned at pixel resolution keep brushing fast. fjader builds them on the first hover over a chart.
+
+**Marks.** Charts are built from marks (dots, bars, rects, lines, areas, rules, text, parallel coordinates). Marks declare the scales they need, and charts sharing a variable share its scale.
+
+**Rendering.** WebGPU shaders draw the marks. A fixed-timestep spring simulation animates domain changes and transitions between states. Level-of-detail rungs move between dots, bins and smoothed density; shift+scroll moves through them.
+
+## Project structure
+
+```
+src/lib/
+  components/     Marks, charts, axes, legends, interaction overlays
+  query-engine/   DuckDB connection, crossfilter, pre-aggregation
+  transforms/     Transform pipeline (SQL first, then JS)
+  scales/         Scale requirements, resolution and shared scale state
+  gpu/            GPUCoordinator, pipelines, shader libraries
+  animation/      Spring physics and the fixed-timestep loop
+  lod/            Level-of-detail rungs
+  interactors/    Brushes, toggles, tooltips, pan and zoom
+  spec/           JSON spec renderer and export
+python/fjader/    Python API, Jupyter widget, Streamlit component
+```
+
+## Development
+
+```bash
+npm install
+npm run fetch-data       # Example datasets, from their upstream sources
+npm run dev              # Dev server with examples and test routes
+npm run build            # Production build
+npm run lint             # ESLint + Prettier
+npx vitest               # JavaScript tests
+npm run build:python     # Widget and Streamlit bundles, then the Python wheel
+```
+
+The Python package's widget and Streamlit bundles are build output and not in git. In a checkout, run `npm run build:all` before using the Python package, and again after changing JavaScript code.
+
+The pages under `src/routes/` are development and test pages for working on fjader, not documentation. They read the example data that `npm run fetch-data` downloads.
+
+## Acknowledgements
+
+fjader takes ideas from two projects, and in places code from Mosaic:
+
+- **[Mosaic](https://github.com/uwdata/mosaic)**, by the UW Interactive Data Lab. fjader began as a Mosaic client, with `@uwdata/mosaic-core` as a dependency, and its query layer still follows Mosaic's design: pre-aggregation with sufficient statistics and the crossfilter selection model. The API, interactors and JSON spec layout are modeled on vgplot's, without being compatible with it. As fjader moved to rendering directly in WebGPU, it needed its queries tied more closely to its marks: results shaped for GPU buffers, query timing coupled to interaction frames, and state that follows Svelte 5's reactivity rather than a callback protocol. So it replaced `mosaic-core` with its own query layer, adapted from Mosaic's, and still builds every query with `@uwdata/mosaic-sql`.
+- **[Observable Plot](https://github.com/observablehq/plot)**, by Observable. Mark names, channel shorthands, stacking conventions and many defaults are modeled on Plot's.
+
+Mosaic is described in Jeffrey Heer and Dominik Moritz, [_Mosaic: An Architecture for Scalable & Interoperable Data Views_](https://idl.uw.edu/papers/mosaic), IEEE Transactions on Visualization and Computer Graphics 30 (Proc. VIS 2023), 2024, [doi:10.1109/TVCG.2023.3327189](https://doi.org/10.1109/TVCG.2023.3327189).
+
+It also rests on [DuckDB](https://duckdb.org) and [DuckDB-WASM](https://github.com/duckdb/duckdb-wasm), [Flechette](https://github.com/uwdata/flechette), [d3](https://d3js.org) and [Svelte](https://svelte.dev).
+
+## License
+
+BSD 3-Clause; see [LICENSE](https://github.com/dlyngman/fjader/blob/main/LICENSE). [NOTICE](https://github.com/dlyngman/fjader/blob/main/NOTICE) credits the work fjader adapts and reproduces the licenses of Mosaic and Observable Plot in full. The Python package's bundled JavaScript ships with a `THIRD_PARTY_LICENSES.txt` covering every package compiled into it.

fjader-0.2.0/README.md

@@ -0,0 +1,155 @@
+# fjader
+
+An experimental charting library for Svelte and Python with a declarative, grammar-of-graphics API, that queries DuckDB and renders with WebGPU. It is not feature complete, and the API may still change.
+
+fjader builds on the ideas of [Mosaic](https://github.com/uwdata/mosaic): charts are described as marks whose data comes from SQL queries run in DuckDB, and linked charts filter each other through selections. Its marks and channels borrow from [Observable Plot](https://observablehq.com/plot/), but the API is its own and not compatible with Plot's. Query results arrive as Arrow and are drawn with WebGPU.
+
+There are three ways to use it: Svelte components; a JSON spec, rendered from JavaScript with `Fjader.render(element, spec)`; and a Python package that builds specs and renders them in Jupyter, marimo or Streamlit.
+
+The name comes from Swedish _fjäder_ (say "fyeh-der"), which means both spring and feather.
+
+## Install
+
+```bash
+npm install @fjader/svelte @uwdata/mosaic-sql   # Svelte 5 components, and the SQL builder the examples use
+pip install fjader                 # Python: marimo and Jupyter
+pip install "fjader[streamlit]"    # Python: Streamlit
+```
+
+fjader needs Chrome 149 or later, or another Chromium browser on that version. It relies on two recent features other browsers don't ship yet: WebGPU's `immediate_address_space`, through which every chart passes its scales to the shaders (so every zoom and pan uses it), and the `Temporal` API, used for calendar offsets. There is no fallback renderer.
+
+Three things to know before using it in a deployed app:
+
+- **Data goes to the browser in full.** The Python widget and the Streamlit component send every column of a DataFrame to the browser, where DuckDB-WASM queries it. Anyone viewing the app can extract it, so pass only the columns you mean to show. In Jupyter, saved widget state can also store the data in the notebook file.
+- **DuckDB-WASM loads from jsDelivr at runtime.** The browser fetches it from the CDN, so locked-down networks that block it cannot render charts.
+- **Specs are trusted input.** A spec's `{ "sql": "…" }` field runs as raw SQL in the viewer's DuckDB-WASM. Don't build specs from untrusted input.
+
+## Svelte
+
+```svelte
+<script>
+	import {
+		initFjader,
+		ChartContainer,
+		WebGPUCanvas,
+		AxisLeft,
+		AxisBottom,
+		Grid,
+		BarMarkY,
+		stack
+	} from '@fjader/svelte';
+	import { count, loadParquet } from '@uwdata/mosaic-sql';
+	import { onMount } from 'svelte';
+
+	const { queryEngine } = initFjader();
+	let loaded = $state(false);
+
+	// DuckDB-WASM fetches only full URLs; a bare path means its own file system.
+	onMount(async () => {
+		const url = new URL('/data/penguins.parquet', location.href).href;
+		await queryEngine.exec([loadParquet('penguins', url).toString()]);
+		loaded = true;
+	});
+</script>
+
+{#if loaded}
+	<div style="height: 400px">
+		<ChartContainer xLabel="island" yLabel="count">
+			{#snippet background()}
+				<AxisLeft />
+				<AxisBottom />
+			{/snippet}
+			{#snippet canvas()}
+				<WebGPUCanvas>
+					{#snippet canvasComponents()}
+						<Grid />
+						<BarMarkY
+							table="penguins"
+							x="island"
+							y={count()}
+							fill="species"
+							transforms={[stack()]}
+						/>
+					{/snippet}
+				</WebGPUCanvas>
+			{/snippet}
+		</ChartContainer>
+	</div>
+{/if}
+```
+
+A chart is a container with layers: axes in the background, marks on the GPU canvas. It fills its parent, so give the parent a height; the Python widget and Streamlit set one for you (400 and 500 px). The same chart can be written as a JSON spec and rendered with `Fjader.render(element, spec)`; the npm package ships Svelte source, so this needs a build that compiles Svelte, such as Vite with the Svelte plugin.
+
+## Python
+
+```python
+import polars as pl
+import fjader as fj
+
+weather = pl.read_parquet("seattle-weather.parquet")
+
+fj.plot(
+    fj.dot(data=weather, x="date", y="temp_max", fill="weather", r="precipitation"),
+    x_label="Date",
+    y_label="Max temperature (°F)",
+)
+```
+
+Charts display on their own in marimo and Jupyter; in Streamlit, call `fj.streamlit.render(chart)`. polars DataFrames need nothing more; pandas ones need pyarrow (`pip install "fjader[pyarrow]"`). Marks compose: `*` overlays two marks in one chart, `+` places charts side by side, and `df.fj.dot(x=..., y=...)` works straight from a pandas or polars DataFrame.
+
+## How it works
+
+**Queries.** Aggregation, binning, filtering, top-N, stacking and normalization compile to SQL and run in DuckDB-WASM in the browser. What reaches JavaScript is sized by the chart, not by the data.
+
+**Selections.** As in Mosaic, brushes crossfilter the other charts, and pre-aggregated tables binned at pixel resolution keep brushing fast. fjader builds them on the first hover over a chart.
+
+**Marks.** Charts are built from marks (dots, bars, rects, lines, areas, rules, text, parallel coordinates). Marks declare the scales they need, and charts sharing a variable share its scale.
+
+**Rendering.** WebGPU shaders draw the marks. A fixed-timestep spring simulation animates domain changes and transitions between states. Level-of-detail rungs move between dots, bins and smoothed density; shift+scroll moves through them.
+
+## Project structure
+
+```
+src/lib/
+  components/     Marks, charts, axes, legends, interaction overlays
+  query-engine/   DuckDB connection, crossfilter, pre-aggregation
+  transforms/     Transform pipeline (SQL first, then JS)
+  scales/         Scale requirements, resolution and shared scale state
+  gpu/            GPUCoordinator, pipelines, shader libraries
+  animation/      Spring physics and the fixed-timestep loop
+  lod/            Level-of-detail rungs
+  interactors/    Brushes, toggles, tooltips, pan and zoom
+  spec/           JSON spec renderer and export
+python/fjader/    Python API, Jupyter widget, Streamlit component
+```
+
+## Development
+
+```bash
+npm install
+npm run fetch-data       # Example datasets, from their upstream sources
+npm run dev              # Dev server with examples and test routes
+npm run build            # Production build
+npm run lint             # ESLint + Prettier
+npx vitest               # JavaScript tests
+npm run build:python     # Widget and Streamlit bundles, then the Python wheel
+```
+
+The Python package's widget and Streamlit bundles are build output and not in git. In a checkout, run `npm run build:all` before using the Python package, and again after changing JavaScript code.
+
+The pages under `src/routes/` are development and test pages for working on fjader, not documentation. They read the example data that `npm run fetch-data` downloads.
+
+## Acknowledgements
+
+fjader takes ideas from two projects, and in places code from Mosaic:
+
+- **[Mosaic](https://github.com/uwdata/mosaic)**, by the UW Interactive Data Lab. fjader began as a Mosaic client, with `@uwdata/mosaic-core` as a dependency, and its query layer still follows Mosaic's design: pre-aggregation with sufficient statistics and the crossfilter selection model. The API, interactors and JSON spec layout are modeled on vgplot's, without being compatible with it. As fjader moved to rendering directly in WebGPU, it needed its queries tied more closely to its marks: results shaped for GPU buffers, query timing coupled to interaction frames, and state that follows Svelte 5's reactivity rather than a callback protocol. So it replaced `mosaic-core` with its own query layer, adapted from Mosaic's, and still builds every query with `@uwdata/mosaic-sql`.
+- **[Observable Plot](https://github.com/observablehq/plot)**, by Observable. Mark names, channel shorthands, stacking conventions and many defaults are modeled on Plot's.
+
+Mosaic is described in Jeffrey Heer and Dominik Moritz, [_Mosaic: An Architecture for Scalable & Interoperable Data Views_](https://idl.uw.edu/papers/mosaic), IEEE Transactions on Visualization and Computer Graphics 30 (Proc. VIS 2023), 2024, [doi:10.1109/TVCG.2023.3327189](https://doi.org/10.1109/TVCG.2023.3327189).
+
+It also rests on [DuckDB](https://duckdb.org) and [DuckDB-WASM](https://github.com/duckdb/duckdb-wasm), [Flechette](https://github.com/uwdata/flechette), [d3](https://d3js.org) and [Svelte](https://svelte.dev).
+
+## License
+
+BSD 3-Clause; see [LICENSE](https://github.com/dlyngman/fjader/blob/main/LICENSE). [NOTICE](https://github.com/dlyngman/fjader/blob/main/NOTICE) credits the work fjader adapts and reproduces the licenses of Mosaic and Observable Plot in full. The Python package's bundled JavaScript ships with a `THIRD_PARTY_LICENSES.txt` covering every package compiled into it.

fjader-0.2.0/fjader/__init__.py

@@ -0,0 +1,98 @@
+"""Fjader — GPU-accelerated data visualization for Python.
+
+Phase 1: Spec generation. Produces JSON specs consumed by the Fjader
+JavaScript renderer.
+
+Usage:
+    import fjader as fj
+
+    chart = fj.dot(table='penguins', x='bill_length', y='bill_depth', fill='species')
+    chart.to_dict()
+
+    # Overlay (two marks, one chart)
+    overlay = fj.dot(table='t', x='a', y='b') * fj.line(table='t', x='a', y='b')
+
+    # Layout (two charts side by side)
+    layout = fj.dot(table='t', x='a', y='b') + fj.bar_y(table='t', x='species', y='count()')
+
+    # Chart-level config
+    fj.plot(fj.dot(table='t', x='a', y='b'), width=600, x_label='X')
+"""
+
+from ._version import __version__
+
+# Mark factory functions
+from .marks import dot, bar_x, bar_y, line, area_y, area_x, rect, rect_x, rect_y, text
+
+# Chart container
+from .plot import plot
+
+# Interactors
+from .interactors import interval_x, interval_y, interval_2d, toggle, derived_interval
+
+# Layout helpers
+from .layout import hconcat, vconcat
+
+# Transforms
+from .transforms import (
+    filter,
+    having,
+    limit,
+    orderby,
+    topN,
+    stack_y,
+    stack_x,
+    normalize,
+    dodge,
+)
+
+# Field spec helpers
+from .fields import count, sum, avg, min_, max_, median, bin, window, sql_expr
+
+# Data helpers
+from .data import sql
+
+# Display helpers
+from ._display import show
+
+# Spec import
+from ._from_spec import from_spec
+
+# Lazy submodule access — import only when accessed (avoids hard dep on streamlit)
+import importlib as _importlib
+
+def __getattr__(name: str):
+    if name == "streamlit":
+        return _importlib.import_module("._streamlit", __name__)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+# Types (for type annotations in user code)
+from ._types import ColorScheme, CurveType, ScaleType, SortConfig, TextAnchor, LineAnchor
+from .fields import FieldSpec
+
+__all__ = [
+    "__version__",
+    # Marks
+    "dot", "bar_x", "bar_y", "line", "area_y", "area_x",
+    "rect", "rect_x", "rect_y", "text",
+    # Chart
+    "plot",
+    # Interactors
+    "interval_x", "interval_y", "interval_2d", "toggle", "derived_interval",
+    # Layout
+    "hconcat", "vconcat",
+    # Transforms
+    "filter", "having", "limit", "orderby",
+    "topN", "stack_y", "stack_x", "normalize", "dodge",
+    # Fields
+    "count", "sum", "avg", "min_", "max_", "median", "bin", "window", "sql_expr",
+    # Data
+    "sql",
+    # Display
+    "show",
+    # Spec import
+    "from_spec",
+    # Types
+    "FieldSpec", "ColorScheme", "CurveType", "ScaleType",
+    "SortConfig", "TextAnchor", "LineAnchor",
+]

fjader-0.2.0/fjader/_accessor.py

@@ -0,0 +1,74 @@
+"""Shared DataFrame accessor for Fjader.
+
+Provides ``df.fj.dot(x='a', y='b')`` syntax for quick exploration.
+Returns anywidget instances that auto-display in Jupyter and Marimo,
+and support composition via ``*`` (overlay), ``+`` (layout), and ``.opts()``.
+
+Registration is done by importing the appropriate module::
+
+    import fjader.pandas as fj   # registers .fj on pandas DataFrames
+    import fjader.polars as fj   # registers .fj on polars DataFrames
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from . import marks as _marks
+from ._display import show
+
+
+class FjaderAccessor:
+    """DataFrame accessor — ``df.fj.dot(x='a', y='b', fill='species')``."""
+
+    def __init__(self, df: Any) -> None:
+        self._df = df
+
+    def _call(self, factory: Any, **kwargs: Any) -> Any:
+        for key in ("data", "table"):
+            if key in kwargs:
+                raise TypeError(
+                    f"Cannot pass '{key}' through the .fj accessor — "
+                    f"data is implicitly the DataFrame itself."
+                )
+        return show(factory(data=self._df, **kwargs))
+
+    def dot(self, **kwargs: Any) -> Any:
+        """Scatter/dot mark. See ``fj.dot()`` for parameters."""
+        return self._call(_marks.dot, **kwargs)
+
+    def bar_x(self, **kwargs: Any) -> Any:
+        """Horizontal bar mark. See ``fj.bar_x()`` for parameters."""
+        return self._call(_marks.bar_x, **kwargs)
+
+    def bar_y(self, **kwargs: Any) -> Any:
+        """Vertical bar mark. See ``fj.bar_y()`` for parameters."""
+        return self._call(_marks.bar_y, **kwargs)
+
+    def line(self, **kwargs: Any) -> Any:
+        """Line mark. See ``fj.line()`` for parameters."""
+        return self._call(_marks.line, **kwargs)
+
+    def area_y(self, **kwargs: Any) -> Any:
+        """Vertical area mark. See ``fj.area_y()`` for parameters."""
+        return self._call(_marks.area_y, **kwargs)
+
+    def area_x(self, **kwargs: Any) -> Any:
+        """Horizontal area mark. See ``fj.area_x()`` for parameters."""
+        return self._call(_marks.area_x, **kwargs)
+
+    def rect(self, **kwargs: Any) -> Any:
+        """Rectangle mark. See ``fj.rect()`` for parameters."""
+        return self._call(_marks.rect, **kwargs)
+
+    def rect_x(self, **kwargs: Any) -> Any:
+        """Horizontal rect mark. See ``fj.rect_x()`` for parameters."""
+        return self._call(_marks.rect_x, **kwargs)
+
+    def rect_y(self, **kwargs: Any) -> Any:
+        """Vertical rect mark. See ``fj.rect_y()`` for parameters."""
+        return self._call(_marks.rect_y, **kwargs)
+
+    def text(self, **kwargs: Any) -> Any:
+        """Text mark. See ``fj.text()`` for parameters."""
+        return self._call(_marks.text, **kwargs)