@vectoriox/iox-ui 4.33.1 → 4.35.0

package/index.d.ts

@@ -1941,6 +1941,115 @@ declare function safeSetInput(ref: ComponentRef<unknown>, name: string, value: u
  */
 declare function resolvePath(obj: any, path: string): any;
 
+/** The part of an `IoxBinding` that turns source data into a value. */
+interface BoundValueSpec {
+    /** Dot/bracket path into the source data. Empty or absent means the source value itself. */
+    path?: string;
+    /** Render-time transforms (UI label "Filters"), applied after the path lookup. */
+    pipes?: IoxPipe[];
+}
+/**
+ * Resolve one binding's value out of its already-selected source data: path lookup, then pipes.
+ *
+ * Trivial on its own, which is exactly why it had been retyped at three call sites — the engine's
+ * string renderer, the engine's component renderer and the builder canvas — plus a fourth needed by
+ * page SEO. `resolvePath` itself was forked five times before it was shared, and the copy that
+ * drifted caused a repeater to render in the SSR HTML and then blank on hydration.
+ *
+ * What is NOT here: picking the source (`resolvedData[binding.source]`) and deciding what an empty
+ * context slot means. Those are per-renderer policy — the string renderer clears the prop, the
+ * builder skips it — so they stay with the caller.
+ */
+declare function resolveBoundValue(sourceData: unknown, binding: BoundValueSpec, ctx?: PipeContext): unknown;
+
+/**
+ * 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;
+}
+
+/**
+ * Turn a page's STORED SEO document into the resolved one a crawler should see.
+ *
+ * Runs the ladder, per field: `override` → `binding` → auto. It lives in the main entry point rather
+ * than `seo-core` because the binding rung needs `resolvePath` + `applyBindingPipes` from here, and
+ * `iox-cms` (which imports `seo-core` under plain Node) never resolves anything — it only stores and
+ * declares. `seoToTags` then turns this output into head tags.
+ *
+ * The reason this exists: `applyPageSeo(page.seo)` used to hand the stored strings straight to the
+ * head, never consulting the resolved route item, so all 24 pages rendered from one template shipped
+ * the same `<title>`. See iox-ai-guidance `architecture/cms/seo-plan.md`.
+ */
+/** What the ladder's lower two rungs need. All optional — a static page supplies almost none of it. */
+interface SeoResolveContext {
+    /** The page's resolved data sources, keyed by alias (`$current` on a template page). */
+    resolvedData?: Record<string, unknown> | null;
+    /** The page's layout tree, for the "derive from the content" rung. */
+    tree?: readonly unknown[] | null;
+    /** Title of last resort, when the page has no heading at all. */
+    pageName?: string;
+    /** Absolute URL of the page being rendered — the automatic canonical. */
+    pageUrl?: string;
+}
+/** What the layout tree yields for the bottom rung. */
+interface SeoDerivedContent {
+    title?: string;
+    description?: string;
+    image?: string;
+}
+declare function resolveSeo(seo: unknown, ctx?: SeoResolveContext): SeoDoc;
+/**
+ * Derive a title, description and image from the page's own content, in document order.
+ *
+ * ⚠️ Node bindings are resolved here too. On a template page the `<h1>` is normally bound to
+ * `$current.title`, so reading `props.content` alone would return the design-time placeholder — the
+ * same trap that made context slots fall through to component defaults. An unresolved binding yields
+ * nothing rather than the placeholder.
+ *
+ * Node shapes are the renderers' own: `Heading` has `level` + `content`, `Text` has `content` (rich
+ * HTML from the editor) + `tag`, `Image` has `src`.
+ */
+declare function deriveSeoFromContent(tree: readonly unknown[] | null | undefined, resolvedData?: Record<string, unknown> | null): SeoDerivedContent;
+
 /**
  * Element context state — shared types.
  *
@@ -2441,5 +2550,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, ENVIRONMENT, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };
+export { AOSService, AnalyticsService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CMSClientInfraModule, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ConsentService, ContainerComponent, ContentService, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, ENVIRONMENT, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, PrivacyModalComponent, PrivacyModalService, PrivacyModelEvent, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, WebSettingsService, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, effectiveTransitionId, excludeSelf, feelFor, getByPath, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, parentBreakpoint, parseUrlList, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, stateNamesIn, stripSuppressedProps, styleKeyToKebab, variableAliases, variableItemsFrom, withContextSlots, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "4.33.1",
+  "version": "4.35.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,189 @@
+/**
+ * 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;
+}
+/**
+ * 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.
+ */
+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.
+ */
+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. */
+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.
+ */
+declare const SEO_BINDABLE_FIELDS: readonly string[];
+/** Where an automatic value comes from when a field has neither an override nor a binding. */
+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.
+ */
+declare const SEO_AUTO_SOURCES: ReadonlyArray<{
+    field: string;
+    source: SeoAutoSource;
+}>;
+/** `<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;
+/**
+ * A field's value as a trimmed string, or `undefined`. Exported because the resolver needs the exact
+ * same coercion for a value it has just pulled out of a data source.
+ *
+ * Unwraps the value object: a bound or auto field has no `override`, so it correctly resolves to
+ * `undefined` here and `resolveSeo` fills it in from the lower rungs.
+ */
+declare function seoString(value: unknown): string | undefined;
+
+/**
+ * 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_AUTO_SOURCES, SEO_BINDABLE_FIELDS, SEO_CHANGE_FREQ_OPTIONS, SEO_DESCRIPTION_MAX, SEO_ROBOTS_OPTIONS, SEO_TITLE_MAX, SEO_TWITTER_CARD_OPTIONS, buildSeoSchemaProperties, normalizeSeoDoc, seoString, seoToTags };
+export type { SeoAutoSource, SeoBinding, SeoDoc, SeoFieldValue, SeoLinkTag, SeoMetaTag, SeoOg, SeoRawDoc, 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,126 @@
+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: seoString(pick(src, 'og', 'title') ?? src['ogTitle']),
+        description: seoString(pick(src, 'og', 'description') ?? src['ogDescription']),
+        image: seoString(pick(src, 'og', 'image') ?? src['ogImage']),
+    });
+
+    const twitter = compact<SeoTwitter>({
+        card: seoString(pick(src, 'twitter', 'card')),
+        title: seoString(pick(src, 'twitter', 'title')),
+        description: seoString(pick(src, 'twitter', 'description')),
+        image: seoString(pick(src, 'twitter', 'image')),
+    });
+
+    const sitemap = compact<SeoSitemap>({
+        include: bool(pick(src, 'sitemap', 'include')),
+        priority: num(pick(src, 'sitemap', 'priority')),
+        changeFreq: seoString(pick(src, 'sitemap', 'changeFreq')),
+    });
+
+    const structuredData = structured(src['structuredData']);
+
+    const doc = compact<SeoDoc>({
+        title: seoString(src['title']),
+        description: seoString(src['description']),
+        keywords: seoString(src['keywords']),
+        canonicalUrl: seoString(src['canonicalUrl']),
+        robots: seoString(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`. Exported because the resolver needs the exact
+ * same coercion for a value it has just pulled out of a data source.
+ *
+ * Unwraps the value object: a bound or auto field has no `override`, so it correctly resolves to
+ * `undefined` here and `resolveSeo` fills it in from the lower rungs.
+ */
+export function seoString(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 })),
+                    },
+                },
+            },
+        },
+    };
+}