@bettercms-ai/next 0.23.0 → 0.25.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { PageMetaJson, ContentBlock, DeliveredLayout, FieldStyles, SiteSeoDefaults, BlockStyle, FieldStyle, DeliveryComponent } from '@bettercms-ai/types';
-export { DeliveredLayout, PageMetaJson, RESPONSIVE_CSS, SiteSeoDefaults } from '@bettercms-ai/types';
+export { DeliveredLayout, LinkValue, PageMetaJson, RESPONSIVE_CSS, SiteSeoDefaults, linkHref } from '@bettercms-ai/types';
 import { Metadata } from 'next';
 import { SeoInput, SeoLocation, DeliveryForm } from '@bettercms-ai/sdk';
 export { ResolvedSeo, SeoInput, resolveSeo } from '@bettercms-ai/sdk';
-import { CSSProperties, ReactElement, ElementType, ReactNode } from 'react';
+import { CSSProperties, ReactElement, ReactNode, ElementType, ImgHTMLAttributes } from 'react';
+import { ImageSource, ImageFormat, ImageFit } from '@bettercms-ai/image-url';
 export { ImageCrop, ImageFit, ImageFocal, ImageFormat, ImageSource, ImageUrlBuilder, ImageValueUrlOptions, imageUrl, default as imageUrlBuilder, imageValueObjectPosition, imageValueUrl } from '@bettercms-ai/image-url';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
@@ -586,12 +587,124 @@ interface BcmsBlocksProps {
     showScheduled?: boolean;
 }
 
+/**
+ * The data `<BcmsSections>` renders from, read from the published snapshot (`bcms-content.json`
+ * at build time, `BCMS_CONTENT_FILE` on a server BetterCMS hosts).
+ *
+ * Server-side: in the App Router call `sectionsFor` in the page itself; in the Pages Router the
+ * page component also renders in the browser, where there is no snapshot, so the list must travel
+ * as page props or the client would draw the source order over the server's (`sectionsStaticProps`).
+ */
+
+interface SectionsData {
+    page: string;
+    /** The page's published blocks. Null when there is no snapshot or the page is not in it. */
+    blocks: ContentBlock[] | null;
+    components: DeliveryComponent[];
+    forms: DeliveryForm[];
+}
+/** Which of two pages that share a slug is read. */
+interface SectionsRead {
+    /**
+     * The collection page of this slug, whose list is its item TEMPLATE's: what a dynamic route
+     * (`blog/[slug]`) draws on every entry. Without it the read is a page of its own route, the
+     * listing page beside a collection included.
+     */
+    template?: boolean;
+}
+/** `<BcmsSections {...sectionsFor("home")}>`. Never throws; JSON-serialisable, so it can be a page prop. */
+declare function sectionsFor(page: string, read?: SectionsRead): SectionsData;
+/** A data function's answer with the page's sections among its props; a redirect or `notFound` as it is. */
+type WithSections<R> = R extends {
+    props: infer P;
+} ? Omit<R, "props"> & {
+    props: Awaited<P> & {
+        bcmsSections: SectionsData;
+    };
+} : R;
+/**
+ * Pages Router: `export const getStaticProps = sectionsStaticProps("home")`, then
+ * `<BcmsSections {...bcmsSections}>` in a page that takes `{ bcmsSections }`.
+ *
+ * A page with a data function of its own passes it in: `sectionsStaticProps("home", pageStaticProps)`
+ * calls it with the same context and adds `bcmsSections` to the props it answers. Whatever else it
+ * answers (`revalidate`, a redirect, `notFound`) is the page's own and is returned unchanged.
+ *
+ * A dynamic route passes `{ template: true }` last: `sectionsStaticProps("blog", pageStaticProps,
+ * { template: true })` reads the collection page's list, which every entry route draws.
+ */
+declare function sectionsStaticProps(page: string, own?: undefined, read?: SectionsRead): () => Promise<{
+    props: {
+        bcmsSections: SectionsData;
+    };
+}>;
+declare function sectionsStaticProps<C, R>(page: string, own: (context: C) => R | Promise<R>, read?: SectionsRead): (context: C) => Promise<WithSections<R>>;
+/** The same merge for `getServerSideProps`. */
+declare const sectionsServerSideProps: typeof sectionsStaticProps;
+
+/**
+ * <BcmsSections> — a code-built page's sections, in the order its CMS page lists them.
+ *
+ *   <BcmsSections {...sectionsFor("home")}>
+ *     <BcmsSection bind="hero"><Hero /></BcmsSection>
+ *     <BcmsSection bind="features">{(root) => <Features rootProps={root} />}</BcmsSection>
+ *   </BcmsSections>
+ *
+ * Each section the page can draw is a `<BcmsSection>` child, named by its placement's bind: what is
+ * inside is the site's own and is rendered as written. The CMS page's block list decides the rest:
+ *
+ * - a block bound to a section renders it at the block's position, stamped (below);
+ * - a block with no bind (a section added from the library) renders through `<BcmsBlocks>`;
+ * - a section no block names: `code:<bind>` always renders where the source has it; a bare `<bind>`
+ *   does too until the list names one of this page's sections, and from then on it is a removed one.
+ *
+ * With `blocks` null (a build without a snapshot) every child renders in source order, untouched.
+ *
+ * THE STAMP goes on the section's own root, never on a box of ours that changes layout:
+ * - one DOM element (`<section>`): `data-bcms-block`, `data-bcms-style` and the block's style are
+ *   cloned onto it, its own style first;
+ * - a function child is handed those props and puts them on its root itself: the way a COMPONENT
+ *   section takes its style, since a component may not pass unknown props on;
+ * - a component or several children: a box of ours carries the stamp. `display:contents` while
+ *   the block has no style, so the page lays out as written; `display:flow-root` with the style on
+ *   it once the block has one, because a box that draws nothing cannot show a padding. A styled
+ *   box is ONE block box: in a flex or grid parent its children are one item, and their margins
+ *   stop collapsing with the neighbours'. The function-child form has no box and no such limit.
+ *
+ * Server-safe (no hooks, no "use client"): a Server Component in the App Router, and plain React
+ * in the Pages Router, where `blocks` must come through page props so the client renders the same
+ * list (`sectionsStaticProps`). Twin: BcmsSections.astro in @bettercms-ai/astro; the order is
+ * `planSections` in @bettercms-ai/types.
+ */
+
+/** What a function child receives: spread it on the section's root element. Empty when no block places the section. */
+type SectionRootProps = Partial<SectionRootAttrs> & {
+    "data-bcms-sections"?: string;
+};
+interface BcmsSectionProps {
+    /** The placement's bind (`hero`), or `code:<bind>` for a section the CMS did not hold when the page was wrapped. */
+    bind: string;
+    children: ReactNode | ((root: SectionRootProps) => ReactNode);
+}
+interface BcmsSectionsProps {
+    /** The CMS page's slug: `home`, `services`. */
+    page: string;
+    /** The page's block list: `sectionsFor(slug).blocks`, or a draft read. Null or absent renders the source order. */
+    blocks?: ContentBlock[] | null;
+    /** Component definitions and forms for the sections `<BcmsBlocks>` draws. */
+    components?: DeliveryComponent[];
+    forms?: DeliveryForm[];
+    /** The instant block windows are read against. Defaults to the render time. */
+    now?: Date;
+    children?: ReactNode;
+}
+
 interface BcmsFieldProps {
     /** Field path in the editor grammar, e.g. `title` or `facts[2].label`. */
     path: string;
     /** Kind hint the editor's reflection branches on. Omit for plain text/number. */
     kind?: "richtext" | "image";
-    /** Wrapper element. Defaults to a `display:contents` span. */
+    /** Wrapper element. Without it: no wrapper around a single DOM element, a `display:contents` span around anything else. */
     as?: ElementType;
     children: ReactNode;
 }
@@ -606,6 +719,32 @@ interface BcmsButtonProps {
 }
 declare function BcmsButton({ path, value, className }: BcmsButtonProps): react_jsx_runtime.JSX.Element | null;
 
+/** What delivery adds to an image value beside its url: the facts this component reads. */
+type ImageFacts = {
+    altText?: string | null;
+    alt?: string | null;
+    width?: number | null;
+    height?: number | null;
+    focalX?: number | null;
+    focalY?: number | null;
+};
+interface BcmsImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "srcSet" | "width" | "height"> {
+    src: ImageSource | (Exclude<ImageSource, string> & ImageFacts);
+    /** The field this image renders, in the editor grammar (`cover`, `hero.image`). */
+    path?: string;
+    width?: number;
+    height?: number;
+    format?: ImageFormat;
+    quality?: number;
+    fit?: ImageFit;
+    /** Focal point override, 0–1. Normally omitted: the value and the asset carry their own. */
+    focalX?: number | null;
+    focalY?: number | null;
+    /** Media host for a `src` that is only an asset id. Defaults to the platform's. */
+    baseUrl?: string;
+}
+declare function BcmsImage({ src, path, alt, width, height, format, quality, fit, sizes, loading, focalX, focalY, baseUrl, style, ...rest }: BcmsImageProps): react_jsx_runtime.JSX.Element;
+
 /** A `change` frame off the live stream. */
 interface BcmsChangeEvent<T = unknown> {
     type: "entry" | "page";
@@ -687,4 +826,4 @@ interface VisualEditingProps {
     studioUrl?: string;
 }
 
-export { type BcmsBlocksProps, BcmsButton, type BcmsButtonProps, BcmsDraftMarker, BcmsField, type BcmsFieldProps, type BcmsFormProps, type BcmsLiveProps, type BetterCMSConfig, type BetterCMSEntry, BetterCMSError, type BetterCMSLiveConfig, type BetterCMSNext, type BetterCMSPage, type ContentSnapshot, type ContentSource, DEFAULT_SNAPSHOT_FILE, type DraftModeRouteConfig, type EntryList, type FieldAttrs, type GetEntryOptions, type ListEntriesOptions, type LlmsModel, type LlmsModelField, type LlmsTxtOptions, type LlmsTxtRouteConfig, PREVIEW_TOKEN_COOKIE, type ReadOptions, type RevalidateRouteConfig, SNAPSHOT_VERSION, type SectionColumnAttrs, type SectionRootAttrs, type SectionRootBlock, type SnapshotForms, type SnapshotPage, type VisualEditingProps, buildMetadata, buildSnapshot, createBetterCMS, createDisableDraftRoute, createDraftModeRoute, createRevalidateRoute, defineBetterCMSLive, fetchModels, fieldAttrs, fieldStyleOf, generateLlmsTxt, getComponent, getContent, getForm, getPage, getPreviewToken, isDraftEnabled, llmsTxtRoute, parseSnapshot, readComponents, readForms, readPages, readSnapshot, sectionColumnAttrs, sectionRootAttrs, serializeSnapshot, writeSnapshot };
+export { type BcmsBlocksProps, BcmsButton, type BcmsButtonProps, BcmsDraftMarker, BcmsField, type BcmsFieldProps, type BcmsFormProps, BcmsImage, type BcmsImageProps, type BcmsLiveProps, type BcmsSectionProps, type BcmsSectionsProps, type BetterCMSConfig, type BetterCMSEntry, BetterCMSError, type BetterCMSLiveConfig, type BetterCMSNext, type BetterCMSPage, type ContentSnapshot, type ContentSource, DEFAULT_SNAPSHOT_FILE, type DraftModeRouteConfig, type EntryList, type FieldAttrs, type GetEntryOptions, type ListEntriesOptions, type LlmsModel, type LlmsModelField, type LlmsTxtOptions, type LlmsTxtRouteConfig, PREVIEW_TOKEN_COOKIE, type ReadOptions, type RevalidateRouteConfig, SNAPSHOT_VERSION, type SectionColumnAttrs, type SectionRootAttrs, type SectionRootBlock, type SectionRootProps, type SectionsData, type SectionsRead, type SnapshotForms, type SnapshotPage, type VisualEditingProps, buildMetadata, buildSnapshot, createBetterCMS, createDisableDraftRoute, createDraftModeRoute, createRevalidateRoute, defineBetterCMSLive, fetchModels, fieldAttrs, fieldStyleOf, generateLlmsTxt, getComponent, getContent, getForm, getPage, getPreviewToken, isDraftEnabled, llmsTxtRoute, parseSnapshot, readComponents, readForms, readPages, readSnapshot, sectionColumnAttrs, sectionRootAttrs, sectionsFor, sectionsServerSideProps, sectionsStaticProps, serializeSnapshot, writeSnapshot };

package/dist/index.js

@@ -222,6 +222,7 @@ function buildMetadata(page, siteDefaults = {}, location = {}) {
 
 // src/index.ts
 import { RESPONSIVE_CSS } from "@bettercms-ai/types";
+import { linkHref } from "@bettercms-ai/types";
 
 // src/section-root.ts
 import { blockStyleToColumnCss, blockStyleToCss, hideOnAttr } from "@bettercms-ai/types";
@@ -620,10 +621,43 @@ function getComponent(idOrSlug, path) {
   );
 }
 
+// src/sections-read.ts
+import { readPublishedContent } from "@bettercms-ai/sdk";
+function pageRow(pages, page, read) {
+  const rows = (Array.isArray(pages) ? pages : []).filter((p) => p?.slug === page);
+  const template = rows.find((row) => row.template === true);
+  return read?.template ? template : rows.find((row) => row.template !== true) ?? rows[0];
+}
+function sectionsFor(page, read) {
+  const snapshot = readPublishedContent();
+  const row = pageRow(snapshot?.pages, page, read);
+  const blocks = row?.blocks ?? row?.blockJson;
+  return {
+    page,
+    blocks: Array.isArray(blocks) ? blocks : null,
+    components: Array.isArray(snapshot?.components) ? snapshot.components : [],
+    forms: Array.isArray(snapshot?.forms) ? snapshot.forms : []
+  };
+}
+function sectionsStaticProps(page, own, read) {
+  return async (context) => {
+    const answer = own ? await own(context) : { props: {} };
+    if (!answer || typeof answer !== "object" || !("props" in answer)) return answer;
+    return { ...answer, props: { ...await answer.props, bcmsSections: sectionsFor(page, read) } };
+  };
+}
+var sectionsServerSideProps = sectionsStaticProps;
+
 // src/field.tsx
+import { Children, cloneElement, isValidElement } from "react";
 import { jsx } from "react/jsx-runtime";
 function BcmsField({ path, kind, as, children }) {
   const Tag = as ?? "span";
+  const only = as ? [] : Children.toArray(children);
+  const sole = only.length === 1 && isValidElement(only[0]) && typeof only[0].type === "string" ? only[0] : null;
+  if (sole && sole.props["data-bcms-field"] === void 0 && sole.props["data-bcms-layout-field"] === void 0) {
+    return cloneElement(sole, { "data-bcms-field": path, "data-bcms-kind": kind });
+  }
   return /* @__PURE__ */ jsx(
     Tag,
     {
@@ -661,6 +695,78 @@ function BcmsButton({ path, value, className }) {
   );
 }
 
+// src/image.tsx
+import imageUrlBuilder, {
+  focalInCrop,
+  normalizeImageCrop,
+  normalizeImageFocal,
+  objectPosition
+} from "@bettercms-ai/image-url";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var LADDER = [480, 768, 1080, 1440, 1920];
+var num = (v) => typeof v === "number" && Number.isFinite(v) ? v : void 0;
+function BcmsImage({
+  src,
+  path,
+  alt,
+  width,
+  height,
+  format = "webp",
+  quality,
+  fit,
+  sizes,
+  loading = "lazy",
+  focalX,
+  focalY,
+  baseUrl,
+  style,
+  ...rest
+}) {
+  const asset = typeof src === "object" && src !== null ? src : {};
+  const explicit = focalX != null || focalY != null;
+  const stored = normalizeImageFocal(asset.focal) ?? (num(asset.focalX) != null || num(asset.focalY) != null ? { x: num(asset.focalX) ?? 0.5, y: num(asset.focalY) ?? 0.5 } : null);
+  const inWindow = stored ? focalInCrop(stored, normalizeImageCrop(asset.crop)) : null;
+  const fx = explicit ? focalX : inWindow?.x;
+  const fy = explicit ? focalY : inWindow?.y;
+  const hasFocal = fx != null || fy != null;
+  const builder = imageUrlBuilder({ baseUrl });
+  const make = () => {
+    let b = builder(src);
+    if (width) b = b.width(width);
+    if (height) b = b.height(height);
+    if (format) b = b.format(format);
+    if (quality) b = b.quality(quality);
+    if (fit) b = b.fit(fit);
+    if (hasFocal) b = b.focal(fx ?? 0.5, fy ?? 0.5);
+    return b;
+  };
+  const src1x = make().url();
+  const own = num(asset.width);
+  const ladder = own ? [.../* @__PURE__ */ new Set([...LADDER.filter((w) => w < own), Math.min(own, LADDER[LADDER.length - 1])])] : LADDER;
+  const srcSet = sizes && !width ? ladder.map((w) => `${make().width(w).url()} ${w}w`).join(", ") : `${src1x} 1x, ${make().dpr(2).url()} 2x`;
+  const merged = {
+    ...width ? { width: `${width}px`, maxWidth: "100%", height: "auto" } : {},
+    ...hasFocal ? { objectPosition: objectPosition({ x: fx, y: fy }) } : {},
+    ...style
+  };
+  return /* @__PURE__ */ jsx3(
+    "img",
+    {
+      src: src1x,
+      srcSet,
+      alt: alt ?? (typeof asset.altText === "string" ? asset.altText : typeof asset.alt === "string" ? asset.alt : ""),
+      "data-bcms-field": path,
+      "data-bcms-kind": path ? "image" : void 0,
+      width,
+      height,
+      sizes,
+      loading,
+      style: Object.keys(merged).length > 0 ? merged : void 0,
+      ...rest
+    }
+  );
+}
+
 // src/live-config.ts
 function defineBetterCMSLive(config) {
   const base = config.apiUrl.replace(/\/+$/, "");
@@ -705,6 +811,7 @@ export {
   BcmsButton,
   BcmsDraftMarker,
   BcmsField,
+  BcmsImage,
   BetterCMSError,
   DEFAULT_SNAPSHOT_FILE,
   PREVIEW_TOKEN_COOKIE,
@@ -731,6 +838,7 @@ export {
   imageValueObjectPosition,
   imageValueUrl,
   isDraftEnabled,
+  linkHref,
   llmsTxtRoute,
   parseSnapshot,
   readComponents,
@@ -740,6 +848,9 @@ export {
   resolveSeo2 as resolveSeo,
   sectionColumnAttrs,
   sectionRootAttrs,
+  sectionsFor,
+  sectionsServerSideProps,
+  sectionsStaticProps,
   serializeSnapshot,
   writeSnapshot
 };