# @atlassianlabs/jql-editor

> This package allows consumers to render an advanced JQL editor component to enable autocomplete-assisted authoring and validation of JQL queries.

Latest version **2.0.1** (published 2023-07-12) · 0 weekly downloads

## Install

```sh
npm install @atlassianlabs/jql-editor
pnpm add @atlassianlabs/jql-editor
yarn add @atlassianlabs/jql-editor
bun add @atlassianlabs/jql-editor
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2023-07-12 |
| First published | 2021-12-10 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 35 |
| Unpacked size | 2 MB |
| Known vulnerabilities | 0 (+2 in 2 direct dependencies) |
| Install scripts | no |
| Author | Atlassian Pty Ltd |
| Maintainers | doklovic, prkb, crumley, nrundquist, dkolbly-atlassian, kpainter-atl, soneymathew |

## Links

- npm: https://www.npmjs.com/package/@atlassianlabs/jql-editor
- Repository: https://bitbucket.org/atlassian/atlassian-frontend
- Homepage: https://bitbucket.org/atlassian/atlassian-frontend#readme
- Issues: https://bitbucket.org/atlassian/atlassian-frontend/issues
- npm.io page: https://npm.io/package/@atlassianlabs/jql-editor

## Dependencies (35)

- [rxjs](https://npm.io/package/rxjs.md) ^5.5.0
- [util](https://npm.io/package/util.md) ^0.12.4
- [uuid](https://npm.io/package/uuid.md) ^3.1.0
- [assert](https://npm.io/package/assert.md) ^2.0.0
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [antlr4ts](https://npm.io/package/antlr4ts.md) 0.5.0-alpha.4
- [@atlaskit/form](https://npm.io/package/@atlaskit/form.md) ^8.11.0
- [@atlaskit/icon](https://npm.io/package/@atlaskit/icon.md) ^21.12.0
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.0.0
- [@emotion/react](https://npm.io/package/@emotion/react.md) ^11.7.1
- [@atlaskit/theme](https://npm.io/package/@atlaskit/theme.md) ^12.5.0
- [@emotion/styled](https://npm.io/package/@emotion/styled.md) ^10.0.7
- [react-intl-next](https://npm.io/package/react-intl-next.md) npm:react-intl@^5.18.1
- [@atlaskit/avatar](https://npm.io/package/@atlaskit/avatar.md) ^21.3.0
- [@atlaskit/button](https://npm.io/package/@atlaskit/button.md) ^16.8.0
- [@atlaskit/tokens](https://npm.io/package/@atlaskit/tokens.md) ^1.11.0
- [prosemirror-view](https://npm.io/package/prosemirror-view.md) 1.23.7
- [@atlaskit/spinner](https://npm.io/package/@atlaskit/spinner.md) ^15.5.0
- [@atlaskit/tooltip](https://npm.io/package/@atlaskit/tooltip.md) ^17.8.0
- [prosemirror-model](https://npm.io/package/prosemirror-model.md) 1.16.0
- [prosemirror-state](https://npm.io/package/prosemirror-state.md) 1.3.4
- [react-magnetic-di](https://npm.io/package/react-magnetic-di.md) ^2.2.6
- [react-sweet-state](https://npm.io/package/react-sweet-state.md) ^2.6.5
- [prosemirror-keymap](https://npm.io/package/prosemirror-keymap.md) 1.1.4
- [react-loosely-lazy](https://npm.io/package/react-loosely-lazy.md) ^1.0.0
- [prosemirror-history](https://npm.io/package/prosemirror-history.md) ^1.1.3
- [prosemirror-commands](https://npm.io/package/prosemirror-commands.md) 1.1.11
- [prosemirror-transform](https://npm.io/package/prosemirror-transform.md) 1.3.2
- [@atlassianlabs/jql-ast](https://npm.io/package/@atlassianlabs/jql-ast.md) ^2.1.0
- [@atlaskit/analytics-next](https://npm.io/package/@atlaskit/analytics-next.md) ^9.1.0
- [@atlassianlabs/jql-parser](https://npm.io/package/@atlassianlabs/jql-parser.md) ^1.0.0
- [@react-loosely-lazy/manifest](https://npm.io/package/@react-loosely-lazy/manifest.md) ^1.0.0
- [@atlaskit/analytics-gas-types](https://npm.io/package/@atlaskit/analytics-gas-types.md) ^5.1.0
- [@atlassianlabs/jql-autocomplete](https://npm.io/package/@atlassianlabs/jql-autocomplete.md) ^1.1.1
- [@atlassianlabs/jql-editor-common](https://npm.io/package/@atlassianlabs/jql-editor-common.md) ^1.0.0

## Recent versions

- 2.0.1 (latest) — 2023-07-12
- 2.0.0 — 2023-06-02
- 1.2.0 — 2022-09-26
- 1.1.0 — 2022-08-10
- 1.0.0 — 2022-02-21
- 0.0.3 — 2021-12-17
- 0.0.2 — 2021-12-17
- 0.0.1 — 2021-12-10

## README

# JQL Editor

[![Atlassian license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)

This package allows consumers to render an advanced JQL editor component to enable autocomplete-assisted authoring and
validation of JQL queries.

## Usage

To render the editor, the consumer must configure an `autocompleteProvider`, which defines callback functions used to
retrieve JQL fields, functions and values. To ease configuration, we also ship the
`@atlassianlabs/jql-editor-autocomplete-rest` package, which wraps these callbacks and provides simple hooks to delegate
to Jira REST API's.

A minimal configuration of the JQL editor is as follows:

```typescript jsx
import { useCallback } from 'react';
import { JQLEditorAsync as JQLEditor } from '@atlassianlabs/jql-editor';
import { useAutocompleteProvider } from '@atlassianlabs/jql-editor-autocomplete-rest';

const getInitialData = async (url: string) => {
  const response = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ includeCollapsedFields: true })
  });
  const data = response.json();

  return {
    jqlFields: data.visibleFieldNames,
    jqlFunctions: data.visibleFunctionNames,
  };
};

const getSuggestions = async (url: string) => {
  const response = await fetch(url);
  return response.json();
};

const MyJQLEditor = () => {
  const autocompleteProvider = useAutocompleteProvider('my-app', getInitialData, getSuggestions);

  const onSearch = useCallback((jql: string) => {
    // Do some action on search    
  }, []);

  return (
    <JQLEditor
      analyticsSource={'my-app'}
      query={''}
      onSearch={onSearch}
      autocompleteProvider={autocompleteProvider}
      locale={"en"}
    />
  );
};
```

For app developers, please refer to the `@atlassianlabs/jql-editor-connect` and `@atlassianlabs/jql-editor-forge`
packages. Which come pre-configured with Jira autocomplete integration.

## Installation

```sh
yarn add @atlassianlabs/jql-editor
```

## Documentation

### Searching and authoring JQL

There are two main use cases for the editor:

1. Searching by a JQL query
2. Authoring a JQL query

The key difference between the two is that rendering a search button may not make sense when authoring JQL, e.g. when
using the JQL editor as a form input. The searching use case is documented above, here we'll discuss authoring.

#### Authoring JQL

Hiding the search button is as simple as not providing an `onSearch` prop. Instead you'll want to use `onUpdate` which
is triggered whenever the query is updated.

By default, the editor will automatically show any syntax errors when the user presses search. Without the search button
the consumer will need to set errors to show manually.

```typescript jsx
import { useCallback, useMemo, useState } from 'react';
import { Jast, JQLParseError } from '@atlassianlabs/jql-ast';
import { JQLEditorAsync as JQLEditor, ExternalError } from '@atlassianlabs/jql-editor';
import debounce from 'lodash/debounce';

const MyJQLEditor = () => {
  const [errors, setErrors] = useState<ExternalError[]>([]);

  const debounceSetErrors = useMemo(() => {
    // Update our errors after a 1 second debounce
    return debounce((parseErrors: JQLParseError[]) => {
      // Format JQL parse errors to be shown as custom error messages in the editor
      const errorMessages: ExternalError[] = parseErrors.map(({ description }) => ({
        message: description,
        type: 'error',
      }));
      setErrors(errorMessages)
    }, 1000);
  }, [setErrors]);

  const onUpdate = useCallback((jql: string, jast: Jast) => {
    debounceSetErrors(jast.errors)
  }, []);

  return (
    <JQLEditor
      analyticsSource={'my-app'}
      query={''}
      onUpdate={onUpdate}
      messages={errors}
      autocompleteProvider={/* ... */}
      locale={"en"}
    />
  );
};
```

Using the same API, the editor may also show warning and info messages:
```typescript jsx
const [messages] = useState<ExternalMessage[]>([
  { type: 'error', message: `I'm an error message`} as ExternalError,
  { type: 'warning', message: `I'm a warning message`} as ExternalWarning,
  { type: 'info', message: `I'm an info message`} as ExternalInfo,
]);

return (
  <JQLEditor
    {/* ... */}
    messages={messages}
  />
);
```

Its worth mentioning that messages are rendered by the priority
and only a single type of messages could be present on UI at once.

So in the example above, only an error message will be rendered.

## Support

For developers outside of Atlassian looking for help, or to report
issues, [please make a post on the community forum](https://community.developer.atlassian.com/c/atlassian-ecosystem-design)
. We will monitor the forums and redirect topics to the appropriate maintainers.

## License

Copyright (c) 2021 - 2022 Atlassian and others. Apache 2.0 licensed, see [LICENSE](LICENSE) file.

---
_Source: https://npm.io/package/@atlassianlabs/jql-editor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
