@contentstack/studio-registry 1.8.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.
Files changed (37) hide show
  1. package/dist/cjs/index.cjs +1096 -202
  2. package/dist/cjs/index.cjs.map +1 -1
  3. package/dist/esm/common/global-store.js +2 -0
  4. package/dist/esm/common/global-store.js.map +1 -1
  5. package/dist/esm/component-registry/registry-options-processor.js +75 -0
  6. package/dist/esm/component-registry/registry-options-processor.js.map +1 -1
  7. package/dist/esm/component-registry/registry.constant.js +0 -3
  8. package/dist/esm/component-registry/registry.constant.js.map +1 -1
  9. package/dist/esm/component-registry/registry.js +1 -27
  10. package/dist/esm/component-registry/registry.js.map +1 -1
  11. package/dist/esm/data-binder/cslp.js +8 -1
  12. package/dist/esm/data-binder/cslp.js.map +1 -1
  13. package/dist/esm/data-binder/retrieve-data.js +19 -32
  14. package/dist/esm/data-binder/retrieve-data.js.map +1 -1
  15. package/dist/esm/data-binder/retrieve-data.util.js +23 -5
  16. package/dist/esm/data-binder/retrieve-data.util.js.map +1 -1
  17. package/dist/esm/data-binder/state-binding.util.js +158 -0
  18. package/dist/esm/data-binder/state-binding.util.js.map +1 -0
  19. package/dist/esm/design-registry/design-token.js +5 -2
  20. package/dist/esm/design-registry/design-token.js.map +1 -1
  21. package/dist/esm/index.d.ts +488 -27
  22. package/dist/esm/index.js +6 -1
  23. package/dist/esm/index.js.map +1 -1
  24. package/dist/esm/state-store/action-props.util.js +42 -0
  25. package/dist/esm/state-store/action-props.util.js.map +1 -0
  26. package/dist/esm/state-store/function-registry.js +128 -0
  27. package/dist/esm/state-store/function-registry.js.map +1 -0
  28. package/dist/esm/state-store/public-api.js +109 -0
  29. package/dist/esm/state-store/public-api.js.map +1 -0
  30. package/dist/esm/state-store/singleton.js +27 -0
  31. package/dist/esm/state-store/singleton.js.map +1 -0
  32. package/dist/esm/state-store/state-store.js +384 -0
  33. package/dist/esm/state-store/state-store.js.map +1 -0
  34. package/package.json +9 -6
  35. package/LICENSE +0 -21
  36. package/dist/esm/utils/symbols.js +0 -12
  37. package/dist/esm/utils/symbols.js.map +0 -1
@@ -57,140 +57,6 @@ function getRegistryErrorMessage(key, params) {
57
57
  return template;
58
58
  }
59
59
 
60
- const DATA_SOURCES_PREFIX = "dataSources";
61
- const DATA_SOURCES = {
62
- COMPONENT_PROPS: "component_props",
63
- STATIC_VALUE: "static_value",
64
- TEMPLATE: "template",
65
- CONTENTSTACK: "contentstack",
66
- REPEATER: "repeater",
67
- QUERY: "contentstack_queries",
68
- SYMBOL_PROPS: "symbol_props",
69
- };
70
- const INTERNAL_COMPONENT_SECTIONS = {
71
- BASIC: "Basic",
72
- MEDIA: "Media",
73
- CONTAINER: "Container",
74
- SMART_CONTAINER: "Smart Containers",
75
- ADVANCED: "Advanced",
76
- REGISTERED_COMPONENTS: "Registered Components",
77
- HTML_ELEMENT: "HTML Elements",
78
- SYMBOL: "Symbols",
79
- SECTION_COMPOSITION: "Sections",
80
- };
81
- const INTERNAL_SECTIONS = Object.values(INTERNAL_COMPONENT_SECTIONS);
82
- const STYLE_SECTIONS_OPTIONS = [
83
- "class",
84
- "size",
85
- "spacing",
86
- "position",
87
- "visibility",
88
- "layout",
89
- "typography",
90
- "transform",
91
- "media",
92
- "background",
93
- "shadow",
94
- "effect",
95
- "overflow",
96
- "border",
97
- "responsive",
98
- ];
99
- /**
100
- * The style group is the group of the style sections options.
101
- * When a style group is selected, all the styles
102
- * corresponding to it will be extracted from the
103
- */
104
- const STYLE_SECTION_CATEGORIES = {
105
- block: [
106
- "class",
107
- "size",
108
- "spacing",
109
- "position",
110
- "visibility",
111
- "layout",
112
- "background",
113
- "shadow",
114
- "effect",
115
- "overflow",
116
- "border",
117
- "responsive",
118
- ],
119
- text: ["typography"],
120
- };
121
- const INTERNAL_COMPONENTS_NAMES = {
122
- // * System
123
- PAGE: "page",
124
- // * Basic
125
- HEADER: "header",
126
- LINK: "link",
127
- LINK_CONTAINER: "link-container",
128
- TEXT: "text",
129
- NUMBER: "number",
130
- BUTTON: "button",
131
- JSON_RTE: "json-rte",
132
- COLLAPSIBLE_TEXT: "collapsible-text",
133
- PLAIN_TEXT: "plain-text",
134
- RICH_TEXT: "rich-text",
135
- // * Media
136
- VIDEO: "video",
137
- EMBED: "embed",
138
- IMAGE: "image",
139
- // * Container
140
- SECTION: "section",
141
- BOX: "box",
142
- COLUMNS: "hstack",
143
- ROWS: "vstack",
144
- REPEATER: "repeater",
145
- CONDITION_BLOCK: "condition-block",
146
- SYMBOL: "symbol",
147
- FRAGMENT: "fragment",
148
- // Exposed-slot placeholder authored inside a section composition. When the
149
- // section is dropped into a page, each section-slot becomes a fill point
150
- // the page composer can drop arbitrary components into.
151
- SECTION_SLOT: "section-slot",
152
- // * HTML Elements
153
- HTML_ELEMENT: "html-element",
154
- STYLE_SHEET: "style-sheet",
155
- };
156
- /**
157
- * System components are protected components that are not intended to be modified or removed.
158
- */
159
- const SYSTEM_COMPONENTS = /* #__PURE__ */ new Set(Object.values([INTERNAL_COMPONENTS_NAMES.PAGE]));
160
- /**
161
- * Built-in components are components that are included in the component registry by default.
162
- * User can opt-out of including these components in the registry by setting the
163
- * `includeBuiltInComponents` option to `false`.
164
- */
165
- const BUILT_IN_COMPONENTS = {
166
- // * Basic
167
- HEADER: "header",
168
- LINK: "link",
169
- LINK_CONTAINER: "link-container",
170
- TEXT: "text",
171
- NUMBER: "number",
172
- BUTTON: "button",
173
- JSON_RTE: "json-rte",
174
- COLLAPSIBLE_TEXT: "collapsible-text",
175
- // * Media
176
- VIDEO: "video",
177
- EMBED: "embed",
178
- IMAGE: "image",
179
- // * Container
180
- SECTION: "section",
181
- BOX: "box",
182
- COLUMNS: "hstack",
183
- ROWS: "vstack",
184
- };
185
-
186
- const getSymbolUIDFromNode = (symbol) => {
187
- const symbolUID = symbol.metadata?.symbolUID;
188
- return `${INTERNAL_COMPONENTS_NAMES.SYMBOL}-${symbolUID}`;
189
- };
190
- const getSymbolUIDFromUID = (uid) => {
191
- return `${INTERNAL_COMPONENTS_NAMES.SYMBOL}-${uid}`;
192
- };
193
-
194
60
  /**
195
61
  * Extracts the composition UID from a section-composition node's metadata.
196
62
  * Used to resolve section references to their actual composition identifiers.
@@ -3895,6 +3761,129 @@ var snakeCase = createCompounder(function(result, word, index) {
3895
3761
  return result + (index ? '_' : '') + word.toLowerCase();
3896
3762
  });
3897
3763
 
3764
+ const DATA_SOURCES_PREFIX = "dataSources";
3765
+ const DATA_SOURCES = {
3766
+ COMPONENT_PROPS: "component_props",
3767
+ STATIC_VALUE: "static_value",
3768
+ TEMPLATE: "template",
3769
+ CONTENTSTACK: "contentstack",
3770
+ REPEATER: "repeater",
3771
+ QUERY: "contentstack_queries",
3772
+ };
3773
+ const INTERNAL_COMPONENT_SECTIONS = {
3774
+ BASIC: "Basic",
3775
+ MEDIA: "Media",
3776
+ CONTAINER: "Container",
3777
+ SMART_CONTAINER: "Smart Containers",
3778
+ ADVANCED: "Advanced",
3779
+ REGISTERED_COMPONENTS: "Registered Components",
3780
+ HTML_ELEMENT: "HTML Elements",
3781
+ SECTION_COMPOSITION: "Sections",
3782
+ };
3783
+ const INTERNAL_SECTIONS = Object.values(INTERNAL_COMPONENT_SECTIONS);
3784
+ const STYLE_SECTIONS_OPTIONS = [
3785
+ "class",
3786
+ "size",
3787
+ "spacing",
3788
+ "position",
3789
+ "visibility",
3790
+ "layout",
3791
+ "typography",
3792
+ "transform",
3793
+ "media",
3794
+ "background",
3795
+ "shadow",
3796
+ "effect",
3797
+ "overflow",
3798
+ "border",
3799
+ "responsive",
3800
+ ];
3801
+ /**
3802
+ * The style group is the group of the style sections options.
3803
+ * When a style group is selected, all the styles
3804
+ * corresponding to it will be extracted from the
3805
+ */
3806
+ const STYLE_SECTION_CATEGORIES = {
3807
+ block: [
3808
+ "class",
3809
+ "size",
3810
+ "spacing",
3811
+ "position",
3812
+ "visibility",
3813
+ "layout",
3814
+ "background",
3815
+ "shadow",
3816
+ "effect",
3817
+ "overflow",
3818
+ "border",
3819
+ "responsive",
3820
+ ],
3821
+ text: ["typography"],
3822
+ };
3823
+ const INTERNAL_COMPONENTS_NAMES = {
3824
+ // * System
3825
+ PAGE: "page",
3826
+ // * Basic
3827
+ HEADER: "header",
3828
+ LINK: "link",
3829
+ LINK_CONTAINER: "link-container",
3830
+ TEXT: "text",
3831
+ NUMBER: "number",
3832
+ BUTTON: "button",
3833
+ JSON_RTE: "json-rte",
3834
+ COLLAPSIBLE_TEXT: "collapsible-text",
3835
+ PLAIN_TEXT: "plain-text",
3836
+ RICH_TEXT: "rich-text",
3837
+ // * Media
3838
+ VIDEO: "video",
3839
+ EMBED: "embed",
3840
+ IMAGE: "image",
3841
+ // * Container
3842
+ SECTION: "section",
3843
+ BOX: "box",
3844
+ COLUMNS: "hstack",
3845
+ ROWS: "vstack",
3846
+ REPEATER: "repeater",
3847
+ CONDITION_BLOCK: "condition-block",
3848
+ FRAGMENT: "fragment",
3849
+ // Exposed-slot placeholder authored inside a section composition. When the
3850
+ // section is dropped into a page, each section-slot becomes a fill point
3851
+ // the page composer can drop arbitrary components into.
3852
+ SECTION_SLOT: "section-slot",
3853
+ // * HTML Elements
3854
+ HTML_ELEMENT: "html-element",
3855
+ STYLE_SHEET: "style-sheet",
3856
+ };
3857
+ /**
3858
+ * System components are protected components that are not intended to be modified or removed.
3859
+ */
3860
+ const SYSTEM_COMPONENTS = /* #__PURE__ */ new Set(Object.values([INTERNAL_COMPONENTS_NAMES.PAGE]));
3861
+ /**
3862
+ * Built-in components are components that are included in the component registry by default.
3863
+ * User can opt-out of including these components in the registry by setting the
3864
+ * `includeBuiltInComponents` option to `false`.
3865
+ */
3866
+ const BUILT_IN_COMPONENTS = {
3867
+ // * Basic
3868
+ HEADER: "header",
3869
+ LINK: "link",
3870
+ LINK_CONTAINER: "link-container",
3871
+ TEXT: "text",
3872
+ NUMBER: "number",
3873
+ BUTTON: "button",
3874
+ JSON_RTE: "json-rte",
3875
+ COLLAPSIBLE_TEXT: "collapsible-text",
3876
+ // * Media
3877
+ VIDEO: "video",
3878
+ EMBED: "embed",
3879
+ IMAGE: "image",
3880
+ // * Container
3881
+ SECTION: "section",
3882
+ BOX: "box",
3883
+ COLUMNS: "hstack",
3884
+ ROWS: "vstack",
3885
+ };
3886
+
3898
3887
  function getDefaultComponentSchemaInput(options) {
3899
3888
  return {
3900
3889
  component: options.component,
@@ -3959,6 +3948,7 @@ function processRegistryOptions(userConfig, options) {
3959
3948
  if (userConfig.thumbnailUrl) {
3960
3949
  defaultOptions.thumbnailUrl = userConfig.thumbnailUrl;
3961
3950
  }
3951
+ validateDesignProps(userConfig.type, defaultOptions.props, userConfig.styles);
3962
3952
  if (userConfig.styles) {
3963
3953
  defaultOptions.styles = processRegistryOptionsStylesOptions(userConfig.styles);
3964
3954
  }
@@ -4093,6 +4083,79 @@ function processRegistryOptionsProps(props) {
4093
4083
  validateSlotCountPropLinkages(props, processedProps);
4094
4084
  return { props: processedProps, validators: propValidators };
4095
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
+ }
4096
4159
  /**
4097
4160
  * The editor stores a single-select choice value as a `string[]` (and the SDK unwraps
4098
4161
  * it to a scalar on render). Authors may write a single-select `defaultValue` as a
@@ -4118,6 +4181,7 @@ function getExpandedPropTypes(prop) {
4118
4181
  href: { type: "href" },
4119
4182
  imageurl: { type: "imageurl" },
4120
4183
  slot: { type: "slot" },
4184
+ action: { type: "action" },
4121
4185
  };
4122
4186
  return propTypeMapping[prop];
4123
4187
  }
@@ -4240,7 +4304,6 @@ class ComponentRegistry {
4240
4304
  this.componentRegistry.forEach((componentConfig) => {
4241
4305
  if (!updatedConfig.some((c) => c.type === componentConfig.type)) {
4242
4306
  if (SYSTEM_COMPONENTS.has(componentConfig.type) ||
4243
- componentConfig.metadata?.type === "symbol" ||
4244
4307
  componentConfig.metadata?.type === "section-composition") {
4245
4308
  return;
4246
4309
  }
@@ -4314,23 +4377,6 @@ class ComponentRegistry {
4314
4377
  this.propValidatorRegistry.set(type, propValidators);
4315
4378
  });
4316
4379
  }
4317
- /**
4318
- * Registers list of symbol components in the component registry
4319
- * @param componentsConfigs
4320
- */
4321
- registerSymbolComponent(componentsConfigs) {
4322
- componentsConfigs.forEach((componentConfig) => {
4323
- // ComponentConfig.name for symbols are UID we are prefixing it with INTERNAL_COMPONENTS_NAMES.SYMBOL
4324
- componentConfig["type"] = getSymbolUIDFromUID(componentConfig.type);
4325
- const { type } = componentConfig;
4326
- componentConfig["sections"] = [INTERNAL_COMPONENT_SECTIONS.SYMBOL];
4327
- // TODO: Check if this works for symbol components
4328
- const { processedOptions } = processRegistryOptions(componentConfig, {
4329
- registry: "symbols",
4330
- });
4331
- this.componentRegistry.set(type, processedOptions);
4332
- });
4333
- }
4334
4380
  registerSectionComponent(componentsConfigs) {
4335
4381
  componentsConfigs.forEach((componentConfig) => {
4336
4382
  const { type } = componentConfig;
@@ -4339,7 +4385,7 @@ class ComponentRegistry {
4339
4385
  ];
4340
4386
  componentConfig["hideFromComponentList"] = true;
4341
4387
  const { processedOptions } = processRegistryOptions(componentConfig, {
4342
- registry: "symbols",
4388
+ registry: "sections",
4343
4389
  });
4344
4390
  this.componentRegistry.set(type, processedOptions);
4345
4391
  });
@@ -4498,13 +4544,6 @@ class ComponentRegistry {
4498
4544
  }
4499
4545
  getComponentName(node) {
4500
4546
  const { type } = node;
4501
- if (type === "symbol") {
4502
- // If node is under editing mode return symbol to be rendered by symbol component
4503
- if (Object.keys(node.slots).length > 0) {
4504
- return type;
4505
- }
4506
- return getSymbolUIDFromNode(node);
4507
- }
4508
4547
  if (type === "section-composition") {
4509
4548
  const resolvedName = getSectionUIDFromNode(node) || type;
4510
4549
  return resolvedName;
@@ -4689,6 +4728,8 @@ function getGlobalStudioStore() {
4689
4728
  componentRegistry: null,
4690
4729
  designRegistry: null,
4691
4730
  breakpointManager: null,
4731
+ stateStore: null,
4732
+ functionRegistry: null,
4692
4733
  };
4693
4734
  }
4694
4735
  return g[GLOBAL_STORE_KEY];
@@ -5409,8 +5450,9 @@ function processDesignTokensOptions(options = {}) {
5409
5450
  return defaultOptions;
5410
5451
  }
5411
5452
  function processAllowedDesignValues(allowedValues) {
5453
+ // Keep this fallback in agreement with getDefaultDesignTokensOptions().
5412
5454
  if (!allowedValues)
5413
- return ALLOWED_DESIGN_VALUES_LEVELS.DYNAMIC;
5455
+ return ALLOWED_DESIGN_VALUES_LEVELS.ARBITRARY;
5414
5456
  switch (allowedValues) {
5415
5457
  case "dynamic":
5416
5458
  return ALLOWED_DESIGN_VALUES_LEVELS.DYNAMIC;
@@ -5483,7 +5525,9 @@ function getDefaultDesignTokens() {
5483
5525
  function getDefaultDesignTokensOptions() {
5484
5526
  return {
5485
5527
  allowDefaultDesignTokens: true,
5486
- allowedValuesLevel: ALLOWED_DESIGN_VALUES_LEVELS.DYNAMIC,
5528
+ // Default to the most permissive level: Studio is powerful out of the box
5529
+ // and design governance is opt-in (a site sets a lower level to lock down).
5530
+ allowedValuesLevel: ALLOWED_DESIGN_VALUES_LEVELS.ARBITRARY,
5487
5531
  };
5488
5532
  }
5489
5533
  function getDefaultGlobalDesignTokens() {
@@ -5640,7 +5684,14 @@ function getCslpPath(binding) {
5640
5684
  }
5641
5685
  const bindingParts = binding.split(".");
5642
5686
  const lastPart = bindingParts.pop();
5643
- const cslpPath = bindingParts.join(".") + ".$." + lastPart;
5687
+ // A TOP-LEVEL binding ("modular_blocks") has no parent parts, so joining them
5688
+ // yields "" and naive concatenation produces a LEADING DOT (".$.modular_blocks").
5689
+ // lodash `get` reads that as an empty first key and resolves to undefined, so the
5690
+ // edit tag silently goes missing for every top-level field — while nested
5691
+ // bindings ("cards.card" → "cards.$.card") resolve fine. Anchor at "$." instead.
5692
+ const cslpPath = bindingParts.length
5693
+ ? `${bindingParts.join(".")}.$.${lastPart}`
5694
+ : `$.${lastPart}`;
5644
5695
  return cslpPath;
5645
5696
  }
5646
5697
  //TODO: Move it to more appropriate place
@@ -5877,6 +5928,7 @@ function getDefaultPropStaticValue(args) {
5877
5928
  any: "",
5878
5929
  json_rte: {},
5879
5930
  plaintext: "",
5931
+ action: "",
5880
5932
  };
5881
5933
  if (args) {
5882
5934
  return defaultValues[args];
@@ -5898,12 +5950,28 @@ function isKnownType(type) {
5898
5950
  any: true,
5899
5951
  json_rte: true,
5900
5952
  plaintext: true,
5953
+ action: true,
5901
5954
  };
5902
5955
  return Object.keys(knownTypes).includes(type);
5903
5956
  }
5904
5957
  function getSlotData({ nodeProps, field, node, getSlots, }) {
5905
5958
  const currentNodeProp = nodeProps[field];
5906
- 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);
5907
5975
  if (!slotUid) {
5908
5976
  return null;
5909
5977
  }
@@ -5939,9 +6007,6 @@ registry.register(DATA_SOURCES.COMPONENT_PROPS, {
5939
6007
  registry.register(DATA_SOURCES.STATIC_VALUE, {
5940
6008
  getBindingString: (binding) => [DATA_SOURCES.STATIC_VALUE, binding.value].filter(Boolean).join("."),
5941
6009
  });
5942
- registry.register(DATA_SOURCES.SYMBOL_PROPS, {
5943
- getBindingString: (binding) => [DATA_SOURCES.SYMBOL_PROPS, binding.value].filter(Boolean).join("."),
5944
- });
5945
6010
  const getBindingString = (binding) => {
5946
6011
  const strategy = DataSourceStrategyRegistry.getInstance().get(binding.type);
5947
6012
  if (strategy) {
@@ -6017,11 +6082,15 @@ function isDataMatchingPropType(data, type) {
6017
6082
  href: dataType === "string",
6018
6083
  imageurl: dataType === "string",
6019
6084
  datestring: dataType === "string",
6020
- json_rte: dataType === "object",
6085
+ // object = JSON RTE document; string = HTML RTE / Markdown
6086
+ json_rte: dataType === "object" || dataType === "string",
6021
6087
  // "any" accepts all data types — no validation
6022
6088
  any: true,
6023
6089
  // "plaintext" accepts singleline/multiline text, number, and boolean fields
6024
6090
  plaintext: dataType === "string" || dataType === "number" || dataType === "boolean",
6091
+ // "action" stores a registered function NAME; the renderer later swaps it
6092
+ // for a callable, so post-wrap re-validation must accept functions too.
6093
+ action: dataType === "string" || dataType === "function",
6025
6094
  };
6026
6095
  return map[type] ?? false;
6027
6096
  }
@@ -6088,21 +6157,7 @@ function clearReportedBindingErrorsForNode(nodeUid) {
6088
6157
  // Responsible for resolving props to values
6089
6158
  function retrievePropValue(args) {
6090
6159
  const { data, componentOptions, node, cslp, placeholders = {}, getSlots, jsonRTE, isCompositionBeingEdited, } = args;
6091
- const componentProps = (function getComponentProps() {
6092
- // Only resolve props when in editing mode
6093
- if (node.type === "symbol" && node.metadata.editing) {
6094
- const props = {
6095
- ...componentOptions.props,
6096
- };
6097
- const symbolProps = node.metadata.symbolProps || [];
6098
- for (const symbolProp of symbolProps) {
6099
- const { uid } = symbolProp;
6100
- props[uid] = symbolProp;
6101
- }
6102
- return props;
6103
- }
6104
- return componentOptions.props;
6105
- })();
6160
+ const componentProps = componentOptions.props;
6106
6161
  const nodeProps = node.props;
6107
6162
  if (!componentProps || !nodeProps)
6108
6163
  return {};
@@ -6112,6 +6167,14 @@ function retrievePropValue(args) {
6112
6167
  if (!isKnownType(type)) {
6113
6168
  return;
6114
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
+ }
6115
6178
  let resolvedData;
6116
6179
  // When the value is resolved via the `dataSources.page.*` fallback below,
6117
6180
  // the CSLP tag must come from the SAME page path (not the section-local
@@ -6211,7 +6274,8 @@ function retrievePropValue(args) {
6211
6274
  }
6212
6275
  }
6213
6276
  else if (dataPath &&
6214
- !(type === "choice" && bindedField?.type === "static_value")) {
6277
+ !((type === "choice" || type === "action") &&
6278
+ bindedField?.type === "static_value")) {
6215
6279
  resolvedData = get(data, dataPath, fallbackValue);
6216
6280
  // TEMP — slot-child page-context fallback (PHASE 8 will remove this).
6217
6281
  //
@@ -6306,8 +6370,9 @@ function retrievePropValue(args) {
6306
6370
  }
6307
6371
  }
6308
6372
  else {
6309
- // For choice props, explicitly retrieve saved values from static content store
6310
- if (type === "choice" && bindedField?.type === "static_value") {
6373
+ // For choice/action props, explicitly retrieve saved values from static content store
6374
+ if ((type === "choice" || type === "action") &&
6375
+ bindedField?.type === "static_value") {
6311
6376
  const staticContentKey = bindedField.value; // e.g., "B575hDbLkWhPSfB-alignment"
6312
6377
  // Try to find the saved value in the static content store
6313
6378
  let savedValue = undefined;
@@ -6399,7 +6464,11 @@ function retrievePropValue(args) {
6399
6464
  bindedField: cslpPathOverride ?? dataPath,
6400
6465
  data,
6401
6466
  });
6402
- if (cslpValue) {
6467
+ // `getCslpTag` returns `{}` on a miss, and `{}` is truthy — so the old
6468
+ // `if (cslpValue)` published a tag-shaped object with no tag inside, which
6469
+ // consumers then interpolated as `undefined` (see Repeater's `$items`).
6470
+ // Skip that empty miss sentinel without assuming the metadata's inner shape.
6471
+ if (Object.keys(cslpValue).length) {
6403
6472
  mappedData[`$${field}`] = cslpValue;
6404
6473
  }
6405
6474
  }
@@ -6420,19 +6489,6 @@ function retrievePropValue(args) {
6420
6489
  mappedData["condition"] = node?.metadata?.condition;
6421
6490
  mappedData["mode"] = node?.metadata?.mode;
6422
6491
  }
6423
- if (node.type === "symbol") {
6424
- mappedData["symbol_internal_props"] = {
6425
- isEditing: node.metadata.editing,
6426
- };
6427
- mappedData["symbol_props"] = {};
6428
- Object.entries(componentProps).forEach(([field]) => {
6429
- const uid = componentProps[field]["uid"];
6430
- if (!uid) {
6431
- return;
6432
- }
6433
- mappedData["symbol_props"][uid] = mappedData[field];
6434
- });
6435
- }
6436
6492
  if (node.type === "section-composition") {
6437
6493
  // Surface the page composer's LIVE binding type for each exposed prop so the
6438
6494
  // SectionComposition renderer can tell an untouched seed from a real override.
@@ -6465,6 +6521,685 @@ function retrievePropValue(args) {
6465
6521
  return mappedData;
6466
6522
  }
6467
6523
 
6524
+ const isServer = () => typeof window === "undefined";
6525
+ const isDev$1 = () => typeof process !== "undefined" && process.env.NODE_ENV === "development";
6526
+ const DEFAULT_STORAGE_KEY = "cs-studio:state";
6527
+ /**
6528
+ * Built-in web-storage backend for `storage: "local" | "session"` — an
6529
+ * in-memory object hydrated from the chosen Storage with write-through on
6530
+ * every set, plus per-key listeners. SSR-safe: with no `window` it serves
6531
+ * memory only (the store's `set` is a server no-op anyway).
6532
+ */
6533
+ function createWebStorageBackend(kind, storageKey) {
6534
+ const storageArea = () => {
6535
+ if (isServer())
6536
+ return null;
6537
+ try {
6538
+ return kind === "local" ? window.localStorage : window.sessionStorage;
6539
+ }
6540
+ catch {
6541
+ return null; // storage blocked (privacy mode / embedded context)
6542
+ }
6543
+ };
6544
+ const values = (() => {
6545
+ const area = storageArea();
6546
+ if (!area)
6547
+ return {};
6548
+ try {
6549
+ const parsed = JSON.parse(area.getItem(storageKey) ?? "{}");
6550
+ // Only a plain object is a valid value map. A stored bare primitive or
6551
+ // array (e.g. a colliding storageKey, or an older write) must NOT become
6552
+ // `values`, or the first `values[key] = ...` throws in strict mode.
6553
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed)
6554
+ ? parsed
6555
+ : {};
6556
+ }
6557
+ catch {
6558
+ return {};
6559
+ }
6560
+ })();
6561
+ const persist = () => {
6562
+ const area = storageArea();
6563
+ if (!area)
6564
+ return;
6565
+ try {
6566
+ area.setItem(storageKey, JSON.stringify(values));
6567
+ }
6568
+ catch {
6569
+ // quota exceeded / storage blocked — state stays in-memory only
6570
+ }
6571
+ };
6572
+ // No `subscribe` bridge: every mutation goes through the SDK's own set()
6573
+ // (nothing else holds a reference to this backend), and the store already
6574
+ // notifies its per-key listeners after each delegated set.
6575
+ return {
6576
+ getState: (key) => values[key],
6577
+ setState: (key, value) => {
6578
+ values[key] = value;
6579
+ persist();
6580
+ },
6581
+ };
6582
+ }
6583
+ /**
6584
+ * Page-global shared state store — the "Bring Your Own State" (BYOS) core.
6585
+ *
6586
+ * Delegates reads/writes to the user's `getState`/`setState` when configured
6587
+ * (Redux, Zustand, plain object, anything), otherwise falls back to an
6588
+ * internal Map. Reactivity is per-key: `set("cart")` notifies ONLY listeners
6589
+ * subscribed to `"cart"`, so unrelated components never re-render.
6590
+ *
6591
+ * One instance per JS runtime via the globalThis registry slot (see
6592
+ * `singleton.ts`) — every surface (components, sections, templates, custom
6593
+ * code) reads and writes the same store.
6594
+ *
6595
+ * SSR: `set` is a no-op with a dev warning (a mutable process-wide store
6596
+ * would leak state across requests); `get` still delegates so a
6597
+ * server-appropriate `getState` (e.g. request-scoped values) works, falling
6598
+ * back to declared defaults.
6599
+ */
6600
+ class StudioStateStore {
6601
+ userConfig = null;
6602
+ internal = new Map();
6603
+ listeners = new Map();
6604
+ variables = new Map();
6605
+ /** Priority tier each declaration came from (see StateVariableTier). */
6606
+ variableTiers = new Map();
6607
+ /** Fired when the DECLARED variable set changes (declare/configure/reset). */
6608
+ variableListeners = new Set();
6609
+ /** One bridge subscription per key into the user's own store. */
6610
+ externalUnsubs = new Map();
6611
+ warnedServerSet = false;
6612
+ /**
6613
+ * Wire the state backend + init-declared variables. Called once from SDK
6614
+ * init; calling again replaces the config (HMR-safe — variables merge,
6615
+ * they don't reset).
6616
+ *
6617
+ * Storage resolution (see StudioStateStorage):
6618
+ * - `storage: "custom"` → user's getState/setState (required).
6619
+ * - `storage: "local"` → built-in localStorage store.
6620
+ * - `storage: "session"` → built-in sessionStorage store.
6621
+ * - omitted → custom when getState+setState are provided,
6622
+ * otherwise the built-in SESSION store.
6623
+ */
6624
+ configure(config) {
6625
+ const hasCustomFns = typeof config.getState === "function" &&
6626
+ typeof config.setState === "function";
6627
+ const storage = config.storage ?? (hasCustomFns ? "custom" : "session");
6628
+ // Reconfigure (HMR / second init): tear down bridges bound to the PREVIOUS
6629
+ // backend before switching, so ensureExternalBridge below rebuilds them
6630
+ // against the new store instead of leaving them pointing at the old one.
6631
+ for (const unsub of this.externalUnsubs.values())
6632
+ unsub();
6633
+ this.externalUnsubs.clear();
6634
+ if (storage === "custom") {
6635
+ if (!hasCustomFns) {
6636
+ throw new Error('[Composable Studio SDK] state storage "custom" requires getState and setState functions');
6637
+ }
6638
+ this.userConfig = {
6639
+ getState: config.getState,
6640
+ setState: config.setState,
6641
+ subscribe: config.subscribe,
6642
+ };
6643
+ }
6644
+ else {
6645
+ if (hasCustomFns && isDev$1()) {
6646
+ console.warn(`[Composable Studio SDK] state storage "${storage}" uses the built-in store — the provided getState/setState are ignored (use storage: "custom" to keep them)`);
6647
+ }
6648
+ this.userConfig = createWebStorageBackend(storage, config.storageKey ?? DEFAULT_STORAGE_KEY);
6649
+ }
6650
+ // Migrate writes made BEFORE configure ran (they landed in the internal Map
6651
+ // because userConfig was null) into the now-resolved backend, so a
6652
+ // pre-init `set("cart:count", 3)` isn't silently dropped when init lands.
6653
+ // Don't clobber a value the new backend already holds (e.g. hydrated Redux
6654
+ // / persisted web storage) — pre-init writes only fill the gaps.
6655
+ for (const [key, value] of this.internal) {
6656
+ try {
6657
+ if (this.userConfig.getState(key) === undefined) {
6658
+ this.userConfig.setState(key, value);
6659
+ }
6660
+ }
6661
+ catch {
6662
+ // backend rejected the migrated write — leave it; not fatal
6663
+ }
6664
+ }
6665
+ this.internal.clear();
6666
+ for (const [key, def] of Object.entries(config.variables ?? {})) {
6667
+ this.declareVariable(key, def, "init");
6668
+ }
6669
+ // Components may have subscribed BEFORE configure ran (e.g. the SDK init
6670
+ // module evaluates after React mounted a state-bound component). The new
6671
+ // backing store can hold different values (persisted state, hydrated
6672
+ // Redux…), so (re)build the external bridge for every already-subscribed
6673
+ // key and wake every existing subscriber to re-read.
6674
+ for (const key of [...this.listeners.keys()]) {
6675
+ this.ensureExternalBridge(key);
6676
+ this.notify(key);
6677
+ }
6678
+ this.notifyVariablesChanged();
6679
+ }
6680
+ /**
6681
+ * Open a single bridge subscription from the user's own store into this
6682
+ * store's per-key listeners, so mutations made OUTSIDE Studio propagate in.
6683
+ * Idempotent and safe to call from both `subscribe` (first listener) and
6684
+ * `configure` (backend arrived/changed after listeners already existed).
6685
+ */
6686
+ ensureExternalBridge(key) {
6687
+ if (!this.userConfig?.subscribe)
6688
+ return;
6689
+ if (this.externalUnsubs.has(key))
6690
+ return;
6691
+ if (!this.listeners.has(key))
6692
+ return; // only bridge keys someone listens to
6693
+ try {
6694
+ const unsub = this.userConfig.subscribe(key, () => this.notify(key));
6695
+ this.externalUnsubs.set(key, typeof unsub === "function" ? unsub : () => { });
6696
+ }
6697
+ catch (err) {
6698
+ console.error(`[Composable Studio SDK] state subscribe("${key}") threw:`, err);
6699
+ }
6700
+ }
6701
+ isConfigured() {
6702
+ return this.userConfig !== null;
6703
+ }
6704
+ /**
6705
+ * Register an author-bindable variable.
6706
+ *
6707
+ * Priority: a `component`-tier declaration (registerComponentStateVariable at component
6708
+ * module scope) OVERRIDES an `init`-tier one (SDK init `state.variables`)
6709
+ * for the same key — deterministically, whichever loads first. An init
6710
+ * declaration never overrides a component one; it only fills keys no
6711
+ * component declared. Same-tier re-declarations (module reload, repeated
6712
+ * imports) keep the first definition and dev-warn only when the type
6713
+ * conflicts. Runtime `set` values always beat declared defaults.
6714
+ */
6715
+ declareVariable(key, def, tier = "component") {
6716
+ const existing = this.variables.get(key);
6717
+ if (existing) {
6718
+ const existingTier = this.variableTiers.get(key) ?? "component";
6719
+ if (tier === "component" && existingTier === "init") {
6720
+ this.variables.set(key, def);
6721
+ this.variableTiers.set(key, tier);
6722
+ // The effective default may have changed — wake this key's subscribers
6723
+ // (e.g. a mounted useStudioState reading the old default) plus the
6724
+ // declared-set listeners.
6725
+ this.notify(key);
6726
+ this.notifyVariablesChanged();
6727
+ return;
6728
+ }
6729
+ if (existing.type !== def.type && isDev$1()) {
6730
+ console.warn(`[Composable Studio SDK] state variable "${key}" already declared as "${existing.type}"; ignoring re-declaration as "${def.type}"`);
6731
+ }
6732
+ return;
6733
+ }
6734
+ this.variables.set(key, def);
6735
+ this.variableTiers.set(key, tier);
6736
+ // A brand-new declaration makes a default available where `get(key)` used
6737
+ // to return undefined. Wake any component that already subscribed to this
6738
+ // key BEFORE the (lazily-imported) declaration landed, so it re-reads the
6739
+ // default instead of staying stuck on undefined.
6740
+ this.notify(key);
6741
+ this.notifyVariablesChanged();
6742
+ }
6743
+ /** All declared (author-bindable) variables. */
6744
+ getVariables() {
6745
+ return Object.fromEntries(this.variables);
6746
+ }
6747
+ /**
6748
+ * Subscribe to declared-variable-set changes. The SDK's Studio bridge uses
6749
+ * this to push the fresh values snapshot to the Data Picker — apps declare
6750
+ * variables from lazily-imported init code, typically AFTER the component
6751
+ * registry synced, so a one-shot pull at sync time reads an empty set.
6752
+ */
6753
+ subscribeVariablesChanged(listener) {
6754
+ this.variableListeners.add(listener);
6755
+ return () => this.variableListeners.delete(listener);
6756
+ }
6757
+ notifyVariablesChanged() {
6758
+ for (const listener of [...this.variableListeners]) {
6759
+ try {
6760
+ listener();
6761
+ }
6762
+ catch (err) {
6763
+ console.error("[Composable Studio SDK] state variables-changed listener threw:", err);
6764
+ }
6765
+ }
6766
+ }
6767
+ isDeclared(key) {
6768
+ return this.variables.has(key);
6769
+ }
6770
+ /**
6771
+ * The declared default for a key, ignoring any live backend value. This is
6772
+ * the server / hydration baseline: SSR and the client's hydration render
6773
+ * must agree, so state-bound content renders the default on both and only
6774
+ * switches to a persisted/live value AFTER hydration.
6775
+ */
6776
+ getDeclaredDefault(key) {
6777
+ return this.variables.get(key)?.defaultValue;
6778
+ }
6779
+ /** Raw backing value with NO declared-default fallback (undefined if unset). */
6780
+ readRaw(key) {
6781
+ if (this.userConfig) {
6782
+ try {
6783
+ return this.userConfig.getState(key);
6784
+ }
6785
+ catch (err) {
6786
+ console.error(`[Composable Studio SDK] getState("${key}") threw:`, err);
6787
+ return undefined;
6788
+ }
6789
+ }
6790
+ return (this.internal.has(key) ? this.internal.get(key) : undefined);
6791
+ }
6792
+ get(key) {
6793
+ let value = this.readRaw(key);
6794
+ if (value === undefined) {
6795
+ value = this.variables.get(key)?.defaultValue;
6796
+ }
6797
+ return value;
6798
+ }
6799
+ set(key, next) {
6800
+ if (isServer()) {
6801
+ if (!this.warnedServerSet && isDev$1()) {
6802
+ this.warnedServerSet = true;
6803
+ console.warn("[Composable Studio SDK] setState is a no-op during server rendering — state writes are client-only");
6804
+ }
6805
+ return;
6806
+ }
6807
+ // The functional updater sees the effective value (default-aware)...
6808
+ const effectivePrev = this.get(key);
6809
+ const value = typeof next === "function"
6810
+ ? next(effectivePrev)
6811
+ : next;
6812
+ // ...but dedup against the RAW backing value, not get(). Comparing against
6813
+ // get() (which folds in the declared default) would swallow the first write
6814
+ // of a value that equals the default — e.g. set("cart:count", 0) when the
6815
+ // default is 0 — so the backend/custom store never receives it.
6816
+ const rawPrev = this.readRaw(key);
6817
+ if (Object.is(rawPrev, value))
6818
+ return;
6819
+ if (this.userConfig) {
6820
+ this.userConfig.setState(key, value);
6821
+ }
6822
+ else {
6823
+ this.internal.set(key, value);
6824
+ }
6825
+ this.notify(key);
6826
+ }
6827
+ /**
6828
+ * Per-key subscription. Returns an unsubscribe. When the user supplied
6829
+ * their own `subscribe`, a single bridge per key is also registered so
6830
+ * store mutations made OUTSIDE Studio propagate into Studio listeners.
6831
+ */
6832
+ subscribe(key, listener) {
6833
+ if (isServer())
6834
+ return () => { };
6835
+ let set = this.listeners.get(key);
6836
+ if (!set) {
6837
+ set = new Set();
6838
+ this.listeners.set(key, set);
6839
+ }
6840
+ set.add(listener);
6841
+ this.ensureExternalBridge(key);
6842
+ return () => {
6843
+ const listeners = this.listeners.get(key);
6844
+ listeners?.delete(listener);
6845
+ if (listeners && listeners.size === 0) {
6846
+ this.listeners.delete(key);
6847
+ const unsubExternal = this.externalUnsubs.get(key);
6848
+ if (unsubExternal) {
6849
+ this.externalUnsubs.delete(key);
6850
+ unsubExternal();
6851
+ }
6852
+ }
6853
+ };
6854
+ }
6855
+ notify(key) {
6856
+ const listeners = this.listeners.get(key);
6857
+ if (!listeners)
6858
+ return;
6859
+ for (const listener of [...listeners]) {
6860
+ try {
6861
+ listener();
6862
+ }
6863
+ catch (err) {
6864
+ console.error(`[Composable Studio SDK] state listener for "${key}" threw:`, err);
6865
+ }
6866
+ }
6867
+ }
6868
+ /**
6869
+ * Soft reset for hosts that want per-page state on a client-side route
6870
+ * change (this is what the public `studioState.reset()` calls). Clears the
6871
+ * SDK-owned internal values and wakes every subscriber to re-read — but
6872
+ * deliberately KEEPS the wired backend, the declared variables, and all live
6873
+ * subscriptions. Tearing those down here (the previous behavior) disconnected
6874
+ * a configured custom store, wiped every declaration, and froze every still-
6875
+ * mounted `useStudioState`. For a full teardown (tests / HMR) use `resetAll`.
6876
+ *
6877
+ * A configured custom or web-storage backend owns its own values and is left
6878
+ * intact — the host resets its own store if it wants those cleared too.
6879
+ */
6880
+ reset() {
6881
+ this.internal.clear();
6882
+ for (const key of [...this.listeners.keys()]) {
6883
+ this.notify(key);
6884
+ }
6885
+ this.notifyVariablesChanged();
6886
+ }
6887
+ /**
6888
+ * Full teardown — internal values, declarations, config, listeners, and
6889
+ * external bridges. For tests and HMR (the singleton drop), NOT for
6890
+ * route-change resets (see `reset`).
6891
+ */
6892
+ resetAll() {
6893
+ for (const unsub of this.externalUnsubs.values())
6894
+ unsub();
6895
+ this.externalUnsubs.clear();
6896
+ this.internal.clear();
6897
+ this.listeners.clear();
6898
+ this.variables.clear();
6899
+ this.variableTiers.clear();
6900
+ this.userConfig = null;
6901
+ this.warnedServerSet = false;
6902
+ this.notifyVariablesChanged();
6903
+ }
6904
+ }
6905
+
6906
+ /**
6907
+ * Lazily create (or reuse) the page-global StudioStateStore in the SDK's
6908
+ * versioned globalThis slot. Same pattern as the component/design registries
6909
+ * — survives Next.js RSC/client module-graph splits so every surface talks
6910
+ * to the same store instance.
6911
+ */
6912
+ function getStateStoreInstance() {
6913
+ const store = getGlobalStudioStore();
6914
+ if (!store.stateStore) {
6915
+ store.stateStore = new StudioStateStore();
6916
+ }
6917
+ return store.stateStore;
6918
+ }
6919
+ /** Test-only: drop the singleton so the next access builds a fresh store. */
6920
+ function resetStateStoreInstance() {
6921
+ const store = getGlobalStudioStore();
6922
+ // Full teardown (unsub bridges, drop config/vars/listeners) — not the soft
6923
+ // route-change reset() — since the slot itself is being dropped.
6924
+ store.stateStore?.resetAll();
6925
+ store.stateStore = null;
6926
+ }
6927
+
6928
+ function getRegistry() {
6929
+ const store = getGlobalStudioStore();
6930
+ if (!store.functionRegistry) {
6931
+ store.functionRegistry = {
6932
+ functions: new Map(),
6933
+ changeListeners: new Set(),
6934
+ };
6935
+ }
6936
+ // Slot created by an older module instance (globalThis singleton outlives
6937
+ // module graphs) — patch the field in rather than dropping registrations.
6938
+ if (!store.functionRegistry.changeListeners) {
6939
+ store.functionRegistry.changeListeners = new Set();
6940
+ }
6941
+ return store.functionRegistry;
6942
+ }
6943
+ function notifyFunctionsChanged() {
6944
+ for (const listener of [...getRegistry().changeListeners]) {
6945
+ try {
6946
+ listener();
6947
+ }
6948
+ catch (err) {
6949
+ console.error("[Composable Studio SDK] studio-functions change listener threw:", err);
6950
+ }
6951
+ }
6952
+ }
6953
+ /**
6954
+ * Subscribe to registry changes (functions added / reset). Used by the SDK's
6955
+ * Studio bridge to push the fresh name list to the Studio props panel whenever
6956
+ * the app registers functions — regardless of whether that happens before or
6957
+ * after the component registry sync.
6958
+ */
6959
+ function subscribeStudioFunctionsChanged(listener) {
6960
+ const registry = getRegistry();
6961
+ registry.changeListeners.add(listener);
6962
+ return () => registry.changeListeners.delete(listener);
6963
+ }
6964
+ const isDev = () => typeof process !== "undefined" && process.env.NODE_ENV === "development";
6965
+ /**
6966
+ * Register named custom functions — the app's business logic that components
6967
+ * invoke by NAME. Call as many times as you like (e.g. one call per feature
6968
+ * module); registrations MERGE. Re-registering an existing name overwrites it
6969
+ * with a dev warning (supports HMR).
6970
+ *
6971
+ * ```ts
6972
+ * registerStudioFunctions({
6973
+ * "cart:add": (ctx, args) => {
6974
+ * ctx.set("cart:count", (prev) => (prev ?? 0) + 1);
6975
+ * ctx.set("cart:last_added", args?.sku ?? "");
6976
+ * },
6977
+ * "coupon:apply": (ctx, args) => {
6978
+ * const discounts = { SAVE10: 10, SAVE20: 20 };
6979
+ * ctx.set("checkout:discount", discounts[args?.code] ?? 0);
6980
+ * },
6981
+ * });
6982
+ * ```
6983
+ */
6984
+ function registerStudioFunctions(functions) {
6985
+ const registry = getRegistry();
6986
+ for (const [name, fn] of Object.entries(functions ?? {})) {
6987
+ if (typeof fn !== "function") {
6988
+ console.warn(`[Composable Studio SDK] registerStudioFunctions: "${name}" is not a function — skipped`);
6989
+ continue;
6990
+ }
6991
+ if (registry.functions.has(name) && isDev()) {
6992
+ console.warn(`[Composable Studio SDK] studio function "${name}" re-registered (overwriting previous)`);
6993
+ }
6994
+ registry.functions.set(name, fn);
6995
+ }
6996
+ notifyFunctionsChanged();
6997
+ }
6998
+ /** Names of every registered function — for debugging / future picker UI. */
6999
+ function getStudioFunctionNames() {
7000
+ return [...getRegistry().functions.keys()];
7001
+ }
7002
+ /**
7003
+ * Invoke a registered function by name from ANY component or code.
7004
+ *
7005
+ * ```ts
7006
+ * <button onClick={() => callStudioFunction("cart:add", { sku })}>Add</button>
7007
+ * ```
7008
+ *
7009
+ * Never throws into the UI: a missing name warns and returns undefined; sync
7010
+ * throws and async rejections are caught and logged. The function receives
7011
+ * the shared-state ctx as its first argument.
7012
+ */
7013
+ function callStudioFunction(name, ...args) {
7014
+ const fn = getRegistry().functions.get(name);
7015
+ if (!fn) {
7016
+ console.warn(`[Composable Studio SDK] studio function "${name}" is not registered. Did you call registerStudioFunctions()?`);
7017
+ return undefined;
7018
+ }
7019
+ const store = getStateStoreInstance();
7020
+ const ctx = {
7021
+ get: (key) => store.get(key),
7022
+ set: (key, next) => store.set(key, next),
7023
+ subscribe: (key, listener) => store.subscribe(key, listener),
7024
+ };
7025
+ try {
7026
+ // Forward every argument the caller passed (action-prop callbacks can be
7027
+ // invoked with multiple positional args); the cast bridges the variadic
7028
+ // call to StudioFunction's (ctx, args?, ...rest) shape.
7029
+ const result = fn(ctx, ...args);
7030
+ if (result &&
7031
+ typeof result.then === "function" &&
7032
+ typeof result.catch === "function") {
7033
+ return result.catch((err) => {
7034
+ console.error(`[Composable Studio SDK] studio function "${name}" rejected:`, err);
7035
+ return undefined;
7036
+ });
7037
+ }
7038
+ return result;
7039
+ }
7040
+ catch (err) {
7041
+ console.error(`[Composable Studio SDK] studio function "${name}" threw:`, err);
7042
+ return undefined;
7043
+ }
7044
+ }
7045
+ /** Test-only: clear all registered functions. */
7046
+ function resetStudioFunctions() {
7047
+ getRegistry().functions.clear();
7048
+ notifyFunctionsChanged();
7049
+ }
7050
+
7051
+ /**
7052
+ * Collect the DECLARED state variable keys a node's prop bindings reference.
7053
+ *
7054
+ * Per the BYOS design there is no new binding type: authors bind state
7055
+ * through the existing `component_props` source. A `component_props` binding
7056
+ * whose value matches a declared state variable resolves from the shared
7057
+ * state store instead of the composition's external data — this helper finds
7058
+ * exactly those keys so the renderer can subscribe the node to them.
7059
+ *
7060
+ * Undeclared keys never match (ad-hoc state is code-only), and nodes without
7061
+ * state-backed bindings return an empty array — the zero-cost path.
7062
+ */
7063
+ /**
7064
+ * The longest dotted-prefix of `path` that is a declared state key, or
7065
+ * undefined. `product:price` (declared, no dot) returns itself;
7066
+ * `user:profile.tier` returns the declared root `user:profile`; a path with no
7067
+ * declared prefix returns undefined (an ordinary external-data binding).
7068
+ */
7069
+ function declaredKeyForPath(store, path) {
7070
+ if (store.isDeclared(path))
7071
+ return path;
7072
+ const segments = path.split(".");
7073
+ for (let end = segments.length - 1; end >= 1; end--) {
7074
+ const prefix = segments.slice(0, end).join(".");
7075
+ if (store.isDeclared(prefix))
7076
+ return prefix;
7077
+ }
7078
+ return undefined;
7079
+ }
7080
+ function collectStateBindingKeys(node) {
7081
+ if (!node)
7082
+ return [];
7083
+ const store = getStateStoreInstance();
7084
+ const keys = new Set();
7085
+ const consider = (binding) => {
7086
+ const key = getComponentPropsBindingKey(binding);
7087
+ if (!key)
7088
+ return;
7089
+ // A binding to a nested sub-field of a declared object/array state variable
7090
+ // is a DOTTED path (the picker writes `pathSegments.join(".")`), e.g.
7091
+ // "user:profile.tier" or "cart:items.0.name". Only the ROOT ("user:profile")
7092
+ // is declared, so collect+subscribe that — the snapshot merges the whole
7093
+ // object under it and the sub-path resolves via the normal component_props
7094
+ // path walk. Top-level primitive keys (no dot) match directly.
7095
+ const declared = declaredKeyForPath(store, key);
7096
+ if (declared)
7097
+ keys.add(declared);
7098
+ };
7099
+ // Scan BOTH attribute bindings (metadata.bindings, e.g. attrs.id) and prop
7100
+ // bindings — symmetric with getNodeBoundFunctionName. Scanning only props
7101
+ // left attribute-bound state variables un-snapshotted and un-subscribed
7102
+ // (rendered empty, never reactive).
7103
+ for (const binding of Object.values(node.metadata?.bindings ?? {})) {
7104
+ consider(binding);
7105
+ }
7106
+ for (const prop of Object.values(node.props ?? {})) {
7107
+ consider(prop?.binding);
7108
+ }
7109
+ return [...keys];
7110
+ }
7111
+ /**
7112
+ * Snapshot of the given declared state keys — `{ key: currentValue }` —
7113
+ * merged by the renderer into `data.component_props` before prop resolution
7114
+ * so the existing `component_props` path machinery (fallbacks, type
7115
+ * validation, editor error badges) resolves state values unchanged.
7116
+ *
7117
+ * Keys whose current value is `undefined` (declared but unset, no default) are
7118
+ * OMITTED — spreading `{key: undefined}` over `component_props` would wipe an
7119
+ * external/authored value of the same name, silently losing server content.
7120
+ */
7121
+ function getStateValuesFor(keys) {
7122
+ const store = getStateStoreInstance();
7123
+ const out = {};
7124
+ for (const key of keys) {
7125
+ const value = store.get(key);
7126
+ if (value !== undefined)
7127
+ out[key] = value;
7128
+ }
7129
+ return out;
7130
+ }
7131
+ /**
7132
+ * Like getStateValuesFor but reads ONLY the declared defaults, never the live
7133
+ * backend value. Used as the server / hydration baseline so SSR and the client
7134
+ * hydration render agree (a persisted local/session value read on the client
7135
+ * but not the server would otherwise be a hydration mismatch). Undefined
7136
+ * defaults are omitted for the same reason as getStateValuesFor.
7137
+ */
7138
+ function getStateDefaultsFor(keys) {
7139
+ const store = getStateStoreInstance();
7140
+ const out = {};
7141
+ for (const key of keys) {
7142
+ const value = store.getDeclaredDefault(key);
7143
+ if (value !== undefined)
7144
+ out[key] = value;
7145
+ }
7146
+ return out;
7147
+ }
7148
+ /**
7149
+ * Extract the Component Props KEY a binding refers to. The picker writes the
7150
+ * key either as a plain string value or wrapped in a `{ path: { key: {} } }`
7151
+ * object (template-style) — accept both so the function detection below
7152
+ * doesn't depend on which surface authored the binding.
7153
+ */
7154
+ function getComponentPropsBindingKey(binding) {
7155
+ const b = binding;
7156
+ if (!b || b.type !== DATA_SOURCES.COMPONENT_PROPS)
7157
+ return undefined;
7158
+ if (typeof b.value === "string")
7159
+ return b.value || undefined;
7160
+ const path = b.value
7161
+ ?.path;
7162
+ if (path && typeof path === "object") {
7163
+ const [first] = Object.keys(path);
7164
+ return first || undefined;
7165
+ }
7166
+ return undefined;
7167
+ }
7168
+ /**
7169
+ * The registered studio FUNCTION a node is bound to, if any.
7170
+ *
7171
+ * Authors assign behavior from the Data Picker's Component Props section
7172
+ * (functions are listed under the state variables): the picker writes an
7173
+ * ordinary `component_props` binding — on an attribute (`metadata.bindings`,
7174
+ * e.g. `attrs.id`) or a prop — whose key is a registered function NAME.
7175
+ * Because functions and data share the source, "is it a function?" is decided
7176
+ * right here: key ∈ function registry → behavior, otherwise it stays a plain
7177
+ * data binding and is ignored by this helper.
7178
+ *
7179
+ * The renderer attaches the returned name as the node's click handler
7180
+ * (`callStudioFunction(name)`), which is what makes assignment work for ANY
7181
+ * component with zero prop declarations.
7182
+ */
7183
+ function getNodeBoundFunctionName(node) {
7184
+ if (!node)
7185
+ return undefined;
7186
+ const registered = getStudioFunctionNames();
7187
+ if (registered.length === 0)
7188
+ return undefined;
7189
+ const names = new Set(registered);
7190
+ for (const binding of Object.values(node.metadata?.bindings ?? {})) {
7191
+ const key = getComponentPropsBindingKey(binding);
7192
+ if (key && names.has(key))
7193
+ return key;
7194
+ }
7195
+ for (const prop of Object.values(node.props ?? {})) {
7196
+ const key = getComponentPropsBindingKey(prop?.binding);
7197
+ if (key && names.has(key))
7198
+ return key;
7199
+ }
7200
+ return undefined;
7201
+ }
7202
+
6468
7203
  class BreakpointRegistry {
6469
7204
  breakpoints = [];
6470
7205
  requiredFields = ["id", "query", "previewSize"];
@@ -6531,6 +7266,149 @@ class BreakpointRegistry {
6531
7266
  }
6532
7267
  }
6533
7268
 
7269
+ /**
7270
+ * Declare an author-bindable state variable at component/section module
7271
+ * scope — the "component-declared" tier. Call at module load time (top of
7272
+ * the file, next to the component definition):
7273
+ *
7274
+ * ```ts
7275
+ * registerComponentStateVariable("cart:filter", { type: "string", defaultValue: "" });
7276
+ *
7277
+ * export function CartFilter() {
7278
+ * const [filter, setFilter] = useStudioState<string>("cart:filter");
7279
+ * ...
7280
+ * }
7281
+ * ```
7282
+ *
7283
+ * Declared variables appear for binding inside the existing External Data
7284
+ * source; undeclared keys stay code-only (ad-hoc tier).
7285
+ *
7286
+ * Priority: component-level declarations WIN over the same key declared
7287
+ * globally at init (`state.variables`) — deterministically, regardless of
7288
+ * which module evaluated first. The global declaration is used only for keys
7289
+ * no component declared. Runtime `set` values always beat declared defaults.
7290
+ */
7291
+ function registerComponentStateVariable(key, options) {
7292
+ if (!key || typeof key !== "string") {
7293
+ throw new Error("[Composable Studio SDK] registerComponentStateVariable requires a non-empty string key");
7294
+ }
7295
+ getStateStoreInstance().declareVariable(key, options, "component");
7296
+ }
7297
+ /**
7298
+ * Imperative access to the shared state store — for custom user code outside
7299
+ * React (event handlers, analytics glue, business logic):
7300
+ *
7301
+ * ```ts
7302
+ * import { studioState } from "@contentstack/studio-react";
7303
+ *
7304
+ * studioState.set("cart:count", (prev) => (prev ?? 0) + 1);
7305
+ * const count = studioState.get<number>("cart:count");
7306
+ * const stop = studioState.subscribe("cart:count", () => console.log("changed"));
7307
+ * ```
7308
+ *
7309
+ * Same store instance the `useStudioState` hook and author bindings use —
7310
+ * one source of truth across components, sections, templates, and code.
7311
+ */
7312
+ /**
7313
+ * Snapshot of every DECLARED state variable with its CURRENT value —
7314
+ * `[{ key, value }]`. This is what the Studio Data Picker lists under
7315
+ * Component Props so authors can bind the values the app made available
7316
+ * (init `state.variables`, `registerComponentStateVariable`) — e.g. `price → 2999`.
7317
+ *
7318
+ * Only declared variables are enumerable: BYOS user stores expose key-based
7319
+ * `getState` with no key listing, so ad-hoc (code-only) keys can't be swept.
7320
+ */
7321
+ function getStudioStateSnapshot() {
7322
+ const store = getStateStoreInstance();
7323
+ return Object.keys(store.getVariables()).map((key) => ({
7324
+ key,
7325
+ value: store.get(key),
7326
+ }));
7327
+ }
7328
+ /**
7329
+ * Subscribe to declared-variable-set changes on the page-global store —
7330
+ * passthrough for the Studio bridge (see StudioStateStore.subscribeVariablesChanged).
7331
+ */
7332
+ function subscribeStudioStateVariablesChanged(listener) {
7333
+ return getStateStoreInstance().subscribeVariablesChanged(listener);
7334
+ }
7335
+ const studioState = {
7336
+ get(key) {
7337
+ return getStateStoreInstance().get(key);
7338
+ },
7339
+ set(key, next) {
7340
+ getStateStoreInstance().set(key, next);
7341
+ },
7342
+ subscribe(key, listener) {
7343
+ return getStateStoreInstance().subscribe(key, listener);
7344
+ },
7345
+ /** Clear all state — call on client-side route change if you want per-page state. */
7346
+ reset() {
7347
+ getStateStoreInstance().reset();
7348
+ },
7349
+ };
7350
+ /**
7351
+ * Declare a SET of variables at the INIT tier — same priority as SDK init
7352
+ * `state.variables`, so later component-level `registerComponentStateVariable` calls
7353
+ * still override them.
7354
+ *
7355
+ * Purpose: SSR hydration alignment. The server declares variables at module
7356
+ * scope (server init file), but apps typically run the CLIENT init from a
7357
+ * lazily-imported module — AFTER hydration. State-bound nodes then hydrate
7358
+ * against undeclared keys and mismatch the server HTML. Import a tiny module
7359
+ * that calls this at module scope (e.g. from _app) so declarations exist on
7360
+ * the client BEFORE hydration:
7361
+ *
7362
+ * ```ts
7363
+ * // lib/register-state-variables.ts — imported statically by _app
7364
+ * registerGlobalStateVariables(studioStateConfig.variables ?? {});
7365
+ * ```
7366
+ */
7367
+ function registerGlobalStateVariables(variables) {
7368
+ const store = getStateStoreInstance();
7369
+ for (const [key, def] of Object.entries(variables ?? {})) {
7370
+ store.declareVariable(key, def, "init");
7371
+ }
7372
+ }
7373
+
7374
+ /**
7375
+ * Swap resolved `action` props (registered function NAMES saved from the
7376
+ * Studio props panel) for real callables before the props reach the
7377
+ * component. Runs in both renderers (live + canvas) right after
7378
+ * `retrievePropValue`, so ANY component — SDK basic or app-registered —
7379
+ * that declares a `{ type: "action" }` prop receives an invokable function:
7380
+ *
7381
+ * ```tsx
7382
+ * function Card({ onBuy }: { onBuy?: (...args: unknown[]) => unknown }) {
7383
+ * return <button onClick={() => onBuy?.({ sku: "X1" })}>Buy</button>;
7384
+ * }
7385
+ * ```
7386
+ *
7387
+ * An unset/empty selection resolves to `undefined` (component can feature-
7388
+ * detect); a missing function name is contained inside `callStudioFunction`
7389
+ * (warn, no crash). Non-action props pass through untouched.
7390
+ */
7391
+ function wrapActionProps(componentProps, resolvedProps) {
7392
+ if (!componentProps)
7393
+ return resolvedProps;
7394
+ let wrapped = null;
7395
+ for (const [name, def] of Object.entries(componentProps)) {
7396
+ const type = typeof def === "string" ? def : def?.type;
7397
+ if (type !== "action")
7398
+ continue;
7399
+ const value = resolvedProps[name];
7400
+ if (typeof value === "function")
7401
+ continue; // already callable (direct usage)
7402
+ if (!wrapped)
7403
+ wrapped = { ...resolvedProps };
7404
+ const functionName = typeof value === "string" ? value.trim() : "";
7405
+ wrapped[name] = functionName
7406
+ ? (...args) => callStudioFunction(functionName, ...args)
7407
+ : undefined;
7408
+ }
7409
+ return wrapped ?? resolvedProps;
7410
+ }
7411
+
6534
7412
  exports.ALLOWED_DESIGN_VALUES_LEVELS = ALLOWED_DESIGN_VALUES_LEVELS;
6535
7413
  exports.BUILT_IN_COMPONENTS = BUILT_IN_COMPONENTS;
6536
7414
  exports.BreakpointRegistry = BreakpointRegistry;
@@ -6546,7 +7424,10 @@ exports.JSONRTERegistry = JSONRTERegistry;
6546
7424
  exports.STYLE_SECTIONS_OPTIONS = STYLE_SECTIONS_OPTIONS;
6547
7425
  exports.STYLE_SECTION_CATEGORIES = STYLE_SECTION_CATEGORIES;
6548
7426
  exports.SYSTEM_COMPONENTS = SYSTEM_COMPONENTS;
7427
+ exports.StudioStateStore = StudioStateStore;
7428
+ exports.callStudioFunction = callStudioFunction;
6549
7429
  exports.clearReportedBindingErrorsForNode = clearReportedBindingErrorsForNode;
7430
+ exports.collectStateBindingKeys = collectStateBindingKeys;
6550
7431
  exports.convertBindingPath = convertBindingPath;
6551
7432
  exports.getBindingString = getBindingString;
6552
7433
  exports.getComponentRegistryInstance = getComponentRegistryInstance;
@@ -6558,21 +7439,34 @@ exports.getDesignClassesNames = getDesignClassesNames;
6558
7439
  exports.getDesignRegistryInstance = getDesignRegistryInstance;
6559
7440
  exports.getFlattenedData = getFlattenedData;
6560
7441
  exports.getGlobalStudioStore = getGlobalStudioStore;
7442
+ exports.getNodeBoundFunctionName = getNodeBoundFunctionName;
6561
7443
  exports.getPlaceHolderComponent = getPlaceHolderComponent;
6562
7444
  exports.getRepeaterBinding = getRepeaterBinding;
6563
7445
  exports.getRepeaterContextPath = getRepeaterContextPath;
6564
7446
  exports.getSectionUIDFromNode = getSectionUIDFromNode;
6565
7447
  exports.getSlotData = getSlotData;
6566
- exports.getSymbolUIDFromNode = getSymbolUIDFromNode;
6567
- exports.getSymbolUIDFromUID = getSymbolUIDFromUID;
7448
+ exports.getStateDefaultsFor = getStateDefaultsFor;
7449
+ exports.getStateStoreInstance = getStateStoreInstance;
7450
+ exports.getStateValuesFor = getStateValuesFor;
7451
+ exports.getStudioFunctionNames = getStudioFunctionNames;
7452
+ exports.getStudioStateSnapshot = getStudioStateSnapshot;
6568
7453
  exports.hasComponentRegistryInstance = hasComponentRegistryInstance;
6569
7454
  exports.hasDesignRegistryInstance = hasDesignRegistryInstance;
6570
7455
  exports.isDataMatchingPropType = isDataMatchingPropType;
6571
7456
  exports.isKnownType = isKnownType;
6572
7457
  exports.normalizeSingleSelectChoiceValue = normalizeSingleSelectChoiceValue;
7458
+ exports.registerComponentStateVariable = registerComponentStateVariable;
7459
+ exports.registerGlobalStateVariables = registerGlobalStateVariables;
7460
+ exports.registerStudioFunctions = registerStudioFunctions;
6573
7461
  exports.resetComponentRegistryInstance = resetComponentRegistryInstance;
6574
7462
  exports.resetDesignRegistryInstance = resetDesignRegistryInstance;
6575
7463
  exports.resetGlobalStudioStore = resetGlobalStudioStore;
7464
+ exports.resetStateStoreInstance = resetStateStoreInstance;
7465
+ exports.resetStudioFunctions = resetStudioFunctions;
6576
7466
  exports.resolveMetadataBindings = resolveMetadataBindings;
6577
7467
  exports.retrievePropValue = retrievePropValue;
7468
+ exports.studioState = studioState;
7469
+ exports.subscribeStudioFunctionsChanged = subscribeStudioFunctionsChanged;
7470
+ exports.subscribeStudioStateVariablesChanged = subscribeStudioStateVariablesChanged;
7471
+ exports.wrapActionProps = wrapActionProps;
6578
7472
  //# sourceMappingURL=index.cjs.map