create-nextblock 0.16.2 → 0.16.4

package/templates/nextblock-template/lib/seo/page-document.test.ts

@@ -347,4 +347,72 @@ describe('buildPageSeoDocument feeding the page-level audit', () => {
     expect(oneBlock.issues.map((issue) => issue.id)).toContain('content-thin');
     expect(wholePage.issues.map((issue) => issue.id)).not.toContain('content-thin');
   });
+
+  it('treats post title as H1 when documentType is post', () => {
+    const blocks = [
+      headingBlock(2, 'Overview'),
+      textBlock('<p>Detailed article content goes here.</p>'),
+    ];
+
+    const withoutOptions = buildPageSeoDocument(blocks);
+    expect(withoutOptions.headings.map((h) => h.level)).toEqual([2]);
+
+    const withPost = buildPageSeoDocument(blocks, {
+      documentTitle: 'My Great Article',
+      documentType: 'post',
+    });
+    expect(withPost.headings).toEqual([
+      { level: 1, order: 0, text: 'My Great Article' },
+      { level: 2, order: 1, text: 'Overview' },
+    ]);
+    expect(withPost.words).toContain('my');
+    expect(withPost.words).toContain('article');
+
+    const audit = auditSeo({ document: withPost });
+    expect(audit.issues.map((i) => i.id)).not.toContain('headings-missing-h1');
+  });
+
+  it('handles empty blocks with post title', () => {
+    const doc = buildPageSeoDocument([], {
+      documentTitle: 'Initial Draft Post',
+      documentType: 'post',
+    });
+    expect(doc.headings).toEqual([{ level: 1, order: 0, text: 'Initial Draft Post' }]);
+    expect(doc.text).toBe('Initial Draft Post');
+  });
+
+  it('prepends product title as H1 when documentType is product', () => {
+    const blocks = [
+      {
+        block_type: 'section',
+        content: {
+          column_blocks: [
+            [
+              {
+                block_type: 'heading',
+                content: { level: 2, text_content: 'Features' },
+              },
+            ],
+          ],
+        },
+      },
+    ];
+
+    const withProduct = buildPageSeoDocument(blocks, {
+      documentTitle: 'NextBlock Commerce Pro',
+      documentType: 'product',
+    });
+
+    expect(withProduct.headings).toEqual([
+      { level: 1, order: 0, text: 'NextBlock Commerce Pro' },
+      { level: 2, order: 1, text: 'Features' },
+    ]);
+    expect(withProduct.words).toContain('commerce');
+    expect(withProduct.words).toContain('pro');
+
+    const audit = auditSeo({ document: withProduct });
+    expect(audit.issues.map((i) => i.id)).not.toContain('headings-missing-h1');
+  });
 });
+
+

package/templates/nextblock-template/lib/seo/page-document.ts

@@ -1,412 +1,4 @@
-import {
-  buildSeoDocument,
-  emptySeoDocument,
-  isExternalHref,
-  tokenizeWords,
-  type SeoDocument,
-  type SeoHeading,
-  type SeoHeadingLevel,
-  type SeoImage,
-  type SeoLink,
-} from '@nextblock-cms/utils/seo';
-
-/**
- * Flattens a page's blocks into the single `SeoDocument` the audit grades.
- *
- * The SEO engine in `@nextblock-cms/utils/seo` was written against one document
- * that represents one page, but the CMS does not store a page as one document:
- * it stores a list of block rows, each holding its own slice of content in its
- * own differently-named field, with most of a real page's copy nested two
- * levels down inside a `section` block's columns. Auditing those rows one at a
- * time is what produced the finding this module exists to retire — "this page
- * has no H1 heading" reported against a single paragraph, when the H1 was sitting
- * in a `heading` block two rows above and the auditor was never shown it.
- *
- * So this walks the whole list in document order and merges everything into one
- * document, which lets `auditSeo` answer the questions it was designed to
- * answer — is there exactly one H1, is there enough copy, where does the
- * keyphrase fall — about the page a visitor actually reads.
- *
- * Two properties are load-bearing and every change here has to preserve them:
- *
- *  - **Nothing throws.** `content` is `Json` straight out of Postgres, and the
- *    editor hands us half-typed state on every keystroke, so a field can be
- *    null, a number, an array where an object was expected, or absent. Every
- *    read below tolerates that and skips rather than reporting. An unrecognised
- *    block — a custom block, whose content shape is whatever its author defined
- *    — is skipped for the same reason: guessing at arbitrary keys would put the
- *    author's internal configuration strings into the page's word count.
- *  - **It stays linear and allocation-light.** This runs behind the analysis
- *    panel's debounce, so it is re-run every time the author pauses typing. It
- *    makes one pass over the tree, reuses the image and link objects the HTML
- *    reader already built instead of copying them, and joins the text exactly
- *    once at the end.
- *
- * One known and accepted limitation: `buildSeoDocument` records where blocks
- * divide the token stream so a multi-word keyphrase cannot be counted across a
- * gap the reader can see, and that side table is keyed on the document object
- * it built, so the merged document here does not carry one. The consequence is
- * narrow — a phrase whose words happen to straddle the join between two blocks
- * can be counted once too often — and it is the same fallback any hand-built
- * document has always had. Correcting it needs a way to register boundaries for
- * an assembled document, which is a change to the engine, not to this walker.
- */
-
-/**
- * How deep the walk will follow nested containers before giving up.
- *
- * Sections can hold sections, so the structure is genuinely recursive and has
- * no schema-enforced ceiling. Eight levels is far past anything a human builds
- * and cheap to enforce, and it means a corrupt row that somehow refers back
- * into itself costs a bounded walk instead of a blown stack in the editor.
- */
-const MAX_BLOCK_NESTING_DEPTH = 8;
-
-/**
- * The heading level used when a `heading` block's level is missing or corrupt.
- *
- * This mirrors `HeadingBlockRenderer`, which falls back to an H2 for anything
- * outside 1-6. The audit has to grade the outline the visitor is served, and
- * defaulting to 1 instead would invent an H1 that is nowhere on the page — and
- * then report a second, entirely fictional H1 as a duplicate.
- */
-const FALLBACK_HEADING_LEVEL: SeoHeadingLevel = 2;
-
-/** The accumulating page document, before its parts are joined. */
-interface PageDocumentDraft {
-  headings: SeoHeading[];
-  images: SeoImage[];
-  links: SeoLink[];
-  /**
-   * Each block's text, kept apart until the end and then joined with a single
-   * space. Concatenating without a separator would glue the last word of one
-   * block onto the first word of the next ("…our coffee" + "beans are…" reading
-   * as the single token "coffeebeans"), which corrupts the word count, the
-   * keyphrase density and the readability sample all at once.
-   */
-  textParts: string[];
-  words: string[];
-}
-
-function createDraft(): PageDocumentDraft {
-  return { headings: [], images: [], links: [], textParts: [], words: [] };
-}
-
-/** Narrows to a plain object, which is the only shape a block or content has. */
-function readRecord(value: unknown): Record<string, unknown> | null {
-  return typeof value === 'object' && value !== null && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : null;
-}
-
-/**
- * Reads a field that is supposed to hold display text.
- *
- * Whitespace is collapsed to single spaces to match `SeoDocument.text`, which
- * the readability pass tokenises on the assumption that it already has been.
- * Anything that is not a string reads as empty rather than being coerced,
- * because `String(someObject)` would put "[object Object]" on the page.
- */
-function readText(value: unknown): string {
-  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
-}
-
-/** Clamps a stored heading level onto the six levels HTML actually has. */
-function readHeadingLevel(value: unknown): SeoHeadingLevel {
-  const level = typeof value === 'number' ? Math.trunc(value) : Number.NaN;
-
-  return Number.isFinite(level) && level >= 1 && level <= 6
-    ? (level as SeoHeadingLevel)
-    : FALLBACK_HEADING_LEVEL;
-}
-
-/** Adds a run of plain text, keeping the token stream in step with the text. */
-function appendText(draft: PageDocumentDraft, text: string): void {
-  if (text === '') {
-    return;
-  }
-
-  draft.textParts.push(text);
-  for (const word of tokenizeWords(text)) {
-    draft.words.push(word);
-  }
-}
-
-/**
- * Folds a document the engine already built — one rich-text block's HTML or
- * Tiptap JSON — into the page draft.
- *
- * Headings are renumbered as they land so `order` counts positions on the page
- * rather than positions within whichever block happened to contain them; the
- * audit uses that number to say where the H1 sits, and a per-block number would
- * point the author at the wrong heading.
- */
-function appendDocument(draft: PageDocumentDraft, document: SeoDocument): void {
-  for (const heading of document.headings) {
-    draft.headings.push({ level: heading.level, order: draft.headings.length, text: heading.text });
-  }
-
-  for (const image of document.images) {
-    draft.images.push(image);
-  }
-
-  for (const link of document.links) {
-    draft.links.push(link);
-  }
-
-  if (document.text !== '') {
-    draft.textParts.push(document.text);
-  }
-
-  // `words` is taken from the sub-document rather than re-tokenised from its
-  // text: the engine guarantees the two agree, and re-tokenising would double
-  // the work on the largest blocks on the page for an identical answer.
-  for (const word of document.words) {
-    draft.words.push(word);
-  }
-}
-
-/** Adds one heading block, which is a standalone row rather than inline markup. */
-function collectHeadingBlock(content: Record<string, unknown>, draft: PageDocumentDraft): void {
-  // Not run through an HTML stripper, unlike a rich-text block: the renderer
-  // prints `text_content` as a React child, so any markup in it is escaped and
-  // the visitor sees the angle brackets. Stripping here would analyse text the
-  // page never shows.
-  const text = readText(content['text_content']);
-
-  draft.headings.push({
-    level: readHeadingLevel(content['level']),
-    order: draft.headings.length,
-    text,
-  });
-
-  // A heading is also words on the page. Leaving it out of the text would make
-  // headings free of charge in the word count and invisible to the keyphrase
-  // density, even though they are the most heavily weighted copy on the page.
-  appendText(draft, text);
-}
-
-/**
- * Adds one image block.
- *
- * The source is resolved the way `ImageBlockRenderer` resolves it — an external
- * URL wins, otherwise the R2 object key — and a block with neither is not
- * recorded as an image at all, because that block renders a "media not
- * selected" placeholder. Reporting it would raise "an image is missing alt
- * text" about something the visitor never sees as an image, which is precisely
- * the class of false finding this module was written to remove.
- */
-function collectImageBlock(content: Record<string, unknown>, draft: PageDocumentDraft): void {
-  const externalUrl = readText(content['external_url']);
-  const objectKey = readText(content['object_key']);
-  const source = externalUrl !== '' ? externalUrl : objectKey;
-
-  if (source === '') {
-    return;
-  }
-
-  draft.images.push({ alt: readText(content['alt_text']), src: source });
-
-  // The caption is rendered in a <figcaption> under the image, so it is prose a
-  // reader and a crawler both see, and it belongs in the page's text.
-  appendText(draft, readText(content['caption']));
-}
-
-/** Adds one button block: a link the visitor can follow, with a visible label. */
-function collectButtonBlock(content: Record<string, unknown>, draft: PageDocumentDraft): void {
-  const text = readText(content['text']);
-  const href = readText(content['url']);
-
-  if (href !== '') {
-    draft.links.push({ external: isExternalHref(href), href, text });
-  }
-
-  appendText(draft, text);
-}
-
-/** Adds a testimonial's visible quote and attribution. */
-function collectTestimonialBlock(
-  content: Record<string, unknown>,
-  draft: PageDocumentDraft
-): void {
-  appendText(draft, readText(content['quote']));
-  appendText(draft, readText(content['author_name']));
-  appendText(draft, readText(content['author_title']));
-}
-
-/**
- * Walks `column_blocks`, an array of columns each holding an array of blocks.
- *
- * Column order then block order is the order the page reads in on a phone,
- * where the columns stack, and it is the only total order that exists for this
- * shape. Getting it wrong would not lose any content, but it would misreport
- * which heading comes first and where in the copy the keyphrase falls.
- */
-function collectColumnBlocks(value: unknown, draft: PageDocumentDraft, depth: number): void {
-  if (!Array.isArray(value)) {
-    return;
-  }
-
-  for (const column of value) {
-    if (!Array.isArray(column)) {
-      continue;
-    }
-
-    for (const block of column) {
-      collectBlock(block, draft, depth + 1);
-    }
-  }
-}
-
-/**
- * Walks a section, which is where most of a real page's content lives.
- *
- * Its children are not rows in the blocks array — they are plain
- * `{ block_type, content }` objects buried in `content.column_blocks` — so a
- * walker that only looked at the top-level list would under-report almost every
- * page ever built in this CMS.
- *
- * A section in slider mode renders its slides *instead of* its columns, and
- * this mirrors that: walking both would count copy from a stale column set the
- * visitor cannot reach, and inflate the word count with it.
- */
-function collectSectionBlock(
-  content: Record<string, unknown>,
-  draft: PageDocumentDraft,
-  depth: number
-): void {
-  const slides = content['slides'];
-
-  if (content['slider'] === true && Array.isArray(slides) && slides.length > 0) {
-    for (const slide of slides) {
-      const record = readRecord(slide);
-      if (record !== null) {
-        collectColumnBlocks(record['column_blocks'], draft, depth);
-      }
-    }
-
-    return;
-  }
-
-  collectColumnBlocks(content['column_blocks'], draft, depth);
-}
-
-/** Dispatches one block row onto the reader that knows where its text lives. */
-function collectBlock(value: unknown, draft: PageDocumentDraft, depth: number): void {
-  if (depth > MAX_BLOCK_NESTING_DEPTH) {
-    return;
-  }
-
-  const block = readRecord(value);
-  if (block === null) {
-    return;
-  }
-
-  const blockType = typeof block['block_type'] === 'string' ? block['block_type'] : '';
-  const content = readRecord(block['content']);
-  if (content === null) {
-    return;
-  }
-
-  switch (blockType) {
-    case 'text': {
-      // `html_content` holds either an HTML string or a JSON-stringified Tiptap
-      // document depending on when and where the block was authored.
-      // `buildSeoDocument` already distinguishes the two and reads both, so
-      // this delegates rather than growing a second parser that could disagree
-      // with the one the block-level panel uses. `text_content` is the shape
-      // some older rows still carry.
-      const source = content['html_content'] ?? content['text_content'];
-      appendDocument(draft, buildSeoDocument(source));
-
-      return;
-    }
-
-    case 'heading':
-      collectHeadingBlock(content, draft);
-
-      return;
-
-    case 'image':
-      collectImageBlock(content, draft);
-
-      return;
-
-    case 'button':
-      collectButtonBlock(content, draft);
-
-      return;
-
-    case 'testimonial':
-      collectTestimonialBlock(content, draft);
-
-      return;
-
-    // The registry calls this `video_embed`; `video` is accepted alongside it
-    // because that is the name the block is known by in the UI and in prompts,
-    // and both carry the same optional `title`.
-    case 'video':
-    case 'video_embed':
-      appendText(draft, readText(content['title']));
-
-      return;
-
-    case 'section':
-      collectSectionBlock(content, draft, depth);
-
-      return;
-
-    // `hero` is not in the current registry, but rows created before sections
-    // absorbed it still exist in live databases and still render, so their copy
-    // still counts. They keep both shapes: slides and a plain column set.
-    case 'hero': {
-      const slides = content['slides'];
-      if (Array.isArray(slides)) {
-        for (const slide of slides) {
-          const record = readRecord(slide);
-          if (record !== null) {
-            collectColumnBlocks(record['column_blocks'], draft, depth);
-          }
-        }
-      }
-
-      collectColumnBlocks(content['column_blocks'], draft, depth);
-
-      return;
-    }
-
-    default:
-      // Every other block type — posts grids, forms, the commerce blocks, and
-      // any custom block whose content is defined by whoever built it — renders
-      // from data this walker cannot read, so it contributes nothing rather
-      // than contributing a guess.
-      return;
-  }
-}
-
-/**
- * Builds one `SeoDocument` from a page's or post's block list.
- *
- * `blocks` is deliberately typed `unknown`: it comes from form state, from a
- * draft row, or straight from Supabase as `Json`, and pretending at the
- * signature that it is already an array of well-formed rows would only push the
- * validation somewhere that has less context to do it in.
- */
-export function buildPageSeoDocument(blocks: unknown): SeoDocument {
-  if (!Array.isArray(blocks) || blocks.length === 0) {
-    return emptySeoDocument();
-  }
-
-  const draft = createDraft();
-  for (const block of blocks) {
-    collectBlock(block, draft, 0);
-  }
-
-  return {
-    headings: draft.headings,
-    images: draft.images,
-    links: draft.links,
-    text: draft.textParts.join(' '),
-    words: draft.words,
-  };
-}
+export {
+  buildPageSeoDocument,
+  type BuildPageSeoDocumentOptions,
+} from '@nextblock-cms/utils/seo';

package/templates/nextblock-template/lib/seo/robots-txt.ts

@@ -346,7 +346,7 @@ function toCustomRule(group: CustomRuleGroup): RobotsRule {
       const values = group.other[key];
       other[key] = values.length === 1 ? values[0] : values;
     }
-    rule.other = other;
+    (rule as any).other = other;
   }
 
   return rule;
@@ -476,9 +476,10 @@ export function renderRobotsMetadata(metadata: MetadataRoute.Robots): string {
       content += `Crawl-delay: ${rule.crawlDelay}\n`;
     }
 
-    if (rule.other) {
-      for (const key of Object.keys(rule.other)) {
-        const value = rule.other[key];
+    const ruleOther = (rule as any).other;
+    if (ruleOther) {
+      for (const key of Object.keys(ruleOther)) {
+        const value = ruleOther[key];
         if (value === null || value === undefined) {
           continue;
         }