feat(spec): unify conditional-visibility predicate under visibleWhen (ADR-0089) (#2900)

* feat(spec): unify conditional-visibility predicate under visibleWhen (ADR-0089)

Make `visibleWhen` the single canonical conditional-visibility key across all
layers (data field, view form section/field, page component), aligning with the
existing `readonlyWhen` / `requiredWhen` family and the resolved
`conditionalRequired → requiredWhen` precedent.

D1 — canonical key: accept `visibleWhen` on `FormFieldSchema` /
`FormSectionSchema` (view.zod.ts) and `PageComponentSchema` (page.zod.ts),
documenting the per-layer binding root (runtime surfaces bind
`record` + `current_user` + `page.<var>`; metadata-editing forms bind `data`).

D2 — aliases + normalization: mark the view `visibleOn` and page `visibility`
keys `@deprecated`; fold them into `visibleWhen` once at the schema boundary via
a shared `normalizeVisibleWhen` zod `.transform()` (canonical wins when both are
present), so no consumer re-implements the fallback.

Codemod first-party sources to canonical `visibleWhen`: metadata-editing forms
(`*.form.ts`), the showcase view/pages, and the affected tests + docs + the
objectstack-formula skill + the expression-conformance ledger (both spellings
kept as live CEL surfaces during the deprecation window).

Out of scope, unchanged: boolean `visible` (Tab on/off), field `hidden`,
gallery `visibleFields`, and unrelated `visibility` enums (feed / package /
environment / agent). The `.strict()` flip (D3a), the lint rule (D3b), and the
ObjectUI renderer reads (sibling repo) are staged follow-ups per the ADR.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017fU25GeYSPKq9eEURsQffF

* chore(spec): update api-surface snapshot for visibleWhen helpers

Regenerate the public API-surface snapshot to include the two new
`@objectstack/spec` exports added by ADR-0089 — `normalizeVisibleWhen`
and `VISIBILITY_ALIAS_KEYS` (shared visibility-normalization helper).
Non-breaking (2 added, 0 removed/narrowed).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017fU25GeYSPKq9eEURsQffF

* feat(lint): visibility-predicate lint rule for ADR-0089 (D3b)

Add `validateVisibilityPredicates` (`@objectstack/lint`) and wire it into
`os validate` + `os compile` as advisory warnings:

- `visibility-alias-deprecated` — a deprecated `visibleOn` (view form) or
  `visibility` (page component) key in authored source → steer to `visibleWhen`.
- `visibility-root-mislayered` — a runtime view/page visibility predicate rooted
  at `data.` (the metadata-editing-form root) → runtime surfaces bind
  `record`/`current_user`/`page.<var>`, so a `data.` root never matches.

Runs on the PRE-parse (normalized) stack — like `validate-list-view-mode` —
because the schema folds `visibleOn`/`visibility` into `visibleWhen` at parse,
so the parsed stack no longer carries the alias the author wrote. Both rules are
warnings; the build never fails on them.

Addresses #2903 (ADR-0089 D3b).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017fU25GeYSPKq9eEURsQffF

---------

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

Author: os-zhuang

.changeset/adr-0089-visibility-lint.md

@@ -0,0 +1,13 @@
+---
+"@objectstack/lint": minor
+"@objectstack/cli": minor
+---
+
+ADR-0089 D3b: add the `validateVisibilityPredicates` lint rule for conditional-visibility keys, wired into `os validate` and `os compile` as advisory warnings.
+
+Two rules, both `warning` (never fail the build):
+
+- `visibility-alias-deprecated` — a `visibleOn` (view form section/field) or `visibility` (page component) key in authored source. It still works — the schema normalizes it to `visibleWhen` at parse — but the canonical key is `visibleWhen`. Fix: rename the key (same CEL value).
+- `visibility-root-mislayered` — a runtime view/page visibility predicate rooted at `data.` (the metadata-editing-form root). Runtime record surfaces bind `record` + `current_user` (pages also expose `page.<var>`), so a `data.`-rooted predicate here never matches and the element renders unconditionally. Fix: use `record.`/`page.`.
+
+The rule runs on the **pre-parse** stack (like `validate-list-view-mode`) so it can see the deprecated alias the author actually wrote before the schema folds it into `visibleWhen`.

.changeset/adr-0089-visible-when.md

@@ -0,0 +1,17 @@
+---
+"@objectstack/spec": minor
+---
+
+ADR-0089: unify the conditional-visibility predicate under one canonical key, `visibleWhen`, across every layer (data field, view form section/field, page component). This aligns visibility with the existing `readonlyWhen` / `requiredWhen` family and the `conditionalRequired → requiredWhen` precedent.
+
+**Canonical key:** `visibleWhen` — a CEL predicate; the element is shown only when it is TRUE. The binding *root* is still set by the layer: runtime record forms and pages bind `record` + `current_user` (pages also expose `page.<var>`); metadata-editing forms (`*.form.ts`) bind `data`.
+
+**Deprecated aliases (still accepted):** the view key `visibleOn` and the page key `visibility` are now `@deprecated`. Both are folded into `visibleWhen` **once, at the schema boundary** (a zod `.transform()`), so consumers only ever read `visibleWhen`. When both a canonical and an alias key are present, the canonical wins.
+
+Migration (L1 — no consumer action required; existing metadata keeps working):
+
+- View form section/field: `visibleOn: "<cel>"` → `visibleWhen: "<cel>"`
+- Page component: `visibility: "<cel>"` → `visibleWhen: "<cel>"`
+- Data field / field option: already `visibleWhen` — unchanged.
+
+Out of scope (unchanged): the boolean `visible` (Tab on/off), field `hidden`, gallery `visibleFields`, and unrelated `visibility` *enums* (feed / package / environment / agent). Aliases remain for the standard deprecation window and are removed in a future major.

content/docs/data-modeling/formulas.mdx

@@ -11,7 +11,7 @@ piece of metadata needs to compute a value or evaluate a condition:
 - **Formula fields** (`type: 'formula'`)
 - **Predicates** — validation `condition`, sharing `condition`, field
   conditional rules (`visibleWhen`, `readonlyWhen`, `requiredWhen`),
-  view section/column visibility (`visibleOn`), action `disabled`,
+  view section/column visibility (`visibleWhen`), action `disabled`,
   hook `condition`, flow decisions
 - **Dynamic seed values** — fixtures whose value depends on the install-time
   clock or identity context

content/docs/protocol/objectui/layout-dsl.mdx

@@ -752,7 +752,7 @@ interface FormSection {
   collapsible?: boolean;  // default false
   collapsed?: boolean;    // default false
   columns?: 1 | 2 | 3 | 4;  // default 1
-  visibleOn?: string;     // CEL visibility predicate; hides section when false
+  visibleWhen?: string;   // CEL visibility predicate; hides section when false
   fields: (string | FormField)[];
 }
 ```
@@ -772,7 +772,7 @@ interface FormField {
   readonly?: boolean;
   hidden?: boolean;
   widget?: string;     // custom widget override
-  visibleOn?: string;  // CEL visibility predicate
+  visibleWhen?: string;  // CEL visibility predicate
 }
 ```
 
@@ -794,18 +794,30 @@ interface ResponsiveColumns {
 ### Visibility Rule
 
 Visibility is a single **CEL expression** string, not a structured rule object.
-Page components expose it as `visibility` (`packages/spec/src/ui/page.zod.ts`);
-form sections and fields expose it as `visibleOn` (`packages/spec/src/ui/view.zod.ts`).
-The component is shown only when the expression evaluates truthy.
+Since [ADR-0089](/docs/adr) the one canonical key is **`visibleWhen`** across every
+layer — data fields, view form sections/fields, and page components — aligning with
+the `readonlyWhen` / `requiredWhen` family. The element is shown only when the
+expression evaluates truthy.
 
 ```typescript
 // e.g. on a PageComponent:
-visibility: "record.account_type == 'premium'"
+visibleWhen: "record.account_type == 'premium'"
 
 // e.g. on a FormSection / FormField:
-visibleOn: "record.status != 'closed' && user.hasRole('admin')"
+visibleWhen: "record.status != 'closed' && user.hasRole('admin')"
 ```
 
+The predicate's **binding root** is set by the layer, not the key:
+
+| Layer | Predicate binds |
+|---|---|
+| Runtime record forms & pages (`*.view.ts`, `*.page.ts`) | `record` + `current_user` (pages also expose `page.<var>`) |
+| Metadata-editing forms (`*.form.ts`) | `data` — the row under edit |
+
+The legacy spellings `visibleOn` (view) and `visibility` (page) are `@deprecated`
+aliases: still accepted and folded into `visibleWhen` at parse time, so existing
+metadata keeps working. Author new metadata with `visibleWhen`.
+
 Breakpoint-based show/hide is handled separately via the component's
 `responsive.hiddenOn` array (e.g. `hiddenOn: ['xs', 'sm']`), see
 `packages/spec/src/ui/responsive.zod.ts`.

content/docs/ui/views.mdx

@@ -233,7 +233,7 @@ fields: [
     required: true,              // Override required
     colSpan: 2,                  // Span 2 grid columns
     widget: 'custom-editor',     // Custom widget component
-    visibleOn: "status != 'cancelled'",
+    visibleWhen: "status != 'cancelled'",
   },
 ]
 ```
@@ -250,7 +250,7 @@ fields: [
 | `colSpan` | `1-4` | Column span in grid layout |
 | `widget` | `string` | Custom widget/component name |
 | `dependsOn` | `string` | Parent field for cascading |
-| `visibleOn` | `string` | Visibility condition expression |
+| `visibleWhen` | `string` | Visibility condition expression (was `visibleOn`, ADR-0089) |
 
 ### Default Sort for Related Lists
 

docs/adr/0089-unify-visibility-predicate-naming.md

@@ -1,6 +1,6 @@
 # ADR-0089: Unify the conditional-visibility predicate under one name (`visibleWhen`), alias the rest
 
-**Status**: Proposed (2026-07-05)
+**Status**: Accepted (2026-07-14) — D1 + D2 + codemod + docs implemented in #2642. D3a (`.strict()` flip) and D3b (lint rule) deferred to follow-up per the ADR's staged rollout (sweep first, then flip).
 **Deciders**: ObjectStack Protocol Architects
 **Builds on**: [ADR-0049](./0049-no-unenforced-security-properties.md) (enforce-or-remove — a declared-but-unchecked visibility key is exactly this class), [ADR-0078](./0078-no-silently-inert-metadata.md) (no silently-inert metadata — a mis-layered visibility key that zod strips is inert by accident), [ADR-0085](./0085-object-semantic-roles-over-surface-hint-blocks.md) (the enforce-or-remove pass that already deleted a consumer-less `visibleOn` from `fieldGroups`), [ADR-0033](./0033-ai-assisted-metadata-authoring.md) (the AI-authoring population this ADR optimizes for), [ADR-0058](./0058-expression-and-predicate-surface.md) (the CEL predicate surface these keys all belong to), [ADR-0087](./0087-metadata-protocol-upgrade-contract.md) (conversion-over-notification; this rename ships as an L1 invisible break via the alias mechanism)
 **Consumers**: `@objectstack/spec` (the field / view / page zod schemas + the alias normalization), `@objectstack/objectql` (`rule-validator` — the server-side enforcer), `@objectstack/lint` (the new mis-layer / wrong-root rule), ObjectUI form + page renderers, and every AI author of `*.object.ts` / `*.view.ts` / `*.page.ts`

examples/app-showcase/src/ui/pages/contact-form.page.ts

@@ -94,7 +94,7 @@ export const ContactFormPage = definePage({
         {
           type: 'element:text',
           id: 'ready_hint',
-          visibility: "page.inquiryEmail != ''",
+          visibleWhen: "page.inquiryEmail != ''",
           properties: {
             content: '✓ Looks good — hit Submit to send your inquiry.',
             variant: 'caption',

examples/app-showcase/src/ui/pages/page-variables.page.ts

@@ -10,7 +10,7 @@ import { definePage } from '@objectstack/spec/ui';
  *      is `project_picker` (PageVariableSchema.source = that component id).
  *   2. `element:record_picker` (id: project_picker) writes the chosen project's
  *      id into that variable on selection.
- *   3. Sibling components gate on `page.selectedProjectId` via `visibility`:
+ *   3. Sibling components gate on `page.selectedProjectId` via `visibleWhen`:
  *      the empty-state hint shows while nothing is picked; the detail panel
  *      appears the moment a project is chosen — re-evaluated live, no reload.
  *
@@ -69,7 +69,7 @@ export const PageVariablesPage = definePage({
         {
           type: 'element:text',
           id: 'empty_hint',
-          visibility: "page.selectedProjectId == ''",
+          visibleWhen: "page.selectedProjectId == ''",
           properties: {
             content: '↑ Select a project above to reveal its detail panel.',
             variant: 'caption',
@@ -79,12 +79,12 @@ export const PageVariablesPage = definePage({
         {
           type: 'element:divider',
           id: 'detail_divider',
-          visibility: "page.selectedProjectId != ''",
+          visibleWhen: "page.selectedProjectId != ''",
         },
         {
           type: 'element:text',
           id: 'detail_heading',
-          visibility: "page.selectedProjectId != ''",
+          visibleWhen: "page.selectedProjectId != ''",
           properties: {
             content: '✓ Project selected',
             variant: 'subheading',
@@ -93,7 +93,7 @@ export const PageVariablesPage = definePage({
         {
           type: 'element:text',
           id: 'detail_body',
-          visibility: "page.selectedProjectId != ''",
+          visibleWhen: "page.selectedProjectId != ''",
           properties: {
             content:
               'This panel is gated on `page.selectedProjectId != ""`. It became visible the instant the picker wrote the variable — the same page-local state any other component (or its data filter) can read.',

examples/app-showcase/src/ui/views/task.view.ts

@@ -239,13 +239,13 @@ export const TaskViews = defineView({
             { field: 'status', required: true },
             { field: 'priority' },
             { field: 'due_date' },
-            // View-level conditional visibility (FormField.visibleOn, CEL):
+            // View-level conditional visibility (FormField.visibleWhen, CEL):
             // the notes box only appears while the task is Urgent. Data-level
             // counterpart is `visibleWhen` on invoice.paid_on.
             // Width via the semantic `span` (#2578): 'full' = whole row at any
             // derived column count — the primary primitive; absolute colSpan
             // is legacy and lint-discouraged.
-            { field: 'notes', visibleOn: P`record.priority == 'urgent'`, span: 'full' },
+            { field: 'notes', visibleWhen: P`record.priority == 'urgent'`, span: 'full' },
           ],
         },
       ],

examples/app-showcase/test/page-variables.test.ts

@@ -21,7 +21,7 @@ import { ShowcaseApp } from '../src/ui/apps/index.js';
 type AnyComponent = {
   type: string;
   id?: string;
-  visibility?: unknown;
+  visibleWhen?: unknown;
   [k: string]: unknown;
 };
 
@@ -76,7 +76,7 @@ describe('Page Variables showcase — page-local state (ADR-0049)', () => {
 
   it('gates its detail panel on the variable — hidden until a project is picked, shown after', () => {
     const comps = allComponents(PageVariablesPage);
-    const gated = comps.filter((c) => c.visibility !== undefined);
+    const gated = comps.filter((c) => c.visibleWhen !== undefined);
     // Empty-hint + divider + heading + body — every gated node references the variable.
     expect(gated.length).toBeGreaterThanOrEqual(2);
 
@@ -86,7 +86,7 @@ describe('Page Variables showcase — page-local state (ADR-0049)', () => {
     let shownWhenEmpty = 0;
     let shownWhenPicked = 0;
     for (const c of gated) {
-      const src = predicateSource(c.visibility);
+      const src = predicateSource(c.visibleWhen);
       expect(src, `gated component ${c.id} must carry a predicate`).toBeTruthy();
       // Every gating predicate is about the page variable.
       expect(src).toContain('page.selectedProjectId');
@@ -102,7 +102,7 @@ describe('Page Variables showcase — page-local state (ADR-0049)', () => {
     // The empty-state predicate and the detail predicates are mutually exclusive:
     // no gated node is visible in BOTH states.
     for (const c of gated) {
-      const src = predicateSource(c.visibility)!;
+      const src = predicateSource(c.visibleWhen)!;
       const inEmpty = evalPredicate(src, empty.page);
       const inPicked = evalPredicate(src, picked.page);
       expect(inEmpty && inPicked, `component ${c.id} should not be visible in both states`).toBe(false);