@orchidsoftware/charts 0.0.1

package/docs/getting-started.md

@@ -0,0 +1,121 @@
+# Getting started
+
+This page takes you from an empty element to a responsive product chart.
+
+## Install Charts2
+
+Install the package with npm:
+
+```bash
+npm install @orchidsoftware/charts
+```
+
+Charts2 ships as an ES module. Import the chart you need and its stylesheet:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+```
+
+## Render your first chart
+
+Add a host element to your page:
+
+```html
+<div id="revenue"></div>
+```
+
+Create a line chart inside it:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const revenue = LineChart.make("#revenue")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Revenue", [42, 48, 57, 63])
+  .render();
+```
+
+Charts2 uses the width of the host element and redraws when that width changes.
+The default height, palette, axes, legend, labels, and tooltip are ready to use.
+
+## Understand the chain
+
+Every chart follows the same path:
+
+```text
+make(parent) → add data → render()
+```
+
+- `make(parent)` accepts a CSS selector or an `Element`.
+- Data methods describe the values to show. Most charts use `labels()` and
+  `dataset()`.
+- `render()` mounts the chart and returns its small runtime API.
+
+Methods before `render()` shape the whole chart:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+const revenue = LineChart.make("#revenue")
+  .title("Monthly revenue")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Revenue", [42, 48, 57, 63])
+  .colors(["#2563eb"])
+  .height(300)
+  .smooth()
+  .gradient()
+  .render();
+```
+
+## Add another series
+
+Call `dataset()` again. Names appear in the legend and tooltip.
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+const revenue = LineChart.make("#revenue")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Actual", [42, 48, 57, 63])
+  .dataset("Plan", [45, 50, 55, 65])
+  .colors(["#2563eb", "#94a3b8"])
+  .render();
+```
+
+Each dataset must contain one value for every label.
+
+## Use Charts2 without a build step
+
+For a plain HTML page, use an import map and load the stylesheet with a
+`<link>`. Pin an exact version in production.
+
+```html
+<div id="chart"></div>
+
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@orchidsoftware/charts@0.0.1/src/styles.css" />
+
+<script type="importmap">
+  {
+    "imports": {
+      "@orchidsoftware/charts": "https://cdn.jsdelivr.net/npm/@orchidsoftware/charts@0.0.1/dist/index.js"
+    }
+  }
+</script>
+
+<script type="module">
+  import { BarChart } from "@orchidsoftware/charts";
+
+  BarChart.make("#chart").labels(["Starter", "Team", "Business"]).dataset("Accounts", [84, 46, 21]).render();
+</script>
+```
+
+Native browsers load CSS through `<link>`; a JavaScript `import` cannot load the
+stylesheet without a bundler.
+
+## Where to go next
+
+- Pick a visualization in [Chart types](./chart-types.md).
+- Make it fit your interface in [Customization](./customization.md).
+- Connect it to changing data in [Updates and interaction](./updates-and-interaction.md).

package/docs/heatmap.md

@@ -0,0 +1,95 @@
+# Calendar heatmaps
+
+## Introduction
+
+Calendar heatmaps show activity day by day. Color intensity makes recurring
+patterns, quiet periods, and unusually active days easy to find.
+
+## Creating a calendar heatmap
+
+Point keys use the timezone-free `YYYY-MM-DD` form:
+
+```js
+import { HeatmapChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = HeatmapChart.make("#activity")
+  .points({
+    "2026-08-26": 3,
+    "2026-08-27": 7,
+    "2026-08-28": 4,
+    "2026-08-29": 9,
+  })
+  .render();
+```
+
+Point values must be finite numbers. Zero is valid and represents an inactive
+day.
+
+## Displaying a fixed range
+
+Without `range()`, Charts2 derives the calendar range from the first and last
+point. Use `range(start, end)` when the chart should also show inactive days
+outside that interval:
+
+```js
+import { HeatmapChart } from "@orchidsoftware/charts";
+
+HeatmapChart.make("#activity")
+  .range(new Date("2026-01-01T00:00:00Z"), new Date("2026-12-31T00:00:00Z"))
+  .points(activity)
+  .render();
+```
+
+## Naming the count
+
+`countLabel()` names the unit in the tooltip and accessible text:
+
+```js
+import { HeatmapChart } from "@orchidsoftware/charts";
+
+HeatmapChart.make("#activity").points(activity).countLabel("contributions").render();
+```
+
+## Color scale
+
+For a heatmap, `colors()` defines a low-to-high intensity scale. Unlike a
+series palette, the supplied colors are used once rather than cycled:
+
+```js
+import { HeatmapChart } from "@orchidsoftware/charts";
+
+HeatmapChart.make("#activity")
+  .points(activity)
+  .colors(["#eff6ff", "#bfdbfe", "#60a5fa", "#2563eb", "#1e3a8a"])
+  .render();
+```
+
+## Rounded day cells
+
+Use `radius()` to round each day cell in CSS pixels:
+
+```js
+import { HeatmapChart } from "@orchidsoftware/charts";
+
+HeatmapChart.make("#activity").points(activity).radius(2).render();
+```
+
+## Formatting the tooltip
+
+The heatmap tooltip provides `formatDate()` and `formatValue()`:
+
+```js
+import { HeatmapChart } from "@orchidsoftware/charts";
+
+HeatmapChart.make("#activity")
+  .points(activity)
+  .tooltip((tooltip) => {
+    tooltip.formatDate((date) => date.toLocaleDateString()).formatValue((value) => `${value} contributions`);
+  })
+  .render();
+```
+
+Calendar heatmaps also support the shared `title()`, `description()`,
+`ariaLabel()`, `width()`, `height()`, `colors()`, `tooltip()`, and `onSelect()`
+methods. See [Customization](./customization.md) for details.

package/docs/line.md

@@ -0,0 +1,148 @@
+# Line charts
+
+## Introduction
+
+Line charts are a good choice when the shape of change matters: revenue over
+time, response time by hour, or the growth of several plans. A line chart may
+contain one or more datasets, and every dataset must contain one value for each
+label.
+
+## Creating a line chart
+
+Import `LineChart`, choose a host element with `make()`, add the labels and
+values, and call `render()`:
+
+```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();
+```
+
+The value returned by `render()` is the mounted chart. You may use it to
+[update the data](./updates-and-interaction.md#replace-the-data), react to a
+selection, or export the SVG.
+
+## Multiple lines
+
+Call `dataset()` once for each line. Named datasets appear in the legend and
+tooltip:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Actual", [42, 48, 57, 63])
+  .dataset("Plan", [45, 50, 55, 65])
+  .colors(["#2563eb", "#94a3b8"])
+  .render();
+```
+
+## Smooth lines
+
+The `smooth()` method rounds the path between points. It applies to every line
+in the chart:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#signups")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Signups", [120, 156, 184, 231])
+  .smooth()
+  .render();
+```
+
+You may pass a boolean when the choice is conditional:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#signups").dataset(values).smooth(shouldSmooth).render();
+```
+
+## Gradient and area fills
+
+The `gradient()` method fills the area beneath every visible line with a
+fading version of its color:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .dataset("Revenue", [42, 48, 57, 63])
+  .gradient()
+  .render();
+```
+
+To control the fade, pass the starting and ending opacity:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .dataset([42, 48, 57, 63])
+  .gradient({ fromOpacity: 0.35, toOpacity: 0.02 })
+  .render();
+```
+
+Use `area()` for a solid area fill. Use `line(false)` when the filled shape
+should appear without its line:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#usage").dataset([18, 24, 31, 39]).area().line(false).render();
+```
+
+## Points and stroke
+
+Use `dots(false)` to hide points, `dotSize()` to resize them, and
+`strokeWidth()` to change the line width:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#latency").dataset([180, 210, 195, 205]).dots(false).dotSize(5).strokeWidth(3).render();
+```
+
+## Compact line charts
+
+`frameless()` hides the axes, grid, direct values, legend, tooltip, and points
+unless you explicitly enable one of them. This is useful for a chart embedded
+inside a small metric card:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue-trend").dataset([42, 48, 57, 63]).height(90).gradient().frameless().render();
+```
+
+## Customizing one line
+
+Chart-level methods are the usual choice. When one line needs different
+styling, configure only that dataset:
+
+```js
+import { LineChart } from "@orchidsoftware/charts";
+
+LineChart.make("#revenue")
+  .dataset("Actual", [42, 48, 57], (line) => {
+    line.color("#2563eb").smooth().gradient().strokeWidth(3);
+  })
+  .dataset("Plan", [45, 50, 55], (line) => {
+    line.color("#94a3b8").dots(false).opacity(0.7);
+  })
+  .render();
+```
+
+A line dataset supports `color()`, `opacity()`, `formatValue()`, `smooth()`,
+`gradient()`, `dots()`, `dotSize()`, `line()`, `area()`, and `strokeWidth()`.
+
+Line charts also support the shared [cartesian presentation, formatting, and
+annotation methods](./customization.md).

package/docs/mixed.md

@@ -0,0 +1,114 @@
+# Mixed charts
+
+## Introduction
+
+Mixed charts place line, bar, and scatter datasets on the same cartesian scale.
+They are useful for comparing an actual value with a plan, or showing events
+alongside a trend.
+
+## Creating a mixed chart
+
+```js
+import { MixedChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = MixedChart.make("#plan")
+  .labels(["Jan", "Feb", "Mar", "Apr"])
+  .bar("Actual", [42, 48, 57, 63])
+  .line("Plan", [45, 50, 55, 65])
+  .render();
+```
+
+Unlike other series charts, mixed charts use a method named after the desired
+dataset type.
+
+## Line datasets
+
+Use `line(name, values, colorOrCallback?)` to add a line:
+
+```js
+import { MixedChart } from "@orchidsoftware/charts";
+
+MixedChart.make("#plan")
+  .labels(["Jan", "Feb", "Mar"])
+  .line("Plan", [45, 50, 55], (line) => {
+    line.color("#2563eb").smooth().dots(false).strokeWidth(3);
+  })
+  .render();
+```
+
+The callback supports every line-dataset method: `color()`, `opacity()`,
+`formatValue()`, `smooth()`, `gradient()`, `dots()`, `dotSize()`, `line()`,
+`area()`, and `strokeWidth()`.
+
+## Bar datasets
+
+Use `bar(name, values, colorOrCallback?)` to add bars:
+
+```js
+import { MixedChart } from "@orchidsoftware/charts";
+
+MixedChart.make("#plan")
+  .labels(["Jan", "Feb", "Mar"])
+  .bar("Actual", [42, 48, 57], (bars) => {
+    bars.color("#8b5cf6").radius(5);
+  })
+  .render();
+```
+
+The callback supports `color()`, `opacity()`, `formatValue()`, and `radius()`.
+
+## Scatter datasets
+
+Use `scatter(name, values, colorOrCallback?)` to add individual observations:
+
+```js
+import { MixedChart } from "@orchidsoftware/charts";
+
+MixedChart.make("#plan")
+  .scatter("Releases", [
+    { x: 0, y: 42 },
+    { x: 2, y: 57 },
+  ])
+  .render();
+```
+
+Scatter values may be `{ x, y }` points or numbers. The callback supports
+`color()`, `opacity()`, and `formatValue()`.
+
+## Gradient fills
+
+Call `gradient()` on the chart to add a fading fill to every line dataset:
+
+```js
+import { MixedChart } from "@orchidsoftware/charts";
+
+MixedChart.make("#plan")
+  .labels(["Jan", "Feb", "Mar"])
+  .bar("Actual", [42, 48, 57])
+  .line("Plan", [45, 50, 55])
+  .gradient({ fromOpacity: 0.3, toOpacity: 0.02 })
+  .render();
+```
+
+Use a line callback when only one line should have a gradient.
+
+## Advanced dataset input
+
+The named methods are the clearest way to add mixed data. When your data is
+already stored as objects, `dataset()` also accepts an explicit `chartType`:
+
+```js
+import { MixedChart } from "@orchidsoftware/charts";
+
+MixedChart.make("#plan")
+  .dataset({ chartType: "bar", name: "Actual", values: [42, 48, 57] })
+  .dataset({ chartType: "line", name: "Plan", values: [45, 50, 55] })
+  .render();
+```
+
+The `chartType` must be `"line"`, `"bar"`, or `"scatter"`. Its value also
+determines which methods are available in an optional dataset callback.
+
+Mixed charts also support the shared [cartesian presentation, formatting, and
+annotation methods](./customization.md).

package/docs/percentage.md

@@ -0,0 +1,48 @@
+# Percentage charts
+
+## Introduction
+
+Percentage charts show composition as a compact horizontal strip. They are a
+good fit for storage, plan distribution, progress allocation, and other places
+where a full pie or donut would use too much space.
+
+## Creating a percentage chart
+
+```js
+import { PercentageChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = PercentageChart.make("#storage")
+  .labels(["Used", "Available"])
+  .dataset([68, 32])
+  .colors(["#2563eb", "#e2e8f0"])
+  .render();
+```
+
+Values must be non-negative and at least one value must be positive. Charts2
+calculates each category's share from the supplied values; they do not need to
+sum to 100.
+
+## Limiting segments
+
+Use `maxSlices()` to keep the largest categories and combine the remainder:
+
+```js
+import { PercentageChart } from "@orchidsoftware/charts";
+
+PercentageChart.make("#traffic").labels(sources).dataset(visits).maxSlices(5).render();
+```
+
+## Rounded segments
+
+The `radius()` method rounds segment corners in CSS pixels:
+
+```js
+import { PercentageChart } from "@orchidsoftware/charts";
+
+PercentageChart.make("#storage").labels(["Used", "Available"]).dataset([68, 32]).radius(6).render();
+```
+
+Percentage charts also support `formatLabel()`, `formatValue()`,
+`legend(false)`, and the shared [colors, dimensions, tooltip, and selection
+methods](./customization.md).

package/docs/pie.md

@@ -0,0 +1,58 @@
+# Pie charts
+
+## Introduction
+
+Pie charts show how a whole is divided into a small number of categories. They
+work best when the differences between slices are clear and precise comparison
+is not required.
+
+## Creating a pie chart
+
+```js
+import { PieChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = PieChart.make("#plans")
+  .labels(["Starter", "Team", "Business"])
+  .dataset([58, 31, 11])
+  .colors(["#2563eb", "#8b5cf6", "#f59e0b"])
+  .render();
+```
+
+Pie values must be non-negative and at least one value must be positive.
+
+## Limiting slices
+
+Use `maxSlices()` when incoming data may contain more categories than the chart
+can communicate clearly. Charts2 keeps the largest slices and combines the
+remainder:
+
+```js
+import { PieChart } from "@orchidsoftware/charts";
+
+PieChart.make("#sources").labels(sources).dataset(visits).maxSlices(5).render();
+```
+
+## Starting angle
+
+`startAngle()` rotates the chart by the given number of degrees:
+
+```js
+import { PieChart } from "@orchidsoftware/charts";
+
+PieChart.make("#plans").labels(plans).dataset(accounts).startAngle(-90).render();
+```
+
+## Slice spacing and corners
+
+Use `padAngle()` to place space between slices and `cornerRadius()` to soften
+their corners:
+
+```js
+import { PieChart } from "@orchidsoftware/charts";
+
+PieChart.make("#plans").labels(plans).dataset(accounts).padAngle(2).cornerRadius(4).render();
+```
+
+Pie charts also support `formatLabel()`, `formatValue()`, `legend(false)`, and
+the shared [colors, dimensions, tooltip, and selection methods](./customization.md).

package/docs/polar-area.md

@@ -0,0 +1,46 @@
+# Polar area charts
+
+## Introduction
+
+Polar area charts give every category the same angle and encode its value with
+radius. Use one when the circular form is useful and magnitude—not a share of a
+fixed whole—is the main comparison.
+
+## Creating a polar area chart
+
+```js
+import { PolarAreaChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = PolarAreaChart.make("#sources")
+  .labels(["Search", "Direct", "Partners", "Social"])
+  .dataset([48, 31, 22, 15])
+  .colors(["#2563eb", "#8b5cf6", "#f59e0b", "#16a34a"])
+  .render();
+```
+
+Values must be non-negative and at least one value must be positive.
+
+## Segment spacing
+
+`padAngle()` adds space between segments, measured in degrees:
+
+```js
+import { PolarAreaChart } from "@orchidsoftware/charts";
+
+PolarAreaChart.make("#sources").labels(sources).dataset(visits).padAngle(3).render();
+```
+
+## Rounded segments
+
+Use `cornerRadius()` to round segment corners in CSS pixels:
+
+```js
+import { PolarAreaChart } from "@orchidsoftware/charts";
+
+PolarAreaChart.make("#sources").labels(sources).dataset(visits).padAngle(3).cornerRadius(4).render();
+```
+
+Polar area charts also support `formatLabel()`, `formatValue()`,
+`legend(false)`, and the shared [colors, dimensions, tooltip, and selection
+methods](./customization.md).

package/docs/radar.md

@@ -0,0 +1,49 @@
+# Radar charts
+
+## Introduction
+
+Radar charts compare profiles across several measures that share a common
+scale. They work best with a small number of measures and datasets.
+
+## Creating a radar chart
+
+```js
+import { RadarChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = RadarChart.make("#quality")
+  .labels(["Speed", "Reliability", "Ease", "Support", "Value"])
+  .dataset("Current", [78, 91, 86, 74, 82])
+  .render();
+```
+
+Radar values must be non-negative. Every dataset must contain one value for
+each label.
+
+## Comparing profiles
+
+Add another named dataset to compare profiles on the same scale:
+
+```js
+import { RadarChart } from "@orchidsoftware/charts";
+
+RadarChart.make("#quality")
+  .labels(["Speed", "Reliability", "Ease", "Support", "Value"])
+  .dataset("Current", [78, 91, 86, 74, 82])
+  .dataset("Previous", [69, 84, 80, 70, 76])
+  .colors(["#2563eb", "#94a3b8"])
+  .render();
+```
+
+## Stroke width
+
+Use `strokeWidth()` to change the outline of every profile:
+
+```js
+import { RadarChart } from "@orchidsoftware/charts";
+
+RadarChart.make("#quality").labels(metrics).dataset(scores).strokeWidth(3).render();
+```
+
+Radar charts also support `formatLabel()`, `formatValue()`, `legend(false)`,
+and the shared [colors, dimensions, tooltip, and selection methods](./customization.md).