@uniweb/kit 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Standard component library for Uniweb foundations",
   "type": "module",
   "exports": {
@@ -38,7 +38,7 @@
     "fuse.js": "^7.0.0",
     "shiki": "^3.0.0",
     "tailwind-merge": "^2.6.0",
-    "@uniweb/core": "0.6.1"
+    "@uniweb/core": "0.7.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/hooks/index.js

@@ -1,4 +1,8 @@
 export { useWebsite, default } from './useWebsite.js'
+export { useFetched } from './useFetched.js'
+export { useCacheEntry } from './useCacheEntry.js'
+export { useEntityDetail } from './useEntityDetail.js'
+export { useCollectionQueryable } from './useCollectionQueryable.js'
 export { useRouting } from './useRouting.js'
 export { useActiveRoute } from './useActiveRoute.js'
 export { useVersion } from './useVersion.js'
@@ -8,6 +12,8 @@ export { useAccordion } from './useAccordion.js'
 export { useGridLayout, getGridClasses } from './useGridLayout.js'
 export { useTheme, getThemeClasses, THEMES, THEME_NAMES } from './useTheme.js'
 export { useInView, useIsInView } from './useInView.js'
+export { usePageState } from './usePageState.js'
+export { useWebsiteState } from './useWebsiteState.js'
 
 // Theme data hooks (runtime theme access)
 export {

package/src/hooks/useCacheEntry.js

@@ -0,0 +1,53 @@
+/**
+ * useCacheEntry — read-only observation of a DataStore entry.
+ *
+ * Subscribes to a cache key without triggering a fetch. Returns null
+ * while the entry is absent; `{ data, meta }` once it's populated.
+ * Used for components that want to display data someone else fetched
+ * (e.g., an "articles count" shown in a header while the main page
+ * fetches the collection).
+ *
+ * Pairs with useFetched: useFetched triggers the dispatch and fills
+ * the cache; useCacheEntry reads it. They share the same keyspace.
+ *
+ * @example
+ * function ArticlesCount() {
+ *   const entry = useCacheEntry({ path: '/data/articles.json', schema: 'articles' })
+ *   if (!entry) return null
+ *   return <span>{entry.data.length} articles</span>
+ * }
+ */
+
+import { useEffect, useState } from 'react'
+import { getUniweb, deriveCacheKey } from '@uniweb/core'
+
+/**
+ * @param {Object|null} request - A fetch request spec. Pass null/undefined
+ *   to skip (returns null without subscribing).
+ * @returns {{ data: any, meta?: Object } | null}
+ */
+export function useCacheEntry(request) {
+  const website = getUniweb()?.activeWebsite ?? null
+  const key = request && website ? deriveCacheKey(request) : null
+
+  const [entry, setEntry] = useState(() =>
+    key ? website.dataStore.get(key) : null,
+  )
+
+  useEffect(() => {
+    if (!key || !website) {
+      setEntry(null)
+      return undefined
+    }
+
+    setEntry(website.dataStore.get(key))
+    const unsubscribe = website.dataStore.subscribe(key, () => {
+      setEntry(website.dataStore.get(key))
+    })
+    return unsubscribe
+  }, [key, website])
+
+  return entry
+}
+
+export default useCacheEntry

package/src/hooks/useCollectionQueryable.js

@@ -0,0 +1,74 @@
+/**
+ * useCollectionQueryable — read the queryable-surface metadata for a
+ * collection.
+ *
+ * Authors declare the queryable surface of an entity in `site.yml`:
+ *
+ *   collections:
+ *     members:
+ *       path: collections/members
+ *       queryable:
+ *         department:
+ *           type: enum
+ *           label: Department
+ *           options: [biology, physics, chemistry, geology]
+ *         tenured:
+ *           type: boolean
+ *           label: Tenured
+ *         start_year:
+ *           type: range
+ *           label: Start year
+ *           min: 1800
+ *           max: 2025
+ *
+ * Foundations consume this hook to render filter UIs and compose
+ * where-objects from user interactions. The kit doesn't ship UI
+ * components for the controls (different foundations have different
+ * vocabularies); foundations build their own controls against the
+ * metadata returned here.
+ *
+ * @example
+ * function MemberFilters({ onChange }) {
+ *   const queryable = useCollectionQueryable('members')
+ *   const [values, setValues] = useState({})
+ *   if (!queryable) return null
+ *   return (
+ *     <div>
+ *       {Object.entries(queryable).map(([field, def]) => (
+ *         <FilterControl
+ *           key={field}
+ *           field={field}
+ *           def={def}
+ *           value={values[field]}
+ *           onChange={(v) => {
+ *             const next = { ...values, [field]: v }
+ *             setValues(next)
+ *             onChange(composeWhereObject(next))
+ *           }}
+ *         />
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ *
+ * Returns null when the collection has no `queryable:` declared.
+ *
+ * @param {string} collectionName - Name of the collection to read queryable
+ *   metadata for. Pass null/undefined to skip (returns null).
+ * @returns {Object|null} The queryable metadata object, or null.
+ */
+
+import { getUniweb } from '@uniweb/core'
+
+export function useCollectionQueryable(collectionName) {
+  if (!collectionName) return null
+  const website = getUniweb()?.activeWebsite
+  if (!website) return null
+  const config = website.config?.collections?.[collectionName]
+  if (!config || typeof config !== 'object') return null
+  const queryable = config.queryable
+  if (!queryable || typeof queryable !== 'object') return null
+  return queryable
+}
+
+export default useCollectionQueryable

package/src/hooks/useEntityDetail.js

@@ -0,0 +1,51 @@
+/**
+ * useEntityDetail — fetch the full record for a deferred-field collection.
+ *
+ * When a collection declares `deferred: [...]` in `site.yml`, the cascade
+ * payload omits the deferred fields. The full record (with deferred
+ * fields included) lives in a per-record file at
+ * `/data/<collection>/<slug>.json`. On dynamic-route pages, the framework
+ * routes the singular detail there automatically. Anywhere else (a card
+ * grid that wants to show a hover-card preview, a modal that opens an
+ * article body) — use this hook.
+ *
+ * Returns `{ data, error, loading }` like `useFetched`. Shares the same
+ * cache. Pass null/undefined to skip without subscribing.
+ *
+ * @example
+ * function ArticleCard({ article }) {
+ *   const [open, setOpen] = useState(false)
+ *   const { data: full, loading } = useEntityDetail(open ? article : null, {
+ *     collection: 'articles',
+ *   })
+ *   return (
+ *     <div>
+ *       <h3>{article.title}</h3>
+ *       <p>{article.excerpt}</p>
+ *       <button onClick={() => setOpen(true)}>Read more</button>
+ *       {open && (loading ? <Spinner /> : <ArticleBody html={full.body} />)}
+ *     </div>
+ *   )
+ * }
+ */
+
+import { useFetched } from './useFetched.js'
+
+/**
+ * @param {Object|null} record - A record from a cascade-delivered collection.
+ *   Must have a `slug` field. Pass null/undefined to skip the fetch.
+ * @param {Object} [options]
+ * @param {string} options.collection - The collection name (e.g., 'articles').
+ *   Required when record is non-null. Used to build the per-record file URL
+ *   `/data/<collection>/<slug>.json`.
+ * @returns {{ data: any, error: string|null, loading: boolean }}
+ */
+export function useEntityDetail(record, options = {}) {
+  const collection = options?.collection
+  const request = (record && record.slug && collection)
+    ? { path: `/data/${collection}/${record.slug}.json`, schema: collection }
+    : null
+  return useFetched(request)
+}
+
+export default useEntityDetail

package/src/hooks/useFetched.js

@@ -0,0 +1,115 @@
+/**
+ * useFetched — imperative Layer-3 fetch hook.
+ *
+ * Shares the DataStore keyspace with Layer-1 (`content.data.*`) fetches.
+ * A declarative fetch for the same request warms the cache; this hook
+ * gets a synchronous cache hit on first render.
+ *
+ * Surface is intentionally narrow — no retries, no refetch intervals,
+ * no stale-while-revalidate. If you need those, reach for a
+ * purpose-built library and compose it around your own fetch.
+ *
+ * @example
+ * function ProductCard({ params }) {
+ *   const { data, error, loading } = useFetched({
+ *     url: params.productUrl,
+ *     transform: 'data.product',
+ *   })
+ *   if (loading) return <Skeleton />
+ *   if (error) return <Error message={error} />
+ *   return <Product {...data} />
+ * }
+ */
+
+import { useEffect, useState } from 'react'
+import { getUniweb, deriveCacheKey } from '@uniweb/core'
+
+function emptyState() {
+  return { data: null, error: null, loading: false }
+}
+
+function loadingState() {
+  return { data: null, error: null, loading: true }
+}
+
+function readyState(data) {
+  return { data, error: null, loading: false }
+}
+
+function errorState(error, data = null) {
+  return { data, error, loading: false }
+}
+
+/**
+ * @param {Object|null} request - A fetch request spec (path / url / schema / ...).
+ *   Pass null/undefined to skip — the hook returns `{ data: null, error: null,
+ *   loading: false }` without subscribing or dispatching.
+ * @returns {{ data: any, error: string|null, loading: boolean }}
+ */
+export function useFetched(request) {
+  const website = getUniweb()?.activeWebsite ?? null
+
+  // Cache key is also the React dep. Serialized JSON so prop-identity-
+  // changes that don't affect the key don't re-run the effect.
+  const key = request && website ? deriveCacheKey(request) : null
+
+  // Synchronous hit on first render.
+  const initial = key ? website.dataStore.get(key) : null
+  const [state, setState] = useState(() =>
+    initial ? readyState(initial.data) : (key ? loadingState() : emptyState()),
+  )
+
+  useEffect(() => {
+    if (!key || !website) {
+      setState(emptyState())
+      return undefined
+    }
+
+    // Re-check cache after mount: the key may have changed between
+    // render and effect, or a parallel Layer-1 fetch may have landed.
+    const cached = website.dataStore.get(key)
+    if (cached) {
+      setState(readyState(cached.data))
+    } else {
+      setState(loadingState())
+    }
+
+    // Subscribe first so a concurrent Layer-1 fetch's cache write
+    // wakes this hook even if our own dispatch is still in flight.
+    const unsubscribe = website.dataStore.subscribe(key, () => {
+      const entry = website.dataStore.get(key)
+      if (entry) setState(readyState(entry.data))
+    })
+
+    const controller = new AbortController()
+    website.fetcher
+      .dispatch(request, { website, signal: controller.signal })
+      .then((result) => {
+        if (controller.signal.aborted) return
+        if (result?.error) {
+          setState(errorState(result.error, result.data ?? null))
+          return
+        }
+        // Successful results typically arrive via the subscription (the
+        // dispatcher writes to cache and fires listeners). Fall through
+        // here to handle cached-hit and null-data paths so a useFetched
+        // caller never sits in `loading: true` when dispatch returns.
+        if (result && 'data' in result) {
+          setState(readyState(result.data))
+        }
+      })
+      .catch((err) => {
+        if (controller.signal.aborted) return
+        setState(errorState(String(err?.message || err)))
+      })
+
+    return () => {
+      controller.abort()
+      unsubscribe()
+    }
+  }, [key, website])
+
+  return state
+}
+
+export default useFetched

package/src/hooks/usePageState.js

@@ -0,0 +1,52 @@
+/**
+ * usePageState — React bridge into the active page's ObservableState.
+ *
+ * Reads `page.state.get(key)` on render and subscribes to changes so
+ * React re-renders when the value flips. The setter writes back through
+ * `page.state.set(key, value)` — one source of truth, readable from
+ * outside React (the fetcher, sibling components, persistence helpers).
+ *
+ * Scope: the *active* page's state. Navigating to a different page
+ * swaps the observed scope; the new page's state is read instead.
+ * That's usually what foundations want (filters don't carry across
+ * pages). For site-wide state use `useWebsiteState`.
+ *
+ * @param {string} key - The key on page.state.
+ * @param {*} [defaultValue] - Returned when the key has never been set.
+ * @returns {[any, (value: any) => void]} [value, setValue]
+ *
+ * @example
+ *   const [slug, setSlug] = usePageState('selectedQuery', 'all')
+ *   return <select value={slug} onChange={e => setSlug(e.target.value)}>{...}</select>
+ */
+
+import { useEffect, useReducer } from 'react'
+import { useWebsite } from './useWebsite.js'
+
+function forceTick(n) {
+  return n + 1
+}
+
+export function usePageState(key, defaultValue) {
+  const { website } = useWebsite()
+  const [, tick] = useReducer(forceTick, 0)
+
+  const page = website.activePage
+  const state = page?.state
+
+  useEffect(() => {
+    if (!state) return
+    return state.subscribe(key, tick)
+  }, [state, key])
+
+  const value = state?.has(key) ? state.get(key) : defaultValue
+
+  const setValue = (next) => {
+    if (!state) return
+    state.set(key, typeof next === 'function' ? next(value) : next)
+  }
+
+  return [value, setValue]
+}
+
+export default usePageState

package/src/hooks/useWebsiteState.js

@@ -0,0 +1,44 @@
+/**
+ * useWebsiteState — React bridge into the Website's ObservableState.
+ *
+ * Sibling of `usePageState` but scoped site-wide rather than per-page.
+ * Typical uses: active appearance ('light'/'dark'/'system'), authenticated
+ * user, cross-page selections (a filter chosen on /search that other
+ * pages honor).
+ *
+ * Same contract: reads on render, subscribes to the keyed slot, re-renders
+ * when the value changes, writes via `website.state.set(key, value)`.
+ *
+ * @param {string} key
+ * @param {*} [defaultValue]
+ * @returns {[any, (value: any) => void]}
+ */
+
+import { useEffect, useReducer } from 'react'
+import { useWebsite } from './useWebsite.js'
+
+function forceTick(n) {
+  return n + 1
+}
+
+export function useWebsiteState(key, defaultValue) {
+  const { website } = useWebsite()
+  const [, tick] = useReducer(forceTick, 0)
+  const state = website?.state
+
+  useEffect(() => {
+    if (!state) return
+    return state.subscribe(key, tick)
+  }, [state, key])
+
+  const value = state?.has(key) ? state.get(key) : defaultValue
+
+  const setValue = (next) => {
+    if (!state) return
+    state.set(key, typeof next === 'function' ? next(value) : next)
+  }
+
+  return [value, setValue]
+}
+
+export default useWebsiteState

package/src/index.js

@@ -51,6 +51,11 @@ export {
 
 export {
   useWebsite,
+  // Layer-3 data hooks — share the DataStore keyspace with Layer 1.
+  useFetched,
+  useCacheEntry,
+  useEntityDetail,
+  useCollectionQueryable,
   useRouting,
   useActiveRoute,
   useVersion,
@@ -71,7 +76,10 @@ export {
   useColorContext,
   useAppearance,
   useThemeColor,
-  useThemeColorVar
+  useThemeColorVar,
+  // Observable state bridges (page.state / website.state)
+  usePageState,
+  useWebsiteState
 } from './hooks/index.js'
 
 // ============================================================================