<?php
/**
 * File Path: helpers/class-mbs-section-helper.php
 *
 * Canonical section schema helper. Provides the authoritative set of section
 * keys, tier metadata, and display labels for the section order feature.
 * CR-2 formal justification: see Section 0C of UX-EDIT-002 plan.
 *
 * @package MyBookShowroom
 * @since   1.5.0
 */
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

class MBS_Section_Helper { // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.NonPrefixedClassFound -- mbs_/MBS_ prefix is correct; scanner not configured with plugin prefix

	/**
	 * Canonical section keys -- the authoritative set of sections the plugin
	 * supports. CR-2 justification: this is schema configuration (which sections
	 * exist), not user data (what order they appear in). Analogous to a CPT slug.
	 * DB governs sort order; this method governs which keys exist.
	 *
	 * UX-NAV-001: updated to 16-key list. Removed deprecated keys,
	 * added book-details, trailer, more-in-collection, more-in-universe,
	 * more-by-author. look-inside and series-order are now regular
	 * draggable sections (tab-controlled status retired).
	 *
	 * @return string[]
	 */
	public static function get_canonical_keys(): array {
		return array(
			'about-the-book',
			'book-details',
			'endorsements',
			'amazon-reviews',
			'kindle-preview',
			'reviews',
			'awards-accolades',
			'look-inside',
			'related-books',
			'series-order',
			'more-in-collection',
			'more-in-universe',
			'more-by-author',
			'audio-sample',
			'trailer',
			'book-club-resources',
		);
	}

	/**
	 * Full section definitions with tier metadata and option-gate key.
	 *
	 * Tier values for section order UI:
	 *   'free' -- visible to all users; no license required.
	 *   'all'  -- visible to all users (CE-1: all activated tiers). Treated
	 *             identically to 'free' in the allowlist filter. Distinguished
	 *             as a documentation label only.
	 *   'pro'  -- requires active PRO license. Shown to all users with lock
	 *             icon styling (Design A / teaser pattern); stripped by save()
	 *             allowlist for FREE users.
	 *
	 * requires_option: wp_options key that gates this section. Empty string
	 *   means no option dependency. get_available_section_data() uses this
	 *   field to filter out sections whose option resolves to falsy.
	 *
	 * Callers filter on ['tier'] themselves. This method does not call
	 * mbs_is_pro() (SRP: the helper has no license-detection responsibility).
	 *
	 * @return array[] Each item: ['label' => string, 'tier' => 'free'|'all'|'pro', 'requires_option' => string]
	 */
	public static function get_canonical_section_data(): array {
		return array(
			'book-details'        => array( 'label' => __( 'Book Details',            'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'about-the-book'      => array( 'label' => __( 'About the Book',          'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'look-inside'         => array( 'label' => __( 'Look Inside',             'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'endorsements'        => array( 'label' => __( 'Endorsements / Blurbs',   'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'reviews'             => array( 'label' => __( 'Reader Reviews',          'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'series-order'        => array( 'label' => __( 'More in This Series',     'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'more-in-collection'  => array( 'label' => __( 'More in This Collection', 'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'more-in-universe'    => array( 'label' => __( 'More in This Universe',   'my-book-showroom' ), 'tier' => 'pro',  'requires_option' => 'mbs_setting_advanced_universe_enabled' ),
			'more-by-author'      => array( 'label' => __( 'More by This Author',     'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'related-books'       => array( 'label' => __( 'Related Books',           'my-book-showroom' ), 'tier' => 'free', 'requires_option' => '' ),
			'awards-accolades'    => array( 'label' => __( 'Awards & Accolades',      'my-book-showroom' ), 'tier' => 'all',  'requires_option' => '' ),
			'trailer'             => array( 'label' => __( 'Book Trailer',            'my-book-showroom' ), 'tier' => 'pro',  'requires_option' => '' ),
			'audio-sample'        => array( 'label' => __( 'Audio Sample',            'my-book-showroom' ), 'tier' => 'pro',  'requires_option' => '' ),
			'amazon-reviews'      => array( 'label' => __( 'Amazon Reviews',          'my-book-showroom' ), 'tier' => 'pro',  'requires_option' => '' ),
			'kindle-preview'      => array( 'label' => __( 'Kindle Preview',          'my-book-showroom' ), 'tier' => 'pro',  'requires_option' => '' ),
			'book-club-resources' => array( 'label' => __( 'Book Club Resources',     'my-book-showroom' ), 'tier' => 'pro',  'requires_option' => '' ),
		);
	}

	/**
	 * Returns canonical section data with option-gated sections removed.
	 *
	 * Sections whose requires_option value resolves to falsy are excluded.
	 * Tier filtering (PRO gate) is the responsibility of the caller.
	 *
	 * @param bool $check_options Apply requires_option filter. Default true.
	 * @return array[] Section data keyed by section key.
	 *                 Each entry: ['label' => string, 'tier' => string, 'requires_option' => string]
	 */
	public static function get_available_section_data( bool $check_options = true ): array {
		$data = self::get_canonical_section_data();
		if ( ! $check_options ) {
			return $data;
		}
		foreach ( $data as $key => $meta ) {
			if ( '' !== $meta['requires_option']
				 && ! (int) get_option( $meta['requires_option'] ) ) {
				unset( $data[ $key ] );
			}
		}
		return $data;
	}

}
