chore(gen2-storage): Update StorageImage API (aws-amplify#5171)

Co-authored-by: Caleb Pollman <[email protected]>

Author: esauerbo

.changeset/big-owls-nail.md

@@ -0,0 +1,8 @@
+---
+"@aws-amplify/ui-react-storage": minor
+"@aws-amplify/ui-react": patch
+---
+
+chore(gen2-storage): Update StorageImage API.
+
+Updates the StorageImage component to work with both gen1 and gen2 props. Accepts either `imgKey` or `path` props.

packages/react-storage/jest.config.ts

@@ -11,7 +11,7 @@ const config: Config = {
   ],
   coverageThreshold: {
     global: {
-      branches: 50,
+      branches: 85,
       functions: 87,
       lines: 93,
       statements: 93,

packages/react-storage/src/components/StorageImage/StorageImage.tsx

@@ -1,53 +1,101 @@
 import * as React from 'react';
 
-import { classNames, ComponentClassName, isUndefined } from '@aws-amplify/ui';
+import { classNames, ComponentClassName } from '@aws-amplify/ui';
 import { Image } from '@aws-amplify/ui-react';
-import { useStorageURL } from '@aws-amplify/ui-react/internal';
-import { useSetUserAgent } from '@aws-amplify/ui-react-core';
+import { useDeprecationWarning } from '@aws-amplify/ui-react/internal';
+import { useGetUrl, useSetUserAgent } from '@aws-amplify/ui-react-core';
 
 import { VERSION } from '../../version';
-import type { StorageImageProps } from './types';
+import type { StorageImageProps, StorageImagePathProps } from './types';
+
+export const MISSING_REQUIRED_PROP_MESSAGE =
+  '`StorageImage` requires either an `imgKey` or `path` prop.';
+
+export const HAS_DEPRECATED_PROPS_MESSAGE =
+  '`imgKey`, `accessLevel`, and `identityId` will be replaced with `path` in a future major version.';
+
+export const HAS_PATH_AND_KEY_MESSAGE =
+  '`imgKey` is ignored when both `imgKey` and `path` props are provided.';
+
+export const HAS_PATH_AND_UNSUPPORTED_OPTIONS_MESSAGE =
+  '``accessLevel` and `identityId` are ignored when the `path` prop is provided.';
+
+const getDeprecationMessage = ({
+  hasImgkey,
+  hasPath,
+  hasDeprecatedOptions,
+}: {
+  hasImgkey: boolean;
+  hasPath: boolean;
+  hasDeprecatedOptions: boolean;
+}): string => {
+  let message = '';
+
+  if (hasPath && hasImgkey) {
+    message = HAS_PATH_AND_KEY_MESSAGE;
+  } else if (hasPath && hasDeprecatedOptions) {
+    message = HAS_PATH_AND_UNSUPPORTED_OPTIONS_MESSAGE;
+  } else if (hasImgkey) {
+    message = HAS_DEPRECATED_PROPS_MESSAGE;
+  }
+
+  return message;
+};
 
 export const StorageImage = ({
   accessLevel,
   className,
   fallbackSrc,
   identityId,
   imgKey,
+  path,
   onStorageGetError,
-  validateObjectExistence,
+  onGetUrlError,
+  validateObjectExistence = true,
   ...rest
-}: StorageImageProps): JSX.Element => {
-  const resolvedValidateObjectExistence = isUndefined(validateObjectExistence)
-    ? true
-    : validateObjectExistence;
-  const options = React.useMemo(
-    () => ({
-      accessLevel,
-      targetIdentityId: identityId,
-      validateObjectExistence: resolvedValidateObjectExistence,
-    }),
-    [accessLevel, identityId, resolvedValidateObjectExistence]
-  );
+}: StorageImageProps | StorageImagePathProps): JSX.Element => {
+  const hasImgkey = !!imgKey;
+  const hasPath = !!path;
+  const hasDeprecatedOptions = !!accessLevel || !!identityId;
+
+  const message = getDeprecationMessage({
+    hasDeprecatedOptions,
+    hasImgkey,
+    hasPath,
+  });
+  useDeprecationWarning({ message, shouldWarn: !!message });
+
+  if (!hasImgkey && !hasPath) {
+    throw new Error(MISSING_REQUIRED_PROP_MESSAGE);
+  }
 
   useSetUserAgent({
     componentName: 'StorageImage',
     packageName: 'react-storage',
     version: VERSION,
   });
 
-  const url = useStorageURL({
-    key: imgKey,
-    options,
-    fallbackURL: fallbackSrc,
-    onStorageGetError,
-  });
+  const onError = onGetUrlError ?? onStorageGetError;
+  const input = React.useMemo(
+    () => ({
+      ...(path ? { path } : { key: imgKey! }), // if `path` is falsy `imgKey` exists
+      onError,
+      options: {
+        accessLevel,
+        targetIdentityId: identityId,
+        validateObjectExistence,
+      },
+    }),
+    [accessLevel, imgKey, identityId, onError, path, validateObjectExistence]
+  );
+
+  const { url } = useGetUrl(input);
 
   return (
     <Image
       {...rest}
       className={classNames(ComponentClassName.StorageImage, className)}
-      src={url}
+      src={url?.toString() ?? fallbackSrc}
     />
   );
 };