From bcce1c5d572b7fc6baa956a8549ccba34057671b Mon Sep 17 00:00:00 2001 From: Gilad Gray Date: Tue, 14 Mar 2017 18:51:54 -0700 Subject: [PATCH] [DM] docs for all packages (#818) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * run all packages through Documentalist (easy glob change 👍) * index.md page for each package, _nav in docs * update nesting in datetime docs * title in styleguide * change default page * fix Table links, rename page to just Table * move color aliases table styles to live with its family --- gulp/docs.js | 2 +- packages/core/src/components/table/table.md | 2 +- packages/core/src/docs/_nav.md | 11 - packages/core/src/docs/color-aliases.md | 418 +++++++++++--------- packages/core/src/docs/index.md | 18 + packages/datetime/src/dateinput.md | 4 +- packages/datetime/src/datepicker.md | 6 +- packages/datetime/src/index.md | 35 ++ packages/docs/src/_nav.md | 8 + packages/docs/src/index.tsx | 5 +- packages/docs/src/styleguide.md | 3 +- packages/docs/src/styles/_colors.scss | 14 + packages/docs/src/styles/_sections.scss | 16 - packages/table/src/docs.md | 43 +- 14 files changed, 350 insertions(+), 235 deletions(-) delete mode 100644 packages/core/src/docs/_nav.md create mode 100644 packages/core/src/docs/index.md create mode 100644 packages/datetime/src/index.md create mode 100644 packages/docs/src/_nav.md diff --git a/gulp/docs.js b/gulp/docs.js index ce77edd198..326d596b1b 100644 --- a/gulp/docs.js +++ b/gulp/docs.js @@ -28,7 +28,7 @@ module.exports = (blueprint, gulp, plugins) => { gulp.task("docs-json", () => { return dm.Documentalist.create({ renderer: text.renderer }) .use(".scss", new dm.KssPlugin()) - .documentGlobs("packages/core/src/**/*") + .documentGlobs("packages/*/src/**/*") .then((contents) => { function nestChildPage(child, parent) { const originalRef = child.reference; diff --git a/packages/core/src/components/table/table.md b/packages/core/src/components/table/table.md index 958a97872d..a1829aa09f 100644 --- a/packages/core/src/components/table/table.md +++ b/packages/core/src/components/table/table.md @@ -6,7 +6,7 @@ This component adds 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**](#components.table-js). + spreadsheet-like features, check out [**@blueprintjs/table**](#table-js). @## CSS API diff --git a/packages/core/src/docs/_nav.md b/packages/core/src/docs/_nav.md deleted file mode 100644 index 8b27064607..0000000000 --- a/packages/core/src/docs/_nav.md +++ /dev/null @@ -1,11 +0,0 @@ - - -@page accessibility -@page colors -@page typography -@page icons -@page variables -@page components -@page resources diff --git a/packages/core/src/docs/color-aliases.md b/packages/core/src/docs/color-aliases.md index 998e2f06e8..7dde8875fd 100644 --- a/packages/core/src/docs/color-aliases.md +++ b/packages/core/src/docs/color-aliases.md @@ -1,181 +1,245 @@ @## Color aliases -These variables are semantic aliases of our [colors](#colors). They are used throughout Blueprint -itself to ensure consistent color usage across components. +These variables are semantic aliases of our [colors](#colors). +They are used throughout Blueprint itself to ensure consistent color usage across components. -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
VariableDescription
$pt-intent-primaryPrimary intent color
$pt-intent-successSuccess intent color
$pt-intent-warningWarning intent color
$pt-intent-dangerDanger intent color
$pt-app-background-colorApplication background color
$pt-dark-app-background-colorDark theme application background color
$pt-text-colorDefault text color
$pt-text-color-mutedMuted text color
$pt-text-color-disabledDisabled text color
$pt-heading-colorText color for headers
$pt-link-colorText color for links
$pt-dark-text-colorDark theme default text color
$pt-dark-text-color-mutedDark theme muted text color
$pt-dark-text-color-disabledDark theme disabled text color
$pt-dark-heading-colorDark theme text color for headers
$pt-dark-link-colorDark theme text color for links
$pt-text-selection-colorText selection color
$pt-icon-colorDefault icon color
$pt-icon-color-hoverHovered icon color
$pt-icon-color-disabledDisabled icon color
$pt-icon-color-selectedSelected icon color
$pt-dark-icon-colorDark theme default icon color
$pt-dark-icon-color-hoverDark theme hovered icon color
$pt-dark-icon-color-disabledDark theme disabled icon color
$pt-dark-icon-color-selectedDark theme selected icon color
$pt-divider-blackBlack divider color
$pt-dark-divider-blackDark theme black divider color
$pt-dark-divider-whiteDark theme white divider color
$pt-code-text-colorCode text color
$pt-code-background-colorCode background color
$pt-dark-code-text-colorDark theme code text color
$pt-dark-code-background-colorDark theme code background color
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableDescription
+
+ 		$pt-intent-primaryPrimary intent color
+
+ 		$pt-intent-successSuccess intent color
+
+ 		$pt-intent-warningWarning intent color
+
+ 		$pt-intent-dangerDanger intent color
+
+ 		$pt-app-background-colorApplication background color
+
+ 		$pt-dark-app-background-colorDark theme application background color
+
+ 		$pt-text-colorDefault text color
+
+ 		$pt-text-color-mutedMuted text color
+
+ 		$pt-text-color-disabledDisabled text color
+
+ 		$pt-heading-colorText color for headers
+
+ 		$pt-link-colorText color for links
+
+ 		$pt-dark-text-colorDark theme default text color
+
+ 		$pt-dark-text-color-mutedDark theme muted text color
+
+ 		$pt-dark-text-color-disabledDark theme disabled text color
+
+ 		$pt-dark-heading-colorDark theme text color for headers
+
+ 		$pt-dark-link-colorDark theme text color for links
+
+ 		$pt-text-selection-colorText selection color
+
+ 		$pt-icon-colorDefault icon color
+
+ 		$pt-icon-color-hoverHovered icon color
+
+ 		$pt-icon-color-disabledDisabled icon color
+
+ 		$pt-icon-color-selectedSelected icon color
+
+ 		$pt-dark-icon-colorDark theme default icon color
+
+ 		$pt-dark-icon-color-hoverDark theme hovered icon color
+
+ 		$pt-dark-icon-color-disabledDark theme disabled icon color
+
+ 		$pt-dark-icon-color-selectedDark theme selected icon color
+
+ 		$pt-divider-blackBlack divider color
+
+ 		$pt-dark-divider-blackDark theme black divider color
+
+ 		$pt-dark-divider-whiteDark theme white divider color
+
+ 		$pt-code-text-colorCode text color
+
+ 		$pt-code-background-colorCode background color
+
+ 		$pt-dark-code-text-colorDark theme code text color
+
+ 		$pt-dark-code-background-colorDark theme code background color
diff --git a/packages/core/src/docs/index.md b/packages/core/src/docs/index.md new file mode 100644 index 0000000000..9840a01f77 --- /dev/null +++ b/packages/core/src/docs/index.md @@ -0,0 +1,18 @@ +--- +reference: core +--- + +@# Core + +The __@blueprintjs/core__ NPM package is the basis of any Blueprint app. It includes many (30+) +React components covering all the basic bases, from buttons to form controls to tooltips and trees. +It also includes CSS styles for every component and the tools to style your own components and apps +with Sass and Less variables, an elegant color palette, and 300+ UI icons in two sizes. + +@page accessibility +@page colors +@page typography +@page icons +@page variables +@page components +@page resources diff --git a/packages/datetime/src/dateinput.md b/packages/datetime/src/dateinput.md index 7b7c23c06c..4c89e0efdf 100644 --- a/packages/datetime/src/dateinput.md +++ b/packages/datetime/src/dateinput.md @@ -1,4 +1,4 @@ -@## Date input +@# Date input The `DateInput` component is an [input group](#components.forms.input-group) with a calendar button that shows a [`DatePicker`](#components.datetime.datepicker) in a [`Popover`](#components.popover). @@ -13,7 +13,7 @@ Use this component in forms where the user must enter a date. @reactExample DateInputExample -@### JavaScript API +@## JavaScript API The `DateInput` component is available in the __@blueprintjs/datetime__ package. Make sure to review the [general usage docs for date & time components](#components.datetime). diff --git a/packages/datetime/src/datepicker.md b/packages/datetime/src/datepicker.md index 40d83bf7ea..7f2b92315f 100644 --- a/packages/datetime/src/datepicker.md +++ b/packages/datetime/src/datepicker.md @@ -1,4 +1,4 @@ -@## Date picker +@# Date picker A `DatePicker` shows a monthly calendar and allows the user to choose a single date. @@ -17,7 +17,7 @@ for an example of defining `localeUtils` functions using Moment.js. @reactExample DatePickerExample -@### JavaScript API +@## JavaScript API The `DatePicker` component is available in the __@blueprintjs/datetime__ package. Make sure to review the [general usage docs for date & time components](#components.datetime). @@ -28,7 +28,7 @@ in the [**react-day-picker** documentation](http://www.gpbl.org/react-day-picker @interface IDatePickerProps -@### Using modifiers +@## Using modifiers You can use the `modifiers` prop to conditionally apply styles to days. Modifiers are documented in full in the [**react-day-picker** documentation](http://react-day-picker.js.org/Modifiers.html). diff --git a/packages/datetime/src/index.md b/packages/datetime/src/index.md new file mode 100644 index 0000000000..f4e819e194 --- /dev/null +++ b/packages/datetime/src/index.md @@ -0,0 +1,35 @@ +--- +reference: datetime +--- + +@# Datetime + +The __@blueprintjs/datetime__ NPM package provides several components for interacting with dates and times: + +- [`DatePicker`](#components.datetime.datepicker) for selecting a single date (day, month, year). + +- [`DateRangePicker`](#components.datetime.daterangepicker) for selecting date ranges. + +- [`TimePicker`](#components.datetime.timepicker) for selecting a time (hour, minute, second, + millisecond). + +- [`DateTimePicker`](#components.datetime.datetimepicker), which composes `DatePicker` and + `TimePicker` to select a date and time together. + +- [`DateInput`](#components.datetime.dateinput), which composes a text input with a `DatePicker` in + a `Popover`, for use in forms. + +They are available in the __@blueprintjs/datetime__ package on +[NPM](https://www.npmjs.com/package/@blueprintjs/datetime). + +Make sure to review the [general usage docs for JS components](#components.usage). + +```sh +npm install --save @blueprintjs/datetime +``` + +@page datepicker +@page daterangepicker +@page timepicker +@page datetimepicker +@page dateinput diff --git a/packages/docs/src/_nav.md b/packages/docs/src/_nav.md new file mode 100644 index 0000000000..3d249519c7 --- /dev/null +++ b/packages/docs/src/_nav.md @@ -0,0 +1,8 @@ + + +@page styleguide +@page core +@page datetime +@page table-js diff --git a/packages/docs/src/index.tsx b/packages/docs/src/index.tsx index ed34efcbd9..ada23da132 100644 --- a/packages/docs/src/index.tsx +++ b/packages/docs/src/index.tsx @@ -95,11 +95,9 @@ const updateExamples = () => { }); }; -// this is invoked exactly once so there's no penalty for lambdas and they make the code cleaner -// tslint:disable:jsx-no-lambda ReactDOM.render( , document.query("#blueprint-documentation"), ); -// tslint:enable:jsx-no-lambda FocusStyleManager.onlyShowFocusOnTabs(); diff --git a/packages/docs/src/styleguide.md b/packages/docs/src/styleguide.md index 99df88f38a..7684c27c7f 100644 --- a/packages/docs/src/styleguide.md +++ b/packages/docs/src/styleguide.md @@ -1,3 +1,5 @@ +@# Blueprint + Blueprint is a React-based UI toolkit for the web. Development and issue tracking occurs in [github.com/palantir/blueprint](https://github.com/palantir/blueprint). @@ -7,7 +9,6 @@ Releases are tagged and documented [here on GitHub](https://github.com/palantir/ Use the [__blueprintjs__ tag on Stack Overflow](http://stackoverflow.com/questions/tagged/blueprintjs) for support requests. - @## Usage Blueprint is available as a collection of NPM packages under the `@blueprintjs` scope. diff --git a/packages/docs/src/styles/_colors.scss b/packages/docs/src/styles/_colors.scss index c115462357..c732118441 100644 --- a/packages/docs/src/styles/_colors.scss +++ b/packages/docs/src/styles/_colors.scss @@ -301,3 +301,17 @@ $bubble-size: $pt-grid-size * 2; box-shadow: inset border-shadow(0.2, $white); } } + +.docs-color-aliases-table { + margin-top: $content-padding; + + th { + padding-top: 0; + } + + th:first-child, + td:first-child { + padding-right: 0; + padding-left: 0; + } +} diff --git a/packages/docs/src/styles/_sections.scss b/packages/docs/src/styles/_sections.scss index e94be9cc2f..57223287ca 100644 --- a/packages/docs/src/styles/_sections.scss +++ b/packages/docs/src/styles/_sections.scss @@ -227,22 +227,6 @@ } } -#{section-name("Color aliases")} { - .pt-table { - margin-top: $content-padding; - - th { - padding-top: 0; - } - - th:first-child, - td:first-child { - padding-right: 0; - padding-left: 0; - } - } -} - #{section-id("components.hotkeys")} { .piano-example { opacity: 0.5; diff --git a/packages/table/src/docs.md b/packages/table/src/docs.md index 5d8089f61a..5e09e05f6e 100644 --- a/packages/table/src/docs.md +++ b/packages/table/src/docs.md @@ -1,9 +1,14 @@ -@# Table (React) +--- +reference: table-js +--- -A highly interactive table React component. +@# Table + +A highly interactive React `Table` component.
- If you are looking instead for the Blueprint-styled HTML table, see [**the previous section**](#components.table). + If you are looking instead for the Blueprint-styled HTML table, see + [`.pt-table` in **@blueprintjs/core**](#core.components.table).
### Features @@ -16,13 +21,13 @@ A highly interactive table React component. * Editable headers and cells * Integrated header and context menus -@# Installation +@## Installation ```sh npm install --save @blueprintjs/core @blueprintjs/table ``` -@# Making a table +@## Making a table To create a table, you must define the rows and columns. Add children to the `Table` to create columns, and change the `numRows` prop on the `Table` to set the number of rows. @@ -55,7 +60,7 @@ const renderCell = (rowIndex: number) => { @reactExample TableDollarExample -@# Sortable content +@## Sortable content Because the table is **data-agnostic**, you can display complex data in the table and perform arbitrary operations on it. @@ -70,7 +75,7 @@ In the table below, try: @reactExample TableSortableExample -@# Editable content +@## Editable content To make your table editable, use the `EditableCell` and `EditableName` components to create editable table cells and column names. @@ -87,7 +92,7 @@ regular expression (`[a-zA-Z]`). If the content is invalid, a @reactExample TableEditableExample -@# Loading states +@## Loading states When fetching or updating data, it may be desirable to show a loading state. The table components provide fine-grain loading control of loading row headers, column headers, or individual cells. @@ -112,7 +117,7 @@ individual column's header and body cells. Try selecting a different column in t @reactExample ColumnLoadingExample -@# Cells +@## Cells `Cell`, `EditableCell`, `ColumnHeaderCell`, and `RowHeaderCell` expose a `loading` prop for granular control of which cells should show a loading state. Try selecting a different preset loading @@ -120,7 +125,7 @@ configuration. @reactExample CellLoadingExample -@# Formatted content +@## Formatted content To display long strings or native JavaScript objects, we provide `` and `` components, which are designed to be used @@ -132,19 +137,19 @@ and a `` component to show the timezone info object. @reactExample TableFormatsExample -@# JavaScript API +@## JavaScript API The `Table`, `Column`, `Cell`, `ColumnHeaderCell`, `EditableName`, and `EditableCell` components are available in the __@blueprintjs/table__ package. -@## Table +@### Table The top-level component of the table is `Table`. You must at least define the number of rows (`numRows` prop) as well as a set of `Column` children. @interface ITableProps -@## Column +@### Column `Column` contains props for defining how the header and cells of that column are rendered. @@ -157,14 +162,14 @@ Use the `renderRowHeaderCell` prop of `Table` to define row headers. @interface IColumnProps -@## Cell +@### Cell The `Cell` component renders content in the table body. `Cell`s should be returned from the `renderCell` method of each `Column`. @interface ICellProps -@## ColumnHeaderCell +@### ColumnHeaderCell Customize how each column header is displayed. @@ -175,7 +180,7 @@ name, you can supply a `renderName` prop to the `ColumnHeaderCell`. @interface IColumnHeaderCellProps -@## EditableName +@### EditableName Return a `EditableName` component from the `renderName` prop on a `ColumnHeaderCell` to enable click-to-edit functionality in the column @@ -183,14 +188,14 @@ header. @interface IEditableNameProps -@## EditableCell +@### EditableCell Return a `EditableCell` component from the `renderCell` prop on a `Column` to enable double-click-to-edit functionality in the table body. @interface IEditableCellProps -@## TruncatedFormat +@### TruncatedFormat Wrap your cell contents with a `TruncatedFormat` component like so: @@ -201,7 +206,7 @@ return {content} @interface ITruncatedFormatProps -@## JSONFormat +@### JSONFormat Wrap your JavaScript object cell contents with a `JSONFormat` component like so: