@wp-typia/block-types 0.3.0 → 0.3.1

package/README.md

@@ -108,6 +108,52 @@ generation. Non-strict mode downgrades them to warnings and recommends guarded
 generation. Unknown future keys are guarded by default, or passed through only
 when `allowUnknownFutureKeys` is enabled.
 
+## Diagnostic output policy
+
+Supports, Variations, and Bindings helpers keep diagnostics structured and
+silent by default. Strict diagnostics still throw grouped errors, but non-strict
+warnings do not write to `console.warn` unless a consumer opts into visible
+output.
+
+Use `onDiagnostic` when callers need callback-driven diagnostics for tests,
+custom reporting, or UI integration:
+
+```ts
+const diagnostics: Array<{ message: string; severity: 'warning' | 'error' }> =
+  [];
+
+defineSupports(
+  {
+    allowedBlocks: true,
+    minWordPress: '6.8',
+    strict: false,
+  },
+  {
+    onDiagnostic: (diagnostic) => {
+      diagnostics.push(diagnostic);
+    },
+  },
+);
+```
+
+Use `logger` when callers want formatted warning messages without taking over
+the structured callback path. Passing `console` restores console warning output.
+If both `onDiagnostic` and `logger` are provided, `onDiagnostic` handles the
+diagnostic and the logger is not called.
+
+```ts
+defineSupports(
+  {
+    allowedBlocks: true,
+    minWordPress: '6.8',
+    strict: false,
+  },
+  {
+    logger: console,
+  },
+);
+```
+
 ## Validation coverage
 
 `@wp-typia/block-types` now validates itself with a mixed strategy that matches

package/dist/blocks/bindings-codegen.d.ts

@@ -0,0 +1,13 @@
+import { type DefinedBindingSource } from "./bindings-core.js";
+export interface CreatePhpBindingSourceRegistrationSourceOptions {
+    readonly functionName?: string;
+    readonly hook?: string;
+    readonly includeOpeningTag?: boolean;
+    readonly textDomain?: string;
+}
+export interface CreateEditorBindingSourceRegistrationSourceOptions {
+    readonly functionName?: string;
+    readonly importSource?: string;
+}
+export declare function createPhpBindingSourceRegistrationSource(sources: DefinedBindingSource | readonly DefinedBindingSource[], options?: CreatePhpBindingSourceRegistrationSourceOptions): string;
+export declare function createEditorBindingSourceRegistrationSource(sources: DefinedBindingSource | readonly DefinedBindingSource[], options?: CreateEditorBindingSourceRegistrationSourceOptions): string;

package/dist/blocks/bindings-codegen.js

@@ -0,0 +1,210 @@
+import { createBindingSourceRegistrationPlan, } from "./bindings-core.js";
+import { normalizeStaticRegistrationValue } from "./shared/static-registration.js";
+function getBindingEvaluation(metadata, feature) {
+    return metadata.manifest.evaluations.find((evaluation) => evaluation.area === "blockBindings" && evaluation.feature === feature);
+}
+function shouldGenerateFeature(metadata, feature) {
+    const evaluation = getBindingEvaluation(metadata, feature);
+    return evaluation?.action === "generate";
+}
+function asSourceList(sources) {
+    if (Array.isArray(sources)) {
+        return sources;
+    }
+    return [sources];
+}
+function escapePhpSingleQuotedString(value) {
+    return value.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'");
+}
+function phpString(value) {
+    return `'${escapePhpSingleQuotedString(value)}'`;
+}
+function phpStringArray(values) {
+    return values.length === 0
+        ? "array()"
+        : `array( ${values.map((value) => phpString(value)).join(", ")} )`;
+}
+const PHP_IDENTIFIER_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+function sanitizePhpIdentifier(value) {
+    if (PHP_IDENTIFIER_PATTERN.test(value)) {
+        return value;
+    }
+    const sanitized = value.replace(/[^A-Za-z0-9_]/gu, "_").replace(/_+/gu, "_");
+    return /^[A-Za-z_]/u.test(sanitized) ? sanitized : `wp_typia_${sanitized}`;
+}
+function createPhpIdentifierHash(value) {
+    let hash = 0x811c9dc5;
+    for (const character of value) {
+        hash ^= character.codePointAt(0) ?? 0;
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash.toString(36);
+}
+function createPhpSourceProperties(source, options) {
+    const properties = [];
+    if (source.label) {
+        const label = options.textDomain
+            ? `__( ${phpString(source.label)}, ${phpString(options.textDomain)} )`
+            : phpString(source.label);
+        properties.push(`'label' => ${label}`);
+    }
+    if (source.usesContext && source.usesContext.length > 0) {
+        properties.push(`'uses_context' => ${phpStringArray(source.usesContext)}`);
+    }
+    if (source.getValueCallback) {
+        properties.push(`'get_value_callback' => ${phpString(source.getValueCallback)}`);
+    }
+    return properties;
+}
+function createPhpBindableAttributeFilterSource(entries, functionName) {
+    const lines = [];
+    const targets = entries.flatMap((entry) => (entry.source.bindableAttributes ?? []).map((target, index) => ({
+        index,
+        metadata: entry.metadata,
+        sourceName: entry.source.name,
+        target,
+    })));
+    if (targets.length === 0) {
+        return lines;
+    }
+    lines.push("");
+    lines.push("if ( function_exists( 'get_block_bindings_supported_attributes' ) ) {");
+    for (const [targetIndex, target] of targets.entries()) {
+        if (!shouldGenerateFeature(target.metadata, "supportedAttributesFilter")) {
+            lines.push(`\t// block_bindings_supported_attributes requires WordPress 6.9+ for ${target.target.blockName}.`);
+            continue;
+        }
+        const callbackSeed = [
+            functionName,
+            target.sourceName,
+            target.target.blockName,
+            String(target.index),
+            String(targetIndex),
+        ].join("\0");
+        const callbackName = sanitizePhpIdentifier(`${functionName}_${target.sourceName}_${target.target.blockName}_${target.index}_${targetIndex}_${createPhpIdentifierHash(callbackSeed)}_supported_attributes`);
+        lines.push(`\tadd_filter( ${phpString(`block_bindings_supported_attributes_${target.target.blockName}`)}, ${phpString(callbackName)} );`);
+        lines.push(`\tfunction ${callbackName}( $supported_attributes ) {`);
+        lines.push(`\t\treturn array_values( array_unique( array_merge( $supported_attributes, ${phpStringArray(target.target.attributes)} ) ) );`);
+        lines.push("\t}");
+    }
+    lines.push("}");
+    return lines;
+}
+export function createPhpBindingSourceRegistrationSource(sources, options = {}) {
+    const functionName = sanitizePhpIdentifier(options.functionName ?? "wp_typia_register_block_binding_sources");
+    const hook = options.hook ?? "init";
+    const entries = createBindingSourceRegistrationPlan(asSourceList(sources));
+    const lines = [];
+    if (options.includeOpeningTag ?? false) {
+        lines.push("<?php");
+        lines.push("");
+    }
+    lines.push(`function ${functionName}() {`);
+    lines.push("\tif ( ! function_exists( 'register_block_bindings_source' ) ) {");
+    lines.push("\t\treturn;");
+    lines.push("\t}");
+    lines.push("");
+    for (const entry of entries) {
+        if (!shouldGenerateFeature(entry.metadata, "serverRegistration")) {
+            lines.push(`\t// register_block_bindings_source() requires WordPress 6.5+ for ${entry.source.name}.`);
+            continue;
+        }
+        const properties = createPhpSourceProperties(entry.source, options);
+        lines.push(`\tregister_block_bindings_source( ${phpString(entry.source.name)}, array(`);
+        for (const property of properties) {
+            lines.push(`\t\t${property},`);
+        }
+        lines.push("\t) );");
+    }
+    lines.push("}");
+    lines.push(`add_action( ${phpString(hook)}, ${phpString(functionName)} );`);
+    lines.push(...createPhpBindableAttributeFilterSource(entries, functionName));
+    lines.push("");
+    return lines.join("\n");
+}
+function createEditorRegistrationEntries(entries) {
+    const fields = {};
+    const skipped = [];
+    const skippedFields = [];
+    const sources = [];
+    for (const entry of entries) {
+        const editorEvaluation = getBindingEvaluation(entry.metadata, "editorRegistration");
+        if (editorEvaluation === undefined) {
+            continue;
+        }
+        if (editorEvaluation.action !== "generate") {
+            skipped.push(entry.source.name);
+            continue;
+        }
+        sources.push(normalizeStaticRegistrationValue({
+            label: entry.source.label,
+            name: entry.source.name,
+            usesContext: entry.source.usesContext,
+        }, `sources.${entry.source.name}`, { description: "binding source" }));
+        if ((entry.source.fields?.length ?? 0) === 0) {
+            continue;
+        }
+        if (!shouldGenerateFeature(entry.metadata, "editorFieldsList")) {
+            skippedFields.push(entry.source.name);
+            continue;
+        }
+        fields[entry.source.name] = normalizeStaticRegistrationValue(entry.source.fields, `fields.${entry.source.name}`, { description: "binding source" });
+    }
+    return {
+        fields,
+        skipped,
+        skippedFields,
+        sources,
+    };
+}
+export function createEditorBindingSourceRegistrationSource(sources, options = {}) {
+    const importSource = options.importSource ?? "@wordpress/blocks";
+    const functionName = options.functionName ?? "registerWpTypiaBindingSources";
+    const entries = createBindingSourceRegistrationPlan(asSourceList(sources));
+    const registration = createEditorRegistrationEntries(entries);
+    if (registration.sources.length === 0) {
+        return [
+            "// No editor block binding sources were generated.",
+            ...(registration.skipped.length > 0
+                ? [
+                    `// Skipped editor registration for ${registration.skipped.join(", ")}; registerBlockBindingsSource() requires WordPress 6.7+.`,
+                ]
+                : []),
+            "",
+        ].join("\n");
+    }
+    const serializedSources = JSON.stringify(registration.sources, null, 2);
+    const serializedFields = JSON.stringify(registration.fields, null, 2);
+    const hasGeneratedFields = Object.keys(registration.fields).length > 0;
+    const lines = [
+        `import { registerBlockBindingsSource } from ${JSON.stringify(importSource)};`,
+        "",
+        `const sources = ${serializedSources};`,
+        ...(hasGeneratedFields ? [`const fieldsBySource = ${serializedFields};`] : []),
+        "",
+        `export function ${functionName}() {`,
+        "  if (typeof registerBlockBindingsSource !== \"function\") {",
+        "    return;",
+        "  }",
+        "  for (const source of sources) {",
+        ...(hasGeneratedFields
+            ? [
+                "    const fields = fieldsBySource[source.name];",
+                "    registerBlockBindingsSource({",
+                "      ...source,",
+                "      ...(fields ? { getFieldsList: () => fields } : {}),",
+                "    });",
+            ]
+            : ["    registerBlockBindingsSource(source);"]),
+        "  }",
+        "}",
+    ];
+    if (registration.skipped.length > 0) {
+        lines.push("", `// Skipped editor registration for ${registration.skipped.join(", ")}; registerBlockBindingsSource() requires WordPress 6.7+.`);
+    }
+    if (registration.skippedFields.length > 0) {
+        lines.push("", `// Skipped getFieldsList() for ${registration.skippedFields.join(", ")}; getFieldsList() requires WordPress 6.9+.`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/blocks/bindings-core.d.ts

@@ -0,0 +1,123 @@
+import type { BlockAttributes } from "./registration.js";
+import { type WordPressBlockApiCompatibilityDiagnostic, type WordPressBlockApiCompatibilityFeature, type WordPressBlockApiCompatibilityManifest, type WordPressCompatibilitySettings, type WordPressVersion } from "./compatibility.js";
+import { type DiagnosticLogger } from "./shared/diagnostics.js";
+export type BindingSourceName = `${string}/${string}`;
+export type BindingSourceArgs = Readonly<Record<string, unknown>>;
+export type BindingFieldType = "array" | "boolean" | "integer" | "number" | "object" | "string";
+export interface BindingSourceField<TArgs extends BindingSourceArgs = BindingSourceArgs> {
+    readonly args?: TArgs;
+    readonly label: string;
+    readonly name: string;
+    readonly type?: BindingFieldType;
+}
+export type BlockBindingAttributeName<TAttributes extends BlockAttributes = BlockAttributes> = Extract<Exclude<keyof TAttributes, "metadata">, string>;
+export interface BindingSourceBindableAttributes<TAttributes extends BlockAttributes = BlockAttributes, TBlockName extends string = string, TAttributesList extends readonly BlockBindingAttributeName<TAttributes>[] = readonly BlockBindingAttributeName<TAttributes>[]> {
+    readonly attributes: TAttributesList;
+    readonly blockName: TBlockName;
+}
+export interface BindingSourceDefinition<TName extends string = string, TArgs extends BindingSourceArgs = BindingSourceArgs, TFields extends readonly BindingSourceField[] = readonly BindingSourceField[]> {
+    readonly args?: TArgs;
+    readonly bindableAttributes?: readonly BindingSourceBindableAttributes[];
+    readonly fields?: TFields;
+    readonly getValueCallback?: string;
+    readonly label?: string;
+    readonly name: TName;
+    readonly usesContext?: readonly string[];
+}
+export interface BindingSourceVersionGates {
+    readonly editor?: WordPressVersion;
+    readonly fieldsList?: WordPressVersion;
+    readonly server?: WordPressVersion;
+    readonly supportedAttributesFilter?: WordPressVersion;
+}
+export interface DefineBindingSourceInlineOptions {
+    readonly allowUnknownFutureKeys?: boolean;
+    readonly editor?: boolean;
+    readonly fieldsList?: boolean;
+    readonly logger?: DiagnosticLogger<BindingSourceDiagnostic>;
+    readonly minVersion?: WordPressVersion;
+    readonly minWordPress?: WordPressVersion | BindingSourceVersionGates;
+    readonly minWordPressEditor?: WordPressVersion;
+    readonly minWordPressFieldsList?: WordPressVersion;
+    readonly minWordPressServer?: WordPressVersion;
+    readonly minWordPressSupportedAttributesFilter?: WordPressVersion;
+    readonly onDiagnostic?: (diagnostic: BindingSourceDiagnostic) => void;
+    readonly server?: boolean;
+    readonly strict?: boolean;
+    readonly supportedAttributesFilter?: boolean;
+}
+export interface DefineBindingSourceOptions extends WordPressCompatibilitySettings {
+    readonly editor?: boolean;
+    readonly fieldsList?: boolean;
+    readonly logger?: DiagnosticLogger<BindingSourceDiagnostic>;
+    readonly minWordPress?: WordPressVersion | BindingSourceVersionGates;
+    readonly minWordPressEditor?: WordPressVersion;
+    readonly minWordPressFieldsList?: WordPressVersion;
+    readonly minWordPressServer?: WordPressVersion;
+    readonly minWordPressSupportedAttributesFilter?: WordPressVersion;
+    readonly onDiagnostic?: (diagnostic: BindingSourceDiagnostic) => void;
+    readonly server?: boolean;
+    readonly supportedAttributesFilter?: boolean;
+}
+export type StripDefineBindingSourceOptions<TSource> = Omit<TSource, keyof DefineBindingSourceInlineOptions>;
+export declare const DEFINED_BLOCK_BINDING_SOURCE_METADATA: unique symbol;
+export type DefinedBlockBindingSourceMetadataKey = typeof DEFINED_BLOCK_BINDING_SOURCE_METADATA;
+export interface DefinedBlockBindingSourceMetadata {
+    readonly diagnostics: readonly BindingSourceDiagnostic[];
+    readonly features: readonly WordPressBlockApiCompatibilityFeature[];
+    readonly manifest: WordPressBlockApiCompatibilityManifest;
+}
+export type DefinedBindingSource<TName extends string = string, TArgs extends BindingSourceArgs = BindingSourceArgs, TFields extends readonly BindingSourceField[] = readonly BindingSourceField[], TSource extends BindingSourceDefinition = BindingSourceDefinition> = Readonly<StripDefineBindingSourceOptions<TSource>> & {
+    readonly [DEFINED_BLOCK_BINDING_SOURCE_METADATA]?: DefinedBlockBindingSourceMetadata | undefined;
+    readonly __wpTypiaBindingSourceArgs?: TArgs;
+    readonly __wpTypiaBindingSourceFields?: TFields;
+    readonly name: TName;
+};
+export interface BlockBinding<TSourceName extends string = string, TArgs extends BindingSourceArgs = BindingSourceArgs> {
+    readonly args?: TArgs;
+    readonly source: TSourceName;
+}
+type BindingSourceInferredArgs<TSource> = TSource extends {
+    readonly __wpTypiaBindingSourceArgs?: infer TArgs extends BindingSourceArgs;
+} ? TArgs : BindingSourceArgs;
+export type Binding<TSource extends DefinedBindingSource | string, TArgs extends BindingSourceArgs = BindingSourceInferredArgs<TSource>> = TSource extends DefinedBindingSource<infer TName, infer TSourceArgs> ? TArgs extends TSourceArgs ? BlockBinding<TName, TArgs> : never : TSource extends string ? BlockBinding<TSource, TArgs> : never;
+export type BlockBindingMap<TAttributes extends BlockAttributes = BlockAttributes> = Readonly<Partial<Record<BlockBindingAttributeName<TAttributes>, BlockBinding>>>;
+export interface BlockMetadataBindings<TBindings extends Readonly<Record<string, BlockBinding | undefined>> = Readonly<Record<string, BlockBinding>>> {
+    readonly bindings?: TBindings;
+}
+export type TypedBlockMetadataBindings<TAttributes extends BlockAttributes, TBindings extends BlockBindingMap<TAttributes> = BlockBindingMap<TAttributes>> = BlockMetadataBindings<TBindings>;
+export type BindingSourceDiagnosticCode = "duplicate-bindable-attribute" | "duplicate-field-name" | "fields-list-requires-editor" | "invalid-bindable-attribute" | "invalid-block-name" | "invalid-field-name" | "invalid-source-name" | "missing-php-callback";
+export interface BindingSourceAuthoringDiagnostic {
+    readonly attribute?: string | undefined;
+    readonly blockName?: string | undefined;
+    readonly code: BindingSourceDiagnosticCode;
+    readonly fieldName?: string | undefined;
+    readonly message: string;
+    readonly severity: "error" | "warning";
+    readonly sourceName: string;
+}
+export type BindingSourceDiagnostic = BindingSourceAuthoringDiagnostic | WordPressBlockApiCompatibilityDiagnostic;
+export interface BindingSourceRegistrationEntry {
+    readonly metadata: DefinedBlockBindingSourceMetadata;
+    readonly source: DefinedBindingSource;
+}
+export declare function collectBindingSourceCompatibilityFeatures(settings?: {
+    readonly editor?: boolean;
+    readonly fieldsList?: boolean;
+    readonly metadata?: boolean;
+    readonly server?: boolean;
+    readonly supportedAttributesFilter?: boolean;
+}): readonly WordPressBlockApiCompatibilityFeature[];
+export declare function createBindingSourceCompatibilityManifest(settings?: DefineBindingSourceOptions): WordPressBlockApiCompatibilityManifest;
+export declare function getDefinedBindingSourceMetadata(source: unknown): DefinedBlockBindingSourceMetadata | undefined;
+export declare function getDefinedBindingSourceCompatibilityManifest(source: unknown): WordPressBlockApiCompatibilityManifest | undefined;
+export declare function defineBindingSource<const TSource extends BindingSourceDefinition & DefineBindingSourceInlineOptions>(source: TSource, options?: DefineBindingSourceOptions): DefinedBindingSource<Extract<TSource["name"], string>, TSource extends {
+    readonly args: infer TArgs extends BindingSourceArgs;
+} ? TArgs : BindingSourceArgs, TSource extends {
+    readonly fields: infer TFields extends readonly BindingSourceField[];
+} ? TFields : readonly BindingSourceField[], TSource>;
+export declare function defineBindableAttributes<TAttributes extends BlockAttributes = BlockAttributes, const TBlockName extends string = string, const TAttributesList extends readonly BlockBindingAttributeName<TAttributes>[] = readonly BlockBindingAttributeName<TAttributes>[]>(blockName: TBlockName, attributes: TAttributesList): BindingSourceBindableAttributes<TAttributes, TBlockName, TAttributesList>;
+export declare function defineBlockMetadataBindings<const TBindings extends Readonly<Record<string, BlockBinding | undefined>>>(bindings: TBindings): BlockMetadataBindings<TBindings>;
+export declare function defineTypedBlockMetadataBindings<TAttributes extends BlockAttributes, const TBindings extends BlockBindingMap<TAttributes> = BlockBindingMap<TAttributes>>(bindings: TBindings): TypedBlockMetadataBindings<TAttributes, TBindings>;
+export declare function createBindingSourceRegistrationPlan(sources: readonly DefinedBindingSource[]): readonly BindingSourceRegistrationEntry[];
+export {};