@builder.io/sdk-react 0.2.3-2 → 0.2.3-4

package/packages/react/src/functions/extract-text-styles.ts

@@ -0,0 +1,39 @@
+const TEXT_STYLE_KEYS = [
+  'color',
+  'whiteSpace',
+  'direction',
+  'hyphens',
+  'overflowWrap',
+];
+
+/**
+ * Check if the key represent a CSS style property that applies to text
+ * See MDN docs for refrence of what properties apply to text.
+ * https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Fundamentals#summary
+ */
+const isTextStyle = (key: string) => {
+  return (
+    TEXT_STYLE_KEYS.includes(key) ||
+    key.startsWith('font') ||
+    key.startsWith('text') ||
+    key.startsWith('letter') ||
+    key.startsWith('line') ||
+    key.startsWith('word') ||
+    key.startsWith('writing')
+  );
+};
+
+/**
+ * Extract styles that apply to text from a style object.
+ */
+export const extractTextStyles = (styles: Partial<CSSStyleDeclaration>) => {
+  const textStyles: Partial<CSSStyleDeclaration> = {};
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Object.entries(styles).forEach(([key, value]: [any, any]) => {
+    if (isTextStyle(key)) {
+      textStyles[key] = value;
+    }
+  });
+
+  return textStyles;
+};

package/packages/react/src/functions/fast-clone.ts

@@ -0,0 +1,5 @@
+/**
+ * We need to serialize values to a string in case there are Proxy values, as is the case with SolidJS etc.
+ */
+export const fastClone = <T extends object>(obj: T): T =>
+  JSON.parse(JSON.stringify(obj));

package/packages/react/src/functions/get-block-actions-handler.ts

@@ -0,0 +1,20 @@
+import type { BuilderContextInterface } from '../context/types.js';
+import type { BuilderBlock } from '../types/builder-block.js';
+import { evaluate } from './evaluate.js';
+
+type Options = {
+  block: BuilderBlock;
+} & Pick<BuilderContextInterface, 'state' | 'context'>;
+
+type EventHandler = (event: Event) => any;
+
+export const createEventHandler =
+  (value: string, options: Options): EventHandler =>
+  (event) =>
+    evaluate({
+      code: value,
+      context: options.context,
+      state: options.state,
+      event,
+      isExpression: false,
+    });

package/packages/react/src/functions/get-block-actions.ts

@@ -0,0 +1,25 @@
+import type { BuilderContextInterface } from '../context/types.js';
+import type { BuilderBlock } from '../types/builder-block.js';
+import { getEventHandlerName } from './event-handler-name.js';
+import { createEventHandler } from './get-block-actions-handler.js';
+
+type Actions = { [index: string]: (event: Event) => any };
+
+export function getBlockActions(
+  options: {
+    block: BuilderBlock;
+  } & Pick<BuilderContextInterface, 'state' | 'context'>
+): Actions {
+  const obj: Actions = {};
+  const optionActions = options.block.actions ?? {};
+
+  for (const key in optionActions) {
+    // eslint-disable-next-line no-prototype-builtins
+    if (!optionActions.hasOwnProperty(key)) {
+      continue;
+    }
+    const value = optionActions[key];
+    obj[getEventHandlerName(key)] = createEventHandler(value, options);
+  }
+  return obj;
+}

package/packages/react/src/functions/get-block-component-options.ts

@@ -0,0 +1,12 @@
+import type { BuilderBlock } from '../types/builder-block.js';
+
+export function getBlockComponentOptions(block: BuilderBlock) {
+  return {
+    ...block.component?.options,
+    ...(block as any).options,
+    /**
+     * Our built-in components frequently make use of the block, so we provide all of it under `builderBlock`
+     */
+    builderBlock: block,
+  };
+}

package/packages/react/src/functions/get-block-properties.ts

@@ -0,0 +1,75 @@
+import { TARGET } from '../constants/target.js';
+import { convertStyleMapToCSSArray } from '../helpers/css.js';
+import type { BuilderBlock } from '../types/builder-block.js';
+import { transformBlockProperties } from './transform-block-properties.js';
+
+const extractRelevantRootBlockProperties = (block: BuilderBlock) => {
+  // currently we are only spreading the `href` property
+  // TO-DO: potentially spread all properties from block, but only if they are not already defined by BuilderBlock
+
+  // const {
+  //   '@type': _type,
+  //   '@version': _version,
+  //   id: _id,
+  //   tagName: _tagName,
+  //   layerName: _layerName,
+  //   groupLocked: _groupLocked,
+  //   layerLocked: _layerLocked,
+  //   class: _class,
+  //   children: _children,
+  //   responsiveStyles: _responsiveStyles,
+  //   component: _component,
+  //   bindings: _bindings,
+  //   meta: _meta,
+  //   actions: _actions,
+  //   properties: _properties,
+  //   code: _code,
+  //   repeat: _repeat,
+  //   animations: _animations,
+  //   style: _style,
+  //   hide: _hide,
+  //   show: _show,
+  //   // anything set by dynamic bindings outside of predefined `BuilderBlock` properties
+  //   ...remainingBlockProperties
+  // } = block;
+
+  return { href: (block as any).href };
+};
+
+export function getBlockProperties(block: BuilderBlock) {
+  const properties = {
+    ...extractRelevantRootBlockProperties(block),
+    ...block.properties,
+    'builder-id': block.id,
+    style: getStyleAttribute(block.style),
+    class: [block.id, 'builder-block', block.class, block.properties?.class]
+      .filter(Boolean)
+      .join(' '),
+  };
+
+  return transformBlockProperties(properties);
+}
+/**
+ * Svelte does not support style attribute as an object so we need to flatten it.
+ *
+ * Additionally, Svelte, Vue and other frameworks use kebab-case styles, so we need to convert them.
+ */
+function getStyleAttribute(
+  style: Partial<CSSStyleDeclaration> | undefined
+): string | Partial<CSSStyleDeclaration> | undefined {
+  if (!style) {
+    return undefined;
+  }
+
+  switch (TARGET) {
+    case 'svelte':
+    case 'vue2':
+    case 'vue3':
+    case 'solid':
+      return convertStyleMapToCSSArray(style).join(' ');
+    case 'qwik':
+    case 'reactNative':
+    case 'react':
+      return style;
+  }
+}

package/packages/react/src/functions/get-builder-search-params/fn.test.ts

@@ -0,0 +1,19 @@
+import { convertSearchParamsToQueryObject, getBuilderSearchParams } from '.';
+
+const querystring =
+  'someotherValue=jklsjfdal&abc=klfdjklgfds&builder.cachebust=true&builder.preview=page&builder.noCache=true&__builder_editing__=true&builder.overrides.page=037948e52eaf4743afed464f02c70da4&builder.overrides.037948e52eaf4743afed464f02c70da4=037948e52eaf4743afed464f02c70da4&builder.overrides.page%3A%2F=037948e52eaf4743afed464f02c70da4&preview_theme_id=128854393017';
+
+const url = new URL(`localhost:3000/about-us?${querystring}`);
+
+describe('Get Builder SearchParams', () => {
+  test('correctly converts URLSearchParams to object', () => {
+    const output = convertSearchParamsToQueryObject(url.searchParams);
+    expect(output).toMatchSnapshot();
+  });
+  test('correctly extracts all builder params from a query object', () => {
+    const output = getBuilderSearchParams(
+      convertSearchParamsToQueryObject(url.searchParams)
+    );
+    expect(output).toMatchSnapshot();
+  });
+});

package/packages/react/src/functions/get-builder-search-params/index.ts

@@ -0,0 +1,50 @@
+import { isBrowser } from '../is-browser.js';
+
+const BUILDER_SEARCHPARAMS_PREFIX = 'builder.';
+const BUILDER_OPTIONS_PREFIX = 'options.';
+type QueryObject = Record<string, string | string[]>;
+
+export const convertSearchParamsToQueryObject = (
+  searchParams: URLSearchParams
+): QueryObject => {
+  const options: Record<string, string> = {};
+  searchParams.forEach((value, key) => {
+    options[key] = value;
+  });
+  return options;
+};
+
+export const getBuilderSearchParams = (
+  _options: QueryObject | URLSearchParams | undefined
+) => {
+  if (!_options) {
+    return {};
+  }
+  const options = normalizeSearchParams(_options);
+
+  const newOptions: QueryObject = {};
+  Object.keys(options).forEach((key) => {
+    if (key.startsWith(BUILDER_SEARCHPARAMS_PREFIX)) {
+      const trimmedKey = key
+        .replace(BUILDER_SEARCHPARAMS_PREFIX, '')
+        .replace(BUILDER_OPTIONS_PREFIX, '');
+      newOptions[trimmedKey] = options[key];
+    }
+  });
+  return newOptions;
+};
+
+export const getBuilderSearchParamsFromWindow = () => {
+  if (!isBrowser()) {
+    return {};
+  }
+  const searchParams = new URLSearchParams(window.location.search);
+  return getBuilderSearchParams(searchParams);
+};
+
+export const normalizeSearchParams = (
+  searchParams: QueryObject | URLSearchParams
+): QueryObject =>
+  searchParams instanceof URLSearchParams
+    ? convertSearchParamsToQueryObject(searchParams)
+    : searchParams;

package/packages/react/src/functions/get-content/ab-testing.ts

@@ -0,0 +1,132 @@
+import type {
+  BuilderContent,
+  BuilderContentVariation,
+} from '../../types/builder-content.js';
+import {
+  getContentVariationCookie,
+  setContentVariationCookie,
+} from '../../helpers/ab-tests.js';
+import type { Overwrite } from '../../types/typescript.js';
+import type { CanTrack } from '../../types/can-track.js';
+import { checkIsDefined } from '../../helpers/nullable.js';
+
+type BuilderContentWithVariations = Overwrite<
+  BuilderContent,
+  Required<Pick<BuilderContent, 'variations' | 'id'>>
+>;
+
+const checkIsBuilderContentWithVariations = (
+  item: BuilderContent
+): item is BuilderContentWithVariations =>
+  checkIsDefined(item.id) &&
+  checkIsDefined(item.variations) &&
+  Object.keys(item.variations).length > 0;
+
+/**
+ * Randomly assign a variation to this user and store it in cookies/storage
+ */
+const getRandomVariationId = ({
+  id,
+  variations,
+}: BuilderContentWithVariations) => {
+  let n = 0;
+  const random = Math.random();
+
+  // loop over variations test ratios, incrementing a counter,
+  // until we find the variation that this user should be assigned to
+  for (const id in variations) {
+    const testRatio = variations[id]?.testRatio;
+    n += testRatio!;
+
+    if (random < n) {
+      return id;
+    }
+  }
+
+  // `item.variations` does not include the default variation
+  // if we arrive here, then it means that the random number fits in the default variation bucket
+  return id;
+};
+
+const getTestFields = ({
+  item,
+  testGroupId,
+}: {
+  item: BuilderContentWithVariations;
+  testGroupId: string;
+}): TestFields => {
+  const variationValue = item.variations[testGroupId];
+  if (
+    testGroupId === item.id ||
+    // handle edge-case where `testGroupId` points to non-existing variation
+    !variationValue
+  ) {
+    return {
+      testVariationId: item.id,
+      testVariationName: 'Default',
+    };
+  } else {
+    return {
+      data: variationValue.data,
+      testVariationId: variationValue.id,
+      testVariationName:
+        variationValue.name || (variationValue.id === item.id ? 'Default' : ''),
+    };
+  }
+};
+
+type TestFields = {
+  data?: BuilderContentVariation['data'];
+  testVariationId?: string;
+  testVariationName: string;
+};
+
+const getContentVariation = async ({
+  item,
+  canTrack,
+}: {
+  item: BuilderContentWithVariations;
+} & CanTrack): Promise<TestFields> => {
+  // try to find test variation in cookies/storage
+  const testGroupId = await getContentVariationCookie({
+    canTrack,
+    contentId: item.id,
+  });
+
+  const testFields = testGroupId
+    ? getTestFields({ item, testGroupId })
+    : undefined;
+
+  if (testFields) {
+    return testFields;
+  } else {
+    // if variation not found in storage, assign a random variation to this user
+    const randomVariationId = getRandomVariationId({
+      variations: item.variations,
+      id: item.id,
+    });
+
+    // store variation in cookies/storage
+    setContentVariationCookie({
+      contentId: item.id,
+      value: randomVariationId,
+      canTrack,
+    }).catch((err) => {
+      console.error('could not store A/B test variation: ', err);
+    });
+
+    return getTestFields({ item, testGroupId: randomVariationId });
+  }
+};
+
+export const handleABTesting = async ({
+  item,
+  canTrack,
+}: { item: BuilderContent } & CanTrack) => {
+  if (!checkIsBuilderContentWithVariations(item)) {
+    return;
+  }
+
+  const variationValue = await getContentVariation({ item, canTrack });
+  Object.assign(item, variationValue);
+};

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

@@ -0,0 +1,95 @@
+import { generateContentUrl } from './generate-content-url';
+import type { GetContentOptions } from './types';
+
+const testKey = 'YJIGb4i01jvw0SRdL5Bt';
+const testModel = 'page';
+const testId = 'c1b81bab59704599b997574eb0736def';
+
+const options = {
+  cachebust: 'true',
+  noCache: 'true',
+  'overrides.037948e52eaf4743afed464f02c70da4':
+    '037948e52eaf4743afed464f02c70da4',
+  'overrides.page': '037948e52eaf4743afed464f02c70da4',
+  'overrides.page:/': '037948e52eaf4743afed464f02c70da4',
+  preview: 'page',
+};
+
+describe('Generate Content URL', () => {
+  test('generates the proper value for a simple query', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      query: { id: testId },
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('Handles overrides correctly', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      query: { id: testId },
+      options,
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('generate content url with apiVersion as default', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      query: { id: testId },
+      options,
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('generate content url with apiVersion as v2', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      query: { id: testId },
+      options,
+      apiVersion: 'v2',
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('generate content url with apiVersion as v3', () => {
+    const output = generateContentUrl({
+      apiKey: testKey,
+      model: testModel,
+      query: { id: testId },
+      options,
+      apiVersion: 'v3',
+    });
+    expect(output).toMatchSnapshot();
+  });
+
+  test('throw error when trying to generate content url with apiVersion as v1', () => {
+    expect(() => {
+      generateContentUrl({
+        apiKey: testKey,
+        model: testModel,
+        query: { id: testId },
+        options,
+        apiVersion: 'v1' as GetContentOptions['apiVersion'],
+      });
+    }).toThrow(`Invalid apiVersion: expected 'v2' or 'v3', received 'v1'`);
+  });
+
+  test('throw error when trying to generate content url with an invalid apiVersion value', () => {
+    expect(() => {
+      generateContentUrl({
+        apiKey: testKey,
+        model: testModel,
+        query: { id: testId },
+        options,
+        apiVersion: 'INVALID_API_VERSION' as GetContentOptions['apiVersion'],
+      });
+    }).toThrow(
+      `Invalid apiVersion: expected 'v2' or 'v3', received 'INVALID_API_VERSION'`
+    );
+  });
+});

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

@@ -0,0 +1,59 @@
+import { flatten } from '../../helpers/flatten.js';
+import {
+  getBuilderSearchParamsFromWindow,
+  normalizeSearchParams,
+} from '../get-builder-search-params/index.js';
+import type { GetContentOptions } from './types.js';
+import { DEFAULT_API_VERSION } from '../../types/api-version';
+
+export const generateContentUrl = (options: GetContentOptions): URL => {
+  const {
+    limit = 30,
+    userAttributes,
+    query,
+    noTraverse = false,
+    model,
+    apiKey,
+    includeRefs = true,
+    locale,
+    apiVersion = DEFAULT_API_VERSION,
+  } = options;
+
+  if (!apiKey) {
+    throw new Error('Missing API key');
+  }
+
+  if (!['v2', 'v3'].includes(apiVersion)) {
+    throw new Error(
+      `Invalid apiVersion: expected 'v2' or 'v3', received '${apiVersion}'`
+    );
+  }
+
+  const url = new URL(
+    `https://cdn.builder.io/api/${apiVersion}/content/${model}?apiKey=${apiKey}&limit=${limit}&noTraverse=${noTraverse}&includeRefs=${includeRefs}${
+      locale ? `&locale=${locale}` : ''
+    }`
+  );
+
+  const queryOptions = {
+    ...getBuilderSearchParamsFromWindow(),
+    ...normalizeSearchParams(options.options || {}),
+  };
+
+  const flattened = flatten(queryOptions);
+  for (const key in flattened) {
+    url.searchParams.set(key, String(flattened[key]));
+  }
+
+  if (userAttributes) {
+    url.searchParams.set('userAttributes', JSON.stringify(userAttributes));
+  }
+  if (query) {
+    const flattened = flatten({ query });
+    for (const key in flattened) {
+      url.searchParams.set(key, JSON.stringify((flattened as any)[key]));
+    }
+  }
+
+  return url;
+};

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

@@ -0,0 +1,62 @@
+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 { generateContentUrl } from './generate-content-url.js';
+import type { GetContentOptions } from './types.js';
+
+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;
+  }
+
+  return null;
+}
+
+type ContentResponse =
+  | {
+      results: BuilderContent[];
+    }
+  | {
+      status: number;
+      message: string;
+    };
+
+export async function getAllContent(
+  options: GetContentOptions
+): Promise<ContentResponse | null> {
+  try {
+    const url = generateContentUrl(options);
+
+    const res = await fetch(url.href);
+    const content = await (res.json() as Promise<ContentResponse>);
+
+    if ('status' in content && !('results' in 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;
+  } catch (error) {
+    logger.error('Error fetching data. ', error);
+    return null;
+  }
+}

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

@@ -0,0 +1,53 @@
+export interface GetContentOptions {
+  /** The model to get content for */
+  model: string;
+
+  /** Your public API key */
+  apiKey: string;
+
+  /** Number of items to fetch. Default is 1 */
+  limit?: number;
+
+  /** User attributes to target on, such as { urlPath: '/foo', device: 'mobile', ...etc } */
+  userAttributes?: (Record<string, string> & { urlPath?: string }) | null;
+
+  /** Custom query */
+  query?: Record<string, any>;
+
+  /**
+   * Any other API options.
+   * Accepts both a key/value object or a `URLSearchParams` instance
+   * */
+  options?: Record<string, any> | URLSearchParams;
+
+  /**
+   * If set to `true`, it will lazy load symbols/references.
+   * If set to `false`, it will render the entire content tree eagerly.
+   */
+  noTraverse?: boolean;
+
+  /**
+   * If set to `false`, it will not use cookies to target content. Therefore, A/B Testing will be disabled and
+   * only the default variation will be returned to every user.
+   *
+   * Defaults to `true`.
+   */
+  canTrack?: boolean;
+
+  /**
+   * Include references in the response. Defaults to `true`.
+   */
+  includeRefs?: boolean;
+
+  /**
+   * If provided, the API will auto-resolve localized objects to the value of this `locale` key.
+   */
+  locale?: string;
+
+  /**
+   * If provided, sets the Builder API version used to fetch content.
+   *
+   * Defaults to `v3`.
+   */
+  apiVersion?: 'v2' | 'v3';
+}

package/packages/react/src/functions/get-fetch.ts

@@ -0,0 +1,18 @@
+import { getGlobalThis } from './get-global-this.js';
+
+function getFetch(): typeof global.fetch {
+  const globalFetch: typeof global.fetch = getGlobalThis().fetch;
+
+  if (typeof globalFetch === 'undefined') {
+    console.warn(
+      `Builder SDK could not find a global fetch function. Make sure you have a polyfill for fetch in your project. 
+      For more information, read https://github.com/BuilderIO/this-package-uses-fetch`
+    );
+
+    throw new Error('Builder SDK could not find a global `fetch` function');
+  }
+
+  return globalFetch;
+}
+
+export const fetch = getFetch();

package/packages/react/src/functions/get-global-this.ts

@@ -0,0 +1,17 @@
+type Global = typeof global | typeof window | typeof self | typeof globalThis;
+
+export function getGlobalThis(): Global {
+  if (typeof globalThis !== 'undefined') {
+    return globalThis;
+  }
+  if (typeof window !== 'undefined') {
+    return window;
+  }
+  if (typeof global !== 'undefined') {
+    return global;
+  }
+  if (typeof self !== 'undefined') {
+    return self;
+  }
+  return globalThis;
+}