@nixxie-cms/core 1.0.0

package/src/admin-ui/context.tsx

@@ -0,0 +1,338 @@
+import UploadLink from 'apollo-upload-client/UploadHttpLink.mjs'
+import NextHead from 'next/head'
+import { type ReactNode, createContext, useContext, useEffect, useMemo } from 'react'
+
+import { ClientSideOnlyDocumentElement, KeystarProvider } from '@keystar/ui/core'
+import { injectGlobal, tokenSchema } from '@keystar/ui/style'
+import { Toaster } from '@keystar/ui/toast'
+import { useRouter } from '@nixxie-cms/core/admin-ui/router'
+
+import { snapValueToClosest } from '../___internal-do-not-use-will-break-in-patch/admin-ui/pages/ListPage/PaginationControls'
+import type {
+  AdminConfig,
+  BaseListTypeInfo,
+  ConditionalFilter,
+  ConditionalFilterCase,
+  FieldViews,
+  ListMeta,
+} from '../types'
+import { type AdminMetaQuery, adminMetaQuery } from './admin-meta-graphql'
+import {
+  ApolloClient,
+  ApolloProvider,
+  type ErrorLike,
+  InMemoryCache,
+  gql,
+  useQuery,
+} from './apollo'
+import { getConditionalFilterFieldKeys, isActionAvailable } from './utils/filters'
+
+type NixxieContextType = {
+  adminConfig: AdminConfig | null
+  apiPath: string | null
+  error?: ErrorLike | null
+  fieldViews: FieldViews
+  lists: { [list: string]: ListMeta }
+}
+
+const NixxieContext = createContext<NixxieContextType>({
+  adminConfig: null,
+  apiPath: null,
+  lists: {},
+  fieldViews: {},
+})
+
+type NixxieProviderProps = {
+  adminConfig: AdminConfig
+  apiPath: string
+  fieldViews: FieldViews
+  children: ReactNode
+}
+
+const expectedExports = new Set(['Field', 'controller'])
+
+function InternalNixxieProvider({
+  adminConfig,
+  apiPath,
+  fieldViews,
+  children,
+}: NixxieProviderProps) {
+  const { push: navigate } = useRouter()
+  const keystarRouter = useMemo(() => ({ navigate }), [navigate])
+  const { data, loading, error } = useQuery<AdminMetaQuery>(adminMetaQuery, {
+    errorPolicy: 'all',
+  })
+  const listsData = data?.nixxie?.adminMeta?.lists
+  const lists = useMemo(() => {
+    if (!listsData) return
+    if (error) return
+
+    const lists: NixxieContextType['lists'] = {}
+
+    for (const listData of listsData) {
+      lists[listData.key] = {
+        ...listData,
+        pageSize: snapValueToClosest(listData.pageSize ?? 50),
+        fields: {},
+        groups: [],
+      }
+
+      for (const field of listData.fields) {
+        for (const exportName of expectedExports) {
+          if ((fieldViews[field.viewsIndex] as any)[exportName] === undefined) {
+            throw new Error(
+              `The view for the field at ${listData.key}.${field.key} is missing the ${exportName} export`
+            )
+          }
+        }
+
+        const views = { ...fieldViews[field.viewsIndex] }
+        const customViews: Record<string, any> = {}
+        if (field.customViewsIndex !== null) {
+          const customViewsSource: FieldViews[number] & Record<string, any> =
+            fieldViews[field.customViewsIndex]
+          const allowedExportsOnCustomViews = new Set(views.allowedExportsOnCustomViews)
+          for (const exportName in customViewsSource) {
+            if (allowedExportsOnCustomViews.has(exportName)) {
+              customViews[exportName] = customViewsSource[exportName]
+            } else if (expectedExports.has(exportName)) {
+              ;(views as any)[exportName] = customViewsSource[exportName]
+            }
+          }
+        }
+
+        lists[listData.key].fields[field.key] = {
+          ...field,
+          createView: {
+            fieldMode: field.createView?.fieldMode ?? null,
+            isRequired: field.createView?.isRequired ?? false,
+          },
+          itemView: {
+            fieldMode: field.itemView?.fieldMode ?? null,
+            fieldPosition: field.itemView?.fieldPosition ?? null,
+            isRequired: field.itemView?.isRequired ?? false,
+          },
+          listView: {
+            fieldMode: field.listView?.fieldMode ?? null,
+          },
+          views,
+          controller: views.controller({
+            listKey: listData.key,
+            fieldKey: field.key,
+            label: field.label,
+            description: field.description,
+            fieldMeta: field.fieldMeta,
+            customViews,
+          }),
+        }
+      }
+
+      for (const group of listData.groups) {
+        lists[listData.key].groups.push({
+          label: group.label,
+          description: group.description,
+          fields: group.fields.map(field => lists[listData.key].fields[field.key]),
+        })
+      }
+    }
+
+    return lists
+  }, [listsData, error, fieldViews])
+
+  useEffect(() => {
+    injectGlobal({
+      body: {
+        fontFamily:
+          "'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
+        WebkitFontSmoothing: 'antialiased',
+        MozOsxFontSmoothing: 'grayscale',
+      },
+      '*, ::before, ::after': {
+        borderWidth: 0,
+        borderStyle: 'solid',
+        borderColor: tokenSchema.color.border.neutral,
+        boxSizing: 'border-box',
+      },
+      // Force light background on all Keystar surface/canvas elements
+      // when they appear inside the main content (not inside our dark sidebar)
+      '[data-nixxie-content]': {
+        colorScheme: 'light',
+      },
+    })
+  }, [])
+
+  // TODO
+  if (loading) return null
+  //   if (!meta) return null
+  return (
+    <KeystarProvider router={keystarRouter} colorScheme="light">
+      <ClientSideOnlyDocumentElement bodyBackground="canvas" />
+      <NextHead>
+        <meta key="viewport" name="viewport" content="width=device-width, initial-scale=1.0" />
+        <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+        <link
+          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+          rel="stylesheet"
+        />
+      </NextHead>
+
+      <NixxieContext.Provider
+        value={{
+          adminConfig,
+          apiPath,
+          fieldViews,
+          lists: lists ?? {},
+          error: error ?? null,
+        }}
+      >
+        {children}
+      </NixxieContext.Provider>
+      <Toaster />
+    </KeystarProvider>
+  )
+}
+
+export function NixxieProvider(props: NixxieProviderProps) {
+  const apolloClient = useMemo(
+    () =>
+      new ApolloClient({
+        cache: new InMemoryCache(),
+        link: new UploadLink({
+          uri: props.apiPath,
+          headers: { 'Apollo-Require-Preflight': 'true' },
+        }),
+      }),
+    [props.apiPath]
+  )
+
+  return (
+    <ApolloProvider client={apolloClient}>
+      <InternalNixxieProvider {...props} />
+    </ApolloProvider>
+  )
+}
+
+export function useNixxie() {
+  return useContext(NixxieContext)
+}
+
+export function useList(listKey: string) {
+  const { lists } = useNixxie()
+  const list = lists?.[listKey]
+  if (!list) throw new Error(`Unknown list ${listKey}`)
+  return list
+}
+
+export function useField(listKey: string, fieldKey: string) {
+  const list = useList(listKey)
+  const field = list.fields[fieldKey]
+  if (!field) throw new Error(`Unknown field ${listKey}.${fieldKey}`)
+  return field
+}
+
+// TODO useContext?
+export function useListItem(
+  listKey: string,
+  itemId: string | null
+): useQuery.Result<
+  {
+    item: Record<string, unknown> | null
+    nixxie: {
+      adminMeta: {
+        list: {
+          fields: {
+            key: string
+            itemView: {
+              fieldMode: ConditionalFilter<
+                'edit' | 'read' | 'hidden',
+                'read' | 'hidden',
+                BaseListTypeInfo
+              >
+              fieldPosition: 'form' | 'sidebar'
+              isRequired: ConditionalFilterCase<BaseListTypeInfo>
+            } | null
+          }[]
+          actions: {
+            key: string
+            itemView: {
+              actionMode: ConditionalFilter<
+                'enabled' | 'disabled' | 'hidden',
+                'disabled' | 'hidden',
+                BaseListTypeInfo
+              >
+            } | null
+          }[]
+        } | null
+      }
+    }
+  },
+  { id: string | null; listKey: string }
+> {
+  const list = useList(listKey)
+  const query = useMemo(() => {
+    const selectedFieldKeys = new Set<string>()
+
+    for (const field of Object.values(list.fields)) {
+      if (field.key === 'id') continue // always in the query
+      if (field.itemView.fieldMode === 'hidden') continue
+      selectedFieldKeys.add(field.key)
+    }
+
+    for (const action of list.actions) {
+      if (!isActionAvailable(action, action.itemView)) continue
+
+      for (const fieldKey of getConditionalFilterFieldKeys(action.itemView.actionMode)) {
+        selectedFieldKeys.add(fieldKey)
+      }
+
+      for (const arg of action.graphql.arguments) {
+        if (!arg.source) continue
+        selectedFieldKeys.add(arg.source.itemField)
+      }
+    }
+
+    const selectedFields = [...selectedFieldKeys]
+      .map(fieldKey => list.fields[fieldKey])
+      .filter(Boolean)
+      .map(field => field.controller.graphqlSelection)
+      .join('\n')
+
+    return gql`
+      query KsFetchItem ($listKey: String!, $id: ID!) {
+        nixxie {
+          adminMeta {
+            list(key: $listKey, itemId: $id) {
+              fields {
+                key
+                itemView {
+                  fieldMode
+                  fieldPosition
+                  isRequired
+                }
+              }
+              actions {
+                key
+                itemView {
+                  actionMode
+                }
+              }
+            }
+          }
+        }
+        item: ${list.graphql.names.itemQueryName}(where: { id: $id }) {
+          id
+          ${selectedFields}
+        }
+      }
+    `
+  }, [list])
+
+  return useQuery(query, {
+    errorPolicy: 'all',
+    skip: itemId === null,
+    variables: {
+      listKey,
+      id: itemId,
+    },
+  })
+}

package/src/admin-ui/image.tsx

@@ -0,0 +1,2 @@
+export * from 'next/image'
+export { default } from 'next/image'

package/src/admin-ui/index.tsx

@@ -0,0 +1 @@
+export { NixxieProvider, useNixxie, useList } from './context'

package/src/admin-ui/router.tsx

@@ -0,0 +1,24 @@
+/**
+ * This file is exposed by the /router entrypoint, and helps ensure that other
+ * packages import the same instance of next's router.
+ */
+
+// not using export * because Rollup's CJS re-export code doesn't ignore __esModule on the exports object so it will re-define it if it exists
+// and since __esModule isn't configurable(at least with the code that's _generally_ emitted by Rollup, Babel, tsc and etc.)
+// an error will be thrown
+// that's normally not a problem because modules generally use Object.defineProperty(exports, '__esModule', { value: true })
+// which means that the property isn't enumerable but Next uses Babel's loose mode and Babel's loose mode for the CJS transform
+// uses exports.__esModule = true instead of defineProperty so the property is enumerable
+export { Router, useRouter, withRouter } from 'next/router'
+export type { NextRouter } from 'next/router'
+
+import NextLink, { type LinkProps as NextLinkProps } from 'next/link'
+import type { AnchorHTMLAttributes } from 'react'
+
+export type LinkProps = NextLinkProps & AnchorHTMLAttributes<HTMLAnchorElement>
+
+export const Link = NextLink
+
+import NextHead from 'next/head'
+
+export const Head = NextHead

package/src/admin-ui/system/generateAdminUI.ts

@@ -0,0 +1,155 @@
+import { type Entry, walk as _walk } from '@nodelib/fs.walk'
+import fse from 'fs-extra'
+import fs from 'node:fs/promises'
+import Path from 'node:path'
+import { promisify } from 'node:util'
+
+import type { AdminMetaSource } from '../../lib/admin-meta'
+import type { AdminFileToWrite, NixxieConfig } from '../../types'
+import { writeAdminFiles } from '../templates'
+import { withSpan } from '../../lib/otel'
+
+const walk = promisify(_walk)
+
+function toPosixPath(p: string) {
+  return p.split(Path.sep).join('/')
+}
+
+function serializePathForImport(path: string) {
+  // JSON.stringify is important here because it will escape windows style paths(and any thing else that might potentially be in there)
+  return JSON.stringify(
+    toPosixPath(
+      path
+        // Next is unhappy about imports that include .ts/tsx in them because TypeScript is unhappy with them because when doing a TypeScript compilation with tsc, the imports won't be written so they would be wrong there
+        .replace(/\.tsx?$/, '')
+    )
+  )
+}
+
+export async function writeAdminFile(file: AdminFileToWrite, projectAdminPath: string) {
+  const outputFilename = Path.join(projectAdminPath, file.outputPath)
+  if (file.mode === 'copy') {
+    if (!Path.isAbsolute(file.inputPath)) {
+      throw new Error(
+        `An inputPath of "${file.inputPath}" was provided to copy but inputPaths must be absolute`
+      )
+    }
+    await fse.ensureDir(Path.dirname(outputFilename))
+    // TODO: should we use copyFile or copy?
+    await fs.copyFile(file.inputPath, outputFilename)
+  }
+  let content: undefined | string
+  try {
+    content = await fs.readFile(outputFilename, 'utf8')
+  } catch (err: any) {
+    if (err.code !== 'ENOENT') throw err
+  }
+  if (file.mode === 'write' && content !== file.src) {
+    await fse.outputFile(outputFilename, file.src)
+  }
+  return Path.normalize(outputFilename)
+}
+
+const pageExtensions = new Set(['.js', '.jsx', '.ts', '.tsx'])
+
+export async function generateAdminUI(
+  config: NixxieConfig,
+  adminMeta: AdminMetaSource,
+  projectAdminPath: string,
+  isLiveReload: boolean
+) {
+  await withSpan('generating admin next application', async () => {
+    // when we're not doing a live reload, we want to clear everything out except the .next directory (not the .next directory because it has caches)
+    // so that at least every so often, we'll clear out anything that the deleting we do during live reloads doesn't (should just be directories)
+    if (!isLiveReload) {
+      const dir = await fs.readdir(projectAdminPath).catch(err => {
+        if (err.code === 'ENOENT') return []
+        throw err
+      })
+
+      await Promise.all(
+        dir.map(x => {
+          if (x === '.next') return
+          return fs.rm(Path.join(projectAdminPath, x), { recursive: true })
+        })
+      )
+    }
+
+    // Write out the files configured by the user
+    const userFilesToWrite = await config.ui.getAdditionalFiles()
+    const savedFiles = await Promise.all(
+      userFilesToWrite.map(file => writeAdminFile(file, projectAdminPath))
+    )
+    const uniqueFiles = new Set(savedFiles)
+
+    // Add files to pages/ which point to any files which exist in admin/pages
+    const adminConfigDir = Path.join(process.cwd(), 'admin')
+    const userPagesDir = Path.join(adminConfigDir, 'pages')
+
+    let userPagesEntries: Entry[] = []
+    try {
+      userPagesEntries = await walk(userPagesDir, {
+        entryFilter: entry => entry.dirent.isFile() && pageExtensions.has(Path.extname(entry.name)),
+      })
+    } catch (err: any) {
+      if (err.code !== 'ENOENT') throw err
+    }
+
+    // Collect files into a map keyed by outputPath to handle duplicates
+    // User-provided files take precedence over internal files
+    const adminFilesMap = new Map<string, AdminFileToWrite>()
+
+    // Add internal files first
+    for (const file of writeAdminFiles(config, adminMeta)) {
+      adminFilesMap.set(file.outputPath, file)
+    }
+
+    // Add user page files (these override internal files)
+    for (const { path } of userPagesEntries) {
+      const outputFilename = toPosixPath(Path.relative(adminConfigDir, path))
+      const importPath = Path.relative(
+        Path.dirname(Path.join(projectAdminPath, outputFilename)),
+        path
+      )
+      const serializedImportPath = serializePathForImport(importPath)
+      adminFilesMap.set(outputFilename, {
+        mode: 'write',
+        outputPath: outputFilename,
+        src: `export { default } from ${serializedImportPath}`,
+      })
+    }
+
+    // Filter out files already written by getAdditionalFiles() and convert to array
+    const adminFiles = Array.from(adminFilesMap.values()).filter(
+      x => !uniqueFiles.has(Path.normalize(Path.join(projectAdminPath, x.outputPath)))
+    )
+
+    // Write distinct output paths in parallel after deterministic de-duplication
+    await Promise.all(adminFiles.map(file => writeAdminFile(file, projectAdminPath)))
+
+    // Because Next will re-compile things (or at least check things and log a bunch of stuff)
+    // if we delete pages and then re-create them, we want to avoid that when live reloading
+    // so we only delete things that shouldn't exist anymore
+    // this won't clear out empty directories, this is fine since:
+    // - they won't create pages in Admin UI which is really what this deleting is about avoiding
+    // - we'll remove them when the user restarts the process
+    if (isLiveReload) {
+      const ignoredDir = Path.resolve(projectAdminPath, '.next')
+      const ignoredFiles = new Set(
+        [
+          ...adminFiles.map(x => x.outputPath),
+          ...uniqueFiles,
+          'next-env.d.ts',
+          'pages/api/__nixxie_api_build.js',
+        ].map(x => Path.resolve(projectAdminPath, x))
+      )
+
+      const entries = await walk(projectAdminPath, {
+        deepFilter: entry => entry.path !== ignoredDir,
+        entryFilter: entry => entry.dirent.isFile() && !ignoredFiles.has(entry.path),
+      })
+
+      await Promise.all(entries.map(entry => fs.rm(entry.path, { recursive: true })))
+    }
+  })
+}

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

@@ -0,0 +1 @@
+export { generateAdminUI } from './generateAdminUI'

package/src/admin-ui/templates/app.ts

@@ -0,0 +1,60 @@
+import Path from 'node:path'
+import resolve from 'resolve'
+
+import type { AdminMetaSource } from '../../lib/admin-meta'
+import type { NixxieConfig } from '../../types'
+
+function doesConfigExist(path: string[]) {
+  try {
+    const configPath = Path.join(process.cwd(), ...path)
+    resolve.sync(configPath, {
+      extensions: ['.ts', '.tsx', '.js'],
+      preserveSymlinks: false,
+    })
+    return true
+  } catch (err: any) {
+    if (err.code === 'MODULE_NOT_FOUND') return false
+    throw err
+  }
+}
+
+export function appTemplate(config: NixxieConfig, adminMeta: AdminMetaSource) {
+  const allViews = adminMeta.views.map(viewRelativeToProject => {
+    const isRelativeToFile =
+      viewRelativeToProject.startsWith('./') || viewRelativeToProject.startsWith('../')
+    const viewRelativeToAppFile = isRelativeToFile
+      ? '../../../' + viewRelativeToProject
+      : viewRelativeToProject
+
+    // we're not using serializePathForImport here because we want the thing you write for a view
+    // to be exactly what you would put in an import in the project directory.
+    // we're still using JSON.stringify to escape anything that might need to be though
+    return JSON.stringify(viewRelativeToAppFile)
+  })
+  // -- TEMPLATE START
+  return `import { getApp } from '@nixxie-cms/core/___internal-do-not-use-will-break-in-patch/admin-ui/pages/App'
+
+${allViews.map((views, i) => `import * as view${i} from ${views}`).join('\n')}
+
+${
+  doesConfigExist(['.nixxie', 'admin', 'config'])
+    ? `import * as packageAdminConfig from "../../../.nixxie/admin/config"`
+    : 'let packageAdminConfig = {}'
+}
+
+${
+  doesConfigExist(['admin', 'config'])
+    ? `import * as userAdminConfig from "../../../admin/config"`
+    : 'let userAdminConfig = {}'
+}
+
+export default getApp({
+  adminConfig: {
+    ...packageAdminConfig,
+    ...userAdminConfig
+  },
+  apiPath: "${config.graphql.path}",
+  fieldViews: [${allViews.map((_, i) => `view${i}`)}],
+})
+`
+}

package/src/admin-ui/templates/create-item.ts

@@ -0,0 +1,5 @@
+export const createItemTemplate = (listKey: string) =>
+  `import { getCreateItemPage } from '@nixxie-cms/core/___internal-do-not-use-will-break-in-patch/admin-ui/pages/CreateItemPage';
+
+export default getCreateItemPage(${JSON.stringify({ listKey })})
+`

package/src/admin-ui/templates/home.ts

@@ -0,0 +1,2 @@
+export const homeTemplate = `export { HomePage as default } from '@nixxie-cms/core/___internal-do-not-use-will-break-in-patch/admin-ui/pages/HomePage';
+`

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

@@ -0,0 +1,53 @@
+import path from 'node:path'
+
+import type { AdminMetaSource } from '../../lib/admin-meta'
+import type { NixxieConfig } from '../../types'
+import { appTemplate } from './app'
+import { createItemTemplate } from './create-item'
+import { homeTemplate } from './home'
+import { itemTemplate } from './item'
+import { listTemplate } from './list'
+import { nextConfigTemplate } from './next-config'
+import { noAccessTemplate } from './no-access'
+
+const pkgDir = path.dirname(require.resolve('@nixxie-cms/core/package.json'))
+
+export function writeAdminFiles(config: NixxieConfig, adminMeta: AdminMetaSource) {
+  return [
+    {
+      mode: 'write' as const,
+      src: nextConfigTemplate(config.ui?.basePath),
+      outputPath: 'next.config.js',
+    },
+    {
+      mode: 'copy' as const,
+      inputPath: path.join(pkgDir, 'static', 'favicon.ico'),
+      outputPath: 'public/favicon.ico',
+    },
+    {
+      mode: 'copy' as const,
+      inputPath: path.join(pkgDir, 'static', 'favicon.svg'),
+      outputPath: 'public/favicon.svg',
+    },
+    {
+      mode: 'write' as const,
+      src: noAccessTemplate(config.session),
+      outputPath: 'pages/no-access.js',
+    },
+    {
+      mode: 'write' as const,
+      src: appTemplate(config, adminMeta),
+      outputPath: 'pages/_app.js',
+    },
+    { mode: 'write' as const, src: homeTemplate, outputPath: 'pages/index.js' },
+    ...adminMeta.lists.flatMap(({ path, key }) => [
+      { mode: 'write' as const, src: listTemplate(key), outputPath: `pages/${path}/index.js` },
+      { mode: 'write' as const, src: itemTemplate(key), outputPath: `pages/${path}/[id].js` },
+      {
+        mode: 'write' as const,
+        src: createItemTemplate(key),
+        outputPath: `pages/${path}/create.js`,
+      },
+    ]),
+  ]
+}

package/src/admin-ui/templates/item.tsx

@@ -0,0 +1,5 @@
+export const itemTemplate = (listKey: string) =>
+  `import { getItemPage } from '@nixxie-cms/core/___internal-do-not-use-will-break-in-patch/admin-ui/pages/ItemPage';
+
+export default getItemPage(${JSON.stringify({ listKey })})
+`

package/src/admin-ui/templates/list.tsx

@@ -0,0 +1,5 @@
+export const listTemplate = (listKey: string) =>
+  `import { getListPage } from '@nixxie-cms/core/___internal-do-not-use-will-break-in-patch/admin-ui/pages/ListPage';
+
+export default getListPage(${JSON.stringify({ listKey })});
+`

package/src/admin-ui/templates/next-config.ts

@@ -0,0 +1,16 @@
+export const nextConfigTemplate = (basePath?: string) =>
+  `const nextConfig = {
+    bundlePagesRouterDependencies: true,
+    typescript: {
+      ignoreBuildErrors: true,
+    },
+    eslint: {
+      ignoreDuringBuilds: true,
+    },
+    // We use transpilePackages for the custom admin-ui pages in the ./admin folder
+    // as they import ts files into nextjs
+    transpilePackages: ['../../admin'],
+    ${basePath ? `basePath: '${basePath}',` : ''}
+  }
+
+  module.exports = nextConfig`

package/src/admin-ui/templates/no-access.ts

@@ -0,0 +1,7 @@
+import type { NixxieConfig } from '../../types'
+
+export const noAccessTemplate = (session: NixxieConfig['session']) =>
+  `import { getNoAccessPage } from '@nixxie-cms/core/___internal-do-not-use-will-break-in-patch/admin-ui/pages/NoAccessPage';
+
+export default getNoAccessPage(${JSON.stringify({ sessionsEnabled: !!session })})
+`