@aws-amplify/ui-react-core 3.0.30 → 3.1.1

package/dist/elements.js

@@ -8,13 +8,91 @@ function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var React__default = /*#__PURE__*/_interopDefault(React);
 
+function isComponent(component) {
+    return typeof component === 'function';
+}
+function isForwardRefExoticComponent(component) {
+    return (typeof component === 'object' &&
+        typeof component.$$typeof ===
+            'symbol' &&
+        ['react.memo', 'react.forward_ref'].includes(component.$$typeof.description));
+}
+
+/**
+ * @internal @unstable
+ */
+const ControlsContext = React__default["default"].createContext(undefined);
+/**
+ * @internal @unstable
+ *
+ * `ControlsProvider` provides the values contained in `ControlsContext`
+ * to consumers. `ControlsContext` lookup is handled directly
+ * by `Control` components returned by `withControls`.
+ *
+ * @example
+ *
+ * Add `ControlsContext` aware `Controls` components to a Connected
+ * Component:
+ *
+ * ```tsx
+ *  const DataList = withControls(function DataList<T>(data: T[]) {
+ *    return <ScrollView>data.map(ListItem)</ScrollView>;
+ *  }, 'DataList');
+ *
+ *  const DataListControl = () => {
+ *    const data = useData();
+ *    return <DataList data={data} />;
+ *  }
+ *
+ *  interface ComponentControls {
+ *    DataList: typeof DataListControl;
+ *  }
+ *
+ *  function Component<T extends ComponentControls>(
+ *    controls?: T
+ *  ) {
+ *    function ConnectedComponent({
+ *      children,
+ *    }: { children?: React.ReactNode }) {
+ *      return (
+ *        <ControlsProvider controls={controls}>
+ *          {children}
+ *        </ControlsProvider>
+ *      );
+ *    }
+ *
+ *    return ConnectedComponent;
+ *  }
+ * ```
+ */
+function ControlsProvider({ controls, ...props }) {
+    return React__default["default"].createElement(ControlsContext.Provider, { ...props, value: controls });
+}
+/**
+ * @internal @unstable
+ *
+ * @note reference `ControlsProvider` for example usage
+ */
+function withControls(Default, name) {
+    const Component = (props) => {
+        const Override = React__default["default"].useContext(ControlsContext)?.[name];
+        if (isComponent(Override)) {
+            return React__default["default"].createElement(Override, { ...props });
+        }
+        return React__default["default"].createElement(Default, { ...props });
+    };
+    Component.displayName = name;
+    return Component;
+}
+
 const ElementsContext = React__default["default"].createContext(undefined);
 /**
  * @internal @unstable
  *
  * `ElementsProvider` provides the values contained in `ElementsContext`
  * to its `children`. `ElementsContext` lookup is handled directly
- * by `BaseElement`components returned by `defineBaseElement`.
+ * by `BaseElement`components returned by `defineBaseElement` and
+ * `defineBaseElementWithRef`.
  *
  * @example
  *
@@ -23,7 +101,7 @@ const ElementsContext = React__default["default"].createContext(undefined);
  *
  * ```tsx
  * // `BaseElement`, renders custom or default element defintion
- * const ViewElement = defineBaseElement({
+ * const ViewElement = defineBaseElementWithRef({
  *   displayName: "View",
  *   type: "div",
  * });
@@ -77,6 +155,35 @@ function ElementsProvider({ elements, ...props }) {
  * @returns {BaseElement} `ElementsContext` aware UI component
  */
 function defineBaseElement(input) {
+    const { displayName, type } = input;
+    const Element = ({ variant, ...props }) => {
+        const Element = React__default["default"].useContext(ElementsContext)?.[displayName];
+        if (Element) {
+            // only pass `variant` to provided `Element` values
+            return React__default["default"].createElement(Element, { ...props, variant });
+        }
+        return React__default["default"].createElement(type, props);
+    };
+    Element.displayName = displayName;
+    return Element;
+}
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName` and element `ref`.
+ *
+ * If `BaseElement` is used as a child of an `ElementsProvider`, returns the
+ * `BaseElement` value of the provided `displayName` of `ElementsContext`.
+ *
+ * When used outside of a  parent `ElementsProvider` or no `BaseElement`
+ * of `displayName` is found in the `ElementsContext`, returns a stateless,
+ * unstyled HTML element of the provided `type`.
+ *
+ * @param {DefineBaseElementInput} input `BaseElement` parameters
+ * @returns {BaseElementWithRefProps} `ElementsContext` aware UI component
+ */
+function defineBaseElementWithRef(input) {
     const { displayName, type } = input;
     const Element = React__default["default"].forwardRef(({ variant, ...props }, ref) => {
         const Element = React__default["default"].useContext(ElementsContext)?.[displayName];
@@ -105,7 +212,7 @@ function defineBaseElement(input) {
  * type InputElementPropKey = 'onChange' | 'type';
  *
  * // create `InputElement` base with `type` generic and extended `props` key
- * export const InputElement = defineBaseElement<"input", InputElementPropKey>({
+ * export const InputElement = defineBaseElementWithRef<"input", InputElementPropKey>({
  *   type: "input",
  *   displayName: "Input",
  * });
@@ -130,6 +237,12 @@ function withBaseElementProps(Target, defaultProps) {
     return Component;
 }
 
+exports.ControlsContext = ControlsContext;
+exports.ControlsProvider = ControlsProvider;
 exports.ElementsProvider = ElementsProvider;
 exports.defineBaseElement = defineBaseElement;
+exports.defineBaseElementWithRef = defineBaseElementWithRef;
+exports.isComponent = isComponent;
+exports.isForwardRefExoticComponent = isForwardRefExoticComponent;
 exports.withBaseElementProps = withBaseElementProps;
+exports.withControls = withControls;

package/dist/esm/elements/ControlsContext.mjs

@@ -0,0 +1,71 @@
+import React__default from 'react';
+import { isComponent } from './utils.mjs';
+
+/**
+ * @internal @unstable
+ */
+const ControlsContext = React__default.createContext(undefined);
+/**
+ * @internal @unstable
+ *
+ * `ControlsProvider` provides the values contained in `ControlsContext`
+ * to consumers. `ControlsContext` lookup is handled directly
+ * by `Control` components returned by `withControls`.
+ *
+ * @example
+ *
+ * Add `ControlsContext` aware `Controls` components to a Connected
+ * Component:
+ *
+ * ```tsx
+ *  const DataList = withControls(function DataList<T>(data: T[]) {
+ *    return <ScrollView>data.map(ListItem)</ScrollView>;
+ *  }, 'DataList');
+ *
+ *  const DataListControl = () => {
+ *    const data = useData();
+ *    return <DataList data={data} />;
+ *  }
+ *
+ *  interface ComponentControls {
+ *    DataList: typeof DataListControl;
+ *  }
+ *
+ *  function Component<T extends ComponentControls>(
+ *    controls?: T
+ *  ) {
+ *    function ConnectedComponent({
+ *      children,
+ *    }: { children?: React.ReactNode }) {
+ *      return (
+ *        <ControlsProvider controls={controls}>
+ *          {children}
+ *        </ControlsProvider>
+ *      );
+ *    }
+ *
+ *    return ConnectedComponent;
+ *  }
+ * ```
+ */
+function ControlsProvider({ controls, ...props }) {
+    return React__default.createElement(ControlsContext.Provider, { ...props, value: controls });
+}
+/**
+ * @internal @unstable
+ *
+ * @note reference `ControlsProvider` for example usage
+ */
+function withControls(Default, name) {
+    const Component = (props) => {
+        const Override = React__default.useContext(ControlsContext)?.[name];
+        if (isComponent(Override)) {
+            return React__default.createElement(Override, { ...props });
+        }
+        return React__default.createElement(Default, { ...props });
+    };
+    Component.displayName = name;
+    return Component;
+}
+
+export { ControlsContext, ControlsProvider, withControls };

package/dist/esm/elements/ElementsContext.mjs

@@ -6,7 +6,8 @@ const ElementsContext = React__default.createContext(undefined);
  *
  * `ElementsProvider` provides the values contained in `ElementsContext`
  * to its `children`. `ElementsContext` lookup is handled directly
- * by `BaseElement`components returned by `defineBaseElement`.
+ * by `BaseElement`components returned by `defineBaseElement` and
+ * `defineBaseElementWithRef`.
  *
  * @example
  *
@@ -15,7 +16,7 @@ const ElementsContext = React__default.createContext(undefined);
  *
  * ```tsx
  * // `BaseElement`, renders custom or default element defintion
- * const ViewElement = defineBaseElement({
+ * const ViewElement = defineBaseElementWithRef({
  *   displayName: "View",
  *   type: "div",
  * });

package/dist/esm/elements/defineBaseElement.mjs

@@ -18,6 +18,35 @@ import { ElementsContext } from './ElementsContext.mjs';
  * @returns {BaseElement} `ElementsContext` aware UI component
  */
 function defineBaseElement(input) {
+    const { displayName, type } = input;
+    const Element = ({ variant, ...props }) => {
+        const Element = React__default.useContext(ElementsContext)?.[displayName];
+        if (Element) {
+            // only pass `variant` to provided `Element` values
+            return React__default.createElement(Element, { ...props, variant });
+        }
+        return React__default.createElement(type, props);
+    };
+    Element.displayName = displayName;
+    return Element;
+}
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName` and element `ref`.
+ *
+ * If `BaseElement` is used as a child of an `ElementsProvider`, returns the
+ * `BaseElement` value of the provided `displayName` of `ElementsContext`.
+ *
+ * When used outside of a  parent `ElementsProvider` or no `BaseElement`
+ * of `displayName` is found in the `ElementsContext`, returns a stateless,
+ * unstyled HTML element of the provided `type`.
+ *
+ * @param {DefineBaseElementInput} input `BaseElement` parameters
+ * @returns {BaseElementWithRefProps} `ElementsContext` aware UI component
+ */
+function defineBaseElementWithRef(input) {
     const { displayName, type } = input;
     const Element = React__default.forwardRef(({ variant, ...props }, ref) => {
         const Element = React__default.useContext(ElementsContext)?.[displayName];
@@ -31,4 +60,4 @@ function defineBaseElement(input) {
     return Element;
 }
 
-export { defineBaseElement as default };
+export { defineBaseElement, defineBaseElementWithRef };

package/dist/esm/elements/utils.mjs

@@ -0,0 +1,11 @@
+function isComponent(component) {
+    return typeof component === 'function';
+}
+function isForwardRefExoticComponent(component) {
+    return (typeof component === 'object' &&
+        typeof component.$$typeof ===
+            'symbol' &&
+        ['react.memo', 'react.forward_ref'].includes(component.$$typeof.description));
+}
+
+export { isComponent, isForwardRefExoticComponent };

package/dist/esm/elements/withBaseElementProps.mjs

@@ -15,7 +15,7 @@ import React__default from 'react';
  * type InputElementPropKey = 'onChange' | 'type';
  *
  * // create `InputElement` base with `type` generic and extended `props` key
- * export const InputElement = defineBaseElement<"input", InputElementPropKey>({
+ * export const InputElement = defineBaseElementWithRef<"input", InputElementPropKey>({
  *   type: "input",
  *   displayName: "Input",
  * });

package/dist/esm/elements.mjs

@@ -1,3 +1,5 @@
-export { default as defineBaseElement } from './elements/defineBaseElement.mjs';
+export { ControlsContext, ControlsProvider, withControls } from './elements/ControlsContext.mjs';
+export { defineBaseElement, defineBaseElementWithRef } from './elements/defineBaseElement.mjs';
 export { default as withBaseElementProps } from './elements/withBaseElementProps.mjs';
 export { ElementsProvider } from './elements/ElementsContext.mjs';
+export { isComponent, isForwardRefExoticComponent } from './elements/utils.mjs';

package/dist/esm/hooks/useDataState.mjs

@@ -1,3 +1,4 @@
+import { isFunction } from '@aws-amplify/ui';
 import React__default from 'react';
 
 // default state
@@ -8,23 +9,28 @@ const resolveMaybeAsync = async (value) => {
     const awaited = await value;
     return awaited;
 };
-function useDataState(action, initialData) {
+function useDataState(action, initialData, options) {
     const [dataState, setDataState] = React__default.useState(() => ({
         ...INITIAL_STATE,
         data: initialData,
     }));
     const prevData = React__default.useRef(initialData);
-    const handleAction = React__default.useCallback((...input) => {
+    const { onSuccess, onError } = options ?? {};
+    const handleAction = React__default.useCallback((input) => {
         setDataState(({ data }) => ({ ...LOADING_STATE, data }));
-        resolveMaybeAsync(action(prevData.current, ...input))
+        resolveMaybeAsync(action(prevData.current, input))
             .then((data) => {
+            if (isFunction(onSuccess))
+                onSuccess(data);
             prevData.current = data;
             setDataState({ ...INITIAL_STATE, data });
         })
             .catch(({ message }) => {
+            if (isFunction(onError))
+                onError(message);
             setDataState(({ data }) => ({ ...ERROR_STATE, data, message }));
         });
-    }, [action]);
+    }, [action, onError, onSuccess]);
     return [dataState, handleAction];
 }
 

package/dist/esm/utils/createContextUtilities.mjs

@@ -53,7 +53,10 @@ function createContextUtilities(options) {
     if (isUndefined(defaultValue) && !isString(errorMessage)) {
         throw new Error(INVALID_OPTIONS_MESSAGE);
     }
+    const contextDisplayName = `${contextName}Context`;
+    const providerDisplayName = `${contextName}Provider`;
     const Context = React__default.createContext(defaultValue);
+    Context.displayName = contextDisplayName;
     function Provider(props) {
         const { children, ...context } = props;
         const value = React__default.useMemo(() => context, 
@@ -63,7 +66,7 @@ function createContextUtilities(options) {
         Object.values(context));
         return React__default.createElement(Context.Provider, { value: value }, children);
     }
-    Provider.displayName = `${contextName}Provider`;
+    Provider.displayName = providerDisplayName;
     return {
         [`use${contextName}`]: function (params) {
             const context = React__default.useContext(Context);
@@ -72,8 +75,8 @@ function createContextUtilities(options) {
             }
             return context;
         },
-        [`${contextName}Provider`]: Provider,
-        [`${contextName}Context`]: Context,
+        [providerDisplayName]: Provider,
+        [contextDisplayName]: Context,
     };
 }
 

package/dist/index.js

@@ -563,23 +563,28 @@ const resolveMaybeAsync = async (value) => {
     const awaited = await value;
     return awaited;
 };
-function useDataState(action, initialData) {
+function useDataState(action, initialData, options) {
     const [dataState, setDataState] = React__namespace["default"].useState(() => ({
         ...INITIAL_STATE,
         data: initialData,
     }));
     const prevData = React__namespace["default"].useRef(initialData);
-    const handleAction = React__namespace["default"].useCallback((...input) => {
+    const { onSuccess, onError } = options ?? {};
+    const handleAction = React__namespace["default"].useCallback((input) => {
         setDataState(({ data }) => ({ ...LOADING_STATE, data }));
-        resolveMaybeAsync(action(prevData.current, ...input))
+        resolveMaybeAsync(action(prevData.current, input))
             .then((data) => {
+            if (ui.isFunction(onSuccess))
+                onSuccess(data);
             prevData.current = data;
             setDataState({ ...INITIAL_STATE, data });
         })
             .catch(({ message }) => {
+            if (ui.isFunction(onError))
+                onError(message);
             setDataState(({ data }) => ({ ...ERROR_STATE, data, message }));
         });
-    }, [action]);
+    }, [action, onError, onSuccess]);
     return [dataState, handleAction];
 }
 
@@ -911,7 +916,10 @@ function createContextUtilities(options) {
     if (ui.isUndefined(defaultValue) && !ui.isString(errorMessage)) {
         throw new Error(INVALID_OPTIONS_MESSAGE);
     }
+    const contextDisplayName = `${contextName}Context`;
+    const providerDisplayName = `${contextName}Provider`;
     const Context = React__namespace["default"].createContext(defaultValue);
+    Context.displayName = contextDisplayName;
     function Provider(props) {
         const { children, ...context } = props;
         const value = React__namespace["default"].useMemo(() => context, 
@@ -921,7 +929,7 @@ function createContextUtilities(options) {
         Object.values(context));
         return React__namespace["default"].createElement(Context.Provider, { value: value }, children);
     }
-    Provider.displayName = `${contextName}Provider`;
+    Provider.displayName = providerDisplayName;
     return {
         [`use${contextName}`]: function (params) {
             const context = React__namespace["default"].useContext(Context);
@@ -930,8 +938,8 @@ function createContextUtilities(options) {
             }
             return context;
         },
-        [`${contextName}Provider`]: Provider,
-        [`${contextName}Context`]: Context,
+        [providerDisplayName]: Provider,
+        [contextDisplayName]: Context,
     };
 }
 

package/dist/types/elements/ControlsContext.d.ts

@@ -0,0 +1,63 @@
+import React from 'react';
+/**
+ * @internal @unstable
+ */
+export interface Controls extends Partial<Record<string, React.ComponentType>> {
+}
+/**
+ * @internal @unstable
+ */
+export declare const ControlsContext: React.Context<Controls | undefined>;
+/**
+ * @internal @unstable
+ *
+ * `ControlsProvider` provides the values contained in `ControlsContext`
+ * to consumers. `ControlsContext` lookup is handled directly
+ * by `Control` components returned by `withControls`.
+ *
+ * @example
+ *
+ * Add `ControlsContext` aware `Controls` components to a Connected
+ * Component:
+ *
+ * ```tsx
+ *  const DataList = withControls(function DataList<T>(data: T[]) {
+ *    return <ScrollView>data.map(ListItem)</ScrollView>;
+ *  }, 'DataList');
+ *
+ *  const DataListControl = () => {
+ *    const data = useData();
+ *    return <DataList data={data} />;
+ *  }
+ *
+ *  interface ComponentControls {
+ *    DataList: typeof DataListControl;
+ *  }
+ *
+ *  function Component<T extends ComponentControls>(
+ *    controls?: T
+ *  ) {
+ *    function ConnectedComponent({
+ *      children,
+ *    }: { children?: React.ReactNode }) {
+ *      return (
+ *        <ControlsProvider controls={controls}>
+ *          {children}
+ *        </ControlsProvider>
+ *      );
+ *    }
+ *
+ *    return ConnectedComponent;
+ *  }
+ * ```
+ */
+export declare function ControlsProvider<T extends Controls>({ controls, ...props }: {
+    children?: React.ReactNode;
+    controls?: T;
+}): React.JSX.Element;
+/**
+ * @internal @unstable
+ *
+ * @note reference `ControlsProvider` for example usage
+ */
+export declare function withControls<T extends React.ComponentType<any>, K extends keyof Controls>(Default: T, name: K): (props: React.ComponentProps<T>) => React.JSX.Element;

package/dist/types/elements/ElementsContext.d.ts

@@ -11,7 +11,8 @@ export declare const ElementsContext: React.Context<Elements | undefined>;
  *
  * `ElementsProvider` provides the values contained in `ElementsContext`
  * to its `children`. `ElementsContext` lookup is handled directly
- * by `BaseElement`components returned by `defineBaseElement`.
+ * by `BaseElement`components returned by `defineBaseElement` and
+ * `defineBaseElementWithRef`.
  *
  * @example
  *
@@ -20,7 +21,7 @@ export declare const ElementsContext: React.Context<Elements | undefined>;
  *
  * ```tsx
  * // `BaseElement`, renders custom or default element defintion
- * const ViewElement = defineBaseElement({
+ * const ViewElement = defineBaseElementWithRef({
  *   displayName: "View",
  *   type: "div",
  * });

package/dist/types/elements/defineBaseElement.d.ts

@@ -1,4 +1,4 @@
-import { BaseElement, BaseElementProps, ElementDisplayName, ElementRefType, ReactElementProps, ReactElementType } from './types';
+import { BaseElement, BaseElementProps, BaseElementWithRef, BaseElementWithRefProps, ElementDisplayName, ElementRefType, ReactElementProps, ReactElementType } from './types';
 /**
  * @internal @unstable
  */
@@ -28,4 +28,21 @@ export interface DefineBaseElementInput<T> {
  * @param {DefineBaseElementInput} input `BaseElement` parameters
  * @returns {BaseElement} `ElementsContext` aware UI component
  */
-export default function defineBaseElement<T extends ReactElementType, K extends keyof U = never, V = string, U extends ReactElementProps<T> = ReactElementProps<T>, P extends BaseElementProps<K, V, U> = BaseElementProps<K, V, U>>(input: DefineBaseElementInput<T>): BaseElement<P, ElementRefType<P>>;
+export declare function defineBaseElement<T extends ReactElementType, K extends keyof U = never, V = string, U extends ReactElementProps<T> = ReactElementProps<T>, P extends BaseElementProps<K, V, U> = BaseElementProps<K, V, U>>(input: DefineBaseElementInput<T>): BaseElement<P>;
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName` and element `ref`.
+ *
+ * If `BaseElement` is used as a child of an `ElementsProvider`, returns the
+ * `BaseElement` value of the provided `displayName` of `ElementsContext`.
+ *
+ * When used outside of a  parent `ElementsProvider` or no `BaseElement`
+ * of `displayName` is found in the `ElementsContext`, returns a stateless,
+ * unstyled HTML element of the provided `type`.
+ *
+ * @param {DefineBaseElementInput} input `BaseElement` parameters
+ * @returns {BaseElementWithRefProps} `ElementsContext` aware UI component
+ */
+export declare function defineBaseElementWithRef<T extends ReactElementType, K extends keyof U = never, V = string, U extends ReactElementProps<T> = ReactElementProps<T>, P extends BaseElementWithRefProps<K, V, U> = BaseElementWithRefProps<K, V, U>>(input: DefineBaseElementInput<T>): BaseElementWithRef<P, ElementRefType<P>>;

package/dist/types/elements/index.d.ts

@@ -1,3 +1,6 @@
-export { default as defineBaseElement } from './defineBaseElement';
+export * from './ControlsContext';
+export { defineBaseElement, defineBaseElementWithRef, } from './defineBaseElement';
 export { default as withBaseElementProps } from './withBaseElementProps';
 export { ElementsProvider } from './ElementsContext';
+export { isComponent, isForwardRefExoticComponent } from './utils';
+export * from './types';