@templatical/types - npm Package Compare versions

Comparing version 0.20.0 to 0.21.0

dist/index.d.ts

@@ -234,2 +234,168 @@ //#region src/blocks.d.ts
 //#endregion
+//#region src/saved-blocks.d.ts
+/**
+ * A reusable, user-authored group of blocks — saved from the canvas and
+ * re-insertable into any template.
+ *
+ * Distinct from a *custom block* (`CustomBlockDefinition`), which is a
+ * developer-defined block **type** with its own template and field schema.
+ * A saved block is an instance-level snapshot of ordinary blocks.
+ */
+interface SavedBlock {
+  /**
+   * Store-assigned identifier. Returned by {@link SavedBlocksProvider.create}
+   * — the editor never generates it, so the store stays the authority on
+   * identity (database primary key, storage slug, etc.).
+   */
+  id: string;
+  name: string;
+  /**
+   * Top-level blocks captured in this saved block. A `section` carries its own
+   * `children`, so a whole section-with-columns round-trips as one entry.
+   *
+   * Blocks are re-identified on insert (via `cloneBlock`), so the IDs stored
+   * here never collide with the blocks already on a canvas.
+   */
+  content: Block[];
+  /**
+   * Optional free-text grouping, surfaced in the browser as a filter.
+   *
+   * Flat and free-text by design — there is no category registry and no
+   * nesting. The editor derives the set of available categories from the
+   * entries it has loaded, so a category exists exactly as long as something
+   * carries it; an entry without one is simply uncategorised.
+   */
+  category?: string;
+  /**
+   * Per-entry permission carve-outs. **Absent means allowed** — the provider's
+   * `update` / `delete` already say whether the capability exists at all, so
+   * these exist only to forbid it on *particular* entries (a shared block a
+   * viewer may insert but not edit, someone else's block, a locked entry).
+   *
+   * Return them from your API alongside the row, where the answer is already
+   * known — the editor never second-guesses them and never computes its own.
+   * When one is `false` the corresponding control is not rendered for that
+   * entry.
+   */
+  canUpdate?: boolean;
+  canDelete?: boolean;
+  /**
+   * Store-assigned timestamps, used for display only: the browser shows a
+   * relative "5m ago" label per entry (preferring `updatedAt`, falling back to
+   * `createdAt`) with the absolute date on hover.
+   *
+   * They do **not** affect ordering — the editor renders whatever order
+   * `list()` returns and never re-sorts. Both are optional; omit them and the
+   * label is simply not shown.
+   */
+  createdAt?: string;
+  updatedAt?: string;
+}
+/**
+ * Parameters for {@link SavedBlocksProvider.list}. An object (rather than
+ * positional arguments) so future filters can be added without breaking
+ * existing provider implementations.
+ *
+ * **These are only sent by headless callers.** The editor's own browser calls
+ * `list()` with no parameters and filters the loaded entries in memory — that
+ * way a provider stays a dumb store and still gets a working search box and
+ * category filter. They arrive only when you drive `useSavedBlocks`
+ * yourself (see the guide's "Headless use"), so implement them if you want
+ * server-side filtering for your own UI and ignore them otherwise.
+ */
+interface SavedBlocksListParams {
+  /** Free-text filter over the saved block's `name`. */
+  search?: string;
+  /** Exact-match filter over {@link SavedBlock.category}. */
+  category?: string;
+}
+/** Payload for {@link SavedBlocksProvider.create}. */
+interface SavedBlockInput {
+  name: string;
+  content: Block[];
+  category?: string;
+}
+/**
+ * Partial patch for {@link SavedBlocksProvider.update}. Only the keys present
+ * are being changed — `category: ""` clears the category, whereas omitting the
+ * key leaves it alone.
+ */
+type SavedBlockPatch = Partial<{
+  name: string;
+  content: Block[];
+  category: string;
+}>;
+/**
+ * Storage contract for saved blocks. Implement it to back the editor's saved
+ * blocks UI with your own persistence — the editor owns the save dialog, the
+ * browser, and insertion; you own the transport.
+ *
+ * Pass an implementation as `savedBlocks` to `init()`. When omitted, the
+ * feature stays off entirely and none of its UI renders.
+ *
+ * Every method may reject; the editor surfaces the failure through the
+ * editor's `onError` callback and leaves its in-memory list untouched.
+ *
+ * **Each mutation can be turned off by passing `false` instead of a function.**
+ * The editor then hides the affordance rather than letting the user try and
+ * fail. They are required rather than optional precisely so that disabling is a
+ * decision you state, never something you get by forgetting a method. Setting
+ * all three yields a **read-only library**: users still browse, preview and
+ * insert, because insertion only touches the canvas and never your store.
+ *
+ * ```ts
+ * const provider: SavedBlocksProvider = {
+ *   list: ({ search } = {}) =>
+ *     fetch(`/api/saved-blocks?search=${search ?? ""}`).then((r) => r.json()),
+ *   create: (input) =>
+ *     fetch("/api/saved-blocks", {
+ *       method: "POST",
+ *       headers: { "Content-Type": "application/json" },
+ *       body: JSON.stringify(input),
+ *     }).then((r) => r.json()),
+ *   update: (id, patch) =>
+ *     fetch(`/api/saved-blocks/${id}`, {
+ *       method: "PUT",
+ *       headers: { "Content-Type": "application/json" },
+ *       body: JSON.stringify(patch),
+ *     }).then((r) => r.json()),
+ *   delete: (id) =>
+ *     fetch(`/api/saved-blocks/${id}`, { method: "DELETE" }).then(() => undefined),
+ * };
+ * ```
+ */
+interface SavedBlocksProvider {
+  /**
+   * Fetch saved blocks. The editor calls this with no arguments and expects
+   * everything the current user may see — scoping the result per user, tenant
+   * or permission is yours to do here. {@link SavedBlocksListParams} is only
+   * populated by headless callers; honouring it is optional.
+   *
+   * The one method that cannot be disabled: without it the feature has nothing
+   * to show.
+   */
+  list(params?: SavedBlocksListParams): Promise<SavedBlock[]>;
+  /**
+   * Persist a new saved block and return it with its store-assigned `id`, or
+   * `false` to disable saving entirely — the block chrome's bookmark action
+   * disappears and no pick session can be started.
+   */
+  create: false | ((input: SavedBlockInput) => Promise<SavedBlock>);
+  /**
+   * Apply a partial update and return the stored result, or `false` to disable
+   * editing entirely. Renaming is `update(id, { name })` and recategorising is
+   * `update(id, { category })` — there are no separate methods for either.
+   *
+   * To allow editing in general but forbid it on particular entries, keep the
+   * function and set {@link SavedBlock.canUpdate} to `false` on those.
+   */
+  update: false | ((id: string, patch: SavedBlockPatch) => Promise<SavedBlock>);
+  /**
+   * Remove a saved block, resolving once the store has applied the delete, or
+   * `false` to disable deletion entirely. Per-entry exceptions go through
+   * {@link SavedBlock.canDelete}.
+   */
+  delete: false | ((id: string) => Promise<void>);
+}
+//#endregion
 //#region src/guards.d.ts
@@ -800,9 +966,2 @@ declare function isSection(block: Block): block is SectionBlock;
 }
-interface SavedModule {
-  id: string;
-  name: string;
-  content: Block[];
-  created_at: string;
-  updated_at: string;
-}
 type FindingSeverity = "high" | "medium" | "low";
@@ -1060,3 +1219,3 @@ type ScoringCategory = "spam" | "readability" | "accessibility" | "bestPractices";
 //#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 SavedModule, 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 TemplaticalConfig, type TemplaticalInstance, type TestEmailConfig, 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, getSyntaxClosingChar, getSyntaxTriggerChar, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone };
+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 TemplaticalConfig, type TemplaticalInstance, type TestEmailConfig, 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, getSyntaxClosingChar, getSyntaxTriggerChar, isButton, isCountdown, isCustomBlock, isDivider, isHtml, isImage, isLogicMergeTagValue, isMenu, isMergeTagValue, isParagraph, isSection, isSocialIcons, isSpacer, isTable, isTitle, isVideo, resolveHtmlLogicMergeTagLabels, resolveHtmlMergeTagLabels, resolveSyntax, restoreMergeTagMarkup, safeClone };
 //# sourceMappingURL=index.d.ts.map

package.json

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

New alerts

Unidentified License

License

Something that seems like a license was found, but its contents could not be matched with a known license.

Fixed alerts

Unidentified License

License

Something that seems like a license was found, but its contents could not be matched with a known license.

Improved metrics

Total package byte prevSize

151079

4.82%

Lines of code

1952

8.87%

No dependency changes