@10up/block-renderer-core

@10up/block-renderer-core

Shared TypeScript types and Zod schemas for the JSON Block Renderer ecosystem. This package provides the foundational types used across all other packages in the monorepo.

Installation

npm install @10up/block-renderer-core
# or
pnpm add @10up/block-renderer-core

Overview

This package exports three categories of types:

1. Block Tree Types - The JSON format for representing WordPress blocks
2. Block Definition Types - Metadata and schemas for block validation
3. Block JSON Types - TypeScript definitions for WordPress block.json files

Block Tree Format

The block tree uses a flat structure with key references instead of deep nesting. This design (inspired by Vercel's json-render) makes it easier for AI to generate valid structures.

BlockElement

A single block element in the tree:

interface BlockElement {
  /** Unique identifier for this element */
  key: string;
  /** Block name, e.g., "core/paragraph", "core/group" */
  type: string;
  /** Block attributes/props */
  props: Record<string, unknown>;
  /** Keys of child elements (for blocks with InnerBlocks) */
  children?: string[];
  /** Key of the parent element */
  parentKey?: string;
}

BlockTree

The complete block tree structure:

interface BlockTree {
  /** Key of the root element */
  root: string;
  /** Map of element keys to BlockElement objects */
  elements: Record<string, BlockElement>;
}

Example

import type { BlockTree, BlockElement } from '@10up/block-renderer-core';

const tree: BlockTree = {
  root: 'group-1',
  elements: {
    'group-1': {
      key: 'group-1',
      type: 'core/group',
      props: { layout: { type: 'constrained' } },
      children: ['heading-1', 'para-1']
    },
    'heading-1': {
      key: 'heading-1',
      type: 'core/heading',
      props: { content: 'Welcome', level: 2 },
      parentKey: 'group-1'
    },
    'para-1': {
      key: 'para-1',
      type: 'core/paragraph',
      props: { content: 'Hello world' },
      parentKey: 'group-1'
    }
  }
};

Block Template Format

An alternative PHP-style nested array format, useful for migration scripts and server-side rendering:

BlockTemplateEntry

A single entry in a block template:

type BlockTemplateEntry =
  | [string]                                           // Just block type
  | [string, Record<string, unknown>]                  // Block type + attributes
  | [string, Record<string, unknown>, BlockTemplateEntry[]]; // Full entry with children

BlockTemplate

An array of block template entries:

type BlockTemplate = BlockTemplateEntry[];

Example

import type { BlockTemplate, BlockTemplateEntry } from '@10up/block-renderer-core';

const template: BlockTemplate = [
  ['core/group', { layout: { type: 'constrained' } }, [
    ['core/heading', { content: 'Welcome', level: 2 }],
    ['core/paragraph', { content: 'Hello world' }],
  ]],
];

// This corresponds to the WordPress PHP format:
// array(
//   array( 'core/group', array( 'layout' => array( 'type' => 'constrained' ) ), array(
//     array( 'core/heading', array( 'content' => 'Welcome', 'level' => 2 ) ),
//     array( 'core/paragraph', array( 'content' => 'Hello world' ) ),
//   )),
// )

When to Use Each Format

Format	Best For
BlockTree (flat)	AI generation, complex validation, IDE tooling
BlockTemplate (nested)	Migration scripts, PHP-to-JS conversion, manual authoring

Block Definition Types

Used for validation and prompt generation:

BlockDefinition

interface BlockDefinition {
  /** Block name, e.g., "core/paragraph" */
  name: string;
  /** Human-readable title */
  title?: string;
  /** Block description */
  description?: string;
  /** Zod schema for validating block attributes */
  schema: z.ZodObject<z.ZodRawShape>;
  /** Valid parent blocks (direct parent) */
  parent?: string[];
  /** Valid ancestor blocks (anywhere in tree path) */
  ancestor?: string[];
  /** Valid child blocks, or true for any */
  allowedBlocks?: string[] | true;
  /** Whether block supports InnerBlocks (children) */
  hasInnerBlocks: boolean;
  /** Whether block is dynamic (server-rendered) */
  isDynamic: boolean;
  /** Block category */
  category?: string;
  /** Block keywords for search */
  keywords?: string[];
}

BlockCatalog

A map of block names to their definitions:

type BlockCatalog = Map<string, BlockDefinition>;

Validation Result Types

interface ValidationResult {
  valid: boolean;
  errors: string[];
  warnings?: string[];
}

interface TreeValidationResult extends ValidationResult {
  /** Per-element validation results keyed by element key */
  elementResults?: Record<string, ValidationResult>;
}

Block JSON Types

TypeScript definitions matching the WordPress block.json schema:

BlockJson

interface BlockJson {
  name: string;                                    // Required: Block name
  title: string;                                   // Required: Display title
  category?: string;                               // Block category
  description?: string;                            // Block description
  keywords?: string[];                             // Search keywords
  attributes?: Record<string, BlockAttributeDefinition>;
  supports?: BlockSupports;                        // Feature support flags
  parent?: string[];                               // Direct parent constraints
  ancestor?: string[];                             // Ancestor constraints
  allowedBlocks?: string[];                        // Allowed child blocks
  providesContext?: Record<string, string>;        // Context provided to children
  usesContext?: string[];                          // Context consumed from parents
  styles?: Array<{ name: string; label: string; isDefault?: boolean }>;
  variations?: Array<BlockVariation>;
  render?: string;                                 // Server-side render callback
  // ... and more
}

BlockAttributeDefinition

interface BlockAttributeDefinition {
  type?: BlockAttributeType | BlockAttributeType[];
  enum?: (string | number | boolean)[];
  default?: unknown;
  source?: 'attribute' | 'text' | 'html' | 'query' | 'meta' | 'raw';
  selector?: string;
  attribute?: string;
  items?: BlockAttributeDefinition;              // For array types
  properties?: Record<string, BlockAttributeDefinition>; // For object types
}

type BlockAttributeType =
  | 'string' | 'number' | 'integer' | 'boolean'
  | 'object' | 'array' | 'null' | 'rich-text';

BlockSupports

Comprehensive type for WordPress block supports:

interface BlockSupports {
  anchor?: boolean;
  align?: boolean | ('left' | 'center' | 'right' | 'wide' | 'full')[];
  className?: boolean;
  color?: boolean | {
    background?: boolean;
    gradients?: boolean;
    link?: boolean;
    text?: boolean;
  };
  typography?: boolean | {
    fontSize?: boolean;
    lineHeight?: boolean;
    fontFamily?: boolean;
    fontWeight?: boolean;
    // ... and more
  };
  spacing?: boolean | {
    margin?: boolean | ('top' | 'right' | 'bottom' | 'left')[];
    padding?: boolean | ('top' | 'right' | 'bottom' | 'left')[];
    blockGap?: boolean | ('horizontal' | 'vertical')[];
  };
  border?: boolean | { color?: boolean; radius?: boolean; style?: boolean; width?: boolean };
  layout?: boolean | { default?: { type?: 'constrained' | 'flex' | 'flow' | 'grid' } };
  // ... and more
}

Zod Schemas

Runtime validation schemas for block trees:

import { blockTreeSchema, blockElementSchema } from '@10up/block-renderer-core';

// Validate a complete tree
const result = blockTreeSchema.safeParse(input);
if (result.success) {
  const tree: BlockTree = result.data;
} else {
  console.error(result.error.issues);
}

// Validate a single element
const elementResult = blockElementSchema.safeParse(element);

Schema Definitions

// BlockElement schema
const blockElementSchema = z.object({
  key: z.string().min(1),
  type: z.string().min(1),
  props: z.record(z.unknown()),
  children: z.array(z.string()).optional(),
  parentKey: z.string().optional(),
});

// BlockTree schema
const blockTreeSchema = z.object({
  root: z.string().min(1),
  elements: z.record(blockElementSchema),
});

PHP Pattern Options

Options for transforming rendered markup into production-ready PHP patterns with internationalization:

interface PhpPatternOptions {
  /** Theme text domain for translation functions (required) */
  textDomain: string;
  /** Asset directory name for image path detection (default: 'assets') */
  assetDirectory?: string;
}

Example

import type { PhpPatternOptions } from '@10up/block-renderer-core';

const options: PhpPatternOptions = {
  textDomain: 'my-theme',
  assetDirectory: 'assets'
};

// When used with renderBlockTree, text content will be wrapped:
// "Hello World" → <?php echo esc_html__( 'Hello World', 'my-theme' ); ?>
// Image paths will use get_template_directory_uri()

Complete Exports

Types

Type	Description
BlockElement	Single block in the tree
BlockTree	Complete block tree structure
BlockElementSchema	Zod inferred type for BlockElement
BlockTreeSchema	Zod inferred type for BlockTree
BlockTemplate	PHP-style nested array format
BlockTemplateEntry	Single entry in a BlockTemplate
BlockTemplateEntrySchema	Zod inferred type for BlockTemplateEntry
BlockTemplateSchema	Zod inferred type for BlockTemplate
BlockDefinition	Block schema and metadata for validation
BlockCatalog	Map of block names to definitions
ValidationResult	Single element validation result
TreeValidationResult	Full tree validation result
BlockJson	WordPress block.json structure
BlockSupports	Block supports configuration
BlockAttributeDefinition	Block attribute definition
BlockAttributeType	Attribute type union
PhpPatternOptions	Options for PHP pattern transformation
PhpPatternOptionsSchema	Zod inferred type for PhpPatternOptions

Schemas

Schema	Description
blockElementSchema	Zod schema for validating BlockElement
blockTreeSchema	Zod schema for validating BlockTree
blockTemplateEntrySchema	Zod schema for validating BlockTemplateEntry
blockTemplateSchema	Zod schema for validating BlockTemplate
phpPatternOptionsSchema	Zod schema for validating PhpPatternOptions

License

MIT