uikit-react-public 0.48.1 → 0.49.1

package/lib/components/ConfidentialDisplayField/ConfidentialDisplayField.stories.tsx

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

package/lib/components/ConfidentialDisplayField/ConfidentialDisplayField.tsx

@@ -0,0 +1,105 @@
+import { forwardRef, memo, useEffect, useState } from 'react';
+import { css, cx } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import DisplayField, { DisplayFieldProps } from '../DisplayField';
+import Icon from '../Icon';
+import IconButton from '../IconButton';
+import formatConfidentialValue, {
+  MaskFormat,
+} from '../common/formatConfidentialValue';
+import marginsStyle from '../common/marginsStyle';
+
+export const NAME = 'ucl-uikit-confidential-display-field';
+
+export interface ConfidentialDisplayFieldProps extends DisplayFieldProps {
+  maskFormat: MaskFormat;
+  showable?: boolean;
+}
+
+export type Ref = HTMLOutputElement;
+
+const ConfidentialDisplayField = forwardRef<Ref, ConfidentialDisplayFieldProps>(
+  (
+    {
+      value,
+      numeric,
+      maskFormat,
+      showable = false,
+      testId = NAME,
+      className,
+      m,
+      mv,
+      mh,
+      mt,
+      mb,
+      ml,
+      mr,
+      noMargins,
+      ...props
+    },
+    ref
+  ) => {
+    const [theme] = useTheme();
+    const [isShown, setIsShown] = useState(false);
+    const stringValue = String(value);
+    const valueIsShown = showable && isShown;
+    const displayedValue = valueIsShown
+      ? stringValue
+      : formatConfidentialValue(stringValue, maskFormat);
+
+    useEffect(() => {
+      if (!showable) setIsShown(false);
+    }, [showable]);
+
+    const wrapperStyle = cx(
+      NAME,
+      css`
+        display: inline-flex;
+        align-items: center;
+        gap: ${theme.padding.p8};
+      `,
+      marginsStyle({ m, mv, mh, mt, mb, ml, mr, noMargins }, theme),
+      className
+    );
+
+    return (
+      <span className={wrapperStyle}>
+        <DisplayField
+          {...props}
+          ref={ref}
+          value={displayedValue}
+          numeric={numeric ?? typeof value === 'number'}
+          testId={testId}
+          noMargins
+        />
+        {showable && (
+          <IconButton
+            type='button'
+            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>
+        )}
+      </span>
+    );
+  }
+);
+
+export default memo(ConfidentialDisplayField);

package/lib/components/ConfidentialDisplayField/Documentation.mdx

@@ -0,0 +1,46 @@
+import * as ConfidentialDisplayFieldStories from './ConfidentialDisplayField.stories';
+import {
+  Meta,
+  Title,
+  Subtitle,
+  Canvas,
+  Source,
+  ArgTypes,
+} from '@storybook/addon-docs/blocks';
+
+<Meta of={ConfidentialDisplayFieldStories} />
+<Title />
+<Subtitle>A DisplayField that masks confidential values</Subtitle>
+
+`ConfidentialDisplayField` extends `DisplayField` with the same simple mask
+format used by `ConfidentialInput`. `#` reveals a value character, `*` masks it
+with a `•`, and other characters are displayed as separators.
+
+<Source
+  code={`<ConfidentialDisplayField
+  value='123472'
+  maskFormat='****##'
+  format='##-##-##'
+  showable
+/>`}
+/>
+
+## Props
+
+- `value`: **string | number** - The original value.
+- `maskFormat`: **string | (value: string) => string** - Required mask template
+  or formatter.
+- `showable`: **boolean** - Adds a button that toggles the original value.
+  Defaults to `false`.
+- `format`: **string | (value: string) => string** - Formats both the masked
+  and visible values using the `DisplayField` format syntax.
+- All `DisplayField` props are supported.
+
+<ArgTypes />
+
+## Examples
+
+<Canvas of={ConfidentialDisplayFieldStories.Default} />
+<Canvas of={ConfidentialDisplayFieldStories.Showable} />
+<Canvas of={ConfidentialDisplayFieldStories.WithSeparators} />
+<Canvas of={ConfidentialDisplayFieldStories.FunctionMask} />

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

@@ -0,0 +1,144 @@
+import { createRef } from 'react';
+import { describe, expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import ConfidentialDisplayField from '../ConfidentialDisplayField';
+
+const renderDisplayField = (
+  props: React.ComponentProps<typeof ConfidentialDisplayField>
+) =>
+  render(
+    <ThemeContextProvider>
+      <ConfidentialDisplayField {...props} />
+    </ThemeContextProvider>
+  );
+
+describe('ConfidentialDisplayField', () => {
+  test('applies a string mask', () => {
+    renderDisplayField({
+      value: '12345678',
+      maskFormat: '******##',
+    });
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-display-field')
+    ).toHaveTextContent('••••••78');
+  });
+
+  test('applies a function mask', () => {
+    renderDisplayField({
+      value: 12345678,
+      maskFormat: (value) => `**** ending in ${value.slice(-2)}`,
+    });
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-display-field')
+    ).toHaveTextContent('•••• ending in 78');
+  });
+
+  test('does not add a visibility control by default', () => {
+    renderDisplayField({
+      value: '12345678',
+      maskFormat: '******##',
+    });
+
+    expect(
+      screen.queryByRole('button', { name: 'Show confidential value' })
+    ).not.toBeInTheDocument();
+  });
+
+  test('toggles the original value', async () => {
+    const user = userEvent.setup();
+    renderDisplayField({
+      value: '12345678',
+      maskFormat: '******##',
+      showable: true,
+    });
+
+    const output = screen.getByTestId('ucl-uikit-confidential-display-field');
+    await user.click(
+      screen.getByRole('button', { name: 'Show confidential value' })
+    );
+
+    expect(output).toHaveTextContent('12345678');
+    expect(
+      screen.getByRole('button', { name: 'Hide confidential value' })
+    ).toHaveAttribute('aria-pressed', 'true');
+
+    await user.click(
+      screen.getByRole('button', { name: 'Hide confidential value' })
+    );
+    expect(output).toHaveTextContent('••••••78');
+  });
+
+  test('formats both masked and visible values', async () => {
+    const user = userEvent.setup();
+    renderDisplayField({
+      value: '123472',
+      maskFormat: '****##',
+      format: '##-##-##',
+      showable: true,
+    });
+
+    const output = screen.getByTestId('ucl-uikit-confidential-display-field');
+    expect(output).toHaveTextContent('••-••-72');
+
+    await user.click(
+      screen.getByRole('button', { name: 'Show confidential value' })
+    );
+
+    expect(output).toHaveTextContent('12-34-72');
+  });
+
+  test('forwards its ref to the output', () => {
+    const ref = createRef<HTMLOutputElement>();
+    render(
+      <ThemeContextProvider>
+        <ConfidentialDisplayField
+          ref={ref}
+          value='12345678'
+          maskFormat='******##'
+        />
+      </ThemeContextProvider>
+    );
+
+    expect(ref.current).toBe(
+      screen.getByTestId('ucl-uikit-confidential-display-field')
+    );
+  });
+
+  test('hides the value when showable changes to false', async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(
+      <ThemeContextProvider>
+        <ConfidentialDisplayField
+          value='12345678'
+          maskFormat='******##'
+          showable
+        />
+      </ThemeContextProvider>
+    );
+
+    await user.click(
+      screen.getByRole('button', { name: 'Show confidential value' })
+    );
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-display-field')
+    ).toHaveTextContent('12345678');
+
+    rerender(
+      <ThemeContextProvider>
+        <ConfidentialDisplayField
+          value='12345678'
+          maskFormat='******##'
+          showable={false}
+        />
+      </ThemeContextProvider>
+    );
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-display-field')
+    ).toHaveTextContent('••••••78');
+  });
+});

package/lib/components/ConfidentialDisplayField/index.ts

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

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

@@ -11,7 +11,7 @@ const meta = {
   args: {
     'aria-label': 'Account number',
     defaultValue: '12345678',
-    maskFormat: '****1111',
+    maskFormat: '****####',
   },
 } satisfies Meta<typeof ConfidentialInput>;
 
@@ -31,7 +31,7 @@ export const WithSeparators: Story = {
   args: {
     'aria-label': 'Sort code',
     defaultValue: '123472',
-    maskFormat: '**-**-11',
+    maskFormat: '**-**-##',
     showable: true,
   },
 };

package/lib/components/ConfidentialInput/ConfidentialInput.tsx

@@ -16,6 +16,10 @@ import IconButton from '../IconButton';
 import Input, { InputProps } from '../Input';
 import { FieldContext } from '../Field';
 import marginsStyle from '../common/marginsStyle';
+import formatConfidentialValue, {
+  MaskFormat,
+} from '../common/formatConfidentialValue';
+import formatDisplayValue from '../common/formatDisplayValue';
 
 export const NAME = 'ucl-uikit-confidential-input';
 
@@ -23,7 +27,7 @@ export interface ConfidentialInputProps extends Omit<
   InputProps,
   'iconButton' | 'type'
 > {
-  maskFormat: string | ((value: string) => string);
+  maskFormat: MaskFormat;
   showable?: boolean;
   visibleWhenFocused?: boolean;
 }
@@ -37,36 +41,13 @@ const getStringValue = (
   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,
       visibleWhenFocused = true,
+      format,
       value,
       defaultValue,
       disabled,
@@ -142,13 +123,18 @@ const ConfidentialInput = forwardRef<Ref, ConfidentialInputProps>(
 
     const stringValue =
       value === undefined ? uncontrolledValue : getStringValue(value);
-    const maskedValue =
-      typeof maskFormat === 'function'
-        ? maskFormat(stringValue)
-        : applyMaskTemplate(stringValue, maskFormat);
-    const displayedMaskedValue = maskedValue.split('*').join('•');
-    const configuredMaskIsVisible =
-      !valueIsPersistentlyShown && !isFocused && stringValue.length > 0;
+    const displayedMaskedValue = formatConfidentialValue(
+      stringValue,
+      maskFormat
+    );
+    const configuredValueIsVisible =
+      !isFocused &&
+      stringValue.length > 0 &&
+      (!valueIsPersistentlyShown || Boolean(format));
+    const configuredValue = formatDisplayValue(
+      valueIsPersistentlyShown ? stringValue : displayedMaskedValue,
+      format
+    );
 
     const wrapperStyle = cx(
       NAME,
@@ -254,7 +240,7 @@ const ConfidentialInput = forwardRef<Ref, ConfidentialInputProps>(
           iconPosition={iconPosition}
           iconButton={visibilityButton}
           inputClassName={cx(
-            configuredMaskIsVisible && hiddenInputStyle,
+            configuredValueIsVisible && hiddenInputStyle,
             inputClassName
           )}
           testId={testId}
@@ -263,13 +249,13 @@ const ConfidentialInput = forwardRef<Ref, ConfidentialInputProps>(
           onFocus={handleFocus}
           onBlur={handleBlur}
         />
-        {configuredMaskIsVisible && (
+        {configuredValueIsVisible && (
           <span
             className={maskStyle}
             data-testid={`${testId}-mask`}
             aria-hidden='true'
           >
-            {displayedMaskedValue}
+            {configuredValue}
           </span>
         )}
       </span>

package/lib/components/ConfidentialInput/Documentation.mdx

@@ -19,7 +19,7 @@ change events, and form submission while displaying a masked value.
 
 ## Usage
 
-The string mask is a simple template. `1` reveals the corresponding value
+The string mask is a simple template. `#` reveals the corresponding value
 character, `*` masks it with a `•`, and all other characters are displayed as
 separators. Asterisks returned by a formatter function are also displayed as
 bullets. Focusing the input temporarily reveals the original value for editing,
@@ -32,7 +32,7 @@ value. The configured mask returns on blur.
 <Source
   code={`<ConfidentialInput
   defaultValue='12345678'
-  maskFormat='****1111'
+  maskFormat='****####'
   showable
   aria-label='Account number'
 />`}
@@ -58,6 +58,8 @@ A function can be supplied when the template syntax is not sufficient:
 - `visibleWhenFocused`: **boolean** - Reveals the original value while focused.
   When `false`, the native password mask is shown while editing. Defaults to
   `true`.
+- `format`: **string | (value: string) => string** - Formats both the masked
+  and visible values while blurred using the `Input` format syntax.
 - All `Input` props except `type` and `iconButton` are supported.
 
 <ArgTypes />

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

@@ -17,7 +17,7 @@ const renderInput = (props: React.ComponentProps<typeof ConfidentialInput>) =>
 describe('ConfidentialInput', () => {
   test('applies a string mask without changing the input value', () => {
     renderInput({
-      maskFormat: '1111****',
+      maskFormat: '####****',
       value: '12345678',
       onChange: () => {},
     });
@@ -32,7 +32,7 @@ describe('ConfidentialInput', () => {
 
   test('supports separators and masks characters beyond the template', () => {
     renderInput({
-      maskFormat: '**-**-11',
+      maskFormat: '**-**-##',
       value: '1234729',
       onChange: () => {},
     });
@@ -68,7 +68,7 @@ describe('ConfidentialInput', () => {
   test('toggles between the masked and shown value', async () => {
     const user = userEvent.setup();
     renderInput({
-      maskFormat: '****1111',
+      maskFormat: '****####',
       defaultValue: '12345678',
       showable: true,
     });
@@ -131,7 +131,7 @@ describe('ConfidentialInput', () => {
         <form data-testid='form'>
           <ConfidentialInput
             name='accountNumber'
-            maskFormat='****1111'
+            maskFormat='****####'
             defaultValue='12345678'
           />
         </form>
@@ -180,7 +180,7 @@ describe('ConfidentialInput', () => {
   test('shows the raw value while editing a non-showable value', async () => {
     const user = userEvent.setup();
     renderInput({
-      maskFormat: '**-**-11',
+      maskFormat: '**-**-##',
       defaultValue: '123472',
     });
 
@@ -209,7 +209,7 @@ describe('ConfidentialInput', () => {
   test('uses native password masking when visibleWhenFocused is false', async () => {
     const user = userEvent.setup();
     renderInput({
-      maskFormat: '**-**-11',
+      maskFormat: '**-**-##',
       defaultValue: '123472',
       visibleWhenFocused: false,
     });
@@ -240,7 +240,7 @@ describe('ConfidentialInput', () => {
   test('shows the raw value while editing a showable value', async () => {
     const user = userEvent.setup();
     renderInput({
-      maskFormat: '**-**-11',
+      maskFormat: '**-**-##',
       defaultValue: '123472',
       showable: true,
     });
@@ -289,6 +289,32 @@ describe('ConfidentialInput', () => {
     ).toHaveStyle({ right: '16px' });
   });
 
+  test('formats both masked and visible values while blurred', async () => {
+    const user = userEvent.setup();
+    renderInput({
+      value: '123472',
+      maskFormat: '****##',
+      format: '##-##-##',
+      showable: true,
+      onChange: () => {},
+    });
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('••-••-72');
+
+    await user.click(
+      screen.getByRole('button', { name: 'Show confidential value' })
+    );
+
+    expect(
+      screen.getByTestId('ucl-uikit-confidential-input-mask')
+    ).toHaveTextContent('12-34-72');
+    expect(screen.getByTestId('ucl-uikit-confidential-input')).toHaveValue(
+      '123472'
+    );
+  });
+
   test('disables the visibility control with the input', () => {
     renderInput({
       maskFormat: '****',

package/lib/components/DisplayField/DisplayField.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import DisplayField from './DisplayField';
+
+const meta = {
+  title: 'Components/DisplayField',
+  component: DisplayField,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+  args: {
+    value: 'Personal savings',
+  },
+} satisfies Meta<typeof DisplayField>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Text: Story = {};
+
+export const Number: Story = {
+  args: {
+    value: 12345678,
+  },
+};
+
+export const NumericString: Story = {
+  args: {
+    value: '00123456',
+    numeric: true,
+  },
+};
+
+export const StringFormat: Story = {
+  args: {
+    value: '112233',
+    numeric: true,
+    format: '##-##-##',
+  },
+};
+
+export const FunctionFormat: Story = {
+  args: {
+    value: 1234.5,
+    format: (value) => `£${value}`,
+  },
+};