AND, OR and NOT in client side conditional filters

Co-authored-by: Copilot <[email protected]>
Co-authored-by: dcousens <[email protected]>
Co-authored-by: Daniel Cousens <[email protected]>

Author: 3 people

.changeset/and-or-not-conditional-filters.md

@@ -0,0 +1,5 @@
+---
+"@keystone-6/core": minor
+---
+
+Add `AND`, `OR` and `NOT` support for conditional client-state filters

docs/content/docs/config/lists.md

@@ -1,32 +1,46 @@
 ---
-title: "Lists API"
-description: "Reference docs for Keystone’s Lists API, which defines the data model of your system."
+title: 'Lists API'
+description: 'Reference docs for Keystone’s Lists API, which defines the data model of your system.'
 ---
 
 The `lists` property of the [system configuration](./config) object is where you define the data model, or schema, of your Keystone system.
 It accepts an object with list names as keys, and `list()` configurations as values.
 
 ```typescript
-import { config, list } from '@keystone-6/core';
+import { config, list } from '@keystone-6/core'
 
 export default config({
-  lists: ({
+  lists: {
     SomeListName: list({
-      fields: { /* ... */ },
-      actions: { /* ... */ },
-      access: { /* ... */ },
-      ui: { /* ... */ },
-      hooks: { /* ... */ },
-      graphql: { /* ... */ },
-      db: { /* ... */ },
+      fields: {
+        /* ... */
+      },
+      actions: {
+        /* ... */
+      },
+      access: {
+        /* ... */
+      },
+      ui: {
+        /* ... */
+      },
+      hooks: {
+        /* ... */
+      },
+      graphql: {
+        /* ... */
+      },
+      db: {
+        /* ... */
+      },
       isSingleton: false,
       defaultIsFilterable: false,
       defaultIsOrderable: false,
     }),
     /* ... */
-  }),
+  },
   /* ... */
-});
+})
 ```
 
 This document will explain the configuration options which can be used with the `list()` function.
@@ -43,21 +57,23 @@ The `fields` option defines the names, types, and configuration of the fields in
 This configuration option takes an object with field names as keys and configured field types as values.
 
 ```typescript
-import { config, list } from '@keystone-6/core';
-import { text } from '@keystone-6/core/fields';
+import { config, list } from '@keystone-6/core'
+import { text } from '@keystone-6/core/fields'
 
 export default config({
   lists: {
     SomeListName: list({
       fields: {
-        someFieldName: text({ /* ... */ }),
+        someFieldName: text({
+          /* ... */
+        }),
         /* ... */
       },
     }),
     /* ... */
   },
   /* ... */
-});
+})
 ```
 
 For full details on the available field types and their configuration options please see the [Fields API](../fields/overview).
@@ -68,9 +84,9 @@ The `actions` property of the list configuration object is where you define acti
 An action can be triggered on individual items or in bulk from the list view in the Admin UI, or directly using GraphQL.
 
 ```typescript
-import { config, list } from '@keystone-6/core';
-import { allowAll } from '@keystone-6/core/access';
-import { text, integer } from '@keystone-6/core/fields';
+import { config, list } from '@keystone-6/core'
+import { allowAll } from '@keystone-6/core/access'
+import { text, integer } from '@keystone-6/core/fields'
 
 export default config({
   lists: {
@@ -83,7 +99,7 @@ export default config({
       actions: {
         vote: {
           access: allowAll,
-          async resolve ({ where }, context) {
+          async resolve({ where }, context) {
             if (!where) return null
             return await context.prisma.post.update({
               where: { id: where.id },
@@ -98,7 +114,7 @@ export default config({
       },
     }),
   },
-});
+})
 ```
 
 Each action accepts the following options:
@@ -118,12 +134,12 @@ Each action accepts the following options:
     - `success`, `successMany`: Success toast messages.
     - `fail`, `failMany`: Failure toast messages.
   - `itemView`: Controls for the item view.
-    - `actionMode` (default: `'enabled'`): Can be `'enabled'`, `'disabled'`, or `'hidden'`, or a function that returns one of those values.
+    - `actionMode` (default: `'enabled'`): Can be `'enabled'`, `'disabled'`, or `'hidden'`, a conditional filter object, or a function that returns one of those values. Conditional filter objects can combine field predicates with nested `AND`, `OR`, and `NOT` groups.
     - `navigation` (default: `'follow'`): Controls navigation after the action completes. `'follow'` navigates to the returned item (or list view if `null`), `'refetch'` stays and refreshes the item, `'return'` goes back to the list view.
     - `hidePrompt` (default: `false`): Do not show a confirmation dialog.
     - `hideToast` (default: `false`): Do not show a toast notification.
   - `listView`: Controls for the list view.
-    - `actionMode` (default: `'enabled'`): Can be `'enabled'` or `'hidden'`, or a function that returns one of those values.
+    - `actionMode` (default: `'enabled'`): Can be `'enabled'` or `'hidden'`, a conditional filter object, or a function that returns one of those values. Conditional filter objects can combine field predicates with nested `AND`, `OR`, and `NOT` groups.
 
 ## access
 
@@ -169,7 +185,7 @@ Options:
     Option `field` is the name of the field to sort by, and `direction` is either `'ASC'` or `'DESC'` for ascending and descending sorting respectively.
     If undefined then data will be unsorted.
   - `pageSize` (default: lower of `50` or [`graphql.maxTake`](#graphql)): Sets the number of items to show per page in the list view.
-  - `initialFilter` (default: `undefined`): Sets a default filter to apply to the list view. Accepts a where input object (excluding `AND`, `OR`, `NOT`), or an async function with an argument `{ session, context }` that returns a where input object.
+  - `initialFilter` (default: `undefined`): Sets a default column filter to apply to the list view. Accepts a where input object (excluding `AND`, `OR`, `NOT`), or an async function with an argument `{ session, context }` that returns a where input object. 
 - `label`: The label used to identify the list in navigation etc.
 - `singular`: The singular form of the list key. It is used in sentences like `Are you sure you want to delete this {singular}?`
 - `plural`: The plural form of the list key. It is used in sentences like `Are you sure you want to delete these {plural}?`
@@ -243,7 +259,7 @@ Options:
   - `omit.delete` (default: `false`): If set to true, the delete mutation will be omitted from the GraphQL API for this list.
 
 ```typescript
-import { config, list } from '@keystone-6/core';
+import { config, list } from '@keystone-6/core'
 
 export default config({
   lists: {
@@ -266,7 +282,7 @@ export default config({
     /* ... */
   },
   /* ... */
-});
+})
 ```
 
 ## db
@@ -281,7 +297,7 @@ Options:
 - `map`: Adds a [Prisma `@@map`](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#map-1) attribute to the Prisma model for this list which specifies a custom database table name for the list, instead of using the list key
 
 ```typescript
-import { config, list } from '@keystone-6/core';
+import { config, list } from '@keystone-6/core'
 
 export default config({
   lists: {
@@ -295,7 +311,7 @@ export default config({
     /* ... */
   },
   /* ... */
-});
+})
 ```
 
 ## isSingleton

docs/content/docs/fields/overview.md

@@ -1,6 +1,6 @@
 ---
-title: "Fields"
-description: "A reference of Keystone’s field types, and the configuration options they accept."
+title: 'Fields'
+description: 'A reference of Keystone’s field types, and the configuration options they accept.'
 ---
 
 {% hint kind="warn" %}
@@ -14,7 +14,7 @@ This document covers the different field types which are available and the confi
 To see how to access fields in the GraphQL API please see the [GraphQL API](../graphql/overview) docs.
 
 ```typescript
-import { config, list } from '@keystone-6/core';
+import { config, list } from '@keystone-6/core'
 import {
   // Scalar types
   checkbox,
@@ -39,24 +39,26 @@ import {
   // File types
   file,
   image,
-} from '@keystone-6/core/fields';
+} from '@keystone-6/core/fields'
 
 // Complex types
-import { document } from '@keystone-6/fields-document';
-import { cloudinaryImage } from '@keystone-6/cloudinary';
+import { document } from '@keystone-6/fields-document'
+import { cloudinaryImage } from '@keystone-6/cloudinary'
 
 export default config({
   lists: {
     SomeListName: list({
       fields: {
-        someFieldName: text({ /* ... */ }),
+        someFieldName: text({
+          /* ... */
+        }),
         /* ... */
       },
     }),
     /* ... */
   },
   /* ... */
-});
+})
 ```
 
 ## Common configuration
@@ -92,7 +94,7 @@ Options:
     Defaults to the list's `ui.itemView.defaultFieldMode` config if defined.
     See the [Lists API](../config/lists#ui) for details.
 - `itemView.fieldPosition` (default: `form`): Controls which side of the page the field is placed in the Admin UI.
-    Can be either `form` or `sidebar`, or an async function with an argument `{ session, context, listKey, fieldKey, item, itemField }` that returns one of `['form', 'sidebar']`. The `item` argument may be `null`. `form` or blank places the field on the left hand side of the item view. `sidebar` places the field on the right hand side under the ID field
+  Can be either `form` or `sidebar`, or an async function with an argument `{ session, context, listKey, fieldKey, item, itemField }` that returns one of `['form', 'sidebar']`. The `item` argument may be `null`. `form` or blank places the field on the left hand side of the item view. `sidebar` places the field on the right hand side under the ID field
   - `itemView.isRequired` (default: `undefined`): Controls whether the field is marked as required in the item view. Can be a boolean or an async function with an argument `{ session, context }` that returns a boolean. When `true`, the Admin UI will show the field as required.
   - `listView.fieldMode` (default: `'read'`): Controls the list view page of the Admin UI.
     Can be one of `['read', 'hidden']`, or an async function with an argument `{ session, context }` that returns one of `['read', 'hidden']`.
@@ -115,6 +117,8 @@ Options:
     - `omit.create` (default: `false`): If you specify `true`, then the field will be excluded from the list's CreateInput GraphQL type.
     - `omit.update` (default: `false`): If you specify `true`, then the field will be excluded from the list's UpdateInput GraphQL type.
 
+For Admin UI conditional config such as `fieldMode` and `isRequired`, filter objects can combine field predicates with nested `AND`, `OR`, and `NOT` groups. These are evaluated client-side in the Admin UI and do not change the GraphQL `where` input API.
+
 ```typescript
 export default config({
   lists: {
@@ -123,16 +127,25 @@ export default config({
         someFieldName: text({
           isFilterable: ({ context, session, fieldKey, listKey }) => true,
           isOrderable: ({ context, session, fieldKey, listKey }) => true,
-          access: { /* ... */ },
-          hooks: { /* ... */ },
+          access: {
+            /* ... */
+          },
+          hooks: {
+            /* ... */
+          },
           ui: {
             label: '...',
             views: './path/to/viewsModule',
             createView: {
               fieldMode: ({ session, context }) => 'edit',
             },
             itemView: {
-              fieldMode: ({ session, context, item, itemField }) => 'read',
+              fieldMode: {
+                read: {
+                  status: { equals: 'archived' },
+                  NOT: { canEdit: { equals: true } },
+                },
+              },
             },
             listView: {
               fieldMode: ({ session, context }) => 'read',
@@ -145,24 +158,24 @@ export default config({
               create: true,
               update: true,
             },
-          }
+          },
         }),
         /* ... */
       },
     }),
     /* ... */
   },
   /* ... */
-});
+})
 ```
 
 ## Groups
 
 Fields can be grouped together in the Admin UI using the `group` function, with a customisable `label` and `description`.
 
 ```typescript
-import { config, list, group } from '@keystone-6/core';
-import { text } from '@keystone-6/core/fields';
+import { config, list, group } from '@keystone-6/core'
+import { text } from '@keystone-6/core/fields'
 
 export default config({
   lists: {
@@ -172,7 +185,9 @@ export default config({
           label: 'Group label',
           description: 'Group description',
           fields: {
-            someFieldName: text({ /* ... */ }),
+            someFieldName: text({
+              /* ... */
+            }),
             /* ... */
           },
         }),
@@ -182,7 +197,7 @@ export default config({
     /* ... */
   },
   /* ... */
-});
+})
 ```
 
 Groups also support `defaultFieldMode` overrides for `createView`, `itemView`, and `listView`, which apply to all fields within the group unless overridden at the field level:

examples/actions/schema.ts

@@ -31,6 +31,10 @@ const readOnly = {
   },
 }
 
+const isReportDisabled = {
+  OR: [{ hidden: { equals: true } }, { reportedAt: { not: { equals: null } } }],
+} as const
+
 export const lists = {
   Post: list({
     access: allowAll, // WARNING: public
@@ -122,12 +126,12 @@ export const lists = {
             successMany: 'Successfully reported {countSuccess} {singular|plural}',
           },
           itemView: {
-            actionMode: { disabled: { hidden: { equals: true } } },
+            actionMode: { disabled: isReportDisabled },
             navigation: 'refetch',
             hideToast: true,
           },
           listView: {
-            actionMode: { disabled: { hidden: { equals: true } } },
+            actionMode: { disabled: isReportDisabled },
           },
         },
       },

examples/dynamic-is-required/schema.ts

@@ -3,6 +3,11 @@ import { list } from '@keystone-6/core'
 import { allowAll } from '@keystone-6/core/access'
 import { checkbox, relationship, select, text, timestamp } from '@keystone-6/core/fields'
 
+const hasHighPriority = {
+  priority: { equals: 'high' },
+  isComplete: { equals: false },
+} as const
+
 export const lists = {
   Todo: list({
     access: allowAll,
@@ -19,24 +24,20 @@ export const lists = {
       reasonForHighPriority: text({
         ui: {
           createView: {
+            isRequired: hasHighPriority,
             fieldMode: {
               hidden: {
-                priority: { not: { equals: 'high' } },
+                NOT: hasHighPriority,
               },
             },
-            isRequired: {
-              priority: { equals: 'high' },
-            },
           },
           itemView: {
+            isRequired: hasHighPriority,
             fieldMode: {
               hidden: {
-                priority: { not: { equals: 'high' } },
+                NOT: hasHighPriority,
               },
             },
-            isRequired: {
-              priority: { equals: 'high' },
-            },
           },
         },
         hooks: {