@sonordev/site-kit 7.0.1 → 7.1.0

package/src/forms/README.md

@@ -0,0 +1,219 @@
+# Forms — `@sonordev/site-kit/forms`
+
+Sonor-managed forms with multi-step support, conditional logic, validation, anti-bot protection, and automatic CRM routing.
+
+## Usage
+
+### Option 1: Managed (simplest)
+
+```tsx
+import { ManagedForm } from '@sonordev/site-kit/forms'
+
+export default function ContactPage() {
+  return <ManagedForm formId="contact-form" />
+}
+```
+
+Fetches form config from Sonor, renders fields, handles submission, routes to CRM.
+
+## Experiences (4.0)
+
+Since 4.0 that one line gets you the **spotlight** experience by default: the
+familiar layout, alive. A glowing ring visits the field you're in, completed
+fields earn a check, and each finished row collapses into a sentence the form
+says back — "Nice to meet you, Jordan." / "We'll follow up at jordan@…" — with
+an edit control to reopen it.
+
+| Experience | What it is | How to get it |
+|---|---|---|
+| `spotlight` | **Default.** Fields perform in place; answered rows become sentences | nothing to do |
+| `stage` | Accordion: one beat at a time on a single surface, answered beats settle into filled rows | `experience="stage"` |
+| `classic` | The plain grid form, no choreography | `experience="classic"` |
+
+```tsx
+<ManagedForm formId="contact-form" />                      // spotlight
+<ManagedForm formId="contact-form" experience="stage" />   // accordion
+<ManagedForm formId="contact-form" experience="classic" /> // opt out
+```
+
+Sonor can decide instead of the site, with no deploy on either side — set the
+form's `layout` to `classic`, `stage`, or `spotlight`. An explicit
+`experience` prop always wins over the config.
+
+Three things hold for every experience:
+
+- **The lead is always capturable.** SSR and no-JS render the plain classic
+  form; the experience layers on after hydration. If its chunk never arrives,
+  the form still works and still submits.
+- **Nobody pays for what they don't use.** Experience code is loaded on
+  demand, so a `classic` form downloads none of it.
+- **Same engine.** Identical validation, honeypot, reCAPTCHA, and CRM routing
+  — an experience is a rendering, not a fork.
+
+### Editing what the form says back
+
+The sentence for a row comes from the kit's built-in wording unless you write
+your own in Sonor: set **`completion_message`** on a field (the first answered
+field in the row that has one wins). Tokens:
+
+| Token | Resolves to |
+|---|---|
+| `{value}` | this field's answer |
+| `{label}` | this field's label |
+| `{first_name}` | the form's first-name answer, if any |
+| `{any_field_slug}` | that field's answer |
+
+```
+Welcome aboard, {first_name}. We'll reach you at {email}.
+```
+
+Leave it empty to keep the built-in sentence. Unknown or unanswered tokens
+render as nothing — never raw braces.
+
+### Option 2: Headless Hook (full UI control)
+
+```tsx
+'use client'
+import { useForm } from '@sonordev/site-kit/forms'
+
+export function ContactForm() {
+  const {
+    fields, values, errors, setFieldValue, submit, isSubmitting,
+    step, totalSteps, isMultiStep, nextStep, prevStep, isLastStep,
+  } = useForm('contact-form')
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); submit() }}>
+      {fields.map(field => (
+        <div key={field.slug}>
+          <label>{field.label}</label>
+          <input
+            value={String(values[field.slug] || '')}
+            onChange={(e) => setFieldValue(field.slug, e.target.value)}
+          />
+          {errors[field.slug] && <span className="error">{errors[field.slug]}</span>}
+        </div>
+      ))}
+      {isMultiStep && !isLastStep && <button type="button" onClick={nextStep}>Next</button>}
+      {isLastStep && <button type="submit" disabled={isSubmitting}>Submit</button>}
+    </form>
+  )
+}
+```
+
+### Option 3: Render Prop
+
+```tsx
+<ManagedForm formId="contact-form">
+  {({ fields, values, setFieldValue, submit }) => (
+    <MyCustomFormUI fields={fields} values={values} onChange={setFieldValue} onSubmit={submit} />
+  )}
+</ManagedForm>
+```
+
+### Option 4: Programmatic API
+
+```ts
+import { formsApi, field, configureFormsApi } from '@sonordev/site-kit/forms'
+
+configureFormsApi({ baseUrl: 'https://api.sonor.io', apiKey: 'sonor_...' })
+
+const form = await formsApi.create({
+  projectId: 'xxx',
+  slug: 'newsletter',
+  name: 'Newsletter Signup',
+  formType: 'newsletter',
+  fields: [
+    field.email('email', 'Email', { isRequired: true }),
+    field.text('name', 'Name'),
+  ],
+})
+```
+
+## ManagedForm Props
+
+```ts
+interface ManagedFormProps {
+  formId: string                              // Form slug or ID
+  className?: string
+  onSuccess?: (submission: FormSubmitResult) => void
+  onError?: (error: Error) => void
+  children?: (renderProps: UseFormReturn) => ReactNode  // Render prop override
+}
+```
+
+## useForm Return
+
+```ts
+interface UseFormReturn {
+  form: ManagedFormConfig | null
+  isLoading: boolean
+  fetchError: Error | null
+  allFields: FormField[]
+  fields: FormField[]               // Current step's fields
+  visibleFields: FormField[]         // After conditional logic
+  values: Record<string, unknown>
+  errors: Record<string, string>
+  setFieldValue: (key: string, value: unknown) => void
+  step: number
+  totalSteps: number
+  isMultiStep: boolean
+  progress: number                   // 0-100
+  nextStep: () => void
+  prevStep: () => void
+  goToStep: (n: number) => void
+  canGoNext: boolean
+  canGoPrev: boolean
+  isLastStep: boolean
+  validate: () => boolean
+  submit: () => Promise<void>
+  isSubmitting: boolean
+  isComplete: boolean
+  reset: () => void
+}
+```
+
+## Field Types
+
+`text`, `email`, `phone`, `tel`, `number`, `textarea`, `select`, `multi-select`, `checkbox`, `radio`, `date`, `time`, `datetime`, `file`, `signature`, `rating`, `slider`, `hidden`, `heading`, `section_header`, `paragraph`
+
+## Field Builder
+
+```ts
+field.text(slug, label, options?)
+field.email(slug, label, options?)
+field.phone(slug, label, options?)
+field.textarea(slug, label, options?)
+field.select(slug, label, { options: [{ value, label }] })
+field.date(slug, label, options?)
+field.checkbox(slug, label, options?)
+field.rating(slug, label, options?)
+```
+
+## Form Routing
+
+Submissions auto-route based on `form_type`:
+
+| Form Type | Routes To | Use Case |
+|-----------|-----------|----------|
+| `prospect` / `lead-capture` / `contact` | CRM Contacts | Sales inquiries, quotes |
+| `support` | Support Tickets | Help requests |
+| `feedback` | Feedback entries | User feedback |
+| `newsletter` | Email Subscribers | Newsletter signups |
+| `custom` | Form Submissions only | Custom handling |
+
+## Anti-Bot Protection
+
+- **Honeypot fields** — hidden fields that bots fill (server-side rejection)
+- **reCAPTCHA Enterprise** — optional Google reCAPTCHA v3 scoring
+- **Submission timing** — forms that submit in < 3 seconds are flagged
+- **Composite spam scoring** — name patterns, email domain, user-agent, IP rate, message content
+- **NestJS ThrottlerGuard** — 10 requests/minute per IP at HTTP level
+
+## Styles
+
+```tsx
+import '@sonordev/site-kit/forms/styles.css'  // Optional default styles
+```
+
+All components use `.sk-form__*` class names. Override with `className` prop or CSS variables.

package/src/images/README.md

@@ -0,0 +1,74 @@
+# Images — `@sonordev/site-kit/images`
+
+Sonor-managed image slots with dev-mode editing, focal point support, and image picker.
+
+## Usage
+
+```tsx
+import { ManagedImage } from '@sonordev/site-kit/images'
+
+export default function HeroSection() {
+  return (
+    <ManagedImage
+      slotId="hero-background"
+      alt="Hero background"
+      width={1920}
+      height={1080}
+      objectFit="cover"
+      fallback="/images/default-hero.jpg"
+    />
+  )
+}
+```
+
+## Props
+
+```ts
+interface ManagedImageProps {
+  slotId: string                     // Unique slot identifier (e.g., 'hero-background')
+  pagePath?: string                  // Page-specific slots (defaults to current path)
+  alt?: string                       // Fallback alt text
+  className?: string
+  width?: number | string
+  height?: number | string
+  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
+  fallback?: string                  // Fallback image URL when slot is empty
+  placeholder?: React.ReactNode     // Custom placeholder component
+  onLoad?: () => void
+  onError?: (error: Error) => void
+  priority?: boolean                 // Eager loading (Next.js Image priority)
+  style?: React.CSSProperties
+  forceDevMode?: boolean             // Enable dev picker outside localhost
+}
+```
+
+## Dev Mode
+
+Dev mode is on when `NODE_ENV` is `development`, on `localhost` / `127.0.0.1`, on any host with `?sonor_dev=true` in the URL, or with `forceDevMode`:
+- Click any `ManagedImage` to open the image picker modal
+- Browse files by folder, search, upload new images
+- Set alt text and focal point
+- Shows slot ID in empty states for debugging
+
+## Focal Point
+
+When an image has `focal_point_x` / `focal_point_y` set in Sonor, the component auto-calculates `object-position` so the focal area stays visible during cropping.
+
+## API Functions
+
+```ts
+import { fetchManagedImage, uploadImage, assignImageToSlot } from '@sonordev/site-kit/images'
+
+const image = await fetchManagedImage(slotId, pagePath)
+const uploaded = await uploadImage(file, { folder: 'heroes', category: 'background' })
+await assignImageToSlot(slotId, uploaded.id, pagePath)
+```
+
+## Favicon
+
+```tsx
+import { ManagedFavicon } from '@sonordev/site-kit/images'
+
+// In layout <head>:
+<ManagedFavicon />  // Fetches Sonor logo as favicon link tags
+```

package/src/layout/README.md

@@ -0,0 +1,66 @@
+# Layout — `@sonordev/site-kit/layout`
+
+RSC-compatible master layout that auto-composes all site-kit features.
+
+## Usage
+
+```tsx
+// app/layout.tsx
+import { SiteKitLayout } from '@sonordev/site-kit/layout'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <SiteKitLayout>{children}</SiteKitLayout>
+      </body>
+    </html>
+  )
+}
+```
+
+Zero-config: reads `SONOR_API_KEY` from env, injects it into client modules automatically.
+
+## Props
+
+```ts
+interface SiteKitLayoutProps {
+  children: React.ReactNode
+  apiKey?: string                         // Defaults to SONOR_API_KEY env var
+  apiUrl?: string                         // Defaults to SONOR_API_URL, then https://api.sonor.io
+  projectId?: string                      // For Engage chat routing (auto-resolved if omitted)
+  analytics?: boolean | AnalyticsConfig   // Default: true
+  engage?: boolean | EngageConfig         // Default: true
+  signal?: boolean | SignalConfig         // Default: false
+  sitemapSync?: boolean                   // Default: false (build-time + server reconciler own this)
+  fleet?: boolean                         // Default: true (once-per-session kit version heartbeat)
+  defer?: boolean                         // Default: true (client modules wait for load + idle)
+  favicon?: boolean                       // Default: true
+  managedScripts?: boolean                // Default: true
+  debug?: boolean                         // Default: false
+  showLlmsTxtFooterLink?: boolean         // Default: false (prefer middleware discovery headers)
+  speculation?: boolean | { mode?: 'prerender' | 'prefetch'; exclude?: string[] } // Default: false
+}
+```
+
+Module options live with each module: [Analytics](../analytics/README.md) (`trackPageViews`, `excludePaths`, `site`, `allowInFrame`, `allowLocalhost`) and [Engage](../engage/README.md) (`position`, `chatEnabled`, and launcher placement).
+
+## What It Composes
+
+**Server-side (RSC):**
+- `ManagedFavicon` — Sonor logo as `<link>` tags
+- `ManagedScripts` — tracking pixels/analytics tags in `<head>` and body-end positions
+- API preconnect/dns-prefetch hints
+
+**Client-side (lazy-loaded island):**
+- `AnalyticsProvider` — page views, scroll depth, heatmap clicks, Web Vitals
+- `EngageWidget` — popups, nudges, chat
+- `SignalBridge` — A/B experiments, behavior tracking (opt-in)
+- `SitemapSync` — parses `/sitemap.xml` and syncs to Sonor (opt-in)
+- `FleetHeartbeat` — reports the kit version and enabled modules once per session
+
+Since 4.0.0 none of these wrap your page. `{children}` renders first and every module mounts after it as a childless sibling, so `SiteKitLayout` never pushes a route to client rendering. Analytics, Engage, SitemapSync and the heartbeat also wait for window load + idle (or the first interaction) unless you pass `defer={false}`. `SignalBridge` isn't deferred, so experiment variants apply early. Visitor and session IDs come from a shared storage singleton rather than a provider.
+
+## Note
+
+`SiteKitProvider` was **removed in 4.0.0**. It wrapped the whole tree client-side, which broke RSC. Migrate an older layout with `npx sonor-setup codemod --only provider-to-layout --write`.