@vantage-ui/client 0.0.0-stage → 0.4.3

package/skills/vantage-client/references/react.md

@@ -0,0 +1,242 @@
+# React
+
+Import the bindings from `@vantage-ui/client/react`. React 18 or later.
+
+## The provider, and the connection's states
+
+`VantageProvider` makes `db` available to `useVantage()`. With a `fallback`,
+its children wait for `db.ready`: the `instant` entities loaded, or a final
+refusal. One component can serve as the fallback and as a gate that
+explains `refused` and `protocol_mismatch` once the children show:
+
+```tsx
+// test: react#provider
+// continues from SKILL.md's Connect: db; App is your app's root component
+import { VantageProvider, useConnection } from "@vantage-ui/client/react";
+import type { ReactNode } from "react";
+
+function ConnectionGate({ children }: { children?: ReactNode }) {
+  const { status, error } = useConnection();
+  if (status === "refused") return <p role="alert">Sign-in refused: {error}</p>;
+  if (status === "protocol_mismatch") return <p role="alert">This page is out of date. Reload it. ({error})</p>;
+  return children ?? <p>Connecting…</p>;
+}
+
+function Root() {
+  return (
+    <VantageProvider db={db} fallback={<ConnectionGate />}>
+      <ConnectionGate>
+        <App />
+      </ConnectionGate>
+    </VantageProvider>
+  );
+}
+```
+
+`useConnection()` returns `{ status, halted, error, seq, principal }`;
+`halted` is true once `refused` or `protocol_mismatch`. `closed` is
+transient (the client reconnects); show it as a hint, not an error. A
+sign-in form shown for `refused` stores the new token and calls
+`useVantage().reconnect()`; the gate shows the children again once the
+connection opens (SKILL.md, Connection states).
+
+## observer
+
+`observer(Component)` re-renders a component when anything it read during
+render changes: a field, a collection's members, a reference's value. It
+re-renders on nothing else.
+
+```tsx
+// test: react#collection
+import { observer, useCollection, useVantage } from "@vantage-ui/client/react";
+import type { Schema } from "./vantage.gen";
+
+const OpenIssues = observer(() => {
+  const db = useVantage<Schema>();
+  const { items, loadState, error } = useCollection(db.issues.where({ status: "open" }));
+  if (error) return <p role="alert">{error}</p>;
+  if (loadState === "loading") return <p>Loading…</p>;
+  return <ul>{items.map((issue) => <li key={issue.id}>{issue.title}</li>)}</ul>;
+});
+```
+
+`useCollection` returns `{ items, loadState, total, totalExact, length, error }`.
+Build the collection inline, as above: the same description is the same
+object, so it needs no `useMemo`.
+
+## Windows
+
+For virtualised lists, `useWindow(collection, start, count)` gives the rows
+`start..start+count`. Moving `start` moves the server's window; rows stay
+on screen until the new ones arrive. Size the virtualiser from
+`page.length`, show it as a count only when `page.lengthExact`, and use
+`page.settled` to tell "still loading" from "no rows here".
+
+```tsx
+// test: react#window
+import { observer, useVantage, useWindow } from "@vantage-ui/client/react";
+import type { Schema } from "./vantage.gen";
+
+const IssueRows = observer(({ start }: { start: number }) => {
+  const page = useWindow(useVantage<Schema>().issues.sort("created_at", "desc"), start, 50);
+  if (page.error) return <p role="alert">{page.error}</p>;
+  return <>{page.items.map((issue, i) => <div key={start + i}>{issue?.title ?? "…"}</div>)}</>;
+});
+```
+
+## One record
+
+`useRecord(reference)` returns `{ value, status, error }`. `status` is
+`none`, `loading`, `loaded`, `missing` or `error`; `error` holds the
+server's message when it refused the record. Unlike collections, each
+`ref()` call is a new reference, so keep it stable with `useMemo`:
+
+```tsx
+// test: react#record
+import { useRecord, useVantage } from "@vantage-ui/client/react";
+import { useMemo } from "react";
+import type { Schema } from "./vantage.gen";
+
+function IssueTitle({ id }: { id: string }) {
+  const db = useVantage<Schema>();
+  const ref = useMemo(() => db.issues.ref(id), [db, id]);
+  const { value, status, error } = useRecord(ref);
+  if (status === "error") return <p role="alert">{error}</p>;
+  if (status === "missing") return <p>No issue {id}</p>;
+  return <h1>{value?.title ?? "…"}</h1>;
+}
+```
+
+`useHydrated(target, keys?)` suspends until a model's references, a
+reference or a collection have loaded; wrap the component in `<Suspense>`.
+It also stops suspending when the server refuses the load or the
+connection halts: the collection's `error`, or the reference's `error`
+(with `status: "error"`), then holds the message.
+
+## Actions
+
+`useAction(fn)` wraps an action for a button: `run`, `pending`, and the last
+`error`. Call row actions on the model inside the function, so `this` is
+kept:
+
+```tsx
+// test: react#action
+import { observer, useAction } from "@vantage-ui/client/react";
+import type { Issues } from "./vantage.gen";
+
+const CloseButton = observer(({ issue }: { issue: Issues }) => {
+  const close = useAction(() => issue.close_issue({ resolution: "fixed" }));
+  if (!issue.$actions.includes("close_issue")) return null;
+  return (
+    <>
+      <button disabled={close.pending} onClick={() => void close.run()}>Close</button>
+      {close.error && <span role="alert">{close.error.message}</span>}
+    </>
+  );
+});
+```
+
+## Runs
+
+`useRun(db.run.<action>, { key? })` gives the component one run, idle until
+`start`. With `key`, its id is kept in the tab's `sessionStorage`, per
+action: after a page reload the same component attaches to the run again
+and continues from its current state. A stored run the server no longer has
+(expired, or not yours) is forgotten and the run is `idle` again;
+`run.forget()` does the same on purpose, to stop showing a finished run. A
+new `key` is a new run.
+`useShared(run, "name")` reads one variable, or gives `[value, set]` for an
+input; only components that read a variable re-render when it changes.
+`useRunMessage(run, "name", fn)` calls `fn` for each message while mounted,
+in order; `"vantage.notify"` is the body's `notify(text)` (`m.text`).
+
+```tsx
+// test: react#run
+import { useRun, useRunMessage, useShared, useVantage } from "@vantage-ui/client/react";
+import type { Schema } from "./vantage.gen";
+
+// notifyUser is your UI's
+function Triage({ project }: { project: string }) {
+  const db = useVantage<Schema>();
+  const triage = useRun(db.run.triage, { key: `triage:${project}` });
+  const progress = useShared(triage, "progress");
+  const total = useShared(triage, "total");
+  const [confirmed, setConfirmed] = useShared(triage, "confirmed");
+  useRunMessage(triage, "flagged", (m) => notifyUser(`${m.issue} has no assignee`));
+  useRunMessage(triage, "vantage.notify", (m) => notifyUser(m.text));
+  if (triage.status === "idle") return <button onClick={() => triage.start({ project })}>Triage</button>;
+  if (triage.status === "running" && !confirmed) return <button onClick={() => void setConfirmed(true)}>Confirm {total} issues</button>;
+  return <progress value={progress} max={total || 1} />;
+}
+```
+
+`useRunMessage` hears only the messages that arrive while the component is
+mounted. After a page reload, the run attaches, and the messages sent
+before then come back as history in `run.messages`, not as events. A list
+that has to survive a reload (the issues a run flagged) is therefore built
+from `run.messages`, in an `observer` component so that it re-renders as
+messages arrive. Each entry is
+`{ name, payload }`, oldest first. The list holds the run's last 100
+messages, the framework's `vantage.notify` and `vantage.log` included.
+Compare `name` to pick out one kind of message; the comparison narrows
+`payload` to that message's type:
+
+```tsx
+// test: react#run-history
+import { observer, useRun, useVantage } from "@vantage-ui/client/react";
+import type { Schema } from "./vantage.gen";
+
+const Flagged = observer(() => {
+  const db = useVantage<Schema>();
+  const triage = useRun(db.run.triage, { key: "triage:JIR" });
+  const flagged = triage.messages.flatMap((m) => (m.name === "flagged" ? [m.payload.issue] : []));
+  if (triage.status === "idle") return <button onClick={() => triage.start({ project: "JIR" })}>Triage</button>;
+  return <ul>{flagged.map((issue) => <li key={issue}>{issue} has no assignee</li>)}</ul>;
+});
+```
+
+Forms, confirms and multi-step wizards are your components: collect what
+the action needs, then `start` it once with the values.
+
+`run.start(args)` always begins a new run with a new id; it never attaches.
+On a finished run (`done`, `failed`, `cancelled`) that is "run it again":
+no `forget()` first. With a `key`, the new id replaces the stored one. A
+page reload shows the last run, finished or not, until the next `start`.
+On a running run, `start` switches the handle to the new run and leaves
+the old one running on the server; `cancel()` it first if it should stop.
+
+`check.start()` with no argument type-checks when the action declares no
+args (the generated `args` is `{}`), or when all its args are optional;
+`start({})` means the same. When an arg is required, the argument is
+required too, and leaving it out is a type error.
+
+```tsx
+// test: react#run-again
+import { useRun, useShared, useVantage } from "@vantage-ui/client/react";
+import type { Schema } from "./vantage.gen";
+
+function CheckOverdue() {
+  const db = useVantage<Schema>();
+  const check = useRun(db.run.check_overdue, { key: "desk" });
+  const overdue = useShared(check, "overdue");
+  const busy = check.status === "starting" || check.status === "running";
+  return (
+    <>
+      <button disabled={busy} onClick={() => check.start()}>Check overdue loans</button>
+      {check.status === "done" && <p>{overdue} overdue</p>}
+    </>
+  );
+}
+```
+
+## Drafts in forms
+
+`useServo(model)` gives an edit draft that re-renders the form as it
+changes: set fields, read `$isDirty`, `$status` and `$errors`, then
+`$flash()`.
+
+## Other hooks
+
+- `usePreloadOnIntent(load)`: starts `load` when the pointer rests on an
+  element, so the data is there by the click.
+- `useLive(fn, deps)`: any derived value, recomputed when what it reads changes.

package/skills/vantage-client/references/testing.md

@@ -0,0 +1,173 @@
+# Testing
+
+`@vantage-ui/client/testing` has `MockServer`: an in-memory vantage-server
+that speaks the same frames, with no network. Collections filter, sort,
+window and follow `via` like the real one; writes broadcast `changed` and
+move collection membership. Use it in unit tests and Storybook.
+
+## With the generated schema
+
+```ts
+// test: testing#generated
+import { createTestVantage } from "@vantage-ui/client/testing";
+import { schema, type Schema } from "./vantage.gen";
+
+const { db, server } = createTestVantage<Schema>(schema, {
+  tables: { issues: [{ id: "JIR-1", title: "Login fails", status: "open", project: "JIR" }] },
+  actions: { "issues.close_issue": () => ({ status: "done" }) },
+});
+await db.ready;
+const issue = await db.issues.ref("JIR-1").load();
+server.upsert("issues", { id: "JIR-1", title: "Login fails on Safari" }); // someone else's edit
+```
+
+Fixtures also take `available` (which row actions a record offers, standing
+in for `when:`), `validate` (refuse writes with a message or field errors),
+`protocol` (the version the mock speaks) and `refuseHello` (refuse every
+token with a message).
+
+A third argument passes client options, such as `{ token: "test" }`.
+
+## Runs
+
+An action's handler is its body: `(row, args, run)`. Its return value (or
+what its promise resolves to) is the run's `result`, and a row action's
+returned object is applied to the row. `run` stands in for the body's run
+vocabulary: `run.set(name, value)` sends a state patch, `run.wait(name)`
+resolves once an input is set, `run.emit(name, payload)` and
+`run.notify(text)` send messages. `server.runs` holds every run by id, with
+its `action`, `args`, `state` and `status`:
+
+```ts
+// test: testing#runs
+// continues from "With the generated schema": createTestVantage, schema, Schema
+import { expect } from "vitest";
+
+const triage = createTestVantage<Schema>(schema, {
+  actions: {
+    triage: async (_, args, run) => {
+      run.set("total", 1);
+      await run.wait("confirmed");
+      run.emit("flagged", { issue: "JIR-1" });
+      return `triaged ${args.project}`;
+    },
+  },
+});
+await triage.db.ready;
+const run = triage.db.run.triage.start({ project: "JIR" });
+await run.set("confirmed", true);
+expect(await run.done).toEqual({ ok: true, value: "triaged JIR" });
+expect(triage.server.runs.get(run.id)?.args).toEqual({ project: "JIR" });
+```
+
+Fixture `actions` are keyed by the action's wire name, the name `db.run`
+uses: a project action's key with dashes turned into underscores
+(`check_overdue` for `action/check-overdue.yaml`), and `<entity>.<name>`
+for a row action. The YAML key with dashes (`"check-overdue"`) works too;
+naming one action both ways throws. Type a handler declared on its own
+with `ActionHandler`, and its `run` parameter with `MockRunControl`:
+
+```ts
+// test: testing#action-names
+// continues from "With the generated schema": createTestVantage, schema, Schema
+import { type ActionHandler, type MockRunControl } from "@vantage-ui/client/testing";
+import { expect } from "vitest";
+
+const checkOverdue: ActionHandler = async (_, __, run: MockRunControl) => {
+  run.set("overdue", 3);
+  return "3 tools are overdue";
+};
+const desk = createTestVantage<Schema>(schema, { actions: { check_overdue: checkOverdue } });
+await desk.db.ready;
+const run = desk.db.run.check_overdue.start({});
+expect(await run.done).toEqual({ ok: true, value: "3 tools are overdue" });
+expect(run.state.overdue).toBe(3);
+```
+
+`server.refuse("run_set", message)` refuses input writes, so a test can
+check the rollback; `run_set` of a non-input or a wrong type is refused as
+the real server does. `run.update({ a, b })` sends several variables in one
+patch, as the server's throttle does. The fixture `eager: true` starts a
+handler before the invoking socket follows the run, as vantage-server does,
+so what it sends first arrives inside the first snapshot; `features: []`
+is a server without runs.
+
+## Without generated types
+
+`MockServer.withTable` builds a one-entity schema from the rows' keys.
+`db.table(name)` reaches any entity by name:
+
+```ts
+// test: testing#one-table
+import { MockServer, createTestVantage } from "@vantage-ui/client/testing";
+
+const server = MockServer.withTable("issues", [{ id: "1", title: "First" }]);
+const { db } = createTestVantage(server, { token: "test" });
+const all = await db.table("issues").all.load();
+```
+
+## Refusals, held replies and resync
+
+The server-side events a test can cause:
+- `server.refuse(op, message)` answers every `op` frame (`open_table`,
+  `open_records`, `viewport`, …) with that error; `server.allow(op)` stops it;
+- `server.refuseWrites(message)` refuses every write, whether the client
+  sends it alone or batched with others; `server.allowWrites()` stops it;
+- `server.hold(op)` keeps `op` replies pending until `server.release(op)`;
+- `server.resync()` is an API reload: a new journal, every collection gone,
+  `resync` sent to every client;
+- `server.reload()` sends `reload` to every client, which calls its
+  `onReload`;
+- `server.invalidate(table)` is a coarse change: clients re-read the table;
+- `server.opened` lists every collection a client opened (table, `where`,
+  `sort`, …), refused ones too; `server.count(op)` counts the frames
+  received, and `server.hellos` keeps every `hello`.
+
+Assert on what the page asked for through these, not by spying on the
+transport's frames:
+
+```ts
+// test: testing#opened
+// continues from "Without generated types": server, db
+import { expect } from "vitest";
+
+await db.table("issues").where({ title: "First" }).load();
+expect(server.opened.at(-1)).toEqual({ table: "issues", where: [["title", "eq", "First"]] });
+server.refuseWrites("issues: column `title` is not writable");
+const issue = await db.table("issues").ref("1").load();
+const saved = await issue!.patch({ title: "Renamed" });
+expect(saved.ok).toBe(false);
+```
+
+```ts
+// test: testing#refusal
+// continues from the previous block: server, db
+import { expect } from "vitest";
+
+server.refuse("open_table", "invalid column `x` is not filterable");
+const refused = await db.table("issues").where({ x: 1 }).load();
+expect(refused.error).toBe("invalid column `x` is not filterable");
+expect(server.count("open_table")).toBe(1); // a refusal is not retried
+```
+
+```ts
+// test: testing#resync
+// continues from "Without generated types": server, db
+import { expect } from "vitest";
+
+const rows = () => db.table("issues").all.map((r) => r.title);
+const settle = () => new Promise((resolve) => setTimeout(resolve, 5));
+await db.table("issues").all.load();
+server.setRows("issues", [{ id: "1", title: "First, renamed" }]); // the reloaded API's data
+
+server.hold("open_table"); // keep the reopen pending
+server.resync();
+await settle();
+expect(rows()).toEqual(["First"]); // still shown, no flash to empty
+server.release("open_table");
+await settle();
+expect(rows()).toEqual(["First, renamed"]);
+```
+
+`transport.drop()` (from `createTestVantage`'s result) simulates a lost
+connection; `transport.drop(1008, reason)` a refused one.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.