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

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

@@ -1,12 +1,40 @@
-@import "helpers/commonHeader";
+@import "dxHelpers/commonHeader";
 
 dx-logo {
     min-width: fit-content;
-    min-width: -moz-fit-content;
+}
+
+.dev-center-link {
+    display: inline-block;
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg) 0
+        var(--dx-g-global-header-padding-horizontal);
+    height: var(--dx-g-spacing-xl);
+}
+
+.dev-center-content {
+    display: flex;
+    align-items: center;
+    text-decoration: none;
+    color: inherit;
+    font-weight: var(--dx-g-font-bold);
+}
+
+dx-icon {
+    --dx-c-icon-size: var(--dx-g-icon-size-xs);
+    --dx-c-icon-color: var(--dx-g-blue-vibrant-20);
+}
+
+.dev-center-content > * + * {
+    margin-left: 8px; /* Adjust this value to your desired spacing */
 }
 
 .header_l2 {
     justify-content: space-between;
+    height: var(--dx-g-doc-header-main-nav-height);
+}
+
+.has-brand .header_l2 {
+    height: var(--dx-g-spacing-3xl);
 }
 
 .nav_menu-button {
@@ -16,84 +44,89 @@ dx-logo {
     );
 }
 
+.has-brand.has-scoped-nav-items {
+    border-bottom: 1px solid var(--dx-g-gray-90);
+    border-top: 1px solid var(--dx-g-gray-90);
+}
+
 .nav_menu-ctas {
     margin-right: var(--dx-g-spacing-sm);
 }
 
 header:not(.has-brand) > .header_l1 {
-    background: var(--dx-g-brand-current-color-background);
+    background: white;
+    border-bottom: 1px solid var(--dx-g-gray-90);
 }
 
 header:not(.has-brand) > .header_l2 {
-    background: var(--dx-g-brand-current-color-background-2);
+    border-bottom: 1px solid var(--dx-g-gray-90);
+    border-top: 1px solid var(--dx-g-gray-90);
 }
 
 .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);
+.has-brand .header_l2_group-title {
+    padding: var(--dx-g-spacing-sm) var(--dx-g-spacing-xl)
+        calc(var(--dx-g-spacing-smd) - 1px) 0;
+    min-width: 320px;
 }
 
-.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);
+.no-header-content {
+    border-top: 1px solid var(--dx-g-gray-90);
 }
 
-@media (max-width: 740px) {
+@media (max-width: 768px) {
     .header_l2 {
         padding: 0;
         flex-wrap: wrap;
+        height: 100%;
+    }
+
+    .has-nav-items .header_l2 {
+        height: initial;
     }
 
     .header_l2_group {
         width: 100%;
     }
 
+    .header_l2_group-title {
+        margin-right: 0;
+        padding: var(--dx-g-spacing-sm) 0 2px
+            var(--dx-g-global-header-padding-horizontal);
+        min-height: var(--dx-g-doc-header-main-nav-height);
+    }
+
     .header_l2_group-nav {
         height: var(--dx-g-spacing-3xl);
         padding: 0;
-        padding-left: var(--dx-g-spacing-sm);
+        margin-top: calc(var(--dx-g-spacing-2xs) + 1px);
     }
 
     .header_l2_group-nav_overflow {
+        height: var(--dx-g-spacing-3xl);
         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);
+    .subtitle {
+        font-weight: var(--dx-g-font-demi);
+        letter-spacing: -0.08px;
     }
 
-    .header_l2_group-title .header_lang-dropdown {
-        margin-left: auto;
-    }
-
-    .header_lang-dropdown > dx-button {
-        padding: var(--dx-g-spacing-2xs) 0;
+    .has-brand .header_l2_group-title {
+        margin-right: 0;
+        padding: var(--dx-g-spacing-sm) 0 var(--dx-g-spacing-2xs)
+            var(--dx-g-global-header-padding-horizontal);
     }
 
     .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);
+    header:not(.has-brand) > .header_l2 {
+        padding-bottom: 0;
+        border: 0;
     }
 }

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

@@ -1,152 +1,55 @@
 <template>
-    <dx-brand-theme-provider brand={brand}>
-        <header class={className}>
-            <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">
+    <template lwc:if={shouldRender}>
+        <dx-brand-theme-provider brand={brand}>
+            <header class={className}>
+                <dx-banner
+                    lwc:if={showBanner}
+                    banner-markup={bannerMarkup}
+                ></dx-banner>
+                <!-- To-Do: Move the devCenter as a new component and use it here, as devCenter is also used in Sidebar now -->
+                <div lwc:if={devCenter} class="dev-center-link">
+                    <a href={devCenter.link} class="dev-center-content">
+                        <dx-icon symbol="back"></dx-icon>
                         <dx-icon
                             class="brand-icon"
-                            if:true={isValidBrand}
+                            lwc:if={devCenter.icon}
                             sprite="salesforcebrand"
                             symbol={brand}
-                            size="xlarge"
+                            size="large"
                         ></dx-icon>
-                        <span class="subtitle dx-text-heading-4">
-                            {subtitle}
+                        <span class="subtitle dx-text-body-4">
+                            {devCenter.title}
                         </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 class="header_l2">
+                    <div class="header_l2_group header_l2_group-title">
+                        <a href={headerHref} class="home-link">
+                            <span class="subtitle dx-text-display-7">
+                                {subtitle}
+                            </span>
+                        </a>
                     </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}
+                    <div
+                        lwc:if={showScopedNavItems}
+                        class="header_l2_group header_l2_group-nav"
                     >
-                        <dx-button
-                            aria-label="Select Language"
-                            variant="inline"
-                            icon-size="small"
-                            icon-symbol="world"
+                        <div
+                            class="header_l2_group-nav_overflow"
+                            onscroll={onNavScroll}
                         >
-                            {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>
+                            <dx-header-nav
+                                aria-label="Scoped Navigation Bar"
+                                nav-items={scopedNavItems}
+                                pathname={pathname}
+                            ></dx-header-nav>
+                        </div>
+                    </div>
                 </div>
-            </div>
-        </header>
-    </dx-brand-theme-provider>
+            </header>
+        </dx-brand-theme-provider>
+    </template>
+    <template lwc:if={shouldHideHeader}>
+        <div class="no-header-content"></div>
+    </template>
 </template>

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

@@ -1,93 +1,76 @@
 import { api } from "lwc";
 import cx from "classnames";
-import type { Option } from "typings/custom";
-import { HeaderBase } from "utils/headerBase";
-import { toJson } from "utils/normalizers";
-import get from "lodash.get";
+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 = "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!: Option[];
-    private _scopedNavItems!: Option[];
-    private smallMobile = false;
-    private smallMobileMatchMedia!: MediaQueryList;
+    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 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

@@ -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}`;
+    }
+}