makersclaw 0.1.0 → 0.3.0

package/registry/blocks/spreadsheet/README.md

@@ -0,0 +1,307 @@
+# Spreadsheet
+
+A table you edit like Google Sheets or Airtable. Click a cell and type;
+Enter edits, Tab and the arrows move, Shift extends a range, ⌘C / ⌘V copy
+and paste ranges to and from Sheets and Excel, drag the small square at a
+range's corner to fill down, ⌘Z undoes. Every column has a type — text,
+number, currency, date, single select, multiple select, person, checkbox,
+link, rating — and each type draws its own cell and opens its own editor
+(a calendar for a date, a searchable list for a select or a person). Drag
+a header to reorder, its edge to resize; its menu sorts, filters, renames,
+changes the type, inserts, freezes, hides and deletes. The toolbar has
+search, a filter panel, a sort panel, show/hide fields and "Add row"; the
+line under the grid counts rows and sums the selected numbers.
+
+It is virtualised in both directions (`@tanstack/react-virtual`): only the
+cells in the window are drawn, so 10,000 rows scroll like ten. On a phone
+the rows grow to 44px, the frozen column narrows, a tap selects and a
+second tap edits; long-press opens the row menu.
+
+```jsx
+import { Spreadsheet } from "../components/blocks/spreadsheet";   // a Makersclaw app ("./blocks/spreadsheet" from components/)
+import { Spreadsheet } from "@/components/makersclaw/blocks/spreadsheet";   // a shadcn project
+```
+
+It is a client component: render it from a `"use client"` component, and
+load the rows in the server surface (README §4). `makersclaw add
+spreadsheet` adds `@tanstack/react-virtual` (pinned, exact) to
+package.json: run `npm install` after. The helpers (the type registry,
+`processRows`, TSV) are plain functions and run on the server too.
+Blocks built on this one (base-view, csv-import) import it, never the
+virtualiser.
+
+## The data
+
+`rows` — plain objects with a unique `id`; each column reads one key.
+`columns` — what each key is:
+
+```js
+const COLUMNS = [
+  { key: "company", name: "Company", type: "text", width: 200, required: true },
+  { key: "stage", name: "Stage", type: "select",
+    options: [{ value: "lead", label: "Lead", hue: 5 }, { value: "won", label: "Won", hue: 1 }] },
+  { key: "value", name: "Deal value", type: "currency", currency: "USD", precision: 0 },
+  { key: "owner", name: "Owner", type: "person" },            // ids from the `people` prop
+  { key: "close", name: "Close date", type: "date" },          // "YYYY-MM-DD"
+  { key: "segments", name: "Segments", type: "multi-select", options: [...] },
+  { key: "fit", name: "Fit", type: "rating", max: 5 },
+  { key: "contacted", name: "Contacted", type: "checkbox" },
+  { key: "website", name: "Website", type: "url" },
+];
+```
+
+A column: `key`, `name`, `type` (default `"text"`), and any of `width`
+(px), `readOnly`, `required` (an empty cell is marked as a problem),
+`options` (select types: `{ value, label, hue: 1–5 }` — the hue is a
+chart token, never a colour), `allowNew: false` (a select that refuses
+new options), `currency` + `precision` (currency, number), `max`
+(rating, default 5), `multiple: true` (person: several people),
+`dateOrder: "dmy"` (how `3/4/2026` is read; default month first). Any
+other key is kept and ignored, so a block on top can carry its own.
+
+What each type stores:
+
+| type | value |
+| --- | --- |
+| `text`, `url` | a string |
+| `number`, `currency` | a number, or `null` |
+| `date` | `"YYYY-MM-DD"`, or `null` — a day, never a `Date` |
+| `select` | an option's `value`, or `null` |
+| `multi-select` | an array of option values |
+| `person` | a person's `id` (an array with `multiple`) |
+| `checkbox` | `true` / `false` |
+| `rating` | a whole number, `0` = none |
+
+## Props
+
+Required first; the rest have the defaults shown.
+
+- `rows` — the records, as above.
+- `columns` — the fields, as above.
+
+Saving. Every callback is async and answers `{ ok: true }` or
+`{ ok: false, error }` (a throw counts as a failure; nothing returned
+counts as ok). The grid applies the change at once and, on a failure,
+puts it back and says so in a toast.
+
+- `onChange(changes)` — cell edits, always a batch: one typed value, a
+  paste, a fill, a clear, an undo. `changes` is
+  `[{ rowId, key, value, prev }]`. Without it the grid still edits (in
+  memory).
+- `onAddRows(rows, { index, restore })` — new rows (from "Add row", the
+  row menu's insert, a paste that runs past the end, or an Undo of a
+  delete when `restore` is true). `index` is where in `rows` they go
+  (absent: the end). A row's `id` is made here (`createRow` or a random
+  one); answer `{ ok: true, rows: [{ id }] }` to swap in the server's ids.
+  Without it there is no Add row.
+- `onDeleteRows(ids)` — rows deleted from the row menu or the selection
+  line; a toast offers Undo (which calls `onAddRows` with `restore`).
+  Without it rows cannot be deleted.
+- `onColumnsChange(columns, { reason })` — the whole new column list after
+  a rename, a type change, an added, deleted or restored field, or a
+  select option created while typing; `reason` is `"rename"`, `"type"`,
+  `"add"`, `"delete"`, `"restore"` or `"options"`. A type change also sends
+  the converted values through `onChange`. Without it the header menu
+  cannot change fields (options typed into a select are kept in memory).
+- `createRow()` — a new row's starting values (`{ id, stage: "lead" }`).
+  Give each call a unique `id`.
+
+The view — which fields show, in what order and width, what is frozen,
+sorted and filtered. Plain JSON; store it per view (base-view keeps one
+per tab):
+
+```js
+{ order: ["company", "stage", …], hidden: ["website"], widths: { company: 240 },
+  frozen: 1, sort: [{ key: "value", dir: "desc" }],
+  filters: [{ id: "f1", key: "stage", op: "any", value: ["won", "negotiation"] }] }
+```
+
+- `view` + `onViewChange(view)` — controlled; or `defaultView` and the
+  grid keeps it (still reporting through `onViewChange`). Keep it in state:
+  a new `sort` or `filters` array each render re-sorts each render.
+- A filter's `op` is one of its type's conditions (`COLUMN_TYPES[type]
+  .filters[].id`, plus `empty` / `not-empty`); a blank `value` means "not
+  set yet" and passes every row.
+- Edits do not re-sort: an edited row stays where it is (as in Airtable)
+  and the line under the grid offers "Sort again". New data from the
+  props re-runs the view.
+
+Behaviour and look:
+
+- `people` — `[{ id, name, email?, src? }]`, who a `person` cell can hold.
+- `types` — your own column types, or overrides of the built-ins (see
+  below). Keep the object stable (a module constant).
+- `validate(row, column)` — a message when a cell is wrong, else null. A
+  wrong cell gets a red corner and its message on hover and under the
+  grid; the line under the grid counts problems and jumps to the next.
+- `readOnly` — nothing edits (select, copy, sort, filter still work).
+  Per column: `column.readOnly`.
+- `lockFields` — the header menu cannot rename, retype, add or delete
+  fields, though `onColumnsChange` is given; select options typed into a
+  cell still arrive through it (reason `"options"`). csv-import's review
+  uses this.
+- `onExpandRow(row)` — adds an open button to each row's number (and
+  Space / ⌘↵ / the row menu); draw the record yourself (a Sheet).
+- `onSelectionChange({ active: { rowId, key }, rowIds, keys } | null)`.
+- `loading` — skeleton rows.
+- `label` — what a screen reader calls the grid (`"Table"`).
+- `noun` — what a row is (`"deal"`): "Add deal", "10,000 deals". Plural
+  is noun + "s". Default `"row"`.
+- `height` — the grid's height (`560`, or any CSS length); it scrolls
+  inside it.
+- `toolbar` — `false` hides the toolbar (a parent draws its own and
+  drives the grid through the handle). `toolbarStart`, `toolbarEnd` —
+  nodes at the toolbar's ends (an "Import CSV" button).
+- `empty` — a node for the empty table, instead of "No rows yet".
+- `locale`, `currency` — for numbers, amounts and dates (the reader's
+  locale, `"USD"`). `today` — `"YYYY-MM-DD"` for the date picker (a demo
+  that must not change day to day).
+- `ref` — the handle, below.
+
+### The handle
+
+`<Spreadsheet ref={grid} …>` then `grid.current`:
+
+- `focus()` · `clearSelection()`
+- `select({ rowId, key, toRowId?, toKey? })` → true when found; a range
+  when `to…` is given
+- `getSelection()` → `{ active, rowIds, keys }` or null
+- `scrollToRow(rowId)` · `edit(rowId, key)` — opens that cell's editor
+- `addRow(values?)` — adds, selects and edits a row (through `onAddRows`)
+- `deleteRows(ids)` · `undo()` · `redo()`
+- `copy()` → the selection as TSV · `paste(text)` — TSV at the selection
+- `visibleRows()` · `visibleColumns()` — after filter and sort, in order
+- `resort()` — the "Sort again" button
+
+### The column-type registry
+
+`COLUMN_TYPES` holds the built-ins; `typeOf(column, types)` resolves one
+(your `types` first, then the built-ins, unknown names read as text). A
+type is plain data and functions — the logic runs on the server too:
+
+```js
+{
+  label: "Currency", icon: "dollar",      // a kit glyph for the header
+  align: "end", width: 130,               // default width, px
+  editor: "number",                       // the in-cell editor: text · number · date ·
+                                          //   select · person · toggle · rating · url · none
+  multiple: false,                        // select editor: pick several
+  empty: (v) => v == null,                // default: null, "" or []
+  parse: (text, column, ctx) => ({ value }) | ({ error }),  // typed or pasted text in;
+                                          //   a select may add `create: [{ value, label, hue }]`
+  toText: (v, column, ctx) => "1250.5",   // what a copy puts on the clipboard, and an edit starts from
+  format: (v, column, ctx) => "$1,250.50",// what the cell shows (and search matches)
+  compare: (a, b, column, ctx) => a - b,  // sort order; empties always sort last
+  filters: [{ id: "gt", label: ">", arg: "number", test: (v, arg, column, ctx) => v > arg }],
+                                          // arg: text · number · date · options · person · none
+  render: (v, column, ctx) => <node/>,    // optional: draw the cell yourself
+  Editor: MyEditor,                       // optional: your own editor component
+}
+```
+
+`ctx` is `{ people, locale, currency }`. A custom type may be small —
+anything it leaves out comes from `text`:
+
+```js
+const TYPES = {
+  percent: {
+    label: "Percent", icon: "hash", align: "end", width: 100, editor: "number",
+    parse: (t) => { const n = parseNumberText(String(t).replace("%", "")); return Number.isNaN(n) ? { error: "Not a percent" } : { value: n == null ? null : n / 100 }; },
+    toText: (v) => (v == null ? "" : String(v * 100)),
+    format: (v) => (v == null ? "" : `${Math.round(v * 100)}%`),
+    compare: (a, b) => a - b,
+  },
+};
+```
+
+A custom `Editor` gets `{ value, column, type, ctx, initial, today,
+canCreate, onCommit(value, move, { create }?), onCancel() }` and draws
+inside the cell (absolutely positioned over it). `initial` is the key
+that opened it (a typed letter) or null; `move` is `"down"`, `"up"`,
+`"right"`, `"left"` or null (stay). Float a panel beside the cell with
+the exported `CellPanel` (`anchorRef`, `onDismiss`, `width`, `label`).
+
+Other exports, for blocks on top: `CellValue` (a cell's display),
+`OptionBadge`, `editorFor(type)`, `parseCell`, `convertValue(v, from,
+to)`, `guessType(texts)` (csv-import's guess), `parseNumberText`,
+`parseDateText`, `optionValue(label, taken)`, `emptyView`,
+`normalizeView`, `orderedColumns`, `visibleColumns`, `processRows(rows,
+columns, view, { search, ctx, custom })`, `passesFilters`, `parseTSV`,
+`toTSV`, `pasteChanges`, `fillChanges`, `clearChanges`, `applyChanges`,
+`invertChanges`, `TYPE_ORDER`, `sortWords(type)`.
+
+## Keys
+
+↑ ↓ ← → move (⌘ to the edge; Shift extends) · Tab / Shift+Tab · Home /
+End · Page Up / Down · Enter or F2 edits · typing replaces · Esc cancels ·
+Delete clears · ⌘C ⌘X ⌘V · ⌘D fills down · ⌘Z / ⇧⌘Z · ⌘A all · Shift+Space
+the row · ⌘Space the column · Space ticks a box or opens the row ·
+Shift+F10 the row menu.
+
+## Example
+
+```jsx
+"use client";
+import { useState } from "react";
+import { updateRow, insertRow, deleteRow } from "../lib/actions";
+import { Spreadsheet } from "./blocks/spreadsheet";
+
+const COLUMNS = [
+  { key: "name", name: "Name", type: "text", required: true },
+  { key: "stage", name: "Stage", type: "select", options: [{ value: "lead", label: "Lead", hue: 2 }, { value: "won", label: "Won", hue: 1 }] },
+  { key: "amount", name: "Amount", type: "currency", precision: 0 },
+  { key: "close", name: "Close date", type: "date" },
+];
+
+export default function Deals({ deals, team }) {
+  const [view, setView] = useState({ sort: [{ key: "amount", dir: "desc" }] });
+  return (
+    <Spreadsheet
+      label="Deals"
+      noun="deal"
+      rows={deals}
+      columns={COLUMNS}
+      people={team}
+      view={view}
+      onViewChange={setView}
+      onChange={async (changes) => {
+        for (const c of changes) {
+          const r = await updateRow({ source: "public.deals", id: c.rowId, patch: { [c.key]: c.value } });
+          if (!r.ok) return r;
+        }
+        return { ok: true };
+      }}
+      onAddRows={async (rows) => {
+        const made = [];
+        for (const { id, ...values } of rows) {
+          const r = await insertRow({ source: "public.deals", values: { stage: "lead", ...values } });
+          if (!r.ok) return r;
+          made.push({ id: r.id });   // the database's id replaces the one the grid made up
+        }
+        return { ok: true, rows: made };
+      }}
+      onDeleteRows={async (ids) => {
+        for (const id of ids) {
+          const r = await deleteRow({ source: "public.deals", id });
+          if (!r.ok) return r;
+        }
+        return { ok: true };
+      }}
+    />
+  );
+}
+```
+
+## What it will not do
+
+- No formulas. A value is what was typed; a derived column is computed by
+  you and passed in (mark it `readOnly`).
+- No merged cells, no rich text in a cell, no row heights of their own:
+  every row is one height (that is what keeps 10,000 rows smooth).
+- No grouping of rows under headings — that is a view on top (base-view).
+- Search and filters run in the browser over `rows`. For a table too big
+  to send, filter on the server and pass the page.
+- Sort and filter follow the view, not the edits: an edited row stays put
+  until "Sort again" (or new props).
+- Paste reads plain text (TSV). Pasted images and HTML tables are read as
+  their text.

package/registry/blocks/spreadsheet/block.json

@@ -0,0 +1,13 @@
+{
+  "name": "spreadsheet",
+  "title": "Spreadsheet",
+  "description": "A table you edit like Google Sheets or Airtable, virtualised for 10,000+ rows: typed columns (text, number, currency, date, single and multiple select, person, checkbox, link, rating) each with its own in-cell editor, a cell cursor and range selection with the mouse and arrow keys, typing to edit, copy and paste ranges as TSV (to and from Sheets and Excel), drag-to-fill and ⌘D fill down, undo/redo, column resize, drag to reorder, hide, freeze, rename, change type and add fields, row insert and delete with Undo, sort and filter panels, search, a sum/average of the selection, validation marks, and a phone layout. Edits go out as async callbacks answering { ok }, applied at once and rolled back on failure. A column-type registry and an imperative handle for blocks built on it.",
+  "useWhen": "People need to enter or clean up many records in a grid, fast, with the keyboard: a lead list, an inventory, a budget, a content calendar, a table view over any collection, the grid under an Airtable-like base. Not for a read-mostly list to scan and act on row by row (data-table), records moving through stages (board), or a single record (record-form).",
+  "tags": ["spreadsheet", "grid", "table", "airtable", "google sheets", "excel", "editable", "cells", "inline edit", "virtualized", "10k rows", "copy paste", "tsv", "fill down", "columns", "sort", "filter", "select", "multi select", "person", "rating", "undo", "keyboard", "base"],
+  "exports": ["Spreadsheet", "CellValue", "CellPanel", "OptionBadge", "editorFor", "TYPE_ORDER", "sortWords", "COLUMN_TYPES", "typeOf", "parseCell", "convertValue", "guessType", "parseNumberText", "parseDateText", "optionValue", "isBlank", "emptyView", "normalizeView", "orderedColumns", "visibleColumns", "processRows", "passesFilters", "parseTSV", "toTSV", "pasteChanges", "fillChanges", "clearChanges", "applyChanges", "invertChanges"],
+  "files": ["index.js", "spreadsheet.jsx", "cells.jsx", "chrome.jsx", "types.js", "grid.js"],
+  "requires": [],
+  "dependencies": {
+    "@tanstack/react-virtual": "3.14.13"
+  }
+}