@knime/kds-code-editor 2.6.3

package/README.md

@@ -0,0 +1,133 @@
+# KNIME® Design System – Code Editor
+
+This is part of the [KNIME Design System](https://github.com/knime/knime-designsystem) maintained by the [UI Core Team](mailto:team-ui-core@knime.com).
+
+This package contains the `KdsCodeEditor` component, a code editor that follows the KNIME Design System. It is based on the [Vue] JavaScript framework and powered by the [Monaco editor][Monaco].
+
+It's published as npm package: [@knime/kds-code-editor]
+
+## Why a separate package?
+
+Monaco is a large dependency (the editor core plus language workers) that is irrelevant to most consumers of `@knime/kds-components`. Keeping the code editor in its own package keeps that dependency, bundle, and security-audit/SBOM surface **opt-in** — only apps that install this package pull it in.
+
+`monaco-editor` is declared as a peer dependency and is **externalized** in the build (see [`vite.config.ts`](vite.config.ts)): Monaco holds global state (language registry, `MonacoEnvironment`, models), so the host app controls the single shared instance and can pull CVE-patched versions via its own lockfile without waiting on a republish.
+
+## Setup in consuming repositories
+
+### Peer dependency
+
+`monaco-editor` is a peer dependency (see [Why a separate package?](#why-a-separate-package)). Install a version matching the peer range declared in [package.json](package.json).
+
+### Monaco shadow-DOM patch (required inside KNIME UI extensions)
+
+Monaco's hover, suggest, and action widgets mis-position and mis-detect mouse
+leave when the editor is rendered inside a shadow root — which is how KNIME
+embeds UI extensions (AP-25740). The fix is a
+[pnpm patch](https://pnpm.io/settings#patcheddependencies) that ships with this
+package under [`patches/`](patches/).
+
+Because pnpm applies patches in the installing workspace (a package cannot
+patch its consumer's dependencies), every consuming repository must apply it
+to its own `monaco-editor` install:
+
+1. Copy `node_modules/@knime/kds-code-editor/patches/monaco-editor@<version>.patch`
+   into your repository (e.g. a `patches/` folder). Do not reference the file
+   inside `node_modules` directly — on a cold install pnpm needs the patch
+   before the package providing it is extracted.
+2. Register it in your `pnpm-workspace.yaml`:
+
+   ```yaml
+   patchedDependencies:
+     monaco-editor@0.55.1: patches/monaco-editor@0.55.1.patch
+   ```
+
+When this package bumps its `monaco-editor` peer range, the bundled patch is
+updated with it — re-copy the patch file when you bump Monaco.
+
+### Monaco state is global
+
+Standalone Monaco keeps page-global state, and `KdsCodeEditor` participates
+in it:
+
+- **Theme:** the component switches Monaco's built-in `vs-light` / `vs-dark`
+  theme to follow the KDS dark-mode setting — once at mount and again on every
+  dark-mode change. Monaco's theme applies to **every** standalone editor on
+  the page, so the host app's own Monaco editors switch along with it, and a
+  custom theme set by the host is overridden while a `KdsCodeEditor` is
+  mounted. If your app defines its own Monaco editors, expect them to render
+  with `vs-light` / `vs-dark` alongside this component.
+- **Worker environment and languages:** `setupMonacoEnvironment` installs a
+  `MonacoEnvironment` only when the host app has not already defined one, and
+  the custom language grammars shipped with this package (e.g. `toml`) are
+  registered in Monaco's global language registry at import time — they are
+  also available to the host app's own editors.
+
+## Using the editor in a Vue application
+
+Install the [@knime/kds-code-editor] npm package as a dependency. It requires `@knime/kds-components`, `monaco-editor`, and `vue` as peer dependencies:
+
+```sh
+pnpm add @knime/kds-code-editor @knime/kds-components @knime/kds-styles monaco-editor
+```
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+
+import { KdsCodeEditor } from "@knime/kds-code-editor";
+
+const value = ref('key = "value"');
+</script>
+
+<template>
+  <KdsCodeEditor v-model="value" language="toml" :min-rows="5" />
+</template>
+```
+
+### Public exports
+
+All public symbols follow the KDS `Kds` prefix convention:
+
+| Export                            | Kind      | Description                                                   |
+| --------------------------------- | --------- | ------------------------------------------------------------- |
+| `KdsCodeEditor`                   | component | The code editor (with header, copy button, and sub-text)      |
+| `setupMonacoEnvironment`          | function  | Installs the Monaco worker environment (no-op if already set) |
+| `kdsCodeEditorState`              | const     | Editor states (`default` / `error` / `warning`)               |
+| `kdsCodeEditorStates`             | const     | Array of all editor states                                    |
+| `KdsCodeEditorProps`              | type      | Props of `KdsCodeEditor`                                      |
+| `KdsCodeEditorState`              | type      | Union of the editor states                                    |
+| `KdsCodeEditorAction`             | type      | Union of the header action types below                        |
+| `KdsCodeEditorButtonAction`       | type      | Header action rendered as `KdsButton`                         |
+| `KdsCodeEditorToggleButtonAction` | type      | Header action rendered as `KdsToggleButton`                   |
+| `KdsCodeEditorMenuButtonAction`   | type      | Header action rendered as `KdsMenuButton`                     |
+
+### Using with Vitest, Nuxt, or Vite SSR
+
+The published JavaScript imports its CSS as a side effect (e.g.
+`import "./index.css"`), which bundlers handle automatically. When the package
+is instead evaluated by Node's native ESM loader — as **Vitest** and
+**Vite/Nuxt SSR** do by default, since they externalize `node_modules` — Node
+has no `.css` loader and throws `Unknown file extension ".css"`. Configure the
+consuming project once so `@knime/*` packages are processed instead of
+externalized:
+
+```ts
+// Vitest — vitest.config.ts
+export default defineConfig({
+  test: { server: { deps: { inline: [/@knime\//] } } },
+});
+```
+
+```ts
+// Vite SSR — vite.config.ts
+export default defineConfig({ ssr: { noExternal: [/@knime\//] } });
+```
+
+```ts
+// Nuxt — nuxt.config.ts
+export default defineNuxtConfig({ build: { transpile: [/@knime\//] } });
+```
+
+[Vue]: https://vuejs.org/
+[Monaco]: https://microsoft.github.io/monaco-editor/
+[@knime/kds-code-editor]: https://www.npmjs.com/package/@knime/kds-code-editor