<?php
/**
 * Fonts service interface for PDFDraft.
 *
 * @package PDFDraft
 */

namespace PDFDraft\Contracts\Services;

if ( ! defined( 'ABSPATH' ) ) {
	exit; // Exit if accessed directly.
}

use WP_Error;

/**
 * Defines the contract for font service implementations.
 */
interface FontsServiceInterface {
	/**
	 * Get fonts with optional filtering.
	 *
	 * @param array       $args         Query arguments.
	 * @param string|null $fontDataPath Optional custom path to fonts JSON file.
	 * @return array|WP_Error Array of fonts or WP_Error on failure.
	 */
	public function getFonts( array $args = array(), ?string $fontDataPath = null );

	/**
	 * Get font by ID(s).
	 *
	 * @param string|array $ids          Font ID or array of IDs to retrieve.
	 * @param string|null  $fontDataPath Optional custom path to fonts JSON file.
	 * @return array|WP_Error Font data or WP_Error on failure.
	 */
	public function getFontById( $ids, ?string $fontDataPath = null );

	/**
	 * Get font categories.
	 *
	 * @param string|null $fontDataPath Optional custom path to fonts JSON file.
	 * @return array|WP_Error Array of font categories or WP_Error on failure.
	 */
	public function getFontCategories( ?string $fontDataPath = null );

	/**
	 * Create Google Fonts URL from font data.
	 *
	 * @param array $fontData Font data.
	 * @return string Google Fonts URL.
	 */
	public function createGoogleFontsUrl( array $fontData ): string;
}
