@threadlabs/looma 0.4.0 → 0.5.1

package/vue/editor/LoomaEditor.d.ts

@@ -0,0 +1,171 @@
+import "./looma-editor.css";
+import type { AnyExtension, Editor, JSONContent } from "@tiptap/core";
+import { type PropType, type VNode } from "vue";
+import { type LoomaMentionItem, type LoomaMentionProvider } from "@threadlabs/looma/editor";
+import { type LoomaImageActivationDetail, type LoomaImageAttributeResolver, type LoomaImageDescriptor, type LoomaImageRenditionErrorDetail } from "./image-delivery.js";
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export declare const LoomaEditor: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    modelValue: {
+        type: PropType<JSONContent>;
+        default: () => {
+            [key: string]: any;
+            type?: string;
+            attrs?: Record<string, any>;
+            content?: JSONContent[];
+            marks?: {
+                type: string;
+                attrs?: Record<string, any>;
+                [key: string]: any;
+            }[];
+            text?: string;
+        };
+    };
+    editable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    placeholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    extensions: {
+        type: PropType<AnyExtension[]>;
+        default: () => never[];
+    };
+    mentionItems: {
+        type: PropType<LoomaMentionItem[]>;
+        default: () => never[];
+    };
+    mentionProvider: {
+        type: PropType<LoomaMentionProvider | undefined>;
+        default: undefined;
+    };
+    mentionLimit: {
+        type: NumberConstructor;
+        default: number;
+    };
+    uploadImage: {
+        type: PropType<LoomaImageUploader | undefined>;
+        default: undefined;
+    };
+    resolveImageAttributes: {
+        type: PropType<LoomaImageAttributeResolver | undefined>;
+        default: undefined;
+    };
+    toolbarMode: {
+        type: PropType<LoomaEditorToolbarMode>;
+        default: string;
+    };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:modelValue": (_value: JSONContent) => true;
+    update: (_value: JSONContent) => true;
+    ready: (_editor: Editor) => true;
+    uploadError: (_error: unknown, _file: File) => true;
+    imageActivate: (_detail: LoomaImageActivationDetail) => true;
+    imageRenditionError: (_detail: LoomaImageRenditionErrorDetail) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    modelValue: {
+        type: PropType<JSONContent>;
+        default: () => {
+            [key: string]: any;
+            type?: string;
+            attrs?: Record<string, any>;
+            content?: JSONContent[];
+            marks?: {
+                type: string;
+                attrs?: Record<string, any>;
+                [key: string]: any;
+            }[];
+            text?: string;
+        };
+    };
+    editable: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    placeholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    extensions: {
+        type: PropType<AnyExtension[]>;
+        default: () => never[];
+    };
+    mentionItems: {
+        type: PropType<LoomaMentionItem[]>;
+        default: () => never[];
+    };
+    mentionProvider: {
+        type: PropType<LoomaMentionProvider | undefined>;
+        default: undefined;
+    };
+    mentionLimit: {
+        type: NumberConstructor;
+        default: number;
+    };
+    uploadImage: {
+        type: PropType<LoomaImageUploader | undefined>;
+        default: undefined;
+    };
+    resolveImageAttributes: {
+        type: PropType<LoomaImageAttributeResolver | undefined>;
+        default: undefined;
+    };
+    toolbarMode: {
+        type: PropType<LoomaEditorToolbarMode>;
+        default: string;
+    };
+}>> & Readonly<{
+    "onUpdate:modelValue"?: ((_value: JSONContent) => any) | undefined;
+    onUpdate?: ((_value: JSONContent) => any) | undefined;
+    onReady?: ((_editor: Editor) => any) | undefined;
+    onUploadError?: ((_error: unknown, _file: File) => any) | undefined;
+    onImageActivate?: ((_detail: LoomaImageActivationDetail) => any) | undefined;
+    onImageRenditionError?: ((_detail: LoomaImageRenditionErrorDetail) => any) | undefined;
+}>, {
+    placeholder: string;
+    modelValue: JSONContent;
+    editable: boolean;
+    extensions: AnyExtension[];
+    mentionItems: LoomaMentionItem[];
+    mentionProvider: LoomaMentionProvider | undefined;
+    mentionLimit: number;
+    uploadImage: LoomaImageUploader | undefined;
+    resolveImageAttributes: LoomaImageAttributeResolver | undefined;
+    toolbarMode: LoomaEditorToolbarMode;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/vue/editor/image-delivery.d.ts

@@ -0,0 +1,61 @@
+import { Extension, type Editor, type JSONContent } from "@tiptap/core";
+/** What caused an overlay to open or close. */
+type OverlayTrigger = "keyboard" | "pointer" | "programmatic";
+/**
+ * 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.
+ */
+export interface LoomaImageDescriptor {
+    src: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    responsive?: boolean;
+}
+/** Browser-only attributes resolved by a host image-delivery provider. */
+export interface LoomaImageRenditionAttributes {
+    src?: string;
+    srcset?: string;
+    sizes?: string;
+    loading?: "eager" | "lazy";
+    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.
+ */
+export type LoomaImageAttributeResolver = (image: LoomaImageDescriptor) => LoomaImageRenditionAttributes | undefined;
+/** User-originated interaction that may request the host's image viewer. */
+export 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.
+ */
+export 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.
+ */
+export interface LoomaImageRenditionErrorDetail extends LoomaImageDescriptor {
+    trigger: "programmatic";
+}
+interface LoomaImageDeliveryExtensionOptions {
+    resolveAttributes: () => LoomaImageAttributeResolver | undefined;
+}
+export declare function normalizeImageDimension(value: unknown): number | undefined;
+export declare function imageDescriptorFromAttrs(attrs: Record<string, unknown>): LoomaImageDescriptor | null;
+export declare function createLoomaImageDeliveryController(options: LoomaImageDeliveryExtensionOptions): {
+    extension: Extension;
+    markRenditionFailed: (editor: Editor, src: string) => boolean;
+    reset: (editor: Editor) => void;
+};
+export declare function imageUploadContent(image: LoomaImageDescriptor): JSONContent;
+export {};

package/vue/editor/index.d.ts

@@ -1,386 +1,4 @@
-import { LoomaMentionItem, SlashMenuAnchorRect, SlashMenuItem, LoomaMentionProvider } from '@threadlabs/looma/editor';
-export * from '@threadlabs/looma/editor';
-import * as vue from 'vue';
-import { PropType, VNode } from 'vue';
-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 {
-    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;
-        default: boolean;
-    };
-    query: {
-        type: StringConstructor;
-        default: string;
-    };
-    items: {
-        type: PropType<SlashMenuItem[]>;
-        default: () => never[];
-    };
-    selectedIndex: {
-        type: NumberConstructor;
-        default: number;
-    };
-    anchorRect: {
-        type: PropType<SlashMenuAnchorRect | null>;
-        default: null;
-    };
-    loading: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    open: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-    query: {
-        type: StringConstructor;
-        default: string;
-    };
-    items: {
-        type: PropType<SlashMenuItem[]>;
-        default: () => never[];
-    };
-    selectedIndex: {
-        type: NumberConstructor;
-        default: number;
-    };
-    anchorRect: {
-        type: PropType<SlashMenuAnchorRect | null>;
-        default: null;
-    };
-    loading: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>> & Readonly<{}>, {
-    open: boolean;
-    items: SlashMenuItem[];
-    query: string;
-    loading: boolean;
-    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;
-        default: boolean;
-    };
-    query: {
-        type: StringConstructor;
-        default: string;
-    };
-    items: {
-        type: PropType<LoomaMentionItem[]>;
-        default: () => never[];
-    };
-    selectedIndex: {
-        type: NumberConstructor;
-        default: number;
-    };
-    anchorRect: {
-        type: PropType<SlashMenuAnchorRect | null>;
-        default: null;
-    };
-    loading: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>, () => vue.VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    open: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-    query: {
-        type: StringConstructor;
-        default: string;
-    };
-    items: {
-        type: PropType<LoomaMentionItem[]>;
-        default: () => never[];
-    };
-    selectedIndex: {
-        type: NumberConstructor;
-        default: number;
-    };
-    anchorRect: {
-        type: PropType<SlashMenuAnchorRect | null>;
-        default: null;
-    };
-    loading: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-}>> & Readonly<{}>, {
-    open: boolean;
-    items: LoomaMentionItem[];
-    query: string;
-    loading: boolean;
-    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";
-    readonly EditorMentionMenu: "ui-editor-mention-menu";
-    readonly EditorTableContextMenu: "ui-editor-table-context-menu";
-    readonly EditorTableToolbar: "ui-editor-table-toolbar";
-    readonly EditorInsertTableGrid: "ui-editor-insert-table-grid";
-    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;
-    width?: number;
-    height?: number;
-    responsive?: boolean;
-}
-/** Browser-only attributes resolved by a host image-delivery provider. */
-interface LoomaImageRenditionAttributes {
-    src?: string;
-    srcset?: string;
-    sizes?: string;
-    loading?: "eager" | "lazy";
-    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>;
-        default: () => {
-            [key: string]: any;
-            type?: string;
-            attrs?: Record<string, any>;
-            content?: JSONContent[];
-            marks?: {
-                type: string;
-                attrs?: Record<string, any>;
-                [key: string]: any;
-            }[];
-            text?: string;
-        };
-    };
-    editable: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-    placeholder: {
-        type: StringConstructor;
-        default: string;
-    };
-    extensions: {
-        type: PropType<AnyExtension[]>;
-        default: () => never[];
-    };
-    mentionItems: {
-        type: PropType<LoomaMentionItem[]>;
-        default: () => never[];
-    };
-    mentionProvider: {
-        type: PropType<LoomaMentionProvider | undefined>;
-        default: undefined;
-    };
-    mentionLimit: {
-        type: NumberConstructor;
-        default: number;
-    };
-    uploadImage: {
-        type: PropType<LoomaImageUploader | undefined>;
-        default: undefined;
-    };
-    resolveImageAttributes: {
-        type: PropType<LoomaImageAttributeResolver | undefined>;
-        default: undefined;
-    };
-    toolbarMode: {
-        type: PropType<LoomaEditorToolbarMode>;
-        default: string;
-    };
-}>, () => VNode<vue.RendererNode, vue.RendererElement, {
-    [key: string]: any;
-}>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {
-    "update:modelValue": (_value: JSONContent) => true;
-    update: (_value: JSONContent) => true;
-    ready: (_editor: Editor) => true;
-    uploadError: (_error: unknown, _file: File) => true;
-    imageActivate: (_detail: LoomaImageActivationDetail) => true;
-    imageRenditionError: (_detail: LoomaImageRenditionErrorDetail) => true;
-}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
-    modelValue: {
-        type: PropType<JSONContent>;
-        default: () => {
-            [key: string]: any;
-            type?: string;
-            attrs?: Record<string, any>;
-            content?: JSONContent[];
-            marks?: {
-                type: string;
-                attrs?: Record<string, any>;
-                [key: string]: any;
-            }[];
-            text?: string;
-        };
-    };
-    editable: {
-        type: BooleanConstructor;
-        default: boolean;
-    };
-    placeholder: {
-        type: StringConstructor;
-        default: string;
-    };
-    extensions: {
-        type: PropType<AnyExtension[]>;
-        default: () => never[];
-    };
-    mentionItems: {
-        type: PropType<LoomaMentionItem[]>;
-        default: () => never[];
-    };
-    mentionProvider: {
-        type: PropType<LoomaMentionProvider | undefined>;
-        default: undefined;
-    };
-    mentionLimit: {
-        type: NumberConstructor;
-        default: number;
-    };
-    uploadImage: {
-        type: PropType<LoomaImageUploader | undefined>;
-        default: undefined;
-    };
-    resolveImageAttributes: {
-        type: PropType<LoomaImageAttributeResolver | undefined>;
-        default: undefined;
-    };
-    toolbarMode: {
-        type: PropType<LoomaEditorToolbarMode>;
-        default: string;
-    };
-}>> & Readonly<{
-    "onUpdate:modelValue"?: (_value: JSONContent) => any;
-    onUpdate?: (_value: JSONContent) => any;
-    onReady?: (_editor: Editor) => any;
-    onUploadError?: (_error: unknown, _file: File) => any;
-    onImageActivate?: (_detail: LoomaImageActivationDetail) => any;
-    onImageRenditionError?: (_detail: LoomaImageRenditionErrorDetail) => any;
-}>, {
-    placeholder: string;
-    modelValue: JSONContent;
-    editable: boolean;
-    extensions: AnyExtension[];
-    mentionItems: LoomaMentionItem[];
-    mentionProvider: LoomaMentionProvider | undefined;
-    mentionLimit: number;
-    uploadImage: LoomaImageUploader | undefined;
-    resolveImageAttributes: LoomaImageAttributeResolver | undefined;
-    toolbarMode: LoomaEditorToolbarMode;
-}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
-
-export { EDITOR_ADAPTER_COMPONENT_TAG_MAP, EditorInsertTableGrid, EditorMentionMenu, EditorSlashMenu, EditorTableContextMenu, EditorTableOverlay, EditorTableToolbar, EditorToolbar, LoomaEditor, type LoomaEditorToolbarMode, type LoomaImageActivationDetail, type LoomaImageActivationTrigger, type LoomaImageAttributeResolver, type LoomaImageDescriptor, type LoomaImageRenditionAttributes, type LoomaImageRenditionErrorDetail, type LoomaImageUploadResult, type LoomaImageUploader, type VueEditorAdapterEventMap };
+export * from "@threadlabs/looma/editor";
+export * from "./primitives.js";
+export { LoomaEditor, type LoomaEditorToolbarMode, type LoomaImageUploader, type LoomaImageUploadResult, } from "./LoomaEditor.js";
+export type { LoomaImageActivationDetail, LoomaImageActivationTrigger, LoomaImageAttributeResolver, LoomaImageDescriptor, LoomaImageRenditionErrorDetail, LoomaImageRenditionAttributes, } from "./image-delivery.js";