From d5aaf1dbc543079eb1955dae46938aadef09d459 Mon Sep 17 00:00:00 2001 From: TJ Egan <tw15egan@gmail.com> Date: Fri, 7 Feb 2020 13:27:36 -0800 Subject: [PATCH] docs(readme): remove readmes, old migratiion docs (#5277) --- .../src/components/accordion/README.md | 32 --- .../components/accordion/migrate-to-7.x.md | 49 ---- .../src/components/breadcrumb/README.md | 40 --- .../components/breadcrumb/migrate-to-7.x.md | 22 -- .../src/components/button/README.md | 57 ---- .../src/components/button/migrate-to-7.x.md | 35 --- .../src/components/checkbox/README.md | 71 ----- .../src/components/checkbox/migrate-to-7.x.md | 26 -- .../src/components/code-snippet/README.md | 21 -- .../components/code-snippet/migrate-to-7.x.md | 23 -- .../components/code-snippet/migrate-to-9.x.md | 18 -- .../src/components/combo-box/README.md | 9 - .../src/components/content-switcher/README.md | 243 ------------------ .../content-switcher/migrate-to-7.x.md | 42 --- .../src/components/data-table/README.md | 139 ---------- .../src/components/date-picker/README.md | 107 -------- .../src/components/dropdown/README.md | 92 ------- .../src/components/dropdown/migrate-to-7.x.md | 34 --- .../src/components/file-uploader/README.md | 152 ----------- .../file-uploader/migrate-to-7.x.md | 46 ---- .../src/components/floating-menu/README.md | 32 --- .../components/src/components/form/README.md | 146 ----------- .../src/components/form/migrate-to-7.x.md | 47 ---- .../src/components/inline-loading/README.md | 56 ---- .../src/components/link/migrate-to-7.x.md | 25 -- .../src/components/list-box/README.md | 23 -- .../components/src/components/list/README.md | 11 - .../src/components/list/migrate-to-7.x.md | 21 -- .../src/components/loading/README.md | 68 ----- .../src/components/loading/migrate-to-7.x.md | 34 --- .../components/src/components/modal/README.md | 165 ------------ .../src/components/modal/migrate-to-7.x.md | 65 ----- .../src/components/multi-select/README.md | 58 ----- .../src/components/notification/README.md | 127 --------- .../components/notification/migrate-to-7.x.md | 65 ----- .../src/components/number-input/README.md | 14 - .../components/number-input/migrate-to-7.x.md | 43 ---- .../src/components/overflow-menu/README.md | 122 --------- .../overflow-menu/migrate-to-7.x.md | 45 ---- .../src/components/pagination-nav/README.md | 30 --- .../src/components/pagination/README.md | 31 --- .../components/pagination/migrate-to-7.x.md | 29 --- .../components/progress-indicator/README.md | 105 -------- .../progress-indicator/experimental.md | 139 ---------- .../progress-indicator/migrate-to-7.x.md | 46 ---- .../src/components/radio-button/README.md | 8 - .../components/radio-button/migrate-to-7.x.md | 19 -- .../components/src/components/search/FAQ.md | 24 -- .../src/components/search/README.md | 34 --- .../src/components/search/migrate-to-7.x.md | 39 --- .../src/components/select/README.md | 50 ---- .../src/components/select/migrate-to-7.x.md | 28 -- .../src/components/slider/README.md | 36 --- .../src/components/structured-list/README.md | 94 ------- .../components/src/components/tabs/README.md | 96 ------- .../src/components/tabs/migrate-to-7.x.md | 27 -- .../components/src/components/tag/README.md | 9 - .../src/components/tag/migrate-to-7.x.md | 34 --- .../src/components/text-area/README.md | 6 - .../components/text-area/migrate-to-7.x.md | 26 -- .../src/components/text-input/README.md | 33 --- .../components/text-input/migrate-to-7.x.md | 40 --- .../components/src/components/tile/README.md | 63 ----- .../src/components/time-picker/README.md | 26 -- .../src/components/toggle/README.md | 21 -- .../src/components/toggle/migrate-to-7.x.md | 23 -- .../src/components/toolbar/README.md | 33 --- .../src/components/tooltip/README.md | 182 ------------- .../src/components/tooltip/migrate-to-9.x.md | 28 -- .../src/components/ui-shell/README.md | 96 ------- 70 files changed, 3880 deletions(-) delete mode 100644 packages/components/src/components/accordion/README.md delete mode 100644 packages/components/src/components/accordion/migrate-to-7.x.md delete mode 100644 packages/components/src/components/breadcrumb/README.md delete mode 100644 packages/components/src/components/breadcrumb/migrate-to-7.x.md delete mode 100644 packages/components/src/components/button/README.md delete mode 100644 packages/components/src/components/button/migrate-to-7.x.md delete mode 100644 packages/components/src/components/checkbox/README.md delete mode 100644 packages/components/src/components/checkbox/migrate-to-7.x.md delete mode 100644 packages/components/src/components/code-snippet/README.md delete mode 100644 packages/components/src/components/code-snippet/migrate-to-7.x.md delete mode 100644 packages/components/src/components/code-snippet/migrate-to-9.x.md delete mode 100644 packages/components/src/components/combo-box/README.md delete mode 100644 packages/components/src/components/content-switcher/README.md delete mode 100644 packages/components/src/components/content-switcher/migrate-to-7.x.md delete mode 100644 packages/components/src/components/data-table/README.md delete mode 100644 packages/components/src/components/date-picker/README.md delete mode 100644 packages/components/src/components/dropdown/README.md delete mode 100644 packages/components/src/components/dropdown/migrate-to-7.x.md delete mode 100644 packages/components/src/components/file-uploader/README.md delete mode 100644 packages/components/src/components/file-uploader/migrate-to-7.x.md delete mode 100644 packages/components/src/components/floating-menu/README.md delete mode 100644 packages/components/src/components/form/README.md delete mode 100644 packages/components/src/components/form/migrate-to-7.x.md delete mode 100644 packages/components/src/components/inline-loading/README.md delete mode 100644 packages/components/src/components/link/migrate-to-7.x.md delete mode 100644 packages/components/src/components/list-box/README.md delete mode 100644 packages/components/src/components/list/README.md delete mode 100644 packages/components/src/components/list/migrate-to-7.x.md delete mode 100644 packages/components/src/components/loading/README.md delete mode 100644 packages/components/src/components/loading/migrate-to-7.x.md delete mode 100644 packages/components/src/components/modal/README.md delete mode 100644 packages/components/src/components/modal/migrate-to-7.x.md delete mode 100644 packages/components/src/components/multi-select/README.md delete mode 100644 packages/components/src/components/notification/README.md delete mode 100644 packages/components/src/components/notification/migrate-to-7.x.md delete mode 100644 packages/components/src/components/number-input/README.md delete mode 100644 packages/components/src/components/number-input/migrate-to-7.x.md delete mode 100644 packages/components/src/components/overflow-menu/README.md delete mode 100644 packages/components/src/components/overflow-menu/migrate-to-7.x.md delete mode 100644 packages/components/src/components/pagination-nav/README.md delete mode 100644 packages/components/src/components/pagination/README.md delete mode 100644 packages/components/src/components/pagination/migrate-to-7.x.md delete mode 100644 packages/components/src/components/progress-indicator/README.md delete mode 100644 packages/components/src/components/progress-indicator/experimental.md delete mode 100644 packages/components/src/components/progress-indicator/migrate-to-7.x.md delete mode 100644 packages/components/src/components/radio-button/README.md delete mode 100644 packages/components/src/components/radio-button/migrate-to-7.x.md delete mode 100644 packages/components/src/components/search/FAQ.md delete mode 100644 packages/components/src/components/search/README.md delete mode 100644 packages/components/src/components/search/migrate-to-7.x.md delete mode 100644 packages/components/src/components/select/README.md delete mode 100644 packages/components/src/components/select/migrate-to-7.x.md delete mode 100644 packages/components/src/components/slider/README.md delete mode 100644 packages/components/src/components/structured-list/README.md delete mode 100644 packages/components/src/components/tabs/README.md delete mode 100644 packages/components/src/components/tabs/migrate-to-7.x.md delete mode 100644 packages/components/src/components/tag/README.md delete mode 100644 packages/components/src/components/tag/migrate-to-7.x.md delete mode 100644 packages/components/src/components/text-area/README.md delete mode 100644 packages/components/src/components/text-area/migrate-to-7.x.md delete mode 100644 packages/components/src/components/text-input/README.md delete mode 100644 packages/components/src/components/text-input/migrate-to-7.x.md delete mode 100644 packages/components/src/components/tile/README.md delete mode 100644 packages/components/src/components/time-picker/README.md delete mode 100644 packages/components/src/components/toggle/README.md delete mode 100644 packages/components/src/components/toggle/migrate-to-7.x.md delete mode 100644 packages/components/src/components/toolbar/README.md delete mode 100644 packages/components/src/components/tooltip/README.md delete mode 100644 packages/components/src/components/tooltip/migrate-to-9.x.md delete mode 100644 packages/components/src/components/ui-shell/README.md diff --git a/packages/components/src/components/accordion/README.md b/packages/components/src/components/accordion/README.md deleted file mode 100644 index 8c215c12a244..000000000000 --- a/packages/components/src/components/accordion/README.md +++ /dev/null @@ -1,32 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--accordion` class. - -| Default Selector | Description | -| ------------------------------ | ------------------------------------------ | -| `.bx--accordion__item--active` | The className for an active accordion item | - -### JavaScript - -#### Public Methods - -| Name | Params | Description | -| --------- | ------ | -------------------- | -| `release` | | Deletes the instance | - -#### Options - -| Option | Default Selector | Description | -| -------------------------- | ----------------------------- | ------------------------------------------------- | -| `selectorInit` | `[data-accordion]` | The selector to find the accordion | -| `selectorAccordionItem` | `[data-accordion-item]` | The selector to find the accordion item component | -| `selectorAccordionContent` | `.bx--accordion__content` | The selector for the accordion content element | -| `classActive` | `bx--accordion__item--active` | The className for an active accordion item | - -#### Classes - -| Name | Description | -| ----------------------------- | ------------------------------------------ | -| `bx--accordion__item--active` | The className for an active accordion item | diff --git a/packages/components/src/components/accordion/migrate-to-7.x.md b/packages/components/src/components/accordion/migrate-to-7.x.md deleted file mode 100644 index df8e5d4f5ba4..000000000000 --- a/packages/components/src/components/accordion/migrate-to-7.x.md +++ /dev/null @@ -1,49 +0,0 @@ -### HTML - -Updating HTML pertains mainly to SVG icon paths. It's now recommended to use -inline SVG icons. - -```html -<svg - class="bx--accordion__arrow" - width="8" - height="12" - viewBox="0 0 8 12" - fill-rule="evenodd" -> - <path d="M0 10.6L4.7 6 0 1.4 1.4 0l6.1 6-6.1 6z"></path> -</svg> -``` - -But if you're going to make use of carbon-icons.svg, it's recommended to use the -sprite svg file locally in your project. - -Update `<use xlink:href>` to a local path of bluemix-icons.svg, which should -look something like this: - -```html -<svg class="bx--accordion__arrow"> - <use xlink:href="/carbon-icons/bluemix-icons.svg#chevron--right"></use> -</svg> -``` - -For more details on installing and using bluemix-icons, see install and usage -guidelines docs here. - -### SCSS - -The `_accordion.scss` file is now located at -`src/components/accordion/_accordion.scss`. You'll need to update any `@import` -statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/accordion/accordion'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/accordion/accordion'; -``` diff --git a/packages/components/src/components/breadcrumb/README.md b/packages/components/src/components/breadcrumb/README.md deleted file mode 100644 index 26c518c5e1b3..000000000000 --- a/packages/components/src/components/breadcrumb/README.md +++ /dev/null @@ -1,40 +0,0 @@ -### SCSS - -| Selector | Description | -| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -| `bx--breadcrumb` | Used on the containing `<nav>` or equivalent node | -| `bx--breadcrumb-item` | Used on each individual breadcrumb item | -| `bx--breadcrumb-item--current` | Used to specify which breadcrumb item is the current page | -| `bx--breadcrumb-item [aria-current='page']` | Alternative to `bx--breadcrumb-item--current`, automatically applied if a descending `<a>` tag uses `aria-current` | -| `bx--breadcrumb--no-trailing-slash` | Used to specify that no trailing slash should be added | - -### FAQ - -#### How to remove a breadcrumb-item slash - -Use CSS to override breadcrumb styles to hide any unwanted slashes. Slashes are -created using CSS pseudo elements (`::after`). Setting this to `display: none` -will remove the associated slash. - -```scss -/* Removes the slash from the last breadcrumb-item */ -.bx--breadcrumb-item:last-child::after { - display: none; -} -``` - -Or you can add `.bx--breadcrumb--no-trailing-slash` to `.bx--breadcrumb` to -remove leading slashes. - -```html -/* Removes the slash from the last breadcrumb-item */ -<div class="bx--breadcrumb bx--breadcrumb--no-trailing-slash"> - <div class="bx--breadcrumb-item"> - <a href="#" class="bx--link">Breadcrumb 1</a> - </div> - <div class="bx--breadcrumb-item"> - <a href="#" class="bx--link">Breadcrumb 2</a> - </div> - <div class="bx--breadcrumb-item"><span>Breadcrumb 3</span></div> -</div> -``` diff --git a/packages/components/src/components/breadcrumb/migrate-to-7.x.md b/packages/components/src/components/breadcrumb/migrate-to-7.x.md deleted file mode 100644 index 21e001b81d44..000000000000 --- a/packages/components/src/components/breadcrumb/migrate-to-7.x.md +++ /dev/null @@ -1,22 +0,0 @@ -### HTML - -The `bx--breadcrumb--lg` modifier class has been removed in `7.x` and is no -longer in use. - -### SCSS - -The `_breadcrumb.scss` file is now located at -`src/components/breadcrumb/_breadcrumb.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/breadcrumb/breadcrumb'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/breadcrumb/breadcrumb'; -``` diff --git a/packages/components/src/components/button/README.md b/packages/components/src/components/button/README.md deleted file mode 100644 index 07ab0aba7e59..000000000000 --- a/packages/components/src/components/button/README.md +++ /dev/null @@ -1,57 +0,0 @@ -### SCSS - -#### Mixins - -Mixins specific to button are located in -[src/components/button/\_mixins.scss](). - -| Name | Params | Description | -| -------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | -| `button-base` | | Base styles used in every button. Used in `@mixin button-theme` by default | -| `button-theme` | `bg-color`, `border-color`, `font-color`, `hover-bg-color`, `icon-color` | Used to create variant styles for a button (Variations like, primary, secondary, etc.) | - -#### Modifiers - -Use these modifiers with `.bx--btn` class. - -| Selector | Description | -| --------------------- | --------------------------------------------- | -| `.bx--btn--primary` | Selector for applying primary button styles | -| `.bx--btn--secondary` | Selector for applying secondary button styles | -| `.bx--btn--tertiary` | Selector for applying tertiary button styles | -| `.bx--btn--danger` | Selector for applying danger button styles | -| `.bx--btn--sm` | Selector for applying small button styles | -| `.bx--btn—ghost` | Selector for applying ghost button styles | -| `.bx--btn--icon-only` | Selector for applying icon button styles | - -### FAQ - -#### Using icons with buttons - -All buttons can use icons. It's recommended to inline SVG icons when possible. -Simply add the appropriate `<svg>` to the button HTML with the `bx--btn__icon` -class. You can also include `<title>` for better accessibility to describe what -the button does. - -```html -<button class="bx--btn bx--btn--secondary" type="button"> - Secondary - <svg - class="bx--btn__icon" - width="16" - height="16" - viewBox="0 0 16 16" - fill-rule="evenodd" - > - <title>add a new connection to your instance</title> - <path - d="M8 0C3.6 0 0 3.6 0 8s3.6 8 8 8 8-3.6 8-8-3.6-8-8-8zm4 9H9v3H7V9H4V7h3V4h2v3h3v2z" - ></path> - </svg> -</button> -``` - -### Icon-only buttons - -When using the icon-only button variant, tooltip styles must also be imported -for the component to display properly. diff --git a/packages/components/src/components/button/migrate-to-7.x.md b/packages/components/src/components/button/migrate-to-7.x.md deleted file mode 100644 index 4c66c940aab9..000000000000 --- a/packages/components/src/components/button/migrate-to-7.x.md +++ /dev/null @@ -1,35 +0,0 @@ -### SCSS - -The `_button.scss` file is now located at `src/components/button/_button.scss`. -You will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/button/button'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/button/button'; -``` - -The `.bx--sets-of-buttons` class has been removed and is no longer in use. -Secondary and Primary buttons are meant to be paired together in that order -according to UX guidelines. When paired as siblings, Primary buttons will have a -`margin-left: 1rem` or `16px`. - -The `.bx--btn--right-icon__icon` class has been replaced by `.bx--btn__icon`. - -SCSS Extends for buttons have been removed and are no longer in use. SCSS -Variables specific to Button have been removed and are no longer in use. - -SCSS Mixins have been reduced. The following mixins have been removed: - -- @mixin btn--browser-fixes (CSS browser fixes applied directly to element and - class selectors) -- @mixin btn--primary (replaced by @mixin button-theme) -- @mixin btn--secondary (replaced by @mixin button-theme) -- @mixin btn--danger (replaced by @mixin button-theme) diff --git a/packages/components/src/components/checkbox/README.md b/packages/components/src/components/checkbox/README.md deleted file mode 100644 index 6fa69a252d43..000000000000 --- a/packages/components/src/components/checkbox/README.md +++ /dev/null @@ -1,71 +0,0 @@ -### Javascript - -#### Public Methods - -| Name | Params | Description | -| ------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------- | -| `setState` | `state`: `String` ['true', 'false', 'mixed'] | Can be used to set the checkbox to `true`(checked), `false`(unchecked) or `mixed` (indeterminate) | -| `setDisabled` | `state`: `Boolean` | Can be used to set the checkbox to disabled, needed for the `label > input` | - -#### Options - -| Option | Default Selector | Description | -| ----------------------------------- | ------------------------------------ | -------------------------------------------------------------------------- | -| `selectorInit` | `.bx--checkbox` | The CSS selector to find checkbox | -| `selectorContainedCheckboxState` | `[data-contained-checkbox-state]` | The CSS selector to find a container of checkbox preserving checked state | -| `selectorContainedCheckboxDisabled` | `[data-contained-checkbox-disabled]` | The CSS selector to find a container of checkbox preserving disabled state | -| `classLabel` | `.bx--checkbox-label` | The CSS class for the label | -| `classLabelFocused` | `.bx--checkbox-label__focus` | The CSS class for the focused label | -| `attribContainedCheckboxState` | `data-contained-checkbox-state` | The attribute name for the checked state of contained checkbox | -| `attribContainedCheckboxDisabled` | `data-contained-checkbox-disabled` | The attribute name for the disabled state of contained checkbox | - -### FAQ - -#### Two ways to write checkbox HTML - -Checkbox HTML can be written in two ways: - -With `input` and `label` as siblings - -```html -<div class="bx--form-item"> - <input - id="bx--checkbox" - class="bx--checkbox" - type="checkbox" - value="green" - name="checkbox" - /> - <label for="bx--checkbox" class="bx--checkbox-label"> - Checkbox (input + label) - </label> -</div> -``` - -With `label` wrapping `input` - -```html -<div class="bx--form-item"> - <label class="bx--checkbox-label"> - <input - class="bx--checkbox" - type="checkbox" - value="yellow" - name="checkbox" - /> - Checkbox (label > input) - </label> -</div> -``` - -Note: You no longer need to include a SVG for the checkmark to render. - -#### Fieldset and Legend - -As a best practice, groups of checkboxes should make use of `<fieldset>` and -`<legend>` (see Form for details). This is especially true for forms submitting -data. - -But, there are exceptions to the rule. For example, Data Tables make use of -checkboxes as a way to select rows of data. Checkboxes in this context would -represent an entire row of data in its associated table row. diff --git a/packages/components/src/components/checkbox/migrate-to-7.x.md b/packages/components/src/components/checkbox/migrate-to-7.x.md deleted file mode 100644 index a093371554fc..000000000000 --- a/packages/components/src/components/checkbox/migrate-to-7.x.md +++ /dev/null @@ -1,26 +0,0 @@ -### HTML - -Checkbox HTML that does not use SVG is no longer supported and has been removed. -All checkboxes must use SVG icons to ensure browser compatibility. - -### SCSS - -The `_checkbox.scss` file is now located in -`src/components/checkbox/_checkbox.scss`. You'll need to update any `@import` -statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/checkbox/checkbox'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/checkbox/checkbox'; -``` - -Almost all checkbox classes have been changed to use less BEM underscore syntax. -To use the newest checkbox styles, it will be best to copy and paste the latest -checkbox HTML provided by the design-system. diff --git a/packages/components/src/components/code-snippet/README.md b/packages/components/src/components/code-snippet/README.md deleted file mode 100644 index 2d0d1fd119cf..000000000000 --- a/packages/components/src/components/code-snippet/README.md +++ /dev/null @@ -1,21 +0,0 @@ -### SCSS - -#### Mixins - -Mixins specific to Code Snippet are located in -[src/components/code-snippet/\_mixins.scss](). - -| Name | Params | Description | -| ------------- | ------ | ------------------------- | -| `bx--snippet` | | Common styles for Snippet | - -#### Modifiers - -Use these modifiers with `.bx--snippet` class. - -| Selector | Description | -| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `.bx--snippet--single` | Selector for single lines of code | -| `.bx--snippet--multi` | Selector for multiple lines of code | -| `.bx--snippet--inline` | Selector for inline code inside text | -| `.bx--snippet--light` | Selector for inline code inside text with a light background. Can only be used with .bx--snippet-inline selector | diff --git a/packages/components/src/components/code-snippet/migrate-to-7.x.md b/packages/components/src/components/code-snippet/migrate-to-7.x.md deleted file mode 100644 index 3b17e9c54c39..000000000000 --- a/packages/components/src/components/code-snippet/migrate-to-7.x.md +++ /dev/null @@ -1,23 +0,0 @@ -### HTML - -No changes. - -### SCSS - -The `_code-snippet.scss` file is now located at -`src/components/code-snippet/_code-snippet.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/code-snippet/code-snippet'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/code-snippet/code-snippet'; -``` - -No changes to classes made. diff --git a/packages/components/src/components/code-snippet/migrate-to-9.x.md b/packages/components/src/components/code-snippet/migrate-to-9.x.md deleted file mode 100644 index 7d9594a88b81..000000000000 --- a/packages/components/src/components/code-snippet/migrate-to-9.x.md +++ /dev/null @@ -1,18 +0,0 @@ -### HTML - -Terminal snippet has been renamed to Single line snippet, Code snippet has been -renamed to Multi-line snippet. We have also added a new variation, Inline -snippet. - -### SCSS - -| Old Class | New Class | Note | -| ----------------------- | --------------------- | ------- | -| `bx--snippet--terminal` | `bx--snippet--single` | Changed | -| `bx--snippet--code` | `bx--snippet--multi` | Changed | -| | `bx--snippet--inline` | New | - -### Javascript - -The multi-line code snippet now has javascript. Be sure to add the data -attribute `[data-code-snippet]` for it to work. diff --git a/packages/components/src/components/combo-box/README.md b/packages/components/src/components/combo-box/README.md deleted file mode 100644 index 4d1873a703eb..000000000000 --- a/packages/components/src/components/combo-box/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# `combo-box` - -### SCSS - -#### Classes - -| Name | Description | -| :--------------- | :--------------------------------------------------- | -| `.bx--combo-box` | Used on a container node to specify its control type | diff --git a/packages/components/src/components/content-switcher/README.md b/packages/components/src/components/content-switcher/README.md deleted file mode 100644 index 8add452d8b7c..000000000000 --- a/packages/components/src/components/content-switcher/README.md +++ /dev/null @@ -1,243 +0,0 @@ -### SCSS - -#### Modifiers - -| Name | Description | -| --------------------------------- | ------------------------------------------------------------ | -| `.bx--content-switcher--selected` | Applies the "selected" styles to the content-switcher button | - -### Javascript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { ContentSwitcher } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var ContentSwitcher = CarbonComponents.ContentSwitcher; -``` - -#### Instantiating - -```javascript -// `#my-content-switcher` is an element with `[data-content-switcher]` attribute -ContentSwitcher.create(document.getElementById('my-content-switcher')); -``` - -#### Public Methods - -| Name | Params | Description | -| ----------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `setActive` | `item`: `HTMLElement`, `callback`: `Function` | Uses `data-target` attribute to show a content panel using the given CSS selector. Non-active targets will be hidden. You can also pass in an optional callback function, see FAQ for details | -| `release` | | Deletes the instance and removes document event listeners | - -##### Example - Changing the active item - -```javascript -// `#my-content-switcher` is an element with `[data-content-switcher]` attribute -var contentSwitcherInstance = ContentSwitcher.create( - document.getElementById('my-content-switcher') -); -// `#my-content-switcher-btn-1` is one of the `<button>`s with `bx--content-switcher-btn` class -contentSwitcherInstance.setActive( - document.getElementById('my-content-switcher-btn-1') -); -``` - -#### Options - -| Option | Default Selector | Description | -| --------------------- | ------------------------------------------------ | ------------------------------------------------------------------ | -| `selectorInit` | `[data-content-switcher]` | The CSS selector to find content-switcher | -| `selectorButton` | `input[type="radio"], .bx--content-switcher-btn` | The CSS selector to find the content-switcher buttons | -| `classActive` | `bx--content-switcher--selected` | The className for a selected button | -| `eventBeforeSelected` | `content-switcher-beingselected` | Custom event fired before a button is selected in content-switcher | -| `eventAfterSelected` | `content-switcher-selected` | Custom event fired after a button is selected in content-switcher | - -#### Events - -| Event Name | Description | -| -------------------------------- | ------------------------------------------------------------------ | -| `content-switcher-beingselected` | Custom event fired before a button is selected in content-switcher | -| `content-switcher-selected` | Custom event fired after a button is selected in content-switcher | - -##### Example - -Preventing a content switcher item from being selected in a certain condition - -```javascript -document.addEventListener('content-switcher-beingselected', function(evt) { - if (!myApplication.shouldContentSwitcherItemBeSelected(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - -Notifying events of all content switcher items being selected to an analytics -library - -```javascript -document.addEventListener('content-switcher-selected', function(evt) { - myAnalyticsLibrary.send({ - action: 'Content switcher item selected', - id: evt.target.id, - }); -}); -``` - -#### Classes - -| Name | Description | -| -------------------------------- | ----------------------------------- | -| `bx--content-switcher--selected` | The className for a selected button | - -### FAQ - -#### Preset an active button and panel with HTML - -While SCSS and JS are setup, you can configure Content Switcher and its -associated content through the HTML. - -Each `bx--content-switcher-btn` has a `data-target` value with a selector for a -panel element. When one of these buttons is clicked, then it will show the panel -that the `data-target` is pointing to. - -For example, - -The first button has a `data-target` pointing to `.demo-panel--opt-1`. When -clicking the first button, the JavaScript will find the DOM element using the -given `data-target` selector and display it while hiding all other panels using -the `hidden` attribute. - -Below is an HTML setup for Content Switcher that will do the following: - -- Select the first button by default (as indicated by - `bx--content-switcher--selected` class) -- Show the `<div class="demo--panel--opt-1">` element -- Hide the other elements - -```html -<div data-content-switcher class="bx--content-switcher"> - <button - class="bx--content-switcher-btn bx--content-switcher--selected" - data-target=".demo--panel--opt-1" - > - Option 1 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2"> - Option 2 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3"> - Option 3 - </button> -</div> -<div class="demo--panel--opt-1">Show Option 1</div> -<div class="demo--panel--opt-2" hidden>Show Option 2</div> -<div class="demo--panel--opt-3" hidden>Show Option 3</div> -``` - -#### Preset an active button and panel with JavaScript - -Use `setActive` class method to preset the selection on a Content Switcher; -doing this will avoid manually adding `bx--content-switcher--selected` modifier -class and `hidden` attributes on HTML. - -```html -<div - data-content-switcher - id="my-content-switcher" - class="bx--content-switcher" -> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-1"> - Option 1 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2"> - Option 2 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3"> - Option 3 - </button> -</div> -<div class="demo--panel--opt-1">Show Option 1</div> -<div class="demo--panel--opt-2">Show Option 2</div> -<div class="demo--panel--opt-3">Show Option 3</div> -``` - -```js -// Get HTMLelement for button to preselect it with setActive -const button = document.querySelector('[data-target=".demo--panel--opt-2"]'); -// Initialize an instance of ContentSwitcher with init(), create(element) or new ContentSwitcher(element) -ContentSwitcher.init(); -// Grab an ContentSwitcher instance -const instance = ContentSwitcher.components.get( - document.getElementById('my-content-switcher') -); -// Use setActive -instance.setActive(button); -``` - -The `setActive` method also takes an optional `callback` function parameter. The -most typical example of using this is acting on a newly selected -content-switcher button. - -```js -contentSwitcher.setActive(button, function(error, item) { - if (!error) { - // Having no error means that content switching is not canceled, so go on… - item.ownerDocument - .querySelector(item.dataset.target) - .querySelector('input') - .focus(); // `item` is the newly selected button - } -}); -``` - -#### Using buttons or anchor elements are both fine - -Content Switcher can be implemented with either `<button>` or `<a>` elements for -its click targets. Both uses of HTML will render the same visual styles and -interactions. - -```html -<div data-content-switcher class="bx--content-switcher"> - <a - href="javascript:void(0)" - class="bx--content-switcher-btn bx--content-switcher--selected" - data-target=".demo--panel--opt-1" - >Option 1</a - > - <a - href="javascript:void(0)" - class="bx--content-switcher-btn" - data-target=".demo--panel--opt-2" - >Option 2</a - > - <a - href="javascript:void(0)" - class="bx--content-switcher-btn" - data-target=".demo--panel--opt-3" - >Option 3</a - > -</div> -<div data-content-switcher class="bx--content-switcher"> - <button - class="bx--content-switcher-btn bx--content-switcher--selected" - data-target=".demo--panel--opt-1" - > - Option 1 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2"> - Option 2 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3"> - Option 3 - </button> -</div> -``` diff --git a/packages/components/src/components/content-switcher/migrate-to-7.x.md b/packages/components/src/components/content-switcher/migrate-to-7.x.md deleted file mode 100644 index d2158b557d28..000000000000 --- a/packages/components/src/components/content-switcher/migrate-to-7.x.md +++ /dev/null @@ -1,42 +0,0 @@ -### HTML - -Previously supported HTML for content-switcher that was deprecated in 6.x has -now been removed in 7.x. Use the smaller, simpler HTML for content-switcher from -now on: - -```html -<div data-content-switcher class="bx--content-switcher"> - <button - class="bx--content-switcher-btn bx--content-switcher--selected" - data-target=".demo--panel--opt-1" - > - Option 1 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-2"> - Option 2 - </button> - <button class="bx--content-switcher-btn" data-target=".demo--panel--opt-3"> - Option 3 - </button> -</div> -``` - -### SCSS - -The `_content-switcher.scss` file is now located at -`src/components/content-switcher/_content-switcher.scss`. You will need to -update any `@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/content-switcher/content-switcher'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/content-switcher/content-switcher'; -``` - -Classes for content-switcher have been renamed to use less BEM underscores. diff --git a/packages/components/src/components/data-table/README.md b/packages/components/src/components/data-table/README.md deleted file mode 100644 index d0840e676522..000000000000 --- a/packages/components/src/components/data-table/README.md +++ /dev/null @@ -1,139 +0,0 @@ -### SCSS - -The update to tables splits out the `scss` files into multiple partial files -with specific functionality, with a main index file bringing them together. - -#### Files - -| Name | Description | -| ----------------------- | ---------------------------------------- | -| `data-table` | index file, brings in all functionality | -| `data-table-core` | Core styles and base modifiers, required | -| `data-table-action` | Action bar styles | -| `data-table-expandable` | Expandable row styles | -| `data-table-sort` | Sortable header styles | - -#### Modifiers - -| Name | Description | -| --------------------------------------- | --------------------------------------------------- | -| `bx--data-table--compact` | Change table row height to 24 | -| `bx--data-table--short` | Change table row height to 32 | -| `bx--data-table--tall` | Change table row height to 64 | -| `bx--data-table--zebra` | Toggle on zebra striping | -| `bx--data-table--static` | Change default table width from 100% to auto | -| `bx--data-table--no-border` | Remove default border on table cells | -| `bx--data-table--visible-overflow-menu` | Show overflow menu icons by default (without hover) | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { DataTable } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var DataTable = CarbonComponents.DataTable; -``` - -#### Instantiating - -```javascript -// `#my-data-table` is an element with `[data-data-table]` attribute -DataTable.create(document.getElementById('my-data-table')); -``` - -#### Public Methods - -| Name | Params | Descriptions | -| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | -| `release` | | Deletes the instance and removes document event listeners | -| `refreshRows` | | When adding in new table rows, reinitialize parent-child relationships. Not required if not using expandable rows | - -##### Example - Keeping data table in sync with dynamic change in rows list (For expantable table) - -```javascript -// `#my-data-table` is an element with `[data-data-table]` attribute -var dataTableInstance = DataTable.create( - document.getElementById('my-data-table') -); -dataTableInstance.refreshRows(); -``` - -#### Events - -| Key | Value | Description | -| ---------------------- | ------------------------------- | ----------------------------------- | -| `eventBeforeExpand` | `data-table-beforetoggleexpand` | Row expansion event | -| `eventAfterExpand` | `data-table-aftertoggleexpand` | Row expansion event | -| `eventBeforeSort` | `data-table-beforetogglesort` | Sort event | -| `eventAfterSort` | `data-table-aftertogglesort` | Sort event | -| `eventTrigger` | `[data-event]` | Data attribute for clickable events | -| `eventParentContainer` | `[data-parent-row]` | Data attribute for event container | - -##### Example - Preventing a table expando from being toggled in a certain condition - -```javascript -document.addEventListener('data-table-beforetoggleexpand', function(evt) { - if (!myApplication.shouldToggleExpando(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Sorting table content - -```javascript -document.addEventListener('data-table-aftertogglesort', function(evt) { - // `evt.target` will be `div.bx--data-table-container` - // `evt.detail.element` will be `button.bx--table-sort` whose sorting is changed, - // and will have `bx--table-sort--ascending` class or not depending on the sorting state - evt.target.querySelector( - 'tbody' - ).innerHTML = myApplication.resortTableContent( - evt.target, - evt.detail.element - ); -}); -``` - -#### Options - -| Key | Value | Description | -| -------------------------- | ---------------------------- | ------------------------------------------ | -| `selectorInit` | `[data-table]` | Required css class to target table element | -| `selectorToolbar` | `.bx--table--toolbar` | Toolbar parent selector | -| `selectorActions` | `.bx--batch-actions` | Action bar parent selector | -| `selectorCount` | `[data-items-selected]` | Selected count span selector | -| `selectorActionCancel` | `.bx--batch-summary__cancel` | Action cancel button selector | -| `selectorCheckbox` | `.bx--checkbox` | Checkbox class selector | -| `selectorExpandCells` | `.bx--table-expand` | Expand td selector | -| `selectorExpandableRows` | `.bx--expandable-row` | Expand tr selector | -| `selectorParentRows` | `.bx--parent-row` | Parent row selector | -| `selectorChildRow` | `[data-child-row]` | Child row selector | -| `selectorTableBody` | `tbody` | Generic tbody selector | -| `classExpandableRow` | `bx--expandable-row` | Expandable Row parent class | -| `classExpandableRowHidden` | `bx--expandable-row--hidden` | Initial hidden class | -| `classExpandableRowHover` | `bx--expandable-row--hover` | Hover styles class | -| `classTableSortAscending` | `bx--table-sort--ascending` | Ascending sort icon class | -| `classTableSortActive` | `bx--table-sort--active` | Active sort icon class | - -### FAQ - -**How do I sort the tables** The table component does not sort the table for -you, rather it emits an event and toggles the sort UI. It is up to the user to -re-render the table rows sorted; you can see this in action -[in the React Storybook](http://react.carbondesignsystem.com/?selectedKind=DataTable&selectedStory=with%20sorting&full=0&addons=1&stories=1&panelRight=0&addonPanel=storybook%2Factions%2Factions-panel). - -**How do I use the expandable rows** If you would like to programmatically -expand table rows, you can add the `bx--expandable-row` to the -`selectorParentRows` elements. - -**How do I activate the batch actions pane** If you would like to -programmatically activate the batch actions pane, you can add -`bx--batch-actions--active` to the `bx--batch-actions` element. diff --git a/packages/components/src/components/date-picker/README.md b/packages/components/src/components/date-picker/README.md deleted file mode 100644 index 622259fd2278..000000000000 --- a/packages/components/src/components/date-picker/README.md +++ /dev/null @@ -1,107 +0,0 @@ -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { DatePicker } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var DatePicker = CarbonComponents.DatePicker; -``` - -#### Instantiating - -```javascript -// `#my-date-picker` is an element with `[data-date-picker]` attribute -DatePicker.create(document.getElementById('my-date-picker')); -``` - -#### Public Methods - -| Name | Params | Description | -| --------- | ------ | -------------------- | -| `release` | | Deletes the instance | - -#### Options - -| Option | Default Selector | Description | -| ----------------------------- | ------------------------------- | -------------------------------------------------------- | -| `selectorInit` | `[data-date-picker]` | Element for initializing instance | -| `selectorDatePickerInput` | `[data-date-picker-input]` | Input element | -| `selectorDatePickerInputFrom` | `[data-date-picker-input-from]` | For ranged calendars only: The "From date" input element | -| `selectorDatePickerInputTo` | `[data-date-picker-input-to]` | For ranged calendars only: The "To date" input element | -| `selectorDatePickerIcon` | `[data-date-picker-icon]` | Calendar icon | -| `classCalendarContainer` | `.bx--date-picker__calendar` | Class selector for the calendar container | -| `classMonth` | `.bx--date-picker__month` | Class selector for the calendar month | -| `classWeekdays` | `.bx--date-picker__weekdays` | Class selector for the calendar weekdays | -| `classDays` | `.bx--date-picker__days` | Class selector for the calendar days | -| `classWeekday` | `.bx--date-picker__weekday` | Class selector for a calendar weekday | -| `classDay` | `.bx--date-picker__day` | Class selector for a calendar day | -| `attribType` | `data-date-picker-type` | Specifies the calendar mode (single or range) | -| `dateFormat` | `'m/d/Y'` | The date format given to the calendar instance | - -The date picker is built on top of -[Flatpickr](https://chmln.github.io/flatpickr/), so many of the -[events](https://chmln.github.io/flatpickr/events/) and -[config options](https://chmln.github.io/flatpickr/options/) that come with -Flatpickr is therefore available to the date picker options. This includes -methods for setting a min date, max date, disabling date(s), specifiying a range -of dates, and more. - -##### Example - Getting notified of date picker dropdown being closed - -```javascript -// `#my-date-picker` is an element with `[data-date-picker]` attribute -DatePicker.create(document.getElementById('my-date-picker'), { - onClose() { - console.log('Date picker dropdown closed!'); - }, -}); -``` - -### FAQ - -#### Using and understanding Date Picker - -There are 3 different date picker types: - -| Type | `data-date-picker-type` | -| --------------------------------------- | ---------------------------------- | -| A simple date picker without a calendar | No data attributes needed | -| A single date picker | `[data-date-picker-type="single"]` | -| A ranged date picker | `[data-date-picker-type="range"]` | - -**The simple date picker** is a text input without a calendar. You can specify -the pattern for the text input to make sure the user enters the correct date -format. The default regex pattern that ships with the simple date picker is -`\d{1,2}/\d{4}` ('dd/yyyy' for short date pickers) and `\d{1,2}/\d{1,2}/\d{4}` -('dd/mm/yyyy' or mm/dd/yyyy). The simple date picker does not require any -JavaScript. - -**The single date picker** is a text input with a calendar instance attached to -it. It also ships with a calendar icon inside the input field. The calendar will -open when the input is focused, and the user can both type in a date or select a -day from the calendar. The single date picker requires JavaScript, so the data -attributes `data-date-picker` and `data-date-picker-type="single"` are required -on the parent div, and the data attribute `data-date-picker-input` is required -on the input field. - -**The ranged date picker** has two text inputs with a ranged calendar instance -attached to them. The ranged date picker requires JavaScript, so the data -attributes `data-date-picker` and `data-date-picker-type="range"` are required -on the parent div, and the data attributes `data-date-picker-input-from` and -`data-date-picker-input-to` are required on the two input fields. - -#### Localization - -Date Picker supports localization, and you can specify the date format by -overriding the component option `dateFormat`. Supported date formats are listed -[here](https://chmln.github.io/flatpickr/formatting/). - -To localize the date picker globally, please follow -[these instructions](https://chmln.github.io/flatpickr/localization/). diff --git a/packages/components/src/components/dropdown/README.md b/packages/components/src/components/dropdown/README.md deleted file mode 100644 index ca70513ed012..000000000000 --- a/packages/components/src/components/dropdown/README.md +++ /dev/null @@ -1,92 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--dropdown` class. - -| Name | Description | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `.bx--dropdown--auto-width` | Allows the width of the dropdown to be equal to the width of the content inside it instead of being 100% width of the container. | -| `.bx--dropdown--selected` | Applies specific styles for a selected dropdown item. | -| `.bx--dropdown--open` | Applies specific styles when the dropdown is opened | -| `.bx--dropdown--up` | Applies style to have the dropdown slide up instead of down | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { Dropdown } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var Dropdown = CarbonComponents.Dropdown; -``` - -#### Instantiating - -```javascript -// `#my-dropdown` is an element with `[data-dropdown]` attribute -Dropdown.create(document.getElementById('my-dropdown')); -``` - -#### Public Methods - -| Name | Params | Description | -| ---------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `release` | | Deletes the instance | -| `getCurrentNavigation` | | Returns the currently highlighted element | -| `navigate` | direction: `Number` | Moves the focus up or down | -| `select` | itemToSelect: `Object` | Handles clicking on the dropdown options, doing the following: Changing text to selected option, removing selected option from options when selected, and emitting custom events | -| `setCloseOnBlur` | | Sets an event handler to document for "close on blue" behavior | - -##### Example - Changing the active item - -```javascript -// `#my-dropdown` is an element with `[data-dropdown]` attribute -var dropdownInstance = Dropdown.create(document.getElementById('my-dropdown')); -// `#my-dropdown-link-1` is one of the `<a>`s with `bx--dropdown-link` class -dropdownInstance.select(document.getElementById('my-dropdown-link-1')); -``` - -#### Options - -| Option | Default Selector | Description | -| ---------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------ | -| `selectorInit` | `[data-dropdown]` | The selector to find the dropdown component | -| `selectorItem` | `.bx--dropdown-link` | The selector to find the clickable area in the selected dropdown item | -| `selectorItemSelected` | `.bx--dropdown--selected` | The selector to find the clickable area in the selected dropdown item | -| `selectorItemHidden` | `[hidden],[aria-hidden="true"]` | The selector to find hidden dropdown items. Used to skip dropdown items for keyboard navigation. | -| `classSelected` | `bx--dropdown--selected` | The class for the selected dropdown item. | - -#### Events - -| Event Name | Description | -| ------------------------ | ----------------------------------------------------- | -| `dropdown-beingselected` | Custom event fired before a dropdown item is selected | -| `dropdown-selected` | Custom event fired after a dropdown item is selected | - -##### Example - Preventing a dropdown item from being selected in a certain condition - -```javascript -document.addEventListener('dropdown-beingselected', function(evt) { - if (!myApplication.shouldDropdownItemBeSelected(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Notifying events of all dropdown items being selected to an analytics library - -```javascript -document.addEventListener('dropdown-selected', function(evt) { - myAnalyticsLibrary.send({ - action: 'Dropdown item selected', - id: evt.target.id, - }); -}); -``` diff --git a/packages/components/src/components/dropdown/migrate-to-7.x.md b/packages/components/src/components/dropdown/migrate-to-7.x.md deleted file mode 100644 index a3333e4d7485..000000000000 --- a/packages/components/src/components/dropdown/migrate-to-7.x.md +++ /dev/null @@ -1,34 +0,0 @@ -### HTML - -No structural changes. However, class names have been changed. - -### SCSS - -The `_dropdown.scss` file is now located at -`src/components/dropdown/_dropdown.scss`. You will need to update any `@import` -statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/dropdown/dropdown'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/dropdown/dropdown'; -``` - -Quite a few class names have changed. See table below. - -| Old Class | New Class | -| ------------------------- | ----------------- | -| bx--dropdown\_\_menu-text | bx--dropdown-text | -| bx--dropdown\_\_list | bx--dropdown-list | -| bx--dropdown\_\_list-item | bx--dropdown-item | -| bx--dropdown\_\_link | bx--dropdown-link | - -### JavaScript - -No changes. diff --git a/packages/components/src/components/file-uploader/README.md b/packages/components/src/components/file-uploader/README.md deleted file mode 100644 index a8439578185e..000000000000 --- a/packages/components/src/components/file-uploader/README.md +++ /dev/null @@ -1,152 +0,0 @@ -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { FileUploader } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var FileUploader = CarbonComponents.FileUploader; -``` - -#### Instantiating - -```javascript -// `#my-file` is an element with `[data-file]` attribute -FileUploader.create(document.getElementById('my-file')); -``` - -#### Public Methods - -| Name | Params | Description | -| ---------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | -| `setState` | `state`: `String`, `selectIndex`: `Number` | After files are added, call this method to change `state` of the filenames (`'upload'`, `'complete'`, `'edit'`). | -| `release` | | Deletes the instance | - -##### Example - Changing the uploading state - -```javascript -// `#my-file` is an element with `[data-file]` attribute -var fileUploaderInstance = FileUploader.create( - document.getElementById('my-file') -); -// Makes the 2nd file shown as its uploading complete -fileUploaderInstance.setState('complete', 1); -``` - -#### Options - -| Option | Default Selector | Description | -| ----------------------------- | ------------------------------------- | ------------------------------------------------------------- | -| `selectorInit` | `[data-file]` | Element for initializing instance | -| `selectorInput` | `[input[type="file"].bx--file-input]` | Input element | -| `selectorContainer` | `[data-file-container]` | Element for injecting HTML for upload and edit states | -| `selectorDropContainer` | `[data-file-drop-container]` | Element for drag files onto | -| `selectorOtherDropContainers` | `[data-drop-containers]` | Element for applications to handle their own drag/drop effect | -| `selectorCloseButton` | `.bx--file-close` | Close button for removing filename nodes | - -#### Events - -| Event Name | Description | -| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `change` | When files are added to File Uploader, a change event is fired. This also triggers custom events; see eventBeforeDisplayFilesFileuploader and eventAfterDisplayFilesFileuploader` | -| `eventBeforeDeleteFilenameFileuploader` | Triggered before clicking on close button(s) inside filename node(s). | -| `eventAfterDeleteFilenameFileuploader` | Triggered after clicking on close button(s) inside filename node(s). | - -### FAQ - -#### Using and understanding File Uploader - -When files are added to File Uploader, a `change` event or `drop` event is -fired. The `change`/`drop` events trigger a private method to inject HTML into -the `selectorContainer` element displaying all added filenames. - -![file](https://cloud.githubusercontent.com/assets/4185382/24562175/7fcb4502-160f-11e7-8d9c-5ef4bdd67194.gif) - -Trigger additional states using `setState()` public method. Additional states -are **edit**, **complete** and **upload**. - -**Edit** injects close icons into each filename state container. A `click` event -listener is also added to remove the filename when close button is clicked. - -![edit](https://cloud.githubusercontent.com/assets/4185382/24562305/f3660b28-160f-11e7-9c67-c47829597931.gif) - -```scss -.bx--file__state-container .bx--file-close { - width: 1rem; - height: 1rem; - fill: $text-01; - cursor: pointer; -} -``` - -**Upload** injects Loading components into each filename state container. - -Developers using File Uploader will be able to use JavaScript to inject a -Loading component when selected files are _actually_ being uploaded. Users can -select a **single** file or **multiple** files. By default, any file type is -accepted. It's up to the developer and their design team to specify and -implement validations for which file types are acceptable. - -![upload](https://cloud.githubusercontent.com/assets/4185382/24562332/114feabe-1610-11e7-9aba-3ca74ef9e8cc.gif) - -**Complete** injects checkmark icons into each filename state container. - -![complete](https://cloud.githubusercontent.com/assets/4185382/24562373/2f901fbc-1610-11e7-97f4-153f16bcbcfc.pngtrun) - -```scss -.bx--loading { - width: 2rem; - height: 2rem; - margin-right: -7px; -} -.bx--loading__svg { - stroke: $ui-05; -} -``` - -#### WCAG AA Color Accessibility - -File Uploader color contrast ratios are accessible. Since File Uploader -(specifically filename elements) low-opacity colors, verifying color ratios with -IBM a11y tool may not yield passing results. - -However, evaluating resulting background colors as solid colors will pass. - -| Opacity + UI background color | Actual background color | Text color | WCAG AA Color Ratio | Passes 4.5? | -| ----------------------------- | ----------------------- | ---------- | ------------------- | ------------------ | -| `#5a6872` at 10% on `#ffffff` | `#cedbec` | `#152935` | 10.70 | :white_check_mark: | -| `#5a6872` at 10% on `#f5f7fa` | `#c6d5e8` | `#152935` | 10.07 | :white_check_mark: | - -#### Truncating long filenames - -By default, filenames are truncated so that any filename that goes beyond -`300px` will be cutoff. - -![image](https://cloud.githubusercontent.com/assets/4185382/24562399/4a00f560-1610-11e7-97c1-9113fb299160.png) - -Truncating filenames is enabled through the use of -`@mixin text-overflow($size)`. - -You can override this behavior with SCSS by giving the `@mixin` a new `width` by -overriding this `@mixin`. - -```scss -// Using mixin, override initial styles in _file-uploader.scss -.bx--file-filename { - @include text-overflow(768px); -} -``` - -You can also use plain CSS by setting a new `width`. - -```scss -.bx--file-filename { - width: 768px; -} -``` diff --git a/packages/components/src/components/file-uploader/migrate-to-7.x.md b/packages/components/src/components/file-uploader/migrate-to-7.x.md deleted file mode 100644 index 8fc4a9160b84..000000000000 --- a/packages/components/src/components/file-uploader/migrate-to-7.x.md +++ /dev/null @@ -1,46 +0,0 @@ -### HTML - -HTML for File Uploader has changed a lot, it will be best to simply copy and -paste the HTML to your project. With that said, here are some of the main -changes to be aware of. - -HTML for File Uploader (along with all other form elements) now use -`.bx--form-item` to wrap the HTML and `.bx--label` to use as a label. There's -also a new `.bx--file-container` element that is used to display filename -elements. See README for details on how this works. - -### SCSS - -The `_file-uploader.scss` file is now located at -`src/components/file-uploader/_file-uploader.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/file-uploader/file-uploader'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/file-uploader/file-uploader'; -``` - -| Old Class | New Class | Note | -| ----------------- | --------------------------- | ------- | -| bx--file\_\_label | bx--label | Changed | -| | bx--form-item | Added | -| | bx--label-description | Added | -| | bx--file | Added | -| | bx--file-btn | Added | -| | bx--file-container | Added | -| | .bx--file=filename | Added | -| | bx--file\_\_state-container | Added | -| | bx--file--close | Added | -| | bx--file--complete | Added | -| | bx--loading | Added | - -### JavaScript - -The entire API for `FileUploader` has changed. See README for details. diff --git a/packages/components/src/components/floating-menu/README.md b/packages/components/src/components/floating-menu/README.md deleted file mode 100644 index 11d89ab35d80..000000000000 --- a/packages/components/src/components/floating-menu/README.md +++ /dev/null @@ -1,32 +0,0 @@ -#### Public Methods - -| Name | Params | Description | -| ---------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------- | -| `show`/`hide` | `evt`: `Event` or `Element`, `callback`: `Function` | Shows/hides the menu. | -| `changeState` | `state`: `string`, `detail`: `Object`, `callback`: `Function` | Changes the shown/hidden state. | -| `shouldStateBeChanged` | `state`: `string` | Returns `true` if the given state is different from the current state. | -| `release` | | Deletes the instance and removes resize event listeners. | - -#### Options - -| Option | Default value | Description | -| ------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `selectorContainer` | `[data-floating-menu-container]` | The CSS selector to find the element you wish the append the menu contents to. | -| `attribDirection` | `data-floating-menu-direction` | The attribute name to specify menu placement direction (top/right/bottom/left). | -| `classShown` | None | The CSS class for shown state, for the menu. Should be provided via component creation options. | -| `classRefShown` | None | The CSS class for shown state, for the trigger button. Should be provided via component creation options. | -| `eventBeforeShown` | `floating-menu-beingshown` | The name of the custom event fired before a menu is opened. | -| `eventAfterShown` | `floating-menu-shown` | The name of the custom event fired after a menu is opened. | -| `eventBeforeHidden` | `floating-menu-beinghidden` | The name of the custom event fired before a menu is closed. | -| `eventAfterHidden` | `floating-menu-hidden` | The name of the custom event fired after a menu is closed. | -| `refNode` | None | The trigger button. Should be provided via component creation options. | -| `offset` | `{ top: 0, left: 0}` | An object containing the top and left offset values in px. | - -#### Events - -| Event Name | Description | -| --------------------------- | -------------------------------------------------------------------------------------------------------- | -| `floating-menu-beingshown` | The name of the custom event fired before a menu is opened. Cancellation of this event stops it opening. | -| `floating-menu-shown` | The name of the custom event fired after a menu is opened. | -| `floating-menu-beinghidden` | The name of the custom event fired before a menu is closed. Cancellation of this event stops it closing. | -| `floating-menu-hidden` | The name of the custom event fired after a menu is closed. | diff --git a/packages/components/src/components/form/README.md b/packages/components/src/components/form/README.md deleted file mode 100644 index 2da450fd1510..000000000000 --- a/packages/components/src/components/form/README.md +++ /dev/null @@ -1,146 +0,0 @@ -### SCSS - -#### Modifiers - -Modifiers are used with various form-related classes. - -| Selector | Description | -| ---------------------- | ----------------------------------- | -| `.bx--label--disabled` | Applies disabled styles for a label | - -### FAQ - -#### Using Form Requirement - -Carbon Components provide HTML attributes and CSS to enable form validation for -each input or control. - -For example, here's a **Form Item** with a required text input. - -```html -<div class="bx--form-item"> - <label for="text1" class="bx--label">Username</label> - <input - required - id="text1" - type="text" - class="bx--text__input" - placeholder="Enter username here" - /> - <div class="bx--form-requirement">Username is taken.</div> -</div> -``` - -The `bx--form-requirement` element will be hidden until `data-invalid` attribute -gets added to the `input`. Validate the text input on your own and then use -JavaScript to add the attribute if the input value is invalid. - -```html -<div class="bx--form-item"> - <label for="text1" class="bx--label">Username</label> - <input - data-invalid - required - id="text1" - type="text" - class="bx--text__input" - placeholder="Enter username here" - /> - <div class="bx--form-requirement">Username is taken.</div> -</div> -``` - -Now that `data-invalid` is added to the `input`, the `bx--form-requirement` will -appear. - -#### HTML - -Carbon Components provides inputs (checkboxes, text-inputs, etc.) and some -default styles for forms: - -- `.bx--form-item` -- `.bx--fieldset` -- `.bx--label` -- `.bx--form-requirement` - -Make use of HTML to compose and structure forms appropriate to your project's -needs. - -For example, here's a simple form for a login page that uses a mix of HTML and -Carbon Components. - -```html -<form> - <section> - <div class="bx--form-item"> - <label for="text1" class="bx--label">Username</label> - <input - data-invalid - id="your-username-id" - type="text" - class="bx--text__input" - placeholder="Enter username here" - /> - <div class="bx--form-requirement">Username is taken.</div> - </div> - <div class="bx--form-item"> - <label for="text1" class="bx--label">Password</label> - <input - data-invalid - id="your-password-id" - type="password" - class="bx--text__input" - placeholder="Enter username here" - /> - <div class="bx--form-requirement">Password must rhyme with Batman.</div> - </div> - </section> - <fieldset> - <legend>Click Register when you're ready!</legend> - <button class="bx--btn bx--btn--primary" type="submit">Register</button> - </fieldset> -</form> -``` - -You can use any appropriate HTML for structuring and grouping your forms. If you -want, those `<section>` elements could be `<div>` elements. Or you can change -the `<fieldset>` element to be a `<section>` if that's what you want. - -#### Fieldset and Legend - -It's best practice to wrap any groups of checkboxes or radio inputs with -`<fieldset>` and use `<legend>` to label the group. This best practice applies -mainly to composing forms where users are submitting data. - -Here's an example from -[MDN](https://developer.mozilla.org/en-US/docs/Learn/HTML/Forms/How_to_structure_an_HTML_form) -that explains why this is a best practice. - -> The `<legend>` element formally describes the purpose of the `<fieldset>` -> element. Many assistive technologies will use the `<legend>` element as if it -> is a part of the label of each widget inside the corresponding `<fieldset>` -> element. -> -> ```html -> <form> -> <fieldset> -> <legend>Fruit juice size</legend> -> <p> -> <input type="radio" name="size" id="size_1" value="small" /> -> <label for="size_1">Small</label> -> </p> -> <p> -> <input type="radio" name="size" id="size_2" value="medium" /> -> <label for="size_2">Medium</label> -> </p> -> <p> -> <input type="radio" name="size" id="size_3" value="large" /> -> <label for="size_3">Large</label> -> </p> -> </fieldset> -> </form> -> ``` -> -> With this example, a screen reader will pronounce "Fruit juice size small" for -> the first widget, "Fruit juice size medium" for the second, and "Fruit juice -> size large" for the third. diff --git a/packages/components/src/components/form/migrate-to-7.x.md b/packages/components/src/components/form/migrate-to-7.x.md deleted file mode 100644 index 9035dbe9ccc1..000000000000 --- a/packages/components/src/components/form/migrate-to-7.x.md +++ /dev/null @@ -1,47 +0,0 @@ -### HTML - -The `form` component has been simplified. `.bx--form` has been removed since it -was not providing anything significant. Your forms should still be contained in -a `<form>` element but the `.bx--form` class is unneeded. The `.bx--form__row` -and `.bx--form__row--column` classes for form layout have been removed. Form -styles will no longer dictate default layouts. See HTML docs for more details - -The form component supplies 3 classes. - -- `.bx--form-item` -- `.bx--label` -- `.bx--form-requirement` - -Styles for form components such as `text-input` are contained in their own -component files. - -For full usage guidelines of the new HTML see the component README file. - -### SCSS - -The `_form.scss` file is now located at `src/components/form/_form.scss`. You -will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/form/form'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/form/form'; -``` - -Quite a few class names have changed. See table below. - -| Old Class | New Class | Note | -| ------------------------ | -------------------- | ------- | -| bx--form\_\_row-item | bx--form-item | Changed | -| bx--form\_\_label | bx--label | Changed | -| bx--form\_\_requirements | bx--form-requirement | Changed | -| bx--form\_\_row | N/A | Removed | -| bx--form\_\_row--column | N/A | Removed | -| | bx--fieldset | Added | diff --git a/packages/components/src/components/inline-loading/README.md b/packages/components/src/components/inline-loading/README.md deleted file mode 100644 index 29d9830a3f43..000000000000 --- a/packages/components/src/components/inline-loading/README.md +++ /dev/null @@ -1,56 +0,0 @@ -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { InlineLoading } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var InlineLoading = CarbonComponents.InlineLoading; -``` - -#### Instantiating - -```javascript -// `#my-inline-loading` is an element with `[data-inline-loading]` attribute -InlineLoading.create(document.getElementById('my-inline-loading')); -``` - -#### Static properties - -| Name | Type | Description | -| ------ | ------ | ---------------------------------------------------------------------------- | -| states | Object | The loading states. Contains `INACTIVE`, `ACTIVE` and `FINISHED` properties. | - -#### Public Methods - -| Name | Params | Description | -| ---------- | ---------------- | --------------------------------------- | -| `release` | | Deletes the instance | -| `setState` | state : `string` | Sets the active/inactive/finished state | - -##### Example - Transitioning the loading spinner to the finished state - -```javascript -// `#my-inline-loading` is an element with `[data-inline-loading]` attribute -var inlineLoadingInstance = InlineLoading.create( - document.getElementById('my-inline-loading') -); -inlineLoadingInstance.setState(InlineLoading.states.FINISHED); -``` - -#### Options - -| Option | Default Selector | Description | -| ---------------------- | ------------------------------------- | --------------------------------------------------------------- | -| `selectorInit` | `[data-inline-loading]` | The CSS selector to find the inline loading components | -| `selectorSpinner` | `[data-inline-loading-spinner]` | The CSS selector to find the spinner | -| `selectorFinished` | `[data-inline-loading-finished]` | The CSS selector to find the "finished" icon | -| `selectorTextActive` | `[data-inline-loading-text-active]` | The CSS selector to find the text describing the active state | -| `selectorTextFinished` | `[data-inline-loading-text-finished]` | The CSS selector to find the text describing the finished state | -| `classLoadingStop` | `.bx--loading--stop` | The CSS class for spinner's stopped state | diff --git a/packages/components/src/components/link/migrate-to-7.x.md b/packages/components/src/components/link/migrate-to-7.x.md deleted file mode 100644 index 0063f67ac7ba..000000000000 --- a/packages/components/src/components/link/migrate-to-7.x.md +++ /dev/null @@ -1,25 +0,0 @@ -### HTML - -No changes. - -### SCSS - -The `_link.scss` file is now located at `src/components/link/_link.scss`. You -will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/link/link'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/link/link'; -``` - -### JavaScript - -No changes. diff --git a/packages/components/src/components/list-box/README.md b/packages/components/src/components/list-box/README.md deleted file mode 100644 index 1847f30e4792..000000000000 --- a/packages/components/src/components/list-box/README.md +++ /dev/null @@ -1,23 +0,0 @@ -# `list-box` - -> A generic UI component used to build selection menus like Dropdowns, -> Comboboxes, and more. - -### SCSS - -#### Classes - -| Name | Description | -| :-------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `.bx--list-box` | The containing element for a `list-box` | -| `.bx--list-box--inline` | The `inline` variant of a `list-box` | -| `.bx--list-box--disabled` | The `disabled` state of a `list-box` control | -| `.bx--list-box__field` | A descendant of a `list-box` responsible for showing label information, selections, and current input | -| `.bx--list-box__label` | A descendant of a `list-box` field responsible for displaying the label of the control | -| `.bx--list-box__menu-icon` | A descendant of a `list-box` field responsible for displaying the open status of the menu of options for the control | -| `.bx--list-box__menu-icon--open` | A modifier of `.bx--list-box__menu-icon` that updates the orientation of the icon for when the menu of options for the control is visible | -| `.bx--list-box__selection` | A descendant of a `list-box` field responsbile for showing a selection has been made, in addition to providing a way to clear the current selection for the control | -| `.bx--list-box__selection--multi` | A modifier of `.bx--list-box__selection` when the control is able to have multiple selections | -| `.bx--list-box__menu` | A descendant of a `list-box` that provides a list of options that the user can select for the control | -| `.bx--list-box__menu-item` | A descendant of a `list-box__menu` that is a selectable option | -| `.bx--list-box__menu-item--highlighted` | A modifier for `list-box__menu-item` that indicates the item is being interacted with by a user | diff --git a/packages/components/src/components/list/README.md b/packages/components/src/components/list/README.md deleted file mode 100644 index 1b6e61680012..000000000000 --- a/packages/components/src/components/list/README.md +++ /dev/null @@ -1,11 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--list` class. - -| Selector | Description | -| ---------------------- | ------------------------------------------------------------------------ | -| `.bx--list--unordered` | Use to apply styles to an unordered list | -| `.bx--list--ordered` | Use to apply styles to an ordered list | -| `.bx--list--nested` | Use to apply styles to a nested list inside an ordered or unordered list | diff --git a/packages/components/src/components/list/migrate-to-7.x.md b/packages/components/src/components/list/migrate-to-7.x.md deleted file mode 100644 index 44acdb53c61b..000000000000 --- a/packages/components/src/components/list/migrate-to-7.x.md +++ /dev/null @@ -1,21 +0,0 @@ -### HTML - -No changes. - -### SCSS - -The `_list.scss` file is now located at `src/components/list/_list.scss`. You -will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/list/list'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/list/list'; -``` diff --git a/packages/components/src/components/loading/README.md b/packages/components/src/components/loading/README.md deleted file mode 100644 index 0ac4ebcbc13f..000000000000 --- a/packages/components/src/components/loading/README.md +++ /dev/null @@ -1,68 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--loading` class. - -| Selector | Description | -| ---------------------------- | ---------------------------------------- | -| `.bx--loading--small` | Class for small loading spinner | -| `.bx--loading--stop` | Class for stopping the loading animation | -| `.bx--loading-overlay--stop` | Class for hiding the overlay | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { Loading } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var Loading = CarbonComponents.Loading; -``` - -#### Instantiating - -```javascript -// `#my-loading` is an element with `[data-loading]` attribute -Loading.create(document.getElementById('my-loading')); -``` - -#### Public Methods - -| Name | Params | Description | -| ---------- | ------------------ | ----------------------------------------------------------- | -| `release` | | Deletes the instance | -| `set` | active : `Boolean` | Sets the active/inactive state | -| `toggle` | | Toggles active/inactive state | -| `isActive` | | Returns current state | -| `end` | | Runs end animation and then delete the element from the DOM | - -##### Example - Activating the loading spinner - -```javascript -// `#my-loading` is an element with `[data-loading]` attribute -var loadingInstance = Loading.create(document.getElementById('my-loading')); -loadingInstance.set(true); -``` - -#### Options - -| Option | Default Selector | Description | -| ------------------------- | --------------------------- | ---------------------------------------------------------------- | -| `selectorInit` | `[data-loading]` | The CSS selector to find the loading component | -| `selectorLoadingOverlay` | `.bx--loading-overlay` | The selector for the loading overlay. | -| `classLoadingOverlayStop` | `bx--loading-overlay--stop` | The class for the loading overlay's stopped state. | -| `active` | `true` | A boolean value representing the initial state of the component. | - -##### Example - Activating upon instantiating - -```javascript -// `#my-loading` is an element with `[data-loading]` attribute -Loading.create(document.getElementById('my-loading'), { active: true }); -``` diff --git a/packages/components/src/components/loading/migrate-to-7.x.md b/packages/components/src/components/loading/migrate-to-7.x.md deleted file mode 100644 index 8c93d5e5c5da..000000000000 --- a/packages/components/src/components/loading/migrate-to-7.x.md +++ /dev/null @@ -1,34 +0,0 @@ -### HTML - -There are now three variations of this component. Default, with a page overlay, -and a small version. No class names have changed. - -### SCSS - -The `_loading.scss` file is now located at -`src/components/loading/_loading.scss`. You will need to update any `@import` -statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/loading/loading'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/loading/loading'; -``` - -New class `.bx--loading-overlay` wraps a `.bx--loading` component and provides -an overlay for a "full screen" loading scenario. - -`bx--loading--small` is a new modifier class to be added with `bx--loading`. It -provides the small version of the loading component for use inside of another -component such as a button. - -### JavaScript - -`end()` is a method that plays the loading finished animation and then deletes -the element from the DOM. diff --git a/packages/components/src/components/modal/README.md b/packages/components/src/components/modal/README.md deleted file mode 100644 index b2bbb204f331..000000000000 --- a/packages/components/src/components/modal/README.md +++ /dev/null @@ -1,165 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--modal` class. - -| Name | Description | -| -------------------- | ----------------------------------------- | -| `.bx--modal--danger` | Selector for applying danger modal styles | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { Modal } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var Modal = CarbonComponents.Modal; -``` - -#### Instantiating - -##### For one with a trigger button (a `<button>` with `data-modal-target` attribute) - -```javascript -Modal.init(); -``` - -##### For one without a trigger button - -```javascript -// `#my-modal` is an element with `[data-modal]` attribute -Modal.create(document.getElementById('my-modal')); -``` - -#### Public methods - -| Name | Params | Description | -| --------- | ------ | -------------------- | -| `release` | | Deletes the instance | -| `show` | | Show the modal | -| `hide` | | Hide the modal | - -##### Example - Showing modal - -```javascript -// `#my-modal` is an element with `[data-modal]` attribute -var modalInstance = Modal.create(document.getElementById('my-modal')); -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 | -| `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 | -| `classBody` | 'bx--body--with-modal-open' | Class on `<body>` that toggles when a modal opens/closes | -| `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' | -| `eventAfterHidden` | 'modal-hidden' | - -##### Example - Preventing modals from being closed in a certain condition - -```javascript -document.addEventListener('modal-beinghidden', function(evt) { - if (myApplication.shouldModalKeptOpen(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Notifying events of all modals being closed to an analytics library - -```javascript -document.addEventListener('modal-hidden', function(evt) { - myAnalyticsLibrary.send({ - action: 'Modal hidden', - id: evt.target.id, - }); -}); -``` - -### FAQ - -#### How do I point multiple elements to the same modal? - -To trigger the same modal, you need to add the `data-modal-target` attribute to -a element, and then point it to the same id. For example - -```html -<button - class="bx--btn bx-btn--primary" - type="button" - data-modal-target="#modal" -> - A button -</button> -<button - class="bx--btn bx-btn--secondary" - type="button" - data-modal-target="#modal" -> - Another button -</button> -``` - -Both these buttons would trigger the modal with the id of `modal.` diff --git a/packages/components/src/components/modal/migrate-to-7.x.md b/packages/components/src/components/modal/migrate-to-7.x.md deleted file mode 100644 index 679806d5b0c1..000000000000 --- a/packages/components/src/components/modal/migrate-to-7.x.md +++ /dev/null @@ -1,65 +0,0 @@ -### HTML - -HTML for Modals have been given a siginificant overhaul. Previously, there were -3 distinct types of modals. Now, Modals simply adhere to a simple 3-part HTML -structure for better composability: - -A Modal can be made of these parts: - -- Modal Header -- Modal Content -- Modal Footer - -The Modal Footer will contain actions, usually a set of buttons. The most common -patterns for Modals will usually be Modals with a footer and Modals without a -footer. - -With that said, it will be best to copy and paste the new HTML for Modal to -capture all of the latest changes. - -### SCSS - -The `_modal.scss` file is now located at `src/components/modal/_modal.scss`. You -will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/modal/modal'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/modal/modal'; -``` - -Some classes have been changed. Some old classes have been repurposed to take on -different meanings or hook in different kinds of styles. Below is a subset of -changes that you can expect, but does not cover all changes. It will be best to -use the newest HTML as a template for new Modals. - -| Old Class | New Class | Note | -| ---------------------------- | ----------------------- | ------- | -| bx--modal-content\_\_label | | Removed | -| bx--modal-content\_\_heading | | Removed | -| bx--modal-content\_\_text | | Removed | -| | bx--modal-footer | Added | -| | bx--modal-header | Added | -| bx--modal-inner | bx--modal-container | Changed | -| bx--modal\_\_close | bx--modal-close | Changed | -| bx--modal\_\_close--icon | bx--modal-close\_\_icon | Changed | - -### JavaScript - -The `getTransitionDuration` function is no longer used. - -The `hookCloseActions` method is now a private method, so it's been renamed to -`_hookCloseActions`. - -A new private method has been added called `_getLaunchingDetails`, which is used -inside the `show` public method. - -The `static hook` method has been removed since it was deprecated in the -previous major version (6.x). diff --git a/packages/components/src/components/multi-select/README.md b/packages/components/src/components/multi-select/README.md deleted file mode 100644 index cfdccf405e4f..000000000000 --- a/packages/components/src/components/multi-select/README.md +++ /dev/null @@ -1,58 +0,0 @@ -# `multi-select` - -### SCSS - -#### Classes - -| Name | Description | -| :------------------ | :--------------------------------------------------- | -| `.bx--multi-select` | Used on a container node to specify its control type | - -#### Using Form Validation - -Carbon Components provides HTML attributes and CSS to enable form validation for -each input or control. - -For example, here's a **Multiselect** that provides a message if an option is -not selected. - -```html -<div - role="listbox" - tabindex="0" - class="bx--multi-select bx--list-box" - data-invalid="true" -> - <div - role="button" - class="bx--list-box__field" - tabindex="0" - type="button" - aria-label="open menu" - aria-expanded="false" - aria-haspopup="true" - data-toggle="true" - > - <span class="bx--list-box__label">MultiSelect Label</span> - <div class="bx--list-box__menu-icon"> - <svg - fill-rule="evenodd" - height="5" - role="img" - viewBox="0 0 10 5" - width="10" - alt="Open menu" - aria-label="Open menu" - > - <title>Open menu</title> - <path d="M0 0l5 4.998L10 0z"></path> - </svg> - </div> - </div> -</div> -<div class="bx--form-requirement">Please select an option.</div> -``` - -The `bx--form-requirement` element will be hidden until `data-invalid` attribute -gets added to the `bx--multi-select`. Validate the multiselect on your own and -then use JavaScript to add the attribute if the multiselect value is invalid. diff --git a/packages/components/src/components/notification/README.md b/packages/components/src/components/notification/README.md deleted file mode 100644 index 0a99ae882843..000000000000 --- a/packages/components/src/components/notification/README.md +++ /dev/null @@ -1,127 +0,0 @@ -### SCSS - -#### Mixins - -| Name | Params | Description | -| ---------------------------- | ---------------- | ----------------------------------------- | -| `inline-notification--color` | `$color`: String | Applies given `$color` to border and icon | -| `notification--color` | `$color`: String | Applies given `$color` to left border | - -#### Modifiers - -Use these modifiers with `.bx--inline-notification` class. - -| Selector | Description | -| ---------------------------------------- | -------------------------------------------------------------- | -| `.bx--inline-notification--low-contrast` | Use low contrast variant (The color scheme used until `v10.2`) | -| `.bx--inline-notification--error` | Apply error color to border and icon | -| `.bx--inline-notification--success` | Apply success color to border and icon | -| `.bx--inline-notification--info` | Apply info color to border and icon | -| `.bx--inline-notification--warning` | Apply warning color to border and icon | - -Use these modifiers with `.bx--toast-notification` class. - -| Selector | Description | -| --------------------------------------- | -------------------------------------------------------------- | -| `.bx--toast-notification--low-contrast` | Use low contrast variant (The color scheme used until `v10.2`) | -| `.bx--toast-notification--error` | Apply error color on left border | -| `.bx--toast-notification--success` | Apply success color on left border | -| `.bx--toast-notification--info` | Apply info color on left border | -| `.bx--toast-notification--warning` | Apply warning color on left border | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { Notification } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var Notification = CarbonComponents.Notification; -``` - -#### Instantiating - -```javascript -// `#my-notification` is an element with `[data-notification]` attribute -Notification.create(document.getElementById('my-notification')); -``` - -#### Public Methods - -| Name | Params | Description | -| --------- | ------ | --------------------------------------------------------------------------------- | -| `remove` | | Removes the component, deletes the instance, and removes document event listeners | -| `release` | | Delete the instance | - -##### Example - Removing a notification - -```javascript -// `#my-notification` is an element with `[data-notification]` attribute -notificationInstance = Notification.create( - document.getElementById('my-notification') -); -notificationInstance.remove(); -``` - -#### Options - -| Option | Default Selector | Description | -| ------------------------------- | ---------------------------- | ------------------------------------------------------ | -| `selectorInit` | `[data-notification]` | The selector to find instances of the component | -| `selectorButton` | `[data-notification-btn]` | The selector to find the close button in the component | -| `eventBeforeDeleteNotification` | `notification-before-delete` | Event before deleting the notification | -| `eventAfterDeleteNotification` | `notification-after-delete` | Event after deleting the notification | - -##### Example - Preventing a notification from being removed in a certain condition - -```javascript -document.addEventListener('notification-before-delete', function(evt) { - if (!myApplication.shouldNotificationBeRemoved(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Notifying events of all notifications being removed to an analytics library - -```javascript -document.addEventListener('notification-after-delete', function(evt) { - myAnalyticsLibrary.send({ - action: 'Notification removed', - id: evt.target.id, - }); -}); -``` - -### FAQ - -#### Using aria live regions and alert roles - -Using `role="alert"` is an aggressive call to action that the prompts a screen -reader user to take immediate action on something that changed in the UI. This -is usually reserved for things that are important or time-sensitive like: - -- An invalid value was entered into a form field -- The user's login session is about to expire -- The connection to the server was lost, local changes will not be saved - -Use the alert role sparingly and only in situations where the user's immediate -attention is required. Dynamic changes that are less urgent should use a less -aggressive method, such as `aria-live="polite"` or other live region roles. - -Don't use an alert role on all notifications. - -By default, we recommend that error and warning notifications use -`role="alert"`, while success and info notifications use `aria-live="polite"`. -But as always, this will depend on the urgency of the notification. - -**Sources:** - -- [Use the alert role - MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_alert_role) -- [ARIA Live Regions - MDN](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) diff --git a/packages/components/src/components/notification/migrate-to-7.x.md b/packages/components/src/components/notification/migrate-to-7.x.md deleted file mode 100644 index bbd91445cb59..000000000000 --- a/packages/components/src/components/notification/migrate-to-7.x.md +++ /dev/null @@ -1,65 +0,0 @@ -### HTML - -All notification variations have been condensed into two files -`inline-notification.html` and `toast-notification.html`. - -There are now two data attributes for `notification.js` to target. -`[data-notification]` identifies the component and `[data-notification-btn]` -marks the button to close a notification. - -The majority of the class names have changed along with some structural changes. -The class name changes are documented below. However, probably the easiest way -to migrate to the 7.0 component is just by copy/pasting in the new HTML. - -### SCSS - -The `_notification.scss` is now split in to two files. They are located at -`src/components/notification/_inline-notification.scss` and -`src/components/notification/_toast-notification.scss`. You will need to update -any `@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/notification/_toast-notification.scss'; -@import 'path_to_node_modules/carbon-components/src/components/notification/_inline-notification.scss'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/notification/notification'; -``` - -Quite a few class names have changed. See table below. - -| Old Class | New Class: Inline | New Class: Toast | -| -------------------------------- | --------------------------------------- | -------------------------------------- | -| bx--notification\_\_title | bx--inline-notification\_\_title | bx--toast-notification\_\_title | -| bx--notification\_\_subtitle | bx--inline-notification\_\_subtitle | bx--toast-notification\_\_subtitle | -| bx--notification\_\_caption | N/A | bx--toast-notification\_\_caption | -| bx--notification\_\_close-button | bx--inline-notification\_\_close-button | bx--toast-notification\_\_close-button | -| bx--notification\_\_icon | bx--inline-notification\_\_icon | bx--toast-notification\_\_icon | - -To specify the type of notification you'll add a modifier class. - -`<div class="bx--toast-notification bx--toast-notification--success">` - -Previously this was all handled by one class. - -`<div class="bx--notification-inline--warning">` - -Here are the possible modifiers. - -| bx--inline-notification | bx--toast-notification | -| -------------------------------- | ------------------------------- | -| bx--inline-notification--error | bx--toast-notification--error | -| bx--inline-notification--success | bx--toast-notification--success | -| bx--inline-notification--info | bx--toast-notification--info | -| bx--inline-notification--warning | bx--toast-notification--warning | - -### JavaScript - -New in 7.0 we now have JavaScript to handle closing a notification! As long as -you have the data attributes discussed in the HTML section and the JavaScript is -initialized it'll just work. For more details see the component README file. diff --git a/packages/components/src/components/number-input/README.md b/packages/components/src/components/number-input/README.md deleted file mode 100644 index 406c2052d483..000000000000 --- a/packages/components/src/components/number-input/README.md +++ /dev/null @@ -1,14 +0,0 @@ -### JavaScript - -#### Options - -| Option | Default Selector | Description | -| -------------- | -------------------- | ------------------------------------------ | -| `selectorInit` | `[data-numberinput]` | The CSS selector to find number input HTML | - -#### Events - -| Name | Description | -| -------- | ----------------------------------------------------------------- | -| `click` | Increases and decreases value attribute of number-input | -| `change` | Emitted when click event inceases or decreases number-input value | diff --git a/packages/components/src/components/number-input/migrate-to-7.x.md b/packages/components/src/components/number-input/migrate-to-7.x.md deleted file mode 100644 index 1f224e249e42..000000000000 --- a/packages/components/src/components/number-input/migrate-to-7.x.md +++ /dev/null @@ -1,43 +0,0 @@ -### HTML - -Number Input and other form components now use common form HTML and CSS. See -Form README for details. - -In general, it will be easiest to simply copy and paste the new HTML to replace -older Number Inputs. - -### SCSS - -The `_number-input.scss` file is now located at -`src/components/number-input/_number-input.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/number-input/number-input'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/number-input/number-input'; -``` - -| Old Class | New Class | Note | -| ------------------------- | ---------- | --------- | -| bx--number | bx--number | Unchanged | -| bx--number\_\_arrow | | Removed | -| bx--number\_\_icon | | Removed | -| bx--number\_\_arrow--up | up-icon | Changed | -| bx--number\_\_arrow--down | down-icon | Changed | -| bx--number\_\_input | | Removed | - -### JavaScript - -The `handleClick` method is now a private method, so it has been renamed to -`_handleClick`. The `options` property now only contains a `selectorInit` -key/value pair. The `ie` property in `options` has been removed. In general, the -`NumberInput` class does not check for Internet Explorer browsers and relies on -increasing and decreasing the Number input `value` attribute directly. Changing -the `value` attribute is compatible with all browsers. diff --git a/packages/components/src/components/overflow-menu/README.md b/packages/components/src/components/overflow-menu/README.md deleted file mode 100644 index 2304e875f23c..000000000000 --- a/packages/components/src/components/overflow-menu/README.md +++ /dev/null @@ -1,122 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with .bx--overflow-menu-options class. - -| Selector | Description | -| ---------------------------------- | ------------------------------------------- | -| `.bx--overflow-menu--flip` | Reverse the direction of the overflow menu. | -| `.bx--overflow-menu-options--open` | Displays the overflow menu options. | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { OverflowMenu } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var OverflowMenu = CarbonComponents.OverflowMenu; -``` - -#### Instantiating - -```javascript -// `#my-overflow-menu` is an element with `[data-overflow-menu]` attribute -OverflowMenu.create(document.getElementById('my-overflow-menu')); -``` - -#### Public Methods - -| Name | Params | Description | -| ---------------------- | ----------------- | ------------------------------------------------------------------ | -| `shouldStateBeChanged` | `state`: `String` | Return true if the given state is different from the current state | -| `release` | | Deletes the instance and removes document event listeners | - -#### Options - -| Option | Default Selector | Description | -| ------------------------ | ---------------------------- | --------------------------------------------------------------------------------- | -| `selectorInit` | `[data-overflow-menu]` | The CSS selector to find menu | -| `selectorPlacementScope` | `body` | The CSS selector to find the element you wish the append the menu contents to | -| `selectorOptionMenu` | `.bx--overflow-menu-options` | The CSS selector to find the contents of the menu | -| `objMenuOffset` | `{ top: 3, left: 61 }` | An object containing the top and left offset values in px | -| `objMenuOffsetFlip` | `{ top: 3, left: -61 }` | An object containing the top and left offset values in px for the "flipped" state | - -##### Example - Changing menu position by 8 pixels vertically - -```javascript -// `#my-overflow-menu` is an element with `[data-overflow-menu]` attribute -OverflowMenu.create(document.getElementById('my-overflow-menu'), { - objMenuOffset(menuBody, direction) { - const { objMenuOffset: offset } = OverflowMenu.options; - const { top, left } = - typeof offset !== 'function' ? offset : offset(menuBody, direction); - return { - top: top + 8, - left, - }; - }, -}); -``` - -#### Events - -| Event Name | Description | -| --------------------------- | --------------------------------------------------- | -| 'floating-menu-beingshown' | The custom event fired before the menu gets open. | -| 'floating-menu-shown' | The custom event fired after the menu gets open. | -| 'floating-menu-beinghidden' | The custom event fired before the menu gets closed. | -| 'floating-menu-hidden' | The custom event fired after the menu gets closed. | - -##### Example - Preventing menu from being closed in a certain condition - -```javascript -document.addEventListener('floating-menu-beinghidden', function(evt) { - if (myApplication.shouldMenuKeptOpen(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Notifying events of all overflow menus being closed to an analytics library - -```javascript -document.addEventListener('floating-menu-hidden', function(evt) { - myAnalyticsLibrary.send({ - action: 'Overflow menu closed', - id: evt.target.id, - }); -}); -``` - -### HTML - -By default, the menu body (`ul.bx--overflow-menu-options`) goes right under -`<body>`. To ensure the proper accessibility experience, add -`data-floating-menu-container` to one of the DOM ancestors of the root element -(`div[data-overflow-menu]`). For example, if you have HTML structure like below, -the menu body will go under the second `<div>`: - -```html -<body> - <div> - <div data-floating-menu-container> - <div> - <div data-overflow-menu class="bx--overflow-menu" ...> - ... - <ul class="bx--overflow-menu-options" ...> - ... - </ul> - </div> - </div> - </div> - </div> -</body> -``` diff --git a/packages/components/src/components/overflow-menu/migrate-to-7.x.md b/packages/components/src/components/overflow-menu/migrate-to-7.x.md deleted file mode 100644 index fa5e5d3900c6..000000000000 --- a/packages/components/src/components/overflow-menu/migrate-to-7.x.md +++ /dev/null @@ -1,45 +0,0 @@ -### HTML - -Structure stays the same but some class names have been changed. See below. - -### SCSS - -The `_overflow-menu.scss` file is now located at -`src/components/overflow-menu/_overflow-menu.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/overflow-menu/overflow-menu'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/overflow-menu/overflow-menu'; -``` - -`.bx--overflow-menu__options` is now `.bx--overflow-menu-options` Any `<li>` -inside `.bx--overflow-menu-options` should now have the -`.bx--overflow-menu-options__option` class. `.bx--overflow-menu__btn` is now -`.bx--overflow-menu-options__btn` If you would like to display the menu in the -other direction add `.bx--overflow-menu--flip` to the -`.bx--overflow-menu-options` element. - -### JavaScript - -Initializing new instances of `OverflowMenu` automatically moves the -`.bx--overflow-menu-options` HTML so that it is appended to the `<body>`. It is -then positioned relative to `.bx--overflow-menu`. This will not change the -visual appearance of the component. However this is extremely useful when an -`overflow-menu` is inside a component with `overflow: hidden;` set. A good -example is the `data-table` component. - -If you are targeting `.bx--overflow-menu-options` via it's parent -`.bx--overflow-menu` you'll need to update your code to target the -`.bx--overflow-menu-options` element directly. - -This new functionality gives you a new group of options for the `overflow-menu` -component including scope and offset amount. Full documentation is contained in -the component README file. diff --git a/packages/components/src/components/pagination-nav/README.md b/packages/components/src/components/pagination-nav/README.md deleted file mode 100644 index 01b8c6459e7a..000000000000 --- a/packages/components/src/components/pagination-nav/README.md +++ /dev/null @@ -1,30 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--pagination-nav` class. - -| Selector | Description | -| -------------------------------------- | --------------------------------------------------------------- | -| `.bx--pagination-nav--active` | Applies active styles to page element | -| `.bx--pagination-nav--disabled` | Applies disabled styles to page element when using anchor links | -| `.bx--pagination-nav__page--select` | Applies select override styles to page element | -| `.bx--pagination-nav__page--direction` | Applies previous/next button styles to page element | - -### JavaScript - -#### Options - -| Option | Default Selector | Description | -| ---------------------- | ------------------------------------ | --------------------------------------------------------- | -| `selectorInit` | `[data-pagination-nav]` | The selector to find the pagination nav. | -| `selectorPageElement` | `[data-page]` | The data attribute to find page elements. | -| `selectorPageButton` | `[data-page-button]` | The data attribute to find page ui elements. | -| `selectorPagePrevious` | `[data-page-previous]` | The selector to find the 'previous' ui element. | -| `selectorPageNext` | `[data-page-next]` | The selector to find the 'next' ui element. | -| `selectorPageSelect` | `[data-page-select]` | The selector to find the overflow select element. | -| `selectorPageActive` | `[data-page-active="true"]` | The data attribute to find active page element. | -| `attribPage` | `data-page` | The data attribute key for accessing page number. | -| `attribActive` | `data-page-active` | The data attribute key for accessing active page element. | -| `classActive` | `bx--pagination-nav__page--active` | The CSS class for pages's selected state. | -| `classDisabled` | `bx--pagination-nav__page--disabled` | The CSS class for pages's disabled state. | diff --git a/packages/components/src/components/pagination/README.md b/packages/components/src/components/pagination/README.md deleted file mode 100644 index ddc939bb3d85..000000000000 --- a/packages/components/src/components/pagination/README.md +++ /dev/null @@ -1,31 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--pagination__button` class. - -| Selector | Description | -| ----------------------------------- | ---------------------------------- | -| `.bx--pagination__button--backward` | Applies styles for backward button | -| `.bx--pagination__button--forward` | Applies styles for forward button | -| `.bx--pagination__button--no-index` | Applies styles for disabled button | - -### JavaScript - -#### Options - -| Option | Default Selector | Description | -| --------------------------- | -------------------------- | ---------------------------------------------------------------------------- | -| `selectorInit` | `[data-pagination]` | The selector to find the pagination | -| `selectorItemsPerPageInput` | `[data-items-per-page]` | The selector to find the input that determines the number of items per page. | -| `selectorPageNumberInput` | `[data-page-number-input]` | The selector to find the input that changes the page displayed. | -| `selectorPageBackward` | `[data-page-backward]` | The selector to find the button that goes back a page. | -| `selectorPageForward` | `[data-page-forward]` | The selector to find the button that goes forward a page. | - -#### Events - -| Name | Default Value | Description | -| ------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -| `eventItemsPerPage` | `itemsPerPage` | Custom event fired when a user changes the number of items per page. event.detail.value contains the number of items a user wishes to see. | -| `eventPageNumber` | `pageNumber` | The name of the custom event fired when a user inputs a specific page number. event.detail.value contains the value that the user input. | -| `eventPageChange` | `pageChange` | The name of the custom event fired when a user goes forward or backward a page. event.detail.direction contains the direction a user wishes to go. | diff --git a/packages/components/src/components/pagination/migrate-to-7.x.md b/packages/components/src/components/pagination/migrate-to-7.x.md deleted file mode 100644 index df886db6eb5f..000000000000 --- a/packages/components/src/components/pagination/migrate-to-7.x.md +++ /dev/null @@ -1,29 +0,0 @@ -### HTML - -No changes. - -### SCSS - -The `_pagination.scss` file is now located at -`src/components/pagination/_pagination.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/pagination/pagination'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/pagination/pagination'; -``` - -No class changes. - -### JavaScript - -The `emitEvent` is now a private method and has been renamed to `_emitEvent`. - -The `components` and `options` properties are now declared using `static`. diff --git a/packages/components/src/components/progress-indicator/README.md b/packages/components/src/components/progress-indicator/README.md deleted file mode 100644 index e785ddabf31f..000000000000 --- a/packages/components/src/components/progress-indicator/README.md +++ /dev/null @@ -1,105 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--progress` class. - -| Selector | Description | -| -------------------------------- | ---------------------------------------------- | -| `.bx--progress-step--current` | Applies styles for the current progress-step | -| `.bx--progress-step--incomplete` | Applies styles for an incomplete progress-step | -| `.bx--progress-step--complete` | Applies styles for a complete progress-step | - -### Javascript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { ProgressIndicator } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var ProgressIndicator = CarbonComponents.ProgressIndicator; -``` - -#### Instantiating - -```javascript -// `#my-progress` is an element with `[data-progress]` attribute -ProgressIndicator.create(document.getElementById('my-progress')); -``` - -#### Public Methods - -| Name | Params | Description | -| ------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `getSteps` | | Returns Array of Objects with `element` and `order` key/value pairs. The `element` key contains a step element. The `order` key is what order the step element is, order starts counting from 1 (the first step element) to whatever the last step element is. | -| `getCurrent` | | Returns an Object with data of the current step (`element` and `order` key/value pairs) | -| `setCurrent` | `newCurrentStep`: `Number` | Changes the current step with the given `index` number. (ex. `setCurrent(0)` sets the first step as the current step) | - -##### Example - Changing the current step - -```javascript -// `#my-progress` is an element with `[data-progress]` attribute -var progressIndicatorInstance = ProgressIndicator.create( - document.getElementById('my-progress') -); -// Sets the 2nd step current -progressIndicatorInstance.setCurrent(1); -``` - -- All index numbers less than the current index will be complete -- All index numbers greater than the current index will be incomplete - -#### Options - -| Option | Default Selector | Description | -| --------------------- | -------------------------------- | --------------------------------------------------- | -| `selectorInit` | `[data-progress]` | The selector to find the ProgressIndicator element. | -| `selectorStepElement` | `.bx--progress-step` | The selector to find the step element. | -| `selectorCurrent` | `.bx--progress-step--current` | The selector to find the step current step element. | -| `selectorIncomplete` | `.bx--progress-step--incomplete` | The selector to find incomplete step elements. | -| `selectorComplete` | `.bx--progress-step--complete` | The selector to find complete step elements. | -| `classStep` | `bx--progress-step` | ClassName for step element | -| `classCompleteStep` | `bx--progress-step--complete` | ClassName for complete step element | -| `classIncompleteStep` | `bx--progress-step--incomplete` | ClassName for incomplete step element | -| `classCurrent` | `bx--progress-step--current` | ClassName for current step element | - -#### Classes - -| Name | Description | -| ------------------------------- | ---------------------------------------- | -| `bx--progress-step` | The class for a step element | -| `bx--progress-step--complete` | The class for a complete step element | -| `bx--progress-step--incomplete` | The class for an incomplete step element | -| `bx--progress-step--current` | The class for a current step element | - -### FAQ - -#### Adding or removing Progress steps - -Once `ProgressIndicator` instance is initialized, simply add or remove Progress -steps in the HTML. The JavaScript will automatically accommodate for any number -of steps. A Progress step in HTML looks like this: - -```html -<li class="bx--progress-step bx--progress-step--complete"> - <svg width="24px" height="24px" viewBox="0 0 24 24"> - <circle cx="12" cy="12" r="12"></circle> - <polygon - points="10.3 13.6 7.7 11 6.3 12.4 10.3 16.4 17.8 9 16.4 7.6" - ></polygon> - </svg> - <p class="bx--progress-label">Label 1</p> - <span class="bx--progress-line"></span> -</li> -``` - -Note that each progress step will need a modifier class. In the example above, -it is `bx--progress-step--complete`, but the JavaScript will set this to the -appropriate modifier class relative to the current step as indicated by -`bx--progress-step--incomplete`. diff --git a/packages/components/src/components/progress-indicator/experimental.md b/packages/components/src/components/progress-indicator/experimental.md deleted file mode 100644 index 3baad90a96b0..000000000000 --- a/packages/components/src/components/progress-indicator/experimental.md +++ /dev/null @@ -1,139 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--progress` class. - -| Selector | Description | -| ------------------------------ | ---------------------------------------------- | -| .bx--progress-step--current | Applies styles for the current progress-step | -| .bx--progress-step--incomplete | Applies styles for an incomplete progress-step | -| .bx--progress-step--complete | Applies styles for a complete progress-step | - -### Javascript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { ProgressIndicator } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var ProgressIndicator = CarbonComponents.ProgressIndicator; -``` - -#### Instantiating - -```javascript -// `#my-progress` is an element with `[data-progress]` attribute -ProgressIndicator.create(document.getElementById('my-progress')); -``` - -#### Public Methods - -| Name | Params | Description | -| ------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| getSteps | | Returns Array of Objects with `element` and `order` key/value pairs. The `element` key contains a step element. The `order` key is what order the step element is, order starts counting from 1 (the first step element) to whatever the last step element is. | -| getCurrent | | Returns an Object with data of the current step (`element` and `order` key/value pairs) | -| setCurrent | newCurrentStep: `Number` | Changes the current step with the given `index` number. (ex. `setCurrent(0)` sets the first step as the current step) | -| addOverflowTooltip | | Adds an overflow class that displays the tooltip if step label is truncated | - -##### Example - Changing the current step - -```javascript -// `#my-progress` is an element with `[data-progress]` attribute -var progressIndicatorInstance = ProgressIndicator.create( - document.getElementById('my-progress') -); -// Sets the 2nd step current -progressIndicatorInstance.setCurrent(1); -``` - -- All index numbers less than the current index will be complete -- All index numbers greater than the current index will be incomplete - -#### Options - -| Option | Default Selector | Description | -| --------------------- | -------------------------------- | ----------------------------------------------------------- | -| `selectorInit` | `[data-progress]` | The selector to find the ProgressIndicator element | -| `selectorStepElement` | `.bx--progress-step` | The selector to find the step element | -| `selectorCurrent` | `.bx--progress-step--current` | The selector to find the step current step element | -| `selectorIncomplete` | `.bx--progress-step--incomplete` | The selector to find incomplete step elements | -| `selectorComplete` | `.bx--progress-step--complete` | The selector to find complete step elements | -| `selectorLabel` | `.bx---progress-label` | The selector to find all label elements | -| `selectorTooltip` | `.bx----tooltip` | The selector to find all tooltip elements | -| `selectorTooltipText` | `.bx--tooltip__text` | The selector to find the child text of each tooltip | -| `classStep` | `bx--progress-step` | ClassName for step element | -| `classCurrent` | `bx--progress-step--current` | ClassName for current step element | -| `classComplete` | `bx--progress-step--complete` | ClassName for complete step element | -| `classIncomplete` | `bx--progress-step--incomplete` | ClassName for incomplete step element | -| `classOverflowLabel` | `bx--progress-label-overflow` | ClassName for current step element | -| `classTooltipMulti` | `bx--tooltip_multi` | ClassName for multi line tooltip element | -| `maxWidth` | `81` | The max width of a step label before it's truncated | -| `tooltipMinHeight` | `21` | The max height before a tooltip is given a multi line class | - -#### Classes - -| Name | Description | -| ------------------------------- | ---------------------------------------- | -| `bx--progress-step` | The class for a step element | -| `bx--progress-step--complete` | The class for a complete step element | -| `bx--progress-step--incomplete` | The class for an incomplete step element | -| `bx--progress-step--current` | The class for a current step element | - -### FAQ - -#### Adding or removing Progress steps - -Once `ProgressIndicator` instance is initialized, simply add or remove Progress -steps in the HTML. The JavaScript will automatically accommodate for any number -of steps. A Progress step with an overflow tooltip and optional helper text in -HTML looks like this: - -```html -<li class="bx--progress-step bx--progress-step--complete"> - <svg - focusable="false" - preserveAspectRatio="xMidYMid meet" - xmlns="http://www.w3.org/2000/svg" - width="16" - height="16" - viewBox="0 0 16 16" - aria-hidden="true" - > - <path - d="M8 1C4.1 1 1 4.1 1 8s3.1 7 7 7 7-3.1 7-7-3.1-7-7-7zm0 13c-3.3 0-6-2.7-6-6s2.7-6 6-6 6 2.7 6 6-2.7 6-6 6z" - ></path> - <path d="M7 10.8L4.5 8.3l.8-.8L7 9.2l3.7-3.7.8.8z"></path> - </svg> - <p - tabindex="0" - class="bx--progress-label bx--progress-label-overflow" - aria-describedby="label-tooltip" - > - Overflow Example First step - </p> - <div - id="label-tooltip" - role="tooltip" - data-floating-menu-direction="bottom" - class="bx--tooltip bx--tooltip_multi" - data-avoid-focus-on-open - > - <span class="bx--tooltip__caret"></span> - <p class="bx--tooltip__text">Overflow Example First Step</p> - </div> - <p class="bx--progress-optional">Optional Helper Text</p> - <span class="bx--progress-line"></span> -</li> -``` - -Note that each progress step will need a modifier class. In the example above, -it is `bx--progress-step--complete`, but the JavaScript will set this to the -appropriate modifier class relative to the current step as indicated by -`bx--progress-step--incomplete`. diff --git a/packages/components/src/components/progress-indicator/migrate-to-7.x.md b/packages/components/src/components/progress-indicator/migrate-to-7.x.md deleted file mode 100644 index e66efb2e69eb..000000000000 --- a/packages/components/src/components/progress-indicator/migrate-to-7.x.md +++ /dev/null @@ -1,46 +0,0 @@ -### HTML - -Most of the changes to HTML pertain mainly to class changes. See SCSS for -details. - -SVGs representing incomplete, complete and current steps now rely on inline SVGs -and not bluemix-icons. The JavaScript for ProgressIndicator needs to remove and -inject SVG data into HTML to represent visual state of the component. Relying on -`xlink:href` is not consistent enough to be sustainable for how -`ProgressIndicator` is used. - -### SCSS - -The `_progress-indicator.scss` file is now located at -`src/components/progress-indicator/_progress-indicator.scss`. You will need to -update any `@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/progress-indicator/progress-indicator'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/progress-indicator/progress-indicator'; -``` - -| Old Class | New Class | Note | -| ---------------------------------------- | ----------------------------- | --------- | -| bx--progress-indicator | bx--progress | Changed | -| bx--progress-indicator\_\_step | | Unchanged | -| bx--progress-indicator\_\_step--complete | bx--progress-step--complete | Changed | -| | bx--progress-step--incomplete | Added | -| bx--progress-indicator\_\_step--active | bx--progress-step--current | Changed | -| bx--progress-indicator\_\_icon | | Removed | -| bx--progress-indicator\_\_label | bx--progress-label | Changed | - -### JavaScript - -The `ProgressIndicator` class should be used to initialize the component -instance. Previously, this component was not needed but it was decided that -having automatic state changes would make the experience of implementing this -component easier for the developer. State specifically means pertains to the -automatic setting of CSS modifier classes to represent visual state. diff --git a/packages/components/src/components/radio-button/README.md b/packages/components/src/components/radio-button/README.md deleted file mode 100644 index 1772e4017947..000000000000 --- a/packages/components/src/components/radio-button/README.md +++ /dev/null @@ -1,8 +0,0 @@ -### FAQ - -#### Using fieldset and legend - -It's a best practice to use fieldset and legend when composing HTML for radio -buttons. Unlike checkboxes, radio buttons should always be grouped. - -See Form for more details. diff --git a/packages/components/src/components/radio-button/migrate-to-7.x.md b/packages/components/src/components/radio-button/migrate-to-7.x.md deleted file mode 100644 index d23ae1935aad..000000000000 --- a/packages/components/src/components/radio-button/migrate-to-7.x.md +++ /dev/null @@ -1,19 +0,0 @@ -### HTML - -### SCSS - -The `_radio-button.scss` file is now located at -`src/components/radio-button/_radio-button.scss`. You'll need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/radio-button/radio-button'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/radio-button/radio-button'; -``` diff --git a/packages/components/src/components/search/FAQ.md b/packages/components/src/components/search/FAQ.md deleted file mode 100644 index 89f6f6fd4724..000000000000 --- a/packages/components/src/components/search/FAQ.md +++ /dev/null @@ -1,24 +0,0 @@ -# FAQ - -## Table of Contents - -<!-- To run doctoc, just do `npx doctoc FAQ.md` in this directory! --> - -<!-- START doctoc generated TOC please keep comment here to allow auto update --> -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> - -- [Why is the clear icon a button?](#why-is-the-clear-icon-a-button) -- [The close icon isn't tab-able in Safari](#the-close-icon-isnt-tab-able-in-safari) - -<!-- END doctoc generated TOC please keep comment here to allow auto update --> - -## Why is the clear icon a button? - -The clear icon has been updated to use a `button` in order to be tab-able by -various browsers. If the icon is just an SVG target, than unfortunately some -screen readers may not be able to access it during the normal control flow. - -## The close icon isn't tab-able in Safari - -In order to tab to the close icon in an input in Safar, you'll have to use -`<Option><Tab>` instead of the standard `<Tab>` keystroke. diff --git a/packages/components/src/components/search/README.md b/packages/components/src/components/search/README.md deleted file mode 100644 index 234f461dc969..000000000000 --- a/packages/components/src/components/search/README.md +++ /dev/null @@ -1,34 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--search` class. - -| Name | Description | -| -------------------- | -------------------------------------------- | -| `.bx--search--sm` | Selector for applying small search styles | -| `.bx--search--lg` | Selector for applying medium search styles | -| `.bx--search--xl` | Selector for applying standard search styles | -| `.bx--search--light` | Selector for applying light search styles | - -### JavaScript - -#### Public Methods - -| Name | Params | Description | -| -------------- | ----------------------------------- | ---------------------------------------- | -| `toggleLayout` | `element`: `Object` | Toggles between the grid and list layout | -| `showClear` | `value`: `String`, `icon`: `Object` | Toggles the clear icon visibility | -| `release` | | Deletes the instance | - -#### Options - -| Option | Default Selector | Description | -| ----------------------- | ---------------------------------------- | ----------------------------------------------------------- | -| `selectorInit` | `[data-search]` | The selector to find the Search element. | -| `selectorSearchView` | `[data-search-view]` | The selector to find the search view icon containers. | -| `selectorSearchInput` | `.bx--search-input` | The selector to find the search input. | -| `selectorClearIcon` | `.bx--search-close` | The selector for the clear icon that clears the search box. | -| `selectorIconContainer` | `.bx--search-button[data-search-toggle]` | The data attribute selector for the icon layout container. | -| `classClearHidden` | `bx--search-close--hidden` | The class used to hide the clear icon. | -| `classLayoutHidden` | `bx--search-view--hidden` | The class used to hide the non-selected layout view. | diff --git a/packages/components/src/components/search/migrate-to-7.x.md b/packages/components/src/components/search/migrate-to-7.x.md deleted file mode 100644 index f6032d112423..000000000000 --- a/packages/components/src/components/search/migrate-to-7.x.md +++ /dev/null @@ -1,39 +0,0 @@ -### HTML - -The new HTML is structurally the same. However, we've now added the -`[data-search]` attribute. This allows the component's JavaScript to function. -In addition a few class names have been changed slightly. See below. - -### SCSS - -The `_search.scss` file is now located at `src/components/search/_search.scss`. -You'll need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/search/search'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/search/search'; -``` - -| Old Class | New Class | Note | -| ----------------------------- | ------------------------- | ------- | -| bx--search\_\_icon--magnifier | bx--search--magnifier | Changed | -| bx--search\_\_label | bx--label | Changed | -| bx--search\_\_input | bx--search-input | Changed | -| | bx--search--lg | Added | -| | bx--search--close | Added | -| | bx--search--close--hidden | Added | -| | bx--search-button | Added | -| | bx--search-view--hidden | Added | - -### JavaScript - -The search component now has JavaScript! Make sure you've added the -`[data-search]` attribute for it to work. diff --git a/packages/components/src/components/select/README.md b/packages/components/src/components/select/README.md deleted file mode 100644 index b2c51a4a798e..000000000000 --- a/packages/components/src/components/select/README.md +++ /dev/null @@ -1,50 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--select` class. - -| Name | Description | -| --------------------- | ------------------------------------------ | -| `.bx--select--inline` | Selector for applying inline select styles | -| `.bx--select--light` | Selector for applying light select styles | - -#### Inline Select width - -The width of the inline select box should be the width of the default -placeholder text + 16px/1rem of padding. There should be 10px of padding between -the placeholder text and the caret. - -#### Using Form Validation - -Carbon Components provides HTML attributes and CSS to enable form validation for -each input or control. - -For example, here's a **Select** that provides a message if an option is not -selected. - -```html -<div class="bx--form-item"> - <div class="bx--select"> - <select data-invalid id="select-id" class="bx--select-input" - >...</select - > - ... - </div> - <svg - class="bx--select__arrow" - width="10" - height="5" - viewBox="0 0 10 5" - fill-rule="evenodd" - > - <path d="M10 0L5 5 0 0z"></path> - </svg> - <label for="select-id" class="bx--label">Select</label> - <div class="bx--form-requirement">Please select an option.</div> -</div> -``` - -The `bx--form-requirement` element will be hidden until `data-invalid` attribute -gets added to the `select` child of `bx--select`. Validate the select on your -own and then use JavaScript to add the attribute if the select value is invalid. diff --git a/packages/components/src/components/select/migrate-to-7.x.md b/packages/components/src/components/select/migrate-to-7.x.md deleted file mode 100644 index f1a24d98011f..000000000000 --- a/packages/components/src/components/select/migrate-to-7.x.md +++ /dev/null @@ -1,28 +0,0 @@ -### HTML - -No changes. - -### SCSS - -The `_select.scss` file is now located at `src/components/select/_select.scss`. -You will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/select/select'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/select/select'; -``` - -Quite a few class names have changed. See table below. - -| Old Class | New Class | Note | -| ---------------------- | ------------------- | ------- | -| bx--select\_\_optgroup | bx--select-optgroup | Changed | -| bx--select\_\_option | bx--select-option | Changed | diff --git a/packages/components/src/components/slider/README.md b/packages/components/src/components/slider/README.md deleted file mode 100644 index 1b0d0fd80fe2..000000000000 --- a/packages/components/src/components/slider/README.md +++ /dev/null @@ -1,36 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--slider` class. - -| Selector | Description | -| --------------------- | ------------------------------------------------------------------- | -| .bx--slider--disabled | Applies disabled styling and prevents JS from running on user input | - -### Javascript - -#### Options - -| Option | Default Selector | Description | -| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------- | -| `selectorInit` | `[data-slider]` | The selector to find the Slider element. | -| `selectorTrack` | `.bx--slider__track` | The selector to find the Slider track element. | -| `selectorFilledTrack` | `.bx--slider__filled-track` | The selector to find the Slider filled track element. | -| `selectorThumb` | `.bx--slider__thumb` | The selector to find the Slider thumb element. | -| `selectorInput` | `.bx--slider__input` | The selector to find the Slider input element. | -| `eventBeforeSliderValueChange` | `slider-before-value-change` | The event emitted before the Slider value changes. | -| `eventAfterSliderValueChange` | `slider-after-value-change` | The event emitted when the Slider value changes. | -| `stepMultiplier` | `4` | The multiplier applied to arrow key inputs when the shift key is pressed. | - -### FAQ - -#### Keydown event - -Once `Slider` instance is initialized a user can use the following keys to -control the slider. - -- `up` and `right` arrow keys increase the slider value by one step -- `down` and `left` arrow keys decrease the slider value by one step -- Pressing `shift` while changing the value of the slider will multiple the - change by `Slider.options.stepMultiplier` (the default is 4) diff --git a/packages/components/src/components/structured-list/README.md b/packages/components/src/components/structured-list/README.md deleted file mode 100644 index 6f09d700b8b6..000000000000 --- a/packages/components/src/components/structured-list/README.md +++ /dev/null @@ -1,94 +0,0 @@ -### SCSS - -#### Variables - -All configurable variables are located in -[src/globals/scss/\_vars.scss](https://github.com/IBM/carbon-components/blob/master/src/globals/scss/_vars.scss) - -| name | description | -| -------------------------- | ----------------------------------------------------------------------------------------- | -| `$structured-list-padding` | Set padding value for structured-list. This will change gutter sizes between table cells. | - -#### Mixins - -Mixins specific to structured-list are located in -[src/components/structured-list/\_mixins.scss](https://github.com/IBM/carbon-components/blob/master/src/components/structured-list/_mixins.scss). -All mixins listed below take an optional `$padding` parameter. Default value for -`$padding` is equal to `$structured-list-padding: 2rem !default;`, which can be -overwritten. - -| name | params | description | -| ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `padding-td--condensed` | `$padding` | Customizes padding when `.bx--structured-list--condensed` modifier class is used. Default padding is the value of `$structured-list-padding` (`2rem`). | -| `padding--data-structured-list` | `$padding` | Customizes padding. Only used when `[data-structured-list]` attribute is on HTML indicating that this component uses `<input type="radio">` controls. | -| `padding-td` | `$padding` | Customizes padding for `.bx--structured-list-td` | -| `padding-th` | `$padding` | Customizes padding for `.bx--structured-list-th` | - -#### Modifiers - -Use these modifiers with `.bx--structured-list` class. - -| Selector | Description | -| -------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -| `.bx--structured-list--border` | Applies border around structured-list and white background-color | -| `.bx--structured-list--condensed` | Applies condensed styles for all body rows | -| `.bx--structured-list-content--nowrap` | Applies `white-space: nowrap;` on content. Prevents titles from wrapping in small viewports. | -| `.bx--structured-list--selection` | Applies styles used for selection variant of structured-list. | -| `.bx--structured-list-row--selected` | Applies modifier class to label row. This changes the background color to indicate that the row is selected. | - -Use these modifiers with `.bx--structured-list-td` class. - -| Selector | Description | -| -------------------------------------- | ----------------------------------------- | -| `.bx--structured-list-content--nowrap` | Applies `white-space: nowrap;` on content | - -### Javascript - -#### Options - -| Option | Default Selector | Description | -| --------------------- | ----------------------------------------------------- | ------------------------------------------------ | -| `selectorInit` | `[data-structured-list]` | The selector to find the StructuredList element. | -| `selectorStepElement` | `.bx--structured-list-tbody .bx--structured-list-row` | The selector to find the step element. | -| `classActive` | `'bx--structured-list-row--selected'` | The class to indicate a selected row | - -### FAQ - -#### Keydown event - -Once `StructuredList` instance is initialized, use -[structured-list--selection.html](https://github.com/IBM/carbon-components/blob/master/src/components/structured-list/structured-list--selection.html) -and users will be able to make row selections with keyboard similar to radio -buttons. - -- `up` and `down` arrow keys for navigation (focus and select) -- `tab` and `shift + tab` for navigation (focus only) -- `enter` and `space` for selecting - -**Chrome**: `up` and `down` arrow keys will set `focus` on `<label>` elements -and associated `<input type="radio">` will recieve `checked` attribute via -`StructuredList` JavaScript. - -**Firefox**: `up` and `down` arrows keys will set focus on -`<input type="radio">` through the associated `<label>` and will only set the -`checked` attribute on the input. Arrow keys will not set focus on the -`<label>`. - -#### Add visual styles to text - -You can add text to each cell in a structured-list. Use CSS to add visual styles -to text. - -**HTML** - -```html -<div class="bx--structured-list-td bold">Apache Spark</div> -``` - -**CSS** - -```css -.bold { - font-weight: 700; -} -``` diff --git a/packages/components/src/components/tabs/README.md b/packages/components/src/components/tabs/README.md deleted file mode 100644 index 5a70c743583a..000000000000 --- a/packages/components/src/components/tabs/README.md +++ /dev/null @@ -1,96 +0,0 @@ -### SCSS - -#### Modifiers - -Modifiers are used with various classes for Tabs. - -| Name | Description | -| ------------------------------- | ------------------------------------------------------------------------ | -| `.bx--tabs__nav--hidden` | Applies specific styles to hide the narrow tab menu options | -| `.bx--tabs__nav-item--selected` | Applies specific styles to the currently selected tab item | -| `.bx--tabs--light` | Selector for applying light dropdown styles when tabs are in mobile view | - -### JavaScript - -#### Getting component class reference - -##### ES2015 - -```javascript -import { Tab } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var Tab = CarbonComponents.Tab; -``` - -#### Instantiating - -```javascript -// `#my-tabs` is an element with `[data-tabs]` attribute -Tabs.create(document.getElementById('my-tabs')); -``` - -#### Public Methods - -| Name | Params | Description | -| ----------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `setActive` | `item`: `HTMLElement`, `callback`: `Function` | Uses `data-target` attribute to show a content panel using the given CSS selector. Non-active targets will be hidden. You can also pass in an optional callback function, see FAQ in Content Switcher for details | -| `release` | | Deletes the instance and removes document event listeners | - -##### Example - Changing the active item - -```javascript -// `#my-tabs` is an element with `[data-tabs]` attribute -var tabsInstance = Tabs.create(document.getElementById('my-tabs')); -// `#my-tab-item-1` is one of the `<li>`s with `bx--tabs__nav-item` class -tabsInstance.setActive(document.getElementById('my-tab-item-1')); -``` - -#### Options - -| Option | Default Selector | Description | -| ------------------------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------- | -| `selectorInit` | `[data-tabs]` | The CSS selector to find tab containers | -| `selectorMenu` | `.bx--tabs__nav` | The CSS selector to find the drop down menu used in narrow mode | -| `selectorTrigger` | `.bx--tabs-trigger` | The CSS selector to find the button to open the drop down menu used in narrow mode | -| `selectorTriggerText` | `.bx--tabs-trigger-text` | The CSS selector to find the element used in narrow mode showing the selected tab item | -| `selectorButton` | `.bx--tabs__nav-item` | The CSS selector to find tab containers | -| `selectorButtonEnabled` | `.bx--tabs__nav-item:not(.bx--tabs__nav-item--disabled)` | The CSS selector to find tab containers that are not disabled | -| `selectorButtonSelected` | `.bx--tabs__nav-item--selected` | The CSS selector to find the selected tab | -| `selectorLink` | `.bx--tabs__nav-link` | The CSS selector to find the links in tabs | -| `classActive` | `bx--tabs__nav-item--selected` | The CSS class for tab's selected state | -| `classHidden` | `bx--tabs__nav--hidden` | The CSS class for the drop down menu's hidden state used in narrow mode | -| `classOpen` | `bx--tabs-trigger--open` | The CSS class for the drop down menu motion on open and close | -| `eventBeforeSelected` | `tab-beingselected` | The name of the custom event fired before a tab is selected | -| `eventAfterSelected` | `tab-selected` | The name of the custom event fired after a tab is selected | - -#### Events - -| Event Name | Description | -| ------------------- | --------------------------------------------------------------------------------------------------------------- | -| `tab-beingselected` | The name of the custom event fired before a tab is selected. Cancellation of this event stops selection of tab. | -| `tab-selected` | The name of the custom event fired after a tab is selected | - -##### Example - Preventing a tab from being selected in a certain condition - -```javascript -document.addEventListener('tab-beingselected', function(evt) { - if (!myApplication.shouldTabItemBeSelected(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Notifying events of all tab items being selected to an analytics library - -```javascript -document.addEventListener('tab-selected', function(evt) { - myAnalyticsLibrary.send({ - action: 'Tab selected', - id: evt.target.id, - }); -}); -``` diff --git a/packages/components/src/components/tabs/migrate-to-7.x.md b/packages/components/src/components/tabs/migrate-to-7.x.md deleted file mode 100644 index fb72f9b30806..000000000000 --- a/packages/components/src/components/tabs/migrate-to-7.x.md +++ /dev/null @@ -1,27 +0,0 @@ -### HTML - -No changes. - -### SCSS - -The `_tabs.scss` file is now located at `src/components/tabs/_tabs.scss`. You -will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/tabs/tabs'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/tabs/tabs'; -``` - -No class changes. - -### JavaScript - -All methods for Tab class have been changed to private methods. diff --git a/packages/components/src/components/tag/README.md b/packages/components/src/components/tag/README.md deleted file mode 100644 index e7e415fbe0f4..000000000000 --- a/packages/components/src/components/tag/README.md +++ /dev/null @@ -1,9 +0,0 @@ -### SCSS - -#### Mixins - -Mixins specific to tag are located in [src/components/tag/\_mixins.scss](). - -| Name | Params | Description | -| ----------- | -------------------------- | ------------------------------------------ | -| `tag-theme` | `$bg-color`, `$text-color` | Adds given background-color and text color | diff --git a/packages/components/src/components/tag/migrate-to-7.x.md b/packages/components/src/components/tag/migrate-to-7.x.md deleted file mode 100644 index 2f419e4bcc55..000000000000 --- a/packages/components/src/components/tag/migrate-to-7.x.md +++ /dev/null @@ -1,34 +0,0 @@ -### HTML - -HTML has not changed except for class attributes. See SCSS for more details. - -### SCSS - -The `_tag.scss` file is now located at `src/components/tag/_tag.scss`. You will -need to update any `@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/tag/tag'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/tag/tag'; -``` - -| Old Class | New Class | Note | -| ----------------- | --------------------- | ------- | -| | bx--tag | Added | -| tag--ibm | bx--tag--ibm | Changed | -| tag--beta | bx--tag--beta | Changed | -| tag--third-party | bx--tag--third-party | Changed | -| tag--local | bx--tag--local | Changed | -| tag--dedicated | bx--tag--dedicated | Changed | -| tag--custom | bx--tag--custom | Changed | -| tag--experimental | bx--tag--experimental | Changed | -| tag--community | bx--tag--community | Changed | -| tag--private | bx--tag--private | Changed | -| tag--deprecated | | Removed | diff --git a/packages/components/src/components/text-area/README.md b/packages/components/src/components/text-area/README.md deleted file mode 100644 index 3fb2144ccb5f..000000000000 --- a/packages/components/src/components/text-area/README.md +++ /dev/null @@ -1,6 +0,0 @@ -### FAQ - -#### Using Form Requirement with Text Area - -All form elements use the same HTML and CSS for enabling form requirements and -validations. diff --git a/packages/components/src/components/text-area/migrate-to-7.x.md b/packages/components/src/components/text-area/migrate-to-7.x.md deleted file mode 100644 index ece3a63a2698..000000000000 --- a/packages/components/src/components/text-area/migrate-to-7.x.md +++ /dev/null @@ -1,26 +0,0 @@ -### HTML - -Text Area and other form components now make use of common form HTML and CSS. -See form README for details. - -### SCSS - -The `_text-area.scss` file is now located at -`src/components/text-area/_text-area.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/text-area/text-area'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/text-area/text-area'; -``` - -| Old Class | New Class | Note | -| --------------------- | ------------- | ------- | -| bx--textarea\_\_input | bx--text-area | Changed | diff --git a/packages/components/src/components/text-input/README.md b/packages/components/src/components/text-input/README.md deleted file mode 100644 index ea060d70f933..000000000000 --- a/packages/components/src/components/text-input/README.md +++ /dev/null @@ -1,33 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--form-item[data-text-input]` class. - -| Default Selector | Description | -| ---------------------------------- | --------------------------------------------------------- | -| `.bx--text-input-password-visible` | The className for a password field that is revealing text | - -### JavaScript - -#### Public Methods - -| Name | Params | Description | -| --------- | ------ | -------------------- | -| `release` | | Deletes the instance | - -#### Options - -| Option | Default Selector | Description | -| ----------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- | -| `selectorInit` | `[data-text-input]` | The selector to find the text input form groups | -| `selectorPasswordField` | `.bx--text-input[data-toggle-password-visibility]` | The selector to find the input field | -| `selectorPasswordVisibilityButton` | `.bx--text-input--password__visibility__toggle` | The selector to find the password visibility toggle | -| `selectorPasswordVisibilityTooltip` | `.bx--text-input--password__visibility__toggle > .bx--assistive-text` | The selector to find the password visibility toggle tooltip | -| `passwordIsVisible` | `.bx--text-input--password-visible` | The className for a field with visible passwords | - -#### Classes - -| Default Selector | Description | -| ---------------------------------- | --------------------------------------------------------- | -| `.bx--text-input-password-visible` | The className for a password field that is revealing text | diff --git a/packages/components/src/components/text-input/migrate-to-7.x.md b/packages/components/src/components/text-input/migrate-to-7.x.md deleted file mode 100644 index 1e2b8cd9142c..000000000000 --- a/packages/components/src/components/text-input/migrate-to-7.x.md +++ /dev/null @@ -1,40 +0,0 @@ -### HTML - -Text Input and all other form components now require the use of labels and form -validations that come from the Form component. - -```html -<div class="bx--form-item"> - <label for="text-input-1" class="bx--label">Text field label</label> - <input - id="text-input-1" - type="text" - class="bx--text-input" - placeholder="Hint text here" - /> -</div> -``` - -See Forms for more details on using labels and form validation. - -### SCSS - -The `_text-input.scss` file is now located at -`src/components/text-input/_text-input.scss`. You will need to update any -`@import` statements for this file to reflect this change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/text-input/text-input'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/text-input/text-input'; -``` - -| Old Class | New Class | Note | -| ----------------- | -------------- | ------- | -| bx--text\_\_input | bx--text-input | Changed | diff --git a/packages/components/src/components/tile/README.md b/packages/components/src/components/tile/README.md deleted file mode 100644 index 4adbc6878061..000000000000 --- a/packages/components/src/components/tile/README.md +++ /dev/null @@ -1,63 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--tile` class. - -| Selector | Description | -| ----------------------- | ------------------------------------------------------------------------ | -| `.bx--tile--clickable` | Adds specific styles and custom focus/hover states for a clickable tile | -| `.bx--tile--expandable` | Adds specific styles and custom focus/hover states for a expandable tile | -| `.bx--tile--selectable` | Adds specific styles and custom focus/hover states for a selectable tile | - -### Javascript - -#### Options - -| Option | Default Selector | Description | -| ---------------------- | ------------------------ | ------------------------------------------------------------------------------ | -| `selectorInit` | `[data-tile]` | The selector to find the Tile element. | -| `selectorAboveTheFold` | `[data-tile-atf]` | The selector to find the above the fold content for a expandable Tile element. | -| `selectorTileInput` | `[data-tile-input]` | The selector to find the input field in a selectable Tile element. | -| `classExpandedTile` | `.bx--tile--is-expanded` | The CSS modifier class triggered when a tile is expanded | -| `classClickableTile` | `.bx--tile--is-clicked` | The CSS modifier class triggered when a tile is clicked | -| `classSelectableTile` | `.bx--tile--is-selected` | The CSS modifier class triggered when a tile is selected | - -### Tile types - -#### Expandable Tiles - -The expandable tile consists of two content container, one for the above the -fold content and one for the below the fold content. Place the content you want -to be displayed in the tile before it is expanded in the above the fold -container, and the content that is to be revealed when a tile is expnaded in the -below the fold container. The JavaScript attached to the expandable tile will -automatically calculate the height needed to display both containers. - -```html -<div data-tile="expandable" class="bx--tile bx--tile--expandable" tabindex="0"> - <button class="bx--tile__chevron"> - <svg width="12" height="8" viewBox="0 0 12 8" fill-rule="evenodd"> - <path d="M10.6 0L6 4.7 1.4 0 0 1.4l6 6.1 6-6.1z"></path> - </svg> - </button> - <div class="bx--tile-content"> - <span data-tile-atf class="bx--tile-content__above-the-fold"> - <!-- Above the fold content here --> - </span> - <span class="bx--tile-content__below-the-fold"> - <!-- Rest of the content here --> - </span> - </div> -</div> -``` - -#### Selectable Tiles - -The selectable tile includes a hidden checkbox input element, and the value of -the selected tile can be obtained using the same method as with any other -checkbox element. - -#### Clickable Tiles - -The clickable tile is an anchor tag. diff --git a/packages/components/src/components/time-picker/README.md b/packages/components/src/components/time-picker/README.md deleted file mode 100644 index 761a5e6147e4..000000000000 --- a/packages/components/src/components/time-picker/README.md +++ /dev/null @@ -1,26 +0,0 @@ -### FAQ - -The Time Picker consists of a mandatory input field and two optional -[Inline Select](http://carbondesignsystem.com/components/select/code) -components. The Inline Select components are only used when the user is required -to select either a time zone and/or when specifying AM/PM is required. - -The Time Picker uses form validation, and the valid pattern should be specified -in the pattern attribute of the input field. You can read more about patterns -[here](https://www.w3schools.com/tags/att_input_pattern.asp). - -Here are some examples: - -#### 24-hour military time - -`<input type="text" class="bx--time-picker__input-field" pattern="[01]?[0-9]|2[0-3]):[0-5][0-9]" placeholder="hh:mm" maxlength="5" />` - -#### 12-hour am-pm clock - -`<input type="text" class="bx--time-picker__input-field" pattern="(1[012]|[1-9]):[0-5][0-9](\\s)?" placeholder="hh:mm" maxlength="5" />` - -#### Localization - -In order for the component to be localized, please make sure you update the -validation pattern, the AM/PM select component (if it is needed), and the time -zone select component (if it is needed). diff --git a/packages/components/src/components/toggle/README.md b/packages/components/src/components/toggle/README.md deleted file mode 100644 index c67ed1927d08..000000000000 --- a/packages/components/src/components/toggle/README.md +++ /dev/null @@ -1,21 +0,0 @@ -### SCSS - -#### Modifiers - -Use these modifiers with `.bx--toggle` class. - -| Selector | Description | -| -------------------------- | ----------------------------------------- | -| `.bx--toggle-input--small` | Selector for applying small toggle styles | - -### FAQ - -#### Best practice - -`.bx--toggle-input__label` must always have a value for the `aria-label` -attribute. This makes it visible to screen readers. - -The `.bx--toggle__text--off` and `.bx--toggle__text--on` elements are completely -optional. If they are present, they can be hidden from screen readers with -`aria-hidden="true"` since the `checked` state of the checkbox will indicate -this information already. diff --git a/packages/components/src/components/toggle/migrate-to-7.x.md b/packages/components/src/components/toggle/migrate-to-7.x.md deleted file mode 100644 index 11e0c57c4851..000000000000 --- a/packages/components/src/components/toggle/migrate-to-7.x.md +++ /dev/null @@ -1,23 +0,0 @@ -### HTML - -Toggle and other form components are wrapped with the `.bx--form-item` element. - -### SCSS - -The `_toggle.scss` file is now located at `src/components/toggle/_toggle.scss`. -You will need to update any `@import` statements for this file to reflect this -change. - -**New**: - -```scss -@import 'path_to_node_modules/carbon-components/src/components/toggle/toggle'; -``` - -**Old**: - -```scss -@import 'path_to_node_modules/@console/bluemix-components/src/components/toggle/toggle'; -``` - -All classes are the same. diff --git a/packages/components/src/components/toolbar/README.md b/packages/components/src/components/toolbar/README.md deleted file mode 100644 index faa2a41f0fd6..000000000000 --- a/packages/components/src/components/toolbar/README.md +++ /dev/null @@ -1,33 +0,0 @@ -### JavaScript - -#### Public Methods - -| Name | Params | Description | -| --------- | ------ | --------------------------------------------------------- | -| `release` | | Deletes the instance and removes document event listeners | - -#### Options - -| Option | Default Selector | Description | -| ------------------- | ---------------------------- | ----------------------------------------------------------------------- | -| `selectorInit` | `[data-toolbar]` | The selector to find instances of the component | -| `selectorSearch` | `[data-toolbar-search]` | The selector to find the search field in the toolbar | -| `selectorRowHeight` | `[data-row-height]` | The selector to find the buttons to change the row height of table rows | -| `classTallRows` | `bx--responsive-table--tall` | The modifier class for tall table rows | -| `classSearchActive` | `bx--toolbar-search--active` | The class for the active state of the toolbar search input | - -### FAQ - -#### Bind a Toolbar to a Table - -To bind a toolbar to a specific table add the table component's unique id to the -`data-table-target` attribute of the toolbar. - -```html -<div class="bx--toolbar" data-table-target="unique-id"></div> -<div class="bx--responsive-table-container" data-responsive-table> - <table class="bx--responsive-table" data-table id="unique-id"> - ... - </table> -</div> -``` diff --git a/packages/components/src/components/tooltip/README.md b/packages/components/src/components/tooltip/README.md deleted file mode 100644 index b144321293e9..000000000000 --- a/packages/components/src/components/tooltip/README.md +++ /dev/null @@ -1,182 +0,0 @@ -### JavaScript (Applied _only_ to click-to-open tooltip) - -#### Getting component class reference - -##### ES2015 - -```javascript -import { Tooltip } from 'carbon-components'; -``` - -##### With pre-build bundle (`carbon-components.min.js`) - -```javascript -var Tooltip = CarbonComponents.Tooltip; -``` - -#### Instantiating - -```javascript -// `#my-tooltip-trigger` is an element with `[data-tooltip-trigger]` attribute -Tooltip.create(document.getElementById('my-tooltip-trigger')); -``` - -#### Attributes - -| Name | Param | Description | -| ------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------ | -| `data-tooltip-target` | Any unique CSS selector | The selector, typically an id, to find the tooltip corresponding to the trigger. | -| `data-tooltip-direction` | `left`, `top`, `right`, or `bottom` | Setting this attribute overrides the directions set by this.options.tooltipDirection | - -#### Public Methods - -| Name | Params | Description | -| --------- | ------ | ---------------------------------------------------------- | -| `show` | | Shows the tooltip. | -| `hide` | | Hides the tooltip. | -| `release` | | Deletes the instance and removes document event listeners. | - -##### Example - Showing tooltip - -```javascript -// `#my-tooltip-trigger` is an element with `[data-tooltip-trigger]` attribute -var tooltipInstance = Tooltip.create( - document.getElementById('my-tooltip-trigger') -); -tooltipInstance.show(); -``` - -#### Options - -| Option | Default Selector | Description | -| --------------- | ------------------------ | --------------------------------------------------------- | -| `selectorInit` | `[data-tooltip-trigger]` | The CSS selector to find the tooltip. | -| `objMenuOffset` | `{ top: 10, left: 0 }` | An object containing the top and left offset values in px | - -##### Example - Changing menu position by 8 pixels vertically - -```javascript -// `#my-tooltip-trigger` is an element with `[data-tooltip-trigger]` attribute -Tooltip.create(document.getElementById('my-tooltip-trigger'), { - objMenuOffset(menuBody, direction) { - const { objMenuOffset: offset } = Tooltip.options; - const { top, left } = - typeof offset !== 'function' ? offset : offset(menuBody, direction); - return { - top: top + 8, - left, - }; - }, -}); -``` - -#### Events - -| Event Name | Description | -| --------------------------- | --------------------------------------------------- | -| 'floating-menu-beingshown' | The custom event fired before the menu gets open. | -| 'floating-menu-shown' | The custom event fired after the menu gets open. | -| 'floating-menu-beinghidden' | The custom event fired before the menu gets closed. | -| 'floating-menu-hidden' | The custom event fired after the menu gets closed. | - -##### Example - Preventing click-to-open tooltip from being closed in a certain condition - -```javascript -document.addEventListener('floating-menu-beinghidden', function(evt) { - if (myApplication.shouldTooltipKeptOpen(evt.target)) { - evt.preventDefault(); - } -}); -``` - -##### Example - Notifying events of all click-to-open tooltips being hidden to an analytics library - -```javascript -document.addEventListener('floating-menu-hidden', function(evt) { - myAnalyticsLibrary.send({ - action: 'Tooltip hidden', - id: evt.target.id, - }); -}); -``` - -### Interactive tooltip - -Interactive tooltip should be used if there are actions a user can take in the -tooltip (e.g. a link or a button). For more regular use case, e.g. giving the -user more text information about something, use definition tooltip or icon -tooltip. - -| Selector | Description | -| ----------------------------- | ---------------------------------- | -| `.bx--tooltip__trigger--bold` | Modifier class to make label bold. | - -#### HTML - -By default, the tooltip (`.bx--tooltip`) goes right under `<body>`. You can -change the behavior by adding `data-floating-menu-container` to one of the DOM -ancestors of the tooltip's original location. For example, if you have HTML -structure like below, the menu body will go under the second `<div>`: - -```html -<body> - <div> - <div data-floating-menu-container> - <div> - <div class="bx--tooltip__label" ...> - Tooltip label - <div - tabindex="0" - data-tooltip-trigger - data-tooltip-target="#unique-tooltip" - class="bx--tooltip__trigger" - ... - > - ... - </div> - </div> - <div - id="unique-tooltip" - data-floating-menu-direction="bottom" - class="bx--tooltip" - ... - > - <span class="bx--tooltip__caret"></span> ... - </div> - </div> - </div> - </div> -</body> -``` - -### Definition tooltip - -Definition tooltip is for regular use case of tooltip, e.g. giving the user more -text information about something, like defining a word. This works better than -the interactive tooltip in regular use cases because the info icon used in -interactive tooltip can be repetitive when it’s shown several times on a page. -Definition tooltip does not use any JavaScript. If there are actions a user can -take in the tooltip (e.g. a link or a button), use interactive tooltip. - -| Selector | Description | -| ---------------------- | ----------------------------------------------------- | -| `.bx--tooltip--top` | A simple tooltip that is displayed above the trigger. | -| `.bx--tooltip--bottom` | A simple tooltip that is displayed below the trigger. | - -### Icon tooltip - -Icon tooltip is for short single line of text describing an icon. Icon tooltip -does not use any JavaScript. No label should be added to this variation. If -there are actions a user can take in the tooltip (e.g. a link or a button), use -interactive tooltip. - -| Selector | Description | -| ---------------------- | --------------------------------------------------------------- | -| `.bx--tooltip--top` | A simple tooltip that is displayed above the trigger. | -| `.bx--tooltip--right` | A simple tooltip that is displayed to the right of the trigger. | -| `.bx--tooltip--bottom` | A simple tooltip that is displayed below the trigger. | -| `.bx--tooltip--left` | A simple tooltip that is displayed to the left of the trigger. | - -### Links & Resources - -- [Tooltips & Toggletips](https://inclusive-components.design/tooltips-toggletips/) diff --git a/packages/components/src/components/tooltip/migrate-to-9.x.md b/packages/components/src/components/tooltip/migrate-to-9.x.md deleted file mode 100644 index bf83fc8ab8df..000000000000 --- a/packages/components/src/components/tooltip/migrate-to-9.x.md +++ /dev/null @@ -1,28 +0,0 @@ -### HTML - -There are now three major variations of this component. Default tooltip is now -interactive tooltip and is an on click icon instead of the prior on hover. -`.bx--tooltip--definition` does not contain an icon and should only be used to -define the underlined word. `.bx--tooltip--icon` replaces -`.bx--tooltip--simple`. You should only use this variation for an icon and -limited to a single line describing the icon. Multi-line is not supported. - -### SCSS - -The tooltips are now by default normal font weight and can be made semi-bold by -adding the modifier class `.bx--tooltip__trigger--bold`. - -**New**: `.bx--tooltip__trigger--bold` - -`.bx--tooltip--definition` - -`.bx--tooltip--icon` - -**Old**: - -`.bx--tooltip--simple` - -### JavaScript - -The old tooltip variation of the default tooltip was on hover. This variation -however now has on click functionality. diff --git a/packages/components/src/components/ui-shell/README.md b/packages/components/src/components/ui-shell/README.md deleted file mode 100644 index fa8a17e780c8..000000000000 --- a/packages/components/src/components/ui-shell/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# UI Shell - -## Accessibility - -#### Header - -> A menu that is visually persistent is a menubar. A menubar is typically -> horizontal and is often used to create a menu bar similar to those found near -> the top of the window in many desktop applications, offering the user quick -> access to a consistent set of commands. - -Source: https://www.w3.org/TR/wai-aria-practices/#menu - -Resources: - -- https://www.w3.org/TR/wai-aria-practices/#menu -- https://www.w3.org/TR/wai-aria-practices/examples/menubar/menubar-1/menubar-1.html - -Requirements: - -- https://www.w3.org/TR/wai-aria-practices/#menu -- `nav` should have an `aria-label` that matches the label on the menubar since - it is a site navigation system -- Verify that the icons are compatible in high contrast mode -- [Keyboard Support](https://www.w3.org/TR/wai-aria-practices/examples/menubar/menubar-1/menubar-1.html#kbd_label) -- When a menu opens, or when a menubar receives focus, keyboard focus is placed - on the first item. All items are focusable as described in 5.6 Keyboard - Navigation Inside Components. - -## Side navigation - -Our Side Navigation has approximately the following structure: - -```html -<!-- Top level container --> -<aside class="bx--side-nav"> - <!-- Navigation wrapper for accessibility --> - <nav - class="bx--side-nav__navigation" - role="navigation" - aria-label="Navigation" - > - <!-- Has the title and an optionaly select menu rendered at the top of the side nav --> - <header class="bx--side-nav__header"></header> - <!-- Renders all of our navigation items --> - <ul class="bx--side-nav__items"></ul> - <!-- Renders the button to collapse or expand the side nav --> - <footer class="bx--side-nav__footer"></footer> - </nav> -</aside> -``` - -### Header - -The header is mostly just an icon and a title for the local context of a page. -For example, in IBM Cloud we would have IBM Cloud in the header and a product in -the side navigation, like Containers. - -The header also can optionally have a select that acts as a sub-menu that adds -another navigation pattern to the page. - -### Items - -A side nav item is a `<li>` with the `bx--side-nav__item` class. Inside, we will -have a link or a category. Categories themselves have links inside of a menu. - -Links can either be active, or in-active, and this status is reflected by using -an aria attribute `aria-current="page"` or by a class name. - -Categories have a `<button>` as their target so that we can easily open/close -them using screen readers. - -### Footer - -The footer itself is primary just a `<button>` that should handle expanding and -closing the side nav. - -## Tokens - -## Header & header-panel - -| `#` | Variable/token | Role | Theme value | -| --- | ------------------------- | ------------------------------------------- | ----------- | -| 1 | `$shell-header-bg-01` | Header bar background | `$gray-100` | -| 2 | `$shell-header-bg-02` | Header menu trigger hover | `#2c2c2c` | -| 3 | `$shell-header-bg-03` | Header action active background | `$gray-80` | -| 4 | `$shell-header-bg-04` | Header nav link hover | `#353535` | -| 5 | `$shell-header-bg-05` | Header nav link focus and active background | `$gray-70` | -| 6 | `$shell-header-bg-06` | Header nav link submenu | `$gray-90` | -| 7 | `$shell-header-border-01` | Header bar border bottom | `$gray-80` | -| 8 | `$shell-header-focus` | Header focus border | `$white-0` | -| 9 | `$shell-header-text-01` | Primary text in header <br> Title text | `$gray-10` | -| 8 | `$shell-header-text-02` | Secondary text in header <br> Menu items | `$gray-30` | -| 10 | `$shell-header-icon-01` | Header menu trigger | `$gray-10` | -| 11 | `$shell-header-icon-02` | Header bar action icons | `$white-0` | -| 12 | `$shell-header-link` | Header menu item link | `$blue-60` |