@salesforcedevs/docs-components 0.28.1 → 0.46.1

package/lwc.config.json

@@ -4,6 +4,7 @@
         { "npm": "@salesforcedevs/dx-components" }
     ],
     "expose": [
+        "doc/breadcrumbs",
         "doc/contentCallout",
         "doc/contentMedia",
         "doc/content",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "0.28.1",
+    "version": "0.46.1",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -10,5 +10,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "01dbc1fb1d21c1b83ec997821bb33e8343732ec8"
+    "gitHead": "9d6112f99bee139b17929e838f6ba8ac199dea2a"
 }

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/content/content.css

@@ -242,7 +242,8 @@ dd {
 }
 
 li {
-    margin-left: var(--dx-g-spacing-lg);
+    margin: var(--dx-g-spacing-sm) 0 var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-lg);
 }
 
 li > li {