@builder.io/sdk-svelte 0.3.1 → 0.4.0

package/src/components/render-content-variants/helpers.ts

@@ -0,0 +1,245 @@
+import { isBrowser } from '../../functions/is-browser';
+import type { Nullable } from '../../helpers/nullable';
+import type { BuilderContent } from '../../types/builder-content';
+import type { Target } from '../../types/targets';
+
+export const getVariants = (content: Nullable<BuilderContent>) =>
+  Object.values(content?.variations || {});
+
+export const checkShouldRunVariants = ({
+  canTrack,
+  content,
+}: {
+  canTrack: Nullable<boolean>;
+  content: Nullable<BuilderContent>;
+}) => {
+  const hasVariants = getVariants(content).length > 0;
+
+  if (!hasVariants) {
+    return false;
+  }
+
+  if (!canTrack) {
+    return false;
+  }
+
+  if (isBrowser()) {
+    return false;
+  }
+
+  return true;
+};
+
+type VariantData = {
+  id: string;
+  testRatio?: number;
+};
+
+/**
+ * NOTE: when this function is stringified, single-line comments can cause weird issues when compiled by Sveltekit.
+ * Make sure to write multi-line comments only.
+ */
+function bldrAbTest(
+  contentId: string,
+  variants: VariantData[],
+  isHydrationTarget: boolean
+) {
+  function getAndSetVariantId(): string {
+    function setCookie(name: string, value: string, days?: number) {
+      let expires = '';
+      if (days) {
+        const date = new Date();
+        date.setTime(date.getTime() + days * 24 * 60 * 60 * 1000);
+        expires = '; expires=' + date.toUTCString();
+      }
+      document.cookie =
+        name +
+        '=' +
+        (value || '') +
+        expires +
+        '; path=/' +
+        '; Secure; SameSite=None';
+    }
+    function getCookie(name: string) {
+      const nameEQ = name + '=';
+      const ca = document.cookie.split(';');
+      for (let i = 0; i < ca.length; i++) {
+        let c = ca[i];
+        while (c.charAt(0) === ' ') c = c.substring(1, c.length);
+        if (c.indexOf(nameEQ) === 0)
+          return c.substring(nameEQ.length, c.length);
+      }
+      return null;
+    }
+    const cookieName = `builder.tests.${contentId}`;
+    const variantInCookie = getCookie(cookieName);
+    const availableIDs = variants.map((vr) => vr.id).concat(contentId);
+    /**
+     * cookie already exists
+     */
+    if (variantInCookie && availableIDs.includes(variantInCookie)) {
+      return variantInCookie;
+    }
+
+    /**
+     * no cookie exists, find variant
+     */
+    let n = 0;
+    const random = Math.random();
+    for (let i = 0; i < variants.length; i++) {
+      const variant = variants[i];
+      const testRatio = variant.testRatio;
+      n += testRatio!;
+      if (random < n) {
+        setCookie(cookieName, variant.id);
+        return variant.id;
+      }
+    }
+
+    /**
+     * no variant found, assign default content
+     */
+    setCookie(cookieName, contentId);
+
+    return contentId;
+  }
+
+  const winningVariantId = getAndSetVariantId();
+
+  const styleEl = document.getElementById(
+    `variants-styles-${contentId}`
+  ) as HTMLStyleElement;
+
+  /**
+   * For React to work, we need hydration to match SSR, so we completely remove this node and the styles tag.
+   */
+  if (isHydrationTarget) {
+    styleEl.remove();
+    const thisScriptEl = document.getElementById(
+      `variants-script-${contentId}`
+    );
+    thisScriptEl?.remove();
+  } else {
+    /* update styles to hide all variants except the winning variant */
+    const newStyleStr = variants
+      .concat({ id: contentId })
+      .filter((variant) => variant.id !== winningVariantId)
+      .map((value) => {
+        return `.variant-${value.id} {  display: none; }
+        `;
+      })
+      .join('');
+
+    /* TO-DO: check if this actually updates the style */
+    styleEl.innerHTML = newStyleStr;
+  }
+}
+
+/**
+ * NOTE: when this function is stringified, single-line comments can cause weird issues when compiled by Sveltekit.
+ * Make sure to write multi-line comments only.
+ */
+function bldrCntntScrpt(
+  variantContentId: string,
+  defaultContentId: string,
+  isHydrationTarget: boolean
+) {
+  if (!navigator.cookieEnabled) {
+    return;
+  }
+
+  function getCookie(name: string) {
+    const nameEQ = name + '=';
+    const ca = document.cookie.split(';');
+    for (let i = 0; i < ca.length; i++) {
+      let c = ca[i];
+      while (c.charAt(0) === ' ') c = c.substring(1, c.length);
+      if (c.indexOf(nameEQ) === 0) return c.substring(nameEQ.length, c.length);
+    }
+    return null;
+  }
+  const cookieName = `builder.tests.${defaultContentId}`;
+  const variantId = getCookie(cookieName);
+
+  /** get parent div by searching on `builder-content-id` attr */
+  const parentDiv = document.querySelector(
+    `[builder-content-id="${variantContentId}"]`
+  );
+
+  const variantIsDefaultContent = variantContentId === defaultContentId;
+
+  if (variantId === variantContentId) {
+    if (variantIsDefaultContent) {
+      /** the default content is already visible, no need to do anything */
+      return;
+    }
+
+    /** this is the winning variant and not already visible: remove `hidden` and `aria-hidden` attr */
+
+    parentDiv?.removeAttribute('hidden');
+    parentDiv?.removeAttribute('aria-hidden');
+  } else {
+    if (variantIsDefaultContent) {
+      if (isHydrationTarget) {
+        /**
+         * For React to work, we need to support hydration, in which case the first CSR will have none of the hidden variants.
+         * So we completely remove that node.
+         */
+        parentDiv?.remove();
+      } else {
+        /** this is not the winning variant, add `hidden` attr */
+        parentDiv?.setAttribute('hidden', 'true');
+        parentDiv?.setAttribute('aria-hidden', 'true');
+      }
+    }
+
+    /** This is not the winning variant, and it's not the default content.
+     * There's no need to hide it, because it's already hidden.
+     */
+    return;
+  }
+
+  return;
+}
+
+const isHydrationTarget = (target: Target) =>
+  target === 'react' ||
+  target === 'reactNative' ||
+  target === 'vue3' ||
+  target === 'vue2';
+
+/**
+ * We hardcode explicit function names here, because the `.toString()` of a function can change depending on the bundler.
+ * Some bundlers will minify the fn name, etc.
+ *
+ * So we hardcode the function names here, and then use those names in the script string to make sure the function names are consistent.
+ */
+const AB_TEST_FN_NAME = 'bldrAbTest';
+const CONTENT_FN_NAME = 'bldrCntntScrpt';
+
+export const getVariantsScriptString = (
+  variants: VariantData[],
+  contentId: string
+) => {
+  const fnStr = bldrAbTest.toString().replace(/\s+/g, ' ');
+  const fnStr2 = bldrCntntScrpt.toString().replace(/\s+/g, ' ');
+
+  return `
+  const ${AB_TEST_FN_NAME} = ${fnStr}
+  const ${CONTENT_FN_NAME} = ${fnStr2}
+  ${AB_TEST_FN_NAME}("${contentId}", ${JSON.stringify(
+    variants
+  )}, ${isHydrationTarget})
+  `;
+};
+
+export const getRenderContentScriptString = ({
+  parentContentId,
+  contentId,
+}: {
+  contentId: string;
+  parentContentId: string;
+}) => {
+  return `
+  ${CONTENT_FN_NAME}("${contentId}", "${parentContentId}", ${isHydrationTarget})`;
+};

package/src/components/render-content-variants/render-content-variants.svelte

@@ -0,0 +1,83 @@
+<script context="module" lang="ts">
+  type VariantsProviderProps = RenderContentProps;
+</script>
+
+<script lang="ts">
+  import {
+    checkShouldRunVariants,
+    getVariants,
+    getVariantsScriptString,
+  } from "./helpers";
+  import RenderContent from "../render-content/render-content.svelte";
+  import type { RenderContentProps } from "../render-content/render-content.types";
+  import { getDefaultCanTrack } from "../../helpers/canTrack";
+  import RenderInlinedStyles from "../render-inlined-styles.svelte";
+  import { handleABTestingSync } from "../../helpers/ab-tests";
+
+  export let content: VariantsProviderProps["content"];
+  export let canTrack: VariantsProviderProps["canTrack"];
+  export let apiKey: VariantsProviderProps["apiKey"];
+  export let apiVersion: VariantsProviderProps["apiVersion"];
+  export let customComponents: VariantsProviderProps["customComponents"];
+  export let model: VariantsProviderProps["model"];
+
+  let variantScriptStr = getVariantsScriptString(
+    getVariants(content).map((value) => ({
+      id: value.id!,
+      testRatio: value.testRatio,
+    })),
+    content?.id || ""
+  );
+  let shouldRenderVariants = checkShouldRunVariants({
+    canTrack: getDefaultCanTrack(canTrack),
+    content: content,
+  });
+  let hideVariantsStyleString = getVariants(content)
+    .map((value) => `.variant-${value.id} { display: none; } `)
+    .join("");
+  let contentToRender = checkShouldRunVariants({
+    canTrack: getDefaultCanTrack(canTrack),
+    content: content,
+  })
+    ? content
+    : handleABTestingSync({
+        item: content,
+        canTrack: getDefaultCanTrack(canTrack),
+      });
+</script>
+
+{#if shouldRenderVariants}
+  <RenderInlinedStyles
+    id={`variants-styles-${content?.id}`}
+    styles={hideVariantsStyleString}
+  />
+
+  <svelte:element this={"script"} id={`variants-script-${content?.id}`}
+    >{@html variantScriptStr}</svelte:element
+  >
+
+  {#each getVariants(content) as variant (variant.id)}
+    <RenderContent
+      content={variant}
+      {apiKey}
+      {apiVersion}
+      {canTrack}
+      {customComponents}
+      hideContent={true}
+      parentContentId={content?.id}
+      isSsrAbTest={shouldRenderVariants}
+    />
+  {/each}
+{/if}
+
+<RenderContent
+  {model}
+  content={contentToRender}
+  {apiKey}
+  {apiVersion}
+  {canTrack}
+  {customComponents}
+  classNameProp={`variant-${content?.id}`}
+  parentContentId={content?.id}
+  isSsrAbTest={shouldRenderVariants}
+/>

package/src/components/render-inlined-styles.svelte

@@ -1,26 +1,13 @@
 <script context="module" lang="ts">
   interface Props {
     styles: string;
+    id?: string;
   }
 </script>
 
 <script lang="ts">
-  import { TARGET } from "../constants/target.js";
-
   export let styles: Props["styles"];
-
-  $: tag = () => {
-    // NOTE: we have to obfuscate the name of the tag due to a limitation in the svelte-preprocessor plugin.
-    // https://github.com/sveltejs/vite-plugin-svelte/issues/315#issuecomment-1109000027
-    return ("sty" + "le") as any;
-  };
-  $: injectedStyleScript = () => {
-    return `<${tag()}>${styles}</${tag()}>`;
-  };
+  export let id: Props["id"];
 </script>
 
-{#if TARGET === "svelte" || TARGET === "qwik"}
-  {@html injectedStyleScript()}
-{:else}
-  <svelte:element this={tag()}>{styles}</svelte:element>
-{/if}
+<svelte:element this={"sty" + "le"} {id}>{@html styles}</svelte:element>

package/src/constants/sdk-version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.3.1"
+export const SDK_VERSION = "0.4.0"

package/src/functions/get-content/generate-content-url.test.ts

@@ -92,4 +92,21 @@ describe('Generate Content URL', () => {
       `Invalid apiVersion: expected 'v2' or 'v3', received 'INVALID_API_VERSION'`
     );
   });
+
+  test('generate content url with enrich option true', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      enrich: true,
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('generate content url with enrich option not present', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+    });
+    expect(output).toMatchSnapshot();
+  });
 });

package/src/functions/get-content/generate-content-url.ts

@@ -15,6 +15,7 @@ export const generateContentUrl = (options: GetContentOptions): URL => {
     model,
     apiKey,
     includeRefs = true,
+    enrich,
     locale,
     apiVersion = DEFAULT_API_VERSION,
   } = options;
@@ -32,7 +33,7 @@ export const generateContentUrl = (options: GetContentOptions): URL => {
   const url = new URL(
     `https://cdn.builder.io/api/${apiVersion}/content/${model}?apiKey=${apiKey}&limit=${limit}&noTraverse=${noTraverse}&includeRefs=${includeRefs}${
       locale ? `&locale=${locale}` : ''
-    }`
+    }${enrich ? `&enrich=${enrich}` : ''}`
   );
 
   const queryOptions = {

package/src/functions/get-content/index.ts

@@ -1,60 +1,91 @@
+import { TARGET } from '../../constants/target.js';
+import { handleABTesting } from '../../helpers/ab-tests.js';
+import { getDefaultCanTrack } from '../../helpers/canTrack.js';
 import { logger } from '../../helpers/logger.js';
 import type { BuilderContent } from '../../types/builder-content.js';
 import { fetch } from '../get-fetch.js';
-import { handleABTesting } from './ab-testing.js';
+import { isBrowser } from '../is-browser.js';
 import { generateContentUrl } from './generate-content-url.js';
 import type { GetContentOptions } from './types.js';
 
+const checkContentHasResults = (
+  content: ContentResponse
+): content is ContentResults => 'results' in content;
+
 export async function getContent(
   options: GetContentOptions
 ): Promise<BuilderContent | null> {
   const allContent = await getAllContent({ ...options, limit: 1 });
-  if (allContent && 'results' in allContent) {
-    return allContent?.results[0] || null;
+  if (allContent && checkContentHasResults(allContent)) {
+    return allContent.results[0] || null;
   }
 
   return null;
 }
 
+type ContentResults = {
+  results: BuilderContent[];
+};
+
 type ContentResponse =
-  | {
-      results: BuilderContent[];
-    }
+  | ContentResults
   | {
       status: number;
       message: string;
     };
 
+const fetchContent = async (options: GetContentOptions) => {
+  const url = generateContentUrl(options);
+
+  const res = await fetch(url.href);
+  const content = await (res.json() as Promise<ContentResponse>);
+  return content;
+};
+
+/**
+ * Exported only for testing purposes. Should not be used directly.
+ */
+export const processContentResult = async (
+  options: GetContentOptions,
+  content: ContentResults
+) => {
+  const canTrack = getDefaultCanTrack(options.canTrack);
+
+  if (!canTrack) return content;
+  if (!(isBrowser() || TARGET === 'reactNative')) return content;
+
+  /**
+   * For client-side navigations, it is ideal to handle AB testing at this point instead of using our
+   * complex multi-rendering variants approach, which is only needed for SSR'd content.
+   *
+   * This is also where react-native would handle AB testing.
+   */
+  try {
+    const newResults: BuilderContent[] = [];
+    for (const item of content.results) {
+      newResults.push(await handleABTesting({ item, canTrack }));
+    }
+    content.results = newResults;
+  } catch (e) {
+    logger.error('Could not process A/B tests. ', e);
+  }
+
+  return content;
+};
+
 export async function getAllContent(
   options: GetContentOptions
 ): Promise<ContentResponse | null> {
   try {
     const url = generateContentUrl(options);
+    const content = await fetchContent(options);
 
-    const res = await fetch(url.href);
-    const content = await (res.json() as Promise<ContentResponse>);
-
-    if ('status' in content && !('results' in content)) {
+    if (!checkContentHasResults(content)) {
       logger.error('Error fetching data. ', { url, content, options });
       return content;
     }
 
-    const canTrack = options.canTrack !== false;
-    try {
-      if (
-        canTrack &&
-        // This makes sure we have a non-error response with the results array.
-        Array.isArray(content.results)
-      ) {
-        for (const item of content.results) {
-          await handleABTesting({ item, canTrack });
-        }
-      }
-    } catch (e) {
-      logger.error('Could not setup A/B testing. ', e);
-    }
-
-    return content;
+    return processContentResult(options, content);
   } catch (error) {
     logger.error('Error fetching data. ', error);
     return null;

package/src/functions/get-content/types.ts

@@ -23,6 +23,7 @@ export interface GetContentOptions {
   /**
    * If set to `true`, it will lazy load symbols/references.
    * If set to `false`, it will render the entire content tree eagerly.
+   * @deprecated use `enrich` instead
    */
   noTraverse?: boolean;
 
@@ -36,9 +37,15 @@ export interface GetContentOptions {
 
   /**
    * Include references in the response. Defaults to `true`.
+   * @deprecated use `enrich` instead
    */
   includeRefs?: boolean;
 
+  /**
+   * Include multilevel references in the response.
+   */
+  enrich?: boolean;
+
   /**
    * If provided, the API will auto-resolve localized objects to the value of this `locale` key.
    */