@uniweb/kit 0.12.0 → 0.12.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -44,9 +44,9 @@
     "shiki": "^3.0.0",
     "tailwind-merge": "^3.6.0",
     "temml": "^0.13.2",
-    "@uniweb/semantic-parser": "^1.2.2",
+    "@uniweb/core": "^0.10.0",
     "@uniweb/scene": "^0.1.3",
-    "@uniweb/core": "^0.8.5"
+    "@uniweb/semantic-parser": "^1.2.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/hooks/index.js

@@ -38,3 +38,10 @@ export {
 // Form submission lifecycle for foundation Form components
 export { useFormSubmit } from './useFormSubmit.js'
 export { useFormValues, valueAt } from './useFormValues.js'
+
+// Site tracking — one event stream (`kb/framework/plans/tracking.md`).
+// `block.track(name, data)` is the common case and needs no hook; these cover
+// events with no block in hand, the consent gate, and opt-in scroll reporting.
+export { useTracker } from './useTracker.js'
+export { useTrackingConsent } from './useTrackingConsent.js'
+export { useScrollDepth } from './useScrollDepth.js'

package/src/hooks/useScrollDepth.js

@@ -0,0 +1,97 @@
+/**
+ * useScrollDepth — report how far down the page a visitor got.
+ *
+ * ```jsx
+ * useScrollDepth()                       // 25 / 50 / 75 / 100, once each per page
+ * ```
+ *
+ * ⭐ **Opt-in, and in kit rather than the runtime, on purpose.** The runtime
+ * auto-emits only what requires runtime privilege — a page view needs the
+ * router, so nothing else can emit it. Scroll depth needs nothing but the
+ * window, so it is a foundation's choice and lives where tree-shaking can drop
+ * it for the foundations that never call it.
+ *
+ * *(It previously lived in `@uniweb/runtime` as an unexported, unreachable file
+ * that reported to a metric baked into the transport. The milestones are now an
+ * ordinary event, which is both smaller and more general.)*
+ *
+ * ⛔ **No guard is needed.** With no tracking destination the report is a
+ * silent no-op — but the scroll listener is skipped too, so an unconfigured
+ * site pays nothing for the call.
+ *
+ * @module @uniweb/kit/hooks/useScrollDepth
+ */
+
+import { useEffect, useRef } from 'react'
+import { getUniweb } from '@uniweb/core'
+import { useRouting } from './useRouting.js'
+
+const MILESTONES = [25, 50, 75, 100]
+
+/** @returns {number} 0-100; 100 when the page fits in the viewport */
+function getScrollDepth() {
+  const scrollTop = window.scrollY
+  const docHeight = document.documentElement.scrollHeight - window.innerHeight
+  if (docHeight <= 0) return 100
+  return Math.min(100, Math.round((scrollTop / docHeight) * 100))
+}
+
+/**
+ * @param {Object} [options]
+ * @param {boolean} [options.enabled=true]
+ * @param {number} [options.throttleMs=200]
+ * @param {string} [options.event='scroll_depth'] - override the event name
+ */
+export function useScrollDepth(options = {}) {
+  const { enabled = true, throttleMs = 200, event = 'scroll_depth' } = options
+
+  const lastCheck = useRef(0)
+  const reported = useRef(new Set())
+
+  // ⛔ **Keyed on the path, or "once each per page" is not true.** The milestone
+  // set lives in a ref, so without this the effect runs once at mount and the
+  // set is never cleared again — a second page reports nothing at all. That bites
+  // exactly where this hook is most naturally called: once, in a layout
+  // component, which persists across SPA navigation (`PageRenderer` does not
+  // remount — the router declares a single catch-all route). Calling it in every
+  // section would have hidden the bug and multiplied the events instead.
+  //
+  // ⭐ `pathname` rather than a route object, deliberately: it is the same
+  // boundary `usePageView` emits on, so a `scroll_depth` always pairs with the
+  // `page_view` it belongs to. `useRouting` returns a default location when there
+  // is no Router, so this stays SSG-safe.
+  const { useLocation } = useRouting()
+  const { pathname } = useLocation()
+
+  useEffect(() => {
+    const tracking = getUniweb()?.tracking
+    // Skip the listener entirely when there is nowhere to report — the calls
+    // would be no-ops, but the scroll handler would still run on every frame.
+    if (!enabled || !tracking?.isEnabled?.()) return
+
+    reported.current.clear()
+    // Reset the throttle too: a navigation within the throttle window would
+    // otherwise make the immediate check below return early and miss the fold.
+    lastCheck.current = 0
+
+    const handleScroll = () => {
+      const now = Date.now()
+      if (now - lastCheck.current < throttleMs) return
+      lastCheck.current = now
+
+      const depth = getScrollDepth()
+      for (const milestone of MILESTONES) {
+        if (depth >= milestone && !reported.current.has(milestone)) {
+          reported.current.add(milestone)
+          tracking.track(event, { depth: milestone })
+        }
+      }
+    }
+
+    handleScroll() // a page that fits the viewport is already at 100
+    window.addEventListener('scroll', handleScroll, { passive: true })
+    return () => window.removeEventListener('scroll', handleScroll)
+  }, [enabled, throttleMs, event, pathname])
+}
+
+export default useScrollDepth

package/src/hooks/useTracker.js

@@ -0,0 +1,40 @@
+/**
+ * useTracker — report an event from a foundation component.
+ *
+ * ```jsx
+ * const { track } = useTracker()
+ * <button onClick={() => track('brochure_download', { file: 'specs.pdf' })}>…</button>
+ * ```
+ *
+ * ⛔ **No guard is needed.** A site with no tracking destination is the default
+ * and the majority: the call returns having done nothing, opened no connection
+ * and thrown nothing. Absent is the normal state, not an error — so never wrap
+ * this in a "is tracking on?" check, and never render differently because of it.
+ *
+ * ⭐ **Prefer `block.track(name, data)` when you have a block**, which almost
+ * every section type does. It attaches the section type and the page path for
+ * you. Reach for this hook for events with no block in hand — a site-level
+ * control, a layout element, a modal.
+ *
+ * The event name is yours: the registry is open, and the framework keeps no
+ * list of permitted names. What a host does with an event it does not recognise
+ * is the host's business.
+ *
+ * @module @uniweb/kit/hooks/useTracker
+ */
+
+import { useCallback } from 'react'
+import { getUniweb } from '@uniweb/core'
+
+/**
+ * @returns {{ track: (event: string, data?: object) => void }}
+ */
+export function useTracker() {
+  const track = useCallback((event, data = {}) => {
+    getUniweb()?.tracking?.track(event, data)
+  }, [])
+
+  return { track }
+}
+
+export default useTracker

package/src/hooks/useTrackingConsent.js

@@ -0,0 +1,68 @@
+/**
+ * useTrackingConsent — the visitor's decision, for a consent component to set.
+ *
+ * ```jsx
+ * const { status, grant, deny } = useTrackingConsent()
+ * if (status !== 'pending') return null          // nothing to ask
+ * return <Banner onAccept={grant} onReject={deny} />
+ * ```
+ *
+ * ## ⛔ Why this exists at all
+ *
+ * Tracking used to arrive as a third-party `<script>`, which consent tooling —
+ * banners, browser blockers, CMPs — works by blocking. Emitting from inside the
+ * site's own bundle means **none of that can see it**, so a site that was
+ * compliant by virtue of its banner would silently stop being so, with no
+ * symptom. The framework moved the capability in, so the framework owes the
+ * gate.
+ *
+ * ## Status values
+ *
+ * - `'pending'` — the site declared `tracking: { consent: required }` and nobody
+ *   has answered. Events are **buffered, not sent**; granting flushes them, so
+ *   the views before the click are not lost, and denying discards them. Nothing
+ *   leaves the device before the decision.
+ * - `'granted'` — sending. **This is the default** when a site does not ask for
+ *   a consent gate: declaring a destination is itself the operator's decision,
+ *   and the framework does not presume a jurisdiction on their behalf.
+ * - `'denied'` — nothing is sent and nothing accumulates.
+ *
+ * ⚖️ **Single-owner assumption.** The status is mirrored into component state so
+ * a banner re-renders when it changes; two independent components calling this
+ * will not observe each other's grant. Consent is a one-banner concern, so that
+ * is the intended shape rather than a limitation to design around.
+ *
+ * @module @uniweb/kit/hooks/useTrackingConsent
+ */
+
+import { useCallback, useState } from 'react'
+import { getUniweb } from '@uniweb/core'
+
+function readStatus() {
+  return getUniweb()?.tracking?.consentStatus?.() || 'granted'
+}
+
+/**
+ * @returns {{ status: 'granted'|'denied'|'pending', grant: () => void, deny: () => void }}
+ */
+export function useTrackingConsent() {
+  const [status, setStatus] = useState(readStatus)
+
+  const set = useCallback((granted) => {
+    getUniweb()?.tracking?.setConsent(granted)
+    // Read back rather than assuming. The tracker is the authority on its own
+    // state, and a site that never asked for a gate starts — and stays —
+    // 'granted', so a banner following the pattern above never renders and this
+    // never runs. Recording a decision does not depend on the tracker having
+    // anywhere to send, so the status moves in a framed document too — where
+    // the tracker is disabled and nothing is transmitted either way.
+    setStatus(readStatus())
+  }, [])
+
+  const grant = useCallback(() => set(true), [set])
+  const deny = useCallback(() => set(false), [set])
+
+  return { status, grant, deny }
+}
+
+export default useTrackingConsent

package/src/index.js

@@ -93,7 +93,13 @@ export {
   // 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
+  valueAt,
+  // Site tracking. `block.track(name, data)` is the common case and needs no
+  // hook — these are for events with no block in hand, the consent gate a
+  // banner sets, and opt-in scroll reporting.
+  useTracker,
+  useTrackingConsent,
+  useScrollDepth
 } from './hooks/index.js'
 
 // ============================================================================

package/src/styled/Media/Media.jsx

@@ -186,6 +186,11 @@ function PlayButton({ onClick, className }) {
  * @param {string} [props.className] - Additional CSS classes
  * @param {Function} [props.onProgress] - Progress callback for tracking
  * @param {Object} [props.block] - Block object for event tracking
+ * @param {boolean} [props.track=true] - Report `video_milestone` events to the
+ *   site's tracking destination (requires `block`). On by default because the
+ *   point of the capability is that a foundation should not have to wire it,
+ *   and it is inert on a site with no destination configured. Pass `false` to
+ *   keep video out of the event stream on a site that does track.
  *
  * @example
  * // YouTube video
@@ -239,6 +244,7 @@ export function Media({
   className,
   onProgress,
   block,
+  track = true,
   ...props
 }) {
   const [showVideo, setShowVideo] = useState(!facade)
@@ -263,14 +269,19 @@ export function Media({
   const handleProgress = useCallback((data) => {
     onProgress?.(data)
 
-    // Track via block if available
-    if (block?.trackEvent && typeof window !== 'undefined' && window.uniweb?.analytics?.initialized) {
-      block.trackEvent(`video_milestone_${data.milestone}`, {
-        milestone: `${data.milestone}%`,
-        src: videoSrc
-      })
+    // Report the milestone through the site's tracking destination, if it has
+    // one. `block.track` attaches the section type and page path itself, and is
+    // a silent no-op when nothing is configured — which is the default and the
+    // majority — so no guard belongs here.
+    //
+    // ⭐ The milestone is DATA, not part of the event name. This used to emit
+    // `video_milestone_25` / `_50` / `_75` / `_100`, which makes four names out
+    // of one event and turns any consumer's event dimension into a cardinality
+    // problem. One name, one field.
+    if (track) {
+      block?.track?.('video_milestone', { milestone: data.milestone, src: videoSrc })
     }
-  }, [onProgress, block, videoSrc])
+  }, [onProgress, block, videoSrc, track])
 
   // Render facade (thumbnail with play button)
   if (facade && !showVideo && thumbnailSrc) {

package/src/utils/href.js

@@ -36,6 +36,9 @@
  */
 
 import { isFileUrl } from './url.js'
+// Imported rather than only re-exported: `resolveHref` below calls it, and a
+// bare `export … from` creates no local binding.
+import { applyBasePath } from '@uniweb/core/base-path'
 
 // An <a> tag's href attribute. Captures the prefix, the quote style, and the
 // value, so the replacement can preserve the original quoting.
@@ -48,24 +51,15 @@ const NON_ROUTE_HREF_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i
 /**
  * Prefix a site-root-relative href with the deployment base path.
  *
- * The invariant this encodes — a base is only ever joined to a path that
- * starts at the site root — is the whole point of routing every caller
- * through here. A bare `basePath + href` concatenation produces garbage the
- * moment href turns out to be absolute (`/basehttps://example.com/x`), and
- * whether it is absolute depends on a classification that has been wrong
- * before. Guarding at the join makes the failure impossible rather than
- * unlikely.
- *
- * @param {string} href - Href to prefix
- * @param {string} basePath - Deployment base (no trailing slash), '' for root
- * @returns {string} Href with the base applied, or unchanged if not applicable
+ * ⛔ **Implementation moved to `@uniweb/core/base-path`; edit it there.**
+ * Re-exported here because this is where every caller reaches it and should
+ * keep reaching it. It came down one layer because `@uniweb/core/services`
+ * needs it and **`@uniweb/runtime` does not depend on kit** — so a service
+ * address resolved in the runtime could not have reached this copy. The
+ * invariant it encodes, and why the join is guarded rather than concatenated,
+ * are in the module header there.
  */
-export function applyBasePath(href, basePath) {
-  if (!href || typeof href !== 'string' || !basePath) return href
-  if (!href.startsWith('/') || href.startsWith('//')) return href
-  if (href === basePath || href.startsWith(basePath + '/')) return href // already based
-  return basePath + href
-}
+export { applyBasePath }
 
 /**
  * Translate a route slug and prefix the active locale, when the site is

package/src/utils/services.js

@@ -1,168 +1,27 @@
-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 renders
- * for that 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 omits it, or declares
- * the name with no address. 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.
- *
- * ⛔ **There is deliberately no explanatory string, and there was one — it was
- * a mistake.** Until 2026-08-13 a declining host could supply a `reason` that
- * this module relayed "to the UI verbatim", with an English default
- * (`NO_SERVICE_REASON`) when nothing did. Removed, on two counts:
- *
- *   1. **Wrong audience.** A visitor has no stake in which services an operator
- *      provisioned. "Submissions are not enabled for this site" reports someone's
- *      billing state to the public and reads like a breakage. It is neither — it
- *      is a service that was not bought, and **a generic component is supposed to
- *      be smart about that.**
- *   2. **Wrong language, unfixably.** Sites here are multilingual, or unilingual
- *      and not English. A host-supplied sentence bypasses the site's entire
- *      localization pipeline, and a canned constant in a public package cannot
- *      be translated at all. Any text a visitor should read is *site content*,
- *      which is authored and localized — never a string a service layer invents.
- *
- * ⇒ **`url` is the whole answer, and absence is a rendering decision rather
- * than a message.** No submit endpoint → render no form, or degrade to
- * something that still serves the visitor: a `mailto:` or a number the site
- * already carries in its content. No assistant → render no Ask-AI affordance.
- * Nobody is told why, because nobody visiting needs to know.
- *
- * **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
-
-/**
- * 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`:
+ * Site services — re-export shim.
  *
- *   - **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 implementation moved to `@uniweb/core/services`. Edit it there, not
+ * here.** This file exists so that no foundation's import had to change:
+ * `import { resolveService } from '@uniweb/kit'` is still the way a foundation
+ * reaches it, and still should be.
  *
- * 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.
+ * **Why it moved:** `@uniweb/runtime` resolves a service address itself (for
+ * `tracking`) and **does not depend on `@uniweb/kit`** — only on core and
+ * theming. The alternative was a second resolver with the same job and its own
+ * base-joining rules, which is precisely the defect `@uniweb/core/route-match`
+ * was created to end after one matcher was implemented twice and the copies
+ * diverged by one character.
  *
- * @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.
+ * The full contract — two tiers, site-outranks-host, open registry,
+ * absent-means-absent, and why entitlement and decline strings are deliberately
+ * unmodelled — lives in the module header there.
  *
- * ```js
- * const { url } = resolveService(website, 'submit')
- * if (!url) return null          // no endpoint — render no form, or degrade
- * ```
- *
- * @param {object} website - the active Website
- * @param {string} name - service name, e.g. 'submit' · 'search' · 'assistant'
- * @returns {{ url: string|null, source: 'site'|'host'|null }}
- *   `url` is the whole answer for rendering. `source` says which declaration
- *   answered — a diagnostic, and the thing to check when a host's value appears
- *   not to be taking effect. `'host'` with a null `url` means the host answered
- *   and offered no address; `null` means nothing declared the service at all.
+ * @module @uniweb/kit/utils/services
  */
-export function resolveService(website, name) {
-  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), 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), source: 'host' }
-  }
-
-  // A host may declare the name while offering no address — a decline. It is
-  // still the host answering, which is all a caller can use: any *wording* for
-  // that state would be ours to invent, in one language, for a visitor who has
-  // no stake in it. See the entitlement note above.
-  if (hostDeclaration !== undefined) return { url: null, source: 'host' }
 
-  // 3 — nobody supplied one.
-  return { url: null, source: null }
-}
+export {
+  resolveService,
+  resolveServiceUrl,
+  readServiceOptions
+} from '@uniweb/core/services'