diff --git a/docs/README.md b/docs/README.md index 938e0d2c8de..4b4554629cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,7 +21,7 @@ Otherwise, [RVM](https://rvm.io/) and [rbenv](https://github.com/sstephenson/rbe - [Ruby](http://www.ruby-lang.org/) (version >= 1.8.7) - [RubyGems](http://rubygems.org/) (version >= 1.3.7) - - [Bundler](http://gembundler.com/) + - [Bundler](http://bundler.io/) The version of the Pygment syntax highlighter used by Jekyll requires Python 2.7.x (not 3.x). macOS comes pre-installed with Python 2.7, but you may need to install it on other OSs. diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index 0e00373acc3..548ca95fd06 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -32,6 +32,8 @@ title: JSX In Depth - id: typechecking-with-proptypes title: Typechecking With PropTypes + - id: static-type-checking + title: Static Type Checking - id: refs-and-the-dom title: Refs and the DOM - id: uncontrolled-components diff --git a/docs/docs/accessibility.md b/docs/docs/accessibility.md index 2b57aa24988..6ad7877d9e3 100644 --- a/docs/docs/accessibility.md +++ b/docs/docs/accessibility.md @@ -2,6 +2,7 @@ id: accessibility title: Accessibility permalink: docs/accessibility.html +prev: integrating-with-other-libraries.html redirect_from: - "docs/index.html" --- @@ -32,7 +33,7 @@ Note that all `aria-*` HTML attributes are fully supported in JSX. Whereas most ```javascript{3,4} Note: @@ -141,7 +142,7 @@ initially triggered the modal. A more complex user experience should not mean a less accessible one. Whereas accessibility is most easily achieved by coding as close to HTML as possible, even the most complex widget can be coded accessibly. -Here we require knowledge of [ARIA Roles](https://www.w3.org/TR/wai-aria/roles) as well as [ARIA States and Properties](https://www.w3.org/TR/wai-aria/states_and_properties). +Here we require knowledge of [ARIA Roles](https://www.w3.org/TR/wai-aria/roles) as well as [ARIA States and Properties](https://www.w3.org/TR/wai-aria/states_and_properties). These are toolboxes filled with HTML attributes that are fully supported in JSX and enable us to construct fully accessible, highly functional React components. Each type of widget has a specific design pattern and is expected to function in a certain way by users and user agents alike: @@ -194,11 +195,11 @@ By far the easiest and also one of the most important checks is to test if your 1. Plugging out your mouse. 1. Using `Tab` and `Shift+Tab` to browse. 1. Using `Enter` to activate elements. -1. Where required, using your keyboard arrow keys to interact with some elements, such as menus and dropdowns. +1. Where required, using your keyboard arrow keys to interact with some elements, such as menus and dropdowns. ### Development assistance -We can check some accessibility features directly in our JSX code. Often intellisense checks are already provided in JSX aware IDE's for the ARIA roles, states and properties. We also +We can check some accessibility features directly in our JSX code. Often intellisense checks are already provided in JSX aware IDE's for the ARIA roles, states and properties. We also have access to the following tool: #### eslint-plugin-jsx-a11y @@ -206,9 +207,9 @@ have access to the following tool: The [eslint-plugin-jsx-a11y](https://github.com/evcohen/eslint-plugin-jsx-a11y) plugin for ESLint provides AST linting feedback regarding accessibility issues in your JSX. Many IDE's allow you to integrate these findings directly into code analysis and source code windows. -[Create React App](https://github.com/facebookincubator/create-react-app) has this plugin with a subset of rules activated. If you want to enable even more accessibility rules, +[Create React App](https://github.com/facebookincubator/create-react-app) has this plugin with a subset of rules activated. If you want to enable even more accessibility rules, you can create an `.eslintrc` file in the root of your project with this content: - + ```json { "extends": ["react-app", "plugin:jsx-a11y/recommended"], @@ -235,7 +236,7 @@ The [Web Accessibility Evaluation Tool](http://wave.webaim.org/extension/) is an #### Accessibility inspectors and the Accessibility Tree -[The Accessibility Tree](https://www.paciellogroup.com/blog/2015/01/the-browser-accessibility-tree/) is a subset of the DOM tree that contains accessible objects for every DOM element that should be exposed +[The Accessibility Tree](https://www.paciellogroup.com/blog/2015/01/the-browser-accessibility-tree/) is a subset of the DOM tree that contains accessible objects for every DOM element that should be exposed to assistive technology, such as screen readers. In some browsers we can easily view the accessibility information for each element in the accessibility tree: @@ -260,7 +261,7 @@ Refer to the following guides on how to best use NVDA: #### VoiceOver in Safari -VoiceOver is an integrated screen reader on Apple devices. +VoiceOver is an integrated screen reader on Apple devices. Refer to the following guides on how activate and use VoiceOver: @@ -270,7 +271,7 @@ Refer to the following guides on how activate and use VoiceOver: #### JAWS in Internet Explorer -[Job Access With Speech](http://www.freedomscientific.com/Products/Blindness/JAWS) or JAWS, is a prolifically used screen reader on Windows. +[Job Access With Speech](http://www.freedomscientific.com/Products/Blindness/JAWS) or JAWS, is a prolifically used screen reader on Windows. Refer to the following guides on how to best use JAWS: diff --git a/docs/docs/context.md b/docs/docs/context.md index ed75177ad3d..81966836ac8 100644 --- a/docs/docs/context.md +++ b/docs/docs/context.md @@ -2,6 +2,8 @@ id: context title: Context permalink: docs/context.html +prev: reconciliation.html +next: web-components.html --- > Note: diff --git a/docs/docs/higher-order-components.md b/docs/docs/higher-order-components.md index b5386dd83fd..21b7b09a07b 100644 --- a/docs/docs/higher-order-components.md +++ b/docs/docs/higher-order-components.md @@ -2,6 +2,8 @@ id: higher-order-components title: Higher-Order Components permalink: docs/higher-order-components.html +prev: web-components.html +next: integrating-with-other-libraries.html --- A higher-order component (HOC) is an advanced technique in React for reusing component logic. HOCs are not part of the React API, per se. They are a pattern that emerges from React's compositional nature. diff --git a/docs/docs/integrating-with-other-libraries.md b/docs/docs/integrating-with-other-libraries.md index 85704ab53b1..4b69cdf298a 100644 --- a/docs/docs/integrating-with-other-libraries.md +++ b/docs/docs/integrating-with-other-libraries.md @@ -2,6 +2,8 @@ id: integrating-with-other-libraries title: Integrating with Other Libraries permalink: docs/integrating-with-other-libraries.html +prev: higher-order-components.html +next: accessibility.html --- React can be used in any web application. It can be embedded in other applications and, with a little care, other applications can be embedded in React. This guide will examine some of the more common use cases, focusing on integration with [jQuery](https://jquery.com/) and [Backbone](http://backbonejs.org/), but the same ideas can be applied to integrating components with any existing code. @@ -158,7 +160,7 @@ class Chosen extends React.Component { this.handleChange = this.handleChange.bind(this); this.$el.on('change', this.handleChange); } - + componentDidUpdate(prevProps) { if (prevProps.children !== this.props.children) { this.$el.trigger("chosen:updated"); @@ -169,7 +171,7 @@ class Chosen extends React.Component { this.$el.off('change', this.handleChange); this.$el.chosen('destroy'); } - + handleChange(e) { this.props.onChange(e.target.value); } diff --git a/docs/docs/jsx-in-depth.md b/docs/docs/jsx-in-depth.md index 282c199d557..89bf4299372 100644 --- a/docs/docs/jsx-in-depth.md +++ b/docs/docs/jsx-in-depth.md @@ -2,6 +2,7 @@ id: jsx-in-depth title: JSX In Depth permalink: docs/jsx-in-depth.html +next: typechecking-with-proptypes.html redirect_from: - "docs/jsx-spread.html" - "docs/jsx-gotchas.html" diff --git a/docs/docs/optimizing-performance.md b/docs/docs/optimizing-performance.md index 29b1186be9b..ab42059472f 100644 --- a/docs/docs/optimizing-performance.md +++ b/docs/docs/optimizing-performance.md @@ -3,6 +3,8 @@ id: optimizing-performance title: Optimizing Performance permalink: docs/optimizing-performance.html redirect_from: "docs/advanced-performance.html" +prev: uncontrolled-components.html +next: react-without-es6.html --- Internally, React uses several clever techniques to minimize the number of costly DOM operations required to update the UI. For many applications, using React will lead to a fast user interface without doing much work to specifically optimize for performance. Nevertheless, there are several ways you can speed up your React application. @@ -74,10 +76,10 @@ For the most efficient Browserify production build, install a few plugins: ``` # If you use npm -npm install --save-dev bundle-collapser envify uglify-js uglifyify +npm install --save-dev bundle-collapser envify uglify-js uglifyify # If you use Yarn -yarn add --dev bundle-collapser envify uglify-js uglifyify +yarn add --dev bundle-collapser envify uglify-js uglifyify ``` To create a production build, make sure that you add these transforms **(the order matters)**: @@ -110,10 +112,10 @@ For the most efficient Rollup production build, install a few plugins: ``` # If you use npm -npm install --save-dev rollup-plugin-commonjs rollup-plugin-replace rollup-plugin-uglify +npm install --save-dev rollup-plugin-commonjs rollup-plugin-replace rollup-plugin-uglify # If you use Yarn -yarn add --dev rollup-plugin-commonjs rollup-plugin-replace rollup-plugin-uglify +yarn add --dev rollup-plugin-commonjs rollup-plugin-replace rollup-plugin-uglify ``` To create a production build, make sure that you add these plugins **(the order matters)**: diff --git a/docs/docs/react-without-es6.md b/docs/docs/react-without-es6.md index e49a5e07570..7bfd49cf34b 100644 --- a/docs/docs/react-without-es6.md +++ b/docs/docs/react-without-es6.md @@ -2,6 +2,8 @@ id: react-without-es6 title: React Without ES6 permalink: docs/react-without-es6.html +prev: optimizing-performance.html +next: react-without-jsx.html --- Normally you would define a React component as a plain JavaScript class: diff --git a/docs/docs/react-without-jsx.md b/docs/docs/react-without-jsx.md index e1439009504..6ee8074f7c3 100644 --- a/docs/docs/react-without-jsx.md +++ b/docs/docs/react-without-jsx.md @@ -2,6 +2,8 @@ id: react-without-jsx title: React Without JSX permalink: docs/react-without-jsx.html +prev: react-without-es6.html +next: reconciliation.html --- JSX is not a requirement for using React. Using React without JSX is especially convenient when you don't want to set up compilation in your build environment. @@ -56,4 +58,3 @@ ReactDOM.render( If you use this shorthand form for `React.createElement`, it can be almost as convenient to use React without JSX. Alternatively, you can refer to community projects such as [`react-hyperscript`](https://github.com/mlmorg/react-hyperscript) and [`hyperscript-helpers`](https://github.com/ohanhi/hyperscript-helpers) which offer a terser syntax. - diff --git a/docs/docs/reconciliation.md b/docs/docs/reconciliation.md index 19178069b53..3e031c5a790 100644 --- a/docs/docs/reconciliation.md +++ b/docs/docs/reconciliation.md @@ -2,6 +2,8 @@ id: reconciliation title: Reconciliation permalink: docs/reconciliation.html +prev: react-without-jsx.html +next: context.html --- React provides a declarative API so that you don't have to worry about exactly what changes on every update. This makes writing applications a lot easier, but it might not be obvious how this is implemented within React. This article explains the choices we made in React's "diffing" algorithm so that component updates are predictable while being fast enough for high-performance apps. diff --git a/docs/docs/refs-and-the-dom.md b/docs/docs/refs-and-the-dom.md index d14a94bf812..59e679122f2 100644 --- a/docs/docs/refs-and-the-dom.md +++ b/docs/docs/refs-and-the-dom.md @@ -1,6 +1,9 @@ --- id: refs-and-the-dom title: Refs and the DOM +permalink: docs/refs-and-the-dom.html +prev: static-type-checking.html +next: uncontrolled-components.html redirect_from: - "docs/working-with-the-browser.html" - "docs/more-about-refs.html" @@ -8,7 +11,6 @@ redirect_from: - "docs/more-about-refs-zh-CN.html" - "tips/expose-component-functions.html" - "tips/children-undefined.html" -permalink: docs/refs-and-the-dom.html --- In the typical React dataflow, [props](/react/docs/components-and-props.html) are the only way that parent components interact with their children. To modify a child, you re-render it with new props. However, there are a few cases where you need to imperatively modify a child outside of the typical dataflow. The child to be modified could be an instance of a React component, or it could be a DOM element. For both of these cases, React provides an escape hatch. @@ -68,7 +70,7 @@ class CustomTextInput extends React.Component { React will call the `ref` callback with the DOM element when the component mounts, and call it with `null` when it unmounts. -Using the `ref` callback just to set a property on the class is a common pattern for accessing DOM elements. The preferred way is to set the property in the `ref` callback like in the above example. There is even a shorter way to write it: `ref={input => this.textInput = input}`. +Using the `ref` callback just to set a property on the class is a common pattern for accessing DOM elements. The preferred way is to set the property in the `ref` callback like in the above example. There is even a shorter way to write it: `ref={input => this.textInput = input}`. ### Adding a Ref to a Class Component diff --git a/docs/docs/static-type-checking.md b/docs/docs/static-type-checking.md new file mode 100644 index 00000000000..f79e893b8a6 --- /dev/null +++ b/docs/docs/static-type-checking.md @@ -0,0 +1,180 @@ +--- +id: static-type-checking +title: Static Type Checking +permalink: docs/static-type-checking.html +prev: typechecking-with-proptypes.html +next: refs-and-the-dom.html +--- + +When your project codebase growths and became more complicated you can decide that you need more flexibly approach for typechecking than used in PropTypes, or, if you didn't use PropTypes, to add typechecking from scratch with tools throws errors within JavaScript precompilation for more effectively development process. + +### Why to use these libraries instead of PropTypes? + +Although PropTypes can be useful for typechecking of the props being passed to a component, Flow and Typescript can provide additional tools like interfaces, fixed-length typed arrays, typed objects and primitive variables, annotations, etc. With these advantages taken from typed compiling languages like C and Java this libraries can be more powerful for developing complicated applications. + +## Flow + +When Typescript is above the standarts of ESMAScript, Flow allows you to use typing within code comments using usual JavaScript: + +```js +// @flow + +/*:: +type MyTypes = { + foo: string +}; +*/ + +function bar(value /*: MyTypes */) /*: string */ { + return value.foo.length; +} + +bar({ foo: 'Hello, world!' }); +``` + +>**Note:** +> +>Although you can use Flow as in example above, you still be able to use Flow without comment-based syntax. + +For try Flow use this [playground](https://flow.org/try/). + +### With Babel + +To add Flow in your project, you can install `babel-preset-flow` (you should have [babel](http://babeljs.io/docs/setup/) installed): + +```bash +yarn add --dev babel-preset-flow +# or +npm install --save-dev babel-preset-flow +``` + +Then add flow into your Babel config: + +``` +{ + "presets": ["flow"] +} +``` + +### With built-in boilerplates + +You can use Flow out of the box with [create-react-app](https://flow.org/en/docs/tools/create-react-app/). + +## Typescript + +Some Typescript features: + +- [Namespaces](https://www.typescriptlang.org/docs/handbook/namespaces.html) +- Mapped Types + +For fast dive into Typescript, go [here](https://www.typescriptlang.org/play/). + +If you want to use Typescript in your React project, you can try [typescript-react-starter](https://github.com/Microsoft/TypeScript-React-Starter#typescript-react-starter). + +## Migration from PropTypes + +>**Note:** +> +>In the example below, prototype-based style rewritten using [ES7 property initializers](https://esdiscuss.org/topic/es7-property-initializers). + +```js{17-26} +class Button extends React.Component { + handleClick() { + const checkCondition = this.props.checkCondition(); + if (checkCondition) this.props.doSomething(); + } + + render() { + return ( + + ); + } +} + +Button.propTypes = { + caption: PropTypes.string.isRequired; + iconClass: PropTypes.string; + checkCondition: PropTypes.func.isRequired; + doSomething: PropTypes.func.isRequired; +}; + +Button.defaultProps = { + iconClass: 'custom' +}; +``` + +### To Flow + +```js{1-9,12-16} +// @flow + +type Props = { + caption: string, + iconClass?: string, + checkCondition: () => boolean, + doSomething: () => void, + children?: React.Node +}; + +class Button extends React.Component { + static defaultProps: { + iconClass: 'custom' + }; + + static props: Props; + + handleClick() { + const checkCondition = this.props.checkCondition(); + if (checkCondition) this.props.doSomething(); + } + + render() { + return ( + + ); + } +} +``` + +### To TypeScript + +```ts{1-7,9-18} +// Extend React.Props to handle this.props.children and other stuff +interface Props extends React.Props + ); + } +} +``` + +## Do not complicate things + +If you want more flexible typechecking for your project, you can use libraries like Flow or Typescript. But if you don't planned to build complex large application, for example if you want to build simple website or application on React, perhaps you should just use PropTypes package instead. Сome up to choice of development tools carefully. diff --git a/docs/docs/typechecking-with-proptypes.md b/docs/docs/typechecking-with-proptypes.md index 2ff09339100..feb2eb0ab1c 100644 --- a/docs/docs/typechecking-with-proptypes.md +++ b/docs/docs/typechecking-with-proptypes.md @@ -2,6 +2,8 @@ id: typechecking-with-proptypes title: Typechecking With PropTypes permalink: docs/typechecking-with-proptypes.html +prev: jsx-in-depth.html +next: static-type-checking.html redirect_from: - "docs/react-api.html#typechecking-with-proptypes" --- diff --git a/docs/docs/uncontrolled-components.md b/docs/docs/uncontrolled-components.md index d9fa20ac80a..b701c0a7dd3 100644 --- a/docs/docs/uncontrolled-components.md +++ b/docs/docs/uncontrolled-components.md @@ -2,6 +2,8 @@ id: uncontrolled-components title: Uncontrolled Components permalink: docs/uncontrolled-components.html +prev: refs-and-the-dom.html +next: optimizing-performance.html --- In most cases, we recommend using [controlled components](/react/docs/forms.html) to implement forms. In a controlled component, form data is handled by a React component. The alternative is uncontrolled components, where form data is handled by the DOM itself. diff --git a/docs/docs/web-components.md b/docs/docs/web-components.md index 1012ea795b6..661bb582e60 100644 --- a/docs/docs/web-components.md +++ b/docs/docs/web-components.md @@ -2,6 +2,8 @@ id: web-components title: Web Components permalink: docs/web-components.html +prev: context.html +next: higher-order-components.html redirect_from: "docs/webcomponents.html" ---