@aws-amplify/ui-react-core 3.0.16 → 3.0.18

package/README.md

@@ -1,3 +1,3 @@
 # Amplify UI React Core
 
-`@aws-amplify/ui-react-core` is a React platform agnostic utility library for Amplify UI internal usage in the `@aws-amplify/ui-react` and `@aws-amplify/ui-react-native` packages.
+`@aws-amplify/ui-react-core` is a React platform agnostic utility library for Amplify UI internal usage in `@aws-amplify/ui-react*` and `@aws-amplify/ui-react-native*` namespaced packages.

package/dist/elements.js

@@ -0,0 +1,135 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var React = require('react');
+
+function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
+
+var React__default = /*#__PURE__*/_interopDefaultLegacy(React);
+
+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`.
+ *
+ * @example
+ *
+ * Add `ElementsContext` aware `BaseElement` components to a Connected
+ * Component
+ *
+ * ```tsx
+ * // `BaseElement`, renders custom or default element defintion
+ * const ViewElement = defineBaseElement({
+ *   displayName: "View",
+ *   type: "div",
+ * });
+ *
+ * // `BaseElement` components to be provided through `ElementsContext`
+ * interface ConnectedComponentElements {
+ *   View: typeof ViewElement;
+ * }
+ *
+ * function createConnectedComponent<T extends ConnectedComponentElements>(
+ *   elements?: T
+ * ) {
+ *   const Provider = ({ children }: { children?: React.ReactNode }) => (
+ *     <ElementsProvider elements={elements}>
+ *       <Children />
+ *     </ElementsProvider>
+ *   );
+ *
+ *   function ConnectedComponent() {
+ *     return (
+ *       <Provider>
+ *         <ConnectedComponentContent />
+ *       </Provider>
+ *     );
+ *   }
+ *
+ *   ConnectedComponent.Provider = Provider;
+ *
+ *   return ConnectedComponent;
+ * }
+ * ```
+ */
+function ElementsProvider({ elements, ...props }) {
+    return React__default["default"].createElement(ElementsContext.Provider, { ...props, value: elements });
+}
+
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName`.
+ *
+ * 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 {BaseElement} `ElementsContext` aware UI component
+ */
+function defineBaseElement(input) {
+    const { displayName, type } = input;
+    const Element = React__default["default"].forwardRef(({ variant, ...props }, ref) => {
+        const Element = React__default["default"].useContext(ElementsContext)?.[displayName];
+        if (Element) {
+            // only pass `variant` to provided `Element` values
+            return React__default["default"].createElement(Element, { ...props, ref, variant });
+        }
+        return React__default["default"].createElement(type, { ...props, ref });
+    });
+    Element.displayName = displayName;
+    return Element;
+}
+
+/**
+ * @internal @unstable
+ *
+ * Extend target `BaseElement` with `defaultProps`. `defaultProps`
+ * are overidden by `props` provided to returned `BaseElement`.
+ *
+ * @example
+ *
+ * Extend `InputElement` with default `className` and `type`
+ * ```tsx
+ *
+ * // define extended `props` on `BaseElement` interface
+ * type InputElementPropKey = 'onChange' | 'type';
+ *
+ * // create `InputElement` base with `type` generic and extended `props` key
+ * export const InputElement = defineBaseElement<"input", InputElementPropKey>({
+ *   type: "input",
+ *   displayName: "Input",
+ * });
+ *
+ * // extend base `InputElement` with default input `type` of `checkbox`
+ * const CheckboxElement = withBaseElementProps(Input, {
+ *   className: 'submit-toggle__checkbox',
+ *   type: 'checkbox',
+ * });
+ * ```
+ *
+ * @param Target `BaseElement` to extend
+ * @param defaultProps `defaultProps` to apply to `Target`, accepts object or callback
+ * @returns extended `BaseElement` with `defaultProps`
+ */
+function withBaseElementProps(Target, defaultProps) {
+    const Component = React__default["default"].forwardRef((props, ref) => (React__default["default"].createElement(Target, { ...(typeof defaultProps === 'function'
+            ? defaultProps(props)
+            : defaultProps),
+        ...props, ref: ref })));
+    Component.displayName = Target.displayName;
+    return Component;
+}
+
+exports.ElementsProvider = ElementsProvider;
+exports.defineBaseElement = defineBaseElement;
+exports.withBaseElementProps = withBaseElementProps;

package/dist/esm/elements/ElementsContext.mjs

@@ -0,0 +1,55 @@
+import React__default from 'react';
+
+const ElementsContext = React__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`.
+ *
+ * @example
+ *
+ * Add `ElementsContext` aware `BaseElement` components to a Connected
+ * Component
+ *
+ * ```tsx
+ * // `BaseElement`, renders custom or default element defintion
+ * const ViewElement = defineBaseElement({
+ *   displayName: "View",
+ *   type: "div",
+ * });
+ *
+ * // `BaseElement` components to be provided through `ElementsContext`
+ * interface ConnectedComponentElements {
+ *   View: typeof ViewElement;
+ * }
+ *
+ * function createConnectedComponent<T extends ConnectedComponentElements>(
+ *   elements?: T
+ * ) {
+ *   const Provider = ({ children }: { children?: React.ReactNode }) => (
+ *     <ElementsProvider elements={elements}>
+ *       <Children />
+ *     </ElementsProvider>
+ *   );
+ *
+ *   function ConnectedComponent() {
+ *     return (
+ *       <Provider>
+ *         <ConnectedComponentContent />
+ *       </Provider>
+ *     );
+ *   }
+ *
+ *   ConnectedComponent.Provider = Provider;
+ *
+ *   return ConnectedComponent;
+ * }
+ * ```
+ */
+function ElementsProvider({ elements, ...props }) {
+    return React__default.createElement(ElementsContext.Provider, { ...props, value: elements });
+}
+
+export { ElementsContext, ElementsProvider };

package/dist/esm/elements/defineBaseElement.mjs

@@ -0,0 +1,34 @@
+import React__default from 'react';
+import { ElementsContext } from './ElementsContext.mjs';
+
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName`.
+ *
+ * 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 {BaseElement} `ElementsContext` aware UI component
+ */
+function defineBaseElement(input) {
+    const { displayName, type } = input;
+    const Element = React__default.forwardRef(({ variant, ...props }, ref) => {
+        const Element = React__default.useContext(ElementsContext)?.[displayName];
+        if (Element) {
+            // only pass `variant` to provided `Element` values
+            return React__default.createElement(Element, { ...props, ref, variant });
+        }
+        return React__default.createElement(type, { ...props, ref });
+    });
+    Element.displayName = displayName;
+    return Element;
+}
+
+export { defineBaseElement as default };

package/dist/esm/elements/elements.mjs

@@ -0,0 +1,3 @@
+export { default as defineBaseElement } from './defineBaseElement.mjs';
+export { default as withBaseElementProps } from './withBaseElementProps.mjs';
+export { ElementsProvider } from './ElementsContext.mjs';

package/dist/esm/elements/withBaseElementProps.mjs

@@ -0,0 +1,43 @@
+import React__default from 'react';
+
+/**
+ * @internal @unstable
+ *
+ * Extend target `BaseElement` with `defaultProps`. `defaultProps`
+ * are overidden by `props` provided to returned `BaseElement`.
+ *
+ * @example
+ *
+ * Extend `InputElement` with default `className` and `type`
+ * ```tsx
+ *
+ * // define extended `props` on `BaseElement` interface
+ * type InputElementPropKey = 'onChange' | 'type';
+ *
+ * // create `InputElement` base with `type` generic and extended `props` key
+ * export const InputElement = defineBaseElement<"input", InputElementPropKey>({
+ *   type: "input",
+ *   displayName: "Input",
+ * });
+ *
+ * // extend base `InputElement` with default input `type` of `checkbox`
+ * const CheckboxElement = withBaseElementProps(Input, {
+ *   className: 'submit-toggle__checkbox',
+ *   type: 'checkbox',
+ * });
+ * ```
+ *
+ * @param Target `BaseElement` to extend
+ * @param defaultProps `defaultProps` to apply to `Target`, accepts object or callback
+ * @returns extended `BaseElement` with `defaultProps`
+ */
+function withBaseElementProps(Target, defaultProps) {
+    const Component = React__default.forwardRef((props, ref) => (React__default.createElement(Target, { ...(typeof defaultProps === 'function'
+            ? defaultProps(props)
+            : defaultProps),
+        ...props, ref: ref })));
+    Component.displayName = Target.displayName;
+    return Component;
+}
+
+export { withBaseElementProps as default };

package/dist/esm/index.mjs

@@ -9,6 +9,7 @@ export { default as useForm } from './components/FormCore/useForm.mjs';
 export { default as FormProvider } from './components/FormCore/FormProvider.mjs';
 export { default as withFormProvider } from './components/FormCore/withFormProvider.mjs';
 export { default as RenderNothing } from './components/RenderNothing/RenderNothing.mjs';
+import 'react';
 export { default as useDeprecationWarning } from './hooks/useDeprecationWarning.mjs';
 export { default as useGetUrl } from './hooks/useGetUrl.mjs';
 export { default as useHasValueUpdated } from './hooks/useHasValueUpdated.mjs';

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

@@ -0,0 +1,59 @@
+import React from 'react';
+import { ElementDisplayName } from './types';
+/**
+ * @internal @unstable
+ */
+export interface Elements extends Partial<Record<ElementDisplayName, React.ComponentType>> {
+}
+export declare const ElementsContext: React.Context<Elements | undefined>;
+/**
+ * @internal @unstable
+ *
+ * `ElementsProvider` provides the values contained in `ElementsContext`
+ * to its `children`. `ElementsContext` lookup is handled directly
+ * by `BaseElement`components returned by `defineBaseElement`.
+ *
+ * @example
+ *
+ * Add `ElementsContext` aware `BaseElement` components to a Connected
+ * Component
+ *
+ * ```tsx
+ * // `BaseElement`, renders custom or default element defintion
+ * const ViewElement = defineBaseElement({
+ *   displayName: "View",
+ *   type: "div",
+ * });
+ *
+ * // `BaseElement` components to be provided through `ElementsContext`
+ * interface ConnectedComponentElements {
+ *   View: typeof ViewElement;
+ * }
+ *
+ * function createConnectedComponent<T extends ConnectedComponentElements>(
+ *   elements?: T
+ * ) {
+ *   const Provider = ({ children }: { children?: React.ReactNode }) => (
+ *     <ElementsProvider elements={elements}>
+ *       <Children />
+ *     </ElementsProvider>
+ *   );
+ *
+ *   function ConnectedComponent() {
+ *     return (
+ *       <Provider>
+ *         <ConnectedComponentContent />
+ *       </Provider>
+ *     );
+ *   }
+ *
+ *   ConnectedComponent.Provider = Provider;
+ *
+ *   return ConnectedComponent;
+ * }
+ * ```
+ */
+export declare function ElementsProvider<T extends Elements>({ elements, ...props }: {
+    children?: React.ReactNode;
+    elements?: T;
+}): React.JSX.Element;

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

@@ -0,0 +1,31 @@
+import { BaseElement, BaseElementProps, ElementDisplayName, ElementRefType, ReactElementProps, ReactElementType } from './types';
+/**
+ * @internal @unstable
+ */
+export interface DefineBaseElementInput<T> {
+    /**
+     * `BaseElement` display name in React dev tools and stack traces
+     */
+    displayName: ElementDisplayName;
+    /**
+     * base HTML `element` type
+     */
+    type: T;
+}
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName`.
+ *
+ * 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 {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>>;

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

@@ -0,0 +1,3 @@
+export { default as defineBaseElement } from './defineBaseElement';
+export { default as withBaseElementProps } from './withBaseElementProps';
+export { ElementsProvider } from './ElementsContext';

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

@@ -0,0 +1,53 @@
+import React from 'react';
+/**
+ * @internal @unstable
+ *
+ * Base type definition of `BaseElement` components available through
+ * `ElementsContext`. The definitions define a contract between a
+ * Connected Component and the `elements` that can be provided as
+ * overrides.
+ *
+ * `BaseElement` interfaces surface a minimal set of HTML semantic `props`
+ * required to achieve the base functionality of consumers. `props`
+ * are always optional at the interface level, allowing for additional `props`
+ * to be added to existing `BaseElement` interfaces as needed.
+ */
+export type BaseElement<T = {}, K = {}> = React.ForwardRefExoticComponent<React.PropsWithoutRef<T> & React.RefAttributes<K>>;
+type ListElementSubType = 'Ordered' | 'Unordered';
+type ListElementDisplayName = 'List' | `${ListElementSubType}List`;
+type TableElementSubType = 'Body' | 'Data' | 'Row' | 'Head' | 'Header';
+type TableElementDisplayName = 'Table' | `Table${TableElementSubType}`;
+/**
+ * @internal @unstable
+ *
+ * allowed values of `displayName` of `BaseElement` and `ElemebtsContext` keys
+ */
+export type ElementDisplayName = 'Button' | 'Divider' | 'Heading' | 'Icon' | 'Input' | 'Label' | 'ListItem' | 'Nav' | 'ProgressBar' | 'Span' | 'Text' | 'Title' | 'View' | ListElementDisplayName | TableElementDisplayName;
+/**
+ * @internal @unstable
+ */
+export type ElementRefType<T> = T extends {
+    ref?: React.LegacyRef<infer K> | React.Ref<infer K> | React.ForwardedRef<infer K>;
+} ? K : never;
+/**
+ * @internal @unstable
+ */
+export type ReactElementType = keyof React.JSX.IntrinsicElements;
+/**
+ * @internal @unstable
+ */
+export type ReactElementProps<T extends ReactElementType> = React.JSX.IntrinsicElements[T];
+/**
+ * @internal @unstable
+ *
+ * key of `props` always available on `BaseElement` definitions
+ */
+type ElementPropKey<T> = T | 'children' | 'className' | 'style';
+/**
+ * @internal @unstable
+ */
+export type BaseElementProps<T extends keyof K, V = string, K extends Record<ElementPropKey<keyof K>, any> = Record<string, any>> = React.AriaAttributes & React.RefAttributes<ElementRefType<K>> & Pick<K, ElementPropKey<T>> & {
+    testId?: string;
+    variant?: V;
+};
+export {};

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

@@ -0,0 +1,34 @@
+import React from 'react';
+import { BaseElement, ElementRefType } from './types';
+/**
+ * @internal @unstable
+ *
+ * Extend target `BaseElement` with `defaultProps`. `defaultProps`
+ * are overidden by `props` provided to returned `BaseElement`.
+ *
+ * @example
+ *
+ * Extend `InputElement` with default `className` and `type`
+ * ```tsx
+ *
+ * // define extended `props` on `BaseElement` interface
+ * type InputElementPropKey = 'onChange' | 'type';
+ *
+ * // create `InputElement` base with `type` generic and extended `props` key
+ * export const InputElement = defineBaseElement<"input", InputElementPropKey>({
+ *   type: "input",
+ *   displayName: "Input",
+ * });
+ *
+ * // extend base `InputElement` with default input `type` of `checkbox`
+ * const CheckboxElement = withBaseElementProps(Input, {
+ *   className: 'submit-toggle__checkbox',
+ *   type: 'checkbox',
+ * });
+ * ```
+ *
+ * @param Target `BaseElement` to extend
+ * @param defaultProps `defaultProps` to apply to `Target`, accepts object or callback
+ * @returns extended `BaseElement` with `defaultProps`
+ */
+export default function withBaseElementProps<T, K extends T | ((input: T) => T)>(Target: React.ForwardRefExoticComponent<T>, defaultProps: K): BaseElement<T, ElementRefType<T>>;

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

@@ -1,3 +1,4 @@
+export { default as useDataState, DataState } from './useDataState';
 export { default as useDeprecationWarning, UseDeprecationWarning, } from './useDeprecationWarning';
 export { default as useGetUrl } from './useGetUrl';
 export { default as useHasValueUpdated } from './useHasValueUpdated';

package/dist/types/hooks/useDataState.d.ts

@@ -0,0 +1,7 @@
+export interface DataState<T> {
+    data: T;
+    hasError: boolean;
+    isLoading: boolean;
+    message: string | undefined;
+}
+export default function useDataState<T, K>(action: (prevData: T, ...input: K[]) => T | Promise<T>, initialData: T): [state: DataState<T>, handleAction: (...input: K[]) => void];

package/elements/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@aws-amplify/ui-react-core/elements",
+  "main": "../dist/elements.js",
+  "module": "../dist/esm/elements/elements.mjs",
+  "types": "../dist/types/elements/index.d.ts"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-amplify/ui-react-core",
-  "version": "3.0.16",
+  "version": "3.0.18",
   "main": "dist/index.js",
   "module": "dist/esm/index.mjs",
   "react-native": "src/index.ts",
@@ -10,12 +10,19 @@
       "require": "./dist/index.js",
       "types": "./dist/types/index.d.ts"
     },
+    "./elements": {
+      "import": "./dist/esm/elements/elements.mjs",
+      "require": "./dist/elements.js",
+      "react-native": "./src/elements/index.ts",
+      "types": "./dist/types/elements/index.d.ts"
+    },
     "./package.json": "./package.json"
   },
   "types": "dist/types/index.d.ts",
   "license": "Apache-2.0",
   "files": [
     "dist",
+    "elements",
     "LICENSE",
     "src",
     "!**/__mocks__",
@@ -33,7 +40,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@aws-amplify/ui": "6.0.16",
+    "@aws-amplify/ui": "6.1.0",
     "@xstate/react": "^3.2.2",
     "lodash": "4.17.21",
     "react-hook-form": "^7.43.5",

package/src/elements/ElementsContext.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { ElementDisplayName } from './types';
+
+/**
+ * @internal @unstable
+ */
+export interface Elements
+  extends Partial<Record<ElementDisplayName, React.ComponentType>> {}
+
+export const ElementsContext = React.createContext<Elements | undefined>(
+  undefined
+);
+
+/**
+ * @internal @unstable
+ *
+ * `ElementsProvider` provides the values contained in `ElementsContext`
+ * to its `children`. `ElementsContext` lookup is handled directly
+ * by `BaseElement`components returned by `defineBaseElement`.
+ *
+ * @example
+ *
+ * Add `ElementsContext` aware `BaseElement` components to a Connected
+ * Component
+ *
+ * ```tsx
+ * // `BaseElement`, renders custom or default element defintion
+ * const ViewElement = defineBaseElement({
+ *   displayName: "View",
+ *   type: "div",
+ * });
+ *
+ * // `BaseElement` components to be provided through `ElementsContext`
+ * interface ConnectedComponentElements {
+ *   View: typeof ViewElement;
+ * }
+ *
+ * function createConnectedComponent<T extends ConnectedComponentElements>(
+ *   elements?: T
+ * ) {
+ *   const Provider = ({ children }: { children?: React.ReactNode }) => (
+ *     <ElementsProvider elements={elements}>
+ *       <Children />
+ *     </ElementsProvider>
+ *   );
+ *
+ *   function ConnectedComponent() {
+ *     return (
+ *       <Provider>
+ *         <ConnectedComponentContent />
+ *       </Provider>
+ *     );
+ *   }
+ *
+ *   ConnectedComponent.Provider = Provider;
+ *
+ *   return ConnectedComponent;
+ * }
+ * ```
+ */
+export function ElementsProvider<T extends Elements>({
+  elements,
+  ...props
+}: {
+  children?: React.ReactNode;
+  elements?: T;
+}): React.JSX.Element {
+  return <ElementsContext.Provider {...props} value={elements} />;
+}

package/src/elements/defineBaseElement.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import { ElementsContext } from './ElementsContext';
+import {
+  BaseElement,
+  BaseElementProps,
+  ElementDisplayName,
+  ElementRefType,
+  ReactElementProps,
+  ReactElementType,
+} from './types';
+
+/**
+ * @internal @unstable
+ */
+export interface DefineBaseElementInput<T> {
+  /**
+   * `BaseElement` display name in React dev tools and stack traces
+   */
+  displayName: ElementDisplayName;
+
+  /**
+   * base HTML `element` type
+   */
+  type: T;
+}
+
+/**
+ * @internal @unstable
+ *
+ * Defines a `ElementsContext` aware `BaseElement` UI component of the
+ * provided `type` with an assigned `displayName`.
+ *
+ * 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 {BaseElement} `ElementsContext` aware UI component
+ */
+export default function defineBaseElement<
+  // element type
+  T extends ReactElementType,
+  // string union of base element props to include
+  K extends keyof U = never,
+  // variant string union
+  V = string,
+  // available props of base element type
+  U extends ReactElementProps<T> = ReactElementProps<T>,
+  // control element props
+  P extends BaseElementProps<K, V, U> = BaseElementProps<K, V, U>,
+>(input: DefineBaseElementInput<T>): BaseElement<P, ElementRefType<P>> {
+  const { displayName, type } = input;
+
+  const Element = React.forwardRef<ElementRefType<P>, P>(
+    ({ variant, ...props }, ref) => {
+      const Element = React.useContext(ElementsContext)?.[displayName];
+
+      if (Element) {
+        // only pass `variant` to provided `Element` values
+        return <Element {...{ ...props, ref, variant }} />;
+      }
+
+      return React.createElement(type, { ...props, ref });
+    }
+  );
+
+  Element.displayName = displayName;
+
+  return Element;
+}

package/src/elements/index.ts

@@ -0,0 +1,3 @@
+export { default as defineBaseElement } from './defineBaseElement';
+export { default as withBaseElementProps } from './withBaseElementProps';
+export { ElementsProvider } from './ElementsContext';

package/src/elements/types.ts

@@ -0,0 +1,87 @@
+import React from 'react';
+
+/**
+ * @internal @unstable
+ *
+ * Base type definition of `BaseElement` components available through
+ * `ElementsContext`. The definitions define a contract between a
+ * Connected Component and the `elements` that can be provided as
+ * overrides.
+ *
+ * `BaseElement` interfaces surface a minimal set of HTML semantic `props`
+ * required to achieve the base functionality of consumers. `props`
+ * are always optional at the interface level, allowing for additional `props`
+ * to be added to existing `BaseElement` interfaces as needed.
+ */
+export type BaseElement<T = {}, K = {}> = React.ForwardRefExoticComponent<
+  React.PropsWithoutRef<T> & React.RefAttributes<K>
+>;
+
+type ListElementSubType = 'Ordered' | 'Unordered';
+type ListElementDisplayName = 'List' | `${ListElementSubType}List`;
+
+type TableElementSubType = 'Body' | 'Data' | 'Row' | 'Head' | 'Header';
+type TableElementDisplayName = 'Table' | `Table${TableElementSubType}`;
+
+/**
+ * @internal @unstable
+ *
+ * allowed values of `displayName` of `BaseElement` and `ElemebtsContext` keys
+ */
+export type ElementDisplayName =
+  | 'Button'
+  | 'Divider'
+  | 'Heading' // h1, h2, etc
+  | 'Icon'
+  | 'Input'
+  | 'Label'
+  | 'ListItem'
+  | 'Nav'
+  | 'ProgressBar'
+  | 'Span'
+  | 'Text'
+  | 'Title'
+  | 'View'
+  | ListElementDisplayName
+  | TableElementDisplayName;
+
+/**
+ * @internal @unstable
+ */
+export type ElementRefType<T> = T extends {
+  ref?:
+    | React.LegacyRef<infer K>
+    | React.Ref<infer K>
+    | React.ForwardedRef<infer K>;
+}
+  ? K
+  : never;
+
+/**
+ * @internal @unstable
+ */
+export type ReactElementType = keyof React.JSX.IntrinsicElements;
+
+/**
+ * @internal @unstable
+ */
+export type ReactElementProps<T extends ReactElementType> =
+  React.JSX.IntrinsicElements[T];
+
+/**
+ * @internal @unstable
+ *
+ * key of `props` always available on `BaseElement` definitions
+ */
+type ElementPropKey<T> = T | 'children' | 'className' | 'style';
+
+/**
+ * @internal @unstable
+ */
+export type BaseElementProps<
+  T extends keyof K,
+  V = string,
+  K extends Record<ElementPropKey<keyof K>, any> = Record<string, any>,
+> = React.AriaAttributes &
+  React.RefAttributes<ElementRefType<K>> &
+  Pick<K, ElementPropKey<T>> & { testId?: string; variant?: V };

package/src/elements/withBaseElementProps.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { BaseElement, ElementRefType } from './types';
+
+/**
+ * @internal @unstable
+ *
+ * Extend target `BaseElement` with `defaultProps`. `defaultProps`
+ * are overidden by `props` provided to returned `BaseElement`.
+ *
+ * @example
+ *
+ * Extend `InputElement` with default `className` and `type`
+ * ```tsx
+ *
+ * // define extended `props` on `BaseElement` interface
+ * type InputElementPropKey = 'onChange' | 'type';
+ *
+ * // create `InputElement` base with `type` generic and extended `props` key
+ * export const InputElement = defineBaseElement<"input", InputElementPropKey>({
+ *   type: "input",
+ *   displayName: "Input",
+ * });
+ *
+ * // extend base `InputElement` with default input `type` of `checkbox`
+ * const CheckboxElement = withBaseElementProps(Input, {
+ *   className: 'submit-toggle__checkbox',
+ *   type: 'checkbox',
+ * });
+ * ```
+ *
+ * @param Target `BaseElement` to extend
+ * @param defaultProps `defaultProps` to apply to `Target`, accepts object or callback
+ * @returns extended `BaseElement` with `defaultProps`
+ */
+export default function withBaseElementProps<
+  T,
+  K extends T | ((input: T) => T),
+>(
+  Target: React.ForwardRefExoticComponent<T>,
+  defaultProps: K
+): BaseElement<T, ElementRefType<T>> {
+  const Component = React.forwardRef<ElementRefType<T>, T>((props, ref) => (
+    <Target
+      {...{
+        ...(typeof defaultProps === 'function'
+          ? defaultProps(props)
+          : defaultProps),
+        ...props,
+      }}
+      ref={ref}
+    />
+  ));
+  Component.displayName = Target.displayName;
+  return Component;
+}

package/src/hooks/index.ts

@@ -1,3 +1,5 @@
+export { default as useDataState, DataState } from './useDataState';
+
 export {
   default as useDeprecationWarning,
   UseDeprecationWarning,

package/src/hooks/useDataState.ts

@@ -0,0 +1,50 @@
+import React from 'react';
+
+export interface DataState<T> {
+  data: T;
+  hasError: boolean;
+  isLoading: boolean;
+  message: string | undefined;
+}
+
+// default state
+const INITIAL_STATE = { hasError: false, isLoading: false, message: undefined };
+const LOADING_STATE = { hasError: false, isLoading: true, message: undefined };
+const ERROR_STATE = { hasError: true, isLoading: false };
+
+const resolveMaybeAsync = async <T>(
+  value: T | Promise<T>
+): Promise<Awaited<T>> => {
+  const awaited = await value;
+  return awaited;
+};
+
+export default function useDataState<T, K>(
+  action: (prevData: T, ...input: K[]) => T | Promise<T>,
+  initialData: T
+): [state: DataState<T>, handleAction: (...input: K[]) => void] {
+  const [dataState, setDataState] = React.useState<DataState<T>>(() => ({
+    ...INITIAL_STATE,
+    data: initialData,
+  }));
+
+  const prevData = React.useRef(initialData);
+
+  const handleAction: (...input: K[]) => void = React.useCallback(
+    (...input) => {
+      setDataState(({ data }) => ({ ...LOADING_STATE, data }));
+
+      resolveMaybeAsync(action(prevData.current, ...input))
+        .then((data: T) => {
+          prevData.current = data;
+          setDataState({ ...INITIAL_STATE, data });
+        })
+        .catch(({ message }: Error) => {
+          setDataState(({ data }) => ({ ...ERROR_STATE, data, message }));
+        });
+    },
+    [action]
+  );
+
+  return [dataState, handleAction];
+}