@contentstack/studio-registry 1.9.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3948,6 +3948,7 @@ function processRegistryOptions(userConfig, options) {
3948
3948
  if (userConfig.thumbnailUrl) {
3949
3949
  defaultOptions.thumbnailUrl = userConfig.thumbnailUrl;
3950
3950
  }
3951
+ validateDesignProps(userConfig.type, defaultOptions.props, userConfig.styles);
3951
3952
  if (userConfig.styles) {
3952
3953
  defaultOptions.styles = processRegistryOptionsStylesOptions(userConfig.styles);
3953
3954
  }
@@ -4082,6 +4083,79 @@ function processRegistryOptionsProps(props) {
4082
4083
  validateSlotCountPropLinkages(props, processedProps);
4083
4084
  return { props: processedProps, validators: propValidators };
4084
4085
  }
4086
+ /** Prop types that may carry the `design` flag. */
4087
+ const DESIGN_PROP_TYPES = new Set(["choice", "string"]);
4088
+ /**
4089
+ * Keys a design prop must never use: `default` is consumed as the component's
4090
+ * `className` by `handleNodeStyles`, and the rest would collide with React /
4091
+ * renderer-owned props when the generated class is spread onto the component.
4092
+ */
4093
+ const DESIGN_PROP_RESERVED_KEYS = new Set([
4094
+ "default",
4095
+ "className",
4096
+ "children",
4097
+ "style",
4098
+ "key",
4099
+ "ref",
4100
+ ]);
4101
+ /**
4102
+ * Design props are style groups in disguise: the renderer spreads
4103
+ * `node.styles[key]`'s generated class onto the component under the prop key.
4104
+ * A key that is not a CSS property, is reserved, collides with a registered
4105
+ * style group, or sits on an unsupported prop type would either style nothing
4106
+ * or clobber another prop — so the flag is stripped with a warning
4107
+ * (registry convention: warn, don't throw).
4108
+ *
4109
+ * CSS-property check: only the camelCase SHAPE is enforced (strip-worthy) —
4110
+ * DOM-based existence checks differ across browsers/test environments, and an
4111
+ * unknown-but-css-shaped key merely emits a no-op CSS declaration, which is
4112
+ * safe. When a DOM is available and doesn't know the property, an advisory
4113
+ * warning is logged without stripping the flag.
4114
+ */
4115
+ function validateDesignProps(componentType, processedProps, stylesInput) {
4116
+ const styleGroupKeys = new Set(Object.keys(stylesInput ?? {}));
4117
+ for (const [field, prop] of Object.entries(processedProps)) {
4118
+ if (!("design" in prop) || !prop.design)
4119
+ continue;
4120
+ const strip = (reason) => {
4121
+ console.warn(`[studio] Ignoring \`design: true\` on prop "${field}" of component "${componentType}": ${reason}`);
4122
+ delete prop.design;
4123
+ };
4124
+ if (!DESIGN_PROP_TYPES.has(prop.type)) {
4125
+ strip(`type "${prop.type}" is not supported (allowed: ${[...DESIGN_PROP_TYPES].join(", ")}).`);
4126
+ }
4127
+ else if (DESIGN_PROP_RESERVED_KEYS.has(field)) {
4128
+ strip(`"${field}" is a reserved key.`);
4129
+ }
4130
+ else if (styleGroupKeys.has(field)) {
4131
+ strip(`"${field}" collides with a registered style group.`);
4132
+ }
4133
+ else if (!CAMEL_CASE_CSS_KEY.test(field)) {
4134
+ strip(`"${field}" is not a camelCase CSS property.`);
4135
+ }
4136
+ else if (!isKnownCssPropertyInDom(field)) {
4137
+ console.warn(`[studio] Design prop "${field}" of component "${componentType}" does not match a known CSS property in this browser — its values will emit a no-op declaration.`);
4138
+ }
4139
+ }
4140
+ }
4141
+ const CAMEL_CASE_CSS_KEY = /^[a-z][a-zA-Z]*$/;
4142
+ /** Best-effort DOM probe; returns true when no reliable DOM is available. */
4143
+ function isKnownCssPropertyInDom(key) {
4144
+ if (typeof document === "undefined" || !document.createElement)
4145
+ return true;
4146
+ try {
4147
+ const style = document.createElement("div").style;
4148
+ if (key in style)
4149
+ return true;
4150
+ // Some DOM implementations only accept kebab-case via setProperty.
4151
+ const kebab = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
4152
+ style.setProperty(kebab, "unset");
4153
+ return style.getPropertyValue(kebab) !== "";
4154
+ }
4155
+ catch {
4156
+ return true;
4157
+ }
4158
+ }
4085
4159
  /**
4086
4160
  * The editor stores a single-select choice value as a `string[]` (and the SDK unwraps
4087
4161
  * it to a scalar on render). Authors may write a single-select `defaultValue` as a
@@ -5882,7 +5956,22 @@ function isKnownType(type) {
5882
5956
  }
5883
5957
  function getSlotData({ nodeProps, field, node, getSlots, }) {
5884
5958
  const currentNodeProp = nodeProps[field];
5885
- const slotUid = currentNodeProp?.slot;
5959
+ // The slot key normally rides on the node's own prop (`props.children.slot`),
5960
+ // which Studio's editor writes when it authors a container. A composition
5961
+ // authored through the CMA routinely omits it — the children are already in
5962
+ // `node.slots[field]`, so the prop looks redundant.
5963
+ //
5964
+ // Without a fallback that omission renders NOTHING, silently: no throw, no
5965
+ // warning, and the parent still renders its own wrapper, so the page looks
5966
+ // "built but empty" and the cause is invisible. Measured end-to-end: a
5967
+ // page > section-composition > box > header/plain-text tree resolved
5968
+ // correctly at every layer — CDA, spec, registry, static_value — and emitted
5969
+ // a single empty <div>.
5970
+ //
5971
+ // `node.slots[field]` is the same key the component definition declares the
5972
+ // slot under, so falling back to `field` is the author's evident intent and
5973
+ // matches what the editor would have written.
5974
+ const slotUid = currentNodeProp?.slot ?? (node.slots?.[field] ? field : undefined);
5886
5975
  if (!slotUid) {
5887
5976
  return null;
5888
5977
  }
@@ -6078,6 +6167,14 @@ function retrievePropValue(args) {
6078
6167
  if (!isKnownType(type)) {
6079
6168
  return;
6080
6169
  }
6170
+ // Design props never resolve to a data value: their generated class is
6171
+ // spread onto the component from `node.styles[field]` BEFORE resolved
6172
+ // props, so emitting anything here (even the registration defaultValue)
6173
+ // would clobber that class. See studio-registry design-prop validation
6174
+ // and docs/adr/0003.
6175
+ if ("design" in prop && prop.design) {
6176
+ return;
6177
+ }
6081
6178
  let resolvedData;
6082
6179
  // When the value is resolved via the `dataSources.page.*` fallback below,
6083
6180
  // the CSLP tag must come from the SAME page path (not the section-local