docs(ui): document dashboard drill-in (drill-through + drill-to-record chain) (#2126)

Dashboards drill in two ways and the docs/skill didn't cover it — the
objectstack-ui skill even had a 'Drilldown' header with no content. Documents:

- table/pivot dataset widgets drill through to the underlying records (raw group
  keys preserved); the drilled record list now drills into the clicked record,
  completing the group → records → record chain.
- metric/chart dataset widgets are not click-drillable (surface detail via a
  table/pivot widget).
- the ObjectUI renderer's richer options.drillDown block (mode filter|record,
  drawer/dialog target, column whitelist, scatter/treemap/sankey chart drill)
  for object/record-backed surfaces.

Fixes the guide's overclaim that every dataset widget has 'drill-down
affordances', and notes the completed record chain in implementation-status.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

content/docs/concepts/implementation-status.mdx

@@ -208,7 +208,7 @@ The data (`/data`), metadata (`/meta`), and batch endpoints are implemented in `
 | **FormView** | ✅ | 🟡 | 🟡 ObjectUI forms support live field rules (`visibleWhen` / `readonlyWhen` / `requiredWhen`), inline-grid row rules, and server-aligned required enforcement |
 | **Page** | ✅ | 🟡 | 🟡 Record-page authoring, page create flows, block canvas editing, slotted record pages, and selected page blocks are implemented in ObjectUI; full component catalogue remains in progress |
 | **App** | ✅ | 🟡 | 🟡 Navigation metadata is consumed by the console/app shell; full renderer parity remains in progress |
-| **Dashboard** | ✅ | 🟡 | 🟡 ObjectUI renders metric/chart/list/pivot/funnel/table widgets, drill-downs, type-aware cells, and dataset-bound widgets; Studio can author per-widget dataset bindings (`dataset` / `dimensions` / `values`) |
+| **Dashboard** | ✅ | 🟡 | 🟡 ObjectUI renders metric/chart/list/pivot/funnel/table widgets, drill-downs (group → records → record chain), type-aware cells, and dataset-bound widgets; Studio can author per-widget dataset bindings (`dataset` / `dimensions` / `values`) |
 | **Report** | ✅ | 🟡 | 🟡 ObjectUI renders spec-native tabular/summary/matrix/joined reports, chart/KPI blocks, drill-downs, and dataset-bound reports |
 | **Action** | ✅ | 🟡 | 🟡 ObjectUI supports row/global/header actions, action modal transport, parameter collection, visibility CEL, and nested action runners |
 | **Component** | ✅ | 🟡 | 🟡 Selected page/record components render in ObjectUI (`record:alert`, related lists, highlights, page blocks); catalogue parity remains in progress |

content/docs/guides/metadata/dashboard.mdx

@@ -164,9 +164,10 @@ the base object and joined objects.
 
 ObjectUI currently renders dataset-backed metric, chart,
 table/list, pivot, funnel, and gauge-style widgets with type-aware cells,
-field/option labels, date bucketing, numeric/currency formatting, and
-drill-down affordances. Use declarative drill-down settings and preserve raw
-group keys so the generated filter can navigate to the underlying records.
+field/option labels, date bucketing, and numeric/currency formatting.
+`table` and `pivot` widgets are also **drill-through** (see
+[Drill-down](#drill-down) below); the dataset preserves raw group keys so the
+generated filter navigates to the exact underlying records.
 
 ### Chart Types
 
@@ -188,6 +189,44 @@ group keys so the generated filter can navigate to the underlying records.
 Additional types: `horizontal-bar`, `column`, `donut`, `sankey`, `solid-gauge`,
 `kpi`, and `bullet`. The default type is `metric`.
 
+### Drill-down
+
+`table` and `pivot` widgets are **drill-through**: clicking an aggregated row
+(table) or cell (pivot) opens a side drawer listing the **underlying records**
+behind that group. Because the dataset preserves each grouped row's raw group
+keys, the drawer's filter matches the exact records — no label-to-id guessing.
+
+The drilled record list is itself **drill-to-record**: click any row in the
+drawer to open that single record's detail. This completes the
+**group → records → record** chain (e.g. *Revenue by Region* → the orders in
+the *West* bucket → one order).
+
+```typescript
+// A drill-through table widget. No drill configuration is required — it is
+// automatic whenever the dataset exposes the base object and the widget groups
+// by at least one dimension.
+{
+  id: 'orders_by_region',
+  title: 'Orders by Region',
+  type: 'table',
+  dataset: 'sales',
+  dimensions: ['region'],
+  values: ['revenue', 'deal_count'],
+  layout: { x: 0, y: 0, w: 6, h: 4 },
+}
+```
+
+Drill-through is automatic — there is no per-widget drill configuration in the
+dataset form. `metric` and `chart` widgets render the aggregate only and are not
+click-drillable; expose the detail through a `table`/`pivot` widget instead.
+
+> **Renderer note.** Object/record-backed list and table surfaces (and the
+> ObjectUI renderer's `options.drillDown` block) support a richer drill model —
+> a `mode: 'filter' | 'record'` discriminator, drawer-vs-dialog target, a column
+> whitelist, and chart-segment drill for the `scatter` / `treemap` / `sankey`
+> families. Those knobs live in the renderer; dataset-bound dashboards drill
+> through the semantic layer as described above.
+
 ### Aggregation Functions
 
 Aggregation is declared on the dataset's **measures** (via `aggregate`), not on

skills/objectstack-ui/SKILL.md

@@ -952,6 +952,32 @@ defineDataset({
   compareTo: 'previousYear' }
 ```
 
+### Drilldown
+
+Dashboards drill in two ways: **drill-through** turns an aggregate into the rows
+behind it; **drill-to-record** opens one record.
+
+* **`table` / `pivot` widgets drill through.** Clicking an aggregated table row
+  or pivot cell opens a side drawer listing the underlying records. The dataset
+  preserves each grouped row's raw group keys, so the drawer filters to the
+  *exact* records (no label→id guessing). Automatic — no per-widget config.
+* **The drilled record list drills to record.** Any row in that drawer opens the
+  single record's detail, completing the **group → records → record** chain.
+* **`metric` / `chart` widgets are not click-drillable** in the dataset form
+  (they render the aggregate only; `compareTo` still applies). Surface the detail
+  through a `table` / `pivot` widget instead.
+
+> **Renderer note (object/record-backed surfaces).** The ObjectUI renderer
+> exposes a richer `options.drillDown` block for non-dataset list/table widgets
+> and the drill drawers — `enabled`, `mode` (`'filter'` = aggregate → filtered
+> list; `'record'` = row → that record), `target` (`'drawer'` | `'dialog'`),
+> `columns` (whitelist), and `title` (`${event.*}` interpolation). At the
+> renderer level drill-through covers the `bar` / `line` / `area` / `pie` /
+> `donut` / `funnel` / `scatter` / `treemap` / `sankey` families and pivot
+> cell/row/column/total clicks (`radar` is excluded — no single clickable
+> category point). **Dataset-bound dashboards use the semantic-layer drill above
+> and ignore this block.**
+
 | `dateGranularity` | Rendered bucket label |
 |:--|:--|
 | `'day'` | `YYYY-MM-DD` |