@uniweb/kit 0.10.21 → 0.10.23

package/README.md

@@ -476,9 +476,15 @@ const client = createSearchClient(website, {
   defaultLimit: 10
 })
 
-// Query
+// Query — returns SearchResult[]
 const results = await client.query('authentication', { limit: 5 })
 
+// Same query, plus how many matched before `limit` — the 47 in "showing 10 of 47".
+// `total` is null when the active provider cannot say (a deployment fact, not an
+// error): the local index always knows it; an endpoint knows it only if it
+// reports one. Render the count conditionally, the results unconditionally.
+const { results: page, total } = await client.queryWithTotal('authentication', { limit: 5 })
+
 // Preload index
 await client.preload()
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.10.21",
+  "version": "0.10.23",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -43,8 +43,8 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
-    "@uniweb/semantic-parser": "1.2.1",
     "@uniweb/scene": "0.1.3",
+    "@uniweb/semantic-parser": "1.2.1",
     "@uniweb/core": "0.8.2"
   },
   "peerDependencies": {

package/src/hooks/useFormValues.js

@@ -170,6 +170,18 @@ function setIn(node, [key, ...rest], value) {
   return { ...base, [key]: setIn(base[key], rest, value) }
 }
 
+/**
+ * Which control kinds hold uploads.
+ *
+ * BOTH `file` and `image` — they are two words in the authoring vocabulary for
+ * the same control, and the visual editor draws a file picker for either. Only
+ * `file` was checked here, so an `image` control's `File` objects went into
+ * `formData` and `JSON.stringify` turned each into `{}`: an attachment the
+ * visitor chose, reported as sent, arriving empty. Exactly the failure the
+ * split below exists to prevent, reachable through the other spelling.
+ */
+const isUpload = (control) => control.type === 'file' || control.type === 'image'
+
 /**
  * Split the held values into what is submitted and what is uploaded.
  *
@@ -186,7 +198,7 @@ function split(controls, values) {
     const value = valueAt(values, control.path)
     if (value === undefined) continue
 
-    if (control.type === 'file') {
+    if (isUpload(control)) {
       for (const file of [].concat(value).filter(isFile)) {
         files.push({ file, field: control.path })
       }

package/src/search/client.js

@@ -84,6 +84,25 @@ async function loadProviderFactory(name, transports) {
  * const search = createSearchClient(website)
  * const results = await search.query('authentication')
  */
+/**
+ * Accept either provider return shape.
+ *
+ * A provider may return `SearchResult[]` or `{ results, total }`. Both are
+ * valid and the array form is not deprecated: `transport.query` is a public
+ * seam a third party implements, and its documented contract has always been
+ * "returns results". Widening that to an envelope would break every custom
+ * transport in the field to add a number most of them cannot supply.
+ *
+ * An array therefore means "no count offered" → `total: null`, which is exactly
+ * what null is for here. Our own two providers return the envelope.
+ */
+function normalizeQueryResult(returned) {
+  if (Array.isArray(returned)) return { results: returned, total: null }
+  const results = Array.isArray(returned?.results) ? returned.results : []
+  const total = Number.isInteger(returned?.total) ? returned.total : null
+  return { results, total }
+}
+
 export function createSearchClient(website, options = {}) {
   const {
     defaultLimit = 10,
@@ -207,7 +226,7 @@ export function createSearchClient(website, options = {}) {
     },
 
     /**
-     * Perform a search query
+     * Perform a search query.
      *
      * @param {string} query - Search query
      * @param {Object} queryOptions - Query options
@@ -218,21 +237,47 @@ export function createSearchClient(website, options = {}) {
      * @returns {Promise<Array>} Search results
      */
     async query(query, queryOptions = {}) {
+      return (await this.queryWithTotal(query, queryOptions)).results
+    },
+
+    /**
+     * The same query, plus how many matched.
+     *
+     * Exists because `query()` returns an array and a count cannot ride on one
+     * without being silently dropped by `.slice()`/`.filter()`/spread — and
+     * `query()` is a published surface returning `SearchResult[]`, so widening
+     * its return would break every foundation iterating it.
+     *
+     * **`total` is the match count BEFORE `limit`** — the 47 in "showing 10 of
+     * 47". It is `null` when unknowable, and null is a real answer rather than
+     * a failure: a provider-optional field in the same sense as `matches` or
+     * `item` on a result. Whether a count arrives is a DEPLOYMENT fact — the
+     * local index always knows it, an endpoint knows it only if it says so —
+     * so a UI must render the count conditionally and the bare result list
+     * unconditionally.
+     *
+     * ⚠️ `total >= results.length` is NOT guaranteed to be checkable: a
+     * provider reporting a count for a set we then filtered locally reports
+     * null instead, precisely so the two numbers are never inconsistent.
+     *
+     * @returns {Promise<{results: Array, total: number|null}>}
+     */
+    async queryWithTotal(query, queryOptions = {}) {
       const { limit = defaultLimit, type, route, signal } = queryOptions
 
       const trimmed = query?.trim()
-      if (!trimmed) return []
+      if (!trimmed) return { results: [], total: 0 }
 
       if (!website.isSearchEnabled()) {
         console.warn('Search is not enabled for this site')
-        return []
+        return { results: [], total: 0 }
       }
 
       const opts = { limit, type, route, signal }
 
       try {
         const provider = await getProvider()
-        return await provider.query(trimmed, opts)
+        return normalizeQueryResult(await provider.query(trimmed, opts))
       } catch (err) {
         // An aborted query is a caller decision, not a provider failure.
         if (err?.name === 'AbortError') throw err
@@ -240,13 +285,13 @@ export function createSearchClient(website, options = {}) {
         const fallback = await fallbackToIndex(err)
         if (!fallback) {
           console.warn(`[uniweb] Search failed: ${err?.message}`)
-          return []
+          return { results: [], total: null }
         }
         try {
-          return await fallback.query(trimmed, opts)
+          return normalizeQueryResult(await fallback.query(trimmed, opts))
         } catch (fallbackErr) {
           console.warn(`[uniweb] Search fallback failed: ${fallbackErr?.message}`)
-          return []
+          return { results: [], total: null }
         }
       }
     },

package/src/search/hooks.js

@@ -17,12 +17,13 @@ import { useShortcut } from '../hooks/useShortcut.js'
  *
  * @example
  * function SearchComponent() {
- *   const { query, results, isLoading, error } = useSearch(website)
+ *   const { query, results, total, isLoading, error } = useSearch(website)
  *
  *   return (
  *     <div>
  *       <input onChange={e => query(e.target.value)} />
  *       {isLoading && <span>Searching...</span>}
+ *       {total !== null && <span>Showing {results.length} of {total}</span>}
  *       {results.map(r => <SearchResult key={r.id} result={r} />)}
  *     </div>
  *   )
@@ -32,6 +33,7 @@ export function useSearch(website, options = {}) {
   const { debounceMs = 150, ...clientOptions } = options
 
   const [results, setResults] = useState([])
+  const [total, setTotal] = useState(null)
   const [isLoading, setIsLoading] = useState(false)
   const [error, setError] = useState(null)
   const [lastQuery, setLastQuery] = useState('')
@@ -71,6 +73,7 @@ export function useSearch(website, options = {}) {
     // Empty query - clear results immediately
     if (!trimmed) {
       setResults([])
+      setTotal(0)
       setIsLoading(false)
       setError(null)
       return []
@@ -99,7 +102,8 @@ export function useSearch(website, options = {}) {
         setError(null)
 
         try {
-          const searchResults = await client.query(trimmed, queryOptions)
+          const { results: searchResults, total: matchTotal } =
+            await client.queryWithTotal(trimmed, queryOptions)
 
           // Skip if a newer search was started
           if (pendingRef.current !== searchId) {
@@ -108,7 +112,10 @@ export function useSearch(website, options = {}) {
           }
 
           setResults(searchResults)
+          setTotal(matchTotal)
           setIsLoading(false)
+          // Resolves with the ARRAY, unchanged — this hook's promise is a
+          // published surface and the count is available as state instead.
           resolve(searchResults)
         } catch (err) {
           // Skip if a newer search was started
@@ -119,6 +126,7 @@ export function useSearch(website, options = {}) {
 
           setError(err)
           setResults([])
+          setTotal(null)
           setIsLoading(false)
           resolve([])
         }
@@ -136,6 +144,7 @@ export function useSearch(website, options = {}) {
     }
     pendingRef.current = null
     setResults([])
+    setTotal(null)
     setLastQuery('')
     setError(null)
     setIsLoading(false)
@@ -156,6 +165,10 @@ export function useSearch(website, options = {}) {
   return {
     // State
     results,
+    // How many matched before `limit` — the 47 in "showing 10 of 47".
+    // `null` means the active provider cannot say, which is a normal state and
+    // not an error: render the count conditionally, the results always.
+    total,
     isLoading,
     error,
     lastQuery,

package/src/search/providers/endpoint-provider.js

@@ -149,7 +149,8 @@ export function createEndpointProvider(website, options = {}) {
         )
       }
 
-      const results = extractResults(await response.json()).map(normalize)
+      const payload = await response.json()
+      const results = extractResults(payload).map(normalize)
 
       // Filters are applied client-side because they are not part of the wire
       // contract a third-party endpoint is expected to honor. A server that
@@ -158,7 +159,23 @@ export function createEndpointProvider(website, options = {}) {
       if (type) filtered = filtered.filter(r => r.type === type)
       if (route) filtered = filtered.filter(r => r.route?.startsWith(route))
 
-      return filtered.slice(0, limit)
+      // How many matched, when the endpoint says. Null when it does not, and
+      // null is a real answer — see `total` in client.js.
+      //
+      // ⚠️ Discarded when a local filter removed anything, because then the
+      // server counted a DIFFERENT set: it does not know about `type`/`route`,
+      // so its number describes matches we just narrowed away. Reporting it
+      // would render "showing 3 of 47" beside a filter that produced the 3 —
+      // a number that is not wrong about anything the reader can see, which is
+      // the worst kind. We cannot recompute it either: what arrived was already
+      // capped at `limit`, so the filtered count is a floor, not a total.
+      const narrowed = filtered.length !== results.length
+      const stated = Number.isInteger(payload?.total) ? payload.total : null
+
+      return {
+        results: filtered.slice(0, limit),
+        total: narrowed ? null : stated
+      }
     },
 
     // Nothing to warm: there is no index to download. Defined so every provider

package/src/search/providers/index-provider.js

@@ -342,7 +342,13 @@ export function createIndexProvider(website, options = {}) {
         .sort((a, b) => a.tier - b.tier || a.i - b.i)
         .map(({ r }) => r)
 
-      return results.slice(0, limit).map(({ item, matches }) => {
+      // Exact here, unlike the endpoint provider: the whole corpus is local, so
+      // this counts every match after filtering and before the cut — the number
+      // a "showing 10 of 47" needs, and 47 is knowable only on this side of the
+      // slice.
+      const total = results.length
+
+      const page = results.slice(0, limit).map(({ item, matches }) => {
         const snippet = buildSnippet(item.content, matches, { key: 'content' })
 
         return {
@@ -363,6 +369,8 @@ export function createIndexProvider(website, options = {}) {
           matches
         }
       })
+
+      return { results: page, total }
     },
 
     async preload() {

package/src/utils/submitForm.js

@@ -32,7 +32,10 @@
  *                                                   when omitted
  * @param {object} [args.context]                  — where the submission came from:
  *                                                   formId, sectionType, sectionId,
- *                                                   pageId, pageLabel
+ *                                                   pageId, pageLabel. `formId` is
+ *                                                   sent at the top level of the
+ *                                                   body; the rest ride in
+ *                                                   `metadata` (see below)
  * @param {string} [args.verificationToken]        — bot-protection token, when the
  *                                                   endpoint verifies one
  * @param {Array<File|{file:File,field?:string}>} [args.files]
@@ -95,10 +98,20 @@ export async function submitForm({
       }))
     : fileSlots
 
+  // `formId` rides at the TOP LEVEL, not inside `metadata` with the rest of the
+  // context. It is the only part of a submission's origin an endpoint stores as
+  // its own field rather than in an opaque blob, because it is what submissions
+  // are grouped BY — every other origin key is decoration read back for display.
+  // Nesting it means the endpoint's own column is never filled, and nothing on
+  // either side reports that: the value is present, one level down, and the
+  // column is simply null forever.
+  const { formId, ...origin } = context || {}
+
   // ── API name → wire name. See the header before "correcting" these. ──
   const body = {
     formData,
-    metadata: { ...context, preview: summary || deriveSummary(formData) },
+    ...(formId ? { formId } : {}),
+    metadata: { ...origin, preview: summary || deriveSummary(formData) },
     ...(verificationToken ? { turnstileToken: verificationToken } : {}),
     ...(Array.isArray(slots) && slots.length ? { fileSlots: slots } : {}),
   }
@@ -126,6 +139,35 @@ export async function submitForm({
   return { ...result, filesUploaded: entries.length, ...report }
 }
 
+/**
+ * One entry of an endpoint's `uploadUrls`, as a URL.
+ *
+ * Two shapes are in the wild and both mean the same thing: a bare URL string,
+ * or a **record** describing the slot — `{slot, name, uploadUrl}` is what the
+ * endpoint this client is built against actually returns. Reading only the
+ * string form does not degrade, it *breaks*: a record is truthy, so it was used
+ * as the URL directly and `fetch` stringified it to `[object Object]`, turning
+ * every upload into a request for a path that cannot exist. The submission row
+ * was already written by then, so the visitor's message arrived and their files
+ * did not.
+ *
+ * Anything that does not yield a non-empty string returns `''`, so the caller
+ * falls back to the documented `{target}/upload` — which is where the bytes were
+ * going anyway in every deployment seen so far.
+ *
+ * @param {*} entry
+ * @returns {string}
+ */
+function readUploadUrl(entry) {
+  if (typeof entry === 'string') return entry.trim()
+  if (entry && typeof entry === 'object') {
+    for (const key of ['uploadUrl', 'url', 'href']) {
+      if (typeof entry[key] === 'string' && entry[key].trim()) return entry[key].trim()
+    }
+  }
+  return ''
+}
+
 /**
  * Accept either bare `File`s or `{ file, field }` pairs, and drop anything that
  * is not a file. The pair form exists so a submission can say WHICH field an
@@ -176,7 +218,7 @@ async function uploadFiles(entries, result, target, fetchFn) {
   const urls = Array.isArray(result?.uploadUrls) ? result.uploadUrls : []
 
   for (const [slot, { file }] of entries.entries()) {
-    const url = urls[slot] || `${base}/upload`
+    const url = readUploadUrl(urls[slot]) || `${base}/upload`
     let res
     try {
       res = await fetchFn(url, {
@@ -208,11 +250,18 @@ async function uploadFiles(entries, result, target, fetchFn) {
   // count is what a quota or an invoice would otherwise derive from. Sending it
   // costs a few bytes and satisfies the stricter reading of the contract, in
   // which `files` is required and its absence is a malformed call.
-  const manifest = entries.map(({ file }, slot) => ({
+  // Carries `field` for the same reason the create manifest does — which form
+  // control an attachment answers is the difference between a readable
+  // submission and two anonymous blobs. The two manifests describe the same
+  // files and now describe them with the same keys; a receiver that built its
+  // stored record from this one rather than from the create manifest would
+  // otherwise lose the association, silently and only for uploads.
+  const manifest = entries.map(({ file, field }, slot) => ({
     slot,
     name: file.name,
     size: file.size,
     mime: file.type || 'application/octet-stream',
+    ...(field ? { field } : {}),
   }))
 
   const done = await fetchFn(`${base}/finalize`, {