vuehex 0.5.8 → 0.6.1

package/README.md

@@ -1,10 +1,15 @@
 # VueHex
 
-VueHex is a fast, virtualized hex viewer component for Vue 3. It can be used both for cleanly displaying binary data and for efficiently viewing very large datasets.
+[![Live Demo](https://img.shields.io/badge/Live_Demo-2da44e?style=for-the-badge)](https://vvollers.github.io/vuehex/demo/)
+[![Documentation](https://img.shields.io/badge/Documentation-0969da?style=for-the-badge)](https://vvollers.github.io/vuehex/docs/)
+
+## Description
+
+VueHex is a fast, virtualized hex viewer/editor component for Vue 3. It can be used both for cleanly viewing and editing binary data and for efficiently handling very large datasets.
 
 * No dependencies
-* Small package (~64KB minimized / ~15KB zipped)
-* Render local and remote data
+* Small package (~72KB minimized / ~18KB zipped)
+* Render any local or remote data
 * Can handle extremely large data sizes
 * Very flexible and themeable, can be as simple or as complicated as you wish
 
@@ -16,7 +21,7 @@ VueHex is a fast, virtualized hex viewer component for Vue 3. It can be used bot
 npm install vuehex
 ```
 
-Optionally register the plugin once to make the `<VueHex>` component available everywhere and load the bundled styles:
+Register the plugin once to make the `<VueHex>` component available everywhere and load the bundled styles:
 
 ```ts
 import { createApp } from "vue";
@@ -68,6 +73,7 @@ const windowData = ref(backingFile.slice(0, 16 * 48));
 | `statusbar` | `null` | Status bar placement: `'top'`, `'bottom'`, or `null` to hide. Shows byte info on hover and selection details. |
 | `statusbarLayout` | — | Configuration object controlling which items appear in the status bar and their placement (`left`, `middle`, `right` sections). |
 | `cursor` | `false` | Enable keyboard/click cursor navigation. Navigate with arrow keys when focused or click bytes to move cursor. |
+| `editable` | `false` | Enable editor mode. Typing/paste/cut emit `edit` intents. Cursor is automatically enabled while editing. |
 
 ## Models
 
@@ -86,12 +92,101 @@ VueHex emits several events to enable interactive features:
 | Event | Payload | Description |
 |-------|---------|-------------|
 | `updateVirtualData` | `{ offset: number, length: number }` | Emitted when the component needs more data in windowed mode. Load the requested byte range and update `v-model` with the new data. |
+| `edit` | `VueHexEditIntent` | Emitted when `editable` is enabled and the user types, deletes, pastes, or cuts. In windowed mode, the parent should apply the intent to the backing store and refresh `v-model`. |
 | `byte-click` | `{ index: number, byte: number, kind: 'hex' \| 'ascii' }` | Emitted when a user clicks on a specific byte cell. `index` is the absolute byte position, `byte` is the value (0-255), and `kind` indicates whether the hex or ASCII column was clicked. |
 | `selection-change` | `{ start: number \| null, end: number \| null, length: number }` | Emitted when the selection range changes. `start` and `end` are absolute byte positions (inclusive), or `null` if nothing is selected. `length` is the number of selected bytes. |
 | `row-hover-on` / `row-hover-off` | `{ offset: number }` | Emitted when hovering over/leaving a row. |
 | `hex-hover-on` / `hex-hover-off` | `{ index: number, byte: number }` | Emitted when hovering over/leaving a hex cell. |
 | `ascii-hover-on` / `ascii-hover-off` | `{ index: number, byte: number }` | Emitted when hovering over/leaving an ASCII cell. |
 
+## Editable mode
+
+Set `editable` to turn VueHex into a hex editor. VueHex emits a single `edit` event describing user intent.
+
+Editing highlights:
+
+- Click hex vs ASCII to choose the active column (or press `Tab` to toggle).
+- Press `Insert` to toggle insert/overwrite mode.
+- Hex typing commits after two nibbles.
+- Selection integrates with editing: typing/paste replaces the selection; `Delete`/`Backspace` delete the selection.
+- Clipboard shortcuts:
+    - `Ctrl/Cmd+C` copy selection
+    - `Ctrl/Cmd+V` paste (hex column treats clipboard as hex bytes; whitespace is ignored)
+    - `Ctrl/Cmd+X` cut (copy + delete selection)
+- Undo/redo shortcuts:
+    - `Ctrl/Cmd+Z` undo
+    - `Ctrl/Cmd+Y` redo (also `Ctrl/Cmd+Shift+Z`)
+
+### Buffer mode (self-managed)
+
+In `data-mode="buffer"`, VueHex will apply edits to `v-model` automatically. Listening to `@edit` is optional.
+
+Undo/redo is built-in in this mode and is implemented as a compact history of edit diffs (not full buffer snapshots).
+
+```vue
+<template>
+    <VueHex v-model="bytes" data-mode="buffer" editable style="height: 320px" />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import VueHex from "vuehex";
+
+const bytes = ref(new Uint8Array(await file.arrayBuffer()));
+</script>
+```
+
+### Window mode (parent-managed)
+
+In `data-mode="window"`, VueHex does not own the full dataset. The parent is responsible for applying `edit` intents to the backing store and then refreshing `windowData`.
+
+For undo/redo in windowed mode, VueHex emits `{ kind: "undo" }` / `{ kind: "redo" }` intents on the `edit` event and the parent should implement history.
+
+```vue
+<template>
+    <VueHex
+        v-model="windowData"
+        data-mode="window"
+        :window-offset="windowOffset"
+        :total-size="store.length"
+        :get-selection-data="getSelectionData"
+        editable
+        style="height: 320px"
+        @updateVirtualData="handleUpdateVirtualData"
+        @edit="handleEdit"
+    />
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import VueHex, { type VueHexEditIntent, type VueHexWindowRequest } from "vuehex";
+
+const store = ref(new Uint8Array(await file.arrayBuffer()));
+const windowOffset = ref(0);
+const windowData = ref(new Uint8Array());
+let windowLength = 0x4000;
+
+function handleUpdateVirtualData(request: VueHexWindowRequest) {
+    windowOffset.value = request.offset;
+    windowLength = request.length ?? windowLength;
+    windowData.value = store.value.slice(windowOffset.value, windowOffset.value + windowLength);
+}
+
+function getSelectionData(start: number, end: number) {
+    const from = Math.min(start, end);
+    const to = Math.max(start, end);
+    return store.value.slice(from, to + 1);
+}
+
+function handleEdit(intent: VueHexEditIntent) {
+    // Apply the intent to your backing store, then refresh windowData.
+    // (See Storybook "Editable (windowed)" / docs guide for a complete apply function.)
+    store.value = applyEditIntent(store.value, intent);
+    windowData.value = store.value.slice(windowOffset.value, windowOffset.value + windowLength);
+}
+</script>
+```
+
 ## Styling options
 
 1. Import `vuehex/styles` for the default look.
@@ -117,7 +212,7 @@ VueHex solves this with optimized **virtual scrolling**:
 
 The above technique works very well, but unfortunately it has a limit. Browsers impose limits on element dimensions to prevent rendering engine crashes. Most modern browsers cap `max-height` at around **33,554,432 pixels** (Chrome/Edge) or **17,895,698 pixels** (Firefox). Once your calculated scroll container height exceeds this limit, virtualization breaks—the scrollbar becomes inaccurate, and you can't reach data beyond the cap.
 
-For a hex viewer with 16 bytes per row and 24px row height:
+For a hex viewer/editor with 16 bytes per row and 24px row height:
 - **Firefox limit:** ~746,000 rows = ~11.4 MB of data
 - **Chrome limit:** ~1.4 million rows = ~21.4 MB of data
 
@@ -358,17 +453,72 @@ Customize individual chunk items with access to chunk data and active state:
 
 Both slots are optional. If not provided, VueHex uses the default chunk navigator appearance.
 
-## Status Bar Slots
+## Status bar
+
+Enable the status bar by setting `statusbar="top"` or `statusbar="bottom"`. You can control which items appear (and where) using `statusbarLayout`.
+
+### Layout
+
+`statusbarLayout` splits the status bar into three sections:
 
-When using the status bar (`statusbar="top"` or `statusbar="bottom"`), you can provide custom content via slots. Use the `statusbarLayout` prop with the `"slot"` component name to control where your custom content appears.
+- `left` (left-aligned)
+- `middle` (centered)
+- `right` (right-aligned)
 
-### Available slots
+Each section is an array of **status bar components** (strings or `{ name, config }` objects). Unknown component names are ignored.
 
-- `#statusbar-left` - Content for the left section
-- `#statusbar-middle` - Content for the middle section  
-- `#statusbar-right` - Content for the right section
+When `statusbarLayout` is omitted, VueHex defaults to:
 
-### Example
+- `left: ["offset", "hex", "ascii"]`
+- `right: ["selection"]`
+
+### Built-in components
+
+- `offset`: hovered byte offset (respects `uppercase` + `isPrintable`/`renderAscii` where relevant)
+- `hex`: hovered byte value as a 2-digit hex string
+- `ascii`: hovered byte rendered as ASCII (or `nonPrintableChar`)
+- `selection`: selection summary (`"<count> bytes (start–end)"`)
+- `editable`: editor state label (`VIEW` / `EDIT`)
+- `mode`: editor mode (`INS` / `OVR`) or placeholder when not available
+- `column`: active editor column (`HEX` / `ASCII`) or placeholder when not available
+- `total`: total size in bytes (derived from `totalSize` when provided; otherwise `v-model.length`). Does not include the EOF "ghost" cell.
+- `slot`: renders one of the status bar slots (see below)
+
+Notes:
+
+- The hover-driven items (`offset`, `hex`, `ascii`) reflect the cell under the mouse, not the keyboard cursor.
+- Editor items (`editable`, `mode`, `column`) render whenever they are included in the layout (they do not auto-hide when `editable` is false).
+
+### Per-component configuration (`config`)
+
+All built-ins support:
+
+- `label` (string): overrides the label text
+- `valueMinWidth` (string): CSS length (e.g. `"10ch"`) for stable widths
+- `valueWidth` (string): CSS length (e.g. `"120px"`)
+
+Component-specific keys:
+
+- `offset`: `format` (`"hex"` or `"decimal"`), `pad` (number), `prefix` (boolean)
+- `hex`: `prefix` (boolean)
+- `ascii`: `quote` (boolean)
+- `selection`: `showWhenEmpty` (boolean)
+- `editable`: `short` (boolean)
+- `mode`: `short` (boolean), `placeholder` (string)
+- `column`: `short` (boolean), `placeholder` (string)
+- `total`: `format` (`"human"` or `"hex"`), `decimals` (number, for `"human"`), `unit` (boolean), `pad` (number, for `"hex"`), `prefix` (boolean, for `"hex"`)
+
+### Slot components
+
+Use the built-in `"slot"` component name to render your own custom content inside the status bar.
+
+Available slots:
+
+- `#statusbar-left`
+- `#statusbar-middle`
+- `#statusbar-right`
+
+Example:
 
 ```vue
 <VueHex
@@ -377,20 +527,20 @@ When using the status bar (`statusbar="top"` or `statusbar="bottom"`), you can p
     :statusbar-layout="{
         left: ['offset', 'slot', 'hex'],
         middle: ['ascii'],
-        right: ['selection', 'slot']
+        right: ['selection', 'slot'],
     }"
 >
     <template #statusbar-left>
         <span>Mode: RO</span>
     </template>
-    
+
     <template #statusbar-right>
         <span>Endian: LE</span>
     </template>
 </VueHex>
 ```
 
-The `"slot"` entry in `statusbarLayout` determines where your custom content renders relative to built-in status bar items. You can place it at any position within each section array.
+The `"slot"` entry controls where your slot content renders relative to built-in items.
 
 ## License