@salesforcedevs/docs-components 0.17.0 → 0.17.12-search-alpha

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

@@ -1,8 +1,8 @@
-@import "helpers/reset";
+@import "dxHelpers/reset";
 
 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

@@ -0,0 +1,53 @@
+@import "dxHelpers/reset";
+
+:host {
+    --doc-c-heading-anchor-button-bottom: 0;
+    --doc-c-heading-anchor-icon-size: 18px;
+    --button-size: var(--dx-g-spacing-xl);
+}
+
+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 {
+    position: absolute;
+    bottom: var(--doc-c-heading-anchor-button-bottom);
+    left: 0;
+    opacity: 0;
+    color: rgb(11 92 171);
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    height: var(--button-size);
+    width: var(--button-size);
+    border-radius: 4px;
+}
+
+dx-icon {
+    --dx-c-icon-size: var(--doc-c-heading-anchor-icon-size);
+}
+
+.title {
+    word-break: break-word;
+}
+
+button:focus {
+    box-shadow: 0 0 0 2px rgb(11 92 171);
+}
+
+button:focus,
+button:hover,
+span:hover dx-tooltip button,
+span:hover ~ dx-tooltip button {
+    opacity: 1;
+    outline: none;
+}

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

@@ -0,0 +1,13 @@
+<template>
+    <template if:false={hash}>{header}</template>
+    <template if:true={hash}>
+        <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

@@ -0,0 +1,30 @@
+import { LightningElement, api } from "lwc";
+
+export default class HeadingContent extends LightningElement {
+    @api header: string = "";
+    @api hash: string | null = null;
+
+    label: string = "Copy link to clipboard";
+    timeout: number | null = null;
+
+    private async copy() {
+        if (this.timeout) {
+            window.clearTimeout(this.timeout);
+        }
+
+        this.label = "Copied";
+        this.timeout = window.setTimeout(() => {
+            this.label = "Copy link to clipboard";
+        }, 2000);
+
+        try {
+            if (this.header && this.hash) {
+                const [hostUrl] = window.location.href.split("#");
+                const url = `${hostUrl}#${this.hash}`;
+                await navigator.clipboard.writeText(url);
+            }
+        } catch (error) {
+            console.error(error);
+        }
+    }
+}

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

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

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

@@ -0,0 +1,45 @@
+<template>
+    <div class="content">
+        <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>
+        <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

@@ -0,0 +1,70 @@
+@import "dxHelpers/reset";
+@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;
+    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
+    Ref: https://stackoverflow.com/a/41164095
+
+    Otherwise we need to change the height when user clicks on button
+    Ref: https://stackoverflow.com/a/11837673
+*/
+
+.doc-phase-body {
+    display: block;
+    max-height: 1000px;
+    overflow: hidden;
+    padding-top: var(--dx-g-spacing-smd);
+    transition: max-height 0.25s ease, padding 0.25s ease;
+}
+
+.doc-phase-body-hidden {
+    max-height: 0;
+    padding-top: 0;
+    transition: max-height 0.1s ease-out, padding 0.25s ease-out;
+}
+
+.doc-phase-body a {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
+/* Small Devices */
+@media screen and (max-width: 480px) {
+    .doc-phase-container {
+        padding: var(--doc-status-vertical-padding);
+    }
+}

package/src/modules/doc/phase/phase.html

@@ -0,0 +1,38 @@
+<template>
+    <div class={className} part="container">
+        <div class="doc-phase-title-container">
+            <dx-icon
+                class="doc-status-icon doc-phase-icon"
+                symbol={iconName}
+                size="large"
+                color="status-icon-color"
+            ></dx-icon>
+            <p class="doc-status-title doc-phase-title dx-text-body-3">
+                {docPhaseTitle}
+            </p>
+            <dx-button
+                lwc:if={dismissible}
+                aria-label="Dismiss"
+                icon-color="status-icon-color"
+                icon-size="large"
+                icon-symbol="close"
+                variant="icon-only"
+                onclick={onDismiss}
+            ></dx-button>
+            <dx-button
+                lwc:else
+                variant="inline"
+                onclick={onShowHide}
+                aria-label={hideBodyText}
+            >
+                {hideBodyText}
+            </dx-button>
+        </div>
+        <!--
+            NOTE: Here we are rendering mark up using lwc:dom & innerHTML
+            option instead of slots because the html markup will come as a
+            property to the component from a configuration
+        -->
+        <span lwc:dom="manual" class={bodyClassName}></span>
+    </div>
+</template>