vuehex 0.6.3 → 0.6.5

package/README.md

@@ -29,7 +29,7 @@ Register the plugin once to make the `<VueHex>` component available everywhere a
 ```ts
 import { createApp } from "vue";
 import VueHex from "vuehex";
-import "vuehex/styles";
+import "vuehex/style.css";
 
 import App from "./App.vue";
 
@@ -38,6 +38,8 @@ app.use(VueHex);
 app.mount("#app");
 ```
 
+`vuehex/style.css` resolves to the package's bundled stylesheet.
+
 ## Quick start
 
 It can be as simple as this
@@ -192,7 +194,7 @@ function handleEdit(intent: VueHexEditIntent) {
 
 ## Styling options
 
-1. Import `vuehex/styles` for the default look.
+1. Import `vuehex/style.css` for the default look.
 2. Pass `theme="dark" | "light" | "terminal" | "sunset" | "auto"` to toggle bundled palettes explicitly (or skip the prop entirely to stick with OS detection).
 3. Roll your own styles targeting the emitted class names (`.vuehex`, `.vuehex-byte`, `.vuehex-ascii-char`, etc.). The default sheet sets `.vuehex { height: 100%; }`, so remember to give the wrapper a concrete height.
 
@@ -606,4 +608,4 @@ Bug reports are most actionable with:
 
 ## License
 
-MIT © Vincent Vollers
+MIT © Vincent Vollers

package/dist/components/VueHex.vue.d.ts

@@ -0,0 +1,217 @@
+import type { VueHexAsciiRenderer, VueHexCellClassResolverInput, VueHexEditIntent, VueHexPrintableCheck, VueHexStatusBarLayout, VueHexWindowRequest } from "./vuehex-api";
+/**
+ * VueHex - A performant, virtualized hex editor component for Vue 3.
+ *
+ * Supports three data modes:
+ * - `buffer`: Full dataset in `v-model` (no windowing)
+ * - `window`: Partial dataset in `v-model`, emits `updateVirtualData` for more
+ * - `auto`: Infers mode from `windowOffset` and `totalSize` props
+ *
+ * @example
+ * ```vue
+ * <VueHex
+ *   v-model="bytes"
+ *   :total-size="fileSize"
+ *   data-mode="window"
+ *   @update-virtual-data="loadWindow"
+ * />
+ * ```
+ */
+interface VueHexProps {
+    /**
+     * Controls whether VueHex treats `v-model` as the full buffer or as a virtual window.
+     *
+     * - `auto` (default): infer based on `windowOffset` / `totalSize` vs `modelValue.length`.
+     * - `buffer`: `v-model` is the entire dataset (no window requests).
+     * - `window`: `v-model` is a slice; VueHex may emit `updateVirtualData`.
+     */
+    dataMode?: "auto" | "buffer" | "window";
+    /**
+     * When true, disables internal scrolling/virtualization and expands the component height
+     * to fit the entire dataset.
+     *
+     * In this mode, VueHex expects the full data buffer in `v-model` (windowing is not used).
+     */
+    expandToContent?: boolean;
+    /** Total bytes available in the backing source; defaults to modelValue length. */
+    totalSize?: number;
+    /** Controls how many bytes render per table row; consumers tune readability. */
+    bytesPerRow?: number;
+    /** When true, renders hexadecimal digits in uppercase for stylistic preference. */
+    uppercase?: boolean;
+    /** Substitute character used for non-printable bytes in the ASCII pane. */
+    nonPrintableChar?: string;
+    /** Number of rows to pre-render above/below the viewport to reduce flicker. */
+    overscan?: number;
+    /** Optional custom printable check letting consumers broaden the ASCII range. */
+    isPrintable?: VueHexPrintableCheck;
+    /** Optional renderer for printable ASCII cells so callers can supply glyphs. */
+    renderAscii?: VueHexAsciiRenderer;
+    /** Theme token appended to classes, enabling consumer-provided styling. */
+    theme?: string | null;
+    /**
+     * Hook for assigning classes per cell, useful for highlighting bytes of interest.
+     *
+     * Pass an array to layer multiple resolvers; results are merged in order.
+     *
+     * When omitted/undefined, VueHex applies the built-in ASCII category highlighting.
+     * To disable all highlighting, pass null.
+     */
+    cellClassForByte?: VueHexCellClassResolverInput | null;
+    /**
+     * Optional selection provider used for clipboard copy.
+     * Should return the raw bytes between selectionStart and selectionEnd (inclusive).
+     */
+    getSelectionData?: import("./vuehex-api").VueHexSelectionDataProvider;
+    /** Toggles the chunk navigator UI, allowing quick jumps through large files. */
+    showChunkNavigator?: boolean;
+    /** Places the chunk navigator around the viewer to fit various layouts. */
+    chunkNavigatorPlacement?: "left" | "right" | "top" | "bottom";
+    /**
+     * Optional status bar placement.
+     *
+     * When set to "top" or "bottom", the status bar is shown.
+     * When omitted/null, the status bar is hidden.
+     */
+    statusbar?: "top" | "bottom" | null;
+    /** When true, enables keyboard/click cursor navigation and rendering. */
+    cursor?: boolean;
+    /** When true, enables editor mode (typing emits edit intents). */
+    editable?: boolean;
+    /**
+     * Configures which items appear in the status bar and where they render.
+     *
+     * The status bar is split into three sections: left, middle, right.
+     */
+    statusbarLayout?: VueHexStatusBarLayout | null;
+}
+type __VLS_Props = VueHexProps;
+type __VLS_ModelProps = {
+    "windowOffset"?: number;
+    modelValue?: Uint8Array;
+    "cursorLocation"?: number | null;
+};
+type __VLS_PublicProps = __VLS_Props & __VLS_ModelProps;
+declare var __VLS_11: {
+    chunks: import("./VueHexChunkNavigator.vue").ChunkDescriptor[];
+    activeIndex: number;
+}, __VLS_14: {
+    chunk: import("./VueHexChunkNavigator.vue").ChunkDescriptor;
+    active: boolean;
+    select: () => void;
+}, __VLS_25: {}, __VLS_28: {}, __VLS_31: {};
+type __VLS_Slots = {} & {
+    'chunk-navigator-header'?: (props: typeof __VLS_11) => any;
+} & {
+    'chunk-navigator-item'?: (props: typeof __VLS_14) => any;
+} & {
+    'statusbar-left'?: (props: typeof __VLS_25) => any;
+} & {
+    'statusbar-middle'?: (props: typeof __VLS_28) => any;
+} & {
+    'statusbar-right'?: (props: typeof __VLS_31) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<__VLS_PublicProps, {
+    scrollToByte: (offset: number) => void;
+    selectChunk: (index: number) => boolean;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:windowOffset": (value: number) => any;
+    "update:modelValue": (value: Uint8Array<ArrayBufferLike>) => any;
+    "update:cursorLocation": (value: number | null) => any;
+} & {
+    "row-hover-on": (payload: {
+        offset: number;
+    }) => any;
+    "row-hover-off": (payload: {
+        offset: number;
+    }) => any;
+    "hex-hover-on": (payload: {
+        index: number;
+        byte: number;
+    }) => any;
+    "hex-hover-off": (payload: {
+        index: number;
+        byte: number;
+    }) => any;
+    "ascii-hover-on": (payload: {
+        index: number;
+        byte: number;
+    }) => any;
+    "ascii-hover-off": (payload: {
+        index: number;
+        byte: number;
+    }) => any;
+    updateVirtualData: (payload: VueHexWindowRequest) => any;
+    edit: (payload: VueHexEditIntent) => any;
+    "byte-click": (payload: {
+        index: number;
+        byte: number;
+        kind: "hex" | "ascii";
+    }) => any;
+    "selection-change": (payload: {
+        start: number | null;
+        end: number | null;
+        length: number;
+    }) => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_PublicProps> & Readonly<{
+    "onRow-hover-on"?: ((payload: {
+        offset: number;
+    }) => any) | undefined;
+    "onRow-hover-off"?: ((payload: {
+        offset: number;
+    }) => any) | undefined;
+    "onHex-hover-on"?: ((payload: {
+        index: number;
+        byte: number;
+    }) => any) | undefined;
+    "onHex-hover-off"?: ((payload: {
+        index: number;
+        byte: number;
+    }) => any) | undefined;
+    "onAscii-hover-on"?: ((payload: {
+        index: number;
+        byte: number;
+    }) => any) | undefined;
+    "onAscii-hover-off"?: ((payload: {
+        index: number;
+        byte: number;
+    }) => any) | undefined;
+    onUpdateVirtualData?: ((payload: VueHexWindowRequest) => any) | undefined;
+    onEdit?: ((payload: VueHexEditIntent) => any) | undefined;
+    "onByte-click"?: ((payload: {
+        index: number;
+        byte: number;
+        kind: "hex" | "ascii";
+    }) => any) | undefined;
+    "onSelection-change"?: ((payload: {
+        start: number | null;
+        end: number | null;
+        length: number;
+    }) => any) | undefined;
+    "onUpdate:windowOffset"?: ((value: number) => any) | undefined;
+    "onUpdate:modelValue"?: ((value: Uint8Array<ArrayBufferLike>) => any) | undefined;
+    "onUpdate:cursorLocation"?: ((value: number | null) => any) | undefined;
+}>, {
+    editable: boolean;
+    cursor: boolean;
+    expandToContent: boolean;
+    uppercase: boolean;
+    isPrintable: VueHexPrintableCheck;
+    renderAscii: VueHexAsciiRenderer;
+    nonPrintableChar: string;
+    statusbar: "top" | "bottom" | null;
+    dataMode: "auto" | "buffer" | "window";
+    bytesPerRow: number;
+    overscan: number;
+    showChunkNavigator: boolean;
+    chunkNavigatorPlacement: "left" | "right" | "top" | "bottom";
+    statusbarLayout: VueHexStatusBarLayout | null;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/VueHexChunkNavigator.vue.d.ts

@@ -0,0 +1,49 @@
+export type ChunkNavigatorPlacement = "left" | "right" | "top" | "bottom";
+export interface ChunkDescriptor {
+    index: number;
+    label: string;
+    range: string;
+}
+interface VueHexChunkNavigatorProps {
+    show?: boolean;
+    placement?: ChunkNavigatorPlacement;
+    chunks: ChunkDescriptor[];
+    activeIndex: number;
+    rootClassExtra?: string[];
+    viewerClassExtra?: string[];
+    expandToContent?: boolean;
+}
+declare var __VLS_1: {
+    chunks: ChunkDescriptor[];
+    activeIndex: number;
+}, __VLS_3: {
+    chunk: ChunkDescriptor;
+    active: boolean;
+    select: () => void;
+}, __VLS_5: {};
+type __VLS_Slots = {} & {
+    'chunk-navigator-header'?: (props: typeof __VLS_1) => any;
+} & {
+    'chunk-navigator-item'?: (props: typeof __VLS_3) => any;
+} & {
+    default?: (props: typeof __VLS_5) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<VueHexChunkNavigatorProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    select: (index: number) => any;
+}, string, import("vue").PublicProps, Readonly<VueHexChunkNavigatorProps> & Readonly<{
+    onSelect?: ((index: number) => any) | undefined;
+}>, {
+    show: boolean;
+    placement: ChunkNavigatorPlacement;
+    rootClassExtra: string[];
+    viewerClassExtra: string[];
+    expandToContent: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/VueHexStatusBar.vue.d.ts

@@ -0,0 +1,55 @@
+import type { VueHexAsciiRenderer, VueHexEditorColumn, VueHexEditorMode, VueHexPrintableCheck, VueHexStatusBarLayout } from "./vuehex-api";
+type StatusBarPlacement = "top" | "bottom";
+interface VueHexStatusBarProps {
+    placement: StatusBarPlacement;
+    layout?: VueHexStatusBarLayout | null;
+    uppercase?: boolean;
+    isPrintable?: VueHexPrintableCheck;
+    renderAscii?: VueHexAsciiRenderer;
+    nonPrintableChar?: string;
+    selectionRange: {
+        start: number;
+        end: number;
+    } | null;
+    selectionCount: number;
+    editable?: boolean;
+    editorMode?: VueHexEditorMode | null;
+    editorColumn?: VueHexEditorColumn | null;
+    totalBytes?: number;
+}
+type VueHexHoverEvent = "row-hover-on" | "row-hover-off" | "hex-hover-on" | "hex-hover-off" | "ascii-hover-on" | "ascii-hover-off";
+type VueHexHoverEmit = (event: VueHexHoverEvent, payload: unknown) => void;
+declare var __VLS_2: "statusbar-left" | "statusbar-middle" | "statusbar-right", __VLS_3: {}, __VLS_6: "statusbar-left" | "statusbar-middle" | "statusbar-right", __VLS_7: {}, __VLS_10: "statusbar-left" | "statusbar-middle" | "statusbar-right", __VLS_11: {};
+type __VLS_Slots = {} & {
+    [K in NonNullable<typeof __VLS_2>]?: (props: typeof __VLS_3) => any;
+} & {
+    [K in NonNullable<typeof __VLS_6>]?: (props: typeof __VLS_7) => any;
+} & {
+    [K in NonNullable<typeof __VLS_10>]?: (props: typeof __VLS_11) => any;
+};
+declare const __VLS_base: import("vue").DefineComponent<VueHexStatusBarProps, {
+    handleHoverEvent: VueHexHoverEmit;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<VueHexStatusBarProps> & Readonly<{}>, {
+    editable: boolean;
+    layout: VueHexStatusBarLayout | null;
+    uppercase: boolean;
+    isPrintable: VueHexPrintableCheck;
+    renderAscii: VueHexAsciiRenderer;
+    nonPrintableChar: string;
+    selectionRange: {
+        start: number;
+        end: number;
+    } | null;
+    selectionCount: number;
+    editorMode: VueHexEditorMode | null;
+    editorColumn: VueHexEditorColumn | null;
+    totalBytes: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/composables/useChunking.d.ts

@@ -0,0 +1,66 @@
+import type { ComputedRef, Ref } from "vue";
+/**
+ * A UI-facing description of a single chunk in the chunk navigator.
+ */
+export interface VueHexChunkDescriptor {
+    index: number;
+    label: string;
+    range: string;
+}
+/**
+ * Inputs required to compute chunk boundaries and navigator metadata.
+ */
+interface UseChunkingOptions {
+    /** Whether the chunk navigator UI is enabled/visible. */
+    showNavigator: ComputedRef<boolean>;
+    /** Total bytes in the backing data source. */
+    totalBytes: ComputedRef<number>;
+    /** Bytes per rendered row (used to convert between bytes and rows). */
+    bytesPerRow: ComputedRef<number>;
+    /** Measured row height in pixels (used to cap the virtual scroll height). */
+    rowHeightValue: ComputedRef<number>;
+    /** Max virtual height in pixels allowed before chunking is enabled. */
+    maxVirtualHeight: ComputedRef<number>;
+    /** Casing preference used for chunk range labels. */
+    uppercase: ComputedRef<boolean>;
+}
+export interface UseChunkingResult {
+    /** Absolute start row (0-based) of the active chunk. */
+    chunkStartRow: Ref<number>;
+    /** Total number of rows required to render `totalBytes` at `bytesPerRow`. */
+    totalRows: ComputedRef<number>;
+    /** Maximum rows per chunk derived from `maxVirtualHeight / rowHeight`. */
+    chunkRowCapacity: ComputedRef<number>;
+    /** True when chunking is active (total rows exceed capacity). */
+    isChunking: ComputedRef<boolean>;
+    /** Total number of chunks available for the current dataset. */
+    chunkCount: ComputedRef<number>;
+    /** 0-based chunk index that contains `chunkStartRow`. */
+    activeChunkIndex: ComputedRef<number>;
+    /** Number of rows available within the active chunk. */
+    chunkRowCount: ComputedRef<number>;
+    /** Pixel height of the active chunk (`chunkRowCount * rowHeightValue`). */
+    chunkHeight: ComputedRef<number>;
+    /** Items suitable for a chunk navigator UI (empty when disabled). */
+    chunkItems: ComputedRef<VueHexChunkDescriptor[]>;
+    /** Normalizes `chunkStartRow` to valid bounds and chunk boundaries. */
+    clampChunkStartToBounds: () => void;
+    /** Ensures the chunk containing `row` is active; returns true if it changed. */
+    ensureChunkForRow: (row: number) => boolean;
+    /** Selects the chunk by 0-based index; returns true if it changed. */
+    selectChunk: (index: number) => boolean;
+}
+/**
+ * Provides chunking state + helpers for very large virtualized hex views.
+ *
+ * Chunking is used to cap the maximum virtual scroll height: the full data is
+ * split into fixed-size row ranges (chunks), and the UI renders/scrolls within
+ * the currently active chunk.
+ *
+ * Used by VueHex to keep scroll containers manageable for extremely large inputs,
+ * and to power the optional chunk navigator UI.
+ */
+export declare function useChunking(options: UseChunkingOptions): UseChunkingResult;
+export type UseChunkingReturn = ReturnType<typeof useChunking>;
+export type ChunkStartRowRef = Ref<number>;
+export {};

package/dist/components/composables/useCursor.d.ts

@@ -0,0 +1,57 @@
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+export interface CursorOptions {
+    /** Master enable toggle for cursor behaviors and DOM highlighting. */
+    enabled: ComputedRef<boolean>;
+    /** When true, scrolling/virtualization is disabled so cursor scrolling is skipped. */
+    isExpandToContent: ComputedRef<boolean>;
+    /** Scroll container element (focus + scrollTop updates). */
+    containerEl: Ref<HTMLDivElement | undefined>;
+    /** Table body element containing the rendered cells (for class toggling). */
+    tbodyEl: Ref<HTMLTableSectionElement | undefined>;
+    /** Current rendered markup (used to know when to re-apply cursor highlights). */
+    markup: ShallowRef<string>;
+    /** Total bytes in the backing data source (for clamping). */
+    totalBytes: ComputedRef<number>;
+    /** Bytes per row (for row math during navigation). */
+    bytesPerRow: ComputedRef<number>;
+    /** Row height in pixels (for scroll math). */
+    rowHeightValue: ComputedRef<number>;
+    /** Visible rows in the viewport (used to keep cursor in view). */
+    viewportRows: ComputedRef<number>;
+    /** Current chunk start row (for relative scroll math within a chunk). */
+    chunkStartRow: Ref<number>;
+    /** Ensures the chunk containing a row is active; returns true if it changed. */
+    ensureChunkForRow: (row: number) => boolean;
+    /** Schedules a re-evaluation of the rendered window after scroll/chunk changes. */
+    scheduleWindowEvaluation: () => void;
+    /** External cursor location model (0-based byte index), or null. */
+    cursorLocation: Ref<number | null>;
+    /** Requests scrolling such that an absolute byte offset is visible. */
+    scrollToByte: (offset: number) => void;
+}
+export interface CursorResult {
+    /**
+     * Normalized cursor location (byte index) or null when cursor is disabled/unset.
+     */
+    cursorLocation: ComputedRef<number | null>;
+    /**
+     * Updates the cursor location (clamped to the valid byte range).
+     */
+    setCursorLocation: (index: number | null) => void;
+}
+/**
+ * Manages the interactive cursor for VueHex.
+ *
+ * Why it exists:
+ * - Centralizes keyboard + pointer navigation for the "active byte".
+ * - Applies/removes cursor highlight classes to both hex and ASCII cells.
+ * - Ensures the active byte stays visible within the current scroll window.
+ *
+ * How it is used:
+ * - VueHex wires table/container refs + event handlers into this composable.
+ * - When the cursor changes, it updates the `cursorLocation` model value and
+ *   mutates DOM classes inside the rendered `tbody` markup.
+ * - For large datasets, it works with chunking/window virtualization via
+ *   `ensureChunkForRow` and `scheduleWindowEvaluation`.
+ */
+export declare function useCursor(options: CursorOptions): CursorResult;

package/dist/components/composables/useDataMode.d.ts

@@ -0,0 +1,36 @@
+import type { ComputedRef, Ref } from "vue";
+export interface UseDataModeOptions {
+    /** `dataMode` prop (or undefined) controlling buffer/window/auto behavior. */
+    dataMode: Ref<"auto" | "buffer" | "window" | undefined>;
+    /** When true, VueHex expands to content and never uses windowing. */
+    isExpandToContent: ComputedRef<boolean>;
+    /** Current window offset in bytes (used by the host in windowed mode). */
+    windowOffset: ComputedRef<number>;
+    /** Total size of the backing source (may be larger than provided data). */
+    totalSize: Ref<number | undefined>;
+    /** Current length of the provided data (e.g. modelValue.length). */
+    dataLength: ComputedRef<number>;
+}
+export interface UseDataModeResult {
+    /** Normalized mode after applying defaults and validation. */
+    normalizedMode: ComputedRef<"auto" | "buffer" | "window">;
+    /** True when VueHex should request/operate on a moving window of data. */
+    isWindowed: ComputedRef<boolean>;
+    /** True when VueHex owns the full buffer locally (non-windowed). */
+    isSelfManaged: ComputedRef<boolean>;
+}
+/**
+ * Composable that centralizes data mode detection logic.
+ *
+ * Why it exists:
+ * - VueHex supports both "buffer" mode (all bytes provided) and "window" mode
+ *   (only a slice provided; the host is responsible for loading more).
+ * - This composable keeps the mode decision logic in one place so the rest of
+ *   the component can branch on `isWindowed` / `isSelfManaged`.
+ *
+ * How it is used:
+ * - VueHex passes `dataMode`, `expandToContent`, `totalSize`, and the current
+ *   `modelValue.length`.
+ * - In `auto` mode, it treats `totalSize > modelValue.length` as windowed.
+ */
+export declare function useDataMode(options: UseDataModeOptions): UseDataModeResult;

package/dist/components/composables/useEditing.d.ts

@@ -0,0 +1,28 @@
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+import type { VueHexEditIntent, VueHexEditorColumn, VueHexEditorMode } from "../vuehex-api";
+export interface EditingOptions {
+    enabled: ComputedRef<boolean>;
+    containerEl: Ref<HTMLDivElement | undefined>;
+    tbodyEl: Ref<HTMLTableSectionElement | undefined>;
+    markup: ShallowRef<string>;
+    uppercase: ComputedRef<boolean>;
+    cursorIndex: ComputedRef<number | null>;
+    setCursorIndex: (index: number | null) => void;
+    selectionRange: ComputedRef<{
+        start: number;
+        end: number;
+    } | null>;
+    clearSelection: () => void;
+    copySelectionToClipboard: () => Promise<boolean>;
+    totalBytes: ComputedRef<number>;
+    isSelfManagedData: ComputedRef<boolean>;
+    getSelfManagedBytes: () => Uint8Array;
+    setSelfManagedBytes: (bytes: Uint8Array) => void;
+    emitEdit: (intent: VueHexEditIntent) => void;
+}
+export interface EditingResult {
+    activeColumn: Ref<VueHexEditorColumn>;
+    editorMode: Ref<VueHexEditorMode>;
+    resetPendingHexInput: () => void;
+}
+export declare function useEditing(options: EditingOptions): EditingResult;

package/dist/components/composables/useHexWindow.d.ts

@@ -0,0 +1,104 @@
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+import type { VueHexAsciiRenderer, VueHexCellClassResolver, VueHexPrintableCheck, VueHexWindow, VueHexWindowRequest } from "../vuehex-api";
+export interface HexWindowOptions {
+    /** Scroll container element (scrollTop source of truth). */
+    containerEl: Ref<HTMLDivElement | undefined>;
+    /** Table body element where HTML markup is injected. */
+    tbodyEl: Ref<HTMLTableSectionElement | undefined>;
+    /** Bytes per row (affects layout + offset-to-row conversions). */
+    bytesPerRow: ComputedRef<number>;
+    /** Measured row height (null until measured). */
+    rowHeight: Ref<number | null>;
+    /** Row height value used for calculations (fallback when not measured). */
+    rowHeightValue: ComputedRef<number>;
+    /** Number of visible rows in the viewport. */
+    viewportRows: ComputedRef<number>;
+    /** Rows to render above/below viewport to reduce flicker. */
+    overscanRows: ComputedRef<number>;
+    /** Active chunk start row (0-based). */
+    chunkStartRow: Ref<number>;
+    /** Total rows available within the active chunk. */
+    chunkRowCount: ComputedRef<number>;
+    /** Total bytes in the backing data source. */
+    totalBytes: ComputedRef<number>;
+    /** Total bytes that can actually be requested from the host (excludes the editable EOF ghost). */
+    requestTotalBytes: ComputedRef<number>;
+    /** When true, renders a single EOF ghost byte at index == requestTotalBytes. */
+    includeGhostEnd?: ComputedRef<boolean>;
+    /** True when VueHex treats the provided data as the full buffer (no windowing). */
+    isSelfManagedData: ComputedRef<boolean>;
+    /** Two-way model tracking the current absolute offset (used for buffer mode scroll sync). */
+    windowOffset: Ref<number>;
+    /** Ensures the chunk containing a row is active; returns true if it changed. */
+    ensureChunkForRow: (row: number) => boolean;
+    /** Normalizes `chunkStartRow` to valid bounds/chunk boundaries. */
+    clampChunkStartToBounds: () => void;
+    /** Reads the latest window state (offset + data) from the host/component. */
+    getWindowState: () => VueHexWindow;
+    /** Casing preference for hex rendering. */
+    getUppercase: () => boolean;
+    /** Determines whether bytes are printable for ASCII rendering. */
+    getPrintableChecker: () => VueHexPrintableCheck;
+    /** Converts a byte into an ASCII glyph (when printable). */
+    getAsciiRenderer: () => VueHexAsciiRenderer;
+    /** Optional class resolver for per-cell highlighting. */
+    getCellClassResolver: () => VueHexCellClassResolver | undefined;
+    /** Replacement character for non-printable bytes. */
+    getNonPrintableChar: () => string;
+    /** Current selection range (inclusive) for embedding selection classes. */
+    getSelectionRange: () => {
+        start: number;
+        end: number;
+    } | null;
+    /** Issues a window request to the host (used only in windowed mode). */
+    requestWindow: (request: VueHexWindowRequest) => void;
+    /** Clears hover state when markup changes. */
+    clearHoverState: () => void;
+}
+export interface HexWindowResult {
+    /** Rendered HTML for the visible table slice (consumed via `v-html`). */
+    markup: ShallowRef<string>;
+    /** Normalized bytes backing the current rendered/windowed slice. */
+    normalizedBytes: ShallowRef<Uint8Array<ArrayBufferLike>>;
+    /** HTML-safe replacement for non-printable ASCII characters. */
+    fallbackAsciiChar: ShallowRef<string>;
+    /** Absolute start row of the currently rendered markup slice. */
+    renderStartRow: Ref<number>;
+    /** Count of rows currently rendered from `normalizedBytes`. */
+    renderedRows: ComputedRef<number>;
+    /** Absolute start row of the current externally-provided window (`windowOffset`). */
+    startRow: ComputedRef<number>;
+    /** Schedules a recalculation of visible rows and window requests. */
+    scheduleWindowEvaluation: () => void;
+    /** Scroll handler for the container; coalesces work via RAF. */
+    handleScroll: () => void;
+    /** Immediately scrolls to ensure an absolute byte offset is visible. */
+    scrollToByte: (offset: number) => void;
+    /** Queues a scroll-to-offset to be applied on the next evaluation tick. */
+    queueScrollToOffset: (offset: number) => void;
+    /** Syncs internal buffers from the current external window state. */
+    updateFromWindowState: () => void;
+    /** Regenerates markup for the current visible slice. */
+    updateRenderedSlice: () => void;
+    /** Measures row height from the DOM when possible (used for scroll math). */
+    measureRowHeight: () => void;
+}
+/**
+ * Owns the virtualized "rendered window" for VueHex.
+ *
+ * Why it exists:
+ * - Generates the table body's HTML markup (via `v-html`) for only the rows that
+ *   should be visible (plus overscan), rather than rendering the full dataset.
+ * - Keeps scrolling smooth by translating scrollTop into a rendered row slice.
+ * - Coordinates external window requests for huge datasets ("windowed mode")
+ *   while also supporting "buffer mode" where all bytes are locally available.
+ *
+ * How it is used:
+ * - VueHex provides refs to the scroll container and `tbody`, plus rendering
+ *   preferences (bytesPerRow, casing, ASCII rendering, class resolvers).
+ * - `handleScroll` and `scheduleWindowEvaluation` are called on scroll to update
+ *   markup and to request more data when needed.
+ * - Works in tandem with chunking (`chunkStartRow`, `chunkRowCount`) to keep the
+ *   virtual scroll height bounded for very large inputs.
+ */
+export declare function useHexWindow(options: HexWindowOptions): HexWindowResult;

package/dist/components/composables/useHoverLinking.d.ts

@@ -0,0 +1,39 @@
+import type { Ref } from "vue";
+/**
+ * Typed emitter contract for hover events forwarded by VueHex.
+ *
+ * Why it exists: keeps the composable decoupled from the Vue component instance
+ * while still allowing consumers to observe hover state.
+ */
+type HoverEmit = (event: "row-hover-on" | "row-hover-off" | "hex-hover-on" | "hex-hover-off" | "ascii-hover-on" | "ascii-hover-off", payload: unknown) => void;
+export interface HoverLinkingOptions {
+    /** Event emitter from VueHex; hover events are forwarded to component consumers. */
+    emit: HoverEmit;
+    /** Table body element containing rendered cells (used for class toggling). */
+    tbodyEl: Ref<HTMLTableSectionElement | undefined>;
+}
+export interface HoverLinkingResult {
+    /** Pointer-over handler (attach to the table body). */
+    handlePointerOver: (event: PointerEvent) => void;
+    /** Pointer-out handler (attach to the table body). */
+    handlePointerOut: (event: PointerEvent) => void;
+    /** Clears any active hover state and linked highlighting. */
+    clearHoverState: () => void;
+}
+/**
+ * Links hover state between rows, hex cells, and ASCII cells.
+ *
+ * Why it exists:
+ * - Keeps hex/ASCII columns visually synchronized on hover.
+ * - Emits semantic hover events (row/hex/ascii enter/leave) for consumers.
+ * - Debounces DOM class updates to avoid excessive work during pointer movement.
+ *
+ * How it is used:
+ * - VueHex forwards `pointerover`/`pointerout` events from the rendered `tbody`.
+ * - The composable reads `data-*` attributes embedded in the markup to determine
+ *   which row/cell is under the pointer and emits matching events.
+ * - `clearHoverState` is called when the pointer leaves the table or when the
+ *   rendered markup changes.
+ */
+export declare function useHoverLinking(options: HoverLinkingOptions): HoverLinkingResult;
+export {};

package/dist/components/composables/useSelection.d.ts

@@ -0,0 +1,91 @@
+import type { ComputedRef, Ref, ShallowRef } from "vue";
+import type { VueHexAsciiRenderer, VueHexPrintableCheck, VueHexSelectionDataProvider } from "../vuehex-api";
+export interface SelectionOptions {
+    /** Scroll container element (focus + pointer event wiring). */
+    containerEl: Ref<HTMLDivElement | undefined>;
+    /** Table body element containing rendered cells (used for event delegation). */
+    tbodyEl: Ref<HTMLTableSectionElement | undefined>;
+    /** Current rendered markup; changes trigger re-sync of selection classes. */
+    markup: ShallowRef<string>;
+    /** Optional user-provided selection data provider (used for copy). */
+    getSelectionDataProp: () => VueHexSelectionDataProvider | undefined;
+    /** True when VueHex owns the full data buffer locally. */
+    isSelfManagedData: ComputedRef<boolean>;
+    /** Total bytes in the backing data source (for clamping). */
+    totalBytes: ComputedRef<number>;
+    /** Returns the locally-managed bytes when in self-managed mode. */
+    getSelfManagedBytes: () => Uint8Array;
+    /** Casing preference used by renderer helpers. */
+    getUppercase: () => boolean;
+    /** Determines whether bytes are printable for ASCII rendering. */
+    getPrintableChecker: () => VueHexPrintableCheck;
+    /** Converts a byte into an ASCII glyph (when printable). */
+    getAsciiRenderer: () => VueHexAsciiRenderer;
+    /** Replacement character for non-printable bytes. */
+    getNonPrintableChar: () => string;
+    /** Forces markup regeneration so selection CSS classes are embedded. */
+    updateRenderedSlice: () => void;
+    /**
+     * When true, selection can only be started/updated via Shift+click.
+     *
+     * Why it exists: in cursor/editable modes, normal clicks should move the cursor
+     * without implicitly selecting a single byte.
+     */
+    requireShiftToSelect?: ComputedRef<boolean>;
+    /**
+     * Optional cursor index used as the anchor when shift-clicking with no existing selection.
+     *
+     * Why it exists: supports common UX where click moves cursor, then shift-click
+     * selects the range from the cursor to the clicked byte.
+     */
+    cursorIndex?: ComputedRef<number | null>;
+    /** Optional emitter for click events on individual bytes. */
+    emitByteClick?: (payload: {
+        index: number;
+        byte: number;
+        kind: "hex" | "ascii";
+    }) => void;
+    /** Optional emitter for selection range changes. */
+    emitSelectionChange?: (payload: {
+        start: number | null;
+        end: number | null;
+        length: number;
+    }) => void;
+}
+export interface SelectionResult {
+    /**
+     * Function used to retrieve selected bytes for copy/consumer APIs.
+     * Null when selection is disabled.
+     */
+    selectionDataProvider: ComputedRef<VueHexSelectionDataProvider | null>;
+    /** True when selection is active/enabled. */
+    selectionEnabled: ComputedRef<boolean>;
+    /** Ordered selection range (inclusive), or null when there is no selection. */
+    selectionRange: ComputedRef<{
+        start: number;
+        end: number;
+    } | null>;
+    /** Number of selected bytes. */
+    selectionCount: ComputedRef<number>;
+    /** Clears any active selection (no-op if none). */
+    clearSelection: () => void;
+    /** Copies the current selection to the clipboard (no-op if none). */
+    copySelectionToClipboard: () => Promise<boolean>;
+}
+/**
+ * Provides mouse/pointer-driven selection for VueHex.
+ *
+ * Why it exists:
+ * - Tracks anchor/focus to form a stable selection range across interactions.
+ * - Supports selection in either the hex or ASCII column while keeping indices aligned.
+ * - Emits selection/click events and triggers markup regeneration so selection CSS
+ *   classes are embedded in the rendered HTML.
+ *
+ * How it is used:
+ * - VueHex passes DOM refs (`containerEl`, `tbodyEl`) and the current markup ref.
+ * - The composable attaches pointer listeners and updates selection state.
+ * - When selection changes, it requests a re-render via `updateRenderedSlice`.
+ * - For clipboard/copy workflows, it exposes a `selectionDataProvider` that is
+ *   either user-supplied (`getSelectionDataProp`) or derived from self-managed data.
+ */
+export declare function useSelection(options: SelectionOptions): SelectionResult;

package/dist/components/composables/useVueHexTheme.d.ts

@@ -0,0 +1,35 @@
+import type { ComputedRef, Ref } from "vue";
+export interface UseVueHexThemeOptions {
+    /** Theme token provided by the consumer (prop). */
+    theme: Ref<string | null | undefined>;
+    /** True when VueHex expands to fit content (no virtualization). */
+    isExpandToContent: ComputedRef<boolean>;
+    /** True when selection features are enabled; affects container classes. */
+    selectionEnabled: ComputedRef<boolean>;
+    /** Status bar placement prop; null/undefined means hidden. */
+    statusbar: Ref<"top" | "bottom" | null | undefined>;
+}
+export interface UseVueHexThemeResult {
+    /** Canonical theme key (kebab-case), or null when no explicit theme is set. */
+    themeKey: ComputedRef<string | null>;
+    /** Theme classes applied to the component root and related wrappers. */
+    themeClass: ComputedRef<string[]>;
+    /** Classes applied to the scroll container element. */
+    containerClass: ComputedRef<string[]>;
+    /** Extra classes forwarded to the chunk navigator root wrapper. */
+    rootClassExtra: ComputedRef<string[]>;
+    /** True when the status bar should be rendered. */
+    showStatusBar: ComputedRef<boolean>;
+    /** Status bar placement, or null when the status bar is hidden. */
+    statusBarPlacement: ComputedRef<"top" | "bottom" | null>;
+    /** Extra classes forwarded to the chunk navigator viewer wrapper. */
+    viewerClassExtra: ComputedRef<string[]>;
+}
+/**
+ * Centralizes theme + class computations for VueHex.
+ *
+ * Why it exists:
+ * - VueHex derives multiple class lists (container/root/viewer) from the theme,
+ *   interactive state, and status bar placement.
+ */
+export declare function useVueHexTheme(options: UseVueHexThemeOptions): UseVueHexThemeResult;

package/dist/components/vuehex-api.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Describes the currently loaded window of bytes, including the absolute offset into the full data set.
+ */
+export interface VueHexWindow {
+    offset: number;
+    data: Uint8Array;
+}
+/**
+ * Payload emitted when VueHex needs a new slice of bytes from the host application.
+ */
+export interface VueHexWindowRequest {
+    offset: number;
+    length: number;
+}
+/**
+ * Built-in theme keys supported by VueHex out of the box.
+ *
+ * Custom themes are also supported by passing any token to the `theme` prop
+ * (VueHex emits `.vuehex-theme-<token>`).
+ */
+export declare const VUE_HEX_BUILTIN_THEME_KEYS: readonly ["auto", "light", "dark", "terminal", "sunset"];
+/** Union type of the built-in theme keys. */
+export type VueHexBuiltinThemeKey = (typeof VUE_HEX_BUILTIN_THEME_KEYS)[number];
+/**
+ * Function that determines whether a given byte should be treated as printable ASCII for the viewer.
+ */
+export type VueHexPrintableCheck = (byte: number) => boolean;
+/**
+ * Function that renders a printable byte into its display string representation.
+ */
+export type VueHexAsciiRenderer = (byte: number) => string;
+/**
+ * Fetches raw bytes for the given inclusive selection range.
+ */
+export type VueHexSelectionDataProvider = (selectionStart: number, selectionEnd: number) => Uint8Array;
+/** Which column the editor is currently targeting. */
+export type VueHexEditorColumn = "hex" | "ascii";
+/** Editing mode: overwrite replaces bytes; insert grows the buffer. */
+export type VueHexEditorMode = "overwrite" | "insert";
+/**
+ * Single edit intent emitted by VueHex when `editable` is enabled.
+ *
+ * Consumers that own the backing buffer should apply these intents to their
+ * data source and feed the updated bytes back via `v-model`.
+ */
+export type VueHexEditIntent = {
+    kind: "overwrite-byte";
+    index: number;
+    value: number;
+    column: VueHexEditorColumn;
+} | {
+    kind: "insert-byte";
+    index: number;
+    value: number;
+    column: VueHexEditorColumn;
+} | {
+    kind: "overwrite-bytes";
+    index: number;
+    values: number[];
+    column: VueHexEditorColumn;
+} | {
+    kind: "insert-bytes";
+    index: number;
+    values: number[];
+    column: VueHexEditorColumn;
+} | {
+    kind: "delete-byte";
+    index: number;
+    direction: "backspace" | "delete";
+} | {
+    kind: "delete-range";
+    start: number;
+    end: number;
+} | {
+    /** Undo the most recent edit action (Ctrl/Cmd+Z). */
+    kind: "undo";
+} | {
+    /** Redo the most recently undone edit action (Ctrl/Cmd+Y or Ctrl/Cmd+Shift+Z). */
+    kind: "redo";
+};
+/**
+ * Built-in status bar component identifiers.
+ *
+ * - "offset": cursor offset (absolute byte index)
+ * - "hex": current byte rendered as hex
+ * - "ascii": current byte rendered as ASCII (or nonPrintableChar)
+ * - "selection": selection summary text
+ * - "slot": renders a named Vue slot in the status bar section
+ */
+export type VueHexStatusBarComponentName = "offset" | "hex" | "ascii" | "selection" | "editable" | "mode" | "column" | "total" | "slot";
+/**
+ * Declares a component that can appear in the VueHex status bar.
+ *
+ * A string is treated as the component name. The object form allows
+ * attaching per-component configuration.
+ */
+export type VueHexStatusBarComponent = string | {
+    name: string;
+    config?: unknown;
+};
+/**
+ * Controls where status bar components render.
+ *
+ * The status bar is split into three sections:
+ * - left (left-aligned)
+ * - middle (centered)
+ * - right (right-aligned)
+ */
+export interface VueHexStatusBarLayout {
+    left?: VueHexStatusBarComponent[];
+    middle?: VueHexStatusBarComponent[];
+    right?: VueHexStatusBarComponent[];
+}
+/**
+ * Identifies which table column a cell represents when resolving custom classes.
+ */
+export type VueHexCellKind = "hex" | "ascii";
+/**
+ * Shape of the payload provided to the cell class resolver, including the absolute index and byte value.
+ */
+export interface VueHexCellClassPayload {
+    kind: VueHexCellKind;
+    index: number;
+    byte: number;
+}
+/**
+ * Allows consumers to return custom class names for individual cells in the hex or ASCII columns.
+ */
+export type VueHexCellClassResolver = (payload: VueHexCellClassPayload) => string | string[] | null | undefined;
+/**
+ * Accepts either a single cell class resolver or an ordered list of resolvers.
+ *
+ * When multiple resolvers are supplied, VueHex will call each resolver and merge
+ * the returned class names.
+ */
+export type VueHexCellClassResolverInput = VueHexCellClassResolver | ReadonlyArray<VueHexCellClassResolver>;
+/**
+ * Default per-byte cell classifier used by VueHex when `cellClassForByte` is not provided.
+ *
+ * Returns built-in category classes (`vuehex-category-*`) based on ASCII ranges.
+ */
+export declare const DEFAULT_ASCII_CATEGORY_CELL_CLASS_RESOLVER: VueHexCellClassResolver;
+/**
+ * Default printable check for standard ASCII range (0x20-0x7E).
+ */
+export declare const DEFAULT_PRINTABLE_CHECK: VueHexPrintableCheck;
+/**
+ * Default renderer that converts printable bytes to their character form.
+ */
+export declare const DEFAULT_ASCII_RENDERER: VueHexAsciiRenderer;
+/**
+ * Describes an ASCII preset bundle with labeling and behavior for rendering/printability.
+ */
+export interface VueHexAsciiPreset {
+    label: string;
+    isPrintable: VueHexPrintableCheck;
+    renderAscii: VueHexAsciiRenderer;
+}
+/**
+ * Built-in presets for common ASCII rendering scenarios that consumers can reuse.
+ */
+export declare const VUE_HEX_ASCII_PRESETS: Record<"standard" | "latin1" | "visibleWhitespace", VueHexAsciiPreset>;

package/dist/components/vuehex-resolvers.d.ts

@@ -0,0 +1,11 @@
+import type { VueHexCellClassResolver, VueHexCellClassResolverInput } from "./vuehex-api";
+/**
+ * Normalizes `cellClassForByte` input into a single resolver function.
+ *
+ * Rules:
+ * - `undefined`: use the default built-in ASCII category resolver.
+ * - `null`: disable all per-cell class resolution.
+ * - `function`: use as-is.
+ * - `array`: filter to functions and merge results (flattened).
+ */
+export declare function normalizeCellClassForByteResolver(input: VueHexCellClassResolverInput | null | undefined): VueHexCellClassResolver | undefined;

package/dist/components/vuehex-utils.d.ts

@@ -0,0 +1,41 @@
+export declare const OFFSET_PAD = 8;
+/**
+ * Validates that the input data source is a Uint8Array, failing fast otherwise.
+ */
+export declare function normalizeSource(source: unknown): Uint8Array;
+/**
+ * Sanitizes the requested bytes-per-row value, ensuring downstream layout logic always
+ * receives a finite integer at least one byte wide per row.
+ */
+export declare function clampBytesPerRow(value: unknown): number;
+/**
+ * Produces the fallback ASCII character used for non-printable bytes, escaping it so
+ * it can be dropped directly into HTML markup.
+ */
+export declare function resolveFallbackChar(value: unknown): string;
+/**
+ * Escapes raw text for safe HTML insertion by replacing reserved characters.
+ */
+export declare function escapeHtml(value: string): string;
+/**
+ * Formats a byte offset as plain hexadecimal text (no HTML) for summary displays.
+ */
+export declare function formatOffsetPlain(value: number, uppercase: boolean): string;
+/**
+ * Clamps a numeric value into an inclusive range for shared viewport math helpers.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Parses an integer from a DOM element attribute and validates it.
+ * Returns null if the attribute doesn't exist or contains an invalid number.
+ */
+export declare function parseIndexAttribute(element: HTMLElement, attrName: string): number | null;
+/**
+ * Reads a byte index from a hex or ASCII cell element.
+ * Returns null if the element is not a valid cell or has no index.
+ */
+export declare function readByteIndexFromElement(element: Element | null): number | null;
+/**
+ * Normalizes a theme identifier into a kebab-case token that can be appended to class names.
+ */
+export declare function normalizeThemeKey(value: unknown): string | null;

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import "./assets/vuehex.css";
+import type { App } from "vue";
+import VueHex from "./components/VueHex.vue";
+export interface VueHexPluginOptions {
+    componentName?: string;
+}
+export declare function install(app: App, options?: VueHexPluginOptions): void;
+declare const _default: {
+    install: typeof install;
+};
+export default _default;
+export { VueHex };
+export * from "./components/vuehex-api";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "vuehex",
-	"version": "0.6.3",
+	"version": "0.6.5",
 	"private": false,
 	"description": "A fast and flexible Vue 3 component for viewing and editing binary data as a hexadecimal view",
 	"author": "Vincent Vollers",
@@ -11,14 +11,11 @@
 	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
+			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
+			"default": "./dist/index.js"
 		},
-		"./styles": {
-			"import": "./dist/styles.js",
-			"types": "./dist/styles.d.ts"
-		},
-		"./style.css": "./dist/style.css",
+		"./style.css": "./dist/index.css",
 		"./package.json": "./package.json"
 	},
 	"files": [
@@ -28,7 +25,7 @@
 	],
 	"scripts": {
 		"dev": "vite",
-		"build": "vite build && vue-tsc --declaration --emitDeclarationOnly --outDir dist",
+		"build": "vite build && vue-tsc -p tsconfig.build.json",
 		"build:demo": "vite build --mode demo",
 		"preview": "vite preview",
 		"storybook": "storybook dev -p 6006 --disable-telemetry",