@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/collection-delete.js

@@ -0,0 +1,120 @@
+/**
+ * @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.
+ */ /**
+ * Whether a collection may be deleted, and what to say when it may not
+ * (AGL-1324).
+ *
+ * A collection could be created and never deleted: "New collection" existed,
+ * no delete affordance did anywhere, so a mis-created collection was
+ * permanent — a one-way door in an ordinary authoring flow for a no-code
+ * product.
+ *
+ * The delete itself is the easy half; `/api/resources/erase` already
+ * recursiveDeletes a collection subtree for the commerce catalog card. This
+ * file is the hard half: deciding when it must NOT happen. It is pure and
+ * lives beside `collection-kind` / `collection-slug` for the same reason
+ * `eraseScopeDenial` lives beside its route — a destructive decision that
+ * cannot be unit-tested is the shape of control this project exists to
+ * avoid — and because BOTH sides need it: the console dialog to show the
+ * blockers before the button is armed, and the route to enforce them.
+ *
+ * ## Why blocking, not cascading
+ *
+ * Both blockers refuse. The alternative — delete the collection and take its
+ * entries and its published routes with it — makes destroying a live page a
+ * side effect of tidying up a list, and no consent given to the second act
+ * was given to the first. This repo already settled that argument for
+ * account erasure (`userErasureBlockers`): blocking is recoverable, a
+ * cascade is not. Emptying a collection is two clicks; un-deleting a
+ * published page is a restore from an export.
+ */ /** What a template binding drives — which public route it publishes. */ const asId = (value)=>typeof value === 'string' ? value.trim() : '';
+/**
+ * The LIVE template bindings on a collection — the screens that would be
+ * left publishing an empty route if it were deleted.
+ *
+ * `screens` is required rather than defaulted because the sole reason a
+ * binding is dropped here is that its screen is gone, and an empty map means
+ * "every screen is gone". Defaulting it would make the safe-looking call the
+ * one that silently answers "nothing depends on this". Callers pass the
+ * screens they read: the route fetches exactly the bound ids, the console
+ * already holds the host's screen list.
+ *
+ * Mirrors `resolveCollectionTemplateScreenId` in tenant-runtime: the list
+ * route uses `listScreenId` only, the entry route uses `entryScreenId` with
+ * `templateScreenId` as the legacy fallback. Deduped by screen id, because
+ * one screen serving both routes is one thing to detach, not two.
+ */ export function collectionTemplateBindings(data, screens) {
+    const listScreenId = asId(data == null ? void 0 : data.listScreenId);
+    // `||`, not `??`: the console writes `deleteField()` to clear, but an
+    // empty string has meant "cleared" in older documents too.
+    const entryScreenId = asId(data == null ? void 0 : data.entryScreenId) || asId(data == null ? void 0 : data.templateScreenId);
+    const bindings = [];
+    const seen = new Set();
+    for (const [role, screenId] of [
+        [
+            'list',
+            listScreenId
+        ],
+        [
+            'entry',
+            entryScreenId
+        ]
+    ]){
+        if (!screenId || seen.has(screenId)) continue;
+        const screen = screens[screenId];
+        if (!screen || screen.deletedAt) continue;
+        seen.add(screenId);
+        bindings.push({
+            role,
+            screenId,
+            screenName: asId(screen.displayName) || screenId
+        });
+    }
+    return bindings;
+}
+const describeBinding = (binding)=>`"${binding.screenName}" (${binding.role} template)`;
+/**
+ * Null when the collection may be deleted; otherwise the response to return.
+ *
+ * Both blockers are reported at once. Fixing one and being told about the
+ * other is two trips through a destructive dialog to learn a fact that was
+ * knowable on the first — and the second refusal, arriving after the user
+ * has already detached a template, reads as the product changing its mind.
+ */ export function collectionDeleteDenial(input) {
+    const { displayName, entryCount, bindings } = input;
+    const name = displayName || 'This collection';
+    const blockers = [];
+    const sentences = [];
+    // Severity order: a bound template is a published page that stops
+    // rendering; entries are data that merely becomes unreachable.
+    if (bindings.length) {
+        blockers.push('template-bound');
+        sentences.push(`"${name}" is still the source for ${bindings.map(describeBinding).join(' and ')}. Clear ${bindings.length > 1 ? 'those templates' : 'that template'} on the collection first — deleting it now would leave a published ` + 'page with nothing to render.');
+    }
+    if (entryCount > 0) {
+        blockers.push('has-entries');
+        sentences.push(`"${name}" still has ${entryCount} ${entryCount === 1 ? 'entry' : 'entries'}. Delete ${entryCount === 1 ? 'it' : 'them'} first — deleting a collection never removes published entries for ` + 'you.');
+    }
+    if (!blockers.length) return null;
+    return {
+        error: sentences.join(' '),
+        status: 409,
+        blockers
+    };
+}
+export default collectionDeleteDenial;
+
+//# sourceMappingURL=collection-delete.js.map

package/src/lib/app-utils/collection-delete.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/collection-delete.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 * Whether a collection may be deleted, and what to say when it may not\n * (AGL-1324).\n *\n * A collection could be created and never deleted: \"New collection\" existed,\n * no delete affordance did anywhere, so a mis-created collection was\n * permanent — a one-way door in an ordinary authoring flow for a no-code\n * product.\n *\n * The delete itself is the easy half; `/api/resources/erase` already\n * recursiveDeletes a collection subtree for the commerce catalog card. This\n * file is the hard half: deciding when it must NOT happen. It is pure and\n * lives beside `collection-kind` / `collection-slug` for the same reason\n * `eraseScopeDenial` lives beside its route — a destructive decision that\n * cannot be unit-tested is the shape of control this project exists to\n * avoid — and because BOTH sides need it: the console dialog to show the\n * blockers before the button is armed, and the route to enforce them.\n *\n * ## Why blocking, not cascading\n *\n * Both blockers refuse. The alternative — delete the collection and take its\n * entries and its published routes with it — makes destroying a live page a\n * side effect of tidying up a list, and no consent given to the second act\n * was given to the first. This repo already settled that argument for\n * account erasure (`userErasureBlockers`): blocking is recoverable, a\n * cascade is not. Emptying a collection is two clicks; un-deleting a\n * published page is a restore from an export.\n */\n\n/** What a template binding drives — which public route it publishes. */\nexport type CollectionTemplateRole = 'list' | 'entry'\n\n/** A screen as far as this decision cares: does it exist, and what's it called. */\nexport interface CollectionTemplateScreen {\n  displayName?: string\n  /**\n   * Soft-deleted screens render nothing, so a binding to one is stale and\n   * must not block — otherwise deleting a screen makes its collection\n   * permanently undeletable, which is the bug this file exists to fix,\n   * one level up.\n   */\n  deletedAt?: unknown\n}\n\nexport interface CollectionTemplateBinding {\n  role: CollectionTemplateRole\n  screenId: string\n  /** The screen's name; falls back to the id when it has none. */\n  screenName: string\n}\n\n/** The collection fields that point at a template screen. */\nexport interface CollectionTemplateSource {\n  listScreenId?: unknown\n  entryScreenId?: unknown\n  /** Superseded AGL-105 pointer; still honoured as the entry fallback. */\n  templateScreenId?: unknown\n}\n\nconst asId = (value: unknown): string =>\n  typeof value === 'string' ? value.trim() : ''\n\n/**\n * The LIVE template bindings on a collection — the screens that would be\n * left publishing an empty route if it were deleted.\n *\n * `screens` is required rather than defaulted because the sole reason a\n * binding is dropped here is that its screen is gone, and an empty map means\n * \"every screen is gone\". Defaulting it would make the safe-looking call the\n * one that silently answers \"nothing depends on this\". Callers pass the\n * screens they read: the route fetches exactly the bound ids, the console\n * already holds the host's screen list.\n *\n * Mirrors `resolveCollectionTemplateScreenId` in tenant-runtime: the list\n * route uses `listScreenId` only, the entry route uses `entryScreenId` with\n * `templateScreenId` as the legacy fallback. Deduped by screen id, because\n * one screen serving both routes is one thing to detach, not two.\n */\nexport function collectionTemplateBindings(\n  data: CollectionTemplateSource | undefined | null,\n  screens: Readonly<Record<string, CollectionTemplateScreen | undefined>>,\n): CollectionTemplateBinding[] {\n  const listScreenId = asId(data?.listScreenId)\n  // `||`, not `??`: the console writes `deleteField()` to clear, but an\n  // empty string has meant \"cleared\" in older documents too.\n  const entryScreenId = asId(data?.entryScreenId) || asId(data?.templateScreenId)\n\n  const bindings: CollectionTemplateBinding[] = []\n  const seen = new Set<string>()\n  for (const [role, screenId] of [\n    ['list', listScreenId],\n    ['entry', entryScreenId],\n  ] as const) {\n    if (!screenId || seen.has(screenId)) continue\n    const screen = screens[screenId]\n    if (!screen || screen.deletedAt) continue\n    seen.add(screenId)\n    bindings.push({\n      role,\n      screenId,\n      screenName: asId(screen.displayName) || screenId,\n    })\n  }\n  return bindings\n}\n\n/** Why a delete was refused, for callers that need more than the sentence. */\nexport type CollectionDeleteBlocker = 'template-bound' | 'has-entries'\n\nexport interface CollectionDeleteInput {\n  /** The collection's name, so the message names what it is refusing. */\n  displayName: string\n  /** How many entries still live under it. */\n  entryCount: number\n  /** Live template bindings — see {@link collectionTemplateBindings}. */\n  bindings: readonly CollectionTemplateBinding[]\n}\n\nexport interface CollectionDeleteDenial {\n  error: string\n  /** 409: the request is well-formed, the resource's state refuses it. */\n  status: 409\n  blockers: CollectionDeleteBlocker[]\n}\n\nconst describeBinding = (binding: CollectionTemplateBinding) =>\n  `\"${binding.screenName}\" (${binding.role} template)`\n\n/**\n * Null when the collection may be deleted; otherwise the response to return.\n *\n * Both blockers are reported at once. Fixing one and being told about the\n * other is two trips through a destructive dialog to learn a fact that was\n * knowable on the first — and the second refusal, arriving after the user\n * has already detached a template, reads as the product changing its mind.\n */\nexport function collectionDeleteDenial(\n  input: CollectionDeleteInput,\n): CollectionDeleteDenial | null {\n  const { displayName, entryCount, bindings } = input\n  const name = displayName || 'This collection'\n  const blockers: CollectionDeleteBlocker[] = []\n  const sentences: string[] = []\n\n  // Severity order: a bound template is a published page that stops\n  // rendering; entries are data that merely becomes unreachable.\n  if (bindings.length) {\n    blockers.push('template-bound')\n    sentences.push(\n      `\"${name}\" is still the source for ${bindings\n        .map(describeBinding)\n        .join(' and ')}. Clear ${\n        bindings.length > 1 ? 'those templates' : 'that template'\n      } on the collection first — deleting it now would leave a published ` +\n        'page with nothing to render.',\n    )\n  }\n\n  if (entryCount > 0) {\n    blockers.push('has-entries')\n    sentences.push(\n      `\"${name}\" still has ${entryCount} ${\n        entryCount === 1 ? 'entry' : 'entries'\n      }. Delete ${\n        entryCount === 1 ? 'it' : 'them'\n      } first — deleting a collection never removes published entries for ` +\n        'you.',\n    )\n  }\n\n  if (!blockers.length) return null\n  return { error: sentences.join(' '), status: 409, blockers }\n}\n\nexport default collectionDeleteDenial\n"],"names":["asId","value","trim","collectionTemplateBindings","data","screens","listScreenId","entryScreenId","templateScreenId","bindings","seen","Set","role","screenId","has","screen","deletedAt","add","push","screenName","displayName","describeBinding","binding","collectionDeleteDenial","input","entryCount","name","blockers","sentences","length","map","join","error","status"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BC,GAED,sEAAsE,GA8BtE,MAAMA,OAAO,CAACC,QACZ,OAAOA,UAAU,WAAWA,MAAMC,IAAI,KAAK;AAE7C;;;;;;;;;;;;;;;CAeC,GACD,OAAO,SAASC,2BACdC,IAAiD,EACjDC,OAAuE;IAEvE,MAAMC,eAAeN,KAAKI,wBAAAA,KAAME,YAAY;IAC5C,sEAAsE;IACtE,2DAA2D;IAC3D,MAAMC,gBAAgBP,KAAKI,wBAAAA,KAAMG,aAAa,KAAKP,KAAKI,wBAAAA,KAAMI,gBAAgB;IAE9E,MAAMC,WAAwC,EAAE;IAChD,MAAMC,OAAO,IAAIC;IACjB,KAAK,MAAM,CAACC,MAAMC,SAAS,IAAI;QAC7B;YAAC;YAAQP;SAAa;QACtB;YAAC;YAASC;SAAc;KACzB,CAAW;QACV,IAAI,CAACM,YAAYH,KAAKI,GAAG,CAACD,WAAW;QACrC,MAAME,SAASV,OAAO,CAACQ,SAAS;QAChC,IAAI,CAACE,UAAUA,OAAOC,SAAS,EAAE;QACjCN,KAAKO,GAAG,CAACJ;QACTJ,SAASS,IAAI,CAAC;YACZN;YACAC;YACAM,YAAYnB,KAAKe,OAAOK,WAAW,KAAKP;QAC1C;IACF;IACA,OAAOJ;AACT;AAqBA,MAAMY,kBAAkB,CAACC,UACvB,CAAC,CAAC,EAAEA,QAAQH,UAAU,CAAC,GAAG,EAAEG,QAAQV,IAAI,CAAC,UAAU,CAAC;AAEtD;;;;;;;CAOC,GACD,OAAO,SAASW,uBACdC,KAA4B;IAE5B,MAAM,EAAEJ,WAAW,EAAEK,UAAU,EAAEhB,QAAQ,EAAE,GAAGe;IAC9C,MAAME,OAAON,eAAe;IAC5B,MAAMO,WAAsC,EAAE;IAC9C,MAAMC,YAAsB,EAAE;IAE9B,kEAAkE;IAClE,+DAA+D;IAC/D,IAAInB,SAASoB,MAAM,EAAE;QACnBF,SAAST,IAAI,CAAC;QACdU,UAAUV,IAAI,CACZ,CAAC,CAAC,EAAEQ,KAAK,0BAA0B,EAAEjB,SAClCqB,GAAG,CAACT,iBACJU,IAAI,CAAC,SAAS,QAAQ,EACvBtB,SAASoB,MAAM,GAAG,IAAI,oBAAoB,gBAC3C,mEAAmE,CAAC,GACnE;IAEN;IAEA,IAAIJ,aAAa,GAAG;QAClBE,SAAST,IAAI,CAAC;QACdU,UAAUV,IAAI,CACZ,CAAC,CAAC,EAAEQ,KAAK,YAAY,EAAED,WAAW,CAAC,EACjCA,eAAe,IAAI,UAAU,UAC9B,SAAS,EACRA,eAAe,IAAI,OAAO,OAC3B,mEAAmE,CAAC,GACnE;IAEN;IAEA,IAAI,CAACE,SAASE,MAAM,EAAE,OAAO;IAC7B,OAAO;QAAEG,OAAOJ,UAAUG,IAAI,CAAC;QAAME,QAAQ;QAAKN;IAAS;AAC7D;AAEA,eAAeJ,uBAAsB"}