@salesforcedevs/docs-components 0.7.0 → 0.7.59-sppage-alpha2

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

@@ -0,0 +1,58 @@
+<template>
+    <nav role="navigation" aria-label={ariaLabel}>
+        <template if:true={displayCrumbs}>
+            <template if:false={renderSmallVariant}>
+                <doc-breadcrumb-item
+                    href={firstCrumb.href}
+                    label={firstCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash">/</span>
+                <template if:true={renderDropdown}>
+                    <dx-dropdown
+                        analytics-event="custEv_breadcrumbClick"
+                        analytics-payload={ANALYTICS_PAYLOAD}
+                        if:true={renderDropdown}
+                        options={dropdownOptions}
+                        open-on-hover
+                        placement="bottom"
+                        variant="indented"
+                        width="fit-content"
+                    >
+                        <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.id}
+                        label={breadcrumb.label}
+                        level={breadcrumb.level}
+                        breadcrumb-labels={breadcrumbLabels}
+                    ></doc-breadcrumb-item>
+                    <span class="breadcrumb-item_slash" key={breadcrumb.label}>
+                        /
+                    </span>
+                </template>
+                <doc-breadcrumb-item
+                    label={lastCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                ></doc-breadcrumb-item>
+            </template>
+            <template if:true={renderSmallVariant}>
+                <doc-breadcrumb-item
+                    href={lastLinkCrump.href}
+                    label={lastLinkCrump.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                    variant="back-arrow"
+                ></doc-breadcrumb-item>
+            </template>
+        </template>
+    </nav>
+</template>

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

@@ -0,0 +1,192 @@
+import { LightningElement, api } from "lwc";
+import { Breadcrumb, OptionWithLink } from "typings/custom";
+import { toJson } from "dxUtils/normalizers";
+
+type BreadcrumbConfig = {
+    minWidth: number;
+    crumbsInDropdown: number;
+};
+
+const GAP = 8;
+
+// Unit in pixels based on Salesforce Sans font-family.
+const CONSTANTS = {
+    pixelPerCharacter: 7.7,
+    pixelPerCrumbSpace: GAP * 2 + 8.6,
+    minWidthPerCrumb: 200,
+    dropdownWidth: 32
+};
+
+export default class Breadcrumbs extends LightningElement {
+    @api ariaLabel: string = "Documentation Breadcrumbs";
+
+    @api
+    get breadcrumbs(): Breadcrumb[] {
+        return this._breadcrumbs;
+    }
+
+    set breadcrumbs(value) {
+        this.normalizeAndAssignBreadcrumbs(value);
+        this.calculateBreadcrumbsConfigs();
+        if (this.observer) {
+            this.updateDropdownOptionAmount();
+        }
+    }
+
+    @api
+    get pixelPerCharacter(): number {
+        return this._pixelPerCharacter;
+    }
+
+    set pixelPerCharacter(value: number | string) {
+        this._pixelPerCharacter = +value;
+    }
+
+    private _breadcrumbs: Breadcrumb[] = [];
+    private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
+    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(): OptionWithLink[] {
+        return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
+            (link) => ({
+                id: link.id!,
+                label: link.label,
+                link: { href: link.href! }
+            })
+        );
+    }
+
+    private get displayCrumbs(): boolean {
+        return this.breadcrumbs.length > 1;
+    }
+
+    private get firstCrumb(): Breadcrumb {
+        return this.breadcrumbs[0];
+    }
+
+    private get breadcrumbLabels(): string {
+        return this.breadcrumbs.map((crumb) => crumb.label).join(":");
+    }
+
+    private get lastCrumb(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 1];
+    }
+
+    // this payload is only used for breadcrumb dropdown
+    private get ANALYTICS_PAYLOAD() {
+        return {
+            element_type: "link",
+            nav_type: "breadcrumb",
+            nav_level: 1
+        };
+    }
+
+    renderedCallback(): void {
+        if (!this.observer) {
+            try {
+                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")!);
+            } catch (error) {
+                console.error(
+                    "Error occured while setting up ResizeObserver on breadcrumbs",
+                    error
+                );
+            }
+        }
+    }
+
+    disconnectedCallback(): void {
+        this.observer?.disconnect();
+    }
+
+    private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
+        if (!breadcrumbs) {
+            return;
+        }
+
+        this._breadcrumbs = toJson(breadcrumbs).map(
+            (crumb: Breadcrumb, index: number) => ({
+                ...crumb,
+                id: crumb.id || crumb.href,
+                level: index
+            })
+        );
+    }
+
+    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 *
+                        (this.pixelPerCharacter || CONSTANTS.pixelPerCharacter),
+                    CONSTANTS.minWidthPerCrumb
+                ),
+            (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset
+        );
+    }
+}

package/src/modules/doc/content/content.css

@@ -4,10 +4,10 @@
  * pattern validation cannot be applied
  */
 
-@import "helpers/text";
-@import "helpers/reset";
-@import "helpers/card";
-@import "helpers/table";
+@import "dxHelpers/text";
+@import "dxHelpers/reset";
+@import "dxHelpers/table";
+@import "docHelpers/imgStyle";
 
 .doc-content {
     width: 100%;
@@ -31,11 +31,6 @@
     margin-bottom: var(--dx-g-spacing-md);
 }
 
-.helpHead2 {
-    margin-top: 36px;
-    margin-bottom: var(--dx-g-spacing-md);
-}
-
 .relinfo {
     padding-top: var(--dx-g-spacing-sm);
     padding-bottom: var(--dx-g-spacing-sm);
@@ -46,17 +41,10 @@
     padding-bottom: var(--dx-g-spacing-sm);
 }
 
-img.content-image {
-    height: auto;
-    display: unset;
-}
-
 .image-block .content-image {
     margin-top: var(--dx-g-spacing-lg);
     margin-bottom: var(--dx-g-spacing-sm);
     display: block;
-    margin-left: auto;
-    margin-right: auto;
 }
 
 td > img.content-image:first-child:last-child[alt="Yes"],
@@ -64,45 +52,61 @@ td > img.content-image:first-child:last-child[alt="No"] {
     width: var(--dx-g-spacing-md);
 }
 
-h1 {
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    color: var(--dx-g-blue-vibrant-20);
     font-family: var(--dx-g-font-display);
-    font-size: 40px;
+    font-weight: var(--dx-g-font-demi);
+}
 
-    /* not registered */
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: -0.4px;
-    line-height: 40px;
+h1 {
+    font-size: var(--dx-g-text-3xl);
+    letter-spacing: -0.8px;
+    line-height: var(--dx-g-spacing-3xl);
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
 }
 
 h2 {
-    font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-xl);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: -0.1px;
-    line-height: var(--dx-g-spacing-lg);
+    font-size: var(--dx-g-text-2xl);
+    letter-spacing: -0.4px;
+    line-height: var(--dx-g-spacing-2xl);
+    margin: var(--dx-g-spacing-2xl) 0 var(--dx-g-spacing-md) 0;
 }
 
 h3 {
-    font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-lg);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: -0.1px;
-    line-height: var(--dx-g-spacing-lg);
+    font-size: var(--dx-g-text-xl);
+    letter-spacing: -0.4px;
+    line-height: var(--dx-g-spacing-xl);
+    margin: var(--dx-g-spacing-xl) 0 var(--dx-g-spacing-md) 0;
 }
 
 h4 {
-    font-family: var(--dx-g-font-display);
     font-size: var(--dx-g-text-base);
-    color: var(--dx-g-blue-vibrant-20);
-    letter-spacing: 0;
+    letter-spacing: -0.5px;
+    line-height: var(--dx-g-spacing-lg);
+    margin: var(--dx-g-spacing-lg) 0 var(--dx-g-spacing-sm) 0;
+}
+
+h5 {
+    font-size: var(--dx-g-text-sm);
+    letter-spacing: -0.3px;
     line-height: var(--dx-g-spacing-mlg);
+    margin: var(--dx-g-spacing-md) 0 var(--dx-g-spacing-sm) 0;
 }
 
-.dx-text-heading-alt-1 {
-    color: var(--dx-g-gray-30);
-    font-family: var(--dx-g-font-sans);
-    font-size: var(--slds-text-lg);
-    line-height: 25px;
+h6 {
+    font-size: var(--dx-g-text-xs);
+    letter-spacing: -0.3px;
+    line-height: var(--dx-g-spacing-md);
+    margin: var(--dx-g-spacing-sm) 0 var(--dx-g-spacing-sm) 0;
+}
+
+img {
+    image-rendering: optimize-contrast;
 }
 
 p,
@@ -116,6 +120,12 @@ p,
     margin-bottom: var(--dx-g-spacing-md);
 }
 
+dd > p,
+dd > .p {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
 .li {
     font-family: var(--dx-g-font-sans);
     font-size: var(--dx-g-text-base);
@@ -143,10 +153,6 @@ a,
     color: var(--dx-g-blue-vibrant-50);
 }
 
-.helpHead1 {
-    margin-bottom: var(--dx-g-spacing-lg);
-}
-
 .shortdesc {
     font-family: var(--dx-g-font-sans);
     font-size: var(--dx-g-text-base);
@@ -175,7 +181,8 @@ a,
     margin-right: var(--dx-g-spacing-lg);
 }
 
-.codeph {
+.codeph,
+.filepath {
     font-family: var(--dx-g-font-mono);
     font-size: var(--dx-g-text-sm);
     line-height: var(--dx-g-text-lg);
@@ -238,10 +245,17 @@ dd {
     color: var(--dx-g-gray-10);
     letter-spacing: 0;
     line-height: var(--dx-g-spacing-lg);
+    margin-left: var(--dx-g-spacing-smd);
+    margin-bottom: var(--dx-g-spacing-md);
 }
 
 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 table {
+    margin-bottom: var(--dx-g-spacing-lg);
 }
 
 li > li {
@@ -257,27 +271,6 @@ a:hover,
     text-decoration: underline;
 }
 
-@media (max-width: 640px) {
-    /* Mobile */
-    img.content-image {
-        max-width: 95vw;
-    }
-}
-
-@media (min-width: 641px) {
-    /* Tablet (medium) */
-    img.content-image {
-        max-width: 80vw;
-    }
-}
-
-@media (min-width: 769px) {
-    /* Desktop */
-    img.content-image {
-        max-width: min(60vw, 650px);
-    }
-}
-
 ul,
 ol {
     margin-left: var(--dx-g-spacing-lg);
@@ -350,13 +343,30 @@ ul ul ul ul ul ul {
     margin: var(--dx-g-spacing-lg) 0;
 }
 
-figure {
+figure,
+.fig {
     margin: var(--dx-g-spacing-lg) 0;
+    text-align: left;
+    display: flex;
+    flex-direction: column;
+    align-items: left;
+    justify-content: left;
 }
 
-figcaption {
+figcaption,
+.figcap {
+    display: block;
     font-size: var(--dx-g-text-xs);
-    margin-top: var(--dx-g-spacing-sm);
+    margin: var(--dx-g-spacing-sm) 0;
+    order: 2;
+}
+
+.figcap .image {
+    order: 1;
+}
+
+.fig.fig-centered {
+    text-align: center;
 }
 
 code,
@@ -367,3 +377,17 @@ samp,
     font-family: Menlo, monospace;
     font-size: 1em;
 }
+
+mark {
+    background-color: var(--dx-g-yellow-vibrant-90);
+}
+
+/* offset page jump link due to fixed header */
+[id] {
+    --dx-c-content-scroll-margin-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-2xl)
+    );
+
+    scroll-margin-top: var(--dx-c-content-scroll-margin-top);
+}