@salesforcedevs/docs-components 0.56.2-comp-flex-ref-1 → 0.56.2-example

package/src/modules/doc/heading/heading.html

@@ -1,14 +1,14 @@
 <template>
     <h1 class={className} if:true={isAriaLevelOne}>
-        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+        <doc-heading-content header={header} hash={hash}></doc-heading-content>
     </h1>
     <h2 class={className} if:true={isAriaLevelTwo}>
-        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+        <doc-heading-content header={header} hash={hash}></doc-heading-content>
     </h2>
     <h3 class={className} if:true={isAriaLevelThree}>
-        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+        <doc-heading-content header={header} hash={hash}></doc-heading-content>
     </h3>
     <h4 class={className} if:true={isAriaLevelFour}>
-        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+        <doc-heading-content header={header} hash={hash}></doc-heading-content>
     </h4>
 </template>

package/src/modules/doc/heading/heading.ts

@@ -1,22 +1,24 @@
 import { LightningElement, api } from "lwc";
 
-export const displayLevels = ["3", "4", "5", "6"];
-
-export const ariaLevels = ["1", "2", "3", "4"];
-
 export const ariaDisplayLevels: { [key: string]: string } = {
-    "1": "3",
-    "2": "4",
-    "3": "5",
-    "4": "6"
+    "1": "4",
+    "2": "5",
+    "3": "6",
+    "4": "8"
 };
 
+export const ariaLevels = Object.keys(ariaDisplayLevels);
+
+export const displayLevels = Object.values(ariaDisplayLevels);
+
+// @ts-ignore: Really Dark Magic (TM) to do with ariaLevel needing explicit getter/setters
 export default class Heading extends LightningElement {
-    @api title: string = "";
+    @api header: string = "";
     @api hash: string | null = null;
 
     @api
     private get ariaLevel(): string {
+        // Really Dark Magic (TM)
         return this._ariaLevel || "2";
     }
     private set ariaLevel(value: string | null) {
@@ -60,6 +62,6 @@ export default class Heading extends LightningElement {
     }
 
     private get className(): string {
-        return `display-${this.displayLevel}`;
+        return `dx-text-display-${this.displayLevel}`;
     }
 }

package/src/modules/doc/headingAnchor/headingAnchor.css

@@ -2,7 +2,7 @@
 
 button {
     opacity: 0;
-    color: rgb(11, 92, 171);
+    color: rgb(11 92 171);
 }
 
 button:hover {
@@ -17,7 +17,7 @@ button:focus {
 
 button:focus-visible {
     border-radius: 4px;
-    border: 2px solid rgb(11, 92, 171);
+    border: 2px solid rgb(11 92 171);
 }
 
 .icon-wrapper {

package/src/modules/doc/headingAnchor/headingAnchor.ts

@@ -6,7 +6,7 @@ export default class HeadingAnchor extends LightningElement {
     @api iconSize?: IconSize = "override";
     @api iconSprite?: IconSprite = "utility";
     @api iconSymbol?: IconSymbol;
-    @api title: string = "";
+    @api header: string = "";
     @api urlText: string = "";
 
     label: string = "Copy link to clipboard";
@@ -22,7 +22,7 @@ export default class HeadingAnchor extends LightningElement {
         }, 2000);
 
         try {
-            if (this.title && this.urlText) {
+            if (this.header && this.urlText) {
                 const [hostUrl] = window.location.href.split("#");
                 const url = `${hostUrl}#${this.urlText}`;
                 await navigator.clipboard.writeText(url);

package/src/modules/doc/headingContent/headingContent.css

@@ -8,12 +8,14 @@
 
 dx-tooltip {
     line-height: var(--button-size);
+    padding-right: var(--dx-g-spacing-xs);
 }
 
 .button-container {
     height: 100%;
     margin-right: calc(var(--dx-g-spacing-xl) - 4px);
     position: relative;
+    padding-right: var(--dx-g-spacing-xs);
 }
 
 button {
@@ -21,7 +23,7 @@ button {
     bottom: var(--doc-c-heading-anchor-button-bottom);
     left: 0;
     opacity: 0;
-    color: rgb(11, 92, 171);
+    color: rgb(11 92 171);
     display: flex;
     justify-content: center;
     align-items: center;
@@ -34,12 +36,8 @@ dx-icon {
     --dx-c-icon-size: var(--doc-c-heading-anchor-icon-size);
 }
 
-span:last-of-type {
-    padding-right: var(--dx-g-spacing-xs);
-}
-
-.nowrap {
-    white-space: nowrap;
+.title {
+    word-break: break-word;
 }
 
 button:focus {
@@ -49,7 +47,7 @@ button:focus {
 button:focus,
 button:hover,
 span:hover dx-tooltip button,
-span:hover ~ span dx-tooltip button {
+span:hover ~ dx-tooltip button {
     opacity: 1;
     outline: none;
 }

package/src/modules/doc/headingContent/headingContent.html

@@ -1,19 +1,13 @@
 <template>
-    <template if:false={hash}>{title}</template>
+    <template if:false={hash}>{header}</template>
     <template if:true={hash}>
-        <template if:true={needsSpace}>
-            <span>{titleToWrap}</span>
-            <span>&#32;</span>
-        </template>
-        <span class="nowrap">
-            {titleNoWrap}&nbsp;
-            <dx-tooltip placement="top" label={label}>
-                <span class="button-container">
-                    <button onclick={copy} aria-label="copy">
-                        <dx-icon size="override" symbol="link"></dx-icon>
-                    </button>
-                </span>
-            </dx-tooltip>
-        </span>
+        <span class="title">{header}&nbsp;</span>
+        <dx-tooltip placement="top" label={label}>
+            <span class="button-container">
+                <button onclick={copy} aria-label="copy">
+                    <dx-icon size="override" symbol="link"></dx-icon>
+                </button>
+            </span>
+        </dx-tooltip>
     </template>
 </template>

package/src/modules/doc/headingContent/headingContent.ts

@@ -1,24 +1,12 @@
 import { LightningElement, api } from "lwc";
 
 export default class HeadingContent extends LightningElement {
-    @api title: string = "";
+    @api header: string = "";
     @api hash: string | null = null;
 
     label: string = "Copy link to clipboard";
     timeout: number | null = null;
 
-    private get titleToWrap(): string {
-        return this.title.substring(0, this.title.lastIndexOf(" "));
-    }
-
-    private get needsSpace(): boolean {
-        return this.titleToWrap.length > 0;
-    }
-
-    private get titleNoWrap(): string {
-        return this.title.substring(this.title.lastIndexOf(" ") + 1);
-    }
-
     private async copy() {
         if (this.timeout) {
             window.clearTimeout(this.timeout);
@@ -30,7 +18,7 @@ export default class HeadingContent extends LightningElement {
         }, 2000);
 
         try {
-            if (this.title && this.hash) {
+            if (this.header && this.hash) {
                 const [hostUrl] = window.location.href.split("#");
                 const url = `${hostUrl}#${this.hash}`;
                 await navigator.clipboard.writeText(url);

package/src/modules/doc/lwcContentLayout/lwcContentLayout.css

@@ -0,0 +1 @@
+@import "docHelpers/contentLayoutStyle";

package/src/modules/doc/lwcContentLayout/lwcContentLayout.html

@@ -0,0 +1,68 @@
+<template>
+    <div class="content">
+        <template lwc:if={useOldSidebar}>
+            <dx-sidebar-old
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+                ontogglesidebar={onToggleSidebar}
+                languages={languages}
+                language={language}
+                bail-href={bailHref}
+                bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
+            >
+                <slot name="sidebar-header" slot="version-picker"></slot>
+            </dx-sidebar-old>
+        </template>
+        <template lwc:else>
+            <dx-sidebar
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+                coveo-organization-id={coveoOrganizationId}
+                coveo-public-access-token={coveoPublicAccessToken}
+                coveo-search-hub={coveoSearchHub}
+                coveo-advanced-query-config={coveoAdvancedQueryConfig}
+                ontogglesidebar={onToggleSidebar}
+                languages={languages}
+                language={language}
+                bail-href={bailHref}
+                bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
+            >
+                <slot name="sidebar-header" slot="version-picker"></slot>
+            </dx-sidebar>
+        </template>
+        <div class="content-body-doc-phase-container">
+            <slot name="doc-phase"></slot>
+            <slot name="version-banner"></slot>
+            <div class="content-body-container">
+                <div class="content-body">
+                    <doc-breadcrumbs
+                        lwc:if={showBreadcrumbs}
+                        breadcrumbs={breadcrumbs}
+                    ></doc-breadcrumbs>
+                    <slot onslotchange={onSlotChange}></slot>
+                    <doc-sprig-survey
+                        lwc:if={shouldDisplayFeedback}
+                    ></doc-sprig-survey>
+                </div>
+                <div lwc:if={showToc} class="right-nav-bar is-sticky">
+                    <dx-toc
+                        header={tocTitle}
+                        options={tocOptions}
+                        value={tocValue}
+                    ></dx-toc>
+                </div>
+            </div>
+            <div lwc:if={showFooter} class="footer-container">
+                <dx-footer variant="no-signup"></dx-footer>
+            </div>
+        </div>
+    </div>
+</template>

package/src/modules/doc/lwcContentLayout/lwcContentLayout.ts

@@ -0,0 +1,256 @@
+import ContentLayout from "doc/contentLayout";
+
+const TOC_HEADER_TAG = "doc-heading";
+const RNB_BY_TAB = "docs-tab";
+const SPECIFICATION_TAG = "doc-specification-content";
+export const OBSERVER_ATTACH_WAIT_TIME = 500;
+
+export default class LwcContentLayout extends ContentLayout {
+    private rnbByTab: boolean = false;
+
+    // DOM element caches to avoid repeated queries
+    private tabPanelListCache: any = null;
+    private hasSpecContentCache: boolean | null = null;
+    private allTabsCache: any[] | null = null;
+    private mainSlotCache: any = null;
+
+    private setRNBByTab() {
+        const tabPanelListItem = this.getTabPanelList();
+        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB;
+    }
+
+    get showTabBasedRNB() {
+        return this.rnbByTab;
+    }
+
+    /**
+     * Check if the main slot contains doc-specification-content
+     * Uses caching to avoid repeated DOM queries
+     */
+    private hasSpecificationContent(): boolean {
+        if (this.hasSpecContentCache !== null) {
+            return this.hasSpecContentCache;
+        }
+
+        const mainSlot = this.getMainSlot();
+        if (mainSlot) {
+            const assignedElements = (mainSlot as any).assignedElements();
+
+            for (const element of assignedElements) {
+                if (
+                    element.tagName === SPECIFICATION_TAG ||
+                    element.querySelector(SPECIFICATION_TAG) ||
+                    element.shadowRoot?.querySelector(SPECIFICATION_TAG)
+                ) {
+                    return (this.hasSpecContentCache = true);
+                }
+            }
+        }
+        return (this.hasSpecContentCache = false);
+    }
+
+    /**
+     * Clear all caches when content changes
+     */
+    private clearAllCaches(): void {
+        this.hasSpecContentCache = null;
+        this.tabPanelListCache = null;
+        this.allTabsCache = null;
+        this.mainSlotCache = null;
+    }
+
+    /**
+     * Get the main slot element with caching
+     */
+    private getMainSlot(): any {
+        if (!this.mainSlotCache) {
+            this.mainSlotCache =
+                this.template.querySelector("slot:not([name])");
+        }
+        return this.mainSlotCache;
+    }
+
+    /**
+     * Get tab panel list with caching
+     */
+    private getTabPanelList(): any {
+        if (!this.tabPanelListCache) {
+            // eslint-disable-next-line @lwc/lwc/no-document-query
+            this.tabPanelListCache =
+                document.querySelector("dx-tab-panel-list");
+        }
+        return this.tabPanelListCache;
+    }
+
+    onRNBClick = (event: CustomEvent) => {
+        event.stopPropagation();
+        if (this.hasSpecificationContent()) {
+            this.didScrollToSelectedHash = false;
+        }
+    };
+
+    onTabChanged = () => {
+        this.updateRNB();
+
+        const { hash } = window.location;
+        if (this.hasSpecificationContent() && hash) {
+            this.didScrollToSelectedHash = false;
+
+            requestAnimationFrame(() => this.updateHeadingForRNB());
+        }
+    };
+
+    protected getHeadingElements() {
+        let headingElements = super.getHeadingElements();
+        if (this.showTabBasedRNB) {
+            const tabPanelListItem = this.getTabPanelList();
+            const tabPanels =
+                tabPanelListItem?.querySelectorAll("dx-tab-panel");
+
+            for (const tabPanelItem of tabPanels) {
+                if (tabPanelItem.active) {
+                    // This is needed for Specification tab content
+                    const specificationElement = tabPanelItem.querySelector(
+                        "doc-specification-content"
+                    );
+                    if (specificationElement) {
+                        headingElements =
+                            specificationElement.shadowRoot.querySelectorAll(
+                                TOC_HEADER_TAG
+                            );
+                    } else {
+                        headingElements =
+                            tabPanelItem.querySelectorAll(TOC_HEADER_TAG);
+                    }
+                    break;
+                }
+            }
+        }
+        return headingElements;
+    }
+
+    private updateURL() {
+        const tabs = this.getAllTabs();
+        const selectedTabId = this.getSelectedTabId();
+
+        tabs.forEach((tab: any) => {
+            if (tab.getAttribute("aria-selected") === "true") {
+                const tabID = tab.getAttribute("aria-label");
+                const url = new URL(window.location.href);
+                if (selectedTabId !== tabID) {
+                    url.searchParams.set("type", tabID);
+                    url.hash = "";
+                    window.history.pushState({}, "", url.toString());
+                }
+            }
+        });
+    }
+
+    // This event gets triggered when navigating back/forward
+    handlePopState = (): void => {
+        if (this.showTabBasedRNB) {
+            this.restoreTabSelection();
+        }
+    };
+
+    connectedCallback(): void {
+        super.connectedCallback();
+        window.addEventListener("popstate", this.handlePopState);
+    }
+
+    private getSelectedTabId() {
+        const urlParams = new URLSearchParams(window.location.search);
+        const selectedTabId = urlParams.get("type");
+        return selectedTabId;
+    }
+
+    private restoreTabSelection() {
+        requestAnimationFrame(() => {
+            const selectedTabId = this.getSelectedTabId();
+            if (selectedTabId) {
+                this.selectTabById(selectedTabId);
+
+                // If there's a hash and we have specification content,
+                // we need to wait for the content to load before scrolling
+                const { hash } = window.location;
+                if (this.hasSpecificationContent() && hash) {
+                    // Reset the scroll flag to allow scrolling once content is loaded
+                    this.didScrollToSelectedHash = false;
+                }
+            }
+        });
+    }
+
+    private getAllTabs(): any[] {
+        // Return cached result if available
+        if (this.allTabsCache) {
+            return this.allTabsCache;
+        }
+
+        const tabPanelListItem = this.getTabPanelList();
+        if (tabPanelListItem?.shadowRoot) {
+            this.allTabsCache = Array.from(
+                tabPanelListItem.shadowRoot.querySelectorAll(
+                    "dx-tab-panel-item"
+                )
+            ).map((tabPanelItem: any) =>
+                tabPanelItem.shadowRoot.querySelector("button")
+            );
+        } else {
+            this.allTabsCache = [];
+        }
+
+        return this.allTabsCache;
+    }
+
+    private selectTabById(tabId: string) {
+        const tabs = this.getAllTabs();
+        tabs.forEach((tab: any) => {
+            if (tab.getAttribute("aria-label") === tabId) {
+                tab.click();
+            }
+        });
+    }
+
+    postRenderedCallback(): void {
+        this.setRNBByTab();
+        if (this.showTabBasedRNB) {
+            window.addEventListener("tabchanged", this.onTabChanged);
+            window.addEventListener(
+                "specificationdatarendered",
+                this.onTabChanged
+            );
+            window.addEventListener("selectedcontent", (event) =>
+                this.onRNBClick(event as CustomEvent)
+            );
+            this.restoreTabSelection();
+        }
+    }
+
+    disconnectedCallback(): void {
+        super.disconnectedCallback();
+        if (this.showTabBasedRNB) {
+            window.removeEventListener("tabchanged", this.onTabChanged);
+            window.removeEventListener(
+                "specificationdatarendered",
+                this.onTabChanged
+            );
+            window.removeEventListener("selectedcontent", (event) =>
+                this.onRNBClick(event as CustomEvent)
+            );
+            window.removeEventListener("popstate", this.handlePopState);
+        }
+    }
+
+    onSlotChange(): void {
+        this.clearAllCaches();
+        super.onSlotChange();
+    }
+
+    updateHeadingForRNB(): void {
+        if (this.showTabBasedRNB) {
+            this.updateURL();
+        }
+        super.updateHeadingForRNB();
+    }
+}

package/src/modules/doc/overview/overview.css

@@ -0,0 +1,40 @@
+doc-phase {
+    --doc-c-phase-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
+    );
+}
+
+dx-section {
+    --dx-c-section-padding-top: 0;
+    --dx-c-section-padding-bottom: var(--dx-g-spacing-2xl);
+}
+
+dx-section::part(content) {
+    max-width: 1280px;
+    margin: auto;
+}
+
+dx-group-text:first-of-type {
+    margin-top: var(--dx-g-spacing-2xl);
+}
+
+dx-group-text.features {
+    margin-top: var(--dx-g-spacing-xl);
+    margin-bottom: var(--dx-g-spacing-xl);
+}
+
+.content {
+    padding-right: var(--dx-g-spacing-xl);
+}
+
+@media (max-width: 1024px) {
+    .content {
+        padding-right: 0;
+    }
+}
+
+@media (max-width: 800px) {
+    dx-group-text.description {
+        margin-top: var(--dx-g-spacing-lg);
+    }
+}

package/src/modules/doc/overview/overview.html

@@ -0,0 +1,34 @@
+<template>
+    <div class="container">
+        <doc-phase
+            if:true={docPhaseInfo}
+            doc-phase-info={docPhaseInfo}
+        ></doc-phase>
+
+        <dx-section>
+            <dx-grid columns="two-slim-right">
+                <div class="content">
+                    <dx-group-text
+                        class="description"
+                        header={header}
+                        body={description}
+                        size="large"
+                        title-aria-level="1"
+                        primary-link={primaryLink}
+                        secondary-link={secondaryLink}
+                    ></dx-group-text>
+                </div>
+                <div>
+                    <dx-group-text
+                        header={featuresListTitle}
+                        size="medium"
+                        class="features"
+                    ></dx-group-text>
+                    <dx-features-list
+                        options={featuresListOptions}
+                    ></dx-features-list>
+                </div>
+            </dx-grid>
+        </dx-section>
+    </div>
+</template>

package/src/modules/doc/overview/overview.ts

@@ -0,0 +1,12 @@
+import { LightningElement, api } from "lwc";
+import { DocPhaseInfo, FeatureItem, Link } from "typings/custom";
+
+export default class Overview extends LightningElement {
+    @api docPhaseInfo!: DocPhaseInfo;
+    @api header!: string;
+    @api description!: string;
+    @api primaryLink!: Link;
+    @api secondaryLink!: Link;
+    @api featuresListTitle!: string;
+    @api featuresListOptions!: FeatureItem[];
+}

package/src/modules/doc/phase/phase.css

@@ -2,25 +2,39 @@
 @import "dxHelpers/text";
 @import "docHelpers/status";
 
+:host {
+    --doc-c-phase-top: 0;
+    --doc-c-phase-container-align-items: flex-start;
+
+    position: sticky;
+    top: var(--doc-c-phase-top);
+
+    /* NOTE: If you are changing z-index value here, ensure it's less than z-index of dx-sidebar in contentLayout.css */
+    z-index: var(--dx-g-z-index-100);
+}
+
 .doc-phase-container {
     display: flex;
     flex-direction: column;
-    padding-left: var(--dx-g-spacing-3xl);
-    padding-right: var(--dx-g-spacing-3xl);
+    align-items: var(--doc-c-phase-container-align-items);
+    padding-left: var(--dx-g-global-header-padding-horizontal);
+    padding-right: var(--dx-g-global-header-padding-horizontal);
     width: 100%;
+    border: none;
 }
 
 .doc-phase-title-container {
     display: flex;
     flex-direction: row;
     align-items: center;
+    width: 100%;
 }
 
 dx-button {
     margin-left: auto;
 }
 
-/* 
+/*
     NOTE: Here we are assuming that indicator height won't go beyond 1000px.
 
     It's one of the suggested way to achieve the expand/collapse animation
@@ -31,6 +45,7 @@ dx-button {
 */
 
 .doc-phase-body {
+    display: block;
     max-height: 1000px;
     overflow: hidden;
     padding-top: var(--dx-g-spacing-smd);