|
| 1 | +import type NativeArray from '@ember/array/-private/native-array'; |
| 2 | +import type SortRule from '../../lib/SortRule'; |
| 3 | + |
| 4 | +import Component from '@ember/component'; |
| 5 | +import { layout, tagName } from '@ember-decorators/component'; |
| 6 | +import { action, computed, set } from '@ember/object'; |
| 7 | +import { A, isArray } from '@ember/array'; |
| 8 | +import { next } from '@ember/runloop'; |
| 9 | + |
| 10 | +import { SortOrder } from '../../constants'; |
| 11 | +import { sortArrayWithRules } from '../../utils'; |
| 12 | +import template from './template'; |
| 13 | + |
| 14 | +/** |
| 15 | + * |
| 16 | + */ |
| 17 | +function defaultSortDescription(rules: SortRule[]) { |
| 18 | + if (!rules.length) { |
| 19 | + return 'No sorting has been applied'; |
| 20 | + } |
| 21 | + |
| 22 | + const messages = rules |
| 23 | + .map((rule) => (rule.enabled ? `${rule.displayName} ${rule.direction}` : null)) |
| 24 | + .filter(Boolean); |
| 25 | + |
| 26 | + return `Sorted on ${messages.join(', ')}`; |
| 27 | +} |
| 28 | + |
| 29 | +/** |
| 30 | + * The UiSorter provides an easy mechanism for multidimensional sorting of a recordset. |
| 31 | + * |
| 32 | + * ```handlebars |
| 33 | + * {{!-- This example shows a table whose Last Name column is sortable --}} |
| 34 | + * |
| 35 | + * <UiSorter @records={{this.records}} as |Sorter|> |
| 36 | + * <p>{{Sorter.description}}</p> |
| 37 | + * |
| 38 | + * <table class="table"> |
| 39 | + * <thead> |
| 40 | + * <tr> |
| 41 | + * <th>First Name</th> |
| 42 | + * |
| 43 | + * <Sorter.Criterion @sortOn="lastName" as |Criterion|> |
| 44 | + * <th onclick={{Criterion.cycleDirection}} aria-sort="{{Criterion.direction}}"> |
| 45 | + * {{if Criterion.index (concat Criterion.index '. ')}} |
| 46 | + * Last Name |
| 47 | + * <UiIcon @name={{Criterion.iconClass}} /> |
| 48 | + * </th> |
| 49 | + * </Sorter.Criterion> |
| 50 | + * </tr> |
| 51 | + * </thead> |
| 52 | + * |
| 53 | + * <tbody> |
| 54 | + * {{#each Sorter.sortedRecords as |record|}} |
| 55 | + * <tr> |
| 56 | + * <td>{{record.firstName}}</td> |
| 57 | + * <td>{{record.lastName}}</td> |
| 58 | + * </tr> |
| 59 | + * {{/each}} |
| 60 | + * </tbody> |
| 61 | + * </table> |
| 62 | + * </UiSorter> |
| 63 | + * ``` |
| 64 | + * |
| 65 | + * ## Sort Criterion |
| 66 | + * The workhorse of the UiSorter is the `Criterion` component which is yielded in the UiSorter's |
| 67 | + * block. This is a tagless component, and is intended to be wrapped around a button or whatever |
| 68 | + * other interactive element is to be used. |
| 69 | + * |
| 70 | + * The `@sortOn` attribute is always required. This is the property name of the objects within |
| 71 | + * the target recordset whose value will be sorted on. |
| 72 | + * |
| 73 | + * ```handlebars |
| 74 | + * <Sorter.Criterion @sortOn="lastName" as |Criterion|> |
| 75 | + * {{!-- --}} |
| 76 | + * </Sorter.Criterion> |
| 77 | + * ``` |
| 78 | + * |
| 79 | + * ### Pre-sorting |
| 80 | + * By default, the order that the recordset is provided in will be the same order that the yielded |
| 81 | + * `sortedRecords` array will have as all sort criterion default their sort direction to "none". |
| 82 | + * |
| 83 | + * It is possible to request a default sort that will be applied when the component renders by |
| 84 | + * providing the `@direction` attribute with a string of either "ascending" or "descending". |
| 85 | + * |
| 86 | + * ```handlebars |
| 87 | + * <Sorter.Criterion @sortOn="lastName" @direction="ascending" as |Criterion|> |
| 88 | + * {{!-- --}} |
| 89 | + * </Sorter.Criterion> |
| 90 | + * ``` |
| 91 | + * |
| 92 | + * ### Sub-sorting |
| 93 | + * Second, third, to _N_-th order child sorts can be provided with the `@subSortOn` attributes. |
| 94 | + * |
| 95 | + * Imagine a long list of names where many of the last names were all _"Smith"_. It might be convenient |
| 96 | + * to end-users to automatically sort on first names after the round of last name sorting so that |
| 97 | + * all of the _"Smith"_ records are easier to scan. |
| 98 | + * |
| 99 | + * ```handlebars |
| 100 | + * <Sorter.Criterion @sortOn="lastName" @subSortOn="firstName" as |Criterion|> |
| 101 | + * {{!-- --}} |
| 102 | + * </Sorter.Criterion> |
| 103 | + * ``` |
| 104 | + * |
| 105 | + * Multiple values can be provided to the `@subSortOn` attribute by providing a comma separated list. E.g. |
| 106 | + * `@subSortOn="firstName,middleName,phoneNumber"`. Sorts will be processed in the order that they are |
| 107 | + * provided. |
| 108 | + * |
| 109 | + * By default, the direction of all sub-sorts follow the direction of the primary sort. If the direction |
| 110 | + * of the sub-sort needs to be fixed, then there is a `@subSortDirection` attribute for that. |
| 111 | + * |
| 112 | + * ```handlebars |
| 113 | + * <Sorter.Criterion @sortOn="lastName" @subSortOn="firstName" @subSortDirection="ascending" as |Criterion|> |
| 114 | + * {{!-- --}} |
| 115 | + * </Sorter.Criterion> |
| 116 | + * ``` |
| 117 | + * |
| 118 | + * Multiple `@subSortDirection` values can be provided via a comma separated list, and are mapped to each |
| 119 | + * `@subSortOn` in the order they are provided. |
| 120 | + */ |
| 121 | +@tagName('') |
| 122 | +@layout(template) |
| 123 | +export default class UiSorter extends Component { |
| 124 | + public static readonly positionalParams = ['records']; |
| 125 | + |
| 126 | + /** |
| 127 | + * The array of objects that will be sorted. Sort operations do not mutate this array. |
| 128 | + */ |
| 129 | + public declare records: unknown[]; |
| 130 | + |
| 131 | + /** |
| 132 | + * The method that is used to generate descriptive text for the state of the sort for |
| 133 | + * assistive technologies. It receives, as an argument, an array containing active |
| 134 | + * SortRule instances and must return a string. |
| 135 | + */ |
| 136 | + public createDescription: (rules: SortRule[]) => string = defaultSortDescription; |
| 137 | + |
| 138 | + protected ruleSet: NativeArray<SortRule> = A([]); |
| 139 | + |
| 140 | + @computed('ruleSet.[]', 'ruleSet.@each.{displayName,direction}') |
| 141 | + protected get description() { |
| 142 | + return this.createDescription(this.ruleSet); |
| 143 | + } |
| 144 | + |
| 145 | + @computed( |
| 146 | + 'records.[]', |
| 147 | + 'ruleSet.[]', |
| 148 | + 'ruleSet.@each.{sortOn,direction,subSortOn,subSortDirection}' |
| 149 | + ) |
| 150 | + protected get sortedRecords() { |
| 151 | + return isArray(this.records) ? sortArrayWithRules(this.records, this.ruleSet) : []; |
| 152 | + } |
| 153 | + |
| 154 | + // eslint-disable-next-line ember/classic-decorator-hooks |
| 155 | + init() { |
| 156 | + super.init(); |
| 157 | + |
| 158 | + // Cannot pin down why, but on first render the `description` property is |
| 159 | + // being computed before any rules are pushed in, but not being recomputed |
| 160 | + // after. Oddly enough `sortedRecords` is being recomputed, but the two |
| 161 | + // display different behavior even will the exact same dependent keys. |
| 162 | + next(this, 'notifyPropertyChange', 'description'); |
| 163 | + } |
| 164 | + |
| 165 | + @action |
| 166 | + handleRuleUpdated(rule: SortRule) { |
| 167 | + // The rule was turned off, remove it |
| 168 | + if (!rule.enabled) { |
| 169 | + this.ruleSet.removeObject(rule); |
| 170 | + set(rule, 'index', undefined); |
| 171 | + } |
| 172 | + // The rule was just turned on, add it to the end of the list |
| 173 | + else if (rule.previousDirection === SortOrder.NONE) { |
| 174 | + this.ruleSet.addObject(rule); |
| 175 | + } |
| 176 | + |
| 177 | + // Re-index all remaining rules |
| 178 | + this.ruleSet.forEach((item, idx) => set(item, 'index', idx + 1)); |
| 179 | + } |
| 180 | +} |
0 commit comments