1. AngularJS — супергероический фреймворк от гугла, реализующий MVVM шаблон проектирования архитектуры приложения.
2. UI-router — ангуляровский модуль, без которого немыслимо проектирование приложений, основанных на состояниях.
3. Angular-permission — ангуляровский модуль (работает только в паре с ui-router), упрощающий контроль доступа и авторизацию на стороне клиента.
4. Bootstrap 3 — CSS-фреймворк, ускоряющий верстку адаптивных страниц.
5. Yeoman-генератор — консольная утилита для автоматического построения структуры проекта.
6. Bower — менеджер пакетов, упрощающий установку и обновление зависимостей проекта.
7. Gulp — потоковый сборщик проектов на JS.
8. NodeJS — среда разработки серверной части.

1. Последняя версия UI-router выпадает с ошибкой, если в объекте params есть поля со значениями, которые приравниваются к логическому отрицанию (false, 0, undefined, null или пустая строка). Решения проблемы я не нашел, поэтому откатился до последней работоспособной версии «0.2.13».
2. Генератор Yeoman предлагает довольно удобную структуру будущего приложения. В корневом каталоге, помимо служебных, создается каталог src с самим проектом. В нем находится основная html страница и три каталога:
                  
   app — каталог с состояниями приложения (рекомендуется под каждое состояние выделять свою папку).
   assets — папка со статическим контентом.
   components — папка для элементов приложения, которые могут использоваться многократно (в нашем случае это директивы, сервисы, фабрики, провайдеры и т.д.).
          В соответствии с такой структурой Yeoman-овский генератор настраивает gulp на мониторинг изменений и подключение файлов к запущенному приложению (все делается автоматически, не нужно подключать зависимости к html-странице вручную).
   В последней версии генератора папка components была перемещена в каталог app и, соответственно, были изменены настройки gulp. Чтобы наш проект видел папку components и не выдавал в консоли разработчика ошибку об отсутствии модуля navbar, правим следующие файлы в папке gulp:
   
   • скрипт inject.js
     
     в массив injectScripts добавляем элемент
     

      options.src + '/components/**/*.js'
     

     
     в массив injectStyles добавляем элемент
     

     options.src + '/components/**/*.css'
     

     
     
   • скрипт watch.js — добавляем следующие правила:
     
     

     gulp.watch(options.src + '/components/**/*.css', function(event) {
        if(isOnlyChange(event)) {
         browserSync.reload(event.path);
       } else {
         gulp.start('inject');
       }
     });
     gulp.watch(options.src + '/components/**/*.js', function(event) {
       if(isOnlyChange(event)) {
         gulp.start('scripts');
       } else {
         gulp.start('inject');
       }
     });
     gulp.watch(options.src + '/components/**/*.html', function(event) {
       browserSync.reload(event.path);
     });
     

     
     
   
   
3. Так как директива написана на бутстрапе, то, естественно, она требует его компонентов, в частности, библиотеку jQuery. При создании проекта, Yeoman будет спрашивать про необходимость подключения jquery, bootstrap и как с ним работать (ангуляровские директивы ui-bootstrap или AngularStrap, официальное применение bootstrap с jQuery либо чистый CSS). Тут есть небольшой подвох. При установке, еще до выбора вышеперечисленных опций, будет предложено добавить в проект jQuery. Обязательно нужно выбрать эту опцию, иначе останемся без важных зависимостей и все сломается.
           P.S.: на самом деле исправить данный момент не сложно. Всего лишь нужно подшаманить код самой директивы и можно вообще обойтись без jQuery, но, как говорится, «работает — не трогай (с)».
   
   
4. Если возникнет желание побаловаться в проекте гугловским angular-material, который Yeoman предлагает включить в проект, нужно знать, что в таком случае подключится старая версия библиотеки, для которой документация с официального сайта не подходит. Поэтому правильным вариантом будет подключение библиотеки с помощью bower с опцией --save.

<div class="container" ng-mouseleave="closeMenu($event)">  
    <div class="navbar-header">
    <button type="button" class="navbar-toggle" ng-click="collapseMenu($event)">
      <span class="sr-only">Toggle navigation</span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
      <span class="icon-bar"></span>
    </button>
    <a class="link-kukuri" href="#" ui-sref="{{::sref}}" data-letters="{{::name}}">{{::name}}</a>
  </div>
  <div id="navbar" class="collapse navbar-collapse" aria-expanded="false" ng-class="navCollapsed">
    <ul class="nav navbar-nav navbar-right">
      <li ng-repeat="items in navbar" class="{{::menuClass(items.name, 'firstLevel')}} list-status">
        <a href="#" ng-if="!items.name.pop" ui-sref="{{items.state}}" ng-mouseenter="closeOnMoveMenu()">{{items.name}}</a>
        <a href="#" ng-if="items.name.pop" class="dropdown-toggle dropdown-toggle-firstLevel" dropdown-toggle aria-expanded="false" ng-click="expandMenu($event)" ng-mouseenter="expandMenu($event)" ng-mouseleave="closeSubMenu($event)">
          {{::items.name[0]}}<b class="caret"></b>
        </a>
        <ul ng-if="items.name.pop" class="dropdown-menu"  ng-include="'submenu.template'"></ul>
      </li>
    </ul>
  </div>
</div>
<script type="text/ng-template" id="submenu.template">
  <li ng-repeat="items in items.name" ng-if="$index !== 0" class="{{::menuClass(items.name)}} sub-menu">
    <a href="#" class="sub-link" ng-if="!items.name.pop" ui-sref="{{::items.state}}" ng-mouseenter="closeOnMoveSubMenu($event)"> {{::items.name}}</a>
    <a href="#" ng-if="items.name.pop" class="dropdown-toggle" data-toggle="dropdown" ng-click="expandSubMenu($event)" ng-mouseenter="expandSubMenu($event)">
       {{::items.name[0]}}
    </a>
    <ul ng-if="items.name.pop" class="dropdown-menu"  ng-include="'submenu.template'">
    </ul>
  </li>
</script>

1. Список пунктов меню генерируется с помощью директивы ng-repeat, которая клонирует заготовленный html-шаблон, подставляя в него данные из массива пунктов меню, который определяется в текущем скоупе директивы. Отмечу, что в шаблоне используется так называемое одноразовое присваивание (one time binding), синтаксис которого — две точки возле переменной (например {{::name}} ). Дело в том, что на каждую переменную ангуляр создает отдельного слушателя (watcher), который проверяет ее изменение при каждом дайджесте (проверка на изменение всех переменных в текущем скоупе до тех пор, пока их значения меняются, по окончанию происходит отрисовка DOM с новыми значениями). Так как пункты нашего меню — величины постоянные, то имеет смысл отрисовать их один раз, сократив при этом число слушателей и повысив производительность.
   
   
2. Вложенные подпункты собираются рекурсивно при помощи ng-include. Рекурсивная часть шаблона хранится в теге script c атрибутом type=«text/ng-template». Браузер не знает такой тип скрипта и не обрабатывает эту часть DOM, однако директива ng-include вставляет лишь содержимое скрипта в нужном месте, что позволяет браузеру нормально обрабатывать DOM элемент.
           Сама вложенность контролируется директивой ng-if, которая проверяет, является ли текущий элемент массивом пунктов или строкой с названием пункта. Проверка осуществляется при помощи так называемой «утиной типизации», если перед нами массив, то он имеет методы массива (push, pop и т.д.), обращение к которым без () вернет нам функцию, которая приравнивается к логическому true. Если перед нами строка, то такое обращение к методу массива вернет undefined.
   
   
3. Существует внегласное правило работы с директивами ангуляра, которое гласит: «директива не должна изменять элементы DOM-дерева вне своего элемента». Для работы раскрывающихся пунктов меню требуются слушатели, которые будут отслеживать события клика, наведения и покидания курсором элемента. Можно было бы использовать обычный поиск элементов по селекторам элементов DOM дерева и навешать на них слушателей. Но в большом проекте существует вероятность, что кто-то другой будет использовать идентичные названия селекторов. Последствия такого события непредсказуемы :) Для подобных случаев предусмотрены директивы ng-click, ng-mouseenter и ng-mouseleave, которые были навешаны на соответствующие элементы.

'use strict';

(function () {
    angular.module('navbar')
        .directive('navbar', function ($document, $state, navbarList, navPermission) {
            return {
                restrict: 'A',
                scope: {
                    name: '@',
                    sref: '@'
                },
                templateUrl: '/components/navbar.directive/navbar.template.html',
                link: function (scope, elem) {
                    var openedMenu = null,
                        openedSubMenu = null,
                        username = navPermission.getUser($state.params);
// присваиваем нашему DOM элементу необходимые классы и атрибуты для работы bootstrap
                    elem.addClass('navbar navbar-inverse navbar-fixed-top');
                    elem.attr('role', 'navigation');
// редактируем список пунктов меню в соотвествии с доступом и передаем его в scope директивы
                    if(username) {
                        navPermission.acceptPermission(navbarList.list, username);
                    }
                    scope.navbar = navbarList.list;
// открытие/сокрытие меню на телефонах или при узком экране браузера
                    scope.collapseMenu = function ($event) {
                        var navbar = elem.find('#navbar'),
                            expanded = navbar.hasClass('in');
                        navbar.attr('aria-expanded', !expanded);
                        scope.navCollapsed = (expanded) ? '' : 'in';
                        closeAllMenu();
                        stopBubleAndPropagation($event);
                    };
// присвоение класса активного пункта меню соответствующей страницы и класса подменю, если пункт содержит подпункты
                    scope.menuClass = function (item, level) {
                        var status = false,
                            activePage = getActivePage($state.current.name),
                            currentPage = (item.pop) ? item[0] : item,
                            classList = (level === 'firstLevel') ? 'dropdown dropdown-firstLevel ' :
                                'menu-item dropdown dropdown-submenu ',
                            activeClass = (currentPage === activePage || isActive(item, activePage, status) ) ?
                                'menu-active' : '';
                        if(item.pop) {
                            return classList + activeClass;
                        } else {
                            return activeClass;
                        }
                    };
// получение имени активного пункта меню в соответствии с открытой страницей (состоянием)
                    function getActivePage(state, currentList) {
                        var name;
                        if(!currentList) {
                            currentList = scope.navbar;
                        }
                        for(var i = (currentList[0].name) ? 0 : 1; i < currentList.length; i++) {
                            if(currentList[i].state === state) {
                                return currentList[i].name;
                            } else if(currentList[i].name.pop) {
                                name = getActivePage(state, currentList[i].name);
                            }
                        }
                        return name;
                    }
// проверка, является ли пункт меню активным
                    function isActive (item, activePage, status) {
                        if(item.pop) {
                            for(var i = 1; i < item.length; i++) {
                                if(item[i].name.pop) {
                                    status = isActive(item[i].name, activePage, status);
                                } else if(item[i].name === activePage) {
                                    return true;
                                }
                            }
                        } else if(item === activePage) {
                            return true;
                        }
                        return status;
                    }
// раскрытие сокрытие подпунктов меню по кликку или наведению мыши (страшная функция, т.к. учтены варианты разного разрешения экрана)
                    scope.expandMenu = function ($event) {
                        var clickedElem = $($event.currentTarget),
                            parentClicked = $($event.currentTarget.parentElement),
                            expanded = clickedElem.attr('aria-expanded'),
                            isOpened = parentClicked.hasClass('open'),
                            attrExpanded = (expanded === 'false'),
                            allOpenedMenu = parentClicked.parent().find('.open'),
                            smallWindow = window.innerWidth < 768,
                            eventMouseEnter = $event.type === 'mouseenter',
                            subMenuAll = elem.find('.dropdown-submenu');
                        if(!smallWindow || !eventMouseEnter) {
                            allOpenedMenu.removeClass('open');
                            clickedElem.attr('aria-expanded', attrExpanded);
                            if(isOpened && !eventMouseEnter) {
                                parentClicked.removeClass('open');
                            } else {
                                parentClicked.addClass('open');
                                openedMenu = clickedElem; //**
                            }
                        }
                        subMenuAll.removeClass('dropdown-submenu-small dropdown-submenu-big');
                        if(smallWindow) {
                            subMenuAll.addClass('dropdown-submenu-small');
                        } else {
                            subMenuAll.addClass('dropdown-submenu-big');
                        }
                        stopBubleAndPropagation($event);
                    };
// закрытие подменю при наведении на соседний пункт в основном меню
                    scope.closeOnMoveMenu = function () {
                        var smallWindow = window.innerWidth < 768;
                        if(openedMenu && !smallWindow) {
                            var clickedLink = openedMenu,
                                clickedElement = clickedLink.parent();
                            clickedElement.removeClass('open');
                            clickedLink.attr('aria-expanded', false);
                            openedMenu = null;
                        }
                    };
// раскрытие сокрытие подпунктов подменю (аналогично функции с 92 строки)
                    scope.expandSubMenu = function ($event) {
                        var elemClicked = $($event.currentTarget.parentElement),
                            smallWindow = window.innerWidth < 768,
                            eMouseEnter = $event.type === 'mouseenter',
                            sameElement = elemClicked.hasClass('open');
                        if(!smallWindow || !eMouseEnter) { // потом подумать как упростить
                            if(!sameElement && !eMouseEnter || !eMouseEnter || !sameElement) {
                                elemClicked.parent().find('.open').removeClass('open');
                            }
                            if(!sameElement) {
                                elemClicked.addClass('open');
                                openedSubMenu = elemClicked;
                            }
                        }
                        stopBubleAndPropagation($event);
                    };
// закрытие подменю при наведении на соседний подпункт в подменю (звучит то как:))
                    scope.closeOnMoveSubMenu = function ($event) {
                        var smallWindow = window.innerWidth < 768;
                        if(openedSubMenu && !smallWindow) {
                            var clickedElement = openedSubMenu,
                                savedList = clickedElement.parent(),
                                currentList = $($event.target).parent().parent();
                            if(savedList[0] === currentList[0]) {
                                clickedElement.removeClass('open');
                                openedSubMenu = null;
                            }
                        }
                    };
                    scope.closeMenu = closeMenu;
// удаляем всех слушателей с документа при его уничтожении
                    var $body = $document.find('html');
                    elem.bind('$destroy', function() {
                        $body.unbind();  //не хватает проверки на удаленный элемент
                    });
// при клике вне меню - закрываем все открытые позиции
                    $body.bind('click', closeMenu);
                    function closeMenu ($event) {
                        var elemClicked = $event.relatedTarget || $event.target;
                        if(isClickOutNavbar(elemClicked)) {
                            closeAllMenu();
                        }
                    }
// рекурсивно поднимаемся по родителям элемента, чтобы узнать, был клик по меню или нет
                    function isClickOutNavbar(elem) {
                        if($(elem).hasClass('dropdown-firstLevel')) {
                            return false;
                        }
                        if(elem.parentElement !== null) {
                            return isClickOutNavbar(elem.parentElement);
                        } else {
                            return true;
                        }
                    }
// закрываем все открытые пункты и подпункты меню
                    function closeAllMenu() {
                        elem.find('.open').removeClass('open');
                        elem.find('[aria-expanded=true]').attr('aria-expanded', false);
                    }
// служебная функция предотвращения действий браузера поумолчанию и всплывающих событий
                    function stopBubleAndPropagation($event) {
                        $event.stopPropagation();
                        $event.preventDefault();
                    }
                }
            };
        });
})();

'use strict';

(function () {
    angular.module('navbar')
        .provider('navbarList', function () {
            var list = [];
// основная функция добавления пункта в меню
            this.add = function (obj) {
// проверка на правильно заданные параметры расположения пункта
                if(obj.location) {
                    if(obj.location.place.length !== obj.location.priority.length ||
                        !obj.location.place.pop || !obj.location.priority.pop) {
                        console.log('Warning! Bad location params for menu "' + obj.name + '". Skip item');
                        return;
                    }
                }
// добавление пункта на первый уровень меню при отстутствии местоположения
                if(!obj.location) {
                    var name = obj.name;
                    for(var i = 0; i < list.length; i++) { // рассказать про тернарный оператор и утиную типизацию
                        var currentName = (list[i].name.pop) ? list[i].name[0] : list[i].name;
                        if(currentName === name) {
                            console.log('Warning! Duplicate menu "' + name + '". Skip item');
                            return;
                        }
                    }
                    list.push(obj);
                    list.sort(sortByPriority);
                    return;
                }
// поиск пункта, в который нужно добавить подпункт согласно местоположению
                var place = obj.location.place.shift(),
                    priority = obj.location.priority.shift();
                for(i = 0; i < list.length; i++) { // описать в статье, что i блочная не в JS
                    var currentSubName = (list[i].name.pop) ? list[i].name[0] : null;
                    if(place === currentSubName) {
                        list[i].name = changeExistPart(obj, list[i].name);
                        if(priority !== list[i].priority) {
                            console.log('Warning! Priority of menu "' + list[i].name + '" has been changed from "' +
                                list[i].priority + '" to "' + priority + '"');
                            list[i].priority = priority;
                            list.sort(sortByPriority);
                        }
                        return;
                    }
                    currentName = list[i].name;
                    if(place === currentName) {
                        console.log('Warning! Duplicate submenu "' + place + '". Skip item');
                        return;
                    }
                }
// ни одно вышеописанное условие не совпало, добавляем новый пункт со всеми вложениями
                list.push( {
                    name: [place, makeOriginalPart(obj)],
                    priority: priority
                } );
                list.sort(sortByPriority);
            };
// рекурсивный поиск места в подпунктах меню для вставки нового пункта
            function changeExistPart(obj, list) {
                var place = obj.location.place.shift(),
                    priority = obj.location.priority.shift(), //  возможно необходимо сделать двойной приоритет
                    searchName = (place) ? place : obj.name;
                for(var i = 1; i < list.length; i++) {
                    var currentName = (list[i].name.pop) ? list[i].name[0] : list[i].name;
                    if(searchName === currentName) {
                        if(!list[i].name.pop || (!place && list[i].name.pop) ) {
                            console.log('Warning! Duplicate menu "' + searchName + '". Skip item');
                            return list;
                        } else {
                            list[i].name = changeExistPart(obj, list[i].name);
                            if(priority !== list[i].priority) {
                                console.log('Warning! Priority of menu "' + list[i].name +
                                    '" has been changed from "' + list[i].priority + '" to "' + priority + '"');
                                list[i].priority = priority;
                                list.sort(sortByPriority);
                            }
                            return list;
                        }
                    }
                }
                if(!place) {
                    delete obj.location;
                    list.push(obj);
                } else {
                    list.push({
                        name: [place, makeOriginalPart(obj)],
                        priority: priority
                    });
                }
                list.sort(sortByPriority);
                return list;
            }
// рекурсивное создание новой, оригинальной части пункта меню с подпунктами
            function makeOriginalPart (obj) {
                var place = obj.location.place.shift(),
                    priority = obj.location.priority.shift();
                if(place) {
                    var menu = {
                        priority: priority,
                        name: [place, makeOriginalPart(obj)]
                    };
                } else {
                    delete obj.location;
                    menu = obj;
                }
                return menu;
            }
// функция сортировки пунктов меню по приоритету
            function sortByPriority(a, b) {
                return a.priority - b.priority;
            }
// служебная функция для работы провайдера angularJS
            this.$get = function () {
                return {
                    list: list,
                    add: this.add
                };
            };
        });
})();

'use strict';

(function () {
    angular.module('navbar')
        .factory('navPermission', function (Permission, $q) {
// перебираем все роли и возвращаем подходящую в виде промиса
            function getUser(params) {
                var users = Permission.roleValidations,
                    names = Object.keys(users),
                    promisesArr = [];
                for(var i = 0; i < names.length; i++) {
                    var current = names[i],
                        validUser = $q.when( users[current](params) );
                    promisesArr.push(validUser);
                }
                return $q.all(promisesArr).then(function (users) {
                   for(var i = 0; i < users.length; i++) {
                       if(users[i]) {
                           return names[i];
                       }
                   }
                    return null;
                });
            }
// если пришел промис, ждем его разрешения и меняем меню, если пользователь - сразу меняем меню
            function acceptPermission (list, username) {
                if(!username.then) {
                    return changeList(list, username);
                } else {
                    return username.then(function (username) {
                        return changeList(list, username);
                    });
                }
            }
// рекурсивно пробегаемся по массиву меню и удаляем пункты, которые запрещены для текущей роли
            function changeList(list, username) {
                for(var i = (list[0].name) ? 0 : 1; i < list.length; i++) {
                    if(list[i].permissions) {
                        if(list[i].permissions.except) {
                            var except = list[i].permissions.except;
                            for(var j = 0; j < except.length; j++) {
                                if(except[j] === username) {
                                    list.splice(i--, 1);
                                }
                            }
                        } else if(list[i].permissions.only) {
                            var only = list[i].permissions.only,
                                accessDenided = true;
                            for(j = 0; j < only.length; j++) {
                                if(only[j] === username) {
                                    accessDenided = false;
                                }
                            }
                            if(accessDenided) {
                                list.splice(i--, 1);
                            }
                        }
                    } else if(list[i].name.pop) {
                        list[i].name = changeList( list[i].name, username);
                        if(list[i].name.length === 1 ) {
                            list.splice(i--, 1);
                        }
                    }
                }
                return list;
            }
// возвращаем созданные методы фабрики
            return {
                getUser: getUser,
                acceptPermission: acceptPermission
            };
        });
})();

'use strict';

(function() {
    angular.module('navbar')
        .config(function ($stateProvider, navbarListProvider) {
// добавляем в метод state функционал регистрации пунктов меню
            $stateProvider.decorator('state', function (obj) {
                var menu = obj.menu,
                    permissions = (obj.data) ? obj.data.permissions : null;
// если в коде не указана регистрация текущего стейта в меню - ничего не делаем
                if(!menu) {
                    return;
                }
                menu.state = obj.name;
// регистрируем права доступа пункта при их наличии
                if(permissions) {
                    menu.permissions = {};
                    if(permissions.except) {
                        menu.permissions.except = permissions.except;
                    } else if(permissions.only) {
                        menu.permissions.only = permissions.only;
                    } else {
                        delete menu.permissions;
                    }
                }
// регистрируем пункт меню по скомпонованному объекту menu
                navbarListProvider.add(menu);
            });
        });
})();