@uniweb/kit 0.8.3 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/kit",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "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.1"
   },
   "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,90 @@
+/**
+ * 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 somewhere — either at a per-record file the
+ * build emits, or at an author-declared API endpoint. This hook fetches
+ * that full record on demand.
+ *
+ * Two source patterns, picked automatically from the collection's
+ * declaration:
+ *
+ *   - Markdown-backed collections (declared with `path:` in site.yml).
+ *     The build emits `/data/<collection>/<slug>.json` per record. The
+ *     hook fetches that path.
+ *
+ *   - API-backed collections (declared with `url:` in site.yml plus a
+ *     `detailUrl:` pattern). The hook substitutes `{slug}` in the
+ *     pattern and fetches that URL.
+ *
+ * On dynamic-route pages the framework routes the singular detail to
+ * the same source automatically (entity-store auto-injection). This
+ * hook is for the elsewhere case — a hover-card preview, a modal that
+ * opens an article body, a related-items strip that wants summaries
+ * everywhere except the one being highlighted.
+ *
+ * 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 { getUniweb } from '@uniweb/core'
+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 look up the collection's
+ *   `detailUrl:` (if declared) or fall back to the static-file default
+ *   `/data/<collection>/<slug>.json`.
+ * @returns {{ data: any, error: string|null, loading: boolean }}
+ */
+export function useEntityDetail(record, options = {}) {
+  const collection = options?.collection
+  const request = buildDetailRequest(record, collection)
+  return useFetched(request)
+}
+
+function buildDetailRequest(record, collection) {
+  const slug = record?.slug
+  if (!slug || !collection) return null
+
+  // Look up the collection's per-record source pattern. Authors with
+  // API-backed collections declare `detailUrl:` in site.yml; markdown
+  // collections leave it null and use the static-file default.
+  const website = getUniweb()?.activeWebsite
+  const collConfig = website?.config?.collections?.[collection]
+  const detailUrl = (collConfig && typeof collConfig.detailUrl === 'string')
+    ? collConfig.detailUrl
+    : null
+
+  if (detailUrl) {
+    // Substitute {slug} into the author-declared pattern and use url:
+    // (the source is remote).
+    const url = detailUrl.replace(/\{slug\}/g, encodeURIComponent(slug))
+    return { url, schema: collection }
+  }
+
+  // Static-file default — the build emitted per-record JSON files.
+  return { path: `/data/${collection}/${slug}.json`, schema: collection }
+}
+
+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,