Engineering Highlights
From Recent Projects

<?php
// Auto-discovers all blocks in parent + child theme directories.
// Child blocks override parent blocks of the same name via array_unique.
function get_block_dirs(): array|false {
    $root       = get_template_directory() . '/blocks';
    $block_dirs = array_map(
        fn($dir) => basename($dir),
        array_filter(glob($root . '/*'), 'is_dir')
    );

    if (is_child_theme()) {
        $child_root = get_stylesheet_directory() . '/blocks';
        $child_dirs = array_map(
            fn($dir) => basename($dir),
            array_filter(glob($child_root . '/*'), 'is_dir')
        );
        // Child blocks override parent — duplicates removed in merge
        $block_dirs = array_unique(array_merge($block_dirs, $child_dirs));
    }

    return $block_dirs;
}

// Priority 3: register before default init hooks.
add_action('init', function () {
    $block_dirs = get_block_dirs();

    foreach ($block_dirs as $block_dir) {
        $block_json = locate_template('/blocks/' . $block_dir . '/block.json');
        if (!$block_json) continue;

        // Register editor-only script/style variants (-editor, -init)
        foreach (['-editor', '-init'] as $variant) {
            $path = '/blocks/' . $block_dir . '/dist/' . $block_dir . $variant . '.min.js';
            if ($script = locate_template($path)) {
                wp_register_script(
                    'theme-block-js-' . $block_dir . $variant,
                    get_theme_file_uri($path),
                    [],
                    filemtime($script)  // cache-bust by file modification time
                );
            }
        }

        // Per-block: auto-load functions.php if it exists
        locate_template('blocks/' . $block_dir . '/functions.php', true, true);

        // Per-block: register AJAX nonce if ajax.php exists
        if (locate_template('blocks/' . $block_dir . '/ajax.php', true, true)) {
            wp_localize_script(
                'theme-blocks-scripts',
                'theme_block_' . str_replace('-', '_', $block_dir) . '_ajax',
                [
                    'ajax_url' => admin_url('admin-ajax.php'),
                    'nonce'    => wp_create_nonce('theme-block-' . $block_dir . '-nonce'),
                ]
            );
        }

        register_block_type($block_json);
    }
}, 3);

<?php
// Route ACF JSON saves to the block's own acf-json/ subdirectory,
// co-locating field group configuration with the block files it belongs to.

add_filter('acf/json/save_paths', function ($paths, $post) {
    if (($post['location'][0][0]['param'] ?? false) === 'block') {
        $dir   = explode('/', $post['location'][0][0]['value'])[1] ?? '_default';
        $paths = [get_stylesheet_directory() . '/blocks/' . $dir . '/acf-json'];

        // Auto-create the directory if it doesn't exist yet
        if (!file_exists($paths[0])) {
            mkdir($paths[0], 0755, true);
        }
    }
    return $paths;
}, 10, 2);

// Name each JSON file after the block slug (e.g., hero.json, banner.json)
add_filter('acf/json/save_file_name', function ($filename, $post) {
    if (($post['location'][0][0]['param'] ?? false) === 'block') {
        $block_name = explode('/', $post['location'][0][0]['value'])[1] ?? '_default';
        return $block_name . '.json';
    }
    return $filename;
}, 10, 3);

// Load ACF JSON from the parent theme, child theme,
// AND each block's own acf-json/ directory.
add_filter('acf/settings/load_json', function ($paths) {
    if (is_child_theme()) {
        $paths[0] = get_template_directory()  . '/acf-json'; // parent
        $paths[1] = get_stylesheet_directory() . '/acf-json'; // child overrides
    }
    foreach (get_block_dirs() as $block_dir) {
        if ($block_path = locate_template('/blocks/' . $block_dir . '/acf-json')) {
            $paths[] = $block_path;
        }
    }
    return $paths;
});

<?php
// ACF Composer class-based block — fields() defines the ACF schema,
// item() processes the data, with() passes it to the Blade template.

public function fields(): array
{
    $fields = Builder::make('video_player');

    $fields
        ->addUrl('video_url', [
            'label'        => 'Video URL',
            'instructions' => 'YouTube, Vimeo, or Wistia links.',
            'required'     => true,
        ])
        ->addImage('poster_image', [
            'instructions'  => 'Upload a custom poster, or leave blank to auto-fetch from the video service.',
            'return_format' => 'id',
        ])
        ->addRadio('display_mode', [
            'choices'       => ['lightbox' => 'Lightbox Modal', 'inline' => 'Play In Place'],
            'default_value' => 'lightbox',
        ]);

    return $fields->build();
}

public function item(): array
{
    $poster   = get_field('poster_image');
    $video    = get_field('video_url');
    $mode     = get_field('display_mode') ?: 'lightbox';

    // No custom poster? Auto-fetch the thumbnail from the video service.
    $poster_image = $poster
        ? ['url' => wp_get_attachment_image_url($poster, 'large'),
           'alt' => get_post_meta($poster, '_wp_attachment_image_alt', true) ?: '']
        : $this->getVideoServicePoster($video);

    return compact('video', 'poster_image', 'mode');
}

// Detects YouTube, Vimeo, or Wistia URLs and fetches their thumbnails.
private function getVideoServicePoster(?string $url): array
{
    if (!$url) return ['url' => null, 'alt' => ''];

    // YouTube — construct thumbnail URL directly, no API call needed
    if (preg_match('/(?:youtube\.com\/watch\?v=|youtu\.be\/)([a-zA-Z0-9_-]+)/', $url, $m)) {
        return ['url' => "https://img.youtube.com/vi/{$m[1]}/maxresdefault.jpg",
                'alt' => 'YouTube video poster'];
    }

    // Vimeo — fetch via oEmbed JSON endpoint
    if (preg_match('/vimeo\.com\/\d+/', $url)) {
        $data = json_decode(wp_remote_retrieve_body(
            wp_remote_get("https://vimeo.com/api/oembed.json?url=" . urlencode($url))
        ), true);
        if (!empty($data['thumbnail_url'])) {
            return ['url' => $data['thumbnail_url'], 'alt' => $data['title'] ?? 'Vimeo video poster'];
        }
    }

    // Wistia — fetch via fast.wistia.com oEmbed endpoint
    if (preg_match('/wistia\.(?:com|net)/', $url)) {
        $data = json_decode(wp_remote_retrieve_body(
            wp_remote_get("https://fast.wistia.com/oembed?url=" . urlencode($url))
        ), true);
        if (!empty($data['thumbnail_url'])) {
            return ['url' => $data['thumbnail_url'], 'alt' => $data['title'] ?? 'Wistia video poster'];
        }
    }

    return ['url' => null, 'alt' => ''];
}

// Accessibility-first lightbox with focus trapping, DOM restoration, and cleanup.
export default class VideoPlayer {
    constructor() {
        this.modal     = document.getElementById('videoPlayerModal');
        this.container = document.getElementById('videoPlayerContainer');
        this.closeBtn  = document.getElementById('videoPlayerClose');
        this.overlay   = document.querySelector('.video-player-overlay');

        // Store bound handlers so they can be removed on destroy()
        this.boundHandlers = { escapeKey: null, closeBtn: null, overlay: null,
                               lightbox: [], inline: [] };
        this.lastFocusedElement = null;

        this.bindEvents();
    }

    openModal(trigger) {
        const videoUrl = trigger.querySelector('.video-data')
            ?.getAttribute('data-embed-code');
        if (!videoUrl) return;

        // Remember what was focused so we can restore it on close
        this.lastFocusedElement  = document.activeElement;

        // Track original DOM position so we can restore it after close
        this.originalParent      = this.modal.parentNode;
        this.originalNextSibling = this.modal.nextSibling;

        // Move to body end for reliable z-index stacking context
        document.body.appendChild(this.modal);

        this.container.innerHTML = this.generateEmbedCode(videoUrl);
        this.modal.classList.replace('hidden', 'block');
        document.body.classList.add('overflow-hidden');

        // Animate in on the next frame
        setTimeout(() => {
            this.overlay?.classList.add('opacity-100');
            this.container.classList.add('scale-100', 'opacity-100');
        }, 10);

        // Mark all other body children inert — traps focus + prevents interaction
        this.setBackgroundInert(true);

        // Shift keyboard focus to the close button for screen reader users
        setTimeout(() => this.closeBtn?.focus(), 100);
    }

    closeModal() {
        this.overlay?.classList.remove('opacity-100');
        this.container.classList.remove('scale-100', 'opacity-100');

        setTimeout(() => {
            this.modal.classList.replace('block', 'hidden');
            this.container.innerHTML = '';
            document.body.classList.remove('overflow-hidden');

            // Restore modal to its original position in the DOM
            this.originalNextSibling
                ? this.originalParent.insertBefore(this.modal, this.originalNextSibling)
                : this.originalParent.appendChild(this.modal);

            // Re-enable background content
            this.setBackgroundInert(false);

            // Return focus to the element that triggered the modal
            this.lastFocusedElement?.focus();
            this.lastFocusedElement = null;
        }, 300);
    }

    setBackgroundInert(isInert) {
        Array.from(document.body.children)
            .filter(child => child !== this.modal)
            .forEach(child => isInert
                ? child.setAttribute('inert', '')
                : child.removeAttribute('inert')
            );
    }

    // Full cleanup for SPA-style re-initialization
    destroy() {
        this.boundHandlers.lightbox.forEach(({ trigger, clickHandler, keyHandler }) => {
            trigger.removeEventListener('click', clickHandler);
            trigger.removeEventListener('keydown', keyHandler);
        });
        if (this.boundHandlers.escapeKey) {
            document.removeEventListener('keydown', this.boundHandlers.escapeKey);
        }
    }
}