@builder.io/sdk-react 0.2.3-3 → 0.2.3

package/dist/sdk/types/builder-block.d.ts

@@ -0,0 +1,66 @@
+type JSONValue = string | number | boolean | JSONObject | JSONArray;
+interface JSONObject {
+    [x: string]: JSONValue;
+}
+interface JSONArray extends Array<JSONValue> {
+}
+/** @todo typedoc this */
+export interface BuilderBlock {
+    '@type': '@builder.io/sdk:Element';
+    '@version'?: number;
+    id?: string;
+    tagName?: string;
+    layerName?: string;
+    groupLocked?: boolean;
+    layerLocked?: boolean;
+    /** @todo make alias for properties.class */
+    class?: string;
+    children?: BuilderBlock[];
+    responsiveStyles?: {
+        large?: Partial<CSSStyleDeclaration>;
+        medium?: Partial<CSSStyleDeclaration>;
+        small?: Partial<CSSStyleDeclaration>;
+        /** @deprecated */
+        xsmall?: Partial<CSSStyleDeclaration>;
+    };
+    component?: {
+        name: string;
+        options?: any;
+        tag?: string;
+    };
+    bindings?: {
+        [key: string]: string;
+    };
+    meta?: {
+        [key: string]: JSONValue;
+    };
+    actions?: {
+        [key: string]: string;
+    };
+    properties?: {
+        [key: string]: string;
+    };
+    code?: {
+        bindings?: {
+            [key: string]: string;
+        };
+        actions?: {
+            [key: string]: string;
+        };
+    };
+    repeat?: {
+        collection: string;
+        itemName?: string;
+    } | null;
+    animations?: any[];
+    style?: Partial<CSSStyleDeclaration>;
+    /**
+     * generated by the "Hide If" binding
+     */
+    hide?: boolean;
+    /**
+     * generated by the "Show If" binding
+     */
+    show?: boolean;
+}
+export {};

package/dist/sdk/types/builder-content.d.ts

@@ -0,0 +1,46 @@
+import type { BuilderBlock } from './builder-block.js';
+import type { Input } from './input.js';
+import type { Nullable } from './typescript.js';
+export interface Breakpoints {
+    small: number;
+    medium: number;
+}
+export interface BuilderContentVariation {
+    data?: {
+        title?: string;
+        blocks?: BuilderBlock[];
+        inputs?: Input[];
+        state?: {
+            [key: string]: any;
+        };
+        jsCode?: string;
+        tsCode?: string;
+        httpRequests?: {
+            [key: string]: string;
+        };
+        [key: string]: any;
+    };
+    name?: string;
+    testRatio?: number;
+    id?: string;
+    meta?: {
+        breakpoints?: Nullable<Breakpoints>;
+        [key: string]: any;
+    };
+}
+export interface BuilderContent extends BuilderContentVariation {
+    '@version'?: number;
+    id?: string;
+    name?: string;
+    published?: 'published' | 'draft' | 'archived';
+    modelId?: string;
+    priority?: number;
+    lastUpdated?: number;
+    startDate?: number;
+    endDate?: number;
+    variations?: {
+        [id: string]: BuilderContentVariation | undefined;
+    };
+    testVariationId?: string;
+    testVariationName?: string;
+}

package/dist/sdk/types/can-track.d.ts

@@ -0,0 +1,3 @@
+export type CanTrack = {
+    canTrack: boolean;
+};

package/dist/sdk/types/components.d.ts

@@ -0,0 +1,105 @@
+import type { BuilderElement } from './element';
+import type { Input } from './input';
+export interface ComponentInfo {
+    /**
+     * Name your component something unique, e.g. 'MyButton'. You can override built-in components
+     * by registering a component with the same name, e.g. 'Text', to replace the built-in text component
+     */
+    name: string;
+    description?: string;
+    /**
+     * Link to a documentation page for this component
+     */
+    docsLink?: string;
+    image?: string;
+    /**
+     * Input schema for your component for users to fill in the options
+     */
+    inputs?: Input[];
+    class?: any;
+    type?: 'angular' | 'webcomponent' | 'react' | 'vue';
+    defaultStyles?: {
+        [key: string]: string;
+    };
+    /**
+     * Turn on if your component can accept children. Be sure to use in combination with
+     * withChildren(YourComponent) like here
+     * github.com/BuilderIO/builder/blob/master/examples/react-design-system/src/components/HeroWithChildren/HeroWithChildren.builder.js#L5
+     */
+    canHaveChildren?: boolean;
+    fragment?: boolean;
+    /**
+     * Do not wrap a component in a dom element. Be sure to use {...props.attributes} with this option
+     * like here github.com/BuilderIO/builder/blob/master/packages/react/src/blocks/forms/Input.tsx#L34
+     */
+    noWrap?: boolean;
+    /**
+     * Default children
+     */
+    defaultChildren?: BuilderElement[];
+    defaults?: Partial<BuilderElement>;
+    hooks?: {
+        [key: string]: string | Function;
+    };
+    /**
+     * Hide your component in editor, useful for gradually deprecating components
+     */
+    hideFromInsertMenu?: boolean;
+    tag?: string;
+    static?: boolean;
+    /**
+     * Passing a list of model names will restrict using the component to only the models listed here, otherwise it'll be available for all models
+     */
+    models?: string[];
+    /**
+     * Specify restrictions direct children must match
+     */
+    childRequirements?: {
+        /** Message to show when this doesn't match, e.g. "Children of 'Columns' must be a 'Column'" */
+        message: string;
+        /** Simple way to say children must be a specific component name */
+        component?: string;
+        /**
+         * More advanced - specify a MongoDB-style query (using sift.js github.com/crcn/sift.js)
+         * of what the children objects should match, e.g.
+         *
+         * @example
+         *  query: {
+         *    // Child of this element must be a 'Button' or 'Text' component
+         *    'component.name': { $in: ['Button', 'Text'] }
+         *  }
+         */
+        query?: any;
+    };
+    /**
+     * Specify restrictions any parent must match
+     */
+    requiresParent?: {
+        /** Message to show when this doesn't match, e.g. "'Add to cart' buttons must be within a 'Product box'" */
+        message: string;
+        /** Simple way to say a parent must be a specific component name, e.g. 'Product box' */
+        component?: string;
+        /**
+         * More advanced - specify a MongoDB-style query (using sift.js github.com/crcn/sift.js)
+         * of what at least one parent in the parents hierarchy should match, e.g.
+         *
+         * @example
+         *  query: {
+         *    // Thils element must be somewhere inside either a 'Product box' or 'Collection' component
+         *    'component.name': { $in: ['Product Box', 'Collection'] }
+         *  }
+         */
+        query?: any;
+    };
+    /** not yet implemented */
+    friendlyName?: string;
+    /**
+     * Use to restrict access to your component based on a the current user permissions
+     * By default components will show to all users
+     * for more information on permissions in builder check https://www.builder.io/c/docs/guides/roles-and-permissions
+     */
+    requiredPermissions?: Array<Permission>;
+    hidden?: boolean;
+}
+type Permission = 'read' | 'publish' | 'editCode' | 'editDesigns' | 'admin' | 'create';
+export {};

package/dist/sdk/types/deep-partial.d.ts

@@ -0,0 +1,3 @@
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends Array<infer U> ? Array<DeepPartial<U>> : T[P] extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : DeepPartial<T[P]>;
+};

package/dist/sdk/types/element.d.ts

@@ -0,0 +1,59 @@
+type JSONValue = string | number | boolean | JSONObject | JSONArray;
+interface JSONObject {
+    [x: string]: JSONValue;
+}
+interface JSONArray extends Array<JSONValue> {
+}
+/** @todo typedoc this */
+export interface BuilderElement {
+    '@type': '@builder.io/sdk:Element';
+    '@version'?: number;
+    id?: string;
+    tagName?: string;
+    layerName?: string;
+    groupLocked?: boolean;
+    layerLocked?: boolean;
+    /** @todo make alias for properties.class */
+    class?: string;
+    children?: BuilderElement[];
+    responsiveStyles?: {
+        large?: Partial<CSSStyleDeclaration>;
+        medium?: Partial<CSSStyleDeclaration>;
+        small?: Partial<CSSStyleDeclaration>;
+        /** @deprecated */
+        xsmall?: Partial<CSSStyleDeclaration>;
+    };
+    component?: {
+        name: string;
+        options?: any;
+        tag?: string;
+    };
+    bindings?: {
+        [key: string]: string;
+    };
+    meta?: {
+        [key: string]: JSONValue;
+    };
+    actions?: {
+        [key: string]: string;
+    };
+    properties?: {
+        [key: string]: string;
+    };
+    code?: {
+        bindings?: {
+            [key: string]: string;
+        };
+        actions?: {
+            [key: string]: string;
+        };
+    };
+    repeat?: {
+        collection: string;
+        itemName?: string;
+    } | null;
+    animations?: Animation[];
+}
+interface Animation {
+}
+export {};

package/dist/sdk/types/input.d.ts

@@ -0,0 +1,121 @@
+export interface Input {
+    /** This is the name of the component prop this input represents */
+    name: string;
+    /** A friendlier name to show in the UI if the component prop name is not ideal for end users */
+    friendlyName?: string;
+    /** @hidden @deprecated */
+    description?: string;
+    /** A default value to use */
+    defaultValue?: any;
+    /**
+     * The type of input to use, such as 'text'
+     *
+     * See all available inputs [here](https://www.builder.io/c/docs/custom-react-components#input-types)
+     * and you can create your own custom input types and associated editor UIs with [plugins](https://www.builder.io/c/docs/extending/plugins)
+     */
+    type: string;
+    /** Is this input mandatory or not */
+    required?: boolean;
+    /** @hidden */
+    autoFocus?: boolean;
+    subFields?: Input[];
+    /**
+     * Additional text to render in the UI to give guidance on how to use this
+     *
+     * @example
+     * ```js
+     * helperText: 'Be sure to use a proper URL, starting with "https://"'
+     * 111
+     */
+    helperText?: string;
+    /** @hidden */
+    allowedFileTypes?: string[];
+    /** @hidden */
+    imageHeight?: number;
+    /** @hidden */
+    imageWidth?: number;
+    /** @hidden */
+    mediaHeight?: number;
+    /** @hidden */
+    mediaWidth?: number;
+    /** @hidden */
+    hideFromUI?: boolean;
+    /** @hidden */
+    modelId?: string;
+    /**
+     * Number field type validation maximum accepted input
+     */
+    max?: number;
+    /**
+     * Number field type validation minimum accepted input
+     */
+    min?: number;
+    /**
+     * Number field type step size when using arrows
+     */
+    step?: number;
+    /**
+     * Set this to `true` to show the editor for this input when
+     * children of this component are selected. This is useful for things
+     * like Tabs, such that users may not always select the Tabs component
+     * directly but will still be looking for how to add additional tabs
+     */
+    broadcast?: boolean;
+    /**
+     * Set this to `true` to show the editor for this input when
+     * group locked parents of this component are selected. This is useful
+     * to bubble up important inputs for locked groups, like text and images
+     */
+    bubble?: boolean;
+    /**
+     * Set this to `true` if you want this component to be translatable
+     */
+    localized?: boolean;
+    /** @hidden */
+    options?: {
+        [key: string]: any;
+    };
+    /**
+     * For "text" input type, specifying an enum will show a dropdown of options instead
+     */
+    enum?: string[] | {
+        label: string;
+        value: any;
+        helperText?: string;
+    }[];
+    /** Regex field validation for all string types (text, longText, html, url, etc) */
+    regex?: {
+        /** pattern to test, like "^\/[a-z]$" */
+        pattern: string;
+        /** flags for the RegExp constructor, e.g. "gi"  */
+        options?: string;
+        /**
+         * Friendly message to display to end-users if the regex fails, e.g.
+         * "You must use a relative url starting with '/...' "
+         */
+        message: string;
+    };
+    /**
+     * Set this to `true` to put this under the "show more" section of
+     * the options editor. Useful for things that are more advanced
+     * or more rarely used and don't need to be too prominent
+     */
+    advanced?: boolean;
+    /** @hidden */
+    /** @hidden */
+    code?: boolean;
+    /** @hidden */
+    richText?: boolean;
+    /** @hidden */
+    showIf?: ((options: Map<string, any>) => boolean) | string;
+    /** @hidden */
+    copyOnAdd?: boolean;
+    /**
+     * Use optionally with inputs of type `reference`. Restricts the content entry picker to a specific model by name.
+     */
+    model?: string;
+    valueType?: {
+        type?: string;
+    };
+    onChange?: ((options: Map<string, any>) => void | Promise<void>) | string;
+}

package/dist/sdk/types/targets.d.ts

@@ -0,0 +1,3 @@
+type MitosisTargets = import('@builder.io/mitosis').Target;
+export type Target = Extract<MitosisTargets, 'vue3' | 'vue2' | 'reactNative' | 'svelte' | 'qwik' | 'react' | 'solid'>;
+export {};

package/dist/sdk/types/typescript.d.ts

@@ -0,0 +1,5 @@
+export type Nullable<T> = T | null | undefined;
+export type Dictionary<T> = {
+    [key: string]: T;
+};
+export type Overwrite<T, U> = keyof U extends keyof T ? Pick<T, Exclude<keyof T, keyof U>> & U : never;

package/dist/sdk/types/typescript.js

@@ -0,0 +1 @@
+export {};

package/dist/server/functions/get-builder-search-params/index.d.ts

@@ -0,0 +1,6 @@
+type QueryObject = Record<string, string | string[]>;
+export declare const convertSearchParamsToQueryObject: (searchParams: URLSearchParams) => QueryObject;
+export declare const getBuilderSearchParams: (_options: QueryObject | URLSearchParams | undefined) => QueryObject;
+export declare const getBuilderSearchParamsFromWindow: () => QueryObject;
+export declare const normalizeSearchParams: (searchParams: QueryObject | URLSearchParams) => QueryObject;
+export {};

package/dist/server/functions/get-builder-search-params/index.js

@@ -0,0 +1,36 @@
+import { isBrowser } from '../is-browser.js';
+const BUILDER_SEARCHPARAMS_PREFIX = 'builder.';
+const BUILDER_OPTIONS_PREFIX = 'options.';
+export const convertSearchParamsToQueryObject = (searchParams) => {
+    const options = {};
+    searchParams.forEach((value, key) => {
+        options[key] = value;
+    });
+    return options;
+};
+export const getBuilderSearchParams = (_options) => {
+    if (!_options) {
+        return {};
+    }
+    const options = normalizeSearchParams(_options);
+    const newOptions = {};
+    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) => searchParams instanceof URLSearchParams
+    ? convertSearchParamsToQueryObject(searchParams)
+    : searchParams;

package/dist/server/functions/get-content/ab-testing.d.ts

@@ -0,0 +1,5 @@
+import type { BuilderContent } from '../../types/builder-content.js';
+import type { CanTrack } from '../../types/can-track.js';
+export declare const handleABTesting: ({ item, canTrack, }: {
+    item: BuilderContent;
+} & CanTrack) => Promise<void>;

package/dist/server/functions/get-content/ab-testing.js

@@ -0,0 +1,78 @@
+import { getContentVariationCookie, setContentVariationCookie, } from '../../helpers/ab-tests.js';
+import { checkIsDefined } from '../../helpers/nullable.js';
+const checkIsBuilderContentWithVariations = (item) => 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, }) => {
+    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, }) => {
+    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' : ''),
+        };
+    }
+};
+const getContentVariation = async ({ item, canTrack, }) => {
+    // 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, }) => {
+    if (!checkIsBuilderContentWithVariations(item)) {
+        return;
+    }
+    const variationValue = await getContentVariation({ item, canTrack });
+    Object.assign(item, variationValue);
+};

package/dist/server/functions/get-content/generate-content-url.d.ts

@@ -0,0 +1,2 @@
+import type { GetContentOptions } from './types.js';
+export declare const generateContentUrl: (options: GetContentOptions) => URL;

package/dist/server/functions/get-content/generate-content-url.js

@@ -0,0 +1,31 @@
+import { flatten } from '../../helpers/flatten.js';
+import { getBuilderSearchParamsFromWindow, normalizeSearchParams, } from '../get-builder-search-params/index.js';
+import { DEFAULT_API_VERSION } from '../../types/api-version';
+export const generateContentUrl = (options) => {
+    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[key]));
+        }
+    }
+    return url;
+};

package/dist/server/functions/get-content/generate-content-url.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/functions/get-content/generate-content-url.test.js

@@ -0,0 +1,82 @@
+import { generateContentUrl } from './generate-content-url';
+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',
+            });
+        }).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',
+            });
+        }).toThrow(`Invalid apiVersion: expected 'v2' or 'v3', received 'INVALID_API_VERSION'`);
+    });
+});