@squiz/resource-browser 1.32.1-alpha.33 → 1.32.1-alpha.34

package/lib/types.d.ts

@@ -0,0 +1,67 @@
+import { SquizImageType } from '@squiz/dx-json-schema-lib';
+export type Status = {
+    code: string;
+    name: string;
+};
+/**
+ * Represents a resource that has been picked from a source.
+ */
+export type Resource = {
+    id: string;
+    name: string;
+    type: {
+        code: string;
+        name: string;
+    };
+    status: Status;
+    url: string;
+    urls: string[];
+    childCount: number;
+    squizImage?: SquizImageType['__shape__'];
+};
+/**
+ * Represents a system that resources can be picked from.
+ * Optionally, may indicate a list of "nodes" that can be used to scope the source to a subset of its resources.
+ */
+export type Source = {
+    id: string;
+    name: string;
+    nodes: Resource[];
+};
+/**
+ * Represents a source that has been optionally scoped to one of its "nodes".
+ */
+export type ScopedSource = {
+    source: Source;
+    resource: Resource | null;
+};
+/**
+ * A non-hydrated resource reference.
+ */
+export type ResourceReference = {
+    source: string;
+    resource: string;
+};
+/**
+ * A hydrated resource reference.
+ */
+export type HydratedResourceReference = {
+    source: Source;
+    resource: Resource;
+};
+/**
+ * Represents the hierarchy within the asset picker.
+ * Within the picker T will be ScopedSource|Resource.
+ * ScopedSource will be the first item in the array, Resource will be every other item.
+ */
+export type Hierarchy<T> = Array<{
+    key: string;
+    label: string;
+    node: T;
+}>;
+/**
+ * Augments a type so that all properties are optional.
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends Array<infer U> ? Array<DeepPartial<U>> : T[P] extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : DeepPartial<T[P]>;
+};

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squiz/resource-browser",
-  "version": "1.32.1-alpha.33",
+  "version": "1.32.1-alpha.34",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {
@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "@mui/icons-material": "5.11.16",
-    "@squiz/dx-json-schema-lib": "1.32.1-alpha.33",
+    "@squiz/dx-json-schema-lib": "1.32.1-alpha.34",
     "pretty-bytes": "5.6.0",
     "react-aria": "3.23.1",
     "react-responsive": "9.0.2",
@@ -73,5 +73,5 @@
   "volta": {
     "node": "18.15.0"
   },
-  "gitHead": "614c4ec6f82220758521a2887b45094c36474aef"
+  "gitHead": "34965675fd331238d984f5c4d86cc96d85b5f165"
 }

package/src/Hooks/useAsync.spec.ts

@@ -0,0 +1,106 @@
+import { DependencyList } from 'react';
+import { renderHook, waitFor } from '@testing-library/react';
+import { useAsync } from './useAsync';
+
+describe('useAsync', () => {
+  const renderAsyncHook = (callback: () => any, deps: DependencyList) => {
+    return renderHook(
+      ({ deps }: { deps: DependencyList }) => useAsync({ callback, defaultValue: 'Initial state' }, deps),
+      { initialProps: { deps } },
+    );
+  };
+
+  it('Should invoke callback when hook is initially rendered', async () => {
+    const callback = jest.fn().mockResolvedValue('Resolved data');
+    const { result } = renderAsyncHook(callback, ['initial_dependency_value']);
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toBe('Initial state');
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toBe('Resolved data');
+  });
+
+  it('Should not invoke callback when hook is re-rendered with the same dependencies', async () => {
+    const callback = jest.fn().mockResolvedValue('Resolved data');
+    const { result, rerender } = renderAsyncHook(callback, ['initial_dependency_value']);
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // If we re-render with the same "deps" we should not attempt to re-load data.
+    rerender({ deps: ['initial_dependency_value'] });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toBe('Resolved data');
+    expect(callback).toBeCalledTimes(1);
+  });
+
+  it('Should invoke callback when hook is re-rendered with different dependencies', async () => {
+    const callback = jest.fn().mockResolvedValueOnce('Resolved data').mockResolvedValueOnce('Updated resolved data');
+    const { result, rerender } = renderAsyncHook(callback, ['initial_dependency_value']);
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // If we re-render with the same "deps" we should not attempt to re-load data.
+    rerender({ deps: ['updated_dependency_value'] });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toBe('Updated resolved data');
+    expect(callback).toBeCalledTimes(2);
+  });
+
+  it.each([
+    ['Error object thrown', new Error('Callback failed'), 'Callback failed'],
+    ['Non-error object thrown', 'Callback failed', 'Callback failed'],
+  ])(
+    'Should retain the error if the callback rejects - %s',
+    async (description: string, error: any, expectedErrorMessage: string) => {
+      const callback = jest.fn().mockRejectedValue(error);
+      const { result } = renderAsyncHook(callback, ['initial_dependency_value']);
+
+      await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error?.message).toBe(expectedErrorMessage);
+      expect(result.current.data).toBe('Initial state');
+    },
+  );
+
+  it('Should handle non-async return data returned from callback', async () => {
+    const callback = jest.fn(() => 'Returned data');
+    const { result } = renderAsyncHook(callback, ['initial_dependency_value']);
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toBe('Returned data');
+  });
+
+  it.each([
+    ['Error object thrown', new Error('Callback failed'), 'Callback failed'],
+    ['Non-error object thrown', 'Callback failed', 'Callback failed'],
+  ])(
+    'Should handle non-async thrown errors from callback - %s',
+    async (description: string, error: any, expectedErrorMessage: string) => {
+      const callback = jest.fn(() => {
+        throw error;
+      });
+      const { result } = renderAsyncHook(callback, ['initial_dependency_value']);
+
+      expect(result.current.isLoading).toBe(false);
+      expect(result.current.error).toBeInstanceOf(Error);
+      expect(result.current.error?.message).toBe(expectedErrorMessage);
+      expect(result.current.data).toBe('Initial state');
+    },
+  );
+});

package/src/Hooks/useAsync.ts

@@ -0,0 +1,62 @@
+import { DependencyList, useState, useCallback, useEffect } from 'react';
+
+export type UseAsyncProps<TReturnType, TDefaultValueType> = {
+  /** The async callback to call for fetching data. */
+  callback: () => TReturnType | Promise<TReturnType>;
+  /** The default value to populate the data as when initially mounted or reloading data. */
+  defaultValue: TReturnType | TDefaultValueType;
+};
+
+/**
+ * Hook for invoking a piece of async code and keeping track of its state.
+ *
+ * Data is loaded in 3 different ways:
+ * 1. On initial mount.
+ * 2. When any of the `deps` change.
+ * 3. When the `relaod` function is called.
+ */
+export const useAsync = <TReturnType, TDefaultValueType>(
+  { callback, defaultValue }: UseAsyncProps<TReturnType, TDefaultValueType>,
+  deps: DependencyList,
+) => {
+  const [data, setData] = useState(defaultValue);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const reload = useCallback(() => {
+    setIsLoading(true);
+    setError(null);
+    setData(defaultValue);
+
+    try {
+      const result = callback();
+
+      if (result instanceof Promise) {
+        // if the callback returned a promise wait for it to either resolve or reject.
+        result
+          .then((resolved: TReturnType) => {
+            setData(resolved);
+            setIsLoading(false);
+          })
+          .catch((e: unknown) => {
+            setError(e instanceof Error ? e : new Error(String(e)));
+            setIsLoading(false);
+          });
+      } else {
+        // if the callback returned something other than a promise assume it is the data we want.
+        setData(result);
+        setIsLoading(false);
+      }
+    } catch (e: unknown) {
+      // callback threw outside of the scope of the promise.
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setIsLoading(false);
+    }
+  }, deps);
+
+  // reload data on dependency change (and initial mount)
+  useEffect(() => {
+    reload();
+  }, deps);
+
+  return { data, error, isLoading, reload };
+};

package/src/Hooks/useChildResources.spec.ts

@@ -19,32 +19,11 @@ describe('useChildResources', () => {
 
     expect(result.current.isLoading).toBe(true);
     expect(result.current.error).toBe(null);
-    expect(result.current.resources).toEqual([]);
+    expect(result.current.data).toEqual([]);
 
     await waitFor(() => expect(result.current.isLoading).toBe(false));
 
     expect(result.current.isLoading).toBe(false);
-    expect(result.current.resources).toBe(children);
-  });
-
-  it('Should return the error if loading resources fails', async () => {
-    const source = mockScopedSource();
-    const currentResource = mockResource({ name: 'Current resource' });
-    const error = new Error('Loading the resources failed.');
-    const onRequestChildren = jest.fn().mockRejectedValue(error);
-
-    const { result } = renderHook(() =>
-      useChildResources({
-        source,
-        currentResource,
-        onRequestChildren,
-      }),
-    );
-
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.isLoading).toBe(false);
-    expect(result.current.error).toBe(error);
-    expect(result.current.resources).toEqual([]);
+    expect(result.current.data).toBe(children);
   });
 });

package/src/Hooks/useChildResources.ts

@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useState } from 'react';
 import { Resource, ScopedSource, Source } from '../types';
+import { useAsync } from './useAsync';
 
 type UseChildResourcesProps = {
   source: ScopedSource | null;
@@ -9,37 +9,12 @@ type UseChildResourcesProps = {
 
 /**
  * Triggers a reload of the child resources when the source or current resource change.
- *
- * @param {ScopedSource|null} source
- * @param {Resource|null}     currentResource
- * @param {Function}          onRequestChildren
  */
-export const useChildResources = ({ source, currentResource, onRequestChildren }: UseChildResourcesProps) => {
-  const [error, setError] = useState<Error | null>(null);
-  const [isLoading, setIsLoading] = useState(false);
-  const [resources, setResources] = useState<Resource[]>([]);
-
-  const loadResource = useCallback(() => {
-    setError(null);
-    setResources([]);
-
-    if (source) {
-      setIsLoading(true);
-
-      onRequestChildren(source.source, currentResource)
-        .then((resources: Array<Resource>) => {
-          setResources(resources);
-          setIsLoading(false);
-        })
-        .catch((e) => {
-          setError(e);
-          setIsLoading(false);
-        });
-    }
-  }, [source, currentResource]);
-
-  // trigger a reload of the resources when the source or the current resource changes.
-  useEffect(loadResource, [source, currentResource]);
-
-  return { isLoading, resources, reloadResources: loadResource, error };
-};
+export const useChildResources = ({ source, currentResource, onRequestChildren }: UseChildResourcesProps) =>
+  useAsync(
+    {
+      callback: () => (source ? onRequestChildren(source.source, currentResource || source.resource) : []),
+      defaultValue: [],
+    },
+    [source, currentResource],
+  );

package/src/Hooks/useResource.spec.ts

@@ -0,0 +1,32 @@
+import { renderHook, waitFor } from '@testing-library/react';
+import { mockResource } from '../__mocks__/MockModels';
+import { useResource } from './useResource';
+
+describe('useResource', () => {
+  it('Should load the resource', async () => {
+    const resource = mockResource();
+    const reference = { source: 'source-id', resource: 'resource-id' };
+    const onRequestResource = jest.fn().mockResolvedValue(resource);
+    const { result } = renderHook(() => useResource({ onRequestResource, reference }));
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toEqual(null);
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.data).toBe(resource);
+  });
+
+  it('Should not load the resource if no reference provided', async () => {
+    const reference = null;
+    const onRequestResource = jest.fn();
+    const { result } = renderHook(() => useResource({ onRequestResource, reference }));
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.error).toBe(null);
+    expect(result.current.data).toEqual(null);
+    expect(onRequestResource).not.toBeCalled();
+  });
+});

package/src/Hooks/useResource.ts

@@ -0,0 +1,19 @@
+import { useAsync } from './useAsync';
+import { Resource, ResourceReference } from '../types';
+
+type UseResourceProps = {
+  onRequestResource: (reference: ResourceReference) => Promise<Resource | null>;
+  reference?: ResourceReference | null;
+};
+
+/**
+ * Loads the resource indicated by the provided reference.
+ */
+export const useResource = ({ onRequestResource, reference }: UseResourceProps) =>
+  useAsync(
+    {
+      callback: () => (reference ? onRequestResource(reference) : null),
+      defaultValue: null,
+    },
+    [reference?.source, reference?.resource],
+  );

package/src/Hooks/useSources.spec.ts

@@ -10,23 +10,11 @@ describe('useSources', () => {
 
     expect(result.current.isLoading).toBe(true);
     expect(result.current.error).toBe(null);
-    expect(result.current.sources).toEqual([]);
+    expect(result.current.data).toEqual([]);
 
     await waitFor(() => expect(result.current.isLoading).toBe(false));
 
     expect(result.current.isLoading).toBe(false);
-    expect(result.current.sources).toBe(sources);
-  });
-
-  it('Should return the error if loading resources fails', async () => {
-    const error = new Error('Loading the sources failed.');
-    const onRequestSources = jest.fn().mockRejectedValue(error);
-    const { result } = renderHook(() => useSources({ onRequestSources }));
-
-    await waitFor(() => expect(result.current.isLoading).toBe(false));
-
-    expect(result.current.isLoading).toBe(false);
-    expect(result.current.error).toBe(error);
-    expect(result.current.sources).toEqual([]);
+    expect(result.current.data).toBe(sources);
   });
 });

package/src/Hooks/useSources.ts

@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useState } from 'react';
 import { Source } from '../types';
+import { useAsync } from './useAsync';
 
 type UseSourcesProps = {
   onRequestSources: () => Promise<Source[]>;
@@ -7,29 +7,6 @@ type UseSourcesProps = {
 
 /**
  * Loads and caches the source list when a component using the hook is mounted.
- *
- * @param {Function} onRequestSources
  */
-export const useSources = ({ onRequestSources }: UseSourcesProps) => {
-  const [error, setError] = useState<Error | null>(null);
-  const [isLoading, setIsLoading] = useState(true);
-  const [sources, setSources] = useState<Source[]>([]);
-  const loadSources = useCallback(() => {
-    setIsLoading(true);
-    onRequestSources()
-      .then((sources) => {
-        setIsLoading(false);
-        setSources(sources);
-        setError(null);
-      })
-      .catch((error) => {
-        setIsLoading(false);
-        setError(error);
-      });
-  }, []);
-
-  // trigger a load of the sources when the component using the hook is initially rendered.
-  useEffect(loadSources, []);
-
-  return { isLoading, sources, reload: loadSources, error };
-};
+export const useSources = ({ onRequestSources }: UseSourcesProps) =>
+  useAsync({ callback: onRequestSources, defaultValue: [] }, []);

package/src/PreviewPanel/details/MatrixResource.tsx

@@ -30,8 +30,7 @@ const MatrixResource = ({ resource: { id, type, name, status } }: MatrixResource
           <div className="flex mb-2">
             <dt className="w-[60px] mr-4 text-gray-600">Status</dt>
             <dd className="flex items-center font-semibold">
-              <StatusIndicator status={status} />
-              {status.name}
+              <StatusIndicator className="mr-1" status={status} /> {status.name}
             </dd>
           </div>
         </dl>

package/src/ResourceBrowserContext/ResourceBrowserContext.spec.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { render } from '@testing-library/react';
+import { ResourceBrowserContext, ResourceBrowserContextProps } from './ResourceBrowserContext';
+import { mockSource } from '../__mocks__/MockModels';
+
+describe('ResourceBrowserContext', () => {
+  it('Should render with expected default value', () => {
+    let defaultContext: ResourceBrowserContextProps | null = null;
+
+    render(
+      <ResourceBrowserContext.Consumer>
+        {(value) => {
+          defaultContext = value;
+          return null;
+        }}
+      </ResourceBrowserContext.Consumer>,
+    );
+
+    expect(defaultContext).toEqual({
+      onRequestChildren: expect.any(Function),
+      onRequestResource: expect.any(Function),
+      onRequestSources: expect.any(Function),
+    });
+    expect(() => defaultContext?.onRequestChildren(mockSource(), null)).toThrow(
+      'onRequestChildren has not been configured.',
+    );
+    expect(() => defaultContext?.onRequestResource({ source: 'source-id', resource: 'resource-id' })).toThrow(
+      'onRequestResource has not been configured.',
+    );
+    expect(() => defaultContext?.onRequestSources()).toThrow('onRequestSources has not been configured.');
+  });
+});

package/src/ResourceBrowserContext/ResourceBrowserContext.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import { Resource, ResourceReference, Source } from '../types';
+
+export type ResourceBrowserContextProps = {
+  onRequestSources: () => Promise<Source[]>;
+  onRequestChildren(source: Source, resource: Resource | null): Promise<Resource[]>;
+  onRequestResource(reference: ResourceReference): Promise<Resource | null>;
+};
+
+export const ResourceBrowserContext = React.createContext<ResourceBrowserContextProps>({
+  onRequestSources: () => {
+    throw new Error('onRequestSources has not been configured.');
+  },
+  onRequestChildren: () => {
+    throw new Error('onRequestChildren has not been configured.');
+  },
+  onRequestResource: () => {
+    throw new Error('onRequestResource has not been configured.');
+  },
+});

package/src/ResourceItem/ResourceItem.tsx

@@ -36,7 +36,7 @@ const ResourceItem = <T,>({
   const title = isDisabled ? "You can't select this item" : label;
 
   return (
-    <li className={`flex items-stretch p-1 bg-white border border-grey-200 min-h-[64px] ${className}`}>
+    <li className={`flex items-stretch p-1 bg-white border-1 border-grey-200 min-h-[64px] ${className}`}>
       <ModalOpeningButton
         type="button"
         {...triggerProps}

package/src/ResourcePicker/ResetButton.tsx

@@ -1,13 +1,19 @@
 import React from 'react';
 import CloseRoundedIcon from '@mui/icons-material/CloseRounded';
 
-export const ResetButton = ({ isDisabled }: { isDisabled: boolean }) => (
+export type ResetButtonProps = {
+  onClick: () => void;
+  isDisabled?: boolean;
+};
+
+export const ResetButton = ({ onClick, isDisabled }: ResetButtonProps) => (
   <button
     type="button"
     aria-label={`Remove selection`}
     title={`Remove selection`}
     className="text-gray-500 hover:text-gray-800 focus:text-gray-800 w-6 h-6 disabled:text-gray-500 disabled:cursor-not-allowed"
     disabled={isDisabled}
+    onClick={onClick}
   >
     <CloseRoundedIcon />
   </button>

package/src/ResourcePicker/ResourcePicker.spec.tsx

@@ -35,9 +35,11 @@ describe('Resource picker', () => {
   });
 
   it('should render the error state if set to true', () => {
-    render(<ResourcePicker {...defaultProps} isError={true} />);
+    const errorMessage = 'Failed to retrieve asset info due to a Component Service API key problem.';
+
+    render(<ResourcePicker {...defaultProps} error={new Error(errorMessage)} />);
     const pickerLabel = screen.queryByText('Choose image');
-    const errorLabel = screen.queryByText('Failed to retrieve asset info due to a Component Service API key problem.');
+    const errorLabel = screen.queryByText(errorMessage);
 
     expect(pickerLabel).not.toBeInTheDocument();
     expect(errorLabel).toBeInTheDocument();
@@ -62,8 +64,10 @@ describe('Resource picker', () => {
   });
 
   it('should display the reset button in error state', () => {
-    render(<ResourcePicker {...defaultProps} isError={true} />);
-    const errorLabel = screen.queryByText('Failed to retrieve asset info due to a Component Service API key problem.');
+    const errorMessage = 'Failed to fetch resource.';
+
+    render(<ResourcePicker {...defaultProps} error={new Error(errorMessage)} />);
+    const errorLabel = screen.queryByText(errorMessage);
     const removeButton = screen.queryByLabelText('Remove selection');
 
     expect(errorLabel).toBeInTheDocument();

package/src/ResourcePicker/ResourcePicker.stories.tsx

@@ -12,7 +12,7 @@ export default {
 
 const Template: StoryFn<ResourcePickerProps> = (args: ResourcePickerProps) => (
   <div className="w-[400px] m-3">
-    <ResourcePicker {...args} />
+    <ResourcePicker {...args}>{() => <>Resource browser here</>}</ResourcePicker>
   </div>
 );
 
@@ -40,7 +40,7 @@ Loading.args = {
 export const Error = Template.bind({});
 Error.args = {
   ...Empty.args,
-  isError: true,
+  error: new window.Error('Failed to retrieve asset info due to a Component Service API key problem.'),
 };
 
 export const Selected = Template.bind({});