<commit_before># FilterGroups

<!-- md2toc -l 2 readme.md -->
* [Basic Usage](#basic-usage)
* [Overview](#overview)
    * [Filter configuration](#filter-configuration)
    * [Representation in the user-interface URL](#representation-in-the-user-interface-url)
* [The `initialFilterState` function](#the-initialfilterstate-function)
* [The `<FilterGroups>` component](#the-filtergroups-component)
    * [Properties](#properties)
* [The `filters2cql` function](#the-filters2cql-function)

This component renders a set of filter-groups, each of which pertains to a searchable field and contains a set of filters that indicate values required for that field.


## Basic Usage

```js
const filterConfig = [
  {
    label: 'Item Types',
    name: 'item',
    cql: 'materialType',
    values: ['Books', 'DVDs', 'Microfilm'],
    restrictWhenAllSelected: true,
  }, {
    label: 'Location',
    name: 'location',
    cql: 'location.name',
    values: [{ name: 'Main Library', cql: 'main' }, 'Annex Library'],
  },
];

this.state = {
  filters: initialFilterState(filterConfig, props.location.query.filters),
};

<FilterGroups config={filterConfig} filters={this.state.filters} />

const filterCql = filters2cql(filterConfig, filters);
```


## Overview

This library provides several utilities for initialising, rendering
and manipulating sets of filters, and deriving from them a query
expressed in CQL. The general approach is that a React component
declaratively specifies a set of filter groups, which is then uses in
several different contexts to drive different but related pieces of
code.

In order to make it easy to use without needing to make a lot of
decisions, this library is somewhat opinionated about state
representation. This state is set using a `transitionToParams` method,
and obtined using a `queryParam` method. There must both be provided
within the React component that uses `<FilterGroups>`.


### Filter configuration

The filter configuration is an array containing an ordered list of
filter groups. Each group is represented by an object with four keys:

* `label` -- The human-readable label that is used when presenting the
  group on a page.
* `name` -- The name used internally for the filter group, which may
  be short or opaque in meaning.
* `cql` -- The name of the CQL index that corresponds to the filter
  group, and which will be used in queries to find records that
  satisfy particular settings of the filters in the group. In general,
  this will be the name of a field, or maybe subfield, in the schema
  for the kind of records under consideration.
* `values` -- A list of the possible values that may be selected for
  the filter.
* `restrictWhenAllSelected` -- a boolean indicating how to behave when
  all the filters in the group are selected. By default, this is taken
  to mean no restriction is intended, and so that filter group makes
  no contribution to the query. However, if this is set true, then a
  query clause is always included. (See
  [STCOM-204](https://issues.folio.org/browse/STCOM-204) for
  rationale.)

Each of the `values` is typically represented by a simple string, which
is used both to display on the page and as the value to use in
queries. However, each value may optionally instead be an object
containing two keys:

* `name` -- the name used to display the filter on the page.
* `cql` -- the value used when generating CQL queries.

In the example above, there are two filter groups, "Item Types" and
"Location". All the values of the former are simple strings; one of
the values of the latter is of the more complex form, using "Main
Library" as the displayed value and just 'main' as the corresponding
value to use in searches.

Each filter value has a "full name", made up of the group name, a
period and the filter name itself. For example, in the configuration
above, the full names include `item.Books` and `location.Annex
Library`.

### Representation in the user-interface URL

The state of the filters is represented in the user-interface's URL as
a single query parameter, `filters`, whose value is a comma-separated
list of the full names of all selected filters. For example:


	http://example.com/users?filters=item.DVDs,item.Microfilm,location.Main+Library

<commit_msg>Update "Representation in UI URL" section<commit_after># FilterGroups

<!-- md2toc -l 2 readme.md -->
* [Basic Usage](#basic-usage)
* [Overview](#overview)
    * [Filter configuration](#filter-configuration)
    * [Representation in the user-interface URL](#representation-in-the-user-interface-url)
* [The `initialFilterState` function](#the-initialfilterstate-function)
* [The `<FilterGroups>` component](#the-filtergroups-component)
    * [Properties](#properties)
* [The `filters2cql` function](#the-filters2cql-function)

This component renders a set of filter-groups, each of which pertains to a searchable field and contains a set of filters that indicate values required for that field.


## Basic Usage

```js
const filterConfig = [
  {
    label: 'Item Types',
    name: 'item',
    cql: 'materialType',
    values: ['Books', 'DVDs', 'Microfilm'],
    restrictWhenAllSelected: true,
  }, {
    label: 'Location',
    name: 'location',
    cql: 'location.name',
    values: [{ name: 'Main Library', cql: 'main' }, 'Annex Library'],
  },
];

this.state = {
  filters: initialFilterState(filterConfig, props.location.query.filters),
};

<FilterGroups config={filterConfig} filters={this.state.filters} />

const filterCql = filters2cql(filterConfig, filters);
```


## Overview

This library provides several utilities for initialising, rendering
and manipulating sets of filters, and deriving from them a query
expressed in CQL. The general approach is that a React component
declaratively specifies a set of filter groups, which is then uses in
several different contexts to drive different but related pieces of
code.

In order to make it easy to use without needing to make a lot of
decisions, this library is somewhat opinionated about state
representation. This state is set using a `transitionToParams` method,
and obtined using a `queryParam` method. There must both be provided
within the React component that uses `<FilterGroups>`.


### Filter configuration

The filter configuration is an array containing an ordered list of
filter groups. Each group is represented by an object with four keys:

* `label` -- The human-readable label that is used when presenting the
  group on a page.
* `name` -- The name used internally for the filter group, which may
  be short or opaque in meaning.
* `cql` -- The name of the CQL index that corresponds to the filter
  group, and which will be used in queries to find records that
  satisfy particular settings of the filters in the group. In general,
  this will be the name of a field, or maybe subfield, in the schema
  for the kind of records under consideration.
* `values` -- A list of the possible values that may be selected for
  the filter.
* `restrictWhenAllSelected` -- a boolean indicating how to behave when
  all the filters in the group are selected. By default, this is taken
  to mean no restriction is intended, and so that filter group makes
  no contribution to the query. However, if this is set true, then a
  query clause is always included. (See
  [STCOM-204](https://issues.folio.org/browse/STCOM-204) for
  rationale.)

Each of the `values` is typically represented by a simple string, which
is used both to display on the page and as the value to use in
queries. However, each value may optionally instead be an object
containing two keys:

* `name` -- the name used to display the filter on the page.
* `cql` -- the value used when generating CQL queries.

In the example above, there are two filter groups, "Item Types" and
"Location". All the values of the former are simple strings; one of
the values of the latter is of the more complex form, using "Main
Library" as the displayed value and just 'main' as the corresponding
value to use in searches.

Each filter value has a "full name", made up of the group name, a
period and the filter name itself. For example, in the configuration
above, the full names include `item.Books` and `location.Annex
Library`.

### Representation in the user-interface URL

The state of the filters is communicated back to the caller by
invoking its `transitionTo` method to set the valu of a single query
parameter, `filters`, whose value is a comma-separated list of the
full names of all selected filters. Typically, the caller's
`transitionTo` method will set its values into the anointed
stripes-connect resource resulting in a change in the user-interface's
URL. For example:

	http://example.com/users?filters=item.DVDs,item.Microfilm,location.Main+Library


{'fraction_non_alphanumeric': 0.07983529680887567, 'fraction_numerical': 0.002516298753288345, 'mean_word_length': 4.29939393939394, 'pattern_counts': {'":': 0, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2613722', 'n_tokens_mistral': 2386, 'n_tokens_neox': 2278, 'n_words': 1170}