@object-ui/types 3.1.5 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/types",
-  "version": "3.1.5",
+  "version": "3.3.0",
   "description": "Pure TypeScript type definitions for Object UI - The Protocol Layer",
   "type": "module",
   "sideEffects": false,
@@ -76,11 +76,11 @@
     "directory": "packages/types"
   },
   "dependencies": {
-    "@objectstack/spec": "^3.3.0",
+    "@objectstack/spec": "^4.0.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^6.0.2"
   },
   "scripts": {
     "build": "tsc",

package/src/app.ts

@@ -55,8 +55,8 @@ export interface NavigationItem {
   /** Navigation item type */
   type: NavigationItemType;
 
-  /** Display label (plain string or I18nLabel object for internationalization) */
-  label: string | { key: string; defaultValue?: string; params?: Record<string, any> };
+  /** Display label (plain string per @objectstack/spec v4 protocol) */
+  label: string;
 
   /** Icon name (Lucide) */
   icon?: string;
@@ -129,8 +129,8 @@ export interface NavigationArea {
   /** Unique identifier */
   id: string;
 
-  /** Display label (plain string or I18nLabel object for internationalization) */
-  label: string | { key: string; defaultValue?: string; params?: Record<string, any> };
+  /** Display label (plain string per @objectstack/spec v4 protocol) */
+  label: string;
 
   /** Icon name (Lucide) */
   icon?: string;

package/src/complex.ts

@@ -401,7 +401,7 @@ export interface ChatMessage {
   /**
    * Message role
    */
-  role: 'user' | 'assistant' | 'system';
+  role: 'user' | 'assistant' | 'system' | 'tool';
   /**
    * Message content
    */
@@ -414,6 +414,40 @@ export interface ChatMessage {
    * Message metadata
    */
   metadata?: any;
+  /**
+   * Whether this message is currently being streamed
+   */
+  streaming?: boolean;
+  /**
+   * Tool invocations associated with this message (for tool-calling flows)
+   */
+  toolInvocations?: ChatToolInvocation[];
+}
+
+/**
+ * Represents a tool invocation from an AI assistant message
+ */
+export interface ChatToolInvocation {
+  /**
+   * Unique tool call identifier
+   */
+  toolCallId: string;
+  /**
+   * Name of the tool being invoked
+   */
+  toolName: string;
+  /**
+   * Arguments passed to the tool
+   */
+  args: Record<string, unknown>;
+  /**
+   * Result of the tool invocation (set when complete)
+   */
+  result?: unknown;
+  /**
+   * Tool invocation state
+   */
+  state: 'partial-call' | 'call' | 'result';
 }
 
 /**
@@ -460,6 +494,106 @@ export interface ChatbotSchema extends BaseSchema {
    * Chat height
    */
   height?: string | number;
+
+  // --- AI / service-ai integration fields ---
+
+  /**
+   * Backend API endpoint for chat (e.g., '/api/v1/ai/chat').
+   * When set, the chatbot uses streaming SSE via the vercel/ai SDK.
+   * When not set, the chatbot falls back to local auto-response mode (legacy/demo).
+   */
+  api?: string;
+  /**
+   * Conversation ID for multi-turn context.
+   * Sent to the backend as an `x-conversation-id` HTTP header.
+   */
+  conversationId?: string;
+  /**
+   * System prompt to configure assistant behavior.
+   */
+  systemPrompt?: string;
+  /**
+   * AI model identifier (e.g., 'gpt-4o', 'claude-3-opus').
+   */
+  model?: string;
+  /**
+   * Whether streaming is enabled for AI responses.
+   * @default true
+   */
+  streamingEnabled?: boolean;
+  /**
+   * Additional headers to send with API requests (e.g., auth tokens).
+   */
+  headers?: Record<string, string>;
+  /**
+   * Additional body parameters to include with each API request.
+   */
+  requestBody?: Record<string, unknown>;
+  /**
+   * Maximum number of tool-calling round-trips per user message.
+   * @default 5
+   */
+  maxToolRoundtrips?: number;
+  /**
+   * Callback when an error occurs during streaming or API calls.
+   */
+  onError?: (error: Error) => void;
+
+  // --- Floating / FAB display mode ---
+
+  /**
+   * Display mode for the chatbot.
+   * - `'inline'` (default): Embedded in the page flow.
+   * - `'floating'`: Rendered as a floating action button (FAB) that opens a panel overlay.
+   */
+  displayMode?: 'inline' | 'floating';
+
+  /**
+   * Configuration for floating display mode.
+   * Only used when `displayMode` is `'floating'`.
+   */
+  floatingConfig?: FloatingChatbotConfig;
+}
+
+/**
+ * Configuration for the floating chatbot FAB widget.
+ */
+export interface FloatingChatbotConfig {
+  /**
+   * Position of the FAB trigger button.
+   * @default 'bottom-right'
+   */
+  position?: 'bottom-right' | 'bottom-left';
+  /**
+   * Whether the panel is open by default on mount.
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Width of the floating panel.
+   * @default 400
+   */
+  panelWidth?: number;
+  /**
+   * Height of the floating panel.
+   * @default 520
+   */
+  panelHeight?: number;
+  /**
+   * Title displayed in the panel header.
+   * @default 'Chat'
+   */
+  title?: string;
+  /**
+   * Custom icon name for the FAB trigger (Lucide icon name).
+   * @default 'MessageCircle'
+   */
+  triggerIcon?: string;
+  /**
+   * Custom size for the FAB trigger button in pixels.
+   * @default 56
+   */
+  triggerSize?: number;
 }
 
 /**

package/src/data.ts

@@ -322,6 +322,42 @@ export interface DataSource<T = any> {
    * @returns Promise resolving to aggregated results
    */
   aggregate?(resource: string, params: AggregateParams): Promise<AggregateResult[]>;
+
+  /**
+   * Subscribe to mutation events.
+   * When implemented, data-bound views (ListView, ObjectView) can auto-refresh
+   * after any create/update/delete operation on relevant resources.
+   *
+   * @param callback - Invoked after each successful mutation
+   * @returns Unsubscribe function to remove the listener
+   *
+   * @example
+   * ```typescript
+   * const unsub = dataSource.onMutation?.((event) => {
+   *   if (event.resource === 'contacts') {
+   *     refreshList();
+   *   }
+   * });
+   * // later…
+   * unsub?.();
+   * ```
+   */
+  onMutation?(callback: (event: MutationEvent<T>) => void): () => void;
+}
+
+/**
+ * Describes a mutation that occurred on a DataSource.
+ * Emitted by `DataSource.onMutation` subscribers after create/update/delete.
+ */
+export interface MutationEvent<T = any> {
+  /** The type of mutation that occurred */
+  type: 'create' | 'update' | 'delete';
+  /** The resource (object) name that was mutated */
+  resource: string;
+  /** The affected record (present for create/update) */
+  record?: T;
+  /** The ID of the affected record (present for update/delete) */
+  id?: string | number;
 }
 
 /**

package/src/designer.ts

@@ -632,6 +632,172 @@ export interface DashboardConfig {
   [key: string]: any;
 }
 
+// ============================================================================
+// Object Manager (Enterprise Metadata Management)
+// ============================================================================
+
+/** Object definition for the Object Manager */
+export interface ObjectDefinition {
+  /** Unique object identifier */
+  id: string;
+  /** API name (snake_case) */
+  name: string;
+  /** Display label */
+  label: string;
+  /** Plural display label */
+  pluralLabel?: string;
+  /** Object description */
+  description?: string;
+  /** Icon name (Lucide icon) */
+  icon?: string;
+  /** Grouping/category */
+  group?: string;
+  /** Sort order within group */
+  sortOrder?: number;
+  /** Whether this is a system object (non-deletable) */
+  isSystem?: boolean;
+  /** Whether this object is enabled/active */
+  enabled?: boolean;
+  /** Field count (read-only, for display) */
+  fieldCount?: number;
+  /** Relationships to other objects */
+  relationships?: ObjectDefinitionRelationship[];
+}
+
+/** Relationship reference for Object Manager */
+export interface ObjectDefinitionRelationship {
+  /** Related object name */
+  relatedObject: string;
+  /** Relationship type */
+  type: 'one-to-one' | 'one-to-many' | 'many-to-one' | 'many-to-many';
+  /** Relationship label */
+  label?: string;
+  /** Foreign key field */
+  foreignKey?: string;
+}
+
+/** Object Manager component schema */
+export interface ObjectManagerSchema extends BaseSchema {
+  type: 'object-manager';
+  /** List of object definitions */
+  objects: ObjectDefinition[];
+  /** Read-only mode */
+  readOnly?: boolean;
+  /** Show system objects */
+  showSystemObjects?: boolean;
+}
+
+// ============================================================================
+// Field Designer (Field Configuration Wizard)
+// ============================================================================
+
+/** Supported field types in the Field Designer */
+export type DesignerFieldType =
+  | 'text'
+  | 'textarea'
+  | 'number'
+  | 'boolean'
+  | 'date'
+  | 'datetime'
+  | 'time'
+  | 'select'
+  | 'email'
+  | 'phone'
+  | 'url'
+  | 'password'
+  | 'currency'
+  | 'percent'
+  | 'lookup'
+  | 'formula'
+  | 'autonumber'
+  | 'file'
+  | 'image'
+  | 'markdown'
+  | 'html'
+  | 'color'
+  | 'code'
+  | 'location'
+  | 'address'
+  | 'rating'
+  | 'slider';
+
+/** Select option for field designer */
+export interface DesignerFieldOption {
+  /** Option label */
+  label: string;
+  /** Option value */
+  value: string;
+  /** Option color (for badge display) */
+  color?: string;
+}
+
+/** Validation rule for field designer */
+export interface DesignerValidationRule {
+  /** Rule type */
+  type: 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern' | 'custom';
+  /** Rule value */
+  value: string | number;
+  /** Error message */
+  message?: string;
+}
+
+/** Field definition for the Field Designer */
+export interface DesignerFieldDefinition {
+  /** Unique field identifier */
+  id: string;
+  /** API name (snake_case) */
+  name: string;
+  /** Display label */
+  label: string;
+  /** Field type */
+  type: DesignerFieldType;
+  /** Field group/section */
+  group?: string;
+  /** Sort order within group */
+  sortOrder?: number;
+  /** Field description / help text */
+  description?: string;
+  /** Whether field is required */
+  required?: boolean;
+  /** Whether field is unique */
+  unique?: boolean;
+  /** Whether field is read-only */
+  readonly?: boolean;
+  /** Whether field is hidden */
+  hidden?: boolean;
+  /** Default value */
+  defaultValue?: unknown;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Select options (for select type) */
+  options?: DesignerFieldOption[];
+  /** Validation rules */
+  validationRules?: DesignerValidationRule[];
+  /** Whether this is a system field */
+  isSystem?: boolean;
+  /** External ID flag */
+  externalId?: boolean;
+  /** Track field history */
+  trackHistory?: boolean;
+  /** Whether field is indexed */
+  indexed?: boolean;
+  /** Lookup reference object (for lookup type) */
+  referenceTo?: string;
+  /** Formula expression (for formula type) */
+  formula?: string;
+}
+
+/** Field Designer component schema */
+export interface FieldDesignerSchema extends BaseSchema {
+  type: 'field-designer';
+  /** Object name this field designer belongs to */
+  objectName: string;
+  /** List of field definitions */
+  fields: DesignerFieldDefinition[];
+  /** Read-only mode */
+  readOnly?: boolean;
+}
+
 // ============================================================================
 // Multi-User Collaborative Editing
 // ============================================================================

package/src/index.ts

@@ -249,7 +249,9 @@ export type {
   DashboardWidgetSchema,
   DashboardSchema,
   ChatMessage,
+  ChatToolInvocation,
   ChatbotSchema,
+  FloatingChatbotConfig,
   ComplexSchema,
 } from './complex';
 
@@ -268,6 +270,7 @@ export type {
   FileUploadResult,
   AggregateParams,
   AggregateResult,
+  MutationEvent,
 } from './data';
 
 // ============================================================================
@@ -567,6 +570,14 @@ export type {
   DashboardWidgetType,
   DashboardWidgetConfig,
   DashboardConfig,
+  ObjectDefinition,
+  ObjectDefinitionRelationship,
+  ObjectManagerSchema,
+  DesignerFieldType,
+  DesignerFieldOption,
+  DesignerValidationRule,
+  DesignerFieldDefinition,
+  FieldDesignerSchema,
 } from './designer';
 
 export {

package/src/objectql.ts

@@ -1755,6 +1755,14 @@ export interface ListViewSchema extends BaseSchema {
    * @default false
    */
   allowPrinting?: boolean;
+
+  /**
+   * External refresh trigger.
+   * Increment this value to force the ListView to re-fetch data.
+   * Used by parent components (e.g., ObjectView) to signal that a mutation
+   * (create/update/delete) has occurred and the list should refresh.
+   */
+  refreshTrigger?: number;
 }
 export interface ObjectMapSchema extends BaseSchema {
   type: 'object-map';

package/src/zod/complex.zod.ts

@@ -192,12 +192,22 @@ export const CarouselSchema = BaseSchema.extend({
 /**
  * Chat Message Schema
  */
+export const ChatToolInvocationSchema = z.object({
+  toolCallId: z.string().describe('Unique tool call identifier'),
+  toolName: z.string().describe('Name of the tool'),
+  args: z.record(z.string(), z.unknown()).describe('Tool arguments'),
+  result: z.unknown().optional().describe('Tool result'),
+  state: z.enum(['partial-call', 'call', 'result']).describe('Tool invocation state'),
+});
+
 export const ChatMessageSchema = z.object({
   id: z.string().describe('Message ID'),
-  role: z.enum(['user', 'assistant', 'system']).describe('Message role'),
+  role: z.enum(['user', 'assistant', 'system', 'tool']).describe('Message role'),
   content: z.string().describe('Message content'),
   timestamp: z.union([z.string(), z.date()]).optional().describe('Message timestamp'),
   metadata: z.record(z.string(), z.any()).optional().describe('Custom metadata'),
+  streaming: z.boolean().optional().describe('Whether message is being streamed'),
+  toolInvocations: z.array(ChatToolInvocationSchema).optional().describe('Tool invocations'),
 });
 
 /**
@@ -214,6 +224,15 @@ export const ChatbotSchema = BaseSchema.extend({
   assistantAvatar: z.string().optional().describe('Assistant avatar URL'),
   markdown: z.boolean().optional().describe('Enable markdown rendering'),
   height: z.union([z.string(), z.number()]).optional().describe('Chatbot height'),
+  api: z.string().optional().describe('Backend API endpoint for streaming chat'),
+  conversationId: z.string().optional().describe('Conversation ID for multi-turn context'),
+  systemPrompt: z.string().optional().describe('System prompt for assistant behavior'),
+  model: z.string().optional().describe('AI model identifier'),
+  streamingEnabled: z.boolean().optional().describe('Enable streaming responses'),
+  headers: z.record(z.string(), z.string()).optional().describe('Additional API headers'),
+  body: z.record(z.string(), z.unknown()).optional().describe('Additional API body params'),
+  maxToolRoundtrips: z.number().optional().describe('Max tool-calling round-trips'),
+  onError: z.function().optional().describe('Error callback'),
 });
 
 /**

package/src/zod/index.zod.ts

@@ -225,6 +225,7 @@ export {
   FilterBuilderSchema,
   CarouselItemSchema,
   CarouselSchema,
+  ChatToolInvocationSchema,
   ChatMessageSchema,
   ChatbotSchema,
   DashboardWidgetLayoutSchema,