@uniweb/api 0.6.0 → 0.6.2

package/README.md

@@ -96,11 +96,18 @@ full (`limit`, default 50); `matched` counts the records in this answer, not a t
 
 ```jsx
 const { status, entity } = useEntity({ schema: '@acme/lesson', uuid, via: course.uuid })
-// entity.hydrated.items — the content: { id, section_id, data, … } each
+// entity.hydrated.items — the content: { id, section, section_id, data, … } each
 // entity.hydrated.entity.brief — the summary
 // entity.can_edit — whether this viewer may write to it
+
+const sessions = entity.hydrated.items.filter((item) => item.section === 'sessions')
 ```
 
+`item.section` is the section's name, the word a write takes (`parent/child` for a nested
+section). The package resolves it from the Model's definition, so a component never
+handles a section id. `item.id` is what `useEntityWriter` takes to update, move or remove
+the item.
+
 Its `absent` covers both not-found and not-permitted, on purpose: render your paywall
 or sign-in prompt on it and never say "deleted".
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "The client for a Uniweb site's own backend — session, records, entities — imported by a foundation the way it imports @uniweb/kit.",
   "type": "module",
   "exports": {

package/src/client.js

@@ -103,6 +103,32 @@ function viewerWorkspace(ws) {
   return Object.freeze({ unitUuid: ws.unit_uuid ?? null, handle: ws.handle ?? null })
 }
 
+/**
+ * Label each item with its section's NAME — `section`, the word a write takes — from
+ * a Model's sections (`ApiClient.sections`): `sessions`, or `parent/child` for a
+ * nested section. An item whose section the definition does not name stays as it is.
+ *
+ * @param {object[]|undefined} items - `hydrated.items`, labelled in place
+ * @param {Array<{ id: number, name: string, parent: number|null }>|null} sections
+ */
+function labelSections(items, sections) {
+  if (!Array.isArray(items) || !Array.isArray(sections) || !sections.length) return
+  const byId = new Map(sections.map((s) => [s.id, s]))
+  const pathOf = (section) => {
+    const names = []
+    const seen = new Set()
+    for (let at = section; at && !seen.has(at.id); at = byId.get(at.parent)) {
+      seen.add(at.id)
+      names.unshift(at.name)
+    }
+    return names.join('/')
+  }
+  for (const item of items) {
+    const section = item && byId.get(item[READ.itemSection])
+    if (section) item[CREATE.sectionName] = pathOf(section)
+  }
+}
+
 export class ApiClient {
   /**
    * @param {object} uniweb - the page's `Uniweb` singleton
@@ -539,6 +565,13 @@ export class ApiClient {
    * and `hydrated.entity.brief` is its summary. `can_edit` is the write gate's
    * own answer for this viewer.
    *
+   * ⭐ **Each item also carries `section`, its section's NAME** — `sessions`, or a
+   * `parent/child` path for a nested one — the word a write takes, so a component
+   * never meets a section id in either direction. It is this package's label, not
+   * the backend's: resolved from the Model's definition, read beside the entity
+   * (once per viewer, and kept). When the definition cannot be read, items carry
+   * no `section` and the read still succeeds.
+   *
    * ⭐ **The read seeds the concurrency ledger** with each item's `updated_at`, so
    * the first edit of an item is guarded by the version the viewer was shown.
    *
@@ -558,11 +591,18 @@ export class ApiClient {
     if (!schema) throw ApiError.invalid('No Model', 'readEntity needs a schema — the backend reads an entity by its Model')
     const mark = this.ledger.mark()
     try {
-      const entity = await this.request('GET', ROUTES.read(uuid), {
-        query: { [PARAM.model]: schema, [PARAM.via]: via, ...this._localeQuery() },
-        signal,
-      })
-      this.ledger.observe(entity?.[READ.hydrated]?.[READ.items], mark)
+      const [entity, sections] = await Promise.all([
+        this.request('GET', ROUTES.read(uuid), {
+          query: { [PARAM.model]: schema, [PARAM.via]: via, ...this._localeQuery() },
+          signal,
+        }),
+        // A label, not a condition of the read: a definition this viewer cannot read
+        // leaves the items unlabelled.
+        this.sections(schema, signal).catch(() => null),
+      ])
+      const items = entity?.[READ.hydrated]?.[READ.items]
+      this.ledger.observe(items, mark)
+      labelSections(items, sections)
       return { status: 'ready', entity }
     } catch (err) {
       if (err instanceof ApiError && err.kind === 'absent') return { status: 'absent', entity: null }
@@ -651,9 +691,11 @@ export class ApiClient {
    * section names; the item route after it takes ids, and ids differ from one
    * backend to the next. So a name is resolved here, from the Model's definition.
    *
-   * ⚠️ The definition is readable for the Models the viewer may create, and by the
-   * site's operator. Anywhere else this cannot resolve a name, and says so — pass
-   * the section's numeric id instead (an item's `section_id` on a read).
+   * ⚠️ The definition is readable by any signed-in viewer — Models are open, so every
+   * Model is one they may create (2026-09-23; until then only the Models a viewer
+   * could create, and the operator). Where it cannot be read this cannot resolve a
+   * name, and says so — pass the section's numeric id instead (an item's
+   * `section_id` on a read).
    *
    * @param {string} schema
    * @param {string|number} section - a name, a `parent/child` path, or an id

package/src/hooks/useEntity.js

@@ -16,8 +16,10 @@ const DISABLED = Object.freeze({ status: 'absent', entity: null, error: null })
  * ```
  *
  * The entity is the backend's answer: `entity.hydrated.items` is its content —
- * `{ id, section_id, data, … }` each — `entity.hydrated.entity.brief` its summary,
- * and `entity.can_edit` whether this viewer may write to it.
+ * `{ id, section, section_id, data, … }` each, `section` being the section's NAME
+ * (the word a write takes; this package's label, see `readEntity`) —
+ * `entity.hydrated.entity.brief` its summary, and `entity.can_edit` whether this
+ * viewer may write to it.
  *
  * Cached in the site's data store under a key scoped to the viewer, so a
  * sign-in or sign-out changes the key and the record is read again for who

package/src/mock/store.js

@@ -85,8 +85,21 @@ function canonical(value) {
 const isMulti = (section) => section?.multiple === true || section?.kind === 'multi'
 const shortName = (model) => String(model).split('/').pop() || String(model)
 
-/** A `{ locale: value }` map — a plain object, never an array (a localized list's value). */
-const isLocaleMap = (value) => value != null && typeof value === 'object' && !Array.isArray(value)
+/**
+ * A `{ locale: value }` map — a plain object, never an array (a localized list's
+ * value), and never the value of a field whose OWN type is an object.
+ *
+ * ⛔ A `json` field's value is a plain object too — a richtext body is a ProseMirror
+ * document — and read as a map it has no `en`, so the body was DELETED from every
+ * read that carried `?locale=`, which the client sends on every browser read.
+ * Measured 2026-09-24 on a lesson whose `content` section became declared. The
+ * write checker (`schema-shape.js`) takes any object in such a field as THE value,
+ * so the projection reads it the same way: for these types the map shape is not
+ * knowable, and a value is a value.
+ */
+const OBJECT_TYPED = new Set(['json', 'object', 'group'])
+const isLocaleMap = (field, value) =>
+  value != null && typeof value === 'object' && !Array.isArray(value) && !OBJECT_TYPED.has(field?.type)
 
 export class MockStore {
   /**
@@ -497,13 +510,14 @@ export class MockStore {
    * an array, and an array is a value, not a map of them: read as a map it has no
    * `en`, and the field was DELETED from every read that carried `?locale=` — which
    * the client sends on every browser read. Measured 2026-09-22 on a course brief
-   * whose `outcomes` vanished, and on quiz questions whose `options` did.
+   * whose `outcomes` vanished, and on quiz questions whose `options` did. The same
+   * for a `json` field's document (`isLocaleMap`), measured 2026-09-24.
    */
   project(data, section, locales) {
     if (!locales?.length || !section?.fields || !data || typeof data !== 'object') return data
     const out = { ...data }
     for (const [key, field] of Object.entries(section.fields)) {
-      if (!field?.localized || !isLocaleMap(out[key])) continue
+      if (!field?.localized || !isLocaleMap(field, out[key])) continue
       const hit = locales.find((l) => out[key][l] != null)
       if (hit) out[key] = out[key][hit]
       else delete out[key]