From 21301a8073a48e1e69f3fb404839c77985a4049f Mon Sep 17 00:00:00 2001 From: Adi Dahiya Date: Thu, 6 Jun 2019 21:22:22 -0400 Subject: [PATCH] Fix docs rendering of mixed HTML / markdown content (#3585) --- packages/core/src/components/button/button.md | 16 ++-- .../collapsible-list/collapsible-list.md | 32 +++++--- packages/core/src/components/dialog/dialog.md | 12 +-- .../components/editable-text/editable-text.md | 8 +- .../src/components/forms/control-group.md | 18 +++-- .../core/src/components/forms/file-input.md | 6 +- packages/core/src/components/forms/label.md | 10 ++- .../src/components/forms/numeric-input.md | 8 +- .../core/src/components/forms/text-inputs.md | 11 +-- .../src/components/html-select/html-select.md | 8 +- .../src/components/html-table/html-table.md | 8 +- packages/core/src/components/icon/icon.md | 30 +++++--- packages/core/src/components/menu/menu.md | 12 ++- packages/core/src/components/navbar/navbar.md | 6 +- .../core/src/components/overlay/overlay.md | 5 +- .../core/src/components/popover/popover.md | 76 +++++++++++++------ packages/core/src/components/portal/portal.md | 12 ++- .../components/resize-sensor/resize-sensor.md | 9 ++- .../core/src/components/skeleton/skeleton.md | 10 ++- .../core/src/components/spinner/spinner.md | 8 +- .../src/components/tag-input/tag-input.md | 22 ++++-- packages/core/src/components/toast/toast.md | 22 ++++-- .../core/src/components/tooltip/tooltip.md | 10 ++- packages/core/src/components/tree/tree.md | 6 +- packages/datetime/src/datetimepicker.md | 13 +++- packages/docs-app/src/blueprint.md | 6 +- packages/docs-app/src/getting-started.md | 8 +- packages/docs-app/src/reading-the-docs.md | 5 +- packages/docs-data/package.json | 2 +- packages/icons/src/index.md | 3 +- packages/labs/src/index.md | 4 +- .../src/components/select/multi-select.md | 3 +- .../src/components/select/select-component.md | 24 +++--- packages/table/src/docs/table.md | 5 +- .../timezone-picker/timezone-picker.md | 11 +-- yarn.lock | 5 -- 36 files changed, 286 insertions(+), 168 deletions(-) diff --git a/packages/core/src/components/button/button.md b/packages/core/src/components/button/button.md index 484969917e..124fab0fc0 100644 --- a/packages/core/src/components/button/button.md +++ b/packages/core/src/components/button/button.md @@ -21,13 +21,17 @@ Buttons trigger actions when clicked. ```
-

Disabled `Button` prevents all interaction

- Use `AnchorButton` if you need mouse interaction events (such as hovering) on a disabled button. +

- `Button` uses the native `disabled` attribute on the `

+ +Use `AnchorButton` if you need mouse interaction events (such as hovering) on a disabled button. + +`Button` uses the native `disabled` attribute on the `
diff --git a/packages/core/src/components/collapsible-list/collapsible-list.md b/packages/core/src/components/collapsible-list/collapsible-list.md index 86d13d1678..4c888bce64 100644 --- a/packages/core/src/components/collapsible-list/collapsible-list.md +++ b/packages/core/src/components/collapsible-list/collapsible-list.md @@ -7,18 +7,26 @@ customizing the appearance of visible items, using the props from the `MenuItem` children.
-

Deprecated: use [Overflow list](#core/components/overflow-list)

- This component is **deprecated since 3.0.0** with the introduction of - [`OverflowList`](#core/components/overflow-list) which provides a similar - experience with two distinct advantages: -
    -
  1. Items collapse automatically based on available space in the container.
    2. -
  2. - `OverflowList` accepts a generic array of items (instead of explicit - `` children) with custom renderers for both visible and overflowed - items, allowing for _any_ UI, not just a dropdown menu. -
    3. -
+

+ +Deprecated: use [Overflow list](#core/components/overflow-list) +

+ +This component is **deprecated since 3.0.0** with the introduction of +[`OverflowList`](#core/components/overflow-list) which provides a similar +experience with two distinct advantages: + +
    +
  1. Items collapse automatically based on available space in the container.
    2. +
  2. + +`OverflowList` accepts a generic array of items (instead of explicit +`` children) with custom renderers for both visible and overflowed +items, allowing for _any_ UI, not just a dropdown menu. + +
    3. +
+
@reactExample CollapsibleListExample diff --git a/packages/core/src/components/dialog/dialog.md b/packages/core/src/components/dialog/dialog.md index 05e5fb8837..919f6b9fa4 100644 --- a/packages/core/src/components/dialog/dialog.md +++ b/packages/core/src/components/dialog/dialog.md @@ -4,11 +4,13 @@ Dialogs present content overlaid over other parts of the UI.

Terminology note

- The term "modal" is sometimes used to mean "dialog," but this is a misnomer. - _Modal_ is an adjective that describes parts of a UI. - An element is considered modal if it - [blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window). - We use the term "dialog" to avoid confusion with the adjective. + +The term "modal" is sometimes used to mean "dialog," but this is a misnomer. +_Modal_ is an adjective that describes parts of a UI. +An element is considered modal if it +[blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window). +We use the term "dialog" to avoid confusion with the adjective. +
@reactExample DialogExample diff --git a/packages/core/src/components/editable-text/editable-text.md b/packages/core/src/components/editable-text/editable-text.md index 11624b59ee..99301fdeaf 100644 --- a/packages/core/src/components/editable-text/editable-text.md +++ b/packages/core/src/components/editable-text/editable-text.md @@ -15,9 +15,11 @@ You should not use `EditableText` when a static always-editable `` or

Centering the component

- **Do not center this component** using `text-align: center`, as it will cause an infinite loop - in the browser ([more details](https://github.com/JedWatson/react-select/issues/540)). Instead, - you should center the component via flexbox or with `position` and `transform: translateX(-50%)`. + +**Do not center this component** using `text-align: center`, as it will cause an infinite loop +in the browser ([more details](https://github.com/JedWatson/react-select/issues/540)). Instead, +you should center the component via flexbox or with `position` and `transform: translateX(-50%)`. +
diff --git a/packages/core/src/components/forms/control-group.md b/packages/core/src/components/forms/control-group.md index bb4a86fdc4..9f22a54d37 100644 --- a/packages/core/src/components/forms/control-group.md +++ b/packages/core/src/components/forms/control-group.md @@ -6,13 +6,17 @@ groups, and HTML selects as direct children.

Control group vs. input group

-

Both components group multiple elements into a single unit, but their usage patterns are - quite different.

-

Think of `ControlGroup` as a parent with multiple children, with each one a separate - control.

-

Conversely, an `InputGroup` is a single control, and should function like so. A - button inside of an input group should only affect that input; if its reach is further, then it - should be promoted to live in a control group.

+ +Both components group multiple elements into a single unit, but their usage patterns are +quite different. + +Think of `ControlGroup` as a parent with multiple children, with each one a separate +control. + +Conversely, an `InputGroup` is a single control, and should function like so. A +button inside of an input group should only affect that input; if its reach is further, then it +should be promoted to live in a control group. +
@reactExample ControlGroupExample diff --git a/packages/core/src/components/forms/file-input.md b/packages/core/src/components/forms/file-input.md index 46060095e6..68441224d0 100644 --- a/packages/core/src/components/forms/file-input.md +++ b/packages/core/src/components/forms/file-input.md @@ -12,8 +12,10 @@ Use `inputProps` to apply props to the `` element.

Static file name

- File name does not update on file selection. To get this behavior, - you must implement it separately in JS. + +File name does not update on file selection. To get this behavior, +you must implement it separately in JS. +
```tsx diff --git a/packages/core/src/components/forms/label.md b/packages/core/src/components/forms/label.md index c2d55f5c93..4c8ab018fc 100644 --- a/packages/core/src/components/forms/label.md +++ b/packages/core/src/components/forms/label.md @@ -8,10 +8,12 @@ below, clicking a label focuses its ``.

Prefer form groups over labels

- The [React `FormGroup` component](#core/components/form-group) provides - additional functionality such as helper text and modifier props as well as - full label support. `FormGroup` supports both simple and complex use cases, - therefore we recommend using it exclusively when constructing forms. + +The [React `FormGroup` component](#core/components/form-group) provides +additional functionality such as helper text and modifier props as well as +full label support. `FormGroup` supports both simple and complex use cases, +therefore we recommend using it exclusively when constructing forms. +
@## Props diff --git a/packages/core/src/components/forms/numeric-input.md b/packages/core/src/components/forms/numeric-input.md index d1a1819dca..680c935a67 100644 --- a/packages/core/src/components/forms/numeric-input.md +++ b/packages/core/src/components/forms/numeric-input.md @@ -43,9 +43,11 @@ custom `onKeyDown` callback) and when the field loses focus (via a custom trigged, the field will be cleared.
- This example contains non-core functionality that is meant to demonstrate - the extensibility of the `NumericInput` component. The correctness of the - custom evaluation code has not been tested robustly. + +This example contains non-core functionality that is meant to demonstrate +the extensibility of the `NumericInput` component. The correctness of the +custom evaluation code has not been tested robustly. +
@reactExample NumericInputExtendedExample diff --git a/packages/core/src/components/forms/text-inputs.md b/packages/core/src/components/forms/text-inputs.md index 79ce8a2f88..b24b76edb6 100644 --- a/packages/core/src/components/forms/text-inputs.md +++ b/packages/core/src/components/forms/text-inputs.md @@ -39,12 +39,13 @@ the parent input.

Icons only

-

You cannot use buttons with text in the CSS API for input groups. The padding for text inputs - in CSS cannot accommodate buttons whose width varies due to text content. You should use icons on - buttons instead.

- Conversely, the [`InputGroup`](#core/components/text-inputs.input-group) React - component _does_ support arbitrary content in its right element. +You cannot use buttons with text in the CSS API for input groups. The padding for text inputs +in CSS cannot accommodate buttons whose width varies due to text content. You should use icons on +buttons instead. + +Conversely, the [`InputGroup`](#core/components/text-inputs.input-group) React +component _does_ support arbitrary content in its right element.
diff --git a/packages/core/src/components/html-select/html-select.md b/packages/core/src/components/html-select/html-select.md index 7a79e8f796..287498e743 100644 --- a/packages/core/src/components/html-select/html-select.md +++ b/packages/core/src/components/html-select/html-select.md @@ -5,9 +5,11 @@ dropdown caret, so we provide an `HTMLSelect` component to streamline this process.
- The [`Select`](#select/multi-select) component in the [**@blueprintjs/select**](#select) - package provides a React alternative to the native HTML `` tag. Notably, it +supports custom filtering logic and item rendering. +
@## Props diff --git a/packages/core/src/components/html-table/html-table.md b/packages/core/src/components/html-table/html-table.md index 59968128ce..34fad8dcb9 100644 --- a/packages/core/src/components/html-table/html-table.md +++ b/packages/core/src/components/html-table/html-table.md @@ -4,9 +4,11 @@ This component provides Blueprint styling to native HTML tables.

This is not @blueprintjs/table

- This table component is a simple CSS-only skin for HTML `` elements. - It is ideal for basic static tables. If you're looking for more complex - spreadsheet-like features, check out [**@blueprintjs/table**](#table). + +This table component is a simple CSS-only skin for HTML `
` elements. +It is ideal for basic static tables. If you're looking for more complex +spreadsheet-like features, check out [**@blueprintjs/table**](#table). + @## Props diff --git a/packages/core/src/components/icon/icon.md b/packages/core/src/components/icon/icon.md index 5048da2518..57cd85a2dc 100644 --- a/packages/core/src/components/icon/icon.md +++ b/packages/core/src/components/icon/icon.md @@ -1,15 +1,19 @@ @# Icon
- See the [**Icons package**](#icons) for a searchable list of all available UI icons. + +See the [**Icons package**](#icons) for a searchable list of all available UI icons. +

SVG icons in 2.0

- Blueprint 2.0 introduced SVG icon support and moved icon resources to a separate __@blueprintjs/icons__ package. - The `Icon` component renders SVG paths and the icon classes are no longer used by any Blueprint React component. - Icon font support has been preserved but should be considered a legacy feature that will be removed in a - future major version. + +Blueprint 2.0 introduced SVG icon support and moved icon resources to a separate __@blueprintjs/icons__ package. +The `Icon` component renders SVG paths and the icon classes are no longer used by any Blueprint React component. +Icon font support has been preserved but should be considered a legacy feature that will be removed in a +future major version. +
This section describes two ways of using the UI icon font: via React `Icon` @@ -66,9 +70,11 @@ import { IconNames } from "@blueprintjs/icons";

Icon fonts are legacy in 2.0

- Blueprint's icon fonts should be considered a legacy feature and will be removed in a future major version. - The SVGs rendered by the React component do not suffer from the blurriness of icon fonts, and browser - support is equivalent. + +Blueprint's icon fonts should be considered a legacy feature and will be removed in a future major version. +The SVGs rendered by the React component do not suffer from the blurriness of icon fonts, and browser +support is equivalent. +
The CSS-only icons API uses the __icon fonts__ from the __@blueprintjs/icons__ package. @@ -88,7 +94,9 @@ Icon classes also support the four `.@ns-intent-*` modifiers to color the image.

Non-standard sizes

- Generally, font icons should only be used at either 16px or 20px. However, if a non-standard size is - necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class. - You can instead use the class `@ns-icon` to make the icon inherit its size from surrounding text. + +Generally, font icons should only be used at either 16px or 20px. However, if a non-standard size is +necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class. +You can instead use the class `@ns-icon` to make the icon inherit its size from surrounding text. +
diff --git a/packages/core/src/components/menu/menu.md b/packages/core/src/components/menu/menu.md index 309e8b6225..3babed1e4d 100644 --- a/packages/core/src/components/menu/menu.md +++ b/packages/core/src/components/menu/menu.md @@ -43,8 +43,10 @@ there is not enough room to the right.

JavaScript only

- Submenus are only supported in the React components. They cannot be created with CSS alone because - they rely on the [`Popover`](#core/components/popover) component for positioning and transitions. + +Submenus are only supported in the React components. They cannot be created with CSS alone because +they rely on the [`Popover`](#core/components/popover) component for positioning and transitions. +
@## Props @@ -126,8 +128,10 @@ as they abstract away the tedious parts of implementing a menu. defined as part of `.@ns-menu-item`.
- Note that the following examples are `display: inline-block`; you may need to adjust - menu width in your own usage. + +Note that the following examples are `display: inline-block`; you may need to adjust +menu width in your own usage. +
@css menu diff --git a/packages/core/src/components/navbar/navbar.md b/packages/core/src/components/navbar/navbar.md index 8ee0948131..b07e3c3048 100644 --- a/packages/core/src/components/navbar/navbar.md +++ b/packages/core/src/components/navbar/navbar.md @@ -14,8 +14,10 @@ This modifier is not illustrated here because it breaks the document flow.

Body padding required

- The fixed navbar will lie on top of your other content unless you add padding to the top of the - `` element equal to the height of the navbar. Use the `$pt-navbar-height` Sass variable. + +The fixed navbar will lie on top of your other content unless you add padding to the top of the +`` element equal to the height of the navbar. Use the `$pt-navbar-height` Sass variable. +
@### Fixed width diff --git a/packages/core/src/components/overlay/overlay.md b/packages/core/src/components/overlay/overlay.md index 2a6ed8f682..fdd6a14ace 100644 --- a/packages/core/src/components/overlay/overlay.md +++ b/packages/core/src/components/overlay/overlay.md @@ -44,8 +44,9 @@ actually closes the overlay.

A note about overlay content positioning

- When rendered inline, content will automatically be set to `position: absolute` to respect - document flow. Otherwise, content will be set to `position: fixed` to cover the entire viewport. + +When rendered inline, content will automatically be set to `position: absolute` to respect +document flow. Otherwise, content will be set to `position: fixed` to cover the entire viewport.
```tsx diff --git a/packages/core/src/components/popover/popover.md b/packages/core/src/components/popover/popover.md index bbda3775fb..a720c1426d 100644 --- a/packages/core/src/components/popover/popover.md +++ b/packages/core/src/components/popover/popover.md @@ -73,10 +73,12 @@ wrapped in a single element when rendering

Button targets

- Buttons make great popover targets, but the `disabled` attribute on a `
```tsx @@ -107,7 +109,8 @@ export class PopoverExample extends React.Component { @### Position -The `position` prop controls the Popover's position relative to the target. The `Position` enumeration defines the full set of supported values. There are two attributes of positioning to consider: +The `position` prop controls the Popover's position relative to the target. +The `Position` enumeration defines the full set of supported values. There are two attributes of positioning to consider: - Which __side__ of the target the popover should render on. - The popover's __alignment__ relative to the target. @@ -118,25 +121,38 @@ These two attributes can be expressed with a single value having the following s [SIDE]_[ALIGNMENT] -The following example shows all supported `Position` values and how each behaves in practice. Note that if _[ALIGNMENT] is ommitted, the popover will align to the __center__ of the target. +The following example shows all supported `Position` values and how each behaves in practice. +Note that if _[ALIGNMENT] is ommitted, +the popover will align to the __center__ of the target. @reactExample PopoverPositionExample #### Automatic positioning -The Popover's `position` can also be chosen _automatically_ via `"auto"`, `"auto-start"`, or `"auto-end"`. All of these options choose and continually update the __side__ for you to avoid overflowing the boundary element (when scrolling within it, for instance). The options differ in how they handle __alignment__: +The Popover's `position` can also be chosen _automatically_ via `"auto"`, `"auto-start"`, or `"auto-end"`. +All of these options choose and continually update the __side__ +for you to avoid overflowing the boundary element (when scrolling within it, for instance). +The options differ in how they handle __alignment__: - In `"auto"` mode (the default for `position`), the Popover will align itself to the center of the target as it flips sides. - In `"auto-start"` mode, the Popover will align itself to the `start` of the target (i.e., the top edge when the popover is on the left or right, or the left edge when the popover is on the top or bottom). - In `"auto-end"` mode, the Popover will align itself to the `end` of the target (i.e., the bottom edge when the popover is on the left or right, or the right edge when the popover is on the top or bottom).
- You can also specify a specific initial position (e.g. `LEFT`, `TOP_RIGHT`) and still update the Popover's position automatically by enabling the modifiers `flip` and `preventOverflow`. [See below](#core/components/popover.modifiers) for information about modifiers. + +You can also specify a specific initial position (e.g. `LEFT`, `TOP_RIGHT`) and still update the Popover's position +automatically by enabling the modifiers `flip` and `preventOverflow`. +[See below](#core/components/popover.modifiers) for information about modifiers. +
@### Modifiers -Modifiers are the tools through which you customize Popper.js's behavior. Popper.js defines several of its own modifiers to handle things such as flipping, preventing overflow from a boundary element, and positioning the arrow. `Popover` defines a few additional modifiers to support itself. You can even define your own modifiers, and customize the Popper.js defaults, through the `modifiers` prop. (Note: it is not currently possible to configure `Popover`'s modifiers through the `modifiers` prop, nor can you define your own with the same name.) +Modifiers are the tools through which you customize Popper.js's behavior. Popper.js defines several of its own modifiers +to handle things such as flipping, preventing overflow from a boundary element, and positioning the arrow. +`Popover` defines a few additional modifiers to support itself. You can even define your own modifiers, and customize +the Popper.js defaults, through the `modifiers` prop. (Note: it is not currently possible to configure `Popover`'s modifiers +through the `modifiers` prop, nor can you define your own with the same name.) **Popper.js modifiers that can be customized via the `modifiers` prop:** @@ -157,8 +173,10 @@ Modifiers are the tools through which you customize Popper.js's behavior. Popper - `updatePopoverState` saves off some popper data to `Popover` React state for fancy things
- See [the Popper.js Modifiers documentation](https://popper.js.org/popper-documentation.html#modifiers) - for more details on all the available modifiers. + +See [the Popper.js Modifiers documentation](https://popper.js.org/popper-documentation.html#modifiers) +for more details on all the available modifiers. +
@### Controlled mode @@ -178,8 +196,10 @@ if the `nextOpenState` is not the same as the `Popover`'s current state).

Disabling controlled popovers

-

If `disabled={true}`, a controlled popover will remain closed even if `isOpen={true}`. - The popover will re-open when `disabled` is set to `false`.

+ +If `disabled={true}`, a controlled popover will remain closed even if `isOpen={true}`. +The popover will re-open when `disabled` is set to `false`. +
#### Example controlled usage @@ -242,8 +262,10 @@ The following example demonstrates the various interaction kinds (note: these Po

Conditionally styling popover targets

- When a popover is open, `Classes.POPOVER_OPEN` is applied to the target. - You can use this to style the target differently when the popover is open. + +When a popover is open, `Classes.POPOVER_OPEN` is applied to the target. +You can use this to style the target differently when the popover is open. +
@### Closing on click @@ -284,10 +306,12 @@ for a menu tree. @reactExample PopoverDismissExample
- Dismiss elements won't have any effect in a popover with - `PopoverInteractionKind.HOVER_TARGET_ONLY`, because there is no way to - interact with the popover content itself: the popover is dismissed the - moment the user mouses away from the target. + +Dismiss elements won't have any effect in a popover with +`PopoverInteractionKind.HOVER_TARGET_ONLY`, because there is no way to +interact with the popover content itself: the popover is dismissed the +moment the user mouses away from the target. +
@### Backdrop @@ -318,9 +342,11 @@ The backdrop element has the same opacity-fade transition as the `Dialog` backdr

Dangerous edge case

- Rendering a `` outside the viewport bounds can easily break - your application by covering the UI with an invisible non-interactive backdrop. This edge case - must be handled by your application code or simply avoided if possible. + +Rendering a `` outside the viewport bounds can easily break +your application by covering the UI with an invisible non-interactive backdrop. This edge case +must be handled by your application code or simply avoided if possible. +
@### Portal rendering @@ -390,8 +416,10 @@ documentation. @## Testing
- Your best resource for strategies in popover testing is - [its own unit test suite.](https://github.com/palantir/blueprint/blob/develop/packages/core/test/popover/popoverTests.tsx) + +Your best resource for strategies in popover testing is +[its own unit test suite.](https://github.com/palantir/blueprint/blob/develop/packages/core/test/popover/popoverTests.tsx) +
#### Animation delays diff --git a/packages/core/src/components/portal/portal.md b/packages/core/src/components/portal/portal.md index b8d0a1536a..37deee390a 100644 --- a/packages/core/src/components/portal/portal.md +++ b/packages/core/src/components/portal/portal.md @@ -21,7 +21,9 @@ In a **React 16+** environment, the `Portal` component will use [`ReactDOM.creat To use them, supply a child context to a subtree that contains the Portals you want to customize.
- Blueprint uses the React 15-compatible `getChildContext()` API instead of the newer React 16.3 `React.createContext()` API. + +Blueprint uses the React 15-compatible `getChildContext()` API instead of the newer React 16.3 `React.createContext()` API. +
@interface IPortalContext @@ -37,9 +39,11 @@ application.

A note about responsive layouts

- For a single-page app, if the `` is styled with `width: 100%` and `height: 100%`, a `Portal` - may take up extra whitespace and cause the window to undesirably scroll. To fix this, instead - apply `position: absolute` to the `` tag. + +For a single-page app, if the `` is styled with `width: 100%` and `height: 100%`, a `Portal` +may take up extra whitespace and cause the window to undesirably scroll. To fix this, instead +apply `position: absolute` to the `` tag. +
@interface IPortalProps diff --git a/packages/core/src/components/resize-sensor/resize-sensor.md b/packages/core/src/components/resize-sensor/resize-sensor.md index 7274da7a1c..813b5a9d8a 100644 --- a/packages/core/src/components/resize-sensor/resize-sensor.md +++ b/packages/core/src/components/resize-sensor/resize-sensor.md @@ -26,10 +26,11 @@ function handleResize(entries: IResizeEntry[]) {

Asynchronous behavior

- The `onResize` callback is invoked asynchronously after a resize is detected - and typically happens at the end of a frame (after layout, before paint). - Therefore, testing behavior that relies on this component involves setting a - timeout for the next frame. + +The `onResize` callback is invoked asynchronously after a resize is detected +and typically happens at the end of a frame (after layout, before paint). +Therefore, testing behavior that relies on this component involves setting a +timeout for the next frame.
@interface IResizeSensorProps diff --git a/packages/core/src/components/skeleton/skeleton.md b/packages/core/src/components/skeleton/skeleton.md index 6e8707e54d..adad54d29f 100644 --- a/packages/core/src/components/skeleton/skeleton.md +++ b/packages/core/src/components/skeleton/skeleton.md @@ -16,9 +16,11 @@ a loading animation.

Manually disable focusable elements

- When using the `.@ns-skeleton` class on focusable elements such as inputs - and buttons, be sure to disable the element, via either the `disabled` or - `tabindex="-1"` attributes. Failing to do so will allow these skeleton - elements to be focused when they shouldn't be. + +When using the `.@ns-skeleton` class on focusable elements such as inputs +and buttons, be sure to disable the element, via either the `disabled` or +`tabindex="-1"` attributes. Failing to do so will allow these skeleton +elements to be focused when they shouldn't be. +
diff --git a/packages/core/src/components/spinner/spinner.md b/packages/core/src/components/spinner/spinner.md index 712e403526..f4d756fe89 100644 --- a/packages/core/src/components/spinner/spinner.md +++ b/packages/core/src/components/spinner/spinner.md @@ -23,9 +23,11 @@ by including `Classes.SMALL` or `Classes.LARGE` in `className` instead of the

IE11 compatibility note

- IE11 [does not support CSS transitions on SVG elements][msdn-css-svg] so spinners with known - `value` will not smoothly transition as `value` changes. Indeterminate spinners still animate - correctly because they rely on CSS animations. + +IE11 [does not support CSS transitions on SVG elements][msdn-css-svg] so spinners with known +`value` will not smoothly transition as `value` changes. Indeterminate spinners still animate +correctly because they rely on CSS animations. +
[msdn-css-svg]: https://developer.microsoft.com/en-us/microsoft-edge/platform/status/csstransitionsforsvgelements/?q=svg diff --git a/packages/core/src/components/tag-input/tag-input.md b/packages/core/src/components/tag-input/tag-input.md index 5fba52ab93..fdea1b39c3 100644 --- a/packages/core/src/components/tag-input/tag-input.md +++ b/packages/core/src/components/tag-input/tag-input.md @@ -9,8 +9,10 @@ on the container will focus the text input for seamless interaction.

Looking for a dropdown menu?

- [`MultiSelect` in the **@blueprintjs/select** package](#select/multi-select) - composes this component with a dropdopwn menu of suggestions. + +[`MultiSelect` in the **@blueprintjs/select** package](#select/multi-select) +composes this component with a dropdopwn menu of suggestions. +
@## Props @@ -44,16 +46,20 @@ be applied to the input via `inputProps`.

Handling long words

- Set an explicit `width` on the container element to cause long tags to wrap onto multiple lines. - Either supply a specific pixel value, or use `` - to fill its container's width (try this in the example above). + +Set an explicit `width` on the container element to cause long tags to wrap onto multiple lines. +Either supply a specific pixel value, or use `` +to fill its container's width (try this in the example above). +

Disabling a tag input

-

Disabling this component requires setting the `disabled` prop to `true` - and separately disabling the component's `rightElement` as appropriate - (because `TagInput` accepts any `JSX.Element` as its `rightElement`).

+ +Disabling this component requires setting the `disabled` prop to `true` +and separately disabling the component's `rightElement` as appropriate +(because `TagInput` accepts any `JSX.Element` as its `rightElement`). +
@interface ITagInputProps diff --git a/packages/core/src/components/toast/toast.md b/packages/core/src/components/toast/toast.md index 75a1dccece..a0c7df2f14 100644 --- a/packages/core/src/components/toast/toast.md +++ b/packages/core/src/components/toast/toast.md @@ -36,16 +36,20 @@ There are three ways to use the `Toaster` component:

Working with multiple toasters

- You can have multiple toasters in a single application, but you must ensure that each has a unique - `position` to prevent overlap. + +You can have multiple toasters in a single application, but you must ensure that each has a unique +`position` to prevent overlap. +

Toaster focus

- `Toaster` always disables `Overlay`'s `enforceFocus` behavior (meaning that you're not blocked - from accessing other parts of the application while a toast is active), and by default also - disables `autoFocus` (meaning that focus will not switch to a toast when it appears). You can - enable `autoFocus` for an individual `Toaster` via a prop, if desired. + +`Toaster` always disables `Overlay`'s `enforceFocus` behavior (meaning that you're not blocked +from accessing other parts of the application while a toast is active), and by default also +disables `autoFocus` (meaning that focus will not switch to a toast when it appears). You can +enable `autoFocus` for an individual `Toaster` via a prop, if desired. +
@@ -70,8 +74,10 @@ because the `Toaster` should not be treated as a normal React component.

React 16 usage

- `Toaster.create()` will throw an error if invoked inside a component lifecycle method in React 16, as `ReactDOM.render()` will return - `null` resulting in an inaccessible toaster instance. See the second bullet point on the [React 16 release notes](https://reactjs.org/blog/2017/09/26/react-v16.0.html#breaking-changes) for more information. + +`Toaster.create()` will throw an error if invoked inside a component lifecycle method in React 16, as `ReactDOM.render()` will return +`null` resulting in an inaccessible toaster instance. See the second bullet point on the [React 16 release notes](https://reactjs.org/blog/2017/09/26/react-v16.0.html#breaking-changes) for more information. +
@interface IToaster diff --git a/packages/core/src/components/tooltip/tooltip.md b/packages/core/src/components/tooltip/tooltip.md index 2c2a1251a6..f7722dbb55 100644 --- a/packages/core/src/components/tooltip/tooltip.md +++ b/packages/core/src/components/tooltip/tooltip.md @@ -37,10 +37,12 @@ The content will appear in a contrasting popover when the target is hovered.

Button targets

- Buttons make great tooltip targets, but the `disabled` attribute will prevent all - events so the enclosing `Tooltip` will not know when to respond. - Use [`AnchorButton`](#core/components/button.anchor-button) instead; - see the [callout here](#core/components/button.props) for more details. + +Buttons make great tooltip targets, but the `disabled` attribute will prevent all +events so the enclosing `Tooltip` will not know when to respond. +Use [`AnchorButton`](#core/components/button.anchor-button) instead; +see the [callout here](#core/components/button.props) for more details. +
@interface ITooltipProps diff --git a/packages/core/src/components/tree/tree.md b/packages/core/src/components/tree/tree.md index 1d635fbf55..df2190a0ac 100644 --- a/packages/core/src/components/tree/tree.md +++ b/packages/core/src/components/tree/tree.md @@ -35,8 +35,10 @@ whether the node's children are shown. @## CSS
- Note that the following examples set a maximum width and background color for the tree; - you may want to do this as well in your own usage. + +Note that the following examples set a maximum width and background color for the tree; +you may want to do this as well in your own usage. +
@css tree diff --git a/packages/datetime/src/datetimepicker.md b/packages/datetime/src/datetimepicker.md index 3c5bd7d577..edb945eb16 100644 --- a/packages/datetime/src/datetimepicker.md +++ b/packages/datetime/src/datetimepicker.md @@ -4,10 +4,15 @@ and a [`TimePicker`](#datetime/timepicker) into one container.
-

Deprecated: use [Date picker](#datetime/datepicker)

- This component is **deprecated since @blueprintjs/datetime v3.2.0** with the addition - of `` `timePrecision` and `timePickerProps` props to trivially - compose time selection with the existing date selection. +

+ +Deprecated: use [Date picker](#datetime/datepicker) +

+ +This component is **deprecated since @blueprintjs/datetime v3.2.0** with the addition +of `` `timePrecision` and `timePickerProps` props to trivially +compose time selection with the existing date selection. +
@reactExample DateTimePickerExample diff --git a/packages/docs-app/src/blueprint.md b/packages/docs-app/src/blueprint.md index c115861139..2d9755728b 100644 --- a/packages/docs-app/src/blueprint.md +++ b/packages/docs-app/src/blueprint.md @@ -7,7 +7,11 @@ It is optimized for building complex data-dense interfaces for desktop applicati @reactDocs Welcome
-

Blueprint v3 is available now! [See what's new.](#blueprint/whats-new-3.0)

+

+ +Blueprint v3 is available now! [See what's new.](#blueprint/whats-new-3.0) + +

@## Quick start diff --git a/packages/docs-app/src/getting-started.md b/packages/docs-app/src/getting-started.md index 0e43772cd4..eb27da5cb2 100644 --- a/packages/docs-app/src/getting-started.md +++ b/packages/docs-app/src/getting-started.md @@ -53,8 +53,9 @@ The `main` module exports all symbols from all modules so you don't have to impo

CDN-only usage

- Blueprint can instead be quickly added to a page using the Unpkg CDN. - [See below for instructions](#blueprint/getting-started.cdn-consumption). + +Blueprint can instead be quickly added to a page using the Unpkg CDN. +[See below for instructions](#blueprint/getting-started.cdn-consumption).
@## JS environment @@ -96,7 +97,8 @@ npm install --save @types/moment-timezone Blueprint's declaration files require **TypeScript 2.3+** for default generic parameter arguments: `

`.

- For more information, see [Understanding TypeScript](#blueprint/reading-the-docs.understanding-typescript). + +For more information, see [Understanding TypeScript](#blueprint/reading-the-docs.understanding-typescript).
@## Vanilla JS APIs diff --git a/packages/docs-app/src/reading-the-docs.md b/packages/docs-app/src/reading-the-docs.md index 89483b526d..9b74fdc491 100644 --- a/packages/docs-app/src/reading-the-docs.md +++ b/packages/docs-app/src/reading-the-docs.md @@ -34,8 +34,9 @@ Simply ignoring the type annotations (any italics in code blocks) will produce v Familiarity with the syntax is suggested so you can follow our examples source code.
- For more information, see the TypeScript Handbook for [basic types][basic-types] - and [consuming declaration files][decl-files]. + +For more information, see the TypeScript Handbook for [basic types][basic-types] +and [consuming declaration files][decl-files].
[basic-types]: https://www.typescriptlang.org/docs/handbook/basic-types.html diff --git a/packages/docs-data/package.json b/packages/docs-data/package.json index f91eb3b504..e1fae56a6e 100644 --- a/packages/docs-data/package.json +++ b/packages/docs-data/package.json @@ -17,7 +17,7 @@ "glob": "^7.1.3", "highlights": "^3.1.1", "language-less": "github:atom/language-less", - "marked": "^0.5.2", + "marked": "^0.6.2", "semver": "^6.0.0", "tree-sitter-typescript": "^0.13.6" }, diff --git a/packages/icons/src/index.md b/packages/icons/src/index.md index 8819160f59..0b6cc2f8cd 100644 --- a/packages/icons/src/index.md +++ b/packages/icons/src/index.md @@ -10,7 +10,8 @@ It's easy to change their color or apply effects like text shadows via standard Many Blueprint components support an `icon` prop which accepts an icon name (such as `"history"`) or a JSX element to use as the icon.
- See the [**`Icon` component documentation**](#core/components/icon) for full API details. + +See the [**`Icon` component documentation**](#core/components/icon) for full API details.
@reactExample IconExample diff --git a/packages/labs/src/index.md b/packages/labs/src/index.md index dce3b82ee3..51c5005de6 100644 --- a/packages/labs/src/index.md +++ b/packages/labs/src/index.md @@ -6,7 +6,9 @@ reference: labs

Under construction

- The **[@blueprintjs/labs](https://www.npmjs.com/package/@blueprintjs/labs)** NPM package contains **unstable React components under active development by team members**. It is an incubator and staging area for components as we refine the API design; as such, this package will never reach 1.0.0, and every minor version should be considered breaking. + +The **[@blueprintjs/labs](https://www.npmjs.com/package/@blueprintjs/labs)** NPM package contains **unstable React components under active development by team members**. +It is an incubator and staging area for components as we refine the API design; as such, this package will never reach 1.0.0, and every minor version should be considered breaking.
There are currently no components in labs. diff --git a/packages/select/src/components/select/multi-select.md b/packages/select/src/components/select/multi-select.md index 68405835a0..8ec0b41503 100644 --- a/packages/select/src/components/select/multi-select.md +++ b/packages/select/src/components/select/multi-select.md @@ -4,7 +4,8 @@ Use `MultiSelect` for choosing multiple items in a list. The component render

Generic components and custom filtering

- For more information on controlled usage, generic components, creating new items, and custom filtering, visit the documentation for [`Select`](#select/select-component). + +For more information on controlled usage, generic components, creating new items, and custom filtering, visit the documentation for [`Select`](#select/select-component).
@reactExample MultiSelectExample diff --git a/packages/select/src/components/select/select-component.md b/packages/select/src/components/select/select-component.md index 05b6b549dd..fe277c60ff 100644 --- a/packages/select/src/components/select/select-component.md +++ b/packages/select/src/components/select/select-component.md @@ -4,9 +4,12 @@ Use `Select` for choosing one item from a list. The component's children will

Disabling a Select

-

Disabling the component requires setting the `disabled` prop to `true` - and separately disabling the component's children as appropriate (because `Select` accepts arbitrary children).

-

For example, ``

+ +Disabling the component requires setting the `disabled` prop to `true` +and separately disabling the component's children as appropriate (because `Select` accepts arbitrary children). + +For example, `` +
@reactExample SelectExample @@ -83,7 +86,8 @@ top of the basic `Select` interactions, such as windowed filtering for large data sets.
- To control the active item when a "Create Item" option is present, See [Controlling the active item](#select/select-component.controlling-the-active-item) in the "Creating new items" section below. + +To control the active item when a "Create Item" option is present, See [Controlling the active item](#select/select-component.controlling-the-active-item) in the "Creating new items" section below.
@## Creating new items @@ -99,11 +103,13 @@ will invoke `onItemSelect` with the item returned from `createNewItemFromQuery`.

Avoiding type conflicts

- The "Create Item" option is represented by the reserved type `ICreateNewItem` - exported from this package. It is exceedingly unlikely but technically possible - for your custom type `` to conflict with this type. If your type conflicts, - you may see unexpected behavior; to resolve, consider changing the schema for - your items. + +The "Create Item" option is represented by the reserved type `ICreateNewItem` +exported from this package. It is exceedingly unlikely but technically possible +for your custom type `` to conflict with this type. If your type conflicts, +you may see unexpected behavior; to resolve, consider changing the schema for +your items. +
```tsx diff --git a/packages/table/src/docs/table.md b/packages/table/src/docs/table.md index c6e8e9caee..549fa53db3 100644 --- a/packages/table/src/docs/table.md +++ b/packages/table/src/docs/table.md @@ -3,8 +3,9 @@ A highly interactive React `Table` component.
- If you are looking instead for the Blueprint-styled HTML `
`, see - [`HTMLTable` in **@blueprintjs/core**](#core/components/html-table). + +If you are looking instead for the Blueprint-styled HTML `
`, see +[`HTMLTable` in **@blueprintjs/core**](#core/components/html-table). Make sure to review the [getting started docs for installation info](#blueprint/getting-started). diff --git a/packages/timezone/src/components/timezone-picker/timezone-picker.md b/packages/timezone/src/components/timezone-picker/timezone-picker.md index a4e561685f..4fdf8a51a4 100644 --- a/packages/timezone/src/components/timezone-picker/timezone-picker.md +++ b/packages/timezone/src/components/timezone-picker/timezone-picker.md @@ -38,11 +38,12 @@ all button-specific props will be ignored:

Local timezone detection

- We detect the local timezone when the `showLocalTimezone` prop is enabled and cannot guarantee correctness in all browsers. - In supported browsers, the [i18n API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/resolvedOptions) is used. - In other browsers, `Date` methods and a population heuristic are used. - See [Moment Timezone's documentation](https://momentjs.com/timezone/docs/#/using-timezones/guessing-user-timezone/) - for more information and browser compatibility. + +We detect the local timezone when the `showLocalTimezone` prop is enabled and cannot guarantee correctness in all browsers. +In supported browsers, the [i18n API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat/resolvedOptions) is used. +In other browsers, `Date` methods and a population heuristic are used. +See [Moment Timezone's documentation](https://momentjs.com/timezone/docs/#/using-timezones/guessing-user-timezone/) +for more information and browser compatibility.
```tsx diff --git a/yarn.lock b/yarn.lock index 6426586638..5bbaec996a 100644 --- a/yarn.lock +++ b/yarn.lock @@ -5981,11 +5981,6 @@ marked@^0.4.0: resolved "https://registry.yarnpkg.com/marked/-/marked-0.4.0.tgz#9ad2c2a7a1791f10a852e0112f77b571dce10c66" integrity sha512-tMsdNBgOsrUophCAFQl0XPe6Zqk/uy9gnue+jIIKhykO51hxyu6uNx7zBPy0+y/WKYVZZMspV9YeXLNdKk+iYw== -marked@^0.5.2: - version "0.5.2" - resolved "https://registry.yarnpkg.com/marked/-/marked-0.5.2.tgz#3efdb27b1fd0ecec4f5aba362bddcd18120e5ba9" - integrity sha512-fdZvBa7/vSQIZCi4uuwo2N3q+7jJURpMVCcbaX0S1Mg65WZ5ilXvC67MviJAsdjqqgD+CEq4RKo5AYGgINkVAA== - marked@^0.6.2: version "0.6.2" resolved "https://registry.yarnpkg.com/marked/-/marked-0.6.2.tgz#c574be8b545a8b48641456ca1dbe0e37b6dccc1a"