FilterBar

A unified search+sort+group toolbar. Any combination of controls can be included. Fires a single m:filterbar:change event with the full filter state whenever any control changes. When linked to a Pagination instance via ->pager(), the pager is automatically reset to page 1 on each change. The JS instance provides groupSlice() — a group-aware pagination utility that packs complete groups into pages so no group is ever split across a page boundary.

Search Only

The simplest configuration — a search box that fires m:filterbar:change on every keystroke (debounced 200 ms).

Type to see state…

Sort Buttons Only

Button groups for sort or view-mode switching. Buttons are mutually exclusive within a group.

Click a sort button…

Sort + Group with Labels

Mix icons and labels in the same button group. Useful when the distinction between options needs to be clear.

Click a group button…

Group-Aware Pagination

The classic pagination bug: slicing items before grouping splits groups across page boundaries. groupSlice(items, keyFn, sortFn, perPage, pageIndex) solves this by packing complete groups into pages greedily — a group is never split. Changing any control below updates the page count and resets to page 1 automatically.

48 films across multiple years and genres. Set per-page to a small number (e.g. 6) to observe that changing the group dimension never leaves a partial group at the end of a page.

echo $m->filterBar('moviesFilter')
    ->search('Search titles…')
    ->sort([
        ['value' => 'desc', 'icon' => 'fa-arrow-down-wide-short', 'tooltip' => 'Descending', 'active' => true],
        ['value' => 'asc',  'icon' => 'fa-arrow-up-short-wide',   'tooltip' => 'Ascending'],
    ])
    ->group([
        ['value' => 'year',  'icon' => 'fa-calendar', 'tooltip' => 'Group by year',  'active' => true],
        ['value' => 'genre', 'icon' => 'fa-film',     'tooltip' => 'Group by genre'],
        ['value' => 'none',  'icon' => 'fa-list',     'tooltip' => 'No grouping'],
    ])
    ->pager('moviesPager');

echo $m->pagination('moviesPager')
    ->showInfo(true)
    ->align('center');

document.addEventListener('DOMContentLoaded', function () {
    var allMovies = /* PHP JSON */ [];
    var pageIndex = 0;
    var perPage   = 6;

    var fb    = m.filterBar('moviesFilter');
    var pager = m.pagination('moviesPager');

    document.getElementById('moviesFilter').addEventListener('m:filterbar:change', function () {
        pageIndex = 0; // reset on filter change (pager already reset to page 1 by FilterBar)
        render();
    });

    document.getElementById('moviesPager').addEventListener('m:pagination:change', function (e) {
        pageIndex = e.detail.page - 1;
        render();
    });

    function render() {
        var state    = fb.getState();
        var filtered = allMovies.filter(function (m) {
            return m.title.toLowerCase().indexOf(state.search.toLowerCase()) >= 0;
        });

        // Sort filtered items first
        filtered.sort(function (a, b) {
            return state.sort === 'asc' ? a.year - b.year : b.year - a.year;
        });

        var result;

        if (state.group === 'none') {
            // Ungrouped: use standard slice, then display as flat list
            var total = filtered.length;
            var slice = filtered.slice(pageIndex * perPage, (pageIndex + 1) * perPage);
            pager.setTotal(total);
            // displayFlat(slice); ...
        } else {
            // Grouped: use groupSlice — never splits a group across pages
            var keyFn  = state.group === 'genre'
                ? function (m) { return m.genre; }
                : function (m) { return String(m.year); };
            var sortFn = function (keys) {
                return keys.sort(state.sort === 'asc' ? undefined
                    : function (a, b) { return b.localeCompare(a); });
            };

            result = fb.groupSlice(filtered, keyFn, sortFn, perPage, pageIndex);
            pager.setTotal(filtered.length);
            pager.setTotalPages(result.totalPages);   // <-- correct page count for groups
            // displayGroups(result.keys, result.groups); ...
        }
    }

    render();
});

Basic Usage

// Search only
echo $m->filterBar('myFilter')
    ->search('Search…');

// Sort buttons only
echo $m->filterBar('myFilter')
    ->sort([
        ['value' => 'desc', 'icon' => 'fa-arrow-down-wide-short', 'tooltip' => 'Newest first', 'active' => true],
        ['value' => 'asc',  'icon' => 'fa-arrow-up-short-wide',   'tooltip' => 'Oldest first'],
    ]);

// Full FilterBar with search, sort, group, and linked pager
echo $m->filterBar('myFilter')
    ->search('Search titles…')
    ->sort([
        ['value' => 'desc', 'icon' => 'fa-arrow-down-wide-short', 'tooltip' => 'Descending', 'active' => true],
        ['value' => 'asc',  'icon' => 'fa-arrow-up-short-wide',   'tooltip' => 'Ascending'],
    ])
    ->group([
        ['value' => 'year',  'icon' => 'fa-calendar',    'tooltip' => 'Group by year',  'active' => true],
        ['value' => 'genre', 'icon' => 'fa-film',        'tooltip' => 'Group by genre'],
        ['value' => 'none',  'icon' => 'fa-list',        'tooltip' => 'No grouping'],
    ])
    ->pager('myPager');

document.addEventListener('DOMContentLoaded', function () {
    var fb = m.filterBar('myFilter');

    document.getElementById('myFilter').addEventListener('m:filterbar:change', function (e) {
        console.log(e.detail); // { search: '...', sort: '...', group: '...' }
        // Re-render your list using e.detail
    });
});

PHP PHP Methods (Fluent)

Method / Property	Parameters	Description
`$m->filterBar($id)`	`FilterBar`	Create a FilterBar instance.
`->search($placeholder)`	`self`	Add a debounced search input. Default: omitted (no search shown).
`->sort($options)`	`self`	Add a mutually-exclusive sort button group. Each option: `['value', 'icon', 'label', 'tooltip', 'active']`. Default: omitted.
`->group($options)`	`self`	Add a mutually-exclusive group/view button group. Same option shape as sort. Default: omitted.
`->pager($pagerId)`	`self`	Link to a Pagination element (by id). The pager resets to page 1 on every filter change. Default: omitted (no linked pager).
`->addClass($class)`	`self`	Append extra CSS class(es) to the root element.
`->attr($name, $val)`	`self`	Add an arbitrary HTML attribute to the root element.

JS JS Methods

Method / Property	Parameters	Description
`m.filterBar(id)`	`API object`	Get the FilterBar instance for the given element id.
`getState()`	`{ search, sort, group }`	Return the current filter state object.
`setState(partial)`	`void`	Programmatically update one or more state keys. Does NOT fire the change event or reset the linked pager.
`groupSlice(items, keyFn, sortFn, perPage, pageIndex)`	`{ keys, groups, totalPages }`	Return the groups and keys for one page using group-aware pagination (no group is ever split). `pageIndex` is 0-based (= pager.getState().page − 1).
`computeGroupPages(items, keyFn, sortFn, perPage)`	`{ pages, allGroups, sortedKeys, totalPages }`	Pre-compute all page buckets. Useful when you need `totalPages` before rendering.

EVENT Events

Event Name	Detail	Description
`m:filterbar:change`	`{ search: string, sort: string, group: string }`	Fired on the FilterBar element whenever any search/sort/group control changes. The linked pager (if set) resets to page 1 before this fires.