@sitecore-jss/sitecore-jss-react 0.1.0-beta.2

package/dist/esm/utils.js

@@ -0,0 +1,109 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { getFieldValue } from '@sitecore-jss/sitecore-jss/layout';
+import { parse as styleParse } from 'style-attr';
+// https://stackoverflow.com/a/10426674/9324
+export const convertKebabCasetoCamelCase = (str) => str.replace(/^.|-./g, (letter, index) => index === 0 ? letter.toLowerCase() : letter.substr(1).toUpperCase());
+/**
+ * https://facebook.github.io/react/docs/dom-elements.html
+ * We are only concerned with style at the moment, which needs to be converted from string to object to satisfy React.
+ * We don't need to convert any other attributes (that we know of), because the placeholder renders them "as-is" by using the special "is" React prop.
+ * For whatever reason though, the "style" prop is still validated as needing to be an object when using the "is" prop, which is why we need to convert from string to object.
+ * @param {string} [style] style
+ * @returns {Array} converted attributes
+ */
+export const convertStyleAttribute = (style = '') => {
+    // styleParse converts a style attribute string into an object format
+    const parsedStyle = styleParse(style, { preserveNumbers: true });
+    return Object.keys(parsedStyle).reduce((initialResult, styleKey) => {
+        const result = initialResult;
+        const convertedKey = convertKebabCasetoCamelCase(styleKey);
+        result[convertedKey] = parsedStyle[styleKey];
+        return result;
+    }, {});
+};
+export const convertAttributesToReactProps = (attributes) => {
+    if (!attributes) {
+        return [];
+    }
+    return Object.keys(attributes).reduce((initialResult, attrName) => {
+        const result = initialResult;
+        switch (attrName) {
+            case 'class': {
+                result.className = attributes.class;
+                break;
+            }
+            case 'style': {
+                result.style = convertStyleAttribute(attributes.style);
+                break;
+            }
+            default: {
+                result[attrName] = attributes[attrName];
+                break;
+            }
+        }
+        return result;
+    }, {});
+};
+/**
+ * "class" property will be transformed into or appended to "className" instead.
+ * @param {string} otherAttrs all other props included on the image component
+ * @returns {void}
+ */
+export const addClassName = (otherAttrs) => {
+    if (otherAttrs.class) {
+        // if any classes are defined properly already
+        if (otherAttrs.className) {
+            let className = otherAttrs.className;
+            className += ` ${otherAttrs.class}`;
+            otherAttrs.className = className;
+        }
+        else {
+            otherAttrs.className = otherAttrs.class;
+        }
+        delete otherAttrs.class;
+    }
+};
+/**
+ * Converts the given tag attributes object to a string
+ * @param {Object.<string, unknown>} attributes the attributes object
+ * @returns {string} string representation of the attributes
+ */
+export const getAttributesString = (attributes) => {
+    const { className } = attributes, restAttributes = __rest(attributes, ["className"]);
+    const attributesEntries = Object.entries(restAttributes).map(([key, value]) => {
+        if (typeof value === 'object') {
+            const valueString = JSON.stringify(value)
+                .replace(/"|{|}/g, '')
+                .replace(/,/g, ';');
+            return `${key}="${valueString}"`;
+        }
+        return `${key}="${value}"`;
+    });
+    if (className) {
+        attributesEntries.push(`class="${className}"`);
+    }
+    return attributesEntries.join(' ');
+};
+/**
+ * Used in FEAAS and BYOC implementations to convert datasource item field values into component props
+ * @param {ComponentFields} fields field collection from Sitecore
+ * @returns JSON object that can be used as props
+ */
+export const getDataFromFields = (fields) => {
+    let data = {};
+    data = Object.entries(fields).reduce((acc, [key]) => {
+        acc[key] = getFieldValue(fields, key);
+        return acc;
+    }, data);
+    return data;
+};

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@sitecore-jss/sitecore-jss-react",
+  "version": "0.1.0-beta.2",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run clean && tsc -p tsconfig.json && tsc -p tsconfig-esm.json",
+    "clean": "del-cli dist types",
+    "lint": "eslint \"./src/**/*.tsx\" \"./src/**/*.ts\"",
+    "test": "mocha --require ts-node/register/transpile-only --require ./src/tests/shim.ts ./src/tests/jsdom-setup.ts ./src/tests/enzyme-setup.ts \"./src/**/*.test.ts\" \"./src/**/*.test.tsx\" --exit",
+    "prepublishOnly": "npm run build",
+    "coverage": "nyc npm test",
+    "generate-docs": "npx typedoc --plugin typedoc-plugin-markdown --readme none --out ../../ref-docs/sitecore-jss-react src/index.ts --githubPages false"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "author": {
+    "name": "Sitecore Corporation",
+    "url": "https://jss.sitecore.com"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://jss.sitecore.com",
+  "bugs": {
+    "url": "https://github.com/sitecore/jss/issues"
+  },
+  "devDependencies": {
+    "@sitecore-feaas/clientside": "^0.5.6",
+    "@types/chai": "^4.3.4",
+    "@types/chai-string": "^1.4.2",
+    "@types/enzyme": "^3.10.12",
+    "@types/mocha": "^10.0.1",
+    "@types/node": "18.11.10",
+    "@types/prop-types": "^15.7.5",
+    "@types/react": "^18.2.22",
+    "@types/react-dom": "^18.0.10",
+    "@types/sinon": "^10.0.13",
+    "@types/sinon-chai": "^3.2.9",
+    "@wojtekmaj/enzyme-adapter-react-17": "^0.8.0",
+    "chai": "^4.3.7",
+    "chai-string": "^1.5.0",
+    "cheerio": "1.0.0-rc.12",
+    "del-cli": "^5.0.0",
+    "enzyme": "^3.11.0",
+    "eslint": "^8.28.0",
+    "eslint-plugin-react": "^7.31.11",
+    "jsdom": "^20.0.3",
+    "mocha": "^10.2.0",
+    "nyc": "^15.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "sinon": "^15.0.0",
+    "sinon-chai": "^3.7.0",
+    "ts-node": "^10.9.1",
+    "typescript": "~4.9.3"
+  },
+  "peerDependencies": {
+    "@sitecore-feaas/clientside": "^0.5.6",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "dependencies": {
+    "@sitecore-jss/sitecore-jss": "^0.1.0-beta.2",
+    "fast-deep-equal": "^3.1.3",
+    "prop-types": "^15.8.1",
+    "style-attr": "^1.3.0"
+  },
+  "description": "",
+  "types": "types/index.d.ts",
+  "gitHead": "db3098b97fd0fe5616636da848ab9aefb664a3f3",
+  "files": [
+    "dist",
+    "types"
+  ]
+}

package/types/ComponentBuilder.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="@types/react" />
+import { ComponentType } from 'react';
+import { ComponentFactory } from './components/sharedTypes';
+/**
+ * Configuration for ComponentBuilder
+ */
+export type ComponentBuilderConfig<ComponentType> = {
+    /**
+     * List of components to be stored
+     */
+    components: Map<string, ComponentType>;
+};
+/**
+ * React implementation of component builder class for building components based on the configuration.
+ */
+export declare class ComponentBuilder {
+    protected config: ComponentBuilderConfig<ComponentType>;
+    /**
+     * List of components to be stored
+     */
+    protected components: Map<string, ComponentType>;
+    constructor(config: ComponentBuilderConfig<ComponentType>);
+    /**
+     * Creates a new instance of component factory
+     * @returns {ComponentFactory} Component factory implementation
+     */
+    getComponentFactory(): ComponentFactory;
+}

package/types/components/BYOCComponent.d.ts

@@ -0,0 +1,87 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import { ComponentFields } from '@sitecore-jss/sitecore-jss/layout';
+import { MissingComponentProps } from './MissingComponent';
+import * as FEAAS from '@sitecore-feaas/clientside/react';
+export declare const BYOC_COMPONENT_RENDERING_NAME = "BYOCComponent";
+/**
+ * FEaaS props for server rendering.
+ */
+type BYOCServerProps = {
+    /**
+     * Fetched data from server component props for server rendering, based on rendering params.
+     */
+    fetchedData?: FEAAS.DataScopes;
+};
+/**
+ * Data from rendering params on Sitecore's BYOC rendering
+ */
+export type BYOCComponentParams = {
+    /**
+     * Name of the component to render
+     */
+    ComponentName?: string;
+    /**
+     * JSON props to pass into rendered component
+     */
+    ComponentProps?: string;
+    /**
+     * A JSON object with data sources to be fetched and passed to the component
+     */
+    ComponentDataOverride?: string;
+    /**
+     * A string with classes that can be used to apply themes, via SXA functionality
+     */
+    styles?: string;
+    RenderingIdentifier?: string;
+};
+/**
+ * Props for BYOCComponent. Includes components list to load external components from.
+ */
+export type BYOCComponentClientProps = {
+    /**
+     * rendering params
+     */
+    params?: BYOCComponentParams;
+    /**
+     * fields from datasource items to be passed as rendered child component props
+     */
+    fields?: ComponentFields;
+    /**
+     * Error component override. To be shown when Renderer or underlying component throws
+     */
+    errorComponent?: React.ComponentClass<ErrorComponentProps> | React.FC<ErrorComponentProps>;
+    /**
+     * Override to indicate missing component situations. Would be shown when BYOC component is not registered
+     * or ComponentName is missing
+     */
+    missingComponentComponent?: React.ComponentClass<MissingComponentProps> | React.FC<MissingComponentProps>;
+};
+export type BYOCComponentProps = BYOCComponentClientProps & BYOCServerProps;
+type ErrorComponentProps = {
+    [prop: string]: unknown;
+    error?: Error;
+};
+/**
+ * BYOCComponent facilitate the rendering of external components. It manages potential errors,
+ * missing components, and customization of error messages or alternative rendering components.
+ * @param {ByocComponentProps} props component props
+ * @returns dynamicly rendered component or Missing Component error frame
+ */
+export declare class BYOCComponent extends React.Component<BYOCComponentProps> {
+    state: Readonly<{
+        error?: Error;
+    }>;
+    constructor(props: BYOCComponentProps);
+    static getDerivedStateFromError(error: Error): {
+        error: Error;
+    };
+    componentDidCatch(error: Error): void;
+    render(): React.JSX.Element;
+}
+/**
+ * Fetches server component props required for server rendering, based on rendering params.
+ * @param {BYOCComponentParams} params component params
+ */
+export declare function fetchBYOCComponentServerProps(params: BYOCComponentParams): Promise<BYOCComponentProps>;
+export {};

package/types/components/BYOCWrapper.d.ts

@@ -0,0 +1,3 @@
+import { BYOCComponentProps } from './BYOCComponent';
+export declare const BYOC_WRAPPER_RENDERING_NAME = "BYOCWrapper";
+export declare const BYOCWrapper: (props: BYOCComponentProps) => JSX.Element;

package/types/components/Date.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="@types/react" />
+import React from 'react';
+export interface DateFieldProps {
+    /** The date field data. */
+    [htmlAttributes: string]: unknown;
+    field: {
+        value?: string;
+        editable?: string;
+    };
+    /**
+     * The HTML element that will wrap the contents of the field.
+     */
+    tag?: string;
+    /**
+     * Can be used to explicitly disable inline editing.
+     * If true and `field.editable` has a value, then `field.editable` will be processed and rendered as component output. If false, `field.editable` value will be ignored and not rendered.
+     * @default true
+     */
+    editable?: boolean;
+    render?: (date: Date | null) => React.ReactNode;
+}
+export declare const DateField: React.FC<DateFieldProps>;

package/types/components/EditFrame.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="@types/react" />
+import React, { PropsWithChildren } from 'react';
+import { EditFrameDataSource, EditButtonTypes } from '@sitecore-jss/sitecore-jss/utils';
+export interface EditFrameProps {
+    dataSource?: EditFrameDataSource;
+    buttons?: EditButtonTypes[];
+    title?: string;
+    tooltip?: string;
+    cssClass?: string;
+    parameters?: Record<string, string | number | boolean | undefined | null>;
+}
+export declare const EditFrame: React.FC<PropsWithChildren<EditFrameProps>>;

package/types/components/FEaaSComponent.d.ts

@@ -0,0 +1,71 @@
+import * as FEAAS from '@sitecore-feaas/clientside/react';
+import { ComponentFields, LayoutServicePageState } from '@sitecore-jss/sitecore-jss/layout';
+export declare const FEAAS_COMPONENT_RENDERING_NAME = "FEaaSComponent";
+/**
+ * Params from a Sitecore FEaaS rendering
+ */
+export type FEaaSComponentParams = {
+    LibraryId?: string;
+    ComponentId?: string;
+    ComponentVersion?: string;
+    ComponentRevision?: RevisionType;
+    ComponentHostName?: string;
+    ComponentInstanceId?: string;
+    ComponentDataOverride?: string;
+    ComponentHTMLOverride?: string;
+    styles?: string;
+    RenderingIdentifier?: string;
+};
+type RevisionType = number | 'staged' | 'published' | 'saved';
+/**
+ * FEaaS props for server rendering.
+ */
+type FEaaSComponentServerProps = {
+    /**
+     * HTML template for presentation rendered inside the component
+     */
+    template?: string;
+    /**
+     * Default revision to be fetched. Should be 'staged' for editing/preview. Can be overriden by params.ComponentRevision
+     */
+    revisionFallback?: RevisionType;
+    /**
+     * Fetched data from server component props for server rendering, based on rendering params.
+     */
+    fetchedData?: FEAAS.DataScopes;
+};
+/**
+ * FEaaS props for client side component. Should be used as fallback when server props are not provided.
+ * Would also be passed on server to avoid hydration issues
+ */
+type FEaaSComponentClientProps = {
+    /**
+     * parameters from Sitecore's FEAAS component
+     */
+    params?: FEaaSComponentParams;
+    /**
+     * field data from component's datasource
+     */
+    fields?: ComponentFields;
+};
+export type FEaaSComponentProps = FEaaSComponentServerProps & FEaaSComponentClientProps;
+/**
+ * @param {FEaaSComponentProps} props component props
+ */
+export declare const FEaaSComponent: (props: FEaaSComponentProps) => JSX.Element;
+/**
+ * Fetches server component props required for server rendering, based on rendering params.
+ * Component endpoint will either be retrieved from params or from endpointOverride
+ * @param {FEaaSComponentParams} params component params
+ * @param {LayoutServicePageState} [pageState] page state to determine which component variant to use
+ * @param {string} [endpointOverride] optional override for component endpoint
+ */
+export declare function fetchFEaaSComponentServerProps(params: FEaaSComponentParams, pageState?: LayoutServicePageState, endpointOverride?: string): Promise<FEaaSComponentProps>;
+/**
+ * Build component endpoint URL from component's params
+ * @param {FEaaSComponentParams} params rendering parameters for FEAAS component
+ * @param {RevisionType} revisionFallback fallback revision to fetch if revision is absent in params
+ * @returns component endpoint URL
+ */
+export declare const composeComponentEndpoint: (params: FEaaSComponentParams, revisionFallback: RevisionType) => string;
+export {};

package/types/components/FEaaSWrapper.d.ts

@@ -0,0 +1,3 @@
+import { FEaaSComponentProps } from './FEaaSComponent';
+export declare const FEAAS_WRAPPER_RENDERING_NAME = "FEaaSWrapper";
+export declare const FEaaSWrapper: (props: FEaaSComponentProps) => JSX.Element;

package/types/components/File.d.ts

@@ -0,0 +1,19 @@
+/// <reference types="@types/react" />
+import React from 'react';
+export interface FileFieldValue {
+    [propName: string]: unknown;
+    src?: string;
+    title?: string;
+    displayName?: string;
+}
+export interface FileField {
+    value: FileFieldValue;
+}
+export interface FileProps {
+    [attributeName: string]: unknown;
+    /** The file field data. */
+    field: FileFieldValue | FileField;
+    /** HTML attributes that will be appended to the rendered <a /> tag. */
+    children?: React.ReactNode;
+}
+export declare const File: React.FC<FileProps>;

package/types/components/HiddenRendering.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="@types/react" />
+import React from 'react';
+export declare const HiddenRendering: () => React.JSX.Element;
+export declare const HIDDEN_RENDERING_NAME = "Hidden Rendering";

package/types/components/Image.d.ts

@@ -0,0 +1,62 @@
+/// <reference types="@types/react" />
+import React from 'react';
+export interface ImageFieldValue {
+    [attributeName: string]: unknown;
+    src?: string;
+}
+export interface ImageField {
+    value?: ImageFieldValue;
+    editable?: string;
+}
+export interface ImageSizeParameters {
+    [attr: string]: string | number | undefined;
+    /** Fixed width of the image */
+    w?: number;
+    /** Fixed height of the image */
+    h?: number;
+    /** Max width of the image */
+    mw?: number;
+    /** Max height of the image */
+    mh?: number;
+    /** Ignore aspect ratio */
+    iar?: 1 | 0;
+    /** Allow stretch */
+    as?: 1 | 0;
+    /** Image scale. Defaults to 1.0 */
+    sc?: number;
+}
+export interface ImageProps {
+    [attributeName: string]: unknown;
+    /** Image field data (consistent with other field types) */
+    field?: ImageField | ImageFieldValue;
+    /**
+     * Can be used to explicitly disable inline editing.
+     * If true and `media.editable` has a value, then `media.editable` will be processed
+     * and rendered as component output. If false, `media.editable` value will be ignored and not rendered.
+     */
+    editable?: boolean;
+    /**
+     * Parameters that will be attached to Sitecore media URLs
+     */
+    imageParams?: {
+        [paramName: string]: string | number;
+    };
+    srcSet?: ImageSizeParameters[];
+    /**
+     * Custom regexp that finds media URL prefix that will be replaced by `/-/jssmedia` or `/~/jssmedia`.
+     * @example
+     * /\/([-~]{1})assets\//i
+     * /-assets/website -> /-/jssmedia/website
+     * /~assets/website -> /~/jssmedia/website
+     */
+    mediaUrlPrefix?: RegExp;
+}
+/**
+ * @param {ImageField} imageField {ImageField} provides the dynamicMedia which is used to render the image
+ * @param {ImageProps.imageParams} imageParams {ImageProp['imageParams']}} provides the image parameters that will be attached to the image URL
+ * @param {RegExp} mediaUrlPrefix {RegExp} the url prefix regex used in the mediaApi
+ * @param {ImageProps} otherProps {ImageProps} all other props included on the image component
+ * @returns Experience Editor Markup
+ */
+export declare const getEEMarkup: (imageField: ImageField, imageParams?: ImageProps['imageParams'], mediaUrlPrefix?: RegExp, otherProps?: ImageProps) => React.JSX.Element;
+export declare const Image: React.FC<ImageProps>;

package/types/components/Link.d.ts

@@ -0,0 +1,47 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import PropTypes from 'prop-types';
+export interface LinkFieldValue {
+    [attributeName: string]: unknown;
+    href?: string;
+    className?: string;
+    class?: string;
+    title?: string;
+    target?: string;
+    text?: string;
+    anchor?: string;
+    querystring?: string;
+    linktype?: string;
+}
+export interface LinkField {
+    value: LinkFieldValue;
+    editableFirstPart?: string;
+    editableLastPart?: string;
+}
+export type LinkProps = React.DetailedHTMLProps<React.AnchorHTMLAttributes<HTMLAnchorElement>, HTMLAnchorElement> & {
+    /** The link field data. */
+    field: LinkField | LinkFieldValue;
+    /**
+     * Can be used to explicitly disable inline editing.
+     * If true and `field.editable` has a value, then `field.editable` will be processed and rendered as component output. If false, `field.editable` value will be ignored and not rendered.
+     * @default true
+     */
+    editable?: boolean;
+    /**
+     * Displays a link text ('description' in Sitecore) even when children exist
+     * NOTE: when in Sitecore Experience Editor, this setting is ignored due to technical limitations, and the description is always rendered.
+     */
+    showLinkTextWithChildrenPresent?: boolean;
+};
+export declare const Link: React.ForwardRefExoticComponent<Omit<LinkProps, "ref"> & React.RefAttributes<HTMLAnchorElement>>;
+export declare const LinkPropTypes: {
+    field: PropTypes.Validator<NonNullable<NonNullable<PropTypes.InferProps<{
+        href: PropTypes.Requireable<any>;
+    }> | PropTypes.InferProps<{
+        value: PropTypes.Requireable<object>;
+        editableFirstPart: PropTypes.Requireable<string>;
+        editableLastPart: PropTypes.Requireable<string>;
+    }>>>>;
+    editable: PropTypes.Requireable<boolean>;
+    showLinkTextWithChildrenPresent: PropTypes.Requireable<boolean>;
+};

package/types/components/MissingComponent.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="@types/react" />
+import React from 'react';
+export interface MissingComponentProps {
+    rendering?: {
+        componentName?: string;
+    };
+    errorOverride?: string;
+}
+export declare const MissingComponent: React.FC<MissingComponentProps>;

package/types/components/Placeholder.d.ts

@@ -0,0 +1,25 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import { PlaceholderProps } from './PlaceholderCommon';
+import { ComponentRendering, HtmlElementRendering } from '@sitecore-jss/sitecore-jss/layout';
+export interface PlaceholderComponentProps extends PlaceholderProps {
+    /**
+     * Render props function that is called when the placeholder contains no content components.
+     * Can be used to wrap the Sitecore EE empty placeholder markup in something that's visually correct
+     */
+    renderEmpty?: (components: React.ReactNode[]) => React.ReactNode;
+    /**
+     * Render props function that enables control over the rendering of the components in the placeholder.
+     * Useful for techniques like wrapping each child in a wrapper component.
+     */
+    render?: (components: React.ReactNode[], data: (ComponentRendering | HtmlElementRendering)[], props: PlaceholderProps) => React.ReactNode;
+    /**
+     * Render props function that is called for each non-system component added to the placeholder.
+     * Mutually exclusive with `render`. System components added during Experience Editor are automatically rendered as-is.
+     */
+    renderEach?: (component: React.ReactNode, index: number) => React.ReactNode;
+}
+export declare const Placeholder: {
+    (props: PlaceholderComponentProps): JSX.Element;
+    displayName: string;
+};