princed / query-assist

Query Assist component. REPO DEPRECATED, see

Query Assist component

This repo is deprecated

Ring UI library is now open-sourced including Query Assist component.

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, Upsource or YouTrack new agile board. 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: npm start.
3. Run npm run build to build minified demo version.

Optional: Provide browserlist file to configure vendor prefixes generated by 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		✔️	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<suggestion>			Array of styleRange objects, used to highlight request in input field
suggestions	Array<styleRange>		✔️	Array of suggestion objects to show.

styleRange object fields

Field	Type	Is required	Description
start	number	✔️	Range start (in characters).
length	number	✔️	Range length (in characters).
style	string	✔️	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	✔️	Suggestion option
suffix	string		Suggestion option suffix
description	string		Suggestion option description. Is not visible when a group is set
matchingStart	number	✔️, when matchingEnd is set	Start of highlighted part of option in suggestions list (in characters)
matchingEnd	number	✔️, when matchingEnd is set	End of highlighted part of option in suggestions list (in characters)
caret	number	✔️	Position of caret after option completion (in characters)
completionStart	number	✔️	Index where to start insertion (or replacement, when completing with the Tab key) of completion option (in characters).
completionEnd	number	✔️	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