Skip to content

Commit

Permalink
[DM] squash some pages (#883)
Browse files Browse the repository at this point in the history 
* merge the slider pages by omitting JavaScript API
a daring play by ggray just lists the two components and takes advantage of documentalist's support for multiple tags per section!

* move components usage instructions to styleguide
they relate to all the packages so belong in a shared location, not inside Core Components.
now the Core package is completely empty...

* remove redundant UI icons heading in Icons as it was the only subheading.
also refine the example a bit, using some handlebars!
  • Loading branch information
@giladgray
giladgray authored Mar 28, 2017
1 parent 365c520 commit f98300e
Show file tree
Hide file tree
Showing 5 changed files with 209 additions and 227 deletions.
170 changes: 1 addition & 169 deletions packages/core/src/components/components.md
View file
Original file line number Diff line number Diff line change
@@ -1,173 +1,5 @@
@# Components

Blueprint's JavaScript components are stable and their APIs adhere to
[semantic versioning](http://semver.org/).
They are distributed in the __@blueprintjs/core__ package and can be consumed as CommonJS modules
[via NPM](https://www.npmjs.com/package/@blueprintjs/core).

@## Usage

@### NPM installation

1. Install the core package with an NPM client like `npm` or `yarn`, pulling in all relevant
dependencies:

```sh
npm install --save @blueprintjs/core
```

1. If you see `UNMET PEER DEPENDENCY` errors, you should manually install React:

```sh
npm install --save react react-dom react-addons-css-transition-group
```

1. After installation, you'll be able to import the React components in your application:

```tsx
// extract specific components
import { Intent, Spinner, DatePickerFactory } from "@blueprintjs/core";
// or just take everything!
import * as Blueprint from "@blueprintjs/core";

// using JSX:
const mySpinner = <Spinner intent={Intent.PRIMARY} />;

// using the namespace import:
const anotherSpinner = <Blueprint.Spinner intent={Blueprint.Intent.PRIMARY}/>;

// use factories for React.createElement shorthand if you're not using JSX.
// every component provides a corresponding <Name>Factory.
const myDatePicker = DatePickerFactory();
```

1. Don't forget to include the main CSS file from each Blueprint package! Additionally, the
`resources/` directory contains supporting media such as fonts and images.

```html
<!-- in plain old reliable HTML -->
<!DOCTYPE HTML>
<html>
<head>
...
<!-- include dependencies manually -->
<link href="path/to/node_modules/normalize.css/normalize.css" rel="stylesheet" />
<link href="path/to/node_modules/@blueprintjs/core/dist/blueprint.css" rel="stylesheet" />
...
</head>
...
</html>
```

```css.scss
// or, using node-style package resolution in a CSS file:
// (dependencies' stylesheets should be resolved automatically)
@import "~@blueprintjs/core";
```

@### CDN consumption

Blueprint supports the venerable [unpkg CDN](https://unpkg.com). Each package provides a UMD
`dist/[name].bundle.js` file containing the bundled source code. The UMD wrapper exposes each
library on the `Blueprint` global variable: `Blueprint.Core`, `Blueprint.Datetime`, etc.

These bundles _do not include_ external dependencies; your application will need to ensure that
`normalize.css`, `React`, `classnames`, and `Tether` are available at runtime.

```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>Blueprint Starter Kit</title>
<link href="https://unpkg.com/normalize.css@^4.1.1" rel="stylesheet" />
<link href="https://unpkg.com/@blueprintjs/core@^1.11.0/dist/blueprint.css" rel="stylesheet" />
</head>
<body>
<script src="https://unpkg.com/classnames@^2.2"></script>
<script src="https://unpkg.com/tether@^1.4"></script>
<script src="https://unpkg.com/react@^15.3.1/dist/react-with-addons.min.js"></script>
<script src="https://unpkg.com/react-dom@^15.3.1/dist/react-dom.min.js"></script>
<script src="https://unpkg.com/@blueprintjs/core@^1.11.0"></script>

<div id="btn"></div>
<script>
const button = React.createElement( Blueprint.Core.Button, {
iconName: "predictive-analysis",
text: "CDN Blueprint is go!",
});
ReactDOM.render(button, document.querySelector("#btn"));
</script>
</body>
</html>
```

@### DOM4

Blueprint relies on a handful of DOM Level 4 API methods: `el.query`, `el.queryAll`, and
`el.closest()`. `@blueprintjs/core` depends on a [polyfill library called `dom4`][dom4] to ensure
these methods are available. This module is conditionally loaded if Blueprint is used in a browser
environment.

[dom4]: https://webreflection.github.io/dom4/

@### TypeScript

Blueprint is written in TypeScript and therefore its own `.d.ts` type definitions are distributed in
the NPM package and should be resolved automatically by the compiler. However, you'll need to
install typings for Blueprint's dependencies before you can consume it:

```sh
# required for all @blueprintjs packages:
npm install --save @types/pure-render-decorator @types/react @types/react-dom @types/react-addons-css-transition-group

# @blueprintjs/datetime requires:
npm install --save @types/moment

# @blueprintjs/table requires:
npm install --save @types/es6-shim
```

<div class="pt-callout pt-intent-primary pt-icon-info-sign">
For more information, see the TypeScript Handbook for
[guidance on consuming declaration files][handbook].
</div>

[handbook]: https://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html

@### Vanilla JS APIs

JS components are built using React, but that does not limit their usage to just React applications.
You can render any component in any JavaScript application with `ReactDOM.render`. Think of it like
using a jQuery plugin.

```tsx
const myContainerElement = document.querySelector(".my-container");

// with JSX
ReactDOM.render(
<Spinner className="pt-intent-primary pt-small" />,
myContainerElement
);

// with vanilla JS, use the factory
ReactDOM.render(
SpinnerFactory({
className: "pt-intent-primary pt-small"
}),
myContainerElement
);
```

To remove the component from the DOM and clean up, unmount it:

```tsx
ReactDOM.unmountComponentAtNode(myContainerElement);
```

Check out the [React API docs](https://facebook.github.io/react/docs/react-api.html) for more details.

<!-- Exact ordering of components in the navbar: -->

@page alert
Expand All @@ -190,7 +22,7 @@ Check out the [React API docs](https://facebook.github.io/react/docs/react-api.h
@page popover
@page portal
@page progress
@page slider
@page sliders
@page table
@page tabs
@page tabs2
Expand Down
18 changes: 0 additions & 18 deletions packages/core/src/components/slider/range-slider.md
View file

This file was deleted.

20 changes: 14 additions & 6 deletions ...ages/core/src/components/slider/slider.md → ...ges/core/src/components/slider/sliders.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,23 @@ Use `Slider` for choosing a single value and `RangeSlider` for choosing two valu

@reactExample SliderExample

@### JavaScript API

The `Slider` component is available in the __@blueprintjs/core__ package.
Make sure to review the [general usage docs for JS components](#components.usage).

`Slider` is a controlled component, so the `value` prop determines its current appearance. Provide
an `onChange` handler to receive updates and an `onRelease` handler to determine when the user has
stopped interacting with the slider.

@interface ISliderProps

@page range-slider
@## Range slider

@reactExample RangeSliderExample

`RangeSlider` allows the user to choose a range between upper and lower bounds. The component
functions identically to `Slider` except that the user can select both ends of the range. It exposes
its selected value as `[number, number]`: a two-element array with minimum and maximum range bounds.

`RangeSlider` is a controlled component, so the `value` prop determines its current appearance.
Provide an `onChange` handler to receive updates and an `onRelease` handler to determine when the
user has stopped interacting with the slider.

@interface IRangeSliderProps

24 changes: 14 additions & 10 deletions packages/core/src/docs/icons.md
View file
Original file line number Diff line number Diff line change
@@ -1,24 +1,28 @@
@# Icons

@## UI icons

Blueprint UI icons are implemented via an icon font. They can be used anywhere text is
used. It's easy to change their color or apply effects like text shadows via standard CSS
properties.
Blueprint provides over 300 UI icons in an icon font. They come in two sizes, 16px and 20px, and can
be used anywhere text is used. It's easy to change their color or apply effects like text shadows
via standard CSS properties.

To use Blueprint UI icons, you need to apply two classes to a `<span>` element:
- a __sizing class__, either `pt-icon-standard` (16px) or `pt-icon-large` (20px)
- an icon __identifier class__, such as `pt-icon-projects`
- an __icon name class__, such as `pt-icon-projects`

```html
<span class="pt-icon-{{size}} pt-icon-{{name}}"></span>

<span class="pt-icon-standard pt-icon-projects"></span>
<span class="pt-icon-large pt-icon-geosearch"></span>
```

Many Blueprint [components](#core/components) provide an `iconName` prop, which supports both the
full name `pt-icon-projects` and the short name `projects`.

<div class="pt-callout pt-intent-primary pt-icon-info-sign">
<h5>Non-standard sizes</h5>
Generally, icons should only be used at either 16px or 20px. However if a non-standard size is
necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class.
You can instead use the class `pt-icon` to make the icon inherit its size from surrounding text.
<h5>Non-standard sizes</h5>
Generally, icons should only be used at either 16px or 20px. However if a non-standard size is
necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class.
You can instead use the class `pt-icon` to make the icon inherit its size from surrounding text.
</div>

@reactDocs Icons
Loading

0 comments on commit f98300e

Please sign in to comment.