@salesforcedevs/docs-components 0.3.11 → 0.3.14-banner-alpha1

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

@@ -0,0 +1,160 @@
+<template>
+    <dx-brand-theme-provider brand={brand}>
+        <header class={className}>
+            <dx-skip-nav-link></dx-skip-nav-link>
+            <dx-banner
+                if:true={showBanner}
+                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={showTbidLogin}
+                    class="header-tbid-login"
+                    onclick={closeMobileNavMenu}
+                >
+                    <dw-tbid-login-menu></dw-tbid-login-menu>
+                </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>

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

@@ -0,0 +1,146 @@
+import { api } from "lwc";
+import cx from "classnames";
+import type { OptionWithNested, OptionWithLink } from "typings/custom";
+import { HeaderBase } from "dxBaseElements/headerBase";
+import { toJson } from "dxUtils/normalizers";
+import get from "lodash.get";
+
+const TABLET_MATCH = "980px";
+const MOBILE_MATCH = "880px";
+const SMALL_MOBILE_MATCH = "740px";
+
+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;
+    }
+
+    set scopedNavItems(value) {
+        this._scopedNavItems = toJson(value);
+    }
+
+    @api
+    get languages() {
+        return this._languages;
+    }
+
+    set languages(value) {
+        this._languages = toJson(value);
+    }
+
+    @api
+    get language() {
+        return this._language;
+    }
+
+    set language(value) {
+        if (this._language !== value) {
+            this._language = value;
+        }
+    }
+
+    private _language: string | null = null;
+    private _languages!: OptionWithLink[];
+    private _scopedNavItems!: OptionWithNested[];
+    private smallMobile = false;
+    private smallMobileMatchMedia!: MediaQueryList;
+    private tablet = false;
+    private tabletMatchMedia!: MediaQueryList;
+
+    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 showTbidLogin(): boolean {
+        return this.showSignup;
+    }
+
+    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 {
+        return (
+            (this.language &&
+                this.languages.find(
+                    (lang) => get(lang, this.langValuePath) === this.language
+                )?.label) ||
+            this.languages[0].label
+        );
+    }
+
+    private get showMenuButton(): boolean {
+        return this.mobile && this.hasNavItems;
+    }
+
+    connectedCallback(): void {
+        super.connectedCallback();
+        this.tabletMatchMedia = window.matchMedia(
+            `(max-width: ${TABLET_MATCH})`
+        );
+        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
+        );
+    }
+
+    disconnectedCallback(): void {
+        super.disconnectedCallback();
+        this.tabletMatchMedia.removeEventListener(
+            "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"
+        );
+    }
+
+    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,54 @@
+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);
+}
+
+.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);
+}
+
+.display-3 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: 8px;
+}
+
+.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);
+}
+
+.display-4 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);
+}
+
+.display-5 doc-heading-content {
+    --doc-c-heading-anchor-button-bottom: -4px;
+}
+
+.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);
+}
+
+.display-6 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 title={title} hash={hash}></doc-heading-content>
+    </h1>
+    <h2 class={className} if:true={isAriaLevelTwo}>
+        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+    </h2>
+    <h3 class={className} if:true={isAriaLevelThree}>
+        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+    </h3>
+    <h4 class={className} if:true={isAriaLevelFour}>
+        <doc-heading-content title={title} hash={hash}></doc-heading-content>
+    </h4>
+</template>

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

@@ -0,0 +1,65 @@
+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"
+};
+
+export default class Heading extends LightningElement {
+    @api title: string = "";
+    @api hash: string | null = null;
+
+    @api
+    private get ariaLevel(): string {
+        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 `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 title: 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.title && 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}>{title}</template>
+    <template if:true={hash}>
+        <span class="title">{title}&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 title: 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.title && 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/phase/phase.css

@@ -0,0 +1,55 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "docHelpers/status";
+
+.doc-phase-container {
+    display: flex;
+    flex-direction: column;
+    padding-left: var(--dx-g-spacing-3xl);
+    padding-right: var(--dx-g-spacing-3xl);
+    width: 100%;
+}
+
+.doc-phase-title-container {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+}
+
+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 {
+    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);
+    }
+}