@reblu/site-next 1.17.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @reblu/site-next
 
+## 1.18.0
+
+### Minor Changes
+
+- e4dff25: New `@reblu/site-next/seo` subpath (REB-871) — the one page-title rule, shared with the Reblu SITE API. `resolveSeoTitle({ seoTitle, title, sectionLabel }, { template, siteName })`: a non-empty entity SEO title is used as-is (never suffixed); otherwise the tenant template (`Config.seoTitleTemplate`, default `%s | {siteName}`) is applied exactly once to the display title or the list route's section label, and the brand is never duplicated. `buildMetadata({ seo, config, ... })` returns Next `Metadata` with an absolute title (a root-layout `title.template` can no longer append the brand twice). Also exports `DEFAULT_SEO_TITLE_TEMPLATE`, `validateSeoTitleTemplate` and `resolveSeoTitleTemplate`. Dependency-free, no `'use client'`.
+
+### Patch Changes
+
+- Updated dependencies [e4dff25]
+  - @reblu/site-contracts@1.11.0
+
 ## 1.17.0
 
 ### Minor Changes

package/README.md

@@ -642,6 +642,46 @@ whitespace-only value for any key the same as `undefined` — it always falls
 back to that key's default rather than rendering empty. There is no need to
 `?.trim()` a value before passing it.
 
+## Page titles — `buildMetadata` (REB-871)
+
+`@reblu/site-next/seo` (dependency-free, no `'use client'`) holds the one
+page-title rule the Reblu SITE API also applies server-side:
+
+- an entity SEO title (`seoTitle` / `metaTitle`) that is set is the **whole**
+  title — used as-is, the site name is never appended;
+- otherwise the tenant template (`config.seoTitleTemplate`, default
+  `%s | {siteName}`) is applied **once** to the display title — or to the
+  section label on a list/index route;
+- the brand is never duplicated.
+
+Detail endpoints already return `seo.title` resolved, so a detail route is a
+drop-in:
+
+```ts
+// app/servicios/[slug]/page.tsx
+import type { Metadata } from 'next'
+import { buildMetadata } from '@reblu/site-next/seo'
+
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const { slug } = await params
+  const [page, config] = await Promise.all([reblu.pages.bySlug(slug), reblu.config.get()])
+  return buildMetadata({ seo: page.seo, title: page.title, seoTitle: page.seoTitle, config })
+}
+
+// app/blog/page.tsx — list/index route: the template with the section label
+export async function generateMetadata(): Promise<Metadata> {
+  return buildMetadata({ sectionLabel: 'Blog', config: await reblu.config.get() })
+}
+```
+
+`buildMetadata` emits `title: { absolute }`, so a `title.template` in the root
+layout can never append the brand a second time — drop any hand-written
+`` `${title} · Brand` `` from your routes. Passing `title`/`seoTitle` alongside
+`seo` keeps the route correct against an older API that does not send `seo`
+yet. Need the string only? `resolveSeoTitle({ seoTitle, title, sectionLabel },
+{ template: config.seoTitleTemplate, siteName: config.siteName })`.
+Description/Open Graph are intentionally minimal here (REB-823 extends them).
+
 ## Structured data (JSON-LD)
 
 `@reblu/site-next/json-ld` (REB-622, server-only, dependency-free) renders one

package/dist/seo.cjs

@@ -0,0 +1,101 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/seo.ts
+var seo_exports = {};
+__export(seo_exports, {
+  DEFAULT_SEO_TITLE_TEMPLATE: () => DEFAULT_SEO_TITLE_TEMPLATE,
+  SEO_SITE_NAME_PLACEHOLDER: () => SEO_SITE_NAME_PLACEHOLDER,
+  SEO_TITLE_PLACEHOLDER: () => SEO_TITLE_PLACEHOLDER,
+  SEO_TITLE_RECOMMENDED_MAX_LENGTH: () => SEO_TITLE_RECOMMENDED_MAX_LENGTH,
+  SEO_TITLE_TEMPLATE_MAX_LENGTH: () => SEO_TITLE_TEMPLATE_MAX_LENGTH,
+  buildMetadata: () => buildMetadata,
+  resolveSeoTitle: () => resolveSeoTitle,
+  resolveSeoTitleTemplate: () => resolveSeoTitleTemplate,
+  validateSeoTitleTemplate: () => validateSeoTitleTemplate
+});
+module.exports = __toCommonJS(seo_exports);
+var DEFAULT_SEO_TITLE_TEMPLATE = "%s | {siteName}";
+var SEO_TITLE_PLACEHOLDER = "%s";
+var SEO_SITE_NAME_PLACEHOLDER = "{siteName}";
+var SEO_TITLE_TEMPLATE_MAX_LENGTH = 60;
+var SEO_TITLE_RECOMMENDED_MAX_LENGTH = 60;
+function validateSeoTitleTemplate(template) {
+  const occurrences = template.split(SEO_TITLE_PLACEHOLDER).length - 1;
+  if (occurrences === 0) return "missing_placeholder";
+  if (occurrences > 1) return "multiple_placeholders";
+  if (template.length > SEO_TITLE_TEMPLATE_MAX_LENGTH) return "too_long";
+  return null;
+}
+function resolveSeoTitleTemplate(template) {
+  const trimmed = template?.trim() ?? "";
+  if (trimmed && validateSeoTitleTemplate(trimmed) === null) return trimmed;
+  return DEFAULT_SEO_TITLE_TEMPLATE;
+}
+var WORD_CHAR_AT_END = /[\p{L}\p{N}\p{M}]$/u;
+var WORD_CHAR_AT_START = /^[\p{L}\p{N}\p{M}]/u;
+function containsPhrase(text, phrase) {
+  const haystack = text.toLocaleLowerCase();
+  const needle = phrase.toLocaleLowerCase();
+  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1)) {
+    const before = haystack.slice(0, i);
+    const after = haystack.slice(i + needle.length);
+    if (!WORD_CHAR_AT_END.test(before) && !WORD_CHAR_AT_START.test(after)) return true;
+  }
+  return false;
+}
+function resolveSeoTitle(input, context) {
+  const asIs = input.seoTitle?.trim();
+  if (asIs) return asIs;
+  const siteName = context.siteName?.trim() ?? "";
+  const display = input.title?.trim() || input.sectionLabel?.trim() || "";
+  if (!display) return siteName;
+  const template = resolveSeoTitleTemplate(context.template);
+  if (template.includes(SEO_SITE_NAME_PLACEHOLDER)) {
+    if (!siteName) return display;
+    if (containsPhrase(display, siteName)) return display;
+  }
+  const [before = "", after = ""] = template.split(SEO_TITLE_PLACEHOLDER);
+  const brand = (part) => part.split(SEO_SITE_NAME_PLACEHOLDER).join(siteName);
+  return `${brand(before)}${display}${brand(after)}`.trim();
+}
+function buildMetadata(input) {
+  const title = input.seo?.title?.trim() || resolveSeoTitle(input, {
+    template: input.config.seoTitleTemplate,
+    siteName: input.config.siteName
+  });
+  const metadata = {};
+  if (title) metadata.title = { absolute: title };
+  const description = input.description?.trim();
+  if (description) metadata.description = description;
+  return metadata;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_SEO_TITLE_TEMPLATE,
+  SEO_SITE_NAME_PLACEHOLDER,
+  SEO_TITLE_PLACEHOLDER,
+  SEO_TITLE_RECOMMENDED_MAX_LENGTH,
+  SEO_TITLE_TEMPLATE_MAX_LENGTH,
+  buildMetadata,
+  resolveSeoTitle,
+  resolveSeoTitleTemplate,
+  validateSeoTitleTemplate
+});
+//# sourceMappingURL=seo.cjs.map

package/dist/seo.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/seo.ts"],"sourcesContent":["/**\n * `@reblu/site-next/seo` — the ONE page-title rule (REB-871), shared by the\n * Reblu SITE API (which serves `seo.title` already resolved on every detail\n * endpoint) and by SITEs (index/list routes, or an older API without `seo`).\n *\n * The rule, in order:\n *   1. An entity SEO title (`seoTitle` / `metaTitle`) that is non-empty after\n *      trimming is the WHOLE title — used as-is, never suffixed.\n *   2. Otherwise the tenant template (`SiteSettings.seoTitleTemplate`, default\n *      `%s | {siteName}`) is applied ONCE to the display title — the entity\n *      title on a detail route, the section label on a list/index route.\n *   3. The brand is never duplicated: a display title that already names the\n *      site is used alone, and a site with no name drops the brand part.\n *\n * Own tsup entry with ZERO runtime dependencies (no React, no `next` — only\n * the `Metadata` TYPE) so base-api can import it server-side and a SITE can\n * call it from `generateMetadata` with no RSC-boundary cost. It must never\n * carry `'use client'`.\n */\nimport type { Metadata } from 'next'\n\n/** Applied when the tenant never chose a template (`seoTitleTemplate` NULL). */\nexport const DEFAULT_SEO_TITLE_TEMPLATE = '%s | {siteName}'\n/** The display-title placeholder — must appear exactly once in a template. */\nexport const SEO_TITLE_PLACEHOLDER = '%s'\n/** Optional brand placeholder, replaced by `siteName`. */\nexport const SEO_SITE_NAME_PLACEHOLDER = '{siteName}'\n/** Upper bound for a stored template (write-side validation). */\nexport const SEO_TITLE_TEMPLATE_MAX_LENGTH = 60\n/** Recommended length of a full page title in search results. */\nexport const SEO_TITLE_RECOMMENDED_MAX_LENGTH = 60\n\nexport type SeoTitleTemplateIssue = 'missing_placeholder' | 'multiple_placeholders' | 'too_long'\n\n/** `null` when `template` is a valid title template, otherwise why it is not. */\nexport function validateSeoTitleTemplate(template: string): SeoTitleTemplateIssue | null {\n  const occurrences = template.split(SEO_TITLE_PLACEHOLDER).length - 1\n  if (occurrences === 0) return 'missing_placeholder'\n  if (occurrences > 1) return 'multiple_placeholders'\n  if (template.length > SEO_TITLE_TEMPLATE_MAX_LENGTH) return 'too_long'\n  return null\n}\n\n/**\n * The template to apply: the stored one (trimmed) when valid, otherwise the\n * default. An invalid stored value (hand-edited row) degrades to the default\n * instead of producing a broken title.\n */\nexport function resolveSeoTitleTemplate(template: string | null | undefined): string {\n  const trimmed = template?.trim() ?? ''\n  if (trimmed && validateSeoTitleTemplate(trimmed) === null) return trimmed\n  return DEFAULT_SEO_TITLE_TEMPLATE\n}\n\nexport interface SeoTitleInput {\n  /** Entity SEO title (`seoTitle` on pages, `metaTitle` on posts/products/courses). */\n  seoTitle?: string | null\n  /** Display title of the entity (detail routes). */\n  title?: string | null\n  /** Label of a list/index route (e.g. \"Blog\"), used when there is no entity title. */\n  sectionLabel?: string | null\n}\n\nexport interface SeoTitleContext {\n  /** `Config.seoTitleTemplate` — null/undefined/invalid → the default. */\n  template?: string | null\n  /** `Config.siteName`. */\n  siteName?: string | null\n}\n\n/** A letter, digit or combining mark — accents included (Unicode-aware). */\nconst WORD_CHAR_AT_END = /[\\p{L}\\p{N}\\p{M}]$/u\nconst WORD_CHAR_AT_START = /^[\\p{L}\\p{N}\\p{M}]/u\n\n/**\n * Whether `phrase` occurs in `text` as a whole word/phrase (case-insensitive):\n * the brand \"Arte\" is in \"Galería Arte\" but not in \"Cartera\" or \"Artesanía\".\n */\nfunction containsPhrase(text: string, phrase: string): boolean {\n  const haystack = text.toLocaleLowerCase()\n  const needle = phrase.toLocaleLowerCase()\n  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1)) {\n    const before = haystack.slice(0, i)\n    const after = haystack.slice(i + needle.length)\n    if (!WORD_CHAR_AT_END.test(before) && !WORD_CHAR_AT_START.test(after)) return true\n  }\n  return false\n}\n\nexport function resolveSeoTitle(input: SeoTitleInput, context: SeoTitleContext): string {\n  const asIs = input.seoTitle?.trim()\n  if (asIs) return asIs\n\n  const siteName = context.siteName?.trim() ?? ''\n  const display = input.title?.trim() || input.sectionLabel?.trim() || ''\n  if (!display) return siteName\n\n  const template = resolveSeoTitleTemplate(context.template)\n  if (template.includes(SEO_SITE_NAME_PLACEHOLDER)) {\n    if (!siteName) return display\n    if (containsPhrase(display, siteName)) return display\n  }\n\n  // Split on the placeholder BEFORE inserting the display title, so the title\n  // itself is never scanned for placeholders (applied exactly once) and no\n  // `String.replace` special pattern (`$&`, `$1`) can reach it.\n  const [before = '', after = ''] = template.split(SEO_TITLE_PLACEHOLDER)\n  const brand = (part: string) => part.split(SEO_SITE_NAME_PLACEHOLDER).join(siteName)\n  return `${brand(before)}${display}${brand(after)}`.trim()\n}\n\nexport interface BuildMetadataInput extends SeoTitleInput {\n  /** The detail endpoint's `seo` block — its `title` is already resolved. */\n  seo?: { title?: string | null } | null\n  /** `GET /api/site/config` (or the subset needed here). */\n  config: { siteName?: string | null; seoTitleTemplate?: string | null }\n  description?: string | null\n}\n\n/**\n * Next `Metadata` for a SITE route. The title is emitted as `absolute` so a\n * root-layout `title.template` can never append the brand a second time.\n * Description/Open Graph are deliberately minimal here (REB-823 extends them).\n */\nexport function buildMetadata(input: BuildMetadataInput): Metadata {\n  const title =\n    input.seo?.title?.trim() ||\n    resolveSeoTitle(input, {\n      template: input.config.seoTitleTemplate,\n      siteName: input.config.siteName,\n    })\n\n  const metadata: Metadata = {}\n  if (title) metadata.title = { absolute: title }\n  const description = input.description?.trim()\n  if (description) metadata.description = description\n  return metadata\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsBO,IAAM,6BAA6B;AAEnC,IAAM,wBAAwB;AAE9B,IAAM,4BAA4B;AAElC,IAAM,gCAAgC;AAEtC,IAAM,mCAAmC;AAKzC,SAAS,yBAAyB,UAAgD;AACvF,QAAM,cAAc,SAAS,MAAM,qBAAqB,EAAE,SAAS;AACnE,MAAI,gBAAgB,EAAG,QAAO;AAC9B,MAAI,cAAc,EAAG,QAAO;AAC5B,MAAI,SAAS,SAAS,8BAA+B,QAAO;AAC5D,SAAO;AACT;AAOO,SAAS,wBAAwB,UAA6C;AACnF,QAAM,UAAU,UAAU,KAAK,KAAK;AACpC,MAAI,WAAW,yBAAyB,OAAO,MAAM,KAAM,QAAO;AAClE,SAAO;AACT;AAmBA,IAAM,mBAAmB;AACzB,IAAM,qBAAqB;AAM3B,SAAS,eAAe,MAAc,QAAyB;AAC7D,QAAM,WAAW,KAAK,kBAAkB;AACxC,QAAM,SAAS,OAAO,kBAAkB;AACxC,WAAS,IAAI,SAAS,QAAQ,MAAM,GAAG,MAAM,IAAI,IAAI,SAAS,QAAQ,QAAQ,IAAI,CAAC,GAAG;AACpF,UAAM,SAAS,SAAS,MAAM,GAAG,CAAC;AAClC,UAAM,QAAQ,SAAS,MAAM,IAAI,OAAO,MAAM;AAC9C,QAAI,CAAC,iBAAiB,KAAK,MAAM,KAAK,CAAC,mBAAmB,KAAK,KAAK,EAAG,QAAO;AAAA,EAChF;AACA,SAAO;AACT;AAEO,SAAS,gBAAgB,OAAsB,SAAkC;AACtF,QAAM,OAAO,MAAM,UAAU,KAAK;AAClC,MAAI,KAAM,QAAO;AAEjB,QAAM,WAAW,QAAQ,UAAU,KAAK,KAAK;AAC7C,QAAM,UAAU,MAAM,OAAO,KAAK,KAAK,MAAM,cAAc,KAAK,KAAK;AACrE,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,WAAW,wBAAwB,QAAQ,QAAQ;AACzD,MAAI,SAAS,SAAS,yBAAyB,GAAG;AAChD,QAAI,CAAC,SAAU,QAAO;AACtB,QAAI,eAAe,SAAS,QAAQ,EAAG,QAAO;AAAA,EAChD;AAKA,QAAM,CAAC,SAAS,IAAI,QAAQ,EAAE,IAAI,SAAS,MAAM,qBAAqB;AACtE,QAAM,QAAQ,CAAC,SAAiB,KAAK,MAAM,yBAAyB,EAAE,KAAK,QAAQ;AACnF,SAAO,GAAG,MAAM,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,KAAK;AAC1D;AAeO,SAAS,cAAc,OAAqC;AACjE,QAAM,QACJ,MAAM,KAAK,OAAO,KAAK,KACvB,gBAAgB,OAAO;AAAA,IACrB,UAAU,MAAM,OAAO;AAAA,IACvB,UAAU,MAAM,OAAO;AAAA,EACzB,CAAC;AAEH,QAAM,WAAqB,CAAC;AAC5B,MAAI,MAAO,UAAS,QAAQ,EAAE,UAAU,MAAM;AAC9C,QAAM,cAAc,MAAM,aAAa,KAAK;AAC5C,MAAI,YAAa,UAAS,cAAc;AACxC,SAAO;AACT;","names":[]}

package/dist/seo.d.cts

@@ -0,0 +1,76 @@
+import { Metadata } from 'next';
+
+/**
+ * `@reblu/site-next/seo` — the ONE page-title rule (REB-871), shared by the
+ * Reblu SITE API (which serves `seo.title` already resolved on every detail
+ * endpoint) and by SITEs (index/list routes, or an older API without `seo`).
+ *
+ * The rule, in order:
+ *   1. An entity SEO title (`seoTitle` / `metaTitle`) that is non-empty after
+ *      trimming is the WHOLE title — used as-is, never suffixed.
+ *   2. Otherwise the tenant template (`SiteSettings.seoTitleTemplate`, default
+ *      `%s | {siteName}`) is applied ONCE to the display title — the entity
+ *      title on a detail route, the section label on a list/index route.
+ *   3. The brand is never duplicated: a display title that already names the
+ *      site is used alone, and a site with no name drops the brand part.
+ *
+ * Own tsup entry with ZERO runtime dependencies (no React, no `next` — only
+ * the `Metadata` TYPE) so base-api can import it server-side and a SITE can
+ * call it from `generateMetadata` with no RSC-boundary cost. It must never
+ * carry `'use client'`.
+ */
+
+/** Applied when the tenant never chose a template (`seoTitleTemplate` NULL). */
+declare const DEFAULT_SEO_TITLE_TEMPLATE = "%s | {siteName}";
+/** The display-title placeholder — must appear exactly once in a template. */
+declare const SEO_TITLE_PLACEHOLDER = "%s";
+/** Optional brand placeholder, replaced by `siteName`. */
+declare const SEO_SITE_NAME_PLACEHOLDER = "{siteName}";
+/** Upper bound for a stored template (write-side validation). */
+declare const SEO_TITLE_TEMPLATE_MAX_LENGTH = 60;
+/** Recommended length of a full page title in search results. */
+declare const SEO_TITLE_RECOMMENDED_MAX_LENGTH = 60;
+type SeoTitleTemplateIssue = 'missing_placeholder' | 'multiple_placeholders' | 'too_long';
+/** `null` when `template` is a valid title template, otherwise why it is not. */
+declare function validateSeoTitleTemplate(template: string): SeoTitleTemplateIssue | null;
+/**
+ * The template to apply: the stored one (trimmed) when valid, otherwise the
+ * default. An invalid stored value (hand-edited row) degrades to the default
+ * instead of producing a broken title.
+ */
+declare function resolveSeoTitleTemplate(template: string | null | undefined): string;
+interface SeoTitleInput {
+    /** Entity SEO title (`seoTitle` on pages, `metaTitle` on posts/products/courses). */
+    seoTitle?: string | null;
+    /** Display title of the entity (detail routes). */
+    title?: string | null;
+    /** Label of a list/index route (e.g. "Blog"), used when there is no entity title. */
+    sectionLabel?: string | null;
+}
+interface SeoTitleContext {
+    /** `Config.seoTitleTemplate` — null/undefined/invalid → the default. */
+    template?: string | null;
+    /** `Config.siteName`. */
+    siteName?: string | null;
+}
+declare function resolveSeoTitle(input: SeoTitleInput, context: SeoTitleContext): string;
+interface BuildMetadataInput extends SeoTitleInput {
+    /** The detail endpoint's `seo` block — its `title` is already resolved. */
+    seo?: {
+        title?: string | null;
+    } | null;
+    /** `GET /api/site/config` (or the subset needed here). */
+    config: {
+        siteName?: string | null;
+        seoTitleTemplate?: string | null;
+    };
+    description?: string | null;
+}
+/**
+ * Next `Metadata` for a SITE route. The title is emitted as `absolute` so a
+ * root-layout `title.template` can never append the brand a second time.
+ * Description/Open Graph are deliberately minimal here (REB-823 extends them).
+ */
+declare function buildMetadata(input: BuildMetadataInput): Metadata;
+
+export { type BuildMetadataInput, DEFAULT_SEO_TITLE_TEMPLATE, SEO_SITE_NAME_PLACEHOLDER, SEO_TITLE_PLACEHOLDER, SEO_TITLE_RECOMMENDED_MAX_LENGTH, SEO_TITLE_TEMPLATE_MAX_LENGTH, type SeoTitleContext, type SeoTitleInput, type SeoTitleTemplateIssue, buildMetadata, resolveSeoTitle, resolveSeoTitleTemplate, validateSeoTitleTemplate };

package/dist/seo.d.ts

@@ -0,0 +1,76 @@
+import { Metadata } from 'next';
+
+/**
+ * `@reblu/site-next/seo` — the ONE page-title rule (REB-871), shared by the
+ * Reblu SITE API (which serves `seo.title` already resolved on every detail
+ * endpoint) and by SITEs (index/list routes, or an older API without `seo`).
+ *
+ * The rule, in order:
+ *   1. An entity SEO title (`seoTitle` / `metaTitle`) that is non-empty after
+ *      trimming is the WHOLE title — used as-is, never suffixed.
+ *   2. Otherwise the tenant template (`SiteSettings.seoTitleTemplate`, default
+ *      `%s | {siteName}`) is applied ONCE to the display title — the entity
+ *      title on a detail route, the section label on a list/index route.
+ *   3. The brand is never duplicated: a display title that already names the
+ *      site is used alone, and a site with no name drops the brand part.
+ *
+ * Own tsup entry with ZERO runtime dependencies (no React, no `next` — only
+ * the `Metadata` TYPE) so base-api can import it server-side and a SITE can
+ * call it from `generateMetadata` with no RSC-boundary cost. It must never
+ * carry `'use client'`.
+ */
+
+/** Applied when the tenant never chose a template (`seoTitleTemplate` NULL). */
+declare const DEFAULT_SEO_TITLE_TEMPLATE = "%s | {siteName}";
+/** The display-title placeholder — must appear exactly once in a template. */
+declare const SEO_TITLE_PLACEHOLDER = "%s";
+/** Optional brand placeholder, replaced by `siteName`. */
+declare const SEO_SITE_NAME_PLACEHOLDER = "{siteName}";
+/** Upper bound for a stored template (write-side validation). */
+declare const SEO_TITLE_TEMPLATE_MAX_LENGTH = 60;
+/** Recommended length of a full page title in search results. */
+declare const SEO_TITLE_RECOMMENDED_MAX_LENGTH = 60;
+type SeoTitleTemplateIssue = 'missing_placeholder' | 'multiple_placeholders' | 'too_long';
+/** `null` when `template` is a valid title template, otherwise why it is not. */
+declare function validateSeoTitleTemplate(template: string): SeoTitleTemplateIssue | null;
+/**
+ * The template to apply: the stored one (trimmed) when valid, otherwise the
+ * default. An invalid stored value (hand-edited row) degrades to the default
+ * instead of producing a broken title.
+ */
+declare function resolveSeoTitleTemplate(template: string | null | undefined): string;
+interface SeoTitleInput {
+    /** Entity SEO title (`seoTitle` on pages, `metaTitle` on posts/products/courses). */
+    seoTitle?: string | null;
+    /** Display title of the entity (detail routes). */
+    title?: string | null;
+    /** Label of a list/index route (e.g. "Blog"), used when there is no entity title. */
+    sectionLabel?: string | null;
+}
+interface SeoTitleContext {
+    /** `Config.seoTitleTemplate` — null/undefined/invalid → the default. */
+    template?: string | null;
+    /** `Config.siteName`. */
+    siteName?: string | null;
+}
+declare function resolveSeoTitle(input: SeoTitleInput, context: SeoTitleContext): string;
+interface BuildMetadataInput extends SeoTitleInput {
+    /** The detail endpoint's `seo` block — its `title` is already resolved. */
+    seo?: {
+        title?: string | null;
+    } | null;
+    /** `GET /api/site/config` (or the subset needed here). */
+    config: {
+        siteName?: string | null;
+        seoTitleTemplate?: string | null;
+    };
+    description?: string | null;
+}
+/**
+ * Next `Metadata` for a SITE route. The title is emitted as `absolute` so a
+ * root-layout `title.template` can never append the brand a second time.
+ * Description/Open Graph are deliberately minimal here (REB-823 extends them).
+ */
+declare function buildMetadata(input: BuildMetadataInput): Metadata;
+
+export { type BuildMetadataInput, DEFAULT_SEO_TITLE_TEMPLATE, SEO_SITE_NAME_PLACEHOLDER, SEO_TITLE_PLACEHOLDER, SEO_TITLE_RECOMMENDED_MAX_LENGTH, SEO_TITLE_TEMPLATE_MAX_LENGTH, type SeoTitleContext, type SeoTitleInput, type SeoTitleTemplateIssue, buildMetadata, resolveSeoTitle, resolveSeoTitleTemplate, validateSeoTitleTemplate };

package/dist/seo.js

@@ -0,0 +1,68 @@
+// src/seo.ts
+var DEFAULT_SEO_TITLE_TEMPLATE = "%s | {siteName}";
+var SEO_TITLE_PLACEHOLDER = "%s";
+var SEO_SITE_NAME_PLACEHOLDER = "{siteName}";
+var SEO_TITLE_TEMPLATE_MAX_LENGTH = 60;
+var SEO_TITLE_RECOMMENDED_MAX_LENGTH = 60;
+function validateSeoTitleTemplate(template) {
+  const occurrences = template.split(SEO_TITLE_PLACEHOLDER).length - 1;
+  if (occurrences === 0) return "missing_placeholder";
+  if (occurrences > 1) return "multiple_placeholders";
+  if (template.length > SEO_TITLE_TEMPLATE_MAX_LENGTH) return "too_long";
+  return null;
+}
+function resolveSeoTitleTemplate(template) {
+  const trimmed = template?.trim() ?? "";
+  if (trimmed && validateSeoTitleTemplate(trimmed) === null) return trimmed;
+  return DEFAULT_SEO_TITLE_TEMPLATE;
+}
+var WORD_CHAR_AT_END = /[\p{L}\p{N}\p{M}]$/u;
+var WORD_CHAR_AT_START = /^[\p{L}\p{N}\p{M}]/u;
+function containsPhrase(text, phrase) {
+  const haystack = text.toLocaleLowerCase();
+  const needle = phrase.toLocaleLowerCase();
+  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1)) {
+    const before = haystack.slice(0, i);
+    const after = haystack.slice(i + needle.length);
+    if (!WORD_CHAR_AT_END.test(before) && !WORD_CHAR_AT_START.test(after)) return true;
+  }
+  return false;
+}
+function resolveSeoTitle(input, context) {
+  const asIs = input.seoTitle?.trim();
+  if (asIs) return asIs;
+  const siteName = context.siteName?.trim() ?? "";
+  const display = input.title?.trim() || input.sectionLabel?.trim() || "";
+  if (!display) return siteName;
+  const template = resolveSeoTitleTemplate(context.template);
+  if (template.includes(SEO_SITE_NAME_PLACEHOLDER)) {
+    if (!siteName) return display;
+    if (containsPhrase(display, siteName)) return display;
+  }
+  const [before = "", after = ""] = template.split(SEO_TITLE_PLACEHOLDER);
+  const brand = (part) => part.split(SEO_SITE_NAME_PLACEHOLDER).join(siteName);
+  return `${brand(before)}${display}${brand(after)}`.trim();
+}
+function buildMetadata(input) {
+  const title = input.seo?.title?.trim() || resolveSeoTitle(input, {
+    template: input.config.seoTitleTemplate,
+    siteName: input.config.siteName
+  });
+  const metadata = {};
+  if (title) metadata.title = { absolute: title };
+  const description = input.description?.trim();
+  if (description) metadata.description = description;
+  return metadata;
+}
+export {
+  DEFAULT_SEO_TITLE_TEMPLATE,
+  SEO_SITE_NAME_PLACEHOLDER,
+  SEO_TITLE_PLACEHOLDER,
+  SEO_TITLE_RECOMMENDED_MAX_LENGTH,
+  SEO_TITLE_TEMPLATE_MAX_LENGTH,
+  buildMetadata,
+  resolveSeoTitle,
+  resolveSeoTitleTemplate,
+  validateSeoTitleTemplate
+};
+//# sourceMappingURL=seo.js.map

package/dist/seo.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/seo.ts"],"sourcesContent":["/**\n * `@reblu/site-next/seo` — the ONE page-title rule (REB-871), shared by the\n * Reblu SITE API (which serves `seo.title` already resolved on every detail\n * endpoint) and by SITEs (index/list routes, or an older API without `seo`).\n *\n * The rule, in order:\n *   1. An entity SEO title (`seoTitle` / `metaTitle`) that is non-empty after\n *      trimming is the WHOLE title — used as-is, never suffixed.\n *   2. Otherwise the tenant template (`SiteSettings.seoTitleTemplate`, default\n *      `%s | {siteName}`) is applied ONCE to the display title — the entity\n *      title on a detail route, the section label on a list/index route.\n *   3. The brand is never duplicated: a display title that already names the\n *      site is used alone, and a site with no name drops the brand part.\n *\n * Own tsup entry with ZERO runtime dependencies (no React, no `next` — only\n * the `Metadata` TYPE) so base-api can import it server-side and a SITE can\n * call it from `generateMetadata` with no RSC-boundary cost. It must never\n * carry `'use client'`.\n */\nimport type { Metadata } from 'next'\n\n/** Applied when the tenant never chose a template (`seoTitleTemplate` NULL). */\nexport const DEFAULT_SEO_TITLE_TEMPLATE = '%s | {siteName}'\n/** The display-title placeholder — must appear exactly once in a template. */\nexport const SEO_TITLE_PLACEHOLDER = '%s'\n/** Optional brand placeholder, replaced by `siteName`. */\nexport const SEO_SITE_NAME_PLACEHOLDER = '{siteName}'\n/** Upper bound for a stored template (write-side validation). */\nexport const SEO_TITLE_TEMPLATE_MAX_LENGTH = 60\n/** Recommended length of a full page title in search results. */\nexport const SEO_TITLE_RECOMMENDED_MAX_LENGTH = 60\n\nexport type SeoTitleTemplateIssue = 'missing_placeholder' | 'multiple_placeholders' | 'too_long'\n\n/** `null` when `template` is a valid title template, otherwise why it is not. */\nexport function validateSeoTitleTemplate(template: string): SeoTitleTemplateIssue | null {\n  const occurrences = template.split(SEO_TITLE_PLACEHOLDER).length - 1\n  if (occurrences === 0) return 'missing_placeholder'\n  if (occurrences > 1) return 'multiple_placeholders'\n  if (template.length > SEO_TITLE_TEMPLATE_MAX_LENGTH) return 'too_long'\n  return null\n}\n\n/**\n * The template to apply: the stored one (trimmed) when valid, otherwise the\n * default. An invalid stored value (hand-edited row) degrades to the default\n * instead of producing a broken title.\n */\nexport function resolveSeoTitleTemplate(template: string | null | undefined): string {\n  const trimmed = template?.trim() ?? ''\n  if (trimmed && validateSeoTitleTemplate(trimmed) === null) return trimmed\n  return DEFAULT_SEO_TITLE_TEMPLATE\n}\n\nexport interface SeoTitleInput {\n  /** Entity SEO title (`seoTitle` on pages, `metaTitle` on posts/products/courses). */\n  seoTitle?: string | null\n  /** Display title of the entity (detail routes). */\n  title?: string | null\n  /** Label of a list/index route (e.g. \"Blog\"), used when there is no entity title. */\n  sectionLabel?: string | null\n}\n\nexport interface SeoTitleContext {\n  /** `Config.seoTitleTemplate` — null/undefined/invalid → the default. */\n  template?: string | null\n  /** `Config.siteName`. */\n  siteName?: string | null\n}\n\n/** A letter, digit or combining mark — accents included (Unicode-aware). */\nconst WORD_CHAR_AT_END = /[\\p{L}\\p{N}\\p{M}]$/u\nconst WORD_CHAR_AT_START = /^[\\p{L}\\p{N}\\p{M}]/u\n\n/**\n * Whether `phrase` occurs in `text` as a whole word/phrase (case-insensitive):\n * the brand \"Arte\" is in \"Galería Arte\" but not in \"Cartera\" or \"Artesanía\".\n */\nfunction containsPhrase(text: string, phrase: string): boolean {\n  const haystack = text.toLocaleLowerCase()\n  const needle = phrase.toLocaleLowerCase()\n  for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1)) {\n    const before = haystack.slice(0, i)\n    const after = haystack.slice(i + needle.length)\n    if (!WORD_CHAR_AT_END.test(before) && !WORD_CHAR_AT_START.test(after)) return true\n  }\n  return false\n}\n\nexport function resolveSeoTitle(input: SeoTitleInput, context: SeoTitleContext): string {\n  const asIs = input.seoTitle?.trim()\n  if (asIs) return asIs\n\n  const siteName = context.siteName?.trim() ?? ''\n  const display = input.title?.trim() || input.sectionLabel?.trim() || ''\n  if (!display) return siteName\n\n  const template = resolveSeoTitleTemplate(context.template)\n  if (template.includes(SEO_SITE_NAME_PLACEHOLDER)) {\n    if (!siteName) return display\n    if (containsPhrase(display, siteName)) return display\n  }\n\n  // Split on the placeholder BEFORE inserting the display title, so the title\n  // itself is never scanned for placeholders (applied exactly once) and no\n  // `String.replace` special pattern (`$&`, `$1`) can reach it.\n  const [before = '', after = ''] = template.split(SEO_TITLE_PLACEHOLDER)\n  const brand = (part: string) => part.split(SEO_SITE_NAME_PLACEHOLDER).join(siteName)\n  return `${brand(before)}${display}${brand(after)}`.trim()\n}\n\nexport interface BuildMetadataInput extends SeoTitleInput {\n  /** The detail endpoint's `seo` block — its `title` is already resolved. */\n  seo?: { title?: string | null } | null\n  /** `GET /api/site/config` (or the subset needed here). */\n  config: { siteName?: string | null; seoTitleTemplate?: string | null }\n  description?: string | null\n}\n\n/**\n * Next `Metadata` for a SITE route. The title is emitted as `absolute` so a\n * root-layout `title.template` can never append the brand a second time.\n * Description/Open Graph are deliberately minimal here (REB-823 extends them).\n */\nexport function buildMetadata(input: BuildMetadataInput): Metadata {\n  const title =\n    input.seo?.title?.trim() ||\n    resolveSeoTitle(input, {\n      template: input.config.seoTitleTemplate,\n      siteName: input.config.siteName,\n    })\n\n  const metadata: Metadata = {}\n  if (title) metadata.title = { absolute: title }\n  const description = input.description?.trim()\n  if (description) metadata.description = description\n  return metadata\n}\n"],"mappings":";AAsBO,IAAM,6BAA6B;AAEnC,IAAM,wBAAwB;AAE9B,IAAM,4BAA4B;AAElC,IAAM,gCAAgC;AAEtC,IAAM,mCAAmC;AAKzC,SAAS,yBAAyB,UAAgD;AACvF,QAAM,cAAc,SAAS,MAAM,qBAAqB,EAAE,SAAS;AACnE,MAAI,gBAAgB,EAAG,QAAO;AAC9B,MAAI,cAAc,EAAG,QAAO;AAC5B,MAAI,SAAS,SAAS,8BAA+B,QAAO;AAC5D,SAAO;AACT;AAOO,SAAS,wBAAwB,UAA6C;AACnF,QAAM,UAAU,UAAU,KAAK,KAAK;AACpC,MAAI,WAAW,yBAAyB,OAAO,MAAM,KAAM,QAAO;AAClE,SAAO;AACT;AAmBA,IAAM,mBAAmB;AACzB,IAAM,qBAAqB;AAM3B,SAAS,eAAe,MAAc,QAAyB;AAC7D,QAAM,WAAW,KAAK,kBAAkB;AACxC,QAAM,SAAS,OAAO,kBAAkB;AACxC,WAAS,IAAI,SAAS,QAAQ,MAAM,GAAG,MAAM,IAAI,IAAI,SAAS,QAAQ,QAAQ,IAAI,CAAC,GAAG;AACpF,UAAM,SAAS,SAAS,MAAM,GAAG,CAAC;AAClC,UAAM,QAAQ,SAAS,MAAM,IAAI,OAAO,MAAM;AAC9C,QAAI,CAAC,iBAAiB,KAAK,MAAM,KAAK,CAAC,mBAAmB,KAAK,KAAK,EAAG,QAAO;AAAA,EAChF;AACA,SAAO;AACT;AAEO,SAAS,gBAAgB,OAAsB,SAAkC;AACtF,QAAM,OAAO,MAAM,UAAU,KAAK;AAClC,MAAI,KAAM,QAAO;AAEjB,QAAM,WAAW,QAAQ,UAAU,KAAK,KAAK;AAC7C,QAAM,UAAU,MAAM,OAAO,KAAK,KAAK,MAAM,cAAc,KAAK,KAAK;AACrE,MAAI,CAAC,QAAS,QAAO;AAErB,QAAM,WAAW,wBAAwB,QAAQ,QAAQ;AACzD,MAAI,SAAS,SAAS,yBAAyB,GAAG;AAChD,QAAI,CAAC,SAAU,QAAO;AACtB,QAAI,eAAe,SAAS,QAAQ,EAAG,QAAO;AAAA,EAChD;AAKA,QAAM,CAAC,SAAS,IAAI,QAAQ,EAAE,IAAI,SAAS,MAAM,qBAAqB;AACtE,QAAM,QAAQ,CAAC,SAAiB,KAAK,MAAM,yBAAyB,EAAE,KAAK,QAAQ;AACnF,SAAO,GAAG,MAAM,MAAM,CAAC,GAAG,OAAO,GAAG,MAAM,KAAK,CAAC,GAAG,KAAK;AAC1D;AAeO,SAAS,cAAc,OAAqC;AACjE,QAAM,QACJ,MAAM,KAAK,OAAO,KAAK,KACvB,gBAAgB,OAAO;AAAA,IACrB,UAAU,MAAM,OAAO;AAAA,IACvB,UAAU,MAAM,OAAO;AAAA,EACzB,CAAC;AAEH,QAAM,WAAqB,CAAC;AAC5B,MAAI,MAAO,UAAS,QAAQ,EAAE,UAAU,MAAM;AAC9C,QAAM,cAAc,MAAM,aAAa,KAAK;AAC5C,MAAI,YAAa,UAAS,cAAc;AACxC,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reblu/site-next",
-  "version": "1.17.0",
+  "version": "1.18.0",
   "description": "Next.js RSC glue for Reblu SITEs — cache + CTA + auth server/client components.",
   "license": "Apache-2.0",
   "author": "Reblu — Adolfo Unturbe",
@@ -221,6 +221,16 @@
         "types": "./dist/opening-hours.d.cts",
         "default": "./dist/opening-hours.cjs"
       }
+    },
+    "./seo": {
+      "import": {
+        "types": "./dist/seo.d.ts",
+        "default": "./dist/seo.js"
+      },
+      "require": {
+        "types": "./dist/seo.d.cts",
+        "default": "./dist/seo.cjs"
+      }
     }
   },
   "publishConfig": {
@@ -240,9 +250,9 @@
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.15",
     "zustand": "^5.0.9",
-    "@reblu/site-client": "^5.3.1",
-    "@reblu/site-contracts": "^1.6.1",
-    "@reblu/site-ui": "^0.7.0"
+    "@reblu/site-contracts": "^1.11.0",
+    "@reblu/site-ui": "^0.7.0",
+    "@reblu/site-client": "^5.4.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",