@bsara/react-sort

@bsara/react-sort

A simple React component used for sorting collections and arrays.

Storybook

Changelog

Install

$ npm i --save @bsara/react-sort

Usage

import React from 'react';
import Sort from '@bsara/react-sort';
import { sort as timsort } from 'timsort';

const comparators = [
  { propPath: 'itemPropName1', type: 'string' },
  { propPath: 'itemPropName2', type: 'number' },
  { propPath: 'itemPropName3', type: 'date' },
  { propPath: 'itemPropName4', type: 'boolean' },

  {
    propPath: 'itemPropName5',
    options:  { myOptionProp: 42 },

    comparator(leftItem, rightItem, options) {
      // Perform comparison...
    }
  },

  function anotherComparator(leftItem, rightItem) {
    // Perform comparison...
  }
];

export default function MyComponent(props) {
  return (
    {/* ... */}

      <Sort
        items={props.items}
        sorter={timsort}
        comparators={comparators}
        render={(sortedItems) => (
          // Render sorted items...
        )} />

      {/* ...or... */}

      <Sort items={props.items}
            sorter={timsort}
            comparators={comparators}>
        {(sortedItems) => (
          // Render sorted items...
        )}
      </Sort>

    {/* ... */}
  );
}

Props

• items ?Array

  Array of items to be sorted and passed to render/children prop.

• render(sortedItems) or children(sortedItems) !Function - REQUIRED

  Render function (or function as child) called after items sorting is complete.

• ascending ?Boolean

  Default option to sort in ascending or descending order.

• nullsFirst ?Boolean

  Default option to sort with null values first or last.

• skip ?Boolean

  When true, skips sorting and the value of items prop will be passed to render, unsorted. This is useful in the case where sorting may only be conditionally needed.

• ignoreCache ?Boolean

  When true, a sort is forced even if none of the cached props have changed. This is useful when a custom comparator has been provided that depends on information outside of the given items prop.

• sorter(array, comparator) ?Function

  NOTE: If the sorter given does not return an Array, then it is assumed that the array that was given to the sorter was modified.

  Specifying a sorter function allows you to essential control the sorting algorithm used when a sort occurs within the component. By default, Array.prototype.sort is used if no sorter is specified or if sorter is null or undefined.

• comparator(leftItem, rightItem[, options]) ?Function

  NOTE: This prop takes precedence over the comparators prop and will cause the comparators prop to be ignored if this props is set to a non-null, non-undefined value.

  Comparator function to use when comparing the items found in the given items prop.

• comparators ?Array<(Function|Object)>

  IMPORTANT: When using this prop, it is assumed that all of the items given are objects and not primitive values like a string, boolean, date, or number.

  NOTE: This prop is ignored if the comparator prop is set to a non-null, non-undefined value.

  A list of comparators and/or comparator configurations to use when comparing the items found in the given items prop. The comparators/configurations are applied in the order that they are found in the comparators array given. If an item in the comparators list is a Function, then that function will just be called with "left" and "right" parameters passed to it (in that order as well). If an item in the comparators list is an Object, then it will be treated as a "configuration". For more information about said "configurations", refer to Comparator Config Properties below.

Comparator Configuration Properties

The comparator configuration objects can take one of two forms: either a comparator is given with some accompanying options, or a propPath and type are given and comparisons are taken care of for you by the Sort component. Below you will find two tables, each describes the properties available for one of the two configuration objects already described.

PropPath/Type Configuration Properties:

* = Required Property

Property Name/Type	Type	Default Value	Description
*propPath	String		Path to item property to compare.
*type	String		The type of the value found at propPath. Allowed Values: string, number, date, boolean
options	Object		Comparison options.
options.isAscending	Boolean	props.ascending	When true, items will be sorted in ascending order.
options.nullsFirst	Boolean	props.nullsFirst	When true, null and undefined items will be placed before any defined item.
options.localeIds	String		Only used when type is "string". See localeCompare docs for details.
options.usage	String		Only used when type is "string". See localeCompare docs for details.
options.localeMatcher	String		Only used when type is "string". See localeCompare docs for details.
options.numeric	Boolean		Only used when type is "string". See localeCompare docs for details.
options.caseFirst	String		Only used when type is "string". See localeCompare docs for details.
options.sensitivity	String		Only used when type is "string". See localeCompare docs for details.
options.ignorePunctuation	Boolean		Only used when type is "string". See localeCompare docs for details.

Comparator Configuration Properties:

* = Required Property

Property Name/Type	Type	Default Value	Description
*comparator	Function		Comparator function to use for comparisons. Function Signature: comparator(leftParam, rightParam, options)
options	Object		Comparison options. (NOTE: options will be passed to comparator as a 3rd function parameter)
options.isAscending	Boolean	props.ascending	When true, items will be sorted in ascending order.

License

ISC License (ISC)

Copyright (c) 2019, Brandon D. Sara (https://bsara.dev/)

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.