feat: query presets (#11330)

Query Presets allow you to save and share filters, columns, and sort
orders for your collections. This is useful for reusing common or
complex filtering patterns and column configurations across your team.
Query Presets are defined on the fly by the users of your app, rather
than being hard coded into the Payload Config.

Here's a screen recording demonstrating the general workflow as it
relates to the list view. Query Presets are not exclusive to the admin
panel, however, as they could be useful in a number of other contexts
and environments.


https://github.com/user-attachments/assets/1fe1155e-ae78-4f59-9138-af352762a1d5

Each Query Preset is saved as a new record in the database under the
`payload-query-presets` collection. This will effectively make them
CRUDable and allows for an endless number of preset configurations. As
you make changes to filters, columns, limit, etc. you can choose to save
them as a new record and optionally share them with others.

Normal document-level access control will determine who can read,
update, and delete these records. Payload provides a set of sensible
defaults here, such as "only me", "everyone", and "specific users", but
you can also extend your own set of access rules on top of this, such as
"by role", etc. Access control is customizable at the operation-level,
for example you can set this to "everyone" can read, but "only me" can
update.

To enable the Query Presets within a particular collection, set
`enableQueryPresets` on that collection's config.

Here's an example:

```ts
{
  // ...
  enableQueryPresets: true
}
```

Once enabled, a new set of controls will appear within the list view of
the admin panel. This is where you can select and manage query presets.

General settings for Query Presets are configured under the root
`queryPresets` property. This is where you can customize the labels,
apply custom access control rules, etc.

Here's an example of how you might augment the access control properties
with your own custom rule to achieve RBAC:

```ts
{
  // ...
  queryPresets: {
    constraints: {
      read: [
        {
          label: 'Specific Roles',
          value: 'specificRoles',
          fields: [roles],
          access: ({ req: { user } }) => ({
            'access.update.roles': {
              in: [user?.roles],
            },
          }),
        },
      ],
    }
  }
}
```

Related: #4193 and #3092

---------

Co-authored-by: Dan Ribbens <dan.ribbens@gmail.com>
This commit is contained in:
Jacob Fletcher
2025-03-24 13:16:39 -04:00
committed by GitHub
parent bb14cc9b41
commit 998181b986
168 changed files with 6737 additions and 418 deletions

View File

@@ -392,7 +392,7 @@ describe('List View', () => {
test('should reset filter value when a different field is selected', async () => {
const id = (await page.locator('.cell-id').first().innerText()).replace('ID: ', '')
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'ID',
operatorLabel: 'equals',
@@ -416,7 +416,7 @@ describe('List View', () => {
test('should remove condition from URL when value is cleared', async () => {
await page.goto(postsUrl.list)
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'Relationship',
operatorLabel: 'equals',
@@ -431,16 +431,13 @@ describe('List View', () => {
await whereBuilder.locator('.condition__value .clear-indicator').click()
await page.waitForURL(new RegExp(encodedQueryString))
})
test.skip('should remove condition from URL when a different field is selected', async () => {
// TODO: fix this bug and write this test
expect(true).toBe(true)
})
test('should refresh relationship values when a different field is selected', async () => {
await page.goto(postsUrl.list)
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'Relationship',
operatorLabel: 'equals',
@@ -600,7 +597,7 @@ describe('List View', () => {
test('should reset filter values for every additional filter', async () => {
await page.goto(postsUrl.list)
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'Tab 1 > Title',
operatorLabel: 'equals',
@@ -622,7 +619,7 @@ describe('List View', () => {
test('should not re-render page upon typing in a value in the filter value field', async () => {
await page.goto(postsUrl.list)
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'Tab 1 > Title',
operatorLabel: 'equals',
@@ -645,7 +642,7 @@ describe('List View', () => {
test('should still show second filter if two filters exist and first filter is removed', async () => {
await page.goto(postsUrl.list)
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'Tab 1 > Title',
operatorLabel: 'equals',
@@ -739,7 +736,7 @@ describe('List View', () => {
test('should properly paginate many documents', async () => {
await page.goto(with300DocumentsUrl.list)
const whereBuilder = await addListFilter({
const { whereBuilder } = await addListFilter({
page,
fieldLabel: 'Self Relation',
operatorLabel: 'equals',