Add options page to docs (#402)

.github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: Lint, test, build
+name: build
 
 on: [pull_request]
 

apps/website/docs/adding-removing.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 8
+sidebar_position: 9
 ---
 
 # Adding and removing items

apps/website/docs/advanced-filters.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Advanced filters

apps/website/docs/alternatives.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 12
 ---
 
 # Alternatives

apps/website/docs/api.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 # API
@@ -17,6 +17,10 @@ Filters all the shuffle items and then sorts them.
 
 Sorts the currently filtered shuffle items.
 
+Calling sort with an empty object will reset the elements to DOM order.
+
+See the [SortOptions](./configuration.md#sorting-object) for the available properties.
+
 ## `update(options?)`
 
 Repositions everything. Useful for when dimensions (like the window size) change.

apps/website/docs/changelog.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 15
 ---
 
 # Changelog (abbreviated)

apps/website/docs/configuration.md

@@ -0,0 +1,159 @@
+---
+sidebar_position: 4
+---
+
+# Configuring Shuffle
+
+Here are the options you can change, as well as their defaults. The `Shuffle.options` property contains all the defaults.
+
+No options _need_ to be specified, but `itemSelector` should be used. Other common options to change are `speed` and `sizer`.
+
+## Options
+
+### `buffer` [number]
+
+Default: `0`
+
+Useful for percentage based heights when they might not always be exactly the same (in pixels).
+
+### `columnThreshold` [number]
+
+Default: `0.01`
+
+Reading the width of elements isn't precise enough and can cause columns to jump between values.
+
+### `columnWidth` [number | (conatinerWidth: number) => number]
+
+Default: `0`
+
+A static number or function that returns a number which determines how wide the columns are (in pixels).
+
+### `delimiter` [string | null]
+
+Default: `null`
+
+A static number or function that returns a number which determines how wide the columns are (in pixels).
+
+### `easing` [string]
+
+Default: `'cubic-bezier(0.4, 0.0, 0.2, 1)'`
+
+CSS easing function to use.
+
+### `filterMode` [Shuffle.FilterMode]
+
+Default: `Shuffle.FilterMode.ANY`
+
+Affects using an array with filter. e.g. `filter(['one', 'two'])`. With "any", the element passes the test if any of its groups are in the array. With "all", the element only passes if all groups are in the array.
+
+### `group` [string]
+
+Default: `Shuffle.ALL_ITEMS` (`"all"`)
+
+Initial filter group.
+
+### `gutterWidth` [number | (conatinerWidth: number) => number]
+
+Default: `0`
+
+A static number or function that determines how wide the gutters between columns are (in pixels).
+
+### `initialSort` [SortOptions | null]
+
+Default: `null`
+
+Shuffle can be initialized with a sort object. It is the same object given to the sort method.
+
+### `isCentered` [boolean]
+
+Default: `false`
+
+Whether to center grid items in the row with the leftover space.
+
+### `isRTL` [boolean]
+
+Default: `false`
+
+Whether to align grid items to the right in the row.
+
+### `itemSelector` [string]
+
+Default: `'*'`
+
+Query selector to find Shuffle items. e.g. '.picture-item'.
+
+### `roundTransforms` [boolean]
+
+Default: `true`
+
+Whether to round pixel values used in translate(x, y). This usually avoids blurriness.
+
+### `sizer` [HTMLElement | string | null]
+
+Default: `null`
+
+Element or selector string. Use an element to determine the size of columns and gutters.
+
+### `speed` [number]
+
+Default: `250`
+
+Transition/animation speed (milliseconds).
+
+### `staggerAmount` [number]
+
+Default: `15`
+
+Transition delay offset for each item in milliseconds.
+
+### `staggerAmountMax` [number]
+
+Default: `150`
+
+Maximum stagger delay in milliseconds. This caps the stagger amount so that it does not exceed the given value. Since the transition delay is incremented for each item in the grid, this is useful for large grids of items.
+
+### `useTransforms` [boolean]
+
+Default: `false`
+
+Whether to use absolute positioning instead of transforms.
+
+## Sorting object
+
+### `by` [(element: HTMLElement) => any]
+
+Default: `null`
+
+Sorting function which gives you the element each shuffle item is using by default.
+
+Returning `undefined` from the `by` function will reset the order to DOM order.
+
+### `compare` [(a: Shuffle.ShuffleItem, b: Shuffle.ShuffleItem) => number]
+
+Default: `null`
+
+Instead of using the simple `by` function, you can use the `compare` function provide a completely custom sorting function.
+
+:::tip
+
+See [Advanced sorting](./sorting.md#advanced-sorting) for usage.
+
+:::
+
+### `key` [keyof Shuffle.ShuffleItem]
+
+Default: `'element'`
+
+Determines which property of the `ShuffleItem` instance is passed to the `by` function.
+
+### `randomize` [boolean]
+
+Default: `false`
+
+If true, this will skip the sorting and return a randomized order in the array.
+
+### `reverse` [boolean]
+
+Default: `false`
+
+Use array.reverse() to reverse the results of your sort.

apps/website/docs/custom-styles.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 10
+sidebar_position: 11
 ---
 
 # Custom styles

apps/website/docs/events.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Events

apps/website/docs/faqs.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 13
+sidebar_position: 14
 ---
 
 # FAQs

apps/website/docs/filters.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Filters

apps/website/docs/sorting.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 6
+sidebar_position: 7
 ---
 
 # Sorting

apps/website/docs/supported-browsers.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 12
+sidebar_position: 13
 ---
 
 # Supported browsers

packages/shuffle/index.d.ts

@@ -22,15 +22,15 @@ export interface ShuffleOptions {
   columnThreshold?: number;
 
   /**
-   * A static number or function that returns a number which tells the plugin
+   * A static number or function that returns a number which determines
    * how wide the columns are (in pixels).
    */
-  columnWidth?: number;
+  columnWidth?: number | ((conatinerWidth: number) => number);
 
   /**
    * If your group is not json, and is comma delimited, you could set delimiter to ','.
    */
-  delimiter?: string;
+  delimiter?: string | null;
 
   /**
    * CSS easing function to use.
@@ -50,16 +50,16 @@ export interface ShuffleOptions {
   group?: string;
 
   /**
-   * A static number or function that tells the plugin how wide the gutters
+   * A static number or function that determines how wide the gutters
    * between columns are (in pixels).
    */
-  gutterWidth?: number;
+  gutterWidth?: number | ((conatinerWidth: number) => number);
 
   /**
-   * Shuffle can be isInitialized with a sort object. It is the same object
+   * Shuffle can be initialized with a sort object. It is the same object
    * given to the sort method.
    */
-  initialSort?: SortOptions;
+  initialSort?: SortOptions | null;
 
   /**
    * Whether to center grid items in the row with the leftover space.
@@ -112,16 +112,15 @@ export interface SortOptions {
   reverse?: boolean;
 
   // Sorting function which gives you the element each shuffle item is using by default.
-  by?: (a: Shuffle.ShuffleItem['element'], b: Shuffle.ShuffleItem['element']) => any;
+  by?: ((element: Shuffle.ShuffleItem['element']) => any) | null;
 
   // Custom sort function.
-  compare?: (a: Shuffle.ShuffleItem, b: Shuffle.ShuffleItem) => number;
+  compare?: ((a: Shuffle.ShuffleItem, b: Shuffle.ShuffleItem) => number) | null;
 
   // If true, this will skip the sorting and return a randomized order in the array.
   randomize?: boolean;
 
-  // Determines which property of each item in the array is passed to the
-  // sorting method. Only used if you use the `by` function.
+  // Determines which property of the `ShuffleItem` instance is passed to the `by` function.
   key?: keyof Shuffle.ShuffleItem;
 }
 

packages/shuffle/src/shuffle.js

@@ -1172,7 +1172,7 @@ Shuffle.options = {
   // jump between values.
   columnThreshold: 0.01,
 
-  // Shuffle can be isInitialized with a sort object. It is the same object
+  // Shuffle can be initialized with a sort object. It is the same object
   // given to the sort method.
   initialSort: null,
 

packages/shuffle/test/types/types.ts

@@ -38,7 +38,7 @@ shuffle.filter(function filterEachItem(element, shuffle) {
 const sortOptions: SortOptions = {
   randomize: true,
   reverse: false,
-  by: (element: Shuffle.ShuffleItem['element']) => element.dataset.reviews,
+  by: (element) => element.dataset.reviews,
   compare(a: Shuffle.ShuffleItem, b: Shuffle.ShuffleItem) {
     return 0;
   },