eoAPI UI Interface Technical RFC (based off of eoAPI Issue #97)

[sandrahoang686]

The Ask

github-ref

Context

STAC is extremely flexible (and items essentially schema-less) which makes it difficult for users to determine how they can create queries to filter a large collection.

Ideal

An interface that would be self-configuring based on the results of an initial capabilities query to the queryables endpoint of the STAC API

A set of filter based components (range slider, time selector, dropdown selector, etc) that would be referenced based on the prop attribute of type​.

For example:

1. A user could select an endpoint or collection which would advertise the properties and their datatype which can be used in a filter expression.

2. Let's say that the selected collection advertises eo:cloud_cover as one of its queryables.

 "properties": {
        "eo:cloud_cover": {
          "title": "Cloud Cover",
          "type": "number",
          "minimum": 0,
          "maximum": 100
        }

3. The filter component would then "self-configure" a slider component with the range 0-100

Note: The advertised queryables completely change depending on the collection or endpoint. Ideal if users could have a dynamic interface that is configured in relation to the endpoint being used.

Technical Solutions

Solution 1

as proposed by Oliver (github-ref)

Simplify filter generation based on queryables. I think there can be a middle ground by providing the configuration for components but not the components itself.

Image something along the lines of:

function CloudcoverSlider() {
  const sliderParams = useQueryableFilter("eo:cloud_cover");

  return <input {...sliderParams}>
}

where sliderParams is an object that looks like this:

{
  min: 0,
  max: 100,
  type: "range",
  onChange: () => {}
}

That way we abstract away the complexity of parsing queryables, generating component props, and handle value changes and query construction. And developers have full control of the rest of their component.

Solution 1 (maybe?) flushed out

written by Sandra

Based on a collection and it's advertised queryables. Render this {type} of component...

A controller container component the consumer would interact with and provide the queryable filter object as a prop. The controller component would conditionally render whichever forum component based on type​ attribute. These forum components (slider, date-picker, dropdown) could use Chakra under the hood.

Leverage TypeScript

Main Component Example:

/* TYPE EXAMPLES */

interface Common {
    type: 'range' | 'dates' | 'options';
    onChange:() => void;
}

interface Slider extends Common {
	min: number;
    max: number;
}

interface TimeSelector extends Common {
	...
}

interface DropDownSelector extends Common {
	...
}


/**
	CONTROLLER COMPONENT
    when given the filterParams, it would
    dynamically chose which filter component to render
*/

interface PropTypes {
	filterObj: Slider | TimeSelector | DropDownSelector
}

export function SelfConfigurableForumController({filterObj}: PropTypes) {
	return (
    	{ filterObj.type == 'range' &&
        	<SliderInput {...filterObj}>
        }
        { filterObj.type == 'dates' &&
        	<DateInput {...filterObj}>
        }
        { filterObj.type == 'options' &&
        	<DropDownInput {...filterObj}>
        }
    )
}

Consumer's Code

import SelfConfigurableForumController from ...
import useQueryableFilter from ... // @QUESTION: Is this something we would build? If so
the return type should sync with the "filterObj" type expected


function Cloudcover() {
	// @QUESTION: Would this live in the consumer's code or would this also be 
    abstracted away? 
	const params = useQueryableFilter("eo:cloud_cover");

    return (
      <>
          ...
          ...
          <SelfConfigurableForumController filterObj={params}>
      </>
    )
}

Tradeoffs

Pros:

• Easy to interact with the component code because of the abstraction from the user
• Abstracts away the complexity of parsing queryables
• Generating component props that would adhere to typing
• Controller would handle what forum component show that matches the advertised queryable the best
• Developers have full control of the rest of their component

Risks:

• Opinionated because we make the decision of what to render and what that filter component probably looks like
• The user doesn't know what they are getting, just depends on the collect
• There are also "non-standard" properties (as stated in post) to account for - how do we accommodate to those edge cases?

Alternative Solutions

... TBD

[sandrahoang686]

Posting @oliverroick thoughts from Slack for openness and feedback

Hey Sandra, sorry for the late reply. I had a read through your proposal, I think it’s solid start. I did some more thinking about potential developer use cases for this, which I think we should consider:

1. The developer wants control over how the UI elements to control filter queries are rendered. For example, they might want to use number inputs instead of a slider to control the cloud-cover thresholds. In that case they would want to use the hooks that are already existing and build their own UI using the hooks.
2. The developer wants a quick and easy way to render an interface that allows users to control the STAC queries for a specific STAC API, as advertised by the queryables document. For this, we might be able to push it to the simplest form, which could one component that renders the whole form and that could have a very simple props signature, like .
   These two cases are on opposite ends of a spectrum but it solving case 2, will also address case in the middle of the spectrum. We would have to build components for individual querables anyway (checkboxes for collections, sliders, date pickers, etc), and if we expose those components as well then developers can compose UIs with just the controls they need without implementing everything from scratch. It would work in a similar way as Formik, which also allows for different levels of abstraction.