@salesforcedevs/dx-components 1.40.4 → 1.40.5-final-alpha

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

@@ -0,0 +1,467 @@
+export const TOPIC_VERSION_SESSION_KEY = "sfdocs-topic-version-selections";
+
+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)
+    );
+}
+
+/**
+ * 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).
+ */
+export function getTopicVersionKey(node: VersionedNode | undefined): string {
+    if (!node) {
+        return "";
+    }
+    if (node.name) {
+        return node.name;
+    }
+    const latestHref = node.versions?.[0]?.link?.href;
+    if (latestHref) {
+        return latestHref;
+    }
+    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) {
+        if (version.id === versions[0].id) {
+            continue;
+        }
+        const delta = getVersionPathDelta(
+            latestPath,
+            normalizePath(version.link?.href)
+        );
+        const stripped = delta && stripVersionPathDelta(hrefPath, delta);
+        if (stripped) {
+            return stripped;
+        }
+    }
+
+    return hrefPath;
+}
+
+function hrefMatchesVersion(
+    href: string | undefined,
+    version: TopicVersionOption,
+    versions: TopicVersionOption[]
+): boolean {
+    return hrefMatchesCurrentPage(applyVersionToHref(href, version, versions));
+}
+
+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
+): 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)];
+    return versions.find((version) => version.id === storedId) || versions[0];
+}

package/LICENSE

@@ -1,12 +0,0 @@
-Copyright (c) 2020, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.