@salesforcedevs/docs-components 0.0.7 → 0.0.9-edit

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

@@ -0,0 +1,120 @@
+import { api } from "lwc";
+import cx from "classnames";
+import type { OptionWithNested, DevCenterConfig } from "typings/custom";
+import { HeaderBase } from "dxBaseElements/headerBase";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
+
+const TABLET_MATCH = "980px";
+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 hideDocHeader() {
+        return this._hideDocHeader;
+    }
+
+    set hideDocHeader(value) {
+        this._hideDocHeader = normalizeBoolean(value);
+    }
+
+    @api
+    get scopedNavItems() {
+        return this._scopedNavItems;
+    }
+
+    set scopedNavItems(value) {
+        this._scopedNavItems = toJson(value);
+    }
+
+    @api
+    get devCenter(): DevCenterConfig {
+        return this._devCenter;
+    }
+
+    set devCenter(value) {
+        this._devCenter = toJson(value);
+    }
+
+    private _scopedNavItems!: OptionWithNested[];
+    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 showScopedNavItems(): boolean {
+        return (
+            this.scopedNavItems &&
+            this.scopedNavItems.length > 0 &&
+            !this.hideDocHeader
+        );
+    }
+
+    /**
+     * 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 {
+        super.connectedCallback();
+        this.tabletMatchMedia = window.matchMedia(
+            `(max-width: ${TABLET_MATCH})`
+        );
+        this.onTabletChange(this.tabletMatchMedia);
+        this.tabletMatchMedia.addEventListener("change", this.onTabletChange);
+
+        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 {
+        super.disconnectedCallback();
+        this.tabletMatchMedia.removeEventListener(
+            "change",
+            this.onTabletChange
+        );
+    }
+
+    private onTabletChange = (e: MediaQueryListEvent | MediaQueryList) =>
+        (this.tablet = e.matches);
+
+    protected additionalClasses(): string {
+        return cx(
+            this.brand && "has-brand",
+            this.showScopedNavItems && "has-scoped-nav-items"
+        );
+    }
+}

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

@@ -0,0 +1,33 @@
+@import "dxHelpers/text";
+
+h1 {
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
+}
+
+h1 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: 9.5px;
+}
+
+h2 {
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
+}
+
+h2 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: 3px;
+}
+
+h3 {
+    margin: var(--dx-g-spacing-xl) 0 var(--dx-g-spacing-md) 0;
+}
+
+h3 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: -0.5px;
+}
+
+h4 {
+    margin: var(--dx-g-spacing-lg) 0 var(--dx-g-spacing-sm) 0;
+}
+
+h4 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: -6px;
+}

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

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

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

@@ -0,0 +1,67 @@
+import { LightningElement, api } from "lwc";
+
+export const ariaDisplayLevels: { [key: string]: string } = {
+    "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 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) {
+        if (value && !ariaLevels.includes(value)) {
+            console.error(`Invalid aria-level: "${value}"`);
+            return;
+        }
+        if (value) {
+            this._ariaLevel = value;
+        }
+    }
+
+    @api
+    private get displayLevel(): string {
+        return this._displayLevel || ariaDisplayLevels[this.ariaLevel];
+    }
+    private set displayLevel(value: string | null) {
+        if (value && !displayLevels.includes(value)) {
+            console.error(`Invalid display-level: "${value}"`);
+            value = null;
+        }
+        if (value) {
+            this._displayLevel = value;
+        }
+    }
+
+    private _ariaLevel: string | null = null;
+    private _displayLevel: string | null = null;
+
+    private get isAriaLevelOne(): boolean {
+        return this.ariaLevel === "1";
+    }
+    private get isAriaLevelTwo(): boolean {
+        return this.ariaLevel === "2";
+    }
+    private get isAriaLevelThree(): boolean {
+        return this.ariaLevel === "3";
+    }
+    private get isAriaLevelFour(): boolean {
+        return this.ariaLevel === "4";
+    }
+
+    private get className(): string {
+        return `dx-text-display-${this.displayLevel}`;
+    }
+}

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

@@ -0,0 +1,33 @@
+@import "dxHelpers/reset";
+
+button {
+    opacity: 0;
+    color: rgb(11 92 171);
+}
+
+button:hover {
+    opacity: 1;
+    outline: none;
+}
+
+button:focus {
+    opacity: 1;
+    outline: none;
+}
+
+button:focus-visible {
+    border-radius: 4px;
+    border: 2px solid rgb(11 92 171);
+}
+
+.icon-wrapper {
+    height: 32px;
+    width: 32px;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+}
+
+.icon-container {
+    --dx-c-icon-size: 18px;
+}

package/src/modules/doc/headingAnchor/headingAnchor.html

@@ -0,0 +1,19 @@
+<template>
+    <dx-tooltip placement="top" label={label}>
+        <button
+            onclick={onIconClick}
+            aria-label={ariaLabel}
+            onkeydown={onKeyDown}
+            part="headingAnchorIcon"
+        >
+            <div class="icon-wrapper">
+                <dx-icon
+                    sprite={iconSprite}
+                    size={iconSize}
+                    symbol={iconSymbol}
+                    class="icon-container"
+                ></dx-icon>
+            </div>
+        </button>
+    </dx-tooltip>
+</template>

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

@@ -0,0 +1,43 @@
+import { LightningElement, api } from "lwc";
+import { IconSprite, IconSize, IconSymbol } from "typings/custom";
+
+export default class HeadingAnchor extends LightningElement {
+    @api ariaLabel: string = "copy";
+    @api iconSize?: IconSize = "override";
+    @api iconSprite?: IconSprite = "utility";
+    @api iconSymbol?: IconSymbol;
+    @api header: string = "";
+    @api urlText: string = "";
+
+    label: string = "Copy link to clipboard";
+
+    private async onIconClick() {
+        await this.iconClickHandler();
+    }
+
+    private async iconClickHandler() {
+        this.label = "Copied";
+        setTimeout(() => {
+            this.label = "Copy link to clipboard";
+        }, 2000);
+
+        try {
+            if (this.header && this.urlText) {
+                const [hostUrl] = window.location.href.split("#");
+                const url = `${hostUrl}#${this.urlText}`;
+                await navigator.clipboard.writeText(url);
+            }
+        } catch (error) {
+            console.error(error);
+        }
+    }
+
+    private async onKeyDown(e: KeyboardEvent) {
+        switch (e.key) {
+            case "Enter":
+                await this.iconClickHandler();
+                break;
+            default:
+        }
+    }
+}

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,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/nav/nav.css

@@ -7,6 +7,8 @@
     width: 100%;
 }
 
-doc-toc {
-    margin-top: 15px;
+dx-sidebar {
+    --dx-c-sidebar-width: unset;
+
+    display: block;
 }

package/src/modules/doc/nav/nav.ts

@@ -8,7 +8,7 @@ import {
     SelectedNavigationItem,
     SelectedLanguage,
     SelectedVersion
-} from "../../../../../../../typings/custom";
+} from "typings/custom";
 
 export default class Nav extends LightningElement {
     @api availableLanguages!: AvailableLanguages;