@templatical/types - npm Package Compare versions

Comparing version 0.24.1 to 0.25.0

dist/index.d.ts

@@ -1039,2 +1039,45 @@ //#region src/blocks.d.ts
 //#endregion
+//#region src/preview-resolution.d.ts
+/**
+ * Context handed to `resolvePreview`.
+ *
+ * `recipient` is present only on surfaces that have one — the test-email
+ * dialog — and absent in the editor's own preview mode. Treat its absence as
+ * "no particular recipient", not as an error: a resolver should still return
+ * something renderable, typically its own default or sample data.
+ */
+interface PreviewResolveContext {
+  /**
+   * The template as it currently stands. Already a copy — mutating it has no
+   * effect on the editor, and returning it unchanged is a valid no-op.
+   */
+  content: TemplateContent;
+  /** The address the preview is being shown for, when the surface has one. */
+  recipient?: string;
+}
+/**
+ * Resolves a template for display on preview surfaces — typically substituting
+ * merge tags and **evaluating logic tags** against real data.
+ *
+ * Logic tags are the reason this hook exists. `MergeTag.sample` already covers
+ * value tags client-side, but branching (`{% if %}` … `{% endif %}`) cannot be
+ * evaluated in a browser for every supported syntax — mailchimp and ampscript
+ * logic are server-side dialects — so only the consumer's own backend can do it.
+ *
+ * Display-only. The returned content reaches preview surfaces and nothing else:
+ * it is never written to the editor's state, never returned from
+ * `getContent()`, never sent, and never exported. Rejecting is safe — the
+ * preview falls back to the unresolved template and says so.
+ */
+type ResolvePreview = (context: PreviewResolveContext) => Promise<TemplateContent>;
+/**
+ * Whether `value` is shaped enough like `TemplateContent` to render.
+ *
+ * A resolver is consumer code returning data that often came from an HTTP
+ * response, so the declared return type guarantees nothing at runtime. A
+ * mis-shaped result is treated as a resolution failure — the preview degrades
+ * to the unresolved template — rather than throwing inside the render.
+ */
+declare function isRenderableTemplateContent(value: unknown): value is TemplateContent;
+//#endregion
 //#region ../media-library/src/types.d.ts
@@ -1307,3 +1350,3 @@ interface StorageInfo {
 //#endregion
-export { type AiChatMessage, type AiConfig, type AiGenerateOptions, type AiScoreOptions, type AiStreamEvent, type ApiError, type ApiResponse, type AuthConfig, type AuthRequestOptions, BUTTON_BLOCK_DEFAULTS, type BaseBlock, type Block, type BlockDefaults, type BlockStyles, type BlockType, type BlockVisibility, type ButtonBlock, COUNTDOWN_BLOCK_DEFAULTS, type CategoryScore, type CollaborationConfig, type Collaborator, type ColorsConfig, type ColumnLayout, type Comment, type CommentEvent, type CommentEventType, type CommentThread, type CountdownBlock, type CreateCommentData, type CustomBlock, type CustomBlockBooleanField, type CustomBlockColorField, type CustomBlockDefinition, type CustomBlockField, type CustomBlockFieldBase, type CustomBlockFieldType, type CustomBlockImageField, type CustomBlockNumberField, type CustomBlockRepeatableField, type CustomBlockSelectField, type CustomBlockTextField, type CustomBlockTextareaField, type CustomFont, DEFAULT_BLOCK_DEFAULTS, DEFAULT_TEMPLATE_DEFAULTS, DIVIDER_BLOCK_DEFAULTS, type DataSourceConfig, type DataSourceFetchContext, type DirectAuthConfig, type DisplayCondition, type DisplayConditionsConfig, type DividerBlock, type EditorState, EventEmitter, type ExportResult, type FindingSeverity, type FontsConfig, HEADING_LEVEL_FONT_SIZE, HTML_BLOCK_DEFAULTS, type HeadingLevel, type HealthCheckResult, type HtmlBlock, IMAGE_BLOCK_DEFAULTS, type ImageBlock, type LogicPair, type LogicTag, type LogicTagsConfig, MENU_BLOCK_DEFAULTS, type McpConfig, type McpOperation, type McpOperationPayload, type MediaResult, type MenuBlock, type MenuItemData, type MergeTag, type MergeTagsConfig, PARAGRAPH_BLOCK_DEFAULTS, type ParagraphBlock, type PlanConfig, type PlanFeatures, type PlanLimits, type ProxyAuthConfig, type RewriteData, SECTION_BLOCK_DEFAULTS, SOCIAL_ICONS_BLOCK_DEFAULTS, SOCIAL_ICON_GLYPHS, SPACER_BLOCK_DEFAULTS, SYNTAX_PRESETS, type SaveResult, type SavedBlock, type SavedBlockInput, type SavedBlockPatch, type SavedBlocksListParams, type SavedBlocksProvider, type ScoringCategory, type ScoringFinding, type ScoringResult, type SdkAuthConfig, SdkError, type SectionBlock, type SectionWrapper, type SelectOption, type SocialIcon, type SocialIconGlyph, type SocialIconSize, type SocialIconStyle, type SocialIconsBlock, type SocialPlatform, type SpacerBlock, type SpacingValue, type SyntaxPreset, type SyntaxPresetName, TABLE_BLOCK_DEFAULTS, TITLE_BLOCK_DEFAULTS, type TableBlock, type TableCellData, type TableRowData, type Template, type TemplateContent, type TemplateDefaults, type TemplateSettings, type TemplateSnapshot, type TestEmailConfig, type TestEmailPayload, type TestEmailProvider, type ThemeOverrides, type TitleBlock, type TokenData, type UiTheme, type UpdateCommentData, type UserConfig, VIDEO_BLOCK_DEFAULTS, type VideoBlock, type ViewportSize, type WebSocketServerConfig, cloneBlock, containsMergeTag, createBlock, createButtonBlock, createCountdownBlock, createCustomBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, deepMergeDefaults, generateId, getLogicMergeTagKeyword, getMergeTagLabel, getMergeTagSample, getSyntaxClosingChar, getSyntaxTriggerChar, hasMergeTagSamples, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone, substituteHtmlMergeTagSamples, substituteTextMergeTagSamples };
+export { type AiChatMessage, type AiConfig, type AiGenerateOptions, type AiScoreOptions, type AiStreamEvent, type ApiError, type ApiResponse, type AuthConfig, type AuthRequestOptions, BUTTON_BLOCK_DEFAULTS, type BaseBlock, type Block, type BlockDefaults, type BlockStyles, type BlockType, type BlockVisibility, type ButtonBlock, COUNTDOWN_BLOCK_DEFAULTS, type CategoryScore, type CollaborationConfig, type Collaborator, type ColorsConfig, type ColumnLayout, type Comment, type CommentEvent, type CommentEventType, type CommentThread, type CountdownBlock, type CreateCommentData, type CustomBlock, type CustomBlockBooleanField, type CustomBlockColorField, type CustomBlockDefinition, type CustomBlockField, type CustomBlockFieldBase, type CustomBlockFieldType, type CustomBlockImageField, type CustomBlockNumberField, type CustomBlockRepeatableField, type CustomBlockSelectField, type CustomBlockTextField, type CustomBlockTextareaField, type CustomFont, DEFAULT_BLOCK_DEFAULTS, DEFAULT_TEMPLATE_DEFAULTS, DIVIDER_BLOCK_DEFAULTS, type DataSourceConfig, type DataSourceFetchContext, type DirectAuthConfig, type DisplayCondition, type DisplayConditionsConfig, type DividerBlock, type EditorState, EventEmitter, type ExportResult, type FindingSeverity, type FontsConfig, HEADING_LEVEL_FONT_SIZE, HTML_BLOCK_DEFAULTS, type HeadingLevel, type HealthCheckResult, type HtmlBlock, IMAGE_BLOCK_DEFAULTS, type ImageBlock, type LogicPair, type LogicTag, type LogicTagsConfig, MENU_BLOCK_DEFAULTS, type McpConfig, type McpOperation, type McpOperationPayload, type MediaResult, type MenuBlock, type MenuItemData, type MergeTag, type MergeTagsConfig, PARAGRAPH_BLOCK_DEFAULTS, type ParagraphBlock, type PlanConfig, type PlanFeatures, type PlanLimits, type PreviewResolveContext, type ProxyAuthConfig, type ResolvePreview, type RewriteData, SECTION_BLOCK_DEFAULTS, SOCIAL_ICONS_BLOCK_DEFAULTS, SOCIAL_ICON_GLYPHS, SPACER_BLOCK_DEFAULTS, SYNTAX_PRESETS, type SaveResult, type SavedBlock, type SavedBlockInput, type SavedBlockPatch, type SavedBlocksListParams, type SavedBlocksProvider, type ScoringCategory, type ScoringFinding, type ScoringResult, type SdkAuthConfig, SdkError, type SectionBlock, type SectionWrapper, type SelectOption, type SocialIcon, type SocialIconGlyph, type SocialIconSize, type SocialIconStyle, type SocialIconsBlock, type SocialPlatform, type SpacerBlock, type SpacingValue, type SyntaxPreset, type SyntaxPresetName, TABLE_BLOCK_DEFAULTS, TITLE_BLOCK_DEFAULTS, type TableBlock, type TableCellData, type TableRowData, type Template, type TemplateContent, type TemplateDefaults, type TemplateSettings, type TemplateSnapshot, type TestEmailConfig, type TestEmailPayload, type TestEmailProvider, type ThemeOverrides, type TitleBlock, type TokenData, type UiTheme, type UpdateCommentData, type UserConfig, VIDEO_BLOCK_DEFAULTS, type VideoBlock, type ViewportSize, type WebSocketServerConfig, cloneBlock, containsMergeTag, createBlock, createButtonBlock, createCountdownBlock, createCustomBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, deepMergeDefaults, generateId, getLogicMergeTagKeyword, getMergeTagLabel, getMergeTagSample, getSyntaxClosingChar, getSyntaxTriggerChar, hasMergeTagSamples, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isRenderableTemplateContent, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone, substituteHtmlMergeTagSamples, substituteTextMergeTagSamples };
 //# sourceMappingURL=index.d.ts.map

dist/index.js

@@ -729,2 +729,17 @@ //#region src/blocks.ts
 //#endregion
+//#region src/preview-resolution.ts
+/**
+* Whether `value` is shaped enough like `TemplateContent` to render.
+*
+* A resolver is consumer code returning data that often came from an HTTP
+* response, so the declared return type guarantees nothing at runtime. A
+* mis-shaped result is treated as a resolution failure — the preview degrades
+* to the unresolved template — rather than throwing inside the render.
+*/
+function isRenderableTemplateContent(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return Array.isArray(candidate.blocks);
+}
+//#endregion
 //#region src/config.ts
@@ -749,4 +764,4 @@ var SdkError = class extends Error {
 //#endregion
-export { BUTTON_BLOCK_DEFAULTS, COUNTDOWN_BLOCK_DEFAULTS, DEFAULT_BLOCK_DEFAULTS, DEFAULT_TEMPLATE_DEFAULTS, DIVIDER_BLOCK_DEFAULTS, EventEmitter, HEADING_LEVEL_FONT_SIZE, HTML_BLOCK_DEFAULTS, IMAGE_BLOCK_DEFAULTS, MENU_BLOCK_DEFAULTS, PARAGRAPH_BLOCK_DEFAULTS, SECTION_BLOCK_DEFAULTS, SOCIAL_ICONS_BLOCK_DEFAULTS, SOCIAL_ICON_GLYPHS, SPACER_BLOCK_DEFAULTS, SYNTAX_PRESETS, SdkError, TABLE_BLOCK_DEFAULTS, TITLE_BLOCK_DEFAULTS, VIDEO_BLOCK_DEFAULTS, cloneBlock, containsMergeTag, createBlock, createButtonBlock, createCountdownBlock, createCustomBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, deepMergeDefaults, generateId, getLogicMergeTagKeyword, getMergeTagLabel, getMergeTagSample, getSyntaxClosingChar, getSyntaxTriggerChar, hasMergeTagSamples, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone, substituteHtmlMergeTagSamples, substituteTextMergeTagSamples };
+export { BUTTON_BLOCK_DEFAULTS, COUNTDOWN_BLOCK_DEFAULTS, DEFAULT_BLOCK_DEFAULTS, DEFAULT_TEMPLATE_DEFAULTS, DIVIDER_BLOCK_DEFAULTS, EventEmitter, HEADING_LEVEL_FONT_SIZE, HTML_BLOCK_DEFAULTS, IMAGE_BLOCK_DEFAULTS, MENU_BLOCK_DEFAULTS, PARAGRAPH_BLOCK_DEFAULTS, SECTION_BLOCK_DEFAULTS, SOCIAL_ICONS_BLOCK_DEFAULTS, SOCIAL_ICON_GLYPHS, SPACER_BLOCK_DEFAULTS, SYNTAX_PRESETS, SdkError, TABLE_BLOCK_DEFAULTS, TITLE_BLOCK_DEFAULTS, VIDEO_BLOCK_DEFAULTS, cloneBlock, containsMergeTag, createBlock, createButtonBlock, createCountdownBlock, createCustomBlock, createDefaultTemplateContent, createDividerBlock, createHtmlBlock, createImageBlock, createMenuBlock, createParagraphBlock, createSectionBlock, createSocialIconsBlock, createSpacerBlock, createTableBlock, createTitleBlock, createVideoBlock, deepMergeDefaults, generateId, getLogicMergeTagKeyword, getMergeTagLabel, getMergeTagSample, getSyntaxClosingChar, getSyntaxTriggerChar, hasMergeTagSamples, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isRenderableTemplateContent, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone, substituteHtmlMergeTagSamples, substituteTextMergeTagSamples };
 
 //# sourceMappingURL=index.js.map

package.json

 {
   "name": "@templatical/types",
   "description": "Shared TypeScript types, block factory functions, and event emitter for Templatical email editor",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "bugs": "https://github.com/templatical/sdk/issues",
@@ -9,3 +9,3 @@ "devDependencies": {
     "vitest": "^4.1.10",
-    "@templatical/media-library": "0.24.1"
+    "@templatical/media-library": "0.25.0"
   },
@@ -12,0 +12,0 @@ "exports": {

No alert changes

Improved metrics

Total package byte prevSize

168901

3.2%

Lines of code

2166

2.75%

No dependency changes