Merge branch 'master' into change-image-ref

.changeset/afraid-maps-brake.md

@@ -0,0 +1,5 @@
+---
+'@keystone-next/admin-ui': minor
+---
+
+Added symlink logic for file storage.

.changeset/dirty-bananas-lay.md

@@ -0,0 +1,5 @@
+---
+'@keystone-next/fields': minor
+---
+
+Added file field type.

.changeset/silent-stingrays-check.md

@@ -0,0 +1,5 @@
+---
+'@keystone-next/utils-legacy': minor
+---
+
+Added `getFileRef` and `parseFileRef` to exported utilities.

.changeset/six-dodos-wink.md

@@ -0,0 +1,5 @@
+---
+'@keystone-next/api-tests-legacy': minor
+---
+
+Added beforeEach and afterEach hooks to test suite, added file config defaults.

.gitignore

@@ -89,6 +89,7 @@ dist/
 
 # Used by the image field type tests as a storage target
 tmp_test_images/
+tmp_test_files/
 
 # Created by https://www.gitignore.io/api/vim
 # Edit at https://www.gitignore.io/?templates=vim

docs/pages/apis/config.mdx

@@ -253,6 +253,34 @@ export default config({
 
 See the [schema extension guide](../guides/schema-extension) for more details on how to use `graphQLSchemaExtension()` to extend your GraphQL API.
 
+## files
+
+Keystone supports file handling via the [`file`](./fields#file) field type.
+In order to use this field type you need to configure Keystone with information about where your files will be stored and served from.
+At the moment Keystone supports storing files on the local filesystem, and is agnostic about how files are served.
+
+```typescript
+import { config } from '@keystone-next/keystone/schema';
+
+export default config({
+  files: {
+    upload: 'local',
+    local: {
+      storagePath: 'public/files',
+      baseUrl: '/files',
+    },
+  }
+  /* ... */
+});
+```
+
+Options:
+
+- `upload`: The storage target when uploading files. Currently only `local` is supported.
+- `local`: Configuration options when using the `local` storage target.
+  - `storagePath`: The path local files are uploaded to.
+  - `baseUrl`: The base of the URL local files will be served from, outside of keystone.
+
 ## images
 
 Keystone supports image handling via the [`image`](./fields#image) field type.

docs/pages/apis/fields.mdx

@@ -551,7 +551,33 @@ File types allow you to upload different types of files to your Keystone system.
 
 ### file
 
-(coming soon)
+A `file` field represents a file of any type.
+
+See [`config.files`](./config#files) for details on how to configure your Keystone system with support for the `file` field type.
+
+Options:
+
+- `isRequired` (default: `false`): If `true` then this field can never be set to `null`.
+
+```typescript
+import { config, createSchema, list } from '@keystone-next/keystone/schema';
+import { file } from '@keystone-next/fields';
+
+export default config({
+  lists: createSchema({
+    ListName: list({
+      fields: {
+        repo: file({
+          isRequired: true,
+        }),
+        /* ... */
+      },
+    }),
+    /* ... */
+  }),
+  /* ... */
+});
+```
 
 ### image
 

examples/basic/keystone.ts

@@ -37,6 +37,7 @@ export default auth.withAuth(
       // isAccessAllowed,
     },
     images: { upload: 'local' },
+    files: { upload: 'local' },
     lists,
     extendGraphqlSchema,
     session: withItemData(

examples/basic/schema.ts

@@ -8,6 +8,7 @@ import {
   select,
   virtual,
   image,
+  file,
 } from '@keystone-next/fields';
 import { document } from '@keystone-next/fields-document';
 // import { cloudinaryImage } from '@keystone-next/cloudinary';
@@ -43,7 +44,9 @@ export const lists = createSchema({
       name: text({ isRequired: true }),
       /** Email is used to log into the system. */
       email: text({ isRequired: true, isUnique: true }),
+      /** Avatar upload for the users profile, stored locally */
       avatar: image(),
+      attachment: file(),
       /** Used to log in. */
       password: password(),
       /** Administrators have more access to various lists and fields. */

packages-next/admin-ui/src/system/generateAdminUI.ts

@@ -52,15 +52,24 @@ export const generateAdminUI = async (
 ) => {
   // Nuke any existing files in our target directory
   await fs.remove(projectAdminPath);
+  const publicDirectory = Path.join(projectAdminPath, 'public');
 
-  if (config.images) {
-    const publicDirectory = Path.join(projectAdminPath, 'public');
+  if (config.images || config.files) {
     await fs.mkdir(publicDirectory, { recursive: true });
+  }
+
+  if (config.images) {
     const storagePath = Path.resolve(config.images.local?.storagePath ?? './public/images');
     await fs.mkdir(storagePath, { recursive: true });
     await fs.symlink(storagePath, Path.join(publicDirectory, 'images'), 'junction');
   }
 
+  if (config.files) {
+    const storagePath = Path.resolve(config.files.local?.storagePath ?? './public/files');
+    await fs.mkdir(storagePath, { recursive: true });
+    await fs.symlink(storagePath, Path.join(publicDirectory, 'files'), 'junction');
+  }
+
   // Write out the files configured by the user
   const userPages = config.ui?.getAdditionalFiles?.map(x => x(config)) ?? [];
   const userFilesToWrite = (await Promise.all(userPages)).flat();

packages-next/fields/src/index.ts

@@ -1,14 +1,15 @@
+export { autoIncrement } from './types/autoIncrement';
 export { checkbox } from './types/checkbox';
+export { decimal } from './types/decimal';
+export { file } from './types/file';
+export { float } from './types/float';
+export { integer } from './types/integer';
+export { image } from './types/image';
+export { password } from './types/password';
 export { relationship } from './types/relationship';
+export { select } from './types/select';
 export { text } from './types/text';
-export { password } from './types/password';
 export { timestamp } from './types/timestamp';
-export { integer } from './types/integer';
-export { float } from './types/float';
-export { decimal } from './types/decimal';
-export { autoIncrement } from './types/autoIncrement';
-export { select } from './types/select';
 export { virtual } from './types/virtual';
 export { Implementation } from './Implementation';
 export type { FieldConfigArgs, FieldExtraArgs } from './Implementation';
-export { image } from './types/image';