@nixxie-cms/core 1.0.0

package/src/admin-ui/utils/Fields.tsx

@@ -0,0 +1,241 @@
+import { useSlotId } from '@react-aria/utils'
+import { type ReactNode, useId } from 'react'
+
+import { FieldButton } from '@keystar/ui/button'
+import { Icon } from '@keystar/ui/icon'
+import { chevronRightIcon } from '@keystar/ui/icon/icons/chevronRightIcon'
+import { HStack, VStack } from '@keystar/ui/layout'
+import { css, tokenSchema } from '@keystar/ui/style'
+import { Text } from '@keystar/ui/typography'
+
+import { textCursorInputIcon } from '@keystar/ui/icon/icons/textCursorInputIcon'
+import type {
+  BaseListTypeInfo,
+  ConditionalFilter,
+  ConditionalFilterCase,
+  FieldGroupMeta,
+  FieldMeta,
+} from '../../types'
+import { EmptyState } from '../components/EmptyState'
+import { resolveFieldMode, serializeItemForConditionalFilters, testFilter } from './filters'
+
+export function Fields({
+  view,
+  position,
+  fields,
+  groups = [],
+  forceValidation,
+  invalidFields,
+  onChange,
+  value: itemValue,
+  fieldModes = {},
+  fieldPositions = {},
+  isRequireds,
+}: {
+  view: 'createView' | 'itemView'
+  position: 'form' | 'sidebar'
+  fields: Record<string, FieldMeta>
+  forceValidation: boolean
+  groups?: FieldGroupMeta[]
+  invalidFields: ReadonlySet<string>
+  onChange(value: Record<string, unknown>): void
+  value: Record<string, unknown>
+  fieldModes?: Record<
+    string,
+    ConditionalFilter<'read' | 'edit' | 'hidden', 'read' | 'hidden', BaseListTypeInfo>
+  >
+  fieldPositions?: Record<string, 'form' | 'sidebar'>
+  isRequireds: Record<string, ConditionalFilterCase<BaseListTypeInfo>>
+}) {
+  const fieldDomByKey: Record<string, ReactNode> = {}
+  let focused = false
+
+  const serialized = serializeItemForConditionalFilters(fields, itemValue)
+  for (const fieldKey in fields) {
+    const field = fields[fieldKey]
+    const fieldPosition = fieldPositions[fieldKey] ?? field.itemView.fieldPosition
+    if (view === 'itemView' && fieldPosition !== position) continue
+
+    const fieldModeFilter = fieldModes[fieldKey] ?? field[view].fieldMode
+    const fieldMode = resolveFieldMode(fieldModeFilter, serialized, view)
+    if (fieldMode === 'hidden') continue
+
+    const fieldValue = itemValue[fieldKey]
+    const autoFocus = focused === false // not great, but focuses the first field
+    focused = true
+
+    fieldDomByKey[fieldKey] = (
+      <field.views.Field
+        key={fieldKey}
+        autoFocus={autoFocus}
+        forceValidation={forceValidation && invalidFields.has(fieldKey)}
+        field={field.controller}
+        isRequired={testFilter(isRequireds[fieldKey] ?? false, serialized)}
+        onChange={
+          fieldMode === 'read' || onChange === undefined
+            ? undefined
+            : newFieldValue => {
+                onChange({
+                  ...itemValue,
+                  [field.controller.fieldKey]: newFieldValue,
+                })
+              }
+        }
+        value={fieldValue}
+        itemValue={itemValue}
+      />
+    )
+  }
+
+  const groupByFieldKey: Record<string, FieldGroupMeta> = {}
+  for (const group of groups) {
+    for (const { key: fieldKey } of group.fields) {
+      groupByFieldKey[fieldKey] = group
+    }
+  }
+
+  // WARNING: for no fields and position: sidebar, we show an empty state, that is OK
+  if (Object.keys(fieldDomByKey).length === 0 && position === 'form') {
+    return (
+      <EmptyState
+        icon={textCursorInputIcon}
+        title="No fields"
+        message="There are no fields to be shown."
+      />
+    )
+  }
+
+  return (
+    // the "inline" container allows fields to react to the width of their column
+    <VStack gap="xlarge" UNSAFE_style={{ containerType: 'inline-size' }}>
+      {[
+        ...(function* () {
+          const rendered: Record<string, true> = {}
+          for (const fieldKey in fields) {
+            if (fieldKey in rendered) continue
+
+            const group = groupByFieldKey[fieldKey]
+            if (group) {
+              const fields = [
+                ...(function* () {
+                  for (const { key: fieldKey } of group.fields) {
+                    if (fieldKey in rendered) continue
+                    if (fieldDomByKey[fieldKey]) {
+                      yield fieldDomByKey[fieldKey]
+                    }
+                    rendered[fieldKey] = true
+                  }
+                })(),
+              ]
+              if (fields.length === 0) continue
+              yield (
+                <FieldGroup key={group.label} label={group.label} description={group.description}>
+                  {fields}
+                </FieldGroup>
+              )
+              continue
+            }
+
+            yield fieldDomByKey[fieldKey] ?? null
+            rendered[fieldKey] = true
+          }
+        })(),
+      ]}
+    </VStack>
+  )
+}
+
+function FieldGroup({
+  description,
+  label,
+  children,
+}: {
+  label: string
+  description: string | null
+  children: ReactNode
+}) {
+  const labelId = useId()
+  const descriptionId = useSlotId([Boolean(description)])
+
+  return (
+    <details aria-labelledby={labelId} aria-describedby={descriptionId} open>
+      <HStack
+        gap="medium"
+        alignItems="center"
+        elementType="summary"
+        UNSAFE_className={css({
+          listStyle: 'none',
+          outline: 0,
+          '::-webkit-details-marker': { display: 'none' },
+        })}
+      >
+        <FieldButton
+          // @ts-expect-error — this works, it's just not exposed in the public types
+          elementType="div"
+          // the <summary/> (above) is the focusable element
+          excludeFromTabOrder
+          prominence="low"
+          height="element.small"
+          width="element.small"
+          minWidth="auto"
+          UNSAFE_className={css({
+            'details[open] &': {
+              transform: 'rotate(90deg)',
+            },
+          })}
+        >
+          <Icon src={chevronRightIcon} size="medium" />
+        </FieldButton>
+        <VStack
+          gap="regular"
+          UNSAFE_className={css({
+            cursor: 'default',
+            userSelect: 'none',
+          })}
+        >
+          <Text
+            color="neutralEmphasis"
+            size="large"
+            weight="medium"
+            id={labelId}
+            position="relative"
+          >
+            {label}
+          </Text>
+          {!!description && (
+            <Text id={descriptionId} size="regular" color="neutralSecondary">
+              {description}
+            </Text>
+          )}
+        </VStack>
+      </HStack>
+
+      {/*
+        Padding is applied here because `<details>` doesn't accept flex/grid
+        layout, prefer "gap" in most cases.
+      */}
+      <HStack gap="medium" paddingTop="medium">
+        <GroupIndicatorLine />
+        <VStack gap="xlarge" flex>
+          {children}
+        </VStack>
+      </HStack>
+    </details>
+  )
+}
+
+export function GroupIndicatorLine() {
+  return (
+    <HStack justifyContent="center" width="element.small">
+      <div
+        className={css({
+          height: '100%',
+          width: tokenSchema.size.alias.focusRing,
+          borderRadius: tokenSchema.size.alias.focusRing,
+          backgroundColor: tokenSchema.color.border.neutral,
+          flexShrink: 0,
+        })}
+      />
+    </HStack>
+  )
+}

package/src/admin-ui/utils/actionData.ts

@@ -0,0 +1,36 @@
+import type { ActionMeta, ListMeta } from '../../types'
+import { serializeValueToOperationItem } from './utils'
+
+export function getActionArguments(
+  list: ListMeta,
+  action: ActionMeta,
+  value: Record<string, unknown>
+): Record<string, unknown> {
+  const args: Record<string, unknown> = {}
+  for (const arg of action.graphql.arguments) {
+    const { source } = arg
+    if (!source) continue
+
+    const field = list.fields[source.itemField]
+    if (!field) continue
+
+    const serialized = serializeValueToOperationItem(
+      'update',
+      { [source.itemField]: field },
+      value,
+      {}
+    )
+    if (Object.prototype.hasOwnProperty.call(serialized, source.itemField)) {
+      args[arg.name] = serialized[source.itemField]
+    }
+  }
+  return args
+}
+
+export function getActionGraphQLArgs(action: ActionMeta): string {
+  return action.graphql.arguments.map(arg => `${arg.name}: $${arg.name}`).join(', ')
+}
+
+export function getActionGraphQLVariables(action: ActionMeta): string {
+  return action.graphql.arguments.map(arg => `$${arg.name}: ${arg.type}`).join(', ')
+}

package/src/admin-ui/utils/filters.ts

@@ -0,0 +1,148 @@
+import type {
+  ActionMeta,
+  BaseListTypeInfo,
+  ConditionalFilter,
+  ConditionalFilterCase,
+  FieldMeta,
+} from '../../types'
+
+type SerializedItem = Record<string, unknown>
+type FieldFilter = {
+  equals?: unknown
+  in?: unknown[]
+  not?: {
+    equals?: unknown
+    in?: unknown[]
+  }
+}
+
+function isConditionalFilterOperator(key: string): key is 'AND' | 'OR' | 'NOT' {
+  return key === 'AND' || key === 'OR' || key === 'NOT'
+}
+
+function isFieldFilter(value: unknown): value is FieldFilter {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function applyFilter<T>(
+  filter: {
+    equals?: T
+    in?: T[]
+  },
+  value: T
+): boolean {
+  // WARNING: this is implicit AND
+  if (filter.equals !== undefined && value !== filter.equals) return false
+  if (filter.in !== undefined && !filter.in.includes(value)) return false
+  return true
+}
+
+export function testFilter(
+  filter: ConditionalFilterCase<BaseListTypeInfo> | undefined,
+  serialized: SerializedItem
+): boolean {
+  if (filter === undefined) return false
+  if (typeof filter === 'boolean') return filter
+
+  if (filter.AND !== undefined && !filter.AND.every(filter => testFilter(filter, serialized))) {
+    return false
+  }
+  if (filter.OR !== undefined && !filter.OR.some(filter => testFilter(filter, serialized))) {
+    return false
+  }
+  if (filter.NOT !== undefined && testFilter(filter.NOT, serialized)) {
+    return false
+  }
+
+  for (const [key, fieldFilter] of Object.entries(filter)) {
+    if (!isFieldFilter(fieldFilter)) continue
+    if (isConditionalFilterOperator(key)) continue
+
+    const serializedValue = serialized[key]
+    if (!applyFilter(fieldFilter, serializedValue)) return false
+    if (fieldFilter.not !== undefined && applyFilter(fieldFilter.not, serializedValue)) {
+      return false
+    }
+  }
+  return true
+}
+
+export function serializeItemForConditionalFilters(
+  fields: Record<string, FieldMeta>,
+  itemValue: Record<string, unknown>
+): SerializedItem {
+  const serialized: SerializedItem = {}
+  for (const [fieldKey, field] of Object.entries(fields)) {
+    Object.assign(serialized, field.controller.serialize(itemValue[fieldKey]))
+  }
+  return serialized
+}
+
+export function resolveActionMode(
+  actionMode: ConditionalFilter<
+    'enabled' | 'disabled' | 'hidden',
+    'disabled' | 'hidden',
+    BaseListTypeInfo
+  >,
+  serialized: SerializedItem
+): 'enabled' | 'disabled' | 'hidden' {
+  if (typeof actionMode === 'string') return actionMode
+  if (testFilter(actionMode.hidden, serialized)) return 'hidden'
+  if (testFilter(actionMode.disabled, serialized)) return 'disabled'
+  return 'enabled'
+}
+
+export function resolveFieldMode(
+  fieldMode: ConditionalFilter<'edit' | 'read' | 'hidden', 'read' | 'hidden', BaseListTypeInfo>,
+  serialized: SerializedItem,
+  view: 'createView' | 'itemView'
+) {
+  if (typeof fieldMode === 'string') return fieldMode
+  if (testFilter(fieldMode.hidden, serialized)) return 'hidden'
+  if (view === 'itemView' && testFilter(fieldMode.read, serialized)) return 'read'
+  return 'edit'
+}
+
+export function isActionAvailable(
+  action: ActionMeta,
+  { actionMode }: ActionMeta['listView'] | ActionMeta['itemView']
+): boolean {
+  if (action.graphql.arguments.some(a => !a.source)) return false
+
+  // conditional filters cannot be prefiltered ahead of time
+  if (typeof actionMode !== 'string') return true
+  return actionMode !== 'hidden'
+}
+
+export function getConditionalFilterFieldKeys(
+  actionMode: ConditionalFilter<string, string, BaseListTypeInfo>
+): string[] {
+  if (typeof actionMode === 'string') return []
+
+  const fieldKeys = new Set<string>()
+
+  function collectFieldKeys(filter: ConditionalFilterCase<BaseListTypeInfo> | undefined) {
+    if (!filter || typeof filter !== 'object') return
+
+    if (filter.AND !== undefined) {
+      filter.AND.forEach(collectFieldKeys)
+    }
+    if (filter.OR !== undefined) {
+      filter.OR.forEach(collectFieldKeys)
+    }
+    if (filter.NOT !== undefined) {
+      collectFieldKeys(filter.NOT)
+    }
+
+    for (const key of Object.keys(filter)) {
+      if (isConditionalFilterOperator(key)) continue
+      fieldKeys.add(key)
+    }
+  }
+
+  for (const conditionalFilter of Object.values(actionMode)) {
+    collectFieldKeys(conditionalFilter)
+  }
+
+  return [...fieldKeys]
+}

package/src/admin-ui/utils/index.ts

@@ -0,0 +1,10 @@
+export * from './Fields'
+export * from './filters'
+export * from './utils'
+export * from './useCreateItem'
+
+export type DeepNullable<T> =
+  | null
+  | (T extends Array<infer Item>
+      ? Array<DeepNullable<Item>>
+      : { [Key in keyof T]: DeepNullable<T[Key]> })

package/src/admin-ui/utils/pick.ts

@@ -0,0 +1,12 @@
+export function pick<T extends Record<string, unknown>, K extends keyof T>(
+  value: T,
+  keys: Iterable<K>
+): Pick<T, K> {
+  const result: Partial<Pick<T, K>> = {}
+  for (const key of keys) {
+    if (Object.prototype.hasOwnProperty.call(value, key)) {
+      result[key] = value[key]
+    }
+  }
+  return result as Pick<T, K>
+}

package/src/admin-ui/utils/useCreateItem.ts

@@ -0,0 +1,171 @@
+import { useRouter } from 'next/router'
+import { type ComponentProps, useEffect, useMemo, useRef, useState } from 'react'
+
+import { toastQueue } from '@keystar/ui/toast'
+
+import type { Fields } from '.'
+import {
+  makeDefaultValueState,
+  serializeValueToOperationItem,
+  useHasChanges,
+  useInvalidFields,
+} from '../../admin-ui/utils'
+import type { ListMeta } from '../../types'
+import { type ErrorLike, gql, type TypedDocumentNode, useMutation } from '../apollo'
+import { usePreventNavigation } from './usePreventNavigation'
+
+type CreateItemHookResult = {
+  state: 'editing' | 'loading' | 'created'
+  shouldPreventNavigation: boolean
+  error?: ErrorLike
+  props: ComponentProps<typeof Fields>
+  create: () => Promise<{ id: string; label: string | null } | undefined>
+}
+
+export function useCreateItem(list: ListMeta): CreateItemHookResult {
+  const router = useRouter()
+  const [tryCreateItem, { loading, error, data: returnedData }] = useMutation(
+    gql`mutation($data: ${list.graphql.names.createInputName}!) {
+      item: ${list.graphql.names.createMutationName}(data: $data) {
+        id
+        label: ${list.labelField}
+      }
+    }` as TypedDocumentNode<
+      { item: { id: string; label: string | null } },
+      { data: Record<string, unknown> }
+    >
+  )
+
+  const isRequireds = useMemo(
+    () =>
+      Object.fromEntries(
+        Object.entries(list.fields).map(([key, field]) => [key, field.createView.isRequired])
+      ),
+    [list.fields]
+  )
+
+  const [forceValidation, setForceValidation] = useState(false)
+  const [value, setValue] = useState(() => makeDefaultValueState(list.fields))
+  const invalidFields = useInvalidFields(list.fields, value, isRequireds)
+
+  const hasChangedFields = useHasChanges(
+    'create',
+    list.fields,
+    value,
+    makeDefaultValueState(list.fields)
+  )
+  const shouldPreventNavigation = !returnedData?.item && hasChangedFields
+  const shouldPreventNavigationRef = useRef(shouldPreventNavigation)
+
+  useEffect(() => {
+    shouldPreventNavigationRef.current = shouldPreventNavigation
+  }, [shouldPreventNavigation])
+  usePreventNavigation(shouldPreventNavigationRef)
+
+  return {
+    state: loading ? 'loading' : !returnedData?.item ? 'created' : 'editing',
+    shouldPreventNavigation,
+    error,
+    props: {
+      view: 'createView',
+      position: 'form',
+      fields: list.fields,
+      groups: list.groups,
+      forceValidation,
+      invalidFields,
+      value,
+      isRequireds,
+      onChange: newItemValue => setValue(newItemValue),
+    },
+    async create(): Promise<{ id: string; label: string | null } | undefined> {
+      const newForceValidation = invalidFields.size !== 0
+      setForceValidation(newForceValidation)
+
+      if (newForceValidation) return
+
+      let outputData: { item: { id: string; label: string | null } }
+      try {
+        outputData = await tryCreateItem({
+          variables: {
+            data: serializeValueToOperationItem('create', list.fields, value),
+          },
+          update(cache, { data }) {
+            if (typeof data?.item?.id === 'string') {
+              cache.evict({
+                id: 'ROOT_QUERY',
+                fieldName: `${list.graphql.names.itemQueryName}(${JSON.stringify({
+                  where: { id: data.item.id },
+                })})`,
+              })
+            }
+          },
+        }).then(x => {
+          if (x.data) return x.data
+          if (x.error) throw x.error
+          throw new Error('Something went wrong during item creation.')
+        })
+      } catch {
+        toastQueue.critical(`Unable to create ${list.singular.toLocaleLowerCase()}`)
+        return
+      }
+
+      shouldPreventNavigationRef.current = false
+      toastQueue.positive(`${list.singular} created`, {
+        timeout: 5000,
+        actionLabel: 'Create another',
+        onAction: () => {
+          router.push(`/${list.path}/create`)
+        },
+        shouldCloseOnAction: true,
+      })
+
+      return outputData.item
+    },
+  }
+}
+
+type BuildItemHookResult = {
+  state: 'editing'
+  error?: ErrorLike
+  props: ComponentProps<typeof Fields>
+  build: () => Promise<Record<string, unknown> | undefined>
+}
+
+export function useBuildItem(list: ListMeta, fieldKeys: string[] = []): BuildItemHookResult {
+  const [forceValidation, setForceValidation] = useState(false)
+  const [value, setValue] = useState(() => makeDefaultValueState(list.fields))
+  const fields = fieldKeys.length
+    ? Object.fromEntries(Object.entries(list.fields).filter(([key]) => fieldKeys.includes(key)))
+    : list.fields
+
+  const isRequireds = useMemo(
+    () =>
+      Object.fromEntries(
+        Object.entries(list.fields).map(([key, field]) => [key, field.createView.isRequired])
+      ),
+    [list.fields]
+  )
+
+  const invalidFields = useInvalidFields(list.fields, value, isRequireds)
+
+  return {
+    state: 'editing',
+    props: {
+      view: 'createView',
+      position: 'form',
+      fields,
+      groups: list.groups,
+      forceValidation,
+      invalidFields,
+      value,
+      isRequireds,
+      onChange: newItemValue => setValue(newItemValue),
+    },
+    async build() {
+      const newForceValidation = invalidFields.size !== 0
+      setForceValidation(newForceValidation)
+      if (newForceValidation) return
+      return serializeValueToOperationItem('create', list.fields, value)
+    },
+  }
+}

package/src/admin-ui/utils/usePreventNavigation.tsx

@@ -0,0 +1,31 @@
+import { useRouter } from 'next/router'
+import { useEffect } from 'react'
+
+export function usePreventNavigation(shouldPreventNavigationRef: { current: boolean }) {
+  const router = useRouter()
+
+  useEffect(() => {
+    const clientSideRouteChangeHandler = () => {
+      if (
+        shouldPreventNavigationRef.current &&
+        !window.confirm('There are unsaved changes, are you sure you want to exit?')
+      ) {
+        // throwing from here seems to be the only way to prevent the navigation
+        // we're throwing just a string here rather than an error because throwing an error
+        // causes Next to show an error overlay in dev but it doesn't show the overlay when we throw a string
+        throw 'Navigation cancelled by user'
+      }
+    }
+    router.events.on('routeChangeStart', clientSideRouteChangeHandler)
+    const beforeUnloadHandler = (event: BeforeUnloadEvent) => {
+      if (shouldPreventNavigationRef.current) {
+        event.preventDefault()
+      }
+    }
+    window.addEventListener('beforeunload', beforeUnloadHandler)
+    return () => {
+      router.events.off('routeChangeStart', clientSideRouteChangeHandler)
+      window.removeEventListener('beforeunload', beforeUnloadHandler)
+    }
+  }, [shouldPreventNavigationRef, router.events])
+}