@openeditor/custom-block 0.0.46 → 0.0.47

package/README.md

@@ -1,60 +1,42 @@
-# OpenEditor custom blocks
+# `@openeditor/custom-block`
 
-`@openeditor/custom-block` defines the only public custom-block interface. Every installed block uses the fixed `customBlock` document node. Installation does not change the ProseMirror schema.
+Use this package to add trusted, build-time custom blocks to OpenEditor without adding a ProseMirror node type for each block.
 
-Use the headless entry point for the portable definition, registry, validation manifest, migrations, and static export. Import authoring code from `@openeditor/custom-block/editor`. Import published Viewer code from `@openeditor/custom-block/viewer`. The Viewer entry point does not import Tiptap or editor code.
+OpenEditor stores every installed block in one atomic `customBlock` node. A block package owns its data parser, version migration, static output, and asset references. OpenEditor owns the envelope, registry, editor and Viewer lifecycle, missing-block fallback, and safe HTML serialization.
 
 ```ts
-import { defineOpenEditorCustomBlock } from "@openeditor/custom-block";
+import {
+  createOpenEditorCustomBlockRegistry,
+  defineOpenEditorCustomBlock,
+} from "@openeditor/custom-block";
 
-export const card = defineOpenEditorCustomBlock({
+type CardData = { title: string };
+
+export const card = defineOpenEditorCustomBlock<CardData>({
   id: "acme.card",
   label: "Card",
   version: 1,
-  dataSchema: {
-    type: "object",
-    properties: { title: { type: "string", minLength: 1 } },
-    required: ["title"],
-    additionalProperties: false,
+  createData: () => ({ title: "Untitled" }),
+  parseData: (value) => {
+    if (!value || typeof value !== "object" || !("title" in value))
+      throw new Error("Card title is required.");
+    if (typeof value.title !== "string")
+      throw new Error("Card title must be a string.");
+    return { title: value.title };
   },
-  initialData: () => ({ title: "Untitled" }),
   toHtml: ({ data }) => ({ tag: "article", children: [data.title] }),
   toText: ({ data }) => data.title,
 });
-```
-
-Static HTML uses an OpenEditor-owned safe tree. It does not accept raw HTML. Use the general `{ type: "document" }` data schema and the Editor and Viewer `host.fields.document` adapters for nested rich documents. Use `host.resolveUrl`, `host.links`, `host.icons`, and `host.assets` for product-neutral host facilities.
-
-Define authoring and published Viewer adapters in separate files:
-
-```tsx
-// card-editor.tsx
-import { defineOpenEditorCustomBlockEditor } from "@openeditor/custom-block/editor";
-import { card } from "./card";
 
-export const cardEditor = defineOpenEditorCustomBlockEditor({
-  block: card,
-  render: ({ data, updateData }) => (
-    <input value={data.title} onChange={(event) => updateData({ title: event.target.value })} />
-  ),
-});
+export const registry = createOpenEditorCustomBlockRegistry([card]);
 ```
 
-```tsx
-// card-viewer.tsx
-import { defineOpenEditorCustomBlockViewer } from "@openeditor/custom-block/viewer";
-import { card } from "./card";
-
-export const cardViewer = defineOpenEditorCustomBlockViewer({
-  block: card,
-  render: ({ data }) => <article>{data.title}</article>,
-});
-```
+The parser is the authoritative data contract. Use the same registry in the browser, backend, publisher, migration, and exporters. This prevents validation rules from drifting across environments.
 
-Create one registry from headless definitions. Pass Editor adapters only to authoring surfaces and Viewer adapters only to `@openeditor/react/viewer`. The host provides `fields.document`, safe URL resolution, optional navigation, icon catalog, and managed raster assets. A Viewer adapter cannot update saved data.
+Import React editor adapters from `@openeditor/custom-block/editor`. Import published Viewer adapters from `@openeditor/custom-block/viewer`. The Viewer entry point does not import Tiptap or editor code.
 
-Use integer-keyed `migrations` to convert stored data to the current version. Missing, disabled, incompatible, and invalid blocks preserve the original node and return an explicit registry resolution status. Backends validate `registry.manifests` with `validateOpenEditorCustomBlockEnvelope`; manifests contain JSON only and do not execute extension code. Use `conformOpenEditorCustomBlock(definition)` in each block package test to verify initial data, manifest validation, and safe static output.
+Use `migrate` only while a stored data version is active. The function must return the complete next envelope and increase the version. A final application release can remove the migration after all stored documents use the current version.
 
-Use `{ type: "string", format: "asset-id" }` for a host-managed asset reference. Asset IDs are opaque, have a maximum of 128 characters, and cannot contain URLs, paths, whitespace, or control characters. A backend can call `extractOpenEditorCustomBlockAssetReferences(envelope, manifests)` to authorize all asset references, including references in nested OpenEditor document fields, without loading block code.
+Use `assets` to return host-managed asset IDs and JSON paths. The host authorizes and resolves these opaque IDs. Block packages do not receive storage clients or credentials.
 
-Portable `constraints` cover primitive and keyed uniqueness, scoped map keys, references, acyclic graphs, and conditional URL policies. For example, `keysIn` can validate each directory row against the column IDs in the same directory. These constraints are JSON data in the manifest and run in backend validation.
+Use `conformOpenEditorCustomBlock` in each block package test. It verifies initial data, parsing, and safe static output.

package/dist/index.d.ts

@@ -1,17 +1,11 @@
-import { JsonValue, OpenEditorDocument, ProseMirrorNode } from '@openeditor/core';
+import { OpenEditorDocument, ProseMirrorNode } from '@openeditor/core';
 export { JsonObject as OpenEditorCustomBlockJsonObject, JsonValue as OpenEditorCustomBlockJsonValue, OpenEditorDocument } from '@openeditor/core';
 
 declare const OPENEDITOR_CUSTOM_BLOCK_NODE: "customBlock";
 
 type OpenEditorCustomBlockId = `${string}.${string}`;
-/**
- * A block-owned data record. The portable schema and bounded JSON validator
- * enforce JSON at runtime. `unknown` values at this type boundary also allow
- * the structurally wider `OpenEditorDocument` type in declared document fields.
- */
-type OpenEditorCustomBlockData = Record<string, unknown>;
-/** Preserves a block's precise field types, including nested document fields. */
-type OpenEditorCustomBlockDataShape<TData extends object> = TData;
+/** A block-owned object. Runtime parsing still requires JSON-only plain data. */
+type OpenEditorCustomBlockData = object;
 type OpenEditorCustomBlockEnvelope<TData extends OpenEditorCustomBlockData = OpenEditorCustomBlockData> = {
     blockId: OpenEditorCustomBlockId;
     version: number;
@@ -25,93 +19,19 @@ type OpenEditorCustomBlockDiagnostic = {
     path: string;
     message: string;
 };
-type PortableSchemaBase = {
-    nullable?: boolean;
-    enum?: readonly JsonValue[];
+type OpenEditorCustomBlockAssetReference = {
+    id: string;
+    path: string;
 };
-type OpenEditorCustomBlockDataSchema = PortableSchemaBase & ({
-    type: "any";
-} | {
-    type: "string";
-    minLength?: number;
-    maxLength?: number;
-    format?: "asset-id";
-} | {
-    type: "number";
-    integer?: boolean;
-    minimum?: number;
-    maximum?: number;
-} | {
-    type: "boolean";
-} | {
-    type: "null";
-} | {
-    type: "oneOf";
-    variants: readonly OpenEditorCustomBlockDataSchema[];
-} | {
-    type: "document";
-} | {
-    type: "array";
-    items?: OpenEditorCustomBlockDataSchema;
-    minItems?: number;
-    maxItems?: number;
-} | {
-    type: "object";
-    properties?: Readonly<Record<string, OpenEditorCustomBlockDataSchema>>;
-    required?: readonly string[];
-    additionalProperties?: boolean | OpenEditorCustomBlockDataSchema;
-});
 type OpenEditorCustomBlockManifest = {
     id: OpenEditorCustomBlockId;
     label: string;
     version: number;
-    dataSchema: OpenEditorCustomBlockDataSchema;
-    constraints?: readonly OpenEditorCustomBlockConstraint[];
 };
-type OpenEditorCustomBlockConstraint = {
-    kind: "unique";
-    array: string;
-} | {
-    kind: "uniqueBy";
-    array: string;
-    keys: readonly string[];
-} | {
-    kind: "keysIn";
-    scope?: string;
-    objects: string;
-    keys: string;
-    requireAll?: boolean;
-} | {
-    kind: "reference";
-    array: string;
-    field: string;
-    targetArray: string;
-    targetField: string;
-    nullable?: boolean;
-} | {
-    kind: "acyclic";
-    array: string;
-    id: string;
-    parent: string;
-} | {
-    kind: "graph";
-    array: string;
-    id: string;
-    parent: string;
-    siblingKeys?: readonly string[];
-} | {
-    kind: "url";
-    path: string;
-    allowRelative?: boolean;
-    requireSchemeSeparator?: boolean;
-    schemes?: readonly string[];
-    denySchemes?: readonly string[];
-    when?: {
-        field: string;
-        equals: JsonValue;
-    };
-};
-type OpenEditorCustomBlockMigration = (data: Readonly<OpenEditorCustomBlockData>) => OpenEditorCustomBlockData;
+type OpenEditorCustomBlockMigration = (input: {
+    version: number;
+    data: Readonly<OpenEditorCustomBlockData>;
+}) => OpenEditorCustomBlockEnvelope;
 type OpenEditorCustomBlockStaticContext<TData extends OpenEditorCustomBlockData> = {
     data: Readonly<TData>;
     renderDocument: (document: OpenEditorDocument) => OpenEditorCustomBlockSafeHtml;
@@ -122,31 +42,22 @@ type OpenEditorCustomBlockSafeHtml = string | number | null | false | {
     attrs?: Readonly<Partial<Record<"aria-label" | "aria-current" | "role" | "title" | "href" | "src" | "alt" | "width" | "height" | "start" | "colspan" | "rowspan" | "scope", string | number | undefined>>>;
     children?: readonly OpenEditorCustomBlockSafeHtml[];
 };
+/**
+ * The complete non-React contract for one installed block. The block package
+ * owns parsing because OpenEditor cannot know a third-party data model.
+ */
 type OpenEditorCustomBlockDefinition<TData extends OpenEditorCustomBlockData = any> = {
     id: OpenEditorCustomBlockId;
     label: string;
     version: number;
-    dataSchema: OpenEditorCustomBlockDataSchema;
-    initialData: () => TData;
-    /** Optional in-process refinement. This function is not included in the portable manifest. */
-    validateData?: (data: Readonly<TData>) => string | readonly string[] | null | undefined;
-    constraints?: readonly OpenEditorCustomBlockConstraint[];
-    migrations?: Readonly<Record<number, OpenEditorCustomBlockMigration>>;
+    createData: () => TData;
+    parseData: (data: unknown) => TData;
+    migrate?: OpenEditorCustomBlockMigration;
+    assets?: (data: Readonly<TData>) => readonly OpenEditorCustomBlockAssetReference[];
     toHtml: (context: OpenEditorCustomBlockStaticContext<TData>) => OpenEditorCustomBlockSafeHtml;
     toText: (context: OpenEditorCustomBlockStaticContext<TData>) => string;
     manifest: OpenEditorCustomBlockManifest;
 };
-/** Opaque host asset IDs. URLs, paths, whitespace, and control characters are not valid. */
-declare const OPENEDITOR_CUSTOM_BLOCK_ASSET_ID_PATTERN: RegExp;
-/** Validates one value against a portable JSON-only custom-block schema. */
-declare const validateOpenEditorCustomBlockDataValue: (value: unknown, schema: OpenEditorCustomBlockDataSchema) => {
-    valid: true;
-    diagnostics: readonly [];
-} | {
-    valid: false;
-    diagnostics: readonly OpenEditorCustomBlockDiagnostic[];
-};
-declare const defineOpenEditorCustomBlock: <TData extends OpenEditorCustomBlockData>(input: Omit<OpenEditorCustomBlockDefinition<TData>, "manifest">) => OpenEditorCustomBlockDefinition<TData>;
 type UnavailableStatus = "missing" | "disabled" | "incompatible" | "invalid";
 type OpenEditorResolvedCustomBlock<TData extends OpenEditorCustomBlockData = OpenEditorCustomBlockData> = {
     status: "ready";
@@ -166,50 +77,17 @@ type OpenEditorCustomBlockRegistry = {
     get: (id: string) => OpenEditorCustomBlockDefinition | undefined;
     isEnabled: (id: string) => boolean;
     resolve: (node: ProseMirrorNode) => OpenEditorResolvedCustomBlock;
+    validate: (envelope: unknown) => {
+        valid: true;
+        envelope: OpenEditorCustomBlockEnvelope;
+    } | {
+        valid: false;
+        diagnostics: readonly OpenEditorCustomBlockDiagnostic[];
+    };
+    assets: (envelope: unknown) => readonly OpenEditorCustomBlockAssetReference[];
     toHtml: (node: ProseMirrorNode) => string;
     toText: (node: ProseMirrorNode) => string;
 };
-declare const escapeOpenEditorCustomBlockHtml: (value: unknown) => string;
-declare const renderOpenEditorCustomBlockSafeHtml: (value: OpenEditorCustomBlockSafeHtml) => string;
-declare const createOpenEditorCustomBlockRegistry: (definitions: readonly OpenEditorCustomBlockDefinition[], options?: {
-    disabled?: readonly string[];
-    renderDocument?: (document: OpenEditorDocument) => OpenEditorCustomBlockSafeHtml;
-    documentToText?: (document: OpenEditorDocument) => string;
-}) => OpenEditorCustomBlockRegistry;
-declare const createOpenEditorCustomBlockNode: <TData extends OpenEditorCustomBlockData>(registry: OpenEditorCustomBlockRegistry, id: string, data?: TData, options?: {
-    instanceId?: string;
-    createInstanceId?: () => string;
-}) => OpenEditorCustomBlockNode<TData>;
-declare const resolveOpenEditorCustomBlockNode: (registry: OpenEditorCustomBlockRegistry, node: ProseMirrorNode) => OpenEditorResolvedCustomBlock<OpenEditorCustomBlockData>;
-declare const validateOpenEditorCustomBlockEnvelope: (value: unknown, manifests: readonly OpenEditorCustomBlockManifest[], options?: {
-    mode?: "strict" | "preserve";
-    disabled?: readonly string[];
-}) => {
-    valid: false;
-    diagnostics: {
-        path: string;
-        message: string;
-    }[];
-    status?: undefined;
-} | {
-    valid: true;
-    diagnostics: readonly [];
-    status: "preserved";
-} | {
-    valid: true;
-    diagnostics: OpenEditorCustomBlockDiagnostic[];
-    status: "preserved-invalid";
-} | {
-    valid: true;
-    diagnostics: readonly [];
-    status?: undefined;
-};
-type OpenEditorCustomBlockAssetReference = {
-    id: string;
-    path: string;
-};
-/** Extracts host asset IDs from a portable manifest without loading extension code. */
-declare const extractOpenEditorCustomBlockAssetReferences: (value: unknown, manifests: readonly OpenEditorCustomBlockManifest[]) => readonly OpenEditorCustomBlockAssetReference[];
 type OpenEditorCustomBlockIcon = {
     id: string;
     label: string;
@@ -246,12 +124,27 @@ type OpenEditorCustomBlockHost = {
         } | null>;
     };
 };
-type OpenEditorCustomBlockDocumentField = {
-    value: OpenEditorDocument;
-    onChange?: (value: OpenEditorDocument) => void;
-    readOnly: boolean;
+declare const defineOpenEditorCustomBlock: <TData extends OpenEditorCustomBlockData>(input: Omit<OpenEditorCustomBlockDefinition<TData>, "manifest">) => OpenEditorCustomBlockDefinition<TData>;
+declare const createOpenEditorCustomBlockRegistry: (definitions: readonly OpenEditorCustomBlockDefinition[], options?: {
+    disabled?: readonly string[];
+    renderDocument?: (document: OpenEditorDocument) => OpenEditorCustomBlockSafeHtml;
+    documentToText?: (document: OpenEditorDocument) => string;
+}) => OpenEditorCustomBlockRegistry;
+declare const createOpenEditorCustomBlockNode: <TData extends OpenEditorCustomBlockData>(registry: OpenEditorCustomBlockRegistry, id: string, data?: TData, options?: {
+    instanceId?: string;
+    createInstanceId?: () => string;
+}) => OpenEditorCustomBlockNode<TData>;
+declare const resolveOpenEditorCustomBlockNode: (registry: OpenEditorCustomBlockRegistry, node: ProseMirrorNode) => OpenEditorResolvedCustomBlock<object>;
+declare const validateOpenEditorCustomBlockEnvelope: (value: unknown, registry: Pick<OpenEditorCustomBlockRegistry, "validate">) => {
+    valid: true;
+    envelope: OpenEditorCustomBlockEnvelope;
+} | {
+    valid: false;
+    diagnostics: readonly OpenEditorCustomBlockDiagnostic[];
 };
-/** Runs portable checks that custom-block packages can include in their test suites. */
+declare const extractOpenEditorCustomBlockAssetReferences: (value: unknown, registry: Pick<OpenEditorCustomBlockRegistry, "assets">) => readonly OpenEditorCustomBlockAssetReference[];
 declare const conformOpenEditorCustomBlock: (definition: OpenEditorCustomBlockDefinition) => readonly OpenEditorCustomBlockDiagnostic[];
+declare const escapeOpenEditorCustomBlockHtml: (value: unknown) => string;
+declare const renderOpenEditorCustomBlockSafeHtml: (value: OpenEditorCustomBlockSafeHtml) => string;
 
-export { OPENEDITOR_CUSTOM_BLOCK_ASSET_ID_PATTERN, OPENEDITOR_CUSTOM_BLOCK_NODE, type OpenEditorCustomBlockAsset, type OpenEditorCustomBlockAssetReference, type OpenEditorCustomBlockConstraint, type OpenEditorCustomBlockData, type OpenEditorCustomBlockDataSchema, type OpenEditorCustomBlockDataShape, type OpenEditorCustomBlockDefinition, type OpenEditorCustomBlockDiagnostic, type OpenEditorCustomBlockDocumentField, type OpenEditorCustomBlockEnvelope, type OpenEditorCustomBlockHost, type OpenEditorCustomBlockIcon, type OpenEditorCustomBlockId, type OpenEditorCustomBlockManifest, type OpenEditorCustomBlockMigration, type OpenEditorCustomBlockNode, type OpenEditorCustomBlockRegistry, type OpenEditorCustomBlockSafeHtml, type OpenEditorCustomBlockStaticContext, type OpenEditorResolvedCustomBlock, conformOpenEditorCustomBlock, createOpenEditorCustomBlockNode, createOpenEditorCustomBlockRegistry, defineOpenEditorCustomBlock, escapeOpenEditorCustomBlockHtml, extractOpenEditorCustomBlockAssetReferences, renderOpenEditorCustomBlockSafeHtml, resolveOpenEditorCustomBlockNode, validateOpenEditorCustomBlockDataValue, validateOpenEditorCustomBlockEnvelope };
+export { OPENEDITOR_CUSTOM_BLOCK_NODE, type OpenEditorCustomBlockAsset, type OpenEditorCustomBlockAssetReference, type OpenEditorCustomBlockData, type OpenEditorCustomBlockDefinition, type OpenEditorCustomBlockDiagnostic, type OpenEditorCustomBlockEnvelope, type OpenEditorCustomBlockHost, type OpenEditorCustomBlockIcon, type OpenEditorCustomBlockId, type OpenEditorCustomBlockManifest, type OpenEditorCustomBlockMigration, type OpenEditorCustomBlockNode, type OpenEditorCustomBlockRegistry, type OpenEditorCustomBlockSafeHtml, type OpenEditorCustomBlockStaticContext, type OpenEditorResolvedCustomBlock, conformOpenEditorCustomBlock, createOpenEditorCustomBlockNode, createOpenEditorCustomBlockRegistry, defineOpenEditorCustomBlock, escapeOpenEditorCustomBlockHtml, extractOpenEditorCustomBlockAssetReferences, renderOpenEditorCustomBlockSafeHtml, resolveOpenEditorCustomBlockNode, validateOpenEditorCustomBlockEnvelope };