@bettercms-ai/kit 0.1.1 → 2.0.0

package/dist/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/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-line-strong bg-kit-field-bg pl-1 pr-2.5 text-left text-kit-sm hover:border-kit-line-strong data-[popup-open]:border-kit-line-strong data-[popup-open]:bg-kit-field-bg"
+				}),
+				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 colour"
+					}),
+					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 duration-150 ease-out motion-reduce:transition-none can-hover:hover:scale-[1.02]", 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("mt-3 flex items-center gap-2 border-t border-kit-line pt-3 text-kit-xs text-kit-fg-3", !palette.length && "mt-0 border-t-0 pt-0"),
+						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 colour"
+					}) : 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 [&_input]: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, HEX_COLOR, pickerHex };
+
+//# sourceMappingURL=color.js.map

package/dist/controls/color.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"color.js","names":[],"sources":["../../src/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-line-strong bg-kit-field-bg pl-1 pr-2.5 text-left text-kit-sm hover:border-kit-line-strong data-[popup-open]:border-kit-line-strong data-[popup-open]:bg-kit-field-bg\"\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 colour\"}</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                          // 1–2% hover scale, only for a hovering pointer (canvas revamp V463)\n                          \"relative size-9 rounded-kit-md border border-kit-swatch-ring transition-transform duration-150 ease-out motion-reduce:transition-none can-hover:hover:scale-[1.02]\",\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(\"mt-3 flex items-center gap-2 border-t border-kit-line pt-3 text-kit-xs text-kit-fg-3\", !palette.length && \"mt-0 border-t-0 pt-0\")}>\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 colour\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 [&_input]: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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"}

package/dist/controls/component-services.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The component lookup a rich-text body's embedded component card reads (V2 instance-card.tsx), declared as an
+ * augmentation of KitServices. The host answers from its own components library:
+ *
+ *   the dock     → the project's components (GET /components) and its usage map (GET /projects/:id/component-usage)
+ *   the sandbox  → V2's demo component library (/style-guide/kit fixtures)
+ *
+ * Absent → the card stays the compact "Linked component" row: no state, no count, no preview is ever made up.
+ */
+import type { RichTextAt } from "./rich-text/codec";
+export interface KitComponentField {
+    key: string;
+    label: string;
+    /** the component's own value for it (its default), before this place's overrides */
+    value?: unknown;
+    /** a choice field's options: the card lists the chosen option's LABEL, never its stored value (an id) */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** the component expects every place to fill it (an editor hint): an empty one marks the card's scope chip */
+    required?: boolean;
+}
+export interface KitComponentInfo {
+    /** the component's current name */
+    name: string;
+    /** true: the library has no component with this id (it was deleted) */
+    missing?: boolean;
+    /** how many places link to it; absent → not measured, and the card says "Shared" without a number */
+    places?: number;
+    /** its content fields in order; an override counts as "Edited here" only when its key is one of these */
+    fields?: KitComponentField[];
+    /** its block icon (V2 instance card BlockIcon), a name the host's IconGlyph draws; absent → the components glyph */
+    icon?: string;
+    /** a picture of the component as readers see it (the host's snapshot of it) */
+    image?: string | null;
+    /**
+     * the version readers see now (the component's last publish); a separate copy taken from an older one shows
+     * "Shared version changed". Absent → not known, and no copy is ever called out of date.
+     */
+    publishedAt?: string | null;
+}
+/** A separate copy of a component (V2 instances.ts `detach`): what this place keeps when it stops following it. */
+export interface KitComponentCopy {
+    /** the values readers see, now this place's own (V2 `props`) */
+    props: Record<string, unknown>;
+    /** whatever the host stores beside them to draw the copy (production: the frozen block tree, as JSON) */
+    blocks?: string;
+    /** the version of the component it was taken from */
+    sourcePublishedAt?: string;
+}
+/**
+ * The component drawn live in its card (V2 instance card), with THIS place's values: a linked place's defaults with its
+ * overrides, a separate copy's own values. Read-only, the card's width. `fallback(reason)` is what the card shows when
+ * the host cannot draw it (not validated, no runtime here, an error), with the reason in words.
+ */
+export interface KitComponentPreviewProps {
+    componentId: string;
+    title: string;
+    props: Record<string, unknown>;
+    fallback: (reason: string) => import("react").ReactNode;
+}
+/** A component a rich-text body can embed (the "/" menu's More components). */
+export interface KitInsertableComponent {
+    id: string;
+    name: string;
+    description?: string;
+}
+declare module "../context" {
+    interface KitServices {
+        /**
+         * A React HOOK (called on every render of a component card, so the host passes one function for the life of the
+         * form): what the library knows about the component an embedded instance links to. `info` undefined while it
+         * loads; `error` is a whole sentence ("Components couldn't be loaded: …").
+         */
+        useComponentInfo?: (ref: string) => {
+            info?: KitComponentInfo;
+            loading?: boolean;
+            error?: string;
+        };
+        /**
+         * Make this place a separate copy (V2 "Keep as a separate copy" / "Make a separate copy"): what readers see now,
+         * with this place's overrides. Rejects with a whole sentence the card shows ("“Card” has never been published…").
+         * Absent → the card offers no separate copy.
+         */
+        copyComponent?: (ref: string, input: {
+            overrides: Record<string, unknown>;
+            variant?: string;
+        }) => Promise<KitComponentCopy>;
+        /**
+         * The component that IS `variant` of `ref`'s section family (a variant is its own component): an embedded instance
+         * with a per-instance layout reads as that member, so the card draws the variant itself (V2 instance card draws
+         * `r.variant`). Undefined → `ref` has no family member for it, and the card names the layout instead.
+         */
+        componentVariantMember?: (ref: string, variant: string) => string | undefined;
+        /**
+         * A React HOOK (one identity for the life of the form): the components the rich-text field at `at` may embed,
+         * already narrowed to the ones its config accepts. `error` is a whole sentence. Absent → the "/" menu offers no
+         * components.
+         */
+        useInsertableComponents?: (at: RichTextAt) => {
+            components: KitInsertableComponent[];
+            loading?: boolean;
+            error?: string;
+        };
+        /**
+         * The host's own undo history (the dock: the Visual Editor's toolbar Undo). Runs `write` (synchronously) as ONE
+         * step of it and answers that step (KitHistoryStep). Null: the host recorded no step (it keeps no history here),
+         * so the editor's own history takes the step.
+         */
+        historyStep?: (write: () => void) => KitHistoryStep | null;
+        /**
+         * Draws an embedded component live in its card (KitComponentPreviewProps). Mounted only once the card is on screen.
+         * Absent → the card shows the host's snapshot where the place shows exactly the component, else its values.
+         */
+        ComponentPreview?: import("react").ComponentType<KitComponentPreviewProps>;
+        /**
+         * The per-placement settings form an embedded instance's panel shows (V2 instance panel): inherited values muted,
+         * fields edited here with a Reset, the Layout variant. Absent → the card offers no "Edit properties".
+         */
+        ComponentSettings?: import("react").ComponentType<KitComponentSettingsProps>;
+        /** "Edit for all N places": open the shared component itself. Absent → the item is not offered. */
+        openComponent?: (ref: string) => void;
+        /** "Copy link" to this place. Undefined → the item is not offered. */
+        componentHref?: (ref: string, instanceId?: string) => string | undefined;
+    }
+}
+/** What the host's settings form edits for ONE place of a shared component. */
+export interface KitComponentSettingsProps {
+    componentId: string;
+    /** Only the fields this place changed (everything else follows the component). */
+    overrides: Record<string, unknown>;
+    variant?: string;
+    /** A separate copy: its own full props, no longer following the component. */
+    detached?: {
+        props: Record<string, unknown>;
+    };
+    readOnly?: boolean;
+    /** Focus this field when the panel opens (a click on it in the preview). */
+    focusKey?: string | null;
+    onOverrides: (next: Record<string, unknown>) => void;
+    onVariant?: (variant: string | undefined) => void;
+}
+/** V2's insert toast: an embedded component is shared, edits here change only this place. */
+export declare const COMPONENT_INSERT_TOAST = "Shared: it follows the block. Fields you edit here change only this place.";
+/**
+ * One step of the host's history (KitServices.historyStep). The host's toolbar can undo and redo it too, so `next`
+ * says where it stands NOW: the host's next undo, its next redo, or neither (other changes come first, or it is gone).
+ * `undo` / `redo` answer true or the sentence saying why nothing changed.
+ */
+export interface KitHistoryStep {
+    undo: () => true | string;
+    redo: () => true | string;
+    next: () => "undo" | "redo" | null;
+}
+export {};

package/dist/controls/component-services.js

@@ -0,0 +1,7 @@
+//#region src/controls/component-services.ts
+/** V2's insert toast: an embedded component is shared, edits here change only this place. */
+var COMPONENT_INSERT_TOAST = "Shared: it follows the block. Fields you edit here change only this place.";
+//#endregion
+export { COMPONENT_INSERT_TOAST };
+
+//# sourceMappingURL=component-services.js.map

package/dist/controls/component-services.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-services.js","names":[],"sources":["../../src/controls/component-services.ts"],"sourcesContent":["/**\n * The component lookup a rich-text body's embedded component card reads (V2 instance-card.tsx), declared as an\n * augmentation of KitServices. The host answers from its own components library:\n *\n *   the dock     → the project's components (GET /components) and its usage map (GET /projects/:id/component-usage)\n *   the sandbox  → V2's demo component library (/style-guide/kit fixtures)\n *\n * Absent → the card stays the compact \"Linked component\" row: no state, no count, no preview is ever made up.\n */\nimport type { RichTextAt } from \"./rich-text/codec\";\n\nexport interface KitComponentField {\n  key: string;\n  label: string;\n  /** the component's own value for it (its default), before this place's overrides */\n  value?: unknown;\n  /** a choice field's options: the card lists the chosen option's LABEL, never its stored value (an id) */\n  options?: { value: string; label: string }[];\n  /** the component expects every place to fill it (an editor hint): an empty one marks the card's scope chip */\n  required?: boolean;\n}\n\nexport interface KitComponentInfo {\n  /** the component's current name */\n  name: string;\n  /** true: the library has no component with this id (it was deleted) */\n  missing?: boolean;\n  /** how many places link to it; absent → not measured, and the card says \"Shared\" without a number */\n  places?: number;\n  /** its content fields in order; an override counts as \"Edited here\" only when its key is one of these */\n  fields?: KitComponentField[];\n  /** its block icon (V2 instance card BlockIcon), a name the host's IconGlyph draws; absent → the components glyph */\n  icon?: string;\n  /** a picture of the component as readers see it (the host's snapshot of it) */\n  image?: string | null;\n  /**\n   * the version readers see now (the component's last publish); a separate copy taken from an older one shows\n   * \"Shared version changed\". Absent → not known, and no copy is ever called out of date.\n   */\n  publishedAt?: string | null;\n}\n\n/** A separate copy of a component (V2 instances.ts `detach`): what this place keeps when it stops following it. */\nexport interface KitComponentCopy {\n  /** the values readers see, now this place's own (V2 `props`) */\n  props: Record<string, unknown>;\n  /** whatever the host stores beside them to draw the copy (production: the frozen block tree, as JSON) */\n  blocks?: string;\n  /** the version of the component it was taken from */\n  sourcePublishedAt?: string;\n}\n\n/**\n * The component drawn live in its card (V2 instance card), with THIS place's values: a linked place's defaults with its\n * overrides, a separate copy's own values. Read-only, the card's width. `fallback(reason)` is what the card shows when\n * the host cannot draw it (not validated, no runtime here, an error), with the reason in words.\n */\nexport interface KitComponentPreviewProps {\n  componentId: string;\n  title: string;\n  props: Record<string, unknown>;\n  fallback: (reason: string) => import(\"react\").ReactNode;\n}\n\n/** A component a rich-text body can embed (the \"/\" menu's More components). */\nexport interface KitInsertableComponent {\n  id: string;\n  name: string;\n  description?: string;\n}\n\ndeclare module \"../context\" {\n  interface KitServices {\n    /**\n     * A React HOOK (called on every render of a component card, so the host passes one function for the life of the\n     * form): what the library knows about the component an embedded instance links to. `info` undefined while it\n     * loads; `error` is a whole sentence (\"Components couldn't be loaded: …\").\n     */\n    useComponentInfo?: (ref: string) => { info?: KitComponentInfo; loading?: boolean; error?: string };\n    /**\n     * Make this place a separate copy (V2 \"Keep as a separate copy\" / \"Make a separate copy\"): what readers see now,\n     * with this place's overrides. Rejects with a whole sentence the card shows (\"“Card” has never been published…\").\n     * Absent → the card offers no separate copy.\n     */\n    copyComponent?: (ref: string, input: { overrides: Record<string, unknown>; variant?: string }) => Promise<KitComponentCopy>;\n    /**\n     * The component that IS `variant` of `ref`'s section family (a variant is its own component): an embedded instance\n     * with a per-instance layout reads as that member, so the card draws the variant itself (V2 instance card draws\n     * `r.variant`). Undefined → `ref` has no family member for it, and the card names the layout instead.\n     */\n    componentVariantMember?: (ref: string, variant: string) => string | undefined;\n    /**\n     * A React HOOK (one identity for the life of the form): the components the rich-text field at `at` may embed,\n     * already narrowed to the ones its config accepts. `error` is a whole sentence. Absent → the \"/\" menu offers no\n     * components.\n     */\n    useInsertableComponents?: (at: RichTextAt) => { components: KitInsertableComponent[]; loading?: boolean; error?: string };\n    /**\n     * The host's own undo history (the dock: the Visual Editor's toolbar Undo). Runs `write` (synchronously) as ONE\n     * step of it and answers that step (KitHistoryStep). Null: the host recorded no step (it keeps no history here),\n     * so the editor's own history takes the step.\n     */\n    historyStep?: (write: () => void) => KitHistoryStep | null;\n    /**\n     * Draws an embedded component live in its card (KitComponentPreviewProps). Mounted only once the card is on screen.\n     * Absent → the card shows the host's snapshot where the place shows exactly the component, else its values.\n     */\n    ComponentPreview?: import(\"react\").ComponentType<KitComponentPreviewProps>;\n    /**\n     * The per-placement settings form an embedded instance's panel shows (V2 instance panel): inherited values muted,\n     * fields edited here with a Reset, the Layout variant. Absent → the card offers no \"Edit properties\".\n     */\n    ComponentSettings?: import(\"react\").ComponentType<KitComponentSettingsProps>;\n    /** \"Edit for all N places\": open the shared component itself. Absent → the item is not offered. */\n    openComponent?: (ref: string) => void;\n    /** \"Copy link\" to this place. Undefined → the item is not offered. */\n    componentHref?: (ref: string, instanceId?: string) => string | undefined;\n  }\n}\n\n/** What the host's settings form edits for ONE place of a shared component. */\nexport interface KitComponentSettingsProps {\n  componentId: string;\n  /** Only the fields this place changed (everything else follows the component). */\n  overrides: Record<string, unknown>;\n  variant?: string;\n  /** A separate copy: its own full props, no longer following the component. */\n  detached?: { props: Record<string, unknown> };\n  readOnly?: boolean;\n  /** Focus this field when the panel opens (a click on it in the preview). */\n  focusKey?: string | null;\n  onOverrides: (next: Record<string, unknown>) => void;\n  onVariant?: (variant: string | undefined) => void;\n}\n\n/** V2's insert toast: an embedded component is shared, edits here change only this place. */\nexport const COMPONENT_INSERT_TOAST = \"Shared: it follows the block. Fields you edit here change only this place.\";\n\n/**\n * One step of the host's history (KitServices.historyStep). The host's toolbar can undo and redo it too, so `next`\n * says where it stands NOW: the host's next undo, its next redo, or neither (other changes come first, or it is gone).\n * `undo` / `redo` answer true or the sentence saying why nothing changed.\n */\nexport interface KitHistoryStep {\n  undo: () => true | string;\n  redo: () => true | string;\n  next: () => \"undo\" | \"redo\" | null;\n}\n\nexport {};\n"],"mappings":";;AAwIA,IAAa,yBAAyB"}

package/dist/controls/date-register.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/controls/date-register.js

@@ -0,0 +1,9 @@
+import { CONTROLS } from "../engine/kit-field.js";
+import { DateControl } from "./date.js";
+//#region src/controls/date-register.ts
+/** Lane C3: date and datetime in the engine's dispatch table (one line per type; merge with other lanes by line). */
+CONTROLS.date = DateControl;
+CONTROLS.datetime = DateControl;
+//#endregion
+
+//# sourceMappingURL=date-register.js.map

package/dist/controls/date-register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"date-register.js","names":[],"sources":["../../src/controls/date-register.ts"],"sourcesContent":["/** Lane C3: date and datetime in the engine's dispatch table (one line per type; merge with other lanes by line). */\nimport { CONTROLS } from \"../engine/kit-field\";\nimport { DateControl } from \"./date\";\n\nCONTROLS.date = DateControl;\nCONTROLS.datetime = DateControl;\n"],"mappings":";;;;AAIA,SAAS,OAAO;AAChB,SAAS,WAAW"}

package/dist/controls/date-zone.d.ts

@@ -0,0 +1,104 @@
+import type { FieldSchema } from "../schema/types";
+declare module "../context" {
+    interface KitServices {
+        /**
+         * The site's IANA zone (Project.localeConfig.timeZone, Settings › General): where a new date/time value starts and
+         * what timezone "site" locks to. The dock passes `useSiteTimeZone().zone` when its source is "site". Absent or not
+         * a zone → the viewer's browser zone, which the picker names "Your time zone".
+         */
+        siteTimeZone?: string;
+    }
+}
+export type ZoneSource = "site" | "browser";
+export declare function validZone(z: unknown): z is string;
+export declare const modernZone: (z: string) => string;
+export declare function browserZone(): string;
+/** The zone a new value starts in: the site's, else the browser's. `source` names which one. */
+export declare function useDefaultZone(): {
+    zone: string;
+    source: ZoneSource;
+};
+export type ZoneMode = "pick" | "site" | "fixed" | "none";
+/**
+ * What the schema allows. A `date` never carries a zone here: prod stores a date as "YYYY-MM-DD" and refuses a time on
+ * a date field without includeTime, so a zoned date (V2 allowed one) would be refused at save.
+ */
+export declare function zonePolicy(field: Pick<FieldSchema, "type" | "timezone">): {
+    mode: ZoneMode;
+    zone?: string;
+};
+/** The zone's UTC offset in minutes at an instant (+330 for Kolkata). */
+export declare function offsetMinutes(zone: string, at: Date): number;
+/** +330 → "+05:30"; 0 → "+00:00". */
+export declare const offsetIso: (min: number) => string;
+/** "GMT+5:30", "GMT−7", "GMT" — the short form people read (with a true minus sign). */
+export declare function zoneShortOffset(zone: string, at?: Date): string;
+export declare const zoneCity: (z: string) => string;
+/** "GMT+5:30 · Kolkata" */
+export declare const zoneLabel: (zone: string, at?: Date) => string;
+export interface Wall {
+    /** "YYYY-MM-DD" */
+    ymd: string;
+    /** "HH:mm" */
+    time: string;
+}
+/** The wall clock an instant shows in a zone. */
+export declare function instantToWall(instant: Date, zone: string): Wall;
+/**
+ * The offset of a wall time in a zone, or null when a clock change skips that wall time (it names no instant there).
+ * Two passes: the offset at the naive instant, then at the instant that offset gives.
+ */
+export declare function wallOffset(zone: string, wall: Wall): number | null;
+/** The instant a wall time names in a zone (the earlier one when a clock change skips it). */
+export declare const wallInstant: (zone: string, wall: Wall) => Date;
+export interface ParsedValue {
+    /** the day as stored (wall clock), or null when empty */
+    wall: Wall | null;
+    hasTime: boolean;
+    /** the stated offset in minutes ("Z" → 0); undefined for a floating time */
+    offset?: number;
+    /** an RFC 9557 [Zone] suffix, when valid */
+    zone?: string;
+    /** false: a value this control cannot read (an object, a word); it is shown and never overwritten by accident */
+    readable: boolean;
+}
+export declare function parseStored(v: unknown): ParsedValue;
+/** A stored value as a JS Date (drops the [Zone] annotation, which `new Date()` can't read). */
+export declare function storedToDate(v: unknown): Date | null;
+/** Every IANA zone this runtime knows, UTC included. */
+export declare const ALL_ZONES: readonly string[];
+/** The first zone (in order) whose offset at the instant is `offset`; undefined when none is. */
+export declare function zoneWithOffset(offset: number, instant: Date, candidates: readonly (string | undefined)[]): string | undefined;
+/**
+ * What the control shows for a stored value: the wall time and the zone it lives in.
+ *
+ *   - none: the stored wall time, as typed.
+ *   - site / fixed: that zone. A stored instant with another offset is shown as THAT instant's wall time in the zone,
+ *     so the shown and the saved time never disagree.
+ *   - pick: the stored [Zone]; else the zone the editor picked this session, the default, the browser's, then any
+ *     zone whose offset matches the stored one (a "+05:30" reads back as Kolkata). A floating time reads in the default.
+ */
+export declare function resolveShown(parsed: ParsedValue, mode: ZoneMode, zones: {
+    fixed?: string;
+    def: string;
+    picked?: string;
+}): {
+    wall: Wall | null;
+    zone: string;
+};
+export type WriteResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** The stored string for a wall time under the field's policy (file header). */
+export declare function writeValue(o: {
+    withTime: boolean;
+    mode: ZoneMode;
+    wall: Wall;
+    zone: string;
+}): WriteResult;
+/** Today in a zone (the browser's local day for a floating field). */
+export declare function todayIn(zone: string | undefined, now?: Date): string;