@contentful/experiences-design 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 0.7.1 (2026-08-07)
+
+### 🚀 Features
+
+- server-side design pre-resolution against a fallback viewport [AIS-386] ([#119](https://github.com/contentful/experiences/pull/119))
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.7.1
+
 ## 0.7.0 (2026-08-07)
 
 ### 🧱 Updated Dependencies

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties, toCssMediaQuery } from './viewport.js';
+export { toCssMediaQuery } from './viewport.js';
 export { CSS_PROPERTIES, isCssProperty, toCssKey } from './css-properties.js';
-import '@contentful/experiences-sdk-core';
+export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties } from '@contentful/experiences-sdk-core';

package/dist/viewport.d.ts

@@ -1,4 +1,5 @@
-import { DesignToken, ResolveToken, DesignPropValue, ViewportDef } from '@contentful/experiences-sdk-core';
+import { ViewportDef } from '@contentful/experiences-sdk-core';
+export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties } from '@contentful/experiences-sdk-core';
 
 /**
  * Convert a Contentful viewport `query` string into a CSS media query.
@@ -6,39 +7,5 @@ import { DesignToken, ResolveToken, DesignPropValue, ViewportDef } from '@conten
  * or for any unrecognized format.
  */
 declare function toCssMediaQuery(viewport: ViewportDef): string | undefined;
-/**
- * Resolve a viewport ID to its index in the ordered viewports list. Returns 0
- * (the wildcard viewport) when the id is unknown or undefined.
- */
-declare function getViewportIndex(viewports: ViewportDef[], viewportId?: string): number;
-/**
- * Resolve a single design-property envelope to its render-time value:
- *  - ManualDesignValue → its scalar
- *  - DesignToken       → the envelope passes through (customer-owned resolution)
- *  - ValuesByViewport  → cascade-lookup against the active viewport, then
- *                        unwrap the inner Manual/Token as above
- *  - undefined         → returns undefined
- */
-declare function getValueForViewport(prop: DesignPropValue | undefined, viewports: ViewportDef[], activeViewportIndex: number): string | number | boolean | DesignToken | undefined;
-/**
- * Resolve every design-property envelope on a node into a flat record keyed
- * by property name. Customer components receive these values as plain props.
- */
-declare function resolveDesignProperties(designProperties: Record<string, DesignPropValue> | undefined, viewports: ViewportDef[], activeViewportIndex: number): Record<string, string | number | boolean | DesignToken>;
-/**
- * Resolves `DesignToken` envelopes in a viewport-resolved design record via
- * `resolveToken`; scalars pass through, and with no resolver the record is
- * returned unchanged. Keys that resolve to `undefined` are dropped and their
- * token ids collected in `unresolved` for a single grouped warning.
- *
- * When no `resolveToken` is configured but the record contains `DesignToken`
- * envelopes, warns once — those keys reach components as raw envelope objects
- * (e.g. rendering as `[object Object]`), which is almost always a missing-
- * config mistake rather than intent.
- */
-declare function applyTokenResolver(props: Record<string, string | number | boolean | DesignToken>, resolveToken?: ResolveToken): {
-    props: Record<string, unknown>;
-    unresolved: string[];
-};
 
-export { applyTokenResolver, getValueForViewport, getViewportIndex, resolveDesignProperties, toCssMediaQuery };
+export { toCssMediaQuery };

package/dist/viewport.js

@@ -1,3 +1,9 @@
+import {
+  applyTokenResolver,
+  getValueForViewport,
+  getViewportIndex,
+  resolveDesignProperties
+} from "@contentful/experiences-sdk-core";
 const MEDIA_QUERY_REGEXP = /^(<|>)(\d+)(px|cm|mm|in|pt|pc)$/;
 function toCssMediaQuery(viewport) {
   const { query } = viewport;
@@ -14,70 +20,6 @@ function toCssMediaQuery(viewport) {
   }
   return void 0;
 }
-function getViewportIndex(viewports, viewportId) {
-  if (!viewportId) return 0;
-  const index = viewports.findIndex((v) => v.id === viewportId);
-  return index === -1 ? 0 : index;
-}
-function unwrapInner(inner) {
-  if (!inner) return void 0;
-  if (inner.type === "ManualDesignValue") return inner.value;
-  return inner;
-}
-function resolveValuesByViewport(bag, viewports, activeViewportIndex) {
-  for (let i = activeViewportIndex; i >= 0; i--) {
-    const viewport = viewports[i];
-    if (!viewport) continue;
-    const candidate = bag.values[viewport.id];
-    if (candidate !== void 0 && candidate !== null) return candidate;
-  }
-  return void 0;
-}
-function getValueForViewport(prop, viewports, activeViewportIndex) {
-  if (!prop) return void 0;
-  if (prop.type === "ManualDesignValue") return prop.value;
-  if (prop.type === "DesignToken") return prop;
-  return unwrapInner(resolveValuesByViewport(prop, viewports, activeViewportIndex));
-}
-function resolveDesignProperties(designProperties, viewports, activeViewportIndex) {
-  const out = {};
-  if (!designProperties) return out;
-  for (const [key, prop] of Object.entries(designProperties)) {
-    const value = getValueForViewport(prop, viewports, activeViewportIndex);
-    if (value !== void 0) out[key] = value;
-  }
-  return out;
-}
-let warnedMissingResolver = false;
-function applyTokenResolver(props, resolveToken) {
-  if (!resolveToken) {
-    if (!warnedMissingResolver && typeof console !== "undefined") {
-      const tokenKeys = Object.entries(props).filter(([, v]) => typeof v === "object" && v !== null && v.type === "DesignToken").map(([k]) => k);
-      if (tokenKeys.length) {
-        warnedMissingResolver = true;
-        console.warn(
-          `[@contentful/experiences] Design tokens are present but no \`resolveToken\` is configured on the Config; token-valued design props (${tokenKeys.join(", ")}) reach components unresolved. Add \`resolveToken\` to your Config to map token ids to values.`
-        );
-      }
-    }
-    return { props, unresolved: [] };
-  }
-  const out = {};
-  const unresolved = [];
-  for (const [key, value] of Object.entries(props)) {
-    if (typeof value === "object" && value !== null && value.type === "DesignToken") {
-      const resolved = resolveToken(value);
-      if (resolved === void 0) {
-        unresolved.push(value.value);
-        continue;
-      }
-      out[key] = resolved;
-      continue;
-    }
-    out[key] = value;
-  }
-  return { props: out, unresolved };
-}
 export {
   applyTokenResolver,
   getValueForViewport,

package/dist/viewport.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/viewport.ts"],"sourcesContent":["/*\n * Viewport math + design-property resolution for the Experiences SDK.\n *\n * ## Cascade model\n *\n * Viewport order in the payload encodes cascade direction:\n *  - desktop-first: viewports descend by screen width (`*`, `<992px`, `<576px`)\n *  - mobile-first:  viewports ascend by screen width (`*`, `>576px`, `>992px`)\n *\n * \"Active viewport\" = the last-matching media query in the ordered list.\n * `getValueForViewport` walks backwards from the active viewport toward\n * viewport[0], returning the first defined value — emulating CSS cascade\n * behavior at runtime.\n *\n * ## DesignPropValue unwrapping\n *\n * v1 design properties arrive as a discriminated union:\n *  - ManualDesignValue → unwrap to its scalar `value`\n *  - DesignToken       → pass the envelope through unchanged so customer\n *                        components can resolve it themselves (token\n *                        resolution lands in the future tokens package)\n *  - ValuesByViewport  → cascade-lookup the inner ManualDesignValue/DesignToken\n *                        at the active viewport, then unwrap as above\n */\n\nimport type {\n  DesignPropValue,\n  DesignToken,\n  ManualDesignValue,\n  ResolveToken,\n  ValuesByViewport,\n  ViewportDef,\n} from '@contentful/experiences-sdk-core';\n\nconst MEDIA_QUERY_REGEXP = /^(<|>)(\\d+)(px|cm|mm|in|pt|pc)$/;\n\n/**\n * Convert a Contentful viewport `query` string into a CSS media query.\n * Returns `undefined` for the wildcard \"*\" (always matches; no media query needed)\n * or for any unrecognized format.\n */\nexport function toCssMediaQuery(viewport: ViewportDef): string | undefined {\n  const { query } = viewport;\n  if (query === '*') return undefined;\n  const match = query.match(MEDIA_QUERY_REGEXP);\n  if (!match) return undefined;\n  const [, operator, value, unit] = match;\n  if (!operator || !value || !unit) return undefined;\n  if (operator === '<') {\n    return `(max-width: ${Number(value) - 1}${unit})`;\n  }\n  if (operator === '>') {\n    return `(min-width: ${Number(value) + 1}${unit})`;\n  }\n  return undefined;\n}\n\n/**\n * Resolve a viewport ID to its index in the ordered viewports list. Returns 0\n * (the wildcard viewport) when the id is unknown or undefined.\n */\nexport function getViewportIndex(viewports: ViewportDef[], viewportId?: string): number {\n  if (!viewportId) return 0;\n  const index = viewports.findIndex((v) => v.id === viewportId);\n  return index === -1 ? 0 : index;\n}\n\n/**\n * Unwrap a non-viewport-keyed envelope into a value the customer component\n * can consume directly. ManualDesignValue → its scalar; DesignToken → the\n * envelope passes through (customer-owned resolution).\n */\nfunction unwrapInner(\n  inner: ManualDesignValue | DesignToken | undefined\n): string | number | boolean | DesignToken | undefined {\n  if (!inner) return undefined;\n  if (inner.type === 'ManualDesignValue') return inner.value;\n  return inner;\n}\n\n/**\n * Cascade-lookup for a `ValuesByViewport` envelope. Walks backwards from\n * `activeViewportIndex` toward viewport[0], returning the first defined value.\n */\nfunction resolveValuesByViewport(\n  bag: ValuesByViewport,\n  viewports: ViewportDef[],\n  activeViewportIndex: number\n): ManualDesignValue | DesignToken | undefined {\n  for (let i = activeViewportIndex; i >= 0; i--) {\n    const viewport = viewports[i];\n    if (!viewport) continue;\n    const candidate = bag.values[viewport.id];\n    if (candidate !== undefined && candidate !== null) return candidate;\n  }\n  return undefined;\n}\n\n/**\n * Resolve a single design-property envelope to its render-time value:\n *  - ManualDesignValue → its scalar\n *  - DesignToken       → the envelope passes through (customer-owned resolution)\n *  - ValuesByViewport  → cascade-lookup against the active viewport, then\n *                        unwrap the inner Manual/Token as above\n *  - undefined         → returns undefined\n */\nexport function getValueForViewport(\n  prop: DesignPropValue | undefined,\n  viewports: ViewportDef[],\n  activeViewportIndex: number\n): string | number | boolean | DesignToken | undefined {\n  if (!prop) return undefined;\n  if (prop.type === 'ManualDesignValue') return prop.value;\n  if (prop.type === 'DesignToken') return prop;\n  return unwrapInner(resolveValuesByViewport(prop, viewports, activeViewportIndex));\n}\n\n/**\n * Resolve every design-property envelope on a node into a flat record keyed\n * by property name. Customer components receive these values as plain props.\n */\nexport function resolveDesignProperties(\n  designProperties: Record<string, DesignPropValue> | undefined,\n  viewports: ViewportDef[],\n  activeViewportIndex: number\n): Record<string, string | number | boolean | DesignToken> {\n  const out: Record<string, string | number | boolean | DesignToken> = {};\n  if (!designProperties) return out;\n  for (const [key, prop] of Object.entries(designProperties)) {\n    const value = getValueForViewport(prop, viewports, activeViewportIndex);\n    if (value !== undefined) out[key] = value;\n  }\n  return out;\n}\n\nlet warnedMissingResolver = false;\n\n/**\n * Resolves `DesignToken` envelopes in a viewport-resolved design record via\n * `resolveToken`; scalars pass through, and with no resolver the record is\n * returned unchanged. Keys that resolve to `undefined` are dropped and their\n * token ids collected in `unresolved` for a single grouped warning.\n *\n * When no `resolveToken` is configured but the record contains `DesignToken`\n * envelopes, warns once — those keys reach components as raw envelope objects\n * (e.g. rendering as `[object Object]`), which is almost always a missing-\n * config mistake rather than intent.\n */\nexport function applyTokenResolver(\n  props: Record<string, string | number | boolean | DesignToken>,\n  resolveToken?: ResolveToken\n): { props: Record<string, unknown>; unresolved: string[] } {\n  if (!resolveToken) {\n    if (!warnedMissingResolver && typeof console !== 'undefined') {\n      const tokenKeys = Object.entries(props)\n        .filter(([, v]) => typeof v === 'object' && v !== null && v.type === 'DesignToken')\n        .map(([k]) => k);\n      if (tokenKeys.length) {\n        warnedMissingResolver = true;\n        console.warn(\n          `[@contentful/experiences] Design tokens are present but no \\`resolveToken\\` is configured on the Config; token-valued design props (${tokenKeys.join(', ')}) reach components unresolved. Add \\`resolveToken\\` to your Config to map token ids to values.`\n        );\n      }\n    }\n    return { props, unresolved: [] };\n  }\n  const out: Record<string, unknown> = {};\n  const unresolved: string[] = [];\n  for (const [key, value] of Object.entries(props)) {\n    if (typeof value === 'object' && value !== null && value.type === 'DesignToken') {\n      const resolved = resolveToken(value);\n      if (resolved === undefined) {\n        unresolved.push(value.value);\n        continue;\n      }\n      out[key] = resolved;\n      continue;\n    }\n    out[key] = value;\n  }\n  return { props: out, unresolved };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/viewport.ts"],"sourcesContent":["/*\n * Viewport → CSS media-query translation. The cascade + token-resolution\n * helpers now live in core (so the resolve pipeline can pre-resolve design\n * server-side) and are re-exported here to keep this package's API unchanged.\n */\n\nimport type { ViewportDef } from '@contentful/experiences-sdk-core';\n\nexport {\n  applyTokenResolver,\n  getValueForViewport,\n  getViewportIndex,\n  resolveDesignProperties,\n} from '@contentful/experiences-sdk-core';\n\nconst MEDIA_QUERY_REGEXP = /^(<|>)(\\d+)(px|cm|mm|in|pt|pc)$/;\n\n/**\n * Convert a Contentful viewport `query` string into a CSS media query.\n * Returns `undefined` for the wildcard \"*\" (always matches; no media query needed)\n * or for any unrecognized format.\n */\nexport function toCssMediaQuery(viewport: ViewportDef): string | undefined {\n  const { query } = viewport;\n  if (query === '*') return undefined;\n  const match = query.match(MEDIA_QUERY_REGEXP);\n  if (!match) return undefined;\n  const [, operator, value, unit] = match;\n  if (!operator || !value || !unit) return undefined;\n  if (operator === '<') {\n    return `(max-width: ${Number(value) - 1}${unit})`;\n  }\n  if (operator === '>') {\n    return `(min-width: ${Number(value) + 1}${unit})`;\n  }\n  return undefined;\n}\n"],"mappings":"AAQA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAEP,MAAM,qBAAqB;AAOpB,SAAS,gBAAgB,UAA2C;AACzE,QAAM,EAAE,MAAM,IAAI;AAClB,MAAI,UAAU,IAAK,QAAO;AAC1B,QAAM,QAAQ,MAAM,MAAM,kBAAkB;AAC5C,MAAI,CAAC,MAAO,QAAO;AACnB,QAAM,CAAC,EAAE,UAAU,OAAO,IAAI,IAAI;AAClC,MAAI,CAAC,YAAY,CAAC,SAAS,CAAC,KAAM,QAAO;AACzC,MAAI,aAAa,KAAK;AACpB,WAAO,eAAe,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI;AAAA,EAChD;AACA,MAAI,aAAa,KAAK;AACpB,WAAO,eAAe,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI;AAAA,EAChD;AACA,SAAO;AACT;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentful/experiences-design",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Viewport math and design-property resolution utilities for Contentful Experiences",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,6 @@
     "directory": "packages/design"
   },
   "dependencies": {
-    "@contentful/experiences-sdk-core": "0.7.0"
+    "@contentful/experiences-sdk-core": "0.7.1"
   }
 }