makersclaw 0.2.0 → 0.3.0

package/registry/blocks/data-table/README.md

@@ -0,0 +1,386 @@
+# Data table
+
+Records as a table the founder can work. Click a header to sort (shift-click
+to sort by more than one column), search every column, narrow by facets that
+show how many rows each choice leaves, pick which columns show, select rows
+and act on them together from a bar that appears, act on one row from its
+menu or from buttons in the row, open a row with a click, and move through
+pages of a chosen size. Opt in to rows that open to show their details,
+rows filed under group headings with subtotals, an aligned totals row,
+arrow keys over the rows, and a first column that stays put while a wide table scrolls sideways.
+Loading shows skeleton rows; "no rows yet" and "nothing matches" are two
+different states, the second with a way out. It runs over `rows` in the
+browser, or — with `manual` — shows the page a server chose.
+
+```jsx
+import { DataTable } from "../components/blocks/data-table";   // a Makersclaw app ("./blocks/data-table" from components/)
+import { DataTable } from "@/components/makersclaw/blocks/data-table";   // 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).
+
+## The data
+
+Any array of objects with a unique id (`idColumn`, default `"id"`). Each
+column reads one key of a row, or draws the cell itself with `cell(row)`.
+
+```js
+const COLUMNS = [
+  { key: "number", header: "Invoice", sortable: true, hideable: false },
+  { key: "customer", header: "Customer", sortable: true, cell: (r) => <CustomerCell r={r} /> },
+  { key: "status", header: "Status", sortable: true, cell: (r) => <Badge tone={TONE[r.status]}>{r.status}</Badge> },
+  { key: "amount", header: "Amount", sortable: true, align: "end", cell: (r) => money(r.amount) },
+  { key: "method", header: "Method", hidden: true },
+];
+```
+
+A column:
+
+- `key` — the row key it reads (and its id for sort, filters, visibility).
+- `header` — what the header says; default made from the key.
+- `cell(row)` — what the cell draws; default the value as text. Kit parts
+  and tokens only.
+- `sortable` — the header becomes a sort button.
+- `sortValue(row)` — what it sorts by, when the cell is not the value
+  (a status in its own order, a date string, a nested field). Numbers sort
+  as numbers, strings naturally ("INV-9" before "INV-10"); blanks sort
+  last either way.
+- `searchValue(row)` — what the search matches; default `sortValue` or
+  the value. `searchable: false` leaves the column out of the search.
+- `align` — `"start"` (default) or `"end"` (amounts: right-aligned,
+  tabular figures). `numeric: true` means the same.
+- `width` — a CSS width for the column (`"8rem"`).
+- `hideable` — default true; false keeps it out of the Columns menu.
+- `hidden` — starts hidden (the Columns menu can show it).
+- `className` · `headerClassName` — layout on its cells or its header.
+  Never colour.
+
+Any other key on a column is kept and ignored, so a block built on this
+one can carry its own (report-table's `kind`).
+
+## Props
+
+- `rows` — the records. Pass `useFixture(rows, SAMPLE).rows` and the
+  examples show, sort and filter like rows, but a bulk action never
+  receives them (they are not rows): selecting only examples and pressing
+  one says so and changes nothing.
+- `columns` — as above.
+- `idColumn` — default `"id"`.
+- `label` — what the table is called to a screen reader, default `"Table"`.
+- `noun` — what a row is ("invoice"): used in "1–10 of 60 invoices", the
+  facet counts and the announcements. Default `"row"`.
+
+Search
+
+- `searchable` — default true: a search field with a glyph leads the
+  toolbar. Every word must appear somewhere in the row.
+- `searchPlaceholder` — default `"Search…"`.
+- `search` · `defaultSearch` · `onSearchChange(text)` — the text.
+
+Facets
+
+- `facets` — `[{ key, label?, options?, value?(row) }]`: one multi-choice
+  Combobox per facet, each option with the number of rows it would show
+  at its right (counted over the search and the other facets). `options`
+  `[{ value, label }]` fixes the choices and their order; without it they
+  are the values found in `rows`. `value(row)` when the facet is not a
+  plain key.
+- `filters` · `defaultFilters` · `onFiltersChange(filters)` — the chosen
+  values, `{ status: ["paid", "overdue"], owner: ["Maya"] }`.
+
+Sort
+
+- `sort` · `defaultSort` · `onSortChange(sort)` — `[{ key, dir: "asc" | "desc" }]`,
+  the first entry sorts first. A press cycles a column asc → desc → off.
+- `multiSort` — default true: shift-click adds a column to the sort (each
+  sorted header shows its place). False: one column at a time.
+
+Selection
+
+- `selectable` — checkboxes on every row and a select-this-page box in
+  the header. On by default when `bulkActions`, `selection` or
+  `onSelectionChange` is given.
+- `selection` · `defaultSelection` · `onSelectionChange(ids)` — the chosen
+  ids, as strings. A selection survives search, filters and paging.
+- `bulkActions` — `[{ label, onSelect(rows, ids), icon?, tone?: "danger", disabled?, keepSelection? }]`,
+  or `(selectedRows) => [...]`. With rows selected a bar shows the count,
+  "Select all N" (when the whole page is chosen and more match), Clear,
+  and these as buttons. `onSelect` may be async; return
+  `{ ok: false, error }` (or throw) and the bar says why it failed and
+  keeps the selection. Anything else clears the selection, unless
+  `keepSelection: true` (an export).
+
+Columns
+
+- `hiddenColumns` · `defaultHiddenColumns` · `onHiddenColumnsChange(keys)` —
+  the keys not shown. Default: the columns marked `hidden`. The Columns
+  menu (checkbox items) sets it; the last column shown cannot be hidden.
+
+Pages
+
+- `page` · `defaultPage` (1) · `onPageChange(page)` — 1-based. A new
+  search, filter, sort or page size goes back to page 1; a page past the
+  end (rows removed) goes to the last.
+- `pageSize` · `defaultPageSize` (10) · `onPageSizeChange(n)`, `pageSizes`
+  (default `[10, 25, 50, 100]`) — the "Rows per page" choice.
+- `paginate` — default true; false shows every row and no pager.
+
+Rows
+
+- `rowActions(row)` — the row's "…" menu, in kit `Menu` items
+  (`[{ label, onSelect, icon?, tone?: "danger" }, { type: "separator" }, …]`;
+  a falsy item is skipped). Nothing returned, no menu.
+- `inlineActions` — draw a row's first actions as buttons in the row
+  instead of in the menu: a number (the first N of `rowActions(row)`) or
+  `true` (all of them). An action with `inline: true` is always a button,
+  one with `inline: false` never is; separators and labels stay in the
+  menu, and the "…" menu holds whatever is left. A button with an `icon`
+  is a square glyph button with a tooltip (on a phone card, the glyph and
+  the words); without one it is a small text button ("View"). Its
+  `onSelect(row)` may be async: the button spins and the row's other
+  buttons wait, and `{ ok: false, error }` (or a throw) shows a danger
+  notice above the table naming the action and the row. `tone: "danger"`
+  and `disabled` work as in the menu. Default: none — every action in the
+  menu, as before.
+- `onRowClick(row)` — a click on the row (not on its checkbox, menu or a
+  link inside a cell), or Enter on a focused row: open your `Sheet`.
+- `rowTone(row)` — `"success" | "info" | "warning" | "danger" | "highlighted"`
+  or nothing: a tint on the row's cells from the theme's status colours
+  (hover deepens it). `"highlighted"` is a pinned or best row, not a
+  status: a light primary tint and a bar at its leading edge. Status tones
+  are for status only.
+- `rowClassName(row)` — more classes on the row (layout, weight). Never
+  colour; that is `rowTone`.
+
+Details (expandable rows)
+
+- `renderExpanded(row)` — what shows under a row when it is open. Adds a
+  leading chevron column; the chevron turns when the row is open, and is
+  a button with `aria-expanded`. A row with no `onRowClick` also opens on
+  a click or Enter.
+- `canExpand(row)` — false leaves a row without a chevron. Default: every
+  row can open.
+- `expanded` · `defaultExpanded` · `onExpandedChange(ids)` — the open ids,
+  as strings.
+
+Groups
+
+- `groupBy` — a key or `(row) => value`: each group gets a heading row
+  with its label and how many rows it holds. Sort first, then group: a
+  sort orders rows inside their groups and never moves a group. Paging
+  counts rows; a group split across pages repeats its heading.
+- `groupOrder` — the group values to put first, in order
+  (`["overdue", "pending"]`; the rest follow in the order they first
+  appear in `rows`), or a compare function over two group values.
+  Default: the order groups first appear in `rows`.
+- `groupLabel(value, rows)` — the heading's label. Default the value
+  (`"None"` for a blank).
+- `groupSummary(rows)` — a node at the heading's right: a sum, a count.
+  `rows` is the whole group, not only this page's part.
+- `groupFooter(rows)` — a subtotal row under the group, bold on a tinted
+  background, on the page where the group ends. Return a map of column
+  key to node (`{ amount: "$4,200" }`) for cells aligned under their
+  columns ("Subtotal" fills the first column unless the map has it), or
+  one node for a single right-aligned cell.
+
+Totals
+
+- `totals` — a map of column key to node, or `(rows) => map` over every
+  row that matches the search and filters (all pages; in `manual`, the
+  rows given): one row in the table's `<tfoot>`, each value under its
+  column. `footer` is still the free node under the table.
+- `totalsLabel` — default `"Total"`, in the first column when the map
+  has nothing for it; `null` for none.
+
+Keyboard
+
+- `keyboard` — arrow keys over the rows. One row is in the tab order at
+  a time (the last one focused, else the first) and shows a focus ring.
+  ↑ ↓ move, Home and End go to the first and last row on the page, Space
+  selects the row (when `selectable`), Enter opens it as a click does,
+  → and ← open and close its details, Esc clears the selection. Works on
+  the phone cards too.
+
+Layout
+
+- `stickyFirstColumn` — the first shown column (and the chevron and
+  checkbox before it) stays put while the table scrolls sideways, with an
+  edge line. A wide table always scrolls inside its own box, never the
+  page; details rows and group headings are drawn at the box's visible
+  width.
+
+Slots and states
+
+- `toolbar` — your controls at the toolbar's end, before Columns: the one
+  "New invoice" button, an export.
+- `footer` — a node under the table, above the pager: a total, a note.
+- `loading` — skeleton rows in place of the body (the toolbar stays).
+- `error` — a danger Notice above the table (a failed read).
+- `emptyTitle` · `emptyBody` · `emptyAction` · `emptyIcon` — the state for
+  no rows at all. No matches has its own state with "Clear filters".
+- `mobile` — `"scroll"` (default): under 640px the table scrolls sideways
+  inside its own box; the page never does. `"cards"`: under 640px each row
+  is a card — the first shown column as its title, the others as
+  label/value pairs, with its checkbox and menu. Pick cards when rows are
+  read more than compared; scroll when columns are compared.
+- `cardTitle(row)` — the card's title instead of the first column (the
+  card then lists every shown column).
+- `variant` — `"outline"` (a bordered card; default) or `"plain"` (no
+  border, for a table already inside a `Card`).
+- `className` — layout around it (width, margin). Never colour.
+
+### Controlled or not — letting a server drive it
+
+Every piece of state has three props: the value, a `default…` and an
+`on…Change`. Pass only the default (or nothing) and the table keeps it.
+Pass the value and the table shows what you pass and calls `on…Change`
+with what the founder asked for; you set it back. Each is independent, so
+you can own just the page and leave the rest to the table.
+
+For a table too big for the browser, set `manual`: the table stops
+searching, filtering, sorting and slicing, `rows` is the current page, and
+`rowCount` is how many rows the server has. Own `search`, `filters`,
+`sort`, `page` and `pageSize`, re-read on each change, and give each facet
+its `options` with a `count` (`{ value, label, count }`), since the table
+cannot count rows it does not have. With `manual`, a bulk action's second
+argument, `ids`, is every selected id, including rows not on this page.
+
+```jsx
+const [q, setQ] = useState({ search: "", filters: {}, sort: [], page: 1, pageSize: 25 });
+// …read rows + total for q on the server (a Server Action, a route)…
+<DataTable manual rows={pageRows} rowCount={total} loading={pending}
+  search={q.search} onSearchChange={(search) => setQ((s) => ({ ...s, search }))}
+  filters={q.filters} onFiltersChange={(filters) => setQ((s) => ({ ...s, filters }))}
+  sort={q.sort} onSortChange={(sort) => setQ((s) => ({ ...s, sort }))}
+  page={q.page} onPageChange={(page) => setQ((s) => ({ ...s, page }))}
+  pageSize={q.pageSize} onPageSizeChange={(pageSize) => setQ((s) => ({ ...s, pageSize }))}
+  columns={COLUMNS} facets={[{ key: "status", options: statusCounts }]} />
+```
+
+The pure helpers the table uses are exported too — `processRows`,
+`searchRows`, `filterRows`, `sortRows`, `facetOptions`, `nextSort`,
+`groupRows`, `groupValueOf` and `useControllable` — so a surface can compute the same answer the table
+shows (a total over the filtered rows) without drawing it twice.
+
+## Example
+
+```jsx
+// components/Invoices.jsx — client: the table, the row sheet
+"use client";
+import { useState } from "react";
+import { updateRow } from "../lib/actions";
+import { Badge, Button, Sheet } from "./ui";
+import { FixtureNotice, useFixture } from "./parts";
+import { DataTable } from "./blocks/data-table";
+
+const TONE = { paid: "success", pending: "info", overdue: "danger", draft: "neutral" };
+const COLUMNS = [
+  { key: "number", header: "Invoice", sortable: true, hideable: false },
+  { key: "customer", header: "Customer", sortable: true },
+  { key: "status", header: "Status", sortable: true, cell: (r) => <Badge tone={TONE[r.status]}>{r.status}</Badge> },
+  { key: "amount", header: "Amount", sortable: true, align: "end", cell: (r) => `$${r.amount.toLocaleString()}` },
+  { key: "due", header: "Due", sortable: true },
+];
+const SAMPLE = [
+  { number: "INV-1001", customer: "Northwind", status: "paid", amount: 1200, due: "2026-10-01" },
+  { number: "INV-1002", customer: "Acme Ltd", status: "overdue", amount: 450, due: "2026-09-01" },
+];
+
+export default function Invoices({ invoices }) {
+  const fixture = useFixture(invoices, SAMPLE);
+  const [open, setOpen] = useState(null);
+  const markPaid = (rows) =>
+    Promise.all(rows.map((r) => updateRow({ source: "public.invoices", id: r.id, patch: { status: "paid" } })))
+      .then((all) => all.find((r) => r.ok === false) ?? { ok: true });
+  return (
+    <div className="grid gap-4">
+      {fixture.isFixture ? <FixtureNotice onClear={fixture.clear} /> : null}
+      <DataTable
+        label="Invoices"
+        noun="invoice"
+        rows={fixture.rows}
+        columns={COLUMNS}
+        facets={[{ key: "status", label: "Status" }]}
+        defaultSort={[{ key: "due", dir: "asc" }]}
+        bulkActions={[{ label: "Mark paid", icon: "check", onSelect: markPaid }]}
+        rowActions={(r) => [{ label: "Open", icon: "eye", onSelect: () => setOpen(r) }]}
+        onRowClick={setOpen}
+        rowTone={(r) => (r.status === "overdue" ? "warning" : null)}
+        toolbar={<Button variant="primary" icon="plus">New invoice</Button>}
+        mobile="cards"
+        emptyTitle="No invoices yet"
+      />
+      <Sheet open={Boolean(open)} onClose={() => setOpen(null)} title={open?.number}>
+        {/* the invoice's fields */}
+      </Sheet>
+    </div>
+  );
+}
+```
+
+### Details, groups and totals
+
+A budget: line items under departments, sorted within them, a subtotal
+per department, a total, the months scrolling under the line item.
+
+```jsx
+const MONTHS = ["jan", "feb", "mar"];
+const money = (n) => `$${n.toLocaleString()}`;
+const sumOf = (rows, key) => rows.reduce((s, r) => s + r[key], 0);
+const sums = (rows) => Object.fromEntries([...MONTHS, "total"].map((k) => [k, money(sumOf(rows, k))]));
+const COLUMNS = [
+  { key: "item", header: "Line item", sortable: true },
+  ...MONTHS.map((m) => ({ key: m, align: "end", sortable: true, cell: (r) => money(r[m]) })),
+  { key: "total", align: "end", sortable: true, cell: (r) => money(r.total) },
+];
+
+<DataTable label="Budget" noun="line item" rows={lines} columns={COLUMNS}
+  paginate={false} keyboard stickyFirstColumn
+  groupBy="department" groupOrder={["Engineering"]}
+  groupSummary={(rows) => `${money(sumOf(rows, "total"))} this quarter`}
+  groupFooter={sums} totals={sums}
+  renderExpanded={(r) => <p className="text-sm">{r.note}</p>}
+  canExpand={(r) => Boolean(r.note)}
+  defaultSort={[{ key: "total", dir: "desc" }]} />
+```
+
+### Buttons in the row
+
+Tasks whose actions depend on their state, the common ones as buttons in
+the row and the rest in the menu:
+
+```jsx
+<DataTable label="Tasks" noun="task" rows={tasks} columns={COLUMNS}
+  rowActions={(t) => [
+    t.status === "todo" && { label: "Start", icon: "play", inline: true, onSelect: (r) => setStatus(r, "doing") },
+    t.status === "doing" && { label: "Complete", icon: "check", inline: true, onSelect: (r) => setStatus(r, "done") },
+    { label: "Delete", icon: "trash", tone: "danger", inline: true, onSelect: remove },   // async, may return { ok: false, error }
+    { label: "Copy ID", icon: "copy", onSelect: copyId },
+  ]} />
+```
+
+`setStatus` and `remove` return a promise of `{ ok }`, as a Server Action
+does; a failure is said above the table.
+
+## What it will not do
+
+- Edit a cell in place: open the row (`onRowClick`) in a `Sheet`.
+- Fetch: rows come in as props; with `manual` you read each page.
+- Collapse a group, pin more than the first column, resize or reorder
+  columns, or virtualise thousands of rows — page them (`manual`)
+  instead.
+- Colour a column: a cell says what it means with kit parts (`Badge`,
+  `StatusDot`); a row's tone is `rowTone`, and only for status.
+
+A table it cannot be is your own component in `components/`, built from
+the kit's `Table` parts — not an edit to this block. Its files are fixed:
+`npm run check` refuses a change, and `makersclaw add data-table` restores
+them.
+
+## Credits
+
+The row buttons and the orders example follow blocks.so
+(https://github.com/ephraimduncan/blocks, MIT) and Creative Tim UI
+(https://github.com/creativetimofficial/ui, MIT); this is a rewrite on the
+Makersclaw kit, not their code.

package/registry/blocks/data-table/block.json

@@ -0,0 +1,10 @@
+{
+  "name": "data-table",
+  "title": "Data table",
+  "description": "Records as a table the founder can work: sort by a column (shift for several), search every column, faceted filters with counts, column visibility, row selection with a bulk-actions bar, a menu per row or its first actions as buttons in the row (async, with a spinner and a failure notice), row click, pagination with a page size, loading, empty and no-matches states, and cards on a phone. Opt in to expandable rows, row groups with subtotals, an aligned totals row, arrow-key navigation and a sticky first column. Client-side over rows, or driven by a server.",
+  "useWhen": "A list of records to scan, find, sort and act on: invoices, customers, orders, leads, users, tickets. Not for records that move through stages (a board), a few key numbers (stats), or a grid of cards whose picture matters more than its columns.",
+  "tags": ["table", "data", "records", "list", "grid", "sort", "filter", "search", "facets", "select", "bulk", "pagination", "columns", "crud", "expand", "group", "subtotal", "totals", "keyboard", "sticky", "row actions", "inline actions", "orders"],
+  "exports": ["DataTable", "useControllable", "processRows", "sortRows", "searchRows", "filterRows", "facetOptions", "nextSort", "groupRows", "groupValueOf"],
+  "files": ["index.js", "data-table.jsx", "model.js"],
+  "requires": []
+}