refactor: 💡 more resource filtering name changes

addons/core/addon/decorators/route-resource-filter.js

@@ -3,14 +3,16 @@ import { getOwner } from '@ember/application';
 import { typeOf } from '@ember/utils';
 
 /**
- *
+ * @param value
+ * @return {boolean} true if `value` is a function
  */
 const isFunction = (value) => typeOf(value) === 'function';
 
 /**
- *
+ * Represents a filter on a specific route and maintains filter state.
+ * @class
  */
-class ResourceFilter extends EmberObject {
+class RouteResourceFilter extends EmberObject {
   // =attributes
 
   route;
@@ -18,17 +20,22 @@ class ResourceFilter extends EmberObject {
   defaultValue;
   allowed;
   serialize;
-  deserialize;
+  findBySerialized;
+
+  // =computed
 
   /**
-   *
+   * Query parameter name where the selected value(s) for this filter are
+   * stored in the URL.
+   * @type {string}
    */
   get filterKey() {
     return `filter-${this.name}`;
   }
 
   /**
-   *
+   * The allowed values for this filter.  See `allowed`.
+   * @type {?array}
    */
   get allowedValues() {
     if (isFunction(this.allowed)) {
@@ -38,7 +45,9 @@ class ResourceFilter extends EmberObject {
   }
 
   /**
-   *
+   * Currently selected value(s) for this filter, deserialized from the value of
+   * the associated route query parameter.
+   * @type {?array}
    */
   get value() {
     const decodedValue =
@@ -54,10 +63,6 @@ class ResourceFilter extends EmberObject {
       : null;
     return deserializedValue;
   }
-
-  /**
-   *
-   */
   set value(value) {
     const queryParams = {};
     const serialized = value.map((value) => this.serializeValue(value));
@@ -68,7 +73,8 @@ class ResourceFilter extends EmberObject {
   // =methods
 
   /**
-   *
+   * Calls `serialize` (if set) on the passed value.  Otherwise returns the
+   * value unaltered.
    */
   serializeValue(value) {
     if (this.serialize) {
@@ -78,11 +84,16 @@ class ResourceFilter extends EmberObject {
   }
 
   /**
-   *
+   * Tests if `item` is represented by `serializedValue` when deserializing
+   * items from the query string.  If `findBySerialized` is unspecified,
+   * a simple equality test is used.
+   * @param item
+   * @param {string} serializedValue
+   * @return {boolean} item is represented by `serializedValue`
    */
   deserializeValue(item, serializedValue) {
-    if (this.deserialize) {
-      return this.deserialize(...arguments);
+    if (this.findBySerialized) {
+      return this.findBySerialized(...arguments);
     }
     return item === serializedValue;
   }
@@ -90,7 +101,12 @@ class ResourceFilter extends EmberObject {
   // =static methods
 
   /**
-   *
+   * Configures the specified route with a query parameter of `name` that, when
+   * changed, refreshes the route model and replaces history (rather than
+   * advancing history).
+   * @static
+   * @param {Route} routeClass
+   * @param {string} name
    */
   static setupRouteQueryParams(routeClass, name) {
     const filterKey = `filter-${name}`;
@@ -112,7 +128,15 @@ class ResourceFilter extends EmberObject {
   }
 
   /**
-   *
+   * Factory method to instantiate an instance of this class.
+   * @static
+   * @param {Route} routeInstance
+   * @param {string} name
+   * @param {array|function} allowed
+   * @param {?array} defaultValue
+   * @param {?function} serialize
+   * @param {?function} findBySerialized
+   * @return {RouteResourceFilter}
    */
   static getOrCreateRouteResourceFilter(
     routeInstance,
@@ -120,22 +144,22 @@ class ResourceFilter extends EmberObject {
     allowed,
     defaultValue,
     serialize,
-    deserialize
+    findBySerialized
   ) {
     const owner = getOwner(routeInstance);
     const containerKey = `route-resource-filter:${name}@${routeInstance.routeName}`;
     const factory = owner.factoryFor(containerKey);
     if (!factory) {
       // create factory
-      class RouteResourceFilter extends this {
+      class AppliedRouteResourceFilter extends this {
         route = routeInstance;
         name = name;
         allowed = allowed;
         defaultValue = defaultValue;
         serialize = serialize;
-        deserialize = deserialize;
+        findBySerialized = findBySerialized;
       }
-      owner.register(containerKey, RouteResourceFilter);
+      owner.register(containerKey, AppliedRouteResourceFilter);
     }
     const instance = owner.lookup(containerKey);
     return instance;
@@ -143,18 +167,18 @@ class ResourceFilter extends EmberObject {
 }
 
 /**
- * A resource filter param is a concise way to express a route query parameter.
+ * This decorator provides a concise way to express a route resource filter.
  * Resource filter params abstract away a route's query parameter
- * interface, treating a query param as a simple attribute on a route instance.
+ * interface, treating a query param as just an attribute on a route instance.
  * Getting the attribute value is equivalent to looking up the associated query
  * parameter.  Setting the attribute is equivalent to transitioning to the route
  * and passing the associated query parameter value.
  *
  * Additionally, resource filter params may declare `allowed`, an array
- * containing the set of values the parameter may take.  While unenforced,
- * `allowed` are useful metadata about a resource filter and may be fetch
- * via `ResourceFilterParamHelper`.  An optional default value may be specified
- * via `defaultValue` passed to the decorator.
+ * (or function returning an array) containing the set of values the parameter
+ * may take.  While unenforced, `allowed` are useful metadata about a resource
+ * filter and may be fetch via `ResourceFilterParamHelper`.  An optional default
+ * value may be specified via `defaultValue` passed to the decorator.
  *
  * @see ResourceFilterParamHelper
  *
@@ -162,7 +186,10 @@ class ResourceFilter extends EmberObject {
  *
  *   export default class MyRoute extends Route {
  *
- *     @resourceFilterParam(['active', 'pending'], ['active'])
+ *     @resourceFilterParam({
+ *       allowed: ['active', 'pending'],
+ *       defaultvalue: ['active'],         // optional
+ *     })
  *     status;
  *
  *     @action
@@ -180,7 +207,7 @@ export function resourceFilterParam({
   allowed,
   defaultValue,
   serialize,
-  deserialize,
+  findBySerialized,
 }) {
   /**
    * @param {object} target
@@ -189,7 +216,7 @@ export function resourceFilterParam({
    * @return {object{get, set}}
    */
   return function (target, name /*, descriptor*/) {
-    ResourceFilter.setupRouteQueryParams(target, name);
+    RouteResourceFilter.setupRouteQueryParams(target, name);
 
     let instance;
 
@@ -199,13 +226,13 @@ export function resourceFilterParam({
        * Returns the current value of the resource filter.
        */
       get() {
-        instance = ResourceFilter.getOrCreateRouteResourceFilter(
+        instance = RouteResourceFilter.getOrCreateRouteResourceFilter(
           this,
           name,
           allowed,
           defaultValue,
           serialize,
-          deserialize
+          findBySerialized
         );
         return instance.value;
       },

addons/core/addon/helpers/has-route-resource-filter-selections.js

@@ -11,11 +11,11 @@ import { action } from '@ember/object';
  *
  * @example
  *
- *   {{#if (has-resource-filter-param-selections 'route.name' 'field')}}
+ *   {{#if (has-route-resource-filter-selections 'route.name' 'field')}}
  *     Field has filter selections.
  *   {{/if}}
  */
-export default class HasResourceFilterParamSelectionsHelper extends Helper {
+export default class HasRouteResourceFilterSelectionsHelper extends Helper {
   // =services
 
   @service router;

addons/core/addon/helpers/route-resource-filter.js

@@ -11,11 +11,11 @@ import { action } from '@ember/object';
  *
  * @example
  *
- *   {{#with resource-filter-param 'status' as |param|}}
+ *   {{#with route-resource-filter 'status' as |param|}}
  *     {{param.name}} / {{param.value}} / {{param.selectedValue}}
  *   {{/with}}
  */
-export default class ResourceFilterParamHelper extends Helper {
+export default class RouteResourceFilterHelper extends Helper {
   // =services
 
   @service router;

addons/core/app/decorators/resource-filter-param.js

@@ -1 +0,0 @@
-export { default } from 'core/decorators/resource-filter-param';

addons/core/app/decorators/route-resource-filter.js

@@ -0,0 +1 @@
+export { default } from 'core/decorators/route-resource-filter';

addons/core/app/helpers/has-resource-filter-param-selections.js

@@ -1 +0,0 @@
-export { default } from 'core/helpers/has-resource-filter-param-selections';

addons/core/app/helpers/has-route-resource-filter-selections.js

@@ -0,0 +1 @@
+export { default } from 'core/helpers/has-route-resource-filter-selections';

addons/core/app/helpers/resource-filter-param.js

@@ -1 +0,0 @@
-export { default } from 'core/helpers/resource-filter-param';

addons/core/app/helpers/route-resource-filter.js

@@ -0,0 +1 @@
+export { default } from 'core/helpers/route-resource-filter';

ui/admin/app/routes/scopes/scope/auth-methods.js

@@ -4,7 +4,7 @@ import { action } from '@ember/object';
 import loading from 'ember-loading/decorator';
 import { confirm } from 'core/decorators/confirm';
 import { notifySuccess, notifyError } from 'core/decorators/notify';
-import { resourceFilterParam } from 'core/decorators/resource-filter-param';
+import { resourceFilterParam } from 'core/decorators/route-resource-filter';
 
 export default class ScopesScopeAuthMethodsRoute extends Route {
   // =services

ui/admin/app/routes/scopes/scope/sessions.js

@@ -6,7 +6,7 @@ import { task, timeout } from 'ember-concurrency';
 import { A } from '@ember/array';
 import { notifySuccess, notifyError } from 'core/decorators/notify';
 import config from '../../../config/environment';
-import { resourceFilterParam } from 'core/decorators/resource-filter-param';
+import { resourceFilterParam } from 'core/decorators/route-resource-filter';
 
 const POLL_TIMEOUT_SECONDS = config.sessionPollingTimeoutSeconds;
 
@@ -128,7 +128,7 @@ export default class ScopesScopeSessionsRoute extends Route {
     filterBy(field, value) {
       this[field] = value;
     }
-  
+
     /**
      * Clears and filter selections.
      */

ui/admin/app/templates/scopes/scope/auth-methods/index.hbs

@@ -39,7 +39,7 @@
     {{#if
       (or
         @model
-        (has-resource-filter-param-selections
+        (has-route-resource-filter-selections
           'scopes.scope.auth-methods' 'type'
         )
       )
@@ -47,7 +47,7 @@
       <Rose::Toolbar>
         <Rose::Form as |form|>
           {{#with
-            (resource-filter-param 'scopes.scope.auth-methods' 'type')
+            (route-resource-filter 'scopes.scope.auth-methods' 'type')
             as |filter|
           }}
             <Rose::Dropdown
@@ -76,7 +76,7 @@
           {{/with}}
 
           {{#if
-            (has-resource-filter-param-selections
+            (has-route-resource-filter-selections
               'scopes.scope.auth-methods' 'type'
             )
           }}
@@ -211,7 +211,7 @@
         </table.body>
       </Rose::Table>
 
-    {{else if (has-resource-filter-param-selections
+    {{else if (has-route-resource-filter-selections
       'scopes.scope.auth-methods' 'type'
     )}}
 

ui/admin/app/templates/scopes/scope/sessions/index.hbs

@@ -17,13 +17,13 @@
       {{#if
         (or
           @model
-          (has-resource-filter-param-selections 'scopes.scope.sessions' 'type')
+          (has-route-resource-filter-selections 'scopes.scope.sessions' 'type')
         )
       }}
         <Rose::Toolbar>
           <Rose::Form as |form|>
             {{#with
-              (resource-filter-param 'scopes.scope.sessions' 'status')
+              (route-resource-filter 'scopes.scope.sessions' 'status')
               as |filter|
             }}
               <Rose::Dropdown
@@ -52,7 +52,7 @@
             {{/with}}
 
             {{#if
-              (has-resource-filter-param-selections
+              (has-route-resource-filter-selections
                 'scopes.scope.sessions' 'type'
               )
             }}
@@ -139,7 +139,7 @@
         </table.body>
       </Rose::Table>
 
-    {{else if (has-resource-filter-param-selections
+    {{else if (has-route-resource-filter-selections
       'scopes.scope.sessions' 'type'
     )}}
       <Rose::Layout::Centered>

ui/desktop/app/routes/scopes/scope/projects/sessions.js

@@ -4,7 +4,7 @@ import { task, timeout } from 'ember-concurrency';
 import config from '../../../../config/environment';
 import { action } from '@ember/object';
 import { notifySuccess, notifyError } from 'core/decorators/notify';
-import { resourceFilterParam } from 'core/decorators/resource-filter-param';
+import { resourceFilterParam } from 'core/decorators/route-resource-filter';
 
 const POLL_TIMEOUT_SECONDS = config.sessionPollingTimeoutSeconds;
 
@@ -100,7 +100,7 @@ export default class ScopesScopeProjectsSessionsRoute extends Route {
     filterBy(field, value) {
       this[field] = value;
     }
-  
+
     /**
      * Clears and filter selections.
      */

ui/desktop/app/templates/scopes/scope/projects/sessions/index.hbs

@@ -13,7 +13,7 @@
       {{#if
         (or
           @model
-          (has-resource-filter-param-selections
+          (has-route-resource-filter-selections
             'scopes.scope.projects.sessions' 'type'
           )
         )
@@ -21,7 +21,7 @@
         <Rose::Toolbar>
           <Rose::Form as |form|>
             {{#with
-              (resource-filter-param 'scopes.scope.projects.sessions' 'status')
+              (route-resource-filter 'scopes.scope.projects.sessions' 'status')
               as |filter|
             }}
               <Rose::Dropdown
@@ -50,7 +50,7 @@
             {{/with}}
 
             {{#if
-              (has-resource-filter-param-selections
+              (has-route-resource-filter-selections
                 'scopes.scope.projects.sessions' 'type'
               )
             }}
@@ -142,7 +142,7 @@
           {{/each}}
         </table.body>
       </Rose::Table>
-    {{else if (has-resource-filter-param-selections
+    {{else if (has-route-resource-filter-selections
       'scopes.scope.projects.sessions' 'type'
     )}}
       <Rose::Layout::Centered>