Update documentation for our upcoming major (#9783)

Co-authored-by: Daniel Cousens <dcousens@users.noreply.github.com>
Co-authored-by: Emma Hamilton <git@emmas.town>

Author: dcousens

docs/content/docs/config/auth.md

@@ -73,7 +73,6 @@ The following elements will be added to the GraphQL API.
 ```graphql
 type Mutation {
   authenticateUserWithPassword(email: String!, password: String!): UserAuthenticationWithPasswordResult!
-  endSession: Boolean!
 }
 
 type Query {

docs/content/docs/config/config.md

@@ -64,7 +64,7 @@ These database types are powered by their corresponding Prisma database provider
 - `url`: The connection URL for your database
 - `onConnect`: which takes a [`KeystoneContext`](../context/overview) object, and lets perform any actions you might need at startup, such as data seeding
 - `enableLogging` (default: `false`): Enable logging from the Prisma client.
-- `idField` (default: `{ kind: "cuid" }`): The kind of id field to use, it can be one of: `cuid`, `uuid` or `autoincrement`.
+- `idField` (default: `{ kind: "cuid" }`): The kind of id field to use, it can be one of: `cuid`, `uuid`, `nanoid`, `ulid`, or `autoincrement`.
   This can also be customised at the list level `db.idField`.
   If you are using `autoincrement`, you can also specify `type: 'BigInt'` on PostgreSQL and MySQL to use BigInts.
 - `shadowDatabaseUrl` (default: `undefined`): Enable [shadow databases](https://www.prisma.io/docs/concepts/components/prisma-migrate/shadow-database#cloud-hosted-shadow-databases-must-be-created-manually) for some cloud providers.
@@ -145,7 +145,7 @@ Advanced configuration:
 
 - `publicPages` (default: `[]`): An array of page routes that bypass the `isAccessAllowed` function.
 - `pageMiddleware` (default: `undefined`): An async middleware function that can optionally return a redirect
-- `getAdditionalFiles` (default: `[]`): An async function returns an array of `AdminFileToWrite` objects indicating files to be added to the system at `build` time.
+- `getAdditionalFiles` (default: `undefined`): An async function that returns an array of `AdminFileToWrite` objects indicating files to be added to the system at `build` time.
   If the `mode` is `'write'`, then the code to be written to the file should be provided as the `src` argument.
   If the `mode` is `'copy'` then an `inputPath` value should be provided.
   The `outputPath` indicates where the file should be written or copied to
@@ -160,23 +160,21 @@ export default config<TypeInfo>({
 
     // advanced configuration
     publicPages: ['/welcome'],
-    getAdditionalFiles: [
-      async (config: KeystoneConfig) => [
-        {
-          mode: 'write',
-          src: `
-            import { jsx } from '@keystone-ui/core';
-            export default function Welcome() {
-              return (<h1>Welcome to my Keystone system</h1>);
-            }`,
-          outputPath: 'pages/welcome.js',
-        },
-        {
-          mode: 'copy',
-          inputPath: '...',
-          outputPath: 'pages/farewell.js',
-        }
-      ],
+    getAdditionalFiles: async () => [
+      {
+        mode: 'write',
+        src: `
+          import { Heading } from '@keystar/ui/typography';
+          export default function Welcome() {
+            return (<h1>Welcome to my Keystone system</h1>);
+          }`,
+        outputPath: 'pages/welcome.js',
+      },
+      {
+        mode: 'copy',
+        inputPath: '...',
+        outputPath: 'pages/farewell.js',
+      }
     ],
   },
   /* ... */
@@ -357,7 +355,7 @@ It has a TypeScript type of `(schema: import("graphql").GraphQLSchema) => import
 
 ```typescript
 import type { GraphQLSchema } from 'graphql'
-import { config, graphql } from '@keystone-6/core'
+import { config, g } from '@keystone-6/core'
 
 export default config<TypeInfo>({
   extendGraphqlSchema: (keystoneSchema: GraphQLSchema) => {
@@ -370,6 +368,12 @@ export default config<TypeInfo>({
 
 See the [schema extension guide](../guides/schema-extension) for more details and tooling options on how to extend your GraphQL API.
 
+## OpenTelemetry
+
+Keystone has built-in support for [OpenTelemetry](https://opentelemetry.io/) tracing via `@opentelemetry/api`. When you configure an OpenTelemetry SDK in your application, Keystone will automatically emit trace spans for its internal operations (such as CRUD resolvers and hooks).
+
+No additional Keystone configuration is required — just set up the OpenTelemetry SDK before Keystone starts. See the `logging-opentelemetry` example for a complete setup.
+
 ## Related resources
 
 {% related-content %}

docs/content/docs/config/hooks.md

@@ -13,6 +13,7 @@ export default config({
   lists: ({
     SomeListName: list({
       fields: { /* ... */ },
+      actions: { /* ... */ },
       access: { /* ... */ },
       ui: { /* ... */ },
       hooks: { /* ... */ },
@@ -61,6 +62,69 @@ export default config({
 
 For full details on the available field types and their configuration options please see the [Fields API](../fields/overview).
 
+## actions
+
+The `actions` property of the list configuration object is where you define actions that can triggered for items on your list.
+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';
+
+export default config({
+  lists: {
+    Post: list({
+      access: allowAll,
+      fields: {
+        title: text(),
+        votes: integer({ defaultValue: 0 }),
+      },
+      actions: {
+        vote: {
+          access: allowAll,
+          async resolve ({ where }, context) {
+            if (!where) return null
+            return await context.prisma.post.update({
+              where: { id: where.id },
+              data: { votes: { increment: 1 } },
+            })
+          },
+          ui: {
+            label: 'Vote +1',
+            icon: 'voteIcon',
+          },
+        },
+      },
+    }),
+  },
+});
+```
+
+Each action accepts the following options:
+
+- `access` (**required**): An access control function that determines who can use this action. Receives `{ context, session, listKey, actionKey }`.
+- `resolve` (**required**): The function that performs the action. Receives `{ listKey, actionKey, where }` and `context`. Should return the updated item or `null`.
+- `graphql`: Options for the GraphQL schema output.
+  - `singular`: Override the name of the singular mutation (default: `{action}{list.graphql.singular}`, e.g. `votePost`).
+  - `plural`: Override the name of the plural mutation (default: `{action}{list.graphql.plural}`, e.g. `votePosts`).
+  - `description` (default: `undefined`): Sets the description of the associated GraphQL type in the GraphQL schema output.
+- `ui` (**required**): Controls how the action appears in the Admin UI.
+  - `label` (**required**): The label shown on the action button.
+  - `icon`: An icon name from `@keystar/ui/icon/all` to display alongside the label.
+  - `messages`: Locale messages for prompts and notifications. Supports template tags: `{singular}`, `{plural}`, `{singular|plural}`, `{itemLabel}`, `{count}`, `{countSuccess}`, `{countFail}`.
+    - `promptTitle`, `promptTitleMany`, `prompt`, `promptMany`: Confirmation dialog text.
+    - `promptConfirmLabel`, `promptConfirmLabelMany`: Confirm button text.
+    - `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.
+    - `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.
+
 ## access
 
 The `access` option defines the [Access Control](../guides/auth-and-access-control) rules for the list.
@@ -79,7 +143,6 @@ Options:
 - `searchFields`: The fields used by the Admin UI when searching this list on the list view and in relationship fields. Nominated fields need to support the `contains` filter.
   It is always possible to search by an id and `'id'` should not be specified in this option.
   By default, the `labelField` is used if it has a string `contains` filter, otherwise none.
-- `description` (default: `undefined`): Sets the list description displayed in the Admin UI.
 - `hideNavigation` (default: `false`): Controls whether the list is visible in the navigation elements of the Admin UI.
   Can be either a boolean value or an async function with an argument `{ session, context }` that returns a boolean value.
 - `hideCreate` (default: `false`): Controls whether the `create` button is available in the Admin UI for this list.
@@ -106,6 +169,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.
 - `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}?`
@@ -121,7 +185,6 @@ export default config({
       fields: { name: text({ /* ... */ }) },
       ui: {
         label: 'Some List',
-        description: '...',
 
         singular: 'Item',
         plural: 'Items',
@@ -142,6 +205,7 @@ export default config({
           defaultFieldMode: ({ session, context }) => 'read',
           initialColumns: ['name', /* ... */],
           initialSort: { field: 'name', direction: 'ASC' },
+          initialFilter: { isPublished: { equals: true } },
           pageSize: 50,
         },
       },
@@ -161,12 +225,11 @@ See the [Hooks API](./hooks) for full details on the available hook options.
 
 ## graphql
 
-The `graphql` config option allows you to configure certain aspects of the GraphQL API.
+The `graphql` property allows you to configure certain aspects of the GraphQL API.
 
 Options:
 
-- `description` (default: `undefined`): Sets the description of the associated GraphQL type in the generated GraphQL API documentation.
-  Overrides the list-level `description` config option.
+- `description` (default: `undefined`): Sets the description of the associated GraphQL type in the GraphQL schema output.
 - `singular`: (default: Singular list key, e.g. `'User'`): Overrides the name used in singular mutations and queries (e.g. `user()`, `updateUser()`, etc).
 - `plural`: (default: Pluralised list key, e.g. `'Users'`): Overrides the name used in multiple mutations and queries (e.g. `users()`, `updateUsers()`, etc).
 - `maxTake` (default: `undefined`): Allows you to specify the maximum `take` number for query operations on this list in the GraphQL API.

docs/content/docs/config/lists.md

@@ -37,6 +37,7 @@ const context = {
 
   // New context creators
   sudo,
+  internal,
   withRequest,
   withSession,
 
@@ -97,7 +98,9 @@ See the [session API](../config/session#session-context) for more details.
 When using the `context.query`, `context.graphql.run`, and `context.graphql.raw` APIs, access control and session information is passed through to these calls from the `context` object.
 The following functions will create a new `Context` object with this behaviour modified.
 
-`sudo()`: A function which returns a new `Context` object with access control limitations removed, bypassing your `access` control configuration.
+`sudo()`: A function which returns a new `Context` object that bypasses your `access` control configuration when using `context.query`, `context.db` or `context.graphql`.
+
+`internal()`: A function which returns a new `Context` object that bypasses `graphql.omit` on lists and fields, allowing you to query and mutate data that is otherwise omitted from the GraphQL API.
 
 `withRequest(req, res)`: A function which returns a new `Context` object with the `.session` determined by your `sessionStrategy.get` function.
 
@@ -107,6 +110,9 @@ The following functions will create a new `Context` object with this behaviour m
 
 The `Context` object exposes the underlying database driver directly via `context.prisma`, which is a [Prisma Client](https://www.prisma.io/docs/reference/api-reference/prisma-client-reference) object.
 
+{% hint kind="tip" %}
+**\*Warning** Unlike other data access functions (`context.db`, `context.query` or `context.graphql`), `context.prisma` always bypasses the GraphQL schema and your access control. It is the equivalent of using `.sudo()` always.
+
 ### Images API
 
 If [support for image fields](../config/config#storage-images-and-files) is enabled in the system, then an `images` API will be made available on the `context` object.

docs/content/docs/context/overview.md

@@ -10,7 +10,7 @@ Javascript `BigInt`s are used since [integers in Javascript are unsafe beyond 2{
 
 Options:
 
-- `defaultValue` (default: `undefined`): Can be either a bigint value or `{ kind: 'autoincrement' }`.
+- `defaultValue` (default: `undefined`): Can be either a bigint value, `null`, or `{ kind: 'autoincrement' }`.
   This value will be used for the field when creating items if no explicit value is set.
   `{ kind: 'autoincrement' }` is only supported on PostgreSQL.
 - `db.isNullable` (default: `validation.isRequired ? false : true`): If `false` then this field will be made non-nullable in the database and it will never be possible to set as `null`.

docs/content/docs/fields/bigint.md

@@ -7,7 +7,7 @@ A `decimal` field represents a decimal value.
 
 Options:
 
-- `defaultValue` (default: `undefined`): Can be a decimal value written as a string
+- `defaultValue` (default: `undefined`): Can be a decimal value written as a string, or `null`.
   This value will be used for the field when creating items if no explicit value is set.
 - `precision` (default: `18`): Maximum number of digits that are present in the number.
 - `scale` (default: `4`): Maximum number of decimal places.

docs/content/docs/fields/decimal.md

@@ -7,7 +7,7 @@ A `float` field represents a floating point value.
 
 Options:
 
-- `defaultValue` (default: `undefined`): Can be a finite float value.
+- `defaultValue` (default: `undefined`): Can be a finite float value, or `null`.
   This value will be used for the field when creating items if no explicit value is set.
 - `db.map`: Adds a [Prisma `@map`](https://www.prisma.io/docs/reference/api-reference/prisma-schema-reference#map) attribute to this field which changes the column name in the database
 - `db.isNullable` (default: `validation.isRequired ? false : true`): If `false` then this field will be made non-nullable in the database and it will never be possible to set as `null`.

docs/content/docs/fields/float.md

@@ -7,7 +7,7 @@ An `integer` field represents a 32 bit signed integer value.
 
 Options:
 
-- `defaultValue` (default: `undefined`): Can be either an integer value or `{ kind: 'autoincrement' }`.
+- `defaultValue` (default: `undefined`): Can be either an integer value, `null`, or `{ kind: 'autoincrement' }`.
   This value will be used for the field when creating items if no explicit value is set.
   `{ kind: 'autoincrement' }` is only supported on PostgreSQL.
 - `db.isNullable` (default: `validation.isRequired ? false : true`): If `false` then this field will be made non-nullable in the database and it will never be possible to set as `null`.