@contentful/experiences-design 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+## 0.5.1 (2026-07-17)
+
+### 🚀 Features
+
+- design-token resolution via resolveToken + useDesignValues [AIS-149] ([#53](https://github.com/contentful/experiences/pull/53))
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.5.1
+
+## 0.5.0 (2026-07-17)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.5.0
+
+## 0.4.0 (2026-07-08)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.4.0
+
+## 0.3.0 (2026-06-24)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.3.0
+
+## 0.2.0 (2026-06-24)
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.2.0
+
+## 0.1.2 (2026-06-24)
+
+### 🩹 Fixes
+
+- **design:** clarify toCssMediaQuery README on unrecognized formats ([54fc9a1](https://github.com/contentful/experiences/commit/54fc9a1))
+
+## 0.1.1 (2026-06-23)
+
+### 🩹 Fixes
+
+- **design:** anchor media-query regex so leading-prefix garbage no longer matches ([1db1619](https://github.com/contentful/experiences/commit/1db1619))
+
+## 0.1.0 (2026-06-23)
+
+### 🚀 Features
+
+- initial Experiences SDK monorepo with React adapter [] ([#16](https://github.com/contentful/experiences/pull/16))
+
+### 🧱 Updated Dependencies
+
+- Updated core to 0.1.0

package/README.md

@@ -0,0 +1,36 @@
+# @contentful/experiences-design
+
+> ⚠️ **Internal package.** Customers do not install this directly. The framework adapter (e.g. [`@contentful/experiences-react`](../adapter-react/)) re-exports the utilities customers need.
+
+Pure, framework-agnostic viewport math for resolving Contentful's `DesignPropValue` envelopes against an active viewport.
+
+## What lives here
+
+- **`toCssMediaQuery(viewport)`** — convert Contentful's media-query DSL (`<992px`, `>1200px`, `*`) to a CSS media query string. The wildcard and any unrecognized format return `undefined`.
+- **`getViewportIndex(viewports, id?)`** — resolve a viewport id to its index in the cascade list.
+- **`getValueForViewport(prop, viewports, activeIdx)`** — unwrap a `DesignPropValue`. `ManualDesignValue` → its scalar; `ValuesByViewport` → cascade-lookup at the active viewport, then unwrap; `DesignToken` → pass the envelope through (customer-resolved in v1).
+- **`resolveDesignProperties(designProps, viewports, activeIdx)`** — apply `getValueForViewport` to every key of a node's design-property bag.
+- **`applyTokenResolver(props, resolveToken?)`** — run a resolved design record through the Config's `resolveToken`. Scalars pass through; `DesignToken` envelopes are resolved, and any that resolve to `undefined` are dropped and reported in `unresolved`. With no resolver the record is returned unchanged — and if it still contains tokens, a one-time console warning fires (they'd otherwise reach components as raw envelope objects).
+- **`toCssKey(key)`** — normalize a design-record key to a candidate CSS property name: strip an optional `cf` prefix and camelCase kebab/snake (`cf-font-size` → `fontSize`).
+- **`isCssProperty(key)` / `CSS_PROPERTIES`** — membership test and the underlying `Set` of CSS property names the adapters' `toCss` will emit.
+
+## `toCss` and the CSS-property whitelist
+
+The adapters' `toCss` helper keeps only keys whose normalized form is in `CSS_PROPERTIES` and **drops everything else** — that's how semantic design values (`variant`, `as`, `ratio`, …) stay out of a style object. The trade-off is that a genuine CSS property missing from the set is dropped silently.
+
+If you hit that:
+
+- **Read the value directly.** The full resolved record is available from `useDesignValues()` / `getDesignValues()`; `toCss` is only a convenience over it, so a key it drops is still readable by name.
+- **Extend the set.** `CSS_PROPERTIES` is exported and mutable (`CSS_PROPERTIES.add('containerType')`) — a key added there flows through `toCss` on the next render.
+
+The list is intentionally curated rather than exhaustive (a full CSS-property warning would misfire on the semantic keys `toCss` is meant to drop). Open a PR to add commonly-needed properties.
+
+## Cascade behavior
+
+Viewport order in the payload encodes cascade direction (desktop-first descending, mobile-first ascending). `getValueForViewport` walks backwards from the active viewport toward `viewports[0]`, returning the first defined value — emulating CSS cascade behavior at runtime.
+
+See [`../../AGENTS.md`](../../AGENTS.md) for the design rationale and multi-framework story.
+
+## License
+
+MIT. See the repository [`LICENSE`](../../LICENSE) and [`NOTICE`](../../NOTICE) for full attribution.

package/dist/css-properties.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Normalize a design-record key to a candidate CSS property name: strip an
+ * optional `cf` prefix and camelCase kebab/snake (`cf-font-size` → `fontSize`).
+ */
+declare function toCssKey(key: string): string;
+/** Whether a normalized key names a CSS property `toCss` will emit. */
+declare function isCssProperty(normalizedKey: string): boolean;
+/**
+ * Whitelist of CSS property names (camelCase) `toCss` emits. Curated, not
+ * exhaustive — `add()` a property here to have `toCss` pass it through.
+ */
+declare const CSS_PROPERTIES: Set<string>;
+
+export { CSS_PROPERTIES, isCssProperty, toCssKey };

package/dist/css-properties.js

@@ -0,0 +1,169 @@
+function toCssKey(key) {
+  const stripped = key.replace(/^cf[-_]?/, "");
+  const base = stripped || key;
+  return base.replace(/[-_]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase()).replace(/^([A-Z])/, (c) => c.toLowerCase());
+}
+function isCssProperty(normalizedKey) {
+  return CSS_PROPERTIES.has(normalizedKey);
+}
+const CSS_PROPERTIES = /* @__PURE__ */ new Set([
+  // Box model / sizing
+  "width",
+  "minWidth",
+  "maxWidth",
+  "height",
+  "minHeight",
+  "maxHeight",
+  "margin",
+  "marginTop",
+  "marginRight",
+  "marginBottom",
+  "marginLeft",
+  "marginBlock",
+  "marginInline",
+  "padding",
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "paddingBlock",
+  "paddingInline",
+  "boxSizing",
+  "aspectRatio",
+  // Positioning / display
+  "display",
+  "position",
+  "top",
+  "right",
+  "bottom",
+  "left",
+  "inset",
+  "zIndex",
+  "overflow",
+  "overflowX",
+  "overflowY",
+  "visibility",
+  "float",
+  "clear",
+  // Flexbox / grid
+  "flex",
+  "flexDirection",
+  "flexWrap",
+  "flexFlow",
+  "flexGrow",
+  "flexShrink",
+  "flexBasis",
+  "justifyContent",
+  "justifyItems",
+  "justifySelf",
+  "alignItems",
+  "alignContent",
+  "alignSelf",
+  "placeItems",
+  "placeContent",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "order",
+  "grid",
+  "gridTemplate",
+  "gridTemplateColumns",
+  "gridTemplateRows",
+  "gridTemplateAreas",
+  "gridColumn",
+  "gridRow",
+  "gridArea",
+  "gridAutoFlow",
+  "gridAutoColumns",
+  "gridAutoRows",
+  // Typography
+  "color",
+  "font",
+  "fontFamily",
+  "fontSize",
+  "fontWeight",
+  "fontStyle",
+  "fontVariant",
+  "lineHeight",
+  "letterSpacing",
+  "wordSpacing",
+  "textAlign",
+  "textAlignLast",
+  "textDecoration",
+  "textDecorationLine",
+  "textDecorationColor",
+  "textDecorationStyle",
+  "textTransform",
+  "textOverflow",
+  "textIndent",
+  "textShadow",
+  "whiteSpace",
+  "wordBreak",
+  "wordWrap",
+  "overflowWrap",
+  "writingMode",
+  "verticalAlign",
+  // Background
+  "background",
+  "backgroundColor",
+  "backgroundImage",
+  "backgroundPosition",
+  "backgroundSize",
+  "backgroundRepeat",
+  "backgroundAttachment",
+  "backgroundClip",
+  "backgroundOrigin",
+  "backgroundBlendMode",
+  // Border / outline
+  "border",
+  "borderWidth",
+  "borderStyle",
+  "borderColor",
+  "borderTop",
+  "borderRight",
+  "borderBottom",
+  "borderLeft",
+  "borderRadius",
+  "borderTopLeftRadius",
+  "borderTopRightRadius",
+  "borderBottomLeftRadius",
+  "borderBottomRightRadius",
+  "outline",
+  "outlineWidth",
+  "outlineStyle",
+  "outlineColor",
+  "outlineOffset",
+  // Effects
+  "opacity",
+  "boxShadow",
+  "filter",
+  "backdropFilter",
+  "mixBlendMode",
+  "transform",
+  "transformOrigin",
+  "transition",
+  "transitionProperty",
+  "transitionDuration",
+  "transitionTimingFunction",
+  "transitionDelay",
+  "animation",
+  "cursor",
+  "pointerEvents",
+  "userSelect",
+  // Misc
+  "content",
+  "listStyle",
+  "listStyleType",
+  "listStylePosition",
+  "objectFit",
+  "objectPosition",
+  "fill",
+  "stroke",
+  "strokeWidth"
+]);
+export {
+  CSS_PROPERTIES,
+  isCssProperty,
+  toCssKey
+};
+//# sourceMappingURL=css-properties.js.map

package/dist/css-properties.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/css-properties.ts"],"sourcesContent":["/**\n * Normalize a design-record key to a candidate CSS property name: strip an\n * optional `cf` prefix and camelCase kebab/snake (`cf-font-size` → `fontSize`).\n */\nexport function toCssKey(key: string): string {\n  const stripped = key.replace(/^cf[-_]?/, '');\n  const base = stripped || key; // `cf` alone → keep original\n  return base\n    .replace(/[-_]+([a-zA-Z0-9])/g, (_, c: string) => c.toUpperCase())\n    .replace(/^([A-Z])/, (c) => c.toLowerCase());\n}\n\n/** Whether a normalized key names a CSS property `toCss` will emit. */\nexport function isCssProperty(normalizedKey: string): boolean {\n  return CSS_PROPERTIES.has(normalizedKey);\n}\n\n/**\n * Whitelist of CSS property names (camelCase) `toCss` emits. Curated, not\n * exhaustive — `add()` a property here to have `toCss` pass it through.\n */\nexport const CSS_PROPERTIES: Set<string> = new Set([\n  // Box model / sizing\n  'width',\n  'minWidth',\n  'maxWidth',\n  'height',\n  'minHeight',\n  'maxHeight',\n  'margin',\n  'marginTop',\n  'marginRight',\n  'marginBottom',\n  'marginLeft',\n  'marginBlock',\n  'marginInline',\n  'padding',\n  'paddingTop',\n  'paddingRight',\n  'paddingBottom',\n  'paddingLeft',\n  'paddingBlock',\n  'paddingInline',\n  'boxSizing',\n  'aspectRatio',\n  // Positioning / display\n  'display',\n  'position',\n  'top',\n  'right',\n  'bottom',\n  'left',\n  'inset',\n  'zIndex',\n  'overflow',\n  'overflowX',\n  'overflowY',\n  'visibility',\n  'float',\n  'clear',\n  // Flexbox / grid\n  'flex',\n  'flexDirection',\n  'flexWrap',\n  'flexFlow',\n  'flexGrow',\n  'flexShrink',\n  'flexBasis',\n  'justifyContent',\n  'justifyItems',\n  'justifySelf',\n  'alignItems',\n  'alignContent',\n  'alignSelf',\n  'placeItems',\n  'placeContent',\n  'gap',\n  'rowGap',\n  'columnGap',\n  'order',\n  'grid',\n  'gridTemplate',\n  'gridTemplateColumns',\n  'gridTemplateRows',\n  'gridTemplateAreas',\n  'gridColumn',\n  'gridRow',\n  'gridArea',\n  'gridAutoFlow',\n  'gridAutoColumns',\n  'gridAutoRows',\n  // Typography\n  'color',\n  'font',\n  'fontFamily',\n  'fontSize',\n  'fontWeight',\n  'fontStyle',\n  'fontVariant',\n  'lineHeight',\n  'letterSpacing',\n  'wordSpacing',\n  'textAlign',\n  'textAlignLast',\n  'textDecoration',\n  'textDecorationLine',\n  'textDecorationColor',\n  'textDecorationStyle',\n  'textTransform',\n  'textOverflow',\n  'textIndent',\n  'textShadow',\n  'whiteSpace',\n  'wordBreak',\n  'wordWrap',\n  'overflowWrap',\n  'writingMode',\n  'verticalAlign',\n  // Background\n  'background',\n  'backgroundColor',\n  'backgroundImage',\n  'backgroundPosition',\n  'backgroundSize',\n  'backgroundRepeat',\n  'backgroundAttachment',\n  'backgroundClip',\n  'backgroundOrigin',\n  'backgroundBlendMode',\n  // Border / outline\n  'border',\n  'borderWidth',\n  'borderStyle',\n  'borderColor',\n  'borderTop',\n  'borderRight',\n  'borderBottom',\n  'borderLeft',\n  'borderRadius',\n  'borderTopLeftRadius',\n  'borderTopRightRadius',\n  'borderBottomLeftRadius',\n  'borderBottomRightRadius',\n  'outline',\n  'outlineWidth',\n  'outlineStyle',\n  'outlineColor',\n  'outlineOffset',\n  // Effects\n  'opacity',\n  'boxShadow',\n  'filter',\n  'backdropFilter',\n  'mixBlendMode',\n  'transform',\n  'transformOrigin',\n  'transition',\n  'transitionProperty',\n  'transitionDuration',\n  'transitionTimingFunction',\n  'transitionDelay',\n  'animation',\n  'cursor',\n  'pointerEvents',\n  'userSelect',\n  // Misc\n  'content',\n  'listStyle',\n  'listStyleType',\n  'listStylePosition',\n  'objectFit',\n  'objectPosition',\n  'fill',\n  'stroke',\n  'strokeWidth',\n]);\n"],"mappings":"AAIO,SAAS,SAAS,KAAqB;AAC5C,QAAM,WAAW,IAAI,QAAQ,YAAY,EAAE;AAC3C,QAAM,OAAO,YAAY;AACzB,SAAO,KACJ,QAAQ,uBAAuB,CAAC,GAAG,MAAc,EAAE,YAAY,CAAC,EAChE,QAAQ,YAAY,CAAC,MAAM,EAAE,YAAY,CAAC;AAC/C;AAGO,SAAS,cAAc,eAAgC;AAC5D,SAAO,eAAe,IAAI,aAAa;AACzC;AAMO,MAAM,iBAA8B,oBAAI,IAAI;AAAA;AAAA,EAEjD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA;AAAA,EAEA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;","names":[]}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,19 @@
+import {
+  applyTokenResolver,
+  getValueForViewport,
+  getViewportIndex,
+  resolveDesignProperties,
+  toCssMediaQuery
+} from "./viewport";
+import { CSS_PROPERTIES, isCssProperty, toCssKey } from "./css-properties";
+export {
+  CSS_PROPERTIES,
+  applyTokenResolver,
+  getValueForViewport,
+  getViewportIndex,
+  isCssProperty,
+  resolveDesignProperties,
+  toCssKey,
+  toCssMediaQuery
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export {\n  applyTokenResolver,\n  getValueForViewport,\n  getViewportIndex,\n  resolveDesignProperties,\n  toCssMediaQuery,\n} from './viewport';\nexport { CSS_PROPERTIES, isCssProperty, toCssKey } from './css-properties';\n"],"mappings":"AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,gBAAgB,eAAe,gBAAgB;","names":[]}

package/dist/viewport.d.ts

@@ -0,0 +1,44 @@
+import { DesignToken, ResolveToken, DesignPropValue, ViewportDef } from '@contentful/experiences-core';
+
+/**
+ * Convert a Contentful viewport `query` string into a CSS media query.
+ * Returns `undefined` for the wildcard "*" (always matches; no media query needed)
+ * 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 };

package/dist/viewport.js

@@ -0,0 +1,88 @@
+const MEDIA_QUERY_REGEXP = /^(<|>)(\d+)(px|cm|mm|in|pt|pc)$/;
+function toCssMediaQuery(viewport) {
+  const { query } = viewport;
+  if (query === "*") return void 0;
+  const match = query.match(MEDIA_QUERY_REGEXP);
+  if (!match) return void 0;
+  const [, operator, value, unit] = match;
+  if (!operator || !value || !unit) return void 0;
+  if (operator === "<") {
+    return `(max-width: ${Number(value) - 1}${unit})`;
+  }
+  if (operator === ">") {
+    return `(min-width: ${Number(value) + 1}${unit})`;
+  }
+  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,
+  getViewportIndex,
+  resolveDesignProperties,
+  toCssMediaQuery
+};
+//# sourceMappingURL=viewport.js.map

package/dist/viewport.js.map

@@ -0,0 +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-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":[]}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@contentful/experiences-design",
+  "version": "0.5.1",
+  "description": "Viewport math and design-property resolution utilities for Contentful Experiences",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/contentful/experiences.git",
+    "directory": "packages/design"
+  },
+  "dependencies": {
+    "@contentful/experiences-core": "0.5.1"
+  }
+}