@loadbare/app 0.16.0 → 0.17.0

package/dist/core/lb-types.js

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 // The wire vocabulary. Shared by browser and server.
-import { LB_RESERVED_PREFIX, LB_ROW_REQUESTS, ORDER_DESCENDING, ORDER_PARM_PREFIX, URL_COLUMN_PATH, } from "./lb-constants.js";
+import { FILTER_OPERATORS, LB_RESERVED_PREFIX, LB_ROW_REQUESTS, ORDER_DESCENDING, URL_COLUMN_PATH, } from "./lb-constants.js";
 export function isPatch(result) {
     return !Array.isArray(result);
 }
@@ -54,10 +54,6 @@ export function parseOrder(text) {
         return { column, descending };
     });
 }
-/** The query parm carrying the user's order for a query. */
-export function orderParm(query) {
-    return ORDER_PARM_PREFIX + query;
-}
 /** Strings compare as the user's language orders them. */
 const collator = new Intl.Collator();
 /** How a value sorts among values of other types: by its JSON type. */
@@ -100,22 +96,137 @@ export function compareValues(a, b) {
         return collator.compare(a, b);
     return collator.compare(JSON.stringify(a), JSON.stringify(b));
 }
-/** Compare two rows by an order's terms. */
-export function compareRows(a, b, terms) {
+/**
+ * A value read as a declared column type: a number for `number`, a boolean
+ * for `boolean`, text for `text`. A value that is no value of its type reads
+ * as missing, and compares as a null does. A column with no declared type
+ * reads as it arrived.
+ */
+export function readAs(value, type) {
+    if (type === undefined || value === null || value === undefined)
+        return value;
+    switch (type) {
+        case "number": {
+            if (typeof value === "number")
+                return value;
+            if (typeof value !== "string" || value.trim() === "")
+                return undefined;
+            const n = Number(value);
+            return Number.isNaN(n) ? undefined : n;
+        }
+        case "boolean":
+            if (typeof value === "boolean")
+                return value;
+            return value === "true" ? true : value === "false" ? false : undefined;
+        default:
+            return typeof value === "object" ? JSON.stringify(value) : String(value);
+    }
+}
+/** Compare two rows by an order's terms, each column read as its type. */
+export function compareRows(a, b, terms, types = {}) {
     for (const { column, descending } of terms) {
-        const c = compareValues(a[column], b[column]);
+        const c = compareValues(readAs(a[column], types[column]), readAs(b[column], types[column]));
         if (c !== 0)
             return descending ? -c : c;
     }
     return 0;
 }
+/** Where a filter's next term begins: whitespace before an operator. */
+const NEXT_TERM = new RegExp(`\\s+(?=${FILTER_OPERATORS.map((op) => op.replace(/[$^*]/g, "\\$&")).join("|")})`);
+/**
+ * A filter's terms, from its text: each an operator and the value after it,
+ * a new term beginning wherever whitespace comes before an operator, so a
+ * value may hold spaces. Text with no operator before it is `*=`. A term
+ * with no value is not yet a term, and is left out, so a filter being typed
+ * filters nothing until it says something. Nothing is evaluated.
+ */
+export function parseFilter(text) {
+    const terms = [];
+    for (const raw of text.trim().split(NEXT_TERM)) {
+        const operator = FILTER_OPERATORS.find((op) => raw.startsWith(op)) ?? "*=";
+        const value = raw.slice(raw.startsWith(operator) ? operator.length : 0);
+        if (value.trim() !== "")
+            terms.push({ operator, value: value.trim() });
+    }
+    return terms;
+}
+/**
+ * The filter's value as the column's own type, so a comparison is the one
+ * the order makes: a number for a number, a boolean for a boolean, text for
+ * anything else. Undefined when the text is no value of that type.
+ */
+function asTypeOf(text, like) {
+    if (typeof like === "number") {
+        const n = Number(text);
+        return text.trim() === "" || Number.isNaN(n) ? undefined : n;
+    }
+    if (typeof like === "boolean") {
+        return text === "true" ? true : text === "false" ? false : undefined;
+    }
+    return text;
+}
+/**
+ * Whether a column's value passes one term.
+ *
+ * `^=`, `$=` and `*=` read the value as text, ignoring case: it begins with,
+ * ends with or contains the term's value. The rest compare as the order
+ * compares, with the column read as its declared type, if it has one, and
+ * the term's value read as the column's type. A missing value, and one that
+ * is no value of its declared type, passes only `!=`.
+ */
+export function passesTerm(value, { operator, value: text }, type) {
+    if (value === null || value === undefined)
+        return operator === "!=";
+    if (operator === "^=" || operator === "$=" || operator === "*=") {
+        const have = String(value).toLocaleLowerCase();
+        const want = text.toLocaleLowerCase();
+        if (operator === "^=")
+            return have.startsWith(want);
+        if (operator === "$=")
+            return have.endsWith(want);
+        return have.includes(want);
+    }
+    const read = readAs(value, type);
+    const typed = read === undefined ? undefined : asTypeOf(text, read);
+    if (typed === undefined)
+        return operator === "!=";
+    const c = compareValues(read, typed);
+    switch (operator) {
+        case "=":
+            return c === 0;
+        case "!=":
+            return c !== 0;
+        case "<":
+            return c < 0;
+        case "<=":
+            return c <= 0;
+        case ">":
+            return c > 0;
+        default:
+            return c >= 0;
+    }
+}
+/** Whether a column's value passes every term of a filter. */
+export function passes(value, terms, type) {
+    return terms.every((term) => passesTerm(value, term, type));
+}
+/**
+ * Where a row for `lb-url` leads, from a page and its query parms.
+ *
+ * A column whose name begins with `lb-` is Loadbare's, and never a query
+ * parm; every other column is one. An `lb-path` naming another page enters
+ * it with only the parms the row names. Otherwise the named parms are set,
+ * or taken out when empty, and the rest are kept.
+ *
+ * One rule on both sides of the wire: the server loads the page it names,
+ * and the hub writes the URL it names. The two must agree, or what the page
+ * shows would differ from what the address bar says.
+ */
 export function nextLocation(page, parms, row) {
     const named = {};
     for (const [name, value] of Object.entries(row)) {
-        if (name.startsWith(LB_RESERVED_PREFIX) &&
-            !name.startsWith(ORDER_PARM_PREFIX)) {
+        if (name.startsWith(LB_RESERVED_PREFIX))
             continue;
-        }
         named[name] = value === null || value === undefined ? "" : String(value);
     }
     const path = row[URL_COLUMN_PATH];

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

@@ -1 +1 @@
-{"version":3,"file":"lb-types.js","sourceRoot":"","sources":["../../core/lb-types.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference lib=\"dom\" />\n\n// The wire vocabulary. Shared by browser and server.\n\nimport {\n  KIND_ROW,\n  KIND_ROWS,\n  LB_RESERVED_PREFIX,\n  LB_ROW_REQUESTS,\n  ORDER_DESCENDING,\n  ORDER_PARM_PREFIX,\n  URL_COLUMN_PATH,\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 `rows` query's answer — see docs/reference/server.md, \"Queries\".\n *\n * Rows named here are added or updated, keys in `drop` are removed, and\n * anything unnamed is left alone. The hub places what it names by the\n * query's order. Add and remove are one result rather than two because the\n * interesting cases are both at once — a row whose sort key changed has to\n * move, a swap is one out and one in — and two messages would paint the\n * intermediate state.\n */\nexport interface Patch {\n  rows?: Row[];\n  drop?: unknown[];\n}\n\n/** A query's kind, declared by the server and carried by every answer. */\nexport type Kind = typeof KIND_ROW | typeof KIND_ROWS;\n\n/**\n * What a `rows` query answers with: all rows, or a patch. `Array.isArray`\n * tells the two apart. All rows arrive in the order the server chose, which\n * is the order they show in when the query declares none.\n */\nexport type RowsResult = Row[] | Patch;\n\nexport function isPatch(result: RowsResult): result is Patch {\n  return !Array.isArray(result);\n}\n\n/** What any one query answers with, as the application writes it. */\nexport type HubResult = Row | RowsResult;\n\n/**\n * What application code hands the engine: answers by query name. The engine\n * turns each into a response item, adding the kind and key the query\n * declared.\n */\nexport type HubData = Record<string, HubResult>;\n\n/**\n * One query's answer on the wire: its name, its kind, its key's column name,\n * and exactly one of a row, all rows, or a patch. A patch answers a `rows`\n * query only.\n *\n * A `rows` query also carries what it declared about order: the order the\n * server gives it, and whether the query reads the order parm itself.\n */\nexport interface ResponseItem {\n  query: string;\n  kind: Kind;\n  key: string;\n  row?: Row;\n  rows?: Row[];\n  patch?: Patch;\n  order?: string;\n  serverSortedByUrl?: boolean;\n}\n\n/** Every response the server sends: a page load and a request alike. */\nexport type HubResponse = ResponseItem[];\n\n/**\n * Every request has one shape. The name picks the handler; the rest is\n * present when the hub found it.\n */\nexport interface HubRequest {\n  name: string;\n  query?: string;\n  key?: string;\n  /**\n   * The rows a request acts on together, by key: those the user selected,\n   * for a request that names no one row. Never sent beside `key`.\n   */\n  keys?: string[];\n  values?: Record<string, string>;\n  /**\n   * The rows of the queries nested in a form, by query name, each with the\n   * values of its own controls: a set of rows gathered beside the form's\n   * own values.\n   */\n  rows?: Record<string, GatheredRow[]>;\n}\n\n/** One nested row a form gathered: its key, and its controls' values. */\nexport interface GatheredRow {\n  key: string;\n  values: Record<string, string>;\n}\n\n/**\n * The detail of the `lb-request-done` event: the request as the hub\n * completed and sent it, and what came of it. `items` is every response\n * item that landed because of it, in the order it landed. `error` is set\n * when the request's own round trip failed, and then nothing landed.\n */\nexport interface HubRequestDone {\n  request: HubRequest;\n  items: ResponseItem[];\n  error?: Error;\n  /** Set beside `error` when the handler refused the request. */\n  refusal?: HubRefusal;\n}\n\n/**\n * Why a handler refused a request, in words written for the user: a\n * message for the request as a whole, a message per column the request\n * gathered, or both. Sent with status 422; any other failure sends nothing.\n */\nexport interface HubRefusal {\n  message?: string;\n  columns?: Record<string, string>;\n}\n\n/** The fields a handler receives: the request, less its name. */\nexport type RequestFields = Omit<HubRequest, \"name\">;\n\n/** Whether a name is one of the requests Loadbare provides. */\nexport function isRowRequest(name: string): boolean {\n  return (LB_ROW_REQUESTS as readonly string[]).includes(name);\n}\n\n/**\n * A query string with some parms set, and the rest as they were. An empty\n * value takes its parm out, since empty is every parm's default and a\n * default is left out of the URL.\n *\n * One rule on both sides of the wire: the hub applies it to the address bar,\n * and the server to the query string it loads the page at after a request\n * returned `lb-url`. The two must agree, or what the page shows would differ\n * from what the address bar says.\n */\nexport function withQueryParms(\n  search: URLSearchParams,\n  parms: Record<string, string>,\n): URLSearchParams {\n  const next = new URLSearchParams(search);\n  for (const [name, value] of Object.entries(parms)) {\n    if (value === \"\") next.delete(name);\n    else next.set(name, value);\n  }\n  return next;\n}\n\n/**\n * A path names a page by its stub, and nothing finer. The bare path resolves\n * to `index`, the same convention a static file server follows.\n */\nexport function pageNameFor(path: string): string {\n  const name = path.replace(/^\\/+|\\/+$/g, \"\");\n  return name === \"\" ? \"index\" : name;\n}\n\n/**\n * Where a row for `lb-url` leads, from a page and its query parms.\n *\n * A column whose name begins with `lb-` is Loadbare's, and never a query\n * parm, except an order parm, which is one; every other column is one. An `lb-path` naming another page enters\n * it with only the parms the row names. Otherwise the named parms are set,\n * or taken out when empty, and the rest are kept.\n *\n * One rule on both sides of the wire: the server loads the page it names,\n * and the hub writes the URL it names. The two must agree, or what the page\n * shows would differ from what the address bar says.\n */\n/** One term of an order: a column, and whether it sorts descending. */\nexport interface OrderTerm {\n  column: string;\n  descending: boolean;\n}\n\n/**\n * An order's terms, from its text: columns separated by commas, each\n * descending when it begins with `-`. Throws on a term that names no column.\n * An empty text is no order.\n */\nexport function parseOrder(text: string): OrderTerm[] {\n  if (text.trim() === \"\") return [];\n  return text.split(\",\").map((raw) => {\n    const term = raw.trim();\n    const descending = term.startsWith(ORDER_DESCENDING);\n    const column = descending ? term.slice(ORDER_DESCENDING.length) : term;\n    if (column === \"\" || column.startsWith(ORDER_DESCENDING)) {\n      throw new Error(`the order '${text}' has a term naming no column`);\n    }\n    return { column, descending };\n  });\n}\n\n/** The query parm carrying the user's order for a query. */\nexport function orderParm(query: string): string {\n  return ORDER_PARM_PREFIX + query;\n}\n\n/** Strings compare as the user's language orders them. */\nconst collator = new Intl.Collator();\n\n/** How a value sorts among values of other types: by its JSON type. */\nfunction rank(value: unknown): number {\n  switch (typeof value) {\n    case \"boolean\":\n      return 0;\n    case \"number\":\n      return 1;\n    case \"string\":\n      return 2;\n    default:\n      return 3;\n  }\n}\n\n/**\n * Compare two column values, ascending.\n *\n * A value compares by its JSON type, and nothing is guessed: numbers\n * numerically, booleans false before true, strings as the user's language\n * orders them. A number that arrives as a string sorts as a string, so a\n * numeric sort column is sent as a JSON number. Null and a missing value\n * sort after everything, as Postgres sorts them ascending, and so first\n * descending.\n */\nexport function compareValues(a: unknown, b: unknown): number {\n  const missingA = a === null || a === undefined;\n  const missingB = b === null || b === undefined;\n  if (missingA || missingB) return missingA === missingB ? 0 : missingA ? 1 : -1;\n  const ra = rank(a);\n  const rb = rank(b);\n  if (ra !== rb) return ra - rb;\n  if (typeof a === \"number\") return a - (b as number);\n  if (typeof a === \"boolean\") return Number(a) - Number(b);\n  if (typeof a === \"string\") return collator.compare(a, b as string);\n  return collator.compare(JSON.stringify(a), JSON.stringify(b));\n}\n\n/** Compare two rows by an order's terms. */\nexport function compareRows(a: Row, b: Row, terms: OrderTerm[]): number {\n  for (const { column, descending } of terms) {\n    const c = compareValues(a[column], b[column]);\n    if (c !== 0) return descending ? -c : c;\n  }\n  return 0;\n}\n\nexport function nextLocation(\n  page: string,\n  parms: URLSearchParams,\n  row: Row,\n): { page: string; parms: URLSearchParams; moved: boolean } {\n  const named: Record<string, string> = {};\n  for (const [name, value] of Object.entries(row)) {\n    if (\n      name.startsWith(LB_RESERVED_PREFIX) &&\n      !name.startsWith(ORDER_PARM_PREFIX)\n    ) {\n      continue;\n    }\n    named[name] = value === null || value === undefined ? \"\" : String(value);\n  }\n  const path = row[URL_COLUMN_PATH];\n  const next = typeof path === \"string\" ? pageNameFor(path) : page;\n  const moved = next !== page;\n  return {\n    page: next,\n    parms: withQueryParms(moved ? new URLSearchParams() : parms, named),\n    moved,\n  };\n}\n\n/**\n * What the hub tells a custom element it did, in its own terms rather than\n * the browser's: a custom element implements any of these in place of\n * `connectedCallback` and its kin, which the builder refuses.\n *\n * Each is a method on an element the hub does not own, so it carries the\n * `lb` prefix Loadbare reserves for exactly that — see\n * docs/reference/custom-elements.md.\n */\nexport interface HubLifecycle {\n  /**\n   * Called once, after the hub has placed the element and every column has\n   * landed on it. An element under an `lb-show` that is off is placed inside\n   * its template, so it may not be rendered.\n   */\n  lbAttached?(): void;\n  /**\n   * Called once after a result has landed on an element holding rows, with\n   * every row in place and every stamp set. The hub reconciles and places\n   * every row itself, by the query's order, so a custom element reacts to\n   * rows and never places them.\n   */\n  lbRowsLanded?(): void;\n  /**\n   * Called once a request committed by this element, or by one inside it,\n   * has finished, innermost first and before `lb-request-done` is\n   * dispatched. `origin` is the element that committed.\n   */\n  lbRequestDone?(detail: HubRequestDone, origin: Element): void;\n  /** Called once, after the hub has removed the element. */\n  lbDetached?(): void;\n}\n"]}
+{"version":3,"file":"lb-types.js","sourceRoot":"","sources":["../../core/lb-types.ts"],"names":[],"mappings":"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","sourcesContent":["/// <reference lib=\"dom\" />\n\n// The wire vocabulary. Shared by browser and server.\n\nimport {\n  COLUMN_TYPES,\n  KIND_ROW,\n  FILTER_OPERATORS,\n  KIND_ROWS,\n  LB_RESERVED_PREFIX,\n  LB_ROW_REQUESTS,\n  ORDER_DESCENDING,\n  URL_COLUMN_PATH,\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 `rows` query's answer — see docs/reference/server.md, \"Queries\".\n *\n * Rows named here are added or updated, keys in `drop` are removed, and\n * anything unnamed is left alone. The hub places what it names by the\n * query's order. Add and remove are one result rather than two because the\n * interesting cases are both at once — a row whose sort key changed has to\n * move, a swap is one out and one in — and two messages would paint the\n * intermediate state.\n */\nexport interface Patch {\n  rows?: Row[];\n  drop?: unknown[];\n}\n\n/** A type a `rows` query may declare for a column — see COLUMN_TYPES. */\nexport type ColumnType = (typeof COLUMN_TYPES)[number];\n\n/** The types a `rows` query declares for its columns, by column. */\nexport type ColumnTypes = Record<string, ColumnType>;\n\n/** A query's kind, declared by the server and carried by every answer. */\nexport type Kind = typeof KIND_ROW | typeof KIND_ROWS;\n\n/**\n * What a `rows` query answers with: all rows, or a patch. `Array.isArray`\n * tells the two apart. All rows arrive in the order the server chose, which\n * is the order they show in when the query declares none.\n */\nexport type RowsResult = Row[] | Patch;\n\nexport function isPatch(result: RowsResult): result is Patch {\n  return !Array.isArray(result);\n}\n\n/** What any one query answers with, as the application writes it. */\nexport type HubResult = Row | RowsResult;\n\n/**\n * What application code hands the engine: answers by query name. The engine\n * turns each into a response item, adding the kind and key the query\n * declared.\n */\nexport type HubData = Record<string, HubResult>;\n\n/**\n * One query's answer on the wire: its name, its kind, its key's column name,\n * and exactly one of a row, all rows, or a patch. A patch answers a `rows`\n * query only.\n *\n * A `rows` query also carries the order and column types it declared, once,\n * on the answer that loads the page. The hub keeps them with the answer for\n * every answer after it.\n */\nexport interface ResponseItem {\n  query: string;\n  kind: Kind;\n  key: string;\n  row?: Row;\n  rows?: Row[];\n  patch?: Patch;\n  order?: string;\n  types?: ColumnTypes;\n}\n\n/** Every response the server sends: a page load and a request alike. */\nexport type HubResponse = ResponseItem[];\n\n/**\n * Every request has one shape. The name picks the handler; the rest is\n * present when the hub found it.\n */\nexport interface HubRequest {\n  name: string;\n  query?: string;\n  key?: string;\n  /**\n   * The rows a request acts on together, by key: those the user selected,\n   * for a request that names no one row. Never sent beside `key`.\n   */\n  keys?: string[];\n  values?: Record<string, string>;\n  /**\n   * The rows of the queries nested in a form, by query name, each with the\n   * values of its own controls: a set of rows gathered beside the form's\n   * own values.\n   */\n  rows?: Record<string, GatheredRow[]>;\n}\n\n/** One nested row a form gathered: its key, and its controls' values. */\nexport interface GatheredRow {\n  key: string;\n  values: Record<string, string>;\n}\n\n/**\n * The detail of the `lb-request-done` event: the request as the hub\n * completed and sent it, and what came of it. `items` is every response\n * item that landed because of it, in the order it landed. `error` is set\n * when the request's own round trip failed, and then nothing landed.\n */\nexport interface HubRequestDone {\n  request: HubRequest;\n  items: ResponseItem[];\n  error?: Error;\n  /** Set beside `error` when the handler refused the request. */\n  refusal?: HubRefusal;\n}\n\n/**\n * Why a handler refused a request, in words written for the user: a\n * message for the request as a whole, a message per column the request\n * gathered, or both. Sent with status 422; any other failure sends nothing.\n */\nexport interface HubRefusal {\n  message?: string;\n  columns?: Record<string, string>;\n}\n\n/** The fields a handler receives: the request, less its name. */\nexport type RequestFields = Omit<HubRequest, \"name\">;\n\n/** Whether a name is one of the requests Loadbare provides. */\nexport function isRowRequest(name: string): boolean {\n  return (LB_ROW_REQUESTS as readonly string[]).includes(name);\n}\n\n/**\n * A query string with some parms set, and the rest as they were. An empty\n * value takes its parm out, since empty is every parm's default and a\n * default is left out of the URL.\n *\n * One rule on both sides of the wire: the hub applies it to the address bar,\n * and the server to the query string it loads the page at after a request\n * returned `lb-url`. The two must agree, or what the page shows would differ\n * from what the address bar says.\n */\nexport function withQueryParms(\n  search: URLSearchParams,\n  parms: Record<string, string>,\n): URLSearchParams {\n  const next = new URLSearchParams(search);\n  for (const [name, value] of Object.entries(parms)) {\n    if (value === \"\") next.delete(name);\n    else next.set(name, value);\n  }\n  return next;\n}\n\n/**\n * A path names a page by its stub, and nothing finer. The bare path resolves\n * to `index`, the same convention a static file server follows.\n */\nexport function pageNameFor(path: string): string {\n  const name = path.replace(/^\\/+|\\/+$/g, \"\");\n  return name === \"\" ? \"index\" : name;\n}\n\n/** One term of an order: a column, and whether it sorts descending. */\nexport interface OrderTerm {\n  column: string;\n  descending: boolean;\n}\n\n/**\n * An order's terms, from its text: columns separated by commas, each\n * descending when it begins with `-`. Throws on a term that names no column.\n * An empty text is no order.\n */\nexport function parseOrder(text: string): OrderTerm[] {\n  if (text.trim() === \"\") return [];\n  return text.split(\",\").map((raw) => {\n    const term = raw.trim();\n    const descending = term.startsWith(ORDER_DESCENDING);\n    const column = descending ? term.slice(ORDER_DESCENDING.length) : term;\n    if (column === \"\" || column.startsWith(ORDER_DESCENDING)) {\n      throw new Error(`the order '${text}' has a term naming no column`);\n    }\n    return { column, descending };\n  });\n}\n\n/** Strings compare as the user's language orders them. */\nconst collator = new Intl.Collator();\n\n/** How a value sorts among values of other types: by its JSON type. */\nfunction rank(value: unknown): number {\n  switch (typeof value) {\n    case \"boolean\":\n      return 0;\n    case \"number\":\n      return 1;\n    case \"string\":\n      return 2;\n    default:\n      return 3;\n  }\n}\n\n/**\n * Compare two column values, ascending.\n *\n * A value compares by its JSON type, and nothing is guessed: numbers\n * numerically, booleans false before true, strings as the user's language\n * orders them. A number that arrives as a string sorts as a string, so a\n * numeric sort column is sent as a JSON number. Null and a missing value\n * sort after everything, as Postgres sorts them ascending, and so first\n * descending.\n */\nexport function compareValues(a: unknown, b: unknown): number {\n  const missingA = a === null || a === undefined;\n  const missingB = b === null || b === undefined;\n  if (missingA || missingB) return missingA === missingB ? 0 : missingA ? 1 : -1;\n  const ra = rank(a);\n  const rb = rank(b);\n  if (ra !== rb) return ra - rb;\n  if (typeof a === \"number\") return a - (b as number);\n  if (typeof a === \"boolean\") return Number(a) - Number(b);\n  if (typeof a === \"string\") return collator.compare(a, b as string);\n  return collator.compare(JSON.stringify(a), JSON.stringify(b));\n}\n\n/**\n * A value read as a declared column type: a number for `number`, a boolean\n * for `boolean`, text for `text`. A value that is no value of its type reads\n * as missing, and compares as a null does. A column with no declared type\n * reads as it arrived.\n */\nexport function readAs(value: unknown, type: ColumnType | undefined): unknown {\n  if (type === undefined || value === null || value === undefined) return value;\n  switch (type) {\n    case \"number\": {\n      if (typeof value === \"number\") return value;\n      if (typeof value !== \"string\" || value.trim() === \"\") return undefined;\n      const n = Number(value);\n      return Number.isNaN(n) ? undefined : n;\n    }\n    case \"boolean\":\n      if (typeof value === \"boolean\") return value;\n      return value === \"true\" ? true : value === \"false\" ? false : undefined;\n    default:\n      return typeof value === \"object\" ? JSON.stringify(value) : String(value);\n  }\n}\n\n/** Compare two rows by an order's terms, each column read as its type. */\nexport function compareRows(\n  a: Row,\n  b: Row,\n  terms: OrderTerm[],\n  types: ColumnTypes = {},\n): number {\n  for (const { column, descending } of terms) {\n    const c = compareValues(\n      readAs(a[column], types[column]),\n      readAs(b[column], types[column]),\n    );\n    if (c !== 0) return descending ? -c : c;\n  }\n  return 0;\n}\n\n/** A filter's operator — see FILTER_OPERATORS. */\nexport type FilterOperator = (typeof FILTER_OPERATORS)[number];\n\n/** One term of a filter: an operator, and the value it compares with. */\nexport interface FilterTerm {\n  operator: FilterOperator;\n  value: string;\n}\n\n/** Where a filter's next term begins: whitespace before an operator. */\nconst NEXT_TERM = new RegExp(\n  `\\\\s+(?=${FILTER_OPERATORS.map((op) => op.replace(/[$^*]/g, \"\\\\$&\")).join(\"|\")})`,\n);\n\n/**\n * A filter's terms, from its text: each an operator and the value after it,\n * a new term beginning wherever whitespace comes before an operator, so a\n * value may hold spaces. Text with no operator before it is `*=`. A term\n * with no value is not yet a term, and is left out, so a filter being typed\n * filters nothing until it says something. Nothing is evaluated.\n */\nexport function parseFilter(text: string): FilterTerm[] {\n  const terms: FilterTerm[] = [];\n  for (const raw of text.trim().split(NEXT_TERM)) {\n    const operator =\n      FILTER_OPERATORS.find((op) => raw.startsWith(op)) ?? \"*=\";\n    const value = raw.slice(raw.startsWith(operator) ? operator.length : 0);\n    if (value.trim() !== \"\") terms.push({ operator, value: value.trim() });\n  }\n  return terms;\n}\n\n/**\n * The filter's value as the column's own type, so a comparison is the one\n * the order makes: a number for a number, a boolean for a boolean, text for\n * anything else. Undefined when the text is no value of that type.\n */\nfunction asTypeOf(text: string, like: unknown): unknown {\n  if (typeof like === \"number\") {\n    const n = Number(text);\n    return text.trim() === \"\" || Number.isNaN(n) ? undefined : n;\n  }\n  if (typeof like === \"boolean\") {\n    return text === \"true\" ? true : text === \"false\" ? false : undefined;\n  }\n  return text;\n}\n\n/**\n * Whether a column's value passes one term.\n *\n * `^=`, `$=` and `*=` read the value as text, ignoring case: it begins with,\n * ends with or contains the term's value. The rest compare as the order\n * compares, with the column read as its declared type, if it has one, and\n * the term's value read as the column's type. A missing value, and one that\n * is no value of its declared type, passes only `!=`.\n */\nexport function passesTerm(\n  value: unknown,\n  { operator, value: text }: FilterTerm,\n  type?: ColumnType,\n): boolean {\n  if (value === null || value === undefined) return operator === \"!=\";\n  if (operator === \"^=\" || operator === \"$=\" || operator === \"*=\") {\n    const have = String(value).toLocaleLowerCase();\n    const want = text.toLocaleLowerCase();\n    if (operator === \"^=\") return have.startsWith(want);\n    if (operator === \"$=\") return have.endsWith(want);\n    return have.includes(want);\n  }\n  const read = readAs(value, type);\n  const typed = read === undefined ? undefined : asTypeOf(text, read);\n  if (typed === undefined) return operator === \"!=\";\n  const c = compareValues(read, typed);\n  switch (operator) {\n    case \"=\":\n      return c === 0;\n    case \"!=\":\n      return c !== 0;\n    case \"<\":\n      return c < 0;\n    case \"<=\":\n      return c <= 0;\n    case \">\":\n      return c > 0;\n    default:\n      return c >= 0;\n  }\n}\n\n/** Whether a column's value passes every term of a filter. */\nexport function passes(\n  value: unknown,\n  terms: FilterTerm[],\n  type?: ColumnType,\n): boolean {\n  return terms.every((term) => passesTerm(value, term, type));\n}\n\n/**\n * Where a row for `lb-url` leads, from a page and its query parms.\n *\n * A column whose name begins with `lb-` is Loadbare's, and never a query\n * parm; every other column is one. An `lb-path` naming another page enters\n * it with only the parms the row names. Otherwise the named parms are set,\n * or taken out when empty, and the rest are kept.\n *\n * One rule on both sides of the wire: the server loads the page it names,\n * and the hub writes the URL it names. The two must agree, or what the page\n * shows would differ from what the address bar says.\n */\nexport function nextLocation(\n  page: string,\n  parms: URLSearchParams,\n  row: Row,\n): { page: string; parms: URLSearchParams; moved: boolean } {\n  const named: Record<string, string> = {};\n  for (const [name, value] of Object.entries(row)) {\n    if (name.startsWith(LB_RESERVED_PREFIX)) continue;\n    named[name] = value === null || value === undefined ? \"\" : String(value);\n  }\n  const path = row[URL_COLUMN_PATH];\n  const next = typeof path === \"string\" ? pageNameFor(path) : page;\n  const moved = next !== page;\n  return {\n    page: next,\n    parms: withQueryParms(moved ? new URLSearchParams() : parms, named),\n    moved,\n  };\n}\n\n/**\n * What the hub tells a custom element it did, in its own terms rather than\n * the browser's: a custom element implements any of these in place of\n * `connectedCallback` and its kin, which the builder refuses.\n *\n * Each is a method on an element the hub does not own, so it carries the\n * `lb` prefix Loadbare reserves for exactly that — see\n * docs/reference/custom-elements.md.\n */\nexport interface HubLifecycle {\n  /**\n   * Called once, after the hub has placed the element and every column has\n   * landed on it. An element under an `lb-show` that is off is placed inside\n   * its template, so it may not be rendered.\n   */\n  lbAttached?(): void;\n  /**\n   * Called once after a result has landed on an element holding rows, with\n   * every row in place and every stamp set. The hub reconciles and places\n   * every row itself, by the query's order, so a custom element reacts to\n   * rows and never places them.\n   */\n  lbRowsLanded?(): void;\n  /**\n   * Called once a request committed by this element, or by one inside it,\n   * has finished, innermost first and before `lb-request-done` is\n   * dispatched. `origin` is the element that committed.\n   */\n  lbRequestDone?(detail: HubRequestDone, origin: Element): void;\n  /** Called once, after the hub has removed the element. */\n  lbDetached?(): void;\n}\n"]}

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

@@ -1,4 +1,4 @@
-import { type ResponseItem, type Row, type RowsResult } from "../core/lb-types.js";
+import { type ColumnTypes, type ResponseItem, type Row, type RowsResult } from "../core/lb-types.js";
 /** A control's value, whether it is native or a custom element. */
 export interface Control extends Element {
     value: string;
@@ -35,15 +35,15 @@ export declare function select(box: Element, on: boolean): void;
 /**
  * Fill from one row: every `lb-column` and `lb-show` in root's query.
  *
- * A live row is its own row, so its root counts when it carries
- * `lb-column`: `<option>`'s content model is text, so an option row has to
- * be the column it displays. An element a `row` lands on is not its own
- * ancestor, so its own `lb-column` reads from the row around it and is left
- * alone here.
+ * With `self`, root's own `lb-column` counts, as a live row's does:
+ * `<option>`'s content model is text, so an option row has to be the column
+ * it displays. An element a `row` lands on is not its own ancestor, so its
+ * own `lb-column` reads from the row around it and is left alone here. Root's
+ * own `lb-show` never counts.
  *
- * A live row is searched once, the first time it is filled; see places().
+ * `stop` passes over everything matching it and inside it.
  */
-export declare function applyRow(root: Element, row: Row, liveRow?: boolean, stop?: string): void;
+export declare function applyRow(root: Element, row: Row, self?: boolean, stop?: string): void;
 /**
  * A row naming every column root's query shows, each null: what landing it
  * leaves is root as it stands with no row. Absent branches are counted, so a
@@ -57,10 +57,21 @@ export declare function blankRow(root: Element): Row;
  * live row comes first in document order.
  */
 export declare function templateIn(el: Element): HTMLTemplateElement | null;
+/**
+ * Focus the first element in `root` the user can operate: not disabled, not
+ * in a closed dialog, not inert, not hidden, and one that took the focus
+ * when asked. Nothing in a `<template>` is a candidate, so an absent
+ * `lb-show` branch is passed over.
+ */
+export declare function focusIn(root: Element): void;
 /** How a list of rows lands: in what order, and whether a request asked. */
 export interface RowsOptions {
-    /** The order to place rows by, as an order's text. */
+    /** The order the server declared, as an order's text. */
     order?: string;
+    /** The column types the server declared. */
+    types?: ColumnTypes;
+    /** The user's choices: the row of `lb-choices`. */
+    choices?: Row;
     /** The landing answers a request from this page. */
     requested?: boolean;
     /**
@@ -72,46 +83,47 @@ export interface RowsOptions {
 /**
  * Land rows through a row template.
  *
+ * Two loops do the work, on rows in no document. The creation loop makes a
+ * live row for each key not yet shown, with its key and no values. The
+ * landing loop lands each arriving row's values on its live row, as a `row`
+ * lands, passing over a column that already shows its value. Then every live
+ * row is placed by the order in one fragment, and the browser styles once.
+ *
  * All rows decide membership: a row whose key did not arrive leaves. A patch
  * disturbs only what it names — a row it did not mention keeps its contents,
  * and keeps its place unless a row the patch named now sorts around it.
  *
- * Every live row is placed by the order. With none, all rows show in the
- * order they arrived, and a patch's new rows go last. A row moves only when
- * the order put it somewhere else, so landing the same rows again moves
- * nothing.
+ * With no order, all rows show in the order they arrived, and a patch's new
+ * rows go last. A row that stands where it stood is not touched, so landing
+ * the same rows again moves nothing. A row a filter the user chose does not
+ * pass is `hidden`.
  */
 export declare function applyRows(el: Element, template: HTMLTemplateElement, keyColumn: string, result: RowsResult, options?: RowsOptions): void;
 /** The answer kept for a query, as all of its rows. */
 export declare function keptAnswer(root: ParentNode, query: string): ResponseItem | undefined;
 /**
  * Drop what landing kept for a root. The hub calls it when it replaces the
- * page, since another page's query of the same name is another query.
+ * page, since another page's query of the same name is another query, and
+ * the user's choices were for the page they were made on.
  */
 export declare function forget(root: ParentNode): void;
 /** How response items land. */
 export interface LandOptions {
     /**
-     * Queries that may have nowhere to land without a warning: the hub's own
-     * `lb-url` lands wherever a chrome or page names it, and nowhere otherwise.
+     * Queries that may have nowhere to land without a warning. A query the hub
+     * serves, such as `lb-url`, is always one: it lands wherever a chrome or
+     * page names it, and nowhere otherwise.
      */
     quiet?: readonly string[];
-    /** The user's order for a query, which replaces the server's. */
-    orderFor?: (query: string) => string | undefined;
     /** The items answer a request from this page. */
     requested?: boolean;
 }
 /**
  * Land response items. Every answer arrives through here, and is kept for
  * `root`, so that what arrives after it is filled from it — see forget().
- * Once everything has landed, each custom element placed since the last
- * landing is attached.
+ * An answer to `lb-choices` places again the rows its choices change. Once
+ * everything has landed, each custom element placed since the last landing
+ * is attached.
  */
 export declare function applyResponse(root: ParentNode, items: ResponseItem[], options?: LandOptions): void;
-/**
- * Land a query's kept answer again, as all of its rows: what the hub does
- * when the user's order for it changes and the rows themselves have not.
- * False when no answer is kept.
- */
-export declare function reland(root: ParentNode, query: string): boolean;
 //# 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":"AAyEA,OAAO,EAQL,KAAK,YAAY,EACjB,KAAK,GAAG,EACR,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAkC7B,mEAAmE;AACnE,MAAM,WAAW,OAAQ,SAAQ,OAAO;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AA4BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAGrD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAEhD;AAsFD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAMjE;AA0CD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAGtD;AA4FD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,GAAG,EACR,OAAO,UAAQ,EACf,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAmCN;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAU3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,mBAAmB,GAAG,IAAI,CAKlE;AAyhBD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,WAAgB,GACxB,IAAI,CAyJN;AAmDD,uDAAuD;AACvD,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,GACZ,YAAY,GAAG,SAAS,CAE1B;AAOD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAE7C;AAwDD,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACjD,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,GAAE,WAAgB,GACxB,IAAI,CAwBN;AAED;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK/D"}
+{"version":3,"file":"lb-apply.d.ts","sourceRoot":"","sources":["../../hub/lb-apply.ts"],"names":[],"mappings":"AA+EA,OAAO,EASL,KAAK,WAAW,EAKhB,KAAK,YAAY,EACjB,KAAK,GAAG,EACR,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAyB7B,mEAAmE;AACnE,MAAM,WAAW,OAAQ,SAAQ,OAAO;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AA4BD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAGrD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,OAAO,CAEpD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAEhD;AAsFD;;;;;GAKG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,EAAE,CAMjE;AA0CD;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI,CAGtD;AA6LD;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,GAAG,EACR,IAAI,UAAQ,EACZ,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAU3C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,GAAG,mBAAmB,GAAG,IAAI,CAKlE;AAQD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAS3C;AAwmBD,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,mDAAmD;IACnD,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,OAAO,EACX,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,WAAgB,GACxB,IAAI,CAgIN;AAmFD,uDAAuD;AACvD,wBAAgB,UAAU,CACxB,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,MAAM,GACZ,YAAY,GAAG,SAAS,CAE1B;AAgBD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAE7C;AAoGD,+BAA+B;AAC/B,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,iDAAiD;IACjD,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,GAAE,WAAgB,GACxB,IAAI,CA2BN"}