basic-component-mixins - npm Package Compare versions

Comparing version 0.7.5 to 0.7.6

docs/AttributeMarshalling.md

 # API Documentation
 <a name="AttributeMarshalling"></a>
+
 ## AttributeMarshalling
@@ -4,0 +5,0 @@ Mixin which marshalls attributes to properties (and eventually vice versa).

docs/ClickSelection.md

 # API Documentation
 <a name="ClickSelection"></a>
+
 ## ClickSelection
@@ -4,0 +5,0 @@ Mixin which maps a click (actually, a mousedown) to a selection.

docs/Collective.md

 # API Documentation
 <a name="Collective"></a>
+
 ## Collective
@@ -46,8 +47,9 @@ A group of elements that have been associated for the purpose of
     * [.assimilate(target)](#Collective+assimilate)
-    * [new Collective([elements])](#new_Collective_new)
+    * [new Collective([...elements])](#new_Collective_new)
     * [.elements](#Collective+elements) : <code>Array.&lt;HTMLElement&gt;</code>
-    * [.invokeMethod(method, [args])](#Collective+invokeMethod)
+    * [.invokeMethod(method, [...args])](#Collective+invokeMethod)
     * [.outermostElement](#Collective+outermostElement)
 
 <a name="Collective+assimilate"></a>
+
 ### collective.assimilate(target)
@@ -71,3 +73,4 @@ Add the indicated target to the collective.
 <a name="new_Collective_new"></a>
-### new Collective([elements])
+
+### new Collective([...elements])
 Create a collective.
@@ -78,5 +81,6 @@
 | --- | --- | --- |
-| [elements] | <code>Array.&lt;HTMLELement&gt;</code> | Initial elements to add. |
+| [...elements] | <code>Array.&lt;HTMLELement&gt;</code> | Initial elements to add. |
 
 <a name="Collective+elements"></a>
+
 ### collective.elements : <code>Array.&lt;HTMLElement&gt;</code>
@@ -87,3 +91,4 @@ The elements in the collective.
 <a name="Collective+invokeMethod"></a>
-### collective.invokeMethod(method, [args])
+
+### collective.invokeMethod(method, [...args])
 Invoke a method on all elements in the collective.
@@ -96,5 +101,6 @@
 | method | <code>string</code> | The name of the method to invoke on all elements. |
-| [args] | <code>Array.&lt;object&gt;</code> | The arguments to the method |
+| [...args] | <code>Array.&lt;object&gt;</code> | The arguments to the method |
 
 <a name="Collective+outermostElement"></a>
+
 ### collective.outermostElement
@@ -101,0 +107,0 @@ The outermost element in the collective.

docs/Composable.md

 # API Documentation
 <a name="Composable"></a>
+
 ## Composable
@@ -12,2 +13,3 @@ Mixin to make a class more easily composable with other mixins.
 <a name="Composable.compose"></a>
+
 ### Composable.compose(...mixins)
@@ -14,0 +16,0 @@ Apply a set of mixin functions or mixin objects to the present class and

docs/composeTemplates.md

 # API Documentation
 <a name="composeTemplates"></a>
+
 ## composeTemplates(baseTemplate, subTemplate)
@@ -4,0 +5,0 @@ Given two templates, this "folds" one inside the other. This is

docs/ContentAsItems.md

 # API Documentation
 <a name="ContentAsItems"></a>
+
 ## ContentAsItems
@@ -31,2 +32,3 @@ Mixin which maps content semantics (elements) to list item semantics.
 <a name="ContentAsItems+applySelection"></a>
+
 ### contentAsItems.applySelection(item, selected)
@@ -47,2 +49,3 @@ Apply the selection state to a single item.
 <a name="ContentAsItems+itemAdded"></a>
+
 ### contentAsItems.itemAdded(item)
@@ -61,2 +64,3 @@ This method is invoked whenever a new item is added to the list.
 <a name="ContentAsItems+items"></a>
+
 ### contentAsItems.items : <code>Array.&lt;HTMLElement&gt;</code>
@@ -68,2 +72,3 @@ The current set of items in the list. See the top-level documentation for
 <a name="ContentAsItems.event_items-changed"></a>
+
 ### "items-changed"
@@ -74,2 +79,3 @@ Fires when the items in the list change.
 <a name="ContentAsItems+itemsChanged"></a>
+
 ### contentAsItems.itemsChanged()
@@ -76,0 +82,0 @@ This method is invoked when the underlying contents change. It is also

docs/ContentFirstChildTarget.md

 # API Documentation
 <a name="ContentFirstChildTarget"></a>
+
 ## ContentFirstChildTarget
@@ -31,2 +32,3 @@ Mixin that defines the target of a component — the element the component is
 <a name="ContentFirstChildTarget+target"></a>
+
 ### contentFirstChildTarget.target : <code>HTMLElement</code>
@@ -33,0 +35,0 @@ Gets/sets the current target of the component.

docs/DirectionSelection.md

 # API Documentation
 <a name="DirectionSelection"></a>
+
 ## DirectionSelection
@@ -4,0 +5,0 @@ Mixin which maps direction semantics (goLeft, goRight, etc.) to selection

docs/DistributedChildren.md

 # API Documentation
 <a name="DistributedChildren"></a>
+
 ## DistributedChildren
@@ -54,2 +55,3 @@ Mixin which defines helpers for accessing a component's distributed
 <a name="DistributedChildren+distributedChildNodes"></a>
+
 ### distributedChildren.distributedChildNodes : <code>Array.&lt;Node&gt;</code>
@@ -61,2 +63,3 @@ An in-order collection of child nodes, expanding any slot elements. Like
 <a name="DistributedChildren+distributedChildren"></a>
+
 ### distributedChildren.distributedChildren : <code>Array.&lt;HTMLElement&gt;</code>
@@ -68,2 +71,3 @@ An in-order collection of children, expanding any slot elements. Like the
 <a name="DistributedChildren+distributedTextContent"></a>
+
 ### distributedChildren.distributedTextContent : <code>string</code>
@@ -70,0 +74,0 @@ The concatenated text content of all child nodes, expanding any slot

docs/DistributedChildrenAsContent.md

 # API Documentation
 <a name="DistributedChildrenAsContent"></a>
+
 ## DistributedChildrenAsContent
@@ -16,2 +17,3 @@ Mixin which defines a component's content as its children, expanding any
 <a name="DistributedChildrenAsContent+content"></a>
+
 ### distributedChildrenAsContent.content : <code>Array.&lt;HTMLElement&gt;</code>
@@ -18,0 +20,0 @@ The content of this component, defined to be the flattened array of

docs/Generic.md

 # API Documentation
 <a name="Generic"></a>
+
 ## Generic
@@ -29,2 +30,3 @@ Mixin which allows a component to support a "generic" style: a minimalist
 <a name="Generic+generic"></a>
+
 ### generic.generic : <code>Boolean</code>
@@ -31,0 +33,0 @@ True if the component would like to receive generic styling.

docs/ItemsSelection.md

 # API Documentation
 <a name="ItemsSelection"></a>
+
 ## ItemsSelection
@@ -37,2 +38,3 @@ Mixin which manages single-selection semantics for items in a list.
     * [.selectionRequired](#ItemsSelection+selectionRequired) : <code>boolean</code>
+    * [.selectionWraps](#ItemsSelection+selectionWraps) : <code>boolean</code>
     * [.selectLast()](#ItemsSelection+selectLast)
@@ -43,2 +45,3 @@ * [.selectNext()](#ItemsSelection+selectNext)
 <a name="ItemsSelection+applySelection"></a>
+
 ### itemsSelection.applySelection(item, selected)
@@ -58,2 +61,3 @@ Apply the indicate selection state to the item.
 <a name="ItemsSelection+canSelectNext"></a>
+
 ### itemsSelection.canSelectNext : <code>boolean</code>
@@ -65,2 +69,3 @@ True if the selection can be moved to the next item, false if not (the
 <a name="ItemsSelection+canSelectPrevious"></a>
+
 ### itemsSelection.canSelectPrevious : <code>boolean</code>
@@ -72,2 +77,3 @@ True if the selection can be moved to the previous item, false if not
 <a name="ItemsSelection+itemAdded"></a>
+
 ### itemsSelection.itemAdded(item)
@@ -86,2 +92,3 @@ Handle a new item being added to the list.
 <a name="ItemsSelection.event_selected-index-changed"></a>
+
 ### "selected-index-changed"
@@ -97,2 +104,3 @@ Fires when the selectedIndex property changes.
 <a name="ItemsSelection.event_selected-item-changed"></a>
+
 ### "selected-item-changed"
@@ -109,10 +117,13 @@ Fires when the selectedItem property changes.
 <a name="ItemsSelection+selectedIndex"></a>
+
 ### itemsSelection.selectedIndex : <code>number</code>
-The index of the item which is currently selected, or -1 if there is no
-selection.
+The index of the item which is currently selected.
 
-Setting the index to -1 deselects any current-selected item.
+If `selectionWraps` is false, the index is -1 if there is no selection.
+In that case, setting the index to -1 will deselect any
+currently-selected item.
 
   **Kind**: instance property of <code>[ItemsSelection](#ItemsSelection)</code>
 <a name="ItemsSelection+selectedItem"></a>
+
 ### itemsSelection.selectedItem : <code>object</code>
@@ -125,2 +136,3 @@ The currently selected item, or null if there is no selection.
 <a name="ItemsSelection+selectFirst"></a>
+
 ### itemsSelection.selectFirst()
@@ -131,2 +143,3 @@ Select the first item in the list.
 <a name="ItemsSelection+selectionRequired"></a>
+
 ### itemsSelection.selectionRequired : <code>boolean</code>
@@ -136,3 +149,11 @@ True if the list should always have a selection (if it has items).
   **Kind**: instance property of <code>[ItemsSelection](#ItemsSelection)</code>
+<a name="ItemsSelection+selectionWraps"></a>
+
+### itemsSelection.selectionWraps : <code>boolean</code>
+True if selection navigations wrap from last to first, and vice versa.
+
+  **Kind**: instance property of <code>[ItemsSelection](#ItemsSelection)</code>
+**Default**: <code>{false}</code>  
 <a name="ItemsSelection+selectLast"></a>
+
 ### itemsSelection.selectLast()
@@ -143,2 +164,3 @@ Select the last item in the list.
 <a name="ItemsSelection+selectNext"></a>
+
 ### itemsSelection.selectNext()
@@ -149,2 +171,3 @@ Select the next item in the list.
 <a name="ItemsSelection+selectPrevious"></a>
+
 ### itemsSelection.selectPrevious()
@@ -151,0 +174,0 @@ Select the previous item in the list.

docs/Keyboard.md

 # API Documentation
 <a name="Keyboard"></a>
+
 ## Keyboard
@@ -44,2 +45,3 @@ Mixin which manages the keydown handling for a component.
 <a name="Keyboard+keydown"></a>
+
 ### keyboard.keydown(event) ⇒ <code>boolean</code>
@@ -46,0 +48,0 @@ Handle the indicated keyboard event.

docs/KeyboardDirection.md

 # API Documentation
 <a name="KeyboardDirection"></a>
+
 ## KeyboardDirection
@@ -28,2 +29,3 @@ Mixin which maps direction keys (Left, Right, etc.) to direction semantics
 <a name="KeyboardDirection+goDown"></a>
+
 ### keyboardDirection.goDown()
@@ -35,2 +37,3 @@ Invoked when the user wants to go/navigate down.
 <a name="KeyboardDirection+goEnd"></a>
+
 ### keyboardDirection.goEnd()
@@ -42,2 +45,3 @@ Invoked when the user wants to go/navigate to the end (e.g., of a list).
 <a name="KeyboardDirection+goLeft"></a>
+
 ### keyboardDirection.goLeft()
@@ -49,2 +53,3 @@ Invoked when the user wants to go/navigate left.
 <a name="KeyboardDirection+goRight"></a>
+
 ### keyboardDirection.goRight()
@@ -56,2 +61,3 @@ Invoked when the user wants to go/navigate right.
 <a name="KeyboardDirection+goStart"></a>
+
 ### keyboardDirection.goStart()
@@ -63,2 +69,3 @@ Invoked when the user wants to go/navigate to the start (e.g., of a
 <a name="KeyboardDirection+goUp"></a>
+
 ### keyboardDirection.goUp()
@@ -70,2 +77,3 @@ Invoked when the user wants to go/navigate up.
 <a name="KeyboardDirection+navigationAxis"></a>
+
 ### keyboardDirection.navigationAxis : <code>string</code>
@@ -72,0 +80,0 @@ Indicates the direction of permitted navigation with the keyboard.

docs/KeyboardPagedSelection.md

 # API Documentation
 <a name="KeyboardPagedSelection"></a>
+
 ## KeyboardPagedSelection
@@ -34,2 +35,3 @@ Mixin which maps page keys (Page Up, Page Down) into operations that move
 <a name="KeyboardPagedSelection+pageDown"></a>
+
 ### keyboardPagedSelection.pageDown()
@@ -40,2 +42,3 @@ Scroll down one page.
 <a name="KeyboardPagedSelection+pageUp"></a>
+
 ### keyboardPagedSelection.pageUp()
@@ -46,2 +49,3 @@ Scroll up one page.
 <a name="KeyboardPagedSelection+scrollTarget"></a>
+
 ### keyboardPagedSelection.scrollTarget : <code>HTMLElement</code>
@@ -48,0 +52,0 @@ The element that should be scrolled with the Page Up/Down keys.

docs/KeyboardPrefixSelection.md

 # API Documentation
 <a name="KeyboardPrefixSelection"></a>
+
 ## KeyboardPrefixSelection
@@ -41,2 +42,3 @@ Mixin that handles list box-style prefix typing, in which the user can type
 <a name="KeyboardPrefixSelection+selectItemWithTextPrefix"></a>
+
 ### keyboardPrefixSelection.selectItemWithTextPrefix(prefix)
@@ -43,0 +45,0 @@ Select the first item whose text content begins with the given prefix.

docs/microtask.md

 # API Documentation
 <a name="microtask"></a>
+
 ## microtask(callback)
@@ -4,0 +5,0 @@ Add a callback to the microtask queue.

docs/ObserveContentChanges.md

 # API Documentation
 <a name="ObserveContentChanges"></a>
+
 ## ObserveContentChanges
@@ -32,2 +33,3 @@ Mixin which wires up mutation observers to report any changes in a
 <a name="ObserveContentChanges.event_content-changed"></a>
+
 ### "content-changed"
@@ -39,2 +41,3 @@ This event is raised when the component's contents (including distributed
 <a name="ObserveContentChanges+contentChanged"></a>
+
 ### observeContentChanges.contentChanged()
@@ -41,0 +44,0 @@ Invoked when the contents of the component (including distributed

docs/OpenClose.md

 # API Documentation
 <a name="OpenClose"></a>
+
 ## OpenClose
@@ -21,2 +22,3 @@ Mixin which adds close/open semantics.
 <a name="OpenClose+close"></a>
+
 ### openClose.close()
@@ -29,2 +31,3 @@ Close the component.
 <a name="OpenClose+closed"></a>
+
 ### openClose.closed : <code>boolean</code>
@@ -36,2 +39,3 @@ True if the component is curently closed.
 <a name="OpenClose+open"></a>
+
 ### openClose.open()
@@ -44,2 +48,3 @@ Open the component.
 <a name="OpenClose+render"></a>
+
 ### openClose.render(closing)
@@ -59,2 +64,3 @@ Perform custom rendering of the close/open transition.
 <a name="OpenClose+toggle"></a>
+
 ### openClose.toggle()
@@ -61,0 +67,0 @@ Toggle the component's open/closed state.

docs/renderArrayAsElements.md

 # API Documentation
 <a name="renderArrayAsElements"></a>
+
 ## renderArrayAsElements(items, container, renderItem)
@@ -4,0 +5,0 @@ Helper function for rendering an array of items as elements.

docs/SelectionAriaActive.md

 # API Documentation
 <a name="SelectionAriaActive"></a>
+
 ## SelectionAriaActive
@@ -4,0 +5,0 @@ Mixin which treats the selected item in a list as the active item in ARIA

docs/SelectionHighlight.md

 # API Documentation
 <a name="SelectionHighlight"></a>
+
 ## SelectionHighlight
@@ -4,0 +5,0 @@ Mixin which applies standard highlight colors to a selected item.

docs/SelectionInView.md

 # API Documentation
 <a name="SelectionInView"></a>
+
 ## SelectionInView
@@ -22,2 +23,3 @@ Mixin which scrolls a container to ensure that a newly-selected item is
 <a name="SelectionInView+scrollItemIntoView"></a>
+
 ### selectionInView.scrollItemIntoView(item)
@@ -38,2 +40,3 @@ Scroll the given element completely into view, minimizing the degree of
 <a name="SelectionInView+scrollTarget"></a>
+
 ### selectionInView.scrollTarget : <code>HTMLElement</code>
@@ -40,0 +43,0 @@ The element that should be scrolled to bring an item into view.

docs/ShadowElementReferences.md

 # API Documentation
 <a name="ShadowElementReferences"></a>
+
 ## ShadowElementReferences
@@ -26,2 +27,3 @@ Mixin to create references to elements in a component's Shadow DOM subtree.
 <a name="$"></a>
+
 ## $ : <code>object</code>
@@ -28,0 +30,0 @@ The collection of references to the elements with IDs in a component's

docs/ShadowTemplate.md

 # API Documentation
 <a name="ShadowTemplate"></a>
+
 ## ShadowTemplate
@@ -4,0 +5,0 @@ Mixin for stamping a template into a Shadow DOM subtree upon component

docs/SwipeDirection.md

 # API Documentation
 <a name="SwipeDirection"></a>
+
 ## SwipeDirection
@@ -17,6 +18,6 @@ Mixin which maps touch gestures (swipe left, swipe right) to direction
     * [.goRight()](#SwipeDirection+goRight)
-    * [.position](#SwipeDirection+position) : <code>number</code>
-    * [.showTransition(value)](#SwipeDirection+showTransition)
+    * [.travelFraction](#SwipeDirection+travelFraction) : <code>number</code>
 
 <a name="SwipeDirection+goLeft"></a>
+
 ### swipeDirection.goLeft()
@@ -28,2 +29,3 @@ Invoked when the user wants to go/navigate left.
 <a name="SwipeDirection+goRight"></a>
+
 ### swipeDirection.goRight()
@@ -34,25 +36,8 @@ Invoked when the user wants to go/navigate right.
   **Kind**: instance method of <code>[SwipeDirection](#SwipeDirection)</code>
-<a name="SwipeDirection+position"></a>
-### swipeDirection.position : <code>number</code>
-The distance the user has moved the first touchpoint since the beginning
-of a drag, expressed as a fraction of the element's width.
+<a name="SwipeDirection+travelFraction"></a>
 
+### swipeDirection.travelFraction : <code>number</code>
+The distance the first touchpoint has traveled since the beginning of a
+drag, expressed as a fraction of the element's width.
+
   **Kind**: instance property of <code>[SwipeDirection](#SwipeDirection)</code>
-<a name="SwipeDirection+showTransition"></a>
-### swipeDirection.showTransition(value)
-Determine whether a transition should be shown during a swipe.
-
-Components like carousels often define animated CSS transitions for
-sliding effects. Such a transition should usually *not* be applied while
-the user is dragging, because a CSS animation will introduce a lag that
-makes the swipe feel sluggish. Instead, as long as the user is dragging
-with their finger down, the transition should be suppressed. When the
-user releases their finger, the transition can be restored, allowing the
-animation to show the carousel sliding into its final position.
-
-  **Kind**: instance method of <code>[SwipeDirection](#SwipeDirection)</code>
-
-| Param | Type | Description |
-| --- | --- | --- |
-| value | <code>boolean</code> | true if a component-provided transition should be shown, false if not. |
-

docs/TargetInCollective.md

 # API Documentation
 <a name="TargetInCollective"></a>
+
 ## TargetInCollective
@@ -17,2 +18,3 @@ Mixin which allows a component to provide aggregate behavior with other
 <a name="TargetInCollective+target"></a>
+
 ### targetInCollective.target : <code>HTMLElement</code>
@@ -19,0 +21,0 @@ Gets/sets the current target of the component.

docs/TargetSelection.md

 # API Documentation
 <a name="TargetSelection"></a>
+
 ## TargetSelection
@@ -36,5 +37,7 @@ Mixin which allows a component to delegate its own selection semantics to a
     * [.selectedItem](#TargetSelection+selectedItem) : <code>HTMLElement</code>
+    * [.selectionWraps](#TargetSelection+selectionWraps) : <code>boolean</code>
     * [.target](#TargetSelection+target) : <code>HTMLElement</code>
 
 <a name="TargetSelection+items"></a>
+
 ### targetSelection.items : <code>Array.&lt;HTMLElement&gt;</code>
@@ -45,2 +48,3 @@ The current set of items in the list.
 <a name="TargetSelection+itemsChanged"></a>
+
 ### targetSelection.itemsChanged()
@@ -53,2 +57,3 @@ This method is invoked when the underlying contents change. It is also
 <a name="TargetSelection+selectedIndex"></a>
+
 ### targetSelection.selectedIndex : <code>number</code>
@@ -60,2 +65,3 @@ The index of the item which is currently selected, or -1 if there is no
 <a name="TargetSelection+selectedItem"></a>
+
 ### targetSelection.selectedItem : <code>HTMLElement</code>
@@ -65,3 +71,11 @@ The currently selected item, or null if there is no selection.
   **Kind**: instance property of <code>[TargetSelection](#TargetSelection)</code>
+<a name="TargetSelection+selectionWraps"></a>
+
+### targetSelection.selectionWraps : <code>boolean</code>
+True if selection navigations wrap from last to first, and vice versa.
+
+  **Kind**: instance property of <code>[TargetSelection](#TargetSelection)</code>
+**Default**: <code>{false}</code>  
 <a name="TargetSelection+target"></a>
+
 ### targetSelection.target : <code>HTMLElement</code>
@@ -68,0 +82,0 @@ Gets/sets the target element to which this component will delegate

docs/TimerSelection.md

 # API Documentation
 <a name="TimerSelection"></a>
+
 ## TimerSelection
@@ -19,4 +20,6 @@ Mixin which provides for automatic timed changes in selection.
     * [.playing](#TimerSelection+playing) : <code>boolean</code>
+    * [.selectionTimerDuration](#TimerSelection+selectionTimerDuration) : <code>number</code>
 
 <a name="TimerSelection+pause"></a>
+
 ### timerSelection.pause()
@@ -27,2 +30,3 @@ Pause automatic progression of the selection.
 <a name="TimerSelection+play"></a>
+
 ### timerSelection.play()
@@ -33,2 +37,3 @@ Begin automatic progression of the selection.
 <a name="TimerSelection+playing"></a>
+
 ### timerSelection.playing : <code>boolean</code>
@@ -38,1 +43,9 @@ True if the selection is being automatically advanced.
   **Kind**: instance property of <code>[TimerSelection](#TimerSelection)</code>
+<a name="TimerSelection+selectionTimerDuration"></a>
+
+### timerSelection.selectionTimerDuration : <code>number</code>
+The time in milliseconds that will elapse after the selection changes
+before the selection will be advanced to the next item in the list.
+
+  **Kind**: instance property of <code>[TimerSelection](#TimerSelection)</code>
+**Default**: <code>5000 (5 seconds)</code>  

docs/toggleClass.md

 # API Documentation
 <a name="toggleClass"></a>
+
 ## toggleClass(element, className, [force])
@@ -4,0 +5,0 @@ Helper function for standard classList.toggle() behavior on old browsers,

docs/TrackpadDirection.md

 # API Documentation
 <a name="TrackpadDirection"></a>
+
 ## TrackpadDirection
@@ -32,5 +33,6 @@ Mixin which maps a horizontal trackpad swipe gestures (or horizontal mouse
     * [.goRight()](#TrackpadDirection+goRight)
-    * [.position](#TrackpadDirection+position) : <code>number</code>
+    * [.travelFraction](#TrackpadDirection+travelFraction) : <code>number</code>
 
 <a name="TrackpadDirection+goLeft"></a>
+
 ### trackpadDirection.goLeft()
@@ -42,2 +44,3 @@ Invoked when the user wants to go/navigate left.
 <a name="TrackpadDirection+goRight"></a>
+
 ### trackpadDirection.goRight()
@@ -48,4 +51,5 @@ Invoked when the user wants to go/navigate right.
   **Kind**: instance method of <code>[TrackpadDirection](#TrackpadDirection)</code>
-<a name="TrackpadDirection+position"></a>
-### trackpadDirection.position : <code>number</code>
+<a name="TrackpadDirection+travelFraction"></a>
+
+### trackpadDirection.travelFraction : <code>number</code>
 The distance the user has moved the first touchpoint since the beginning
@@ -52,0 +56,0 @@ of a trackpad/wheel operation, expressed as a fraction of the element's

es5globals.js

@@ -24,2 +24,3 @@ /*
 import ObserveContentChanges from './src/ObserveContentChanges';
+import SelectionAnimation from './src/SelectionAnimation';
 import SelectionAriaActive from './src/SelectionAriaActive';
@@ -58,2 +59,3 @@ import SelectionHighlight from './src/SelectionHighlight';
 window.Basic.ObserveContentChanges = ObserveContentChanges;
+window.Basic.SelectionAnimation = SelectionAnimation;
 window.Basic.SelectionAriaActive = SelectionAriaActive;
@@ -60,0 +62,0 @@ window.Basic.SelectionHighlight = SelectionHighlight;

package.json

 {
   "name": "basic-component-mixins",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Mixins for creating web components in plain JavaScript.",
@@ -5,0 +5,0 @@ "homepage": "https://component.kitchen",

README.md

@@ -276,2 +276,5 @@ # basic-component-mixins
   Typically used in conjunction with the DistributedChildren mixin.
+* [fractionalSelection](docs/fractionalSelection.md)
+  Helpers for components that support gradual transitions between selection
+  states.
 * [Generic](docs/Generic.md).
@@ -297,2 +300,4 @@ Lets a component easily disable standard, optional styling.
   Adds open/close semantics.
+* [SelectionAnimation](docs/SelectionAnimation.md).
+  Uses animation to show transitions between selection states.
 * [SelectionAriaActive](docs/SelectionAriaActive.md).
@@ -299,0 +304,0 @@ Treat the selected item in a list as the active item in ARIA accessibility

src/DirectionSelection.js

@@ -45,12 +45,26 @@ /* Exported function extends a base class with DirectionSelection. */
 
-    // Default implementations. These will typically be handled by other mixins.
+    // Default implementation. This will typically be handled by other mixins.
+    get selectedFraction() {
+      return super.selectedFraction;
+    }
+    set selectedFraction(value) {
+      if ('selectedFraction' in base.prototype) { super.selectedFraction = value; }
+    }
+
+    // Default implementation. This will typically be handled by other mixins.
     selectFirst() {
       if (super.selectFirst) { return super.selectFirst(); }
     }
+
+    // Default implementation. This will typically be handled by other mixins.
     selectLast() {
       if (super.selectLast) { return super.selectLast(); }
     }
+
+    // Default implementation. This will typically be handled by other mixins.
     selectNext() {
       if (super.selectNext) { return super.selectNext(); }
     }
+
+    // Default implementation. This will typically be handled by other mixins.
     selectPrevious() {
@@ -60,2 +74,11 @@ if (super.selectPrevious) { return super.selectPrevious(); }
 
+    // Map drag travel fraction to selection fraction.
+    get travelFraction() {
+      return super.travelFraction;
+    }
+    set travelFraction(value) {
+      if ('travelFraction' in base.prototype) { super.travelFraction = value; }
+      this.selectedFraction = value;
+    }
+
   }
@@ -62,0 +85,0 @@

src/ItemsSelection.js

@@ -99,6 +99,7 @@ import microtask from './microtask';
     /**
-     * The index of the item which is currently selected, or -1 if there is no
-     * selection.
+     * The index of the item which is currently selected.
      *
-     * Setting the index to -1 deselects any current-selected item.
+     * If `selectionWraps` is false, the index is -1 if there is no selection.
+     * In that case, setting the index to -1 will deselect any
+     * currently-selected item.
      *
@@ -229,2 +230,17 @@ * @type {number}
     /**
+     * True if selection navigations wrap from last to first, and vice versa.
+     *
+     * @type {boolean}
+     * @default {false}
+     */
+    get selectionWraps() {
+      return this._selectionWraps || false;
+    }
+    set selectionWraps(value) {
+      if ('selectionWraps' in base.prototype) { super.selectionWraps = value; }
+      this._selectionWraps = String(value) === 'true';
+      updatePossibleNavigations(this);
+    }
+
+    /**
      * Fires when the selectedItem property changes.
@@ -265,3 +281,3 @@ *
       // longer a selection.
-      this.selectedItem = null;
+      element.selectedItem = null;
     }
@@ -274,3 +290,12 @@ }
 function selectIndex(element, index) {
-  let boundedIndex = Math.max(Math.min(index, element.items.length - 1), 0);
+  let count = element.items.length;
+  let boundedIndex;
+  if (element.selectionWraps) {
+    // JavaScript mod doesn't handle negative numbers the way we want to wrap.
+    // See http://stackoverflow.com/a/18618250/76472
+    boundedIndex = ((index % count) + count) % count;
+  } else {
+    // Keep index within bounds of array.
+    boundedIndex = Math.max(Math.min(index, count - 1), 0);
+  }
   let previousIndex = element.selectedIndex;
@@ -295,2 +320,6 @@ if (previousIndex !== boundedIndex) {
     canSelectPrevious = false;
+  } if (element.selectionWraps) {
+    // Since there are items, can always go next/previous.
+    canSelectNext = true;
+    canSelectPrevious = true;
   } else {
@@ -297,0 +326,0 @@ let index = element.selectedIndex;

src/SwipeDirection.js

@@ -18,4 +18,12 @@ /* Exported function extends a base class with SwipeDirection. */
 
-      this.position = 0;
+      // For the component to receive PointerEvents in IE/Edge, we need to set
+      // touch-action: none. Only make this change if touch-action is currently
+      // the default value ("auto"), in case the developer knows better than we
+      // do what they want in their particular context.
+      if (getComputedStyle(this).touchAction === 'auto') {
+        this.style.touchAction = 'none';
+      }
 
+      this.travelFraction = 0;
+
       // TODO: Touch events could be factored out into its own mixin.
@@ -101,34 +109,23 @@
 
-    /**
-     * The distance the user has moved the first touchpoint since the beginning
-     * of a drag, expressed as a fraction of the element's width.
-     *
-     * @type number
-     */
-    get position() {
-      return this._position;
+    // Default implementation.
+    get showTransition() {
+      return super.showTransition;
     }
-    set position(position) {
-      if ('position' in base.prototype) { super.position = position; }
-      this._position = position;
+    set showTransition(value) {
+      if ('showTransition' in base.prototype) { super.showTransition = value; }
     }
 
     /**
-     * Determine whether a transition should be shown during a swipe.
+     * The distance the first touchpoint has traveled since the beginning of a
+     * drag, expressed as a fraction of the element's width.
      *
-     * Components like carousels often define animated CSS transitions for
-     * sliding effects. Such a transition should usually *not* be applied while
-     * the user is dragging, because a CSS animation will introduce a lag that
-     * makes the swipe feel sluggish. Instead, as long as the user is dragging
-     * with their finger down, the transition should be suppressed. When the
-     * user releases their finger, the transition can be restored, allowing the
-     * animation to show the carousel sliding into its final position.
-     *
-     * @param {boolean} value - true if a component-provided transition should
-     * be shown, false if not.
+     * @type number
      */
-    // TODO: Rename (and flip meaning) to something like dragging()?
-    showTransition(value) {
-      if (super.showTransition) { super.showTransition(value); }
+    get travelFraction() {
+      return this._travelFraction;
     }
+    set travelFraction(value) {
+      if ('travelFraction' in base.prototype) { super.travelFraction = value; }
+      this._travelFraction = value;
+    }
 
@@ -149,3 +146,3 @@ }
 function touchStart(element, clientX, clientY) {
-  element.showTransition(false);
+  element.showTransition = false;
   element._startX = clientX;
@@ -181,23 +178,20 @@ element._previousX = clientX;
 function touchEnd(element, clientX, clientY) {
-  element.showTransition(true);
+  element.showTransition = true;
   if (element._deltaX >= 20) {
     // Finished going right at high speed.
-    // console.log("flick right " + element._deltaX);
     element.goLeft();
   } else if (element._deltaX <= -20) {
     // Finished going left at high speed.
-    // console.log("flick left " + element._deltaX);
     element.goRight();
   } else {
     // Finished at low speed.
-    // console.log("slow drag " + element._deltaX);
     trackTo(element, clientX);
-    let position = element.position;
-    if (position >= 0.5) {
+    let travelFraction = element.travelFraction;
+    if (travelFraction >= 0.5) {
       element.goRight();
-    } else if (position <= -0.5) {
+    } else if (travelFraction <= -0.5) {
       element.goLeft();
     }
   }
-  element.position = 0;
+  element.travelFraction = 0;
   element._deltaX = null;
@@ -213,3 +207,3 @@ element._deltaY = null;
     0;
-  element.position = fraction;
+  element.travelFraction = fraction;
 }

src/TargetSelection.js

@@ -94,2 +94,20 @@ /* Exported function extends a base class with TargetSelection. */
     /**
+     * True if selection navigations wrap from last to first, and vice versa.
+     *
+     * @type {boolean}
+     * @default {false}
+     */
+    get selectionWraps() {
+      let target = this.target;
+      return target && target.selectionWraps;
+    }
+    set selectionWraps(value) {
+      if ('selectionWraps' in base.prototype) { super.selectionWraps = value; }
+      let target = this.target;
+      if( target) {
+        target.selectionWraps = value;
+      }
+    }
+
+    /**
      * Gets/sets the target element to which this component will delegate
@@ -96,0 +114,0 @@ * selection actions.

src/TimerSelection.js

@@ -0,1 +1,6 @@
+import createSymbol from './createSymbol';
+
+const selectionTimerDurationSymbol = createSymbol('selectionTimerDuration');
+
+
 /* Exported function extends a base class with TimerSelection. */
@@ -57,8 +62,8 @@ export default (base) => {
     /*
-     * When the selected item changes (because of something this mixin did,
-     * or was changed by an outside agent like the user), we wait a bit before
-     * advancing to the next item. By triggering the next item this way,
-     * we implicitly get a desirable behavior: if the user changes the selection
-     * (e.g., in a carousel), we let them see that selection state for a while
-     * before advancing the selection ourselves.
+     * When the selected item changes (because of something this mixin did, or
+     * was changed by an outside agent like the user), we wait before advancing
+     * to the next item. By triggering the next item this way, we implicitly get
+     * a desirable behavior: if the user changes the selection (e.g., in a
+     * carousel), we let them see that selection state for a while before
+     * advancing the selection ourselves.
      */
@@ -76,2 +81,17 @@ get selectedItem() {
 
+    /**
+     * The time in milliseconds that will elapse after the selection changes
+     * before the selection will be advanced to the next item in the list.
+     *
+     * @type {number} - Time in milliseconds
+     * @default 5000 (5 seconds)
+     */
+    get selectionTimerDuration() {
+      return super.selectionTimerDuration || this[selectionTimerDurationSymbol] || 5000;
+    }
+    set selectionTimerDuration(value) {
+      if ('selectionTimerDuration' in base.prototype) { super.selectionTimerDuration = value; }
+      this[selectionTimerDurationSymbol] = value;
+    }
+
   }
@@ -93,3 +113,3 @@
     selectNextWithWrap(element);
-  }, 2000);
+  }, element.selectionTimerDuration);
 }
@@ -96,0 +116,0 @@

src/TrackpadDirection.js

@@ -57,2 +57,10 @@ /* Exported function extends a base class with TrackpadDirection. */
 
+    // Default implementation.
+    get showTransition() {
+      return super.showTransition;
+    }
+    set showTransition(value) {
+      if ('showTransition' in base.prototype) { super.showTransition = value; }
+    }
+
     /**
@@ -65,14 +73,9 @@ * The distance the user has moved the first touchpoint since the beginning
      */
-    get position() {
-      return super.position;
+    get travelFraction() {
+      return super.travelFraction;
     }
-    set position(position) {
-      if ('position' in base.prototype) { super.position = position; }
+    set travelFraction(value) {
+      if ('travelFraction' in base.prototype) { super.travelFraction = value; }
     }
 
-    // Default implementation
-    showTransition(value) {
-      if (super.showTransition) { super.showTransition(value); }
-    }
-
   }
@@ -94,3 +97,3 @@
 function postNavigate(element) {
-  element.position = 0;
+  element.travelFraction = 0;
   element._wheelDistance = 0;
@@ -106,3 +109,3 @@ element._postNavigateDelayComplete = true;
 function resetWheelTracking(element) {
-  element.position = 0;
+  element.travelFraction = 0;
   element._wheelDistance = 0;
@@ -188,21 +191,21 @@ element._lastDeltaX = 0;
 
-  // Update the position of the items being navigated.
+  // Update the travel fraction of the element being navigated.
   let width = element.offsetWidth;
-  let position = width > 0 ?
+  let travelFraction = width > 0 ?
     element._wheelDistance / width :
     0;
-  element.showTransition(false);
-  position = sign(position) * Math.min(Math.abs(position), 1);
-  element.position = position;
+  element.showTransition = false;
+  travelFraction = sign(travelFraction) * Math.min(Math.abs(travelFraction), 1);
+  element.travelFraction = travelFraction;
 
   // If the user has dragged enough to reach the previous/next item, then
   // complete a navigation to that item.
-  if (position === 1) {
+  if (travelFraction === 1) {
     // console.log("goRight");
-    element.showTransition(true);
+    element.showTransition = true;
     element.goRight();
     postNavigate(element);
-  } else if (position === -1) {
+  } else if (travelFraction === -1) {
     // console.log("goLeft");
-    element.showTransition(true);
+    element.showTransition = true;
     element.goLeft();
@@ -221,8 +224,8 @@ postNavigate(element);
   // Snap to the closest item.
-  element.showTransition(true);
-  let position = element.position;
-  if (position >= 0.5) {
+  element.showTransition = true;
+  let travelFraction = element.travelFraction;
+  if (travelFraction >= 0.5) {
     // console.log("snap right");
     element.goRight();
-  } else if (position <= -0.5) {
+  } else if (travelFraction <= -0.5) {
     // console.log("snap left");
@@ -229,0 +232,0 @@ element.goLeft();

test/ItemsSelection.tests.js

@@ -72,2 +72,22 @@ import { assert } from 'chai';
 
+  it("can advance the selection to the next item", () => {
+    let element = createSampleElement();
+    assert.equal(element.selectedIndex, -1);
+    element.selectNext();
+    assert.equal(element.selectedIndex, 0);
+    element.selectNext();
+    element.selectNext();
+    assert.equal(element.selectedIndex, 2);
+    element.selectNext(); // Moving past last item should have no effect.
+    assert.equal(element.selectedIndex, 2);
+  });
+
+  it("can wrap the selection from the last to the first item", () => {
+    let element = createSampleElement();
+    element.selectionWraps = true;
+    element.selectedIndex = 2;
+    element.selectNext();
+    assert.equal(element.selectedIndex, 0);
+  });
+
 });
@@ -74,0 +94,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

824764

increased by21.7%

Number of package files

92

increased by8.24%

Lines of code

10946

increased by22.37%

Number of lines in readme file

367

increased by1.38%

No dependency changes