monacozen 0.1.0 → 0.3.0

package/README.md

@@ -1,35 +1,43 @@
-# monacozen
+<center><a href="https://npmjs.com/package/monacozen"><img src="https://shieldcn.dev/npm/v/monacozen.svg?variant=secondary&logo=npm&label=latest+version" alt="Latest version on npm"/></a> <a href="https://github.com/Jaid/monacozen/raw/HEAD/license.txt"><img src="https://shieldcn.dev/github/license/Jaid/monacozen.svg?variant=secondary" alt="License"/></a> <a href="https://bun.sh"><picture><source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/badge/Bun-fbf0df.svg?variant=outline&logo=bun&logoColor=fbf0df&mode=dark"><img src="https://shieldcn.dev/badge/Bun-fbf0df.svg?variant=outline&logo=bun&logoColor=fbf0df&mode=light" alt="Bun"/></picture></a></center>
 
-An opinionated React editor with a lazily loaded Monaco backend and a lightweight native alternative.
+# Monacozen
 
-## Install
+text editor component with batteries included and UI clutter removed
+
+## installation
+
+<a href="https://npmjs.com/package/monacozen"><img src="https://shieldcn.dev/badge/npm-monacozen-C23039.svg?variant=secondary&logo=npm" alt="monacozen on npm"/></a>
 
 ```sh
-npm install monacozen
+npm install --save monacozen
 ```
 
-React and React DOM are peer dependencies. Monaco, its workers and Antimono are included in the built package. Use a browser bundler that supports CSS imports, dynamic imports and worker asset URLs. The production package is tested through a separate Vite consumer build.
-
-## Monaco editor
+## example
 
 ```tsx
+import {useState} from 'react'
 import Monacozen from 'monacozen'
 
+const [text, setText] = useState<string>('')
+
 <Monacozen
   language='typescript'
-  monaco={{padding: {top: 6}, readOnly: false}}
   value={text}
   onChange={value => setText(value ?? '')}
 />
 ```
 
+## usage
+
+### Monaco editor
+
 `monaco` replaces the former `options` prop. Omit it to use the shared defaults or pass an options object to override them. `fontFamily` and `disableMonospaceOptimizations` are excluded because the `font` prop controls them. Padding is not part of the shared defaults.
 
 The existing Monaco props, including `beforeMount`, `onMount`, `onChange`, `onValidate`, model paths, language settings and view-state options, remain available in Monaco mode. Ordinary DOM events such as `onFocus`, `onBlur`, `onKeyDown`, `onPaste` and `onContextMenu` are handled on the enclosing element and bubble from the editor. `wrapperProps` provides additional wrapper attributes.
 
 The common `readOnly`, `disabled`, `placeholder`, `autoFocus` and `aria-label` props work in both modes. Explicit common props take precedence over the corresponding Monaco options.
 
-## Native editor
+### native editor
 
 ```tsx
 <Monacozen
@@ -69,21 +77,59 @@ A dynamically selected mode is supported too:
 
 Uncontrolled text is retained when switching modes. For controlled input, keep supplying `value`. The callback types reflect the backend: a dynamically selected mode has a change-event union and an `onMount` callback that may receive either editor kind. Use `SwitchableEditorProps` when explicitly typing a dynamically selected mode.
 
-## Appearance
+### appearance
 
 `dark` defaults to `true`. Monaco uses the bundled, modified `vs-dark` theme with a black background. `dark={false}` selects its light theme. The native editor uses white text on black or black text on white.
 
 `font` defaults to `antimono` and also accepts `mono` for the system monospace font or `dense` for the system sans-serif font. Both backends support `height`, `width`, `className` and `style`.
 
-## Loading
+## advanced usage
 
-Importing Monacozen does not initialize Monaco or load either stylesheet. Rendering the Monaco backend starts the React adapter and Monaco imports concurrently. A Suspense boundary displays the `loading` prop while they load. Monaco's stylesheet belongs to its lazy chunks rather than the public entry, so it is fetched before the editor mounts.
+### loading
+
+Importing Monacozen does not initialize Monaco or load either stylesheet. Rendering the Monaco backend starts the React adapter and Monaco imports concurrently. A Suspense boundary displays the `loading` prop while they load. Monaco’s stylesheet belongs to its lazy chunks rather than the public entry, so it is fetched before the editor mounts.
 
 Antimono has a separate stylesheet and lazy import. It is loaded only when a mounted editor selects `font='antimono'`, including when that selection comes from the default. Selecting `mono` or `dense` alone does not load it. Once the font finishes loading, mounted Monaco editors remeasure their font metrics.
 
-Modules and styles are reused across instances and mode changes. Styles are not removed when a component unmounts. Language workers are constructed on demand; an existing `MonacoEnvironment` worker configuration is respected. Loading errors can be handled by the application's React error boundary.
+Modules and styles are reused across instances and mode changes. Styles are not removed when a component unmounts. Language workers are constructed on demand; an existing `MonacoEnvironment` worker configuration is respected. Loading errors can be handled by the application’s React error boundary.
+
+### schemas
+
+The language-agnostic `schema` prop accepts a JSON Schema object. Monacozen applies it when the active model has a schema-aware language service. JSON and YAML are supported out of the box; unsupported languages and the native textarea backend simply ignore the prop.
+
+```tsx
+const schema = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Display name.',
+    },
+    enabled: {type: 'boolean'},
+  },
+}
+
+<Monacozen language='yaml' schema={schema} value={text} />
+```
+
+The association follows the active Monaco model, including model and language changes, and is removed when `schema` is unset or the editor is disposed. This also works directly with JSON Schema objects generated by libraries such as Zod. Schema-aware completion, hover documentation and diagnostics are provided by the active language service.
+
+YAML additionally includes Prettier formatting. Standard YAML language-server schema comments remain supported when no `schema` prop is supplied:
+
+```tsx
+<Monacozen
+  language='yaml'
+  path='file:///.prettierrc.yaml'
+  defaultValue={'# yaml-language-server: $schema=https://json.schemastore.org/prettierrc.json\nsingleQuote: true\nproseWrap: always\n'}
+/>
+```
+
+Remote schemas and references are fetched on demand. Remote servers must allow browser requests from your application's origin. An inline `schema` can use internal fragment references and absolute remote `$ref` values; use a URL-backed YAML schema comment when relative external references need a URL base. Filenames alone do not enable automatic SchemaStore catalog lookup.
 
-## Additional languages
+The YAML language service is registered once for the shared Monaco instance, and its bundled worker starts only when YAML is used. Consumers do not need to install `monaco-yaml` or add a YAML worker to their bundler configuration. As with other language workers, applications supplying their own `MonacoEnvironment.getWorker` or `getWorkerUrl` remain responsible for handling the `yaml` label.
+
+### additional languages
 
 Set `language` to one of these IDs:
 
@@ -99,26 +145,75 @@ The definitions provide syntax highlighting and basic editing configuration, not
 
 The Monaco build continues to exclude `abap`, `apex`, `lexon`, `sb` and `flow9`.
 
-## Build
+## props
+
+option | type | default | info
+--- | --- | --- | ---
+`className` | `string` |  | class name for the active editor element or Monaco wrapper
+`aria-label` | `string` |  | accessible label for both backends; mapped to Monaco’s ariaLabel option
+`autoFocus` | `boolean` | `false` | Focuses the active editor after mounting.
+`beforeMount` | `(monaco: MonacoApi) => void` |  | callback after Monaco loads and before editor creation
+`dark` | `boolean` | `true` | dark or light appearance
+`defaultLanguage` | `string` |  | language for newly created Monaco models
+`defaultPath` | `string` |  | path for newly created Monaco models
+`defaultValue` | `string` | `''` | initial value for uncontrolled usage and backend switching
+`disabled` | `boolean` | `false` | Disables editing; Monaco also receives domReadOnly.
+`font` | `'antimono' \| 'dense' \| 'mono'` | `'antimono'` | Antimono, system sans-serif or system monospace font
+`height` | `number \| string` | `'100%'`
+`keepCurrentModel` | `boolean` | `false` | Keeps the current Monaco model alive after unmounting.
+`language` | `string` |  | current Monaco model language
+`line` | `number` |  | line to reveal in Monaco
+`loading` | `ReactNode` | `'Loading…'` | Suspense fallback while the Monaco backend loads
+`monaco` | `MonacoOptions \| boolean` |  | Omit for the Monaco backend with shared defaults; false uses DummyEditor and true is shorthand for an empty Monaco options object.
+`overrideServices` | `Monaco.editor.IEditorOverrideServices` | `{}` | Monaco editor service overrides passed to [@monaco-editor/react](https://npmx.dev/package/@monaco-editor/react)
+`path` | `string` |  | current Monaco model path
+`placeholder` | `string` |  | placeholder text supported by both backends
+`readOnly` | `boolean` | `false` | editor read-only state
+`saveViewState` | `boolean` | `true` | Saves and restores Monaco model view state between model changes.
+`schema` | `EditorSchema` |  | JSON Schema applied to supported Monaco languages such as JSON and YAML; ignored elsewhere.
+`style` | `CSSProperties` |  | inline styles applied after the width and height defaults
+`value` | `string` |  | controlled editor value
+`width` | `number \| string` | `'100%'`
+`wrapperProps` | `HTMLAttributes<HTMLDivElement>` |  | attributes for the enclosing wrapper element
+`ref` | `Ref<HTMLTextAreaElement>` |  | native textarea ref when monaco is false
+`onChange` | `(value: string \| undefined, event: ChangeEvent<HTMLTextAreaElement> \| Monaco.editor.IModelContentChangedEvent) => void` |  | Called when the editor value changes; the native backend always provides a string.
+`onMount` | `(editor: HTMLTextAreaElement \| Monaco.editor.IStandaloneCodeEditor, monaco?: MonacoApi) => void` |  | Called after the active backend mounts.
+`onValidate` | `(markers: Monaco.editor.IMarker[]) => void` |  | callback when validation markers for the current model change
+
+## development
+
+### setting up
 
 ```sh
+git clone git@github.com:Jaid/monacozen.git
+cd monacozen
 bun install
-bun run build
 ```
 
-Vite compiles the JSX with React Compiler, produces `out/intermediate/src/main.js` and preserves lazy chunks and styles under `out/intermediate/assets`. `build_lib` packages that project without recombining its runtime chunks. The result is in `dist/monacozen/production`.
-
-The intermediate plugin attaches CSS imports to the chunks that own them. Monaco CSS and Antimono CSS remain separate. Runtime files keep the same relative layout through both build stages, including worker URLs. Monaco's public declarations are inlined into `lib.d.ts`; consumers do not need a separate `monaco-editor` installation for types.
+### linting
 
-The workspace plugins handle intermediate packaging, built-in theme overrides, language omission and additional lazy language registration. Additional language modules export `{language, configuration}`, using Monaco's Monarch tokenizer and language-configuration types.
+```sh
+bun run lint
+```
 
-## Verification
+### type checking
 
 ```sh
 bun run typecheck
-bun run lint
+```
+
+### testing
+
+```sh
 bun run test
-bun run test:browser
 ```
 
-The browser test requires Chromium. It uses Chrome's standard Windows installation by default; set `CHROME_PATH` for another installation. It creates a clean consumer without `monaco-editor`, checks its types with strict library checking, builds it with Vite and verifies actual requests and editor behavior in Chromium.
+## license
+
+[MIT License](https://github.com/Jaid/monacozen/raw/HEAD/license.txt)<br>
+Copyright © 2026, Jaid \<jaid.jsx@gmail.com> (https://github.com/jaid)
+
+<!---
+Readme generated with tldw v8.0.3 from ./docs/tldw
+https://github.com/Jaid/tldw
+-->

package/assets/{bat-C6DzPBcU.js → bat-T2vjbQzY.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.bun/monaco-editor@0.56.0/node_modules/monaco-editor/esm/vs/languages/definitions/bat/bat.js
+//#region node_modules/.bun/monaco-editor@0.57.0/node_modules/monaco-editor/esm/vs/languages/definitions/bat/bat.js
 var e = {
 	comments: { lineComment: "REM" },
 	brackets: [

package/assets/{clojure-D8WHGr6v.js → clojure-BvXzD8Uz.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.bun/monaco-editor@0.56.0/node_modules/monaco-editor/esm/vs/languages/definitions/clojure/clojure.js
+//#region node_modules/.bun/monaco-editor@0.57.0/node_modules/monaco-editor/esm/vs/languages/definitions/clojure/clojure.js
 var e = {
 	comments: { lineComment: ";;" },
 	brackets: [

package/assets/{coffee-C16Mnhbm.js → coffee-D_yet6sT.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.bun/monaco-editor@0.56.0/node_modules/monaco-editor/esm/vs/languages/definitions/coffee/coffee.js
+//#region node_modules/.bun/monaco-editor@0.57.0/node_modules/monaco-editor/esm/vs/languages/definitions/coffee/coffee.js
 var e = {
 	wordPattern: /(-?\d*\.\d\w*)|([^\`\~\!\@\#%\^\&\*\(\)\=\$\-\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g,
 	comments: {

package/assets/{cpp-_HbkGdoj.js → cpp-CsfEADPM.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.bun/monaco-editor@0.56.0/node_modules/monaco-editor/esm/vs/languages/definitions/cpp/cpp.js
+//#region node_modules/.bun/monaco-editor@0.57.0/node_modules/monaco-editor/esm/vs/languages/definitions/cpp/cpp.js
 var e = {
 	comments: {
 		lineComment: "//",

package/assets/{csharp-DeGXkEgi.js → csharp-jw3fFksF.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.bun/monaco-editor@0.56.0/node_modules/monaco-editor/esm/vs/languages/definitions/csharp/csharp.js
+//#region node_modules/.bun/monaco-editor@0.57.0/node_modules/monaco-editor/esm/vs/languages/definitions/csharp/csharp.js
 var e = {
 	wordPattern: /(-?\d*\.\d\w*)|([^\`\~\!\#\$\%\^\&\*\(\)\-\=\+\[\{\]\}\\\|\;\:\'\"\,\.\<\>\/\?\s]+)/g,
 	comments: {

package/assets/{css-DmO2GtiT.js → css-FsiUe-xI.js}

@@ -1,4 +1,4 @@
-//#region node_modules/.bun/monaco-editor@0.56.0/node_modules/monaco-editor/esm/vs/languages/definitions/css/css.js
+//#region node_modules/.bun/monaco-editor@0.57.0/node_modules/monaco-editor/esm/vs/languages/definitions/css/css.js
 var e = {
 	wordPattern: /(#?-?\d*\.\d\w*%?)|((::|[@#.!:])?[\w-?]+%?)|::|[@#.!:]/g,
 	comments: { blockComment: ["/*", "*/"] },