Update schema API docs (#4775)

docs-next/components/Navigation.tsx

@@ -57,11 +57,16 @@ export const Navigation = () => {
         <NavItem href="/guides/getting-started">Getting Started</NavItem>
         <NavItem href="/guides/installation">Installation</NavItem>
         <NavItem href="/guides/cli">Command Line</NavItem>
+        <NavItem href="/guides/access-control">Access Control</NavItem>
+        <NavItem href="/guides/hooks">Hooks</NavItem>
         <NavItem href="/guides/schema-extension">Schema Extension</NavItem>
       </Section>
       <Section label="API">
-        <NavItem href="/apis/system">System API</NavItem>
+        <NavItem href="/apis/config">Config API</NavItem>
         <NavItem href="/apis/schema">Schema API</NavItem>
+        <NavItem href="/apis/fields">Fields API</NavItem>
+        <NavItem href="/apis/access-control">Access Control API</NavItem>
+        <NavItem href="/apis/hooks">Hooks API</NavItem>
         <NavItem href="/apis/session">Session API</NavItem>
         <NavItem href="/apis/context">Context API</NavItem>
       </Section>

docs-next/pages/apis/access-control.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '../../components/Page';
+
+# Access Control API
+
+(coming soon)
+
+export default ({ children }) => <Markdown>{children}</Markdown>;

docs-next/pages/apis/system.mdx → docs-next/pages/apis/config.mdx

@@ -1,6 +1,6 @@
 import { Markdown } from '../../components/Page';
 
-# System API
+# System Configuration API
 
 The `keystone-next` CLI expects to find a module named `keystone.ts` with a default export of a Keystone system configuration returned from the function `config()`.
 
@@ -10,7 +10,7 @@ import { config } from '@keystone-next/keystone/schema';
 export default config({...});
 ```
 
-The `config` function accepts an object representing all the configurable parts of your system:
+The `config` function accepts an object representing all the configurable parts of the system:
 
 ```typescript
 export default config({
@@ -31,15 +31,15 @@ This type definition should be considered the source of truth for the available
 
 ## `lists`
 
-The `lists` config option is where you define the data model, or schema, of your Keystone system.
+The `lists` config option is where you define the data model, or schema, of the Keystone system.
 It has a TypeScript type of `ListSchemaConfig`.
-This is where you define and configure the `lists` and their `fields` of your data model.
+This is where you define and configure the `lists` and their `fields` of the data model.
 In general you will use the `createSchema()` function to create this configuration option.
 See the [Schema API](./schema) docs for details on how to use this function.
 
 ```typescript
 import type { ListSchemaConfig } from '@keystone-next/types';
-import { config, createSchema } from '@keystone-next/keystone/schema'
+import { config, createSchema } from '@keystone-next/keystone/schema';
 
 export default config({
   lists: createSchema({ ... }),
@@ -81,9 +81,9 @@ export default config({
     url: 'postgres://dbuser:dbpass@localhost:5432/keystone',
     onConnect: async context => { ... },
     // Optional advanced configuration
-    enableLogging: true;
-    getPrismaPath: ({ prismaSchema }) => '.prisma';
-    getDbSchemaName: ({ prismaSchema }) => 'prisma';
+    enableLogging: true,
+    getPrismaPath: ({ prismaSchema }) => '.prisma',
+    getDbSchemaName: ({ prismaSchema }) => 'prisma',
   },
   ...
 });
@@ -144,7 +144,6 @@ Options:
 
 - `isAccessAllowed` (default: `(context) => !!context.session`): This function controls whether a user is able to access the Admin UI.
   It takes a [`KeystoneContext`](./context) object as an argument.
-- `path` (default: `'admin'` ): The URL path where your Admin UI will be accessible from.
 
 Advanced configuration:
 
@@ -154,7 +153,6 @@ Advanced configuration:
 export default config({
   ui: {
     isAccessAllowed: async (context) => true,
-    path: 'admin',
     // Optional advanced configuration
     enableSessionItem: true,
     publicPages: [],
@@ -223,8 +221,8 @@ It has a TypeScript type of `GraphQLConfig`.
 
 Options:
 
-- `queryLimits` (default: `undefined`): Allows you to limit the number of results returned from a query to your GraphQL API.
-  See also the per-list `queryLimits` option in the [Schema API](./schema).
+- `queryLimits` (default: `undefined`): Allows you to limit the total number of results returned from a query to your GraphQL API.
+  See also the per-list `graphql.queryLimits` option in the [Schema API](./schema).
 
 ```typescript
 export default config({

docs-next/pages/apis/context.mdx

@@ -1,7 +1,7 @@
-import { Page } from '../../components/Page';
+import { Markdown } from '../../components/Page';
 
-# Keystone Context API
+# Context API
 
 (coming soon)
 
-export default ({ children }) => <Page>{children}</Page>;
+export default ({ children }) => <Markdown>{children}</Markdown>;

docs-next/pages/apis/fields.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '../../components/Page';
+
+# Fields API
+
+(coming soon)
+
+export default ({ children }) => <Markdown>{children}</Markdown>;

docs-next/pages/apis/hooks.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '../../components/Page';
+
+# Hooks API
+
+(coming soon)
+
+export default ({ children }) => <Markdown>{children}</Markdown>;

docs-next/pages/apis/schema.mdx

@@ -2,10 +2,219 @@ import { Markdown } from '../../components/Page';
 
 # Schema API
 
+The `lists` property of the [system configuration](./config) object is where you define the data model, or schema, of your Keystone system.
+To setup the `lists` property of the system configuration you need to use the `createSchema()` function.
+This function accepts an object with list names as keys, and `list()` configurations as values.
+
+```typescript
+import { config, createSchema, list } from '@keystone-next/keystone/schema';
+
+export default config({
+  lists: createSchema({
+    ListName: list({
+      fields: { ... },
+      idField: { ... },
+      access: { ... },
+      ui: { ... },
+      hooks: { ... },
+      graphql: { ... },
+      description: '...',
+    }),
+    ...
+  }),
+  ...
+});
 ```
-import type { ListSchemaConfig } from '@keystone-next/types';
+
+This document will explain the configuration options which can be used with the `list()` function.
+
+## `fields`
+
+The `fields` option defines the names, types, and configuration of the fields in the list.
+This configuration option takes an object with field names as keys, and configured field types as values.
+
+```typescript
+import { config, createSchema, list } from '@keystone-next/keystone/schema';
+import { text } from '@keystone-next/fields';
+
+export default config({
+  lists: createSchema({
+    ListName: list({
+      fields: {
+        fieldName: text({ ... }),
+        ...
+      },
+    }),
+    ...
+  }),
+  ...
+});
 ```
 
-(coming soon)
+For full details on the available field types and their configuration options please see the [Fields API](./fields).
+
+## `idField`
+
+The `idField` option lets you override the default ID field used by Keystone.
+By default the `prisma_postgresql` and `knex` adapters use `autoincrement`, and `mongoose` uses `mongoId`, as an ID field type.
+The default configuration (e.g. when `idField: undefined` ) is equivalent to:
+
+```typescript
+import { config, createSchema, list } from '@keystone-next/keystone/schema';
+import { autoincrement, mongoId } from '@keystone-next/fields';
+
+export default config({
+  lists: createSchema({
+    ListName: list({
+      fields: { ... },
+      // prisma_postgresql and knex adapters
+      idField: autoincrement({
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'hidden' },
+        },
+      }),
+      // mongoose adapter
+      idField: mongoId({
+        ui: {
+          createView: { fieldMode: 'hidden' },
+          itemView: { fieldMode: 'hidden' },
+        },
+      }),
+      ...
+    }),
+    ...
+  }),
+  ...
+});
+```
+
+These defaults hide this field in the `create` and `update` views in the Admin UI.
+You can override these defaults, or any other field config options, by providing a field type configured as needed.
+
+The `idField` will always be made available in the GraphQL API with a name of `id`.
+
+## `access`
+
+The `access` option defines the [Access Control](../guides/access-control) rules for the list.
+These rules determine which of the CRUD (create, read, update, delete) operations users are allowed to perform.
+
+See the [Access Control API](./access-control) for full details on the available access control options.
+
+## `ui`
+
+The `ui` option controls how the list is displayed and interacted with in the Admin UI.
+
+Options:
+
+- `labelField`: Selects the field which will be used as the label column in the Admin UI.
+  By default looks for a field called `'label'`, then falls back to `'name'`, then `'title'`, and finally `'id'`, which is guaranteed to exist.
+- `description` (default: `undefined`): Sets the list description displayed in the Admin UI.
+- `isHidden` (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 }` that returns a boolean value.
+- `hideCreate` (default: `false`): Controls whether the `create` button is available in the Admin UI for this list.
+  Can be either a boolean value, or an async function with an argument `{ session }` that returns a boolean value.
+- `hideDelete` (default: `false`): Controls whether the `delete` button is available in the Admin UI for this list.
+  Can be either a boolean value, or an async function with an argument `{ session }` that returns a boolean value.
+- `listView`: Controls the list view page of the Admin UI.
+  - `defaultFieldMode` (default: `'read'`): Controls the default mode of fields in the list view.
+    Can be overriden by per-field values in the `field.ui.listView.fieldMode` config.
+    See the [Fields API](./fields) for details.
+    Can be one of `['read', 'hidden']`, or an async function with an argument `{ session }` that returns one of `['read', 'hidden']`.
+  - `initialColumns` (default: `[labelField]`). A list of field names to display in columns in the list view. By default only the label column, as determined by `labelField`, is shown.
+  - `initialSort` (default: `undefined`): Sets the field and direction to be used to initially sort the data in the list view.
+    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: `50`): Sets the number of items to show per page in the list view.
+- `createView`: Controls the create view page of the Admin UI.
+  - `defaultFieldMode` (default: `'edit'`):
+    Can be overriden by per-field values in the `field.ui.createView.fieldMode` config.
+    See the [Fields API](./fields) for details.
+    Can be one of `['edit', 'hidden']`, or an async function with an argument `{ session }` that returns one of `['edit', 'hidden']`.
+- `itemView`: Controls the item view page of the Admin UI.
+  - `defaultFieldMode` (default: `'edit'`):
+    Can be overriden by per-field values in the `field.ui.itemView.fieldMode` config.
+    See the [Fields API](./fields) for details.
+    Can be one of `['edit', 'read', 'hidden']`, or an async function with an argument `{ session }` that returns one of `['edit', 'read', 'hidden']`.
+
+```typescript
+import { config, createSchema, list } from '@keystone-next/keystone/schema';
+import { text } from '@keystone-next/fields`;
+
+export default config({
+  lists: createSchema({
+    ListName: list({
+      fields: { name: text({ ... }) },
+      ui: {
+        labelField: 'name',
+        description: '...',
+        isHidden: ({ session }) => false,
+        hideCreate: ({ session }) => false,
+        hideDelete: ({ session }) => false,
+        listView: {
+          defaultFieldMode: ({ session }) => 'read',
+          initialColumns: ['name', ...],
+          initialSort: { field: 'name', direction: 'ASC' },
+          pageSize: 50,
+        },
+        createView: {
+          defaultFieldMode: ({ session }) => 'edit',
+        },
+        itemView: {
+          defaultFieldMode: ({ session, item }) => 'edit',
+        },
+      },
+    }),
+    ...
+  }),
+  ...
+});
+```
+
+
+## `hooks`
+
+The `hooks` option defines [hook](../guides/hooks) functions for the list.
+Hooks allow you to execute code at different stages of the mutation lifecycle.
+
+See the [Hooks API](./hooks) for full details on the available hook options.
+
+## `graphql`
+
+The `graphql` config option allows you to configures 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.
+- `itemQueryName` (default: List key, e.g `'User'`): Overrides the name used in singular mutations and queries (e.g. `User`, `updateUser`, etc).
+- `listQueryName`: (default: Pluralised list key, e.g. `'Users'`): Overrides the name used in multiple mutations and queries (e.g. `allUsers`, `updateUsers`, etc).
+- `queryLimits` (default: `undefined`): Allows you to limit the number of results returned from a query to this list in the GraphQL API.
+  See also the global `graphql.queryLimits` option in the [System Configuration API](./config).
+
+```typescript
+import { config, createSchema, list } from '@keystone-next/keystone/schema';
+
+export default config({
+  lists: createSchema({
+    ListName: list({
+      graphql: {
+        description: '...',
+        itemQueryName: '...',
+        listQueryName: '...',
+        queryLimits: { maxResults: 100 },
+      },
+      ...
+    }),
+    ...
+  }),
+  ...
+});
+```
+
+## `description`
+
+The `description` option defines a string which will be used as a description in the Admin UI and GraphQL API docs.
+This option can be individually overriden by the `graphql.description` or `ui.description` options.
 
 export default ({ children }) => <Markdown>{children}</Markdown>;

docs-next/pages/guides/access-control.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '../../components/Page';
+
+# Access Control
+
+(coming soon)
+
+export default ({ children }) => <Markdown>{children}</Markdown>;

docs-next/pages/guides/cli.mdx

@@ -31,7 +31,7 @@ These different modes support different phases of your project life-cycle.
 The different modes differ in how they interact with your database and with your Admin UI application.
 
 Note: All the **run** commands expect to find a module called `keystone.ts` with a default export which returns a system configuration `config()` from `@keystone-next/keystone/schema`.
-See the [System Configuration API](../apis/system) for details on how to configure a Keystone system.
+See the [System Configuration API](../apis/config) for details on how to configure a Keystone system.
 
 #### `keystone-next prototype` (default)
 

docs-next/pages/guides/hooks.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '../../components/Page';
+
+# Hooks
+
+(coming soon)
+
+export default ({ children }) => <Markdown>{children}</Markdown>;

packages-next/admin-ui/TODO.md

@@ -15,7 +15,7 @@
   - [x] mongoId in fields package
   - [x] `idField` option
   - [x] disallow `id` field in fields object
-  - [x] default `idField` to `autoIncrement` for Knex(& Prisma but we don't handle Prisma in the new interfaces just yet so not gonna actually do that yet) and `mongoId` for Mongoose with fieldMode: 'hidden' for itemView and createView
+  - [x] default `idField` to `autoIncrement` for Knex & Prisma and `mongoId` for Mongoose with fieldMode: 'hidden' for itemView and createView
 - [x] Remove usage of label field in Admin UI and remove it from the GraphQL schema(~~with a feature flag to turn it back on~~ and allow Keystone fields named `_label_` so users can create a virtual field for `_label_`)
 - [ ] Ensure support for field descriptions in the create and item views
 - [ ] Figure out what to support for custom list views