////
/// Validators are custom functions that will be called before a BEM entity is created.
/// They check if the current mixin usage is valid or not and thus they are a flexible way to
/// let you implement your own rules.
/// 
/// Validator functions receive the following information:
/// - BEM entity type
/// - Arguments passed to the mixin
/// - The generated selector
/// - The generated context, if any
/// 
/// Additionally, the context stack used by the BEM system can be examined.
///
/// @group BEM
///
/// @access public
////

@use './vars';
@use '../functions';
@use '../contexts';

///
/// A list of validator functions.
///
/// @type list
///
/// @access private
///
$validators: ();

///
/// Register one or multiple validator functions.
///
/// A validator function is a function that accepts 4 arguments:
/// 1. BEM entity type (string)
/// 2. Arguments passed to the mixin (map)
/// 3. The generated selector (selector)
/// 4. The generated context (list, may be null)
/// 
/// The function must return a list with two items:
/// 1. `true` if the mixin usage is valid, otherwise `false`,
/// 2. a string with a rejection reason (empty if the usage is valid).
///
/// @param {string} $func-name  - First function name.
/// @param {string} $func-names - Other function names.
///
@mixin add($func-name, $func-names...) {
    $noop: add($func-name, $func-names...);
}

///
/// Register one or multiple validator functions. Check the respective mixin documentation for more information.
/// 
/// @see {mixin} add
///
@function add($func-name, $func-names...) {
    @each $fn-name in join($func-name, $func-names) {
        $fn: get-function($fn-name);
        $validators: map-merge($validators, ($fn-name: $fn));
    }
    @return null;
}

///
/// Unregister one or multiple validator functions.
///
/// @param {string} $func-name  - First function name.
/// @param {string} $func-names - Other function names.
///
@mixin remove($func-name, $func-names...) {
    $noop: remove($func-name, $func-names...);
}

///
/// Unregister one or multiple validator functions. Check the respective mixin documentation for more information.
/// 
/// @see {mixin} remove
///
@function remove($func-name, $func-names...) {
    $validators: map-remove($validators, $func-name, $func-names...);
    @return null;
}

///
/// @access private
///
@mixin validate($type, $args, $selector, $context) {
    @each $id, $fn in $validators {
        $result: call($fn, $type, $args, $selector, $context);
        @if not nth($result, 1) {
            @error 'A BEM validator rejected this mixin usage due to the following reason: #{nth($result, 2)}';
        }
    }
}

//
// ---------------------------------------------------------------------------------------------------------
//  Built-in validators
// ---------------------------------------------------------------------------------------------------------
//

///
/// A validator that makes sure blocks are declared in the right order, determined by the
/// namespace used.
///
@function enforce-namespace-order($type, $args, $selector, $context) {
    @if not global-variable-exists(namespace-order, vars) {
        vars.$namespace-order: map-keys(vars.$namespaces);
    }
    @if not global-variable-exists(cur-namespace-index, vars) {
        vars.$cur-namespace-index: 1;
    }

    @if $type == 'block' {
        $block-type: map-get($args, 'type');

        @if $block-type != null {
            $ns-index: index(vars.$namespace-order, $block-type);

            @if $ns-index != null {
                @if $ns-index < vars.$cur-namespace-index {
                    @return false 'Namespace "#{$block-type}" comes before current namespace #{nth(vars.$namespace-order, vars.$cur-namespace-index)}';
                }

                vars.$cur-namespace-index: $ns-index;
            }
        }
    }

    @return true '';
}

///
/// A validator that makes all BEM entities immutable.
///
@function immutable-entities($type, $args, $selector, $context) {
    @if not global-variable-exists(generated-selectors, vars) {
        vars.$generated-selectors: ();
    }

    $block-name: null;
    $block-type: null;
    $block-id:   null;

    @if $type == 'block' {
        $block-name: map-get($args, 'name');
        $block-type: map-get($args, 'type');
    } @else {
        $block-context: contexts.get(vars.$context-id, 'block');
        $block-name:    map-get(nth($block-context, 2), 'name');
        $block-type:    map-get(nth($block-context, 2), 'type');
    }

    @if $block-type != null {
        $block-id: $block-name + '_' + $block-type;
    } @else {
        $block-id: $block-name;
    }

    @if $type == 'block' {
        @if map-has-key(vars.$generated-selectors, $block-id) {
            @return false 'Entity "#{$type}" with arguments [ #{functions.map-print($args)} ] was already defined.';
        }

        vars.$generated-selectors: map-merge(vars.$generated-selectors, ($block-id: ()));
    } @else {
        $selectors: map-get(vars.$generated-selectors, $block-id);

        @if index($selectors, $selector) {
            @return false 'Entity "#{$type}" with arguments [ #{functions.map-print($args)} ] was already defined.';
        }

        $selectors: append($selectors, $selector);

        vars.$generated-selectors: map-merge(vars.$generated-selectors, ($block-id: $selectors));
    }

    @return true '';
}