@salesforcedevs/dx-components 1.40.7-tlv-alpha → 1.40.8

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

@@ -1,511 +0,0 @@
-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;
-    };
-};
-
-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);
-    }
-    for (const child of node.children || []) {
-        if (child.versions?.length || child.link?.target === "_blank") {
-            continue;
-        }
-        hrefs.push(...collectSubtreeCanonicalHrefs(child));
-    }
-    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))
-    );
-}
-
-/**
- * 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 canonical = toCanonicalHref(window.location.pathname, versions);
-    return versions.map((version) => ({
-        ...version,
-        link: {
-            ...version.link,
-            href:
-                applyVersionToHref(canonical, version, versions) ||
-                version.link?.href
-        }
-    }));
-}
-
-/**
- * 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 so a rewritten child URL is not mistaken for latest.
-    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 walk = (list?: VersionedNode[] | null) => {
-        for (const node of list || []) {
-            const version = versionForCurrentPage(node);
-            if (version) {
-                match = { node, version };
-            }
-            walk(node.children);
-        }
-    };
-    walk(nodes);
-    return match;
-}
-
-/**
- * Current page rewritten onto the latest topic version. Falls back to the
- * latest switching URL when the path delta cannot be applied.
- */
-export function latestHrefForCurrentPage(
-    versions: TopicVersionOption[] | undefined
-): string | undefined {
-    const latest = versions?.[0];
-    if (!latest) {
-        return undefined;
-    }
-    if (!isBrowser()) {
-        return latest.link?.href;
-    }
-
-    const canonical = toCanonicalHref(window.location.pathname, versions);
-    return applyVersionToHref(canonical, latest, versions) || latest.link?.href;
-}
-
-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];
-}