@salesforcedevs/docs-components 0.0.2 → 0.0.3-edit

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

@@ -3,6 +3,12 @@
     flex-direction: column;
 }
 
-doc-toc {
-    margin-top: 15px;
+.doc-navigation {
+    width: 100%;
+}
+
+dx-sidebar {
+    --dx-c-sidebar-width: unset;
+
+    display: block;
 }

package/src/modules/doc/nav/nav.html

@@ -1,9 +1,12 @@
 <template>
-    <doc-toolbar
-        languages={availableLanguages}
-        pdf-url={pdfUrl}
-        release-versions={availableVersions}
-    ></doc-toolbar>
-    <doc-search></doc-search>
-    <doc-toc toc={toc}></doc-toc>
+    <div class="doc-navigation">
+        <template if:true={toc}>
+            <dx-sidebar
+                header="Pages"
+                trees={toc}
+                onselect={handleSelected}
+                value={selectedNavigationItem}
+            ></dx-sidebar>
+        </template>
+    </div>
 </template>

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

@@ -1,35 +1,39 @@
 import { LightningElement, api } from "lwc";
+import {
+    AvailableLanguages,
+    AvailableVersions,
+    DocToc,
+    PageReference,
+    PdfUrl,
+    SelectedNavigationItem,
+    SelectedLanguage,
+    SelectedVersion
+} from "typings/custom";
 
-/**
- * @element doc-nav
- */
 export default class Nav extends LightningElement {
-    /*
+    @api availableLanguages!: AvailableLanguages;
+    @api selectedLanguage!: SelectedLanguage;
+    @api availableVersions!: AvailableVersions;
+    @api selectedVersion!: SelectedVersion;
+    @api selectedNavigationItem!: SelectedNavigationItem;
+    @api pdfUrl!: PdfUrl;
+    @api toc!: DocToc;
+    @api pageReference!: PageReference;
 
-    I've temporarily decoupled each property from docsData
-    
-    @api
-    set docsData(value: any) {
-        if (value.available_languages) {
-            this.availableLanguages = value.available_languages;
-        }
-        if (value.available_versions) {
-            this.availableVersions = value.available_versions;
-        }
-        if (value.pdf_url) {
-            this.pdfUrl = value.pdf_url;
-        }
-        if (value.toc) {
-            this.toc = value.toc;
-        }
+    handleSelected(event: CustomEvent) {
+        event.stopPropagation();
+        const newPageReference = { ...this.pageReference };
+        const target = event.detail.name.split("-");
+        newPageReference.contentDocumentId = target[0] + ".htm";
+        newPageReference.hash = target[1];
+        this.dispatchEvent(
+            new CustomEvent("navclick", {
+                detail: {
+                    pageReference: newPageReference
+                },
+                bubbles: true,
+                composed: true
+            })
+        );
     }
-    get docsData() {
-        return null;
-    }
-    */
-
-    @api availableLanguages = [];
-    @api availableVersions = [];
-    @api pdfUrl: string | undefined;
-    @api toc = [];
 }

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>