@orchidsoftware/charts 0.0.1

package/docs/readme.md

@@ -0,0 +1,37 @@
+# Charts2 documentation
+
+Charts2 helps you turn product data into responsive SVG charts with a small,
+consistent JavaScript API. It is part of [Orchid Software](https://orchid.software).
+
+If this is your first chart, begin with [Getting started](./getting-started.md).
+You will install the package and render a useful line chart in a few minutes.
+
+## Learn by result
+
+- [Getting started](./getting-started.md) — render a chart, add another series,
+  and understand the three-step API.
+- [Customization](./customization.md) — change colors, size, layout, labels,
+  tooltips, and annotations.
+- [Updates and interaction](./updates-and-interaction.md) — update data, react
+  to selections, inspect points, and clean up.
+- [Exporting SVG](./exporting.md) — serialize or download the current chart.
+- [React, Vue, and Hotwire](./frameworks.md) — mount, update, and destroy charts with component lifecycles.
+- [API reference](./api-reference.md) — look up chart definitions and public methods.
+
+## Chart types
+
+- [Line](./line.md)
+- [Bar](./bar.md)
+- [Scatter](./scatter.md)
+- [Mixed](./mixed.md)
+- [Bubble](./bubble.md)
+- [Pie](./pie.md)
+- [Donut](./donut.md)
+- [Percentage](./percentage.md)
+- [Radar](./radar.md)
+- [Polar area](./polar-area.md)
+- [Calendar heatmap](./heatmap.md)
+- [Timesheet](./timesheet.md)
+
+Choose a chart, point it at an element, add data, and render. Everything between
+the data and `render()` is optional.

package/docs/scatter.md

@@ -0,0 +1,83 @@
+# Scatter charts
+
+## Introduction
+
+Scatter charts show whether two measurements move together. Each point has an
+`x` and `y` coordinate; multiple named datasets may be compared in one chart.
+
+## Creating a scatter chart
+
+```js
+import { ScatterChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = ScatterChart.make("#results")
+  .dataset("Teams", [
+    { x: 12, y: 38 },
+    { x: 18, y: 51 },
+    { x: 25, y: 63 },
+  ])
+  .render();
+```
+
+The value returned by `render()` is the mounted chart and may be updated,
+selected, or exported.
+
+## Point data
+
+The clearest scatter input uses `{ x, y }` objects:
+
+```js
+import { ScatterChart } from "@orchidsoftware/charts";
+
+ScatterChart.make("#results")
+  .dataset("Current", [
+    { x: 4, y: 18 },
+    { x: 8, y: 31 },
+    { x: 12, y: 46 },
+  ])
+  .dataset("Previous", [
+    { x: 4, y: 15 },
+    { x: 8, y: 25 },
+    { x: 12, y: 38 },
+  ])
+  .render();
+```
+
+A plain number is also accepted. In that form, its array index becomes the
+`x` coordinate:
+
+```js
+import { ScatterChart } from "@orchidsoftware/charts";
+
+ScatterChart.make("#results").dataset([18, 31, 46]).render();
+```
+
+## Point visibility
+
+Use `dots(false)` to hide scatter marks while keeping the chart's scale and
+annotations:
+
+```js
+import { ScatterChart } from "@orchidsoftware/charts";
+
+ScatterChart.make("#results").dataset(points).dots(false).render();
+```
+
+## Dataset appearance
+
+A scatter dataset callback supports `color()`, `opacity()`, and
+`formatValue()`:
+
+```js
+import { ScatterChart } from "@orchidsoftware/charts";
+
+ScatterChart.make("#results")
+  .dataset("Teams", points, (dataset) => {
+    dataset.color("#2563eb").opacity(0.75);
+  })
+  .render();
+```
+
+Scatter charts also support the shared [cartesian presentation, formatting,
+and annotation methods](./customization.md).

package/docs/timesheet.md

@@ -0,0 +1,125 @@
+# Timesheet charts
+
+## Introduction
+
+Timesheet charts place tasks across a time axis. They are suitable for release
+plans, phases, bookings, schedules, and other product views where both start
+and end dates matter.
+
+## Creating a timesheet chart
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+import "@orchidsoftware/charts/style.css";
+
+const chart = TimesheetChart.make("#release-plan")
+  .task("Design", "2026-09-01", "2026-09-03")
+  .task("Build", "2026-09-03", "2026-09-08")
+  .render();
+```
+
+Dates may be `Date` objects, millisecond timestamps, `YYYY-MM-DD` strings, or
+date-time strings with an explicit timezone.
+
+## Task details
+
+Pass an object when a task needs a group or color:
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+
+TimesheetChart.make("#release-plan")
+  .task({
+    label: "Design",
+    start: "2026-09-01",
+    end: "2026-09-03",
+    group: "Product",
+    color: "#8b5cf6",
+  })
+  .task({
+    label: "Build",
+    start: "2026-09-03",
+    end: "2026-09-08",
+    group: "Engineering",
+    color: "#2563eb",
+  })
+  .render();
+```
+
+## Displaying a fixed range
+
+Without `range()`, Charts2 derives the timeline from the earliest start and
+latest end. Use `range()` when the view should include additional time:
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+
+TimesheetChart.make("#release-plan")
+  .range("2026-09-01", "2026-09-12")
+  .task("Design", "2026-09-01", "2026-09-03")
+  .task("Build", "2026-09-03", "2026-09-08")
+  .render();
+```
+
+## Axes, grid, and labels
+
+Use `axes(false)`, `grid(false)`, and `valueLabels(false)` to remove individual
+presentation layers:
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+
+TimesheetChart.make("#release-plan")
+  .task("Design", "2026-09-01", "2026-09-03")
+  .axes(false)
+  .grid(false)
+  .valueLabels(false)
+  .render();
+```
+
+## Date and duration formatting
+
+`formatDate()` formats dates in chart content, `formatDuration()` formats task
+durations, and `formatTick()` formats the time axis:
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+
+TimesheetChart.make("#release-plan")
+  .task("Design", "2026-09-01", "2026-09-03")
+  .formatDate((date) => date.toLocaleDateString())
+  .formatDuration((milliseconds) => `${milliseconds / 86_400_000} days`)
+  .formatTick((date) => date.toLocaleDateString(undefined, { month: "short", day: "numeric" }))
+  .render();
+```
+
+## Rounded task bars
+
+The `radius()` method rounds task bars in CSS pixels:
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+
+TimesheetChart.make("#release-plan").task("Design", "2026-09-01", "2026-09-03").radius(5).render();
+```
+
+## Formatting the tooltip
+
+The timesheet tooltip provides its own date and duration formatters:
+
+```js
+import { TimesheetChart } from "@orchidsoftware/charts";
+
+TimesheetChart.make("#release-plan")
+  .task("Design", "2026-09-01", "2026-09-03")
+  .tooltip((tooltip) => {
+    tooltip
+      .formatDate((date) => date.toLocaleDateString())
+      .formatDuration((milliseconds) => `${milliseconds / 86_400_000} days`);
+  })
+  .render();
+```
+
+Timesheet charts also support the shared `title()`, `description()`,
+`ariaLabel()`, `width()`, `height()`, `colors()`, `tooltip()`, and `onSelect()`
+methods. See [Customization](./customization.md) for details.

package/docs/updates-and-interaction.md

@@ -0,0 +1,124 @@
+# Updates and interaction
+
+`render()` returns the mounted chart. Keep that value when data can change or
+when your interface needs to react to the chart.
+
+```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();
+```
+
+## Replace the data
+
+`update(data)` replaces the complete data scene and redraws the existing chart.
+
+```js
+chart.update({
+  labels: ["Feb", "Mar", "Apr"],
+  datasets: [{ name: "Revenue", values: [48, 57, 63] }],
+});
+```
+
+Send all datasets that should remain visible. The update is validated before
+the current chart changes, so invalid data does not leave a half-updated view.
+
+Series charts use this shape:
+
+```js
+chart.update({
+  labels: ["Jan", "Feb", "Mar"],
+  datasets: [
+    { name: "Actual", values: [42, 48, 57], color: "#2563eb" },
+    { name: "Plan", values: [45, 50, 55], color: "#94a3b8" },
+  ],
+});
+```
+
+Heatmaps and timesheets use their own domain data:
+
+```js
+activity.update({
+  points: {
+    "2026-08-27": 7,
+    "2026-08-28": 4,
+    "2026-08-29": 9,
+  },
+});
+
+plan.update({
+  tasks: [
+    { label: "Design", start: "2026-09-01", end: "2026-09-03" },
+    { label: "Build", start: "2026-09-03", end: "2026-09-08" },
+  ],
+});
+```
+
+## React to a selection
+
+Use `onSelect()` to connect a mark to the rest of your interface.
+
+```js
+import { BarChart } from "@orchidsoftware/charts";
+
+BarChart.make("#orders")
+  .labels(["Web", "Retail", "Partners"])
+  .dataset("Orders", [124, 86, 43])
+  .onSelect((selection) => {
+    if (!selection) {
+      closeDetails();
+      return;
+    }
+
+    openDetails({
+      channel: selection.label,
+      orders: selection.value,
+    });
+  })
+  .render();
+```
+
+The callback receives the selected label, value, dataset, and coordinates for
+series charts. Composition charts add the selected color; heatmaps add a date
+and key; timesheets add the task range and duration. It receives `undefined`
+when the selection is cleared.
+
+Pointer, touch, and keyboard input share the same selection model. Arrow keys
+move between values, Enter or Space keeps a selection open, and Escape clears
+it.
+
+## Read a normalized point
+
+`point(index)` returns an immutable snapshot without exposing internal SVG
+nodes. Without an index it returns the active keyboard or pointer point, or the
+first point when nothing is active.
+
+```js
+const first = chart.point();
+const third = chart.point(2);
+```
+
+It returns `undefined` when the index is outside the chart data.
+
+## Export the chart
+
+Every mounted chart can return its current SVG source or download an SVG file.
+See [Exporting SVG](./exporting.md) for both workflows.
+
+## Clean up
+
+Destroy a chart when its view is permanently removed:
+
+```js
+chart.destroy();
+```
+
+This removes the owned SVG, tooltip, observers, and event listeners. Calling
+`destroy()` again is safe. A destroyed chart cannot be updated or exported.
+
+For method signatures and chart-specific data shapes, use the
+[API reference](./api-reference.md).

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@orchidsoftware/charts",
+  "version": "0.0.1",
+  "description": "Clear, responsive SVG charts for product interfaces with one small JavaScript API",
+  "type": "module",
+  "packageManager": "npm@11.16.0",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./src/styles.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./src/index.d.ts",
+  "style": "./src/styles.css",
+  "homepage": "https://charts.orchid.software",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orchidsoftware/charts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/orchidsoftware/charts/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "src/index.d.ts",
+    "src/styles.css",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "dev": "vite --open /demo/",
+    "build": "vite build && node scripts/WriteBuildSize.mjs",
+    "build:demo": "vite build --config ViteDemoConfig.js",
+    "preview": "vite preview",
+    "format": "prettier --write \"**/*.{js,mjs,cjs,ts,css,html,md,json,yml,yaml}\" --ignore-unknown",
+    "format:check": "prettier --check \"**/*.{js,mjs,cjs,ts,css,html,md,json,yml,yaml}\" --ignore-unknown",
+    "lint": "npm run lint:js && npm run lint:css",
+    "lint:fix": "npm run lint:js:fix && npm run lint:css:fix",
+    "lint:js": "eslint . --max-warnings 0",
+    "lint:js:fix": "eslint . --fix --max-warnings 0",
+    "lint:css": "stylelint \"{src,demo}/**/*.css\" --max-warnings 0",
+    "lint:css:fix": "stylelint \"{src,demo}/**/*.css\" --fix --max-warnings 0",
+    "typecheck": "tsc -p tsconfig.types.json --module ESNext --moduleResolution Bundler && tsc -p tsconfig.types.json --module Node16 --moduleResolution Node16 && tsc -p tsconfig.types.json",
+    "test": "vitest run",
+    "test:size": "npm run build",
+    "test:lab": "vitest run test/Lab.test.js",
+    "test:watch": "vitest",
+    "test:visual": "vitest run test/VisualRegression.test.js",
+    "test:visual:update": "vitest run test/VisualRegression.test.js --update",
+    "test:performance": "vitest run test/Performance.test.js",
+    "test:compatibility": "CHARTS2_COMPATIBILITY=1 vitest run test/Compatibility.test.js",
+    "test:no-build": "vite build && node scripts/TestNoBuild.mjs",
+    "test:ssr": "vite build && node --input-type=module --eval \"await import('./dist/index.js')\"",
+    "coverage": "vitest run --coverage --exclude test/Performance.test.js",
+    "audit": "npm audit --audit-level=high",
+    "pack:check": "npm pack --dry-run --ignore-scripts",
+    "check": "npm run format:check && npm run lint && npm run typecheck && npm run coverage && npm run test:performance && npm run test:compatibility && npm run test:no-build && npm run test:ssr && npm run build",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run check"
+  },
+  "engines": {
+    "node": ">=22.12"
+  },
+  "overrides": {
+    "eslint-plugin-sonarjs": {
+      "typescript": "5.9.3"
+    }
+  },
+  "keywords": [
+    "accessible",
+    "calendar-heatmap",
+    "charting-library",
+    "charts",
+    "dashboard",
+    "data-visualization",
+    "dependency-free",
+    "bubble-chart",
+    "javascript",
+    "product-analytics",
+    "radar-chart",
+    "responsive-charts",
+    "scatter-plot",
+    "svg",
+    "svg-charts",
+    "timeline-chart",
+    "typescript",
+    "visualization"
+  ],
+  "author": {
+    "name": "Alexander Chernyaev",
+    "url": "https://github.com/tabuna"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@vitest/browser-playwright": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.1",
+    "eslint-plugin-import-x": "^4.17.1",
+    "eslint-plugin-jsdoc": "^64.2.1",
+    "eslint-plugin-n": "^18.3.0",
+    "eslint-plugin-promise": "^7.3.0",
+    "eslint-plugin-security": "^4.0.1",
+    "eslint-plugin-sonarjs": "^4.2.0",
+    "eslint-plugin-unicorn": "^73.0.0",
+    "globals": "^17.11.0",
+    "playwright": "^1.62.1",
+    "prettier": "^3.9.6",
+    "prettier-plugin-multiline-arrays": "^4.1.11",
+    "sass": "^1.103.1",
+    "stylelint": "^17.14.1",
+    "stylelint-config-recess-order": "^7.8.0",
+    "stylelint-config-standard": "^40.0.0",
+    "terser": "^5.51.2",
+    "typescript": "^7.0.2",
+    "vite": "^8.2.2",
+    "vitest": "^4.1.11"
+  }
+}