@standhigher/puck-page-builder 0.8.1 → 0.10.0

package/README.md

@@ -44,6 +44,31 @@ const page = <WebRenderer document={migration.data} registry={registry} />;
 | `@standhigher/puck-page-builder/schema` | schema-specific types and migration helpers |
 | `@standhigher/puck-page-builder/styles.css` | Builder and Web renderer styles |
 
+## Editor policies and field validation
+
+Blocks can declare portable interaction and cardinality rules. `required` keeps at least one instance; `singleton` prevents a second instance. Hosts can supplement those declarations with `PageDocumentEditorShell`'s `policy` prop, including globally disabling add, delete, duplicate, or drag operations. Deletion through the packaged editor always opens its built-in confirmation dialog before changing the document.
+
+```tsx
+const notice = {
+  // ...the normal BlockDefinition fields
+  policy: { singleton: true, allowDuplicate: false },
+  fields: {
+    title: { field: "acme.text", control: "text", required: true, validation: { maxLength: 80 } },
+    color: { field: "acme.color", control: "color" }
+  }
+};
+
+<PageDocumentEditorShell
+  initialDocument={document}
+  registry={registry}
+  policy={{ operations: { allowDrag: false } }}
+/>
+```
+
+Built-in field controls are `text` (single line), `textarea` (multi-line), `url`, and `color`. Their validation runs in the editor before save or publish; custom fields may continue using a block's `validate` function. `validateFieldValue` is exported from `/extensions` when a host needs the same validation outside the editor.
+
+Theme values remain deliberately token-based: template theme → page theme → variant theme → block style. A block resets an inherited token by setting its local token explicitly (for example `{ radius: "0" }`), so no incompatible persisted style-reset shape is needed.
+
 ## Runtime and DataSource boundary
 
 The package can register DataSources but does not automatically resolve `block.binding`, call a Live data source, or inject its result into `WebRenderer`. Implement authorization, data resolution, caching, error handling and temporary render-data projection in the host application's server-side Runtime. Do not persist tokens, credentials or resolved private data in `PageDocument`.

package/dist/{chunk-PUTYZI7B.js → chunk-PFCWXLWN.js}

@@ -1,3 +1,54 @@
+// src/core/extensions/validation.ts
+var hexColor = /^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i;
+function stringLength(value) {
+  return Array.from(value).length;
+}
+function isSafeUrl(value, config) {
+  if (value.startsWith("/")) return config.validation?.allowRelativeUrl !== false && !value.startsWith("//");
+  try {
+    const url = new URL(value);
+    if (url.username || url.password) return false;
+    if ((config.validation?.allowedUrlProtocols ?? ["https:", "http:"]).includes(url.protocol)) return true;
+    const editorRunsLocally = typeof window !== "undefined" && (window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1" || window.location.hostname === "[::1]");
+    return config.validation?.allowLocalhost === true && editorRunsLocally && url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]");
+  } catch {
+    return false;
+  }
+}
+function validateFieldValue(config, value) {
+  const control = config.control;
+  if (!control && !config.required && !config.validation) return [];
+  if (value === void 0 && !config.required) return [];
+  if (typeof value !== "string") return [{ path: "", message: "\u5FC5\u987B\u662F\u5B57\u7B26\u4E32\u3002" }];
+  const issues = [];
+  if (config.required && value.trim().length === 0) issues.push({ path: "", message: "\u6B64\u5B57\u6BB5\u4E3A\u5FC5\u586B\u9879\u3002" });
+  if (control === "text" && /[\r\n]/.test(value)) issues.push({ path: "", message: "\u5FC5\u987B\u4E3A\u5355\u884C\u6587\u672C\u3002" });
+  if (config.validation?.minLength !== void 0 && stringLength(value) < config.validation.minLength) issues.push({ path: "", message: `\u81F3\u5C11\u9700\u8981 ${config.validation.minLength} \u4E2A\u5B57\u7B26\u3002` });
+  if (config.validation?.maxLength !== void 0 && stringLength(value) > config.validation.maxLength) issues.push({ path: "", message: `\u6700\u591A\u5141\u8BB8 ${config.validation.maxLength} \u4E2A\u5B57\u7B26\u3002` });
+  if (value && control === "url" && !isSafeUrl(value, config)) issues.push({ path: "", message: "\u5FC5\u987B\u662F\u7AD9\u5185\u76F8\u5BF9\u8DEF\u5F84\u6216\u5141\u8BB8\u7684 HTTP(S) URL\u3002" });
+  if (value && control === "color" && !hexColor.test(value)) issues.push({ path: "", message: "\u5FC5\u987B\u662F\u5341\u516D\u8FDB\u5236\u989C\u8272\uFF0C\u4F8B\u5982 #005BD3\u3002" });
+  return issues;
+}
+function validateBlockPolicy(policy) {
+  if (!policy) return null;
+  for (const key of ["minInstances", "maxInstances"]) {
+    const value = policy[key];
+    if (value !== void 0 && (!Number.isInteger(value) || value < 0)) return `${key} \u5FC5\u987B\u662F\u5927\u4E8E\u6216\u7B49\u4E8E 0 \u7684\u6574\u6570`;
+  }
+  const minimum = Math.max(policy.required ? 1 : 0, policy.minInstances ?? 0);
+  const maximum = Math.min(policy.singleton ? 1 : Infinity, policy.maxInstances ?? Infinity);
+  return minimum > maximum ? "minInstances \u4E0D\u80FD\u5927\u4E8E maxInstances" : null;
+}
+function mergeBlockPolicies(...policies) {
+  return Object.assign({}, ...policies);
+}
+function minimumBlockInstances(policy) {
+  return Math.max(policy?.required ? 1 : 0, policy?.minInstances ?? 0);
+}
+function maximumBlockInstances(policy) {
+  return Math.min(policy?.singleton ? 1 : Infinity, policy?.maxInstances ?? Infinity);
+}
+
 // src/core/extensions/registry.ts
 var ExtensionRegistryError = class extends Error {
   constructor(code, message) {
@@ -163,7 +214,11 @@ var ExtensionRegistry = class _ExtensionRegistry {
     const templateItems = [];
     const slots = /* @__PURE__ */ new Map();
     for (const extension of resolved) {
-      for (const block of extension.blocks ?? []) assertTargets(block.targets, `Block ${block.type}`);
+      for (const block of extension.blocks ?? []) {
+        assertTargets(block.targets, `Block ${block.type}`);
+        const policyIssue = validateBlockPolicy(block.policy);
+        if (policyIssue) throw new ExtensionRegistryError("invalid-block-policy", `Block ${block.type} \u7684\u7B56\u7565\u65E0\u6548\uFF1A${policyIssue}`);
+      }
       register(blockItems, extension.blocks, extension.name, blocks, "Block");
       register(fieldItems, extension.fields, extension.name, fields, "Field");
       register(actionItems, extension.actions, extension.name, actions, "Action");
@@ -204,10 +259,70 @@ function createTemplateRegistry(templates, blocks = []) {
   return TemplateRegistry.create(registered, blocks);
 }
 
+// src/core/extensions/document-validation.ts
+var coreBlockProps = {
+  "core.text": ["content"],
+  "core.image": ["src", "alt"]
+};
+function supportsTarget(block, target) {
+  return block.targets.includes("all") || block.targets.includes(target);
+}
+function validateBlock(document, index, registry) {
+  const block = document.blocks[index];
+  const path = `blocks[${index}]`;
+  const definition = registry.getBlock(block.type);
+  const coreProps = coreBlockProps[block.type];
+  if (!definition && !coreProps) return [{ path, message: `\u672A\u6CE8\u518C\u533A\u5757\uFF1A${block.type}` }];
+  if (!definition) {
+    return Object.keys(block.props).filter((key) => !coreProps.includes(key)).map((key) => ({ path: `${path}.props.${key}`, message: "\u4E0D\u5141\u8BB8\u4FDD\u5B58\u672A\u77E5\u5B57\u6BB5\u3002" }));
+  }
+  const issues = [];
+  if (block.version !== definition.version) issues.push({ path: `${path}.version`, message: `\u533A\u5757\u7248\u672C\u5FC5\u987B\u4E3A ${definition.version}\u3002` });
+  if (!supportsTarget(definition, document.target)) issues.push({ path, message: `\u533A\u5757\u4E0D\u652F\u6301 ${document.target} target\u3002` });
+  if (definition.variants?.length && !definition.variants.some((variant) => variant.id === block.variant)) issues.push({ path: `${path}.variant`, message: `\u4E0D\u652F\u6301\u7684 variant\uFF1A${block.variant}\u3002` });
+  const allowedProps = /* @__PURE__ */ new Set([...Object.keys(definition.defaultProps), ...Object.keys(definition.fields)]);
+  for (const key of Object.keys(block.props)) {
+    if (!allowedProps.has(key)) issues.push({ path: `${path}.props.${key}`, message: "\u4E0D\u5141\u8BB8\u4FDD\u5B58\u672A\u77E5\u5B57\u6BB5\u3002" });
+  }
+  for (const [name, field] of Object.entries(definition.fields)) {
+    for (const issue of validateFieldValue(field, block.props[name])) {
+      issues.push({ ...issue, path: issue.path ? `${path}.props.${name}.${issue.path}` : `${path}.props.${name}` });
+    }
+  }
+  for (const issue of definition.validate?.(block.props) ?? []) {
+    const suffix = issue.path.startsWith("props.") ? issue.path.slice("props.".length) : issue.path;
+    issues.push({ ...issue, path: `${path}.props.${suffix}` });
+  }
+  if (block.binding) {
+    const source = registry.getDataSource(block.binding.source);
+    if (!source) issues.push({ path: `${path}.binding.source`, message: `\u672A\u6CE8\u518C\u6570\u636E\u6E90\uFF1A${block.binding.source}` });
+    else {
+      if (!definition.dataSources?.includes(source.key)) issues.push({ path: `${path}.binding.source`, message: "\u533A\u5757\u672A\u6388\u6743\u4F7F\u7528\u6B64\u6570\u636E\u6E90\u3002" });
+      for (const issue of source.validateParams?.(block.binding.params ?? {}) ?? []) {
+        issues.push({ ...issue, path: issue.path ? `${path}.binding.params.${issue.path}` : `${path}.binding.params` });
+      }
+    }
+  }
+  return issues;
+}
+function validatePageDocumentWithRegistry(document, registry) {
+  const issues = [];
+  if (document.templateId && !registry.getTemplate(document.templateId)) issues.push({ path: "templateId", message: `\u672A\u6CE8\u518C\u6A21\u677F\uFF1A${document.templateId}` });
+  if (document.templateId && document.templateVersion !== registry.getTemplate(document.templateId)?.version) issues.push({ path: "templateVersion", message: "\u6A21\u677F\u7248\u672C\u4E0E\u5DF2\u6CE8\u518C\u6A21\u677F\u4E0D\u4E00\u81F4\u3002" });
+  document.blocks.forEach((_, index) => issues.push(...validateBlock(document, index, registry)));
+  return issues;
+}
+
 export {
+  validateFieldValue,
+  validateBlockPolicy,
+  mergeBlockPolicies,
+  minimumBlockInstances,
+  maximumBlockInstances,
   ExtensionRegistryError,
   TemplateRegistry,
   ExtensionRegistry,
   createExtensionRegistry,
-  createTemplateRegistry
+  createTemplateRegistry,
+  validatePageDocumentWithRegistry
 };

package/dist/extensions.d.ts

@@ -1,188 +1,23 @@
-import { ComponentType, ReactNode } from 'react';
-import { RenderTarget, JsonValue, PageDocument } from './schema.js';
-import { ThemeTokens } from './theme.js';
+import { h as ExtensionRegistry, V as ValidationIssue, c as BlockPolicy, F as FieldConfig } 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, f as EditorOperationPolicy, g as ExtensionActionContext, i as ExtensionRegistryError, j as ExtensionRegistryErrorCode, k as ExtensionRegistryOptions, l as ExtensionTarget, 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 } from './schema.js';
+import 'react';
+import './theme.js';
 
-type ExtensionTarget = RenderTarget | "all";
-type EditorActionPosition = "left" | "center" | "right";
-type UISlotName = "toolbar.left" | "toolbar.center" | "toolbar.right" | "inspector.content";
-type ValidationIssue = {
-    path: string;
-    message: string;
-};
-type FieldConfig = {
-    field: string;
-    label?: string;
-    /** Product-facing editor metadata. Custom field components remain supported. */
-    control?: "text" | "textarea" | "url";
-    description?: string;
-    group?: string;
-    required?: boolean;
-};
-type FieldProps<T = unknown> = {
-    value: T;
-    onChange(value: T): void;
-};
 /**
- * Props available only to an extension's editor-canvas renderer.
- * They are separate from Web rendering so editor interaction cannot invoke a
- * host Runtime or become persisted operational data.
+ * Validates a structurally valid PageDocument against a concrete extension
+ * registry. Hosts should use it at draft and publish boundaries after
+ * migratePageDocument so unregistered blocks and undeclared props cannot
+ * enter persistent storage.
  */
-type BlockEditorProps<P = Record<string, unknown>> = P & {
-    blockId: string;
-    selected: boolean;
-    onPropsChange(props: Record<string, JsonValue>): void;
-};
-interface BlockDefinition<P = Record<string, unknown>> {
-    type: string;
-    version: number;
-    label: string;
-    category: string;
-    targets: ExtensionTarget[];
-    defaultProps: P;
-    fields: Record<string, FieldConfig>;
-    render: Partial<Record<RenderTarget, ComponentType<P>>> & {
-        /** Optional edit-mode renderer. WebRenderer never uses this surface. */
-        editor?: ComponentType<BlockEditorProps<P>>;
-    };
-    defaultVariant?: string;
-    variants?: BlockVariantDefinition[];
-    dataSources?: string[];
-    validate?: (props: P) => ValidationIssue[];
-}
-interface BlockVariantDefinition {
-    id: string;
-    label: string;
-    theme?: ThemeTokens;
-}
-interface FieldDefinition<T = unknown> {
-    type: string;
-    component: ComponentType<FieldProps<T>>;
-    normalize?: (value: T) => T;
-    validate?: (value: T) => ValidationIssue[];
-}
-type ExtensionActionContext = {
-    document: PageDocument;
-    pageId: string;
-    notify?(message: string): void;
-};
-interface EditorAction {
-    id: string;
-    label: string;
-    position: EditorActionPosition;
-    order?: number;
-    variant?: "default" | "primary" | "danger";
-    hidden?: (context: ExtensionActionContext) => boolean;
-    disabled?: (context: ExtensionActionContext) => boolean;
-    execute(context: ExtensionActionContext): Promise<void> | void;
-}
-interface RendererDefinition {
-    id: string;
-    target: RenderTarget;
-    render(document: PageDocument): ReactNode | string;
-}
-/**
- * `P` defaults to `any` so an extension may contribute a narrower, validated
- * parameter type while the framework-independent registry remains generic.
- */
-interface DataSourceDefinition<P = any, R = unknown> {
-    key: string;
-    mock: (params: P) => Promise<R>;
-    live: (params: P) => Promise<R>;
-    validateParams?: (params: P) => ValidationIssue[];
-}
-type TemplateSource = "built-in" | "marketplace" | "custom";
-interface TemplateDefinition {
-    id: string;
-    version: number;
-    name: string;
-    target: RenderTarget;
-    source: TemplateSource;
-    thumbnail?: string;
-    create(): PageDocument;
-    /** Block types that must be registered before this template can be used. */
-    requiredBlocks?: string[];
-    theme?: ThemeTokens;
-}
-interface LifecycleHooks {
-    onChange?(document: PageDocument): void;
-    beforeSave?(document: PageDocument): Promise<PageDocument>;
-    afterSave?(result: unknown): Promise<void>;
-    beforePublish?(document: PageDocument): Promise<PageDocument>;
-    afterPublish?(result: unknown): Promise<void>;
-    onError?(error: Error): void;
-}
-interface UISlotContribution {
-    id: string;
-    slot: UISlotName;
-    order?: number;
-    component: ComponentType;
-}
-interface PageBuilderExtension {
-    /** Namespaced, stable extension identifier, such as `besttrack.tracking`. */
-    name: string;
-    version: string;
-    order?: number;
-    dependsOn?: string[];
-    blocks?: BlockDefinition[];
-    fields?: FieldDefinition[];
-    actions?: EditorAction[];
-    renderers?: RendererDefinition[];
-    dataSources?: DataSourceDefinition[];
-    templates?: TemplateDefinition[];
-    hooks?: LifecycleHooks;
-    slots?: UISlotContribution[];
-}
-type ExtensionRegistryOptions = {
-    disabled?: string[];
-};
+declare function validatePageDocumentWithRegistry(document: PageDocument, registry: ExtensionRegistry): ValidationIssue[];
 
-type ExtensionRegistryErrorCode = "duplicate-extension" | "duplicate-definition" | "invalid-identifier" | "invalid-target" | "missing-dependency" | "missing-template-dependency" | "dependency-cycle";
-declare class ExtensionRegistryError extends Error {
-    readonly code: ExtensionRegistryErrorCode;
-    constructor(code: ExtensionRegistryErrorCode, message: string);
-}
-type Registered<T> = T & {
-    extension: string;
-};
-/** Immutable template view with explicit source and block dependency validation. */
-declare class TemplateRegistry {
-    private readonly templateMap;
-    private constructor();
-    get templates(): readonly Registered<TemplateDefinition>[];
-    get(id: string): Registered<TemplateDefinition> | undefined;
-    static create(templates: readonly Registered<TemplateDefinition>[], blocks: readonly BlockDefinition[]): TemplateRegistry;
-}
-/** Immutable compiled view of all enabled extensions. */
-declare class ExtensionRegistry {
-    readonly extensions: readonly PageBuilderExtension[];
-    private readonly blockMap;
-    private readonly fieldMap;
-    private readonly actionMap;
-    private readonly rendererMap;
-    private readonly dataSourceMap;
-    private readonly templateMap;
-    readonly templateRegistry: TemplateRegistry;
-    private readonly slotMap;
-    private readonly hooks;
-    private constructor();
-    get blocks(): readonly Registered<BlockDefinition<Record<string, unknown>>>[];
-    get fields(): readonly Registered<FieldDefinition<unknown>>[];
-    get actions(): readonly Registered<EditorAction>[];
-    get renderers(): readonly Registered<RendererDefinition>[];
-    get dataSources(): readonly Registered<DataSourceDefinition<any, unknown>>[];
-    get templates(): readonly Registered<TemplateDefinition>[];
-    getBlock(type: string): Registered<BlockDefinition<Record<string, unknown>>> | undefined;
-    getField(type: string): Registered<FieldDefinition<unknown>> | undefined;
-    getAction(id: string): Registered<EditorAction> | undefined;
-    getRenderer(id: string): Registered<RendererDefinition> | undefined;
-    getDataSource(key: string): Registered<DataSourceDefinition<any, unknown>> | undefined;
-    getTemplate(id: string): Registered<TemplateDefinition> | undefined;
-    getSlot(slot: UISlotName): readonly Registered<UISlotContribution>[];
-    notifyChange(document: PageDocument): void;
-    notifyError(error: Error): void;
-    static create(extensions: PageBuilderExtension[], options?: ExtensionRegistryOptions): ExtensionRegistry;
-}
-declare function createExtensionRegistry(extensions: PageBuilderExtension[], options?: ExtensionRegistryOptions): ExtensionRegistry;
-declare function createTemplateRegistry(templates: TemplateDefinition[], blocks?: BlockDefinition[]): TemplateRegistry;
+/** Validates the portable built-in controls without relying on browser-only APIs. */
+declare function validateFieldValue(config: FieldConfig, value: unknown): ValidationIssue[];
+/** Returns a diagnostic for an invalid declaration, or `null` when it is usable. */
+declare function validateBlockPolicy(policy: BlockPolicy | undefined): string | null;
+declare function mergeBlockPolicies(...policies: Array<BlockPolicy | undefined>): BlockPolicy;
+declare function minimumBlockInstances(policy: BlockPolicy | undefined): number;
+declare function maximumBlockInstances(policy: BlockPolicy | undefined): number;
 
-export { type BlockDefinition, type BlockEditorProps, type BlockVariantDefinition, type DataSourceDefinition, type EditorAction, type EditorActionPosition, type ExtensionActionContext, ExtensionRegistry, ExtensionRegistryError, type ExtensionRegistryErrorCode, type ExtensionRegistryOptions, type ExtensionTarget, type FieldConfig, type FieldDefinition, type FieldProps, type LifecycleHooks, type PageBuilderExtension, type RendererDefinition, type TemplateDefinition, TemplateRegistry, type TemplateSource, type UISlotContribution, type UISlotName, type ValidationIssue, createExtensionRegistry, createTemplateRegistry };
+export { BlockPolicy, ExtensionRegistry, FieldConfig, ValidationIssue, maximumBlockInstances, mergeBlockPolicies, minimumBlockInstances, validateBlockPolicy, validateFieldValue, validatePageDocumentWithRegistry };

package/dist/extensions.js

@@ -3,12 +3,24 @@ import {
   ExtensionRegistryError,
   TemplateRegistry,
   createExtensionRegistry,
-  createTemplateRegistry
-} from "./chunk-PUTYZI7B.js";
+  createTemplateRegistry,
+  maximumBlockInstances,
+  mergeBlockPolicies,
+  minimumBlockInstances,
+  validateBlockPolicy,
+  validateFieldValue,
+  validatePageDocumentWithRegistry
+} from "./chunk-PFCWXLWN.js";
 export {
   ExtensionRegistry,
   ExtensionRegistryError,
   TemplateRegistry,
   createExtensionRegistry,
-  createTemplateRegistry
+  createTemplateRegistry,
+  maximumBlockInstances,
+  mergeBlockPolicies,
+  minimumBlockInstances,
+  validateBlockPolicy,
+  validateFieldValue,
+  validatePageDocumentWithRegistry
 };