# Component Registry

A developer tool for browsing and previewing the content blocks registered in the Block Registry.

## Features

- **Registry-driven discovery**: Lists blocks from `block_registry` (active blocks only), not the contents of a directory
- **Component Listing**: Grid view with component cards showing name, description, and metadata
- **Category Organization**: Categories, names and ordering come from the BlockRegistry taxonomy, so the page mirrors the admin block picker at `/admin/blocks`
- **Component Preview**: Isolated preview pages rendered through the real block pipeline
- **Usage Instructions**: Copy-pasteable include examples with variable documentation
- **Search & Filter**: Search by name/description and filter by category
- **Performance**: Cached discovery, invalidated whenever a block or category changes

## What appears here

A block appears at `/component` when all of the following hold:

1. It exists in `block_registry` (import definitions with `php artisan blocks:import --all`)
2. `is_active` is true — deactivating a block removes it from this page entirely
3. Its `template` is set and the file exists under `sites/default/templates/includes/`

Blocks failing 3 are skipped with a warning in the log rather than failing the whole
listing. Twig files that no block points at — headers, footers, popups, vendor
badges — are deliberately absent. To browse raw template files instead, use the
template dropdown in the block definition editor.

Blocks with no category are grouped under **Uncategorised**, sorted last. That
bucket is a prompt to assign a real category, not a supported state.

## Usage

### Browse Components
Visit `/component` to see the main component registry page.

On a fresh clone with no blocks imported the page is empty and says so — run
`php artisan blocks:import --all`.

### Preview Components
Click any component card to open an isolated preview at
`/component/preview/{block-slug}`. Previews render a block's authored
`example_data` through `EntityBlockService::renderExample()`, so the output
matches a published instance. Blocks without `example_data` fall back to the
template's inline `{% if show_dummy_data %}` fixture. Template paths are still
accepted by the preview route so older bookmarks keep working.

### API Access
- `GET /api/components` - List all components with pagination and filtering
- `GET /api/components/{slug}` - Get detailed component information

## Architecture

### Services
- `ComponentScannerService` - `discoverComponents()` queries the block registry and caches the result; `discoverTemplateFiles()` walks `includes/` for the admin template dropdown
- `ComponentRendererService` - Renders a component through the block pipeline, falling back to inline dummy data

### Models
- `Component` - A registered block resolved to its template file. Built via `Component::fromBlock()`; `fromFilePath()` serves the raw template-file listing only

### Controllers
- `ComponentRegistryController` - Main registry page
- `ComponentPreviewController` - Component preview pages
- `ComponentRegistryApiController` - API endpoints

### Frontend
- Vue.js `component-registry` component for the main listing page
- Isolated Twig layout for component previews

## Configuration

Component registry settings in `config/cache.php`:
```php
'component_registry' => [
    'ttl' => env('COMPONENT_CACHE_TTL', 300), // 5 minutes
    'prefix' => 'component_registry',
    'enabled' => env('COMPONENT_CACHE_ENABLED', true),
],
```

## Caching

Discovery is cached under `component_registry_components`. The TTL is a backstop
only — `BlockRegistry` and `BlockRegistryCategory` clear the cache on save and
delete, so an edit in admin, a `blocks:import`, or an activate toggle shows
immediately. The hooks live on the models rather than the services because the
admin's activate toggle and category editor write straight to the model.

To clear it manually: `app(ComponentScannerService::class)->clearCache()`.

## Error Handling

- Blocks whose template file is missing are skipped and logged, leaving the rest of the listing intact
- Broken templates surface as a real Twig error in the preview
- Technical error details displayed for debugging
- Comprehensive logging for troubleshooting

## Development

### Adding a block
Use `/mtc-block-registry <component-name>`, which authors
`modules/BlockRegistry/blocks/{slug}.json`, imports it, and verifies it appears
here under the expected category.

### Testing
- Feature tests in `tests/Feature/Component*Test.php`
- Unit tests in `tests/Unit/Component*ServiceTest.php`

### Extending
Key extension points:
- Block field types and rendering (`modules/BlockRegistry`)
- `example_data` for previews
- Preview layouts and styling
- API response formatting
