feat(docs-site): render a field's view.* subtypes + their attrs (#177)

Object pages now show each field's presentation view children (view.currency /
view.badge / view.meter / view.duration / …) and their attributes — a per-field
sub-row listing `view.<subType>` badges and `@attr=value` pairs (@variantMap and
other object-valued attrs render as sorted `k: v` lists). The field builder
consumes the view node + its ownAttrs, so they no longer surface as "not rendered
by any page" in coverage.

Attrs are read directly off each view node, so custom view subtypes (registered
via extraProviders) render their attrs from a bare registration — no per-attr
schema duplication needed in the consumer's provider.

The acme fixture gains a view.currency field (Product.priceCents) exercising the
new sub-row; golden regenerated. Determinism preserved (view attrs sorted).

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: dmealing

server/typescript/packages/docs-site/src/builders/object-data.ts

@@ -27,7 +27,24 @@ function neighborAttrs(o: MetaData): { attrs: ErAttr[]; more: number } {
 }
 
 export interface EnumValue { value: string; deflt: boolean; desc: string; }
-export interface FieldRow { name: string; type: string; isArray: boolean; required: boolean; badgesHtml: string; desc: string; enumValues: EnumValue[]; refHref?: string | undefined; refName?: string | undefined; inheritedFrom?: { name: string; href: string } | undefined; anchor: string; }
+/** A field's presentation view child (e.g. view.currency / view.badge) + its
+ *  attrs, both HTML-escaped in the builder (this render lib does not escape). */
+export interface ViewAttr { name: string; value: string; }
+export interface ViewRow { subType: string; attrs: ViewAttr[]; }
+export interface FieldRow { name: string; type: string; isArray: boolean; required: boolean; badgesHtml: string; desc: string; enumValues: EnumValue[]; views: ViewRow[]; refHref?: string | undefined; refName?: string | undefined; inheritedFrom?: { name: string; href: string } | undefined; anchor: string; }
+
+/** Render an attr value for display: an object (e.g. view.badge @variantMap) as
+ *  ordered `k: v` pairs, an array as a comma list, else the scalar. */
+function fmtAttrValue(v: unknown): string {
+  if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+    return Object.entries(v as Record<string, unknown>)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([k, vv]) => `${k}: ${vv}`)
+      .join(", ");
+  }
+  if (Array.isArray(v)) return v.map(String).join(", ");
+  return String(v);
+}
 export interface IndexRow { name: string; kind: string; fields: string; extra: string; unique: boolean; }
 export interface ValidatorRow { scope: "field" | "object"; subject: string; rule: string; // human-readable, HTML-escaped
 }
@@ -88,8 +105,18 @@ function fieldRow(f: MetaData, ownerHref: string, g: LinkGraph, cov: CoverageTra
       }));
     }
   }
+  // presentation view children (view.currency / view.badge / view.meter / …) + their
+  // attrs — consumed + rendered so a field's render-semantics appear in the docs.
+  const views: ViewRow[] = [];
+  for (const v of f.childrenOfType("view")) {
+    cov.consumeNode(v);
+    const vAttrs = [...v.ownAttrs()]
+      .sort(([an], [bn]) => (an < bn ? -1 : an > bn ? 1 : 0))
+      .map(([an, av]) => { cov.consumeAttr(v, an); return { name: esc(an), value: esc(fmtAttrValue(av)) }; });
+    views.push({ subType: esc(v.subType), attrs: vAttrs });
+  }
   const desc = esc(a("description") ?? "");
-  return { name: f.name, type: f.subType, isArray: f.resolvedIsArray(), required, badgesHtml: bits.join(" "), desc, enumValues, refHref, refName, inheritedFrom: undefined, anchor: `f-${f.name}` };
+  return { name: f.name, type: f.subType, isArray: f.resolvedIsArray(), required, badgesHtml: bits.join(" "), desc, enumValues, views, refHref, refName, inheritedFrom: undefined, anchor: `f-${f.name}` };
 }
 
 // Neighborhood edge label: relationship edges show their name + (M:N) junction + onDelete; extends/others show via.

server/typescript/packages/docs-site/templates/object.html.mustache

@@ -12,6 +12,7 @@
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 {{#ownFields}}<tr id="{{anchor}}"><td class="font-mono">{{name}}{{#isArray}}[]{{/isArray}}</td><td class="opacity-60">{{type}}</td><td>{{{badgesHtml}}}</td><td class="text-xs">{{desc}}</td></tr>
 {{#enumValues.length}}<tr><td></td><td colspan="3" class="pl-4">{{#enumValues}}<span class="badge badge-soft badge-accent badge-xs mr-1">{{value}}{{#deflt}} ★{{/deflt}}</span>{{/enumValues}}</td></tr>{{/enumValues.length}}
+{{#views.length}}<tr><td></td><td colspan="3" class="pl-4 text-xs">{{#views}}<span class="badge badge-soft badge-info badge-xs mr-1 font-mono">view.{{subType}}</span>{{#attrs}}<span class="opacity-60 font-mono mr-2">@{{name}}={{value}}</span>{{/attrs}}{{/views}}</td></tr>{{/views.length}}
 {{/ownFields}}
 </tbody></table></div>
 {{#inheritedFields.length}}<div class="collapse collapse-arrow bg-base-100 border border-base-300 mt-2"><input type="checkbox"><div class="collapse-title text-sm font-semibold opacity-70">Inherited fields ({{inheritedFields.length}})</div><div class="collapse-content"><table class="table table-xs opacity-80"><tbody>

server/typescript/packages/docs-site/test/fixture/golden/acme/ai/ItemView.html

@@ -59,6 +59,7 @@ <h1 class="text-2xl font-bold font-mono mt-1">ItemView
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-label"><td class="font-mono">label</td><td class="opacity-60">string</td><td></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 </section>
 

server/typescript/packages/docs-site/test/fixture/golden/acme/ai/NpcPayload.html

@@ -59,8 +59,10 @@ <h1 class="text-2xl font-bold font-mono mt-1">NpcPayload
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-npcName"><td class="font-mono">npcName</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-error badge-xs">required</span></td><td class="text-xs"></td></tr>
 
+
 <tr id="f-items"><td class="font-mono">items[]</td><td class="opacity-60">object</td><td><a href="ItemView.html" class="badge badge-soft badge-secondary badge-xs" title="contains (nested object)">⊃ ItemView</a></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 </section>
 

server/typescript/packages/docs-site/test/fixture/golden/acme/ai/NpcResponse.html

@@ -59,8 +59,10 @@ <h1 class="text-2xl font-bold font-mono mt-1">NpcResponse
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-verdict"><td class="font-mono">verdict</td><td class="opacity-60">string</td><td></td><td class="text-xs">verdict &lt;b&gt;tag&lt;/b&gt; &amp; &quot;quote&quot;</td></tr>
 
+
 <tr id="f-reason"><td class="font-mono">reason</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-neutral badge-xs">@xmlText</span></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 </section>
 

server/typescript/packages/docs-site/test/fixture/golden/acme/ai/OrderLine.html

@@ -59,8 +59,10 @@ <h1 class="text-2xl font-bold font-mono mt-1">OrderLine
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-orderId"><td class="font-mono">orderId</td><td class="opacity-60">uuid</td><td></td><td class="text-xs"></td></tr>
 
+
 <tr id="f-lineNo"><td class="font-mono">lineNo</td><td class="opacity-60">int</td><td></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 </section>
 

server/typescript/packages/docs-site/test/fixture/golden/acme/common/BaseEntity.html

@@ -59,8 +59,10 @@ <h1 class="text-2xl font-bold font-mono mt-1">BaseEntity
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-id"><td class="font-mono">id</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-error badge-xs">required</span> <span class="badge badge-soft badge-neutral badge-xs">≤36</span> <span class="badge badge-soft badge-neutral badge-xs">uuid</span></td><td class="text-xs"></td></tr>
 
+
 <tr id="f-createdAt"><td class="font-mono">createdAt</td><td class="opacity-60">timestamp</td><td></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 </section>
 

server/typescript/packages/docs-site/test/fixture/golden/acme/shop/Customer.html

@@ -59,6 +59,7 @@ <h1 class="text-2xl font-bold font-mono mt-1">Customer
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-email"><td class="font-mono">email</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-error badge-xs">required</span> <span class="badge badge-soft badge-neutral badge-xs">≤120</span></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 <div class="collapse collapse-arrow bg-base-100 border border-base-300 mt-2"><input type="checkbox"><div class="collapse-title text-sm font-semibold opacity-70">Inherited fields (2)</div><div class="collapse-content"><table class="table table-xs opacity-80"><tbody>
 <tr id="f-id"><td class="font-mono">id <span class="text-[10px] opacity-50">↑ <a class="link" href="../common/BaseEntity.html">BaseEntity</a></span></td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-error badge-xs">required</span> <span class="badge badge-soft badge-neutral badge-xs">≤36</span> <span class="badge badge-soft badge-neutral badge-xs">uuid</span></td></tr><tr id="f-createdAt"><td class="font-mono">createdAt <span class="text-[10px] opacity-50">↑ <a class="link" href="../common/BaseEntity.html">BaseEntity</a></span></td><td class="opacity-60">timestamp</td><td></td></tr>

server/typescript/packages/docs-site/test/fixture/golden/acme/shop/CustomerFriend.html

@@ -59,8 +59,10 @@ <h1 class="text-2xl font-bold font-mono mt-1">CustomerFriend
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-friendAId"><td class="font-mono">friendAId</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-neutral badge-xs">≤36</span></td><td class="text-xs"></td></tr>
 
+
 <tr id="f-friendBId"><td class="font-mono">friendBId</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-neutral badge-xs">≤36</span></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 <div class="collapse collapse-arrow bg-base-100 border border-base-300 mt-2"><input type="checkbox"><div class="collapse-title text-sm font-semibold opacity-70">Inherited fields (2)</div><div class="collapse-content"><table class="table table-xs opacity-80"><tbody>
 <tr id="f-id"><td class="font-mono">id <span class="text-[10px] opacity-50">↑ <a class="link" href="../common/BaseEntity.html">BaseEntity</a></span></td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-error badge-xs">required</span> <span class="badge badge-soft badge-neutral badge-xs">≤36</span> <span class="badge badge-soft badge-neutral badge-xs">uuid</span></td></tr><tr id="f-createdAt"><td class="font-mono">createdAt <span class="text-[10px] opacity-50">↑ <a class="link" href="../common/BaseEntity.html">BaseEntity</a></span></td><td class="opacity-60">timestamp</td><td></td></tr>

server/typescript/packages/docs-site/test/fixture/golden/acme/shop/CustomerReferral.html

@@ -59,8 +59,10 @@ <h1 class="text-2xl font-bold font-mono mt-1">CustomerReferral
 <div class="overflow-x-auto"><table class="table table-xs"><thead><tr><th>Field</th><th>Type</th><th></th><th>Description</th></tr></thead><tbody>
 <tr id="f-referrerId"><td class="font-mono">referrerId</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-neutral badge-xs">≤36</span></td><td class="text-xs"></td></tr>
 
+
 <tr id="f-referredId"><td class="font-mono">referredId</td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-neutral badge-xs">≤36</span></td><td class="text-xs"></td></tr>
 
+
 </tbody></table></div>
 <div class="collapse collapse-arrow bg-base-100 border border-base-300 mt-2"><input type="checkbox"><div class="collapse-title text-sm font-semibold opacity-70">Inherited fields (2)</div><div class="collapse-content"><table class="table table-xs opacity-80"><tbody>
 <tr id="f-id"><td class="font-mono">id <span class="text-[10px] opacity-50">↑ <a class="link" href="../common/BaseEntity.html">BaseEntity</a></span></td><td class="opacity-60">string</td><td><span class="badge badge-soft badge-error badge-xs">required</span> <span class="badge badge-soft badge-neutral badge-xs">≤36</span> <span class="badge badge-soft badge-neutral badge-xs">uuid</span></td></tr><tr id="f-createdAt"><td class="font-mono">createdAt <span class="text-[10px] opacity-50">↑ <a class="link" href="../common/BaseEntity.html">BaseEntity</a></span></td><td class="opacity-60">timestamp</td><td></td></tr>