@uniweb/kit 0.8.3 → 0.9.0

package/package.json

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

package/src/hooks/index.js

@@ -1,6 +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'

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/index.js

@@ -54,6 +54,8 @@ export {
   // Layer-3 data hooks — share the DataStore keyspace with Layer 1.
   useFetched,
   useCacheEntry,
+  useEntityDetail,
+  useCollectionQueryable,
   useRouting,
   useActiveRoute,
   useVersion,