@purpurds/text-field 5.3.0 → 5.4.0

package/dist/utils.d.ts

@@ -0,0 +1,4 @@
+import { MutableRefObject } from 'react';
+
+export declare const useMutableRefObject: <T>(value: T) => MutableRefObject<T>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAU,MAAM,OAAO,CAAC;AAEjD,eAAO,MAAM,mBAAmB,aAAc,CAAC,KAAG,iBAAiB,CAAC,CAEnE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purpurds/text-field",
-  "version": "5.3.0",
+  "version": "5.4.0",
   "license": "AGPL-3.0-only",
   "main": "./dist/text-field.cjs.js",
   "types": "./dist/text-field.d.ts",
@@ -15,12 +15,13 @@
   "source": "src/text-field.tsx",
   "dependencies": {
     "classnames": "~2.5.0",
-    "@purpurds/field-error-text": "5.3.0",
-    "@purpurds/spinner": "5.3.0",
-    "@purpurds/label": "5.3.0",
-    "@purpurds/tokens": "5.3.0",
-    "@purpurds/icon": "5.3.0",
-    "@purpurds/field-helper-text": "5.3.0"
+    "@purpurds/button": "5.4.0",
+    "@purpurds/icon": "5.4.0",
+    "@purpurds/label": "5.4.0",
+    "@purpurds/field-error-text": "5.4.0",
+    "@purpurds/tokens": "5.4.0",
+    "@purpurds/field-helper-text": "5.4.0",
+    "@purpurds/spinner": "5.4.0"
   },
   "devDependencies": {
     "@rushstack/eslint-patch": "~1.10.0",

package/readme.mdx

@@ -40,10 +40,15 @@ In MyComponent.tsx
 import { TextField } from "@purpurds/purpur";
 
 export const MyComponent = () => {
+  const [value, setValue] = useState("");
+
   return (
-    <div>
-      <TextField {...someProps}>Some content</TextField>
-    </div>
+    <TextField
+      value={value}
+      onChange={setValue}
+      onClear={() => setValue("")}
+      clearButtonAllyLabel="Clear"
+    />
   );
 };
 ```

package/src/text-field.module.scss

@@ -59,6 +59,10 @@
       }
     }
 
+    &--has-clear-button {
+      padding-right: var(--purpur-spacing-25);
+    }
+
     &--start-adornment {
       padding-left: var(--purpur-spacing-150);
 

package/src/text-field.stories.tsx

@@ -4,6 +4,7 @@ import type { Meta, StoryObj } from "@storybook/react";
 
 import "@purpurds/label/styles";
 import "@purpurds/field-helper-text/styles";
+import "@purpurds/button/styles";
 import "@purpurds/field-error-text/styles";
 import "@purpurds/icon/styles";
 import "@purpurds/spinner/styles";

package/src/text-field.test.tsx

@@ -108,8 +108,8 @@ describe("TextField", () => {
   it("should render with adornment", () => {
     render(
       <TextField
-        startAdornment={<span data-testid="start-adornment" />}
-        endAdornment={<span data-testid="end-adornment" />}
+        startAdornment={<span key="start" data-testid="start-adornment" />}
+        endAdornment={<span key="end" data-testid="end-adornment" />}
         id="test"
         data-testid="test"
         label="Test label"
@@ -215,4 +215,26 @@ describe("TextField", () => {
     expect(input).toHaveValue("Changed");
     expect(onChangeMock).toHaveBeenCalled();
   });
+
+  it("should call onClear when clicking the clear button", async () => {
+    const onClearMock = vi.fn();
+    const onChangeMock = vi.fn();
+    render(
+      <TextField
+        id="test"
+        data-testid="test"
+        value="a value"
+        onClear={onClearMock}
+        onChange={onChangeMock}
+        clearButtonAllyLabel="Clear"
+      />
+    );
+
+    const button = screen.getByTestId("test-clear-button");
+
+    // Simulate click on the clear button
+    fireEvent.click(button);
+
+    expect(onClearMock).toHaveBeenCalledTimes(1);
+  });
 });

package/src/text-field.tsx

@@ -6,18 +6,21 @@ import React, {
   ReactNode,
   useId,
 } from "react";
+import { Button } from "@purpurds/button";
 import { FieldErrorText } from "@purpurds/field-error-text";
 import { FieldHelperText } from "@purpurds/field-helper-text";
-import { checkCircleFilled, Icon } from "@purpurds/icon";
+import { IconCheckCircleFilled, IconClose } from "@purpurds/icon";
 import { Label } from "@purpurds/label";
 import { Spinner } from "@purpurds/spinner";
-import c from "classnames";
+import c from "classnames/bind";
 
 import styles from "./text-field.module.scss";
+import { useMutableRefObject } from "./utils";
 
-export type TextFieldProps = ComponentPropsWithoutRef<"input"> & {
+type TextFieldBaseProps = {
   ["data-testid"]?: string;
   className?: string;
+
   /**
    * Use to display e.g. a button after the text field.
    *
@@ -46,6 +49,7 @@ export type TextFieldProps = ComponentPropsWithoutRef<"input"> & {
    *  Use to render a spinner at the end inside of the text field.
    */
   loading?: boolean;
+
   /**
    * Use to display e.g. an icon at the start inside of the text field.
    *
@@ -66,18 +70,47 @@ export type TextFieldProps = ComponentPropsWithoutRef<"input"> & {
   valid?: boolean;
 };
 
+type TextFieldClearProps =
+  | {
+      /**
+       * An accessible label for the clear button.
+       * */
+      clearButtonAllyLabel: string;
+      /**
+       * Event handler called when the clear button is clicked.
+       * */
+      onClear: () => void;
+    }
+  | {
+      /**
+       * An accessible label for the clear button.
+       * */
+      clearButtonAllyLabel?: never;
+      /**
+       * Event handler called when the clear button is clicked.
+       * */
+      onClear?: never;
+    };
+
+export type TextFieldProps = ComponentPropsWithoutRef<"input"> &
+  TextFieldBaseProps &
+  TextFieldClearProps;
+
+const cx = c.bind(styles);
 const rootClassName = "purpur-text-field";
 
 const TextFieldComponent = (
   {
     ["data-testid"]: dataTestId,
     className,
+    clearButtonAllyLabel,
     afterField,
     endAdornment,
     errorText,
     helperText,
     label,
     loading = false,
+    onClear,
     startAdornment,
     valid = false,
     ...inputProps
@@ -89,8 +122,32 @@ const TextFieldComponent = (
   const getTestId = (name: string) => (dataTestId ? `${dataTestId}-${name}` : undefined);
   const isValid = valid && !errorText;
   const helperTextId = helperText ? `${inputId}-helper-text` : undefined;
-
   const startAdornments: ReactNode[] = [startAdornment].filter((adornment) => !!adornment);
+  const hasValue =
+    typeof inputProps.value === "number"
+      ? inputProps.value !== undefined
+      : inputProps.value?.length;
+  const hasClearButton =
+    hasValue &&
+    !inputProps.disabled &&
+    !inputProps.readOnly &&
+    !loading &&
+    onClear &&
+    clearButtonAllyLabel;
+
+  const internalRef = useMutableRefObject<HTMLInputElement | null>(null);
+  const setRef = (node: HTMLInputElement | null) => {
+    internalRef.current = node;
+    if (typeof ref === "function") {
+      ref(node);
+    } else if (ref) {
+      ref.current = node;
+    }
+  };
+  const handleClear = () => {
+    onClear?.();
+    internalRef.current?.focus();
+  };
 
   const endAdornments: ReactNode[] = [
     loading && (
@@ -102,46 +159,57 @@ const TextFieldComponent = (
       />
     ),
     isValid && (
-      <Icon
+      <IconCheckCircleFilled
         key="valid-icon"
         data-testid={getTestId("valid-icon")}
-        className={styles[`${rootClassName}__valid-icon`]}
-        svg={checkCircleFilled}
-        size="md"
+        className={cx(`${rootClassName}__valid-icon`)}
       />
     ),
+    hasClearButton && (
+      <Button
+        key="clear-button"
+        variant="tertiary-purple"
+        onClick={handleClear}
+        iconOnly
+        aria-label={clearButtonAllyLabel ?? ""}
+        data-testid={getTestId("clear-button")}
+        tabIndex={-1}
+      >
+        <IconClose size="xs" />
+      </Button>
+    ),
     endAdornment,
   ].filter((adornment) => !!adornment);
 
-  const inputContainerClassnames = c([
-    styles[`${rootClassName}__input-container`],
+  const inputContainerClassnames = cx([
+    `${rootClassName}__input-container`,
     {
-      [styles[`${rootClassName}__input-container--start-adornment`]]: startAdornments.length,
-      [styles[`${rootClassName}__input-container--end-adornment`]]: endAdornments.length,
-      [styles[`${rootClassName}__input-container--disabled`]]: inputProps.disabled,
-      [styles[`${rootClassName}__input-container--readonly`]]:
-        inputProps.readOnly && !inputProps.disabled,
+      [`${rootClassName}__input-container--start-adornment`]: startAdornments.length,
+      [`${rootClassName}__input-container--end-adornment`]: endAdornments.length,
+      [`${rootClassName}__input-container--disabled`]: inputProps.disabled,
+      [`${rootClassName}__input-container--has-clear-button`]: hasClearButton,
+      [`${rootClassName}__input-container--readonly`]: inputProps.readOnly && !inputProps.disabled,
     },
   ]);
 
   return (
-    <div className={c(className, styles[rootClassName])}>
+    <div className={cx(className, rootClassName)}>
       {label && (
         <Label
           htmlFor={inputId}
-          className={styles[`${rootClassName}__label`]}
+          className={cx(`${rootClassName}__label`)}
           data-testid={getTestId("label")}
           disabled={inputProps.disabled}
         >
           {`${inputProps.required ? "* " : ""}${label}`}
         </Label>
       )}
-      <div className={styles[`${rootClassName}__field-row`]}>
+      <div className={cx(`${rootClassName}__field-row`)}>
         <div className={inputContainerClassnames}>
           {!!startAdornments.length && (
             <div
               data-testid={getTestId("start-adornments")}
-              className={styles[`${rootClassName}__adornment-container`]}
+              className={cx(`${rootClassName}__adornment-container`)}
             >
               {startAdornments}
             </div>
@@ -149,23 +217,23 @@ const TextFieldComponent = (
           <input
             {...inputProps}
             id={inputId}
-            ref={ref}
+            ref={setRef}
             data-testid={getTestId("input")}
             aria-describedby={inputProps["aria-describedby"] || helperTextId}
             aria-invalid={inputProps["aria-invalid"] || !!errorText}
-            className={c([
-              styles[`${rootClassName}__input`],
+            className={cx([
+              `${rootClassName}__input`,
               {
-                [styles[`${rootClassName}__input--valid`]]: isValid,
-                [styles[`${rootClassName}__input--error`]]: !!errorText,
+                [`${rootClassName}__input--valid`]: isValid,
+                [`${rootClassName}__input--error`]: !!errorText,
               },
             ])}
           />
-          <div className={styles[`${rootClassName}__frame`]} />
+          <div className={cx(`${rootClassName}__frame`)} />
           {!!endAdornments.length && (
             <div
               data-testid={getTestId("end-adornments")}
-              className={styles[`${rootClassName}__adornment-container`]}
+              className={cx(`${rootClassName}__adornment-container`)}
             >
               {endAdornments}
             </div>

package/src/utils.ts

@@ -0,0 +1,5 @@
+import { MutableRefObject, useRef } from "react";
+
+export const useMutableRefObject = <T>(value: T): MutableRefObject<T> => {
+  return useRef<T>(value) as MutableRefObject<T>;
+};