@weasel-js/plot 0.0.0-stage → 1.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+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

@@ -1,3 +1,59 @@
-# Temporary Holding Version
+# @weasel-js/plot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Charts on weasel's scene graph. A chart is a scene node holding its spec, with
+the marks it is drawn with as nodes under it, each keeping the value it stands
+for; dragging a mark edits the spec.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/#pkg/plot).
+
+```sh
+npm install @weasel-js/plot
+```
+
+## Two layers
+
+**Scales, axes and marks.** A scale maps values onto a range and says which
+values an axis marks and how they read: `linearScale`, `logScale`,
+`bandScale`, `timeScale` (ticks on calendar units, in UTC) and `ordinalScale`.
+`axisMarks` draws an axis from any of the first four: a rule, ticks, labels
+measured through `@weasel-js/text`, grid lines and a title. The mark builders
+(`barMark`, `spanMark`, `lineMark`, `areaMark`, `pointMark`, `arcMark`,
+`ribbonMark`, `ruleMark`, `textMark`) each return a `PlotMark`: a key, a box,
+and data the kit's own painters draw, with the datum under `plotMark`, so a
+hit-test on a mark reaches its value.
+
+**Chart specs.** `PlotData` is a union of chart specs on `kind`; today it holds
+`xychart`, bar and line series over a category band or a numeric range.
+`plotSpecs(data, { box })` compiles one to scene node specs: a group root whose
+data is `{ plot: { data, theme } }`, then every mark under it, in the root's
+frame. `replacePlotData` swaps a root's spec and rebuilds its marks as one undo
+entry. `plotEditing({ scene })` gives the handle layer and the contribution
+that bind a drag on a bar's end or a line's point to `plot.dragValue`;
+`PlotView` hosts one chart on a canvas of its own with both wired.
+
+Colors come from a `PlotTheme`, by role: `text`, `axis`, `grid`, and `series`,
+which series take in turn. `plotThemeFrom` builds one from a resolved
+`@weasel-js/theme` theme; `PLOT_THEME` is the weasel theme's dark mode.
+
+```tsx
+import { registerCanvasFont } from '@weasel-js/font';
+import { PlotView, type PlotData } from '@weasel-js/plot';
+import { useState } from 'react';
+
+registerCanvasFont('sans-serif');
+
+const SALES: PlotData = {
+  kind: 'xychart',
+  title: 'Sales',
+  x: { kind: 'band', categories: ['jan', 'feb', 'mar'] },
+  y: { title: 'Revenue', min: 0, max: 100 },
+  series: [{ kind: 'bar', values: [20, 50, 80] }, { kind: 'line', values: [10, 60, 40] }],
+};
+
+export function Sales() {
+  const [data, setData] = useState(SALES);
+  return <PlotView data={data} onChange={setData} width={600} height={400} />;
+}
+```