@threadlabs/looma 0.2.20 → 0.3.0

package/vue/editor/index.d.ts

@@ -2,19 +2,24 @@ import { LoomaMentionItem, SlashMenuAnchorRect, SlashMenuItem, LoomaMentionProvi
 export * from '@threadlabs/looma/editor';
 import * as vue from 'vue';
 import { PropType, VNode } from 'vue';
-import { MentionMenuHighlightEventDetail, MentionMenuSelectEventDetail, TableContextMenuActionEventDetail, InsertTableEventDetail, TableOverlayActionEventDetail, SlashMenuHighlightEventDetail, SlashMenuSelectEventDetail } from '@threadlabs/looma/editor/ui';
+import { MentionMenuHighlightEventDetail, SlashMenuHighlightEventDetail, MentionMenuSelectEventDetail, SlashMenuSelectEventDetail, TableContextMenuActionEventDetail, TableOverlayActionEventDetail, InsertTableEventDetail } from '@threadlabs/looma/editor/ui';
 import { JSONContent, AnyExtension, Editor } from '@tiptap/core';
 import { OverlayTrigger } from '@threadlabs/looma/core';
 
+/**
+ * Native editor event details unwrapped for Vue callback attributes.
+ * Multiple menu primitives share `highlight` and `select` because their index
+ * semantics are identical; table primitives share the typed action channel.
+ */
 interface VueEditorAdapterEventMap {
-    mentionMenuHighlight: MentionMenuHighlightEventDetail;
-    mentionMenuSelect: MentionMenuSelectEventDetail;
-    tableAction: TableContextMenuActionEventDetail;
-    insertTable: InsertTableEventDetail;
-    tableOverlayAction: TableOverlayActionEventDetail;
-    slashMenuHighlight: SlashMenuHighlightEventDetail;
-    slashMenuSelect: SlashMenuSelectEventDetail;
+    highlight: MentionMenuHighlightEventDetail | SlashMenuHighlightEventDetail;
+    select: MentionMenuSelectEventDetail | SlashMenuSelectEventDetail;
+    action: TableContextMenuActionEventDetail | TableOverlayActionEventDetail;
+    insert: InsertTableEventDetail;
 }
+/**
+ * Vue projection of the slash suggestion menu with lifecycle-safe event wiring.
+ */
 declare const EditorSlashMenu: vue.DefineComponent<vue.ExtractPropTypes<{
     open: {
         type: BooleanConstructor;
@@ -75,6 +80,7 @@ declare const EditorSlashMenu: vue.DefineComponent<vue.ExtractPropTypes<{
     anchorRect: SlashMenuAnchorRect | null;
     selectedIndex: number;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/** Vue projection of the mention menu using the shared suggestion lifecycle. */
 declare const EditorMentionMenu: vue.DefineComponent<vue.ExtractPropTypes<{
     open: {
         type: BooleanConstructor;
@@ -135,11 +141,24 @@ declare const EditorMentionMenu: vue.DefineComponent<vue.ExtractPropTypes<{
     anchorRect: SlashMenuAnchorRect | null;
     selectedIndex: number;
 }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+/** Vue projection of the editor toolbar's semantic layout shell. */
 declare const EditorToolbar: vue.DefineComponent<Record<string, never>>;
+/** Vue projection that unwraps context-menu table actions for callbacks. */
 declare const EditorTableContextMenu: vue.DefineComponent<Record<string, never>>;
+/** Vue projection that unwraps toolbar table actions for callbacks. */
 declare const EditorTableToolbar: vue.DefineComponent<Record<string, never>>;
+/** Vue projection that reports the selected table dimensions as insert intent. */
 declare const EditorInsertTableGrid: vue.DefineComponent<Record<string, never>>;
+/**
+ * Vue projection of editor-owned table geometry and boundary actions.
+ * Geometry is assigned as a DOM property so structured measurements are never
+ * serialized through attributes.
+ */
 declare const EditorTableOverlay: vue.DefineComponent<Record<string, never>>;
+/**
+ * Canonical Vue editor export-to-native-tag correspondence used by parity
+ * checks and tooling that must enumerate opt-in editor primitives.
+ */
 declare const EDITOR_ADAPTER_COMPONENT_TAG_MAP: {
     readonly EditorToolbar: "ui-editor-toolbar";
     readonly EditorSlashMenu: "ui-editor-slash-menu";
@@ -150,6 +169,11 @@ declare const EDITOR_ADAPTER_COMPONENT_TAG_MAP: {
     readonly EditorTableOverlay: "ui-editor-table-overlay";
 };
 
+/**
+ * Durable image data stored in the editor document.
+ * Delivery-specific attributes are intentionally absent so serialized content
+ * remains portable across CDNs, viewport policies, and Vue applications.
+ */
 interface LoomaImageDescriptor {
     src: string;
     alt?: string;
@@ -166,20 +190,66 @@ interface LoomaImageRenditionAttributes {
     decoding?: "async" | "auto" | "sync";
     fetchPriority?: "auto" | "high" | "low";
 }
+/**
+ * Host policy for deriving transient browser-delivery attributes.
+ *
+ * @ownership The application owns the resolver and any URL/signing policy it
+ * consults; Looma reads its result without persisting it into editor JSON.
+ * @failure Throwing or returning `undefined` falls back to the durable source
+ * instead of interrupting rendering or mutating the document.
+ */
 type LoomaImageAttributeResolver = (image: LoomaImageDescriptor) => LoomaImageRenditionAttributes | undefined;
+/** User-originated interaction that may request the host's image viewer. */
 type LoomaImageActivationTrigger = Exclude<OverlayTrigger, "programmatic">;
+/**
+ * Image identity and user trigger emitted when an editor image is activated.
+ * Hosts may use the stable descriptor to open a viewer without inspecting DOM.
+ */
 interface LoomaImageActivationDetail extends LoomaImageDescriptor {
     trigger: LoomaImageActivationTrigger;
 }
+/**
+ * Durable image identity reported after a transient responsive rendition fails.
+ * The programmatic trigger distinguishes delivery fallback from user intent.
+ */
 interface LoomaImageRenditionErrorDetail extends LoomaImageDescriptor {
     trigger: "programmatic";
 }
 
+/**
+ * Host upload result normalized into the editor's durable image descriptor.
+ * `url` becomes the stored `src`; optional dimensions preserve layout before
+ * the image loads and `responsive` opts into host-provided rendition policy.
+ */
 interface LoomaImageUploadResult extends Omit<LoomaImageDescriptor, "src"> {
     url: string;
 }
+/**
+ * Application-owned upload boundary used by paste, drop, and file selection.
+ *
+ * @ownership The application owns network requests, persistence, and returned
+ * URLs. Looma owns only editor insertion after the promise fulfills.
+ * @failure Rejection leaves the document unchanged and is surfaced through the
+ * editor's `uploadError` event so the host chooses retry and user messaging.
+ */
 type LoomaImageUploader = (file: File) => Promise<string | LoomaImageUploadResult>;
+/**
+ * Chooses whether formatting controls follow a selection or occupy persistent
+ * editor chrome; it does not alter document commands or stored content.
+ */
 type LoomaEditorToolbarMode = "bubble" | "sticky";
+/**
+ * Turnkey Vue editor that composes Looma's framework-neutral Tiptap extensions
+ * with declarative menus, image delivery, and table interaction chrome.
+ *
+ * @ownership The component owns its Tiptap instance and transient UI state;
+ * callers own controlled `modelValue`, extension instances, and host services.
+ * @lifecycle Mount creates one editor and browser listener set, prop watchers
+ * synchronize external state, and unmount cancels frames/listeners and destroys
+ * the editor-owned resources.
+ * @failure Upload and responsive-rendition failures are emitted to the host;
+ * durable document content is retained or left unchanged for recovery.
+ */
 declare const LoomaEditor: vue.DefineComponent<vue.ExtractPropTypes<{
     modelValue: {
         type: PropType<JSONContent>;

package/vue/editor/index.js

@@ -10,7 +10,7 @@ import {
   UiEditorToolbar_default,
   createAdapterComponent,
   toHTMLElement
-} from "../chunk-P7BZ2KJZ.js";
+} from "../chunk-UZMTYDP6.js";
 
 // src/editor/index.ts
 import "@threadlabs/looma/editor";
@@ -23,8 +23,8 @@ import {
   shallowRef,
   watchEffect
 } from "vue";
-function createSuggestionMenuAdapter(name, eventPrefix) {
-  const component = eventPrefix === "slash" ? UiEditorSlashMenu_default : UiEditorMentionMenu_default;
+function createSuggestionMenuAdapter(name) {
+  const component = name === "EditorSlashMenu" ? UiEditorSlashMenu_default : UiEditorMentionMenu_default;
   return defineComponent({
     name,
     inheritAttrs: false,
@@ -42,31 +42,26 @@ function createSuggestionMenuAdapter(name, eventPrefix) {
         const element = elementRef.value;
         if (!element) return;
         const callbackAttrs = attrs;
-        const highlightCallback = eventPrefix === "slash" ? callbackAttrs.onSlashMenuHighlight : callbackAttrs.onMentionMenuHighlight;
-        const selectCallback = eventPrefix === "slash" ? callbackAttrs.onSlashMenuSelect : callbackAttrs.onMentionMenuSelect;
-        const eventBase = `looma-editor-${eventPrefix}-menu`;
+        const highlightCallback = callbackAttrs.onHighlight;
+        const selectCallback = callbackAttrs.onSelect;
         const highlightHandler = typeof highlightCallback === "function" ? (event) => highlightCallback(event.detail) : void 0;
         const selectHandler = typeof selectCallback === "function" ? (event) => selectCallback(event.detail) : void 0;
-        if (highlightHandler) element.addEventListener(`${eventBase}-highlight`, highlightHandler);
-        if (selectHandler) element.addEventListener(`${eventBase}-select`, selectHandler);
+        if (highlightHandler) element.addEventListener("highlight", highlightHandler);
+        if (selectHandler) element.addEventListener("select", selectHandler);
         onCleanup(() => {
-          if (highlightHandler) element.removeEventListener(`${eventBase}-highlight`, highlightHandler);
-          if (selectHandler) element.removeEventListener(`${eventBase}-select`, selectHandler);
+          if (highlightHandler) element.removeEventListener("highlight", highlightHandler);
+          if (selectHandler) element.removeEventListener("select", selectHandler);
         });
       });
       return () => {
         const callbackAttrs = attrs;
         const {
-          onMentionMenuHighlight,
-          onMentionMenuSelect,
-          onSlashMenuHighlight,
-          onSlashMenuSelect,
+          onHighlight,
+          onSelect,
           ...forwardedAttrs
         } = callbackAttrs;
-        void onMentionMenuHighlight;
-        void onMentionMenuSelect;
-        void onSlashMenuHighlight;
-        void onSlashMenuSelect;
+        void onHighlight;
+        void onSelect;
         return h(component, {
           ...props,
           ...forwardedAttrs,
@@ -78,27 +73,22 @@ function createSuggestionMenuAdapter(name, eventPrefix) {
     }
   });
 }
-var EDITOR_EVENT_BINDINGS = [
-  ["looma-editor-table-action", "onTableAction"],
-  ["looma-editor-insert-table", "onInsertTable"],
-  ["looma-editor-table-overlay-action", "onTableOverlayAction"]
-];
+var ACTION_EVENT_BINDINGS = [["action", "onAction"]];
+var INSERT_EVENT_BINDINGS = [["insert", "onInsert"]];
 var EditorSlashMenu = createSuggestionMenuAdapter(
-  "EditorSlashMenu",
-  "slash"
+  "EditorSlashMenu"
 );
 var EditorMentionMenu = createSuggestionMenuAdapter(
-  "EditorMentionMenu",
-  "mention"
+  "EditorMentionMenu"
 );
-var EditorToolbar = createAdapterComponent(UiEditorToolbar_default, "EditorToolbar", EDITOR_EVENT_BINDINGS);
-var EditorTableContextMenu = createAdapterComponent(UiEditorTableContextMenu_default, "EditorTableContextMenu", EDITOR_EVENT_BINDINGS);
-var EditorTableToolbar = createAdapterComponent(UiEditorTableToolbar_default, "EditorTableToolbar", EDITOR_EVENT_BINDINGS);
-var EditorInsertTableGrid = createAdapterComponent(UiEditorInsertTableGrid_default, "EditorInsertTableGrid", EDITOR_EVENT_BINDINGS);
+var EditorToolbar = createAdapterComponent(UiEditorToolbar_default, "EditorToolbar");
+var EditorTableContextMenu = createAdapterComponent(UiEditorTableContextMenu_default, "EditorTableContextMenu", ACTION_EVENT_BINDINGS);
+var EditorTableToolbar = createAdapterComponent(UiEditorTableToolbar_default, "EditorTableToolbar", ACTION_EVENT_BINDINGS);
+var EditorInsertTableGrid = createAdapterComponent(UiEditorInsertTableGrid_default, "EditorInsertTableGrid", INSERT_EVENT_BINDINGS);
 var EditorTableOverlay = createAdapterComponent(
   UiEditorTableOverlay_default,
   "EditorTableOverlay",
-  EDITOR_EVENT_BINDINGS,
+  ACTION_EVENT_BINDINGS,
   "class",
   ["geometry"]
 );
@@ -390,6 +380,8 @@ var LoomaEditor = defineComponent2({
       type: Object,
       default: () => ({ ...EMPTY_DOCUMENT })
     },
+    // Deliberate exception to Looma's opt-in boolean rule: an editor that is
+    // read-only unless configured would violate the primary UX promised by this wrapper.
     editable: { type: Boolean, default: true },
     placeholder: {
       type: String,
@@ -917,7 +909,7 @@ var LoomaEditor = defineComponent2({
     const commandButton = (label, icon, active, disabled, run) => {
       const syncNativeDisabled = (vnode) => {
         if (!(vnode.el instanceof Element)) return;
-        const button = vnode.el.querySelector("button");
+        const button = vnode.el instanceof HTMLButtonElement ? vnode.el : vnode.el.querySelector("button");
         if (button) button.disabled = disabled;
       };
       return h2(IconButton, {
@@ -978,20 +970,33 @@ var LoomaEditor = defineComponent2({
     return () => {
       const instance = editor.value;
       void editorStateVersion.value;
+      const tableActions = [
+        "align-left",
+        "align-center",
+        "align-right",
+        "background-none",
+        "background-gray",
+        "background-yellow",
+        "background-blue",
+        "background-green",
+        "background-red",
+        "clear-cells",
+        ...tableUi.capabilities.canAddRowBefore ? ["add-row-before"] : [],
+        ...tableUi.capabilities.canAddRowAfter ? ["add-row-after"] : [],
+        ...tableUi.capabilities.canAddColumnBefore ? ["add-column-before"] : [],
+        ...tableUi.capabilities.canAddColumnAfter ? ["add-column-after"] : [],
+        ...tableUi.capabilities.canMergeCells ? ["merge-cells"] : [],
+        ...tableUi.capabilities.canSplitCell ? ["split-cell"] : [],
+        ...tableUi.capabilities.canDeleteRow ? ["delete-row"] : [],
+        ...tableUi.capabilities.canDeleteColumn ? ["delete-column"] : [],
+        ...tableUi.capabilities.canDeleteTable ? ["delete-table"] : []
+      ];
       const tableProps = {
         open: true,
         "cell-alignment": tableUi.alignment,
         "cell-background": tableUi.background ?? void 0,
-        "can-add-row-before": tableUi.capabilities.canAddRowBefore,
-        "can-add-row-after": tableUi.capabilities.canAddRowAfter,
-        "can-add-column-before": tableUi.capabilities.canAddColumnBefore,
-        "can-add-column-after": tableUi.capabilities.canAddColumnAfter,
-        "can-delete-row": tableUi.capabilities.canDeleteRow,
-        "can-delete-column": tableUi.capabilities.canDeleteColumn,
-        "can-delete-table": tableUi.capabilities.canDeleteTable,
-        "can-merge-cells": tableUi.capabilities.canMergeCells,
-        "can-split-cell": tableUi.capabilities.canSplitCell,
-        onTableAction: runTableAction
+        actions: tableActions,
+        onAction: runTableAction
       };
       return h2("div", {
         ...attrs,
@@ -1092,7 +1097,7 @@ var LoomaEditor = defineComponent2({
           }
         }, () => [h2(EditorInsertTableGrid, {
           open: true,
-          onInsertTable: (detail) => {
+          onInsert: (detail) => {
             instance?.chain().focus().insertTable(detail).run();
             tablePickerOpen.value = false;
           }
@@ -1103,10 +1108,10 @@ var LoomaEditor = defineComponent2({
           items: managedSlashMenuItems(slash.items),
           selectedIndex: slash.selectedIndex,
           anchorRect: managedMenuAnchorRect(slash.rect),
-          onSlashMenuHighlight: ({ index }) => {
+          onHighlight: ({ index }) => {
             slash.selectedIndex = index;
           },
-          onSlashMenuSelect: ({ index }) => {
+          onSelect: ({ index }) => {
             slash.select?.(index);
           }
         }) : null,
@@ -1118,11 +1123,11 @@ var LoomaEditor = defineComponent2({
           selectedIndex: mention.selectedIndex,
           anchorRect: managedMenuAnchorRect(mention.rect),
           loading: mention.loading,
-          onMentionMenuHighlight: ({ index }) => {
+          onHighlight: ({ index }) => {
             mention.selectedIndex = index;
             mention.highlight?.(index);
           },
-          onMentionMenuSelect: ({ index }) => {
+          onSelect: ({ index }) => {
             mention.select?.(index);
           }
         }) : null,
@@ -1142,7 +1147,7 @@ var LoomaEditor = defineComponent2({
           rows: tableUi.rows,
           cols: tableUi.cols,
           geometry: tableUi.geometry,
-          onTableOverlayAction: runOverlayAction
+          onAction: runOverlayAction
         })]) : null,
         tableUi.menuOpen ? h2("div", {
           ref: tableMenuShell,