@bettercms-ai/kit 0.1.0 → 1.0.0

package/controls/code.js

@@ -0,0 +1,396 @@
+import { cn } from "../lib/cn.js";
+import { isObj } from "../lib/path.js";
+import { CODE_MAX_LENGTH } from "../adapters/prod-types.js";
+import { useKitEnv, useKitServices } from "../context.js";
+import { Button } from "../ui/button.js";
+import { Modal, ModalBody, ModalContent, ModalFooter, ModalHeader } from "../ui/overlay.js";
+import { Select } from "../ui/select.js";
+import * as React from "react";
+import { IconAlertTriangle, IconBraces, IconCode, IconMaximize } from "@tabler/icons-react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/kit/controls/code.tsx
+/**
+* CODE — the code field (DESIGN 8.21), V2 controls/misc.tsx (CodeSurface, CodeControl) fitted to what prod stores.
+*
+* Values (backend reference-validation `code`, adapters/values.ts codeToProd):
+*   "<p>hi</p>"                         a bare string, kept a string
+*   { language?: "html", code: "…" }    the object form; only `code` and `language` are written back
+* The language list sits in the surface header. Picking one writes the object form; a value that never changes its
+* language keeps the shape it was stored in. A value over CODE_MAX_LENGTH characters is refused with the reason.
+*
+* Panel: a one-line summary button that opens a `lg` dialog editing a draft (Cancel / Done). Document: the surface
+* inline. The surface: mono 12/20 textarea with line numbers, Tab inserts two spaces (Shift+Tab leaves the field),
+* Copy, and for JSON a Format action and a live "Invalid JSON · {reason}" footer (json.tsx).
+*/
+var CODE_LANGUAGES = [
+	{
+		value: "html",
+		label: "HTML"
+	},
+	{
+		value: "css",
+		label: "CSS"
+	},
+	{
+		value: "js",
+		label: "JS"
+	},
+	{
+		value: "ts",
+		label: "TS"
+	},
+	{
+		value: "json",
+		label: "JSON"
+	},
+	{
+		value: "liquid",
+		label: "Liquid"
+	},
+	{
+		value: "markdown",
+		label: "Markdown"
+	},
+	{
+		value: "shell",
+		label: "Shell"
+	}
+];
+var PLAIN = "plain";
+/** The picker: Plain text, then the field's allowed languages (or the built-in list), then the stored one if it is outside them. */
+function languageOptions(language, allowed) {
+	const list = allowed ? allowed.map((v) => CODE_LANGUAGES.find((l) => l.value === v) ?? {
+		value: v,
+		label: v
+	}) : CODE_LANGUAGES;
+	return [
+		{
+			value: PLAIN,
+			label: "Plain text"
+		},
+		...list,
+		...language && !list.some((l) => l.value === language) ? [{
+			value: language,
+			label: language
+		}] : []
+	];
+}
+/** Why a JSON text does not parse ("" when it does, or is empty). */
+function jsonProblem(text) {
+	if (!text.trim()) return "";
+	try {
+		JSON.parse(text);
+		return "";
+	} catch (e) {
+		return e.message.replace(/^JSON\.parse: /, "");
+	}
+}
+function CodeSurface({ kind, value, onChange, language, onLanguage, languages, readOnly, id, invalid, minRows = 8, label, describedBy }) {
+	const { toast } = useKitServices();
+	const lines = Math.max(minRows, value.split("\n").length);
+	const problem = kind === "json" ? jsonProblem(value) : value.length > 1e5 ? `Code can hold up to ${CODE_MAX_LENGTH.toLocaleString("en-US")} characters; this has ${value.length.toLocaleString("en-US")}.` : "";
+	const footerId = id ? `${id}-problem` : void 0;
+	const format = () => {
+		try {
+			onChange(JSON.stringify(JSON.parse(value), null, 2));
+			toast?.success("JSON formatted");
+		} catch {
+			toast?.("Fix the JSON before formatting");
+		}
+	};
+	const copy = () => {
+		navigator.clipboard?.writeText(value);
+		toast?.success("Copied");
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: cn("overflow-hidden rounded-kit-lg border bg-kit-subtle transition-colors", invalid || problem ? "border-[var(--kit-field-invalid)]" : "border-kit-line focus-within:border-kit-field-border-focus"),
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex h-8 items-center justify-between border-b border-kit-line px-2",
+				children: [kind === "json" ? /* @__PURE__ */ jsx("span", {
+					className: "px-1 font-kit-mono text-kit-xs text-kit-fg-3",
+					children: "JSON"
+				}) : onLanguage ? /* @__PURE__ */ jsx(Select, {
+					"aria-label": "Code language",
+					size: "sm",
+					variant: "ghost",
+					disabled: readOnly,
+					value: language || PLAIN,
+					onValueChange: (l) => onLanguage(l === PLAIN ? "" : l),
+					options: languageOptions(language, languages)
+				}) : /* @__PURE__ */ jsx("span", {
+					className: "px-1 font-kit-mono text-kit-xs text-kit-fg-3",
+					children: "Code"
+				}), /* @__PURE__ */ jsxs("div", {
+					className: "flex items-center gap-1",
+					children: [kind === "json" ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						disabled: readOnly,
+						className: "rounded-kit-md px-1.5 py-0.5 text-kit-xs text-kit-fg-2 hover:bg-kit-hover hover:text-kit-fg disabled:opacity-50",
+						onClick: format,
+						children: "Format"
+					}) : null, /* @__PURE__ */ jsx("button", {
+						type: "button",
+						className: "rounded-kit-md px-1.5 py-0.5 text-kit-xs text-kit-fg-2 hover:bg-kit-hover hover:text-kit-fg",
+						onClick: copy,
+						children: "Copy"
+					})]
+				})]
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex max-h-[60vh] overflow-auto font-kit-mono text-kit-xs leading-5",
+				children: [/* @__PURE__ */ jsx("div", {
+					"aria-hidden": true,
+					className: "select-none border-r border-kit-line bg-kit-subtle px-2 py-2 text-right text-kit-fg-4",
+					children: Array.from({ length: lines }).map((_, i) => /* @__PURE__ */ jsx("div", { children: i + 1 }, i))
+				}), /* @__PURE__ */ jsx("textarea", {
+					id,
+					spellCheck: false,
+					autoCapitalize: "off",
+					autoCorrect: "off",
+					value,
+					readOnly,
+					"aria-invalid": invalid || !!problem || void 0,
+					"aria-label": label,
+					"aria-describedby": [describedBy, problem ? footerId : void 0].filter(Boolean).join(" ") || void 0,
+					onChange: (e) => onChange(e.target.value),
+					onKeyDown: (e) => {
+						if (e.key === "Tab" && !e.shiftKey && !readOnly) {
+							e.preventDefault();
+							const el = e.currentTarget;
+							const s = el.selectionStart;
+							onChange(value.slice(0, s) + "  " + value.slice(el.selectionEnd));
+							requestAnimationFrame(() => el.setSelectionRange(s + 2, s + 2));
+						}
+					},
+					style: { height: lines * 20 + 16 },
+					className: "min-w-0 flex-1 resize-none bg-kit-field-bg px-3 py-2 text-kit-fg outline-none"
+				})]
+			}),
+			problem ? /* @__PURE__ */ jsx("div", {
+				id: footerId,
+				className: "border-t border-kit-danger-line bg-kit-danger-soft px-3 py-1.5 text-kit-xs text-kit-danger-fg",
+				children: kind === "json" ? `Invalid JSON · ${problem}` : problem
+			}) : null
+		]
+	});
+}
+function CodeDialogField({ kind, title, description, text, readOnly, id, invalid, language, languages, onDone }) {
+	const { toast } = useKitServices();
+	const [open, setOpen] = React.useState(false);
+	const [draft, setDraft] = React.useState(text);
+	const [lang, setLang] = React.useState(language);
+	const [refusal, setRefusal] = React.useState(null);
+	const first = text.split("\n").find((l) => l.trim()) ?? "";
+	const Icon = kind === "json" ? IconBraces : IconCode;
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsxs("button", {
+		id,
+		type: "button",
+		"aria-haspopup": "dialog",
+		"aria-invalid": invalid || void 0,
+		onClick: () => {
+			setDraft(text);
+			setLang(language);
+			setRefusal(null);
+			setOpen(true);
+		},
+		className: cn("group/code flex w-full min-w-0 items-center gap-2 rounded-kit-md border bg-kit-subtle px-2.5 py-2 text-left outline-none transition-colors hover:border-kit-line-strong focus-visible:outline-2 focus-visible:outline-kit-focus-ring", invalid ? "border-[var(--kit-field-invalid)]" : "border-kit-line"),
+		children: [
+			/* @__PURE__ */ jsx(Icon, {
+				className: "size-4 shrink-0 text-kit-fg-3",
+				stroke: 1.5,
+				"aria-hidden": true
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: cn("min-w-0 flex-1 truncate font-kit-mono text-kit-xs", first ? "text-kit-fg-2" : "text-kit-fg-3"),
+				children: first || "Empty"
+			}),
+			/* @__PURE__ */ jsx("span", {
+				className: "shrink-0 text-kit-2xs tabular-nums text-kit-fg-3",
+				children: text ? `${text.split("\n").length} lines` : ""
+			}),
+			/* @__PURE__ */ jsx(IconMaximize, {
+				className: "size-3.5 shrink-0 text-kit-fg-3 group-hover/code:text-kit-fg",
+				stroke: 1.5,
+				"aria-hidden": true
+			})
+		]
+	}), /* @__PURE__ */ jsx(Modal, {
+		open,
+		onOpenChange: setOpen,
+		children: /* @__PURE__ */ jsxs(ModalContent, {
+			size: "lg",
+			children: [
+				/* @__PURE__ */ jsx(ModalHeader, {
+					title,
+					description: description ?? (kind === "json" ? "Structured data for developers" : "Custom code")
+				}),
+				/* @__PURE__ */ jsxs(ModalBody, { children: [/* @__PURE__ */ jsx(CodeSurface, {
+					kind,
+					value: draft,
+					onChange: setDraft,
+					language: lang ?? "",
+					onLanguage: kind === "code" ? setLang : void 0,
+					languages,
+					readOnly,
+					minRows: 14,
+					label: title
+				}), refusal ? /* @__PURE__ */ jsxs("p", {
+					role: "alert",
+					className: "mt-2 flex items-start gap-1.5 text-kit-xs text-kit-danger-fg",
+					children: [/* @__PURE__ */ jsx(IconAlertTriangle, {
+						className: "mt-0.5 size-3.5 shrink-0",
+						stroke: 1.5,
+						"aria-hidden": true
+					}), refusal]
+				}) : null] }),
+				/* @__PURE__ */ jsxs(ModalFooter, { children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "text-kit-xs text-kit-fg-3",
+						children: "Esc to close"
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: "mr-auto",
+						"aria-hidden": true
+					}),
+					/* @__PURE__ */ jsx(Button, {
+						variant: "ghost",
+						onClick: () => setOpen(false),
+						children: "Cancel"
+					}),
+					/* @__PURE__ */ jsx(Button, {
+						variant: "primary",
+						disabled: readOnly,
+						onClick: () => {
+							const why = onDone(draft, lang);
+							if (why) {
+								setRefusal(why);
+								toast?.(kind === "json" ? "Invalid JSON" : "Can't save this code", { description: "Fix it before saving." });
+								return;
+							}
+							setOpen(false);
+						},
+						children: "Done"
+					})
+				] })
+			]
+		})
+	})] });
+}
+function readCode(v) {
+	if (v == null) return {
+		ok: true,
+		code: "",
+		object: false
+	};
+	if (typeof v === "string") return {
+		ok: true,
+		code: v,
+		object: false
+	};
+	if (isObj(v) && typeof v.code === "string" && (v.language === void 0 || typeof v.language === "string")) return {
+		ok: true,
+		code: v.code,
+		language: v.language,
+		object: true
+	};
+	return { ok: false };
+}
+/** The stored shape for edited code: a string stays a string until a language is picked; the object keeps its form. */
+function codeValue(prev, code, language) {
+	const lang = language ?? prev.language ?? "";
+	if (!prev.object && !lang) return code;
+	return lang ? {
+		language: lang,
+		code
+	} : { code };
+}
+var tooLong = (code) => code.length > 1e5 ? `Code can hold up to ${CODE_MAX_LENGTH.toLocaleString("en-US")} characters; this has ${code.length.toLocaleString("en-US")}.` : null;
+function CodeControl({ field, value, onChange, readOnly, id, invalid }) {
+	const { variant } = useKitEnv();
+	const [refused, setRefused] = React.useState(null);
+	const read = readCode(value);
+	if (!read.ok) return /* @__PURE__ */ jsx(UnreadableValue, {
+		id,
+		title: field.title,
+		kind: "code",
+		value
+	});
+	if (variant === "document") return /* @__PURE__ */ jsxs("div", {
+		className: "flex flex-col gap-1.5",
+		children: [/* @__PURE__ */ jsx(CodeSurface, {
+			kind: "code",
+			id,
+			invalid: invalid || !!refused,
+			readOnly,
+			value: read.code,
+			language: read.language ?? "",
+			languages: field.languages,
+			onChange: (code) => {
+				const why = tooLong(code);
+				setRefused(why);
+				if (!why) onChange(codeValue(read, code, void 0));
+			},
+			onLanguage: (l) => onChange(codeValue(read, read.code, l))
+		}), refused ? /* @__PURE__ */ jsx("p", {
+			role: "alert",
+			className: "text-kit-xs text-kit-danger-fg",
+			children: refused
+		}) : null]
+	});
+	return /* @__PURE__ */ jsx(CodeDialogField, {
+		kind: "code",
+		id,
+		title: field.title,
+		description: field.description || void 0,
+		text: read.code,
+		language: read.language,
+		languages: field.languages,
+		readOnly,
+		invalid,
+		onDone: (draft, lang) => {
+			const why = tooLong(draft);
+			if (why) return why;
+			const next = codeValue(read, draft, lang);
+			if (draft !== read.code || (lang ?? "") !== (read.language ?? "")) onChange(next);
+			return null;
+		}
+	});
+}
+/** A stored value the control cannot read: named, shown, kept as it is (never replaced by a stray edit). */
+function UnreadableValue({ id, title, kind, value }) {
+	let raw;
+	try {
+		raw = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+	} catch {
+		raw = String(value);
+	}
+	return /* @__PURE__ */ jsxs("output", {
+		id,
+		tabIndex: 0,
+		"data-slot": `${kind}-unreadable`,
+		className: "flex min-w-0 items-start gap-2 rounded-kit-md border border-dashed border-kit-line-strong bg-kit-subtle px-2.5 py-2 text-kit-xs text-kit-fg-2 outline-none focus-visible:outline-2 focus-visible:outline-kit-focus-ring",
+		children: [/* @__PURE__ */ jsx(IconAlertTriangle, {
+			className: "mt-0.5 size-3.5 shrink-0 text-kit-warning-fg",
+			stroke: 1.5,
+			"aria-hidden": true
+		}), /* @__PURE__ */ jsxs("span", {
+			className: "min-w-0",
+			children: [
+				title,
+				" holds a value this ",
+				kind,
+				" editor can't read, so it is kept as it is:",
+				" ",
+				/* @__PURE__ */ jsx("span", {
+					className: "block max-h-24 overflow-auto whitespace-pre-wrap break-all font-kit-mono text-kit-fg",
+					children: raw
+				})
+			]
+		})]
+	});
+}
+//#endregion
+export { CodeControl, CodeDialogField, CodeSurface, jsonProblem };
+
+//# sourceMappingURL=code.js.map

package/controls/code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"code.js","names":[],"sources":["../../src/kit/controls/code.tsx"],"sourcesContent":["/**\n * CODE — the code field (DESIGN 8.21), V2 controls/misc.tsx (CodeSurface, CodeControl) fitted to what prod stores.\n *\n * Values (backend reference-validation `code`, adapters/values.ts codeToProd):\n *   \"<p>hi</p>\"                         a bare string, kept a string\n *   { language?: \"html\", code: \"…\" }    the object form; only `code` and `language` are written back\n * The language list sits in the surface header. Picking one writes the object form; a value that never changes its\n * language keeps the shape it was stored in. A value over CODE_MAX_LENGTH characters is refused with the reason.\n *\n * Panel: a one-line summary button that opens a `lg` dialog editing a draft (Cancel / Done). Document: the surface\n * inline. The surface: mono 12/20 textarea with line numbers, Tab inserts two spaces (Shift+Tab leaves the field),\n * Copy, and for JSON a Format action and a live \"Invalid JSON · {reason}\" footer (json.tsx).\n */\nimport * as React from \"react\";\nimport { IconAlertTriangle, IconBraces, IconCode, IconMaximize } from \"@tabler/icons-react\";\nimport { cn } from \"../lib/cn\";\nimport { isObj } from \"../lib/path\";\nimport { useKitEnv, useKitServices } from \"../context\";\nimport { CODE_MAX_LENGTH } from \"../adapters/prod-types\";\nimport type { ControlProps } from \"../types\";\nimport { Button } from \"../ui/button\";\nimport { Modal, ModalBody, ModalContent, ModalFooter, ModalHeader } from \"../ui/overlay\";\nimport { Select } from \"../ui/select\";\n\nconst CODE_LANGUAGES: { value: string; label: string }[] = [\n  { value: \"html\", label: \"HTML\" },\n  { value: \"css\", label: \"CSS\" },\n  { value: \"js\", label: \"JS\" },\n  { value: \"ts\", label: \"TS\" },\n  { value: \"json\", label: \"JSON\" },\n  { value: \"liquid\", label: \"Liquid\" },\n  { value: \"markdown\", label: \"Markdown\" },\n  { value: \"shell\", label: \"Shell\" },\n];\nconst PLAIN = \"plain\";\n\n/** The picker: Plain text, then the field's allowed languages (or the built-in list), then the stored one if it is outside them. */\nfunction languageOptions(language: string | undefined, allowed: string[] | undefined) {\n  const list = allowed ? allowed.map((v) => CODE_LANGUAGES.find((l) => l.value === v) ?? { value: v, label: v }) : CODE_LANGUAGES;\n  return [{ value: PLAIN, label: \"Plain text\" }, ...list, ...(language && !list.some((l) => l.value === language) ? [{ value: language, label: language }] : [])];\n}\n\n/** Why a JSON text does not parse (\"\" when it does, or is empty). */\nexport function jsonProblem(text: string): string {\n  if (!text.trim()) return \"\";\n  try {\n    JSON.parse(text);\n    return \"\";\n  } catch (e) {\n    return (e as Error).message.replace(/^JSON\\.parse: /, \"\");\n  }\n}\n\n/* ── The surface ──────────────────────────────────────────────────────── */\nexport interface CodeSurfaceProps {\n  /** \"json\": the JSON header, Format and the parse footer. \"code\": the language list. */\n  kind: \"json\" | \"code\";\n  value: string;\n  onChange: (v: string) => void;\n  /** code: the language shown in the header (\"\" = none) and what picking one does; absent = no list */\n  language?: string;\n  onLanguage?: (language: string) => void;\n  /** code: the only languages the field allows (its config.languages); absent = the built-in list */\n  languages?: string[];\n  readOnly?: boolean;\n  id?: string;\n  invalid?: boolean;\n  minRows?: number;\n  label?: string;\n  describedBy?: string;\n}\n\nexport function CodeSurface({ kind, value, onChange, language, onLanguage, languages, readOnly, id, invalid, minRows = 8, label, describedBy }: CodeSurfaceProps) {\n  const { toast } = useKitServices();\n  const lines = Math.max(minRows, value.split(\"\\n\").length);\n  const problem = kind === \"json\" ? jsonProblem(value) : value.length > CODE_MAX_LENGTH ? `Code can hold up to ${CODE_MAX_LENGTH.toLocaleString(\"en-US\")} characters; this has ${value.length.toLocaleString(\"en-US\")}.` : \"\";\n  const footerId = id ? `${id}-problem` : undefined;\n  const format = () => {\n    try {\n      onChange(JSON.stringify(JSON.parse(value), null, 2));\n      toast?.success(\"JSON formatted\");\n    } catch {\n      toast?.(\"Fix the JSON before formatting\");\n    }\n  };\n  const copy = () => {\n    void navigator.clipboard?.writeText(value);\n    toast?.success(\"Copied\");\n  };\n  return (\n    <div className={cn(\"overflow-hidden rounded-kit-lg border bg-kit-subtle transition-colors\", invalid || problem ? \"border-[var(--kit-field-invalid)]\" : \"border-kit-line focus-within:border-kit-field-border-focus\")}>\n      <div className=\"flex h-8 items-center justify-between border-b border-kit-line px-2\">\n        {kind === \"json\" ? (\n          <span className=\"px-1 font-kit-mono text-kit-xs text-kit-fg-3\">JSON</span>\n        ) : onLanguage ? (\n          <Select\n            aria-label=\"Code language\"\n            size=\"sm\"\n            variant=\"ghost\"\n            disabled={readOnly}\n            value={language || PLAIN}\n            onValueChange={(l) => onLanguage(l === PLAIN ? \"\" : l)}\n            options={languageOptions(language, languages)}\n          />\n        ) : (\n          <span className=\"px-1 font-kit-mono text-kit-xs text-kit-fg-3\">Code</span>\n        )}\n        <div className=\"flex items-center gap-1\">\n          {kind === \"json\" ? (\n            <button type=\"button\" disabled={readOnly} className=\"rounded-kit-md px-1.5 py-0.5 text-kit-xs text-kit-fg-2 hover:bg-kit-hover hover:text-kit-fg disabled:opacity-50\" onClick={format}>\n              Format\n            </button>\n          ) : null}\n          <button type=\"button\" className=\"rounded-kit-md px-1.5 py-0.5 text-kit-xs text-kit-fg-2 hover:bg-kit-hover hover:text-kit-fg\" onClick={copy}>\n            Copy\n          </button>\n        </div>\n      </div>\n      <div className=\"flex max-h-[60vh] overflow-auto font-kit-mono text-kit-xs leading-5\">\n        <div aria-hidden className=\"select-none border-r border-kit-line bg-kit-subtle px-2 py-2 text-right text-kit-fg-4\">\n          {Array.from({ length: lines }).map((_, i) => (\n            <div key={i}>{i + 1}</div>\n          ))}\n        </div>\n        <textarea\n          id={id}\n          spellCheck={false}\n          autoCapitalize=\"off\"\n          autoCorrect=\"off\"\n          value={value}\n          readOnly={readOnly}\n          aria-invalid={invalid || !!problem || undefined}\n          aria-label={label}\n          aria-describedby={[describedBy, problem ? footerId : undefined].filter(Boolean).join(\" \") || undefined}\n          onChange={(e) => onChange(e.target.value)}\n          onKeyDown={(e) => {\n            if (e.key === \"Tab\" && !e.shiftKey && !readOnly) {\n              e.preventDefault();\n              const el = e.currentTarget;\n              const s = el.selectionStart;\n              onChange(value.slice(0, s) + \"  \" + value.slice(el.selectionEnd));\n              requestAnimationFrame(() => el.setSelectionRange(s + 2, s + 2));\n            }\n          }}\n          style={{ height: lines * 20 + 16 }}\n          className=\"min-w-0 flex-1 resize-none bg-kit-field-bg px-3 py-2 text-kit-fg outline-none\"\n        />\n      </div>\n      {problem ? (\n        <div id={footerId} className=\"border-t border-kit-danger-line bg-kit-danger-soft px-3 py-1.5 text-kit-xs text-kit-danger-fg\">\n          {kind === \"json\" ? `Invalid JSON · ${problem}` : problem}\n        </div>\n      ) : null}\n    </div>\n  );\n}\n\n/* ── Panel: summary button + dialog over a draft ─────────────────────── */\nexport function CodeDialogField({\n  kind, title, description, text, readOnly, id, invalid, language, languages, onDone,\n}: {\n  kind: \"json\" | \"code\";\n  title: string;\n  description?: string;\n  text: string;\n  readOnly?: boolean;\n  id: string;\n  invalid?: boolean;\n  language?: string;\n  languages?: string[];\n  /** commit the draft; returns the reason it can't be saved, or null when saved */\n  onDone: (draft: string, language: string | undefined) => string | null;\n}) {\n  const { toast } = useKitServices();\n  const [open, setOpen] = React.useState(false);\n  const [draft, setDraft] = React.useState(text);\n  const [lang, setLang] = React.useState(language);\n  const [refusal, setRefusal] = React.useState<string | null>(null);\n  const first = text.split(\"\\n\").find((l) => l.trim()) ?? \"\";\n  const Icon = kind === \"json\" ? IconBraces : IconCode;\n  return (\n    <>\n      <button\n        id={id}\n        type=\"button\"\n        aria-haspopup=\"dialog\"\n        aria-invalid={invalid || undefined}\n        onClick={() => {\n          setDraft(text);\n          setLang(language);\n          setRefusal(null);\n          setOpen(true);\n        }}\n        className={cn(\n          \"group/code flex w-full min-w-0 items-center gap-2 rounded-kit-md border bg-kit-subtle px-2.5 py-2 text-left outline-none transition-colors hover:border-kit-line-strong focus-visible:outline-2 focus-visible:outline-kit-focus-ring\",\n          invalid ? \"border-[var(--kit-field-invalid)]\" : \"border-kit-line\",\n        )}\n      >\n        <Icon className=\"size-4 shrink-0 text-kit-fg-3\" stroke={1.5} aria-hidden />\n        <span className={cn(\"min-w-0 flex-1 truncate font-kit-mono text-kit-xs\", first ? \"text-kit-fg-2\" : \"text-kit-fg-3\")}>{first || \"Empty\"}</span>\n        <span className=\"shrink-0 text-kit-2xs tabular-nums text-kit-fg-3\">{text ? `${text.split(\"\\n\").length} lines` : \"\"}</span>\n        <IconMaximize className=\"size-3.5 shrink-0 text-kit-fg-3 group-hover/code:text-kit-fg\" stroke={1.5} aria-hidden />\n      </button>\n      <Modal open={open} onOpenChange={setOpen}>\n        <ModalContent size=\"lg\">\n          <ModalHeader title={title} description={description ?? (kind === \"json\" ? \"Structured data for developers\" : \"Custom code\")} />\n          <ModalBody>\n            <CodeSurface kind={kind} value={draft} onChange={setDraft} language={lang ?? \"\"} onLanguage={kind === \"code\" ? setLang : undefined} languages={languages} readOnly={readOnly} minRows={14} label={title} />\n            {refusal ? (\n              <p role=\"alert\" className=\"mt-2 flex items-start gap-1.5 text-kit-xs text-kit-danger-fg\">\n                <IconAlertTriangle className=\"mt-0.5 size-3.5 shrink-0\" stroke={1.5} aria-hidden />\n                {refusal}\n              </p>\n            ) : null}\n          </ModalBody>\n          <ModalFooter>\n            <span className=\"text-kit-xs text-kit-fg-3\">Esc to close</span>\n            <span className=\"mr-auto\" aria-hidden />\n            <Button variant=\"ghost\" onClick={() => setOpen(false)}>\n              Cancel\n            </Button>\n            <Button\n              variant=\"primary\"\n              disabled={readOnly}\n              onClick={() => {\n                const why = onDone(draft, lang);\n                if (why) {\n                  setRefusal(why);\n                  toast?.(kind === \"json\" ? \"Invalid JSON\" : \"Can't save this code\", { description: \"Fix it before saving.\" });\n                  return;\n                }\n                setOpen(false);\n              }}\n            >\n              Done\n            </Button>\n          </ModalFooter>\n        </ModalContent>\n      </Modal>\n    </>\n  );\n}\n\n/* ── The control ──────────────────────────────────────────────────────── */\ntype CodeRead = { ok: true; code: string; language?: string; object: boolean } | { ok: false };\nfunction readCode(v: unknown): CodeRead {\n  if (v == null) return { ok: true, code: \"\", object: false };\n  if (typeof v === \"string\") return { ok: true, code: v, object: false };\n  if (isObj(v) && typeof v.code === \"string\" && (v.language === undefined || typeof v.language === \"string\")) return { ok: true, code: v.code, language: v.language as string | undefined, object: true };\n  return { ok: false };\n}\n\n/** The stored shape for edited code: a string stays a string until a language is picked; the object keeps its form. */\nfunction codeValue(prev: CodeRead & { ok: true }, code: string, language: string | undefined): string | { language?: string; code: string } {\n  const lang = language ?? prev.language ?? \"\";\n  if (!prev.object && !lang) return code;\n  return lang ? { language: lang, code } : { code };\n}\nconst tooLong = (code: string) => (code.length > CODE_MAX_LENGTH ? `Code can hold up to ${CODE_MAX_LENGTH.toLocaleString(\"en-US\")} characters; this has ${code.length.toLocaleString(\"en-US\")}.` : null);\n\nexport function CodeControl({ field, value, onChange, readOnly, id, invalid }: ControlProps) {\n  const { variant } = useKitEnv();\n  const [refused, setRefused] = React.useState<string | null>(null);\n  const read = readCode(value);\n  if (!read.ok) return <UnreadableValue id={id} title={field.title} kind=\"code\" value={value} />;\n  if (variant === \"document\")\n    return (\n      <div className=\"flex flex-col gap-1.5\">\n        <CodeSurface\n          kind=\"code\"\n          id={id}\n          invalid={invalid || !!refused}\n          readOnly={readOnly}\n          value={read.code}\n          language={read.language ?? \"\"}\n          languages={field.languages}\n          onChange={(code) => {\n            const why = tooLong(code);\n            setRefused(why);\n            if (!why) onChange(codeValue(read, code, undefined));\n          }}\n          onLanguage={(l) => onChange(codeValue(read, read.code, l))}\n        />\n        {refused ? (\n          <p role=\"alert\" className=\"text-kit-xs text-kit-danger-fg\">\n            {refused}\n          </p>\n        ) : null}\n      </div>\n    );\n  return (\n    <CodeDialogField\n      kind=\"code\"\n      id={id}\n      title={field.title}\n      description={field.description || undefined}\n      text={read.code}\n      language={read.language}\n      languages={field.languages}\n      readOnly={readOnly}\n      invalid={invalid}\n      onDone={(draft, lang) => {\n        const why = tooLong(draft);\n        if (why) return why;\n        const next = codeValue(read, draft, lang);\n        if (draft !== read.code || (lang ?? \"\") !== (read.language ?? \"\")) onChange(next);\n        return null;\n      }}\n    />\n  );\n}\n\n/** A stored value the control cannot read: named, shown, kept as it is (never replaced by a stray edit). */\nexport function UnreadableValue({ id, title, kind, value }: { id: string; title: string; kind: string; value: unknown }) {\n  let raw: string;\n  try {\n    raw = typeof value === \"string\" ? value : JSON.stringify(value, null, 2);\n  } catch {\n    raw = String(value);\n  }\n  return (\n    <output\n      id={id}\n      tabIndex={0}\n      data-slot={`${kind}-unreadable`}\n      className=\"flex min-w-0 items-start gap-2 rounded-kit-md border border-dashed border-kit-line-strong bg-kit-subtle px-2.5 py-2 text-kit-xs text-kit-fg-2 outline-none focus-visible:outline-2 focus-visible:outline-kit-focus-ring\"\n    >\n      <IconAlertTriangle className=\"mt-0.5 size-3.5 shrink-0 text-kit-warning-fg\" stroke={1.5} aria-hidden />\n      <span className=\"min-w-0\">\n        {title} holds a value this {kind} editor can't read, so it is kept as it is:{\" \"}\n        <span className=\"block max-h-24 overflow-auto whitespace-pre-wrap break-all font-kit-mono text-kit-fg\">{raw}</span>\n      </span>\n    </output>\n  );\n}\n"],"mappings":"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"}

package/controls/color.d.ts

@@ -0,0 +1,5 @@
+import type { ControlProps } from "../types";
+export declare const HEX_COLOR: RegExp;
+/** #RGB / #RRGGBBAA → #RRGGBB for the native picker, which takes only six digits. */
+export declare function pickerHex(v: string): string;
+export declare function ColorControl({ field, value, onChange, readOnly, id, invalid, onBlur }: ControlProps): import("react/jsx-runtime").JSX.Element;

package/controls/color.js

@@ -0,0 +1,130 @@
+import { cn } from "../lib/cn.js";
+import { useKitEnv } from "../context.js";
+import { Popover, PopoverContent, PopoverTrigger, Tooltip } from "../ui/overlay.js";
+import { Input } from "../ui/input.js";
+import { TEXT_FOCUS, str } from "./text.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/kit/controls/color.tsx
+/**
+* COLOR — site-palette swatches first, then a custom colour (V2 HEAD 9829bf1 kit/controls/misc.tsx, DESIGN §8.13).
+*
+* Stored shape (prod `color`): a hex string the backend accepts — #RGB, #RRGGBB or #RRGGBBAA — or null when cleared.
+* The hex box keeps what you type as a draft and writes it only once it is a hex colour; while it is not, the box is
+* marked invalid and says why, so a half-typed "#12" never reaches the save (the API would refuse it).
+* The palette is the host's (`env.palette`, the project's brand colours); with none, the popover offers the custom
+* picker alone.
+*/
+var HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+/** #RGB / #RRGGBBAA → #RRGGBB for the native picker, which takes only six digits. */
+function pickerHex(v) {
+	if (!HEX_COLOR.test(v)) return "#000000";
+	const h = v.slice(1);
+	return `#${(h.length === 3 ? h.split("").map((c) => c + c).join("") : h.slice(0, 6)).toLowerCase()}`;
+}
+function ColorControl({ field, value, onChange, readOnly, id, invalid, onBlur }) {
+	const { palette } = useKitEnv();
+	const v = str(value);
+	const [draft, setDraft] = React.useState(null);
+	const shown = draft ?? v;
+	const bad = draft !== null && draft.trim() !== "" && !HEX_COLOR.test(draft.trim());
+	const sw = palette.find((p) => p.value.toLowerCase() === v.toLowerCase());
+	const errId = React.useId();
+	const write = (next) => {
+		setDraft(null);
+		onChange(next);
+	};
+	return /* @__PURE__ */ jsxs("div", {
+		className: "flex flex-col gap-1",
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex items-center gap-2",
+			children: [/* @__PURE__ */ jsxs(Popover, { children: [/* @__PURE__ */ jsxs(PopoverTrigger, {
+				disabled: readOnly,
+				"aria-label": `Choose a colour for ${field.title}`,
+				render: /* @__PURE__ */ jsx("button", {
+					type: "button",
+					className: "flex h-8 min-w-0 flex-1 items-center gap-2 rounded-kit-md border border-kit-field-border bg-kit-field-bg pl-1 pr-2.5 text-left text-kit-sm shadow-kit-field transition-colors hover:border-kit-field-border-hover disabled:cursor-not-allowed disabled:opacity-60 data-[popup-open]:border-kit-field-border-focus"
+				}),
+				children: [
+					/* @__PURE__ */ jsx("span", {
+						className: "size-6 shrink-0 rounded-kit-md border border-kit-swatch-ring shadow-kit-xs",
+						style: { background: v || "transparent" }
+					}),
+					/* @__PURE__ */ jsx("span", {
+						className: cn("min-w-0 flex-1 truncate", v ? "text-kit-fg" : "text-kit-fg-3"),
+						children: sw ? sw.name : v ? "Custom" : "No color"
+					}),
+					sw?.token ? /* @__PURE__ */ jsx("span", {
+						className: "truncate font-kit-mono text-kit-2xs text-kit-fg-3",
+						children: sw.token
+					}) : null
+				]
+			}), /* @__PURE__ */ jsxs(PopoverContent, {
+				className: "w-64",
+				children: [
+					palette.length ? /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("div", {
+						className: "mb-2 text-kit-xs text-kit-fg-3",
+						children: "Site palette"
+					}), /* @__PURE__ */ jsx("div", {
+						className: "grid grid-cols-5 gap-2",
+						children: palette.map((s) => /* @__PURE__ */ jsx(Tooltip, {
+							content: `${s.name}${s.token ? ` · ${s.token}` : ""}`,
+							children: /* @__PURE__ */ jsx("button", {
+								type: "button",
+								"aria-label": s.name,
+								"aria-pressed": s.value.toLowerCase() === v.toLowerCase(),
+								onClick: () => write(s.value),
+								className: cn("relative size-9 rounded-kit-md border border-kit-swatch-ring transition-transform hover:scale-105", s.value.toLowerCase() === v.toLowerCase() && "ring-2 ring-kit-fg ring-offset-2 ring-offset-kit-surface"),
+								style: { background: s.value }
+							})
+						}, s.value))
+					})] }) : null,
+					/* @__PURE__ */ jsxs("label", {
+						className: cn("flex items-center gap-2 text-kit-xs text-kit-fg-3", palette.length && "mt-3 border-t border-kit-line pt-3"),
+						children: ["Custom", /* @__PURE__ */ jsx("input", {
+							type: "color",
+							value: pickerHex(v),
+							onChange: (e) => write(e.target.value.toUpperCase()),
+							className: "h-7 w-full cursor-pointer rounded-kit-md border border-kit-line bg-transparent"
+						})]
+					}),
+					v ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => write(null),
+						className: "mt-2 w-full rounded-kit-md px-1.5 py-1 text-left text-kit-xs text-kit-fg-2 hover:bg-kit-hover hover:text-kit-fg",
+						children: "No color"
+					}) : null
+				]
+			})] }), /* @__PURE__ */ jsx(Input, {
+				id,
+				value: shown,
+				readOnly,
+				"aria-invalid": invalid || bad,
+				"aria-describedby": bad ? errId : void 0,
+				placeholder: "#RRGGBB",
+				spellCheck: false,
+				onChange: (e) => {
+					const t = e.target.value.trim();
+					if (t === "") write(null);
+					else if (HEX_COLOR.test(t)) write(t);
+					else setDraft(e.target.value);
+				},
+				onBlur,
+				className: cn(TEXT_FOCUS, "w-28 shrink-0 font-kit-mono")
+			})]
+		}), bad ? /* @__PURE__ */ jsxs("p", {
+			id: errId,
+			role: "alert",
+			className: "text-kit-xs text-kit-danger-fg",
+			children: [
+				"“",
+				draft.trim(),
+				"” isn't a hex color, so it isn't saved. Use #RGB or #RRGGBB."
+			]
+		}) : null]
+	});
+}
+//#endregion
+export { ColorControl };
+
+//# sourceMappingURL=color.js.map

package/controls/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","names":[],"sources":["../../src/kit/controls/color.tsx"],"sourcesContent":["/**\n * COLOR — site-palette swatches first, then a custom colour (V2 HEAD 9829bf1 kit/controls/misc.tsx, DESIGN §8.13).\n *\n * Stored shape (prod `color`): a hex string the backend accepts — #RGB, #RRGGBB or #RRGGBBAA — or null when cleared.\n * The hex box keeps what you type as a draft and writes it only once it is a hex colour; while it is not, the box is\n * marked invalid and says why, so a half-typed \"#12\" never reaches the save (the API would refuse it).\n * The palette is the host's (`env.palette`, the project's brand colours); with none, the popover offers the custom\n * picker alone.\n */\nimport * as React from \"react\";\nimport { cn } from \"../lib/cn\";\nimport { useKitEnv } from \"../context\";\nimport { Input } from \"../ui/input\";\nimport { Popover, PopoverContent, PopoverTrigger, Tooltip } from \"../ui/overlay\";\nimport type { ControlProps } from \"../types\";\nimport { str, TEXT_FOCUS } from \"./text\";\n\nexport const HEX_COLOR = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;\n/** #RGB / #RRGGBBAA → #RRGGBB for the native picker, which takes only six digits. */\nexport function pickerHex(v: string): string {\n  if (!HEX_COLOR.test(v)) return \"#000000\";\n  const h = v.slice(1);\n  const six = h.length === 3 ? h.split(\"\").map((c) => c + c).join(\"\") : h.slice(0, 6);\n  return `#${six.toLowerCase()}`;\n}\n\nexport function ColorControl({ field, value, onChange, readOnly, id, invalid, onBlur }: ControlProps) {\n  const { palette } = useKitEnv();\n  const v = str(value);\n  const [draft, setDraft] = React.useState<string | null>(null);\n  const shown = draft ?? v;\n  const bad = draft !== null && draft.trim() !== \"\" && !HEX_COLOR.test(draft.trim());\n  const sw = palette.find((p) => p.value.toLowerCase() === v.toLowerCase());\n  const errId = React.useId();\n  const write = (next: string | null) => {\n    setDraft(null);\n    onChange(next);\n  };\n  return (\n    <div className=\"flex flex-col gap-1\">\n      <div className=\"flex items-center gap-2\">\n        <Popover>\n          <PopoverTrigger\n            disabled={readOnly}\n            aria-label={`Choose a colour for ${field.title}`}\n            render={\n              <button\n                type=\"button\"\n                className=\"flex h-8 min-w-0 flex-1 items-center gap-2 rounded-kit-md border border-kit-field-border bg-kit-field-bg pl-1 pr-2.5 text-left text-kit-sm shadow-kit-field transition-colors hover:border-kit-field-border-hover disabled:cursor-not-allowed disabled:opacity-60 data-[popup-open]:border-kit-field-border-focus\"\n              />\n            }\n          >\n            <span className=\"size-6 shrink-0 rounded-kit-md border border-kit-swatch-ring shadow-kit-xs\" style={{ background: v || \"transparent\" }} />\n            <span className={cn(\"min-w-0 flex-1 truncate\", v ? \"text-kit-fg\" : \"text-kit-fg-3\")}>{sw ? sw.name : v ? \"Custom\" : \"No color\"}</span>\n            {sw?.token ? <span className=\"truncate font-kit-mono text-kit-2xs text-kit-fg-3\">{sw.token}</span> : null}\n          </PopoverTrigger>\n          <PopoverContent className=\"w-64\">\n            {palette.length ? (\n              <>\n                <div className=\"mb-2 text-kit-xs text-kit-fg-3\">Site palette</div>\n                <div className=\"grid grid-cols-5 gap-2\">\n                  {palette.map((s) => (\n                    <Tooltip key={s.value} content={`${s.name}${s.token ? ` · ${s.token}` : \"\"}`}>\n                      <button\n                        type=\"button\"\n                        aria-label={s.name}\n                        aria-pressed={s.value.toLowerCase() === v.toLowerCase()}\n                        onClick={() => write(s.value)}\n                        className={cn(\n                          \"relative size-9 rounded-kit-md border border-kit-swatch-ring transition-transform hover:scale-105\",\n                          s.value.toLowerCase() === v.toLowerCase() && \"ring-2 ring-kit-fg ring-offset-2 ring-offset-kit-surface\",\n                        )}\n                        style={{ background: s.value }}\n                      />\n                    </Tooltip>\n                  ))}\n                </div>\n              </>\n            ) : null}\n            <label className={cn(\"flex items-center gap-2 text-kit-xs text-kit-fg-3\", palette.length && \"mt-3 border-t border-kit-line pt-3\")}>\n              Custom\n              <input\n                type=\"color\"\n                value={pickerHex(v)}\n                onChange={(e) => write(e.target.value.toUpperCase())}\n                className=\"h-7 w-full cursor-pointer rounded-kit-md border border-kit-line bg-transparent\"\n              />\n            </label>\n            {v ? (\n              <button type=\"button\" onClick={() => write(null)} className=\"mt-2 w-full rounded-kit-md px-1.5 py-1 text-left text-kit-xs text-kit-fg-2 hover:bg-kit-hover hover:text-kit-fg\">\n                No color\n              </button>\n            ) : null}\n          </PopoverContent>\n        </Popover>\n        <Input\n          id={id}\n          value={shown}\n          readOnly={readOnly}\n          aria-invalid={invalid || bad}\n          aria-describedby={bad ? errId : undefined}\n          placeholder=\"#RRGGBB\"\n          spellCheck={false}\n          onChange={(e) => {\n            const t = e.target.value.trim();\n            if (t === \"\") write(null);\n            else if (HEX_COLOR.test(t)) write(t);\n            else setDraft(e.target.value);\n          }}\n          onBlur={onBlur}\n          className={cn(TEXT_FOCUS, \"w-28 shrink-0 font-kit-mono\")}\n        />\n      </div>\n      {bad ? (\n        <p id={errId} role=\"alert\" className=\"text-kit-xs text-kit-danger-fg\">\n          “{draft!.trim()}” isn't a hex color, so it isn't saved. Use #RGB or #RRGGBB.\n        </p>\n      ) : null}\n    </div>\n  );\n}\n"],"mappings":"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"}