@threadlabs/looma 0.28.1 → 0.28.3

package/components/shared/overlay.js

@@ -235,8 +235,22 @@ export function writtenPlace(surface, ownedStyles = []) {
   return { rect, floating };
 }
 
-function fallbackPosition(surface, anchor, placement, gap, viewportGap, surfaceRect = layoutRect(surface)) {
-  const bounds = viewport(surface.ownerDocument.defaultView);
+// The visible part of a boundary element, or the visual viewport when there is none or it is off screen.
+function containment(surface, boundary) {
+  const visible = viewport(surface.ownerDocument.defaultView);
+  const element = typeof boundary === "function" ? boundary() : boundary;
+  if (!element) return visible;
+  const box = element.getBoundingClientRect();
+  const left = Math.max(visible.left, box.left);
+  const top = Math.max(visible.top, box.top);
+  const right = Math.min(visible.right, box.right);
+  const bottom = Math.min(visible.bottom, box.bottom);
+  if (right <= left || bottom <= top) return visible;
+  return { left, top, right, bottom, width: right - left, height: bottom - top };
+}
+
+function fallbackPosition(surface, anchor, placement, gap, viewportGap, surfaceRect = layoutRect(surface), boundary = null) {
+  const bounds = containment(surface, boundary);
   const [preferred, align = "center"] = placement.split("-");
   const side = ["top", "bottom", "left", "right"].includes(preferred) ? preferred : "bottom";
   const opposite = { top: "bottom", bottom: "top", left: "right", right: "left" }[side];
@@ -271,9 +285,12 @@ function fallbackPosition(surface, anchor, placement, gap, viewportGap, surfaceR
   surface.style.bottom = "auto";
 }
 
-/** Applies the shared flip/shift policy to a live element or consumer-supplied virtual rectangle. */
+/**
+ * Applies the shared flip/shift policy to a live element or consumer-supplied virtual rectangle.
+ * `boundary` (an element, or a function returning one) narrows the room to its visible part.
+ */
 export function positionAnchoredSurface(surface, rect, options = {}) {
-  fallbackPosition(surface, rect, options.placement ?? "bottom-start", options.gap ?? 4, options.viewportGap ?? 8);
+  fallbackPosition(surface, rect, options.placement ?? "bottom-start", options.gap ?? 4, options.viewportGap ?? 8, undefined, options.boundary);
 }
 
 /**
@@ -379,6 +396,7 @@ export function createAnchoredSurface(surface, options = {}) {
   let placement = options.placement ?? "bottom-start";
   const gap = () => Math.max(0, Number(typeof options.gap === "function" ? options.gap() : options.gap ?? 4) || 0);
   const viewportGap = Math.max(0, options.viewportGap ?? 8);
+  const boundary = options.boundary ?? null;
   let anchor = options.anchor ?? null;
   let point = null;
   let open = false;
@@ -402,17 +420,22 @@ export function createAnchoredSurface(surface, options = {}) {
     // A disappearing trigger has no usable position. Keep the last valid position, or wait before first opening.
     if (!point && typeof anchor !== "function" && (anchor.isConnected === false || rect.width === 0 && rect.height === 0
       || anchor instanceof owner.Element && owner.getComputedStyle(anchor).visibility !== "visible")) {
-      if (lastAnchorRect) positionAnchoredSurface(surface, lastAnchorRect, { placement, gap: gap(), viewportGap });
+      if (lastAnchorRect) positionAnchoredSurface(surface, lastAnchorRect, { placement, gap: gap(), viewportGap, boundary });
       else hide(surface);
       return;
     }
     lastAnchorRect = { left: rect.left, top: rect.top, right: rect.right, bottom: rect.bottom, width: rect.width, height: rect.height };
     show(surface);
-    positionAnchoredSurface(surface, rect, { placement: point ? "bottom-start" : placement, gap: gap(), viewportGap });
+    if (options.maxWidth !== undefined) {
+      const maxWidth = typeof options.maxWidth === "function" ? options.maxWidth() : options.maxWidth;
+      surface.style.maxWidth = maxWidth === null ? "" : `${maxWidth}px`;
+    }
+    positionAnchoredSurface(surface, rect, { placement: point ? "bottom-start" : placement, gap: gap(), viewportGap, boundary });
   };
   surface.style.position = "fixed";
   surface.style.margin = "0";
-  const presentation = createViewportSurface(surface, { position });
+  // `bare` resets the browser's popover chrome on a surface that has none of its own.
+  const presentation = createViewportSurface(surface, { position, bare: options.bare });
   // Resize and scroll events do not report an ancestor's transition or layout shift.
   // While visible, sample the live anchor and only re-position when its bounds change.
   const trackAnchor = () => {

package/editor/selection-surface.d.ts

@@ -0,0 +1,66 @@
+import { type Editor } from "@tiptap/core";
+import { type EditorState } from "@tiptap/pm/state";
+import type { EditorView } from "@tiptap/pm/view";
+type Rect = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};
+/** What `shouldShow` receives on each selection or document change. */
+export interface SelectionSurfaceContext {
+    editor: Editor;
+    view: EditorView;
+    state: EditorState;
+    oldState?: EditorState;
+    from: number;
+    to: number;
+}
+export interface SelectionSurfaceOptions {
+    editor: Editor;
+    /**
+     * The surface element, the only child of a host element that stays in place. It leaves the
+     * document while closed, so its content is absent rather than hidden, and returns to the host,
+     * in the top layer, while open.
+     */
+    element: HTMLElement;
+    pluginKey: string;
+    shouldShow(context: SelectionSurfaceContext): boolean;
+    /** Waits this long after the last change before deciding, for non-empty selections. */
+    updateDelay?: number;
+    placement?: "top" | "bottom";
+    /** The rectangle to anchor to; the selection's by default. */
+    anchor?: () => Rect;
+    /** Keeps the surface inside this element as well as the viewport. */
+    boundary?: () => HTMLElement | null;
+    maxWidth?: () => number | null;
+    /** Elements whose pointer presses do not dismiss the surface, such as the editor's own root. */
+    related?: () => HTMLElement[];
+    /** Return false to keep the surface open, for example while a picker in it has focus. */
+    onHide?: () => boolean | void;
+    /** Escape or a press outside reached this surface first on the shared overlay stack. */
+    onDismiss?: (reason: "escape" | "light-dismiss") => void;
+}
+/** A selection-anchored surface: the editor's floating toolbar, link card, and image actions. */
+export interface SelectionSurface {
+    readonly element: HTMLElement;
+    isOpen(): boolean;
+    show(): void;
+    hide(): void;
+    /** Anchors to `anchor` until the next change the surface decides on. */
+    setAnchor(anchor: () => Rect): void;
+    destroy(): void;
+}
+/**
+ * Shows `element` beside the selection whenever `shouldShow` allows, as Tiptap's bubble menu does,
+ * and presents it through Looma's shared overlay layer: in the top layer, placed by the shared
+ * flip/shift policy, travelling with its anchor, and registered on the overlay stack.
+ *
+ * @lifecycle Registers a ProseMirror plugin now; `destroy()` unregisters it and closes the surface.
+ * The editor destroying its view closes the surface too.
+ * @contract A press inside the surface keeps it open when the editor blurs; dragging hides it.
+ */
+export declare function createSelectionSurface(options: SelectionSurfaceOptions): SelectionSurface;
+export {};

package/editor/session.d.ts

@@ -0,0 +1,39 @@
+import { Editor, type EditorOptions, type JSONContent } from "@tiptap/core";
+import { type Selection, type SelectionBookmark } from "@tiptap/pm/state";
+/** A selection remembered so a controlled document replacement can put it back. */
+export interface LoomaSelectionSnapshot {
+    bookmark: SelectionBookmark;
+    from: number;
+    to: number;
+    text: boolean;
+}
+export declare function selectionSnapshot(selection: Selection): LoomaSelectionSnapshot;
+/**
+ * One editor's Tiptap instance, independent of any component framework.
+ *
+ * @ownership The session owns the `Editor` from creation until `destroy()`. A host renders an
+ * element for the document and hands it to `attach()`; it never creates or destroys the editor.
+ * @lifecycle The editor, its document, and its undo history survive `attach()` to a new element,
+ * so a host can remount its view without losing state.
+ */
+export interface LoomaEditorSession<E extends Editor = Editor> {
+    readonly editor: E;
+    /** Moves the editor's view into `element` (idempotent). */
+    attach(element: HTMLElement): void;
+    /**
+     * Applies a controlled document.
+     *
+     * @contract Returns false, and leaves the editor untouched, when the document already matches.
+     * A focused editor keeps `selection` (or its current selection) in the same transaction.
+     * @failure A selection the new document cannot hold becomes the closest valid text range.
+     */
+    setContent(content: JSONContent, selection?: LoomaSelectionSnapshot | null): boolean;
+    /** Calls `listener` after every transaction; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    destroy(): void;
+}
+/**
+ * Creates the session's editor from `options`. A framework layer may pass its own `Editor`
+ * subclass, such as `@tiptap/vue-3`'s reactive one, so the editor it exposes keeps that behavior.
+ */
+export declare function createEditorSession<E extends Editor = Editor>(options: Partial<EditorOptions>, EditorClass?: new (options: Partial<EditorOptions>) => E): LoomaEditorSession<E>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.28.1",
+  "version": "0.28.3",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",

package/vue/editor/compact/index.js

@@ -1,6 +1,6 @@
 import { defineComponent, h, onBeforeUnmount, onMounted, shallowRef, watch } from "vue";
 import { Extension, Mark, Node, markInputRule, markPasteRule, mergeAttributes } from "@tiptap/core";
-import { Editor, EditorContent } from "@tiptap/vue-3";
+import { Editor as Editor$1, EditorContent } from "@tiptap/vue-3";
 import { closeHistory, history, redo, undo } from "@tiptap/pm/history";
 import { Plugin } from "@tiptap/pm/state";
 //#region ../../node_modules/.pnpm/@tiptap+extension-document@2.27.2_@tiptap+core@2.27.2_@tiptap+pm@2.27.2_/node_modules/@tiptap/extension-document/dist/index.js
@@ -498,7 +498,7 @@ var LoomaCompactEditor = defineComponent({
 	setup(props, { attrs, emit, expose }) {
 		const editor = shallowRef();
 		onMounted(() => {
-			editor.value = new Editor({
+			editor.value = new Editor$1({
 				extensions: [...getCompactEditorExtensions(), ...props.extensions],
 				content: props.modelValue,
 				editable: props.editable,