@aglyn/aglyn 1.0.0-beta.172 → 1.0.0-beta.174

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/aglyn",
-  "version": "1.0.0-beta.172",
+  "version": "1.0.0-beta.174",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -33,15 +33,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-enums": "1.0.0-beta.172",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.172",
-    "@aglyn/shared-data-types": "1.0.0-beta.172",
-    "@aglyn/shared-util-email": "1.0.0-beta.172",
-    "@aglyn/shared-util-http": "1.0.0-beta.172",
-    "@aglyn/shared-util-logger": "1.0.0-beta.172",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.172",
-    "@aglyn/shared-util-tools": "1.0.0-beta.172",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.172",
+    "@aglyn/shared-data-enums": "1.0.0-beta.174",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.174",
+    "@aglyn/shared-data-types": "1.0.0-beta.174",
+    "@aglyn/shared-util-email": "1.0.0-beta.174",
+    "@aglyn/shared-util-http": "1.0.0-beta.174",
+    "@aglyn/shared-util-logger": "1.0.0-beta.174",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.174",
+    "@aglyn/shared-util-tools": "1.0.0-beta.174",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.174",
     "@data-driven-forms/react-form-renderer": "^4.2.0",
     "@msgpack/msgpack": "^3.1.3",
     "@types/unist": "^3.0.3",

package/src/lib/app-utils/campaign-membership.d.ts

@@ -46,8 +46,9 @@ export declare function normalizeCampaignIds(raw: unknown): string[];
  * The campaigns a HOST resource — a form, a screen — belongs to.
  *
  * Host resources carry the field at the top of the document: they belong to
- * one site, which is the same site the campaign belongs to, so there is no
- * second holder to keep the edge away from.
+ * one site, and whoever may read the resource may read which of the org's
+ * campaigns it is filed under, so there is no second holder to keep the edge
+ * away from.
  */
 export declare function readCampaignIds(resource: Record<string, unknown> | null | undefined): string[];
 /**
@@ -100,12 +101,13 @@ export declare function campaignMembershipUnchanged(stored: readonly string[], s
  * detach fails the build rather than shipping a campaign whose removal leaves
  * that collection pointing at nothing.
  *
- * A lead (`hosts/{hostId}/leads/{personKey}`, AGL-3254) carries the field at
- * the top of its document like a form does: a lead is one site's own record,
- * captured there and worked there, so there is no second holder to keep the
- * edge away from. It joins a campaign by hand — the New lead drawer, the CSV
- * import, the list's bulk bar — or by being enrolled in a sequence that is
- * in one, and it hands the membership to the contact it converts into.
+ * `leads` is here for the site rows the lead migration (AGL-3276) has not
+ * reached. A live lead is an org row (`orgs/{orgId}/leads/{personKey}`) that
+ * carries the field at the top of its document like a form does, and the
+ * deletion walks that collection by name beside this list. A lead joins a
+ * campaign by hand — the New lead drawer, the CSV import, the list's bulk
+ * bar — or by being enrolled in a sequence that is in one, and it hands the
+ * membership to the contact it converts into.
  *
  * Contacts are deliberately NOT here. They live on the org
  * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a

package/src/lib/app-utils/campaign-membership.js

@@ -19,7 +19,7 @@
  *
  * ## The edge is a field on the RESOURCE, not a list on the campaign
  *
- * A campaign container lives at `hosts/{hostId}/emailCampaigns/{campaignId}`
+ * A campaign container lives at `orgs/{orgId}/emailCampaigns/{campaignId}`
  * and names nothing outside itself. A send joins one by carrying
  * `emailCampaignId`; every other member joins the same way, through
  * {@link CAMPAIGN_MEMBERSHIP_FIELD} on its own document.
@@ -98,8 +98,9 @@
  * The campaigns a HOST resource — a form, a screen — belongs to.
  *
  * Host resources carry the field at the top of the document: they belong to
- * one site, which is the same site the campaign belongs to, so there is no
- * second holder to keep the edge away from.
+ * one site, and whoever may read the resource may read which of the org's
+ * campaigns it is filed under, so there is no second holder to keep the edge
+ * away from.
  */ export function readCampaignIds(resource) {
     return normalizeCampaignIds((resource != null ? resource : {})[CAMPAIGN_MEMBERSHIP_FIELD]);
 }
@@ -164,12 +165,13 @@
  * detach fails the build rather than shipping a campaign whose removal leaves
  * that collection pointing at nothing.
  *
- * A lead (`hosts/{hostId}/leads/{personKey}`, AGL-3254) carries the field at
- * the top of its document like a form does: a lead is one site's own record,
- * captured there and worked there, so there is no second holder to keep the
- * edge away from. It joins a campaign by hand — the New lead drawer, the CSV
- * import, the list's bulk bar — or by being enrolled in a sequence that is
- * in one, and it hands the membership to the contact it converts into.
+ * `leads` is here for the site rows the lead migration (AGL-3276) has not
+ * reached. A live lead is an org row (`orgs/{orgId}/leads/{personKey}`) that
+ * carries the field at the top of its document like a form does, and the
+ * deletion walks that collection by name beside this list. A lead joins a
+ * campaign by hand — the New lead drawer, the CSV import, the list's bulk
+ * bar — or by being enrolled in a sequence that is in one, and it hands the
+ * membership to the contact it converts into.
  *
  * Contacts are deliberately NOT here. They live on the org
  * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a

package/src/lib/app-utils/campaign-membership.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-membership.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\n/**\n * WHAT ELSE IS IN A CAMPAIGN: the edge between a campaign and the forms,\n * screens and people a push is coordinated across.\n *\n * ## The edge is a field on the RESOURCE, not a list on the campaign\n *\n * A campaign container lives at `hosts/{hostId}/emailCampaigns/{campaignId}`\n * and names nothing outside itself. A send joins one by carrying\n * `emailCampaignId`; every other member joins the same way, through\n * {@link CAMPAIGN_MEMBERSHIP_FIELD} on its own document.\n *\n * Three properties decide it, and all three point the same way:\n *\n *  - **Reading is free where it is asked.** A form's own page reads the form\n *    document to draw anything at all, so the campaign comes with it. A\n *    membership collection under the campaign would make \"which campaign is\n *    this in\" a query issued on mount by every resource page, for a fact one\n *    field already carries.\n *  - **The reduction is already gated this way.** `campaign-manage.ts` clears\n *    `emailCampaignId` from every send before it removes a container, so no\n *    send is left naming one that is gone. Extending that pass to the\n *    membership field is the SAME mechanism; a membership collection would be\n *    a second, different deletion story beside it.\n *  - **Deleting a MEMBER can leave nothing behind.** The campaign holds no\n *    list, so a deleted form takes its own edge with it. This matters most on\n *    a contact: an erasure removes the document, and a membership row stored\n *    anywhere else would survive it holding the id of a person who asked to\n *    be forgotten.\n *\n * ## Plural, because a landing page outlives one campaign\n *\n * The field is an ARRAY. A signup form built for the spring push is the same\n * form the summer push places, and a single-valued field would make the\n * second assignment silently erase the first — a campaign losing a member\n * with nothing on screen to say so. The automation step that has always\n * written this edge (`assignCampaign`) already used `arrayUnion`, so the\n * product has treated it as many-to-many from the start.\n *\n * ## Ids, never names\n *\n * A campaign's name is editable, and every reader here resolves the name from\n * the campaign document at read time. Renaming a campaign therefore moves no\n * membership: the stored value is the container's document id, which nothing\n * rewrites.\n */\n\nimport { contactFacetPath, readContactFacet } from './contacts'\n\n/**\n * The field naming the campaigns a resource belongs to.\n *\n * Not `emailCampaignId`, which is the SEND's field: on a send document the\n * word `campaignId` already means the send's own id — it is what `cid`\n * carries into every unsubscribe footer — so that collection needed a\n * different word. A form, a screen and a contact have no second meaning for\n * it, and the plural says the resource may be in more than one.\n */\nexport const CAMPAIGN_MEMBERSHIP_FIELD = 'campaignIds'\n\n/**\n * How many campaigns one resource may name.\n *\n * A ceiling on the FIELD, not on the product: an array Firestore has to index\n * on every write is not the place to discover that a script has been adding\n * an id a day for a year. Twenty is far past what a person assigns by hand\n * and far short of anything that costs a write.\n */\nexport const CAMPAIGN_MEMBERSHIP_CAP = 20\n\n/**\n * A stored membership array as a clean list of ids.\n *\n * Deduped, trimmed, non-strings dropped, capped. Every reader goes through\n * this because the field is written by three consoles and one automation\n * step, and a surface that trusted the raw value would render `undefined` as\n * a chip the first time one of them wrote a blank.\n */\nexport function normalizeCampaignIds(raw: unknown): string[] {\n  if (!Array.isArray(raw)) return []\n  const seen: string[] = []\n  for (const entry of raw) {\n    if (typeof entry !== 'string') continue\n    const id = entry.trim()\n    if (!id || seen.includes(id)) continue\n    seen.push(id)\n    if (seen.length >= CAMPAIGN_MEMBERSHIP_CAP) break\n  }\n  return seen\n}\n\n/**\n * The campaigns a HOST resource — a form, a screen — belongs to.\n *\n * Host resources carry the field at the top of the document: they belong to\n * one site, which is the same site the campaign belongs to, so there is no\n * second holder to keep the edge away from.\n */\nexport function readCampaignIds(\n  resource: Record<string, unknown> | null | undefined,\n): string[] {\n  return normalizeCampaignIds((resource ?? {})[CAMPAIGN_MEMBERSHIP_FIELD])\n}\n\n/**\n * The dotted path to a contact's membership, inside ONE holder's facet.\n *\n * A contact document is shared by every site in the org — one human who\n * touched two sites is one row — and almost nothing on it is legitimately\n * shared. Which campaigns a merchant has filed a person under is that\n * merchant's business record on exactly the footing their notes and tags are,\n * so it lives at `facets.{groupId}.campaignIds` and not at the top of the\n * document, where every other site in an agency's account could read it.\n */\nexport function contactCampaignFieldPath(groupId: string): string {\n  return contactFacetPath(groupId, CAMPAIGN_MEMBERSHIP_FIELD)\n}\n\n/** The campaigns ONE holder has filed this contact under. */\nexport function readContactCampaignIds(\n  contact: Record<string, unknown> | null | undefined,\n  groupId: string,\n): string[] {\n  return normalizeCampaignIds(readContactFacet(contact, groupId).campaignIds)\n}\n\n/**\n * The membership a save should write, given what is on screen.\n *\n * Pure, and shared by the three consoles that offer the picker, because the\n * decision each of them makes is identical and is not obvious: an EMPTY\n * selection has to be stored as an empty array rather than as a removed\n * field.\n *\n * Removing the field would read the same to every surface here — the readers\n * above answer `[]` either way — and would be wrong for the one reader that\n * is not a surface. `campaign-manage.ts` finds a campaign's members with\n * `array-contains`, which matches on the automatic single-field index; that\n * index has an entry only while the array does, so the two shapes are the\n * same to a reader and different to a writer only in cost. Storing `[]` keeps\n * one shape for \"belongs to no campaign\" across every writer, which is the\n * property the send collection's own detach comment argues for one field\n * over.\n *\n * @returns the value to store under {@link CAMPAIGN_MEMBERSHIP_FIELD}.\n */\nexport function campaignMembershipValue(selected: readonly string[]): string[] {\n  return normalizeCampaignIds(selected)\n}\n\n/**\n * Whether a document's stored membership already says what a save would.\n *\n * Order-insensitive: a picker hands back its options' order and the stored\n * array is in the order it was written, so comparing them literally would\n * report a change on every open and leave Save permanently enabled.\n */\nexport function campaignMembershipUnchanged(\n  stored: readonly string[],\n  selected: readonly string[],\n): boolean {\n  if (stored.length !== selected.length) return false\n  const sortedStored = [...stored].sort()\n  const sortedSelected = [...selected].sort()\n  return sortedStored.every((id, index) => id === sortedSelected[index])\n}\n\n/**\n * The host subcollections whose documents may name a campaign.\n *\n * The list a campaign's deletion walks, and the list this feature's coverage\n * spec reads — so a collection that grows the picker without growing the\n * detach fails the build rather than shipping a campaign whose removal leaves\n * that collection pointing at nothing.\n *\n * A lead (`hosts/{hostId}/leads/{personKey}`, AGL-3254) carries the field at\n * the top of its document like a form does: a lead is one site's own record,\n * captured there and worked there, so there is no second holder to keep the\n * edge away from. It joins a campaign by hand — the New lead drawer, the CSV\n * import, the list's bulk bar — or by being enrolled in a sequence that is\n * in one, and it hands the membership to the contact it converts into.\n *\n * Contacts are deliberately NOT here. They live on the org\n * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a\n * per-holder facet — so they are detached by their own pass, against a field\n * path that names the group. Nor are a plugin's own members — a sequence and\n * its enrollments live under the org, in collections the core does not name\n * — so a plugin registers a detacher for those\n * (`plugin-manager/plugin-membership-detach.ts`) and the deletion runs it.\n */\nexport const CAMPAIGN_MEMBER_HOST_COLLECTIONS = ['forms', 'screens', 'leads'] as const\n\nexport type CampaignMemberHostCollection =\n  (typeof CAMPAIGN_MEMBER_HOST_COLLECTIONS)[number]\n"],"names":["contactFacetPath","readContactFacet","CAMPAIGN_MEMBERSHIP_FIELD","CAMPAIGN_MEMBERSHIP_CAP","normalizeCampaignIds","raw","Array","isArray","seen","entry","id","trim","includes","push","length","readCampaignIds","resource","contactCampaignFieldPath","groupId","readContactCampaignIds","contact","campaignIds","campaignMembershipValue","selected","campaignMembershipUnchanged","stored","sortedStored","sort","sortedSelected","every","index","CAMPAIGN_MEMBER_HOST_COLLECTIONS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CC,GAED,SAASA,gBAAgB,EAAEC,gBAAgB,QAAQ,gBAAY;AAE/D;;;;;;;;CAQC,GACD,OAAO,MAAMC,4BAA4B,cAAa;AAEtD;;;;;;;CAOC,GACD,OAAO,MAAMC,0BAA0B,GAAE;AAEzC;;;;;;;CAOC,GACD,OAAO,SAASC,qBAAqBC,GAAY;IAC/C,IAAI,CAACC,MAAMC,OAAO,CAACF,MAAM,OAAO,EAAE;IAClC,MAAMG,OAAiB,EAAE;IACzB,KAAK,MAAMC,SAASJ,IAAK;QACvB,IAAI,OAAOI,UAAU,UAAU;QAC/B,MAAMC,KAAKD,MAAME,IAAI;QACrB,IAAI,CAACD,MAAMF,KAAKI,QAAQ,CAACF,KAAK;QAC9BF,KAAKK,IAAI,CAACH;QACV,IAAIF,KAAKM,MAAM,IAAIX,yBAAyB;IAC9C;IACA,OAAOK;AACT;AAEA;;;;;;CAMC,GACD,OAAO,SAASO,gBACdC,QAAoD;IAEpD,OAAOZ,qBAAqB,CAACY,mBAAAA,WAAY,CAAC,EAAE,CAACd,0BAA0B;AACzE;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASe,yBAAyBC,OAAe;IACtD,OAAOlB,iBAAiBkB,SAAShB;AACnC;AAEA,2DAA2D,GAC3D,OAAO,SAASiB,uBACdC,OAAmD,EACnDF,OAAe;IAEf,OAAOd,qBAAqBH,iBAAiBmB,SAASF,SAASG,WAAW;AAC5E;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,wBAAwBC,QAA2B;IACjE,OAAOnB,qBAAqBmB;AAC9B;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,4BACdC,MAAyB,EACzBF,QAA2B;IAE3B,IAAIE,OAAOX,MAAM,KAAKS,SAAST,MAAM,EAAE,OAAO;IAC9C,MAAMY,eAAe;WAAID;KAAO,CAACE,IAAI;IACrC,MAAMC,iBAAiB;WAAIL;KAAS,CAACI,IAAI;IACzC,OAAOD,aAAaG,KAAK,CAAC,CAACnB,IAAIoB,QAAUpB,OAAOkB,cAAc,CAACE,MAAM;AACvE;AAEA;;;;;;;;;;;;;;;;;;;;;;CAsBC,GACD,OAAO,MAAMC,mCAAmC;IAAC;IAAS;IAAW;CAAQ,CAAS"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/campaign-membership.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\n/**\n * WHAT ELSE IS IN A CAMPAIGN: the edge between a campaign and the forms,\n * screens and people a push is coordinated across.\n *\n * ## The edge is a field on the RESOURCE, not a list on the campaign\n *\n * A campaign container lives at `orgs/{orgId}/emailCampaigns/{campaignId}`\n * and names nothing outside itself. A send joins one by carrying\n * `emailCampaignId`; every other member joins the same way, through\n * {@link CAMPAIGN_MEMBERSHIP_FIELD} on its own document.\n *\n * Three properties decide it, and all three point the same way:\n *\n *  - **Reading is free where it is asked.** A form's own page reads the form\n *    document to draw anything at all, so the campaign comes with it. A\n *    membership collection under the campaign would make \"which campaign is\n *    this in\" a query issued on mount by every resource page, for a fact one\n *    field already carries.\n *  - **The reduction is already gated this way.** `campaign-manage.ts` clears\n *    `emailCampaignId` from every send before it removes a container, so no\n *    send is left naming one that is gone. Extending that pass to the\n *    membership field is the SAME mechanism; a membership collection would be\n *    a second, different deletion story beside it.\n *  - **Deleting a MEMBER can leave nothing behind.** The campaign holds no\n *    list, so a deleted form takes its own edge with it. This matters most on\n *    a contact: an erasure removes the document, and a membership row stored\n *    anywhere else would survive it holding the id of a person who asked to\n *    be forgotten.\n *\n * ## Plural, because a landing page outlives one campaign\n *\n * The field is an ARRAY. A signup form built for the spring push is the same\n * form the summer push places, and a single-valued field would make the\n * second assignment silently erase the first — a campaign losing a member\n * with nothing on screen to say so. The automation step that has always\n * written this edge (`assignCampaign`) already used `arrayUnion`, so the\n * product has treated it as many-to-many from the start.\n *\n * ## Ids, never names\n *\n * A campaign's name is editable, and every reader here resolves the name from\n * the campaign document at read time. Renaming a campaign therefore moves no\n * membership: the stored value is the container's document id, which nothing\n * rewrites.\n */\n\nimport { contactFacetPath, readContactFacet } from './contacts'\n\n/**\n * The field naming the campaigns a resource belongs to.\n *\n * Not `emailCampaignId`, which is the SEND's field: on a send document the\n * word `campaignId` already means the send's own id — it is what `cid`\n * carries into every unsubscribe footer — so that collection needed a\n * different word. A form, a screen and a contact have no second meaning for\n * it, and the plural says the resource may be in more than one.\n */\nexport const CAMPAIGN_MEMBERSHIP_FIELD = 'campaignIds'\n\n/**\n * How many campaigns one resource may name.\n *\n * A ceiling on the FIELD, not on the product: an array Firestore has to index\n * on every write is not the place to discover that a script has been adding\n * an id a day for a year. Twenty is far past what a person assigns by hand\n * and far short of anything that costs a write.\n */\nexport const CAMPAIGN_MEMBERSHIP_CAP = 20\n\n/**\n * A stored membership array as a clean list of ids.\n *\n * Deduped, trimmed, non-strings dropped, capped. Every reader goes through\n * this because the field is written by three consoles and one automation\n * step, and a surface that trusted the raw value would render `undefined` as\n * a chip the first time one of them wrote a blank.\n */\nexport function normalizeCampaignIds(raw: unknown): string[] {\n  if (!Array.isArray(raw)) return []\n  const seen: string[] = []\n  for (const entry of raw) {\n    if (typeof entry !== 'string') continue\n    const id = entry.trim()\n    if (!id || seen.includes(id)) continue\n    seen.push(id)\n    if (seen.length >= CAMPAIGN_MEMBERSHIP_CAP) break\n  }\n  return seen\n}\n\n/**\n * The campaigns a HOST resource — a form, a screen — belongs to.\n *\n * Host resources carry the field at the top of the document: they belong to\n * one site, and whoever may read the resource may read which of the org's\n * campaigns it is filed under, so there is no second holder to keep the edge\n * away from.\n */\nexport function readCampaignIds(\n  resource: Record<string, unknown> | null | undefined,\n): string[] {\n  return normalizeCampaignIds((resource ?? {})[CAMPAIGN_MEMBERSHIP_FIELD])\n}\n\n/**\n * The dotted path to a contact's membership, inside ONE holder's facet.\n *\n * A contact document is shared by every site in the org — one human who\n * touched two sites is one row — and almost nothing on it is legitimately\n * shared. Which campaigns a merchant has filed a person under is that\n * merchant's business record on exactly the footing their notes and tags are,\n * so it lives at `facets.{groupId}.campaignIds` and not at the top of the\n * document, where every other site in an agency's account could read it.\n */\nexport function contactCampaignFieldPath(groupId: string): string {\n  return contactFacetPath(groupId, CAMPAIGN_MEMBERSHIP_FIELD)\n}\n\n/** The campaigns ONE holder has filed this contact under. */\nexport function readContactCampaignIds(\n  contact: Record<string, unknown> | null | undefined,\n  groupId: string,\n): string[] {\n  return normalizeCampaignIds(readContactFacet(contact, groupId).campaignIds)\n}\n\n/**\n * The membership a save should write, given what is on screen.\n *\n * Pure, and shared by the three consoles that offer the picker, because the\n * decision each of them makes is identical and is not obvious: an EMPTY\n * selection has to be stored as an empty array rather than as a removed\n * field.\n *\n * Removing the field would read the same to every surface here — the readers\n * above answer `[]` either way — and would be wrong for the one reader that\n * is not a surface. `campaign-manage.ts` finds a campaign's members with\n * `array-contains`, which matches on the automatic single-field index; that\n * index has an entry only while the array does, so the two shapes are the\n * same to a reader and different to a writer only in cost. Storing `[]` keeps\n * one shape for \"belongs to no campaign\" across every writer, which is the\n * property the send collection's own detach comment argues for one field\n * over.\n *\n * @returns the value to store under {@link CAMPAIGN_MEMBERSHIP_FIELD}.\n */\nexport function campaignMembershipValue(selected: readonly string[]): string[] {\n  return normalizeCampaignIds(selected)\n}\n\n/**\n * Whether a document's stored membership already says what a save would.\n *\n * Order-insensitive: a picker hands back its options' order and the stored\n * array is in the order it was written, so comparing them literally would\n * report a change on every open and leave Save permanently enabled.\n */\nexport function campaignMembershipUnchanged(\n  stored: readonly string[],\n  selected: readonly string[],\n): boolean {\n  if (stored.length !== selected.length) return false\n  const sortedStored = [...stored].sort()\n  const sortedSelected = [...selected].sort()\n  return sortedStored.every((id, index) => id === sortedSelected[index])\n}\n\n/**\n * The host subcollections whose documents may name a campaign.\n *\n * The list a campaign's deletion walks, and the list this feature's coverage\n * spec reads — so a collection that grows the picker without growing the\n * detach fails the build rather than shipping a campaign whose removal leaves\n * that collection pointing at nothing.\n *\n * `leads` is here for the site rows the lead migration (AGL-3276) has not\n * reached. A live lead is an org row (`orgs/{orgId}/leads/{personKey}`) that\n * carries the field at the top of its document like a form does, and the\n * deletion walks that collection by name beside this list. A lead joins a\n * campaign by hand — the New lead drawer, the CSV import, the list's bulk\n * bar — or by being enrolled in a sequence that is in one, and it hands the\n * membership to the contact it converts into.\n *\n * Contacts are deliberately NOT here. They live on the org\n * (`orgs/{orgId}/contacts`), not the host, and carry the field inside a\n * per-holder facet — so they are detached by their own pass, against a field\n * path that names the group. Nor are a plugin's own members — a sequence and\n * its enrollments live under the org, in collections the core does not name\n * — so a plugin registers a detacher for those\n * (`plugin-manager/plugin-membership-detach.ts`) and the deletion runs it.\n */\nexport const CAMPAIGN_MEMBER_HOST_COLLECTIONS = ['forms', 'screens', 'leads'] as const\n\nexport type CampaignMemberHostCollection =\n  (typeof CAMPAIGN_MEMBER_HOST_COLLECTIONS)[number]\n"],"names":["contactFacetPath","readContactFacet","CAMPAIGN_MEMBERSHIP_FIELD","CAMPAIGN_MEMBERSHIP_CAP","normalizeCampaignIds","raw","Array","isArray","seen","entry","id","trim","includes","push","length","readCampaignIds","resource","contactCampaignFieldPath","groupId","readContactCampaignIds","contact","campaignIds","campaignMembershipValue","selected","campaignMembershipUnchanged","stored","sortedStored","sort","sortedSelected","every","index","CAMPAIGN_MEMBER_HOST_COLLECTIONS"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4CC,GAED,SAASA,gBAAgB,EAAEC,gBAAgB,QAAQ,gBAAY;AAE/D;;;;;;;;CAQC,GACD,OAAO,MAAMC,4BAA4B,cAAa;AAEtD;;;;;;;CAOC,GACD,OAAO,MAAMC,0BAA0B,GAAE;AAEzC;;;;;;;CAOC,GACD,OAAO,SAASC,qBAAqBC,GAAY;IAC/C,IAAI,CAACC,MAAMC,OAAO,CAACF,MAAM,OAAO,EAAE;IAClC,MAAMG,OAAiB,EAAE;IACzB,KAAK,MAAMC,SAASJ,IAAK;QACvB,IAAI,OAAOI,UAAU,UAAU;QAC/B,MAAMC,KAAKD,MAAME,IAAI;QACrB,IAAI,CAACD,MAAMF,KAAKI,QAAQ,CAACF,KAAK;QAC9BF,KAAKK,IAAI,CAACH;QACV,IAAIF,KAAKM,MAAM,IAAIX,yBAAyB;IAC9C;IACA,OAAOK;AACT;AAEA;;;;;;;CAOC,GACD,OAAO,SAASO,gBACdC,QAAoD;IAEpD,OAAOZ,qBAAqB,CAACY,mBAAAA,WAAY,CAAC,EAAE,CAACd,0BAA0B;AACzE;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASe,yBAAyBC,OAAe;IACtD,OAAOlB,iBAAiBkB,SAAShB;AACnC;AAEA,2DAA2D,GAC3D,OAAO,SAASiB,uBACdC,OAAmD,EACnDF,OAAe;IAEf,OAAOd,qBAAqBH,iBAAiBmB,SAASF,SAASG,WAAW;AAC5E;AAEA;;;;;;;;;;;;;;;;;;;CAmBC,GACD,OAAO,SAASC,wBAAwBC,QAA2B;IACjE,OAAOnB,qBAAqBmB;AAC9B;AAEA;;;;;;CAMC,GACD,OAAO,SAASC,4BACdC,MAAyB,EACzBF,QAA2B;IAE3B,IAAIE,OAAOX,MAAM,KAAKS,SAAST,MAAM,EAAE,OAAO;IAC9C,MAAMY,eAAe;WAAID;KAAO,CAACE,IAAI;IACrC,MAAMC,iBAAiB;WAAIL;KAAS,CAACI,IAAI;IACzC,OAAOD,aAAaG,KAAK,CAAC,CAACnB,IAAIoB,QAAUpB,OAAOkB,cAAc,CAACE,MAAM;AACvE;AAEA;;;;;;;;;;;;;;;;;;;;;;;CAuBC,GACD,OAAO,MAAMC,mCAAmC;IAAC;IAAS;IAAW;CAAQ,CAAS"}

package/src/lib/app-utils/compose-layout-props.d.ts

@@ -61,11 +61,15 @@ export declare function applyLayoutProps<N extends AglynNodeSchema = AglynNodeSc
 /**
  * A screen grafted through its whole layout chain, innermost first, with each
  * layout's properties applied from the screen's values for that layout
- * (`layoutPropValues`, keyed by layout id).
+ * (`layoutPropValues`, keyed by layout id), and then the screen's per-page
+ * restyling of that layout's elements (`layoutStyleOverrides`, AGL-3286) —
+ * after the properties, so a page's style wins over whatever a property
+ * bound, and before the graft, so an element the layout hides for this page
+ * is simply not there to be styled.
  *
  * The one composition the published page, the besigner's Preview and its
  * layout chrome all run, so none of them can disagree about which value a
  * layout renders with.
  */
-export declare function composeLayoutChainWithProps<N extends AglynNodeSchema = AglynNodeSchema>(chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>, screenNodes: NormalizedNodes<N>, layoutPropValues?: unknown): NormalizedNodes<N>;
+export declare function composeLayoutChainWithProps<N extends AglynNodeSchema = AglynNodeSchema>(chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>, screenNodes: NormalizedNodes<N>, layoutPropValues?: unknown, layoutStyleOverrides?: unknown): NormalizedNodes<N>;
 export default composeLayoutChainWithProps;

package/src/lib/app-utils/compose-layout-props.js

@@ -16,6 +16,7 @@
  */ import { NODE_ROOT_ID } from "../canvas-manager/canvas-manager.js";
 import { composeLayoutChainAndScreenNodes } from "./compose-layout-nodes.js";
 import { applyDeclaredProps } from "./compose-reusable-components.js";
+import { applyLayoutStyleOverrides, layoutStyleOverridesFor } from "./layout-style-overrides.js";
 /**
  * Screen-version key holding the screen's values for the layouts it renders
  * inside, beside the `layoutId` binding. Persisted in screen version documents
@@ -48,13 +49,17 @@ import { applyDeclaredProps } from "./compose-reusable-components.js";
 /**
  * A screen grafted through its whole layout chain, innermost first, with each
  * layout's properties applied from the screen's values for that layout
- * (`layoutPropValues`, keyed by layout id).
+ * (`layoutPropValues`, keyed by layout id), and then the screen's per-page
+ * restyling of that layout's elements (`layoutStyleOverrides`, AGL-3286) —
+ * after the properties, so a page's style wins over whatever a property
+ * bound, and before the graft, so an element the layout hides for this page
+ * is simply not there to be styled.
  *
  * The one composition the published page, the besigner's Preview and its
  * layout chrome all run, so none of them can disagree about which value a
  * layout renders with.
- */ export function composeLayoutChainWithProps(chain, screenNodes, layoutPropValues) {
-    return composeLayoutChainAndScreenNodes(chain.map((entry)=>applyLayoutProps(entry == null ? void 0 : entry.nodes, entry == null ? void 0 : entry.props, layoutPropValuesFor(layoutPropValues, entry == null ? void 0 : entry.layoutId))), screenNodes);
+ */ export function composeLayoutChainWithProps(chain, screenNodes, layoutPropValues, layoutStyleOverrides) {
+    return composeLayoutChainAndScreenNodes(chain.map((entry)=>applyLayoutStyleOverrides(applyLayoutProps(entry == null ? void 0 : entry.nodes, entry == null ? void 0 : entry.props, layoutPropValuesFor(layoutPropValues, entry == null ? void 0 : entry.layoutId)), layoutStyleOverridesFor(layoutStyleOverrides, entry == null ? void 0 : entry.layoutId))), screenNodes);
 }
 export default composeLayoutChainWithProps;
 

package/src/lib/app-utils/compose-layout-props.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/compose-layout-props.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 {\n  AglynNodeSchema,\n  NodeId,\n  ReusableComponentProp,\n} from '../foundation'\nimport { NODE_ROOT_ID } from '../canvas-manager/canvas-manager'\nimport { composeLayoutChainAndScreenNodes } from './compose-layout-nodes'\nimport { applyDeclaredProps } from './compose-reusable-components'\n\n/**\n * Layout properties (AGL-2893): a shared layout declares properties exactly as\n * a reusable component does, binds its own nodes to them with `{{prop.*}}`,\n * and each screen rendering inside it sets the values.\n *\n * The values are applied to each layout's OWN nodes before the screen is\n * grafted into its slot, so a `{{prop.*}}` the screen's own copy happens to\n * contain is never touched, and a component the layout places receives the\n * values it is handed before it is grafted.\n */\n\ntype NormalizedNodes<N extends AglynNodeSchema> = Record<NodeId, N>\n\n/**\n * Screen-version key holding the screen's values for the layouts it renders\n * inside, beside the `layoutId` binding. Persisted in screen version documents\n * — never rename.\n */\nexport const SCREEN_LAYOUT_PROP_VALUES_KEY = 'layoutPropValues'\n\n/** One layout of a screen's chain, as composition reads it. */\nexport interface LayoutChainEntry<N extends AglynNodeSchema = AglynNodeSchema> {\n  /** The layout document's id, which a screen's values are keyed by. */\n  layoutId?: string | null\n  /** The published version's nodes. */\n  nodes?: NormalizedNodes<N> | null\n  /** The published version's declared properties. */\n  props?: ReusableComponentProp[] | null\n}\n\n/**\n * A screen's values for one layout of its chain, or `undefined` where it set\n * none. Anything that is not a map of values is read as none.\n */\nexport function layoutPropValuesFor(\n  layoutPropValues: unknown,\n  layoutId: string | null | undefined,\n): Record<string, unknown> | undefined {\n  if (!layoutId || !layoutPropValues || typeof layoutPropValues !== 'object') {\n    return undefined\n  }\n  const values = (layoutPropValues as Record<string, unknown>)[layoutId]\n  return values && typeof values === 'object' && !Array.isArray(values)\n    ? (values as Record<string, unknown>)\n    : undefined\n}\n\n/**\n * A layout's nodes with its declared properties applied for one screen: each\n * `{{prop.*}}` takes the screen's value or the property's default, a field\n * bound to one property receives the value its kind holds, and the parts the\n * screen hides (`hideIf` / `hideUnless`) are pruned — the sequence a reusable\n * component's graft runs, over the layout's root.\n *\n * A layout with no root is returned as it is, for the reason\n * `composeLayoutAndScreenNodes` gives: a broken layout degrades to the bare\n * screen rather than taking a page down.\n */\nexport function applyLayoutProps<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: NormalizedNodes<N> | null | undefined,\n  props: ReusableComponentProp[] | null | undefined,\n  values: Readonly<Record<string, unknown>> | null | undefined,\n): NormalizedNodes<N> | undefined {\n  if (!nodes || !nodes[NODE_ROOT_ID]) return nodes ?? undefined\n  return applyDeclaredProps(nodes, props, values, NODE_ROOT_ID)\n}\n\n/**\n * A screen grafted through its whole layout chain, innermost first, with each\n * layout's properties applied from the screen's values for that layout\n * (`layoutPropValues`, keyed by layout id).\n *\n * The one composition the published page, the besigner's Preview and its\n * layout chrome all run, so none of them can disagree about which value a\n * layout renders with.\n */\nexport function composeLayoutChainWithProps<\n  N extends AglynNodeSchema = AglynNodeSchema,\n>(\n  chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>,\n  screenNodes: NormalizedNodes<N>,\n  layoutPropValues?: unknown,\n): NormalizedNodes<N> {\n  return composeLayoutChainAndScreenNodes(\n    chain.map((entry) =>\n      applyLayoutProps(\n        entry?.nodes,\n        entry?.props,\n        layoutPropValuesFor(layoutPropValues, entry?.layoutId),\n      ),\n    ),\n    screenNodes,\n  )\n}\n\nexport default composeLayoutChainWithProps\n"],"names":["NODE_ROOT_ID","composeLayoutChainAndScreenNodes","applyDeclaredProps","SCREEN_LAYOUT_PROP_VALUES_KEY","layoutPropValuesFor","layoutPropValues","layoutId","undefined","values","Array","isArray","applyLayoutProps","nodes","props","composeLayoutChainWithProps","chain","screenNodes","map","entry"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAOD,SAASA,YAAY,QAAQ,sCAAkC;AAC/D,SAASC,gCAAgC,QAAQ,4BAAwB;AACzE,SAASC,kBAAkB,QAAQ,mCAA+B;AAelE;;;;CAIC,GACD,OAAO,MAAMC,gCAAgC,mBAAkB;AAY/D;;;CAGC,GACD,OAAO,SAASC,oBACdC,gBAAyB,EACzBC,QAAmC;IAEnC,IAAI,CAACA,YAAY,CAACD,oBAAoB,OAAOA,qBAAqB,UAAU;QAC1E,OAAOE;IACT;IACA,MAAMC,SAAS,AAACH,gBAA4C,CAACC,SAAS;IACtE,OAAOE,UAAU,OAAOA,WAAW,YAAY,CAACC,MAAMC,OAAO,CAACF,UACzDA,SACDD;AACN;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASI,iBACdC,KAA4C,EAC5CC,KAAiD,EACjDL,MAA4D;IAE5D,IAAI,CAACI,SAAS,CAACA,KAAK,CAACZ,aAAa,EAAE,OAAOY,gBAAAA,QAASL;IACpD,OAAOL,mBAAmBU,OAAOC,OAAOL,QAAQR;AAClD;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASc,4BAGdC,KAA4D,EAC5DC,WAA+B,EAC/BX,gBAA0B;IAE1B,OAAOJ,iCACLc,MAAME,GAAG,CAAC,CAACC,QACTP,iBACEO,yBAAAA,MAAON,KAAK,EACZM,yBAAAA,MAAOL,KAAK,EACZT,oBAAoBC,kBAAkBa,yBAAAA,MAAOZ,QAAQ,KAGzDU;AAEJ;AAEA,eAAeF,4BAA2B"}
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/compose-layout-props.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 {\n  AglynNodeSchema,\n  NodeId,\n  ReusableComponentProp,\n} from '../foundation'\nimport { NODE_ROOT_ID } from '../canvas-manager/canvas-manager'\nimport { composeLayoutChainAndScreenNodes } from './compose-layout-nodes'\nimport { applyDeclaredProps } from './compose-reusable-components'\nimport {\n  applyLayoutStyleOverrides,\n  layoutStyleOverridesFor,\n} from './layout-style-overrides'\n\n/**\n * Layout properties (AGL-2893): a shared layout declares properties exactly as\n * a reusable component does, binds its own nodes to them with `{{prop.*}}`,\n * and each screen rendering inside it sets the values.\n *\n * The values are applied to each layout's OWN nodes before the screen is\n * grafted into its slot, so a `{{prop.*}}` the screen's own copy happens to\n * contain is never touched, and a component the layout places receives the\n * values it is handed before it is grafted.\n */\n\ntype NormalizedNodes<N extends AglynNodeSchema> = Record<NodeId, N>\n\n/**\n * Screen-version key holding the screen's values for the layouts it renders\n * inside, beside the `layoutId` binding. Persisted in screen version documents\n * — never rename.\n */\nexport const SCREEN_LAYOUT_PROP_VALUES_KEY = 'layoutPropValues'\n\n/** One layout of a screen's chain, as composition reads it. */\nexport interface LayoutChainEntry<N extends AglynNodeSchema = AglynNodeSchema> {\n  /** The layout document's id, which a screen's values are keyed by. */\n  layoutId?: string | null\n  /** The published version's nodes. */\n  nodes?: NormalizedNodes<N> | null\n  /** The published version's declared properties. */\n  props?: ReusableComponentProp[] | null\n}\n\n/**\n * A screen's values for one layout of its chain, or `undefined` where it set\n * none. Anything that is not a map of values is read as none.\n */\nexport function layoutPropValuesFor(\n  layoutPropValues: unknown,\n  layoutId: string | null | undefined,\n): Record<string, unknown> | undefined {\n  if (!layoutId || !layoutPropValues || typeof layoutPropValues !== 'object') {\n    return undefined\n  }\n  const values = (layoutPropValues as Record<string, unknown>)[layoutId]\n  return values && typeof values === 'object' && !Array.isArray(values)\n    ? (values as Record<string, unknown>)\n    : undefined\n}\n\n/**\n * A layout's nodes with its declared properties applied for one screen: each\n * `{{prop.*}}` takes the screen's value or the property's default, a field\n * bound to one property receives the value its kind holds, and the parts the\n * screen hides (`hideIf` / `hideUnless`) are pruned — the sequence a reusable\n * component's graft runs, over the layout's root.\n *\n * A layout with no root is returned as it is, for the reason\n * `composeLayoutAndScreenNodes` gives: a broken layout degrades to the bare\n * screen rather than taking a page down.\n */\nexport function applyLayoutProps<N extends AglynNodeSchema = AglynNodeSchema>(\n  nodes: NormalizedNodes<N> | null | undefined,\n  props: ReusableComponentProp[] | null | undefined,\n  values: Readonly<Record<string, unknown>> | null | undefined,\n): NormalizedNodes<N> | undefined {\n  if (!nodes || !nodes[NODE_ROOT_ID]) return nodes ?? undefined\n  return applyDeclaredProps(nodes, props, values, NODE_ROOT_ID)\n}\n\n/**\n * A screen grafted through its whole layout chain, innermost first, with each\n * layout's properties applied from the screen's values for that layout\n * (`layoutPropValues`, keyed by layout id), and then the screen's per-page\n * restyling of that layout's elements (`layoutStyleOverrides`, AGL-3286) —\n * after the properties, so a page's style wins over whatever a property\n * bound, and before the graft, so an element the layout hides for this page\n * is simply not there to be styled.\n *\n * The one composition the published page, the besigner's Preview and its\n * layout chrome all run, so none of them can disagree about which value a\n * layout renders with.\n */\nexport function composeLayoutChainWithProps<\n  N extends AglynNodeSchema = AglynNodeSchema,\n>(\n  chain: ReadonlyArray<LayoutChainEntry<N> | null | undefined>,\n  screenNodes: NormalizedNodes<N>,\n  layoutPropValues?: unknown,\n  layoutStyleOverrides?: unknown,\n): NormalizedNodes<N> {\n  return composeLayoutChainAndScreenNodes(\n    chain.map((entry) =>\n      applyLayoutStyleOverrides(\n        applyLayoutProps(\n          entry?.nodes,\n          entry?.props,\n          layoutPropValuesFor(layoutPropValues, entry?.layoutId),\n        ),\n        layoutStyleOverridesFor(layoutStyleOverrides, entry?.layoutId),\n      ),\n    ),\n    screenNodes,\n  )\n}\n\nexport default composeLayoutChainWithProps\n"],"names":["NODE_ROOT_ID","composeLayoutChainAndScreenNodes","applyDeclaredProps","applyLayoutStyleOverrides","layoutStyleOverridesFor","SCREEN_LAYOUT_PROP_VALUES_KEY","layoutPropValuesFor","layoutPropValues","layoutId","undefined","values","Array","isArray","applyLayoutProps","nodes","props","composeLayoutChainWithProps","chain","screenNodes","layoutStyleOverrides","map","entry"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAOD,SAASA,YAAY,QAAQ,sCAAkC;AAC/D,SAASC,gCAAgC,QAAQ,4BAAwB;AACzE,SAASC,kBAAkB,QAAQ,mCAA+B;AAClE,SACEC,yBAAyB,EACzBC,uBAAuB,QAClB,8BAA0B;AAejC;;;;CAIC,GACD,OAAO,MAAMC,gCAAgC,mBAAkB;AAY/D;;;CAGC,GACD,OAAO,SAASC,oBACdC,gBAAyB,EACzBC,QAAmC;IAEnC,IAAI,CAACA,YAAY,CAACD,oBAAoB,OAAOA,qBAAqB,UAAU;QAC1E,OAAOE;IACT;IACA,MAAMC,SAAS,AAACH,gBAA4C,CAACC,SAAS;IACtE,OAAOE,UAAU,OAAOA,WAAW,YAAY,CAACC,MAAMC,OAAO,CAACF,UACzDA,SACDD;AACN;AAEA;;;;;;;;;;CAUC,GACD,OAAO,SAASI,iBACdC,KAA4C,EAC5CC,KAAiD,EACjDL,MAA4D;IAE5D,IAAI,CAACI,SAAS,CAACA,KAAK,CAACd,aAAa,EAAE,OAAOc,gBAAAA,QAASL;IACpD,OAAOP,mBAAmBY,OAAOC,OAAOL,QAAQV;AAClD;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASgB,4BAGdC,KAA4D,EAC5DC,WAA+B,EAC/BX,gBAA0B,EAC1BY,oBAA8B;IAE9B,OAAOlB,iCACLgB,MAAMG,GAAG,CAAC,CAACC,QACTlB,0BACEU,iBACEQ,yBAAAA,MAAOP,KAAK,EACZO,yBAAAA,MAAON,KAAK,EACZT,oBAAoBC,kBAAkBc,yBAAAA,MAAOb,QAAQ,IAEvDJ,wBAAwBe,sBAAsBE,yBAAAA,MAAOb,QAAQ,KAGjEU;AAEJ;AAEA,eAAeF,4BAA2B"}

package/src/lib/app-utils/compose-reusable-components.d.ts

@@ -17,11 +17,53 @@
 import type { AglynNodeSchema, NodeId, ReusableComponentIcon, ReusableComponentProp } from '../foundation';
 export * from './reusable-component-keys';
 export * from './reusable-prop-values';
+/**
+ * Whether a node is a placed form that names a form entity — the second kind
+ * of node that stands for a tree stored on another document (see
+ * {@link PlacementKind}). A `form` node with no `formId` is an ordinary form
+ * whose fields are its own children, and has no override layer.
+ *
+ * The ref test matches the graft's own resolution rule (a non-empty string),
+ * so the editor and the renderer agree about which forms are placements.
+ */
+export declare function isPlacedFormNode(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null): boolean;
+/**
+ * Whether a node is a placement that GRAFTS a definition — a reusable
+ * component instance or a placed form — and therefore carries the two
+ * per-placement override layers (`styleOverrides`, `attrOverrides`, AGL-3285).
+ *
+ * One predicate for both kinds on purpose: the graft already expands them in
+ * one pass, and an override layer that one kind honoured and the other
+ * silently ignored would be the canvas/Preview/tenant disagreement this file
+ * exists to prevent.
+ */
+export declare function isDefinitionPlacement(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null): boolean;
+/**
+ * The tree a placement grafts, from whichever map its kind reads — the
+ * component definitions for an instance, the published form designs for a
+ * placed form — or `undefined` when it is not a placement or its ref resolves
+ * to nothing (AGL-3285). The editor panels use it to offer the same targets
+ * the graft will consult.
+ */
+export declare function placementDefinitionFor<N extends AglynNodeSchema = AglynNodeSchema>(node: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null, sources: {
+    definitions?: Record<string, ReusableComponentTree<N> | undefined>;
+    formDesigns?: Record<string, Pick<ReusableComponentTree<N>, 'rootId' | 'nodes'> | undefined>;
+}): Pick<ReusableComponentTree<N>, 'rootId' | 'nodes'> | undefined;
 /**
  * Every per-instance style override an instance node carries, keyed the way
  * it is stored (AGL-1332): {@link STYLE_OVERRIDES_ROOT_KEY} for the
  * component root, and a DEFINITION-internal node id for each overridden
- * leaf. Empty for a node that is not an instance or carries none.
+ * leaf. Empty for a node that is not a placement ({@link
+ * isDefinitionPlacement}: an instance or a placed form) or carries none.
  *
  * Keyed on the definition's own id, never the grafted `cmp__…` id: the
  * graft id is DERIVED from the instance id, so keying on it would break the
@@ -39,6 +81,7 @@ export * from './reusable-prop-values';
  */
 export declare function getInstanceStyleOverrides(node: {
     componentId?: string;
+    props?: unknown;
     styleOverrides?: unknown;
 } | undefined | null): Record<string, Record<string, unknown>>;
 /**
@@ -48,8 +91,48 @@ export declare function getInstanceStyleOverrides(node: {
  */
 export declare function getInstanceRootStyleOverride(node: {
     componentId?: string;
+    props?: unknown;
     styleOverrides?: unknown;
 } | undefined | null): Record<string, unknown> | undefined;
+/**
+ * Props a placed form's attribute overrides must never address, on any node
+ * of its design (AGL-3285).
+ *
+ * A form is edited once and every page placing it follows — that is the
+ * whole point of the form entity. Its submission list, its dataset columns,
+ * its consent tick and its routing are all keyed to what the ENTITY declares,
+ * so a page that renamed a field, retyped it, made it optional, rewrote its
+ * choices or re-pointed where the form sends would file answers the form's
+ * own schema does not describe, from one page only, with nothing on the
+ * Forms page saying so. Per page, a form may LOOK different; it may not
+ * collect something different.
+ *
+ * - The form node's identity and submission config: `formId`, `formName`,
+ *   `datasetId`, `datasetName`, and the after-submit outcome
+ *   (`afterSubmit`, `redirectScreenId`, `redirectUrl`, `revealNodeId`).
+ * - Each field's contract: `fieldName` (the submission key),
+ *   `datasetFieldId`, `fieldType`, `options` (a ticked option's TEXT is the
+ *   posted value, and the consent check reads it) and `required`.
+ * - Element attributes a browser submission reads directly: `name`, `type`
+ *   (a submit button made a plain button no longer submits), `value`,
+ *   `action`, `method`, and `disabled` (a disabled input is not posted).
+ * - The hide directives: a hidden field is pruned from the page, so its
+ *   value is never sent.
+ *
+ * Label, placeholder, help text, the submit label and success message, and
+ * everything about styling stay overridable.
+ */
+export declare const PLACED_FORM_REFUSED_ATTR_PROPS: ReadonlySet<string>;
+/**
+ * Whether `prop` may never be an attribute override on this placement — `sx`
+ * on every placement, plus {@link PLACED_FORM_REFUSED_ATTR_PROPS} on a placed
+ * form. The render layer and the editor's writer both ask this, so a refused
+ * prop can neither be offered nor take effect.
+ */
+export declare function isAttrOverrideRefused(placement: {
+    componentId?: string;
+    props?: unknown;
+} | undefined | null, prop: string): boolean;
 /**
  * Every per-instance ATTRIBUTE override an instance node carries, keyed the
  * way {@link getInstanceStyleOverrides} keys styles — `root` for the
@@ -62,6 +145,7 @@ export declare function getInstanceRootStyleOverride(node: {
  */
 export declare function getInstanceAttrOverrides(node: {
     componentId?: string;
+    props?: unknown;
     attrOverrides?: unknown;
 } | undefined | null): Record<string, Record<string, unknown>>;
 /** One styleable target inside an instance — see {@link listInstanceStyleTargets}. */

package/src/lib/app-utils/compose-reusable-components.js

@@ -20,6 +20,7 @@ import { iconPathPropName } from "@aglyn/shared-data-mdi/utils/icon-path-prop-na
 import { reusablePropValueClass } from "../foundation/definitions/property-kinds.js";
 import { COMPONENT_NODE_ID_PREFIX, COMPONENT_PROP_TOKEN_PREFIX, INSTANCE_CARRIED_NODE_FIELDS, INSTANCE_CARRIED_PROPS, NODE_HIDE_IF_PROP, NODE_HIDE_UNLESS_PROP, REUSABLE_INSTANCE_COMPONENT_ID, REUSABLE_INSTANCE_PROP_VALUES_KEY, STYLE_OVERRIDES_ROOT_KEY } from "./reusable-component-keys.js";
 import { REPEAT_DIRECTIVE_PROPS, REPEAT_SELF_PROP, repeatKey, withoutRepeatDirective } from "./expand-repeatables.js";
+import { FORM_COMPONENT_ID, FORM_ID_PROP } from "./forms.js";
 import { mergeNodeSx } from "./merge-node-sx.js";
 import { hasUrlScheme, isSafeNodeUrl, NODE_URL_PROPS } from "./node-url-policy.js";
 import { readInstanceIconValue, readYesNoValue, resolveReusablePropValues } from "./reusable-prop-values.js";
@@ -36,11 +37,60 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
         ...new Set(names)
     ].join(' ') : undefined;
 }
+/**
+ * Whether a node is a placed form that names a form entity — the second kind
+ * of node that stands for a tree stored on another document (see
+ * {@link PlacementKind}). A `form` node with no `formId` is an ordinary form
+ * whose fields are its own children, and has no override layer.
+ *
+ * The ref test matches the graft's own resolution rule (a non-empty string),
+ * so the editor and the renderer agree about which forms are placements.
+ */ export function isPlacedFormNode(node) {
+    var _node_props;
+    if ((node == null ? void 0 : node.componentId) !== FORM_COMPONENT_ID) return false;
+    const formId = (_node_props = node.props) == null ? void 0 : _node_props[FORM_ID_PROP];
+    return typeof formId === 'string' && formId !== '';
+}
+/**
+ * Whether a node is a placement that GRAFTS a definition — a reusable
+ * component instance or a placed form — and therefore carries the two
+ * per-placement override layers (`styleOverrides`, `attrOverrides`, AGL-3285).
+ *
+ * One predicate for both kinds on purpose: the graft already expands them in
+ * one pass, and an override layer that one kind honoured and the other
+ * silently ignored would be the canvas/Preview/tenant disagreement this file
+ * exists to prevent.
+ */ export function isDefinitionPlacement(node) {
+    return (node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID || isPlacedFormNode(node);
+}
+/**
+ * The tree a placement grafts, from whichever map its kind reads — the
+ * component definitions for an instance, the published form designs for a
+ * placed form — or `undefined` when it is not a placement or its ref resolves
+ * to nothing (AGL-3285). The editor panels use it to offer the same targets
+ * the graft will consult.
+ */ export function placementDefinitionFor(node, sources) {
+    const props = node == null ? void 0 : node.props;
+    if ((node == null ? void 0 : node.componentId) === REUSABLE_INSTANCE_COMPONENT_ID) {
+        var _sources_definitions;
+        const refId = props == null ? void 0 : props['refId'];
+        return typeof refId === 'string' && refId ? (_sources_definitions = sources.definitions) == null ? void 0 : _sources_definitions[refId] : undefined;
+    }
+    if (isPlacedFormNode(node)) {
+        var _sources_formDesigns, _design_nodes;
+        const design = (_sources_formDesigns = sources.formDesigns) == null ? void 0 : _sources_formDesigns[props == null ? void 0 : props[FORM_ID_PROP]];
+        // The graft's resolution rule: a design whose root is not among its own
+        // nodes grafts nothing, so it offers nothing to override either.
+        return (design == null ? void 0 : design.rootId) && ((_design_nodes = design.nodes) == null ? void 0 : _design_nodes[design.rootId]) ? design : undefined;
+    }
+    return undefined;
+}
 /**
  * Every per-instance style override an instance node carries, keyed the way
  * it is stored (AGL-1332): {@link STYLE_OVERRIDES_ROOT_KEY} for the
  * component root, and a DEFINITION-internal node id for each overridden
- * leaf. Empty for a node that is not an instance or carries none.
+ * leaf. Empty for a node that is not a placement ({@link
+ * isDefinitionPlacement}: an instance or a placed form) or carries none.
  *
  * Keyed on the definition's own id, never the grafted `cmp__…` id: the
  * graft id is DERIVED from the instance id, so keying on it would break the
@@ -56,7 +106,7 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
  * {@link composeReusableComponentNodes}, so they cannot disagree about
  * what an override means.
  */ export function getInstanceStyleOverrides(node) {
-    if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) return {};
+    if (!isDefinitionPlacement(node)) return {};
     const overrides = node == null ? void 0 : node.styleOverrides;
     if (!isStyleRecord(overrides)) return {};
     const clean = {};
@@ -117,6 +167,65 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
  */ const ATTR_OVERRIDE_REFUSED_PROPS = new Set([
     'sx'
 ]);
+/**
+ * Props a placed form's attribute overrides must never address, on any node
+ * of its design (AGL-3285).
+ *
+ * A form is edited once and every page placing it follows — that is the
+ * whole point of the form entity. Its submission list, its dataset columns,
+ * its consent tick and its routing are all keyed to what the ENTITY declares,
+ * so a page that renamed a field, retyped it, made it optional, rewrote its
+ * choices or re-pointed where the form sends would file answers the form's
+ * own schema does not describe, from one page only, with nothing on the
+ * Forms page saying so. Per page, a form may LOOK different; it may not
+ * collect something different.
+ *
+ * - The form node's identity and submission config: `formId`, `formName`,
+ *   `datasetId`, `datasetName`, and the after-submit outcome
+ *   (`afterSubmit`, `redirectScreenId`, `redirectUrl`, `revealNodeId`).
+ * - Each field's contract: `fieldName` (the submission key),
+ *   `datasetFieldId`, `fieldType`, `options` (a ticked option's TEXT is the
+ *   posted value, and the consent check reads it) and `required`.
+ * - Element attributes a browser submission reads directly: `name`, `type`
+ *   (a submit button made a plain button no longer submits), `value`,
+ *   `action`, `method`, and `disabled` (a disabled input is not posted).
+ * - The hide directives: a hidden field is pruned from the page, so its
+ *   value is never sent.
+ *
+ * Label, placeholder, help text, the submit label and success message, and
+ * everything about styling stay overridable.
+ */ export const PLACED_FORM_REFUSED_ATTR_PROPS = new Set([
+    FORM_ID_PROP,
+    'formName',
+    'datasetId',
+    'datasetName',
+    'afterSubmit',
+    'redirectScreenId',
+    'redirectUrl',
+    'revealNodeId',
+    'fieldName',
+    'datasetFieldId',
+    'fieldType',
+    'options',
+    'required',
+    'name',
+    'type',
+    'value',
+    'action',
+    'method',
+    'disabled',
+    NODE_HIDE_IF_PROP,
+    NODE_HIDE_UNLESS_PROP
+]);
+/**
+ * Whether `prop` may never be an attribute override on this placement — `sx`
+ * on every placement, plus {@link PLACED_FORM_REFUSED_ATTR_PROPS} on a placed
+ * form. The render layer and the editor's writer both ask this, so a refused
+ * prop can neither be offered nor take effect.
+ */ export function isAttrOverrideRefused(placement, prop) {
+    if (ATTR_OVERRIDE_REFUSED_PROPS.has(prop)) return true;
+    return isPlacedFormNode(placement) && PLACED_FORM_REFUSED_ATTR_PROPS.has(prop);
+}
 /**
  * Every per-instance ATTRIBUTE override an instance node carries, keyed the
  * way {@link getInstanceStyleOverrides} keys styles — `root` for the
@@ -127,7 +236,7 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
  * that reached storage before a refusal existed (or by any path that did not
  * go through the panel) still cannot take effect.
  */ export function getInstanceAttrOverrides(node) {
-    if ((node == null ? void 0 : node.componentId) !== REUSABLE_INSTANCE_COMPONENT_ID) return {};
+    if (!isDefinitionPlacement(node)) return {};
     const overrides = node == null ? void 0 : node.attrOverrides;
     if (!isStyleRecord(overrides)) return {};
     const clean = {};
@@ -135,7 +244,7 @@ const isStyleRecord = (value)=>typeof value === 'object' && value !== null && !A
         if (!key || !isStyleRecord(value)) continue;
         const slice = {};
         for (const [prop, propValue] of Object.entries(value)){
-            if (ATTR_OVERRIDE_REFUSED_PROPS.has(prop)) continue;
+            if (isAttrOverrideRefused(node, prop)) continue;
             slice[prop] = propValue;
         }
         if (Object.keys(slice).length > 0) clean[key] = slice;
@@ -850,6 +959,9 @@ function hasVisibilityDirective(props) {
             // Per-leaf is not a nicety: a component's text leaves usually set
             // their OWN colour, so a root-level `color` never reaches them and an
             // instance given a white background renders white-on-white (AGL-1318).
+            //
+            // A placed form carries the same two layers (AGL-3285), so one page can
+            // restyle a field's label without editing the form for every page.
             const styleOverrides = getInstanceStyleOverrides(instanceNode);
             // Attribute overrides (AGL-1899) ride the same graft for the same
             // reason: this is the one point where per-instance scope exists, so
@@ -909,6 +1021,7 @@ function hasVisibilityDirective(props) {
             const rootNamesItself = Boolean(grafting) && refIdOf(definitionRoot) === grafting;
             const graftedRoot = next[graftedRootId];
             if (rootNamesItself && graftedRoot) {
+                var _instanceNode_props;
                 const adopted = Array.isArray(graftedRoot.nodes) ? graftedRoot.nodes : [];
                 for (const childId of adopted){
                     if (next[childId]) {
@@ -918,11 +1031,24 @@ function hasVisibilityDirective(props) {
                     }
                 }
                 delete next[graftedRootId];
-                next[instanceId] = _extends({}, instanceNode, {
+                /*
+         * The root's own override slices land on the instance, because the
+         * instance IS the root here (AGL-3285). The grafted root carried them
+         * and has just been dropped; without this a placed form's `root`
+         * target would save and never render. Same precedence as the merge
+         * branch below: the slice first, the placement's own `sx` over it.
+         */ const rootSx = styleOverrides[STYLE_OVERRIDES_ROOT_KEY];
+                const rootAttrs = attrOverrides[STYLE_OVERRIDES_ROOT_KEY];
+                const unwrappedSx = rootSx ? mergeNodeSx(rootSx, instanceNode.sx) : undefined;
+                next[instanceId] = _extends({}, instanceNode, unwrappedSx === undefined ? {} : {
+                    sx: unwrappedSx
+                }, rootAttrs ? {
+                    props: _extends({}, (_instanceNode_props = instanceNode.props) != null ? _instanceNode_props : {}, rootAttrs)
+                } : {}, {
                     nodes: adopted
                 });
             } else if (graftedRoot) {
-                var _graftedRoot_props, _instanceNode_props;
+                var _graftedRoot_props, _instanceNode_props1;
                 /*
          * THE INSTANCE AND THE DEFINITION'S ROOT ARE ONE ELEMENT (AGL-2521).
          *
@@ -979,8 +1105,8 @@ function hasVisibilityDirective(props) {
                 ];
                 const carried = {};
                 for (const key of INSTANCE_CARRIED_PROPS){
-                    var _instanceNode_props1;
-                    const value = (_instanceNode_props1 = instanceNode.props) == null ? void 0 : _instanceNode_props1[key];
+                    var _instanceNode_props2;
+                    const value = (_instanceNode_props2 = instanceNode.props) == null ? void 0 : _instanceNode_props2[key];
                     if (value !== undefined) carried[key] = value;
                 }
                 /*
@@ -998,8 +1124,8 @@ function hasVisibilityDirective(props) {
          */ const repeatsPlacement = repeatKey(instanceNode) !== '';
                 if (repeatsPlacement) {
                     for (const key of REPEAT_DIRECTIVE_PROPS){
-                        var _instanceNode_props2;
-                        const value = (_instanceNode_props2 = instanceNode.props) == null ? void 0 : _instanceNode_props2[key];
+                        var _instanceNode_props3;
+                        const value = (_instanceNode_props3 = instanceNode.props) == null ? void 0 : _instanceNode_props3[key];
                         if (value !== undefined) carried[key] = value;
                     }
                     carried[REPEAT_SELF_PROP] = true;
@@ -1014,7 +1140,7 @@ function hasVisibilityDirective(props) {
          * element answering to the placement's id, which after the merge is
          * this one. Keeping either list alone drops the other author's names,
          * so the two are joined, each name once, in `props` and on the node.
-         */ const propsClassName = joinClassNames((_graftedRoot_props = graftedRoot.props) == null ? void 0 : _graftedRoot_props['className'], (_instanceNode_props = instanceNode.props) == null ? void 0 : _instanceNode_props['className']);
+         */ const propsClassName = joinClassNames((_graftedRoot_props = graftedRoot.props) == null ? void 0 : _graftedRoot_props['className'], (_instanceNode_props1 = instanceNode.props) == null ? void 0 : _instanceNode_props1['className']);
                 if (propsClassName) carried['className'] = propsClassName;
                 const nodeClassName = joinClassNames(graftedRoot.className, instanceNode.className);
                 // The override slices and the reference are DOCUMENT state living on