@bettercms-ai/kit 2.0.0-next.0 → 2.0.0-next.1

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

@@ -0,0 +1,167 @@
+import { cn } from "../../lib/cn.js";
+import { ArticleEmpty, ArticlePanelBlock } from "./article-shell.js";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { IconPhoto } from "@tabler/icons-react";
+//#region src/controls/rich-text/gallery.tsx
+/**
+* RICH TEXT · Gallery (kit-richtext-ui-spec.md §2): V2's article block, stored as the PT block object
+* `{ _type: "gallery", layout: "grid" | "carousel", images: { _key, image, caption? }[] }`; each image is the rich-text
+* image's own shape (src/alt + media id), so media rewrites and alt audits reach it.
+*
+*   form      V2 article.ts:75-114: Images (a grid list, 2–24, each a required image + caption ≤160), Layout
+*             (Grid | Carousel, segmented). A list of objects → the floating properties panel (D54); a fresh insert opens it.
+*   preview   V2 article-blocks.tsx:451-480: Grid in 2 columns for 2 or 4 images, else 3, square crops; Carousel a
+*             72%-wide scroll-snap row of 4:3 crops with "N images · carousel"; "Add images" when there are none.
+*/
+var GALLERY_LABEL = "Gallery";
+var galleryDefault = () => ({
+	layout: "grid",
+	images: []
+});
+var GALLERY_SCHEMA = {
+	name: "gallery",
+	title: GALLERY_LABEL,
+	kind: "object",
+	icon: "photo",
+	fields: [{
+		name: "images",
+		title: "Images",
+		type: "array",
+		itemNoun: "image",
+		arrayLayout: "grid",
+		validation: {
+			min: 2,
+			max: 24
+		},
+		of: [{
+			name: "photo",
+			title: "Image",
+			type: "object",
+			icon: "photo",
+			preview: {
+				title: "caption",
+				media: "image",
+				fallback: "Untitled image"
+			},
+			fields: [{
+				name: "image",
+				title: "Image",
+				type: "image",
+				validation: { required: true }
+			}, {
+				name: "caption",
+				title: "Caption",
+				type: "string",
+				validation: { max: 160 }
+			}]
+		}]
+	}, {
+		name: "layout",
+		title: "Layout",
+		type: "select",
+		layout: "segmented",
+		initialValue: "grid",
+		options: [{
+			value: "grid",
+			label: "Grid"
+		}, {
+			value: "carousel",
+			label: "Carousel"
+		}]
+	}]
+};
+function GalleryPreview({ m, onAdd, ro }) {
+	const imgs = m.images.filter((x) => x.image?.url);
+	if (!imgs.length) return /* @__PURE__ */ jsx(ArticleEmpty, {
+		icon: /* @__PURE__ */ jsx(IconPhoto, { stroke: 1.5 }),
+		title: GALLERY_LABEL,
+		action: "Add images",
+		onAction: onAdd,
+		ro
+	});
+	if (m.layout === "carousel") return /* @__PURE__ */ jsxs("figure", {
+		className: "m-0",
+		"data-field": "images",
+		children: [/* @__PURE__ */ jsx("ul", {
+			className: "m-0 flex snap-x gap-2 overflow-x-auto p-0 pb-1",
+			"aria-label": GALLERY_LABEL,
+			children: imgs.map((x) => /* @__PURE__ */ jsxs("li", {
+				className: "w-[72%] shrink-0 snap-start list-none",
+				children: [/* @__PURE__ */ jsx("img", {
+					src: x.image.url,
+					alt: x.image.alt ?? "",
+					draggable: false,
+					className: "block aspect-[4/3] w-full rounded-kit-lg border border-kit-line object-cover"
+				}), x.caption ? /* @__PURE__ */ jsx("p", {
+					className: "mt-1 truncate text-kit-xs text-kit-fg-3",
+					children: x.caption
+				}) : null]
+			}, x._key))
+		}), /* @__PURE__ */ jsxs("figcaption", {
+			className: "mt-1 text-kit-2xs text-kit-fg-3",
+			children: [
+				imgs.length,
+				" ",
+				imgs.length === 1 ? "image" : "images",
+				" · carousel"
+			]
+		})]
+	});
+	return /* @__PURE__ */ jsx("figure", {
+		className: "m-0",
+		"data-field": "images",
+		children: /* @__PURE__ */ jsx("ul", {
+			className: cn("m-0 grid gap-2 p-0", imgs.length === 2 || imgs.length === 4 ? "grid-cols-2" : "grid-cols-3"),
+			"aria-label": GALLERY_LABEL,
+			children: imgs.map((x) => /* @__PURE__ */ jsxs("li", {
+				className: "list-none",
+				children: [/* @__PURE__ */ jsx("img", {
+					src: x.image.url,
+					alt: x.image.alt ?? "",
+					draggable: false,
+					className: "block aspect-square w-full rounded-kit-lg border border-kit-line object-cover"
+				}), x.caption ? /* @__PURE__ */ jsx("p", {
+					className: "mt-1 truncate text-kit-xs text-kit-fg-3",
+					children: x.caption
+				}) : null]
+			}, x._key))
+		})
+	});
+}
+var asImages = (v) => Array.isArray(v) ? v.map((x, i) => {
+	const o = x ?? {};
+	return {
+		_key: typeof o._key === "string" ? o._key : `g${i}`,
+		image: o.image ?? null,
+		caption: typeof o.caption === "string" ? o.caption : ""
+	};
+}) : [];
+function GalleryBlock({ m, set, el, ctx, autoFocus }) {
+	return /* @__PURE__ */ jsx(ArticlePanelBlock, {
+		label: GALLERY_LABEL,
+		kind: "gallery",
+		schema: GALLERY_SCHEMA,
+		m,
+		set,
+		el,
+		ctx,
+		autoFocus,
+		toForm: (x) => ({
+			images: x.images,
+			layout: x.layout
+		}),
+		fromForm: (v) => ({
+			images: asImages(v.images),
+			layout: v.layout === "carousel" ? "carousel" : "grid"
+		}),
+		children: (open, ro) => /* @__PURE__ */ jsx(GalleryPreview, {
+			m,
+			onAdd: () => open("images"),
+			ro
+		})
+	});
+}
+//#endregion
+export { GALLERY_LABEL, GALLERY_SCHEMA, GalleryBlock, GalleryPreview, galleryDefault };
+
+//# sourceMappingURL=gallery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gallery.js","names":[],"sources":["../../../src/controls/rich-text/gallery.tsx"],"sourcesContent":["/**\n * RICH TEXT · Gallery (kit-richtext-ui-spec.md §2): V2's article block, stored as the PT block object\n * `{ _type: \"gallery\", layout: \"grid\" | \"carousel\", images: { _key, image, caption? }[] }`; each image is the rich-text\n * image's own shape (src/alt + media id), so media rewrites and alt audits reach it.\n *\n *   form      V2 article.ts:75-114: Images (a grid list, 2–24, each a required image + caption ≤160), Layout\n *             (Grid | Carousel, segmented). A list of objects → the floating properties panel (D54); a fresh insert opens it.\n *   preview   V2 article-blocks.tsx:451-480: Grid in 2 columns for 2 or 4 images, else 3, square crops; Carousel a\n *             72%-wide scroll-snap row of 4:3 crops with \"N images · carousel\"; \"Add images\" when there are none.\n */\nimport { IconPhoto } from \"@tabler/icons-react\";\nimport { cn } from \"../../lib/cn\";\nimport type { TypeSchema } from \"../../schema/types\";\nimport type { ImageValue } from \"../media\";\nimport { ArticleEmpty, ArticlePanelBlock } from \"./article-shell\";\nimport type { IslandCtx } from \"./blocks\";\nimport type { IslandEl } from \"./dom\";\n\nexport interface GalleryImage {\n  _key: string;\n  image: ImageValue | null;\n  caption: string;\n}\nexport interface GalleryModel {\n  layout: \"grid\" | \"carousel\";\n  images: GalleryImage[];\n}\nexport const GALLERY_LABEL = \"Gallery\";\nexport const galleryDefault = (): GalleryModel => ({ layout: \"grid\", images: [] });\n\nexport const GALLERY_SCHEMA: TypeSchema = {\n  name: \"gallery\",\n  title: GALLERY_LABEL,\n  kind: \"object\",\n  icon: \"photo\",\n  fields: [\n    {\n      name: \"images\",\n      title: \"Images\",\n      type: \"array\",\n      itemNoun: \"image\",\n      arrayLayout: \"grid\",\n      validation: { min: 2, max: 24 },\n      of: [\n        {\n          name: \"photo\",\n          title: \"Image\",\n          type: \"object\",\n          icon: \"photo\",\n          preview: { title: \"caption\", media: \"image\", fallback: \"Untitled image\" },\n          fields: [\n            { name: \"image\", title: \"Image\", type: \"image\", validation: { required: true } },\n            { name: \"caption\", title: \"Caption\", type: \"string\", validation: { max: 160 } },\n          ],\n        },\n      ],\n    },\n    {\n      name: \"layout\",\n      title: \"Layout\",\n      type: \"select\",\n      layout: \"segmented\",\n      initialValue: \"grid\",\n      options: [\n        { value: \"grid\", label: \"Grid\" },\n        { value: \"carousel\", label: \"Carousel\" },\n      ],\n    },\n  ],\n};\n\nexport function GalleryPreview({ m, onAdd, ro }: { m: GalleryModel; onAdd: () => void; ro: boolean }) {\n  const imgs = m.images.filter((x) => x.image?.url);\n  if (!imgs.length) return <ArticleEmpty icon={<IconPhoto stroke={1.5} />} title={GALLERY_LABEL} action=\"Add images\" onAction={onAdd} ro={ro} />;\n  if (m.layout === \"carousel\")\n    return (\n      <figure className=\"m-0\" data-field=\"images\">\n        <ul className=\"m-0 flex snap-x gap-2 overflow-x-auto p-0 pb-1\" aria-label={GALLERY_LABEL}>\n          {imgs.map((x) => (\n            <li key={x._key} className=\"w-[72%] shrink-0 snap-start list-none\">\n              <img src={x.image!.url} alt={x.image!.alt ?? \"\"} draggable={false} className=\"block aspect-[4/3] w-full rounded-kit-lg border border-kit-line object-cover\" />\n              {x.caption ? <p className=\"mt-1 truncate text-kit-xs text-kit-fg-3\">{x.caption}</p> : null}\n            </li>\n          ))}\n        </ul>\n        <figcaption className=\"mt-1 text-kit-2xs text-kit-fg-3\">\n          {imgs.length} {imgs.length === 1 ? \"image\" : \"images\"} · carousel\n        </figcaption>\n      </figure>\n    );\n  return (\n    <figure className=\"m-0\" data-field=\"images\">\n      <ul className={cn(\"m-0 grid gap-2 p-0\", imgs.length === 2 || imgs.length === 4 ? \"grid-cols-2\" : \"grid-cols-3\")} aria-label={GALLERY_LABEL}>\n        {imgs.map((x) => (\n          <li key={x._key} className=\"list-none\">\n            <img src={x.image!.url} alt={x.image!.alt ?? \"\"} draggable={false} className=\"block aspect-square w-full rounded-kit-lg border border-kit-line object-cover\" />\n            {x.caption ? <p className=\"mt-1 truncate text-kit-xs text-kit-fg-3\">{x.caption}</p> : null}\n          </li>\n        ))}\n      </ul>\n    </figure>\n  );\n}\n\nconst asImages = (v: unknown): GalleryImage[] =>\n  Array.isArray(v)\n    ? v.map((x, i) => {\n        const o = (x ?? {}) as Record<string, unknown>;\n        return { _key: typeof o._key === \"string\" ? o._key : `g${i}`, image: (o.image as ImageValue | null) ?? null, caption: typeof o.caption === \"string\" ? o.caption : \"\" };\n      })\n    : [];\n\nexport function GalleryBlock({\n  m, set, el, ctx, autoFocus,\n}: {\n  m: GalleryModel;\n  set: (fn: (m: GalleryModel) => GalleryModel, label?: string) => void;\n  el: IslandEl;\n  ctx: IslandCtx;\n  autoFocus: boolean;\n}) {\n  return (\n    <ArticlePanelBlock<GalleryModel>\n      label={GALLERY_LABEL}\n      kind=\"gallery\"\n      schema={GALLERY_SCHEMA}\n      m={m}\n      set={set}\n      el={el}\n      ctx={ctx}\n      autoFocus={autoFocus}\n      toForm={(x) => ({ images: x.images, layout: x.layout })}\n      fromForm={(v) => ({ images: asImages(v.images), layout: v.layout === \"carousel\" ? \"carousel\" : \"grid\" })}\n    >\n      {(open, ro) => <GalleryPreview m={m} onAdd={() => open(\"images\")} ro={ro} />}\n    </ArticlePanelBlock>\n  );\n}\n"],"mappings":"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"}

package/dist/controls/rich-text/link-form.d.ts

@@ -4,10 +4,12 @@ export interface TextLink {
 }
 /** An address a link may carry: http(s), mailto, tel, a site path or an in-page anchor. */
 export declare function linkProblem(href: string): string | null;
-export declare function LinkForm({ initial, allowNewTab, onSave, onCancel, onDetach, }: {
+export declare function LinkForm({ initial, allowNewTab, onSave, onCancel, onDetach, dirty, }: {
     initial: TextLink;
     allowNewTab: boolean;
     onSave: (v: TextLink) => void;
     onCancel: () => void;
     onDetach?: () => void;
+    /** something the host draws beside the form changed (a button's label), so Apply has something to save */
+    dirty?: boolean;
 }): import("react/jsx-runtime").JSX.Element;

package/dist/controls/rich-text/link-form.js

@@ -21,7 +21,7 @@ function linkProblem(href) {
 	if (/^[^\s/]+\.[^\s]+$/.test(h)) return `Add https:// in front: https://${h}`;
 	return "Use a full address (https://…), a page path (/about) or an anchor (#section).";
 }
-function LinkForm({ initial, allowNewTab, onSave, onCancel, onDetach }) {
+function LinkForm({ initial, allowNewTab, onSave, onCancel, onDetach, dirty = false }) {
 	const [href, setHref] = React.useState(initial.href);
 	const [newTab, setNewTab] = React.useState(!!initial.newTab);
 	const [problem, setProblem] = React.useState(null);
@@ -29,7 +29,7 @@ function LinkForm({ initial, allowNewTab, onSave, onCancel, onDetach }) {
 	const tabId = React.useId();
 	const errId = React.useId();
 	const start = initial.href.trim();
-	const changed = href.trim() !== start || allowNewTab && newTab !== !!initial.newTab;
+	const changed = dirty || href.trim() !== start || allowNewTab && newTab !== !!initial.newTab;
 	const ok = !linkProblem(href);
 	return /* @__PURE__ */ jsxs("form", {
 		className: "flex flex-col gap-3",

package/dist/controls/rich-text/link-form.js.map

@@ -1 +1 @@
-{"version":3,"file":"link-form.js","names":[],"sources":["../../../src/controls/rich-text/link-form.tsx"],"sourcesContent":["/**\n * RICH TEXT · the link popover's body for a link inside the text, in V2's link panel chrome (controls/link.tsx\n * LinkPopoverBody: what it links to now · the address · Remove link · Cancel · Apply): the address, and \"Open in new tab\"\n * when the field allows it. A text link stores its address and target only (production's link mark), so V2's link type\n * select and rel choice, which belong to the link FIELD, are not offered here.\n */\nimport * as React from \"react\";\nimport { IconLink } from \"@tabler/icons-react\";\nimport { Button } from \"../../ui/button\";\nimport { Switch } from \"../../ui/controls\";\nimport { Input } from \"../../ui/input\";\nimport { LinkLine, normLink } from \"../link\";\n\nexport interface TextLink {\n  href: string;\n  newTab?: boolean;\n}\n\n/** An address a link may carry: http(s), mailto, tel, a site path or an in-page anchor. */\nexport function linkProblem(href: string): string | null {\n  const h = href.trim();\n  if (!h) return \"Add an address first.\";\n  if (/^(https?:\\/\\/[^\\s]+|mailto:[^\\s]+|tel:[+\\d][\\d\\s()-]*|\\/(?!\\/)[^\\s]*|#[^\\s]+)$/i.test(h)) return null;\n  if (/^[a-z][a-z0-9+.-]*:/i.test(h)) return \"Use an address that starts with https://, mailto: or tel:.\";\n  if (/^[^\\s/]+\\.[^\\s]+$/.test(h)) return `Add https:// in front: https://${h}`;\n  return \"Use a full address (https://…), a page path (/about) or an anchor (#section).\";\n}\n\nexport function LinkForm({\n  initial,\n  allowNewTab,\n  onSave,\n  onCancel,\n  onDetach,\n}: {\n  initial: TextLink;\n  allowNewTab: boolean;\n  onSave: (v: TextLink) => void;\n  onCancel: () => void;\n  onDetach?: () => void;\n}) {\n  const [href, setHref] = React.useState(initial.href);\n  const [newTab, setNewTab] = React.useState(!!initial.newTab);\n  const [problem, setProblem] = React.useState<string | null>(null);\n  const urlId = React.useId();\n  const tabId = React.useId();\n  const errId = React.useId();\n  const start = initial.href.trim();\n  // V2 LinkPopoverBody (controls/link.tsx): Apply only when something changed and the link can be saved\n  const changed = href.trim() !== start || (allowNewTab && newTab !== !!initial.newTab);\n  const ok = !linkProblem(href);\n  return (\n    <form\n      className=\"flex flex-col gap-3\"\n      onSubmit={(e) => {\n        e.preventDefault();\n        const p = linkProblem(href);\n        setProblem(p);\n        if (!p) onSave({ href: href.trim(), newTab: allowNewTab && newTab });\n      }}\n    >\n      <div className=\"flex min-w-0 flex-col gap-1\">\n        <span className=\"text-kit-sm font-medium text-kit-fg\">Link</span>\n        {start ? (\n          <span className=\"flex min-w-0 text-kit-fg-2\">\n            <LinkLine v={normLink({ href: start, newTab: !!initial.newTab })} />\n          </span>\n        ) : (\n          <span className=\"text-kit-xs text-kit-fg-3\">No link yet</span>\n        )}\n      </div>\n      <div\n        className=\"flex flex-col gap-1.5\"\n        onBlur={(e) => {\n          if (!e.currentTarget.contains(e.relatedTarget as Node) && href.trim()) setProblem(linkProblem(href));\n        }}\n      >\n        <label htmlFor={urlId} className=\"text-kit-xs text-kit-fg-2\">\n          Link to\n        </label>\n        <Input\n          id={urlId}\n          autoFocus\n          size=\"sm\"\n          value={href}\n          onChange={(e) => {\n            setHref(e.target.value);\n            if (problem) setProblem(null);\n          }}\n          onKeyDown={(e) => {\n            // Apply is disabled while the address cannot be saved, so Enter says why instead of doing nothing\n            if (e.key === \"Enter\" && !ok) {\n              e.preventDefault();\n              setProblem(linkProblem(href));\n            }\n          }}\n          placeholder=\"https://… or /page\"\n          leading={<IconLink stroke={1.5} />}\n          aria-invalid={problem ? true : undefined}\n          aria-describedby={problem ? errId : undefined}\n        />\n        {problem ? (\n          <p id={errId} role=\"alert\" className=\"text-kit-xs text-kit-danger-fg\">\n            {problem}\n          </p>\n        ) : null}\n      </div>\n      {allowNewTab ? (\n        <label htmlFor={tabId} className=\"flex min-h-7 items-center justify-between gap-3\">\n          <span className=\"text-kit-xs text-kit-fg-2\">Open in new tab</span>\n          <Switch id={tabId} size=\"sm\" checked={newTab} onCheckedChange={setNewTab} />\n        </label>\n      ) : null}\n      <div className=\"flex items-center gap-2 border-t border-kit-line pt-2.5\">\n        {onDetach ? (\n          <Button type=\"button\" size=\"xs\" variant=\"danger-ghost\" onClick={onDetach}>\n            Remove link\n          </Button>\n        ) : null}\n        <span className=\"flex-1\" />\n        <Button type=\"button\" size=\"xs\" variant=\"ghost\" onClick={onCancel}>\n          Cancel\n        </Button>\n        <Button type=\"submit\" size=\"xs\" variant=\"primary\" disabled={!changed || !ok}>\n          Apply\n        </Button>\n      </div>\n    </form>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;AAmBA,SAAgB,YAAY,MAA6B;CACvD,MAAM,IAAI,KAAK,KAAK;CACpB,IAAI,CAAC,GAAG,OAAO;CACf,IAAI,kFAAkF,KAAK,CAAC,GAAG,OAAO;CACtG,IAAI,uBAAuB,KAAK,CAAC,GAAG,OAAO;CAC3C,IAAI,oBAAoB,KAAK,CAAC,GAAG,OAAO,kCAAkC;CAC1E,OAAO;AACT;AAEA,SAAgB,SAAS,EACvB,SACA,aACA,QACA,UACA,YAOC;CACD,MAAM,CAAC,MAAM,WAAW,MAAM,SAAS,QAAQ,IAAI;CACnD,MAAM,CAAC,QAAQ,aAAa,MAAM,SAAS,CAAC,CAAC,QAAQ,MAAM;CAC3D,MAAM,CAAC,SAAS,cAAc,MAAM,SAAwB,IAAI;CAChE,MAAM,QAAQ,MAAM,MAAM;CAC1B,MAAM,QAAQ,MAAM,MAAM;CAC1B,MAAM,QAAQ,MAAM,MAAM;CAC1B,MAAM,QAAQ,QAAQ,KAAK,KAAK;CAEhC,MAAM,UAAU,KAAK,KAAK,MAAM,SAAU,eAAe,WAAW,CAAC,CAAC,QAAQ;CAC9E,MAAM,KAAK,CAAC,YAAY,IAAI;CAC5B,OACE,qBAAC,QAAD;EACE,WAAU;EACV,WAAW,MAAM;GACf,EAAE,eAAe;GACjB,MAAM,IAAI,YAAY,IAAI;GAC1B,WAAW,CAAC;GACZ,IAAI,CAAC,GAAG,OAAO;IAAE,MAAM,KAAK,KAAK;IAAG,QAAQ,eAAe;GAAO,CAAC;EACrE;EAPF,UAAA;GASE,qBAAC,OAAD;IAAK,WAAU;IAAf,UAAA,CACE,oBAAC,QAAD;KAAM,WAAU;KAAsC,UAAA;IAAU,CAAA,GAC/D,QACC,oBAAC,QAAD;KAAM,WAAU;KACd,UAAA,oBAAC,UAAD,EAAU,GAAG,SAAS;MAAE,MAAM;MAAO,QAAQ,CAAC,CAAC,QAAQ;KAAO,CAAC,EAAI,CAAA;IAC/D,CAAA,IAEN,oBAAC,QAAD;KAAM,WAAU;KAA4B,UAAA;IAAiB,CAAA,CAE5D;;GACL,qBAAC,OAAD;IACE,WAAU;IACV,SAAS,MAAM;KACb,IAAI,CAAC,EAAE,cAAc,SAAS,EAAE,aAAqB,KAAK,KAAK,KAAK,GAAG,WAAW,YAAY,IAAI,CAAC;IACrG;IAJF,UAAA;KAME,oBAAC,SAAD;MAAO,SAAS;MAAO,WAAU;MAA4B,UAAA;KAEtD,CAAA;KACP,oBAAC,OAAD;MACE,IAAI;MACJ,WAAA;MACA,MAAK;MACL,OAAO;MACP,WAAW,MAAM;OACf,QAAQ,EAAE,OAAO,KAAK;OACtB,IAAI,SAAS,WAAW,IAAI;MAC9B;MACA,YAAY,MAAM;OAEhB,IAAI,EAAE,QAAQ,WAAW,CAAC,IAAI;QAC5B,EAAE,eAAe;QACjB,WAAW,YAAY,IAAI,CAAC;OAC9B;MACF;MACA,aAAY;MACZ,SAAS,oBAAC,UAAD,EAAU,QAAQ,IAAM,CAAA;MACjC,gBAAc,UAAU,OAAO,KAAA;MAC/B,oBAAkB,UAAU,QAAQ,KAAA;KACrC,CAAA;KACA,UACC,oBAAC,KAAD;MAAG,IAAI;MAAO,MAAK;MAAQ,WAAU;MAClC,UAAA;KACA,CAAA,IACD;IACD;;GACJ,cACC,qBAAC,SAAD;IAAO,SAAS;IAAO,WAAU;IAAjC,UAAA,CACE,oBAAC,QAAD;KAAM,WAAU;KAA4B,UAAA;IAAqB,CAAA,GACjE,oBAAC,QAAD;KAAQ,IAAI;KAAO,MAAK;KAAK,SAAS;KAAQ,iBAAiB;IAAY,CAAA,CACtE;GACL,CAAA,IAAA;GACJ,qBAAC,OAAD;IAAK,WAAU;IAAf,UAAA;KACG,WACC,oBAAC,QAAD;MAAQ,MAAK;MAAS,MAAK;MAAK,SAAQ;MAAe,SAAS;MAAU,UAAA;KAElE,CAAA,IACN;KACJ,oBAAC,QAAD,EAAM,WAAU,SAAU,CAAA;KAC1B,oBAAC,QAAD;MAAQ,MAAK;MAAS,MAAK;MAAK,SAAQ;MAAQ,SAAS;MAAU,UAAA;KAE3D,CAAA;KACR,oBAAC,QAAD;MAAQ,MAAK;MAAS,MAAK;MAAK,SAAQ;MAAU,UAAU,CAAC,WAAW,CAAC;MAAI,UAAA;KAErE,CAAA;IACL;;EACD;;AAEV"}
+{"version":3,"file":"link-form.js","names":[],"sources":["../../../src/controls/rich-text/link-form.tsx"],"sourcesContent":["/**\n * RICH TEXT · the link popover's body for a link inside the text, in V2's link panel chrome (controls/link.tsx\n * LinkPopoverBody: what it links to now · the address · Remove link · Cancel · Apply): the address, and \"Open in new tab\"\n * when the field allows it. A text link stores its address and target only (production's link mark), so V2's link type\n * select and rel choice, which belong to the link FIELD, are not offered here.\n */\nimport * as React from \"react\";\nimport { IconLink } from \"@tabler/icons-react\";\nimport { Button } from \"../../ui/button\";\nimport { Switch } from \"../../ui/controls\";\nimport { Input } from \"../../ui/input\";\nimport { LinkLine, normLink } from \"../link\";\n\nexport interface TextLink {\n  href: string;\n  newTab?: boolean;\n}\n\n/** An address a link may carry: http(s), mailto, tel, a site path or an in-page anchor. */\nexport function linkProblem(href: string): string | null {\n  const h = href.trim();\n  if (!h) return \"Add an address first.\";\n  if (/^(https?:\\/\\/[^\\s]+|mailto:[^\\s]+|tel:[+\\d][\\d\\s()-]*|\\/(?!\\/)[^\\s]*|#[^\\s]+)$/i.test(h)) return null;\n  if (/^[a-z][a-z0-9+.-]*:/i.test(h)) return \"Use an address that starts with https://, mailto: or tel:.\";\n  if (/^[^\\s/]+\\.[^\\s]+$/.test(h)) return `Add https:// in front: https://${h}`;\n  return \"Use a full address (https://…), a page path (/about) or an anchor (#section).\";\n}\n\nexport function LinkForm({\n  initial,\n  allowNewTab,\n  onSave,\n  onCancel,\n  onDetach,\n  dirty = false,\n}: {\n  initial: TextLink;\n  allowNewTab: boolean;\n  onSave: (v: TextLink) => void;\n  onCancel: () => void;\n  onDetach?: () => void;\n  /** something the host draws beside the form changed (a button's label), so Apply has something to save */\n  dirty?: boolean;\n}) {\n  const [href, setHref] = React.useState(initial.href);\n  const [newTab, setNewTab] = React.useState(!!initial.newTab);\n  const [problem, setProblem] = React.useState<string | null>(null);\n  const urlId = React.useId();\n  const tabId = React.useId();\n  const errId = React.useId();\n  const start = initial.href.trim();\n  // V2 LinkPopoverBody (controls/link.tsx): Apply only when something changed and the link can be saved\n  const changed = dirty || href.trim() !== start || (allowNewTab && newTab !== !!initial.newTab);\n  const ok = !linkProblem(href);\n  return (\n    <form\n      className=\"flex flex-col gap-3\"\n      onSubmit={(e) => {\n        e.preventDefault();\n        const p = linkProblem(href);\n        setProblem(p);\n        if (!p) onSave({ href: href.trim(), newTab: allowNewTab && newTab });\n      }}\n    >\n      <div className=\"flex min-w-0 flex-col gap-1\">\n        <span className=\"text-kit-sm font-medium text-kit-fg\">Link</span>\n        {start ? (\n          <span className=\"flex min-w-0 text-kit-fg-2\">\n            <LinkLine v={normLink({ href: start, newTab: !!initial.newTab })} />\n          </span>\n        ) : (\n          <span className=\"text-kit-xs text-kit-fg-3\">No link yet</span>\n        )}\n      </div>\n      <div\n        className=\"flex flex-col gap-1.5\"\n        onBlur={(e) => {\n          if (!e.currentTarget.contains(e.relatedTarget as Node) && href.trim()) setProblem(linkProblem(href));\n        }}\n      >\n        <label htmlFor={urlId} className=\"text-kit-xs text-kit-fg-2\">\n          Link to\n        </label>\n        <Input\n          id={urlId}\n          autoFocus\n          size=\"sm\"\n          value={href}\n          onChange={(e) => {\n            setHref(e.target.value);\n            if (problem) setProblem(null);\n          }}\n          onKeyDown={(e) => {\n            // Apply is disabled while the address cannot be saved, so Enter says why instead of doing nothing\n            if (e.key === \"Enter\" && !ok) {\n              e.preventDefault();\n              setProblem(linkProblem(href));\n            }\n          }}\n          placeholder=\"https://… or /page\"\n          leading={<IconLink stroke={1.5} />}\n          aria-invalid={problem ? true : undefined}\n          aria-describedby={problem ? errId : undefined}\n        />\n        {problem ? (\n          <p id={errId} role=\"alert\" className=\"text-kit-xs text-kit-danger-fg\">\n            {problem}\n          </p>\n        ) : null}\n      </div>\n      {allowNewTab ? (\n        <label htmlFor={tabId} className=\"flex min-h-7 items-center justify-between gap-3\">\n          <span className=\"text-kit-xs text-kit-fg-2\">Open in new tab</span>\n          <Switch id={tabId} size=\"sm\" checked={newTab} onCheckedChange={setNewTab} />\n        </label>\n      ) : null}\n      <div className=\"flex items-center gap-2 border-t border-kit-line pt-2.5\">\n        {onDetach ? (\n          <Button type=\"button\" size=\"xs\" variant=\"danger-ghost\" onClick={onDetach}>\n            Remove link\n          </Button>\n        ) : null}\n        <span className=\"flex-1\" />\n        <Button type=\"button\" size=\"xs\" variant=\"ghost\" onClick={onCancel}>\n          Cancel\n        </Button>\n        <Button type=\"submit\" size=\"xs\" variant=\"primary\" disabled={!changed || !ok}>\n          Apply\n        </Button>\n      </div>\n    </form>\n  );\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,36 @@
+import { type KitRichTextRefRequest } from "../../context";
+import type { TypeSchema } from "../../schema/types";
+import type { IslandCtx } from "./blocks";
+import type { IslandEl } from "./dom";
+export type RelatedMode = "topic" | "newest" | "manual";
+export interface RelatedModel {
+    title: string;
+    mode: RelatedMode;
+    count: number;
+    /** entry ids, Hand-picked only; the PT form wraps each as `{ _key, _ref }` */
+    posts: string[];
+}
+export declare const RELATED_LABEL = "Related posts";
+export declare const relatedDefault: () => RelatedModel;
+/** The panel form; `to` is the field's collection. "How many" explains the chosen automatic mode. */
+export declare const relatedSchema: (to: string[], mode: RelatedMode) => TypeSchema;
+/** What the preview asks the host for: the picked ids, or the automatic mode's query. */
+export declare function relatedRequest(m: RelatedModel, collection?: string, excludeId?: string): KitRichTextRefRequest | null;
+export declare function RelatedPreview({ m, onPick, ro, collection, excludeId }: {
+    m: RelatedModel;
+    onPick: () => void;
+    ro: boolean;
+    collection?: string;
+    excludeId?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function RelatedBlock({ m, set, el, ctx, autoFocus, collection, excludeId, }: {
+    m: RelatedModel;
+    set: (fn: (m: RelatedModel) => RelatedModel, label?: string) => void;
+    el: IslandEl;
+    ctx: IslandCtx;
+    autoFocus: boolean;
+    /** the posts collection (the field's config) */
+    collection: string;
+    /** the entry being edited, left out of the automatic modes */
+    excludeId?: string;
+}): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,213 @@
+import { useRichTextRefs } from "../../context.js";
+import { ArticleEmpty, ArticlePanelBlock } from "./article-shell.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { IconPlus } from "@tabler/icons-react";
+//#region src/controls/rich-text/related.tsx
+/**
+* RICH TEXT · Related posts (kit-richtext-ui-spec.md §6): V2's article block, stored as the PT block object
+* `{ _type: "relatedPosts", title?, mode, count, posts: { _ref }[] }`. Each post's title, cover, category and URL are
+* derived from the referenced or queried entries, never stored.
+*
+*   modes     e1 2026-10-24 (signed deviation from V2's Automatic | Hand-picked): Same topic (topic) · Newest (newest) ·
+*             Hand-picked (manual). "How many" shows for the two automatic modes, Posts for Hand-picked. The schema's
+*             `hidden` is "show only when" (schema/types.ts), as V2's was.
+*   form      V2 article.ts:167-195: Title (≤40, default "Related stories"), Stories (segmented), How many (1–6),
+*             Posts (1–6 unique references to the field's collection). Four settings → the floating panel (D54).
+*   preview   V2 article-blocks.tsx:572-597: the title with the automatic mode's tag, three post cards (4:3 cover,
+*             two-line title, category); "Pick stories" when Hand-picked holds nothing that resolves.
+*   data      KitServices.resolveRichTextRefs (useRichTextRefs): ids for Hand-picked, a query for the automatic modes.
+*             A fresh insert focuses the card (V2 article-blocks.tsx:131).
+*/
+var RELATED_LABEL = "Related posts";
+var relatedDefault = () => ({
+	title: "Related stories",
+	mode: "topic",
+	count: 3,
+	posts: []
+});
+var MODE_TAG = {
+	topic: "Same topic",
+	newest: "Newest"
+};
+var asMode = (v) => v === "newest" || v === "manual" ? v : "topic";
+var clampCount = (v) => Math.min(6, Math.max(1, Math.round(Number(v) || 3)));
+/** The panel form; `to` is the field's collection. "How many" explains the chosen automatic mode. */
+var relatedSchema = (to, mode) => ({
+	name: "relatedPosts",
+	title: RELATED_LABEL,
+	kind: "object",
+	icon: "news",
+	fields: [
+		{
+			name: "title",
+			title: "Title",
+			type: "string",
+			validation: { max: 40 }
+		},
+		{
+			name: "mode",
+			title: "Stories",
+			type: "select",
+			layout: "segmented",
+			initialValue: "topic",
+			options: [
+				{
+					value: "topic",
+					label: "Same topic"
+				},
+				{
+					value: "newest",
+					label: "Newest"
+				},
+				{
+					value: "manual",
+					label: "Hand-picked"
+				}
+			]
+		},
+		{
+			name: "count",
+			title: "How many",
+			type: "number",
+			hidden: {
+				field: "mode",
+				op: "in",
+				value: ["topic", "newest"]
+			},
+			numeric: {
+				min: 1,
+				max: 6,
+				step: 1
+			},
+			description: mode === "newest" ? "Newest first." : "Same topic, newest first."
+		},
+		{
+			name: "posts",
+			title: "Posts",
+			type: "array",
+			hidden: {
+				field: "mode",
+				equals: "manual"
+			},
+			validation: {
+				min: 1,
+				max: 6,
+				unique: true
+			},
+			of: [{
+				name: "post",
+				title: "Post",
+				type: "reference",
+				reference: { to }
+			}]
+		}
+	]
+});
+/** What the preview asks the host for: the picked ids, or the automatic mode's query. */
+function relatedRequest(m, collection, excludeId) {
+	if (m.mode === "manual") return m.posts.length ? {
+		kind: "relatedPosts",
+		ids: m.posts
+	} : null;
+	return {
+		kind: "relatedPosts",
+		query: {
+			collection,
+			mode: m.mode,
+			count: m.count,
+			excludeId
+		}
+	};
+}
+function RelatedPreview({ m, onPick, ro, collection, excludeId }) {
+	const { items, loading, error } = useRichTextRefs(relatedRequest(m, collection, excludeId));
+	const posts = m.mode === "manual" ? m.posts.map((id) => items.find((x) => x.id === id)).filter((x) => !!x) : items;
+	if (m.mode === "manual" && !loading && !error && !posts.length) return /* @__PURE__ */ jsx(ArticleEmpty, {
+		icon: /* @__PURE__ */ jsx(IconPlus, { stroke: 1.5 }),
+		title: m.title || "Related posts",
+		action: "Pick stories",
+		onAction: onPick,
+		ro
+	});
+	return /* @__PURE__ */ jsxs("aside", {
+		className: "rounded-kit-lg border border-kit-line bg-kit-surface px-4 py-3",
+		"aria-label": m.title || "Related posts",
+		"aria-busy": loading || void 0,
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "mb-2 flex items-baseline gap-2",
+			children: [m.title ? /* @__PURE__ */ jsx("p", {
+				"data-field": "title",
+				className: "text-kit-sm font-semibold text-kit-fg",
+				children: m.title
+			}) : null, m.mode !== "manual" ? /* @__PURE__ */ jsx("span", {
+				"data-field": "mode",
+				className: "text-kit-2xs text-kit-fg-3",
+				children: MODE_TAG[m.mode]
+			}) : null]
+		}), error ? /* @__PURE__ */ jsxs("p", {
+			role: "status",
+			className: "text-kit-sm text-kit-warning-fg",
+			children: ["The stories couldn't load: ", error]
+		}) : /* @__PURE__ */ jsx("ul", {
+			className: "m-0 grid grid-cols-3 gap-3 p-0",
+			"data-field": m.mode === "manual" ? "posts" : "count",
+			children: posts.map((e) => /* @__PURE__ */ jsxs("li", {
+				className: "min-w-0 list-none",
+				children: [
+					e.cover ? /* @__PURE__ */ jsx("img", {
+						src: e.cover,
+						alt: "",
+						draggable: false,
+						className: "block aspect-[4/3] w-full rounded-kit-md border border-kit-line object-cover"
+					}) : /* @__PURE__ */ jsx("div", { className: "aspect-[4/3] rounded-kit-md bg-kit-muted" }),
+					/* @__PURE__ */ jsx("p", {
+						className: "mt-1.5 line-clamp-2 text-kit-xs font-medium leading-snug text-kit-fg",
+						children: e.title
+					}),
+					e.category ? /* @__PURE__ */ jsx("p", {
+						className: "mt-0.5 truncate text-kit-2xs text-kit-fg-3",
+						children: e.category
+					}) : null
+				]
+			}, e.id))
+		})]
+	});
+}
+function RelatedBlock({ m, set, el, ctx, autoFocus, collection, excludeId }) {
+	const schema = React.useMemo(() => relatedSchema([collection], m.mode), [collection, m.mode]);
+	return /* @__PURE__ */ jsx(ArticlePanelBlock, {
+		label: RELATED_LABEL,
+		kind: "related",
+		schema,
+		m,
+		set,
+		el,
+		ctx,
+		autoFocus,
+		openOnInsert: false,
+		toForm: (x) => ({
+			title: x.title,
+			mode: x.mode,
+			count: x.count,
+			posts: x.posts
+		}),
+		fromForm: (v) => ({
+			title: String(v.title ?? ""),
+			mode: asMode(v.mode),
+			count: clampCount(v.count),
+			posts: Array.isArray(v.posts) ? v.posts.filter((x) => typeof x === "string") : []
+		}),
+		children: (open, ro) => /* @__PURE__ */ jsx(RelatedPreview, {
+			m,
+			onPick: () => open("posts"),
+			ro,
+			collection,
+			excludeId
+		})
+	});
+}
+//#endregion
+export { RELATED_LABEL, RelatedBlock, RelatedPreview, relatedDefault, relatedRequest, relatedSchema };
+
+//# sourceMappingURL=related.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"related.js","names":[],"sources":["../../../src/controls/rich-text/related.tsx"],"sourcesContent":["/**\n * RICH TEXT · Related posts (kit-richtext-ui-spec.md §6): V2's article block, stored as the PT block object\n * `{ _type: \"relatedPosts\", title?, mode, count, posts: { _ref }[] }`. Each post's title, cover, category and URL are\n * derived from the referenced or queried entries, never stored.\n *\n *   modes     e1 2026-10-24 (signed deviation from V2's Automatic | Hand-picked): Same topic (topic) · Newest (newest) ·\n *             Hand-picked (manual). \"How many\" shows for the two automatic modes, Posts for Hand-picked. The schema's\n *             `hidden` is \"show only when\" (schema/types.ts), as V2's was.\n *   form      V2 article.ts:167-195: Title (≤40, default \"Related stories\"), Stories (segmented), How many (1–6),\n *             Posts (1–6 unique references to the field's collection). Four settings → the floating panel (D54).\n *   preview   V2 article-blocks.tsx:572-597: the title with the automatic mode's tag, three post cards (4:3 cover,\n *             two-line title, category); \"Pick stories\" when Hand-picked holds nothing that resolves.\n *   data      KitServices.resolveRichTextRefs (useRichTextRefs): ids for Hand-picked, a query for the automatic modes.\n *             A fresh insert focuses the card (V2 article-blocks.tsx:131).\n */\nimport * as React from \"react\";\nimport { IconPlus } from \"@tabler/icons-react\";\nimport { useRichTextRefs, type KitRichTextRefRequest } from \"../../context\";\nimport type { TypeSchema } from \"../../schema/types\";\nimport { ArticleEmpty, ArticlePanelBlock } from \"./article-shell\";\nimport type { IslandCtx } from \"./blocks\";\nimport type { IslandEl } from \"./dom\";\n\nexport type RelatedMode = \"topic\" | \"newest\" | \"manual\";\nexport interface RelatedModel {\n  title: string;\n  mode: RelatedMode;\n  count: number;\n  /** entry ids, Hand-picked only; the PT form wraps each as `{ _key, _ref }` */\n  posts: string[];\n}\nexport const RELATED_LABEL = \"Related posts\";\nexport const relatedDefault = (): RelatedModel => ({ title: \"Related stories\", mode: \"topic\", count: 3, posts: [] });\nconst MODE_TAG: Record<Exclude<RelatedMode, \"manual\">, string> = { topic: \"Same topic\", newest: \"Newest\" };\nconst asMode = (v: unknown): RelatedMode => (v === \"newest\" || v === \"manual\" ? v : \"topic\");\nconst clampCount = (v: unknown) => Math.min(6, Math.max(1, Math.round(Number(v) || 3)));\n\n/** The panel form; `to` is the field's collection. \"How many\" explains the chosen automatic mode. */\nexport const relatedSchema = (to: string[], mode: RelatedMode): TypeSchema => ({\n  name: \"relatedPosts\",\n  title: RELATED_LABEL,\n  kind: \"object\",\n  icon: \"news\",\n  fields: [\n    { name: \"title\", title: \"Title\", type: \"string\", validation: { max: 40 } },\n    {\n      name: \"mode\",\n      title: \"Stories\",\n      type: \"select\",\n      layout: \"segmented\",\n      initialValue: \"topic\",\n      options: [\n        { value: \"topic\", label: \"Same topic\" },\n        { value: \"newest\", label: \"Newest\" },\n        { value: \"manual\", label: \"Hand-picked\" },\n      ],\n    },\n    {\n      name: \"count\",\n      title: \"How many\",\n      type: \"number\",\n      hidden: { field: \"mode\", op: \"in\", value: [\"topic\", \"newest\"] },\n      numeric: { min: 1, max: 6, step: 1 },\n      description: mode === \"newest\" ? \"Newest first.\" : \"Same topic, newest first.\",\n    },\n    {\n      name: \"posts\",\n      title: \"Posts\",\n      type: \"array\",\n      hidden: { field: \"mode\", equals: \"manual\" },\n      validation: { min: 1, max: 6, unique: true },\n      of: [{ name: \"post\", title: \"Post\", type: \"reference\", reference: { to } }],\n    },\n  ],\n});\n\n/** What the preview asks the host for: the picked ids, or the automatic mode's query. */\nexport function relatedRequest(m: RelatedModel, collection?: string, excludeId?: string): KitRichTextRefRequest | null {\n  if (m.mode === \"manual\") return m.posts.length ? { kind: \"relatedPosts\", ids: m.posts } : null;\n  return { kind: \"relatedPosts\", query: { collection, mode: m.mode, count: m.count, excludeId } };\n}\n\nexport function RelatedPreview({ m, onPick, ro, collection, excludeId }: { m: RelatedModel; onPick: () => void; ro: boolean; collection?: string; excludeId?: string }) {\n  const { items, loading, error } = useRichTextRefs(relatedRequest(m, collection, excludeId));\n  // Hand-picked keeps the picked order; a post that no longer resolves is skipped (V2 .filter)\n  const posts = m.mode === \"manual\" ? m.posts.map((id) => items.find((x) => x.id === id)).filter((x): x is NonNullable<typeof x> => !!x) : items;\n  if (m.mode === \"manual\" && !loading && !error && !posts.length)\n    return <ArticleEmpty icon={<IconPlus stroke={1.5} />} title={m.title || RELATED_LABEL} action=\"Pick stories\" onAction={onPick} ro={ro} />;\n  return (\n    <aside className=\"rounded-kit-lg border border-kit-line bg-kit-surface px-4 py-3\" aria-label={m.title || RELATED_LABEL} aria-busy={loading || undefined}>\n      <div className=\"mb-2 flex items-baseline gap-2\">\n        {m.title ? (\n          <p data-field=\"title\" className=\"text-kit-sm font-semibold text-kit-fg\">\n            {m.title}\n          </p>\n        ) : null}\n        {m.mode !== \"manual\" ? (\n          <span data-field=\"mode\" className=\"text-kit-2xs text-kit-fg-3\">\n            {MODE_TAG[m.mode]}\n          </span>\n        ) : null}\n      </div>\n      {error ? (\n        <p role=\"status\" className=\"text-kit-sm text-kit-warning-fg\">\n          The stories couldn't load: {error}\n        </p>\n      ) : (\n        <ul className=\"m-0 grid grid-cols-3 gap-3 p-0\" data-field={m.mode === \"manual\" ? \"posts\" : \"count\"}>\n          {posts.map((e) => (\n            <li key={e.id} className=\"min-w-0 list-none\">\n              {e.cover ? (\n                <img src={e.cover} alt=\"\" draggable={false} className=\"block aspect-[4/3] w-full rounded-kit-md border border-kit-line object-cover\" />\n              ) : (\n                <div className=\"aspect-[4/3] rounded-kit-md bg-kit-muted\" />\n              )}\n              <p className=\"mt-1.5 line-clamp-2 text-kit-xs font-medium leading-snug text-kit-fg\">{e.title}</p>\n              {e.category ? <p className=\"mt-0.5 truncate text-kit-2xs text-kit-fg-3\">{e.category}</p> : null}\n            </li>\n          ))}\n        </ul>\n      )}\n    </aside>\n  );\n}\n\nexport function RelatedBlock({\n  m, set, el, ctx, autoFocus, collection, excludeId,\n}: {\n  m: RelatedModel;\n  set: (fn: (m: RelatedModel) => RelatedModel, label?: string) => void;\n  el: IslandEl;\n  ctx: IslandCtx;\n  autoFocus: boolean;\n  /** the posts collection (the field's config) */\n  collection: string;\n  /** the entry being edited, left out of the automatic modes */\n  excludeId?: string;\n}) {\n  const schema = React.useMemo(() => relatedSchema([collection], m.mode), [collection, m.mode]);\n  return (\n    <ArticlePanelBlock<RelatedModel>\n      label={RELATED_LABEL}\n      kind=\"related\"\n      schema={schema}\n      m={m}\n      set={set}\n      el={el}\n      ctx={ctx}\n      autoFocus={autoFocus}\n      openOnInsert={false}\n      toForm={(x) => ({ title: x.title, mode: x.mode, count: x.count, posts: x.posts })}\n      fromForm={(v) => ({\n        title: String(v.title ?? \"\"),\n        mode: asMode(v.mode),\n        count: clampCount(v.count),\n        posts: Array.isArray(v.posts) ? v.posts.filter((x): x is string => typeof x === \"string\") : [],\n      })}\n    >\n      {(open, ro) => <RelatedPreview m={m} onPick={() => open(\"posts\")} ro={ro} collection={collection} excludeId={excludeId} />}\n    </ArticlePanelBlock>\n  );\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,46 @@
+import type { TypeSchema } from "../../schema/types";
+import type { IslandCtx } from "./blocks";
+import { type IslandEl } from "./dom";
+export interface TocModel {
+    title: string;
+    depth: "2" | "3";
+}
+export declare const TOC_LABEL = "Table of contents";
+export declare const tocDefault: () => TocModel;
+/** The popover form (V2 ARTICLE_SCHEMAS.toc). Two settings → the shell's popover (D54). */
+export declare const TOC_SCHEMA: TypeSchema;
+export interface OutlineItem {
+    id: string;
+    text: string;
+    depth: 2 | 3;
+}
+/** V2 article.ts:250-251. ponytail: richtext's one slugify replaces this when it lands (plan RT5); it must stay equal. */
+export declare const slugify: (s: string) => string;
+/** The body's H2 and H3, top level only, in order, with stable de-duplicated ids. */
+export declare function outlineOf(root: ParentNode): OutlineItem[];
+export declare const tocVisible: (outline: OutlineItem[], depth: TocModel["depth"]) => OutlineItem[];
+/** One live outline per editor: the editor sets it after each input, every TOC preview subscribes. */
+export interface OutlineStore {
+    get: () => OutlineItem[];
+    subscribe: (fn: () => void) => () => void;
+    set: (next: OutlineItem[]) => void;
+}
+export declare function createOutlineStore(): OutlineStore;
+export declare const NO_OUTLINE: OutlineStore;
+/** `host` is the TOC's island element; its parent is the editor surface whose headings it lists. */
+export declare function TocPreview({ m, outline, host }: {
+    m: TocModel;
+    outline: OutlineStore;
+    host: HTMLElement;
+}): import("react/jsx-runtime").JSX.Element;
+export interface TocBlockProps {
+    m: TocModel;
+    set: (fn: (m: TocModel) => TocModel, label?: string) => void;
+    el: IslandEl;
+    /** the editor's live outline rides the island context */
+    ctx: IslandCtx & {
+        outline?: OutlineStore;
+    };
+    autoFocus: boolean;
+}
+export declare function TocBlock({ m, set, el, ctx, autoFocus }: TocBlockProps): import("react/jsx-runtime").JSX.Element;