grapper-editor

# ![Grapper](./assets/img/grapper.png)<br/>Code editor web component ## `<g-editor>` A standalone code editor component that edits a `<grapper-view>` in real time and keeps its attributes/internal markup synchronized. ## Features * Inline editor with copy/save/reload/rearrange controls * Works against: * A `<grapper-view>` component (keeps attributes and content synchronized) * Inline code provided in the light DOM (comment node or `<textarea>`) * An `<iframe>`’s `document.body` * Read-only, show, and edit modes * Optional line highlighting * Theme switching (light/dark) * Diagnostics event stream for Grapper View validation ## Installation You can install the component via npm: ```bash npm install --save grapper-editor ``` Then import it in your app from CDN: ```html <script src="https://cdn.jsdelivr.net/npm/grapper-editor@1.0.0-beta.1/dist/editor.js"></script> ``` > The component registers as `<g-editor>`. ## Working with the Grapper view (`<grapper-view>`) When the `href` points at a `<grapper-view>`, the editor switches to **composer mode**: ```html <grapper-view id="composer"></grapper-view> <g-editor title="Composer" href="#composer" mode="edit"></g-editor> ``` In composer mode: * The edited markup is applied to the composer’s **inner content**. * All **attributes** on the composer are kept in sync (added/removed/updated) to match the edited source. * Diagnostics will be computed against the live `<grapper-view>` and surfaced via the `diagnostic` event and the built-in panel (if your provider UI shows it). ## Inline content You can provide the initial code as a comment node or a `<textarea>` in the light DOM: ```html <g-editor title="My template" mode="edit">  </g-editor> ``` Or: ```html <g-editor title="My template" mode="edit"> <textarea> <svg width="300" height="80"> <text x="10" y="40">Hello Graphane!</text> </svg> </textarea> </g-editor> ``` ## Editing an existing element with `href` Point the editor at any element in the same document (or an `<iframe>`): ```html <div id="preview"></div> <g-editor title="Section editor" href="#preview" mode="edit"></g-editor> ``` * If `href` targets an `<iframe>`, the editor waits for it to load and uses its `contentDocument.body`. * When you edit, the target element’s `innerHTML` is updated in real time. ## Attributes | Attribute | Type | Default | Description | |-------------------|-----------|-----------|--------------------------------------------------------------------------------------------------------------------| | `title` | `string` | `""` | UI title displayed in the editor header. | | `href` | `string` | `""` | CSS selector for the element to edit. Supports elements and `<iframe>`. When empty, uses inline light-DOM content. | | `keep-format` | `boolean` | `false` | Preserve original formatting when re-loading code into the model. | | `options` | `object` | `{}` | Editor/model options (pass JSON string in HTML; a plain object when set programmatically). | | `theme` | `string` | `"light"` | Editor theme. Set to `"dark"` for dark mode. Also responds to a global `themeChanged` event (see **Theming**). | | `mode` | `string` | `"show"` | One of: `"readonly"`, `"show"`, `"edit"`. Controls editability and which header actions are visible. | | `lines-highlight` | `string` | `""` | Line ranges to highlight (e.g. `"1-3;8;12-14"`). See **Line highlighting**. | > All attributes are reactive and can be changed at runtime. ## Line highlighting Use `lines-highlight` with a semicolon-separated list of single lines or inclusive ranges: * Single lines: `5` * Ranges: `10-15` * Combined: `1-3;5;12-14` The string is parsed into numeric lines and applied by the editor provider. ## UI & header actions Depending on `mode`, the header shows: * **Edit / Show** toggles * **Reload** — discard unsaved edits and restore the original code * **Rearrange** — re-parse and re-format the current code using the model’s loader * **Copy** — copy current code to clipboard * **Save** — trigger a download of the current code (uses the provided `saveFile` helper) > In `readonly` mode, all editing controls are hidden and the editor is non-editable. ## Events ### `diagnostic` Emitted whenever diagnostics are computed (typically after edits), especially useful with `<grapper-view>`. ```js const editor = document.querySelector('g-editor'); editor.addEventListener('diagnostic', (evt) => { // evt.detail is the diagnostic payload produced by your diagnostic pipeline console.log('Diagnostic:', evt.detail); }); ``` Perfect — with that `BASE.md` content I can now integrate the **public events from grapper-core** into the README for `<g-editor>`. Here’s the **updated README** section with the **public events** clearly documented. ### Lifecycle Events These are automatically emitted during the component's lifecycle: | Event | When it fires | | ------------- | --------------------------------------------------------------------------- | | **`ready`** | When the component has been instantiated and its constructor has run. | | **`render`** | After the component has built its initial UI structure in the shadow DOM. | | **`refresh`** | After the component has updated its content without a full re-render. | | **`update`** | Each time the component’s content is updated (may fire multiple times). | ## Programmatic API Access the component instance and call methods/properties directly: ```js const editor = document.querySelector('g-editor'); // Read or replace the entire code buffer console.log(editor.code); editor.code = '<svg><text>Hello</text></svg>'; // Update without changing "original" snapshot editor.update('<div>New content</div>'); // Is the buffer different from the original snapshot? if (editor.isChanged) { // Revert to original snapshot await editor.discardChanges(); } // Re-parse/normalize current code via the model await editor.rearrange(); // Utilities await editor.toClipboard(); await editor.toDisk(); // triggers a file save editor.resetChange(); // sets "original" = current buffer ``` **Properties** * `code: string` — get/set current buffer * `isChanged: boolean` — whether `code` differs from the original snapshot captured on load or after `resetChange()` **Methods (async when noted)** * `update(v: string): Promise<void>` * `discardChanges(): Promise<void>` * `rearrange(): Promise<void>` * `toClipboard(): Promise<void>` * `toDisk(): Promise<void>` * `resetChange(): void` ## Theming Set `theme="light"` or `theme="dark"` directly, or broadcast a global theme change: ```js document.documentElement.dispatchEvent( new CustomEvent('themeChanged', {detail : {theme : 'dark'}}) ); ``` The editor listens for `themeChanged` on `document.documentElement` and updates itself. ## Examples ### 1) Grapper View ```html <grapper-view id="chart"> <tempplate> <svg viewBox="0 0 200 100" width="200px" height="100px"> <g stroke-width="12" stroke-linecap="round"> <g g-for="(record, index) of data"> <line x1="22" :x2="record.value" :y1="index * 20 + 30" :y2="index * 20 + 30" :stroke="record.color" ></line> </g> </g> </svg> </tempplate> <script type="data"> [ {"color": "#D80000", "value": 130}, {"color": "#00D800", "value": 170}, {"color": "#0000D8", "value": 100} ] </script> </grapper-view> <g-editor title="Basic example" href="#chart"></g-editor> ``` ### 2) Read-only viewer ```html <g-editor title="Spec preview" mode="readonly" lines-highlight="1-5;12">  </g-editor> ``` ### 3) Editing inside an iframe ```html <iframe id="sandbox" src="/playground.html"></iframe> <g-editor title="Iframe body editor" href="#sandbox" mode="edit"></g-editor> ``` ## Tips & gotchas * `keep-format` helps preserve the original formatting when re-loading code into the model. If you prefer normalized output, leave it `false`. * If your `href` selector doesn’t match anything, the editor logs an error and renders nothing. * For `<grapper-view>`, both **attributes** and **inner content** are source-of-truth from the editor; manual changes to the live element may be overwritten by subsequent edits.