@bettercms-ai/types 1.50.1 → 1.51.0

package/dist/index.js

@@ -1,3 +1,30 @@
+// src/body-schema.ts
+var BODY_SCHEMA_ORIGINS = ["inferred", "confirmed", "authored"];
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var nonEmpty = (v) => typeof v === "string" && v.length > 0;
+function allowRuleOf(value) {
+  if (!isRecord(value)) return null;
+  switch (value.kind) {
+    case "source":
+      return nonEmpty(value.pageId) ? { kind: "source", pageId: value.pageId } : null;
+    case "component":
+      return nonEmpty(value.id) ? { kind: "component", id: value.id } : null;
+    case "family":
+      return nonEmpty(value.sectionType) ? { kind: "family", sectionType: value.sectionType } : null;
+    case "builtins":
+      return { kind: "builtins" };
+    case "workspace":
+      return { kind: "workspace" };
+    default:
+      return null;
+  }
+}
+function bodySchemaOf(value) {
+  if (!isRecord(value) || !Array.isArray(value.allowed)) return null;
+  const origin = BODY_SCHEMA_ORIGINS.includes(value.origin) ? value.origin : "authored";
+  return { allowed: value.allowed.map(allowRuleOf).filter((r) => r !== null), origin };
+}
+
 // src/block.ts
 var WINDOW_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/;
 function normalizeWindow(value) {
@@ -197,14 +224,14 @@ var BLOCK_BINDINGS = {
   ],
   tabs: [{ path: "tabs[].label", kind: "text" }]
 };
-var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function readPath(root, path) {
   let cursor = root;
   for (const segment of path.split(".")) {
     if (!segment) return void 0;
     const key = segment.replace(/\[\d+\]/g, "");
     if (key) {
-      if (!isRecord(cursor)) return void 0;
+      if (!isRecord2(cursor)) return void 0;
       cursor = cursor[key];
     }
     for (const index of segment.matchAll(/\[(\d+)\]/g)) {
@@ -229,7 +256,7 @@ function expandBlockBindings(block) {
   const declared = BLOCK_BINDINGS[block.type];
   if (!declared) return [];
   const props = block.props;
-  if (!isRecord(props)) return [];
+  if (!isRecord2(props)) return [];
   return declared.flatMap((binding) => expandTemplate(binding, props, binding.path)).filter((binding) => readPath(props, binding.path) !== void 0);
 }
 function formatPropsAttribute(entries) {
@@ -612,8 +639,8 @@ function slotItems(value) {
 // src/slot-child.ts
 var SLOT_CHILD_KEYS = ["_key", "_type", "_variant", "_settings"];
 var RESERVED = new Set(SLOT_CHILD_KEYS);
-var isRecord2 = (v) => !!v && typeof v === "object" && !Array.isArray(v);
-var isSlotChild = (v) => isRecord2(v) && typeof v._type === "string" && v._type !== "";
+var isRecord3 = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+var isSlotChild = (v) => isRecord3(v) && typeof v._type === "string" && v._type !== "";
 function slotChildValues(child) {
   const out = {};
   for (const [k, v] of Object.entries(child)) if (!RESERVED.has(k)) out[k] = v;
@@ -628,7 +655,7 @@ function slotShapeProblems(value, opts = {}) {
   if (opts.min !== void 0 && value.length < opts.min) out.push({ path: [], code: "slot_too_few", message: `slot_too_few: ${label} needs at least ${opts.min} blocks, got ${value.length}` });
   const keys = /* @__PURE__ */ new Set();
   value.forEach((child, i) => {
-    if (!isRecord2(child)) {
+    if (!isRecord3(child)) {
       out.push({ path: [i], code: "slot_value_invalid", message: `slot_value_invalid: ${label}: block ${i + 1} must be an object { _key, _type, ...values }` });
       return;
     }
@@ -646,7 +673,7 @@ function slotShapeProblems(value, opts = {}) {
     }
     if (child._settings !== void 0) {
       if (!opts.settings) out.push({ path: [i, "_settings"], code: "slot_settings_undeclared", message: `slot_settings_undeclared: ${label} declares no slotSettings, so a block holds no _settings` });
-      else if (!isRecord2(child._settings)) out.push({ path: [i, "_settings"], code: "slot_value_invalid", message: `slot_value_invalid: ${label}: _settings must be an object keyed by the slot's slotSettings` });
+      else if (!isRecord3(child._settings)) out.push({ path: [i, "_settings"], code: "slot_value_invalid", message: `slot_value_invalid: ${label}: _settings must be an object keyed by the slot's slotSettings` });
     }
     for (const k of Object.keys(child)) {
       if (k.startsWith("_") && !RESERVED.has(k)) {
@@ -3132,6 +3159,138 @@ var DOCK_ICON_NAMES = [
 ];
 var DOCK_ICON_NAME_SET = new Set(DOCK_ICON_NAMES);
 
+// src/help-catalog.ts
+var HELP_MAX = 160;
+var ROLE_HELP = {
+  // A top-level field's role in its section.
+  headline: "The page's main heading, one per page.",
+  heading: "The heading of this section.",
+  subheading: "Shown under the heading.",
+  eyebrow: "Short label shown above the heading.",
+  intro: "Shown under the heading. One or two sentences.",
+  paragraph: "A paragraph of text.",
+  text: "Text shown on the page.",
+  "primary-button": "The main call to action.",
+  "secondary-button": "The second call to action.",
+  button: "Its text, where it goes and how it looks.",
+  "button-label": "Text on the button. Two to four words works best.",
+  link: "Text of this link. Say where it leads.",
+  "home-link": "Takes visitors back to the home page.",
+  destination: "Pick a page or paste a full URL.",
+  image: "An image shown on the page.",
+  icon: "Optional icon before the label.",
+  logo: "An SVG or transparent PNG works best.",
+  "background-image": "Text sits on top of it, so a calm image works best.",
+  "video-poster": "Shown before the video plays.",
+  video: "Paste a link or upload an MP4.",
+  embed: "Paste the link the other site gives you to share it.",
+  audio: "Paste a link or upload an audio file.",
+  body: "Headings, paragraphs, lists and links, edited as one.",
+  content: "Headings, paragraphs, lists and links, edited as one.",
+  copyright: "Shown at the bottom of every page.",
+  email: "An email address, such as name@example.com.",
+  phone: "A phone number, with its country code.",
+  price: "Whole number, no currency symbol.",
+  percentage: "A number with its % sign.",
+  number: "A figure shown on the page.",
+  date: "A date, written as it should appear.",
+  "stat-value": "A figure shown large, such as 70k+.",
+  "stat-label": "What the figure counts.",
+  quote: "Without quote marks.",
+  attribution: "Who said it.",
+  caption: "Shown under the image.",
+  label: "A short label.",
+  summary: "Shown in lists and previews.",
+  address: "The postal address, as it should appear.",
+  code: "Shown exactly as written.",
+  term: "The word or phrase being explained.",
+  definition: "What the term means.",
+  "table-heading": "Heading of a table column.",
+  "table-cell": "One cell of the table.",
+  "list-item": "One item of the list.",
+  list: "One item per row.",
+  links: "One link per row.",
+  band: "All the text of this section, edited as one.",
+  // A column's role in its row.
+  title: "The title of this item.",
+  subtitle: "Shown under the title.",
+  description: "One line under the name.",
+  value: "The value shown for this item.",
+  // What a band's shape calls an element.
+  "plan-name": "Short name of this plan, shown at the top of its card.",
+  cents: "Digits after the decimal point.",
+  "billing-period": "How often the price is charged.",
+  // The parts of a plan's price object.
+  amount: "Whole number, no currency symbol.",
+  period: "How often the price is charged.",
+  badge: "Optional. Two or three words that make this plan stand out.",
+  features: "One feature per row.",
+  question: "One question, as a customer would ask it.",
+  answer: "Shown when the question is opened.",
+  author: "The person's full name.",
+  role: "Their job title and company.",
+  // What an attribute is, by what carries it.
+  tooltip: "Shown when the pointer rests on it.",
+  placeholder: "Shown in the empty input.",
+  "image-description": "Read by screen readers, not shown on the page.",
+  "counter-target": "The number the counter runs up to.",
+  attribute: "A setting of this element, not shown as text.",
+  "navigation-label": "Read by screen readers, not shown on the page.",
+  "link-label": "Read by screen readers, not shown on the page.",
+  "image-label": "Read by screen readers, not shown on the page.",
+  "field-label": "Read by screen readers, not shown on the page.",
+  "header-label": "Read by screen readers, not shown on the page.",
+  "footer-label": "Read by screen readers, not shown on the page.",
+  "aside-label": "Read by screen readers, not shown on the page.",
+  "section-label": "Read by screen readers, not shown on the page.",
+  "heading-label": "Read by screen readers, not shown on the page.",
+  // What a list's rows are.
+  plans: "One plan per card.",
+  questions: "One question and its answer per row.",
+  quotes: "One quote per row, with who said it.",
+  testimonials: "One quote per row, with who said it.",
+  stats: "One figure per row, with what it counts.",
+  logos: "One logo per row.",
+  cards: "One card per row.",
+  items: "One item per row."
+};
+var CANVAS_GESTURE_NAMES = ["rows.reorder", "image.replace", "link.popover", "text.inline"];
+var CONTROL_HELP = {
+  rows: { text: "Drag to reorder. You can also drag rows on the canvas.", gesture: "rows.reorder" },
+  image: { text: "You can also click it on the canvas to replace it.", gesture: "image.replace" },
+  link: { text: "Click it on the canvas to change where it goes.", gesture: "link.popover" },
+  text: { text: "You can also edit it on the canvas.", gesture: "text.inline" }
+};
+var EXAMPLE_MAX = 40;
+function sayOf(value) {
+  if (typeof value === "number") return String(value);
+  const v = value;
+  const raw = typeof value === "string" ? value : typeof v?.html === "string" ? v.html : typeof v?.label === "string" ? v.label : typeof v?.text === "string" ? v.text : "";
+  return raw.replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+var quotable = (s) => s !== "" && s.length <= EXAMPLE_MAX && !s.includes('"');
+function exampleFor(column, rows, i) {
+  const at = (j) => {
+    const row = rows[j];
+    return row && typeof row === "object" ? sayOf(row[column]) : "";
+  };
+  const own2 = at(i);
+  for (let d = 1; d < rows.length; d += 1) {
+    for (const j of [i - d, i + d]) {
+      if (j < 0 || j >= rows.length) continue;
+      const v = at(j);
+      if (v !== own2 && quotable(v)) return `e.g. "${v}"`;
+    }
+  }
+  return quotable(own2) ? `e.g. "${own2}"` : void 0;
+}
+function withExample(help, example) {
+  if (!example) return help;
+  if (!help) return example;
+  const joined = `${help} ${example}`;
+  return joined.length <= HELP_MAX ? joined : help;
+}
+
 // src/dock-budget.ts
 var DOCK_BUDGET = { ungrouped: 8, group: 12, depth: 3, activations: 2 };
 function listItems(f) {
@@ -3152,10 +3311,10 @@ function layout(fields, fieldsets, root) {
   const byId = new Map(fieldsets.map((s) => [s.id, s]));
   const tabIds = root ? fieldsets.filter((s) => s.kind === "tab").map((s) => s.id) : [];
   const tabOf = (s) => s?.kind === "tab" ? s.id : s?.tab !== void 0 && byId.get(s.tab)?.kind === "tab" ? s.tab : void 0;
-  const nonEmpty = new Set(
+  const nonEmpty2 = new Set(
     fields.map((f) => tabOf(byId.get(f.fieldsetId ?? ""))).filter((t) => t && tabIds.includes(t))
   );
-  const strip2 = nonEmpty.size >= 2;
+  const strip2 = nonEmpty2.size >= 2;
   const branches = /* @__PURE__ */ new Map();
   const nodeFor = (f, path) => {
     const key = `${path}${f.key}`;
@@ -3176,7 +3335,7 @@ function layout(fields, fieldsets, root) {
     return { kind: "leaf", key };
   };
   const pinned = [];
-  const panels = new Map(strip2 ? tabIds.filter((t) => nonEmpty.has(t)).map((t) => [t, []]) : []);
+  const panels = new Map(strip2 ? tabIds.filter((t) => nonEmpty2.has(t)).map((t) => [t, []]) : []);
   const containers = /* @__PURE__ */ new Map();
   for (const f of fields) {
     const node = nodeFor(f, "");
@@ -3381,6 +3540,19 @@ function buttonLinkPairs(candidates) {
   return [...proposals.values()].filter(([t, l]) => !ambiguous.has(t) && !ambiguous.has(l) && uses.get(t) === 1 && uses.get(l) === 1).sort((a, b) => Math.min(...a) - Math.min(...b));
 }
 
+// src/link-pairs.ts
+var LINK_TYPES2 = /* @__PURE__ */ new Set(["link", "url"]);
+var nameOf = (s) => s.name ?? s.key;
+function rulePartnerOf(labelKey, siblings) {
+  const names = labelKey === "label" ? ["label-href", "href", "url", "link"] : [`${labelKey}-href`];
+  for (const n of names) {
+    const s = siblings.find((f) => nameOf(f) === n);
+    if (s && LINK_TYPES2.has(s.type ?? "")) return n;
+  }
+  return null;
+}
+var isRulePaired = (labelKey, siblings) => rulePartnerOf(labelKey, siblings) !== null;
+
 // src/button-look.ts
 import { ICON_MARKUP, iconSvg } from "@bettercms-ai/icons/markup";
 
@@ -4184,6 +4356,14 @@ function locatorFor(el, region, landmarks = false) {
     tag: el.tagName.toLowerCase()
   };
 }
+function locatorPath(el, landmarks = false) {
+  const path = [];
+  for (let parent = el.parentElement; parent && parent.tagName !== "BODY" && !isChromeLandmark(parent, landmarks); parent = parent.parentElement) {
+    path.unshift(parent.parentElement ? Math.max(Array.from(parent.parentElement.children).indexOf(parent), 0) : 0);
+  }
+  return path;
+}
+var LOCATOR_PATH = /* @__PURE__ */ Symbol.for("bcms.locator.path");
 function landmarkRegions(doc, dialogs = false, landmarks = false) {
   const counts = /* @__PURE__ */ new Map();
   const out = [];
@@ -4244,9 +4424,81 @@ var TAG_HEADS = /* @__PURE__ */ new Set([
   "icon",
   "bg"
 ]);
+var ROLE_KEYS = /* @__PURE__ */ new Set([
+  "headline",
+  "heading",
+  "subheading",
+  "eyebrow",
+  "intro",
+  "paragraph",
+  "text",
+  "primary-button",
+  "secondary-button",
+  "button",
+  "link",
+  "home-link",
+  "image",
+  "icon",
+  "logo",
+  "background-image",
+  "video-poster",
+  "video",
+  "embed",
+  "audio",
+  "body",
+  "content",
+  "copyright",
+  "email",
+  "phone",
+  "price",
+  "percentage",
+  "number",
+  "date",
+  "stat-value",
+  "stat-label",
+  "quote",
+  "attribution",
+  "caption",
+  "label",
+  "summary",
+  "address",
+  "code",
+  "term",
+  "definition",
+  "table-heading",
+  "table-cell",
+  "list-item",
+  "title",
+  "subtitle",
+  "description",
+  "value",
+  "list",
+  "plan-name",
+  "cents",
+  "billing-period",
+  "badge",
+  "features",
+  "question",
+  "answer",
+  "author",
+  "role",
+  "tooltip",
+  "placeholder",
+  "image-description",
+  "counter-target",
+  "amount",
+  "period"
+]);
+var ROLE_TAILS = /(?:-label)?(?:-[a-z])?(?:-\d+)?(?:-href)?$/;
+function isRoleKey(key) {
+  if (ROLE_KEYS.has(key)) return true;
+  const tail = ROLE_TAILS.exec(key);
+  return !!tail && tail[0] !== "" && ROLE_KEYS.has(key.slice(0, tail.index));
+}
 var topFieldKeyOf = (path) => path.split(/[.[]/, 1)[0] ?? path;
 function fieldGroupOf(topKey, flat = false) {
   if (topKey.startsWith("group-")) return { groupKey: topKey, rooted: true };
+  if (isRoleKey(topKey)) return { groupKey: topKey, rooted: false };
   const camel = flat ? /^([a-z][a-z0-9]*)[A-Z]/.exec(topKey)?.[1] : void 0;
   if (camel) return TAG_HEADS.has(camel) ? { groupKey: topKey, rooted: false } : { groupKey: camel, rooted: true };
   const head = topKey.split(/[-_]/, 1)[0] || topKey;
@@ -4300,6 +4552,7 @@ function planSections(slots, blocks) {
 }
 export {
   BLOCK_BINDINGS,
+  BODY_SCHEMA_ORIGINS,
   BREAKPOINTS,
   BUTTON_ACTIONS,
   BUTTON_FULL_WIDTH_INVALID,
@@ -4309,8 +4562,10 @@ export {
   BUTTON_PLACEMENT_KEYS,
   BUTTON_SIZES,
   BUTTON_VARIANTS,
+  CANVAS_GESTURE_NAMES,
   CODE_SLOT_PREFIX,
   COMPONENT_PROP_TYPES,
+  CONTROL_HELP,
   DIALOG_SELECTOR,
   DOCK_BUDGET,
   DOCK_ICON_NAMES,
@@ -4318,6 +4573,7 @@ export {
   FIELD_SIZE_ZOOM,
   FIELD_STYLE_KEYS,
   FOOTER_SECTION_ID,
+  HELP_MAX,
   IMAGE_ASPECTS,
   IMAGE_FRAME_RADIUS,
   LANDMARK_SELECTOR,
@@ -4326,11 +4582,14 @@ export {
   LINK_RELS,
   LINK_VALUE_TYPES,
   LIST_ITEMS_CAP,
+  LOCATOR_PATH,
   MAIN_SELECTOR,
   NAVIGATION_SECTION_ID,
   OPTION_DESCRIPTION_MAX,
   PAGE_CONTENT_ANCHOR_ID,
   RESPONSIVE_CSS,
+  ROLE_HELP,
+  ROLE_KEYS,
   SECTION_DOCTRINE,
   SECTION_SPACE_TOKENS,
   SIDE_SPACE_MIN_PX,
@@ -4347,10 +4606,12 @@ export {
   TAG_HEADS,
   VIDEO_TRANSCRIPT_MAX,
   VIDEO_VALUE_KEYS,
+  allowRuleOf,
   anchorTargetRel,
   blockStyleToColumnCss,
   blockStyleToCss,
   blockStyleToInnerCss,
+  bodySchemaOf,
   buttonBlockProps,
   buttonFullWidthProblem,
   buttonIconOf,
@@ -4367,6 +4628,7 @@ export {
   derivedPairs,
   dockBudget,
   dockScreens,
+  exampleFor,
   expandBlockBindings,
   fieldGroupOf,
   fieldStyleCssText,
@@ -4384,6 +4646,8 @@ export {
   isChromeLandmark,
   isCodeButton,
   isLinkObject,
+  isRoleKey,
+  isRulePaired,
   isScriptHref,
   isSlotChild,
   isTableValue,
@@ -4394,6 +4658,7 @@ export {
   linkRefOf,
   linkValueProblem,
   locatorFor,
+  locatorPath,
   normalizeLinkValue,
   normalizeTableValue,
   normalizeWindow,
@@ -4407,6 +4672,7 @@ export {
   readPath,
   regionOf,
   renderTableHtml,
+  rulePartnerOf,
   safeCssUrl,
   sideFloorApplies,
   sideSpaceCss,
@@ -4431,6 +4697,7 @@ export {
   visibleDeliveredLayout,
   visibleLayoutStructure,
   windowState,
-  withButtonLookProps
+  withButtonLookProps,
+  withExample
 };
 //# sourceMappingURL=index.js.map