@uniweb/kit 0.8.2 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "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.6.2"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/hooks/index.js

@@ -1,4 +1,6 @@
 export { useWebsite, default } from './useWebsite.js'
+export { useFetched } from './useFetched.js'
+export { useCacheEntry } from './useCacheEntry.js'
 export { useRouting } from './useRouting.js'
 export { useActiveRoute } from './useActiveRoute.js'
 export { useVersion } from './useVersion.js'
@@ -8,6 +10,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/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,9 @@ export {
 
 export {
   useWebsite,
+  // Layer-3 data hooks — share the DataStore keyspace with Layer 1.
+  useFetched,
+  useCacheEntry,
   useRouting,
   useActiveRoute,
   useVersion,
@@ -71,7 +74,10 @@ export {
   useColorContext,
   useAppearance,
   useThemeColor,
-  useThemeColorVar
+  useThemeColorVar,
+  // Observable state bridges (page.state / website.state)
+  usePageState,
+  useWebsiteState
 } from './hooks/index.js'
 
 // ============================================================================