@eocrm/design-system 0.6.24 → 0.7.0

package/dist/components/RichText/RichText.d.ts

@@ -0,0 +1,48 @@
+import { type HTMLAttributes } from 'react';
+import type { RichDoc } from './engine/model.js';
+import type { RenderLink } from './engine/renderLink.js';
+import type { RenderMention } from './engine/renderMention.js';
+export interface RichTextProps extends HTMLAttributes<HTMLDivElement> {
+    /** The document to render. Build one with `emptyDoc()` / `createBlock()` or the transforms. */
+    value: RichDoc;
+    /**
+     * Substitute how a link renders. Called per link with `{ href, text }` and the
+     * default `<a>` node; return your own node (e.g. a task/member chip) or the
+     * `defaultNode` to keep the standard anchor. Render-time only — the document
+     * model is unchanged, so serialization still emits a plain link.
+     *
+     * Prose link styling (accent colour + underline) applies to BARE anchors
+     * only: an `<a>` you return with any `className` — including a DS `<Link>` —
+     * keeps its own decoration and colour entirely (#570).
+     *
+     * @remarks Keep it cheap — it runs on every render. Don't block on a network
+     * call inside `renderLink`; return a component that fetches/caches the lookup
+     * itself (or falls back to `defaultNode` while loading).
+     */
+    renderLink?: RenderLink;
+    /**
+     * Substitute how an `@`-mention renders. Called per mention with `{ id, label }`
+     * and the default mention span; return your own node (e.g. an interactive member
+     * chip / popover trigger) or the `defaultNode` to keep the standard
+     * non-interactive span. Render-time only — the document model is unchanged, so
+     * serialization still emits the mention mark. Composes with `renderLink`.
+     *
+     * @remarks Keep it cheap — it runs on every render. Don't block on a network
+     * call inside `renderMention`; return a component that fetches/caches the lookup
+     * itself (or falls back to `defaultNode` while loading).
+     */
+    renderMention?: RenderMention;
+    /**
+     * Maximum DISPLAYED height of image attachments, in px. Default: the
+     * `--size-rich-text-image-max-height` token (480px). A taller image shrinks
+     * (width follows, aspect preserved) — render-time only; stored `width`/`height`
+     * are unchanged, so existing documents need no migration. There is no "off":
+     * pass a large value to effectively remove the cap.
+     */
+    imageMaxHeight?: number;
+}
+/**
+ * Read-only renderer for a `RichDoc` (paragraphs, headings, lists, quotes, code blocks, inline marks) on the in-house engine.
+ * @see docs/components/RichText.md
+ */
+export declare const RichText: import("react").ForwardRefExoticComponent<RichTextProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/RichText/RichText.js

@@ -0,0 +1,25 @@
+'use client';
+import { renderDoc } from "./engine/renderDoc.js";
+import { imageMaxHeightStyle } from "./imageMaxHeightStyle.js";
+import RichText_module_default from "./RichText.module.js";
+import { forwardRef } from "react";
+import clsx from "clsx";
+import { jsx } from "react/jsx-runtime";
+// src/components/RichText/RichText.tsx
+/**
+* Read-only renderer for a `RichDoc` (paragraphs, headings, lists, quotes, code blocks, inline marks) on the in-house engine.
+* @see docs/components/RichText.md
+*/
+var RichText = forwardRef(function RichText({ value, renderLink, renderMention, imageMaxHeight, className, style, ...props }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		className: clsx(RichText_module_default.root, className),
+		style: imageMaxHeightStyle(imageMaxHeight, style),
+		...props,
+		children: renderDoc(value, {
+			renderLink,
+			renderMention
+		})
+	});
+});
+export { RichText };

package/dist/components/RichText/RichText.module.js

@@ -0,0 +1,5 @@
+import "./RichText.css";
+// src/components/RichText/RichText.module.scss
+var root = "RichText__root__tJYHR";
+var RichText_module_default = { root };
+export { RichText_module_default as default, root };

package/dist/components/RichText/RichTextAttachment.css

@@ -0,0 +1,51 @@
+.RichTextAttachment__attachmentImg__yrXdm {
+  --rich-text-image-cap: var(--rich-text-image-max-height, var(--size-rich-text-image-max-height));
+  display: inline-block;
+  max-width: min(100%, var(--rich-text-image-cap) * var(--rich-text-image-aspect, 1000));
+  max-height: var(--rich-text-image-cap);
+  height: auto;
+}
+
+.RichTextAttachment__attachmentLoading__nwKWM,
+.RichTextAttachment__attachmentError__Ct_gI {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width) solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-muted);
+  color: var(--color-fg-muted);
+}
+
+.RichTextAttachment__attachmentChip__pQhOg {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-1);
+  padding: var(--space-1) var(--space-2);
+  border: var(--border-width) solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg);
+  color: var(--color-fg);
+  text-decoration: none;
+}
+
+.RichTextAttachment__attachmentName__qEYIR {
+  font-weight: var(--font-weight-medium);
+}
+
+.RichTextAttachment__attachmentLabel__RBGKX {
+  color: var(--color-danger);
+}
+
+.RichTextAttachment__attachmentReason__6Es5S {
+  color: var(--color-fg);
+}
+
+figure[data-attachment][data-align=center] {
+  text-align: center;
+}
+
+figure[data-attachment][data-align=right] {
+  text-align: right;
+}

package/dist/components/RichText/RichTextAttachment.d.ts

@@ -0,0 +1,5 @@
+import type { Block } from './engine/model.js';
+export declare function RichTextAttachment({ block, editable }: {
+    block: Block;
+    editable?: boolean;
+}): import("react").JSX.Element;

package/dist/components/RichText/RichTextAttachment.js

@@ -0,0 +1,104 @@
+'use client';
+import { Button } from "../Button/Button.js";
+import { CircularProgress } from "../CircularProgress/CircularProgress.js";
+import { Tooltip } from "../Tooltip/Tooltip.js";
+import { useTranslation } from "../../i18n/useTranslation.js";
+import { safeHref } from "./engine/safeHref.js";
+import { attachmentIsImage } from "./engine/attachment.js";
+import { AttachFileIcon } from "./attachmentIcon.js";
+import RichTextAttachment_module_default from "./RichTextAttachment.module.js";
+import { useId } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { RotateCw, X } from "lucide-react";
+// src/components/RichText/RichTextAttachment.tsx
+function RichTextAttachment({ block, editable }) {
+	const t = useTranslation();
+	const name = block.name ?? "";
+	const errorId = useId();
+	if (block.status === "uploading") return /* @__PURE__ */ jsxs("span", {
+		className: RichTextAttachment_module_default.attachmentLoading,
+		children: [/* @__PURE__ */ jsx(CircularProgress, {
+			size: "sm",
+			"aria-label": t("richTextEditor.uploadingFile")
+		}), /* @__PURE__ */ jsx("span", {
+			className: RichTextAttachment_module_default.attachmentName,
+			children: name
+		})]
+	});
+	if (block.status === "error") {
+		const retry = t("richTextEditor.uploadRetry");
+		const remove = t("richTextEditor.uploadRemove");
+		return /* @__PURE__ */ jsxs("span", {
+			className: RichTextAttachment_module_default.attachmentError,
+			children: [
+				/* @__PURE__ */ jsx("span", {
+					className: RichTextAttachment_module_default.attachmentName,
+					children: name
+				}),
+				/* @__PURE__ */ jsxs("span", {
+					id: errorId,
+					children: [/* @__PURE__ */ jsx("span", {
+						className: RichTextAttachment_module_default.attachmentLabel,
+						children: t("richTextEditor.uploadFailed")
+					}), block.uploadError && /* @__PURE__ */ jsxs(Fragment$1, { children: [" ", /* @__PURE__ */ jsx("span", {
+						className: RichTextAttachment_module_default.attachmentReason,
+						children: block.uploadError
+					})] })]
+				}),
+				editable && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Tooltip, {
+					content: retry,
+					children: /* @__PURE__ */ jsx(Button, {
+						size: "xs",
+						iconOnly: true,
+						"data-attachment-action": "retry",
+						"data-block-id": block.id,
+						"aria-label": name ? `${retry} ${name}` : retry,
+						"aria-describedby": errorId,
+						children: /* @__PURE__ */ jsx(RotateCw, {
+							size: 14,
+							"aria-hidden": "true"
+						})
+					})
+				}), /* @__PURE__ */ jsx(Tooltip, {
+					content: remove,
+					children: /* @__PURE__ */ jsx(Button, {
+						size: "xs",
+						iconOnly: true,
+						variant: "danger-outline",
+						"data-attachment-action": "remove",
+						"data-block-id": block.id,
+						"aria-label": name ? `${remove} ${name}` : remove,
+						"aria-describedby": errorId,
+						children: /* @__PURE__ */ jsx(X, {
+							size: 14,
+							"aria-hidden": "true"
+						})
+					})
+				})] })
+			]
+		});
+	}
+	const href = safeHref(block.src ?? "");
+	if (attachmentIsImage(block) && href) return /* @__PURE__ */ jsx("img", {
+		className: RichTextAttachment_module_default.attachmentImg,
+		src: href,
+		alt: block.alt ?? name,
+		width: block.width,
+		height: block.height,
+		onLoad: (e) => {
+			const img = e.currentTarget;
+			if (img.naturalWidth && img.naturalHeight) img.style.setProperty("--rich-text-image-aspect", String(img.naturalWidth / img.naturalHeight));
+		}
+	});
+	return /* @__PURE__ */ jsxs("a", {
+		className: RichTextAttachment_module_default.attachmentChip,
+		href,
+		download: true,
+		rel: "noopener noreferrer",
+		children: [/* @__PURE__ */ jsx(AttachFileIcon, {}), /* @__PURE__ */ jsx("span", {
+			className: RichTextAttachment_module_default.attachmentName,
+			children: name
+		})]
+	});
+}
+export { RichTextAttachment };

package/dist/components/RichText/RichTextAttachment.module.js

@@ -0,0 +1,19 @@
+import "./RichTextAttachment.css";
+// src/components/RichText/RichTextAttachment.module.scss
+var attachmentImg = "RichTextAttachment__attachmentImg__yrXdm";
+var attachmentLoading = "RichTextAttachment__attachmentLoading__nwKWM";
+var attachmentError = "RichTextAttachment__attachmentError__Ct_gI";
+var attachmentChip = "RichTextAttachment__attachmentChip__pQhOg";
+var attachmentName = "RichTextAttachment__attachmentName__qEYIR";
+var attachmentLabel = "RichTextAttachment__attachmentLabel__RBGKX";
+var attachmentReason = "RichTextAttachment__attachmentReason__6Es5S";
+var RichTextAttachment_module_default = {
+	attachmentImg,
+	attachmentLoading,
+	attachmentError,
+	attachmentChip,
+	attachmentName,
+	attachmentLabel,
+	attachmentReason
+};
+export { attachmentChip, attachmentError, attachmentImg, attachmentLabel, attachmentLoading, attachmentName, attachmentReason, RichTextAttachment_module_default as default };

package/dist/components/RichText/attachmentIcon.d.ts

@@ -0,0 +1 @@
+export declare function AttachFileIcon(): import("react").JSX.Element;

package/dist/components/RichText/attachmentIcon.js

@@ -0,0 +1,21 @@
+'use client';
+import { jsx } from "react/jsx-runtime";
+// src/components/RichText/attachmentIcon.tsx
+var base = {
+	width: 16,
+	height: 16,
+	viewBox: "0 0 24 24",
+	fill: "none",
+	stroke: "currentColor",
+	strokeWidth: 2,
+	strokeLinecap: "round",
+	strokeLinejoin: "round",
+	"aria-hidden": true
+};
+function AttachFileIcon() {
+	return /* @__PURE__ */ jsx("svg", {
+		...base,
+		children: /* @__PURE__ */ jsx("path", { d: "M21.44 11.05l-9.19 9.19a5 5 0 0 1-7.07-7.07l9.19-9.19a3 3 0 0 1 4.24 4.24l-9.2 9.19a1 1 0 0 1-1.41-1.41l8.49-8.49" })
+	});
+}
+export { AttachFileIcon };

package/dist/components/RichText/engine/attachment.d.ts

@@ -0,0 +1,67 @@
+import type { RichDoc, Block, Point, Range } from './model.js';
+/**
+ * Fields for creating/patching an attachment block. All optional; only the
+ * provided keys are written (so a block stays canonical — no `undefined` keys).
+ * Mirrors the attachment fields on {@link Block}.
+ */
+export interface AttachmentAttrs {
+    /** Display name / chip label (usually the File's name). */
+    name?: string;
+    /** MIME type — `image/*` renders an inline preview, else a file chip. */
+    mime?: string;
+    /** The uploaded URL. Absent while `status: 'uploading'`. */
+    src?: string;
+    /** Natural image dimensions (layout hints). */
+    width?: number;
+    height?: number;
+    /**
+     * Image alt text. An EMPTY string is honoured, not treated as unset —
+     * `alt=""` is HTML's marker for a decorative image. This is the library's
+     * one exception to "an empty label means unset".
+     */
+    alt?: string;
+    /** Image alignment. */
+    align?: 'left' | 'center' | 'right';
+    /** Upload state. Defaults to `'ready'` when omitted. */
+    status?: 'uploading' | 'ready' | 'error';
+    /** Failure reason shown on an `error` block (from an `UploadError`). */
+    uploadError?: string;
+}
+/** True for void blocks (no editable text; caret sits adjacent, never inside). */
+export declare function isVoidBlock(block: Block): boolean;
+/**
+ * Whether an attachment should render/serialize as an inline image (vs a file
+ * chip). Decided by `mime` (`image/*`), falling back to the URL extension. Shared
+ * by the renderer and the HTML/Markdown serializers so the rule never drifts.
+ */
+export declare function attachmentIsImage(block: Pick<Block, 'mime' | 'src'>): boolean;
+/**
+ * Whether an attachment is "settled" — its upload finished (`status: 'ready'`) OR
+ * it is a persisted/imported block whose transient `status` was dropped on
+ * serialization (`status` absent). Excludes in-flight (`uploading`) and failed
+ * (`error`) blocks. This is the SAME set the renderer treats as displayable, so
+ * the editor's resize-handle / Configure gates must use it (not a stricter
+ * `status === 'ready'`) or they silently disagree on persisted docs. See #263.
+ */
+export declare function isAttachmentSettled(block: Pick<Block, 'status'>): boolean;
+/**
+ * Split the block at `point` and insert an attachment block between the halves.
+ * Always leaves an editable paragraph AFTER the attachment (the caret's home);
+ * the caret lands at offset 0 of that trailing block. If `point` is inside a void
+ * block, inserts after it instead of splitting. Returns the new block's
+ * `attachmentId` so callers needn't re-derive it from array position (`null` on
+ * the no-op path when `point.blockId` isn't found).
+ */
+export declare function insertAttachmentBlock(doc: RichDoc, point: Point, attrs: AttachmentAttrs): {
+    doc: RichDoc;
+    selection: Range;
+    attachmentId: string | null;
+};
+/** Patch an attachment block's fields by id. Same-ref no-op if absent/not attachment. */
+export declare function updateAttachmentBlock(doc: RichDoc, id: string, patch: AttachmentAttrs): RichDoc;
+/**
+ * Remove the given keys from an attachment block (canonical "unset" — e.g.
+ * resetting width/height to natural size). Same-ref no-op if the id is absent,
+ * not an attachment, or none of the keys are present.
+ */
+export declare function clearAttachmentFields(doc: RichDoc, id: string, keys: ('width' | 'height' | 'align' | 'alt' | 'uploadError')[]): RichDoc;

package/dist/components/RichText/engine/attachment.js

@@ -0,0 +1,127 @@
+import { createBlock, nextId } from "./model.js";
+import { blockLength, collapsedRange, findBlockIndex } from "./position.js";
+import { normalizeInlines, sliceInlines } from "./inlines.js";
+// src/components/RichText/engine/attachment.ts
+/** True for void blocks (no editable text; caret sits adjacent, never inside). */
+function isVoidBlock(block) {
+	return block.type === "attachment";
+}
+/**
+* Whether an attachment should render/serialize as an inline image (vs a file
+* chip). Decided by `mime` (`image/*`), falling back to the URL extension. Shared
+* by the renderer and the HTML/Markdown serializers so the rule never drifts.
+*/
+function attachmentIsImage(block) {
+	if (block.mime) return block.mime.startsWith("image/");
+	return /\.(png|jpe?g|gif|webp|avif|svg)(\?|$)/i.test(block.src ?? "");
+}
+/**
+* Whether an attachment is "settled" — its upload finished (`status: 'ready'`) OR
+* it is a persisted/imported block whose transient `status` was dropped on
+* serialization (`status` absent). Excludes in-flight (`uploading`) and failed
+* (`error`) blocks. This is the SAME set the renderer treats as displayable, so
+* the editor's resize-handle / Configure gates must use it (not a stricter
+* `status === 'ready'`) or they silently disagree on persisted docs. See #263.
+*/
+function isAttachmentSettled(block) {
+	return block.status === "ready" || block.status == null;
+}
+function attachmentBlock(attrs) {
+	return {
+		id: nextId(),
+		type: "attachment",
+		inlines: [],
+		status: attrs.status ?? "ready",
+		...attrs.name !== void 0 ? { name: attrs.name } : {},
+		...attrs.mime !== void 0 ? { mime: attrs.mime } : {},
+		...attrs.src !== void 0 ? { src: attrs.src } : {},
+		...attrs.width !== void 0 ? { width: attrs.width } : {},
+		...attrs.height !== void 0 ? { height: attrs.height } : {},
+		...attrs.alt !== void 0 ? { alt: attrs.alt } : {},
+		...attrs.align !== void 0 ? { align: attrs.align } : {}
+	};
+}
+/**
+* Split the block at `point` and insert an attachment block between the halves.
+* Always leaves an editable paragraph AFTER the attachment (the caret's home);
+* the caret lands at offset 0 of that trailing block. If `point` is inside a void
+* block, inserts after it instead of splitting. Returns the new block's
+* `attachmentId` so callers needn't re-derive it from array position (`null` on
+* the no-op path when `point.blockId` isn't found).
+*/
+function insertAttachmentBlock(doc, point, attrs) {
+	const idx = findBlockIndex(doc, point.blockId);
+	if (idx === -1) return {
+		doc,
+		selection: collapsedRange(point.blockId, point.offset),
+		attachmentId: null
+	};
+	const block = doc.blocks[idx];
+	const att = attachmentBlock(attrs);
+	if (isVoidBlock(block)) {
+		const after = createBlock("paragraph");
+		return {
+			doc: { blocks: [
+				...doc.blocks.slice(0, idx + 1),
+				att,
+				after,
+				...doc.blocks.slice(idx + 1)
+			] },
+			selection: collapsedRange(after.id),
+			attachmentId: att.id
+		};
+	}
+	const left = {
+		...block,
+		inlines: normalizeInlines(sliceInlines(block.inlines, 0, point.offset))
+	};
+	const rightInlines = normalizeInlines(sliceInlines(block.inlines, point.offset, blockLength(block)));
+	const right = {
+		...createBlock(block.type, "", {
+			level: block.level,
+			depth: block.depth
+		}),
+		inlines: rightInlines
+	};
+	return {
+		doc: { blocks: [
+			...doc.blocks.slice(0, idx),
+			left,
+			att,
+			right,
+			...doc.blocks.slice(idx + 1)
+		] },
+		selection: collapsedRange(right.id),
+		attachmentId: att.id
+	};
+}
+/** Patch an attachment block's fields by id. Same-ref no-op if absent/not attachment. */
+function updateAttachmentBlock(doc, id, patch) {
+	const idx = findBlockIndex(doc, id);
+	if (idx === -1 || doc.blocks[idx].type !== "attachment") return doc;
+	const clean = {};
+	for (const [k, v] of Object.entries(patch)) if (v !== void 0) clean[k] = v;
+	const blocks = doc.blocks.slice();
+	blocks[idx] = {
+		...blocks[idx],
+		...clean
+	};
+	return { blocks };
+}
+/**
+* Remove the given keys from an attachment block (canonical "unset" — e.g.
+* resetting width/height to natural size). Same-ref no-op if the id is absent,
+* not an attachment, or none of the keys are present.
+*/
+function clearAttachmentFields(doc, id, keys) {
+	const idx = findBlockIndex(doc, id);
+	if (idx === -1 || doc.blocks[idx].type !== "attachment") return doc;
+	const block = doc.blocks[idx];
+	if (!keys.some((k) => k in block)) return doc;
+	const next = { ...block };
+	for (const k of keys) delete next[k];
+	const blocks = doc.blocks.slice();
+	blocks[idx] = next;
+	return { blocks };
+}
+export { attachmentIsImage, clearAttachmentFields, insertAttachmentBlock, isAttachmentSettled, isVoidBlock, updateAttachmentBlock };

package/dist/components/RichText/engine/autolink.d.ts

@@ -0,0 +1,10 @@
+import type { Inline } from './model.js';
+/** The URL that ends exactly at the end of `text`, or null. (For the type rule:
+ *  the caller passes the text up to the caret.) */
+export declare function findUrl(text: string): {
+    start: number;
+    end: number;
+    href: string;
+} | null;
+/** Split `text` into plain + link runs (for paste / import). */
+export declare function linkifyRuns(text: string): Inline[];

package/dist/components/RichText/engine/autolink.js

@@ -0,0 +1,77 @@
+import { safeHref } from "./safeHref.js";
+// src/components/RichText/engine/autolink.ts
+var URL_RE = /\b(?:https?:\/\/|www\.)[^\s<>()[\]]+/gi;
+var TRAILING = /[.,;:!?'"]+$/;
+function normalize(raw) {
+	let url = raw.replace(TRAILING, "");
+	if (/[)\]]$/.test(url) && !/[([]/.test(url)) url = url.slice(0, -1);
+	if (url === "") return null;
+	const candidate = url.startsWith("www.") ? `https://${url}` : url;
+	const safe = safeHref(candidate);
+	if (!safe || !/^https?:/i.test(safe)) return null;
+	return {
+		url,
+		href: safe
+	};
+}
+/** The URL that ends exactly at the end of `text`, or null. (For the type rule:
+*  the caller passes the text up to the caret.) */
+function findUrl(text) {
+	let m;
+	URL_RE.lastIndex = 0;
+	let last = null;
+	while ((m = URL_RE.exec(text)) !== null) {
+		const norm = normalize(m[0]);
+		if (!norm) continue;
+		const start = m.index;
+		const end = start + norm.url.length;
+		const rawEnd = start + m[0].length;
+		last = {
+			start,
+			end,
+			href: norm.href,
+			rawEnd
+		};
+	}
+	if (!last) return null;
+	const tail = text.slice(last.rawEnd);
+	if (!/^[.,;:!?'")\]]*$/.test(tail)) return null;
+	return {
+		start: last.start,
+		end: last.end,
+		href: last.href
+	};
+}
+/** Split `text` into plain + link runs (for paste / import). */
+function linkifyRuns(text) {
+	const runs = [];
+	let i = 0;
+	let m;
+	URL_RE.lastIndex = 0;
+	while ((m = URL_RE.exec(text)) !== null) {
+		const norm = normalize(m[0]);
+		if (!norm) continue;
+		const start = m.index;
+		if (start > i) runs.push({
+			text: text.slice(i, start),
+			marks: []
+		});
+		runs.push({
+			text: norm.url,
+			marks: [{
+				type: "link",
+				href: norm.href
+			}]
+		});
+		i = start + norm.url.length;
+	}
+	if (i < text.length) runs.push({
+		text: text.slice(i),
+		marks: []
+	});
+	return runs.length ? runs : [{
+		text,
+		marks: []
+	}];
+}
+export { findUrl, linkifyRuns };

package/dist/components/RichText/engine/blockUnit.d.ts

@@ -0,0 +1,53 @@
+import type { RichDoc, Block, Range } from './model.js';
+/** Half-open index range `[start, end)` of the unit anchored at `index`. */
+export declare function blockUnitRange(blocks: Block[], index: number): {
+    start: number;
+    end: number;
+};
+/**
+ * Index of the previous sibling's anchor (same effective depth, same list run),
+ * or -1 when `index` is the first child / first block. Descendant blocks of an
+ * earlier sibling (greater depth) are skipped.
+ */
+export declare function prevSiblingAnchor(blocks: Block[], index: number): number;
+/**
+ * Swap the unit anchored at `blockId` with its adjacent SIBLING unit (`dir`: -1
+ * up / +1 down). Same-depth swap, so depths are preserved. No-op (returns the
+ * SAME doc reference) at an edge / when there is no sibling in that direction.
+ */
+export declare function moveBlockUnit(doc: RichDoc, blockId: string, dir: -1 | 1): {
+    doc: RichDoc;
+    selection: Range;
+};
+/**
+ * Duplicate the unit anchored at `blockId`, inserting the clones immediately
+ * after the unit. Fresh ids; depths preserved. Caret lands on the clone's anchor.
+ */
+export declare function duplicateBlockUnit(doc: RichDoc, blockId: string): {
+    doc: RichDoc;
+    selection: Range;
+};
+/**
+ * Remove the unit anchored at `blockId`. Empties to a single empty paragraph if
+ * it was the whole document. Caret lands on the next surviving block, else the
+ * previous, else the new empty paragraph.
+ */
+export declare function removeBlockUnit(doc: RichDoc, blockId: string): {
+    doc: RichDoc;
+    selection: Range;
+};
+/** Insert an empty paragraph directly after the block unit anchored at `blockId`. */
+export declare function insertEmptyBlockBelow(doc: RichDoc, blockId: string): {
+    doc: RichDoc;
+    selection: Range;
+};
+/**
+ * Move the unit anchored at `blockId` so its first block lands at array index
+ * `target` (coordinates of the CURRENT array). The moved unit's top depth is
+ * clamped to a value valid for its new predecessor (`prevListDepth + 1`, else 0);
+ * descendants shift by the same delta. No-op when `target` falls inside the unit.
+ */
+export declare function moveBlockUnitToIndex(doc: RichDoc, blockId: string, target: number): {
+    doc: RichDoc;
+    selection: Range;
+};