@contentstack/studio-registry 1.8.0-alpha-20260721T1325-1838437.0 → 1.9.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 (36) hide show
  1. package/dist/cjs/index.cjs +998 -201
  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 +1 -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 +11 -32
  14. package/dist/esm/data-binder/retrieve-data.js.map +1 -1
  15. package/dist/esm/data-binder/retrieve-data.util.js +7 -4
  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 +468 -26
  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 +6 -6
  35. package/dist/esm/utils/symbols.js +0 -12
  36. 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,
@@ -4118,6 +4107,7 @@ function getExpandedPropTypes(prop) {
4118
4107
  href: { type: "href" },
4119
4108
  imageurl: { type: "imageurl" },
4120
4109
  slot: { type: "slot" },
4110
+ action: { type: "action" },
4121
4111
  };
4122
4112
  return propTypeMapping[prop];
4123
4113
  }
@@ -4240,7 +4230,6 @@ class ComponentRegistry {
4240
4230
  this.componentRegistry.forEach((componentConfig) => {
4241
4231
  if (!updatedConfig.some((c) => c.type === componentConfig.type)) {
4242
4232
  if (SYSTEM_COMPONENTS.has(componentConfig.type) ||
4243
- componentConfig.metadata?.type === "symbol" ||
4244
4233
  componentConfig.metadata?.type === "section-composition") {
4245
4234
  return;
4246
4235
  }
@@ -4314,23 +4303,6 @@ class ComponentRegistry {
4314
4303
  this.propValidatorRegistry.set(type, propValidators);
4315
4304
  });
4316
4305
  }
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
4306
  registerSectionComponent(componentsConfigs) {
4335
4307
  componentsConfigs.forEach((componentConfig) => {
4336
4308
  const { type } = componentConfig;
@@ -4339,7 +4311,7 @@ class ComponentRegistry {
4339
4311
  ];
4340
4312
  componentConfig["hideFromComponentList"] = true;
4341
4313
  const { processedOptions } = processRegistryOptions(componentConfig, {
4342
- registry: "symbols",
4314
+ registry: "sections",
4343
4315
  });
4344
4316
  this.componentRegistry.set(type, processedOptions);
4345
4317
  });
@@ -4498,13 +4470,6 @@ class ComponentRegistry {
4498
4470
  }
4499
4471
  getComponentName(node) {
4500
4472
  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
4473
  if (type === "section-composition") {
4509
4474
  const resolvedName = getSectionUIDFromNode(node) || type;
4510
4475
  return resolvedName;
@@ -4689,6 +4654,8 @@ function getGlobalStudioStore() {
4689
4654
  componentRegistry: null,
4690
4655
  designRegistry: null,
4691
4656
  breakpointManager: null,
4657
+ stateStore: null,
4658
+ functionRegistry: null,
4692
4659
  };
4693
4660
  }
4694
4661
  return g[GLOBAL_STORE_KEY];
@@ -5409,8 +5376,9 @@ function processDesignTokensOptions(options = {}) {
5409
5376
  return defaultOptions;
5410
5377
  }
5411
5378
  function processAllowedDesignValues(allowedValues) {
5379
+ // Keep this fallback in agreement with getDefaultDesignTokensOptions().
5412
5380
  if (!allowedValues)
5413
- return ALLOWED_DESIGN_VALUES_LEVELS.DYNAMIC;
5381
+ return ALLOWED_DESIGN_VALUES_LEVELS.ARBITRARY;
5414
5382
  switch (allowedValues) {
5415
5383
  case "dynamic":
5416
5384
  return ALLOWED_DESIGN_VALUES_LEVELS.DYNAMIC;
@@ -5483,7 +5451,9 @@ function getDefaultDesignTokens() {
5483
5451
  function getDefaultDesignTokensOptions() {
5484
5452
  return {
5485
5453
  allowDefaultDesignTokens: true,
5486
- allowedValuesLevel: ALLOWED_DESIGN_VALUES_LEVELS.DYNAMIC,
5454
+ // Default to the most permissive level: Studio is powerful out of the box
5455
+ // and design governance is opt-in (a site sets a lower level to lock down).
5456
+ allowedValuesLevel: ALLOWED_DESIGN_VALUES_LEVELS.ARBITRARY,
5487
5457
  };
5488
5458
  }
5489
5459
  function getDefaultGlobalDesignTokens() {
@@ -5640,7 +5610,14 @@ function getCslpPath(binding) {
5640
5610
  }
5641
5611
  const bindingParts = binding.split(".");
5642
5612
  const lastPart = bindingParts.pop();
5643
- const cslpPath = bindingParts.join(".") + ".$." + lastPart;
5613
+ // A TOP-LEVEL binding ("modular_blocks") has no parent parts, so joining them
5614
+ // yields "" and naive concatenation produces a LEADING DOT (".$.modular_blocks").
5615
+ // lodash `get` reads that as an empty first key and resolves to undefined, so the
5616
+ // edit tag silently goes missing for every top-level field — while nested
5617
+ // bindings ("cards.card" → "cards.$.card") resolve fine. Anchor at "$." instead.
5618
+ const cslpPath = bindingParts.length
5619
+ ? `${bindingParts.join(".")}.$.${lastPart}`
5620
+ : `$.${lastPart}`;
5644
5621
  return cslpPath;
5645
5622
  }
5646
5623
  //TODO: Move it to more appropriate place
@@ -5877,6 +5854,7 @@ function getDefaultPropStaticValue(args) {
5877
5854
  any: "",
5878
5855
  json_rte: {},
5879
5856
  plaintext: "",
5857
+ action: "",
5880
5858
  };
5881
5859
  if (args) {
5882
5860
  return defaultValues[args];
@@ -5898,6 +5876,7 @@ function isKnownType(type) {
5898
5876
  any: true,
5899
5877
  json_rte: true,
5900
5878
  plaintext: true,
5879
+ action: true,
5901
5880
  };
5902
5881
  return Object.keys(knownTypes).includes(type);
5903
5882
  }
@@ -5939,9 +5918,6 @@ registry.register(DATA_SOURCES.COMPONENT_PROPS, {
5939
5918
  registry.register(DATA_SOURCES.STATIC_VALUE, {
5940
5919
  getBindingString: (binding) => [DATA_SOURCES.STATIC_VALUE, binding.value].filter(Boolean).join("."),
5941
5920
  });
5942
- registry.register(DATA_SOURCES.SYMBOL_PROPS, {
5943
- getBindingString: (binding) => [DATA_SOURCES.SYMBOL_PROPS, binding.value].filter(Boolean).join("."),
5944
- });
5945
5921
  const getBindingString = (binding) => {
5946
5922
  const strategy = DataSourceStrategyRegistry.getInstance().get(binding.type);
5947
5923
  if (strategy) {
@@ -6017,11 +5993,15 @@ function isDataMatchingPropType(data, type) {
6017
5993
  href: dataType === "string",
6018
5994
  imageurl: dataType === "string",
6019
5995
  datestring: dataType === "string",
6020
- json_rte: dataType === "object",
5996
+ // object = JSON RTE document; string = HTML RTE / Markdown
5997
+ json_rte: dataType === "object" || dataType === "string",
6021
5998
  // "any" accepts all data types — no validation
6022
5999
  any: true,
6023
6000
  // "plaintext" accepts singleline/multiline text, number, and boolean fields
6024
6001
  plaintext: dataType === "string" || dataType === "number" || dataType === "boolean",
6002
+ // "action" stores a registered function NAME; the renderer later swaps it
6003
+ // for a callable, so post-wrap re-validation must accept functions too.
6004
+ action: dataType === "string" || dataType === "function",
6025
6005
  };
6026
6006
  return map[type] ?? false;
6027
6007
  }
@@ -6088,21 +6068,7 @@ function clearReportedBindingErrorsForNode(nodeUid) {
6088
6068
  // Responsible for resolving props to values
6089
6069
  function retrievePropValue(args) {
6090
6070
  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
- })();
6071
+ const componentProps = componentOptions.props;
6106
6072
  const nodeProps = node.props;
6107
6073
  if (!componentProps || !nodeProps)
6108
6074
  return {};
@@ -6211,7 +6177,8 @@ function retrievePropValue(args) {
6211
6177
  }
6212
6178
  }
6213
6179
  else if (dataPath &&
6214
- !(type === "choice" && bindedField?.type === "static_value")) {
6180
+ !((type === "choice" || type === "action") &&
6181
+ bindedField?.type === "static_value")) {
6215
6182
  resolvedData = get(data, dataPath, fallbackValue);
6216
6183
  // TEMP — slot-child page-context fallback (PHASE 8 will remove this).
6217
6184
  //
@@ -6306,8 +6273,9 @@ function retrievePropValue(args) {
6306
6273
  }
6307
6274
  }
6308
6275
  else {
6309
- // For choice props, explicitly retrieve saved values from static content store
6310
- if (type === "choice" && bindedField?.type === "static_value") {
6276
+ // For choice/action props, explicitly retrieve saved values from static content store
6277
+ if ((type === "choice" || type === "action") &&
6278
+ bindedField?.type === "static_value") {
6311
6279
  const staticContentKey = bindedField.value; // e.g., "B575hDbLkWhPSfB-alignment"
6312
6280
  // Try to find the saved value in the static content store
6313
6281
  let savedValue = undefined;
@@ -6399,7 +6367,11 @@ function retrievePropValue(args) {
6399
6367
  bindedField: cslpPathOverride ?? dataPath,
6400
6368
  data,
6401
6369
  });
6402
- if (cslpValue) {
6370
+ // `getCslpTag` returns `{}` on a miss, and `{}` is truthy — so the old
6371
+ // `if (cslpValue)` published a tag-shaped object with no tag inside, which
6372
+ // consumers then interpolated as `undefined` (see Repeater's `$items`).
6373
+ // Skip that empty miss sentinel without assuming the metadata's inner shape.
6374
+ if (Object.keys(cslpValue).length) {
6403
6375
  mappedData[`$${field}`] = cslpValue;
6404
6376
  }
6405
6377
  }
@@ -6420,19 +6392,6 @@ function retrievePropValue(args) {
6420
6392
  mappedData["condition"] = node?.metadata?.condition;
6421
6393
  mappedData["mode"] = node?.metadata?.mode;
6422
6394
  }
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
6395
  if (node.type === "section-composition") {
6437
6396
  // Surface the page composer's LIVE binding type for each exposed prop so the
6438
6397
  // SectionComposition renderer can tell an untouched seed from a real override.
@@ -6465,6 +6424,685 @@ function retrievePropValue(args) {
6465
6424
  return mappedData;
6466
6425
  }
6467
6426
 
6427
+ const isServer = () => typeof window === "undefined";
6428
+ const isDev$1 = () => typeof process !== "undefined" && process.env.NODE_ENV === "development";
6429
+ const DEFAULT_STORAGE_KEY = "cs-studio:state";
6430
+ /**
6431
+ * Built-in web-storage backend for `storage: "local" | "session"` — an
6432
+ * in-memory object hydrated from the chosen Storage with write-through on
6433
+ * every set, plus per-key listeners. SSR-safe: with no `window` it serves
6434
+ * memory only (the store's `set` is a server no-op anyway).
6435
+ */
6436
+ function createWebStorageBackend(kind, storageKey) {
6437
+ const storageArea = () => {
6438
+ if (isServer())
6439
+ return null;
6440
+ try {
6441
+ return kind === "local" ? window.localStorage : window.sessionStorage;
6442
+ }
6443
+ catch {
6444
+ return null; // storage blocked (privacy mode / embedded context)
6445
+ }
6446
+ };
6447
+ const values = (() => {
6448
+ const area = storageArea();
6449
+ if (!area)
6450
+ return {};
6451
+ try {
6452
+ const parsed = JSON.parse(area.getItem(storageKey) ?? "{}");
6453
+ // Only a plain object is a valid value map. A stored bare primitive or
6454
+ // array (e.g. a colliding storageKey, or an older write) must NOT become
6455
+ // `values`, or the first `values[key] = ...` throws in strict mode.
6456
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed)
6457
+ ? parsed
6458
+ : {};
6459
+ }
6460
+ catch {
6461
+ return {};
6462
+ }
6463
+ })();
6464
+ const persist = () => {
6465
+ const area = storageArea();
6466
+ if (!area)
6467
+ return;
6468
+ try {
6469
+ area.setItem(storageKey, JSON.stringify(values));
6470
+ }
6471
+ catch {
6472
+ // quota exceeded / storage blocked — state stays in-memory only
6473
+ }
6474
+ };
6475
+ // No `subscribe` bridge: every mutation goes through the SDK's own set()
6476
+ // (nothing else holds a reference to this backend), and the store already
6477
+ // notifies its per-key listeners after each delegated set.
6478
+ return {
6479
+ getState: (key) => values[key],
6480
+ setState: (key, value) => {
6481
+ values[key] = value;
6482
+ persist();
6483
+ },
6484
+ };
6485
+ }
6486
+ /**
6487
+ * Page-global shared state store — the "Bring Your Own State" (BYOS) core.
6488
+ *
6489
+ * Delegates reads/writes to the user's `getState`/`setState` when configured
6490
+ * (Redux, Zustand, plain object, anything), otherwise falls back to an
6491
+ * internal Map. Reactivity is per-key: `set("cart")` notifies ONLY listeners
6492
+ * subscribed to `"cart"`, so unrelated components never re-render.
6493
+ *
6494
+ * One instance per JS runtime via the globalThis registry slot (see
6495
+ * `singleton.ts`) — every surface (components, sections, templates, custom
6496
+ * code) reads and writes the same store.
6497
+ *
6498
+ * SSR: `set` is a no-op with a dev warning (a mutable process-wide store
6499
+ * would leak state across requests); `get` still delegates so a
6500
+ * server-appropriate `getState` (e.g. request-scoped values) works, falling
6501
+ * back to declared defaults.
6502
+ */
6503
+ class StudioStateStore {
6504
+ userConfig = null;
6505
+ internal = new Map();
6506
+ listeners = new Map();
6507
+ variables = new Map();
6508
+ /** Priority tier each declaration came from (see StateVariableTier). */
6509
+ variableTiers = new Map();
6510
+ /** Fired when the DECLARED variable set changes (declare/configure/reset). */
6511
+ variableListeners = new Set();
6512
+ /** One bridge subscription per key into the user's own store. */
6513
+ externalUnsubs = new Map();
6514
+ warnedServerSet = false;
6515
+ /**
6516
+ * Wire the state backend + init-declared variables. Called once from SDK
6517
+ * init; calling again replaces the config (HMR-safe — variables merge,
6518
+ * they don't reset).
6519
+ *
6520
+ * Storage resolution (see StudioStateStorage):
6521
+ * - `storage: "custom"` → user's getState/setState (required).
6522
+ * - `storage: "local"` → built-in localStorage store.
6523
+ * - `storage: "session"` → built-in sessionStorage store.
6524
+ * - omitted → custom when getState+setState are provided,
6525
+ * otherwise the built-in SESSION store.
6526
+ */
6527
+ configure(config) {
6528
+ const hasCustomFns = typeof config.getState === "function" &&
6529
+ typeof config.setState === "function";
6530
+ const storage = config.storage ?? (hasCustomFns ? "custom" : "session");
6531
+ // Reconfigure (HMR / second init): tear down bridges bound to the PREVIOUS
6532
+ // backend before switching, so ensureExternalBridge below rebuilds them
6533
+ // against the new store instead of leaving them pointing at the old one.
6534
+ for (const unsub of this.externalUnsubs.values())
6535
+ unsub();
6536
+ this.externalUnsubs.clear();
6537
+ if (storage === "custom") {
6538
+ if (!hasCustomFns) {
6539
+ throw new Error('[Composable Studio SDK] state storage "custom" requires getState and setState functions');
6540
+ }
6541
+ this.userConfig = {
6542
+ getState: config.getState,
6543
+ setState: config.setState,
6544
+ subscribe: config.subscribe,
6545
+ };
6546
+ }
6547
+ else {
6548
+ if (hasCustomFns && isDev$1()) {
6549
+ 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)`);
6550
+ }
6551
+ this.userConfig = createWebStorageBackend(storage, config.storageKey ?? DEFAULT_STORAGE_KEY);
6552
+ }
6553
+ // Migrate writes made BEFORE configure ran (they landed in the internal Map
6554
+ // because userConfig was null) into the now-resolved backend, so a
6555
+ // pre-init `set("cart:count", 3)` isn't silently dropped when init lands.
6556
+ // Don't clobber a value the new backend already holds (e.g. hydrated Redux
6557
+ // / persisted web storage) — pre-init writes only fill the gaps.
6558
+ for (const [key, value] of this.internal) {
6559
+ try {
6560
+ if (this.userConfig.getState(key) === undefined) {
6561
+ this.userConfig.setState(key, value);
6562
+ }
6563
+ }
6564
+ catch {
6565
+ // backend rejected the migrated write — leave it; not fatal
6566
+ }
6567
+ }
6568
+ this.internal.clear();
6569
+ for (const [key, def] of Object.entries(config.variables ?? {})) {
6570
+ this.declareVariable(key, def, "init");
6571
+ }
6572
+ // Components may have subscribed BEFORE configure ran (e.g. the SDK init
6573
+ // module evaluates after React mounted a state-bound component). The new
6574
+ // backing store can hold different values (persisted state, hydrated
6575
+ // Redux…), so (re)build the external bridge for every already-subscribed
6576
+ // key and wake every existing subscriber to re-read.
6577
+ for (const key of [...this.listeners.keys()]) {
6578
+ this.ensureExternalBridge(key);
6579
+ this.notify(key);
6580
+ }
6581
+ this.notifyVariablesChanged();
6582
+ }
6583
+ /**
6584
+ * Open a single bridge subscription from the user's own store into this
6585
+ * store's per-key listeners, so mutations made OUTSIDE Studio propagate in.
6586
+ * Idempotent and safe to call from both `subscribe` (first listener) and
6587
+ * `configure` (backend arrived/changed after listeners already existed).
6588
+ */
6589
+ ensureExternalBridge(key) {
6590
+ if (!this.userConfig?.subscribe)
6591
+ return;
6592
+ if (this.externalUnsubs.has(key))
6593
+ return;
6594
+ if (!this.listeners.has(key))
6595
+ return; // only bridge keys someone listens to
6596
+ try {
6597
+ const unsub = this.userConfig.subscribe(key, () => this.notify(key));
6598
+ this.externalUnsubs.set(key, typeof unsub === "function" ? unsub : () => { });
6599
+ }
6600
+ catch (err) {
6601
+ console.error(`[Composable Studio SDK] state subscribe("${key}") threw:`, err);
6602
+ }
6603
+ }
6604
+ isConfigured() {
6605
+ return this.userConfig !== null;
6606
+ }
6607
+ /**
6608
+ * Register an author-bindable variable.
6609
+ *
6610
+ * Priority: a `component`-tier declaration (registerComponentStateVariable at component
6611
+ * module scope) OVERRIDES an `init`-tier one (SDK init `state.variables`)
6612
+ * for the same key — deterministically, whichever loads first. An init
6613
+ * declaration never overrides a component one; it only fills keys no
6614
+ * component declared. Same-tier re-declarations (module reload, repeated
6615
+ * imports) keep the first definition and dev-warn only when the type
6616
+ * conflicts. Runtime `set` values always beat declared defaults.
6617
+ */
6618
+ declareVariable(key, def, tier = "component") {
6619
+ const existing = this.variables.get(key);
6620
+ if (existing) {
6621
+ const existingTier = this.variableTiers.get(key) ?? "component";
6622
+ if (tier === "component" && existingTier === "init") {
6623
+ this.variables.set(key, def);
6624
+ this.variableTiers.set(key, tier);
6625
+ // The effective default may have changed — wake this key's subscribers
6626
+ // (e.g. a mounted useStudioState reading the old default) plus the
6627
+ // declared-set listeners.
6628
+ this.notify(key);
6629
+ this.notifyVariablesChanged();
6630
+ return;
6631
+ }
6632
+ if (existing.type !== def.type && isDev$1()) {
6633
+ console.warn(`[Composable Studio SDK] state variable "${key}" already declared as "${existing.type}"; ignoring re-declaration as "${def.type}"`);
6634
+ }
6635
+ return;
6636
+ }
6637
+ this.variables.set(key, def);
6638
+ this.variableTiers.set(key, tier);
6639
+ // A brand-new declaration makes a default available where `get(key)` used
6640
+ // to return undefined. Wake any component that already subscribed to this
6641
+ // key BEFORE the (lazily-imported) declaration landed, so it re-reads the
6642
+ // default instead of staying stuck on undefined.
6643
+ this.notify(key);
6644
+ this.notifyVariablesChanged();
6645
+ }
6646
+ /** All declared (author-bindable) variables. */
6647
+ getVariables() {
6648
+ return Object.fromEntries(this.variables);
6649
+ }
6650
+ /**
6651
+ * Subscribe to declared-variable-set changes. The SDK's Studio bridge uses
6652
+ * this to push the fresh values snapshot to the Data Picker — apps declare
6653
+ * variables from lazily-imported init code, typically AFTER the component
6654
+ * registry synced, so a one-shot pull at sync time reads an empty set.
6655
+ */
6656
+ subscribeVariablesChanged(listener) {
6657
+ this.variableListeners.add(listener);
6658
+ return () => this.variableListeners.delete(listener);
6659
+ }
6660
+ notifyVariablesChanged() {
6661
+ for (const listener of [...this.variableListeners]) {
6662
+ try {
6663
+ listener();
6664
+ }
6665
+ catch (err) {
6666
+ console.error("[Composable Studio SDK] state variables-changed listener threw:", err);
6667
+ }
6668
+ }
6669
+ }
6670
+ isDeclared(key) {
6671
+ return this.variables.has(key);
6672
+ }
6673
+ /**
6674
+ * The declared default for a key, ignoring any live backend value. This is
6675
+ * the server / hydration baseline: SSR and the client's hydration render
6676
+ * must agree, so state-bound content renders the default on both and only
6677
+ * switches to a persisted/live value AFTER hydration.
6678
+ */
6679
+ getDeclaredDefault(key) {
6680
+ return this.variables.get(key)?.defaultValue;
6681
+ }
6682
+ /** Raw backing value with NO declared-default fallback (undefined if unset). */
6683
+ readRaw(key) {
6684
+ if (this.userConfig) {
6685
+ try {
6686
+ return this.userConfig.getState(key);
6687
+ }
6688
+ catch (err) {
6689
+ console.error(`[Composable Studio SDK] getState("${key}") threw:`, err);
6690
+ return undefined;
6691
+ }
6692
+ }
6693
+ return (this.internal.has(key) ? this.internal.get(key) : undefined);
6694
+ }
6695
+ get(key) {
6696
+ let value = this.readRaw(key);
6697
+ if (value === undefined) {
6698
+ value = this.variables.get(key)?.defaultValue;
6699
+ }
6700
+ return value;
6701
+ }
6702
+ set(key, next) {
6703
+ if (isServer()) {
6704
+ if (!this.warnedServerSet && isDev$1()) {
6705
+ this.warnedServerSet = true;
6706
+ console.warn("[Composable Studio SDK] setState is a no-op during server rendering — state writes are client-only");
6707
+ }
6708
+ return;
6709
+ }
6710
+ // The functional updater sees the effective value (default-aware)...
6711
+ const effectivePrev = this.get(key);
6712
+ const value = typeof next === "function"
6713
+ ? next(effectivePrev)
6714
+ : next;
6715
+ // ...but dedup against the RAW backing value, not get(). Comparing against
6716
+ // get() (which folds in the declared default) would swallow the first write
6717
+ // of a value that equals the default — e.g. set("cart:count", 0) when the
6718
+ // default is 0 — so the backend/custom store never receives it.
6719
+ const rawPrev = this.readRaw(key);
6720
+ if (Object.is(rawPrev, value))
6721
+ return;
6722
+ if (this.userConfig) {
6723
+ this.userConfig.setState(key, value);
6724
+ }
6725
+ else {
6726
+ this.internal.set(key, value);
6727
+ }
6728
+ this.notify(key);
6729
+ }
6730
+ /**
6731
+ * Per-key subscription. Returns an unsubscribe. When the user supplied
6732
+ * their own `subscribe`, a single bridge per key is also registered so
6733
+ * store mutations made OUTSIDE Studio propagate into Studio listeners.
6734
+ */
6735
+ subscribe(key, listener) {
6736
+ if (isServer())
6737
+ return () => { };
6738
+ let set = this.listeners.get(key);
6739
+ if (!set) {
6740
+ set = new Set();
6741
+ this.listeners.set(key, set);
6742
+ }
6743
+ set.add(listener);
6744
+ this.ensureExternalBridge(key);
6745
+ return () => {
6746
+ const listeners = this.listeners.get(key);
6747
+ listeners?.delete(listener);
6748
+ if (listeners && listeners.size === 0) {
6749
+ this.listeners.delete(key);
6750
+ const unsubExternal = this.externalUnsubs.get(key);
6751
+ if (unsubExternal) {
6752
+ this.externalUnsubs.delete(key);
6753
+ unsubExternal();
6754
+ }
6755
+ }
6756
+ };
6757
+ }
6758
+ notify(key) {
6759
+ const listeners = this.listeners.get(key);
6760
+ if (!listeners)
6761
+ return;
6762
+ for (const listener of [...listeners]) {
6763
+ try {
6764
+ listener();
6765
+ }
6766
+ catch (err) {
6767
+ console.error(`[Composable Studio SDK] state listener for "${key}" threw:`, err);
6768
+ }
6769
+ }
6770
+ }
6771
+ /**
6772
+ * Soft reset for hosts that want per-page state on a client-side route
6773
+ * change (this is what the public `studioState.reset()` calls). Clears the
6774
+ * SDK-owned internal values and wakes every subscriber to re-read — but
6775
+ * deliberately KEEPS the wired backend, the declared variables, and all live
6776
+ * subscriptions. Tearing those down here (the previous behavior) disconnected
6777
+ * a configured custom store, wiped every declaration, and froze every still-
6778
+ * mounted `useStudioState`. For a full teardown (tests / HMR) use `resetAll`.
6779
+ *
6780
+ * A configured custom or web-storage backend owns its own values and is left
6781
+ * intact — the host resets its own store if it wants those cleared too.
6782
+ */
6783
+ reset() {
6784
+ this.internal.clear();
6785
+ for (const key of [...this.listeners.keys()]) {
6786
+ this.notify(key);
6787
+ }
6788
+ this.notifyVariablesChanged();
6789
+ }
6790
+ /**
6791
+ * Full teardown — internal values, declarations, config, listeners, and
6792
+ * external bridges. For tests and HMR (the singleton drop), NOT for
6793
+ * route-change resets (see `reset`).
6794
+ */
6795
+ resetAll() {
6796
+ for (const unsub of this.externalUnsubs.values())
6797
+ unsub();
6798
+ this.externalUnsubs.clear();
6799
+ this.internal.clear();
6800
+ this.listeners.clear();
6801
+ this.variables.clear();
6802
+ this.variableTiers.clear();
6803
+ this.userConfig = null;
6804
+ this.warnedServerSet = false;
6805
+ this.notifyVariablesChanged();
6806
+ }
6807
+ }
6808
+
6809
+ /**
6810
+ * Lazily create (or reuse) the page-global StudioStateStore in the SDK's
6811
+ * versioned globalThis slot. Same pattern as the component/design registries
6812
+ * — survives Next.js RSC/client module-graph splits so every surface talks
6813
+ * to the same store instance.
6814
+ */
6815
+ function getStateStoreInstance() {
6816
+ const store = getGlobalStudioStore();
6817
+ if (!store.stateStore) {
6818
+ store.stateStore = new StudioStateStore();
6819
+ }
6820
+ return store.stateStore;
6821
+ }
6822
+ /** Test-only: drop the singleton so the next access builds a fresh store. */
6823
+ function resetStateStoreInstance() {
6824
+ const store = getGlobalStudioStore();
6825
+ // Full teardown (unsub bridges, drop config/vars/listeners) — not the soft
6826
+ // route-change reset() — since the slot itself is being dropped.
6827
+ store.stateStore?.resetAll();
6828
+ store.stateStore = null;
6829
+ }
6830
+
6831
+ function getRegistry() {
6832
+ const store = getGlobalStudioStore();
6833
+ if (!store.functionRegistry) {
6834
+ store.functionRegistry = {
6835
+ functions: new Map(),
6836
+ changeListeners: new Set(),
6837
+ };
6838
+ }
6839
+ // Slot created by an older module instance (globalThis singleton outlives
6840
+ // module graphs) — patch the field in rather than dropping registrations.
6841
+ if (!store.functionRegistry.changeListeners) {
6842
+ store.functionRegistry.changeListeners = new Set();
6843
+ }
6844
+ return store.functionRegistry;
6845
+ }
6846
+ function notifyFunctionsChanged() {
6847
+ for (const listener of [...getRegistry().changeListeners]) {
6848
+ try {
6849
+ listener();
6850
+ }
6851
+ catch (err) {
6852
+ console.error("[Composable Studio SDK] studio-functions change listener threw:", err);
6853
+ }
6854
+ }
6855
+ }
6856
+ /**
6857
+ * Subscribe to registry changes (functions added / reset). Used by the SDK's
6858
+ * Studio bridge to push the fresh name list to the Studio props panel whenever
6859
+ * the app registers functions — regardless of whether that happens before or
6860
+ * after the component registry sync.
6861
+ */
6862
+ function subscribeStudioFunctionsChanged(listener) {
6863
+ const registry = getRegistry();
6864
+ registry.changeListeners.add(listener);
6865
+ return () => registry.changeListeners.delete(listener);
6866
+ }
6867
+ const isDev = () => typeof process !== "undefined" && process.env.NODE_ENV === "development";
6868
+ /**
6869
+ * Register named custom functions — the app's business logic that components
6870
+ * invoke by NAME. Call as many times as you like (e.g. one call per feature
6871
+ * module); registrations MERGE. Re-registering an existing name overwrites it
6872
+ * with a dev warning (supports HMR).
6873
+ *
6874
+ * ```ts
6875
+ * registerStudioFunctions({
6876
+ * "cart:add": (ctx, args) => {
6877
+ * ctx.set("cart:count", (prev) => (prev ?? 0) + 1);
6878
+ * ctx.set("cart:last_added", args?.sku ?? "");
6879
+ * },
6880
+ * "coupon:apply": (ctx, args) => {
6881
+ * const discounts = { SAVE10: 10, SAVE20: 20 };
6882
+ * ctx.set("checkout:discount", discounts[args?.code] ?? 0);
6883
+ * },
6884
+ * });
6885
+ * ```
6886
+ */
6887
+ function registerStudioFunctions(functions) {
6888
+ const registry = getRegistry();
6889
+ for (const [name, fn] of Object.entries(functions ?? {})) {
6890
+ if (typeof fn !== "function") {
6891
+ console.warn(`[Composable Studio SDK] registerStudioFunctions: "${name}" is not a function — skipped`);
6892
+ continue;
6893
+ }
6894
+ if (registry.functions.has(name) && isDev()) {
6895
+ console.warn(`[Composable Studio SDK] studio function "${name}" re-registered (overwriting previous)`);
6896
+ }
6897
+ registry.functions.set(name, fn);
6898
+ }
6899
+ notifyFunctionsChanged();
6900
+ }
6901
+ /** Names of every registered function — for debugging / future picker UI. */
6902
+ function getStudioFunctionNames() {
6903
+ return [...getRegistry().functions.keys()];
6904
+ }
6905
+ /**
6906
+ * Invoke a registered function by name from ANY component or code.
6907
+ *
6908
+ * ```ts
6909
+ * <button onClick={() => callStudioFunction("cart:add", { sku })}>Add</button>
6910
+ * ```
6911
+ *
6912
+ * Never throws into the UI: a missing name warns and returns undefined; sync
6913
+ * throws and async rejections are caught and logged. The function receives
6914
+ * the shared-state ctx as its first argument.
6915
+ */
6916
+ function callStudioFunction(name, ...args) {
6917
+ const fn = getRegistry().functions.get(name);
6918
+ if (!fn) {
6919
+ console.warn(`[Composable Studio SDK] studio function "${name}" is not registered. Did you call registerStudioFunctions()?`);
6920
+ return undefined;
6921
+ }
6922
+ const store = getStateStoreInstance();
6923
+ const ctx = {
6924
+ get: (key) => store.get(key),
6925
+ set: (key, next) => store.set(key, next),
6926
+ subscribe: (key, listener) => store.subscribe(key, listener),
6927
+ };
6928
+ try {
6929
+ // Forward every argument the caller passed (action-prop callbacks can be
6930
+ // invoked with multiple positional args); the cast bridges the variadic
6931
+ // call to StudioFunction's (ctx, args?, ...rest) shape.
6932
+ const result = fn(ctx, ...args);
6933
+ if (result &&
6934
+ typeof result.then === "function" &&
6935
+ typeof result.catch === "function") {
6936
+ return result.catch((err) => {
6937
+ console.error(`[Composable Studio SDK] studio function "${name}" rejected:`, err);
6938
+ return undefined;
6939
+ });
6940
+ }
6941
+ return result;
6942
+ }
6943
+ catch (err) {
6944
+ console.error(`[Composable Studio SDK] studio function "${name}" threw:`, err);
6945
+ return undefined;
6946
+ }
6947
+ }
6948
+ /** Test-only: clear all registered functions. */
6949
+ function resetStudioFunctions() {
6950
+ getRegistry().functions.clear();
6951
+ notifyFunctionsChanged();
6952
+ }
6953
+
6954
+ /**
6955
+ * Collect the DECLARED state variable keys a node's prop bindings reference.
6956
+ *
6957
+ * Per the BYOS design there is no new binding type: authors bind state
6958
+ * through the existing `component_props` source. A `component_props` binding
6959
+ * whose value matches a declared state variable resolves from the shared
6960
+ * state store instead of the composition's external data — this helper finds
6961
+ * exactly those keys so the renderer can subscribe the node to them.
6962
+ *
6963
+ * Undeclared keys never match (ad-hoc state is code-only), and nodes without
6964
+ * state-backed bindings return an empty array — the zero-cost path.
6965
+ */
6966
+ /**
6967
+ * The longest dotted-prefix of `path` that is a declared state key, or
6968
+ * undefined. `product:price` (declared, no dot) returns itself;
6969
+ * `user:profile.tier` returns the declared root `user:profile`; a path with no
6970
+ * declared prefix returns undefined (an ordinary external-data binding).
6971
+ */
6972
+ function declaredKeyForPath(store, path) {
6973
+ if (store.isDeclared(path))
6974
+ return path;
6975
+ const segments = path.split(".");
6976
+ for (let end = segments.length - 1; end >= 1; end--) {
6977
+ const prefix = segments.slice(0, end).join(".");
6978
+ if (store.isDeclared(prefix))
6979
+ return prefix;
6980
+ }
6981
+ return undefined;
6982
+ }
6983
+ function collectStateBindingKeys(node) {
6984
+ if (!node)
6985
+ return [];
6986
+ const store = getStateStoreInstance();
6987
+ const keys = new Set();
6988
+ const consider = (binding) => {
6989
+ const key = getComponentPropsBindingKey(binding);
6990
+ if (!key)
6991
+ return;
6992
+ // A binding to a nested sub-field of a declared object/array state variable
6993
+ // is a DOTTED path (the picker writes `pathSegments.join(".")`), e.g.
6994
+ // "user:profile.tier" or "cart:items.0.name". Only the ROOT ("user:profile")
6995
+ // is declared, so collect+subscribe that — the snapshot merges the whole
6996
+ // object under it and the sub-path resolves via the normal component_props
6997
+ // path walk. Top-level primitive keys (no dot) match directly.
6998
+ const declared = declaredKeyForPath(store, key);
6999
+ if (declared)
7000
+ keys.add(declared);
7001
+ };
7002
+ // Scan BOTH attribute bindings (metadata.bindings, e.g. attrs.id) and prop
7003
+ // bindings — symmetric with getNodeBoundFunctionName. Scanning only props
7004
+ // left attribute-bound state variables un-snapshotted and un-subscribed
7005
+ // (rendered empty, never reactive).
7006
+ for (const binding of Object.values(node.metadata?.bindings ?? {})) {
7007
+ consider(binding);
7008
+ }
7009
+ for (const prop of Object.values(node.props ?? {})) {
7010
+ consider(prop?.binding);
7011
+ }
7012
+ return [...keys];
7013
+ }
7014
+ /**
7015
+ * Snapshot of the given declared state keys — `{ key: currentValue }` —
7016
+ * merged by the renderer into `data.component_props` before prop resolution
7017
+ * so the existing `component_props` path machinery (fallbacks, type
7018
+ * validation, editor error badges) resolves state values unchanged.
7019
+ *
7020
+ * Keys whose current value is `undefined` (declared but unset, no default) are
7021
+ * OMITTED — spreading `{key: undefined}` over `component_props` would wipe an
7022
+ * external/authored value of the same name, silently losing server content.
7023
+ */
7024
+ function getStateValuesFor(keys) {
7025
+ const store = getStateStoreInstance();
7026
+ const out = {};
7027
+ for (const key of keys) {
7028
+ const value = store.get(key);
7029
+ if (value !== undefined)
7030
+ out[key] = value;
7031
+ }
7032
+ return out;
7033
+ }
7034
+ /**
7035
+ * Like getStateValuesFor but reads ONLY the declared defaults, never the live
7036
+ * backend value. Used as the server / hydration baseline so SSR and the client
7037
+ * hydration render agree (a persisted local/session value read on the client
7038
+ * but not the server would otherwise be a hydration mismatch). Undefined
7039
+ * defaults are omitted for the same reason as getStateValuesFor.
7040
+ */
7041
+ function getStateDefaultsFor(keys) {
7042
+ const store = getStateStoreInstance();
7043
+ const out = {};
7044
+ for (const key of keys) {
7045
+ const value = store.getDeclaredDefault(key);
7046
+ if (value !== undefined)
7047
+ out[key] = value;
7048
+ }
7049
+ return out;
7050
+ }
7051
+ /**
7052
+ * Extract the Component Props KEY a binding refers to. The picker writes the
7053
+ * key either as a plain string value or wrapped in a `{ path: { key: {} } }`
7054
+ * object (template-style) — accept both so the function detection below
7055
+ * doesn't depend on which surface authored the binding.
7056
+ */
7057
+ function getComponentPropsBindingKey(binding) {
7058
+ const b = binding;
7059
+ if (!b || b.type !== DATA_SOURCES.COMPONENT_PROPS)
7060
+ return undefined;
7061
+ if (typeof b.value === "string")
7062
+ return b.value || undefined;
7063
+ const path = b.value
7064
+ ?.path;
7065
+ if (path && typeof path === "object") {
7066
+ const [first] = Object.keys(path);
7067
+ return first || undefined;
7068
+ }
7069
+ return undefined;
7070
+ }
7071
+ /**
7072
+ * The registered studio FUNCTION a node is bound to, if any.
7073
+ *
7074
+ * Authors assign behavior from the Data Picker's Component Props section
7075
+ * (functions are listed under the state variables): the picker writes an
7076
+ * ordinary `component_props` binding — on an attribute (`metadata.bindings`,
7077
+ * e.g. `attrs.id`) or a prop — whose key is a registered function NAME.
7078
+ * Because functions and data share the source, "is it a function?" is decided
7079
+ * right here: key ∈ function registry → behavior, otherwise it stays a plain
7080
+ * data binding and is ignored by this helper.
7081
+ *
7082
+ * The renderer attaches the returned name as the node's click handler
7083
+ * (`callStudioFunction(name)`), which is what makes assignment work for ANY
7084
+ * component with zero prop declarations.
7085
+ */
7086
+ function getNodeBoundFunctionName(node) {
7087
+ if (!node)
7088
+ return undefined;
7089
+ const registered = getStudioFunctionNames();
7090
+ if (registered.length === 0)
7091
+ return undefined;
7092
+ const names = new Set(registered);
7093
+ for (const binding of Object.values(node.metadata?.bindings ?? {})) {
7094
+ const key = getComponentPropsBindingKey(binding);
7095
+ if (key && names.has(key))
7096
+ return key;
7097
+ }
7098
+ for (const prop of Object.values(node.props ?? {})) {
7099
+ const key = getComponentPropsBindingKey(prop?.binding);
7100
+ if (key && names.has(key))
7101
+ return key;
7102
+ }
7103
+ return undefined;
7104
+ }
7105
+
6468
7106
  class BreakpointRegistry {
6469
7107
  breakpoints = [];
6470
7108
  requiredFields = ["id", "query", "previewSize"];
@@ -6531,6 +7169,149 @@ class BreakpointRegistry {
6531
7169
  }
6532
7170
  }
6533
7171
 
7172
+ /**
7173
+ * Declare an author-bindable state variable at component/section module
7174
+ * scope — the "component-declared" tier. Call at module load time (top of
7175
+ * the file, next to the component definition):
7176
+ *
7177
+ * ```ts
7178
+ * registerComponentStateVariable("cart:filter", { type: "string", defaultValue: "" });
7179
+ *
7180
+ * export function CartFilter() {
7181
+ * const [filter, setFilter] = useStudioState<string>("cart:filter");
7182
+ * ...
7183
+ * }
7184
+ * ```
7185
+ *
7186
+ * Declared variables appear for binding inside the existing External Data
7187
+ * source; undeclared keys stay code-only (ad-hoc tier).
7188
+ *
7189
+ * Priority: component-level declarations WIN over the same key declared
7190
+ * globally at init (`state.variables`) — deterministically, regardless of
7191
+ * which module evaluated first. The global declaration is used only for keys
7192
+ * no component declared. Runtime `set` values always beat declared defaults.
7193
+ */
7194
+ function registerComponentStateVariable(key, options) {
7195
+ if (!key || typeof key !== "string") {
7196
+ throw new Error("[Composable Studio SDK] registerComponentStateVariable requires a non-empty string key");
7197
+ }
7198
+ getStateStoreInstance().declareVariable(key, options, "component");
7199
+ }
7200
+ /**
7201
+ * Imperative access to the shared state store — for custom user code outside
7202
+ * React (event handlers, analytics glue, business logic):
7203
+ *
7204
+ * ```ts
7205
+ * import { studioState } from "@contentstack/studio-react";
7206
+ *
7207
+ * studioState.set("cart:count", (prev) => (prev ?? 0) + 1);
7208
+ * const count = studioState.get<number>("cart:count");
7209
+ * const stop = studioState.subscribe("cart:count", () => console.log("changed"));
7210
+ * ```
7211
+ *
7212
+ * Same store instance the `useStudioState` hook and author bindings use —
7213
+ * one source of truth across components, sections, templates, and code.
7214
+ */
7215
+ /**
7216
+ * Snapshot of every DECLARED state variable with its CURRENT value —
7217
+ * `[{ key, value }]`. This is what the Studio Data Picker lists under
7218
+ * Component Props so authors can bind the values the app made available
7219
+ * (init `state.variables`, `registerComponentStateVariable`) — e.g. `price → 2999`.
7220
+ *
7221
+ * Only declared variables are enumerable: BYOS user stores expose key-based
7222
+ * `getState` with no key listing, so ad-hoc (code-only) keys can't be swept.
7223
+ */
7224
+ function getStudioStateSnapshot() {
7225
+ const store = getStateStoreInstance();
7226
+ return Object.keys(store.getVariables()).map((key) => ({
7227
+ key,
7228
+ value: store.get(key),
7229
+ }));
7230
+ }
7231
+ /**
7232
+ * Subscribe to declared-variable-set changes on the page-global store —
7233
+ * passthrough for the Studio bridge (see StudioStateStore.subscribeVariablesChanged).
7234
+ */
7235
+ function subscribeStudioStateVariablesChanged(listener) {
7236
+ return getStateStoreInstance().subscribeVariablesChanged(listener);
7237
+ }
7238
+ const studioState = {
7239
+ get(key) {
7240
+ return getStateStoreInstance().get(key);
7241
+ },
7242
+ set(key, next) {
7243
+ getStateStoreInstance().set(key, next);
7244
+ },
7245
+ subscribe(key, listener) {
7246
+ return getStateStoreInstance().subscribe(key, listener);
7247
+ },
7248
+ /** Clear all state — call on client-side route change if you want per-page state. */
7249
+ reset() {
7250
+ getStateStoreInstance().reset();
7251
+ },
7252
+ };
7253
+ /**
7254
+ * Declare a SET of variables at the INIT tier — same priority as SDK init
7255
+ * `state.variables`, so later component-level `registerComponentStateVariable` calls
7256
+ * still override them.
7257
+ *
7258
+ * Purpose: SSR hydration alignment. The server declares variables at module
7259
+ * scope (server init file), but apps typically run the CLIENT init from a
7260
+ * lazily-imported module — AFTER hydration. State-bound nodes then hydrate
7261
+ * against undeclared keys and mismatch the server HTML. Import a tiny module
7262
+ * that calls this at module scope (e.g. from _app) so declarations exist on
7263
+ * the client BEFORE hydration:
7264
+ *
7265
+ * ```ts
7266
+ * // lib/register-state-variables.ts — imported statically by _app
7267
+ * registerGlobalStateVariables(studioStateConfig.variables ?? {});
7268
+ * ```
7269
+ */
7270
+ function registerGlobalStateVariables(variables) {
7271
+ const store = getStateStoreInstance();
7272
+ for (const [key, def] of Object.entries(variables ?? {})) {
7273
+ store.declareVariable(key, def, "init");
7274
+ }
7275
+ }
7276
+
7277
+ /**
7278
+ * Swap resolved `action` props (registered function NAMES saved from the
7279
+ * Studio props panel) for real callables before the props reach the
7280
+ * component. Runs in both renderers (live + canvas) right after
7281
+ * `retrievePropValue`, so ANY component — SDK basic or app-registered —
7282
+ * that declares a `{ type: "action" }` prop receives an invokable function:
7283
+ *
7284
+ * ```tsx
7285
+ * function Card({ onBuy }: { onBuy?: (...args: unknown[]) => unknown }) {
7286
+ * return <button onClick={() => onBuy?.({ sku: "X1" })}>Buy</button>;
7287
+ * }
7288
+ * ```
7289
+ *
7290
+ * An unset/empty selection resolves to `undefined` (component can feature-
7291
+ * detect); a missing function name is contained inside `callStudioFunction`
7292
+ * (warn, no crash). Non-action props pass through untouched.
7293
+ */
7294
+ function wrapActionProps(componentProps, resolvedProps) {
7295
+ if (!componentProps)
7296
+ return resolvedProps;
7297
+ let wrapped = null;
7298
+ for (const [name, def] of Object.entries(componentProps)) {
7299
+ const type = typeof def === "string" ? def : def?.type;
7300
+ if (type !== "action")
7301
+ continue;
7302
+ const value = resolvedProps[name];
7303
+ if (typeof value === "function")
7304
+ continue; // already callable (direct usage)
7305
+ if (!wrapped)
7306
+ wrapped = { ...resolvedProps };
7307
+ const functionName = typeof value === "string" ? value.trim() : "";
7308
+ wrapped[name] = functionName
7309
+ ? (...args) => callStudioFunction(functionName, ...args)
7310
+ : undefined;
7311
+ }
7312
+ return wrapped ?? resolvedProps;
7313
+ }
7314
+
6534
7315
  exports.ALLOWED_DESIGN_VALUES_LEVELS = ALLOWED_DESIGN_VALUES_LEVELS;
6535
7316
  exports.BUILT_IN_COMPONENTS = BUILT_IN_COMPONENTS;
6536
7317
  exports.BreakpointRegistry = BreakpointRegistry;
@@ -6546,7 +7327,10 @@ exports.JSONRTERegistry = JSONRTERegistry;
6546
7327
  exports.STYLE_SECTIONS_OPTIONS = STYLE_SECTIONS_OPTIONS;
6547
7328
  exports.STYLE_SECTION_CATEGORIES = STYLE_SECTION_CATEGORIES;
6548
7329
  exports.SYSTEM_COMPONENTS = SYSTEM_COMPONENTS;
7330
+ exports.StudioStateStore = StudioStateStore;
7331
+ exports.callStudioFunction = callStudioFunction;
6549
7332
  exports.clearReportedBindingErrorsForNode = clearReportedBindingErrorsForNode;
7333
+ exports.collectStateBindingKeys = collectStateBindingKeys;
6550
7334
  exports.convertBindingPath = convertBindingPath;
6551
7335
  exports.getBindingString = getBindingString;
6552
7336
  exports.getComponentRegistryInstance = getComponentRegistryInstance;
@@ -6558,21 +7342,34 @@ exports.getDesignClassesNames = getDesignClassesNames;
6558
7342
  exports.getDesignRegistryInstance = getDesignRegistryInstance;
6559
7343
  exports.getFlattenedData = getFlattenedData;
6560
7344
  exports.getGlobalStudioStore = getGlobalStudioStore;
7345
+ exports.getNodeBoundFunctionName = getNodeBoundFunctionName;
6561
7346
  exports.getPlaceHolderComponent = getPlaceHolderComponent;
6562
7347
  exports.getRepeaterBinding = getRepeaterBinding;
6563
7348
  exports.getRepeaterContextPath = getRepeaterContextPath;
6564
7349
  exports.getSectionUIDFromNode = getSectionUIDFromNode;
6565
7350
  exports.getSlotData = getSlotData;
6566
- exports.getSymbolUIDFromNode = getSymbolUIDFromNode;
6567
- exports.getSymbolUIDFromUID = getSymbolUIDFromUID;
7351
+ exports.getStateDefaultsFor = getStateDefaultsFor;
7352
+ exports.getStateStoreInstance = getStateStoreInstance;
7353
+ exports.getStateValuesFor = getStateValuesFor;
7354
+ exports.getStudioFunctionNames = getStudioFunctionNames;
7355
+ exports.getStudioStateSnapshot = getStudioStateSnapshot;
6568
7356
  exports.hasComponentRegistryInstance = hasComponentRegistryInstance;
6569
7357
  exports.hasDesignRegistryInstance = hasDesignRegistryInstance;
6570
7358
  exports.isDataMatchingPropType = isDataMatchingPropType;
6571
7359
  exports.isKnownType = isKnownType;
6572
7360
  exports.normalizeSingleSelectChoiceValue = normalizeSingleSelectChoiceValue;
7361
+ exports.registerComponentStateVariable = registerComponentStateVariable;
7362
+ exports.registerGlobalStateVariables = registerGlobalStateVariables;
7363
+ exports.registerStudioFunctions = registerStudioFunctions;
6573
7364
  exports.resetComponentRegistryInstance = resetComponentRegistryInstance;
6574
7365
  exports.resetDesignRegistryInstance = resetDesignRegistryInstance;
6575
7366
  exports.resetGlobalStudioStore = resetGlobalStudioStore;
7367
+ exports.resetStateStoreInstance = resetStateStoreInstance;
7368
+ exports.resetStudioFunctions = resetStudioFunctions;
6576
7369
  exports.resolveMetadataBindings = resolveMetadataBindings;
6577
7370
  exports.retrievePropValue = retrievePropValue;
7371
+ exports.studioState = studioState;
7372
+ exports.subscribeStudioFunctionsChanged = subscribeStudioFunctionsChanged;
7373
+ exports.subscribeStudioStateVariablesChanged = subscribeStudioStateVariablesChanged;
7374
+ exports.wrapActionProps = wrapActionProps;
6578
7375
  //# sourceMappingURL=index.cjs.map