tosijs-styled-editor 0.4.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Tonio Loewald
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,387 @@
+<!--{ "pin": "top" }-->
+
+# A Rich Text Editor Component
+
+```html
+<tosijs-styled-editor widgets="default" localized>
+  <h2>Try it</h2>
+  <p>This is a live editor. Click anywhere to place the cursor and start typing,
+  then use the menus and toolbar above to format what you write. The 🇬🇧 menu
+  switches the interface to Suomi.</p>
+  <p>Double-click selects a word, triple-click selects a block, and clicking past
+  the end of a line puts the cursor at the end of that line.</p>
+  <ul>
+    <li>Select these two items</li>
+    <li>Press the numbered-list button to renumber them</li>
+  </ul>
+</tosijs-styled-editor>
+```
+
+```css
+tosijs-styled-editor {
+  --editor-ink: #27488c;
+}
+```
+
+A pure web-component. What it does **not** use:
+
+- No `document.execCommand`
+- No `contentEditable`
+- No horrible browser selection and Range APIs
+
+What you get instead:
+
+- Fully styleable selections
+- Exact control over editing behavior
+- Exact control over cursor behavior
+- Touch-friendly selection
+
+## Development
+
+```bash
+bun install
+bun run tls     # once — locally-trusted dev certs (needs mkcert)
+bun start       # dev server + doc site on https://localhost:8789
+bun test        # unit tests
+bun run lint    # typecheck, including unused locals/params
+bun run format  # Prettier
+bun run make    # full build (NOT `bun run build` — `bun build` is a Bun builtin)
+```
+
+`bin/site.ts` is the only build/dev entry; it wraps tosijs-ui's doc system and
+is configured in `tosijs-editor-site.config.ts`.
+
+Live site and docs: <https://editor.tosijs.net>
+
+## Installation
+
+```bash
+npm install tosijs-styled-editor
+```
+
+Peer dependencies: `tosijs`, `tosijs-ui`
+
+## Usage
+
+Drop it in and it is editable. `widgets` picks a built-in toolbar preset —
+`none` (the default), `minimal`, or `default` (toolbar + menus), as in the
+example above.
+
+```xml
+<tosijs-styled-editor widgets="default">
+  <p>Edit this text!</p>
+  <p>It supports <b>bold</b>, <i>italic</i>, and more.</p>
+</tosijs-styled-editor>
+```
+
+The whole chrome is mixed from one custom property, so re-theming is a single
+value:
+
+```xml
+<style>
+  tosijs-styled-editor { --editor-ink: #27488c; }
+</style>
+```
+
+### Setting up toolbars and menus
+
+```typescript
+import { tosijsStyledEditor, type TosijsStyledEditor } from 'tosijs-styled-editor'
+import { defaultToolbar, defaultMenubar } from 'tosijs-styled-editor'
+
+const editor = tosijsStyledEditor() as TosijsStyledEditor
+editor.value = '<p>Hello world</p>'
+document.body.appendChild(editor)
+
+// Add menus (slot="menubar")
+for (const menu of defaultMenubar(editor)) {
+  editor.appendChild(menu)
+}
+
+// Add toolbar buttons (slot="toolbar")
+for (const widget of defaultToolbar()) {
+  widget.setAttribute('slot', 'toolbar')
+  editor.appendChild(widget)
+}
+```
+
+## How It Works
+
+The editor uses three layers:
+
+1. **DOM utilities** (`dom-utils.ts`) — leaf-node traversal; nearly all operations work with leaf nodes
+2. **Selection** (`selection.ts`) — custom selection via "spanification" (wrapping characters in `<span>` elements to determine exact positions without browser APIs)
+3. **Commands** (`commands.ts`) — extensible command system for formatting and editing
+
+The caret is an `<input>` element, so mobile browsers show their keyboard automatically.
+
+## Keyboard Behavior
+
+### General editing
+
+| Key                                | Action                                                       |
+| ---------------------------------- | ------------------------------------------------------------ |
+| **Typing**                         | Inserts character at caret; replaces selection if any        |
+| **Backspace**                      | Deletes character before caret, or deletes selection         |
+| **Delete**                         | Deletes character after caret, or deletes selection          |
+| **Enter**                          | Splits the current block at the caret                        |
+| **ArrowLeft / ArrowRight**         | Moves caret one character                                    |
+| **ArrowUp / ArrowDown**            | Moves caret one visual line, maintaining horizontal position |
+| **Alt+ArrowLeft / Alt+ArrowRight** | Moves caret one word                                         |
+| **Shift+Arrow**                    | Extends selection                                            |
+
+### Mouse selection
+
+| Action           | Selects                             |
+| ---------------- | ----------------------------------- |
+| **Click**        | Places caret at character position  |
+| **Shift+Click**  | Extends selection to click position |
+| **Double-click** | Selects word                        |
+| **Triple-click** | Selects block                       |
+| **Click-drag**   | Selects character range             |
+
+### Inside a table cell
+
+| Key                    | Action                                                           |
+| ---------------------- | ---------------------------------------------------------------- |
+| **Tab**                | Move to next cell; at last cell, creates a new row               |
+| **Shift+Tab**          | Move to previous cell                                            |
+| **ArrowDown**          | Move to cell below; at last row, exit table downward             |
+| **ArrowUp**            | Move to cell above; at first row, exit table upward              |
+| **Shift+Enter**        | Move to cell below (same column); at last row, creates a new row |
+| **Shift+ArrowDown**    | Same as Shift+Enter                                              |
+| **Enter**              | Insert line break (`<br>`) within the cell                       |
+| **Backspace / Delete** | Delete within cell only (won't escape the cell)                  |
+
+### Inside a list item (`<ul>/<ol>`)
+
+| Key           | Action                                                                 |
+| ------------- | ---------------------------------------------------------------------- |
+| **Enter**     | Split into a new list item; if item is empty, exit the list as a `<p>` |
+| **Backspace** | Delete within item; at start, merge with previous item or exit list    |
+| **Delete**    | Delete within item; at end, merge with next item                       |
+
+### Keyboard shortcuts
+
+Shortcuts are defined by toolbar buttons via `data-shortcut` attributes. The default toolbar provides:
+
+| Shortcut       | Action    |
+| -------------- | --------- |
+| **Ctrl/Cmd+B** | Bold      |
+| **Ctrl/Cmd+I** | Italic    |
+| **Ctrl/Cmd+U** | Underline |
+| **Ctrl/Cmd+Z** | Undo      |
+| **Ctrl/Cmd+Y** | Redo      |
+
+## Commands
+
+Commands are invoked via `editor.doCommand(commandString)`. Multiple commands
+can be chained with semicolons.
+
+### Character styling — `setText`
+
+Applies CSS to selected characters:
+
+```
+setText font-weight bold
+setText font-style italic
+setText text-decoration underline
+setText background-color rgba(255,255,64,0.5)
+setText font-family Helvetica
+setText font-size 18px
+```
+
+Use `+` for spaces in values: `setText font-family Times+New+Roman`
+
+### Block type — `setBlockType`
+
+Changes the element type of selected blocks:
+
+```
+setBlockType h1
+setBlockType p
+setBlockType pre
+setBlockType blockquote
+```
+
+### Block styling — `setBlocks`
+
+Applies CSS to selected blocks:
+
+```
+setBlocks text-align center
+setBlocks margin-left 40px
+setBlocks line-height 2.5
+```
+
+### Drag and drop
+
+Selected text becomes a real draggable object — spanification means the
+selection is made of elements, which is exactly what HTML5 drag and drop wants,
+so dragging works between windows, between browsers, and to and from the
+desktop with no extra machinery.
+
+Every drag offers **both representations**, and the receiver picks:
+
+| type         | what it gets      |
+| ------------ | ----------------- |
+| `text/html`  | the styled markup |
+| `text/plain` | clean text        |
+
+- **Move within the editor, Alt to copy.**
+- **Leaving the editor is always a copy.** The source is only deleted by this
+  editor's own drop handler, so text dragged into another app is never removed
+  from a document you can no longer see.
+- **The drop indicator IS the caret.** Since the editor owns its caret, the
+  thing showing where text will land is the thing that receives it.
+- Dropped **image files** are read in as data URIs; dropped HTML goes through
+  the same `pastemode` normalisation as a paste, so dropping and pasting the
+  same content produce the same document.
+
+The editor declares `data-drop="text/html;text/plain;Files;image/*"` and each
+selected element `data-drag="text/html;text/plain"`, matching the conventions
+`tosijs-ui`'s drag library uses to mark compatible drop zones.
+
+### Links, images and footnotes
+
+```
+setLink https://example.com          # wraps the selection; opens in a new tab
+setLink https://example.com _self    # same tab
+setLink https://example.com pane     # a named target
+removeLink                           # unwrap, keeping the text
+insertImage https://host/cat.png A cat
+insertFootnote optional initial text
+renumberFootnotes                    # recompute after editing by hand
+```
+
+Links default to `target="_blank"` and get `rel="noopener"` with it — without
+that, the opened page receives a live `window.opener` reference back to yours.
+Pass `_self` to clear both.
+
+Footnote **numbers are never stored**; they are derived from document order, so
+inserting one in the middle renumbers the rest and reorders the list to match.
+Deleting a marker drops its entry on the next renumber, and deleting the last
+one removes the list. The stable identity is `data-footnote`, not the number.
+
+Inside the editor a link is text you are editing, so clicking it places the
+caret rather than navigating. Ctrl/Cmd-click follows it.
+
+### Table commands
+
+```
+insertTable 3              # 3 columns, 2 rows (1 header)
+insertTable 4 5 1          # 4 columns, 5 rows, 1 header row
+insertTableRow after       # Insert row after current
+insertTableRow before      # Insert row before current
+insertTableCol after       # Insert column after current
+insertTableCol before      # Insert column before current
+deleteTableRow             # Delete current row
+deleteTableCol             # Delete current column
+toggleHeaderRow            # Toggle header styling on current row
+```
+
+Column widths can be resized by dragging cell borders.
+
+### Other commands
+
+```
+updateUndo undo
+updateUndo redo
+setDebug                   # Toggle debug visualization
+annotate note              # Insert annotation at caret
+```
+
+## Tables
+
+Tables use CSS Grid layout instead of `<table>` elements:
+
+```xml
+<ul class="editor-table" style="grid-template-columns: 1fr 1fr 1fr">
+  <li class="table-header">Name</li>
+  <li class="table-header">Role</li>
+  <li class="table-header">Location</li>
+  <li>Alice</li>
+  <li>Engineer</li>
+  <li>New York</li>
+</ul>
+```
+
+## Extending the editor
+
+Add custom commands by extending `editor.commands`:
+
+```typescript
+editor.commands.myCommand = (ctx, ...args) => {
+  // ctx provides: root, selectable, commands, find(), findAll(),
+  //   selectedLeafNodes(), selectedBlocks(), insertionPoint(),
+  //   block(), normalize(), focus(), updateUndo()
+  const nodes = ctx.selectedLeafNodes()
+  // ... manipulate nodes ...
+  ctx.updateUndo('new')
+}
+
+editor.doCommand('myCommand arg1 arg2')
+```
+
+## Localization
+
+Add `localized` and the built-in widgets translate themselves, with a flag-only
+language picker in the menubar:
+
+```xml
+<tosijs-styled-editor widgets="default" localized></tosijs-styled-editor>
+```
+
+Strings live in one tab-separated table, `localized-strings.tsv`. **To add a
+language, add a column** — nothing else changes:
+
+```
+en	fi
+(row 1 is ignored — notes go here)
+English	Suomi
+🇬🇧	🇫🇮
+Bold	Lihavointi
+Italic	Kursivointi
+```
+
+Row 0 is the locale codes, row 2 the language names, row 3 the flag emoji, and
+every row after that is one string. **Column 0 is both the lookup key and the
+English text**, so a missing cell or a missing row falls back to English rather
+than showing a key — you can ship a half-translated column safely. A `"` cell
+means "same as English", which is what proper nouns and numerals use.
+
+Load it once at startup:
+
+```typescript
+import { initLocalization } from 'tosijs-ui'
+
+initLocalization(await (await fetch('/localized-strings.txt')).text())
+```
+
+A doc site built on `tosijs-ui/site` does this for you — pass the table as
+`localizedStrings` in the site config.
+
+Under the hood this is tosijs-ui's convention, not a private one: buttons carry
+`data-tosi-localized` (a JSON map of attribute to key, re-applied on locale
+change), menus set `localized`, and menu labels are `<tosi-localized>` elements.
+Custom widgets you add follow the same rules and get translated too.
+
+## Component API
+
+| Property    | Type                                                | Description                                                           |
+| ----------- | --------------------------------------------------- | --------------------------------------------------------------------- |
+| `value`     | `string`                                            | Get/set the editor content as HTML                                    |
+| `active`    | `boolean`                                           | Enable/disable editing                                                |
+| `pastemode` | `'merge' \| 'remove' \| 'preserve' \| 'paragraphs'` | How pasted HTML is handled                                            |
+| `commands`  | `object`                                            | Command registry (extend to add custom commands)                      |
+| `widgets`   | `'none' \| 'minimal' \| 'default'`                  | Attribute — built-in toolbar preset                                   |
+| `localized` | `boolean`                                           | Attribute — translate the built-in widgets and show a language picker |
+
+| Method           | Description              |
+| ---------------- | ------------------------ |
+| `doCommand(str)` | Execute a command string |
+| `focus()`        | Focus the caret          |
+
+## License
+
+Apache-2.0

package/dist/commands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Command system for tosijs-styled-editor.
+ *
+ * Commands are the interface between the toolbar/keyboard and
+ * the editing engine. Each command is a method that receives
+ * the editable context and arguments parsed from the command string.
+ */
+import type { Selectable } from './selection';
+/** A command implementation */
+export type Command = (ctx: EditableContext, ...args: string[]) => void;
+/** Context passed to every command */
+export interface EditableContext {
+    root: HTMLElement;
+    selectable: Selectable;
+    /**
+     * The command registry `executeCommand` resolves names against.
+     * Omitted contexts fall back to the built-in `commands`.
+     */
+    commands?: Record<string, Command>;
+    find(selector: string): Element | null;
+    findAll(selector: string): Element[];
+    selectedLeafNodes(): Node[];
+    selectedBlocks(): Element[];
+    insertionPoint(): HTMLInputElement | null;
+    block(node: Node): Element | null;
+    normalize(): void;
+    focus(): void;
+    updateUndo(command?: string, reason?: string): void;
+}
+/** Parse a "key value key value" argument list into a CSS object */
+export declare function makeCSS(args: string[]): Record<string, string> | null;
+/**
+ * Renumber footnotes from DOCUMENT ORDER and reorder the list to match.
+ *
+ * Numbers are never stored — they are derived here — so inserting a footnote
+ * in the middle renumbers everything after it, and deleting a marker drops its
+ * entry. The stable identity is `data-footnote`, not the number.
+ */
+export declare function renumberFootnotes(root: HTMLElement): void;
+/** Command definitions — extensible by adding new methods */
+export declare const commands: Record<string, Command>;
+/**
+ * Parse and execute a command string.
+ * Supports chained commands separated by semicolons.
+ * Example: "setText font-weight bold; setBlockType h2"
+ */
+export declare function executeCommand(ctx: EditableContext, commandString: string): void;