makersclaw 0.2.0 → 0.3.0

package/registry/blocks/cart/index.js

@@ -0,0 +1,4 @@
+// The Cart block — `makersclaw add cart`. Fixed: compose it through its
+// props (README.md beside this file); a cart it cannot be is your own
+// component in components/.
+export { Cart } from "./cart";

package/registry/blocks/cart/money.js

@@ -0,0 +1,28 @@
+// Money in the reader's words, and the sums a cart and its summary share.
+// Prices are numbers in the currency's major unit (19.5 is $19.50).
+
+const formats = new Map();
+
+export function money(amount, currency = "USD", locale) {
+  const key = `${locale ?? ""}|${currency}`;
+  let f = formats.get(key);
+  if (!f) {
+    try {
+      f = new Intl.NumberFormat(locale, { style: "currency", currency });
+    } catch {
+      f = new Intl.NumberFormat(locale, { style: "currency", currency: "USD" });
+    }
+    formats.set(key, f);
+  }
+  return f.format(Number(amount) || 0);
+}
+
+export const lineTotal = (item) => (Number(item.price) || 0) * (Number(item.quantity) || 0);
+
+export const subtotalOf = (items) => (items ?? []).reduce((sum, item) => sum + lineTotal(item), 0);
+
+export const countOf = (items) => (items ?? []).reduce((sum, item) => sum + (Number(item.quantity) || 0), 0);
+
+// A charge row's amount: a number is added to the total; a string
+// ("Calculated at payment") is shown as written and adds nothing.
+export const asAmount = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);

package/registry/blocks/chart/README.md

@@ -0,0 +1,316 @@
+# Chart
+
+Numbers as a shape: `LineChart`, `AreaChart` (stacked or not), `BarChart`
+(grouped or stacked, columns or bars), `PieChart` (a pie or a donut with
+the total in its middle), `Sparkline` (a trend beside a KPI) and
+`HeatmapChart` (a grid of two dimensions, each cell shaded by its value,
+with `ScaleLegend` as its key). Drawn in SVG (the heatmap as an HTML
+table), no chart library, in the workspace's chart colours. Each one is as
+wide as its container and redraws when that changes. Hover, touch or the
+arrow keys show a tooltip with a crosshair; the legend hides and shows a
+series; a screen reader gets a summary and the numbers as a table; with
+reduced motion nothing animates.
+
+```jsx
+import { AreaChart, BarChart, HeatmapChart, PieChart, Sparkline } from "../components/blocks/chart";   // a Makersclaw app ("./blocks/chart" from components/)
+import { AreaChart, BarChart, HeatmapChart, PieChart, Sparkline } from "@/components/makersclaw/blocks/chart";   // a shadcn project
+```
+
+They are client components: render them from a `"use client"` component,
+and load the rows in the server surface (README §4). Put a chart in a
+`Card` — the card gives the title; the chart is only the picture.
+
+## The data
+
+Rows, as `loadRows` returns them. One key holds the x (a month, a stage,
+a week) and each series is another key holding a number, in the order the
+x should read — sort in `loadRows`. A value that is missing or not a number
+is a gap in a line and nothing in a bar or an area.
+
+```js
+[{ month: "Jan", newBiz: 24600, expansion: 8100 }, { month: "Feb", newBiz: 26900, expansion: 8800 }]
+```
+
+A pie takes one row per slice: a key for the name, a key for the value.
+
+A heatmap takes one row per grid row: a key for the row's name and one key
+per column holding its number — a pivot, shaped in the query:
+
+```js
+[{ slot: "9–12", mon: 42, tue: 51, wed: 38 }, { slot: "12–15", mon: 18, tue: 24, wed: 65 }]
+```
+
+## Colours
+
+`series[].tone` picks a colour: `"chart-1"` … `"chart-5"` (or `1` … `5`).
+Left out, the series take chart-1, chart-2, … in order. The chart colours
+come from the workspace theme (`app/globals.css`, `--color-chart-N`): the
+first is the theme's primary, the others turn its hue so neighbours stay
+apart in every theme. A series that means a status may take a theme tone
+instead: `"success"`, `"warning"`, `"danger"`, `"info"`, `"primary"`,
+`"muted"`. In your own markup around a chart use the same classes:
+`bg-chart-1`, `text-chart-2`, `fill-chart-3`, `stroke-chart-4`.
+
+## Props
+
+### LineChart · AreaChart · BarChart
+
+- `data` — the rows. Empty (or missing) shows the empty state.
+- `x` — the key that holds each row's x, e.g. `"month"`.
+- `series` — what to draw, in order: `[{ key, label?, tone?, muted?,
+  dashed? }]`. `label` defaults to the key, humanised.
+  - `dashed` — LineChart and AreaChart: a dashed line with no fill under
+    it. The key and the tooltip show a dashed swatch.
+  - `muted` — drawn quieter and underneath the rest: the grey (unless it
+    has its own `tone`), a thinner line, a fainter fill. On a BarChart it
+    is only the grey.
+  - Together they are a "previous period" to compare against:
+
+    ```jsx
+    <LineChart
+      data={days}            // [{ day: "Mon", thisWeek: 42, lastWeek: 35 }, …]
+      x="day"
+      series={[{ key: "thisWeek", label: "This week" }, { key: "lastWeek", label: "Last week", muted: true, dashed: true }]}
+      label="Signups, this week against last"
+    />
+    ```
+- `format(value)` — how a value reads in the tooltip, the summary and the
+  table. Default: `1,250` · `48.2K`.
+- `formatAxis(value)` — how a tick reads (default `format`); give a
+  shorter one when `format` is long (`$48,200` → `$48K`).
+- `formatX(xValue, row)` — how an x reads (default: as written).
+- `label` — what the chart is, for a screen reader: `"Revenue by month"`.
+  Default `"Chart"`; always set it.
+- `description` — the sentence a screen reader hears after `label`.
+  Default: made from the data (the range, each series' first, last and
+  highest value).
+- `xLabel` — the x column's heading in the hidden table (default: the key,
+  humanised).
+- `height` — pixels, default `240`. The width is the container's.
+- `stacked` — AreaChart and BarChart: pile the series (negatives stack
+  down). The tooltip adds a total. Default `false`.
+- `orientation` — BarChart: `"vertical"` (columns, the default) or
+  `"horizontal"` (bars, categories down the left — for long names).
+- `valueLabels` — BarChart: each bar's value at its end ("10%"), in
+  `format`; stacked, the stack's total. `true`, or `(value, row, key)` →
+  the words (`key` is null for a total). With it the value axis is often
+  noise: `xAxis={false}` (horizontal) or `yAxis={false}`. Default `false`.
+- `track` — BarChart: a quiet full-length track behind every bar, for a
+  share or a distribution (a status's share of tickets). Pair it with
+  `grid={false}`. Default `false`.
+- `curve` — LineChart and AreaChart: `"monotone"` (default, smooth and
+  never overshooting), `"linear"` or `"step"`.
+- `dots` — LineChart and AreaChart: a dot on every point. Default `false`.
+- `grid` · `xAxis` · `yAxis` — gridlines and the two axes' labels. All
+  default `true`.
+- `legend` — the legend under the chart; its entries are toggles that hide
+  a series. Default: shown when there is more than one series.
+- `tooltip` — default `true`.
+- `onSelect(row, index)` — a click, a tap or Enter on a point or a bar
+  calls it: open the month, filter by the stage.
+- `emptyLabel` · `emptyBody` — what the empty state says. Default
+  `"No data yet"`.
+- `className` — layout around it (width, margin). Never colour.
+
+### PieChart
+
+- `data` — one row per slice.
+- `name` — the key holding a slice's name, default `"name"`.
+- `value` — the key holding its number, default `"value"`. Zero and
+  negative values draw nothing.
+- `donut` — open the middle. It shows the total, and the picked slice's
+  value and share while one is picked. Default `false`.
+- `centerLabel` — a donut's middle instead of the total: a string, or
+  `{ value, label }`.
+- `totalLabel` — the words under the total, default `"Total"`.
+- `format(value)` · `formatName(name, row)` · `label` · `description` ·
+  `height` · `tooltip` · `onSelect(row, index)` · `emptyLabel` ·
+  `emptyBody` · `className` — as above.
+- `legend` — default `true`; hiding a slice re-shares the rest.
+- `legendValues` — what follows each name in the legend: `"percent"`
+  (default), `"value"` or `"none"`.
+- A row's own `tone` colours its slice; otherwise chart-1 … chart-5 in
+  order (a sixth slice repeats chart-1 — five is the most a pie reads).
+
+### Sparkline
+
+A trend with no axes, gridlines, legend or tooltip, as wide as its box
+and `height` tall — small enough to sit under a kit `Stat` in a tile:
+
+```jsx
+<Card>
+  <Stat label="MRR" value="$84.2k" delta={6.1} />
+  <Sparkline data={mrr} label="MRR, last 12 months" height={28} className="mt-2" />
+</Card>
+```
+
+- `data` — numbers (`[12, 15, 14]`) or rows with `value`.
+- `value` — the key when `data` is rows, default `"value"`.
+- `label` — what it shows, e.g. `"MRR, last 12 months"`: a screen reader
+  hears it with the first, last, low and high values. Always set it.
+- `format(value)` — for those words.
+- `tone` — default `"chart-1"`.
+- `area` — the faded fill under the line, default `true`.
+- `dot` — a dot on the latest value, default `true`.
+- `height` — default `36`. The width is the container's.
+- `className` — layout. Never colour.
+
+### HeatmapChart
+
+- `data` — one row per grid row. Empty (or no `columns`) shows the empty
+  state.
+- `y` — the key holding each row's name, default `"name"`.
+- `columns` — the cells of a row, in order: `["mon", "tue"]` (labels made
+  from the keys) or `[{ key: "mon", label: "Mon" }, …]`.
+- `formatY(yValue, row)` — how a row's name reads (default: as written).
+- `tone` — the ramp's colour: `"chart-1"` (default) … `"chart-5"` (or
+  `1` … `5`). One colour, light to full: a heatmap is one measure.
+- `min` · `max` — the ends of the ramp. Default: 0 (or the lowest value,
+  when negative) and the highest value. Values past them take the end
+  shades.
+- `steps` — how many shades, default `5`. Each cell takes the shade its
+  value falls in (`scaleStep`), so equal shades mean equal bands.
+- `showValues` — the number on each cell, in `format`; on dark shades it
+  is drawn in the background's colour so it stays readable. Default
+  `false` (a compact grid of colour).
+- `format(value)` — how a value reads on the cell, in the tooltip, the
+  totals and the legend. Default: `1,250` · `48.2K`.
+- `cellShape` — `"square"` (default, rounded) or `"pill"` (short and
+  fully round — the contribution grid).
+- `rowTotals` · `colTotals` — a bold Total column at the right, a bold
+  Total row at the foot (and the grand total where they meet). Missing
+  values count as nothing. Default `false`.
+- `totalLabel` — default `"Total"`.
+- `tooltip` — the kit `Tooltip` on hover or keyboard focus. Default `true`.
+- `formatTooltip(value, row, column)` — its words (a string); `column` is
+  `{ key, label }` and `value` is null when the cell has none. Default:
+  `"Tue · 9–12: 51"`. The same words name the cell to a screen reader.
+- `legend` — a `ScaleLegend` under the grid, at the right. Default `true`.
+  Set it `false` to place your own (in the card's header, say).
+- `legendLabels` — its end words, e.g. `["Less", "More"]`; default the
+  numbers at the two ends.
+- `onSelect(row, columnKey, value)` — a click, or Enter or Space on a
+  focused cell.
+- `label` · `description` — as above; the description defaults to the
+  size, the range and the highest cell.
+- `yLabel` — the row names' heading for a screen reader (default: the key,
+  humanised).
+- `emptyLabel` · `emptyBody` · `className` — as above.
+
+The grid is a table: a screen reader reads each cell with its row and
+column. Tab lands on one cell; the arrow keys move, Home and End go to the
+row's ends (with Ctrl or ⌘, the grid's). A grid wider than its box
+scrolls sideways inside it, and the row names stay at the left — on the
+card's background, so put the heatmap in a `Card`.
+
+### ScaleLegend
+
+The heatmap's key, for a legend placed yourself: `Less ▪▪▪▪▪ More`.
+
+- `min` · `max` — the ends, default `0` and `1`.
+- `steps` — the shades, default `5` (match the chart's).
+- `labels` — `["Less", "More"]`, or leave it out for the numbers at the
+  ends, in `format`.
+- `tone` · `format` — as the chart's.
+- `shape` — `"square"` (default) or `"pill"`, as the chart's cells.
+- `label` — what a screen reader hears it called, default `"Scale"`.
+
+### scaleStep · scaleShade
+
+The ramp itself, for cells a block draws on its own.
+
+- `scaleStep(value, min, max, steps = 5)` → which shade a value falls in:
+  `0` … `steps − 1`, or `null` for a missing value.
+- `scaleShade(value, { min, max, steps, tone })` → `{ step, style,
+  className }`: put `style` (the fill) and `className` (the text colour
+  that reads on it) on your element.
+
+### ChartLegend
+
+The key the charts draw, for a legend of your own (several sparklines
+sharing one key, say).
+
+- `items` — `[{ key, label, tone?, value? }]`; `value` is a muted note
+  after the label.
+- `hidden` — a `Set` (or array) of keys shown as off.
+- `onToggle(key)` — makes each entry a toggle; without it the legend is a
+  plain list.
+- `label` — what it is called to a screen reader, default `"Legend"`.
+
+## Example
+
+```jsx
+// surfaces/sales.jsx — server: load, hand over
+import { loadRows } from "../lib/data";
+import SalesCharts from "../components/SalesCharts";
+
+export default async function SalesSurface() {
+  const { rows: months, error } = await loadRows({ source: "public.revenue_by_month", orderBy: "month asc" });
+  const { rows: stages } = await loadRows({ source: "public.deals_by_stage", orderBy: "position asc" });
+  const { rows: visits } = await loadRows({ source: "public.visits_by_slot", orderBy: "position asc" });
+  return <SalesCharts months={months} stages={stages} visits={visits} error={error} />;
+}
+```
+
+```jsx
+// components/SalesCharts.jsx — client: the cards and the charts
+"use client";
+import { Card, Notice } from "./ui";
+import { AreaChart, BarChart, HeatmapChart, Sparkline } from "./blocks/chart";
+
+const usd = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", maximumFractionDigits: 0 });
+const usdShort = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD", notation: "compact" });
+
+export default function SalesCharts({ months, stages, visits, error }) {
+  return (
+    <div className="grid gap-4">
+      {error ? <Notice tone="danger">{error}</Notice> : null}
+      <Card title="MRR">
+        <Sparkline data={months} value="mrr" label="MRR, last 12 months" format={(v) => usd.format(v)} />
+      </Card>
+      <Card title="Revenue by month">
+        <AreaChart
+          data={months}
+          x="month"
+          series={[{ key: "new_biz", label: "New business" }, { key: "expansion", label: "Expansion" }]}
+          stacked
+          format={(v) => usd.format(v)}
+          formatAxis={(v) => usdShort.format(v)}
+          label="Revenue by month"
+        />
+      </Card>
+      <Card title="Deals by stage">
+        <BarChart data={stages} x="stage" series={[{ key: "deals", label: "Deals" }]} orientation="horizontal" label="Deals by stage" />
+      </Card>
+      <Card title="Site visits by time of day">
+        <HeatmapChart
+          data={visits}
+          y="slot"
+          columns={[{ key: "mon", label: "Mon" }, { key: "tue", label: "Tue" }, { key: "wed", label: "Wed" }]}
+          showValues
+          rowTotals
+          colTotals
+          formatTooltip={(v, row, col) => `${col.label} ${row.slot}: ${v ?? 0} visits`}
+          label="Site visits by weekday and time slot"
+        />
+      </Card>
+    </div>
+  );
+}
+```
+
+## What it will not do
+
+- Sort, group or sum: the rows come shaped. Totals by month or by stage
+  are a query (a view, or `loadRows` over one).
+- A time scale: x is a list of labels, evenly spaced, in row order. Give
+  every period a row (a month with no sales is a row with 0).
+- Two value axes, scatter, radar, maps, zoom or brushing.
+- A colour outside the theme: series take the chart tones and the theme's
+  status tones only. Colour by value is the heatmap's alone, on one chart
+  tone.
+- Draw its own title: put it in a `Card`.
+
+A chart it cannot be is your own component in `components/`, built from
+the kit — not an edit to this block. Its files are fixed: `npm run check`
+refuses a change, and `makersclaw add chart` restores them.

package/registry/blocks/chart/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "chart",
+  "title": "Chart",
+  "description": "Line, area (stacked), bar (grouped or stacked, columns or bars, value labels at the ends, a track behind), a muted or dashed series for a previous period to compare against, pie and donut charts, sparklines and heatmaps (a grid shaded by value, with a scale legend), drawn in SVG (the heatmap as an HTML table) with the workspace's chart colours: round ticks, gridlines, a tooltip and crosshair under the pointer or the arrow keys, a legend that hides a series, and a data table for screen readers.",
+  "useWhen": "Numbers the founder should see as a shape: revenue by month, deals by stage, pipeline by source, a KPI's trend. Not for a single figure with no history (a stat), exact lookups (a table), or records on a timeline (a calendar).",
+  "tags": ["chart", "graph", "line", "area", "bar", "pie", "donut", "sparkline", "analytics", "dashboard", "kpi", "trend", "comparison", "previous period", "metrics", "report", "heatmap", "grid", "scale"],
+  "exports": ["LineChart", "AreaChart", "BarChart", "PieChart", "Sparkline", "ChartLegend", "HeatmapChart", "ScaleLegend", "scaleStep", "scaleShade"],
+  "files": ["index.js", "core.jsx", "cartesian.jsx", "pie.jsx", "sparkline.jsx", "heatmap.jsx"],
+  "requires": []
+}