<?php
/**
 * A list-table column, declared by a feature and rendered by an AdminSurface.
 *
 * @package Adminkeep
 */

namespace Adminkeep\Admin;

defined( 'ABSPATH' ) || exit;

/**
 * What a feature wants shown in a column, expressed without reference to how it is drawn.
 *
 * Same contract as RowAction: declare intent, let the surface place it.
 */
class Column {

	/**
	 * Stable identifier, used as the column key.
	 *
	 * @var string
	 */
	private $id;

	/**
	 * Callable returning the translated heading.
	 *
	 * @var callable
	 */
	private $label_callback;

	/**
	 * Post types this column appears on. Empty means every post type.
	 *
	 * @var string[]
	 */
	private $post_types;

	/**
	 * Callable given a WP_Post, returning the cell's HTML. Must return escaped output.
	 *
	 * @var callable
	 */
	private $render_callback;

	/**
	 * Column id to insert this one before. Null appends.
	 *
	 * @var string|null
	 */
	private $before;

	/**
	 * Whether the column is sortable, and by what.
	 *
	 * @var string|null
	 */
	private $orderby;

	/**
	 * Build from a named-argument array.
	 *
	 * @param array $args {
	 *     @type string      $id         Required. Column key.
	 *     @type callable    $label      Required. Returns the translated heading.
	 *     @type callable    $render     Required. Given WP_Post, echoes or returns escaped HTML.
	 *     @type string[]    $post_types Optional. Defaults to all.
	 *     @type string|null $before     Optional. Insert before this column id.
	 *     @type string|null $orderby    Optional. Makes the column sortable by this key.
	 * }
	 */
	public function __construct( array $args ) {
		$this->id              = isset( $args['id'] ) ? (string) $args['id'] : '';
		$this->label_callback  = isset( $args['label'] ) ? $args['label'] : '__return_empty_string';
		$this->render_callback = isset( $args['render'] ) ? $args['render'] : '__return_empty_string';
		$this->post_types      = isset( $args['post_types'] ) ? (array) $args['post_types'] : array();
		$this->before          = isset( $args['before'] ) ? (string) $args['before'] : null;
		$this->orderby         = isset( $args['orderby'] ) ? (string) $args['orderby'] : null;
	}

	/**
	 * Identifier.
	 *
	 * @return string
	 */
	public function id() {
		return $this->id;
	}

	/**
	 * Heading, resolved now.
	 *
	 * @return string
	 */
	public function label() {
		return (string) call_user_func( $this->label_callback );
	}

	/**
	 * Column id this one is inserted before, if any.
	 *
	 * @return string|null
	 */
	public function before() {
		return $this->before;
	}

	/**
	 * Sort key, if sortable.
	 *
	 * @return string|null
	 */
	public function orderby() {
		return $this->orderby;
	}

	/**
	 * Whether the column is sortable.
	 *
	 * @return bool
	 */
	public function is_sortable() {
		return null !== $this->orderby;
	}

	/**
	 * Whether this column was declared for a post type.
	 *
	 * @param string $post_type Post type slug.
	 * @return bool
	 */
	public function applies_to( $post_type ) {
		if ( empty( $this->post_types ) ) {
			return true;
		}

		return in_array( $post_type, $this->post_types, true );
	}

	/**
	 * Render the cell for a post.
	 *
	 * A callback may echo or return its HTML. Echoed output is captured and handed back with the
	 * return value, so the surface escapes both before printing — nothing reaches the page past it.
	 *
	 * @param \WP_Post $post Post being rendered.
	 * @return string Unescaped HTML; the caller escapes it.
	 */
	public function render_for( $post ) {
		ob_start();
		$returned = call_user_func( $this->render_callback, $post );
		$echoed   = (string) ob_get_clean();

		return $echoed . (string) $returned;
	}
}