chart-factory 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Olsufka
+
+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,162 @@
+# chart-factory
+
+A token-driven, responsive chart library built on [D3 v7](https://d3js.org/). One factory, **79 builders across 12 families** — area, line, slope, bar, scatter, dot, histogram, donut/pie, box plot, calendar heatmap, and sankey charts plus sortable tables — that **fill whatever container you put them in** and re-render crisply on resize.
+
+- **Responsive by default** — charts measure their container, render at true pixel size, and adapt density (font size, tick count, dot radius) to the available width. No config needed.
+- **Design tokens** — all styling flows through 300+ CSS custom properties in `tokens.css`; retheme everything by overriding variables.
+- **No build required to consume** — plain ES modules plus a prebuilt browser bundle, TypeScript definitions included.
+- **Date-aware axes** — pass `Date` objects (or ISO strings) as x values and trend charts switch to time scales with adaptive tick formatting automatically.
+
+## Install
+
+```bash
+npm install chart-factory d3
+```
+
+`d3` (v7) is a peer dependency — install it alongside. React apps also want
+the adapter: `npm install chart-factory-react`.
+
+<details><summary>Other install sources</summary>
+
+```bash
+npm install ../chart-factory            # sibling checkout (local development)
+npm install github:jolsufka/chart-factory   # straight from git
+```
+
+</details>
+
+## Usage
+
+### With a bundler (ESM)
+
+```js
+import { ChartFactory } from 'chart-factory';
+import 'chart-factory/styles.css';   // everything (tokens + base + table), or import the pieces:
+// import 'chart-factory/core/tokens.css';
+// import 'chart-factory/core/base.css';
+
+ChartFactory.Line.createBasic('#chart', {
+    data,
+    xAccessor: d => d.week,
+    yAccessor: d => d.points
+});
+```
+
+### Script tag (no build)
+
+```html
+<link rel="stylesheet" href="node_modules/chart-factory/dist/chart-factory.css">
+<script src="https://d3js.org/d3.v7.min.js"></script>
+<script src="node_modules/chart-factory/dist/chart-factory.js"></script>
+<script>
+    ChartFactory.Bar.createBasic('#chart', { data, categoryAccessor: d => d.name, valueAccessor: d => d.value });
+</script>
+```
+
+The dist bundle uses the page's global `d3`, so load d3 first. Plugins that attach to the global (e.g. `d3-hexbin`, used by `Scatter.createHexbin`) keep working.
+
+### Responsive behavior
+
+Charts fill their container's width; height comes from a per-family aspect ratio (`aspectRatio` config to override, `height: <number>` for a fixed height). The container must be block-level with a real width:
+
+```css
+.chart-container { display: block; width: 100%; max-width: 660px; }
+```
+
+Horizontal bar/dot charts and gantt derive height from row count (width-responsive only). Pass `width: <number>` or `responsive: false` to opt out into fixed-size rendering. `size: 'mini' | 'full' | 'wide'` pins the density tier that is otherwise auto-selected from measured width (≤340px → mini, ≤620px → full, else wide). A fourth tier, `size: 'instagram'`, is opt-in only (never auto-selected): poster-scale geometry for 1080px social-feed exports, paired with `<html data-size="instagram">` to scale the text/stroke tokens to match — see docs/API.md.
+
+Every chart returns a facade: `chart.setConfig({...})` merges config and re-renders (state survives resizes), `chart.rerender()`, `chart.destroy()`.
+
+### Tables
+
+```js
+import { ChartFactory } from 'chart-factory';
+import { D3Table } from 'chart-factory/table';
+import 'chart-factory/table/tokens.css';
+import 'chart-factory/table/table.css';
+
+ChartFactory.Table.register(D3Table);   // one-time
+ChartFactory.Table.createSortable('my-table', { columns: [...] }).render(data);
+```
+
+In the browser without a bundler, import `dist/chart-factory-table.js` from a `<script type="module">` (d3 already on the page).
+
+### Dark mode
+
+Opt in by setting `data-theme="dark"` on the root element:
+
+```html
+<html data-theme="dark">
+```
+
+Every color-bearing token (text, surfaces, chart palettes, table heatmap/bar
+ramps) has a dark value in `core/tokens.css`; spacing and sizing carry over.
+Charts read tokens **live at render time**, so switching themes at runtime
+needs a re-render — SVG attribute colors are baked in at draw:
+
+```js
+document.documentElement.dataset.theme = 'dark';  // or delete it for light
+ChartFactory.rerenderAll();  // re-resolves every live chart and table
+```
+
+(`rerenderAll()` tracks all charts and factory-created tables; individual
+handles work too: `chart.rerender()`, `table.rerender()`.)
+
+CSS-styled surfaces (containers, tooltip shell, table chrome) restyle
+immediately without a re-render. There is no automatic
+`prefers-color-scheme` switching — wire the attribute (and the re-render
+calls) to your app's theme state; in React/Next.js, `next-themes` with
+`attribute="data-theme"` pairs naturally.
+
+### Chart states
+
+Dashboards hit three awkward moments; the chart owns all of them:
+
+```js
+const chart = ChartFactory.Line.createBasic('#c', { state: 'loading' });  // skeleton now
+fetch('/api/rows').then(r => r.json())
+    .then(rows => chart.setData(rows))          // real chart (setData ends 'loading')
+    .catch(() => chart.setConfig({ state: 'error' }));
+// rows.length === 0 → the built-in empty state renders automatically
+```
+
+The loading skeleton is family-aware (trend silhouette for line/area,
+breathing columns/rows for bars, quiet dots elsewhere) and takes the chart's
+exact footprint, so the real chart swaps in with zero layout jump.
+`emptyMessage` / `errorMessage` override the state text.
+Live demo (all three states + a fetch simulator):
+[`examples/states-demo.html`](examples/states-demo.html).
+
+## Chart catalog
+
+| Factory | Variants |
+|---|---|
+| `ChartFactory.Area` | basic, stacked, normalized, smoothed, streamgraph, diverging |
+| `ChartFactory.Line` | basic, multi, yearly, smoothed, combined, YoY, textures, area-gradient, growth-rate, forecast-band, dynamic-band, pulse-anomalies, cumulative-vs-moving, bump |
+| `ChartFactory.Slope` | basic, trend, categorical, highlight, animated, bands, indexed |
+| `ChartFactory.Bar` | basic, inline, label-above, progress, bullet, diverging, stacked, grouped, likert, gantt, range, waterfall, pyramid, vertical, vertical-stacked, vertical-normalized |
+| `ChartFactory.Scatter` | basic, logos, animated, trajectory, comet, beeswarm (×4), heatmap, hexbin, contour, quadrant, diagonal, marginal (×3), KDE |
+| `ChartFactory.Dot` | basic, dumbbell, gradient, comet, confidence, percentile, unit-histogram |
+| `ChartFactory.Histogram` | basic, overlay |
+| `ChartFactory.Donut` | basic (donut; `innerRatio: 0` = pie) |
+| `ChartFactory.BoxPlot` | basic (both orientations, raw or precomputed) |
+| `ChartFactory.Calendar` | heatmap (weekly / monthRows / vertical layouts) |
+| `ChartFactory.Sankey` | basic (d3-sankey optional, built-in fallback) |
+| `ChartFactory.Table` | basic, sortable, with-bars, with-heatmap, combined |
+
+Live examples for every variant are in [`examples/`](examples/) — serve the repo root (`npm run serve`) and open `http://localhost:8000/examples/`.
+
+## Development
+
+```bash
+npm install        # installs esbuild
+npm run build      # bundles src/ -> dist/ (also runs on npm prepare)
+npm run watch      # rebuild on change
+npm run serve      # static server for examples/
+```
+
+Source lives in `src/` as plain ES modules; `dist/` holds the generated browser bundles. All styling values must flow through the design tokens in [`src/core/tokens.css`](src/core/tokens.css) — never hardcode colors, spacing, or font sizes.
+
+## License
+
+[MIT](LICENSE)