@salesforcedevs/docs-components 0.0.1

package/src/modules/doc/contentLayout/contentLayout.ts

@@ -0,0 +1,322 @@
+import { LightningElement, api, track } from "lwc";
+import { closest } from "kagekiri";
+import { toJson } from "dxUtils/normalizers";
+import { highlightTerms } from "dxUtils/highlight";
+import { SearchSyncer } from "docUtils/SearchSyncer";
+
+type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
+
+const TOC_HEADER_TAG = "DOC-HEADING";
+const HIGHLIGHTABLE_SELECTOR = [
+    "p",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "li",
+    "dl",
+    "th",
+    "td"
+].join(",");
+const OBSERVER_ATTACH_WAIT_TIME = 500;
+
+export default class ContentLayout extends LightningElement {
+    @api sidebarValue: string;
+    @api sidebarHeader: string;
+    @api tocTitle: string;
+    @api enableSlotChange = false;
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoSearchHub!: string;
+    @api coveoAdvancedQueryConfig!: string;
+    @api useOldSidebar?: boolean = false;
+
+    @api
+    get breadcrumbs() {
+        return this._breadcrumbs;
+    }
+
+    set breadcrumbs(value): [] {
+        if (value) {
+            this._breadcrumbs = toJson(value);
+        }
+    }
+
+    @api
+    get sidebarContent() {
+        return this._sidebarContent;
+    }
+
+    set sidebarContent(value) {
+        this._sidebarContent = toJson(value);
+    }
+
+    @api
+    get tocOptions() {
+        return this._tocOptions;
+    }
+
+    set tocOptions(value) {
+        this._tocOptions = toJson(value);
+    }
+
+    @api
+    setSidebarInputValue(searchTerm: string): void {
+        this.template.querySelector("dx-sidebar")?.setInputValue(searchTerm);
+    }
+
+    @track
+    private _sidebarContent: unknown;
+
+    private _breadcrumbs = null;
+
+    @track
+    private _tocOptions: Array<unknown>;
+
+    private anchoredElements: AnchorMap = {};
+    private lastScrollPosition: number;
+    private observer?: IntersectionObserver;
+    private hasRendered: boolean = false;
+
+    private searchSyncer = new SearchSyncer({
+        callbacks: {
+            onUrlChange: (nextSearchString: string): void => {
+                this.updateHighlightsAndSearch(nextSearchString);
+            },
+            onSearchChange: (nextSearchString: string): void => {
+                this.dispatchHighlightChange(
+                    new URLSearchParams(nextSearchString).get("q") || ""
+                );
+            }
+        },
+        eventName: "sidebarsearchchange",
+        historyMethod: window.history.pushState,
+        searchParam: "q",
+        shouldStopPropagation: true,
+        target: window
+    });
+    private tocValue?: string = undefined;
+    private observerTimerId = null;
+    private didScrollToSelectedHash = false;
+    private _scrollInterval = 0;
+
+    get showToc(): boolean {
+        return this.tocOptions && this.tocOptions.length > 0;
+    }
+
+    // ? This could be a good default for pathname in dx-breadcrumbs. Using this getter for now as a workaround.
+    get pathname(): string {
+        return window.location.pathname;
+    }
+
+    get showBreadcrumbs(): boolean {
+        return (
+            this.breadcrumbs != null && (this.breadcrumbs as any[]).length > 1
+        );
+    }
+
+    get docContentStyle(): string {
+        return this.showBreadcrumbs ? "" : "margin-top: 48px";
+    }
+
+    connectedCallback(): void {
+        const hasParentHighlightListener = closest(
+            "doc-xml-content",
+            this.template.host
+        );
+        if (!hasParentHighlightListener) {
+            window.addEventListener(
+                "highlightedtermchange",
+                this.updateHighlighted
+            );
+            this.searchSyncer.init();
+        }
+
+        this._scrollInterval = window.setInterval(() => {
+            this.saveScroll();
+        }, 1000);
+    }
+
+    renderedCallback(): void {
+        /**
+         * Note: We are adding timeout because chrome is optimizing and not triggering recent renderedCallback though elements reference is changed
+         * Also we are considering recent renderedCallback
+         */
+        this.clearRenderObserverTimer();
+        this.observerTimerId = setTimeout(
+            this.attachInteractionObserver,
+            OBSERVER_ATTACH_WAIT_TIME
+        );
+        if (!this.hasRendered) {
+            this.hasRendered = true;
+            this.restoreScroll();
+        }
+    }
+
+    disconnectedCallback(): void {
+        this.disconnectObserver();
+        window.removeEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+        this.searchSyncer.dispose();
+        this.clearRenderObserverTimer();
+
+        window.clearInterval(this._scrollInterval);
+    }
+
+    saveScroll() {
+        window.history.replaceState(
+            { scrollValue: document.body.scrollTop },
+            "",
+            window.location.href
+        );
+    }
+
+    restoreScroll() {
+        document.body.scrollTop = document.documentElement.scrollTop =
+            window.history.state?.scrollValue;
+    }
+
+    clearRenderObserverTimer = () => {
+        if (this.observerTimerId) {
+            clearTimeout(this.observerTimerId);
+        }
+    };
+
+    updateHighlighted = (event: Event): void =>
+        highlightTerms(
+            this.querySelectorAll(HIGHLIGHTABLE_SELECTOR),
+            (event as CustomEvent<string>).detail
+        );
+
+    attachInteractionObserver = (): void => {
+        if (!this.enableSlotChange) {
+            return;
+        }
+        this.disconnectObserver();
+        this.observer = new IntersectionObserver((entries) => {
+            entries.forEach(
+                (entry) =>
+                    (this.anchoredElements[
+                        entry.target.getAttribute("id")
+                    ].intersect = entry.isIntersecting)
+            );
+            this.calculateActualSection();
+        });
+
+        // Note: We are doing document.querySelectorAll as a quick fix as we are not getting heading elements reference this.querySelectorAll
+        const headingElements = document.querySelectorAll(TOC_HEADER_TAG);
+        for (const headingElement of headingElements) {
+            // Add headingElements to intersectionObserver for highlighting respective RNB item when user scroll
+            const id = headingElement.getAttribute("id");
+            this.anchoredElements[id] = {
+                id,
+                intersect: false
+            };
+            this.observer.observe(headingElement);
+        }
+        if (!this.didScrollToSelectedHash) {
+            this.didScrollToSelectedHash = true;
+            this.scrollToHash(headingElements);
+        }
+    };
+
+    onSlotChange(event: Event): void {
+        const slotElements = (
+            event.target as HTMLSlotElement
+        ).assignedElements();
+
+        if (slotElements.length) {
+            const slotContentElement = slotElements[0];
+            const headingElements =
+                slotContentElement.ownerDocument?.getElementsByTagName(
+                    TOC_HEADER_TAG
+                );
+            for (const headingElement of headingElements) {
+                // Sometimes elements hash is not being set when slot content is wrapped with div
+                headingElement.hash = headingElement.attributes.hash?.nodeValue;
+            }
+            const tocOptions = [];
+            for (const headingElement of headingElements) {
+                headingElement.id = headingElement.hash;
+
+                // Update tocOptions from anchorTags
+                const tocItem = {
+                    anchor: `#${headingElement.hash}`,
+                    id: headingElement.id,
+                    label: headingElement.title
+                };
+                tocOptions.push(tocItem);
+            }
+
+            this._tocOptions = tocOptions;
+        }
+    }
+
+    private disconnectObserver(): void {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+    }
+
+    // eslint-disable-next-line no-undef
+    private scrollToHash(headingElements: NodeListOf<Element>): void {
+        let { hash } = window.location;
+        if (hash) {
+            hash = hash.substr(1);
+            for (const headingElement of headingElements) {
+                if (headingElement.getAttribute("id") === hash) {
+                    headingElement.scrollIntoView({ behavior: "auto" });
+                    break;
+                }
+            }
+        }
+    }
+
+    private calculateActualSection(): void {
+        const currentScrollPosition = document.documentElement.scrollTop;
+        const id = Object.keys(this.anchoredElements).find(
+            (_id) => this.anchoredElements[_id].intersect
+        );
+        if (id) {
+            this.assignElementId(id);
+        } else if (currentScrollPosition < this.lastScrollPosition) {
+            // The user has scroll up since last update
+            this.assignElementId(this.calculatePreviousElementId());
+        }
+
+        this.lastScrollPosition = currentScrollPosition;
+    }
+
+    private calculatePreviousElementId(): string {
+        const keys = Object.keys(this.anchoredElements);
+        const currentIndex = keys.findIndex((id) => this.tocValue === id);
+
+        return currentIndex > 0 ? keys[currentIndex - 1] : undefined;
+    }
+
+    private assignElementId(id: string): void {
+        this.tocValue = id;
+    }
+
+    private dispatchHighlightChange(term: string): void {
+        this.dispatchEvent(
+            new CustomEvent("highlightedtermchange", {
+                detail: term,
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+
+    private updateHighlightsAndSearch(nextSearchString: string): void {
+        const nextSearchParam =
+            new URLSearchParams(nextSearchString).get("q") || "";
+        this.setSidebarInputValue(nextSearchParam);
+        this.dispatchHighlightChange(nextSearchParam);
+    }
+}

package/src/modules/doc/contentMedia/contentMedia.css

@@ -0,0 +1,49 @@
+:host {
+    --aspect-ratio: 9 / 16; /* the vertical axis is the first number */
+}
+
+.content-media-wrapper {
+    margin: 36px 0;
+}
+
+.content-media-title {
+    color: var(--dx-g-blue-vibrant-20);
+    font-size: var(--dx-g-text-base);
+    font-family: var(--dx-g-font-display);
+    font-weight: 500;
+    background-color: var(--sds-g-gray-4);
+    padding: var(--dx-g-spacing-sm) var(--dx-g-spacing-smd);
+    border-top-left-radius: 4px;
+    border-top-right-radius: 4px;
+}
+
+.content-media-image,
+.content-media-iframe {
+    border: 1px solid var(--dx-g-gray-90);
+}
+
+.content-media-image img {
+    display: block;
+    width: 100%;
+}
+
+.content-media-iframe {
+    position: relative;
+    padding-bottom: calc(var(--aspect-ratio, 0.5625) * 100%);
+    height: 0;
+}
+
+.content-media-iframe iframe {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+}
+
+.content-media-caption {
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-xs);
+    margin-top: var(--dx-g-spacing-sm);
+    margin-left: var(--dx-g-spacing-smd);
+}

package/src/modules/doc/contentMedia/contentMedia.html

@@ -0,0 +1,23 @@
+<template>
+    <div class="content-media-wrapper">
+        <div class="content-media-container">
+            <div if:true={mediaTitle} class="content-media-title">
+                {mediaTitle}
+            </div>
+            <div class={mediaWrapperClass}>
+                <img if:true={isImage} src={contentSrc} alt={mediaTitle} />
+                <iframe
+                    if:true={isIframe}
+                    title={frameTitle}
+                    width="560"
+                    height="315"
+                    src={contentSrc}
+                    frameborder="0"
+                    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+                    allowfullscreen
+                ></iframe>
+            </div>
+        </div>
+        <div if:true={caption} class="content-media-caption">{caption}</div>
+    </div>
+</template>

package/src/modules/doc/contentMedia/contentMedia.ts

@@ -0,0 +1,34 @@
+import { LightningElement, api } from "lwc";
+
+export default class ContentMedia extends LightningElement {
+    @api mediaTitle?: string = undefined;
+    @api contentSrc?: string = undefined;
+    @api contentType?: "image" | "iframe" = undefined;
+    @api iframeSrc?: string = undefined;
+    @api caption?: string = undefined;
+
+    get mediaWrapperClass(): string {
+        return this.contentType === "image"
+            ? "content-media-image"
+            : "content-media-iframe";
+    }
+
+    get frameTitle(): string {
+        if (!this.mediaTitle) {
+            console.error(
+                "media-title must be specified when using iframe-src attribute."
+            );
+            return "Embedded iframe";
+        }
+
+        return this.mediaTitle;
+    }
+
+    get isImage(): boolean {
+        return this.contentType === "image";
+    }
+
+    get isIframe(): boolean {
+        return this.contentType === "iframe";
+    }
+}

package/src/modules/doc/header/header.css

@@ -0,0 +1,103 @@
+@import "dxHelpers/commonHeader";
+
+dx-logo {
+    min-width: fit-content;
+    min-width: -moz-fit-content;
+}
+
+.header_l2 {
+    justify-content: space-between;
+}
+
+.nav_menu-button {
+    --dx-c-button-primary-color: var(--dx-g-blue-vibrant-20);
+    --dx-c-button-secondary-color-hover: var(
+        --dx-g-brand-default-button-color-background-inactive
+    );
+}
+
+.nav_menu-ctas {
+    margin-right: var(--dx-g-spacing-sm);
+}
+
+header:not(.has-brand) > .header_l1 {
+    background: var(--dx-g-brand-current-color-background);
+}
+
+header:not(.has-brand) > .header_l2 {
+    background: var(--dx-g-brand-current-color-background-2);
+}
+
+.header_l2_group.header_l2_group-right-ctas {
+    align-items: baseline;
+}
+
+.header_bail-link {
+    --dx-c-button-horizontal-spacing: var(--dx-g-spacing-sm);
+
+    margin-left: var(--dx-g-spacing-sm);
+}
+
+.header_lang-dropdown {
+    --button-primary-color: var(--dx-g-blue-vibrant-50);
+    --button-primary-color-hover: var(--dx-g-blue-vibrant-40);
+}
+
+.header_lang-dropdown > dx-button {
+    --dx-c-button-primary-color: var(--button-primary-color);
+    --dx-c-button-primary-color-hover: var(--button-primary-color-hover);
+    --dx-c-slot-empty-width: min-content;
+    --border-color: var(--button-primary-color);
+
+    border-bottom: 1px dashed var(--border-color);
+}
+
+.header_lang-dropdown > dx-button:hover {
+    --border-color: var(--button-primary-color-hover);
+}
+
+@media (max-width: 740px) {
+    .header_l2 {
+        padding: 0;
+        flex-wrap: wrap;
+    }
+
+    .has-nav-items .header_l2 {
+        height: initial;
+    }
+
+    .header_l2_group {
+        width: 100%;
+    }
+
+    .header_l2_group-nav {
+        height: var(--dx-g-spacing-3xl);
+        padding: 0;
+        padding-left: var(--dx-g-spacing-sm);
+    }
+
+    .header_l2_group-nav_overflow {
+        margin-right: var(--dx-g-spacing-sm);
+    }
+
+    .header_l2_group-title {
+        margin-right: 0;
+        padding: var(--dx-g-spacing-smd) var(--dx-g-page-padding-horizontal);
+    }
+
+    .header_l2_group-title .header_lang-dropdown {
+        margin-left: auto;
+    }
+
+    .header_lang-dropdown > dx-button {
+        padding: var(--dx-g-spacing-2xs) 0;
+    }
+
+    .has-scoped-nav-items > .header_l2 {
+        height: unset;
+    }
+
+    .has-scoped-nav-items .header_l2_group-title {
+        border-bottom: 1px solid var(--dx-g-brand-current-color-border-2);
+    }
+}

package/src/modules/doc/header/header.html

@@ -0,0 +1,153 @@
+<template>
+    <dx-brand-theme-provider brand={brand}>
+        <header class={className}>
+            <dx-skip-nav-link></dx-skip-nav-link>
+            <dx-banner
+                if:true={bannerMarkup}
+                banner-markup={bannerMarkup}
+            ></dx-banner>
+            <div class="header_l1">
+                <div if:true={showMenuButton} class="nav_menu-ctas">
+                    <dx-button
+                        aria-label="Menu Button"
+                        class="nav_menu-button"
+                        icon-size="large"
+                        icon-symbol={mobileMenuIconSymbol}
+                        variant="tertiary"
+                        onclick={toggleMobileNavMenu}
+                    ></dx-button>
+                </div>
+                <dx-logo label={title}></dx-logo>
+                <dx-header-nav
+                    if:true={showDesktopNavItems}
+                    aria-label="Global Navigation Bar"
+                    nav-items={navItems}
+                    onrequestopennavmenu={onRequestOpenNavMenu}
+                    pathname={pathname}
+                    variant="small"
+                ></dx-header-nav>
+                <div class="header-cta-container">
+                    <dx-header-search
+                        if:true={hasSearch}
+                        coveo-organization-id={coveoOrganizationId}
+                        coveo-public-access-token={coveoPublicAccessToken}
+                        coveo-search-pipeline={coveoSearchPipeline}
+                        coveo-search-hub={coveoSearchHub}
+                        mobile={tablet}
+                        onstatechange={handleStateChange}
+                    ></dx-header-search>
+                </div>
+                <div if:true={showSignup} class="header-login-signup">
+                    <dx-button
+                        aria-label="Sign Up For Salesforce Developer Edition"
+                        size="small"
+                        href={signupLink}
+                        onclick={handleSignUpClick}
+                    >
+                        Sign Up
+                    </dx-button>
+                </div>
+                <dx-header-mobile-nav-menu
+                    if:true={hasNavItems}
+                    nav-items={navItems}
+                    open={showMobileNavMenu}
+                    pathname={pathname}
+                    value={mobileNavMenuValue}
+                    onchange={onMobileNavMenuChange}
+                    onrequestclose={closeMobileNavMenu}
+                >
+                    <dx-button
+                        aria-label={bailLabel}
+                        if:true={hasBailLink}
+                        href={bailHref}
+                        variant="tertiary"
+                        icon-symbol="new_window"
+                    >
+                        {bailLabel}
+                    </dx-button>
+                </dx-header-mobile-nav-menu>
+            </div>
+            <div class="header_l2">
+                <div class="header_l2_group header_l2_group-title">
+                    <a href={headerHref} class="home-link">
+                        <dx-icon
+                            class="brand-icon"
+                            if:true={isValidBrand}
+                            sprite="salesforcebrand"
+                            symbol={brand}
+                            size="xlarge"
+                        ></dx-icon>
+                        <span class="subtitle dx-text-heading-4">
+                            {subtitle}
+                        </span>
+                    </a>
+                    <dx-dropdown
+                        if:true={showMobileLanguages}
+                        class="header_lang-dropdown"
+                        options={languages}
+                        small
+                        value={language}
+                        value-path={langValuePath}
+                        onchange={onLangChange}
+                    >
+                        <dx-button
+                            aria-label="Select Language"
+                            variant="inline"
+                            icon-size="large"
+                            icon-symbol="world"
+                        ></dx-button>
+                    </dx-dropdown>
+                </div>
+                <div
+                    if:true={hasScopedNavItems}
+                    class="header_l2_group header_l2_group-nav"
+                >
+                    <div
+                        class="header_l2_group-nav_overflow"
+                        onscroll={onNavScroll}
+                    >
+                        <dx-header-nav
+                            aria-label="Scoped Navigation Bar"
+                            nav-items={scopedNavItems}
+                            pathname={pathname}
+                        ></dx-header-nav>
+                    </div>
+                </div>
+                <div
+                    if:false={smallMobile}
+                    class="header_l2_group header_l2_group-right-ctas"
+                >
+                    <dx-dropdown
+                        if:true={hasLanguages}
+                        class="header_lang-dropdown"
+                        options={languages}
+                        small
+                        value-path={langValuePath}
+                        value={language}
+                        onchange={onLangChange}
+                    >
+                        <dx-button
+                            aria-label="Select Language"
+                            variant="inline"
+                            icon-size="small"
+                            icon-symbol="world"
+                        >
+                            {languageLabel}
+                        </dx-button>
+                    </dx-dropdown>
+                    <dx-button
+                        if:true={hasBailLink}
+                        aria-label={bailLabel}
+                        class="header_bail-link"
+                        href={bailHref}
+                        variant="tertiary"
+                        icon-symbol="new_window"
+                        target="_blank"
+                    >
+                        {bailLabel}
+                    </dx-button>
+                </div>
+            </div>
+        </header>
+    </dx-brand-theme-provider>
+</template>