@standhigher/puck-page-builder 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { ExtensionRegistry } from './extensions.js';
-export { BlockDefinition, BlockEditorProps, BlockVariantDefinition, DataSourceDefinition, EditorAction, EditorActionPosition, ExtensionActionContext, ExtensionRegistryError, ExtensionRegistryErrorCode, ExtensionRegistryOptions, ExtensionTarget, FieldConfig, FieldDefinition, FieldProps, LifecycleHooks, PageBuilderExtension, RendererDefinition, TemplateDefinition, TemplateRegistry, TemplateSource, UISlotContribution, UISlotName, ValidationIssue, createExtensionRegistry, createTemplateRegistry } from './extensions.js';
+import { f as EditorOperationPolicy, c as BlockPolicy, V as ValidationIssue, h as ExtensionRegistry } from './registry-eNtkEC6o.js';
+export { B as BlockDefinition, a as BlockEditorProps, b as BlockOperation, d as BlockVariantDefinition, D as DataSourceDefinition, E as EditorAction, e as EditorActionPosition, g as ExtensionActionContext, i as ExtensionRegistryError, j as ExtensionRegistryErrorCode, k as ExtensionRegistryOptions, l as ExtensionTarget, F as FieldConfig, m as FieldDefinition, n as FieldProps, o as FieldValidation, L as LifecycleHooks, P as PageBuilderExtension, R as RendererDefinition, T as TemplateDefinition, p as TemplateRegistry, q as TemplateSource, U as UISlotContribution, r as UISlotName, s as createExtensionRegistry, t as createTemplateRegistry } from './registry-eNtkEC6o.js';
 import { PageDocument, BlockNode, JsonValue } from './schema.js';
 export { BlockStyleOverrides, DataBinding, PageDocumentIssue, PageDocumentMigration, PageDocumentSchemaVersion, PageSettings, RenderTarget, createPageDocument, migratePageDocument, validatePageDocument } from './schema.js';
 export { ThemeTokenName, ThemeTokens, mergeThemeTokens, normalizeThemeTokens, systemThemeTokens, toThemeStyle } from './theme.js';
 import { Data } from '@puckeditor/core';
 export { WebRenderer, WebRendererProps } from './renderer.js';
+export { maximumBlockInstances, mergeBlockPolicies, minimumBlockInstances, validateBlockPolicy, validateFieldValue, validatePageDocumentWithRegistry } from './extensions.js';
 
 type BlockView = "blocks" | "outline";
 type Device = "desktop" | "tablet" | "mobile" | "full";
@@ -44,6 +45,100 @@ type EditorShellProps = {
 };
 declare function EditorShell({ initialState, iframe }: EditorShellProps): react.JSX.Element;
 
+/** Host-level rules that supplement policies declared by extension blocks. */
+type PageDocumentEditorPolicy = {
+    operations?: EditorOperationPolicy;
+    blocks?: Record<string, BlockPolicy>;
+};
+
+/** An opaque lease returned by the host's single-editor lock service. */
+type EditorSession = {
+    id: string;
+    expiresAt?: string;
+};
+type EditorSessionState = "acquiring" | "active" | "locked" | "lost" | "readonly";
+type EditorSessionAcquireResult = {
+    state: "active";
+    session: EditorSession;
+} | {
+    state: "locked";
+    message?: string;
+    editorName?: string;
+} | {
+    state: "readonly";
+    message?: string;
+};
+/**
+ * Host-owned single-editor locking. The package never stores locks or makes
+ * authorization decisions; it only coordinates the supplied lease.
+ */
+type EditorSessionAdapter = {
+    acquire(input: {
+        pageId: string;
+    }): Promise<EditorSessionAcquireResult>;
+    heartbeat?(input: {
+        pageId: string;
+        session: EditorSession;
+    }): Promise<void>;
+    release?(input: {
+        pageId: string;
+        session: EditorSession;
+    }): Promise<void>;
+    heartbeatIntervalMs?: number;
+};
+type DraftSaveInput = {
+    document: PageDocument;
+    expectedRevision?: number;
+    session?: EditorSession;
+};
+type DraftSaveResult = {
+    revision?: number;
+    savedAt?: string;
+};
+/** Host-owned draft persistence used by manual and automatic saves. */
+type DraftPersistenceAdapter = {
+    saveDraft(input: DraftSaveInput): Promise<DraftSaveResult | void>;
+};
+type PublishActionInput = DraftSaveInput & {
+    validationIssues: readonly ValidationIssue[];
+};
+type PublishActionResult = {
+    versionId?: string;
+    versionLabel?: string;
+    publishedAt?: string;
+};
+/** Host-owned publication transaction. It should validate and publish atomically. */
+type PublishAction = {
+    publish(input: PublishActionInput): Promise<PublishActionResult | void>;
+};
+type AssetStatus = "ready" | "processing" | "failed" | "missing";
+type AssetReference = {
+    id: string;
+    url: string;
+    alt?: string;
+    status?: AssetStatus;
+};
+/**
+ * Opens a host-owned, shop-scoped asset picker. Upload, access checks, and
+ * storage remain outside the editor package.
+ */
+type AssetPickerAdapter = {
+    selectAsset(input: {
+        pageId: string;
+        blockId: string;
+        current?: Partial<AssetReference>;
+    }): Promise<AssetReference | null>;
+};
+type PagePublicationStatus = "unpublished" | "published";
+/** Presentational data for the reusable page state card. */
+type PageStatus = {
+    draftLabel?: string;
+    publicationStatus: PagePublicationStatus;
+    publishedVersionLabel?: string;
+    lastSavedAt?: string;
+    editingBy?: string;
+};
+
 type EditorLoadState = "loading" | "ready" | "empty" | "error" | "disabled" | "success";
 type EditorActionState = {
     canUndo: boolean;
@@ -58,32 +153,48 @@ type EditorContextValue = {
     document: PageDocument;
     selectedBlockId: string | null;
     selectedBlock: BlockNode | null;
+    pendingDeleteBlock: BlockNode | null;
     canvasSelectionRequest: string | null;
     device: Device;
     loadState: EditorLoadState;
+    sessionState: EditorSessionState;
+    session?: EditorSession;
+    sessionMessage?: string;
+    isEditable: boolean;
     isDirty: boolean;
     actionState: EditorActionState;
+    canAddBlock(type: string): boolean;
+    canDragBlock(id: string): boolean;
     /** Request a canvas selection. The inspector changes only after Puck confirms it. */
     requestCanvasSelection(id: string): void;
     /** Called from the canvas/Puck selection event. */
     confirmCanvasSelection(id: string | null): void;
     /** Applies an edit that originated in the canvas engine. */
-    updateFromCanvas(document: PageDocument): void;
+    updateFromCanvas(document: PageDocument): boolean;
     setDevice(device: Device): void;
     addBlock(type: string, beforeId?: string): string | null;
     duplicateBlock(id: string): void;
+    requestDeleteBlock(id: string): void;
+    cancelDeleteBlock(): void;
+    confirmDeleteBlock(): void;
     deleteBlock(id: string): void;
     moveBlock(id: string, direction: -1 | 1): void;
     reorderBlock(id: string, beforeId: string): void;
     updateBlockProps(id: string, props: Record<string, JsonValue>): void;
+    updateBlockPresentation(id: string, presentation: Pick<BlockNode, "variant" | "style">): void;
     undo(): void;
     redo(): void;
-    markSaved(): void;
+    /** Marks the persisted snapshot clean without discarding edits made while saving. */
+    markSaved(document?: PageDocument): void;
 };
-declare function EditorProvider({ initialDocument, registry, loadState, leaveWarning, onDocumentChange, children }: {
+declare function EditorProvider({ initialDocument, registry, policy, loadState, sessionState, session, sessionMessage, leaveWarning, onDocumentChange, children }: {
     initialDocument: PageDocument;
     registry?: ExtensionRegistry;
+    policy?: PageDocumentEditorPolicy;
     loadState?: EditorLoadState;
+    sessionState?: EditorSessionState;
+    session?: EditorSession;
+    sessionMessage?: string;
     leaveWarning?: string;
     onDocumentChange?: (document: PageDocument) => void;
     children: ReactNode;
@@ -94,17 +205,62 @@ type PageDocumentEditorShellProps = {
     initialDocument: PageDocument;
     iframe?: boolean;
     registry?: ExtensionRegistry;
+    /** Limits the add-block library; existing document blocks remain editable. */
+    availableBlockTypes?: readonly string[];
+    /** Enables generic Variant and token-only style editing in the inspector. */
+    appearanceControls?: boolean;
+    /** Host rules that supplement block-declared operation and cardinality policies. */
+    policy?: PageDocumentEditorPolicy;
+    /** Copy or presentation overrides for the built-in, two-step deletion dialog. */
+    deleteConfirmation?: DeleteConfirmationConfig;
     /** Presentation states are explicit so host applications can provide a consistent Admin experience. */
     loadState?: EditorLoadState;
     adminLocale?: string;
     onDocumentChange?: (document: PageDocument) => void;
-    /** Persist the current draft. The shell marks the document clean only after this resolves. */
+    /** @deprecated Prefer draftPersistence so revision and edit-session metadata are preserved. */
     onSave?: (document: PageDocument) => Promise<void> | void;
-    /** Publish the current document. Hosts should persist it atomically with publication. */
+    /** @deprecated Prefer publishAction so revision and edit-session metadata are preserved. */
     onPublish?: (document: PageDocument) => Promise<void> | void;
+    /** Host-owned single-editor lock. Without this adapter the package stays backwards-compatible and editable. */
+    sessionAdapter?: EditorSessionAdapter;
+    onSessionStateChange?: (state: EditorSessionState) => void;
+    /** Host-owned draft persistence shared by the manual-save and 800ms autosave paths. */
+    draftPersistence?: DraftPersistenceAdapter;
+    draftRevision?: number;
+    autoSave?: boolean;
+    autoSaveDelayMs?: number;
+    /** Host-owned atomic publish transaction. */
+    publishAction?: PublishAction;
+    /** Host-owned picker/uploader for shop-scoped assets. */
+    assetPicker?: AssetPickerAdapter;
+    /** Optional reusable page lifecycle summary. */
+    pageStatus?: PageStatus;
+    onBack?: () => void;
+    onPreview?: (input: {
+        document: PageDocument;
+        draftRevision?: number;
+        session?: EditorSession;
+    }) => Promise<void> | void;
+    onAddToStore?: (input: {
+        document: PageDocument;
+        session?: EditorSession;
+    }) => Promise<void> | void;
+};
+type DeleteConfirmationConfig = {
+    title?: string;
+    message?: (block: BlockNode) => ReactNode;
+    cancelLabel?: string;
+    confirmLabel?: string;
 };
 declare function PageDocumentEditorShell(props: PageDocumentEditorShellProps): react.JSX.Element;
 
+type PageStatusCardProps = {
+    status: PageStatus;
+    sessionState?: EditorSessionState;
+};
+/** A small, host-data-driven summary suitable for an editor header or page list. */
+declare function PageStatusCard({ status, sessionState }: PageStatusCardProps): react.JSX.Element;
+
 type AdminLocale = "zh-CN" | "en";
 declare const messages: {
     readonly "zh-CN": {
@@ -116,6 +272,10 @@ declare const messages: {
         readonly redo: "恢复";
         readonly duplicate: "复制";
         readonly remove: "删除";
+        readonly confirmDeleteTitle: "确认删除区块？";
+        readonly confirmDeleteMessage: "删除后可使用撤销恢复。";
+        readonly cancel: "取消";
+        readonly confirm: "确认删除";
         readonly moveUp: "上移";
         readonly moveDown: "下移";
         readonly loading: "正在加载编辑器…";
@@ -130,8 +290,21 @@ declare const messages: {
         readonly publish: "发布";
         readonly publishing: "正在发布…";
         readonly saveFailed: "保存草稿失败";
+        readonly retrySave: "重试保存";
+        readonly offline: "当前离线，恢复网络后将自动保存";
         readonly publishFailed: "发布失败";
         readonly published: "已发布";
+        readonly back: "返回";
+        readonly confirmLeaveTitle: "离开编辑器？";
+        readonly leave: "离开";
+        readonly zoom: "缩放";
+        readonly zoomAuto: "自动缩放";
+        readonly preview: "正式预览";
+        readonly addToStore: "添加到店铺";
+        readonly acquiringLock: "正在获取编辑锁…";
+        readonly locked: "该页面正在被编辑";
+        readonly lockLost: "编辑锁已失效";
+        readonly readonly: "页面为只读状态";
         readonly leaveWarning: "你有未保存的更改。确定要离开吗？";
         readonly selectBlock: "选择一个区块以编辑。";
         readonly desktop: "桌面";
@@ -147,6 +320,10 @@ declare const messages: {
         readonly redo: "Redo";
         readonly duplicate: "Duplicate";
         readonly remove: "Delete";
+        readonly confirmDeleteTitle: "Delete this block?";
+        readonly confirmDeleteMessage: "You can restore it with Undo after deleting.";
+        readonly cancel: "Cancel";
+        readonly confirm: "Delete block";
         readonly moveUp: "Move up";
         readonly moveDown: "Move down";
         readonly loading: "Loading editor…";
@@ -161,8 +338,21 @@ declare const messages: {
         readonly publish: "Publish";
         readonly publishing: "Publishing…";
         readonly saveFailed: "Could not save draft";
+        readonly retrySave: "Retry save";
+        readonly offline: "Offline — changes will save when connection returns";
         readonly publishFailed: "Could not publish";
         readonly published: "Published";
+        readonly back: "Back";
+        readonly confirmLeaveTitle: "Leave the editor?";
+        readonly leave: "Leave";
+        readonly zoom: "Zoom";
+        readonly zoomAuto: "Auto zoom";
+        readonly preview: "Preview";
+        readonly addToStore: "Add to store";
+        readonly acquiringLock: "Acquiring edit lock…";
+        readonly locked: "This page is being edited";
+        readonly lockLost: "The edit lock has expired";
+        readonly readonly: "This page is read-only";
         readonly leaveWarning: "You have unsaved changes. Are you sure you want to leave?";
         readonly selectBlock: "Select a block to edit it.";
         readonly desktop: "Desktop";
@@ -174,10 +364,10 @@ type AdminMessageKey = keyof typeof messages["zh-CN"];
 /** Minimal, dependency-free Admin copy catalog. Product locale remains PageDocument.settings.locale. */
 declare function createAdminI18n(locale?: string): {
     locale: AdminLocale;
-    t: (key: AdminMessageKey) => "Desktop" | "Tablet" | "Mobile" | "未保存变更" | "Outline" | "区块" | "结构" | "撤销" | "恢复" | "属性" | "添加区块" | "复制" | "删除" | "上移" | "下移" | "正在加载编辑器…" | "页面还没有区块" | "编辑器无法加载" | "编辑器当前不可编辑" | "操作已完成" | "所有更改已保留在当前会话中" | "保存草稿" | "正在保存…" | "发布" | "正在发布…" | "保存草稿失败" | "发布失败" | "已发布" | "你有未保存的更改。确定要离开吗？" | "选择一个区块以编辑。" | "桌面" | "平板" | "手机" | "Blocks" | "Properties" | "Add block" | "Undo" | "Redo" | "Duplicate" | "Delete" | "Move up" | "Move down" | "Loading editor…" | "This page has no blocks" | "The editor could not load" | "The editor is currently read-only" | "Action completed" | "Unsaved changes" | "Changes are kept in this session" | "Save draft" | "Saving…" | "Publish" | "Publishing…" | "Could not save draft" | "Could not publish" | "Published" | "You have unsaved changes. Are you sure you want to leave?" | "Select a block to edit it.";
+    t: (key: AdminMessageKey) => "Desktop" | "Tablet" | "Mobile" | "未保存变更" | "Outline" | "Preview" | "缩放" | "区块" | "结构" | "撤销" | "恢复" | "Delete" | "Duplicate" | "编辑锁已失效" | "属性" | "添加区块" | "复制" | "删除" | "确认删除区块？" | "删除后可使用撤销恢复。" | "取消" | "确认删除" | "上移" | "下移" | "正在加载编辑器…" | "页面还没有区块" | "编辑器无法加载" | "编辑器当前不可编辑" | "操作已完成" | "所有更改已保留在当前会话中" | "保存草稿" | "正在保存…" | "发布" | "正在发布…" | "保存草稿失败" | "重试保存" | "当前离线，恢复网络后将自动保存" | "发布失败" | "已发布" | "返回" | "离开编辑器？" | "离开" | "自动缩放" | "正式预览" | "添加到店铺" | "正在获取编辑锁…" | "该页面正在被编辑" | "页面为只读状态" | "你有未保存的更改。确定要离开吗？" | "选择一个区块以编辑。" | "桌面" | "平板" | "手机" | "Blocks" | "Properties" | "Add block" | "Undo" | "Redo" | "Delete this block?" | "You can restore it with Undo after deleting." | "Cancel" | "Delete block" | "Move up" | "Move down" | "Loading editor…" | "This page has no blocks" | "The editor could not load" | "The editor is currently read-only" | "Action completed" | "Unsaved changes" | "Changes are kept in this session" | "Save draft" | "Saving…" | "Publish" | "Publishing…" | "Could not save draft" | "Retry save" | "Offline — changes will save when connection returns" | "Could not publish" | "Published" | "Back" | "Leave the editor?" | "Leave" | "Zoom" | "Auto zoom" | "Add to store" | "Acquiring edit lock…" | "This page is being edited" | "The edit lock has expired" | "This page is read-only" | "You have unsaved changes. Are you sure you want to leave?" | "Select a block to edit it.";
 };
 
 declare function toEngineData(document: PageDocument, registry?: ExtensionRegistry): Data;
 declare function fromEngineData(data: Data, base: PageDocument, registry?: ExtensionRegistry): PageDocument;
 
-export { type AdminLocale, type AdminMessageKey, BlockNode, type DemoBlock, type Device, type EditorActionState, type EditorLoadState, EditorProvider, EditorShell, type EditorShellProps, type EditorState, ExtensionRegistry, JsonValue, PageDocument, PageDocumentEditorShell, type PageDocumentEditorShellProps, type PreviewMode, type PublishState, type SaveState, type Zoom, createAdminI18n, fromEngineData, toEngineData, useEditorContext };
+export { type AdminLocale, type AdminMessageKey, type AssetPickerAdapter, type AssetReference, type AssetStatus, BlockNode, BlockPolicy, type DeleteConfirmationConfig, type DemoBlock, type Device, type DraftPersistenceAdapter, type DraftSaveInput, type DraftSaveResult, type EditorActionState, type EditorLoadState, EditorOperationPolicy, EditorProvider, type EditorSession, type EditorSessionAcquireResult, type EditorSessionAdapter, type EditorSessionState, EditorShell, type EditorShellProps, type EditorState, ExtensionRegistry, JsonValue, PageDocument, type PageDocumentEditorPolicy, PageDocumentEditorShell, type PageDocumentEditorShellProps, type PagePublicationStatus, type PageStatus, PageStatusCard, type PageStatusCardProps, type PreviewMode, type PublishAction, type PublishActionInput, type PublishActionResult, type PublishState, type SaveState, ValidationIssue, type Zoom, createAdminI18n, fromEngineData, toEngineData, useEditorContext };