fix: remove z-index usage (#32)

* fix: remove z-index usage

Signed-off-by: Steven E Wright <StevenEWright@users.noreply.github.com>

* fix: half-baked documentation

Signed-off-by: Steven E Wright <StevenEWright@users.noreply.github.com>

---------

Signed-off-by: Steven E Wright <StevenEWright@users.noreply.github.com>

QUICK_START.md

@@ -4,43 +4,8 @@
 
 ### _css_
 
-```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.8.0/build/styles/base16/solarized-dark.min.css"
-/>
-```
-
-### _js_
-
-```html
-<script src="https://cdn.jsdelivr.net/npm/@kullna/editor/dist/kullna-editor.min.js"></script>
-<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.8.0/build/highlight.min.js"></script>
-```
-
-### _html_
-
-```html
-<div id="editor"></div>
-```
-
-### _init_
-
-```js
-const editor = KullnaEditor.createEditor('#editor', {
-  language: 'javascript',
-  highlightElement: hljs.highlightElement
-});
-editor.spellcheck = false;
-editor.code = 'print("Hello, world!")';
-```
-
-💡 **Tip:** Check out the other options in the [Documentation](/interfaces/Options.html).
-
-## Styling
-
 We recommend the use of the [Source Code Pro](https://fonts.google.com/specimen/Source+Code+Pro)
-font for the editor. You can include it in your page like this:
+font for the editor.
 
 ```html
 <link
@@ -49,8 +14,8 @@ font for the editor. You can include it in your page like this:
 />
 ```
 
-We are also partial to Highlight.js's Solarized Dark theme for syntax highlighting. You can include
-it in your page like this:
+And Highlight.JS's Solarized Dark
+[Theme](https://github.com/highlightjs/highlight.js/tree/main/src/styles):
 
 ```html
 <link
@@ -59,76 +24,104 @@ it in your page like this:
 />
 ```
 
-Finally, we like the following styles for a small embedded editor. This example gives you a good
-starting point for customizing the editor to your needs:
+And we'll style our editor DIV to look nice, and use an appropriate font for a code editor:
 
 ```html
 <style>
-  .editor {
-    border-radius: 6px;
+  #editor {
+    position: relative;
+    min-height: 480px;
+    min-width: 640px;
+
+    background-color: #073642;
+
     font-family: 'Source Code Pro', monospace;
-    font-size: 14px;
-    font-weight: 400;
-    min-height: 240px;
+    font-size: 12px;
     line-height: 20px;
-  }
 
-  .editor > div {
-    padding: 10px;
+    border-radius: 10px;
   }
 
-  .gutter {
+  #editor .gutter {
     background-color: #002b36;
-    color: #839496;
+    border-color: #93a1a1;
+    color: #93a1a1;
   }
 </style>
 ```
 
-## Use with Highlight.js
+### _js_
 
-### _css_
+We can get @kullna/editor and Highlight.JS from JSDelivr:
 
 ```html
-<link
-  rel="stylesheet"
-  href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.8.0/build/styles/base16/solarized-dark.min.css"
-/>
+<script src="https://cdn.jsdelivr.net/npm/@kullna/editor/dist/kullna-editor.min.js"></script>
+<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.8.0/build/highlight.min.js"></script>
 ```
 
-### _js_
+### _html_
+
+We need the element to hold the editor in the DOM:
 
 ```html
-<script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.8.0/build/highlight.min.js"></script>
+<div id="editor"></div>
 ```
 
 ### _init_
 
+Initialize the editor, and set your options:
+
 ```js
-const editor = KullnaEditor.createEditor(editorElement, {
+const editor = KullnaEditor.createEditor('#editor', {
   language: 'javascript',
-  highlightElement: hljs.highlightElement
+  // This tells the editor to use Highlight.JS for syntax highlighting:
+  highlightElement: hljs.highlightElement,
+  // This tells the editor to show a gutter with line numbers and a border:
+  gutter: {
+    border: true,
+    class: 'gutter'
+  }
 });
+// Warning! Disabling spellcheck will disable spellcheck for the entire page.
+editor.spellcheck = false;
 ```
 
-## Use with Prism.js
+Set the code in the editor:
 
-### _css_
+```js
+editor.code = 'print("Hello, world!")';
+```
 
-```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism.min.css" />
+Get notified when the code changes:
+
+```js
+editor.onUpdate(code => {
+  console.log('Code updated:', code);
+});
 ```
 
-### _js_
+Print code on demand:
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/prism.min.js"></script>
+```js
+console.log(editor.code);
 ```
 
-### _init_
+Create a highlight:
 
 ```js
-const editor = KullnaEditor.createEditor(editorElement, {
-  language: 'javascript',
-  highlightElement: Prism.highlightElement
-});
+const highlight = editor.createHighlight();
+highlight.cssClass = 'highlight';
+highlight.lineNumber = 1;
+highlight.visible = true;
 ```
+
+💡 **Tip:** Check out the other options in the [Documentation](/interfaces/Options.html). Also,
+check out [Processors](/modules/Processors.html) for handling keyboard events.
+
+---
+
+The Kullna Editor source, artifacts, and website content are **Copyright (c) 2023
+[The Kullna Programming Language Project](https://www.kullna.org/).**
+
+They are free to use and open-source under the terms of the
+[GNU Lesser General Public License](https://www.gnu.org/licenses/lgpl-3.0).

demo.html

@@ -63,6 +63,7 @@
       }
 
       .editor {
+        position: relative;
         background-color: var(--sd-base02);
         border-radius: 10px;
         box-shadow:

src/index.ts

@@ -71,12 +71,21 @@ const DEFAULT_TAB_CHARACTERS = '  ';
  * Here is a typical example of how to create an editor:
  *
  * ```js
- * const editor = KullnaEditor.createEditor('#editor', {
+ * import {createEditor} from '@kullna/editor';
+ *
+ * const editor = createEditor('#editor', {
  *   language: 'javascript',
- *   highlightElement: hljs.highlightElement
+ *   // This tells the editor to use Highlight.JS for syntax highlighting:
+ *   highlightElement: hljs.highlightElement,
+ *   // This tells the editor to show a gutter with line numbers and a border:
+ *   gutter: {
+ *     border: true,
+ *     class: 'gutter'
+ *   }
  * });
+ * // Warning! Disabling spellcheck will disable spellcheck for the entire page.
  * editor.spellcheck = false;
- * editor.code = 'console.log("Hello, world!");';
+ * editor.wrapsText = true;
  * ```
  *
  * For a list of features and options you can change after creating the editor, see the
@@ -159,6 +168,9 @@ export function createEditor(
   if (options.gutter) {
     editorOptions.gutter = options.gutter;
   }
+  if (options.language) {
+    editorOptions.language = options.language;
+  }
 
   return new Editor(parent, editorOptions);
 }

src/internals/editor.ts

@@ -87,11 +87,12 @@ export class Editor
     };
     this.options = options;
 
-    parent.style.position = 'relative';
+    this.undoRedoManager = new UndoRedoManager(this);
+
     parent.style.overflow = 'hidden';
     parent.dir = options.dir;
 
-    this.highlightView = new HighlightView(parent, 99);
+    this.view = new TextEditorView(options.window, parent, this);
 
     if (options.gutter) {
       // Default gutter options if not specified:
@@ -102,12 +103,20 @@ export class Editor
       // Construct the gutter element
       const gutter = new Gutter(options.gutter);
       this.gutter = gutter;
-      parent.appendChild(gutter.element);
+      parent.insertBefore(gutter.element, this.view.contentEditableSurface);
       gutter.dir = options.dir;
     }
 
-    this.undoRedoManager = new UndoRedoManager(this);
-    this.view = new TextEditorView(options.window, parent, this);
+    const highlightViewContainer = this.options.window.document.createElement('div');
+    highlightViewContainer.style.position = 'absolute';
+    highlightViewContainer.style.top = '0';
+    highlightViewContainer.style.left = '0';
+    highlightViewContainer.style.right = '0';
+    highlightViewContainer.style.bottom = '0';
+    highlightViewContainer.style.overflow = 'hidden';
+    parent.insertBefore(highlightViewContainer, this.view.contentEditableSurface);
+    this.highlightView = new HighlightView(highlightViewContainer);
+
     this.view.gutterWidth = this.gutter ? this.gutter.width : '0px';
     this.view.spellchecking = options.spellcheck;
     this.view.dir = options.dir;

src/internals/gutter/docs_index.ts

@@ -21,17 +21,8 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>. */
  * the DOM elements within the gutter. This approach anticipates future optimization
  * where we aim to manage gutter elements more efficiently by reusing them, rather than
  *  creating new ones every time the line count in the editor changes. This strategy
- * requires the editor to have complete control over these gutter elements. Presently,
- * the gutter also determines the line's location within the editor, crucial for line
- * numbers and highlighting - however, this source of truth will shift to the internals
- * of the selection bridge in the future, as it knows the line's location within the
- * editor already, and defininitively.
- *
- * Currently line highlighting is handled by the gutter, but this will change in the future
- * when we have a better, more flexible, and more performant way of tracking line heights
- * and positions.
+ * requires the editor to have complete control over these gutter elements.
  */
-
 export {GutterLineElement} from './line';
 export {GutterCustomizer} from './customizer';
 export {Gutter} from './gutter';

src/internals/gutter/gutter.ts

@@ -148,7 +148,6 @@ export class Gutter {
     };
     this.element = document.createElement('div');
     this.element.style.position = 'absolute';
-    this.element.style.zIndex = '50';
     this.element.style.top = '0px';
     this.element.style.bottom = '0px';
     this.element.style.overflow = 'hidden';

src/internals/gutter/index.ts

@@ -30,28 +30,38 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>. */
  * and border colors:
  *
  * ```css
- * background-color: #f0f0f0;
- * border-color: #d0d0d0;
- * color: #606060;
+ * #editor .gutter {
+ *   background-color: #002b36;
+ *   border-color: #93a1a1;
+ *   color: #93a1a1;
+ * }
  * ```
  *
- * ### JavaScript Customization
+ * Set the class the gutter uses by providing a `class` option to {@link Options.gutter}:
  *
- * Beyond CSS, you can modify the gutter using JavaScript. This is achieved by providing a `GutterCustomizer` to the `renderGutterLine` option within {@link Options.gutter}. This function lets you modify the `GutterLineElement` in the DOM, facilitating additions like breakpoints and other gutter features.
+ * ```js
+ * const editor = createEditor('#editor', {
+ *   gutter: {
+ *     class: 'gutter'
+ *   }
+ * });
+ * ```
+ *
+ * To customize the width of the gutter, use the Javascript API:
  *
- * For additional details, refer to {@link GutterCustomizer}.
+ * ```js
+ * const editor = createEditor('#editor', {
+ *   gutter: {
+ *     width: '100px'
+ *   }
+ * });
+ * ```
+ *
+ * ### JavaScript Customization
  *
- * ## Development Notes
+ * Beyond CSS, you can modify the gutter using JavaScript. This is achieved by providing a `GutterCustomizer` to the `renderGutterLine` option within {@link Options.gutter}. This function lets you modify the `GutterLineElement` in the DOM, facilitating additions like breakpoints and other gutter features.
  *
- * 💡 **Note:** **Management by `@kullna/editor`**: The editor handles creating and maintaining
- *  the DOM elements within the gutter. This approach anticipates future optimization
- * where we aim to manage gutter elements more efficiently by reusing them, rather than
- *  creating new ones every time the line count in the editor changes. This strategy
- * requires the editor to have complete control over these gutter elements. Presently,
- * the gutter also determines the line's location within the editor, crucial for line
- * numbers and highlighting - however, this source of truth will shift to the internals
- * of the selection bridge in the future, as it knows the line's location within the
- * editor already, and defininitively.
+ * For additional details, including examples, refer to {@link GutterCustomizer}.
  */
 
 export {GutterLineElement} from './line';

src/internals/highlights/highlight.ts

@@ -30,6 +30,24 @@ along with this program.  If not, see <https://www.gnu.org/licenses/>. */
  *
  * Set the visibility of the highlight with `highlight.visible` (see: {@link Highlight.visible}).
  * This will show or hide the highlight.
+ *
+ * ## Example
+ *
+ * ```js
+ * const highlight = editor.createHighlight();
+ * highlight.cssClass = 'highlight';
+ * highlight.lineNumber = 1;
+ * highlight.visible = true;
+ * ```
+ *
+ * ## Example CSS:
+ *
+ * ```css
+ * .highlight {
+ *   /* semi-transparent yellow highlight * /
+ *   background-color: #b5890066;
+ * }
+ * ```
  */
 export interface Highlight {
   /** The line number to highlight. */