create-nextblock 0.15.10 → 0.16.2

package/templates/nextblock-template/lib/posts/readTime.ts

@@ -1,60 +1,60 @@
-import type { Database } from '@nextblock-cms/db';
-
-type BlockRow = Database['public']['Tables']['blocks']['Row'];
-
-const WORDS_PER_MINUTE = 200;
-
-function extractPlainTextFromHtml(html: string) {
-  return html
-    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
-    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
-    .replace(/<[^>]+>/g, ' ')
-    .replace(/&nbsp;/g, ' ')
-    .replace(/&amp;/g, '&')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-function countWords(text: string) {
-  if (!text) {
-    return 0;
-  }
-
-  return text.split(' ').length;
-}
-
-export function estimateReadTimeMinutesFromHtmlFragments(htmlFragments: string[]) {
-  const words = htmlFragments.reduce((total, html) => {
-    const plainText = extractPlainTextFromHtml(html);
-    return total + countWords(plainText);
-  }, 0);
-
-  return Math.max(1, Math.round(words / WORDS_PER_MINUTE));
-}
-
-export function estimateReadTimeMinutesFromBlocks(
-  blocks: Array<Pick<BlockRow, 'block_type' | 'content'>> | undefined
-) {
-  if (!blocks || blocks.length === 0) {
-    return 1;
-  }
-
-  const htmlFragments = blocks.reduce<string[]>((fragments, block) => {
-    if (block.block_type !== 'text') {
-      return fragments;
-    }
-
-    const html =
-      typeof block.content === 'object' && block.content && 'html_content' in block.content
-        ? String((block.content as { html_content?: string }).html_content ?? '')
-        : '';
-
-    if (html) {
-      fragments.push(html);
-    }
-
-    return fragments;
-  }, []);
-
-  return estimateReadTimeMinutesFromHtmlFragments(htmlFragments);
-}
+import type { Database } from '@nextblock-cms/db';
+
+type BlockRow = Database['public']['Tables']['blocks']['Row'];
+
+const WORDS_PER_MINUTE = 200;
+
+function extractPlainTextFromHtml(html: string) {
+  return html
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function countWords(text: string) {
+  if (!text) {
+    return 0;
+  }
+
+  return text.split(' ').length;
+}
+
+export function estimateReadTimeMinutesFromHtmlFragments(htmlFragments: string[]) {
+  const words = htmlFragments.reduce((total, html) => {
+    const plainText = extractPlainTextFromHtml(html);
+    return total + countWords(plainText);
+  }, 0);
+
+  return Math.max(1, Math.round(words / WORDS_PER_MINUTE));
+}
+
+export function estimateReadTimeMinutesFromBlocks(
+  blocks: Array<Pick<BlockRow, 'block_type' | 'content'>> | undefined
+) {
+  if (!blocks || blocks.length === 0) {
+    return 1;
+  }
+
+  const htmlFragments = blocks.reduce<string[]>((fragments, block) => {
+    if (block.block_type !== 'text') {
+      return fragments;
+    }
+
+    const html =
+      typeof block.content === 'object' && block.content && 'html_content' in block.content
+        ? String((block.content as { html_content?: string }).html_content ?? '')
+        : '';
+
+    if (html) {
+      fragments.push(html);
+    }
+
+    return fragments;
+  }, []);
+
+  return estimateReadTimeMinutesFromHtmlFragments(htmlFragments);
+}

package/templates/nextblock-template/lib/publishing/viewUrl.ts

@@ -1,26 +1,26 @@
-/**
- * Build a link to the `/api/view` entry point used by the CMS "Preview" and
- * "View Live" buttons.
- *
- * Always pass the content's own language. The public site resolves language from
- * a cookie, not the URL, so a link without `lang` renders in whatever language
- * the editor happens to be browsing in — which is how opening a French page
- * landed you on the English one. See `app/api/view/route.ts`.
- */
-export function buildViewUrl(options: {
-  /** Root-relative public path, e.g. "/about" or "/article/hello". */
-  path: string;
-  /** The content row's language code, e.g. "fr". */
-  languageCode?: string | null;
-  /** True to enter Live Draft Mode (preview unpublished content). */
-  draft?: boolean;
-}): string {
-  const params = new URLSearchParams({ path: options.path });
-  if (options.languageCode) {
-    params.set("lang", options.languageCode);
-  }
-  if (options.draft) {
-    params.set("draft", "1");
-  }
-  return `/api/view?${params.toString()}`;
-}
+/**
+ * Build a link to the `/api/view` entry point used by the CMS "Preview" and
+ * "View Live" buttons.
+ *
+ * Always pass the content's own language. The public site resolves language from
+ * a cookie, not the URL, so a link without `lang` renders in whatever language
+ * the editor happens to be browsing in — which is how opening a French page
+ * landed you on the English one. See `app/api/view/route.ts`.
+ */
+export function buildViewUrl(options: {
+  /** Root-relative public path, e.g. "/about" or "/article/hello". */
+  path: string;
+  /** The content row's language code, e.g. "fr". */
+  languageCode?: string | null;
+  /** True to enter Live Draft Mode (preview unpublished content). */
+  draft?: boolean;
+}): string {
+  const params = new URLSearchParams({ path: options.path });
+  if (options.languageCode) {
+    params.set("lang", options.languageCode);
+  }
+  if (options.draft) {
+    params.set("draft", "1");
+  }
+  return `/api/view?${params.toString()}`;
+}

package/templates/nextblock-template/lib/search/types.ts

@@ -1,27 +1,27 @@
-export type GlobalSearchResultType = 'page' | 'post' | 'product';
-
-export type GlobalSearchFilter = GlobalSearchResultType | 'all';
-
-export interface GlobalSearchResult {
-  id: string;
-  type: GlobalSearchResultType;
-  title: string;
-  description: string | null;
-  snippet: string | null;
-  href: string;
-  locale: string | null;
-  imageUrl: string | null;
-  score: number;
-  meta: {
-    label?: string | null;
-    sku?: string | null;
-    publishedAt?: string | null;
-    updatedAt?: string | null;
-  };
-}
-
-export interface GlobalSearchResponse {
-  query: string;
-  results: GlobalSearchResult[];
-  counts: Record<GlobalSearchResultType | 'all', number>;
-}
+export type GlobalSearchResultType = 'page' | 'post' | 'product';
+
+export type GlobalSearchFilter = GlobalSearchResultType | 'all';
+
+export interface GlobalSearchResult {
+  id: string;
+  type: GlobalSearchResultType;
+  title: string;
+  description: string | null;
+  snippet: string | null;
+  href: string;
+  locale: string | null;
+  imageUrl: string | null;
+  score: number;
+  meta: {
+    label?: string | null;
+    sku?: string | null;
+    publishedAt?: string | null;
+    updatedAt?: string | null;
+  };
+}
+
+export interface GlobalSearchResponse {
+  query: string;
+  results: GlobalSearchResult[];
+  counts: Record<GlobalSearchResultType | 'all', number>;
+}

package/templates/nextblock-template/lib/seo/alt-text-write-back.test.ts

@@ -0,0 +1,154 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  altTextImageIdentity,
+  resolveAltTextWriteBack,
+  STALE_ALT_TEXT_MESSAGE,
+} from './alt-text-write-back';
+
+type ImageContent = {
+  alt_text: string | null;
+  caption: string | null;
+  external_url?: string | null;
+  media_id: string | null;
+  object_key: string | null;
+};
+
+function content(overrides: Partial<ImageContent> = {}): ImageContent {
+  return {
+    alt_text: '',
+    caption: '',
+    external_url: null,
+    media_id: 'media-1',
+    object_key: 'uploads/harvest.jpg',
+    ...overrides,
+  };
+}
+
+describe('altTextImageIdentity', () => {
+  it('identifies a stored image by its object key', () => {
+    expect(altTextImageIdentity(content())).toBe('stored:uploads/harvest.jpg');
+  });
+
+  it('falls back to the editor selection while content has not echoed it back yet', () => {
+    expect(altTextImageIdentity(content({ object_key: null }), 'uploads/just-picked.jpg')).toBe(
+      'stored:uploads/just-picked.jpg'
+    );
+  });
+
+  it('prefers the external URL, because that is the image the editor renders and sends', () => {
+    expect(
+      altTextImageIdentity(
+        content({ external_url: 'https://images.example.com/a.jpg', object_key: 'uploads/old.jpg' }),
+        'uploads/older.jpg'
+      )
+    ).toBe('external:https://images.example.com/a.jpg');
+  });
+
+  it('returns an empty identity when there is no image at all', () => {
+    expect(altTextImageIdentity(content({ media_id: null, object_key: null }))).toBe('');
+    expect(altTextImageIdentity(content({ object_key: '   ' }))).toBe('');
+  });
+
+  it('never confuses an external URL with an object key of the same text', () => {
+    expect(altTextImageIdentity({ external_url: 'x', object_key: null })).not.toBe(
+      altTextImageIdentity({ external_url: null, object_key: 'x' })
+    );
+  });
+});
+
+describe('resolveAltTextWriteBack', () => {
+  it('writes the description into the CURRENT content, not the copy captured at click time', () => {
+    // The caption was typed while the vision call was in flight. Merging into the captured
+    // copy would silently revert it.
+    const current = content({ caption: 'Typed while generating' });
+
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: current,
+        currentIdentity: 'stored:uploads/harvest.jpg',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: 'uploads/harvest.jpg',
+      })
+    ).toEqual({
+      alt_text: 'A field of chamomile at dawn.',
+      caption: 'Typed while generating',
+      external_url: null,
+      media_id: 'media-1',
+      object_key: 'uploads/harvest.jpg',
+    });
+  });
+
+  it('writes object_key from the editor selection, matching the typed-alt-text shape exactly', () => {
+    const result = resolveAltTextWriteBack({
+      capturedIdentity: 'stored:uploads/just-picked.jpg',
+      currentContent: content({ object_key: null }),
+      currentIdentity: 'stored:uploads/just-picked.jpg',
+      generatedAltText: 'Chamomile.',
+      objectKey: 'uploads/just-picked.jpg',
+    });
+
+    expect(result?.object_key).toBe('uploads/just-picked.jpg');
+  });
+
+  it('drops the response when the image was replaced mid-flight', () => {
+    // The regression this whole module exists for: alt text describing image A must never
+    // be attached to image B.
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: content({ object_key: 'uploads/packaging.jpg' }),
+        currentIdentity: 'stored:uploads/packaging.jpg',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: 'uploads/packaging.jpg',
+      })
+    ).toBeNull();
+  });
+
+  it('drops the response when the image was removed mid-flight, so nothing is resurrected', () => {
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: content({ media_id: null, object_key: null }),
+        currentIdentity: '',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: null,
+      })
+    ).toBeNull();
+  });
+
+  it('drops the response when a stored image was swapped for an external URL', () => {
+    const current = content({
+      external_url: 'https://images.example.com/new.jpg',
+      media_id: null,
+      object_key: null,
+    });
+
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: 'stored:uploads/harvest.jpg',
+        currentContent: current,
+        currentIdentity: altTextImageIdentity(current),
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: null,
+      })
+    ).toBeNull();
+  });
+
+  it('refuses to treat two empty identities as a match', () => {
+    expect(
+      resolveAltTextWriteBack({
+        capturedIdentity: '',
+        currentContent: content({ media_id: null, object_key: null }),
+        currentIdentity: '',
+        generatedAltText: 'A field of chamomile at dawn.',
+        objectKey: null,
+      })
+    ).toBeNull();
+  });
+
+  it('offers an explanation that tells the operator the description was discarded', () => {
+    expect(STALE_ALT_TEXT_MESSAGE).toContain('discarded');
+  });
+});

package/templates/nextblock-template/lib/seo/alt-text-write-back.ts

@@ -0,0 +1,109 @@
+/**
+ * The pure core of the "Generate with AI" alt-text write-back in `ImageBlockEditor`.
+ *
+ * A vision call takes seconds, and the block editor stays fully interactive while one is
+ * in flight: the author can remove the image, pick a different one from the library, or
+ * paste an external URL before the description ever arrives. The original handler assumed
+ * the block it started on would still be the block it finished on — it captured `content`
+ * at click time and wrote `{ ...capturedContent, alt_text: generated }` back on completion
+ * — and that assumption is wrong in exactly the cases that matter. Writing the captured
+ * copy back resurrects an image the author had deleted, or pairs a freshly chosen image
+ * with a description of the previous one. The second failure is worse than having no alt
+ * text at all: it is confidently wrong, and the screen-reader user it exists for has no
+ * way to detect that it describes a different picture.
+ *
+ * The fix is to capture the image's IDENTITY rather than a snapshot of the content, and to
+ * discard the response when the block no longer holds that image. This decision lives here
+ * rather than inline in the component because the component cannot be unit-tested in this
+ * workspace — there is no DOM environment — and a rule about what may overwrite an
+ * accessibility field deserves a test.
+ */
+
+/**
+ * The part of an image block's content that says which image is loaded.
+ *
+ * Deliberately structural and snake_case: these are the JSONB attribute names the block
+ * actually stores, so a caller passes its content object straight in without translating.
+ */
+export interface AltTextImageSource {
+  external_url?: string | null;
+  object_key?: string | null;
+}
+
+/**
+ * Shown when a generated description is thrown away because the image moved on. It is
+ * phrased as a fact plus the next step rather than as a failure, because nothing failed —
+ * the model answered, the answer is simply about an image that is no longer here.
+ */
+export const STALE_ALT_TEXT_MESSAGE =
+  'The image changed while Cortex AI was describing it, so that description was discarded. Generate again for the current image.';
+
+/**
+ * A stable string naming the image a block is currently showing, or `''` for no image.
+ *
+ * The external URL wins over the stored object key because that is the order the editor
+ * itself renders and sends in: a block with an `external_url` shows the external image
+ * regardless of any stale `object_key` left beside it. `fallbackObjectKey` mirrors the
+ * editor's `content.object_key || selectedMediaObjectKey` display rule, which exists
+ * because a just-picked image lives in component state for a beat before the parent
+ * echoes it back through `content`.
+ *
+ * The `external:` / `stored:` prefixes keep the two namespaces from ever colliding, so a
+ * URL that happens to equal an object key cannot be mistaken for the same image.
+ */
+export function altTextImageIdentity(
+  source: AltTextImageSource,
+  fallbackObjectKey?: string | null
+): string {
+  const externalUrl = source.external_url?.trim();
+  if (externalUrl) {
+    return `external:${externalUrl}`;
+  }
+
+  const objectKey = (source.object_key || fallbackObjectKey || '').trim();
+  if (objectKey) {
+    return `stored:${objectKey}`;
+  }
+
+  return '';
+}
+
+export interface AltTextWriteBackParams<TContent extends AltTextImageSource> {
+  /** The identity taken at click time, i.e. the image that was actually sent to the model. */
+  capturedIdentity: string;
+  /** The block's content as of right now — never the copy captured at click time. */
+  currentContent: TContent;
+  /** The identity of the image the block holds right now. */
+  currentIdentity: string;
+  generatedAltText: string;
+  /** The editor's `selectedMediaObjectKey`, written through unchanged (see below). */
+  objectKey: string | null | undefined;
+}
+
+/**
+ * Decide what — if anything — the generated description should write back.
+ *
+ * Returns `null` when the response must be dropped: either the image has been replaced or
+ * removed since the request went out, or there was no identifiable image to begin with (an
+ * empty captured identity, which the disabled button should already prevent, is treated as
+ * a mismatch rather than as a match against another empty).
+ *
+ * When it does write, it merges into the CURRENT content and reproduces the exact shape
+ * `handleAltTextChange` uses — the same key set, including `object_key` taken from the
+ * editor's selection state. Making the AI path indistinguishable from typing is what
+ * guarantees the value lands in the block's JSONB attributes through the one save path,
+ * instead of creating a second write shape to keep in sync forever.
+ */
+export function resolveAltTextWriteBack<TContent extends AltTextImageSource>(
+  params: AltTextWriteBackParams<TContent>
+): (TContent & { alt_text: string; object_key: string | null | undefined }) | null {
+  if (!params.capturedIdentity || params.capturedIdentity !== params.currentIdentity) {
+    return null;
+  }
+
+  return {
+    ...params.currentContent,
+    alt_text: params.generatedAltText,
+    object_key: params.objectKey,
+  };
+}

package/templates/nextblock-template/lib/seo/block-content.ts

@@ -0,0 +1,123 @@
+import { extractIntroExcerptFromBlocks, stripHtmlToText } from '../../app/lib/seo';
+
+/**
+ * Flatten a page's or post's block rows into plain prose for the metadata generator.
+ *
+ * `POST /api/ai/seo/metadata` wants the *body copy* — it has to read the page to write a
+ * title and description about it. What the CMS holds instead is a tree of block rows
+ * whose text is scattered across differently-named fields and nested one or two levels
+ * deep inside layout containers. This walks that tree once and returns the readable text.
+ *
+ * It deliberately reuses `stripHtmlToText` from `app/lib/seo.ts` rather than growing a
+ * fourth HTML stripper in this repo. That module was checked before importing it here:
+ * its only import is `import type { Metadata } from 'next'`, a type-only import that is
+ * erased at compile time, so nothing server-only is pulled into the client bundle even
+ * though `app/lib/site-settings.ts` — a different module — imports it under 'server-only'.
+ *
+ * The walk covers the containers that actually nest content today:
+ *  - `section` blocks hold their children in `content.column_blocks`,
+ *  - `hero` blocks hold theirs in `content.slides`,
+ * matching how `collectIntroTextCandidates` in `app/lib/seo.ts` traverses the same shapes.
+ * Anything unrecognized is skipped rather than guessed at, because feeding the model
+ * stray JSON keys produces worse metadata than feeding it less prose.
+ */
+function collectBlockText(value: unknown, collected: string[]): void {
+  if (!value) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectBlockText(item, collected));
+    return;
+  }
+
+  if (typeof value !== 'object') {
+    return;
+  }
+
+  const block = value as {
+    block_type?: string;
+    content?: Record<string, unknown>;
+  };
+
+  if (block.block_type === 'section' || block.block_type === 'hero') {
+    collectBlockText(block.content?.column_blocks, collected);
+    collectBlockText(block.content?.slides, collected);
+    return;
+  }
+
+  if (block.block_type === 'heading') {
+    const headingText = block.content?.text_content;
+    if (typeof headingText === 'string' && headingText.trim()) {
+      collected.push(stripHtmlToText(headingText));
+    }
+    return;
+  }
+
+  if (block.block_type === 'text') {
+    const htmlContent = block.content?.html_content;
+    const textContent = block.content?.text_content;
+    const candidate =
+      typeof htmlContent === 'string'
+        ? stripHtmlToText(htmlContent)
+        : typeof textContent === 'string'
+          ? stripHtmlToText(textContent)
+          : '';
+
+    if (candidate) {
+      collected.push(candidate);
+    }
+  }
+}
+
+/**
+ * Maximum prose we send to the metadata route.
+ *
+ * A meta title and description summarize the *top* of a page; the model does not need
+ * the whole of a 5,000-word article to write 160 characters, and shipping the whole of
+ * it costs tokens and latency on every click of the button. Cutting at a sentence-ish
+ * boundary keeps the tail from ending mid-word, which reads to the model as a typo.
+ */
+const MAX_CONTENT_CHARACTERS = 6000;
+
+export function extractPlainTextFromBlocks(blocks: unknown): string {
+  const collected: string[] = [];
+  collectBlockText(blocks, collected);
+
+  const joined = collected.join('\n\n').trim();
+  if (joined.length <= MAX_CONTENT_CHARACTERS) {
+    return joined;
+  }
+
+  const truncated = joined.slice(0, MAX_CONTENT_CHARACTERS);
+  const lastBoundary = Math.max(truncated.lastIndexOf('. '), truncated.lastIndexOf('\n'));
+  return (lastBoundary > MAX_CONTENT_CHARACTERS / 2
+    ? truncated.slice(0, lastBoundary + 1)
+    : truncated
+  ).trim();
+}
+
+/**
+ * Best available prose for the metadata call, in descending order of usefulness.
+ *
+ * A brand-new page has no blocks yet, and an operator clicking "Generate" on an empty
+ * page should still get something better than a disabled button — the title plus any
+ * editorial summary they have typed is a thin but genuine brief. `fallbacks` is where
+ * the caller passes those: a post's excerpt and subtitle, or a page's title.
+ */
+export function buildSeoContentForGeneration(
+  blocks: unknown,
+  ...fallbacks: Array<string | null | undefined>
+): string {
+  const fromBlocks = extractPlainTextFromBlocks(blocks);
+  if (fromBlocks) {
+    return fromBlocks;
+  }
+
+  const intro = extractIntroExcerptFromBlocks(blocks);
+  const parts = [intro, ...fallbacks]
+    .map((part) => (typeof part === 'string' ? stripHtmlToText(part) : ''))
+    .filter(Boolean);
+
+  return parts.join('\n\n').trim();
+}