docs

Author: os-zhuang

.changeset/kind-terms-smash.md

@@ -1,5 +1,5 @@
 ---
-"@objectstack/mcp": minor
+"@objectstack/mcp": patch
 ---
 
 ai

CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — ObjectUI one-month frontend scan + backend alignment summary
+
+Scanning `../objectui` from 2026-05-08 through 2026-06-08 shows a broad Studio
+and renderer push, not just the most recent commits. Major frontend changes
+include live field-level conditional rules in forms (`visibleWhen`,
+`readonlyWhen`, `requiredWhen`), row-scoped inline-grid rules,
+required-on-submit handling, spreadsheet-style master-detail line-item editing,
+atomic parent+child form saves, derived related lists, record-page authoring,
+page block/property inspectors, flow-designer typed config panels and
+simulator, dataset designer/preview, dataset-bound dashboard widgets and
+reports, report matrix/joined/drill-down renderers, dashboard drill-downs and
+type-aware cells, metadata-admin draft/publish/rollback and skew protection,
+AI draft review/publish surfaces, public/developer API pages, settings,
+notifications/approvals, marketplace/package management, and wide i18n polish.
+
+The scan covered 910 non-merge commits in `../objectui`: 369 `feat`, 213 `fix`,
+108 `chore`, 37 `refactor`, plus docs/tests/CI/perf work. The largest touched
+areas were `packages/app-shell`, `apps/console`, `packages/plugin-detail`,
+`packages/plugin-dashboard`, `packages/plugin-grid`, `packages/fields`,
+`packages/plugin-report`, `packages/plugin-form`, `packages/plugin-list`, and
+`skills/objectui`.
+
+The framework backend now mirrors the critical enforcement boundaries:
+`@objectstack/plugin-security` exposes `security.getReadFilter(object,
+context)` as a reusable RLS read scope, `@objectstack/service-analytics`
+auto-bridges to it for dataset/dashboard/report queries and fails closed when
+scope cannot be safely applied, and ObjectQL enforces field conditional rules
+by validating `requiredWhen` and ignoring writes to fields locked by
+`readonlyWhen`.
+
 ### Fixed — First-boot platform-admin promotion no longer stolen by the `usr_system` seed identity
 
 `5e831dea3` (#1392) added `ensureSeedIdentity` to the runtime SeedLoader, which

content/docs/concepts/implementation-status.mdx

@@ -186,7 +186,7 @@ This matrix is generated from actual codebase analysis and represents the curren
 
 | Protocol | Implementation | Status | Notes |
 |:---------|:-------------:|:------:|:------|
-| **Analytics** | ✅ | ✅ | Protocol implemented in ObjectQL (driver-level aggregation) |
+| **Analytics** | ✅ | ✅ | ObjectQL aggregation plus `@objectstack/service-analytics` dataset execution; analytics read scope auto-bridges to `security.getReadFilter` for RLS-aware dashboards/reports |
 | **OData** | ❌ | 📋 | Protocol defined, not implemented |
 | **GraphQL** | ❌ | 📋 | Protocol defined, not implemented |
 | **Realtime** | ❌ | 📋 | Protocol defined, not implemented |
@@ -200,24 +200,35 @@ This matrix is generated from actual codebase analysis and represents the curren
 
 | Protocol | @objectstack/spec | Implementation | Status |
 |:---------|:-----------------:|:-------------:|:------:|
-| **View** | ✅ | ❌ | ❌ Spec only |
-| **ListView** | ✅ | ❌ | ❌ Spec only |
-| **FormView** | ✅ | ❌ | ❌ Spec only |
-| **Page** | ✅ | ❌ | ❌ Spec only |
-| **App** | ✅ | ❌ | ❌ Spec only |
-| **Dashboard** | ✅ | ❌ | ❌ Spec only |
-| **Report** | ✅ | ❌ | ❌ Spec only |
-| **Action** | ✅ | ❌ | ❌ Spec only |
-| **Component** | ✅ | ❌ | ❌ Spec only |
+| **View** | ✅ | 🟡 | 🟡 Studio/ObjectUI renders authored metadata surfaces; general-purpose renderer coverage is still incomplete |
+| **ListView** | ✅ | 🟡 | 🟡 ObjectUI grid/list surfaces support per-view persistence, filters, row actions, density, galleries, and permission-aware affordances; full protocol parity is ongoing |
+| **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`) |
+| **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 |
 | **Theme** | ✅ | ❌ | ❌ Spec only |
-| **Widget** | ✅ | ❌ | ❌ Spec only |
-| **Chart** | ✅ | ❌ | ❌ Spec only |
+| **Widget** | ✅ | 🟡 | 🟡 Dashboard/report/list/form widgets render in ObjectUI; custom widget manifest/runtime parity remains in progress |
+| **Chart** | ✅ | 🟡 | 🟡 Recharts-backed dashboard/report charts cover bar/line/pie/area/scatter/funnel/gauge/treemap/sankey with formatting and field-coverage guards |
 
 **Notes:**
 - All UI protocols are fully defined in spec
-- Metadata API can retrieve UI definitions (views, apps)
-- No built-in UI renderer yet - designed for custom implementations
-- React SDK provides data hooks, UI rendering is application responsibility
+- Metadata API can retrieve UI definitions (views, apps, pages, dashboards,
+  reports, actions)
+- Active Studio/ObjectUI source lives in the sibling `../objectui` repo and is
+  bundled into `packages/console` via the objectui refresh workflow
+- Metadata-admin curated forms now merge server-only fields back into the save
+  payload, so a Studio form that exposes only part of a metadata type should
+  not strip newer protocol properties
+- The 2026-05-08 → 2026-06-08 ObjectUI scan covered 910 non-merge frontend
+  commits. The largest functional clusters were metadata-admin/Studio,
+  master-detail forms, reports/dashboards, record detail/related lists,
+  action transport, flow designer, developer/API pages, AI draft publishing,
+  and i18n.
+- React SDK provides data hooks; the cross-surface renderer is still being
+  completed in ObjectUI rather than in this backend repo
 
 ---
 
@@ -273,7 +284,7 @@ The `auth` service in `CoreServiceName` covers both **authentication** (identity
 - Client SDK supports bearer token header — but token validation requires the auth plugin
 - Auth route (`/auth/*`) only appears in Discovery when the auth plugin is registered
 - Fine-grained authorization (RLS, sharing, territory) is internal to the auth plugin
-- **Phase-1 RBAC enforcement is live end-to-end**: REST → ObjectQL → SecurityPlugin middleware now receives a populated `ExecutionContext` (userId, tenantId, roles, permissions). Default `member_default` permission set ships a wildcard RLS rule `organization_id = current_user.organization_id` plus per-object overrides `sys_organization_self` (`id = current_user.organization_id`) and `sys_user_self` (`id = current_user.id`) for the global tables that lack an `organization_id` column. The earlier `tenantField` indirection (RLS expressions written against an abstract `tenant_id` column then rewritten to the configured physical column at compile time) was removed — the placeholder, the column name, and `RLSUserContext.organization_id` are now the same name end-to-end. The legacy `objectql.registerTenantMiddleware` (hardcoded `where.tenant_id` injection that pre-dated SecurityPlugin) has been removed; SecurityPlugin is the sole authority for tenant isolation. Verified cross-organization isolation on `pnpm dev:crm` across `sys_organization`, `sys_member`, `sys_user`, `sys_user_permission_set`, `sys_role_permission_set`. **Anonymous traffic still bypasses enforcement** until a default-deny pass lands.
+- **Phase-1 RBAC enforcement is live end-to-end**: REST → ObjectQL → SecurityPlugin middleware now receives a populated `ExecutionContext` (userId, tenantId, roles, permissions). Default `member_default` permission set ships a wildcard RLS rule `organization_id = current_user.organization_id` plus per-object overrides `sys_organization_self` (`id = current_user.organization_id`) and `sys_user_self` (`id = current_user.id`) for the global tables that lack an `organization_id` column. The earlier `tenantField` indirection (RLS expressions written against an abstract `tenant_id` column then rewritten to the configured physical column at compile time) was removed — the placeholder, the column name, and `RLSUserContext.organization_id` are now the same name end-to-end. The legacy `objectql.registerTenantMiddleware` (hardcoded `where.tenant_id` injection that pre-dated SecurityPlugin) has been removed; SecurityPlugin is the sole authority for tenant isolation. Analytics now uses the same reusable read scope via `security.getReadFilter`, so dataset-bound dashboards/reports do not bypass RLS. Verified cross-organization isolation on `pnpm dev:crm` across `sys_organization`, `sys_member`, `sys_user`, `sys_user_permission_set`, `sys_role_permission_set`. **Anonymous traffic still bypasses enforcement** until a default-deny pass lands.
 
 ---
 
@@ -373,11 +384,19 @@ The `auth` service in `CoreServiceName` covers both **authentication** (identity
 - [ ] Realtime Subscriptions
 - [ ] WebSocket Support
 
-### Phase 7: UI Layer 📋 **PLANNED**
+### Phase 7: UI Layer 🟡 **IN PROGRESS**
 - [ ] UI Renderer
-- [ ] Form Builder
-- [ ] List View Renderer
-- [ ] Dashboard Renderer
+- [x] Studio metadata-admin engine — generic metadata list/detail/edit surfaces, live preview, draft/publish/rollback, create-mode forms, server-side diagnostics, package scoping, and skew-safe curated inspectors
+- [x] Form conditional rules — ObjectUI supports `visibleWhen`, `readonlyWhen`, `requiredWhen`, row-scoped inline-grid rules, and required-on-submit enforcement
+- [x] Master-detail forms — inline subforms, spreadsheet-style line items, atomic batch create/edit, lookup auto-fill, line ordering, duplicate/reorder, and subtotal/tax/total stack
+- [x] Record detail + related lists — derived related lists, record-page assignment, action slots, system/audit sections, and opt-in reference rail
+- [x] Dashboard renderer/editor — widget layout persistence, drill-downs, pivot/funnel/table/list widgets, type-aware cells, and per-widget dataset binding authoring (`dataset`, `dimensions`, `values`)
+- [x] Report renderer/editor — spec-native summary/matrix/joined reports, chart/KPI blocks, drill-downs, dataset-bound reports, and i18n labels
+- [x] Flow/page designers — typed flow node config panels, simulator/debug runner, page block canvas, slotted record pages, and schema-driven block inspectors
+- [x] Action transport — row/global/header actions, modal parameter collection, visible CEL, popup-safe open actions, and nested action runner sharing
+- [x] Developer/admin console surfaces — Integrations & APIs, public forms, flow runs, approvals inbox, settings, marketplace/package management, AI draft review/publish
+- [ ] List View Renderer full protocol parity
+- [ ] Cross-surface UI Renderer full protocol parity
 - [ ] Theme Engine
 
 ### Phase 8: Automation (Plugin) 🟡 **IN PROGRESS**
@@ -390,6 +409,7 @@ The `auth` service in `CoreServiceName` covers both **authentication** (identity
 - [x] Authentication Plugin (`@objectstack/plugin-auth`, better-auth)
 - [x] Authorization Plugin — `@objectstack/plugin-security` enforces CRUD/FLS/RLS in the ObjectQL middleware chain; REST → ObjectQL now propagates `ExecutionContext` end-to-end (Phase-1)
 - [x] Row-Level Security — default `member_default` permission set applies a wildcard `organization_id = current_user.organization_id` rule plus per-object overrides `sys_organization_self` / `sys_user_self`. The earlier `tenantField` rewrite indirection was removed: RLS column, placeholder, and `RLSUserContext.organization_id` use the same canonical name end-to-end
+- [x] Analytics RLS bridge — `@objectstack/service-analytics` auto-bridges to `security.getReadFilter(object, context)` and fails closed when read-scope resolution cannot be safely applied
 - [x] Multi-tenancy — verified cross-organization isolation on `pnpm dev:crm` (Alice@OrgAlpha vs. Bob@OrgBeta only see their own records across `sys_organization`, `sys_member`, `sys_user`, and `sys_*_permission_set` link tables)
 - [x] Legacy `objectql.registerTenantMiddleware` removed — SecurityPlugin is now the sole tenant-isolation authority
 - [ ] Default-deny for anonymous traffic

content/docs/guides/cheatsheets/field-type-gallery.mdx

@@ -631,7 +631,10 @@ These properties are available on **all** field types:
 | `maskingRule` | `object` | — | Data masking configuration |
 | `dependencies` | `object` | — | Dependent field configuration |
 | `dataQuality` | `object` | — | Data quality validation rules |
-| `conditionalRequired` | `object` | — | Conditional requirement rules |
+| `visibleWhen` | `Expression` | — | Show field only when predicate is true |
+| `readonlyWhen` | `Expression` | — | Make field read-only when predicate is true |
+| `requiredWhen` | `Expression` | — | Require field when predicate is true |
+| `conditionalRequired` | `Expression` | — | Deprecated alias of `requiredWhen` |
 
 ---
 

content/docs/guides/cheatsheets/field-validation-rules.mdx

@@ -32,7 +32,10 @@ These properties apply to **all** field types and are validated by the base `Fie
 | `index` | `boolean` | `false` | Creates standard database index |
 | `externalId` | `boolean` | `false` | Marks field as external ID for upsert operations |
 | `auditTrail` | `boolean` | `false` | Tracks all changes with user and timestamp |
-| `conditionalRequired` | `string` | — | Formula expression that makes field required when `TRUE` |
+| `visibleWhen` | `string \| Expression` | — | CEL predicate; field is shown only when `TRUE` |
+| `readonlyWhen` | `string \| Expression` | — | CEL predicate; field is read-only when `TRUE` |
+| `requiredWhen` | `string \| Expression` | — | CEL predicate; field is required when `TRUE` |
+| `conditionalRequired` | `string \| Expression` | — | Deprecated alias of `requiredWhen` |
 
 ---
 

content/docs/guides/formula.mdx

@@ -9,9 +9,10 @@ ObjectStack uses a **single canonical expression language** for every place a
 piece of metadata needs to compute a value or evaluate a condition:
 
 - **Formula fields** (`type: 'formula'`)
-- **Predicates** — validation `condition`, sharing `condition`, conditional
-  visibility (`visibleOn`), conditional required (`conditionalRequired`),
-  action `disabled`, view filter `criteria`, hook `condition`, flow decisions
+- **Predicates** — validation `condition`, sharing `condition`, field
+  conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`),
+  conditional visibility (`visibleOn`), action `disabled`, view filter
+  `criteria`, hook `condition`, flow decisions
 - **Dynamic seed values** — fixtures whose value depends on the install-time
   clock or identity context
 
@@ -92,7 +93,7 @@ export const Invoice = ObjectSchema.create({
       formula: F`record.subtotal + record.subtotal * record.tax_rate`,
     }),
     po_number: Field.text({
-      conditionalRequired: P`record.amount > 10000`,
+      requiredWhen: P`record.amount > 10000`,
     }),
     // M9.9b — declarative default, evaluated at insert time
     issued_date: Field.date({
@@ -196,14 +197,20 @@ CEL throws on `null + string`, so wrap every nullable operand in
 }
 ```
 
-### Predicate (visibility, conditional required)
+### Predicate (visibility, read-only, conditional required)
 
 ```ts
 {
   name: 'rating',
   type: 'picklist',
   visibleOn: P`record.status == 'qualified'`,
 }
+
+Field.text({
+  visibleWhen: P`record.type == 'business'`,
+  readonlyWhen: P`record.status == 'approved'`,
+  requiredWhen: P`record.amount > 10000`,
+})
 ```
 
 ### Dynamic seed dates

content/docs/guides/metadata/dashboard.mdx

@@ -98,6 +98,74 @@ Each widget defines a data visualization:
 | `options` | `object` | optional | Additional display options |
 | `responsive` | `object` | optional | Responsive behavior |
 
+## Dataset-Bound Widgets
+
+Dashboards support two additive query shapes:
+
+- **Inline widgets** use `object`, `categoryField`, `valueField`, `aggregate`,
+  and `filter` directly on the widget.
+- **Dataset-bound widgets** use the semantic-layer `dataset` plus named
+  `dimensions` and `values`.
+
+Prefer dataset-bound widgets for shared business metrics. A dataset defines
+the base object, allowed relationship joins, reusable dimensions, certified
+measures, and intrinsic filters once; dashboards and reports then reference
+the same names so "revenue", "pipeline", or "win rate" stay consistent across
+surfaces.
+
+```typescript
+import { defineDataset } from '@objectstack/spec/ui';
+
+export const salesDataset = defineDataset({
+  name: 'sales',
+  label: 'Sales',
+  object: 'opportunity',
+  include: ['account'],
+  dimensions: [
+    { name: 'region', field: 'account.region', type: 'string' },
+    { name: 'close_month', field: 'close_date', type: 'date', dateGranularity: 'month' },
+  ],
+  measures: [
+    { name: 'revenue', field: 'amount', aggregate: 'sum', certified: true },
+    { name: 'deal_count', aggregate: 'count' },
+  ],
+});
+
+export const salesDashboard = {
+  name: 'sales_overview',
+  label: 'Sales Overview',
+  widgets: [
+    {
+      id: 'revenue_by_region',
+      title: 'Revenue by Region',
+      type: 'bar',
+      dataset: 'sales',
+      dimensions: ['region'],
+      values: ['revenue'],
+      layout: { x: 0, y: 0, w: 6, h: 4 },
+    },
+  ],
+};
+```
+
+Dataset-bound widgets require at least one `values` entry. Do not also set
+`object`, `valueField`, or `aggregate` unless you are intentionally keeping an
+inline widget. Studio's Dashboard Widget Inspector can author the dataset,
+dimensions, and values per widget; curated metadata-admin forms preserve any
+server-only fields that are not exposed by the current inspector, so saving a
+dashboard from Studio should not strip newer protocol fields.
+
+At runtime, dataset queries are executed through the analytics service. When
+`@objectstack/plugin-security` is registered, analytics auto-bridges to
+`security.getReadFilter(object, context)` and applies the caller's RLS scope to
+the base object and joined objects.
+
+ObjectUI currently renders object-backed and 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.
+
 ### Chart Types
 
 | Type | Description | Best For |