@wp-typia/block-types 0.2.4 → 0.3.1

package/README.md

@@ -18,8 +18,11 @@ Shared WordPress block semantic types derived from Gutenberg source and unoffici
 - `@wp-typia/block-types/block-editor/style-attributes`
 - `@wp-typia/block-types/block-editor/typography`
 - `@wp-typia/block-types/blocks`
+- `@wp-typia/block-types/blocks/bindings`
+- `@wp-typia/block-types/blocks/compatibility`
 - `@wp-typia/block-types/blocks/registration`
 - `@wp-typia/block-types/blocks/supports`
+- `@wp-typia/block-types/blocks/variations`
 
 ## Current policy
 
@@ -43,6 +46,12 @@ Shared WordPress block semantic types derived from Gutenberg source and unoffici
   migration-facing `BlockInstance`
 - additive stable Core coverage for drop caps, spacing sizes, layout gaps,
   duotone, per-side border widths, and `js` / `locking`
+- a WordPress block API compatibility matrix for Supports, Variations, and
+  Bindings features that codegen and diagnostics can share
+- typed Block Variations authoring helpers with static JavaScript registration
+  source generation
+- typed Block Bindings source helpers with PHP/editor source generation and
+  `metadata.bindings` type helpers
 
 ## Registration facade
 
@@ -71,6 +80,80 @@ TypeScript installs surface the requirement explicitly.
 Compatibility should track that floor unless the generated project dependency
 matrix changes in the same release.
 
+## WordPress block API compatibility
+
+`@wp-typia/block-types/blocks/compatibility` exposes the shared compatibility
+foundation used by future block Supports, Variations, and Bindings helpers.
+The matrix records documented WordPress version floors, runtime surfaces, derived
+attributes, fallback hints, and source URLs for feature checks.
+
+```ts
+import { createWordPressBlockApiCompatibilityManifest } from '@wp-typia/block-types/blocks/compatibility';
+
+const manifest = createWordPressBlockApiCompatibilityManifest(
+  [
+    { area: 'blockSupports', feature: 'allowedBlocks' },
+    { area: 'blockBindings', feature: 'editorRegistration' },
+  ],
+  {
+    minVersion: '6.7',
+    strict: true,
+    allowUnknownFutureKeys: false,
+  },
+);
+```
+
+Strict mode marks known unsupported features as errors and recommends skipping
+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
@@ -88,35 +171,73 @@ breakage in scaffold or runtime packages.
 
 ## WordPress style support helpers
 
-The package now exposes two complementary surfaces:
+The package now exposes three complementary surfaces:
 
-- `@wp-typia/block-types/blocks/supports` for typed `block.json` `supports`
+- `@wp-typia/block-types/blocks/supports` for typed `block.json` `supports`,
+  the `defineSupports()` helper, and `SupportAttributes<typeof supports>`
 - `@wp-typia/block-types/block-editor/style-attributes` for the attribute and `style` shapes WordPress injects when those supports are enabled
+- `@wp-typia/block-types/blocks/compatibility` for version-aware diagnostics
+  when a support key requires a newer WordPress floor
 
 Example:
 
 ```ts
-import type { BlockStyleSupportAttributes } from '@wp-typia/block-types/block-editor/style-attributes';
-import type { BlockSupports } from '@wp-typia/block-types/blocks/supports';
+import {
+  defineSupports,
+  type SupportAttributes,
+} from '@wp-typia/block-types/blocks/supports';
 
-const supports: BlockSupports = {
-  color: { text: true, background: true, gradients: true, enableAlpha: true },
+const supports = defineSupports({
+  minWordPress: '6.6',
+  color: { text: true, background: true },
   spacing: {
     padding: true,
-    units: ['px', 'rem'],
-    spacingSizes: [{ name: 'Large', slug: 'large', size: '2rem' }],
+    margin: true,
+    blockGap: true,
+  },
+  typography: {
+    fontSize: true,
+    lineHeight: true,
+    letterSpacing: true,
+    textAlign: ['left', 'center'],
+  },
+  layout: {
+    default: {
+      type: 'constrained',
+    },
   },
-  typography: { fontSize: true, dropCap: true },
-  js: true,
-  locking: true,
+  anchor: true,
+  html: false,
+});
+
+type OwnAttributes = {
+  content: string;
+  density: 'compact' | 'balanced' | 'airy';
 };
 
-type MyBlockStyleAttrs = Pick<
-  BlockStyleSupportAttributes,
-  'backgroundColor' | 'fontSize' | 'style' | 'textColor'
->;
+type BlockAttributes = OwnAttributes & SupportAttributes<typeof supports>;
 ```
 
+`defineSupports()` returns a plain object that can be written directly to
+`block.json.supports`; inline helper controls such as `minWordPress`, `strict`,
+and `allowUnknownFutureKeys` are stripped from the returned metadata. The helper
+stores its compatibility manifest on a non-enumerable symbol so generated JSON
+stays clean while tests and codegen can still inspect diagnostics through
+`getDefinedSupportsCompatibilityManifest()`.
+
+Strict mode is enabled by default. Known support keys that require a newer
+WordPress version throw, while `strict: false` reports warnings through
+`onDiagnostic` and keeps the metadata pass-through. Unknown future top-level
+support keys are rejected unless `allowUnknownFutureKeys` is enabled.
+
+`SupportAttributes<typeof supports>` is intentionally conservative where
+Gutenberg behavior is broad. Enabling color, spacing, typography, border,
+dimensions, background, filter duotone, position, or shadow includes the shared
+`style` attribute shape. Typography also exposes slug attributes such as
+`fontSize` and `fontFamily` when typography support is enabled; the compatibility
+matrix tracks version-gated typography keys like `textAlign` separately from
+longstanding keys such as `dropCap`.
+
 Stable Core coverage now also includes support/style helpers for layout
 `rowGap` / `columnGap`, color `duotone`, per-side border widths, and other
 recently stabilized support keys.
@@ -126,6 +247,179 @@ for blocks that compute style output on the server. This follows Gutenberg's
 current experimental surface and should not be treated as a long-term
 stability guarantee.
 
+## WordPress block variation helpers
+
+`@wp-typia/block-types/blocks/variations` provides a type-first layer over the
+native Block Variations API. `defineVariation()` returns a plain variation
+metadata object suitable for `registerBlockVariation(...)`; the target block name
+and compatibility manifest are stored on a non-enumerable symbol so generated
+registration code can still recover the block target.
+
+Static registration source generation serializes JSON-compatible variation
+metadata. Function-based `isActive` callbacks are accepted by the type helper,
+but `createStaticBlockVariationRegistrationSource()` rejects them; use a dynamic
+registration path aligned with the `blockVariations.phpVariationCallback`
+compatibility entry when callbacks must stay executable.
+
+```ts
+import {
+  createStaticBlockVariationRegistrationSource,
+  defineVariation,
+  defineVariations,
+} from '@wp-typia/block-types/blocks/variations';
+
+type HeadingVariationAttributes = {
+  className?: string;
+  level?: number;
+};
+
+const paragraphVariation = defineVariation('core/paragraph', {
+  name: 'example-balanced-paragraph',
+  title: 'Balanced Paragraph',
+  attributes: {
+    className: 'is-style-example-balanced',
+  },
+  scope: ['inserter', 'transform'],
+  isActive: ['className'],
+});
+
+const headingVariation = defineVariation<HeadingVariationAttributes>(
+  'core/heading',
+  {
+    name: 'example-balanced-heading',
+    title: 'Balanced Heading',
+    attributes: {
+      className: 'is-style-example-heading',
+      level: 2,
+    },
+    scope: ['inserter', 'transform'],
+    isActive: ['className', 'level'],
+  },
+);
+
+const variations = defineVariations([
+  paragraphVariation,
+  headingVariation,
+] as const);
+
+const registrationSource =
+  createStaticBlockVariationRegistrationSource(variations);
+```
+
+Custom block variations use the same helper. Pass the custom block name and a
+local attribute type when the variation should be checked against project-owned
+metadata:
+
+```ts
+type TestimonialAttributes = {
+  className?: string;
+  layout?: 'quote' | 'card';
+};
+
+export const featuredTestimonialVariation =
+  defineVariation<TestimonialAttributes>('acme/testimonial', {
+    name: 'acme-featured-testimonial',
+    title: 'Featured Testimonial',
+    attributes: {
+      className: 'is-style-acme-featured',
+      layout: 'card',
+    },
+    isActive: ['className', 'layout'],
+  });
+```
+
+`defineVariation()` warns when active-state detection is missing or points at an
+attribute not present in the variation metadata. Use `allowMissingIsActive: true`
+for intentionally passive/default-style variations. `defineVariations()` detects
+duplicate variation names and shared active discriminators for the same target
+block.
+
+Static code generation currently targets editor-side
+`registerBlockVariation(...)` calls. Function-based `isActive` callbacks are
+accepted by the type helper, but static source generation rejects them because
+they cannot be represented safely as JSON-backed registration metadata. PHP or
+dynamic variation registration remains scoped to a future helper built on the
+existing `blockVariations.phpVariationCallback` compatibility entry.
+
+## WordPress block binding helpers
+
+`@wp-typia/block-types/blocks/bindings` provides a type-first layer for the
+Block Bindings API. `defineBindingSource()` returns a plain source metadata
+object, while compatibility diagnostics and codegen metadata are stored on a
+non-enumerable symbol.
+
+The helper tracks the documented WordPress floors for server registration
+(`6.5`), editor registration (`6.7`), and editor field lists/custom bindable
+attribute filters (`6.9`). Strict mode throws for unsupported combinations;
+`strict: false` reports diagnostics and omits unsupported editor-only output.
+
+```ts
+import {
+  createEditorBindingSourceRegistrationSource,
+  createPhpBindingSourceRegistrationSource,
+  defineBindableAttributes,
+  defineBindingSource,
+  defineBlockMetadataBindings,
+  type Binding,
+} from '@wp-typia/block-types/blocks/bindings';
+
+type ProfileCardAttributes = {
+  imageUrl?: string;
+};
+
+const profileSource = defineBindingSource({
+  name: 'example/profile-data',
+  label: 'Profile Data',
+  getValueCallback: 'example_get_profile_binding_value',
+  usesContext: ['postId'],
+  minWordPress: {
+    server: '6.5',
+    editor: '6.7',
+    fieldsList: '6.9',
+    supportedAttributesFilter: '6.9',
+  },
+  args: {
+    field: 'image_url' as 'display_name' | 'image_url',
+  },
+  fields: [
+    {
+      name: 'display_name',
+      label: 'Display name',
+      args: { field: 'display_name' },
+      type: 'string',
+    },
+    {
+      name: 'image_url',
+      label: 'Image URL',
+      args: { field: 'image_url' },
+      type: 'string',
+    },
+  ],
+  bindableAttributes: [
+    defineBindableAttributes<ProfileCardAttributes>('example/profile-card', [
+      'imageUrl',
+    ] as const),
+  ],
+});
+
+const metadata = defineBlockMetadataBindings({
+  imageUrl: {
+    source: profileSource.name,
+    args: { field: 'image_url' },
+  } satisfies Binding<typeof profileSource, { field: 'image_url' }>,
+});
+
+const phpSource = createPhpBindingSourceRegistrationSource(profileSource);
+const editorSource = createEditorBindingSourceRegistrationSource(profileSource);
+```
+
+The generated PHP registers `register_block_bindings_source()` on `init` and,
+when custom bindable attributes are declared, adds the
+`block_bindings_supported_attributes_{$block_type}` filter behind a WordPress
+6.9-compatible guard. The generated editor source registers
+`registerBlockBindingsSource()` and emits `getFieldsList()` only when the
+source compatibility manifest marks field lists as supported.
+
 ## Typia pipeline notes
 
 - `CssColorValue` and `MinHeightValue` are richer DX aliases that currently rely on template literal types.

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");
+}