SDUI `element:button` executes an `action` prop the spec does not declare

[os-zhuang]

element:button renders an action and dispatches it, but ElementButtonPropsSchema (packages/spec/src/ui/component.zod.ts:298) has no action property at all.

What runs today

packages/components/src/__tests__/element-button-action.test.tsx:33 exercises the live path:

<ElementButton schema={{ type: 'element:button', properties: {
  label: 'Upgrade',
  action: { type: 'navigation', to: '/apps/cloud_control/sys_environment' },
} }} />

The click reaches the navigation handler. So both the action prop and the navigation action type are implemented and reachable, and neither is named in a spec schema:

• ElementButtonPropsSchema declares label, variant, size, icon, iconPosition, disabled, aria — no action;
• ActionType (ui/action.zod.ts:226) is script | url | modal | flow | api | form — no navigation.

Why nothing breaks, and why that is the problem

Page block properties are z.record(z.string(), z.unknown()) (ui/page.zod.ts:86), so an authored action is neither validated nor stripped. Nothing is losing data. What is lost is everything a declaration buys:

• Studio's inspector cannot offer the prop, because it derives fields from the props schema;
  Corrected (see the analysis comment): block-config.ts is hand-written, so the inspector
  needs its own edit either way. Declaring the prop buys validation and discoverability, not a field.
• no validation, so a typo in action.type or a missing to fails silently at click time rather than at save;
• the type vocabulary is undocumented, so an author cannot discover that navigation exists, or that it is not url.

The navigation / url question comes with it

ActionRunner.executeNavigation and executeUrl (packages/core/src/actions/ActionRunner.ts) both navigate. executeUrl is strictly richer — ${param.X} / ${ctx.X} interpolation, apiBase promotion for /api/... paths, openIn — while executeNavigation adds only replace (and reads to where url reads target).

So declaring the prop means deciding one of:

1. action accepts the spec's ActionSchema, and navigation becomes an alias executeUrl absorbs (replace moving onto ActionSchema if it is worth keeping) — one spelling of navigate;
2. element:button.action gets its own narrow schema that names navigation + to, accepting a second vocabulary for this surface;
3. navigation is promoted into ActionType as-is.

(3) was considered and rejected while widening the action vocabularies for #2945 (objectstack-ai/objectstack#4070): adding a synonym to a closed vocabulary is a one-way door — members cannot be removed later — and it would not have declared the prop, which is the actual gap. (1) looks right, but it changes what an authored element:button may say, so it wants a decision rather than a drive-by.

Cross-repo: the schema lives in framework packages/spec, the renderer in objectui packages/components.

Refs #2945, #2901, objectstack-ai/objectstack#4070

[os-zhuang]

Analysis, and a recommendation that is none of the three options above

Investigated properly. Four new facts change the decision, and one claim in the issue body above is wrong — correcting that first.

❌ Correction: Studio's inspector is not derived from the props schema

The body says "Studio's inspector cannot offer the prop, because it derives fields from the props schema." That is not how it works. packages/app-shell/src/views/metadata-admin/previews/block-config.ts:216 is a hand-written table, and its own header says so: "Keep each field name aligned with the property name the corresponding renderer reads." For element:button it lists label, variant, size, icon — and no action.

So declaring the prop in the spec buys validation and discoverability, but not an inspector field; that is a separate hand edit either way. block-config.ts is itself a fourth hand-maintained shadow of the spec's block props, which is the same disease #2901 catalogued — worth its own cleanup, and it means "declare the prop" does not by itself make the button authorable in Studio.

1. This is live in production, not a curiosity

cloud main, packages/service-tenant/src/pages/:

Site	Shape
pricing.page.ts:42	const goToEnvironments = { type: 'navigation', to: ENVIRONMENTS_ROUTE }
welcome.page.ts:66	const go = (to) => ({ type: 'navigation', to }) — used 4×
billing-cancel.page.ts:66, :76	{ type: 'navigation', to: … }
billing-success.page.ts:74	{ type: 'navigation', to: … }

Five declaration sites, ~9 rendered buttons, four pages — the billing and pricing funnel. Every one is cast as any, which is how they get past the type system today.

They use only type and to. No replace, no newTab, no external, no navigate. That matters: folding navigation onto url loses nothing anyone actually writes.

2. The renderer accepts three action dialects simultaneously

packages/components/src/renderers/basic/elements.tsx:212-240 forwards, verbatim:

type | actionType,  name, label, description, target, openIn, endpoint,
method, navigate, to, opensInNewTab, confirmText, successMessage,
errorMessage, refreshAfter, params → {params | actionParams}

That is ActionSchema's own field set (actionType is the dashboard-widget spelling, navigate/to the navigation spelling) — three vocabularies for one concept, in one 25-line callback. Of those, ActionSchema declares all but endpoint, navigate, to, replace.

3. An undeclared prop is stripped, not ignored — a loaded gun

ElementButtonPropsSchema.safeParse({ label: 'Go', action: { type: 'navigation', to: '/x' } })
→ success: true, data: { label: 'Go', variant: 'primary', size: 'medium', iconPosition: 'left', … }

No action. It is a non-strict z.object, so Zod drops the unknown key.

Harmless today, because page block properties are z.record(z.string(), z.unknown()) (page.zod.ts:86) and this schema never runs on a real page save. But the moment anyone tightens properties to validate against COMPONENT_PROPS_SCHEMAS — an obvious future hardening — every cloud button silently loses its action at save, with a green parse. Declaring the prop defuses that; nothing else does.

4. Two constraints that kill the obvious fixes

ActionSchema requires name and label. Verified:

{type:'url', target:'/x'}                → name: required, label: required
{name, type, target}                     → label: required
{name, label, type, target}              → OK

A page button already has properties.label. action: ActionSchema would force the author to write the label twice and invent a name for something that is not a reusable named action. Option 1 as written is not ergonomic.

The lazySchema proxy does not forward object-structural methods. Verified against 17.0.0-rc.0:

Call	Result
ChartTypeSchema.extract([...]), .options	✅ works (enum proxy)
ActionSchema.pick(...)	❌ not a function
ActionSchema.omit(...) / .extend(...) / .shape	❌ not available

So action: ActionSchema.pick({ … the 16 fields the renderer honours … }) — the derivation I would have wanted — is not expressible. Enum subsetting is available (that is how objectstack#4070 derived ListChartConfigSchema.chartType); object subsetting is not.

Recommendation

Declare the prop against a new InlineActionSchema, and treat navigation/to as normalizing aliases of url/target with a scheduled removal — not as new members.

Splitting the decision the issue conflated:

• D1 — declare action? Unambiguously yes. It is live in production, it feeds a real dispatcher, it is the only thing making a standalone-page button interactive, and leaving it undeclared keeps the silent-strip gun loaded. This is the part that closes this issue.
• D2 — pointing at what? None of the three options above is right:

Option	Verdict
1. action: ActionSchema	Right instinct, wrong shape — requires a duplicate label and an invented name, and cannot be narrowed via .pick
2. own narrow schema naming navigation + to	Blesses a fourth action-type vocabulary permanently (after ActionType, the now-unified WidgetActionType, and types/src/api-types.ts's 7-member union). Rejected for the reason this issue exists
3. promote navigation into ActionType	Does not close this issue at all — names the type, leaves the prop undeclared and to homeless. Half a fix, and a permanent synonym

Concretely

Stage A — framework, no breakage. Add InlineActionSchema to action.zod.ts: the ~16 fields the ElementButton renderer actually honours, with name/label optional (an inline action has no registry identity, and the button supplies its own label). Declare ElementButtonPropsSchema.action = InlineActionSchema.optional(). Accept navigation and to as z.preprocess aliases folding to url/target — the VIEW_FILTER_OPERATOR_ALIASES pattern, a bridge with a defined end state rather than a new enum member. Since .pick is unavailable, InlineActionSchema will restate its fields; pin it to ActionSchema with a parity test (the same substitute filter-view-operator-parity.test.ts uses for the data/↔ui/ layering constraint) so the two cannot drift.

Decide endpoint here too: the renderer forwards it and ActionSchema does not declare it — either it joins the inline schema or objectui stops forwarding it.

Stage B — cloud. Rewrite the five sites to { type: 'url', target: … } and drop the as any. Note the graft from objectstack#4107 does not help here: those pages are code-defined *.page.ts, not saveMeta-persisted, so nothing canonicalizes them automatically.

Stage C — framework, next major. retiredKey-tombstone to; drop the navigation alias. By then executeUrl's richer semantics (${param.X}/${ctx.X} interpolation, apiBase promotion for /api/… paths, popup-blocker-safe openIn) are what page buttons get, instead of executeNavigation's strictly weaker behaviour.

Also, separately: add action to block-config.ts's element:button entry, or the Studio inspector still cannot author it — and consider deriving that table from COMPONENT_PROPS_SCHEMAS rather than hand-keeping it.

Ordering

Framework first, then cloud (cloud links @objectstack/* to framework main). Stage A adds no export cloud must import, so cloud can lag safely — the alias keeps its current pages valid throughout. Nothing in Stage A rejects anything that parses today, so it carries no migration.

Refs objectstack-ai/objectstack#4070 (where promoting navigation bare was considered and declined), objectstack-ai/objectstack#4107, #2945

[os-zhuang]

Stage A implemented — objectstack-ai/objectstack#4135, and a correction to my own diagnosis

Correction: .pick is unavailable because of the refine chain, not the lazySchema proxy

My analysis above blamed the proxy. Wrong. Reading shared/lazy-schema.ts, the proxy's get handler forwards everything — real[prop], binding functions — which is exactly why ChartTypeSchema.extract([…]) works (that one wraps a bare z.enum).

The actual cause is that ActionSchema is z.object(…).refine(…).refine(…). .pick() is a ZodObject method, and two refinement wrappers stand between it and the export. Same observable symptom, different fix — and the difference matters, because it means subsetting is achievable by splitting the object half out, which the proxy story would have ruled out.

So the implementation is better than what I proposed:

const actionObject = () => z.object({ …47 fields… });
export const ActionSchema       = lazySchema(() => actionObject().refine(…).refine(…)…);
export const InlineActionSchema = lazySchema(() => z.preprocess(normalizeInlineAction,
  actionObject().pick({ …12 fields… }).partial({ name: true, label: true }).refine(…)));

Real derivation — no parity test needed. I recommended a parity test above as a substitute for the derivation I thought was impossible; it isn't needed, because the field definitions are now literally the same objects. A factory rather than a module-scope const so lazySchema's deferral survives (fields built on first use of whichever schema is touched, not at module load).

What shipped in Stage A

• InlineActionSchema — the twelve fields element:button actually forwards, name/label optional, target-required refinement inherited, registry-only concerns excluded.
• ElementButtonPropsSchema.action = InlineActionSchema.optional() — the prop is declared, so it stops being silently stripped.
• normalizeInlineAction — folds type:'navigation' → 'url' and to → target on parse. cloud's five sites keep validating unchanged; output is always canonical.
• 16 tests, including the derivation asserted from both directions and the fold pinned against the literal shape cloud writes. Full spec suite 7038/271 green, tsc clean, all twelve check:* gates pass, zero removals from any generated surface.

Remaining, in order

1. Stage B — cloud: rewrite the five service-tenant sites to { type: 'url', target }, drop the as any. Waiting on Stage A to merge (cloud links @objectstack/* to framework main).
2. objectui — block-config.ts: add an action field to the element:button entry, or Studio still cannot author it. Independent of Stage A; the table is hand-written.
3. Stage C — next major: retiredKey-tombstone to, drop the navigation alias.

One correction to the issue body's framing while I am here: the body says the prop being undeclared means "no validation … a typo in action.type or a missing to fails silently at click time rather than at save". That is right in direction but was understated — the prop was not merely unvalidated, it was deleted from the parse output. That is now in the analysis above with the executed evidence.

[os-zhuang]

Stages A and B done, plus the Studio half — this issue is closed out

Stage	Repo	PR
A — InlineActionSchema, prop declared, aliases fold	framework	objectstack-ai/objectstack#4135 ✅
B — migrate the five producers to url + target	cloud	objectstack-ai/cloud#926 ✅
Studio — a new button can be given an action	objectui	#3028 ✅

Two corrections to my own analysis in this thread

1. .pick was blocked by the refine chain, not the lazySchema proxy. The proxy forwards everything. ActionSchema is z.object(…).refine(…).refine(…), and .pick() is a ZodObject method. Splitting the object half into a factory made real derivation possible, so the parity test I proposed as a substitute was not needed — the field definitions are literally the same objects now.

2. "Studio cannot author it" was half right. The "Advanced" section can edit an action that source authored; what it cannot do is add one, because it enumerates Object.keys(blockProps) — the keys the block already has. So a button dragged from the palette had no path to becoming interactive. #3028 adds a json field kind (the same editor Advanced uses, reachable for a property that does not exist yet) and an action field with the canonical shape as its placeholder.

3. The Stage A PR body said Stage B would "drop the as any". It does not, and should not: those casts are for children on page:section, which the strict PageComponent type does not model. The comment above each one says so. Nothing to do with the action shape.

What remains — Stage C, next major

retiredKey-tombstone to and drop the navigation alias from normalizeInlineAction. Both producers are migrated now, so the bridge has nothing left to carry — but removing it is a breaking parse change, so it waits for a major.

Worth noting for whoever does it: objectui's ElementButtonRenderer still forwards actionType, endpoint, navigate and description to the runner, none of which InlineActionSchema declares. actionType is the dashboard-widget spelling, endpoint is a third spelling of target (executeAPI reads action.api || action.endpoint || action.target), and description is not on ActionSchema at all. They are dead for authored metadata now that the prop is declared, and trimming them is the natural companion to Stage C.

Closing — the declared-prop gap this issue was filed for is closed, and the remaining item is a scheduled removal rather than a defect.