@salesforcedevs/docs-components 0.0.1 → 0.0.2-edit

package/src/modules/doc/header/header.ts

@@ -1,93 +1,76 @@
 import { api } from "lwc";
 import cx from "classnames";
-import type { OptionWithNested, OptionWithLink } from "typings/custom";
+import type { OptionWithNested, DevCenterConfig } from "typings/custom";
 import { HeaderBase } from "dxBaseElements/headerBase";
-import { toJson } from "dxUtils/normalizers";
-import get from "lodash.get";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 
 const TABLET_MATCH = "980px";
-const MOBILE_MATCH = "880px";
-const SMALL_MOBILE_MATCH = "740px";
+const MOBILE_MATCH = "768px";
+
+const isStorybook = () => {
+    const { host } = window.location;
+    return (
+        host === "localhost:6006" || /^dsc-comp.*\.herokuapp\.com$/.test(host)
+    );
+};
 
 export default class Header extends HeaderBase {
     @api langValuePath: string = "id"; // allows to override how language property is interpreted, follows valuePath dropdown api.
     @api headerHref: string = "/";
 
     @api
-    get scopedNavItems() {
-        return this._scopedNavItems;
+    get hideDocHeader() {
+        return this._hideDocHeader;
     }
 
-    set scopedNavItems(value) {
-        this._scopedNavItems = toJson(value);
+    set hideDocHeader(value) {
+        this._hideDocHeader = normalizeBoolean(value);
     }
 
     @api
-    get languages() {
-        return this._languages;
+    get scopedNavItems() {
+        return this._scopedNavItems;
     }
 
-    set languages(value) {
-        this._languages = toJson(value);
+    set scopedNavItems(value) {
+        this._scopedNavItems = toJson(value);
     }
 
     @api
-    get language() {
-        return this._language;
+    get devCenter(): DevCenterConfig {
+        return this._devCenter;
     }
 
-    set language(value) {
-        if (this._language !== value) {
-            this._language = value;
-        }
+    set devCenter(value) {
+        this._devCenter = toJson(value);
     }
 
-    private _language: string | null = null;
-    private _languages!: OptionWithLink[];
     private _scopedNavItems!: OptionWithNested[];
-    private smallMobile = false;
-    private smallMobileMatchMedia!: MediaQueryList;
     private tablet = false;
     private tabletMatchMedia!: MediaQueryList;
+    private shouldRender: boolean = false;
+    private showDocDivider: boolean = false;
+    private _devCenter!: DevCenterConfig;
+    private _hideDocHeader: boolean = false;
 
     protected mobileBreakpoint(): string {
         return MOBILE_MATCH;
     }
 
-    private get hasScopedNavItems(): boolean {
-        return this.scopedNavItems && this.scopedNavItems.length > 0;
-    }
-
-    private get showDesktopNavItems(): boolean {
-        return !this.mobile && this.hasNavItems;
-    }
-
-    private get showSignup(): boolean {
-        return this.signupLink
-            ? (this.tablet && !this.isSearchOpen) || !this.tablet
-            : false;
-    }
-
-    private get hasLanguages(): boolean {
-        return !!(this.languages && this.languages.length);
-    }
-
-    private get showMobileLanguages(): boolean {
-        return this.smallMobile && this.hasLanguages;
-    }
-
-    private get languageLabel(): string {
+    private get showScopedNavItems(): boolean {
         return (
-            (this.language &&
-                this.languages.find(
-                    (lang) => get(lang, this.langValuePath) === this.language
-                )?.label) ||
-            this.languages[0].label
+            this.scopedNavItems &&
+            this.scopedNavItems.length > 0 &&
+            !this.hideDocHeader
         );
     }
 
-    private get showMenuButton(): boolean {
-        return this.mobile && this.hasNavItems;
+    /**
+     * This function returns true if the hideDocHeader is true and the view is not mobile.
+     * Also we need to show the header border in case the doc is hidden or if the brand information doesn't exists.
+     */
+    private get shouldHideHeader(): boolean {
+        return (this.hideDocHeader && !this.mobile) || this.showDocDivider;
     }
 
     connectedCallback(): void {
@@ -98,14 +81,23 @@ export default class Header extends HeaderBase {
         this.onTabletChange(this.tabletMatchMedia);
         this.tabletMatchMedia.addEventListener("change", this.onTabletChange);
 
-        this.smallMobileMatchMedia = window.matchMedia(
-            `(max-width: ${SMALL_MOBILE_MATCH})`
-        );
-        this.onSmallMobileChange(this.smallMobileMatchMedia);
-        this.smallMobileMatchMedia.addEventListener(
-            "change",
-            this.onSmallMobileChange
-        );
+        if (
+            (!this.shouldHideHeader &&
+                window.location.pathname.includes("/docs/") &&
+                window.location.pathname !== "/docs/apis") ||
+            window.location.pathname ===
+                "/tableau/embedding-playground/overview" ||
+            isStorybook()
+        ) {
+            this.shouldRender = true;
+        }
+
+        if (this.shouldRender && window.location.pathname.includes("/docs/")) {
+            if (!this.brand && !this.mobile) {
+                this.shouldRender = false;
+                this.showDocDivider = true;
+            }
+        }
     }
 
     disconnectedCallback(): void {
@@ -114,29 +106,15 @@ export default class Header extends HeaderBase {
             "change",
             this.onTabletChange
         );
-
-        this.smallMobileMatchMedia.removeEventListener(
-            "change",
-            this.onSmallMobileChange
-        );
     }
 
     private onTabletChange = (e: MediaQueryListEvent | MediaQueryList) =>
         (this.tablet = e.matches);
 
-    private onSmallMobileChange = (e: MediaQueryListEvent | MediaQueryList) =>
-        (this.smallMobile = e.matches);
-
     protected additionalClasses(): string {
         return cx(
             this.brand && "has-brand",
-            this.hasScopedNavItems && "has-scoped-nav-items"
+            this.showScopedNavItems && "has-scoped-nav-items"
         );
     }
-
-    private onLangChange(event: CustomEvent<string>): void {
-        const { detail } = event;
-        this._language = detail;
-        this.dispatchEvent(new CustomEvent("langchange", { detail }));
-    }
 }

package/src/modules/doc/heading/heading.css

@@ -1,54 +1,33 @@
-h1,
-h2,
-h3,
-h4,
-h5,
-h6 {
-    color: var(--dx-g-blue-vibrant-20);
-    font-family: var(--dx-g-font-display);
-    font-weight: var(--dx-g-font-demi);
-}
+@import "dxHelpers/text";
 
-.display-3 {
-    margin: 0 0 24px 0;
-    font-size: var(--dx-g-text-3xl);
-    letter-spacing: -0.85px;
-    line-height: var(--dx-g-text-4xl);
+h1 {
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
 }
 
-.display-3 doc-heading-content {
-    --doc-c-heading-anchor-button-bottom: 8px;
+h1 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: 9.5px;
 }
 
-.display-4 {
-    margin: var(--dx-g-spacing-xl) 0 var(--dx-g-spacing-md) 0;
-    font-size: var(--dx-g-text-xl);
-    letter-spacing: -0.1px;
-    line-height: var(--dx-g-spacing-lg);
+h2 {
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
 }
 
-.display-4 doc-heading-content {
-    --doc-c-heading-anchor-button-bottom: -3px;
+h2 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: 3px;
 }
 
-.display-5 {
-    margin: var(--dx-g-spacing-lg) 0 var(--dx-g-spacing-md) 0;
-    font-size: var(--dx-g-text-lg);
-    letter-spacing: -0.1px;
-    line-height: var(--dx-g-spacing-lg);
+h3 {
+    margin: var(--dx-g-spacing-xl) 0 var(--dx-g-spacing-md) 0;
 }
 
-.display-5 doc-heading-content {
-    --doc-c-heading-anchor-button-bottom: -4px;
+h3 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: -0.5px;
 }
 
-.display-6 {
-    margin: var(--dx-g-spacing-md) 0 var(--dx-g-spacing-sm) 0;
-    font-size: var(--dx-g-text-base);
-    letter-spacing: 0;
-    line-height: var(--dx-g-spacing-mlg);
+h4 {
+    margin: var(--dx-g-spacing-lg) 0 var(--dx-g-spacing-sm) 0;
 }
 
-.display-6 doc-heading-content {
+h4 doc-heading-content {
     --doc-c-heading-anchor-button-bottom: -6px;
 }

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

@@ -23,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;

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

@@ -1,7 +1,7 @@
 <template>
-    <template if:false={hash}>{title}</template>
+    <template if:false={hash}>{header}</template>
     <template if:true={hash}>
-        <span class="title">{title}&nbsp;</span>
+        <span class="title">{header}&nbsp;</span>
         <dx-tooltip placement="top" label={label}>
             <span class="button-container">
                 <button onclick={copy} aria-label="copy">

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

@@ -1,7 +1,7 @@
 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";
@@ -18,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,168 @@
+import ContentLayout from "doc/contentLayout";
+
+const TOC_HEADER_TAG = "doc-heading";
+const RNB_BY_TAB = "docs-tab";
+const SPECIFICATION_TAB_TITLE = "Specification";
+export const OBSERVER_ATTACH_WAIT_TIME = 500;
+
+export default class LwcContentLayout extends ContentLayout {
+    private rnbByTab: boolean = false;
+
+    private setRNBByTab() {
+        const tabPanelListItem: any = this.getTabPanelList();
+        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB ? true : false;
+    }
+
+    get showTabBasedRNB() {
+        return this.rnbByTab;
+    }
+
+    onRNBClick = (event: CustomEvent) => {
+        event.stopPropagation();
+        const currentTab = this.getSelectedTabId();
+        if (currentTab === SPECIFICATION_TAB_TITLE) {
+            this.didScrollToSelectedHash = false;
+        }
+    };
+
+    onTabChanged = () => {
+        this.updateRNB();
+    };
+
+    private getTabPanelList() {
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        return document.querySelector("dx-tab-panel-list");
+    }
+
+    protected getHeadingElements() {
+        let headingElements = super.getHeadingElements();
+        if (this.showTabBasedRNB) {
+            const tabPanelListItem: any = 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);
+            }
+        });
+    }
+
+    private getAllTabs(): any[] {
+        const tabPanelListItem: any = this.getTabPanelList();
+        if (tabPanelListItem?.shadowRoot) {
+            return Array.from(
+                tabPanelListItem.shadowRoot.querySelectorAll(
+                    "dx-tab-panel-item"
+                )
+            ).map((tabPanelItem: any) =>
+                tabPanelItem.shadowRoot.querySelector("button")
+            );
+        }
+        return [];
+    }
+
+    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);
+        }
+    }
+
+    updateHeadingForRNB(): void {
+        // We only need to update URL in case of /docs and ignore if tabs are used anywhere else in DSC
+        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);
+    }
+}