Skip to content
This repository was archived by the owner on Nov 4, 2026. It is now read-only.

Commit 6bca0e4

Browse files
os-justinclaude
andauthored
feat(types)!: retire the legacy ActionSchema onSuccess/onFailure callback pair and delete ActionCallback (objectui#7068) (#7832)
`@object-ui/types` published a THIRD meaning of `onSuccess`: the legacy `crud.ts` `ActionSchema` carried `onSuccess?` / `onFailure?` as Phase-2 `ActionCallback` objects, zod-mirrored and taught by two docs pages, with zero producers outside the package's own fixture and zero runtime readers, while `@objectstack/spec`'s `ActionSchema` refuses the shape at publish. Maintainer ruling option 1 (2026-09-05): retire it, both faces, docs in the same PR. - crud.ts: `ActionCallback` DELETED (the objectui#7664 / PR #7743 route for a standalone retired type); `onSuccess?: never` / `onFailure?: never` with the RETIRED docblocks — tombstones, not deletions, because `BaseSchema`'s index signature would admit a deleted key - crud.zod.ts: `ActionCallbackSchema` and its inferred alias DELETED; the two keys are `retirementTombstone()` named refusals whose guidance names the spec's `{ navigate, openIn }` block on `UIActionSchema` and `successMessage` / `errorMessage` - both barrels drop the two names; parity ledger drops the pair (`EXPECTED_MIRROR_PAIRS` 159 -> 158, header chain extended); the 7340 handler census records the two new `on*?: never` members (26 -> 28, `onFailure` in the name net) - phase2-schemas fixture no longer authors the callback shape; new pin action-callback-retired-7068: both faces refuse at path with the guidance (direct, via DetailSchema.actions, via the union door), base-vs-extended contrast on both faces, neighbours stay legal, absence of the deleted names (barrel object + AST), spec comparison (refuses the callback shape, accepts the navigation block), docs corpus scan, tsc legs - docs: the three enhanced-actions.mdx fences author successMessage / errorMessage; "Callbacks" becomes a "Post-success behaviour" note (no fence); schema-overview.md fragment / bullet / checklist row rewritten; the stale doc-types `message` exemption removed - changeset (types minor, "Breaking for authored metadata") Claude-Session: https://claude.ai/code/session_01BAZFhALsQsGqxui8sNqM8s Co-authored-by: Claude <noreply@anthropic.com>
1 parent 3faaa7d commit 6bca0e4

12 files changed

Lines changed: 565 additions & 147 deletions
Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
---
2+
'@object-ui/types': minor
3+
---
4+
5+
**Breaking for authored metadata:** the legacy `ActionSchema`'s Phase-2 callback
6+
pair — `onSuccess` / `onFailure`, each carrying an `ActionCallback` object — is
7+
RETIRED, and the `ActionCallback` type and its Zod mirror `ActionCallbackSchema`
8+
(with the inferred `ActionCallbackSchemaType`) are DELETED from `@object-ui/types`
9+
and `@object-ui/types/zod` (objectui#7068; maintainer ruling option 1 of
10+
2026-09-05, immediate, no deprecation window; ADR-0049 enforce-or-remove).
11+
12+
**What an author who wrote the shape sees now.** A `{ type: 'action', … }`
13+
document authoring `onSuccess: { type: 'toast', message: '…' }` (or any
14+
`onFailure` callback) no longer validates: the parse fails loudly on the
15+
`onSuccess` / `onFailure` path (`invalid_type`, expected `never`) with the
16+
explanation and the migration in the message, and the TypeScript members are
17+
`?: never` tombstones so the same document is a `tsc` error at the authoring
18+
site. `import type { ActionCallback } from '@object-ui/types'` and
19+
`import { ActionCallbackSchema } from '@object-ui/types/zod'` fail to resolve.
20+
21+
**What was measured, on this branch's base (`900f8d99`).** `ActionCallback`
22+
(`{ type: 'toast' | 'message' | 'redirect' | 'reload' | 'custom' | 'ajax' |
23+
'dialog', message?, url?, api?, method?, dialog?, handler? }`) was declared in
24+
`crud.ts`, mirrored in `zod/crud.zod.ts`, re-exported by both barrels, and
25+
carried on the legacy `ActionSchema` as `onSuccess?` / `onFailure?`. Producers:
26+
the package's own `phase2-schemas.test.ts` fixture and three `ts` fences in
27+
`content/docs/core/enhanced-actions.mdx` — nothing else (`git grep -l
28+
ActionCallback` over `packages content skills` hit the five `packages/types`
29+
files; positive control `SchemaNodeSchema` hit 22). Runtime readers: none —
30+
`ActionRunner` imports `UIActionSchema`, never this interface, and its own
31+
`ActionDef.onFailure` is a different (runner-native) meaning. It was the THIRD
32+
meaning of one key: objectui#5934 had already retired the runner's callback
33+
meaning of `onSuccess` and converged it on the spec's block.
34+
35+
**Why authored JSON that passed publish is unaffected.** `@objectstack/spec`'s
36+
`ActionSchema` (installed pin 17.2.0) already refused the callback shape at
37+
publish — `invalid_type` at `onSuccess.navigate` plus `unrecognized_keys` on the
38+
`onSuccess` block, and `onFailure` refused as an unrecognized key on the action —
39+
so no published or saved metadata could carry it. Only TypeScript code that
40+
typed a callback against the legacy interface, or JSON validated solely through
41+
`@object-ui/types/zod`, meets the new refusal.
42+
43+
**Where the live meaning lives.** Post-success navigation is the spec's
44+
`onSuccess` block, `{ navigate, openIn }`, declared on `UIActionSchema`
45+
(`ui-action.ts`) and forwarded to the runner (objectui#5934). A success or
46+
failure notice is `successMessage` / `errorMessage` — adjacent keys on the same
47+
legacy `ActionSchema`, NOT retired, and still accepted on both faces.
48+
49+
**Two published faces, one retirement — tombstone on the keys, deletion of the
50+
type.** `BaseSchema` is `.passthrough()` on the mirror and carries an index
51+
signature on the interface, so DELETING the two keys would have ADMITTED an
52+
authored callback unchecked on both faces; they stay declared as `?: never` /
53+
`retirementTombstone()` (the PR #7761 / #7769 shape) and the base-vs-extended
54+
contrast is pinned. The standalone `ActionCallback` / `ActionCallbackSchema` have
55+
no such escape hatch and are deleted outright, the route objectui#7664 / PR #7743
56+
took for the `DeclarativeKanban*` trio; the parity ledger drops the pair
57+
(`EXPECTED_MIRROR_PAIRS` 159 → 158) and the absence is pinned in
58+
`action-callback-retired-7068.test.ts`.
59+
60+
**Docs, same change.** `content/docs/core/enhanced-actions.mdx` — the three
61+
`onSuccess` / `onFailure` fences author `successMessage` / `errorMessage`
62+
instead, and the "Callbacks" section is a "Post-success behaviour" note pointing
63+
at the spec block (no fence: the legacy type carries no spec-derived block).
64+
`content/docs/guide/schema-overview.md` — the fragment line, the feature bullet
65+
and the checklist row are rewritten to the truth (the ✅ claim is now a
66+
retirement note).
67+
68+
**Migration:** delete `onSuccess` / `onFailure` from any legacy `ActionSchema`
69+
document or fixture; write `successMessage` / `errorMessage` for notices, put
70+
follow-up work in `chain`, and author post-success navigation as the spec's
71+
`onSuccess: { navigate, openIn }` block on `UIActionSchema`.
72+
73+
Graded `minor`, not `patch`: this narrows the accepted input set on both faces
74+
and removes two exports, which is breaking for any consumer who wrote the shape.
75+
It is not `major` per this repo's fixed-group convention (objectui's own breaking
76+
changes ship as `minor`; the group's major tracks `@objectstack` — AGENTS.md
77+
版本号策略, mechanically enforced by `scripts/check-changeset-no-major.mjs`).

‎content/docs/core/enhanced-actions.mdx‎

Lines changed: 25 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Enhanced Actions"
3-
description: "Advanced action system with AJAX calls, chaining, conditions, and callbacks"
3+
description: "Advanced action system with AJAX calls, chaining, conditions, and tracking"
44
---
55

66
import { SchemaExample } from '@/app/components/ComponentDemo';
@@ -15,7 +15,7 @@ The enhanced `ActionSchema` provides:
1515
- **New action types**: `ajax`, `confirm`, `dialog`
1616
- **Action chaining**: Execute multiple actions sequentially or in parallel
1717
- **Conditional execution**: a `condition` predicate gates whether an action runs
18-
- **Callbacks**: Success and failure handlers
18+
- **Notices**: `successMessage` / `errorMessage` strings
1919
- **Tracking**: Event logging and analytics
2020
- **Retry logic**: Automatic retry with configurable backoff
2121

@@ -54,14 +54,8 @@ const ajaxAction: ActionSchema = {
5454
data: {
5555
filter: 'active'
5656
},
57-
onSuccess: {
58-
type: 'toast',
59-
message: 'Data loaded successfully'
60-
},
61-
onFailure: {
62-
type: 'message',
63-
message: 'Failed to load data'
64-
}
57+
successMessage: 'Data loaded successfully',
58+
errorMessage: 'Failed to load data'
6559
};
6660
```
6761

@@ -302,47 +296,25 @@ for an either/or.
302296
> diagnostic at runtime. The shape is now refused by `ActionSchema`'s zod schema
303297
> instead of being accepted and ignored.
304298
305-
## Callbacks
306-
307-
Handle success and failure scenarios:
299+
## Post-success behaviour
308300

309-
```ts
310-
import type { ActionSchema } from '@object-ui/types';
301+
This legacy `ActionSchema` has no callback slot. The Phase-2 pair it used to
302+
declare — `onSuccess` / `onFailure` carrying an `ActionCallback` object
303+
(`{ type: 'toast' | 'message' | 'redirect' | 'reload' | 'custom' | 'ajax' | 'dialog', message, url, api, … }`)
304+
— was RETIRED (objectui#7068): nothing ever read it (the runner never consumed
305+
the shape), and `@objectstack/spec`'s `ActionSchema` refuses it at publish. Both
306+
keys are `never` on the TypeScript face and named refusals on the Zod mirror, so an
307+
authored callback fails at the authoring site with the migration in the message.
311308

312-
const actionWithCallbacks: ActionSchema = {
313-
type: 'action',
314-
label: 'Submit',
315-
actionType: 'ajax',
316-
api: '/api/submit',
317-
method: 'POST',
318-
319-
onSuccess: {
320-
type: 'toast',
321-
message: 'Submitted successfully!'
322-
},
323-
324-
onFailure: {
325-
type: 'dialog',
326-
dialog: {
327-
type: 'dialog',
328-
title: 'Submission Failed',
329-
content: {
330-
type: 'text',
331-
content: 'Please try again or contact support.'
332-
}
333-
}
334-
}
335-
};
336-
```
309+
What to write instead:
337310

338-
**Callback Types:**
339-
- `toast` - Show toast notification
340-
- `message` - Show message dialog
341-
- `redirect` - Navigate to URL
342-
- `reload` - Reload data
343-
- `ajax` - Execute another API call
344-
- `dialog` - Open dialog
345-
- `custom` - Custom handler
311+
- **A notice** — `successMessage` / `errorMessage`, plain strings (the runner
312+
surfaces `successMessage` as a toast after a successful action).
313+
- **Post-success navigation** — the spec's `onSuccess` block, `{ navigate, openIn }`,
314+
declared on `UIActionSchema` and forwarded to the runner (objectui#5934). It is
315+
a spec key, not a member of this legacy type, so it is not shown in a fence here.
316+
- **Follow-up work** — `chain` (see [Action Chaining](#action-chaining)): declared
317+
actions, not callbacks.
346318

347319
## Action Tracking
348320

@@ -446,22 +418,9 @@ const complexAction: ActionSchema = {
446418
],
447419
chainMode: 'sequential',
448420

449-
// Callbacks
450-
onSuccess: {
451-
type: 'toast',
452-
message: 'Order processed successfully!'
453-
},
454-
onFailure: {
455-
type: 'dialog',
456-
dialog: {
457-
type: 'dialog',
458-
title: 'Order Processing Failed',
459-
content: {
460-
type: 'text',
461-
content: 'Unable to process order. Please try again.'
462-
}
463-
}
464-
},
421+
// Notices
422+
successMessage: 'Order processed successfully!',
423+
errorMessage: 'Unable to process order. Please try again.',
465424

466425
// Tracking
467426
tracking: {
@@ -514,15 +473,15 @@ Enhanced Actions are ideal for:
514473

515474
- **API integration** - Connect to backend services and external APIs
516475
- **Multi-step processes** - Execute complex workflows with multiple stages
517-
- **Form submissions** - Handle form data with validation and callbacks
476+
- **Form submissions** - Handle form data with validation and chained follow-up actions
518477
- **Confirmation dialogs** - Add safety checks for critical operations
519478
- **Event tracking** - Monitor user interactions for analytics
520479
- **Batch operations** - Process multiple items in sequence or parallel
521480

522481
## Best Practices
523482

524483
1. **Use confirm for destructive actions** - Always confirm delete, archive, etc.
525-
2. **Provide clear feedback** - Use callbacks to inform users of success/failure
484+
2. **Provide clear feedback** - Set `successMessage` / `errorMessage` so users learn what happened
526485
3. **Chain related operations** - Group logically related API calls
527486
4. **Track important events** - Enable tracking for business-critical actions
528487
5. **Set appropriate timeouts** - Don't let users wait indefinitely

‎content/docs/guide/schema-overview.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,9 @@ turns it into the CSS variables your components already read.
7070
### Advanced Actions
7171

7272
#### [Enhanced Actions](/docs/core/enhanced-actions)
73-
Powerful action system with AJAX calls, chaining, conditions, and callbacks.
73+
Powerful action system with AJAX calls, chaining, conditions, and tracking.
7474

75-
<!-- doc-snippet: fragment — a shape excerpt: `chain`, `onSuccess` and `tracking` are written as literal `[...]` / `{...}` ellipses so the section can list the action keys without a worked example of each -->
75+
<!-- doc-snippet: fragment — a shape excerpt: `chain` and `tracking` are written as literal `[...]` / `{...}` ellipses so the section can list the action keys without a worked example of each -->
7676

7777
```typescript
7878
const action: ActionSchema = {
@@ -81,7 +81,6 @@ const action: ActionSchema = {
8181
api: '/api/submit',
8282
chain: [...],
8383
condition: '${...}',
84-
onSuccess: {...},
8584
tracking: {...}
8685
};
8786
```
@@ -94,7 +93,7 @@ const action: ActionSchema = {
9493
**Key Features:**
9594
- Action chaining (sequential/parallel)
9695
- Conditional execution (a `condition` predicate gates whether an action runs)
97-
- Success/failure callbacks
96+
- Success / failure notices (`successMessage` / `errorMessage`)
9897
- Event tracking
9998
- Retry logic
10099

@@ -274,7 +273,7 @@ The `ActionSchema` provides comprehensive action handling:
274273
- ✅ Action types: `ajax`, `confirm`, `dialog`
275274
- ✅ Action chaining via the `chain` array (sequential or parallel)
276275
- ✅ Conditional execution with the `condition` property
277-
- ✅ Success/failure callbacks: `onSuccess` and `onFailure`
276+
- ❌ Success/failure callbacks: `onSuccess` / `onFailure` were RETIRED (objectui#7068) — both faces refuse them; write `successMessage` / `errorMessage` for notices, and the spec's `onSuccess` block `{ navigate, openIn }` on `UIActionSchema` for post-success navigation (objectui#5934)
278277
- ✅ Event tracking with the `tracking` configuration
279278
- ✅ Automatic retry logic
280279

@@ -300,7 +299,7 @@ ObjectUI includes enhanced view components:
300299

301300
3. **Set up theming** - Hand a `Theme` document to `ThemeProvider` for consistent styling (optional)
302301

303-
4. **Implement actions** - Use advanced action features like `confirm` and callbacks
302+
4. **Implement actions** - Use advanced action features like `confirm` and chaining
304303

305304
5. **Test your application** - Verify all functionality works as expected
306305

0 commit comments

Comments
 (0)