@contentstack/studio-client 1.7.0 → 1.7.1

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/breakpoints/BreakpointManager.js +1 -0
  2. package/dist/breakpoints/BreakpointManager.js.map +1 -1
  3. package/dist/composable-studio/collect-data-needs.js +78 -4
  4. package/dist/composable-studio/collect-data-needs.js.map +1 -1
  5. package/dist/composable-studio/composition-metadata.js +75 -0
  6. package/dist/composable-studio/composition-metadata.js.map +1 -0
  7. package/dist/composable-studio/sdk.js +682 -191
  8. package/dist/composable-studio/sdk.js.map +1 -1
  9. package/dist/composable-studio/studio-intelligence.manager.js +1 -0
  10. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  11. package/dist/config/stack-sdk-wrapper.js +1 -0
  12. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  13. package/dist/context-menu/context-menu.js +1 -0
  14. package/dist/context-menu/context-menu.js.map +1 -1
  15. package/dist/dnd/dnd-manager.js +1 -0
  16. package/dist/dnd/dnd-manager.js.map +1 -1
  17. package/dist/highlight-node/highlight-node-manager.js +1 -0
  18. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  19. package/dist/highlight-node/highlight-node.js +1 -0
  20. package/dist/highlight-node/highlight-node.js.map +1 -1
  21. package/dist/index.d.ts +396 -229
  22. package/dist/index.js +3 -0
  23. package/dist/index.js.map +1 -1
  24. package/dist/studio-internal/dist/utils/section-slot-walker.js.map +1 -0
  25. package/dist/{packages/studio-internal → studio-internal}/dist/utils/spec-compression.js +1 -1
  26. package/dist/studio-internal/dist/utils/spec-compression.js.map +1 -0
  27. package/dist/utils/constants.js +1 -1
  28. package/dist/utils/editor-mode.js +142 -0
  29. package/dist/utils/editor-mode.js.map +1 -0
  30. package/dist/utils/reference_fetcher.js +1 -1
  31. package/package.json +8 -7
  32. package/dist/node_modules/fflate/esm/browser.js +0 -378
  33. package/dist/node_modules/fflate/esm/browser.js.map +0 -1
  34. package/dist/packages/studio-internal/dist/utils/section-slot-walker.js.map +0 -1
  35. package/dist/packages/studio-internal/dist/utils/spec-compression.js.map +0 -1
  36. /package/dist/{packages/studio-internal → studio-internal}/dist/utils/section-slot-walker.js +0 -0
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as _contentstack_studio_internal from '@contentstack/studio-internal';
2
- import { Node, BindingType, PathNode, Path, Operation, Descendant, Condition, NodeStyles } from '@contentstack/studio-internal';
2
+ import { Node, BindingType, PathNode, Operation, Descendant, Path, Condition, NodeStyles } from '@contentstack/studio-internal';
3
3
  import * as _contentstack_studio_registry from '@contentstack/studio-registry';
4
- import { RawStaticValue, ICSEntryReference, StudioSpecData, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
4
+ import { RawStaticValue, ICSEntryReference, StudioSpecData, DataSources, SectionScopedDataSources, StaticValue, BreakpointInput, Breakpoint } from '@contentstack/studio-registry';
5
5
  export { Breakpoint } from '@contentstack/studio-registry';
6
6
  import * as _contentstack_studio_messenger from '@contentstack/studio-messenger';
7
7
  import { CompositionQuery, CompositionQueryInput, ComposableStudioQueryParams, ComposableStudioQueryParamsKeys, HiddenElementNotificationEventData, POST_MESSAGE_EVENTS } from '@contentstack/studio-messenger';
@@ -637,6 +637,7 @@ declare const studioSdk: {
637
637
  getConfig(): Config;
638
638
  isInsideStudioFrame: () => boolean;
639
639
  fetchSpec: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean, searchParams?: URLSearchParams) => Promise<StudioSpec>;
640
+ fetchCompositionSpecOnly: (queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, skipComponentLoading?: boolean) => Promise<StudioSpec>;
640
641
  fetchMultipleSpecs: (queries: _contentstack_studio_messenger.CompositionQuery[], options?: CompositionQueryOptions) => Promise<StudioSpec[]>;
641
642
  fetchData: (compositionEntry: CompositionEntry, queryOptions: _contentstack_studio_messenger.CompositionQuery, options?: CompositionQueryOptions, sectionEntries?: SectionCompositionEntry[], searchParams?: URLSearchParams) => Promise<_contentstack_studio_registry.StudioSpecData>;
642
643
  fetchTemplateEntry: (fetchOptions: {
@@ -652,6 +653,7 @@ declare const studioSdk: {
652
653
  };
653
654
  public: {
654
655
  fetchCompositionData: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioComponentSpecOptions>;
656
+ fetchComposition: (queryOptions: CompositionQueryForSSRInput, options?: CompositionQueryOptions) => Promise<StudioSpec>;
655
657
  getConfig: () => Pick<Config, "contentTypeUid" | "cslp" | "openInStudioButton">;
656
658
  };
657
659
  };
@@ -667,6 +669,396 @@ declare const NODE_TO_ELEMENT: WeakMap<any, HTMLElement>;
667
669
  declare const NODE_TO_PATH_NODE: WeakMap<any, PathNode>;
668
670
  declare const NODE_TO_PARENT: WeakMap<any, any>;
669
671
 
672
+ declare const findPath: (node: Descendant) => Path;
673
+ declare const findPathForElement: (el: HTMLElement) => Path;
674
+ declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
675
+
676
+ declare function isCompositionBeingEdited(compositionUid: string): boolean;
677
+
678
+ declare const queryParam: {
679
+ get(key: ComposableStudioQueryParamsKeys): string | null;
680
+ has(key: ComposableStudioQueryParamsKeys): boolean;
681
+ };
682
+ declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
683
+
684
+ declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
685
+ declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
686
+ declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
687
+ declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
688
+ /**
689
+ * Counterpart to setStaticEntryInDS: drop a single resolved additional entry
690
+ * from the contentstack data source bucket. Called when the author removes an
691
+ * entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
692
+ * push (which merges at the dataSources level); without it the removed entry's
693
+ * data lingers and keeps rendering.
694
+ */
695
+ declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
696
+ declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
697
+ declare const getBindingStringForCS: (binding: BindingType) => string;
698
+ type EntriesResponse<T> = {
699
+ entries: T[];
700
+ } | [T[]];
701
+ declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
702
+
703
+ declare const isInsideVisualBuilderFrame: () => boolean;
704
+
705
+ /**
706
+ * Checks if the current context is inside an iframe.
707
+ *
708
+ * @returns {boolean} True if inside an iframe, false otherwise.
709
+ */
710
+ declare const isInsideIframe: () => boolean;
711
+
712
+ /** The three author-facing render contexts a host app can find itself in. */
713
+ type StudioMode = "canvas" | "preview" | "visitor";
714
+ /**
715
+ * The query param Studio always appends to canvas / template-preview iframe
716
+ * URLs. Part of the stable contract — changing its value is a breaking
717
+ * change and will be release-noted as such.
718
+ */
719
+ declare const STUDIO_CANVAS_QUERY_PARAM: "cs-composable-studio";
720
+ /**
721
+ * Class the SDK bootstrap adds to `<html>` when running inside the Studio
722
+ * canvas. Available for CSS-only gating (e.g. `html.cs-studio-canvas
723
+ * #onetrust-banner-sdk { display: none }`).
724
+ */
725
+ declare const STUDIO_MODE_HTML_CLASS = "cs-studio-canvas";
726
+ declare global {
727
+ interface Window {
728
+ __CS_STUDIO_MODE__?: StudioMode;
729
+ }
730
+ }
731
+ /**
732
+ * Detects the current Studio mode.
733
+ *
734
+ * Browser: the `window.__CS_STUDIO_MODE__` marker wins when present (it
735
+ * survives client-side navigations that strip query params); otherwise the
736
+ * URL's query params decide.
737
+ *
738
+ * Server: pass the request's search params (string or URLSearchParams) to
739
+ * get a real answer; with no arguments it safely reports `"visitor"`.
740
+ */
741
+ declare function detectStudioMode(searchQuery?: string | URLSearchParams): StudioMode;
742
+ /**
743
+ * True when the host app is rendering inside the Studio canvas (or Visual
744
+ * Builder frame) — the one check to gate cookie banners, chat widgets,
745
+ * analytics, marketing pixels, and feature-flag bootstraps behind.
746
+ *
747
+ * SSR-safe: returns false on the server unless the request's search params
748
+ * are passed explicitly.
749
+ */
750
+ declare function isStudioCanvas(searchQuery?: string | URLSearchParams): boolean;
751
+ /**
752
+ * True in any Studio-driven context (canvas OR live-preview pane). Use when
753
+ * a third-party should also stay out of preview sessions — e.g. analytics.
754
+ */
755
+ declare function isStudioEditorMode(searchQuery?: string | URLSearchParams): boolean;
756
+ /**
757
+ * Bootstrap: computes the mode from the current URL, stamps
758
+ * `window.__CS_STUDIO_MODE__`, and (for canvas mode) adds
759
+ * {@link STUDIO_MODE_HTML_CLASS} to `<html>`. Idempotent; no-op on the
760
+ * server. Invoked automatically when `@contentstack/studio-react` loads in
761
+ * the browser — call it manually only if you gate scripts that run before
762
+ * the SDK's module graph is evaluated.
763
+ */
764
+ declare function markStudioMode(): StudioMode;
765
+
766
+ declare const ComposableStudioErrors: {
767
+ readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
768
+ readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
769
+ readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
770
+ readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
771
+ readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
772
+ readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
773
+ readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
774
+ readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
775
+ readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
776
+ readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
777
+ readonly NETWORK_ERROR: "NETWORK_ERROR";
778
+ readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
779
+ readonly SERVER_ERROR: "SERVER_ERROR";
780
+ readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
781
+ };
782
+ /**
783
+ * Information about a possible cause of an error and how to fix it
784
+ */
785
+ interface TroubleshootingInfo {
786
+ /**
787
+ * Description of the possible cause of the error
788
+ */
789
+ cause: string;
790
+ /**
791
+ * Suggested fix or resolution for this cause
792
+ */
793
+ fix: string;
794
+ }
795
+ /**
796
+ * Type definition for error details that can be passed to ComposableStudioError
797
+ */
798
+ interface ComposableStudioErrorDetails {
799
+ /**
800
+ * Array of troubleshooting information with causes and fixes
801
+ */
802
+ troubleshootingInfo?: TroubleshootingInfo[];
803
+ /**
804
+ * Additional error context and metadata
805
+ */
806
+ [key: string]: any;
807
+ }
808
+ declare class ComposableStudioError extends Error {
809
+ id: keyof typeof ComposableStudioErrors;
810
+ details?: ComposableStudioErrorDetails;
811
+ constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
812
+ }
813
+
814
+ declare const evaluateCondition: (condition: Condition, data: any) => boolean;
815
+
816
+ declare class RendererModeUtil {
817
+ private searchParams;
818
+ private isServerWithoutParams;
819
+ constructor(searchParams?: URLSearchParams);
820
+ /**
821
+ * Checks if the current context is inside a Studio.
822
+ *
823
+ * @returns {boolean} True if inside a Studio, false otherwise.
824
+ */
825
+ isInsideStudioFrame(): boolean;
826
+ /**
827
+ * Checks if the current context is inside an iframe.
828
+ *
829
+ * @returns {boolean} True if inside an iframe, false otherwise.
830
+ */
831
+ isInsideIframe(): boolean;
832
+ /**
833
+ * Checks if the current context is inside a Visual Builder frame.
834
+ *
835
+ * Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
836
+ *
837
+ * @returns {boolean} True if inside a Visual Builder frame, false otherwise.
838
+ */
839
+ isInsideVisualBuilderFrame(): boolean;
840
+ /**
841
+ * Checks if the current context is editing a specific composition.
842
+ *
843
+ * It is useful when you have multiple compositions in a single page
844
+ * and you want to know if the current context is editing a specific
845
+ * composition.
846
+ *
847
+ * @param compositionUid - The UID of the composition to check.
848
+ * @returns {boolean} True if editing the specified composition, false otherwise.
849
+ */
850
+ isEditingCurrentComposition(compositionUid: string): boolean;
851
+ /**
852
+ * Determines the current renderer mode for a given composition UID.
853
+ *
854
+ * - Returns "edit" if the current composition is being edited.
855
+ * - Returns "show_edit_button" if inside the visual builder frame
856
+ * or if the composition is not currently being edited but should show the edit button.
857
+ * - Returns "preview" otherwise.
858
+ *
859
+ * This method is useful when you want to change the functionality of the
860
+ * component based on where it is being rendered.
861
+ *
862
+ * @param compositionUid - The UID of the composition to check.
863
+ * @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
864
+ */
865
+ getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
866
+ }
867
+ /**
868
+ * Module-level mode util backed by `window.location.search` (the browser URL).
869
+ *
870
+ * SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
871
+ * every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
872
+ * ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
873
+ * INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
874
+ * this: the answer is wrong on the server, and a single shared singleton cannot represent
875
+ * per-request state across concurrent SSR requests anyway. There, use the request-scoped
876
+ * helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
877
+ * `getRequestSearchParams`), which read the forwarded request query on the server and fall
878
+ * back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
879
+ * remove this split and make this util correct everywhere.
880
+ */
881
+ declare const clientRendererModeUtil: RendererModeUtil;
882
+ declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
883
+
884
+ /**
885
+ * Analyzes a UI spec (Node tree) and extracts all component types used.
886
+ * Recursively traverses the spec to find all components.
887
+ *
888
+ * @param spec - The root node of the UI spec
889
+ * @returns Set of component types used in the spec
890
+ */
891
+ declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
892
+ /**
893
+ * Analyzes multiple UI specs and returns the union of all component types used.
894
+ * Useful for optimizing multi-composition loading.
895
+ *
896
+ * @param specs - Array of UI spec root nodes
897
+ * @returns Set of all unique component types used across all specs
898
+ */
899
+ declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
900
+ /**
901
+ * Checks if a spec uses a specific component type.
902
+ *
903
+ * @param spec - The UI spec to check
904
+ * @param componentType - The component type to look for
905
+ * @returns true if the component is used in the spec
906
+ */
907
+ declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
908
+ /**
909
+ * Gets component usage statistics for a spec.
910
+ *
911
+ * @param spec - The UI spec to analyze
912
+ * @returns Map of component types to their usage count
913
+ */
914
+ declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
915
+
916
+ interface UrlPatternVariableInfo {
917
+ type: string;
918
+ name: string;
919
+ category: (typeof URL_PATTERN_VARIABLE_TYPES)[keyof typeof URL_PATTERN_VARIABLE_TYPES];
920
+ referenceName?: string;
921
+ referenceField?: string;
922
+ }
923
+ /**
924
+ * Compile a URL pattern into a regex that can match and extract variables
925
+ * Handles arbitrary patterns like: "lsefj{{entry.url}}assefs{{content_type_uid}}/{{taxonomy:ola}}"
926
+ */
927
+ declare function compileUrlPattern(pattern: string, includeReferences?: string[]): {
928
+ regex: RegExp;
929
+ variableOrder: Array<UrlPatternVariableInfo>;
930
+ literalCharCount: number;
931
+ };
932
+ /**
933
+ * Match a request URL against a compiled pattern and extract variables
934
+ */
935
+ declare function matchUrlPattern(requestUrl: string, compiledPattern: ReturnType<typeof compileUrlPattern>): ExtractedUrlPatternVariables | null;
936
+ /**
937
+ * Compute pattern specificity score for ranking
938
+ * Primary: literal character count (more specific)
939
+ * Secondary: total pattern length
940
+ */
941
+ declare function computePatternSpecificity(pattern: string): number;
942
+ interface MatchCompositionOptions {
943
+ includeReferences?: string[];
944
+ connected_content_type?: string;
945
+ }
946
+ /**
947
+ * Match a single composition entry against a request URL
948
+ */
949
+ declare function matchCompositionUrl(requestUrl: string, compositionUrl: string, composable_uid: string, options?: MatchCompositionOptions): PatternMatchResult;
950
+
951
+ interface SectionNeeds {
952
+ entryKeys: string[];
953
+ queryKeys: string[];
954
+ parentRepeaterUID?: string;
955
+ selectedField?: string;
956
+ uidRemapping?: Record<string, string>;
957
+ componentPropsFallback?: Record<string, unknown>;
958
+ }
959
+ type NeedsBySection = Map<string, SectionNeeds>;
960
+
961
+ interface ResolvedPool {
962
+ entriesByKey: Map<string, any>;
963
+ queriesByKey: Map<string, any>;
964
+ /** instanceUid -> (section's data_source uid -> pool entry key) */
965
+ sectionEntryDsToPoolKey: Map<string, Map<string, string>>;
966
+ /** instanceUid -> (section's query data_source uid -> pool query key) */
967
+ sectionQueryDsToPoolKey: Map<string, Map<string, string>>;
968
+ /**
969
+ * instanceUid -> the SECTION composition entry's preprocessed `static_value`
970
+ * (key -> value). Mirrors the page-level static_value path in sdk.ts but per
971
+ * section instance, so static_value bindings authored inside a section
972
+ * subtree resolve at runtime as well as in the editor.
973
+ */
974
+ sectionStaticValueByInstance?: Map<string, Record<string, unknown>>;
975
+ }
976
+ declare function buildScopedDataSources(pool: ResolvedPool, needsBySection: NeedsBySection, pageDataSources: DataSources): Record<string, SectionScopedDataSources>;
977
+
978
+ /**
979
+ * Pure SEO resolver. Merges the composition's saved SEO metadata
980
+ * (`ui.metadata.seo`) with resolved values from `specData` (bound title /
981
+ * description / OG image / meta props read from the template entry). Shared by
982
+ * the SDK's `getSeoMetadata` and exposed for BYO-data callers who resolve SEO
983
+ * against data they supply themselves — see `resolveSeoMetadata` in
984
+ * `@contentstack/studio-react`.
985
+ */
986
+ declare function getSeoMetadataPure(ui: Node, specData?: StudioSpecData): SeoMetadata | null;
987
+ /**
988
+ * Pure per-instance section scoping. Given a composition's `pageUi` + its
989
+ * section composition entries + an ALREADY-RESOLVED `dataSources` pool, derive
990
+ * the `section_scoped_data` map (per section-instance uid). No network.
991
+ *
992
+ * Reused in two places:
993
+ * 1. `fetchData` — after the CDA fetch has populated `data.dataSources`.
994
+ * 2. BYO-data rendering (`StudioComposition`) — the caller supplies
995
+ * `dataSources`; embedded sections scope without any refetch.
996
+ *
997
+ * Returns `{}` when there are no section compositions (e.g. a standalone
998
+ * section rendered as the root reads `dataSources.template` directly).
999
+ */
1000
+ declare function buildSectionScopedData(compositionEntry: CompositionEntry, pageUi: Node, sectionEntries: SectionCompositionEntry[], dataSources: StudioSpecData["dataSources"]): ReturnType<typeof buildScopedDataSources>;
1001
+
1002
+ /**
1003
+ * A single, framework-neutral meta tag. `attr` distinguishes standard
1004
+ * `<meta name="...">` tags from Open Graph-style `<meta property="...">`.
1005
+ */
1006
+ interface CompositionMetaTag {
1007
+ attr: "name" | "property";
1008
+ key: string;
1009
+ content: string;
1010
+ }
1011
+ /**
1012
+ * Framework-neutral SEO metadata derived from a composition's resolved
1013
+ * `specOptions.seo`. Consumers bind this to their host's head mechanism:
1014
+ * Next.js `generateMetadata`, Remix `meta()`, TanStack `head()`, or a raw
1015
+ * HTML template via {@link renderMetadataToHtml}.
1016
+ */
1017
+ interface CompositionMetadata {
1018
+ title?: string;
1019
+ description?: string;
1020
+ ogImage?: string;
1021
+ /** Absolute canonical URL. Present only when `baseUrl` was provided and the composition has a URL. */
1022
+ canonical?: string;
1023
+ /** Every derived tag (description, og:*, twitter:*, custom metaProps) in render order. */
1024
+ tags: CompositionMetaTag[];
1025
+ }
1026
+ interface GetCompositionMetadataOptions {
1027
+ /**
1028
+ * Site origin used to absolutize the canonical URL and og:url,
1029
+ * e.g. `https://www.example.com`. No trailing slash required.
1030
+ */
1031
+ baseUrl?: string;
1032
+ }
1033
+ /**
1034
+ * Derives framework-neutral SEO metadata from a fetched composition.
1035
+ *
1036
+ * The heavy lifting (resolving field bindings for title/description/OG image)
1037
+ * already happens inside `fetchCompositionData` — this helper only shapes the
1038
+ * resolved values into standard head-tag structures.
1039
+ *
1040
+ * @example Plain Node
1041
+ * ```ts
1042
+ * const meta = getCompositionMetadata(specOptions, { baseUrl: "https://example.com" });
1043
+ * res.send(`<head><title>${meta.title}</title>${renderMetadataToHtml(meta)}</head>...`);
1044
+ * ```
1045
+ *
1046
+ * @example Next.js App Router
1047
+ * ```ts
1048
+ * export async function generateMetadata() {
1049
+ * const meta = getCompositionMetadata(await getSpecOptions());
1050
+ * return { title: meta.title, description: meta.description };
1051
+ * }
1052
+ * ```
1053
+ */
1054
+ declare function getCompositionMetadata(specOptions: Pick<StudioComponentSpecOptions, "seo" | "spec">, options?: GetCompositionMetadataOptions): CompositionMetadata;
1055
+ /**
1056
+ * Renders {@link CompositionMetadata} to a raw HTML string (meta + canonical
1057
+ * link tags — the `<title>` element is left to the caller since most hosts
1058
+ * manage it separately). For template-string SSR hosts (Express/Fastify).
1059
+ */
1060
+ declare function renderMetadataToHtml(metadata: CompositionMetadata): string;
1061
+
670
1062
  /**
671
1063
  * Processes the raw static values and stored them against their static value UID.
672
1064
  *
@@ -897,196 +1289,6 @@ declare class BreakpointManager {
897
1289
  private syncBreakpointsWithStudio;
898
1290
  }
899
1291
 
900
- declare const findPath: (node: Descendant) => Path;
901
- declare const findPathForElement: (el: HTMLElement) => Path;
902
- declare const applyOperation: (editor: Node, operations: Operation[]) => Node;
903
-
904
- declare function isCompositionBeingEdited(compositionUid: string): boolean;
905
-
906
- declare const queryParam: {
907
- get(key: ComposableStudioQueryParamsKeys): string | null;
908
- has(key: ComposableStudioQueryParamsKeys): boolean;
909
- };
910
- declare const onlyParmasGenerator: (only: [string, string][]) => Record<string, string[]>;
911
-
912
- declare const SECTION_COMPOSITIONS_KEY = "section_compositions";
913
- declare const TEMPLATE_FULL_ENTRY_KEY = "template_full_entry";
914
- declare const setTemplateEntryInDS: (dataSources: Record<string, any>, entry: unknown) => void;
915
- declare const setStaticEntryInDS: (dataSources: Record<string, any>, ct_uid: string, _entries: unknown) => void;
916
- /**
917
- * Counterpart to setStaticEntryInDS: drop a single resolved additional entry
918
- * from the contentstack data source bucket. Called when the author removes an
919
- * entry so the pruned bucket replaces the stale one on the next UPDATE_SPEC_DATA
920
- * push (which merges at the dataSources level); without it the removed entry's
921
- * data lingers and keeps rendering.
922
- */
923
- declare const removeStaticEntryFromDS: (dataSources: Record<string, any>, ct_uid: string, uid: string) => void;
924
- declare const batchFetchEntries: (sdk: StackSDK, entries: ICSEntryReference[]) => Promise<[string, CompositionEntry[]][]>;
925
- declare const getBindingStringForCS: (binding: BindingType) => string;
926
- type EntriesResponse<T> = {
927
- entries: T[];
928
- } | [T[]];
929
- declare function entriesFromResponse<T>(response: EntriesResponse<T>): T[];
930
-
931
- declare const isInsideVisualBuilderFrame: () => boolean;
932
-
933
- /**
934
- * Checks if the current context is inside an iframe.
935
- *
936
- * @returns {boolean} True if inside an iframe, false otherwise.
937
- */
938
- declare const isInsideIframe: () => boolean;
939
-
940
- declare const ComposableStudioErrors: {
941
- readonly COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND";
942
- readonly COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL";
943
- readonly PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND";
944
- readonly FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED";
945
- readonly RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED";
946
- readonly STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE";
947
- readonly INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS";
948
- readonly MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER";
949
- readonly UI_PARSING_ERROR: "UI_PARSING_ERROR";
950
- readonly SPEC_DATA_INVALID: "SPEC_DATA_INVALID";
951
- readonly NETWORK_ERROR: "NETWORK_ERROR";
952
- readonly AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR";
953
- readonly SERVER_ERROR: "SERVER_ERROR";
954
- readonly COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND";
955
- };
956
- /**
957
- * Information about a possible cause of an error and how to fix it
958
- */
959
- interface TroubleshootingInfo {
960
- /**
961
- * Description of the possible cause of the error
962
- */
963
- cause: string;
964
- /**
965
- * Suggested fix or resolution for this cause
966
- */
967
- fix: string;
968
- }
969
- /**
970
- * Type definition for error details that can be passed to ComposableStudioError
971
- */
972
- interface ComposableStudioErrorDetails {
973
- /**
974
- * Array of troubleshooting information with causes and fixes
975
- */
976
- troubleshootingInfo?: TroubleshootingInfo[];
977
- /**
978
- * Additional error context and metadata
979
- */
980
- [key: string]: any;
981
- }
982
- declare class ComposableStudioError extends Error {
983
- id: keyof typeof ComposableStudioErrors;
984
- details?: ComposableStudioErrorDetails;
985
- constructor(id: keyof typeof ComposableStudioErrors, message: string, details?: ComposableStudioErrorDetails);
986
- }
987
-
988
- declare const evaluateCondition: (condition: Condition, data: any) => boolean;
989
-
990
- declare class RendererModeUtil {
991
- private searchParams;
992
- private isServerWithoutParams;
993
- constructor(searchParams?: URLSearchParams);
994
- /**
995
- * Checks if the current context is inside a Studio.
996
- *
997
- * @returns {boolean} True if inside a Studio, false otherwise.
998
- */
999
- isInsideStudioFrame(): boolean;
1000
- /**
1001
- * Checks if the current context is inside an iframe.
1002
- *
1003
- * @returns {boolean} True if inside an iframe, false otherwise.
1004
- */
1005
- isInsideIframe(): boolean;
1006
- /**
1007
- * Checks if the current context is inside a Visual Builder frame.
1008
- *
1009
- * Learn more about Visual Builder: {@link https://www.contentstack.com/docs/content-managers/visual-builder}
1010
- *
1011
- * @returns {boolean} True if inside a Visual Builder frame, false otherwise.
1012
- */
1013
- isInsideVisualBuilderFrame(): boolean;
1014
- /**
1015
- * Checks if the current context is editing a specific composition.
1016
- *
1017
- * It is useful when you have multiple compositions in a single page
1018
- * and you want to know if the current context is editing a specific
1019
- * composition.
1020
- *
1021
- * @param compositionUid - The UID of the composition to check.
1022
- * @returns {boolean} True if editing the specified composition, false otherwise.
1023
- */
1024
- isEditingCurrentComposition(compositionUid: string): boolean;
1025
- /**
1026
- * Determines the current renderer mode for a given composition UID.
1027
- *
1028
- * - Returns "edit" if the current composition is being edited.
1029
- * - Returns "show_edit_button" if inside the visual builder frame
1030
- * or if the composition is not currently being edited but should show the edit button.
1031
- * - Returns "preview" otherwise.
1032
- *
1033
- * This method is useful when you want to change the functionality of the
1034
- * component based on where it is being rendered.
1035
- *
1036
- * @param compositionUid - The UID of the composition to check.
1037
- * @returns RendererMode - The current mode (EDIT, SHOW_EDIT_BUTTON, or PREVIEW).
1038
- */
1039
- getMode(compositionUid: string): "preview" | "edit" | "show_edit_button";
1040
- }
1041
- /**
1042
- * Module-level mode util backed by `window.location.search` (the browser URL).
1043
- *
1044
- * SSR CAUTION: this reads `window`, which does not exist on the server, so on the server
1045
- * every method returns its production default (e.g. `isInsideStudioFrame()` -> false) for
1046
- * ALL requests. It is correct ONLY in browser-only code (the editor render, hooks,
1047
- * INIT_STUDIO). In server-reachable fetch code (studio-client's spec-fetch path) do NOT use
1048
- * this: the answer is wrong on the server, and a single shared singleton cannot represent
1049
- * per-request state across concurrent SSR requests anyway. There, use the request-scoped
1050
- * helpers in `sdk.ts` (`isInStudio` / `isEditorFetch` / `readStudioParam`, built on
1051
- * `getRequestSearchParams`), which read the forwarded request query on the server and fall
1052
- * back to `window` on the client. See COMS-1554 for the AsyncLocalStorage proposal that would
1053
- * remove this split and make this util correct everywhere.
1054
- */
1055
- declare const clientRendererModeUtil: RendererModeUtil;
1056
- declare const serializeComputedStyles: (computedStyle: CSSStyleDeclaration) => Record<string, string>;
1057
-
1058
- /**
1059
- * Analyzes a UI spec (Node tree) and extracts all component types used.
1060
- * Recursively traverses the spec to find all components.
1061
- *
1062
- * @param spec - The root node of the UI spec
1063
- * @returns Set of component types used in the spec
1064
- */
1065
- declare function analyzeUsedComponents(spec: Node | null | undefined): Set<string>;
1066
- /**
1067
- * Analyzes multiple UI specs and returns the union of all component types used.
1068
- * Useful for optimizing multi-composition loading.
1069
- *
1070
- * @param specs - Array of UI spec root nodes
1071
- * @returns Set of all unique component types used across all specs
1072
- */
1073
- declare function analyzeMultipleSpecs(specs: (Node | null | undefined)[]): Set<string>;
1074
- /**
1075
- * Checks if a spec uses a specific component type.
1076
- *
1077
- * @param spec - The UI spec to check
1078
- * @param componentType - The component type to look for
1079
- * @returns true if the component is used in the spec
1080
- */
1081
- declare function specUsesComponent(spec: Node | null | undefined, componentType: string): boolean;
1082
- /**
1083
- * Gets component usage statistics for a spec.
1084
- *
1085
- * @param spec - The UI spec to analyze
1086
- * @returns Map of component types to their usage count
1087
- */
1088
- declare function getComponentUsageStats(spec: Node | null | undefined): Map<string, number>;
1089
-
1090
1292
  interface GoogleFont {
1091
1293
  family: string;
1092
1294
  variants: string[];
@@ -1502,40 +1704,5 @@ declare function rankUrlMatches(requestUrl: string, lightweightEntries: Lightwei
1502
1704
  */
1503
1705
  declare function shouldUseUrlMetadataPath(url_metadata?: Partial<CompositionUrlMetadataSerialized>): boolean;
1504
1706
 
1505
- interface UrlPatternVariableInfo {
1506
- type: string;
1507
- name: string;
1508
- category: (typeof URL_PATTERN_VARIABLE_TYPES)[keyof typeof URL_PATTERN_VARIABLE_TYPES];
1509
- referenceName?: string;
1510
- referenceField?: string;
1511
- }
1512
- /**
1513
- * Compile a URL pattern into a regex that can match and extract variables
1514
- * Handles arbitrary patterns like: "lsefj{{entry.url}}assefs{{content_type_uid}}/{{taxonomy:ola}}"
1515
- */
1516
- declare function compileUrlPattern(pattern: string, includeReferences?: string[]): {
1517
- regex: RegExp;
1518
- variableOrder: Array<UrlPatternVariableInfo>;
1519
- literalCharCount: number;
1520
- };
1521
- /**
1522
- * Match a request URL against a compiled pattern and extract variables
1523
- */
1524
- declare function matchUrlPattern(requestUrl: string, compiledPattern: ReturnType<typeof compileUrlPattern>): ExtractedUrlPatternVariables | null;
1525
- /**
1526
- * Compute pattern specificity score for ranking
1527
- * Primary: literal character count (more specific)
1528
- * Secondary: total pattern length
1529
- */
1530
- declare function computePatternSpecificity(pattern: string): number;
1531
- interface MatchCompositionOptions {
1532
- includeReferences?: string[];
1533
- connected_content_type?: string;
1534
- }
1535
- /**
1536
- * Match a single composition entry against a request URL
1537
- */
1538
- declare function matchCompositionUrl(requestUrl: string, compositionUrl: string, composable_uid: string, options?: MatchCompositionOptions): PatternMatchResult;
1539
-
1540
- export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, ComposableStudioErrors, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, EDGE_PADDING, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, MAX_SCROLL_SPEED, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SCROLL_INTERVAL, SDK_VERSION, SECTION_COMPOSITIONS_KEY, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, addBreakpointEventListeners, addContextMenuEventListeners, addHighlightNodeEventListeners, addHighlightSpacingEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, buildTemplateQuery, buildUrlMetadataQueryObject, calculateDynamicSpeed, clientRendererModeUtil, closeHiddenElementNotification, compileUrlPattern, composableStudioEventEmitter, compositionSaveEventListener, computePatternSpecificity, createClassNameUid, createEmbeddedEntryConversion, studioSdk as default, defaultAssetRender, dndEventListener, dndManager, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, getBindingStringForCS, getComponentUsageStats, getComposableElement, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getHitboxDetails, getHitboxDirection, getJSONRTE, getNodeScreenshotEvent, getScrollableParent, handleOnScroll, handleResize, hasSlotDropzone, hiddenElementNotificationEventEmitter, highlightNodeManager, isBrowser, isCompositionBeingEdited, isInsideIframe, isInsideVisualBuilderFrame, isModKey, loadGoogleFont, matchCompositionUrl, matchUrlPattern, onlyParmasGenerator, openHiddenElementNotification, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, resolveByUrlSource, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
1541
- export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchTemplateEntryContext, FieldValue, FontVariants, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionCompositionEntry, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioSdk, StudioSpec, SymbolEntry, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };
1707
+ export { BreakpointManager, COMPOSABLE_DATA_ATTRIBUTES, COMPOSABLE_STUDIO_EMITTED_EVENTS, COMPOSITION_PLACEMENT_OPTIONS, COMPOSITION_PREVIEW_URL_SOURCES, COMPOSITION_PREVIEW_URL_SOURCES_VALUES, ComposableStudioError, ComposableStudioErrors, DEFAULT_BREAKPOINTS, DEFAULT_COMPOSITION_PREVIEW_URL_SOURCE, EDGE_PADDING, ELEMENT_TO_NODE, ExpressionResolver, GOOGLE_FONT_API, INCLUDE_DEPTH_COUNT, MAX_SCROLL_SPEED, NODE_TO_ELEMENT, NODE_TO_PARENT, NODE_TO_PATH_NODE, QueryExecutor, RendererMode, RendererModeUtil, SCHEMA_VERSION, SCROLL_INTERVAL, SDK_VERSION, SECTION_COMPOSITIONS_KEY, STUDIO_CANVAS_QUERY_PARAM, STUDIO_MODE_HTML_CLASS, TEMPLATE_FULL_ENTRY_KEY, URL_PATTERN_DATE_VARIABLES, URL_PATTERN_METADATA_FIELDS, URL_PATTERN_METADATA_FIELDS_VALUES, URL_PATTERN_VARIABLE_TYPES, addBreakpointEventListeners, addContextMenuEventListeners, addHighlightNodeEventListeners, addHighlightSpacingEventListeners, addUrlChangeListeners, analyzeMultipleSpecs, analyzeUsedComponents, applyOperation, batchFetchEntries, buildSectionScopedData, buildTemplateQuery, buildUrlMetadataQueryObject, calculateDynamicSpeed, clientRendererModeUtil, closeHiddenElementNotification, compileUrlPattern, composableStudioEventEmitter, compositionSaveEventListener, computePatternSpecificity, createClassNameUid, createEmbeddedEntryConversion, studioSdk as default, defaultAssetRender, detectStudioMode, dndEventListener, dndManager, entriesFromResponse, evaluateCondition, extractHtmlRteRefs, extractJsonRteRefs, fetchEmbeddedEntries, findNearestBuilderNode, findNearestSlotNode, findPath, findPathForElement, getBindingStringForCS, getComponentUsageStats, getComposableElement, getCompositionMetadata, getComputedStyles, getDefaultConfig, getEmbeddedAssetRenderer, getEmbeddedEntryRenderer, getHitboxDetails, getHitboxDirection, getJSONRTE, getNodeScreenshotEvent, getScrollableParent, getSeoMetadataPure, handleOnScroll, handleResize, hasSlotDropzone, hiddenElementNotificationEventEmitter, highlightNodeManager, isBrowser, isCompositionBeingEdited, isInsideIframe, isInsideVisualBuilderFrame, isModKey, isStudioCanvas, isStudioEditorMode, loadGoogleFont, markStudioMode, matchCompositionUrl, matchUrlPattern, onlyParmasGenerator, openHiddenElementNotification, parseStringValue, parseUrlMetadata, preProcessStaticValues, queryParam, rankUrlMatches, registerEmbeddedEntryRenderer, registerJSONRTE, registerRTERenderer, removeStaticEntryFromDS, renderMetadataToHtml, resolveByUrlSource, serializeComputedStyles, serializeEvent, setStaticEntryInDS, setTemplateEntryInDS, shouldExtractTaxonomies, shouldUseUrlMetadataPath, specUsesComponent, studioSdk, toggleNodeVisible, updateStyleOnStyleNodeChange };
1708
+ export type { ClientEditableNodeInternalAttributes, ClientPreviewNodeInternalAttributes, ComposableStudioErrorDetails, ComposableStudioLightSdk, CompositionEntry, CompositionEntryIncompleteUi, CompositionFetcher, CompositionMetaTag, CompositionMetadata, CompositionPlacement, CompositionPreviewUrlSource, CompositionPreviewUrlSourceValues, CompositionQueryForSSR, CompositionQueryForSSRInput, CompositionQueryOptions, CompositionUrlMetadata, CompositionUrlMetadataSerialized, CompositionUrlQueries, Config, ConnectedEntryResult, DateVariableKey, EmbeddedAssetRenderArgs, EmbeddedEntryConversionOptions, EmbeddedEntryRenderArgs, EmittedEvents, ExtractedUrlPatternVariables, ExtractedUrlVariables, FetchCompositionContext, FetchTemplateEntryContext, FieldValue, FontVariants, GetCompositionMetadataOptions, GoogleFont, HiddenElementNotificationHandler, LightConfig, LightweightCompositionEntry, MetaProp, ParsedStringResult, PatternMatchResult, QueryExecutionOptions, QueryResult, QuerySpec, QueryState, RTEConfig, RankingResult, ReferenceFieldValue, RenderableCompositionEntry, ResolvedEmbeddedEntry, ResolvedQueryOptions, RuntimeContext, SearchQueryInput, SectionCompositionEntry, SeoMetadata, StudioComponentFetchOptions, StudioComponentSpecOptions, StudioMode, StudioSdk, StudioSpec, SymbolEntry, TemplateEntryFetcher, TemplateQueryContext, TroubleshootingInfo, URLSearchParamsString, UrlMatchDiagnostic, UrlMetadataQueryMode, UrlPatternMetadataField, UrlPatternMetadataFieldValue, UserConfig };