@opensaas/stack-ui 0.22.0 → 0.23.0

package/src/components/ItemForm.tsx

@@ -4,7 +4,7 @@ import { ItemFormClient } from './ItemFormClient.js'
 import { formatListName } from '../lib/utils.js'
 import type { ServerActionInput } from '../server/types.js'
 import { type AccessContext, getDbKey, getUrlKey, OpenSaasConfig } from '@opensaas/stack-core'
-import { serializeFieldConfigs } from '../lib/serializeFieldConfig.js'
+import { buildRelationshipInclude, prepareItemForm } from '../lib/prepareItemForm.js'
 
 export interface ItemFormProps {
   context: AccessContext<unknown>
@@ -48,16 +48,8 @@ export async function ItemForm({
   let itemData: Record<string, unknown> = {}
   if (mode === 'edit' && itemId) {
     try {
-      // Build include object for relationships
-      const includeRelationships: Record<string, boolean> = {}
-      for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
-        const fieldConfigAny = fieldConfig as { type: string }
-        if (fieldConfigAny.type === 'relationship') {
-          includeRelationships[fieldName] = true
-        }
-      }
-
       // Fetch item with relationships included
+      const includeRelationships = buildRelationshipInclude(listConfig)
       const delegate = context.db[getDbKey(listKey)]
       if (delegate?.findUnique) {
         itemData = await delegate.findUnique({
@@ -90,72 +82,14 @@ export async function ItemForm({
     }
   }
 
-  // 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)) {
-    // Check if field is a relationship type by checking the discriminated union
-    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 dbContext = context.db
-            const delegate = dbContext[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] })
-    }
-  }
+  // Fetch relationship options, serialize field configs, and transform the
+  // record into client-ready form data (shared with the singleton editor).
+  const { serializableFields, initialData, relationshipData } = await prepareItemForm(
+    context,
+    config,
+    listConfig,
+    itemData,
+  )
 
   return (
     <div className="p-8 max-w-4xl">
@@ -187,7 +121,7 @@ export async function ItemForm({
           urlKey={urlKey}
           mode={mode}
           fields={serializableFields}
-          initialData={JSON.parse(JSON.stringify(formData))}
+          initialData={initialData}
           itemId={itemId}
           basePath={basePath}
           serverAction={serverAction}

package/src/components/ItemFormClient.tsx

@@ -21,6 +21,13 @@ export interface ItemFormClientProps {
   basePath: string
   serverAction: (input: ServerActionInput) => Promise<unknown>
   relationshipData?: Record<string, Array<{ id: string; label: string }>>
+  /**
+   * Whether to render the delete affordance in edit mode. Defaults to `true`.
+   * Singletons set this to `false` — a singleton has exactly one record that
+   * can't be deleted (core blocks `delete` even in sudo), so the control is
+   * suppressed for UX hygiene.
+   */
+  canDelete?: boolean
 }
 
 /**
@@ -58,6 +65,7 @@ export function ItemFormClient({
   basePath,
   serverAction,
   relationshipData = {},
+  canDelete = true,
 }: ItemFormClientProps) {
   const router = useRouter()
   const [showDeleteConfirm, setShowDeleteConfirm] = useState(false)
@@ -162,8 +170,8 @@ export function ItemFormClient({
           </Button>
         </div>
 
-        {/* Delete Button (Edit Mode Only) */}
-        {mode === 'edit' && itemId && (
+        {/* Delete Button (Edit Mode Only; suppressed for singletons) */}
+        {mode === 'edit' && itemId && canDelete && (
           <Button
             type="button"
             variant="destructive"

package/src/components/Navigation.tsx

@@ -22,7 +22,12 @@ export function Navigation({
   currentPath = '',
   onSignOut,
 }: NavigationProps) {
-  const lists = Object.keys(config.lists || {})
+  const allLists = Object.keys(config.lists || {})
+  // Split lists into standard lists (under "Lists") and singletons (under
+  // "Settings"). A singleton edits a single record, so it belongs in a distinct
+  // Settings group rather than the standard list grid.
+  const lists = allLists.filter((listKey) => !config.lists[listKey]?.isSingleton)
+  const singletons = allLists.filter((listKey) => config.lists[listKey]?.isSingleton)
 
   return (
     <nav className="w-64 border-r border-border bg-card h-screen sticky top-0 flex flex-col">
@@ -90,6 +95,58 @@ export function Navigation({
               })}
             </>
           )}
+
+          {singletons.length > 0 && (
+            <>
+              <div className="pt-4 pb-2 px-3">
+                <p className="text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+                  Settings
+                </p>
+              </div>
+              {singletons.map((listKey) => {
+                const urlKey = getUrlKey(listKey)
+                const isActive = currentPath.startsWith(`/${urlKey}`)
+                return (
+                  <Link
+                    key={listKey}
+                    href={`${basePath}/${urlKey}`}
+                    className={`block px-3 py-2.5 rounded-lg text-sm font-medium transition-all relative overflow-hidden group ${
+                      isActive
+                        ? 'bg-gradient-to-r from-primary to-accent text-primary-foreground shadow-lg shadow-primary/25'
+                        : 'text-foreground hover:bg-accent/50 hover:text-accent-foreground'
+                    }`}
+                  >
+                    {isActive && (
+                      <div className="absolute inset-0 bg-gradient-to-r from-primary/20 to-accent/20 animate-pulse" />
+                    )}
+                    <span className="relative flex items-center gap-2">
+                      <svg
+                        className="w-4 h-4 opacity-60 group-hover:opacity-100 transition-opacity"
+                        fill="none"
+                        stroke="currentColor"
+                        viewBox="0 0 24 24"
+                        aria-hidden="true"
+                      >
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"
+                        />
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"
+                        />
+                      </svg>
+                      {formatListName(listKey)}
+                    </span>
+                  </Link>
+                )
+              })}
+            </>
+          )}
         </div>
       </div>
 

package/src/components/SingletonView.tsx

@@ -0,0 +1,228 @@
+import * as React from 'react'
+import Link from 'next/link.js'
+import { ItemFormClient } from './ItemFormClient.js'
+import { formatListName } from '../lib/utils.js'
+import type { ServerActionInput } from '../server/types.js'
+import { type AccessContext, getDbKey, getUrlKey, OpenSaasConfig } from '@opensaas/stack-core'
+import { prepareItemForm } from '../lib/prepareItemForm.js'
+import { isOperationPotentiallyAllowed } from '../lib/operationAccess.js'
+
+export interface SingletonViewProps {
+  context: AccessContext<unknown>
+  config: OpenSaasConfig
+  listKey: string
+  basePath?: string
+  // Server action can return any shape depending on the list item type
+  serverAction: (input: ServerActionInput) => Promise<unknown>
+}
+
+/**
+ * Singleton editor — renders a single-record edit form for a list configured
+ * with `isSingleton: true`.
+ *
+ * Resolves the record via the singleton `get()` operation (which auto-creates
+ * the row with field defaults when absent, unless `autoCreate: false`), then
+ * reuses the same `ItemFormClient` + serialization path as `ItemForm` so the
+ * existing field rendering, validation, and `serverAction` save flow apply.
+ *
+ * A `null` from `get()` is ambiguous at the boundary — it means EITHER an
+ * `autoCreate: false` singleton with no row yet, OR that `query` access is
+ * denied (access-controlled reads return null/[] silently). We disambiguate
+ * using the list's operation-level access:
+ *
+ * - `query` denied  → friendly "no access" message (never an editable form).
+ * - `query` allowed + `create` allowed → a create-on-first-save form
+ *   (`ItemFormClient` in `mode="create"`); core assigns the singleton `id` and
+ *   enforces the single-record constraint on create.
+ * - `query` allowed + `create` denied → friendly "no record yet" message.
+ *
+ * An update-denied singleton still renders the edit form (the happy path), but
+ * the save fails gracefully: the server action's `update` access check returns
+ * a denied envelope, which `ItemFormClient` surfaces as an error.
+ *
+ * Server Component that fetches data and sets up actions.
+ */
+export async function SingletonView({
+  context,
+  config,
+  listKey,
+  basePath = '/admin',
+  serverAction,
+}: SingletonViewProps) {
+  const listConfig = config.lists[listKey]
+  const urlKey = getUrlKey(listKey)
+
+  if (!listConfig) {
+    return (
+      <div className="p-8">
+        <div className="bg-destructive/10 border border-destructive text-destructive rounded-lg p-6">
+          <h2 className="text-lg font-semibold mb-2">List not found</h2>
+          <p>The list &quot;{listKey}&quot; does not exist in your configuration.</p>
+        </div>
+      </div>
+    )
+  }
+
+  // Resolve the singleton record. `get()` auto-creates with field defaults when
+  // absent (the default), so a record is the common case. It returns null when
+  // either `autoCreate: false` with no row yet, OR `query` access is denied —
+  // these are indistinguishable here, so we disambiguate via access below.
+  let record: Record<string, unknown> | null = null
+  try {
+    const delegate = context.db[getDbKey(listKey)]
+    if (delegate?.get) {
+      record = await delegate.get()
+    }
+  } catch (error) {
+    console.error(`Failed to resolve singleton ${listKey}:`, error)
+  }
+
+  if (!record) {
+    // A null `get()` is ambiguous (autoCreate:false-empty vs query-denied).
+    // Evaluate operation access to choose the safe affordance.
+    const accessArgs = { session: context.session, context }
+    const canQuery = await isOperationPotentiallyAllowed(
+      listConfig.access?.operation,
+      'query',
+      accessArgs,
+    )
+
+    // Query denied → the session cannot read this singleton at all. Show a
+    // friendly message; never an editable/create form.
+    if (!canQuery) {
+      return (
+        <div className="p-8 max-w-4xl">
+          <div className="mb-8">
+            <h1 className="text-3xl font-bold">{formatListName(listKey)}</h1>
+          </div>
+          <div className="bg-muted/50 border border-border rounded-lg p-6">
+            <p className="text-muted-foreground">
+              You don&apos;t have access to {formatListName(listKey)}.
+            </p>
+          </div>
+        </div>
+      )
+    }
+
+    // Query allowed but no row → an `autoCreate: false` singleton. Offer a
+    // create-on-first-save form only when `create` is actually permitted.
+    const canCreate = await isOperationPotentiallyAllowed(
+      listConfig.access?.operation,
+      'create',
+      accessArgs,
+    )
+
+    if (!canCreate) {
+      return (
+        <div className="p-8 max-w-4xl">
+          <div className="mb-8">
+            <h1 className="text-3xl font-bold">{formatListName(listKey)}</h1>
+          </div>
+          <div className="bg-muted/50 border border-border rounded-lg p-6">
+            <p className="text-muted-foreground">
+              There is no {formatListName(listKey)} record yet.
+            </p>
+          </div>
+        </div>
+      )
+    }
+
+    // Create-on-first-save: render the form in create mode with an empty record.
+    // The save goes through the existing `serverAction` create path; core
+    // assigns the singleton `id` (always `1`) and enforces the single-record
+    // constraint, so the form sends only the user-entered field data.
+    const {
+      serializableFields: createFields,
+      initialData: createInitialData,
+      relationshipData: createRelationshipData,
+    } = await prepareItemForm(context, config, listConfig, {})
+
+    return (
+      <div className="p-8 max-w-4xl">
+        {/* Header — a singleton has no list view, so link back to the dashboard. */}
+        <div className="mb-8">
+          <Link
+            href={basePath}
+            className="inline-flex items-center text-sm text-muted-foreground hover:text-foreground mb-4"
+          >
+            <svg className="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+              <path
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                strokeWidth={2}
+                d="M15 19l-7-7 7-7"
+              />
+            </svg>
+            Back to dashboard
+          </Link>
+          <h1 className="text-3xl font-bold">Create {formatListName(listKey)}</h1>
+        </div>
+
+        {/* Create-on-first-save form */}
+        <div className="bg-card border border-border rounded-lg p-6">
+          <ItemFormClient
+            listKey={listKey}
+            urlKey={urlKey}
+            mode="create"
+            fields={createFields}
+            initialData={createInitialData}
+            basePath={basePath}
+            serverAction={serverAction}
+            relationshipData={createRelationshipData}
+            canDelete={false}
+          />
+        </div>
+      </div>
+    )
+  }
+
+  // Reuse the shared field-serialization + relationship-data logic so the
+  // singleton editor stays in lockstep with the regular item form.
+  const { serializableFields, initialData, relationshipData } = await prepareItemForm(
+    context,
+    config,
+    listConfig,
+    record,
+  )
+
+  const itemId = record.id as string
+
+  return (
+    <div className="p-8 max-w-4xl">
+      {/* Header — a singleton has no list view, so link back to the dashboard. */}
+      <div className="mb-8">
+        <Link
+          href={basePath}
+          className="inline-flex items-center text-sm text-muted-foreground hover:text-foreground mb-4"
+        >
+          <svg className="w-4 h-4 mr-1" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M15 19l-7-7 7-7"
+            />
+          </svg>
+          Back to dashboard
+        </Link>
+        <h1 className="text-3xl font-bold">Edit {formatListName(listKey)}</h1>
+      </div>
+
+      {/* Form */}
+      <div className="bg-card border border-border rounded-lg p-6">
+        <ItemFormClient
+          listKey={listKey}
+          urlKey={urlKey}
+          mode="edit"
+          fields={serializableFields}
+          initialData={initialData}
+          itemId={itemId}
+          basePath={basePath}
+          serverAction={serverAction}
+          relationshipData={relationshipData}
+          canDelete={false}
+        />
+      </div>
+    </div>
+  )
+}

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 }
+}