uikit-react-public 0.48.1 → 0.49.1

package/lib/components/DisplayField/DisplayField.tsx

@@ -0,0 +1,68 @@
+import { forwardRef, memo, OutputHTMLAttributes, use } from 'react';
+import { css, cx } from '@emotion/css';
+import useTheme from '../../theme/useTheme';
+import { FieldContext } from '../Field';
+import marginsStyle, { MarginProps } from '../common/marginsStyle';
+import formatDisplayValue, {
+  DisplayValueFormat,
+} from '../common/formatDisplayValue';
+
+export const NAME = 'ucl-uikit-display-field';
+
+export interface DisplayFieldBaseProps extends Omit<
+  OutputHTMLAttributes<HTMLOutputElement>,
+  'children' | 'value'
+> {
+  value: string | number;
+  numeric?: boolean;
+  format?: DisplayValueFormat;
+  testId?: string;
+}
+
+export type DisplayFieldProps = DisplayFieldBaseProps & MarginProps;
+
+export type Ref = HTMLOutputElement;
+
+const DisplayField = forwardRef<Ref, DisplayFieldProps>(
+  (
+    { value, numeric = false, format, testId = NAME, className, ...props },
+    ref
+  ) => {
+    const [theme] = useTheme();
+    const { id: contextId } = use(FieldContext);
+    const id = props.id ?? contextId;
+    const useNumericTypography = typeof value === 'number' || numeric;
+    const typography = useNumericTypography
+      ? theme.typography.body.mdNumeric
+      : theme.typography.body.md;
+    const displayedValue = formatDisplayValue(String(value), format);
+
+    const baseStyle = css`
+      display: block;
+      min-height: 24px;
+      color: ${theme.colour.text.default};
+      font-family: ${typography.fontFamily};
+      font-feature-settings: ${typography.fontSettings};
+      font-size: ${typography.fontSize}px;
+      font-weight: ${typography.fontWeight};
+      line-height: ${typography.lineHeight}%;
+      overflow-wrap: anywhere;
+    `;
+
+    const style = cx(NAME, baseStyle, marginsStyle(props, theme), className);
+
+    return (
+      <output
+        {...props}
+        ref={ref}
+        id={id}
+        className={style}
+        data-testid={testId}
+      >
+        {displayedValue}
+      </output>
+    );
+  }
+);
+
+export default memo(DisplayField);

package/lib/components/DisplayField/Documentation.mdx

@@ -0,0 +1,44 @@
+import * as DisplayFieldStories from './DisplayField.stories';
+import {
+  Meta,
+  Title,
+  Subtitle,
+  Canvas,
+  Source,
+  ArgTypes,
+} from '@storybook/addon-docs/blocks';
+
+<Meta of={DisplayFieldStories} />
+<Title />
+<Subtitle>A read-only field for displaying a single value</Subtitle>
+
+`DisplayField` renders a semantic HTML `<output>` element. Use it with `Label`
+to display a record in the same field structure used by editable forms.
+
+<Source
+  code={`<Field>
+  <Label>Account name</Label>
+  <DisplayField value='Personal savings' />
+</Field>`}
+/>
+
+## Props
+
+- `value`: **string | number** - The value to display.
+- `numeric`: **boolean** - Applies numeric typography to string values. Number
+  values use numeric typography automatically. Defaults to `false`.
+- `format`: **string | (value: string) => string** - Formats the displayed
+  value. In a string template, each `#` consumes one value character and other
+  characters are displayed literally. For example, `##-##-##` formats `112233`
+  as `11-22-33`.
+- All standard HTML `<output>` props are supported.
+
+<ArgTypes />
+
+## Examples
+
+<Canvas of={DisplayFieldStories.Text} />
+<Canvas of={DisplayFieldStories.Number} />
+<Canvas of={DisplayFieldStories.NumericString} />
+<Canvas of={DisplayFieldStories.StringFormat} />
+<Canvas of={DisplayFieldStories.FunctionFormat} />

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

@@ -0,0 +1,96 @@
+import { createRef } from 'react';
+import { describe, expect, test } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { ThemeContextProvider } from '../../../theme/useTheme';
+import DisplayField from '../DisplayField';
+import Field from '../../Field';
+import Label from '../../Label';
+
+const renderDisplayField = (props: React.ComponentProps<typeof DisplayField>) =>
+  render(
+    <ThemeContextProvider>
+      <DisplayField {...props} />
+    </ThemeContextProvider>
+  );
+
+describe('DisplayField', () => {
+  test('displays a text value', () => {
+    renderDisplayField({ value: 'Personal savings' });
+
+    expect(screen.getByTestId('ucl-uikit-display-field')).toHaveTextContent(
+      'Personal savings'
+    );
+  });
+
+  test('displays a numeric value', () => {
+    renderDisplayField({ value: 12345678 });
+
+    const output = screen.getByTestId('ucl-uikit-display-field');
+    expect(output).toHaveTextContent('12345678');
+    expect(getComputedStyle(output).fontFamily).toContain('DM Mono');
+  });
+
+  test('uses numeric typography for a string when numeric is true', () => {
+    renderDisplayField({ value: '00123456', numeric: true });
+
+    expect(
+      getComputedStyle(screen.getByTestId('ucl-uikit-display-field')).fontFamily
+    ).toContain('DM Mono');
+  });
+
+  test('formats a value with a string template', () => {
+    renderDisplayField({ value: '112233', format: '##-##-##' });
+
+    expect(screen.getByTestId('ucl-uikit-display-field')).toHaveTextContent(
+      '11-22-33'
+    );
+  });
+
+  test('appends value characters beyond a string template', () => {
+    renderDisplayField({ value: '11223344', format: '##-##-##' });
+
+    expect(screen.getByTestId('ucl-uikit-display-field')).toHaveTextContent(
+      '11-22-3344'
+    );
+  });
+
+  test('formats a value with a function', () => {
+    renderDisplayField({
+      value: 1234.5,
+      format: (value) => `£${value}`,
+    });
+
+    expect(screen.getByTestId('ucl-uikit-display-field')).toHaveTextContent(
+      '£1234.5'
+    );
+  });
+
+  test('shares the Field id with its Label', () => {
+    render(
+      <ThemeContextProvider>
+        <Field>
+          <Label>Account name</Label>
+          <DisplayField value='Personal savings' />
+        </Field>
+      </ThemeContextProvider>
+    );
+
+    const label = screen.getByText('Account name');
+    const output = screen.getByTestId('ucl-uikit-display-field');
+    expect(label).toHaveAttribute('for', output.id);
+  });
+
+  test('forwards its ref to the output', () => {
+    const ref = createRef<HTMLOutputElement>();
+    render(
+      <ThemeContextProvider>
+        <DisplayField
+          ref={ref}
+          value='Personal savings'
+        />
+      </ThemeContextProvider>
+    );
+
+    expect(ref.current).toBe(screen.getByTestId('ucl-uikit-display-field'));
+  });
+});

package/lib/components/DisplayField/index.ts

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

package/lib/components/Input/Documentation.mdx

@@ -17,6 +17,7 @@ export const usage = {
   rightIcon: `<Input icon={<Icon.Settings />} iconPosition='right' type='password' />`,
   password: `<Input type='password' />`,
   email: `<Input type='email' icon={<Icon.Facebook />} iconPosition='left' />`,
+  formatted: `<Input defaultValue='112233' format='##-##-##' />`,
 };
 
 <Meta of={InputStories} />
@@ -47,6 +48,10 @@ Use the Input component wherever standard inputs are required with optional enha
 - `type`: **string** – Input type (e.g. `text`, `password`, `email`, etc.)
 - `disabled`: **boolean** – Disables the input field
 - `placeholder`: **string** – Placeholder text
+- `format`: **string | (value: string) => string** – Formats the displayed
+  value while the input is blurred. `#` consumes one raw value character;
+  other template characters are displayed literally. The raw value is shown
+  while focused and remains unchanged for events and form submission.
 - All standard HTML `<input>` props are supported
 
 # Variants
@@ -92,3 +97,9 @@ Use the Input component wherever standard inputs are required with optional enha
   sourceState='shown'
   source={{ code: usage.email }}
 />
+
+<Canvas
+  of={InputStories.Formatted}
+  sourceState='shown'
+  source={{ code: usage.formatted }}
+/>

package/lib/components/Input/Input.stories.tsx

@@ -58,3 +58,10 @@ export const Email: Story = {
     iconPosition: 'left',
   },
 };
+
+export const Formatted: Story = {
+  args: {
+    defaultValue: '112233',
+    format: '##-##-##',
+  },
+};

package/lib/components/Input/Input.tsx

@@ -1,8 +1,14 @@
 import {
+  ChangeEvent,
+  FocusEvent,
   memo,
   InputHTMLAttributes,
   forwardRef,
   use,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
   ReactElement,
 } from 'react';
 import useTheme from '../../theme/useTheme';
@@ -11,6 +17,9 @@ import marginsStyle, { MarginProps } from '../common/marginsStyle';
 import { FieldContext } from '../Field';
 import { IconProps } from '../Icon';
 import { IconButtonProps } from '../IconButton/IconButton';
+import formatDisplayValue, {
+  DisplayValueFormat,
+} from '../common/formatDisplayValue';
 
 export const NAME = 'ucl-uikit-input';
 export const INPUT_NAME = 'ucl-uikit-input__input';
@@ -20,6 +29,7 @@ export interface InputBaseProps extends InputHTMLAttributes<HTMLInputElement> {
   iconPosition?: 'left' | 'right';
   iconButton?: ReactElement<IconButtonProps>;
   inputClassName?: string;
+  format?: DisplayValueFormat;
   testId?: string;
 }
 
@@ -35,17 +45,73 @@ const Input = forwardRef<Ref, InputProps>(
       iconPosition = 'left',
       iconButton,
       inputClassName,
+      format,
       className,
+      value,
+      defaultValue,
+      onChange,
+      onFocus,
+      onBlur,
       ...props
     },
-    ref
+    forwardedRef
   ) => {
     const [theme] = useTheme();
     const { md } = theme.typography.body;
+    const inputRef = useRef<HTMLInputElement>(null);
+    const [isFocused, setIsFocused] = useState(false);
+    const [uncontrolledValue, setUncontrolledValue] = useState(() => {
+      if (defaultValue === undefined || defaultValue === null) return '';
+      return Array.isArray(defaultValue)
+        ? defaultValue.join(',')
+        : String(defaultValue);
+    });
 
     const { disabled: contextDisabled, id: contextId } = use(FieldContext);
     const disabled = props.disabled ?? contextDisabled;
     const id = props.id ?? contextId;
+    const stringValue =
+      value === undefined
+        ? uncontrolledValue
+        : Array.isArray(value)
+          ? value.join(',')
+          : String(value);
+    const formattedValue = formatDisplayValue(stringValue, format);
+    const formattedValueIsVisible =
+      Boolean(format) && !isFocused && stringValue.length > 0;
+
+    const setInputRef = useCallback(
+      (element: HTMLInputElement | null) => {
+        inputRef.current = element;
+
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(element);
+        } else if (forwardedRef) {
+          forwardedRef.current = element;
+        }
+      },
+      [forwardedRef]
+    );
+
+    useEffect(() => {
+      const input = inputRef.current;
+      const form = input?.form;
+      if (!input || !form || value !== undefined || !format) 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);
+      };
+    }, [format, value]);
 
     const inputBaseStyle = css`
       height: 48px;
@@ -92,6 +158,11 @@ const Input = forwardRef<Ref, InputProps>(
       padding-right: ${theme.padding.p80};
     `;
 
+    const formattedInputStyle = css`
+      color: transparent;
+      -webkit-text-fill-color: transparent;
+    `;
+
     const hasRightIconAndButton = Boolean(
       icon && iconPosition === 'right' && iconButton
     );
@@ -106,6 +177,7 @@ const Input = forwardRef<Ref, InputProps>(
         !hasRightIconAndButton &&
         padRightStyle,
       hasRightIconAndButton && padRightForTwoControlsStyle,
+      formattedValueIsVisible && formattedInputStyle,
       inputClassName
     );
 
@@ -150,16 +222,76 @@ const Input = forwardRef<Ref, InputProps>(
 
     const iconButtonStyle = cx(iconWrapperBaseStyle, rightPositionStyle);
 
+    const formattedValueStyle = css`
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: ${
+        icon && iconPosition === 'left' ? theme.padding.p48 : theme.padding.p16
+      };
+      right: ${
+        hasRightIconAndButton
+          ? theme.padding.p80
+          : (icon && iconPosition === 'right') || iconButton
+            ? theme.padding.p48
+            : theme.padding.p16
+      };
+      display: flex;
+      align-items: center;
+      overflow: hidden;
+      color: ${
+        disabled ? 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);
+    };
+
     return (
       <span className={wrapperClass}>
         <input
-          ref={ref}
+          ref={setInputRef}
           id={id}
           className={inputStyle}
           data-testid={testId}
           disabled={disabled}
+          value={value}
+          defaultValue={defaultValue}
+          onChange={handleChange}
+          onFocus={handleFocus}
+          onBlur={handleBlur}
           {...props}
         />
+        {formattedValueIsVisible && (
+          <span
+            className={formattedValueStyle}
+            data-testid={`${testId}-formatted-value`}
+            aria-hidden='true'
+          >
+            {formattedValue}
+          </span>
+        )}
         {icon && <span className={iconWrapperStyle}>{icon}</span>}
         {iconButton && <span className={iconButtonStyle}>{iconButton}</span>}
       </span>

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

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest';
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import Input from '../Input';
 import { ThemeContextProvider } from '../../../theme/useTheme';
@@ -139,4 +139,99 @@ describe('Input', () => {
     expect(iconWrapper).toHaveStyle({ right: '48px' });
     expect(buttonWrapper).toHaveStyle({ right: '16px' });
   });
+
+  test('formats an uncontrolled value while blurred', async () => {
+    const user = userEvent.setup();
+    render(
+      <ThemeContextProvider>
+        <Input
+          defaultValue='112233'
+          format='##-##-##'
+        />
+      </ThemeContextProvider>
+    );
+
+    const input = screen.getByTestId('ucl-uikit-input');
+    expect(input).toHaveValue('112233');
+    expect(
+      screen.getByTestId('ucl-uikit-input-formatted-value')
+    ).toHaveTextContent('11-22-33');
+
+    await user.click(input);
+    expect(
+      screen.queryByTestId('ucl-uikit-input-formatted-value')
+    ).not.toBeInTheDocument();
+
+    await user.clear(input);
+    await user.type(input, '445566');
+    await user.tab();
+
+    expect(input).toHaveValue('445566');
+    expect(
+      screen.getByTestId('ucl-uikit-input-formatted-value')
+    ).toHaveTextContent('44-55-66');
+  });
+
+  test('formats a value with a function', () => {
+    render(
+      <ThemeContextProvider>
+        <Input
+          value='1234.5'
+          format={(value) => `£${value}`}
+          onChange={() => {}}
+        />
+      </ThemeContextProvider>
+    );
+
+    expect(
+      screen.getByTestId('ucl-uikit-input-formatted-value')
+    ).toHaveTextContent('£1234.5');
+  });
+
+  test('submits the raw value when formatted', () => {
+    render(
+      <ThemeContextProvider>
+        <form data-testid='form'>
+          <Input
+            name='sortCode'
+            defaultValue='112233'
+            format='##-##-##'
+          />
+        </form>
+      </ThemeContextProvider>
+    );
+
+    const form = screen.getByTestId('form') as HTMLFormElement;
+    expect(new FormData(form).get('sortCode')).toBe('112233');
+  });
+
+  test('resynchronises a formatted value after form reset', async () => {
+    const user = userEvent.setup();
+    render(
+      <ThemeContextProvider>
+        <form data-testid='form'>
+          <Input
+            defaultValue='112233'
+            format='##-##-##'
+          />
+        </form>
+      </ThemeContextProvider>
+    );
+
+    const input = screen.getByTestId('ucl-uikit-input');
+    const form = screen.getByTestId('form') as HTMLFormElement;
+    await user.click(input);
+    await user.clear(input);
+    await user.type(input, '445566');
+    await user.tab();
+
+    form.reset();
+
+    await waitFor(() => {
+      expect(input).toHaveValue('112233');
+      expect(
+        screen.getByTestId('ucl-uikit-input-formatted-value')
+      ).toHaveTextContent('11-22-33');
+    });
+  });
 });

package/lib/components/common/formatConfidentialValue.ts

@@ -0,0 +1,36 @@
+export type MaskFormat = string | ((value: string) => string);
+
+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 === '#') {
+      maskedValue += valueCharacters[valueIndex];
+      valueIndex += 1;
+    } else if (templateCharacter === '*') {
+      maskedValue += '*';
+      valueIndex += 1;
+    } else {
+      maskedValue += templateCharacter;
+    }
+  }
+
+  return (
+    maskedValue + '*'.repeat(Math.max(0, valueCharacters.length - valueIndex))
+  );
+};
+
+const formatConfidentialValue = (value: string, maskFormat: MaskFormat) => {
+  const maskedValue =
+    typeof maskFormat === 'function'
+      ? maskFormat(value)
+      : applyMaskTemplate(value, maskFormat);
+
+  return maskedValue.split('*').join('•');
+};
+
+export default formatConfidentialValue;

package/lib/components/common/formatDisplayValue.ts

@@ -0,0 +1,29 @@
+export type DisplayValueFormat = string | ((value: string) => string);
+
+const applyFormatTemplate = (value: string, template: string) => {
+  const valueCharacters = Array.from(value);
+  let valueIndex = 0;
+  let formattedValue = '';
+
+  for (const templateCharacter of Array.from(template)) {
+    if (valueIndex >= valueCharacters.length) break;
+
+    if (templateCharacter === '#') {
+      formattedValue += valueCharacters[valueIndex];
+      valueIndex += 1;
+    } else {
+      formattedValue += templateCharacter;
+    }
+  }
+
+  return formattedValue + valueCharacters.slice(valueIndex).join('');
+};
+
+const formatDisplayValue = (value: string, format?: DisplayValueFormat) => {
+  if (!format) return value;
+  return typeof format === 'function'
+    ? format(value)
+    : applyFormatTemplate(value, format);
+};
+
+export default formatDisplayValue;

package/lib/components/index.ts

@@ -7,6 +7,12 @@ export type { InputProps } from './Input';
 export { default as ConfidentialInput } from './ConfidentialInput';
 export type { ConfidentialInputProps } from './ConfidentialInput';
 
+export { default as DisplayField } from './DisplayField';
+export type { DisplayFieldProps } from './DisplayField';
+
+export { default as ConfidentialDisplayField } from './ConfidentialDisplayField';
+export type { ConfidentialDisplayFieldProps } from './ConfidentialDisplayField';
+
 export { default as Link } from './Link';
 export type { LinkProps } from './Link';
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "uikit-react-public",
   "private": false,
   "license": "UNLICENSED",
-  "version": "0.48.1",
+  "version": "0.49.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",