Support for automatic synchronization between inputs and URL search parameters

[DScheglov]

Description

To make filters persistent improves consistency of inter-page navigation, which enhances the overall user experience. Currently, Evidence has limited support for sidebar customization, and manually syncing inputs with the URL requires writing complex code.

So, two features required:

• preserving search params on the page navigation
• synchronization between inputs and URL search parameters

This feature request is a little bit more detailed than #1803

What problem would this solve?

The official documentation offers opportunity to use filters:

```sql products
SELECT code, title
FROM data.products
```

<Dropdown data={products} name="product" value="code" label="title" defaultValue="%">
  <DropdownOption value="%" valueLabel="All products" />
</Dropdown>

For many applications it is useful to be able to reflect the selected filter in the search of the url and vice versa.

Currently to do that we need to write something like that:

<Dropdown
  data={products}
  name="product"
  value="code"
  label="title"
  defaultValue={(typeof window !== 'undefined') && $page.url.searchParams.get('product') || '%'}
>
  <DropdownOption value="%" valueLabel="All products" />
</Dropdown>

const NULL = "(SELECT NULL WHERE 0 /* An Input has not been set */)";
const isNull = value => `${value}` === NULL;

const setFilterParam = (name, value) => {
  if (typeof window === 'undefined') return;

  const params = $page.url.searchParams;
  if (value === '%') {
    params.delete(name);
  } else {
    params.set(name, value);
  }

  const search = params.toString();

  window.history.replaceState({}, '', `${window.location.pathname}${search ? '?' + search : ''}`);
};

$: !isNull(inputs.product.value) && setFilterParam('product', inputs.product.value);

And what is the worse -- It works only for the current page.
The search is not preserved on the navigation between pages.
The evidence doesn't allow to override Sidebar without breaking entire markup.

How should it work?

Add New Page Frontmatters

Frontmatter	Type	Mandatory	Description
preserveSearch	boolean	no	Adds the search parameters from the current URL to the page link in the sidebar. The search parameters are preserved as they exist at the moment the link is triggered (e.g., clicked or navigated programmatically). Defaults to false if preserveSearchParams is not set, and true otherwise.
preserveSearchParams	string[]	no	List of search parameters to preserve from the current URL during navigation to the page. If specified, at least one value is required. If not specified and preserveSearch is explicitly set to true, the entire query string must be preserved. If preserveSearch is explicitly set to false, this frontmatter has no effect — no search parameters will be included in the page link.

Add New Properties: searchParam, toSearch, and fromSearch to All Inputs

Property	Type	Mandatory	Description
searchParam	string	no	Defines the name of the URL search parameter to be synced with the input value. If not specified, the input is not synced with URL search parameters.
toSearch	<T>(value: T) => string | null | undefined	no	Function that converts the current input value into a string to be used in the URL search parameter. Defaults to <T>(value: T) => value?.toString?.(). null and undefined values are excluded from the URL. Has no effect if searchParam is not specified.
fromSearch	<T>(value: string) => T | null | undefined	no	Function that converts the URL search parameter value into the input value. If the URL does not contain the parameter, or the function returns null or undefined, the defaultValue must be used to assign the input field. Defaults to (value?: string) => value Has no effect if searchParam is not specified.

Synchronization

The input values and search parameters must be synchronized on:

• Page load: search parameters → inputs
• Page navigation: search parameters→inputs
• Input updates: input → search parameters

Example

The following code results in automatically populating inputs.product.value before the first query that uses input.product.value is run. Later, when a new product is selected, the URL search is updated with &product=.

<Dropdown
  data={products}
  name="product"
  value="code"
  label="title"
  searchParam="product"
  defaultValue="%"
>
  <DropdownOption value="%" valueLabel="All products" />
</Dropdown>

[hydrojumbo]

This came up today while discussing if a date range filter could be set on one page and then stay applied on others.

In general, my 2 cents is making it easy to bind input values to URL parameters as you have proposed would be a clear improvement in how expert users can share evidence reports with others. "Click here to see the basis for the point I am making now" becomes straightforward. Reading through your proposal, I was initially concerned with "what if the combined fields result in a too-long URL?" But, your proposed toSearch and fromSearch extension points with defaults that probably 'just work' for most cases seems like a smart solution for those with such constraints (although it would probably be an edge case you would want to handle gracefully on the page by alerting the user that the URL was truncated and not all filters have been applied). In the same vein, I am not sure what would happen if the URL parameter allowed for a value that is not in an input's set. Altogether, this feels like a feature that could have been included from the beginning, and your proposal seems like a good way to do it. The overlap between people who appreciate a SSG for data presentation and deep linking as a feature of the web platform is probably pretty high.