@sproutsocial/seeds-react-token-input 1.0.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sproutsocial/seeds-react-token-input",
+  "version": "1.0.0",
+  "description": "Seeds React TokenInput",
+  "author": "Sprout Social, Inc.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup --dts",
+    "build:debug": "tsup --dts --metafile",
+    "dev": "tsup --watch --dts",
+    "clean": "rm -rf .turbo dist",
+    "clean:modules": "rm -rf node_modules",
+    "typecheck": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch --coverage=false"
+  },
+  "dependencies": {
+    "@sproutsocial/seeds-react-theme": "*",
+    "@sproutsocial/seeds-react-system-props": "*",
+    "@sproutsocial/seeds-react-mixins": "*",
+    "@sproutsocial/seeds-react-input": "*",
+    "@sproutsocial/seeds-react-box": "*",
+    "@sproutsocial/seeds-react-icon": "*",
+    "@sproutsocial/seeds-react-token": "*",
+    "lodash.uniqueid": "^4.0.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "@types/styled-components": "^5.1.26",
+    "@types/lodash.uniqueid": "^4.0.1",
+    "@sproutsocial/eslint-config-seeds": "*",
+    "react": "^18.0.0",
+    "styled-components": "^5.2.3",
+    "tsup": "^8.0.2",
+    "typescript": "^5.6.2",
+    "@sproutsocial/seeds-tsconfig": "*",
+    "@sproutsocial/seeds-testing": "*",
+    "@sproutsocial/seeds-react-testing-library": "*"
+  },
+  "peerDependencies": {
+    "styled-components": "^5.2.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/TokenInput.stories.tsx

@@ -0,0 +1,235 @@
+import React, { Fragment, useState } from "react";
+import { Icon } from "@sproutsocial/seeds-react-icon";
+import { TokenInput, type TypeTokenInputProps, type TypeTokenSpec } from "./";
+import type { Meta, StoryObj } from "@storybook/react";
+
+const MinimalStatefulTokenInput = (props: TypeTokenInputProps) => {
+  const { tokens, ...rest } = props;
+  const [tokenSpecs, setTokenSpecs] = useState(tokens || []);
+  return (
+    <Fragment>
+      <TokenInput
+        {...rest}
+        id="example"
+        name="example"
+        tokens={tokenSpecs}
+        onChangeTokens={setTokenSpecs}
+        autocomplete="off"
+      />
+    </Fragment>
+  );
+};
+
+const MeddlingStatefulTokenInput = (props: TypeTokenInputProps) => {
+  const { delimiters, value, tokens, ...rest } = props;
+  const [tokenSpecs, setTokenSpecs] = useState(tokens || []);
+  const [text, setText] = useState(value);
+
+  const handleAddToken = (newToken: TypeTokenSpec) => {
+    setTokenSpecs((tokens) => tokens.concat(newToken));
+    setText("");
+  };
+
+  const handleRemoveToken = (id: TypeTokenSpec["id"]) => {
+    setTokenSpecs((tokens) => tokens.filter((token) => token.id !== id));
+  };
+
+  // @ts-expect-error: event isn't used but it's required by the type
+  const handleChange = (e, newValue: TypeTokenSpec["value"]) => {
+    setText(newValue);
+  };
+
+  // @ts-expect-error: event isn't used but it's required by the type
+  const handleClickToken = (e, id: TypeTokenSpec["id"]) => {
+    handleRemoveToken(id);
+  };
+
+  return (
+    <Fragment>
+      <TokenInput
+        {...rest}
+        id="fine-grain"
+        name="fine-grain"
+        value={text}
+        tokens={tokenSpecs}
+        delimiters={delimiters}
+        onChange={handleChange}
+        onAddToken={handleAddToken}
+        onRemoveToken={handleRemoveToken}
+        onClickToken={handleClickToken}
+      />
+    </Fragment>
+  );
+};
+
+const meta: Meta<typeof TokenInput> = {
+  title: "Components/Form Elements/TokenInput",
+  component: TokenInput,
+  args: {
+    ariaLabel: "Enter names of fruits",
+    value: "",
+    disabled: undefined,
+    isInvalid: undefined,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof TokenInput>;
+
+export const Default: Story = {
+  render: (args) => (
+    <Fragment>
+      <MinimalStatefulTokenInput {...args} />
+    </Fragment>
+  ),
+  name: "Default",
+};
+
+export const HighControl: Story = {
+  args: {
+    tokens: [
+      {
+        id: "0",
+        value: "Cherries",
+      },
+      {
+        id: "1",
+        value: "Mangos",
+      },
+    ],
+  },
+  render: (args) => (
+    <Fragment>
+      <MeddlingStatefulTokenInput {...args} />
+    </Fragment>
+  ),
+  name: "Fine-grained state control",
+};
+
+export const TrimmedTokens: Story = {
+  args: {
+    tokenMaxLength: 4,
+  },
+  render: (args) => (
+    <Fragment>
+      <MinimalStatefulTokenInput {...args} />
+    </Fragment>
+  ),
+  name: "Trimming tokens",
+};
+
+export const WithIcon: Story = {
+  args: {
+    iconName: "lock-outline",
+  },
+  render: (args) => (
+    <Fragment>
+      <MinimalStatefulTokenInput {...args} />
+    </Fragment>
+  ),
+  name: "Tokens With Icon",
+};
+
+export const WithIndividualIcons: Story = {
+  args: {
+    iconName: "triangle-outline",
+    tokens: [
+      {
+        id: "0",
+        iconName: "face-smile-solid",
+        iconProps: {
+          "aria-label": "informative emoji icon",
+        },
+        value: "Cherries",
+      },
+      {
+        id: "1",
+        value: "Mangos",
+      },
+    ],
+  },
+  render: (args) => (
+    <Fragment>
+      <MeddlingStatefulTokenInput {...args} />
+    </Fragment>
+  ),
+  name: "Tokens With Individual Icons",
+};
+
+export const Disabled: Story = {
+  args: {
+    tokens: [
+      {
+        id: "0",
+        value: "One",
+      },
+      {
+        id: "1",
+        value: "Two",
+      },
+    ],
+    disabled: true,
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "Disabled",
+};
+
+export const Error: Story = {
+  args: {
+    isInvalid: true,
+    tokens: [
+      {
+        id: "0",
+        value: "One",
+      },
+      {
+        id: "1",
+        value: "Two",
+      },
+    ],
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "Error",
+};
+
+export const LeftIcon: Story = {
+  args: {
+    elemBefore: <Icon fixedWidth name="lock-outline" aria-hidden />,
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "Left Icon",
+};
+
+export const RightIcon: Story = {
+  args: {
+    elemAfter: <Icon fixedWidth name="lock-outline" aria-hidden />,
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "Right Icon",
+};
+
+export const LeftAndRightIcons: Story = {
+  args: {
+    elemBefore: <Icon fixedWidth name="magnifying-glass-outline" aria-hidden />,
+    elemAfter: <Icon fixedWidth name="lock-outline" aria-hidden />,
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "Left and right icons",
+};
+
+export const Autofocus: Story = {
+  args: {
+    autoFocus: true,
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "Autofocus",
+};
+
+export const WithPlaceholder: Story = {
+  args: {
+    placeholder: "Enter a token...",
+  },
+  render: (args) => <MinimalStatefulTokenInput {...args} />,
+  name: "With Placeholder",
+};

package/src/TokenInput.tsx

@@ -0,0 +1,302 @@
+import * as React from "react";
+import { Accessory } from "@sproutsocial/seeds-react-input";
+import Box from "@sproutsocial/seeds-react-box";
+import Icon from "@sproutsocial/seeds-react-icon";
+import Token from "@sproutsocial/seeds-react-token";
+import Container from "./styles";
+import { asTokenSpec, delimitersAsRegExp } from "./util";
+import type { TypeTokenInputProps, TypeTokenSpec } from "./TokenInputTypes";
+import { TokenScreenReaderStatus } from "./TokenScreenReaderStatus";
+
+type TypeState = {
+  prevProps: TypeTokenInputProps;
+  hasFocus: boolean;
+  activeToken: string | null | undefined;
+  value: string;
+};
+
+const DefaultDelimiters = [",", "Enter"];
+const ControlledPropNames: (keyof TypeState)[] = [
+  "value",
+  "hasFocus",
+  "activeToken",
+];
+
+export default class TokenInput extends React.Component<
+  TypeTokenInputProps,
+  TypeState
+> {
+  delimiterMatcher: RegExp;
+
+  constructor(props: TypeTokenInputProps) {
+    super(props);
+    const { hasFocus, activeToken, value, delimiters } = props;
+    this.delimiterMatcher = delimitersAsRegExp(delimiters || DefaultDelimiters);
+    this.state = {
+      prevProps: props,
+      hasFocus: hasFocus || false,
+      activeToken: activeToken,
+      value: value || "",
+    };
+  }
+
+  static getDerivedStateFromProps(
+    props: Readonly<TypeTokenInputProps>,
+    state: TypeState
+  ) {
+    const { prevProps } = state;
+    const modifiedState: Partial<TypeState> = { prevProps: props };
+    ControlledPropNames.forEach((propName) => {
+      const currentProp = props[propName as keyof TypeTokenInputProps];
+
+      // @ts-ignore: TODO - fix state types for prevProps
+      if (currentProp !== prevProps[propName]) {
+        modifiedState[propName] = currentProp;
+      }
+    });
+    modifiedState.prevProps = props;
+    return modifiedState;
+  }
+
+  isDelimiter(keyName: string) {
+    const { delimiters = DefaultDelimiters } = this.props;
+    return delimiters.includes(keyName);
+  }
+
+  spawnNewTokens(texts: string[]) {
+    const {
+      onAddToken,
+      onChangeTokens,
+      tokenMaxLength: max = Infinity,
+      tokens = [],
+    } = this.props;
+    const tokenSpecs = texts.map((text) => asTokenSpec(text.slice(0, max)));
+
+    if (onAddToken) {
+      tokenSpecs.forEach(onAddToken);
+    } else if (onChangeTokens) {
+      onChangeTokens(tokens.concat(tokenSpecs));
+    }
+
+    this.setState({
+      value: "",
+    });
+  }
+
+  deleteToken(tokenId?: string) {
+    const { onRemoveToken, onChangeTokens, tokens = [] } = this.props;
+    const count = tokens.length;
+    if (count === 0) return;
+    const id = tokenId ?? tokens[count - 1]?.id;
+
+    if (onRemoveToken) {
+      onRemoveToken(id ? id : "");
+    } else if (onChangeTokens) {
+      onChangeTokens(tokens.filter((tokenSpec) => tokenSpec.id !== id));
+    }
+
+    this.setState({
+      value: "",
+    });
+  }
+
+  handleChangeText = (e: React.SyntheticEvent<HTMLInputElement>) => {
+    const { value } = e.currentTarget;
+    const { onChange } = this.props;
+    this.setState({
+      value,
+    });
+    onChange?.(e, value);
+  };
+
+  handleFocus = (e: React.FocusEvent<HTMLInputElement>) => {
+    const { onFocus } = this.props;
+    this.setState({
+      hasFocus: true,
+    });
+    onFocus?.(e);
+  };
+
+  handleBlur = (e: React.FocusEvent<HTMLInputElement>) => {
+    const { onBlur } = this.props;
+    if (onBlur) onBlur(e);
+    this.setState({
+      hasFocus: false,
+    });
+  };
+
+  handleKeyUp = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    this.props.onKeyUp?.(e, e.currentTarget.value);
+  };
+
+  handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    const { onKeyDown } = this.props;
+    const { key, currentTarget } = e;
+    const text = currentTarget.value;
+    if (onKeyDown) onKeyDown(e, text);
+
+    // keyPress event runs before change
+    // Prevent event from bubbling up and calling change, which can lead to comma in value
+    if (this.isDelimiter(key)) {
+      if (text) {
+        this.spawnNewTokens([text]);
+        e.preventDefault();
+      }
+    } else if (key === "Backspace") {
+      if (text === "") {
+        this.deleteToken();
+      }
+    }
+  };
+
+  handlePaste = (e: React.ClipboardEvent<HTMLInputElement>) => {
+    const text = e.clipboardData.getData("text");
+    const { onPaste } = this.props;
+    if (onPaste) onPaste(e, text);
+    const subtexts = text.split(this.delimiterMatcher);
+    const texts = subtexts.filter((subtext) => subtext.length);
+
+    if (texts.length > 1) {
+      this.spawnNewTokens(texts);
+      e.preventDefault();
+    }
+  };
+
+  handleClickToken = (
+    e: React.SyntheticEvent<HTMLButtonElement>,
+    token: TypeTokenSpec
+  ) => {
+    const { onClickToken, disabled } = this.props;
+    if (onClickToken) onClickToken(e, token.id);
+
+    if (!disabled) {
+      this.deleteToken(token.id);
+    }
+  };
+
+  renderToken(token: TypeTokenSpec): React.ReactNode {
+    const { iconName: defaultIconName, disabled } = this.props;
+    const activeId = this.state.activeToken;
+    const {
+      id,
+      iconName: tokenIconName,
+      iconProps = { "aria-hidden": true },
+      value,
+      valid,
+    } = token;
+    const iconName = tokenIconName || defaultIconName;
+    const isActive = activeId === id;
+    return (
+      <Token
+        id={id}
+        onClick={(e) => this.handleClickToken(e, token)}
+        valid={valid}
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        active={isActive}
+        disabled={disabled}
+      >
+        <Box display="flex" alignItems="center">
+          {iconName && (
+            <Icon name={iconName} size="mini" pr={300} {...iconProps} />
+          )}
+          {value}
+        </Box>
+      </Token>
+    );
+  }
+
+  renderTokens(tokens: TypeTokenSpec[]): React.ReactNode {
+    return tokens.map<React.ReactNode>((token) => (
+      <div key={token.id} className="TokenInput-token">
+        {this.renderToken(token)}
+      </div>
+    ));
+  }
+
+  override render() {
+    const {
+      autoFocus,
+      autocomplete,
+      disabled,
+      isInvalid,
+      hasWarning,
+      id,
+      name,
+      placeholder,
+      required,
+      elemBefore,
+      elemAfter,
+      maxLength,
+      ariaDescribedby,
+      ariaLabel,
+      innerRef,
+      // These functions are used in the class functions above, but need to be extracted in order for `rest` to be correct
+      /* eslint-disable @typescript-eslint/no-unused-vars */
+      value,
+      onAddToken,
+      onRemoveToken,
+      onChangeTokens,
+      onClickToken,
+      onBlur,
+      onChange,
+      onFocus,
+      onKeyDown,
+      onKeyUp,
+      onPaste,
+      /* eslint-enable @typescript-eslint/no-unused-vars */
+      inputProps = {},
+      qa = {},
+      tokens,
+      ...rest
+    } = this.props;
+    const { state } = this;
+    return (
+      <Container
+        hasBeforeElement={!!elemBefore}
+        hasAfterElement={!!elemAfter}
+        disabled={disabled}
+        invalid={!!isInvalid}
+        warning={hasWarning}
+        focused={state.hasFocus}
+        {...rest}
+      >
+        {elemBefore && <Accessory before>{elemBefore}</Accessory>}
+
+        {tokens && this.renderTokens(tokens)}
+
+        <TokenScreenReaderStatus tokens={tokens} />
+
+        <input
+          aria-describedby={ariaDescribedby}
+          aria-invalid={!!isInvalid}
+          aria-label={ariaLabel}
+          autoFocus={autoFocus}
+          autoComplete={autocomplete}
+          disabled={disabled}
+          id={id}
+          name={name}
+          placeholder={placeholder}
+          type="text"
+          required={required}
+          value={state.value}
+          maxLength={maxLength}
+          onBlur={this.handleBlur}
+          onChange={this.handleChangeText}
+          onFocus={this.handleFocus}
+          onKeyDown={this.handleKeyDown}
+          onKeyUp={this.handleKeyUp}
+          onPaste={this.handlePaste}
+          ref={innerRef}
+          data-qa-input={name || ""}
+          data-qa-input-isdisabled={!!disabled}
+          data-qa-input-isrequired={!!required}
+          {...qa}
+          {...inputProps}
+        />
+
+        {elemAfter && <Accessory after>{elemAfter}</Accessory>}
+      </Container>
+    );
+  }
+}

package/src/TokenInputTypes.ts

@@ -0,0 +1,119 @@
+import * as React from "react";
+import type {
+  TypeStyledComponentsCommonProps,
+  TypeSystemCommonProps,
+} from "@sproutsocial/seeds-react-system-props";
+import type {
+  TypeIconProps,
+  TypeIconName,
+} from "@sproutsocial/seeds-react-icon";
+
+export interface TypeTokenSpec {
+  id: string;
+  iconName?: TypeIconName;
+  iconProps?: Omit<TypeIconProps, "name">;
+  value: string;
+  valid?: boolean;
+}
+
+export interface TypeBaseTokenInputProps {
+  /** ID of the form element, should match the "for" value of the associated label */
+  id: string;
+  name: string;
+  iconName?: TypeIconName;
+
+  /** Array of delimiter key names */
+  delimiters?: string[];
+
+  /** Current input text. Required when controlling the input text */
+  value?: string;
+
+  /** Current focus state. Required when controlling the focus via onFocus and onBlur */
+  hasFocus?: boolean;
+
+  /** Id of the currently selected token */
+  activeToken?: string;
+
+  /** Array of current tokens */
+  tokens?: TypeTokenSpec[];
+
+  /** Standard control of changing tokens. For fine-grain control use onAddToken and onRemoveToken, instead */
+  onChangeTokens?: (tokens: TypeTokenSpec[]) => void;
+
+  /** Fine-grained control of adding tokens. Use with onRemoveToken instead of onChangeTokens */
+  onAddToken?: (tokenSpec: TypeTokenSpec) => void;
+
+  /** Fine-grained control of removing tokens. Use with onAddToken instead of onChangeTokens */
+  onRemoveToken?: (tokenId: string) => void;
+
+  /** Controls clicking on a token. When absent, clicking a token removes itself */
+  onClickToken?: (
+    e: React.SyntheticEvent<HTMLButtonElement>,
+    tokenId: string
+  ) => void;
+
+  /** Fine-grained control of the input text used to create tokens */
+  onChange?: (e: React.SyntheticEvent<HTMLInputElement>, value: string) => void;
+
+  /** Fine-grained control of pasted text */
+  onPaste?: (e: React.ClipboardEvent<HTMLInputElement>, value: string) => void;
+  onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
+  onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void;
+  onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>, value: string) => void;
+  onKeyUp?: (e: React.KeyboardEvent<HTMLInputElement>, value: string) => void;
+
+  /** Attribute used to associate other elements that describe the Input, like an error */
+  ariaDescribedby?: string;
+
+  /** Label used to describe the input if not used with an accompanying visual label */
+  ariaLabel?: string;
+
+  /** Placeholder text for when value is undefined or empty */
+  placeholder?: string;
+
+  /** Will autofocus the element when mounted to the DOM */
+  autoFocus?: boolean;
+
+  /** HTML disabled attribute */
+  disabled?: boolean;
+
+  /** Whether or not the current contents of the input are invalid */
+  isInvalid?: boolean;
+
+  /** Whether or not the current contents of the input has any warnings */
+  hasWarning?: boolean;
+
+  /** HTML required attribute */
+  required?: boolean;
+
+  /** 16x16 element, such as an icon */
+  elemBefore?: React.ReactNode;
+
+  /** 16x16 element, such as an icon */
+  elemAfter?: React.ReactNode;
+
+  /** Max input text length */
+  maxLength?: number;
+
+  /** Max length of the token */
+  tokenMaxLength?: number;
+
+  /** Props to spread onto the underlying input element */
+  inputProps?: React.ComponentPropsWithoutRef<"input">;
+
+  /** Used to get a reference to the underlying element */
+  innerRef?: React.Ref<HTMLInputElement>;
+  qa?: object;
+
+  /** Browser autocomplete support */
+  autocomplete?: string;
+}
+
+export interface TypeTokenInputProps
+  extends TypeBaseTokenInputProps,
+    TypeStyledComponentsCommonProps,
+    TypeSystemCommonProps,
+    Omit<
+      React.ComponentPropsWithoutRef<"div">,
+      keyof TypeBaseTokenInputProps | "color"
+    > {}