@jini-ai/ui 0.4.6 → 0.4.8

package/dist/features/html-editor/protected-elements.js

@@ -0,0 +1,189 @@
+import { findEditorBlockOpening } from './editor-blocks.js';
+export const PROTECTED_ELEMENT_TYPE = 'protected-element';
+/** Distinguishable from an ordinary best-effort RTE timeout: never persist a damaged raw shell. */
+export class EditorSourceError extends Error {
+    code = 'EDITOR_SOURCE_INTEGRITY';
+    constructor({ message = "Can't edit this source visually. Use HTML." } = {}, _options = {}) { super(message); this.name = 'EditorSourceError'; }
+}
+export function isEditorSourceError({ error }, _options = {}) {
+    return !!error && typeof error === 'object' && 'code' in error && error.code === 'EDITOR_SOURCE_INTEGRITY';
+}
+/** Source lives only on the component model, so clone and undo carry it with ordinary model state. */
+export function protectedElementHtml({ component }, _options = {}) {
+    const original = component.get('originalHtml');
+    if (typeof original !== 'string' || original.length === 0)
+        throw new EditorSourceError();
+    return original;
+}
+function visit(component, callback) {
+    callback(component);
+    component.components().models.forEach(child => visit(child, callback));
+}
+/** Check surviving instances before any export or no-op flush; deletion itself is allowed. */
+export function assertProtectedSourceMetadata({ editor }, _options = {}) {
+    const wrapper = editor.getWrapper();
+    if (wrapper)
+        visit(wrapper, component => {
+            if (component.is(PROTECTED_ELEMENT_TYPE))
+                protectedElementHtml({ component }, {});
+        });
+}
+/** Verify initial parser ownership before the first visual edit; recovered/lost shells fail closed. */
+export function assertPreparedSourceModel({ editor, sourcePlan }, _options = {}) {
+    const actual = [];
+    const wrapper = editor.getWrapper();
+    if (!wrapper)
+        throw new EditorSourceError();
+    visit(wrapper, component => {
+        if (component.is(PROTECTED_ELEMENT_TYPE))
+            actual.push(protectedElementHtml({ component }, {}));
+    });
+    if (actual.length !== sourcePlan.instances.length || actual.some((html, i) => html !== sourcePlan.instances[i].originalHtml)) {
+        throw new EditorSourceError();
+    }
+}
+/** Text ancestors must not sync canvas-only card chrome back into a model during RTE close. */
+export function protectTextAncestors({ editor }, _options = {}) {
+    const wrapper = editor.getWrapper();
+    if (!wrapper)
+        return;
+    visit(wrapper, component => {
+        if (!component.is(PROTECTED_ELEMENT_TYPE))
+            return;
+        for (let parent = component.parent(); parent; parent = parent.parent()) {
+            if (parent.is('text'))
+                parent.set('editable', false, { silent: true });
+        }
+    });
+}
+/** Same canvas card path, addressed through model metadata rather than authored/public selectors. */
+export function protectedCanvasDescriber({ editor }, _options = {}) {
+    const descriptors = new Map();
+    const wrapper = editor.getWrapper();
+    if (wrapper)
+        visit(wrapper, component => {
+            if (!component.is(PROTECTED_ELEMENT_TYPE) || component.get('sourceNonvisual'))
+                return;
+            const el = component.getEl();
+            const descriptor = component.get('placeholderDescriptor');
+            if (el && descriptor)
+                descriptors.set(el, descriptor);
+        });
+    return el => descriptors.get(el);
+}
+/**
+ * Registers the `protected-element` component type so any parsed element `isProtectedElement`
+ * recognizes becomes one atomic block: its content can never be edited (excluded from RTE
+ * content-editing, including as a nested island inside a `text` component), dropped into, or styled,
+ * but the element itself is selectable and can be deliberately moved, copied or deleted like any other
+ * block. Selectable matters for safety: a non-selectable element hands a click to its nearest
+ * selectable ancestor, so clicking an embed selected the block around it and Delete then removed that
+ * block together with the embed. Pair it with `applyCanvasEmbedPlaceholders`, which makes the marker
+ * the clickable surface of its card. Passed as a `plugins` entry so it registers before
+ * `editor.setComponents` parses the initial `html` (see `initInteractiveHtmlEditor` below).
+ *
+ * @complexity O(1) — one type registration; the per-element check GrapesJS then runs during parsing
+ * is O(1) per element (whatever `isProtectedElement` costs), not owned by this function.
+ * @overallScore 100
+ */
+/**
+ * One protected type for runtime roots, host embeds and nonvisual atoms. Registration precedes
+ * parsing; isComponent resolves mount-private tokens to metadata and supplies empty children.
+ */
+export function registerProtectedElementType({ editor, sourcePlan }, options = {}) {
+    const command = 'jini:protected-edit-html';
+    const requestEditHtml = options.onRequestEditHtml;
+    if (requestEditHtml)
+        editor.Commands.add(command, {
+            async run() {
+                try {
+                    await options.beforeRequestEditHtml?.();
+                    const selected = editor.getSelected();
+                    const wrapper = editor.getWrapper();
+                    if (!selected?.is(PROTECTED_ELEMENT_TYPE) || !wrapper || selected.get('sourceNonvisual'))
+                        return;
+                    const original = protectedElementHtml({ component: selected }, {});
+                    const html = wrapper.getInnerHTML();
+                    // Search only exact authored slices. Copies share bytes, so count preceding equal instances
+                    // in model order; no mapping export mode or persistent source tokens are needed.
+                    let copiesBefore = 0;
+                    let reached = false;
+                    visit(wrapper, component => {
+                        if (component === selected)
+                            reached = true;
+                        else if (!reached && component.is(PROTECTED_ELEMENT_TYPE) && protectedElementHtml({ component }, {}) === original)
+                            copiesBefore++;
+                    });
+                    let start = -1;
+                    for (let i = 0; i <= copiesBefore; i++)
+                        start = html.indexOf(original, start + 1);
+                    if (start < 0)
+                        throw new EditorSourceError();
+                    const tagName = selected.get('sourceTagName');
+                    const id = selected.get('sourceId');
+                    let occurrenceIndex = 0;
+                    for (;;) {
+                        const range = findEditorBlockOpening({ html, target: { occurrenceIndex, tagName, ...(id ? { id } : {}) } }, {});
+                        if (!range || range.start > start)
+                            throw new EditorSourceError();
+                        if (range.start === start)
+                            break;
+                        occurrenceIndex++;
+                    }
+                    await requestEditHtml({ occurrenceIndex, tagName, ...(id ? { id } : {}) }, {});
+                }
+                catch (error) {
+                    options.onSerializationError?.(error instanceof EditorSourceError ? error : new EditorSourceError());
+                }
+            },
+        });
+    editor.Components.addType(PROTECTED_ELEMENT_TYPE, {
+        isComponent(el) {
+            const token = typeof el.getAttribute === 'function' ? el.getAttribute(sourcePlan.markerAttribute)
+                : el.attributes?.[sourcePlan.markerAttribute];
+            if (token === null || token === undefined)
+                return undefined;
+            const instance = sourcePlan.instances[Number(token)];
+            if (!instance || String(Number(token)) !== token)
+                throw new EditorSourceError();
+            return {
+                type: PROTECTED_ELEMENT_TYPE, originalHtml: instance.originalHtml, sourceTagName: instance.tagName,
+                sourceId: instance.id, sourceNonvisual: instance.nonvisual, placeholderDescriptor: instance.descriptor,
+                components: [], content: '',
+            };
+        },
+        model: {
+            defaults: {
+                editable: false, droppable: false, stylable: false, resizable: false, traits: [],
+                layerable: false, badgable: false, selectable: true, hoverable: true, highlightable: true,
+                removable: true, draggable: true, copyable: true,
+            },
+            init() {
+                // Keep default move/copy/delete toolbar commands, then append the host navigation action.
+                if (!this.get('sourceNonvisual') && options.onRequestEditHtml) {
+                    const toolbar = (this.get('toolbar') ?? []);
+                    this.set('toolbar', [...toolbar.filter(item => item.command !== command), {
+                            label: options.editHtmlLabel ?? 'Edit HTML', command,
+                            // GrapesJS sizes every toolbar item as a 26px icon square; a text label overflowed past the
+                            // toolbar (and the canvas edge on full-width blocks), so this item sizes to its label.
+                            attributes: {
+                                title: options.editHtmlLabel ?? 'Edit HTML', 'aria-label': options.editHtmlLabel ?? 'Edit HTML',
+                                style: 'width:auto;white-space:nowrap;padding:5px 8px',
+                            },
+                        }], { silent: true });
+                }
+                if (this.get('sourceNonvisual'))
+                    this.set({ selectable: false, draggable: false, hoverable: false, copyable: false }, { silent: true });
+            },
+            toHTML() { return protectedElementHtml({ component: this }, {}); },
+        },
+        view: {
+            onRender() {
+                this.el.setAttribute('contenteditable', 'false');
+                if (this.model.get('sourceNonvisual'))
+                    this.el.style.setProperty('display', 'none', 'important');
+            },
+        },
+    });
+}
+//# sourceMappingURL=protected-elements.js.map

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

@@ -1,6 +1,7 @@
 import 'grapesjs/dist/css/grapes.min.css';
 import type { CanvasEmbedPlaceholderDescriptor } from '../../canvas-embed-placeholders.js';
 import type { CanvasStyling } from '../../canvas-style.js';
+import { type InteractiveEditorOptions } from '../hooks/useInteractiveHtmlEditor.js';
 /**
  * @file A visual, click-into-text editing surface for a bespoke HTML document, built on GrapesJS
  * (MIT). Renders `html` like a live preview but lets the operator click into rendered text and edit
@@ -32,7 +33,8 @@ import type { CanvasStyling } from '../../canvas-style.js';
  * 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.
+ * copied or deleted. Runtime/native and author-opted blocks are always protected; the predicate
+ * adds host-owned embed recognition.
  * `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:
@@ -66,7 +68,7 @@ import type { CanvasStyling } from '../../canvas-style.js';
  * guaranteed by WHEN it is applied (against the live canvas, after GrapesJS has already parsed
  * `html`), not by a strip-on-export step.
  */
-export interface InteractiveHtmlEditorProps {
+export interface InteractiveHtmlEditorProps extends InteractiveEditorOptions {
     /** The document to load into the editor. Read once, at mount — see this file's header and
      *  `react/hooks/useInteractiveHtmlEditor.ts` for why. */
     html: string;
@@ -79,7 +81,7 @@ export interface InteractiveHtmlEditorProps {
     /** 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. */
+     *  directly — see that helper's own doc for why. Omit for runtime/native blocks only. */
     isProtectedElement?: (el: Element) => boolean;
     /** CSS to render the edited document against inside the editing canvas, so the operator sees
      *  roughly what the document publishes as rather than browser defaults. Read once, at mount, same
@@ -90,7 +92,7 @@ export interface InteractiveHtmlEditorProps {
      *  fallback content it authored) — see `../../canvas-embed-placeholders.ts`'s own file header for
      *  the export-safety argument. Read once, at mount, same as `isProtectedElement`. Returning
      *  `undefined` for an element means "not a marker this host owns" — left completely untouched.
-     *  Omit to decorate nothing, the pre-existing behavior. This component has the same zero knowledge
+     *  Omit for runtime/native cards only. This component has the same zero knowledge
      *  of any host's marker convention that `isProtectedElement` documents above. */
     describeEmbedPlaceholder?: (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined;
 }

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

@@ -8,10 +8,10 @@ const GJS_STYLE_VARS = {
     '--gjs-left-width': '0px',
     '--gjs-canvas-top': '0px',
 };
-export const InteractiveHtmlEditor = forwardRef(function InteractiveHtmlEditor({ html, onChange, className, isProtectedElement, canvasStyling, describeEmbedPlaceholder }, ref) {
-    const { containerRef, flush } = useInteractiveHtmlEditor(html, onChange, isProtectedElement, canvasStyling, describeEmbedPlaceholder);
+export const InteractiveHtmlEditor = forwardRef(function InteractiveHtmlEditor({ html, onChange, className, isProtectedElement, canvasStyling, describeEmbedPlaceholder, onRequestEditHtml, translate, onSerializationError }, ref) {
+    const { containerRef, flush, sourceError } = useInteractiveHtmlEditor(html, onChange, isProtectedElement, canvasStyling, describeEmbedPlaceholder, { onRequestEditHtml, translate, onSerializationError });
     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 });
+    return _jsx("div", { ref: containerRef, className: wrapperClassName, style: GJS_STYLE_VARS, children: sourceError && _jsx("p", { role: "alert", children: sourceError }) });
 });
 //# sourceMappingURL=InteractiveHtmlEditor.js.map

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

@@ -1,5 +1,7 @@
 import { type CanvasEmbedPlaceholderDescriptor } from '../../canvas-embed-placeholders.js';
 import { type CanvasStyling } from '../../canvas-style.js';
+import { type RequestEditHtml } from '../../editor-blocks.js';
+import { EditorSourceError } from '../../protected-elements.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 `serializeWithSplice`) on every content
@@ -36,8 +38,14 @@ import { type CanvasStyling } from '../../canvas-style.js';
  * beyond that.
  * @overallScore 100
  */
-export declare function useInteractiveHtmlEditor(html: string, onChange: (html: string) => void, isProtectedElement?: (el: Element) => boolean, canvasStyling?: CanvasStyling, describeEmbedPlaceholder?: (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined): {
+export interface InteractiveEditorOptions {
+    onRequestEditHtml?: RequestEditHtml | undefined;
+    translate?: ((key: string) => string) | undefined;
+    onSerializationError?: ((error: EditorSourceError) => void) | undefined;
+}
+export declare function useInteractiveHtmlEditor(html: string, onChange: (html: string) => void, isProtectedElement?: (el: Element) => boolean, canvasStyling?: CanvasStyling, describeEmbedPlaceholder?: (el: Element) => CanvasEmbedPlaceholderDescriptor | undefined, options?: InteractiveEditorOptions): {
     containerRef: import("react").RefObject<HTMLDivElement | null>;
     flush: () => Promise<string | undefined>;
+    sourceError: string | undefined;
 };
 //# sourceMappingURL=useInteractiveHtmlEditor.d.ts.map