Enhanced Actions

ObjectUI's action system has been significantly enhanced to support complex workflows, including AJAX API calls, confirmation dialogs, action chaining, conditional execution, and comprehensive tracking.

Overview

The enhanced ActionSchema provides:

New action types: ajax, confirm, dialog
Action chaining: Execute multiple actions sequentially or in parallel
Conditional execution: a condition predicate gates whether an action runs
Notices: successMessage / errorMessage strings
Tracking: Event logging and analytics
Retry logic: Automatic retry with configurable backoff

Interactive Examples

Action Buttons

Action Button Variants

Confirmation Dialog Pattern

Confirmation Dialog

Action Toolbar

Action Types

Ajax Actions

Execute API calls with full request configuration:

import type { ActionSchema } from '@object-ui/types';

const ajaxAction: ActionSchema = {
  type: 'action',
  label: 'Load Data',
  actionType: 'ajax',
  api: '/api/users',
  method: 'GET',
  headers: {
    'Authorization': 'Bearer token'
  },
  data: {
    filter: 'active'
  },
  successMessage: 'Data loaded successfully',
  errorMessage: 'Failed to load data'
};

Ajax Properties:

api - API endpoint URL
method - HTTP method (GET, POST, PUT, DELETE, PATCH)
data - Request body/payload
headers - Custom HTTP headers
timeout - Request timeout in milliseconds
retry - Retry configuration

Confirm Actions

Show confirmation dialog before executing:

import type { ActionSchema } from '@object-ui/types';

const confirmAction: ActionSchema = {
  type: 'action',
  label: 'Delete Record',
  actionType: 'confirm',
  confirmText: 'Are you sure you want to delete this record?',
  api: '/api/records/123',
  method: 'DELETE'
};

Confirm Properties:

confirmText - Confirmation message shown in the dialog. This is the one confirm spelling — it is what the translation bundle addresses ({ns}.objects.{obj}._actions.{name}.confirmText), matching @objectstack/spec's action surface. A structured confirm object ({ title, message, ... }) was retired in objectui#4314: it had no translation key, so its dialogs could never be localized.

Dialog Actions

Open a modal or dialog:

import type { ActionSchema } from '@object-ui/types';

const dialogAction: ActionSchema = {
  type: 'action',
  label: 'Edit Details',
  actionType: 'dialog',
  dialog: {
    title: 'Edit Record',
    size: 'lg',
    content: {
      type: 'form',
      fields: [
        { name: 'name', type: 'input', label: 'Name' },
        { name: 'email', type: 'input', label: 'Email' }
      ]
    },
    actions: [
      {
        type: 'action',
        label: 'Save',
        actionType: 'ajax',
        api: '/api/records/123',
        method: 'PUT'
      }
    ]
  }
};

Action Params (input collection)

An action may declare params (spec ActionParamSchema) to collect user input in a dialog before it runs. Each param renders through the same field-widget renderer the object form uses, so a param of any form-supported field type — select, lookup, date, file, image, richtext, color, address, … — gets its real widget, not a text box (ADR-0059):

{
  "name": "approve",
  "label": "Approve",
  "params": [
    { "name": "comment", "type": "textarea", "label": "Comment", "required": true },
    { "name": "attachments", "type": "file", "multiple": true, "accept": ["application/pdf"] },
    { "name": "assignee", "field": "owner_id" },
    { "name": "notify", "type": "boolean", "label": "Notify the requester", "defaultValue": true }
  ]
}

Inline params declare name + type (any spec FieldType), plus widget config: options, multiple, accept, maxSize, placeholder, helpText, defaultValue.
Field-backed params declare field (+ optional objectOverride) and inherit label, type, options, lookup picker config, multiple, accept, and maxSize from the object's field definition; inline properties override.
required blocks submit while the value is empty; visible (a CEL predicate over features / current_user / app / data) hides a param entirely — e.g. gate a param on an opt-in server capability.
Values are passed through to the action exactly as the widget emits them (number → number, date → YYYY-MM-DD, lookup → record id(s), file → uploaded file descriptor(s); arrays when multiple).

File/image params upload through the ambient UploadProvider; lookup/user params query through the surrounding SchemaRendererContext data source — no extra wiring per action. While a file/image upload is in flight the dialog's Confirm button is disabled (labelled "Uploading…"), so a param can't be submitted before its uploaded fileId is ready.

Action Chaining

Execute multiple actions in sequence or parallel:

import type { ActionSchema } from '@object-ui/types';

const chainedAction: ActionSchema = {
  type: 'action',
  label: 'Process Order',
  actionType: 'ajax',
  api: '/api/orders/process',
  method: 'POST',
  
  chain: [
    {
      type: 'action',
      label: 'Send Email',
      actionType: 'ajax',
      api: '/api/emails/send',
      method: 'POST'
    },
    {
      type: 'action',
      label: 'Update Inventory',
      actionType: 'ajax',
      api: '/api/inventory/update',
      method: 'PUT'
    },
    {
      type: 'action',
      label: 'Log Event',
      actionType: 'ajax',
      api: '/api/events/log',
      method: 'POST'
    }
  ],
  
  chainMode: 'sequential'  // or 'parallel'
};

Chain Modes:

sequential - Execute actions one after another (default)
parallel - Execute all actions simultaneously

Conditional Execution

condition is a gate, not a branch: the action executes only while the predicate holds.

import type { ActionSchema } from '@object-ui/types';

const gatedAction: ActionSchema = {
  type: 'action',
  label: 'Require Manager Approval',
  actionType: 'confirm',
  confirmText: 'Amount exceeds $1000. Manager approval needed.',

  // Offered only for amounts over 1000
  condition: '${data.amount > 1000}'
};

How the gate is written - four spellings, all read by the same evaluator:

Spelling	Example
Boolean	`condition: false`
Bare CEL predicate	`condition: 'data.amount > 1000'`
`${...}` template	`condition: '${data.amount > 1000}'`
Normalized envelope	`condition: { dialect: 'cel', source: 'data.amount > 1000' }`

How the gate is read:

Declared and false - the action does not execute; the runner reports Action condition not met.
Declared and true - the action executes normally.
Not declared (key absent, or an empty predicate) - the action executes.

The envelope is what objectstack build emits for a compiled predicate, so authored metadata and built metadata both parse. This is the same predicate vocabulary visible and disabled carry.

Branching: one action per branch

There is no then / else - a branch is expressed as separate actions with mutually exclusive conditions. Each action is gated on its own, so exactly one of them runs:

import type { ActionSchema } from '@object-ui/types';

const approvalActions: ActionSchema[] = [
  {
    type: 'action',
    label: 'Require Manager Approval',
    actionType: 'confirm',
    confirmText: 'Amount exceeds $1000. Manager approval needed.',
    condition: '${data.amount > 1000}'
  },
  {
    type: 'action',
    label: 'Auto Approve',
    actionType: 'ajax',
    api: '/api/approve',
    method: 'POST',
    condition: '${data.amount <= 1000}'
  }
];

Sibling actions - a toolbar's actions, a table's rowActions / batchActions, or an event's action list - are each dispatched through their own gate, which is what makes this an either/or.

A chain step also carries its own condition, but a sequential chain stops at the first step whose condition does not hold (a blocked step reports Action condition not met, and sequential chaining stops on the first failure). So use a step condition to gate an optional follow-up, and sibling actions for an either/or.

Retired (objectui#3917): condition used to be documented here as { expression, then, else }. Nothing ever read expression, then or else. The runner has always read this key as the predicate above, and an object without a source reads as "no gate declared", so an action written that way ran unconditionally, with no error at author time and no diagnostic at runtime. The shape is now refused by ActionSchema's zod schema instead of being accepted and ignored.

Post-success behaviour

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

What to write instead:

A notice — successMessage / errorMessage, plain strings (the runner surfaces successMessage as a toast after a successful action).
Post-success navigation — the spec's onSuccess block, { navigate, openIn }, declared on UIActionSchema and forwarded to the runner (objectui#5934). It is a spec key, not a member of this legacy type, so it is not shown in a fence here.
Follow-up work — chain (see Action Chaining): declared actions, not callbacks.

Action Tracking

Track actions for analytics:

import type { ActionSchema } from '@object-ui/types';

const trackedAction: ActionSchema = {
  type: 'action',
  label: 'Download Report',
  actionType: 'ajax',
  api: '/api/reports/download',
  
  tracking: {
    enabled: true,
    event: 'report_downloaded',
    metadata: {
      reportType: 'sales',
      format: 'pdf',
      dateRange: '2024-01'
    }
  }
};

Retry Logic

Automatically retry failed requests:

import type { ActionSchema } from '@object-ui/types';

const retryAction: ActionSchema = {
  type: 'action',
  label: 'Submit',
  actionType: 'ajax',
  api: '/api/submit',
  method: 'POST',
  
  timeout: 30000,  // 30 seconds
  
  retry: {
    maxAttempts: 3,
    delay: 1000  // 1 second between retries
  }
};

Complete Example

A comprehensive action combining multiple features:

import type { ActionSchema } from '@object-ui/types';

const complexAction: ActionSchema = {
  type: 'action',
  label: 'Process Order',
  icon: 'shopping-cart',
  variant: 'default',
  
  // Confirm before processing
  actionType: 'confirm',
  confirmText: 'Process this order for ${data.customerName}?',
  
  // Execution gate - this action is the premium path; the standard path is a
  // sibling action carrying the opposite predicate
  condition: '${data.totalAmount > 1000}',
  
  // Action chain
  chain: [
    {
      type: 'action',
      label: 'Send Confirmation Email',
      actionType: 'ajax',
      api: '/api/emails/order-confirmation',
      method: 'POST',
      data: {
        orderId: '${data.id}',
        customerEmail: '${data.customerEmail}'
      }
    },
    {
      type: 'action',
      label: 'Update Inventory',
      actionType: 'ajax',
      api: '/api/inventory/update',
      method: 'PUT',
      data: {
        items: '${data.items}'
      }
    },
    {
      type: 'action',
      label: 'Create Invoice',
      actionType: 'ajax',
      api: '/api/invoices/create',
      method: 'POST'
    }
  ],
  chainMode: 'sequential',
  
  // Notices
  successMessage: 'Order processed successfully!',
  errorMessage: 'Unable to process order. Please try again.',
  
  // Tracking
  tracking: {
    enabled: true,
    event: 'order_processed',
    metadata: {
      source: 'web_app',
      amount: '${data.totalAmount}'
    }
  },
  
  // Retry
  timeout: 60000,
  retry: {
    maxAttempts: 3,
    delay: 2000
  },
  
  // Post-action behavior
  reload: true,
  close: true,
  redirect: '/orders/success'
};

Runtime Validation

import { ActionSchema } from '@object-ui/types/zod';

const myAction = {
  type: 'action',
  label: 'Delete Record',
  actionType: 'confirm',
  confirmText: 'Are you sure?',
};

const result = ActionSchema.safeParse(myAction);

if (result.success) {
  console.log('Valid action configuration');
} else {
  console.error('Validation errors:', result.error);
}

Use Cases

Enhanced Actions are ideal for:

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

Best Practices

Use confirm for destructive actions - Always confirm delete, archive, etc.
Provide clear feedback - Set successMessage / errorMessage so users learn what happened
Chain related operations - Group logically related API calls
Track important events - Enable tracking for business-critical actions
Set appropriate timeouts - Don't let users wait indefinitely
Retry transient failures - Use retry for network-related errors
Keep chains short - Long chains can be hard to debug

Building a CRUD App - CRUD operations with actions
Form - Form submission actions
Data Source - API integration

Enhanced Actions

Action Button Variants

Confirmation Dialog

Action Toolbar

On this page