@bettercms-ai/kit 0.1.1 → 2.0.0

package/dist/controls/rich-text/control.js

@@ -0,0 +1,296 @@
+import { cn } from "../../lib/cn.js";
+import { useForm, useKitEnv, useKitServices } from "../../context.js";
+import { pathKey } from "../../lib/path.js";
+import { Tooltip } from "../../ui/overlay.js";
+import { Textarea } from "../../ui/input.js";
+import { resolveFrames } from "../../lib/frames.js";
+import { LegacyFallback } from "../../engine/kit-field.js";
+import { TEXT_FOCUS } from "../text.js";
+import { UnknownValueNote } from "../unknown-value.js";
+import { editorRoundTrip } from "./dom.js";
+import { RichTextEditor } from "./editor.js";
+import { paragraphsHtml, plainParagraphs, usePlainRichText } from "./plain.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { IconArrowsMaximize } from "@tabler/icons-react";
+//#region src/controls/rich-text/control.tsx
+/**
+* Rich text field (V2 HEAD controls/richtext.tsx, CPO D49).
+*  - The editor stays in place: the document variant is the full editor in the column, the panel variant (inspector)
+*    the same editor height-capped.
+*  - Expanding (the toolbar's expand button, ⌘↵, or the expand icon in the field's label row at rest) opens the shared
+*    ExpandedEditorModal: breadcrumb "Section › Item › Field", word count, Done. Esc closes and focus returns.
+*
+* STORAGE. The editor edits HTML; the stored value stays what production stores for the field, through the host's
+* codec (KitServices.richText, see ./codec.ts):
+*   - read:  stored value → the HTML the editor opens on (+ what the field accepts)
+*   - write: edited HTML → the stored value, in the surface's own shape; a write that would drop something is refused,
+*            named, and nothing is stored
+*   - probe: a value the editor cannot carry unchanged (open → no edit → write ≠ stored) is not opened here at all: the
+*            host's own control edits it (LegacyFallback), with the reason above it. Opening never writes.
+*/
+var openKey = null;
+var subs = /* @__PURE__ */ new Set();
+function setFullEditor(key) {
+	openKey = key;
+	subs.forEach((s) => s());
+}
+function useFullEditorKey() {
+	return React.useSyncExternalStore((cb) => {
+		subs.add(cb);
+		return () => subs.delete(cb);
+	}, () => openKey, () => openKey);
+}
+var handedOff = /* @__PURE__ */ new Set();
+function setHandedOff(key, on) {
+	if (handedOff.has(key) === on) return;
+	if (on) handedOff.add(key);
+	else handedOff.delete(key);
+	subs.forEach((s) => s());
+}
+function useHandedOff(key) {
+	return React.useSyncExternalStore((cb) => {
+		subs.add(cb);
+		return () => subs.delete(cb);
+	}, () => handedOff.has(key), () => handedOff.has(key));
+}
+/** The expanded editor's breadcrumb: the form's frames (root › drilled items) and this field. */
+function useExpandCrumbs(fieldTitle) {
+	const form = useForm();
+	const env = useKitEnv();
+	if (!form) return [env.docTitle, fieldTitle].filter(Boolean);
+	const { frames } = resolveFrames(form.schema, form.value, form.path, form.resolveSchema);
+	return [...frames.filter((f) => f.kind !== "history").map((f, i) => i === 0 ? env.docTitle || f.title : f.title), fieldTitle];
+}
+/** A stored block array, or the `{ content }` / `{ format, value }` envelope around one, holding a pull quote block. */
+var holdsPullQuote = (seed) => Array.isArray(seed) ? seed.some((b) => !!b && typeof b === "object" && b._type === "pullQuote") : !!seed && typeof seed === "object" && holdsPullQuote(seed.content ?? seed.value);
+/**
+* Open a stored value: read it, then prove the editor carries it unchanged (load → serialize → write === stored).
+* A codec that throws, or a value that does not survive, is handed to the host's own control with the reason.
+*/
+function openValue(codec, value, at) {
+	let read;
+	try {
+		read = codec.read(value, at);
+	} catch (err) {
+		return {
+			ok: false,
+			reason: `the stored text could not be read (${err instanceof Error ? err.message : String(err)})`
+		};
+	}
+	if (holdsPullQuote(read.seed) && (!/data-rt="pullquote"/.test(read.html) || !read.features.includes("pullquote"))) return {
+		ok: false,
+		reason: "it holds a pull quote, which the standard editor edits"
+	};
+	const html = editorRoundTrip(read.html);
+	try {
+		const back = codec.write(html, at, value);
+		if (back.losses.length) return {
+			ok: false,
+			reason: `this editor would drop ${back.losses.join(", ")}`
+		};
+		if (!codec.same(back.value, read.seed)) return {
+			ok: false,
+			reason: "it holds formatting this editor cannot keep"
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			reason: `the text could not be checked (${err instanceof Error ? err.message : String(err)})`
+		};
+	}
+	return {
+		ok: true,
+		read,
+		html
+	};
+}
+function RichTextControl(props) {
+	const { richText } = useKitServices();
+	if (!richText) return /* @__PURE__ */ jsx(LegacyFallback, { ...props });
+	return /* @__PURE__ */ jsx(CodecRichText, {
+		codec: richText,
+		...props
+	});
+}
+function CodecRichText({ codec, field, value, onChange, readOnly, path, id, invalid }) {
+	const env = useKitEnv();
+	const docKey = `${env.docId}:${pathKey(path)}`;
+	const open = useFullEditorKey() === docKey;
+	const crumbs = useExpandCrumbs(field.title);
+	const plainScope = usePlainRichText();
+	const at = React.useMemo(() => ({
+		field,
+		path
+	}), [field, path]);
+	const { useInsertableComponents } = useKitServices();
+	const insertable = useInsertableComponents?.(at);
+	const mine = React.useRef(null);
+	const [refusal, setRefusal] = React.useState(null);
+	const opened = React.useMemo(() => {
+		if (mine.current && mine.current.value === value) try {
+			return {
+				ok: true,
+				read: codec.read(value, at),
+				html: mine.current.html
+			};
+		} catch {}
+		return openValue(codec, value, at);
+	}, [
+		codec,
+		value,
+		JSON.stringify(field),
+		pathKey(path)
+	]);
+	React.useEffect(() => () => {
+		if (openKey === docKey) setFullEditor(null);
+		setHandedOff(docKey, false);
+	}, [docKey]);
+	React.useLayoutEffect(() => {
+		setHandedOff(docKey, !opened.ok);
+		if (!opened.ok && openKey === docKey) setFullEditor(null);
+	}, [docKey, opened.ok]);
+	if (!opened.ok) return /* @__PURE__ */ jsxs("div", {
+		className: "flex min-w-0 flex-col gap-1.5",
+		children: [/* @__PURE__ */ jsxs("p", {
+			role: "note",
+			"data-slot": "kit-richtext-handoff",
+			className: "rounded-kit-md bg-kit-subtle px-2.5 py-1.5 text-kit-xs text-kit-fg-2",
+			children: [
+				"Edited with the standard editor: ",
+				opened.reason,
+				"."
+			]
+		}), /* @__PURE__ */ jsx(LegacyFallback, {
+			field,
+			value,
+			onChange,
+			readOnly,
+			path,
+			id,
+			invalid
+		})]
+	});
+	const { read, html } = opened;
+	const write = (next) => {
+		let res;
+		try {
+			res = codec.write(next, at, value);
+		} catch (err) {
+			setRefusal(`Not saved: the text could not be stored (${err instanceof Error ? err.message : String(err)}). Undo the last change with ⌘Z; leaving the field puts back the saved text.`);
+			return;
+		}
+		if (res.losses.length) {
+			setRefusal(`Not saved: this field cannot keep ${res.losses.join(", ")}. Undo the last change with ⌘Z; leaving the field puts back the saved text.`);
+			return;
+		}
+		setRefusal(null);
+		if (codec.same(res.value, value)) return;
+		mine.current = {
+			value: res.value,
+			html: next
+		};
+		onChange(res.value);
+	};
+	const plain = plainScope && !read.losses.length ? plainParagraphs(html) : null;
+	if (plain !== null) return /* @__PURE__ */ jsxs("div", {
+		className: "flex min-w-0 flex-col gap-1.5",
+		children: [/* @__PURE__ */ jsx(Textarea, {
+			id,
+			rows: 3,
+			value: plain,
+			readOnly,
+			"aria-invalid": invalid || !!refusal,
+			placeholder: field.placeholder,
+			onChange: (e) => write(paragraphsHtml(e.target.value)),
+			className: cn(TEXT_FOCUS, "leading-5")
+		}), refusal ? /* @__PURE__ */ jsx("p", {
+			role: "alert",
+			className: "text-kit-xs text-kit-danger-fg",
+			children: refusal
+		}) : null]
+	});
+	return /* @__PURE__ */ jsxs("div", { children: [
+		read.losses.length ? /* @__PURE__ */ jsxs("p", {
+			role: "status",
+			className: "mb-1.5 rounded-kit-md bg-kit-warning-soft px-2.5 py-1.5 text-kit-xs text-kit-warning-fg",
+			children: [
+				"Saved by an earlier editor. Editing here would drop ",
+				read.losses.join(", "),
+				". Nothing changes until you edit."
+			]
+		}) : null,
+		read.undeclared?.length && codec.remap ? /* @__PURE__ */ jsx("div", {
+			className: "mb-1.5",
+			children: /* @__PURE__ */ jsx(UnknownValueNote, {
+				items: read.undeclared,
+				onRemap: (key, to) => onChange(codec.remap(value, at, key, to)),
+				onRemove: (key) => onChange(codec.remap(value, at, key, null)),
+				readOnly
+			})
+		}) : null,
+		/* @__PURE__ */ jsx(RichTextEditor, {
+			value: html,
+			onChange: write,
+			readOnly,
+			placeholder: field.placeholder,
+			docKey,
+			id,
+			invalid: invalid || !!refusal,
+			features: read.features,
+			single: read.single,
+			allowNewTab: read.newTab,
+			components: insertable && !read.single && !readOnly ? insertable : void 0,
+			variant: env.variant === "document" ? "document" : "panel",
+			maxHeight: env.variant === "document" ? void 0 : 320,
+			expandCrumbs: crumbs,
+			expandedOpen: open,
+			onExpandedOpenChange: (o) => setFullEditor(o ? docKey : null),
+			onComment: env.onComment ? (quote) => env.onComment?.(path, field, quote) : void 0
+		}),
+		refusal ? /* @__PURE__ */ jsx("p", {
+			role: "alert",
+			className: "mt-1.5 text-kit-xs text-kit-danger-fg",
+			children: refusal
+		}) : null
+	] });
+}
+/** Label-row action (at rest): the field's toolbar holds the same button while it's open. */
+function readsPlain(codec, value, field, path) {
+	try {
+		const read = codec.read(value, {
+			field,
+			path
+		});
+		return !read.losses.length && plainParagraphs(editorRoundTrip(read.html)) !== null;
+	} catch {
+		return false;
+	}
+}
+function RichTextExpandAction({ path, field, value }) {
+	const env = useKitEnv();
+	const { richText } = useKitServices();
+	const handed = useHandedOff(`${env.docId}:${pathKey(path)}`);
+	const plainScope = usePlainRichText();
+	if (env.variant === "document" || !richText || handed) return null;
+	if (plainScope && readsPlain(richText, value, field, path)) return null;
+	return /* @__PURE__ */ jsx(Tooltip, {
+		content: "Expand editor",
+		shortcut: "⌘↵",
+		children: /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"aria-label": `Expand ${field.title}`,
+			onClick: () => setFullEditor(`${env.docId}:${pathKey(path)}`),
+			className: cn("-my-0.5 hidden size-6 items-center justify-center rounded-kit-md text-kit-fg-3 hover:bg-kit-hover hover:text-kit-fg", "group-hover/field:inline-flex group-focus-within/field:!hidden [@media(pointer:coarse)]:inline-flex"),
+			children: /* @__PURE__ */ jsx(IconArrowsMaximize, {
+				className: "size-3.5",
+				stroke: 1.5,
+				"aria-hidden": true
+			})
+		})
+	});
+}
+//#endregion
+export { RichTextControl, RichTextExpandAction, openValue, setFullEditor };
+
+//# sourceMappingURL=control.js.map

package/dist/controls/rich-text/control.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.js","names":[],"sources":["../../../src/controls/rich-text/control.tsx"],"sourcesContent":["/**\n * Rich text field (V2 HEAD controls/richtext.tsx, CPO D49).\n *  - The editor stays in place: the document variant is the full editor in the column, the panel variant (inspector)\n *    the same editor height-capped.\n *  - Expanding (the toolbar's expand button, ⌘↵, or the expand icon in the field's label row at rest) opens the shared\n *    ExpandedEditorModal: breadcrumb \"Section › Item › Field\", word count, Done. Esc closes and focus returns.\n *\n * STORAGE. The editor edits HTML; the stored value stays what production stores for the field, through the host's\n * codec (KitServices.richText, see ./codec.ts):\n *   - read:  stored value → the HTML the editor opens on (+ what the field accepts)\n *   - write: edited HTML → the stored value, in the surface's own shape; a write that would drop something is refused,\n *            named, and nothing is stored\n *   - probe: a value the editor cannot carry unchanged (open → no edit → write ≠ stored) is not opened here at all: the\n *            host's own control edits it (LegacyFallback), with the reason above it. Opening never writes.\n */\nimport * as React from \"react\";\nimport { IconArrowsMaximize } from \"@tabler/icons-react\";\nimport { cn } from \"../../lib/cn\";\nimport { useForm, useKitEnv, useKitServices } from \"../../context\";\nimport { resolveFrames } from \"../../lib/frames\";\nimport { pathKey } from \"../../lib/path\";\nimport type { ControlProps } from \"../../types\";\nimport { Tooltip } from \"../../ui/overlay\";\nimport { LegacyFallback } from \"../../engine/kit-field\";\nimport type { KitRichTextCodec, RichTextRead } from \"./codec\";\nimport { editorRoundTrip } from \"./dom\";\nimport { RichTextEditor } from \"./editor\";\nimport { paragraphsHtml, plainParagraphs, usePlainRichText } from \"./plain\";\nimport { Textarea } from \"../../ui/input\";\nimport { TEXT_FOCUS } from \"../text\";\nimport { UnknownValueNote } from \"../unknown-value\";\n\n/* ── which rich-text field (docKey) has its full editor open — shared with the label-row action ── */\nlet openKey: string | null = null;\nconst subs = new Set<() => void>();\nexport function setFullEditor(key: string | null) {\n  openKey = key;\n  subs.forEach((s) => s());\n}\nfunction useFullEditorKey() {\n  return React.useSyncExternalStore(\n    (cb) => {\n      subs.add(cb);\n      return () => subs.delete(cb);\n    },\n    () => openKey,\n    () => openKey,\n  );\n}\n\n/* ── fields whose value went to the host's own control: the label-row expand button is not theirs to draw ── */\nconst handedOff = new Set<string>();\nfunction setHandedOff(key: string, on: boolean) {\n  if (handedOff.has(key) === on) return;\n  if (on) handedOff.add(key);\n  else handedOff.delete(key);\n  subs.forEach((s) => s());\n}\nfunction useHandedOff(key: string) {\n  return React.useSyncExternalStore(\n    (cb) => {\n      subs.add(cb);\n      return () => subs.delete(cb);\n    },\n    () => handedOff.has(key),\n    () => handedOff.has(key),\n  );\n}\n\n/** The expanded editor's breadcrumb: the form's frames (root › drilled items) and this field. */\nfunction useExpandCrumbs(fieldTitle: string): string[] {\n  const form = useForm();\n  const env = useKitEnv();\n  if (!form) return [env.docTitle, fieldTitle].filter(Boolean) as string[];\n  const { frames } = resolveFrames(form.schema, form.value, form.path, form.resolveSchema);\n  const titles = frames.filter((f) => f.kind !== \"history\").map((f, i) => (i === 0 ? env.docTitle || f.title : f.title));\n  return [...titles, fieldTitle];\n}\n\n/** A stored block array, or the `{ content }` / `{ format, value }` envelope around one, holding a pull quote block. */\nconst holdsPullQuote = (seed: unknown): boolean =>\n  Array.isArray(seed)\n    ? seed.some((b) => !!b && typeof b === \"object\" && (b as { _type?: unknown })._type === \"pullQuote\")\n    : !!seed && typeof seed === \"object\" && holdsPullQuote((seed as { content?: unknown; value?: unknown }).content ?? (seed as { value?: unknown }).value);\n\n/** What the control decided for one stored value. */\ntype Opened =\n  | { ok: true; read: RichTextRead; html: string }\n  | { ok: false; reason: string };\n\n/**\n * Open a stored value: read it, then prove the editor carries it unchanged (load → serialize → write === stored).\n * A codec that throws, or a value that does not survive, is handed to the host's own control with the reason.\n */\nexport function openValue(codec: KitRichTextCodec, value: unknown, at: Parameters<KitRichTextCodec[\"read\"]>[1]): Opened {\n  let read: RichTextRead;\n  try {\n    read = codec.read(value, at);\n  } catch (err) {\n    return { ok: false, reason: `the stored text could not be read (${err instanceof Error ? err.message : String(err)})` };\n  }\n  // a pull quote (V2 D55 article block) opens as the editor's pull-quote island, but only when the codec renders the\n  // stored block as its markup in a field that offers it: a codec that renders nothing for it, or a field with no place\n  // for one (a single paragraph), would lose it, so the standard editor edits it\n  if (holdsPullQuote(read.seed) && (!/data-rt=\"pullquote\"/.test(read.html) || !read.features.includes(\"pullquote\")))\n    return { ok: false, reason: \"it holds a pull quote, which the standard editor edits\" };\n  // tables and pull quotes are islands (V2 TableBlock, PullQuote); the probe below proves they survive unchanged\n  const html = editorRoundTrip(read.html);\n  try {\n    const back = codec.write(html, at, value);\n    if (back.losses.length) return { ok: false, reason: `this editor would drop ${back.losses.join(\", \")}` };\n    if (!codec.same(back.value, read.seed)) return { ok: false, reason: \"it holds formatting this editor cannot keep\" };\n  } catch (err) {\n    return { ok: false, reason: `the text could not be checked (${err instanceof Error ? err.message : String(err)})` };\n  }\n  return { ok: true, read, html };\n}\n\nexport function RichTextControl(props: ControlProps) {\n  const { richText } = useKitServices();\n  if (!richText) return <LegacyFallback {...props} />;\n  return <CodecRichText codec={richText} {...props} />;\n}\n\nfunction CodecRichText({ codec, field, value, onChange, readOnly, path, id, invalid }: ControlProps & { codec: KitRichTextCodec }) {\n  const env = useKitEnv();\n  const docKey = `${env.docId}:${pathKey(path)}`;\n  const open = useFullEditorKey() === docKey;\n  const crumbs = useExpandCrumbs(field.title);\n  const plainScope = usePlainRichText();\n  const at = React.useMemo(() => ({ field, path }), [field, path]);\n  // the components this field may embed (More components): a hook with one identity for the form's life, so calling it\n  // only when the host provides it keeps the hook order fixed\n  const { useInsertableComponents } = useKitServices();\n  const insertable = useInsertableComponents?.(at);\n  /* our own last write: its value comes back as `value`, and the editor keeps the HTML it emitted (no reload, no probe) */\n  const mine = React.useRef<{ value: unknown; html: string } | null>(null);\n  const [refusal, setRefusal] = React.useState<string | null>(null);\n  const opened = React.useMemo<Opened>(() => {\n    if (mine.current && mine.current.value === value) {\n      try {\n        return { ok: true, read: codec.read(value, at), html: mine.current.html };\n      } catch {\n        /* judged afresh below, which names the failure */\n      }\n    }\n    return openValue(codec, value, at);\n    // `at` changes identity with the field object; the field's content is what matters\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [codec, value, JSON.stringify(field), pathKey(path)]);\n\n  // close when this field goes away (block deselected, drilled elsewhere)\n  React.useEffect(\n    () => () => {\n      if (openKey === docKey) setFullEditor(null);\n      setHandedOff(docKey, false);\n    },\n    [docKey],\n  );\n  React.useLayoutEffect(() => {\n    setHandedOff(docKey, !opened.ok);\n    if (!opened.ok && openKey === docKey) setFullEditor(null);\n  }, [docKey, opened.ok]);\n\n  if (!opened.ok)\n    return (\n      <div className=\"flex min-w-0 flex-col gap-1.5\">\n        <p role=\"note\" data-slot=\"kit-richtext-handoff\" className=\"rounded-kit-md bg-kit-subtle px-2.5 py-1.5 text-kit-xs text-kit-fg-2\">\n          Edited with the standard editor: {opened.reason}.\n        </p>\n        <LegacyFallback field={field} value={value} onChange={onChange} readOnly={readOnly} path={path} id={id} invalid={invalid} />\n      </div>\n    );\n\n  const { read, html } = opened;\n  const write = (next: string) => {\n    let res;\n    try {\n      res = codec.write(next, at, value);\n    } catch (err) {\n      setRefusal(`Not saved: the text could not be stored (${err instanceof Error ? err.message : String(err)}). Undo the last change with ⌘Z; leaving the field puts back the saved text.`);\n      return;\n    }\n    if (res.losses.length) {\n      setRefusal(`Not saved: this field cannot keep ${res.losses.join(\", \")}. Undo the last change with ⌘Z; leaving the field puts back the saved text.`);\n      return;\n    }\n    setRefusal(null);\n    if (codec.same(res.value, value)) return;\n    mine.current = { value: res.value, html: next };\n    onChange(res.value);\n  };\n\n  // The Values popover (PlainRichTextScope): plain paragraphs are V2's growing textarea (its `text` control), written\n  // back through the same codec, one `<p>` per line. Anything richer keeps the editor below.\n  const plain = plainScope && !read.losses.length ? plainParagraphs(html) : null;\n  if (plain !== null)\n    return (\n      <div className=\"flex min-w-0 flex-col gap-1.5\">\n        <Textarea\n          id={id}\n          rows={3}\n          value={plain}\n          readOnly={readOnly}\n          aria-invalid={invalid || !!refusal}\n          placeholder={field.placeholder}\n          onChange={(e) => write(paragraphsHtml(e.target.value))}\n          className={cn(TEXT_FOCUS, \"leading-5\")}\n        />\n        {refusal ? (\n          <p role=\"alert\" className=\"text-kit-xs text-kit-danger-fg\">\n            {refusal}\n          </p>\n        ) : null}\n      </div>\n    );\n\n  /* V2 richtext.tsx:57: the editor sits in a plain <div>; the dash-only notes keep the 6px gap as their own margin */\n  return (\n    <div>\n      {read.losses.length ? (\n        <p role=\"status\" className=\"mb-1.5 rounded-kit-md bg-kit-warning-soft px-2.5 py-1.5 text-kit-xs text-kit-warning-fg\">\n          Saved by an earlier editor. Editing here would drop {read.losses.join(\", \")}. Nothing changes until you edit.\n        </p>\n      ) : null}\n      {read.undeclared?.length && codec.remap ? (\n        <div className=\"mb-1.5\">\n          <UnknownValueNote\n            items={read.undeclared}\n            onRemap={(key, to) => onChange(codec.remap!(value, at, key, to))}\n            onRemove={(key) => onChange(codec.remap!(value, at, key, null))}\n            readOnly={readOnly}\n          />\n        </div>\n      ) : null}\n      <RichTextEditor\n        value={html}\n        onChange={write}\n        readOnly={readOnly}\n        placeholder={field.placeholder}\n        docKey={docKey}\n        id={id}\n        invalid={invalid || !!refusal}\n        features={read.features}\n        single={read.single}\n        allowNewTab={read.newTab}\n        components={insertable && !read.single && !readOnly ? insertable : undefined}\n        variant={env.variant === \"document\" ? \"document\" : \"panel\"}\n        maxHeight={env.variant === \"document\" ? undefined : 320}\n        expandCrumbs={crumbs}\n        expandedOpen={open}\n        onExpandedOpenChange={(o) => setFullEditor(o ? docKey : null)}\n        // select words → Comment in the toolbar: the host's comment popover opens on this field, quoting them\n        onComment={env.onComment ? (quote) => env.onComment?.(path, field, quote) : undefined}\n      />\n      {refusal ? (\n        <p role=\"alert\" className=\"mt-1.5 text-kit-xs text-kit-danger-fg\">\n          {refusal}\n        </p>\n      ) : null}\n    </div>\n  );\n}\n\n/** Label-row action (at rest): the field's toolbar holds the same button while it's open. */\nfunction readsPlain(codec: KitRichTextCodec, value: unknown, field: ControlProps[\"field\"], path: ControlProps[\"path\"]) {\n  try {\n    const read = codec.read(value, { field, path });\n    return !read.losses.length && plainParagraphs(editorRoundTrip(read.html)) !== null;\n  } catch {\n    return false; // the control names the failure itself\n  }\n}\n\nexport function RichTextExpandAction({ path, field, value }: ControlProps) {\n  const env = useKitEnv();\n  const { richText } = useKitServices();\n  const handed = useHandedOff(`${env.docId}:${pathKey(path)}`);\n  const plainScope = usePlainRichText();\n  // the host's own control (no codec, or a value handed to it) has its own full-screen button\n  if (env.variant === \"document\" || !richText || handed) return null;\n  // drawn as a plain textarea (V2's `text` control has no ⤢)\n  if (plainScope && readsPlain(richText, value, field, path)) return null;\n  return (\n    <Tooltip content=\"Expand editor\" shortcut=\"⌘↵\">\n      <button\n        type=\"button\"\n        aria-label={`Expand ${field.title}`}\n        onClick={() => setFullEditor(`${env.docId}:${pathKey(path)}`)}\n        className={cn(\n          \"-my-0.5 hidden size-6 items-center justify-center rounded-kit-md text-kit-fg-3 hover:bg-kit-hover hover:text-kit-fg\",\n          \"group-hover/field:inline-flex group-focus-within/field:!hidden [@media(pointer:coarse)]:inline-flex\",\n        )}\n      >\n        <IconArrowsMaximize className=\"size-3.5\" stroke={1.5} aria-hidden />\n      </button>\n    </Tooltip>\n  );\n}\n"],"mappings":"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"}

package/dist/controls/rich-text/dom.d.ts

@@ -0,0 +1,233 @@
+/**
+ * RICH TEXT · DOM layer (V2 HEAD controls/rich-text/dom.ts). The field value is clean, semantic HTML; rich blocks are
+ * "islands" while editing.
+ *
+ * Live DOM  = the HTML, with every rich block swapped for a `div[data-rt-island="kind"]` (contenteditable=false) that
+ *             React renders into through a portal. The island's model lives on the element (`el.__rt`).
+ * Stored    = `serialize()` swaps each island back for its static HTML (`renderStatic`). The static form is the markup
+ *             production's own renderer writes for the same block, so the host's ingest reads it back as that block.
+ * Loading   = `hydrate()` turns that markup back into islands, so a re-mount restores them.
+ *
+ * Only the blocks production stores are islands here. Each one's markup is what the host's codec renders the stored
+ * block as and reads back (features/dock-v2/richTextCodec.ts); `data-extra` carries, opaque, whatever of the stored block
+ * the editor does not edit, so nothing it holds is dropped by an edit elsewhere.
+ *   image       `bcmsBlock` builtin:image: address, alt text, caption, alignment, size, link
+ *               (`<figure data-rt="image" data-align data-size><a href><img src alt></a><figcaption>`)
+ *   table       production's Portable Text table (rows of cells, a header row, header cells, and the V2 table's caption,
+ *               note, row groups and column groups), drawn with the kit's table editor (V2 TableBlock), stored as the markup
+ *               production's renderer writes (`<caption>`, `th[scope=colgroup data-group]`, a `<tbody data-key>` per row
+ *               group under a `th[scope=rowgroup]` row, `<figure data-rt="table">…<p data-notes>` for the note; footnotes
+ *               fold into the note as `[1] …`, as production's ingest folds V2's). A cell's closing
+ *               footnote markers (`<sup data-footnote>`) ride the cell as written (`marks`). A table whose cells hold
+ *               other inline formatting the table value has no place for (a term, bold) is not an island: it stays
+ *               markup in the body, edited in place, so the formatting survives.
+ *   pullquote   V2 article block (CPO D55), `<figure data-rt="pullquote">` → a `pullQuote` block.
+ *   takeaways   V2 article block (CPO D55), `<aside data-rt="takeaways"><p data-title>…<ul><li>…` → a `keyTakeaways` block
+ *               {title?, points} (written in the text itself, V2 TakeawaysEditor).
+ *   callout     `bcmsBlock` builtin:callout {tone, title, message}: `<div data-rt="callout" data-callout><p data-title>…
+ *               <div data-body><p>…` (the message is plain text: paragraphs and line breaks)
+ *   toggle      `bcmsBlock` builtin:toggle {title, body}: `<details data-rt="toggle"><summary>…<div data-body><p>…`
+ *   video       the `video` block {src, title}: `<div data-rt="video" data-url data-title>`
+ *   embed       `bcmsBlock` builtin:video {url, title} (the package's embed: `<iframe src title>` on the page), V2's
+ *               article Embed: `<figure data-rt="embed" data-url data-title><a href>…`. V2's Shape (`aspect`) has no
+ *               stored key, so it is not offered: every embed draws 16:9.
+ *   file        the `file` block {src, name, size}: `<div data-rt="file" data-url data-name data-size>`
+ *   component   `bcmsBlock` "component" {componentId, overrides, variant} (CPO D28): `<div data-rt="component" data-ref
+ *               data-id data-name data-overrides data-variant>` — a linked instance of a project component, shown as a card.
+ *               A separate copy (V2 instances.ts `detach`) adds {detached, props, blocks, sourcePublishedAt}:
+ *               `data-detached="true" data-props data-blocks data-source-published-at`, and carries no overrides.
+ * A key the stored block holds is an attribute or element that is present; a key it lacks is absent, so an untouched
+ * block reads back exactly as stored.
+ * V2's gallery, columns, footnotes, contents, related posts and author bio have no stored form in production and are
+ * not offered.
+ */
+import { type TableColumn, type TableColumnType, type TableValue } from "../../schema/table";
+export declare const esc: (s: string) => string;
+export declare const escAttr: (s: string) => string;
+export declare const rid: (p?: string) => string;
+export type ImageAlign = "full" | "center" | "left" | "right";
+export type ImageSize = "s" | "m" | "l" | "full";
+export declare const IMAGE_ALIGNS: readonly ImageAlign[];
+export declare const IMAGE_SIZES: readonly ImageSize[];
+/** Every optional key is absent when the stored block lacks it (see the header). */
+export interface ImageModel {
+    src: string;
+    /** absent only on a stored block that never had one (every new image has alt text, empty or not) */
+    alt?: string;
+    caption?: string;
+    align?: ImageAlign;
+    size?: ImageSize;
+    href?: string;
+    /** the stored block's other keys, opaque to the editor */
+    extra?: string;
+}
+/** A table island IS the kit's table value (V2 TableModel); only what production's table keeps is stored (see above). */
+export type TableModel = TableValue;
+/** V2 PullQuoteModel (article.ts). */
+export interface PullQuoteModel {
+    quote: string;
+    name: string;
+    role: string;
+    link: string;
+}
+/** V2 TakeawaysModel (article.ts): the title over the list and one plain string per point. */
+export interface TakeawaysModel {
+    title: string;
+    points: string[];
+}
+export type CalloutTone = "info" | "tip" | "warning";
+export declare const CALLOUT_TONES: readonly CalloutTone[];
+export interface CalloutModel {
+    /** the stored tone, as written (the editor offers info, tip and warning) */
+    tone?: string;
+    title?: string;
+    /** plain text: paragraphs split by a blank line, line breaks kept */
+    body?: string;
+    extra?: string;
+}
+export interface ToggleModel {
+    title?: string;
+    body?: string;
+    extra?: string;
+}
+export interface VideoModel {
+    url?: string;
+    title?: string;
+    extra?: string;
+}
+/** V2 EmbedModel (article.ts) without `aspect`, which the stored block has no key for. */
+export interface EmbedModel {
+    url?: string;
+    title?: string;
+    extra?: string;
+}
+export type EmbedProvider = "youtube" | "vimeo" | "x" | "codepen" | "figma" | "maps" | "spotify" | "podcast" | "audio" | "link";
+export interface EmbedInfo {
+    provider: EmbedProvider;
+    label: string;
+    /** frame = a sized player · post = a social post card · audio = a slim player · link = a link card */
+    shape: "frame" | "post" | "audio" | "link";
+    host: string;
+}
+export declare function detectEmbed(url: string): EmbedInfo;
+export interface FileModel {
+    url?: string;
+    name?: string;
+    size?: number;
+    extra?: string;
+}
+/** A linked instance of a project component (CPO D28): its library id, its own id, its name and its overrides. */
+export interface ComponentModel {
+    /** the component it links to (`fields.componentId`) */
+    ref?: string;
+    /** this instance (the block's key) */
+    id: string;
+    /** the component's name when it was placed (`schemaLabel`) */
+    name?: string;
+    /** the fields this instance overrides, as stored JSON */
+    overrides?: string;
+    /** the layout this instance draws the component in (V2's per-instance variant, `fields.variant`) */
+    variant?: string;
+    /** V2 `detached`: a separate copy that no longer follows the component (`fields.detached`) */
+    detached?: boolean;
+    /** a separate copy's values as readers see them, as stored JSON (V2 `props`, `fields.props`) */
+    props?: string;
+    /** a separate copy's frozen block tree, as stored JSON (`fields.blocks`); the editor never edits it */
+    blocks?: string;
+    /** the version of the component the copy was taken from (`fields.sourcePublishedAt`) */
+    sourcePublishedAt?: string;
+    extra?: string;
+}
+export interface IslandModels {
+    image: ImageModel;
+    table: TableModel;
+    pullquote: PullQuoteModel;
+    takeaways: TakeawaysModel;
+    callout: CalloutModel;
+    toggle: ToggleModel;
+    video: VideoModel;
+    embed: EmbedModel;
+    file: FileModel;
+    component: ComponentModel;
+}
+export type IslandKind = keyof IslandModels;
+export declare const ISLAND_KINDS: IslandKind[];
+export type IslandEl = HTMLElement & {
+    __rt?: IslandModels[IslandKind];
+    __rtFocus?: boolean;
+    /** the mounted island's own setter: restores a model from the editor's history (undo / redo) */
+    __rtSet?: (m: IslandModels[IslandKind]) => void;
+};
+export declare function defaultModel<K extends IslandKind>(kind: K, extra?: Partial<IslandModels[K]>): IslandModels[K];
+/** Deep copy (Duplicate). A copied table or component instance gets its own id. */
+export declare const cloneModel: <K extends IslandKind>(kind: K, m: IslandModels[K]) => IslandModels[K];
+/** "a\nb\n\nc" → `<p>a<br>b</p><p>c</p>`. Split on exactly one blank line, so any text reads back as written. */
+export declare const textToParas: (s: string) => string;
+/** The inverse of textToParas: each paragraph's text, its line breaks kept. */
+export declare function parasToText(el: Element): string;
+export declare function renderStatic(kind: IslandKind, model: unknown): string;
+/** The column types a rich-text table stores: V2's island offers these (table-editor.tsx:80-86 TYPE_UI, the non-dev ones). */
+export declare const STORED_COLUMN_TYPES: readonly TableColumnType[];
+/** A column's type and settings as stored (V2 TableColumn's keys). */
+export type ColumnSettings = Partial<Pick<TableColumn, "type" | "description" | "unit" | "currency" | "decimals" | "align" | "trueLabel" | "falseLabel" | "max">>;
+/** The settings a kit column stores: none for a plain text or link column, else its type and every setting it has. */
+export declare function columnSettings(c: TableColumn): ColumnSettings | undefined;
+/** A `<col>`'s attributes, V2 renderTableHtml's order (schema/table.ts:511-526): the column's settings, data-sortable among them. */
+export declare function colAttrs(c: ColumnSettings | undefined, sortable: boolean): string;
+/** A `<col data-type …>` read back, as V2 parseTableElement reads it; undefined without a data-type. */
+export declare function colSettingsOf(col: Element): ColumnSettings | undefined;
+export declare const isValueType: (t: TableColumnType) => boolean;
+/** V2 cellText for a typed cell: the words it says (what a stored typed cell's blocks hold). */
+export declare const typedWords: (c: ColumnSettings | undefined, type: TableColumnType, value: unknown) => string;
+/**
+ * What one cell of a typed table draws, as production's renderer writes it (the package's typedCellView, V2 cellHtml
+ * schema/table.ts:369-437 and the column header at :564): `lead` attributes before data-label / data-highlight, `tail` after,
+ * and the markup when the cell is empty or of a value type (undefined: the cell draws its own text or link).
+ */
+export declare function typedCellView(column: ColumnSettings | undefined, rowType: TableColumnType | undefined, cellType: TableColumnType | undefined, value: unknown, header: boolean, inHead: boolean): {
+    lead: string;
+    tail: string;
+    inner?: string;
+};
+/** A typed cell read back (V2 readCell): data-empty is no value; data-value a number or true / false for a value type. */
+export declare function typedValueOf(cell: Element, type: TableColumnType): number | boolean | "" | undefined;
+export declare const typeAttrOf: (el: Element) => TableColumnType | undefined;
+/**
+ * Production's table markup → the table value, cell for cell (renderStoredTable's inverse): the plain `<table>`, or
+ * the `<figure data-rt="table">` around one with its note. The V2 reader (parseTableElement) is not used here: it reads
+ * a one-column row as a row-group heading and a caption-less grid by guesses that a stored table never meant.
+ */
+export declare function parseStoredTable(src: Element): TableModel;
+/**
+ * The table as production's renderer writes a Portable Text table (@bettercms-ai/richtext html.ts tableHtml): a header
+ * row in <thead>, header cells of the first column as <th>, every cell its text (a link cell its link). A caption, a
+ * note or a group adds what that renderer writes for it, in the order the rows are held (an unedited stored table
+ * comes back as it was; the editor's row list writes V2's order, loose rows first). An empty group has no row to label
+ * and is not written, as production's renderer writes none. The totals rows are a <tfoot> after every <tbody>; a
+ * highlighted row is `<tr data-highlight="true">` and a highlighted column `data-highlight="true"` on each of its cells
+ * (production 0.10, the V2 table's markup). A sortable column is its `<col data-sortable="true">` (one `<col>` per column,
+ * inside each column group's `<colgroup>`), and "Visitors can search rows" the figure's `data-filter="true"`.
+ */
+export declare function renderStoredTable(input: TableModel): string;
+export declare function detectKind(el: Element): IslandKind | null;
+export declare function parseIsland(kind: IslandKind, el: HTMLElement): IslandModels[IslandKind];
+export declare function createIsland<K extends IslandKind>(kind: K, model: IslandModels[K]): IslandEl;
+/** Static block HTML → islands (top level only). Keeps a writable line after a trailing island or rule. */
+export declare function hydrate(root: HTMLElement): void;
+/** Live DOM → stored HTML. */
+export declare function serialize(root: HTMLElement): string;
+/** The HTML exactly as the editor would store it after opening `html` (load → hydrate → serialize), with no edit. */
+export declare function editorRoundTrip(html: string): string;
+/** Strip scripts, event handlers and script URLs from HTML we did not author (paste, Markdown, loaded values). */
+export declare function sanitize(html: string): string;
+export declare const TEXT_BLOCKS: Set<string>;
+export declare function topBlock(root: HTMLElement | null, node: Node | null): HTMLElement | null;
+/** Nearest text-ish block element around a node, inside root. */
+export declare function closestBlock(root: HTMLElement, node: Node | null): HTMLElement | null;
+export declare function placeCaret(el: Node, atEnd?: boolean): void;
+export declare function textBeforeCaret(block: HTMLElement): string | null;
+export declare function editingHost(n: Node | null): HTMLElement | null;
+/** A range's box. Browsers measure a collapsed caret as an empty rect, and some engines cannot measure ranges at all: then
+ *  the box of the element the range sits in. */
+export declare function rangeRect(r: Range, fallback: Element | null): DOMRect;
+export declare const isEmptyHtml: (html: string) => boolean;