@10up/block-renderer-validator

@10up/block-renderer-validator

Validate JSON block trees against schemas, nesting rules, and theme tokens. This package ensures block trees are valid before rendering.

Installation

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

Overview

This package provides comprehensive validation for block trees:

1. Schema Validation - Validates block props against Zod schemas from block definitions
2. Nesting Validation - Checks parent/ancestor/allowedBlocks constraints
3. Token Validation - Verifies theme token references (colors, spacing, etc.)
4. Pattern Validation - Confirms pattern slugs exist in the registry

Usage

Full Tree Validation

The main entry point - validates a tree with all available validators:

import { validateTree } from '@10up/block-renderer-validator';

const tree = {
  root: 'para-1',
  elements: {
    'para-1': {
      key: 'para-1',
      type: 'core/paragraph',
      props: {
        content: 'Hello',
        style: { color: { background: 'var:preset|color|primary' } }
      }
    }
  }
};

const result = validateTree(tree, {
  catalog: blockCatalog,     // Block definitions for schema/nesting
  tokens: themeTokens,       // Theme tokens for color/spacing validation
  patterns: patternRegistry  // Pattern definitions
});

if (result.valid) {
  console.log('Tree is valid');
} else {
  console.log('Errors:', result.errors);
  // ['Unknown color token: primary', 'Invalid block type: core/unknown']
}

Validation Options

interface ValidateTreeOptions {
  /** Block catalog for schema and nesting validation */
  catalog?: BlockCatalog;
  /** Theme tokens for token validation */
  tokens?: ThemeTokens;
  /** Pattern registry for pattern validation */
  patterns?: PatternRegistry;
  /** Whether to validate schemas (default: true if catalog provided) */
  validateSchemas?: boolean;
  /** Whether to validate nesting rules (default: true if catalog provided) */
  validateNesting?: boolean;
  /** Whether to validate theme tokens (default: true if tokens provided) */
  validateTokens?: boolean;
  /** Whether to validate pattern references (default: true if patterns provided) */
  validatePatterns?: boolean;
}

Create Reusable Validator

import { createTreeValidator } from '@10up/block-renderer-validator';

const validator = createTreeValidator({
  catalog: blockCatalog,
  tokens: themeTokens,
  patterns: patternRegistry,
});

// Use the pre-configured validator
const result1 = validator(tree1);
const result2 = validator(tree2);

Schema Validation

Validate block props against their Zod schemas:

import { validateBlockProps, validateTreeSchemas } from '@10up/block-renderer-validator';

// Validate a single element's props
const result = validateBlockProps(element.props, blockDefinition.schema);
if (!result.valid) {
  console.log(result.errors);
  // ['content: Expected string, received number']
}

// Validate all elements in a tree
const treeResult = validateTreeSchemas(tree, catalog);

Create Block Validator

Create a validator for a specific block:

import { createBlockValidator } from '@10up/block-renderer-validator';

const validateParagraph = createBlockValidator(paragraphDefinition);
const result = validateParagraph({ content: 'Hello', dropCap: true });

Get Valid Attributes

Filter props to only include valid attributes:

import { getValidAttributes } from '@10up/block-renderer-validator';

const cleanProps = getValidAttributes(props, blockDefinition.schema);
// Returns only props that match the schema

Nesting Validation

Validate block nesting rules:

import { validateTreeNesting } from '@10up/block-renderer-validator';

const result = validateTreeNesting(tree, catalog);
if (!result.valid) {
  console.log(result.errors);
  // ['core/column must be inside core/columns']
}

Individual Nesting Validators

import {
  validateParent,
  validateAncestor,
  validateChildren,
  validateMultiple,
} from '@10up/block-renderer-validator';

// Check if element has valid parent
validateParent(element, parentElement, blockDefinition);

// Check if element has valid ancestor chain
validateAncestor(element, ancestorChain, blockDefinition);

// Check if children are valid for this block
validateChildren(element, childElements, blockDefinition);

// Check if multiple instances are allowed
validateMultiple(elements, blockDefinition);

Token Validation

Validate theme token references in block props:

import { validateTreeTokens, validateElementTokens } from '@10up/block-renderer-validator';

// Validate all tokens in a tree
const result = validateTreeTokens(tree, themeTokens);
if (!result.valid) {
  console.log(result.errors);
  // ['Unknown color token: invalid-color']
}

// Validate a single element's tokens
const elementResult = validateElementTokens(element, themeTokens);

Specific Token Validators

import {
  validateColorTokens,
  validateTypographyTokens,
  validateSpacingTokens,
} from '@10up/block-renderer-validator';

// Validate specific token types
validateColorTokens(props, themeTokens);
validateTypographyTokens(props, themeTokens);
validateSpacingTokens(props, themeTokens);

Pattern Validation

Validate pattern block references:

import {
  validatePatternReference,
  validateTreePatterns,
  isPatternReference,
  getPatternReferences,
} from '@10up/block-renderer-validator';

// Check if an element is a pattern reference
if (isPatternReference(element)) {
  const result = validatePatternReference(element, patternRegistry);
  if (!result.valid) {
    console.log(result.errors);
    // ['Unknown pattern: theme/nonexistent-pattern']
  }
}

// Validate all patterns in a tree
const treeResult = validateTreePatterns(tree, patternRegistry);

// Get all pattern references from a tree
const patternRefs = getPatternReferences(tree);
// ['theme/hero-section', 'theme/footer']

Template Validation

Validate BlockTemplate format (PHP-style nested arrays):

import {
  validateTemplate,
  validateTemplateStructure,
  validateTemplateBlockTypes,
  validateTemplateNesting,
} from '@10up/block-renderer-validator';

const template = [
  ['core/group', { layout: { type: 'constrained' } }, [
    ['core/heading', { content: 'Title', level: 2 }],
    ['core/paragraph', { content: 'Content' }],
  ]],
];

// Full template validation
const result = validateTemplate(template, {
  catalog: blockCatalog,
});

if (!result.valid) {
  console.log('Errors:', result.errors);
}

// Validate just structure (correct array format)
const structureResult = validateTemplateStructure(template);

// Validate block types exist
const typesResult = validateTemplateBlockTypes(template, catalog);

// Validate nesting rules
const nestingResult = validateTemplateNesting(template, catalog);

Template Validation Options

interface ValidateTemplateOptions {
  /** Block catalog for type and nesting validation */
  catalog?: BlockCatalog;
  /** Whether to validate that block types exist (default: true if catalog provided) */
  validateBlockTypes?: boolean;
  /** Whether to validate nesting rules (default: true if catalog provided) */
  validateNesting?: boolean;
}

Complete Exports

Main Functions

Function	Description
validateTree(tree, options)	Full tree validation with all validators
createTreeValidator(options)	Create reusable validator function

Schema Validation

Function	Description
validateBlockProps(props, schema)	Validate props against Zod schema
validateTreeSchemas(tree, catalog)	Validate all elements in tree
createBlockValidator(definition)	Create validator for specific block
getValidAttributes(props, schema)	Filter to valid attributes only

Nesting Validation

Function	Description
validateTreeNesting(tree, catalog)	Validate all nesting rules in tree
validateParent(element, parent, def)	Check valid parent constraint
validateAncestor(element, ancestors, def)	Check valid ancestor constraint
validateChildren(element, children, def)	Check valid children constraint
validateMultiple(elements, def)	Check multiple instance constraint

Token Validation

Function	Description
validateTreeTokens(tree, tokens)	Validate all tokens in tree
validateElementTokens(element, tokens)	Validate single element tokens
validateColorTokens(props, tokens)	Validate color token references
validateTypographyTokens(props, tokens)	Validate typography tokens
validateSpacingTokens(props, tokens)	Validate spacing tokens

Pattern Validation

Function	Description
validateTreePatterns(tree, patterns)	Validate all pattern refs in tree
validatePatternReference(element, patterns)	Validate single pattern ref
isPatternReference(element)	Check if element is a pattern
getPatternReferences(tree)	Get all pattern slugs from tree

Template Validation

Function	Description
validateTemplate(template, options)	Full template validation
validateTemplateStructure(template)	Validate template array structure
validateTemplateBlockTypes(template, catalog)	Validate block types exist
validateTemplateNesting(template, catalog)	Validate nesting rules

Types

Type	Description
ValidateTreeOptions	Options for validateTree
ValidateTemplateOptions	Options for validateTemplate
TemplateValidationResult	Result from template validation

License

MIT