Add link-based editor for relationships

We want to provide editors with a powerful and easy way to define queries and save them as “saved searches”. The UI for that should look like this:

The output of this will be a JSON:API query that the client can send to the backend as it is, e.g.:

{
  filter: {
    or: [
      { 'first-name': ['Quint'], type: 'people' },
      { type: 'articles', id: '1' }
    ]
  }
}

That query will be stored as the value for @cardstack/core-types::has-many and @cardstack/core-types::belongs-to fields (as opposed storing the data for the relation). So instead of storing something line

{
  "data": {
    "id": "main-footer",
    "type": "footers"
  }
}

as a relationship’s value we would be storing the serialized query:

cards: {
  links: {
    related: "/api?filter%5Btype%5D%5B0%5D=posts&filter%5Btype%5D%5B1%5D=events&filter%5Bcategory%5D%5B0%5D=crypto&filter%5Bcategory%5D%5B1%5D=engineering&page%5Bsize%5D=4&sort=-updated-at"
  }
}

So the UI shown in the above screenshot is really just an alternative to the card-picker that is currently used to edit fields of type @cardstack/core-types::has-many or @cardstack/core-types::belongs-to.

Feature Spec

Each condition is based on a particular field with a particular type (String, Number/Date, Enumerable). Depending on the type of the field, the potential conditions for the field are:

• String: is, not, includes, does not contain, starts with, ends with (the kind of comparison to apply will be chosen via a <select> box, the value to compare to is put in via a <input type="text">)
• Number/Date: is, not, greater than, less than, greater or equal, less or equal, between (as for String, the kind of comparison to apply will be chosen via a <select> box, the value to compare to is put in via a <input type="text">)
• Enumerable: is, not, includes
  • For types that imply 2 values:
    • between (this would be another option in the select box for selecting the kind of comparison, the values to compare to are then put in via 2 <input type="text">)
    • one of: (this would be another option in the select box for selecting the kind of comparison, the values to compare to are then put in via a <input type="text"> as a comma-separated list - we will improve the UI for that in a follow-up issue)

The output of the component is a JSON:API-compatible query filter such as:

{
  filter: {
    or: [
      { 'first-name': ['Quint'], type: 'people' },
      { type: 'articles', id: '1' }
    ]
  }
}

that will be stored as

{
  links: {
    related: '/api??filter%5Btype%5D%5B0%5D=posts&filter%5Btype%5D%5B1%5D=events&filter%5Bcategory%5D%5B0%5D=crypto&filter%5Bcategory%5D%5B1%5D=engineering&page%5Bsize%5D=4&sort=-updated-at'
  }
}

for a @cardstack/core-types::has-many or @cardstack/core-types::belongs-to field.

TODO

• create new editor UI for relationships that works for relationships that are defined via related links; the link as such is the input for the editor then
• store the specified query as related link back in the relationship; this is done by assigning a cardstack-queries resource with the serialized filter set as its id as described in #411

Open Questions

• is storing the serialized query definition in the field actually what we want or is there a better way?
• the available fields to filter on (“Card Type”, “Published Date”, “Tags” in the above screenshot) would have to be defined somewhere, together with their possible values (e.g. all instances of the Tag card being possible values for the “Tags” field) - this could be done via options passed to the editor or potentially elsewhere

This depends on cardstack/cardstack#411 that will allow persisting relationships as links as opposed to data only.

[marcoow]

@bagby: I updated the issue description according the Ed’s comments

[ef4]

@bagby pointed out a good idea, which is that we may be able to use the meta on relationships to hold the query, rather than needing the special cardstack-queries type.

PATCH /api/articles/1
{
  data: {
    type: 'articles',
    id: '1',
    attributes: {
      …
    },
    relationships: {
      relatedArticles: {
        meta: {
          cardstack-query: {
            filter: {
              type: "articles", 
            },
            q: "Bagby",
            page: {
              size: 3, 
              sort: "-updated"
            }
          }
        }
      }
    }
  }
}

If the spec allowed posting back meta like this, it would avoid the need to have a different representation in GET vs POST/PATCH