@salesforcedevs/docs-components 1.30.1-locale-picker-2 → 1.30.1-locale-picker-final

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.30.1-locale-picker-2",
+  "version": "1.30.1-locale-picker-final",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

package/src/modules/doc/redocReference/BACK_NAVIGATION.md

@@ -0,0 +1,233 @@
+# Redoc "← Project Title" Back Button
+
+How the back link in the Redoc Left Nav behaves, and why each piece exists.
+
+## Why this is not a plain `<a href>`
+
+Switching locale in the Redoc UI is a **full page reload** (the locale picker is
+an `<a href>` that navigates to the same page in another locale). That has two
+consequences the back link has to deal with:
+
+1. `document.referrer` only ever remembers **one** previous page, and each locale
+   switch overwrites it. So after a couple of locale switches the referrer no
+   longer points at the real page you came from.
+2. The page you should go "back" to must be shown in **whatever locale you are
+   currently viewing** — not the locale it was in when you first visited it.
+
+To solve (1) we remember the back target ourselves in `sessionStorage` (survives
+reloads, per browser tab). To solve (2) we rewrite the stored URL's locale to the
+current one right before navigating.
+
+## URL shape assumption
+
+The locale segment sits in a **different position** depending on the content
+type:
+
+```
+docs content type
+  en-us (default):  /docs/bot-api            ← no locale segment
+  ja-jp:            /docs/ja-jp/bot-api       ← locale right after "docs"  (index 1)
+
+references content type
+  en-us (default):  /docs/service/multi-oas-redoc/references/reference-sample.html
+  ja-jp:            /docs/service/ja-jp/multi-oas-redoc/references/reference-sample.html
+                                   ↑ locale after the product segment  (index 2)
+```
+
+So: paths always start with `/docs/`, and a non-default locale is an extra
+segment — after `docs` for docs pages, after the product segment for
+references. The default locale `en-us` has no segment. `translateToCurrentLocale`
+picks the index with `isDocContentType` (docs → 1, references → 2).
+
+---
+
+## The two halves of the feature
+
+### Half 1 — Remembering where to go back to (`trackBackTarget`)
+
+Runs once per page load, inside `connectedCallback`.
+
+```ts
+private trackBackTarget(): void {
+    const referrerHref = this.getSameOriginReferrerHref();   // (a)
+    if (!referrerHref) {
+        return;                                              // (b)
+    }
+
+    const referrerUrl = new URL(referrerHref);
+    if (this.isLocaleHref(referrerUrl.pathname)) {           // (c)
+        return;
+    }
+
+    this.setBackTargetInSession(referrerHref);               // (d)
+}
+```
+
+- **(a)** Get the page we navigated here from — but only if it's a real in-tab,
+  same-origin navigation (see `getSameOriginReferrerHref` below).
+- **(b)** No usable referrer (fresh tab, opened a shared link, came from another
+  site) → store nothing. The stored target, if any, is left untouched.
+- **(c)** If the referrer is just **this same page in another locale** (a locale
+  switch), do **not** overwrite the stored target. This is the key line: it lets
+  the real "previous page" survive across any number of locale switches.
+- **(d)** Otherwise this was a normal navigation — remember it as the back target.
+
+#### `getSameOriginReferrerHref`
+
+```ts
+private getSameOriginReferrerHref(): string | null {
+    if (this.initialHistoryLength <= 1 || !document.referrer) {
+        return null;                                 // fresh tab / no referrer
+    }
+    try {
+        const referrerUrl = new URL(document.referrer);
+        if (referrerUrl.origin !== window.location.origin) {
+            return null;                             // came from another site
+        }
+        return referrerUrl.href;
+    } catch {
+        return null;                                 // malformed referrer
+    }
+}
+```
+
+`initialHistoryLength` is captured at mount (before Redoc pushes its own hash
+entries). `<= 1` means this is the first entry in the tab — there is no real
+in-tab "back".
+
+#### `isLocaleHref`
+
+```ts
+private isLocaleHref(pathname: string): boolean {
+    return this.languages.some((locale) => {
+        const href = locale?.link?.href;
+        return (
+            !!href &&
+            new URL(href, window.location.origin).pathname === pathname
+        );
+    });
+}
+```
+
+`this.languages` is the list the locale picker uses — each entry's `link.href` is
+**this page's URL in that locale**. So a pathname is a "locale sibling" if it
+exactly matches one of those hrefs.
+
+### Half 2 — Going back (`onBackClick` → `getTranslatedBackTarget` → `translateToCurrentLocale`)
+
+```ts
+private onBackClick = (event: Event): void => {
+    event.preventDefault();
+
+    const target = this.getTranslatedBackTarget() ?? this.headerHref;  // (1)
+
+    if (target) {
+        window.location.assign(target);                                // (2)
+    }
+};
+```
+
+- **(1)** Work out the back target; if none, fall back to `headerHref` (the
+  parent reference page passed in by the consumer).
+- **(2)** Navigate there.
+
+```ts
+private getTranslatedBackTarget(): string | null {
+    const stored = this.getBackTargetFromSession();        // (3)
+    if (stored) {
+        return this.language
+            ? this.translateToCurrentLocale(stored)        // (4)
+            : stored;
+    }
+
+    const referrer = this.getSameOriginReferrerHref();     // (5)
+    return referrer && !this.isLocaleHref(new URL(referrer).pathname)
+        ? referrer
+        : null;                                            // (6)
+}
+```
+
+- **(3)** Prefer the target we stored in `sessionStorage`.
+- **(4)** Rewrite its locale to match the locale we're viewing right now.
+- **(5)** No stored target → fall back to the referrer.
+- **(6)** But if that referrer is just this page in another locale, reject it
+  (returning `null`) so `onBackClick` uses `headerHref` instead. Without this we
+  could ping-pong between locales.
+
+```ts
+private translateToCurrentLocale(storedHref: string): string {
+    const url = new URL(storedHref, window.location.origin);
+    const localeIds = this.languages.map((loc) => loc.id);
+    const segments = url.pathname.split("/").filter(Boolean);
+
+    if (segments[0] === "docs") {
+        // Drop the existing locale segment, if any
+        if (localeIds.includes(segments[1])) {
+            segments.splice(1, 1);
+        }
+        // Add the current locale (en-us is the default, so it has none)
+        if (this.language && this.language !== "en-us") {
+            segments.splice(1, 0, this.language);
+        }
+    }
+
+    url.pathname = "/" + segments.join("/");
+    return url.href;
+}
+```
+
+Step by step, for a stored `/docs/intro.html` while viewing `ja-jp`:
+
+| step | `segments` |
+|------|-----------|
+| split path | `["docs", "intro.html"]` |
+| drop locale (`"intro.html"` is not a locale → no change) | `["docs", "intro.html"]` |
+| add `ja-jp` after `docs` | `["docs", "ja-jp", "intro.html"]` |
+| join | `/docs/ja-jp/intro.html` |
+
+All four locale combinations:
+
+| current locale | stored URL | result |
+|---|---|---|
+| ja-jp | `/docs/intro.html` | `/docs/ja-jp/intro.html` |
+| en-us | `/docs/ja-jp/intro.html` | `/docs/intro.html` |
+| en-us | `/docs/intro.html` | `/docs/intro.html` (unchanged) |
+| ja-jp | `/docs/ja-jp/intro.html` | `/docs/ja-jp/intro.html` (unchanged) |
+
+---
+
+## Worked example — the original QA bug
+
+> On `advanced-setup` → open `bot-api` → switch ja-jp → switch en → click back.
+
+| step | action | `document.referrer` | `sessionStorage[redoc-back-target]` |
+|------|--------|---------------------|--------------------------------------|
+| 1 | land on `advanced-setup` (en) | — | (empty) |
+| 2 | navigate to `bot-api` (en) | `advanced-setup` | **`advanced-setup`** ← stored, not a locale sibling |
+| 3 | switch to ja-jp → `bot-api` (ja) | `bot-api` (en) | `advanced-setup` ← **kept** (referrer is a locale sibling) |
+| 4 | switch to en → `bot-api` (en) | `bot-api` (ja) | `advanced-setup` ← **kept** again |
+| 5 | click **back** | — | reads `advanced-setup`, current locale en-us → no rewrite → navigate to `advanced-setup` ✓ |
+
+If at step 4 you had **stayed** in ja-jp and clicked back, step 5 would rewrite
+`advanced-setup` → `/docs/ja-jp/.../advanced-setup`, so you land on the page in
+the locale you're actually viewing.
+
+---
+
+## All cases at a glance
+
+| situation | what happens |
+|---|---|
+| Stored target exists | Go to it, re-localed to the current locale |
+| No stored target, normal same-origin referrer | Go to the referrer |
+| No stored target, referrer is a locale sibling | Ignore it → go to `headerHref` (parent) |
+| No stored target, no referrer (fresh tab / shared link / external) | Go to `headerHref` |
+| Multiple locale switches in a row | Original page is preserved (locale-sibling referrers never overwrite it) |
+
+## Tests
+
+See `__tests__/redocReference.test.ts`:
+
+- *adds the locale to the back target on click (en-us → ja-jp)*
+- *removes the locale from the back target on click (ja-jp → en-us)*
+- *falls back to headerHref when nothing is stored*

package/src/modules/doc/redocReference/redocReference.ts

@@ -42,6 +42,8 @@ const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
 const DEFAULT_PROJECT_TITLE = "All Reference";
 const BACK_TARGET_STORAGE_KEY = "redoc-back-target";
+const DOCS_PATH_SEGMENT = "docs";
+const DEFAULT_LOCALE = "en-us";
 
 export default class RedocReference extends LightningElement {
     private _referenceConfig: ReferenceConfig = { refList: [] };
@@ -205,22 +207,25 @@ export default class RedocReference extends LightningElement {
             : null;
     }
 
-    /* Rewrites the stored URL's locale to the current one. Paths are
-     * /docs/locale/.., except the default en-us which has no locale segment.
+    /* The locale segment sits after "docs" for docs pages,
+     * and after the product segment for references.
      */
     private translateToCurrentLocale(storedHref: string): string {
         const url = new URL(storedHref, window.location.origin);
         const localeIds = this.languages.map((loc) => loc.id);
         const segments = url.pathname.split("/").filter(Boolean);
 
-        if (segments[0] === "docs") {
+        // docs -> right after "docs"; references -> after the product segment.
+        const localeIndex = this.isDocContentType ? 1 : 2;
+
+        if (segments[0] === DOCS_PATH_SEGMENT) {
             // Drop the existing locale segment, if any
-            if (localeIds.includes(segments[1])) {
-                segments.splice(1, 1);
+            if (localeIds.includes(segments[localeIndex])) {
+                segments.splice(localeIndex, 1);
             }
             // Add the current locale
-            if (this.language && this.language !== "en-us") {
-                segments.splice(1, 0, this.language);
+            if (this.language && this.language !== DEFAULT_LOCALE) {
+                segments.splice(localeIndex, 0, this.language);
             }
         }
 
@@ -533,22 +538,20 @@ export default class RedocReference extends LightningElement {
     }
 
     /**
-     * Inserts the project header into Redoc for multi-spec reference sets.
+     * Inserts the project header and LNB footer into Redoc.
      */
     private insertSidebarNav(redocContainer: HTMLElement): void {
-        if (!this.showRedocHeader) {
-            return;
-        }
-
         // Select the LNB and content area of Redoc and insert the requried header.
-        redocContainer
-            .querySelectorAll<HTMLElement>(".menu-content, .api-content")
-            .forEach((target) => {
-                target.insertBefore(
-                    this.buildProjectHeaderDom(),
-                    target.firstChild
-                );
-            });
+        if (this.showRedocHeader) {
+            redocContainer
+                .querySelectorAll<HTMLElement>(".menu-content, .api-content")
+                .forEach((target) => {
+                    target.insertBefore(
+                        this.buildProjectHeaderDom(),
+                        target.firstChild
+                    );
+                });
+        }
 
         // Locale picker
         if (this.hasLocalePicker) {

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.html

@@ -15,6 +15,8 @@
         language={language}
         show-footer={enableFooter}
         origin={origin}
+        dev-center={devCenter}
+        brand={brand}
     >
         <doc-phase
             slot="doc-phase"

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.ts

@@ -44,6 +44,8 @@ export default class UnifiedContentLayout extends LightningElement {
     @api tocAriaLevel?: string;
     @api languages?: OptionWithLink[];
     @api language?: string;
+    @api devCenter: any = null;
+    @api brand: any = null;
 
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). */
     @api origin: string | null = null;