@opensaas/stack-ui 0.22.0 → 0.24.0

package/src/index.ts

@@ -7,6 +7,7 @@ export { ListView } from './components/ListView.js'
 export { ListViewClient } from './components/ListViewClient.js'
 export { ItemForm } from './components/ItemForm.js'
 export { ItemFormClient } from './components/ItemFormClient.js'
+export { SingletonView } from './components/SingletonView.js'
 export { ConfirmDialog } from './components/ConfirmDialog.js'
 export { LoadingSpinner } from './components/LoadingSpinner.js'
 export { SkeletonLoader, TableSkeleton, FormSkeleton } from './components/SkeletonLoader.js'
@@ -35,6 +36,7 @@ export type { ListViewProps } from './components/ListView.js'
 export type { ListViewClientProps } from './components/ListViewClient.js'
 export type { ItemFormProps } from './components/ItemForm.js'
 export type { ItemFormClientProps } from './components/ItemFormClient.js'
+export type { SingletonViewProps } from './components/SingletonView.js'
 export type { ConfirmDialogProps } from './components/ConfirmDialog.js'
 export type { LoadingSpinnerProps } from './components/LoadingSpinner.js'
 export type { SkeletonLoaderProps } from './components/SkeletonLoader.js'

package/src/lib/operationAccess.ts

@@ -0,0 +1,53 @@
+import type { AccessContext, OperationAccess, Session } from '@opensaas/stack-core'
+
+/**
+ * The names of the operation-level access checks we evaluate in the UI.
+ */
+export type OperationAccessName = 'query' | 'create' | 'update' | 'delete'
+
+/**
+ * Evaluate a list's operation-level access control for the current session,
+ * coercing the result to a single "is this operation potentially permitted?"
+ * boolean.
+ *
+ * This mirrors how the core access engine treats a result:
+ * - `false`            → denied
+ * - `true`             → permitted
+ * - a filter object    → permitted, but scoped to matching rows
+ *
+ * Because the UI cannot know whether a returned filter would match the
+ * (possibly not-yet-created) singleton row, a filter is treated as "potentially
+ * permitted" — the actual operation still runs through the access engine, which
+ * re-applies the filter. This helper only decides which affordance to render.
+ *
+ * Access functions are user-defined and may throw (e.g. they assume a session
+ * shape that anonymous requests don't have). A throw is treated as **denied** —
+ * the safest outcome, so a misbehaving access function never exposes an
+ * editable/create form to a session that might not be allowed.
+ *
+ * No access function configured for the operation is also treated as denied,
+ * matching the core engine's deny-by-default (`checkAccess` returns `false`
+ * when `accessControl` is undefined).
+ */
+export async function isOperationPotentiallyAllowed(
+  access: OperationAccess | undefined,
+  operation: OperationAccessName,
+  args: { session: Session | null; context: AccessContext<unknown> },
+): Promise<boolean> {
+  const accessControl = access?.[operation]
+  // Deny by default — no rule means no access (matches the core engine).
+  if (!accessControl) return false
+
+  try {
+    const result = await accessControl({
+      session: args.session,
+      // The access engine passes the same context through to the function.
+      context: args.context,
+    })
+    // `false` denies; `true` or a filter object both mean "potentially allowed".
+    return result !== false
+  } catch {
+    // A throwing access function is treated as denied — never widen access on error.
+    return false
+  }
+}

package/src/lib/prepareItemForm.ts

@@ -0,0 +1,121 @@
+import { type AccessContext, getDbKey, OpenSaasConfig } from '@opensaas/stack-core'
+import type { ListConfig } from '@opensaas/stack-core'
+import { serializeFieldConfigs, type SerializableFieldConfig } from './serializeFieldConfig.js'
+
+/**
+ * Data prepared on the server for the client item form.
+ *
+ * Everything here is JSON-serializable and contains only what `ItemFormClient`
+ * needs to render — see the repo rule on minimal, serializable client props.
+ */
+export interface PreparedItemForm {
+  /** Field configs stripped of functions/non-serializable props. */
+  serializableFields: Record<string, SerializableFieldConfig>
+  /** Initial form values (relationships reduced to ids, client transforms applied). */
+  initialData: Record<string, unknown>
+  /** Relationship options keyed by field name. */
+  relationshipData: Record<string, Array<{ id: string; label: string }>>
+}
+
+/**
+ * Build the `include` object needed to hydrate relationship fields when
+ * fetching an item for editing.
+ */
+export function buildRelationshipInclude(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig is generic over TypeInfo
+  listConfig: ListConfig<any>,
+): Record<string, boolean> {
+  const includeRelationships: Record<string, boolean> = {}
+  for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+    if ((fieldConfig as { type: string }).type === 'relationship') {
+      includeRelationships[fieldName] = true
+    }
+  }
+  return includeRelationships
+}
+
+/**
+ * Prepare the serializable props for `ItemFormClient` from an already-fetched
+ * record (or an empty object for create).
+ *
+ * This is shared by `ItemForm` (which fetches via `findUnique`) and
+ * `SingletonView` (which resolves via the singleton `get()`), so the
+ * relationship/serialization logic lives in exactly one place.
+ */
+export async function prepareItemForm(
+  context: AccessContext<unknown>,
+  config: OpenSaasConfig,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig is generic over TypeInfo
+  listConfig: ListConfig<any>,
+  itemData: Record<string, unknown>,
+): Promise<PreparedItemForm> {
+  // Fetch relationship options for all relationship fields
+  const relationshipData: Record<string, Array<{ id: string; label: string }>> = {}
+  for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+    const fieldConfigAny = fieldConfig as { type: string; ref?: string }
+    if (fieldConfigAny.type === 'relationship') {
+      const ref = fieldConfigAny.ref
+      if (ref) {
+        // Parse ref format: "ListName.fieldName"
+        const relatedListName = ref.split('.')[0]
+        const relatedListConfig = config.lists[relatedListName]
+
+        if (relatedListConfig) {
+          try {
+            const delegate = context.db[getDbKey(relatedListName)]
+            const relatedItems = delegate?.findMany ? await delegate.findMany({}) : []
+
+            // Use 'name' field as label if it exists, otherwise use 'id'
+            relationshipData[fieldName] = relatedItems.map((item: Record<string, unknown>) => ({
+              id: item.id as string,
+              label: ((item.name || item.title || item.id) as string) || '',
+            }))
+          } catch (error) {
+            console.error(`Failed to fetch relationship items for ${fieldName}:`, error)
+            relationshipData[fieldName] = []
+          }
+        }
+      }
+    }
+  }
+
+  // Serialize field configs to remove non-serializable properties
+  const serializableFields = serializeFieldConfigs(listConfig.fields)
+
+  // Transform relationship data in itemData from objects to IDs for form
+  // Also apply valueForClientSerialization transformation
+  const formData = { ...itemData }
+  for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+    const fieldConfigAny = fieldConfig as {
+      type: string
+      many?: boolean
+      ui?: Record<string, unknown>
+    }
+    if (fieldConfigAny.type === 'relationship' && formData[fieldName]) {
+      const value = formData[fieldName]
+      if (fieldConfigAny.many && Array.isArray(value)) {
+        // Many relationship: extract IDs from array of objects
+        formData[fieldName] = value.map((item: Record<string, unknown>) => item.id as string)
+      } else if (value && typeof value === 'object' && 'id' in value) {
+        // Single relationship: extract ID from object
+        formData[fieldName] = (value as Record<string, unknown>).id as string
+      }
+    }
+
+    // Apply valueForClientSerialization if defined
+    if (
+      fieldConfigAny.ui?.valueForClientSerialization &&
+      typeof fieldConfigAny.ui.valueForClientSerialization === 'function'
+    ) {
+      const transformer = fieldConfigAny.ui.valueForClientSerialization as (args: {
+        value: unknown
+      }) => unknown
+      formData[fieldName] = transformer({ value: formData[fieldName] })
+    }
+  }
+
+  // JSON round-trip ensures only serializable data crosses the client boundary
+  const initialData = JSON.parse(JSON.stringify(formData)) as Record<string, unknown>
+
+  return { serializableFields, initialData, relationshipData }
+}

package/tests/components/AdminUIListView.test.tsx

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi } from 'vitest'
+import * as React from 'react'
+import type { AccessContext, OpenSaasConfig } from '@opensaas/stack-core'
+import { list } from '@opensaas/stack-core'
+import { text, timestamp } from '@opensaas/stack-core/fields'
+import { AdminUI } from '../../src/components/AdminUI.js'
+import { ListView } from '../../src/components/ListView.js'
+
+// Mock Next.js navigation — client components call useRouter().
+const mockPush = vi.fn()
+const mockRefresh = vi.fn()
+vi.mock('next/navigation.js', () => ({
+  useRouter: () => ({ push: mockPush, refresh: mockRefresh }),
+}))
+
+vi.mock('next/link.js', () => ({
+  default: ({ children, href }: { children: React.ReactNode; href: string }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+interface DelegateStub {
+  findMany?: (args: unknown) => Promise<Array<Record<string, unknown>>>
+  count?: (args: unknown) => Promise<number>
+}
+
+function makeContext(delegates: Record<string, DelegateStub>): AccessContext<unknown> {
+  const context = {
+    db: delegates,
+    session: null,
+    storage: {},
+    plugins: {},
+    _isSudo: false,
+    _resolveOutputCounter: { depth: 0 },
+  }
+  return context as unknown as AccessContext<unknown>
+}
+
+const noopServerAction = vi.fn(async () => ({ success: true }))
+
+/**
+ * AdminUI returns <> {style?} <div><Navigation/><main>{content}</main></div> </>.
+ * Drill into <main> to recover the routed content element (the <ListView /> the
+ * router chose for the bare [list] route) so we can inspect the props AdminUI
+ * passed to it.
+ */
+function routedContent(tree: React.ReactNode): React.ReactElement {
+  const fragment = tree as React.ReactElement<{ children: React.ReactNode }>
+  const children = React.Children.toArray(fragment.props.children)
+  const wrapper = children.find(
+    (child): child is React.ReactElement<{ children: React.ReactNode }> =>
+      React.isValidElement(child) && child.type === 'div',
+  )
+  if (!wrapper) throw new Error('AdminUI layout wrapper not found')
+  const main = React.Children.toArray(wrapper.props.children).find(
+    (child): child is React.ReactElement<{ children: React.ReactNode }> =>
+      React.isValidElement(child) && child.type === 'main',
+  )
+  if (!main) throw new Error('AdminUI <main> not found')
+  return main.props.children as React.ReactElement
+}
+
+describe('AdminUI ui.listView wiring', () => {
+  it('passes initialColumns + initialSort from ui.listView to ListView', async () => {
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: {
+            title: text(),
+            status: text(),
+            createdAt: timestamp(),
+          },
+          ui: {
+            listView: {
+              initialColumns: ['title', 'status'],
+              initialSort: { field: 'createdAt', direction: 'desc' },
+            },
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({
+      post: { findMany: vi.fn(async () => []), count: vi.fn(async () => 0) },
+    })
+
+    const tree = await AdminUI({
+      context,
+      config,
+      params: ['post'],
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+
+    const content = routedContent(tree)
+    expect(content.type).toBe(ListView)
+    // initialColumns drives the `columns` prop (selection + order).
+    expect(content.props.columns).toEqual(['title', 'status'])
+    // initialSort flows through as the default sort.
+    expect(content.props.initialSort).toEqual({ field: 'createdAt', direction: 'desc' })
+  })
+
+  it('passes undefined columns + initialSort when ui.listView is absent', async () => {
+    const config: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Post: list({
+          fields: {
+            title: text(),
+          },
+        }),
+      },
+    }
+
+    const context = makeContext({
+      post: { findMany: vi.fn(async () => []), count: vi.fn(async () => 0) },
+    })
+
+    const tree = await AdminUI({
+      context,
+      config,
+      params: ['post'],
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+
+    const content = routedContent(tree)
+    expect(content.type).toBe(ListView)
+    // Absent config → current behaviour unchanged (no column override, no default sort).
+    expect(content.props.columns).toBeUndefined()
+    expect(content.props.initialSort).toBeUndefined()
+  })
+})

package/tests/components/AdminUISingleton.test.tsx

@@ -0,0 +1,296 @@
+import { describe, it, expect, vi } from 'vitest'
+import * as React from 'react'
+import { render, screen } from '@testing-library/react'
+import type { AccessContext, OpenSaasConfig } from '@opensaas/stack-core'
+import { list } from '@opensaas/stack-core'
+import { text } from '@opensaas/stack-core/fields'
+import { AdminUI } from '../../src/components/AdminUI.js'
+import { SingletonView } from '../../src/components/SingletonView.js'
+import { ListView } from '../../src/components/ListView.js'
+
+// Mock Next.js navigation — the form/table client components call useRouter().
+const mockPush = vi.fn()
+const mockRefresh = vi.fn()
+vi.mock('next/navigation.js', () => ({
+  useRouter: () => ({ push: mockPush, refresh: mockRefresh }),
+}))
+
+// next/link renders an anchor; happy-dom can render it directly.
+vi.mock('next/link.js', () => ({
+  default: ({ children, href }: { children: React.ReactNode; href: string }) => (
+    <a href={href}>{children}</a>
+  ),
+}))
+
+/**
+ * A config with one singleton list (Settings) and one ordinary list (Post).
+ * Built with the real `list()` + field builders so the components see the
+ * same field shapes they would in a real app.
+ */
+const config: OpenSaasConfig = {
+  db: { provider: 'sqlite', url: 'file:./test.db' },
+  lists: {
+    Settings: list({
+      isSingleton: true,
+      fields: {
+        siteName: text(),
+      },
+    }),
+    Post: list({
+      fields: {
+        title: text(),
+      },
+    }),
+  },
+}
+
+interface DelegateStub {
+  get?: () => Promise<Record<string, unknown> | null>
+  findUnique?: (args: unknown) => Promise<Record<string, unknown> | null>
+  findMany?: (args: unknown) => Promise<Array<Record<string, unknown>>>
+  count?: (args: unknown) => Promise<number>
+}
+
+/**
+ * Build a minimal AccessContext whose db delegates return canned data.
+ * Only the methods the views call are implemented.
+ */
+function makeContext(delegates: Record<string, DelegateStub>): AccessContext<unknown> {
+  const context = {
+    db: delegates,
+    session: null,
+    storage: {},
+    plugins: {},
+    _isSudo: false,
+    _resolveOutputCounter: { depth: 0 },
+  }
+  // Cast: this is a stub for rendering tests, not a full Prisma-backed context.
+  return context as unknown as AccessContext<unknown>
+}
+
+const noopServerAction = vi.fn(async () => ({ success: true }))
+
+// React represents `<Component />` as an element whose `.type` is the component
+// function. The router picks the component but does not await it (nested server
+// components resolve during streaming, not in this unit), so we assert the
+// branch by inspecting which component AdminUI chose for the bare [list] route.
+function routedContent(tree: React.ReactNode): React.ReactElement {
+  // AdminUI returns <> {style?} <div><Navigation/><main>{content}</main></div> </>
+  const fragment = tree as React.ReactElement<{ children: React.ReactNode }>
+  const children = React.Children.toArray(fragment.props.children)
+  const wrapper = children.find(
+    (child): child is React.ReactElement<{ children: React.ReactNode }> =>
+      React.isValidElement(child) && child.type === 'div',
+  )
+  if (!wrapper) throw new Error('AdminUI layout wrapper not found')
+  const main = React.Children.toArray(wrapper.props.children).find(
+    (child): child is React.ReactElement<{ children: React.ReactNode }> =>
+      React.isValidElement(child) && child.type === 'main',
+  )
+  if (!main) throw new Error('AdminUI <main> not found')
+  return main.props.children as React.ReactElement
+}
+
+describe('AdminUI singleton routing', () => {
+  it('routes a singleton bare [list] to SingletonView, a non-singleton to ListView', async () => {
+    const context = makeContext({
+      settings: { get: vi.fn(async () => ({ id: '1', siteName: 'My Site' })) },
+      post: { findMany: vi.fn(async () => []), count: vi.fn(async () => 0) },
+    })
+
+    const singletonTree = await AdminUI({
+      context,
+      config,
+      params: ['settings'],
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+    expect(routedContent(singletonTree).type).toBe(SingletonView)
+
+    const listTree = await AdminUI({
+      context,
+      config,
+      params: ['post'],
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+    expect(routedContent(listTree).type).toBe(ListView)
+  })
+
+  it('renders a single-record editor for a singleton list (SingletonView)', async () => {
+    const singletonGet = vi.fn(async () => ({ id: '1', siteName: 'My Site' }))
+    const context = makeContext({ settings: { get: singletonGet } })
+
+    const element = await SingletonView({
+      context,
+      config,
+      listKey: 'Settings',
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+    render(element)
+
+    // Resolved via the singleton get() (auto-create path), not findMany.
+    expect(singletonGet).toHaveBeenCalledTimes(1)
+
+    // Editor header + the record's value rendered in a field input.
+    expect(screen.getByText('Edit Settings')).toBeInTheDocument()
+    expect(screen.getByDisplayValue('My Site')).toBeInTheDocument()
+
+    // Save button (edit form), not a list-table "Create" affordance.
+    expect(screen.getByRole('button', { name: 'Save' })).toBeInTheDocument()
+    expect(screen.queryByText('Create Settings')).not.toBeInTheDocument()
+  })
+
+  it('renders a create-on-save form for an autoCreate:false singleton with no row', async () => {
+    // autoCreate:false + no row → get() returns null. query+create are allowed,
+    // so the editor must offer a create-on-first-save form (mode="create").
+    const autoCreateFalseConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Settings: list({
+          isSingleton: { autoCreate: false },
+          access: {
+            operation: {
+              query: () => true,
+              create: () => true,
+              update: () => true,
+              delete: () => true,
+            },
+          },
+          fields: { siteName: text() },
+        }),
+      },
+    }
+
+    const singletonGet = vi.fn(async () => null)
+    const context = makeContext({ settings: { get: singletonGet } })
+
+    const element = await SingletonView({
+      context,
+      config: autoCreateFalseConfig,
+      listKey: 'Settings',
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+    render(element)
+
+    expect(singletonGet).toHaveBeenCalledTimes(1)
+
+    // Create header + the create affordance ("Create" submit button), not an edit form.
+    expect(screen.getByText('Create Settings')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Create' })).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Save' })).not.toBeInTheDocument()
+    // An empty field input is rendered (no display value yet).
+    expect(screen.getByText('Site Name')).toBeInTheDocument()
+  })
+
+  it('renders a friendly message (not an editable form) for a read-denied singleton', async () => {
+    // query denied → get() returns null. A null is indistinguishable from an
+    // empty autoCreate:false singleton, so the editor disambiguates via access
+    // and must NOT show an editable/create form.
+    const readDeniedConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Settings: list({
+          isSingleton: true,
+          access: {
+            operation: {
+              query: () => false,
+              create: () => true,
+              update: () => true,
+              delete: () => false,
+            },
+          },
+          fields: { siteName: text() },
+        }),
+      },
+    }
+
+    const singletonGet = vi.fn(async () => null)
+    const context = makeContext({ settings: { get: singletonGet } })
+
+    const element = await SingletonView({
+      context,
+      config: readDeniedConfig,
+      listKey: 'Settings',
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+    render(element)
+
+    // Friendly no-access message, no form affordances at all.
+    expect(screen.getByText("You don't have access to Settings.")).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Create' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Save' })).not.toBeInTheDocument()
+    expect(screen.queryByText('Create Settings')).not.toBeInTheDocument()
+    expect(screen.queryByText('Edit Settings')).not.toBeInTheDocument()
+  })
+
+  it('renders a "no record yet" message when create is denied (no editable form)', async () => {
+    // autoCreate:false + no row, query allowed but create denied → cannot offer
+    // a create form; show a friendly "no record yet" message instead.
+    const createDeniedConfig: OpenSaasConfig = {
+      db: { provider: 'sqlite', url: 'file:./test.db' },
+      lists: {
+        Settings: list({
+          isSingleton: { autoCreate: false },
+          access: {
+            operation: {
+              query: () => true,
+              create: () => false,
+              update: () => true,
+              delete: () => false,
+            },
+          },
+          fields: { siteName: text() },
+        }),
+      },
+    }
+
+    const singletonGet = vi.fn(async () => null)
+    const context = makeContext({ settings: { get: singletonGet } })
+
+    const element = await SingletonView({
+      context,
+      config: createDeniedConfig,
+      listKey: 'Settings',
+      basePath: '/admin',
+      serverAction: noopServerAction,
+    })
+    render(element)
+
+    expect(screen.getByText('There is no Settings record yet.')).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Create' })).not.toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'Save' })).not.toBeInTheDocument()
+  })
+
+  it('renders the list table for a non-singleton list (ListView)', async () => {
+    const findMany = vi.fn(async () => [
+      { id: '1', title: 'First Post' },
+      { id: '2', title: 'Second Post' },
+    ])
+    const count = vi.fn(async () => 2)
+    const context = makeContext({ post: { findMany, count } })
+
+    const element = await ListView({
+      context,
+      config,
+      listKey: 'Post',
+      basePath: '/admin',
+    })
+    render(element)
+
+    // List view fetches via findMany/count (the singleton get() is never called).
+    expect(findMany).toHaveBeenCalledTimes(1)
+    expect(count).toHaveBeenCalledTimes(1)
+
+    // The list table renders rows + the "Create" affordance.
+    expect(screen.getByText('First Post')).toBeInTheDocument()
+    expect(screen.getByText('Second Post')).toBeInTheDocument()
+    expect(screen.getByText('Create Post')).toBeInTheDocument()
+
+    // It is NOT the singleton editor.
+    expect(screen.queryByText('Edit Post')).not.toBeInTheDocument()
+  })
+})