@orchidsoftware/charts 0.0.1

package/docs/bubble.md

@@ -0,0 +1,76 @@
+# Bubble charts
+
+## Introduction
+
+Bubble charts compare three measurements at once. The `x` and `y` properties
+position each point, while `r` controls its radius.
+
+## Creating a bubble chart
+
+```js
+import { BubbleChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = BubbleChart.make("#accounts")
+  .dataset("Accounts", [
+    { x: 12, y: 38, r: 6 },
+    { x: 18, y: 51, r: 10 },
+    { x: 25, y: 63, r: 15 },
+  ])
+  .render();
+```
+
+The value returned by `render()` is the mounted chart and may be updated,
+selected, or exported.
+
+## Comparing datasets
+
+Name each dataset so the legend and tooltip can distinguish its bubbles:
+
+```js
+import { BubbleChart } from "@orchidsoftware/charts";
+
+BubbleChart.make("#accounts")
+  .dataset("Self-serve", [
+    { x: 12, y: 38, r: 6 },
+    { x: 18, y: 51, r: 10 },
+  ])
+  .dataset("Sales-led", [
+    { x: 16, y: 58, r: 12 },
+    { x: 24, y: 72, r: 16 },
+  ])
+  .colors(["#2563eb", "#f59e0b"])
+  .render();
+```
+
+The radius must be finite and non-negative. Keep the range of radii modest so
+large bubbles do not hide smaller ones.
+
+## Point visibility
+
+Use `dots(false)` to hide bubble marks while retaining the scale and any
+annotations:
+
+```js
+import { BubbleChart } from "@orchidsoftware/charts";
+
+BubbleChart.make("#accounts").dataset(bubbles).dots(false).render();
+```
+
+## Dataset appearance
+
+A bubble dataset callback supports `color()`, `opacity()`, and
+`formatValue()`:
+
+```js
+import { BubbleChart } from "@orchidsoftware/charts";
+
+BubbleChart.make("#accounts")
+  .dataset("Accounts", bubbles, (dataset) => {
+    dataset.color("#2563eb").opacity(0.75);
+  })
+  .render();
+```
+
+Bubble charts also support the shared [cartesian presentation, formatting, and
+annotation methods](./customization.md).

package/docs/chart-types.md

@@ -0,0 +1,35 @@
+# Chart types
+
+Charts2 includes twelve chart types for common product questions. Choose the
+question you need to answer, then open the corresponding guide.
+
+## Change and comparison
+
+- [Line charts](./line.md) show change across an ordered sequence.
+- [Bar charts](./bar.md) compare categories, groups, and totals.
+- [Mixed charts](./mixed.md) place lines, bars, and scatter points on one scale.
+
+## Relationships
+
+- [Scatter charts](./scatter.md) compare two measurements.
+- [Bubble charts](./bubble.md) add a third measurement through radius.
+
+## Composition and profiles
+
+- [Pie charts](./pie.md) divide a whole into a few slices.
+- [Donut charts](./donut.md) show the same relationship as a ring.
+- [Percentage charts](./percentage.md) show composition in a compact strip.
+- [Radar charts](./radar.md) compare profiles across a shared scale.
+- [Polar area charts](./polar-area.md) compare magnitude with equal angles.
+
+## Activity and planning
+
+- [Calendar heatmaps](./heatmap.md) show daily activity and recurring patterns.
+- [Timesheet charts](./timesheet.md) place tasks and phases on a timeline.
+
+If two types seem suitable, prefer the one that communicates the answer with
+fewer visual concepts. A bar chart is usually easier to compare than a pie, and
+a line is usually clearer than a radar for change over time.
+
+Once you have chosen a type, use [Customization](./customization.md) for shared
+colors, formatting, tooltips, and annotations.

package/docs/customization.md

@@ -0,0 +1,178 @@
+# Customization
+
+Charts2 starts with product-ready defaults. Add only the methods that change
+the result you need.
+
+## Set the size
+
+Charts are responsive by default: they follow the width of their host element.
+Set a fixed drawing width only when the chart should not follow its container.
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue").dataset([42, 48, 57]).height(280).render();
+```
+
+- `height(pixels)` sets the chart height.
+- `width(pixels)` sets an explicit width.
+
+For a wide calendar heatmap on a small screen, let its host scroll:
+
+```html
+<div class="charts2-scrollable-heatmap">
+  <div id="activity"></div>
+</div>
+```
+
+## Choose chart colors
+
+Pass colors in the order they should be used. The palette repeats when there
+are more series or categories than colors.
+
+```js
+import { BarChart } from "@orchidsoftware/charts";
+
+BarChart.make("#orders")
+  .labels(["Web", "Retail", "Partners"])
+  .dataset("Orders", [124, 86, 43])
+  .colors(["#2563eb", "#8b5cf6", "#f59e0b"])
+  .render();
+```
+
+For series charts, colors are assigned by dataset. For pie, donut, percentage,
+and polar area charts, colors are assigned by category. A heatmap uses the
+palette as a low-to-high intensity scale.
+
+To change one dataset without changing the chart palette, pass a color directly:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .dataset("Actual", [42, 48, 57], "#2563eb")
+  .dataset("Plan", [45, 50, 55], "#94a3b8")
+  .render();
+```
+
+## Match the surrounding interface
+
+Charts2 uses CSS variables for shared surface colors. Override them on a page,
+card, or chart host:
+
+```css
+.analytics-card {
+  --charts-label-color: #e2e8f0;
+  --charts-secondary-label-color: #94a3b8;
+  --charts-axis-line-color: #334155;
+  --charts-tooltip-bg: rgb(15 23 42 / 96%);
+  --charts-tooltip-value: #f8fafc;
+  --charts-focus-ring: #38bdf8;
+  --charts-mark-separator: #0f172a;
+  --charts-point-fill: #0f172a;
+}
+```
+
+This is usually enough for a dark card or branded product surface. Keep data
+colors in `colors()` so they remain explicit and readable.
+
+## Change the presentation
+
+Common chart-wide methods describe the result directly:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+const compactTrend = LineChart.make("#trend")
+  .dataset([12, 18, 16, 25])
+  .height(90)
+  .smooth()
+  .gradient()
+  .frameless()
+  .render();
+```
+
+- Line: `smooth()`, `gradient()`, `area()`, `dots(false)`, `strokeWidth(value)`.
+- Bar: `horizontal()`, `stacked()`, `radius(value)`.
+- Cartesian: `axes(false)`, `grid(false)`, `valueLabels(false)`, `frameless()`.
+- Pie and donut: `maxSlices(value)`, `startAngle(value)`, `padAngle(value)`,
+  `cornerRadius(value)`.
+- Percentage: `maxSlices(value)`, `radius(value)`.
+- Polar area: `padAngle(value)`, `cornerRadius(value)`.
+- Radar: `strokeWidth(value)`.
+- Heatmap: `countLabel(value)`, `radius(value)`.
+- Timesheet: `axes(false)`, `grid(false)`, `valueLabels(false)`, `radius(value)`.
+
+Boolean conventions use the short form when enabled. Their optional boolean
+argument is useful for conditional code, such as `.stacked(isCompact)`.
+
+## Format labels and values
+
+Use chart-level formatters when the same rule should apply everywhere:
+
+```js
+import { BarChart } from "@orchidsoftware/charts";
+
+BarChart.make("#revenue")
+  .labels(["Starter", "Team", "Business"])
+  .dataset("MRR", [12400, 28600, 53100])
+  .formatValue((value) => `$${Math.round(value / 1000)}k`)
+  .formatLabel((label) => label.toUpperCase())
+  .render();
+```
+
+Customize only the tooltip when the axis should stay compact:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .dataset("Revenue", [12400, 28600, 53100])
+  .tooltip((tooltip) => {
+    tooltip.formatValue((value) => `$${value.toLocaleString()}`);
+  })
+  .render();
+```
+
+Pass `false` to `tooltip()` or `legend()` when that layer does not help the
+reader.
+
+## Add context to a cartesian chart
+
+Markers show a target or threshold. Regions show a meaningful range.
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#response-time")
+  .labels(["Mon", "Tue", "Wed", "Thu", "Fri"])
+  .dataset("p95", [180, 210, 195, 240, 205])
+  .marker("Target", 200, "#dc2626")
+  .region("Healthy", [0, 200], "#16a34a")
+  .render();
+```
+
+Line, bar, scatter, bubble, and mixed charts support markers and regions.
+
+## Customize one dataset
+
+Use a dataset callback only when one series needs different treatment:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .dataset("Actual", [42, 48, 57], (dataset) => {
+    dataset.color("#2563eb").strokeWidth(3).dots(true);
+  })
+  .dataset("Plan", [45, 50, 55], (dataset) => {
+    dataset.color("#94a3b8").opacity(0.7).dots(false);
+  })
+  .render();
+```
+
+Start with chart-wide methods. Reach for a callback only when a single dataset,
+axis, marker, region, or tooltip must differ.
+
+Continue with [Updates and interaction](./updates-and-interaction.md) to connect
+the finished chart to your application.

package/docs/donut.md

@@ -0,0 +1,55 @@
+# Donut charts
+
+## Introduction
+
+Donut charts show the same part-to-whole relationship as pie charts while
+leaving the center open. Use one when the ring shape fits the surrounding
+interface better than a solid circle.
+
+## Creating a donut chart
+
+```js
+import { DonutChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = DonutChart.make("#plans")
+  .labels(["Starter", "Team", "Business"])
+  .dataset([58, 31, 11])
+  .colors(["#2563eb", "#8b5cf6", "#f59e0b"])
+  .render();
+```
+
+Donut values must be non-negative and at least one value must be positive.
+
+## Limiting slices
+
+`maxSlices()` keeps the largest categories and combines the remainder:
+
+```js
+import { DonutChart } from "@orchidsoftware/charts";
+
+DonutChart.make("#sources").labels(sources).dataset(visits).maxSlices(5).render();
+```
+
+## Starting angle
+
+Use `startAngle()` to rotate the first slice to a deliberate position:
+
+```js
+import { DonutChart } from "@orchidsoftware/charts";
+
+DonutChart.make("#plans").labels(plans).dataset(accounts).startAngle(-90).render();
+```
+
+## Slice spacing and corners
+
+`padAngle()` adds spacing between slices. `cornerRadius()` rounds their corners:
+
+```js
+import { DonutChart } from "@orchidsoftware/charts";
+
+DonutChart.make("#plans").labels(plans).dataset(accounts).padAngle(2).cornerRadius(4).render();
+```
+
+Donut charts also support `formatLabel()`, `formatValue()`, `legend(false)`, and
+the shared [colors, dimensions, tooltip, and selection methods](./customization.md).

package/docs/exporting.md

@@ -0,0 +1,87 @@
+# Exporting SVG
+
+## Introduction
+
+Every Charts2 chart is rendered as SVG. The runtime API can return that SVG as
+a string or download it as a file. Export always uses the chart's current data
+and presentation.
+
+## Getting the SVG source
+
+The `toSvg()` method returns the complete SVG markup as a string:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = LineChart.make("#revenue")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Revenue", [42, 48, 57, 63])
+  .render();
+
+const source = chart.toSvg();
+```
+
+Charts2 copies the computed presentation styles into the exported SVG. This
+makes the result self-contained when it is opened outside the current page.
+
+You may send the string to your own storage or download service:
+
+```js
+await fetch("/reports/revenue.svg", {
+  method: "PUT",
+  headers: { "Content-Type": "image/svg+xml" },
+  body: chart.toSvg(),
+});
+```
+
+## Downloading an SVG file
+
+The `download()` method starts a browser download:
+
+```js
+import { BarChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = BarChart.make("#orders")
+  .labels(["Web", "Retail", "Partners"])
+  .dataset("Orders", [124, 86, 43])
+  .render();
+
+chart.download("orders-by-channel");
+```
+
+Charts2 adds the `.svg` extension when it is not supplied. If the filename is
+omitted, the chart title is used; a chart without a title downloads as
+`Chart.svg`.
+
+The filename must not be empty or contain `/` or `\\` path separators.
+
+## Exporting updated data
+
+Export reflects the latest successful update:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = LineChart.make("#revenue")
+  .labels(["Jan", "Feb", "Mar"])
+  .dataset("Revenue", [42, 48, 57])
+  .render();
+
+chart.update({
+  labels: ["Feb", "Mar", "Apr"],
+  datasets: [{ name: "Revenue", values: [48, 57, 63] }],
+});
+
+chart.download("latest-revenue");
+```
+
+An invalid update leaves the previous chart unchanged, so a later export still
+contains the last successfully rendered data.
+
+## Exporting after cleanup
+
+Do not call `toSvg()` or `download()` after `destroy()`. Destroying a chart
+releases its SVG and browser resources, and the chart can no longer be used.

package/docs/frameworks.md

@@ -0,0 +1,203 @@
+# React, Vue, and Hotwire
+
+## Introduction
+
+Charts2 does not require a framework wrapper. A chart owns one host element and
+returns a small lifecycle that maps directly to component mounting, updates,
+and cleanup.
+
+## React
+
+Create the chart after the host element mounts. Keep the chart in a ref so data
+changes can call `update()`, then destroy it from the effect cleanup:
+
+```jsx
+import { useEffect, useRef } from "react";
+import { LineChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+export function RevenueChart({ labels, values }) {
+  const host = useRef(null);
+  const chart = useRef(null);
+  const initialData = useRef({ labels, values });
+
+  useEffect(() => {
+    const initial = initialData.current;
+
+    chart.current = LineChart.make(host.current)
+      .labels(initial.labels)
+      .dataset("Revenue", initial.values)
+      .gradient()
+      .render();
+
+    return () => {
+      chart.current?.destroy();
+      chart.current = null;
+    };
+  }, []);
+
+  useEffect(() => {
+    chart.current?.update({
+      labels,
+      datasets: [{ name: "Revenue", values }],
+    });
+  }, [labels, values]);
+
+  return <div ref={host} />;
+}
+```
+
+The first effect owns the chart lifecycle. The second replaces its data without
+recreating the SVG or its event listeners.
+
+If presentation methods such as `gradient()` or `height()` depend on props,
+recreate the chart when those presentation props change. `update()` replaces
+data; it does not reconfigure the chart type or builder options.
+
+## Vue
+
+Mount the chart in `onMounted()`, watch the data that may change, and destroy
+the chart before the component unmounts:
+
+```vue
+<script setup>
+import { onBeforeUnmount, onMounted, ref, watch } from "vue";
+import { BarChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const props = defineProps({
+  labels: { type: Array, required: true },
+  values: { type: Array, required: true },
+});
+
+const host = ref(null);
+let chart;
+
+onMounted(() => {
+  chart = BarChart.make(host.value)
+    .labels(props.labels)
+    .dataset("Orders", props.values)
+    .horizontal()
+    .render();
+});
+
+watch(
+  () => [props.labels, props.values],
+  ([labels, values]) => {
+    chart?.update({
+      labels,
+      datasets: [{ name: "Orders", values }],
+    });
+  },
+);
+
+onBeforeUnmount(() => chart?.destroy());
+</script>
+
+<template>
+  <div ref="host" />
+</template>
+```
+
+## Hotwire and Stimulus
+
+Let a Stimulus controller own the chart element. Values keep server-rendered
+data in the HTML, value callbacks update a controller preserved by a Turbo
+morph, and `disconnect()` handles frame or page replacement.
+
+Import the Charts2 stylesheet once from your JavaScript entry point:
+
+```js
+// app/javascript/application.js
+import "@orchidsoftware/charts/style.css";
+```
+
+Put the chart data in Stimulus values. The `turbo:before-cache` action removes
+the generated SVG before Turbo takes its snapshot, so restoring the page never
+duplicates a cached chart:
+
+```html
+<div
+  class="analytics-chart"
+  data-controller="revenue-chart"
+  data-action="turbo:before-cache@document->revenue-chart#destroy"
+  data-revenue-chart-labels-value='["Jan", "Feb", "Mar", "Apr"]'
+  data-revenue-chart-values-value="[42, 48, 57, 63]"
+></div>
+```
+
+```js
+// app/javascript/controllers/revenue_chart_controller.js
+import { Controller } from "@hotwired/stimulus";
+import { LineChart } from "@orchidsoftware/charts";
+
+export default class extends Controller {
+  static values = {
+    labels: Array,
+    values: Array,
+  };
+
+  chart = null;
+  updateQueued = false;
+
+  connect() {
+    this.chart = LineChart.make(this.element)
+      .labels(this.labelsValue)
+      .dataset("Revenue", this.valuesValue)
+      .gradient()
+      .render();
+  }
+
+  disconnect() {
+    this.destroy();
+  }
+
+  labelsValueChanged() {
+    this.queueUpdate();
+  }
+
+  valuesValueChanged() {
+    this.queueUpdate();
+  }
+
+  destroy() {
+    this.chart?.destroy();
+    this.chart = null;
+  }
+
+  queueUpdate() {
+    if (!this.chart || this.updateQueued) return;
+
+    this.updateQueued = true;
+
+    queueMicrotask(() => {
+      this.updateQueued = false;
+      this.chart?.update({
+        labels: this.labelsValue,
+        datasets: [{ name: "Revenue", values: this.valuesValue }],
+      });
+    });
+  }
+}
+```
+
+The microtask combines adjacent label and value mutations into one update.
+When Turbo replaces the controller element, Stimulus destroys the old chart
+and `connect()` renders the new one; no Turbo-specific global listener is
+needed.
+
+## Resizing
+
+Do not calculate the component width for Charts2. Unless `width()` is set, the
+chart follows its host element and observes width changes automatically. Use
+ordinary CSS to size the host:
+
+```css
+.analytics-chart {
+  width: 100%;
+  min-width: 0;
+}
+```
+
+Continue with [Updates and interaction](./updates-and-interaction.md) for data,
+selection, point snapshots, and cleanup details.