@aglyn/aglyn 1.0.0-beta.231 → 1.0.0-beta.233

package/src/lib/app-utils/artifact-list-keys.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/artifact-list-keys.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { displayNameSearchFields } from './name-search'\n\n/*\n * THE KEYS A SITE ARTIFACT'S LISTS QUERY BY (AGL-3321).\n *\n * The screens, layouts, reusable components and templates of a site are\n * listed, searched and filtered by Firestore queries, so every key a list\n * asks about has to be WRITTEN — a query cannot find a document by a value it\n * derives, and cannot find one that lacks the field at all:\n *\n *   nameLower / nameTokens / nameReversed\n *                the name keys (`displayNameSearchFields`), on all four;\n *   kind         on a component, `site` or `email` — a component stored\n *                before AGL-3287 carries none and is read as `site`, so the\n *                \"Used in: Page\" filter needs the word stored;\n *                on a template, `page`, `component` or `layout` — a template\n *                stored with none is read as a page template;\n *   source.type  on a template, its provenance — one stored with no\n *                `source`, or with the legacy `workspace`, was saved here,\n *                which is `authored`;\n *   libraryRow   on a template, whether it is its own row of the templates\n *                library: a multi-page STARTER is one row (AGL-696), led by\n *                its first live page, so the other pages carry `false` — and\n *                so does a deleted template (`artifactDeleteListKeys`), which\n *                is how the library's query leaves tombstones out;\n *\n *   deletedAt    on a screen, `null` — the flag a campaign's screens list\n *                asks for (`deletedAt == null`) to leave tombstones out. A\n *                query cannot ask for a field to be absent, so a live\n *                screen must STORE the null; a delete overwrites it with\n *                the time (and the security rules let an editor do that\n *                only while it is null, so a tombstone stays one);\n *\n * A DELETED screen gets none of them. The email templates list orders by\n * `nameLower`, and an email template's delete clears its name keys so the\n * tombstone leaves that order (a query cannot ask for `deletedAt` to be\n * absent) — so no create, restore or backfill may stamp them back.\n *\n * Every CREATE stamps them (`artifactCreateListKeys`) and every rename\n * restamps the name keys (`artifactRenameListKeys`).\n * `tools/scripts/backfill-artifacts-list-keys.mjs` stamps the documents\n * written before them; a script cannot import this library, so it reads the\n * documents the way this module does, and both sides answer\n * `tools/scripts/lib/artifact-list-keys.fixtures.json` — this module's spec\n * and the backfill's `--self-test`.\n */\n\n/** The site artifact collections whose lists query these keys. */\nexport const LISTED_ARTIFACT_COLLECTIONS = [\n  'screens',\n  'layouts',\n  'components',\n  'templates',\n] as const\n\nexport type ListedArtifactCollection =\n  (typeof LISTED_ARTIFACT_COLLECTIONS)[number]\n\n/** Whether a host subcollection is one whose lists query these keys. */\nexport const isListedArtifactCollection = (\n  collection: string,\n): collection is ListedArtifactCollection =>\n  (LISTED_ARTIFACT_COLLECTIONS as readonly string[]).includes(collection)\n\n/** The kinds a template's `kind` holds; absent reads as `page`. */\nconst TEMPLATE_KINDS = ['page', 'component', 'layout']\n\n/**\n * A provenance word no writer stores any more: a detached marketplace copy\n * was stamped `workspace` before it was stamped `authored` (AGL-3321).\n */\nconst LEGACY_AUTHORED_SOURCE = 'workspace'\n\nconst record = (value: unknown): Record<string, unknown> =>\n  value && typeof value === 'object' ? (value as Record<string, unknown>) : {}\n\n/**\n * The name a list finds an artifact by.\n *\n * Its `displayName` — except a page of a multi-page STARTER, which the\n * templates library lists as ONE row under the starter's name\n * (`source.starterName`), so every page of it carries that name's keys and a\n * search for the starter finds the row whichever page leads it.\n */\nexport function artifactSearchName(\n  collection: string,\n  doc: Record<string, unknown>,\n): unknown {\n  if (collection === 'templates') {\n    const starterName = record(doc['source'])['starterName']\n    if (typeof starterName === 'string' && starterName.trim()) return starterName\n  }\n  return doc['displayName']\n}\n\n/**\n * The list keys a CREATE of `doc` into `collection` stamps: the name keys,\n * and the stored default of a kind a reader otherwise infers. Nothing for a\n * collection no artifact list queries.\n *\n * Spread AFTER the document's own fields: the keys are derived from them.\n */\nexport function artifactCreateListKeys(\n  collection: string,\n  doc: Record<string, unknown>,\n): Record<string, unknown> {\n  if (!isListedArtifactCollection(collection)) return {}\n  if (collection === 'screens' && doc['deletedAt'] != null) return {}\n  const keys: Record<string, unknown> = {\n    ...displayNameSearchFields(artifactSearchName(collection, doc)),\n  }\n  // Stored, not omitted: `deletedAt == null` matches only a document that\n  // holds the field (AGL-3321, a campaign's screens).\n  if (collection === 'screens') keys['deletedAt'] = null\n  if (collection === 'components' && doc['kind'] !== 'email') keys['kind'] = 'site'\n  if (collection === 'templates') {\n    if (!TEMPLATE_KINDS.includes(String(doc['kind']))) keys['kind'] = 'page'\n    // Provenance is server-managed (AGL-666), and a writer that states it is\n    // never overridden here. None at all, or the legacy word a detached copy\n    // carried, was saved here, which is `authored`.\n    const sourceType = record(doc['source'])['type']\n    if (typeof sourceType !== 'string' || sourceType === LEGACY_AUTHORED_SOURCE) {\n      keys['source'] = { ...record(doc['source']), type: 'authored' }\n    }\n    keys['libraryRow'] = doc['deletedAt'] == null && leadsItsStarter(doc)\n  }\n  return keys\n}\n\n/**\n * Whether a template leads its starter's library row when the starter is\n * written whole: every template that is not a starter page does, and of a\n * starter's pages the first (`starterOrder` 0). A later delete moves the lead\n * to the next live page — see `artifactDeleteListKeys`.\n */\nfunction leadsItsStarter(doc: Record<string, unknown>): boolean {\n  const source = record(doc['source'])\n  const starterId = source['starterId']\n  if (typeof starterId !== 'string' || !starterId) return true\n  return Number(source['starterOrder'] ?? 0) === 0\n}\n\n/**\n * The list keys a SOFT DELETE writes beside `deletedAt`: a deleted template\n * is no longer a library row. A caller deleting the page that LEADS a\n * starter's row gives the lead to the next live page (`libraryRow: true`),\n * or the starter disappears from the library with pages still in it.\n */\nexport function artifactDeleteListKeys(\n  collection: string,\n): Record<string, unknown> {\n  return collection === 'templates' ? { libraryRow: false } : {}\n}\n\n/**\n * The name keys a RENAME writes beside the new `displayName`. `doc` is the\n * document as read, for the one case whose search name is not its display\n * name (a starter page — see `artifactSearchName`).\n */\nexport function artifactRenameListKeys(\n  collection: string,\n  displayName: unknown,\n  doc: Record<string, unknown> = {},\n): Record<string, unknown> {\n  if (!isListedArtifactCollection(collection)) return {}\n  return displayNameSearchFields(\n    artifactSearchName(collection, { ...doc, displayName }),\n  )\n}\n"],"names":["displayNameSearchFields","LISTED_ARTIFACT_COLLECTIONS","isListedArtifactCollection","collection","includes","TEMPLATE_KINDS","LEGACY_AUTHORED_SOURCE","record","value","artifactSearchName","doc","starterName","trim","artifactCreateListKeys","keys","String","sourceType","type","leadsItsStarter","source","starterId","Number","artifactDeleteListKeys","libraryRow","artifactRenameListKeys","displayName"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,uBAAuB,QAAQ,mBAAe;AAEvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CC,GAED,gEAAgE,GAChE,OAAO,MAAMC,8BAA8B;IACzC;IACA;IACA;IACA;CACD,CAAS;AAKV,sEAAsE,GACtE,OAAO,MAAMC,6BAA6B,CACxCC,aAEA,AAACF,4BAAkDG,QAAQ,CAACD,YAAW;AAEzE,iEAAiE,GACjE,MAAME,iBAAiB;IAAC;IAAQ;IAAa;CAAS;AAEtD;;;CAGC,GACD,MAAMC,yBAAyB;AAE/B,MAAMC,SAAS,CAACC,QACdA,SAAS,OAAOA,UAAU,WAAYA,QAAoC,CAAC;AAE7E;;;;;;;CAOC,GACD,OAAO,SAASC,mBACdN,UAAkB,EAClBO,GAA4B;IAE5B,IAAIP,eAAe,aAAa;QAC9B,MAAMQ,cAAcJ,OAAOG,GAAG,CAAC,SAAS,CAAC,CAAC,cAAc;QACxD,IAAI,OAAOC,gBAAgB,YAAYA,YAAYC,IAAI,IAAI,OAAOD;IACpE;IACA,OAAOD,GAAG,CAAC,cAAc;AAC3B;AAEA;;;;;;CAMC,GACD,OAAO,SAASG,uBACdV,UAAkB,EAClBO,GAA4B;IAE5B,IAAI,CAACR,2BAA2BC,aAAa,OAAO,CAAC;IACrD,IAAIA,eAAe,aAAaO,GAAG,CAAC,YAAY,IAAI,MAAM,OAAO,CAAC;IAClE,MAAMI,OAAgC,aACjCd,wBAAwBS,mBAAmBN,YAAYO;IAE5D,wEAAwE;IACxE,oDAAoD;IACpD,IAAIP,eAAe,WAAWW,IAAI,CAAC,YAAY,GAAG;IAClD,IAAIX,eAAe,gBAAgBO,GAAG,CAAC,OAAO,KAAK,SAASI,IAAI,CAAC,OAAO,GAAG;IAC3E,IAAIX,eAAe,aAAa;QAC9B,IAAI,CAACE,eAAeD,QAAQ,CAACW,OAAOL,GAAG,CAAC,OAAO,IAAII,IAAI,CAAC,OAAO,GAAG;QAClE,yEAAyE;QACzE,yEAAyE;QACzE,gDAAgD;QAChD,MAAME,aAAaT,OAAOG,GAAG,CAAC,SAAS,CAAC,CAAC,OAAO;QAChD,IAAI,OAAOM,eAAe,YAAYA,eAAeV,wBAAwB;YAC3EQ,IAAI,CAAC,SAAS,GAAG,aAAKP,OAAOG,GAAG,CAAC,SAAS;gBAAGO,MAAM;;QACrD;QACAH,IAAI,CAAC,aAAa,GAAGJ,GAAG,CAAC,YAAY,IAAI,QAAQQ,gBAAgBR;IACnE;IACA,OAAOI;AACT;AAEA;;;;;CAKC,GACD,SAASI,gBAAgBR,GAA4B;QAIrCS;IAHd,MAAMA,SAASZ,OAAOG,GAAG,CAAC,SAAS;IACnC,MAAMU,YAAYD,MAAM,CAAC,YAAY;IACrC,IAAI,OAAOC,cAAc,YAAY,CAACA,WAAW,OAAO;IACxD,OAAOC,QAAOF,uBAAAA,MAAM,CAAC,eAAe,YAAtBA,uBAA0B,OAAO;AACjD;AAEA;;;;;CAKC,GACD,OAAO,SAASG,uBACdnB,UAAkB;IAElB,OAAOA,eAAe,cAAc;QAAEoB,YAAY;IAAM,IAAI,CAAC;AAC/D;AAEA;;;;CAIC,GACD,OAAO,SAASC,uBACdrB,UAAkB,EAClBsB,WAAoB,EACpBf,MAA+B,CAAC,CAAC;IAEjC,IAAI,CAACR,2BAA2BC,aAAa,OAAO,CAAC;IACrD,OAAOH,wBACLS,mBAAmBN,YAAY,aAAKO;QAAKe;;AAE7C"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/artifact-list-keys.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { displayNameSearchFields } from './name-search'\n\n/*\n * THE KEYS A SITE ARTIFACT'S LISTS QUERY BY (AGL-3321).\n *\n * The screens, layouts, reusable components and templates of a site are\n * listed, searched and filtered by Firestore queries, so every key a list\n * asks about has to be WRITTEN — a query cannot find a document by a value it\n * derives, and cannot find one that lacks the field at all:\n *\n *   nameLower / nameTokens / nameReversed\n *                the name keys (`displayNameSearchFields`), on all four;\n *   kind         on a component, `site` or `email` — a component stored\n *                before AGL-3287 carries none and is read as `site`, so the\n *                \"Used in: Page\" filter needs the word stored;\n *                on a template, `page`, `component` or `layout` — a template\n *                stored with none is read as a page template;\n *   source.type  on a template, its provenance — one stored with no\n *                `source`, or with the legacy `workspace`, was saved here,\n *                which is `authored`;\n *   libraryRow   on a template, whether it is its own row of the templates\n *                library: a multi-page STARTER is one row (AGL-696), led by\n *                its first live page, so the other pages carry `false` — and\n *                so does a deleted template (`artifactDeleteListKeys`), which\n *                is how the library's query leaves tombstones out;\n *\n *   description  on a layout or component that has none, `null` — the\n *                lists sort by it (AGL-3680), and an `orderBy` drops every\n *                document that lacks the field. A writer that passes a\n *                partial document here must pass its `description` too, or\n *                the null would overwrite the one it writes;\n *   deletedAt    on a screen, `null` — the flag a campaign's screens list\n *                asks for (`deletedAt == null`) to leave tombstones out. A\n *                query cannot ask for a field to be absent, so a live\n *                screen must STORE the null; a delete overwrites it with\n *                the time (and the security rules let an editor do that\n *                only while it is null, so a tombstone stays one);\n *\n * A DELETED screen gets none of them. The email templates list orders by\n * `nameLower`, and an email template's delete clears its name keys so the\n * tombstone leaves that order (a query cannot ask for `deletedAt` to be\n * absent) — so no create, restore or backfill may stamp them back.\n *\n * Every CREATE stamps them (`artifactCreateListKeys`) and every rename\n * restamps the name keys (`artifactRenameListKeys`).\n * `tools/scripts/backfill-artifacts-list-keys.mjs` stamps the documents\n * written before them; a script cannot import this library, so it reads the\n * documents the way this module does, and both sides answer\n * `tools/scripts/lib/artifact-list-keys.fixtures.json` — this module's spec\n * and the backfill's `--self-test`.\n */\n\n/** The site artifact collections whose lists query these keys. */\nexport const LISTED_ARTIFACT_COLLECTIONS = [\n  'screens',\n  'layouts',\n  'components',\n  'templates',\n] as const\n\nexport type ListedArtifactCollection =\n  (typeof LISTED_ARTIFACT_COLLECTIONS)[number]\n\n/** Whether a host subcollection is one whose lists query these keys. */\nexport const isListedArtifactCollection = (\n  collection: string,\n): collection is ListedArtifactCollection =>\n  (LISTED_ARTIFACT_COLLECTIONS as readonly string[]).includes(collection)\n\n/** The kinds a template's `kind` holds; absent reads as `page`. */\nconst TEMPLATE_KINDS = ['page', 'component', 'layout']\n\n/**\n * A provenance word no writer stores any more: a detached marketplace copy\n * was stamped `workspace` before it was stamped `authored` (AGL-3321).\n */\nconst LEGACY_AUTHORED_SOURCE = 'workspace'\n\nconst record = (value: unknown): Record<string, unknown> =>\n  value && typeof value === 'object' ? (value as Record<string, unknown>) : {}\n\n/**\n * The name a list finds an artifact by.\n *\n * Its `displayName` — except a page of a multi-page STARTER, which the\n * templates library lists as ONE row under the starter's name\n * (`source.starterName`), so every page of it carries that name's keys and a\n * search for the starter finds the row whichever page leads it.\n */\nexport function artifactSearchName(\n  collection: string,\n  doc: Record<string, unknown>,\n): unknown {\n  if (collection === 'templates') {\n    const starterName = record(doc['source'])['starterName']\n    if (typeof starterName === 'string' && starterName.trim()) return starterName\n  }\n  return doc['displayName']\n}\n\n/**\n * The list keys a CREATE of `doc` into `collection` stamps: the name keys,\n * and the stored default of a kind a reader otherwise infers. Nothing for a\n * collection no artifact list queries.\n *\n * Spread AFTER the document's own fields: the keys are derived from them.\n */\nexport function artifactCreateListKeys(\n  collection: string,\n  doc: Record<string, unknown>,\n): Record<string, unknown> {\n  if (!isListedArtifactCollection(collection)) return {}\n  if (collection === 'screens' && doc['deletedAt'] != null) return {}\n  const keys: Record<string, unknown> = {\n    ...displayNameSearchFields(artifactSearchName(collection, doc)),\n  }\n  // Stored, not omitted: `deletedAt == null` matches only a document that\n  // holds the field (AGL-3321, a campaign's screens).\n  if (collection === 'screens') keys['deletedAt'] = null\n  // A live layout too: its list asks for `deletedAt == null` rather than\n  // dropping tombstones from the page they fall in (AGL-3680).\n  if (collection === 'layouts' && doc['deletedAt'] == null) keys['deletedAt'] = null\n  if (collection === 'components' && doc['kind'] !== 'email') keys['kind'] = 'site'\n  // Stored, not omitted: the Description header orders by it (AGL-3680).\n  if ((collection === 'layouts' || collection === 'components') && doc['description'] == null) {\n    keys['description'] = null\n  }\n  if (collection === 'templates') {\n    if (!TEMPLATE_KINDS.includes(String(doc['kind']))) keys['kind'] = 'page'\n    // Provenance is server-managed (AGL-666), and a writer that states it is\n    // never overridden here. None at all, or the legacy word a detached copy\n    // carried, was saved here, which is `authored`.\n    const sourceType = record(doc['source'])['type']\n    if (typeof sourceType !== 'string' || sourceType === LEGACY_AUTHORED_SOURCE) {\n      keys['source'] = { ...record(doc['source']), type: 'authored' }\n    }\n    keys['libraryRow'] = doc['deletedAt'] == null && leadsItsStarter(doc)\n  }\n  return keys\n}\n\n/**\n * Whether a template leads its starter's library row when the starter is\n * written whole: every template that is not a starter page does, and of a\n * starter's pages the first (`starterOrder` 0). A later delete moves the lead\n * to the next live page — see `artifactDeleteListKeys`.\n */\nfunction leadsItsStarter(doc: Record<string, unknown>): boolean {\n  const source = record(doc['source'])\n  const starterId = source['starterId']\n  if (typeof starterId !== 'string' || !starterId) return true\n  return Number(source['starterOrder'] ?? 0) === 0\n}\n\n/**\n * The list keys a SOFT DELETE writes beside `deletedAt`: a deleted template\n * is no longer a library row. A caller deleting the page that LEADS a\n * starter's row gives the lead to the next live page (`libraryRow: true`),\n * or the starter disappears from the library with pages still in it.\n */\nexport function artifactDeleteListKeys(\n  collection: string,\n): Record<string, unknown> {\n  return collection === 'templates' ? { libraryRow: false } : {}\n}\n\n/**\n * The name keys a RENAME writes beside the new `displayName`. `doc` is the\n * document as read, for the one case whose search name is not its display\n * name (a starter page — see `artifactSearchName`).\n */\nexport function artifactRenameListKeys(\n  collection: string,\n  displayName: unknown,\n  doc: Record<string, unknown> = {},\n): Record<string, unknown> {\n  if (!isListedArtifactCollection(collection)) return {}\n  return displayNameSearchFields(\n    artifactSearchName(collection, { ...doc, displayName }),\n  )\n}\n"],"names":["displayNameSearchFields","LISTED_ARTIFACT_COLLECTIONS","isListedArtifactCollection","collection","includes","TEMPLATE_KINDS","LEGACY_AUTHORED_SOURCE","record","value","artifactSearchName","doc","starterName","trim","artifactCreateListKeys","keys","String","sourceType","type","leadsItsStarter","source","starterId","Number","artifactDeleteListKeys","libraryRow","artifactRenameListKeys","displayName"],"mappings":"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"}

package/src/lib/app-utils/artifact-list-queries.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { ListFilterOption } from '@aglyn/shared-util-tools/list-query/list-filter-codecs';
+import { type ListQueryDeclaration, type ListQueryFilter, type ListQuerySort } from '@aglyn/shared-util-tools/list-query/list-query-plan';
+/** The walk every artifact list keeps: the document name, ascending. */
+export declare const ARTIFACT_LIST_ORDER: ListQuerySort;
+/** The quick search every artifact list and gallery shelf offers: the name's word prefixes. */
+export declare const ARTIFACT_NAME_SEARCH: {
+    tokensPath: string;
+};
+/** The layouts page's header sorts; the ID ascending one is the default. */
+export declare const LAYOUT_LIST_SORTS: readonly ListQuerySort[];
+/**
+ * The layouts list's scope: live layouts. Every create stores `deletedAt: null`
+ * (`artifactCreateListKeys`) and a delete stamps the time, so the query leaves
+ * tombstones out instead of the page dropping them after the read (AGL-3680).
+ */
+export declare const LAYOUT_LIST_BASE: readonly ListQueryFilter[];
+/** `hosts/{hostId}/layouts`. */
+export declare const LAYOUT_LIST_QUERY: ListQueryDeclaration;
+export declare const LAYOUT_LIST_HEADERS: Readonly<Record<string, string>>;
+/** The components card's header sorts; the ID ascending one is the default. */
+export declare const COMPONENT_LIST_SORTS: readonly ListQuerySort[];
+/** `hosts/{hostId}/components`. */
+export declare const COMPONENT_LIST_QUERY: ListQueryDeclaration;
+export declare const COMPONENT_LIST_HEADERS: Readonly<Record<string, string>>;
+export declare const TEMPLATE_LIST_BASE: readonly ListQueryFilter[];
+/**
+ * The templates library's header sorts. It shows no ID column, so the walk
+ * stays the unlabelled default; Description sorts the page (see "The header
+ * sorts").
+ */
+export declare const TEMPLATE_LIST_SORTS: readonly ListQuerySort[];
+export declare const TEMPLATE_LIST_QUERY: ListQueryDeclaration;
+export declare const TEMPLATE_LIST_HEADERS: Readonly<Record<string, string>>;
+/** The template kinds, by the stored `kind`. */
+export declare const TEMPLATE_KIND_OPTIONS: readonly ListFilterOption[];

package/src/lib/app-utils/artifact-list-queries.js

@@ -0,0 +1,321 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { LIST_QUERY_ID_PATH } from "@aglyn/shared-util-tools/list-query/list-query-plan";
+/*
+ * WHAT THE SITE ARTIFACT LISTS ASK FIRESTORE (AGL-3321).
+ *
+ * The layouts page, the components card and the templates library put every
+ * clause their Filters panel accepts, and the quick-search word, on the query
+ * — composed by `planListQuery` — and page what it answers. Nothing is matched
+ * over the rows a page happened to read. The template gallery's shelves ask
+ * the same keys (`template-gallery-dialog.component.tsx`), and so does the
+ * email plugin's templates list, from its own declaration.
+ *
+ * ## The keys are WRITTEN
+ *
+ * A query finds a document by a stored value, so each list reads keys every
+ * writer stamps (`artifactCreateListKeys`/`artifactRenameListKeys` in
+ * `@aglyn/aglyn/app-utils/artifact-list-keys`) and
+ * `tools/scripts/backfill-artifacts-list-keys.mjs` stamps on the documents
+ * written before them:
+ *
+ *   nameTokens   the name's word prefixes — the search box and `contains`;
+ *   nameLower    the normalized name — `equals`;
+ *   kind         a component's `site`/`email`, a template's page/component/
+ *                layout, stored even where a reader used to infer it;
+ *   source.type  a template's provenance, `authored` where there was none;
+ *   libraryRow   a template that is its own library row (below).
+ *
+ * ## The order is the document NAME, and that is what keeps it cheap
+ *
+ * `hostArtifactQuery` explains why these lists walk the document id: it is
+ * the one order no writer can omit, so the walk is total. It is also the
+ * order index merging serves with Firestore's automatic single-field
+ * indexes: any mix of the equalities and the one array clause above, ordered
+ * by `__name__`, needs no composite at all. The composites below exist only
+ * for the one range each list offers — `Updated` — which must lead the order
+ * it ranges over, so it pairs with each equality once.
+ *
+ * ## What is not offered, and why
+ *
+ *   - `startsWith`/`endsWith` on the name: a prefix range must lead the order,
+ *     and these lists are not sorted by name.
+ *   - `description` (a filter and a search target before): no token field,
+ *     and a second token array could not share the query's one array clause
+ *     with the search anyway.
+ *   - `Created` ranges: a second range order would double the composites for
+ *     a question `Updated` answers nearly as well; one range per list.
+ *
+ * ## The header sorts (AGL-3680)
+ *
+ * Every column sorts on the QUERY, by a stored value every writer stamps:
+ *
+ *   Display name  `nameLower` (above; a starter page's is its starter's
+ *                 name, which is the name its library row shows);
+ *   ID            the walk itself, either way;
+ *   Updated,      `updatedAt` / `createdAt` — stamped by every create, and by
+ *   Created       `backfill-artifacts-list-keys.mjs` on a document that
+ *                 predates either;
+ *   Used in, Kind the stored `kind`; Source the stored `source.type`;
+ *   Description   a layout's or component's `description`, stored as `null`
+ *                 when it has none (`artifactCreateListKeys` + the backfill),
+ *                 because an `orderBy` DROPS a document that lacks the field.
+ *                 A template row's description is its starter's when it
+ *                 leads one, which is no stored field: it sorts the page.
+ *
+ * Each is `alone` — served only while no filter or search is on, falling
+ * back to the list's default header order with a notice — so on the layouts
+ * and components subcollections it costs no composite. Updated newest-first
+ * is not `alone`: it is the order
+ * the Updated range already imposes, so it pairs with every equality and
+ * its composites are the ones the range needed anyway. The templates
+ * library's `libraryRow` scope is an equality every order pairs with, so
+ * each of its orders has one `(libraryRow, order)` composite.
+ */ /** The walk every artifact list keeps: the document name, ascending. */ export const ARTIFACT_LIST_ORDER = {
+    path: LIST_QUERY_ID_PATH,
+    direction: 'asc'
+};
+/** The name, by word prefix (`contains`) or whole (`equals`). */ const NAME_FIELD = {
+    column: 'displayName',
+    kind: 'text',
+    path: 'displayName',
+    lowerPath: 'nameLower',
+    tokensPath: 'nameTokens',
+    operators: [
+        'contains',
+        'equals'
+    ]
+};
+/** The document id, which the walk already orders by. */ const ID_FIELD = {
+    column: '$id',
+    kind: 'id',
+    path: LIST_QUERY_ID_PATH
+};
+/** The one range: `updatedAt`, which every writer stamps. */ const UPDATED_FIELD = {
+    column: 'updatedAt',
+    kind: 'date',
+    path: 'updatedAt',
+    operators: [
+        'is',
+        'after',
+        'onOrAfter',
+        'before',
+        'onOrBefore'
+    ]
+};
+/** The quick search every artifact list and gallery shelf offers: the name's word prefixes. */ export const ARTIFACT_NAME_SEARCH = {
+    tokensPath: 'nameTokens'
+};
+/** One header's two orders, `alone` (see "The header sorts"). */ const headerSorts = (column, path, label)=>[
+        {
+            path,
+            direction: 'asc',
+            column,
+            label,
+            alone: true
+        },
+        {
+            path,
+            direction: 'desc',
+            column,
+            label,
+            alone: true
+        }
+    ];
+/**
+ * The ID header: the walk ascending — the list's default, served under every
+ * filter — and descending, `alone`.
+ */ const ID_SORTS = [
+    {
+        path: LIST_QUERY_ID_PATH,
+        direction: 'asc',
+        column: '$id',
+        label: 'ID'
+    },
+    {
+        path: LIST_QUERY_ID_PATH,
+        direction: 'desc',
+        column: '$id',
+        label: 'ID',
+        alone: true
+    }
+];
+/**
+ * Updated newest first FIRST: it is the order the Updated range imposes
+ * (`planListQuery` takes the first declared order on the range's field), so
+ * it is not `alone` — the range's composites already serve it.
+ */ const TIME_SORTS = [
+    {
+        path: 'updatedAt',
+        direction: 'desc',
+        column: 'updatedAt',
+        label: 'Updated'
+    },
+    {
+        path: 'updatedAt',
+        direction: 'asc',
+        column: 'updatedAt',
+        label: 'Updated',
+        alone: true
+    },
+    ...headerSorts('createdAt', 'createdAt', 'Created')
+];
+const NAME_SORTS = headerSorts('displayName', 'nameLower', 'Display name');
+const DESCRIPTION_SORTS = headerSorts('description', 'description', 'Description');
+/** The layouts page's header sorts; the ID ascending one is the default. */ export const LAYOUT_LIST_SORTS = [
+    ...ID_SORTS,
+    ...NAME_SORTS,
+    ...DESCRIPTION_SORTS,
+    ...TIME_SORTS
+];
+/**
+ * The layouts list's scope: live layouts. Every create stores `deletedAt: null`
+ * (`artifactCreateListKeys`) and a delete stamps the time, so the query leaves
+ * tombstones out instead of the page dropping them after the read (AGL-3680).
+ */ export const LAYOUT_LIST_BASE = [
+    {
+        path: 'deletedAt',
+        op: '==',
+        value: null
+    }
+];
+/** `hosts/{hostId}/layouts`. */ export const LAYOUT_LIST_QUERY = {
+    fields: [
+        NAME_FIELD,
+        ID_FIELD,
+        UPDATED_FIELD
+    ],
+    sorts: [
+        ARTIFACT_LIST_ORDER,
+        ...LAYOUT_LIST_SORTS
+    ],
+    search: ARTIFACT_NAME_SEARCH
+};
+export const LAYOUT_LIST_HEADERS = {
+    displayName: 'Display name',
+    $id: 'ID',
+    updatedAt: 'Updated'
+};
+/** The components card's header sorts; the ID ascending one is the default. */ export const COMPONENT_LIST_SORTS = [
+    ...ID_SORTS,
+    ...NAME_SORTS,
+    ...headerSorts('kind', 'kind', 'Used in'),
+    ...DESCRIPTION_SORTS,
+    ...TIME_SORTS
+];
+/** `hosts/{hostId}/components`. */ export const COMPONENT_LIST_QUERY = {
+    fields: [
+        NAME_FIELD,
+        {
+            column: 'kind',
+            kind: 'exact',
+            path: 'kind',
+            operators: [
+                'equals',
+                'isAnyOf'
+            ]
+        },
+        ID_FIELD,
+        UPDATED_FIELD
+    ],
+    sorts: [
+        ARTIFACT_LIST_ORDER,
+        ...COMPONENT_LIST_SORTS
+    ],
+    search: ARTIFACT_NAME_SEARCH
+};
+export const COMPONENT_LIST_HEADERS = {
+    displayName: 'Display name',
+    kind: 'Used in',
+    $id: 'ID',
+    updatedAt: 'Updated'
+};
+/*
+ * `hosts/{hostId}/templates`, as the library lists it: one row per template,
+ * except that a multi-page STARTER is one row (AGL-696) — its first live page
+ * carries `libraryRow: true` and the rest `false`, and a deleted template
+ * `false`, so the base clause below is both "one row per starter" and "no
+ * tombstones" without a single row being dropped after the read. Every page
+ * of a starter carries the starter's name keys, so a search for it finds the
+ * row whichever page leads it.
+ */ export const TEMPLATE_LIST_BASE = [
+    {
+        path: 'libraryRow',
+        op: '==',
+        value: true
+    }
+];
+/**
+ * The templates library's header sorts. It shows no ID column, so the walk
+ * stays the unlabelled default; Description sorts the page (see "The header
+ * sorts").
+ */ export const TEMPLATE_LIST_SORTS = [
+    ...NAME_SORTS,
+    ...headerSorts('kind', 'kind', 'Kind'),
+    ...headerSorts('source', 'source.type', 'Source'),
+    ...TIME_SORTS
+];
+export const TEMPLATE_LIST_QUERY = {
+    fields: [
+        NAME_FIELD,
+        {
+            column: 'kind',
+            kind: 'exact',
+            path: 'kind',
+            operators: [
+                'equals',
+                'isAnyOf'
+            ]
+        },
+        {
+            column: 'source',
+            kind: 'exact',
+            path: 'source.type',
+            operators: [
+                'equals',
+                'isAnyOf'
+            ]
+        },
+        UPDATED_FIELD
+    ],
+    sorts: [
+        ARTIFACT_LIST_ORDER,
+        ...TEMPLATE_LIST_SORTS
+    ],
+    search: ARTIFACT_NAME_SEARCH
+};
+export const TEMPLATE_LIST_HEADERS = {
+    displayName: 'Display name',
+    kind: 'Kind',
+    source: 'Source',
+    updatedAt: 'Updated'
+};
+/** The template kinds, by the stored `kind`. */ export const TEMPLATE_KIND_OPTIONS = [
+    {
+        value: 'page',
+        label: 'Page'
+    },
+    {
+        value: 'component',
+        label: 'Component'
+    },
+    {
+        value: 'layout',
+        label: 'Layout'
+    }
+];
+
+//# sourceMappingURL=artifact-list-queries.js.map

package/src/lib/app-utils/artifact-list-queries.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/artifact-list-queries.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { ListFilterField } from '@aglyn/shared-util-tools/list-query/list-filter'\nimport type { ListFilterOption } from '@aglyn/shared-util-tools/list-query/list-filter-codecs'\nimport {\n  LIST_QUERY_ID_PATH,\n  type ListQueryDeclaration,\n  type ListQueryFilter,\n  type ListQuerySort,\n} from '@aglyn/shared-util-tools/list-query/list-query-plan'\n\n/*\n * WHAT THE SITE ARTIFACT LISTS ASK FIRESTORE (AGL-3321).\n *\n * The layouts page, the components card and the templates library put every\n * clause their Filters panel accepts, and the quick-search word, on the query\n * — composed by `planListQuery` — and page what it answers. Nothing is matched\n * over the rows a page happened to read. The template gallery's shelves ask\n * the same keys (`template-gallery-dialog.component.tsx`), and so does the\n * email plugin's templates list, from its own declaration.\n *\n * ## The keys are WRITTEN\n *\n * A query finds a document by a stored value, so each list reads keys every\n * writer stamps (`artifactCreateListKeys`/`artifactRenameListKeys` in\n * `@aglyn/aglyn/app-utils/artifact-list-keys`) and\n * `tools/scripts/backfill-artifacts-list-keys.mjs` stamps on the documents\n * written before them:\n *\n *   nameTokens   the name's word prefixes — the search box and `contains`;\n *   nameLower    the normalized name — `equals`;\n *   kind         a component's `site`/`email`, a template's page/component/\n *                layout, stored even where a reader used to infer it;\n *   source.type  a template's provenance, `authored` where there was none;\n *   libraryRow   a template that is its own library row (below).\n *\n * ## The order is the document NAME, and that is what keeps it cheap\n *\n * `hostArtifactQuery` explains why these lists walk the document id: it is\n * the one order no writer can omit, so the walk is total. It is also the\n * order index merging serves with Firestore's automatic single-field\n * indexes: any mix of the equalities and the one array clause above, ordered\n * by `__name__`, needs no composite at all. The composites below exist only\n * for the one range each list offers — `Updated` — which must lead the order\n * it ranges over, so it pairs with each equality once.\n *\n * ## What is not offered, and why\n *\n *   - `startsWith`/`endsWith` on the name: a prefix range must lead the order,\n *     and these lists are not sorted by name.\n *   - `description` (a filter and a search target before): no token field,\n *     and a second token array could not share the query's one array clause\n *     with the search anyway.\n *   - `Created` ranges: a second range order would double the composites for\n *     a question `Updated` answers nearly as well; one range per list.\n *\n * ## The header sorts (AGL-3680)\n *\n * Every column sorts on the QUERY, by a stored value every writer stamps:\n *\n *   Display name  `nameLower` (above; a starter page's is its starter's\n *                 name, which is the name its library row shows);\n *   ID            the walk itself, either way;\n *   Updated,      `updatedAt` / `createdAt` — stamped by every create, and by\n *   Created       `backfill-artifacts-list-keys.mjs` on a document that\n *                 predates either;\n *   Used in, Kind the stored `kind`; Source the stored `source.type`;\n *   Description   a layout's or component's `description`, stored as `null`\n *                 when it has none (`artifactCreateListKeys` + the backfill),\n *                 because an `orderBy` DROPS a document that lacks the field.\n *                 A template row's description is its starter's when it\n *                 leads one, which is no stored field: it sorts the page.\n *\n * Each is `alone` — served only while no filter or search is on, falling\n * back to the list's default header order with a notice — so on the layouts\n * and components subcollections it costs no composite. Updated newest-first\n * is not `alone`: it is the order\n * the Updated range already imposes, so it pairs with every equality and\n * its composites are the ones the range needed anyway. The templates\n * library's `libraryRow` scope is an equality every order pairs with, so\n * each of its orders has one `(libraryRow, order)` composite.\n */\n\n/** The walk every artifact list keeps: the document name, ascending. */\nexport const ARTIFACT_LIST_ORDER: ListQuerySort = {\n  path: LIST_QUERY_ID_PATH,\n  direction: 'asc',\n}\n\n/** The name, by word prefix (`contains`) or whole (`equals`). */\nconst NAME_FIELD: ListFilterField = {\n  column: 'displayName',\n  kind: 'text',\n  path: 'displayName',\n  lowerPath: 'nameLower',\n  tokensPath: 'nameTokens',\n  operators: ['contains', 'equals'],\n}\n\n/** The document id, which the walk already orders by. */\nconst ID_FIELD: ListFilterField = {\n  column: '$id',\n  kind: 'id',\n  path: LIST_QUERY_ID_PATH,\n}\n\n/** The one range: `updatedAt`, which every writer stamps. */\nconst UPDATED_FIELD: ListFilterField = {\n  column: 'updatedAt',\n  kind: 'date',\n  path: 'updatedAt',\n  operators: ['is', 'after', 'onOrAfter', 'before', 'onOrBefore'],\n}\n\n/** The quick search every artifact list and gallery shelf offers: the name's word prefixes. */\nexport const ARTIFACT_NAME_SEARCH = { tokensPath: 'nameTokens' }\n\n/** One header's two orders, `alone` (see \"The header sorts\"). */\nconst headerSorts = (column: string, path: string, label: string): ListQuerySort[] => [\n  { path, direction: 'asc', column, label, alone: true },\n  { path, direction: 'desc', column, label, alone: true },\n]\n\n/**\n * The ID header: the walk ascending — the list's default, served under every\n * filter — and descending, `alone`.\n */\nconst ID_SORTS: readonly ListQuerySort[] = [\n  { path: LIST_QUERY_ID_PATH, direction: 'asc', column: '$id', label: 'ID' },\n  { path: LIST_QUERY_ID_PATH, direction: 'desc', column: '$id', label: 'ID', alone: true },\n]\n\n/**\n * Updated newest first FIRST: it is the order the Updated range imposes\n * (`planListQuery` takes the first declared order on the range's field), so\n * it is not `alone` — the range's composites already serve it.\n */\nconst TIME_SORTS: readonly ListQuerySort[] = [\n  { path: 'updatedAt', direction: 'desc', column: 'updatedAt', label: 'Updated' },\n  { path: 'updatedAt', direction: 'asc', column: 'updatedAt', label: 'Updated', alone: true },\n  ...headerSorts('createdAt', 'createdAt', 'Created'),\n]\n\nconst NAME_SORTS = headerSorts('displayName', 'nameLower', 'Display name')\nconst DESCRIPTION_SORTS = headerSorts('description', 'description', 'Description')\n\n/** The layouts page's header sorts; the ID ascending one is the default. */\nexport const LAYOUT_LIST_SORTS: readonly ListQuerySort[] = [\n  ...ID_SORTS,\n  ...NAME_SORTS,\n  ...DESCRIPTION_SORTS,\n  ...TIME_SORTS,\n]\n\n/**\n * The layouts list's scope: live layouts. Every create stores `deletedAt: null`\n * (`artifactCreateListKeys`) and a delete stamps the time, so the query leaves\n * tombstones out instead of the page dropping them after the read (AGL-3680).\n */\nexport const LAYOUT_LIST_BASE: readonly ListQueryFilter[] = [\n  { path: 'deletedAt', op: '==', value: null },\n]\n\n/** `hosts/{hostId}/layouts`. */\nexport const LAYOUT_LIST_QUERY: ListQueryDeclaration = {\n  fields: [NAME_FIELD, ID_FIELD, UPDATED_FIELD],\n  sorts: [ARTIFACT_LIST_ORDER, ...LAYOUT_LIST_SORTS],\n  search: ARTIFACT_NAME_SEARCH,\n}\n\nexport const LAYOUT_LIST_HEADERS: Readonly<Record<string, string>> = {\n  displayName: 'Display name',\n  $id: 'ID',\n  updatedAt: 'Updated',\n}\n\n/** The components card's header sorts; the ID ascending one is the default. */\nexport const COMPONENT_LIST_SORTS: readonly ListQuerySort[] = [\n  ...ID_SORTS,\n  ...NAME_SORTS,\n  ...headerSorts('kind', 'kind', 'Used in'),\n  ...DESCRIPTION_SORTS,\n  ...TIME_SORTS,\n]\n\n/** `hosts/{hostId}/components`. */\nexport const COMPONENT_LIST_QUERY: ListQueryDeclaration = {\n  fields: [\n    NAME_FIELD,\n    { column: 'kind', kind: 'exact', path: 'kind', operators: ['equals', 'isAnyOf'] },\n    ID_FIELD,\n    UPDATED_FIELD,\n  ],\n  sorts: [ARTIFACT_LIST_ORDER, ...COMPONENT_LIST_SORTS],\n  search: ARTIFACT_NAME_SEARCH,\n}\n\nexport const COMPONENT_LIST_HEADERS: Readonly<Record<string, string>> = {\n  displayName: 'Display name',\n  kind: 'Used in',\n  $id: 'ID',\n  updatedAt: 'Updated',\n}\n\n/*\n * `hosts/{hostId}/templates`, as the library lists it: one row per template,\n * except that a multi-page STARTER is one row (AGL-696) — its first live page\n * carries `libraryRow: true` and the rest `false`, and a deleted template\n * `false`, so the base clause below is both \"one row per starter\" and \"no\n * tombstones\" without a single row being dropped after the read. Every page\n * of a starter carries the starter's name keys, so a search for it finds the\n * row whichever page leads it.\n */\nexport const TEMPLATE_LIST_BASE: readonly ListQueryFilter[] = [\n  { path: 'libraryRow', op: '==', value: true },\n]\n\n/**\n * The templates library's header sorts. It shows no ID column, so the walk\n * stays the unlabelled default; Description sorts the page (see \"The header\n * sorts\").\n */\nexport const TEMPLATE_LIST_SORTS: readonly ListQuerySort[] = [\n  ...NAME_SORTS,\n  ...headerSorts('kind', 'kind', 'Kind'),\n  ...headerSorts('source', 'source.type', 'Source'),\n  ...TIME_SORTS,\n]\n\nexport const TEMPLATE_LIST_QUERY: ListQueryDeclaration = {\n  fields: [\n    NAME_FIELD,\n    { column: 'kind', kind: 'exact', path: 'kind', operators: ['equals', 'isAnyOf'] },\n    {\n      column: 'source',\n      kind: 'exact',\n      path: 'source.type',\n      operators: ['equals', 'isAnyOf'],\n    },\n    UPDATED_FIELD,\n  ],\n  sorts: [ARTIFACT_LIST_ORDER, ...TEMPLATE_LIST_SORTS],\n  search: ARTIFACT_NAME_SEARCH,\n}\n\nexport const TEMPLATE_LIST_HEADERS: Readonly<Record<string, string>> = {\n  displayName: 'Display name',\n  kind: 'Kind',\n  source: 'Source',\n  updatedAt: 'Updated',\n}\n\n/** The template kinds, by the stored `kind`. */\nexport const TEMPLATE_KIND_OPTIONS: readonly ListFilterOption[] = [\n  { value: 'page', label: 'Page' },\n  { value: 'component', label: 'Component' },\n  { value: 'layout', label: 'Layout' },\n]\n"],"names":["LIST_QUERY_ID_PATH","ARTIFACT_LIST_ORDER","path","direction","NAME_FIELD","column","kind","lowerPath","tokensPath","operators","ID_FIELD","UPDATED_FIELD","ARTIFACT_NAME_SEARCH","headerSorts","label","alone","ID_SORTS","TIME_SORTS","NAME_SORTS","DESCRIPTION_SORTS","LAYOUT_LIST_SORTS","LAYOUT_LIST_BASE","op","value","LAYOUT_LIST_QUERY","fields","sorts","search","LAYOUT_LIST_HEADERS","displayName","$id","updatedAt","COMPONENT_LIST_SORTS","COMPONENT_LIST_QUERY","COMPONENT_LIST_HEADERS","TEMPLATE_LIST_BASE","TEMPLATE_LIST_SORTS","TEMPLATE_LIST_QUERY","TEMPLATE_LIST_HEADERS","source","TEMPLATE_KIND_OPTIONS"],"mappings":"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"}

package/src/lib/app-utils/business-profile.d.ts

@@ -0,0 +1,171 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type HostSeoEntity } from './content-authors';
+/**
+ * A site's BUSINESS PROFILE (AGL-3661): what the business is, as everything
+ * that writes about it needs to know — the site's own pages, the structured
+ * data, and any generator a plugin brings.
+ *
+ * ── Most of it is already stored, so this stores only the rest ─────────────
+ *
+ * The site's name, its one-line description, its contact details, its hours,
+ * the areas it serves and its social profiles all have a home on the host
+ * document already: `seo.entity` (the publisher entity the JSON-LD is built
+ * from, edited in Setup → SEO) and `business` (the contact card the `host.*`
+ * tokens and the footer read, edited in Setup → Basic details). Copying them
+ * here would make two places to keep in step, and the copy would drift.
+ *
+ * So the profile document holds only what has no home yet — the services, the
+ * audience, the tone of voice — plus a line about the business and the area it
+ * serves for a site whose SEO entity does not say. {@link resolveBusinessProfile}
+ * reads the two together into one picture, field by field, and says where
+ * each value came from.
+ *
+ * ── Where it is stored ────────────────────────────────────────────────────
+ *
+ * `hosts/{hostId}/businessProfile/profile` for a site and
+ * `orgs/{orgId}/businessProfile/defaults` for the workspace, whose values a
+ * site inherits where it has none of its own. A subcollection document rather
+ * than a key on the host: the host document's `business` map is replaced
+ * whole by the contact card's save, and a key beside it would be one more
+ * thing a partial write could blank.
+ *
+ * ── Whose words win ───────────────────────────────────────────────────────
+ *
+ * Every stored value carries its source. What the owner typed is never
+ * replaced by anything else; what the guided start was told replaces only
+ * what a generator guessed; and a generator's guess fills only what is empty.
+ * {@link mergeBusinessProfilePrefill} is the one place that rule is applied.
+ */
+/** The collection a profile document lives in, under a host or an org. */
+export declare const BUSINESS_PROFILE_SUBCOLLECTION = "businessProfile";
+/** The site's profile document id. */
+export declare const BUSINESS_PROFILE_SITE_DOC = "profile";
+/** The workspace defaults document id. */
+export declare const BUSINESS_PROFILE_WORKSPACE_DOC = "defaults";
+/** Who wrote a stored value: the owner, the guided start's answers, or a generator. */
+export type BusinessProfileSource = 'owner' | 'start' | 'ai';
+/**
+ * Where a RESOLVED value came from: a stored source, the site's own settings
+ * (`seo.entity`, `business`, the display name), or the workspace defaults.
+ */
+export type BusinessProfileOrigin = BusinessProfileSource | 'site' | 'workspace';
+export declare const BUSINESS_TONES: readonly ["friendly", "professional", "playful", "premium", "plain"];
+export type BusinessTone = (typeof BUSINESS_TONES)[number];
+/** Each tone as the owner picks it and as a writer is told it. */
+export declare const BUSINESS_TONE_LABELS: Readonly<Record<BusinessTone, string>>;
+/** The fields the profile document stores itself. */
+export declare const BUSINESS_PROFILE_FIELDS: readonly ["whatYouDo", "services", "serviceArea", "audience", "tone", "toneNotes"];
+export type BusinessProfileField = (typeof BUSINESS_PROFILE_FIELDS)[number];
+/** Each field's ceiling, in characters; `services` is per item. */
+export declare const BUSINESS_PROFILE_MAX_CHARS: Readonly<Record<Exclude<BusinessProfileField, 'tone'>, number>>;
+/** At most this many services are kept. */
+export declare const BUSINESS_PROFILE_MAX_SERVICES = 12;
+/** The stored document, at either level. */
+export interface BusinessProfileDoc {
+    whatYouDo?: string;
+    services?: string[];
+    serviceArea?: string;
+    audience?: string;
+    tone?: BusinessTone | null;
+    toneNotes?: string;
+    /** Who wrote each stored value; a value without one is the owner's. */
+    sources?: Partial<Record<BusinessProfileField, BusinessProfileSource>>;
+    updatedAt?: unknown;
+    updatedBy?: string | null;
+}
+/** The values a write carries, before they are sanitized. */
+export type BusinessProfileValues = Partial<Pick<BusinessProfileDoc, 'whatYouDo' | 'services' | 'serviceArea' | 'audience' | 'tone' | 'toneNotes'>>;
+/** The host fields the profile reads. A closed surface, as the host tokens' is. */
+export interface BusinessProfileHost {
+    displayName?: string;
+    logoUrl?: string;
+    seo?: {
+        description?: string;
+        entity?: HostSeoEntity | null;
+    } | null;
+    business?: {
+        supportEmail?: string;
+        address?: string;
+        socialLinks?: Array<{
+            label?: string;
+            url?: string;
+        } | null> | null;
+    } | null;
+}
+export interface ResolvedBusinessField<T> {
+    value: T;
+    origin: BusinessProfileOrigin;
+}
+/** The picture every reader works from: each field's value and where it came from. */
+export interface ResolvedBusinessProfile {
+    name: ResolvedBusinessField<string> | null;
+    whatYouDo: ResolvedBusinessField<string> | null;
+    services: ResolvedBusinessField<string[]> | null;
+    serviceArea: ResolvedBusinessField<string> | null;
+    audience: ResolvedBusinessField<string> | null;
+    tone: ResolvedBusinessField<BusinessTone> | null;
+    toneNotes: ResolvedBusinessField<string> | null;
+    /** The schema.org business type the SEO entity names, e.g. `Plumber`. */
+    businessType: string | null;
+    /** Real contact details, each only where the owner entered it in the site's settings. */
+    contact: {
+        email: string | null;
+        phone: string | null;
+        address: string | null;
+        hours: string | null;
+    };
+    /** The site's social and other profiles, https only. */
+    profiles: string[];
+    logo: string | null;
+}
+/** The source a stored, non-empty value carries; the owner's when none is recorded. */
+export declare function businessProfileSourceOf(doc: BusinessProfileDoc | null | undefined, field: BusinessProfileField): BusinessProfileSource | null;
+/** Every value a write may carry, sanitized; an absent field stays absent. */
+export declare function sanitizeBusinessProfileValues(values: BusinessProfileValues): BusinessProfileValues;
+/**
+ * The document a generator's or the guided start's values make of the stored
+ * one: each value fills a field that is empty or was written by a source that
+ * weighs less, and nothing else. `null` when nothing would change, so a caller
+ * writes only when there is something to write.
+ */
+export declare function mergeBusinessProfilePrefill(current: BusinessProfileDoc | null | undefined, values: BusinessProfileValues, source: Exclude<BusinessProfileSource, 'owner'>): BusinessProfileDoc | null;
+/**
+ * The document the owner's save makes: every field they changed becomes
+ * theirs, and a field they left as it was keeps the source it had — so saving
+ * the form after correcting one line does not claim every suggestion on it.
+ */
+export declare function businessProfileOwnerWrite(current: BusinessProfileDoc | null | undefined, edited: BusinessProfileValues): Pick<BusinessProfileDoc, BusinessProfileField | 'sources'>;
+/**
+ * The profile as every reader sees it, field by field (AGL-3661):
+ *
+ * 1. what the OWNER typed into the site's profile;
+ * 2. what the site's own settings say (the SEO entity, the contact card, the
+ *    display name), which the owner typed too, elsewhere;
+ * 3. what the guided start or a generator stored on the site's profile;
+ * 4. the workspace defaults.
+ *
+ * Contact details, the logo and the profiles come from the site's settings
+ * only: nothing but the owner's own entry may say how to reach the business.
+ */
+export declare function resolveBusinessProfile(input: {
+    host: BusinessProfileHost | null | undefined;
+    site?: BusinessProfileDoc | null;
+    workspace?: BusinessProfileDoc | null;
+}): ResolvedBusinessProfile;
+/** Each origin as the profile screen labels it. */
+export declare const BUSINESS_PROFILE_ORIGIN_LABELS: Readonly<Record<BusinessProfileOrigin, string>>;