@livepreso/react-plugin-textfield 0.6.4 → 1.0.0

package/index.js

@@ -10,9 +10,9 @@ import {
 	useFloating,
 } from "@floating-ui/react-dom";
 import {
-	useCMSVal,
+	useCanEditCMSValKey,
+	useActions,
 	useModes,
-	usePrepEditable,
 	useSlide,
 } from "@livepreso/content-react";
 import Document from "@tiptap/extension-document";
@@ -30,6 +30,10 @@ import {
 import { PrimaryToolbar } from "./components/PrimaryToolbar.js";
 import { TableToolbar } from "./components/TableToolbar.js";
 import { generateToolbarOptions } from "./configs/generate-toolbar-options.js";
+import { defineEditableSource, prop } from "@livepreso/webpack-deck";
+
+import { PERMITS } from "./permits-table.js";
+import { text } from "./text-actions.js";
 import {
 	DEFAULT_TOOLBAR_CONFIG,
 	DEFAULT_TABLE_TOOLBAR_CONFIG,
@@ -81,9 +85,17 @@ function EditableTextField({
 	const { isUserTemplateLibrary } = useSlide();
 	const [textColor, setTextColor] = useState(null);
 	const initialValue = useRef(value);
+
+	// Values handed on and not yet seen coming back. One of them arriving as
+	// `value` is a late round trip, and setting it would undo what was typed
+	// since. Focus is no guide: blurring right after typing leaves one in flight.
+	const inFlight = useRef([initialValue.current]);
+
 	const tokens = allTokens.reduce((acc, token) => {
 		const { id } = token;
-		if (acc.some((accToken) => accToken.id === id)) return acc;
+		if (acc.some((accToken) => accToken.id === id)) {
+			return acc;
+		}
 		return [...acc, token];
 	}, []);
 
@@ -178,12 +190,36 @@ function EditableTextField({
 				convertTokensToTextNodes(editor, tokenOptions);
 			}
 		},
-		onUpdate: debounce(({ editor }) => {
-			onChange?.(editor.getHTML());
-		}, 100),
+		onUpdate: ({ editor }) => {
+			const html = editor.getHTML();
+
+			inFlight.current = [...inFlight.current, html];
+			onChange?.(html);
+		},
 		parseOptions: { preserveWhitespace: true },
 	});
 
+	// Show a value set from anywhere other than this editor.
+	useEffect(() => {
+		if (!editor || editor.isDestroyed || typeof value !== "string") {
+			return;
+		}
+
+		if (inFlight.current.includes(value)) {
+			inFlight.current = inFlight.current.filter((sent) => sent !== value);
+			return;
+		}
+
+		if (value === editor.getHTML()) {
+			return;
+		}
+
+		editor.commands.setContent(value, {
+			emitUpdate: false,
+			parseOptions: { preserveWhitespace: true },
+		});
+	}, [editor, value]);
+
 	const { refs } = useFloating({
 		whileElementsMounted: autoUpdate,
 		placement: "top-start",
@@ -192,7 +228,9 @@ function EditableTextField({
 
 	useEffect(() => {
 		const preventPropagation = (event) => {
-			if (!isEditable || disableSpellcheck) return;
+			if (!isEditable || disableSpellcheck) {
+				return;
+			}
 			event.stopPropagation();
 		};
 
@@ -319,47 +357,25 @@ function EditableTextField({
 	);
 }
 
-function PrepEditableField({ id, prepId = id, children, isCompany, ...props }) {
+function PrepEditableField({ id, ...props }) {
 	const { isPresomanager } = useModes();
 	const { isUserTemplateLibrary, isUserTemplate } = useSlide();
 
-	const [defaultCmsValue] = useCMSVal(id, {
-		enabled: isCompany && !isPresomanager,
-	});
-
-	const [prepValue, setPrepValue] = usePrepEditable(prepId);
-
-	let value = isCompany && prepValue === null ? defaultCmsValue : prepValue;
-
 	const isEditable =
 		props.isEditable &&
 		(!isPresomanager || isUserTemplateLibrary || isUserTemplate);
 
 	return (
-		<EditableTextField
-			{...props}
-			value={value ?? renderToString(children)}
-			onChange={setPrepValue}
-			isEditable={isEditable}
-			mode={MODE_PREP}
-		/>
+		<EditableTextField {...props} isEditable={isEditable} mode={MODE_PREP} />
 	);
 }
 
-function CMSValField({ id, children, ...props }) {
+function CMSValField({ id, value, defaultValue, ...props }) {
 	const { isPresomanager, isThumbnailScreenshot } = useModes();
-	const { isUserTemplateLibrary, isUserTemplate, slidePath } = useSlide();
-
-	const [cmsValue, setCMSValue] = useCMSVal(id);
-	const value = !isThumbnailScreenshot && cmsValue;
+	const { isUserTemplateLibrary, isUserTemplate } = useSlide();
 
-	// Check if the app allows editing this field. If the function doesn't exist
-	// assume it's ok. Pass calling slide's slidePath so the key resolves against
-	// this slide rather than presenter's current slide.
-	const userCanEdit =
-		isUserTemplate ||
-		isUserTemplateLibrary ||
-		(Bridge.CMSVals?.canEditKey?.(id, { slidePath }) ?? true);
+	const canEditKey = useCanEditCMSValKey(id);
+	const userCanEdit = isUserTemplate || isUserTemplateLibrary || canEditKey;
 
 	const isEditable =
 		props.isEditable &&
@@ -369,8 +385,9 @@ function CMSValField({ id, children, ...props }) {
 	return (
 		<EditableTextField
 			{...props}
-			value={value ?? renderToString(children)}
-			onChange={setCMSValue}
+			// A thumbnail shows the copy the usage wrote rather than the stored
+			// value, so a slide looks the same in every tenancy's picker.
+			value={isThumbnailScreenshot ? defaultValue : value}
 			isEditable={isEditable}
 			mode={MODE_CMS}
 		/>
@@ -391,41 +408,111 @@ export function TextField(props) {
 	);
 }
 
+/** How long a run of keystrokes settles for before the value is stored. */
+const SETTLE_MS = 100;
+
+/**
+ * Sends the value to the store once a run of keystrokes stops.
+ *
+ * The field shows every keystroke regardless, and only the write waits. A
+ * mutation carries the whole value rather than a change, so the one that lands
+ * says everything the skipped ones would have.
+ */
+function useDebouncedSet(mutations) {
+	const store = useRef(mutations.set);
+
+	store.current = mutations.set;
+
+	return useMemo(
+		() => debounce((html) => store.current({ html }), SETTLE_MS),
+		[],
+	);
+}
+
 export function ManagedTextField(props) {
-	const { isPresomanager, isPreview, isEmptyPreview } = useModes();
-	const { isUserTemplateLibrary } = useSlide();
+	const { isPresomanager, isPreview, isReadOnly: isPageReadOnly } = useModes();
 	const {
+		id,
+		children,
 		isReadOnly = false,
 		isPrep = false,
 		isCompany = false,
-		// we only want to pass this to the PrepEditableField, not the CMSValField
+		// Kept out of `other`, which is spread onto the element. The declaration
+		// reads these off `props` directly.
 		prepId,
+		scope,
 		...other
 	} = props;
 
-	const isEditable = !isReadOnly && (isPresomanager || isPreview);
-	const sharedProps = { ...other, isEditable };
-
 	// occasionally, we want to lock the field and pass a value
 	// without it ever being configured to allow updates
 	if (!isReadOnly && !isPrep && !isCompany) {
 		throw new Error("Must set isPrep or isCompany or both");
 	}
 
-	const isReallyPresoManager = isPresomanager && !isUserTemplateLibrary;
+	const defaultValue = renderToString(children);
 
-	if (
-		(isPrep && !isReallyPresoManager && !isEmptyPreview) ||
-		(isPrep && isReallyPresoManager && !isCompany)
-	) {
+	const { channel, queries, mutations } = useActions(editable, props, {
+		defaultValue,
+	});
+
+	const sharedProps = {
+		...other,
+		value: queries.get(),
+		// The debounce sits here because this component stores the value, so it
+		// decides how often the store hears about it.
+		onChange: useDebouncedSet(mutations),
+		// Two read-only checks: this field, and the page the host says stores
+		// nothing.
+		isEditable: !isReadOnly && !isPageReadOnly && (isPresomanager || isPreview),
+	};
+
+	return (
+		<ManagedField
+			id={id}
+			channel={channel}
+			defaultValue={defaultValue}
+			{...sharedProps}
+		/>
+	);
+}
+
+function ManagedField({ id, channel, defaultValue, ...props }) {
+	// The channel arrives once the presenter has read the deck's index. Picking a
+	// field kind before then asks the wrong store about this key.
+	if (!channel) {
 		return (
-			<PrepEditableField
-				isCompany={isCompany}
-				prepId={prepId}
-				{...sharedProps}
-			/>
+			<EditableTextField {...props} isEditable={false} mode={MODE_UNMANAGED} />
 		);
 	}
 
-	return <CMSValField {...sharedProps} />;
+	if (channel === "personal") {
+		return <PrepEditableField id={id} {...props} />;
+	}
+
+	return <CMSValField id={id} defaultValue={defaultValue} {...props} />;
 }
+
+// ManagedTextField renders no marker attribute and stores through
+// Bridge.CMSVals, so the build finds no `data-toolbar` and would call a field
+// that takes headings and lists plain text. The actions say what these fields
+// permit instead, named in the toolbar groups this plugin's permits table lists.
+const editable = defineEditableSource(ManagedTextField, {
+	actions: text,
+	props: {
+		toolbar: prop("toolbarConfig", { default: DEFAULT_TOOLBAR_CONFIG }),
+		permits: prop("permits", { default: PERMITS }),
+		tag: prop("tag", { default: null }),
+	},
+	everyone: {
+		when: prop("isCompany"),
+		key: "{id}-{instance}",
+		scope: prop("scope", { default: "instance" }),
+	},
+	personal: {
+		when: prop("isPrep"),
+		id: prop("prepId"),
+		key: "{id}-{instance}",
+		scope: prop("scope", { default: "instance" }),
+	},
+});

package/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+	testEnvironment: "node",
+	moduleNameMapper: {
+		// Jest reads a stylesheet as JavaScript, and a component importing one
+		// throws before the test reaches it.
+		"\\.(scss|css)$": "<rootDir>/test/style-stub.js",
+	},
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livepreso/react-plugin-textfield",
-  "version": "0.6.4",
+  "version": "1.0.0",
   "description": "",
   "main": "index.js",
   "publishConfig": {
@@ -16,6 +16,10 @@
     "react-dom": "~19.2.0",
     "@babel/parser": "^7.26.10",
     "@babel/traverse": "^7.26.10",
+    "@babel/core": "~7.26.0",
+    "@babel/preset-env": "^7.14.9",
+    "babel-jest": "~29.7.0",
+    "jest": "~29.7.0",
     "@livepreso/eslint-config": "1.0.0"
   },
   "peerDependencies": {
@@ -57,10 +61,12 @@
     "@tiptap/extension-mention": "~3.31.0",
     "@tiptap/suggestion": "~3.31.0",
     "fuse.js": "~7.1.0",
-    "@livepreso/content-react": "2.3.1",
-    "@livepreso/react-plugin-ui": "1.1.2"
+    "@livepreso/content-react": "3.0.0",
+    "@livepreso/webpack-deck": "4.0.0",
+    "@livepreso/react-plugin-ui": "2.0.0"
   },
   "scripts": {
-    "build": ""
+    "build": "",
+    "test": "jest --maxWorkers=2 --workerIdleMemoryLimit=512MB"
   }
 }

package/permits-table.js

@@ -0,0 +1,59 @@
+/**
+ * What each toolbar group lets a person put in a field, as the markup it comes
+ * out as.
+ *
+ * Data only, importing nothing, because a target's interface module reaches
+ * this through the declaration and is loaded for slides a reader never opens.
+ *
+ * The keys are the toolbar group names from `constants.js`, written out, since
+ * they are the strings a deck already types in its own `toolbarConfig`.
+ *
+ * A null group adds no markup at all.
+ *
+ * Keep this beside the `extensions` each item lists in
+ * `configs/toolbar-configuration.js`, which are what decide the markup.
+ */
+export const PERMITS = Object.freeze({
+	"text-style": {
+		tags: ["strong", "em", "u", "s", "sup", "sub", "span"],
+		attributes: ["style"],
+		coloursFromPalette: true,
+	},
+
+	block: {
+		tags: ["h1", "h2", "h3", "h4", "h5", "h6"],
+	},
+
+	list: {
+		tags: ["ul", "ol", "li"],
+	},
+
+	link: {
+		tags: ["a"],
+		attributes: ["href", "target", "rel", "title"],
+	},
+
+	alignment: {
+		attributes: ["style"],
+		align: ["left", "center", "right", "justify"],
+	},
+
+	table: {
+		tags: ["table", "thead", "tbody", "colgroup", "col", "th", "tr", "td"],
+		attributes: ["colspan", "rowspan", "colwidth", "style", "class"],
+		styles: ["width"],
+	},
+
+	// A token renders through a node view rather than a renderHTML, so what is
+	// stored is the span that view built.
+	token: {
+		tags: ["span"],
+		attributes: ["id", "label", "class", "contenteditable"],
+	},
+
+	undo: null,
+	"clear-formatting": null,
+});
+
+/** Every field keeps these, whatever its toolbar permits. */
+export const ALWAYS_PERMITTED = Object.freeze(["p", "br"]);

package/test/style-stub.js

@@ -0,0 +1 @@
+module.exports = {};

package/text-actions.js

@@ -0,0 +1,147 @@
+import {
+	defineActions,
+	defineRule,
+	findNotPermitted,
+	listPermitted,
+} from "@livepreso/webpack-deck";
+
+import { ALWAYS_PERMITTED } from "./permits-table.js";
+
+/**
+ * What a field with this toolbar permits, as one table the description and the
+ * check both read.
+ *
+ * A toolbar carrying a group this table does not list answers null, which stands
+ * for an unanswered field. A caller reading that as "permits nothing" would
+ * refuse writes the field takes every day.
+ */
+function derivePermits(toolbar, permits, tag) {
+	if (!Array.isArray(toolbar) || toolbar.some((group) => !(group in permits))) {
+		return null;
+	}
+
+	const groups = toolbar.map((group) => permits[group]).filter(Boolean);
+	const tags = [
+		...ALWAYS_PERMITTED,
+		...groups.flatMap((group) => group.tags ?? []),
+	];
+
+	// The editor wraps every value in the field's tag, so `<h4>` is stored even
+	// where the toolbar offers no headings.
+	if (tag) {
+		tags.push(tag);
+	}
+
+	return {
+		tags: [...new Set(tags)],
+		attributes: [...new Set(groups.flatMap((group) => group.attributes ?? []))],
+		styles: [...new Set(groups.flatMap((group) => group.styles ?? []))],
+		// A palette narrows which colours may be written, and a deck without one
+		// leaves them unchecked rather than refusing every colour.
+		colours: null,
+		align: groups.find((group) => group.align)?.align ?? null,
+	};
+}
+
+/** What kind of field this is, which a caller reading one wants as much as one writing. */
+function describeKind(toolbar, permits) {
+	if (!derivePermits(toolbar, permits)) {
+		return "Text. What formatting it takes is not known here, so nothing is refused on that ground.";
+	}
+
+	return "Rich text, stored as HTML.";
+}
+
+/**
+ * The markup a value may use, which only something writing one needs. It rides
+ * on the rule rather than the declaration, so it reaches `set` and not `get`.
+ *
+ * Named as tags rather than described as formatting, because whatever is driving
+ * the deck writes HTML and would otherwise have to translate "headings" into
+ * `<h1>` for itself.
+ */
+function describeMarkup(toolbar, permits, tag) {
+	const derived = derivePermits(toolbar, permits, tag);
+
+	if (!derived) {
+		return "Nothing is refused, since what this field takes is not known here.";
+	}
+
+	const written = [`Allowed tags: ${derived.tags.join(", ")}.`];
+
+	if (derived.attributes.length > 0) {
+		written.push(`Allowed attributes: ${derived.attributes.join(", ")}.`);
+	}
+
+	return written.join(" ");
+}
+
+/**
+ * Answers for what a managed text field holds and what may be written into it.
+ *
+ * `permits` is the extension point: a deck adding a tiptap extension widens the
+ * table through the prop rather than copying this declaration, and the description
+ * widens with it because it is a function of props.
+ */
+export const text = defineActions({
+	// Only where a usage wrote no copy between its tags. Where it did, the build
+	// reads that and the binding starts the field with it instead.
+	defaultState: "",
+
+	// Stores HTML in a text/plain slot, deliberately: it is how a decade of
+	// data-editable content is already stored, so an existing field becomes a
+	// rich text field without moving any of it. The cost is that it can never
+	// carry a version.
+	mime: "text/plain",
+
+	description: (props) => describeKind(props.toolbar, props.permits),
+
+	rules: {
+		"not-permitted": defineRule({
+			description: (props) =>
+				describeMarkup(props.toolbar, props.permits, props.tag),
+			check: ({ state, props }) => {
+				const permits = derivePermits(props.toolbar, props.permits, props.tag);
+
+				// A toolbar this table cannot read permits everything rather than
+				// nothing. The editor still enforces the real one, so refusing here
+				// would block writes the field takes every day.
+				if (!permits) {
+					return true;
+				}
+
+				const refused = findNotPermitted(state, permits);
+
+				if (refused.length === 0) {
+					return true;
+				}
+
+				return {
+					message: `The value uses ${refused.join(", ")}. ${listPermitted(permits)}`,
+					notPermitted: refused,
+					permits,
+				};
+			},
+		}),
+	},
+
+	queries: {
+		/**
+		 * What this field currently holds.
+		 *
+		 * @returns {string}   the text, as HTML
+		 */
+		get: ({ state }) => state,
+	},
+
+	mutations: {
+		/**
+		 * Replace the text.
+		 *
+		 * @param {object} args
+		 * @param {object} args.input
+		 * @param {string} args.input.html   the new text, as HTML
+		 */
+		set: ({ input }) => input.html,
+	},
+});

package/text-actions.spec.js

@@ -0,0 +1,37 @@
+import { text } from "./text-actions.js";
+import { PERMITS } from "./permits-table.js";
+
+function checkPermitted(state, props) {
+	return text.rules["not-permitted"].check({
+		state,
+		props: { toolbar: ["text-style"], permits: PERMITS, ...props },
+	});
+}
+
+describe("text", () => {
+	it("should permit the heading its tag draws", () => {
+		expect(
+			checkPermitted("<h4>Due <strong>soon</strong></h4>", { tag: "h4" }),
+		).toBe(true);
+	});
+
+	it("should permit the table its toolbar draws", () => {
+		const table = `<table data-density="normal" class="tiptap-table-density-normal" style="width: 600px;">`;
+		const column = `<colgroup><col style="width: 300px;"></colgroup>`;
+		const stored = `${table}${column}<tbody><tr><th colwidth="300"><p>Due</p></th></tr></tbody></table>`;
+
+		expect(
+			checkPermitted(stored, { toolbar: ["text-style", "table", "token"] }),
+		).toBe(true);
+	});
+
+	it("should permit the span a chosen token stores", () => {
+		const attributes = `id="date" label="Date" data-mention-suggestion-char="@"`;
+		const rest = `data-mode="cms" class="token" contenteditable="false"`;
+		const stored = `<h1><span ${attributes} ${rest}>@Date</span></h1>`;
+
+		expect(
+			checkPermitted(stored, { tag: "h1", toolbar: ["text-style", "token"] }),
+		).toBe(true);
+	});
+});

package/utils/generate-border-icon.js

@@ -7,8 +7,12 @@ import style from "../index.module.scss";
 export function generateBorderIcon(editor) {
 	const sides = getCellBorderSides(editor);
 
-	if (sides.length === BORDER_SIDES.length) return <icons.BorderOuter />;
-	if (sides.length === 0) return <icons.BorderClear />;
+	if (sides.length === BORDER_SIDES.length) {
+		return <icons.BorderOuter />;
+	}
+	if (sides.length === 0) {
+		return <icons.BorderClear />;
+	}
 
 	return (
 		<div className={style.borderIconContainer}>