docs(modal): document data-modal-primary-focus (#1112)

Also bring back demo of modal with text input. Fixes #1110.
carbon-design-system · Sep 18, 2018 · 78ee39a · 78ee39a
1 parent d8c5398
commit 78ee39a
Show file tree

Hide file tree

Showing 4 changed files with 63 additions and 21 deletions.
diff --git a/src/components/modal/README.md b/src/components/modal/README.md
@@ -4,8 +4,8 @@
 
 Use these modifiers with `.bx--modal` class.
 
-| Name                    | Description                                           |
-|-------------------------|-------------------------------------------------------|
+| Name               | Description                               |
+| ------------------ | ----------------------------------------- |
 | .bx--modal--danger | Selector for applying danger modal styles |
 
 ### JavaScript
@@ -41,11 +41,11 @@ Modal.create(document.getElementById('my-modal'));
 
 #### Public Methods
 
-| Name              | Params           | Description          |
-|-------------------|------------------|----------------------|
-| release           |                  | Deletes the instance |
-| show              |                  | Show the modal       |
-| hide              |                  | Hide the modal       |
+| Name    | Params | Description          |
+| ------- | ------ | -------------------- |
+| release |        | Deletes the instance |
+| show    |        | Show the modal       |
+| hide    |        | Hide the modal       |
 
 ##### Example - Showing modal
 
@@ -57,18 +57,38 @@ modalInstance.show();
 
 #### Options
 
-| Option             | Default Selector     | Description                                                                                                                           |
-|--------------------|----------------------|---------------------------------------------------------------------------------------------------------------------------------------|
-| selectorInit       | '[data-modal]'       | The css selector for root modal component                                                                                             |
-| selectorModalClose | '[data-modal-close]' | The selector to find elements that close the modal                                                                                    |
-| classVisible       | 'is-visible'         | Class to toggle visibility of modal                                                                                                   |
-| attribInitTarget   | 'data-modal-target'  | The attribute on the launching element to target the modal                                                                            |
-| initEventNames     | '['click']'          | On specified events, if event matches the attribInitTarget, then initialize the component and run createdByLauncher if method exists  |
+| Option               | Default Selector             | Description                                                                                                                          |
+| -------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| selectorInit         | '[data-modal]'               | The css selector for root modal component                                                                                            |
+| selectorModalClose   | '[data-modal-close]'         | The selector to find elements that close the modal                                                                                   |
+| selectorPrimaryFocus | '[data-modal-primary-focus]' | The CSS selector to determine the element to put focus when modal gets open                                                          |
+| classVisible         | 'is-visible'                 | Class to toggle visibility of modal                                                                                                  |
+| attribInitTarget     | 'data-modal-target'          | The attribute on the launching element to target the modal                                                                           |
+| initEventNames       | '['click']'                  | On specified events, if event matches the attribInitTarget, then initialize the component and run createdByLauncher if method exists |
+
+##### Example - Putting focus on text box when modal gets open
+
+```html
+<div data-modal id="my-modal" class="bx--modal " role="dialog" aria-modal="true" aria-labelledby="my-modal-label" aria-describedby="my-modal-heading" tabindex="-1">
+  <div class="bx--modal-container">
+    <div class="bx--modal-header">
+      <p class="bx--modal-header__heading bx--type-beta" id="my-modal-heading">Modal heading</p>
+      <button class="bx--modal-close" type="button" data-modal-close aria-label="close modal" >
+        (The close button image)
+      </button>
+    </div>
+    <div class="bx--modal-content">
+      <label for="my-text-input" class="bx--label">Text Input label</label>
+      <input id="my-text-input" type="text" class="bx--text-input" placeholder="Optional placeholder text" data-modal-primary-focus>
+    </div>
+  </div>
+</div>
+```
 
 #### Events
 
 | Event Option      | Event Name          |
-|-------------------|---------------------|
+| ----------------- | ------------------- |
 | eventBeforeShown  | 'modal-beingshown'  |
 | eventAfterShown   | 'modal-shown'       |
 | eventBeforeHidden | 'modal-beinghidden' |
@@ -77,7 +97,7 @@ modalInstance.show();
 ##### Example - Preventing modals from being closed in a certain condition
 
 ```javascript
-document.addEventListener('modal-beinghidden', function (evt) {
+document.addEventListener('modal-beinghidden', function(evt) {
   if (myApplication.shouldModalKeptOpen(evt.target)) {
     evt.preventDefault();
   }
@@ -87,7 +107,7 @@ document.addEventListener('modal-beinghidden', function (evt) {
 ##### Example - Notifying events of all modals being closed to an analytics library
 
 ```javascript
-document.addEventListener('modal-hidden', function (evt) {
+document.addEventListener('modal-hidden', function(evt) {
   myAnalyticsLibrary.send({
     action: 'Modal hidden',
     id: evt.target.id,

diff --git a/src/components/modal/modal.config.js b/src/components/modal/modal.config.js
@@ -44,5 +44,18 @@ module.exports = {
         classCloseButton: 'bx--btn--tertiary',
       },
     },
+    {
+      name: 'input',
+      label: 'Input Modal',
+      context: {
+        idSuffix: Math.random()
+          .toString(36)
+          .substr(2),
+        hasInput: true,
+        hasFooter: true,
+        classPrimaryButton: 'bx--btn--primary',
+        classCloseButton: 'bx--btn--secondary',
+      },
+    },
   ],
 };
diff --git a/src/components/modal/modal.hbs b/src/components/modal/modal.hbs
@@ -15,16 +15,23 @@
     </div>
 
     <div class="bx--modal-content">
-      <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id accumsan augue. Phasellus consequat augue vitae
-        tellus tincidunt posuere. Curabitur justo urna, consectetur vel elit iaculis, ultrices condimentum risus. Nulla facilisi.
-        Etiam venenatis molestie tellus. Quisque consectetur non risus eu rutrum. </p>
+      {{#if hasInput}}
+        <div class="bx--form-item">
+          <label for="text-input-{{idSuffix}}" class="bx--label">Text Input label</label>
+          <input id="text-input-{{idSuffix}}" type="text" class="bx--text-input" placeholder="Optional placeholder text" data-modal-primary-focus>
+        </div>
+      {{else}}
+        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Aenean id accumsan augue. Phasellus consequat augue vitae
+          tellus tincidunt posuere. Curabitur justo urna, consectetur vel elit iaculis, ultrices condimentum risus. Nulla facilisi.
+          Etiam venenatis molestie tellus. Quisque consectetur non risus eu rutrum. </p>
+      {{/if}}
     </div>
 
     {{#if hasFooter}}
     <div class="bx--modal-footer">
       <button class="bx--btn {{classCloseButton}}" type="button" data-modal-close>Secondary button</button>
       <button class="bx--btn {{classPrimaryButton}}" type="button" {{#if labelPrimaryButton}}aria-label="{{labelPrimaryButton}}"
-        {{/if}} data-modal-primary-focus>Primary button</button>
+        {{/if}}{{#unless hasInput}} data-modal-primary-focus{{/unless}}>Primary button</button>
     </div>
     {{/if}}
   </div>

diff --git a/src/components/modal/modal.js b/src/components/modal/modal.js
@@ -166,6 +166,8 @@ class Modal extends mixin(createComponent, initComponentByLauncher, eventedShowH
    * @member Modal.options
    * @type {Object}
    * @property {string} selectorInit The CSS class to find modal dialogs.
+   * @property {string} [selectorModalClose] The selector to find elements that close the modal.
+   * @property {string} [selectorPrimaryFocus] The CSS selector to determine the element to put focus when modal gets open.
    * @property {string} attribInitTarget The attribute name in the launcher buttons to find target modal dialogs.
    * @property {string[]} [selectorsFloatingMenu]
    *   The CSS selectors of floating menus.