Add field descriptions (#7578)

* Add field descriptions Co-authored-by: Mitchell Hamilton <[email protected]> * updates for graphql * schema update for example document field * Update for tests * update tests * Add description to Cards of relationship field * Little things * Changesets Co-authored-by: Mitchell Hamilton <[email protected]> Co-authored-by: mitchellhamilton <[email protected]>
keystonejs · Jun 10, 2022 · 29db9b5 · 29db9b5
1 parent 52e5477
commit 29db9b5
Show file tree

Hide file tree

Showing 64 changed files with 210 additions and 53 deletions.
diff --git a/.changeset/fast-coins-occur.md b/.changeset/fast-coins-occur.md
@@ -0,0 +1,5 @@
+---
+'@keystone-ui/fields': minor
+---
+
+Added `FieldDescription` component
diff --git a/.changeset/spicy-dragons-poke.md b/.changeset/spicy-dragons-poke.md
@@ -0,0 +1,7 @@
+---
+'@keystone-6/cloudinary': minor
+'@keystone-6/core': minor
+'@keystone-6/fields-document': minor
+---
+
+Added `ui.description` option to fields to show a description below the label in the Admin UI
diff --git a/design-system/packages/fields/src/FieldDescription.tsx b/design-system/packages/fields/src/FieldDescription.tsx
@@ -0,0 +1,26 @@
+/** @jsxRuntime classic */
+/** @jsx jsx */
+
+import { jsx, useTheme } from '@keystone-ui/core';
+
+type FieldDescriptionProps = {
+  id: string;
+  children: string | null;
+};
+
+export const FieldDescription = (props: FieldDescriptionProps) => {
+  const { spacing, palette } = useTheme();
+  if (props.children === null) {
+    return null;
+  }
+  return (
+    <div
+      css={{
+        color: palette.neutral700,
+        marginBottom: spacing.small,
+        minWidth: 120,
+      }}
+      {...props}
+    />
+  );
+};
diff --git a/design-system/packages/fields/src/components/ControlLabel.tsx b/design-system/packages/fields/src/components/ControlLabel.tsx
@@ -38,7 +38,6 @@ export const ControlLabel = ({
             fontSize: size.fontSize,
             lineHeight: typography.leading.tight,
             marginLeft: spacing.small,
-            paddingTop: spacing.xsmall,
             userSelect: 'none',
           }}
         >

diff --git a/design-system/packages/fields/src/index.ts b/design-system/packages/fields/src/index.ts
@@ -11,6 +11,7 @@ export { Checkbox, CheckboxControl } from './Checkbox';
 export { FieldContainer } from './FieldContainer';
 export { FieldLabel } from './FieldLabel';
 export { FieldLegend } from './FieldLegend';
+export { FieldDescription } from './FieldDescription';
 export { Radio } from './Radio';
 export { Switch } from './Switch';
 export { TextArea } from './TextArea';

diff --git a/examples-staging/assets-local/schema.graphql b/examples-staging/assets-local/schema.graphql
@@ -322,6 +322,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/assets-s3/schema.graphql b/examples-staging/assets-s3/schema.graphql
@@ -322,6 +322,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/auth/schema.graphql b/examples-staging/auth/schema.graphql
@@ -200,6 +200,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/basic/schema.graphql b/examples-staging/basic/schema.graphql
@@ -496,6 +496,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/ecommerce/schema.graphql b/examples-staging/ecommerce/schema.graphql
@@ -961,6 +961,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/embedded-nextjs/schema.graphql b/examples-staging/embedded-nextjs/schema.graphql
@@ -152,6 +152,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/graphql-api-endpoint/schema.graphql b/examples-staging/graphql-api-endpoint/schema.graphql
@@ -435,6 +435,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples-staging/roles/schema.graphql b/examples-staging/roles/schema.graphql
@@ -414,6 +414,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/blog/schema.graphql b/examples/blog/schema.graphql
@@ -281,6 +281,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/custom-admin-ui-logo/schema.graphql b/examples/custom-admin-ui-logo/schema.graphql
@@ -281,6 +281,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/custom-admin-ui-navigation/schema.graphql b/examples/custom-admin-ui-navigation/schema.graphql
@@ -281,6 +281,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/custom-admin-ui-pages/schema.graphql b/examples/custom-admin-ui-pages/schema.graphql
@@ -281,6 +281,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/custom-field-view/schema.graphql b/examples/custom-field-view/schema.graphql
@@ -284,6 +284,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/custom-field/schema.graphql b/examples/custom-field/schema.graphql
@@ -297,6 +297,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/custom-field/stars-field/views.tsx b/examples/custom-field/stars-field/views.tsx
@@ -1,5 +1,5 @@
 import React from 'react';
-import { FieldContainer, FieldLabel, TextInput } from '@keystone-ui/fields';
+import { FieldContainer, FieldDescription, FieldLabel, TextInput } from '@keystone-ui/fields';
 import { CellLink, CellContainer } from '@keystone-6/core/admin-ui/components';
 
 import {
@@ -15,6 +15,7 @@ import { StarsInput } from './stars-input';
 export const Field = ({ field, value, onChange, autoFocus }: FieldProps<typeof controller>) => (
   <FieldContainer as="fieldset">
     <FieldLabel as="legend">{field.label}</FieldLabel>
+    <FieldDescription id={`${field.path}-description`}>{field.description}</FieldDescription>
     <StarsInput maxStars={field.maxStars} onChange={onChange} value={value} autoFocus={autoFocus} />
   </FieldContainer>
 );
@@ -48,6 +49,7 @@ export const controller = (
     maxStars: config.fieldMeta.maxStars,
     path: config.path,
     label: config.label,
+    description: config.description,
     graphqlSelection: config.path,
     defaultValue: null,
     deserialize: data => {

diff --git a/examples/default-values/schema.graphql b/examples/default-values/schema.graphql
@@ -281,6 +281,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/document-field/schema.graphql b/examples/document-field/schema.graphql
@@ -296,6 +296,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/extend-graphql-schema-graphql-ts/schema.graphql b/examples/extend-graphql-schema-graphql-ts/schema.graphql
@@ -290,6 +290,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/extend-graphql-schema-nexus/schema.graphql b/examples/extend-graphql-schema-nexus/schema.graphql
@@ -283,6 +283,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/extend-graphql-schema/schema.graphql b/examples/extend-graphql-schema/schema.graphql
@@ -312,6 +312,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/json/schema.graphql b/examples/json/schema.graphql
@@ -250,6 +250,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/rest-api/schema.graphql b/examples/rest-api/schema.graphql
@@ -282,6 +282,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/task-manager/schema.graphql b/examples/task-manager/schema.graphql
@@ -282,6 +282,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/testing/schema.graphql b/examples/testing/schema.graphql
@@ -324,6 +324,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/virtual-field/schema.graphql b/examples/virtual-field/schema.graphql
@@ -292,6 +292,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/examples/with-auth/schema.graphql b/examples/with-auth/schema.graphql
@@ -324,6 +324,7 @@ type KeystoneAdminUIListMeta {
 type KeystoneAdminUIFieldMeta {
   path: String!
   label: String!
+  description: String
   isOrderable: Boolean!
   isFilterable: Boolean!
   fieldMeta: JSON

diff --git a/packages/cloudinary/src/views/Field.tsx b/packages/cloudinary/src/views/Field.tsx
@@ -4,7 +4,7 @@
 import { jsx, Stack, useTheme } from '@keystone-ui/core';
 import { useEffect, useMemo, useRef, useState } from 'react';
 
-import { FieldContainer, FieldLabel } from '@keystone-ui/fields';
+import { FieldContainer, FieldDescription, FieldLabel } from '@keystone-ui/fields';
 import { Pill } from '@keystone-ui/pill';
 import { Button } from '@keystone-ui/button';
 import { FieldProps } from '@keystone-6/core/types';
@@ -48,6 +48,7 @@ export function Field({
   return (
     <FieldContainer>
       <FieldLabel>{field.label}</FieldLabel>
+      <FieldDescription id={`${field.path}-description`}>{field.description}</FieldDescription>
       {value.kind === 'from-server' || value.kind === 'upload' ? (
         <Stack gap="small">
           {imagePath && errorMessage === undefined && <Image src={imagePath} alt={field.path} />}

diff --git a/packages/cloudinary/src/views/index.tsx b/packages/cloudinary/src/views/index.tsx
@@ -73,6 +73,7 @@ export const controller = (config: FieldControllerConfig): CloudinaryImageContro
   return {
     path: config.path,
     label: config.label,
+    description: config.description,
     graphqlSelection: `${config.path} {
         id
         filename

diff --git a/packages/core/src/___internal-do-not-use-will-break-in-patch/admin-ui/id-field-view.tsx b/packages/core/src/___internal-do-not-use-will-break-in-patch/admin-ui/id-field-view.tsx
@@ -35,6 +35,7 @@ export const controller = (
   return {
     path: config.path,
     label: config.label,
+    description: config.description,
     graphqlSelection: config.path,
     idFieldKind: config.fieldMeta.kind,
     defaultValue: undefined,

diff --git a/packages/core/src/admin-ui/admin-meta-graphql.ts b/packages/core/src/admin-ui/admin-meta-graphql.ts
@@ -31,6 +31,7 @@ export const staticAdminMetaQuery = gql`
             __typename
             path
             label
+            description
             fieldMeta
             viewsIndex
             customViewsIndex
@@ -91,6 +92,7 @@ export type StaticAdminMetaQuery = {
           __typename: 'KeystoneAdminUIFieldMeta';
           path: string;
           label: string;
+          description: Maybe<string>;
           fieldMeta: Maybe<JSONValue>;
           viewsIndex: number;
           customViewsIndex: Maybe<number>;

diff --git a/packages/core/src/admin-ui/system/createAdminMeta.ts b/packages/core/src/admin-ui/system/createAdminMeta.ts
@@ -130,6 +130,7 @@ export function createAdminMeta(
       }
       adminMetaRoot.listsByKey[key].fields.push({
         label: field.label ?? humanize(fieldKey),
+        description: field.ui?.description ?? null,
         viewsIndex: getViewId(field.views),
         customViewsIndex: field.ui?.views === undefined ? null : getViewId(field.ui.views),
         fieldMeta: null,

diff --git a/packages/core/src/admin-ui/system/getAdminMetaSchema.ts b/packages/core/src/admin-ui/system/getAdminMetaSchema.ts
@@ -37,6 +37,7 @@ export function getAdminMetaSchema({
     fields: {
       path: graphql.field({ type: graphql.nonNull(graphql.String) }),
       label: graphql.field({ type: graphql.nonNull(graphql.String) }),
+      description: graphql.field({ type: graphql.String }),
       isOrderable: graphql.field({
         type: graphql.nonNull(graphql.Boolean),
         resolve(rootVal, args, context) {

diff --git a/packages/core/src/admin-ui/utils/useAdminMeta.tsx b/packages/core/src/admin-ui/utils/useAdminMeta.tsx
@@ -117,6 +117,7 @@ export function useAdminMeta(adminMetaHash: string, fieldViews: FieldViews) {
             listKey: list.key,
             fieldMeta: field.fieldMeta,
             label: field.label,
+            description: field.description,
             path: field.path,
             customViews,
           }),