uikit-react-public 0.47.1 → 0.48.0

package/lib/components/ConfidentialInput/ConfidentialInput.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import ConfidentialInput from './ConfidentialInput';
+
+const meta = {
+  title: 'Components/ConfidentialInput',
+  component: ConfidentialInput,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  args: {
+    'aria-label': 'Account number',
+    defaultValue: '12345678',
+    maskFormat: '****1111',
+  },
+} satisfies Meta<typeof ConfidentialInput>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const Showable: Story = {
+  args: {
+    showable: true,
+  },
+};
+
+export const WithSeparators: Story = {
+  args: {
+    'aria-label': 'Sort code',
+    defaultValue: '123472',
+    maskFormat: '**-**-11',
+    showable: true,
+  },
+};
+
+export const FunctionMask: Story = {
+  args: {
+    maskFormat: (value) =>
+      `${'*'.repeat(Math.max(0, value.length - 2))}${value.slice(-2)}`,
+    showable: true,
+  },
+};

package/lib/components/ConfidentialInput/ConfidentialInput.tsx

@@ -0,0 +1,273 @@
+import {
+  ChangeEvent,
+  FocusEvent,
+  forwardRef,
+  memo,
+  use,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import { css, cx } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import Icon from '../Icon';
+import IconButton from '../IconButton';
+import Input, { InputProps } from '../Input';
+import { FieldContext } from '../Field';
+import marginsStyle from '../common/marginsStyle';
+
+export const NAME = 'ucl-uikit-confidential-input';
+
+export interface ConfidentialInputProps extends Omit<
+  InputProps,
+  'iconButton' | 'type'
+> {
+  maskFormat: string | ((value: string) => string);
+  showable?: boolean;
+}
+
+export type Ref = HTMLInputElement;
+
+const getStringValue = (
+  value: InputProps['value'] | InputProps['defaultValue']
+) => {
+  if (value === undefined || value === null) return '';
+  return Array.isArray(value) ? value.join(',') : String(value);
+};
+
+const applyMaskTemplate = (value: string, template: string) => {
+  const valueCharacters = Array.from(value);
+  let valueIndex = 0;
+  let maskedValue = '';
+
+  for (const templateCharacter of Array.from(template)) {
+    if (valueIndex >= valueCharacters.length) break;
+
+    if (templateCharacter === '1') {
+      maskedValue += valueCharacters[valueIndex];
+      valueIndex += 1;
+    } else if (templateCharacter === '*') {
+      maskedValue += '*';
+      valueIndex += 1;
+    } else {
+      maskedValue += templateCharacter;
+    }
+  }
+
+  return (
+    maskedValue + '*'.repeat(Math.max(0, valueCharacters.length - valueIndex))
+  );
+};
+
+const ConfidentialInput = forwardRef<Ref, ConfidentialInputProps>(
+  (
+    {
+      maskFormat,
+      showable = false,
+      value,
+      defaultValue,
+      disabled,
+      icon,
+      iconPosition = 'left',
+      inputClassName,
+      className,
+      testId = NAME,
+      onChange,
+      onBlur,
+      onFocus,
+      m,
+      mv,
+      mh,
+      mt,
+      mb,
+      ml,
+      mr,
+      noMargins,
+      ...props
+    },
+    ref
+  ) => {
+    const [theme] = useTheme();
+    const { disabled: contextDisabled } = use(FieldContext);
+    const inputRef = useRef<HTMLInputElement>(null);
+    const [isShown, setIsShown] = useState(false);
+    const [isFocused, setIsFocused] = useState(false);
+    const [uncontrolledValue, setUncontrolledValue] = useState(() =>
+      getStringValue(defaultValue)
+    );
+    const resolvedDisabled = disabled ?? contextDisabled;
+    const valueIsShown = showable && isShown;
+
+    const setInputRef = useCallback(
+      (element: HTMLInputElement | null) => {
+        inputRef.current = element;
+
+        if (typeof ref === 'function') {
+          ref(element);
+        } else if (ref) {
+          ref.current = element;
+        }
+      },
+      [ref]
+    );
+
+    useEffect(() => {
+      if (!showable) setIsShown(false);
+    }, [showable]);
+
+    useEffect(() => {
+      const input = inputRef.current;
+      const form = input?.form;
+      if (!input || !form || value !== undefined) return;
+
+      let resetTimeout: ReturnType<typeof setTimeout> | undefined;
+      const handleReset = () => {
+        if (resetTimeout) clearTimeout(resetTimeout);
+        resetTimeout = setTimeout(() => {
+          setUncontrolledValue(input.value);
+        });
+      };
+
+      form.addEventListener('reset', handleReset);
+      return () => {
+        form.removeEventListener('reset', handleReset);
+        if (resetTimeout) clearTimeout(resetTimeout);
+      };
+    }, [value]);
+
+    const stringValue =
+      value === undefined ? uncontrolledValue : getStringValue(value);
+    const maskedValue =
+      typeof maskFormat === 'function'
+        ? maskFormat(stringValue)
+        : applyMaskTemplate(stringValue, maskFormat);
+    const visuallyHidden =
+      !valueIsShown && !isFocused && stringValue.length > 0;
+
+    const wrapperStyle = cx(
+      NAME,
+      css`
+        position: relative;
+        display: block;
+      `,
+      marginsStyle({ m, mv, mh, mt, mb, ml, mr, noMargins }, theme),
+      className
+    );
+
+    const hiddenInputStyle = css`
+      color: transparent;
+      -webkit-text-fill-color: transparent;
+      caret-color: ${theme.colour.text.default};
+    `;
+
+    const { md } = theme.typography.body;
+    const maskStyle = css`
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: ${
+        icon && iconPosition === 'left' ? theme.padding.p48 : theme.padding.p16
+      };
+      right: ${
+        showable && icon && iconPosition === 'right'
+          ? theme.padding.p80
+          : showable || (icon && iconPosition === 'right')
+            ? theme.padding.p48
+            : theme.padding.p16
+      };
+      display: flex;
+      align-items: center;
+      overflow: hidden;
+      color: ${
+        resolvedDisabled
+          ? theme.colour.text.disabled
+          : theme.colour.text.default
+      };
+      font-family: ${md.fontFamily};
+      font-feature-settings: ${md.fontSettings};
+      font-size: ${md.fontSize}px;
+      font-weight: ${md.fontWeight};
+      line-height: ${md.lineHeight}%;
+      pointer-events: none;
+      white-space: nowrap;
+    `;
+
+    const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+      if (value === undefined) {
+        setUncontrolledValue(event.target.value);
+      }
+      onChange?.(event);
+    };
+
+    const handleFocus = (event: FocusEvent<HTMLInputElement>) => {
+      setIsFocused(true);
+      onFocus?.(event);
+    };
+
+    const handleBlur = (event: FocusEvent<HTMLInputElement>) => {
+      setIsFocused(false);
+      onBlur?.(event);
+    };
+
+    const visibilityButton = showable ? (
+      <IconButton
+        type='button'
+        disabled={resolvedDisabled}
+        aria-label={
+          valueIsShown ? 'Hide confidential value' : 'Show confidential value'
+        }
+        aria-pressed={valueIsShown}
+        testId={`${testId}-visibility-toggle`}
+        onClick={() => setIsShown((shown) => !shown)}
+      >
+        {valueIsShown ? (
+          <Icon.EyeOff
+            aria-hidden='true'
+            testId={`${testId}-hide-icon`}
+          />
+        ) : (
+          <Icon.Eye
+            aria-hidden='true'
+            testId={`${testId}-show-icon`}
+          />
+        )}
+      </IconButton>
+    ) : undefined;
+
+    return (
+      <span className={wrapperStyle}>
+        <Input
+          {...props}
+          ref={setInputRef}
+          value={value}
+          defaultValue={defaultValue}
+          disabled={resolvedDisabled}
+          icon={icon}
+          iconPosition={iconPosition}
+          iconButton={visibilityButton}
+          inputClassName={cx(
+            visuallyHidden && hiddenInputStyle,
+            inputClassName
+          )}
+          testId={testId}
+          type={valueIsShown ? 'text' : 'password'}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
+        />
+        {visuallyHidden && (
+          <span
+            className={maskStyle}
+            data-testid={`${testId}-mask`}
+            aria-hidden='true'
+          >
+            {maskedValue}
+          </span>
+        )}
+      </span>
+    );
+  }
+);
+
+export default memo(ConfidentialInput);

package/lib/components/ConfidentialInput/Documentation.mdx

@@ -0,0 +1,62 @@
+import * as ConfidentialInputStories from './ConfidentialInput.stories';
+import {
+  Meta,
+  Title,
+  Subtitle,
+  Canvas,
+  Source,
+  ArgTypes,
+} from '@storybook/addon-docs/blocks';
+
+<Meta of={ConfidentialInputStories} />
+<Title />
+<Subtitle>An Input that masks confidential values</Subtitle>
+
+`ConfidentialInput` extends `Input` and preserves the original value for editing,
+change events, and form submission while displaying a masked value.
+
+<Canvas of={ConfidentialInputStories.Default} />
+
+## Usage
+
+The string mask is a simple template. `1` reveals the corresponding value
+character, `*` masks it, and all other characters are displayed as separators.
+The configured mask is displayed while the input is unfocused. While editing,
+the native password mask is used so the caret and selection remain aligned with
+the underlying value.
+
+<Source
+  code={`<ConfidentialInput
+  defaultValue='12345678'
+  maskFormat='****1111'
+  showable
+  aria-label='Account number'
+/>`}
+/>
+
+A function can be supplied when the template syntax is not sufficient:
+
+<Source
+  code={`<ConfidentialInput
+  defaultValue='12345678'
+  maskFormat={(value) =>
+    \`\${'*'.repeat(Math.max(0, value.length - 2))}\${value.slice(-2)}\`
+  }
+/>`}
+/>
+
+## Props
+
+- `maskFormat`: **string | (value: string) => string** - Required mask template
+  or formatter.
+- `showable`: **boolean** - Adds a button that toggles the original value.
+  Defaults to `false`.
+- All `Input` props except `type` and `iconButton` are supported.
+
+<ArgTypes />
+
+## Examples
+
+<Canvas of={ConfidentialInputStories.Showable} />
+<Canvas of={ConfidentialInputStories.WithSeparators} />
+<Canvas of={ConfidentialInputStories.FunctionMask} />

package/lib/components/ConfidentialInput/__tests__/ConfidentialInput.test.tsx

@@ -0,0 +1,272 @@
+import { createRef } from 'react';
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import ConfidentialInput from '../ConfidentialInput';
+import Field from '../../Field';
+import Icon from '../../Icon';
+
+const renderInput = (props: React.ComponentProps<typeof ConfidentialInput>) =>
+  render(
+    <ThemeContextProvider>
+      <ConfidentialInput {...props} />
+    </ThemeContextProvider>
+  );
+
+describe('ConfidentialInput', () => {
+  test('applies a string mask without changing the input value', () => {
+    renderInput({
+      maskFormat: '1111****',
+      value: '12345678',
+      onChange: () => {},
+    });
+
+    expect(screen.getByTestId('ucl-uikit-confidential-input')).toHaveValue(
+      '12345678'
+    );
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('1234****');
+  });
+
+  test('supports separators and masks characters beyond the template', () => {
+    renderInput({
+      maskFormat: '**-**-11',
+      value: '1234729',
+      onChange: () => {},
+    });
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('**-**-72*');
+  });
+
+  test('applies a function mask', () => {
+    renderInput({
+      maskFormat: (value) => `ending in ${value.slice(-2)}`,
+      value: '12345678',
+      onChange: () => {},
+    });
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('ending in 78');
+  });
+
+  test('does not add a visibility control by default', () => {
+    renderInput({
+      maskFormat: '****',
+      defaultValue: '1234',
+    });
+
+    expect(
+      screen.queryByRole('button', { name: 'Show confidential value' })
+    ).not.toBeInTheDocument();
+  });
+
+  test('toggles between the masked and shown value', async () => {
+    const user = userEvent.setup();
+    renderInput({
+      maskFormat: '****1111',
+      defaultValue: '12345678',
+      showable: true,
+    });
+
+    const input = screen.getByTestId('ucl-uikit-confidential-input');
+    const showButton = screen.getByRole('button', {
+      name: 'Show confidential value',
+    });
+
+    expect(input).toHaveAttribute('type', 'password');
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-show-icon')
+    ).toBeInTheDocument();
+
+    await user.click(showButton);
+
+    expect(input).toHaveAttribute('type', 'text');
+    expect(
+      screen.queryByTestId('ucl-uikit-confidential-input-mask')
+    ).not.toBeInTheDocument();
+    expect(
+      screen.getByRole('button', { name: 'Hide confidential value' })
+    ).toHaveAttribute('aria-pressed', 'true');
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-hide-icon')
+    ).toBeInTheDocument();
+  });
+
+  test('updates an uncontrolled value and reports the original value', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+    renderInput({
+      maskFormat: '****',
+      onChange,
+    });
+
+    const input = screen.getByTestId('ucl-uikit-confidential-input');
+    await user.type(input, '1234');
+
+    expect(input).toHaveValue('1234');
+    expect(
+      screen.queryByTestId('ucl-uikit-confidential-input-mask')
+    ).not.toBeInTheDocument();
+
+    await user.tab();
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('****');
+    expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({}));
+    expect(onChange.mock.lastCall?.[0].target.value).toBe('1234');
+  });
+
+  test('submits the original value', () => {
+    render(
+      <ThemeContextProvider>
+        <form data-testid='form'>
+          <ConfidentialInput
+            name='accountNumber'
+            maskFormat='****1111'
+            defaultValue='12345678'
+          />
+        </form>
+      </ThemeContextProvider>
+    );
+
+    const form = screen.getByTestId('form') as HTMLFormElement;
+    expect(new FormData(form).get('accountNumber')).toBe('12345678');
+  });
+
+  test('resynchronises the mask after a native form reset', async () => {
+    const user = userEvent.setup();
+    render(
+      <ThemeContextProvider>
+        <form data-testid='form'>
+          <ConfidentialInput
+            maskFormat={(value) => value}
+            defaultValue='1234'
+          />
+        </form>
+      </ThemeContextProvider>
+    );
+
+    const input = screen.getByTestId('ucl-uikit-confidential-input');
+    const form = screen.getByTestId('form') as HTMLFormElement;
+
+    await user.clear(input);
+    await user.type(input, '9876');
+
+    await user.tab();
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('9876');
+
+    form.reset();
+
+    await waitFor(() => {
+      expect(input).toHaveValue('1234');
+      expect(
+        screen.getByTestId('ucl-uikit-confidential-input-mask')
+      ).toHaveTextContent('1234');
+    });
+  });
+
+  test('uses native password rendering while editing formatted values', async () => {
+    const user = userEvent.setup();
+    renderInput({
+      maskFormat: '**-**-11',
+      defaultValue: '123472',
+    });
+
+    const input = screen.getByTestId(
+      'ucl-uikit-confidential-input'
+    ) as HTMLInputElement;
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('**-**-72');
+
+    await user.click(input);
+
+    expect(input).toHaveAttribute('type', 'password');
+    expect(
+      screen.queryByTestId('ucl-uikit-confidential-input-mask')
+    ).not.toBeInTheDocument();
+    input.setSelectionRange(4, 4);
+    expect(input.selectionStart).toBe(4);
+
+    await user.tab();
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('**-**-72');
+  });
+
+  test('supports a right icon alongside the visibility control', () => {
+    renderInput({
+      maskFormat: '****',
+      defaultValue: '1234',
+      showable: true,
+      icon: <Icon.Search testId='right-icon' />,
+      iconPosition: 'right',
+    });
+
+    expect(screen.getByTestId('right-icon').parentElement).toHaveStyle({
+      right: '48px',
+    });
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-visibility-toggle')
+        .parentElement
+    ).toHaveStyle({ right: '16px' });
+  });
+
+  test('disables the visibility control with the input', () => {
+    renderInput({
+      maskFormat: '****',
+      defaultValue: '1234',
+      showable: true,
+      disabled: true,
+    });
+
+    expect(
+      screen.getByRole('button', { name: 'Show confidential value' })
+    ).toBeDisabled();
+  });
+
+  test('inherits its disabled state from Field', () => {
+    render(
+      <ThemeContextProvider>
+        <Field disabled>
+          <ConfidentialInput
+            maskFormat='****'
+            defaultValue='1234'
+            showable
+          />
+        </Field>
+      </ThemeContextProvider>
+    );
+
+    expect(screen.getByTestId('ucl-uikit-confidential-input')).toBeDisabled();
+    expect(
+      screen.getByRole('button', { name: 'Show confidential value' })
+    ).toBeDisabled();
+  });
+
+  test('forwards its ref to the input', () => {
+    const ref = createRef<HTMLInputElement>();
+    render(
+      <ThemeContextProvider>
+        <ConfidentialInput
+          ref={ref}
+          maskFormat='****'
+        />
+      </ThemeContextProvider>
+    );
+
+    expect(ref.current).toBe(
+      screen.getByTestId('ucl-uikit-confidential-input')
+    );
+  });
+});

package/lib/components/ConfidentialInput/index.ts

@@ -0,0 +1,2 @@
+export { default } from './ConfidentialInput';
+export type { ConfidentialInputProps } from './ConfidentialInput';

package/lib/components/Input/Input.tsx

@@ -88,13 +88,24 @@ const Input = forwardRef<Ref, InputProps>(
       padding-right: ${theme.padding.p48};
     `;
 
+    const padRightForTwoControlsStyle = css`
+      padding-right: ${theme.padding.p80};
+    `;
+
+    const hasRightIconAndButton = Boolean(
+      icon && iconPosition === 'right' && iconButton
+    );
+
     const inputStyle = cx(
       INPUT_NAME,
       inputBaseStyle,
       !disabled && activeAndFocusStyle,
       disabled && disabledStyle,
       icon && iconPosition === 'left' && padLeftStyle,
-      ((icon && iconPosition === 'right') || iconButton) && padRightStyle,
+      ((icon && iconPosition === 'right') || iconButton) &&
+        !hasRightIconAndButton &&
+        padRightStyle,
+      hasRightIconAndButton && padRightForTwoControlsStyle,
       inputClassName
     );
 
@@ -126,10 +137,15 @@ const Input = forwardRef<Ref, InputProps>(
       right: ${theme.padding.p16};
     `;
 
+    const rightIconWithButtonPositionStyle = css`
+      right: ${theme.padding.p48};
+    `;
+
     const iconWrapperStyle = cx(
       iconWrapperBaseStyle,
       iconPosition === 'left' && leftPositionStyle,
-      iconPosition === 'right' && rightPositionStyle
+      iconPosition === 'right' &&
+        (iconButton ? rightIconWithButtonPositionStyle : rightPositionStyle)
     );
 
     const iconButtonStyle = cx(iconWrapperBaseStyle, rightPositionStyle);