@uniweb/kit 0.9.11 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {

package/src/components/Link/Link.jsx

@@ -217,6 +217,7 @@ export function Link({
         href={basePath + linkHref}
         title={linkTitle}
         className={className}
+        data-reload="true"
         {...props}
       >
         {children}

package/src/hooks/index.js

@@ -23,3 +23,6 @@ export {
   useThemeColor,
   useThemeColorVar
 } from './useThemeData.js'
+
+// Form submission lifecycle for foundation Form components
+export { useFormSubmit } from './useFormSubmit.js'

package/src/hooks/useFormSubmit.js

@@ -0,0 +1,70 @@
+import { useCallback, useState } from 'react'
+import { submitForm } from '../utils/submitForm.js'
+
+/**
+ * React hook wrapping `submitForm()` with state machine for the
+ * `idle → submitting → success | error` lifecycle most form UIs need.
+ *
+ * Pass `defaults` once (formId, sectionType, preview-builder, …) and call
+ * `submit(formData)` from your submit handler. The hook exposes:
+ *   - status: 'idle' | 'submitting' | 'success' | 'error'
+ *   - error:  Error | null
+ *   - response: { submissionId, uploadUrls? } | null  (on success)
+ *   - submit: async (formData, perCallOverrides?) => response
+ *   - reset:  () => void
+ *
+ * `defaults.preview` may be either a static object or a function of formData
+ * that returns one. The function form is useful when the preview is computed
+ * from the same fields that just got submitted.
+ *
+ * Examples — see kit's submitForm() JSDoc for the full payload contract.
+ *
+ * @param {object} [defaults] — merged into every submit() call
+ * @returns {{
+ *   status: 'idle' | 'submitting' | 'success' | 'error',
+ *   error: Error | null,
+ *   response: object | null,
+ *   submit: (formData: object, overrides?: object) => Promise<object>,
+ *   reset: () => void,
+ * }}
+ */
+export function useFormSubmit(defaults = {}) {
+  const [status, setStatus] = useState('idle')
+  const [error, setError] = useState(null)
+  const [response, setResponse] = useState(null)
+
+  const submit = useCallback(
+    async (formData, perCallOverrides = {}) => {
+      setStatus('submitting')
+      setError(null)
+      try {
+        const merged = { ...defaults, ...perCallOverrides, formData }
+        // Resolve preview-as-function against the formData being submitted.
+        if (typeof merged.preview === 'function') {
+          merged.preview = merged.preview(formData)
+        }
+        const result = await submitForm(merged)
+        setStatus('success')
+        setResponse(result)
+        return result
+      } catch (err) {
+        setStatus('error')
+        setError(err)
+        throw err
+      }
+    },
+    // `defaults` is referentially unstable across renders; we deliberately
+    // close over the latest one each render rather than memo the hook.
+    // The lint rule fires false positives here.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
+  const reset = useCallback(() => {
+    setStatus('idle')
+    setError(null)
+    setResponse(null)
+  }, [])
+
+  return { status, error, response, submit, reset }
+}

package/src/index.js

@@ -79,7 +79,9 @@ export {
   useThemeColorVar,
   // Observable state bridges (page.state / website.state)
   usePageState,
-  useWebsiteState
+  useWebsiteState,
+  // Form submission lifecycle for foundation Form components
+  useFormSubmit
 } from './hooks/index.js'
 
 // ============================================================================
@@ -102,7 +104,10 @@ export {
   ChildBlocks,
   // Locale utilities
   LOCALE_DISPLAY_NAMES,
-  getLocaleLabel
+  getLocaleLabel,
+  // Form submission utilities (low-level companion of useFormSubmit hook)
+  submitForm,
+  derivePreviewFromFormData
 } from './utils/index.js'
 
 // ============================================================================

package/src/utils/index.js

@@ -271,3 +271,9 @@ export function detectMediaType(url) {
 
   return 'unknown'
 }
+
+// ─────────────────────────────────────────────────────────────────
+// Form Submission
+// ─────────────────────────────────────────────────────────────────
+
+export { submitForm, derivePreviewFromFormData } from './submitForm.js'

package/src/utils/submitForm.js

@@ -0,0 +1,92 @@
+/**
+ * Submit a form to the Uniweb submission endpoint.
+ *
+ * Form components in a foundation collect field values and call this to
+ * deliver them to the platform's submission pipeline. The submission lands
+ * keyed by the site's identity (resolved by the platform from the
+ * visitor's hostname), so this function takes no siteId — the page's
+ * own URL determines the destination.
+ *
+ * The default `submitPath` is `/_submit`, served on the visitor's hostname
+ * by the Uniweb runtime infrastructure. Override only if you're testing
+ * against a non-standard endpoint.
+ *
+ * The `preview` object becomes the {title, subtitle, tag} that the
+ * editor's inbox row displays for this submission. If a foundation
+ * doesn't pass one, a fallback is derived from the first two non-empty
+ * string fields of `formData` so the row is always meaningful.
+ *
+ * Optional `turnstileToken` is forwarded as-is for bot-protection
+ * verification when the platform has Turnstile enabled.
+ *
+ * @param {object} args
+ * @param {Record<string, unknown>} args.formData      — field values
+ * @param {object} [args.preview]                       — { title, subtitle, tag? }
+ * @param {object} [args.metadata]                      — formId, sectionType, sectionId, pageId, pageLabel, …
+ * @param {string} [args.turnstileToken]                — Cloudflare Turnstile token
+ * @param {Array<{name:string,size:number,mime?:string}>} [args.fileSlots]
+ *                                                       — declared file uploads (multi-step ingestion)
+ * @param {string} [args.submitPath='/_submit']         — endpoint override (testing)
+ * @param {typeof fetch} [args.fetchFn=fetch]           — fetch override (testing / SSR)
+ *
+ * @returns {Promise<{ submissionId: string, uploadUrls?: Array }>}
+ * @throws {Error} on non-2xx with the server's `error` message when present.
+ */
+export async function submitForm({
+  formData,
+  preview,
+  metadata = {},
+  turnstileToken,
+  fileSlots,
+  submitPath = '/_submit',
+  fetchFn = typeof fetch === 'function' ? fetch : null,
+} = {}) {
+  if (!formData || typeof formData !== 'object') {
+    throw new Error('submitForm: formData object is required')
+  }
+  if (!fetchFn) {
+    throw new Error('submitForm: fetch is unavailable in this environment')
+  }
+
+  const finalPreview = preview || derivePreviewFromFormData(formData)
+
+  const body = {
+    formData,
+    metadata: { ...metadata, preview: finalPreview },
+    ...(turnstileToken ? { turnstileToken } : {}),
+    ...(Array.isArray(fileSlots) && fileSlots.length ? { fileSlots } : {}),
+  }
+
+  const res = await fetchFn(submitPath, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+
+  if (!res.ok) {
+    let serverMessage
+    try { serverMessage = (await res.json()).error } catch { /* not JSON */ }
+    throw new Error(serverMessage || `Submission failed (HTTP ${res.status})`)
+  }
+
+  return res.json()
+}
+
+/**
+ * Build a default preview from a form's field values: first two non-empty
+ * string fields become the title / subtitle. Mirrors the legacy
+ * getStandardPreview() convention from the prior Form class.
+ *
+ * @param {Record<string, unknown>} data
+ * @returns {{ title: string, subtitle: string }}
+ */
+export function derivePreviewFromFormData(data) {
+  if (!data || typeof data !== 'object') return { title: 'Submission', subtitle: '' }
+  const entries = Object.entries(data).filter(
+    ([, v]) => typeof v === 'string' && v.trim().length > 0,
+  )
+  return {
+    title: entries[0]?.[1] || 'Submission',
+    subtitle: entries[1]?.[1] || '',
+  }
+}