@coopdigital/react 0.33.0 → 0.34.0

package/dist/components/Input/Input.d.ts

@@ -3,7 +3,10 @@ import { FormFieldError, StandardSizes } from "../../../src/types";
 export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
     /** **(Optional)** Specify additional CSS classes to be applied to the component. */
     className?: string;
-    /** **(Optional)** Specify the Input error. */
+    /** **(Optional)** Specify the Input error state.
+     *
+     * This is an instance of `FormFieldError`. You can provide either an object with a `message` key, or a boolean value if you need to render the message independently.
+     */
     error?: FormFieldError;
     /** **(Optional)** Specify the Input hint.
      *

package/dist/components/Textarea/Textarea.d.ts

@@ -0,0 +1,47 @@
+import type { JSX, TextareaHTMLAttributes } from "react";
+import { FormFieldError, StandardSizes } from "../../types";
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** **(Optional)** Specify additional CSS classes to be applied to the component. */
+    className?: string;
+    /** Specify the number of columns (characters per row) in the Textarea. Defaults to `30`. */
+    cols?: number;
+    /** **(Optional)** Specify whether the Textarea should allow more characters than its `maxLength` value.
+     *
+     * Defaults to `false`, meaning users can enter more characters than the maximum but will be warned if they go over the limit. When set to `true`, users will be blocked from typing once they hit the character limit. This can be an accessiblity anti-pattern, so only use this option when absolutely necessary.
+     *
+     * Remember it is still your responsibility to handle validation on submission, this is simply a hint for the user.
+     */
+    cutoff?: boolean;
+    /** **(Optional)** Specify the Textarea error state.
+     *
+     * This is an instance of `FormFieldError`. You can provide either an object with a `message` key, or a boolean value if you need to render the message independently.
+     */
+    error?: FormFieldError;
+    /** **(Optional)** Specify the Textarea hint.
+     *
+     * This text is rendered under the label to provide further guidance for users.
+     */
+    hint?: string;
+    /** **(Optional)** Specify the Textarea id. Will be auto-generated if not set. */
+    id?: string;
+    /** **(Optional)** Specify the Textarea label.
+     *
+     * This property is optional in case you need to render your own label, but all form elements *must* provide a label. */
+    label?: string;
+    /** **(Optional)** Specify whether the label should be visible to humans or screen readers. */
+    labelVisible?: boolean;
+    /** **(Optional)** Specify the Textarea maxLength. This is the maximum number of characters users can enter. */
+    maxLength?: number;
+    /** Specify the Textarea name. */
+    name: string;
+    /** **(Optional)** Specify the Textarea placeholder text. Do not use in place of a form label. */
+    placeholder?: string;
+    /** Specify the number of rows (lines of text) in the Textarea. Defaults to `4`. */
+    rows?: number;
+    /** **(Optional)** Specify whether to show the remaining character count underneath the Textarea. */
+    showRemaining?: boolean;
+    /** **(Optional)** Specify the Textarea size. */
+    size?: StandardSizes;
+}
+export declare const Textarea: ({ "aria-placeholder": ariaPlaceholder, className, cols, cutoff, error, hint, id, label, labelVisible, maxLength, name, onChange: userOnChange, placeholder, rows, showRemaining, size, ...props }: TextareaProps) => JSX.Element;
+export default Textarea;

package/dist/components/Textarea/Textarea.js

@@ -0,0 +1,41 @@
+import { jsxs, Fragment, jsx } from 'react/jsx-runtime';
+import { clsx } from '../../node_modules/clsx/dist/clsx.js';
+import { useId, useState } from 'react';
+import { useDebounce } from '../../hooks/useDebounce.js';
+import { FieldError } from '../FieldError/FieldError.js';
+import { FieldHint } from '../FieldHint/FieldHint.js';
+import { FieldLabel } from '../FieldLabel/FieldLabel.js';
+
+const DEBOUNCE_DELAY = 750;
+const charCountMessage = (remaining) => {
+    return `You have ${Math.abs(remaining)} ${Math.abs(remaining) === 1 ? "character" : "characters"} ${remaining < 0 ? "too many" : "remaining"}`;
+};
+const Textarea = ({ "aria-placeholder": ariaPlaceholder, className, cols = 30, cutoff = false, error = false, hint, id, label, labelVisible = true, maxLength, name, onChange: userOnChange = undefined, placeholder, rows = 4, showRemaining = false, size = "md", ...props }) => {
+    var _a;
+    const internalId = useId();
+    id = id !== null && id !== void 0 ? id : internalId;
+    const componentProps = {
+        "aria-placeholder": (_a = placeholder !== null && placeholder !== void 0 ? placeholder : ariaPlaceholder) !== null && _a !== void 0 ? _a : undefined,
+        className: clsx("coop-textarea", className),
+        cols,
+        "data-error": error ? "" : undefined,
+        "data-size": size.length && size !== "md" ? size : undefined,
+        id,
+        maxLength: cutoff ? maxLength : undefined,
+        name,
+        placeholder,
+        rows,
+        ...props,
+    };
+    const [remaining, setRemaining] = useState(maxLength);
+    const debouncedRemaining = useDebounce(remaining, DEBOUNCE_DELAY);
+    const handleChange = (e) => {
+        maxLength && e.target && setRemaining(maxLength - e.target.value.length);
+    };
+    return (jsxs(Fragment, { children: [label && (jsx(FieldLabel, { htmlFor: id, isVisible: labelVisible, children: label })), hint && jsx(FieldHint, { children: hint }), typeof error === "object" && (error === null || error === void 0 ? void 0 : error.message) && jsx(FieldError, { children: error.message }), jsx("div", { className: "coop-field-control", children: jsx("textarea", { ...componentProps, onChange: (e) => {
+                        userOnChange === null || userOnChange === void 0 ? void 0 : userOnChange(e);
+                        handleChange(e);
+                    } }) }), showRemaining && maxLength && remaining != null && debouncedRemaining != null && (jsxs(Fragment, { children: [jsx("small", { "aria-hidden": "true", className: "coop-textarea-counter", ...(remaining < 0 && { "data-error": "" }), children: charCountMessage(remaining) }), jsx("span", { "aria-live": "polite", className: "sr-only", children: charCountMessage(debouncedRemaining) })] }))] }));
+};
+
+export { Textarea, Textarea as default };

package/dist/components/Textarea/index.d.ts

@@ -0,0 +1,4 @@
+import Textarea from "./Textarea";
+export default Textarea;
+export { Textarea };
+export * from "./Textarea";

package/dist/hooks/useDebounce.d.ts

@@ -0,0 +1 @@
+export declare function useDebounce<T>(value: T, delay: number): T;

package/dist/hooks/useDebounce.js

@@ -0,0 +1,16 @@
+import { useState, useEffect } from 'react';
+
+function useDebounce(value, delay) {
+    const [debouncedValue, setDebouncedValue] = useState(value);
+    useEffect(() => {
+        const handler = setTimeout(() => {
+            setDebouncedValue(value);
+        }, delay);
+        return () => {
+            clearTimeout(handler);
+        };
+    }, [value, delay]);
+    return debouncedValue;
+}
+
+export { useDebounce };

package/dist/index.d.ts

@@ -17,3 +17,4 @@ export * from "./components/Signpost";
 export * from "./components/SkipNav";
 export * from "./components/Squircle";
 export * from "./components/Tag";
+export * from "./components/Textarea";

package/dist/index.js

@@ -17,3 +17,4 @@ export { Signpost } from './components/Signpost/Signpost.js';
 export { SkipNav } from './components/SkipNav/SkipNav.js';
 export { Squircle } from './components/Squircle/Squircle.js';
 export { Tag } from './components/Tag/Tag.js';
+export { Textarea } from './components/Textarea/Textarea.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@coopdigital/react",
   "type": "module",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -80,7 +80,7 @@
     "storybook": "$storybook"
   },
   "dependencies": {
-    "@coopdigital/styles": "^0.29.0"
+    "@coopdigital/styles": "^0.30.0"
   },
-  "gitHead": "b7f3df204e1f4e38b3c978af0506243b30365b4a"
+  "gitHead": "858102db210474fc31e01a2f4dc97551af2621d3"
 }

package/src/components/Input/Input.tsx

@@ -11,7 +11,10 @@ import { FieldLabel } from "../FieldLabel"
 export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "type"> {
   /** **(Optional)** Specify additional CSS classes to be applied to the component. */
   className?: string
-  /** **(Optional)** Specify the Input error. */
+  /** **(Optional)** Specify the Input error state.
+   *
+   * This is an instance of `FormFieldError`. You can provide either an object with a `message` key, or a boolean value if you need to render the message independently.
+   */
   error?: FormFieldError
   /** **(Optional)** Specify the Input hint.
    *

package/src/components/Textarea/Textarea.tsx

@@ -0,0 +1,145 @@
+import type { ChangeEvent, JSX, TextareaHTMLAttributes } from "react"
+
+import clsx from "clsx"
+import { useId, useState } from "react"
+
+import { useDebounce } from "../../hooks/useDebounce"
+import { FormFieldError, StandardSizes } from "../../types"
+import { FieldError } from "../FieldError"
+import { FieldHint } from "../FieldHint"
+import { FieldLabel } from "../FieldLabel"
+
+const DEBOUNCE_DELAY = 750
+
+const charCountMessage = (remaining: number) => {
+  return `You have ${Math.abs(remaining)} ${Math.abs(remaining) === 1 ? "character" : "characters"} ${remaining < 0 ? "too many" : "remaining"}`
+}
+
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+  /** **(Optional)** Specify additional CSS classes to be applied to the component. */
+  className?: string
+  /** Specify the number of columns (characters per row) in the Textarea. Defaults to `30`. */
+  cols?: number
+  /** **(Optional)** Specify whether the Textarea should allow more characters than its `maxLength` value.
+   *
+   * Defaults to `false`, meaning users can enter more characters than the maximum but will be warned if they go over the limit. When set to `true`, users will be blocked from typing once they hit the character limit. This can be an accessiblity anti-pattern, so only use this option when absolutely necessary.
+   *
+   * Remember it is still your responsibility to handle validation on submission, this is simply a hint for the user.
+   */
+  cutoff?: boolean
+  /** **(Optional)** Specify the Textarea error state.
+   *
+   * This is an instance of `FormFieldError`. You can provide either an object with a `message` key, or a boolean value if you need to render the message independently.
+   */
+  error?: FormFieldError
+  /** **(Optional)** Specify the Textarea hint.
+   *
+   * This text is rendered under the label to provide further guidance for users.
+   */
+  hint?: string
+  /** **(Optional)** Specify the Textarea id. Will be auto-generated if not set. */
+  id?: string
+  /** **(Optional)** Specify the Textarea label.
+   *
+   * This property is optional in case you need to render your own label, but all form elements *must* provide a label. */
+  label?: string
+  /** **(Optional)** Specify whether the label should be visible to humans or screen readers. */
+  labelVisible?: boolean
+  /** **(Optional)** Specify the Textarea maxLength. This is the maximum number of characters users can enter. */
+  maxLength?: number
+  /** Specify the Textarea name. */
+  name: string
+  /** **(Optional)** Specify the Textarea placeholder text. Do not use in place of a form label. */
+  placeholder?: string
+  /** Specify the number of rows (lines of text) in the Textarea. Defaults to `4`. */
+  rows?: number
+  /** **(Optional)** Specify whether to show the remaining character count underneath the Textarea. */
+  showRemaining?: boolean
+  /** **(Optional)** Specify the Textarea size. */
+  size?: StandardSizes
+}
+
+export const Textarea = ({
+  "aria-placeholder": ariaPlaceholder,
+  className,
+  cols = 30,
+  cutoff = false,
+  error = false,
+  hint,
+  id,
+  label,
+  labelVisible = true,
+  maxLength,
+  name,
+  onChange: userOnChange = undefined,
+  placeholder,
+  rows = 4,
+  showRemaining = false,
+  size = "md",
+  ...props
+}: TextareaProps): JSX.Element => {
+  const internalId = useId()
+
+  id = id ?? internalId
+
+  const componentProps = {
+    "aria-placeholder": placeholder ?? ariaPlaceholder ?? undefined,
+    className: clsx("coop-textarea", className),
+    cols,
+    "data-error": error ? "" : undefined,
+    "data-size": size.length && size !== "md" ? size : undefined,
+    id,
+    maxLength: cutoff ? maxLength : undefined,
+    name,
+    placeholder,
+    rows,
+    ...props,
+  }
+
+  const [remaining, setRemaining] = useState(maxLength)
+  const debouncedRemaining = useDebounce(remaining, DEBOUNCE_DELAY)
+
+  const handleChange = (e: ChangeEvent<HTMLTextAreaElement>) => {
+    maxLength && e.target && setRemaining(maxLength - e.target.value.length)
+  }
+
+  return (
+    <>
+      {label && (
+        <FieldLabel htmlFor={id} isVisible={labelVisible}>
+          {label}
+        </FieldLabel>
+      )}
+
+      {hint && <FieldHint>{hint}</FieldHint>}
+
+      {typeof error === "object" && error?.message && <FieldError>{error.message}</FieldError>}
+      <div className="coop-field-control">
+        <textarea
+          {...componentProps}
+          onChange={(e) => {
+            userOnChange?.(e)
+            handleChange(e)
+          }}
+        ></textarea>
+      </div>
+
+      {showRemaining && maxLength && remaining != null && debouncedRemaining != null && (
+        <>
+          <small
+            aria-hidden="true"
+            className="coop-textarea-counter"
+            {...(remaining < 0 && { "data-error": "" })}
+          >
+            {charCountMessage(remaining)}
+          </small>
+          <span aria-live="polite" className="sr-only">
+            {charCountMessage(debouncedRemaining)}
+          </span>
+        </>
+      )}
+    </>
+  )
+}
+
+export default Textarea

package/src/components/Textarea/index.ts

@@ -0,0 +1,5 @@
+import Textarea from "./Textarea"
+
+export default Textarea
+export { Textarea }
+export * from "./Textarea"

package/src/hooks/useDebounce.ts

@@ -0,0 +1,16 @@
+import { useEffect, useState } from "react"
+
+export function useDebounce<T>(value: T, delay: number) {
+  const [debouncedValue, setDebouncedValue] = useState(value)
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value)
+    }, delay)
+
+    return () => {
+      clearTimeout(handler)
+    }
+  }, [value, delay])
+
+  return debouncedValue
+}

package/src/index.ts

@@ -17,3 +17,4 @@ export * from "./components/Signpost"
 export * from "./components/SkipNav"
 export * from "./components/Squircle"
 export * from "./components/Tag"
+export * from "./components/Textarea"