Block Library

Capell Block Library

Block Library provides shared block primitives, foundation block views, screenshots, and Filament Builder block definitions that richer content-editing packages can register and render without reaching into each other's internals.

It owns the reusable public Blade blocks and the Builder block catalog, but it still does not own migrations, standalone admin resources, routes, or authoring markup.

The directory remains packages/block-library for workspace history, but the package identity is capell-app/block-library and the namespace is Capell\BlockLibrary\. Keep external references on the Composer name, not the folder name.

Start with Overview for install impact, surfaces, and screenshot coverage. Screenshot targets for consuming-package diagnostics live in docs/screenshots.json.

Why It Helps Your Capell Workflow

• Gives content packages a shared typed block language and default renderable block catalog without coupling to each other.
• Helps developers add reusable block definitions, variants, and renderer references behind one registry pattern.
• Keeps public block rendering safe by separating trusted definitions from editor state, requests, and database-driven view names.

Best Used With

• Layout Builder
• Content Sections
• Foundation Theme

Docs

• docs index
• overview.md
• screenshots.json

Current Surface

Registering Blocks

Packages register blocks by tagging a BlockDefinitionProvider implementation with BlockDefinitionProvider::TAG.

use Capell\BlockLibrary\Contracts\BlockDefinitionProvider;
use Capell\BlockLibrary\Data\BlockDefinitionData;

final class MarketingBlockProvider implements BlockDefinitionProvider
{
    public function definitions(): iterable
    {
        yield new BlockDefinitionData(
            key: 'marketing.hero',
            label: 'Marketing hero',
            description: 'A campaign-ready hero block.',
            category: 'marketing',
            view: 'vendor-package::blocks.marketing-hero',
            defaults: ['alignment' => 'center'],
        );
    }
}

Block views must render ordinary public HTML. Authoring metadata, selectors, model IDs, signed URLs, and editor scripts belong behind the authenticated frontend authoring beacon, not in block definitions or public output.

Block Definitions

BlockDefinitionData remains backwards compatible with the original key, label, description, category, view, and defaults shape. New packages can also provide:

• per-block variants through BlockVariantData and BlockVariantKey slug value objects;
• structured setting definitions with translated label/help keys, defaults, grouping, responsive fallbacks, and accessibility rules;
• content and accessibility contracts for required fields, item limits, CTA rules, image ratios, alt/decorative-image intent, semantic rules, and keyboard expectations;
• context-separated PublicBlockViewReference and AdminPreviewBlockViewReference;
• class-string fixture/demo providers, screenshots, compatibility metadata, and source package metadata.

Public views are trusted PHP definitions only. Do not read view names from editor state, database meta, fixtures, or request data.

Registry Cache Safety

Registry manifests should contain structural metadata only. Localized labels/help text should be translation keys or resolved for the current admin locale at render time.

Compiled manifests must be written atomically and validated against currently installed packages, provider classes, fixture/demo provider classes, and trusted view contexts before use. If compilation fails and no valid manifest exists, callers should fall back to the safe built-in fallback definition and surface an admin/system health warning.

Testing

Run package tests from the repository root:

vendor/bin/pest packages/block-library/tests --configuration=phpunit.xml

Block Library

Status: Available, shared foundation · Kind: package · Tier: free · Bundle: foundation · Contexts: admin, frontend, shared · Product group: Capell Foundation

Block Library provides typed block definitions, reusable foundation block views, screenshots, renderer contracts, fixtures, demo-content contracts, and Filament Builder block discovery for packages that contribute reusable content blocks.

What This Package Adds

• Block definition data objects and manifest metadata.
• Registry actions for registering, listing, and resolving block definitions.
• Contracts for block definition providers, renderers, fixtures, demo content, and Filament builder blocks.
• Builder block discovery for classes implementing FilamentBuilderBlock.
• Public Blade views and screenshots for the default block catalog.
• A fallback block Blade view for unrenderable or unknown block output.

Install Flow

• Composer package: capell-app/block-library
• Repository directory: packages/block-library
• Hard dependencies: capell-app/admin, capell-app/core
• Optional dependencies: capell-app/content-sections, capell-app/foundation-theme
• Run capell:extension-install capell-app/block-library after Composer install when validating package-installed guards.

Admin Surfaces

This package adds no standalone Filament navigation item, resource, page, widget, relation manager, or settings screen. Admin visibility appears through consuming packages that place the registered Filament Builder blocks into a Builder field.

Frontend Surfaces

This package adds no standalone public route. Frontend visibility appears through consuming packages that render registered block views and through the fallback block view when a block renderer cannot resolve a normal output view.

Screenshot Plan

• Admin and frontend screenshots exist for every default catalog block in docs/screenshots/.
• capell.json promotes the committed Capell runner captures for the registry list, editor form, asset settings, hero block, features block, and pricing block.
• A Filament Builder block picker capture can still be added from a consuming admin Builder field as a future optional gallery item.
• Fallback block rendering state should remain a controlled fixture capture when that fixture is added.

Known Risks

• The package owns block screenshots but not a standalone preview route. Final captures still need a consuming harness or admin Builder field.

Feature Suggestions

• Add a lightweight diagnostics command that lists registered block definitions, providers, renderers, and missing views.
• Add a developer-facing preview page gated to admins that renders each registered block fixture from the registry.
• Add schema validation output for block definitions so consuming packages can catch missing labels, categories, preview views, and accessibility metadata.