@bettercms-ai/types 1.7.0 → 1.9.0

package/dist/index.d.ts

@@ -307,7 +307,27 @@ interface ComponentBlock {
     style?: BlockStyle;
     props: ComponentProps;
 }
-type ContentBlock = HeadingBlock | TextBlock | RichTextBlock | ImageBlock | ButtonBlock | SpacerBlock | ColumnsBlock | VideoBlock | FormBlock | SectionBlock | NavbarBlock | FooterBlock | SliderBlock | TabsBlock | ComponentBlock;
+interface CollectionProps {
+    /** Component rendered once per entry, interpolated with {{field}} and {{url}}. Omit for a built-in card. */
+    cardComponentId?: string;
+    /** Component rendered for the single entry on a detail URL. Omit to fall back to the generic field layout. */
+    detailComponentId?: string;
+    /** Built-in card only. Defaults to "title" / no excerpt. */
+    titleField?: string;
+    excerptField?: string;
+    /** Max cards to render. Defaults to 20. */
+    limit?: number;
+    /** "newest" (default) reverses the reader's created_at ordering. */
+    order?: "newest" | "oldest";
+    emptyText?: string;
+}
+interface CollectionBlock {
+    type: "collection";
+    id: string;
+    style?: BlockStyle;
+    props: CollectionProps;
+}
+type ContentBlock = CollectionBlock | HeadingBlock | TextBlock | RichTextBlock | ImageBlock | ButtonBlock | SpacerBlock | ColumnsBlock | VideoBlock | FormBlock | SectionBlock | NavbarBlock | FooterBlock | SliderBlock | TabsBlock | ComponentBlock;
 /** Literal union of all block type discriminators. */
 type BlockType = ContentBlock["type"];
 /**
@@ -340,6 +360,326 @@ declare function getBlockType(value: unknown): BlockType | null;
 /** 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;
 
+/**
+ * Generated from lucide-react@1.8.0 dynamic icon names.
+ * Legacy CamelCase identifiers remain valid for existing Layout documents.
+ */
+declare const LAYOUT_SECTION_ICONS: readonly string[];
+declare const LAYOUT_SECTION_ICON_SET: ReadonlySet<string>;
+type LayoutSectionIcon = string;
+
+/** Stable identifiers used by every project and page layout document. */
+declare const PAGE_CONTENT_ANCHOR_ID: "page-content";
+declare const NAVIGATION_SECTION_ID: "navigation";
+declare const FOOTER_SECTION_ID: "footer";
+
+type LayoutZone = "above-page-content" | "below-page-content";
+type ReservedLayoutSection = "navigation" | "footer";
+type LayoutScalarFieldType = "text" | "longtext" | "richtext" | "number" | "toggle" | "date" | "image" | "file" | "link" | "email" | "phone" | "select" | "color" | "json" | "reference" | "multi-reference";
+type LayoutFieldType = LayoutScalarFieldType | "group" | "repeater";
+/** A recursive, stable-ID field contract shared by Sections and variant inputs. */
+interface LayoutFieldDefinition {
+    id: string;
+    slug: string;
+    label: string;
+    type: LayoutFieldType;
+    required?: boolean;
+    defaultValue?: unknown;
+    config?: {
+        options?: Array<{
+            label: string;
+            value: string;
+        }>;
+        referenceModelId?: string;
+        minItems?: number;
+        maxItems?: number;
+    } & Record<string, unknown>;
+    /** Required for group/repeater; forbidden for scalar fields. */
+    fields?: LayoutFieldDefinition[];
+}
+/** The canonical public input contract all variants in a group implement. */
+type CanonicalInputDefinition = LayoutFieldDefinition;
+/** Maps one canonical input onto one or more internal component prop paths. */
+interface VariantInputMapping {
+    inputId: string;
+    targets: Array<{
+        blockId: string;
+        path: string;
+    }>;
+}
+interface ComponentVariantGroup {
+    id: string;
+    workspaceId: string;
+    projectId?: string | null;
+    name: string;
+    slug: string;
+    canonicalInputs: CanonicalInputDefinition[];
+    status: "draft" | "published";
+}
+interface LayoutFieldItem {
+    id: string;
+    kind: "field";
+    fieldId: string;
+}
+interface LayoutComponentItem {
+    id: string;
+    kind: "component";
+    componentId: string;
+    variantGroupId?: string;
+    bindings: Array<{
+        inputId: string;
+        fieldId: string;
+    }>;
+    literalValues?: Record<string, unknown>;
+}
+type LayoutSectionItem = LayoutFieldItem | LayoutComponentItem;
+interface LayoutSection {
+    id: string;
+    name: string;
+    slug: string;
+    icon: string;
+    zone: LayoutZone;
+    orderKey: string;
+    reserved?: ReservedLayoutSection;
+    fields: LayoutFieldDefinition[];
+    items: LayoutSectionItem[];
+}
+interface LayoutStructureDocument {
+    version: 1;
+    pageContentAnchor: {
+        id: typeof PAGE_CONTENT_ANCHOR_ID;
+    };
+    sections: LayoutSection[];
+}
+interface LayoutDataDocument {
+    version: 1;
+    sections: Record<string, {
+        fields: Record<string, unknown>;
+    }>;
+}
+type PageLayoutOverrideState = "inherit" | "override-content" | "customize-structure" | "disable";
+interface PageSectionPlacement {
+    zone: LayoutZone;
+    afterSectionId?: string;
+    beforeSectionId?: string;
+    localOrderKey: string;
+}
+type PageLayoutSectionOverride = {
+    sectionId: string;
+    state: "inherit";
+} | {
+    sectionId: string;
+    state: "override-content";
+    values: Record<string, unknown>;
+} | {
+    sectionId: string;
+    state: "customize-structure";
+    section: LayoutSection;
+    data: {
+        fields: Record<string, unknown>;
+    };
+    /** Retained when the inherited Section is later deleted. */
+    placement: PageSectionPlacement;
+} | {
+    sectionId: string;
+    state: "disable";
+};
+interface PageOnlyLayoutSection {
+    section: LayoutSection;
+    data: {
+        fields: Record<string, unknown>;
+    };
+    placement: PageSectionPlacement;
+}
+type PageLayoutSectionStructureOverride = {
+    sectionId: string;
+    state: "inherit";
+} | {
+    sectionId: string;
+    state: "override-content";
+} | {
+    sectionId: string;
+    state: "customize-structure";
+    section: LayoutSection;
+    placement: PageSectionPlacement;
+} | {
+    sectionId: string;
+    state: "disable";
+};
+/** Persisted in pages.layout_override_structure_json. */
+interface PageLayoutOverrideStructureDocument {
+    version: 1;
+    sections: PageLayoutSectionStructureOverride[];
+    pageOnlySections: Array<{
+        section: LayoutSection;
+        placement: PageSectionPlacement;
+    }>;
+}
+/** Persisted independently so values can be patched without rewriting structure. */
+interface PageLayoutOverrideDataDocument {
+    version: 1;
+    sections: Record<string, {
+        fields: Record<string, unknown>;
+    }>;
+    pageOnlySections: Record<string, {
+        fields: Record<string, unknown>;
+    }>;
+}
+/** Canonical in-memory form consumed by the pure resolver. */
+interface PageLayoutOverrideDocument {
+    version: 1;
+    sections: PageLayoutSectionOverride[];
+    pageOnlySections: PageOnlyLayoutSection[];
+}
+/** Canonical, discriminated Management/MCP authoring transport. Authority is derived from type. */
+type ManagementLayoutCommand = {
+    type: "set-section-values";
+    sectionId: string;
+    values: Record<string, unknown>;
+} | {
+    type: "set-field-value";
+    sectionId: string;
+    fieldId: string;
+    value: unknown;
+} | {
+    type: "add-component";
+    sectionId: string;
+    componentId: string;
+    variantGroupId?: string;
+    bindings?: LayoutComponentItem["bindings"];
+    literalValues?: Record<string, unknown>;
+} | {
+    type: "remove-item";
+    sectionId: string;
+    itemId: string;
+} | {
+    type: "move-component";
+    sectionId: string;
+    itemId: string;
+    index: number;
+} | {
+    type: "move-item";
+    sectionId: string;
+    itemId: string;
+    index: number;
+} | {
+    type: "swap-component-variant";
+    sectionId: string;
+    itemId: string;
+    componentId: string;
+} | {
+    type: "set-page-state";
+    sectionId: string;
+    state: PageLayoutOverrideState | "reset";
+} | {
+    type: "set-section-state";
+    sectionId: string;
+    state: PageLayoutOverrideState | "reset";
+} | {
+    type: "add-section";
+    name: string;
+    icon: LayoutSectionIcon;
+    zone: "before_page" | "after_page";
+} | {
+    type: "restore-section";
+    section: LayoutSection;
+    data: {
+        fields: Record<string, unknown>;
+    };
+    placement?: PageSectionPlacement;
+} | {
+    type: "update-section";
+    sectionId: string;
+    name?: string;
+    icon?: LayoutSectionIcon;
+    slug?: string;
+    zone?: LayoutZone;
+    orderKey?: string;
+} | {
+    type: "remove-section";
+    sectionId: string;
+} | {
+    type: "move-section";
+    sectionId: string;
+    afterId?: string | null;
+    beforeId?: string | null;
+} | {
+    type: "add-field";
+    sectionId: string;
+    parentFieldId?: string;
+    field?: LayoutFieldDefinition;
+    fieldType?: LayoutFieldType;
+} | {
+    type: "update-field";
+    sectionId: string;
+    fieldId: string;
+    patch: Partial<Omit<LayoutFieldDefinition, "id">>;
+} | {
+    type: "remove-field";
+    sectionId: string;
+    fieldId: string;
+} | {
+    type: "move-field";
+    sectionId: string;
+    itemId: string;
+    index: number;
+} | {
+    type: "set-bindings";
+    sectionId: string;
+    itemId: string;
+    bindings: LayoutComponentItem["bindings"];
+    literalValues?: Record<string, unknown>;
+};
+type ResolvedLayoutNode = {
+    kind: "page-content";
+    id: typeof PAGE_CONTENT_ANCHOR_ID;
+} | {
+    kind: "section";
+    id: string;
+    section: LayoutSection;
+    data: {
+        fields: Record<string, unknown>;
+    };
+    source: "inherit" | "override-content" | "customize-structure" | "page-only" | "detached";
+};
+interface DeliveredLayout {
+    version: 1;
+    nodes: Array<{
+        kind: "page-content";
+        id: typeof PAGE_CONTENT_ANCHOR_ID;
+    } | {
+        kind: "section";
+        id: string;
+        slug: string;
+        name: string;
+        source: Extract<ResolvedLayoutNode, {
+            kind: "section";
+        }>["source"];
+    }>;
+    sections: Record<string, {
+        id: string;
+        slug: string;
+        name: string;
+        fields: Record<string, unknown>;
+        items: Array<{
+            id: string;
+            kind: "field";
+            fieldId: string;
+            value: unknown;
+        } | {
+            id: string;
+            kind: "component";
+            componentId: string;
+            variantGroupId?: string;
+            canonicalInputs: CanonicalInputDefinition[];
+            bindings: LayoutComponentItem["bindings"];
+            canonicalValues: Record<string, unknown>;
+            resolvedProps: Record<string, unknown>;
+            blocks: unknown[];
+        }>;
+    }>;
+}
+
 /**
  * Component — a reusable, Webflow-style block tree (a "symbol").
  *
@@ -367,9 +707,27 @@ interface ComponentPropDef {
         blockId: string;
         path: string;
     };
-    type: "text" | "richtext" | "image" | "url" | "boolean";
+    /**
+     * `slot` holds ONE nested component instance — the component-level twin of the
+     * content-model field type `component-ref` (see content-model.ts), named differently for
+     * the same reason that one is: `component` already means a BLOCK type. Its value is
+     * `{ componentId, overrides }` and its `target.path` is `props`, so filling a slot writes
+     * that object over an empty `component` block's props.
+     *
+     * On a PAGE a slot fill is a LIVE reference; a published ENTRY freezes it (resolveDeep).
+     */
+    type: "text" | "richtext" | "image" | "url" | "boolean" | "slot";
     defaultValue?: unknown;
+    /** Per-type settings. `slot` uses `componentIds` as a pick allowlist. */
+    config?: {
+        componentIds?: string[];
+    } & Record<string, unknown>;
 }
+/**
+ * A component is a DRAFT until published; only the published copy reaches a visitor.
+ * Mirrors pages and entries. See migration 0186_component_draft_live_split.sql.
+ */
+type ComponentStatus = "draft" | "published";
 interface Component {
     id: string;
     workspaceId: string;
@@ -383,14 +741,41 @@ interface Component {
      * of one section. Null/absent = an ordinary component, not shown in the section library.
      */
     sectionType?: string | null;
+    /** First-class variant family membership; exact workspace/project scope is enforced in DB. */
+    variantGroupId?: string | null;
+    variantInputMappings?: VariantInputMapping[];
+    /** Placement governance: `*`, `slug:<page-slug>`, and/or `type:<page-type>`. */
+    allowedOn: string[];
     description?: string | null;
+    /** The DRAFT definition. Every builder/autosave/import write path targets these two. */
     blockJson: ContentBlock[];
     props: ComponentPropDef[];
+    status: ComponentStatus;
+    /**
+     * The LIVE snapshot get_components_by_handle() serves. Null until the first publish.
+     * Returned by GET-one (the Compare view needs it), omitted from list rows for payload.
+     */
+    publishedBlockJson?: ContentBlock[] | null;
+    publishedProps?: ComponentPropDef[] | null;
+    publishedAt?: string | null;
+    /**
+     * Computed in SQL on list/get, never stored:
+     *   status='published' AND (blockJson or props has diverged from its published copy).
+     * An exact jsonb compare, so it self-clears when an edit is reverted.
+     */
+    pendingChanges?: boolean;
     thumbnail?: string | null;
     createdAt: string;
     updatedAt: string;
 }
-/** Public/delivery projection — the fields a renderer needs to resolve instances. */
+/**
+ * Public/delivery projection — the fields a renderer needs to resolve instances.
+ *
+ * DELIBERATELY UNCHANGED by the 0186 draft/live split: delivery aliases
+ * publishedBlockJson -> blockJson, so every already-deployed site and every
+ * bcms-content.json on disk keeps a byte-identical wire shape. Do not add `status` here —
+ * delivery only ever returns published rows, so it would always be the same constant.
+ */
 interface DeliveryComponent {
     id: string;
     name: string;
@@ -411,6 +796,7 @@ interface ContentEntry {
     slug: string;
     title: string;
     blocks: ContentBlock[];
+    layout?: DeliveredLayout | null;
     updatedAt: string;
 }
 
@@ -423,7 +809,11 @@ interface ContentModel {
     workspaceId: string;
     name: string;
     description?: string;
+    /** 'block' models hold no entries — they are instantiable only inside a `modular` field. */
+    kind?: ContentModelKind;
     fields: ContentModelField[];
+    /** Authoring-only field grouping for the schema builder. Never affects the API shape. */
+    fieldsets?: Fieldset[];
     createdAt: string;
     updatedAt: string;
 }
@@ -433,7 +823,13 @@ interface ContentModel {
  * by the API but normalized to `array` + zones on write, so stored/delivered
  * content never contains them.
  */
-type ContentModelFieldType = "text" | "richtext" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref";
+type ContentModelFieldType = "text" | "richtext" | "document" | "image" | "boolean" | "number" | "select" | "reference" | "multi-reference" | "multiReference" | "array" | "date" | "datetime" | "longtext" | "slug" | "email" | "phone" | "link" | "color" | "json" | "file" | "component-ref" | "modular" | "sections" | "location";
+type ContentModelKind = "model" | "block";
+/** A named, UI-only grouping of a model's fields. Order is the array index. */
+interface Fieldset {
+    id: string;
+    name: string;
+}
 /**
  * Nested-content config for an `array` field. A zone holds ordinary fields, and a
  * zone field may itself be an `array` with its own zones, so nesting is recursive
@@ -462,6 +858,38 @@ interface FieldConfig {
     max?: number;
     /** date / datetime */
     includeTime?: boolean;
+    /** modular: SLUGS of the kind='block' models this field accepts. Non-empty. */
+    blockSlugs?: string[];
+    /** modular: bounds on how many block instances the field may hold. */
+    minItems?: number;
+    maxItems?: number;
+    /**
+     * sections: SLUGS of the sections an author may insert into this zone.
+     *
+     * Deliberately NOT named `blockSlugs`. That key means "kind='block' content models" and is
+     * read by ModularField; these are section-registry slugs resolved from a different place.
+     * One key meaning two things is how `blockModels`/`blockSlugs` already drifted apart in the
+     * dashboard — a distinct name costs nothing and cannot be confused at a call site.
+     *
+     * ⚠ ABSENT ≠ EMPTY:
+     *     absent   → UNRESTRICTED, every registry section may be inserted
+     *     []       → DENY ALL, a deliberate empty restriction
+     *     [a, b]   → only those
+     * `[]` means DENY here to match `components.allowed_on` (migration 0190), so two adjacent
+     * allow-lists never disagree about what empty means.
+     *
+     * Absent rather than "all current slugs" because the registry GROWS — it is fed by repo
+     * pushes and project components, so materializing today's slugs at field-creation time would
+     * silently exclude every section shipped afterwards.
+     *
+     * NOT READ DIRECTLY. Insertability is this list INTERSECTED with the component's `allowedOn`
+     * (where that section may be placed), computed by one resolver so the two cannot drift.
+     *
+     * Enforced on NEW picks only. Narrowing the list later must never invalidate sections an
+     * author already placed, the same rule modular's blockSlugs and component-ref's allowlist
+     * follow.
+     */
+    allowedSections?: string[];
     [key: string]: unknown;
 }
 /**
@@ -498,6 +926,11 @@ interface ContentModelField {
     options?: string[];
     /** Per-type config. For `array`: either `itemType` (primitive) or `zones` (nested). */
     config?: FieldConfig | null;
+    /**
+     * Which fieldset this field renders under in the schema builder. Authoring-only: it is
+     * never delivered and cannot move a value — see {@link Fieldset}.
+     */
+    fieldsetId?: string;
     /**
      * Authoring-only editor placement. See {@link ContentModelFieldPlacement}.
      * Field ORDER is the array index — there is deliberately no `order` property.
@@ -618,6 +1051,7 @@ interface SiteSeoDefaults {
 }
 /** A published page with its rendered block tree. */
 interface DeliveryPage {
+    projectId?: string | null;
     slug: string;
     title: string;
     metaTitle: string | null;
@@ -625,6 +1059,7 @@ interface DeliveryPage {
     /** Rich SEO (OG / Twitter / canonical / JSON-LD). Always present; `null` when unset. */
     metaJson: PageMetaJson | null;
     blocks: ContentBlock[];
+    layout?: DeliveredLayout | null;
     updatedAt: string | null;
     publishedAt: string | null;
 }
@@ -811,4 +1246,4 @@ type DeepReadonly<T> = T extends Function ? T : T extends object ? {
  */
 type AssertEqual<L, R> = [L] extends [R] ? ([R] extends [L] ? true : false) : false;
 
-export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, type BetterCMSErrorCode, type BlockStyle, type BlockType, type ButtonBlock, type ButtonProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentPropDef, type ComponentProps, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentPageResult, type ContentResponse, type DeepReadonly, type DeliveryComponent, type DeliveryEntry, type DeliveryList, type DeliveryPage, type FieldConfig, 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, type MediaAsset, type NavLink, type NavbarBlock, type NavbarProps, type Page, type PageMetaJson, type PaginatedResult, type Perspective, type PortableTextDocument, type PortableTextNode, type RadiusToken, type Redirect, type RichTextBlock, type RichTextProps, type SectionBlock, type SectionProps, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, getBlockType, isBlock };
+export { type AlignToken, type ApiError, type ApiKey, type ApiKeyPermission, type ApiKeyTokenType, type ArrayZoneConfig, type AssertEqual, type AuthResponse, type AuthSession, type AuthUser, type BetterCMSErrorCode, type BlockStyle, type BlockType, type ButtonBlock, type ButtonProps, type CanonicalInputDefinition, type CollectionBlock, type CollectionProps, type ColorToken, type ColumnsBlock, type ColumnsProps, type Component, type ComponentBlock, type ComponentCategory, type ComponentPropDef, type ComponentProps, type ComponentVariantGroup, type Content, type ContentBlock, type ContentEntry, type ContentModel, type ContentModelField, type ContentModelFieldType, type ContentPageResult, type ContentResponse, type DeepReadonly, type DeliveredLayout, type DeliveryComponent, type DeliveryEntry, type DeliveryList, type DeliveryPage, FOOTER_SECTION_ID, type FieldConfig, 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, LAYOUT_SECTION_ICONS, LAYOUT_SECTION_ICON_SET, type LayoutComponentItem, type LayoutDataDocument, type LayoutFieldDefinition, type LayoutFieldItem, type LayoutFieldType, type LayoutScalarFieldType, type LayoutSection, type LayoutSectionIcon, type LayoutSectionItem, type LayoutStructureDocument, type LayoutZone, type ManagementLayoutCommand, type MediaAsset, 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 RadiusToken, type Redirect, type ReservedLayoutSection, type ResolvedLayoutNode, type RichTextBlock, type RichTextProps, type SectionBlock, type SectionProps, type SignInInput, type SignUpInput, type SiteSeoDefaults, type SlideItem, type SliderBlock, type SliderProps, type SpaceToken, type SpacerBlock, type SpacerProps, type TabItem, type TabsBlock, type TabsProps, type TextBlock, type TextProps, type VariantInputMapping, type VideoBlock, type VideoProps, type WeightToken, type Workspace, type ZoneField, blockStyleToCss, getBlockType, isBlock };