@nixxie-cms/core 1.0.0

package/src/types/admin-meta.ts

@@ -0,0 +1,218 @@
+import type { allIcons as KeystarIcons } from '@keystar/ui/icon/all'
+import type { ReactElement } from 'react'
+
+import type { ConditionalFilter, ConditionalFilterCase, ListSortDescriptor } from './config'
+import type { BaseListTypeInfo } from './type-info'
+import type { GraphQLNames, JSONValue } from './utils'
+
+export type NavigationProps = {
+  lists: ListMeta[]
+}
+
+export type AdminConfig = {
+  components?: {
+    Logo?: (props: object) => ReactElement
+    Navigation?: (props: NavigationProps) => ReactElement
+  }
+}
+
+export type FieldControllerConfig<FieldMeta extends JSONValue | undefined = undefined> = {
+  listKey: string
+  fieldKey: string
+
+  label: string
+  description: string
+  customViews: Record<string, any>
+  fieldMeta: FieldMeta
+}
+
+type FilterTypeDeclaration<Value extends JSONValue> = {
+  readonly label: string
+  readonly initialValue: Value
+}
+
+export type FilterTypeToFormat<Value extends JSONValue> = {
+  readonly type: string
+  readonly label: string
+  readonly value: Value
+}
+
+export type FieldController<
+  FormState,
+  FilterValue extends JSONValue = never,
+  GraphQLFilterValue = never,
+> = {
+  fieldKey: string
+
+  label: string
+  description: string
+
+  defaultValue: FormState
+  deserialize: (item: any) => FormState // TODO: unknown
+  serialize: (formState: FormState) => any // TODO: unknown
+  validate?: (formState: FormState, opts: { isRequired: boolean }) => boolean
+
+  graphqlSelection: string
+  filter?: {
+    types: Record<string, FilterTypeDeclaration<FilterValue>>
+    parseGraphQL(value: GraphQLFilterValue & {}): { type: string; value: FilterValue }[]
+    graphql(type: { type: string; value: FilterValue }): Record<string, any>
+    Label(type: FilterTypeToFormat<FilterValue>): string | ReactElement | null
+    Filter(props: {
+      autoFocus?: boolean
+      forceValidation?: boolean
+      context: 'add' | 'edit'
+      onChange(value: FilterValue): void
+      type: string
+      // TODO: could be derived `filter.types[type].label`?
+      typeLabel?: string
+      value: FilterValue
+    }): ReactElement | null
+  }
+}
+
+// TODO: duplicate, reference core/src/lib/admin-meta.ts
+export type FieldMeta = {
+  key: string
+  label: string
+  description: string
+  fieldMeta: JSONValue | null
+  viewsIndex: number
+  customViewsIndex: number | null
+  views: FieldViews[number]
+  controller: FieldController<unknown, JSONValue>
+  isFilterable: boolean
+  isOrderable: boolean
+
+  search: 'default' | 'insensitive' | null
+  isNonNull: ('read' | 'create' | 'update')[]
+  createView: {
+    fieldMode: ConditionalFilter<'edit' | 'hidden', 'hidden', BaseListTypeInfo>
+    isRequired: ConditionalFilterCase<BaseListTypeInfo>
+  }
+  itemView: {
+    fieldMode: ConditionalFilter<'edit' | 'read' | 'hidden', 'read' | 'hidden', BaseListTypeInfo>
+    fieldPosition: 'form' | 'sidebar'
+    isRequired: ConditionalFilterCase<BaseListTypeInfo>
+  }
+  listView: {
+    fieldMode: 'read' | 'hidden'
+  }
+}
+
+export type FieldGroupMeta = {
+  label: string
+  description: string
+  fields: FieldMeta[]
+}
+
+export type ActionMeta = {
+  key: string
+  graphql: {
+    arguments: readonly { name: string; type: string; source: { itemField: string } | null }[]
+    names: {
+      one: string
+      many: string
+    }
+  }
+
+  label: string
+  icon: keyof typeof KeystarIcons | null
+  messages: {
+    promptTitle: string
+    promptTitleMany: string
+    prompt: string
+    promptMany: string
+    promptConfirmLabel: string
+    promptConfirmLabelMany: string
+    fail: string
+    failMany: string
+    success: string
+    successMany: string
+  }
+  itemView: {
+    actionMode: ConditionalFilter<
+      'enabled' | 'disabled' | 'hidden',
+      'disabled' | 'hidden',
+      BaseListTypeInfo
+    >
+    navigation: 'follow' | 'refetch' | 'return'
+    hidePrompt: boolean
+    hideToast: boolean
+  }
+  listView: {
+    actionMode: ConditionalFilter<
+      'enabled' | 'disabled' | 'hidden',
+      'disabled' | 'hidden',
+      BaseListTypeInfo
+    >
+  }
+}
+
+export type ListMeta = {
+  key: string
+  label: string
+  singular: string
+  plural: string
+  path: string
+
+  labelField: string
+  fields: { [key: string]: FieldMeta }
+  groups: FieldGroupMeta[]
+  actions: ActionMeta[]
+  graphql: {
+    names: GraphQLNames
+  }
+
+  pageSize: number
+  initialColumns: string[]
+  initialSearchFields: string[]
+  initialSort: ListSortDescriptor<string>
+  initialFilter: JSONValue
+  isSingleton: boolean
+
+  hideNavigation: boolean
+  hideCreate: boolean
+  hideDelete: boolean
+}
+
+export type Item = {
+  [key: string]: unknown
+}
+
+export type FieldProps<FieldControllerFn extends (...args: any) => FieldController<any, any>> = {
+  autoFocus?: boolean
+  field: ReturnType<FieldControllerFn>
+  isRequired: boolean
+  /**
+   * Will be true when the user has clicked submit and
+   * the validate function on the field controller has returned false
+   */
+  forceValidation?: boolean
+  onChange?(value: ReturnType<ReturnType<FieldControllerFn>['deserialize']>): void
+  value: ReturnType<ReturnType<FieldControllerFn>['deserialize']>
+  itemValue: Item
+}
+
+export type FieldViews = Record<
+  string,
+  {
+    Field: (props: FieldProps<any>) => ReactElement | null
+    Cell: CellComponent
+    controller: (args: FieldControllerConfig<any>) => FieldController<unknown, JSONValue>
+    allowedExportsOnCustomViews?: string[]
+  }
+>
+
+export type CellComponent<
+  FieldControllerFn extends (...args: any) => FieldController<any, any> = () => FieldController<
+    any,
+    any
+  >,
+> = {
+  (props: {
+    value: any // TODO: T
+    field: ReturnType<FieldControllerFn>
+    item: Record<string, unknown>
+  }): ReactElement | null
+}

package/src/types/config/access-control.ts

@@ -0,0 +1,186 @@
+import type { NixxieContext } from '../context'
+import type { BaseListTypeInfo } from '../type-info'
+import type { MaybePromise } from '../utils'
+
+export type BaseAccessArgs<ListTypeInfo extends BaseListTypeInfo> = {
+  context: NixxieContext<ListTypeInfo['all']>
+  session?: ListTypeInfo['all']['session'] // TODO: use context.session, remove in breaking change
+  listKey: ListTypeInfo['key']
+}
+
+export type AccessOperation = 'create' | 'query' | 'update' | 'delete'
+export type FilterOperation = 'query' | 'update' | 'delete'
+export type ItemOperation = 'create' | 'update' | 'delete'
+
+export type ListOperationAccessControl<
+  Operation extends AccessOperation,
+  ListTypeInfo extends BaseListTypeInfo,
+> = (args: BaseAccessArgs<ListTypeInfo> & { operation: Operation }) => MaybePromise<boolean>
+
+export type ListFilterAccessControl<
+  Operation extends FilterOperation,
+  ListTypeInfo extends BaseListTypeInfo,
+> = (
+  args: BaseAccessArgs<ListTypeInfo> & { operation: Operation }
+) => MaybePromise<boolean | ListTypeInfo['inputs']['where']>
+
+export type ListItemAccessControl<
+  Operation extends ItemOperation,
+  ListTypeInfo extends BaseListTypeInfo,
+> = (
+  args: BaseAccessArgs<ListTypeInfo> &
+    {
+      create: {
+        operation: 'create'
+
+        /**
+         * The input passed in from the GraphQL API
+         */
+        inputData: ListTypeInfo['inputs']['create']
+      }
+      update: {
+        operation: 'update'
+
+        /**
+         * The input passed in from the GraphQL API
+         */
+        inputData: ListTypeInfo['inputs']['update']
+
+        /**
+         * The item being updated
+         */
+        item: ListTypeInfo['item']
+      }
+      delete: {
+        operation: 'delete'
+
+        /**
+         * The item being deleted
+         */
+        item: ListTypeInfo['item']
+      }
+    }[Operation]
+) => MaybePromise<boolean>
+
+export type CreateListItemAccessControl<ListTypeInfo extends BaseListTypeInfo> =
+  ListItemAccessControl<'create', ListTypeInfo>
+export type UpdateListItemAccessControl<ListTypeInfo extends BaseListTypeInfo> =
+  ListItemAccessControl<'update', ListTypeInfo>
+export type DeleteListItemAccessControl<ListTypeInfo extends BaseListTypeInfo> =
+  ListItemAccessControl<'delete', ListTypeInfo>
+
+type ListAccessControlFunction<ListTypeInfo extends BaseListTypeInfo> = (
+  args: BaseAccessArgs<ListTypeInfo> & { operation: AccessOperation }
+) => MaybePromise<boolean>
+
+type ListAccessControlObject<ListTypeInfo extends BaseListTypeInfo> = {
+  // these functions should return `true` if access is allowed or `false` if access is denied.
+  operation:
+    | ListOperationAccessControl<AccessOperation, ListTypeInfo>
+    | {
+        query: ListOperationAccessControl<'query', ListTypeInfo>
+        create: ListOperationAccessControl<'create', ListTypeInfo>
+        update: ListOperationAccessControl<'update', ListTypeInfo>
+        delete: ListOperationAccessControl<'delete', ListTypeInfo>
+      }
+
+  // The 'filter' rules can return either:
+  // - a filter. In this case, the operation can proceed, but the filter will be additionally applied when updating/reading/deleting
+  //   which may make it appear that some of the items don't exist.
+  // - boolean true/false. If false, treated as a filter that never matches.
+  filter?: {
+    query?: ListFilterAccessControl<'query', ListTypeInfo>
+    // create?: not supported
+    update?: ListFilterAccessControl<'update', ListTypeInfo>
+    delete?: ListFilterAccessControl<'delete', ListTypeInfo>
+  }
+
+  // These rules are applied to each item being operated on individually. They return `true` or `false`,
+  // and if false, an access denied error will be returned for the individual operation.
+  item?: {
+    // read?: not supported // TODO: why not
+    create?: ListItemAccessControl<'create', ListTypeInfo>
+    update?: ListItemAccessControl<'update', ListTypeInfo>
+    delete?: ListItemAccessControl<'delete', ListTypeInfo>
+  }
+}
+
+// List level access control lets you set permissions on the autogenerated CRUD API for each list.
+//
+// * `operation` access lets you check the information in the `context` and `session` objects to decide if the
+// user is allow to access the list.
+// * `filter` access lets you provide a GraphQL filter which defines the items the user is allowed to access.
+// * `item` access lets you write a function which inspects the provided input data and the existing object (if it exists)
+// and make a decision based on this extra data.
+//
+// If access is denied due to any of the access control methods then the following response will be returned from the GraphQL API:
+//   Mutations:
+//     - Single operations will return `null` and return an access denied error
+//     - Multi operations will return a data array with `null` values for the items which have access denied.
+//       Access denied errors will be return for each `null` items.
+//   Queries:
+//     - Single item queries will return `null` with no errors.
+//     - Many item queries will filter out those items which have access denied, with no errors.
+//     - Count queries will only count those items for which access is not denied, with no errors.
+//
+export type ListAccessControl<ListTypeInfo extends BaseListTypeInfo> =
+  | ListAccessControlFunction<ListTypeInfo>
+  | ListAccessControlObject<ListTypeInfo>
+
+// Field Access
+export type FieldAccessControlFunction<Args> = (args: Args) => MaybePromise<boolean>
+
+export type FieldCreateItemAccessArgs<ListTypeInfo extends BaseListTypeInfo> =
+  BaseAccessArgs<ListTypeInfo> & {
+    operation: 'create'
+    fieldKey: string
+    /**
+     * The input passed in from the GraphQL API
+     */
+    inputData: ListTypeInfo['inputs']['create']
+  }
+
+export type FieldReadItemAccessArgs<ListTypeInfo extends BaseListTypeInfo> =
+  BaseAccessArgs<ListTypeInfo> & {
+    operation: 'read'
+    fieldKey: string
+    /**
+     * The item being read
+     */
+    item: ListTypeInfo['item']
+  }
+
+export type FieldUpdateItemAccessArgs<ListTypeInfo extends BaseListTypeInfo> =
+  BaseAccessArgs<ListTypeInfo> & {
+    operation: 'update'
+    fieldKey: string
+    /**
+     * The item being updated
+     */
+    item: ListTypeInfo['item']
+    /**
+     * The input passed in from the GraphQL API
+     */
+    inputData: ListTypeInfo['inputs']['update']
+  }
+
+export type FieldAccessControl<ListTypeInfo extends BaseListTypeInfo> =
+  | FieldAccessControlFunction<
+      | FieldReadItemAccessArgs<ListTypeInfo>
+      | FieldCreateItemAccessArgs<ListTypeInfo>
+      | FieldUpdateItemAccessArgs<ListTypeInfo>
+      // delete: not supported
+    >
+  | {
+      read?: FieldAccessControlFunction<FieldReadItemAccessArgs<ListTypeInfo>>
+      create?: FieldAccessControlFunction<FieldCreateItemAccessArgs<ListTypeInfo>>
+      update?: FieldAccessControlFunction<FieldUpdateItemAccessArgs<ListTypeInfo>>
+      // delete: not supported
+    }
+
+// Action Access
+export type ActionAccessControlFunction<ListTypeInfo extends BaseListTypeInfo> = (
+  args: BaseAccessArgs<ListTypeInfo> & {
+    actionKey: string
+  }
+) => MaybePromise<boolean>

package/src/types/config/fields.ts

@@ -0,0 +1,96 @@
+import type { CacheHint } from '@apollo/cache-control-types'
+import type { NixxieContext } from '..'
+import type { FieldTypeFunc } from '../next-fields'
+import type { BaseListTypeInfo } from '../type-info'
+import type { FieldAccessControl } from './access-control'
+import type { FieldHooks } from './hooks'
+import type {
+  MaybeBooleanSessionFunctionWithFilter,
+  MaybeFieldFunction,
+  MaybeItemFieldFunction,
+  MaybeItemFieldFunctionWithFilter,
+  MaybeSessionFunction,
+  MaybeSessionFunctionWithFilter,
+} from './lists'
+
+export type BaseFields<ListTypeInfo extends BaseListTypeInfo> = {
+  [key: string]: FieldTypeFunc<ListTypeInfo>
+}
+
+export type FilterOrderArgs<ListTypeInfo extends BaseListTypeInfo> = {
+  context: NixxieContext<ListTypeInfo['all']>
+  session?: ListTypeInfo['all']['session']
+  listKey: ListTypeInfo['key']
+  fieldKey: ListTypeInfo['fields']
+}
+
+export type BaseFieldTypeInfo = {
+  item: any
+  inputs: {
+    create: any
+    update: any
+    where: any
+    uniqueWhere: any
+    orderBy: any
+  }
+  prisma: {
+    create: any
+    update: any
+  }
+}
+
+export type CommonFieldConfig<
+  ListTypeInfo extends BaseListTypeInfo,
+  FieldTypeInfo extends BaseFieldTypeInfo,
+> = {
+  access?: FieldAccessControl<ListTypeInfo>
+  hooks?: FieldHooks<ListTypeInfo, FieldTypeInfo>
+  ui?: {
+    label?: string
+    description?: string
+    views?: string
+    createView?: {
+      fieldMode?: MaybeSessionFunctionWithFilter<'edit' | 'hidden', 'hidden', ListTypeInfo>
+      isRequired?: MaybeBooleanSessionFunctionWithFilter<ListTypeInfo>
+    }
+    itemView?: {
+      fieldMode?: MaybeItemFieldFunctionWithFilter<
+        'edit' | 'read' | 'hidden',
+        'read' | 'hidden',
+        ListTypeInfo,
+        FieldTypeInfo
+      >
+      fieldPosition?: MaybeItemFieldFunction<'form' | 'sidebar', ListTypeInfo, FieldTypeInfo>
+      isRequired?: MaybeBooleanSessionFunctionWithFilter<ListTypeInfo>
+    }
+    listView?: {
+      fieldMode?: MaybeSessionFunction<'read' | 'hidden', ListTypeInfo>
+    }
+  }
+  graphql?: {
+    cacheHint?: CacheHint
+    isNonNull?:
+      | boolean
+      | {
+          // whether this field is non-nullable on the {List} GraphQL type
+          read?: boolean
+          // whether this field is non-nullable on the {List}CreateInput GraphQL type
+          create?: boolean
+          // whether this field is non-nullable on the {List}UpdateInput GraphQL type
+          update?: boolean
+        }
+
+    omit?:
+      | boolean
+      | {
+          // whether this field is omitted from the {List} GraphQL type
+          read?: boolean
+          // whether this field is omitted from the {List}CreateInput GraphQL type
+          create?: boolean
+          // whether this field is omitted from the {List}UpdateInput GraphQL type
+          update?: boolean
+        }
+  }
+  isFilterable?: MaybeFieldFunction<ListTypeInfo>
+  isOrderable?: MaybeFieldFunction<ListTypeInfo>
+}