@salesforcedevs/dx-components 0.16.3 → 0.17.1-review-diff1

package/src/modules/dxUtils/analytics/analytics.ts

@@ -0,0 +1,24 @@
+export const TRACKING_EVENT_NAME = "developerwebsite_track";
+export const LISTENER_QUEUE = "__DX_INSTRUMENTATION_QUEUE__";
+export const LISTENER_INDICATOR = "__DX_INSTRUMENTATION_IS_INITIALIZED__";
+
+export function track(
+    element: EventTarget,
+    event: string,
+    payload: Record<string, unknown>
+): void {
+    const detail = { event, payload };
+    // if window.LISTENER_INDICATOR is undefined, `dx-instrumentation` has not
+    // been mounted, and the listener hasn't been attached.
+    if ((window as any)[LISTENER_INDICATOR] === undefined) {
+        (window as any)[LISTENER_QUEUE] = (window as any)[LISTENER_QUEUE] || [];
+        (window as any)[LISTENER_QUEUE].push(detail);
+    } else {
+        const e = new CustomEvent(TRACKING_EVENT_NAME, {
+            bubbles: true,
+            composed: true,
+            detail
+        });
+        element.dispatchEvent(e);
+    }
+}

package/src/modules/dxUtils/async/async.ts

@@ -0,0 +1,45 @@
+/**
+ * Checks whether a condition is satisfied at a specified interval, stopping after a maximum amount
+ * of time (if specified). Returns a Promise that resolves with `true` if the condition was
+ * satisfied during polling (if a maximum time is specified, it can resolve with false if the
+ * condition was not satisfied within the maximum time).
+ *
+ * Usage:
+ *  await pollUntil(() => something.is.true, 200, 1000);
+ *
+ * @param {Function} condition the "check" callback that will be called to determine whether the
+ *  condition has been satisfied (satisfied === callback returns truthy value)
+ * @param {number} atIntervalMs value in milliseconds specifying how often to poll
+ * @param {number} [forMaximumMs] value in milliseconds specifying the maximum time to poll
+ * @returns {Promise}
+ */
+export function pollUntil(
+    condition: () => boolean,
+    atIntervalMs: number,
+    forMaximumMs?: number
+) {
+    return new Promise<boolean>((resolve) => {
+        let timeoutId: ReturnType<typeof setTimeout>;
+        const intervalId = setInterval(() => {
+            if (condition()) {
+                resolveWithCleanup(true);
+            }
+        }, atIntervalMs);
+        if (typeof forMaximumMs === "number") {
+            timeoutId = setTimeout(() => {
+                // One last check in case the condition was satisfied right before the end:
+                resolveWithCleanup(condition() || false);
+            }, forMaximumMs);
+        }
+        if (condition()) {
+            // Condition already fulfilled before intervals, no need to keep waiting!
+            resolveWithCleanup(true);
+        }
+
+        function resolveWithCleanup(success: boolean) {
+            clearInterval(intervalId);
+            clearTimeout(timeoutId);
+            resolve(success);
+        }
+    });
+}

package/src/modules/dxUtils/browser/browser.ts

@@ -0,0 +1,17 @@
+/**
+ * Returns whether given element is in browser viewport or not
+ */
+function isInViewport(element: HTMLElement): boolean {
+    const rect = element?.getBoundingClientRect();
+    return (
+        rect &&
+        rect.top >= 0 &&
+        rect.left >= 0 &&
+        rect.bottom <=
+            (window.innerHeight || document.documentElement.clientHeight) &&
+        rect.right <=
+            (window.innerWidth || document.documentElement.clientWidth)
+    );
+}
+
+export { isInViewport };

package/src/modules/dxUtils/constants/breakpoints.ts

@@ -0,0 +1,9 @@
+// these breakpoints are written in terms of "max-width"
+export const BREAKPOINT_MOBILE_SMALL = "640px";
+export const BREAKPOINT_MOBILE = "768px";
+export const BREAKPOINT_TABLET = "1024px";
+export const BREAKPOINT_DESKTOP = "1280px";
+
+export const DEVICE_DESKTOP = "desktop";
+export const DEVICE_TABLET = "tablet";
+export const DEVICE_MOBILE = "mobile";

package/src/modules/dxUtils/constants/constants.ts

@@ -0,0 +1 @@
+export * from "./breakpoints";

package/src/modules/dxUtils/contentTypes/contentTypes.ts

@@ -0,0 +1,30 @@
+import { CONTENT_TYPES } from "dxConstants/contentTypes";
+import { BRANDS } from "dxConstants/brands";
+import { Brand, ContentType } from "typings/custom";
+import { buildStyleColorVariables } from "dxUtils/css";
+
+export const isBrand = (id: string): boolean => {
+    return BRANDS.includes(id as Brand);
+};
+
+export const isContentType = (id: string): boolean => {
+    return CONTENT_TYPES.includes(id as ContentType);
+};
+
+export const getContentTypeColorScope = (id: string): string | null => {
+    if (isContentType(id)) {
+        return "content-type";
+    }
+    if (isBrand(id)) {
+        return "brand";
+    }
+    return null;
+};
+
+export const getContentTypeColorVariables = (id: string): string => {
+    const scope = getContentTypeColorScope(id);
+    return buildStyleColorVariables({
+        background: `--dx-g-${scope}-${id}-color-background`,
+        color: `--dx-g-${scope}-${id}-color`
+    });
+};

package/src/modules/dxUtils/coveo/coveo.ts

@@ -0,0 +1,70 @@
+import {
+    buildSearchEngine as _buildSearchEngine,
+    SearchAppState,
+    SearchEngineOptions
+} from "@coveo/headless";
+
+export const buildSearchEngine = ({
+    organizationId,
+    preloadedState,
+    publicAccessToken,
+    searchHub,
+    searchPipeline
+}: {
+    organizationId: string;
+    publicAccessToken: string;
+    searchPipeline?: string;
+    searchHub: string;
+    preloadedState?: SearchAppState;
+}) => {
+    const search = searchPipeline
+        ? { pipeline: searchPipeline, searchHub }
+        : { searchHub };
+
+    const configuration = {
+        accessToken: publicAccessToken,
+        organizationId,
+        search
+    };
+
+    const engineConfiguration: SearchEngineOptions = preloadedState
+        ? { configuration, preloadedState }
+        : { configuration };
+
+    return _buildSearchEngine(engineConfiguration);
+};
+
+export const getSidebarSearchParams = () =>
+    new URLSearchParams(window.location.search).get("q");
+
+const coveoOrganizationId = "coveosalesforcetestakshatha";
+const coveoPublicAccessToken = "xxfeb39525-e402-4e41-a870-7132441f7875";
+
+export const coveoHeaderConfig = {
+    coveoOrganizationId,
+    coveoPublicAccessToken,
+    coveoSearchPipeline: "salesforcedevdoc",
+    coveoSearchHub: "salesforcedevdoc"
+};
+
+export const coveoXMLDocsConfig = {
+    coveoOrganizationId,
+    coveoPublicAccessToken,
+    coveoSearchHub: "Developer_Docs_SS",
+    coveoAdvancedQueryConfig: JSON.stringify({
+        objecttype: "HTDeveloperDocumentsC",
+        sflocale__c: "en_US",
+        sfrelease__c: "232.0",
+        sfdelivarable__c: "apexcode"
+    })
+};
+
+export const coveoSFDocsConfig = {
+    coveoOrganizationId,
+    coveoPublicAccessToken,
+    coveoSearchHub: "Developer_MdDocs_SS",
+    coveoAdvancedQueryConfig: JSON.stringify({
+        source: "Sitemap - Developer Docs",
+        path_segment_3: "pardot"
+    })
+};

package/src/modules/dxUtils/css/css.ts

@@ -0,0 +1,58 @@
+import { Color } from "typings/custom";
+
+const LABEL_TO_DX_VAR: { [key: string]: string } = {
+    blue: "blue-vibrant",
+    "cloud-blue": "cloud-blue-vibrant",
+    green: "green-vibrant",
+    "hot-orange": "hot-orange-vibrant",
+    indigo: "indigo-vibrant",
+    orange: "orange-vibrant",
+    pink: "pink-vibrant",
+    purple: "purple-vibrant",
+    red: "red-vibrant",
+    teal: "teal-natural",
+    violet: "violet-vibrant",
+    yellow: "yellow-natural"
+};
+
+const DEFAULT_BACKGROUND_LEVEL = 95;
+const DEFAULT_COLOR_LEVEL = 40;
+const BROWSER_COLOR_REGEXP = /^(?:#[0-9A-F]{3,8}|rgba?\(.+\))/;
+
+export const colorToDxColors = (
+    color?: Color
+): {
+    background: string;
+    color: string;
+} | null => {
+    if (!color) {
+        return null;
+    }
+
+    const dxVarColor = LABEL_TO_DX_VAR[color];
+    if (!dxVarColor) {
+        return null;
+    }
+
+    return {
+        background: `--dx-g-${dxVarColor}-${DEFAULT_BACKGROUND_LEVEL}`,
+        color: `--dx-g-${dxVarColor}-${DEFAULT_COLOR_LEVEL}`
+    };
+};
+
+export const toDxColor = (color: string) =>
+    ["white", "transparent"].includes(color) ||
+    color?.includes("linear-gradient") ||
+    BROWSER_COLOR_REGEXP.test(color)
+        ? color
+        : `var(--dx-g-${color})`;
+
+export const buildStyleColorVariables = ({
+    background,
+    color
+}: {
+    background: string;
+    color: string;
+}): string => {
+    return `--color: var(${color}); --background: var(${background})`;
+};

package/src/modules/dxUtils/dates/dates.ts

@@ -0,0 +1,72 @@
+import { DateTime } from "luxon";
+
+const MONTHS = {
+    January: 0,
+    February: 1,
+    March: 2,
+    April: 3,
+    May: 4,
+    June: 5,
+    July: 6,
+    August: 7,
+    September: 8,
+    October: 9,
+    November: 10,
+    December: 11
+};
+
+/*
+    sorts the months by their date heading, for example:
+    {
+        "February 2022": [ *array of dates for this month* ],
+        "January 2022": [ *array of dates for this month* ],
+    }
+*/
+export function sortSplittedPostsByMonth(postsByMonth: any) {
+    const sortedPostsByMonth: { [key: string]: Array<{}> } = {};
+
+    Object.keys(postsByMonth)
+        .sort((a, b) => {
+            const [aMonth, aYear] = a.split(" ");
+            const [bMonth, bYear] = b.split(" ");
+
+            if (aYear < bYear) {
+                return 1;
+            } else if (aYear > bYear) {
+                return -1;
+            } else if (
+                MONTHS[aMonth as keyof typeof MONTHS] <
+                MONTHS[bMonth as keyof typeof MONTHS]
+            ) {
+                return 1;
+            } else if (
+                MONTHS[aMonth as keyof typeof MONTHS] >
+                MONTHS[bMonth as keyof typeof MONTHS]
+            ) {
+                return -1;
+            }
+            return 0;
+        })
+        .forEach((key) => {
+            sortedPostsByMonth[key] = [
+                ...postsByMonth[key].sort((a: any, b: any) => {
+                    const aDate = new Date(a.date);
+                    const bDate = new Date(b.date);
+
+                    if (aDate < bDate) {
+                        return 1;
+                    } else if (aDate > bDate) {
+                        return -1;
+                    }
+                    return 0;
+                })
+            ];
+        });
+
+    return sortedPostsByMonth;
+}
+
+export function convertForDaylightSavings(utcIsoString: string) {
+    const utcDate = DateTime.fromISO(utcIsoString, { zone: "utc" });
+    return utcDate.toLocal();
+}

package/src/modules/{utils → dxUtils}/highlight/highlight.ts

@@ -1,9 +1,10 @@
-import { createSearchRegExp } from "utils/regexps";
+import { createSearchRegExp } from "dxUtils/regexps";
 
 const MARK_TAGS = /<\/?mark>/gi;
 
 export const highlightTerms = (
-    elements: Array<HTMLElement>,
+    // eslint-disable-next-line no-undef
+    elements: NodeListOf<Element>,
     searchTerm: string
 ): void => {
     searchTerm = searchTerm.trim();

package/src/modules/dxUtils/language/language.ts

@@ -0,0 +1,21 @@
+import { Language } from "typings/custom";
+
+export const getLanguageDisplayTextById = (
+    languages: Language[],
+    languageId: string
+): string => {
+    const language = languages.find(
+        (languageItem) => languageItem.id === languageId
+    );
+    return language ? language.displayText : "";
+};
+
+export const isGivenLanguageSupported = (
+    languages: Language[],
+    languageId: string
+): boolean => {
+    const languageIndex = languages.findIndex(
+        (languageItem) => languageItem.id === languageId
+    );
+    return languageIndex >= 0;
+};

package/src/modules/dxUtils/list/list.ts

@@ -0,0 +1,11 @@
+import { v4 as createUuid } from "uuid";
+
+export const getListWithUuids = <T extends object>(
+    list: T[],
+    idKey?: string
+) => {
+    return list.map((listItem) => ({
+        ...listItem,
+        [idKey || "id"]: createUuid()
+    }));
+};

package/src/modules/dxUtils/lwc/lwc.ts

@@ -0,0 +1,24 @@
+import { LightningElement } from "lwc";
+
+export const setContainerInnerHtml = (
+    container: HTMLElement,
+    markup: string
+) => {
+    if (container && markup && markup !== "") {
+        // eslint-disable-next-line @lwc/lwc/no-inner-html
+        container.innerHTML = markup;
+    }
+};
+
+export const reflectBooleanAttribute = <T extends LightningElement>(
+    element: T,
+    attrName: string,
+    value: string | boolean | undefined
+) => {
+    // Reflect to HTML, accommodating the disparate ways HTML and LWC handle boolean attributes
+    if (value !== false) {
+        element.setAttribute(attrName, "");
+    } else {
+        element.removeAttribute(attrName);
+    }
+};

package/src/modules/dxUtils/normalizers/normalizers.ts

@@ -0,0 +1,112 @@
+import get from "lodash.get";
+import {
+    WordpressPodcastEpisode,
+    WordpressBlogPost,
+    WordpressSingleBlogPostResponse
+} from "typings/custom";
+
+export const toJson = (value: string | object | null) =>
+    typeof value === "string" ? JSON.parse(value) : value;
+
+export const normalizeToArray = (
+    value: string[] | string | null,
+    splitKey: string = ","
+): Array<string> => {
+    if (!value) {
+        return [];
+    }
+
+    if (typeof value === "string") {
+        try {
+            value = JSON.parse(value);
+        } catch (e) {
+            value = (value as string).split(splitKey);
+        }
+    }
+
+    return (Array.isArray(value) ? value : [value]) as Array<string>;
+};
+
+const getLength = (duration: string) => {
+    if (!duration || !duration.includes(":")) {
+        return undefined;
+    }
+    return `${get(duration.split(":"), "[1]")} min`;
+};
+
+export const normalizeEpisode = ({
+    url,
+    id,
+    title,
+    description,
+    date,
+    podcastDuration
+}: WordpressPodcastEpisode) => ({
+    body: description,
+    datetime: date,
+    href: url,
+    id,
+    length: getLength(podcastDuration),
+    title
+});
+
+export const normalizePost = ({
+    authors = [],
+    date,
+    description,
+    featuredImage,
+    id,
+    title,
+    url
+}: WordpressBlogPost) => ({
+    body: description,
+    datetime: date,
+    href: url,
+    authors: authors,
+    imgAlt: "Blogpost image",
+    imgSrc: featuredImage,
+    id,
+    title
+});
+
+export const normalizeSinglePostResponse = ({
+    id,
+    authors = [],
+    date,
+    link,
+    featured_image,
+    yoast_head_json
+}: WordpressSingleBlogPostResponse) => ({
+    body: yoast_head_json?.description,
+    datetime: date,
+    href: link,
+    authors: authors,
+    imgAlt: "Blogpost image",
+    imgSrc: featured_image,
+    id,
+    title: yoast_head_json?.title
+});
+
+export const normalizeBoolean = (
+    value: string | boolean | number | undefined
+): boolean => (typeof value === "string" ? value === "true" : !!value);
+
+/**
+ * Cleans characters that are invalid for DOM IDs
+ * @param {string} id id to normalize
+ */
+export const normalizeDomId = (id: string): string => {
+    return id.replace(/^[^a-z]+|[^\w.-]+/gi, "");
+};
+
+export const safeDecodeURI = (value: string): string => {
+    try {
+        // Check if the value contains URI encoding patterns
+        return typeof value === "string" && value.includes("%")
+            ? decodeURIComponent(value)
+            : value;
+    } catch (error) {
+        // In case of any errors, return the original value
+        return value;
+    }
+};

package/src/modules/{utils → dxUtils}/options/options.ts

@@ -1,12 +1,12 @@
-import { Option } from "typings/custom";
+import { OptionWithNested } from "typings/custom";
 
 const deepmapper = (
-    _options: Option[],
-    _callback: (option: Option, lavel: number) => Option,
+    _options: OptionWithNested[],
+    _callback: (option: OptionWithNested, lavel: number) => OptionWithNested,
     level: number = 0
-): Option[] => {
+): OptionWithNested[] => {
     const _level = level + 1;
-    return _options?.map((option: Option) =>
+    return _options?.map((option: OptionWithNested) =>
         // eslint-disable-next-line @typescript-eslint/no-unused-vars
         option.options
             ? {
@@ -18,9 +18,13 @@ const deepmapper = (
 };
 
 export const deepmapOptions = (
-    options: Option[],
-    callback: (option: Option, index: number, level: number) => Option
-): Option[] => {
+    options: OptionWithNested[],
+    callback: (
+        option: OptionWithNested,
+        index: number,
+        level: number
+    ) => OptionWithNested
+): OptionWithNested[] => {
     let index = 0;
     return deepmapper(options, (option, level) => {
         const newOption = callback(option, index, level);
@@ -29,7 +33,7 @@ export const deepmapOptions = (
     });
 };
 
-export const getOptionsCount = (options: Option[]) => {
+export const getOptionsCount = (options: OptionWithNested[]) => {
     let count = 0;
     deepmapper(options, (option) => {
         count += 1;