npm package: @stoplight/monaco
Description: Monaco Editor for React, with some light state management.
Author: Stoplight
Latest version: 7.0.1

# @stoplight/monaco

[![Maintainability](https://api.codeclimate.com/v1/badges/bb00da22bced49505b2e/maintainability)](https://codeclimate.com/repos/5bf2632b26f5dd02b40058af/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/bb00da22bced49505b2e/test_coverage)](https://codeclimate.com/repos/5bf2632b26f5dd02b40058af/test_coverage)

Monaco Editor for React, with some light state management.

- Explore the components: [Storybook](https://stoplightio.github.io/monaco/)
- View the changelog: [Releases](https://github.com/stoplightio/monaco/releases)

### Features

- **Two Way Binding**: Separate store model makes it easy to control the value outside of Monaco itself.
- **Themable**: Integrated with [@stoplight/ui-kit](https://github.com/stoplightio/ui-kit).
- **Editor State Management**: The editor view state will be saved and restored as the active store changes. This means the user cursor, undo stack, highlight, etc, will be preserved as you switch the stores out (which you'd normally do as the use moves between files, etc). You can see this in action in the Storybook by highlighting some text and switching back and forth between editors.
- **Highlight Lines**: Simple options to highlight particular lines.

### Installation

Supported in modern browsers.

```bash
# latest stable
yarn add @stoplight/monaco

# install dev deps
yarn add -D @stoplight/webpack
```

Note: there is some setup required to get this component to work.
A webpack-bundled version of `monaco-editor` is included and exported from the main module as a named export `monaco`, so you do _not_ have to use [monaco-editor-webpack-plugin](https://github.com/microsoft/monaco-editor-webpack-plugin), but you _do_ need to statically serve the webworkers at some route. By default this route is `/` but can be configured at runtime like so:

```ts
import { setGetWorkerUrlFunc } from "@stoplight/monaco";

// something like this
setGetWorkerUrlFunc(
  (fileName) => `${process.env.YOUR_CDN}/monaco-workers/${fileName}`
);
```

The webworkers that need to be served are in `node_modules/@stoplight/monaco/monaco-editor/monaco-workers` directory.

#### Configuring Storybook

Storybook makes it easy to add some public static file directories. Add an `-s` flag when you launch it.

We can't control the route, so this serves it at the default `/*.worker.js` routes.

`package.json`

```diff
  "scripts": {
-   "storybook": "start-storybook -p 9001",
+   "storybook": "start-storybook -s ./node_modules/@stoplight/monaco/monaco-editor/monaco-workers -p 9001",
```

### Usage

#### MonacoCodeEditor

```tsx
import * as React from "react";
import { MonacoCodeEditor, MonacoCodeStore } from "@stoplight/monaco";

const store = new MonacoCodeStore({
  id: "a",
  path: "file:///a.js",
  value: "var y = true;"
});

store.onDidUpdateValue(val => {
  console.log('latest value', val);
});

// The store value is synced with the MonacoCodeEditor internal value, but you can
// also treat it as a controlled component by calling setValue on the store directly (this will update the component).
const resetValue = () => store.setValue('');

export const Component = () => {
  return (
    <div>
      <button onClick={resetValue}>Reset Value</div>
      <MonacoCodeEditor store={store} />
    </div>
  );
};
```

#### MonacoDiffEditor

Note that `DiffEditor` is not included in the default export to help with bundle size shaking.

```tsx
import * as React from "react";
import { MonacoDiffStore } from "@stoplight/monaco";
import { MonacoDiffEditor } from "@stoplight/monaco/DiffEditor";

const store = new MonacoDiffStore({
  id: "a",
  lang: "js",
  original: "var y = true;"
  modified: "var y = false;"
});

store.modifiedStore.onDidUpdateValue(val => {
  console.log('latest value', val);
});

// The diff store has a originalStore and modifiedStore that you can access to manipulate highlight, listen to events, etc.
const resetValue = () => store.modifiedStore.setValue('');

export const Component = () => {
  return (
    <div>
      <button onClick={resetValue}>Reset Value</div>
      <MonacoDiffEditor store={store} options={{ originalEditable: true }} />
    </div>
  );
};
```

#### onEditorDidChange and useCurrentCodeEditor

In some cases you might need react to the underlying `IStadaloneCodeEditor` being changed.

```tsx
import * as React from "react";
import { MonacoCodeStore, useCurrentCodeEditor } from "@stoplight/monaco";

const store = new MonacoCodeStore({
  id: "a",
  path: "file:///a.js",
  value: "var y = true;"
});

// You can subscribe to this event
store.onEditorDidChange(editor => {
  console.log('editor', editor);
});

// Or use the provided hook
export const Toolbar = () => {
  const editor = useCurrentCodeEditor(store)

  React.useEffect(() => {
    // Do something with the editor, like register plugins
  }, [editor]);

  return <ToolbarButtons />;
};
```

### Mocking

To use the Stoplight monaco mocks, do the following in your test files or in `jest.setup.ts`:

```js
require("@stoplight/monaco/mock").mock();
```

or if you're feeling importy

```ts
import { mock as mockMonaco } from "@stoplight/monaco/mock";
mockMonaco();
```

There isn't currently an `unmock` function or any variations of the mock, but if you need those, go ahead and add those to `mock.ts`. That's why I used a named export.

### Contributing

1. Clone repo.
2. Create / checkout `feature/{name}`, `chore/{name}`, or `fix/{name}` branch.
3. Install deps: `yarn`.
4. Make your changes.
5. Run tests: `yarn test.prod`.
6. Stage relevant files to git.
7. Commit: `yarn commit`. _NOTE: Commits that don't follow the [conventional](https://github.com/marionebl/commitlint/tree/master/%40commitlint/config-conventional) format will be rejected. `yarn commit` creates this format for you, or you can put it together manually and then do a regular `git commit`._
8. Push: `git push`.
9. Open PR targeting the `develop` branch.