@livepreso/content-react 2.3.1 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,20 @@
 # Change Log - @livepreso/content-react
 
-This log was last generated on Thu, 17 Sep 2026 01:30:15 GMT and should not be manually modified.
+This log was last generated on Tue, 03 Nov 2026 22:02:25 GMT and should not be manually modified.
+
+## 3.0.0
+Tue, 03 Nov 2026 22:02:25 GMT
+
+### Breaking changes
+
+- Editable reads and writes go through the deck interface. Requires a deck built with webpack-deck 4.
+
+### Minor changes
+
+- Adds useActions for calling a deck's actions from a component, and useTargetKey for the key a component renders under.
+- usePrepEditable supports a field edited on the everyone channel.
+- A template placement is read-only while previewing.
+- useActions registers its field with the host when the component mounts, and releases it when it unmounts.
 
 ## 2.3.1
 Thu, 17 Sep 2026 01:30:15 GMT

package/babel.config.js

@@ -0,0 +1,8 @@
+// Only the test run uses this. A deck's build resolves its babel config from
+// its own root, so nothing here reaches the bundle.
+module.exports = {
+	presets: [
+		["@babel/preset-env", { targets: { node: "current" } }],
+		["@babel/preset-react", { runtime: "automatic" }],
+	],
+};

package/jest.config.js

@@ -0,0 +1,11 @@
+// No jsdom and no renderer: the hooks under test hold no state of their own, so
+// a spec calls them directly with the context hook they read stubbed out. A
+// hook that later needs `useState` or `useMemo` will throw when called this
+// way, which is the point at which one is worth setting up.
+module.exports = {
+	testEnvironment: "node",
+	moduleNameMapper: {
+		// A deck's build resolves this to the project file it was built from.
+		"^@project$": "<rootDir>/test/project.json",
+	},
+};

package/lib/components/OverlayPortal.js

@@ -6,5 +6,9 @@ export function OverlayPortal({ children }) {
 	if ((!entered && !exiting) || exited) {
 		return;
 	}
-	return createPortal(children, window.Bridge.UI.overlay);
+	const overlay = window.Bridge.UI.overlay;
+	if (!overlay) {
+		return;
+	}
+	return createPortal(children, overlay);
 }

package/lib/hooks/cmsvals.js

@@ -54,6 +54,24 @@ function useDefaultCMSValueFromPresomanager(id, { slidePath = null } = {}) {
 	return cmsVals?.find?.((c) => c.key === key)?.value ?? null;
 }
 
+function isShowing(presentationKey) {
+	return Bridge.presenter.getPresentation().current?.key === presentationKey;
+}
+
+/**
+ * Whether the app allows this field to be edited.
+ *
+ * True where nothing says otherwise, so a deck older than the check keeps
+ * working.
+ */
+export function useCanEditCMSValKey(id) {
+	const { slidePath } = useSlide();
+
+	// Neighbouring slides are mounted too, so the key resolves against this slide
+	// rather than whichever one the presenter is showing.
+	return Bridge.CMSVals?.canEditKey?.(id, { slidePath }) ?? true;
+}
+
 export function useCMSVal(
 	id,
 	{ enabled = true, slidePath: slidePathOverride = null } = {},
@@ -64,10 +82,11 @@ export function useCMSVal(
 	const {
 		isUserTemplate,
 		isUserTemplateLibrary,
+		presentationKey,
 		slidePath: ownSlidePath,
 	} = useSlide();
 
-	// Defaults to the calling slide's path.
+	// A caller that passes no path gets the path of the slide it renders in.
 	const slidePath = slidePathOverride ?? ownSlidePath;
 	const [userTemplateValue, setUserTemplateValue] = useUserTemplateCMS(id);
 	const defaultFromPM = useDefaultCMSValueFromPresomanager(id, { slidePath });
@@ -95,6 +114,12 @@ export function useCMSVal(
 			return defaultFromPM;
 		}
 
+		// Neighbouring slides are mounted too, and the presenter resolves a key
+		// against the slide that is showing.
+		if (!slidePath && !isShowing(presentationKey)) {
+			return undefined;
+		}
+
 		return Bridge.CMSVals.get(id, { slidePath });
 	}, [
 		enabled,
@@ -102,11 +127,14 @@ export function useCMSVal(
 		defaultFromPM,
 		isUserTemplate,
 		isUserTemplateLibrary,
+		userTemplateValue,
 		isActiveSlide,
 		isPresomanager,
+		// Read off the article, so it can arrive after the first render.
+		presentationKey,
 	]);
 
-	const [value, setCMSValue] = useState(getCmsVal());
+	const [value, setCMSValue] = useState(getCmsVal);
 
 	function updateCMSVal(value) {
 		if (isUserTemplate) {
@@ -114,15 +142,28 @@ export function useCMSVal(
 		} else {
 			Bridge.CMSVals.set(id, value, { slidePath });
 		}
-		setCMSValue(value);
 	}
 
+	useEffect(() => {
+		const stored = getCmsVal();
+
+		// undefined means the value cannot be read from here, so a slide part
+		// way out of view keeps what it had instead of blanking.
+		if (stored !== undefined) {
+			setCMSValue(stored);
+		}
+	}, [getCmsVal]);
+
 	useEffect(() => {
 		if (!enabled || !isActiveSlide) {
 			return;
 		}
 
 		function onCMSValChanged(key, newValue) {
+			if (!slidePath && !isShowing(presentationKey)) {
+				return;
+			}
+
 			const fullKey = Bridge.CMSVals.getFullKey(id, { slidePath });
 
 			if (key !== fullKey) {
@@ -132,10 +173,10 @@ export function useCMSVal(
 			setCMSValue(newValue);
 		}
 
-		Bridge.presenter.getPresentation().on("cmsValChanged", onCMSValChanged);
+		Bridge.CMSVals.on("changed", onCMSValChanged);
 
 		return () => {
-			Bridge.presenter.getPresentation().off("cmsValChanged", onCMSValChanged);
+			Bridge.CMSVals.off("changed", onCMSValChanged);
 		};
 	}, [enabled, id, getCmsVal]);
 

package/lib/hooks/cmsvals.spec.js

@@ -0,0 +1,87 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { act, renderHook } from "@testing-library/react";
+
+import { useCMSVal } from "./cmsvals.js";
+import { useModes } from "./use-modes.js";
+import { useSlide, useSlideModel } from "./slide.js";
+import { useSlideContext } from "./use-slide-context.js";
+import { useTransitions } from "./use-transitions";
+
+jest.mock("./use-modes.js", () => ({ useModes: jest.fn() }));
+jest.mock("./slide.js", () => ({
+	useSlide: jest.fn(),
+	useSlideModel: jest.fn(),
+}));
+jest.mock("./use-slide-context.js", () => ({ useSlideContext: jest.fn() }));
+jest.mock("./use-transitions", () => ({ useTransitions: jest.fn() }));
+
+function stub({ showing = "a-preso", stored = null } = {}) {
+	const listeners = new Set();
+	let current = showing ? { key: showing } : null;
+
+	const presentation = {
+		on: (name, listener) => listeners.add(listener),
+		off: (name, listener) => listeners.delete(listener),
+		get current() {
+			return current;
+		},
+	};
+
+	global.Bridge = {
+		CMSVals: {
+			get: jest.fn(() => stored),
+			set: jest.fn(),
+			getFullKey: (id) => `stored-${id}`,
+			on: (name, listener) => listeners.add(listener),
+			off: (name, listener) => listeners.delete(listener),
+		},
+		presenter: { getPresentation: () => presentation },
+	};
+
+	useTransitions.mockReturnValue({ entered: true, entering: false });
+	useModes.mockReturnValue({ isCdk: true });
+	useSlideModel.mockReturnValue(null);
+	useSlideContext.mockReturnValue([null, jest.fn()]);
+	useSlide.mockReturnValue({ presentationKey: showing });
+
+	return {
+		report: (key, value) => {
+			for (const listener of listeners) {
+				listener(key, value);
+			}
+		},
+	};
+}
+
+describe("useCMSVal", () => {
+	it("should read again once the slide it is on says which one it is", () => {
+		stub({ showing: "a-preso", stored: "what the store holds" });
+		useSlide.mockReturnValue({ presentationKey: null });
+
+		const { result, rerender } = renderHook(() => useCMSVal("a-note"));
+
+		expect(result.current[0]).toBeUndefined();
+
+		useSlide.mockReturnValue({ presentationKey: "a-preso" });
+		rerender();
+
+		expect(result.current[0]).toBe("what the store holds");
+	});
+
+	it("should show what the store reported rather than what was written", () => {
+		const { report } = stub({ stored: "what the store holds" });
+
+		const { result } = renderHook(() => useCMSVal("a-note"));
+
+		act(() => result.current[1]("typed"));
+
+		expect(result.current[0]).toBe("what the store holds");
+
+		act(() => report("stored-a-note", "what the store kept"));
+
+		expect(result.current[0]).toBe("what the store kept");
+	});
+});

package/lib/hooks/cwe-editable.js

@@ -45,16 +45,18 @@ export function useCWEEditableInfo(id) {
 	}
 
 	useEffect(() => {
-		if (isPresomanager) return;
+		if (isPresomanager) {
+			return;
+		}
 
 		function onContextChange() {
 			updateValue();
 		}
 
-		Bridge.presenter.getPresentation().on("change:context", onContextChange);
+		Bridge.Context.on("changed", onContextChange);
 
 		return () => {
-			Bridge.presenter.getPresentation().off("change:context", onContextChange);
+			Bridge.Context.off("changed", onContextChange);
 		};
 	}, [isPresomanager, value, getValue]);
 

package/lib/hooks/index.js

@@ -9,6 +9,7 @@ export { useTransitions } from "./use-transitions.js";
 export { useSubslides } from "./use-subslides.js";
 export { useSlideDone } from "./use-slide-done.js";
 export { useEditableFieldKey } from "./use-editable-field-key.js";
+export { useTargetKey } from "./use-target-key.js";
 export { useEditableInitialState } from "./use-editable-initial-state.js";
 export {
 	usePrepEditable,
@@ -17,4 +18,5 @@ export {
 	usePrepEditableImage,
 } from "./prep-editable.js";
 export { useCWEEditableInfo, useCWEEditableValue } from "./cwe-editable.js";
-export { useCMSVal } from "./cmsvals.js";
+export { useCMSVal, useCanEditCMSValKey } from "./cmsvals.js";
+export { useActions } from "./use-actions.js";

package/lib/hooks/prep-editable.js

@@ -9,13 +9,14 @@ import { useEditableFieldKey } from "./use-editable-field-key";
  * of the context to allow the user template magic to work, and this is the
  * function to use to make that seamless.
  */
-export function usePrepEditable(editableKey) {
-	const { isPresomanager } = useModes();
+export function usePrepEditable(editableKey, { isGlobal = false } = {}) {
+	const { isPresomanager, isReadOnly: isPageReadOnly } = useModes();
 	const { slideID, isUserTemplateLibrary } = useSlide();
 
 	const key = useEditableFieldKey(editableKey, { isPrep: true });
 
-	const prepKey = `${slideID}--${key}`;
+	// Not owned by a slide, so every slide using this key sees one value.
+	const prepKey = isGlobal ? key : `${slideID}--${key}`;
 	const keyPath = `_editableContent.${prepKey}`;
 
 	const [obj, setObj] = useSlideContext(
@@ -25,7 +26,7 @@ export function usePrepEditable(editableKey) {
 			value: null,
 		},
 		{
-			enabled: !isPresomanager || isUserTemplateLibrary,
+			enabled: !isPageReadOnly && (!isPresomanager || isUserTemplateLibrary),
 		},
 	);
 
@@ -70,7 +71,7 @@ export function usePrepEditableValue(id, defaultValue = null) {
  * Returns the URL of a prep editable dynamic image on the current slide.
  */
 export function usePrepEditableImage(editableKey) {
-	const { isPresomanager } = useModes();
+	const { isPresomanager, isReadOnly: isPageReadOnly } = useModes();
 	const { slideID, isUserTemplateLibrary } = useSlide();
 
 	const key = useEditableFieldKey(editableKey, { isPrep: true });
@@ -82,7 +83,7 @@ export function usePrepEditableImage(editableKey) {
 		keyPath,
 		{ image: null },
 		{
-			enabled: !isPresomanager || isUserTemplateLibrary,
+			enabled: !isPageReadOnly && (!isPresomanager || isUserTemplateLibrary),
 		},
 	);
 

package/lib/hooks/prep-editable.spec.js

@@ -0,0 +1,78 @@
+import { useModes } from "./use-modes.js";
+import { usePrepEditable } from "./prep-editable.js";
+import { useSlide } from "./slide.js";
+import { useSlideContext } from "./use-slide-context.js";
+
+jest.mock("./use-modes.js", () => ({ useModes: jest.fn() }));
+jest.mock("./slide.js", () => ({ useSlide: jest.fn() }));
+jest.mock("./use-slide-context.js", () => ({ useSlideContext: jest.fn() }));
+
+function stub() {
+	useModes.mockReturnValue({ isPresomanager: false });
+	useSlide.mockReturnValue({
+		slideID: "opening",
+		isPMTemplate: false,
+		isUserTemplate: false,
+		isUserTemplateLibrary: false,
+	});
+	useSlideContext.mockReturnValue([{ value: "Stored" }, jest.fn()]);
+}
+
+describe("usePrepEditable", () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+		stub();
+	});
+
+	it("should keep a value against the slide it was written on", () => {
+		usePrepEditable("note");
+
+		expect(useSlideContext).toHaveBeenCalledWith(
+			"_editableContent.opening--note",
+			expect.anything(),
+			expect.anything(),
+		);
+	});
+
+	it("should offer a prep editable on a user template being edited", () => {
+		useModes.mockReturnValue({ isPresomanager: true, isReadOnly: false });
+		useSlide.mockReturnValue({
+			slideID: "opening",
+			isUserTemplateLibrary: true,
+		});
+
+		usePrepEditable("note");
+
+		expect(useSlideContext).toHaveBeenCalledWith(
+			expect.anything(),
+			expect.anything(),
+			{ enabled: true },
+		);
+	});
+
+	it("should offer none on a template preview that stores nothing", () => {
+		useModes.mockReturnValue({ isPresomanager: true, isReadOnly: true });
+		useSlide.mockReturnValue({
+			slideID: "opening",
+			isUserTemplateLibrary: true,
+		});
+
+		usePrepEditable("note");
+
+		expect(useSlideContext).toHaveBeenCalledWith(
+			expect.anything(),
+			expect.anything(),
+			{ enabled: false },
+		);
+	});
+
+	it("should keep a global value under its bare key", () => {
+		usePrepEditable("note", { isGlobal: true });
+
+		expect(useSlideContext).toHaveBeenCalledWith(
+			"_editableContent.note",
+			expect.anything(),
+			expect.anything(),
+		);
+	});
+});

package/lib/hooks/slide.js

@@ -6,8 +6,8 @@ export function useSlide() {
 	const {
 		slideID,
 		slideKey,
-		presentationKey,
 		slidePath,
+		presentationKey,
 		isSlideReady,
 		doneRegister,
 		isCurrentSlide,
@@ -22,8 +22,8 @@ export function useSlide() {
 	return {
 		slideID,
 		slideKey,
-		presentationKey,
 		slidePath,
+		presentationKey,
 		isSlideReady,
 		doneRegister,
 		isCurrentSlide,

package/lib/hooks/use-actions.js

@@ -0,0 +1,112 @@
+import { useEffect, useMemo, useReducer } from "react";
+import { bindActions, provideRendered } from "@livepreso/webpack-deck";
+
+import { useSlide } from "./slide.js";
+import { useTargetKey } from "./use-target-key.js";
+
+/**
+ * The queries and mutations this editable declares, bound to
+ * wherever it is stored.
+ *
+ * ```
+ *   const { queries, mutations } = useActions(editable, props);
+ *
+ *   value={queries.get()}       onChange={(html) => mutations.set({ html })}
+ *   await queries.getAsync()    await mutations.set({ html })
+ * ```
+ *
+ * A person editing the content reaches the mutation an assistant calls, which
+ * is why a component is never handed a plain setter.
+ */
+export function useActions(
+	source,
+	args,
+	{ defaultValue = null, field, rendered, onValidationError } = {},
+) {
+	const { slidePath } = useSlide();
+	const targetKey = useTargetKey();
+
+	const bound = useMemo(
+		() =>
+			bindActions(source, args, {
+				targetKey,
+				slidePath,
+				defaultValue,
+				field,
+				isRegistered: false,
+			}),
+		// The declaration and the args are the same objects every render, and the
+		// binding reads its stores on every call, so only where it stores can
+		// change under it.
+		[targetKey, slidePath],
+	);
+
+	useRendered(bound.key, rendered);
+
+	// Lists a field the build missed while it is on screen, so it can be edited.
+	useEffect(() => bound.register(), [bound]);
+
+	const [, render] = useReducer((count) => count + 1, 0);
+
+	useEffect(() => {
+		bound.on("changed", render);
+
+		return () => bound.off("changed", render);
+	}, [bound]);
+
+	useEffect(() => {
+		if (!onValidationError) {
+			return undefined;
+		}
+
+		bound.on("validation-error", onValidationError);
+
+		return () => bound.off("validation-error", onValidationError);
+	}, [bound, onValidationError]);
+
+	return {
+		channel: bound.channel,
+		errors: bound.errors,
+		queries: bound.queries,
+		mutations: bound.mutations,
+	};
+}
+
+/**
+ * Holds what a field has while it is on screen, for the entries that name it.
+ *
+ * The nodes are read on every render because a ref is filled after the render
+ * that created it, so reading during one would hold null.
+ */
+function useRendered(fieldKey, refs) {
+	const names = Object.keys(refs ?? {});
+
+	useEffect(() => {
+		if (names.length === 0) {
+			return undefined;
+		}
+
+		return provideRendered(
+			fieldKey,
+			Object.fromEntries(
+				names.map((name) => [name, readRenderedValue(refs[name])]),
+			),
+		);
+	});
+}
+
+/**
+ * A ref gives its element. A flag such as `always: true` passes through, so an entry can
+ * require the slide on screen.
+ */
+function readRenderedValue(value) {
+	if (isRef(value)) {
+		return value.current;
+	}
+
+	return value;
+}
+
+function isRef(value) {
+	return typeof value === "object" && value !== null && "current" in value;
+}

package/lib/hooks/use-actions.spec.js

@@ -0,0 +1,150 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import { act, renderHook } from "@testing-library/react";
+import {
+	defineEditableSource,
+	defineActions,
+	prop,
+} from "@livepreso/webpack-deck";
+
+import { useActions } from "./use-actions.js";
+import { useSlide } from "./slide.js";
+import { useTargetKey } from "./use-target-key.js";
+
+jest.mock("./slide.js", () => ({ useSlide: jest.fn() }));
+jest.mock("./use-target-key.js", () => ({ useTargetKey: jest.fn() }));
+
+function Field() {}
+
+function aNoteField() {
+	return defineEditableSource(Field, {
+		fields: { id: prop("name") },
+		actions: defineActions({
+			defaultState: "",
+			mime: "text/plain",
+			description: "A note.",
+			queries: { get: ({ state }) => state },
+			mutations: { set: ({ input }) => input.text.trim() },
+		}),
+		everyone: { when: prop("isCompany"), key: "{targetKey}-{id}" },
+	});
+}
+
+function stub({
+	state = null,
+	channel = "everyone",
+	applyResult = { errors: {} },
+} = {}) {
+	const listeners = new Set();
+
+	const versionOne = {
+		read: jest.fn().mockReturnValue({ state, channel, provided: {} }),
+		apply: jest.fn().mockResolvedValue(applyResult),
+		on: (name, listener) => listeners.add(listener),
+		off: (name, listener) => listeners.delete(listener),
+	};
+
+	global.Bridge = { Interface: { open: () => versionOne } };
+
+	useTargetKey.mockReturnValue("a-target");
+	useSlide.mockReturnValue({ slidePath: "a-deck/a-section/a-target" });
+
+	return {
+		versionOne,
+		raiseChanged: (changed) => {
+			for (const listener of listeners) {
+				listener(changed);
+			}
+		},
+	};
+}
+
+function aDrawnField() {
+	return defineEditableSource(Field, {
+		fields: { id: prop("name") },
+		actions: defineActions({
+			queries: { readDrawn: ({ rendered }) => rendered.drawn },
+		}),
+		everyone: { key: "{targetKey}-{id}" },
+	});
+}
+
+function renderField(options) {
+	return renderHook(() =>
+		useActions(aNoteField(), { name: "a-field", isCompany: true }, options),
+	);
+}
+
+describe("useActions", () => {
+	it("should give back what the binding reads", () => {
+		stub({ state: "Stored" });
+
+		expect(renderField().result.current.queries.get()).toBe("Stored");
+	});
+
+	it("should say which channel the field stores on", () => {
+		stub({ channel: "personal" });
+
+		expect(renderField().result.current.channel).toBe("personal");
+	});
+
+	it("should read the channel fresh once the presenter has answered it", () => {
+		const { raiseChanged, versionOne } = stub({ channel: null });
+		const field = renderField();
+
+		// While the presenter reports no channel, the field takes the declared one.
+		expect(field.result.current.channel).toBe("everyone");
+
+		versionOne.read.mockReturnValue({
+			state: "Stored",
+			channel: "personal",
+			provided: {},
+		});
+		act(() =>
+			raiseChanged({
+				slidePath: "a-deck/a-section/a-target",
+				field: "a-target-a-field",
+			}),
+		);
+
+		expect(field.result.current.channel).toBe("personal");
+	});
+
+	it("should render again once a mutation's errors change", async () => {
+		stub({ applyResult: { errors: { "too-long": {} } } });
+		const field = renderField();
+
+		await act(() => field.result.current.mutations.set({ text: "New" }));
+
+		expect(field.result.current.errors.set).toEqual({ "too-long": {} });
+	});
+
+	it.each([
+		["a ref, as its element", { current: "an-element" }, "an-element"],
+		["a plain value, as it is", true, true],
+	])("should hand a query reading rendered %s", (_label, drawn, expected) => {
+		stub();
+
+		const field = renderHook(() =>
+			useActions(aDrawnField(), { name: "a-field" }, { rendered: { drawn } }),
+		);
+
+		expect(field.result.current.queries.readDrawn()).toBe(expected);
+	});
+
+	it("should tell onValidationError about a call that failed a rule", async () => {
+		stub({ applyResult: { errors: { "too-long": {} } } });
+		const onValidationError = jest.fn();
+		const field = renderField({ onValidationError });
+
+		await act(() => field.result.current.mutations.set({ text: "New" }));
+
+		expect(onValidationError).toHaveBeenCalledWith({
+			operation: "set",
+			input: { text: "New" },
+			errors: { "too-long": {} },
+		});
+	});
+});