@wp-typia/block-types 0.2.4 → 0.3.0

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,34 @@ 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.
+
 ## Validation coverage
 
 `@wp-typia/block-types` now validates itself with a mixed strategy that matches
@@ -88,35 +125,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 +201,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.d.ts

@@ -0,0 +1,132 @@
+import type { BlockAttributes } from "./registration.js";
+import { type WordPressBlockApiCompatibilityDiagnostic, type WordPressBlockApiCompatibilityFeature, type WordPressBlockApiCompatibilityManifest, type WordPressCompatibilitySettings, type WordPressVersion } from "./compatibility.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 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 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 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 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 declare function createPhpBindingSourceRegistrationSource(sources: DefinedBindingSource | readonly DefinedBindingSource[], options?: CreatePhpBindingSourceRegistrationSourceOptions): string;
+export declare function createEditorBindingSourceRegistrationSource(sources: DefinedBindingSource | readonly DefinedBindingSource[], options?: CreateEditorBindingSourceRegistrationSourceOptions): string;
+export {};