@loadbare/app 0.11.0 → 0.12.0

package/dist/server/lb-server.js

@@ -81,6 +81,23 @@ export function createHub(pages) {
                     `beginning with '${LB_RESERVED_PREFIX}' are reserved`);
             }
         }
+        // An update or a delete names its row by key, so its handler always
+        // knows which rows changed and can answer with a patch; removing a row
+        // never reorders the rest. Refreshing the whole set instead sends every
+        // row and places every row again, which moves the element the user is
+        // in. There is no case where that is the answer to either, so it is
+        // refused rather than warned about. An insert is not: where its row
+        // goes depends on the markup, which the server cannot see.
+        for (const [name, crud] of Object.entries(entry.requests.crud ?? {})) {
+            if (entry.queries[name]?.kind !== KIND_ROWS)
+                continue;
+            for (const request of ["rowUpdate", "rowDelete"]) {
+                if (crud[request]?.refresh.includes(name)) {
+                    throw new Error(`loadbare: page '${page}' refreshes '${name}' after its own ` +
+                        `${request}; return the changed rows in a patch instead`);
+                }
+            }
+        }
     }
     /**
      * Answers into response items, adding the kind and key each query

package/dist/server/lb-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"lb-server.js","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"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","sourcesContent":["// The server-side contract and the engine that runs it.\n//\n// This is the counterpart to core/lb-constants.ts: that file is the\n// vocabulary the browser writes, this one is the vocabulary the application\n// writes. The engine below is the whole of Loadbare on the server. It ships\n// no HTTP server, no router, and no data layer.\n\nimport type {\n  HubData,\n  HubRequest,\n  HubResponse,\n  HubResult,\n  Kind,\n  Patch,\n  RequestFields,\n  ResponseItem,\n  Row,\n} from \"../core/lb-types.js\";\nimport { isRowRequest } from \"../core/lb-types.js\";\nimport {\n  KIND_ROW,\n  KIND_ROWS,\n  LB_RESERVED_PREFIX,\n  REQUEST_ROW_DELETE,\n  REQUEST_ROW_INSERT,\n  REQUEST_ROW_UPDATE,\n  URL_COLUMN_PATH,\n  URL_QUERY,\n} from \"../core/lb-constants.js\";\n\n/**\n * Whatever the application hands the engine for the duration of one request.\n *\n * Loadbare declares it empty and never reads it. An application fills it in\n * by declaration merging, once, anywhere in its own source:\n *\n *     declare module \"@loadbare/app/server\" {\n *       interface HubContext {\n *         db: Db;\n *       }\n *     }\n *\n * That is why no type on this page takes a type parameter. The context is a\n * request-scoped handle — an authenticated database connection is the\n * expected case — so it is passed per call rather than held by the engine.\n * The page's query parms are the other expected member: a query that reads\n * one off the context takes no argument, and re-runs under `refresh` like\n * any other.\n */\nexport interface HubContext {}\n\n/**\n * A declared query: its kind, its key, and the run that answers it.\n *\n * Kind and key are properties of the name rather than of any one answer, so\n * they are declared here and never inferred from what comes back. The engine\n * sends both with every answer, so the markup repeats neither. Every query\n * has a key; an aggregate row answers with a constant one.\n *\n * Write one with `row()` or `rows()` below; nothing else builds one.\n */\nexport interface Query {\n  readonly kind: Kind;\n  readonly key: string;\n  readonly run: (ctx: HubContext) => HubResult | Promise<HubResult>;\n}\n\n/** A query that answers with one row, identified by its `key` column. */\nexport function row(\n  key: string,\n  run: (ctx: HubContext) => Row | Promise<Row>,\n): Query {\n  return { kind: KIND_ROW, key, run };\n}\n\n/**\n * A query that answers with all its rows, and therefore also their order.\n * Rows land by their `key` column: a row whose key is not in the answer is\n * gone.\n */\nexport function rows(\n  key: string,\n  run: (ctx: HubContext) => Row[] | Promise<Row[]>,\n): Query {\n  return { kind: KIND_ROWS, key, run };\n}\n\n/**\n * Only what changed, returned from a handler for a `rows` query. Rows named\n * here are added or updated, keys in `drop` are removed, and everything\n * unnamed is left alone — its contents, and its place in whatever order the\n * page is keeping.\n *\n * `Array.isArray` is what tells a patch from all rows, so a patch needs no\n * marker of its own and no column name is reserved to carry one.\n */\nexport function patch(change: { rows?: Row[]; drop?: unknown[] }): Patch {\n  const made = { ...change };\n  patches.add(made);\n  return made;\n}\n\n/**\n * Every object `patch()` made. A patch and a row are both plain objects, so\n * this is how the engine refuses a patch answering a `row` query.\n */\nconst patches = new WeakSet<object>();\n\n/**\n * A new row for `lb-url`, returned from a handler when only the handler can\n * know where the page belongs: the key of a row it inserted, or the absence\n * of one it deleted.\n *\n * A column other than `lb-path` is a query parm: set, or taken out when its\n * value is empty. With `lb-path` naming another page, the page is entered\n * with only the parms named here; otherwise every other parm is kept.\n *\n * The page then loads at the new URL in the same round trip, as a cold load\n * of it would, so the refresh set is not run and whatever else the handler\n * returned is dropped: both were answers for the URL the page is leaving.\n * This is Post/Redirect/Get without the redirect.\n */\nexport function url(columns: Record<string, string>): HubData {\n  return { [URL_QUERY]: { ...columns } };\n}\n\n/** The shape of a `<stub>.queries.ts` module. */\nexport type Queries = Record<string, Query>;\n\n/**\n * What a handler does, and which queries re-run once it has.\n *\n * `run` may also return answers of its own, which are laid over the\n * refreshed ones. That is how a patch reaches the browser: a query answers\n * for all its rows and cannot know why it re-ran, but the handler knows\n * exactly what it changed and can say only that.\n */\nexport interface Handler<R = RequestFields> {\n  run: (\n    ctx: HubContext,\n    request: R,\n  ) => void | HubData | Promise<void | HubData>;\n  refresh: string[];\n}\n\nexport type RowInsertHandler = Handler<{\n  key?: string;\n  values: Record<string, string>;\n}>;\n/** `values` holds only the columns being set, as an SQL UPDATE sets them. */\nexport type RowUpdateHandler = Handler<{\n  key: string;\n  values: Record<string, string>;\n}>;\nexport type RowDeleteHandler = Handler<{ key: string }>;\n\n/**\n * What the requests Loadbare provides do to one query, keyed by its name in\n * `Requests.crud`. A query with no entry here permits none of them: the wire\n * cannot reach anything the page has not published.\n *\n * Every key is the request name with the prefix stripped and the rest\n * camel-cased: `lb-row-insert` runs `rowInsert`.\n */\nexport interface Crud {\n  rowInsert?: RowInsertHandler;\n  rowUpdate?: RowUpdateHandler;\n  rowDelete?: RowDeleteHandler;\n}\n\n/**\n * The shape of a `<stub>.requests.ts` module.\n *\n * `onPageEnter` runs when the page loads, before its queries. It declares no\n * refresh set: the page's queries all run afterward, so whatever it changed\n * is already in the response.\n *\n * `handlers` holds the page's declared requests, by name. A name the page\n * did not declare is refused, so the wire cannot reach anything the page has\n * not published.\n *\n * `crud` holds what the requests Loadbare provides run, by query name.\n */\nexport interface Requests {\n  onPageEnter?: (ctx: HubContext) => void | Promise<void>;\n  handlers?: Record<string, Handler>;\n  crud?: Record<string, Crud>;\n}\n\n/** A page is three files sharing a stub; two of them are these. */\nexport interface Page {\n  queries: Queries;\n  requests: Requests;\n}\n\n/**\n * The page registry. The builder writes it from every `.requests.ts` and\n * `.queries.ts` it discovers — see docs/reference/builder.md.\n */\nexport type Pages = Record<string, Page>;\n\n/**\n * The engine. Both calls answer with response items. A request whose\n * handler returned `url()` answers with the `lb-url` item alone: the caller\n * builds a context at the new URL, calls `dataForPage` with it, and sends\n * the load beside the item. `hubRoutes` does exactly that.\n */\nexport interface Hub {\n  /** A page load: its `onPageEnter`, then all of its queries. */\n  dataForPage(page: string, ctx: HubContext): Promise<HubResponse>;\n\n  /** A request: run the handler its name picks, then the refresh set. */\n  runRequest(\n    page: string,\n    request: HubRequest,\n    ctx: HubContext,\n  ): Promise<HubResponse>;\n}\n\n/** The camel-cased `Crud` key of a request Loadbare provides. */\nconst CRUD_KEYS: Record<string, keyof Crud> = {\n  [REQUEST_ROW_INSERT]: \"rowInsert\",\n  [REQUEST_ROW_UPDATE]: \"rowUpdate\",\n  [REQUEST_ROW_DELETE]: \"rowDelete\",\n};\n\n/**\n * Build the engine over a set of pages. The pages are fixed at startup; the\n * context is not, and arrives with each call.\n */\nexport function createHub(pages: Pages): Hub {\n  // Names beginning with the reserved prefix are Loadbare's — its own query,\n  // the requests it provides — so an application cannot declare one.\n  // Refused at startup, because a name is a fact about the page and not\n  // about any request.\n  for (const [page, entry] of Object.entries(pages)) {\n    const declared = [\n      ...Object.keys(entry.queries),\n      ...Object.keys(entry.requests.handlers ?? {}),\n      ...Object.keys(entry.requests.crud ?? {}),\n    ];\n    for (const name of declared) {\n      if (name.startsWith(LB_RESERVED_PREFIX)) {\n        throw new Error(\n          `loadbare: page '${page}' declares '${name}', but names ` +\n            `beginning with '${LB_RESERVED_PREFIX}' are reserved`,\n        );\n      }\n    }\n  }\n\n  /**\n   * Answers into response items, adding the kind and key each query\n   * declared. An answer that disagrees with its declaration is a mistake in\n   * the application rather than a case to handle, and is left out: a page is\n   * better off missing one query than showing the wrong shape for it.\n   */\n  function items(page: string, data: HubData): HubResponse {\n    const out: ResponseItem[] = [];\n    for (const [name, result] of Object.entries(data)) {\n      const query = pages[page]?.queries[name];\n      if (!query) {\n        console.warn(`loadbare: page '${page}' declares no query '${name}'`);\n        continue;\n      }\n      const item: ResponseItem = {\n        query: name,\n        kind: query.kind,\n        key: query.key,\n      };\n      if (query.kind === KIND_ROW) {\n        if (Array.isArray(result) || patches.has(result)) {\n          console.warn(\n            `loadbare: query '${name}' is declared row but answered with ` +\n              `${Array.isArray(result) ? \"rows\" : \"a patch\"}`,\n          );\n          continue;\n        }\n        item.row = result as Row;\n      } else if (Array.isArray(result)) {\n        item.rows = result;\n      } else {\n        item.patch = result as Patch;\n      }\n      out.push(item);\n    }\n    return out;\n  }\n\n  /** Run queries by name, each answering with all its rows or its row. */\n  async function run(\n    page: string,\n    names: string[],\n    ctx: HubContext,\n  ): Promise<HubData> {\n    const data: HubData = {};\n    for (const name of names) {\n      const query = pages[page]?.queries[name];\n      if (!query) {\n        console.warn(`loadbare: page '${page}' declares no query '${name}'`);\n        continue;\n      }\n      const result = await query.run(ctx);\n      if (Array.isArray(result) !== (query.kind === KIND_ROWS)) {\n        console.warn(\n          `loadbare: query '${name}' is declared ${query.kind} but answered ` +\n            `with ${Array.isArray(result) ? \"rows\" : \"one row\"}`,\n        );\n        continue;\n      }\n      data[name] = result;\n    }\n    return data;\n  }\n\n  /**\n   * Run a handler, then its refresh set against the same context, laying\n   * what the handler itself returned over the refreshed queries — the\n   * narrower answer wins because it knows what actually changed.\n   *\n   * A handler that returned `url()` answers with the `lb-url` item alone.\n   * Loading the page there needs a context built at the new URL, and\n   * building one is the caller's.\n   */\n  async function settle(\n    page: string,\n    handler: Handler<never> | undefined,\n    request: RequestFields,\n    ctx: HubContext,\n    notFound: string,\n  ): Promise<HubResponse> {\n    if (!handler) {\n      console.warn(notFound);\n      return [];\n    }\n    const { [URL_QUERY]: moved, ...stated } =\n      (await handler.run(ctx, request as never)) ?? {};\n    if (moved !== undefined) {\n      const refused = refusal(moved);\n      if (refused === undefined) {\n        return [\n          {\n            query: URL_QUERY,\n            kind: KIND_ROW,\n            key: URL_COLUMN_PATH,\n            row: moved as Row,\n          },\n        ];\n      }\n      // The handler has already run, so the page still hears about it, by\n      // its refresh set, as if no row for lb-url had been returned.\n      console.warn(\n        `loadbare: page '${page}' returned ${URL_QUERY} ${refused}, ignoring it`,\n      );\n    }\n    return items(page, {\n      ...(await run(page, handler.refresh, ctx)),\n      ...stated,\n    });\n  }\n\n  return {\n    async dataForPage(page, ctx) {\n      const entry = pages[page];\n      if (!entry) {\n        console.warn(`loadbare: no page '${page}'`);\n        return [];\n      }\n      await entry.requests.onPageEnter?.(ctx);\n      return items(page, await run(page, Object.keys(entry.queries), ctx));\n    },\n\n    runRequest(page, request, ctx) {\n      const { name, ...fields } = request;\n      if (isRowRequest(name)) {\n        const query = fields.query ?? \"\";\n        return settle(\n          page,\n          pages[page]?.requests.crud?.[query]?.[CRUD_KEYS[name]!] as\n            Handler<never> | undefined,\n          fields,\n          ctx,\n          `loadbare: page '${page}' declares no ${CRUD_KEYS[name]} for '${query}'`,\n        );\n      }\n      return settle(\n        page,\n        pages[page]?.requests.handlers?.[name] as Handler<never> | undefined,\n        fields,\n        ctx,\n        `loadbare: page '${page}' declares no request '${name}'`,\n      );\n    },\n  };\n}\n\n/**\n * Why a returned row for `lb-url` cannot be used, or nothing when it can.\n *\n * A value is a string, as a control's is and a URL's is. At least one column\n * is named: a row naming none changes nothing.\n */\nfunction refusal(columns: unknown): string | undefined {\n  if (\n    typeof columns !== \"object\" ||\n    columns === null ||\n    Array.isArray(columns)\n  ) {\n    return \"that is not a row\";\n  }\n  const values = Object.values(columns);\n  if (values.length === 0) return \"naming no column\";\n  if (!values.every((v) => typeof v === \"string\")) {\n    return `holding a value that is not a string; write url({ name: \"...\" })`;\n  }\n  return undefined;\n}\n"]}
+{"version":3,"file":"lb-server.js","sourceRoot":"","sources":["../../server/lb-server.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,oEAAoE;AACpE,4EAA4E;AAC5E,4EAA4E;AAC5E,gDAAgD;AAahD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EACL,QAAQ,EACR,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,SAAS,GACV,MAAM,yBAAyB,CAAC;AAuCjC,yEAAyE;AACzE,MAAM,UAAU,GAAG,CACjB,GAAW,EACX,GAA4C;IAE5C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACtC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAClB,GAAW,EACX,GAAgD;IAEhD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CAAC,MAA0C;IAC9D,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC3B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAU,CAAC;AAEtC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,GAAG,CAAC,OAA+B;IACjD,OAAO,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,CAAC;AACzC,CAAC;AA+FD,iEAAiE;AACjE,MAAM,SAAS,GAA+B;IAC5C,CAAC,kBAAkB,CAAC,EAAE,WAAW;IACjC,CAAC,kBAAkB,CAAC,EAAE,WAAW;IACjC,CAAC,kBAAkB,CAAC,EAAE,WAAW;CAClC,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAY;IACpC,2EAA2E;IAC3E,mEAAmE;IACnE,sEAAsE;IACtE,qBAAqB;IACrB,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAG;YACf,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YAC7B,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC;YAC7C,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC;SAC1C,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,IAAI,IAAI,CAAC,UAAU,CAAC,kBAAkB,CAAC,EAAE,CAAC;gBACxC,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,eAAe,IAAI,eAAe;oBACvD,mBAAmB,kBAAkB,gBAAgB,CACxD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,oEAAoE;QACpE,uEAAuE;QACvE,wEAAwE;QACxE,sEAAsE;QACtE,oEAAoE;QACpE,oEAAoE;QACpE,2DAA2D;QAC3D,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;YACrE,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,SAAS;gBAAE,SAAS;YACtD,KAAK,MAAM,OAAO,IAAI,CAAC,WAAW,EAAE,WAAW,CAAU,EAAE,CAAC;gBAC1D,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC1C,MAAM,IAAI,KAAK,CACb,mBAAmB,IAAI,gBAAgB,IAAI,kBAAkB;wBAC3D,GAAG,OAAO,8CAA8C,CAC3D,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACH,SAAS,KAAK,CAAC,IAAY,EAAE,IAAa;QACxC,MAAM,GAAG,GAAmB,EAAE,CAAC;QAC/B,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,mBAAmB,IAAI,wBAAwB,IAAI,GAAG,CAAC,CAAC;gBACrE,SAAS;YACX,CAAC;YACD,MAAM,IAAI,GAAiB;gBACzB,KAAK,EAAE,IAAI;gBACX,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,GAAG,EAAE,KAAK,CAAC,GAAG;aACf,CAAC;YACF,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACjD,OAAO,CAAC,IAAI,CACV,oBAAoB,IAAI,sCAAsC;wBAC5D,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE,CAClD,CAAC;oBACF,SAAS;gBACX,CAAC;gBACD,IAAI,CAAC,GAAG,GAAG,MAAa,CAAC;YAC3B,CAAC;iBAAM,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBACjC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC;YACrB,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,GAAG,MAAe,CAAC;YAC/B,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,wEAAwE;IACxE,KAAK,UAAU,GAAG,CAChB,IAAY,EACZ,KAAe,EACf,GAAe;QAEf,MAAM,IAAI,GAAY,EAAE,CAAC;QACzB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;YACzC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,mBAAmB,IAAI,wBAAwB,IAAI,GAAG,CAAC,CAAC;gBACrE,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACpC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,EAAE,CAAC;gBACzD,OAAO,CAAC,IAAI,CACV,oBAAoB,IAAI,iBAAiB,KAAK,CAAC,IAAI,gBAAgB;oBACjE,QAAQ,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,EAAE,CACvD,CAAC;gBACF,SAAS;YACX,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;QACtB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,UAAU,MAAM,CACnB,IAAY,EACZ,OAAmC,EACnC,OAAsB,EACtB,GAAe,EACf,QAAgB;QAEhB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACvB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,EAAE,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,GACrC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAgB,CAAC,CAAC,IAAI,EAAE,CAAC;QACnD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,OAAO;oBACL;wBACE,KAAK,EAAE,SAAS;wBAChB,IAAI,EAAE,QAAQ;wBACd,GAAG,EAAE,eAAe;wBACpB,GAAG,EAAE,KAAY;qBAClB;iBACF,CAAC;YACJ,CAAC;YACD,oEAAoE;YACpE,8DAA8D;YAC9D,OAAO,CAAC,IAAI,CACV,mBAAmB,IAAI,cAAc,SAAS,IAAI,OAAO,eAAe,CACzE,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,EAAE;YACjB,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC1C,GAAG,MAAM;SACV,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,GAAG;YACzB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,OAAO,CAAC,IAAI,CAAC,sBAAsB,IAAI,GAAG,CAAC,CAAC;gBAC5C,OAAO,EAAE,CAAC;YACZ,CAAC;YACD,MAAM,KAAK,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,CAAC;YACxC,OAAO,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QACvE,CAAC;QAED,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG;YAC3B,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC;YACpC,IAAI,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC;gBACvB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;gBACjC,OAAO,MAAM,CACX,IAAI,EACJ,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,CAAC,IAAI,CAAE,CAC1B,EAC5B,MAAM,EACN,GAAG,EACH,mBAAmB,IAAI,iBAAiB,SAAS,CAAC,IAAI,CAAC,SAAS,KAAK,GAAG,CACzE,CAAC;YACJ,CAAC;YACD,OAAO,MAAM,CACX,IAAI,EACJ,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,CAA+B,EACpE,MAAM,EACN,GAAG,EACH,mBAAmB,IAAI,0BAA0B,IAAI,GAAG,CACzD,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,OAAO,CAAC,OAAgB;IAC/B,IACE,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,KAAK,IAAI;QAChB,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EACtB,CAAC;QACD,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,kBAAkB,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,EAAE,CAAC;QAChD,OAAO,kEAAkE,CAAC;IAC5E,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["// The server-side contract and the engine that runs it.\n//\n// This is the counterpart to core/lb-constants.ts: that file is the\n// vocabulary the browser writes, this one is the vocabulary the application\n// writes. The engine below is the whole of Loadbare on the server. It ships\n// no HTTP server, no router, and no data layer.\n\nimport type {\n  HubData,\n  HubRequest,\n  HubResponse,\n  HubResult,\n  Kind,\n  Patch,\n  RequestFields,\n  ResponseItem,\n  Row,\n} from \"../core/lb-types.js\";\nimport { isRowRequest } from \"../core/lb-types.js\";\nimport {\n  KIND_ROW,\n  KIND_ROWS,\n  LB_RESERVED_PREFIX,\n  REQUEST_ROW_DELETE,\n  REQUEST_ROW_INSERT,\n  REQUEST_ROW_UPDATE,\n  URL_COLUMN_PATH,\n  URL_QUERY,\n} from \"../core/lb-constants.js\";\n\n/**\n * Whatever the application hands the engine for the duration of one request.\n *\n * Loadbare declares it empty and never reads it. An application fills it in\n * by declaration merging, once, anywhere in its own source:\n *\n *     declare module \"@loadbare/app/server\" {\n *       interface HubContext {\n *         db: Db;\n *       }\n *     }\n *\n * That is why no type on this page takes a type parameter. The context is a\n * request-scoped handle — an authenticated database connection is the\n * expected case — so it is passed per call rather than held by the engine.\n * The page's query parms are the other expected member: a query that reads\n * one off the context takes no argument, and re-runs under `refresh` like\n * any other.\n */\nexport interface HubContext {}\n\n/**\n * A declared query: its kind, its key, and the run that answers it.\n *\n * Kind and key are properties of the name rather than of any one answer, so\n * they are declared here and never inferred from what comes back. The engine\n * sends both with every answer, so the markup repeats neither. Every query\n * has a key; an aggregate row answers with a constant one.\n *\n * Write one with `row()` or `rows()` below; nothing else builds one.\n */\nexport interface Query {\n  readonly kind: Kind;\n  readonly key: string;\n  readonly run: (ctx: HubContext) => HubResult | Promise<HubResult>;\n}\n\n/** A query that answers with one row, identified by its `key` column. */\nexport function row(\n  key: string,\n  run: (ctx: HubContext) => Row | Promise<Row>,\n): Query {\n  return { kind: KIND_ROW, key, run };\n}\n\n/**\n * A query that answers with all its rows, and therefore also their order.\n * Rows land by their `key` column: a row whose key is not in the answer is\n * gone.\n */\nexport function rows(\n  key: string,\n  run: (ctx: HubContext) => Row[] | Promise<Row[]>,\n): Query {\n  return { kind: KIND_ROWS, key, run };\n}\n\n/**\n * Only what changed, returned from a handler for a `rows` query. Rows named\n * here are added or updated, keys in `drop` are removed, and everything\n * unnamed is left alone — its contents, and its place in whatever order the\n * page is keeping.\n *\n * `Array.isArray` is what tells a patch from all rows, so a patch needs no\n * marker of its own and no column name is reserved to carry one.\n */\nexport function patch(change: { rows?: Row[]; drop?: unknown[] }): Patch {\n  const made = { ...change };\n  patches.add(made);\n  return made;\n}\n\n/**\n * Every object `patch()` made. A patch and a row are both plain objects, so\n * this is how the engine refuses a patch answering a `row` query.\n */\nconst patches = new WeakSet<object>();\n\n/**\n * A new row for `lb-url`, returned from a handler when only the handler can\n * know where the page belongs: the key of a row it inserted, or the absence\n * of one it deleted.\n *\n * A column other than `lb-path` is a query parm: set, or taken out when its\n * value is empty. With `lb-path` naming another page, the page is entered\n * with only the parms named here; otherwise every other parm is kept.\n *\n * The page then loads at the new URL in the same round trip, as a cold load\n * of it would, so the refresh set is not run and whatever else the handler\n * returned is dropped: both were answers for the URL the page is leaving.\n * This is Post/Redirect/Get without the redirect.\n */\nexport function url(columns: Record<string, string>): HubData {\n  return { [URL_QUERY]: { ...columns } };\n}\n\n/** The shape of a `<stub>.queries.ts` module. */\nexport type Queries = Record<string, Query>;\n\n/**\n * What a handler does, and which queries re-run once it has.\n *\n * `run` may also return answers of its own, which are laid over the\n * refreshed ones. That is how a patch reaches the browser: a query answers\n * for all its rows and cannot know why it re-ran, but the handler knows\n * exactly what it changed and can say only that.\n */\nexport interface Handler<R = RequestFields> {\n  run: (\n    ctx: HubContext,\n    request: R,\n  ) => void | HubData | Promise<void | HubData>;\n  refresh: string[];\n}\n\nexport type RowInsertHandler = Handler<{\n  key?: string;\n  values: Record<string, string>;\n}>;\n/** `values` holds only the columns being set, as an SQL UPDATE sets them. */\nexport type RowUpdateHandler = Handler<{\n  key: string;\n  values: Record<string, string>;\n}>;\nexport type RowDeleteHandler = Handler<{ key: string }>;\n\n/**\n * What the requests Loadbare provides do to one query, keyed by its name in\n * `Requests.crud`. A query with no entry here permits none of them: the wire\n * cannot reach anything the page has not published.\n *\n * Every key is the request name with the prefix stripped and the rest\n * camel-cased: `lb-row-insert` runs `rowInsert`.\n */\nexport interface Crud {\n  rowInsert?: RowInsertHandler;\n  rowUpdate?: RowUpdateHandler;\n  rowDelete?: RowDeleteHandler;\n}\n\n/**\n * The shape of a `<stub>.requests.ts` module.\n *\n * `onPageEnter` runs when the page loads, before its queries. It declares no\n * refresh set: the page's queries all run afterward, so whatever it changed\n * is already in the response.\n *\n * `handlers` holds the page's declared requests, by name. A name the page\n * did not declare is refused, so the wire cannot reach anything the page has\n * not published.\n *\n * `crud` holds what the requests Loadbare provides run, by query name.\n */\nexport interface Requests {\n  onPageEnter?: (ctx: HubContext) => void | Promise<void>;\n  handlers?: Record<string, Handler>;\n  crud?: Record<string, Crud>;\n}\n\n/** A page is three files sharing a stub; two of them are these. */\nexport interface Page {\n  queries: Queries;\n  requests: Requests;\n}\n\n/**\n * The page registry. The builder writes it from every `.requests.ts` and\n * `.queries.ts` it discovers — see docs/reference/builder.md.\n */\nexport type Pages = Record<string, Page>;\n\n/**\n * The engine. Both calls answer with response items. A request whose\n * handler returned `url()` answers with the `lb-url` item alone: the caller\n * builds a context at the new URL, calls `dataForPage` with it, and sends\n * the load beside the item. `hubRoutes` does exactly that.\n */\nexport interface Hub {\n  /** A page load: its `onPageEnter`, then all of its queries. */\n  dataForPage(page: string, ctx: HubContext): Promise<HubResponse>;\n\n  /** A request: run the handler its name picks, then the refresh set. */\n  runRequest(\n    page: string,\n    request: HubRequest,\n    ctx: HubContext,\n  ): Promise<HubResponse>;\n}\n\n/** The camel-cased `Crud` key of a request Loadbare provides. */\nconst CRUD_KEYS: Record<string, keyof Crud> = {\n  [REQUEST_ROW_INSERT]: \"rowInsert\",\n  [REQUEST_ROW_UPDATE]: \"rowUpdate\",\n  [REQUEST_ROW_DELETE]: \"rowDelete\",\n};\n\n/**\n * Build the engine over a set of pages. The pages are fixed at startup; the\n * context is not, and arrives with each call.\n */\nexport function createHub(pages: Pages): Hub {\n  // Names beginning with the reserved prefix are Loadbare's — its own query,\n  // the requests it provides — so an application cannot declare one.\n  // Refused at startup, because a name is a fact about the page and not\n  // about any request.\n  for (const [page, entry] of Object.entries(pages)) {\n    const declared = [\n      ...Object.keys(entry.queries),\n      ...Object.keys(entry.requests.handlers ?? {}),\n      ...Object.keys(entry.requests.crud ?? {}),\n    ];\n    for (const name of declared) {\n      if (name.startsWith(LB_RESERVED_PREFIX)) {\n        throw new Error(\n          `loadbare: page '${page}' declares '${name}', but names ` +\n            `beginning with '${LB_RESERVED_PREFIX}' are reserved`,\n        );\n      }\n    }\n\n    // An update or a delete names its row by key, so its handler always\n    // knows which rows changed and can answer with a patch; removing a row\n    // never reorders the rest. Refreshing the whole set instead sends every\n    // row and places every row again, which moves the element the user is\n    // in. There is no case where that is the answer to either, so it is\n    // refused rather than warned about. An insert is not: where its row\n    // goes depends on the markup, which the server cannot see.\n    for (const [name, crud] of Object.entries(entry.requests.crud ?? {})) {\n      if (entry.queries[name]?.kind !== KIND_ROWS) continue;\n      for (const request of [\"rowUpdate\", \"rowDelete\"] as const) {\n        if (crud[request]?.refresh.includes(name)) {\n          throw new Error(\n            `loadbare: page '${page}' refreshes '${name}' after its own ` +\n              `${request}; return the changed rows in a patch instead`,\n          );\n        }\n      }\n    }\n  }\n\n  /**\n   * Answers into response items, adding the kind and key each query\n   * declared. An answer that disagrees with its declaration is a mistake in\n   * the application rather than a case to handle, and is left out: a page is\n   * better off missing one query than showing the wrong shape for it.\n   */\n  function items(page: string, data: HubData): HubResponse {\n    const out: ResponseItem[] = [];\n    for (const [name, result] of Object.entries(data)) {\n      const query = pages[page]?.queries[name];\n      if (!query) {\n        console.warn(`loadbare: page '${page}' declares no query '${name}'`);\n        continue;\n      }\n      const item: ResponseItem = {\n        query: name,\n        kind: query.kind,\n        key: query.key,\n      };\n      if (query.kind === KIND_ROW) {\n        if (Array.isArray(result) || patches.has(result)) {\n          console.warn(\n            `loadbare: query '${name}' is declared row but answered with ` +\n              `${Array.isArray(result) ? \"rows\" : \"a patch\"}`,\n          );\n          continue;\n        }\n        item.row = result as Row;\n      } else if (Array.isArray(result)) {\n        item.rows = result;\n      } else {\n        item.patch = result as Patch;\n      }\n      out.push(item);\n    }\n    return out;\n  }\n\n  /** Run queries by name, each answering with all its rows or its row. */\n  async function run(\n    page: string,\n    names: string[],\n    ctx: HubContext,\n  ): Promise<HubData> {\n    const data: HubData = {};\n    for (const name of names) {\n      const query = pages[page]?.queries[name];\n      if (!query) {\n        console.warn(`loadbare: page '${page}' declares no query '${name}'`);\n        continue;\n      }\n      const result = await query.run(ctx);\n      if (Array.isArray(result) !== (query.kind === KIND_ROWS)) {\n        console.warn(\n          `loadbare: query '${name}' is declared ${query.kind} but answered ` +\n            `with ${Array.isArray(result) ? \"rows\" : \"one row\"}`,\n        );\n        continue;\n      }\n      data[name] = result;\n    }\n    return data;\n  }\n\n  /**\n   * Run a handler, then its refresh set against the same context, laying\n   * what the handler itself returned over the refreshed queries — the\n   * narrower answer wins because it knows what actually changed.\n   *\n   * A handler that returned `url()` answers with the `lb-url` item alone.\n   * Loading the page there needs a context built at the new URL, and\n   * building one is the caller's.\n   */\n  async function settle(\n    page: string,\n    handler: Handler<never> | undefined,\n    request: RequestFields,\n    ctx: HubContext,\n    notFound: string,\n  ): Promise<HubResponse> {\n    if (!handler) {\n      console.warn(notFound);\n      return [];\n    }\n    const { [URL_QUERY]: moved, ...stated } =\n      (await handler.run(ctx, request as never)) ?? {};\n    if (moved !== undefined) {\n      const refused = refusal(moved);\n      if (refused === undefined) {\n        return [\n          {\n            query: URL_QUERY,\n            kind: KIND_ROW,\n            key: URL_COLUMN_PATH,\n            row: moved as Row,\n          },\n        ];\n      }\n      // The handler has already run, so the page still hears about it, by\n      // its refresh set, as if no row for lb-url had been returned.\n      console.warn(\n        `loadbare: page '${page}' returned ${URL_QUERY} ${refused}, ignoring it`,\n      );\n    }\n    return items(page, {\n      ...(await run(page, handler.refresh, ctx)),\n      ...stated,\n    });\n  }\n\n  return {\n    async dataForPage(page, ctx) {\n      const entry = pages[page];\n      if (!entry) {\n        console.warn(`loadbare: no page '${page}'`);\n        return [];\n      }\n      await entry.requests.onPageEnter?.(ctx);\n      return items(page, await run(page, Object.keys(entry.queries), ctx));\n    },\n\n    runRequest(page, request, ctx) {\n      const { name, ...fields } = request;\n      if (isRowRequest(name)) {\n        const query = fields.query ?? \"\";\n        return settle(\n          page,\n          pages[page]?.requests.crud?.[query]?.[CRUD_KEYS[name]!] as\n            Handler<never> | undefined,\n          fields,\n          ctx,\n          `loadbare: page '${page}' declares no ${CRUD_KEYS[name]} for '${query}'`,\n        );\n      }\n      return settle(\n        page,\n        pages[page]?.requests.handlers?.[name] as Handler<never> | undefined,\n        fields,\n        ctx,\n        `loadbare: page '${page}' declares no request '${name}'`,\n      );\n    },\n  };\n}\n\n/**\n * Why a returned row for `lb-url` cannot be used, or nothing when it can.\n *\n * A value is a string, as a control's is and a URL's is. At least one column\n * is named: a row naming none changes nothing.\n */\nfunction refusal(columns: unknown): string | undefined {\n  if (\n    typeof columns !== \"object\" ||\n    columns === null ||\n    Array.isArray(columns)\n  ) {\n    return \"that is not a row\";\n  }\n  const values = Object.values(columns);\n  if (values.length === 0) return \"naming no column\";\n  if (!values.every((v) => typeof v === \"string\")) {\n    return `holding a value that is not a string; write url({ name: \"...\" })`;\n  }\n  return undefined;\n}\n"]}

package/docs/TECHREF-1.0.md

@@ -64,10 +64,9 @@ fine, because every `<select>` receives the same rows.
 
 But the allowed values may depend on other values in the row.
 
-- **Decide how a new live row fills a nested query.** A row added to the
-  outer query starts with its nested query empty, and it fills only when the
-  nested query's name lands again.  See [Master-detail](#master-detail) for
-  what a nested query is for.
+- **Decide whether a nested query's rows may depend on its row.** A nested
+  query has one answer, which every live row receives.  See
+  [Master-detail](#master-detail) for what a nested query is for.
 
 ```html
 <tbody lb-query="accounts">
@@ -78,6 +77,24 @@ But the allowed values may depend on other values in the row.
 </tbody>
 ```
 
+### Who creates and orders rows
+
+The hub creates every live row from a row template and places it in the
+query's order, unless the element holding the rows has `lbPlaceRow`, in
+which case the custom element decides where each row goes.  Custom elements
+also create rows of their own: `lb-table` clones a ghost row per section and
+builds each section's heading.  Neither side owns creation or order.
+
+- **Decide who creates rows and who orders them.** A patch cannot say where
+  a new row goes, so it lands where the host puts it: in order under
+  `lb-table` with `data-sort`, last in plain markup and in `lb-options`.
+  Whether an insert may answer with a patch therefore depends on markup the
+  server cannot see, and the server cannot refuse an insert that refreshes
+  its own query the way it refuses an update or a delete.
+- **Decide whether landing all rows moves rows already in place.** It moves
+  every row today, which takes focus from the control the user is in, and
+  `lbPlaceRow` does the same.
+
 ### The server API
 
 - **Give the chrome a way to state its own queries.** A custom element in
@@ -425,7 +442,7 @@ query.
 | ----------- | -------- | -------------------------------------------------- |
 | `lb-query`  | a query  | Puts its rows in the element's content             |
 | `lb-column` | a column | Sets the element from that column                  |
-| `lb-show`   | a column | Removes it while the named column is null or false |
+| `lb-show`   | a column | Removes it while the named column is null or false; `!column` reverses it |
 
 | Stamp                | The hub stamps it with           |
 | -------------------- | -------------------------------- |
@@ -558,6 +575,10 @@ so `"false"` is on, and a query spells a condition as a boolean or a null.
 </template>
 ```
 
+Write `!` before the column to reverse it: `lb-show="!chosen"` is present
+while `chosen` is null or false.  One column then decides both of two
+elements, rather than a column and its opposite, which could disagree.
+
 It reads from the nearest ancestor row, as `lb-column` does, and on an
 element that carries `lb-query` the column belongs to the row around it.  A
 row that does not carry the column leaves the element as it is.
@@ -578,7 +599,8 @@ nothing conditional shows until its row lands.  An absent element's template
 keeps its place among its siblings, and a position selector counts it.
 
 These are build errors: `lb-show` on a row template's root, `lb-show` with
-no `lb-query` around it, and `lb-show` on a `<template>`.
+no `lb-query` around it, `lb-show` on a `<template>`, and `lb-show="!"` or
+`lb-show="!!column"`.
 
 Hiding is presentation, and the server still refuses what a request may not
 do.
@@ -608,7 +630,9 @@ each detail row carries its master's columns.  A custom element's
 
 A query nested in another query's row template receives the same rows in
 every live row.  That serves a picker offering the same choices on every
-row, and is not a way to show a different detail per row.
+row, and is not a way to show a different detail per row.  A live row added
+later is filled from the nested query's last answer, so a request that adds
+one does not refresh the nested query to fill it.
 
 Which master a page shows is a query parm, which a query reads off `ctx`
 since it takes no argument from the browser — see [Query parms](#query-parms).
@@ -767,6 +791,18 @@ interceptor calls `stopPropagation`, not `preventDefault`.  This is what
 makes a confirmation wrapper possible without the wrapped element knowing
 about it.
 
+Once what the request brought back has landed, or its round trip has failed,
+the hub dispatches the bubbling `lb-request-done` event from the same
+element.  Its `detail`, `HubRequestDone` in `@loadbare/app/types`, holds
+the request as the hub sent it and `items`, every response item that landed
+because of it, in order.  An answer that moved the URL contributes its
+`lb-url` item and the page load.  `error` is set instead when the round trip
+failed.  By then `lb-request-pending` is gone, and a listener sees the page
+as the answer left it.  A request the hub or an ancestor stopped was never
+sent, and gets no `lb-request-done`.  An element the answer removed from the
+document, such as the row a delete took away, dispatches the event where it
+now is, and no ancestor it had on the page hears it.
+
 #### Request state
 
 The hub stamps `lb-request-pending` on the element that issued a request
@@ -804,6 +840,14 @@ A page load that fails lands nothing and is reported to the console.  A load
 started by a request for `lb-url` stamps the element that issued it, as any
 request stamps its element.
 
+A response answers for the URL its request was sent from, path and query
+string both.  One that returns after the URL has moved lands nothing, since
+it describes what the user is no longer looking at: a request's answer,
+including any `url()` it carries, and a page load overtaken by a newer one.
+A write whose answer is dropped this way has still happened.  Its
+`lb-request-done` carries no items and no error, and an insert still resets
+its form.
+
 ### The URL
 
 ---- UNEDITED ----
@@ -834,6 +878,14 @@ server runs its `onPageEnter`, then its queries.  When a query parm takes a
 new value, the hub reloads the page's queries, and keeps the page's DOM, so
 live rows that come back keep their place.
 
+Once an entered page's queries have landed, the hub focuses the first
+element in `<main>` the user can operate: not disabled, not in a closed
+`<dialog>`, not `inert`, not `hidden`, not in an absent `lb-show` branch,
+and one that takes the focus.  Entering is a cold load, a new `lb-path`,
+and Back or Forward to another page.  A change of query parm enters no
+page, and focus stays where it is, as it does when it is already in
+`<main>`.
+
 The page's title is the text of the page file's `<title>`, which the builder
 stamps on the page as `lb-page-title`.  The hub sets the document title to
 `lb-page-label` when it is not null.
@@ -1003,8 +1055,8 @@ rowInsert: {
   carries the `lb-url` item alone, and the hub loads the page itself.  A
   failure there is a page load's, and is not stamped on the element that
   issued the request.
-- A user who has left the page by the time the response arrives keeps the
-  URL they are on.
+- A user who has moved by the time the response arrives, to another page or
+  to other query parms, keeps the URL they are on.
 
 The page is loaded with a second context, built by `contextFor` from the new
 parms — see [The Express server](#the-express-server).
@@ -1027,6 +1079,7 @@ to build on any of these:
   `<lb-hub>`.
 - `lb-show` on a `<template>`, on a row template's root, or with no
   `lb-query` around it.
+- `lb-show="!"` or `lb-show="!!column"`, which reverse no column.
 
 `lb-column` with no ancestor row is allowed: the hub gathers from it.
 
@@ -1276,6 +1329,9 @@ request carrying no name answers 400, and a `run` that throws answers 500.
 
 Every handler under `handlers` and `crud` has the same two members.  `run`
 performs the work, and `refresh` names the queries to re-run once it has.
+A query belongs there when its answer changed, never to fill an element the
+request's answer creates: that element is filled from the last answer its
+query landed.
 
 `run` receives the same `ctx` and the request less its name: `query`, `key`
 and `values`, as present.
@@ -1284,6 +1340,15 @@ and `values`, as present.
 the refreshed ones.  That is how a delta reaches the browser: wrap it in
 `patch()`, naming the rows that arrived or changed and the keys that went.
 
+A refreshed `rows` query sends every row, and the hub places every row
+again, which moves each element and takes focus from the control the user
+is in.  An update or a delete names its row by key, and removing a row
+never reorders the rest, so its handler always knows what changed:
+`createHub` refuses at startup a `crud` `rowUpdate` or `rowDelete` on a
+`rows` query whose `refresh` names that same query.  A `row` query sends one
+row and may refresh itself.  An insert may refresh its own query; see
+[Who creates and orders rows](#who-creates-and-orders-rows).
+
 `run` may instead return `url()`, a new row for `lb-url`, naming query parms
 only the write can know, such as the key of a row it inserted.  The page
 then loads at them in the same round trip, in place of the refresh set — see
@@ -1397,6 +1462,25 @@ export default ["@scope/library-name"];
 Import every attribute name from `@loadbare/app/constants` — see
 [Constants](#constants).  Never write one as a string literal.
 
+### What the hub and an element say to each other
+
+Each direction has one mechanism for each kind of message:
+
+| Direction      | What                                        | How                          | Today                                            |
+| -------------- | ------------------------------------------- | ---------------------------- | ------------------------------------------------ |
+| Hub to element | State that lasts                            | An attribute the hub stamps  | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State the platform already names           | A property                   | A control's `value`                              |
+| Hub to element | Work the hub needs done now, while landing  | An optional `lb` method      | `lbPlaceRow`, `lbRowsLanded`                     |
+| Hub to element | A moment an element started                 | A bubbling event             | `lb-request-done`                                |
+| Element to hub | A moment                                    | A bubbling event             | `lb-request`, and `change`, `click` and `submit` |
+
+State is an attribute, because a stylesheet can select on it and an element
+that upgrades late still finds it.  A method is for work the hub cannot go
+on without, since it acts on one element at one point in landing and nothing
+else can do it.  A moment is an event, because the element that cares is
+often an ancestor of the one it concerns, and an event reaches it with no
+knowledge of either.
+
 ### Controls
 
 A form-associated custom element with a `value` property that fires
@@ -1450,6 +1534,11 @@ The hub calls both on a custom element with `lb-query` and a row template.
 Both are optional.  The `RowsHost` interface in `@loadbare/app/types`
 declares them.
 
+A custom element the builder shipped absent under `lb-show` has not
+upgraded while its column is off, and rows that land on it then are placed
+without it.  When the column first turns on and it upgrades, the hub lands
+the query's last answer on it again, as all rows, so both hooks run.
+
 `applyRow(root, row)`, exported by `@loadbare/app`, fills `root` from one
 row, the same operation that fills a live row.
 
@@ -1593,6 +1682,7 @@ Loadbare/app owns every DOM event in this table, both the name and what its
 | Event        | Dispatched from                  | Bubbles | Cancelable | Defined in                              |
 | ------------ | -------------------------------- | ------- | ---------- | --------------------------------------- |
 | `lb-request` | The element that committed       | Yes     | No         | [The request event](#the-request-event) |
+| `lb-request-done` | The element that committed  | Yes     | No         | [The request event](#the-request-event) |
 
 ### Reserved methods
 
@@ -1628,6 +1718,8 @@ imports them rather than writing a string.
 | `ATTR_PAGE_TITLE`         | `lb-page-title`                         |
 | `DEVELOPER_ATTRIBUTES`    | The seven attributes a developer writes |
 | `LB_EVENT_NAME`           | `lb-request`                            |
+| `LB_DONE_EVENT_NAME`      | `lb-request-done`                       |
+| `SHOW_NOT`                | `!`, written before a column in `lb-show` |
 | `LB_RESERVED_PREFIX`      | `lb-`                                   |
 | `REQUEST_ROW_INSERT`      | `lb-row-insert`                         |
 | `REQUEST_ROW_UPDATE`      | `lb-row-update`                         |

package/docs/comparison.md

@@ -128,7 +128,7 @@ shape of the data an application works with.
 ### Loadbare/app
 
 The hub holds no application data.  There is no store, no signal, no
-observable, and no client cache of query results.
+observable, and no client cache that answers a request.
 
 - A value that has landed exists in the DOM: as `textContent` or `value`, and
   as the `lb-column-value` stamp.
@@ -138,6 +138,10 @@ observable, and no client cache of query results.
   the path, the page label and the query parms.
 - An element hidden by `lb-show` exists inside a `<template>` standing where
   it stood.
+- The hub keeps each query's last answer until the page changes, only to
+  fill an element that names the query and arrives after it, such as a
+  picker in a new live row.  Nothing is read from it in place of asking the
+  server.
 - The hub keeps two pieces of state of its own: the name of the current page,
   and, until an insert completes, the form it gathered from.
 

package/docs/reference/chrome.md

@@ -108,6 +108,21 @@ tab and the browser history show the page.
 `lb-url` is the one query a page may use that the server does not declare. A
 page names it the same way, anywhere inside the hub.
 
+### Where focus starts
+
+On entering a page, once its queries have landed, the hub focuses the first
+element in `<main>` the user can operate, so a keyboard user starts in the
+page rather than on the document. The chrome comes first in the document,
+and is passed over. So is anything disabled, in a closed `<dialog>`,
+`inert`, `hidden`, in an absent `lb-show` branch, or that does not take
+the focus when asked. A widget's native control counts, so write no
+`autofocus` to restate this.
+
+A page is entered on a cold load, a new `lb-path` from a link or from a
+handler's `url()`, and Back or Forward to another page. A change of query
+parm enters no page: the user who chose a record in a picker stays in the
+picker. Focus the user has already put in `<main>` is left there.
+
 ### Links
 
 Write `lb-url-link` on an `<a>` to move between pages:

package/docs/reference/custom-elements.md

@@ -268,6 +268,8 @@ one as a string literal:
 | `REQUEST_ROW_INSERT`, `REQUEST_ROW_UPDATE`, `REQUEST_ROW_DELETE` | The requests Loadbare provides |
 | `LB_ROW_REQUESTS`      | All three, in one array |
 | `LB_EVENT_NAME`        | `lb-request`, the event every request travels as |
+| `LB_DONE_EVENT_NAME`   | `lb-request-done`, the event that says how it turned out |
+| `SHOW_NOT`             | `!`, written before a column in `lb-show` |
 | `URL_QUERY`            | `lb-url`             |
 | `URL_COLUMN_PATH`, `URL_COLUMN_PAGE_LABEL`, `URL_COLUMN_PAGE_UNKNOWN` | `lb-path`, `lb-page-label`, `lb-page-unknown` |
 | `LB_RESERVED_PREFIX`   | `lb-`                |
@@ -278,6 +280,24 @@ writes them in markup, and the hub and the builder write their stamps.
 Loadbare reserves method names beginning with `lb` on a custom element, for
 the methods it calls; see [Holding rows](#holding-rows).
 
+### What the hub and an element say to each other
+
+Each direction has one mechanism for each kind of message:
+
+| Direction      | What                                       | How                         | Today |
+|----------------|--------------------------------------------|-----------------------------|-------|
+| Hub to element | State that lasts                           | An attribute the hub stamps | `lb-column-value`, `lb-key-value`, `lb-query-row-count`, `lb-request-pending`, `lb-request-error` |
+| Hub to element | State the platform already names           | A property                  | A control's `value` |
+| Hub to element | Work the hub needs done now, while landing | An optional `lb` method     | `lbPlaceRow`, `lbRowsLanded` |
+| Hub to element | A moment an element started                | A bubbling event            | `lb-request-done` |
+| Element to hub | A moment                                   | A bubbling event            | `lb-request`, and `change`, `click` and `submit` |
+
+State is an attribute: a stylesheet can select on it, and an element that
+upgrades late still finds it. A method is for work the hub cannot go on
+without, done by one element at one point in landing. A moment is an event,
+because the element that cares is often an ancestor of the one it concerns,
+and an event reaches it knowing neither.
+
 ### When its code runs
 
 The hub creates, places and parks elements, and each of those reaches a
@@ -450,6 +470,39 @@ missing a field its name needs, and stamps the dispatching element with
 
 Let the event bubble, so an ancestor can stop it before the hub sends it.
 
+### Hearing how it turned out
+
+Once what a request brought back has landed, or its round trip has failed,
+the hub dispatches `lb-request-done` from the element that committed. It
+bubbles, so the element that cares need not be the one that committed: a
+dialog hears it from the form inside it.
+
+```ts
+import { LB_DONE_EVENT_NAME } from "@loadbare/app/constants";
+import type { HubRequestDone } from "@loadbare/app/types";
+
+this.addEventListener(LB_DONE_EVENT_NAME, (e) => {
+  const { request, items, error } = (e as CustomEvent<HubRequestDone>).detail;
+  if (error) return;
+  const item = items.find((i) => i.query === request.query);
+  const created = item?.patch?.rows?.[0];
+  if (created) this.choose(String(created[item!.key]));
+});
+```
+
+`items` is every response item that landed because of the request, in
+order. An answer that moved the URL contributes its `lb-url` item, which
+carries a key only the server knew, and the page load. `error` is set when
+the round trip failed, and then nothing landed. A new row's key is in the
+answer only when the handler returned it in a patch: a refresh sends all
+rows, and nothing marks which one is new.
+
+By the time the event is dispatched, `lb-request-pending` is gone and the
+page is as the answer left it. A request that was never sent, because the
+hub or an ancestor stopped it, gets no `lb-request-done`. An element the
+answer removed, such as the row a delete took away, dispatches the event
+outside the document, and no ancestor it had there hears it.
+
 ### Holding rows
 
 The hub lands every row template itself. A plain element carrying `lb-query`
@@ -498,6 +551,15 @@ template, in arrival order. `lb-options.browser.ts` and
 `lb-table.browser.ts` in [`@loadbare/widgets`](./widgets.md) are two
 different placements over the same landing.
 
+A custom element the builder shipped absent under `lb-show` has not
+upgraded while its column is off, so it has no `lbPlaceRow` when rows land
+on it then, and the hub places them before the template. When the column
+first turns on and the element upgrades, the hub lands the query's last
+answer on it again, as all rows, so every row goes through `lbPlaceRow` and
+`lbRowsLanded` runs. Once upgraded it stays so: when its branch goes away and
+comes back, it has placed every row that landed meanwhile, and nothing is
+landed again.
+
 A custom element that walks its own rows finds them with `LIVE_ROW` from
 `@loadbare/app/constants`, never by `lb-key-value`: an element a `row` lands
 on carries a key too, and may sit among the rows, as a total in a table's

package/docs/reference/data-binding.md

@@ -168,6 +168,28 @@ a row goes and add scaffolding around the rows; see
 [Holding rows](./custom-elements.md#holding-rows) and
 [The Basic Widget Library](./widgets.md).
 
+### What arrives later
+
+The hub keeps each query's last answer until the page changes, with any
+patch since applied to it. An element that names a query and arrives after
+that query's answer is filled from what was kept, at the end of the landing
+that follows its arrival. Such an element is a picker in a new live row, or
+scaffolding a custom element builds around its rows, such as a ghost row. So
+a query nested in another query's rows need not land again, or land after
+the outer query, for a new outer row to show its choices.
+
+A custom element the builder shipped absent has not upgraded while its
+`lb-show` column is off, so rows that land on it then are not placed by it.
+When the column first turns on and the element upgrades, the hub lands the
+kept answer on it again, and every row goes through its `lbPlaceRow`. So a
+table that groups its rows can sit under `lb-show`. See
+[Holding rows](./custom-elements.md#holding-rows).
+
+Nothing is answered from what the hub kept: a request always goes to the
+server, and a query re-runs only when a response names it. A patch that
+arrives before all of a query's rows is not kept, since it is not the whole
+of anything.
+
 A `rows` query on an element with no row template lands nothing. That is the
 insert form above: it sits inside `lb-query="roster"` so its request is for
 `roster`, and it shows none of its rows.
@@ -225,6 +247,14 @@ have the query answer with a boolean or a null. A row that does not carry
 the column leaves the element as it is, so a query answers with the column
 in every row.
 
+Write `!` before the column to reverse it. One column then decides between
+two elements, rather than a column and its opposite, which could disagree:
+
+```html
+<h2 lb-show="chosen" lb-column="title"></h2>
+<p lb-show="!chosen">Choose a batch.</p>
+```
+
 `lb-show` reads from the nearest ancestor row, as `lb-column` does. On an
 element that also carries `lb-query`, the column belongs to the row around
 it, so this picker takes its choices from `groups` and whether it is present
@@ -463,6 +493,11 @@ An ancestor may stop the event, and the request is not sent. A custom
 element may dispatch the event itself; see
 [Sending a request](./custom-elements.md#sending-a-request).
 
+Once the answer has landed, or the round trip has failed, the hub dispatches
+a bubbling `lb-request-done` event from the same element, carrying the
+request and what landed because of it, or the error; see
+[Hearing how it turned out](./custom-elements.md#hearing-how-it-turned-out).
+
 ## The URL
 
 The hub serves one query of its own, `lb-url`: one row holding the path, the
@@ -495,3 +530,4 @@ expansion, and refuses to build:
 - `lb-url-unknown` on anything but a `<dialog>`, or outside `<lb-hub>`
 - `lb-show` on a `<template>`, or on a row template's root
 - `lb-show` with no `lb-query` around it
+- `lb-show="!"` or `lb-show="!!column"`, which reverse no column

package/docs/reference/page-files.md

@@ -223,6 +223,9 @@ Every value in `values` is a string, as a control's value is.
 ### refresh and patch
 
 List in `refresh` every query whose whole answer the request changed.
+Never list one only to fill what the request's answer creates, such as the
+picker in a new row: the hub fills that from the query's last answer. See
+[What arrives later](./data-binding.md#what-arrives-later).
 
 Return answers from `run` to state a narrower change than re-running a query
 would. What `run` returns is keyed by query name and laid over the refreshed
@@ -236,8 +239,33 @@ queries:
 | `patch({ drop: [...] })` | These keys are gone; the rest stand         |
 
 Return a patch for a change the request knows the extent of — one row added,
-one row dropped, one row edited — and leave `refresh` empty. Re-run the query
-instead when membership or order changed in a way the request cannot name:
+one row dropped, one row edited — and leave `refresh` empty. A refreshed
+`rows` query sends every row, and the hub places every row again, which moves
+each element and takes focus from the control the user is in.
+
+A change that seems to need a refresh usually has a patch:
+
+- A placeholder row standing in for an empty set or section: drop its key in
+  the patch that adds the first real row, and add it back in the patch that
+  drops the last.
+- A row whose position changes: the rows host places it, as
+  [`lb-table`](./widgets.md#lb-table) does by `data-sort`.
+- A row whose other columns change with the edit: re-read the row and patch
+  it.
+- Rows the database removes with a deleted one: select their keys before the
+  delete and drop them too.
+
+An update or a delete always has a patch, since it names its row by key and
+removing a row never reorders the rest. `createHub` refuses at startup a
+`crud` `rowUpdate` or `rowDelete` on a `rows` query whose `refresh` names
+that same query. An insert may refresh its own query: where a new row goes
+depends on whether its host places it, which the server cannot see.
+
+Each request's `refresh` is its own, and every query in it needs its own
+reason. A list shared by several requests is a warning sign.
+
+Re-run the query when membership or order changed in a way the request
+cannot name:
 
 ```ts
 resetRoster: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "files": [
     "dist",