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

package/types/components/PlaceholderCommon.d.ts

@@ -0,0 +1,105 @@
+/// <reference types="@types/react" />
+import React, { ComponentType } from 'react';
+import PropTypes from 'prop-types';
+import { ComponentFactory } from './sharedTypes';
+import { ComponentRendering, RouteData, Field, Item, HtmlElementRendering } from '@sitecore-jss/sitecore-jss/layout';
+type ErrorComponentProps = {
+    [prop: string]: unknown;
+};
+/** Provided for the component which represents rendering data */
+export type ComponentProps = {
+    [key: string]: unknown;
+    rendering: ComponentRendering;
+};
+export interface PlaceholderProps {
+    [key: string]: unknown;
+    /** Name of the placeholder to render. */
+    name: string;
+    /** Rendering data to be used when rendering the placeholder. */
+    rendering: ComponentRendering | RouteData;
+    /**
+     * A factory function that will receive a componentName and return an instance of a React component.
+     * When rendered within a <SitecoreContext> component, defaults to the context componentFactory.
+     */
+    componentFactory?: ComponentFactory;
+    /**
+     * An object of field names/values that are aggregated and propagated through the component tree created by a placeholder.
+     * Any component or placeholder rendered by a placeholder will have access to this data via `props.fields`.
+     */
+    fields?: {
+        [name: string]: Field | Item[];
+    };
+    /**
+     * An object of rendering parameter names/values that are aggregated and propagated through the component tree created by a placeholder.
+     * Any component or placeholder rendered by a placeholder will have access to this data via `props.params`.
+     */
+    params?: {
+        [name: string]: string;
+    };
+    /**
+     * Modify final props of component (before render) provided by rendering data.
+     * Can be used in case when you need to insert additional data into the component.
+     * @param {ComponentProps} componentProps component props to be modified
+     * @returns {ComponentProps} modified or initial props
+     */
+    modifyComponentProps?: (componentProps: ComponentProps) => ComponentProps;
+    /**
+     * A component that is rendered in place of any components that are in this placeholder,
+     * but do not have a definition in the componentFactory (i.e. don't have a React implementation)
+     */
+    missingComponentComponent?: React.ComponentClass<unknown> | React.FC<unknown>;
+    /**
+     * A component that is rendered in place of any components that are hidden
+     */
+    hiddenRenderingComponent?: React.ComponentClass<unknown> | React.FC<unknown>;
+    /**
+     * A component that is rendered in place of the placeholder when an error occurs rendering
+     * the placeholder
+     */
+    errorComponent?: React.ComponentClass<ErrorComponentProps> | React.FC<ErrorComponentProps>;
+}
+export declare class PlaceholderCommon<T extends PlaceholderProps> extends React.Component<T> {
+    static propTypes: {
+        rendering: PropTypes.Validator<NonNullable<NonNullable<ComponentRendering | RouteData<Record<string, Field<import("@sitecore-jss/sitecore-jss/types/layout/models").GenericFieldValue> | Item | Item[]>>>>>;
+        fields: PropTypes.Requireable<{
+            [x: string]: NonNullable<NonNullable<Field<import("@sitecore-jss/sitecore-jss/types/layout/models").GenericFieldValue> | Item[]>>;
+        }>;
+        params: PropTypes.Requireable<{
+            [x: string]: string;
+        }>;
+        missingComponentComponent: PropTypes.Requireable<NonNullable<React.ComponentClass<unknown, any> | React.FC<unknown>>>;
+        hiddenRenderingComponent: PropTypes.Requireable<NonNullable<React.ComponentClass<unknown, any> | React.FC<unknown>>>;
+        errorComponent: PropTypes.Requireable<NonNullable<React.ComponentClass<unknown, any> | React.FC<unknown>>>;
+        modifyComponentProps: PropTypes.Requireable<(...args: any[]) => any>;
+    };
+    nodeRefs: Element[];
+    state: Readonly<{
+        error?: Error;
+    }>;
+    constructor(props: T);
+    static getPlaceholderDataFromRenderingData(rendering: ComponentRendering | RouteData, name: string): (ComponentRendering | HtmlElementRendering)[];
+    componentDidMount(): void;
+    componentDidUpdate(): void;
+    componentDidCatch(error: Error): void;
+    getSXAParams(rendering: ComponentRendering): {
+        styles?: undefined;
+    } | {
+        styles: string;
+    };
+    getComponentsForRenderingData(placeholderData: (ComponentRendering | HtmlElementRendering)[]): React.ReactElement<{
+        [attr: string]: unknown;
+    }, string | React.JSXElementConstructor<any>>[];
+    getComponentForRendering(renderingDefinition: ComponentRendering): ComponentType | null;
+    addRef(nodeRef: Element): void;
+    createRawElement(elem: HtmlElementRendering, baseProps: {
+        key?: string;
+    }): React.ReactElement<{
+        [attr: string]: unknown;
+        key?: string;
+        dangerouslySetInnerHTML?: {
+            __html: string | null;
+        };
+    }, string | React.JSXElementConstructor<any>>;
+    updateKeyAttributes(): void;
+}
+export {};

package/types/components/RichText.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import PropTypes from 'prop-types';
+export interface RichTextField {
+    value?: string;
+    editable?: string;
+}
+export interface RichTextProps {
+    [htmlAttributes: string]: unknown;
+    /** The rich text field data. */
+    field?: RichTextField;
+    /**
+     * The HTML element that will wrap the contents of the field.
+     * @default <div />
+     */
+    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;
+}
+export declare const RichText: React.FC<RichTextProps>;
+export declare const RichTextPropTypes: {
+    field: PropTypes.Requireable<PropTypes.InferProps<{
+        value: PropTypes.Requireable<string>;
+        editable: PropTypes.Requireable<string>;
+    }>>;
+    tag: PropTypes.Requireable<string>;
+    editable: PropTypes.Requireable<boolean>;
+};

package/types/components/SitecoreContext.d.ts

@@ -0,0 +1,43 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import PropTypes from 'prop-types';
+import { ComponentFactory } from './sharedTypes';
+import { LayoutServiceContext, LayoutServiceData, RouteData } from '../index';
+export interface SitecoreContextProps {
+    componentFactory: ComponentFactory;
+    layoutData?: LayoutServiceData;
+    children: React.ReactNode;
+}
+export interface SitecoreContextState {
+    setContext: (value: SitecoreContextValue | LayoutServiceData) => void;
+    context: SitecoreContextValue;
+}
+export declare const SitecoreContextReactContext: React.Context<SitecoreContextState>;
+export declare const ComponentFactoryReactContext: React.Context<ComponentFactory>;
+export type SitecoreContextValue = LayoutServiceContext & {
+    itemId?: string;
+    route?: RouteData;
+};
+export declare class SitecoreContext extends React.Component<SitecoreContextProps, SitecoreContextState> {
+    static propTypes: {
+        children: PropTypes.Validator<any>;
+        componentFactory: PropTypes.Requireable<(...args: any[]) => any>;
+        layoutData: PropTypes.Requireable<PropTypes.InferProps<{
+            sitecore: PropTypes.Requireable<PropTypes.InferProps<{
+                context: PropTypes.Requireable<any>;
+                route: PropTypes.Requireable<any>;
+            }>>;
+        }>>;
+    };
+    static displayName: string;
+    constructor(props: SitecoreContextProps);
+    constructContext(layoutData?: LayoutServiceData): SitecoreContextValue;
+    componentDidUpdate(prevProps: SitecoreContextProps): void;
+    /**
+     * Update context state. Value can be @type {LayoutServiceData} which will be automatically transformed
+     * or you can provide exact @type {SitecoreContextValue}
+     * @param {SitecoreContextValue | LayoutServiceData} value New context value
+     */
+    setContext: (value: SitecoreContextValue | LayoutServiceData) => void;
+    render(): React.JSX.Element;
+}

package/types/components/Text.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="@types/react" />
+import { FunctionComponent } from 'react';
+export interface TextField {
+    value?: string | number;
+    editable?: string;
+}
+export interface TextProps {
+    [htmlAttributes: string]: unknown;
+    /** The text field data. */
+    field?: TextField;
+    /**
+     * 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;
+    /**
+     * If false, HTML-encoding of the field value is disabled and the value is rendered as-is.
+     */
+    encode?: boolean;
+}
+export declare const Text: FunctionComponent<TextProps>;

package/types/components/sharedTypes.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="@types/react" />
+import { ComponentType } from 'react';
+/**
+ * @param {string} componentName component to be imported from the component factory
+ * @param {string?} exportName component to be imported in case you export multiple components from the same file
+ */
+export type ComponentFactory = (componentName: string, exportName?: string) => ComponentType | null;

package/types/enhancers/withComponentFactory.d.ts

@@ -0,0 +1,13 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import { ComponentFactory } from '../components/sharedTypes';
+export interface ComponentFactoryProps {
+    componentFactory?: ComponentFactory;
+}
+/**
+ * @param {React.ComponentClass<T> | React.FC<T>} Component
+ */
+export declare function withComponentFactory<T extends ComponentFactoryProps>(Component: React.ComponentClass<T> | React.FC<T>): {
+    (props: T): JSX.Element;
+    displayName: string;
+};

package/types/enhancers/withDatasourceCheck.d.ts

@@ -0,0 +1,22 @@
+/// <reference types="@types/react" />
+import React from 'react';
+import { ComponentRendering } from '@sitecore-jss/sitecore-jss/layout';
+export declare const DefaultEditingError: () => JSX.Element;
+export interface WithDatasourceCheckProps {
+    rendering: ComponentRendering;
+}
+export interface WithDatasourceCheckOptions {
+    /**
+     * A component that is rendered when a datasource is missing during editing.
+     * If unspecified, a default component with message is displayed.
+     */
+    editingErrorComponent?: React.ComponentClass<unknown> | React.FC<unknown>;
+}
+/**
+ * Checks whether a Sitecore datasource is present and renders appropriately depending on page mode (normal vs editing).
+ * @param {WithDatasourceCheckOptions} [options]
+ * @returns
+ *  The wrapped component, if a datasource is present.
+ *  A null component (in normal mode) or an error component (in editing mode), if a datasource is not present.
+ */
+export declare function withDatasourceCheck(options?: WithDatasourceCheckOptions): <ComponentProps extends WithDatasourceCheckProps>(Component: React.ComponentType<ComponentProps>) => (props: ComponentProps) => React.JSX.Element;

package/types/enhancers/withEditorChromes.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="@types/react" />
+import React from 'react';
+export declare const withEditorChromes: (WrappedComponent: React.ComponentClass<unknown> | React.FC<unknown>) => React.ComponentClass<{}, any>;

package/types/enhancers/withPlaceholder.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import { ComponentRendering, RouteData } from '@sitecore-jss/sitecore-jss/layout';
+import { PlaceholderProps } from '../components/PlaceholderCommon';
+export interface WithPlaceholderOptions {
+    /**
+     * Function to map incoming placeholder props into rendering data to use for the placeholder data.
+     * Normally in a JSS component, props.rendering is passed the component data, and that is the default.
+     * However, if your component data is in a different prop, like say 'route' in a sample app,
+     * this lets you map that.
+     */
+    resolvePlaceholderDataFromProps?: (props: unknown) => ComponentRendering | RouteData;
+    /**
+     * Function to alter the placeholder props from within the HOC. Enables the props to be
+     * transformed before being used by the placeholder/HOC, for example to customize the
+     * error or missing component display
+     */
+    propsTransformer?: (props: PlaceholderProps) => PlaceholderProps;
+}
+export interface PlaceholderToPropMapping {
+    /**
+     * The name of the placeholder this component will expose
+     */
+    placeholder: string;
+    /**
+     * The name of the prop on your wrapped component that you would like the placeholder data injected on
+     */
+    prop: string;
+}
+export type WithPlaceholderSpec = (string | PlaceholderToPropMapping) | (string | PlaceholderToPropMapping)[];
+/**
+ * @param {WithPlaceholderSpec} placeholders
+ * @param {WithPlaceholderOptions} [options]
+ */
+export declare function withPlaceholder(placeholders: WithPlaceholderSpec, options?: WithPlaceholderOptions): (WrappedComponent: React.ComponentClass<PlaceholderProps> | React.FunctionComponent<PlaceholderProps>) => {
+    (props: PlaceholderProps): JSX.Element;
+    displayName: string;
+};

package/types/enhancers/withSitecoreContext.d.ts

@@ -0,0 +1,47 @@
+/// <reference types="@types/react" />
+import React, { ReactNode } from 'react';
+import { SitecoreContextValue } from '../components/SitecoreContext';
+export interface WithSitecoreContextOptions {
+    updatable?: boolean;
+}
+export interface WithSitecoreContextProps {
+    sitecoreContext: SitecoreContextValue;
+    updateSitecoreContext?: ((value: SitecoreContextValue) => void) | false;
+}
+export interface ComponentConsumerProps extends WithSitecoreContextProps {
+    children?: ReactNode;
+}
+export type WithSitecoreContextHocProps<ComponentProps> = Pick<ComponentProps, Exclude<keyof ComponentProps, keyof WithSitecoreContextProps>>;
+/**
+ * @param {WithSitecoreContextOptions} [options]
+ */
+export declare function withSitecoreContext(options?: WithSitecoreContextOptions): <ComponentProps extends ComponentConsumerProps>(Component: React.ComponentType<ComponentProps>) => (props: WithSitecoreContextHocProps<ComponentProps>) => React.JSX.Element;
+/**
+ * This hook grants acсess to the current Sitecore page context
+ * by default JSS includes the following properties in this context:
+ * - pageEditing - Provided by Layout Service, a boolean indicating whether the route is being accessed via the Experience Editor.
+ * - pageState - Like pageEditing, but a string: normal, preview or edit.
+ * - site - Provided by Layout Service, an object containing the name of the current Sitecore site context.
+ *
+ * @see https://jss.sitecore.com/docs/techniques/extending-layout-service/layoutservice-extending-context
+ *
+ * @param {WithSitecoreContextOptions} [options] hook options
+ *
+ * @example
+ * const EditMode = () => {
+ *    const { sitecoreContext } = useSitecoreContext();
+ *    return <span>Edit Mode is {sitecoreContext.pageEditing ? 'active' : 'inactive'}</span>
+ * }
+ *
+ * @example
+ * const EditMode = () => {
+ *    const { sitecoreContext, updateSitecoreContext } = useSitecoreContext({ updatable: true });
+ *    const onClick = () => updateSitecoreContext({ pageEditing: true });
+ *    return <span onClick={onClick}>Edit Mode is {sitecoreContext.pageEditing ? 'active' : 'inactive'}</span>
+ * }
+ * @returns {Object} { sitecoreContext, updateSitecoreContext }
+ */
+export declare function useSitecoreContext(options?: WithSitecoreContextOptions): {
+    sitecoreContext: SitecoreContextValue;
+    updateSitecoreContext: (value: import("@sitecore-jss/sitecore-jss/layout").LayoutServiceData | SitecoreContextValue) => void;
+};

package/types/index.d.ts

@@ -0,0 +1,24 @@
+export { constants, NativeDataFetcher, NativeDataFetcherResponse, NativeDataFetcherConfig, enableDebug, } from '@sitecore-jss/sitecore-jss';
+export { isEditorActive, resetEditorChromes, DefaultEditFrameButton, DefaultEditFrameButtons, EditFrameDataSource, FieldEditButton, WebEditButton, EditButtonTypes, } from '@sitecore-jss/sitecore-jss/utils';
+export { getContentStylesheetLink, getComponentLibraryStylesheetLinks, LayoutService, LayoutServiceData, LayoutServicePageState, LayoutServiceContext, LayoutServiceContextData, GraphQLLayoutService, RouteData, Field, Item, HtmlElementRendering, getChildPlaceholder, getFieldValue, ComponentRendering, ComponentFields, ComponentParams, } from '@sitecore-jss/sitecore-jss/layout';
+export { DictionaryPhrases, DictionaryService, GraphQLDictionaryService, } from '@sitecore-jss/sitecore-jss/i18n';
+export { mediaApi } from '@sitecore-jss/sitecore-jss/media';
+export { ComponentFactory } from './components/sharedTypes';
+export { Placeholder, PlaceholderComponentProps } from './components/Placeholder';
+export { Image, ImageProps, ImageField, getEEMarkup, ImageFieldValue, ImageSizeParameters, } from './components/Image';
+export { RichText, RichTextProps, RichTextPropTypes, RichTextField } from './components/RichText';
+export { Text, TextField } from './components/Text';
+export { DateField, DateFieldProps } from './components/Date';
+export { FEaaSComponent, FEaaSComponentProps, FEaaSComponentParams, fetchFEaaSComponentServerProps, } from './components/FEaaSComponent';
+export { FEaaSWrapper } from './components/FEaaSWrapper';
+export { BYOCComponent, BYOCComponentParams, BYOCComponentProps, fetchBYOCComponentServerProps, } from './components/BYOCComponent';
+export { BYOCWrapper } from './components/BYOCWrapper';
+export { Link, LinkField, LinkFieldValue, LinkProps, LinkPropTypes } from './components/Link';
+export { File, FileField } from './components/File';
+export { SitecoreContext, SitecoreContextState, SitecoreContextValue, SitecoreContextReactContext, } from './components/SitecoreContext';
+export { withSitecoreContext, useSitecoreContext, ComponentConsumerProps, WithSitecoreContextOptions, WithSitecoreContextProps, WithSitecoreContextHocProps, } from './enhancers/withSitecoreContext';
+export { withEditorChromes } from './enhancers/withEditorChromes';
+export { withPlaceholder } from './enhancers/withPlaceholder';
+export { withDatasourceCheck } from './enhancers/withDatasourceCheck';
+export { EditFrameProps, EditFrame } from './components/EditFrame';
+export { ComponentBuilder, ComponentBuilderConfig } from './ComponentBuilder';

package/types/utils.d.ts

@@ -0,0 +1,42 @@
+import { ComponentFields } from '@sitecore-jss/sitecore-jss/layout';
+export declare const convertKebabCasetoCamelCase: (str: string) => string;
+/**
+ * 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 declare const convertStyleAttribute: (style?: string) => {};
+export declare const convertAttributesToReactProps: (attributes: {
+    [key: string]: unknown;
+    style?: string;
+    class?: string;
+}) => [] | {
+    [attr: string]: unknown;
+};
+/**
+ * "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 declare const addClassName: (otherAttrs: {
+    [key: string]: unknown;
+}) => void;
+/**
+ * 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 declare const getAttributesString: (attributes: {
+    [key: string]: unknown;
+}) => string;
+/**
+ * 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 declare const getDataFromFields: (fields: ComponentFields) => {
+    [key: string]: unknown;
+};