https://github.com/princed/query-assist
Query Assist component. REPO DEPRECATED, see
https://github.com/princed/query-assist
Last synced: about 2 months ago
JSON representation
Query Assist component. REPO DEPRECATED, see
- Host: GitHub
- URL: https://github.com/princed/query-assist
- Owner: princed
- License: apache-2.0
- Created: 2016-08-22T09:50:27.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2017-08-08T13:33:55.000Z (almost 9 years ago)
- Last Synced: 2025-12-26T08:35:32.667Z (6 months ago)
- Language: JavaScript
- Homepage: https://github.com/JetBrains/ring-ui
- Size: 42 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Query Assist component
## This repo is deprecated
Ring UI library is now open-sourced including [Query Assist component](http://www.jetbrains.org/ring-ui/query-assist.html).
## Disclaimer
This temporary repo contains our Query Assist component that we're often asked to share.
The component depends on a half of our library and a few external modules. Thus, it is not possible to share it as just one file.
It is unlikely that we will accept any pull request as this is not the main repo.
However, any feedback is highly appreciated.
## Try the demo
Try the Query Assist component in action on our production services: [Hub](https://hub.jetbrains.com), [Upsource](https://upsource.jetbrains.com) or [YouTrack new agile board](https://youtrack.jetbrains.com/agiles). In YouTrack, most query and search fields in other parts of the interface still use the previous version of the component.
Prerequisites: `nodejs` (tested with `5.7.0`).
1. Install dependencies: `npm install`.
2. Start [server](http://localhost:8080/): `npm start`.
3. Run `npm run build` to build minified demo version.
Optional: Provide [browserlist](https://github.com/ai/browserslist) file to configure vendor prefixes generated by [Autoprefixer](https://github.com/postcss/autoprefixer).
## Important files in the repo
- `components/query-assist/query-assist.js` — the component source
- `query-assist.js` — the component usage demo
- `webpack.config.js` — minimal webpack config required to build the component
## End-user shortcuts
| Shortcut | Action |
| --- | --- |
| `down` | Select the next suggestion |
| `up` | Select the previous suggestion |
| `enter`, `command+enter`, `ctrl+enter`| Insert selected suggestion or apply the query when nothing is selected |
| `ctrl+space` | Show suggestions popup |
| `esc` | Hide suggestions popup |
| `tab` | Replace the current part of a query with a selected or the first (!) suggestion |
## Component params
| Field | Type | Default | Is required | Description |
| --- | --- | --- | --- | --- |
| autoOpen | `bool` | `false` | | Open suggestions popup on the initial render |
| caret | `number` | `query.length` | | Initial caret position |
| clear | `bool` | `false` | | Show clickable looking cross on the right which clears query |
| className | `string` | `''` | | Additional class for component |
| popupClassName | `string` | `''` | | Pass additional class for popup |
| dataSource | `func` | | :heavy_check_mark: | Data source function |
| delay | `number` | `0` | | Input debounce delay |
| disabled | `bool` | `false` | | Disable component |
| focus | `bool` | `false` | | Initial focus |
| hint | `string` | `''` | | Hint under the suggestions list |
| hintOnSelection | `string` | `''` | | Hint under the suggestions list visible when suggestion is selected |
| glass | `bool` | `false` | | Show clickable looking glass on the right which applies query |
| loader | `bool` | `false` | | Show loader when data source request is in process |
| placeholder | `string` | `''` | | Field placeholder value |
| onApply | `func` | | | Called when the query is applied. An object with fields `caret`, `focus` and `query` is passed as argument. |
| onChange | `func` | | | Called when the query is changed. An object with fields `caret` and `query` is passed to it as argument. |
| onClear | `func` | | | Called when the query is cleared. Called without arguments. |
| onFocusChange | `func` | | | Called when the focus status is changed. An object with fields `focus` is passed as argument. |
| shortcuts | `bool` | `true` | | Enable shortcuts|
| query | `string` | `''` | | Initial query |
## Data source function
Component class calls a data source function when user input happens and passes object with fields `caret`, `focus` and `query` as the only argument.
The function must return object with fields described below. The object can be optionally wrapped in Promise.
### return object fields
`caret` and `query` should just return server values provided to data source function.
These fields allow the Query Assist component to recognise and drop earlier responds from server, if responds took longer than the most recent ones.
| Field | Type | Default | Is required | Description |
| --- | --- | --- | --- | --- |
| caret | `string` | `0` | | Caret from request |
| query | `string` | `''` | | Query from request |
| styleRanges | `Array` | | | Array of `styleRange` objects, used to highlight request in input field |
| suggestions | `Array` | | :heavy_check_mark: | Array of `suggestion` objects to show. |
### `styleRange` object fields
| Field | Type | Is required | Description |
| --- | --- | --- | --- |
| start | `number` | :heavy_check_mark: | Range start (in characters). |
| length | `number` | :heavy_check_mark: | Range length (in characters). |
| style | `string` | :heavy_check_mark: | Style of the range. Possible values: `text`, `field_value`, `field_name`, `operator` |
### `suggestion` object fields
| Field | Type | Is required | Description |
| --- | --- | --- | --- |
| prefix | `string` | | Suggestion option prefix |
| option | `string` | :heavy_check_mark: | Suggestion option |
| suffix | `string` | | Suggestion option suffix |
| description | `string` | | Suggestion option description. Is not visible when a group is set |
| matchingStart | `number` | :heavy_check_mark:, when matchingEnd is set | Start of highlighted part of option in suggestions list (in characters)|
| matchingEnd | `number` | :heavy_check_mark:, when matchingEnd is set | End of highlighted part of option in suggestions list (in characters)|
| caret | `number` | :heavy_check_mark: | Position of caret after option completion (in characters) |
| completionStart | `number` | :heavy_check_mark: | Index where to start insertion (or replacement, when completing with the `Tab` key) of completion option (in characters). |
| completionEnd | `number` | :heavy_check_mark: | Index where to end replacement of completion option (in characters) |
| group | `string` | | Group title. Options with the same title are grouped under it. |
| icon | `string` | | Icon URI, Data URI is possible |
## License
Apache 2.0