smartrte-core 1.0.0-beta.2 → 1.0.0-beta.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.0-beta.3
+
+- Add `href`/`target` (a clickable link), `borderRadius` (corner rounding), and license metadata fields (`licenseDescription`, `licenseSourceUrl`, `licenseType`, `licenseVersion`, `licenseAttribution`) to the image atom schema. `href` is validated the same way as the existing `link` mark; exported HTML wraps a linked image in a real `<a>` for portability outside the editor. Fix a pre-existing renderer gap where clearing an image's `align` back to unset never removed the CSS float/display/margin it had previously applied.
+
 ## 1.0.0-beta.2
 
 - Add an opt-in `renderFormulaHtml` option to `serializeCanonicalListHtml` that bakes real KaTeX-rendered HTML into exported formula elements, instead of leaving an empty placeholder — for consumers (e.g. a read-only preview) that display this HTML directly without also running KaTeX against it themselves. Off by default; no change for existing consumers.

package/dist/foundation/atom/formats.d.ts

@@ -3,7 +3,7 @@ import type { SmartElementNode } from "../types.js";
 export declare const atomToHtml: (node: SmartElementNode, options?: {
     renderFormulaHtml?: boolean;
 }) => string;
-export declare const atomFromHtmlElement: (element: Element) => SmartElementNode | null;
+export declare const atomFromHtmlElement: (rawElement: Element) => SmartElementNode | null;
 export declare const atomToMarkdown: (node: SmartElementNode) => string;
 export interface AtomDocxRun {
     readonly kind: "image" | "text";

package/dist/foundation/atom/formats.js

@@ -6,6 +6,7 @@ import katex from "katex";
 // fall back to plain text in the exported/baked HTML.
 import "katex/contrib/mhchem";
 import { createNodeId } from "../identity.js";
+import { sanitizeLinkHref, sanitizeLinkTarget } from "../security/urlPolicy.js";
 import { sanitizeAtomSource } from "./security.js";
 const escape = (value) => String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const attr = (name, value) => value === undefined ? "" : ` ${name}="${escape(value)}"`;
@@ -25,7 +26,23 @@ const renderFormulaToHtml = (source) => {
 export const atomToHtml = (node, options) => {
     if (node.type === "image" || node.type === "block_image") {
         const src = sanitizeAtomSource(String(node.attrs?.src || ""), { kind: "image", allowBlobPreview: node.attrs?.status === "pending" }) || "";
-        return `<img data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" src="${escape(src)}" alt="${escape(node.attrs?.alt)}"${dimensions(node)}${attr("data-smart-status", node.attrs?.status || "ready")}${node.attrs?.decorative === true ? ' data-smart-decorative="true"' : ""}${attr("data-smart-align", node.attrs?.align)}>`;
+        // Corner radius and license fields are data-attributes only (round-trip
+        // fidelity), matching this same function's existing data-smart-align -
+        // a raw HTML consumer displaying this string directly without also
+        // running the live surface renderer's own style logic against it
+        // wouldn't see visual rounding either way, same as align today; that's
+        // a deliberate, pre-existing scope boundary this doesn't change.
+        const img = `<img data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" src="${escape(src)}" alt="${escape(node.attrs?.alt)}"${dimensions(node)}${attr("data-smart-status", node.attrs?.status || "ready")}${node.attrs?.decorative === true ? ' data-smart-decorative="true"' : ""}${attr("data-smart-align", node.attrs?.align)}${attr("data-smart-radius", node.attrs?.borderRadius)}${attr("data-smart-license-description", node.attrs?.licenseDescription)}${attr("data-smart-license-source-url", node.attrs?.licenseSourceUrl)}${attr("data-smart-license-type", node.attrs?.licenseType)}${attr("data-smart-license-version", node.attrs?.licenseVersion)}${attr("data-smart-license-attribution", node.attrs?.licenseAttribution)}${attr("data-smart-href", node.attrs?.href)}${attr("data-smart-target", node.attrs?.target)}>`;
+        // A real <a> wrapper, unlike the live surface renderer's plain data
+        // attributes on the bare <img> - see surface/renderer.ts's own
+        // reasoning (stable-element-per-id constraint that doesn't apply to
+        // this string-based export) and modelDom.ts's identical choice for the
+        // one-shot clipboard/print DOM builder.
+        const linkHref = sanitizeLinkHref(typeof node.attrs?.href === "string" ? node.attrs.href : undefined);
+        if (!linkHref)
+            return img;
+        const target = sanitizeLinkTarget(typeof node.attrs?.target === "string" ? node.attrs.target : undefined);
+        return `<a href="${escape(linkHref)}"${target ? ` target="${escape(target)}"` : ""}>${img}</a>`;
     }
     if (node.type === "formula" || node.type === "block_formula") {
         const tag = node.type === "formula" ? "span" : "div";
@@ -48,7 +65,14 @@ export const atomToHtml = (node, options) => {
         return `<hr data-smart-id="${escape(node.id)}" data-smart-type="divider">`;
     throw new Error(`Unsupported atom type "${node.type}".`);
 };
-export const atomFromHtmlElement = (element) => {
+export const atomFromHtmlElement = (rawElement) => {
+    // atomToHtml's own inverse - a linked image now wraps in a real <a>
+    // (needed so the link survives outside a live editor at all, see
+    // atomToHtml's own doc comment); unwrap to the actual atom element
+    // (which still carries every attribute, including data-smart-href,
+    // directly) before parsing, matching what a single element's own
+    // attributes already fully describe.
+    const element = rawElement.tagName === "A" && rawElement.children.length === 1 ? rawElement.children[0] : rawElement;
     const declared = element.getAttribute("data-smart-type");
     const type = declared || (element.tagName === "IMG" ? "image" : element.tagName.toLowerCase());
     const id = element.getAttribute("data-smart-id") || createNodeId();
@@ -57,7 +81,21 @@ export const atomFromHtmlElement = (element) => {
         const src = sanitizeAtomSource(element.getAttribute("src"), { kind: "image" });
         if (!src)
             return null;
-        return { type, id, attrs: { src, alt: element.getAttribute("alt") || "", status: element.getAttribute("data-smart-status") || "ready", ...(element.getAttribute("data-smart-decorative") === "true" ? { decorative: true } : {}), ...(element.getAttribute("data-smart-align") ? { align: element.getAttribute("data-smart-align") } : {}), ...(number("width") ? { width: number("width") } : {}), ...(number("height") ? { height: number("height") } : {}) } };
+        const radius = Number(element.getAttribute("data-smart-radius"));
+        return { type, id, attrs: {
+                src, alt: element.getAttribute("alt") || "", status: element.getAttribute("data-smart-status") || "ready",
+                ...(element.getAttribute("data-smart-decorative") === "true" ? { decorative: true } : {}),
+                ...(element.getAttribute("data-smart-align") ? { align: element.getAttribute("data-smart-align") } : {}),
+                ...(number("width") ? { width: number("width") } : {}), ...(number("height") ? { height: number("height") } : {}),
+                ...(Number.isFinite(radius) && radius > 0 ? { borderRadius: radius } : {}),
+                ...(element.getAttribute("data-smart-href") ? { href: element.getAttribute("data-smart-href") } : {}),
+                ...(element.getAttribute("data-smart-target") ? { target: element.getAttribute("data-smart-target") } : {}),
+                ...(element.getAttribute("data-smart-license-description") ? { licenseDescription: element.getAttribute("data-smart-license-description") } : {}),
+                ...(element.getAttribute("data-smart-license-source-url") ? { licenseSourceUrl: element.getAttribute("data-smart-license-source-url") } : {}),
+                ...(element.getAttribute("data-smart-license-type") ? { licenseType: element.getAttribute("data-smart-license-type") } : {}),
+                ...(element.getAttribute("data-smart-license-version") ? { licenseVersion: element.getAttribute("data-smart-license-version") } : {}),
+                ...(element.getAttribute("data-smart-license-attribution") ? { licenseAttribution: element.getAttribute("data-smart-license-attribution") } : {}),
+            } };
     }
     if (type === "formula" || type === "block_formula") {
         return { type, id, attrs: { source: element.getAttribute("data-smart-formula") || "", notation: element.getAttribute("data-smart-notation") === "mathml" ? "mathml" : "latex" } };

package/dist/foundation/atom/schema.js

@@ -1,3 +1,4 @@
+import { normalizeLinkInput } from "../security/urlPolicy.js";
 const optionalString = { validate: (value) => typeof value === "string" };
 const requiredString = { required: true, validate: (value) => typeof value === "string" };
 const dimension = { validate: (value) => Number.isFinite(value) && Number(value) > 0 && Number(value) <= 100000 };
@@ -6,6 +7,34 @@ const imageAttrs = {
     src: requiredString, alt: requiredString, width: dimension, height: dimension,
     status, uploadId: optionalString, error: optionalString, decorative: { validate: (value) => typeof value === "boolean" },
     align: { validate: (value) => value === "center" || value === "left" || value === "right" },
+    /**
+     * docs/bugs/media-details-old-editor-field-parity.md: the old editor's
+     * "Link"/"Target" fields have no equivalent yet - the `link` mark already
+     * has this exact href/target shape (marks/commands.ts), but marks are
+     * explicitly disallowed on every atom node (`marks: ""` below), so this
+     * is a dedicated pair of atom-level attrs instead of reusing the mark.
+     */
+    /** Same normalizeLinkInput validation the "link" mark's own schema uses (marks/schema.ts) - rejects at the command layer, not just sanitizing later at render/export time. */
+    href: { validate: (value) => typeof value === "string" && normalizeLinkInput(value).href !== null },
+    target: optionalString,
+    /** Corner rounding (px) - confirmed absent anywhere in this schema before now, unlike align/alt/width which already existed with no UI. */
+    borderRadius: { validate: (value) => Number.isFinite(value) && Number(value) >= 0 && Number(value) <= 1000 },
+    /**
+     * Mirrors MediaItem.license's own shape (packages/react/src/mediaProvider.ts)
+     * field-for-field where a real equivalent exists, so a library-sourced
+     * image's already-fetched license metadata can be copied straight across
+     * at insert time (CanonicalAuthorityEditor.tsx's selectFromMediaManager)
+     * instead of being read, shown in the library browser, and then silently
+     * discarded the way it was before this - the atom schema had nowhere to
+     * persist it. Renamed to this project's own vocabulary (the old editor's
+     * "Attribution text" ~ MediaItem.license.author, "License description" ~
+     * workName/licenseText) and kept independently user-editable, since a
+     * freshly uploaded image has no provider-supplied license data at all.
+     * `licenseVersion` has no MediaItem.license equivalent (its shape has no
+     * separate version field) - always user-entered, never auto-populated.
+     */
+    licenseDescription: optionalString, licenseSourceUrl: optionalString,
+    licenseType: optionalString, licenseVersion: optionalString, licenseAttribution: optionalString,
 };
 const formulaAttrs = {
     source: requiredString,

package/dist/foundation/list/formats.js

@@ -20,6 +20,23 @@ const isEditorUiNode = (node) => attr(node, "data-smart-ui") !== undefined || at
  * parseBlockList below for how they're unwrapped instead of swallowed.
  */
 const TRANSPARENT_CONTAINER_TAGS = ["div", "section", "article", "figure"];
+/** Shared by both the inline `image` and block `block_image` parsing branches below - radius/license round-trip identically for both, only href/target's link-mark-fallback behavior deliberately differs between them (see each call site's own comment). */
+const imageStyleAndLicenseAttrs = (node) => {
+    const radius = Number(attr(node, "data-smart-radius"));
+    const licenseDescription = attr(node, "data-smart-license-description");
+    const licenseSourceUrl = attr(node, "data-smart-license-source-url");
+    const licenseType = attr(node, "data-smart-license-type");
+    const licenseVersion = attr(node, "data-smart-license-version");
+    const licenseAttribution = attr(node, "data-smart-license-attribution");
+    return {
+        ...(Number.isFinite(radius) && radius > 0 ? { borderRadius: radius } : {}),
+        ...(licenseDescription ? { licenseDescription } : {}),
+        ...(licenseSourceUrl ? { licenseSourceUrl } : {}),
+        ...(licenseType ? { licenseType } : {}),
+        ...(licenseVersion ? { licenseVersion } : {}),
+        ...(licenseAttribution ? { licenseAttribution } : {}),
+    };
+};
 /** See serializeCanonicalListHtml's own doc comment for why this is a module-scoped flag rather than a threaded parameter. */
 let renderFormulaHtmlMode = false;
 const serializeInline = (node) => {
@@ -227,12 +244,27 @@ const textWithMarks = (node, inherited = []) => {
             // synchronous and the image hasn't loaded yet at this point.
             const width = parsePixelWidth(styleValue(node, "width")) ?? parsePixelWidth(attr(node, "width"));
             const height = parsePixelWidth(styleValue(node, "height")) ?? parsePixelWidth(attr(node, "height"));
+            // <a><img></a> (this project's own export - list/formats.ts's own
+            // serializeBlock/atom/formats.ts's atomToHtml wrap a linked image in a
+            // real anchor - or any real-world source doing the same): the link
+            // mark from that ancestor <a> arrives here via `inherited`, but
+            // SmartElementNode has no `marks` field at all (only SmartTextNode
+            // does) - without this, the href would be silently discarded the
+            // moment it reached this atomic-image branch. The live editor's own
+            // DOM instead encodes this as plain data-smart-href/-target
+            // attributes directly on the <img> (surface/renderer.ts) with no
+            // wrapping <a> at all, so both encodings are checked.
+            const inheritedLink = inherited.find((mark) => mark.type === "link");
+            const href = attr(node, "data-smart-href") || inheritedLink?.attrs?.href;
+            const target = attr(node, "data-smart-target") || inheritedLink?.attrs?.target;
             return [{ type: "image", id: generatedId(node, "image"), attrs: {
                         src, alt: attr(node, "alt") || "", status: attr(node, "data-smart-status") || "ready",
                         ...(attr(node, "data-smart-decorative") === "true" ? { decorative: true } : {}),
                         ...(attr(node, "title") ? { title: attr(node, "title") } : {}),
                         ...(attr(node, "data-smart-align") ? { align: attr(node, "data-smart-align") } : {}),
                         ...(width !== null ? { width } : {}), ...(height !== null ? { height } : {}),
+                        ...(href ? { href } : {}), ...(target ? { target } : {}),
+                        ...imageStyleAndLicenseAttrs(node),
                     } }];
         }
     }
@@ -375,6 +407,19 @@ const parseBlock = (node) => {
                 src, alt: attr(node, "alt") || "", status: attr(node, "data-smart-status") || "ready",
                 ...(attr(node, "data-smart-decorative") === "true" ? { decorative: true } : {}),
                 ...(width !== null ? { width } : {}), ...(height !== null ? { height } : {}),
+                // Only from data-smart-href/-target directly on this element (our own
+                // round-tripped export, per this whole branch's own `declaredAtom`
+                // gate) - deliberately NOT also checking for a wrapping <a> the way
+                // the inline `image` atom's parsing does just above in textWithMarks.
+                // The bare-<img>-at-block-level fallback a few lines down has its own
+                // long-standing, evidence-based decision (a real Wikipedia "copy
+                // image" paste) to unwrap and drop an incidental <a> wrapper rather
+                // than treat it as a user-authored link - extending that to also
+                // read href here would silently reverse that decision for every
+                // third-party block-level image paste, not just this app's own.
+                ...(attr(node, "data-smart-href") ? { href: attr(node, "data-smart-href") } : {}),
+                ...(attr(node, "data-smart-target") ? { target: attr(node, "data-smart-target") } : {}),
+                ...imageStyleAndLicenseAttrs(node),
             } };
     }
     if (declaredAtom === "block_formula")

package/dist/foundation/modelDom.js

@@ -2,6 +2,7 @@ import { isTextNode } from "./identity.js";
 import { nodeAtPath } from "./positions.js";
 import { renderMarkedText } from "./marks/dom.js";
 import { sanitizeAtomSource } from "./atom/security.js";
+import { sanitizeLinkHref, sanitizeLinkTarget } from "./security/urlPolicy.js";
 const atomTypes = new Set(["image", "block_image", "formula", "block_formula", "video", "audio", "divider"]);
 export const SMART_UI_ATTRIBUTE = "data-smart-ui";
 export const SMART_PROJECTION_ATTRIBUTE = "data-smart-projection";
@@ -93,6 +94,23 @@ const renderNode = (node, ownerDocument) => {
         if (source)
             element.setAttribute("src", source);
         element.setAttribute("alt", typeof node.attrs?.alt === "string" ? node.attrs.alt : "");
+        if (node.attrs?.borderRadius)
+            element.style.borderRadius = `${Number(node.attrs.borderRadius)}px`;
+        const linkHref = sanitizeLinkHref(typeof node.attrs?.href === "string" ? node.attrs.href : undefined);
+        if (linkHref) {
+            // A real <a> wrapper, unlike the live surface renderer's plain data
+            // attributes - this is a one-shot tree builder (no per-node element
+            // identity to preserve across renders), and clipboard/print output
+            // needs a genuine anchor for the link to survive outside this editor
+            // at all.
+            const link = ownerDocument.createElement("a");
+            link.setAttribute("href", linkHref);
+            const linkTarget = sanitizeLinkTarget(typeof node.attrs?.target === "string" ? node.attrs.target : undefined);
+            if (linkTarget)
+                link.setAttribute("target", linkTarget);
+            link.appendChild(element);
+            return link;
+        }
     }
     if (node.type === "formula" || node.type === "block_formula") {
         const source = String(node.attrs?.source || "");

package/dist/foundation/surface/renderer.js

@@ -405,6 +405,62 @@ export class FoundationSubtreeRenderer {
                 element.style.float = imageAlign;
                 element.style.margin = imageAlign === "left" ? "0 8px 8px 0" : "0 0 8px 8px";
             }
+            else {
+                // No align set - reset every property the two branches above can
+                // set, not just skip setting new ones. A pre-existing gap (found
+                // while verifying docs/bugs/media-details-old-editor-field-parity.md's
+                // new "clear align back to None" UI path): this renderer's other
+                // conditional style branches (e.g. borderRadius just below) always
+                // pair their "set" case with an explicit "else remove" case for
+                // exactly this reason - align's own else branches never existed
+                // before this UI made "align was set, then explicitly cleared" a
+                // real, reachable transition for the first time.
+                element.style.removeProperty("display");
+                element.style.removeProperty("float");
+                element.style.removeProperty("margin");
+            }
+            if (node.attrs?.borderRadius)
+                element.style.borderRadius = `${Number(node.attrs.borderRadius)}px`;
+            else
+                element.style.removeProperty("border-radius");
+            // Plain data attributes, not a wrapping <a> - this element's identity
+            // is stable across renders (see this class's own diffing contract);
+            // introducing a conditional DOM-structure change here for something
+            // input.ts's click handling already reads directly is unnecessary
+            // risk. atomToHtml/modelDom.ts DO wrap in a real <a> for the
+            // string/one-shot export paths, which have no such stability
+            // constraint and need a real anchor for the link to work outside
+            // this live editor at all.
+            if (typeof node.attrs?.href === "string" && node.attrs.href)
+                this.setAttribute(element, "data-smart-href", node.attrs.href, node.id);
+            else
+                this.removeAttribute(element, "data-smart-href", node.id);
+            if (typeof node.attrs?.target === "string" && node.attrs.target)
+                this.setAttribute(element, "data-smart-target", node.attrs.target, node.id);
+            else
+                this.removeAttribute(element, "data-smart-target", node.id);
+            // Mirrored as data attributes too, matching href/target above - a
+            // host inspecting the live DOM (or this project's own e2e suite)
+            // should be able to see this data the same way it can see href, not
+            // just find it by reading the model directly. Purely descriptive
+            // metadata, so unlike align/borderRadius there's no matching CSS
+            // side effect to apply here.
+            if (node.attrs?.borderRadius)
+                this.setAttribute(element, "data-smart-radius", String(node.attrs.borderRadius), node.id);
+            else
+                this.removeAttribute(element, "data-smart-radius", node.id);
+            [
+                ["licenseDescription", "data-smart-license-description"],
+                ["licenseSourceUrl", "data-smart-license-source-url"],
+                ["licenseType", "data-smart-license-type"],
+                ["licenseVersion", "data-smart-license-version"],
+                ["licenseAttribution", "data-smart-license-attribution"],
+            ].forEach(([key, attrName]) => {
+                if (typeof node.attrs?.[key] === "string" && node.attrs[key])
+                    this.setAttribute(element, attrName, String(node.attrs[key]), node.id);
+                else
+                    this.removeAttribute(element, attrName, node.id);
+            });
         }
         else if (node.type === "formula" || node.type === "block_formula") {
             const source = String(node.attrs?.source || "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartrte-core",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.3",
   "description": "Framework-agnostic document model and editing primitives for Smart RTE",
   "repository": {
     "type": "git",