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

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,183 @@
+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.isRendered) {
+            this.onWidthOrContentChange();
+        }
+    }
+
+    @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 breadcrumbConfigs: BreadcrumbConfig[] = [];
+    private dropdownOptionAmount? = 0;
+    private isRendered = false;
+
+    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
+        };
+    }
+
+    private onWidthOrContentChange = () => {
+        this.navWidth = this.template
+            .querySelector("nav")!
+            .getBoundingClientRect().width;
+        this.updateDropdownOptionAmount();
+    };
+
+    renderedCallback(): void {
+        this.isRendered = true;
+        this.onWidthOrContentChange();
+        window.addEventListener("resize", this.onWidthOrContentChange);
+    }
+
+    disconnectedCallback(): void {
+        window.removeEventListener("resize", this.onWidthOrContentChange);
+    }
+
+    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/componentPlayground/componentPlayground.css

@@ -0,0 +1,22 @@
+@import "dxHelpers/reset";
+
+/**
+ * Designs link - https://www.figma.com/design/9SalRPlJmtRDZHq03o8dL1/One-Doc-Site-Visionary-Mocks?node-id=9968-366397&m=dev
+ * Preview padding: 24px
+ * Example Selector height: 122px
+ * Example Preview min height: 150px
+ * Tab height with border: 46px(45px height and 1px border)
+ * Codeblock height: 264px(224px for codeblock and 40px for panel)
+ * Total: 606px
+**/
+
+iframe {
+    width: 100%;
+    height: 606px;
+    border-radius: var(--dx-g-spacing-sm);
+    border: 1px solid var(--dx-g-gray-90);
+}
+
+.playground-container {
+    position: relative;
+}

package/src/modules/doc/componentPlayground/componentPlayground.html

@@ -0,0 +1,20 @@
+<template>
+    <div class="playground-container" lwc:if={playgroundAvailable}>
+        <dx-spinner
+            size="large"
+            variant="brand"
+            if:true={isLoading}
+        ></dx-spinner>
+        <iframe
+            src={playgroundSrc}
+            onload={handleIframeLoad}
+            title={playgroundTitle}
+            allow="clipboard-write"
+        ></iframe>
+    </div>
+    <dx-error-fallback
+        lwc:else
+        title="Code Examples Unavailable"
+        description="This component's code examples are currently unavailable. Please check again later."
+    ></dx-error-fallback>
+</template>

package/src/modules/doc/componentPlayground/componentPlayground.ts

@@ -0,0 +1,42 @@
+import { LightningElement, api } from "lwc";
+
+export default class ComponentPlayground extends LightningElement {
+    @api model!: string;
+    @api namespace!: string;
+    @api component!: string;
+    @api playgroundAppUrl!: string;
+
+    isLoading = true;
+
+    /**
+     * Returns a formatted title for the component playground
+     * Maps 'aura' model to 'Aura' and 'lwc' model to 'Lightning'
+     * Capitalizes the first letter of the component name
+     * @returns {string} Formatted playground title
+     */
+    get playgroundTitle() {
+        const modelName = this.model === "aura" ? "Aura" : "Lightning";
+        const componentName =
+            this.component.charAt(0).toUpperCase() + this.component.slice(1);
+        return `Example previews and code for ${modelName} ${componentName} component`;
+    }
+
+    get playgroundAvailable() {
+        return (
+            this.playgroundAppUrl &&
+            this.model &&
+            this.namespace &&
+            this.component
+        );
+    }
+
+    get playgroundSrc(): string {
+        return `${this.playgroundAppUrl}/playground/${this.model}/${
+            this.namespace
+        }/${this.component.toLowerCase()}.html`;
+    }
+
+    handleIframeLoad() {
+        this.isLoading = false;
+    }
+}

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);
@@ -239,10 +246,16 @@ dd {
     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 {
@@ -258,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);
@@ -351,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,
@@ -372,3 +381,13 @@ samp,
 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);
+}

package/src/modules/doc/content/content.html

@@ -1,4 +1,5 @@
 <template>
+    <dx-redirect-checker></dx-redirect-checker>
     <template if:true={docsData}>
         <div class="container" data-name="content" lwc:dom="manual"></div>
     </template>