@ai-matrx/records-ui 0.16.0 → 0.28.0

package/CHANGELOG.md

@@ -1,5 +1,320 @@
 # Changelog — @ai-matrx/records-ui
 
+## 0.28.0
+
+**The publish canary installs every peer this package declares.** It named
+`react` and `react-dom` by hand, so the day a THIRD peer arrived (`recharts`,
+with `ChartBlock`) the published bundle imported something no consumer had
+been given and `import * as ui from "@ai-matrx/records-ui"` threw
+`ERR_MODULE_NOT_FOUND` — the canary was right and the whole publish stopped
+(run 35513820597). The peer list is read from the manifest, and the peers are
+installed in a pass of their own so each brings its own peers (`react-is` is
+`recharts`'). 0.27.0 was tagged and never published; its tag was left where it
+is.
+
+**A first-time admin could not make a table, and the gate could not see it.**
+
+Creating one showed a red refusal and made a table anyway; that table opened with
+no grid; the saved-views table behind every table page was itself unusable. One
+cause, in three places: a Field is a record (REC-25), so this package wrote one
+through the ordinary write door — and `custom._field_class_guard` refuses that
+row outright (23514 / FLD-13, "a column of a table is stored as a field, and this
+one says record"). Measured on the published screens (0.16.0) on 2026-09-20: four
+tables in one organization, every one declaring a column NAME with no Field row
+behind it.
+
+- **`systemTable.ts` goes through the declare doors.** `declare` and
+  `addMissingFields` use `custom.field_declare`; the shape reconciliation uses
+  `custom.field_update`, which converts the values a behaviour change orphans and
+  writes the migration row — `record_update` wrote the two keys onto the document
+  and did none of it. `addMissingFields` no longer patches the Table's own
+  `fields` list: that is the door's job, and a client doing it separately is how a
+  Table came to declare a column nothing backed.
+- **`records_ui_view` is why the grid was empty.** Its nine columns were refused,
+  so `ensureSystemTable` failed on every load, `ViewBar` could never read or seed
+  a view, and every table page in the organization read "Waiting for <name>'s
+  views" over an empty frame.
+- **`ensureSystemTable`'s in-flight claim was never released on success**, which
+  turned a race guard into a permanent cache: after the first declaration, every
+  later call returned before the two reconciliation paths ran, so a package table
+  could not grow a column in the session that made it.
+- **Creating a table is ONE act from the person's side.** A table that could not
+  take all of its columns is taken back, newest first, and a take-back that itself
+  fails SAYS SO and says what to do. Never a red sentence beside a table.
+- **`declareTable` hands back the Home it made** (REC-14), so the caller that
+  made it can tidy it up.
+- **`fieldDeclarationFor` carries everything the person said** — a list's choices,
+  a money column's unit, a date's day-or-day-and-time, a relation's target. Without
+  `options` the door refuses a choice list outright.
+- **`TableSettings`' reorder goes through `custom.field_update`**, which is the
+  door for a field's own settings and the one that asks `admin` on the TABLE.
+
+**A table with no columns is a real state, and it drew nothing at all.** The grid
+now says so — "This table has no columns yet" — with the one control that ends it,
+present for somebody who may change the table's shape and ABSENT with the ladder's
+own reason for everybody else.
+
+**The records are never held back by the bookkeeping.** `TablePage` always has a
+view: the saved one when `ViewBar` has it, the unsaved default until then, with a
+line saying the layout is not being kept yet. One table's plumbing can no longer
+decide whether another table's data is visible.
+
+**The gate now walks the first thing anybody does.** `demo/first-time-journey.ts`
+is one walk driven twice — recorded real-door answers in `demo/deterministic.test.tsx`,
+the real doors in `demo/live-smoke.test.tsx`: declare a table with no columns,
+declare one with three columns of three different kinds, write a record, read it
+back, see it in the page read, grow a package-owned table, and delete everything.
+Red against the old code on both halves.
+## 0.26.0 — 2026-09-20
+
+**The owner's side of the client portal: who signs in from outside, and exactly
+what they see.**
+
+The portal doors could be called from 0.15.0 of `@ai-matrx/records`, and there
+was no screen. `PortalsPanel` is that screen, and it is a RAIL ON THE TABLE'S
+OWN PAGE beside its forms and its notifications — never a Portals area of the
+app, for the same reason a form is not one: a portal is a way IN to Tables, so
+it is reached from a Table.
+
+- **The portals over this organization** — title, public address, how many
+  Tables, and the two numbers kept apart: signed in, and invited and waiting.
+  Adding them together is how an owner comes to believe a client is looking at
+  something they cannot reach.
+- **One portal opened** — each exposed Table with the relation Field that makes
+  a record theirs (`names_via`), the fields they see, the fields they may
+  change, whether they may comment, and the most they are ever conveyed. Each
+  person with which of the three states they are in, in words.
+- **Invite** — a picker over the portal's own client Table (a portal principal
+  IS one of those rows, so a client cannot be typed) and an email. It passes no
+  user id, and it shows the door's own sentence afterwards: they get access the
+  moment they follow the link, and until then the row holds nothing.
+- **Remove their access** — the consequence is named BEFORE the click, by name:
+  this person can no longer sign in to this portal, and the records that named
+  their client stop reaching them. A generic "Are you sure?" fails this repo's
+  law. Afterwards the door's own past-tense sentence is shown.
+- **View as this client** — `custom.portal_preview`'s answer, with a line saying
+  plainly that it is the same question their own screen asks. For somebody who
+  has not signed in, the door's refusal is shown rather than an empty list: an
+  empty list reads as "they see nothing" when the truth is they hold nothing yet.
+- **Copy the portal's link** — through `portalPath`, and it shows the address to
+  copy by hand when a browser refuses the clipboard.
+
+`PortalCardView` is exported as well: it takes a `PortalCard` and two callbacks
+and holds no client at all, which is how `demo/portals-panel.test.tsx` mounts it
+BARE in the blocking gate against a recorded real `custom.portal_card` answer
+(`demo/fixtures/portal-card.json`, re-recordable with
+`demo/record-portal-card.mjs`) with the real `custom.portal_preview` answers,
+including that door's own refusal.
+
+**Consumer action:** none required. A host that mounts `TablePage` gets the new
+"Portals" rail with no change; a host that assembles its own page can mount
+`PortalsPanel` anywhere it mounts `FormsPanel`. `RecordsUiHost.publicOrigin` is
+what makes the copied address one a client can actually open.
+
+## 0.21.0
+
+**ONE dashboard object, one call, and every number clicks through to the records
+it counts.**
+
+`DashboardCanvas` kept its dashboards as rows of a package-owned
+`records_ui_dashboard` Table — a second store the agent could not reach and the
+database never validated, sitting beside the presentation-kernel dashboard that
+`dashboard_propose` writes and `custom.dashboard_run` runs. It now reads
+`custom.dashboards`, runs `custom.dashboard_run` and saves with
+`custom.dashboard_declare`: the same three doors the agent uses. `DASHBOARD_TABLE`,
+`dashboardDocument`, `dashboardFromRecord` and the seeding are gone, replaced by
+one mapper each way — `dashboardFromSummary` / `dashboardDeclareArgs`, and
+`specFromBlock` / `blockFromSpec` for a single block. `ChartKind` IS the store's
+`DashboardBlockKind`; there is no second closed set of shapes.
+
+**ONE call for the whole canvas.** Every block used to make its own
+`custom.record_aggregate` request. The door answers all of them in one snapshot,
+under the caller's own principal, each with its own `ms` — so eight blocks cannot
+disagree about what the last hour did, and eight round trips are one. Each block
+shows the milliseconds it took. A block the store REFUSED prints the store's own
+sentence, classified by its SQLSTATE through the same formatter as every other
+refusal, and its siblings still draw.
+
+**The platform's chart library.** Bars, columns, lines and donuts are Recharts
+now, not hand-cut `<rect>` and `<circle>`, with the app's own conventions:
+`--color-<key>` variables from a `ChartConfig`-shaped map, semantic tokens only
+(so light and dark both come out right with no second palette), and the app's
+tooltip and legend markup. There is no `ResponsiveContainer` — the box is
+measured with a `ResizeObserver` and falls back to a sane width when there is no
+measurement, so a chart always has real dimensions and a component test proves
+what a person sees. `number` and `table` stay a big number and an HTML table.
+
+**Every number clicks through.** A bar, a slice, a table row and the big number
+all open the records they counted, through the new `openRecords` host port, with
+the block's own filter and the clicked group merged. Every group is also a real
+button, so the chart works from a keyboard.
+
+**A re-ask box.** One input at the top of the canvas — "break it down by owner" —
+through the new `onReask` host port, which the host drives with
+`dashboard_propose` on the server's `records` tool.
+
+**A Dashboards tab** on `TablePage`, beside the views of the same records.
+
+### Consumer action
+
+- `recharts` is a PEER dependency now (`>=3.0.0`). A host already on Recharts 3
+  provides the one copy; a host that is not must add it.
+- `DashboardCanvas` no longer takes `seed`. Dashboards come from
+  `custom.dashboards`; an agent writes one with `dashboard_propose`.
+- `ChartBlock` takes `{ block, subject }` — one `DashboardBlockResult` out of the
+  canvas's run — instead of `{ spec }`. It opens no door of its own.
+- `DASHBOARD_TABLE`, `dashboardDocument`, `dashboardFromRecord` and
+  `DashboardSpec` are removed.
+- Bind `openRecords` for click-through and `onReask` for the re-ask box; unbound,
+  each says in one sentence what to bind rather than drawing a dead control.
+- Needs `@ai-matrx/records` 0.14.0 or above.
+## 0.20.0 — 2026-09-20
+
+**The store's grid inherits the spreadsheet, instead of re-implementing it.**
+
+The app's `/data` route had grown colors, rules, formats and a wide-table
+layout, and none of it could reach the record store: that work lives in the app,
+and this package's Grid renders through `@ai-matrx/design-system`'s data table.
+The capabilities moved into that table (design-system 0.22.0); this release is
+the store's half.
+
+- **`presentation.ts`** — how a table LOOKS, as one document: `style` (color by a
+  column, live rules, manual highlights), `formats` (per-column overrides) and
+  `frozen` (the columns that stay while the rest scrolls). It lives on the SAVED
+  VIEW, because two people read one table two ways and neither reading is a fact
+  about the records — and it lives on a RECORD, not a new column, which is why
+  this needed no migration and why an agent sets it through the same
+  `record_write` it uses for everything else.
+- **A Field's money is right with nothing configured.** `formatForField` reads
+  the Field's OWN declaration — a currency parity type and its unit, a percent, a
+  datetime's `config.kind` — so `$1,250.50` and `45%` appear on a table nobody
+  has ever styled. A view's `formats` only OVERRIDES that. A relation, a person
+  or a choice keeps its own control rather than being handed to a text formatter.
+- **`RecordValue` and `GridCell` take a `format`.** A cell renderer beats
+  `MatrxColumnDef.format` — the table hands the cell over and steps back — so a
+  column that declared `currency` was showing a raw `1250.5` under its own
+  right-aligned header. Both now ask the primitive's formatter for the text, so
+  the read view and the table can never disagree about a number.
+- **Color-by never does nothing.** The store keeps a list column's choices as
+  records of another Table and this grid has not read their colors, so a value's
+  color is derived from the value itself — same word, same color, always — rather
+  than leaving a setting a person just changed with nothing to show for it.
+- **`Grid` takes `presentation`**, `ViewSwitcher` passes the open view's, and
+  `SavedViewSpec` / the `records_ui_view` Table carry it.
+
+### Fixed — a column could not be declared at all
+
+`addFields` wrote each Field as a plain record into the Field kernel Table, and
+the store now refuses that out loud (FLD-13, `23514`): *"a column of a table is
+stored as a field, and this one says record"*. Every table made through
+`declareTable` — the create path AND import — failed at its first column. It
+goes through `custom.field_declare` now, which is also what derives a parity
+type, makes a choice Table for a list column, and stamps the auto Rules a url or
+a percent carries; every column made the old way was thinner than one made
+through the field panel.
+
+### Consumer action
+
+None. `presentation` is optional and its absence is today's behavior.
+
+
+## 0.19.1
+
+**The progress bar and the count beside it said different things.** One question
+at a time, "1 of 4" is a POSITION, and the bar was measuring ANSWERS — so on the
+first question the count said one and the bar sat at zero: an empty sliver in a
+tinted track, which reads as either full or broken. Found by rendering the public
+form, not by reading it. Typeform's bar advances as you move through the form,
+and now so does this one. On a single page there is no position, so it keeps
+measuring what it can: how much is answered.
+
+
+## 0.19.0
+
+**The choice picker reads a document from any era, and writes the contract.**
+`OptionControl` compared the cell to `option.id` and wrote `option.id`. A choice
+value is now the option's own stable key and the read doors hand back the LABEL,
+so a picker that compares against the id shows nothing selected. It now uses
+`isTheChosen` from `@ai-matrx/records` — which recognises a choice by its key,
+its label or its option id — and writes `optionKey(option)`, for both the single
+and the multi control.
+
+`scalarText` is unchanged and did not need to change: it resolves a value
+through the label provider only when the value LOOKS like an id, so a label
+falls through and renders as itself.
+
+**Consumer action:** none beyond taking 0.19.0 with `@ai-matrx/records` 0.13.0.
+
+
+## 0.18.0
+
+**A person can switch off a notification an agent switched on.** "Make me an
+intake form that tells me when a new patient arrives" creates a subscription
+Rule, and until now nothing in any screen could see it, let alone stop it: the
+only reader was `custom.agg_subscriptions`, which is the notifier's and is not
+client-callable. `SubscriptionsPanel` is the owner's side — what this table is
+telling you about, on which channel, how often, and one switch — and it opens in
+the table's own rail beside its Forms, because a subscription watches a Table.
+
+A row the store says you may not mute carries no switch at all rather than a
+greyed one, and says whose it is. "Off" is the store's own word: muting is
+honoured inside the single reader every consumer goes through, so a screen can
+never say a subscription is off while it keeps firing.
+
+### Consumer action
+
+None — `TablePage` grew the rail. Needs `@ai-matrx/records` 0.12.0 or above for
+`client.subscriptions` and `client.subscriptionMute`.
+
+
+## 0.17.0
+
+**There is one Form object, and it is the one with the link.** `FormBuilder` kept
+its own form records in a package-owned `records_ui_form` Table — a second form
+with no public link, no accept Rule and no notify Rule, sitting beside the
+`custom.anon_form` one that `form_propose` writes and a stranger actually
+answers. Two objects, one name, nothing reconciling them: a person tweaked one
+form and published the other. The builder now reads `custom.forms` and writes
+`custom.form_declare` — the same two doors the agent uses — so a tweak changes
+the form at the link, and the screen says which link that is and whether it is
+answering.
+
+A save is a RE-STATEMENT of the whole form, because that is what the door is, so
+`formDeclareArgs` hands the accept Rule, the notify Rule, the cap and the slug
+straight back. A save that dropped `notify_rule_id` would silently stop the owner
+being told that somebody answered — which is most of what the person asked for.
+
+**The public form printed its own title twice**, once as the page's heading and
+again three millimetres below it in the runner's progress row — measured in a
+headless render, not reasoned about. The runner runs the form; the page names
+it. A host that mounts a form has a heading of its own, and a component that
+repeats it is a component deciding something it cannot see. `FormBuilder`'s
+preview pane grew the one line it needed.
+
+"New form" is back, and it starts by asking for the Table's first Field: the
+store refuses a form that asks nothing, and it is right to — a form with no
+questions is a link to an empty page.
+
+### Consumer action — BREAKING, and it is three names
+
+`FORM_TABLE`, `formDocument` and `formFromRecord` are gone, with the second store
+they served. `SavedForm.version` is gone too (`custom.anon_form` has no record
+version); `SavedForm` now carries `state`, `slug`, `submissionCap`,
+`quarantineRuleId` and `notifyRuleId`. If you mapped forms yourself, the two
+directions are `formFromSummary(summary)` and `formDeclareArgs(form)`.
+
+## 0.16.1
+
+**`FormSubmitOutcome` is exported.** It is the return type of
+`FormRunnerProps.onSubmit`, so a host supplying its own submit could not type
+its own handler: matrx-frontend's `PublicFormRunner` failed `tsc` on 0.16.0 with
+TS2459, "declares it locally, but it is not exported". A public surface is every
+type a consumer has to name.
+
+### Consumer action
+
+None beyond importing it if you implement `onSubmit`.
+
 ## 0.16.0
 
 **The grid never draws a row before it knows what the person may do.** My own