@aglyn/shared-ui-jsx 1.0.0-beta.233 → 1.0.0-beta.235

package/src/lib/utils/new-tab.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @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.
+ */
+/**
+ * Preview and view links open in a NEW TAB (AGL-3660).
+ *
+ * A "Preview", "View live", "Visit site" or eye-icon action shows the reader
+ * something ELSE — a rendered artifact, a published page, a buyer's view —
+ * while they are in the middle of working on a list or an editor. Sending the
+ * console tab there threw away their place (filters, scroll, an open drawer)
+ * for a glance they meant to take beside it. So every such action opens a tab
+ * of its own, and says so to assistive tech.
+ *
+ * This module is the one place that spelling lives:
+ *
+ * - {@link newTabLinkProps} for an anchor / `AppLink` / MUI `href` control;
+ * - {@link openInNewTab} for a click handler that has the URL in hand;
+ * - {@link openPendingTab} for one that must `await` the URL first — a tab
+ *   opened after the await is a popup the browser blocks;
+ * - {@link withNewTabHint} for the accessible name.
+ *
+ * `apps/console/specs/preview-links-open-in-new-tab.spec.ts` sweeps the
+ * console and plugin sources and fails when a preview/view action is wired
+ * without one of these (or an equivalent `target="_blank"`).
+ */
+/** The suffix every new-tab control's accessible name ends with. */
+export declare const NEW_TAB_HINT = "(opens in a new tab)";
+/**
+ * `noopener` so the opened page cannot script this console through
+ * `window.opener`; `noreferrer` so a published site does not learn the
+ * console URL (org slug, site id) it was opened from.
+ */
+export declare const NEW_TAB_REL = "noopener noreferrer";
+/** Spread onto an anchor-rendering control: `<AppLink {...newTabLinkProps}>`. */
+export declare const newTabLinkProps: Readonly<{
+    readonly target: "_blank";
+    readonly rel: "noopener noreferrer";
+}>;
+/**
+ * `rel` for a new-tab link that already carries tokens of its own
+ * (`nofollow`, say): theirs, plus `noopener noreferrer`, each once.
+ */
+export declare function mergeNewTabRel(rel?: string | null): string;
+/** `label` with {@link NEW_TAB_HINT} appended, exactly once. */
+export declare function withNewTabHint(label: string): string;
+/**
+ * Open `url` in a new tab from a click handler. Use this rather than
+ * `router.push` / `location.assign` for a preview or view action.
+ */
+export declare function openInNewTab(url: string): void;
+/** A tab opened during the click, navigated once its URL is known. */
+export interface PendingTab {
+    /** Send the tab to `url`; falls back to {@link openInNewTab} if the browser
+     *  refused the blank tab. Never navigates the console tab itself. */
+    navigate(url: string): void;
+    /** Close the blank tab, for when the URL could not be produced. */
+    close(): void;
+}
+/**
+ * Open a blank tab NOW, inside the click's user activation, and point it at a
+ * URL that is only known after an `await`.
+ *
+ * NOT `window.open('', '_blank', 'noopener')`: with `noopener` the browser
+ * returns `null`, so there is no handle to navigate — the pattern that left
+ * "Preview on site" opening an empty tab AND moving the console tab. Instead
+ * the tab is opened with a handle and its `opener` is cut by hand before it
+ * goes anywhere, which is what `noopener` would have done.
+ */
+export declare function openPendingTab(): PendingTab;

package/src/lib/utils/new-tab.js

@@ -0,0 +1,97 @@
+/**
+ * @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.
+ */ /**
+ * Preview and view links open in a NEW TAB (AGL-3660).
+ *
+ * A "Preview", "View live", "Visit site" or eye-icon action shows the reader
+ * something ELSE — a rendered artifact, a published page, a buyer's view —
+ * while they are in the middle of working on a list or an editor. Sending the
+ * console tab there threw away their place (filters, scroll, an open drawer)
+ * for a glance they meant to take beside it. So every such action opens a tab
+ * of its own, and says so to assistive tech.
+ *
+ * This module is the one place that spelling lives:
+ *
+ * - {@link newTabLinkProps} for an anchor / `AppLink` / MUI `href` control;
+ * - {@link openInNewTab} for a click handler that has the URL in hand;
+ * - {@link openPendingTab} for one that must `await` the URL first — a tab
+ *   opened after the await is a popup the browser blocks;
+ * - {@link withNewTabHint} for the accessible name.
+ *
+ * `apps/console/specs/preview-links-open-in-new-tab.spec.ts` sweeps the
+ * console and plugin sources and fails when a preview/view action is wired
+ * without one of these (or an equivalent `target="_blank"`).
+ */ /** The suffix every new-tab control's accessible name ends with. */ export const NEW_TAB_HINT = '(opens in a new tab)';
+/**
+ * `noopener` so the opened page cannot script this console through
+ * `window.opener`; `noreferrer` so a published site does not learn the
+ * console URL (org slug, site id) it was opened from.
+ */ export const NEW_TAB_REL = 'noopener noreferrer';
+/** Spread onto an anchor-rendering control: `<AppLink {...newTabLinkProps}>`. */ export const newTabLinkProps = Object.freeze({
+    target: '_blank',
+    rel: NEW_TAB_REL
+});
+/**
+ * `rel` for a new-tab link that already carries tokens of its own
+ * (`nofollow`, say): theirs, plus `noopener noreferrer`, each once.
+ */ export function mergeNewTabRel(rel) {
+    const tokens = new Set(`${rel != null ? rel : ''} ${NEW_TAB_REL}`.split(/\s+/).filter(Boolean));
+    return [
+        ...tokens
+    ].join(' ');
+}
+/** `label` with {@link NEW_TAB_HINT} appended, exactly once. */ export function withNewTabHint(label) {
+    const trimmed = label.trim();
+    return trimmed.endsWith(NEW_TAB_HINT) ? trimmed : `${trimmed} ${NEW_TAB_HINT}`;
+}
+/**
+ * Open `url` in a new tab from a click handler. Use this rather than
+ * `router.push` / `location.assign` for a preview or view action.
+ */ export function openInNewTab(url) {
+    if (typeof window === 'undefined' || !url) return;
+    window.open(url, '_blank', 'noopener,noreferrer');
+}
+/**
+ * Open a blank tab NOW, inside the click's user activation, and point it at a
+ * URL that is only known after an `await`.
+ *
+ * NOT `window.open('', '_blank', 'noopener')`: with `noopener` the browser
+ * returns `null`, so there is no handle to navigate — the pattern that left
+ * "Preview on site" opening an empty tab AND moving the console tab. Instead
+ * the tab is opened with a handle and its `opener` is cut by hand before it
+ * goes anywhere, which is what `noopener` would have done.
+ */ export function openPendingTab() {
+    const tab = typeof window === 'undefined' ? null : window.open('about:blank', '_blank');
+    if (tab) {
+        try {
+            tab.opener = null;
+        } catch (unused) {
+        // Cross-origin by now is impossible for about:blank; nothing to cut.
+        }
+    }
+    return {
+        navigate (url) {
+            if (!url) return;
+            if (tab && !tab.closed) tab.location.replace(url);
+            else openInNewTab(url);
+        },
+        close () {
+            if (tab && !tab.closed) tab.close();
+        }
+    };
+}
+
+//# sourceMappingURL=new-tab.js.map

package/src/lib/utils/new-tab.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../../libs/shared/ui/jsx/src/lib/utils/new-tab.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 * Preview and view links open in a NEW TAB (AGL-3660).\n *\n * A \"Preview\", \"View live\", \"Visit site\" or eye-icon action shows the reader\n * something ELSE — a rendered artifact, a published page, a buyer's view —\n * while they are in the middle of working on a list or an editor. Sending the\n * console tab there threw away their place (filters, scroll, an open drawer)\n * for a glance they meant to take beside it. So every such action opens a tab\n * of its own, and says so to assistive tech.\n *\n * This module is the one place that spelling lives:\n *\n * - {@link newTabLinkProps} for an anchor / `AppLink` / MUI `href` control;\n * - {@link openInNewTab} for a click handler that has the URL in hand;\n * - {@link openPendingTab} for one that must `await` the URL first — a tab\n *   opened after the await is a popup the browser blocks;\n * - {@link withNewTabHint} for the accessible name.\n *\n * `apps/console/specs/preview-links-open-in-new-tab.spec.ts` sweeps the\n * console and plugin sources and fails when a preview/view action is wired\n * without one of these (or an equivalent `target=\"_blank\"`).\n */\n\n/** The suffix every new-tab control's accessible name ends with. */\nexport const NEW_TAB_HINT = '(opens in a new tab)'\n\n/**\n * `noopener` so the opened page cannot script this console through\n * `window.opener`; `noreferrer` so a published site does not learn the\n * console URL (org slug, site id) it was opened from.\n */\nexport const NEW_TAB_REL = 'noopener noreferrer'\n\n/** Spread onto an anchor-rendering control: `<AppLink {...newTabLinkProps}>`. */\nexport const newTabLinkProps = Object.freeze({\n  target: '_blank',\n  rel: NEW_TAB_REL,\n} as const)\n\n/**\n * `rel` for a new-tab link that already carries tokens of its own\n * (`nofollow`, say): theirs, plus `noopener noreferrer`, each once.\n */\nexport function mergeNewTabRel(rel?: string | null): string {\n  const tokens = new Set(\n    `${rel ?? ''} ${NEW_TAB_REL}`.split(/\\s+/).filter(Boolean),\n  )\n  return [...tokens].join(' ')\n}\n\n/** `label` with {@link NEW_TAB_HINT} appended, exactly once. */\nexport function withNewTabHint(label: string): string {\n  const trimmed = label.trim()\n  return trimmed.endsWith(NEW_TAB_HINT) ? trimmed : `${trimmed} ${NEW_TAB_HINT}`\n}\n\n/**\n * Open `url` in a new tab from a click handler. Use this rather than\n * `router.push` / `location.assign` for a preview or view action.\n */\nexport function openInNewTab(url: string): void {\n  if (typeof window === 'undefined' || !url) return\n  window.open(url, '_blank', 'noopener,noreferrer')\n}\n\n/** A tab opened during the click, navigated once its URL is known. */\nexport interface PendingTab {\n  /** Send the tab to `url`; falls back to {@link openInNewTab} if the browser\n   *  refused the blank tab. Never navigates the console tab itself. */\n  navigate(url: string): void\n  /** Close the blank tab, for when the URL could not be produced. */\n  close(): void\n}\n\n/**\n * Open a blank tab NOW, inside the click's user activation, and point it at a\n * URL that is only known after an `await`.\n *\n * NOT `window.open('', '_blank', 'noopener')`: with `noopener` the browser\n * returns `null`, so there is no handle to navigate — the pattern that left\n * \"Preview on site\" opening an empty tab AND moving the console tab. Instead\n * the tab is opened with a handle and its `opener` is cut by hand before it\n * goes anywhere, which is what `noopener` would have done.\n */\nexport function openPendingTab(): PendingTab {\n  const tab =\n    typeof window === 'undefined' ? null : window.open('about:blank', '_blank')\n  if (tab) {\n    try {\n      tab.opener = null\n    } catch {\n      // Cross-origin by now is impossible for about:blank; nothing to cut.\n    }\n  }\n  return {\n    navigate(url: string) {\n      if (!url) return\n      if (tab && !tab.closed) tab.location.replace(url)\n      else openInNewTab(url)\n    },\n    close() {\n      if (tab && !tab.closed) tab.close()\n    },\n  }\n}\n"],"names":["NEW_TAB_HINT","NEW_TAB_REL","newTabLinkProps","Object","freeze","target","rel","mergeNewTabRel","tokens","Set","split","filter","Boolean","join","withNewTabHint","label","trimmed","trim","endsWith","openInNewTab","url","window","open","openPendingTab","tab","opener","navigate","closed","location","replace","close"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;CAqBC,GAED,kEAAkE,GAClE,OAAO,MAAMA,eAAe,uBAAsB;AAElD;;;;CAIC,GACD,OAAO,MAAMC,cAAc,sBAAqB;AAEhD,+EAA+E,GAC/E,OAAO,MAAMC,kBAAkBC,OAAOC,MAAM,CAAC;IAC3CC,QAAQ;IACRC,KAAKL;AACP,GAAW;AAEX;;;CAGC,GACD,OAAO,SAASM,eAAeD,GAAmB;IAChD,MAAME,SAAS,IAAIC,IACjB,GAAGH,cAAAA,MAAO,GAAG,CAAC,EAAEL,aAAa,CAACS,KAAK,CAAC,OAAOC,MAAM,CAACC;IAEpD,OAAO;WAAIJ;KAAO,CAACK,IAAI,CAAC;AAC1B;AAEA,8DAA8D,GAC9D,OAAO,SAASC,eAAeC,KAAa;IAC1C,MAAMC,UAAUD,MAAME,IAAI;IAC1B,OAAOD,QAAQE,QAAQ,CAAClB,gBAAgBgB,UAAU,GAAGA,QAAQ,CAAC,EAAEhB,cAAc;AAChF;AAEA;;;CAGC,GACD,OAAO,SAASmB,aAAaC,GAAW;IACtC,IAAI,OAAOC,WAAW,eAAe,CAACD,KAAK;IAC3CC,OAAOC,IAAI,CAACF,KAAK,UAAU;AAC7B;AAWA;;;;;;;;;CASC,GACD,OAAO,SAASG;IACd,MAAMC,MACJ,OAAOH,WAAW,cAAc,OAAOA,OAAOC,IAAI,CAAC,eAAe;IACpE,IAAIE,KAAK;QACP,IAAI;YACFA,IAAIC,MAAM,GAAG;QACf,EAAE,eAAM;QACN,qEAAqE;QACvE;IACF;IACA,OAAO;QACLC,UAASN,GAAW;YAClB,IAAI,CAACA,KAAK;YACV,IAAII,OAAO,CAACA,IAAIG,MAAM,EAAEH,IAAII,QAAQ,CAACC,OAAO,CAACT;iBACxCD,aAAaC;QACpB;QACAU;YACE,IAAIN,OAAO,CAACA,IAAIG,MAAM,EAAEH,IAAIM,KAAK;QACnC;IACF;AACF"}