[core] HTML Label component (#2571)

* Label docs refactor * add Label HTML component * delete old Label and tests * fix Label usages in examples
palantir · Jun 6, 2018 · 381cbc7 · 381cbc7 · blueprint-bot · Jun 6, 2018
1 parent 4c40ada
commit 381cbc7
Show file tree

Hide file tree

Showing 21 changed files with 71 additions and 184 deletions.
diff --git a/packages/core/src/components/forms/_label.scss b/packages/core/src/components/forms/_label.scss
@@ -10,25 +10,34 @@ Markup:
 <div>
   <label class="#{$ns}-label {{.modifier}}">
     Label A
-    <span class="#{$ns}-text-muted">(required)</span>
-    <input class="#{$ns}-input" style="width: 180px;" type="text" placeholder="Text input" dir="auto" />
+    <span class="#{$ns}-text-muted">(optional)</span>
+    <input {{:modifier}} class="#{$ns}-input" style="width: 200px;" type="text" placeholder="Text input" dir="auto" />
   </label>
   <label class="#{$ns}-label {{.modifier}}">
     Label B
-    <span class="#{$ns}-text-muted">(optional)</span>
-    <div class="#{$ns}-input-group">
+    <div class="#{$ns}-input-group {{.modifier}}">
       <span class="#{$ns}-icon #{$ns}-icon-calendar"></span>
-      <input class="#{$ns}-input" style="width: 180px;" type="text" placeholder="Input group" dir="auto" />
+      <input {{:modifier}} class="#{$ns}-input" style="width: 200px;" type="text" placeholder="Input group" dir="auto" />
+    </div>
+  </label>
+  <label class="#{$ns}-label {{.modifier}}">
+    Label C
+    <div class="#{$ns}-select {{.modifier}}">
+      <select {{:modifier}}>
+        <option selected>Choose an item...</option>
+        <option value="1">One</option>
+      </select>
     </div>
   </label>
 </div>
 
-.#{$ns}-inline - Inline
+:disabled - Disable the input.
+.#{$ns}-disabled - Disabled styles. Input must be disabled separately via attribute.
+.#{$ns}-inline - Label and content appear side by side.
 
 Styleguide label
 */
 
-// stylelint-disable-next-line selector-no-qualifying-type
 label.#{$ns}-label {
   display: block;
   margin-top: 0;
@@ -49,6 +58,13 @@ label.#{$ns}-label {
     font-weight: 400;
   }
 
+  &.#{$ns}-disabled {
+    &,
+    .#{$ns}-text-muted {
+      color: $pt-text-color-disabled;
+    }
+  }
+
   &.#{$ns}-inline {
     line-height: $pt-input-height;
 
@@ -74,44 +90,6 @@ label.#{$ns}-label {
     display: block;
   }
 
-  /*
-  Disabled labels
-
-  Markup:
-  <div>
-    <label class="#{$ns}-label #{$ns}-disabled">
-      Label A
-      <span class="#{$ns}-text-muted">(optional)</span>
-      <input disabled class="#{$ns}-input" style="width: 200px;" type="text" placeholder="Text input" dir="auto" />
-    </label>
-    <label class="#{$ns}-label #{$ns}-disabled">
-      Label B
-      <div class="#{$ns}-input-group #{$ns}-disabled">
-        <span class="#{$ns}-icon #{$ns}-icon-calendar"></span>
-        <input disabled class="#{$ns}-input" style="width: 200px;" type="text" placeholder="Input group" dir="auto" />
-      </div>
-    </label>
-    <label class="#{$ns}-label #{$ns}-disabled">
-      Label C
-      <div class="#{$ns}-select #{$ns}-disabled">
-        <select disabled>
-          <option selected>Choose an item...</option>
-          <option value="1">One</option>
-        </select>
-      </div>
-    </label>
-  </div>
-
-  Styleguide label-disabled
-  */
-
-  &.#{$ns}-disabled {
-    &,
-    .#{$ns}-text-muted {
-      color: $pt-text-color-disabled;
-    }
-  }
-
   .#{$ns}-dark & {
     color: $pt-dark-heading-color;
 

diff --git a/packages/core/src/components/forms/label.md b/packages/core/src/components/forms/label.md
@@ -2,50 +2,35 @@
 
 Labels enhance the usability of your forms.
 
-<div class="@ns-callout @ns-intent-success @ns-icon-comparison">
-    <h4 class="@ns-heading">Simple labels vs. form groups</h4>
-    <p>Blueprint provides two ways of connecting label text to control fields, depending on the complexity of the control.</p>
-    <p>Simple labels are a basic way to connect a label with a single control.</p>
-    <p>Form groups support more complex control layouts but require more markup to maintain consistent visuals.</p>
+Wrapping a `<label>` element around a form input effectively increases the area
+where the user can click to activate the control. Notice how in the examples
+below, clicking a label focuses its `<input>`.
+
+<div class="@ns-callout @ns-intent-warning @ns-icon-warning-sign">
+    <h4 class="@ns-heading">Prefer form groups over labels</h4>
+    The [React `FormGroup` component](#core/components/form-group) provides
+    additional functionality such as helper text and modifier props as well as
+    full label support. `FormGroup` supports both simple and complex use cases,
+    therefore we recommend using it exclusively when constructing forms.
 </div>
 
 @## CSS API
 
-@### Simple labels
-
 Simple labels are useful for basic forms for a single `<input>`.
 
-- Add extra information to the label with `span.@ns-text-muted`.
-
-- Putting the `<input>` element _inside_ a `<label>` element increases the area where the user
-can click to activate the control. Notice how in the examples below, clicking a `<label>` focuses its `<input>`.
+Apply disabled styles with the `@ns-disabled` class. This styles the label text,
+but does not disable any nested children like inputs or selects. You must add
+the `:disabled` attribute directly to any nested elements to disable them.
+Similarly the respective `@ns-*` form control will need a `.@ns-disabled`
+modifier. See the examples below.
 
 @css label
 
-@### Disabled labels
-
-Add the `.@ns-label` and `.@ns-disabled` class modifiers to a `<label>` to make the label appear
-disabled.
-
-This styles the label text, but does not disable any nested children like inputs or selects. You
-must add the `:disabled` attribute directly to any nested elements to disable them. Similarly the respective
-`@ns-*` form control will need a `.@ns-disabled` modifier. See the examples below.
-
-@css label-disabled
-
 @## JavaScript API
 
-The `Label` component is available in the __@blueprintjs/core__ package. Make sure to review the [getting started docs for installation info](#blueprint/getting-started).
-
-This component is a simple wrapper around the corresponding CSS API. It supports the full range of HTML props.
-
-```tsx
-<Label
-    helperText="Helper text with details..."
-    text="Label A"
->
-    <input className="@ns-input" id="text-input" placeholder="Placeholder text" />
-</Label>
-```
+The `Label` component is available in the __@blueprintjs/core__ package. Make
+sure to review the [getting started docs for installation
+info](#blueprint/getting-started).
 
-@interface ILabelProps
+The `Label` component is a trivial wrapper for the `<label>` HTML element. See
+[HTML elements](#core/components/html) for usage notes.
diff --git a/packages/core/src/components/forms/label.tsx b/packages/core/src/components/forms/label.tsx
diff --git a/packages/core/src/components/html/html.md b/packages/core/src/components/html/html.md
@@ -18,6 +18,7 @@ The following elements should be used in this manner:
 | `H1` - `H6` | `h1` - `h6` | `HEADING` |
 | `Blockquote` | `blockquote` | `BLOCKQUOTE` |
 | `Code` | `code` | `CODE` |
+| `Label` | `label` | `LABEL` - see [Labels](#core/components/label) |
 | `Pre` | `pre` | `CODE_BLOCK` |
 | `OL` | `ol` | `LIST` |
 | `UL` | `ul` | `LIST` |

diff --git a/packages/core/src/components/html/html.tsx b/packages/core/src/components/html/html.tsx
@@ -6,7 +6,7 @@
 
 import classNames from "classnames";
 import * as React from "react";
-import { BLOCKQUOTE, CODE, CODE_BLOCK, HEADING, LIST } from "../../common/classes";
+import { BLOCKQUOTE, CODE, CODE_BLOCK, HEADING, LABEL, LIST } from "../../common/classes";
 
 export interface IElementRefProps<E extends HTMLElement> {
     /** Ref handler to access the instance of the internal HTML element. */
@@ -40,8 +40,9 @@ export const H6 = htmlElement<HTMLHeadingElement>("h6", HEADING);
 export const Blockquote = htmlElement<HTMLElement>("blockquote", BLOCKQUOTE);
 export const Code = htmlElement<HTMLElement>("code", CODE);
 export const Pre = htmlElement<HTMLElement>("pre", CODE_BLOCK);
+export const Label = htmlElement<HTMLLabelElement>("label", LABEL);
 
 // these two are not linted by blueprint-html-components because there are valid
 // uses of these elements without Blueprint styles:
-export const OL = htmlElement<HTMLElement>("ol", LIST);
-export const UL = htmlElement<HTMLElement>("ul", LIST);
+export const OL = htmlElement<HTMLOListElement>("ol", LIST);
+export const UL = htmlElement<HTMLUListElement>("ul", LIST);
diff --git a/packages/core/src/components/index.ts b/packages/core/src/components/index.ts
@@ -31,7 +31,6 @@ export * from "./forms/controls";
 export * from "./forms/fileInput";
 export * from "./forms/formGroup";
 export * from "./forms/inputGroup";
-export * from "./forms/label";
 export * from "./forms/numericInput";
 export * from "./forms/radioGroup";
 export * from "./forms/textArea";

diff --git a/packages/core/test/forms/labelTests.tsx b/packages/core/test/forms/labelTests.tsx
diff --git a/packages/core/test/index.ts b/packages/core/test/index.ts
@@ -24,7 +24,6 @@ import "./dialog/dialogTests";
 import "./editable-text/editableTextTests";
 import "./forms/fileInputTests";
 import "./forms/formGroupTests";
-import "./forms/labelTests";
 import "./hotkeys/hotkeysTests";
 import "./icon/iconTests";
 import "./menu/menuItemTests";

diff --git a/packages/docs-app/src/examples/core-examples/cardExample.tsx b/packages/docs-app/src/examples/core-examples/cardExample.tsx
@@ -25,7 +25,8 @@ export class CardExample extends React.PureComponent<IExampleProps, ICardExample
             <>
                 <H5>Props</H5>
                 <Switch checked={this.state.interactive} label="Interactive" onChange={this.handleInteractiveChange} />
-                <Label text="Elevation">
+                <Label>
+                    Elevation
                     <Slider
                         max={4}
                         showTrackFill={false}

diff --git a/packages/docs-app/src/examples/core-examples/checkboxExample.tsx b/packages/docs-app/src/examples/core-examples/checkboxExample.tsx
@@ -14,7 +14,7 @@ export class CheckboxExample extends React.PureComponent<IExampleProps> {
         return (
             <Example options={false} {...this.props}>
                 <div>
-                    <Label text="Assign responsibility" />
+                    <Label>Assign responsibility</Label>
                     <Checkbox label="Gilad Gray" defaultIndeterminate={true} />
                     <Checkbox label="Jason Killian" />
                     <Checkbox label="Antoine Llorca" />

diff --git a/packages/docs-app/src/examples/core-examples/collapsibleListExample.tsx b/packages/docs-app/src/examples/core-examples/collapsibleListExample.tsx
@@ -42,7 +42,7 @@ export class CollapsibleListExample extends React.PureComponent<IExampleProps, I
         const options = (
             <>
                 <H5>Props</H5>
-                <Label text="Visible items" />
+                <Label>Visible items</Label>
                 <Slider
                     max={6}
                     onChange={this.handleChangeCount}

diff --git a/packages/docs-app/src/examples/core-examples/common/intentSelect.tsx b/packages/docs-app/src/examples/core-examples/common/intentSelect.tsx
@@ -22,7 +22,8 @@ export interface IIntentSelectProps {
 }
 
 export const IntentSelect: React.SFC<IIntentSelectProps> = props => (
-    <Label text="Intent">
+    <Label>
+        Intent
         <div className={Classes.SELECT}>
             <select value={props.intent} onChange={props.onChange}>
                 {INTENTS.map((opt, i) => (

diff --git a/packages/docs-app/src/examples/core-examples/iconExample.tsx b/packages/docs-app/src/examples/core-examples/iconExample.tsx
@@ -33,7 +33,7 @@ export class IconExample extends React.PureComponent<IExampleProps, IIconExample
                 <H5>Props</H5>
                 <IconSelect iconName={icon} onChange={this.handleIconNameChange} />
                 <IntentSelect intent={this.state.intent} onChange={this.handleIntentChange} />
-                <Label text="Icon size" />
+                <Label>Icon size</Label>
                 <Slider
                     labelStepSize={MAX_ICON_SIZE / 5}
                     min={0}

diff --git a/packages/docs-app/src/examples/core-examples/numericInputBasicExample.tsx b/packages/docs-app/src/examples/core-examples/numericInputBasicExample.tsx
@@ -149,7 +149,7 @@ export class NumericInputBasicExample extends React.PureComponent<IExampleProps,
 
         return (
             <>
-                <Label text="Modifiers" />
+                <Label>Modifiers</Label>
                 {this.renderSwitch("Numeric characters only", numericCharsOnly, this.toggleNumericCharsOnly)}
                 {this.renderSwitch("Select all on focus", selectAllOnFocus, this.toggleSelectAllOnFocus)}
                 {this.renderSwitch("Select all on increment", selectAllOnIncrement, this.toggleSelectAllOnIncrement)}
@@ -182,7 +182,8 @@ export class NumericInputBasicExample extends React.PureComponent<IExampleProps,
         onChange: React.FormEventHandler<HTMLElement>,
     ) {
         return (
-            <Label text={label}>
+            <Label>
+                {label}
                 <div className={Classes.SELECT}>
                     <select value={selectedValue} onChange={onChange}>
                         {this.renderSelectMenuOptions(options)}

diff --git a/packages/docs-app/src/examples/core-examples/overflowListExample.tsx b/packages/docs-app/src/examples/core-examples/overflowListExample.tsx
@@ -65,7 +65,7 @@ export class OverflowListExample extends React.PureComponent<IExampleProps, IOve
                     selectedValue={this.state.collapseFrom.toString()}
                 />
                 <H5>Example</H5>
-                <Label text="Width" />
+                <Label>Width</Label>
                 <Slider
                     labelRenderer={this.renderLabel}
                     labelStepSize={50}

diff --git a/packages/docs-app/src/examples/core-examples/popoverExample.tsx b/packages/docs-app/src/examples/core-examples/popoverExample.tsx
@@ -163,7 +163,8 @@ export class PopoverExample extends React.PureComponent<IExampleProps, IPopoverE
                         </select>
                     </div>
                 </FormGroup>
-                <Label text="Example content">
+                <Label>
+                    Example content
                     <div className={Classes.SELECT}>
                         <select value={this.state.exampleIndex} onChange={this.handleExampleIndexChange}>
                             <option value="0">Text</option>
@@ -214,7 +215,7 @@ export class PopoverExample extends React.PureComponent<IExampleProps, IPopoverE
                         </select>
                     </div>
                 </Switch>
-                <Label text={undefined}>
+                <Label>
                     <AnchorButton
                         href={POPPER_DOCS}
                         fill={true}