Skip to content

Commit 020487b

Browse files
committed
Merge origin/main into claude/issue-28404-override-declaration
Takes the sibling spec cards that landed since the last merge (resolving the app schema: the override spread now sits inside the landing refinement); the generated artefacts are regenerated from the merged tree in the next commit. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017ihL2fi9zfJhUTubyJYb6V
2 parents 0f9936f + 80a9f99 commit 020487b

36 files changed

Lines changed: 1091 additions & 36 deletions
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/lint': minor
4+
---
5+
6+
feat(spec): an app can name a landing per audience with `landing`
7+
8+
Clause-②: yes (widening)
9+
Metadata-protocol: added
10+
11+
An app opens on its first navigation item, one landing for every audience. `AppSchema` now declares `landing`, a list of `{ item, visible }` entries (`AppLandingEntrySchema`): the first entry whose `visible` (CEL, the dialect of a navigation entry's `visible`) holds for the reader names the navigation entry the app opens on. With no match, or no key, the app opens where it did before: its first navigation item by `order`.
12+
13+
- **It cannot dangle.** Every app parse runs `checkAppLandingItems`: an `item` that names no entry of the app's own `navigation` or `areas[].navigation` (any depth), or names a `group`, `separator` or `action` entry, is refused at `landing.N.item`, and the message lists the entries that do exist. Items another package contributes through `navigationContributions` cannot be named.
14+
- **It is per audience.** `visible` is required, and an empty list is refused. To change where everyone lands, put that entry first in `navigation`, as before. A `visible` that reads `data` is refused: a landing entry has no `dataSource`.
15+
- **Lint.** `os validate` and `os build` check each landing predicate with the shared expression validator (CEL syntax, size, unknown functions). The metadata save door runs the parse refusals above on every app write.
16+
- **Planned.** No console reads `landing` yet. The liveness ledger carries it as `planned` with an author warning, so `os validate` tells an author that every reader still opens on the first navigation item until the console landing redirect ships.
17+
18+
Nothing to do for existing apps. The retired `homePageId` (and its `home` / `homepage` / `landingpage` spellings) still answers with its removal notice, which now also names `landing`.
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
'@object-ui/components': patch
3+
'@object-ui/i18n': patch
4+
---
5+
6+
feat(components): the edit form names the fields a visible update action would require, before the action is pressed
7+
8+
Clause-②: yes (widening: `@object-ui/i18n` gains the `form.requiredForAction` key in all ten locales; no accept set moves)
9+
Metadata-protocol: none
10+
11+
A declarative update action (`operation: 'update'` with a static `patch`) writes its patch over the record, and the server runs the object's `requiredWhen` rules over the result. The edit form judged the record as it stands, so a field that only the action makes required showed nothing, and the first press was refused. In the showcase, "Issued On" on a draft invoice is required once `status` is `sent`, and "Submit for Sign-off" sets `status: 'sent'`.
12+
13+
The form renderer now reads the object's declared actions on an edit form, through the data source it already has. For each update action that is placed, not switched off, permitted and visible for the record, it evaluates each field's `requiredWhen` over the record merged with the patch. An empty field that comes out required shows "Required to run “Submit for Sign-off”." under the control, inside the description the control's `aria-describedby` names.
14+
15+
- It is a heads-up only. Save is not blocked, and the field is not marked required for Save. The server's refusal stays the source of truth.
16+
- Actions that collect `params`, and actions whose write is not a static `patch`, are skipped, because what they write is not known before they run.
17+
- A create form reads and marks nothing.

‎content/docs/ui/apps.mdx‎

Lines changed: 60 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ const crmApp = defineApp({
4949
| `navigation` | `NavigationItem[]` | optional | Navigation tree |
5050
| `areas` | `NavigationArea[]` | optional | Partition navigation by business domain — see [Areas](#areas) |
5151
| `contextSelectors` | `AppContextSelector[]` | optional | Sidebar scope dropdowns whose value is injected into navigation items — see [Context Selectors](#context-selectors) |
52+
| `landing` | `AppLandingEntry[]` | optional | **Planned.** Per-audience landing: which navigation entry each audience opens on — see [Landing per audience](#landing-per-audience) |
5253
| `branding` | `AppBranding` | optional | Visual customization |
5354
| `requiredPermissions` | `string[]` | optional | Required permissions to access |
5455
| `defaultAgent` | `string` | optional | Platform agent bound to this app's ambient AI chat — see [Default Agent](#default-agent) |
@@ -283,7 +284,8 @@ label — the only keys it accepts are `type`, an optional `id`, and an optional
283284
All navigation items **except `separator`** share these base properties. Every
284285
item **must** declare a unique `id` (lowercase `snake_case`) — it is required by
285286
the schema, and it is what `order` sorts and what the landing page resolves to
286-
(the first item, since `homePageId` was removed in 17.0.0 — see below).
287+
(the first item, since `homePageId` was removed in 17.0.0 — see below — unless a
288+
[`landing`](#landing-per-audience) entry matches the reader).
287289
(On a `separator`, `id` is optional and the remaining properties below are
288290
rejected — a divider has nothing to label, gate, or badge.)
289291

@@ -714,6 +716,63 @@ const studioApp = defineApp({
714716
});
715717
```
716718

719+
## Landing per audience
720+
721+
An app opens on its first navigation item (by `order`). When one app serves
722+
several audiences, that is one landing for all of them: moving Sales above
723+
Service to suit the sales team moves service staff's landing to Leads.
724+
`landing` lets the app name, per audience, which of its own navigation entries
725+
a reader opens on.
726+
727+
```typescript
728+
defineApp({
729+
name: 'crm',
730+
label: 'CRM',
731+
navigation: [
732+
{ id: 'nav_leads', type: 'object', label: 'Leads', objectName: 'lead' },
733+
{ id: 'grp_service', type: 'group', label: 'Service', children: [
734+
{ id: 'nav_service_console', type: 'page', label: 'Service console', pageName: 'service_console' },
735+
]},
736+
],
737+
landing: [
738+
{ item: 'nav_service_console', visible: "'service_agent' in current_user.positions" },
739+
{ item: 'nav_leads', visible: "'sales_rep' in current_user.positions" },
740+
],
741+
});
742+
```
743+
744+
The entries are asked **in order**, and the first whose `visible` holds for the
745+
reader wins. When no entry matches, or the key is absent, the app opens where it
746+
always has: its first navigation item.
747+
748+
| Property | Type | Required | Description |
749+
| :--- | :--- | :--- | :--- |
750+
| `item` | `string` | ✅ | The `id` of a navigation entry of **this app** — its own `navigation` or any `areas[].navigation`, at any depth |
751+
| `visible` | `string` (CEL) | ✅ | Who lands there — the same dialect and reader roots (`current_user`, `features`) as a navigation entry's `visible` |
752+
753+
Refused at parse, at the entry's own path:
754+
755+
- an `item` that names no navigation entry of this app (the error lists the ones
756+
that exist). Items another package contributes through
757+
`navigationContributions` are not part of the app being parsed and cannot be
758+
named;
759+
- an `item` that names a `group`, `separator` or `action` entry — none of them
760+
opens a page;
761+
- an entry without `visible`. A landing for everyone is still "put that entry
762+
first in `navigation`"; `landing` is for different audiences;
763+
- a `visible` that reads `data` — a landing entry has no `dataSource`.
764+
765+
`landing` only decides where a reader **opens**. It grants nothing: the entry
766+
keeps its own `visible` / `requiredPermissions` / `requiresObject` gates, and an
767+
entry the reader cannot see is passed over.
768+
769+
<Callout type="warn">
770+
**Planned — not yet applied.** The key is declared and validated, but no
771+
console reads it yet, so every reader still opens on the app's first
772+
navigation item until the console's landing redirect ships. `os validate`
773+
says so for any app that declares it.
774+
</Callout>
775+
717776
## Default Agent
718777

719778
`defaultAgent` binds this app's **ambient AI chat** — the assistant the shell

‎docs/audits/2026-07-unknown-key-strictness-ledger.counts/ui.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ The `strict` column is the one the campaign schedules against; it counts both th
2121

2222
| Dir | Sites | strict | passthrough | catchall | strip |
2323
|---|---|---|---|---|---|
24-
| `ui/` | 217 | 208 | 4 | 0 | 5 |
24+
| `ui/` | 218 | 209 | 4 | 0 | 5 |
2525

2626
## `ui/` — sites
2727

@@ -33,7 +33,7 @@ classify and is not listed (it becomes reportable the day it grows its first sit
3333
|---|---|
3434
| `action-params.zod.ts` | 1 |
3535
| `action.zod.ts` | 9 |
36-
| `app.zod.ts` | 19 |
36+
| `app.zod.ts` | 20 |
3737
| `bulk-action.zod.ts` | 4 |
3838
| `chart.zod.ts` | 8 |
3939
| `component.zod.ts` | 81 |
@@ -46,23 +46,23 @@ classify and is not listed (it becomes reportable the day it grows its first sit
4646
| `sharing.zod.ts` | 1 |
4747
| `view.zod.ts` | 59 |
4848
| `widget.zod.ts` | 1 |
49-
| **total** | **217** |
49+
| **total** | **218** |
5050

5151
## `ui/` — open
5252

5353
Per file, how many of its sites still silently discard unknown keys. The `Class`
5454
column that decides the bucket split is hand-written in the ledger; the arithmetic
5555
over it is here.
5656

57-
**5 strip of 217**, in 4 file(s).
57+
**5 strip of 218**, in 4 file(s).
5858

5959
| File | Strip | Sites |
6060
|---|---|---|
6161
| `action-params.zod.ts` | 1 | 1 |
62-
| `app.zod.ts` | 1 | 19 |
62+
| `app.zod.ts` | 1 | 20 |
6363
| `view.zod.ts` | 2 | 59 |
6464
| `widget.zod.ts` | 1 | 1 |
65-
| **total** | **5** | **217** |
65+
| **total** | **5** | **218** |
6666

6767
| Bucket | Sites |
6868
|---|---|

‎packages/lint/src/validate-expressions.test.ts‎

Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import { EVALUATED_EXPRESSION_SOURCE_REQUIRED, ExpressionInputSchema, ObjectStac
1010
import { FieldSchema, ObjectFieldGroupSchema, ObjectSchema, SelectOptionSchema } from '@objectstack/spec/data';
1111
import { EvalUserSchema } from '@objectstack/spec/identity';
1212
import { SharingRuleSchema } from '@objectstack/spec/security';
13-
import { BulkActionDefSchema } from '@objectstack/spec/ui';
13+
import { AppLandingEntrySchema, AppSchema, BulkActionDefSchema } from '@objectstack/spec/ui';
1414
// [#15137] The published refusal sentence a `value`-slot finding must lead
1515
// with — asserted from the spec's own export, never re-spelled in a test.
1616
import {
@@ -945,6 +945,24 @@ describe('validateStackExpressions (ADR-0032 build-time)', () => {
945945
expect(ok).toHaveLength(0);
946946
});
947947

948+
it('judges an app landing predicate with the data-independent verdicts and no record scope (#28022)', () => {
949+
const nav = [{ id: 'nav_leads', type: 'object', label: 'Leads', objectName: 'lead' }];
950+
// `===` is not CEL: the predicate can never evaluate, so the landing could never match.
951+
const bad = validateStackExpressions({
952+
apps: [{ name: 'crm', label: 'CRM', navigation: nav, landing: [{ item: 'nav_leads', visible: "current_user.positions === 'x'" }] }],
953+
});
954+
const landingIssues = bad.filter(i => i.where === "app 'crm' · landing[0] ('nav_leads') visible");
955+
expect(landingIssues).toHaveLength(1);
956+
expect(landingIssues[0].severity).toBe('error');
957+
958+
// A healthy reader predicate is clean, and the slot binds no record, so a
959+
// bare identifier is not told to become `record.<x>`.
960+
const ok = validateStackExpressions({
961+
apps: [{ name: 'crm', label: 'CRM', navigation: nav, landing: [{ item: 'nav_leads', visible: "'sales_rep' in current_user.positions && features.crm != false" }] }],
962+
});
963+
expect(ok).toHaveLength(0);
964+
});
965+
948966
it('never reads `disabledReason` as a predicate — it is display copy (#26619)', () => {
949967
// The same bare-field source that is an error on `disabled` above is a
950968
// plain sentence on `disabledReason`: nothing is checked, nothing flagged.
@@ -3357,10 +3375,23 @@ const READ_SURFACES: Array<{ receiver: string; expected: string[]; declaredBy: s
33573375
receiver: 'stack',
33583376
// `views` joined with #24798: the bulk `confirmText` pass walks the views'
33593377
// list containers.
3360-
expected: ['actions', 'flows', 'hooks', 'objects', 'sharingRules', 'views'],
3378+
// `apps` joined with #28022: the landing predicates.
3379+
expected: ['actions', 'apps', 'flows', 'hooks', 'objects', 'sharingRules', 'views'],
33613380
declaredBy: 'ObjectStackSchema',
33623381
keys: () => Object.keys(ObjectStackSchema.shape),
33633382
},
3383+
{
3384+
receiver: 'appDef',
3385+
expected: ['landing', 'name'],
3386+
declaredBy: 'AppSchema',
3387+
keys: () => Object.keys(AppSchema.shape),
3388+
},
3389+
{
3390+
receiver: 'landingEntry',
3391+
expected: ['item', 'visible'],
3392+
declaredBy: 'AppLandingEntrySchema',
3393+
keys: () => Object.keys(AppLandingEntrySchema.shape),
3394+
},
33643395
{
33653396
receiver: 'obj',
33663397
// `validationRules` is absent — one of the five #5017 removed.

‎packages/lint/src/validate-expressions.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3542,6 +3542,24 @@ export function runStackExpressionPasses(stack: AnyRec, options: StackExpression
35423542
}
35433543
}
35443544

3545+
// ── App landing predicates (`app.landing[].visible`) ───────────────
3546+
// [#28022] An app's per-audience landing: the first entry whose predicate
3547+
// holds names the navigation entry the reader opens on. It reads the
3548+
// signed-in reader (`current_user`, `features`) and no record, so it gets
3549+
// the shared validator's data-independent verdicts (CEL syntax, size, an
3550+
// unknown function, a malformed `has()`) with no object and no bare-field
3551+
// judgement — a `record`-scoped call would prescribe `record.<x>` on a slot
3552+
// that binds no record. The parse already refused a dangling `item` and a
3553+
// `data` read (`checkAppLandingItems`). Apps are not an object's body, so
3554+
// an object write reads an empty list here.
3555+
for (const appDef of objectWrite ? [] : recordsOf(stack.apps)) {
3556+
const appName = typeof appDef.name === 'string' ? appDef.name : '?';
3557+
recordsOf(appDef.landing).forEach((landingEntry, index) => {
3558+
const item = typeof landingEntry.item === 'string' ? landingEntry.item : '?';
3559+
check(`app '${appName}' · landing[${index}] ('${item}') visible`, landingEntry.visible);
3560+
});
3561+
}
3562+
35453563
// ── Sharing-rule predicates (security-critical, record-scoped) ─────
35463564
// A criteria sharing rule's `condition` decides which rows a principal sees.
35473565
// It is evaluated against the record, so a bare ref silently changes access.

‎packages/metadata-protocol/src/protocol.meta-types-degenerate-derivation.test.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -356,8 +356,9 @@ describe('#17501 — /meta/types serves a real schema for `action`, and moves no
356356
// face (the progress bar or the plain percentage).
357357
// [#27945] `field` 80 → 81: `lookupAutofill`, the fields a pick in a
358358
// lookup fills.
359+
// [#28022] `app` 22 → 23: `landing`, the per-audience landing list.
359360
const CARD_PROPERTY_COUNTS: Record<string, number> = {
360-
agent: 24, app: 22, dashboard: 20, dataset: 16, field: 81, flow: 22,
361+
agent: 24, app: 23, dashboard: 20, dataset: 16, field: 81, flow: 22,
361362
hook: 23, object: 49, page: 26, position: 13, report: 23, skill: 16, tool: 14,
362363
};
363364

‎packages/qa/dogfood/test/expression-conformance.ledger.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -439,6 +439,16 @@ export const EXPRESSION_SURFACE: ExprSurface[] = [
439439
covers: ['ui/action.zod.ts:actionObject.pressed'],
440440
note: 'Display only by contract — it never gates, greys or routes the action — so a fault refuses nothing: the predicate\'s effect (the pressed face) is dropped and the fault is logged, which is `fail-soft-log`, not `fail-closed`. The unpressed face is also the one that never claims the reader acted. Split from `cel-action-visible` / `cel-action-disabled` for the collision rule those two were split on: one row cannot state three fault faces. A menu item (the header overflow, the bar\'s override menu) draws no pressed state at all. Measured here: the ui half is in this checkout and its suites pin the TRUE / FALSE / fault faces on both surfaces.',
441441
},
442+
{
443+
// The key arrived spec-first (card 28022); the console landing redirect that reads it is its own ui card.
444+
id: 'cel-app-landing',
445+
summary: "app per-audience landing predicate (AppLandingEntry.visible) — the first entry whose predicate holds names the navigation entry the app opens on",
446+
dialect: 'cel', mode: 'interpret', state: 'experimental', failPolicy: 'unevaluated',
447+
enforcement:
448+
'PARSE ONLY — `EvaluatedExpressionInputSchema` normalizes a bare string to `{dialect:"cel",source}` and refuses an `ast`-only envelope and a blank source, and `checkAppLandingItems` on `AppSchema` refuses a `data` read (a landing entry binds no `data`) and an `item` naming no openable navigation entry of the app. NO EVALUATOR FOUND: no console reads `app.landing` yet; the landing redirect that will ask these predicates is the follow-up ui card',
449+
covers: ['ui/app.zod.ts:AppLandingEntrySchema.visible'],
450+
note: 'EXPERIMENTAL, declared spec-first by ruling (letter A): the liveness ledger carries `app.landing` as `planned` with an author warning, so an author is told no console reads it yet. Re-classify when the console redirect lands: the predicate decides only where a reader opens, never what they may reach (each navigation entry keeps its own gates), so its fault face is expected to be `fail-soft-log` — a faulting entry is passed over and the app opens on its first navigation item.',
451+
},
442452
{
443453
id: 'cel-record-alert-visible',
444454
summary: '`record:alert` banner visibility (RecordAlertProps.visible) — the one record component whose PROPS carry a real predicate',

‎packages/spec/api-surface/ui.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,9 @@
5656
"AppContextSelector (type)",
5757
"AppContextSelectorParsed (type)",
5858
"AppContextSelectorSchema (const)",
59+
"AppLandingEntry (type)",
60+
"AppLandingEntryParsed (type)",
61+
"AppLandingEntrySchema (const)",
5962
"AppParsed (type)",
6063
"AppSchema (const)",
6164
"AppearanceConfig (type)",
@@ -522,6 +525,7 @@
522525
"chartAggregateCategoryKey (function)",
523526
"chartAggregateResultKeys (function)",
524527
"chartAggregateValueKey (function)",
528+
"checkAppLandingItems (function)",
525529
"checkDashboardWidgetChartMeasureArity (function)",
526530
"checkDashboardWidgetMetricMeasureArity (function)",
527531
"checkDashboardWidgetStageOrder (function)",

‎packages/spec/declaration-map/ui.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,8 @@
3030
"AppBrandingSchema": "ui/AppBranding",
3131
"AppContextSelector": "ui/AppContextSelector",
3232
"AppContextSelectorSchema": "ui/AppContextSelector",
33+
"AppLandingEntry": "ui/AppLandingEntry",
34+
"AppLandingEntrySchema": "ui/AppLandingEntry",
3335
"AppSchema": "ui/App",
3436
"AppearanceConfig": "ui/AppearanceConfig",
3537
"AppearanceConfigSchema": "ui/AppearanceConfig",

0 commit comments

Comments
 (0)