Code Area(s) Impacted

• Block Variations
• Block Registration System
• Metadata Structure

Is your code refactoring request related to a problem?

The Tour Operator plugin's block variations lack consistent metadata structure, preventing proper WordPress.org integration and editor functionality. Many blocks are missing critical fields like descriptions, keywords, icons, textdomain consistency, supports fields, and example attributes. This creates poor user experience in the block editor and prevents blocks from appearing correctly on the WordPress.org plugin directory page.

Test practice is to create a separate sub-issue and PR for each block to ensure modularity, better review, and easier tracking.

Additionally, when working with block variations (not custom blocks), the block.json file does not function exactly as described in the official WordPress documentation. For example, the supports attribute in block.json does not affect block variations as expected. This limitation should be noted for future work and referenced in implementation notes.

Describe the Refactoring / Review Task

Scope: Refactor all block variation registrations in assets/js/blocks/ directory

Goals:

• Break down this parent issue into smaller sub-issues, each focused on refactoring metadata for a specific block or block variation.
• For block variations, keep in mind the limitations of block.json (e.g., supports attribute does not apply) and adjust code accordingly.
• Ensure each sub-issue and PR focuses on a single block or variation for clear code review and changelog updates.
• Standardize metadata structure using src/blocks/icons/block.json as template
• Add missing essential fields (description, keywords, icon, textdomain, supports, attributes, example)
• Ensure WordPress.org plugin directory integration
• Enable proper block previews in editor

Files to refactor:

• src/blocks/*/index.js - Block index files
• src/blocks/*/block.json - Block json declarations

Automated tools: Use GitHub Copilot for consistent metadata generation, ESLint for code quality, and wp-scripts linting tools

Focus areas: Block registration patterns, metadata consistency, WordPress coding standards compliance

Use Case

Primary beneficiaries: WordPress users, plugin developers, content creators

Benefits:

• Improved block discoverability in WordPress editor
• Enhanced user experience with proper block previews
• Better WordPress.org plugin directory integration
• Consistent development patterns for future blocks
• Compliance with WordPress block development standards
• Easier onboarding for new developers working with Tour Operator blocks
• Improves code review quality and traceability

Alternatives Considered

• Manual, ad-hoc metadata updates without standardization
• Continuing with inconsistent block registration patterns
• Relying only on pull request reviews to catch metadata issues

Additional Context

References:

• WordPress Block Editor Handbook: https://developer.wordpress.org/block-editor/
• Block Metadata Documentation: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
• Tour Operator Plugin Development Guidelines
• Using src/blocks/icons/block.json as structural template

Standards: Follow WordPress coding standards, use lsx-tour-operator textdomain consistently, implement proper supports fields for editor integration

Example Code Snippets

// Before: Block variation without proper metadata
wp.blocks.registerBlockVariation("core/group", {
  name: "lsx-tour-operator/price",
  title: "Price"
});

// After: Standardized metadata structure
wp.blocks.registerBlockVariation("core/group", {
  name: "lsx-tour-operator/price", 
  title: "Price",
  description: "Display tour pricing information with currency support.",
  keywords: ["price", "cost", "currency"],
  icon: "money-alt",
  category: "lsx-tour-operator",
  attributes: {
    metadata: { name: "Price" }
  },
  example: {
    attributes: { price: "$1,500" }
  },
  supports: {
    color: true,
    spacing: { margin: true, padding: true },
    typography: true
  }
});

Additional Context

• WordPress Block Editor Handbook
• Block Metadata Documentation
• PR #613
• Note on block.json for block variations: Certain attributes (e.g., supports) do not apply and must be handled differently than documented.
• Adhere to [Development Guidelines] and [Coding Standards] as outlined in the repository documentation.

Example of ignored block.json attribute for block variation

// Block variation: block.json supports attribute is ignored
// This does NOT enable color settings:
{
  "supports": {
    "color": true
  }
}

// Instead, use JS registration options for variations.

Refactoring / Review Checklist

• Create sub-issues for each block or block variation
• Note block.json limitations for variations
• Modular, clear PRs and changelog entries
• Merge to one changelog entry when all the sub issues are closed

References

• WordPress Block Editor Handbook
• Block Metadata Documentation
• [Development Guidelines] (see repo docs)
• [Coding Standards] (see repo docs)