@threadlabs/looma 0.2.19 → 0.3.0

package/editor/extensions/index.d.ts

@@ -1,10 +1,12 @@
 import { Node, AnyExtension, Extension, Editor, Range } from '@tiptap/core';
-import { d as TableContextMenuActionEventDetail, g as TableOverlayActionEventDetail } from '../table-overlay-DoiLie4h.js';
-export { a as TABLE_CELL_BACKGROUND_PRESETS } from '../table-overlay-DoiLie4h.js';
+import { d as TableContextMenuActionEventDetail, g as TableOverlayActionEventDetail } from '../table-overlay-DZFGHQDt.js';
+export { a as TABLE_CELL_BACKGROUND_PRESETS } from '../table-overlay-DZFGHQDt.js';
 import { PluginKey } from '@tiptap/pm/state';
 import { LoomaIconName } from '@threadlabs/looma/core';
 
+/** Canonical tone values that may be persisted in a Looma callout node. */
 declare const LOOMA_CALLOUT_TONES: readonly ["info", "note", "warning"];
+/** A serialized callout tone; unsupported input is normalized to `note`. */
 type LoomaCalloutTone = (typeof LOOMA_CALLOUT_TONES)[number];
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
@@ -14,7 +16,12 @@ declare module "@tiptap/core" {
         };
     }
 }
-/** A durable, themeable block container for informational editor content. */
+/**
+ * A durable, themeable block container for informational editor content.
+ *
+ * @invariant Parsed and rendered `data-tone` values always belong to
+ * `LOOMA_CALLOUT_TONES`; missing or unknown values round-trip as `note`.
+ */
 declare const LoomaCallout: Node<any, any>;
 
 /**
@@ -22,19 +29,41 @@ declare const LoomaCallout: Node<any, any>;
  * Uses the Vanilla JS Tiptap API; apps provide @tiptap/core and Looma ships the preset extensions.
  */
 
+/**
+ * Deliberate policy knobs in Looma's default extension set.
+ * Consumers needing different schemas should compose an explicit Tiptap list
+ * rather than relying on undocumented mutation of the returned extensions.
+ */
 interface DefaultEditorExtensionsOptions {
+    /** Placeholder shown only for empty paragraphs, not every empty node type. */
     placeholder?: string;
+    /** Passed to Tiptap Link; defaults false to keep editing clicks in the editor. */
     linkOpenOnClick?: boolean;
+    /** Passed to Tiptap Image; block images are the default document policy. */
     imageInline?: boolean;
+    /** Custom mention extension, the Looma default, or false to omit mentions. */
     mention?: AnyExtension | false;
 }
-/** Complete Looma table support as one Tiptap extension. */
+/**
+ * Complete Looma table schema as one Tiptap extension.
+ * Use this in presets that want table, row, header, and cell nodes to remain an
+ * atomic policy choice; use `getLoomaTableExtensions` only when ordering or
+ * per-extension composition must be explicit.
+ *
+ * @invariant Installs exactly one compatible table, row, header, and cell node
+ * set so a preset cannot accidentally split Looma's persisted table schema.
+ */
 declare const LoomaTableKit: AnyExtension;
-/** Individual table extensions for consumers that prefer an explicit extension list. */
+/** Returns a fresh ordered list of the same schema extensions as `LoomaTableKit`. */
 declare function getLoomaTableExtensions(): AnyExtension[];
 /**
- * Returns the default Looma editor extensions (Vanilla Tiptap).
- * Use with new Editor({ extensions: getDefaultEditorExtensions(), ... }) or framework useEditor().
+ * Builds Looma's complete, ordered Tiptap extension policy.
+ *
+ * A fresh array is returned for each editor. Document nodes precede marks and
+ * behavior extensions; Looma's table/list policies are installed once; mention
+ * can be replaced without coupling UI chrome to an application directory.
+ * Use with `new Editor({ extensions: getDefaultEditorExtensions(), ... })` or a
+ * framework's Tiptap editor hook.
  */
 declare function getDefaultEditorExtensions(options?: DefaultEditorExtensionsOptions): AnyExtension[];
 
@@ -44,29 +73,92 @@ declare function getDefaultEditorExtensions(options?: DefaultEditorExtensionsOpt
  *
  * Source-editor metadata remains authoritative for non-document languages.
  * Explicit code-block context is never reinterpreted.
+ *
+ * @contract Recognized document markup is sanitized and dispatched as one paste
+ * transaction; every unrecognized or code-oriented payload returns control to
+ * Tiptap's remaining paste handlers without changing the document.
  */
 declare const LoomaSmartPaste: Extension<any, any>;
 
+/** Persistable horizontal alignments accepted by Looma table cells. */
 type TableCellAlignment = "left" | "center" | "right";
+/** CSS color stored in document attrs; null removes authored cell background. */
 type TableCellBackground = string | null;
+/**
+ * Looma's table behavior policy: resizable columns, stable minimum cell width,
+ * and no independently resizable trailing column. The narrow handle is also a
+ * Tiptap coordinate probe, so changing it affects selection as well as visuals.
+ *
+ * @invariant The 3px handle, 112px cell minimum, and fixed trailing edge are a
+ * coordinated selection-and-resize policy and must be changed together.
+ */
 declare const LoomaTable: AnyExtension;
+/**
+ * Header node that round-trips Looma alignment and background attributes.
+ *
+ * @contract Inherits the base header schema while normalizing authored styles
+ * into the same persisted attributes used by body cells.
+ */
 declare const LoomaTableHeader: AnyExtension;
+/**
+ * Body-cell node with the same persisted formatting contract as headers.
+ *
+ * @contract Inherits the base cell schema and shares header parsing/rendering so
+ * moving content between header and body cells does not change formatting data.
+ */
 declare const LoomaTableCell: AnyExtension;
+/**
+ * Reads formatting from the nearest cell/header ancestor of the selection.
+ * Left is the canonical default and is not serialized as an inline style.
+ *
+ * @contract Returns `left` outside a table cell and for missing, invalid, or
+ * explicitly default alignment attributes.
+ */
 declare function getActiveTableCellAlignment(editor: Editor): TableCellAlignment;
+/**
+ * Returns the nearest cell/header background, normalized so blank means absent.
+ *
+ * @contract Returns null outside a table cell and for non-string or whitespace-
+ * only attributes, matching the value used to clear persisted background CSS.
+ */
 declare function getActiveTableCellBackground(editor: Editor): TableCellBackground;
+/**
+ * Updates the active header or body cell and returns false outside a table cell.
+ * Setting left stores null, keeping the document free of redundant default CSS.
+ *
+ * @contract Focuses and updates only the active header or body cell; unsupported
+ * selections return false without creating a transaction.
+ */
 declare function setActiveTableCellAlignment(editor: Editor, alignment: TableCellAlignment): boolean;
+/**
+ * Updates the active header or body cell; blank strings normalize to null so
+ * clearing formatting removes persisted inline style instead of storing noise.
+ *
+ * @contract Focuses and updates only the active header or body cell; unsupported
+ * selections return false and blank values remove the persisted attribute.
+ */
 declare function setActiveTableCellBackground(editor: Editor, backgroundColor: TableCellBackground): boolean;
 
 /**
  * Table overlay action handler — maps boundaryIndex to Tiptap table commands.
- * Use with looma-editor-table-overlay-action: call this from the adapter's handler.
+ * Use with the table overlay's `action` event: call this from the adapter's handler.
  */
 
+/**
+ * Bounded initial shape for table insertion.
+ * Rows and columns are clamped to 1–10 by `insertTableAtRange` so slash-command
+ * or custom UI input cannot create an accidentally unbounded transaction.
+ */
 interface InsertTableAtRangeOptions {
     rows?: number;
     cols?: number;
     withHeaderRow?: boolean;
 }
+/**
+ * Command availability calculated from the current ProseMirror selection.
+ * Keeping capabilities beside UI state prevents toolbars from duplicating
+ * Tiptap's schema/selection rules or optimistically enabling invalid actions.
+ */
 interface TableActionCapabilities {
     canAddRowBefore: boolean;
     canAddRowAfter: boolean;
@@ -78,6 +170,12 @@ interface TableActionCapabilities {
     canMergeCells: boolean;
     canSplitCell: boolean;
 }
+/**
+ * One replaceable snapshot for editor-owned table chrome.
+ * Consumers should discard prior capabilities whenever `active` becomes false;
+ * they describe the current ProseMirror transaction state, not table schema in
+ * general.
+ */
 interface ActiveTableUiState {
     active: boolean;
     showToolbar: boolean;
@@ -85,50 +183,114 @@ interface ActiveTableUiState {
     cellBackground: TableCellBackground;
     capabilities: TableActionCapabilities;
 }
-/** Text formatting belongs to actual text selections, not table CellSelections. */
+/**
+ * Text formatting belongs to actual text selections, not table CellSelections.
+ *
+ * @contract Returns true only for an editable editor with a non-collapsed
+ * `TextSelection`; node and cell selections never activate formatting chrome.
+ */
 declare function shouldShowTextFormattingToolbar(editor: Editor, from?: number, to?: number): boolean;
-/** Returns Looma's complete interaction state for the table containing the selection. */
+/**
+ * Returns the complete interaction state for the table containing the selection.
+ * Inactive defaults are concrete so UI can replace its previous snapshot and
+ * cannot accidentally retain enabled controls from a table that lost selection.
+ *
+ * @contract Capabilities are recalculated from `editor.can()` at call time; an
+ * inactive snapshot disables every action and resets authored cell formatting.
+ */
 declare function getActiveTableUiState(editor: Editor): ActiveTableUiState;
-/** Executes a toolbar/context-menu action using Looma's table behavior policy. */
+/**
+ * Executes a toolbar/context-menu action using Looma's table behavior policy.
+ * The boolean is Tiptap's command result, so callers can distinguish a handled
+ * action from one rejected by the current schema or selection.
+ *
+ * @contract The event action becomes one focused Tiptap transaction; UI callers
+ * never need to reproduce selection repair or cell-format policy.
+ * @failure Returns false when the current selection cannot support the action.
+ */
 declare function handleTableAction(editor: Editor, detail: TableContextMenuActionEventDetail): boolean;
 /**
  * Deletes a slash-command range (or other inline trigger text) and inserts a table.
- * Use this when apps want a stable default `/table` behavior without owning table policy.
+ * Use this when apps want a stable default `/table` behavior without owning
+ * table policy. Deletion and insertion share one focused command chain, so the
+ * trigger text cannot remain behind if insertion succeeds.
+ *
+ * @contract Rows and columns are clamped to 1–10, then range deletion and table
+ * insertion succeed or fail together through a single Tiptap command chain.
  */
 declare function insertTableAtRange(editor: Editor, range: Range, options?: InsertTableAtRangeOptions): boolean;
 /**
- * Reconciles rendered column widths back into table-cell colwidth attrs so a resized
- * full-width table stays inside the editor width after resize completes.
+ * Reconciles rendered column widths back into table-cell `colwidth` attributes.
+ *
+ * Browser layout is the source of truth at the end of a pointer resize, but
+ * ProseMirror must persist integer widths in the document. The algorithm keeps
+ * proportions, enforces a minimum, and distributes rounding error so the final
+ * sum still equals the rendered table width. Spanning cells are updated once at
+ * their top-left map coordinate rather than once per covered grid position.
+ *
+ * @invariant Every persisted width is an integer at least `minWidth`, and each
+ * spanning cell receives one width per logical column from its top-left origin.
+ * @failure Returns false without an active table or measurable columns and does
+ * not dispatch when persisted widths already match the rendered geometry.
  */
 declare function normalizeActiveTableColumnWidths(editor: Editor, tableElement: HTMLTableElement, minWidth?: number): boolean;
 /**
- * Handles a table overlay action by selecting the target cell and running the Tiptap command.
- * Call this from your adapter's onTableOverlayAction handler.
+ * Handles a geometry-derived table-overlay intent without exposing ProseMirror
+ * positions to UI components.
+ *
+ * Boundary indices address the visual grid edges measured by the overlay. The
+ * helper maps them into the current table transaction, rejects indices that do
+ * not represent a legal insertion edge, dispatches once, and restores editor
+ * focus. `open-cell-menu` returns handled without editing because menu ownership
+ * remains with the application/adapter.
  *
- * @example
- * ```vue
- * <EditorTableOverlay
- *   :open="tableOverlayOpen"
- *   :rows="tableRows"
- *   :cols="tableCols"
- *   @looma-editor-table-overlay-action="(e) => handleTableOverlayAction(editor, e.detail)"
- * />
- * ```
+ * @contract A valid structural intent dispatches at most one transaction;
+ * `open-cell-menu` acknowledges UI ownership without mutating the document.
+ * @failure Missing tables, malformed payloads, and out-of-range boundaries
+ * return false before dispatching a transaction.
  */
 declare function handleTableOverlayAction(editor: Editor, detail: TableOverlayActionEventDetail): boolean;
 
+/** Default visible candidate budget when an application does not set a limit. */
 declare const DEFAULT_MENTION_RESULT_LIMIT = 8;
+/** Hard candidate ceiling shared by providers, keyboard state, and menu rendering. */
 declare const MAX_MENTION_RESULT_LIMIT = 20;
+/**
+ * Application-owned identity and display data for one mention candidate.
+ * Looma persists `id` and `label` in the editor document; `detail` and
+ * `initials` are presentation hints and are not part of mention identity.
+ */
 interface LoomaMentionItem {
     id: string;
     label: string;
     detail?: string;
     initials?: string;
 }
+/** Bounded result budget passed to a directory provider for the current query. */
 interface LoomaMentionProviderContext {
     limit: number;
 }
+/**
+ * Resolves candidates for the current query.
+ *
+ * Providers may perform asynchronous directory lookup, but should return no
+ * more than `context.limit`. The extension also clamps and filters results so a
+ * provider cannot accidentally create an unbounded suggestion surface.
+ *
+ * @ownership The application owns directory access and returned item data;
+ * Looma owns filtering, clamping, and the suggestion state that consumes it.
+ */
 type LoomaMentionProvider = (query: string, context: LoomaMentionProviderContext) => readonly LoomaMentionItem[] | Promise<readonly LoomaMentionItem[]>;
+/**
+ * Complete render state handed from the headless Tiptap extension to UI chrome.
+ *
+ * The snapshot owns selection commands only while `active` is true. Consumers
+ * should replace, not merge, snapshots: callbacks and rectangles are tied to a
+ * particular suggestion range and become stale as soon as the query changes.
+ *
+ * @lifecycle `highlight` and `select` are valid only while this snapshot remains
+ * active; the next query update or exit invalidates both callbacks.
+ */
 interface LoomaMentionMenuSnapshot {
     active: boolean;
     items: LoomaMentionItem[];
@@ -139,13 +301,33 @@ interface LoomaMentionMenuSnapshot {
     highlight: ((index: number) => void) | null;
     select: ((index: number) => void) | null;
 }
+/**
+ * Mention policy supplied by the application.
+ *
+ * Looma owns suggestion mechanics and accessibility state; the application
+ * owns the directory and may render the snapshot with Looma's menu or custom
+ * UI. `menuId` must match that UI's listbox id so `aria-controls` and
+ * `aria-activedescendant` reference real elements.
+ *
+ * @ownership The application owns provider work and rendering callbacks; Looma
+ * owns transient selection state and restores every borrowed editor ARIA value.
+ */
 interface LoomaMentionOptions {
     items?: readonly LoomaMentionItem[] | LoomaMentionProvider;
     limit?: number;
     menuId?: string;
     onStateChange?: (state: LoomaMentionMenuSnapshot) => void;
 }
+/** Clamps public/provider limits so keyboard navigation remains predictably bounded. */
 declare function normalizeMentionResultLimit(limit?: number): number;
+/**
+ * Applies Looma's local fallback matching to static or provider results.
+ * Matching is intentionally limited to display text; stable ids and arbitrary
+ * metadata must not become discoverable search fields by accident.
+ *
+ * @contract Preserves source order, does not mutate the input, and returns no
+ * more than the normalized public result limit.
+ */
 declare function filterLoomaMentionItems(items: readonly LoomaMentionItem[], query: string, limit?: number): LoomaMentionItem[];
 
 interface MentionPluginState {
@@ -156,17 +338,43 @@ interface MentionPluginState {
         to: number;
     };
 }
+/**
+ * Stable key for reading Looma's active mention query and source range.
+ * Consumers should treat the keyed value as transient suggestion state rather
+ * than document data.
+ */
 declare const LoomaMentionSuggestionPluginKey: PluginKey<MentionPluginState>;
 /**
- * Domain-neutral Tiptap mention node and suggestion lifecycle. Applications
- * provide either a small static list or a bounded async directory provider.
+ * Creates a domain-neutral Tiptap mention node and suggestion lifecycle.
+ *
+ * Applications provide either a small static list or a bounded async directory
+ * provider. Looma owns keyboard selection plus the temporary combobox ARIA
+ * attributes on the editor. Every attribute is snapshotted and restored so
+ * installing this extension cannot erase accessibility state owned by another
+ * extension or by the host application.
+ *
+ * @ownership The application owns the item provider and rendered menu. The
+ * extension owns suggestion state and only borrows editor ARIA attributes.
+ * @lifecycle Each suggestion update replaces the published snapshot; exit
+ * restores borrowed attributes and invalidates callbacks from the prior range.
+ * @failure Provider rejection degrades to an empty result set so Tiptap's
+ * suggestion lifecycle cannot become an unhandled promise rejection.
  */
 declare function createLoomaMentionExtension(options?: LoomaMentionOptions): AnyExtension;
 
+/** Editor state a slash command may replace and then act upon. */
 interface LoomaSlashCommandContext {
     editor: Editor;
     range: Range;
 }
+/**
+ * Ephemeral render model published to any slash-menu UI.
+ * Replace snapshots rather than merging them: the `select` callback closes over
+ * a particular Tiptap range and becomes invalid when the suggestion updates.
+ *
+ * @lifecycle `select` is valid only until the next snapshot or suggestion exit;
+ * retaining it can apply a command to a stale source range.
+ */
 interface LoomaSlashMenuSnapshot {
     active: boolean;
     items: LoomaSlashCommand[];
@@ -175,12 +383,36 @@ interface LoomaSlashMenuSnapshot {
     rect: DOMRect | null;
     select: ((index: number) => void) | null;
 }
+/**
+ * Application-owned command inventory and integration callbacks.
+ * Replacing `commands` changes search and execution together; the extension
+ * never merges domain commands into defaults implicitly. Asset selection stays
+ * callback-driven because uploads and persistence are outside editor ownership.
+ *
+ * @ownership The application owns command objects and callback side effects;
+ * the extension only searches the inventory and publishes replacement snapshots.
+ */
 interface LoomaSlashCommandOptions {
     commands: LoomaSlashCommand[];
     onStateChange?: (state: LoomaSlashMenuSnapshot) => void;
     onOpenImagePicker?: () => void;
 }
+/**
+ * Builds Looma's default command policy as fresh objects for one editor.
+ * The image command delegates asset selection because Looma does not own upload,
+ * persistence, or media-library concerns.
+ *
+ * @ownership Returned command objects belong to the caller and are recreated
+ * per call so one editor cannot mutate another editor's command inventory.
+ */
 declare function getDefaultSlashCommands(onOpenImagePicker?: () => void): LoomaSlashCommand[];
+/**
+ * One application-extensible command.
+ *
+ * Commands own their editor mutation, including removal of `context.range`.
+ * Keeping that policy in the command lets custom items behave exactly like
+ * built-ins without coupling the headless suggestion lifecycle to Tiptap nodes.
+ */
 interface LoomaSlashCommand {
     title: string;
     description: string;
@@ -192,8 +424,21 @@ interface LoomaSlashCommand {
  * Framework-neutral slash-command extension used by the turnkey editor.
  * Consumers embedding Looma into their own Tiptap instance can configure the
  * same behavior and render any menu they choose from `onStateChange`.
+ *
+ * @ownership The extension owns query and keyboard-selection state; the caller
+ * owns the command inventory and every menu snapshot after publication.
+ * @lifecycle Snapshot callbacks are valid only for the suggestion range that
+ * produced them and are replaced on every update or exit.
  */
 declare const LoomaSlashCommand: Extension<LoomaSlashCommandOptions, any>;
+/**
+ * Creates an independently configured extension instance.
+ * Prefer this factory when callbacks or commands are editor-specific; the
+ * exported base extension remains a convenient zero-configuration preset.
+ *
+ * @ownership The caller owns supplied commands and callbacks. The returned
+ * extension captures them for one configuration without mutating the inventory.
+ */
 declare function createLoomaSlashCommandExtension(options?: Partial<LoomaSlashCommandOptions>): Extension<LoomaSlashCommandOptions, any>;
 
 export { type ActiveTableUiState, DEFAULT_MENTION_RESULT_LIMIT, type DefaultEditorExtensionsOptions, type InsertTableAtRangeOptions, LOOMA_CALLOUT_TONES, LoomaCallout, type LoomaCalloutTone, type LoomaMentionItem, type LoomaMentionMenuSnapshot, type LoomaMentionOptions, type LoomaMentionProvider, type LoomaMentionProviderContext, LoomaMentionSuggestionPluginKey, LoomaSlashCommand, type LoomaSlashCommandContext, LoomaSlashCommand as LoomaSlashCommandItem, type LoomaSlashCommandOptions, type LoomaSlashMenuSnapshot, LoomaSmartPaste, LoomaTable, LoomaTableCell, LoomaTableHeader, LoomaTableKit, MAX_MENTION_RESULT_LIMIT, type TableActionCapabilities, type TableCellAlignment, type TableCellBackground, createLoomaMentionExtension, createLoomaSlashCommandExtension, filterLoomaMentionItems, getActiveTableCellAlignment, getActiveTableCellBackground, getActiveTableUiState, getDefaultEditorExtensions, getDefaultSlashCommands, getLoomaTableExtensions, handleTableAction, handleTableOverlayAction, insertTableAtRange, normalizeActiveTableColumnWidths, normalizeMentionResultLimit, setActiveTableCellAlignment, setActiveTableCellBackground, shouldShowTextFormattingToolbar };

package/editor/index.d.ts

@@ -1,4 +1,4 @@
-export { A as ActiveCellRect, T as TABLE_CELL_BACKGROUND_OPTIONS, a as TABLE_CELL_BACKGROUND_PRESETS, b as TableCellBackgroundAction, c as TableContextMenuAction, d as TableContextMenuActionEventDetail, e as TableInsertionAction, f as TableOverlayAction, g as TableOverlayActionEventDetail, h as TableOverlayGeometry, d as TableToolbarActionEventDetail, m as measureTableOverlayGeometry, r as resolveTableCellAt } from './table-overlay-DoiLie4h.js';
+export { A as ActiveCellRect, T as TABLE_CELL_BACKGROUND_OPTIONS, a as TABLE_CELL_BACKGROUND_PRESETS, b as TableCellBackgroundAction, c as TableContextMenuAction, d as TableContextMenuActionEventDetail, e as TableInsertionAction, f as TableOverlayAction, g as TableOverlayActionEventDetail, h as TableOverlayGeometry, d as TableToolbarActionEventDetail, m as measureTableOverlayGeometry, r as resolveTableCellAt } from './table-overlay-DZFGHQDt.js';
 export { InsertTableEventDetail, MentionMenuHighlightEventDetail, MentionMenuSelectEventDetail, SlashMenuAnchorRect, SlashMenuHighlightEventDetail, SlashMenuItem, SlashMenuSelectEventDetail } from './ui.js';
 export { ActiveTableUiState, DEFAULT_MENTION_RESULT_LIMIT, DefaultEditorExtensionsOptions, InsertTableAtRangeOptions, LOOMA_CALLOUT_TONES, LoomaCallout, LoomaCalloutTone, LoomaMentionItem, LoomaMentionMenuSnapshot, LoomaMentionOptions, LoomaMentionProvider, LoomaMentionProviderContext, LoomaMentionSuggestionPluginKey, LoomaSlashCommand, LoomaSlashCommandContext, LoomaSlashCommand as LoomaSlashCommandItem, LoomaSlashCommandOptions, LoomaSlashMenuSnapshot, LoomaSmartPaste, LoomaTable, LoomaTableCell, LoomaTableHeader, LoomaTableKit, MAX_MENTION_RESULT_LIMIT, TableActionCapabilities, TableCellAlignment, TableCellBackground, createLoomaMentionExtension, createLoomaSlashCommandExtension, filterLoomaMentionItems, getActiveTableCellAlignment, getActiveTableCellBackground, getActiveTableUiState, getDefaultEditorExtensions, getDefaultSlashCommands, getLoomaTableExtensions, handleTableAction, handleTableOverlayAction, insertTableAtRange, normalizeActiveTableColumnWidths, normalizeMentionResultLimit, setActiveTableCellAlignment, setActiveTableCellBackground, shouldShowTextFormattingToolbar } from './extensions/index.js';
 import '@threadlabs/looma/core';

package/editor/index.js

@@ -1,7 +1,7 @@
 import {
   measureTableOverlayGeometry,
   resolveTableCellAt
-} from "./chunk-WI7ZA44X.js";
+} from "./chunk-U36XNFJN.js";
 import {
   DEFAULT_MENTION_RESULT_LIMIT,
   LOOMA_CALLOUT_TONES,

package/editor/{table-overlay-DoiLie4h.d.ts → table-overlay-DZFGHQDt.d.ts}

@@ -1,3 +1,4 @@
+/** Canonical persisted colors shared by editor commands and table UI swatches. */
 declare const TABLE_CELL_BACKGROUND_PRESETS: {
     readonly none: null;
     readonly gray: "#f3f4f6";
@@ -6,6 +7,7 @@ declare const TABLE_CELL_BACKGROUND_PRESETS: {
     readonly green: "#dcfce7";
     readonly red: "#fee2e2";
 };
+/** Ordered menu choices coupling each UI intent to its persisted color value. */
 declare const TABLE_CELL_BACKGROUND_OPTIONS: readonly [{
     readonly action: "background-none";
     readonly label: "Default";
@@ -37,15 +39,18 @@ declare const TABLE_CELL_BACKGROUND_OPTIONS: readonly [{
     readonly value: "#fee2e2";
     readonly swatch: "#fee2e2";
 }];
+/** Background-only action vocabulary derived from the canonical menu choices. */
 type TableCellBackgroundAction = typeof TABLE_CELL_BACKGROUND_OPTIONS[number]["action"];
 
+/** Intent contracts shared by declarative table menus and editor adapters. */
+
 /**
- * ui-editor-table-context-menu — web component for table cell context menu.
- * Emits custom events for each action; the adapter (Vue/React) wires Tiptap commands.
- * Domain-neutral: no Tiptap dependency.
+ * Complete intent vocabulary emitted by table chrome for an adapter to execute.
+ * Keeping this as data prevents the reusable menu from importing or mutating a
+ * particular editor implementation.
  */
-
 type TableContextMenuAction = "align-left" | "align-center" | "align-right" | TableCellBackgroundAction | "add-row-before" | "add-row-after" | "add-column-before" | "add-column-after" | "delete-row" | "delete-column" | "delete-table" | "clear-cells" | "merge-cells" | "split-cell";
+/** Adapter-facing payload that keeps the menu independent of editor commands. */
 interface TableContextMenuActionEventDetail {
     action: TableContextMenuAction;
 }
@@ -54,8 +59,20 @@ interface TableContextMenuActionEventDetail {
  * ui-editor-table-overlay — anticipatory table affordances.
  * Domain-neutral: it emits intent while the adapter owns editor commands.
  */
+/** Table-structure mutations addressed by a measured row/column boundary. */
 type TableInsertionAction = "add-row-before" | "add-row-after" | "add-column-before" | "add-column-after";
+/**
+ * Intent vocabulary emitted by the headless table overlay.
+ * UI stays independent of Tiptap/ProseMirror positions; adapters translate
+ * these logical coordinates with `handleTableOverlayAction`.
+ */
 type TableOverlayAction = TableInsertionAction | "select-row" | "select-column" | "open-cell-menu";
+/**
+ * Discriminated action payload.
+ * Boundary indices refer to entries in the measured boundary arrays. Cell
+ * indices refer to the logical grid after row/column spans are expanded. The
+ * menu anchor uses CSS-pixel viewport coordinates suitable for fixed surfaces.
+ */
 type TableOverlayActionEventDetail = {
     action: TableInsertionAction;
     boundaryIndex: number;
@@ -74,6 +91,11 @@ type TableOverlayActionEventDetail = {
         bottom: number;
     };
 };
+/**
+ * A cell rectangle relative to the table's border box, plus logical grid
+ * coordinates. Width/height include spans because they come from the rendered
+ * cell rather than an inferred uniform grid.
+ */
 interface ActiveCellRect {
     left: number;
     top: number;
@@ -82,15 +104,35 @@ interface ActiveCellRect {
     rowIndex: number;
     columnIndex: number;
 }
+/**
+ * Replaceable geometry snapshot for overlay rendering.
+ * Boundaries are CSS-pixel offsets relative to the table; callers should
+ * remeasure after editor transactions or layout changes rather than mutate the
+ * arrays in place.
+ */
 interface TableOverlayGeometry {
     rowBoundaries: number[];
     columnBoundaries: number[];
     activeCell: ActiveCellRect | null;
     hoveredCell?: ActiveCellRect | null;
 }
-/** Resolves a logical table coordinate, including cells that span rows or columns. */
+/**
+ * Resolves a logical grid coordinate to its owning DOM cell.
+ * A spanning cell can therefore be returned for more than one coordinate; this
+ * is intentional and prevents overlay actions from inventing nonexistent cells.
+ *
+ * @contract Coordinates outside the expanded table grid return null; coordinates
+ * covered by a span resolve to the single DOM cell that owns them.
+ */
 declare function resolveTableCellAt(table: HTMLTableElement, rowIndex: number, columnIndex: number): HTMLTableCellElement | null;
-/** Measures real rendered boundaries, including non-uniform and merged cells. */
+/**
+ * Measures rendered boundaries rather than assuming a uniform table grid.
+ * Returned offsets are table-relative and rounded to hundredths of a CSS pixel
+ * to suppress observer churn without losing subpixel layout fidelity.
+ *
+ * @contract Active and hovered rectangles are returned only for cells contained
+ * by the supplied table; detached or foreign cells are represented as null.
+ */
 declare function measureTableOverlayGeometry(table: HTMLTableElement, activeCell: HTMLTableCellElement | null, hoveredCell?: HTMLTableCellElement | null): TableOverlayGeometry;
 
 export { type ActiveCellRect as A, TABLE_CELL_BACKGROUND_OPTIONS as T, TABLE_CELL_BACKGROUND_PRESETS as a, type TableCellBackgroundAction as b, type TableContextMenuAction as c, type TableContextMenuActionEventDetail as d, type TableInsertionAction as e, type TableOverlayAction as f, type TableOverlayActionEventDetail as g, type TableOverlayGeometry as h, measureTableOverlayGeometry as m, resolveTableCellAt as r };

package/editor/ui.d.ts

@@ -1,38 +1,41 @@
-export { A as ActiveCellRect, T as TABLE_CELL_BACKGROUND_OPTIONS, a as TABLE_CELL_BACKGROUND_PRESETS, b as TableCellBackgroundAction, c as TableContextMenuAction, d as TableContextMenuActionEventDetail, e as TableInsertionAction, f as TableOverlayAction, g as TableOverlayActionEventDetail, h as TableOverlayGeometry, d as TableToolbarActionEventDetail, m as measureTableOverlayGeometry, r as resolveTableCellAt } from './table-overlay-DoiLie4h.js';
+export { A as ActiveCellRect, T as TABLE_CELL_BACKGROUND_OPTIONS, a as TABLE_CELL_BACKGROUND_PRESETS, b as TableCellBackgroundAction, c as TableContextMenuAction, d as TableContextMenuActionEventDetail, e as TableInsertionAction, f as TableOverlayAction, g as TableOverlayActionEventDetail, h as TableOverlayGeometry, d as TableToolbarActionEventDetail, m as measureTableOverlayGeometry, r as resolveTableCellAt } from './table-overlay-DZFGHQDt.js';
 import { LoomaIconName } from '@threadlabs/looma/core';
 
-/**
- * ui-editor-insert-table-grid — web component for picking table dimensions.
- * Emits looma-editor-insert-table with { rows, cols, withHeaderRow }.
- * Domain-neutral: no Tiptap dependency.
- */
+/** Event contract for the declarative table-dimension picker. */
+/** Confirmed table dimensions emitted after preview state has been committed. */
 interface InsertTableEventDetail {
     rows: number;
     cols: number;
     withHeaderRow: boolean;
 }
 
-/** ui-editor-mention-menu — bounded, accessible mention suggestions. */
+/** Event contracts for the declarative mention menu. */
+/** Zero-based candidate position requested by pointer-driven menu highlighting. */
 interface MentionMenuHighlightEventDetail {
     index: number;
 }
+/** Zero-based candidate position the host should commit as the chosen mention. */
 interface MentionMenuSelectEventDetail {
     index: number;
 }
 
+/** Public data and event contracts for the declarative slash-command menu. */
+
 /**
- * ui-editor-slash-menu — floating slash-command menu.
- * Apps own the command list and suggestion state; Looma owns the chrome.
+ * Presentation projection of a slash command.
+ * It intentionally omits editor callbacks: the menu emits an index and the
+ * headless extension executes the command from its current ephemeral snapshot.
  */
-
 interface SlashMenuItem {
     title: string;
     description: string;
     icon: LoomaIconName;
 }
+/** Pointer-hover request; selection remains owned by the suggestion extension. */
 interface SlashMenuHighlightEventDetail {
     index: number;
 }
+/** Activation request for an item in the current published snapshot. */
 interface SlashMenuSelectEventDetail {
     index: number;
 }
@@ -41,7 +44,8 @@ interface SlashMenuSelectEventDetail {
  *
  * Browser DOMRect objects satisfy both variants. Plain rectangles from Tiptap
  * and ProseMirror are also supported when they provide either edge coordinates
- * or an origin plus dimensions.
+ * or an origin plus dimensions. Values use CSS-pixel viewport coordinates; the
+ * menu converts them into visual-viewport-aware fixed positioning.
  */
 type SlashMenuAnchorRect = Pick<DOMRectReadOnly, "left" | "top" | "right" | "bottom"> | Pick<DOMRectReadOnly, "x" | "y" | "width" | "height">;
 

package/editor/ui.js

@@ -1,7 +1,7 @@
 import {
   measureTableOverlayGeometry,
   resolveTableCellAt
-} from "./chunk-WI7ZA44X.js";
+} from "./chunk-U36XNFJN.js";
 import {
   TABLE_CELL_BACKGROUND_OPTIONS,
   TABLE_CELL_BACKGROUND_PRESETS