<?php
/**
 * Standard settings tab ids and ordering for RSM plugins.
 *
 * @package Rsmspark_Suite
 */

defined( 'ABSPATH' ) || exit;

/**
 * Tab order helpers for Rsmspark_Settings_Page.
 */
final class Rsmspark_Settings_Tabs {

	/** @var string */
	public const GENERAL = 'general';

	/** @var string */
	public const APPEARANCE = 'appearance';

	/** @var string */
	public const INTEGRATIONS = 'integrations';

	/** @var string */
	public const WORKFLOW = 'workflow';

	/** @var string Tools tab (calendar and similar). */
	public const TOOLS = 'tools';

	/** @var string */
	public const IMPORT_EXPORT = 'import_export';

	/** @var string Power-user / diagnostic settings; always immediately before Licensing. */
	public const ADVANCED = 'advanced';

	/** @var string Always last when present (suite license lives in Spark PRO; per-plugin for à-la-carte sales). */
	public const LICENSING = 'licensing';

	/** @var string Forms notification defaults tab. */
	public const NOTIFICATIONS = 'notifications';

	/** @var string Forms Pro payments configuration. */
	public const PAYMENTS = 'payments';

	/** @var string Content Widgets widget registry tab. */
	public const WIDGETS = 'widgets';

	/** @var string Spark suite manager tabs. */
	public const PLUGINS = 'plugins';

	/** @var string */
	public const EDITOR = 'editor';

	/** @var string Spark published documentation links tab. */
	public const DOCUMENTATION = 'documentation';

	/** @var string Spark starter site importer tab (RSF Phase 3). */
	public const STARTER_SITES = 'starter_sites';

	/** @var string Spark PRO licensing tab. */
	public const PRO = 'pro';

	/**
	 * RSM Forms — Payments before Advanced/Licensing; Import/Export added in a later phase.
	 *
	 * @var list<string>
	 */
	public const FORMS_ORDER = array(
		self::GENERAL,
		self::APPEARANCE,
		self::NOTIFICATIONS,
		self::INTEGRATIONS,
		self::IMPORT_EXPORT,
		self::PAYMENTS,
		self::ADVANCED,
		self::LICENSING,
	);

	/**
	 * Default tab order for most suite plugins.
	 *
	 * @var list<string>
	 */
	public const STANDARD_ORDER = array(
		self::GENERAL,
		self::APPEARANCE,
		self::INTEGRATIONS,
		self::WORKFLOW,
		self::TOOLS,
		self::IMPORT_EXPORT,
		self::ADVANCED,
		self::LICENSING,
	);

	/**
	 * Content Widgets — Widgets tab follows General.
	 *
	 * @var list<string>
	 */
	public const CONTENT_WIDGETS_ORDER = array(
		self::GENERAL,
		self::WIDGETS,
		self::EDITOR,
		self::ADVANCED,
		self::LICENSING,
	);

	/**
	 * RSM Spark — PRO tab is suite licensing (always last).
	 *
	 * @var list<string>
	 */
	public const SPARK_ORDER = array(
		self::PLUGINS,
		self::EDITOR,
		self::DOCUMENTATION,
		self::STARTER_SITES,
		self::ADVANCED,
		self::PRO,
	);

	/**
	 * Reorder a tab definition array without dropping unknown tabs.
	 *
	 * Tabs listed in $order appear first (in that sequence). Any remaining tab
	 * ids keep their relative order from $tabs and are appended afterward.
	 *
	 * @param array<string, array<string, mixed>> $tabs  Tab id => [ label, callback, ... ].
	 * @param list<string>                        $order Preferred tab ids.
	 * @return array<string, array<string, mixed>>
	 */
	public static function order( array $tabs, array $order = self::STANDARD_ORDER ) {
		if ( empty( $tabs ) ) {
			return $tabs;
		}

		$ordered = array();

		foreach ( $order as $tab_id ) {
			if ( isset( $tabs[ $tab_id ] ) ) {
				$ordered[ $tab_id ] = $tabs[ $tab_id ];
			}
		}

		foreach ( $tabs as $tab_id => $tab ) {
			if ( ! isset( $ordered[ $tab_id ] ) ) {
				$ordered[ $tab_id ] = $tab;
			}
		}

		return $ordered;
	}

	/**
	 * Build a tab array from partial definitions, applying standard order.
	 *
	 * @param array<string, array<string, mixed>> $tabs  Tab definitions keyed by id.
	 * @param list<string>                        $order Optional order override.
	 * @return array<string, array<string, mixed>>
	 */
	public static function build( array $tabs, array $order = self::STANDARD_ORDER ) {
		return self::order( $tabs, $order );
	}

	/**
	 * Whether the licensing tab (or Spark PRO) is the last tab in the ordered list.
	 *
	 * @param array<string, array<string, mixed>> $tabs           Ordered tab definitions.
	 * @param string                              $licensing_tab_id Tab id for licensing (default licensing; use pro for Spark).
	 * @return bool
	 */
	public static function licensing_is_last( array $tabs, $licensing_tab_id = self::LICENSING ) {
		if ( empty( $tabs ) || ! isset( $tabs[ $licensing_tab_id ] ) ) {
			return true;
		}

		$ids = array_keys( $tabs );

		return $licensing_tab_id === $ids[ count( $ids ) - 1 ];
	}
}
