[core] feat(InputGroup): add leftElement prop

packages/core/src/common/classes.ts

@@ -143,6 +143,7 @@ export const HTML_TABLE_STRIPED = `${HTML_TABLE}-striped`;
 export const INPUT = `${NS}-input`;
 export const INPUT_GHOST = `${INPUT}-ghost`;
 export const INPUT_GROUP = `${INPUT}-group`;
+export const INPUT_LEFT_CONTAINER = `${INPUT}-left-container`;
 export const INPUT_ACTION = `${INPUT}-action`;
 
 export const CONTROL = `${NS}-control`;

packages/core/src/common/errors.ts

@@ -36,6 +36,9 @@ export const HOTKEYS_WARN_DECORATOR_NO_METHOD = ns + ` @HotkeysTarget-decorated
 export const HOTKEYS_WARN_DECORATOR_NEEDS_REACT_ELEMENT =
     ns + ` "@HotkeysTarget-decorated components must return a single JSX.Element or an empty render.`;
 
+export const INPUT_WARN_LEFT_ELEMENT_LEFT_ICON_MUTEX =
+    ns + ` <InputGroup> leftElement and leftIcon prop are mutually exclusive, with leftElement taking priority.`;
+
 export const NUMERIC_INPUT_MIN_MAX = ns + ` <NumericInput> requires min to be no greater than max if both are defined.`;
 export const NUMERIC_INPUT_MINOR_STEP_SIZE_BOUND =
     ns + ` <NumericInput> requires minorStepSize to be no greater than stepSize.`;

packages/core/src/common/props.ts

@@ -121,6 +121,7 @@ const INVALID_PROPS = [
     "inline",
     "large",
     "loading",
+    "leftElement",
     "leftIcon",
     "minimal",
     "onRemove", // ITagProps, ITagInputProps

packages/core/src/components/forms/_input-group.scss

@@ -59,6 +59,7 @@ $input-button-height-small: $pt-button-height-smaller !default;
   }
 
   .#{$ns}-input-action,
+  > .#{$ns}-input-left-container,
   > .#{$ns}-button,
   > .#{$ns}-icon {
     position: absolute;
@@ -83,10 +84,15 @@ $input-button-height-small: $pt-button-height-smaller !default;
     &:empty { padding: 0; }
   }
 
-  // direct descendant to exclude icons in buttons
+  // bump icon or left content up so it sits above input
+  > .#{$ns}-input-left-container,
   > .#{$ns}-icon {
-    // bump icon up so it sits above input
     z-index: 1;
+  }
+
+  // direct descendant to exclude icons in buttons
+  > .#{$ns}-input-left-container > .#{$ns}-icon,
+  > .#{$ns}-icon {
     color: $pt-icon-color;
 
     &:empty {
@@ -96,6 +102,7 @@ $input-button-height-small: $pt-button-height-smaller !default;
 
   // adjusting the margin of spinners in input groups
   // we have to avoid targetting buttons that contain a spinner
+  > .#{$ns}-input-left-container > .#{$ns}-icon,
   > .#{$ns}-icon,
   .#{$ns}-input-action > .#{$ns}-spinner {
     margin: ($pt-input-height - $pt-icon-size-standard) / 2;
@@ -150,6 +157,7 @@ $input-button-height-small: $pt-button-height-smaller !default;
       margin: ($pt-input-height-large - $input-button-height-large) / 2;
     }
 
+    > .#{$ns}-input-left-container > .#{$ns}-icon,
     > .#{$ns}-icon,
     .#{$ns}-input-action > .#{$ns}-spinner {
       margin: ($pt-input-height-large - $pt-icon-size-standard) / 2;
@@ -179,6 +187,7 @@ $input-button-height-small: $pt-button-height-smaller !default;
       margin: ($pt-input-height-small - $pt-button-height-smaller) / 2;
     }
 
+    > .#{$ns}-input-left-container > .#{$ns}-icon,
     > .#{$ns}-icon,
     .#{$ns}-input-action > .#{$ns}-spinner {
       margin: ($pt-input-height-small - $pt-icon-size-standard) / 2;

packages/core/src/components/forms/inputGroup.tsx

@@ -18,6 +18,7 @@ import classNames from "classnames";
 import * as React from "react";
 import { polyfill } from "react-lifecycles-compat";
 import { AbstractPureComponent2, Classes } from "../../common";
+import * as Errors from "../../common/errors";
 import {
     DISPLAYNAME_PREFIX,
     HTMLInputProps,
@@ -29,8 +30,6 @@ import {
 } from "../../common/props";
 import { Icon, IconName } from "../icon/icon";
 
-const DEFAULT_RIGHT_ELEMENT_WIDTH = 10;
-
 // NOTE: This interface does not extend HTMLInputProps due to incompatiblity with `IControlledProps`.
 // Instead, we union the props in the component definition, which does work and properly disallows `string[]` values.
 export interface IInputGroupProps extends IControlledProps, IIntentProps, IProps {
@@ -50,8 +49,15 @@ export interface IInputGroupProps extends IControlledProps, IIntentProps, IProps
     inputRef?: (ref: HTMLInputElement | null) => any;
 
     /**
-     * Name of a Blueprint UI icon (or an icon element) to render on the left side of the input group,
-     * before the user's cursor.
+     * Element to render on the left side of input.  This prop is mutually exclusive
+     * with `leftIcon`.
+     */
+    leftElement?: JSX.Element;
+
+    /**
+     * Name of a Blueprint UI icon to render on the left side of the input group,
+     * before the user's cursor.  This prop is mutually exclusive with `leftElement`.
+     * Usage with content is deprecated.  Use `leftElement` for elements.
      */
     leftIcon?: IconName | MaybeElement;
 
@@ -81,24 +87,26 @@ export interface IInputGroupProps extends IControlledProps, IIntentProps, IProps
 }
 
 export interface IInputGroupState {
-    rightElementWidth: number;
+    leftElementWidth?: number;
+    rightElementWidth?: number;
 }
 
 @polyfill
 export class InputGroup extends AbstractPureComponent2<IInputGroupProps & HTMLInputProps, IInputGroupState> {
     public static displayName = `${DISPLAYNAME_PREFIX}.InputGroup`;
 
-    public state: IInputGroupState = {
-        rightElementWidth: DEFAULT_RIGHT_ELEMENT_WIDTH,
-    };
+    public state: IInputGroupState = {};
 
+    private leftElement: HTMLElement;
     private rightElement: HTMLElement;
+
     private refHandlers = {
+        leftElement: (ref: HTMLSpanElement) => (this.leftElement = ref),
         rightElement: (ref: HTMLSpanElement) => (this.rightElement = ref),
     };
 
     public render() {
-        const { className, disabled, fill, intent, large, small, leftIcon, round } = this.props;
+        const { className, disabled, fill, intent, large, small, round } = this.props;
         const classes = classNames(
             Classes.INPUT_GROUP,
             Classes.intentClass(intent),
@@ -111,11 +119,16 @@ export class InputGroup extends AbstractPureComponent2<IInputGroupProps & HTMLIn
             },
             className,
         );
-        const style: React.CSSProperties = { ...this.props.style, paddingRight: this.state.rightElementWidth };
+
+        const style: React.CSSProperties = {
+            ...this.props.style,
+            paddingLeft: this.state.leftElementWidth,
+            paddingRight: this.state.rightElementWidth,
+        };
 
         return (
             <div className={classes}>
-                <Icon icon={leftIcon} />
+                {this.maybeRenderLeftElement()}
                 <input
                     type="text"
                     {...removeNonHTMLProps(this.props)}
@@ -133,11 +146,34 @@ export class InputGroup extends AbstractPureComponent2<IInputGroupProps & HTMLIn
     }
 
     public componentDidUpdate(prevProps: IInputGroupProps & HTMLInputProps) {
-        if (prevProps.rightElement !== this.props.rightElement) {
+        const { leftElement, rightElement } = this.props;
+        if (prevProps.leftElement !== leftElement || prevProps.rightElement !== rightElement) {
             this.updateInputWidth();
         }
     }
 
+    protected validateProps(props: IInputGroupProps) {
+        if (props.leftElement != null && props.leftIcon != null) {
+            console.warn(Errors.INPUT_WARN_LEFT_ELEMENT_LEFT_ICON_MUTEX);
+        }
+    }
+
+    private maybeRenderLeftElement() {
+        const { leftElement, leftIcon } = this.props;
+
+        if (leftElement != null) {
+            return (
+                <span className={Classes.INPUT_LEFT_CONTAINER} ref={this.refHandlers.leftElement}>
+                    {leftElement}
+                </span>
+            );
+        } else if (leftIcon != null) {
+            return <Icon icon={leftIcon} />;
+        }
+
+        return undefined;
+    }
+
     private maybeRenderRightElement() {
         const { rightElement } = this.props;
         if (rightElement == null) {
@@ -151,14 +187,26 @@ export class InputGroup extends AbstractPureComponent2<IInputGroupProps & HTMLIn
     }
 
     private updateInputWidth() {
+        const { leftElementWidth, rightElementWidth } = this.state;
+
+        if (this.leftElement != null) {
+            const { clientWidth } = this.leftElement;
+            // small threshold to prevent infinite loops
+            if (leftElementWidth === undefined || Math.abs(clientWidth - leftElementWidth) > 2) {
+                this.setState({ leftElementWidth: clientWidth });
+            }
+        } else {
+            this.setState({ leftElementWidth: undefined });
+        }
+
         if (this.rightElement != null) {
             const { clientWidth } = this.rightElement;
             // small threshold to prevent infinite loops
-            if (Math.abs(clientWidth - this.state.rightElementWidth) > 2) {
+            if (rightElementWidth === undefined || Math.abs(clientWidth - rightElementWidth) > 2) {
                 this.setState({ rightElementWidth: clientWidth });
             }
         } else {
-            this.setState({ rightElementWidth: DEFAULT_RIGHT_ELEMENT_WIDTH });
+            this.setState({ rightElementWidth: undefined });
         }
     }
 }

packages/core/test/controls/inputGroupTests.tsx

@@ -38,7 +38,7 @@ describe("<InputGroup>", () => {
     it(`renders right element inside .${Classes.INPUT_ACTION} after input`, () => {
         const action = mount(<InputGroup rightElement={<address />} />)
             .children()
-            .childAt(2);
+            .childAt(1);
         assert.isTrue(action.hasClass(Classes.INPUT_ACTION));
         assert.lengthOf(action.find("address"), 1);
     });

packages/docs-app/src/examples/core-examples/inputGroupExample.tsx

@@ -117,7 +117,7 @@ export class InputGroupExample extends React.PureComponent<IExampleProps, IInput
                 <InputGroup
                     disabled={disabled}
                     large={large}
-                    leftIcon="tag"
+                    leftElement={<Icon icon="tag" />}
                     onChange={this.handleTagChange}
                     placeholder="Find tags"
                     rightElement={resultsTag}