@pramen/cms-editor 0.0.53 → 0.0.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/cms-editor",
-  "version": "0.0.53",
+  "version": "0.0.54",
   "description": "Visual block/page editor for @pramen/cms \u2014 a standalone React SPA that talks to the CMS handlers over HTTP.",
   "license": "MIT",
   "repository": {

package/src/app-context.tsx

@@ -27,7 +27,7 @@ declare global {
       hidePages?: boolean;
       /** Extra top-nav links to companion tools the host serves (e.g. a curation page).
        * Rendered as plain external `<a>` links after the built-in tabs. */
-      extraNav?: { label: string; href: string }[];
+      extraNav?: { label: string; href: string; target?: "_blank" | "_self" }[];
       /** The wordmark in the topbar, on the Setup screen, and in the browser tab.
        *
        * This editor ships as a package an agency deploys FOR ITS CLIENT, so the default

package/src/mount.ts

@@ -17,7 +17,8 @@
 
 import type { BuzolaNavigateEvent, NavigationAdapter } from "@buzola/router";
 
-/** A mount path must be a chain of path segments rooted at the origin.
+/** A mount path must be a chain of non-empty path segments rooted at the origin, written
+ * only in characters that `URL.pathname` returns UNENCODED.
  *
  * Rooted, and required to say so: buzola prepends the base path to every href it builds, so
  * anything that is not already an absolute path resolves somewhere unintended. A leading
@@ -26,10 +27,14 @@ import type { BuzolaNavigateEvent, NavigationAdapter } from "@buzola/router";
  * mounted. `//cdn.example.com` is rejected for the same reason: protocol-relative, and the
  * natural product of `"/" + prefix` where the prefix already carried a slash.
  *
- * Segments only, too: a value carrying `?`, `#` or `\` is not a mount path, and each breaks
- * routing in its own silent way (a query swallows the rest of every href; a backslash
- * resolves off-site while looking local). */
-const MOUNT_PATH = /^\/[^/\\?#][^\\?#]*$/;
+ * The character set is not a style choice. Every comparison against a mount path in this
+ * file — and buzola's own `stripBasePath`, which we cannot change — is a raw `startsWith`
+ * against a `URL.pathname`, which is percent-ENCODED. Admit a character the parser encodes
+ * and the two sides can never match: a mount of `/správa` is compared against
+ * `/spr%C3%A1va/...` and EVERY in-prefix url reads as off-prefix. So the admitted set is
+ * derived from the parser rather than guessed — `"<>^`{}`, backslash, space and everything
+ * non-ASCII all encode, and are refused here. */
+const MOUNT_PATH = /^(?:\/[A-Za-z0-9!$%&'()*+,\-.:;=@[\]_|~]+)+$/;
 
 /**
  * Normalize the mount node's declared prefix to buzola's shape: `""` for the origin root,
@@ -43,12 +48,16 @@ const MOUNT_PATH = /^\/[^/\\?#][^\\?#]*$/;
  */
 export function resolveBasePath(raw?: string | null): string {
   const trimmed = (raw ?? "").trim();
-  if (trimmed === "" || trimmed === "/") return "";
-  if (!MOUNT_PATH.test(trimmed)) {
+  // Trailing slashes come off FIRST, so `MOUNT_PATH` only ever judges the canonical form
+  // and a value that is nothing but slashes collapses to the root rather than being warned
+  // about as malformed.
+  const canonical = trimmed.replace(/\/+$/, "");
+  if (canonical === "") return "";
+  if (!MOUNT_PATH.test(canonical)) {
     console.warn(`pramen/cms-editor: ignoring unusable mount path ${JSON.stringify(trimmed)} — mounting at the origin root.`);
     return "";
   }
-  return trimmed.replace(/\/+$/, "");
+  return canonical;
 }
 
 /** Read the prefix the shell stamped onto the mount node. */
@@ -86,13 +95,19 @@ export function scopeToBasePath(inner: NavigationAdapter, basePath: string): Nav
   // Keyed by the caller's handler so `removeEventListener` can find the wrapper it added;
   // without this the router's `start()` teardown would leave the listener attached.
   const wrappers = new Map<Handler, Handler>();
+  // Spread, not a hand-written list of the seven methods. Enumerating them forwards
+  // correctly today but only fails safe by luck: tsc catches a newly REQUIRED member of
+  // `NavigationAdapter`, while an OPTIONAL one is silently dropped — and the next planned
+  // buzola bump (past ^0.0.12, for `router.leaveApp`) is exactly where such a member would
+  // arrive. Overriding the two listener methods is the whole of what this wrapper does.
   return {
-    getCurrentURL: () => inner.getCurrentURL(),
-    navigate: (url, options) => inner.navigate(url, options),
-    back: () => inner.back(),
-    forward: () => inner.forward(),
-    getState: () => inner.getState(),
+    ...inner,
     addEventListener(type, handler) {
+      // Adding the same handler twice would attach two wrappers to the inner adapter while
+      // the map kept only the second, so the first could never be removed and would keep
+      // feeding a torn-down router. Nothing does this today (`Router.start()` mints a fresh
+      // closure per call), which is precisely why it should be closed while it is free.
+      if (wrappers.has(handler)) return;
       const wrapper: Handler = (event) => {
         // A malformed destination is not ours to claim.
         let pathname: string;
@@ -115,6 +130,51 @@ export function scopeToBasePath(inner: NavigationAdapter, basePath: string): Nav
   };
 }
 
+/**
+ * Whether a host-configured nav link may navigate the CURRENT tab.
+ *
+ * The default for `extraNav` is a new tab, because `_404.tsx` registers the catch-all
+ * `/:__notFound+`: an unmounted editor's router matches every same-origin path, so a
+ * same-tab click would land on the in-app 404 instead of the tool. `target: "_self"` asks
+ * for the co-hosted case, and is honoured only where it cannot strand the user.
+ *
+ * Lives here, not in the layout, for two reasons: these are the same containment rules
+ * `scopeToBasePath` enforces and they belong beside them, and a predicate that decides
+ * whether a click escapes the SPA has to be testable without a DOM. `documentUrl` is a
+ * PARAMETER rather than a read of `window.location` for the same reason — and because it
+ * is the one input that must not be guessed:
+ *
+ *   - Resolve against `location.origin` and a relative href like `"curate"` is judged as
+ *     `/curate` while the browser navigates to `<current dir>/curate`. Off-prefix by the
+ *     check, in-prefix in fact, so the link lands on the very 404 this exists to avoid.
+ *     `?tab=x` and `#top` are the same mistake with an even wider gap.
+ *   - So the caller passes the document URL the browser will itself resolve against.
+ */
+export function opensInSameTab(href: string, target: string | undefined, basePath: string, documentUrl: string): boolean {
+  if (target !== "_self") return false;
+  let url: URL;
+  let docOrigin: string;
+  try {
+    url = new URL(href, documentUrl);
+    docOrigin = new URL(documentUrl).origin;
+  } catch {
+    return false;
+  }
+  // `new URL` happily parses `javascript:` and `data:`, and their `pathname` is an opaque
+  // string that trivially fails any containment test — so without this they would take the
+  // same-tab branch and shed the `rel` that used to confine them. A url with no hierarchical
+  // path cannot be reasoned about as "inside or outside the mount"; the answer is no.
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  // Cross-origin ALWAYS escapes on its own — the catch-all can only claim same-origin paths
+  // — so it is safe in the same tab whether or not this editor is mounted. That makes an
+  // external tool the one configuration that works at the origin root, which is the opposite
+  // of what a bare `basePath` check concludes.
+  if (url.origin !== docOrigin) return true;
+  // Same origin: safe only where the router will not claim it. At the root `isWithinBasePath`
+  // is true for everything, so this correctly refuses every same-origin `_self` there.
+  return !isWithinBasePath(url.pathname, basePath);
+}
+
 /** The backend the shell declared: which Worker to call, and as which tenant.
  *
  * When present these are NOT read from (or written to) localStorage — the server knows

package/src/routes/_layout.tsx

@@ -2,11 +2,12 @@
 // wrapped around every route via <Outlet />. Tab highlighting is derived from the
 // current path, so a deep link or refresh lands with the right tab lit.
 
-import { Outlet, useNavigate, useRoute } from "@buzola/router";
+import { Outlet, useNavigate, useRoute, useRouter } from "@buzola/router";
 import { Button, Card, MoonIcon, SunIcon, Text, Topbar } from "@podoba/react";
 import { useEffect, useState } from "react";
 import { useApp } from "../app-context";
 import { BRAND } from "../brand";
+import { opensInSameTab } from "../mount";
 
 const THEME_KEY = "pramen.cms.theme";
 
@@ -18,8 +19,11 @@ export default function RootLayout() {
   // Every chrome action here is a way OUT of the current screen, so it runs through that
   // screen's unsaved-changes guard first (the page editor registers one; with no guard
   // registered this is a pass-through). In-app navigation fires no `beforeunload`, so
-  // without this the topbar silently discards unsaved edits. The external `extraNav` links
-  // open in a new tab and leave nothing behind, so they stay unguarded.
+  // without this the topbar silently discards unsaved edits. An `extraNav` link that opens a
+  // NEW tab leaves this document alone and needs no guard; one honoured as `_self` is a real
+  // cross-document navigation, so it takes the guard too (below). `beforeunload` is not a
+  // fallback for it — only `PageEditor` registers one, so a dirty CollectionEditor form would
+  // otherwise be discarded with no prompt of any kind.
   const guarded = (go: () => void) => () => { if (confirmNavigation()) go(); };
 
   // Dark mode: podoba tokens flip under `[data-theme="dark"]` — no `dark:` prefixes.
@@ -47,6 +51,13 @@ export default function RootLayout() {
   // Collections-only deployments hide the block/page builder entirely.
   const hidePages = typeof window !== "undefined" ? window.PRAMEN_CMS_EDITOR?.hidePages === true : false;
 
+  // See the extraNav comment below. The rules live in `mount.ts` beside the containment they
+  // depend on; what this supplies is the URL the BROWSER will resolve a relative href
+  // against — the current document, not the origin. Empty when there is no `window`, which
+  // makes every href unparseable and so degrades to the safe new-tab default.
+  const basePath = useRouter().basePath;
+  const documentUrl = typeof window !== "undefined" ? window.location.href : "";
+
   return (
     // Page-level surface so the whole viewport (not just the topbar + cards) flips
     // under `[data-theme="dark"]` — otherwise the body stays white in dark mode.
@@ -89,24 +100,21 @@ export default function RootLayout() {
             Settings
           </Button>
           {extraNav.map((l) => (
-            // Companion tools live OUTSIDE this SPA (a separate static page/worker route), so
-            // open them in a new tab. NOT a style choice, and `target: "_self"` alone would not
-            // fix it: `_404.tsx` registers the catch-all `/:__notFound+`, so buzola matches
-            // EVERY same-origin path and intercepts it — a same-tab click and `location.assign`
-            // both land on the in-app 404 (verified). Only a cross-origin url escapes on its own.
+            // Defaults to a new tab: a companion tool is normally a separate deployment, and
+            // `_404.tsx` registers the catch-all `/:__notFound+`, so the router matches every
+            // SAME-ORIGIN path — a same-tab click would land on the in-app 404 rather than the
+            // tool. `target: "_self"` asks for the co-hosted case, and is honoured only where
+            // the router provably will not claim the url (`opensInSameTab` in mount.ts):
+            //
+            //   - cross-origin: always, mounted or not. The catch-all cannot reach another
+            //     origin, so this is the ONE case that also works at the origin root.
+            //   - same-origin: only outside the mount prefix, where `scopeToBasePath` leaves
+            //     the navigation to the browser. At the root there is no outside, so never.
             //
-            // The supported same-tab route is `router.leaveApp(href)` (@buzola/router >= 0.0.16),
-            // which releases one navigation to the browser. This package still pins ^0.0.12, so
-            // adopting it is a version bump plus a `target` option on the config item.
-            <a
-              key={l.href}
-              href={l.href}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="rounded-md px-2.5 py-1.5 text-small text-fg-muted transition-colors hover:bg-surface-muted hover:text-fg"
-            >
-              {l.label}
-            </a>
+            // Anything else degrades to the new tab rather than stranding the user on a 404.
+            // (When @buzola/router moves past ^0.0.12 here, `router.leaveApp(href)` releases
+            // one navigation to the browser and makes same-origin `_self` work unmounted too.)
+            <NavLink key={`${l.href}|${l.label}`} link={l} sameTab={opensInSameTab(l.href, l.target, basePath, documentUrl)} confirm={confirmNavigation} />
           ))}
         </Topbar.Nav>
         <Topbar.Actions>
@@ -136,3 +144,29 @@ export default function RootLayout() {
     </div>
   );
 }
+
+/** One host-configured link to a companion tool.
+ *
+ * `rel="noreferrer"` is on BOTH branches. `noopener` is genuinely moot in the same tab (no
+ * new browsing context is created, so there is no `window.opener` to sever) but `noreferrer`
+ * is not: without it a click from `/_pramen/admin/pages/<id>` hands that full url to the
+ * destination as `Referer`, and `_self` is honoured for cross-origin destinations.
+ *
+ * The key pairs href with label, because two entries may legitimately point at the same href
+ * and differ only in label or target — keyed on href alone React reconciles them together
+ * and the rendered label can end up on the other one's anchor.
+ */
+function NavLink({ link, sameTab, confirm }: { link: { label: string; href: string; target?: string }; sameTab: boolean; confirm: () => boolean }) {
+  return (
+    <a
+      href={link.href}
+      rel={sameTab ? "noreferrer" : "noopener noreferrer"}
+      // Only the same-tab case unloads this document, so only it consults the guard.
+      onClick={sameTab ? (e) => { if (!confirm()) e.preventDefault(); } : undefined}
+      {...(sameTab ? {} : { target: "_blank" })}
+      className="rounded-md px-2.5 py-1.5 text-small text-fg-muted transition-colors hover:bg-surface-muted hover:text-fg"
+    >
+      {link.label}
+    </a>
+  );
+}