diff --git a/.editorconfig b/.editorconfig index 72611bed18..38d0a2a141 100644 --- a/.editorconfig +++ b/.editorconfig @@ -13,7 +13,7 @@ indent_size = 2 indent_style = space # some files use 4 spaces for indentation -[*.{js,jsx,ts,tsx,java,xml}] +[*.{js,jsx,ts,tsx,java,xml,md}] indent_size = 4 [*.java] diff --git a/mdify.js b/mdify.js new file mode 100644 index 0000000000..a65cec3094 --- /dev/null +++ b/mdify.js @@ -0,0 +1,30 @@ +#!/usr/bin/env node + +const glob = require("glob"); +const fs = require("fs"); + +// captures: [title, body, reference] +const BLOCK_REGEX = /\/\*\n(.+)\n\n((?:.|\n)+?)\nStyleguide:? (.+)\n\*\//g; + +const HEADINGS = "######"; + +glob.sync("packages/core/src/components/*/*.scss") + .filter((filepath) => !/common\.scss$/.test(filepath)) + .forEach((comp) => { + const scss = fs.readFileSync(comp, "utf-8").replace(/^ */gm, ""); + const contents = [`---\nparent: ${comp.indexOf("/forms/") > 0 ? "forms" : "components"}\n---`]; + + /** @type {RegExpExecArray} */ + let match; + // tslint:disable-next-line:no-conditional-assignment + while ((match = BLOCK_REGEX.exec(scss)) !== null) { + const [title, body, reference] = match.slice(1); + const depth = reference.split(".").length - 1; + + contents.push( + `${HEADINGS.slice(0, depth)} ${title}`, + body.trim().replace(/@\w+(-\w+)/g, (tag, ext) => tag.replace(ext, ext[1].toUpperCase() + ext.slice(2))) + ); + } + fs.writeFileSync(comp.replace(".scss", ".md").replace("/_", "/"), contents.join("\n\n") + "\n"); + }); diff --git a/packages/core/src/components/_index.scss b/packages/core/src/components/_index.scss index a5ed195d0a..df0587d8d3 100644 --- a/packages/core/src/components/_index.scss +++ b/packages/core/src/components/_index.scss @@ -172,7 +172,6 @@ Styleguide components.usage.vanilla @import "callout/callout"; @import "card/card"; @import "collapse/collapse"; -@import "collapsible-list/collapsible-list"; @import "context-menu/context-menu"; @import "dialog/dialog"; @import "editable-text/editable-text"; diff --git a/packages/core/src/components/alert/_alert.scss b/packages/core/src/components/alert/_alert.scss index 299bb75bd2..63a8b9d7bf 100644 --- a/packages/core/src/components/alert/_alert.scss +++ b/packages/core/src/components/alert/_alert.scss @@ -5,37 +5,6 @@ @import "../../common/variables"; -/* -Alerts - -Alerts notify users of important information and force them to acknowledge the alert content before -continuing. - -Although similar to [dialogs](#components.dialog), alerts are more restrictive and should only be -used for important notifications. The user can only exit the alert by clicking one of the -confirmation buttons — clicking the overlay or pressing the esc key will -not close the alert. - -You can only use this component in controlled mode. Use the `onClick` handlers in the primary and -secondary action props to handle closing the `Alert`. Optionally, display an icon next to the body -to show the type of the alert. - -@react-example AlertExample - -Styleguide components.alert -*/ - -/* -JavaScript API - -The `Alert` component is available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -@interface IAlertProps - -Styleguide components.alert.js -*/ - .pt-alert { max-width: $pt-grid-size * 40; padding: $pt-grid-size * 2; diff --git a/packages/core/src/components/alert/alert.md b/packages/core/src/components/alert/alert.md new file mode 100644 index 0000000000..c51e51cddd --- /dev/null +++ b/packages/core/src/components/alert/alert.md @@ -0,0 +1,21 @@ +@# Alerts + +Alerts notify users of important information and force them to acknowledge the alert content before +continuing. + +Although similar to [dialogs](#components.dialog), alerts are more restrictive and should only be +used for important informations. The user can only exit the alert by clicking one of the +confirmation buttons—clicking the overlay or pressing the `esc` key will not close the alert. + +You can only use this component in controlled mode. Use the `onClick` handlers in the primary and +secondary action props to handle closing the `Alert`. Optionally, display an icon next to the body +to show the type of the alert. + +@reactExample AlertExample + +@## JavaScript API + +The `Alert` component is available in the __@blueprintjs/core__ package. +Make sure to review the [general usage docs for JS components](#components.usage). + +@interface IAlertProps diff --git a/packages/core/src/components/breadcrumbs/_breadcrumbs.scss b/packages/core/src/components/breadcrumbs/_breadcrumbs.scss index 588a55768d..9676b20d3f 100644 --- a/packages/core/src/components/breadcrumbs/_breadcrumbs.scss +++ b/packages/core/src/components/breadcrumbs/_breadcrumbs.scss @@ -8,31 +8,6 @@ @import "../../common/variables"; /* -Breadcrumbs - -Breadcrumbs identify the current resource in an application. - -Styleguide components.breadcrumbs -*/ - -/* -CSS API - -* Begin with a `ul.pt-breadcrumbs`; each crumb should be in its own `li` as a direct descendant. -* Breadcrumbs are typically navigation links (for example, to the parent folder in a file path), and - therefore should use `` tags (except for the final breadcrumb). -* Each navigation breadcrumb should use `.pt-breadcrumb`. -* Make a breadcrumb non-interactive with the `.pt-disabled` class. You should only use this - state when you want to indicate that the user cannot navigate to the breadcrumb (for example, if - the user does not have permission to access it). Otherwise, clicking a breadcrumb should take the - user to that resource. -* Mark the final breadcrumb `.pt-breadcrumb-current` for an emphasized appearance. -* The `.pt-breadcrumbs-collapsed` button-like element can be used as the target for a dropdown menu - containing breadcrumbs that are collapsed due to layout constraints. -* When adding another element (such as a [tooltip](#components.tooltip) or - [popover](#components.popover)) to a breadcrumb, wrap it around the contents of the `li`. - - Markup: - -Styleguide components.breadcrumbs.css -*/ - -/* -JavaScript API - -The `Breadcrumb` component is available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -The component renders an `a.pt-breadcrumb`. -You are responsible for constructing the `ul.pt-breadcrumbs` list. -[`CollapsibleList`](#components.collapsiblelist) works nicely with this component -because its props are a subset of `IMenuItemProps`. - -@interface IBreadcrumbProps - -Styleguide components.breadcrumbs.js */ // shaving off 1px for perfect centering (... icon is 5px high) diff --git a/packages/core/src/components/breadcrumbs/breadcrumbs.md b/packages/core/src/components/breadcrumbs/breadcrumbs.md new file mode 100644 index 0000000000..24d555d237 --- /dev/null +++ b/packages/core/src/components/breadcrumbs/breadcrumbs.md @@ -0,0 +1,30 @@ +@# Breadcrumbs + +Breadcrumbs identify the current resource in an application. + +@## CSS API + +* Begin with a `ul.pt-breadcrumbs`; each crumb should be in its own `li` as a direct descendant. +* Breadcrumbs are typically navigation links (for example, to the parent folder in a file path), and +therefore should use `` tags (except for the final breadcrumb). +* Each navigation breadcrumb should use `.pt-breadcrumb`. +* Make a breadcrumb non-interactive with the `.pt-disabled` class. You should only use this +state when you want to indicate that the user cannot navigate to the breadcrumb (for example, if +the user does not have permission to access it). Otherwise, clicking a breadcrumb should take the +user to that resource. +* Mark the final breadcrumb `.pt-breadcrumb-current` for an emphasized appearance. +* The `.pt-breadcrumbs-collapsed` button-like element can be used as the target for a dropdown menu +containing breadcrumbs that are collapsed due to layout constraints. +* When adding another element (such as a [tooltip](#components.tooltip) or +[popover](#components.popover)) to a breadcrumb, wrap it around the contents of the `li`. + +@## JavaScript API + +The `Breadcrumb` component is available in the __@blueprintjs/core__ package. +Make sure to review the [general usage docs for JS components](#components.usage). + +The component renders an `a.pt-breadcrumb`. You are responsible for constructing +the `ul.pt-breadcrumbs` list. [`CollapsibleList`](#components.collapsiblelist) +works nicely with this component because its props are a subset of `IMenuItemProps`. + +@interface IBreadcrumbProps diff --git a/packages/core/src/components/button/_button-group.scss b/packages/core/src/components/button/_button-group.scss index f7ae0a08f0..f9193e7d23 100644 --- a/packages/core/src/components/button/_button-group.scss +++ b/packages/core/src/components/button/_button-group.scss @@ -9,21 +9,6 @@ @import "./common"; /* -Button groups - -Button groups arrange multiple buttons in a horizontal or vertical group. - -Styleguide components.button-group -*/ - -/* -CSS API - -Arrange multiple buttons in a group by wrapping them in `.pt-button-group`. -You can apply sizing directly on the button group container element. - -You should implement interactive segmented controls as button groups. - Markup:
Queries @@ -53,8 +38,6 @@ Markup: .pt-large - Use large buttons .pt-minimal - Use minimal buttons. Note that these minimal buttons will not automatically truncate text in an ellipsis because of the divider line added in CSS. - -Styleguide components.button-group.css */ .pt-button-group { @@ -167,17 +150,6 @@ Styleguide components.button-group.css } /* - Responsive button groups - - Add the class `pt-fill` to a button group to make all buttons expand equally to fill the - available space. Then add the class `pt-fixed` to individual buttons to revert them to their - original default sizes. - - Alternatively, add the class `pt-fill` to an individual button (instead of to the container) - to expand it to fill the available space while other buttons retain their original sizes. - - You can adjust the specific size of a button with the `flex-basis` CSS property. - Markup:
Start @@ -192,8 +164,6 @@ Styleguide components.button-group.css
- - Styleguide components.button-group.css.fill */ &.pt-fill { @@ -206,23 +176,14 @@ Styleguide components.button-group.css } /* - Vertical button groups - - Add the class `pt-vertical` to create a vertical button group. The buttons in a vertical - group all have the same size as the widest button in the group. - - Add the modifier class `pt-align-left` to left-align all button text and icons. - - You can also combine vertical groups with the `pt-fill` and `pt-minimal` class modifiers. - Markup: -
+
-
+
@@ -233,8 +194,6 @@ Styleguide components.button-group.css
- - Styleguide components.button-group.css.vertical */ &.pt-vertical { diff --git a/packages/core/src/components/button/_button.scss b/packages/core/src/components/button/_button.scss index 343a27ad99..9fa88da501 100644 --- a/packages/core/src/components/button/_button.scss +++ b/packages/core/src/components/button/_button.scss @@ -8,27 +8,6 @@ @import "./common"; /* -Buttons - -Buttons trigger actions when clicked. - -Styleguide components.button -*/ - -/* -CSS API - -Use the `pt-button` class to access button styles. You should implement buttons using the -` @@ -42,8 +21,6 @@ Markup: .pt-active - Active appearance .pt-large - Larger size .pt-fill - Fill parent container - -Styleguide components.button.css */ .pt-button { @@ -87,22 +64,12 @@ Styleguide components.button.css } } - /* - Buttons with icons - - Add an icon before the button text with `pt-icon-*` classes. - You _do not_ need to include an icon sizing class. - Markup: - - Weight: -1 - - Styleguide components.button.css.icon */ &[class*="pt-icon-"]::before { @@ -113,14 +80,6 @@ Styleguide components.button.css } /* - Advanced icon layout - - You can use a `pt-icon-*` class on a button to add a single icon before the button - text, but for more advanced icon layouts, use `` tags inside the button. - Add multiple icons to the same button, or move icons after the text. - - To adjust margins on right-aligned icons, add the class `pt-align-right` to the icon. - Markup: - - Styleguide components.button.css.advanced */ #{$icon-classes} { @@ -187,14 +144,6 @@ Styleguide components.button.css } /* - Minimal buttons - - For a subtler button that appears to fade into the UI, add the `.pt-minimal` modifier - to any `.pt-button`. `pt-minimal` is compatible with all other button modifiers, - except for `.pt-fill` (due to lack of visual affordances). - - Note that minimal buttons are _not supported_ in button groups at this time. - Markup: Anchor @@ -204,8 +153,6 @@ Styleguide components.button.css .pt-intent-success - Success intent .pt-intent-warning - Warning intent .pt-intent-danger - Danger intent - - Styleguide components.button.css.minimal */ &.pt-minimal { @@ -281,58 +228,3 @@ a.pt-button { // stylelint-disable-next-line scss/at-extend-no-missing-placeholder @extend .pt-button:disabled; } - -/* -JavaScript API - -The `Button` and `AnchorButton` components are available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -Button components render buttons with Blueprint classes and attributes. -See the [Buttons CSS docs](#components.button.css) for styling options. - -You can provide your own props to these components as if they were regular JSX HTML elements. If you -provide a `className` prop, the class names you provide will be added alongside of the default -Blueprint class name. If you specify other attributes that the component provides, such as a `role` -for an ``, you'll overide the default value. - -
-
Interactions with disabled buttons
- Use `AnchorButton` if you need mouse interaction events (such as hovering) on a disabled button. - This is because `Button` and `AnchorButton` handle the `disabled` prop differently: `Button` uses - the native `disabled` attribute on the `
- -@react-example ButtonsExample - -Styleguide components.button.js -*/ - -/* -Anchor button - -``` - -// renders: -Click -``` - -Styleguide: components.button.js.anchor-button -*/ - -/* -Button - -``` - -``` - -@interface IButtonProps - -Styleguide: components.button.js.button -*/ diff --git a/packages/core/src/components/button/button-group.md b/packages/core/src/components/button/button-group.md new file mode 100644 index 0000000000..a3165a7079 --- /dev/null +++ b/packages/core/src/components/button/button-group.md @@ -0,0 +1,30 @@ +@# Button groups + +Button groups arrange multiple buttons in a horizontal or vertical group. + +@## CSS API + +Arrange multiple buttons in a group by wrapping them in `.pt-button-group`. +You can apply sizing directly on the button group container element. + +You should implement interactive segmented controls as button groups. + +@### Responsive button groups + +Add the class `pt-fill` to a button group to make all buttons expand equally to fill the +available space. Then add the class `pt-fixed` to individual buttons to revert them to their +original default sizes. + +Alternatively, add the class `pt-fill` to an individual button (instead of to the container) +to expand it to fill the available space while other buttons retain their original sizes. + +You can adjust the specific size of a button with the `flex-basis` CSS property. + +@### Vertical button groups + +Add the class `pt-vertical` to create a vertical button group. The buttons in a vertical +group all have the same size as the widest button in the group. + +Add the modifier class `pt-align-left` to left-align all button text and icons. + +You can also combine vertical groups with the `pt-fill` and `pt-minimal` class modifiers. diff --git a/packages/core/src/components/button/button.md b/packages/core/src/components/button/button.md new file mode 100644 index 0000000000..56fa887fb1 --- /dev/null +++ b/packages/core/src/components/button/button.md @@ -0,0 +1,80 @@ +@# Buttons + +Buttons trigger actions when clicked. + +@## CSS API + +Use the `pt-button` class to access button styles. You should implement buttons using the +`
+ +@reactExample ButtonsExample + +@### Anchor button + +``` + +// renders: +Click +``` + +@### Button + +``` + +``` + +@interface IButtonProps diff --git a/packages/core/src/components/callout/_callout.scss b/packages/core/src/components/callout/_callout.scss index 05d61d85a5..11e95e270e 100644 --- a/packages/core/src/components/callout/_callout.scss +++ b/packages/core/src/components/callout/_callout.scss @@ -7,23 +7,6 @@ @import "../../common/variables"; /* -Callouts - -Callouts visually highlight important content for the user. - -Styleguide components.callout -*/ - -/* -CSS API - -Callouts use the same visual intent modifier classes as buttons. If you need a -heading, use the `
` element. - -
- Note that the `
` heading is entirely optional. -
- Markup:
Callout Heading
@@ -35,8 +18,6 @@ Markup: .pt-intent-warning - Warning intent .pt-intent-danger - Danger intent .pt-icon-info-sign - With an icon - -Styleguide components.callout.css */ .pt-callout { diff --git a/packages/core/src/components/callout/callout.md b/packages/core/src/components/callout/callout.md new file mode 100644 index 0000000000..2b391eb203 --- /dev/null +++ b/packages/core/src/components/callout/callout.md @@ -0,0 +1,12 @@ +@# Callouts + +Callouts visually highlight important content for the user. + +@## CSS API + +Callouts use the same visual intent modifier classes as buttons. If you need a +heading, use the `
` element. + +
+ Note that the `
` heading is entirely optional. +
diff --git a/packages/core/src/components/card/_card.scss b/packages/core/src/components/card/_card.scss index 7b8cfa05f5..afd8305349 100644 --- a/packages/core/src/components/card/_card.scss +++ b/packages/core/src/components/card/_card.scss @@ -6,22 +6,6 @@ @import "../../common/variables"; /* -Cards - -A card is a bounded unit of UI content with a solid background color. - -Styleguide components.card -*/ - -/* -CSS API - -Start with `.pt-card` and add an elevation modifier class to apply a drop shadow that simulates -height in the UI. - -You can also use the `.pt-elevation-*` classes by themselves to apply shadows to any arbitrary -element. - Markup:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus nec dapibus et mauris, @@ -33,8 +17,6 @@ Markup: .pt-elevation-2 - Second. An even stronger shadow, moving on up. .pt-elevation-3 - Third. For containers overlaying content temporarily. .pt-elevation-4 - Fourth. The strongest shadow, usually for overlay containers on top of backdrops. - -Styleguide components.card.css */ $card-padding: $pt-grid-size * 2 !default; @@ -84,14 +66,6 @@ $dark-elevation-shadows: ( } /* -Interactive cards - -Add the `.pt-interactive` modifier class to make a `.pt-card` respond to user interactions. When you -hover over cards with this class applied, the mouse changes to a pointer and the elevation shadow on -the card increases by two levels. - -Users expect an interactive card to be a single clickable unit. - Markup:
@@ -107,8 +81,6 @@ Markup:

Stats of dataset completeness and reference data join percentages.

- -Styleguide components.card.css.interactive */ .pt-card.pt-interactive { diff --git a/packages/core/src/components/card/card.md b/packages/core/src/components/card/card.md new file mode 100644 index 0000000000..b7e4ed228c --- /dev/null +++ b/packages/core/src/components/card/card.md @@ -0,0 +1,19 @@ +@# Cards + +A card is a bounded unit of UI content with a solid background color. + +@## CSS API + +Start with `.pt-card` and add an elevation modifier class to apply a drop shadow that simulates +height in the UI. + +You can also use the `.pt-elevation-*` classes by themselves to apply shadows to any arbitrary +element. + +@### Interactive cards + +Add the `.pt-interactive` modifier class to make a `.pt-card` respond to user interactions. When you +hover over cards with this class applied, the mouse changes to a pointer and the elevation shadow on +the card increases by two levels. + +Users expect an interactive card to be a single clickable unit. diff --git a/packages/core/src/components/collapse/_collapse.scss b/packages/core/src/components/collapse/_collapse.scss index 0f2c135c04..f036b3f443 100644 --- a/packages/core/src/components/collapse/_collapse.scss +++ b/packages/core/src/components/collapse/_collapse.scss @@ -5,66 +5,6 @@ @import "../../common/variables"; -/* -Collapse - -The `Collapse` element shows and hides content with a built-in slide in/out animation. -You might use this to create a panel of settings for your application, with sub-sections -that can be expanded and collapsed. - -@react-example CollapseExample - -Styleguide components.collapse -*/ - -/* -JavaScript API - -The `Collapse` component is available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -Any content should be a child of the `Collapse` element. Content must be in the document -flow (e.g. `position: absolute;` wouldn't work, as the parent element would inherit a height of 0). - -Toggling the `isOpen` prop triggers the open and close animations. -Once the component is in the closed state, the children are no longer rendered. - -``` -export interface ICollapseExampleState { - isOpen?: boolean; -}; - -export class CollapseExample extends React.Component<{}, ICollapseExampleState> { - public state = { - isOpen: false, - }; - - public render() { - return ( -
- - - 
-                        Dummy text.
-
- -
- ); - } - - private handleClick = () => { - this.setState({isOpen: !this.state.isOpen}); - } -} -``` - -@interface ICollapseProps - -Styleguide components.collapse.js -*/ - $collapse-transition: ($pt-transition-duration * 2) $pt-transition-ease !default; .pt-collapse { diff --git a/packages/core/src/components/collapse/collapse.md b/packages/core/src/components/collapse/collapse.md new file mode 100644 index 0000000000..04a03ca18b --- /dev/null +++ b/packages/core/src/components/collapse/collapse.md @@ -0,0 +1,51 @@ +@# Collapse + +The `Collapse` element shows and hides content with a built-in slide in/out animation. +You might use this to create a panel of settings for your application, with sub-sections +that can be expanded and collapsed. + +@reactExample CollapseExample + +@## JavaScript API + +The `Collapse` component is available in the __@blueprintjs/core__ package. +Make sure to review the [general usage docs for JS components](#components.usage). + +Any content should be a child of the `Collapse` element. Content must be in the document +flow (e.g. `position: absolute;` wouldn't work, as the parent element would inherit a height of 0). + +Toggling the `isOpen` prop triggers the open and close animations. +Once the component is in the closed state, the children are no longer rendered. + +``` +export interface ICollapseExampleState { + isOpen?: boolean; +}; + +export class CollapseExample extends React.Component<{}, ICollapseExampleState> { + public state = { + isOpen: false, + }; + + public render() { + return ( +
+ + + 
+                        Dummy text.
+
+ +
+ ); + } + + private handleClick = () => { + this.setState({ isOpen: !this.state.isOpen }); + } +} +``` + +@interface ICollapseProps diff --git a/packages/core/src/components/collapsible-list/_collapsible-list.scss b/packages/core/src/components/collapsible-list/collapsible-list.md similarity index 64% rename from packages/core/src/components/collapsible-list/_collapsible-list.scss rename to packages/core/src/components/collapsible-list/collapsible-list.md index 0bd0eea7d3..88f88d95a2 100644 --- a/packages/core/src/components/collapsible-list/_collapsible-list.scss +++ b/packages/core/src/components/collapsible-list/collapsible-list.md @@ -1,23 +1,13 @@ -// Copyright 2015 Palantir Technologies, Inc. All rights reserved. -// Licensed under the BSD-3 License as modified (the “License”); you may obtain a copy -// of the license at https://github.com/palantir/blueprint/blob/master/LICENSE -// and https://github.com/palantir/blueprint/blob/master/PATENTS - -/* -Collapsible list +@# Collapsible list The `CollapsibleList` React component accepts a list of menu items and a count of visible items. It shows precisely that many items and collapses the rest into a dropdown menu. The required `renderVisibleItem` callback prop allows for customizing the appearance of visible items, using the props from the `MenuItem` children. -@react-example CollapsibleListExample - -Styleguide components.collapsiblelist -*/ +@reactExample CollapsibleListExample -/* -JavaScript API +@## JavaScript API The `CollapsibleList` component is available in the __@blueprintjs/core__ package. Make sure to review the [general usage docs for JS components](#components.usage). @@ -28,13 +18,7 @@ items using their [`IMenuItemProps`](#components.menu.js.menu-item). @interface ICollapsibleListProps -Weight: -10 - -Styleguide components.collapsiblelist.js -*/ - -/* -Separators +@## Separators Often a list of items calls for separators between each item. Adding separators to a `CollapsibleList` is easily achieved via CSS using `::after` pseudo-elements. @@ -43,16 +27,13 @@ Adding separators to a `CollapsibleList` is easily achieved via CSS using `::aft // pass `visibleItemClassName="my-list-item"` to component, then... .my-list-item::after { - display: inline-block; - content: ""; - // custom separator styles... + display: inline-block; + content: ""; + // custom separator styles... } // remove separator after the last item .my-list-item:last-child::after { - display: none; + display: none; } ``` - -Styleguide components.collapsiblelist.separator -*/ diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md new file mode 100644 index 0000000000..e9f6b3a538 --- /dev/null +++ b/packages/core/src/components/components.md @@ -0,0 +1,35 @@ +@# Components + +@## Usage + +Use them like you normally do. + + + +@page alert +@page breadcrumbs +@page button +@page callout +@page card +@page collapse +@page collapsible-list +@page context-menu + +@page dialog +@page editable-text + +@page hotkeys +@page menu +@page navbar +@page non-ideal-state +@page overlay +@page popover +@page portal + +@page slider +@page table +@page tabs +@page tag +@page toast +@page tooltip +@page tree diff --git a/packages/core/src/components/context-menu/_context-menu.scss b/packages/core/src/components/context-menu/_context-menu.scss index 1c6ae0e4bb..14da431223 100644 --- a/packages/core/src/components/context-menu/_context-menu.scss +++ b/packages/core/src/components/context-menu/_context-menu.scss @@ -3,124 +3,6 @@ // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE // and https://github.com/palantir/blueprint/blob/master/PATENTS -/* -Context menus - -Context menus present the user with a custom list of actions upon right-click. - -You can create context menus in either of the following ways: - -- by adding the `@ContextMenuTarget` [decorator](#components.context-menu.decorator) to a React - component that implements `renderContextMenu(): JSX.Element`. -- via the [imperative](#components.context-menu.js) `ContextMenu.show` and `ContextMenu.hide` API - methods, ideal for non-React-based applications. - -@react-example ContextMenuExample - -Styleguide components.context-menu -*/ - -/* -JavaScript API: decorator - -The `ContextMenuTarget` decorator is available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -The `@ContextMenuTarget` [class decorator][ts-decorator] can be applied to any `React.Component` -class that meets the following requirements: - -- It defines an instance method called `renderContextMenu()` that returns a single `JSX.Element` - (most likely a [`Menu`](#components.menu)). -- Its root element supports the `"contextmenu"` event and the `onContextMenu` prop. - - This is always true if the decorated class uses an intrinsic element, such as `
`, as its - root. If it uses a custom element as its root, you must ensure that the prop is implemented - correctly for that element. - -When the user triggers the `"contextmenu"` event on the decorated class, `renderContextMenu()` is -called. If `renderContextMenu()` returns an element, the browser's native [context menu][wiki-cm] is -blocked and the returned element is displayed instead in a `Popover` at the cursor's location. - -If the instance has a `onContextMenuClose` method, the decorator will call this function when -the context menu is closed. - -``` -import { ContextMenuTarget, Menu, MenuItem } from "@blueprintjs/core"; - -@ContextMenuTarget -class RightClickMe extends React.Component<{}, {}> { - public render() { - // root element must support `onContextMenu` - return
{...}
; - } - - public renderContextMenu() { - // return a single element, or nothing to use default browser behavior - return ( - - - - - ); - } - - public onContextMenuClose() { - // Optional method called once the context menu is closed. - } -} -``` - -[ts-decorator]: https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Decorators.md -[wiki-cm]: https://en.wikipedia.org/wiki/Context_menu - -Styleguide components.context-menu.decorator -*/ - -/* -JavaScript API: imperative - -The `ContextMenu` component is available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -The imperative API provides a single static `ContextMenu` object, enforcing the principle that only -one context menu can be open at a time. - -- `ContextMenu.show(menu: JSX.Element, offset: IOffset, onClose?: () => void): void` – - Show the given element at the given offset from the top-left corner of the viewport. - Showing a menu closes the previously shown one automatically. - - The menu appears below-right of this point, but will flip to below-left instead if there is not - enough room onscreen. The optional callback is invoked when this menu closes. - -- `ContextMenu.hide(): void` – Hide the context menu, if it is open. -- `ContextMenu.isOpen(): boolean` – Whether a context menu is currently visible. - -This API is ideal for non-React-based apps or for programmatically triggered menus. - -``` -import { ContextMenu, MenuFactory, MenuItemFactory } from "@blueprintjs/core"; - -const rightClickMe = document.query("#right-click-me") as HTMLElement; -rightClickMe.oncontextmenu = (e: MouseEvent) => { - // prevent the browser's native context menu - e.preventDefault(); - // render a Menu without JSX... - const menu = MenuFactory({ - children: [ - MenuItemFactory({ onClick: handleSave, text: "Save" }), - MenuItemFactory({ onClick: handleDelete, text: "Delete" }), - ] - }); - // mouse position is available on event - ContextMenu.show(menu, { left: e.clientX, top: e.clientY }, () => { - // menu was closed; callback optional - }); -}; -``` - -Styleguide components.context-menu.js -*/ - .pt-context-menu .pt-popover-target { display: block; } diff --git a/packages/core/src/components/context-menu/context-menu.md b/packages/core/src/components/context-menu/context-menu.md new file mode 100644 index 0000000000..62f9f99851 --- /dev/null +++ b/packages/core/src/components/context-menu/context-menu.md @@ -0,0 +1,107 @@ +@# Context menus + +Context menus present the user with a custom list of actions upon right-click. + +You can create context menus in either of the following ways: + +- by adding the `@ContextMenuTarget` [decorator](#components.context-menu.decorator) to a React +component that implements `renderContextMenu(): JSX.Element`. +- via the [imperative](#components.context-menu.js) `ContextMenu.show` and `ContextMenu.hide` API +methods, ideal for non-React-based applications. + +@reactExample ContextMenuExample + +@## JavaScript API: decorator + +The `ContextMenuTarget` decorator is available in the __@blueprintjs/core__ package. +Make sure to review the [general usage docs for JS components](#components.usage). + +The `@ContextMenuTarget` [class decorator][ts-decorator] can be applied to any `React.Component` +class that meets the following requirements: + +- It defines an instance method called `renderContextMenu()` that returns a single `JSX.Element` +(most likely a [`Menu`](#components.menu)). +- Its root element supports the `"contextmenu"` event and the `onContextMenu` prop. + +This is always true if the decorated class uses an intrinsic element, such as `
`, as its +root. If it uses a custom element as its root, you must ensure that the prop is implemented +correctly for that element. + +When the user triggers the `"contextmenu"` event on the decorated class, `renderContextMenu()` is +called. If `renderContextMenu()` returns an element, the browser's native [context menu][wiki-cm] is +blocked and the returned element is displayed instead in a `Popover` at the cursor's location. + +If the instance has a `onContextMenuClose` method, the decorator will call this function when +the context menu is closed. + +``` +import { ContextMenuTarget, Menu, MenuItem } from "@blueprintjs/core"; + +@ContextMenuTarget +class RightClickMe extends React.Component<{}, {}> { + public render() { + // root element must support `onContextMenu` + return
{...}
; + } + + public renderContextMenu() { + // return a single element, or nothing to use default browser behavior + return ( + + + + + ); + } + + public onContextMenuClose() { + // Optional method called once the context menu is closed. + } +} +``` + +[ts-decorator]: https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Decorators.md +[wiki-cm]: https://en.wikipedia.org/wiki/Context_menu + +@## JavaScript API: imperative + +The `ContextMenu` component is available in the __@blueprintjs/core__ package. +Make sure to review the [general usage docs for JS components](#components.usage). + +The imperative API provides a single static `ContextMenu` object, enforcing the principle that only +one context menu can be open at a time. + +- `ContextMenu.show(menu: JSX.Element, offset: IOffset, onClose?: () => void): void` – +Show the given element at the given offset from the top-left corner of the viewport. +Showing a menu closes the previously shown one automatically. + +The menu appears below-right of this point, but will flip to below-left instead if there is not +enough room onscreen. The optional callback is invoked when this menu closes. + +- `ContextMenu.hide(): void` – Hide the context menu, if it is open. +- `ContextMenu.isOpen(): boolean` – Whether a context menu is currently visible. + +This API is ideal for non-React-based apps or for programmatically triggered menus. + +``` +import { ContextMenu, MenuFactory, MenuItemFactory } from "@blueprintjs/core"; + +const rightClickMe = document.query("#right-click-me") as HTMLElement; +rightClickMe.oncontextmenu = (e: MouseEvent) => { + // prevent the browser's native context menu + e.preventDefault(); + + // render a Menu without JSX... + const menu = MenuFactory({ + children: [ + MenuItemFactory({ onClick: handleSave, text: "Save" }), + MenuItemFactory({ onClick: handleDelete, text: "Delete" }), + ] + }); + + // mouse position is available on event + ContextMenu.show(menu, { left: e.clientX, top: e.clientY }, () => { + // menu was closed; callback optional + }); +}; +``` diff --git a/packages/core/src/components/dialog/_dialog.scss b/packages/core/src/components/dialog/_dialog.scss index da4f69de6e..dbc74aa3a6 100644 --- a/packages/core/src/components/dialog/_dialog.scss +++ b/packages/core/src/components/dialog/_dialog.scss @@ -10,82 +10,24 @@ @import "../../common/variables"; /* -Dialogs - -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. +Markup: +
+
+ +
Dialog header
+ +
+
+ This dialog hasn't been wired up with any open or close interactions. + It's just an example of markup and styles. +
+
+
+ + +
+
- -Styleguide components.dialog -*/ - -/* -JavaScript API - -The `Dialog` component is available in the __@blueprintjs/core__ package. -Make sure to review the [general usage docs for JS components](#components.usage). - -There are two ways to render dialogs: - -- in-place in the DOM tree. This is the default behavior. -- injected into a newly created element attached to `document.body`. - Set `inline={false}` to enable this. - -`Dialog` is implemented as a stateless React component. The children you provide to this component -are rendered as contents inside the `.pt-dialog` element. - -``` -interface IDialogExampleState { - isOpen: boolean; -} - -class DialogExample extends React.Component<{}, IDialogExampleState> { - public state = { isOpen: false }; - - public render() { - return ( -
-
-
- -
- ); - } - - private toggleDialog = () => this.setState({ isOpen: !this.state.isOpen }); -} -``` - -@interface IDialogProps - -@react-example DialogExample - -Styleguide components.dialog.js */ $dialog-border-radius: $pt-border-radius * 2 !default; @@ -208,34 +150,3 @@ $dialog-padding: $pt-grid-size * 2 !default; margin-left: $pt-grid-size; } } - -/* -CSS API - -You can create dialogs manually using the HTML markup and `pt-dialog-*` classes below. -However, you should use the dialog [JavaScript APIs](#components.dialog.js) whenever possible, -as they automatically generate some of this markup. - -More examples of dialog content are shown below. - -Markup: -
-
- -
Dialog header
- -
-
- This dialog hasn't been wired up with any open or close interactions. - It's just an example of markup and styles. -
-
-
- - -
-
-
- -Styleguide components.dialog.css -*/ diff --git a/packages/core/src/components/dialog/dialog.md b/packages/core/src/components/dialog/dialog.md new file mode 100644 index 0000000000..369e3b0c8e --- /dev/null +++ b/packages/core/src/components/dialog/dialog.md @@ -0,0 +1,78 @@ +@# Dialogs + +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. +
+ +@## JavaScript API + +The `Dialog` component is available in the __@blueprintjs/core__ package. +Make sure to review the [general usage docs for JS components](#components.usage). + +There are two ways to render dialogs: + +- in-place in the DOM tree. This is the default behavior. +- injected into a newly created element attached to `document.body`. +Set `inline={false}` to enable this. + +`Dialog` is implemented as a stateless React component. The children you provide to this component +are rendered as contents inside the `.pt-dialog` element. + +``` +interface IDialogExampleState { + isOpen: boolean; +} + +class DialogExample extends React.Component<{}, IDialogExampleState> { + public state = { isOpen: false }; + + public render() { + return ( +
+
+
+ +
+ ); + } + + private toggleDialog = () => this.setState({ isOpen: !this.state.isOpen }); +} +``` + +@interface IDialogProps + +@reactExample DialogExample + +@## CSS API + +You can create dialogs manually using the HTML markup and `pt-dialog-*` classes below. +However, you should use the dialog [JavaScript APIs](#components.dialog.js) whenever possible, +as they automatically generate some of this markup. + +More examples of dialog content are shown below. diff --git a/packages/core/src/components/editable-text/_editable-text.scss b/packages/core/src/components/editable-text/_editable-text.scss index 669a8c5a1c..4acfdde448 100644 --- a/packages/core/src/components/editable-text/_editable-text.scss +++ b/packages/core/src/components/editable-text/_editable-text.scss @@ -7,82 +7,6 @@ @import "../../common/variables"; @import "../forms/common"; -/* -Editable text - -`EditableText` looks like normal UI text, but transforms into a text input field when the user -focuses it. - -The text input inherits all font styling from its ancestors, making the transition between reading -and editing text seamless. - -You might use this component for inline renaming, or for an [editable multiline -description](#components.editable.multiline). You should not use `EditableText` when a static -always-editable `` or ` @@ -100,10 +71,6 @@ Markup: .pt-intent-primary - Primary intent .pt-intent-danger - Danger intent .pt-fill - Take up full width of parent element - -Weight: 3 - -Styleguide components.forms.textarea */ // stylelint-disable selector-no-qualifying-type diff --git a/packages/core/src/components/forms/_label.scss b/packages/core/src/components/forms/_label.scss index 9770f7af28..f9c6e7172c 100644 --- a/packages/core/src/components/forms/_label.scss +++ b/packages/core/src/components/forms/_label.scss @@ -6,32 +6,6 @@ @import "../../common/variables"; /* -Labels - -Labels enhance the usability of your forms. - -
-
Simple labels vs. form groups
-

Blueprint provides two ways of connecting label text to control fields, depending on the complexity of the control.

-

Simple labels are a basic way to connect a label with a single control.

-

Form groups support more complex control layouts but require more markup to maintain consistent visuals.

-
- -Weight: 1 - -Styleguide components.forms.labels -*/ - -/* -Simple labels - -Simple labels are useful for basic forms for a single ``. - -- Add extra information to the label with `span.pt-text-muted`. - -- Putting the `` element _inside_ a `