npm package: @notcominghome/qliksense-script-editor
Description: React Monaco Editor component for QlikSense script editing with IntelliSense support
Author: catalincernatro
Latest version: 1.0.0

# QlikSense Script Editor

A powerful React Monaco Editor component for QlikSense script editing with full IntelliSense support, syntax highlighting, and validation.

## Features

- **Syntax Highlighting** - Full syntax highlighting for QlikSense script language
- **IntelliSense** - Autocomplete for 75+ keywords, 200+ functions, and 40+ code snippets
- **Hover Documentation** - Detailed documentation appears when hovering over keywords and functions
- **Validation** - Real-time validation for bracket matching, control structures, and common errors
- **Custom Themes** - Three beautiful themes: Qlik Light, Qlik Dark, and Qlik Green
- **TypeScript Support** - Full TypeScript definitions included
- **Zero Configuration** - Works out of the box with sensible defaults

## Installation

```bash
npm install qliksense-script-editor
```

or with yarn:

```bash
yarn add qliksense-script-editor
```

### Peer Dependencies

Make sure you have React installed:

```bash
npm install react react-dom
```

## Quick Start

```tsx
import { QlikScriptEditor } from 'qliksense-script-editor';
import { useState } from 'react';

function App() {
  const [script, setScript] = useState(`
// Load data from QVD
Sales:
LOAD
    CustomerID,
    ProductID,
    Sales,
    Date
FROM [lib://DataFiles/Sales.qvd]
(qvd);
  `);

  return (
    <QlikScriptEditor
      value={script}
      onChange={setScript}
      theme="qlik-dark"
      height="600px"
    />
  );
}

export default App;
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | - | Controlled value of the editor |
| `defaultValue` | `string` | `''` | Default value when uncontrolled |
| `onChange` | `(value: string \| undefined) => void` | - | Callback when content changes |
| `height` | `string \| number` | `'400px'` | Height of the editor |
| `width` | `string \| number` | `'100%'` | Width of the editor |
| `theme` | `'vs' \| 'vs-dark' \| 'hc-black' \| 'qlik-light' \| 'qlik-dark' \| 'qlik-green'` | `'vs'` | Editor theme |
| `options` | `IStandaloneEditorConstructionOptions` | `{}` | Additional Monaco editor options |
| `readOnly` | `boolean` | `false` | Whether the editor is read-only |
| `onMount` | `(editor, monaco) => void` | - | Callback when editor is mounted |
| `enableValidation` | `boolean` | `true` | Enable/disable validation |
| `validationDelay` | `number` | `500` | Validation debounce delay in ms |
| `className` | `string` | - | Additional CSS class name |
| `style` | `React.CSSProperties` | - | Additional inline styles |

## Themes

### Available Themes

- **`vs`** - Visual Studio Light (default Monaco theme)
- **`vs-dark`** - Visual Studio Dark (default Monaco dark theme)
- **`hc-black`** - High Contrast Black
- **`qlik-light`** - Qlik Sense Light theme
- **`qlik-dark`** - Qlik Sense Dark theme
- **`qlik-green`** - Qlik signature green theme

### Using Themes

```tsx
<QlikScriptEditor
  value={script}
  onChange={setScript}
  theme="qlik-dark"
/>
```

## IntelliSense Features

### Keywords

The editor provides autocomplete for all QlikSense script keywords:

- **Statements**: `LOAD`, `SELECT`, `LET`, `SET`, `STORE`, `DROP TABLE`, etc.
- **Control Statements**: `IF`, `FOR`, `DO`, `SUB`, `SWITCH`, etc.
- **Prefixes**: `JOIN`, `CONCATENATE`, `MAPPING`, `CROSSTABLE`, etc.
- **Clauses**: `FROM`, `WHERE`, `GROUP BY`, `ORDER BY`, etc.

### Functions

200+ built-in functions with full documentation:

- **String Functions**: `Left`, `Right`, `Mid`, `Len`, `Replace`, `SubField`, etc.
- **Date/Time Functions**: `Today`, `Now`, `Year`, `Month`, `Day`, `AddMonths`, etc.
- **Aggregation Functions**: `Sum`, `Count`, `Avg`, `Min`, `Max`, `Concat`, etc.
- **Conditional Functions**: `If`, `Match`, `Pick`, `Alt`, `Coalesce`, etc.
- **And many more...**

### Snippets

40+ code snippets for common patterns:

| Prefix | Description |
|--------|-------------|
| `loadinline` | LOAD with inline data |
| `loadfile` | LOAD from file |
| `loadqvd` | LOAD from QVD |
| `loadexcel` | LOAD from Excel |
| `loadcsv` | LOAD from CSV |
| `ifthen` | IF/THEN/ELSE block |
| `for` | FOR/NEXT loop |
| `foreach` | FOR EACH loop |
| `sub` | SUB routine |
| `calendar` | Master calendar table |
| `incremental` | Incremental load pattern |
| `sectionaccess` | Section Access block |

## Validation

The editor validates your script for common errors:

- **Bracket Matching** - Unmatched `()`, `[]`, `{}`
- **Control Structures** - Unmatched `IF`/`END IF`, `FOR`/`NEXT`, `DO`/`LOOP`, etc.
- **String Literals** - Unclosed quotes
- **Missing Semicolons** - Warnings for potentially missing statement terminators

### Disabling Validation

```tsx
<QlikScriptEditor
  value={script}
  onChange={setScript}
  enableValidation={false}
/>
```

### Custom Validation Delay

```tsx
<QlikScriptEditor
  value={script}
  onChange={setScript}
  validationDelay={1000} // 1 second delay
/>
```

## Advanced Usage

### Accessing the Editor Instance

```tsx
import { QlikScriptEditor } from 'qliksense-script-editor';

function App() {
  const handleMount = (editor, monaco) => {
    // Access the editor instance
    editor.focus();

    // Add custom keybinding
    editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.KeyS, () => {
      console.log('Save triggered!');
    });
  };

  return (
    <QlikScriptEditor
      value={script}
      onChange={setScript}
      onMount={handleMount}
    />
  );
}
```

### Custom Monaco Options

```tsx
<QlikScriptEditor
  value={script}
  onChange={setScript}
  options={{
    fontSize: 16,
    minimap: { enabled: false },
    lineNumbers: 'off',
    wordWrap: 'on',
    tabSize: 2
  }}
/>
```

### Using the Language Standalone

You can register the QlikSense language with Monaco without using the React component:

```tsx
import { registerQlikLanguage } from 'qliksense-script-editor';
import * as monaco from 'monaco-editor';

// Register the language
registerQlikLanguage(monaco);

// Create an editor with the language
const editor = monaco.editor.create(document.getElementById('container'), {
  value: 'LOAD * FROM data.qvd (qvd);',
  language: 'qlikscript',
  theme: 'qlik-dark'
});
```

## Utility Functions

The package exports several utility functions for working with QlikSense scripts:

```tsx
import {
  extractTableNames,
  extractVariableNames,
  extractFieldNames,
  countLinesOfCode,
  formatScript,
  validateScript
} from 'qliksense-script-editor';

const script = `
Sales:
LOAD * FROM sales.qvd (qvd);

LET vToday = Today();
`;

// Extract table names
const tables = extractTableNames(script); // ['Sales']

// Extract variable names
const variables = extractVariableNames(script); // ['vToday']

// Count lines of code (excluding comments/empty lines)
const loc = countLinesOfCode(script); // 3

// Format script (basic indentation)
const formatted = formatScript(script);

// Validate script
const markers = validateScript(script);
```

## API Reference

### Exported Types

```tsx
import type {
  QlikScriptEditorProps,
  QlikKeyword,
  QlikFunction,
  QlikParameter,
  QlikOperator,
  QlikSnippet,
  QlikValidationMarker,
  QlikTheme,
  FunctionCategory,
  Monaco,
  IStandaloneCodeEditor
} from 'qliksense-script-editor';
```

### Exported Constants

```tsx
import {
  QLIK_KEYWORDS,      // Array of all keywords
  QLIK_FUNCTIONS,     // Array of all functions
  QLIK_OPERATORS,     // Array of all operators
  QLIK_SNIPPETS,      // Array of all snippets
  LANGUAGE_ID         // 'qlikscript'
} from 'qliksense-script-editor';
```

### Helper Functions

```tsx
import {
  // Keyword helpers
  getKeywordNames,
  findKeyword,

  // Function helpers
  getFunctionNames,
  findFunction,
  getFunctionsByCategory,
  getFunctionCategories,

  // Operator helpers
  getOperatorSymbols,
  findOperator,
  getOperatorsByCategory,

  // Snippet helpers
  getSnippetPrefixes,
  findSnippet,
  getSnippetsByCategory,

  // Theme helpers
  registerQlikThemes,
  getQlikThemeNames,

  // Validation helpers
  validateScript,
  setValidationMarkers,
  clearValidationMarkers,

  // Utility helpers
  debounce,
  throttle,
  extractTableNames,
  extractVariableNames,
  extractFieldNames,
  countLinesOfCode,
  formatScript,
  isValidIdentifier,
  escapeQlikString,
  parseConnectionString
} from 'qliksense-script-editor';
```

## Browser Support

This package works in all modern browsers that support ES2020:

- Chrome 80+
- Firefox 74+
- Safari 13.1+
- Edge 80+

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- Built on [Monaco Editor](https://microsoft.github.io/monaco-editor/)
- Uses [@monaco-editor/react](https://github.com/suren-atoyan/monaco-react)
- Inspired by [VSCode Qlik Extension](https://github.com/Gimly/vscode-qlik)