@aglyn/aglyn 1.0.0-beta.252 → 1.0.0-beta.254

package/src/lib/app-utils/template-slug.js

@@ -0,0 +1,150 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 { normalizeScreenSlug, reservedScreenRouteMessage, reservedScreenRouteSegment, SCREEN_ROOT_PATH, SCREEN_SLUG_PATH_SEPARATOR_MESSAGE, screenSlugHasPathSeparator } from "./screen-slug.js";
+/*
+ * Where a page made from a template lands, in a leaf of its own (it was
+ * `create-page-from-template.ts`, which reaches Firestore) so the native apps
+ * replay the same answers. The console file re-exports all three names.
+ */ /**
+ * Why one template screen cannot be given the address it asks for, or
+ * `undefined` when it can (AGL-2588).
+ *
+ * The bundle appliers pass `slug` straight off a template document into
+ * {@link createPageFromTemplate}, so no field ever asks the two questions
+ * every typed slug field asks: is this ONE path segment (AGL-2572), and is
+ * the address one the published site can actually answer (AGL-2076)? The set
+ * of bundle slugs is safe today only because of where they come from —
+ * starter slugs are code-defined, and library-template slugs were captured
+ * off screens that already passed a guard. Provenance is not a guard, and it
+ * stops being true the first time a template carries an author-supplied slug.
+ *
+ * Answers over the address `resolveTemplateSlug` would REQUEST — the slug,
+ * or the display name when the slug sanitizes away, or `page` — because a
+ * screen whose slug is `###` and whose name is `Search` still lands on
+ * `search`. De-confliction only ever appends a numeric suffix, so it can
+ * neither create a reserved segment nor clear one.
+ *
+ * A refusal string rather than a boolean, so the caller can name to the
+ * author which rule the screen fell foul of.
+ */ export function templateScreenAddressRefusal(input) {
+    var _ref, _normalizeScreenSlug;
+    if (screenSlugHasPathSeparator(input.slug)) {
+        return SCREEN_SLUG_PATH_SEPARATOR_MESSAGE;
+    }
+    const requested = (_ref = (_normalizeScreenSlug = normalizeScreenSlug(input.slug)) != null ? _normalizeScreenSlug : normalizeScreenSlug(input.displayName)) != null ? _ref : 'page';
+    const reserved = reservedScreenRouteSegment(requested);
+    return reserved ? reservedScreenRouteMessage(reserved) : undefined;
+}
+/**
+ * The address one template page claims (AGL-1575).
+ *
+ * This used to be a private `slugifyPageName` that stripped every character
+ * outside `[a-z0-9]`, so `'/'` and `''` both reduced to the empty string and
+ * fell through to the display name. A template screen asking for the SITE
+ * ROOT could therefore never get it: the shop starters declared `slug: ''`
+ * meaning home and were published at `/home`, and a site started from any
+ * template 404'd at its own URL while the console showed a success toast.
+ *
+ * The routing-map format has one canonical normalizer — `normalizeScreenSlug`
+ * — which is what the Screens page and the besigner already publish through,
+ * and which is the only place that knows `'/'` is the root path rather than
+ * punctuation. Template pages now go through it too, so all three surfaces
+ * agree on what a user-supplied address means.
+ *
+ * ## De-confliction (the invariant)
+ *
+ * `usedSlugs` holds every path already routed on the host plus everything
+ * claimed earlier in the same batch. A claim that collides FALLS BACK; it
+ * never overwrites, because the caller publishes into the host's routing map
+ * and a duplicate path would take a live page off the site.
+ *
+ * The root is the interesting case: `'/-2'` is not an address, so a second
+ * claimant on a host that already has a home page falls back to its NAME
+ * (`Home` → `home`), and only then to numeric suffixes. First claimant wins
+ * the root; everybody after it gets a real path of their own.
+ *
+ * Mutates `usedSlugs` with whatever it hands out.
+ */ export function resolveTemplateSlug(input) {
+    var _normalizeScreenSlug, _normalizeScreenSlug1;
+    const { usedSlugs } = input;
+    // `normalizeScreenSlug` returns undefined for anything that sanitizes away
+    // (`''`, `'###'`) — the caller decides what that means, and here it means
+    // "no address authored", so the display name answers instead.
+    const named = (_normalizeScreenSlug = normalizeScreenSlug(input.displayName)) != null ? _normalizeScreenSlug : 'page';
+    const requested = (_normalizeScreenSlug1 = normalizeScreenSlug(input.slug)) != null ? _normalizeScreenSlug1 : named;
+    const base = requested === SCREEN_ROOT_PATH && usedSlugs.has(SCREEN_ROOT_PATH) ? named : requested;
+    let slug = base;
+    let attempt = 2;
+    while(usedSlugs.has(slug))slug = `${base}-${attempt++}`;
+    usedSlugs.add(slug);
+    return {
+        slug,
+        requestedSlug: requested
+    };
+}
+/**
+ * Gives a multi-page bundle a home page when nothing in it claims one
+ * (AGL-1575).
+ *
+ * A starter is somebody's whole site, and a site whose root 404s is broken in
+ * the one place every visitor lands. When no screen in the bundle asks for
+ * `SCREEN_ROOT_PATH` and the host has no root route yet, the FIRST screen —
+ * authored order, which is the order the author meant them to be created in —
+ * takes it. That also repairs starters materialized before this fix, whose
+ * seeded documents dropped the home screen's `slug: ''` on the floor.
+ *
+ * Deliberately NOT applied to the single-template "Use template" dialog: the
+ * user types an address there, and silently re-pointing an explicit answer at
+ * the root would be a worse surprise than a site that needs a home page.
+ * Deliberately conditional on the host having no root: it never moves a live
+ * home page, which is the same invariant `resolveTemplateSlug` protects.
+ */ export function withBundleRootScreen(screens, usedSlugs) {
+    const list = [
+        ...screens
+    ];
+    if (!list.length) return list;
+    if ([
+        ...usedSlugs
+    ].includes(SCREEN_ROOT_PATH)) return list;
+    const claimsRoot = list.some((screen)=>normalizeScreenSlug(screen.slug) === SCREEN_ROOT_PATH);
+    if (claimsRoot) return list;
+    list[0] = _extends({}, list[0], {
+        slug: SCREEN_ROOT_PATH
+    });
+    return list;
+}
+/**
+ * {@link resolveTemplateSlug} over a list instead of a `Set` it mutates: the
+ * address a page claims, and the paths taken once it has. For a caller that
+ * cannot hold a `Set` (the native apps) and for the recorded cases.
+ */ export function resolveTemplateSlugAmong(input) {
+    const used = new Set(input.taken);
+    const { slug, requestedSlug } = resolveTemplateSlug({
+        slug: input.slug,
+        displayName: input.displayName,
+        usedSlugs: used
+    });
+    return {
+        slug,
+        requestedSlug,
+        taken: [
+            ...used
+        ]
+    };
+}
+
+//# sourceMappingURL=template-slug.js.map

package/src/lib/app-utils/template-slug.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/template-slug.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 */\nimport {\n  normalizeScreenSlug,\n  reservedScreenRouteMessage,\n  reservedScreenRouteSegment,\n  SCREEN_ROOT_PATH,\n  SCREEN_SLUG_PATH_SEPARATOR_MESSAGE,\n  screenSlugHasPathSeparator,\n} from './screen-slug'\n\n/*\n * Where a page made from a template lands, in a leaf of its own (it was\n * `create-page-from-template.ts`, which reaches Firestore) so the native apps\n * replay the same answers. The console file re-exports all three names.\n */\n\n/**\n * Why one template screen cannot be given the address it asks for, or\n * `undefined` when it can (AGL-2588).\n *\n * The bundle appliers pass `slug` straight off a template document into\n * {@link createPageFromTemplate}, so no field ever asks the two questions\n * every typed slug field asks: is this ONE path segment (AGL-2572), and is\n * the address one the published site can actually answer (AGL-2076)? The set\n * of bundle slugs is safe today only because of where they come from —\n * starter slugs are code-defined, and library-template slugs were captured\n * off screens that already passed a guard. Provenance is not a guard, and it\n * stops being true the first time a template carries an author-supplied slug.\n *\n * Answers over the address `resolveTemplateSlug` would REQUEST — the slug,\n * or the display name when the slug sanitizes away, or `page` — because a\n * screen whose slug is `###` and whose name is `Search` still lands on\n * `search`. De-confliction only ever appends a numeric suffix, so it can\n * neither create a reserved segment nor clear one.\n *\n * A refusal string rather than a boolean, so the caller can name to the\n * author which rule the screen fell foul of.\n */\nexport function templateScreenAddressRefusal(input: {\n  slug?: string\n  displayName?: string\n}): string | undefined {\n  if (screenSlugHasPathSeparator(input.slug)) {\n    return SCREEN_SLUG_PATH_SEPARATOR_MESSAGE\n  }\n  const requested =\n    normalizeScreenSlug(input.slug) ??\n    normalizeScreenSlug(input.displayName) ??\n    'page'\n  const reserved = reservedScreenRouteSegment(requested)\n  return reserved ? reservedScreenRouteMessage(reserved) : undefined\n}\n\n/**\n * The address one template page claims (AGL-1575).\n *\n * This used to be a private `slugifyPageName` that stripped every character\n * outside `[a-z0-9]`, so `'/'` and `''` both reduced to the empty string and\n * fell through to the display name. A template screen asking for the SITE\n * ROOT could therefore never get it: the shop starters declared `slug: ''`\n * meaning home and were published at `/home`, and a site started from any\n * template 404'd at its own URL while the console showed a success toast.\n *\n * The routing-map format has one canonical normalizer — `normalizeScreenSlug`\n * — which is what the Screens page and the besigner already publish through,\n * and which is the only place that knows `'/'` is the root path rather than\n * punctuation. Template pages now go through it too, so all three surfaces\n * agree on what a user-supplied address means.\n *\n * ## De-confliction (the invariant)\n *\n * `usedSlugs` holds every path already routed on the host plus everything\n * claimed earlier in the same batch. A claim that collides FALLS BACK; it\n * never overwrites, because the caller publishes into the host's routing map\n * and a duplicate path would take a live page off the site.\n *\n * The root is the interesting case: `'/-2'` is not an address, so a second\n * claimant on a host that already has a home page falls back to its NAME\n * (`Home` → `home`), and only then to numeric suffixes. First claimant wins\n * the root; everybody after it gets a real path of their own.\n *\n * Mutates `usedSlugs` with whatever it hands out.\n */\nexport function resolveTemplateSlug(input: {\n  /** Preferred address as authored — `'/'` (or `SCREEN_ROOT_PATH`) for home. */\n  slug?: string\n  /** Falls back to a slug of this when no address is authored. */\n  displayName: string\n  /** Paths already taken. Mutated with whatever this page claims. */\n  usedSlugs: Set<string>\n}): { slug: string; requestedSlug: string } {\n  const { usedSlugs } = input\n  // `normalizeScreenSlug` returns undefined for anything that sanitizes away\n  // (`''`, `'###'`) — the caller decides what that means, and here it means\n  // \"no address authored\", so the display name answers instead.\n  const named = normalizeScreenSlug(input.displayName) ?? 'page'\n  const requested = normalizeScreenSlug(input.slug) ?? named\n\n  const base =\n    requested === SCREEN_ROOT_PATH && usedSlugs.has(SCREEN_ROOT_PATH)\n      ? named\n      : requested\n  let slug = base\n  let attempt = 2\n  while (usedSlugs.has(slug)) slug = `${base}-${attempt++}`\n  usedSlugs.add(slug)\n  return { slug, requestedSlug: requested }\n}\n\n/**\n * Gives a multi-page bundle a home page when nothing in it claims one\n * (AGL-1575).\n *\n * A starter is somebody's whole site, and a site whose root 404s is broken in\n * the one place every visitor lands. When no screen in the bundle asks for\n * `SCREEN_ROOT_PATH` and the host has no root route yet, the FIRST screen —\n * authored order, which is the order the author meant them to be created in —\n * takes it. That also repairs starters materialized before this fix, whose\n * seeded documents dropped the home screen's `slug: ''` on the floor.\n *\n * Deliberately NOT applied to the single-template \"Use template\" dialog: the\n * user types an address there, and silently re-pointing an explicit answer at\n * the root would be a worse surprise than a site that needs a home page.\n * Deliberately conditional on the host having no root: it never moves a live\n * home page, which is the same invariant `resolveTemplateSlug` protects.\n */\nexport function withBundleRootScreen<T extends { slug?: string }>(\n  screens: readonly T[],\n  usedSlugs: Iterable<string>,\n): T[] {\n  const list = [...screens]\n  if (!list.length) return list\n  if ([...usedSlugs].includes(SCREEN_ROOT_PATH)) return list\n  const claimsRoot = list.some(\n    (screen) => normalizeScreenSlug(screen.slug) === SCREEN_ROOT_PATH,\n  )\n  if (claimsRoot) return list\n  list[0] = { ...list[0], slug: SCREEN_ROOT_PATH }\n  return list\n}\n\n\n/**\n * {@link resolveTemplateSlug} over a list instead of a `Set` it mutates: the\n * address a page claims, and the paths taken once it has. For a caller that\n * cannot hold a `Set` (the native apps) and for the recorded cases.\n */\nexport function resolveTemplateSlugAmong(input: {\n  slug?: string\n  displayName: string\n  taken: readonly string[]\n}): { slug: string; requestedSlug: string; taken: string[] } {\n  const used = new Set(input.taken)\n  const { slug, requestedSlug } = resolveTemplateSlug({\n    slug: input.slug,\n    displayName: input.displayName,\n    usedSlugs: used,\n  })\n  return { slug, requestedSlug, taken: [...used] }\n}\n"],"names":["normalizeScreenSlug","reservedScreenRouteMessage","reservedScreenRouteSegment","SCREEN_ROOT_PATH","SCREEN_SLUG_PATH_SEPARATOR_MESSAGE","screenSlugHasPathSeparator","templateScreenAddressRefusal","input","slug","requested","displayName","reserved","undefined","resolveTemplateSlug","usedSlugs","named","base","has","attempt","add","requestedSlug","withBundleRootScreen","screens","list","length","includes","claimsRoot","some","screen","resolveTemplateSlugAmong","used","Set","taken"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GACD,SACEA,mBAAmB,EACnBC,0BAA0B,EAC1BC,0BAA0B,EAC1BC,gBAAgB,EAChBC,kCAAkC,EAClCC,0BAA0B,QACrB,mBAAe;AAEtB;;;;CAIC,GAED;;;;;;;;;;;;;;;;;;;;;CAqBC,GACD,OAAO,SAASC,6BAA6BC,KAG5C;QAKGP,MAAAA;IAJF,IAAIK,2BAA2BE,MAAMC,IAAI,GAAG;QAC1C,OAAOJ;IACT;IACA,MAAMK,aACJT,QAAAA,uBAAAA,oBAAoBO,MAAMC,IAAI,aAA9BR,uBACAA,oBAAoBO,MAAMG,WAAW,aADrCV,OAEA;IACF,MAAMW,WAAWT,2BAA2BO;IAC5C,OAAOE,WAAWV,2BAA2BU,YAAYC;AAC3D;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BC,GACD,OAAO,SAASC,oBAAoBN,KAOnC;QAKeP,sBACIA;IALlB,MAAM,EAAEc,SAAS,EAAE,GAAGP;IACtB,2EAA2E;IAC3E,0EAA0E;IAC1E,8DAA8D;IAC9D,MAAMQ,SAAQf,uBAAAA,oBAAoBO,MAAMG,WAAW,aAArCV,uBAA0C;IACxD,MAAMS,aAAYT,wBAAAA,oBAAoBO,MAAMC,IAAI,aAA9BR,wBAAmCe;IAErD,MAAMC,OACJP,cAAcN,oBAAoBW,UAAUG,GAAG,CAACd,oBAC5CY,QACAN;IACN,IAAID,OAAOQ;IACX,IAAIE,UAAU;IACd,MAAOJ,UAAUG,GAAG,CAACT,MAAOA,OAAO,GAAGQ,KAAK,CAAC,EAAEE,WAAW;IACzDJ,UAAUK,GAAG,CAACX;IACd,OAAO;QAAEA;QAAMY,eAAeX;IAAU;AAC1C;AAEA;;;;;;;;;;;;;;;;CAgBC,GACD,OAAO,SAASY,qBACdC,OAAqB,EACrBR,SAA2B;IAE3B,MAAMS,OAAO;WAAID;KAAQ;IACzB,IAAI,CAACC,KAAKC,MAAM,EAAE,OAAOD;IACzB,IAAI;WAAIT;KAAU,CAACW,QAAQ,CAACtB,mBAAmB,OAAOoB;IACtD,MAAMG,aAAaH,KAAKI,IAAI,CAC1B,CAACC,SAAW5B,oBAAoB4B,OAAOpB,IAAI,MAAML;IAEnD,IAAIuB,YAAY,OAAOH;IACvBA,IAAI,CAAC,EAAE,GAAG,aAAKA,IAAI,CAAC,EAAE;QAAEf,MAAML;;IAC9B,OAAOoB;AACT;AAGA;;;;CAIC,GACD,OAAO,SAASM,yBAAyBtB,KAIxC;IACC,MAAMuB,OAAO,IAAIC,IAAIxB,MAAMyB,KAAK;IAChC,MAAM,EAAExB,IAAI,EAAEY,aAAa,EAAE,GAAGP,oBAAoB;QAClDL,MAAMD,MAAMC,IAAI;QAChBE,aAAaH,MAAMG,WAAW;QAC9BI,WAAWgB;IACb;IACA,OAAO;QAAEtB;QAAMY;QAAeY,OAAO;eAAIF;SAAK;IAAC;AACjD"}