@uniweb/kit 0.10.12 → 0.10.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.10.12",
+  "version": "0.10.14",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -43,9 +43,9 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
+    "@uniweb/semantic-parser": "1.2.1",
     "@uniweb/scene": "0.1.2",
-    "@uniweb/core": "0.8.1",
-    "@uniweb/semantic-parser": "1.2.1"
+    "@uniweb/core": "0.8.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/hooks/useFormSubmit.js

@@ -1,29 +1,45 @@
-import { useCallback, useState } from 'react'
+import { useCallback, useRef, useState } from 'react'
 import { submitForm } from '../utils/submitForm.js'
+import { resolveSubmitTarget } from '../utils/submitTarget.js'
+import { useWebsite } from './useWebsite.js'
 
 /**
- * React hook wrapping `submitForm()` with state machine for the
- * `idle → submitting → success | error` lifecycle most form UIs need.
+ * Submit a form, with 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
+ * The hook resolves *where* to submit from the site's configuration (`submit:`
+ * in site.yml) or from its host, so a component never names an endpoint. When
+ * neither supplies one, `canSubmit` is false and `unavailableReason` says why —
+ * render the control disabled rather than letting someone fill in a form whose
+ * contents have nowhere to go. See `resolveSubmitTarget` for the precedence.
  *
- * `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.
+ * ```jsx
+ * const { submit, status, error, canSubmit, unavailableReason } =
+ *   useFormSubmit({ block, context: { formId: 'contact' } })
  *
- * Examples — see kit's submitForm() JSDoc for the full payload contract.
+ * <button type="submit" disabled={!canSubmit || status === 'submitting'}>
+ *   {canSubmit ? 'Send' : unavailableReason}
+ * </button>
+ * ```
+ *
+ * Pass `block` and the submission carries where it came from — section type,
+ * section id, page id and label — without every component assembling that by
+ * hand. Anything in `context` wins over what the block supplies.
+ *
+ * `summary` may be an object or a function of the submitted values, which is
+ * the useful form when the digest is built from the fields that were just
+ * filled in.
  *
  * @param {object} [defaults] — merged into every submit() call
+ * @param {object} [defaults.block] — the section's block, for submission context
+ * @param {object} [defaults.context] — formId and any explicit overrides
+ * @param {object|Function} [defaults.summary] — { title, subtitle, tag? } or (formData) => that
  * @returns {{
  *   status: 'idle' | 'submitting' | 'success' | 'error',
  *   error: Error | null,
  *   response: object | null,
+ *   canSubmit: boolean,
+ *   unavailableReason: string | null,
  *   submit: (formData: object, overrides?: object) => Promise<object>,
  *   reset: () => void,
  * }}
@@ -33,16 +49,36 @@ export function useFormSubmit(defaults = {}) {
   const [error, setError] = useState(null)
   const [response, setResponse] = useState(null)
 
+  const { website } = useWebsite()
+  const { url: target, reason: unavailableReason } = resolveSubmitTarget(website)
+
+  // `defaults` is a fresh object every render, so listing it as a dependency
+  // would rebuild the callback on each one. A ref is what actually makes "the
+  // newest defaults win" true — with an empty dependency list the callback
+  // closes over the *first* render's defaults forever, so a summary or context
+  // computed from changing content would silently keep sending the original.
+  const defaultsRef = useRef(defaults)
+  defaultsRef.current = defaults
+
   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 { block, context, summary, ...rest } = {
+          ...defaultsRef.current,
+          ...perCallOverrides,
         }
+
+        const merged = {
+          ...rest,
+          formData,
+          target,
+          // Block-derived context first so an explicit `context` overrides it.
+          context: { ...contextFromBlock(block), ...context },
+          summary: typeof summary === 'function' ? summary(formData) : summary,
+        }
+
         const result = await submitForm(merged)
         setStatus('success')
         setResponse(result)
@@ -53,11 +89,7 @@ export function useFormSubmit(defaults = {}) {
         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
-    [],
+    [target],
   )
 
   const reset = useCallback(() => {
@@ -66,5 +98,40 @@ export function useFormSubmit(defaults = {}) {
     setResponse(null)
   }, [])
 
-  return { status, error, response, submit, reset }
+  return {
+    status,
+    error,
+    response,
+    canSubmit: !!target,
+    unavailableReason,
+    submit,
+    reset,
+  }
+}
+
+/**
+ * Where a submission came from, read off the block the form is rendered in.
+ *
+ * `stableId` is preferred over the positional `id` because it survives a
+ * section being reordered on its page — a submission's origin should not change
+ * because something moved above it. Keys with no value are dropped rather than
+ * sent as null, so they never mask a caller-supplied one.
+ *
+ * @param {object} [block]
+ * @returns {object}
+ */
+function contextFromBlock(block) {
+  if (!block) return {}
+
+  const page = block.page
+  const fields = {
+    sectionType: block.type,
+    sectionId: block.stableId || block.id,
+    pageId: page?.id,
+    pageLabel: page?.title,
+  }
+
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, v]) => v !== undefined && v !== null && v !== ''),
+  )
 }

package/src/index.js

@@ -124,7 +124,9 @@ export {
   getLocaleLabel,
   // Form submission utilities (low-level companion of useFormSubmit hook)
   submitForm,
-  derivePreviewFromFormData
+  deriveSummary,
+  resolveSubmitTarget,
+  NO_SUBMIT_TARGET_REASON
 } from './utils/index.js'
 
 // ============================================================================

package/src/utils/index.js

@@ -247,7 +247,8 @@ export function detectMediaType(url) {
 // Form Submission
 // ─────────────────────────────────────────────────────────────────
 
-export { submitForm, derivePreviewFromFormData } from './submitForm.js'
+export { submitForm, deriveSummary } from './submitForm.js'
+export { resolveSubmitTarget, NO_SUBMIT_TARGET_REASON } from './submitTarget.js'
 
 /**
  * The text of a ProseMirror node, flattened.

package/src/utils/submitForm.js

@@ -1,63 +1,78 @@
 /**
- * Submit a form to the Uniweb submission endpoint.
+ * POST a form's values to a 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.
+ * This is the low-level companion of `useFormSubmit()`. Most components want
+ * the hook — it resolves the target from the site's configuration and tracks
+ * the request's lifecycle. Reach for this directly when you are submitting
+ * outside React, or already hold a resolved target.
  *
- * 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.
+ * ## `target` is required, and there is no default
  *
- * 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.
+ * Where a site's submissions go is the site's declaration (`submit:` in
+ * site.yml — see `resolveSubmitTarget`), never this function's guess. Calling
+ * without a target throws rather than falling back to a path, because a form
+ * POSTing into a 404 loses what a visitor typed and reports success-shaped
+ * failure. Resolve first, disable the control if there is nowhere to send.
  *
- * Optional `turnstileToken` is forwarded as-is for bot-protection
- * verification when the platform has Turnstile enabled.
+ * ## API names and wire names differ, on purpose
+ *
+ * The request body's field names are a contract with already-deployed
+ * endpoints, so they are kept exactly as those endpoints read them. This
+ * function's *arguments* are named for what they mean to a foundation
+ * developer. The mapping is applied in one place below and is not a bug to
+ * tidy up — changing the body's spelling would require every deployed endpoint
+ * to change with it.
  *
  * @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 {Record<string, unknown>} args.formData  — field values
+ * @param {string} args.target                     — resolved endpoint URL (required)
+ * @param {object} [args.summary]                  — { title, subtitle, tag? }, a short
+ *                                                   human-readable digest of this
+ *                                                   submission; derived from formData
+ *                                                   when omitted
+ * @param {object} [args.context]                  — where the submission came from:
+ *                                                   formId, sectionType, sectionId,
+ *                                                   pageId, pageLabel
+ * @param {string} [args.verificationToken]        — bot-protection token, when the
+ *                                                   endpoint verifies one
  * @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)
+ *                                                 — declared file uploads
+ * @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.
+ * @throws {Error} with no target, and on non-2xx with the server's message when present.
  */
 export async function submitForm({
   formData,
-  preview,
-  metadata = {},
-  turnstileToken,
+  target,
+  summary,
+  context = {},
+  verificationToken,
   fileSlots,
-  submitPath = '/_submit',
   fetchFn = typeof fetch === 'function' ? fetch : null,
 } = {}) {
   if (!formData || typeof formData !== 'object') {
     throw new Error('submitForm: formData object is required')
   }
+  if (!target || typeof target !== 'string') {
+    throw new Error(
+      'submitForm: no submission target. Declare `submit:` in site.yml, or ' +
+      'check `canSubmit` from useFormSubmit() before calling.',
+    )
+  }
   if (!fetchFn) {
     throw new Error('submitForm: fetch is unavailable in this environment')
   }
 
-  const finalPreview = preview || derivePreviewFromFormData(formData)
-
+  // ── API name → wire name. See the header before "correcting" these. ──
   const body = {
     formData,
-    metadata: { ...metadata, preview: finalPreview },
-    ...(turnstileToken ? { turnstileToken } : {}),
+    metadata: { ...context, preview: summary || deriveSummary(formData) },
+    ...(verificationToken ? { turnstileToken: verificationToken } : {}),
     ...(Array.isArray(fileSlots) && fileSlots.length ? { fileSlots } : {}),
   }
 
-  const res = await fetchFn(submitPath, {
+  const res = await fetchFn(target, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify(body),
@@ -73,14 +88,14 @@ export async function submitForm({
 }
 
 /**
- * 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.
+ * Build a default summary from a form's values: the first two non-empty string
+ * fields become the title and subtitle, so whoever reads submissions sees
+ * something meaningful even when a component passes no summary of its own.
  *
  * @param {Record<string, unknown>} data
  * @returns {{ title: string, subtitle: string }}
  */
-export function derivePreviewFromFormData(data) {
+export function deriveSummary(data) {
   if (!data || typeof data !== 'object') return { title: 'Submission', subtitle: '' }
   const entries = Object.entries(data).filter(
     ([, v]) => typeof v === 'string' && v.trim().length > 0,

package/src/utils/submitTarget.js

@@ -0,0 +1,124 @@
+/**
+ * Resolve where this site's form submissions go.
+ *
+ * A site declares its endpoint under `submit:` in site.yml, and the value
+ * arrives here as `website.config.submit` — the same passthrough every other
+ * site.yml key rides (`collections:`, `search:`, `fetcher:`). Two spellings,
+ * because one destination is the common case and the object form leaves room
+ * to grow:
+ *
+ *   submit: /forms                    # shorthand
+ *   submit: { endpoint: /forms }      # object form
+ *   submit: https://forms.example.com/intake
+ *
+ * A relative endpoint resolves against `website.basePath`, so one spelling
+ * works whether the site is served from the root, from a subdirectory
+ * (`base: /docs/`), or from a host subpath. An absolute URL passes through
+ * untouched, for a form service on another origin.
+ *
+ * ## Precedence — and why the framework never picks one itself
+ *
+ * A destination comes from the first of these that applies:
+ *
+ *   1. `submit:` here — the site operator's declaration.
+ *   2. `forms: { endpoint, reason }` in the served payload config — what the
+ *      HOST reports about this site. A host that accepts submissions gives an
+ *      endpoint; one that does not may give a reason, which is relayed verbatim.
+ *   3. Neither — `url: null` plus a generic reason, so the form renders disabled.
+ *
+ * What the framework must never do is invent one. It cannot know where a given
+ * site can accept a submission, and guessing is worse than having none: on a
+ * static host, or any deployment with nothing listening, the form POSTs a
+ * visitor's data into a 404 and nothing here can tell. The asymmetry with
+ * reading matters — a fetch that 404s degrades to `[]` and the page still
+ * renders, which is a documented guarantee, but a write that 404s loses what
+ * someone typed.
+ *
+ * Note that a host supplying a site-local path is NOT the same as the framework
+ * defaulting to one, even when the two produce an identical request: a host only
+ * offers the path when something is actually there to catch it. Same bytes, and
+ * only one of them is correct.
+ *
+ * ## Simulating a host locally
+ *
+ * The bundle lane spreads all of site.yml into the payload config, so writing
+ * `forms: { endpoint: … }` in site.yml exercises tier 2 end to end with no
+ * framework change. It cannot leak into a real deployment: the sync lane is an
+ * explicit allowlist and does not carry `forms`, so a synced site's value can
+ * only have come from its host.
+ */
+
+/**
+ * Shown when a site declares no endpoint. English, and a foundation is free to
+ * ignore it and render its own copy — check `url` for the yes/no and treat this
+ * as a default rather than a string to translate.
+ */
+export const NO_SUBMIT_TARGET_REASON =
+  'This site has no form submission endpoint configured.'
+
+/**
+ * Resolve the submission target for a site.
+ *
+ * @param {object} website - The active Website instance
+ * @returns {{ url: string|null, reason: string|null }}
+ *   `url` is the resolved absolute-or-base-relative endpoint, or null when the
+ *   site declares none. `reason` is set exactly when `url` is null.
+ */
+export function resolveSubmitTarget(website) {
+  const config = website?.config
+  const basePath = website?.basePath
+
+  // Tier 1 — the site operator's own declaration (`submit:` in site.yml).
+  const declared = config?.submit
+  const declaredEndpoint =
+    typeof declared === 'string'
+      ? declared.trim()
+      : typeof declared?.endpoint === 'string'
+        ? declared.endpoint.trim()
+        : ''
+
+  if (declaredEndpoint) {
+    return { url: resolveAgainstBase(declaredEndpoint, basePath), reason: null }
+  }
+
+  // Tier 2 — a destination the HOST reports, under `forms` in the served
+  // payload config. Named for the capability rather than the action so it
+  // cannot be misread as the authored `submit` sitting beside it in the same
+  // flat object.
+  const host = config?.forms
+  const hostEndpoint = typeof host?.endpoint === 'string' ? host.endpoint.trim() : ''
+  if (hostEndpoint) {
+    return { url: resolveAgainstBase(hostEndpoint, basePath), reason: null }
+  }
+
+  // A host that reports WHY it cannot accept submissions gets that relayed
+  // verbatim. The framework does not interpret, reword, or second-guess it: it
+  // has no standing to judge why a given site can or cannot accept them, and
+  // guessing at the reason in public code would mean encoding someone else's
+  // policy here.
+  const hostReason = typeof host?.reason === 'string' ? host.reason.trim() : ''
+  if (hostReason) return { url: null, reason: hostReason }
+
+  // Tier 3 — nobody supplied one.
+  return { url: null, reason: NO_SUBMIT_TARGET_REASON }
+}
+
+/**
+ * Join a declared endpoint to the site's base path.
+ *
+ * This is the same shape as `resolveEndpointUrl` in the search provider, and is
+ * deliberately NOT shared with it: that one falls back to a default endpoint
+ * when given nothing, which is precisely the behaviour a submission target must
+ * not have (see the header). Three lines of duplication is the cheaper mistake.
+ *
+ * @param {string} endpoint - Declared endpoint, relative or absolute
+ * @param {string} [basePath] - `website.basePath`, normalized without a trailing slash
+ * @returns {string}
+ */
+export function resolveAgainstBase(endpoint, basePath = '') {
+  if (/^https?:\/\//i.test(endpoint)) return endpoint
+
+  const base = (basePath || '').replace(/\/+$/, '')
+  const rel = endpoint.replace(/^\/+/, '')
+  return `${base}/${rel}`
+}