<?php

/**
 * @package    Grav\Common\Page
 *
 * @copyright  Copyright (c) 2015 - 2025 Trilby Media, LLC. All rights reserved.
 * @license    MIT License; see LICENSE file for details.
 */

namespace Grav\Common\Page\Interfaces;

use ArrayAccess;
use Countable;
use Exception;
use InvalidArgumentException;
use Serializable;
use Traversable;

/**
 * Interface PageCollectionInterface
 * @package Grav\Common\Page\Interfaces
 *
 * @template TKey of array-key
 * @template T
 * @extends Traversable<TKey,T>
 * @extends ArrayAccess<TKey|null,T>
 */
interface PageCollectionInterface extends Traversable, ArrayAccess, Countable, Serializable
{
    /**
     * Get the collection params
     *
     * @return array
     */
    public function params();

    /**
     * Set parameters to the Collection
     *
     * @param array $params
     * @return $this
     */
    public function setParams(array $params);

    /**
     * Add a single page to a collection
     *
     * @param PageInterface $page
     * @return $this
     */
    public function addPage(PageInterface $page);

    /**
     * Add a page with path and slug
     *
     * @param string $path
     * @param string $slug
     * @return $this
     */
    //public function add($path, $slug);

    /**
     *
     * Create a copy of this collection
     *
     * @return static
     */
    public function copy();

    /**
     *
     * Merge another collection with the current collection
     *
     * @param PageCollectionInterface $collection
     * @return PageCollectionInterface
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function merge(PageCollectionInterface $collection);

    /**
     * Intersect another collection with the current collection
     *
     * @param PageCollectionInterface $collection
     * @return PageCollectionInterface
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function intersect(PageCollectionInterface $collection);

    /**
     * Split collection into array of smaller collections.
     *
     * @param int $size
     * @return PageCollectionInterface[]
     * @phpstan-return array<PageCollectionInterface<TKey,T>>
     */
    public function batch($size);

    /**
     * Remove item from the list.
     *
     * @param PageInterface|string|null $key
     * @return PageCollectionInterface
     * @phpstan-return PageCollectionInterface<TKey,T>
     * @throws InvalidArgumentException
     */
    //public function remove($key = null);

    /**
     * Reorder collection.
     *
     * @param string $by
     * @param string $dir
     * @param array|null  $manual
     * @param string|null $sort_flags
     * @return PageCollectionInterface
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function order($by, $dir = 'asc', $manual = null, $sort_flags = null);

    /**
     * Check to see if this item is the first in the collection.
     *
     * @param  string $path
     * @return bool True if item is first.
     */
    public function isFirst($path): bool;

    /**
     * Check to see if this item is the last in the collection.
     *
     * @param  string $path
     * @return bool True if item is last.
     */
    public function isLast($path): bool;

    /**
     * Gets the previous sibling based on current position.
     *
     * @param  string $path
     * @return PageInterface  The previous item.
     * @phpstan-return T
     */
    public function prevSibling($path);

    /**
     * Gets the next sibling based on current position.
     *
     * @param  string $path
     * @return PageInterface The next item.
     * @phpstan-return T
     */
    public function nextSibling($path);

    /**
     * Returns the adjacent sibling based on a direction.
     *
     * @param  string  $path
     * @param  int $direction either -1 or +1
     * @return PageInterface|PageCollectionInterface|false    The sibling item.
     * @phpstan-return T|false
     */
    public function adjacentSibling($path, $direction = 1);

    /**
     * Returns the item in the current position.
     *
     * @param  string $path the path the item
     * @return int|null The index of the current page, null if not found.
     */
    public function currentPosition($path): ?int;

    /**
     * Returns the items between a set of date ranges of either the page date field (default) or
     * an arbitrary datetime page field where start date and end date are optional
     * Dates must be passed in as text that strtotime() can process
     * http://php.net/manual/en/function.strtotime.php
     *
     * @param string|null $startDate
     * @param string|null $endDate
     * @param string|null $field
     * @return PageCollectionInterface
     * @phpstan-return PageCollectionInterface<TKey,T>
     * @throws Exception
     */
    public function dateRange($startDate = null, $endDate = null, $field = null);

    /**
     * Creates new collection with only visible pages
     *
     * @return PageCollectionInterface The collection with only visible pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function visible();

    /**
     * Creates new collection with only non-visible pages
     *
     * @return PageCollectionInterface The collection with only non-visible pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function nonVisible();

    /**
     * Creates new collection with only pages
     *
     * @return PageCollectionInterface The collection with only pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function pages();

    /**
     * Creates new collection with only modules
     *
     * @return PageCollectionInterface The collection with only modules
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function modules();

    /**
     * Creates new collection with only modules
     *
     * @return PageCollectionInterface The collection with only modules
     * @phpstan-return PageCollectionInterface<TKey,T>
     * @deprecated 1.7 Use $this->modules() instead
     */
    public function modular();

    /**
     * Creates new collection with only non-module pages
     *
     * @return PageCollectionInterface The collection with only non-module pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     * @deprecated 1.7 Use $this->pages() instead
     */
    public function nonModular();

    /**
     * Creates new collection with only published pages
     *
     * @return PageCollectionInterface The collection with only published pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function published();

    /**
     * Creates new collection with only non-published pages
     *
     * @return PageCollectionInterface The collection with only non-published pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function nonPublished();

    /**
     * Creates new collection with only routable pages
     *
     * @return PageCollectionInterface The collection with only routable pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function routable();

    /**
     * Creates new collection with only non-routable pages
     *
     * @return PageCollectionInterface The collection with only non-routable pages
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function nonRoutable();

    /**
     * Creates new collection with only pages of the specified type
     *
     * @param string $type
     * @return PageCollectionInterface The collection
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function ofType($type);

    /**
     * Creates new collection with only pages of one of the specified types
     *
     * @param string[] $types
     * @return PageCollectionInterface The collection
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function ofOneOfTheseTypes($types);

    /**
     * Creates new collection with only pages of one of the specified access levels
     *
     * @param array $accessLevels
     * @return PageCollectionInterface The collection
     * @phpstan-return PageCollectionInterface<TKey,T>
     */
    public function ofOneOfTheseAccessLevels($accessLevels);

    /**
     * Converts collection into an array.
     *
     * @return array
     */
    public function toArray();

    /**
     * Get the extended version of this Collection with each page keyed by route
     *
     * @return array
     * @throws Exception
     */
    public function toExtendedArray();
}
