feat: APP-2727 - Implement AddressInput module component

CHANGELOG.md

@@ -9,13 +9,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ### Added
 
--   Implement `DaoDataListItem`, `ProposalDataListItem.Structure`, and `MemberDataListItem.Structure` module components
+-   Implement `DaoDataListItem.Structure`, `ProposalDataListItem.Structure`, `MemberDataListItem.Structure` and
+    `AddressInput` module components
 -   Implement `StatePingAnimation` core component
+-   Implement `addressUtils` and `ensUtils` module utilities
+-   Implement `useDebouncedValue` core hook and `clipboardUtils` core utility
 
 ### Changed
 
 -   Update `Tag` component primary variant styling
 -   Update Eslint rules to align usage of boolean properties
+-   Update default query-client options to set a stale time greater than 0
 
 ### Fixed
 

jest.config.js

@@ -10,7 +10,7 @@ const config = {
         '^.+\\.svg$': '<rootDir>/src/core/test/svgTransform.js',
         '^.+\\.m?[tj]sx?$': 'ts-jest',
     },
-    transformIgnorePatterns: ['node_modules/(?!(.*\\.mjs$|react-merge-refs))'],
+    transformIgnorePatterns: ['node_modules/(?!(.*\\.mjs$|react-merge-refs|wagmi|@wagmi))'],
 };
 
 module.exports = config;

src/core/components/input/index.ts

@@ -1,3 +1,4 @@
+export * from './hooks';
 export * from './inputContainer';
 export * from './inputDate';
 export * from './inputFileAvatar';

src/core/components/input/inputContainer/inputContainer.api.ts

@@ -65,7 +65,8 @@ export interface IInputContainerBaseProps {
      */
     wrapperClassName?: string;
     /**
-     * Shortcircuits all the input wrapper classes to pass control to the child component.
+     * Does not render the default input wrapper when set to true, to be used for using the base input container
+     * properties (label, helpText, ..) for components without a input wrapper (e.g. file inputs).
      */
     useCustomWrapper?: boolean;
 }
@@ -75,7 +76,7 @@ export interface IInputContainerProps extends IInputContainerBaseProps, Omit<Com
 export type InputComponentElement = HTMLInputElement | HTMLTextAreaElement;
 
 export interface IInputComponentProps<TElement extends InputComponentElement = HTMLInputElement>
-    extends Omit<IInputContainerBaseProps, 'children' | 'id' | 'inputLength'>,
+    extends Omit<IInputContainerBaseProps, 'children' | 'id' | 'inputLength' | 'useCustomWrapper'>,
         Omit<InputHTMLAttributes<TElement>, 'type'> {
     /**
      * Classes for the input element.

src/core/components/textAreas/textArea/textArea.tsx

@@ -1,7 +1,6 @@
 import classNames from 'classnames';
 import { forwardRef } from 'react';
-import { InputContainer, type IInputComponentProps } from '../../input';
-import { useInputProps } from '../../input/hooks';
+import { InputContainer, useInputProps, type IInputComponentProps } from '../../input';
 
 export interface ITextAreaProps extends IInputComponentProps<HTMLTextAreaElement> {}
 

src/core/hooks/index.ts

@@ -0,0 +1 @@
+export * from './useDebouncedValue';

src/core/hooks/useDebouncedValue/index.ts

@@ -0,0 +1 @@
+export { useDebouncedValue, type IUseDebouncedValueParams, type IUseDebouncedValueResult } from './useDebouncedValue';

src/core/hooks/useDebouncedValue/useDebouncedValue.test.ts

@@ -0,0 +1,34 @@
+import { act, renderHook } from '@testing-library/react';
+import { useDebouncedValue } from './useDebouncedValue';
+
+describe('useDebouncedValue hook', () => {
+    beforeEach(() => {
+        jest.useFakeTimers();
+    });
+
+    it('returns the value initialised to the value property and a function to update the debounced value', () => {
+        const value = 'test-value';
+        const { result } = renderHook(() => useDebouncedValue(value));
+        expect(result.current).toEqual([value, expect.any(Function)]);
+    });
+
+    it('debounces the value updates', () => {
+        const newValue = 'test';
+        const { result, rerender } = renderHook((value) => useDebouncedValue(value));
+        expect(result.current[0]).toBeUndefined();
+
+        rerender(newValue);
+        expect(result.current[0]).toBeUndefined();
+
+        act(() => jest.runAllTimers());
+        expect(result.current[0]).toEqual(newValue);
+    });
+
+    it('the returned setter updates the debounced value', () => {
+        const newValue = 'my-value';
+        const { result } = renderHook((value) => useDebouncedValue(value));
+        expect(result.current[0]).toBeUndefined();
+        act(() => result.current[1](newValue));
+        expect(result.current[0]).toEqual(newValue);
+    });
+});

src/core/hooks/useDebouncedValue/useDebouncedValue.ts

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from 'react';
+
+export interface IUseDebouncedValueParams {
+    /**
+     * Debounce time period in milliseconds.
+     * @default 500
+     */
+    delay?: number;
+}
+
+export type IUseDebouncedValueResult<TValue> = [
+    /**
+     * Debounced value.
+     */
+    TValue,
+    /**
+     * Setter for the debounced value.
+     */
+    (value: TValue) => void,
+];
+
+export const useDebouncedValue = <TValue>(
+    value: TValue,
+    params: IUseDebouncedValueParams = {},
+): IUseDebouncedValueResult<TValue> => {
+    const { delay } = params;
+
+    const [debouncedValue, setDebouncedValue] = useState(value);
+
+    const timeoutRef = useRef<NodeJS.Timeout>();
+
+    useEffect(() => {
+        timeoutRef.current = setTimeout(() => setDebouncedValue(value), delay);
+
+        return () => clearTimeout(timeoutRef.current);
+    }, [value, delay]);
+
+    return [debouncedValue, setDebouncedValue];
+};

src/core/index.ts

@@ -1,3 +1,4 @@
 export * from './components';
+export * from './hooks';
 export * from './types';
 export * from './utils';

src/core/test/setup.ts

@@ -3,7 +3,11 @@
 // expect(element).toHaveTextContent(/react/i)
 // learn more: https://github.com/testing-library/jest-dom
 import '@testing-library/jest-dom';
+import { TextDecoder, TextEncoder } from 'util';
 import { testLogger } from './utils';
 
 // Setup test logger
 testLogger.setup();
+
+// Globally setup TextEncoder/TextDecoder needed by viem
+Object.assign(global, { TextDecoder, TextEncoder });

src/core/utils/clipboardUtils/clipboardUtils.test.ts

@@ -0,0 +1,61 @@
+import { testLogger } from '../../test';
+import { clipboardUtils } from './clipboardUtils';
+
+// Navigator.clipboard object is not defined on Jest by default
+Object.defineProperty(navigator, 'clipboard', {
+    value: { writeText: jest.fn(), readText: jest.fn() },
+});
+
+describe('clipboard utils', () => {
+    describe('copy', () => {
+        const writeTextMock = jest.spyOn(navigator.clipboard, 'writeText');
+
+        afterEach(() => {
+            writeTextMock.mockReset();
+        });
+
+        it('copies the specified value on the user clipboard', async () => {
+            const copyValue = 'copy-value';
+            await clipboardUtils.copy(copyValue);
+            expect(writeTextMock).toHaveBeenCalledWith(copyValue);
+        });
+
+        it('calls the onError callback on copy error', async () => {
+            testLogger.suppressErrors();
+            const onError = jest.fn();
+            const error = new Error('test-error');
+            writeTextMock.mockImplementation(() => {
+                throw error;
+            });
+            await clipboardUtils.copy('test', { onError });
+            expect(onError).toHaveBeenCalledWith(error);
+        });
+    });
+
+    describe('paste', () => {
+        const readTextMock = jest.spyOn(navigator.clipboard, 'readText');
+
+        afterEach(() => {
+            readTextMock.mockReset();
+        });
+
+        it('reads and returns the user clipboard', async () => {
+            const clipboardValue = 'test-value';
+            readTextMock.mockResolvedValue(clipboardValue);
+            const result = await clipboardUtils.paste();
+            expect(result).toEqual(clipboardValue);
+        });
+
+        it('calls the onError callback on paste error', async () => {
+            testLogger.suppressErrors();
+            const onError = jest.fn();
+            const error = new Error('test-error');
+            readTextMock.mockImplementation(() => {
+                throw error;
+            });
+            const result = await clipboardUtils.paste({ onError });
+            expect(result).toEqual('');
+            expect(onError).toHaveBeenCalledWith(error);
+        });
+    });
+});

src/core/utils/clipboardUtils/clipboardUtils.ts

@@ -0,0 +1,33 @@
+export interface IClipboardUtilsParams {
+    /**
+     * Callback called on paste error.
+     */
+    onError?: (error: unknown) => void;
+}
+
+class ClipboardUtils {
+    copy = async (value: string, params: IClipboardUtilsParams = {}): Promise<void> => {
+        const { onError } = params;
+
+        try {
+            await navigator.clipboard.writeText(value);
+        } catch (error: unknown) {
+            onError?.(error);
+        }
+    };
+
+    paste = async (params: IClipboardUtilsParams = {}): Promise<string> => {
+        const { onError } = params;
+        let clipboardText = '';
+
+        try {
+            clipboardText = await navigator.clipboard.readText();
+        } catch (error: unknown) {
+            onError?.(error);
+        }
+
+        return clipboardText;
+    };
+}
+
+export const clipboardUtils = new ClipboardUtils();

src/core/utils/clipboardUtils/index.ts

@@ -0,0 +1 @@
+export { clipboardUtils, type IClipboardUtilsParams } from './clipboardUtils';

src/core/utils/index.ts

@@ -1,3 +1,4 @@
+export * from './clipboardUtils';
 export * from './formatterUtils';
 export * from './mergeRefs';
 export * from './responsiveUtils';

src/modules/components/address/addressInput/addressInput.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import { AddressInput, type IAddressInputProps, type IAddressInputResolvedValue } from './addressInput';
+
+const meta: Meta<typeof AddressInput> = {
+    title: 'Modules/Components/Address/AddressInput',
+    component: AddressInput,
+    tags: ['autodocs'],
+    parameters: {
+        design: {
+            type: 'figma',
+            url: 'https://www.figma.com/file/P0GeJKqILL7UXvaqu5Jj7V/v1.1.0?type=design&node-id=8192-18146&mode=design&t=VfR81DAQucRS3iGm-4',
+        },
+    },
+};
+
+type Story = StoryObj<typeof AddressInput>;
+
+const ControlledComponent = (props: IAddressInputProps) => {
+    const [value, setValue] = useState<string>();
+    const [addressValue, setAddressValue] = useState<IAddressInputResolvedValue>();
+
+    const stringAddressValue = JSON.stringify(addressValue, null, 2) ?? 'undefined';
+
+    return (
+        <div className="flex grow flex-col gap-2">
+            <AddressInput value={value} onChange={setValue} onAccept={setAddressValue} {...props} />
+            <code className="[word-break:break-word]">Address value: {stringAddressValue}</code>
+        </div>
+    );
+};
+
+/**
+ * Default usage of the AddressInput component.
+ */
+export const Default: Story = {
+    args: {
+        placeholder: 'ENS or 0x …',
+    },
+    render: ({ onChange, onAccept, ...props }) => <ControlledComponent {...props} />,
+};
+
+export default meta;