@vectoriox/iox-ui 5.2.0 → 5.4.0

package/index.d.ts

@@ -1549,6 +1549,66 @@ declare function compileTokenCss(tokens: ReadonlyArray<DesignTokenLike> | null |
     dark: string;
 };
 
+/**
+ * Flavors (flavors-and-theming-plan.md, F1): the design language a studio launches with,
+ * expressed as data. THE invariant — a flavor never writes a literal into a node; it writes
+ * tokens, and element defaults that REFERENCE tokens. To that end a pack's `defaults` map
+ * holds TOKEN NAMES, not CSS values: the resolver builds `var(--iox-<name>, <packValue>)`,
+ * so smuggling a literal in is impossible by construction, and the validator only has to
+ * check that every referenced token exists.
+ *
+ * The fallback is the bootstrap: until F2 seeds the org's `designtokens` rows, no `--iox-*`
+ * var is defined anywhere, and `var(--iox-radius-control, 4px)` must still paint identically
+ * in the builder canvas and the SSR page. Once tokens ARE seeded (or re-themed), the var wins
+ * over the fallback everywhere — which is exactly the §3 propagation story.
+ */
+interface FlavorTokenDef {
+    name: string;
+    value: string;
+    /** Dark-scheme override, seeded into DesignToken.values.dark at F2. */
+    values?: {
+        dark?: string;
+    };
+    type?: 'color' | 'spacing' | 'size' | 'font' | 'other';
+    /** Tokens-panel grouping (flavors plan §10 C5). */
+    group?: 'colour' | 'type' | 'space' | 'radius' | 'shadow' | 'motion';
+}
+interface FlavorPack {
+    id: string;
+    /** Bumped when the pack's values change; seeding stamps `flavor:<id>@<version>` as DesignToken.source. */
+    version: number;
+    label: string;
+    blurb: string;
+    tokens: FlavorTokenDef[];
+    /** type → styleTrait → TOKEN NAME (never a CSS value — see the module header). */
+    defaults: Record<string, Record<string, string>>;
+}
+/** trait → `var(--iox-<token>, <packValue>)` for one node type. Unknown type → {}. */
+declare function resolveFlavorDefaults(type: string, pack: FlavorPack | null | undefined): Record<string, string>;
+/**
+ * The ENGINE's half of the cascade: kebab `prop: var(…)` declarations for every pack default
+ * the node's persisted styleProps does NOT set. Appended beside renderDefaultDeclarations —
+ * same guard-on-undefined discipline, so a node saved post-F1 (var already serialised via the
+ * builder's trait defaults) is untouched, and a legacy node picks the pack default up at
+ * render time. Node styleProps always wins.
+ */
+declare function flavorDefaultDeclarations(type: string, styleProps: Record<string, any> | null | undefined, pack: FlavorPack | null | undefined): string[];
+/**
+ * The CI gate (flavors plan §10 C4): a pack may only name types and traits that exist in the
+ * live component registry, and tokens it defines itself. Returns human-readable errors; a
+ * consumer spec feeds it the REAL registry and asserts [].
+ */
+declare function validateFlavorPack(pack: FlavorPack, knownTraitsByType: Record<string, ReadonlySet<string> | string[]>): string[];
+/**
+ * Swiss — the default pack (flavors plan §8: "the flavor that can never embarrass anyone").
+ * Deliberately SMALL at F1: radius + control padding on the clickables, surface radius on Card.
+ * Colour, type and motion arrive with the brand step (F2) — a colour default here would repaint
+ * legacy pages before anyone chose anything.
+ */
+declare const SWISS_FLAVOR: FlavorPack;
+/** What both renderers use until F2 lets an org choose. */
+declare const DEFAULT_FLAVOR: FlavorPack;
+
 /**
  * page-style — the ONE compiler that turns a page's style settings into CSS.
  *
@@ -2718,5 +2778,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, 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, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, compileTokenCss, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, styleKeyToKebab, tokensToDarkVarMap, tokensToVarMap, 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, DesignTokenLike, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };
+export { AOSService, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_FLAVOR, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, 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, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SWISS_FLAVOR, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, compileTokenCss, composeVirtualTraits, computeRelative, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, flavorDefaultDeclarations, getByPath, getSeoValue, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveFlavorDefaults, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, stripSuppressedProps, styleKeyToKebab, tokensToDarkVarMap, tokensToVarMap, validateFlavorPack, 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, DesignTokenLike, FlavorPack, FlavorTokenDef, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, 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": "5.2.0",
+  "version": "5.4.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",
@@ -23,6 +23,10 @@
       "types": "./actions-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-actions-core.mjs"
     },
+    "./consent-core": {
+      "types": "./consent-core/index.d.ts",
+      "default": "./fesm2022/vectoriox-iox-ui-consent-core.mjs"
+    },
     "./forms-core": {
       "types": "./forms-core/index.d.ts",
       "default": "./fesm2022/vectoriox-iox-ui-forms-core.mjs"

package/src/consent-core/consent-mode.ts

@@ -0,0 +1,38 @@
+import { ConsentCategory, ConsentDecision, hasConsent } from './consent.model';
+
+/**
+ * Google Consent Mode v2 (consent plan §4): four parameters, mandatory for EEA/UK measurement
+ * since March 2024. Our categories map onto them; `necessary` maps to none.
+ */
+export type ConsentModeSignal = 'granted' | 'denied';
+
+export const CONSENT_MODE_PARAMS = [
+    'analytics_storage', 'ad_storage', 'ad_user_data', 'ad_personalization',
+] as const;
+
+/** What the SSR head declares BEFORE any tag can load (invariant I1): everything denied. */
+export const CONSENT_DEFAULTS_DENIED: Readonly<Record<(typeof CONSENT_MODE_PARAMS)[number], ConsentModeSignal>> =
+    Object.freeze({
+        analytics_storage: 'denied',
+        ad_storage: 'denied',
+        ad_user_data: 'denied',
+        ad_personalization: 'denied',
+    });
+
+/** A decision → the four v2 signals. `null` (undecided) is indistinguishable from denied. */
+export function toConsentModeSignals(decision: ConsentDecision | null | undefined): Record<string, ConsentModeSignal> {
+    const analytics: ConsentModeSignal = hasConsent(decision ?? null, ConsentCategory.Analytics) ? 'granted' : 'denied';
+    const marketing: ConsentModeSignal = hasConsent(decision ?? null, ConsentCategory.Marketing) ? 'granted' : 'denied';
+    return {
+        analytics_storage: analytics,
+        ad_storage: marketing,
+        ad_user_data: marketing,
+        ad_personalization: marketing,
+    };
+}
+
+/** The inline `<head>` bootstrap (basic mode, D-C2): defaults denied before anything loads. */
+export function consentModeBootstrapJs(): string {
+    return "window.dataLayer=window.dataLayer||[];function gtag(){dataLayer.push(arguments);}" +
+        `gtag('consent','default',${JSON.stringify(CONSENT_DEFAULTS_DENIED)});`;
+}

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

@@ -0,0 +1,64 @@
+/**
+ * The visitor-consent vocabulary (consent plan C1). Framework-free for the same forced reason as
+ * forms-core/seo-core/actions-core: iox-cms consumes it under plain Node, the engine at SSR time,
+ * the builder for design-time preview — ONE implementation of what a decision is.
+ */
+
+export enum ConsentCategory {
+    /** Always on, never user-controllable — the site working at all. */
+    Necessary = 'necessary',
+    Analytics = 'analytics',
+    Marketing = 'marketing',
+}
+
+/** A visitor's recorded decision. `necessary` is implied true and never stored as false. */
+export interface ConsentDecision {
+    categories: Partial<Record<ConsentCategory, boolean>>;
+    /** Bumping the org's policy version invalidates every prior decision. */
+    policyVersion: string;
+    /** ISO timestamp of the decision. */
+    decidedAt: string;
+    anonymousId: string;
+}
+
+/** A fresh "nothing granted" decision skeleton — used when a visitor must be asked. */
+export function emptyDecision(anonymousId: string, policyVersion: string, now: Date = new Date()): ConsentDecision {
+    return {
+        categories: { [ConsentCategory.Necessary]: true },
+        policyVersion,
+        decidedAt: now.toISOString(),
+        anonymousId,
+    };
+}
+
+/** `null` (no decision yet) grants nothing; `necessary` is always granted. */
+export function hasConsent(decision: ConsentDecision | null | undefined, category: ConsentCategory): boolean {
+    if (category === ConsentCategory.Necessary) return true;
+    if (!decision) return false;
+    return decision.categories?.[category] === true;
+}
+
+/** A decision older than `maxMonths` no longer counts (default re-ask: 12 months, D-C6). */
+export function isExpired(decision: ConsentDecision, now: Date, maxMonths: number): boolean {
+    const decided = new Date(decision.decidedAt);
+    if (Number.isNaN(decided.getTime())) return true;
+    const expiry = new Date(decided);
+    expiry.setMonth(expiry.getMonth() + maxMonths);
+    return now >= expiry;
+}
+
+/**
+ * The function the dead fork got wrong: **a recorded "no" is a decision.** The banner shows only
+ * when there is no decision, the decision expired, or the policy version moved on — never because
+ * the visitor declined.
+ */
+export function needsPrompt(
+    decision: ConsentDecision | null | undefined,
+    policyVersion: string,
+    now: Date = new Date(),
+    maxMonths = 12,
+): boolean {
+    if (!decision) return true;
+    if (decision.policyVersion !== policyVersion) return true;
+    return isExpired(decision, now, maxMonths);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * @vectoriox/iox-ui/consent-core — the shared, FRAMEWORK-FREE core of visitor consent.
+ *
+ * What a decision IS (`needsPrompt`: a recorded "no" is a decision), how it travels (a tolerant
+ * first-party cookie), and what it tells Google (Consent Mode v2 signals, denied-by-default).
+ * Consumed by the SSR engine (the gate, C2), the builder (banner preview, C3) and iox-cms (the
+ * optional per-org log, C4) — the fourth entry point on the forms-core pattern, replacing the
+ * dead byte-identical fork C0 deleted.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig
+ * paths — or `nest start` dies with ERR_REQUIRE_ESM while jest and build both pass.
+ */
+export * from './consent.model';
+export * from './storage';
+export * from './consent-mode';

package/src/consent-core/storage.ts

@@ -0,0 +1,43 @@
+import { ConsentCategory, ConsentDecision } from './consent.model';
+
+/** First-party cookie name — the visitor's browser carries the proof (D-C1). */
+export const CONSENT_COOKIE_NAME = 'iox-consent';
+
+/** Cookie payload. Versioned so a future shape change can read old cookies tolerantly. */
+export function encode(decision: ConsentDecision): string {
+    return JSON.stringify({ v: 1, ...decision });
+}
+
+/**
+ * Tolerant by contract: bad JSON, a foreign shape, a tampered cookie — all read as `null`
+ * ("no decision"), never a throw and never a guess. The old fork threw its way to a re-prompt.
+ */
+export function decode(raw: string | null | undefined): ConsentDecision | null {
+    if (!raw) return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object') return null;
+        if (typeof parsed.anonymousId !== 'string' || !parsed.anonymousId) return null;
+        if (typeof parsed.policyVersion !== 'string') return null;
+        if (!parsed.categories || typeof parsed.categories !== 'object' || Array.isArray(parsed.categories)) return null;
+        const categories: Partial<Record<ConsentCategory, boolean>> = {};
+        for (const [k, v] of Object.entries(parsed.categories)) {
+            categories[k as ConsentCategory] = v === true;
+        }
+        categories[ConsentCategory.Necessary] = true;
+        return {
+            categories,
+            policyVersion: parsed.policyVersion,
+            decidedAt: typeof parsed.decidedAt === 'string' ? parsed.decidedAt : '',
+            anonymousId: parsed.anonymousId,
+        };
+    } catch {
+        return null;
+    }
+}
+
+/** `Set-Cookie` attributes for the decision: a NECESSARY cookie, 12 months, first-party. */
+export function cookieAttributes(maxMonths = 12): string {
+    const maxAge = Math.floor(maxMonths * 30.44 * 24 * 60 * 60);
+    return `Path=/; Max-Age=${maxAge}; SameSite=Lax; Secure`;
+}