@bettercms-ai/kit 0.1.1 → 2.0.0

package/dist/controls/json.js

@@ -0,0 +1,82 @@
+import { useKitEnv } from "../context.js";
+import { CodeDialogField, CodeSurface, jsonProblem } from "./code.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/controls/json.tsx
+/**
+* JSON — the json field (DESIGN 8.21), on the code surface (code.tsx).
+*
+* Values: whatever JSON the field holds (an object, a list, a number, or a JSON string a textarea wrote). An edit is
+* written PARSED, the way the classic JsonField writes it, and an emptied box writes null; the backend takes both.
+* Text that does not parse is never written: the panel's Done refuses with "Invalid JSON · {reason}", the inline
+* (document) surface keeps the last valid value and shows the reason under the code.
+*/
+/** The text a stored JSON value is edited as. A stored string that is JSON text stays as written; any other string is a
+*  JSON string value, so it reads as its literal ("hello" → `"hello"`), never as "Invalid JSON". */
+var jsonText = (v) => {
+	if (v == null || v === "") return "";
+	if (typeof v !== "string") return JSON.stringify(v, null, 2);
+	try {
+		JSON.parse(v);
+		return v;
+	} catch {
+		return JSON.stringify(v);
+	}
+};
+var parse = (text) => text.trim() ? JSON.parse(text) : null;
+function JsonControl({ field, value, onChange, readOnly, id, invalid }) {
+	const { variant } = useKitEnv();
+	const text = jsonText(value);
+	if (variant === "document") return /* @__PURE__ */ jsx(InlineJson, {
+		id,
+		value,
+		text,
+		onChange,
+		readOnly,
+		invalid
+	});
+	return /* @__PURE__ */ jsx(CodeDialogField, {
+		kind: "json",
+		id,
+		title: field.title,
+		description: field.description || void 0,
+		text,
+		readOnly,
+		invalid,
+		onDone: (draft) => {
+			if (draft === text) return null;
+			const why = jsonProblem(draft);
+			if (why) return `Invalid JSON · ${why}`;
+			if (draft !== text) onChange(parse(draft));
+			return null;
+		}
+	});
+}
+/** The document variant: the surface inline over a draft that survives invalid intermediates. */
+function InlineJson({ id, value, text, onChange, readOnly, invalid }) {
+	const [draft, setDraft] = React.useState(text);
+	const [mine, setMine] = React.useState(void 0);
+	const [seen, setSeen] = React.useState(value);
+	if (value !== seen) {
+		setSeen(value);
+		if (value !== mine) setDraft(text);
+	}
+	return /* @__PURE__ */ jsx(CodeSurface, {
+		kind: "json",
+		id,
+		invalid,
+		readOnly,
+		value: draft,
+		onChange: (next) => {
+			setDraft(next);
+			if (jsonProblem(next)) return;
+			const parsed = parse(next);
+			setMine(parsed);
+			onChange(parsed);
+		}
+	});
+}
+//#endregion
+export { JsonControl };
+
+//# sourceMappingURL=json.js.map

package/dist/controls/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","names":[],"sources":["../../src/controls/json.tsx"],"sourcesContent":["/**\n * JSON — the json field (DESIGN 8.21), on the code surface (code.tsx).\n *\n * Values: whatever JSON the field holds (an object, a list, a number, or a JSON string a textarea wrote). An edit is\n * written PARSED, the way the classic JsonField writes it, and an emptied box writes null; the backend takes both.\n * Text that does not parse is never written: the panel's Done refuses with \"Invalid JSON · {reason}\", the inline\n * (document) surface keeps the last valid value and shows the reason under the code.\n */\nimport * as React from \"react\";\nimport { useKitEnv } from \"../context\";\nimport type { ControlProps } from \"../types\";\nimport { CodeDialogField, CodeSurface, jsonProblem } from \"./code\";\n\n/** The text a stored JSON value is edited as. A stored string that is JSON text stays as written; any other string is a\n *  JSON string value, so it reads as its literal (\"hello\" → `\"hello\"`), never as \"Invalid JSON\". */\nconst jsonText = (v: unknown): string => {\n  if (v == null || v === \"\") return \"\";\n  if (typeof v !== \"string\") return JSON.stringify(v, null, 2);\n  try {\n    JSON.parse(v);\n    return v;\n  } catch {\n    return JSON.stringify(v);\n  }\n};\nconst parse = (text: string): unknown => (text.trim() ? JSON.parse(text) : null);\n\nexport function JsonControl({ field, value, onChange, readOnly, id, invalid }: ControlProps) {\n  const { variant } = useKitEnv();\n  const text = jsonText(value);\n  if (variant === \"document\") return <InlineJson id={id} value={value} text={text} onChange={onChange} readOnly={readOnly} invalid={invalid} />;\n  return (\n    <CodeDialogField\n      kind=\"json\"\n      id={id}\n      title={field.title}\n      description={field.description || undefined}\n      text={text}\n      readOnly={readOnly}\n      invalid={invalid}\n      onDone={(draft) => {\n        if (draft === text) return null; // nothing edited: Done closes even over a stored string that isn't JSON\n        const why = jsonProblem(draft);\n        if (why) return `Invalid JSON · ${why}`;\n        if (draft !== text) onChange(parse(draft));\n        return null;\n      }}\n    />\n  );\n}\n\n/** The document variant: the surface inline over a draft that survives invalid intermediates. */\nfunction InlineJson({ id, value, text, onChange, readOnly, invalid }: { id: string; value: unknown; text: string; onChange: (v: unknown) => void; readOnly?: boolean; invalid?: boolean }) {\n  const [draft, setDraft] = React.useState(text);\n  const [mine, setMine] = React.useState<unknown>(undefined);\n  const [seen, setSeen] = React.useState(value);\n  // a value set from elsewhere (undo, another editor) replaces the draft; our own writes keep the author's text\n  if (value !== seen) {\n    setSeen(value);\n    if (value !== mine) setDraft(text);\n  }\n  return (\n    <CodeSurface\n      kind=\"json\"\n      id={id}\n      invalid={invalid}\n      readOnly={readOnly}\n      value={draft}\n      onChange={(next) => {\n        setDraft(next);\n        if (jsonProblem(next)) return;\n        const parsed = parse(next);\n        setMine(parsed);\n        onChange(parsed);\n      }}\n    />\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,IAAM,YAAY,MAAuB;CACvC,IAAI,KAAK,QAAQ,MAAM,IAAI,OAAO;CAClC,IAAI,OAAO,MAAM,UAAU,OAAO,KAAK,UAAU,GAAG,MAAM,CAAC;CAC3D,IAAI;EACF,KAAK,MAAM,CAAC;EACZ,OAAO;CACT,QAAQ;EACN,OAAO,KAAK,UAAU,CAAC;CACzB;AACF;AACA,IAAM,SAAS,SAA2B,KAAK,KAAK,IAAI,KAAK,MAAM,IAAI,IAAI;AAE3E,SAAgB,YAAY,EAAE,OAAO,OAAO,UAAU,UAAU,IAAI,WAAyB;CAC3F,MAAM,EAAE,YAAY,UAAU;CAC9B,MAAM,OAAO,SAAS,KAAK;CAC3B,IAAI,YAAY,YAAY,OAAO,oBAAC,YAAD;EAAgB;EAAW;EAAa;EAAgB;EAAoB;EAAmB;CAAU,CAAA;CAC5I,OACE,oBAAC,iBAAD;EACE,MAAK;EACD;EACJ,OAAO,MAAM;EACb,aAAa,MAAM,eAAe,KAAA;EAC5B;EACI;EACD;EACT,SAAS,UAAU;GACjB,IAAI,UAAU,MAAM,OAAO;GAC3B,MAAM,MAAM,YAAY,KAAK;GAC7B,IAAI,KAAK,OAAO,kBAAkB;GAClC,IAAI,UAAU,MAAM,SAAS,MAAM,KAAK,CAAC;GACzC,OAAO;EACT;CACD,CAAA;AAEL;;AAGA,SAAS,WAAW,EAAE,IAAI,OAAO,MAAM,UAAU,UAAU,WAAgI;CACzL,MAAM,CAAC,OAAO,YAAY,MAAM,SAAS,IAAI;CAC7C,MAAM,CAAC,MAAM,WAAW,MAAM,SAAkB,KAAA,CAAS;CACzD,MAAM,CAAC,MAAM,WAAW,MAAM,SAAS,KAAK;CAE5C,IAAI,UAAU,MAAM;EAClB,QAAQ,KAAK;EACb,IAAI,UAAU,MAAM,SAAS,IAAI;CACnC;CACA,OACE,oBAAC,aAAD;EACE,MAAK;EACD;EACK;EACC;EACV,OAAO;EACP,WAAW,SAAS;GAClB,SAAS,IAAI;GACb,IAAI,YAAY,IAAI,GAAG;GACvB,MAAM,SAAS,MAAM,IAAI;GACzB,QAAQ,MAAM;GACd,SAAS,MAAM;EACjB;CACD,CAAA;AAEL"}

package/dist/controls/link.d.ts

@@ -0,0 +1,260 @@
+/**
+ * LINK — the ONE link element of the product (V2 HEAD kit/controls/link.tsx, DESIGN §8.7, CPO D43 · D48 · D57).
+ *
+ *  - <LinkForm>        Type (Page · CMS item · URL · Email · Phone · Section · File) → the target for that type (search over
+ *                      the host's pages and CMS items, paste detection, URL / email / phone / #anchor validation; File =
+ *                      the host's media library) → Section on the picked page → options (new tab · rel · email subject).
+ *  - <LinkPopoverBody> the link panel: what it links to now + LinkForm + Remove link · Cancel · Apply.
+ *  - <LinkField>       a link at rest (one bordered row): click edits in place (quick edit), the sliders icon opens the panel.
+ *  - <LinkPicker>      the target input inside all of the above.
+ *  - <LinkLine>        how a link READS at rest: page icon + title + path · external icon + domain · mail / phone.
+ *
+ * Where the targets come from. The kit never fetches: the host hands its own link-target query in as a React hook,
+ * `KitServices.useLinkTargets` (KitLinkServices below), and the media library as `KitServices.MediaPicker`. With no hook a
+ * page link is typed as a path and the list says so in words; with no media picker the File type is not offered.
+ * Section anchors come from the host that knows the page (SectionAnchorsProvider); without one a section is typed (#faq).
+ *
+ * Stored shape (prod `link`, adapters/values.ts linkToProd / linkFromProd). The kit value is what the field already
+ * stores: a STRING href stays a string (legacy fields and the sites that read `href={link}`), an object stays an object.
+ * An empty field takes `field.valueShape` and, with none, the string (prod LinkField's default). In the string shape the
+ * options (new tab, rel) need the object, so they hide — V2's `valueShape="string"`. An object never carries `target`
+ * (derived from newTab), `rel: "follow"` (follow = no rel) or `newTab: false`, so it reads back exactly as written.
+ *
+ * Deviations from V2, each because prod has no source for it: no "From this entry" {{token}} targets (no binding store
+ * behind them), no seeded page anchors, no fabricated CDN address for a file (a file without a public url is refused).
+ */
+import * as React from "react";
+import { type KitMediaAsset, type KitServices } from "../context";
+import type { ControlProps } from "../types";
+export type LinkType = "page" | "url" | "section" | "email" | "phone" | "file" | "entry";
+export type LinkRel = "follow" | "nofollow" | "ugc" | "sponsored";
+export type ButtonStyle = "primary" | "secondary" | "outline" | "link";
+export interface LinkValue {
+    type?: LinkType;
+    href: string;
+    /** button label / link text */
+    label?: string;
+    /** resolved title of the target (page or entry name) */
+    title?: string;
+    pageId?: string;
+    entryId?: string;
+    anchor?: string;
+    assetId?: string;
+    email?: string;
+    subject?: string;
+    phone?: string;
+    /** legacy target: read as newTab, never written */
+    target?: "_self" | "_blank";
+    newTab?: boolean;
+    rel?: LinkRel;
+    style?: ButtonStyle;
+    variant?: string;
+    size?: "sm" | "md" | "lg";
+    arrow?: boolean;
+    icon?: string;
+    fullWidth?: boolean;
+}
+/** A place a link can point at, as the host lists it. */
+export interface LinkTarget {
+    id: string;
+    title: string;
+    /** the public path ("/about", "/blog/hello") or a file's url */
+    href: string;
+    kind: "page" | "entry" | "file" | "section";
+    /** collection name for an entry, file kind for a file */
+    meta?: string;
+    /** list group: "Pages", the collection's name, "Files", "On this page" */
+    group: string;
+    /** draft · published · scheduled · archived … (shown when it is not live) */
+    status?: string;
+    /** "#faq" anchors on that page, when the host knows them */
+    anchors?: string[];
+    /** a section without an anchor yet gets it when picked */
+    onChoose?: () => void;
+}
+/**
+ * The link services a host provides next to KitServices (registerKitServices / KitServicesProvider take them as is).
+ * `useLinkTargets` is a React HOOK (called on every render of a link control), so a host passes the same function for
+ * the life of the form.
+ */
+export type KitLinkServices = Pick<KitServices, "useLinkTargets">;
+type LinkHost = {
+    targets: LinkTarget[];
+    loading: boolean;
+    error?: string;
+    unavailable: boolean;
+};
+/** The host's pages, CMS items (and files, when it lists them). */
+export declare function useLinkTargets(): LinkHost;
+/** A section on the page being edited that a link can jump to (`id` on the block). */
+export interface SectionAnchor {
+    /** "#faq" */
+    anchor: string;
+    /** what a person reads: the block's name */
+    label: string;
+    /** the block has no anchor yet: give it this one when a link picks it */
+    ensure?: () => void;
+}
+/** The host that knows the page being edited lists its section anchors, so the Section type is a pick. */
+export declare function SectionAnchorsProvider({ anchors, children }: {
+    anchors: SectionAnchor[];
+    children: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** A file from the media library as a link target, or the reason it can't be one. */
+export declare function fileTarget(a: Pick<KitMediaAsset, "id" | "name" | "url">): LinkTarget | {
+    problem: string;
+};
+export declare const normLink: (v: unknown) => LinkValue;
+export declare function detectType(raw: string): LinkType;
+export declare const LINK_TYPES: {
+    type: LinkType;
+    label: string;
+    icon: React.ReactNode;
+    placeholder: string;
+    target: string;
+}[];
+/** The target a value points at: by id first, then by an exact path ("/about" typed by hand still reads as About). */
+export declare function findTarget(targets: LinkTarget[], v: LinkValue): LinkTarget | undefined;
+/** The final href for a link value. */
+export declare function hrefOf(v: LinkValue): string;
+/** Why a link can't be saved yet, in plain words. Undefined when it is fine (or empty). */
+export declare function linkProblem(v: LinkValue): string | undefined;
+/** One list for every link editor (dropdown, never a segmented row — D40). */
+export declare const REL_ITEMS: {
+    value: LinkRel;
+    label: string;
+    description: string;
+}[];
+export declare const hasLink: (v: LinkValue) => boolean;
+export declare const TARGET_KEYS: {
+    readonly title: undefined;
+    readonly pageId: undefined;
+    readonly entryId: undefined;
+    readonly assetId: undefined;
+    readonly anchor: undefined;
+};
+/** The value a picked target produces (keeps label, style and options). */
+export declare function withTarget(v: LinkValue, t: LinkTarget): LinkValue;
+/** The value typed text produces (auto-detects URL / email / phone / #section unless the type was chosen). */
+export declare function withText(v: LinkValue, s: string, type?: LinkType): LinkValue;
+/** Clean a value before it is stored: add https:// to bare domains, refuse script URLs, store the href the site renders. */
+export declare function finalizeLink(v: LinkValue): LinkValue | null;
+/**
+ * The object as prod stores it, keyed like the value it replaces (`original`), so an edit changes only what was edited:
+ * no undefined keys; no `rel: "follow"` (follow is no rel: the backend normalises it away and a button refuses it); no
+ * `newTab: false` and no `target` unless the stored value had that key (a stored `target` is kept in sync with newTab,
+ * and is then the one that carries it).
+ */
+export declare function storedLink<T extends LinkValue>(v: T, original?: unknown): T;
+export declare function linkIcon(v: LinkValue, target?: LinkTarget): React.ReactNode;
+/** Primary + secondary text: page title + path · domain + rest of the URL · address · number. */
+export declare function describeLink(v: LinkValue, target?: LinkTarget): {
+    primary: string;
+    secondary?: string;
+};
+/** What a person reads for a link (one string — menus, aria labels, history). */
+export declare const linkText: (v: LinkValue) => string;
+/** A link at rest: icon · title (fg) · path (fg-3) · new-tab mark. Empty → "Add link". */
+export declare function LinkLine({ v, target, placeholder, className }: {
+    v: LinkValue;
+    target?: LinkTarget;
+    placeholder?: string;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export interface LinkPickerProps {
+    value: LinkValue;
+    /** every change: typed text, a picked target, a cleared value */
+    onChange: (v: LinkValue) => void;
+    /** a target was chosen from the list (quick editors commit here) */
+    onPick?: (v: LinkValue) => void;
+    /** Enter with no list row active */
+    onEnter?: (v: LinkValue) => void;
+    /** Escape with the list closed */
+    onEscape?: () => void;
+    autoFocus?: boolean;
+    /** open straight into search (quick edit), even when a target is picked */
+    startSearching?: boolean;
+    id?: string;
+    "aria-label"?: string;
+    size?: "sm" | "md";
+    /** no border of its own — it sits inside a unit that already draws one (button field) */
+    bare?: boolean;
+    /** the host shows its own type control (link panel): hide the inline type menu and search only this type */
+    lockedType?: LinkType;
+    /** results render in the flow under the input instead of a floating list — panels/popovers, never over them */
+    inlineList?: boolean;
+    /** the link types this place allows. Default: all of them */
+    types?: LinkType[];
+    /** the value can't be saved as it is (shown as the field's error state) */
+    invalid?: boolean;
+    "aria-describedby"?: string;
+    className?: string;
+}
+export declare function LinkPicker({ value, onChange, onPick, onEnter, onEscape, autoFocus, startSearching, id, "aria-label": ariaLabel, size, bare, lockedType, inlineList, types, invalid, "aria-describedby": describedBy, className, }: LinkPickerProps): import("react/jsx-runtime").JSX.Element;
+export declare function LinkOptions({ v, onChange, compact, disabled }: {
+    v: LinkValue;
+    onChange: (v: LinkValue) => void;
+    compact?: boolean;
+    disabled?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function LinkForm({ value, onChange, onEnter, hideOptions, types, autoFocus, readOnly, className, }: {
+    value: LinkValue;
+    onChange: (v: LinkValue) => void;
+    /** Enter in the target with a value that can be saved */
+    onEnter?: (v: LinkValue) => void;
+    /** string-only values: no new tab / rel */
+    hideOptions?: boolean;
+    /** the link types this place allows. Default: all */
+    types?: LinkType[];
+    /** focus the Type control on open (D48: never the search) */
+    autoFocus?: boolean;
+    /** the lens can't edit the link: every control is disabled */
+    readOnly?: boolean;
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function LinkPopoverBody({ initial, onSave, onDetach, onCancel, hideOptions, types, }: {
+    initial: LinkValue;
+    onSave: (v: LinkValue) => void;
+    onDetach?: () => void;
+    onCancel?: () => void;
+    /** string-only fields: no new tab / rel */
+    hideOptions?: boolean;
+    /** the link types this place allows. Default: all */
+    types?: LinkType[];
+}): import("react/jsx-runtime").JSX.Element;
+export declare function LinkQuickEdit({ value, onCommit, onDone, ariaLabel, size, bare, types, }: {
+    value: LinkValue;
+    /** null = cleared */
+    onCommit: (v: LinkValue | null) => void;
+    onDone: () => void;
+    ariaLabel: string;
+    size?: "sm" | "md";
+    bare?: boolean;
+    types?: LinkType[];
+}): import("react/jsx-runtime").JSX.Element;
+export interface LinkFieldProps {
+    /** a LinkValue or a plain href string */
+    value: unknown;
+    /** null = cleared (object shape); "" = cleared (string shape) */
+    onChange: (v: LinkValue | string | null) => void;
+    /** "string": the value is the href alone. New tab and rel need the object shape, so they hide. */
+    valueShape?: "string" | "object";
+    id?: string;
+    "aria-label": string;
+    readOnly?: boolean;
+    size?: "sm" | "md";
+    /** the link types this place allows. Default: all */
+    types?: LinkType[];
+    invalid?: boolean;
+    placeholder?: string;
+    className?: string;
+}
+export declare function LinkField({ value, onChange: write, valueShape, id: idProp, "aria-label": label, readOnly, size, types, invalid, placeholder, className }: LinkFieldProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The shape a link field writes: the shape its value already has (a string stays a string, an object an object), and
+ * for an empty field `field.valueShape`, else the string prod stores by default.
+ */
+export declare function linkShapeOf(value: unknown, valueShape?: "string" | "object"): "string" | "object";
+/** The Block Kit `link` field: the LinkField above, sized for the form it sits in. */
+export declare function LinkControl({ value, onChange, readOnly, id, field, invalid }: ControlProps): import("react/jsx-runtime").JSX.Element;
+export {};