@salesforcedevs/docs-components 0.28.0 → 0.46.0

package/lwc.config.json

@@ -4,11 +4,13 @@
         { "npm": "@salesforcedevs/dx-components" }
     ],
     "expose": [
+        "doc/breadcrumbs",
         "doc/contentCallout",
         "doc/contentMedia",
         "doc/content",
         "doc/header",
         "doc/heading",
+        "doc/headingAnchor",
         "doc/phase"
     ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "0.28.0",
+    "version": "0.46.0",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -10,5 +10,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "e7bf549e93170dd173ff7419b302674d0faa0b7a"
+    "gitHead": "78a4e68343ce579334b49d3dd6c474e1f71b4fd6"
 }

package/src/modules/doc/breadcrumbItem/breadcrumbItem.css

@@ -0,0 +1,50 @@
+@import "helpers/reset";
+@import "helpers/text";
+
+:host {
+    display: flex;
+    align-items: center;
+    width: fit-content;
+}
+
+:host(.breadcrumb_long) {
+    /* ensure 30 character min-width */
+    min-width: 245px;
+}
+
+:host(.breadcrumb_back-arrow) {
+    gap: var(--dx-g-spacing-sm);
+    padding: var(--dx-g-spacing-sm);
+}
+
+:host(.breadcrumb_back-arrow:hover) {
+    background-color: var(--dx-g-cloud-blue-vibrant-90);
+    border-radius: var(--dx-g-spacing-xs);
+}
+
+:host(.breadcrumb_back-arrow) :is(a, dx-icon) {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
+a {
+    font-weight: var(--dx-g-font-bold);
+    text-decoration: none;
+    transition: var(--dx-g-transition-hue-1x);
+}
+
+a,
+span {
+    color: var(
+        --dx-c-breadcrumbs-breadcrumb-color,
+        var(--dx-g-blue-vibrant-20)
+    );
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-sm);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+a:hover {
+    color: var(--dx-g-blue-vibrant-40);
+}

package/src/modules/doc/breadcrumbItem/breadcrumbItem.html

@@ -0,0 +1,5 @@
+<template>
+    <dx-icon if:true={isBackArrowVariant} symbol="back"></dx-icon>
+    <a if:true={href} href={href}>{label}</a>
+    <span if:false={href}>{label}</span>
+</template>

package/src/modules/doc/breadcrumbItem/breadcrumbItem.ts

@@ -0,0 +1,49 @@
+import { LightningElement, api } from "lwc";
+import { BreadcrumbItemVariant } from "typings/custom";
+
+const BREADCRUMB_LONG = "breadcrumb_long";
+const BREADCRUMB_BACK_ARROW = "breadcrumb_back-arrow";
+
+const LONG_LABEL_NUMBER = 30;
+export default class BreadcrumbItem extends LightningElement {
+    @api href?: string;
+
+    @api
+    get label() {
+        return this._label;
+    }
+
+    set label(value) {
+        this._label = value;
+        this.calculateClass();
+    }
+
+    @api
+    get variant() {
+        return this._variant;
+    }
+
+    set variant(value) {
+        this._variant = value;
+        this.calculateClass();
+    }
+
+    _label: string = "";
+    _variant: BreadcrumbItemVariant = "default";
+
+    private calculateClass(): void {
+        this.classList.remove(BREADCRUMB_LONG, BREADCRUMB_BACK_ARROW);
+
+        if (this.label?.length >= LONG_LABEL_NUMBER) {
+            this.classList.add(BREADCRUMB_LONG);
+        }
+
+        if (this._variant === "back-arrow") {
+            this.classList.add(BREADCRUMB_BACK_ARROW);
+        }
+    }
+
+    private get isBackArrowVariant(): boolean {
+        return this._variant === "back-arrow";
+    }
+}

package/src/modules/doc/breadcrumbs/breadcrumbs.css

@@ -0,0 +1,19 @@
+@import "helpers/reset";
+@import "helpers/text";
+
+:host {
+    --dx-c-breadcrumbs-title-color: var(--dx-g-blue-vibrant-20);
+    --dx-c-breadcrumbs-breadcrumb-color: var(--dx-g-blue-vibrant-20);
+}
+
+nav {
+    display: flex;
+    align-items: center;
+    height: 100%;
+    position: relative;
+    gap: var(--dx-g-spacing-sm);
+}
+
+.breadcrumb-item_slash {
+    min-width: fit-content;
+}

package/src/modules/doc/breadcrumbs/breadcrumbs.html

@@ -0,0 +1,48 @@
+<template>
+    <nav role="navigation" aria-label={ariaLabel}>
+        <template if:false={renderSmallVariant}>
+            <template if:true={renderFirstCrumb}>
+                <doc-breadcrumb-item
+                    href={firstCrumb.href}
+                    label={firstCrumb.label}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash">/</span>
+            </template>
+            <template if:true={renderDropdown}>
+                <dx-dropdown
+                    if:true={renderDropdown}
+                    options={dropdownOptions}
+                    open-on-hover
+                    placement="bottom"
+                    width="200px"
+                >
+                    <dx-button
+                        aria-label="Open Breadcrumbs Dropdown"
+                        icon-size="large"
+                        icon-symbol="threedots"
+                        variant="tertiary"
+                    ></dx-button>
+                </dx-dropdown>
+                <span class="breadcrumb-item_slash">/</span>
+            </template>
+            <template for:each={breadcrumbItems} for:item="breadcrumb">
+                <doc-breadcrumb-item
+                    href={breadcrumb.href}
+                    key={breadcrumb.label}
+                    label={breadcrumb.label}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash" key={breadcrumb.label}>
+                    /
+                </span>
+            </template>
+            <doc-breadcrumb-item label={lastCrumb.label}></doc-breadcrumb-item>
+        </template>
+        <template if:true={renderSmallVariant}>
+            <doc-breadcrumb-item
+                href={lastLinkCrump.href}
+                label={lastLinkCrump.label}
+                variant="back-arrow"
+            ></doc-breadcrumb-item>
+        </template>
+    </nav>
+</template>

package/src/modules/doc/breadcrumbs/breadcrumbs.ts

@@ -0,0 +1,144 @@
+import { LightningElement, api } from "lwc";
+import { Breadcrumb, Option } from "typings/custom";
+import { toJson } from "utils/normalizers";
+
+type BreadcrumbConfig = {
+    minWidth: number;
+    crumbsInDropdown: number;
+};
+
+const GAP = 8;
+const CONSTANTS = {
+    pixelPerCharacter: 7.2,
+    pixelPerCrumbSpace: GAP * 2 + 4.6,
+    minWidthPerCrumb: 245,
+    dropdownWidth: 32
+};
+
+export default class Breadcrumbs extends LightningElement {
+    @api ariaLabel: string = "Documentation Breadcrumbs";
+
+    @api
+    get breadcrumbs(): Breadcrumb[] {
+        return this._breadcrumbs;
+    }
+    set breadcrumbs(value) {
+        this._breadcrumbs = toJson(value) || [];
+        this.calculateBreadcrumbsConfigs();
+        if (this.observer) {
+            this.updateDropdownOptionAmount();
+        }
+    }
+
+    private _breadcrumbs: Breadcrumb[] = [];
+    private navWidth = 0;
+    private observer: ResizeObserver | null = null;
+    private breadcrumbConfigs: BreadcrumbConfig[] = [];
+    private dropdownOptionAmount? = 0;
+
+    private get renderSmallVariant(): boolean {
+        return (
+            !this.dropdownOptionAmount &&
+            this.dropdownOptionAmount !== 0 &&
+            !!this.lastLinkCrump
+        );
+    }
+
+    private get lastLinkCrump(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 2];
+    }
+
+    private get hasInternalBreadcrumbs(): boolean {
+        return this.breadcrumbs.length > 2;
+    }
+
+    private get breadcrumbItems(): Breadcrumb[] {
+        return this.breadcrumbs!.slice(
+            this.dropdownOptionAmount! + 1,
+            this._breadcrumbs.length - 1
+        );
+    }
+
+    private get renderDropdown(): boolean {
+        return this.hasInternalBreadcrumbs && !!this.dropdownOptionAmount;
+    }
+    private get dropdownOptions(): Option[] {
+        return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
+            (link) => ({
+                id: link.href!,
+                label: link.label,
+                link: { href: link.href! }
+            })
+        );
+    }
+
+    private get renderFirstCrumb(): boolean {
+        return this.breadcrumbs.length > 1;
+    }
+
+    private get firstCrumb(): Breadcrumb {
+        return this.breadcrumbs[0];
+    }
+
+    private get lastCrumb(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 1];
+    }
+
+    renderedCallback(): void {
+        if (!this.observer) {
+            this.observer = new ResizeObserver((entries) => {
+                const [nav] = entries;
+                if (this.navWidth === nav.contentRect.width) {
+                    return;
+                }
+                this.navWidth = nav.contentRect.width;
+                this.updateDropdownOptionAmount();
+            });
+
+            this.observer.observe(this.template.querySelector("nav")!);
+        }
+    }
+
+    disconnectedCallback(): void {
+        this.observer?.disconnect();
+    }
+
+    private updateDropdownOptionAmount(): void {
+        this.dropdownOptionAmount = this.breadcrumbConfigs.find(
+            ({ minWidth }) => minWidth <= this.navWidth
+        )?.crumbsInDropdown;
+    }
+
+    private calculateBreadcrumbsConfigs(): void {
+        this.breadcrumbConfigs = [
+            ...Array(this._breadcrumbs.length - 1).keys()
+        ].map((optionsAmount) => {
+            const breadcrumbs = [...this._breadcrumbs];
+            breadcrumbs.splice(1, optionsAmount);
+            return {
+                crumbsInDropdown: optionsAmount,
+                minWidth: this.reduceBreadcrumbs(
+                    breadcrumbs,
+                    optionsAmount
+                        ? CONSTANTS.dropdownWidth + CONSTANTS.pixelPerCrumbSpace
+                        : 0
+                )
+            };
+        });
+    }
+
+    private reduceBreadcrumbs(
+        breadcrumbs: Breadcrumb[],
+        offset: number = 0
+    ): number {
+        return breadcrumbs.reduce(
+            (previousValue, element) =>
+                previousValue +
+                Math.min(
+                    element.label.length * CONSTANTS.pixelPerCharacter,
+                    CONSTANTS.minWidthPerCrumb
+                ),
+            (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset
+        );
+    }
+}

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

@@ -16,7 +16,7 @@ h6 {
     line-height: var(--dx-g-text-4xl);
 }
 
-.display-3 doc-heading-anchor {
+.display-3 doc-heading-content {
     --doc-c-heading-anchor-button-bottom: 8px;
 }
 
@@ -27,7 +27,7 @@ h6 {
     line-height: var(--dx-g-spacing-lg);
 }
 
-.display-4 doc-heading-anchor {
+.display-4 doc-heading-content {
     --doc-c-heading-anchor-button-bottom: -3px;
 }
 
@@ -38,7 +38,7 @@ h6 {
     line-height: var(--dx-g-spacing-lg);
 }
 
-.display-5 doc-heading-anchor {
+.display-5 doc-heading-content {
     --doc-c-heading-anchor-button-bottom: -4px;
 }
 
@@ -49,6 +49,6 @@ h6 {
     line-height: var(--dx-g-spacing-mlg);
 }
 
-.display-6 doc-heading-anchor {
+.display-6 doc-heading-content {
     --doc-c-heading-anchor-button-bottom: -6px;
 }

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

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

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

@@ -1,55 +1,33 @@
 @import "helpers/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);
-}
-
-.button-container {
-    height: 100%;
-    margin-right: calc(var(--dx-g-spacing-xl) - 4px);
-    position: relative;
-}
-
 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);
+button:hover {
+    opacity: 1;
+    outline: none;
 }
 
-span:last-of-type {
-    padding-right: var(--dx-g-spacing-xs);
+button:focus {
+    opacity: 1;
+    outline: none;
 }
 
-.nowrap {
-    white-space: nowrap;
+button:focus-visible {
+    border-radius: 4px;
+    border: 2px solid rgb(11, 92, 171);
 }
 
-button:focus {
-    box-shadow: 0 0 0 2px rgb(11 92 171);
+.icon-wrapper {
+    height: 32px;
+    width: 32px;
+    display: flex;
+    justify-content: center;
+    align-items: center;
 }
 
-button:focus,
-button:hover,
-span:hover dx-tooltip button,
-span:hover ~ span dx-tooltip button {
-    opacity: 1;
-    outline: none;
+.icon-container {
+    --dx-c-icon-size: 18px;
 }

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

@@ -1,19 +1,19 @@
 <template>
-    <template if:false={hash}>{title}</template>
-    <template if:true={hash}>
-        <template if:true={needsSpace}>
-            <span>{titleToWrap}</span>
-            <span>&#32;</span>
-        </template>
-        <span class="nowrap">
-            {titleNoWrap}&nbsp;
-            <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>
-        </span>
-    </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

@@ -1,42 +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 hash: string | null = null;
+    @api urlText: string = "";
 
     label: string = "Copy link to clipboard";
-    timeout: number | null = null;
 
-    private get titleToWrap() {
-        return this.title.substring(0, this.title.lastIndexOf(" "));
+    private async onIconClick() {
+        await this.iconClickHandler();
     }
 
-    private get needsSpace() {
-        return this.titleToWrap.length > 0;
-    }
-
-    private get titleNoWrap() {
-        return this.title.substring(this.title.lastIndexOf(" ") + 1);
-    }
-
-    private async copy() {
-        if (this.timeout) {
-            window.clearTimeout(this.timeout);
-        }
-
+    private async iconClickHandler() {
         this.label = "Copied";
-        this.timeout = window.setTimeout(() => {
+        setTimeout(() => {
             this.label = "Copy link to clipboard";
         }, 2000);
 
         try {
-            if (this.title && this.hash) {
+            if (this.title && this.urlText) {
                 const [hostUrl] = window.location.href.split("#");
-                const url = `${hostUrl}#${this.hash}`;
+                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,55 @@
+@import "helpers/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);
+}
+
+.button-container {
+    height: 100%;
+    margin-right: calc(var(--dx-g-spacing-xl) - 4px);
+    position: relative;
+}
+
+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);
+}
+
+span:last-of-type {
+    padding-right: var(--dx-g-spacing-xs);
+}
+
+.nowrap {
+    white-space: nowrap;
+}
+
+button:focus {
+    box-shadow: 0 0 0 2px rgb(11 92 171);
+}
+
+button:focus,
+button:hover,
+span:hover dx-tooltip button,
+span:hover ~ span dx-tooltip button {
+    opacity: 1;
+    outline: none;
+}

package/src/modules/doc/headingContent/headingContent.html

@@ -0,0 +1,19 @@
+<template>
+    <template if:false={hash}>{title}</template>
+    <template if:true={hash}>
+        <template if:true={needsSpace}>
+            <span>{titleToWrap}</span>
+            <span>&#32;</span>
+        </template>
+        <span class="nowrap">
+            {titleNoWrap}&nbsp;
+            <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>
+        </span>
+    </template>
+</template>

package/src/modules/doc/headingContent/headingContent.ts

@@ -0,0 +1,42 @@
+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 get titleToWrap(): string {
+        return this.title.substring(0, this.title.lastIndexOf(" "));
+    }
+
+    private get needsSpace(): boolean {
+        return this.titleToWrap.length > 0;
+    }
+
+    private get titleNoWrap(): string {
+        return this.title.substring(this.title.lastIndexOf(" ") + 1);
+    }
+
+    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);
+        }
+    }
+}