@bettercms-ai/convert 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -514,9 +514,13 @@ interface DynamicBinding {
  * editable and the NUMBER of rows is still the template's — a row added in the CMS does not appear
  * and a deleted one falls back to the template's own copy. The paths are `rewritten` and true; what
  * the note adds is that ceiling. @see bindLists
+ *
+ * `FIELD_STYLE_SKIPPED` is one element this run stamped `data-bcms-field` on and could NOT give the
+ * `data-bcms-style` marker and its style (C3/C9) — its own `style`, a spread, a page it cannot name.
+ * The binding is real; the editor just offers no width or spacing handles on it. @see field-styles.ts
  */
 interface ReceiptNote {
-    code: "TSCONFIG_UNREADABLE" | "TSCONFIG_EXTENDS_ONLY" | "PRIMITIVE_LIST";
+    code: "TSCONFIG_UNREADABLE" | "TSCONFIG_EXTENDS_ONLY" | "PRIMITIVE_LIST" | "FIELD_STYLE_SKIPPED";
     file: string;
     message: string;
 }
@@ -957,7 +961,7 @@ declare function attrsFor(path: string, kind: string, props?: AttrBinding[], sco
 declare function propsAttribute(props: AttrBinding[]): string;
 
 /** Bumped whenever the emitted source changes. `isKnownHelper` upgrades anything older. */
-declare const HELPER_VERSION = 14;
+declare const HELPER_VERSION = 15;
 /** Where each dialect's helper lives. Null = this dialect reads nothing at build time. */
 declare const HELPER_PATH: Record<Dialect, string | null>;
 /** The directory the snapshots live in, at the repository root. */
@@ -1203,6 +1207,8 @@ interface ImageTarget {
     /** The brief's `original` — the BUILT url. */
     original: string;
     slug: string;
+    /** The file already declares this path: only a missing READ is added, and nothing is refused. */
+    declared?: boolean;
 }
 interface ImageSplice {
     start: number;
@@ -1885,6 +1891,38 @@ interface BcmsBuild {
  */
 declare function bcmsBuildScript(packageJson: string): BcmsBuild | null;
 
+/**
+ * `--upgrade-sections`: give the section roots of a site converted BEFORE helper v10 the
+ * `data-bcms-style` marker, so the editor's section spacing and style handles (C3/C4) turn on.
+ *
+ * The editor shows those handles on a site-rendered page only when EVERY root the page stamps
+ * with `data-bcms-block` also carries `data-bcms-style` — the site's promise that "this root's
+ * inline style is `blockStyleToCss(block.style)`". A conversion made before v10 stamped the block
+ * and never the style, so one unmarked root keeps the whole page off the lane. This pass makes the
+ * promise TRUE before it makes it: a root gets the marker only together with the style that keeps
+ * it, and only where the block that style belongs to can be named.
+ *
+ * Three ways a root can be given its style, chosen per root:
+ *
+ * - `section-prop` — a component `--componentize` wrote (`data-bcms-block={blockId}` in a file with
+ *   the section marker). The registry passes each placement's `block.style` as `blockStyle`, so the
+ *   root gets exactly what a fresh extraction writes today, the component gains the `blockStyle`
+ *   prop, and a registry or `bcms-sections` that predates it is patched to pass it.
+ * - `sectionRootAttrs` — `data-bcms-block={block.id}` in a repository whose SDK exports
+ *   `sectionRootAttrs`: the attribute becomes `{...sectionRootAttrs(block)}`, which carries the id,
+ *   the marker and the style in one spread.
+ * - `helper` — the same root where the SDK is older: `data-bcms-style="" style={…(block.style)}`
+ *   through the committed helper, which this pass upgrades (or adds) for the purpose.
+ *
+ * Everything else is LEFT ALONE and receipted with a reason: a root that already decides its own
+ * inline style (a `style` attribute or a spread — which of two styles wins depends on the dialect),
+ * and a root whose block cannot be named here (only an id string reaches it, a literal id, a
+ * conditional). Marking one of those would paint a capsule the build never ships.
+ *
+ * Nothing else changes: no class, className or existing style token, which `--verify-styles`
+ * checks, and a second run finds every root it marked already marked.
+ */
+
 /** The plan's own file shape, restated rather than imported to keep `index.ts` acyclic. */
 interface UpgradeFile {
     path: string;
@@ -1963,6 +2001,77 @@ declare function upgradeSections(sources: readonly SourceFile[], options?: Upgra
     receipt: SectionUpgradeReceipt;
 }>;
 
+/** Why a field element was left without the marker. */
+type FieldStyleSkipReason = 
+/** The element has its own `style` attribute; a second one would be resolved by the dialect. */
+"OWN_STYLE"
+/** The element has a spread (`{...rest}`) that may carry a style. */
+ | "SPREAD"
+/** A component tag other than `astro:assets` / `next/image`: whether it passes `style` on is unknown. */
+ | "NOT_AN_ELEMENT"
+/** `data-bcms-layout-field`: the shared chrome has no page whose `fieldStyles` it could read. */
+ | "LAYOUT_FIELD"
+/** An instance's own address (`<blockId>__overrides.<key>`): the section's `bind` owns it. */
+ | "COMPONENT_INSTANCE"
+/** The address is computed (`{f("hero.title")}`, a prop): no path this pass can repeat. */
+ | "PATH_UNRESOLVABLE"
+/** `data-bcms-kind` other than text, richtext or image. */
+ | "KIND"
+/** No page snapshot is imported here, or more than one and the element reads none of them. */
+ | "NO_SNAPSHOT"
+/** The reader's name already means something else in this file. */
+ | "NAME_TAKEN"
+/** A dialect this pass does not rewrite (html, vue, svelte). */
+ | "DIALECT_UNSUPPORTED"
+/** The file did not parse. */
+ | "PARSE_ERROR";
+interface FieldStyleRef {
+    file: string;
+    /** 1-based line of the element's `<`. */
+    line: number;
+    tag: string;
+    /** The `data-bcms-field` attribute as written: `data-bcms-field="hero-h1"`, `` data-bcms-field={`g[${i}].h3`} ``. */
+    field: string;
+}
+interface SkippedFieldStyle extends FieldStyleRef {
+    reason: FieldStyleSkipReason;
+    message: string;
+}
+/** The reader each dialect's style attribute calls: a string for Astro, an object for JSX. */
+declare const FIELD_STYLE_READER: Record<"astro" | "jsx", string>;
+/**
+ * Mark every page-field element in one parsed file that this pass can keep the promise for.
+ *
+ * `skip` names elements to pass over without a word — the ones a conversion did not stamp itself.
+ */
+declare function markFieldStyles(file: string, content: string, dialect: "astro" | "jsx", parsed: ParsedFile, skip?: (field: string) => boolean): {
+    content: string;
+    marked: FieldStyleRef[];
+    alreadyMarked: FieldStyleRef[];
+    skipped: SkippedFieldStyle[];
+};
+interface ElementStyleUpgradeReceipt {
+    /** The helper at `src/bcms-content.ts` (and its siblings), when there is one or this pass wrote one. */
+    helpers: SectionUpgradeReceipt["helpers"];
+    fields: {
+        upgraded: (FieldStyleRef & {
+            form: "helper";
+        })[];
+        alreadyMarked: FieldStyleRef[];
+        skipped: SkippedFieldStyle[];
+    };
+}
+/**
+ * `--upgrade-element-styles`: the same marker for a site converted before helper v15, over every
+ * `data-bcms-field` element in the repository, plus the helper upgrade that makes the reader exist.
+ */
+declare function upgradeElementStyles(sources: readonly SourceFile[], options?: {
+    overwriteHelper?: boolean;
+}): Promise<{
+    files: UpgradeFile[];
+    receipt: ElementStyleUpgradeReceipt;
+}>;
+
 /** One file operation, exactly as `src/lib/github/plan-digest.ts` spells it. */
 interface PlanFile {
     path: string;
@@ -1997,4 +2106,4 @@ declare function convertSources(briefIn: Brief, sources: SourceFile[], options?:
     receipt: ConversionReceipt;
 }>;
 
-export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type BcmsBuild, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, FORM_SCRIPT, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type HelperUpgrade, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionUpgradeReceipt, type SectionsReceipt, type Site, type SiteWhere, type SkippedRoot, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, UpgradeError, type UpgradeOptions, type UpgradeRootRef, type UpgradeSkipReason, type UpgradedRoot, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bcmsBuildScript, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, helperUpgrades, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, upgradeSections, walkAst, wireForms };
+export { ASTRO_LANE_PENDING, type AstNode, type AttrBinding, type BcmsBuild, type Brief, type BriefForm, type BriefPage, type BriefPath, COMPONENT_DIR, CONTENT_DIR, type CanvasResult, type CanvasSource, type Carried, type ComponentizeOptions, type ComponentizePlan, type ComponentizePlanComponent, type ComponentizePlanField, type ComponentizePlanPage, type ComponentizePlanSection, type ComponentizeReceipt, type ConversionReceipt, ConvertError, type ConvertErrorCode, type ConvertOptions, DIALECT_RULES, type DataMember, type DataResult, type DeclaredPath, type Dialect, type DynamicBinding, type ElementStyleUpgradeReceipt, FIELD_STYLE_READER, FORM_SCRIPT, type FieldStyleRef, type FieldStyleSkipReason, type FileDeclaration, type FindSitesResult, type FixAction, FormInvariantError, type FormPendingReason, type FormsReceipt, HELPER_PATH, HELPER_VERSION, type HelperUpgrade, type ImageResult, type ImageTarget, type ImportedFrom, type LlmFallback, type LocatedPath, type Node, PARSE_FILE, type ParsedFile, type ParserError, type PathLocator, type PendingFix, type PendingForm, type PendingPath, type PendingReason, type PendingSection, type PlanFile, REGISTRY_MARKER, type ReceiptFile, ReceiptInvariantError, type ReceiptNote, type Rewrite, SECTIONS_LIB, SECTION_MARKER, SKIP_DIRS, SKIP_FILES, SOURCE_EXTENSIONS, SSR_DRAFT_RECIPE, STUB_CONTENT, SectionInvariantError, type SectionPendingReason, type SectionUpgradeReceipt, type SectionsReceipt, type Site, type SiteWhere, type SkippedFieldStyle, type SkippedRoot, type SourceFile, type Splice, type TargetIdentity, type UnlocatedPath, UpgradeError, type UpgradeOptions, type UpgradeRootRef, type UpgradeSkipReason, type UpgradedRoot, type ValidationCode, ValidationError, type Xray, type XrayBucket, aliasesFrom, assertForms, assertReceipt, assertSections, assetCandidates, assetImport, attrsFor, bcmsBuildScript, bindDataLiterals, bindImages, briefDigest, canvasBridge, carryFor, componentizeSources, convertSources, convertedHere, coverageOf, declaringElements, dialectOf, exportedFunction, extendedConfigs, findLiteral, findSites, findSitesTolerant, fixFor, flat, helperSource, helperUpgrades, importsIn, isDecorativeGlyph, isDynamicRoute, isKnownHelper, isSourceCandidate, locate, markFieldStyles, measureUnaddressable, overlapping, pageFilesFor, parseFile, propsAttribute, readBrief, readComponentizePlan, readDeclarations, readExpr, readPlan, relativeImport, resolveSpecifier, rewriteFile, routeCounts, routeOfFile, stripTags, unreadableConfigs, upgradeElementStyles, upgradeSections, walkAst, wireForms };