<?php
/**
 * Settings-bearing module contract.
 *
 * @package Rahkar\WP
 */

declare( strict_types = 1 );

namespace Rahkar\WP\Contracts;

defined( 'ABSPATH' ) || exit;

/**
 * A module that exposes configurable settings.
 *
 * The schema is the single source of truth: the same array drives form
 * rendering, sanitisation, and — later — the REST representation. Splitting
 * those apart is how settings screens drift out of sync with what the code
 * actually reads.
 */
interface HasSettings {

	/**
	 * Declarative field definitions.
	 *
	 * Each entry is keyed by setting name and describes one field:
	 *
	 *     'code_length' => [
	 *         'type'    => 'number',   // text|number|checkbox|select|textarea|password
	 *         'label'   => __( 'طول کد', 'rahkar-toolkit' ),
	 *         'help'    => __( '…', 'rahkar-toolkit' ),
	 *         'default' => 6,
	 *         'min'     => 4,
	 *         'max'     => 8,
	 *         'options' => [ 'a' => 'A' ],   // select only
	 *         'section' => 'general',
	 *     ]
	 *
	 * @return array<string, array<string, mixed>>
	 */
	public function settingsSchema(): array;

	/**
	 * Optional named sections, keyed by section id.
	 *
	 * @return array<string, string>
	 */
	public function settingsSections(): array;
}