Updated comments on AppSearchDriver

README.md

@@ -71,7 +71,7 @@ You can follow the previous steps, but then you will need to configure
 [engine.json](src/config/engine.json).
 
 To do so, make a copy of [engine.json.example](src/config/engine.json.example),
-rename it to `engine.json` and configure with your Engine's specific details.
+rename it to `engine.json` and configure it with your Engine's specific details.
 
 ```bash
 cp src/config/engine.json.example src/config/engine.json
@@ -117,7 +117,14 @@ That corresponds to the code and file structure in the following way:
 
 **src/app-search**
 
-This holds the `AppSearchDriver`, the `URLManager`, and `AppSearchProvider`
+Everything in this directory for now should be thought of as a separate library.
+The goal eventually is to actually separate this out into a library of its own,
+so when composing a UI you'd simply need to focus on creating components
+from actions and state, and not all of the plumbing that goes into managing
+that state. For now though, it's included in this reference as a pattern
+that can be followed.
+
+This holds the `SearchDriver`, the `URLManager`, and `SearchProvider`
 from the diagram above. This is where all of the core application logic lives.
 The interface to all of this logic is a set of "actions" and "state" that are
 passed down in a React [Context](https://reactjs.org/docs/context.html). Those
@@ -158,13 +165,6 @@ So, for instance, a `SearchBox` component might be wired up to call the
 value. A `Results` component could then simply iterate through the `results`
 from state to render search results.
 
-Everything in this directory for now should be thought of as a separate library.
-The goal eventually is to actually separate this out into a library of it's own,
-so when composing a UI you'd simply need to focus on creating components
-from actions and state, and not all of the plumbing that goes into managing
-that state. For now though, it's included in this reference as a pattern
-that can be followed.
-
 **src/containers**
 
 Components in this UI are separated into "Containers" and "Components". These
@@ -195,16 +195,28 @@ It should be feasible to use this project as a starting point for your
 own implementation. Here are a few places to look to make changes:
 
 - The styles for the entire project can be found in [src/styles](src/styles).
- Simple style tweaks changes can be made here, or you could replace these styles
- with your own.
+ Simple style tweaks can be made here, or you could replace these styles
+ entirely with your own.
 - [src/components](src/components) contains the view templates for
  components. Structural HTML changes can be made here.
 - If you find that you have different data or behavior requirements for
  existing components, you can customize the component Containers in
  [src/containers](src/containers).
 - If you find you have requirements that none of the existing components
  satisfy, you could create an entirely new component and/or container. Use the
- `withAppSearch` HOC in order to access any action or state.
+ [withSearch.js](src/search-lib/withSearch.js) HOC in order to access any action or state.
+- The SearchDriver can be configured directly in [App.js](src/App.js) to do things like:
+
+ - Optimize your API calls
+ - Add additional facets and customize facet behavior
+ - Disable URL State management
+
+ A full list of configuration options can be found in [SearchDriver.js](src/search-lib/SearchDriver.js)
+
+- Eject from 'configuration'. You may choose to to delete the entire [src/config](src/config) directory, which holds the configuration logic that makes this a
+ generic UI. If you're using this as your own, production application, you likely
+ won't need this.
+
 - Lastly, if you find there is a core action or state missing, you may
  consider updating the core logic in [src/app-search](src/app-search).
 

src/app-search/AppSearchAPIConnector.js

@@ -1,8 +1,12 @@
 import * as SwiftypeAppSearch from "swiftype-app-search-javascript";
 
 /*
- * We mainly just need to filter out unsupported configuration values, like
- * `disjunctive`
+ * We simply pass our Facet configuration through to the App Search API
+ * call. There are, however, certain properties that the API does not
+ * support in that configuration. For that reason, we need to filter
+ * those properties out before passing them to the API.
+ *
+ * An example is 'disjunctive', and 'conditional'.
  */
 function toAPIFacetSyntax(facetConfig = {}) {
  return Object.entries(facetConfig).reduce((acc, [key, value]) => {
@@ -16,6 +20,12 @@ function toAPIFacetSyntax(facetConfig = {}) {
  }, {});
 }
 
+/*
+ * 'disjunctive' flags are embedded in individual facet configurations, like
+ * so:
+ *
+ * facets
+ */
 function getListOfDisjunctiveFacets(facetConfig = {}) {
  return Object.entries(facetConfig).reduce((acc, [key, value]) => {
  if (value && value.disjunctive === true) {

src/app-search/AppSearchDriver.js

@@ -39,18 +39,17 @@ function removeSingleFilterValue(filters, name, value) {
 }
 
 export const DEFAULT_STATE = {
- // Search Parameters -- This is state that represents the input that was
- // used to produce the current query results. It is always in sync
- // with the Results State
+ // Search Parameters -- This is state that represents the input state.
  current: 1,
- error: "",
  filters: [],
- isLoading: false,
  resultsPerPage: 20,
  searchTerm: "",
  sortDirection: "",
  sortField: "",
- // Results State -- This state represents the results of the current query
+ // Result State -- This state represents state that is updated automatically
+ // as the result of changing input state.
+ error: "",
+ isLoading: false,
  facets: {},
  requestId: "",
  results: [],
@@ -60,7 +59,7 @@ export const DEFAULT_STATE = {
 };
 
 /*
- * This temporarily fixes a core issue we have with filtering.
+ * This fixes an issue with filtering.
  * Our data structure for filters are the "OR" format for the App Search
  * API:
  *
@@ -83,9 +82,6 @@ export const DEFAULT_STATE = {
  * ]
  * }
  * ```
- *
- * Ultimately, we should choose our own data structures in the driver
- * that don't mirror the API. But they will need to support AND vs OR.
  */
 function formatORFiltersAsAND(filters = []) {
  return filters.reduce((acc, filter) => {
@@ -96,9 +92,9 @@ function formatORFiltersAsAND(filters = []) {
 }
 
 /*
- * There's this weird thing where facet values for dates come back as an integer
- * from the API, but the API expects them as parameters formatted as date
- * strings.
+ * Facet values for dates come back as Integer from the API. However, the API
+ * expects them as a formatted date String when applying that same value
+ * as a filter.
  */
 function convertRangeFiltersToDateString(filters = []) {
  const val = filters.map(filter => {
@@ -154,31 +150,78 @@ function matchFilter(filter1, filter2) {
  * it is the source of truth for state in this React App, but it has no
  * dependencies on React itself.
  *
- * The public interface of the Driver can be thought about in the following
- * way:
+ * The public interface of the Driver can be thought about as "state" and
+ * "actions."
  *
  * Ways to GET state:
  * - getState - Get the initial app state
- * - subscribeToStateChanges - Get updated state whenever it changes
+ * - subscribeToStateChanges - Get updated state whenever it changes.
+ *
+ * Ways to SET state, using actions. All actions can be found in 'getActions'.
+ *
+ * const {addFilter} = getActions().
+ *
+ * addFilter, and most actions, will typically update the state and trigger
+ * new queries to be run against the search API.
+ *
+ * Configuration:
+ *
+ * - apiConnector: APIConnector
+ * Instance of an API Connector. For instance, AppSearchAPIConnector
  *
- * Ways to SET state, or "Actions" as we refer to them elsewhere
- * - addFilter, etc, will typically update the state and trigger new queries
+ * - facetConfig: Facet
+ * Configuration for Facet filters to be used within this application. The
+ * syntax for Facet configuration follows the API syntax:
+ * https://swiftype.com/documentation/app-search/api/search/facets. In
+ * addition to the options provided by the API, the following per Facet
+ * configuration is also available:
+ * - conditional[function]
+ * This facet will only be applied if the condition specified returns
+ * true, based on the current applied filters.
+ * - disjunctive[boolean]
+ * When returning counts for disjunctive facets, the counts will be
+ * returned as if no filter is applied on this field, even if one is
+ * applied. A common use case for this is tabbed filters.
  *
+ * ex.
+ * facetConfig: {
+ * author: {
+ * type: "value",
+ * size: 40,
+ * disjunctive: true,
+ * conditional: ({ filters }) =>
+ * ["blog", "videos"].includes(filters.filter(f => f["website_area"]))
+ * }
+ * }
+ *
+ * - initialState: Object
+ * Set initial input state, or search parameters. For example, initializing
+ * the search page with certain parameters already set:
+ *`
+ * initialState: {
+ * searchTerm: "test",
+ * resultsPerPage: 40
+ * }
+ *
+ * Valid search parameters are:
+ * current: Integer
+ * filters: Array[Object]
+ * resultsPerPage: Integer
+ * searchTerm: String
+ * sortDirection: String ["asc"|"desc"]
+ * sortField: String
+ *
+ * - searchOptions: Object
+ * This is low level configuration which lets you configure
+ * the options used on the Search API endpoint, ex: `result_fields`.
+ * https://swiftype.com/documentation/app-search/api/search
+ *
+ * - trackURLState: Boolean
+ * URL State management can be disabled completely
  */
 export default class AppSearchDriver {
  state = DEFAULT_STATE;
 
- /**
- *
- * @param options Object
- * apiConnector - Connector for a particular search API
- * facetConfig - Configuration for facets, based on format specified in API documentation
- * initialState - This lets you set initial search parameters, ex:
- * `searchTerm: "test"`
- * searchOptions - A low level configuration which lets you configure
- * the options used on the Search API endpoint, ex: `result_fields`
- * trackURLState - Boolean, track state in the url or not?
- */
  constructor({
  apiConnector,
  facetConfig,