@salesforcedevs/dx-components 1.41.0 → 1.42.0-final-test

package/src/modules/dxUtils/topicVersion/topicVersion.ts

@@ -0,0 +1,758 @@
+export const TOPIC_VERSION_SESSION_KEY = "sfdocs-topic-version-selections";
+export const DOCS_PATH_SEGMENT = "docs";
+// Locale position in the path segments: `/docs/<locale>` for Docs,
+// `/docs/<brand>/<locale>` for Guides/References.
+export const DOCS_LOCALE_SEGMENT_INDEX = 1;
+export const REFERENCES_LOCALE_SEGMENT_INDEX = 2;
+
+export type TopicVersionOption = {
+    id: string;
+    label: string;
+    deprecated?: boolean;
+    selected?: boolean;
+    link?: {
+        href?: string;
+        target?: string;
+    };
+    /** Topics authored under this version. Absent when the client only rewrites hrefs. */
+    // VersionedNode also points back here through `versions`.
+    // eslint-disable-next-line no-use-before-define
+    children?: VersionedNode[];
+};
+
+export type VersionedNode = {
+    name?: string;
+    label?: string;
+    key?: string;
+    link?: {
+        href?: string;
+        target?: string;
+    };
+    children?: VersionedNode[];
+    versions?: TopicVersionOption[];
+    /** Set on Redoc spec tiles after the docs layout decorates the TOC. */
+    showForwardArrow?: boolean;
+    /** Docs TOC topic type (`markdown` | `spec`). May be stripped after decoration. */
+    topicType?: string;
+};
+
+type VersionPathDelta = {
+    prefix: string;
+    inserted: string;
+};
+
+function isBrowser(): boolean {
+    return typeof window !== "undefined";
+}
+
+export function normalizePath(href?: string): string {
+    if (!href) {
+        return "";
+    }
+
+    try {
+        const url = href.startsWith("http")
+            ? new URL(href)
+            : new URL(
+                  href,
+                  isBrowser() ? window.location.origin : "http://localhost"
+              );
+        return url.pathname.replace(/\/$/, "") || "/";
+    } catch {
+        return href.replace(/\/$/, "");
+    }
+}
+
+export function hrefMatchesCurrentPage(href?: string): boolean {
+    if (!isBrowser()) {
+        return false;
+    }
+    return normalizePath(href) === normalizePath(window.location.pathname);
+}
+
+export function readTopicVersionSelections(): Record<string, string> {
+    if (!isBrowser() || !window.sessionStorage) {
+        return {};
+    }
+
+    try {
+        const raw = window.sessionStorage.getItem(TOPIC_VERSION_SESSION_KEY);
+        return raw ? JSON.parse(raw) : {};
+    } catch {
+        return {};
+    }
+}
+
+export function persistTopicVersion(
+    topicName: string,
+    versionId: string
+): void {
+    if (!topicName || !versionId || !isBrowser() || !window.sessionStorage) {
+        return;
+    }
+
+    const stored = readTopicVersionSelections();
+    stored[topicName] = versionId;
+    window.sessionStorage.setItem(
+        TOPIC_VERSION_SESSION_KEY,
+        JSON.stringify(stored)
+    );
+}
+
+/**
+ * Normalizes the path, then removes `locale` when it sits in the docs or
+ * references locale position, so every locale shares one session key.
+ */
+function stripLocaleFromPath(path: string, locale?: string): string {
+    const normalized = normalizePath(path);
+    const segments = normalized.split("/").filter(Boolean);
+    const normalizedLocale = locale?.toLowerCase();
+    if (!normalizedLocale || segments[0] !== DOCS_PATH_SEGMENT) {
+        return normalized;
+    }
+
+    const localeIndex = [
+        DOCS_LOCALE_SEGMENT_INDEX,
+        REFERENCES_LOCALE_SEGMENT_INDEX
+    ].find((index) => segments[index]?.toLowerCase() === normalizedLocale);
+    if (localeIndex === undefined) {
+        return normalized;
+    }
+
+    segments.splice(localeIndex, 1);
+    return `/${segments.join("/")}`;
+}
+
+/**
+ * Stable session key for a versioned topic. Parent-only sections have an empty
+ * `name`/`href`, so fall back to the latest switching URL (then the label).
+ * The locale is stripped so a selection carries across locales.
+ */
+export function getTopicVersionKey(
+    node: VersionedNode | undefined,
+    locale?: string
+): string {
+    if (!node) {
+        return "";
+    }
+    if (node.name) {
+        return stripLocaleFromPath(node.name, locale);
+    }
+    const latestHref = node.versions?.[0]?.link?.href;
+    if (latestHref) {
+        return stripLocaleFromPath(latestHref, locale);
+    }
+    return node.label || "";
+}
+
+/** Section header with children but no page of its own. */
+export function isParentOnlyTopic(node: VersionedNode | undefined): boolean {
+    if (!node) {
+        return false;
+    }
+    const ownHref = node.link?.href || node.name;
+    return !ownHref && !!node.children?.length;
+}
+
+function isSpecNode(node: VersionedNode): boolean {
+    return node.showForwardArrow === true || node.topicType === "spec";
+}
+
+/**
+ * First descendant that has a markdown page (own href/name). Specs (Redoc)
+ * and external links are skipped so parent-only sections land on the first
+ * markdown topic even when a spec is authored first in the TOC.
+ */
+export function firstContentNode(
+    node: VersionedNode | undefined
+): VersionedNode | undefined {
+    if (!node || node.link?.target === "_blank" || isSpecNode(node)) {
+        return undefined;
+    }
+    if (node.link?.href || node.name) {
+        return node;
+    }
+    for (const child of node.children || []) {
+        const found = firstContentNode(child);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+
+export function shouldShowTopicVersionPicker(
+    versions?: TopicVersionOption[],
+    showForwardArrow?: boolean
+): boolean {
+    return !showForwardArrow && Array.isArray(versions) && versions.length > 1;
+}
+
+/**
+ * Difference between a picker's latest switching URL and an older one.
+ *
+ * latest:  /docs/project/errors.html
+ * v1:      /docs/project/v1/errors.html
+ * → prefix `/docs/project/`, inserted `v1/`
+ */
+function getVersionPathDelta(
+    latestPath: string,
+    selectedPath: string
+): VersionPathDelta | undefined {
+    const latestDirEnd = latestPath.lastIndexOf("/") + 1;
+    if (latestDirEnd <= 0) {
+        return undefined;
+    }
+
+    const prefix = latestPath.slice(0, latestDirEnd);
+    const latestSlug = latestPath.slice(latestDirEnd);
+    if (!selectedPath.startsWith(prefix) || !latestSlug) {
+        return undefined;
+    }
+
+    const selectedAfterPrefix = selectedPath.slice(prefix.length);
+    if (!selectedAfterPrefix.endsWith(latestSlug)) {
+        return undefined;
+    }
+
+    const inserted = selectedAfterPrefix.slice(
+        0,
+        selectedAfterPrefix.length - latestSlug.length
+    );
+    if (!inserted) {
+        return undefined;
+    }
+
+    return { prefix, inserted };
+}
+
+function applyVersionPathDelta(
+    hrefPath: string,
+    delta: VersionPathDelta
+): string | undefined {
+    if (!hrefPath.startsWith(delta.prefix)) {
+        return undefined;
+    }
+
+    const rest = hrefPath.slice(delta.prefix.length);
+    if (rest.startsWith(delta.inserted)) {
+        return hrefPath;
+    }
+
+    return delta.prefix + delta.inserted + rest;
+}
+
+function stripVersionPathDelta(
+    hrefPath: string,
+    delta: VersionPathDelta
+): string | undefined {
+    if (!hrefPath.startsWith(delta.prefix)) {
+        return undefined;
+    }
+
+    const rest = hrefPath.slice(delta.prefix.length);
+    if (!rest.startsWith(delta.inserted)) {
+        return undefined;
+    }
+
+    return delta.prefix + rest.slice(delta.inserted.length);
+}
+
+/**
+ * Maps a canonical (latest) href onto another version using the picker's
+ * latest vs selected switching URLs as the template.
+ *
+ * latest parent:  /docs/project/errors.html
+ * v1 parent:      /docs/project/v1/errors.html
+ * latest child:   /docs/project/extra-child-a.html
+ * → v1 child:     /docs/project/v1/extra-child-a.html
+ */
+export function applyVersionToHref(
+    canonicalHref: string | undefined,
+    selectedVersion: TopicVersionOption | undefined,
+    versions?: TopicVersionOption[]
+): string | undefined {
+    if (!canonicalHref) {
+        return canonicalHref;
+    }
+    if (!selectedVersion || !versions?.length) {
+        return canonicalHref;
+    }
+
+    const latest = versions[0];
+    if (!latest || selectedVersion.id === latest.id) {
+        return canonicalHref;
+    }
+
+    const latestPath = normalizePath(latest.link?.href);
+    const selectedPath = normalizePath(selectedVersion.link?.href);
+    const hrefPath = normalizePath(canonicalHref);
+
+    if (!latestPath || !selectedPath || latestPath === selectedPath) {
+        return insertVersionBeforeSlug(canonicalHref, selectedVersion.id);
+    }
+
+    const delta = getVersionPathDelta(latestPath, selectedPath);
+    return (
+        (delta && applyVersionPathDelta(hrefPath, delta)) ||
+        insertVersionBeforeSlug(canonicalHref, selectedVersion.id)
+    );
+}
+
+function insertVersionBeforeSlug(href: string, versionId: string): string {
+    const path = normalizePath(href);
+    const lastSlash = path.lastIndexOf("/");
+    if (lastSlash <= 0 || !versionId) {
+        return href;
+    }
+    const dir = path.slice(0, lastSlash);
+    const slug = path.slice(lastSlash);
+    if (dir.endsWith(`/${versionId}`)) {
+        return path;
+    }
+    return `${dir}/${versionId}${slug}`;
+}
+
+export function toCanonicalHref(
+    href: string | undefined,
+    versions?: TopicVersionOption[]
+): string {
+    if (!href) {
+        return "";
+    }
+    if (!versions?.length) {
+        return normalizePath(href);
+    }
+
+    const latestPath = normalizePath(versions[0].link?.href);
+    const hrefPath = normalizePath(href);
+    if (!latestPath) {
+        return hrefPath;
+    }
+
+    for (const version of versions) {
+        // The latest is also served under `/<latestId>/`, so that form is
+        // stripped too.
+        const versionedPath =
+            version.id === versions[0].id
+                ? insertVersionBeforeSlug(latestPath, version.id)
+                : normalizePath(version.link?.href);
+        const delta = getVersionPathDelta(latestPath, versionedPath);
+        const stripped = delta && stripVersionPathDelta(hrefPath, delta);
+        if (stripped) {
+            return stripped;
+        }
+    }
+
+    return hrefPath;
+}
+
+function hrefMatchesVersion(
+    href: string | undefined,
+    version: TopicVersionOption,
+    versions: TopicVersionOption[]
+): boolean {
+    if (hrefMatchesCurrentPage(applyVersionToHref(href, version, versions))) {
+        return true;
+    }
+    // The server serves the latest under its canonical URL and also under
+    // `/<latestId>/`, so the versioned form must select the latest too.
+    return (
+        !!href &&
+        version.id === versions[0]?.id &&
+        hrefMatchesCurrentPage(insertVersionBeforeSlug(href, version.id))
+    );
+}
+
+export function collectSubtreeCanonicalHrefs(
+    node: VersionedNode,
+    includeSelf = true
+): string[] {
+    const hrefs: string[] = [];
+    const own = node.link?.href || node.name;
+    if (includeSelf && own) {
+        hrefs.push(own);
+    }
+    const collectChildHrefs = (children?: VersionedNode[]) => {
+        for (const child of children || []) {
+            if (child.versions?.length || child.link?.target === "_blank") {
+                continue;
+            }
+            hrefs.push(...collectSubtreeCanonicalHrefs(child));
+        }
+    };
+    collectChildHrefs(node.children);
+    // Latest topics already live on `children`, so skip versions[0]. Older
+    // versions can add topics that are not in that list. Those hrefs are
+    // version-specific (`/docs/project/v1/only-on-v1.html`), not canonical.
+    for (const version of (node.versions || []).slice(1)) {
+        collectChildHrefs(version.children);
+    }
+    return hrefs;
+}
+
+export function isCurrentPageInSubtree(
+    node: VersionedNode,
+    versions?: TopicVersionOption[]
+): boolean {
+    if (!isBrowser() || !versions?.length) {
+        return false;
+    }
+
+    return collectSubtreeCanonicalHrefs(node).some((href) =>
+        versions.some((version) => hrefMatchesVersion(href, version, versions))
+    );
+}
+
+/**
+ * True when the open URL is a latest-version path, or an older path whose
+ * switching URL shares the latest slug so the version segment can be removed.
+ * Parent-only topics whose versions open on different slugs leave the older
+ * URL unchanged, and the version directory is still in the path.
+ *
+ * `hrefPath` and `canonical` are the open page normalized once by the caller.
+ */
+function canMapCurrentPageToLatest(
+    hrefPath: string,
+    canonical: string,
+    versions: TopicVersionOption[]
+): boolean {
+    if (canonical !== hrefPath) {
+        return true;
+    }
+
+    const latest = versions[0];
+    if (!latest) {
+        return false;
+    }
+
+    return !versions.some((version) => {
+        if (version.id === latest.id) {
+            return false;
+        }
+        const selectedPath = normalizePath(version.link?.href);
+        return (
+            (!!selectedPath && hrefPath === selectedPath) ||
+            (!!version.id &&
+                (hrefPath.includes(`/${version.id}/`) ||
+                    hrefPath.endsWith(`/${version.id}`)))
+        );
+    });
+}
+
+function pageSlug(href: string | undefined): string {
+    const path = normalizePath(href);
+    const slash = path.lastIndexOf("/");
+    return slash >= 0 ? path.slice(slash + 1) : path;
+}
+
+/**
+ * The open page inside one version. Each version already carries its entry
+ * URL and its own child hrefs. Match the slug, then use the entry URL when
+ * that page is absent from the version.
+ */
+function hrefInVersion(
+    version: TopicVersionOption,
+    slug: string
+): string | undefined {
+    if (!slug) {
+        return undefined;
+    }
+    const entry = version.link?.href;
+    if (entry && pageSlug(entry) === slug) {
+        return normalizePath(entry);
+    }
+    return findChildHref(version.children, slug);
+}
+
+function findChildHref(
+    children: VersionedNode[] | undefined,
+    slug: string
+): string | undefined {
+    for (const child of children || []) {
+        if (child.versions?.length || child.link?.target === "_blank") {
+            continue;
+        }
+        const href = child.link?.href || child.name;
+        if (href && pageSlug(href) === slug) {
+            return normalizePath(href);
+        }
+        const nested = findChildHref(child.children, slug);
+        if (nested) {
+            return nested;
+        }
+    }
+    return undefined;
+}
+
+function walkVersionChildren(
+    children: VersionedNode[] | undefined,
+    visit: (node: VersionedNode) => boolean
+): boolean {
+    for (const child of children || []) {
+        if (child.versions?.length || child.link?.target === "_blank") {
+            continue;
+        }
+        if (visit(child) || walkVersionChildren(child.children, visit)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+function findNodeBySlug(
+    children: VersionedNode[] | undefined,
+    slug: string
+): VersionedNode | undefined {
+    let found: VersionedNode | undefined;
+    walkVersionChildren(children, (node) => {
+        const href = node.link?.href || node.name;
+        if (href && pageSlug(href) === slug) {
+            found = node;
+            return true;
+        }
+        return false;
+    });
+    return found;
+}
+
+function specNodes(children: VersionedNode[] | undefined): VersionedNode[] {
+    const specs: VersionedNode[] = [];
+    walkVersionChildren(children, (node) => {
+        if (isSpecNode(node)) {
+            specs.push(node);
+        }
+        return false;
+    });
+    return specs;
+}
+
+function nodeHref(node: VersionedNode | undefined): string | undefined {
+    const href = node?.link?.href || node?.name;
+    return href ? normalizePath(href) : undefined;
+}
+
+/**
+ * Spec in `version` that corresponds to the open spec.
+ * Same title first. When each version has exactly one spec, that spec is
+ * the counterpart even if the title changed. Returns undefined for a
+ * markdown page so the existing slug rewrite stays in place.
+ */
+function specCounterpartHref(
+    version: TopicVersionOption,
+    openNode: VersionedNode | undefined,
+    openVersion: TopicVersionOption | undefined
+): string | undefined {
+    if (!openNode || !isSpecNode(openNode) || !version.children) {
+        return undefined;
+    }
+    const specs = specNodes(version.children);
+    const sameTitle = specs.find(
+        (spec) => spec.label && spec.label === openNode.label
+    );
+    if (sameTitle) {
+        return nodeHref(sameTitle);
+    }
+    const openSpecs = specNodes(openVersion?.children);
+    if (specs.length === 1 && openSpecs.length === 1) {
+        return nodeHref(specs[0]);
+    }
+    return undefined;
+}
+
+/**
+ * Href for one picker option, or for View Latest.
+ * Same-slug switching URLs still rewrite the open page onto that version.
+ * When those slugs differ, use the target version's own copy of this page.
+ * A spec whose file name changed uses that version's spec instead of a
+ * rewritten slug. A spec the target version does not have keeps its slug
+ * on that version, so the missing page 404s.
+ *
+ * The canonical path and slug depend only on the open page, so they are
+ * computed once and reused for every version.
+ */
+function hrefForVersionSwitch(
+    pathname: string,
+    versions: TopicVersionOption[]
+): (version: TopicVersionOption) => string | undefined {
+    const hrefPath = normalizePath(pathname);
+    const canonical = toCanonicalHref(pathname, versions);
+    const canMap = canMapCurrentPageToLatest(hrefPath, canonical, versions);
+    const slug = pageSlug(pathname);
+    const openVersion = versions.find(
+        (version) => version.children && findNodeBySlug(version.children, slug)
+    );
+    const openNode = openVersion
+        ? findNodeBySlug(openVersion.children, slug)
+        : undefined;
+
+    return (version) => {
+        const bySlug = hrefInVersion(version, slug);
+        if (bySlug) {
+            return bySlug;
+        }
+
+        // A renamed spec is a real page in this version. A spec with no
+        // counterpart keeps its slug under this version so the request 404s
+        // instead of opening the spec the reader is already on.
+        const counterpart = specCounterpartHref(version, openNode, openVersion);
+        if (counterpart) {
+            return counterpart;
+        }
+        if (openNode && isSpecNode(openNode)) {
+            return applyVersionToHref(canonical, version, versions);
+        }
+
+        const latest = versions[0];
+        const onLatest = !latest || version.id === latest.id;
+        if (canMap && (onLatest || sharesSlugDelta(latest, version))) {
+            const rewritten =
+                applyVersionToHref(canonical, version, versions) ||
+                version.link?.href;
+            if (rewritten) {
+                return rewritten;
+            }
+        }
+        return version.link?.href;
+    };
+}
+
+/** True when this version's switching URL differs from latest by a version segment. */
+function sharesSlugDelta(
+    latest: TopicVersionOption | undefined,
+    version: TopicVersionOption
+): boolean {
+    const latestPath = normalizePath(latest?.link?.href);
+    const selectedPath = normalizePath(version.link?.href);
+    return !!(
+        latestPath &&
+        selectedPath &&
+        getVersionPathDelta(latestPath, selectedPath)
+    );
+}
+
+/**
+ * Picker option hrefs. When the current page is this topic or a descendant,
+ * each option points at that same topic in the chosen version so the child
+ * stays selected. Otherwise keep the backend switching URL (parent page, or
+ * first content child for parent-only sections).
+ */
+export function getVersionPickerOptions(
+    node: VersionedNode | undefined
+): TopicVersionOption[] | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length) {
+        return versions;
+    }
+    if (!isCurrentPageInSubtree(node, versions)) {
+        return versions;
+    }
+
+    const hrefForVersion = hrefForVersionSwitch(
+        window.location.pathname,
+        versions
+    );
+    return versions.map((version) => ({
+        ...version,
+        link: {
+            ...version.link,
+            href: hrefForVersion(version)
+        }
+    }));
+}
+
+/**
+ * Version whose page (or a descendant of it) is the current URL.
+ * Ignores the session-stored picker selection, which can remember an older
+ * version while the reader is still on the latest page.
+ */
+export function versionForCurrentPage(
+    node: VersionedNode | undefined
+): TopicVersionOption | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length || !isBrowser()) {
+        return undefined;
+    }
+
+    const hrefs = collectSubtreeCanonicalHrefs(node);
+    const matches = (version: TopicVersionOption) =>
+        hrefMatchesCurrentPage(version.link?.href) ||
+        hrefs.some((href) => hrefMatchesVersion(href, version, versions));
+
+    // Older versions first. A rewritten child URL, and a version-specific href
+    // from an older version's children, also match latest (that comparison
+    // leaves the path unchanged). Checking older versions first keeps those
+    // pages on the older version.
+    const older = versions.find(
+        (version) => version.id !== versions[0].id && matches(version)
+    );
+    if (older) {
+        return older;
+    }
+
+    return matches(versions[0]) ? versions[0] : undefined;
+}
+
+/**
+ * Deepest versioned topic that contains the current page, with the version
+ * the URL selects. Nested versioned topics own their pages.
+ */
+export function findTopicVersionForCurrentPage(
+    nodes: VersionedNode[] | undefined | null
+): { node: VersionedNode; version: TopicVersionOption } | undefined {
+    let match: { node: VersionedNode; version: TopicVersionOption } | undefined;
+    const traverseNodes = (list?: VersionedNode[] | null) => {
+        for (const node of list || []) {
+            const version = versionForCurrentPage(node);
+            if (version) {
+                match = { node, version };
+            }
+            traverseNodes(node.children);
+            // Latest children are already on node.children.
+            for (const versionOption of (node.versions || []).slice(1)) {
+                traverseNodes(versionOption.children);
+            }
+        }
+    };
+    traverseNodes(nodes);
+    return match;
+}
+
+/**
+ * Current page in the latest topic version. Uses the latest copy of this
+ * page when the server sent it, and the latest entry URL otherwise.
+ */
+export function latestHrefForCurrentPage(
+    versions: TopicVersionOption[] | undefined
+): string | undefined {
+    const latest = versions?.[0];
+    if (!latest) {
+        return undefined;
+    }
+    if (!isBrowser()) {
+        return latest.link?.href;
+    }
+
+    return hrefForVersionSwitch(window.location.pathname, versions)(latest);
+}
+
+export function resolveSelectedVersion(
+    node: VersionedNode | undefined,
+    locale?: string
+): TopicVersionOption | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length) {
+        return undefined;
+    }
+
+    // The open page wins, including a canonical child opened from "View Latest".
+    // Session is only for a picker whose topic is not the current page.
+    const fromUrl = versionForCurrentPage(node);
+    if (fromUrl) {
+        return fromUrl;
+    }
+
+    const storedId =
+        readTopicVersionSelections()[getTopicVersionKey(node, locale)];
+    return versions.find((version) => version.id === storedId) || versions[0];
+}