From 3290f795b0e62542ca5d8d4cb31189f5ef336832 Mon Sep 17 00:00:00 2001 From: Bill Dwyer Date: Fri, 31 Mar 2017 12:17:53 -0700 Subject: [PATCH] Documentation Overhaul (#917) * split docs package into `docs` and `docs-site` `docs` is the documentalist theme. `docs-site` is the blueprint-specific content for our docs site. write reusable tag renderers for the common tags. this is by no means finished, just a good place to start committing * move BaseExample into `docs` package * move typings around * fix docs-site webpack compile errors! * fix sass compile errors * require react ^15.3 so we can use PureComponent instead of pure-render-decorator * clean up docs common files - move ClickToCopy to docs-site cuz it's not used in docs - rename to propsStore.ts - delete unused PureComponent * move FocusStyleManager call into Styleguide componentDidMount so consumer doesn't have to set it. also fix typings of setHotkeysDialogProps with Partial<>. * fix html paths * fix broken import (forgot to save) * rename Styleguide to Documentation * copyright headers * move docs-site files into same structure as docs components / styles / tags. tags export maps of files for reactDocs and reactExample * Documentation navbarLeft/Right props BlueprintDocs component wraps Documentation with added themeName state. all theme logic moves to `docs-site` custom code. * make some Documentation props optional * remove theme from docs * enable strictNullChecks in docs and docs-site!! * move docs md file, rename styleguide.md to blueprint.md * Update to documentalist 0.0.7 * move .d.ts and README around * move normalize.css import to docs-site.scss until we include it in blueprint.css itself! * fix some small build errors * add project files * update links to docs-site * Add top comment block to interface table tag renderer * export BaseExample from docs package, refactor example imports * fix CONTRIBUTING docs path * Null check when naving to section * Lint * Add docs-site artifact * Fix gulp watch task * minor polish --- CONTRIBUTING.md | 2 +- Gulpfile.js | 8 + README.md | 2 +- circle.yml | 2 + gulp/docs.js | 2 +- gulp/watch.js | 6 +- gulp/webpack.js | 2 +- packages/core/examples/alertExample.tsx | 2 +- packages/core/examples/buttonsExample.tsx | 2 +- packages/core/examples/collapseExample.tsx | 2 +- .../core/examples/collapsibleListExample.tsx | 2 +- packages/core/examples/contextMenuExample.tsx | 2 +- packages/core/examples/controlsExample.tsx | 2 +- .../core/examples/dropdownMenuExample.tsx | 2 +- .../core/examples/editableTextExample.tsx | 2 +- packages/core/examples/focusExample.tsx | 2 +- packages/core/examples/hotkeyPiano.tsx | 2 +- packages/core/examples/hotkeyTester.tsx | 2 +- packages/core/examples/index.ts | 2 - packages/core/examples/inputGroupExample.tsx | 2 +- packages/core/examples/menuExample.tsx | 2 +- .../core/examples/nonIdealStateExample.tsx | 2 +- .../examples/numericInputBasicExample.tsx | 2 +- .../examples/numericInputExtendedExample.tsx | 3 +- packages/core/examples/overlayExample.tsx | 2 +- packages/core/examples/popoverExample.tsx | 2 +- packages/core/examples/progressExample.tsx | 2 +- packages/core/examples/rangeSliderExample.tsx | 2 +- packages/core/examples/sliderExample.tsx | 2 +- packages/core/examples/spinnerExample.tsx | 2 +- packages/core/examples/tabs2Example.tsx | 2 +- packages/core/examples/tabsExample.tsx | 2 +- packages/core/examples/tagExample.tsx | 2 +- packages/core/examples/textExample.tsx | 3 +- packages/core/examples/toastExample.tsx | 2 +- packages/core/examples/tooltipExample.tsx | 2 +- packages/core/examples/treeExample.tsx | 2 +- packages/core/examples/tsconfig.json | 3 +- .../src/components/hotkeys/hotkeysDialog.tsx | 2 +- .../datetime/examples/dateInputExample.tsx | 2 +- .../datetime/examples/datePickerExample.tsx | 2 +- .../examples/dateRangeInputExample.tsx | 2 +- .../examples/dateRangePickerExample.tsx | 2 +- .../examples/dateTimePickerExample.tsx | 2 +- .../datetime/examples/timePickerExample.tsx | 2 +- packages/datetime/examples/tsconfig.json | 6 +- packages/docs-site/README.md | 12 ++ packages/docs-site/package.json | 33 +++ .../resources/blueprint-logo.svg | 0 .../{docs => docs-site}/resources/favicon.png | Bin .../resources/sketch-mac-icon@2x.png | Bin packages/{docs => docs-site}/src/_nav.md | 2 +- .../src/blueprint.md} | 0 .../src/components/blueprintDocs.tsx | 66 ++++++ .../src/components}/clickToCopy.tsx | 9 +- .../src/components/colorPalettes.tsx | 2 +- .../src/components/colorSchemes.tsx | 8 +- .../src/components/icon.tsx | 6 +- .../src/components/icons.tsx | 6 +- .../src/components/navbarActions.tsx | 101 ++++++++++ packages/docs-site/src/docs-site.scss | 28 +++ packages/{docs => docs-site}/src/index.html | 4 +- packages/docs-site/src/index.tsx | 48 +++++ .../{docs => docs-site}/src/require-shim.d.ts | 0 .../src/styles/_colors.scss | 4 +- packages/docs-site/src/styles/_examples.scss | 189 ++++++++++++++++++ .../src/styles/_icons.scss | 4 +- .../src/styles/_resources.scss | 2 + .../src/styles/_sections.scss | 2 - .../src/tags}/reactDocs.ts | 10 +- packages/docs-site/src/tags/reactExamples.ts | 30 +++ packages/docs-site/tsconfig.json | 44 ++++ packages/{docs => docs-site}/tsd.json | 0 .../typings/chroma-js/chroma-js.d.ts | 0 packages/{docs => docs-site}/typings/tsd.d.ts | 0 packages/docs/.npmignore | 4 + packages/docs/LICENSE | 39 ++++ packages/docs/PATENTS | 45 +++++ packages/docs/README.md | 21 +- packages/docs/package.json | 30 ++- packages/docs/src/common/index.ts | 9 + .../common/{propsStore.tsx => propsStore.ts} | 18 +- packages/docs/src/common/pureComponent.tsx | 15 -- packages/docs/src/common/resolveDocs.ts | 33 --- packages/docs/src/common/resolveExample.tsx | 87 -------- packages/docs/src/common/theme.ts | 18 -- packages/docs/src/common/utils.ts | 4 +- .../src/components}/baseExample.tsx | 8 +- packages/docs/src/components/block.tsx | 33 +++ .../{styleguide.tsx => documentation.tsx} | 137 ++++++------- .../{propsTable.tsx => interfaceTable.tsx} | 50 +++-- .../docs/src/components/modifierTable.tsx | 2 +- packages/docs/src/components/navMenu.tsx | 2 +- packages/docs/src/components/navbar.tsx | 134 ------------- packages/docs/src/components/navigator.tsx | 19 +- packages/docs/src/components/page.tsx | 33 ++- packages/docs/src/docs.scss | 10 - packages/docs/src/index.ts | 13 ++ packages/docs/src/index.tsx | 102 ---------- packages/docs/src/styles/_content.scss | 2 +- packages/docs/src/styles/_examples.scss | 189 +----------------- packages/docs/src/styles/_layout.scss | 2 +- packages/docs/src/styles/_navbar.scss | 3 +- packages/docs/src/styles/_navigator.scss | 5 +- packages/docs/src/styles/_overrides.scss | 5 +- packages/docs/src/styles/_props.scss | 5 +- packages/docs/src/styles/_syntax.scss | 5 + packages/docs/src/styles/_variables.scss | 14 +- .../{common/cssExample.tsx => tags/css.tsx} | 24 ++- packages/docs/src/tags/defaults.ts | 27 +++ packages/docs/src/tags/heading.tsx | 26 +++ packages/docs/src/tags/index.ts | 29 +++ packages/docs/src/tags/interface.tsx | 26 +++ packages/docs/src/tags/page.tsx | 12 ++ packages/docs/src/tags/reactDocs.tsx | 34 ++++ packages/docs/src/tags/reactExample.tsx | 56 ++++++ packages/docs/tsconfig.json | 29 +-- .../table/examples/cellLoadingExample.tsx | 2 +- .../table/examples/columnLoadingExample.tsx | 2 +- .../table/examples/tableDollarExample.tsx | 4 +- .../table/examples/tableEditableExample.tsx | 2 +- .../table/examples/tableFormatsExample.tsx | 2 +- .../table/examples/tableLoadingExample.tsx | 2 +- .../table/examples/tableSortableExample.tsx | 2 +- packages/table/examples/tsconfig.json | 5 +- scripts/docsDist.sh | 13 +- scripts/preview.sh | 2 +- 127 files changed, 1229 insertions(+), 885 deletions(-) create mode 100644 packages/docs-site/README.md create mode 100644 packages/docs-site/package.json rename packages/{docs => docs-site}/resources/blueprint-logo.svg (100%) rename packages/{docs => docs-site}/resources/favicon.png (100%) rename packages/{docs => docs-site}/resources/sketch-mac-icon@2x.png (100%) rename packages/{docs => docs-site}/src/_nav.md (87%) rename packages/{docs/src/styleguide.md => docs-site/src/blueprint.md} (100%) create mode 100644 packages/docs-site/src/components/blueprintDocs.tsx rename packages/{docs/src/common => docs-site/src/components}/clickToCopy.tsx (92%) rename packages/{docs => docs-site}/src/components/colorPalettes.tsx (98%) rename packages/{docs => docs-site}/src/components/colorSchemes.tsx (95%) rename packages/{docs => docs-site}/src/components/icon.tsx (92%) rename packages/{docs => docs-site}/src/components/icons.tsx (95%) create mode 100644 packages/docs-site/src/components/navbarActions.tsx create mode 100644 packages/docs-site/src/docs-site.scss rename packages/{docs => docs-site}/src/index.html (93%) create mode 100644 packages/docs-site/src/index.tsx rename packages/{docs => docs-site}/src/require-shim.d.ts (100%) rename packages/{docs => docs-site}/src/styles/_colors.scss (99%) create mode 100644 packages/docs-site/src/styles/_examples.scss rename packages/{docs => docs-site}/src/styles/_icons.scss (96%) rename packages/{docs => docs-site}/src/styles/_resources.scss (97%) rename packages/{docs => docs-site}/src/styles/_sections.scss (99%) rename packages/{docs/src/components => docs-site/src/tags}/reactDocs.ts (57%) create mode 100644 packages/docs-site/src/tags/reactExamples.ts create mode 100644 packages/docs-site/tsconfig.json rename packages/{docs => docs-site}/tsd.json (100%) rename packages/{docs => docs-site}/typings/chroma-js/chroma-js.d.ts (100%) rename packages/{docs => docs-site}/typings/tsd.d.ts (100%) create mode 100644 packages/docs/.npmignore create mode 100644 packages/docs/LICENSE create mode 100644 packages/docs/PATENTS create mode 100644 packages/docs/src/common/index.ts rename packages/docs/src/common/{propsStore.tsx => propsStore.ts} (63%) delete mode 100644 packages/docs/src/common/pureComponent.tsx delete mode 100644 packages/docs/src/common/resolveDocs.ts delete mode 100644 packages/docs/src/common/resolveExample.tsx delete mode 100644 packages/docs/src/common/theme.ts rename packages/{core/examples/common => docs/src/components}/baseExample.tsx (90%) create mode 100644 packages/docs/src/components/block.tsx rename packages/docs/src/components/{styleguide.tsx => documentation.tsx} (69%) rename packages/docs/src/components/{propsTable.tsx => interfaceTable.tsx} (71%) delete mode 100644 packages/docs/src/components/navbar.tsx create mode 100644 packages/docs/src/index.ts delete mode 100644 packages/docs/src/index.tsx rename packages/docs/src/{common/cssExample.tsx => tags/css.tsx} (57%) create mode 100644 packages/docs/src/tags/defaults.ts create mode 100644 packages/docs/src/tags/heading.tsx create mode 100644 packages/docs/src/tags/index.ts create mode 100644 packages/docs/src/tags/interface.tsx create mode 100644 packages/docs/src/tags/page.tsx create mode 100644 packages/docs/src/tags/reactDocs.tsx create mode 100644 packages/docs/src/tags/reactExample.tsx diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8001324e7e..e79788a9f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ A typical contributor workflow looks like this: 1. Create a new feature branch. We use a format like `[your-initials]/[short-name]`: `bd/refactor-buttons`. 1. Run the development server via `gulp` (no arguments). - - Navigate to http://localhost:9000/packages/docs/dist/ when the server starts. + - Navigate to http://localhost:9000/packages/docs-site/dist/ when the server starts. - See [Build tasks](https://github.com/palantir/blueprint/wiki/Build-tasks) on the wiki for more details on the inner workings of the Gulp build. - If you are contributing to the `table` or `landing` packages then run `npm start` in those diff --git a/Gulpfile.js b/Gulpfile.js index a7114a1576..98a7bb4d4d 100644 --- a/Gulpfile.js +++ b/Gulpfile.js @@ -71,11 +71,18 @@ const projects = [ }, { id: "docs", cwd: "packages/docs/", + dependencies: ["core"], + sass: "compile", + typescript: true, + }, { + id: "docs-site", + cwd: "packages/docs-site/", dependencies: [ // You must add your package to this dependency list if you have any // examples in the docs. "core", "datetime", + "docs", "table", ], sass: "bundle", @@ -87,6 +94,7 @@ const projects = [ // (they all import @blueprint/* but don't actually have themselves in their node_modules) "@blueprintjs/core", "@blueprintjs/datetime", + "@blueprintjs/docs", "@blueprintjs/table", "dom4", "moment", diff --git a/README.md b/README.md index b0c7265ce3..e2b3a006dc 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ __Prerequisite__: Node.js v6 or v7 1. `npm install` to install build dependencies 1. `npm run bootstrap` to install and link each package using [Lerna](https://lernajs.io/) 1. `npm run gulp` to compile and start the server and watcher -1. Open your browser to [localhost:9000/packages/docs/dist/](http://localhost:9000/packages/docs/dist/) +1. Open your browser to [localhost:9000/packages/docs-site/dist/](http://localhost:9000/packages/docs-site/dist/) ## Contributing diff --git a/circle.yml b/circle.yml index 9a57b6cccc..43381e1aef 100644 --- a/circle.yml +++ b/circle.yml @@ -4,6 +4,7 @@ general: - packages/core/dist - packages/datetime/dist - packages/docs/dist + - packages/docs-site/dist - packages/landing/dist - packages/table/dist # code coverage reports @@ -22,6 +23,7 @@ dependencies: - packages/core/node_modules - packages/datetime/node_modules - packages/docs/node_modules + - packages/docs-site/node_modules - packages/landing/node_modules - packages/table/node_modules # non-zero exit codes in `dependencies` group will fail the build early diff --git a/gulp/docs.js b/gulp/docs.js index 6b03aee18d..c3a2c12382 100644 --- a/gulp/docs.js +++ b/gulp/docs.js @@ -10,7 +10,7 @@ module.exports = (blueprint, gulp, plugins) => { const text = require("./util/text"); const spawn = require("child_process").spawn; const semver = require("semver"); - const cwd = blueprint.findProject("docs").cwd; + const cwd = blueprint.findProject("docs-site").cwd; const config = { data: path.join(cwd, "src", "generated"), diff --git a/gulp/watch.js b/gulp/watch.js index b3c208c50e..1a5386a562 100644 --- a/gulp/watch.js +++ b/gulp/watch.js @@ -24,7 +24,7 @@ module.exports = (blueprint, gulp, plugins) => { gulp.task("watch-files", ["connect"], () => { blueprint.projectsWithBlock("sass").forEach((project) => { const tasks = [`sass-${project.id}:only`]; - if (project.id !== "docs") { + if (project.id === "core") { tasks.push("sass-variables"); } gulp.watch(createSrcGlob(project, "*.scss"), tasks); @@ -36,8 +36,8 @@ module.exports = (blueprint, gulp, plugins) => { gulp.watch("packages/*/!(node_modules)/**/*.md", ["docs-json"]); - // recompile docs CSS when non-docs dist/*.css files change - gulp.watch("packages/!(docs)/dist/*.css", ["sass-docs:only"]); + // recompile docs CSS when non-docs-site dist/*.css files change + gulp.watch("packages/!(docs-site)/dist/*.css", ["sass-docs-site:only"]); }); gulp.task("watch", ["watch-files", "webpack-docs-watch"]); diff --git a/gulp/webpack.js b/gulp/webpack.js index df4672448c..6a3dd07bb9 100644 --- a/gulp/webpack.js +++ b/gulp/webpack.js @@ -7,7 +7,7 @@ module.exports = (blueprint, gulp) => { const webpack = require("webpack"); const webpackConfig = require("./util/webpack-config"); - const docsProject = blueprint.findProject("docs"); + const docsProject = blueprint.findProject("docs-site"); const configuration = webpackConfig.generateWebpackTypescriptConfig(docsProject); gulp.task("webpack-docs", ["docs"], (callback) => { diff --git a/packages/core/examples/alertExample.tsx b/packages/core/examples/alertExample.tsx index c4e981a7fa..25d66e1d4f 100644 --- a/packages/core/examples/alertExample.tsx +++ b/packages/core/examples/alertExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Alert, Button, Intent, IToaster, Toaster } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export interface IAlertExampleState { isOpen?: boolean; diff --git a/packages/core/examples/buttonsExample.tsx b/packages/core/examples/buttonsExample.tsx index 7ffb9d7593..0ecd8fce28 100644 --- a/packages/core/examples/buttonsExample.tsx +++ b/packages/core/examples/buttonsExample.tsx @@ -9,7 +9,7 @@ import * as classNames from "classnames"; import * as React from "react"; import { AnchorButton, Button, Classes, Intent, Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs"; import { IntentSelect } from "./common/intentSelect"; export interface IButtonsExampleState { diff --git a/packages/core/examples/collapseExample.tsx b/packages/core/examples/collapseExample.tsx index e514ebc000..2d8b6bf3d7 100644 --- a/packages/core/examples/collapseExample.tsx +++ b/packages/core/examples/collapseExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Button, Collapse } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export class CollapseExample extends BaseExample<{ isOpen: boolean }> { public state = { diff --git a/packages/core/examples/collapsibleListExample.tsx b/packages/core/examples/collapsibleListExample.tsx index 742758e0b6..001855b392 100644 --- a/packages/core/examples/collapsibleListExample.tsx +++ b/packages/core/examples/collapsibleListExample.tsx @@ -17,7 +17,7 @@ import { RadioGroup, Slider, } from "@blueprintjs/core"; -import BaseExample, { handleNumberChange } from "./common/baseExample"; +import { BaseExample, handleNumberChange } from "@blueprintjs/docs"; export interface ICollapsibleListExampleState { collapseFrom?: CollapseFrom; diff --git a/packages/core/examples/contextMenuExample.tsx b/packages/core/examples/contextMenuExample.tsx index bc8c0ab4a7..ba163b64e6 100644 --- a/packages/core/examples/contextMenuExample.tsx +++ b/packages/core/examples/contextMenuExample.tsx @@ -12,7 +12,7 @@ import * as PureRender from "pure-render-decorator"; import * as React from "react"; import { ContextMenu, ContextMenuTarget, Menu, MenuDivider, MenuItem } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; /** * This component uses the imperative ContextMenu API. diff --git a/packages/core/examples/controlsExample.tsx b/packages/core/examples/controlsExample.tsx index 2b51e8d2ca..e55426006b 100644 --- a/packages/core/examples/controlsExample.tsx +++ b/packages/core/examples/controlsExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Checkbox, Classes, Radio, RadioGroup, Switch } from "@blueprintjs/core"; -import BaseExample, { handleStringChange } from "./common/baseExample"; +import { BaseExample, handleStringChange } from "@blueprintjs/docs"; export interface IControlsExampleState { radioValue?: string; diff --git a/packages/core/examples/dropdownMenuExample.tsx b/packages/core/examples/dropdownMenuExample.tsx index 8a27282518..da0f1418a7 100644 --- a/packages/core/examples/dropdownMenuExample.tsx +++ b/packages/core/examples/dropdownMenuExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Menu, MenuDivider, MenuItem, Popover, Position } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export class DropdownMenuExample extends BaseExample<{}> { protected renderExample() { diff --git a/packages/core/examples/editableTextExample.tsx b/packages/core/examples/editableTextExample.tsx index f550483e8e..a8fe7064f2 100644 --- a/packages/core/examples/editableTextExample.tsx +++ b/packages/core/examples/editableTextExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Classes, EditableText, Intent, Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleNumberChange, handleStringChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange, handleNumberChange, handleStringChange } from "@blueprintjs/docs"; import { IntentSelect } from "./common/intentSelect"; export interface IEditableTextExampleState { diff --git a/packages/core/examples/focusExample.tsx b/packages/core/examples/focusExample.tsx index e3d153d30c..74c8d69363 100644 --- a/packages/core/examples/focusExample.tsx +++ b/packages/core/examples/focusExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Button, FocusStyleManager, InputGroup, Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; export interface IFocusExampleState { isFocusActive?: boolean; diff --git a/packages/core/examples/hotkeyPiano.tsx b/packages/core/examples/hotkeyPiano.tsx index e13052abdc..1a486edfb8 100644 --- a/packages/core/examples/hotkeyPiano.tsx +++ b/packages/core/examples/hotkeyPiano.tsx @@ -11,7 +11,7 @@ import * as classNames from "classnames"; import * as React from "react"; import { Hotkey, Hotkeys, HotkeysTarget } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; class Oscillator { public oscillator: OscillatorNode; diff --git a/packages/core/examples/hotkeyTester.tsx b/packages/core/examples/hotkeyTester.tsx index 6a19abb2b2..b948e5ef20 100644 --- a/packages/core/examples/hotkeyTester.tsx +++ b/packages/core/examples/hotkeyTester.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { getKeyComboString, KeyCombo } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export interface IHotkeyTesterState { combo: string; diff --git a/packages/core/examples/index.ts b/packages/core/examples/index.ts index 5a14bf08d0..3c3f9b1769 100644 --- a/packages/core/examples/index.ts +++ b/packages/core/examples/index.ts @@ -5,8 +5,6 @@ * and https://github.com/palantir/blueprint/blob/master/PATENTS */ -export * from "./common/baseExample"; - export * from "./alertExample"; export * from "./buttonsExample"; export * from "./collapseExample"; diff --git a/packages/core/examples/inputGroupExample.tsx b/packages/core/examples/inputGroupExample.tsx index 636e3dc37f..0a474c4590 100644 --- a/packages/core/examples/inputGroupExample.tsx +++ b/packages/core/examples/inputGroupExample.tsx @@ -22,7 +22,7 @@ import { Tag, Tooltip, } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleStringChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange, handleStringChange } from "@blueprintjs/docs"; export interface IInputGroupExampleState { disabled?: boolean; diff --git a/packages/core/examples/menuExample.tsx b/packages/core/examples/menuExample.tsx index b36fb5aa95..4b406239db 100644 --- a/packages/core/examples/menuExample.tsx +++ b/packages/core/examples/menuExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Classes, Menu, MenuDivider, MenuItem } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export class MenuExample extends BaseExample<{}> { protected renderExample() { diff --git a/packages/core/examples/nonIdealStateExample.tsx b/packages/core/examples/nonIdealStateExample.tsx index 4e642423cd..1dcfb4447a 100644 --- a/packages/core/examples/nonIdealStateExample.tsx +++ b/packages/core/examples/nonIdealStateExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { InputGroup, NonIdealState } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export class NonIdealStateExample extends BaseExample<{}> { protected renderExample() { diff --git a/packages/core/examples/numericInputBasicExample.tsx b/packages/core/examples/numericInputBasicExample.tsx index 6ecea72764..90f64558b3 100644 --- a/packages/core/examples/numericInputBasicExample.tsx +++ b/packages/core/examples/numericInputBasicExample.tsx @@ -13,8 +13,8 @@ import { Position, Switch, } from "@blueprintjs/core"; +import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs"; -import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample"; import { IntentSelect } from "./common/intentSelect"; export interface INumericInputBasicExampleState { diff --git a/packages/core/examples/numericInputExtendedExample.tsx b/packages/core/examples/numericInputExtendedExample.tsx index 3724fc169c..93840d2fca 100644 --- a/packages/core/examples/numericInputExtendedExample.tsx +++ b/packages/core/examples/numericInputExtendedExample.tsx @@ -9,8 +9,7 @@ import { Keys, NumericInput, } from "@blueprintjs/core"; - -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export interface INumericInputExtendedExampleState { value?: string; diff --git a/packages/core/examples/overlayExample.tsx b/packages/core/examples/overlayExample.tsx index fd8af6f54a..f43c1e3134 100644 --- a/packages/core/examples/overlayExample.tsx +++ b/packages/core/examples/overlayExample.tsx @@ -17,7 +17,7 @@ import { Overlay, Switch, } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; const OVERLAY_EXAMPLE_CLASS = "docs-overlay-example-transition"; diff --git a/packages/core/examples/popoverExample.tsx b/packages/core/examples/popoverExample.tsx index b6389b0a25..0ef02505ed 100644 --- a/packages/core/examples/popoverExample.tsx +++ b/packages/core/examples/popoverExample.tsx @@ -21,7 +21,7 @@ import { Slider, Switch, } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs"; const INTERACTION_KINDS = [ { label: "Click", value: PopoverInteractionKind.CLICK.toString() }, diff --git a/packages/core/examples/progressExample.tsx b/packages/core/examples/progressExample.tsx index fe0749f4ba..dd732a3fbd 100644 --- a/packages/core/examples/progressExample.tsx +++ b/packages/core/examples/progressExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Intent, ProgressBar, Slider, Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs"; import { IntentSelect } from "./common/intentSelect"; export interface IProgressExampleState { diff --git a/packages/core/examples/rangeSliderExample.tsx b/packages/core/examples/rangeSliderExample.tsx index 962785b8b5..a04fe052cc 100644 --- a/packages/core/examples/rangeSliderExample.tsx +++ b/packages/core/examples/rangeSliderExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { NumberRange, RangeSlider } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export interface IRangeSliderExampleState { range?: NumberRange; diff --git a/packages/core/examples/sliderExample.tsx b/packages/core/examples/sliderExample.tsx index 4e4baa8356..ef9a75a3ed 100644 --- a/packages/core/examples/sliderExample.tsx +++ b/packages/core/examples/sliderExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Slider } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export interface ISliderExampleState { value1?: number; diff --git a/packages/core/examples/spinnerExample.tsx b/packages/core/examples/spinnerExample.tsx index 214fe7f113..204ae90baa 100644 --- a/packages/core/examples/spinnerExample.tsx +++ b/packages/core/examples/spinnerExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Classes, Spinner } from "@blueprintjs/core"; -import { handleStringChange } from "./common/baseExample"; +import { handleStringChange } from "@blueprintjs/docs"; import { ProgressExample } from "./progressExample"; const SIZES = [ diff --git a/packages/core/examples/tabs2Example.tsx b/packages/core/examples/tabs2Example.tsx index 4234178ccf..de37ddd7a0 100644 --- a/packages/core/examples/tabs2Example.tsx +++ b/packages/core/examples/tabs2Example.tsx @@ -9,7 +9,7 @@ import * as classNames from "classnames"; import * as React from "react"; import { Classes, Switch, Tab2, Tabs2 } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; export interface ITabs2ExampleState { activeTabId?: string; diff --git a/packages/core/examples/tabsExample.tsx b/packages/core/examples/tabsExample.tsx index 1f02e6fedc..cbf7ac21a7 100644 --- a/packages/core/examples/tabsExample.tsx +++ b/packages/core/examples/tabsExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Switch, Tab, TabList, TabPanel, Tabs } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; export class TabsExample extends BaseExample<{ isVertical?: boolean }> { public state = { diff --git a/packages/core/examples/tagExample.tsx b/packages/core/examples/tagExample.tsx index b50f7b4bd3..fb0dd853ed 100644 --- a/packages/core/examples/tagExample.tsx +++ b/packages/core/examples/tagExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Classes, Intent, Tag } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export class TagExample extends BaseExample<{ showTag?: boolean }> { public state = { diff --git a/packages/core/examples/textExample.tsx b/packages/core/examples/textExample.tsx index 199ebfa01b..ae17a229c2 100644 --- a/packages/core/examples/textExample.tsx +++ b/packages/core/examples/textExample.tsx @@ -8,10 +8,9 @@ import * as classNames from "classnames"; import * as React from "react"; +import { BaseExample, handleStringChange } from "@blueprintjs/docs"; import * as Classes from "../src/common/classes"; import { Text } from "../src/components/text/text"; -import BaseExample from "./common/baseExample"; -import { handleStringChange } from "./common/baseExample"; export interface ITextExampleState { textContent: string; diff --git a/packages/core/examples/toastExample.tsx b/packages/core/examples/toastExample.tsx index d93182fce4..e322835fcc 100644 --- a/packages/core/examples/toastExample.tsx +++ b/packages/core/examples/toastExample.tsx @@ -19,7 +19,7 @@ import { Switch, Toaster, } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample"; +import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs"; type IToastDemo = IToastProps & { button: string }; diff --git a/packages/core/examples/tooltipExample.tsx b/packages/core/examples/tooltipExample.tsx index 3c669ece59..938036dc76 100644 --- a/packages/core/examples/tooltipExample.tsx +++ b/packages/core/examples/tooltipExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Intent, Popover, Position, Switch, Tooltip } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export class TooltipExample extends BaseExample<{ isOpen: boolean }> { public state = { diff --git a/packages/core/examples/treeExample.tsx b/packages/core/examples/treeExample.tsx index 50fdc6d5d5..15b39a73d7 100644 --- a/packages/core/examples/treeExample.tsx +++ b/packages/core/examples/treeExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Classes, ITreeNode, Tooltip, Tree } from "@blueprintjs/core"; -import BaseExample from "./common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; export interface ITreeExampleState { nodes: ITreeNode[]; diff --git a/packages/core/examples/tsconfig.json b/packages/core/examples/tsconfig.json index 7b2cf963de..9c7a233d58 100644 --- a/packages/core/examples/tsconfig.json +++ b/packages/core/examples/tsconfig.json @@ -17,7 +17,8 @@ "stripInternal": true, "target": "es5", "paths": { - "@blueprintjs/core": ["../dist/index"] + "@blueprintjs/core": ["../dist/index"], + "@blueprintjs/docs": ["../../docs/dist/index"] } } } diff --git a/packages/core/src/components/hotkeys/hotkeysDialog.tsx b/packages/core/src/components/hotkeys/hotkeysDialog.tsx index be9b4199d1..c263259534 100644 --- a/packages/core/src/components/hotkeys/hotkeysDialog.tsx +++ b/packages/core/src/components/hotkeys/hotkeysDialog.tsx @@ -126,7 +126,7 @@ export function isHotkeysDialogShowing() { return HOTKEYS_DIALOG.isShowing(); } -export function setHotkeysDialogProps(props: IHotkeysDialogProps) { +export function setHotkeysDialogProps(props: Partial) { for (const key in props) { if (props.hasOwnProperty(key)) { (HOTKEYS_DIALOG.componentProps as any)[key] = (props as any)[key]; diff --git a/packages/datetime/examples/dateInputExample.tsx b/packages/datetime/examples/dateInputExample.tsx index 02b887bff5..4e77c8215a 100644 --- a/packages/datetime/examples/dateInputExample.tsx +++ b/packages/datetime/examples/dateInputExample.tsx @@ -6,7 +6,7 @@ */ import { Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleStringChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleBooleanChange, handleStringChange } from "@blueprintjs/docs"; import * as React from "react"; import { DateInput } from "../src"; diff --git a/packages/datetime/examples/datePickerExample.tsx b/packages/datetime/examples/datePickerExample.tsx index 552b770c4d..acbaa8367f 100644 --- a/packages/datetime/examples/datePickerExample.tsx +++ b/packages/datetime/examples/datePickerExample.tsx @@ -6,7 +6,7 @@ */ import { Classes, Intent, Switch, Tag } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; import * as classNames from "classnames"; import * as moment from "moment"; import * as React from "react"; diff --git a/packages/datetime/examples/dateRangeInputExample.tsx b/packages/datetime/examples/dateRangeInputExample.tsx index 48e0850459..a735de8f6f 100644 --- a/packages/datetime/examples/dateRangeInputExample.tsx +++ b/packages/datetime/examples/dateRangeInputExample.tsx @@ -6,7 +6,7 @@ */ import { Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange, handleStringChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleBooleanChange, handleStringChange } from "@blueprintjs/docs"; import * as React from "react"; import { DateRangeInput } from "../src"; diff --git a/packages/datetime/examples/dateRangePickerExample.tsx b/packages/datetime/examples/dateRangePickerExample.tsx index 5ace77a140..074223e88c 100644 --- a/packages/datetime/examples/dateRangePickerExample.tsx +++ b/packages/datetime/examples/dateRangePickerExample.tsx @@ -6,7 +6,7 @@ */ import { Classes, Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; import * as React from "react"; import { DateRange, DateRangePicker } from "../src"; diff --git a/packages/datetime/examples/dateTimePickerExample.tsx b/packages/datetime/examples/dateTimePickerExample.tsx index f296378d05..cd4783cebd 100644 --- a/packages/datetime/examples/dateTimePickerExample.tsx +++ b/packages/datetime/examples/dateTimePickerExample.tsx @@ -6,7 +6,7 @@ */ import { Classes } from "@blueprintjs/core"; -import BaseExample from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; import * as React from "react"; import { DateTimePicker, TimePickerPrecision } from "../src"; diff --git a/packages/datetime/examples/timePickerExample.tsx b/packages/datetime/examples/timePickerExample.tsx index 76c073e70a..7aff067c01 100644 --- a/packages/datetime/examples/timePickerExample.tsx +++ b/packages/datetime/examples/timePickerExample.tsx @@ -6,7 +6,7 @@ */ import { Classes, Switch } from "@blueprintjs/core"; -import BaseExample, { handleNumberChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleNumberChange } from "@blueprintjs/docs"; import * as React from "react"; import { TimePicker, TimePickerPrecision } from "../src"; diff --git a/packages/datetime/examples/tsconfig.json b/packages/datetime/examples/tsconfig.json index 7abf64418b..6e02f3a149 100644 --- a/packages/datetime/examples/tsconfig.json +++ b/packages/datetime/examples/tsconfig.json @@ -1,6 +1,7 @@ { "version": "2.0.0", "compilerOptions": { + "baseUrl": ".", "declaration": true, "experimentalDecorators": true, "jsx": "react", @@ -14,6 +15,9 @@ "removeComments": false, "sourceMap": false, "stripInternal": true, - "target": "es5" + "target": "es5", + "paths": { + "@blueprintjs/docs": ["../../docs/dist/index"] + } } } diff --git a/packages/docs-site/README.md b/packages/docs-site/README.md new file mode 100644 index 0000000000..dd1e0ebe8e --- /dev/null +++ b/packages/docs-site/README.md @@ -0,0 +1,12 @@ +# [Blueprint Documentation](http://blueprintjs.com/docs) + +This project generates and aggregates the documentation from the packages +in this repo. + +## Quick start + +From the root of the repo: + +1. Run `npm run bootstrap` +1. Run `npm run gulp` +1. Open your browser to http://localhost:9000/packages/docs-site/dist diff --git a/packages/docs-site/package.json b/packages/docs-site/package.json new file mode 100644 index 0000000000..3ecd1537c0 --- /dev/null +++ b/packages/docs-site/package.json @@ -0,0 +1,33 @@ +{ + "name": "@blueprintjs/docs-site", + "version": "1.12.0", + "description": "Blueprint Docs", + "private": true, + "dependencies": { + "@blueprintjs/core": "^1.12.0", + "@blueprintjs/datetime": "^1.10.0", + "@blueprintjs/docs": "^1.0.0", + "@blueprintjs/table": "^1.9.0", + "bourbon": "4.2.2", + "chroma-js": "1.1.1", + "classnames": "2.2.5", + "dom4": "1.8.3", + "moment": "2.15.1", + "normalize.css": "4.1.1", + "react": "15.4.0", + "react-addons-css-transition-group": "15.4.0", + "react-dom": "15.4.0", + "tslib": "1.5.0" + }, + "repository": { + "type": "git", + "url": "git@github.com:palantir/blueprint.git" + }, + "keywords": [ + "palantir", + "blueprint", + "docs" + ], + "author": "Palantir Technologies", + "license": "BSD-3-Clause" +} diff --git a/packages/docs/resources/blueprint-logo.svg b/packages/docs-site/resources/blueprint-logo.svg similarity index 100% rename from packages/docs/resources/blueprint-logo.svg rename to packages/docs-site/resources/blueprint-logo.svg diff --git a/packages/docs/resources/favicon.png b/packages/docs-site/resources/favicon.png similarity index 100% rename from packages/docs/resources/favicon.png rename to packages/docs-site/resources/favicon.png diff --git a/packages/docs/resources/sketch-mac-icon@2x.png b/packages/docs-site/resources/sketch-mac-icon@2x.png similarity index 100% rename from packages/docs/resources/sketch-mac-icon@2x.png rename to packages/docs-site/resources/sketch-mac-icon@2x.png diff --git a/packages/docs/src/_nav.md b/packages/docs-site/src/_nav.md similarity index 87% rename from packages/docs/src/_nav.md rename to packages/docs-site/src/_nav.md index 3d249519c7..c03a6147cb 100644 --- a/packages/docs/src/_nav.md +++ b/packages/docs-site/src/_nav.md @@ -2,7 +2,7 @@ This file enumerates the exact order of root pages in the left sidebar. --> -@page styleguide +@page blueprint @page core @page datetime @page table-js diff --git a/packages/docs/src/styleguide.md b/packages/docs-site/src/blueprint.md similarity index 100% rename from packages/docs/src/styleguide.md rename to packages/docs-site/src/blueprint.md diff --git a/packages/docs-site/src/components/blueprintDocs.tsx b/packages/docs-site/src/components/blueprintDocs.tsx new file mode 100644 index 0000000000..203a5d63f5 --- /dev/null +++ b/packages/docs-site/src/components/blueprintDocs.tsx @@ -0,0 +1,66 @@ + +import { setHotkeysDialogProps } from "@blueprintjs/core"; +import { Documentation, IDocumentationProps } from "@blueprintjs/docs"; +import * as React from "react"; +import { IPackageInfo, NavbarActions } from "./navbarActions"; + +const DARK_THEME = "pt-dark"; +const LIGHT_THEME = ""; +const THEME_LOCAL_STORAGE_KEY = "pt-blueprint-theme"; + +/** Return the current theme className. */ +export function getTheme(): string { + return localStorage.getItem(THEME_LOCAL_STORAGE_KEY) || LIGHT_THEME; +} + +/** Persist the current theme className in local storage. */ +export function setTheme(themeName: string) { + localStorage.setItem(THEME_LOCAL_STORAGE_KEY, themeName); +} + +export interface IBlueprintDocsProps extends Pick { + releases: IPackageInfo[]; + versions: IPackageInfo[]; +} + +export class BlueprintDocs extends React.Component { + public state = { themeName: getTheme() }; + + public render() { + const navbarLeft = [ + , +
Blueprint
, +
v{this.props.versions[0].version}
, + ]; + const navbarRight = ( + + ); + return ; + } + + // This function is called whenever the documentation page changes and should be used to + // run non-React code on the newly rendered sections. + private handleComponentUpdate = () => { + // indeterminate checkbox styles must be applied via JavaScript. + document.queryAll(".pt-checkbox input[indeterminate]").forEach((el: HTMLInputElement) => { + el.indeterminate = true; + }); + } + + private handleToggleDark = (useDark: boolean) => { + const themeName = useDark ? DARK_THEME : LIGHT_THEME; + this.setState({ themeName }); + setTheme(themeName); + setHotkeysDialogProps({ className: this.state.themeName }); + } +} diff --git a/packages/docs/src/common/clickToCopy.tsx b/packages/docs-site/src/components/clickToCopy.tsx similarity index 92% rename from packages/docs/src/common/clickToCopy.tsx rename to packages/docs-site/src/components/clickToCopy.tsx index 41aaa3de74..16562010fd 100644 --- a/packages/docs/src/common/clickToCopy.tsx +++ b/packages/docs-site/src/components/clickToCopy.tsx @@ -6,12 +6,10 @@ */ import * as classNames from "classnames"; -import * as PureRender from "pure-render-decorator"; import * as React from "react"; import { IProps, Keys, removeNonHTMLProps, Utils } from "@blueprintjs/core"; - -import { createKeyEventHandler } from "./utils"; +import { createKeyEventHandler } from "@blueprintjs/docs"; export interface IClickToCopyProps extends IProps, React.HTMLProps { /** @@ -38,8 +36,7 @@ export interface IClickToCopyState { * - `[data-copied-message=""]` will be shown when the element has been copied. * The message is reset to default when the user mouses off the element after copying it. */ -@PureRender -export class ClickToCopy extends React.Component { +export class ClickToCopy extends React.PureComponent { public static defaultProps: IClickToCopyProps = { copiedClassName: "docs-clipboard-copied", value: "", @@ -60,7 +57,7 @@ export class ClickToCopy extends React.Component diff --git a/packages/docs/src/components/colorPalettes.tsx b/packages/docs-site/src/components/colorPalettes.tsx similarity index 98% rename from packages/docs/src/components/colorPalettes.tsx rename to packages/docs-site/src/components/colorPalettes.tsx index c79b25327c..a71b3fea4e 100644 --- a/packages/docs/src/components/colorPalettes.tsx +++ b/packages/docs-site/src/components/colorPalettes.tsx @@ -10,7 +10,7 @@ import * as React from "react"; import { Colors } from "@blueprintjs/core"; -import { ClickToCopy } from "../common/clickToCopy"; +import { ClickToCopy } from "./clickToCopy"; function expand(color: string) { return [`${color}1`, `${color}2`, `${color}3`, `${color}4`, `${color}5`]; diff --git a/packages/docs/src/components/colorSchemes.tsx b/packages/docs-site/src/components/colorSchemes.tsx similarity index 95% rename from packages/docs/src/components/colorSchemes.tsx rename to packages/docs-site/src/components/colorSchemes.tsx index 659488d8e9..7855893a83 100644 --- a/packages/docs/src/components/colorSchemes.tsx +++ b/packages/docs-site/src/components/colorSchemes.tsx @@ -7,13 +7,10 @@ import * as chroma from "chroma-js"; import * as classNames from "classnames"; -import * as PureRender from "pure-render-decorator"; import * as React from "react"; import { Classes, Keys, RadioGroup } from "@blueprintjs/core"; -import { handleNumberChange } from "@blueprintjs/core/examples/common/baseExample"; - -import { createKeyEventHandler } from "../common/utils"; +import { createKeyEventHandler, handleNumberChange } from "@blueprintjs/docs"; import { ColorBar } from "./colorPalettes"; const MIN_STEPS = 3; @@ -68,8 +65,7 @@ export interface IColorSchemeState { steps?: number; } -@PureRender -export class ColorScheme extends React.Component { +export class ColorScheme extends React.PureComponent { public state: IColorSchemeState = { activePalette: 0, activeSchema: 0, diff --git a/packages/docs/src/components/icon.tsx b/packages/docs-site/src/components/icon.tsx similarity index 92% rename from packages/docs/src/components/icon.tsx rename to packages/docs-site/src/components/icon.tsx index 7b99501a47..ccacf14299 100644 --- a/packages/docs/src/components/icon.tsx +++ b/packages/docs-site/src/components/icon.tsx @@ -6,12 +6,11 @@ */ import * as classNames from "classnames"; -import * as PureRender from "pure-render-decorator"; import * as React from "react"; import { ContextMenuTarget, Menu, MenuItem } from "@blueprintjs/core"; -import { ClickToCopy } from "../common/clickToCopy"; +import { ClickToCopy } from "./clickToCopy"; export interface IIcon { group: string; @@ -29,9 +28,8 @@ export interface IIconProps { const GITHUB_PATH = "https://github.com/palantir/blueprint/blob/master/resources/icons"; -@PureRender @ContextMenuTarget -export class Icon extends React.Component { +export class Icon extends React.PureComponent { public render() { const { className, name, tags } = this.props.icon; diff --git a/packages/docs/src/components/icons.tsx b/packages/docs-site/src/components/icons.tsx similarity index 95% rename from packages/docs/src/components/icons.tsx rename to packages/docs-site/src/components/icons.tsx index 238d524e3b..aa101a4056 100644 --- a/packages/docs/src/components/icons.tsx +++ b/packages/docs-site/src/components/icons.tsx @@ -5,10 +5,9 @@ * and https://github.com/palantir/blueprint/blob/master/PATENTS */ -import * as PureRender from "pure-render-decorator"; import * as React from "react"; -import { smartSearch } from "../common/utils"; +import { smartSearch } from "@blueprintjs/docs"; import { Icon, IFontIcon, IIcon } from "./icon"; @@ -28,8 +27,7 @@ export interface IIconsProps { icons?: IIcon[]; } -@PureRender -export class Icons extends React.Component { +export class Icons extends React.PureComponent { public static defaultProps: IIconsProps = { iconFilter: isIconFiltered, iconRenderer: renderIcon, diff --git a/packages/docs-site/src/components/navbarActions.tsx b/packages/docs-site/src/components/navbarActions.tsx new file mode 100644 index 0000000000..8387406e18 --- /dev/null +++ b/packages/docs-site/src/components/navbarActions.tsx @@ -0,0 +1,101 @@ +/* + * Copyright 2017-present 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 + */ + +import { + AnchorButton, + Classes, + Hotkey, + Hotkeys, + HotkeysTarget, + Menu, + MenuDivider, + MenuItem, + Popover, + Position, +} from "@blueprintjs/core"; + +import * as classNames from "classnames"; +import * as React from "react"; + +export interface IPackageInfo { + /** Name of package. Ignored for documentation site versions. */ + name?: string; + url: string; + version: string; +} + +export interface INavbarActionsProps { + onToggleDark: (useDark: boolean) => void; + releases: IPackageInfo[]; + useDarkTheme: boolean; +} + +@HotkeysTarget +export class NavbarActions extends React.PureComponent { + public render() { + return ( +
+ + + + + +
+ ); + } + + public renderHotkeys() { + return + + ; + } + + /** + * Render a list of the latest artifacts versions, including links to them on Stash and Artifactory. + * Also include a link to the GitHub release notes. + */ + private renderReleasesMenu() { + const menuItems = this.props.releases.map((version: IPackageInfo, index: number) => ( + + )); + return ( + + + + {menuItems} + + ); + } + + private handleDarkSwitchChange = () => { + this.props.onToggleDark(!this.props.useDarkTheme); + } +} diff --git a/packages/docs-site/src/docs-site.scss b/packages/docs-site/src/docs-site.scss new file mode 100644 index 0000000000..f619248a18 --- /dev/null +++ b/packages/docs-site/src/docs-site.scss @@ -0,0 +1,28 @@ +/** +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 +*/ + +@import "~normalize.css"; + +// import these first cuz they're the base layer +@import "~@blueprintjs/core"; +@import "~@blueprintjs/datetime"; +@import "~@blueprintjs/table"; + +// then the docs theme styles +@import "~@blueprintjs/docs"; +@import "~@blueprintjs/docs/src/styles/variables"; + +// then our own styles +@import "styles/colors"; +@import "styles/examples"; +@import "styles/icons"; +@import "styles/resources"; +@import "styles/sections"; + +.docs-logo { + background-image: url("../resources/blueprint-logo.svg"); +} diff --git a/packages/docs/src/index.html b/packages/docs-site/src/index.html similarity index 93% rename from packages/docs/src/index.html rename to packages/docs-site/src/index.html index 6a518715f1..b03d522c16 100644 --- a/packages/docs/src/index.html +++ b/packages/docs-site/src/index.html @@ -10,7 +10,7 @@ - + + diff --git a/packages/docs-site/src/index.tsx b/packages/docs-site/src/index.tsx new file mode 100644 index 0000000000..141779de06 --- /dev/null +++ b/packages/docs-site/src/index.tsx @@ -0,0 +1,48 @@ +/* + * 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 + */ + +import "dom4"; + +import * as React from "react"; +import * as ReactDOM from "react-dom"; + +import { createDefaultRenderers, IDocsData, ReactDocsTagRenderer, ReactExampleTagRenderer } from "@blueprintjs/docs"; + +import { BlueprintDocs } from "./components/blueprintDocs"; +import { IPackageInfo } from "./components/navbarActions"; +import * as ReactDocs from "./tags/reactDocs"; +import { reactExamples } from "./tags/reactExamples"; + +/* tslint:disable:no-var-requires */ +const docs = require("./generated/docs.json"); + +const releases = require("./generated/releases.json") + .map((pkg) => { + pkg.url = `https://www.npmjs.com/package/${pkg.name}`; + return pkg; + }); + +const versions = require("./generated/versions.json") + .map((version) => ({ + url: `https://palantir.github.io/blueprint/docs/${version}`, + version, + } as IPackageInfo)); +/* tslint:enable:no-var-requires */ + +const reactDocs = new ReactDocsTagRenderer(ReactDocs as any); +const reactExample = new ReactExampleTagRenderer(reactExamples); + +const tagRenderers = { + ...createDefaultRenderers(docs), + reactDocs: reactDocs.render, + reactExample: reactExample.render, +}; + +ReactDOM.render( + , + document.query("#blueprint-documentation"), +); diff --git a/packages/docs/src/require-shim.d.ts b/packages/docs-site/src/require-shim.d.ts similarity index 100% rename from packages/docs/src/require-shim.d.ts rename to packages/docs-site/src/require-shim.d.ts diff --git a/packages/docs/src/styles/_colors.scss b/packages/docs-site/src/styles/_colors.scss similarity index 99% rename from packages/docs/src/styles/_colors.scss rename to packages/docs-site/src/styles/_colors.scss index 07f0ef08ed..ad7415cbcf 100644 --- a/packages/docs/src/styles/_colors.scss +++ b/packages/docs-site/src/styles/_colors.scss @@ -3,10 +3,8 @@ // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE // and https://github.com/palantir/blueprint/blob/master/PATENTS -@import "variables"; - @import "~bourbon/app/assets/stylesheets/bourbon"; -@import "../../../core/src/common/icons"; +@import "~@blueprintjs/core/src/common/icons"; $palette-spacing: $pt-grid-size * 2; diff --git a/packages/docs-site/src/styles/_examples.scss b/packages/docs-site/src/styles/_examples.scss new file mode 100644 index 0000000000..707573a931 --- /dev/null +++ b/packages/docs-site/src/styles/_examples.scss @@ -0,0 +1,189 @@ +// Copyright 2016 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 + +@import "~@blueprintjs/core/src/common/icons"; +@import "~@blueprintjs/core/src/common/react-transition"; + +// Specific Example Customizations + +.docs-react-example { + .pt-slider:not(:last-child) { + margin-bottom: $options-margin; + } +} + +.docs-card-example { + display: flex; + justify-content: space-between; + + .pt-card { + width: floor(($content-width - $pt-grid-size * 10) / 3); + + &:hover a { + text-decoration: underline; + } + + p { + margin: 0; + } + } +} + +.docs-datetime-example { + > .pt-datepicker { + margin-bottom: $pt-grid-size * 2; + } + + > .pt-datetimepicker { + display: inline-block; + margin-bottom: $pt-grid-size * 2; + } + + .pt-icon-arrow-right { + margin: 0 ($pt-grid-size / 2); + } +} + +.docs-dialog-example { + display: flex; + align-items: center; + height: $pt-grid-size * 6; + + .pt-button + .pt-button { + margin-left: $pt-grid-size; + } +} + +.docs-editable-text-example { + width: 100%; + + h1 { + margin-bottom: $pt-grid-size * 3; + } +} + +.docs-overlay-example-transition { + $overlay-example-width: $pt-grid-size * 40; + $enter: ( + transform: (translateY(-50vh) rotate(-10deg), translateY(0) rotate(0deg)) + ); + $leave: ( + transform: (translateY(150vh) rotate(-20deg), translateY(0) rotate(0deg)) + ); + + @include react-transition-phase( + "pt-overlay", + "enter", + $enter, + $pt-transition-duration * 3, + $pt-transition-ease-bounce, + $before: "&" + ); + @include react-transition-phase( + "pt-overlay", + "leave", + $leave, + $pt-transition-duration * 5, + $before: "&" + ); + top: $overlay-example-width / 2; + left: calc(50% - #{$overlay-example-width / 2}); + z-index: $pt-z-index-overlay + 1; + width: $overlay-example-width; +} + +.docs-context-menu-example { + $node-size: $pt-grid-size * 8; + $icon-size: $pt-icon-size-standard * 2; + $node-border-width: 4px; + + display: flex; + flex-direction: column; + align-items: center; + justify-content: center; + + border-radius: $pt-border-radius; + background: $light-gray3; + padding: $options-margin; + + .pt-dark & { + background: $dark-gray5; + } + + .context-menu-node { + border: $node-border-width solid $white; + border-radius: 50%; + box-shadow: $pt-elevation-shadow-2; + background-color: $blue5; + width: $node-size; + height: $node-size; + overflow: hidden; + + &::before { + @include pt-icon($icon-size, 16); + position: relative; + top: ($node-size - $icon-size) / 2 - $node-border-width; + left: ($node-size - $icon-size) / 2 - $node-border-width; + color: $white; + content: $pt-icon-envelope; + } + + &.context-menu-open { + box-shadow: $pt-elevation-shadow-2, 0 0 0 4px $orange4; + } + } +} + +.docs-input-group-example { + .docs-flex-column { + margin-right: $options-margin; + } + + .pt-input-group { + width: $pt-grid-size * 30; + + &:first-child { + margin-bottom: $options-margin; + } + } +} + +.docs-progress-example { + .docs-react-example { + flex-direction: column; + } +} + +.docs-tabs2-example .pt-navbar .pt-tab { + line-height: $pt-navbar-height; +} + +.docs-example-wrapper .pt-navbar { + position: static; +} + +.docs-tag-example .pt-tag:not(:last-child) { + margin-right: $pt-grid-size * 0.5; +} + +.pt-progress-bar.docs-toast-progress { + margin-top: $pt-grid-size / 2; + margin-bottom: 0; +} + +.pt-popover .docs-popover-example { + padding: $pt-grid-size; +} + +.docs-wiggle { + animation: docs-wiggle-rotate $pt-transition-duration $pt-transition-ease infinite; +} + +@keyframes docs-wiggle-rotate { + 0% { transform: rotate(0); } + 25% { transform: rotate(-3deg); } + 75% { transform: rotate(3deg); } + 100% { transform: rotate(0); } +} diff --git a/packages/docs/src/styles/_icons.scss b/packages/docs-site/src/styles/_icons.scss similarity index 96% rename from packages/docs/src/styles/_icons.scss rename to packages/docs-site/src/styles/_icons.scss index 9fdd57373c..ceacb0719f 100644 --- a/packages/docs/src/styles/_icons.scss +++ b/packages/docs-site/src/styles/_icons.scss @@ -3,8 +3,8 @@ // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE // and https://github.com/palantir/blueprint/blob/master/PATENTS -@import "../../../core/src/common/variables"; -@import "../../../core/src/components/button/common"; +@import "~@blueprintjs/core/src/common/variables"; +@import "~@blueprintjs/core/src/components/button/common"; $svg-icon-size: 36px; diff --git a/packages/docs/src/styles/_resources.scss b/packages/docs-site/src/styles/_resources.scss similarity index 97% rename from packages/docs/src/styles/_resources.scss rename to packages/docs-site/src/styles/_resources.scss index 978fbae476..5d2fe1a437 100644 --- a/packages/docs/src/styles/_resources.scss +++ b/packages/docs-site/src/styles/_resources.scss @@ -1,5 +1,7 @@ // Copyright 2017 Palantir Technologies, Inc. All rights reserved. +$resources-path: "../resources"; + $asset-padding: $pt-grid-size; $asset-icon-size: $pt-grid-size * 6.4; diff --git a/packages/docs/src/styles/_sections.scss b/packages/docs-site/src/styles/_sections.scss similarity index 99% rename from packages/docs/src/styles/_sections.scss rename to packages/docs-site/src/styles/_sections.scss index 48dce83575..8ea5bd86a4 100644 --- a/packages/docs/src/styles/_sections.scss +++ b/packages/docs-site/src/styles/_sections.scss @@ -3,8 +3,6 @@ // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE // and https://github.com/palantir/blueprint/blob/master/PATENTS -@import "variables"; - // Generate a selector for a KSS example by reference @function reference($ref, $comparator: "=") { @return "[data-reference#{$comparator}\"#{$ref}\"]"; diff --git a/packages/docs/src/components/reactDocs.ts b/packages/docs-site/src/tags/reactDocs.ts similarity index 57% rename from packages/docs/src/components/reactDocs.ts rename to packages/docs-site/src/tags/reactDocs.ts index 6de5508a5c..02519a43e2 100644 --- a/packages/docs/src/components/reactDocs.ts +++ b/packages/docs-site/src/tags/reactDocs.ts @@ -1,5 +1,5 @@ /* - * Copyright 2015 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017 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 @@ -7,7 +7,7 @@ // These components can be references via the @react-docs flag -export * from "./colorPalettes"; -export * from "./colorSchemes"; -export * from "./icon"; -export * from "./icons"; +export * from "../components/colorPalettes"; +export * from "../components/colorSchemes"; +export * from "../components/icon"; +export * from "../components/icons"; diff --git a/packages/docs-site/src/tags/reactExamples.ts b/packages/docs-site/src/tags/reactExamples.ts new file mode 100644 index 0000000000..400ab1eab8 --- /dev/null +++ b/packages/docs-site/src/tags/reactExamples.ts @@ -0,0 +1,30 @@ +import { IBaseExampleProps, IExampleMap } from "@blueprintjs/docs"; +import * as React from "react"; + +import * as CoreExamples from "@blueprintjs/core/examples"; +import * as DateExamples from "@blueprintjs/datetime/examples"; +import * as TableExamples from "@blueprintjs/table/examples"; + +import { getTheme } from "../components/blueprintDocs"; + +const SRC_HREF_BASE = "https://github.com/palantir/blueprint/blob/master/packages"; + +export const reactExamples: IExampleMap = {}; + +function addPackageExamples( + packageName: string, + packageExamples: { [name: string]: React.ComponentClass }, +) { + for (const exampleName of Object.keys(packageExamples)) { + const example = packageExamples[exampleName]; + const fileName = exampleName.charAt(0).toLowerCase() + exampleName.slice(1) + ".tsx"; + reactExamples[exampleName] = { + render: (props) => React.createElement(example, { ...props, getTheme }), + sourceUrl: [SRC_HREF_BASE, packageName, "examples", fileName].join("/"), + }; + } +} + +addPackageExamples("core", CoreExamples as any); +addPackageExamples("datetime", DateExamples as any); +addPackageExamples("table", TableExamples as any); diff --git a/packages/docs-site/tsconfig.json b/packages/docs-site/tsconfig.json new file mode 100644 index 0000000000..a8f47130c1 --- /dev/null +++ b/packages/docs-site/tsconfig.json @@ -0,0 +1,44 @@ +{ + "version": "2.0.0", + "compilerOptions": { + "baseUrl": ".", + "declaration": false, + "experimentalDecorators": true, + "importHelpers": true, + "jsx": "react", + "lib": [ + "dom", + "es2015.core", + "es2015.collection", + "es2015.generator", + "es2015.iterable", + "es2015.promise", + "es2015.reflect", + "es2015.symbol", + "es5" + ], + "module": "commonjs", + "noFallthroughCasesInSwitch": true, + "noImplicitAny": true, + "noImplicitReturns": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "outDir": "dist/", + "removeComments": true, + "sourceMap": false, + "target": "es5", + "paths": { + "@blueprintjs/*": ["node_modules/@blueprintjs/*"] + } + }, + "include": [ + "typings/tsd.d.ts", + "src/**/*" + ], + "exclude": [ + "node_modules", + "build", + "test" + ], + "compileOnSave": false +} diff --git a/packages/docs/tsd.json b/packages/docs-site/tsd.json similarity index 100% rename from packages/docs/tsd.json rename to packages/docs-site/tsd.json diff --git a/packages/docs/typings/chroma-js/chroma-js.d.ts b/packages/docs-site/typings/chroma-js/chroma-js.d.ts similarity index 100% rename from packages/docs/typings/chroma-js/chroma-js.d.ts rename to packages/docs-site/typings/chroma-js/chroma-js.d.ts diff --git a/packages/docs/typings/tsd.d.ts b/packages/docs-site/typings/tsd.d.ts similarity index 100% rename from packages/docs/typings/tsd.d.ts rename to packages/docs-site/typings/tsd.d.ts diff --git a/packages/docs/.npmignore b/packages/docs/.npmignore new file mode 100644 index 0000000000..f77e43dac5 --- /dev/null +++ b/packages/docs/.npmignore @@ -0,0 +1,4 @@ +coverage/ +test/ +typings/ +tsd.json diff --git a/packages/docs/LICENSE b/packages/docs/LICENSE new file mode 100644 index 0000000000..e3d3c24325 --- /dev/null +++ b/packages/docs/LICENSE @@ -0,0 +1,39 @@ +The BSD License (as modified) + +Copyright (c) 2017, Palantir Technologies Inc. All rights reserved. + +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + * The name, trade names, trademarks, service marks, or product names of + Palantir or any of its contributors may not be used to endorse or promote + products derived from this software (including the user interface elements + embodied therein) without specific prior written permission. Nothing in + this license constitutes as permission to (i) use the software (including + the user interface elements embodied therein) in a way that is likely or + intended to cause confusion about the owner or source of products derived + from this software (including the user interface elements therein), or (ii) + assert or imply (other than any attribution notice) that products derived + from this software (including the user interface elements embodied therein) + are connected or affiliated with Palantir, its products, or its contributors + or sourced from or sponsored or endorsed by Palantir or its contributors. + +THIS SOFTWARE (INCLUDING THE USER INTERFACE ELEMENTS EMBODIED THEREIN) IS +PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT +SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE +OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE (INCLUDING THE +USER INTERFACE ELEMENTS EMBODIED THEREIN), EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. diff --git a/packages/docs/PATENTS b/packages/docs/PATENTS new file mode 100644 index 0000000000..d0cb66d715 --- /dev/null +++ b/packages/docs/PATENTS @@ -0,0 +1,45 @@ +Patent Grant + +1. Definitions. + +"Entity" means any person, corporation, partnership, limited liability company, +association, joint stock company, trust, joint venture, unincorporated +organization, governmental entity (or any department, agency, or political +subdivision thereof) or any other legal entity. + +"Palantir" means Palantir Technologies Inc., together with any Entity in +whatever country organized, that controls, is controlled by or is under common +control of Palantir Technologies Inc. The term "control" means possession, +direct or indirect, of the power to direct or cause the direction of the +management and policies of an Entity, whether by contract or otherwise. + +"Software" means the Blueprint software (including the user interface elements +embodied therein), in binary, source, or object form, including any +modifications or additions to the Blueprint software submitted for inclusion in +the software. + +"You" means each Entity that is a recipient of the Software. + +2. Grant of Patent License. Palantir hereby grants to You a perpetual, +worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated +in the termination provision below) patent license to make, have made, use, +offer to sell, import, and otherwise transfer the Software, where such license +applies only to those patent claims licensable by Palantir that are necessarily +infringed by the Software standing alone. For avoidance of doubt, no license is +granted under Palantir's rights in any patent claims that are infringed by (i) +modifications to the Software made by You or any third party or (ii) the +Software in combination with any software or other technology. + +3. Termination of Patent License. If You or Your agent or exclusive licensee +institute, directly or indirectly, or agree to the institution of or take +financial interest in any lawsuit or other action, including a cross-claim or +counterclaim, alleging direct, indirect, joint, or contributory infringement or +inducement to infringe any patent against: (i) Palantir, (ii) any party if such +allegation arises in whole or in part from any software, technology, product or +service of Palantir, or (iii) any party relating to the Software, then any and +all rights granted to You under this license shall terminate automatically and +without notice as of the date such assertion is made. Notwithstanding the +foregoing, if Palantir files a lawsuit alleging patent infringement against You +in the first instance, and, in response, You file a patent infringement +counterclaim that is unrelated to the Software, the license granted hereunder +will not terminate due to such counterclaim. diff --git a/packages/docs/README.md b/packages/docs/README.md index 15552dc813..784e41d7bc 100644 --- a/packages/docs/README.md +++ b/packages/docs/README.md @@ -1,12 +1,17 @@ -# [Blueprint Documentation](http://blueprintjs.com/docs) + -This project generates and aggregates the documentation from the packages -in this repo. +# [Blueprint](http://blueprintjs.com/) Documentation Theme -## Quick start +Blueprint is a React UI toolkit for the web. -From the root of the repo: +This package provides a React-based documentation theme for +[Documentalist](https://github.com/palantir/documentalist/), a tool for generating documentation +data from markdown files and documented source code. -1. Run `npm run bootstrap` -1. Run `npm run gulp` -1. Open your browser to http://localhost:9000 +## Installation + +``` +npm install --save @blueprintjs/docs +``` + +### [Full Documentation](http://blueprintjs.com/docs) | [Source Code](https://github.com/palantir/blueprint) diff --git a/packages/docs/package.json b/packages/docs/package.json index a1343f88ad..ea893df658 100644 --- a/packages/docs/package.json +++ b/packages/docs/package.json @@ -1,24 +1,20 @@ { "name": "@blueprintjs/docs", - "version": "1.12.0", - "description": "Blueprint Docs", - "main": "dist/index.html", - "private": true, + "version": "1.0.0", + "description": "Blueprint theme for documentalist", + "main": "dist/index.js", + "typings": "dist/index.d.ts", + "style": "dist/docs.css", + "unpkg": "dist/docs.bundle.js", "dependencies": { "@blueprintjs/core": "^1.12.0", - "@blueprintjs/datetime": "^1.10.0", - "@blueprintjs/table": "^1.9.0", - "chroma-js": "1.1.1", - "classnames": "2.2.5", - "dom4": "1.8.3", - "fuzzaldrin-plus": "0.3.1", - "moment": "2.15.1", - "normalize.css": "4.1.1", - "pure-render-decorator": "1.1.1", - "react": "15.4.0", - "react-addons-css-transition-group": "15.4.0", - "react-dom": "15.4.0", - "tslib": "1.5.0" + "classnames": "^2.2", + "documentalist": "^0.0.7", + "fuzzaldrin-plus": "^0.3.1", + "react": "^15.3.0", + "react-addons-css-transition-group": "^15.3.0", + "react-dom": "^15.3.0", + "tslib": "^1.5.0" }, "devDependencies": { "@types/fuzzaldrin-plus": "0.0.1", diff --git a/packages/docs/src/common/index.ts b/packages/docs/src/common/index.ts new file mode 100644 index 0000000000..eb88dce390 --- /dev/null +++ b/packages/docs/src/common/index.ts @@ -0,0 +1,9 @@ +/* + * Copyright 2017-present 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 + */ + +export * from "./propsStore"; +export * from "./utils"; diff --git a/packages/docs/src/common/propsStore.tsx b/packages/docs/src/common/propsStore.ts similarity index 63% rename from packages/docs/src/common/propsStore.tsx rename to packages/docs/src/common/propsStore.ts index 22f4a7ef3c..5eb1468f61 100644 --- a/packages/docs/src/common/propsStore.tsx +++ b/packages/docs/src/common/propsStore.ts @@ -1,4 +1,11 @@ -import { ITsInterfaceEntry, ITsPropertyEntry } from "documentalist/dist/plugins/typescript"; +/* + * Copyright 2017-present 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 + */ + +import { ITsInterfaceEntry, ITsPropertyEntry } from "documentalist/dist/client"; export interface IInheritedPropertyEntry extends ITsPropertyEntry { inheritedFrom?: string; @@ -7,8 +14,11 @@ export interface IInheritedPropertyEntry extends ITsPropertyEntry { export class PropsStore { constructor(private props: { [name: string]: ITsInterfaceEntry }) {} - public getProps = (name: string): IInheritedPropertyEntry[] => { - const entry = this.props[name]; + public getInterface = (name: string) => { + return this.props[name]; + } + + public getProps = (entry: ITsInterfaceEntry): IInheritedPropertyEntry[] => { if (entry == null) { return []; } else if (entry.extends == null) { @@ -26,7 +36,7 @@ export class PropsStore { } private getInheritedProps = (name: string) => { - return this.getProps(name).map((p: IInheritedPropertyEntry) => { + return this.getProps(this.getInterface(name)).map((p: IInheritedPropertyEntry) => { p.inheritedFrom = name; return p; }); diff --git a/packages/docs/src/common/pureComponent.tsx b/packages/docs/src/common/pureComponent.tsx deleted file mode 100644 index 6071e8a171..0000000000 --- a/packages/docs/src/common/pureComponent.tsx +++ /dev/null @@ -1,15 +0,0 @@ -/* - * @license Copyright 2016 Palantir Technologies, Inc. All rights reserved. - */ - -import * as PureRender from "pure-render-decorator"; -import * as React from "react"; - -@PureRender -export abstract class PureComponent extends React.Component { - // define this method so that subclasses can call super to invoke the shallow compare behavior as needed - public shouldComponentUpdate(_nextProps: P, _nextState: S): boolean { - // filled in by pure render decorator - return true; - } -} diff --git a/packages/docs/src/common/resolveDocs.ts b/packages/docs/src/common/resolveDocs.ts deleted file mode 100644 index b7df97931e..0000000000 --- a/packages/docs/src/common/resolveDocs.ts +++ /dev/null @@ -1,33 +0,0 @@ -/* - * Copyright 2016 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 - */ - -import * as React from "react"; - -// this is the default map, containing docs components defined locally. -import { TagRenderer } from "../components/page"; -import * as ReactDocs from "../components/reactDocs"; - -export interface IDocsMap { - [name: string]: React.ComponentClass<{}>; -}; - -/** - * Given the name of a component, like `"ColorSchemes"`, attempts to resolve - * it to an actual component class in the given map, or in the default map which contains - * valid docs components from this package. Provide a custom map to inject your own components. - */ -export const resolveDocs: TagRenderer = ({ value: componentName }, key) => { - if (componentName == null) { - return undefined; - } - - const docsComponent = (ReactDocs as any as IDocsMap)[componentName]; - if (docsComponent == null) { - throw new Error(`Unknown @reactDocs component: ${componentName}`); - } - return React.createElement(docsComponent, { key }); -}; diff --git a/packages/docs/src/common/resolveExample.tsx b/packages/docs/src/common/resolveExample.tsx deleted file mode 100644 index 16c28be248..0000000000 --- a/packages/docs/src/common/resolveExample.tsx +++ /dev/null @@ -1,87 +0,0 @@ -/* - * Copyright 2016 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 - */ - -import * as React from "react"; - -import * as CoreExamples from "@blueprintjs/core/examples"; -import * as DateExamples from "@blueprintjs/datetime/examples"; -import * as TableExamples from "@blueprintjs/table/examples"; - -import { TagRenderer } from "src/components/page"; -import { getTheme } from "./theme"; - -// tslint:disable-next-line no-empty-interface -export interface IExampleComponentClass extends React.ComponentClass { -} - -// construct a map of package name to all examples defined in that package. -// packageName must match directory name as it is used to generate sourceUrl. -export interface IExampleMap { - [packageName: string]: { - [componentName: string]: IExampleComponentClass; - }; -}; - -const Examples: IExampleMap = { - core: CoreExamples as any, - datetime: DateExamples as any, - table: TableExamples as any, -}; - -/** - * Searches the given examples for a component with the given name and returns the class - * and name of package in which it was found. - */ -export function getExample(componentName: string, examples: IExampleMap) { - for (const packageName of Object.keys(examples)) { - const component = examples[packageName][componentName]; - if (component != null) { - return { component, packageName }; - } - } - return { component: undefined, packageName: undefined }; -} - -const SRC_HREF_BASE = "https://github.com/palantir/blueprint/blob/master/packages"; - -export interface IExampleProps { - component: IExampleComponentClass; - name: string; - sourceUrl: string; -} - -const Example: React.SFC = (props) => ( -
- {React.createElement(props.component, { getTheme, id: props.name })} - -  View source on GitHub - -
-); - -/** - * Given the name of an example component, like `"AlertExample"`, attempts to resolve - * it to an actual example component exported by one of the packages. Also returns - * the URL of the source code on GitHub. - */ -export const resolveExample: TagRenderer = ({ value: exampleName }, key) => { - if (exampleName == null) { - return undefined; - } - - const { component, packageName } = getExample(exampleName, Examples); - if (component == null) { - throw new Error(`Unknown @example component: ${exampleName}`); - } - const fileName = exampleName.charAt(0).toLowerCase() + exampleName.slice(1) + ".tsx"; - return ; -}; diff --git a/packages/docs/src/common/theme.ts b/packages/docs/src/common/theme.ts deleted file mode 100644 index 7c1e338c11..0000000000 --- a/packages/docs/src/common/theme.ts +++ /dev/null @@ -1,18 +0,0 @@ -/* - * Copyright 2016 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 - */ - -const THEME_LOCAL_STORAGE_KEY = "pt-blueprint-theme"; - -/** Return the current theme className. */ -export function getTheme(): string { - return localStorage.getItem(THEME_LOCAL_STORAGE_KEY); -} - -/** Persist the current theme className in local storage. */ -export function setTheme(themeName: string) { - localStorage.setItem(THEME_LOCAL_STORAGE_KEY, themeName); -} diff --git a/packages/docs/src/common/utils.ts b/packages/docs/src/common/utils.ts index 26587e760d..dadeb3ef7f 100644 --- a/packages/docs/src/common/utils.ts +++ b/packages/docs/src/common/utils.ts @@ -1,5 +1,5 @@ /* - * Copyright 2016 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 @@ -19,7 +19,7 @@ export function dedent(strings: TemplateStringsArray, ...values: Array<{ toStrin }); // match all leading spaces/tabs at the start of each line - const match = fullString.match(/^[ \t]*(?=\S)/gm); + const match = fullString.match(/^[ \t]*(?=\S)/gm)!; // find the smallest indent, we don't want to remove all leading whitespace const indent = Math.min(...match.map((el) => el.length)); const regexp = new RegExp("^[ \\t]{" + indent + "}", "gm"); diff --git a/packages/core/examples/common/baseExample.tsx b/packages/docs/src/components/baseExample.tsx similarity index 90% rename from packages/core/examples/common/baseExample.tsx rename to packages/docs/src/components/baseExample.tsx index ccf8f9ccbf..9bc9d87d85 100644 --- a/packages/core/examples/common/baseExample.tsx +++ b/packages/docs/src/components/baseExample.tsx @@ -1,12 +1,11 @@ /* - * Copyright 2016 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 */ import * as classNames from "classnames"; -import * as PureRender from "pure-render-decorator"; import * as React from "react"; export interface IBaseExampleProps { @@ -18,8 +17,7 @@ export interface IBaseExampleProps { * Starter class for all React example components. * Examples and options are rendered into separate containers. */ -@PureRender -export default class BaseExample extends React.Component { +export class BaseExample extends React.PureComponent { /** Define this prop to add a className to the example container */ protected className: string; @@ -35,7 +33,7 @@ export default class BaseExample extends React.Component { + if (typeof node === "string") { + return
; + } + try { + const renderer = tagRenderers[node.tag]; + if (renderer === undefined) { + throw new Error(`Unknown @tag: ${node.tag}`); + } + return renderer(node, i, tagRenderers, page); + } catch (ex) { + console.error(ex.message); + return

{ex.message}

; + } + }); +} diff --git a/packages/docs/src/components/styleguide.tsx b/packages/docs/src/components/documentation.tsx similarity index 69% rename from packages/docs/src/components/styleguide.tsx rename to packages/docs/src/components/documentation.tsx index 59c261f8b5..da6f241b48 100644 --- a/packages/docs/src/components/styleguide.tsx +++ b/packages/docs/src/components/documentation.tsx @@ -1,81 +1,69 @@ /* - * Copyright 2015 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 */ import * as classNames from "classnames"; -import { IPageData, IPageNode, isPageNode } from "documentalist/dist/client"; -import * as PureRender from "pure-render-decorator"; +import { IMarkdownPluginData, isPageNode } from "documentalist/dist/client"; import * as React from "react"; -import { Hotkey, Hotkeys, HotkeysTarget, IHotkeysDialogProps, setHotkeysDialogProps } from "@blueprintjs/core"; +import { FocusStyleManager, Hotkey, Hotkeys, HotkeysTarget, IProps, Utils } from "@blueprintjs/core"; -import { getTheme, setTheme } from "../common/theme"; import { eachLayoutNode } from "../common/utils"; -import { Navbar } from "./navbar"; +import { TagRenderer } from "../tags"; import { Navigator } from "./navigator"; import { NavMenu } from "./navMenu"; -import { Page, TagRenderer } from "./page"; +import { Page } from "./page"; -// these interfaces are essential to the docs app, so it's helpful to re-export here -export { IInterfaceEntry, IPropertyEntry } from "ts-quick-docs/dist/interfaces"; - -const DARK_THEME = "pt-dark"; -const LIGHT_THEME = ""; - -// TODO: this is unused until we implement CSS docs -export interface IStyleguideModifier { - className?: string; - description: string; - name: string; -} - -export interface IPackageInfo { - /** Name of package. Ignored for documentation site versions. */ - name?: string; - url: string; - version: string; -} - -export interface IStyleguideProps { +export interface IDocumentationProps extends IProps { /** * Default page to render in the absence of a hash route. */ defaultPageId: string; /** - * Callback invoked whenever the documentation state updates (typically page or theme change). - * Use it to run non-React code on the newly rendered sections. + * All the docs data from Documentalist. + * Must include at least `{ nav, pages }` from the MarkdownPlugin. */ - onUpdate: (pageId: string) => void; - - /** A multi-rooted tree describing the layout of pages in the styleguide. */ - layout: IPageNode[]; + docs: IMarkdownPluginData; - /** All pages in the documentation. */ - pages: { [ref: string]: IPageData }; + /** + * Callback invoked whenever the component props or state change (specifically, + * called in `componentDidMount` and `componentDidUpdate`). + * Use it to run non-React code on the newly rendered sections. + */ + onComponentUpdate?: (pageId: string) => void; /** Tag renderer functions. Unknown tags will log console errors. */ tagRenderers: { [tag: string]: TagRenderer }; - /** Release versions for published documentation. */ - versions: IPackageInfo[]; + /** + * Elements to render on the left side of the navbar, typically logo and title. + * All elements will be wrapped in a single `.pt-navbar-group`. + * @default "Documentation" + */ + navbarLeft?: React.ReactNode; - /** Latest release versions for published projects. */ - releases: IPackageInfo[]; + /** + * Element to render on the right side of the navbar, typically links and actions. + * All elements will be wrapped in a single `.pt-navbar-group`. + */ + navbarRight?: React.ReactNode; } -export interface IStyleguideState { - activePageId?: string; - activeSectionId?: string; - themeName?: string; +export interface IDocumentationState { + activePageId: string; + activeSectionId: string; } @HotkeysTarget -@PureRender -export class Styleguide extends React.Component { +export class Documentation extends React.PureComponent { + public static defaultProps = { + navbarLeft: "Documentation", + }; + /** Map of section route to containing page reference. */ private routeToPage: { [route: string]: string }; @@ -86,39 +74,41 @@ export class Styleguide extends React.Component this.navElement = ref, }; - public constructor(props: IStyleguideProps) { + public constructor(props: IDocumentationProps) { super(props); this.state = { activePageId: props.defaultPageId, activeSectionId: props.defaultPageId, - themeName: getTheme(), }; // build up static map of all references to their page, for navigation / routing this.routeToPage = {}; - eachLayoutNode(this.props.layout, (node, parents) => { + eachLayoutNode(this.props.docs.nav, (node, parents) => { const { reference } = isPageNode(node) ? node : parents[0]; this.routeToPage[node.route] = reference; }); } public render() { - const { activePageId, activeSectionId, themeName } = this.state; - const { layout, pages } = this.props; + const { activePageId, activeSectionId } = this.state; + const { nav, pages } = this.props.docs; return ( -
+
- - - +
+
+ {this.props.navbarLeft} +
+
+ +
+
+ {this.props.navbarRight} +
+
{ if (location.hostname.indexOf("blueprint") !== -1) { @@ -159,7 +151,6 @@ export class Styleguide extends React.Component { - const themeName = useDark ? DARK_THEME : LIGHT_THEME; - this.setState({ themeName }); - setTheme(themeName); + this.setState({ ...this.state, activeSectionId }); } private maybeScrollToActivePageMenuItem() { @@ -266,6 +250,9 @@ function getScrolledReference(offset: number, container: HTMLElement, scrollPare */ function scrollToReference(reference: string, container: HTMLElement, scrollParent = document.body) { const headingAnchor = queryHTMLElement(container, `a[name="${reference}"]`); - const scrollOffset = headingAnchor.parentElement.offsetTop + headingAnchor.offsetTop; + if (headingAnchor == null || headingAnchor.parentElement == null) { + return; + } + const scrollOffset = headingAnchor.parentElement!.offsetTop + headingAnchor.offsetTop; scrollParent.scrollTop = scrollOffset; } diff --git a/packages/docs/src/components/propsTable.tsx b/packages/docs/src/components/interfaceTable.tsx similarity index 71% rename from packages/docs/src/components/propsTable.tsx rename to packages/docs/src/components/interfaceTable.tsx index d64b52255b..7c3592c8a5 100644 --- a/packages/docs/src/components/propsTable.tsx +++ b/packages/docs/src/components/interfaceTable.tsx @@ -1,5 +1,5 @@ /* - * Copyright 2016 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 @@ -7,8 +7,11 @@ import { Classes, Intent, Tag } from "@blueprintjs/core"; import * as classNames from "classnames"; +import { ITsInterfaceEntry } from "documentalist/dist/client"; import * as React from "react"; import { IInheritedPropertyEntry } from "../common/propsStore"; +import { ITagRendererMap } from "../tags"; +import { renderContentsBlock } from "./block"; // HACKHACK support `code` blocks until we get real markdown parsing in ts-quick-docs function dirtyMarkdown(text: string) { @@ -47,7 +50,7 @@ const renderPropRow = (prop: IInheritedPropertyEntry) => { if (deprecated) { const maybeMessage = typeof deprecated === "string" ? - : undefined; + : ""; tags.push(propTag(Intent.DANGER, "Deprecated", maybeMessage)); } if (inheritedFrom != null) { @@ -74,20 +77,29 @@ const renderPropRow = (prop: IInheritedPropertyEntry) => { ); }; -export const PropsTable: React.SFC<{ name: string, props: IInheritedPropertyEntry[] }> = ({ name, props }) => ( -
-
{name}
- - - - - - - - - {props.map(renderPropRow)} - -
PropDescription
-
-); -PropsTable.displayName = "Docs.PropsTable"; +export interface IInterfaceTableProps { + iface: ITsInterfaceEntry; + props: IInheritedPropertyEntry[]; + tagRenderers: ITagRendererMap; +} + +export const InterfaceTable: React.SFC = ({iface, props, tagRenderers }) => { + return ( +
+
{iface.name}
+ {renderContentsBlock(iface.documentation.contents, tagRenderers)} + + + + + + + + + {props.map(renderPropRow)} + +
PropDescription
+
+ ); +}; +InterfaceTable.displayName = "Docs.InterfaceTable"; diff --git a/packages/docs/src/components/modifierTable.tsx b/packages/docs/src/components/modifierTable.tsx index 17ade715c0..c67e71e16e 100644 --- a/packages/docs/src/components/modifierTable.tsx +++ b/packages/docs/src/components/modifierTable.tsx @@ -1,5 +1,5 @@ /* - * Copyright 2016 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 diff --git a/packages/docs/src/components/navMenu.tsx b/packages/docs/src/components/navMenu.tsx index 36a69b9bb2..65ca3348c9 100644 --- a/packages/docs/src/components/navMenu.tsx +++ b/packages/docs/src/components/navMenu.tsx @@ -1,5 +1,5 @@ /* - * Copyright 2015 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 diff --git a/packages/docs/src/components/navbar.tsx b/packages/docs/src/components/navbar.tsx deleted file mode 100644 index a8f759e21a..0000000000 --- a/packages/docs/src/components/navbar.tsx +++ /dev/null @@ -1,134 +0,0 @@ -/* - * Copyright 2016 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 - */ - -import { - AnchorButton, - Classes, - Hotkey, - Hotkeys, - HotkeysTarget, - Menu, - MenuDivider, - MenuItem, - Popover, - Position, -} from "@blueprintjs/core"; - -import * as classNames from "classnames"; -import * as PureRender from "pure-render-decorator"; -import * as React from "react"; - -import { IPackageInfo } from "./styleguide"; - -export interface INavbarProps { - onToggleDark: (useDark: boolean) => void; - releases: IPackageInfo[]; - useDarkTheme: boolean; - versions: IPackageInfo[]; -} - -@PureRender -@HotkeysTarget -export class Navbar extends React.Component { - public render() { - return ( - - ); - } - - public renderHotkeys() { - return - - ; - } - - /** - * Render a list of the latest artifacts versions, including links to them on Stash and Artifactory. - * Also include a link to the GitHub release notes. - */ - private renderReleasesMenu() { - const menuItems = this.props.releases.map((version: IPackageInfo, index: number) => ( - - )); - return ( - - - - {menuItems} - - ); - } - - private renderVersionsMenu() { - const { versions } = this.props; - if (versions.length === 1) { - return
v{versions[0].version}
; - } - - const match = /releases\/([^\/]+)\/dist/.exec(location.href); - // default to latest release if we can't find a tag in the URL - const currentRelease = (match == null ? versions[0].version : match[1]); - const releaseItems = versions.map((rel, i) => ( - - )); - const menu = {releaseItems}; - - return ( - - - - ); - } - - private handleDarkSwitchChange = () => { - this.props.onToggleDark(!this.props.useDarkTheme); - } -} diff --git a/packages/docs/src/components/navigator.tsx b/packages/docs/src/components/navigator.tsx index e3fcebe24d..bdb53182bd 100644 --- a/packages/docs/src/components/navigator.tsx +++ b/packages/docs/src/components/navigator.tsx @@ -1,5 +1,5 @@ /* - * Copyright 2016 Palantir Technologies, Inc. All rights reserved. + * Copyright 2017-present 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 @@ -17,16 +17,15 @@ import { Popover, Position, } from "@blueprintjs/core"; -import { handleStringChange } from "@blueprintjs/core/examples/common/baseExample"; import * as classNames from "classnames"; import { IHeadingNode, IPageNode } from "documentalist/dist/client"; import { filter } from "fuzzaldrin-plus"; -import * as PureRender from "pure-render-decorator"; import * as React from "react"; import { findDOMNode } from "react-dom"; import { createKeyEventHandler, eachLayoutNode } from "../common/utils"; +import { handleStringChange } from "./baseExample"; export interface INavigatorProps { items: Array; @@ -34,8 +33,8 @@ export interface INavigatorProps { } export interface INavigatorState { - query?: string; - selectedIndex?: number; + query: string; + selectedIndex: number; } interface INavigationSection { @@ -45,9 +44,8 @@ interface INavigationSection { title: string; } -@PureRender @HotkeysTarget -export class Navigator extends React.Component { +export class Navigator extends React.PureComponent { public state: INavigatorState = { query: "", selectedIndex: 0, @@ -180,12 +178,15 @@ export class Navigator extends React.Component private handleResultHover = (e: React.MouseEvent) => { const el = e.currentTarget as HTMLElement; - const selectedIndex: number = Array.prototype.indexOf.call(el.parentElement.children, el); - this.setState({ selectedIndex }); + if (el.parentElement != null) { + const selectedIndex: number = Array.prototype.indexOf.call(el.parentElement.children, el); + this.setState({ ...this.state, selectedIndex }); + } } private selectNext(direction = 1) { return () => this.setState({ + ...this.state, selectedIndex: Math.max(0, this.state.selectedIndex + direction), }); } diff --git a/packages/docs/src/components/page.tsx b/packages/docs/src/components/page.tsx index 34dbe52616..5f37dd5667 100644 --- a/packages/docs/src/components/page.tsx +++ b/packages/docs/src/components/page.tsx @@ -1,31 +1,22 @@ -import * as React from "react"; +/* + * Copyright 2017-present 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 + */ -import { IPageData, ITag } from "documentalist/dist/client"; +import * as React from "react"; -export type TagRenderer = (tag: ITag, key: React.Key, page: IPageData) => JSX.Element | undefined; +import { IPageData } from "documentalist/dist/client"; +import { ITagRendererMap } from "../tags"; +import { renderContentsBlock } from "./block"; export interface IPageProps { page: IPageData; - tagRenderers: { [tag: string]: TagRenderer }; + tagRenderers: ITagRendererMap; } export const Page: React.SFC = ({ tagRenderers, page }) => { - const pageContents = page.contents.map((node, i) => { - if (typeof node === "string") { - return
; - } - - // try rendering the tag, - try { - const renderer = tagRenderers[node.tag]; - if (renderer === undefined) { - throw new Error(`Unknown @tag: ${node.tag}`); - } - return renderer(node, i, page); - } catch (ex) { - console.error(ex.message); - return

{ex.message}

; - } - }); + const pageContents = renderContentsBlock(page.contents, tagRenderers, page); return
{pageContents}
; }; diff --git a/packages/docs/src/docs.scss b/packages/docs/src/docs.scss index 09197096ba..6dc537e171 100644 --- a/packages/docs/src/docs.scss +++ b/packages/docs/src/docs.scss @@ -5,21 +5,11 @@ of the license at https://github.com/palantir/blueprint/blob/master/LICENSE and https://github.com/palantir/blueprint/blob/master/PATENTS */ -@import "~normalize.css"; - -@import "~@blueprintjs/core"; -@import "~@blueprintjs/datetime"; -@import "~@blueprintjs/table"; - -@import "styles/colors"; @import "styles/content"; @import "styles/examples"; -@import "styles/icons"; @import "styles/layout"; @import "styles/navbar"; @import "styles/navigator"; @import "styles/overrides"; @import "styles/props"; -@import "styles/resources"; -@import "styles/sections"; @import "styles/syntax"; diff --git a/packages/docs/src/index.ts b/packages/docs/src/index.ts new file mode 100644 index 0000000000..f4d557e481 --- /dev/null +++ b/packages/docs/src/index.ts @@ -0,0 +1,13 @@ +/* + * Copyright 2017-present 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 + */ + +import "dom4"; + +export * from "./components/baseExample"; +export * from "./components/documentation"; +export * from "./common"; +export * from "./tags"; diff --git a/packages/docs/src/index.tsx b/packages/docs/src/index.tsx deleted file mode 100644 index fd33c78fb5..0000000000 --- a/packages/docs/src/index.tsx +++ /dev/null @@ -1,102 +0,0 @@ -/* - * 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 - */ - -import "dom4"; - -import { FocusStyleManager } from "@blueprintjs/core"; -import * as React from "react"; -import * as ReactDOM from "react-dom"; - -import { CssExample } from "./common/cssExample"; -import { PropsStore } from "./common/propsStore"; -import { resolveDocs } from "./common/resolveDocs"; -import { resolveExample } from "./common/resolveExample"; -import { TagRenderer } from "./components/page"; -import { PropsTable } from "./components/propsTable"; -import { IPackageInfo, Styleguide } from "./components/styleguide"; - -import { IHeadingTag } from "documentalist/dist/client"; -import { IKssPluginData, IMarkdownPluginData, ITypescriptPluginData } from "documentalist/dist/plugins"; - -interface IDocsData extends IKssPluginData, IMarkdownPluginData, ITypescriptPluginData { -} - -/* tslint:disable:no-var-requires */ -const docs = require("./generated/docs.json"); - -const releases = require("./generated/releases.json") - .map((pkg) => { - pkg.url = `https://www.npmjs.com/package/${pkg.name}`; - return pkg; - }); -const versions = require("./generated/versions.json") - .map((version) => ({ - url: `https://palantir.github.io/blueprint/docs/${version}`, - version, - } as IPackageInfo)); -/* tslint:enable:no-var-requires */ - -const resolveCssExample: TagRenderer = ({ value: reference }, key) => { - const example = docs.css[reference]; - if (example === undefined || example.reference === undefined) { - throw new Error(`Unknown @css reference: ${reference}`); - } - return ; -}; - -const propsStore = new PropsStore(docs.ts); -const resolveInterface: TagRenderer = ({ value: name }, key) => { - const props = propsStore.getProps(name); - return ; -}; - -const Heading: React.SFC = ({ level, route, value }) => ( - // use createElement so we can dynamically choose tag based on depth - React.createElement(`h${level}`, { className: "docs-title" }, - , - - - , - value, - ) -); -Heading.displayName = "Docs.Heading"; -const renderHeading: TagRenderer = (heading: IHeadingTag, key) => ; - -// tslint:disable:object-literal-key-quotes -const TAGS = { - css: resolveCssExample, - heading: renderHeading, - interface: resolveInterface, - page: () => undefined as JSX.Element, - reactDocs: resolveDocs, - reactExample: resolveExample, -}; - -// This function is called whenever the documentation page changes and should be used to -// run non-React code on the newly rendered sections. -const updateExamples = () => { - // indeterminate checkbox styles must be applied via JavaScript. - document.queryAll(".pt-checkbox input[indeterminate]").forEach((el: HTMLInputElement) => { - el.indeterminate = true; - }); -}; - -ReactDOM.render( - , - document.query("#blueprint-documentation"), -); - -FocusStyleManager.onlyShowFocusOnTabs(); diff --git a/packages/docs/src/styles/_content.scss b/packages/docs/src/styles/_content.scss index 8ab7981515..8d0dddbefe 100644 --- a/packages/docs/src/styles/_content.scss +++ b/packages/docs/src/styles/_content.scss @@ -1,4 +1,4 @@ -// Copyright 2015 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 diff --git a/packages/docs/src/styles/_examples.scss b/packages/docs/src/styles/_examples.scss index 478d31c8a0..91e48ddc77 100644 --- a/packages/docs/src/styles/_examples.scss +++ b/packages/docs/src/styles/_examples.scss @@ -1,13 +1,8 @@ -// Copyright 2016 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 -@import "../../../core/src/common/react-transition"; - -$options-width: $pt-grid-size * 18; -$options-margin: $pt-grid-size * 3; - // Base Styles for All Examples .docs-react-example, @@ -57,185 +52,3 @@ $options-margin: $pt-grid-size * 3; margin-right: 0; } } - -// Specific Example Customizations - -.docs-react-example { - .pt-slider:not(:last-child) { - margin-bottom: $options-margin; - } -} - -.docs-card-example { - display: flex; - justify-content: space-between; - - .pt-card { - width: floor(($content-width - $pt-grid-size * 10) / 3); - - &:hover a { - text-decoration: underline; - } - - p { - margin: 0; - } - } -} - -.docs-datetime-example { - > .pt-datepicker { - margin-bottom: $pt-grid-size * 2; - } - - > .pt-datetimepicker { - display: inline-block; - margin-bottom: $pt-grid-size * 2; - } - - .pt-icon-arrow-right { - margin: 0 ($pt-grid-size / 2); - } -} - -.docs-dialog-example { - display: flex; - align-items: center; - height: $pt-grid-size * 6; - - .pt-button + .pt-button { - margin-left: $pt-grid-size; - } -} - -.docs-editable-text-example { - width: 100%; - - h1 { - margin-bottom: $pt-grid-size * 3; - } -} - -.docs-overlay-example-transition { - $overlay-example-width: $pt-grid-size * 40; - $enter: ( - transform: (translateY(-50vh) rotate(-10deg), translateY(0) rotate(0deg)) - ); - $leave: ( - transform: (translateY(150vh) rotate(-20deg), translateY(0) rotate(0deg)) - ); - - @include react-transition-phase( - "pt-overlay", - "enter", - $enter, - $pt-transition-duration * 3, - $pt-transition-ease-bounce, - $before: "&" - ); - @include react-transition-phase( - "pt-overlay", - "leave", - $leave, - $pt-transition-duration * 5, - $before: "&" - ); - top: $overlay-example-width / 2; - left: calc(50% - #{$overlay-example-width / 2}); - z-index: $pt-z-index-overlay + 1; - width: $overlay-example-width; -} - -.docs-context-menu-example { - $node-size: $pt-grid-size * 8; - $icon-size: $pt-icon-size-standard * 2; - $node-border-width: 4px; - - display: flex; - flex-direction: column; - align-items: center; - justify-content: center; - - border-radius: $pt-border-radius; - background: $light-gray3; - padding: $options-margin; - - .pt-dark & { - background: $dark-gray5; - } - - .context-menu-node { - border: $node-border-width solid $white; - border-radius: 50%; - box-shadow: $pt-elevation-shadow-2; - background-color: $blue5; - width: $node-size; - height: $node-size; - overflow: hidden; - - &::before { - @include pt-icon($icon-size, 16); - position: relative; - top: ($node-size - $icon-size) / 2 - $node-border-width; - left: ($node-size - $icon-size) / 2 - $node-border-width; - color: $white; - content: $pt-icon-envelope; - } - - &.context-menu-open { - box-shadow: $pt-elevation-shadow-2, 0 0 0 4px $orange4; - } - } -} - -.docs-input-group-example { - .docs-flex-column { - margin-right: $options-margin; - } - - .pt-input-group { - width: $pt-grid-size * 30; - - &:first-child { - margin-bottom: $options-margin; - } - } -} - -.docs-progress-example { - .docs-react-example { - flex-direction: column; - } -} - -.docs-tabs2-example .pt-navbar .pt-tab { - line-height: $pt-navbar-height; -} - -.docs-example-wrapper .pt-navbar { - position: static; -} - -.docs-tag-example .pt-tag:not(:last-child) { - margin-right: $pt-grid-size * 0.5; -} - -.pt-progress-bar.docs-toast-progress { - margin-top: $pt-grid-size / 2; - margin-bottom: 0; -} - -.pt-popover .docs-popover-example { - padding: $pt-grid-size; -} - -.docs-wiggle { - animation: docs-wiggle-rotate $pt-transition-duration $pt-transition-ease infinite; -} - -@keyframes docs-wiggle-rotate { - 0% { transform: rotate(0); } - 25% { transform: rotate(-3deg); } - 75% { transform: rotate(3deg); } - 100% { transform: rotate(0); } -} diff --git a/packages/docs/src/styles/_layout.scss b/packages/docs/src/styles/_layout.scss index d547e7614c..e8c9efe643 100644 --- a/packages/docs/src/styles/_layout.scss +++ b/packages/docs/src/styles/_layout.scss @@ -1,4 +1,4 @@ -// Copyright 2015 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 diff --git a/packages/docs/src/styles/_navbar.scss b/packages/docs/src/styles/_navbar.scss index d0b473cdc7..bc399acdc3 100644 --- a/packages/docs/src/styles/_navbar.scss +++ b/packages/docs/src/styles/_navbar.scss @@ -1,4 +1,4 @@ -// Copyright 2016 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 @@ -39,7 +39,6 @@ All the components that live *inside* the navbar. .docs-logo { margin: $pt-grid-size; - background-image: url("../resources/blueprint-logo.svg"); background-repeat: no-repeat; background-size: 100% auto; width: $logo-width; diff --git a/packages/docs/src/styles/_navigator.scss b/packages/docs/src/styles/_navigator.scss index 90cf83b490..32e9f897fd 100644 --- a/packages/docs/src/styles/_navigator.scss +++ b/packages/docs/src/styles/_navigator.scss @@ -1,4 +1,7 @@ -// Copyright 2016 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 $navigator-height: $pt-grid-size * 24; $navigator-min-width: $pt-grid-size * 22; diff --git a/packages/docs/src/styles/_overrides.scss b/packages/docs/src/styles/_overrides.scss index f37755df5a..e049411c1d 100644 --- a/packages/docs/src/styles/_overrides.scss +++ b/packages/docs/src/styles/_overrides.scss @@ -1,4 +1,7 @@ -// Copyright 2015 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 .pt-table { width: 100%; diff --git a/packages/docs/src/styles/_props.scss b/packages/docs/src/styles/_props.scss index 11cca061db..ccea7978ae 100644 --- a/packages/docs/src/styles/_props.scss +++ b/packages/docs/src/styles/_props.scss @@ -1,4 +1,7 @@ -// Copyright 2016 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 .docs-prop-details code { box-shadow: none; diff --git a/packages/docs/src/styles/_syntax.scss b/packages/docs/src/styles/_syntax.scss index d32533aee9..2e214b0d90 100644 --- a/packages/docs/src/styles/_syntax.scss +++ b/packages/docs/src/styles/_syntax.scss @@ -1,3 +1,8 @@ +// Copyright 2017-present 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 + @import "variables"; $syntax-background-color: $white; diff --git a/packages/docs/src/styles/_variables.scss b/packages/docs/src/styles/_variables.scss index 12d92b1e61..82a910043c 100644 --- a/packages/docs/src/styles/_variables.scss +++ b/packages/docs/src/styles/_variables.scss @@ -1,9 +1,10 @@ -// Copyright 2016 Palantir Technologies, Inc. All rights reserved. +// Copyright 2017-present 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 -@import "../../../core/src/common/variables"; -@import "../../../core/src/common/mixins"; - -$resources-path: "../resources"; +@import "~@blueprintjs/core/src/common/variables"; +@import "~@blueprintjs/core/src/common/mixins"; $container-width: $pt-grid-size * 100; @@ -14,3 +15,6 @@ $content-width: $container-width - $sidebar-width; $content-padding: $pt-grid-size * 3; $content-background-color: $light-gray5; $dark-content-background-color: $dark-gray3; + +$options-width: $pt-grid-size * 18; +$options-margin: $pt-grid-size * 3; diff --git a/packages/docs/src/common/cssExample.tsx b/packages/docs/src/tags/css.tsx similarity index 57% rename from packages/docs/src/common/cssExample.tsx rename to packages/docs/src/tags/css.tsx index e8c61b6356..b3b96d81d0 100644 --- a/packages/docs/src/common/cssExample.tsx +++ b/packages/docs/src/tags/css.tsx @@ -1,6 +1,14 @@ -import { IKssExample, IKssModifier } from "documentalist/dist/plugins"; +/* + * Copyright 2017-present 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 + */ + +import { IKssExample, IKssModifier, IKssPluginData } from "documentalist/dist/client"; import * as React from "react"; import { ModifierTable } from "../components/modifierTable"; +import { TagRenderer } from "./"; const MODIFIER_PLACEHOLDER = /\{\{([\.\:]?)modifier\}\}/g; const DEFAULT_MODIFIER: IKssModifier = { @@ -8,7 +16,7 @@ const DEFAULT_MODIFIER: IKssModifier = { name: "default", }; -export const CssExample: React.SFC = ({ markup, markupHtml, modifiers, reference }) => ( +const CssExample: React.SFC = ({ markup, markupHtml, modifiers, reference }) => (
{modifiers.length > 0 ? : undefined}
@@ -37,3 +45,15 @@ function renderMarkupForModifier(markup: string, modifier: IKssModifier) {
); } + +export class CssTagRenderer { + constructor(private docs: IKssPluginData) {} + + public render: TagRenderer = ({ value: reference }, key) => { + const example = this.docs.css[reference]; + if (example === undefined || example.reference === undefined) { + throw new Error(`Unknown @css reference: ${reference}`); + } + return ; + } +} diff --git a/packages/docs/src/tags/defaults.ts b/packages/docs/src/tags/defaults.ts new file mode 100644 index 0000000000..a3b6e4d634 --- /dev/null +++ b/packages/docs/src/tags/defaults.ts @@ -0,0 +1,27 @@ +/* + * Copyright 2017-present 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 + */ + +import * as tags from "./"; + +import { IKssPluginData, IMarkdownPluginData, ITypescriptPluginData } from "documentalist/dist/client"; + +export interface IDocsData extends IKssPluginData, IMarkdownPluginData, ITypescriptPluginData { +} + +export function createDefaultRenderers(docs: IDocsData) { + const css = new tags.CssTagRenderer(docs); + const heading = new tags.HeadingTagRenderer(); + const iface = new tags.InterfaceTagRenderer(docs); + const page = new tags.PageTagRenderer(); + + return { + css: css.render, + heading: heading.render, + interface: iface.render, + page: page.render, + }; +} diff --git a/packages/docs/src/tags/heading.tsx b/packages/docs/src/tags/heading.tsx new file mode 100644 index 0000000000..265f23a2b2 --- /dev/null +++ b/packages/docs/src/tags/heading.tsx @@ -0,0 +1,26 @@ +/* + * Copyright 2017-present 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 + */ + +import { IHeadingTag } from "documentalist/dist/client"; +import * as React from "react"; +import { TagRenderer } from "./"; + +const Heading: React.SFC = ({ level, route, value }) => ( + // use createElement so we can dynamically choose tag based on depth + React.createElement(`h${level}`, { className: "docs-title" }, + , + + + , + value, + ) +); +Heading.displayName = "Docs.Heading"; + +export class HeadingTagRenderer { + public render: TagRenderer = (heading: IHeadingTag, key) => ; +} diff --git a/packages/docs/src/tags/index.ts b/packages/docs/src/tags/index.ts new file mode 100644 index 0000000000..b0700127fb --- /dev/null +++ b/packages/docs/src/tags/index.ts @@ -0,0 +1,29 @@ +/* + * Copyright 2017-present 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 + */ + +import { IPageData, ITag } from "documentalist/dist/client"; + +export interface ITagRendererMap { + [tagName: string]: TagRenderer; +} + +export type TagElement = JSX.Element | undefined; + +export type TagRenderer = ( + tag: ITag, + key: React.Key, + tagRenderers: ITagRendererMap, + page?: IPageData, +) => TagElement; + +export * from "./css"; +export * from "./defaults"; +export * from "./heading"; +export * from "./interface"; +export * from "./page"; +export * from "./reactDocs"; +export * from "./reactExample"; diff --git a/packages/docs/src/tags/interface.tsx b/packages/docs/src/tags/interface.tsx new file mode 100644 index 0000000000..371aa0d414 --- /dev/null +++ b/packages/docs/src/tags/interface.tsx @@ -0,0 +1,26 @@ +/* + * Copyright 2017-present 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 + */ + +import { ITypescriptPluginData } from "documentalist/dist/client"; +import * as React from "react"; +import { PropsStore } from "../common/propsStore"; +import { InterfaceTable } from "../components/interfaceTable"; +import { TagRenderer } from "./"; + +export class InterfaceTagRenderer { + private propsStore: PropsStore; + + constructor(docs: ITypescriptPluginData) { + this.propsStore = new PropsStore(docs.ts); + } + + public render: TagRenderer = ({ value: name }, key, tagRenderers) => { + const iface = this.propsStore.getInterface(name); + const props = this.propsStore.getProps(iface); + return ; + } +} diff --git a/packages/docs/src/tags/page.tsx b/packages/docs/src/tags/page.tsx new file mode 100644 index 0000000000..00ded17517 --- /dev/null +++ b/packages/docs/src/tags/page.tsx @@ -0,0 +1,12 @@ +/* + * Copyright 2017-present 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 + */ + +import { TagRenderer } from "./"; + +export class PageTagRenderer { + public render: TagRenderer = () => undefined; +} diff --git a/packages/docs/src/tags/reactDocs.tsx b/packages/docs/src/tags/reactDocs.tsx new file mode 100644 index 0000000000..959a471630 --- /dev/null +++ b/packages/docs/src/tags/reactDocs.tsx @@ -0,0 +1,34 @@ +/* + * Copyright 2017-present 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 + */ + +import * as React from "react"; +import { TagRenderer } from "./"; + +export interface IDocsMap { + [name: string]: React.ComponentClass<{}>; +}; + +export class ReactDocsTagRenderer { + constructor(private docs: IDocsMap) {} + + /** + * Given the name of a component, like `"ColorSchemes"`, attempts to resolve + * it to an actual component class in the given map, or in the default map which contains + * valid docs components from this package. Provide a custom map to inject your own components. + */ + public render: TagRenderer = ({ value: componentName }, key) => { + if (componentName == null) { + return undefined; + } + + const docsComponent = this.docs[componentName]; + if (docsComponent == null) { + throw new Error(`Unknown @reactDocs component: ${componentName}`); + } + return React.createElement(docsComponent, { key }); + } +} diff --git a/packages/docs/src/tags/reactExample.tsx b/packages/docs/src/tags/reactExample.tsx new file mode 100644 index 0000000000..919a395165 --- /dev/null +++ b/packages/docs/src/tags/reactExample.tsx @@ -0,0 +1,56 @@ +/* + * Copyright 2017-present 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 + */ + +import * as React from "react"; +import { TagRenderer } from "./"; + +export interface IExample { + sourceUrl: string; + render: (props: { id: string }) => JSX.Element | undefined; +} + +// construct a map of package name to all examples defined in that package. +// packageName must match directory name as it is used to generate sourceUrl. +export interface IExampleMap { + [componentName: string]: IExample; +}; + +export interface IExampleProps { + example: IExample; + name: string; +} + +export const ReactExample: React.SFC = (props) => ( +
+ {props.example.render({ id: props.name })} + +  View source on GitHub + +
+); +ReactExample.displayName = "Docs.ReactExample"; + +export class ReactExampleTagRenderer { + constructor(private examples: IExampleMap) {} + + /** + * Given the name of an example component, like `"AlertExample"`, attempts to resolve + * it to an actual example component exported by one of the packages. Also returns + * the URL of the source code on GitHub. + */ + public render: TagRenderer = ({ value: exampleName }, key) => { + if (exampleName == null) { + return undefined; + } + + const example = this.examples[exampleName]; + if (example == null) { + throw new Error(`Unknown @example component: ${exampleName}`); + } + return ; + } +} diff --git a/packages/docs/tsconfig.json b/packages/docs/tsconfig.json index a8f47130c1..9cff66b2d2 100644 --- a/packages/docs/tsconfig.json +++ b/packages/docs/tsconfig.json @@ -1,44 +1,29 @@ { "version": "2.0.0", "compilerOptions": { - "baseUrl": ".", - "declaration": false, + "declaration": true, "experimentalDecorators": true, "importHelpers": true, "jsx": "react", - "lib": [ - "dom", - "es2015.core", - "es2015.collection", - "es2015.generator", - "es2015.iterable", - "es2015.promise", - "es2015.reflect", - "es2015.symbol", - "es5" - ], "module": "commonjs", + "moduleResolution": "node", "noFallthroughCasesInSwitch": true, "noImplicitAny": true, "noImplicitReturns": true, "noUnusedLocals": true, "noUnusedParameters": true, "outDir": "dist/", - "removeComments": true, + "removeComments": false, "sourceMap": false, - "target": "es5", - "paths": { - "@blueprintjs/*": ["node_modules/@blueprintjs/*"] - } + "stripInternal": true, + "target": "es5" }, "include": [ - "typings/tsd.d.ts", "src/**/*" ], "exclude": [ "node_modules", - "build", + "dist", "test" - ], - "compileOnSave": false + ] } diff --git a/packages/table/examples/cellLoadingExample.tsx b/packages/table/examples/cellLoadingExample.tsx index e2d178488a..14382043c3 100644 --- a/packages/table/examples/cellLoadingExample.tsx +++ b/packages/table/examples/cellLoadingExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { RadioGroup } from "@blueprintjs/core"; -import BaseExample, { handleStringChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleStringChange } from "@blueprintjs/docs"; import { Cell, Column, ColumnHeaderCell, RowHeaderCell, Table } from "../src"; diff --git a/packages/table/examples/columnLoadingExample.tsx b/packages/table/examples/columnLoadingExample.tsx index a9373a3afb..7d9a3d4659 100644 --- a/packages/table/examples/columnLoadingExample.tsx +++ b/packages/table/examples/columnLoadingExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Classes } from "@blueprintjs/core"; -import BaseExample, { handleNumberChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleNumberChange } from "@blueprintjs/docs"; import { Cell, Column, ColumnLoadingOption, Table } from "../src"; diff --git a/packages/table/examples/tableDollarExample.tsx b/packages/table/examples/tableDollarExample.tsx index ed3cc742e5..b332a526ed 100644 --- a/packages/table/examples/tableDollarExample.tsx +++ b/packages/table/examples/tableDollarExample.tsx @@ -7,12 +7,12 @@ import * as React from "react"; -import BaseExample from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; import { Cell, Column, Table } from "../src"; export class TableDollarExample extends BaseExample<{}> { - public render() { + public renderExample() { const renderCell = (rowIndex: number) => {`$${(rowIndex * 10).toFixed(2)}`}; return ( diff --git a/packages/table/examples/tableEditableExample.tsx b/packages/table/examples/tableEditableExample.tsx index cf23f1df3e..1482849205 100644 --- a/packages/table/examples/tableEditableExample.tsx +++ b/packages/table/examples/tableEditableExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Intent } from "@blueprintjs/core"; -import BaseExample from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; import { Column, ColumnHeaderCell, EditableCell, EditableName, Table } from "../src"; diff --git a/packages/table/examples/tableFormatsExample.tsx b/packages/table/examples/tableFormatsExample.tsx index b05ba465b4..12ed5501b8 100644 --- a/packages/table/examples/tableFormatsExample.tsx +++ b/packages/table/examples/tableFormatsExample.tsx @@ -7,7 +7,7 @@ import * as React from "react"; -import BaseExample from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; import { Cell, Column, JSONFormat, Table, TruncatedFormat } from "../src"; diff --git a/packages/table/examples/tableLoadingExample.tsx b/packages/table/examples/tableLoadingExample.tsx index 3a68409004..e29b1d0be3 100644 --- a/packages/table/examples/tableLoadingExample.tsx +++ b/packages/table/examples/tableLoadingExample.tsx @@ -8,7 +8,7 @@ import * as React from "react"; import { Switch } from "@blueprintjs/core"; -import BaseExample, { handleBooleanChange } from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample, handleBooleanChange } from "@blueprintjs/docs"; import { Cell, Column, Table, TableLoadingOption } from "../src"; diff --git a/packages/table/examples/tableSortableExample.tsx b/packages/table/examples/tableSortableExample.tsx index 93299467c1..1e039b13a5 100644 --- a/packages/table/examples/tableSortableExample.tsx +++ b/packages/table/examples/tableSortableExample.tsx @@ -10,7 +10,7 @@ import * as React from "react"; import { Menu, MenuItem } from "@blueprintjs/core"; -import BaseExample from "@blueprintjs/core/examples/common/baseExample"; +import { BaseExample } from "@blueprintjs/docs"; import { Cell, diff --git a/packages/table/examples/tsconfig.json b/packages/table/examples/tsconfig.json index 4abd0d0b1e..6e02f3a149 100644 --- a/packages/table/examples/tsconfig.json +++ b/packages/table/examples/tsconfig.json @@ -15,6 +15,9 @@ "removeComments": false, "sourceMap": false, "stripInternal": true, - "target": "es5" + "target": "es5", + "paths": { + "@blueprintjs/docs": ["../../docs/dist/index"] + } } } diff --git a/scripts/docsDist.sh b/scripts/docsDist.sh index cf37135684..9ccc191709 100755 --- a/scripts/docsDist.sh +++ b/scripts/docsDist.sh @@ -3,10 +3,13 @@ # Circle does not handle symlinks in artifacts so we must turn Lerna's symlinked # local deps into actual directories. -find packages/docs/node_modules/@blueprintjs -type l -delete +DOCS_PATH=packages/docs-site/node_modules/@blueprintjs -mkdir -p packages/docs/node_modules/@blueprintjs/core/ -mkdir -p packages/docs/node_modules/@blueprintjs/datetime/ -mkdir -p packages/docs/node_modules/@blueprintjs/table/ +find $DOCS_PATH -type l -delete -cp -fR packages/core packages/datetime packages/table packages/docs/node_modules/@blueprintjs/ +mkdir -p $DOCS_PATH/core/ +mkdir -p $DOCS_PATH/datetime/ +mkdir -p $DOCS_PATH/docs/ +mkdir -p $DOCS_PATH/table/ + +cp -fR packages/core packages/datetime packages/docs packages/table $DOCS_PATH/ diff --git a/scripts/preview.sh b/scripts/preview.sh index 1de430d3d9..62c5cb241a 100755 --- a/scripts/preview.sh +++ b/scripts/preview.sh @@ -5,7 +5,7 @@ source scripts/artifactVariables.sh # Docs echo "Docs preview...RENDER" scripts/docsDist.sh -PREVIEWS="$(artifactLink '/packages/docs/dist/index.html' 'docs')" +PREVIEWS="$(artifactLink '/packages/docs-site/dist/index.html' 'documentation')" COVERAGES="$(coverageLink '/packages/core/' 'core')" COVERAGES="$COVERAGES | $(coverageLink 'packages/datetime/' 'datetime')"