first commit

mixitup-3.3.1/docs/mixitup-3-migration-guide.md

@@ -0,0 +1,105 @@
+# MixItUp 3 Migration Guide
+
+The biggest change to MixItUp with v3, is the dropping of jQuery as a dependency. MixItUp 1 and 2 both existed as jQuery plugins, with instantiation and API calls abstracted away through a typical jQuery-plugin interface.
+
+With MixItUp 3, we can now interact with MixItUp instances ('mixers') directly with minimal abstraction.
+
+## Instantiation
+
+###### Example: Basic Instantiation
+
+```js
+// MixItUp 2
+
+$('.container').mixItUp();
+```
+
+```js
+// MixItUp 3
+
+var mixer = mixitup('.container');
+```
+
+###### Example: Passing the configuration object
+
+```js
+// MixItUp 2
+
+$('.container').mixItUp({
+    selectors: {
+        target: '.item'
+    }
+});
+```
+
+```js
+// MixItUp 3
+
+var mixer = mixitup('.container', {
+    selectors: {
+        target: '.item'
+    }
+});
+```
+
+Note that the `mixitup()` factory function is now all lowercase, as apposed to the camel case MixItUp 2 jQuery method `.mixItUp()`.
+
+MixItUp 3 adds many new configuration options, and renames or removes some of those from MixItUp 2.
+
+*Further reading: [Configuration Object](/docs/mixitup.Config.md)*
+
+## Method Invocation
+
+```js
+// MixItUp 2
+
+$('.container').mixItUp('filter', '.category-a');
+```
+```js
+// MixItUp 3
+
+mixer.filter('.category-a');
+```
+
+As you may have noticed, mixers in MixItUp 3 have many of the same API methods as were available in MixItUp 2, but are called using standard method invocation syntax, with arguments passed in the standard form rather than the jQuery-UI-like syntax of MixItUp 2.
+
+MixItUp 3 adds many new API methods, and renames or removes some of those from MixItUp 2.
+
+*Further reading: [Mixer API Methods](/docs/mixitup.Mixer.md)*
+
+## Promises and Callbacks
+
+In MixItUp 2, asynchronous operations (those involving animation) accepted an optional callback function to be invoked on completion.
+
+With MixItUp 3, all asynchronous methods return a promise resolving with a state object. Callback functions are still permitted as an optional argument, but promises should be considered the preferred method for dealing with asynchronous operations.
+
+```js
+// MixItUp 2 (callbacks)
+
+$('.container').mixItUp('filter', '.category-a', function(state) {
+    // Operation finished, the new state is:
+
+    console.log(state);
+});
+```
+
+```js
+// MixItUp 3 (promises)
+
+mixer.filter('.category-a')
+    .then(function(state) {
+        // Operation finished, the new state is:
+
+        console.log(state);
+    });
+```
+
+## CSS
+
+In MixItUp 2, it was required that a CSS `display: none` rule be applied to all target elements by default, with MixItUp adding the `display` value of your choice (e.g. `inline-block`) to only those targets to be shown. This was intended to prevent a flash-of-content before MixItUp 2's loading animation started.
+
+With MixItUp 3, loading animations are removed by default, and mixers are instantiated synchronously and instantly. Because of this, it is assumed that all targets in the DOM are already shown, so MixItUp only needs to add `display: none` to those targets to be hidden, using whatever `display` value is declared in your CSS for shown targets.
+
+In short – you no longer need to set `display: none` in your CSS. Simply use whatever display value your layout would require, regardless of MixItUp.
+
+Loading animations are still possible in MixItUp 3 as demonstrated in the [Loading Animation](http://demos.kunkalabs.com/mixitup/loading-animation/) demo. The code for this demo is available [here](/demos/loading-animation/).

mixitup-3.3.1/docs/mixitup.Events.md

@@ -0,0 +1,104 @@
+# mixitup.Events
+
+## Overview
+
+The `mixitup.Events` class contains all custom events dispatched by MixItUp at various
+points within the lifecycle of a mixer operation.
+
+Each event is analogous to the callback function of the same name defined in
+the `callbacks` configuration object, and is triggered immediately before it.
+
+Events are always triggered from the container element on which MixItUp is instantiated
+upon.
+
+As with any event, registered event handlers receive the event object as a parameter
+which includes a `detail` property containting references to the current `state`,
+the `mixer` instance, and other event-specific properties described below.
+
+### Contents
+
+- [mixStart](#mixStart)
+- [mixBusy](#mixBusy)
+- [mixEnd](#mixEnd)
+- [mixFail](#mixFail)
+- [mixClick](#mixClick)
+
+
+<h3 id="mixStart">mixStart</h3>
+
+
+
+
+A custom event triggered immediately after any MixItUp operation is requested
+and before animations have begun.
+
+The `mixStart` event also exposes a `futureState` property via the
+`event.detail` object, which represents the final state of the mixer once
+the requested operation has completed.
+
+
+|Type
+|---
+|`CustomEvent`
+
+
+<h3 id="mixBusy">mixBusy</h3>
+
+
+
+
+A custom event triggered when a MixItUp operation is requested while another
+operation is in progress, and the animation queue is full, or queueing
+is disabled.
+
+
+|Type
+|---
+|`CustomEvent`
+
+
+<h3 id="mixEnd">mixEnd</h3>
+
+
+
+
+A custom event triggered after any MixItUp operation has completed, and the
+state has been updated.
+
+
+|Type
+|---
+|`CustomEvent`
+
+
+<h3 id="mixFail">mixFail</h3>
+
+
+
+
+A custom event triggered whenever a filter operation "fails", i.e. no targets
+could be found matching the requested filter.
+
+
+|Type
+|---
+|`CustomEvent`
+
+
+<h3 id="mixClick">mixClick</h3>
+
+
+
+
+A custom event triggered whenever a MixItUp control is clicked, and before its
+respective operation is requested.
+
+This event also exposes an `originalEvent` property via the `event.detail`
+object, which holds a reference to the original click event.
+
+
+|Type
+|---
+|`CustomEvent`
+
+

mixitup-3.3.1/docs/mixitup.State.md

@@ -0,0 +1,248 @@
+# mixitup.State
+
+## Overview
+
+`mixitup.State` objects expose various pieces of data detailing the state of
+a MixItUp instance. They are provided at the start and end of any operation via
+callbacks and events, with the most recent state stored between operations
+for retrieval at any time via the API.
+
+### Contents
+
+- [id](#id)
+- [activeFilter](#activeFilter)
+- [activeSort](#activeSort)
+- [activeContainerClassName](#activeContainerClassName)
+- [container](#container)
+- [targets](#targets)
+- [hide](#hide)
+- [show](#show)
+- [matching](#matching)
+- [totalTargets](#totalTargets)
+- [totalShow](#totalShow)
+- [totalHide](#totalHide)
+- [totalMatching](#totalMatching)
+- [hasFailed](#hasFailed)
+- [triggerElement](#triggerElement)
+- [activeDataset](#activeDataset)
+
+
+<h3 id="id">id</h3>
+
+
+
+
+The ID of the mixer instance.
+
+
+|Type | Default
+|---  | ---
+|`string`| `''`
+
+
+<h3 id="activeFilter">activeFilter</h3>
+
+
+
+
+The currently active filter command as set by a control click or API call.
+
+
+|Type | Default
+|---  | ---
+|`mixitup.CommandFilter`| `null`
+
+
+<h3 id="activeSort">activeSort</h3>
+
+
+
+
+The currently active sort command as set by a control click or API call.
+
+
+|Type | Default
+|---  | ---
+|`mixitup.CommandSort`| `null`
+
+
+<h3 id="activeContainerClassName">activeContainerClassName</h3>
+
+
+
+
+The current layout-specific container class name, if applied.
+
+
+|Type | Default
+|---  | ---
+|`string`| `''`
+
+
+<h3 id="container">container</h3>
+
+
+
+
+A reference to the container element that the mixer is instantiated on.
+
+
+|Type | Default
+|---  | ---
+|`Element`| `null`
+
+
+<h3 id="targets">targets</h3>
+
+
+
+
+An array of all target elements indexed by the mixer.
+
+
+|Type | Default
+|---  | ---
+|`Array.<Element>`| `[]`
+
+
+<h3 id="hide">hide</h3>
+
+
+
+
+An array of all target elements not matching the current filter.
+
+
+|Type | Default
+|---  | ---
+|`Array.<Element>`| `[]`
+
+
+<h3 id="show">show</h3>
+
+
+
+
+An array of all target elements matching the current filter and any additional
+limits applied such as pagination.
+
+
+|Type | Default
+|---  | ---
+|`Array.<Element>`| `[]`
+
+
+<h3 id="matching">matching</h3>
+
+
+
+
+An array of all target elements matching the current filter irrespective of
+any additional limits applied such as pagination.
+
+
+|Type | Default
+|---  | ---
+|`Array.<Element>`| `[]`
+
+
+<h3 id="totalTargets">totalTargets</h3>
+
+
+
+
+An integer representing the total number of target elements indexed by the
+mixer. Equivalent to `state.targets.length`.
+
+
+|Type | Default
+|---  | ---
+|`number`| `-1`
+
+
+<h3 id="totalShow">totalShow</h3>
+
+
+
+
+An integer representing the total number of target elements matching the
+current filter and any additional limits applied such as pagination.
+Equivalent to `state.show.length`.
+
+
+|Type | Default
+|---  | ---
+|`number`| `-1`
+
+
+<h3 id="totalHide">totalHide</h3>
+
+
+
+
+An integer representing the total number of target elements not matching
+the current filter. Equivalent to `state.hide.length`.
+
+
+|Type | Default
+|---  | ---
+|`number`| `-1`
+
+
+<h3 id="totalMatching">totalMatching</h3>
+
+
+
+
+An integer representing the total number of target elements matching the
+current filter irrespective of any other limits applied such as pagination.
+Equivalent to `state.matching.length`.
+
+
+|Type | Default
+|---  | ---
+|`number`| `-1`
+
+
+<h3 id="hasFailed">hasFailed</h3>
+
+
+
+
+A boolean indicating whether the last operation "failed", i.e. no targets
+could be found matching the filter.
+
+
+|Type | Default
+|---  | ---
+|`boolean`| `false`
+
+
+<h3 id="triggerElement">triggerElement</h3>
+
+
+
+
+The DOM element that was clicked if the last operation was triggered by the
+clicking of a control and not an API call.
+
+
+|Type | Default
+|---  | ---
+|`Elementnull`| `null`
+
+
+<h3 id="activeDataset">activeDataset</h3>
+
+
+
+
+The currently active dataset underlying the rendered targets, if the
+dataset API is in use.
+
+
+|Type | Default
+|---  | ---
+|`Array.<object>`| `null`
+
+

mixitup-3.3.1/docs/mixitup.md

@@ -0,0 +1,47 @@
+#mixitup()
+
+*Version added: 3.0.0*
+
+`mixitup(container [,config] [,foreignDoc])`
+
+The `mixitup()` "factory" function creates and returns individual instances
+of MixItUp, known as "mixers", on which API methods can be called.
+
+When loading MixItUp via a script tag, the factory function is accessed
+via the global variable `mixitup`. When using a module loading
+system (e.g. ES2015, CommonJS, RequireJS), the factory function is
+exported into your module when you require the MixItUp library.
+
+|   |Type | Name | Description
+|---|--- | --- | ---
+|Param   |`Element, string` | `container` | A DOM element or selector string representing the container(s) on which to instantiate MixItUp.
+|Param   |`object` | `[config]` | An optional "configuration object" used to customize the behavior of the MixItUp instance.
+|Param   |`object` | `[foreignDoc]` | An optional reference to a `document`, which can be used to control a MixItUp instance in an iframe.
+|Returns |`mixitup.Mixer` | A "mixer" object holding the MixItUp instance.
+
+###### Example 1: Creating a mixer instance with an element reference
+
+```js
+var containerEl = document.querySelector('.container');
+
+var mixer = mixitup(containerEl);
+```
+###### Example 2: Creating a mixer instance with a selector string
+
+```js
+var mixer = mixitup('.container');
+```
+###### Example 3: Passing a configuration object
+
+```js
+var mixer = mixitup(containerEl, {
+    animation: {
+        effects: 'fade scale(0.5)'
+    }
+});
+```
+###### Example 4: Passing an iframe reference
+
+```js
+var mixer = mixitup(containerEl, config, foreignDocument);
+```