@opensaas/stack-ui 0.20.0 → 0.21.0

package/src/components/standalone/ItemCreateForm.tsx

@@ -1,12 +1,13 @@
 'use client'
 
 import * as React from 'react'
-import { useState, useMemo } from 'react'
+import { useMemo } from 'react'
 import { FieldRenderer } from '../fields/FieldRenderer.js'
 import { LoadingSpinner } from '../LoadingSpinner.js'
 import { Button } from '../../primitives/button.js'
 import type { FieldConfig } from '@opensaas/stack-core'
 import { serializeFieldConfigs } from '../../lib/serializeFieldConfig.js'
+import { useItemForm } from '../../lib/useItemForm.js'
 
 export interface ItemCreateFormProps<TData = Record<string, unknown>> {
   fields: Record<string, FieldConfig>
@@ -46,74 +47,25 @@ export function ItemCreateForm<TData = Record<string, unknown>>({
   // Serialize field configs to remove non-serializable properties
   const serializedFields = useMemo(() => serializeFieldConfigs(fields), [fields])
 
-  const [isPending, setIsPending] = useState(false)
-  const [formData, setFormData] = useState<Partial<TData>>({} as Partial<TData>)
-  const [errors, setErrors] = useState<Record<string, string>>({})
-  const [generalError, setGeneralError] = useState<string | null>(null)
-
-  const handleFieldChange = (fieldName: string, value: unknown) => {
-    setFormData((prev) => ({ ...prev, [fieldName]: value }) as Partial<TData>)
-    // Clear error for this field when user starts typing
-    if (errors[fieldName]) {
-      setErrors((prev) => {
-        const newErrors = { ...prev }
-        delete newErrors[fieldName]
-        return newErrors
-      })
-    }
-  }
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault()
-    setErrors({})
-    setGeneralError(null)
-    setIsPending(true)
-
-    try {
-      // Transform relationship fields to Prisma format
-      const transformedData: Record<string, unknown> = {}
-      for (const [fieldName, value] of Object.entries(formData as Record<string, unknown>)) {
-        const fieldConfig = serializedFields[fieldName]
-
-        // Transform relationship fields
-        if (fieldConfig?.type === 'relationship') {
-          if (fieldConfig.many) {
-            // Many relationship: use connect format
-            if (Array.isArray(value) && value.length > 0) {
-              transformedData[fieldName] = {
-                connect: value.map((id: string) => ({ id })),
-              }
-            }
-          } else {
-            // Single relationship: use connect format
-            if (value) {
-              transformedData[fieldName] = {
-                connect: { id: value },
-              }
-            }
-          }
-        } else {
-          // Non-relationship field: pass through
-          transformedData[fieldName] = value
-        }
-      }
-
-      const result = await onSubmit(transformedData as TData)
-
-      if (!result.success) {
-        setGeneralError(result.error || 'Failed to create item')
-      }
-    } catch (error: unknown) {
-      setGeneralError((error as Error).message || 'Failed to create item')
-    } finally {
-      setIsPending(false)
-    }
-  }
-
-  // Filter out system fields
-  const editableFields = Object.entries(serializedFields).filter(
-    ([key]) => !['id', 'createdAt', 'updatedAt'].includes(key),
-  )
+  const {
+    formData,
+    errors,
+    generalError,
+    isPending,
+    editableFields,
+    handleFieldChange,
+    handleSubmit,
+  } = useItemForm({
+    fields: serializedFields,
+    mode: 'create',
+    errorFallback: 'Failed to create item',
+    onSubmit: async (data) => {
+      const result = await onSubmit(data as TData)
+      return result.success
+        ? { success: true }
+        : { success: false, error: result.error || 'Failed to create item' }
+    },
+  })
 
   return (
     <form onSubmit={handleSubmit} className={className}>

package/src/components/standalone/ItemEditForm.tsx

@@ -1,12 +1,13 @@
 'use client'
 
 import * as React from 'react'
-import { useState, useMemo } from 'react'
+import { useMemo } from 'react'
 import { FieldRenderer } from '../fields/FieldRenderer.js'
 import { LoadingSpinner } from '../LoadingSpinner.js'
 import { Button } from '../../primitives/button.js'
 import type { FieldConfig } from '@opensaas/stack-core'
 import { serializeFieldConfigs } from '../../lib/serializeFieldConfig.js'
+import { useItemForm, transformInitialData } from '../../lib/useItemForm.js'
 
 export interface ItemEditFormProps<TData = Record<string, unknown>> {
   fields: Record<string, FieldConfig>
@@ -52,100 +53,32 @@ export function ItemEditForm<TData = Record<string, unknown>>({
   const serializedFields = useMemo(() => serializeFieldConfigs(fields), [fields])
 
   // Apply valueForClientSerialization transformations to initial data
-  const transformedInitialData = useMemo(() => {
-    const transformed = { ...initialData }
-    for (const [fieldName, fieldConfig] of Object.entries(fields)) {
-      const fieldConfigAny = fieldConfig as { ui?: Record<string, unknown> }
-      if (
-        fieldConfigAny.ui?.valueForClientSerialization &&
-        typeof fieldConfigAny.ui.valueForClientSerialization === 'function'
-      ) {
-        const transformer = fieldConfigAny.ui.valueForClientSerialization as (args: {
-          value: unknown
-        }) => unknown
-        transformed[fieldName as keyof TData] = transformer({
-          value: transformed[fieldName as keyof TData],
-        }) as TData[keyof TData]
-      }
-    }
-    return transformed
-  }, [initialData, fields])
-
-  const [isPending, setIsPending] = useState(false)
-  const [formData, setFormData] = useState<TData>(transformedInitialData)
-  const [errors, setErrors] = useState<Record<string, string>>({})
-  const [generalError, setGeneralError] = useState<string | null>(null)
-
-  const handleFieldChange = (fieldName: string, value: unknown) => {
-    setFormData((prev) => ({ ...prev, [fieldName]: value }) as TData)
-    // Clear error for this field when user starts typing
-    if (errors[fieldName]) {
-      setErrors((prev) => {
-        const newErrors = { ...prev }
-        delete newErrors[fieldName]
-        return newErrors
-      })
-    }
-  }
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault()
-    setErrors({})
-    setGeneralError(null)
-    setIsPending(true)
-
-    try {
-      // Transform relationship fields to Prisma format
-      // Filter out password fields with isSet objects (unchanged passwords)
-      const transformedData: Record<string, unknown> = {}
-      for (const [fieldName, value] of Object.entries(formData as Record<string, unknown>)) {
-        const fieldConfig = serializedFields[fieldName]
-
-        // Skip password fields that have { isSet: boolean } value (not being changed)
-        if (typeof value === 'object' && value !== null && 'isSet' in value) {
-          continue
-        }
-
-        // Transform relationship fields
-        if (fieldConfig?.type === 'relationship') {
-          if (fieldConfig.many) {
-            // Many relationship: use connect format
-            if (Array.isArray(value) && value.length > 0) {
-              transformedData[fieldName] = {
-                connect: value.map((id: string) => ({ id })),
-              }
-            }
-          } else {
-            // Single relationship: use connect format
-            if (value) {
-              transformedData[fieldName] = {
-                connect: { id: value },
-              }
-            }
-          }
-        } else {
-          // Non-relationship field: pass through
-          transformedData[fieldName] = value
-        }
-      }
-
-      const result = await onSubmit(transformedData as TData)
-
-      if (!result.success) {
-        setGeneralError(result.error || 'Failed to update item')
-      }
-    } catch (error: unknown) {
-      setGeneralError((error as Error).message || 'Failed to update item')
-    } finally {
-      setIsPending(false)
-    }
-  }
-
-  // Filter out system fields
-  const editableFields = Object.entries(serializedFields).filter(
-    ([key]) => !['id', 'createdAt', 'updatedAt'].includes(key),
+  const transformedInitialData = useMemo(
+    () => transformInitialData(fields, initialData as Record<string, unknown>),
+    [initialData, fields],
   )
 
+  const {
+    formData,
+    errors,
+    generalError,
+    isPending,
+    editableFields,
+    handleFieldChange,
+    handleSubmit,
+  } = useItemForm({
+    fields: serializedFields,
+    initialData: transformedInitialData,
+    mode: 'update',
+    errorFallback: 'Failed to update item',
+    onSubmit: async (data) => {
+      const result = await onSubmit(data as TData)
+      return result.success
+        ? { success: true }
+        : { success: false, error: result.error || 'Failed to update item' }
+    },
+  })
+
   return (
     <form onSubmit={handleSubmit} className={className}>
       {/* General Error */}

package/src/lib/theme.ts

@@ -1,4 +1,4 @@
-import type { ThemeColors, ThemeConfig, ThemePreset } from '@opensaas/stack-core'
+import type { ThemeColors, ThemeConfig, ThemePreset } from '@opensaas/stack-core/internal'
 
 /**
  * Preset theme definitions

package/src/lib/useItemForm.ts

@@ -0,0 +1,194 @@
+'use client'
+
+import { useState, useTransition } from 'react'
+import type { SerializableFieldConfig } from './serializeFieldConfig.js'
+
+/**
+ * The action an item form submission represents.
+ */
+export type ItemFormAction = 'create' | 'update'
+
+const SYSTEM_FIELDS = ['id', 'createdAt', 'updatedAt']
+
+/**
+ * Transform raw form state into the data shape expected by the server/Prisma.
+ *
+ * This is the shared submit transform used by every item form (the AdminUI
+ * form and the standalone create/edit forms). Keeping it a pure function makes
+ * it testable without rendering a component.
+ *
+ * Behaviour (the superset applied by all forms):
+ * - Relationship fields are converted to Prisma `connect` shape (single or many).
+ *   Empty single relationships and empty many-arrays are omitted.
+ * - Password fields whose value is an `{ isSet }` sentinel (an unchanged password
+ *   read back from the server) are skipped, so they are not re-submitted.
+ * - All other fields pass through unchanged (including `File` objects, which the
+ *   Next.js server action serialises).
+ */
+export function transformItemFormData(
+  fields: Record<string, SerializableFieldConfig>,
+  formData: Record<string, unknown>,
+): Record<string, unknown> {
+  const transformed: Record<string, unknown> = {}
+
+  for (const [fieldName, value] of Object.entries(formData)) {
+    const fieldConfig = fields[fieldName]
+
+    // Skip password fields carrying an { isSet } sentinel (unchanged password).
+    if (typeof value === 'object' && value !== null && 'isSet' in value) {
+      continue
+    }
+
+    if (fieldConfig?.type === 'relationship') {
+      if (fieldConfig.many) {
+        if (Array.isArray(value) && value.length > 0) {
+          transformed[fieldName] = { connect: value.map((id: string) => ({ id })) }
+        }
+      } else if (value) {
+        transformed[fieldName] = { connect: { id: value } }
+      }
+    } else {
+      transformed[fieldName] = value
+    }
+  }
+
+  return transformed
+}
+
+/**
+ * Apply each field's `valueForClientSerialization` transform to initial data,
+ * so values read from the server are shaped for the client form inputs.
+ *
+ * Operates on the original (non-serialized) field configs because the transform
+ * function is stripped during serialization.
+ */
+export function transformInitialData<TData extends Record<string, unknown>>(
+  fields: Record<string, unknown>,
+  initialData: TData,
+): TData {
+  const transformed = { ...initialData }
+  for (const [fieldName, fieldConfig] of Object.entries(fields)) {
+    const ui = (fieldConfig as { ui?: Record<string, unknown> }).ui
+    const transformer = ui?.valueForClientSerialization
+    if (typeof transformer === 'function') {
+      transformed[fieldName as keyof TData] = (
+        transformer as (args: { value: unknown }) => unknown
+      )({ value: transformed[fieldName as keyof TData] }) as TData[keyof TData]
+    }
+  }
+  return transformed
+}
+
+/**
+ * Drop system fields (id, createdAt, updatedAt) from a field-config map,
+ * returning the editable entries in declaration order.
+ */
+export function getEditableFields(
+  fields: Record<string, SerializableFieldConfig>,
+): Array<[string, SerializableFieldConfig]> {
+  return Object.entries(fields).filter(([key]) => !SYSTEM_FIELDS.includes(key))
+}
+
+/**
+ * Result of a form submission adapter. `false`/error means the submission
+ * failed and the form should surface `error` (and optional per-field errors).
+ */
+export type ItemFormSubmitResult =
+  | { success: true }
+  | { success: false; error: string; fieldErrors?: Record<string, string> }
+
+export interface UseItemFormOptions {
+  /** Serialized field configs (drives rendering + the submit transform). */
+  fields: Record<string, SerializableFieldConfig>
+  /** Initial form values (already client-serialized). */
+  initialData?: Record<string, unknown>
+  /** Whether this form creates or updates. Selects the submit action. */
+  mode: ItemFormAction
+  /**
+   * Submit adapter. Receives the transformed data and the action; each caller
+   * wires this to its own mechanism (AdminUI server action + navigation, or a
+   * standalone `onSubmit` callback). May return void for the legacy/standalone
+   * "throw on failure" style.
+   */
+  onSubmit: (
+    data: Record<string, unknown>,
+    action: ItemFormAction,
+  ) => Promise<ItemFormSubmitResult | void>
+  /** Optional fallback message when a submit throws without a message. */
+  errorFallback?: string
+}
+
+export interface UseItemFormResult {
+  formData: Record<string, unknown>
+  errors: Record<string, string>
+  generalError: string | null
+  isPending: boolean
+  editableFields: Array<[string, SerializableFieldConfig]>
+  handleFieldChange: (fieldName: string, value: unknown) => void
+  handleSubmit: (e: { preventDefault: () => void }) => void
+  setGeneralError: (message: string | null) => void
+}
+
+/**
+ * The shared item-form engine.
+ *
+ * Holds the form state, the clear-error-on-change behaviour, the submit
+ * transform, and the pending state (via `useTransition`) that every item form
+ * needs. Callers supply only an `onSubmit` adapter and render the returned
+ * fields/handlers — so the AdminUI form and the standalone create/edit forms
+ * stay thin and share one tested code path.
+ */
+export function useItemForm({
+  fields,
+  initialData = {},
+  mode,
+  onSubmit,
+  errorFallback = 'Operation failed',
+}: UseItemFormOptions): UseItemFormResult {
+  const [isPending, startTransition] = useTransition()
+  const [formData, setFormData] = useState<Record<string, unknown>>(initialData)
+  const [errors, setErrors] = useState<Record<string, string>>({})
+  const [generalError, setGeneralError] = useState<string | null>(null)
+
+  const handleFieldChange = (fieldName: string, value: unknown) => {
+    setFormData((prev) => ({ ...prev, [fieldName]: value }))
+    if (errors[fieldName]) {
+      setErrors((prev) => {
+        const next = { ...prev }
+        delete next[fieldName]
+        return next
+      })
+    }
+  }
+
+  const handleSubmit = (e: { preventDefault: () => void }) => {
+    e.preventDefault()
+    setErrors({})
+    setGeneralError(null)
+
+    startTransition(async () => {
+      const data = transformItemFormData(fields, formData)
+      try {
+        const result = await onSubmit(data, mode)
+        // void result → adapter handles its own success/navigation.
+        if (result && result.success === false) {
+          if (result.fieldErrors) setErrors(result.fieldErrors)
+          setGeneralError(result.error || errorFallback)
+        }
+      } catch (error: unknown) {
+        setGeneralError((error as Error)?.message || errorFallback)
+      }
+    })
+  }
+
+  return {
+    formData,
+    errors,
+    generalError,
+    isPending,
+    editableFields: getEditableFields(fields),
+    handleFieldChange,
+    handleSubmit,
+    setGeneralError,
+  }
+}

package/src/server/types.ts

@@ -2,7 +2,7 @@
  * Input for the generic server action
  * Re-exported from @opensaas/stack-core for convenience
  */
-export type { ServerActionProps as ServerActionInput } from '@opensaas/stack-core'
+export type { ServerActionProps as ServerActionInput } from '@opensaas/stack-core/internal'
 
 /**
  * Result of a server action

package/tests/lib/useItemForm.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect } from 'vitest'
+import {
+  transformItemFormData,
+  transformInitialData,
+  getEditableFields,
+} from '../../src/lib/useItemForm.js'
+import type { SerializableFieldConfig } from '../../src/lib/serializeFieldConfig.js'
+
+const text = (): SerializableFieldConfig => ({ type: 'text' })
+const singleRel = (): SerializableFieldConfig => ({ type: 'relationship', many: false })
+const manyRel = (): SerializableFieldConfig => ({ type: 'relationship', many: true })
+const password = (): SerializableFieldConfig => ({ type: 'password' })
+
+describe('transformItemFormData', () => {
+  it('passes scalar fields through unchanged', () => {
+    const fields = { title: text(), views: text() }
+    const out = transformItemFormData(fields, { title: 'Hi', views: 3 })
+    expect(out).toEqual({ title: 'Hi', views: 3 })
+  })
+
+  it('converts a single relationship to connect shape', () => {
+    const fields = { author: singleRel() }
+    expect(transformItemFormData(fields, { author: 'u1' })).toEqual({
+      author: { connect: { id: 'u1' } },
+    })
+  })
+
+  it('omits an empty single relationship', () => {
+    const fields = { author: singleRel() }
+    expect(transformItemFormData(fields, { author: '' })).toEqual({})
+    expect(transformItemFormData(fields, { author: null })).toEqual({})
+  })
+
+  it('converts a many relationship to connect-array shape', () => {
+    const fields = { tags: manyRel() }
+    expect(transformItemFormData(fields, { tags: ['a', 'b'] })).toEqual({
+      tags: { connect: [{ id: 'a' }, { id: 'b' }] },
+    })
+  })
+
+  it('omits an empty many relationship', () => {
+    const fields = { tags: manyRel() }
+    expect(transformItemFormData(fields, { tags: [] })).toEqual({})
+  })
+
+  it('skips password fields carrying an { isSet } sentinel', () => {
+    const fields = { password: password() }
+    expect(transformItemFormData(fields, { password: { isSet: true } })).toEqual({})
+  })
+
+  it('submits a password when a new plaintext value is provided', () => {
+    const fields = { password: password() }
+    expect(transformItemFormData(fields, { password: 'secret' })).toEqual({ password: 'secret' })
+  })
+
+  it('handles a mixed payload end-to-end', () => {
+    const fields = {
+      title: text(),
+      author: singleRel(),
+      tags: manyRel(),
+      password: password(),
+    }
+    const out = transformItemFormData(fields, {
+      title: 'Post',
+      author: 'u1',
+      tags: ['t1'],
+      password: { isSet: true },
+    })
+    expect(out).toEqual({
+      title: 'Post',
+      author: { connect: { id: 'u1' } },
+      tags: { connect: [{ id: 't1' }] },
+    })
+  })
+})
+
+describe('transformInitialData', () => {
+  it('applies a field valueForClientSerialization transform', () => {
+    const fields = {
+      when: {
+        type: 'timestamp',
+        ui: { valueForClientSerialization: ({ value }: { value: unknown }) => `iso:${value}` },
+      },
+      title: { type: 'text' },
+    }
+    const out = transformInitialData(fields, { when: 123, title: 'x' })
+    expect(out).toEqual({ when: 'iso:123', title: 'x' })
+  })
+
+  it('leaves data unchanged when no transform is defined', () => {
+    const fields = { title: { type: 'text' } }
+    expect(transformInitialData(fields, { title: 'x' })).toEqual({ title: 'x' })
+  })
+})
+
+describe('getEditableFields', () => {
+  it('drops system fields and preserves declaration order', () => {
+    const fields = {
+      id: text(),
+      title: text(),
+      createdAt: text(),
+      body: text(),
+      updatedAt: text(),
+    }
+    expect(getEditableFields(fields).map(([k]) => k)).toEqual(['title', 'body'])
+  })
+})