@bettercms-ai/kit 1.0.0 → 2.0.0

package/{controls → dist/controls}/rich-text/component-card.js

@@ -1,11 +1,14 @@
 import { cn } from "../../lib/cn.js";
 import { useKitServices } from "../../context.js";
 import { Button, IconButton } from "../../ui/button.js";
-import { Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger, Modal, ModalBody, ModalContent, ModalFooter, ModalHeader, Tooltip } from "../../ui/overlay.js";
+import { Menu, MenuContent, MenuItem, MenuSeparator, MenuSub, MenuSubContent, MenuSubTrigger, MenuTrigger, Modal, ModalBody, ModalContent, ModalFooter, ModalHeader, Tooltip } from "../../ui/overlay.js";
+import { eventKey } from "../../lib/key-event.js";
+import { useCatalogComponents } from "./catalog.js";
+import { ComponentPanel, closeComponentPanel, openComponentPanel, useComponentPanel } from "./component-panel.js";
 import * as React from "react";
-import { IconAlertTriangle, IconArrowDown, IconArrowUp, IconComponents, IconCopy, IconDots, IconLayoutNavbarCollapse, IconLayoutNavbarExpand, IconLink, IconRefresh, IconTrash, IconUnlink } from "@tabler/icons-react";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-//#region src/kit/controls/rich-text/component-card.tsx
+import { IconAdjustmentsHorizontal, IconAlertTriangle, IconArrowBarToDown, IconArrowBarToUp, IconArrowUpRight, IconCheck, IconComponents, IconCopy, IconDots, IconGripVertical, IconLayoutNavbarCollapse, IconLayoutNavbarExpand, IconLink, IconRefresh, IconReplace, IconRestore, IconTrash, IconUnlink } from "@tabler/icons-react";
+//#region src/controls/rich-text/component-card.tsx
 /**
 * The embedded component card (V2 features/blocks/instance-card.tsx + instance-ui.tsx StateChip / MissingNote / dialogs),
 * drawn when the host can look the component up (KitServices.useComponentInfo, component-services.ts):
@@ -50,10 +53,13 @@ function useWidth(ref) {
 /** A stored value as one line of reading text, or null when it has none (lists, empty values, flags). */
 function readable(v) {
 	if (typeof v === "number") return String(v);
-	if (typeof v === "string") return v.replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim() || null;
+	if (typeof v === "string") {
+		if (v.startsWith("data:image/")) return "Image";
+		return (new DOMParser().parseFromString(v.replace(/<[^>]+>/g, " "), "text/html").body.textContent ?? "").replace(/\s+/g, " ").trim() || null;
+	}
 	if (v && typeof v === "object" && !Array.isArray(v)) {
 		const o = v;
-		return readable(o.label ?? o.text ?? o.title ?? o.href);
+		return readable(o.label || o.text || o.title || o.altText || o.href || o.url || o.html);
 	}
 	return null;
 }
@@ -72,27 +78,54 @@ var laterThan = (a, b) => {
 	return Number.isFinite(x) && Number.isFinite(y) && x > y;
 };
 var same = (a, b) => a === b || JSON.stringify(a) === JSON.stringify(b);
+/**
+* "Collapse preview", remembered per component (V2 instance-card): read before the first render, so a reload never
+* draws the preview and then folds it away. Storage that is absent or throws reads as expanded.
+*/
+function useCollapsed(ref) {
+	const key = ref ? `bcms:card-collapsed:${ref}` : null;
+	const [collapsed, setState] = React.useState(() => {
+		try {
+			return !!key && globalThis.localStorage?.getItem(key) === "1";
+		} catch {
+			return false;
+		}
+	});
+	return [collapsed, React.useCallback((next) => {
+		setState(next);
+		if (!key) return;
+		try {
+			if (next) globalThis.localStorage?.setItem(key, "1");
+			else globalThis.localStorage?.removeItem(key);
+		} catch {}
+	}, [key])];
+}
 function ComponentCard({ m, el, ctx, use, overrides, set }) {
-	const { copyComponent, toast, ComponentPreview } = useKitServices();
-	const { info, loading, error } = use(m.ref ?? "");
+	const { copyComponent, toast, ComponentPreview, IconGlyph, componentVariantMember, ComponentSettings, openComponent, componentHref } = useKitServices();
+	const member = !m.detached && m.ref && m.variant ? componentVariantMember?.(m.ref, m.variant) : void 0;
+	const ref = member ?? m.ref;
+	const variant = member ? void 0 : m.variant;
+	const { info, loading, error } = use(ref ?? "");
 	const card = React.useRef(null);
 	const width = useWidth(card);
 	const narrow = !!width && width <= NARROW;
-	const [collapsed, setCollapsed] = React.useState(false);
+	const [collapsed, setCollapsed] = useCollapsed(m.ref);
 	const [dialog, setDialog] = React.useState(null);
 	const [busy, setBusy] = React.useState(false);
 	const detached = !!m.detached;
 	const own = React.useMemo(() => parseObj(m.props), [m.props]);
-	const missing = !m.ref || !!info?.missing;
-	const name = info && !info.missing ? info.name : m.name || info?.name || "Component";
+	const missing = !ref || !!info?.missing;
+	const name = info && !info.missing ? info.name : m.name || info?.name || "Block";
 	const fieldKeys = new Set((info?.fields ?? []).map((f) => f.key));
 	const edited = missing || detached ? 0 : Object.keys(overrides).filter((k) => fieldKeys.has(k)).length;
 	const places = info?.places;
 	const known = !!info || missing;
 	const changed = detached && !missing && laterThan(info?.publishedAt, m.sourcePublishedAt);
-	const label = `${name} component${known ? `, ${detached ? `Detached${changed ? ", Shared version changed" : ""}` : missing ? "Missing component" : edited ? "Edited here" : "Shared"}` : ""}${known && !missing && !detached && places != null ? `, ${placesShort(places)}` : ""}`;
-	const rows = detached ? copyRows(own, info?.fields, m.variant) : previewRows(missing, info?.fields, overrides, m.variant);
-	const image = missing || detached || edited || m.variant ? null : info?.image || null;
+	const state = detached ? `Detached${changed ? ", Shared version changed" : ""}` : missing ? "Missing block" : edited || m.variant ? "Edited here" : "Shared";
+	const requiredEmpty = !missing && !detached && (info?.fields ?? []).some((f) => f.required && blank(f.key in overrides ? overrides[f.key] : f.value));
+	const label = `${name} block${known ? `, ${state}` : ""}${known && !missing && !detached && places != null ? `, ${placesShort(places)}` : ""}${requiredEmpty ? `. ${REQUIRED_EMPTY}` : ""}`;
+	const rows = detached ? copyRows(own, info?.fields, m.variant) : previewRows(missing, info?.fields, overrides, variant);
+	const image = missing || detached || edited || variant ? null : info?.image || null;
 	const liveProps = React.useMemo(() => detached ? own : {
 		...Object.fromEntries((info?.fields ?? []).flatMap((f) => f.value !== void 0 ? [[f.key, f.value]] : [])),
 		...overrides
@@ -102,9 +135,9 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 		info?.fields,
 		overrides
 	]);
-	const live = ComponentPreview && m.ref && info && !missing && !m.variant ? {
+	const live = ComponentPreview && ref && info && !missing && !variant ? {
 		Preview: ComponentPreview,
-		ref: m.ref
+		ref
 	} : null;
 	const preview = live ? /* @__PURE__ */ jsx(LivePreview, {
 		Preview: live.Preview,
@@ -117,6 +150,27 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 		rows
 	}) : null;
 	const canCopy = !!copyComponent && !!m.ref && !ctx.readOnly;
+	const ro = !!ctx.readOnly;
+	const linked = !missing && !detached;
+	const open = useComponentPanel(el);
+	const editing = !!open;
+	const [cardEl, setCardEl] = React.useState(null);
+	const cardRef = React.useCallback((n) => {
+		card.current = n;
+		if (n) setCardEl(n);
+	}, []);
+	const openPanel = React.useCallback((focusKey) => openComponentPanel(el, focusKey ?? null), [el]);
+	const closePanel = React.useCallback(() => closeComponentPanel(el), [el]);
+	const focusCard = React.useCallback(() => requestAnimationFrame(() => card.current?.focus({ preventScroll: true })), []);
+	React.useEffect(() => () => closeComponentPanel(el), [el]);
+	const swappable = useCatalogComponents()?.components ?? [];
+	const [swapTo, setSwapTo] = React.useState(null);
+	const editAll = openComponent && m.ref && info && linked ? {
+		label: places != null && places > 1 ? `Edit for all ${places} places` : "Edit the shared block",
+		run: () => openComponent(m.ref)
+	} : void 0;
+	const href = m.ref ? componentHref?.(m.ref, m.id) : void 0;
+	const hasEdits = linked && (Object.keys(overrides).length > 0 || !!m.variant);
 	/**
 	* The change as ONE undo step (IslandCtx.step: the dock's toolbar Undo, this toast's Undo and ⌘Z in the body are one
 	* undo), and the toast that offers it back.
@@ -154,7 +208,7 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 				...copy.blocks !== void 0 ? { blocks: copy.blocks } : {},
 				...copy.sourcePublishedAt ? { sourcePublishedAt: copy.sourcePublishedAt } : {},
 				...cur.extra !== void 0 ? { extra: cur.extra } : {}
-			}), "Make a separate copy", title, "It keeps its content and no longer follows the shared component.");
+			}), "Make a separate copy", title, "It keeps its content and no longer follows the shared block.");
 		} catch (e) {
 			ctx.notify("This place couldn't keep its own copy", e instanceof Error ? e.message : String(e));
 		} finally {
@@ -172,24 +226,143 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 			...mode === "keep" && Object.keys(kept).length ? { overrides: JSON.stringify(kept) } : {},
 			...mode === "keep" && cur.variant !== void 0 ? { variant: cur.variant } : {},
 			...cur.extra !== void 0 ? { extra: cur.extra } : {}
-		}), "Use shared version again", `${name} is shared again`, mode === "keep" && n ? `${n} ${n === 1 ? "edit" : "edits"} kept here.` : "It shows the component's content.");
+		}), "Use shared version again", `${name} is shared again`, mode === "keep" && n ? `${n} ${n === 1 ? "edit" : "edits"} kept here.` : "It shows the block's content.");
+	};
+	/** V2 instanceOps.resetAll: this place's overrides and its layout go, as one undo step. */
+	const resetAll = () => commit((cur) => {
+		const { variant: _v, ...rest } = cur;
+		return {
+			...rest,
+			overrides: "{}"
+		};
+	}, "Reset all edits here", `Back to the shared ${name}`, "This place shows the block's content again.");
+	/**
+	* V2 instanceOps.swap, once the new component's fields are known (SwapResolver): this place's edits stay only where the
+	* new component declares a field with that key; everything else is the new component's own content. One undo step.
+	*/
+	const swap = (to, next) => {
+		const keys = new Set((next.fields ?? []).map((f) => f.key));
+		const kept = Object.fromEntries(Object.entries(detached ? own : overrides).filter(([k]) => keys.has(k)));
+		const n = Object.keys(kept).length;
+		commit((cur) => ({
+			id: cur.id,
+			ref: to.id,
+			name: next.name || to.name,
+			overrides: JSON.stringify(kept),
+			...cur.extra !== void 0 ? { extra: cur.extra } : {}
+		}), `Swap to ${to.name}`, `Swapped to ${to.name}`, n ? `Kept ${n} ${n === 1 ? "edit" : "edits"} made here.` : "It shows the block's own content.");
+	};
+	const copyLink = () => {
+		if (!href) return;
+		navigator.clipboard?.writeText(href).catch(() => {});
+		toast?.success("Link copied", { description: `Opens this page scrolled to the ${name}.` });
+	};
+	/** The panel's form writes this place: overrides (or the layout) as one undo step each, through the island's model. */
+	const onOverrides = (next) => {
+		const changed = [.../* @__PURE__ */ new Set([...Object.keys(next), ...Object.keys(overrides)])].find((k) => !same(next[k], overrides[k]));
+		set({ overrides: JSON.stringify(next) }, changed ? `Edit ${changed}` : "Edit block properties");
+	};
+	const onVariant = (variant) => set((cur) => {
+		const { variant: _v, ...rest } = cur;
+		return variant ? {
+			...rest,
+			variant
+		} : rest;
+	}, "Change layout");
+	/** V2 instance card keys, on the focused card itself (fields and the portalled panel keep their own). */
+	const onKeyDown = (e) => {
+		if (e.defaultPrevented || e.target !== card.current) return;
+		const mod = e.metaKey || e.ctrlKey;
+		const k = eventKey(e);
+		if (mod && k === "z") {
+			e.preventDefault();
+			e.stopPropagation();
+			if (e.shiftKey) ctx.redo?.();
+			else ctx.undo?.();
+			return;
+		}
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			openPanel();
+			return;
+		}
+		if (e.key === "Escape") {
+			e.preventDefault();
+			e.stopPropagation();
+			if (editing) closePanel();
+			else ctx.exit(el);
+			return;
+		}
+		if (ro) return;
+		if (mod && k === "d" && ctx.duplicate) {
+			e.preventDefault();
+			e.stopPropagation();
+			ctx.duplicate(el);
+		} else if (e.altKey && (e.key === "ArrowUp" || e.key === "ArrowDown") && ctx.move) {
+			e.preventDefault();
+			ctx.move(el, e.key === "ArrowUp" ? -1 : 1);
+			focusCard();
+		} else if (e.key === "Backspace" || e.key === "Delete") {
+			e.preventDefault();
+			ctx.remove(el);
+		}
 	};
+	const chip = (compact) => detached ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(DetachedChip, {
+		name,
+		compact
+	}), changed ? /* @__PURE__ */ jsx(ChangedChip, {
+		name,
+		compact,
+		onReview: canCopy ? () => setDialog("relink") : void 0
+	}) : null] }) : known ? /* @__PURE__ */ jsx(StateChip, {
+		missing,
+		places,
+		edited,
+		layout: !!m.variant,
+		requiredEmpty,
+		compact
+	}) : null;
 	return /* @__PURE__ */ jsxs("div", {
-		ref: card,
+		ref: cardRef,
 		role: "group",
+		tabIndex: 0,
 		"aria-label": label,
 		"aria-roledescription": "component",
+		"aria-haspopup": "dialog",
+		"aria-expanded": editing,
 		"aria-busy": busy || void 0,
 		"data-instance-card": "",
 		"data-rt-isolate": "",
 		"data-state": detached ? "detached" : missing ? "missing" : known ? "linked" : void 0,
-		className: cn("group/inst relative rounded-kit-lg border bg-kit-control-bg text-left transition-colors duration-150 motion-reduce:transition-none", missing && !detached ? "border-kit-warning-line" : "border-kit-line hover:border-kit-line-strong"),
+		onKeyDown,
+		onClick: (e) => {
+			if (!e.currentTarget.contains(e.target) || e.target.closest("button,a,[role=menuitem],[role=note],[role=alert]")) return;
+			openPanel(propKeyAt(e.currentTarget, e.clientX, e.clientY));
+		},
+		className: cn("group/inst relative cursor-pointer rounded-kit-lg border bg-kit-control-bg text-left focus-visible:outline-offset-2 transition-colors duration-150 motion-reduce:transition-none", editing ? "border-transparent shadow-[0_0_0_2px_var(--kit-accent)]" : missing && !detached ? "border-kit-warning-line" : "border-kit-line hover:border-kit-line-strong"),
 		children: [
 			/* @__PURE__ */ jsxs("div", {
 				className: "flex h-9 select-none items-center gap-1.5 pl-1 pr-1",
 				children: [
-					/* @__PURE__ */ jsx("span", { className: "w-1" }),
-					/* @__PURE__ */ jsx(IconComponents, {
+					ro || !ctx.drag ? /* @__PURE__ */ jsx("span", { className: "w-1" }) : /* @__PURE__ */ jsx(Tooltip, {
+						content: "Drag to move",
+						children: /* @__PURE__ */ jsx("button", {
+							type: "button",
+							"aria-label": `Move ${name}`,
+							tabIndex: -1,
+							onPointerDown: (e) => ctx.drag?.(el, e),
+							className: "flex h-7 w-4 shrink-0 cursor-grab touch-none pointer-coarse:size-11 items-center justify-center rounded-kit-sm text-kit-fg-4 opacity-0 transition-opacity duration-150 hover:text-kit-fg-2 active:cursor-grabbing motion-reduce:transition-none group-hover/inst:opacity-100 group-focus-within/inst:opacity-100 pointer-coarse:opacity-100 [&_svg]:size-3.5",
+							children: /* @__PURE__ */ jsx(IconGripVertical, { stroke: 1.5 })
+						})
+					}),
+					info?.icon && IconGlyph ? /* @__PURE__ */ jsx("span", {
+						"aria-hidden": true,
+						className: "flex size-[15px] shrink-0 text-kit-fg-2 [&_svg]:size-full",
+						children: /* @__PURE__ */ jsx(IconGlyph, {
+							name: info.icon,
+							className: "size-[15px]"
+						})
+					}) : /* @__PURE__ */ jsx(IconComponents, {
 						size: 15,
 						stroke: 1.5,
 						className: "shrink-0 text-kit-fg-2",
@@ -199,33 +372,31 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 						className: "min-w-0 shrink truncate text-kit-sm font-medium text-kit-fg",
 						children: name
 					}),
-					detached ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(DetachedChip, {
-						name,
-						compact: narrow
-					}), changed ? /* @__PURE__ */ jsx(ChangedChip, {
-						name,
-						compact: narrow,
-						onReview: canCopy ? () => setDialog("relink") : void 0
-					}) : null] }) : known ? /* @__PURE__ */ jsx(StateChip, {
-						missing,
-						places,
-						edited,
-						compact: narrow
-					}) : null,
+					chip(narrow),
 					/* @__PURE__ */ jsx("span", { className: "flex-1" }),
-					ctx.readOnly ? null : /* @__PURE__ */ jsxs(Menu, { children: [/* @__PURE__ */ jsx(MenuTrigger, { render: /* @__PURE__ */ jsx(IconButton, {
+					/* @__PURE__ */ jsxs(Menu, { children: [/* @__PURE__ */ jsx(MenuTrigger, { render: /* @__PURE__ */ jsx(IconButton, {
 						size: "sm",
 						className: "shrink-0",
 						label: `${name} actions`,
 						children: /* @__PURE__ */ jsx(IconDots, { stroke: 1.5 })
 					}) }), /* @__PURE__ */ jsxs(MenuContent, {
 						align: "end",
-						className: "w-56",
+						className: "w-64",
 						children: [
-							preview ? /* @__PURE__ */ jsx(MenuItem, {
-								icon: collapsed ? /* @__PURE__ */ jsx(IconLayoutNavbarExpand, { stroke: 1.5 }) : /* @__PURE__ */ jsx(IconLayoutNavbarCollapse, { stroke: 1.5 }),
-								onClick: () => setCollapsed(!collapsed),
-								children: collapsed ? "Show preview" : "Collapse preview"
+							ComponentSettings ? /* @__PURE__ */ jsx(MenuItem, {
+								icon: /* @__PURE__ */ jsx(IconAdjustmentsHorizontal, { stroke: 1.5 }),
+								onClick: () => openPanel(),
+								children: "Edit properties"
+							}) : null,
+							editAll ? /* @__PURE__ */ jsx(MenuItem, {
+								icon: /* @__PURE__ */ jsx(IconArrowUpRight, { stroke: 1.5 }),
+								onClick: editAll.run,
+								children: editAll.label
+							}) : null,
+							!ro && hasEdits ? /* @__PURE__ */ jsx(MenuItem, {
+								icon: /* @__PURE__ */ jsx(IconRestore, { stroke: 1.5 }),
+								onClick: resetAll,
+								children: "Reset all edits here"
 							}) : null,
 							canCopy && info && !missing && !detached ? /* @__PURE__ */ jsx(MenuItem, {
 								icon: /* @__PURE__ */ jsx(IconUnlink, { stroke: 1.5 }),
@@ -244,29 +415,68 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 								onClick: () => setDialog("relink"),
 								children: "Use shared version again"
 							}) : null,
-							ctx.duplicate ? /* @__PURE__ */ jsx(MenuItem, {
+							!ro && swappable.length ? /* @__PURE__ */ jsxs(MenuSub, { children: [/* @__PURE__ */ jsx(MenuSubTrigger, {
+								icon: /* @__PURE__ */ jsx(IconReplace, { stroke: 1.5 }),
+								children: "Swap block"
+							}), /* @__PURE__ */ jsx(MenuSubContent, {
+								className: "max-h-[320px] w-60 overflow-y-auto",
+								children: swappable.map((c) => {
+									const on = c.id === m.ref;
+									return /* @__PURE__ */ jsx(MenuItem, {
+										icon: /* @__PURE__ */ jsx(IconComponents, { stroke: 1.5 }),
+										disabled: on || !!swapTo,
+										onClick: () => setSwapTo(c),
+										children: /* @__PURE__ */ jsxs("span", {
+											className: "flex w-full items-center justify-between gap-2",
+											children: [/* @__PURE__ */ jsx("span", {
+												className: "truncate",
+												children: c.name
+											}), on ? /* @__PURE__ */ jsx(IconCheck, {
+												className: "size-3.5 shrink-0 text-kit-fg-2",
+												stroke: 2,
+												"aria-label": "Current"
+											}) : null]
+										})
+									}, c.id);
+								})
+							})] }) : null,
+							preview ? /* @__PURE__ */ jsx(MenuItem, {
+								icon: collapsed ? /* @__PURE__ */ jsx(IconLayoutNavbarExpand, { stroke: 1.5 }) : /* @__PURE__ */ jsx(IconLayoutNavbarCollapse, { stroke: 1.5 }),
+								onClick: () => setCollapsed(!collapsed),
+								children: collapsed ? "Show preview" : "Collapse preview"
+							}) : null,
+							/* @__PURE__ */ jsx(MenuSeparator, {}),
+							!ro && ctx.duplicate ? /* @__PURE__ */ jsx(MenuItem, {
 								icon: /* @__PURE__ */ jsx(IconCopy, { stroke: 1.5 }),
+								shortcut: "⌘D",
 								onClick: () => ctx.duplicate?.(el),
 								children: "Duplicate"
 							}) : null,
-							ctx.move ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(MenuItem, {
-								icon: /* @__PURE__ */ jsx(IconArrowUp, { stroke: 1.5 }),
+							!ro && ctx.move ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(MenuItem, {
+								icon: /* @__PURE__ */ jsx(IconArrowBarToUp, { stroke: 1.5 }),
+								shortcut: "⌥↑",
 								disabled: !el.previousElementSibling,
 								onClick: () => ctx.move?.(el, -1),
 								children: "Move up"
 							}), /* @__PURE__ */ jsx(MenuItem, {
-								icon: /* @__PURE__ */ jsx(IconArrowDown, { stroke: 1.5 }),
+								icon: /* @__PURE__ */ jsx(IconArrowBarToDown, { stroke: 1.5 }),
+								shortcut: "⌥↓",
 								disabled: !el.nextElementSibling,
 								onClick: () => ctx.move?.(el, 1),
 								children: "Move down"
 							})] }) : null,
-							/* @__PURE__ */ jsx(MenuSeparator, {}),
-							/* @__PURE__ */ jsx(MenuItem, {
+							href ? /* @__PURE__ */ jsx(MenuItem, {
+								icon: /* @__PURE__ */ jsx(IconLink, { stroke: 1.5 }),
+								onClick: copyLink,
+								children: "Copy link"
+							}) : null,
+							!ro ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(MenuSeparator, {}), /* @__PURE__ */ jsx(MenuItem, {
 								danger: true,
 								icon: /* @__PURE__ */ jsx(IconTrash, { stroke: 1.5 }),
+								shortcut: "⌫",
 								onClick: () => ctx.remove(el),
 								children: "Remove"
-							})
+							})] }) : null
 						]
 					})] })
 				]
@@ -336,7 +546,37 @@ function ComponentCard({ m, el, ctx, use, overrides, set }) {
 					setDialog(null);
 					relink(mode);
 				}
-			})] }) : null
+			})] }) : null,
+			swapTo ? /* @__PURE__ */ jsx(SwapResolver, {
+				use,
+				to: swapTo,
+				onReady: (next) => {
+					setSwapTo(null);
+					swap(swapTo, next);
+				},
+				onFail: (why) => {
+					setSwapTo(null);
+					ctx.notify(`Couldn't swap to ${swapTo.name}`, why);
+				}
+			}) : null,
+			open ? /* @__PURE__ */ jsx(ComponentPanel, {
+				name,
+				chip: chip(false),
+				anchor: cardEl,
+				open,
+				editAll,
+				onClose: closePanel,
+				focusBack: focusCard,
+				settings: {
+					componentId: m.ref ?? "",
+					overrides,
+					...m.variant ? { variant: m.variant } : {},
+					...detached ? { detached: { props: own } } : {},
+					readOnly: ro || detached || missing,
+					onOverrides,
+					onVariant
+				}
+			}) : null
 		]
 	});
 }
@@ -355,11 +595,14 @@ function copyEdits(m, own, fields) {
 	for (const f of fields ?? []) if (f.key in own && !same(own[f.key], f.value)) out[f.key] = own[f.key];
 	return out;
 }
+var REQUIRED_EMPTY = "Required field empty.";
+/** Nothing an author would call filled in: no value, blank text, an empty list. */
+var blank = (v) => v == null || typeof v === "string" && !v.trim() || Array.isArray(v) && v.length === 0;
 /** V2 StateChip: 13px, neutral, not a pill; the missing chip is the one tinted state. */
-function StateChip({ missing, places, edited, compact }) {
+function StateChip({ missing, places, edited, layout, requiredEmpty, compact }) {
 	const base = CHIP;
 	if (missing) return /* @__PURE__ */ jsx(Tooltip, {
-		content: "The component was deleted. Readers see nothing in this place.",
+		content: "The block was deleted. Readers see nothing in this place.",
 		children: /* @__PURE__ */ jsxs("span", {
 			className: cn(base, "bg-kit-warning-soft px-1.5 text-kit-warning-fg"),
 			children: [/* @__PURE__ */ jsx(IconAlertTriangle, {
@@ -368,17 +611,23 @@ function StateChip({ missing, places, edited, compact }) {
 				"aria-hidden": true
 			}), compact ? /* @__PURE__ */ jsx("span", {
 				className: "sr-only",
-				children: "Missing component"
-			}) : "Missing component"]
+				children: "Missing block"
+			}) : "Missing block"]
 		})
 	});
 	const count = places ? placesShort(places) : null;
+	const tip = `Changes here apply only to this place. Edit the block to change ${places && places > 1 ? `all ${places}` : "it everywhere"}.${edited ? ` ${edited} ${edited === 1 ? "field" : "fields"} edited here.` : ""}${layout ? " Its layout is set here." : ""}${requiredEmpty ? ` ${REQUIRED_EMPTY}` : ""}`;
 	return /* @__PURE__ */ jsx(Tooltip, {
-		content: `Changes here apply only to this place. Edit the component to change ${places && places > 1 ? `all ${places}` : "it everywhere"}.${edited ? ` ${edited} ${edited === 1 ? "field" : "fields"} edited here.` : ""}`,
+		content: tip,
 		children: /* @__PURE__ */ jsxs("span", {
 			className: cn(base, "px-1 text-kit-fg-2"),
 			tabIndex: -1,
 			children: [
+				requiredEmpty ? /* @__PURE__ */ jsx("span", {
+					"data-required-empty": true,
+					className: "size-1.5 shrink-0 rounded-full bg-kit-danger-fg",
+					"aria-hidden": true
+				}) : null,
 				/* @__PURE__ */ jsx(IconLink, {
 					className: "size-3.5 shrink-0",
 					stroke: 1.5,
@@ -392,7 +641,7 @@ function StateChip({ missing, places, edited, compact }) {
 					className: "sr-only",
 					children: ", shared"
 				}) : null,
-				edited ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+				edited || layout ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
 					className: "ml-1 size-1.5 shrink-0 rounded-full bg-kit-accent",
 					"aria-hidden": true
 				}), compact ? /* @__PURE__ */ jsx("span", {
@@ -453,7 +702,7 @@ function DetachDialog({ open, name, places, onClose, onConfirm }) {
 			children: [
 				/* @__PURE__ */ jsx(ModalHeader, {
 					title: `Make a separate copy of ${name}?`,
-					description: "This place keeps its current content and stops following the shared component."
+					description: "This place keeps its current content and stops following the shared block."
 				}),
 				others != null ? /* @__PURE__ */ jsx(ModalBody, {
 					className: "pt-2 text-kit-sm text-kit-fg-2",
@@ -496,7 +745,7 @@ function RelinkDialog({ open, name, kept, onClose, onConfirm }) {
 			children: [
 				/* @__PURE__ */ jsx(ModalHeader, {
 					title: `Use the shared ${name} again?`,
-					description: "This place follows the shared component again."
+					description: "This place follows the shared block again."
 				}),
 				/* @__PURE__ */ jsx(ModalBody, {
 					className: "pt-3",
@@ -558,6 +807,12 @@ function RelinkDialog({ open, name, kept, onClose, onConfirm }) {
 * component's own), then the layout this place draws it in. A missing component has only what this place stored: its
 * overrides, named by their keys, and its layout.
 */
+/** A choice field's value as its option's label (BUG-8: a select whose values are ids listed the id); others as they are. */
+function chosen(f, v) {
+	if (!f.options) return v;
+	const label = (x) => f.options.find((o) => o.value === x)?.label ?? x;
+	return Array.isArray(v) ? v.map(label).join(", ") : label(v);
+}
 function previewRows(missing, fields, overrides, variant) {
 	const out = [];
 	if (missing || !fields) for (const [key, v] of Object.entries(overrides)) {
@@ -569,7 +824,7 @@ function previewRows(missing, fields, overrides, variant) {
 		});
 	}
 	else for (const f of fields) {
-		const text = readable(f.key in overrides ? overrides[f.key] : f.value);
+		const text = readable(chosen(f, f.key in overrides ? overrides[f.key] : f.value));
 		if (text) out.push({
 			key: f.key,
 			label: f.label,
@@ -598,7 +853,7 @@ function copyRows(own, fields, variant) {
 			text
 		});
 	};
-	for (const f of fields ?? []) push(f.key, f.label, f.key in own ? own[f.key] : f.value);
+	for (const f of fields ?? []) push(f.key, f.label, chosen(f, f.key in own ? own[f.key] : f.value));
 	for (const [key, v] of Object.entries(own)) if (!fields?.some((f) => f.key === key)) push(key, key, v);
 	if (variant) out.push({
 		key: "__variant",
@@ -607,19 +862,65 @@ function copyRows(own, fields, variant) {
 	});
 	return out;
 }
-/** The preview's frame: under the card's header, at most PREVIEW_H tall. */
-var PREVIEW_CHROME = "relative overflow-hidden rounded-b-kit-lg border-t border-kit-line-subtle bg-kit-subtle";
-function PreviewWindow({ image, rows }) {
-	return /* @__PURE__ */ jsx("div", {
+/**
+* The preview's frame: under the card's header, capped at PREVIEW_H (its top border inside, as V2's CappedPreview).
+* The cap lifts instantly on hover: a height animation is layout work every frame (canvas revamp V937).
+*/
+var PREVIEW_CHROME = "group/cap relative max-h-[240px] overflow-hidden rounded-b-kit-lg border-t border-kit-line-subtle";
+/**
+* V2 instance-card CappedPreview: at most 240px, faded at its foot when the content is taller; hover shows its full
+* height. Measured a frame after each resize, so a frame or picture that sizes itself late is read once settled.
+*/
+function CappedPreview({ live, children }) {
+	const inner = React.useRef(null);
+	const [tall, setTall] = React.useState(false);
+	const [site, setSite] = React.useState(false);
+	React.useLayoutEffect(() => {
+		const el = inner.current;
+		if (!el) return;
+		let raf = 0;
+		const measure = () => {
+			cancelAnimationFrame(raf);
+			raf = requestAnimationFrame(() => {
+				setTall(el.offsetHeight > 241);
+				setSite(!!el.querySelector("iframe"));
+			});
+		};
+		measure();
+		const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+		ro?.observe(el);
+		const mo = typeof MutationObserver === "undefined" ? null : new MutationObserver(measure);
+		mo?.observe(el, {
+			childList: true,
+			subtree: true
+		});
+		return () => {
+			ro?.disconnect();
+			mo?.disconnect();
+			cancelAnimationFrame(raf);
+		};
+	}, []);
+	return /* @__PURE__ */ jsxs("div", {
 		"data-instance-preview": "",
-		className: PREVIEW_CHROME,
-		style: { maxHeight: PREVIEW_H },
-		children: /* @__PURE__ */ jsx(PreviewBody, {
-			image,
-			rows
-		})
+		"data-live": live ? "" : void 0,
+		"data-tall": tall ? "" : void 0,
+		"data-site": site ? "" : void 0,
+		className: cn(PREVIEW_CHROME, site ? "bg-kit-site-paper" : "bg-kit-subtle", tall && "can-hover:hover:max-h-[2400px]"),
+		children: [/* @__PURE__ */ jsx("div", {
+			ref: inner,
+			children
+		}), tall ? /* @__PURE__ */ jsx("div", {
+			"aria-hidden": true,
+			className: cn("pointer-events-none absolute inset-x-0 bottom-0 h-6 bg-gradient-to-b from-transparent transition-opacity duration-150 ease-out can-hover:group-hover/cap:opacity-0 motion-reduce:transition-none", site ? "to-kit-site-paper" : "to-kit-subtle")
+		}) : null]
 	});
 }
+function PreviewWindow({ image, rows }) {
+	return /* @__PURE__ */ jsx(CappedPreview, { children: /* @__PURE__ */ jsx(PreviewBody, {
+		image,
+		rows
+	}) });
+}
 /**
 * The component drawn live by the host (KitServices.ComponentPreview), mounted once the card is on screen. Its height is
 * reserved from the start (PREVIEW_H), so the card never moves while it loads; where the host cannot draw it, the values
@@ -637,44 +938,30 @@ function LivePreview({ Preview, componentId, title, props, rows }) {
 		io.observe(el);
 		return () => io.disconnect();
 	}, [seen]);
-	return /* @__PURE__ */ jsx("div", {
-		ref: box,
-		"data-instance-preview": "",
-		"data-live": "",
-		className: PREVIEW_CHROME,
-		children: seen ? /* @__PURE__ */ jsx(Preview, {
-			componentId,
-			title,
-			props,
-			fallback: (reason) => /* @__PURE__ */ jsx(PreviewBody, {
-				image: null,
-				rows,
-				note: reason
+	return /* @__PURE__ */ jsx(CappedPreview, {
+		live: true,
+		children: /* @__PURE__ */ jsx("div", {
+			ref: box,
+			children: seen ? /* @__PURE__ */ jsx(Preview, {
+				componentId,
+				title,
+				props,
+				fallback: (reason) => /* @__PURE__ */ jsx(PreviewBody, {
+					image: null,
+					rows,
+					note: reason
+				})
+			}) : /* @__PURE__ */ jsx("div", {
+				"aria-hidden": true,
+				style: { height: PREVIEW_H }
 			})
-		}) : /* @__PURE__ */ jsx("div", {
-			"aria-hidden": true,
-			style: { height: PREVIEW_H }
 		})
 	});
 }
 function PreviewBody({ image, rows, note }) {
-	const inner = React.useRef(null);
-	const [tall, setTall] = React.useState(false);
 	const [loaded, setLoaded] = React.useState(!image);
-	React.useLayoutEffect(() => {
-		const el = inner.current;
-		if (!el) return;
-		const on = () => setTall(el.scrollHeight > PREVIEW_H + 1);
-		on();
-		if (typeof ResizeObserver === "undefined") return;
-		const ro = new ResizeObserver(on);
-		ro.observe(el);
-		return () => ro.disconnect();
-	}, []);
 	return /* @__PURE__ */ jsx("div", {
-		ref: inner,
-		className: cn(tall && "[mask-image:linear-gradient(to_bottom,black_calc(100%-24px),transparent)]"),
-		style: tall || !loaded ? { height: PREVIEW_H } : void 0,
+		style: !loaded ? { height: PREVIEW_H } : void 0,
 		children: image ? /* @__PURE__ */ jsx("img", {
 			src: image,
 			alt: "",
@@ -688,6 +975,7 @@ function PreviewBody({ image, rows, note }) {
 		}) : null, /* @__PURE__ */ jsx("dl", {
 			className: "flex flex-col gap-3 px-4 py-3.5",
 			children: rows.map((r) => /* @__PURE__ */ jsxs("div", {
+				"data-prop-key": r.key === "__variant" ? void 0 : r.key,
 				className: "min-w-0",
 				children: [/* @__PURE__ */ jsx("dt", {
 					className: "truncate text-kit-xs text-kit-fg-3",
@@ -700,6 +988,36 @@ function PreviewBody({ image, rows, note }) {
 		})] })
 	});
 }
+/** The listed value (`data-prop-key`) under a point of the card, else null. */
+function propKeyAt(root, x, y) {
+	for (const row of root.querySelectorAll("[data-prop-key]")) {
+		const r = row.getBoundingClientRect();
+		if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return row.dataset.propKey ?? null;
+	}
+	return null;
+}
+/**
+* Swap component: the new component's fields come from the same lookup the card reads (KitServices.useComponentInfo, a
+* hook, so it is asked from a component of its own). Answers once, when they are known.
+*/
+function SwapResolver({ use, to, onReady, onFail }) {
+	const { info, error } = use(to.id);
+	const done = React.useRef(false);
+	React.useEffect(() => {
+		if (done.current) return;
+		if (error) {
+			done.current = true;
+			onFail(error);
+		} else if (info?.missing) {
+			done.current = true;
+			onFail("The library has no such block.");
+		} else if (info) {
+			done.current = true;
+			onReady(info);
+		}
+	});
+	return null;
+}
 //#endregion
 export { ComponentCard };