@uniweb/kit 0.10.21 → 0.10.22

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.22",
   "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/core": "0.8.2",
     "@uniweb/semantic-parser": "1.2.1",
-    "@uniweb/scene": "0.1.3",
-    "@uniweb/core": "0.8.2"
+    "@uniweb/scene": "0.1.3"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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() {