@bettercms-ai/types 1.50.2 → 1.51.0

package/dist/index.d.ts

@@ -574,7 +574,7 @@ type ZoneField = ContentModelField;
  * wording improves), a person in the dashboard (`human`) or an agent over the API (`agent`). Only
  * `auto` text is ever replaced. Server-owned: a client's copy is ignored.
  */
-type HelpSource = "auto" | "human" | "agent";
+type HelpSource = "auto" | "site" | "human" | "agent";
 
 /**
  * Page — a published content page within a workspace.
@@ -1860,7 +1860,7 @@ interface LayoutFieldDefinition {
     /** Shown to editors under the field. */
     helpText?: string;
     /** Server-owned: who wrote `helpText`. */
-    helpSource?: "auto" | "human" | "agent";
+    helpSource?: "auto" | "site" | "human" | "agent";
     /** `true`: no route the last release inspected renders this field — hidden, never deleted. `false`: a person keeps it shown. */
     stale?: boolean;
     /** false: a page may not override this value; the Global value renders on every page. Absent = true. */
@@ -2361,7 +2361,7 @@ interface ComponentPropDef {
     /** Hint shown under the control, muted. */
     helpText?: string;
     /** Server-owned: who wrote `helpText`. */
-    helpSource?: "auto" | "human" | "agent";
+    helpSource?: "auto" | "site" | "human" | "agent";
     /** Ghost text inside a text-ish control. */
     placeholder?: string;
     /**
@@ -2540,7 +2540,7 @@ interface ComponentSubField {
     /** The same editor hints as the prop above, one level down. @see ComponentPropDef */
     required?: boolean;
     helpText?: string;
-    helpSource?: "auto" | "human" | "agent";
+    helpSource?: "auto" | "site" | "human" | "agent";
     placeholder?: string;
     options?: Array<string | ChoiceOption>;
     /** The V2 editor keys, one level down. `showIf` names SIBLING sub-fields. @see ComponentPropDef */
@@ -2785,6 +2785,53 @@ declare function slotShapeProblems(value: unknown, opts?: SlotShapeOptions): Slo
 /** `rows[2]._key`-style path text for a problem path. */
 declare const slotPathString: (path: Array<string | number>) => string;
 
+/**
+ * What the dock says under a field, as data both sides read: the backend's generator
+ * (src/lib/content/help-text.ts) writes the role sentence and the control's how-to into the
+ * stored `helpText`; the dashboard adds a list column's example per row ({@link exampleFor}),
+ * because the example depends on WHICH row is open and a stored line has one value for all rows.
+ *
+ * A field's help, joined with single spaces, at most {@link HELP_MAX} characters (two dock lines):
+ *   1. a role sentence (@see ROLE_HELP), or the site's own words where the markup has them;
+ *   2. the control's how-to (@see CONTROL_HELP), only where the canvas has the gesture it names;
+ *   3. for a column of a list, `e.g. "<value>"` from the nearest OTHER row.
+ *
+ * Pure. No DOM, no I/O.
+ */
+/** Two dock lines at 12px in a ~250px column. */
+declare const HELP_MAX = 160;
+/**
+ * What one role holds, said once: the role words a structural key ends in (@see ROLE_KEYS in
+ * sections.ts, and the server's ROLE_VOCABULARY), plus the words a band's shape and a list give.
+ * Never the label again, never writing advice.
+ */
+declare const ROLE_HELP: Readonly<Record<string, string>>;
+/**
+ * The canvas gestures a how-to may name, each one a control the Visual Editor draws:
+ *   rows.reorder — a selected row's grip (dashboard canvas/dnd/RowGrip.tsx);
+ *   image.replace — a click on a picture opens its popover (CanvasImagePopover.tsx);
+ *   link.popover — a click on a button or link opens its editor (CanvasButtonPopover.tsx);
+ *   text.inline — a click on copy puts the caret in it (canvasInlineText.ts).
+ * The dashboard exports the same names beside those components (CANVAS_GESTURES) and its test
+ * fails when one is missing.
+ */
+declare const CANVAS_GESTURE_NAMES: readonly ["rows.reorder", "image.replace", "link.popover", "text.inline"];
+type CanvasGesture = (typeof CANVAS_GESTURE_NAMES)[number];
+/** A control kind the canvas can also edit. A kind with no gesture (an icon, a switch) has no how-to. */
+type ControlKind = "rows" | "image" | "link" | "text";
+declare const CONTROL_HELP: Readonly<Record<ControlKind, {
+    text: string;
+    gesture: CanvasGesture;
+}>>;
+/**
+ * `e.g. "<value>"` for column `column` of row `i`: the nearest OTHER row's value (i-1, then i+1,
+ * then further out), the first non-empty one that differs from row i's own. When none differs, or
+ * there is one row, row i's own value. Undefined when the column holds no quotable words.
+ */
+declare function exampleFor(column: string, rows: readonly unknown[], i: number): string | undefined;
+/** A stored line with its row's example after it: one space between, the example dropped rather than run past {@link HELP_MAX}. */
+declare function withExample(help: string | undefined, example: string | undefined): string | undefined;
+
 /**
  * The dock's click budget, as ONE pure function both ends read (V9): the backend's next-steps
  * rules call it on live data, and the dashboard's reach test measures its RENDERED dock against the
@@ -2954,6 +3001,31 @@ declare function derivedPairs(candidates: readonly ButtonLinkCandidate[]): Map<n
 /** Every unambiguous pair in one sibling list, as `[textIndex, linkIndex]`, in list order. */
 declare function buttonLinkPairs(candidates: readonly ButtonLinkCandidate[]): Array<[number, number]>;
 
+/**
+ * THE link-label rule, pure: which sibling a text LABEL links with by its name alone. A label that pairs
+ * is one link to the author (the dashboard's `linkLabelHref`: a click opens the Link popover over both
+ * values); one that does not is plain text, unless the owner names its partner (`config.linkHref`, the
+ * editable plan's `link-pair` answer).
+ *
+ * 1. `<key>` pairs with `<key>-href` (the annotator's spelling).
+ * 2. `label` pairs with `label-href`, `href`, `url` or `link`, first found (a nav or footer row).
+ * 3. The partner must be link-typed (`link`, `url`).
+ *
+ * The plan asks only about the pairs this rule misses. Its twin is the dashboard's `linkLabelHref`
+ * (src/features/live-preview/identity/controlAt.ts), proven against one fixture on both sides
+ * (`__tests__/fixtures/link-pairs.json`).
+ */
+/** A sibling as either side spells it: a stored field (`key`) or a V2 schema field (`name`). */
+interface LinkPairSibling {
+    name?: string;
+    key?: string;
+    type?: string;
+}
+/** The sibling the rule pairs `labelKey` with, or null. PURE. */
+declare function rulePartnerOf(labelKey: string, siblings: readonly LinkPairSibling[]): string | null;
+/** Does the rule pair `labelKey` with a link-typed sibling by name? PURE. */
+declare const isRulePaired: (labelKey: string, siblings: readonly LinkPairSibling[]) => boolean;
+
 /**
  * The V2 video value (DESIGN.md §6.2, §8.15): a pasted provider link or a file URL, as a bare
  * string or as `{ url, poster?, autoplay?, loop?, transcript? }`.
@@ -3929,4 +4001,4 @@ type SectionPlanItem<B> = {
  */
 declare function planSections<B>(slots: readonly string[], blocks: readonly B[] | null | undefined): SectionPlanItem<B>[];
 
-export { type AlignToken, type AllowRule, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BODY_SCHEMA_ORIGINS, BREAKPOINTS, BUTTON_ACTIONS, BUTTON_FULL_WIDTH_INVALID, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_PLACEMENT_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type BodySchema, type BodySchemaOrigin, type ButtonAction, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSiteLook, type ButtonSizeName, type ButtonValue, type ButtonVariant, CODE_SLOT_PREFIX, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type ChoiceOption, type CollectionBlock, type CollectionFilter, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPreview, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, type ComponentProps, type ComponentSubField, type ComponentTab, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentModelFieldUi, type ContentPageResult, type ContentResponse, type ContentWidthToken, type CornerToken, DIALOG_SELECTOR, DOCK_BUDGET, DOCK_ICON_NAMES, DOCK_ICON_NAME_SET, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type DockBudget, type DockFieldLike, type DockFieldsetLike, type DockIconName, type DockInputRef, type DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FIELD_SIZE_ZOOM, FIELD_STYLE_KEYS, FOOTER_SECTION_ID, type FieldConfig, type FieldSize, type FieldStyle, type FieldStyleKey, type FieldStyles, type Fieldset, type FieldsetKind, type FieldsetUiBefore, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, type HeadingBlock, type HeadingProps, IMAGE_ASPECTS, IMAGE_FRAME_RADIUS, type ImageAspect, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, LINK_RELS, LINK_VALUE_TYPES, LIST_ITEMS_CAP, LOCATOR_PATH, type LandmarkChainElement, type LandmarkElement, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type LinkRel, type LinkValue, type LinkValueType, type LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, type NumberFieldFormat, type NumberScale, OPTION_DESCRIPTION_MAX, type OpenMode, PAGE_CONTENT_ANCHOR_ID, type Page, type PageLayoutOverrideDataDocument, type PageLayoutOverrideDocument, type PageLayoutOverrideState, type PageLayoutOverrideStructureDocument, type PageLayoutSectionOverride, type PageLayoutSectionStructureOverride, type PageMetaJson, type PageOnlyLayoutSection, type PageSectionPlacement, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type PropGroup, type PropTab, RESPONSIVE_CSS, ROLE_KEYS, type RadiusToken, type ReadButtonValue, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SIDE_SPACE_MIN_PX, SIDE_SPACE_TOKENS, SLOT_CHILD_KEYS, SLOT_ITEMS_CAP, SLOT_MAX_ITEMS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type ScaleUnit, type SectionBlock, type SectionPlanItem, type SectionProps, type SectionSpaceToken, type ShadowToken, type ShowIf, type ShowIfRule, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SlotChild, type SlotItem, type SlotShapeOptions, type SlotShapeProblem, type SlotValue, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, TABLE_COLUMN_TYPES, TABLE_JSONLD_TYPES, TABLE_LIMITS, TABLE_RESPONSIVE, TAG_HEADS, type TabItem, type TableCell, type TableCellObject, type TableCellValue, type TableCheckOptions, type TableColumn, type TableColumnType, type TableFieldOptions, type TableFootnote, type TableGroup, type TableLink, type TableProblem, type TableRef, type TableRefResolved, type TableRow, type TableValue, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, VIDEO_TRANSCRIPT_MAX, VIDEO_VALUE_KEYS, type VariantInputMapping, type VideoBlock, type VideoProps, type VideoValue, type VisibilityWindow, type WeightToken, type WindowState, type Workspace, type ZoneField, allowRuleOf, anchorTargetRel, blockStyleToColumnCss, blockStyleToCss, blockStyleToInnerCss, bodySchemaOf, buttonBlockProps, buttonFullWidthProblem, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonLookValue, buttonSiteLookOf, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, derivedPairs, dockBudget, dockScreens, expandBlockBindings, fieldGroupOf, fieldStyleCssText, fieldStyleToCss, formatNumber, formatPropsAttribute, getBlockType, headingPaintCss, hiddenEverywhere, hideOnAttr, imageFrameCss, inWindow, isBlock, isButtonLookValue, isChromeLandmark, isCodeButton, isLinkObject, isRoleKey, isScriptHref, isSlotChild, isTableValue, keyWords, landmarkRegions, linkAnchorOf, linkHref, linkRefOf, linkValueProblem, locatorFor, locatorPath, normalizeLinkValue, normalizeTableValue, normalizeWindow, parseNumberText, parsePropsAttribute, pickFieldStyle, placementBindOf, planSections, readButtonValue, readNumberFormat, readPath, regionOf, renderTableHtml, safeCssUrl, sideFloorApplies, sideSpaceCss, slotBindOf, slotChildValues, slotItems, slotPathString, slotShapeProblems, spaceTokenCss, splitButtonStyle, tableCellText, tablePathString, tableRefCells, tableSearchText, tableToMarkdown, tableValueProblems, topFieldKeyOf, usesHideOn, videoUrlOf, videoValueProblem, visibleBlocks, visibleDeliveredLayout, visibleLayoutStructure, windowState, withButtonLookProps };
+export { type AlignToken, type AllowRule, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BODY_SCHEMA_ORIGINS, BREAKPOINTS, BUTTON_ACTIONS, BUTTON_FULL_WIDTH_INVALID, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_PLACEMENT_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type BodySchema, type BodySchemaOrigin, type ButtonAction, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSiteLook, type ButtonSizeName, type ButtonValue, type ButtonVariant, CANVAS_GESTURE_NAMES, CODE_SLOT_PREFIX, COMPONENT_PROP_TYPES, CONTROL_HELP, type CanonicalInputDefinition, type CanvasGesture, type ChoiceOption, type CollectionBlock, type CollectionFilter, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPreview, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, type ComponentProps, type ComponentSubField, type ComponentTab, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentModelFieldUi, type ContentPageResult, type ContentResponse, type ContentWidthToken, type ControlKind, type CornerToken, DIALOG_SELECTOR, DOCK_BUDGET, DOCK_ICON_NAMES, DOCK_ICON_NAME_SET, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryEntrySeo, type DeliveryList, type DeliveryPage, type DerivedLocator, type DockBudget, type DockFieldLike, type DockFieldsetLike, type DockIconName, type DockInputRef, type DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FIELD_SIZE_ZOOM, FIELD_STYLE_KEYS, FOOTER_SECTION_ID, type FieldConfig, type FieldSize, type FieldStyle, type FieldStyleKey, type FieldStyles, type Fieldset, type FieldsetKind, type FieldsetUiBefore, type FontSizeToken, type FooterBlock, type FooterColumn, type FooterProps, type Form, type FormBlock, type FormField, type FormProps, type FormSubmission, HELP_MAX, type HeadingBlock, type HeadingProps, IMAGE_ASPECTS, IMAGE_FRAME_RADIUS, type ImageAspect, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, LINK_RELS, LINK_VALUE_TYPES, LIST_ITEMS_CAP, LOCATOR_PATH, type LandmarkChainElement, type LandmarkElement, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type LinkPairSibling, type LinkRel, type LinkValue, type LinkValueType, type LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, type NumberFieldFormat, type NumberScale, OPTION_DESCRIPTION_MAX, type OpenMode, PAGE_CONTENT_ANCHOR_ID, type Page, type PageLayoutOverrideDataDocument, type PageLayoutOverrideDocument, type PageLayoutOverrideState, type PageLayoutOverrideStructureDocument, type PageLayoutSectionOverride, type PageLayoutSectionStructureOverride, type PageMetaJson, type PageOnlyLayoutSection, type PageSectionPlacement, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type PropGroup, type PropTab, RESPONSIVE_CSS, ROLE_HELP, ROLE_KEYS, type RadiusToken, type ReadButtonValue, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SIDE_SPACE_MIN_PX, SIDE_SPACE_TOKENS, SLOT_CHILD_KEYS, SLOT_ITEMS_CAP, SLOT_MAX_ITEMS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type ScaleUnit, type SectionBlock, type SectionPlanItem, type SectionProps, type SectionSpaceToken, type ShadowToken, type ShowIf, type ShowIfRule, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SlotChild, type SlotItem, type SlotShapeOptions, type SlotShapeProblem, type SlotValue, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, TABLE_COLUMN_TYPES, TABLE_JSONLD_TYPES, TABLE_LIMITS, TABLE_RESPONSIVE, TAG_HEADS, type TabItem, type TableCell, type TableCellObject, type TableCellValue, type TableCheckOptions, type TableColumn, type TableColumnType, type TableFieldOptions, type TableFootnote, type TableGroup, type TableLink, type TableProblem, type TableRef, type TableRefResolved, type TableRow, type TableValue, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, VIDEO_TRANSCRIPT_MAX, VIDEO_VALUE_KEYS, type VariantInputMapping, type VideoBlock, type VideoProps, type VideoValue, type VisibilityWindow, type WeightToken, type WindowState, type Workspace, type ZoneField, allowRuleOf, anchorTargetRel, blockStyleToColumnCss, blockStyleToCss, blockStyleToInnerCss, bodySchemaOf, buttonBlockProps, buttonFullWidthProblem, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonLookValue, buttonSiteLookOf, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, derivedPairs, dockBudget, dockScreens, exampleFor, expandBlockBindings, fieldGroupOf, fieldStyleCssText, fieldStyleToCss, formatNumber, formatPropsAttribute, getBlockType, headingPaintCss, hiddenEverywhere, hideOnAttr, imageFrameCss, inWindow, isBlock, isButtonLookValue, isChromeLandmark, isCodeButton, isLinkObject, isRoleKey, isRulePaired, isScriptHref, isSlotChild, isTableValue, keyWords, landmarkRegions, linkAnchorOf, linkHref, linkRefOf, linkValueProblem, locatorFor, locatorPath, normalizeLinkValue, normalizeTableValue, normalizeWindow, parseNumberText, parsePropsAttribute, pickFieldStyle, placementBindOf, planSections, readButtonValue, readNumberFormat, readPath, regionOf, renderTableHtml, rulePartnerOf, safeCssUrl, sideFloorApplies, sideSpaceCss, slotBindOf, slotChildValues, slotItems, slotPathString, slotShapeProblems, spaceTokenCss, splitButtonStyle, tableCellText, tablePathString, tableRefCells, tableSearchText, tableToMarkdown, tableValueProblems, topFieldKeyOf, usesHideOn, videoUrlOf, videoValueProblem, visibleBlocks, visibleDeliveredLayout, visibleLayoutStructure, windowState, withButtonLookProps, withExample };

package/dist/index.js

@@ -3159,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) {
@@ -3408,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";
 
@@ -4340,7 +4485,9 @@ var ROLE_KEYS = /* @__PURE__ */ new Set([
   "tooltip",
   "placeholder",
   "image-description",
-  "counter-target"
+  "counter-target",
+  "amount",
+  "period"
 ]);
 var ROLE_TAILS = /(?:-label)?(?:-[a-z])?(?:-\d+)?(?:-href)?$/;
 function isRoleKey(key) {
@@ -4415,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,
@@ -4424,6 +4573,7 @@ export {
   FIELD_SIZE_ZOOM,
   FIELD_STYLE_KEYS,
   FOOTER_SECTION_ID,
+  HELP_MAX,
   IMAGE_ASPECTS,
   IMAGE_FRAME_RADIUS,
   LANDMARK_SELECTOR,
@@ -4438,6 +4588,7 @@ export {
   OPTION_DESCRIPTION_MAX,
   PAGE_CONTENT_ANCHOR_ID,
   RESPONSIVE_CSS,
+  ROLE_HELP,
   ROLE_KEYS,
   SECTION_DOCTRINE,
   SECTION_SPACE_TOKENS,
@@ -4477,6 +4628,7 @@ export {
   derivedPairs,
   dockBudget,
   dockScreens,
+  exampleFor,
   expandBlockBindings,
   fieldGroupOf,
   fieldStyleCssText,
@@ -4495,6 +4647,7 @@ export {
   isCodeButton,
   isLinkObject,
   isRoleKey,
+  isRulePaired,
   isScriptHref,
   isSlotChild,
   isTableValue,
@@ -4519,6 +4672,7 @@ export {
   readPath,
   regionOf,
   renderTableHtml,
+  rulePartnerOf,
   safeCssUrl,
   sideFloorApplies,
   sideSpaceCss,
@@ -4543,6 +4697,7 @@ export {
   visibleDeliveredLayout,
   visibleLayoutStructure,
   windowState,
-  withButtonLookProps
+  withButtonLookProps,
+  withExample
 };
 //# sourceMappingURL=index.js.map