Capstone 1: AI Alt-Text Generator

function ai_course_ch28_generate_alt_text( WP_REST_Request $request ) {
    $attachment_id = $request->get_param( 'attachment_id' );

    // Confirms this is a real attachment before doing anything else with it.
    if ( 'attachment' !== get_post_type( $attachment_id ) ) {
        return new WP_Error( 'ai_course_invalid_attachment', 'That attachment could not be found.' );
    }

    $file_path = get_attached_file( $attachment_id );
    $mime_type = get_post_mime_type( $attachment_id );

    // Only an actual image can be described this way.
    if ( ! $file_path || 0 !== strpos( (string) $mime_type, 'image/' ) ) {
        return new WP_Error( 'ai_course_not_an_image', 'AI alt text only works on image attachments.' );
    }

    // Forces the reply down to one clean field, nothing else to parse
    // out of a longer answer.
    $schema = array(
        'type'                 => 'object',
        'properties'           => array(
            'alt_text' => array(
                'type'        => 'string',
                'description' => 'Concise, descriptive alt text for the image, no more than 125 characters.',
            ),
        ),
        'required'             => array( 'alt_text' ),
        'additionalProperties' => false,
    );

    // Three earlier chapters in one prompt: a role (Ch. 5), the actual
    // image attached (Ch. 15), and a forced JSON shape (Ch. 8).
    $builder = wp_ai_client_prompt( 'Write accessible alt text for this image.' )
        ->using_system_instruction( 'You are an accessibility expert writing alt text for images on a WordPress website. Alt text should be concise, descriptive, and useful to someone using a screen reader. Never start with phrases like "image of" or "picture of".' )
        ->with_file( $file_path, $mime_type )
        ->as_json_response( $schema );

    // Checks this exact configuration, not a generic version of it.
    if ( ! $builder->is_supported_for_text_generation() ) {
        return new WP_Error( 'ai_course_not_supported', 'The configured AI provider does not support this right now.' );
    }

    $result = $builder->generate_text();

    if ( is_wp_error( $result ) ) {
        return $result;
    }

    $data = json_decode( $result, true );

    if ( ! isset( $data['alt_text'] ) ) {
        return new WP_Error( 'ai_course_bad_response', 'The AI response was not in the expected shape.' );
    }

    // WordPress's own alt-text field, not a separate custom one, this
    // is the same meta key the Media Library itself reads and writes.
    update_post_meta( $attachment_id, '_wp_attachment_image_alt', sanitize_text_field( $data['alt_text'] ) );

    return rest_ensure_response( array( 'alt_text' => $data['alt_text'] ) );
}

function ai_course_ch28_add_button( $form_fields, $post ) {
    if ( ! current_user_can( 'edit_post', $post->ID ) ) {
        return $form_fields;
    }

    $button_field = array(
        'ai_course_ch28_generate' => array(
            'label' => 'AI Alt Text',
            'input' => 'html',
            'html'  => '<button type="button" class="button ai-course-ch28-button" data-attachment-id="' . esc_attr( $post->ID ) . '">Generate with AI</button>',
        ),
    );

    // Inserts right after WordPress's own Alternative Text field
    // ('image_alt'), instead of at the end of the whole form.
    $position = array_search( 'image_alt', array_keys( $form_fields ), true );

    if ( false === $position ) {
        return $form_fields + $button_field;
    }

    return array_slice( $form_fields, 0, $position + 1, true )
        + $button_field
        + array_slice( $form_fields, $position + 1, null, true );
}
add_filter( 'attachment_fields_to_edit', 'ai_course_ch28_add_button', 10, 2 );

function ai_course_ch28_enqueue_assets( $hook ) {
    // An admin-only feature, so only load on the screens where the
    // button can actually appear, not every admin page.
    if ( ! in_array( $hook, array( 'post.php', 'post-new.php', 'upload.php' ), true ) ) {
        return;
    }

    wp_enqueue_script(
        'ai-course-ch28-alt-text',
        plugins_url( 'js/chapter-28-alt-text.js', __FILE__ ),
        array( 'wp-api-fetch' ),
        '1.0',
        true
    );

    wp_add_inline_script(
        'ai-course-ch28-alt-text',
        sprintf(
            'wp.apiFetch.use( wp.apiFetch.createNonceMiddleware( %s ) );',
            wp_json_encode( wp_create_nonce( 'wp_rest' ) )
        ),
        'before'
    );
}
// Admin-only feature, so this hooks the admin equivalent of
// wp_enqueue_scripts, used everywhere else in this book.
add_action( 'admin_enqueue_scripts', 'ai_course_ch28_enqueue_assets' );

function ai_course_ch28_init() {
    // The button lives inside the media modal, which doesn't exist in
    // the page until it's actually opened, so this listens on the
    // whole document instead of the button itself.
    document.addEventListener( 'click', ( event ) => {
        if ( ! event.target.classList.contains( 'ai-course-ch28-button' ) ) {
            return;
        }

        const button = event.target;
        const attachmentId = button.getAttribute( 'data-attachment-id' );

        // WordPress renders the Alternative Text field with a different
        // ID depending on which screen you're on: the classic media
        // modal namespaces it by attachment ID, the newer "two column"
        // Attachment Details screen uses one fixed ID since only one
        // attachment is ever shown on it at a time. Try each in turn.
        const altField =
            document.getElementById( 'attachment-details-two-column-alt-text' ) ||
            document.getElementById( 'attachments-' + attachmentId + '-image_alt' ) ||
            document.getElementById( 'attachments-' + attachmentId + '-alt' );

        if ( ! altField ) {
            return;
        }

        button.disabled = true;
        button.textContent = 'Generating...';

        wp.apiFetch( {
            path: '/ai-course/v1/alt-text',
            method: 'POST',
            data: { attachment_id: attachmentId }
        } )
            .then( ( data ) => {
                altField.value = data.alt_text;
                button.disabled = false;
                button.textContent = 'Generate with AI';
            } )
            .catch( ( error ) => {
                alert( error.message || 'Something went wrong, please try again.' );
                button.disabled = false;
                button.textContent = 'Generate with AI';
            } );
    } );
}

// If scripts load after the page has already finished loading (common
// with some caching/optimization plugins), DOMContentLoaded has already
// fired and never will again, so check readyState first.
if ( 'loading' === document.readyState ) {
    document.addEventListener( 'DOMContentLoaded', ai_course_ch28_init );
} else {
    ai_course_ch28_init();
}