From 8d3ee81668385ee48a9002b3eb12f629c2b81b7f Mon Sep 17 00:00:00 2001 From: mthuret Date: Mon, 7 Nov 2016 16:01:44 +0100 Subject: [PATCH] docs: fix some typos and bugs - markdown is taken into account inside props #1517 - highlighting added for guide section --- docgen/layouts/HOC/connector.pug | 4 ++-- docgen/layouts/component/core.pug | 6 +++--- docgen/layouts/component/widget.pug | 8 ++++---- docgen/src/guides/3rd-party-librairies.md | 4 ++-- docgen/src/guides/advanced-topics.md | 16 ++++++++++++---- docgen/src/guides/conditional-display.md | 6 +++--- docgen/src/guides/connectors.md | 4 ++-- docgen/src/guides/create-own-widget.md | 6 +++--- docgen/src/guides/internationalization.md | 2 +- docgen/src/guides/styling.md | 2 +- .../src/core/InstantSearch.js | 8 ++------ 11 files changed, 35 insertions(+), 31 deletions(-) diff --git a/docgen/layouts/HOC/connector.pug b/docgen/layouts/HOC/connector.pug index 639d60c51b8..b8338166d14 100644 --- a/docgen/layouts/HOC/connector.pug +++ b/docgen/layouts/HOC/connector.pug @@ -28,7 +28,7 @@ block content span default value: code=type.defaultValue tr.api-entry-description - td(colspan=3)=type.description + td(colspan=3)!=h.markdown(type.description) else p This connector does not expose external props. h2#provided-props Provided props @@ -49,6 +49,6 @@ block content span default value: code=type.defaultValue tr.api-entry-description - td(colspan=3)=type.description + td(colspan=3)!=h.markdown(type.description) else p This connector does not provided props to its wrapped Component. diff --git a/docgen/layouts/component/core.pug b/docgen/layouts/component/core.pug index 59e7779a780..f4ae326ba61 100644 --- a/docgen/layouts/component/core.pug +++ b/docgen/layouts/component/core.pug @@ -13,7 +13,7 @@ block content h2#proptypes Props a.anchor(href='#proptypes') if proptype - p List of props exposed by + p List of props exposed by code=name table.api.proptypes tbody @@ -26,10 +26,10 @@ block content code=type.type td.api-entry-default-value if type.defaultValue - span default value: + span default value: code=type.defaultValue tr.api-entry-description - td(colspan=3)=type.description + td(colspan=3)!=h.markdown(type.description) else p This component does not accept props. h2#example Example diff --git a/docgen/layouts/component/widget.pug b/docgen/layouts/component/widget.pug index 15a16cdbdda..cabe141e296 100644 --- a/docgen/layouts/component/widget.pug +++ b/docgen/layouts/component/widget.pug @@ -13,9 +13,9 @@ block content h2#proptypes Props a.anchor(href='#proptypes') if proptype - p List of props exposed by the + p List of props exposed by the code=name - | widget + | widget table.api.proptypes tbody each type in proptype @@ -27,10 +27,10 @@ block content code=type.type td.api-entry-default-value if type.defaultValue - span default value: + span default value: code=type.defaultValue tr.api-entry-description - td(colspan=3)=type.description + td(colspan=3)!=h.markdown(type.description) else p This widget does not accept props. h2#theme Classnames diff --git a/docgen/src/guides/3rd-party-librairies.md b/docgen/src/guides/3rd-party-librairies.md index 4b73ade57bc..e615f548634 100644 --- a/docgen/src/guides/3rd-party-librairies.md +++ b/docgen/src/guides/3rd-party-librairies.md @@ -14,7 +14,7 @@ Check out the [connectors guide](connectors.html) to learn how to use them. Let's take an example building a SearchBox using Material UI: -```js +```javascript import {connectSearchBox} from 'react-instantsearch/connectors'; import {TextField} from 'material-ui'; @@ -31,7 +31,7 @@ const ConnectedSearchBox = connectSearchBox(MaterialUiSearchBox); Then, you will be able to use your `ConnectedSearchBox` inside the `InstantSearch` component: -```js +```javascript { return null; }); @@ -29,7 +29,7 @@ To do that, you can use the appropriate connector and manually add your values. Here's an example to force category values for a Menu. -``` +```javascript const ConnectedMenu = connectMenu(props => { const items = [];` @@ -53,13 +53,13 @@ const ConnectedMenu = connectMenu(props => { The InstantSearch component features a complete URL synchronization solution. Whenever a widget's state changes, the URL will be updated to reflect the new state of the search UI. This has two main benefits: * the user can use the browser's back and forward buttons to navigate back and forth between the different states of the search. -* the user can bookmark, copy and share a custom search URL.` +* the user can bookmark, copy and share a custom search URL. To activate this feature, you need to pass the `urlSync` props when instantiating the InstantSearch component. Here's an example -``` +```javascript ``` + +**Location Debouncing** + +Since UI updates can happen in quick succession, for instance when the user types in a query, +the new locations are debounced. The treshold prop controls how long the component should wait between +state changes before pushing a new location instead of replacing the old one. + + diff --git a/docgen/src/guides/conditional-display.md b/docgen/src/guides/conditional-display.md index c97c1bbda8c..24ae043bbfc 100644 --- a/docgen/src/guides/conditional-display.md +++ b/docgen/src/guides/conditional-display.md @@ -19,7 +19,7 @@ then access the `state` of all widgets. By doing so you're able to get the query Here's an example: -```js +```javascript const Content = createConnector({ displayName: 'ConditionalQuery', getProps(props, state) { @@ -41,7 +41,7 @@ returned and decide what to do according to this number. Here's an example: -```js +```javascript const content = createConnector({ displayName: 'ConditionalResults', getProps(props, state, search) { @@ -64,7 +64,7 @@ decide what to do with it. Here's an example: -```js +```javascript const content = createConnector({ displayName: 'ConditionalError', getProps(props, state, search) { diff --git a/docgen/src/guides/connectors.md b/docgen/src/guides/connectors.md index b7b2fd2e967..b3c417bfb8b 100644 --- a/docgen/src/guides/connectors.md +++ b/docgen/src/guides/connectors.md @@ -24,7 +24,7 @@ All default widgets have a corresponding higher-order component that acts as a c For instance, if you want to create your own search box, you will need to use the `connectSearchBox` connector: -```js +```javascript import {connectSearchBox} from 'react-instantsearch/connectors'; const MySearchBox = props => @@ -50,7 +50,7 @@ When a widget is stateful, its state will get serialized and persisted to the UR Stateful widgets are also provided with `refine` and `createURL` methods. The `refine(nextState)` method allows the widget to edit its state, while the `createURL(nextState)` method allows the widget to generate a URL for the corresponding state. -```js +```javascript // Here's a variation on the usage of `connectSearchBox`: a component that just // renders a link to set the current query to "cute cats". // By adding an `onClick` handler on top of the `href`, and cancelling the diff --git a/docgen/src/guides/create-own-widget.md b/docgen/src/guides/create-own-widget.md index 6f0204322dd..031d674ee7a 100644 --- a/docgen/src/guides/create-own-widget.md +++ b/docgen/src/guides/create-own-widget.md @@ -31,7 +31,7 @@ This method defines exactly how the `refine` prop of connected widgets affects t It takes in the current props of the higher-order component, the state of all widgets, as well as all arguments passed to the `refine` and `createURL` props of stateful widgets, and returns a new state. -```js +```javascript const CoolWidget = createConnector({ displayName: 'CoolWidget', @@ -93,7 +93,7 @@ Every time the props or state of a widget change, all the `getSearchParameters` As such, the `getSearchParameters` method allows you to describe how the state and props of a widget should affect the search parameters. -```js +```javascript const CoolWidget = createConnector({ // displayName, getProps, refine @@ -121,7 +121,7 @@ The metadata object also allows you to declare any data that you would like to p The `CurrentRefinements` widget leverages this mechanism in order to allow any widget to declare the filters it has applied. If you want to add your own filter, declare a `filters` property on your widget's metadata object: -```js +```javascript const CoolWidget = createConnector({ // displayName, getProps, refine, getSearchParameters diff --git a/docgen/src/guides/internationalization.md b/docgen/src/guides/internationalization.md index 8beceb78b84..f36ff89e4a2 100644 --- a/docgen/src/guides/internationalization.md +++ b/docgen/src/guides/internationalization.md @@ -9,7 +9,7 @@ All widgets rendering text that is not otherwise configurable via props accept a ### Example: Translating a Pagination -``` +```javascript import {Pagination} from 'react-instantsearch/dom'; function TranslatedPagination(props) { diff --git a/docgen/src/guides/styling.md b/docgen/src/guides/styling.md index 353203c4b4d..66705f7ab38 100644 --- a/docgen/src/guides/styling.md +++ b/docgen/src/guides/styling.md @@ -50,7 +50,7 @@ When building `react-instantsearch` we are using [babel-plugin-transform-inline- If you want you can also use it with your own code and load the css with [`insert-css`](https://github.com/substack/insert-css). -```js +```javascript import theme from './theme.css' insertCss(theme.code); diff --git a/packages/react-instantsearch/src/core/InstantSearch.js b/packages/react-instantsearch/src/core/InstantSearch.js index 061fe752c9a..a1a2f4c4592 100644 --- a/packages/react-instantsearch/src/core/InstantSearch.js +++ b/packages/react-instantsearch/src/core/InstantSearch.js @@ -61,12 +61,8 @@ function validateNextProps(props, nextProps) { * It will be overriden by the search parameters resolved via the widgets. Typical use case: * setting the distinct setting is done by providing an object like: `{distinct: 1}`. For more information * about the kind of object that can be provided on the [official API documentation](https://www.algolia.com/doc/rest-api/search#full-text-search-parameters). - * @propType {bool=false} urlSync - Enables automatic synchronization of widgets state to the URL. See [URL Synchronization](#url-synchronization). - * @propType {object} history - A custom [history](https://github.com/ReactTraining/history) to push location to. Useful for quick integration with [React Router](https://github.com/reactjs/react-router). Takes precedence over urlSync. See [Custom History](#custom-history). - * @propType {number=700} threshold - Threshold in milliseconds above which new locations will be pushed to the history, instead of replacing the previous one. See [Location Debouncing](#location-debouncing). - * @propType {func} onStateChange - See [Controlled State](#controlled-state). - * @propType {object} state - See [Controlled State](#controlled-state). - * @propType {func} createURL - See [Controlled State](#controlled-state). + * @propType {bool=false} urlSync - Enables automatic synchronization of widgets state to the URL. See [URL Synchronization](/guides/advanced-topics.html#how-to-synchronize-the-url-with-the-search). + * @propType {number=700} threshold - Threshold in milliseconds above which new locations will be pushed to the history, instead of replacing the previous one. See [Location Debouncing](guides/advanced-topics.html#how-to-synchronize-the-url-with-the-search). * @example * import {InstantSearch, SearchBox, Hits} from 'react-instantsearch/dom'; *