@bettercms-ai/types 1.29.1 → 1.30.0

package/dist/index.d.ts

@@ -997,8 +997,31 @@ declare function componentInstanceAddresses(instanceBlockId: string, props: read
  * render-page.ts. Unknown tokens are dropped — closed set, no arbitrary CSS.
  */
 
+/**
+ * 🔴 The ONE place a free-form string is allowed near CSS: `bgImage` is author-supplied, so it is
+ * rejected — never escaped — unless it is an http(s) or root-relative url with nothing that could
+ * end a `url(…)` token or start a new declaration (quotes, parens, backslash, `;`, whitespace).
+ * Returns "" for anything it does not fully trust. Twin of `safeCssUrl` in render-page.ts.
+ */
+declare function safeCssUrl(raw: unknown): string;
 /** A CSS declaration object (key → value) usable as a React `style` prop, or undefined when empty. */
 declare function blockStyleToCss(style: BlockStyle | undefined): Record<string, string | number> | undefined;
+/**
+ * The content column: the declarations for the INNER box a renderer nests between a block's
+ * style wrapper (`blockStyleToCss`, which carries the full-bleed background) and the block itself.
+ * The outer box can't constrain width without shrinking its own background, so a width needs a
+ * second box. `undefined` when there is no column (no `contentWidth`, `full`, or unknown) — a
+ * renderer then emits no inner box at all.
+ *
+ * Placement is `contentAlign`, falling back to `align`. `align` alone used to mean both text
+ * alignment (outer box) and column placement (here); `contentAlign` split them, and the fallback
+ * keeps every style written before the split rendering identically. Twin: `styleTokensToInnerCss`
+ * in render-page.ts, which the hosted lane serialises as `max-width:…;margin:…`.
+ */
+declare function blockStyleToInnerCss(style: BlockStyle | undefined): {
+    maxWidth: string;
+    margin: string;
+} | undefined;
 /**
  * HEADING-STYLE-PAINT — a heading's own size and weight, for the `<hN>` element itself.
  *
@@ -1022,6 +1045,25 @@ declare function headingPaintCss(style: BlockStyle | undefined, opts?: {
     fontSize?: string;
     fontWeight?: number;
 } | undefined;
+/**
+ * Style keys that PLACE a block. A button keeps only these on its wrapper; the rest paints the
+ * `<a>` itself. On the wrapper (where every other block's style goes) a fill, theme or corner
+ * painted a box BEHIND the anchor, which kept its variant's own fill. 🔴 Twin of `PLACEMENT_KEYS`
+ * in src/lib/sites/render-page.ts; src/__tests__/sites/block-style-parity.test.ts pins the two.
+ */
+declare const BUTTON_PLACEMENT_KEYS: readonly ["align", "contentAlign", "contentWidth", "marginTop", "marginBottom", "fullHeight", "spaceTop", "spaceBottom"];
+/**
+ * A button's style split in two: `placement` (the keys its wrapper keeps — feed it to
+ * `blockStyleToCss` / `blockStyleToInnerCss` exactly like any block's style) and `paint`, the
+ * declarations for the `<a>` itself. `bg: "none"` paints the anchor transparent (and inherits the
+ * text colour unless one is set), so it clears the variant's fill instead of doing nothing.
+ * `hover` is not painted: the hosted lane draws it with classes its own stylesheet styles.
+ * Either half is `undefined` when empty, so an unstyled button gets no wrapper and no `style`.
+ */
+declare function splitButtonStyle(style: BlockStyle | undefined): {
+    placement: BlockStyle | undefined;
+    paint: Record<string, string | number> | undefined;
+};
 
 /**
  * Generated from lucide-react@1.8.0 dynamic icon names.
@@ -2409,4 +2451,4 @@ declare function regionOf<E extends {
     el: E;
 }[], el: unknown): string | null;
 
-export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, BUTTON_ICONS, BUTTON_ICON_NAMES, BUTTON_LOOK_KEYS, BUTTON_SIZES, BUTTON_VARIANTS, type BetterCMSErrorCode, type BgToken, type BindingKind, type BlockBinding, type BlockHoverStyle, type BlockStyle, type BlockType, type ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSizeName, type ButtonValue, type ButtonVariant, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, type ComponentProps, type ComponentSubField, 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 DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FOOTER_SECTION_ID, type FieldConfig, 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, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, 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 LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, 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 RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, type VariantInputMapping, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, dockBudget, dockScreens, expandBlockBindings, formatPropsAttribute, getBlockType, headingPaintCss, isBlock, isChromeLandmark, keyWords, landmarkRegions, locatorFor, parsePropsAttribute, readButtonValue, readPath, regionOf, spaceTokenCss, withButtonLookProps };
+export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, BLOCK_BINDINGS, 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 ButtonBlock, type ButtonIcon, type ButtonLinkCandidate, type ButtonLookKey, type ButtonProps, type ButtonSizeName, type ButtonValue, type ButtonVariant, COMPONENT_PROP_TYPES, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentFormPropRef, type ComponentPropDef, type ComponentPropType, type ComponentPropUi, type ComponentProps, type ComponentSubField, 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 DockLane, type DockNode, type DockPropGroupLike, type DockScreen, type ElementLike, type ExpandedBinding, FOOTER_SECTION_ID, type FieldConfig, 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, type ImageBlock, type ImageProps, LANDMARK_SELECTOR, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, 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 LocatorGrammar, MAIN_SELECTOR, type ManagementLayoutCommand, type MediaAsset, type MediaCaptionTrack, type MediaFieldValue, NAVIGATION_SECTION_ID, type NavLink, type NavbarBlock, type NavbarProps, 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 RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, SECTION_DOCTRINE, SECTION_SPACE_TOKENS, SPACE_BOTTOM_TOKENS, SPACE_STEP_TOKENS, type SectionBlock, type SectionProps, type SectionSpaceToken, type ShadowToken, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceStepToken, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type ThemeToken, type UiBefore, type UiOrigin, type VariantInputMapping, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, blockStyleToInnerCss, buttonIconOf, buttonIconSvg, buttonLinkPairs, buttonValueOfInstance, buttonValueProblem, buttonVariantOf, candidateRole, componentInstanceAddresses, componentPropTargetKey, dockBudget, dockScreens, expandBlockBindings, formatPropsAttribute, getBlockType, headingPaintCss, isBlock, isChromeLandmark, keyWords, landmarkRegions, locatorFor, parsePropsAttribute, readButtonValue, readPath, regionOf, safeCssUrl, spaceTokenCss, splitButtonStyle, withButtonLookProps };

package/dist/index.js

@@ -144,6 +144,38 @@ var FONT_SIZE_REM = {
 var WEIGHT = { normal: 400, medium: 500, semibold: 600, bold: 700 };
 var RADIUS_PX = { none: "0", sm: "4px", md: "8px", lg: "16px", full: "9999px" };
 var COLOR_HEX = { white: "#ffffff", black: "#111111", muted: "#6b7280", mutedBg: "#f3f4f6", primary: "#111111", accent: "#4f46e5" };
+var THEME = {
+  light: { colorScheme: "light", background: "#ffffff", color: "#111111" },
+  dark: { colorScheme: "dark", background: "#0b0b0d", color: "#f7f8f8" }
+};
+var BG_HEX = {
+  surface: "var(--bcms-bg-surface,#ffffff)",
+  muted: "var(--bcms-bg-muted,#f3f4f6)",
+  accent: "var(--bcms-bg-accent,#4f46e5)",
+  dark: "var(--bcms-bg-dark,#0b0b0d)"
+};
+var CORNER_PX = { "0": "0", s: "4px", m: "8px", l: "16px", xl: "24px", "2xl": "32px" };
+var SHADOW_CSS = {
+  "0": "none",
+  s: "0 1px 2px rgba(0,0,0,.06)",
+  m: "0 4px 12px rgba(0,0,0,.08)",
+  l: "0 10px 24px rgba(0,0,0,.10)",
+  xl: "0 24px 48px rgba(0,0,0,.14)"
+};
+var HAIRLINE = "1px solid rgba(0,0,0,.10)";
+var CONTENT_WIDTH_PX = { narrow: "640px", default: "1024px", wide: "1280px" };
+var HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+var clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+var own = (map, key) => typeof key === "string" && Object.prototype.hasOwnProperty.call(map, key) ? map[key] : void 0;
+function safeCssUrl(raw) {
+  if (typeof raw !== "string") return "";
+  const url = raw.trim();
+  if (!url || url.length > 2e3) return "";
+  if (/["'()\\;]|\s/.test(url)) return "";
+  if (url.startsWith("//")) return "";
+  if (url.startsWith("/")) return url;
+  return /^https?:\/\//i.test(url) ? url : "";
+}
 function blockStyleToCss(style) {
   if (!style || typeof style !== "object") return void 0;
   const s = style;
@@ -178,9 +210,55 @@ function blockStyleToCss(style) {
   if (s.fontSize && FONT_SIZE_REM[s.fontSize]) css.fontSize = FONT_SIZE_REM[s.fontSize];
   if (s.weight && WEIGHT[s.weight] != null) css.fontWeight = WEIGHT[s.weight];
   if (s.radius && RADIUS_PX[s.radius] != null) css.borderRadius = RADIUS_PX[s.radius];
+  const theme = own(THEME, s.theme);
+  if (theme) {
+    css.colorScheme = theme.colorScheme;
+    css.background = theme.background;
+    css.color = theme.color;
+  }
+  if (s.bg === "custom") {
+    if (HEX.test(s.bgCustom ?? "")) css.background = s.bgCustom;
+  } else if (own(BG_HEX, s.bg)) css.background = own(BG_HEX, s.bg);
+  const bgImage = safeCssUrl(s.bgImage);
+  if (bgImage) {
+    css.backgroundImage = `url(${bgImage})`;
+    css.backgroundSize = "cover";
+    css.backgroundPosition = "center";
+  }
+  const n = style;
+  if (!top && typeof n.paddingTop === "number") css.paddingTop = `${clamp(n.paddingTop, 0, 240)}px`;
+  if (!bottom && typeof n.paddingBottom === "number") css.paddingBottom = `${clamp(n.paddingBottom, 0, 240)}px`;
+  if (!sides && typeof n.paddingSides === "number") {
+    const px = `${clamp(n.paddingSides, 0, 240)}px`;
+    css.paddingLeft = px;
+    css.paddingRight = px;
+  }
+  if (n.fullHeight === true) {
+    css.minHeight = "100vh";
+    css.display = "flex";
+    css.flexDirection = "column";
+    css.justifyContent = "center";
+  }
+  if (typeof n.opacity === "number") css.opacity = clamp(n.opacity, 0, 100) / 100;
+  if (own(CORNER_PX, s.corner) != null) {
+    css.borderRadius = own(CORNER_PX, s.corner);
+    css.overflow = "hidden";
+  }
+  if (own(SHADOW_CSS, s.shadow)) css.boxShadow = own(SHADOW_CSS, s.shadow);
+  if (n.borderTop === true) css.borderTop = HAIRLINE;
+  if (n.borderBottom === true) css.borderBottom = HAIRLINE;
   if (style.border === true) css.border = "1px solid currentColor";
   return Object.keys(css).length ? css : void 0;
 }
+function blockStyleToInnerCss(style) {
+  if (!style || typeof style !== "object") return void 0;
+  const s = style;
+  const max = own(CONTENT_WIDTH_PX, s.contentWidth);
+  if (!max) return void 0;
+  const placement = s.contentAlign ?? s.align;
+  const margin = placement === "left" ? "0 auto 0 0" : placement === "right" ? "0 0 0 auto" : "0 auto";
+  return { maxWidth: max, margin };
+}
 function headingPaintCss(style, opts = {}) {
   if (!style || typeof style !== "object") return void 0;
   const s = style;
@@ -190,6 +268,35 @@ function headingPaintCss(style, opts = {}) {
   if (s.weight && WEIGHT[s.weight] != null) css.fontWeight = WEIGHT[s.weight];
   return css.fontSize !== void 0 || css.fontWeight !== void 0 ? css : void 0;
 }
+var BUTTON_PLACEMENT_KEYS = [
+  "align",
+  "contentAlign",
+  "contentWidth",
+  "marginTop",
+  "marginBottom",
+  "fullHeight",
+  "spaceTop",
+  "spaceBottom"
+];
+var PLACEMENT = new Set(BUTTON_PLACEMENT_KEYS);
+function splitButtonStyle(style) {
+  if (!style || typeof style !== "object") return { placement: void 0, paint: void 0 };
+  const placement = {};
+  const rest = {};
+  for (const [k, v] of Object.entries(style)) {
+    if (k === "hover") continue;
+    (PLACEMENT.has(k) ? placement : rest)[k] = v;
+  }
+  const paint = { ...blockStyleToCss(rest) };
+  if (rest.bg === "none") {
+    paint.background = "transparent";
+    if (!rest.textColor) paint.color = "inherit";
+  }
+  return {
+    placement: Object.keys(placement).length ? placement : void 0,
+    paint: Object.keys(paint).length ? paint : void 0
+  };
+}
 
 // src/component.ts
 var SECTION_DOCTRINE = "STRUCTURE (separate from schema): a page is composed of SECTIONS. NEVER build a page out of loose top-level heading/text/image/button/spacer blocks \u2014 they cannot be moved, duplicated or swapped as a unit, the visual editor cannot outline or name them, and every one of them becomes its own section in the editor. A hero of a headline, a lede and two CTAs is ONE section, not four. TWO SHAPES, and the choice is about REUSE. (1) A band that appears on more than one page, or that needs layout variants, is a COMPONENT with a `sectionType` \u2014 see create_component. Components sharing a `sectionType` are that section's VARIANTS (one Hero: 'Centered' for the home page and 'Two-column' for about, same prop keys so a swap keeps the content). This is also the only shape the editor's 'Add a section' picker can insert, and the only one that gets a family name and a variant switcher. (2) A genuinely one-off band on a single page is a `section` BLOCK whose `props.children` hold its blocks. THE TRADEOFF, stated in the present tense because it is real today: inside a component, ONLY the leaves a declared prop TARGETS are click-to-edit on the canvas \u2014 each declared prop's `target` is re-keyed to that PLACEMENT's own override address, so editing it changes this page and not the shared definition. A prop with no `target` still SHOWS as a dock control, but its override reaches no rendered slot, so editing it changes nothing on the page. Copy that no prop points at is worse still: no binding and no control, unreachable from click-to-edit AND from the dock, changeable only by editing the component definition, which rewrites every page that places it. A `section` block's children stay click-to-edit unconditionally. So when you choose a component, DECLARE A PROP \u2014 WITH A `target` \u2014 for every string, link and image a marketer will ever touch; a component with un-propped editable copy is the defect, not the component. In the dock an unset prop shows EMPTY and inherits the definition's default, so set props explicitly when you want the current copy visible there. An IMPORTED site's components are its own (read the repo); its nav, footer and modals are the Layout. On a blank site, do not hand-write a band's JSON: start from a built-in section blueprint (list_components returns locked `builtin:*` blueprints with no projectId \u2014 hero-centered, hero-split, feature-grid-three, cta-banner and nine more), each already rooted in a `section` block with its editable leaves declared as props. INLINE its blockJson as a `section` block for a one-off band; for a recurring band, materialize the blueprint with create_component so it becomes project-scoped before implementation validation, Output or publication. Direct `builtin:*` component references exist only for legacy delivery compatibility. Two consecutive call-to-action buttons are two sibling `button` blocks inside the same section \u2014 never a `columns` block, which is a `repeat(N,1fr)` grid and would stretch each CTA to half the container. Buttons are inline-level and flow side by side on their own.";
@@ -2778,6 +2885,7 @@ export {
   BUTTON_ICONS,
   BUTTON_ICON_NAMES,
   BUTTON_LOOK_KEYS,
+  BUTTON_PLACEMENT_KEYS,
   BUTTON_SIZES,
   BUTTON_VARIANTS,
   COMPONENT_PROP_TYPES,
@@ -2797,6 +2905,7 @@ export {
   SPACE_BOTTOM_TOKENS,
   SPACE_STEP_TOKENS,
   blockStyleToCss,
+  blockStyleToInnerCss,
   buttonIconOf,
   buttonIconSvg,
   buttonLinkPairs,
@@ -2821,7 +2930,9 @@ export {
   readButtonValue,
   readPath,
   regionOf,
+  safeCssUrl,
   spaceTokenCss,
+  splitButtonStyle,
   withButtonLookProps
 };
 //# sourceMappingURL=index.js.map