@fayz-ai/saas 0.8.0 → 0.8.2

package/src/components/shared/ContactPicker.tsx

@@ -0,0 +1,394 @@
+import React, { useState, useEffect, useMemo, useRef } from 'react'
+import { X } from 'lucide-react'
+import { SearchCombobox, cn, toast, type ComboboxOption } from '@fayz-ai/ui'
+import { useTranslation } from '@fayz-ai/core'
+import { createArchetypeLookup, type EntityLookup } from '../../archetype-lookup'
+import { createPerson } from './create-person'
+import { PersonLink } from './PersonLink'
+
+// ---------------------------------------------------------------------------
+// ContactPicker — "find the person, or create them" as ONE component.
+//
+// The agenda invented this flow inline (search a client → no match → quick-add
+// with name/phone/email → keep going without leaving the modal). It's the same
+// need anywhere a plugin starts something FOR someone: a booking, a
+// conversation, an invoice. This is that flow, extracted, so the behaviour and
+// the rows written stay identical across surfaces (see `createPerson`).
+//
+// Three states, one component:
+//   • empty     → SearchCombobox over the person lookup, with "+ Create <text>"
+//   • selected  → a compact chip (PersonLink + phone) with an optional clear
+//   • creating  → inline name / phone / email form → `createPerson` → selected
+//
+// ONE behaviour, two skins (`variant`). What used to differ between hosts was
+// the FLOW — the agenda hid its search behind a collapsed "+ Add client" and
+// rendered its own quick-create, conversations rendered its own phone field —
+// and that is what made the same feature read as two. Those are gone: search,
+// chip, inline create, label and handle capture all live here now, and the host
+// passes configuration, not layout. `variant` only picks how much chrome the
+// input wears, so it can sit in a form-shaped modal or in a dense icon row
+// without the surrounding layout looking broken. Always open in both: the
+// contact is the primary input everywhere this is mounted.
+//
+// Uncontrolled-friendly: pass `value`/`onChange` and the parent owns the id.
+// ---------------------------------------------------------------------------
+
+export interface ContactPickerValue {
+  /** Person id — undefined while the user has only typed a name. */
+  id?: string
+  name: string
+  phone?: string
+  email?: string
+}
+
+export interface ContactPickerProps {
+  value: ContactPickerValue | null
+  onChange: (value: ContactPickerValue | null) => void
+  /**
+   * `people.kind` for records created here (e.g. 'client', 'lead', 'contact').
+   * Also narrows the default lookup, so a vertical only searches its own people.
+   */
+  kind?: string
+  /** Per-vertical extension table linked by `person_id` — skipped when absent from the pool. */
+  extensionTable?: string
+  /** Search source. Defaults to the `person` archetype lookup narrowed by `kind`. */
+  lookup?: EntityLookup
+  /**
+   * Allow committing a typed name with NO person record (`{ name }` and no id).
+   * Off by default: the point of the picker is to end up with a real contact.
+   * Conversations turns it on so an ad-hoc handle can still start a thread.
+   */
+  allowFreeText?: boolean
+  /** Hide the clear button (agenda locks the client on a paid booking). */
+  clearable?: boolean
+  disabled?: boolean
+  autoFocus?: boolean
+  placeholder?: string
+  /**
+   * How much chrome the field carries. The BEHAVIOUR — search, chip, inline
+   * create, handle capture — is identical either way; only the input's skin
+   * changes, so it can sit in whichever layout grammar the host already uses.
+   *
+   *  • 'field' (default) — label above + bordered input. For form-shaped modals
+   *    (the conversations composer), where every control is a labelled field.
+   *  • 'inline' — no label, borderless input that underlines on focus. For the
+   *    appointment modal's icon rows, where a bordered box next to "Scheduled"
+   *    and "Add notes" is the thing that looks out of place.
+   */
+  variant?: 'field' | 'inline'
+  /** Field label, rendered BY the component so every host gets the same one. Ignored when `variant='inline'`. */
+  label?: string
+  /**
+   * Right-hand detail on the selected chip. Defaults to the person's phone; a
+   * host that cares about a different datum (the conversations composer shows
+   * the handle for the ACTIVE channel) passes its own.
+   */
+  secondaryText?: string
+  /**
+   * Optional second datum captured alongside the contact — the address to reach
+   * them at in this context (a channel handle, a delivery phone…). Lives HERE,
+   * not in the host, because it is contact data and hosts were rendering their
+   * own field around the picker, which is exactly what made the same flow look
+   * like two different features.
+   *
+   * `derived` is what we already know from the picked person: when set it rides
+   * on the chip and no field is offered. Otherwise the picker shows a discreet
+   * "+ Add {label}" that expands into the input.
+   */
+  handleField?: {
+    /** Human name of the datum, interpolated into "+ Add {label}". */
+    label: string
+    /** Known from the contact — suppresses the field entirely. */
+    derived?: string
+    value: string
+    onChange: (value: string) => void
+    /** Label above the input once open. Defaults to `label`. */
+    fieldLabel?: string
+    placeholder?: string
+  }
+  /**
+   * Copy for the "+ Create …" row. Defaults to the shared "New contact"; a
+   * plugin whose vertical calls them something else (the agenda says "client")
+   * passes its own label so the wording doesn't regress into generic SDK copy.
+   */
+  createLabel?: string
+  /**
+   * Fires when the inline create form opens/closes. The create form owns phone
+   * and email while it is open, so a host that ALSO renders a phone/handle field
+   * (the conversations composer does) hides its own to avoid asking twice.
+   */
+  onCreatingChange?: (creating: boolean) => void
+  className?: string
+  /** Extra hint under the input while a name is typed but nothing is selected. */
+  hint?: React.ReactNode
+}
+
+export function ContactPicker({
+  value,
+  onChange,
+  kind,
+  extensionTable,
+  lookup,
+  allowFreeText = false,
+  clearable = true,
+  disabled,
+  autoFocus,
+  placeholder,
+  variant = 'field',
+  label,
+  secondaryText,
+  handleField,
+  createLabel,
+  onCreatingChange,
+  className,
+  hint,
+}: ContactPickerProps) {
+  const t = useTranslation()
+  const resolvedLookup = useMemo(
+    () => lookup ?? createArchetypeLookup({ archetype: 'person', kind }),
+    [lookup, kind],
+  )
+
+  const [search, setSearch] = useState(value?.id ? value.name : (value?.name ?? ''))
+  const [options, setOptions] = useState<ComboboxOption[]>([])
+  const [searching, setSearching] = useState(false)
+
+  const [creating, setCreatingState] = useState(false)
+  const creatingChanged = useRef(onCreatingChange)
+  creatingChanged.current = onCreatingChange
+  const setCreating = (next: boolean) => {
+    setCreatingState(next)
+    creatingChanged.current?.(next)
+  }
+  const [handleOpen, setHandleOpen] = useState(false)
+  const [newName, setNewName] = useState('')
+  const [newPhone, setNewPhone] = useState('')
+  const [newEmail, setNewEmail] = useState('')
+  const [saving, setSaving] = useState(false)
+
+  // Keep the visible text in sync with the parent — but ONLY on an id
+  // transition. Parents build `value` as a fresh object literal every render, so
+  // reacting to the object itself would re-run each keystroke and wipe the text
+  // the user is typing (there is no id yet while they type).
+  const selectedId = value?.id
+  const selectedName = value?.id ? value.name : undefined
+  const lastSelectedId = useRef(selectedId)
+  useEffect(() => {
+    if (selectedId === lastSelectedId.current) return
+    lastSelectedId.current = selectedId
+    if (selectedId) {
+      setSearch(selectedName ?? '')
+      setCreating(false)
+    } else {
+      // Parent dropped the selection (form reset, "change contact", …).
+      setSearch('')
+    }
+  }, [selectedId, selectedName])
+
+  // Debounced search — skipped once a person is selected.
+  useEffect(() => {
+    if (value?.id || creating || search.trim().length < 1) {
+      setOptions([])
+      setSearching(false)
+      return
+    }
+    setSearching(true)
+    const timer = setTimeout(async () => {
+      try {
+        const results = await resolvedLookup.search(search)
+        setOptions(results.map((r) => ({ id: r.id, label: r.label, subtitle: r.subtitle, data: r.data })))
+      } catch {
+        setOptions([])
+      }
+      setSearching(false)
+    }, 250)
+    return () => clearTimeout(timer)
+  }, [search, value?.id, creating, resolvedLookup])
+
+  // Free-text mode: a typed name with no match is still a usable value, so the
+  // parent sees every keystroke. Without it the text would be lost on submit.
+  function handleSearchChange(next: string) {
+    setSearch(next)
+    if (value?.id) onChange(null)
+    if (allowFreeText) onChange(next.trim() ? { name: next } : null)
+  }
+
+  function handleSelect(opt: ComboboxOption) {
+    const data = (opt.data ?? {}) as Record<string, unknown>
+    setSearch(opt.label)
+    setOptions([])
+    onChange({
+      id: opt.id,
+      name: opt.label,
+      phone: (data.phone as string) || undefined,
+      email: (data.email as string) || undefined,
+    })
+  }
+
+  function startCreate(prefillName: string) {
+    setCreating(true)
+    setNewName(prefillName)
+    setNewPhone('')
+    setNewEmail('')
+  }
+
+  async function handleCreate() {
+    if (!newName.trim() || saving) return
+    setSaving(true)
+    try {
+      const person = await createPerson({
+        name: newName,
+        phone: newPhone,
+        email: newEmail,
+        kind: kind ?? 'contact',
+        extensionTable,
+      })
+      setSearch(person.name)
+      setCreating(false)
+      onChange(person)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      toast.error(t('contactPicker.createFailed'), { description: message })
+    }
+    setSaving(false)
+  }
+
+  function handleClear() {
+    setSearch('')
+    setOptions([])
+    onChange(null)
+  }
+
+  const inputClass =
+    'w-full rounded-input border border-input bg-card shadow-[inset_0_1px_0_rgb(0_0_0_/0.06)] px-2.5 py-1.5 text-sm focus:outline-none focus:ring-2 focus:ring-ring'
+
+  // Each state renders only its BODY; `frame` below wraps every one of them in
+  // the same label + handle chrome, so the picker looks identical wherever it is
+  // mounted no matter which state it is in.
+  const frame = (body: React.ReactNode) => (
+    <div className={cn('flex flex-col', className)}>
+      {label && variant === 'field' && (
+        <label className="mb-1.5 block text-xs font-medium text-muted-foreground">{label}</label>
+      )}
+      {body}
+      {handleField && !creating && !handleField.derived && (
+        handleOpen || handleField.value ? (
+          <div className="mt-3">
+            <label htmlFor="contact-handle" className="mb-1.5 block text-xs font-medium text-muted-foreground">
+              {handleField.fieldLabel ?? handleField.label}
+            </label>
+            <input
+              id="contact-handle"
+              type="text"
+              value={handleField.value}
+              onChange={(e) => handleField.onChange(e.target.value)}
+              placeholder={handleField.placeholder}
+              className={inputClass}
+              autoFocus={handleOpen}
+            />
+          </div>
+        ) : (
+          <button
+            type="button"
+            onClick={() => setHandleOpen(true)}
+            className="mt-2 self-start text-xs font-medium text-primary hover:underline"
+          >
+            + {t('contactPicker.addField').replace('{label}', handleField.label)}
+          </button>
+        )
+      )}
+    </div>
+  )
+
+  // ---- Selected -----------------------------------------------------------
+  if (value?.id && !creating) {
+    return frame(
+      <div className="flex items-center gap-2 rounded-md bg-muted/30 px-2.5 py-1.5 text-sm">
+        <PersonLink personId={value.id} name={value.name} size="default" className="flex-1 min-w-0" />
+        {(secondaryText ?? value.phone) && (
+          <span className="text-[10px] text-muted-foreground shrink-0">{secondaryText ?? value.phone}</span>
+        )}
+        {clearable && !disabled && (
+          <button
+            type="button"
+            onClick={handleClear}
+            aria-label={t('contactPicker.clear')}
+            className="p-0.5 text-muted-foreground hover:text-destructive shrink-0"
+          >
+            <X className="h-3 w-3" />
+          </button>
+        )}
+      </div>,
+    )
+  }
+
+  // ---- Creating -----------------------------------------------------------
+  if (creating) {
+    return frame(
+      <div className="rounded-input border border-input bg-card shadow-[inset_0_1px_0_rgb(0_0_0_/0.06)] p-2.5 space-y-2">
+        <div className="flex items-center gap-2">
+          <input
+            type="text"
+            value={newName}
+            onChange={(e) => setNewName(e.target.value)}
+            placeholder={t('contactPicker.name')}
+            className={cn(inputClass, 'flex-1 font-medium')}
+            autoFocus
+          />
+          <button
+            type="button"
+            onClick={() => setCreating(false)}
+            aria-label={t('contactPicker.cancel')}
+            className="p-1 text-muted-foreground hover:text-foreground shrink-0"
+          >
+            <X className="h-3.5 w-3.5" />
+          </button>
+        </div>
+        <div className="grid grid-cols-2 gap-2">
+          <input
+            type="tel"
+            value={newPhone}
+            onChange={(e) => setNewPhone(e.target.value)}
+            placeholder={t('contactPicker.phone')}
+            className={inputClass}
+          />
+          <input
+            type="email"
+            value={newEmail}
+            onChange={(e) => setNewEmail(e.target.value)}
+            placeholder={t('contactPicker.emailOptional')}
+            className={inputClass}
+          />
+        </div>
+        <button
+          type="button"
+          disabled={saving || !newName.trim()}
+          onClick={handleCreate}
+          className="w-full rounded-md bg-primary border border-primary px-3 py-1.5 text-xs font-medium text-primary-foreground hover:bg-primary/90 shadow-button-primary active:shadow-button-inset disabled:opacity-40 transition-colors"
+        >
+          {saving ? t('contactPicker.creating') : t('contactPicker.create')}
+        </button>
+      </div>,
+    )
+  }
+
+  // ---- Empty / searching --------------------------------------------------
+  return frame(
+    <div>
+      <SearchCombobox
+        value={search}
+        onChange={handleSearchChange}
+        onSelect={handleSelect}
+        options={options}
+        loading={searching}
+        placeholder={placeholder ?? t('contactPicker.search')}
+        allowCreate
+        createLabel={createLabel ?? t('contactPicker.newContact')}
+        onCreateNew={startCreate}
+        autoFocus={autoFocus}
+        minimal={variant === 'inline'}
+      />
+      {hint && search.trim() && !searching && <div className="mt-1">{hint}</div>}
+    </div>,
+  )
+}

package/src/components/shared/PersonLink.tsx

@@ -12,6 +12,14 @@ const personLookup = createArchetypeLookup({ archetype: 'person' })
 interface PersonLinkProps {
   /** Person UUID — required for fetching details */
   personId?: string | null
+  /**
+   * Where to load the details from. Defaults to the `person` archetype lookup
+   * (the `people` table). Modules whose "person" lives elsewhere pass their own
+   * loader — a shop customer, for instance, is a plg_shop_customers row and the
+   * default lookup would never find it. Without this the popover silently shows
+   * an empty card, which reads as a bug rather than as a wrong data source.
+   */
+  lookup?: { getById: (id: string) => Promise<EntityLookupResult | null> }
   /** Display name (shown as the clickable text) */
   name: string
   /** Optional href to navigate to the person's profile */
@@ -34,7 +42,7 @@ function formatAge(dob: string): string | null {
   } catch { return null }
 }
 
-export function PersonLink({ personId, name, profileHref, tab, size = 'default', className }: PersonLinkProps) {
+export function PersonLink({ personId, name, lookup, profileHref, tab, size = 'default', className }: PersonLinkProps) {
   const [person, setPerson] = useState<EntityLookupResult | null>(null)
   const [loading, setLoading] = useState(false)
   const [fetched, setFetched] = useState(false)
@@ -44,7 +52,7 @@ export function PersonLink({ personId, name, profileHref, tab, size = 'default',
   const fetchPerson = useCallback(() => {
     if (!fetched && personId) {
       setLoading(true)
-      personLookup.getById(personId).then((result) => {
+      ;(lookup ?? personLookup).getById(personId).then((result) => {
         setPerson(result)
         setFetched(true)
         setLoading(false)
@@ -53,7 +61,7 @@ export function PersonLink({ personId, name, profileHref, tab, size = 'default',
         setLoading(false)
       })
     }
-  }, [personId, fetched])
+  }, [personId, fetched, lookup])
 
   const handleOpenChange = useCallback((v: boolean) => {
     setOpen(v)

package/src/components/shared/create-person.ts

@@ -0,0 +1,74 @@
+import { getSupabaseClientOptional } from '@fayz-ai/core'
+import { useOrganizationStore } from '../../org/store'
+
+// ---------------------------------------------------------------------------
+// createPerson — the ONE way a plugin turns "a name someone typed" into a real
+// person record. Extracted from the agenda's inline quick-create so every
+// surface that needs "find the contact, or create it" writes the SAME rows:
+// `public.people` (the archetype base) plus, when the pool ships it, a
+// per-vertical extension table (`clients`, `leads`, …).
+//
+// Pool tolerance is the whole reason this is shared: beauty-style pools have
+// `public.clients`, school/agency pools live off `public.people` alone. A
+// MISSING extension table is not an error (PostgREST reports PGRST205 /
+// "Could not find the table"); any other failure rolls the person back so a
+// half-written contact never survives.
+// ---------------------------------------------------------------------------
+
+export interface CreatePersonInput {
+  name: string
+  phone?: string
+  email?: string
+  /** `people.kind` discriminator for this vertical (e.g. 'client', 'lead'). */
+  kind: string
+  /**
+   * Optional per-vertical extension table linked by `person_id`. Absent in the
+   * pool → silently skipped (see above).
+   */
+  extensionTable?: string
+}
+
+export interface CreatedPerson {
+  id: string
+  name: string
+  phone?: string
+  email?: string
+}
+
+export async function createPerson(input: CreatePersonInput): Promise<CreatedPerson> {
+  const supabase = getSupabaseClientOptional() as any
+  const tenantId = useOrganizationStore.getState().currentOrg?.id
+  if (!supabase) throw new Error('[createPerson] Supabase client not registered.')
+  if (!tenantId) throw new Error('[createPerson] Active tenant not resolved — try again in a moment.')
+
+  const name = input.name.trim()
+  const phone = input.phone?.trim() || null
+  const email = input.email?.trim() || null
+
+  const { data: personRow, error: personError } = await supabase
+    .from('people')
+    .insert({ tenant_id: tenantId, kind: input.kind, name, phone, email })
+    .select('id, name, phone, email')
+    .single()
+  if (personError) throw personError
+
+  if (input.extensionTable) {
+    const { error: extError } = await supabase
+      .from(input.extensionTable)
+      .insert({ person_id: personRow.id, tenant_id: tenantId })
+    const missingExtensionTable =
+      extError?.code === 'PGRST205' || extError?.message?.includes('Could not find the table')
+    if (extError && !missingExtensionTable) {
+      // Roll the person back so the failure leaves nothing behind.
+      await supabase.from('people').delete().eq('id', personRow.id)
+      throw extError
+    }
+  }
+
+  return {
+    id: String(personRow.id),
+    name: String(personRow.name ?? name),
+    phone: personRow.phone ?? undefined,
+    email: personRow.email ?? undefined,
+  }
+}

package/src/crud/CrudDetailPage.tsx

@@ -7,6 +7,7 @@ import { Badge } from '@fayz-ai/ui'
 import { Breadcrumb } from '@fayz-ai/ui'
 import { Tabs, TabsList, TabsTrigger, TabsContent } from '@fayz-ai/ui'
 import { Separator } from '@fayz-ai/ui'
+import { Markdown } from '@fayz-ai/ui'
 import { WidgetSlot } from '../plugins/WidgetSlot'
 import { formatCurrency } from '@fayz-ai/core'
 import { PERSON_DETAIL_TABS } from './archetypes/PersonDetailTabs'
@@ -76,6 +77,8 @@ function formatValue(field: FieldDef, value: any, t?: (key: string) => string):
       return <a href={value} target="_blank" rel="noopener noreferrer" className="text-primary hover:underline">{value}</a>
     case 'textarea':
       return <p className="whitespace-pre-wrap">{value}</p>
+    case 'markdown':
+      return value ? <Markdown source={String(value)} /> : null
     default:
       return String(value)
   }
@@ -270,7 +273,11 @@ export function CrudDetailPage({
   const displayField = entityDef.displayField ?? entityDef.fields[0]?.key ?? 'id'
   const displayValue = item[displayField] ?? 'Untitled'
   const subtitleValue = entityDef.subtitleField ? item[entityDef.subtitleField] : null
-  const imageValue = entityDef.imageField ? item[entityDef.imageField] : null
+  // `imageField` only reaches a plain string column. Entities whose image lives
+  // somewhere richer (a product's images[] relation, say) supply `image.get`,
+  // and without consulting it the hero fell back to the initial letter even for
+  // records that clearly have a photo.
+  const imageValue = entityDef.image?.get(item) ?? (entityDef.imageField ? item[entityDef.imageField] : null)
   const initial = typeof displayValue === 'string' ? displayValue.charAt(0).toUpperCase() : '?'
 
   // Merge archetype tabs + custom entity tabs. Entity-specific tabs win by id