@uniweb/kit 0.10.14 → 0.10.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.10.14",
+  "version": "0.10.16",
   "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/core": "0.8.2",
     "@uniweb/scene": "0.1.2",
-    "@uniweb/core": "0.8.2"
+    "@uniweb/semantic-parser": "1.2.1"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/index.js

@@ -126,7 +126,11 @@ export {
   submitForm,
   deriveSummary,
   resolveSubmitTarget,
-  NO_SUBMIT_TARGET_REASON
+  NO_SUBMIT_TARGET_REASON,
+  // Site services (search / submit / assistant / anything a host offers)
+  resolveService,
+  resolveServiceUrl,
+  NO_SERVICE_REASON
 } from './utils/index.js'
 
 // ============================================================================

package/src/search/client.js

@@ -28,6 +28,7 @@
  */
 
 import { emptyResult } from './providers/result.js'
+import { resolveService } from '../utils/services.js'
 
 // Re-exported so existing importers of these keep working; they live with the
 // provider that owns them now.
@@ -92,7 +93,24 @@ export function createSearchClient(website, options = {}) {
   } = options
 
   const searchConfig = website.getSearchConfig?.() || {}
-  const declared = providerOverride || searchConfig.provider || 'index'
+
+  // Where search is answered: the site's own `search.endpoint`, else the host's
+  // `services.search`, else nothing. Same rule every site service resolves by.
+  const service = resolveService(website, 'search')
+
+  // The AUTHORED provider, read from config rather than from getSearchConfig(),
+  // which fills in 'index' before kit sees it (core/website.js). That default
+  // would make "the author chose index" and "the author said nothing"
+  // indistinguishable — and the difference is precisely what decides whether a
+  // host's offer applies. An author who picked a provider means it; one who
+  // picked nothing gets whatever the host serves, and the local index if the
+  // host serves none.
+  const authoredProvider = website?.config?.search?.provider
+
+  const declared =
+    providerOverride ||
+    authoredProvider ||
+    (service.source === 'host' ? 'endpoint' : 'index')
 
   // One in-flight resolution shared by every caller.
   let providerPromise = null
@@ -115,7 +133,14 @@ export function createSearchClient(website, options = {}) {
         activeName = 'index'
       }
 
-      return factory(website, { ...providerOptions, endpoint: searchConfig.endpoint })
+      // `service.url` is already joined to the base; the endpoint provider
+      // joins again, which is a no-op because the join is idempotent. Falls
+      // back to the raw authored value, and to the provider's own default when
+      // an author selects `endpoint` without naming one.
+      return factory(website, {
+        ...providerOptions,
+        endpoint: service.url || searchConfig.endpoint,
+      })
     })()
 
     return providerPromise

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

@@ -14,6 +14,7 @@
  */
 
 import { emptyResult } from './result.js'
+import { resolveServiceUrl } from '../../utils/services.js'
 
 /** Path used when a site declares `provider: endpoint` without an `endpoint:`. */
 const DEFAULT_ENDPOINT = '_search'
@@ -31,17 +32,17 @@ const DEFAULT_ENDPOINT = '_search'
  * An absolute URL is passed through untouched, for a search service on another
  * origin.
  *
+ * The join itself is the shared one every site service uses — this function is
+ * now only the *default*, which is the one thing search has that the others must
+ * not: a form submission with no declared target has nowhere to go, whereas
+ * search with no declared endpoint has a conventional one.
+ *
  * @param {string} endpoint - Declared endpoint (relative or absolute)
  * @param {string} basePath - `website.basePath`, normalized without a trailing slash
  * @returns {string}
  */
 export function resolveEndpointUrl(endpoint, basePath = '') {
-  const path = endpoint || DEFAULT_ENDPOINT
-  if (/^https?:\/\//i.test(path)) return path
-
-  const base = (basePath || '').replace(/\/+$/, '')
-  const rel = path.replace(/^\/+/, '')
-  return `${base}/${rel}`
+  return resolveServiceUrl(endpoint || DEFAULT_ENDPOINT, basePath)
 }
 
 /**

package/src/utils/index.js

@@ -249,6 +249,7 @@ export function detectMediaType(url) {
 
 export { submitForm, deriveSummary } from './submitForm.js'
 export { resolveSubmitTarget, NO_SUBMIT_TARGET_REASON } from './submitTarget.js'
+export { resolveService, resolveServiceUrl, NO_SERVICE_REASON } from './services.js'
 
 /**
  * The text of a ProseMirror node, flattened.

package/src/utils/services.js

@@ -0,0 +1,148 @@
+import { applyBasePath } from './href.js'
+
+/**
+ * Site services — where a site's search, form submissions, assistant, or
+ * anything else of that shape actually go.
+ *
+ * ## The one idea
+ *
+ * A component must never name a host. Whether this site's search is answered by
+ * a prebuilt index, a server endpoint, or a vendor API is a *deployment* fact,
+ * and a foundation that hardcodes it is coupled to one deployment. So the
+ * address comes from configuration, and there are exactly two places it can
+ * come from:
+ *
+ *   1. **The site**, authored — `search:`, `submit:`, `assistant:` in site.yml.
+ *      The operator's own declaration, and it wins.
+ *   2. **The host**, served — `config.services.<name>` in the payload. What the
+ *      deployment offers, which the site never had to know about.
+ *
+ * Absent from both means the site has no such service, and the component says so
+ * rather than guessing an address. That is the same rule for every service, and
+ * it is why this module exists: it was previously implemented three times — the
+ * search provider, the submit resolver, and a hand-rolled copy inside a
+ * foundation — with three slightly different base-joining rules between them.
+ *
+ * ## The registry is open, not an enum
+ *
+ * `resolveService(website, name)` takes a *name*, and the framework has no list
+ * of permitted ones. It ships **clients** only for what it already implements
+ * (search, form submission); it ships **resolution** for anything. A foundation
+ * that invents `assistant`, `booking` or `translate` gets the same precedence,
+ * the same base handling and the same absent-means-absent behaviour, and a host
+ * can fill the slot without a framework change.
+ *
+ * This is deliberate and it is the same shape as `fetcher.transports`: the
+ * framework owns the seam, not the catalogue.
+ *
+ * ## What this deliberately does not model
+ *
+ * **Entitlement.** A host that will not serve a service either omits it or
+ * supplies a `reason`, which is relayed to the UI verbatim. The framework never
+ * learns why — no plan names, no tiers, no "paid" anywhere. That is not
+ * squeamishness: `@uniweb/kit` is public, and a framework that encodes which
+ * capabilities cost money ships the business model into open source.
+ *
+ * **The site's own base.** `config.base` is where the site *lives*, not a
+ * service it consumes — it is load-bearing for routing and asset URLs too. It
+ * stays where it is and is an input here, not an entry.
+ */
+
+/** Anything with a scheme, or protocol-relative — never joined to a base. */
+const ABSOLUTE_URL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i
+
+/** Shown when nothing supplies a service and the caller gives no wording. */
+export const NO_SERVICE_REASON = 'This site has no such service configured.'
+
+/**
+ * Read an endpoint out of either declaration form.
+ *
+ * A site may write the shorthand (`submit: /forms`) or the object
+ * (`submit: { endpoint: /forms }`); a host emits JSON and normally writes the
+ * object. Both are accepted from both sides — one reader, no per-side rules to
+ * remember.
+ *
+ * @param {*} declaration
+ * @returns {string} the endpoint, or '' when there is none
+ */
+function readEndpoint(declaration) {
+  if (typeof declaration === 'string') return declaration.trim()
+  if (typeof declaration?.endpoint === 'string') return declaration.endpoint.trim()
+  return ''
+}
+
+/**
+ * Join a service endpoint to the site's base path.
+ *
+ * Three cases, and the middle one is why this is not simply `applyBasePath`:
+ *
+ *   - **Absolute** (`https://…`, `//host/…`, any scheme) — passed through. A
+ *     service on another origin is not the site's to relocate.
+ *   - **Bare relative** (`_search`) — rooted first. This spelling is documented
+ *     and in use, and `applyBasePath` alone would leave it untouched, silently
+ *     producing a request relative to whatever page the visitor is on.
+ *   - **Root-relative** (`/forms`) — the ordinary case.
+ *
+ * The join itself goes through `applyBasePath` rather than concatenation,
+ * because that is where the invariant "a base is only ever joined to a path that
+ * starts at the site root" is enforced, and it is idempotent — an
+ * already-based path is not based twice.
+ *
+ * @param {string} endpoint
+ * @param {string} [basePath] - `website.basePath`
+ * @returns {string}
+ */
+export function resolveServiceUrl(endpoint, basePath = '') {
+  if (!endpoint) return ''
+  if (ABSOLUTE_URL_RE.test(endpoint)) return endpoint
+
+  const rooted = endpoint.startsWith('/') ? endpoint : `/${endpoint}`
+  // `applyBasePath` concatenates and documents its input as carrying no
+  // trailing slash, so normalizing is the caller's job — skip it and
+  // `base: /docs/` yields `/docs//forms`.
+  const base = (basePath || '').replace(/\/+$/, '')
+  return applyBasePath(rooted, base)
+}
+
+/**
+ * Resolve where a named service lives for this site.
+ *
+ * ```js
+ * const { url, reason } = resolveService(website, 'submit')
+ * if (!url) return renderDisabled(reason)
+ * ```
+ *
+ * @param {object} website - the active Website
+ * @param {string} name - service name, e.g. 'submit' · 'search' · 'assistant'
+ * @param {object} [options]
+ * @param {string} [options.reason] - wording when nothing supplies it
+ * @returns {{ url: string|null, reason: string|null, source: 'site'|'host'|null }}
+ *   `source` says which declaration answered — useful in diagnostics, and the
+ *   thing to check when a host's value appears not to be taking effect.
+ */
+export function resolveService(website, name, options = {}) {
+  const config = website?.config
+  const basePath = website?.basePath
+
+  // 1 — the site's own declaration wins. An operator who named an endpoint
+  // means it, including on a host that offers one.
+  const authored = readEndpoint(config?.[name])
+  if (authored) {
+    return { url: resolveServiceUrl(authored, basePath), reason: null, source: 'site' }
+  }
+
+  // 2 — what the host says it offers.
+  const hostDeclaration = config?.services?.[name]
+  const hostEndpoint = readEndpoint(hostDeclaration)
+  if (hostEndpoint) {
+    return { url: resolveServiceUrl(hostEndpoint, basePath), reason: null, source: 'host' }
+  }
+
+  // A host that declines may say why, and that reaches the visitor unaltered.
+  const hostReason =
+    typeof hostDeclaration?.reason === 'string' ? hostDeclaration.reason.trim() : ''
+  if (hostReason) return { url: null, reason: hostReason, source: 'host' }
+
+  // 3 — nobody supplied one.
+  return { url: null, reason: options.reason || NO_SERVICE_REASON, source: null }
+}

package/src/utils/submitTarget.js

@@ -1,38 +1,21 @@
+import { resolveService, resolveServiceUrl } from './services.js'
+
 /**
- * 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
+ * Where this site's form submissions go.
  *
- * 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.
+ * A thin naming of the general rule in `./services.js` — a site declares
+ * `submit:` in site.yml, a host may offer one under `config.services.submit`,
+ * and absent from both means the form renders disabled rather than posting a
+ * visitor's answers to an address nobody claimed.
  *
- * ## Precedence — and why the framework never picks one itself
+ * ## There is deliberately no default
  *
- * 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.
+ * The framework does not know where a given site can accept a submission, and
+ * picking a path on the site's behalf is worse than having none: on a static
+ * host, or any deployment with nothing listening, the form POSTs 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
@@ -41,17 +24,17 @@
  *
  * ## 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
+ * The bundle lane spreads all of site.yml into the payload config, so writing a
+ * `services:` block in site.yml exercises the host tier 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
+ * explicit allowlist and does not carry `services`, 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.
+ * Shown when a site declares no endpoint and no host offers one. 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.'
@@ -60,65 +43,24 @@ export const NO_SUBMIT_TARGET_REASON =
  * 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.
+ * @returns {{ url: string|null, reason: string|null, source: 'site'|'host'|null }}
+ *   `url` is the resolved endpoint, or null when nothing supplies one. `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 }
+  return resolveService(website, 'submit', { reason: NO_SUBMIT_TARGET_REASON })
 }
 
 /**
- * Join a declared endpoint to the site's base path.
+ * Join an 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.
+ * Retained as a named export because it shipped as one. Prefer
+ * `resolveServiceUrl` from `./services.js` — this is that function.
  *
  * @param {string} endpoint - Declared endpoint, relative or absolute
- * @param {string} [basePath] - `website.basePath`, normalized without a trailing slash
+ * @param {string} [basePath] - `website.basePath`
  * @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}`
+  return resolveServiceUrl(endpoint, basePath)
 }