@startsimpli/ui 0.4.35 → 0.4.37

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/ui",
-  "version": "0.4.35",
+  "version": "0.4.37",
   "description": "Shared UI components package for StartSimpli applications",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -33,8 +33,8 @@
     "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
-    "@startsimpli/api": "0.5.35",
-    "@startsimpli/auth": "0.4.28"
+    "@startsimpli/auth": "0.4.28",
+    "@startsimpli/api": "0.5.35"
   },
   "peerDependenciesMeta": {
     "@startsimpli/api": {

package/src/components/schema/RelationshipBuilder.tsx

@@ -0,0 +1,167 @@
+'use client'
+
+import { useState } from 'react'
+import { Button } from '../ui/button'
+import { Input } from '../ui/input'
+import { Label } from '../ui/label'
+import { Card, CardContent, CardHeader, CardTitle } from '../ui/card'
+import {
+  Select,
+  SelectTrigger,
+  SelectValue,
+  SelectContent,
+  SelectItem,
+} from '../ui/select'
+import { notify as defaultNotify } from '../toast'
+import { cn } from '../../lib/utils'
+import { suggestRelationshipKey, type SchemaId } from './schema-builder-core'
+import type { SchemaTypeBuilderNotifier } from './SchemaTypeBuilder'
+
+/** A type option the edge can connect (id + its key/label for display). */
+export interface RelationshipTypeOption {
+  id: SchemaId
+  key: string
+  label: string
+}
+
+export interface RelationshipBuilderClassNames {
+  root?: string
+  card?: string
+  submit?: string
+}
+
+export interface RelationshipBuilderProps {
+  /** The org's entity types — the selectable endpoints of the edge. */
+  types: RelationshipTypeOption[]
+  /** Persist a relationship definition (typed edge source_type -> target_type). */
+  createRelationship: (input: {
+    key: string
+    sourceType: SchemaId
+    targetType: SchemaId
+  }) => Promise<unknown>
+  /** Fired after the relationship def is created (refetch here). */
+  onCreated?: (created: { key: string }) => void
+  notify?: SchemaTypeBuilderNotifier
+  classNames?: RelationshipBuilderClassNames
+}
+
+/**
+ * No-code relationship builder (768w.10.4 S5): connect two entity types with a
+ * typed edge. The persistence layer is injected via `createRelationship`; the
+ * consuming app supplies the type list + handles refetch in `onCreated`.
+ */
+export function RelationshipBuilder({
+  types,
+  createRelationship,
+  onCreated,
+  notify = defaultNotify,
+  classNames,
+}: RelationshipBuilderProps) {
+  const [sourceId, setSourceId] = useState('')
+  const [targetId, setTargetId] = useState('')
+  const [keyOverride, setKeyOverride] = useState('')
+  const [saving, setSaving] = useState(false)
+
+  const sourceKey = types.find((t) => String(t.id) === sourceId)?.key ?? ''
+  const targetKey = types.find((t) => String(t.id) === targetId)?.key ?? ''
+  const effectiveKey = keyOverride.trim() || suggestRelationshipKey(sourceKey, targetKey)
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    if (!sourceId || !targetId) {
+      notify.error?.('Pick a source and a target type.')
+      return
+    }
+    if (!effectiveKey) {
+      notify.error?.('Give the relationship a name.')
+      return
+    }
+    setSaving(true)
+    try {
+      await createRelationship({ key: effectiveKey, sourceType: sourceId, targetType: targetId })
+      notify.success?.(`Connected ${sourceKey} → ${targetKey}.`)
+      onCreated?.({ key: effectiveKey })
+      setKeyOverride('')
+    } catch (err) {
+      notify.error?.(err instanceof Error ? err.message : 'Could not create the relationship.')
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <form onSubmit={handleSubmit} className={cn('space-y-6', classNames?.root)}>
+      <Card className={classNames?.card}>
+        <CardHeader>
+          <CardTitle>Connect two types</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          {types.length === 0 ? (
+            <p className="text-sm text-gray-500">
+              Create at least one entity type first, then connect them.
+            </p>
+          ) : (
+            <>
+              <div className="grid gap-3 sm:grid-cols-2">
+                <div className="space-y-1.5">
+                  <Label>From (source)</Label>
+                  <Select value={sourceId} onValueChange={setSourceId}>
+                    <SelectTrigger>
+                      <SelectValue placeholder="Pick a type" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {types.map((t) => (
+                        <SelectItem key={String(t.id)} value={String(t.id)}>
+                          {t.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
+                <div className="space-y-1.5">
+                  <Label>To (target)</Label>
+                  <Select value={targetId} onValueChange={setTargetId}>
+                    <SelectTrigger>
+                      <SelectValue placeholder="Pick a type" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {types.map((t) => (
+                        <SelectItem key={String(t.id)} value={String(t.id)}>
+                          {t.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
+              </div>
+
+              <div className="space-y-1.5">
+                <Label htmlFor="rel-key">Name (optional)</Label>
+                <Input
+                  id="rel-key"
+                  value={keyOverride}
+                  onChange={(e) => setKeyOverride(e.target.value)}
+                  placeholder={effectiveKey || 'auto-generated from the two types'}
+                />
+                <p className="text-xs text-gray-500">
+                  Stable identifier for this edge. Defaults to{' '}
+                  <span className="font-mono">{effectiveKey || '—'}</span>.
+                </p>
+              </div>
+            </>
+          )}
+        </CardContent>
+      </Card>
+
+      <div className="flex justify-end">
+        <Button
+          type="submit"
+          disabled={saving || types.length === 0}
+          className={classNames?.submit}
+        >
+          {saving ? 'Connecting…' : 'Define relationship'}
+        </Button>
+      </div>
+    </form>
+  )
+}

package/src/components/schema/SchemaTypeBuilder.tsx

@@ -18,21 +18,33 @@ import { notify as defaultNotify } from '../toast'
 import { cn } from '../../lib/utils'
 import {
   type DataType,
-  type DraftAttribute,
+  type EditableDraft,
+  type ExistingAttribute,
   type AttributePayload,
+  type SchemaId,
   DATA_TYPES,
   blankAttribute,
   toKey,
   draftToAttributePayloads,
+  attributeToDraft,
+  diffAttributes,
 } from './schema-builder-core'
 
 /** The type the backend echoes back after creation (only `id` is required). */
 export interface CreatedType {
-  id: number
+  id: SchemaId
   key: string
   label: string
 }
 
+/** A persisted type loaded into the builder for editing. */
+export interface ExistingType {
+  id: SchemaId
+  key: string
+  label: string
+  attributes: ExistingAttribute[]
+}
+
 /** A minimal notifier surface; defaults to @startsimpli/ui's toast notify. */
 export interface SchemaTypeBuilderNotifier {
   success?: (message: string) => void
@@ -49,41 +61,73 @@ export interface SchemaTypeBuilderClassNames {
 
 export interface SchemaTypeBuilderProps {
   /** Persist the entity type. Must resolve to at least its server-assigned id. */
-  createType: (input: { key: string; label: string }) => Promise<{ id: number }>
-  /** Persist one attribute against the just-created type. */
+  createType: (input: { key: string; label: string }) => Promise<{ id: SchemaId }>
+  /** Persist one attribute against a type. */
   createAttribute: (input: AttributePayload) => Promise<unknown>
-  /** Fired after the type and all its attributes are created (navigate / refetch here). */
+  /** Fired after the type + its attributes are persisted (create OR save). Navigate / refetch here. */
   onCreated?: (created: CreatedType) => void
+
+  // ---- edit mode (optional): pass an existing type to load + edit it ----
+  /** When present, the builder opens in edit mode pre-filled from this type. */
+  existingType?: ExistingType
+  /** Rename a type's label (key is immutable). Required for label edits. */
+  updateType?: (id: SchemaId, input: { label: string }) => Promise<unknown>
+  /** Patch an existing attribute. Required for field edits in edit mode. */
+  updateAttribute?: (
+    id: SchemaId,
+    input: Omit<AttributePayload, 'entityType'>,
+  ) => Promise<unknown>
+  /** Delete an existing attribute. Required to remove fields in edit mode. */
+  deleteAttribute?: (id: SchemaId) => Promise<unknown>
+  /** Delete the whole type. When provided in edit mode, a delete control is shown. */
+  deleteType?: (id: SchemaId) => Promise<unknown>
+  /** Fired after the type is deleted (navigate away / refetch here). */
+  onDeleted?: (type: ExistingType) => void
+
   /** Inject a notifier; defaults to the shared @startsimpli/ui notify. */
   notify?: SchemaTypeBuilderNotifier
-  /** Override the submit label (default "Create type"). */
+  /** Override the create-mode submit label (default "Create type"). */
   submitLabel?: string
   classNames?: SchemaTypeBuilderClassNames
 }
 
+function initialDrafts(existingType?: ExistingType): EditableDraft[] {
+  if (existingType && existingType.attributes.length) {
+    return existingType.attributes.map(attributeToDraft)
+  }
+  return [blankAttribute()]
+}
+
 /**
  * No-code entity-type builder, promoted from frontend-starter (rule #9). The
- * persistence layer is injected via `createType`/`createAttribute` props so the
- * component carries no API client, router, or query-cache coupling — the
- * consuming app wires those in a thin wrapper and handles post-create
- * navigation/refetch in `onCreated`.
+ * persistence layer is injected via callback props so the component carries no
+ * API client, router, or query-cache coupling. Pass `existingType` (+ the
+ * update/delete callbacks) to open it in edit mode; otherwise it creates.
  */
 export function SchemaTypeBuilder({
   createType,
   createAttribute,
   onCreated,
+  existingType,
+  updateType,
+  updateAttribute,
+  deleteAttribute,
+  deleteType,
+  onDeleted,
   notify = defaultNotify,
   submitLabel = 'Create type',
   classNames,
 }: SchemaTypeBuilderProps) {
-  const [label, setLabel] = useState('')
+  const editing = !!existingType
+  const [label, setLabel] = useState(existingType?.label ?? '')
   const [keyOverride, setKeyOverride] = useState('')
-  const [attributes, setAttributes] = useState<DraftAttribute[]>([blankAttribute()])
+  const [attributes, setAttributes] = useState<EditableDraft[]>(() => initialDrafts(existingType))
   const [saving, setSaving] = useState(false)
+  const [confirmingDelete, setConfirmingDelete] = useState(false)
 
-  const effectiveKey = keyOverride.trim() || toKey(label)
+  const effectiveKey = editing ? existingType!.key : keyOverride.trim() || toKey(label)
 
-  function updateAttr(index: number, patch: Partial<DraftAttribute>) {
+  function updateAttr(index: number, patch: Partial<EditableDraft>) {
     setAttributes((prev) => prev.map((a, i) => (i === index ? { ...a, ...patch } : a)))
   }
 
@@ -95,6 +139,32 @@ export function SchemaTypeBuilder({
     setAttributes((prev) => prev.filter((_, i) => i !== index))
   }
 
+  async function persistEdit() {
+    const type = existingType!
+    if (updateType && label.trim() !== type.label) {
+      await updateType(type.id, { label: label.trim() })
+    }
+    const { creates, updates, deletes } = diffAttributes(type.id, type.attributes, attributes)
+    for (const payload of creates) await createAttribute(payload)
+    for (const u of updates) {
+      const { id, ...rest } = u
+      if (updateAttribute) await updateAttribute(id, rest)
+    }
+    for (const id of deletes) {
+      if (deleteAttribute) await deleteAttribute(id)
+    }
+  }
+
+  async function persistCreate() {
+    const type = await createType({ key: effectiveKey, label: label.trim() })
+    // Create each declared attribute, in order; blank rows + config are handled
+    // by the pure helper. (New attributes carry no id in edit mode either.)
+    for (const payload of draftToAttributePayloads(type.id, attributes)) {
+      await createAttribute(payload)
+    }
+    return type.id
+  }
+
   async function handleSubmit(e: React.FormEvent) {
     e.preventDefault()
     if (!label.trim() || !effectiveKey) {
@@ -103,20 +173,34 @@ export function SchemaTypeBuilder({
     }
     setSaving(true)
     try {
-      const type = await createType({ key: effectiveKey, label: label.trim() })
-
-      // Create each declared attribute, in order; the backend attaches them to
-      // the type by id. Blank rows + enum config are handled by the pure helper.
-      for (const payload of draftToAttributePayloads(type.id, attributes)) {
-        await createAttribute(payload)
+      if (editing) {
+        await persistEdit()
+        notify.success?.(`Saved "${label.trim()}".`)
+        onCreated?.({ id: existingType!.id, key: effectiveKey, label: label.trim() })
+      } else {
+        const id = await persistCreate()
+        notify.success?.(`Created "${label.trim()}".`)
+        onCreated?.({ id, key: effectiveKey, label: label.trim() })
       }
+    } catch (err) {
+      notify.error?.(err instanceof Error ? err.message : 'Could not save the type.')
+    } finally {
+      setSaving(false)
+    }
+  }
 
-      notify.success?.(`Created "${label.trim()}".`)
-      onCreated?.({ id: type.id, key: effectiveKey, label: label.trim() })
+  async function handleDelete() {
+    if (!existingType || !deleteType) return
+    setSaving(true)
+    try {
+      await deleteType(existingType.id)
+      notify.success?.(`Deleted "${existingType.label}".`)
+      onDeleted?.(existingType)
     } catch (err) {
-      notify.error?.(err instanceof Error ? err.message : 'Could not create the type.')
+      notify.error?.(err instanceof Error ? err.message : 'Could not delete the type.')
     } finally {
       setSaving(false)
+      setConfirmingDelete(false)
     }
   }
 
@@ -137,16 +221,23 @@ export function SchemaTypeBuilder({
             />
           </div>
           <div className="space-y-1.5">
-            <Label htmlFor="type-key">Key (optional)</Label>
+            <Label htmlFor="type-key">Key{editing ? '' : ' (optional)'}</Label>
             <Input
               id="type-key"
-              value={keyOverride}
+              value={editing ? existingType!.key : keyOverride}
               onChange={(e) => setKeyOverride(e.target.value)}
+              disabled={editing}
               placeholder={toKey(label) || 'auto-generated from the name'}
             />
             <p className="text-xs text-gray-500">
-              Stable identifier used in URLs and the API. Defaults to{' '}
-              <span className="font-mono">{effectiveKey || '—'}</span>.
+              {editing ? (
+                <>The key is fixed once a type exists.</>
+              ) : (
+                <>
+                  Stable identifier used in URLs and the API. Defaults to{' '}
+                  <span className="font-mono">{effectiveKey || '—'}</span>.
+                </>
+              )}
             </p>
           </div>
         </CardContent>
@@ -159,7 +250,7 @@ export function SchemaTypeBuilder({
         <CardContent className="space-y-4">
           {attributes.map((attr, i) => (
             <div
-              key={i}
+              key={attr.id ?? `new-${i}`}
               className={cn(
                 'grid items-end gap-3 sm:grid-cols-[1fr_180px_auto_auto]',
                 classNames?.fieldRow,
@@ -209,7 +300,7 @@ export function SchemaTypeBuilder({
                 size="icon"
                 onClick={() => removeAttr(i)}
                 aria-label="Remove field"
-                disabled={attributes.length === 1}
+                disabled={attributes.length === 1 && !editing}
               >
                 <Trash2 className="h-4 w-4" />
               </Button>
@@ -275,9 +366,53 @@ export function SchemaTypeBuilder({
         </CardContent>
       </Card>
 
-      <div className="flex justify-end">
+      <div className="flex items-center justify-between gap-3">
+        <div>
+          {editing && deleteType && (
+            confirmingDelete ? (
+              <div className="flex items-center gap-2">
+                <span className="text-sm text-gray-600">Delete this type and all its fields?</span>
+                <Button
+                  type="button"
+                  variant="destructive"
+                  size="sm"
+                  onClick={handleDelete}
+                  disabled={saving}
+                >
+                  Delete
+                </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => setConfirmingDelete(false)}
+                  disabled={saving}
+                >
+                  Cancel
+                </Button>
+              </div>
+            ) : (
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => setConfirmingDelete(true)}
+                disabled={saving}
+              >
+                <Trash2 className="mr-2 h-4 w-4" />
+                Delete type
+              </Button>
+            )
+          )}
+        </div>
+
         <Button type="submit" disabled={saving} className={classNames?.submit}>
-          {saving ? 'Creating…' : submitLabel}
+          {editing
+            ? saving
+              ? 'Saving…'
+              : 'Save changes'
+            : saving
+              ? 'Creating…'
+              : submitLabel}
         </Button>
       </div>
     </form>

package/src/components/schema/__tests__/RelationshipBuilder.test.tsx

@@ -0,0 +1,34 @@
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { RelationshipBuilder } from '../RelationshipBuilder'
+
+const types = [
+  { id: 'uuid-artist', key: 'artist', label: 'Artist' },
+  { id: 'uuid-release', key: 'release', label: 'Release' },
+]
+
+describe('RelationshipBuilder', () => {
+  it('renders source + target pickers and a define button', () => {
+    render(<RelationshipBuilder types={types} createRelationship={jest.fn()} />)
+    expect(screen.getByText('From (source)')).toBeInTheDocument()
+    expect(screen.getByText('To (target)')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /define relationship/i })).toBeInTheDocument()
+  })
+
+  it('warns and does not persist when no endpoints are chosen', async () => {
+    const createRelationship = jest.fn().mockResolvedValue({})
+    const notify = { success: jest.fn(), error: jest.fn() }
+    render(
+      <RelationshipBuilder types={types} createRelationship={createRelationship} notify={notify} />,
+    )
+    await userEvent.setup().click(screen.getByRole('button', { name: /define relationship/i }))
+    expect(createRelationship).not.toHaveBeenCalled()
+    expect(notify.error).toHaveBeenCalled()
+  })
+
+  it('prompts to create types first when none exist (submit disabled)', () => {
+    render(<RelationshipBuilder types={[]} createRelationship={jest.fn()} />)
+    expect(screen.getByText(/create at least one entity type first/i)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /define relationship/i })).toBeDisabled()
+  })
+})

package/src/components/schema/__tests__/SchemaTypeBuilder.test.tsx

@@ -57,3 +57,66 @@ describe('SchemaTypeBuilder', () => {
     expect(notify.error).toHaveBeenCalled()
   })
 })
+
+describe('SchemaTypeBuilder (edit mode)', () => {
+  const existingType = {
+    id: 'uuid-1',
+    key: 'matter',
+    label: 'Matter',
+    attributes: [
+      { id: 'a1', name: 'title', dataType: 'text' as const, required: true, config: {} },
+      { id: 'a2', name: 'stale', dataType: 'text' as const, required: false, config: {} },
+    ],
+  }
+
+  function setupEdit() {
+    const fns = {
+      createType: jest.fn(),
+      createAttribute: jest.fn().mockResolvedValue({}),
+      updateType: jest.fn().mockResolvedValue({}),
+      updateAttribute: jest.fn().mockResolvedValue({}),
+      deleteAttribute: jest.fn().mockResolvedValue({}),
+      deleteType: jest.fn().mockResolvedValue({}),
+      onCreated: jest.fn(),
+      onDeleted: jest.fn(),
+    }
+    const notify = { success: jest.fn(), error: jest.fn() }
+    render(<SchemaTypeBuilder {...fns} existingType={existingType} notify={notify} />)
+    return { ...fns, notify, user: userEvent.setup() }
+  }
+
+  it('pre-fills the label + a locked key + the existing field names', () => {
+    setupEdit()
+    expect(screen.getByLabelText('Name')).toHaveValue('Matter')
+    expect(screen.getByLabelText('Key')).toBeDisabled()
+    expect(screen.getByLabelText('Key')).toHaveValue('matter')
+    const fieldNames = screen.getAllByLabelText('Field name').map((el) => (el as HTMLInputElement).value)
+    expect(fieldNames).toEqual(['title', 'stale'])
+    expect(screen.getByRole('button', { name: /save changes/i })).toBeInTheDocument()
+  })
+
+  it('saves a renamed label + removed field as updateType + deleteAttribute (no create/update of unchanged)', async () => {
+    const { updateType, updateAttribute, createAttribute, deleteAttribute, onCreated, user } = setupEdit()
+
+    await user.clear(screen.getByLabelText('Name'))
+    await user.type(screen.getByLabelText('Name'), 'Legal Matter')
+    // remove the second field ("stale")
+    await user.click(screen.getAllByRole('button', { name: /remove field/i })[1])
+    await user.click(screen.getByRole('button', { name: /save changes/i }))
+
+    await waitFor(() => expect(updateType).toHaveBeenCalledWith('uuid-1', { label: 'Legal Matter' }))
+    expect(deleteAttribute).toHaveBeenCalledWith('a2')
+    expect(createAttribute).not.toHaveBeenCalled()
+    expect(updateAttribute).not.toHaveBeenCalled() // 'title' is unchanged
+    expect(onCreated).toHaveBeenCalledWith({ id: 'uuid-1', key: 'matter', label: 'Legal Matter' })
+  })
+
+  it('deletes the type only after the inline confirm', async () => {
+    const { deleteType, onDeleted, user } = setupEdit()
+    await user.click(screen.getByRole('button', { name: /delete type/i }))
+    expect(deleteType).not.toHaveBeenCalled() // confirm step shown, not yet deleted
+    await user.click(screen.getByRole('button', { name: /^delete$/i }))
+    await waitFor(() => expect(deleteType).toHaveBeenCalledWith('uuid-1'))
+    expect(onDeleted).toHaveBeenCalledWith(existingType)
+  })
+})

package/src/components/schema/__tests__/schema-builder-core.test.ts

@@ -2,8 +2,13 @@ import {
   toKey,
   blankAttribute,
   draftToAttributePayloads,
+  attributeToDraft,
+  diffAttributes,
+  suggestRelationshipKey,
   DATA_TYPES,
   type DraftAttribute,
+  type ExistingAttribute,
+  type EditableDraft,
 } from '../schema-builder-core'
 
 describe('toKey', () => {
@@ -110,6 +115,99 @@ describe('draftToAttributePayloads', () => {
   })
 })
 
+describe('attributeToDraft (hydrate a saved attribute into an editable row)', () => {
+  const existing = (over: Partial<ExistingAttribute> = {}): ExistingAttribute => ({
+    id: 1,
+    name: 'status',
+    dataType: 'text',
+    required: false,
+    config: {},
+    ...over,
+  })
+
+  it('round-trips an enum: config.choices -> comma-joined string', () => {
+    const d = attributeToDraft(existing({ dataType: 'enum', config: { choices: ['Open', 'Done'] } }))
+    expect(d).toMatchObject({ id: 1, dataType: 'enum', choices: 'Open, Done', min: '', max: '', regex: '' })
+  })
+
+  it('round-trips numeric bounds and a regex into their string inputs', () => {
+    expect(attributeToDraft(existing({ dataType: 'integer', config: { min: 1, max: 10 } })))
+      .toMatchObject({ min: '1', max: '10', choices: '', regex: '' })
+    expect(attributeToDraft(existing({ dataType: 'text', config: { regex: '\\d+' } })))
+      .toMatchObject({ regex: '\\d+', min: '', max: '' })
+  })
+
+  it('is the inverse of draftToAttributePayloads for the config payload', () => {
+    const e = existing({ id: 7, name: 'qty', dataType: 'number', required: true, config: { min: 0, max: 5 } })
+    const draft = attributeToDraft(e)
+    const [payload] = draftToAttributePayloads(99, [draft])
+    expect(payload).toMatchObject({ name: 'qty', dataType: 'number', required: true, config: { min: 0, max: 5 } })
+  })
+})
+
+describe('diffAttributes (create/update/delete reconciliation)', () => {
+  const existing = (over: Partial<ExistingAttribute> = {}): ExistingAttribute => ({
+    id: 1, name: 'title', dataType: 'text', required: false, config: {}, ...over,
+  })
+  const draftOf = (e: ExistingAttribute): EditableDraft => attributeToDraft(e)
+  const newRow = (over: Partial<EditableDraft> = {}): EditableDraft => ({
+    ...blankAttribute(), name: 'extra', ...over,
+  })
+
+  it('flags a brand-new (id-less) row as a create', () => {
+    const orig = [existing()]
+    const { creates, updates, deletes } = diffAttributes(3, orig, [draftOf(orig[0]), newRow({ name: 'note' })])
+    expect(creates).toHaveLength(1)
+    expect(creates[0]).toMatchObject({ entityType: 3, name: 'note' })
+    expect(updates).toEqual([])
+    expect(deletes).toEqual([])
+  })
+
+  it('flags a changed existing row as an update (carrying its id)', () => {
+    const orig = [existing({ id: 5, name: 'title', dataType: 'text' })]
+    const edited = { ...draftOf(orig[0]), name: 'headline', dataType: 'longtext' as const }
+    const { creates, updates, deletes } = diffAttributes(3, orig, [edited])
+    expect(creates).toEqual([])
+    expect(updates).toEqual([{ id: 5, name: 'headline', dataType: 'longtext', required: false, config: {} }])
+    expect(deletes).toEqual([])
+  })
+
+  it('does not update an unchanged existing row', () => {
+    const orig = [existing({ id: 5, dataType: 'enum', config: { choices: ['a', 'b'] } })]
+    const { creates, updates, deletes } = diffAttributes(3, orig, [draftOf(orig[0])])
+    expect(creates).toEqual([])
+    expect(updates).toEqual([])
+    expect(deletes).toEqual([])
+  })
+
+  it('flags an original whose row was removed as a delete', () => {
+    const orig = [existing({ id: 5, name: 'title' }), existing({ id: 6, name: 'gone' })]
+    const { creates, updates, deletes } = diffAttributes(3, orig, [draftOf(orig[0])])
+    expect(creates).toEqual([])
+    expect(updates).toEqual([])
+    expect(deletes).toEqual([6])
+  })
+
+  it('treats a blanked-name existing row as a delete (not an update)', () => {
+    const orig = [existing({ id: 9, name: 'title' })]
+    const { updates, deletes } = diffAttributes(3, orig, [{ ...draftOf(orig[0]), name: '   ' }])
+    expect(updates).toEqual([])
+    expect(deletes).toEqual([9])
+  })
+})
+
+describe('suggestRelationshipKey', () => {
+  it('joins source + target into a slugified edge key', () => {
+    expect(suggestRelationshipKey('artist', 'release')).toBe('artist_release')
+    expect(suggestRelationshipKey('Purchase Order', 'Line Item')).toBe('purchase_order_line_item')
+  })
+
+  it('is empty until both ends are chosen', () => {
+    expect(suggestRelationshipKey('', 'release')).toBe('')
+    expect(suggestRelationshipKey('artist', '')).toBe('')
+  })
+})
+
 describe('DATA_TYPES', () => {
   it('exposes the eight backend data types as {value,label} options', () => {
     expect(DATA_TYPES.map((d) => d.value)).toEqual([

package/src/components/schema/index.ts

@@ -4,11 +4,31 @@ export type {
   SchemaTypeBuilderClassNames,
   SchemaTypeBuilderNotifier,
   CreatedType,
+  ExistingType,
 } from './SchemaTypeBuilder'
+export { RelationshipBuilder } from './RelationshipBuilder'
+export type {
+  RelationshipBuilderProps,
+  RelationshipBuilderClassNames,
+  RelationshipTypeOption,
+} from './RelationshipBuilder'
 export {
   DATA_TYPES,
   blankAttribute,
   toKey,
+  suggestRelationshipKey,
+  draftToPayload,
   draftToAttributePayloads,
+  attributeToDraft,
+  diffAttributes,
+} from './schema-builder-core'
+export type {
+  DataType,
+  DraftAttribute,
+  EditableDraft,
+  ExistingAttribute,
+  AttributePayload,
+  AttributeUpdate,
+  AttributeEdits,
+  SchemaId,
 } from './schema-builder-core'
-export type { DataType, DraftAttribute, AttributePayload } from './schema-builder-core'

package/src/components/schema/schema-builder-core.ts

@@ -58,51 +58,158 @@ export function toKey(label: string): string {
     .replace(/^_+|_+$/g, '')
 }
 
+/** Suggest a relationship (edge) key from its endpoint type names. Empty until
+ * both ends are chosen. */
+export function suggestRelationshipKey(source: string, target: string): string {
+  if (!source.trim() || !target.trim()) return ''
+  return toKey(`${source}_${target}`)
+}
+
+/** Server-assigned ids are UUID strings; numbers are tolerated for tests/legacy. */
+export type SchemaId = string | number
+
 export interface AttributePayload {
-  entityType: number
+  entityType: SchemaId
   name: string
   dataType: DataType
   required: boolean
   config: Record<string, unknown>
 }
 
+/** Build the dataType-scoped config for one draft row. Keys match what the
+ * backend enforces (enum: choices, number/integer: min/max, text/longtext:
+ * regex). Numeric bounds + regex are omitted when blank; an enum always carries
+ * its choices. */
+function buildConfig(attr: DraftAttribute): Record<string, unknown> {
+  const config: Record<string, unknown> = {}
+  if (attr.dataType === 'enum') {
+    config.choices = attr.choices
+      .split(',')
+      .map((c) => c.trim())
+      .filter(Boolean)
+  } else if (attr.dataType === 'number' || attr.dataType === 'integer') {
+    const min = Number(attr.min)
+    const max = Number(attr.max)
+    if (attr.min.trim() !== '' && !Number.isNaN(min)) config.min = min
+    if (attr.max.trim() !== '' && !Number.isNaN(max)) config.max = max
+  } else if (attr.dataType === 'text' || attr.dataType === 'longtext') {
+    if (attr.regex.trim() !== '') config.regex = attr.regex.trim()
+  }
+  return config
+}
+
+/** One draft row → a createAttribute() payload, or null for a blank-name row. */
+export function draftToPayload(
+  entityTypeId: SchemaId,
+  attr: DraftAttribute,
+): AttributePayload | null {
+  const name = attr.name.trim()
+  if (!name) return null
+  return { entityType: entityTypeId, name, dataType: attr.dataType, required: attr.required, config: buildConfig(attr) }
+}
+
 /**
  * Turn the draft field rows into createAttribute() inputs for a just-created
- * type: drop blank-name rows, trim names, and build enum `config.choices` from
- * the comma-separated input (trimmed, empties removed).
+ * type: drop blank-name rows, trim names, and build the dataType-scoped config.
  */
 export function draftToAttributePayloads(
-  entityTypeId: number,
+  entityTypeId: SchemaId,
   drafts: DraftAttribute[],
 ): AttributePayload[] {
   const out: AttributePayload[] = []
   for (const attr of drafts) {
-    const name = attr.name.trim()
-    if (!name) continue
-    // Config keys are scoped to the dataType + match what the backend enforces
-    // (enum: choices, number/integer: min/max, text/longtext: regex). Numeric
-    // bounds + regex are omitted when blank; an enum always carries its choices.
-    const config: Record<string, unknown> = {}
-    if (attr.dataType === 'enum') {
-      config.choices = attr.choices
-        .split(',')
-        .map((c) => c.trim())
-        .filter(Boolean)
-    } else if (attr.dataType === 'number' || attr.dataType === 'integer') {
-      const min = Number(attr.min)
-      const max = Number(attr.max)
-      if (attr.min.trim() !== '' && !Number.isNaN(min)) config.min = min
-      if (attr.max.trim() !== '' && !Number.isNaN(max)) config.max = max
-    } else if (attr.dataType === 'text' || attr.dataType === 'longtext') {
-      if (attr.regex.trim() !== '') config.regex = attr.regex.trim()
-    }
-    out.push({
-      entityType: entityTypeId,
-      name,
-      dataType: attr.dataType,
-      required: attr.required,
-      config,
-    })
+    const payload = draftToPayload(entityTypeId, attr)
+    if (payload) out.push(payload)
   }
   return out
 }
+
+// ---- edit mode (S4): hydrate existing attributes + diff against drafts ----
+
+/** A persisted attribute as the schema API returns it (camelCase via the client). */
+export interface ExistingAttribute {
+  id: SchemaId
+  name: string
+  dataType: DataType
+  required: boolean
+  config: Record<string, unknown>
+}
+
+/** A draft row that may correspond to a persisted attribute (carries its id). */
+export interface EditableDraft extends DraftAttribute {
+  id?: SchemaId
+}
+
+/** Inverse of draftToPayload: hydrate an editable row from a saved attribute,
+ * back-filling the dataType-scoped config into its string inputs. */
+export function attributeToDraft(attr: ExistingAttribute): EditableDraft {
+  const cfg = attr.config || {}
+  const choices = Array.isArray(cfg.choices) ? (cfg.choices as unknown[]).join(', ') : ''
+  const min = cfg.min !== undefined && cfg.min !== null ? String(cfg.min) : ''
+  const max = cfg.max !== undefined && cfg.max !== null ? String(cfg.max) : ''
+  const regex = typeof cfg.regex === 'string' ? cfg.regex : ''
+  return {
+    id: attr.id,
+    name: attr.name,
+    dataType: attr.dataType,
+    required: attr.required,
+    choices,
+    min,
+    max,
+    regex,
+  }
+}
+
+/** A single attribute update (the id + the writable payload fields). */
+export type AttributeUpdate = { id: SchemaId } & Omit<AttributePayload, 'entityType'>
+
+export interface AttributeEdits {
+  creates: AttributePayload[]
+  updates: AttributeUpdate[]
+  deletes: SchemaId[]
+}
+
+function sameConfig(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  const ak = Object.keys(a).sort()
+  const bk = Object.keys(b).sort()
+  if (ak.length !== bk.length || ak.some((k, i) => k !== bk[i])) return false
+  return ak.every((k) => JSON.stringify(a[k]) === JSON.stringify(b[k]))
+}
+
+/**
+ * Reconcile the edited draft rows against the type's persisted attributes into
+ * the API calls needed: id-less rows -> creates, changed existing rows ->
+ * updates, and originals whose row was removed (or blanked) -> deletes.
+ */
+export function diffAttributes(
+  entityTypeId: SchemaId,
+  originals: ExistingAttribute[],
+  drafts: EditableDraft[],
+): AttributeEdits {
+  const creates: AttributePayload[] = []
+  const updates: AttributeUpdate[] = []
+  const keptIds = new Set<SchemaId>()
+
+  for (const draft of drafts) {
+    const payload = draftToPayload(entityTypeId, draft)
+    if (!payload) continue // blank-name row: a new blank is ignored; a blanked existing falls through to delete
+    if (draft.id == null) {
+      creates.push(payload)
+      continue
+    }
+    keptIds.add(draft.id)
+    const orig = originals.find((o) => o.id === draft.id)
+    const changed =
+      !orig ||
+      orig.name !== payload.name ||
+      orig.dataType !== payload.dataType ||
+      orig.required !== payload.required ||
+      !sameConfig(orig.config || {}, payload.config)
+    if (changed) {
+      updates.push({ id: draft.id, name: payload.name, dataType: payload.dataType, required: payload.required, config: payload.config })
+    }
+  }
+
+  const deletes = originals.filter((o) => !keptIds.has(o.id)).map((o) => o.id)
+  return { creates, updates, deletes }
+}