@salesforcedevs/docs-components 1.17.6-hover-edit → 1.17.6-redoc2

package/src/modules/doc/flexReference/flexReference.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 "./types";
+
+import {
+    REFERENCE_TYPES,
+    oldReferenceIdNewReferenceIdMap
+} from "./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 FlexReference 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
+    }
+}