@salesforcedevs/docs-components 1.17.5 → 1.17.6-redoc1

package/lwc.config.json

@@ -20,6 +20,7 @@
         "doc/headingAnchor",
         "doc/overview",
         "doc/phase",
+        "doc/docReference",
         "doc/specificationContent",
         "doc/versionPicker",
         "doc/xmlContent",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.17.5",
+    "version": "1.17.6-redoc1",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -25,5 +25,5 @@
         "@types/lodash.orderby": "4.6.9",
         "@types/lodash.uniqby": "4.7.9"
     },
-    "gitHead": "5aaacff2c6b494563ccf0d8a08ee809f5c1226b7"
+    "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
 }

package/src/modules/doc/docReference/docReference.css

@@ -0,0 +1,52 @@
+@import "docHelpers/amfStyle";
+
+:host {
+    --reference-container-margin-top: var(--dx-g-spacing-sm);
+    --api-documentation-margin-top: var(--dx-g-spacing-3xl);
+}
+
+/**
+ * 1. We need to scroll to top from the tablet size as side nav bar and content in side by side from tablet size
+ * 2. Consider global nav height, doc header height and content margins to scroll to the right position
+ */
+
+@media screen and (min-width: 769px) {
+    .redoc-container {
+        scroll-margin-top: calc(
+            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+                var(--reference-container-margin-top) +
+                var(--api-documentation-margin-top)
+        );
+    }
+}
+
+.redoc-container {
+    width: 100%;
+    height: 100%;
+    /* Ensure Redoc content is scrollable within the content layout */
+    overflow-y: auto;
+}
+
+/* Loading state styles */
+.loading-container {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    height: 200px;
+    font-size: 16px;
+    color: var(--dx-g-color-text-secondary);
+}
+
+/* Error state styles */
+.error-container {
+    padding: 20px;
+    background-color: var(--dx-g-color-background-error);
+    border: 1px solid var(--dx-g-color-border-error);
+    border-radius: 4px;
+    margin: 20px 0;
+}
+
+.error-message {
+    color: var(--dx-g-color-text-error);
+    font-weight: 600;
+}

package/src/modules/doc/docReference/docReference.html

@@ -0,0 +1,62 @@
+<template>
+    <doc-content-layout
+        lwc:if={isVersionFetched}
+        use-old-sidebar={useOldSidebar}
+        class="content-type content-type-reference"
+        coveo-organization-id={coveoOrganizationId}
+        coveo-public-access-token={coveoPublicAccessToken}
+        coveo-analytics-token={coveoAnalyticsToken}
+        coveo-search-hub={coveoSearchHub}
+        coveo-advanced-query-config={coveoAdvancedQueryConfig}
+        breadcrumbs={breadcrumbs}
+        sidebar-header={sidebarHeader}
+        sidebar-value={selectedSidebarValue}
+        sidebar-content={navigation}
+        onselect={onNavSelect}
+        onexpandcollapse={onExpandCollapse}
+        toc-title={tocTitle}
+        toc-options={tocOptions}
+        enable-slot-change="true"
+        languages={languages}
+        language={language}
+        show-footer={enableFooter}
+    >
+        <doc-phase
+            slot="doc-phase"
+            lwc:if={docPhaseInfo}
+            doc-phase-info={docPhaseInfo}
+        ></doc-phase>
+        <doc-phase
+            slot="version-banner"
+            lwc:if={showVersionBanner}
+            doc-phase-info={oldVersionInfo}
+            icon-name="warning"
+            dismissible="true"
+            ondismissphase={handleDismissVersionBanner}
+        ></doc-phase>
+        <div lwc:if={isVersionEnabled} slot="sidebar-header">
+            <doc-version-picker
+                onchange={handleVersionChange}
+                data-type="version"
+                versions={versions}
+                selected-version={selectedVersion}
+                latest-version={latestVersion}
+            ></doc-version-picker>
+        </div>
+        <template lwc:if={showSpecBasedReference}>
+            <div class="container">
+                <div class="api-documentation">
+                    <!-- Replace doc-amf-topic with Redoc container -->
+                    <div 
+                        class="redoc-container" 
+                        lwc:dom="manual"
+                        data-redoc-container
+                    ></div>
+                </div>
+            </div>
+        </template>
+        <template lwc:else>
+            <slot></slot>
+        </template>
+    </doc-content-layout>
+</template>

package/src/modules/doc/docReference/docReference.ts

@@ -0,0 +1,1090 @@
+import { LightningElement, api, track } from "lwc";
+import { normalizeBoolean, toJson } from "dxUtils/normalizers";
+import type { OptionWithLink } from "typings/custom";
+import type {
+    AmfConfig,
+    ReferenceVersion,
+    ReferenceSetConfig,
+    ParsedMarkdownTopic
+} from "../amfReference/types";
+
+import {
+    REFERENCE_TYPES,
+    oldReferenceIdNewReferenceIdMap
+} from "../amfReference/constants";
+import { restoreScroll } from "dx/scrollManager";
+import { DocPhaseInfo } from "typings/custom";
+import { logCoveoPageView, oldVersionDocInfo } from "docUtils/utils";
+import type { RedocNavigationItem, RedocSidebarData } from "./types";
+import "./types"; // Import types to ensure global declarations are loaded
+
+type NavigationItem = {
+    label: string;
+    name: string;
+    isExpanded: boolean;
+    children: RedocNavigationItem[];
+    isChildrenLoading: boolean;
+};
+
+export default class DocReference extends LightningElement {
+    @api breadcrumbs: string | null = null;
+    @api sidebarHeader!: string;
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoAnalyticsToken!: string;
+    @api coveoSearchHub!: string;
+    @api useOldSidebar: boolean = false;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api languages!: OptionWithLink[];
+    @api language!: string;
+    @api hideFooter = false;
+    @track navigation = [] as NavigationItem[];
+    @track versions: Array<ReferenceVersion> = [];
+    @track showVersionBanner = false;
+    @track _coveoAdvancedQueryConfig!: { [key: string]: any };
+
+    get isVersionEnabled(): boolean {
+        return !!this._referenceSetConfig?.versions?.length;
+    }
+
+    /**
+     * Gives if the currently selected reference is spec based or not
+     */
+    get showSpecBasedReference(): boolean {
+        return this.isSpecBasedReference(this._currentReferenceId);
+    }
+
+    @api
+    get referenceSetConfig(): ReferenceSetConfig {
+        return this._referenceSetConfig;
+    }
+
+    set referenceSetConfig(value: ReferenceSetConfig) {
+        // No change, do nothing.
+        if (value === this._referenceSetConfig) {
+            return;
+        }
+
+        try {
+            const refConfig =
+                typeof value === "string" ? JSON.parse(value) : value;
+            if (!(<ReferenceSetConfig>refConfig).versions) {
+                return;
+            }
+            this._referenceSetConfig = refConfig;
+        } catch (e) {
+            this._referenceSetConfig = {
+                refList: [],
+                versions: []
+            };
+        }
+
+        this._amfConfigList = this._referenceSetConfig.refList || [];
+
+        this._amfConfigList.forEach((amfConfig) => {
+            this._amfConfigMap.set(amfConfig.id, amfConfig);
+        });
+
+        if (this._amfConfigList.length > 0) {
+            this._currentReferenceId =
+                this._referenceSetConfig.refId || this._amfConfigList[0].id;
+        }
+
+        if (this.isVersionEnabled) {
+            const selectedVersion = this.getSelectedVersion();
+
+            if (this.isSpecBasedReference(this._currentReferenceId)) {
+                this.versions = this.getVersions();
+            }
+            this.selectedVersion = selectedVersion;
+            if (this.isSpecBasedReference(this._currentReferenceId)) {
+                this.isVersionFetched = true;
+                if (this.oldVersionInfo) {
+                    this.showVersionBanner = true;
+                } else {
+                    this.latestVersion = true;
+                }
+            }
+        } else {
+            this.isVersionFetched = true;
+        }
+
+        // This is to check if the url is hash based and redirect if needed
+        const redirectUrl = this.getHashBasedRedirectUrl();
+        if (redirectUrl) {
+            window.location.href = redirectUrl;
+        } else {
+            this.updateConfigInView();
+        }
+    }
+
+    @api
+    get docPhaseInfo(): string | null {
+        return this.selectedReferenceDocPhase || null;
+    }
+
+    set docPhaseInfo(value: string) {
+        if (value) {
+            this.isParentLevelDocPhaseEnabled = true;
+            this.selectedReferenceDocPhase = value;
+        }
+    }
+
+    @api
+    get expandChildren() {
+        return this._expandChildren;
+    }
+
+    set expandChildren(value) {
+        this._expandChildren = normalizeBoolean(value);
+    }
+
+    @api
+    get coveoAdvancedQueryConfig(): { [key: string]: any } {
+        const coveoConfig = this._coveoAdvancedQueryConfig;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                const version = this.selectedVersion.id.replace("v", "");
+                coveoConfig.version = version;
+                this._coveoAdvancedQueryConfig = coveoConfig;
+            }
+        }
+        return this._coveoAdvancedQueryConfig;
+    }
+
+    set coveoAdvancedQueryConfig(config) {
+        this._coveoAdvancedQueryConfig = toJson(config);
+    }
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+
+    // model
+    protected _amfConfigList: AmfConfig[] = [];
+    protected _amfConfigMap: Map<string, AmfConfig> = new Map();
+    protected _referenceSetConfig!: ReferenceSetConfig;
+    protected _currentReferenceId = "";
+
+    protected parentReferenceUrls = [] as string[];
+    protected redocFetchPromiseMap = {} as any;
+    protected selectedSidebarValue: string | undefined = undefined;
+    protected selectedVersion: ReferenceVersion | null = null;
+
+    // Redoc-specific properties
+    private redocContainers: Map<string, Element> = new Map();
+    private redocSidebarData: Map<string, RedocSidebarData> = new Map();
+    private currentActiveSection: string | null = null;
+    private isProgrammaticScroll = false;
+    private scrollTimeout: number | null = null;
+
+    private hasRendered = false;
+    private isParentLevelDocPhaseEnabled = false;
+    private selectedReferenceDocPhase?: string | null = null;
+    private _expandChildren?: boolean = false;
+    private isVersionFetched = false;
+    private latestVersion = false;
+
+    private readonly docsReferenceUrlSessionKey: string = "docsReferenceUrl";
+
+    _boundOnApiNavigationChanged;
+    _boundUpdateSelectedItemFromUrlQuery;
+    _boundHandleRedocScroll;
+
+    constructor() {
+        super();
+
+        this._boundOnApiNavigationChanged =
+            this.onApiNavigationChanged.bind(this);
+        this._boundUpdateSelectedItemFromUrlQuery =
+            this.updateSelectedItemFromUrlQuery.bind(this);
+        this._boundHandleRedocScroll = 
+            this.handleRedocScroll.bind(this);
+    }
+
+    connectedCallback(): void {
+        this.addEventListener(
+            "api-navigation-selection-changed",
+            this._boundOnApiNavigationChanged
+        );
+        window.addEventListener(
+            "popstate",
+            this._boundUpdateSelectedItemFromUrlQuery
+        );
+        window.addEventListener(
+            "hashchange", 
+            this.handleHashNavigation.bind(this)
+        );
+    }
+
+    disconnectedCallback(): void {
+        this.removeEventListener(
+            "api-navigation-selection-changed",
+            this._boundOnApiNavigationChanged
+        );
+        window.removeEventListener(
+            "popstate",
+            this._boundUpdateSelectedItemFromUrlQuery
+        );
+        window.removeEventListener(
+            "hashchange",
+            this.handleHashNavigation.bind(this)
+        );
+        if (this.scrollTimeout) {
+            clearTimeout(this.scrollTimeout);
+        }
+    }
+
+    renderedCallback(): void {
+        if (!this.hasRendered) {
+            this.hasRendered = true;
+            if (this._amfConfigList && this._amfConfigList.length) {
+                this.updateView();
+            }
+        }
+    }
+
+    /**
+     * Check if the URL hash to see whether this is one we want to redirect
+     */
+    private getHashBasedRedirectUrl(): string | undefined {
+        const { hash } = window.location;
+        let hashBasedRedirectUrl = "";
+        if (hash) {
+            const strippedHash = hash.startsWith("#") ? hash.slice(1) : hash;
+            const strippedHashItems = strippedHash
+                ? strippedHash.split(":")
+                : [];
+            if (strippedHashItems.length) {
+                const referenceId = strippedHashItems[0];
+                const section = strippedHashItems[1];
+                const updatedReferenceId =
+                    oldReferenceIdNewReferenceIdMap[referenceId];
+                const newReferenceId = updatedReferenceId || referenceId;
+                const referenceItemConfig =
+                    this.getAmfConfigWithId(newReferenceId);
+                if (referenceItemConfig) {
+                    hashBasedRedirectUrl = `${referenceItemConfig.href}#${section}`;
+                }
+            }
+        }
+        return hashBasedRedirectUrl;
+    }
+
+    /**
+     * @param referenceId
+     * @returns AMFConfig with given reference Id
+     */
+    private getAmfConfigWithId(referenceId: string): AmfConfig | undefined {
+        return this._amfConfigMap.get(referenceId);
+    }
+
+    /**
+     * @param referenceId
+     * @returns if the reference is spec based one or not with given referenceId.
+     */
+    private isSpecBasedReference(referenceId: string): boolean {
+        const selectedReference = this.getAmfConfigWithId(referenceId);
+        return selectedReference
+            ? selectedReference.referenceType !== REFERENCE_TYPES.markdown
+            : false;
+    }
+
+    /**
+     * @param url
+     * @returns reference Id from url path / selected sidebar item.
+     */
+    private getReferenceIdFromUrl(url: string): string {
+        let referenceId = "";
+        const urlItems = url.split("/references/");
+        if (urlItems.length > 1) {
+            const rightSidePart = urlItems[1];
+            const slashSeparatorItems = rightSidePart.split("/");
+            const querySeparatorItems = slashSeparatorItems[0].split("?");
+            referenceId = querySeparatorItems[0];
+        }
+        return referenceId;
+    }
+
+    private get oldVersionInfo(): DocPhaseInfo | null {
+        let info = null;
+        if (this.versions.length > 1 && this.selectedVersion) {
+            const currentGAVersionRef = this.versions[0];
+            if (this.selectedVersion.id !== currentGAVersionRef.id) {
+                info = oldVersionDocInfo(currentGAVersionRef.link.href);
+            }
+        }
+        return info;
+    }
+
+    /**
+     * @returns versions to be shown in the dropdown
+     */
+    private getVersions(): Array<ReferenceVersion> {
+        const allVersions = this._referenceSetConfig.versions;
+        if (!this.isSpecBasedReference(this._currentReferenceId)) {
+            // For markdown references, handle differently if needed
+            // For now, return as-is since we're focusing on spec-based
+        }
+        return allVersions;
+    }
+
+    /**
+     * Returns the selected version or the first available version.
+     */
+    private getSelectedVersion(): ReferenceVersion | null {
+        const versions = this._referenceSetConfig?.versions || [];
+        const selectedVersion = versions.find(
+            (v: ReferenceVersion) => v.selected
+        );
+        return selectedVersion || (versions.length && versions[0]) || null;
+    }
+
+    private updateConfigInView(): void {
+        if (this._amfConfigList && this._amfConfigList.length) {
+            this.populateReferenceItems();
+            if (this.hasRendered) {
+                this.updateView();
+            }
+        }
+    }
+
+    /**
+     * Fetch spec and generate Redoc structure
+     */
+    private async fetchSpec(amfConfig: AmfConfig): Promise<RedocSidebarData | null> {
+        const { amf } = amfConfig;
+        try {
+            // Load Redoc sidebar structure
+            if (window.Redoc?.getSpecStructure && amf) {
+                return await window.Redoc.getSpecStructure(amf);
+            }
+            return null;
+        } catch (error) {
+            console.error('Failed to fetch spec structure:', error);
+            return null;
+        }
+    }
+
+    /**
+     * Populates reference Items and assigns it to navigation for sidebar
+     */
+    private populateReferenceItems(): void {
+        const navOrder = [] as NavigationItem[];
+        for (const [index, amfConfig] of this._amfConfigList.entries()) {
+            let navItemChildren = [] as RedocNavigationItem[];
+            let isChildrenLoading = false;
+            
+            if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+                if (amfConfig.isSelected) {
+                    const redocPromise = this.fetchSpec(amfConfig).then(
+                        (redocData) => {
+                            if (redocData) {
+                                this.redocSidebarData.set(amfConfig.id, redocData);
+                                this.assignNavigationItemsFromRedoc(amfConfig, index);
+                            }
+                        }
+                    );
+                    this.redocFetchPromiseMap[amfConfig.id] = redocPromise;
+                }
+                isChildrenLoading = true;
+            } else {
+                const isExpandChildrenEnabled = this.isExpandChildrenEnabled(
+                    amfConfig.id
+                );
+                // check whether we should expand all the child nodes, this is required for Coveo to crawl.
+                if (isExpandChildrenEnabled && amfConfig.topic) {
+                    this.expandChildrenForMarkdownReferences(
+                        amfConfig.topic.children
+                    );
+                }
+                // Convert markdown topics to RedocNavigationItem format
+                navItemChildren = this.convertMarkdownTopicsToNavItems(
+                    amfConfig.topic?.children || []
+                );
+            }
+            
+            navOrder[index] = {
+                label: amfConfig.title,
+                name: amfConfig.href,
+                isExpanded:
+                    amfConfig.isSelected ||
+                    this.isExpandChildrenEnabled(amfConfig.id),
+                children: navItemChildren,
+                isChildrenLoading
+            };
+            this.parentReferenceUrls.push(amfConfig.href);
+        }
+        this.navigation = navOrder;
+    }
+
+    /**
+     * Returns a boolean indicating whether the children should be expanded or not.
+     */
+    private isExpandChildrenEnabled(referenceId: string): boolean {
+        return (
+            !!this.expandChildren && this._currentReferenceId === referenceId
+        );
+    }
+
+    /**
+     * Assigns Navigation Items to dx-sidebar from the Redoc structure.
+     */
+    private assignNavigationItemsFromRedoc(
+        amfConfig: AmfConfig,
+        amfIdx: number
+    ): void {
+        const referenceId = amfConfig.id;
+        const redocData = this.redocSidebarData.get(referenceId);
+        
+        if (!redocData) {
+            return;
+        }
+
+        const children: RedocNavigationItem[] = this.convertRedocItemsToNavItems(
+            redocData.items,
+            amfConfig.href
+        );
+
+        this.navigation[amfIdx] = {
+            ...this.navigation[amfIdx],
+            children,
+            isChildrenLoading: false
+        };
+        this.navigation = [...this.navigation];
+    }
+
+    /**
+     * Convert Redoc sidebar items to navigation items with proper hash URLs
+     */
+    private convertRedocItemsToNavItems(
+        redocItems: RedocNavigationItem[],
+        baseHref: string
+    ): RedocNavigationItem[] {
+        return redocItems.map(item => ({
+            label: item.label,
+            name: `${baseHref}#${item.id}`, // Hash-based navigation
+            id: item.id,
+            children: item.children ? 
+                this.convertRedocItemsToNavItems(item.children, baseHref) : 
+                undefined
+        }));
+    }
+
+    /**
+     * Find a Redoc navigation item by its ID
+     */
+    private findRedocItemById(
+        items: RedocNavigationItem[], 
+        targetId: string
+    ): RedocNavigationItem | null {
+        for (const item of items) {
+            if (item.id === targetId) {
+                return item;
+            }
+            if (item.children) {
+                const found = this.findRedocItemById(item.children, targetId);
+                if (found) {
+                    return found;
+                }
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Convert markdown topics to RedocNavigationItem format for unified sidebar handling
+     */
+    private convertMarkdownTopicsToNavItems(
+        markdownTopics: ParsedMarkdownTopic[]
+    ): RedocNavigationItem[] {
+        return markdownTopics.map(topic => ({
+            label: topic.label,
+            name: topic.link?.href || '',
+            id: topic.label.toLowerCase().replace(/\s+/g, '-'),
+            children: topic.children ? 
+                this.convertMarkdownTopicsToNavItems(topic.children) : 
+                undefined
+        }));
+    }
+
+    /**
+     * Update the DOM on the first load
+     */
+    updateView(): void {
+        const referenceId = this._currentReferenceId;
+        const specBasedReference = this.isSpecBasedReference(referenceId);
+        
+        if (specBasedReference) {
+            // Wait till the spec is loaded.
+            this.redocFetchPromiseMap[referenceId].then(() => {
+                this.loadSpecReferenceContent(referenceId);
+                this.updateDocPhase();
+                
+                // Handle hash navigation after content is loaded
+                setTimeout(() => {
+                    this.handleHashNavigation();
+                }, 1000);
+            });
+        } else {
+            // Handle markdown references if needed
+            this.loadMarkdownBasedReference();
+        }
+    }
+
+    /**
+     * Load and render Redoc content for the selected reference
+     */
+    private async loadSpecReferenceContent(referenceId: string): Promise<void> {
+        const amfConfig = this.getAmfConfigWithId(referenceId);
+        if (!amfConfig) {
+            return;
+        }
+
+        const redocContainer = this.template.querySelector('.redoc-container');
+        if (!redocContainer) {
+            return;
+        }
+
+        try {
+            // Clear existing content
+            while (redocContainer.firstChild) {
+                redocContainer.firstChild.remove();
+            }
+            
+            // Initialize Redoc
+            if (window.Redoc && amfConfig.amf) {
+                await window.Redoc.init(amfConfig.amf, {
+                    expandResponses: '200,400',
+                    scrollYOffset: 73,
+                    sidebar: false
+                }, redocContainer);
+                
+                // Set up scroll sync after Redoc is loaded
+                setTimeout(() => {
+                    this.setupScrollSync();
+                }, 2000);
+            }
+        } catch (error) {
+            console.error('Failed to load Redoc:', error);
+            
+            // Create error elements properly without innerHTML
+            const errorContainer = document.createElement('div');
+            errorContainer.className = 'error-container';
+            
+            const errorMessage = document.createElement('div');
+            errorMessage.className = 'error-message';
+            errorMessage.textContent = 'Failed to load API documentation';
+            
+            errorContainer.appendChild(errorMessage);
+            redocContainer.appendChild(errorContainer);
+        }
+    }
+
+    /**
+     * Set up scroll synchronization between sidebar and Redoc content
+     */
+    private setupScrollSync(): void {
+        const contentArea = this.template.querySelector('.api-documentation');
+        if (!contentArea) {
+            return;
+        }
+
+        contentArea.addEventListener('scroll', this._boundHandleRedocScroll);
+    }
+
+    /**
+     * Handle scroll events in Redoc content to update active sidebar item
+     */
+    private handleRedocScroll(): void {
+        if (this.isProgrammaticScroll) {
+            return;
+        }
+
+        if (this.scrollTimeout) {
+            clearTimeout(this.scrollTimeout);
+        }
+
+        this.scrollTimeout = window.setTimeout(() => {
+            this.updateActiveSidebarItemFromScroll();
+        }, 50);
+    }
+
+    /**
+     * Update active sidebar item based on scroll position
+     */
+    private updateActiveSidebarItemFromScroll(): void {
+        const redocSections = this.template.querySelectorAll('[data-section-id]');
+        if (redocSections.length === 0) {
+            return;
+        }
+
+        let activeSection: string | null = null;
+        let bestScore = -Infinity;
+        const viewportHeight = window.innerHeight;
+        const scrollThreshold = viewportHeight * 0.3;
+
+        redocSections.forEach(section => {
+            const sectionId = section.getAttribute('data-section-id');
+            if (!sectionId) {
+                return;
+            }
+
+            const rect = section.getBoundingClientRect();
+            const visibleHeight = Math.max(0, Math.min(viewportHeight, rect.bottom) - Math.max(0, rect.top));
+            const visibilityPercentage = visibleHeight / section.clientHeight;
+
+            let score = 0;
+            if (visibilityPercentage > 0.05) {
+                score += visibilityPercentage * 100;
+                
+                if (rect.top <= scrollThreshold && rect.top >= -scrollThreshold) {
+                    score += 100;
+                }
+            }
+
+            if (score > bestScore) {
+                bestScore = score;
+                activeSection = sectionId;
+            }
+        });
+
+        if (activeSection && activeSection !== this.currentActiveSection) {
+            this.currentActiveSection = activeSection;
+            this.updateSelectedSidebarItem(activeSection);
+            
+            // Update URL hash
+            if (window.location.hash !== `#${activeSection}`) {
+                window.history.replaceState(null, '', `#${activeSection}`);
+            }
+        }
+    }
+
+    /**
+     * Update the selected sidebar item based on section ID
+     */
+    private updateSelectedSidebarItem(sectionId: string): void {
+        const currentRef = this.getAmfConfigWithId(this._currentReferenceId);
+        if (currentRef) {
+            this.selectedSidebarValue = `${currentRef.href}#${sectionId}`;
+        }
+    }
+
+    /**
+     * Handle hash navigation from URL changes
+     */
+    private handleHashNavigation(): void {
+        const hash = window.location.hash;
+        if (hash) {
+            const sectionId = hash.substring(1);
+            this.scrollToSection(sectionId);
+            this.updateSelectedSidebarItem(sectionId);
+        }
+    }
+
+    /**
+     * Scroll to a specific section in Redoc content
+     */
+    private scrollToSection(sectionId: string): void {
+        this.isProgrammaticScroll = true;
+
+        const targetSection = this.template.querySelector(`[data-section-id="${sectionId}"]`);
+        if (targetSection) {
+            targetSection.scrollIntoView({
+                behavior: 'smooth',
+                block: 'start'
+            });
+
+            // Reset flag after scroll animation
+            setTimeout(() => {
+                this.isProgrammaticScroll = false;
+            }, 1000);
+        } else {
+            this.isProgrammaticScroll = false;
+        }
+    }
+
+    /**
+     * Handle navigation selection from sidebar
+     */
+    onNavSelect(event: CustomEvent): void {
+        const name = event.detail.name;
+        if (name) {
+            const urlReferenceId = this.getReferenceIdFromUrl(name);
+            const specBasedReference = this.isSpecBasedReference(urlReferenceId);
+            
+            if (specBasedReference) {
+                // Extract hash from the name (URL)
+                const hashIndex = name.indexOf('#');
+                if (hashIndex > -1) {
+                    const sectionId = name.substring(hashIndex + 1);
+                    
+                    // Update URL hash and scroll to section
+                    window.location.hash = sectionId;
+                    
+                    // Update page title with section name
+                    const redocData = this.redocSidebarData.get(urlReferenceId);
+                    if (redocData) {
+                        const sectionItem = this.findRedocItemById(redocData.items, sectionId);
+                        if (sectionItem) {
+                            this.updateTags(sectionItem.label);
+                        }
+                    }
+                    
+                    logCoveoPageView(
+                        this.coveoOrganizationId,
+                        this.coveoAnalyticsToken
+                    );
+                } else {
+                    // This is a parent reference selection
+                    if (this.isParentReferencePath(name)) {
+                        this.loadNewReferenceItem(name);
+                    }
+                }
+            } else {
+                this.loadMarkdownBasedReference(name);
+            }
+        }
+    }
+
+    onExpandCollapse(event: CustomEvent): void {
+        const { name, isSelectAction, isExpanded } = event.detail;
+        if (!isSelectAction && isExpanded) {
+            const referenceId = this.getReferenceIdFromUrl(name);
+            const currentUrl = window.location.href;
+            const currentReferenceId = this.getReferenceIdFromUrl(currentUrl);
+            
+            if (referenceId !== currentReferenceId) {
+                const isSpecBasedReference = this.isSpecBasedReference(referenceId);
+                if (isSpecBasedReference) {
+                    this.onNavSelect(event);
+                }
+            }
+        }
+    }
+
+    /**
+     * The API Navigation event will always intend to navigate within the current reference
+     */
+    protected onApiNavigationChanged(): void {
+        // Handle API navigation changes if needed
+        restoreScroll();
+    }
+
+    /**
+     * This method gets called when the user navigates back and forth using browser arrows
+     */
+    protected updateSelectedItemFromUrlQuery(): void {
+        const specBasedReference = this.isSpecBasedReference(this._currentReferenceId);
+        if (specBasedReference) {
+            this.handleHashNavigation();
+        } else {
+            this.loadMarkdownBasedReference();
+        }
+        restoreScroll();
+    }
+
+    /**
+     * Returns whether given url is parent reference path
+     */
+    private isParentReferencePath(urlPath?: string | null): boolean {
+        if (!urlPath) {
+            return false;
+        }
+        const parentReferenceIndex = this.parentReferenceUrls.findIndex(
+            (referenceUrl: string) => {
+                return urlPath.endsWith(referenceUrl);
+            }
+        );
+        return parentReferenceIndex !== -1;
+    }
+
+    /**
+     * Navigates to reference of the given URL
+     */
+    private loadNewReferenceItem(url: string): void {
+        const referenceId = this.getReferenceIdFromUrl(url);
+        const referenceItem = this.getAmfConfigWithId(referenceId);
+        if (referenceItem) {
+            window.location.href = referenceItem.href;
+        }
+    }
+
+    /**
+     * Load markdown-based reference
+     */
+    private loadMarkdownBasedReference(referenceUrl?: string | null): void {
+        let referenceId = "";
+        const currentUrl = window.location.href;
+        
+        if (this.isProjectRootPath()) {
+            /**
+             * CASE1: This case is to consider when the user navigates to references by clicking a project card
+             * Ex: /docs/example-project/references should navigate to the first topic in the first reference
+             */
+            referenceId = this._currentReferenceId;
+        } else if (this.isParentReferencePath(referenceUrl)) {
+            /**
+             * CASE2: This case is to navigate to respective reference when the user clicked on root item
+             * Ex: .../references/markdown-ref should navigate to first topic.
+             */
+            referenceId = this.getReferenceIdFromUrl(referenceUrl!);
+        } else if (this.isParentReferencePath(currentUrl)) {
+            /**
+             * CASE3: This case is to navigate to respective reference when the user entered url with reference id
+             * Ex: .../references/markdown-ref should navigate to first topic.
+             */
+            referenceId = this.getReferenceIdFromUrl(currentUrl);
+        } else if (referenceUrl) {
+            /**
+             * CASE4: This case is to navigate to first item when we don't have topic in the selected version
+             * Ex: .../references/markdown-ref/not-existed-topic-url should navigate to first topic.
+             */
+            referenceId = this.getReferenceIdFromUrl(referenceUrl);
+        }
+
+        let isRedirecting = false;
+        if (referenceId) {
+            const amfConfig = this.getAmfConfigWithId(referenceId);
+            let redirectReferenceUrl = "";
+            if (amfConfig && amfConfig.topic) {
+                const childrenItems = amfConfig.topic.children;
+                if (childrenItems && childrenItems.length > 0) {
+                    redirectReferenceUrl = childrenItems[0].link!.href;
+                }
+            }
+            if (redirectReferenceUrl) {
+                if (this.isParentReferencePath(referenceUrl)) {
+                    // This is for CASE2 mentioned above, Where we need to navigate user to respective href
+                    isRedirecting = true;
+                    window.location.href = redirectReferenceUrl;
+                } else {
+                    // This is for CASE 1,3 and 4 mentioned above, Where we need to update the browser history
+                    window.history.replaceState(
+                        window.history.state,
+                        "",
+                        redirectReferenceUrl
+                    );
+                }
+            }
+        }
+        
+        if (!isRedirecting) {
+            // Update title for markdown references
+            // For markdown, we could extract title from the page or use a default
+            this.updateTags("Reference Documentation");
+
+            this.versions = this.getVersions();
+            if (this.oldVersionInfo) {
+                this.showVersionBanner = true;
+            } else {
+                this.latestVersion = true;
+            }
+
+            this.isVersionFetched = true;
+            this.updateDocPhase();
+            this.selectedSidebarValue = window.location.pathname;
+        }
+    }
+
+    /**
+     * Handle version change
+     */
+    handleVersionChange(): void {
+        const currentUrl = window.location.href;
+        window.sessionStorage.setItem(
+            this.docsReferenceUrlSessionKey,
+            currentUrl
+        );
+    }
+
+    handleDismissVersionBanner() {
+        this.showVersionBanner = false;
+    }
+
+    /**
+     * Updates doc phase of selected reference
+     */
+    updateDocPhase(): void {
+        /* If parent level doc phase is enabled, Individual reference level doc phase should not be considered */
+
+        if (!this.isParentLevelDocPhaseEnabled) {
+            const selectedReference = this._amfConfigList.find(
+                (referenceItem: AmfConfig) => {
+                    return referenceItem.id === this._currentReferenceId;
+                }
+            );
+            if (selectedReference) {
+                this.selectedReferenceDocPhase = JSON.stringify(
+                    selectedReference.docPhase
+                );
+            }
+        }
+    }
+
+    /**
+     * Normalizes topic identifier by replacing spaces with '+'
+     * and running encodeURI() on it
+     * @param identifier raw identifier for a topic as parsed from the spec file
+     * @returns normalized and encoded identifier
+     */
+    protected encodeIdentifier(identifier: string): string {
+        let result = identifier.trim();
+        result = result.replace(new RegExp(/\s+/, "g"), "+");
+        return encodeURI(result);
+    }
+
+    /**
+     * Gets the encoded url.
+     * This method will return the encoded url for 2 cases,
+     * 1. If the url is encoded already
+     * 2. If the url is decoded
+     */
+    getUrlEncoded(url: string): string {
+        // if url matches, then return the encoded url.
+        if (decodeURIComponent(url) === url) {
+            return encodeURIComponent(url);
+        }
+        // return the encoded url.
+        return this.getUrlEncoded(decodeURIComponent(url));
+    }
+
+    /**
+     * Constructs a Reference Topic ID
+     */
+    protected getFormattedIdentifier(referenceId: string, id: string): string {
+        return `${referenceId}:${id}`;
+    }
+
+    /**
+     * Update browser URL with hash-based navigation
+     */
+    protected updateUrlWithHash(hash: string): void {
+        if (hash) {
+            window.history.pushState({}, "", `#${hash}`);
+        }
+    }
+
+    /**
+     * Replace browser URL with hash-based navigation (no history entry)
+     */
+    protected replaceUrlWithHash(hash: string): void {
+        if (hash) {
+            window.history.replaceState(null, '', `#${hash}`);
+        }
+    }
+
+    /**
+     * Update page title and meta tags
+     */
+    private updateTags(navTitle = ""): void {
+        if (!navTitle) {
+            return;
+        }
+
+        // this is required to update the nav title meta tag.
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const metaNavTitle = document.querySelector('meta[name="nav-title"]');
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const titleTag = document.querySelector("title");
+        const TITLE_SEPARATOR = " | ";
+
+        if (metaNavTitle) {
+            metaNavTitle.setAttribute("content", navTitle);
+        }
+
+        /**
+         * Right now, the title tag only changes when you pick a Ref spec,
+         * not every time you choose a subsection of the Ref spec.
+         * This update aims to refresh the title tag with each selection.
+         * If a Ref spec is chosen, we add the value of the <selected topic> to the title.
+         * If a subsection is selected, we update the first part of the current
+         * title with the new <selected topic>.
+         * Example: Following is a sample project structure.
+         * - Project Name
+         *  - Ref Spec1
+         *      - Summary
+         *      - Endpoints
+         *          - E1
+         *          - E2
+         *  - Ref Spec2
+         *      - Summary
+         *      - Endpoints
+         *          - E1 (Selected)
+         *          - E2
+         * Previous Title: Ref Spec2 | Project Name | Salesforce Developer
+         * New Title: E1 | Ref Spec2 | Project Name | Salesforce Developer
+         *
+         */
+        if (titleTag) {
+            let titleTagValue = titleTag.textContent;
+            const titleTagSectionValues: string[] =
+                titleTagValue?.split(TITLE_SEPARATOR) || [];
+            if (titleTagSectionValues.length > 0) {
+                if (titleTagSectionValues.length <= 3) {
+                    titleTagValue = navTitle + TITLE_SEPARATOR + titleTagValue;
+                } else {
+                    titleTagSectionValues[0] = navTitle;
+                    titleTagValue = titleTagSectionValues.join(TITLE_SEPARATOR);
+                }
+            }
+            titleTag.textContent = titleTagValue;
+        }
+    }
+
+    /**
+     * Expands the children of Markdown-based References.
+     */
+    private expandChildrenForMarkdownReferences(
+        children: ParsedMarkdownTopic[]
+    ): void {
+        if (!children) {
+            return;
+        }
+        for (const childNode of children) {
+            childNode.isExpanded = true;
+            this.expandChildrenForMarkdownReferences(childNode.children);
+        }
+    }
+
+    /**
+     * Returns whether current location is project root path like ../example-project/references
+     */
+    private isProjectRootPath(): boolean {
+        return this.getReferenceIdFromUrl(window.location.href) === "";
+    }
+
+    /**
+     * Returns the current hash from URL (for hash-based navigation)
+     * Note: This replaces the old meta query param logic
+     */
+    getMetaFromUrl(): string {
+        // For hash-based navigation, extract from hash instead
+        const hash = window.location.hash;
+        if (hash) {
+            return hash.substring(1); // Remove '#' prefix
+        }
+        
+        return "";
+    }
+
+    /**
+     * Convert any case to a readable Title
+     * ex: snake_case => Snake case
+     * ex: camelCase =>  Camel case
+     * ex: PascalCase => Pascal case
+     * @param label
+     * @returns string
+     */
+    private getTitleForLabel(label: string): string {
+        // Simple sentence case conversion without external dependencies
+        return label
+            .replace(/([A-Z])/g, ' $1') // Add space before capitals
+            .replace(/[-_]/g, ' ') // Replace dashes and underscores with spaces
+            .trim()
+            .toLowerCase()
+            .replace(/^\w/, c => c.toUpperCase()); // Capitalize first letter
+    }
+}

package/src/modules/doc/docReference/types.ts

@@ -0,0 +1,24 @@
+// Redoc type declarations for window object
+export interface RedocNavigationItem {
+    label: string;
+    name: string; // Hash-based URL (#section-id)
+    id: string;   // Section ID for scroll targeting
+    children?: RedocNavigationItem[];
+}
+
+export interface RedocSidebarData {
+    spec: {
+        title: string;
+        version: string;
+    };
+    items: RedocNavigationItem[];
+}
+
+declare global {
+    interface Window {
+        Redoc?: {
+            init: (specUrl: string, options: any, container: Element) => Promise<void>;
+            getSpecStructure?: (specUrl: string) => Promise<RedocSidebarData>;
+        };
+    }
+}

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.