@vectoriox/iox-ui 4.33.0 → 4.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.33.0",
+  "version": "4.34.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -22,6 +22,10 @@
     "./forms-core": {
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"
+    },
+    "./seo-core": {
+      "types": "./seo-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-seo-core.mjs"
     }
   },
   "sideEffects": false

package/seo-core/index.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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. */
+interface SeoOg {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+/** Twitter-card subset. Emitted only when `card` is set — see `seoToTags`. */
+interface SeoTwitter {
+    card?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+}
+/** Sitemap participation for this page. Consumed by the sitemap route (plan phase 3). */
+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.
+ */
+interface SeoDoc {
+    title?: string;
+    description?: string;
+    keywords?: string;
+    canonicalUrl?: string;
+    robots?: string;
+    og?: SeoOg;
+    twitter?: SeoTwitter;
+    structuredData?: unknown;
+    sitemap?: SeoSitemap;
+}
+/** `<title>`. */
+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.
+ */
+interface SeoMetaTag {
+    kind: 'meta';
+    attr: 'name' | 'property';
+    key: string;
+    content: string;
+}
+/** A `<link>`, currently only `rel="canonical"`. */
+interface SeoLinkTag {
+    kind: 'link';
+    rel: string;
+    href: string;
+}
+type SeoTag = SeoTitleTag | SeoMetaTag | SeoLinkTag;
+/** Context that lets `seoToTags` fill gaps without reaching for the DOM or a data source. */
+interface SeoTagContext {
+    /** Used as `<title>` when the document has none — usually the page name. */
+    fallbackTitle?: string;
+}
+/** Recommended maximum before search results truncate the title. */
+declare const SEO_TITLE_MAX = 60;
+/** Recommended maximum before search results truncate the description. */
+declare const SEO_DESCRIPTION_MAX = 160;
+declare const SEO_ROBOTS_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: string;
+}>;
+declare const SEO_TWITTER_CARD_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: string;
+}>;
+declare const SEO_CHANGE_FREQ_OPTIONS: ReadonlyArray<{
+    label: string;
+    value: string;
+}>;
+
+/**
+ * Coerce whatever a page document happens to hold into a `SeoDoc`.
+ *
+ * Every consumer calls this before reading `seo`, because four shapes are in the wild:
+ *  • the current nested shape (`og.title`);
+ *  • the flat shape the SSR engine used to read (`ogTitle`) — never actually written, but a
+ *    document hand-edited against the old engine code could carry it;
+ *  • `""` for "not set", which must not become an empty `<meta>`;
+ *  • `{ override: '…' }`, the per-field value object that plan phase 2 introduces — tolerated here
+ *    so the ladder can land without a second normalizer.
+ *
+ * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.
+ */
+declare function normalizeSeoDoc(raw: unknown): SeoDoc;
+
+/**
+ * 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`.
+ */
+declare function seoToTags(seo: SeoDoc | unknown, ctx?: SeoTagContext): SeoTag[];
+
+/**
+ * The authoring schema for the `seo` object, in the platform's standard property dialect: `label`
+ * at property level, rendering metadata under `controller`.
+ *
+ * ONE builder, two callers: `iox-cms` spreads it into `PagesSchema` (the stored schema) and
+ * `iox-cms-client` feeds it to `<dynamic-form>`. Those used to be two hand-written copies that had
+ * already drifted — different controller types for the same field, and the client's copy missing
+ * `structuredData` entirely.
+ *
+ * `keywords` is deliberately absent: the tag is emitted when a document carries one, but there is
+ * no reason to invite new ones.
+ */
+declare function buildSeoSchemaProperties(): Record<string, unknown>;
+
+export { SEO_CHANGE_FREQ_OPTIONS, SEO_DESCRIPTION_MAX, SEO_ROBOTS_OPTIONS, SEO_TITLE_MAX, SEO_TWITTER_CARD_OPTIONS, buildSeoSchemaProperties, normalizeSeoDoc, seoToTags };
+export type { SeoDoc, SeoLinkTag, SeoMetaTag, SeoOg, SeoSitemap, SeoTag, SeoTagContext, SeoTitleTag, SeoTwitter };

package/seo-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-seo-core.mjs"
+}

package/src/seo-core/normalize.ts

@@ -0,0 +1,125 @@
+import { SeoDoc, SeoOg, SeoSitemap, SeoTwitter } from './seo.model';
+
+/**
+ * Coerce whatever a page document happens to hold into a `SeoDoc`.
+ *
+ * Every consumer calls this before reading `seo`, because four shapes are in the wild:
+ *  • the current nested shape (`og.title`);
+ *  • the flat shape the SSR engine used to read (`ogTitle`) — never actually written, but a
+ *    document hand-edited against the old engine code could carry it;
+ *  • `""` for "not set", which must not become an empty `<meta>`;
+ *  • `{ override: '…' }`, the per-field value object that plan phase 2 introduces — tolerated here
+ *    so the ladder can land without a second normalizer.
+ *
+ * Empty branches are dropped rather than left as `{}`, so `if (seo.og)` is a meaningful test.
+ */
+export function normalizeSeoDoc(raw: unknown): SeoDoc {
+    const src = asRecord(raw);
+    if (!src) return {};
+
+    const og = compact<SeoOg>({
+        title: str(pick(src, 'og', 'title') ?? src['ogTitle']),
+        description: str(pick(src, 'og', 'description') ?? src['ogDescription']),
+        image: str(pick(src, 'og', 'image') ?? src['ogImage']),
+    });
+
+    const twitter = compact<SeoTwitter>({
+        card: str(pick(src, 'twitter', 'card')),
+        title: str(pick(src, 'twitter', 'title')),
+        description: str(pick(src, 'twitter', 'description')),
+        image: str(pick(src, 'twitter', 'image')),
+    });
+
+    const sitemap = compact<SeoSitemap>({
+        include: bool(pick(src, 'sitemap', 'include')),
+        priority: num(pick(src, 'sitemap', 'priority')),
+        changeFreq: str(pick(src, 'sitemap', 'changeFreq')),
+    });
+
+    const structuredData = structured(src['structuredData']);
+
+    const doc = compact<SeoDoc>({
+        title: str(src['title']),
+        description: str(src['description']),
+        keywords: str(src['keywords']),
+        canonicalUrl: str(src['canonicalUrl']),
+        robots: str(src['robots']),
+        og,
+        twitter,
+        sitemap,
+        structuredData,
+    });
+
+    return doc ?? {};
+}
+
+/** Read `src[branch][leaf]` without assuming the branch exists or is an object. */
+function pick(src: Record<string, unknown>, branch: string, leaf: string): unknown {
+    const nested = asRecord(src[branch]);
+    return nested ? nested[leaf] : undefined;
+}
+
+/**
+ * A field's value as a trimmed string, or `undefined`.
+ *
+ * Unwraps the phase-2 value object: a bound or auto field has no `override`, so it correctly
+ * resolves to `undefined` here and the binding layer fills it in later.
+ */
+function str(value: unknown): string | undefined {
+    const wrapper = asRecord(value);
+    const raw = wrapper ? wrapper['override'] : value;
+    if (typeof raw === 'number') return String(raw);
+    if (typeof raw !== 'string') return undefined;
+    const trimmed = raw.trim();
+    return trimmed.length ? trimmed : undefined;
+}
+
+/**
+ * `UIFormToDTO` can hand back `"true"` / `"false"` for a switch (see
+ * `architecture/cms/shop.md` — the boolean/number coercion pitfall), so accept both.
+ */
+function bool(value: unknown): boolean | undefined {
+    if (typeof value === 'boolean') return value;
+    if (value === 'true') return true;
+    if (value === 'false') return false;
+    return undefined;
+}
+
+function num(value: unknown): number | undefined {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : undefined;
+    if (typeof value !== 'string' || !value.trim().length) return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/** JSON-LD is stored as an object or as a JSON string from the `json` controller. */
+function structured(value: unknown): unknown {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed.length) return undefined;
+        try {
+            return JSON.parse(trimmed);
+        } catch {
+            return undefined;
+        }
+    }
+    if (Array.isArray(value)) return value.length ? value : undefined;
+    const record = asRecord(value);
+    return record && Object.keys(record).length ? record : undefined;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : undefined;
+}
+
+/** Drop `undefined` values and empty nested objects, so absence is always `undefined`. */
+function compact<T extends object>(value: Record<string, unknown>): T | undefined {
+    const out: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined) continue;
+        out[key] = entry;
+    }
+    return (Object.keys(out).length ? out : undefined) as T | undefined;
+}

package/src/seo-core/public-api.ts

@@ -0,0 +1,16 @@
+/*
+ * @vectoriox/iox-ui/seo-core — the shared, FRAMEWORK-FREE core of page SEO.
+ *
+ * ⚠️ Nothing in this entry point may import Angular, RxJS, the DOM, or Node. It is consumed by
+ * THREE runtimes: the builder panel (Angular), the SSR engine (Angular), and `iox-cms` (NestJS,
+ * plain Node) — the same reason `forms-core` exists.
+ *
+ * A page describes itself to a crawler exactly once: `seoToTags` is the only place that decides
+ * which head tags a page emits, and `buildSeoSchemaProperties` the only place that declares what an
+ * author can fill in. See iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+
+export * from './seo.model';
+export * from './normalize';
+export * from './tags';
+export * from './schema';

package/src/seo-core/schema.ts

@@ -0,0 +1,140 @@
+import {
+    SEO_CHANGE_FREQ_OPTIONS,
+    SEO_DESCRIPTION_MAX,
+    SEO_ROBOTS_OPTIONS,
+    SEO_TITLE_MAX,
+    SEO_TWITTER_CARD_OPTIONS,
+} from './seo.model';
+
+/**
+ * The authoring schema for the `seo` object, in the platform's standard property dialect: `label`
+ * at property level, rendering metadata under `controller`.
+ *
+ * ONE builder, two callers: `iox-cms` spreads it into `PagesSchema` (the stored schema) and
+ * `iox-cms-client` feeds it to `<dynamic-form>`. Those used to be two hand-written copies that had
+ * already drifted — different controller types for the same field, and the client's copy missing
+ * `structuredData` entirely.
+ *
+ * `keywords` is deliberately absent: the tag is emitted when a document carries one, but there is
+ * no reason to invite new ones.
+ */
+export function buildSeoSchemaProperties(): Record<string, unknown> {
+    return {
+        title: {
+            type: 'string',
+            label: 'Meta Title',
+            controller: {
+                type: 'text',
+                placeholder: 'Page title for search engines',
+                maxLength: SEO_TITLE_MAX,
+            },
+        },
+        description: {
+            type: 'string',
+            label: 'Meta Description',
+            controller: {
+                type: 'textarea',
+                placeholder: 'Brief description for search results',
+                maxLength: SEO_DESCRIPTION_MAX,
+            },
+        },
+        canonicalUrl: {
+            type: 'string',
+            label: 'Canonical URL',
+            controller: {
+                type: 'text',
+                placeholder: 'https://example.com/page',
+            },
+        },
+        robots: {
+            type: 'string',
+            label: 'Robots',
+            controller: {
+                type: 'select',
+                options: SEO_ROBOTS_OPTIONS.map(option => ({ ...option })),
+            },
+        },
+        og: {
+            type: 'object',
+            label: 'Open Graph',
+            controller: { type: 'object' },
+            properties: {
+                title: {
+                    type: 'string',
+                    label: 'OG Title',
+                    controller: { type: 'text', placeholder: 'Title for social sharing' },
+                },
+                description: {
+                    type: 'string',
+                    label: 'OG Description',
+                    controller: { type: 'textarea', placeholder: 'Description for social sharing' },
+                },
+                image: {
+                    type: 'string',
+                    label: 'OG Image',
+                    controller: { type: 'image' },
+                },
+            },
+        },
+        twitter: {
+            type: 'object',
+            label: 'Twitter Card',
+            controller: { type: 'object' },
+            properties: {
+                card: {
+                    type: 'string',
+                    label: 'Card Type',
+                    controller: {
+                        type: 'select',
+                        options: SEO_TWITTER_CARD_OPTIONS.map(option => ({ ...option })),
+                    },
+                },
+                title: {
+                    type: 'string',
+                    label: 'Twitter Title',
+                    controller: { type: 'text' },
+                },
+                description: {
+                    type: 'string',
+                    label: 'Twitter Description',
+                    controller: { type: 'textarea' },
+                },
+                image: {
+                    type: 'string',
+                    label: 'Twitter Image',
+                    controller: { type: 'image' },
+                },
+            },
+        },
+        structuredData: {
+            type: 'object',
+            label: 'Structured Data (JSON-LD)',
+            controller: { type: 'json' },
+        },
+        sitemap: {
+            type: 'object',
+            label: 'Sitemap Settings',
+            controller: { type: 'object' },
+            properties: {
+                include: {
+                    type: 'boolean',
+                    label: 'Include in Sitemap',
+                    controller: { type: 'switch' },
+                },
+                priority: {
+                    type: 'number',
+                    label: 'Priority',
+                    controller: { type: 'range', options: { min: 0, max: 1, step: 0.1 } },
+                },
+                changeFreq: {
+                    type: 'string',
+                    label: 'Change Frequency',
+                    controller: {
+                        type: 'select',
+                        options: SEO_CHANGE_FREQ_OPTIONS.map(option => ({ ...option })),
+                    },
+                },
+            },
+        },
+    };
+}

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

@@ -0,0 +1,111 @@
+/**
+ * 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;
+}
+
+/** `<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;
+}