@loadbare/app 0.5.6 → 0.7.0

package/dist/core/lb-types.d.ts

@@ -1,88 +1,129 @@
-/** docs/reference/data-binding.md — the operation set is closed. */
-export type HubRequest = {
-    op: "cell-change";
-    query: string;
-    key: string;
-    cell: string;
-    value: string;
-} | {
-    op: "tuple-insert";
-    query: string;
+import { ACTION_CELL_CHANGE, ACTION_ROW_DELETE, ACTION_ROW_INSERT, ACTION_ROW_UPDATE } from "./lb-constants.js";
+/**
+ * One row: its columns, by name.
+ *
+ * A value is whatever the server serialized. The hub knows nothing about its
+ * type and enforces nothing: it hands each value to the browser untouched,
+ * and the browser renders it as it sees fit. What a number, a date or a null
+ * should look like is the application's decision, made in the query.
+ */
+export type Row = Record<string, unknown>;
+/**
+ * Part of a list — see docs/reference/server.md, "Queries".
+ *
+ * Rows named here arrive or are updated, keys in `drop` are gone, and
+ * anything unnamed is left alone: its contents, and its place in whatever
+ * order the widget is keeping. Add and remove are one result rather than two
+ * because the interesting cases are both at once — a row whose sort key
+ * changed has to move, a swap is one out and one in — and two messages would
+ * paint the intermediate state.
+ */
+export interface Patch {
+    rows?: Row[];
+    drop?: unknown[];
+}
+/**
+ * What a list answers with.
+ *
+ * An array is the entire set and therefore also the order: a row whose key
+ * is not in it is gone. A Patch disturbs only what it names.
+ *
+ * `Array.isArray` tells the two apart, which is why no column name has to be
+ * reserved to carry a discriminant. A list answering with an object is a
+ * patch, because the declaration already said this name answers with rows.
+ */
+export type ListResult = Row[] | Patch;
+export declare function isPatch(result: ListResult): result is Patch;
+/**
+ * What any one name answers with. Which of the two it is comes from the
+ * query's own declaration, never from inspecting the value.
+ */
+export type HubResult = Row | ListResult;
+/**
+ * Every response on the data channel is the same shape, whether it is a cold
+ * start or the narrowest refresh. The hub does not know which case it is in.
+ *
+ * A name rides as an object key and is labelled by nothing, which is why the
+ * response direction never needed a noun for the addressable thing.
+ */
+export type HubData = Record<string, HubResult>;
+/**
+ * The four operations — docs/reference/data-binding.md. The set is closed.
+ *
+ * `action` carries the value of `lb-action` verbatim, so the attribute, the
+ * wire field and the CRUD key are one vocabulary with no translation step.
+ * The scope field is `list` here because all four are list operations: each
+ * needs a key, and a key exists only on a live row inside a list.
+ */
+export type LbOperation = {
+    action: typeof ACTION_ROW_INSERT;
+    list: string;
     values: Record<string, string>;
 } | {
-    op: "tuple-update";
-    query: string;
+    action: typeof ACTION_ROW_DELETE;
+    list: string;
+    key: string;
+} | {
+    action: typeof ACTION_ROW_UPDATE;
+    list: string;
     key: string;
     values: Record<string, string>;
 } | {
-    op: "tuple-delete";
-    query: string;
+    action: typeof ACTION_CELL_CHANGE;
+    list: string;
     key: string;
-}
+    cell: string;
+    value: string;
+};
 /**
- * Everything that is not a CRUD operation.
+ * Everything that is not one of the four.
  *
  * The name is the application's and is looked up in the page's declared
  * actions. What keeps this from being an RPC endpoint is that the name must
- * already appear in the page's hooks: the browser cannot reach anything the
+ * already appear in the page's requests: the browser cannot reach anything the
  * page has not published, and there is no argument list — only where the
  * interaction happened and, where a control has one, its value.
  *
- * A button carries no value, so the server computes the whole of the new
+ * The scope field is `list` or `row`, whichever attribute scoped the element
+ * the interaction came from, so an action fired from a single-row scope says
+ * so. A button carries no value, so the server computes the whole of the new
  * state and the browser never displays a number it has not confirmed. A
  * `<select>` carries one, because the choice is the interaction.
  */
- | {
-    op: "action";
-    name: string;
-    query?: string;
+export interface DeclaredAction {
+    action: string;
+    list?: string;
+    row?: string;
     key?: string;
     cell?: string;
     value?: string;
-};
-/** One query's result: the cells of a single tuple. Every value is a string. */
-export type QueryResult = Record<string, string>;
-/**
- * A query that returns many tuples — see docs/reference/server.md, "Queries".
- *
- * Two results, because a list widget must be told the difference. `rows` is
- * the entire set and therefore also the order; `patch` names only what
- * changed and leaves everything it does not name alone. Add and remove are
- * one result rather than two because the interesting cases are both at once
- * — a row whose sort key changed has to move, a swap is one out and one in —
- * and two messages would paint the intermediate state.
- *
- * `op` is the same discriminant word the request union uses, so one
- * vocabulary runs in both directions. It is therefore a reserved cell name:
- * a tuple with a cell called `op` whose value is `rows` or `patch` would be
- * read as a projection.
- */
-export type Projection = {
-    op: "rows";
-    rows: QueryResult[];
-} | {
-    op: "patch";
-    rows?: QueryResult[];
-    drop?: string[];
-};
-/** A tuple is the sugar and the common case; a projection says so. */
-export type HubResult = QueryResult | Projection;
-export declare function isProjection(result: HubResult): result is Projection;
+}
+export type HubRequest = LbOperation | DeclaredAction;
 /**
- * Every response on the data channel is the same shape, whether it is a
- * cold start or the narrowest refresh. The hub does not know which case
- * it is in.
+ * The reserved prefix is the whole of the discriminant. Nothing else tells
+ * an operation from a declared action, on the wire or anywhere else.
  */
-export type HubData = Record<string, HubResult>;
+export declare function isOperation(request: HubRequest): request is LbOperation;
 /**
- * What a list widget implements. The hub delivers a projection by calling
- * this and stops; where a row goes is the widget's, because only the widget
- * knows whether it sorts, groups, or appends.
+ * The two hooks a list widget may implement, both optional.
+ *
+ * The hub reconciles every list scope itself, so a widget supplies placement
+ * and scaffolding and nothing else. A scope that implements neither is a
+ * plain element with a row template inside it, which is why there is no
+ * repeater widget.
  *
- * One protocol name, not a table of tag names — the hub tests for the method,
- * never for the element.
+ * They are methods on an element the hub does not own, so they carry the
+ * `lb` prefix that Loadbare reserves for exactly that — see
+ * docs/reference/custom-elements.md.
  */
-export interface HubRowHost {
-    acceptRows(result: Projection): void;
+export interface ListHost {
+    /**
+     * Where a row belongs, called with the row detached on its first
+     * appearance. Without it a row lands immediately before the template, so
+     * rows accumulate in the order they arrive.
+     */
+    lbPlaceRow?(el: Element, row: Row, template: HTMLTemplateElement): void;
+    /** Called once after a whole result has landed, for derived scaffolding. */
+    lbRowsLanded?(): void;
 }
 //# sourceMappingURL=lb-types.d.ts.map

package/dist/core/lb-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lb-types.d.ts","sourceRoot":"","sources":["../../core/lb-types.ts"],"names":[],"mappings":"AAEA,oEAAoE;AACpE,MAAM,MAAM,UAAU,GAClB;IACE,EAAE,EAAE,aAAa,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,GACD;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GACrE;IACE,EAAE,EAAE,cAAc,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,GACD;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE;AACpD;;;;;;;;;;;;GAYG;GACD;IACE,EAAE,EAAE,QAAQ,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,EAAE,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE3D,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,CAAC;AAEjD,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,IAAI,UAAU,CAGpE;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC"}
+{"version":3,"file":"lb-types.d.ts","sourceRoot":"","sources":["../../core/lb-types.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EAElB,MAAM,mBAAmB,CAAC;AAE3B;;;;;;;GAOG;AACH,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,WAAW,KAAK;IACpB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;CAClB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,UAAU,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC;AAEvC,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,IAAI,KAAK,CAE3D;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG,UAAU,CAAC;AAEzC;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GACnB;IACE,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,GACD;IAAE,MAAM,EAAE,OAAO,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/D;IACE,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,GACD;IACE,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEN;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,IAAI,WAAW,CAEvE;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;OAIG;IACH,UAAU,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAExE,4EAA4E;IAC5E,YAAY,CAAC,IAAI,IAAI,CAAC;CACvB"}

package/dist/core/lb-types.js

@@ -1,5 +1,14 @@
+/// <reference lib="dom" />
 // The wire vocabulary. Shared by browser and server.
-export function isProjection(result) {
-    const op = result.op;
-    return op === "rows" || op === "patch";
+import { LB_RESERVED_PREFIX, } from "./lb-constants.js";
+export function isPatch(result) {
+    return !Array.isArray(result);
 }
+/**
+ * The reserved prefix is the whole of the discriminant. Nothing else tells
+ * an operation from a declared action, on the wire or anywhere else.
+ */
+export function isOperation(request) {
+    return request.action.startsWith(LB_RESERVED_PREFIX);
+}
+//# sourceMappingURL=lb-types.js.map

package/dist/core/lb-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lb-types.js","sourceRoot":"","sources":["../../core/lb-types.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAE3B,qDAAqD;AAErD,OAAO,EAKL,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAuC3B,MAAM,UAAU,OAAO,CAAC,MAAkB;IACxC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAwED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAAmB;IAC7C,OAAO,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvD,CAAC","sourcesContent":["/// <reference lib=\"dom\" />\n\n// The wire vocabulary. Shared by browser and server.\n\nimport {\n  ACTION_CELL_CHANGE,\n  ACTION_ROW_DELETE,\n  ACTION_ROW_INSERT,\n  ACTION_ROW_UPDATE,\n  LB_RESERVED_PREFIX,\n} from \"./lb-constants.js\";\n\n/**\n * One row: its columns, by name.\n *\n * A value is whatever the server serialized. The hub knows nothing about its\n * type and enforces nothing: it hands each value to the browser untouched,\n * and the browser renders it as it sees fit. What a number, a date or a null\n * should look like is the application's decision, made in the query.\n */\nexport type Row = Record<string, unknown>;\n\n/**\n * Part of a list — see docs/reference/server.md, \"Queries\".\n *\n * Rows named here arrive or are updated, keys in `drop` are gone, and\n * anything unnamed is left alone: its contents, and its place in whatever\n * order the widget is keeping. Add and remove are one result rather than two\n * because the interesting cases are both at once — a row whose sort key\n * changed has to move, a swap is one out and one in — and two messages would\n * paint the intermediate state.\n */\nexport interface Patch {\n  rows?: Row[];\n  drop?: unknown[];\n}\n\n/**\n * What a list answers with.\n *\n * An array is the entire set and therefore also the order: a row whose key\n * is not in it is gone. A Patch disturbs only what it names.\n *\n * `Array.isArray` tells the two apart, which is why no column name has to be\n * reserved to carry a discriminant. A list answering with an object is a\n * patch, because the declaration already said this name answers with rows.\n */\nexport type ListResult = Row[] | Patch;\n\nexport function isPatch(result: ListResult): result is Patch {\n  return !Array.isArray(result);\n}\n\n/**\n * What any one name answers with. Which of the two it is comes from the\n * query's own declaration, never from inspecting the value.\n */\nexport type HubResult = Row | ListResult;\n\n/**\n * Every response on the data channel is the same shape, whether it is a cold\n * start or the narrowest refresh. The hub does not know which case it is in.\n *\n * A name rides as an object key and is labelled by nothing, which is why the\n * response direction never needed a noun for the addressable thing.\n */\nexport type HubData = Record<string, HubResult>;\n\n/**\n * The four operations — docs/reference/data-binding.md. The set is closed.\n *\n * `action` carries the value of `lb-action` verbatim, so the attribute, the\n * wire field and the CRUD key are one vocabulary with no translation step.\n * The scope field is `list` here because all four are list operations: each\n * needs a key, and a key exists only on a live row inside a list.\n */\nexport type LbOperation =\n  | {\n      action: typeof ACTION_ROW_INSERT;\n      list: string;\n      values: Record<string, string>;\n    }\n  | { action: typeof ACTION_ROW_DELETE; list: string; key: string }\n  | {\n      action: typeof ACTION_ROW_UPDATE;\n      list: string;\n      key: string;\n      values: Record<string, string>;\n    }\n  | {\n      action: typeof ACTION_CELL_CHANGE;\n      list: string;\n      key: string;\n      cell: string;\n      value: string;\n    };\n\n/**\n * Everything that is not one of the four.\n *\n * The name is the application's and is looked up in the page's declared\n * actions. What keeps this from being an RPC endpoint is that the name must\n * already appear in the page's requests: the browser cannot reach anything the\n * page has not published, and there is no argument list — only where the\n * interaction happened and, where a control has one, its value.\n *\n * The scope field is `list` or `row`, whichever attribute scoped the element\n * the interaction came from, so an action fired from a single-row scope says\n * so. A button carries no value, so the server computes the whole of the new\n * state and the browser never displays a number it has not confirmed. A\n * `<select>` carries one, because the choice is the interaction.\n */\nexport interface DeclaredAction {\n  action: string;\n  list?: string;\n  row?: string;\n  key?: string;\n  cell?: string;\n  value?: string;\n}\n\nexport type HubRequest = LbOperation | DeclaredAction;\n\n/**\n * The reserved prefix is the whole of the discriminant. Nothing else tells\n * an operation from a declared action, on the wire or anywhere else.\n */\nexport function isOperation(request: HubRequest): request is LbOperation {\n  return request.action.startsWith(LB_RESERVED_PREFIX);\n}\n\n/**\n * The two hooks a list widget may implement, both optional.\n *\n * The hub reconciles every list scope itself, so a widget supplies placement\n * and scaffolding and nothing else. A scope that implements neither is a\n * plain element with a row template inside it, which is why there is no\n * repeater widget.\n *\n * They are methods on an element the hub does not own, so they carry the\n * `lb` prefix that Loadbare reserves for exactly that — see\n * docs/reference/custom-elements.md.\n */\nexport interface ListHost {\n  /**\n   * Where a row belongs, called with the row detached on its first\n   * appearance. Without it a row lands immediately before the template, so\n   * rows accumulate in the order they arrive.\n   */\n  lbPlaceRow?(el: Element, row: Row, template: HTMLTemplateElement): void;\n\n  /** Called once after a whole result has landed, for derived scaffolding. */\n  lbRowsLanded?(): void;\n}\n"]}

package/dist/hub/lb-apply.d.ts

@@ -1,13 +1,37 @@
-import { type QueryResult, type HubData } from "../core/lb-types";
+import { type HubData, type ListResult, type Row } from "../core/lb-types.js";
 /**
- * Fill one scope from one tuple.
+ * A form control whose state is its `value`: a `<select>`, a `<textarea>`,
+ * or an `<input>` of any type but checkbox, radio and file. Landing and
+ * gathering draw the same line, so a value read back from a form is the one
+ * that landed there.
+ *
+ * Told apart by tag name and type rather than by class, so it holds for an
+ * element from any document.
+ */
+export declare function isValueControl(el: Element): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+/**
+ * Fill one scope from one row.
  *
  * The root counts as a cell if it carries one. A `<tr>` holds its cells in
  * `<td>` children, but `<option>`'s content model is text, so an option row
  * has to be the cell it displays. Requiring a wrapper there would require an
  * element HTML does not allow.
  */
-export declare function applyTuple(root: Element, cells: QueryResult): void;
-/** Land a whole response. Every query result arrives through here. */
+export declare function applyRow(root: Element, row: Row): void;
+/**
+ * Land a list result in a list scope.
+ *
+ * An array is the whole set, so it decides membership and order: every row is
+ * placed in the order given, and a row whose key did not arrive is gone. A
+ * patch disturbs only what it names — a row it did not mention keeps its
+ * contents and its position.
+ *
+ * A widget that carries `lbPlaceRow` decides where a row goes, because only
+ * it knows whether it sorts or groups. Without it a row lands immediately
+ * before the template, so rows accumulate in the order they arrive and the
+ * template stays put as the insertion marker.
+ */
+export declare function applyList(scope: Element, result: ListResult): void;
+/** Land a whole response. Every result arrives through here. */
 export declare function applyData(root: ParentNode, data: HubData): void;
 //# sourceMappingURL=lb-apply.d.ts.map

package/dist/hub/lb-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lb-apply.d.ts","sourceRoot":"","sources":["../../hub/lb-apply.ts"],"names":[],"mappings":"AAcA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,OAAO,EAEb,MAAM,kBAAkB,CAAC;AAkB1B;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAMlE;AAmBD,sEAAsE;AACtE,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAY/D"}
+{"version":3,"file":"lb-apply.d.ts","sourceRoot":"","sources":["../../hub/lb-apply.ts"],"names":[],"mappings":"AA4BA,OAAO,EAEL,KAAK,OAAO,EAEZ,KAAK,UAAU,EACf,KAAK,GAAG,EACT,MAAM,qBAAqB,CAAC;AAK7B;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,EAAE,EAAE,OAAO,GACV,EAAE,IAAI,gBAAgB,GAAG,iBAAiB,GAAG,mBAAmB,CAMlE;AAgED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,CAMtD;AA2CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,CAgElE;AAED,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAkC/D"}

package/dist/hub/lb-apply.js

@@ -2,76 +2,263 @@
 /**
  * Landing data on a live host — see docs/reference/data-binding.md.
  *
- * This is one file rather than part of the hub because a list widget needs
- * the same operation. It clones a row and fills it with a tuple, and filling
- * a row is filling a scope: the only difference is how much of the page the
- * root covers. A widget imports `applyTuple` the way it imports `ATTR_VALUE`,
- * so there is one implementation of what a cell means and nobody reaches into
- * anybody's children.
+ * One containment ladder, and one function per rung. `applyData` lands a
+ * whole response, `applyList` lands one list result, `applyRow` fills one
+ * scope from one row. Filling a live row and filling a single-row scope are
+ * the same operation, and the only difference is how much of the page the
+ * root covers.
+ *
+ * The row machinery used to live in its own file because every list widget
+ * imported and called it. The hub reconciles a list scope itself now, so a
+ * widget supplies placement and scaffolding through two optional hooks and
+ * never sees a whole result. Cloning the template, matching a row to the
+ * element already showing it, and filling that element are the same in every
+ * list, so no widget can get them wrong.
+ */
+import { ATTR_CELL, ATTR_KEY, ATTR_KEY_VALUE, ATTR_LIST, ATTR_ROW, ATTR_ROW_COUNT, ATTR_VALUE, } from "../core/lb-constants.js";
+import { isPatch, } from "../core/lb-types.js";
+/** The input types whose state is not their `value`, or cannot be set. */
+const UNLANDED_INPUTS = ["checkbox", "radio", "file"];
+/**
+ * A form control whose state is its `value`: a `<select>`, a `<textarea>`,
+ * or an `<input>` of any type but checkbox, radio and file. Landing and
+ * gathering draw the same line, so a value read back from a form is the one
+ * that landed there.
+ *
+ * Told apart by tag name and type rather than by class, so it holds for an
+ * element from any document.
  */
-import { ATTR_CELL, ATTR_QUERY, ATTR_VALUE } from "../core/lb-constants";
-import { isProjection, } from "../core/lb-types";
+export function isValueControl(el) {
+    if (el.localName === "select" || el.localName === "textarea")
+        return true;
+    return (el.localName === "input" &&
+        !UNLANDED_INPUTS.includes(el.type));
+}
 /**
- * A cell lands one of two ways. A custom element owns whatever control it
+ * A cell lands one of three ways. A custom element owns whatever control it
  * wraps, so it receives the value as an attribute and renders it itself.
  * Because the browser runs `attributeChangedCallback` for attributes already
  * present when a widget upgrades, that is the same operation whether the host
  * was inserted a microsecond ago or an hour ago.
  *
- * A native element has no behavior of its own, so its value is its text.
- * The test is lexical — a hyphen in the tag name — and the hub holds no
- * knowledge of any particular element.
+ * A form control shows its state as its `value`, so that is where the value
+ * goes; its text is its options, for a select. Any other native element has
+ * no behavior of its own, so its value is its text. Either one also carries
+ * the value as `lb-value`, so a stylesheet can select on what landed.
+ * Checkboxes and radio buttons are not implemented, and receive nothing — see
+ * docs/TECHREF-1.0.md, "Blockers".
  */
 function land(el, value) {
-    if (el.localName.includes("-"))
+    // Untouched, whatever the server sent: the browser decides what a
+    // non-string looks like. See Row in core/lb-types.ts.
+    if (el.localName.includes("-")) {
         el.setAttribute(ATTR_VALUE, value);
-    else
+    }
+    else if (isValueControl(el)) {
+        el.value = value;
+        el.setAttribute(ATTR_VALUE, value);
+    }
+    else if (el.localName === "input") {
+        console.warn(`lb-hub: a value does not land on <input type="${el.type}">, ignoring`, el);
+    }
+    else {
         el.textContent = value;
+        el.setAttribute(ATTR_VALUE, value);
+    }
 }
 /**
- * Fill one scope from one tuple.
+ * Whether an element under `root` belongs to root's scope, rather than to a
+ * scope nested inside it.
+ *
+ * Both scope attributes scope their DOM children, and a nested one of either
+ * kind begins a new scope (docs/reference/data-binding.md). So a descendant
+ * is in root's scope unless something between it and root — the element
+ * itself included — carries one. Root's own attribute does not count: root is
+ * the scope being filled, whatever it carries.
+ */
+function inScope(root, el) {
+    for (let node = el; node && node !== root;) {
+        if (node.hasAttribute(ATTR_LIST) || node.hasAttribute(ATTR_ROW)) {
+            return false;
+        }
+        node = node.parentElement;
+    }
+    return true;
+}
+/** Root if it matches, then every descendant in root's scope that does. */
+function within(root, selector) {
+    const found = root.matches(selector) ? [root] : [];
+    for (const el of root.querySelectorAll(selector)) {
+        if (inScope(root, el))
+            found.push(el);
+    }
+    return found;
+}
+/**
+ * Fill one scope from one row.
  *
  * The root counts as a cell if it carries one. A `<tr>` holds its cells in
  * `<td>` children, but `<option>`'s content model is text, so an option row
  * has to be the cell it displays. Requiring a wrapper there would require an
  * element HTML does not allow.
  */
-export function applyTuple(root, cells) {
-    for (const [cell, value] of Object.entries(cells)) {
-        const selector = `[${ATTR_CELL}="${cell}"]`;
-        if (root.matches(selector))
-            land(root, value);
-        for (const el of root.querySelectorAll(selector))
+export function applyRow(root, row) {
+    for (const [column, value] of Object.entries(row)) {
+        for (const el of within(root, `[${ATTR_CELL}="${column}"]`)) {
             land(el, value);
+        }
     }
 }
 /**
- * A projection has to reach a widget. A native element has one destination
- * for a value and no way to acquire children, so a list is not something it
- * can be asked to show.
+ * The row template: the one the developer wrote inside this list scope, or
+ * null when this scope shows nothing. A template inside a nested scope is
+ * that scope's.
+ *
+ * A scope with no template is bound to the list without displaying it.
+ * That is not a mistake, so it is silent. A template that does not name its
+ * key column is a mistake, and says so.
  */
-function landRows(scope, query, result) {
-    const host = scope;
-    if (typeof host.acceptRows !== "function") {
-        console.error(`lb-hub: query '${query}' returned rows, but <${scope.localName}> ` +
-            `is not a list widget`);
+function templateIn(scope) {
+    const template = within(scope, "template")[0];
+    if (!template)
+        return null;
+    if (!template.getAttribute(ATTR_KEY)) {
+        console.error(`lb-hub: the <template> in <${scope.localName}> has no ${ATTR_KEY} ` +
+            `naming the column that identifies a row`);
+        return null;
+    }
+    return template;
+}
+/**
+ * The rows already showing, by the key value each carries. Only a live row
+ * carries one: the template names the key column under a different name.
+ *
+ * A row of a nested scope is that scope's. A row's own `lb-list` or `lb-row`
+ * names what it displays, not which list it is a row of, so the walk starts
+ * at its parent.
+ */
+function showing(scope) {
+    const rows = new Map();
+    for (const el of scope.querySelectorAll(`[${ATTR_KEY_VALUE}]`)) {
+        if (inScope(scope, el.parentElement)) {
+            rows.set(el.getAttribute(ATTR_KEY_VALUE), el);
+        }
+    }
+    return rows;
+}
+/**
+ * Land a list result in a list scope.
+ *
+ * An array is the whole set, so it decides membership and order: every row is
+ * placed in the order given, and a row whose key did not arrive is gone. A
+ * patch disturbs only what it names — a row it did not mention keeps its
+ * contents and its position.
+ *
+ * A widget that carries `lbPlaceRow` decides where a row goes, because only
+ * it knows whether it sorts or groups. Without it a row lands immediately
+ * before the template, so rows accumulate in the order they arrive and the
+ * template stays put as the insertion marker.
+ */
+export function applyList(scope, result) {
+    const template = templateIn(scope);
+    if (!template)
         return;
+    const keyColumn = template.getAttribute(ATTR_KEY);
+    const shown = showing(scope);
+    const host = scope;
+    const whole = !isPatch(result);
+    const place = (el, row) => {
+        if (host.lbPlaceRow)
+            host.lbPlaceRow(el, row, template);
+        else
+            template.parentElement.insertBefore(el, template);
+    };
+    const upsert = (row) => {
+        if (row[keyColumn] === undefined) {
+            console.error(`lb-hub: a row for <${scope.localName}> has no '${keyColumn}' column`);
+            return null;
+        }
+        // The key is stored on the row as an attribute and read back from
+        // there, so it is compared as the string the attribute holds.
+        const key = String(row[keyColumn]);
+        let el = shown.get(key);
+        const fresh = el === undefined;
+        if (!el) {
+            el = template.content.firstElementChild.cloneNode(true);
+            el.setAttribute(ATTR_KEY_VALUE, key);
+            shown.set(key, el);
+        }
+        // Fill before insertion. The attributes are already there when the row
+        // upgrades, which is the same thing that makes hydration and refresh one
+        // operation everywhere else.
+        applyRow(el, row);
+        if (fresh || whole)
+            place(el, row);
+        return key;
+    };
+    if (Array.isArray(result)) {
+        const arrived = new Set();
+        for (const row of result) {
+            const key = upsert(row);
+            if (key !== null)
+                arrived.add(key);
+        }
+        for (const [key, el] of shown)
+            if (!arrived.has(key))
+                el.remove();
+    }
+    else {
+        for (const row of result.rows ?? [])
+            upsert(row);
+        for (const key of result.drop ?? [])
+            shown.get(String(key))?.remove();
     }
-    host.acceptRows(result);
+    // How many rows are showing, counted from the DOM rather than from either
+    // branch above, so a whole set and a patch report the same fact the same
+    // way.
+    //
+    // It is stamped here because only this function knows the count: it is the
+    // one conditional a page cannot be sent, since the server answers with rows
+    // and says nothing about how many survived reconciliation. A page says what
+    // an empty list looks like in a stylesheet, and no list widget carries code
+    // for it. See docs/reference/data-binding.md.
+    scope.setAttribute(ATTR_ROW_COUNT, String(showing(scope).size));
+    // Derived scaffolding — a section heading, an <optgroup> — goes when its
+    // last row does, and only the widget knows it exists.
+    host.lbRowsLanded?.();
 }
-/** Land a whole response. Every query result arrives through here. */
+/** Land a whole response. Every result arrives through here. */
 export function applyData(root, data) {
-    for (const [query, result] of Object.entries(data)) {
-        const scopes = root.querySelectorAll(`[${ATTR_QUERY}="${query}"]`);
-        if (scopes.length === 0) {
-            console.warn(`lb-hub: no scope for query '${query}', skipping`);
+    for (const [name, result] of Object.entries(data)) {
+        const lists = root.querySelectorAll(`[${ATTR_LIST}="${name}"]`);
+        const rows = root.querySelectorAll(`[${ATTR_ROW}="${name}"]`);
+        if (lists.length === 0 && rows.length === 0) {
+            console.warn(`lb-hub: no scope for '${name}', skipping`);
             continue;
         }
-        for (const scope of scopes) {
-            if (isProjection(result))
-                landRows(scope, query, result);
-            else
-                applyTuple(scope, result);
+        // Cardinality is a property of the name, so one name is a list or a row
+        // and never both. Two spellings of it on one page is a mistake in the
+        // markup rather than a case to reconcile.
+        if (lists.length > 0 && rows.length > 0) {
+            console.error(`lb-hub: '${name}' is bound as a list in one place and a row in ` +
+                `another; a name answers with one shape`);
+            continue;
+        }
+        if (lists.length > 0) {
+            for (const scope of lists)
+                applyList(scope, result);
+            continue;
+        }
+        // The only disagreement visible from here: a patch and a row are both
+        // objects, so an array arriving at a row scope is the one case the
+        // browser can name. createHub holds the stronger check, because it knows
+        // what the query declared.
+        if (Array.isArray(result)) {
+            console.error(`lb-hub: '${name}' is bound with ${ATTR_ROW} but answered with rows`);
+            continue;
         }
+        for (const scope of rows)
+            applyRow(scope, result);
     }
 }
+//# sourceMappingURL=lb-apply.js.map

package/dist/hub/lb-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lb-apply.js","sourceRoot":"","sources":["../../hub/lb-apply.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference lib=\"dom\" />\n\n/**\n * Landing data on a live host — see docs/reference/data-binding.md.\n *\n * One containment ladder, and one function per rung. `applyData` lands a\n * whole response, `applyList` lands one list result, `applyRow` fills one\n * scope from one row. Filling a live row and filling a single-row scope are\n * the same operation, and the only difference is how much of the page the\n * root covers.\n *\n * The row machinery used to live in its own file because every list widget\n * imported and called it. The hub reconciles a list scope itself now, so a\n * widget supplies placement and scaffolding through two optional hooks and\n * never sees a whole result. Cloning the template, matching a row to the\n * element already showing it, and filling that element are the same in every\n * list, so no widget can get them wrong.\n */\n\nimport {\n  ATTR_CELL,\n  ATTR_KEY,\n  ATTR_KEY_VALUE,\n  ATTR_LIST,\n  ATTR_ROW,\n  ATTR_ROW_COUNT,\n  ATTR_VALUE,\n} from \"../core/lb-constants.js\";\nimport {\n  isPatch,\n  type HubData,\n  type ListHost,\n  type ListResult,\n  type Row,\n} from \"../core/lb-types.js\";\n\n/** The input types whose state is not their `value`, or cannot be set. */\nconst UNLANDED_INPUTS = [\"checkbox\", \"radio\", \"file\"];\n\n/**\n * A form control whose state is its `value`: a `<select>`, a `<textarea>`,\n * or an `<input>` of any type but checkbox, radio and file. Landing and\n * gathering draw the same line, so a value read back from a form is the one\n * that landed there.\n *\n * Told apart by tag name and type rather than by class, so it holds for an\n * element from any document.\n */\nexport function isValueControl(\n  el: Element,\n): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement {\n  if (el.localName === \"select\" || el.localName === \"textarea\") return true;\n  return (\n    el.localName === \"input\" &&\n    !UNLANDED_INPUTS.includes((el as HTMLInputElement).type)\n  );\n}\n\n/**\n * A cell lands one of three ways. A custom element owns whatever control it\n * wraps, so it receives the value as an attribute and renders it itself.\n * Because the browser runs `attributeChangedCallback` for attributes already\n * present when a widget upgrades, that is the same operation whether the host\n * was inserted a microsecond ago or an hour ago.\n *\n * A form control shows its state as its `value`, so that is where the value\n * goes; its text is its options, for a select. Any other native element has\n * no behavior of its own, so its value is its text. Either one also carries\n * the value as `lb-value`, so a stylesheet can select on what landed.\n * Checkboxes and radio buttons are not implemented, and receive nothing — see\n * docs/TECHREF-1.0.md, \"Blockers\".\n */\nfunction land(el: Element, value: unknown): void {\n  // Untouched, whatever the server sent: the browser decides what a\n  // non-string looks like. See Row in core/lb-types.ts.\n  if (el.localName.includes(\"-\")) {\n    el.setAttribute(ATTR_VALUE, value as string);\n  } else if (isValueControl(el)) {\n    el.value = value as string;\n    el.setAttribute(ATTR_VALUE, value as string);\n  } else if (el.localName === \"input\") {\n    console.warn(\n      `lb-hub: a value does not land on <input type=\"${(el as HTMLInputElement).type}\">, ignoring`,\n      el,\n    );\n  } else {\n    el.textContent = value as string;\n    el.setAttribute(ATTR_VALUE, value as string);\n  }\n}\n\n/**\n * Whether an element under `root` belongs to root's scope, rather than to a\n * scope nested inside it.\n *\n * Both scope attributes scope their DOM children, and a nested one of either\n * kind begins a new scope (docs/reference/data-binding.md). So a descendant\n * is in root's scope unless something between it and root — the element\n * itself included — carries one. Root's own attribute does not count: root is\n * the scope being filled, whatever it carries.\n */\nfunction inScope(root: Element, el: Element): boolean {\n  for (let node: Element | null = el; node && node !== root;) {\n    if (node.hasAttribute(ATTR_LIST) || node.hasAttribute(ATTR_ROW)) {\n      return false;\n    }\n    node = node.parentElement;\n  }\n  return true;\n}\n\n/** Root if it matches, then every descendant in root's scope that does. */\nfunction within(root: Element, selector: string): Element[] {\n  const found: Element[] = root.matches(selector) ? [root] : [];\n  for (const el of root.querySelectorAll(selector)) {\n    if (inScope(root, el)) found.push(el);\n  }\n  return found;\n}\n\n/**\n * Fill one scope from one row.\n *\n * The root counts as a cell if it carries one. A `<tr>` holds its cells in\n * `<td>` children, but `<option>`'s content model is text, so an option row\n * has to be the cell it displays. Requiring a wrapper there would require an\n * element HTML does not allow.\n */\nexport function applyRow(root: Element, row: Row): void {\n  for (const [column, value] of Object.entries(row)) {\n    for (const el of within(root, `[${ATTR_CELL}=\"${column}\"]`)) {\n      land(el, value);\n    }\n  }\n}\n\n/**\n * The row template: the one the developer wrote inside this list scope, or\n * null when this scope shows nothing. A template inside a nested scope is\n * that scope's.\n *\n * A scope with no template is bound to the list without displaying it.\n * That is not a mistake, so it is silent. A template that does not name its\n * key column is a mistake, and says so.\n */\nfunction templateIn(scope: Element): HTMLTemplateElement | null {\n  const template = within(scope, \"template\")[0] as\n    HTMLTemplateElement | undefined;\n  if (!template) return null;\n  if (!template.getAttribute(ATTR_KEY)) {\n    console.error(\n      `lb-hub: the <template> in <${scope.localName}> has no ${ATTR_KEY} ` +\n        `naming the column that identifies a row`,\n    );\n    return null;\n  }\n  return template;\n}\n\n/**\n * The rows already showing, by the key value each carries. Only a live row\n * carries one: the template names the key column under a different name.\n *\n * A row of a nested scope is that scope's. A row's own `lb-list` or `lb-row`\n * names what it displays, not which list it is a row of, so the walk starts\n * at its parent.\n */\nfunction showing(scope: Element): Map<string, Element> {\n  const rows = new Map<string, Element>();\n  for (const el of scope.querySelectorAll(`[${ATTR_KEY_VALUE}]`)) {\n    if (inScope(scope, el.parentElement!)) {\n      rows.set(el.getAttribute(ATTR_KEY_VALUE)!, el);\n    }\n  }\n  return rows;\n}\n\n/**\n * Land a list result in a list scope.\n *\n * An array is the whole set, so it decides membership and order: every row is\n * placed in the order given, and a row whose key did not arrive is gone. A\n * patch disturbs only what it names — a row it did not mention keeps its\n * contents and its position.\n *\n * A widget that carries `lbPlaceRow` decides where a row goes, because only\n * it knows whether it sorts or groups. Without it a row lands immediately\n * before the template, so rows accumulate in the order they arrive and the\n * template stays put as the insertion marker.\n */\nexport function applyList(scope: Element, result: ListResult): void {\n  const template = templateIn(scope);\n  if (!template) return;\n  const keyColumn = template.getAttribute(ATTR_KEY)!;\n  const shown = showing(scope);\n  const host = scope as Element & ListHost;\n  const whole = !isPatch(result);\n\n  const place = (el: Element, row: Row): void => {\n    if (host.lbPlaceRow) host.lbPlaceRow(el, row, template);\n    else template.parentElement!.insertBefore(el, template);\n  };\n\n  const upsert = (row: Row): string | null => {\n    if (row[keyColumn] === undefined) {\n      console.error(\n        `lb-hub: a row for <${scope.localName}> has no '${keyColumn}' column`,\n      );\n      return null;\n    }\n    // The key is stored on the row as an attribute and read back from\n    // there, so it is compared as the string the attribute holds.\n    const key = String(row[keyColumn]);\n    let el = shown.get(key);\n    const fresh = el === undefined;\n    if (!el) {\n      el = template.content.firstElementChild!.cloneNode(true) as Element;\n      el.setAttribute(ATTR_KEY_VALUE, key);\n      shown.set(key, el);\n    }\n    // Fill before insertion. The attributes are already there when the row\n    // upgrades, which is the same thing that makes hydration and refresh one\n    // operation everywhere else.\n    applyRow(el, row);\n    if (fresh || whole) place(el, row);\n    return key;\n  };\n\n  if (Array.isArray(result)) {\n    const arrived = new Set<string>();\n    for (const row of result) {\n      const key = upsert(row);\n      if (key !== null) arrived.add(key);\n    }\n    for (const [key, el] of shown) if (!arrived.has(key)) el.remove();\n  } else {\n    for (const row of result.rows ?? []) upsert(row);\n    for (const key of result.drop ?? []) shown.get(String(key))?.remove();\n  }\n\n  // How many rows are showing, counted from the DOM rather than from either\n  // branch above, so a whole set and a patch report the same fact the same\n  // way.\n  //\n  // It is stamped here because only this function knows the count: it is the\n  // one conditional a page cannot be sent, since the server answers with rows\n  // and says nothing about how many survived reconciliation. A page says what\n  // an empty list looks like in a stylesheet, and no list widget carries code\n  // for it. See docs/reference/data-binding.md.\n  scope.setAttribute(ATTR_ROW_COUNT, String(showing(scope).size));\n\n  // Derived scaffolding — a section heading, an <optgroup> — goes when its\n  // last row does, and only the widget knows it exists.\n  host.lbRowsLanded?.();\n}\n\n/** Land a whole response. Every result arrives through here. */\nexport function applyData(root: ParentNode, data: HubData): void {\n  for (const [name, result] of Object.entries(data)) {\n    const lists = root.querySelectorAll(`[${ATTR_LIST}=\"${name}\"]`);\n    const rows = root.querySelectorAll(`[${ATTR_ROW}=\"${name}\"]`);\n    if (lists.length === 0 && rows.length === 0) {\n      console.warn(`lb-hub: no scope for '${name}', skipping`);\n      continue;\n    }\n    // Cardinality is a property of the name, so one name is a list or a row\n    // and never both. Two spellings of it on one page is a mistake in the\n    // markup rather than a case to reconcile.\n    if (lists.length > 0 && rows.length > 0) {\n      console.error(\n        `lb-hub: '${name}' is bound as a list in one place and a row in ` +\n          `another; a name answers with one shape`,\n      );\n      continue;\n    }\n    if (lists.length > 0) {\n      for (const scope of lists) applyList(scope, result as ListResult);\n      continue;\n    }\n    // The only disagreement visible from here: a patch and a row are both\n    // objects, so an array arriving at a row scope is the one case the\n    // browser can name. createHub holds the stronger check, because it knows\n    // what the query declared.\n    if (Array.isArray(result)) {\n      console.error(\n        `lb-hub: '${name}' is bound with ${ATTR_ROW} but answered with rows`,\n      );\n      continue;\n    }\n    for (const scope of rows) applyRow(scope, result as Row);\n  }\n}\n"]}

package/dist/hub/lb-hub.browser.d.ts

@@ -1,2 +1,2 @@
-export { applyData, applyTuple } from "./lb-apply";
+export { applyData, applyRow } from "./lb-apply.js";
 //# sourceMappingURL=lb-hub.browser.d.ts.map