@vectoriox/iox-ui 4.33.1 → 4.35.0

package/src/seo-core/seo.model.ts

@@ -0,0 +1,175 @@
+/**
+ * The canonical shape of a page's SEO metadata, plus the flat tag list both renderers emit.
+ *
+ * ⚠️ This file is the ONLY declaration of that shape. Before it existed, `iox-cms` stored
+ * `seo.og.title` while the SSR engine read a flat `seo.ogTitle`, so no Open Graph tag had ever been
+ * emitted, and `iox-cms-client` carried a third, hand-copied variant of the same schema. See
+ * iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+
+/** Open Graph subset we author and emit. */
+export interface SeoOg {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+
+/** Twitter-card subset. Emitted only when `card` is set — see `seoToTags`. */
+export interface SeoTwitter {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+}
+
+/** Sitemap participation for this page. Consumed by the sitemap route (plan phase 3). */
+export interface SeoSitemap {
+    include?: boolean;
+    priority?: number;
+    changeFreq?: string;
+}
+
+/**
+ * A page's stored SEO metadata, normalized.
+ *
+ * `keywords` has no authoring field — search engines have ignored the tag for over a decade — but
+ * it is read and emitted when a document already carries one, because the engine used to read it.
+ */
+export interface SeoDoc {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    canonicalUrl?: string;
+    robots?: string;
+    og?: SeoOg;
+    twitter?: SeoTwitter;
+    structuredData?: unknown;
+    sitemap?: SeoSitemap;
+}
+
+/**
+ * A binding on an SEO field. Structurally the resolvable part of an `IoxBinding` — `source` picks an
+ * entry in the page's resolved data (`$current` on a template page), `path` walks into it, `pipes`
+ * are the render-time transforms. Typed loosely because the pipe catalog lives in the main
+ * `@vectoriox/iox-ui` entry point, which this framework-free one must not import.
+ */
+export interface SeoBinding {
+    source: string;
+    path?: string;
+    pipes?: readonly unknown[];
+}
+
+/**
+ * One SEO field as stored once it carries more than a typed string.
+ *
+ * The ladder is `override` → `binding` → auto; `auto: false` opts that field out of the automatic
+ * value, leaving it genuinely empty. A bare `string` in a stored document means `{ override }`, so
+ * nothing has to be migrated.
+ */
+export interface SeoFieldValue {
+    override?: string;
+    binding?: SeoBinding;
+    auto?: false;
+}
+
+/** A stored SEO document, before resolution: any text field may be a plain string or a value object. */
+export type SeoRawDoc = Record<string, unknown>;
+
+/**
+ * The text fields that can carry a binding, as dotted paths into the document.
+ *
+ * One list, used by the resolver and (phase 2) by the panel that draws the bind affordance — so a
+ * field can never be bindable in the UI and ignored at render time. `robots`, `sitemap.*` and
+ * `structuredData` are deliberately absent: they are pick-lists and blobs, not prose.
+ */
+export const SEO_BINDABLE_FIELDS: readonly string[] = [
+    'title',
+    'description',
+    'canonicalUrl',
+    'og.title',
+    'og.description',
+    'og.image',
+    'twitter.title',
+    'twitter.description',
+    'twitter.image',
+];
+
+/** Where an automatic value comes from when a field has neither an override nor a binding. */
+export type SeoAutoSource = 'contentTitle' | 'contentDescription' | 'contentImage' | 'pageUrl';
+
+/**
+ * The bottom rung of the ladder, as a table rather than a chain of ifs.
+ *
+ * Deliberately short. `og:title` and `twitter:*` are NOT here — `seoToTags` already falls back to
+ * the page title for them, and materialising a copy of a value we did not author would only make
+ * later drift harder to see.
+ */
+export const SEO_AUTO_SOURCES: ReadonlyArray<{ field: string; source: SeoAutoSource }> = [
+    { field: 'title', source: 'contentTitle' },
+    { field: 'description', source: 'contentDescription' },
+    { field: 'og.image', source: 'contentImage' },
+    { field: 'canonicalUrl', source: 'pageUrl' },
+];
+
+/** `<title>`. */
+export interface SeoTitleTag {
+    kind: 'title';
+    content: string;
+}
+
+/**
+ * A `<meta>` tag. `attr` says which attribute identifies it — Open Graph is addressed by
+ * `property`, everything else by `name`. Both renderers need that distinction to update rather
+ * than duplicate a tag.
+ */
+export interface SeoMetaTag {
+    kind: 'meta';
+    attr: 'name' | 'property';
+    key: string;
+    content: string;
+}
+
+/** A `<link>`, currently only `rel="canonical"`. */
+export interface SeoLinkTag {
+    kind: 'link';
+    rel: string;
+    href: string;
+}
+
+export type SeoTag = SeoTitleTag | SeoMetaTag | SeoLinkTag;
+
+/** Context that lets `seoToTags` fill gaps without reaching for the DOM or a data source. */
+export interface SeoTagContext {
+    /** Used as `<title>` when the document has none — usually the page name. */
+    fallbackTitle?: string;
+}
+
+/** Recommended maximum before search results truncate the title. */
+export const SEO_TITLE_MAX = 60;
+
+/** Recommended maximum before search results truncate the description. */
+export const SEO_DESCRIPTION_MAX = 160;
+
+export const SEO_ROBOTS_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+    { label: 'Index, Follow', value: 'index, follow' },
+    { label: 'Index, No Follow', value: 'index, nofollow' },
+    { label: 'No Index, Follow', value: 'noindex, follow' },
+    { label: 'No Index, No Follow', value: 'noindex, nofollow' },
+];
+
+export const SEO_TWITTER_CARD_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+    { label: 'Summary', value: 'summary' },
+    { label: 'Summary Large Image', value: 'summary_large_image' },
+    { label: 'App', value: 'app' },
+    { label: 'Player', value: 'player' },
+];
+
+export const SEO_CHANGE_FREQ_OPTIONS: ReadonlyArray<{ label: string; value: string }> = [
+    { label: 'Always', value: 'always' },
+    { label: 'Hourly', value: 'hourly' },
+    { label: 'Daily', value: 'daily' },
+    { label: 'Weekly', value: 'weekly' },
+    { label: 'Monthly', value: 'monthly' },
+    { label: 'Yearly', value: 'yearly' },
+    { label: 'Never', value: 'never' },
+];

package/src/seo-core/tags.ts

@@ -0,0 +1,57 @@
+import { SeoDoc, SeoTag, SeoTagContext } from './seo.model';
+import { normalizeSeoDoc } from './normalize';
+
+/**
+ * Turn a page's SEO document into the flat list of head tags to emit.
+ *
+ * Both renderers call this, so a page cannot describe itself differently to a crawler than the
+ * builder previews. The order is fixed and part of the contract: title, description, keywords,
+ * canonical, Open Graph, Twitter, robots.
+ *
+ * Fallbacks are deliberately shallow — `og:title` reuses the page title, `twitter:*` reuses the
+ * Open Graph values — because a social scraper that finds no `og:title` falls back to `<title>`
+ * itself, and duplicating a value we did not author only makes the drift harder to see. The
+ * "derive from the page content" half of the ladder (first h1, first paragraph, first image) is
+ * `resolveSeo`, which runs BEFORE this and hands its output in as a filled-in `SeoDoc`.
+ */
+export function seoToTags(seo: SeoDoc | unknown, ctx: SeoTagContext = {}): SeoTag[] {
+    const doc = normalizeSeoDoc(seo);
+    const tags: SeoTag[] = [];
+
+    const title = doc.title ?? trimmed(ctx.fallbackTitle);
+    if (title) tags.push({ kind: 'title', content: title });
+    if (doc.description) tags.push({ kind: 'meta', attr: 'name', key: 'description', content: doc.description });
+    if (doc.keywords) tags.push({ kind: 'meta', attr: 'name', key: 'keywords', content: doc.keywords });
+    if (doc.canonicalUrl) tags.push({ kind: 'link', rel: 'canonical', href: doc.canonicalUrl });
+
+    // Open Graph. `og:url` reuses the canonical URL, which is what it means.
+    const ogTitle = doc.og?.title ?? title;
+    const ogDescription = doc.og?.description ?? doc.description;
+    if (ogTitle) tags.push({ kind: 'meta', attr: 'property', key: 'og:title', content: ogTitle });
+    if (ogDescription) tags.push({ kind: 'meta', attr: 'property', key: 'og:description', content: ogDescription });
+    if (doc.og?.image) tags.push({ kind: 'meta', attr: 'property', key: 'og:image', content: doc.og.image });
+    if (doc.canonicalUrl) tags.push({ kind: 'meta', attr: 'property', key: 'og:url', content: doc.canonicalUrl });
+
+    // Twitter. Emitted ONLY when a card type is chosen: without `twitter:card` the other tags are
+    // ignored anyway, so writing them would be noise that looks like configuration.
+    if (doc.twitter?.card) {
+        tags.push({ kind: 'meta', attr: 'name', key: 'twitter:card', content: doc.twitter.card });
+        const twitterTitle = doc.twitter.title ?? ogTitle;
+        const twitterDescription = doc.twitter.description ?? ogDescription;
+        const twitterImage = doc.twitter.image ?? doc.og?.image;
+        if (twitterTitle) tags.push({ kind: 'meta', attr: 'name', key: 'twitter:title', content: twitterTitle });
+        if (twitterDescription) {
+            tags.push({ kind: 'meta', attr: 'name', key: 'twitter:description', content: twitterDescription });
+        }
+        if (twitterImage) tags.push({ kind: 'meta', attr: 'name', key: 'twitter:image', content: twitterImage });
+    }
+
+    if (doc.robots) tags.push({ kind: 'meta', attr: 'name', key: 'robots', content: doc.robots });
+
+    return tags;
+}
+
+function trimmed(value: string | undefined): string | undefined {
+    const out = value?.trim();
+    return out?.length ? out : undefined;
+}