): BaseElement {
+ const { displayName, type } = input;
+
+ const Element = ({ variant, ...props }: Omit) => {
+ const Element = React.useContext(ElementsContext)?.[displayName];
+
+ if (Element) {
+ // only pass `variant` to provided `Element` values
+ return ;
+ }
+
+ return React.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
+ */
+export function defineBaseElementWithRef<
+ // 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 = ReactElementProps,
+ // control element props
+ P extends BaseElementWithRefProps = BaseElementWithRefProps,
+>(input: DefineBaseElementInput): BaseElementWithRef> {
const { displayName, type } = input;
const Element = React.forwardRef, P>(
diff --git a/packages/react-core/src/elements/index.ts b/packages/react-core/src/elements/index.ts
index b3bf08b7a45..712b05d57b1 100644
--- a/packages/react-core/src/elements/index.ts
+++ b/packages/react-core/src/elements/index.ts
@@ -1,3 +1,9 @@
-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';
diff --git a/packages/react-core/src/elements/types.ts b/packages/react-core/src/elements/types.ts
index a01057829cd..455ea5d752b 100644
--- a/packages/react-core/src/elements/types.ts
+++ b/packages/react-core/src/elements/types.ts
@@ -13,16 +13,31 @@ import React from 'react';
* are always optional at the interface level, allowing for additional `props`
* to be added to existing `BaseElement` interfaces as needed.
*/
-export type BaseElement = React.ForwardRefExoticComponent<
+export type BaseElement = (props: T) => React.JSX.Element;
+
+/**
+ * @internal @unstable
+ *
+ * see @type {BaseElement}
+ *
+ * `BaseElement` with a `ref` corresponding to the `element` type
+ */
+export type BaseElementWithRef<
+ T = {},
+ K = {},
+> = React.ForwardRefExoticComponent<
React.PropsWithoutRef & React.RefAttributes
>;
type ListElementSubType = 'Ordered' | 'Unordered';
-type ListElementDisplayName = 'List' | `${ListElementSubType}List`;
+type ListElementDisplayName = `${ListElementSubType}List`;
-type TableElementSubType = 'Body' | 'Data' | 'Row' | 'Head' | 'Header';
+type TableElementSubType = 'Body' | 'DataCell' | 'Row' | 'Head' | 'Header';
type TableElementDisplayName = 'Table' | `Table${TableElementSubType}`;
+type DescriptionElementSubType = 'Details' | 'List' | 'Term';
+type DescriptionElementDisplayName = `Description${DescriptionElementSubType}`;
+
/**
* @internal @unstable
*
@@ -30,7 +45,6 @@ type TableElementDisplayName = 'Table' | `Table${TableElementSubType}`;
*/
export type ElementDisplayName =
| 'Button'
- | 'Divider'
| 'Heading' // h1, h2, etc
| 'Icon'
| 'Image'
@@ -44,6 +58,7 @@ export type ElementDisplayName =
| 'TextArea'
| 'Title'
| 'View'
+ | DescriptionElementDisplayName
| ListElementDisplayName
| TableElementDisplayName;
@@ -68,7 +83,7 @@ export type ReactElementType = keyof React.JSX.IntrinsicElements;
* @internal @unstable
*/
export type ReactElementProps =
- React.JSX.IntrinsicElements[T];
+ React.ComponentProps;
/**
* @internal @unstable
@@ -85,5 +100,98 @@ export type BaseElementProps<
V = string,
K extends Record, any> = Record,
> = React.AriaAttributes &
- React.RefAttributes> &
+ React.Attributes &
Pick> & { testId?: string; variant?: V };
+
+/**
+ * @internal @unstable
+ */
+export type BaseElementWithRefProps<
+ T extends keyof K,
+ V = string,
+ K extends Record, any> = Record,
+> = BaseElementProps & React.RefAttributes>;
+
+/**
+ * @internal @unstable
+ */
+export type ElementWithAndWithoutRef<
+ T extends ReactElementType,
+ K extends React.ComponentType> = React.ComponentType<
+ React.ComponentProps
+ >,
+> = K extends React.ComponentType
+ ? React.ForwardRefExoticComponent
+ : never;
+
+/**
+ * @internal @unstable
+ *
+ * Merge `BaseElement` defintions with `elements` types provided by
+ * consumers, for use with top level connected component function
+ * signatures.
+ *
+ * Example:
+ *
+ * ```tsx
+ * export function createStorageBrowser<
+ * T extends Partial,
+ * >({ elements }: CreateStorageBrowserInput = {}): {
+ * StorageBrowser: StorageBrowser>
+ * } {
+ * // ...do create stuff
+ * };
+ * ```
+ */
+export type MergeBaseElements> = {
+ [U in keyof T]: K[U] extends T[U] ? K[U] : T[U];
+};
+
+/**
+ * @internal @unstable
+ *
+ * Extend the defintion of a `BaseElement` with additional `props`.
+ *
+ * Use cases are restricted to scenarios where additional `props`
+ * are required for a `ControlElement` interface, for example:
+ *
+ * @example
+ * ```tsx
+ * const FieldInput = defineBaseElementWithRef({
+ * type: 'input',
+ * displayName: 'Input'
+ * });
+ *
+ * type InputWithSearchCallback =
+ * ExtendBaseElement<
+ * typeof FieldInput,
+ * { onSearch?: (event: { value: string }) => void }
+ * >
+ *
+ * const SearchInput = React.forwardRef((
+ * { onSearch, ...props }
+ * ref
+ * ) => {
+ * // ...do something with onSearch
+ *
+ * return ;
+ * });
+ * ```
+ *
+ * Caveats:
+ * - additional `props` should not be passed directly to
+ * `BaseElement` components, the outputted interface should be
+ * applied to a wrapping element that handles the additional `props`
+ *
+ * - additional `props` that share a key with existing `props`
+ * are omitted from the outputted interface to adhere to `BaseElement`
+ * type contracts
+ *
+ */
+export type ExtendBaseElement<
+ // `BaseElement` to extend
+ T extends React.ComponentType,
+ // additional `props`
+ K = {},
+ U extends React.ComponentPropsWithRef = React.ComponentPropsWithRef,
+> = BaseElementWithRef, U>;
diff --git a/packages/react-core/src/elements/utils.ts b/packages/react-core/src/elements/utils.ts
new file mode 100644
index 00000000000..aebab72b2a8
--- /dev/null
+++ b/packages/react-core/src/elements/utils.ts
@@ -0,0 +1,20 @@
+import React from 'react';
+
+export function isComponent(
+ component?: React.ComponentType | React.ForwardRefExoticComponent
+): component is React.ComponentType {
+ return typeof component === 'function';
+}
+
+export function isForwardRefExoticComponent(
+ component: React.ComponentType | React.ForwardRefExoticComponent
+): component is React.ForwardRefExoticComponent {
+ return (
+ typeof component === 'object' &&
+ typeof (component as React.ForwardRefExoticComponent).$$typeof ===
+ 'symbol' &&
+ ['react.memo', 'react.forward_ref'].includes(
+ (component as React.ForwardRefExoticComponent).$$typeof.description!
+ )
+ );
+}
diff --git a/packages/react-core/src/elements/withBaseElementProps.tsx b/packages/react-core/src/elements/withBaseElementProps.tsx
index 4389fd35d01..4ac9708e80b 100644
--- a/packages/react-core/src/elements/withBaseElementProps.tsx
+++ b/packages/react-core/src/elements/withBaseElementProps.tsx
@@ -1,5 +1,5 @@
import React from 'react';
-import { BaseElement, ElementRefType } from './types';
+import { BaseElementWithRef, ElementRefType } from './types';
/**
* @internal @unstable
@@ -16,7 +16,7 @@ import { BaseElement, ElementRefType } from './types';
* 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",
* });
@@ -38,7 +38,7 @@ export default function withBaseElementProps<
>(
Target: React.ForwardRefExoticComponent,
defaultProps: K
-): BaseElement> {
+): BaseElementWithRef> {
const Component = React.forwardRef, T>((props, ref) => (
@@ -6,19 +6,26 @@ const asyncAction = jest.fn((_prev: string, next: string) =>
);
const syncAction = jest.fn((_prev: string, next: string) => next);
+const errorMessage = 'Unhappy!';
+const unhappyAction = jest.fn((_, isUnhappy: boolean) =>
+ isUnhappy ? Promise.reject(new Error(errorMessage)) : Promise.resolve()
+);
+
+const initData = 'initial-data';
+const nextData = 'next-data';
+
describe('useDataState', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
it.each([
{ type: 'async', action: asyncAction },
{ type: 'sync', action: syncAction },
])(
'handles a $type action as expected in the happy path',
async ({ action }) => {
- const initData = 'initial-data';
- const nextData = 'next-data';
-
- const { result, waitForNextUpdate } = renderHook(() =>
- useDataState(action, 'initial-data')
- );
+ const { result } = renderHook(() => useDataState(action, initData));
// first render
const [initState, handleAction] = result.current;
@@ -46,31 +53,71 @@ describe('useDataState', () => {
expect(loadingState.isLoading).toBe(true);
expect(loadingState.message).toBeUndefined();
- await waitForNextUpdate();
-
- // action complete
- const [nextState] = result.current;
+ await waitFor(() => {
+ // action complete
+ const [nextState] = result.current;
- expect(action).toHaveBeenCalledTimes(1);
- expect(action).toHaveBeenCalledWith(initData, nextData);
+ expect(action).toHaveBeenCalledTimes(1);
+ expect(action).toHaveBeenCalledWith(initData, nextData);
- expect(nextState.data).toBe(nextData);
- expect(nextState.hasError).toBe(false);
- expect(nextState.isLoading).toBe(false);
- expect(nextState.message).toBeUndefined();
+ expect(nextState.data).toBe(nextData);
+ expect(nextState.hasError).toBe(false);
+ expect(nextState.isLoading).toBe(false);
+ expect(nextState.message).toBeUndefined();
+ });
}
);
- it('handles an error and resets error state on the next call to handleAction', async () => {
- const errorMessage = 'Unhappy!';
- const unhappyAction = jest.fn((_, isUnhappy: boolean) =>
- isUnhappy ? Promise.reject(new Error(errorMessage)) : Promise.resolve()
+ it('calls `onSuccess` callback as expected', async () => {
+ const onSuccess = jest.fn();
+ const { result } = renderHook(() =>
+ useDataState(asyncAction, initData, { onSuccess })
);
- const { result, waitForNextUpdate } = renderHook(() =>
- useDataState(unhappyAction, undefined)
+ // first render
+ const [_, handleAction] = result.current;
+
+ // call action
+ act(() => {
+ handleAction(nextData);
+ });
+
+ await waitFor(() => {
+ expect(asyncAction).toHaveBeenCalledTimes(1);
+ expect(asyncAction).toHaveBeenCalledWith(initData, nextData);
+ });
+
+ expect(onSuccess).toHaveBeenCalledTimes(1);
+ expect(onSuccess).toHaveBeenCalledWith(nextData);
+ });
+
+ it('calls `onError` callback as expected', async () => {
+ const onError = jest.fn();
+ const { result } = renderHook(() =>
+ useDataState(unhappyAction, undefined, { onError })
);
+ const [_, handleAction] = result.current;
+
+ act(() => {
+ handleAction(true);
+ });
+
+ await waitFor(() => {
+ const [errorState] = result.current;
+
+ expect(errorState.hasError).toBe(true);
+ expect(errorState.isLoading).toBe(false);
+ expect(errorState.message).toBe(errorMessage);
+ });
+
+ expect(onError).toHaveBeenCalledTimes(1);
+ expect(onError).toHaveBeenCalledWith(errorMessage);
+ });
+
+ it('handles an error and resets error state on the next call to handleAction', async () => {
+ const { result } = renderHook(() => useDataState(unhappyAction, undefined));
+
const [initialState, handleAction] = result.current;
expect(unhappyAction).not.toHaveBeenCalled();
@@ -89,26 +136,25 @@ describe('useDataState', () => {
expect(loadingState.isLoading).toBe(true);
expect(loadingState.message).toBeUndefined();
- await waitForNextUpdate();
+ await waitFor(() => {
+ const [errorState] = result.current;
- const [errorState] = result.current;
-
- expect(errorState.hasError).toBe(true);
- expect(errorState.isLoading).toBe(false);
- expect(errorState.message).toBe(errorMessage);
+ expect(errorState.hasError).toBe(true);
+ expect(errorState.isLoading).toBe(false);
+ expect(errorState.message).toBe(errorMessage);
+ });
act(() => {
handleAction(false);
});
- const [nextLoadingState] = result.current;
+ await waitFor(() => {
+ const [nextLoadingState] = result.current;
- expect(nextLoadingState.hasError).toBe(false);
- expect(nextLoadingState.isLoading).toBe(true);
- expect(nextLoadingState.message).toBeUndefined();
-
- // cleanup
- await waitForNextUpdate();
+ expect(nextLoadingState.hasError).toBe(false);
+ expect(nextLoadingState.isLoading).toBe(true);
+ expect(nextLoadingState.message).toBeUndefined();
+ });
});
it.todo('only returns the value of the last call to handleAction');
diff --git a/packages/react-core/src/hooks/index.ts b/packages/react-core/src/hooks/index.ts
index b941809a63e..5eb30109f0a 100644
--- a/packages/react-core/src/hooks/index.ts
+++ b/packages/react-core/src/hooks/index.ts
@@ -1,4 +1,9 @@
-export { default as useDataState, DataState } from './useDataState';
+export {
+ default as useDataState,
+ AsyncDataAction,
+ DataAction,
+ DataState,
+} from './useDataState';
export {
default as useDeprecationWarning,
diff --git a/packages/react-core/src/hooks/useDataState.ts b/packages/react-core/src/hooks/useDataState.ts
index 7ccece3630d..986d64468ac 100644
--- a/packages/react-core/src/hooks/useDataState.ts
+++ b/packages/react-core/src/hooks/useDataState.ts
@@ -1,3 +1,4 @@
+import { isFunction } from '@aws-amplify/ui';
import React from 'react';
export interface DataState {
@@ -7,6 +8,13 @@ export interface DataState {
message: string | undefined;
}
+export type DataAction = (prevData: T, input: K) => T;
+
+export type AsyncDataAction = (
+ prevData: T,
+ input: K
+) => Promise;
+
// default state
const INITIAL_STATE = { hasError: false, isLoading: false, message: undefined };
const LOADING_STATE = { hasError: false, isLoading: true, message: undefined };
@@ -20,9 +28,13 @@ const resolveMaybeAsync = async (
};
export default function useDataState(
- action: (prevData: T, ...input: K[]) => T | Promise,
- initialData: T
-): [state: DataState, handleAction: (...input: K[]) => void] {
+ action: DataAction | AsyncDataAction,
+ initialData: T,
+ options?: {
+ onSuccess?: (data: T) => void;
+ onError?: (message: string) => void;
+ }
+): [state: DataState, handleAction: (input: K) => void] {
const [dataState, setDataState] = React.useState>(() => ({
...INITIAL_STATE,
data: initialData,
@@ -30,20 +42,26 @@ export default function useDataState(
const prevData = React.useRef(initialData);
- const handleAction: (...input: K[]) => void = React.useCallback(
- (...input) => {
+ const { onSuccess, onError } = options ?? {};
+
+ const handleAction: (input: K) => void = React.useCallback(
+ (input) => {
setDataState(({ data }) => ({ ...LOADING_STATE, data }));
- resolveMaybeAsync(action(prevData.current, ...input))
+ resolveMaybeAsync(action(prevData.current, input))
.then((data: T) => {
+ if (isFunction(onSuccess)) onSuccess(data);
+
prevData.current = data;
setDataState({ ...INITIAL_STATE, data });
})
.catch(({ message }: Error) => {
+ if (isFunction(onError)) onError(message);
+
setDataState(({ data }) => ({ ...ERROR_STATE, data, message }));
});
},
- [action]
+ [action, onError, onSuccess]
);
return [dataState, handleAction];
diff --git a/packages/react-core/src/index.ts b/packages/react-core/src/index.ts
index c445ae0c8a3..ebe4e012b38 100644
--- a/packages/react-core/src/index.ts
+++ b/packages/react-core/src/index.ts
@@ -35,6 +35,8 @@ export {
} from './components';
export {
+ AsyncDataAction,
+ DataAction,
useDeprecationWarning,
UseDeprecationWarning,
useGetUrl,
diff --git a/packages/react-core/src/utils/createContextUtilities.tsx b/packages/react-core/src/utils/createContextUtilities.tsx
index 77d2975e35d..5df48495451 100644
--- a/packages/react-core/src/utils/createContextUtilities.tsx
+++ b/packages/react-core/src/utils/createContextUtilities.tsx
@@ -36,7 +36,7 @@ type CreateContextUtilitiesReturn = {
: Key extends `use${string}`
? (params?: HookParams) => ContextType
: Key extends `${string}Context`
- ? React.Context
+ ? React.Context
: never;
};
@@ -89,7 +89,7 @@ type CreateContextUtilitiesReturn = {
export default function createContextUtilities<
ContextType,
ContextName extends string = string,
- Message extends string | undefined = string | undefined
+ Message extends string | undefined = string | undefined,
>(
options: ContextOptions
): CreateContextUtilitiesReturn {
@@ -99,7 +99,11 @@ export default function createContextUtilities<
throw new Error(INVALID_OPTIONS_MESSAGE);
}
+ const contextDisplayName = `${contextName}Context`;
+ const providerDisplayName = `${contextName}Provider`;
+
const Context = React.createContext(defaultValue);
+ Context.displayName = contextDisplayName;
function Provider(props: React.PropsWithChildren) {
const { children, ...context } = props;
@@ -113,8 +117,7 @@ export default function createContextUtilities<
return {children};
}
- Provider.displayName = `${contextName}Provider`;
-
+ Provider.displayName = providerDisplayName;
return {
[`use${contextName}`]: function (params?: HookParams) {
const context = React.useContext(Context);
@@ -125,7 +128,7 @@ export default function createContextUtilities<
return context;
},
- [`${contextName}Provider`]: Provider,
- [`${contextName}Context`]: Context,
+ [providerDisplayName]: Provider,
+ [contextDisplayName]: Context,
} as CreateContextUtilitiesReturn;
}
diff --git a/packages/react-geo/package.json b/packages/react-geo/package.json
index cdfca551800..8b4b7653f31 100644
--- a/packages/react-geo/package.json
+++ b/packages/react-geo/package.json
@@ -47,13 +47,13 @@
"tslib": "^2.5.2"
},
"peerDependencies": {
- "@aws-amplify/geo": "^3.0.47",
- "aws-amplify": "^6.6.5",
+ "@aws-amplify/geo": "unstable",
+ "aws-amplify": "unstable",
"react": "^16.14.0 || ^17.0 || ^18.0",
"react-dom": "^16.14.0 || ^17.0 || ^18.0"
},
"devDependencies": {
- "@aws-amplify/geo": "^3.0.40",
+ "@aws-amplify/geo": "unstable",
"@types/mapbox__mapbox-gl-draw": "^1.3.3"
},
"sideEffects": [
diff --git a/packages/react-liveness/package.json b/packages/react-liveness/package.json
index 29c34c99010..29f563a239e 100644
--- a/packages/react-liveness/package.json
+++ b/packages/react-liveness/package.json
@@ -43,7 +43,7 @@
},
"peerDependencies": {
"@aws-amplify/core": "*",
- "aws-amplify": "^6.6.5",
+ "aws-amplify": "unstable",
"react": "^16.14.0 || ^17.0 || ^18.0",
"react-dom": "^16.14.0 || ^17.0 || ^18.0"
},
diff --git a/packages/react-native-auth/package.json b/packages/react-native-auth/package.json
index e45f2b7504c..0ff5f00d88e 100644
--- a/packages/react-native-auth/package.json
+++ b/packages/react-native-auth/package.json
@@ -34,7 +34,7 @@
"qrcode": "1.5.0"
},
"peerDependencies": {
- "aws-amplify": "^6.6.5",
+ "aws-amplify": "unstable",
"react": "^18",
"react-native": "^0.70 || ^0.71 || ^0.72"
},
diff --git a/packages/react-native/package.json b/packages/react-native/package.json
index bc3737fc165..2baa81e747a 100644
--- a/packages/react-native/package.json
+++ b/packages/react-native/package.json
@@ -35,7 +35,7 @@
"@aws-amplify/ui-react-core-notifications": "2.0.30"
},
"peerDependencies": {
- "aws-amplify": "^6.6.5",
+ "aws-amplify": "unstable",
"react": "*",
"react-native": "^0.70 || ^0.71 || ^0.72 || ^0.73 || ^0.74 || ^0.75",
"react-native-safe-area-context": "^4.2.5"
diff --git a/packages/react-notifications/package.json b/packages/react-notifications/package.json
index 2aec8732146..41f371bfad5 100644
--- a/packages/react-notifications/package.json
+++ b/packages/react-notifications/package.json
@@ -46,7 +46,7 @@
"tinycolor2": "1.4.2"
},
"peerDependencies": {
- "aws-amplify": "^6.6.5",
+ "aws-amplify": "unstable",
"react": "^16.14.0 || ^17.0 || ^18.0",
"react-dom": "^16.14.0 || ^17.0 || ^18.0"
},
diff --git a/packages/react-storage/browser/package.json b/packages/react-storage/browser/package.json
new file mode 100644
index 00000000000..0c783973601
--- /dev/null
+++ b/packages/react-storage/browser/package.json
@@ -0,0 +1,8 @@
+{
+ "name": "@aws-amplify/ui-react-storage/browser",
+ "main": "../dist/browser.js",
+ "module": "../dist/esm/browser.mjs",
+ "types": "../dist/types/components/StorageBrowser/index.d.ts",
+ "private": true,
+ "sideEffects": false
+}
diff --git a/packages/react-storage/jest.config.ts b/packages/react-storage/jest.config.ts
index 09a528f0a3f..294793ecdc1 100644
--- a/packages/react-storage/jest.config.ts
+++ b/packages/react-storage/jest.config.ts
@@ -4,21 +4,30 @@ const config: Config = {
collectCoverage: true,
collectCoverageFrom: [
'/src/**/*.(ts|tsx)',
- // do not collect from export files
- '!/**/index.(ts|tsx)',
- // do not collect from top level version and styles files
- '!/src/(styles|version).(ts|tsx)',
+ // do not collect from index, testUtils or version files
+ '!/**/(index|version).(ts|tsx)',
+ // do not collect from top level styles directory
+ '!/src/styles/*.ts',
],
coverageThreshold: {
global: {
- branches: 87,
- functions: 86.5,
- lines: 93.5,
+ // TEMP REDUCE COVERAGE
+ // branches: 87,
+ // functions: 90,
+ // lines: 95,
+ // statements: 95,
+ branches: 84,
+ functions: 88,
+ lines: 94,
statements: 94,
},
},
moduleNameMapper: { '^uuid$': '/../../node_modules/uuid' },
- modulePathIgnorePatterns: ['/dist/'],
+ modulePathIgnorePatterns: ['c/dist/'],
+ testPathIgnorePatterns: [
+ '/src/components/StorageBrowser/displayText/libraries/en/__tests__/scenarios.ts',
+ '__testUtils__/',
+ ],
preset: 'ts-jest',
setupFilesAfterEnv: ['./jest.setup.ts'],
testEnvironment: 'jsdom',
diff --git a/packages/react-storage/package.json b/packages/react-storage/package.json
index 458f89b14ba..9a509efe9a1 100644
--- a/packages/react-storage/package.json
+++ b/packages/react-storage/package.json
@@ -9,10 +9,17 @@
"import": "./dist/esm/index.mjs",
"require": "./dist/index.js"
},
- "./styles.css": "./dist/styles.css"
+ "./browser": {
+ "main": "./dist/browser.js",
+ "types": "./dist/types/components/StorageBrowser/index.d.ts",
+ "import": "./dist/esm/browser.mjs"
+ },
+ "./styles.css": "./dist/styles.css",
+ "./storage-browser-styles.css": "./dist/storage-browser-styles.css"
},
"browser": {
- "./styles.css": "./dist/styles.css"
+ "./styles.css": "./dist/styles.css",
+ "./storage-browser-styles.css": "./dist/storage-browser-styles.css"
},
"types": "dist/types/index.d.ts",
"license": "Apache-2.0",
@@ -23,7 +30,8 @@
},
"files": [
"dist",
- "LICENSE"
+ "LICENSE",
+ "browser"
],
"scripts": {
"build": "yarn build:rollup",
@@ -45,14 +53,28 @@
"tslib": "^2.5.2"
},
"peerDependencies": {
- "aws-amplify": "^6.6.5",
+ "aws-amplify": "unstable",
"react": "^16.14.0 || ^17.0 || ^18.0",
"react-dom": "^16.14.0 || ^17.0 || ^18.0"
},
+ "devDependencies": {
+ "jest-tsd": "^0.2.2",
+ "@tsd/typescript": "^5.1.6",
+ "@types/node": "^18.19.50"
+ },
"sideEffects": [
"dist/**/*.css"
],
"size-limit": [
+ {
+ "name": "createStorageBrowser",
+ "path": "dist/esm/browser.mjs",
+ "import": "{ createStorageBrowser }",
+ "limit": "60 kB",
+ "ignore": [
+ "@aws-amplify/storage"
+ ]
+ },
{
"name": "FileUploader",
"path": "dist/esm/index.mjs",
diff --git a/packages/react-storage/rollup.config.mjs b/packages/react-storage/rollup.config.mjs
index ca3323488ed..46760e761d8 100644
--- a/packages/react-storage/rollup.config.mjs
+++ b/packages/react-storage/rollup.config.mjs
@@ -4,7 +4,10 @@ import styles from 'rollup-plugin-styles';
import externals from 'rollup-plugin-node-externals';
// common config settings
-const input = ['src/index.ts'];
+const input = {
+ index: 'src/index.ts',
+ browser: 'src/components/StorageBrowser/index.ts',
+};
const sourceMap = false;
const tsconfig = 'tsconfig.dist.json';
@@ -51,8 +54,21 @@ const config = defineConfig([
},
// CSS config
{
- input: 'src/styles.ts',
- output: { dir: 'dist', format: 'cjs', assetFileNames: '[name][extname]' },
+ input: 'src/styles/styles.ts',
+ output: {
+ dir: 'dist',
+ format: 'cjs',
+ assetFileNames: '[name][extname]',
+ },
+ plugins: [styles({ mode: ['extract'] })],
+ },
+ {
+ input: 'src/styles/storage-browser-styles.ts',
+ output: {
+ dir: 'dist',
+ format: 'cjs',
+ assetFileNames: '[name][extname]',
+ },
plugins: [styles({ mode: ['extract'] })],
},
]);
diff --git a/packages/react-storage/src/__tests__/__snapshots__/exports.spec.ts.snap b/packages/react-storage/src/__tests__/__snapshots__/exports.spec.ts.snap
new file mode 100644
index 00000000000..ae89c4d72b4
--- /dev/null
+++ b/packages/react-storage/src/__tests__/__snapshots__/exports.spec.ts.snap
@@ -0,0 +1,19 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`@aws-amplify/ui-react-storage exports should match snapshot 1`] = `
+[
+ "FileUploader",
+ "StorageBrowser",
+ "StorageImage",
+ "StorageManager",
+]
+`;
+
+exports[`@aws-amplify/ui-react-storage/browser exports should match snapshot 1`] = `
+[
+ "componentsDefault",
+ "createAmplifyAuthAdapter",
+ "createManagedAuthAdapter",
+ "createStorageBrowser",
+]
+`;
diff --git a/packages/react-storage/src/__tests__/exports.spec.ts b/packages/react-storage/src/__tests__/exports.spec.ts
new file mode 100644
index 00000000000..790f48489b4
--- /dev/null
+++ b/packages/react-storage/src/__tests__/exports.spec.ts
@@ -0,0 +1,22 @@
+import * as exported from '../';
+import * as browser from '../../browser';
+
+describe('@aws-amplify/ui-react-storage', () => {
+ describe('exports', () => {
+ it('should match snapshot', () => {
+ const sortedExports = Object.keys(exported).sort();
+
+ expect(sortedExports).toMatchSnapshot();
+ });
+ });
+});
+
+describe('@aws-amplify/ui-react-storage/browser', () => {
+ describe('exports', () => {
+ it('should match snapshot', () => {
+ const sortedBrowserExports = Object.keys(browser).sort();
+
+ expect(sortedBrowserExports).toMatchSnapshot();
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/ComponentsProvider.tsx b/packages/react-storage/src/components/StorageBrowser/ComponentsProvider.tsx
new file mode 100644
index 00000000000..3548bff11dd
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/ComponentsProvider.tsx
@@ -0,0 +1,28 @@
+import React from 'react';
+
+import { ElementsProvider } from '@aws-amplify/ui-react-core/elements';
+
+import { ComposablesProvider, Composables } from './composables';
+import { StorageBrowserElements } from './context/elements';
+
+export interface Components extends Partial {}
+
+export interface ComponentsProviderProps {
+ children?: React.ReactNode;
+ composables?: Composables;
+ elements?: Partial;
+}
+
+export function ComponentsProvider(
+ props: ComponentsProviderProps
+): React.JSX.Element {
+ const { children, composables, elements } = props;
+
+ return (
+
+
+ {children}
+
+
+ );
+}
diff --git a/packages/react-storage/src/components/StorageBrowser/ErrorBoundary/ErrorBoundary.tsx b/packages/react-storage/src/components/StorageBrowser/ErrorBoundary/ErrorBoundary.tsx
new file mode 100644
index 00000000000..312e551fef1
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/ErrorBoundary/ErrorBoundary.tsx
@@ -0,0 +1,44 @@
+import React from 'react';
+
+import { STORAGE_BROWSER_BLOCK_TO_BE_UPDATED } from '../constants';
+
+interface ErrorBoundaryProps {
+ children: React.ReactNode;
+}
+
+interface ErrorBoundaryState {
+ hasError: boolean;
+}
+
+const Fallback = (): React.JSX.Element => (
+
+
+ Something went wrong.
+
+
This should throw an error
;
+};
+
+describe('ErrorBoundary', () => {
+ it('should render the fallback component when an error is thrown', () => {
+ // Mock implementation for console.error to prevent logging during tests
+ jest.spyOn(console, 'error').mockImplementation(() => null);
+
+ render(
+
+
+
+ );
+
+ expect(screen.getByText('Something went wrong.')).toBeInTheDocument();
+ });
+
+ it('should render children when no error is thrown', () => {
+ render(
+
+ No error here
+
+ );
+
+ expect(screen.getByText('No error here')).toBeInTheDocument();
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/ErrorBoundary/index.ts b/packages/react-storage/src/components/StorageBrowser/ErrorBoundary/index.ts
new file mode 100644
index 00000000000..8d337a3dcc4
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/ErrorBoundary/index.ts
@@ -0,0 +1 @@
+export { ErrorBoundary } from './ErrorBoundary';
diff --git a/packages/react-storage/src/components/StorageBrowser/StorageBrowserAmplify.tsx b/packages/react-storage/src/components/StorageBrowser/StorageBrowserAmplify.tsx
new file mode 100644
index 00000000000..db84a3de1ee
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/StorageBrowserAmplify.tsx
@@ -0,0 +1,22 @@
+import React from 'react';
+
+import { createStorageBrowser } from './createStorageBrowser';
+import { StorageBrowserProps as StorageBrowserPropsBase } from './types';
+import { createAmplifyAuthAdapter } from './adapters';
+import { componentsDefault } from './componentsDefault';
+
+export interface StorageBrowserProps extends StorageBrowserPropsBase {}
+
+export const StorageBrowser = ({
+ views,
+ displayText,
+}: StorageBrowserProps): React.JSX.Element => {
+ const { StorageBrowser } = React.useRef(
+ createStorageBrowser({
+ components: componentsDefault,
+ config: createAmplifyAuthAdapter(),
+ })
+ ).current;
+
+ return ;
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/StorageBrowserDefault.tsx b/packages/react-storage/src/components/StorageBrowser/StorageBrowserDefault.tsx
new file mode 100644
index 00000000000..cf74af8127f
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/StorageBrowserDefault.tsx
@@ -0,0 +1,27 @@
+import React from 'react';
+
+import { useViews } from './views';
+import { useStore } from './providers/store';
+
+/**
+ * Handles default `StorageBrowser` behavior:
+ * - render `LocationsView` on init
+ * - render `LocationDetailView` on location selection
+ * - render `ActionView` on action selection
+ */
+export function StorageBrowserDefault(): React.JSX.Element {
+ const { LocationActionView, LocationDetailView, LocationsView } = useViews();
+
+ const [{ actionType, location }] = useStore();
+ const { current } = location;
+
+ if (actionType) {
+ return ;
+ }
+
+ if (current) {
+ return ;
+ }
+
+ return ;
+}
diff --git a/packages/react-storage/src/components/StorageBrowser/__tests__/StorageBrowserAmplify.spec.tsx b/packages/react-storage/src/components/StorageBrowser/__tests__/StorageBrowserAmplify.spec.tsx
new file mode 100644
index 00000000000..5d6b33b7440
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/__tests__/StorageBrowserAmplify.spec.tsx
@@ -0,0 +1,58 @@
+import React from 'react';
+import { render, waitFor, screen } from '@testing-library/react';
+import { Amplify } from 'aws-amplify';
+import * as CreateStorageBrowserModule from '../createStorageBrowser';
+import * as CreateAmplifyAuthAdapter from '../adapters/createAmplifyAuthAdapter';
+import { StorageBrowser } from '../StorageBrowserAmplify';
+import { StorageBrowserDisplayText } from '../displayText/types';
+
+const createStorageBrowserSpy = jest.spyOn(
+ CreateStorageBrowserModule,
+ 'createStorageBrowser'
+);
+
+jest.spyOn(Amplify, 'getConfig').mockReturnValue({
+ Storage: {
+ S3: {
+ bucket: 'XXXXXX',
+ region: 'region',
+ },
+ },
+});
+
+const createAmplifyAuthAdapterSpy = jest.spyOn(
+ CreateAmplifyAuthAdapter,
+ 'createAmplifyAuthAdapter'
+);
+
+describe('StorageBrowser', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+ it('calls `createStorageBrowser`', async () => {
+ await waitFor(() => {
+ render();
+ });
+
+ expect(createStorageBrowserSpy).toHaveBeenCalledTimes(1);
+ expect(createStorageBrowserSpy).toHaveBeenCalledWith({
+ components: expect.anything(),
+ config: expect.anything(),
+ });
+
+ expect(createAmplifyAuthAdapterSpy).toHaveBeenCalledTimes(1);
+ });
+
+ it('support passing custom displayText', async () => {
+ const displayText: StorageBrowserDisplayText = {
+ LocationsView: { title: 'Hello' },
+ };
+
+ await waitFor(() => {
+ render();
+ });
+
+ const Title = screen.getByText('Hello');
+ expect(Title).toBeInTheDocument();
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/__tests__/StorageBrowserDefault.spec.tsx b/packages/react-storage/src/components/StorageBrowser/__tests__/StorageBrowserDefault.spec.tsx
new file mode 100644
index 00000000000..b3e24e3c09f
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/__tests__/StorageBrowserDefault.spec.tsx
@@ -0,0 +1,67 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import * as StoreModule from '../providers/store';
+import * as ViewsModule from '../views/context';
+import { StorageBrowserDefault } from '../StorageBrowserDefault';
+import { LocationData } from '../actions';
+
+jest.spyOn(ViewsModule, 'useViews').mockReturnValue({
+ LocationsView: () => ,
+ LocationDetailView: () => ,
+ LocationActionView: () => ,
+});
+
+const useStoreSpy = jest.spyOn(StoreModule, 'useStore');
+
+const location: LocationData = {
+ id: 'an-id-👍🏼',
+ bucket: 'test-bucket',
+ permissions: ['list'],
+ prefix: 'test-prefix/',
+ type: 'PREFIX',
+};
+
+describe('StorageBrowserDefault', () => {
+ afterEach(jest.clearAllMocks);
+
+ it('renders the `LocationsView` by default', () => {
+ useStoreSpy.mockReturnValueOnce([
+ {
+ actionType: undefined,
+ location: { current: undefined },
+ } as StoreModule.UseStoreState,
+ jest.fn(),
+ ]);
+ const { getByTestId } = render();
+
+ expect(getByTestId('LOCATIONS_VIEW')).toBeInTheDocument();
+ });
+
+ it('renders the `LocationDetailView` when a location is selected', () => {
+ useStoreSpy.mockReturnValueOnce([
+ {
+ actionType: undefined,
+ location: { current: location },
+ } as StoreModule.UseStoreState,
+ jest.fn(),
+ ]);
+
+ const { getByTestId } = render();
+
+ expect(getByTestId('LOCATION_DETAIL_VIEW')).toBeInTheDocument();
+ });
+
+ it('renders the `LocationActionView` when an action is selected', () => {
+ useStoreSpy.mockReturnValueOnce([
+ {
+ actionType: 'super-coll-action-type',
+ location: { current: location },
+ } as StoreModule.UseStoreState,
+ jest.fn(),
+ ]);
+ const { getByTestId } = render();
+
+ expect(getByTestId('LOCATION_ACTION_VIEW')).toBeInTheDocument();
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/__tests__/createStorageBrowser.spec.tsx b/packages/react-storage/src/components/StorageBrowser/__tests__/createStorageBrowser.spec.tsx
new file mode 100644
index 00000000000..bfb6c7fbea3
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/__tests__/createStorageBrowser.spec.tsx
@@ -0,0 +1,82 @@
+import React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+
+import * as ProvidersModule from '../providers';
+
+import { createStorageBrowser } from '../createStorageBrowser';
+import { StorageBrowserDisplayText } from '../displayText/types';
+
+const createConfigurationProviderSpy = jest.spyOn(
+ ProvidersModule,
+ 'createConfigurationProvider'
+);
+
+const accountId = '012345678901';
+const customEndpoint = 'mock-endpoint';
+const getLocationCredentials = jest.fn();
+const listLocations = jest.fn();
+const region = 'region';
+
+const config = {
+ accountId,
+ customEndpoint,
+ getLocationCredentials,
+ listLocations,
+ region,
+ registerAuthListener: jest.fn(),
+};
+
+const input = { config };
+
+describe('createStorageBrowser', () => {
+ it('throws when registerAuthListener is not a function', () => {
+ const input = {
+ config: { getLocationCredentials, listLocations, region },
+ };
+
+ // @ts-expect-error intentionally omit registerAuthListener
+ expect(() => createStorageBrowser(input)).toThrow(
+ 'StorageBrowser: `registerAuthListener` must be a function.'
+ );
+ });
+
+ it('renders the `LocationsView` by default', async () => {
+ const { StorageBrowser } = createStorageBrowser(input);
+
+ await waitFor(() => {
+ render();
+ });
+
+ expect(screen.getByTestId('LOCATIONS_VIEW')).toBeInTheDocument();
+
+ expect(createConfigurationProviderSpy).toHaveBeenCalledWith({
+ accountId: config.accountId,
+ displayName: 'ConfigurationProvider',
+ customEndpoint: config.customEndpoint,
+ getLocationCredentials: config.getLocationCredentials,
+ region: config.region,
+ registerAuthListener: config.registerAuthListener,
+ actions: {
+ copy: expect.any(Object),
+ createFolder: expect.any(Object),
+ delete: expect.any(Object),
+ listLocationItems: expect.any(Object),
+ listLocations: expect.any(Object),
+ upload: expect.any(Object),
+ },
+ });
+ });
+
+ it('support passing custom displayText', async () => {
+ const { StorageBrowser } = createStorageBrowser(input);
+ const displayText: StorageBrowserDisplayText = {
+ LocationsView: { title: 'Hello' },
+ };
+ await waitFor(() => {
+ render();
+ });
+
+ const Title = screen.getByText('Hello');
+ expect(Title).toBeInTheDocument();
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/__testUtils__/permissions.ts b/packages/react-storage/src/components/StorageBrowser/actions/__testUtils__/permissions.ts
new file mode 100644
index 00000000000..57a52f71c4d
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/__testUtils__/permissions.ts
@@ -0,0 +1,20 @@
+import { LocationPermissions } from '../handlers';
+
+export const generateCombinations = (values: T[]): T[][] => {
+ if (values.length === 1) {
+ return [values];
+ }
+
+ const [first, ...rest] = values;
+ const restPermutations = generateCombinations(rest);
+
+ const firstPermutations = restPermutations.map((value) => [first, ...value]);
+ return [...restPermutations, ...firstPermutations, [first]];
+};
+
+export const LOCATION_PERMISSION_VALUES: LocationPermissions = [
+ 'get',
+ 'list',
+ 'delete',
+ 'write',
+];
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/__snapshots__/defaults.spec.ts.snap b/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/__snapshots__/defaults.spec.ts.snap
new file mode 100644
index 00000000000..d2894ca6058
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/__snapshots__/defaults.spec.ts.snap
@@ -0,0 +1,64 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`defaultActionConfigs matches expected shape 1`] = `
+{
+ "copy": {
+ "actionsListItemConfig": {
+ "disable": [Function],
+ "hide": [Function],
+ "icon": "copy-file",
+ "label": "Copy",
+ },
+ "componentName": "CopyView",
+ "displayName": "Copy",
+ "handler": [Function],
+ },
+ "createFolder": {
+ "actionsListItemConfig": {
+ "disable": [Function],
+ "hide": [Function],
+ "icon": "create-folder",
+ "label": "Create folder",
+ },
+ "componentName": "CreateFolderView",
+ "displayName": "Create Folder",
+ "handler": [Function],
+ "isCancelable": false,
+ },
+ "delete": {
+ "actionsListItemConfig": {
+ "disable": [Function],
+ "hide": [Function],
+ "icon": "delete-file",
+ "label": "Delete",
+ },
+ "componentName": "DeleteView",
+ "displayName": "Delete",
+ "handler": [Function],
+ },
+ "listLocationItems": {
+ "componentName": "LocationDetailView",
+ "displayName": [Function],
+ "handler": [Function],
+ },
+ "listLocations": {
+ "componentName": "LocationsView",
+ "displayName": "Home",
+ "handler": [Function],
+ },
+ "upload": {
+ "actionsListItemConfig": {
+ "disable": [Function],
+ "fileSelection": "FILE",
+ "hide": [Function],
+ "icon": "upload-file",
+ "label": "Upload",
+ },
+ "componentName": "UploadView",
+ "displayName": "Upload",
+ "handler": [Function],
+ "includeProgress": true,
+ "isCancelable": true,
+ },
+}
+`;
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/context.spec.tsx b/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/context.spec.tsx
new file mode 100644
index 00000000000..9008ffc0c21
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/context.spec.tsx
@@ -0,0 +1,30 @@
+import React from 'react';
+import { renderHook } from '@testing-library/react';
+
+import { defaultActionConfigs } from '../defaults';
+import { ActionConfigs } from '../types';
+
+import { ActionConfigsProvider, useActionConfigs } from '../context';
+
+describe('useActionConfigs', () => {
+ it('returns default and custom config values passed to `ActionConfigsProvider`', () => {
+ const someCoolHandler = jest.fn();
+ const configs: ActionConfigs = {
+ ...defaultActionConfigs,
+ SomeCoolAction: {
+ componentName: 'SomeCoolView',
+ handler: someCoolHandler,
+ isCancelable: false,
+ displayName: 'Do Cool Action',
+ },
+ };
+
+ const { result } = renderHook(useActionConfigs, {
+ wrapper: (props) => (
+
+ ),
+ });
+
+ expect(result.current.actions).toStrictEqual(configs);
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/defaults.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/defaults.spec.ts
new file mode 100644
index 00000000000..d5e2689c1cd
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/__tests__/defaults.spec.ts
@@ -0,0 +1,143 @@
+import { ActionListItemConfig } from '../types';
+import {
+ createFolderActionConfig,
+ defaultActionConfigs,
+ listLocationItemsActionConfig,
+ uploadActionConfig,
+} from '../defaults';
+import {
+ generateCombinations,
+ LOCATION_PERMISSION_VALUES,
+} from '../../__testUtils__/permissions';
+
+const file = {
+ key: 'key',
+ id: 'id',
+ lastModified: new Date(),
+ size: 100,
+ type: 'FILE' as const,
+};
+
+const permissionValuesWithoutWrite = LOCATION_PERMISSION_VALUES.filter(
+ (value) => value !== 'write'
+);
+
+describe('defaultActionConfigs', () => {
+ it('matches expected shape', () => {
+ expect(defaultActionConfigs).toMatchSnapshot();
+ });
+
+ describe('createFolderActionConfig', () => {
+ it('hides the action list item as expected', () => {
+ const hide =
+ (createFolderActionConfig.actionsListItemConfig as ActionListItemConfig)!
+ .hide!;
+ for (const permissionsWithoutWrite of generateCombinations(
+ permissionValuesWithoutWrite
+ )) {
+ expect(hide(permissionsWithoutWrite)).toBe(true);
+ expect(hide([...permissionValuesWithoutWrite, 'write'])).toBe(false);
+ }
+ });
+
+ it('is never disabled', () => {
+ const disable =
+ (createFolderActionConfig.actionsListItemConfig as ActionListItemConfig)!
+ .disable!;
+
+ expect(disable([])).toBe(false);
+ expect(disable([file])).toBe(false);
+ expect(disable(undefined)).toBe(false);
+ });
+ });
+
+ describe('listLocationItemsActionConfig', () => {
+ it('returns the expected value of title', () => {
+ const { displayName } = listLocationItemsActionConfig;
+
+ expect(displayName(undefined, undefined)).toBe('-');
+ expect(displayName('bucket', undefined)).toBe('bucket');
+ expect(displayName('bucket', 'prefix/')).toBe('bucket: prefix/');
+ expect(displayName('bucket', 'prefix/nested/')).toBe(
+ 'bucket: ../nested/'
+ );
+ });
+ });
+
+ describe('uploadActionConfig', () => {
+ it('hides the action list item as expected', () => {
+ const uploadFileListItem = uploadActionConfig.actionsListItemConfig!;
+
+ for (const permissionsWithoutWrite of generateCombinations(
+ permissionValuesWithoutWrite
+ )) {
+ const permissionsWithWrite = [
+ ...permissionValuesWithoutWrite,
+ 'write' as const,
+ ];
+ expect(uploadFileListItem.hide?.(permissionsWithoutWrite)).toBe(true);
+ expect(uploadFileListItem.hide?.(permissionsWithWrite)).toBe(false);
+ }
+ });
+
+ it('is never disabled', () => {
+ const uploadFileListItem = uploadActionConfig.actionsListItemConfig!;
+
+ expect(uploadFileListItem.disable?.([])).toBe(false);
+ expect(uploadFileListItem.disable?.([file])).toBe(false);
+ expect(uploadFileListItem.disable?.(undefined)).toBe(false);
+ });
+ });
+
+ describe('deleteActionConfig', () => {
+ it('hides the action list item as expected', () => {
+ const deleteFileListItem =
+ defaultActionConfigs.delete.actionsListItemConfig!;
+
+ for (const permissionsWithoutDelete of generateCombinations(
+ LOCATION_PERMISSION_VALUES.filter((value) => value !== 'delete')
+ )) {
+ const permissionsWithDelete = [
+ ...permissionsWithoutDelete,
+ 'delete' as const,
+ ];
+ expect(deleteFileListItem.hide?.(permissionsWithoutDelete)).toBe(true);
+ expect(deleteFileListItem.hide?.(permissionsWithDelete)).toBe(false);
+ }
+ });
+
+ it('is disabled when no files are selected', () => {
+ const deleteFileListItem =
+ defaultActionConfigs.delete.actionsListItemConfig!;
+
+ expect(deleteFileListItem.disable?.(undefined)).toBe(true);
+ expect(deleteFileListItem.disable?.([])).toBe(true);
+ expect(deleteFileListItem.disable?.([file])).toBe(false);
+ });
+ });
+
+ describe('copyActionConfig', () => {
+ it('hides the action list item as expected', () => {
+ const copyFileListItem = defaultActionConfigs.copy.actionsListItemConfig!;
+
+ for (const permissionsWithoutWrite of generateCombinations(
+ permissionValuesWithoutWrite
+ )) {
+ const permissionsWithWrite = [
+ ...permissionValuesWithoutWrite,
+ 'write' as const,
+ ];
+ expect(copyFileListItem.hide?.(permissionsWithoutWrite)).toBe(true);
+ expect(copyFileListItem.hide?.(permissionsWithWrite)).toBe(false);
+ }
+ });
+
+ it('is disabled when no files are selected', () => {
+ const copyFileListItem = defaultActionConfigs.copy.actionsListItemConfig!;
+
+ expect(copyFileListItem.disable?.(undefined)).toBe(true);
+ expect(copyFileListItem.disable?.([])).toBe(true);
+ expect(copyFileListItem.disable?.([file])).toBe(false);
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/context.ts b/packages/react-storage/src/components/StorageBrowser/actions/configs/context.ts
new file mode 100644
index 00000000000..2bde82f1c50
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/context.ts
@@ -0,0 +1,23 @@
+import { createContextUtilities } from '@aws-amplify/ui-react-core';
+import { ActionConfigs } from './types';
+
+export interface ActionConfigsProviderProps {
+ actions?: ActionConfigs;
+ children?: React.ReactNode;
+}
+
+const defaultValue: { actions?: ActionConfigs } = { actions: undefined };
+export const { useActionConfigs, ActionConfigsProvider } =
+ createContextUtilities({ contextName: 'ActionConfigs', defaultValue });
+
+export function useActionConfig(
+ type?: T
+): ActionConfigs[T] {
+ const { actions } = useActionConfigs();
+
+ const config = type && actions?.[type];
+
+ if (!config) throw new Error('No action!');
+
+ return config;
+}
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/defaults.tsx b/packages/react-storage/src/components/StorageBrowser/actions/configs/defaults.tsx
new file mode 100644
index 00000000000..a58ec847424
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/defaults.tsx
@@ -0,0 +1,113 @@
+import {
+ listLocationItemsHandler,
+ listLocationsHandler,
+ createFolderHandler,
+ uploadHandler,
+ copyHandler,
+ deleteHandler,
+} from '../handlers';
+
+import {
+ CopyActionConfig,
+ CreateFolderActionConfig,
+ DeleteActionConfig,
+ ListLocationItemsActionConfig,
+ ListLocationsActionConfig,
+ UploadActionConfig,
+} from './types';
+
+export const copyActionConfig: CopyActionConfig = {
+ componentName: 'CopyView',
+ actionsListItemConfig: {
+ disable: (selected) => !selected || selected.length === 0,
+ hide: (permissions) => !permissions.includes('write'),
+ icon: 'copy-file',
+ label: 'Copy',
+ },
+ displayName: 'Copy',
+ handler: copyHandler,
+};
+
+export const deleteActionConfig: DeleteActionConfig = {
+ componentName: 'DeleteView',
+ actionsListItemConfig: {
+ disable: (selected) => !selected || selected.length === 0,
+ hide: (permissions) => !permissions.includes('delete'),
+ icon: 'delete-file',
+ label: 'Delete',
+ },
+ displayName: 'Delete',
+ handler: deleteHandler,
+};
+
+export const createFolderActionConfig: CreateFolderActionConfig = {
+ componentName: 'CreateFolderView',
+ actionsListItemConfig: {
+ disable: () => false,
+ hide: (permissions) => !permissions.includes('write'),
+ icon: 'create-folder',
+ label: 'Create folder',
+ },
+ handler: createFolderHandler,
+ isCancelable: false,
+ displayName: 'Create Folder',
+};
+
+export const listLocationItemsActionConfig: ListLocationItemsActionConfig = {
+ componentName: 'LocationDetailView',
+ handler: listLocationItemsHandler,
+ displayName: (bucket, prefix) => {
+ if (bucket && prefix) {
+ const prefixes = prefix.split('/');
+ return `${bucket}: ${
+ prefixes.length > 2 ? `../${prefixes[prefixes.length - 2]}/` : prefix
+ }`;
+ }
+ return !bucket ? '-' : bucket;
+ },
+};
+
+export const listLocationsActionConfig: ListLocationsActionConfig = {
+ componentName: 'LocationsView',
+ handler: listLocationsHandler,
+ displayName: 'Home',
+};
+
+export const uploadActionConfig: UploadActionConfig = {
+ componentName: 'UploadView',
+ actionsListItemConfig: {
+ disable: () => false,
+ fileSelection: 'FILE',
+ hide: (permissions) => !permissions.includes('write'),
+ icon: 'upload-file',
+ label: 'Upload',
+ },
+ isCancelable: true,
+ includeProgress: true,
+ handler: uploadHandler,
+ displayName: 'Upload',
+};
+
+export const defaultActionViewConfigs = {
+ copy: copyActionConfig,
+ createFolder: createFolderActionConfig,
+ delete: deleteActionConfig,
+ upload: uploadActionConfig,
+};
+
+export type DefaultActionViewType = keyof typeof defaultActionViewConfigs;
+
+export const DEFAULT_ACTION_VIEW_TYPES = Object.keys(
+ defaultActionViewConfigs
+) as DefaultActionViewType[];
+
+export const isDefaultActionViewType = (
+ value?: string
+): value is DefaultActionViewType =>
+ DEFAULT_ACTION_VIEW_TYPES.some((type) => type === value);
+
+export const defaultActionConfigs = {
+ ...defaultActionViewConfigs,
+ listLocationItems: listLocationItemsActionConfig,
+ listLocations: listLocationsActionConfig,
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/index.ts b/packages/react-storage/src/components/StorageBrowser/actions/configs/index.ts
new file mode 100644
index 00000000000..b94b3f540be
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/index.ts
@@ -0,0 +1,11 @@
+export {
+ ActionConfigsProvider,
+ ActionConfigsProviderProps,
+ useActionConfig,
+} from './context';
+export {
+ defaultActionConfigs,
+ defaultActionViewConfigs,
+ isDefaultActionViewType,
+} from './defaults';
+export * from './types';
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/configs/types.ts b/packages/react-storage/src/components/StorageBrowser/actions/configs/types.ts
new file mode 100644
index 00000000000..52ae4082997
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/configs/types.ts
@@ -0,0 +1,167 @@
+import { StorageBrowserIconType } from '../../context/elements';
+import { LocationPermissions } from '../../actions';
+
+import {
+ ListLocationsHandler,
+ ListLocationItemsHandler,
+ LocationItemData,
+ LocationItemType,
+ UploadHandler,
+ CreateFolderHandler,
+ DeleteHandler,
+ CopyHandler,
+ TaskHandler,
+} from '../handlers';
+
+type StringWithoutSpaces = Exclude<
+ T,
+ ` ${string}` | `${string} ` | `${string} ${string}`
+>;
+
+export type ComponentName = Capitalize<`${string}View`>;
+type ActionName = StringWithoutSpaces;
+
+/**
+ * native OS file picker type. to restrict selectable file types, define the picker types
+ * followed by accepted file types as strings
+ * @example
+ * ```ts
+ * type JPEGOnly = ['FOLDER', '.jpeg'];
+ * ```
+ */
+export type SelectionType = LocationItemType | [LocationItemType, ...string[]];
+
+export interface ActionConfigTemplate {
+ /**
+ * The name of the component associated with the action
+ */
+ componentName: ComponentName;
+
+ /**
+ * action handler
+ */
+ handler: T;
+}
+
+export interface ActionListItemConfig {
+ /**
+ * conditionally disable item selection based on currently selected values
+ * @default false
+ */
+ disable?: (selectedValues: LocationItemData[] | undefined) => boolean;
+
+ /**
+ * open native OS file picker with associated selection type on item select
+ */
+ fileSelection?: SelectionType;
+
+ /**
+ * conditionally render list item based on location permission
+ * @default false
+ */
+ hide?: (permissions: LocationPermissions) => boolean;
+
+ /**
+ * list item icon
+ */
+ icon: StorageBrowserIconType;
+
+ /**
+ * list item label
+ */
+ label: string;
+}
+
+/**
+ * defines an action to be included in the actions list of the `LocationDetailView` with
+ * a dedicated subcomponent of the `LocationActionView`
+ */
+export interface TaskActionConfig
+ extends ActionConfigTemplate {
+ /**
+ * configure action list item behavior. provide multiple configs
+ * to create additional list items for a single action
+ */
+ actionsListItemConfig?: ActionListItemConfig;
+
+ /**
+ * whether the provided `handler` allow inflight cancellation
+ * @default false
+ */
+ isCancelable?: boolean;
+
+ /**
+ * show per task progress in the action task table
+ * @default false
+ */
+ includeProgress?: boolean;
+
+ /**
+ * default display name value displayed on action view
+ */
+ displayName: string;
+}
+
+export interface ListActionConfig extends ActionConfigTemplate {}
+
+export interface UploadActionConfig extends TaskActionConfig {
+ componentName: 'UploadView';
+}
+
+export interface DeleteActionConfig extends TaskActionConfig {
+ componentName: 'DeleteView';
+}
+
+export interface CopyActionConfig extends TaskActionConfig {
+ componentName: 'CopyView';
+}
+
+export interface CreateFolderActionConfig
+ extends TaskActionConfig {
+ componentName: 'CreateFolderView';
+}
+
+export interface ListLocationsActionConfig
+ extends ListActionConfig {
+ componentName: 'LocationsView';
+ displayName: string;
+}
+
+export interface ListLocationItemsActionConfig
+ extends ListActionConfig {
+ componentName: 'LocationDetailView';
+ displayName: (
+ bucket: string | undefined,
+ prefix: string | undefined
+ ) => string;
+}
+
+export interface DefaultActionConfigs {
+ ListLocationItems: ListLocationItemsActionConfig;
+ ListLocations: ListLocationsActionConfig;
+ CreateFolder: CreateFolderActionConfig;
+ Upload: UploadActionConfig;
+ Delete: DeleteActionConfig;
+ Copy: CopyActionConfig;
+}
+
+export type DefaultActionKey = keyof DefaultActionConfigs;
+
+export type ActionConfigs = Record<
+ ActionsKeys,
+ | ListLocationItemsActionConfig
+ | ListLocationsActionConfig
+ | CreateFolderActionConfig
+ | UploadActionConfig
+ | TaskActionConfig
+>;
+
+export type ResolveActionHandler = T extends
+ | TaskActionConfig
+ | ListActionConfig
+ ? K
+ : never;
+
+export type ResolveActionHandlers = {
+ [K in keyof T]: ResolveActionHandler;
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/createUseAction.ts b/packages/react-storage/src/components/StorageBrowser/actions/createUseAction.ts
new file mode 100644
index 00000000000..58e47777a8c
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/createUseAction.ts
@@ -0,0 +1,6 @@
+import { CreateUseAction } from './types';
+
+export const createUseAction: CreateUseAction = (_) => {
+ // TODO: implement this function
+ throw new Error('Not implemented');
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/copy.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/copy.spec.ts
new file mode 100644
index 00000000000..8b385f86b5e
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/copy.spec.ts
@@ -0,0 +1,105 @@
+import * as StorageModule from '../../../storage-internal';
+
+import { copyHandler, CopyHandlerInput } from '../copy';
+
+const copySpy = jest.spyOn(StorageModule, 'copy');
+
+const baseInput: CopyHandlerInput = {
+ destinationPrefix: 'destination/',
+ config: {
+ accountId: '012345678901',
+ bucket: 'bucket',
+ credentials: jest.fn(),
+ customEndpoint: 'mock-endpoint',
+ region: 'region',
+ },
+ data: {
+ id: 'identity',
+ key: 'some-prefixfix/some-key.hehe',
+ fileKey: 'some-key.hehe',
+ lastModified: new Date(),
+ size: 100000000,
+ eTag: 'etag',
+ type: 'FILE',
+ },
+};
+
+describe('copyHandler', () => {
+ afterEach(() => {
+ copySpy.mockClear();
+ });
+
+ it('calls `copy` wth the expected values', () => {
+ copyHandler(baseInput);
+
+ const bucket = {
+ bucketName: `${baseInput.config.bucket}`,
+ region: `${baseInput.config.region}`,
+ };
+
+ const expected: StorageModule.CopyInput = {
+ destination: {
+ expectedBucketOwner: baseInput.config.accountId,
+ bucket,
+ path: `${baseInput.destinationPrefix}${baseInput.data.fileKey}`,
+ },
+ source: {
+ expectedBucketOwner: `${baseInput.config.accountId}`,
+ bucket,
+ path: baseInput.data.key,
+ eTag: baseInput.data.eTag,
+ notModifiedSince: baseInput.data.lastModified,
+ },
+ options: {
+ locationCredentialsProvider: baseInput.config.credentials,
+ customEndpoint: baseInput.config.customEndpoint,
+ },
+ };
+
+ expect(copySpy).toHaveBeenCalledWith(expected);
+ });
+
+ it('provides eTag and notModifiedSince to copy for durableness', () => {
+ copyHandler(baseInput);
+
+ const bucket = {
+ bucketName: `${baseInput.config.bucket}`,
+ region: `${baseInput.config.region}`,
+ };
+
+ const copyInput = copySpy.mock.lastCall?.[0];
+ expect(copyInput).toHaveProperty('source', {
+ expectedBucketOwner: `${baseInput.config.accountId}`,
+ bucket,
+ path: baseInput.data.key,
+ eTag: baseInput.data.eTag,
+ notModifiedSince: baseInput.data.lastModified,
+ });
+ });
+
+ it.each([
+ ['unicode', 'bucket/path/☺️', 'bucket/path/%E2%98%BA%EF%B8%8F'],
+ ['already encoded', 'bucket/path/%20', 'bucket/path/%2520'],
+ [
+ 'characters to be uri encoded',
+ 'bucket/path/&$@=;:+,?',
+ 'bucket/path/%26%24%40%3D%3B%3A%2B%2C%3F',
+ ],
+ ])('encodes the source path that is %s', (_, sourcePath, expectedPath) => {
+ copyHandler({
+ ...baseInput,
+ data: {
+ ...baseInput.data,
+ key: sourcePath,
+ },
+ });
+
+ const expected = expect.objectContaining({
+ source: expect.objectContaining({
+ path: expectedPath,
+ }),
+ });
+
+ expect(copySpy).toHaveBeenCalledWith(expected);
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/createFolder.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/createFolder.spec.ts
new file mode 100644
index 00000000000..04fb557ab44
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/createFolder.spec.ts
@@ -0,0 +1,155 @@
+import { createFolderHandler, CreateFolderHandlerInput } from '../createFolder';
+
+import * as InternalStorageModule from '../../../storage-internal';
+
+const uploadDataSpy = jest.spyOn(InternalStorageModule, 'uploadData');
+
+const credentials = jest.fn();
+
+const config: CreateFolderHandlerInput['config'] = {
+ accountId: '012345678901',
+ bucket: 'bucket',
+ credentials,
+ customEndpoint: 'mock-endpoint',
+ region: 'region',
+};
+
+const onProgress = jest.fn();
+
+const baseInput: CreateFolderHandlerInput = {
+ config,
+ data: { key: '', id: 'an-id' },
+ destinationPrefix: 'prefix/',
+};
+
+const error = new Error('Failed!');
+
+describe('createFolderHandler', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('behaves as expected in the happy path', async () => {
+ uploadDataSpy.mockReturnValueOnce({
+ cancel: jest.fn(),
+ pause: jest.fn(),
+ resume: jest.fn(),
+ result: Promise.resolve({ path: '' }),
+ state: 'SUCCESS',
+ });
+
+ const { result } = createFolderHandler(baseInput);
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+ });
+
+ it('calls `uploadData` with the expected values', () => {
+ createFolderHandler({ ...baseInput, options: { preventOverwrite: true } });
+
+ const expected: InternalStorageModule.UploadDataInput = {
+ data: '',
+ options: {
+ expectedBucketOwner: config.accountId,
+ bucket: {
+ bucketName: config.bucket,
+ region: config.region,
+ },
+ customEndpoint: config.customEndpoint,
+ locationCredentialsProvider: credentials,
+ onProgress: expect.any(Function),
+ preventOverwrite: true,
+ },
+ path: `${baseInput.destinationPrefix}${baseInput.data.key}`,
+ };
+
+ expect(uploadDataSpy).toHaveBeenCalledWith(expected);
+ });
+
+ it('calls provided onProgress callback as expected in the happy path', async () => {
+ uploadDataSpy.mockImplementation(({ options }) => {
+ // @ts-expect-error - `options` is potentially `undefined` in the `uploadData` input interface
+ options.onProgress({ totalBytes: 23, transferredBytes: 23 });
+
+ return {
+ cancel: jest.fn(),
+ pause: jest.fn(),
+ resume: jest.fn(),
+ result: Promise.resolve({ path: '' }),
+ state: 'SUCCESS',
+ };
+ });
+
+ const { result } = createFolderHandler({
+ ...baseInput,
+ options: { onProgress },
+ });
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+
+ expect(onProgress).toHaveBeenCalledTimes(1);
+ expect(onProgress).toHaveBeenCalledWith(baseInput.data, 1);
+ });
+
+ it('calls provided onProgress callback as expected when `totalBytes` is `undefined`', async () => {
+ uploadDataSpy.mockImplementation(({ options }) => {
+ // @ts-expect-error - `options` is potentially `undefined` in the `uploadData` input interface
+ options.onProgress({ transferredBytes: 23 });
+
+ return {
+ cancel: jest.fn(),
+ pause: jest.fn(),
+ resume: jest.fn(),
+ result: Promise.resolve({ path: '' }),
+ state: 'SUCCESS',
+ };
+ });
+
+ const { result } = createFolderHandler({
+ ...baseInput,
+ options: { onProgress },
+ });
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+
+ expect(onProgress).toHaveBeenCalledTimes(1);
+ expect(onProgress).toHaveBeenCalledWith(baseInput.data, undefined);
+ });
+
+ it('handles a failure as expected', async () => {
+ uploadDataSpy.mockReturnValueOnce({
+ cancel: jest.fn(),
+ pause: jest.fn(),
+ resume: jest.fn(),
+ result: Promise.reject(error),
+ state: 'ERROR',
+ });
+
+ const { result } = createFolderHandler(baseInput);
+
+ expect(await result).toStrictEqual({
+ message: error.message,
+ status: 'FAILED',
+ });
+ });
+
+ it('returns "OVERWRITE_PREVENTED" on `PreconditionFailed` error', async () => {
+ const message = 'No overwrite!';
+ const overwritePreventedError = new Error(message);
+ overwritePreventedError.name = 'PreconditionFailed';
+
+ uploadDataSpy.mockReturnValueOnce({
+ cancel: jest.fn(),
+ pause: jest.fn(),
+ resume: jest.fn(),
+ result: Promise.reject(overwritePreventedError),
+ state: 'ERROR',
+ });
+
+ const { result } = createFolderHandler(baseInput);
+
+ expect(await result).toStrictEqual({
+ message,
+ status: 'OVERWRITE_PREVENTED',
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/delete.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/delete.spec.ts
new file mode 100644
index 00000000000..7e99f1cc3f4
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/delete.spec.ts
@@ -0,0 +1,44 @@
+import * as StorageModule from '../../../storage-internal';
+
+import { deleteHandler, DeleteHandlerInput } from '../delete';
+
+const removeSpy = jest.spyOn(StorageModule, 'remove');
+
+const baseInput: DeleteHandlerInput = {
+ config: {
+ accountId: '012345678901',
+ bucket: 'bucket',
+ credentials: jest.fn(),
+ customEndpoint: 'mock-endpoint',
+ region: 'region',
+ },
+ data: {
+ id: 'id',
+ key: 'prefix/key.png',
+ fileKey: 'key.png',
+ lastModified: new Date(),
+ size: 829292,
+ type: 'FILE',
+ },
+};
+
+describe('deleteHandler', () => {
+ it('calls `remove` and returns the expected `key`', () => {
+ deleteHandler(baseInput);
+
+ const expected: StorageModule.RemoveInput = {
+ path: baseInput.data.key,
+ options: {
+ expectedBucketOwner: baseInput.config.accountId,
+ bucket: {
+ bucketName: baseInput.config.bucket,
+ region: baseInput.config.region,
+ },
+ customEndpoint: baseInput.config.customEndpoint,
+ locationCredentialsProvider: baseInput.config.credentials,
+ },
+ };
+
+ expect(removeSpy).toHaveBeenCalledWith(expected);
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/download.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/download.spec.ts
new file mode 100644
index 00000000000..cf602feaf34
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/download.spec.ts
@@ -0,0 +1,46 @@
+import * as StorageModule from '../../../storage-internal';
+
+import { downloadHandler, DownloadHandlerInput } from '../download';
+
+const downloadSpy = jest.spyOn(StorageModule, 'getUrl');
+
+const baseInput: DownloadHandlerInput = {
+ config: {
+ accountId: 'accountId',
+ bucket: 'bucket',
+ credentials: jest.fn(),
+ customEndpoint: 'mock-endpoint',
+ region: 'region',
+ },
+ data: {
+ id: 'id',
+ key: 'prefix/file-name',
+ fileKey: 'file-name',
+ lastModified: new Date(),
+ size: 1000022,
+ type: 'FILE',
+ },
+};
+
+describe('downloadHandler', () => {
+ it('calls `getUrl` with the expected values', () => {
+ downloadHandler(baseInput);
+
+ const expected: StorageModule.GetUrlInput = {
+ path: baseInput.data.key,
+ options: {
+ bucket: {
+ bucketName: baseInput.config.bucket,
+ region: baseInput.config.region,
+ },
+ customEndpoint: baseInput.config.customEndpoint,
+ locationCredentialsProvider: baseInput.config.credentials,
+ validateObjectExistence: true,
+ contentDisposition: 'attachment',
+ expectedBucketOwner: baseInput.config.accountId,
+ },
+ };
+
+ expect(downloadSpy).toHaveBeenCalledWith(expected);
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/listLocationItems.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/listLocationItems.spec.ts
new file mode 100644
index 00000000000..84f51da6e81
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/listLocationItems.spec.ts
@@ -0,0 +1,162 @@
+import * as StorageModule from '../../../storage-internal';
+
+import {
+ listLocationItemsHandler,
+ ListLocationItemsHandlerInput,
+ parseResult,
+} from '../listLocationItems';
+
+let uuid = 0;
+Object.defineProperty(globalThis, 'crypto', {
+ value: {
+ randomUUID: () => {
+ uuid++;
+ return uuid.toString();
+ },
+ },
+});
+
+const listSpy = jest
+ .spyOn(StorageModule, 'list')
+ .mockImplementation(() => Promise.resolve({ items: [], nextToken: '' }));
+
+const baseInput: ListLocationItemsHandlerInput = {
+ prefix: 'prefix/',
+ config: {
+ accountId: '012345678901',
+ bucket: 'bucket',
+ customEndpoint: 'mock-endpoint',
+ credentials: jest.fn(),
+ region: 'region',
+ },
+};
+
+const prefix = 'prefix1/';
+
+describe('listLocationItemsHandler', () => {
+ beforeEach(() => {
+ listSpy.mockClear();
+ });
+
+ it('returns the expected output shape in the happy path', async () => {
+ listSpy.mockResolvedValueOnce({ items: [], nextToken: 'tokeno' });
+
+ const { items, nextToken } = await listLocationItemsHandler(baseInput);
+
+ expect(items).toHaveLength(0);
+ expect(nextToken).toBeDefined();
+ });
+
+ it('provides expected `pageSize` to `list` on initial load', async () => {
+ listSpy.mockResolvedValueOnce({ items: [] });
+
+ const input = {
+ ...baseInput,
+ options: { pageSize: 10 },
+ prefix: 'a_prefix',
+ };
+
+ await listLocationItemsHandler(input);
+
+ expect(listSpy).toHaveBeenCalledTimes(1);
+ expect(listSpy).toHaveBeenCalledWith({
+ path: input.prefix,
+ options: {
+ bucket: {
+ bucketName: input.config.bucket,
+ region: input.config.region,
+ },
+ customEndpoint: input.config.customEndpoint,
+ expectedBucketOwner: input.config.accountId,
+ locationCredentialsProvider: input.config.credentials,
+ nextToken: undefined,
+ pageSize: input.options.pageSize + 1,
+ subpathStrategy: { delimiter: undefined, strategy: 'include' },
+ },
+ });
+ });
+ it('provides `pageSize` number of items after removing items that match / or . or ..', async () => {
+ listSpy
+ .mockResolvedValueOnce({
+ items: [
+ { path: `/`, lastModified: new Date(), size: 0 },
+ { path: `.`, lastModified: new Date(), size: 0 },
+ { path: `..`, lastModified: new Date(), size: 0 },
+ { path: `${prefix}-1`, lastModified: new Date(), size: 0 },
+ ],
+ nextToken: '1',
+ })
+ .mockResolvedValueOnce({
+ items: [
+ { path: `${prefix}-2`, lastModified: new Date(), size: 0 },
+ { path: `${prefix}-3`, lastModified: new Date(), size: 0 },
+ ],
+ nextToken: undefined,
+ });
+
+ const input = {
+ ...baseInput,
+ options: { pageSize: 3 },
+ prefix: 'a_prefix',
+ };
+
+ const listItems = await listLocationItemsHandler(input);
+ expect(listItems.items).toHaveLength(input.options.pageSize);
+ expect(listSpy).toHaveBeenCalledTimes(2);
+ });
+});
+
+describe('parseResult', () => {
+ it('outputs correct list with items: prefix, zero byte folder, object and excludedSubpaths', () => {
+ const output = {
+ items: [
+ // Current prefix
+ { path: prefix, lastModified: new Date(), size: 0 },
+ // Zero byte subfolder:
+ { path: `${prefix}Banana/`, lastModified: new Date(), size: 0 },
+ // Image file:
+ { path: `${prefix}Orange.jpg`, lastModified: new Date(), size: 56984 },
+ ],
+ // subfolder with objects in it
+ excludedSubpaths: [`${prefix}Cloudberry/`],
+ };
+ const result = parseResult(output, prefix);
+ expect(result).toHaveLength(3);
+ const subFolderWithObject = result[0];
+ expect(subFolderWithObject.key).toBe(`${prefix}Cloudberry/`);
+ expect(subFolderWithObject.type).toBe('FOLDER');
+ const zeroByteSubFolder = result[1];
+ expect(zeroByteSubFolder.key).toBe(`${prefix}Banana/`);
+ expect(zeroByteSubFolder.type).toBe('FOLDER');
+ const file = result[2];
+ expect(file.key).toBe(`${prefix}Orange.jpg`);
+ expect(file.type).toBe('FILE');
+ });
+
+ it('should return empty array for empty zero byte folder', () => {
+ // empty folders will just show the current prefix as the path
+ const output = {
+ items: [{ path: prefix, lastModified: new Date(), size: 0 }],
+ };
+ const result = parseResult(output, prefix);
+ expect(result).toHaveLength(0);
+ });
+
+ describe('filterDotItems', () => {
+ it('should filter out invalid keys: "/", "." etc', () => {
+ const output = {
+ items: [
+ { path: ` / `, lastModified: new Date(), size: 0 },
+ { path: ` ./ `, lastModified: new Date(), size: 0 },
+ { path: ` ../ `, lastModified: new Date(), size: 0 },
+ { path: ` . `, lastModified: new Date(), size: 0 },
+ { path: ` .. `, lastModified: new Date(), size: 0 },
+ { path: `${prefix}visible`, lastModified: new Date(), size: 0 },
+ ],
+ };
+ const result = parseResult(output, prefix);
+ expect(result).toHaveLength(1);
+ expect(result[0].key).toBe(`${prefix}visible`);
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/listLocations.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/listLocations.spec.ts
new file mode 100644
index 00000000000..60fd72da488
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/listLocations.spec.ts
@@ -0,0 +1,130 @@
+import {
+ listCallerAccessGrants,
+ ListLocationsOutput,
+ LocationCredentialsProvider,
+ LocationAccess,
+} from '../../../storage-internal';
+
+import { getFilteredLocations } from '../utils';
+
+import {
+ listLocationsHandler,
+ ListLocationsHandlerInput,
+} from '../listLocations';
+
+jest.mock('../../../storage-internal');
+
+const mockListCallerAccessGrants = jest.mocked(listCallerAccessGrants);
+
+const generateMockLocations = (size: number, mockLocations: LocationAccess) =>
+ Array(size).fill(mockLocations);
+
+const accountId = 'account-id';
+const credentials: LocationCredentialsProvider = jest.fn();
+const region = 'region';
+
+const customEndpoint = 'mock-endpoint';
+const DEFAULT_PAGE_SIZE = 5;
+
+const input: ListLocationsHandlerInput = {
+ config: { accountId, credentials, customEndpoint, region },
+ options: {
+ pageSize: DEFAULT_PAGE_SIZE,
+ nextToken: undefined,
+ exclude: { exactPermissions: ['get', 'list'] },
+ },
+};
+
+describe('listLocationsHandler', () => {
+ // TODO(@AllanZhengYP): add unit test for more permissions permutations
+ beforeAll(() => {
+ Object.defineProperty(globalThis, 'crypto', {
+ value: { randomUUID: () => 'intentionally-static-test-id' },
+ });
+ });
+
+ beforeEach(() => {
+ jest.resetAllMocks();
+ });
+
+ it('should fetch a single page of results successfully', async () => {
+ const mockOutput: ListLocationsOutput = {
+ locations: [
+ { scope: 's3://bucket/prefix/*', permission: 'READ', type: 'PREFIX' },
+ ],
+ nextToken: undefined,
+ };
+
+ mockListCallerAccessGrants.mockResolvedValueOnce(mockOutput);
+
+ const result = await listLocationsHandler(input);
+
+ expect(result.items).toEqual(
+ getFilteredLocations(mockOutput.locations, input.options?.exclude)
+ );
+ expect(result.nextToken).toBeUndefined();
+ expect(mockListCallerAccessGrants).toHaveBeenCalledTimes(1);
+ expect(mockListCallerAccessGrants).toHaveBeenCalledWith({
+ accountId: input.config.accountId,
+ credentialsProvider: input.config.credentials,
+ customEndpoint: input.config.customEndpoint,
+ nextToken: input.options?.nextToken,
+ pageSize: input.options?.pageSize,
+ region: input.config.region,
+ });
+ });
+
+ it('should fetch multiple pages of results successfully', async () => {
+ const mockLocation: LocationAccess = {
+ scope: 's3://bucket/prefix1/*',
+ permission: 'READWRITE',
+ type: 'PREFIX',
+ };
+ const mockOutputPage1: ListLocationsOutput = {
+ locations: [mockLocation],
+ nextToken: 'token1',
+ };
+
+ const mockOutputPage2: ListLocationsOutput = {
+ locations: [...generateMockLocations(2, mockLocation)],
+ nextToken: 'token2',
+ };
+
+ const mockOutputPage3: ListLocationsOutput = {
+ locations: [...generateMockLocations(2, mockLocation)],
+ nextToken: undefined,
+ };
+
+ mockListCallerAccessGrants
+ .mockResolvedValueOnce(mockOutputPage1)
+ .mockResolvedValueOnce(mockOutputPage2)
+ .mockResolvedValueOnce(mockOutputPage3);
+
+ const result = await listLocationsHandler(input);
+
+ expect(result.items).toEqual([
+ ...getFilteredLocations(
+ mockOutputPage1.locations,
+ input.options?.exclude
+ ),
+ ...getFilteredLocations(
+ mockOutputPage2.locations,
+ input.options?.exclude
+ ),
+ ...getFilteredLocations(
+ mockOutputPage3.locations,
+ input.options?.exclude
+ ),
+ ]);
+ expect(result.nextToken).toBeUndefined();
+ expect(mockListCallerAccessGrants).toHaveBeenCalledTimes(3);
+ expect(result.items.length).toEqual(DEFAULT_PAGE_SIZE);
+ });
+
+ it('should throw when accountId is not present to fetch Locations', async () => {
+ input.config.accountId = undefined;
+ await expect(listLocationsHandler(input)).rejects.toThrow(
+ 'Storage Browser: Must provide accountId to `listCallerAccessGrants`.'
+ );
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/upload.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/upload.spec.ts
new file mode 100644
index 00000000000..2e123f8dae1
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/upload.spec.ts
@@ -0,0 +1,236 @@
+import * as InternalStorageModule from '../../../storage-internal';
+import * as StorageModule from 'aws-amplify/storage';
+
+import {
+ MULTIPART_UPLOAD_THRESHOLD_BYTES,
+ uploadHandler,
+ UploadHandlerInput,
+ UNDEFINED_CALLBACKS,
+} from '../upload';
+
+const isCancelErrorSpy = jest.spyOn(StorageModule, 'isCancelError');
+const uploadDataSpy = jest.spyOn(InternalStorageModule, 'uploadData');
+
+const credentials = jest.fn();
+
+const config: UploadHandlerInput['config'] = {
+ accountId: '012345678901',
+ bucket: 'bucket',
+ credentials,
+ customEndpoint: 'mock-endpoint',
+ region: 'region',
+};
+
+const file = new File([], 'test-o');
+
+const onProgress = jest.fn();
+
+const baseInput: UploadHandlerInput = {
+ config,
+ data: { key: file.name, id: 'an-id', file },
+ destinationPrefix: 'prefix/',
+};
+
+const cancel = jest.fn();
+const pause = jest.fn();
+const resume = jest.fn();
+
+const error = new Error('Failed!');
+
+describe('uploadHandler', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('behaves as expected in the happy path', async () => {
+ uploadDataSpy.mockReturnValueOnce({
+ cancel,
+ pause,
+ resume,
+ result: Promise.resolve({ path: file.name }),
+ state: 'SUCCESS',
+ });
+
+ const { result } = uploadHandler(baseInput);
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+ });
+
+ it('calls upload with the expected values', () => {
+ uploadHandler({ ...baseInput, options: { preventOverwrite: true } });
+
+ const expected: InternalStorageModule.UploadDataInput = {
+ data: file,
+ options: {
+ expectedBucketOwner: config.accountId,
+ bucket: {
+ bucketName: config.bucket,
+ region: config.region,
+ },
+ customEndpoint: config.customEndpoint,
+ locationCredentialsProvider: credentials,
+ onProgress: expect.any(Function),
+ preventOverwrite: true,
+ checksumAlgorithm: 'crc-32',
+ },
+ path: `${baseInput.destinationPrefix}${baseInput.data.key}`,
+ };
+
+ expect(uploadDataSpy).toHaveBeenCalledWith(expected);
+ });
+
+ it('calls provided onProgress callback as expected in the happy path', async () => {
+ uploadDataSpy.mockImplementation(({ options }) => {
+ // @ts-expect-error - `options` is potentially `undefined` in the `uploadData` input interface
+ options.onProgress({ totalBytes: 23, transferredBytes: 23 });
+
+ return {
+ cancel,
+ pause,
+ resume,
+ result: Promise.resolve({ path: file.name }),
+ state: 'SUCCESS',
+ };
+ });
+
+ const { result } = uploadHandler({
+ ...baseInput,
+ options: { onProgress },
+ });
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+
+ expect(onProgress).toHaveBeenCalledTimes(1);
+ expect(onProgress).toHaveBeenCalledWith(baseInput.data, 1);
+ });
+
+ it('calls provided onProgress callback as expected when `totalBytes` is `undefined`', async () => {
+ uploadDataSpy.mockImplementation(({ options }) => {
+ // @ts-expect-error - `options` is potentially `undefined` in the `uploadData` input interface
+ options.onProgress({ transferredBytes: 23 });
+
+ return {
+ cancel,
+ pause,
+ resume,
+ result: Promise.resolve({ path: file.name }),
+ state: 'SUCCESS',
+ };
+ });
+
+ const { result } = uploadHandler({
+ ...baseInput,
+ options: { onProgress },
+ });
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+
+ expect(onProgress).toHaveBeenCalledTimes(1);
+ expect(onProgress).toHaveBeenCalledWith(baseInput.data, undefined);
+ });
+
+ it('returns the expected callback values for a file size greater than 5 mb', async () => {
+ const bigFile = new File(
+ [new ArrayBuffer(MULTIPART_UPLOAD_THRESHOLD_BYTES * 2)],
+ '😅'
+ );
+
+ uploadDataSpy.mockReturnValueOnce({
+ cancel,
+ pause,
+ resume,
+ result: Promise.resolve({ path: file.name }),
+ state: 'SUCCESS',
+ });
+
+ const { result, ...callbacks } = uploadHandler({
+ ...baseInput,
+ data: { key: bigFile.name, id: 'hi!', file: bigFile },
+ });
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+
+ expect(callbacks).toStrictEqual({ cancel, pause, resume });
+ });
+
+ it('returns undefined callback values for a file size less than 5 mb', async () => {
+ const smallFile = new File([], '😅');
+
+ uploadDataSpy.mockReturnValueOnce({
+ cancel,
+ pause,
+ resume,
+ result: Promise.resolve({ path: file.name }),
+ state: 'SUCCESS',
+ });
+
+ const { result, ...callbacks } = uploadHandler({
+ ...baseInput,
+ data: { key: smallFile.name, id: 'ohh', file: smallFile },
+ });
+
+ expect(await result).toStrictEqual({ status: 'COMPLETE' });
+
+ expect(callbacks).toStrictEqual(UNDEFINED_CALLBACKS);
+ });
+
+ it('handles a failure as expected', async () => {
+ uploadDataSpy.mockReturnValueOnce({
+ cancel,
+ pause,
+ resume,
+ result: Promise.reject(error),
+ state: 'ERROR',
+ });
+
+ const { result } = uploadHandler(baseInput);
+
+ expect(await result).toStrictEqual({
+ message: error.message,
+ status: 'FAILED',
+ });
+ });
+
+ it('handles a cancel failure as expected', async () => {
+ // turn off console.warn in test output
+ jest.spyOn(console, 'warn').mockReturnValueOnce();
+ isCancelErrorSpy.mockReturnValue(true);
+ uploadDataSpy.mockReturnValueOnce({
+ cancel,
+ pause,
+ resume,
+ result: Promise.reject(error),
+ state: 'ERROR',
+ });
+
+ const { result } = uploadHandler(baseInput);
+
+ expect(await result).toStrictEqual({
+ message: 'Failed!',
+ status: 'CANCELED',
+ });
+ });
+
+ it('handles an overwrite failure as expected', async () => {
+ const preconditionError = new Error('Failed!');
+ preconditionError.name = 'PreconditionFailed';
+
+ uploadDataSpy.mockReturnValueOnce({
+ cancel,
+ pause,
+ resume,
+ result: Promise.reject(preconditionError),
+ state: 'ERROR',
+ });
+
+ const { result } = uploadHandler({
+ ...baseInput,
+ options: { preventOverwrite: true },
+ });
+
+ expect(await result).toStrictEqual({
+ message: 'Failed!',
+ status: 'OVERWRITE_PREVENTED',
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/utils.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/utils.spec.ts
new file mode 100644
index 00000000000..f9cec8851ae
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/__tests__/utils.spec.ts
@@ -0,0 +1,140 @@
+import { LocationAccess as AccessGrantLocation } from '../../../storage-internal';
+import { LocationData } from '../types';
+
+import {
+ shouldExcludeLocation,
+ getFileKey,
+ parseAccessGrantLocation,
+} from '../utils';
+
+describe('parseLocationAccess', () => {
+ const bucket = 'test-bucket';
+ const folderPrefix = 'test-prefix/';
+ const filePath = 'some-file.jpeg2000';
+
+ const id = 'intentionally-static-test-id';
+ beforeAll(() => {
+ Object.defineProperty(globalThis, 'crypto', {
+ value: { randomUUID: () => id },
+ });
+ });
+
+ it('throws if provided an invalid location scope', () => {
+ const invalidLocation: AccessGrantLocation = {
+ scope: 'nope',
+ permission: 'READ',
+ type: 'BUCKET',
+ };
+
+ expect(() => parseAccessGrantLocation(invalidLocation)).toThrow(
+ 'Invalid scope: nope'
+ );
+ });
+
+ it('throws if provided an invalid location type', () => {
+ const invalidLocation: AccessGrantLocation = {
+ scope: 's3://yes',
+ permission: 'READ',
+ // @ts-expect-error intentional coercing to allow unhappy path test
+ type: 'NOT_BUCKET',
+ };
+
+ expect(() => parseAccessGrantLocation(invalidLocation)).toThrow(
+ 'Invalid location type: NOT_BUCKET'
+ );
+ });
+
+ it('parses a BUCKET location as expected', () => {
+ const location: AccessGrantLocation = {
+ permission: 'WRITE',
+ scope: `s3://${bucket}/*`,
+ type: 'BUCKET',
+ };
+ const expected: LocationData = {
+ bucket,
+ id,
+ prefix: '',
+ permissions: ['delete', 'write'],
+ type: 'BUCKET',
+ };
+
+ expect(parseAccessGrantLocation(location)).toStrictEqual(expected);
+ });
+
+ it('parses a PREFIX location as expected', () => {
+ const location: AccessGrantLocation = {
+ permission: 'WRITE',
+ scope: `s3://${bucket}/${folderPrefix}*`,
+ type: 'PREFIX',
+ };
+
+ const expected: LocationData = {
+ bucket,
+ id,
+ prefix: folderPrefix,
+ permissions: ['delete', 'write'],
+ type: 'PREFIX',
+ };
+
+ expect(parseAccessGrantLocation(location)).toStrictEqual(expected);
+ });
+
+ it('parses an OBJECT location as expected', () => {
+ const location: AccessGrantLocation = {
+ permission: 'WRITE',
+ scope: `s3://${bucket}/${folderPrefix}${filePath}`,
+ type: 'OBJECT',
+ };
+
+ const expected: LocationData = {
+ bucket,
+ id,
+ prefix: `${folderPrefix}${filePath}`,
+ permissions: ['delete', 'write'],
+ type: 'OBJECT',
+ };
+
+ expect(parseAccessGrantLocation(location)).toStrictEqual(expected);
+ });
+});
+
+describe('getFileKey', () => {
+ it('should return the filename without the path', () => {
+ expect(getFileKey('/path/to/file.txt')).toBe('file.txt');
+ expect(getFileKey('document.pdf')).toBe('document.pdf');
+ });
+
+ it('should handle paths with multiple slashes', () => {
+ expect(getFileKey('/path//to///file.txt')).toBe('file.txt');
+ });
+});
+
+describe('shouldExcludeLocation', () => {
+ const location: LocationData = {
+ bucket: 'bucket',
+ id: 'id',
+ permissions: ['list', 'get'],
+ prefix: 'prefix/',
+ type: 'PREFIX',
+ };
+
+ it('returns true when the provided location permissions match excluded permissions', () => {
+ const output = shouldExcludeLocation(location, {
+ exactPermissions: ['list', 'get'],
+ });
+
+ expect(output).toBe(true);
+ });
+
+ it('returns true when the provided location type match excluded type', () => {
+ const output = shouldExcludeLocation(location, { type: 'PREFIX' });
+
+ expect(output).toBe(true);
+ });
+
+ it('returns false when provided a location without an exclude value', () => {
+ const output = shouldExcludeLocation(location);
+
+ expect(output).toBe(false);
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/copy.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/copy.ts
new file mode 100644
index 00000000000..a214f44cfa0
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/copy.ts
@@ -0,0 +1,67 @@
+import { copy, CopyInput } from '../../storage-internal';
+import {
+ FileDataItem,
+ TaskHandler,
+ TaskHandlerInput,
+ TaskHandlerOptions,
+ TaskHandlerOutput,
+} from './types';
+
+import { constructBucket } from './utils';
+
+export interface CopyHandlerData extends FileDataItem {}
+
+export interface CopyHandlerInput
+ extends TaskHandlerInput {
+ destinationPrefix: string;
+}
+export interface CopyHandlerOutput extends TaskHandlerOutput {}
+
+export interface CopyHandler
+ extends TaskHandler {}
+
+export const copyHandler: CopyHandler = (input) => {
+ const { config, destinationPrefix: path, data } = input;
+ const {
+ accountId: expectedBucketOwner,
+ credentials,
+ customEndpoint,
+ } = config;
+ const { key: sourcePath, fileKey, lastModified, eTag } = data;
+
+ const bucket = constructBucket(config);
+
+ const destinationPath = `${path}${fileKey}`;
+ const source: CopyInput['source'] = {
+ bucket,
+ expectedBucketOwner,
+ /**
+ * Per S3 requirement, copy source must the URI encoded.
+ * This is NOT added to Amplify JS v6 because it will be a breaking
+ * change to suddenly introduce URI encode to copy API source.
+ *
+ * see: https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html#API_CopyObject_RequestSyntax
+ */
+ path: sourcePath.split('/').map(encodeURIComponent).join('/'),
+ notModifiedSince: lastModified,
+ eTag,
+ };
+
+ const destination: CopyInput['destination'] = {
+ bucket,
+ expectedBucketOwner,
+ path: destinationPath,
+ };
+
+ const result = copy({
+ source,
+ destination,
+ options: { locationCredentialsProvider: credentials, customEndpoint },
+ });
+
+ return {
+ result: result
+ .then(() => ({ status: 'COMPLETE' as const }))
+ .catch(({ message }: Error) => ({ message, status: 'FAILED' as const })),
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/createFolder.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/createFolder.ts
new file mode 100644
index 00000000000..4ba599a96c4
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/createFolder.ts
@@ -0,0 +1,64 @@
+import { uploadData } from '../../storage-internal';
+import { isFunction } from '@aws-amplify/ui';
+
+import {
+ TaskData,
+ TaskHandler,
+ TaskHandlerInput,
+ TaskHandlerOutput,
+ TaskHandlerOptions,
+} from './types';
+import { constructBucket, getProgress } from './utils';
+
+export interface CreateFolderHandlerData extends TaskData {}
+export interface CreateFolderHandlerOptions extends TaskHandlerOptions {
+ preventOverwrite?: boolean;
+}
+
+export interface CreateFolderHandlerInput
+ extends TaskHandlerInput<
+ CreateFolderHandlerData,
+ CreateFolderHandlerOptions
+ > {
+ destinationPrefix: string;
+}
+
+export interface CreateFolderHandlerOutput extends TaskHandlerOutput {}
+
+export interface CreateFolderHandler
+ extends TaskHandler {}
+
+export const createFolderHandler: CreateFolderHandler = (input) => {
+ const { destinationPrefix, config, data, options } = input;
+ const { accountId, credentials, customEndpoint } = config;
+ const { onProgress, preventOverwrite } = options ?? {};
+ const { key } = data;
+
+ const bucket = constructBucket(config);
+
+ const { result } = uploadData({
+ path: `${destinationPrefix}${key}`,
+ data: '',
+ options: {
+ bucket,
+ expectedBucketOwner: accountId,
+ locationCredentialsProvider: credentials,
+ customEndpoint,
+ onProgress: (event) => {
+ if (isFunction(onProgress)) onProgress(data, getProgress(event));
+ },
+ preventOverwrite,
+ },
+ });
+
+ return {
+ result: result
+ .then(() => ({ status: 'COMPLETE' as const }))
+ .catch(({ message, name }: Error) => {
+ if (name === 'PreconditionFailed') {
+ return { message, status: 'OVERWRITE_PREVENTED' } as const;
+ }
+ return { message, status: 'FAILED' as const };
+ }),
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/delete.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/delete.ts
new file mode 100644
index 00000000000..7ce1b4aaf22
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/delete.ts
@@ -0,0 +1,46 @@
+import { remove } from '../../storage-internal';
+
+import {
+ TaskHandler,
+ TaskHandlerOptions,
+ TaskHandlerInput,
+ TaskHandlerOutput,
+ FileDataItem,
+} from './types';
+
+import { constructBucket } from './utils';
+
+export interface DeleteHandlerOptions extends TaskHandlerOptions {}
+
+export interface DeleteHandlerData extends FileDataItem {}
+
+export interface DeleteHandlerInput
+ extends TaskHandlerInput {}
+
+export interface DeleteHandlerOutput extends TaskHandlerOutput {}
+
+export interface DeleteHandler
+ extends TaskHandler {}
+
+export const deleteHandler: DeleteHandler = ({
+ config,
+ data: { key },
+}): DeleteHandlerOutput => {
+ const { accountId, credentials, customEndpoint } = config;
+
+ const result = remove({
+ path: key,
+ options: {
+ bucket: constructBucket(config),
+ locationCredentialsProvider: credentials,
+ expectedBucketOwner: accountId,
+ customEndpoint,
+ },
+ });
+
+ return {
+ result: result
+ .then(() => ({ status: 'COMPLETE' as const }))
+ .catch(({ message }: Error) => ({ message, status: 'FAILED' as const })),
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/download.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/download.ts
new file mode 100644
index 00000000000..63cb0f7e3ac
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/download.ts
@@ -0,0 +1,64 @@
+import { getUrl } from '../../storage-internal';
+import {
+ FileDataItem,
+ TaskHandler,
+ TaskHandlerInput,
+ TaskHandlerOptions,
+ TaskHandlerOutput,
+} from './types';
+
+import { constructBucket } from './utils';
+
+export interface DownloadHandlerData extends FileDataItem {}
+export interface DownloadHandlerOptions extends TaskHandlerOptions {}
+
+export interface DownloadHandlerInput
+ extends TaskHandlerInput {}
+
+export interface DownloadHandlerOutput extends TaskHandlerOutput {}
+
+export interface DownloadHandler
+ extends TaskHandler {}
+
+function downloadFromUrl(fileName: string, url: string) {
+ const a = document.createElement('a');
+
+ a.href = url;
+ a.download = fileName;
+ a.target = '_blank';
+ document.body.appendChild(a);
+
+ a.click();
+
+ document.body.removeChild(a);
+}
+
+export const downloadHandler: DownloadHandler = ({
+ config,
+ data: { key },
+}): DownloadHandlerOutput => {
+ const { accountId, credentials, customEndpoint } = config;
+
+ const result = getUrl({
+ path: key,
+ options: {
+ bucket: constructBucket(config),
+ customEndpoint,
+ locationCredentialsProvider: credentials,
+ validateObjectExistence: true,
+ contentDisposition: 'attachment',
+ expectedBucketOwner: accountId,
+ },
+ }).then((result) => {
+ return result;
+ });
+
+ return {
+ result: result
+ .then(({ url }) => {
+ downloadFromUrl(key, url.toString());
+ return { status: 'COMPLETE' as const };
+ })
+ .catch(({ message }: Error) => ({ message, status: 'FAILED' as const })),
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/index.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/index.ts
new file mode 100644
index 00000000000..c093f1ba0d7
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/index.ts
@@ -0,0 +1,9 @@
+export * from './copy';
+export * from './createFolder';
+export * from './delete';
+export * from './download';
+export * from './listLocationItems';
+export * from './listLocations';
+export * from './upload';
+export * from './utils';
+export * from './types';
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/listLocationItems.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/listLocationItems.ts
new file mode 100644
index 00000000000..2fe3c8f38dd
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/listLocationItems.ts
@@ -0,0 +1,156 @@
+import {
+ list,
+ StorageSubpathStrategy,
+ ListPaginateInput,
+ ListOutput,
+} from '../../storage-internal';
+import {
+ ListHandler,
+ ListHandlerInput,
+ ListHandlerOptions,
+ ListHandlerOutput,
+ LocationItemData,
+} from './types';
+
+const DEFAULT_PAGE_SIZE = 1000;
+
+type ListOutputItem = ListOutput['items'][number];
+
+export type LocationItemType = LocationItemData['type'];
+
+export interface ListLocationItemsHandlerOptions
+ extends ListHandlerOptions {
+ delimiter?: string;
+ query?: string;
+}
+
+export interface ListLocationItemsHandlerInput
+ extends ListHandlerInput {}
+
+export interface ListLocationItemsHandlerOutput
+ extends ListHandlerOutput {}
+
+export interface ListLocationItemsHandler
+ extends ListHandler<
+ ListLocationItemsHandlerInput,
+ ListLocationItemsHandlerOutput
+ > {}
+
+const parseItems = (
+ items: ListOutputItem[],
+ excludedPath: string
+): LocationItemData[] =>
+ items
+ // remove root `key` from results
+ .filter(({ path }) => path !== excludedPath)
+ .map(({ path: key, lastModified, size, eTag }) => {
+ const id = crypto.randomUUID();
+ // Mark zero byte files as Folders
+ if (size === 0 && key.endsWith('/')) {
+ return { key, id, type: 'FOLDER' };
+ }
+
+ return {
+ key,
+ id,
+ eTag,
+ lastModified: lastModified!,
+ size: size!,
+ type: 'FILE',
+ };
+ });
+
+const parseExcludedPaths = (paths: string[] | undefined): LocationItemData[] =>
+ paths?.map((key) => ({ key, id: crypto.randomUUID(), type: 'FOLDER' })) ?? [];
+
+export const filterDotItems = (
+ items: LocationItemData[],
+ prefix: string
+): LocationItemData[] =>
+ items.filter((item) => {
+ const key = (
+ item.key.startsWith(prefix) ? item.key.substring(prefix.length) : item.key
+ ).trim();
+ // matches object keys that would cause problems either as folder names in navigation (`/`, `./`, `../`) or as objects (`.`, `..`)
+ return !(
+ key === '/' ||
+ key === './' ||
+ key === '../' ||
+ key === '.' ||
+ key === '..'
+ );
+ });
+
+export const parseResult = (
+ { excludedSubpaths, items }: ListOutput,
+ prefix: string
+): LocationItemData[] =>
+ filterDotItems(
+ [...parseExcludedPaths(excludedSubpaths), ...parseItems(items, prefix)],
+ prefix
+ );
+
+export const listLocationItemsHandler: ListLocationItemsHandler = async (
+ input
+) => {
+ const { config, prefix, options } = input;
+ const {
+ bucket: _bucket,
+ credentials,
+ customEndpoint,
+ region,
+ accountId,
+ } = config;
+
+ const {
+ exclude,
+ delimiter,
+ nextToken,
+ pageSize: _pageSize = DEFAULT_PAGE_SIZE,
+ ..._options
+ } = options ?? {};
+
+ const bucket = { bucketName: _bucket, region };
+ const subpathStrategy: StorageSubpathStrategy = {
+ delimiter,
+ strategy: delimiter ? 'exclude' : 'include',
+ };
+
+ // `ListObjectsV2` returns the root `key` on initial request, which is from
+ // filtered from `results` by `parseResult`, creatimg a scenario where the
+ // return count of `results` to be one item less than provided the `pageSize`.
+ // To mitigate, if a `pageSize` is provided and there are no previous `results`
+ // or `refresh` is `true` increment the provided `pageSize` by `1`
+ const hasOffset = !nextToken;
+ const pageSize = hasOffset ? _pageSize + 1 : _pageSize;
+
+ const result: LocationItemData[] = [];
+ let nextNextToken = nextToken;
+
+ do {
+ const listInput: ListPaginateInput = {
+ path: prefix,
+ options: {
+ nextToken: nextNextToken,
+ ..._options,
+ bucket,
+ customEndpoint,
+ expectedBucketOwner: accountId,
+ locationCredentialsProvider: credentials,
+ pageSize,
+ subpathStrategy,
+ },
+ };
+
+ const output = await list(listInput);
+ nextNextToken = output.nextToken;
+
+ const items = parseResult(output, prefix);
+
+ result.push(
+ ...(exclude ? items.filter((item) => item.type !== exclude) : items)
+ );
+ } while (nextNextToken && result.length < pageSize);
+
+ return { items: result, nextToken: nextNextToken };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/listLocations.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/listLocations.ts
new file mode 100644
index 00000000000..b85ba3c3460
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/listLocations.ts
@@ -0,0 +1,90 @@
+import {
+ listCallerAccessGrants,
+ LocationCredentialsProvider,
+} from '../../storage-internal';
+import { assertAccountId } from '../../validators';
+
+import {
+ ListHandlerOptions,
+ ListHandler,
+ ListLocationsExcludeOptions,
+ LocationData,
+} from './types';
+import { getFilteredLocations } from './utils';
+
+const DEFAULT_PAGE_SIZE = 1000;
+
+export interface ListLocationsOptions extends ListLocationsHandlerOptions {}
+
+export interface ListLocationsInput {
+ options?: ListLocationsOptions;
+}
+
+export interface ListLocationsOutput {
+ items: LocationData[];
+ nextToken: string | undefined;
+}
+
+// `ListLocations` and its associated input/output types are the types
+// used `Config` option of `CreateStorageBrowser` that do not require
+// `config` values as they are provided through higher-order functions
+// defined in the default and managed auth adapters
+export interface ListLocations
+ extends ListHandler {}
+
+export interface ListLocationsHandlerOptions
+ extends ListHandlerOptions {}
+
+export interface ListLocationsHandlerInput {
+ options?: ListLocationsHandlerOptions;
+ config: {
+ accountId?: string;
+ credentials: LocationCredentialsProvider;
+ customEndpoint?: string;
+ region: string;
+ };
+}
+
+export interface ListLocationsHandlerOutput {
+ items: LocationData[];
+ nextToken: string | undefined;
+}
+
+export interface ListLocationsHandler
+ extends ListHandler {}
+
+export const listLocationsHandler: ListLocationsHandler = async (input) => {
+ const { config, options } = input;
+ const { accountId, credentials, customEndpoint, region } = config;
+ const { exclude, nextToken, pageSize = DEFAULT_PAGE_SIZE } = options ?? {};
+
+ const fetchLocations = async (
+ accumulatedItems: LocationData[],
+ locationsNextToken: ListLocationsOutput['nextToken']
+ ): Promise => {
+ const remainingPageSize = pageSize - accumulatedItems.length;
+
+ assertAccountId(accountId);
+
+ const output = await listCallerAccessGrants({
+ accountId,
+ credentialsProvider: credentials,
+ customEndpoint,
+ nextToken: locationsNextToken,
+ pageSize: remainingPageSize,
+ region,
+ });
+
+ const parsedOutput = getFilteredLocations(output.locations, exclude);
+
+ const items = [...accumulatedItems, ...parsedOutput];
+
+ if (output.nextToken && items.length < pageSize) {
+ return fetchLocations(items, output.nextToken);
+ }
+
+ return { items, nextToken: output.nextToken };
+ };
+
+ return fetchLocations([], nextToken);
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/types.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/types.ts
new file mode 100644
index 00000000000..25fd7df1abc
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/types.ts
@@ -0,0 +1,127 @@
+import { LocationCredentialsProvider } from '../../storage-internal';
+
+export type LocationType = 'OBJECT' | 'PREFIX' | 'BUCKET';
+
+export type LocationPermissions = ('delete' | 'get' | 'list' | 'write')[];
+
+/**
+ * `location` metadata
+ */
+export interface LocationData {
+ /**
+ * `location` s3 bucket
+ */
+ bucket: string;
+
+ /**
+ * Unique identifier
+ */
+ id: string;
+
+ /**
+ * `location` permission granted to user
+ */
+ permissions: LocationPermissions;
+
+ /**
+ * `location` base prefix, delimited by `'/'`. Empty string indicates bucket root
+ */
+ prefix: string;
+
+ /**
+ * `location` grant scope
+ *
+ * @type "OBJECT" | "PREFIX" | "BUCKET"
+ */
+ type: LocationType;
+}
+
+export interface FolderData {
+ key: string;
+ id: string;
+ type: 'FOLDER';
+}
+
+export interface FileData {
+ eTag?: string;
+ key: string;
+ lastModified: Date;
+ id: string;
+ size: number;
+ type: 'FILE';
+}
+
+export type LocationItemData = FileData | FolderData;
+
+export interface FileDataItem extends FileData, TaskData {
+ fileKey: string;
+}
+
+export interface FileItem extends TaskData {
+ file: File;
+}
+
+export interface ActionInputConfig {
+ accountId?: string;
+ bucket: string;
+ credentials: LocationCredentialsProvider;
+ customEndpoint?: string;
+ region: string;
+}
+
+interface ActionInput {
+ config: ActionInputConfig;
+ prefix: string;
+ options?: T;
+}
+
+export interface TaskData {
+ key: string;
+ id: string;
+}
+
+export interface TaskHandlerOptions {
+ onProgress?: (
+ data: { key: string; id: string },
+ progress: number | undefined
+ ) => void;
+}
+
+export interface TaskHandlerInput<
+ T extends TaskData = TaskData,
+ K extends TaskHandlerOptions = TaskHandlerOptions,
+> {
+ config: ActionInputConfig;
+ data: T;
+ options?: K;
+}
+
+export interface TaskHandlerOutput {
+ cancel?: () => void;
+ result: Promise<{
+ message?: string;
+ status: 'CANCELED' | 'COMPLETE' | 'FAILED' | 'OVERWRITE_PREVENTED';
+ }>;
+}
+
+export type TaskHandler = (input: T) => K;
+
+export interface ListHandlerOptions {
+ exclude?: T;
+ nextToken?: string;
+ pageSize?: number;
+}
+
+export interface ListHandlerInput extends ActionInput {}
+
+export interface ListHandlerOutput {
+ nextToken: string | undefined;
+ items: T[];
+}
+
+export type ListHandler = (input: T) => Promise;
+
+export interface ListLocationsExcludeOptions {
+ exactPermissions?: LocationPermissions;
+ type?: LocationType | LocationType[];
+}
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/upload.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/upload.ts
new file mode 100644
index 00000000000..d42b7b7ef38
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/upload.ts
@@ -0,0 +1,89 @@
+import { isCancelError } from 'aws-amplify/storage';
+import { isFunction } from '@aws-amplify/ui';
+
+import { uploadData, UploadDataInput } from '../../storage-internal';
+
+import {
+ TaskData,
+ TaskHandler,
+ TaskHandlerInput,
+ TaskHandlerOutput,
+ TaskHandlerOptions,
+} from './types';
+
+import { constructBucket, getProgress } from './utils';
+
+export interface UploadHandlerOptions extends TaskHandlerOptions {
+ preventOverwrite?: boolean;
+}
+
+export interface UploadHandlerData extends TaskData {
+ file: File;
+}
+
+export interface UploadHandlerInput
+ extends TaskHandlerInput {
+ destinationPrefix: string;
+}
+
+export interface UploadHandlerOutput extends TaskHandlerOutput {}
+
+export interface UploadHandler
+ extends TaskHandler {}
+
+// 5MB for multipart upload
+// https://github.com/aws-amplify/amplify-js/blob/1a5366d113c9af4ce994168653df3aadb142c581/packages/storage/src/providers/s3/utils/constants.ts#L16
+export const MULTIPART_UPLOAD_THRESHOLD_BYTES = 5 * 1024 * 1024;
+
+export const UNDEFINED_CALLBACKS = {
+ cancel: undefined,
+ pause: undefined,
+ resume: undefined,
+};
+
+export const uploadHandler: UploadHandler = ({
+ config,
+ data,
+ destinationPrefix,
+ options,
+}) => {
+ const { accountId, credentials, customEndpoint } = config;
+ const { key, file } = data;
+ const { onProgress, preventOverwrite } = options ?? {};
+
+ const input: UploadDataInput = {
+ path: `${destinationPrefix}${key}`,
+ data: file,
+ options: {
+ bucket: constructBucket(config),
+ expectedBucketOwner: accountId,
+ locationCredentialsProvider: credentials,
+ onProgress: (event) => {
+ if (isFunction(onProgress)) onProgress(data, getProgress(event));
+ },
+ preventOverwrite,
+ customEndpoint,
+ checksumAlgorithm: 'crc-32',
+ },
+ };
+
+ const { cancel, pause, resume, result } = uploadData(input);
+
+ return {
+ ...(file.size > MULTIPART_UPLOAD_THRESHOLD_BYTES
+ ? { cancel, pause, resume }
+ : UNDEFINED_CALLBACKS),
+ result: result
+ .then(() => ({ status: 'COMPLETE' as const }))
+ .catch((error: Error) => {
+ const { message } = error;
+ if (error.name === 'PreconditionFailed') {
+ return { message, status: 'OVERWRITE_PREVENTED' as const };
+ }
+ return {
+ message,
+ status: isCancelError(error) ? 'CANCELED' : 'FAILED',
+ };
+ }),
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/handlers/utils.ts b/packages/react-storage/src/components/StorageBrowser/actions/handlers/utils.ts
new file mode 100644
index 00000000000..99610f61541
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/handlers/utils.ts
@@ -0,0 +1,172 @@
+import { TransferProgressEvent } from 'aws-amplify/storage';
+import { LocationAccess as AccessGrantLocation } from '../../storage-internal';
+import { ListLocationsExcludeOptions } from './types';
+
+import {
+ ActionInputConfig,
+ FileData,
+ FileDataItem,
+ FileItem,
+ LocationData,
+ LocationPermissions,
+ LocationType,
+} from './types';
+
+export const constructBucket = ({
+ bucket: bucketName,
+ region,
+}: Pick): {
+ bucketName: string;
+ region: string;
+} => ({ bucketName, region });
+
+export const parseAccessGrantLocation = (
+ location: AccessGrantLocation
+): LocationData => {
+ const { permission, scope, type } = location;
+ if (!scope.startsWith('s3://')) {
+ throw new Error(`Invalid scope: ${scope}`);
+ }
+
+ const id = crypto.randomUUID();
+
+ // remove default path
+ const slicedScope = scope.slice(5);
+ let bucket, prefix;
+
+ switch (type) {
+ case 'BUCKET': {
+ // { scope: 's3://bucket/*', type: 'BUCKET', },
+ bucket = slicedScope.slice(0, -2);
+ prefix = '';
+ break;
+ }
+ case 'PREFIX': {
+ // { scope: 's3://bucket/path/*', type: 'PREFIX', },
+ bucket = slicedScope.slice(0, slicedScope.indexOf('/'));
+ prefix = `${slicedScope.slice(bucket.length + 1, -1)}`;
+ break;
+ }
+ case 'OBJECT': {
+ // { scope: 's3://bucket/path/to/object', type: 'OBJECT', },
+ bucket = slicedScope.slice(0, slicedScope.indexOf('/'));
+ prefix = slicedScope.slice(bucket.length + 1);
+ break;
+ }
+ default: {
+ throw new Error(`Invalid location type: ${type}`);
+ }
+ }
+
+ let permissions: LocationPermissions;
+ switch (permission) {
+ case 'READ':
+ permissions = ['get', 'list'];
+ break;
+ case 'READWRITE':
+ permissions = ['delete', 'get', 'list', 'write'];
+ break;
+ case 'WRITE':
+ permissions = ['delete', 'write'];
+ break;
+ default:
+ throw new Error(`Invalid location permission: ${permission}`);
+ }
+
+ return { bucket, id, permissions: permissions, prefix, type };
+};
+
+const isSamePermissions = (
+ permissionsToExclude: LocationPermissions,
+ locationPermissions: LocationPermissions
+) => {
+ if (permissionsToExclude.length !== locationPermissions.length) {
+ return false;
+ }
+ const sortedLocationPermissions = locationPermissions.sort();
+ return permissionsToExclude
+ .sort()
+ .every(
+ (permission, index) => permission === sortedLocationPermissions[index]
+ );
+};
+
+const isSameType = (
+ typeToExclude: LocationType | LocationType[],
+ locationType: LocationType
+) =>
+ typeof typeToExclude === 'string'
+ ? typeToExclude === locationType
+ : typeToExclude.includes(locationType);
+
+export const shouldExcludeLocation = (
+ { permissions, type }: LocationData,
+ exclude?: ListLocationsExcludeOptions
+): boolean => {
+ const excludedByPermssions = !!(
+ exclude?.exactPermissions &&
+ isSamePermissions(exclude.exactPermissions, permissions)
+ );
+
+ const excludedByType = !!(exclude?.type && isSameType(exclude.type, type));
+
+ return excludedByPermssions || excludedByType;
+};
+
+export const getFilteredLocations = (
+ locations: AccessGrantLocation[],
+ exclude?: ListLocationsExcludeOptions
+): LocationData[] =>
+ locations.reduce(
+ (filteredLocations: LocationData[], location: AccessGrantLocation) => {
+ const parsedLocation = parseAccessGrantLocation(location);
+
+ const isNonFolderLikePrefix =
+ !parsedLocation.prefix.endsWith('/') &&
+ parsedLocation.type === 'PREFIX';
+
+ if (isNonFolderLikePrefix) {
+ return filteredLocations;
+ }
+
+ if (!shouldExcludeLocation(parsedLocation, exclude)) {
+ filteredLocations.push(parsedLocation);
+ }
+
+ return filteredLocations;
+ },
+ []
+ );
+
+export const getFileKey = (key: string): string =>
+ key.slice(key.lastIndexOf('/') + 1, key.length);
+
+export const createFileDataItem = (data: FileData): FileDataItem => ({
+ ...data,
+ fileKey: getFileKey(data.key),
+});
+
+export const createFileDataItemFromLocation = (
+ data: LocationData
+): FileDataItem => ({
+ id: data.id,
+ type: 'FILE',
+ key: data.prefix,
+ fileKey: getFileKey(data.prefix),
+ // `lastModified` and `size` included to satisfy
+ // expected shape of `FileDataItem`
+ lastModified: new Date(),
+ size: 0,
+});
+
+export const isFileItem = (value: unknown): value is FileItem =>
+ !!(value as FileItem).file;
+
+export const isFileDataItem = (item: unknown): item is FileDataItem =>
+ !!(item as FileDataItem).fileKey;
+
+export const getProgress = ({
+ totalBytes,
+ transferredBytes,
+}: TransferProgressEvent): number | undefined =>
+ totalBytes ? transferredBytes / totalBytes : undefined;
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/index.ts b/packages/react-storage/src/components/StorageBrowser/actions/index.ts
new file mode 100644
index 00000000000..a6fb6f1f009
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/index.ts
@@ -0,0 +1,85 @@
+export {
+ ActionConfigs,
+ ActionConfigsProvider,
+ ActionConfigsProviderProps,
+ ComponentName,
+ defaultActionConfigs,
+ DefaultActionConfigs,
+ defaultActionViewConfigs,
+ DefaultActionKey,
+ isDefaultActionViewType,
+ SelectionType,
+ TaskActionConfig,
+ useActionConfig,
+} from './configs';
+
+export {
+ ActionInputConfig,
+ copyHandler,
+ CopyHandler,
+ CopyHandlerData,
+ CopyHandlerInput,
+ CopyHandlerOutput,
+ createFileDataItemFromLocation,
+ createFileDataItem,
+ createFolderHandler,
+ CreateFolderHandler,
+ CreateFolderHandlerData,
+ CreateFolderHandlerInput,
+ CreateFolderHandlerOptions,
+ CreateFolderHandlerOutput,
+ downloadHandler,
+ DownloadHandler,
+ DownloadHandlerData,
+ DownloadHandlerInput,
+ DownloadHandlerOptions,
+ DownloadHandlerOutput,
+ DeleteHandler,
+ DeleteHandlerData,
+ DeleteHandlerInput,
+ DeleteHandlerOptions,
+ DeleteHandlerOutput,
+ FileData,
+ FileDataItem,
+ FileItem,
+ FolderData,
+ isFileDataItem,
+ isFileItem,
+ ListHandler,
+ ListHandlerInput,
+ ListHandlerOptions,
+ ListHandlerOutput,
+ listLocationItemsHandler,
+ ListLocationItemsHandler,
+ ListLocationItemsHandlerInput,
+ ListLocationItemsHandlerOptions,
+ ListLocationItemsHandlerOutput,
+ ListLocationsExcludeOptions,
+ ListLocations,
+ ListLocationsInput,
+ ListLocationsOutput,
+ listLocationsHandler,
+ ListLocationsHandler,
+ ListLocationsHandlerInput,
+ ListLocationsHandlerOptions,
+ ListLocationsHandlerOutput,
+ LocationData,
+ LocationItemData,
+ LocationPermissions,
+ LocationType,
+ TaskData,
+ TaskHandler,
+ TaskHandlerInput,
+ TaskHandlerOptions,
+ TaskHandlerOutput,
+ uploadHandler,
+ UploadHandler,
+ UploadHandlerData,
+ UploadHandlerInput,
+ UploadHandlerOptions,
+ UploadHandlerOutput,
+} from './handlers';
+
+export { ActionState } from './types';
+
+export { useListLocations, UseListLocationsState } from './useAction';
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/types.ts b/packages/react-storage/src/components/StorageBrowser/actions/types.ts
new file mode 100644
index 00000000000..7a09f7e1089
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/types.ts
@@ -0,0 +1,18 @@
+import { DataState } from '@aws-amplify/ui-react-core';
+
+import { ListHandler, TaskHandler } from './handlers';
+
+export type ActionState = [
+ state: DataState,
+ handleAction: (...input: K[]) => void,
+];
+
+export type UseAction = T extends
+ | ListHandler
+ | TaskHandler
+ ? ActionState
+ : never;
+
+export type CreateUseAction = (
+ actions: T
+) => (key: K) => UseAction;
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/useAction/__tests__/createEnhancedListHandler.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/useAction/__tests__/createEnhancedListHandler.spec.ts
new file mode 100644
index 00000000000..217a169a317
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/useAction/__tests__/createEnhancedListHandler.spec.ts
@@ -0,0 +1,255 @@
+import {
+ createEnhancedListHandler,
+ SEARCH_LIMIT,
+} from '../createEnhancedListHandler';
+import {
+ ActionInputConfig,
+ ListHandler,
+ ListHandlerInput,
+ ListHandlerOutput,
+} from '../../handlers';
+
+const mockAction = jest.fn();
+
+const config: ActionInputConfig = {
+ bucket: 'bucky',
+ credentials: jest.fn(),
+ region: 'us-west-1',
+};
+type Output = ListHandlerOutput<{
+ name: string;
+ alt: string;
+ id: number;
+}>;
+
+type Handler = ListHandler;
+
+describe('createEnhancedListHandler', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('should return an empty state when reset is true', async () => {
+ const handler = createEnhancedListHandler(mockAction);
+ const prevState = { items: [{ id: 1 }], nextToken: 'abc' };
+ const options = { reset: true };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: 'a_prefix',
+ options,
+ });
+
+ expect(result).toEqual({ items: [], nextToken: undefined });
+ });
+
+ it('should collect and filter results when search and prefix is provided', async () => {
+ mockAction
+ .mockResolvedValueOnce({
+ items: [{ name: 'a_prefix/apple' }, { name: 'a_prefix/banana' }],
+ nextToken: 'next',
+ })
+ .mockResolvedValueOnce({
+ items: [{ name: 'a_prefix/cherry' }, { name: 'a_prefix/date' }],
+ nextToken: null,
+ });
+
+ const handler = createEnhancedListHandler(mockAction as Handler);
+ const prevState = { items: [], nextToken: undefined };
+ const options = {
+ search: { query: 'a', filterBy: 'name' as const },
+ };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: 'a_prefix',
+ options,
+ });
+
+ expect(result.items).toEqual([
+ { name: 'a_prefix/apple' },
+ { name: 'a_prefix/banana' },
+ { name: 'a_prefix/date' },
+ ]);
+ expect(result.nextToken).toBeUndefined();
+ });
+
+ it('should collect and filter results when search and empty prefix is provided', async () => {
+ mockAction
+ .mockResolvedValueOnce({
+ items: [{ name: 'foo/bar/apple' }, { name: 'banana' }],
+ nextToken: 'next',
+ })
+ .mockResolvedValueOnce({
+ items: [{ name: 'foo/bar/cherry' }, { name: 'date' }],
+ nextToken: null,
+ });
+
+ const handler = createEnhancedListHandler(mockAction as Handler);
+ const prevState = { items: [], nextToken: undefined };
+ const options = {
+ search: { query: 'a', filterBy: 'name' as const },
+ };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: '',
+ options,
+ });
+
+ expect(result.items).toEqual([
+ { name: 'foo/bar/apple' },
+ { name: 'banana' },
+ { name: 'foo/bar/cherry' },
+ { name: 'date' },
+ ]);
+ expect(result.nextToken).toBeUndefined();
+ expect(result.search?.hasExhaustedSearch).toBeFalsy();
+ });
+
+ it('should collect and filter results using a filter key function', async () => {
+ mockAction
+ .mockResolvedValueOnce({
+ items: [
+ { name: 'foo/bar/apple', alt: 'cosmic-crisp' },
+ { name: 'banana', alt: '' },
+ ],
+ nextToken: 'next',
+ })
+ .mockResolvedValueOnce({
+ items: [
+ { name: 'melon', alt: 'aka-melon' },
+ { name: 'foo/bar/cherry', alt: '' },
+ { name: 'date', alt: '' },
+ ],
+ nextToken: null,
+ });
+
+ const handler = createEnhancedListHandler(mockAction as Handler);
+ const prevState = { items: [], nextToken: undefined };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: '',
+ options: {
+ search: {
+ query: 'a',
+ filterBy: (item) => {
+ return item.alt ? 'alt' : 'name';
+ },
+ },
+ },
+ });
+
+ expect(result.items).toEqual([
+ expect.objectContaining({ name: 'banana' }),
+ expect.objectContaining({ name: 'melon', alt: 'aka-melon' }),
+ expect.objectContaining({ name: 'foo/bar/cherry' }),
+ expect.objectContaining({ name: 'date' }),
+ ]);
+
+ expect(result.nextToken).toBeUndefined();
+ expect(result.search?.hasExhaustedSearch).toBeFalsy();
+ });
+
+ it('should collect and filter results when search and duplicate prefix is provided', async () => {
+ mockAction.mockResolvedValueOnce({
+ items: [{ name: 'foo/bar/cherry' }, { name: 'foo/date/foo' }],
+ nextToken: null,
+ });
+
+ const handler = createEnhancedListHandler(mockAction as Handler);
+ const prevState = { items: [], nextToken: undefined };
+ const options = {
+ search: { query: 'foo', filterBy: 'name' as const },
+ };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: 'foo/',
+ options,
+ });
+
+ expect(result.items).toEqual([{ name: 'foo/date/foo' }]);
+ expect(result.nextToken).toBeUndefined();
+ });
+
+ it('should stop collecting results when SEARCH_LIMIT is reached', async () => {
+ const mockItems = new Array(SEARCH_LIMIT).fill({ name: 'a_prefix/item' });
+ mockAction
+ .mockResolvedValueOnce({
+ items: mockItems.slice(0, SEARCH_LIMIT / 2),
+ nextToken: 'token',
+ })
+ .mockResolvedValueOnce({
+ items: mockItems.slice(SEARCH_LIMIT / 2),
+ nextToken: 'token2',
+ })
+ .mockResolvedValueOnce({ items: mockItems, nextToken: 'token3' });
+
+ const handler = createEnhancedListHandler(mockAction as Handler);
+ const prevState = { items: [], nextToken: undefined };
+ const options = {
+ search: { query: 'item', filterBy: 'name' as const },
+ };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: 'a_prefix',
+ options,
+ });
+
+ expect(mockAction).toHaveBeenCalledTimes(2);
+ expect(result.items.length).toBe(SEARCH_LIMIT);
+ expect(result.nextToken).toBeUndefined();
+ expect(result.search?.hasExhaustedSearch).toBeTruthy();
+
+ mockAction.mockReset();
+ });
+
+ it('should ignore provided nextToken on refresh', async () => {
+ mockAction.mockResolvedValue({
+ items: [{ id: 1 }, { id: 2 }],
+ nextToken: 'next',
+ });
+
+ const handler = createEnhancedListHandler(mockAction);
+ const prevState = { items: [{ id: 0 }], nextToken: 'abc' };
+ const options = { refresh: true, nextToken: 'token' };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: 'a_prefix',
+ options,
+ });
+
+ expect(mockAction).toHaveBeenCalledWith({
+ config,
+ prefix: 'a_prefix',
+ options: { nextToken: undefined },
+ });
+
+ expect(result.items).toEqual([{ id: 1 }, { id: 2 }]);
+ expect(result.nextToken).toBe('next');
+ });
+
+ it('should append items when refresh is false', async () => {
+ mockAction.mockResolvedValue({
+ items: [{ id: 2 }, { id: 3 }],
+ nextToken: 'next',
+ });
+
+ const handler = createEnhancedListHandler(mockAction);
+ const prevState = { items: [{ id: 1 }], nextToken: 'abc' };
+ const options = { refresh: false };
+
+ const result = await handler(prevState, {
+ config,
+ prefix: 'a_prefix',
+ options,
+ });
+
+ expect(result.items).toEqual([{ id: 1 }, { id: 2 }, { id: 3 }]);
+ expect(result.nextToken).toBe('next');
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/useAction/__tests__/search.spec.ts b/packages/react-storage/src/components/StorageBrowser/actions/useAction/__tests__/search.spec.ts
new file mode 100644
index 00000000000..78a8af4b6eb
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/useAction/__tests__/search.spec.ts
@@ -0,0 +1,430 @@
+import { searchItems } from '../createEnhancedListHandler';
+
+let uuid = 0;
+Object.defineProperty(globalThis, 'crypto', {
+ value: {
+ randomUUID: () => {
+ uuid++;
+ return uuid.toString();
+ },
+ },
+});
+
+interface Item {
+ key: string;
+}
+
+describe('Search', () => {
+ it('should handle empty lists', () => {
+ const result = searchItems({
+ prefix: '',
+ list: [],
+ options: {
+ query: 'test',
+ filterBy: 'path',
+ groupBy: '/',
+ },
+ });
+
+ expect(result).toEqual([]);
+ });
+
+ it('should return all items matching the prefix when the query is empty', () => {
+ const mockData = [{ key: 'folder/file1.txt' }, { key: 'folder/file2.txt' }];
+
+ const result = searchItems({
+ prefix: 'folder/',
+ list: mockData,
+ options: {
+ query: '',
+ filterBy: 'key',
+ groupBy: '/',
+ },
+ });
+
+ expect(result).toEqual([
+ { id: expect.any(String), key: 'folder/file1.txt', type: 'FILE' },
+ { id: expect.any(String), key: 'folder/file2.txt', type: 'FILE' },
+ ]);
+ });
+
+ it('should return an empty array when no items match the query', () => {
+ const list = [{ key: '/folder/file1.txt' }, { key: '/folder/file2.txt' }];
+
+ const result = searchItems({
+ prefix: '/folder',
+ list,
+ options: {
+ query: 'nonexistent',
+ filterBy: 'key',
+ groupBy: '/',
+ },
+ });
+
+ expect(result).toEqual([]);
+ });
+
+ describe('group by', () => {
+ it('should handle root level objects', () => {
+ const mockData = [
+ {
+ key: 'photo1.jpg',
+ },
+ {
+ key: 'photos/',
+ },
+ {
+ key: 'pic.jpg',
+ },
+ ];
+
+ const output = searchItems- ({
+ list: mockData,
+ prefix: '',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'photo',
+ },
+ });
+ expect(output).toEqual([
+ { id: expect.any(String), key: 'photo1.jpg', type: 'FILE' },
+ { id: expect.any(String), key: 'photos/', type: 'FOLDER' },
+ ]);
+ });
+
+ it('should handle single level structures', () => {
+ const mockData = [
+ {
+ key: 'collections/photo1.jpg',
+ },
+ {
+ key: 'collections/photo2.jpg',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'photo',
+ },
+ });
+
+ expect(output).toEqual([
+ { id: expect.any(String), key: 'collections/photo1.jpg', type: 'FILE' },
+ { id: expect.any(String), key: 'collections/photo2.jpg', type: 'FILE' },
+ ]);
+ });
+
+ it('should handle multi level structures', () => {
+ const mockData = [
+ {
+ key: 'collections/photos/beach.jpg',
+ },
+ {
+ key: 'collections/photos/pic.jpg',
+ },
+ {
+ key: 'collections/photos/hawaii/beaches/beach.jpg',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'beach',
+ },
+ });
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'collections/photos/beach.jpg',
+ type: 'FILE',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/photos/hawaii/beaches/',
+ type: 'FOLDER',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/photos/hawaii/beaches/beach.jpg',
+ type: 'FILE',
+ },
+ ]);
+ });
+
+ it('de-dupes paths', () => {
+ const mockData = [
+ {
+ key: 'collections/photos/beach.jpg',
+ },
+ {
+ key: 'collections/photos/pic.jpg',
+ },
+ {
+ key: 'collections/photos/hawaii/beaches/beach.jpg',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'photos',
+ },
+ });
+ expect(output).toEqual([
+ { id: expect.any(String), key: 'collections/photos/', type: 'FOLDER' },
+ ]);
+ });
+
+ it('handles complex group-by delimiters', () => {
+ const mockData = [
+ {
+ key: 'collections<.>photos<.>beach.jpg',
+ },
+ {
+ key: 'collections<.>photos<.>pic.jpg',
+ },
+ {
+ key: 'collections<.>beaches<.>beach<.>',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '<.>',
+ query: 'beach',
+ },
+ });
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'collections<.>photos<.>beach.jpg',
+ type: 'FILE',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections<.>beaches<.>',
+ type: 'FOLDER',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections<.>beaches<.>beach<.>',
+ type: 'FOLDER',
+ },
+ ]);
+ });
+
+ it('should only match paths ahead of prefix', () => {
+ const mockData = [
+ {
+ key: 'photos/album/random-photos/photo1.jpg',
+ },
+ {
+ key: 'photos/album/cats/pic.jpg',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'photos/album/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'photo',
+ },
+ });
+
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'photos/album/random-photos/',
+ type: 'FOLDER',
+ },
+ {
+ id: expect.any(String),
+ key: 'photos/album/random-photos/photo1.jpg',
+ type: 'FILE',
+ },
+ ]);
+ });
+
+ it('should handle consecutive delimiters', () => {
+ const mockData = [
+ {
+ key: 'collections////photo1.jpg',
+ },
+ {
+ key: 'collections/photos///',
+ },
+ {
+ key: 'collections//animals//',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'photo',
+ },
+ });
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'collections////photo1.jpg',
+ type: 'FILE',
+ },
+ { id: expect.any(String), key: 'collections/photos/', type: 'FOLDER' },
+ ]);
+ });
+
+ it('should handle special characters', () => {
+ const mockData = [
+ {
+ key: 'collections/special!@#$/photo1.jpg',
+ },
+ {
+ key: 'collections/ photo folder with spaces /',
+ },
+ {
+ key: 'collections/ wildlife\x00photos.jpg ',
+ },
+ {
+ key: 'collections/nomatch',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'photo',
+ },
+ });
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'collections/special!@#$/photo1.jpg',
+ type: 'FILE',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/ photo folder with spaces /',
+ type: 'FOLDER',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/ wildlife\x00photos.jpg ',
+ type: 'FILE',
+ },
+ ]);
+ });
+
+ it('should be case insensitive', () => {
+ const mockData = [
+ {
+ key: 'collections/seattle/Cafè.jpg',
+ },
+ {
+ key: 'collections/ Ca\uFB00e\x01photos.jpg ',
+ },
+ {
+ key: 'collections/album/CaFe/',
+ },
+ {
+ key: 'collections/album/random/cafe-vita.png',
+ },
+ {
+ key: 'collections/album/random/pic.jpg',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'càf',
+ },
+ });
+
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'collections/seattle/Cafè.jpg',
+ type: 'FILE',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/ Ca\uFB00e\x01photos.jpg ',
+ type: 'FILE',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/album/CaFe/',
+ type: 'FOLDER',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/album/random/cafe-vita.png',
+ type: 'FILE',
+ },
+ ]);
+ });
+ it('ignores diacritics', () => {
+ const mockData = [
+ {
+ key: 'collections/São Paulo/',
+ },
+ {
+ key: 'collections/random/Sãopaulino.jpg',
+ },
+ {
+ key: 'collections/random/photos.jpg ',
+ },
+ ];
+
+ const output = searchItems
- ({
+ list: mockData,
+ prefix: 'collections/',
+ options: {
+ filterBy: 'key',
+ groupBy: '/',
+ query: 'sao',
+ },
+ });
+
+ expect(output).toEqual([
+ {
+ id: expect.any(String),
+ key: 'collections/São Paulo/',
+ type: 'FOLDER',
+ },
+ {
+ id: expect.any(String),
+ key: 'collections/random/Sãopaulino.jpg',
+ type: 'FILE',
+ },
+ ]);
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/useAction/createEnhancedListHandler.ts b/packages/react-storage/src/components/StorageBrowser/actions/useAction/createEnhancedListHandler.ts
new file mode 100644
index 00000000000..abb909eec2b
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/useAction/createEnhancedListHandler.ts
@@ -0,0 +1,218 @@
+import { AsyncDataAction } from '@aws-amplify/ui-react-core';
+
+import {
+ ListHandler,
+ ListHandlerOptions,
+ ListHandlerInput,
+ ListHandlerOutput,
+} from '../handlers';
+
+type KeyWithStringValue = keyof {
+ [P in keyof T as T[P] extends string ? P : never]: T[P];
+};
+
+interface SearchOptions {
+ query: string;
+ /**
+ * The key of the object in the list to filter by, which must have a string value.
+ * Also accepts a function which takes an item and returns the appropriate key.
+ * This determines where the `query` will be searched.
+ */
+ filterBy: KeyWithStringValue | ((item: T) => KeyWithStringValue);
+
+ /**
+ * Optional delimiter to group item keys.
+ */
+ groupBy?: string;
+}
+
+export interface EnhancedListHandlerOptions
+ extends ListHandlerOptions {
+ refresh?: boolean;
+ reset?: boolean;
+ search?: SearchOptions;
+}
+
+export interface SearchOutput {
+ hasExhaustedSearch: boolean;
+}
+
+export interface EnhancedListHandlerOutput extends ListHandlerOutput {
+ search?: SearchOutput;
+}
+
+export interface EnhancedListHandlerInput
+ extends ListHandlerInput> {}
+
+export interface EnhancedListHandler
+ extends AsyncDataAction<
+ EnhancedListHandlerOutput,
+ EnhancedListHandlerInput
+ > {}
+
+type ListItem = Action extends ListHandler<
+ any,
+ ListHandlerOutput
+>
+ ? T
+ : never;
+
+type Options = Action extends ListHandler<
+ ListHandlerInput>
+>
+ ? E
+ : never;
+
+export const SEARCH_LIMIT = 10000;
+export const SEARCH_PAGE_SIZE = 1000;
+
+/**
+ * Normalizes and converts a string to lower case,
+ * handling Unicode characters and locale-specific case mappings.
+ * Uses NFKD to fully decompose unicode: https://unicode.org/reports/tr15/#Normalization_Forms_Table
+ */
+function normalize(input: string) {
+ return input
+ .normalize('NFKD')
+ .replace(/[\u0300-\u036f]/g, '') // remove diacritic modifiers
+ .toLocaleLowerCase();
+}
+
+/**
+ * Performs a case-insensitive check to determine if a string includes another string,
+ * handling Unicode characters and locale-specific case mappings.
+ *
+ * @param {string} input - The string to search within.
+ * @param {string} query - The substring to search for.
+ * @returns {boolean} - Returns `true` if `query` is found in `input` (case-insensitively), otherwise `false`.
+ *
+ * @example
+ * caseInsensitiveIncludes("Photos", "photo"); // true
+ * caseInsensitiveIncludes("Hello", "HELLO"); // true
+ * caseInsensitiveIncludes("\uFB00", "\u0046\u0046"); // ff = FF true
+ * caseInsensitiveIncludes("Cafè", "cafe"); // true
+ */
+function caseInsensitiveIncludes(input: string, query: string): boolean {
+ return normalize(input).includes(normalize(query));
+}
+
+interface Search {
+ prefix?: string;
+ list: T[];
+ options: SearchOptions;
+}
+
+export function searchItems({ prefix = '', list, options }: Search): T[] {
+ const { query, filterBy, groupBy } = options;
+
+ // filter keys that match `filterBy` search option
+ const filteredItems = list.filter((item) => {
+ const key = typeof filterBy === 'function' ? filterBy(item) : filterBy;
+ const path = item[key] as string;
+ const suffix = path.slice(prefix.length);
+ return caseInsensitiveIncludes(suffix, query);
+ });
+
+ if (!groupBy) {
+ return filteredItems;
+ }
+
+ // group items using the provided grouping delimiter
+ const uniquePaths = new Map();
+
+ for (const item of filteredItems) {
+ const key = typeof filterBy === 'function' ? filterBy(item) : filterBy;
+ const path = item[key] as string;
+ const components = path.split(groupBy);
+
+ for (const [i, component] of components.entries()) {
+ if (!caseInsensitiveIncludes(component, query)) {
+ continue;
+ }
+
+ // list of components ending with match
+ const matchedPathSegments = components.slice(0, i + 1);
+
+ // create new path
+ let matchedPath = matchedPathSegments.join(groupBy);
+ const isFolder = matchedPath !== path;
+ if (isFolder) {
+ matchedPath += groupBy;
+ }
+
+ // ignore anything below the prefix for matching
+ if (matchedPath.length > prefix.length && !uniquePaths.has(matchedPath)) {
+ // add a new item
+ uniquePaths.set(matchedPath, {
+ ...item,
+ id: crypto.randomUUID(),
+ [key]: matchedPath,
+ type: isFolder ? 'FOLDER' : 'FILE',
+ });
+ }
+ }
+ }
+
+ return Array.from(uniquePaths.values());
+}
+
+export const createEnhancedListHandler = (
+ action: Action
+): EnhancedListHandler, Options> => {
+ return async function listActionHandler(prevState, { options, ...input }) {
+ const {
+ nextToken: _nextToken,
+ refresh,
+ reset,
+ search,
+ ...rest
+ } = options ?? {};
+
+ if (reset) {
+ return { items: [], nextToken: undefined };
+ }
+
+ // collect and filter results on `search`
+ if (search) {
+ const result = [];
+ let nextNextToken = undefined;
+ do {
+ const output = (await action({
+ ...input,
+ options: {
+ ...rest,
+ pageSize: SEARCH_PAGE_SIZE,
+ nextToken: nextNextToken,
+ },
+ })) as ListHandlerOutput>;
+ result.push(...output.items);
+ nextNextToken = output.nextToken;
+ } while (nextNextToken && result.length < SEARCH_LIMIT);
+
+ return {
+ items: searchItems({
+ list: result,
+ prefix: input.prefix,
+ options: search,
+ }),
+ search: {
+ // search limit reached but we still have a next token
+ hasExhaustedSearch: !!nextNextToken,
+ },
+ nextToken: undefined,
+ };
+ }
+
+ // ignore provided `nextToken` on `refresh`
+ const nextToken = refresh ? undefined : _nextToken;
+ const output = (await action({
+ ...input,
+ options: { ...rest, nextToken },
+ })) as ListHandlerOutput>;
+
+ return {
+ items: [...(refresh ? [] : prevState.items), ...output.items],
+ nextToken: output.nextToken,
+ };
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/useAction/index.ts b/packages/react-storage/src/components/StorageBrowser/actions/useAction/index.ts
new file mode 100644
index 00000000000..8b7ee5535f2
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/useAction/index.ts
@@ -0,0 +1 @@
+export { useListLocations, UseListLocationsState } from './useListLocations';
diff --git a/packages/react-storage/src/components/StorageBrowser/actions/useAction/useListLocations.ts b/packages/react-storage/src/components/StorageBrowser/actions/useAction/useListLocations.ts
new file mode 100644
index 00000000000..9de7697950e
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/actions/useAction/useListLocations.ts
@@ -0,0 +1,43 @@
+import React from 'react';
+
+import { useDataState } from '@aws-amplify/ui-react-core';
+
+import { useActionConfig } from '../configs';
+import {
+ ListLocations,
+ LocationData,
+ ListLocationsExcludeOptions,
+} from '../handlers';
+import { ActionState } from '../types';
+
+import {
+ createEnhancedListHandler,
+ EnhancedListHandlerInput,
+ EnhancedListHandlerOutput,
+} from './createEnhancedListHandler';
+
+// Utility type functioning as a shim to allow for the outputted
+// enhanced `ListLocations` handler to not require `config` and `prefix`
+// in usage, which are required by the signature of `createEnhancedListHandler`
+type RemoveConfigAndPrefix = Omit;
+
+export interface UseListLocationsState
+ extends ActionState<
+ EnhancedListHandlerOutput,
+ RemoveConfigAndPrefix<
+ EnhancedListHandlerInput
+ >
+ > {}
+
+export const useListLocations = (): UseListLocationsState => {
+ const { handler } = useActionConfig('listLocations');
+ const enhancedHandler = React.useMemo(
+ () => createEnhancedListHandler(handler as ListLocations),
+ [handler]
+ );
+
+ return useDataState(enhancedHandler, {
+ items: [],
+ nextToken: undefined,
+ }) as UseListLocationsState;
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/__tests__/permissionParsers.spec.ts b/packages/react-storage/src/components/StorageBrowser/adapters/__tests__/permissionParsers.spec.ts
new file mode 100644
index 00000000000..0e8f371a1d8
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/__tests__/permissionParsers.spec.ts
@@ -0,0 +1,92 @@
+import {
+ parseAccessGrantPermission,
+ toAccessGrantPermission,
+ parseAmplifyAuthPermission,
+} from '../../adapters/permissionParsers';
+import { StorageAccess } from '../../storage-internal';
+
+import { generateCombinations } from '../../actions/__testUtils__/permissions';
+
+describe('parseAccessGrantPermission', () => {
+ it.each([
+ ['READ' as const, ['get', 'list']],
+ ['WRITE' as const, ['delete', 'write']],
+ ['READWRITE' as const, ['delete', 'get', 'list', 'write']],
+ ])('should parse %s to %s', (permission, expected) => {
+ expect(parseAccessGrantPermission(permission)).toEqual(expected);
+ });
+
+ it('should throw an error if the permission is invalid', () => {
+ // @ts-expect-error: test invalid permission
+ expect(() => parseAccessGrantPermission('INVALID')).toThrow(
+ 'Improper Permission: Please provide correct permission.'
+ );
+ });
+});
+
+describe('toAccessGrantPermission', () => {
+ const readAccessCombinations = generateCombinations([
+ 'read',
+ 'list',
+ 'get',
+ ] as StorageAccess[]);
+ const writeAccessCombinations = generateCombinations([
+ 'write',
+ 'delete',
+ ] as StorageAccess[]);
+ const readWriteCombinations = [] as StorageAccess[][];
+ for (const readAccess of readAccessCombinations) {
+ for (const writeAccess of writeAccessCombinations) {
+ readWriteCombinations.push([...readAccess, ...writeAccess]);
+ }
+ }
+ it.each([
+ ...readAccessCombinations.map(
+ (permissions) => [permissions, 'READ'] as const
+ ),
+ ...writeAccessCombinations.map(
+ (permissions) => [permissions, 'WRITE'] as const
+ ),
+ ...readWriteCombinations.map(
+ (permissions) => [permissions, 'READWRITE'] as const
+ ),
+ ])('should parse %s to %s', (permissions, expected) => {
+ expect(toAccessGrantPermission(permissions)).toEqual(expected);
+ });
+
+ it('should throw an error if the permission is invalid', () => {
+ // @ts-expect-error: test invalid permission
+ expect(() => toAccessGrantPermission(['INVALID'])).toThrow(
+ 'Improper Permission: Please provide correct permission.'
+ );
+ });
+});
+
+describe('parseAmplifyAuthPermission', () => {
+ it.each([
+ [['read'], ['get', 'list']],
+ [
+ ['list', 'get'],
+ ['get', 'list'],
+ ],
+ [
+ ['list', 'get', 'delete'],
+ ['delete', 'get', 'list'],
+ ],
+ [
+ ['delete', 'write'],
+ ['delete', 'write'],
+ ],
+ ])('should parse %s to %s', (permission, expected) => {
+ expect(parseAmplifyAuthPermission(permission as StorageAccess[])).toEqual(
+ expected
+ );
+ });
+
+ it('should throw an error if the permission is invalid', () => {
+ // @ts-expect-error: test invalid permission
+ expect(() => parseAmplifyAuthPermission(['INVALID'])).toThrow(
+ 'Improper Permission: Please provide correct permission.'
+ );
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/createAmplifyAuthAdapter.spec.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/createAmplifyAuthAdapter.spec.ts
new file mode 100644
index 00000000000..a5c9a56dd72
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/createAmplifyAuthAdapter.spec.ts
@@ -0,0 +1,107 @@
+import { Amplify } from 'aws-amplify';
+import { Hub } from 'aws-amplify/utils';
+import {
+ createAmplifyAuthAdapter,
+ MISSING_BUCKET_OR_REGION_ERROR,
+ MISSING_IDENTITY_ID_ERROR,
+ MISSING_TEMPORARY_CREDENTIALS_ERROR,
+} from '../createAmplifyAuthAdapter';
+
+const credentials = {
+ accessKeyId: 'accessKeyId',
+ secretAccessKey: 'secretAccessKey',
+ sessionToken: 'sessionToken',
+ expiration: new Date(Date.now() + 60 * 60_1000),
+};
+const mockFetchAuthSession = jest.fn(async (_: { forceRefresh?: boolean }) =>
+ Promise.resolve({ credentials, identityId: 'identityId' })
+);
+
+jest.mock('aws-amplify/auth', () => ({
+ fetchAuthSession: (input: { forceRefresh?: boolean }) =>
+ mockFetchAuthSession(input),
+}));
+
+describe('createAmplifyAuthAdapter', () => {
+ beforeEach(() => {
+ jest.clearAllMocks();
+ jest.spyOn(Amplify, 'getConfig').mockReturnValue({
+ Storage: { S3: { bucket: 'XXXXXX', region: 'region' } },
+ });
+ });
+
+ it('should create an auth adapter with the correct properties', () => {
+ const authAdapter = createAmplifyAuthAdapter();
+
+ expect(authAdapter).toHaveProperty('getLocationCredentials');
+ expect(authAdapter).toHaveProperty('listLocations');
+ expect(authAdapter).toHaveProperty('region');
+ expect(authAdapter.region).toEqual('region');
+ expect(authAdapter).toHaveProperty('registerAuthListener');
+ });
+
+ it('should throw if no bucket is returned from getConfig', () => {
+ jest
+ .spyOn(Amplify, 'getConfig')
+ .mockReturnValue({ Storage: { S3: { region: 'region' } } });
+
+ expect(createAmplifyAuthAdapter).toThrow(MISSING_BUCKET_OR_REGION_ERROR);
+ });
+
+ it('should throw if no region is returned from getConfig', () => {
+ jest
+ .spyOn(Amplify, 'getConfig')
+ .mockReturnValue({ Storage: { S3: { bucket: 'bucket' } } });
+
+ expect(createAmplifyAuthAdapter).toThrow(MISSING_BUCKET_OR_REGION_ERROR);
+ });
+
+ it('should set Hub listener when registerAuthListener is called', () => {
+ const hubListenSpy = jest.spyOn(Hub, 'listen');
+
+ const authAdapter = createAmplifyAuthAdapter();
+ const onStateChange = () => {
+ /* clear location store */
+ };
+ authAdapter.registerAuthListener(onStateChange);
+ expect(hubListenSpy).toHaveBeenCalled();
+ });
+
+ it('should call onStateChange if Hub signedOut event is called', () => {
+ const authAdapter = createAmplifyAuthAdapter();
+ const onStateChange = jest.fn();
+ authAdapter.registerAuthListener(onStateChange);
+
+ Hub.dispatch('auth', { event: 'signedOut' });
+
+ expect(onStateChange).toHaveBeenCalled();
+ });
+
+ it('throws when getLocationCredentials is called and fetchAuthSession does not return temporary credentials', async () => {
+ // @ts-expect-error intentionally return empty credentials
+ mockFetchAuthSession.mockResolvedValueOnce({ credentials: {} });
+
+ const { getLocationCredentials } = createAmplifyAuthAdapter();
+
+ await expect(
+ getLocationCredentials({
+ permissions: ['delete', 'get', 'list', 'write'],
+ scope: 's3://bucket/prefix/*',
+ })
+ ).rejects.toThrow(MISSING_TEMPORARY_CREDENTIALS_ERROR);
+ });
+
+ it('throws when getLocationCredentials is called and fetchAuthSession does not return an identityId', async () => {
+ // @ts-expect-error intentionally return missing identityId
+ mockFetchAuthSession.mockResolvedValueOnce({ credentials });
+
+ const { getLocationCredentials } = createAmplifyAuthAdapter();
+
+ await expect(
+ getLocationCredentials({
+ permissions: ['delete', 'get', 'list', 'write'],
+ scope: 's3://bucket/prefix/*',
+ })
+ ).rejects.toThrow(MISSING_IDENTITY_ID_ERROR);
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/createAmplifyListLocationsHandler.spec.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/createAmplifyListLocationsHandler.spec.ts
new file mode 100644
index 00000000000..a1c51182774
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/createAmplifyListLocationsHandler.spec.ts
@@ -0,0 +1,168 @@
+import { ListLocations, LocationData } from '../../../actions';
+import { listPaths, ListPathsOutput } from '../../../storage-internal';
+
+import { getPaginatedLocations } from '../getPaginatedLocations';
+import { createAmplifyListLocationsHandler } from '../createAmplifyListLocationsHandler';
+
+jest.mock('../../../storage-internal', () => ({
+ listPaths: jest.fn(),
+}));
+jest.mock(
+ '../../../adapters/createAmplifyAuthAdapter/getPaginatedLocations',
+ () => ({
+ getPaginatedLocations: jest.fn(),
+ })
+);
+
+describe('createAmplifyListLocationsHandler', () => {
+ const mockListPaths = jest.mocked(listPaths);
+ const mockGetPaginatedItems = jest.mocked(getPaginatedLocations);
+ const mockId = 'intentionally-static-test-id';
+
+ beforeAll(() => {
+ Object.defineProperty(globalThis, 'crypto', {
+ value: { randomUUID: () => mockId },
+ });
+ });
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('should fetch locations when the cache is empty', async () => {
+ const handler = createAmplifyListLocationsHandler();
+ const fetchedLocations: ListPathsOutput['locations'] = [
+ {
+ bucket: 'bucket1',
+ permission: ['read'],
+ prefix: 'prefix1/*',
+ type: 'PREFIX',
+ },
+ ];
+ const sanitizedLocations: LocationData[] = [
+ {
+ prefix: 'prefix1/',
+ bucket: 'bucket1',
+ id: mockId,
+ permissions: ['get', 'list'],
+ type: 'PREFIX',
+ },
+ ];
+
+ const input = { options: { pageSize: 10, nextToken: undefined } };
+ const paginatedResult = {
+ items: sanitizedLocations,
+ nextToken: undefined,
+ };
+
+ mockListPaths.mockResolvedValueOnce({ locations: fetchedLocations });
+ mockGetPaginatedItems.mockReturnValueOnce(paginatedResult);
+
+ const result = await handler(input);
+
+ expect(result).toEqual(paginatedResult);
+ expect(mockListPaths).toHaveBeenCalledTimes(1);
+ expect(mockGetPaginatedItems).toHaveBeenCalledWith({
+ items: sanitizedLocations,
+ pageSize: input.options.pageSize,
+ nextToken: input.options.nextToken,
+ });
+ });
+
+ it('should fetch locations from the cache', async () => {
+ const handler: ListLocations = createAmplifyListLocationsHandler();
+ const input = { options: { pageSize: 10, nextToken: undefined } };
+
+ const fetchedLocations: ListPathsOutput['locations'] = [
+ {
+ bucket: 'bucket1',
+ permission: ['read'],
+ prefix: 'prefix1/*',
+ type: 'PREFIX',
+ },
+ ];
+ mockListPaths.mockResolvedValueOnce({ locations: fetchedLocations });
+ await handler(input);
+
+ const cachedItems: LocationData[] = [
+ {
+ prefix: 'prefix1/',
+ bucket: 'bucket1',
+ id: mockId,
+ permissions: ['get', 'list'],
+ type: 'PREFIX',
+ },
+ ];
+
+ const paginatedResult = {
+ items: cachedItems,
+ nextToken: undefined,
+ };
+
+ mockGetPaginatedItems.mockReturnValueOnce(paginatedResult);
+
+ const result = await handler(input);
+
+ expect(result).toEqual(paginatedResult);
+ expect(mockGetPaginatedItems).toHaveBeenCalledWith({
+ items: cachedItems,
+ pageSize: input.options.pageSize,
+ nextToken: input.options.nextToken,
+ });
+ expect(mockListPaths).toHaveBeenCalledTimes(1);
+ });
+
+ it('should handle pagination', async () => {
+ const handler = createAmplifyListLocationsHandler();
+ const fetchedLocations: ListPathsOutput['locations'] = [
+ {
+ bucket: 'bucket1',
+ permission: ['read'],
+ prefix: 'prefix1/*',
+ type: 'PREFIX',
+ },
+ {
+ bucket: 'bucket2',
+ permission: ['read'],
+ prefix: 'prefix2/*',
+ type: 'PREFIX',
+ },
+ ];
+
+ const sanitizedLocations: LocationData[] = [
+ {
+ prefix: 'prefix1/',
+ bucket: 'bucket1',
+ id: mockId,
+ permissions: ['get', 'list'],
+ type: 'PREFIX',
+ },
+ {
+ prefix: 'prefix2/',
+ bucket: 'bucket2',
+ id: mockId,
+ permissions: ['get', 'list'],
+ type: 'PREFIX',
+ },
+ ];
+
+ const input = { options: { pageSize: 1, nextToken: undefined } };
+ const paginatedResult = {
+ items: [{ ...sanitizedLocations }[0]],
+ nextToken: 'token1',
+ };
+
+ mockListPaths.mockResolvedValueOnce({ locations: fetchedLocations });
+ mockGetPaginatedItems.mockReturnValueOnce(paginatedResult);
+
+ const result = await handler(input);
+
+ expect(result.items).toEqual(paginatedResult.items);
+ expect(mockListPaths).toHaveBeenCalledTimes(1);
+ expect(mockGetPaginatedItems).toHaveBeenCalledWith({
+ items: sanitizedLocations,
+ pageSize: input.options.pageSize,
+ nextToken: input.options.nextToken,
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/getPaginatedLocations.test.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/getPaginatedLocations.test.ts
new file mode 100644
index 00000000000..057d6d1b84c
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/getPaginatedLocations.test.ts
@@ -0,0 +1,93 @@
+import { getPaginatedLocations } from '../getPaginatedLocations';
+import { ListLocationsHandlerOutput } from '../../../actions';
+
+describe('getPaginatedLocations', () => {
+ const mockItems: ListLocationsHandlerOutput['items'] = [
+ {
+ type: 'PREFIX',
+ permissions: ['list'],
+ prefix: 'path1/',
+ bucket: 'bucket1',
+ id: '1',
+ },
+ {
+ type: 'PREFIX',
+ permissions: ['get'],
+ prefix: 'path2/',
+ bucket: 'bucket2',
+ id: '2',
+ },
+ {
+ type: 'PREFIX',
+ permissions: ['write'],
+ prefix: 'path3/',
+ bucket: 'bucket3',
+ id: '3',
+ },
+ ];
+
+ it('should return all locations when no pagination is specified', () => {
+ const result = getPaginatedLocations({ items: mockItems });
+ expect(result).toEqual({ items: mockItems });
+ });
+
+ it('should return paginated locations when pageSize is specified', () => {
+ const result = getPaginatedLocations({
+ items: mockItems,
+ pageSize: 2,
+ });
+ expect(result).toEqual({
+ items: mockItems.slice(0, 2),
+ nextToken: '1',
+ });
+ });
+
+ it('should return paginated locations when pageSize and nextToken are specified', () => {
+ const result = getPaginatedLocations({
+ items: mockItems,
+ pageSize: 1,
+ nextToken: '2',
+ });
+ expect(result).toEqual({
+ items: mockItems.slice(1, 2),
+ nextToken: '1',
+ });
+ });
+
+ it('should return empty locations when locations array is empty', () => {
+ const result = getPaginatedLocations({ items: [], pageSize: 2 });
+ expect(result).toEqual({ items: [] });
+ });
+
+ it('should return empty location when nextToken is beyond array length', () => {
+ const result = getPaginatedLocations({
+ items: mockItems,
+ pageSize: 2,
+ nextToken: '5',
+ });
+ expect(result).toEqual({ items: [], nextToken: undefined });
+ });
+
+ it('should return all remaining location when page size is greater than remaining locations length', () => {
+ const result = getPaginatedLocations({
+ items: mockItems,
+ pageSize: 5,
+ nextToken: '2',
+ });
+ expect(result).toEqual({
+ items: mockItems.slice(-2),
+ nextToken: undefined,
+ });
+ });
+
+ it('should return undefined nextToken when end of array is reached', () => {
+ const result = getPaginatedLocations({
+ items: mockItems,
+ pageSize: 5,
+ });
+ expect(result).toEqual({
+ items: mockItems.slice(0, 3),
+ nextToken: undefined,
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/mapAmplifyPermissions.test.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/mapAmplifyPermissions.test.ts
new file mode 100644
index 00000000000..b785f8ec86c
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/__tests__/mapAmplifyPermissions.test.ts
@@ -0,0 +1,30 @@
+import { toAccessGrantPermission } from '../../permissionParsers';
+import { Permission, StorageAccess } from '../../../storage-internal';
+
+describe('toAccessGrantPermission', () => {
+ it('should map either of read, get, list - storage access to READ', () => {
+ const input: StorageAccess[] = ['read', 'get', 'list'];
+ const expectedOutput: Permission = 'READ';
+ expect(toAccessGrantPermission(input)).toBe(expectedOutput);
+ });
+
+ it('should map write, delete - storage access to WRITE', () => {
+ const input: StorageAccess[] = ['write', 'delete'];
+ const expectedOutput: Permission = 'WRITE';
+ expect(toAccessGrantPermission(input)).toBe(expectedOutput);
+ });
+
+ it('should map get, list, and write permissions to READWRITE', () => {
+ const input: StorageAccess[] = ['get', 'list', 'write'];
+ const expectedOutput: Permission = 'READWRITE';
+ expect(toAccessGrantPermission(input)).toBe(expectedOutput);
+ });
+
+ it('should return an empty string for unknown permissions', () => {
+ // @ts-expect-error
+ const input: StorageAccess[] = ['unknown'];
+ expect(() => toAccessGrantPermission(input)).toThrow(
+ 'Improper Permission: Please provide correct permission.'
+ );
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/createAmplifyAuthAdapter.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/createAmplifyAuthAdapter.ts
new file mode 100644
index 00000000000..1efb5acd400
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/createAmplifyAuthAdapter.ts
@@ -0,0 +1,59 @@
+import { Amplify } from 'aws-amplify';
+import { AuthSession, fetchAuthSession } from 'aws-amplify/auth';
+import { Hub } from 'aws-amplify/utils';
+
+import { AWSTemporaryCredentials } from '../../storage-internal';
+import { StorageBrowserAuthAdapter } from '../types';
+import { createAmplifyListLocationsHandler } from './createAmplifyListLocationsHandler';
+import { RegisterAuthListener } from '../../providers';
+
+export const MISSING_BUCKET_OR_REGION_ERROR =
+ 'Amplify Storage configuration not found. Did you run `Amplify.configure` from your project root?';
+export const MISSING_IDENTITY_ID_ERROR = '`identityId` not found.';
+export const MISSING_TEMPORARY_CREDENTIALS_ERROR =
+ 'Temporary Auth `credentials` not found.';
+
+interface AWSCredentials extends NonNullable {}
+
+const isTemporaryCredentials = (
+ value?: AWSCredentials | AWSTemporaryCredentials
+): value is AWSTemporaryCredentials =>
+ !!value?.sessionToken || !!value?.expiration;
+
+export const createAmplifyAuthAdapter = (): StorageBrowserAuthAdapter => {
+ const { bucket, region } = Amplify.getConfig()?.Storage?.S3 ?? {};
+ if (!bucket || !region) {
+ throw new Error(MISSING_BUCKET_OR_REGION_ERROR);
+ }
+ const listLocations = createAmplifyListLocationsHandler();
+
+ const getLocationCredentials = async (): Promise<{
+ credentials: AWSTemporaryCredentials;
+ identityId: string;
+ }> => {
+ const { credentials, identityId } = await fetchAuthSession();
+ if (!isTemporaryCredentials(credentials)) {
+ throw new Error(MISSING_TEMPORARY_CREDENTIALS_ERROR);
+ }
+ if (!identityId) {
+ throw new Error(MISSING_IDENTITY_ID_ERROR);
+ }
+ return { credentials, identityId };
+ };
+
+ const registerAuthListener: RegisterAuthListener = (onStateChange) => {
+ const remove = Hub.listen('auth', (data) => {
+ if (data.payload.event === 'signedOut') {
+ onStateChange();
+ remove();
+ }
+ });
+ };
+
+ return {
+ getLocationCredentials,
+ listLocations,
+ registerAuthListener,
+ region,
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/createAmplifyListLocationsHandler.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/createAmplifyListLocationsHandler.ts
new file mode 100644
index 00000000000..58c87c26af5
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/createAmplifyListLocationsHandler.ts
@@ -0,0 +1,46 @@
+import { LocationData } from '../../actions';
+import { listPaths, ListPathsOutput } from '../../storage-internal';
+import { ListLocations, ListLocationsInput } from '../../actions';
+
+import { parseAmplifyAuthPermission } from '../permissionParsers';
+import { getPaginatedLocations } from './getPaginatedLocations';
+
+export const createAmplifyListLocationsHandler = (): ListLocations => {
+ let cachedItems: LocationData[] = [];
+
+ return async function listLocations(input: ListLocationsInput) {
+ const { options } = input ?? {};
+ const { nextToken, pageSize } = options ?? {};
+
+ if (cachedItems.length > 0) {
+ return getPaginatedLocations({
+ items: cachedItems,
+ pageSize,
+ nextToken,
+ });
+ }
+
+ const { locations }: { locations: ListPathsOutput['locations'] } =
+ await listPaths();
+
+ const sanitizedItems: LocationData[] = locations.map(
+ ({ bucket, permission, prefix, type }) => {
+ return {
+ type,
+ permissions: parseAmplifyAuthPermission(permission),
+ bucket,
+ prefix: prefix.endsWith('*') ? prefix.slice(0, -1) : prefix,
+ id: crypto.randomUUID(),
+ };
+ }
+ );
+
+ cachedItems = sanitizedItems;
+
+ return getPaginatedLocations({
+ items: cachedItems,
+ pageSize,
+ nextToken,
+ });
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/getPaginatedLocations.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/getPaginatedLocations.ts
new file mode 100644
index 00000000000..c9d7f743fc1
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/getPaginatedLocations.ts
@@ -0,0 +1,34 @@
+import { ListLocationsHandlerOutput, LocationData } from '../../actions';
+
+export const getPaginatedLocations = ({
+ items,
+ pageSize,
+ nextToken,
+}: {
+ items: LocationData[];
+ pageSize?: number;
+ nextToken?: string;
+}): ListLocationsHandlerOutput => {
+ if (pageSize) {
+ if (nextToken) {
+ if (Number(nextToken) > items.length) {
+ return { items: [], nextToken: undefined };
+ }
+ const start = -nextToken;
+ const end = start + pageSize < 0 ? start + pageSize : undefined;
+
+ return {
+ items: items.slice(start, end),
+ nextToken: end ? `${-end}` : undefined,
+ };
+ }
+
+ return {
+ items: items.slice(0, pageSize),
+ nextToken:
+ items.length > pageSize ? `${items.length - pageSize}` : undefined,
+ };
+ }
+
+ return { items, nextToken: undefined };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/index.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/index.ts
new file mode 100644
index 00000000000..6b71b6b512d
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createAmplifyAuthAdapter/index.ts
@@ -0,0 +1 @@
+export { createAmplifyAuthAdapter } from './createAmplifyAuthAdapter';
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/__tests__/createManagedAuthConfigAdapter.test.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/__tests__/createManagedAuthConfigAdapter.test.ts
new file mode 100644
index 00000000000..f01e4f9cd26
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/__tests__/createManagedAuthConfigAdapter.test.ts
@@ -0,0 +1,77 @@
+import { createManagedAuthAdapter } from '../../../adapters/createManagedAuthAdapter/createManagedAuthAdapter';
+import { createLocationCredentialsHandler } from '../../../adapters/createManagedAuthAdapter/createLocationCredentialsHandler';
+
+jest.mock(
+ '../../../adapters/createManagedAuthAdapter/createLocationCredentialsHandler'
+);
+
+const mockCreateLocationCredentialsHandler = jest.mocked(
+ createLocationCredentialsHandler
+);
+
+describe('createManagedAuthConfigAdapter', () => {
+ const region = 'us-foo-2';
+ const accountId = 'XXXXXXXXXXXX';
+ const credentialsProvider = jest.fn();
+ const customEndpoint = 'mock-endpoint';
+ const mockCreatedLocationCredentialsHandler = jest.fn();
+ const mockRegisterAuthListener = jest.fn();
+
+ beforeEach(() => {
+ mockCreateLocationCredentialsHandler.mockReturnValue(
+ mockCreatedLocationCredentialsHandler
+ );
+ });
+
+ afterEach(() => {
+ jest.clearAllMocks();
+ });
+
+ it('should pass region and accountId to the adapter', () => {
+ expect(
+ createManagedAuthAdapter({
+ region,
+ credentialsProvider: jest.fn(),
+ accountId,
+ registerAuthListener: mockRegisterAuthListener,
+ })
+ ).toMatchObject({
+ region,
+ accountId,
+ });
+ });
+
+ it('should create list locations handler', () => {
+ expect(
+ createManagedAuthAdapter({
+ region,
+ accountId,
+ credentialsProvider,
+ customEndpoint,
+ registerAuthListener: mockRegisterAuthListener,
+ })
+ ).toMatchObject({
+ listLocations: expect.any(Function),
+ });
+ });
+
+ it('should create get location credentials handler', () => {
+ expect(
+ createManagedAuthAdapter({
+ region,
+ accountId,
+ credentialsProvider,
+ customEndpoint,
+ registerAuthListener: mockRegisterAuthListener,
+ })
+ ).toMatchObject({
+ getLocationCredentials: mockCreatedLocationCredentialsHandler,
+ });
+ expect(mockCreateLocationCredentialsHandler).toHaveBeenCalledWith({
+ region,
+ accountId,
+ credentialsProvider,
+ customEndpoint,
+ });
+ });
+});
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/createLocationCredentialsHandler.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/createLocationCredentialsHandler.ts
new file mode 100644
index 00000000000..4ebe408aa7a
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/createLocationCredentialsHandler.ts
@@ -0,0 +1,39 @@
+import {
+ GetLocationCredentials,
+ GetLocationCredentialsInput,
+} from '../../credentials/types';
+import { getDataAccess, CredentialsProvider } from '../../storage-internal';
+import { toAccessGrantPermission } from '../permissionParsers';
+interface CreateLocationCredentialsHandlerInput {
+ accountId: string;
+ credentialsProvider: CredentialsProvider;
+ region: string;
+ customEndpoint?: string;
+}
+
+export const createLocationCredentialsHandler = (
+ handlerInput: CreateLocationCredentialsHandlerInput
+): GetLocationCredentials => {
+ const { accountId, region, credentialsProvider, customEndpoint } =
+ handlerInput;
+
+ /**
+ * Retrieves credentials for the specified scope & permission.
+ *
+ * @param input - An object specifying the requested scope & permission.
+ *
+ * @returns A promise which will resolve with the requested credentials.
+ */
+ return (input: GetLocationCredentialsInput) => {
+ const { scope, permissions } = input;
+
+ return getDataAccess({
+ accountId,
+ credentialsProvider,
+ permission: toAccessGrantPermission(permissions),
+ region,
+ scope,
+ customEndpoint,
+ });
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/createManagedAuthAdapter.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/createManagedAuthAdapter.ts
new file mode 100644
index 00000000000..b242f42a4e8
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/createManagedAuthAdapter.ts
@@ -0,0 +1,46 @@
+import { createLocationCredentialsHandler } from './createLocationCredentialsHandler';
+import {
+ StorageBrowserAuthAdapter,
+ CreateManagedAuthAdapterInput,
+} from '../types';
+import { listLocationsHandler, ListLocationsInput } from '../../actions';
+
+/**
+ * Create configuration including handlers to call S3 Access Grant APIs to list and get
+ * credentials for different locations.
+ *
+ * @param options - Configuration options for the adapter.
+ * @returns - An object containing the handlers to call S3 Access Grant APIs and region
+ */
+export const createManagedAuthAdapter = ({
+ accountId,
+ credentialsProvider,
+ customEndpoint,
+ region,
+ registerAuthListener,
+}: CreateManagedAuthAdapterInput): StorageBrowserAuthAdapter => {
+ const config = {
+ accountId,
+ credentials: credentialsProvider,
+ customEndpoint,
+ region,
+ };
+
+ const listLocations = ({ options }: ListLocationsInput = {}) =>
+ listLocationsHandler({ config, options });
+
+ const getLocationCredentials = createLocationCredentialsHandler({
+ credentialsProvider,
+ accountId,
+ customEndpoint,
+ region,
+ });
+
+ return {
+ accountId,
+ listLocations,
+ getLocationCredentials,
+ region,
+ registerAuthListener,
+ };
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/index.ts b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/index.ts
new file mode 100644
index 00000000000..7125c56c5ce
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/createManagedAuthAdapter/index.ts
@@ -0,0 +1 @@
+export { createManagedAuthAdapter } from './createManagedAuthAdapter';
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/index.ts b/packages/react-storage/src/components/StorageBrowser/adapters/index.ts
new file mode 100644
index 00000000000..0a9a681ee39
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/index.ts
@@ -0,0 +1,6 @@
+export { createAmplifyAuthAdapter } from './createAmplifyAuthAdapter';
+export { createManagedAuthAdapter } from './createManagedAuthAdapter';
+export {
+ CreateManagedAuthAdapterInput,
+ StorageBrowserAuthAdapter,
+} from './types';
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/permissionParsers.ts b/packages/react-storage/src/components/StorageBrowser/adapters/permissionParsers.ts
new file mode 100644
index 00000000000..b29d4d0990d
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/permissionParsers.ts
@@ -0,0 +1,68 @@
+import { LocationPermissions } from '../actions/handlers/types';
+import { Permission, StorageAccess } from '../storage-internal';
+
+export const parseAccessGrantPermission = (
+ accessGrantPermission: Permission
+): LocationPermissions => {
+ if (accessGrantPermission === 'READ') {
+ return ['get', 'list'];
+ } else if (accessGrantPermission === 'WRITE') {
+ return ['delete', 'write'];
+ } else if (accessGrantPermission === 'READWRITE') {
+ return ['delete', 'get', 'list', 'write'];
+ }
+ throw new Error('Improper Permission: Please provide correct permission.');
+};
+
+export const toAccessGrantPermission = (
+ permission: StorageAccess[]
+): Permission => {
+ let result: string = '';
+
+ permission.forEach((access: StorageAccess) => {
+ if (['read', 'get', 'list'].includes(access as string)) {
+ if (!result.includes('READ')) {
+ result = 'READ' + result;
+ }
+ }
+ if (['write', 'delete'].includes(access as string)) {
+ if (!result.includes('WRITE')) {
+ result += 'WRITE';
+ }
+ }
+ });
+
+ if (result === '') {
+ throw new Error('Improper Permission: Please provide correct permission.');
+ }
+
+ return result as Permission;
+};
+
+export const parseAmplifyAuthPermission = (
+ permissions: StorageAccess[]
+): LocationPermissions => {
+ const result: LocationPermissions = [];
+
+ permissions.forEach((access: StorageAccess) => {
+ if (access === 'read') {
+ if (!result.includes('list')) {
+ result.push('list');
+ }
+ if (!result.includes('get')) {
+ result.push('get');
+ }
+ } else if (
+ ['delete', 'get', 'list', 'write'].includes(access) &&
+ !result.includes(access)
+ ) {
+ result.push(access);
+ }
+ });
+
+ if (result.length === 0) {
+ throw new Error('Improper Permission: Please provide correct permission.');
+ }
+
+ return result.sort();
+};
diff --git a/packages/react-storage/src/components/StorageBrowser/adapters/types.ts b/packages/react-storage/src/components/StorageBrowser/adapters/types.ts
new file mode 100644
index 00000000000..521c2fd5b49
--- /dev/null
+++ b/packages/react-storage/src/components/StorageBrowser/adapters/types.ts
@@ -0,0 +1,33 @@
+import { RegisterAuthListener } from '../providers';
+import {
+ GetLocationCredentials,
+ CredentialsLocation,
+} from '../credentials/types';
+import { CredentialsProvider } from '../storage-internal';
+import { LocationType, ListLocations } from '../actions';
+
+export interface LocationAccess extends CredentialsLocation {
+ /**
+ * Parse location type parsed from scope format:
+ * * BUCKET: `'s3:///*'`
+ * * PREFIX: `'s3:///*'`
+ * * OBJECT: `'s3:////