@jini-ai/ui 0.3.8 → 0.3.10

package/dist/features/html-editor/canvas-embed-placeholders.js

@@ -29,6 +29,10 @@
  * (untouched, still literally empty) marker means there is nothing inside the marker for that re-parse
  * to ever pick up, regardless of whether that `isProtectedElement` gap is ever closed.
  *
+ * **Safe to call again after every structural edit** (the hook does, on the tick after any component
+ * add or remove): each pass first drops cards whose marker has gone (see `removeStaleCards`), then
+ * wraps any marker not already inside a card.
+ *
  * Re-entrancy (defensive, mirroring `canvas-content-wrapper.ts`'s own `WRAPPER_ROOT_MARKER` guard): a
  * marker already sitting inside a placeholder card (`el.closest('[' + CARD_ROOT_MARKER + ']')`) is
  * skipped, so a second call — or a caller's own `load` handler firing twice — cannot nest a second card
@@ -38,12 +42,31 @@
  *  `load`) can recognize an already-decorated marker via `el.closest` and skip it — see this file's
  *  header. */
 const CARD_ROOT_MARKER = 'data-tovu-embed-placeholder-root';
+/** Flags every child the card itself builds (icon, text), so the one unflagged child is always the
+ *  marker. {@link OVERLAY_RULE} and the stale-card check in `removeStaleCards` both rely on it. */
+const CARD_CHROME_MARKER = 'data-tovu-embed-placeholder-chrome';
+/** Identifies the one `<style>` this module adds to the canvas document's `<head>`. */
+const OVERLAY_STYLE_MARKER = 'data-tovu-embed-placeholder-style';
+/**
+ * Stretches the (empty) marker over its card as a transparent overlay, so a click anywhere on the card
+ * lands on the marker element itself. GrapesJS resolves a click by walking up from the event target to
+ * the nearest element it rendered; the card is not one of those, so without this a click on the card
+ * selected whatever block wraps the embed, and Delete then removed that block together with the embed.
+ * With it, the editor selects (and outlines) the embed. A stylesheet rule rather than an inline style,
+ * so the marker's own attributes stay untouched. `!important` because the host's theme may style the
+ * marker element.
+ */
+const OVERLAY_RULE = `[${CARD_ROOT_MARKER}] > :not([${CARD_CHROME_MARKER}])` +
+    ' { position: absolute !important; inset: 0 !important; margin: 0 !important; width: auto !important;' +
+    ' height: auto !important; min-width: 0 !important; max-width: none !important; min-height: 0 !important;' +
+    ' display: block !important; background: transparent !important; }';
 /** One CSS declaration list, as `property:value` pairs, for the card's own opaque chrome. Deliberately
  *  NOT derived from the host's theme in any way — themes are arbitrary and downloadable, and this card
  *  must stay legible whether the canvas underneath is a light theme, a dark theme, or (mid-edit) no
  *  theme at all. An opaque background plus a fixed, high-contrast foreground guarantees that
  *  regardless of what renders behind it, unlike a translucent or theme-token-based treatment would. */
 const CARD_STYLE = [
+    'position:relative',
     'display:flex',
     'align-items:flex-start',
     'gap:8px',
@@ -91,6 +114,7 @@ function buildPlaceholderCard(doc, descriptor) {
     card.setAttribute(CARD_ROOT_MARKER, '');
     card.setAttribute('style', CARD_STYLE);
     const text = doc.createElement('div');
+    text.setAttribute(CARD_CHROME_MARKER, '');
     const heading = doc.createElement('div');
     heading.setAttribute('style', 'font-weight:600;');
     heading.textContent = `Placeholder — ${descriptor.kindLabel}`;
@@ -101,7 +125,9 @@ function buildPlaceholderCard(doc, descriptor) {
     note.setAttribute('style', 'opacity:.6;margin-top:4px;font-size:11px;');
     note.textContent = 'Shown here for editing only — the real content renders on the published page.';
     text.append(heading, identity, note);
-    card.append(buildPlaceholderIcon(doc), text);
+    const icon = buildPlaceholderIcon(doc);
+    icon.setAttribute(CARD_CHROME_MARKER, '');
+    card.append(icon, text);
     return card;
 }
 /**
@@ -136,6 +162,28 @@ function applyResolvedMaxWidth(marker, card) {
     if (maxWidth && maxWidth !== 'none')
         card.style.setProperty('max-width', maxWidth);
 }
+/** Adds {@link OVERLAY_RULE} to `doc`'s `<head>` once. Idempotent. */
+function ensureOverlayRule(doc) {
+    if (doc.head.querySelector(`style[${OVERLAY_STYLE_MARKER}]`))
+        return;
+    const style = doc.createElement('style');
+    style.setAttribute(OVERLAY_STYLE_MARKER, '');
+    style.textContent = OVERLAY_RULE;
+    doc.head.appendChild(style);
+}
+/**
+ * Removes every card whose marker is no longer inside it. The card lives only in the canvas DOM, so the
+ * editor knows nothing about it: deleting the embed removes just the marker element (leaving a ghost
+ * card that still reads "Placeholder"), and moving it takes the marker out (leaving an empty card
+ * behind). The next pass of `applyCanvasEmbedPlaceholders` then wraps the moved marker again.
+ */
+function removeStaleCards(body) {
+    for (const card of Array.from(body.querySelectorAll(`[${CARD_ROOT_MARKER}]`))) {
+        const hasMarker = Array.from(card.children).some((child) => !child.hasAttribute(CARD_CHROME_MARKER));
+        if (!hasMarker)
+            card.remove();
+    }
+}
 /**
  * Scans every element under `body` once and, for each one `describe` recognizes (returns a descriptor
  * for), replaces its visible slot with an explicit placeholder card — see this file's header for the
@@ -155,6 +203,7 @@ function applyResolvedMaxWidth(marker, card) {
  */
 export function applyCanvasEmbedPlaceholders(body, describe) {
     const doc = body.ownerDocument;
+    removeStaleCards(body);
     // Snapshotted into an array before any mutation starts: this function inserts new ancestors as it
     // goes, and a live `querySelectorAll` result must never be iterated while the tree it was taken over
     // is being restructured underneath it — same discipline `applyCanvasContentWrapper` applies to
@@ -185,6 +234,7 @@ export function applyCanvasEmbedPlaceholders(body, describe) {
         applyResolvedMaxWidth(el, card);
         parent.insertBefore(card, el);
         card.appendChild(el); // Moves the SAME node (auto-detaches from `parent`) — never cloned.
+        ensureOverlayRule(doc);
     }
 }
 //# sourceMappingURL=canvas-embed-placeholders.js.map

package/dist/features/html-editor/canvas-style.d.ts

@@ -51,6 +51,17 @@ export interface CanvasStyling {
      */
     contentWrapper?: readonly CanvasContentWrapperNode[];
 }
+/**
+ * CSS class the canvas body carries while `react/hooks/useInteractiveHtmlEditor.ts`'s
+ * `revealCanvasWhenStylesheetsSettle` is still waiting on `canvas.styles`' `<link>` elements to settle
+ * (Bug B, Slice B1, this repo's `pages-redo` plan): every Interactive mount re-fetches the theme
+ * stylesheet (no browser cache short-circuit is guaranteed), and GrapesJS renders the canvas body
+ * without waiting for it, so a slow or restarting API left the canvas showing raw browser-default
+ * styling (Times New Roman, blue links) until the stylesheet arrived. Exported so the hook that
+ * toggles this class on/off and this module's CSS rule for it never drift onto two different literal
+ * strings.
+ */
+export declare const CANVAS_STYLES_PENDING_CLASS = "gjs-canvas-styles-pending";
 /** The `canvas` slice of a GrapesJS editor config — structurally the subset of its `CanvasConfig`
  *  this module decides, kept as its own type so the builder is assertable without a live editor. */
 export interface CanvasStyleConfig {

package/dist/features/html-editor/canvas-style.js

@@ -25,6 +25,21 @@ const CANVAS_SCROLLBAR_STYLE = [
 /** The half of GrapesJS's default `canvas.frameStyle` this module conditionally drops — see the file
  *  header for why it cannot simply be left in place. */
 const CANVAS_DEFAULT_BODY_BACKGROUND = "body { background-color: #fff }";
+/**
+ * CSS class the canvas body carries while `react/hooks/useInteractiveHtmlEditor.ts`'s
+ * `revealCanvasWhenStylesheetsSettle` is still waiting on `canvas.styles`' `<link>` elements to settle
+ * (Bug B, Slice B1, this repo's `pages-redo` plan): every Interactive mount re-fetches the theme
+ * stylesheet (no browser cache short-circuit is guaranteed), and GrapesJS renders the canvas body
+ * without waiting for it, so a slow or restarting API left the canvas showing raw browser-default
+ * styling (Times New Roman, blue links) until the stylesheet arrived. Exported so the hook that
+ * toggles this class on/off and this module's CSS rule for it never drift onto two different literal
+ * strings.
+ */
+export const CANVAS_STYLES_PENDING_CLASS = "gjs-canvas-styles-pending";
+/** The rule that makes {@link CANVAS_STYLES_PENDING_CLASS} actually hide the canvas. Unconditional —
+ *  unlike {@link CANVAS_DEFAULT_BODY_BACKGROUND}, it doesn't depend on whether the host supplies its
+ *  own styling, since the class is only ever present while a fetch is genuinely in flight. */
+const CANVAS_STYLES_PENDING_RULE = `.${CANVAS_STYLES_PENDING_CLASS} { visibility: hidden }`;
 /**
  * Whether the host has taken over the canvas document's appearance. Either input is enough: a
  * stylesheet alone is the common case (a real theme's CSS), and raw `css` alone is enough for a host
@@ -39,7 +54,7 @@ function hostStylesTheCanvas(styling) {
  * and followed by the host's raw `css` when supplied.
  */
 function buildCanvasFrameStyle(styling) {
-    const rules = [CANVAS_SCROLLBAR_STYLE];
+    const rules = [CANVAS_SCROLLBAR_STYLE, CANVAS_STYLES_PENDING_RULE];
     if (!hostStylesTheCanvas(styling))
         rules.unshift(CANVAS_DEFAULT_BODY_BACKGROUND);
     if (styling.css)

package/dist/features/html-editor/index.d.ts

@@ -1,5 +1,5 @@
 export { InteractiveHtmlEditor } from './react/components/InteractiveHtmlEditor.js';
-export type { InteractiveHtmlEditorProps } from './react/components/InteractiveHtmlEditor.js';
+export type { InteractiveHtmlEditorHandle, InteractiveHtmlEditorProps } from './react/components/InteractiveHtmlEditor.js';
 export { useInteractiveHtmlEditor } from './react/hooks/useInteractiveHtmlEditor.js';
 export type { CanvasContentWrapperNode, CanvasStyling } from './canvas-style.js';
 export type { CanvasEmbedPlaceholderDescriptor } from './canvas-embed-placeholders.js';

package/dist/features/html-editor/react/components/InteractiveHtmlEditor.d.ts

@@ -9,10 +9,12 @@ import type { CanvasStyling } from '../../canvas-style.js';
  * `<textarea>`. See `react/hooks/useInteractiveHtmlEditor.ts` for why this is uncontrolled
  * (mount-once) rather than reacting to `html`/`isProtectedElement` prop changes after construction.
  *
- * **Scope, this pass: text editing + basic formatting only.** GrapesJS also does drag/drop block
- * manipulation, a Style Manager, and a Layers panel; none of that chrome is enabled here (`panels:
- * { defaults: [] }`, `blockManager: { blocks: [] }` in the hook) — Gutenberg-style block
- * move/duplicate/lock/group is explicitly deferred, not merely unbuilt.
+ * **Scope: text editing, basic formatting, and GrapesJS's own block move/copy/delete.** Selecting a
+ * block shows GrapesJS's selection toolbar (move, copy, delete) and Delete removes it; the owner kept
+ * these on purpose (2026-09-23). A text edit is saved as a byte-minimal splice of the original
+ * `html`; a block move/copy/delete falls back to a cleaned full re-serialization, with a dev warning
+ * naming the cause (see the hook's `serializeWithSplice`). No Style Manager, Layers panel or block
+ * library is enabled (`panels: { defaults: [] }`, `blockManager: { blocks: [] }` in the hook).
  *
  * **`GJS_STYLE_VARS` below is a consequence of that same choice, not a separate styling decision.**
  * GrapesJS's own vendor CSS unconditionally reserves layout space for the default chrome this
@@ -27,9 +29,10 @@ import type { CanvasStyling } from '../../canvas-style.js';
  * its own stylesheet.
  *
  * **This component has zero knowledge of any host's embed/placeholder conventions.** `isProtectedElement`
- * is an optional predicate the caller supplies to lock specific elements (identified however the
- * caller likes) out of every GrapesJS interaction that could edit, move, or remove them — not
- * editable, draggable, droppable, removable, or selectable. When omitted, no elements are protected.
+ * is an optional predicate the caller supplies to turn specific elements (identified however the
+ * caller likes) into atomic blocks: their content can never be edited, dropped into or styled, but a
+ * click selects the element itself (never the block around it), and it can be deliberately moved,
+ * copied or deleted. When omitted, no elements are protected.
  * `describeEmbedPlaceholder` is the same idea for a second, independent concern: recognizing an
  * unresolved embed marker and labeling it for `../../canvas-embed-placeholders.ts`'s explicit
  * placeholder card. See `@jini-ai/admin/react`'s `InteractiveHtmlEditor` for a worked example of both:
@@ -69,11 +72,12 @@ export interface InteractiveHtmlEditorProps {
     html: string;
     /** Fires with the editor's current serialized HTML on every content edit. Does not persist
      *  anything itself — the caller decides when/whether to save, same as an HTML source textarea's
-     *  `onChange`. */
+     *  `onChange`. A host that saves or unmounts should `await ref.flush()` first, to sync an RTE
+     *  session that is still open — see `InteractiveHtmlEditorHandle`. */
     onChange: (html: string) => void;
     className?: string;
-    /** Identifies elements that must never become editable, draggable, removable, or droppable inside
-     *  the editor. Read once, at mount, same as `html`. Predicates that check attributes should use
+    /** Identifies elements whose content must never be edited or dropped into inside the editor. Each
+     *  one is selectable as a single block that can be deliberately moved, copied or deleted. Read once, at mount, same as `html`. Predicates that check attributes should use
      *  `hasAttributeOnAnyNodeShape` (exported alongside this component) rather than `el.hasAttribute`
      *  directly — see that helper's own doc for why. Omit to protect nothing. */
     isProtectedElement?: (el: Element) => boolean;
@@ -90,5 +94,13 @@ export interface InteractiveHtmlEditorProps {
      *  of any host's marker convention that `isProtectedElement` documents above. */
     describeEmbedPlaceholder?: (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined;
 }
-export declare function InteractiveHtmlEditor({ html, onChange, className, isProtectedElement, canvasStyling, describeEmbedPlaceholder, }: InteractiveHtmlEditorProps): import("react").JSX.Element;
+/** Imperative handle exposed via `ref`. A host calls `flush()` right before it saves or unmounts, to
+ *  sync an open RTE session's still-pending edit into `onChange` first — see `onChange`'s own doc and
+ *  `useInteractiveHtmlEditor`'s `flush` for the full rationale (GrapesJS only syncs an RTE session's
+ *  text on close, never on every keystroke). Resolves the flushed HTML, or `undefined` when nothing
+ *  had changed since mount. */
+export interface InteractiveHtmlEditorHandle {
+    flush(): Promise<string | undefined>;
+}
+export declare const InteractiveHtmlEditor: import("react").ForwardRefExoticComponent<InteractiveHtmlEditorProps & import("react").RefAttributes<InteractiveHtmlEditorHandle>>;
 //# sourceMappingURL=InteractiveHtmlEditor.d.ts.map

package/dist/features/html-editor/react/components/InteractiveHtmlEditor.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef, useImperativeHandle } from 'react';
 import 'grapesjs/dist/css/grapes.min.css';
 import { useInteractiveHtmlEditor } from '../hooks/useInteractiveHtmlEditor.js';
 /** See this file's header for why these exist: they zero out layout space GrapesJS's default CSS
@@ -7,9 +8,10 @@ const GJS_STYLE_VARS = {
     '--gjs-left-width': '0px',
     '--gjs-canvas-top': '0px',
 };
-export function InteractiveHtmlEditor({ html, onChange, className, isProtectedElement, canvasStyling, describeEmbedPlaceholder, }) {
-    const { containerRef } = useInteractiveHtmlEditor(html, onChange, isProtectedElement, canvasStyling, describeEmbedPlaceholder);
+export const InteractiveHtmlEditor = forwardRef(function InteractiveHtmlEditor({ html, onChange, className, isProtectedElement, canvasStyling, describeEmbedPlaceholder }, ref) {
+    const { containerRef, flush } = useInteractiveHtmlEditor(html, onChange, isProtectedElement, canvasStyling, describeEmbedPlaceholder);
+    useImperativeHandle(ref, () => ({ flush }), [flush]);
     const wrapperClassName = className ? `interactive-html-editor ${className}` : 'interactive-html-editor';
     return _jsx("div", { ref: containerRef, className: wrapperClassName, style: GJS_STYLE_VARS });
-}
+});
 //# sourceMappingURL=InteractiveHtmlEditor.js.map

package/dist/features/html-editor/react/hooks/useInteractiveHtmlEditor.d.ts

@@ -2,7 +2,7 @@ import { type CanvasEmbedPlaceholderDescriptor } from '../../canvas-embed-placeh
 import { type CanvasStyling } from '../../canvas-style.js';
 /**
  * Owns one GrapesJS `Editor` instance for the lifetime of the calling component's mount. `onChange`
- * fires with the editor's current serialized content (see `serializeEditorContent`) on every content
+ * fires with the editor's current serialized content (see `serializeWithSplice`) on every content
  * mutation (GrapesJS's `update` event — components, styles, or attributes changing); it is not
  * debounced, so a caller replacing an existing uncontrolled `<textarea>` (which already pushes a full
  * value on every keystroke) sees matching behavior.
@@ -22,6 +22,15 @@ import { type CanvasStyling } from '../../canvas-style.js';
  * `class="frame"` forever, inert and unrendered. `.gjs-frame` — the class `FrameView.render()`
  * assigns — is what callers should select on, never a bare `iframe` under the wrapper.)
  *
+ * **`flush()` exists because GrapesJS's RTE only syncs on `disableEditing`, and `update` is
+ * double-debounced and never fires after `off()`.** A host that calls `onChange` on every keystroke
+ * (like an uncontrolled `<textarea>`) still misses the operator's last edit if they click Save or
+ * navigate away while an RTE session is still open: GrapesJS writes that session's text into the
+ * component model only when it closes, and by the time a host's save handler runs, this hook has
+ * already stopped listening (or the debounce hasn't fired yet). `flush` closes any open RTE session,
+ * computes and emits the current content the same way `handleUpdate` does, and hands the result back
+ * directly — see its own doc below for exactly what it returns and when.
+ *
  * @complexity O(1) setup/teardown. Steady-state cost is GrapesJS's own serialization per edit,
  * proportional to document size — not something this hook controls or should hide a note about
  * beyond that.
@@ -29,5 +38,6 @@ import { type CanvasStyling } from '../../canvas-style.js';
  */
 export declare function useInteractiveHtmlEditor(html: string, onChange: (html: string) => void, isProtectedElement?: (el: Element) => boolean, canvasStyling?: CanvasStyling, describeEmbedPlaceholder?: (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined): {
     containerRef: import("react").RefObject<HTMLDivElement | null>;
+    flush: () => Promise<string | undefined>;
 };
 //# sourceMappingURL=useInteractiveHtmlEditor.d.ts.map