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

package/src/modules/doc/amfTopic/amfTopic.ts

@@ -0,0 +1,94 @@
+import { LightningElement, api } from "lwc";
+import {
+    createDocumentationElement,
+    createEndpointElement,
+    createMethodElement,
+    createSecurityElement,
+    createSummaryElement,
+    createTypeElement
+} from "./utils";
+import type { TopicModel } from "./types";
+
+export default class AmfTopic extends LightningElement {
+    private _model;
+    private amf;
+    private type;
+
+    @api
+    get model(): TopicModel {
+        return this._model;
+    }
+
+    set model(value: TopicModel) {
+        if (
+            !this.amf ||
+            (value && this._model && value.amf !== this._model?.amf)
+        ) {
+            this.amf = value && clone(value.amf);
+        }
+        if (
+            !this.type ||
+            (value && this._model && value.type !== this._model?.type)
+        ) {
+            this.type = value && clone(value.type);
+        }
+
+        this._model = value;
+        if (this._model) {
+            this.update();
+        }
+        // else { Remove child? No model, seems like no component should be shown. }
+    }
+
+    update(): void {
+        const container = this.template.querySelector("div.topic-container");
+        const { id } = this.model;
+        const type = this.type;
+        const amf = this.amf;
+        const { parser } = this.model;
+        let element;
+
+        if (type === "summary") {
+            element = createSummaryElement(amf);
+        } else if (type === "endpoint") {
+            const endpointModel = parser.computeEndpointApiModel(amf, id);
+            element = createEndpointElement(amf, endpointModel, id);
+        } else if (type === "method") {
+            const endpointMethodModel = parser.computeEndpointApiMethodModel(
+                amf,
+                id
+            );
+            const methodModel = parser.computeMethodApiModel(amf, id);
+            element = createMethodElement(
+                amf,
+                endpointMethodModel,
+                methodModel
+            );
+        } else if (type === "security") {
+            const securityModel = parser.computeSecurityApiModel(amf, id);
+            element = createSecurityElement(amf, securityModel);
+        } else if (type === "type") {
+            const mediaTypes = parser.computeApiMediaTypes(amf);
+            const typeModel = parser.computeTypeApiModel(amf, id);
+            element = createTypeElement(amf, typeModel, mediaTypes);
+        } else if (type === "documentation") {
+            const docsModel = parser.computeDocsApiModel(amf, id);
+            element = createDocumentationElement(amf, docsModel);
+        }
+
+        if (container.firstChild) {
+            container.firstChild.remove();
+        }
+        container.appendChild(element);
+    }
+}
+
+/**
+ * The underlying web components we use from api-console mutate their models we pass in.
+ * Since LWC makes them Read Only, we need to copy them before passing to the Web Component.
+ * @param value JSON Serializable object to clone.
+ * @returns A copy of Value. One that has been serialized and parsed via JSON. (Functions, Regex, etc are not preserved.)
+ */
+function clone(value): object {
+    return JSON.parse(JSON.stringify(value));
+}

package/src/modules/doc/amfTopic/types.ts

@@ -0,0 +1,54 @@
+import { Json } from "typings/custom";
+
+export type ApiSummaryElement = HTMLElement & {
+    amf: Json;
+    hideToc: boolean;
+    titleLevel: string;
+};
+
+export type ApiEndpointElement = HTMLElement & {
+    amf: Json;
+    inlineMethods: boolean;
+    noNavigation: boolean;
+    selected: string;
+    endpoint: Json;
+    noTryIt: boolean;
+};
+
+export type ApiMethodElement = HTMLElement & {
+    amf: Json;
+    noNavigation: boolean;
+    endpoint: Json;
+    method: Json;
+    noTryIt: boolean;
+};
+
+export type ApiSecurityElement = HTMLElement & {
+    amf: Json;
+    security: Json;
+};
+
+export type ApiTypeElement = HTMLElement & {
+    amf: Json;
+    type: Json;
+    mediaTypes: Json;
+};
+
+export type ApiDocElement = HTMLElement & {
+    amf: Json;
+    shape: Json;
+};
+
+export type AmfModel = Json;
+
+export interface AmfParser {
+    parse(): void;
+    parsedModel: any;
+}
+
+export interface TopicModel {
+    id: string;
+    type: string;
+    amf: AmfModel;
+    parser: AmfParser;
+}

package/src/modules/doc/amfTopic/utils.ts

@@ -0,0 +1,130 @@
+import type {
+    ApiDocElement,
+    ApiEndpointElement,
+    ApiMethodElement,
+    ApiSecurityElement,
+    ApiSummaryElement,
+    ApiTypeElement
+} from "./types";
+import { Json } from "typings/custom";
+
+export function createSummaryElement(amf: Json): HTMLElement {
+    const summaryElement: ApiSummaryElement = document.createElement(
+        "api-summary"
+    ) as ApiSummaryElement;
+    summaryElement.amf = amf;
+    summaryElement.hideToc = true;
+    summaryElement.titleLevel = "1";
+    summaryElement.setAttribute(
+        "exportparts",
+        [
+            "api-title",
+            "api-title-label",
+            "api-version",
+            "marked-description",
+            "info-section",
+            "info-inline-desc",
+            "license-section",
+            "separator",
+            "toc"
+        ].join(",")
+    );
+    return summaryElement;
+}
+
+/**
+ * Creates a `api-endpoint-documentation` web element from web API and current selection.
+ */
+export function createEndpointElement(
+    amf: Json,
+    endpointModel: Json,
+    selected: string
+): HTMLElement {
+    const el: ApiEndpointElement = document.createElement(
+        "api-endpoint-documentation"
+    ) as ApiEndpointElement;
+    el.amf = amf;
+    el.inlineMethods = false;
+    el.noNavigation = true;
+    el.selected = selected;
+    el.endpoint = endpointModel;
+    el.noTryIt = true;
+    return el;
+}
+
+/**
+ * Creates a `api-method-documentation` web element from web API and current selection.
+ */
+export function createMethodElement(
+    amf: Json,
+    endpointMethodModel: Json,
+    methodModel: Json
+): HTMLElement {
+    const el: ApiMethodElement = document.createElement(
+        "api-method-documentation"
+    ) as ApiMethodElement;
+    el.amf = amf;
+    el.noNavigation = true;
+    el.endpoint = endpointMethodModel;
+    el.method = methodModel;
+    el.noTryIt = true;
+    el.setAttribute("renderSecurity", "");
+    el.setAttribute("renderCodeSnippets", "");
+    return el;
+}
+
+/**
+ * Creates a documentation element for Security AMF type
+ *
+ */
+export function createSecurityElement(
+    amf: Json,
+    securityModel: Json
+): HTMLElement {
+    const el: ApiSecurityElement = document.createElement(
+        "api-security-documentation"
+    ) as ApiSecurityElement;
+    el.setAttribute("exportparts", ["security-title"].join(","));
+    el.amf = amf;
+    el.security = securityModel;
+    return el;
+}
+
+/**
+ * Creates a documentation element for Type AMF type
+ *
+ * @param {string} amfId Reference ID as passed in from amfConfig
+ * @param {string} selected Currently selected `@id`.
+ */
+export function createTypeElement(
+    amf: Json,
+    typeModel: Json,
+    mediaTypes: Json
+): HTMLElement {
+    const el: ApiTypeElement = document.createElement(
+        "api-type-documentation"
+    ) as ApiTypeElement;
+    el.setAttribute("exportparts", ["type-title"].join(","));
+    el.amf = amf;
+    el.type = typeModel;
+    el.mediaTypes = mediaTypes;
+    return el;
+}
+
+/**
+ * Creates a documentation element for Docs AMF type
+ *
+ * @param {string} amfId Reference ID as passed in from amfConfig
+ * @param {string} selected Currently selected `@id`.
+ */
+export function createDocumentationElement(
+    amf: Json,
+    docsModel: Json
+): HTMLElement {
+    const el: ApiDocElement = document.createElement(
+        "api-documentation-document"
+    ) as ApiDocElement;
+    el.amf = amf;
+    el.shape = docsModel;
+    return el;
+}

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

@@ -0,0 +1,51 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+
+:host {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: fit-content;
+}
+
+:host(.breadcrumb_long) {
+    /* ensure 30 character min-width */
+    min-width: 200px;
+}
+
+: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} onclick={onLinkClick}>{label}</a>
+    <span if:false={href}>{label}</span>
+</template>

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

@@ -0,0 +1,64 @@
+import { track } from "dxUtils/analytics";
+import { LightningElement, api } from "lwc";
+import { AnalyticsPayload, 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 analyticsEvent!: string;
+    @api analyticsBasePayload!: AnalyticsPayload;
+
+    @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";
+    }
+
+    private onLinkClick(event: Event): void {
+        if (!this.analyticsEvent) {
+            return;
+        }
+
+        track(event.target!, this.analyticsEvent, {
+            ...this.analyticsBasePayload,
+            clickText: this.label,
+            clickUrl: this.href
+        });
+    }
+}

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

@@ -0,0 +1,27 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+
+:host {
+    --dx-c-breadcrumbs-title-color: var(--dx-g-blue-vibrant-20);
+    --dx-c-breadcrumbs-breadcrumb-color: var(--dx-g-blue-vibrant-20);
+
+    font-family: var(--dx-g-font-sans);
+}
+
+nav {
+    display: flex;
+    align-items: center;
+    position: relative;
+    gap: var(--dx-g-spacing-sm);
+}
+
+.breadcrumb-item_slash {
+    min-width: fit-content;
+}
+
+dx-dropdown {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-sm);
+    --dx-c-dropdown-option-label-color: var(
+        --dx-c-breadcrumbs-breadcrumb-color
+    );
+}

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

@@ -0,0 +1,60 @@
+<template>
+    <nav role="navigation" aria-label={ariaLabel}>
+        <template if:true={displayCrumbs}>
+            <template if:false={renderSmallVariant}>
+                <doc-breadcrumb-item
+                    analytics-event={analyticsEventName}
+                    analytics-base-payload={analyticsBasePayload}
+                    href={firstCrumb.href}
+                    label={firstCrumb.label}
+                ></doc-breadcrumb-item>
+                <span class="breadcrumb-item_slash">/</span>
+                <template if:true={renderDropdown}>
+                    <dx-dropdown
+                        if:true={renderDropdown}
+                        analytics-event={analyticsEventName}
+                        analytics-base-payload={analyticsBasePayload}
+                        options={dropdownOptions}
+                        open-on-hover
+                        placement="bottom"
+                        suppress-gtm-nav-headings
+                        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
+                        analytics-event={analyticsEventName}
+                        analytics-base-payload={analyticsBasePayload}
+                        href={breadcrumb.href}
+                        key={breadcrumb.id}
+                        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
+                    analytics-event={analyticsEventName}
+                    analytics-base-payload={analyticsBasePayload}
+                    href={lastLinkCrump.href}
+                    label={lastLinkCrump.label}
+                    variant="back-arrow"
+                ></doc-breadcrumb-item>
+            </template>
+        </template>
+    </nav>
+</template>

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

@@ -0,0 +1,187 @@
+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 const ANALYTICS_EVENT_NAME = "custEv_breadcrumbClick";
+export const ANALYTICS_BASE_PAYLOAD = {
+    elementType: "breadcrumb",
+    locationOnPage: "breadcrumb",
+    ctaClick: true
+};
+
+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 lastCrumb(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 1];
+    }
+
+    private get analyticsEventName() {
+        return ANALYTICS_EVENT_NAME;
+    }
+
+    private get analyticsBasePayload() {
+        return {
+            ...ANALYTICS_BASE_PAYLOAD,
+            itemTitle: this.breadcrumbs.map((crumb) => crumb.label).join("/")
+        };
+    }
+
+    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 normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
+        if (!breadcrumbs) {
+            return;
+        }
+
+        this._breadcrumbs = toJson(breadcrumbs).map((crumb: Breadcrumb) => ({
+            ...crumb,
+            id: crumb.id || crumb.href
+        }));
+    }
+
+    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
+        );
+    }
+}