@bettercms-ai/convert 0.26.1 → 0.27.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @bettercms-ai/convert
 
+## 0.27.0
+
+### Minor Changes
+
+- a69e514: Page-field styles (C3/C9) on converted sites. Helper v15 adds `bcmsStyle(page, path)` (a style object, JSX) and `bcmsStyleText(page, path)` (a CSS string, Astro): `fieldStyleToCss` inlined, reading the page's `fieldStyles` — from the published `pages[]` row in `BCMS_CONTENT_FILE` on a server BetterCMS hosts, from the snapshot at build — and nothing (no `style` attribute) for an unstyled field. v14 is recognised, so a BetterCMS build swaps it for v15. A conversion now gives every element it stamps `data-bcms-field` on `data-bcms-style=""` and `style={bcmsStyleText(…)}` / `style={bcmsStyle(…)}` (a repeater row with its own template address), so the editor offers that element's width, spacing, Align, Size and Weight controls; an element with its own `style` or a spread is left alone and noted as `FIELD_STYLE_SKIPPED`. `--upgrade-element-styles [--dry-run]` does the same to a site converted before, with the helper upgrade, and receipts each element as upgraded, already marked or skipped with its reason.
+
+### Patch Changes
+
+- Updated dependencies [9ea579c]
+  - @bettercms-ai/types@1.37.0
+
 ## 0.26.1
 
 ### Patch Changes

package/README.md

@@ -640,6 +640,46 @@ className or existing style token changes (`--verify-styles` stays clean), and a
 nothing and counts every root it marked as `alreadyMarked`. `--strict` exits 2 while any root is
 skipped.
 
+### Element style handles on a field (`--upgrade-element-styles`)
+
+A page field's own width, spacing, Align, Size and Weight (C3, `pages.fieldStyles` keyed by the
+`data-bcms-field` address) are offered only on an element that also carries `data-bcms-style` —
+the site's promise that its inline style is `fieldStyleToCss(page.fieldStyles[path])`. Helper v15
+reads them: `bcmsStyleText(page, path)` (a CSS string, for Astro) and `bcmsStyle(page, path)` (an
+object, for JSX), from the published page row in `BCMS_CONTENT_FILE` on a server BetterCMS hosts and
+from the snapshot at build. No style stored: `undefined`, so no `style` attribute at all.
+
+A conversion from 0.27 on marks each element it stamps (text, richtext, image, the text of a
+link) — a repeater row with its own template address:
+
+```astro
+<h1 class="type-hero" data-bcms-field="shell-h1-x" data-bcms-kind="text" data-bcms-style="" style={bcmsStyleText(bcmsHome, "shell-h1-x")}>…</h1>
+<h3 data-bcms-field={`g[${index}].h3-x`} data-bcms-kind="text" data-bcms-style="" style={bcmsStyleText(bcmsHome, `g[${index}].h3-x`)}>…</h3>
+```
+
+A site converted before that takes the same marks in one run, with the helper upgraded alongside
+(a BetterCMS build also swaps an older helper of ours for v15 in its own checkout):
+
+```bash
+npx @bettercms-ai/convert@latest --upgrade-element-styles --root . --dry-run   # read the plan
+npx @bettercms-ai/convert@latest --upgrade-element-styles --root .             # then push and release
+```
+
+Always the helper form, never the SDK's `{...fieldAttrs(…)}` spread: the spread would hide the
+literal `data-bcms-field` every reader of a converted file finds by its bytes, and only the helper
+follows a publish on a hosted server. Left alone, and listed as `skipped` with a reason:
+`OWN_STYLE`, `SPREAD`, `NOT_AN_ELEMENT` (a component other than `astro:assets`' `Image`/`Picture`
+or `next/image`), `LAYOUT_FIELD` (the chrome is not a page's), `COMPONENT_INSTANCE` (an
+`__overrides` address), `PATH_UNRESOLVABLE` (a computed address), `KIND` (not text, richtext or
+image), `NO_SNAPSHOT` (no page snapshot imported, or several and the element reads none),
+`NAME_TAKEN`, `DIALECT_UNSUPPORTED` (html, vue, svelte), `PARSE_ERROR`. A conversion lists the
+elements it stamped and could not mark as `FIELD_STYLE_SKIPPED` notes.
+
+The receipt (`--receipt <file>`) is `{ helpers, fields: { upgraded, alreadyMarked, skipped } }`,
+each element as `{ file, line, tag, field, form | reason + message }` (`field` is the attribute as
+written). `--verify-styles` stays clean — an expression style is no token — a second run writes
+nothing, and `--strict` exits 2 while any element is skipped.
+
 ## Forms
 
 The third mode, and the shortest. The release-time derive lane reads every `<form>` in the built