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

package/src/hooks/index.js

@@ -37,3 +37,4 @@ export {
 
 // Form submission lifecycle for foundation Form components
 export { useFormSubmit } from './useFormSubmit.js'
+export { useFormValues, valueAt } from './useFormValues.js'

package/src/hooks/useFormValues.js

@@ -0,0 +1,214 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+/**
+ * Hold the values of a form an AUTHOR designed, so a foundation only writes the
+ * part that is actually its own — the controls.
+ *
+ * An authored form arrives as content (a ```` ```yaml:form ```` block at
+ * `content.data.form`), which makes a form-rendering component the inverse of
+ * every other one: it does not declare the fields, it receives them and draws
+ * whatever it is given. Everything between "receive a list of controls" and
+ * "call submit" is then identical in every such component — seeding defaults,
+ * tracking edits, spotting what is still empty, keeping files out of the JSON.
+ * That is undifferentiated boilerplate, and it is what this owns.
+ *
+ * What it deliberately does NOT own is the rendering. Which control a `type`
+ * maps to, how it looks, how an error reads — that is the foundation's design
+ * and its whole reason for existing. Same split as `useCollectionQueryable`:
+ * the kit hands over the metadata and the state, the foundation builds the
+ * controls against them.
+ *
+ * ```jsx
+ * const { controls, values, setValue, missing, formData, files } =
+ *   useFormValues(content.data.form)
+ * const { submit, canSubmit, status } = useFormSubmit({ block })
+ *
+ * {controls.map((c) => (
+ *   <MyControl key={c.path} control={c}
+ *              value={valueAt(values, c.path)}
+ *              onChange={(v) => setValue(c.path, v)} />
+ * ))}
+ *
+ * <button disabled={!canSubmit || missing.length > 0 || status === 'submitting'}
+ *         onClick={() => submit(formData, { files })}>Send</button>
+ * ```
+ *
+ * ## Three returned shapes, because they are three different things
+ *
+ * `values` is what the UI binds to and holds whatever was set, `File` objects
+ * included, so a file input can show its selection. `formData` is what you
+ * submit. They differ for one reason that would otherwise be a silent data-
+ * shaped failure: `submitForm` sends `formData` through `JSON.stringify`, and a
+ * `File` serializes to `{}` — the attachment would appear to have been sent and
+ * would arrive empty. So file controls are **omitted from `formData`** and ride
+ * in `files` instead, each tagged with the control it came from. That tag is
+ * the `{ file, field }` shape `submitForm` accepts precisely so a form with two
+ * file inputs can say which is which; hand-rolled callers pass bare `File`s and
+ * silently lose the attribution.
+ *
+ * ## `missing` is computed, not enforced
+ *
+ * It lists the paths of `required` controls that are still empty. It does not
+ * block anything: whether an incomplete form disables the button, shows a
+ * message, or submits anyway is a design decision. `useFormSubmit` draws the
+ * same line with `canSubmit` / `unavailableReason` — the kit works out the
+ * fact, the foundation decides what it looks like.
+ *
+ * Empty means `undefined`, `null`, `''`, or `[]`. A `false` boolean is a VALUE,
+ * so a required checkbox that is unchecked is not "missing" — "must be ticked"
+ * is a stronger rule than `required` and belongs to the component that knows it
+ * is a consent box.
+ *
+ * ## Both authored shapes
+ *
+ * Accepts a list of controls, and also the older map keyed by control name —
+ * during a transition both exist in content, and a hook that handled one would
+ * be unusable with the other. A map is normalized to a list, taking each key as
+ * the control's `name`.
+ *
+ * @param {Array<object>|object} definition — `content.data.form`
+ * @returns {{
+ *   controls: Array<object>,
+ *   values: object,
+ *   setValue: (path: string, value: unknown) => void,
+ *   reset: () => void,
+ *   missing: string[],
+ *   formData: object,
+ *   files: Array<{ file: File, field: string }>,
+ * }}
+ */
+export function useFormValues(definition) {
+  const controls = useMemo(() => flatten(normalize(definition)), [definition])
+  const initial = useMemo(() => seed(controls), [controls])
+
+  const [values, setValues] = useState(initial)
+
+  // Re-seed when the DEFINITION changes, not on every render. An author editing
+  // the form in the visual app changes it under a mounted component, and values
+  // keyed to controls that no longer exist would linger in the payload.
+  const seededFrom = useRef(initial)
+  useEffect(() => {
+    if (seededFrom.current !== initial) {
+      seededFrom.current = initial
+      setValues(initial)
+    }
+  }, [initial])
+
+  const setValue = useCallback((path, value) => {
+    setValues((prev) => setIn(prev, String(path).split('.'), value))
+  }, [])
+
+  const reset = useCallback(() => setValues(seededFrom.current), [])
+
+  const missing = useMemo(
+    () => controls.filter((c) => c.required && isEmpty(valueAt(values, c.path))).map((c) => c.path),
+    [controls, values],
+  )
+
+  const { formData, files } = useMemo(() => split(controls, values), [controls, values])
+
+  return { controls, values, setValue, reset, missing, formData, files }
+}
+
+/**
+ * Read a value out of the nested `values` by dotted path — the companion of
+ * `setValue`, exported because a component rendering a control needs it and
+ * would otherwise write the same three lines.
+ */
+export function valueAt(values, path) {
+  return String(path)
+    .split('.')
+    .reduce((node, key) => (node == null ? undefined : node[key]), values)
+}
+
+// --- internals ---------------------------------------------------------------
+
+// A list as authored, or the older map keyed by control name.
+function normalize(definition) {
+  if (Array.isArray(definition)) return definition.filter(isRecord)
+  if (isRecord(definition)) {
+    return Object.entries(definition)
+      .filter(([, spec]) => isRecord(spec))
+      .map(([name, spec]) => ({ name, ...spec }))
+  }
+  return []
+}
+
+/**
+ * Depth-first list of every control, each carrying the dotted `path` its value
+ * lives at. A container (`children`) contributes a nested object rather than a
+ * value of its own, which is why `group` is the author-facing spelling of
+ * `object`: a fieldset's answers nest exactly as the type says they do.
+ */
+function flatten(list, prefix = '') {
+  const out = []
+  for (const control of list) {
+    const name = control?.name
+    if (typeof name !== 'string' || !name) continue // unaddressable — cannot hold a value
+    const path = prefix ? `${prefix}.${name}` : name
+    const children = Array.isArray(control.children) ? control.children : null
+    out.push({ ...control, path, isGroup: !!children })
+    if (children) out.push(...flatten(children, path))
+  }
+  return out
+}
+
+function seed(controls) {
+  let out = {}
+  for (const control of controls) {
+    if (control.isGroup) continue // its shape comes from its children
+    if (control.default === undefined) continue
+    out = setIn(out, control.path.split('.'), control.default)
+  }
+  return out
+}
+
+// Immutable nested set; creates the intermediate objects a group needs.
+function setIn(node, [key, ...rest], value) {
+  const base = isRecord(node) ? node : {}
+  if (rest.length === 0) return { ...base, [key]: value }
+  return { ...base, [key]: setIn(base[key], rest, value) }
+}
+
+/**
+ * Split the held values into what is submitted and what is uploaded.
+ *
+ * File controls are omitted from `formData` rather than serialized: they would
+ * become `{}` and report an attachment nobody received. Their attribution is
+ * carried on each file entry's `field`, which is what the endpoint reads.
+ */
+function split(controls, values) {
+  const files = []
+  let formData = {}
+
+  for (const control of controls) {
+    if (control.isGroup) continue
+    const value = valueAt(values, control.path)
+    if (value === undefined) continue
+
+    if (control.type === 'file') {
+      for (const file of [].concat(value).filter(isFile)) {
+        files.push({ file, field: control.path })
+      }
+      continue
+    }
+    formData = setIn(formData, control.path.split('.'), value)
+  }
+
+  return { formData, files }
+}
+
+function isEmpty(value) {
+  if (value === undefined || value === null || value === '') return true
+  return Array.isArray(value) && value.length === 0
+}
+
+function isFile(value) {
+  // Duck-typed rather than `instanceof File`: this runs under SSR and in tests
+  // where the constructor may not exist, and `submitForm` checks the same way.
+  return !!value && typeof value === 'object' && 'name' in value && 'size' in value
+}
+
+function isRecord(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}

package/src/index.js

@@ -89,7 +89,11 @@ export {
   formatShortcut,
   isApplePlatform,
   // Form submission lifecycle for foundation Form components
-  useFormSubmit
+  useFormSubmit,
+  // The state of an AUTHORED form — seeds defaults, tracks edits, keeps Files
+  // out of the JSON payload. The foundation writes the controls and nothing else.
+  useFormValues,
+  valueAt
 } from './hooks/index.js'
 
 // ============================================================================

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