@object-ui/types 3.0.2 → 3.1.0

package/src/record-components.ts

@@ -0,0 +1,188 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * @object-ui/types - Record Component Schemas
+ *
+ * Type definitions for record:* page components.
+ * Aligned with @objectstack/spec RecordDetailsProps, RecordRelatedListProps,
+ * RecordHighlightsProps, RecordActivityProps, RecordChatterProps, RecordPathProps.
+ *
+ * @module record-components
+ * @packageDocumentation
+ */
+
+/**
+ * ARIA props shared across all record components.
+ * Aligned with @objectstack/spec AriaPropsSchema.
+ */
+export interface RecordComponentAriaProps {
+  ariaLabel?: string;
+  ariaDescribedBy?: string;
+  role?: string;
+}
+
+// ============================================================================
+// record:details — Record Detail Panel
+// ============================================================================
+
+/**
+ * Props for the record:details page component.
+ * Displays a record's fields in a structured detail layout.
+ * Aligned with @objectstack/spec RecordDetailsProps.
+ */
+export interface RecordDetailsComponentProps {
+  /** Number of columns for field layout (1-4) */
+  columns?: number;
+  /** Detail layout mode */
+  layout?: 'stacked' | 'inline' | 'compact';
+  /** Sections to organize fields */
+  sections?: Array<{
+    label?: string;
+    fields: string[];
+    collapsible?: boolean;
+    collapsed?: boolean;
+  }>;
+  /** Specific fields to display (overrides auto-detection from object) */
+  fields?: string[];
+  /** ARIA accessibility attributes */
+  aria?: RecordComponentAriaProps;
+}
+
+// ============================================================================
+// record:highlights — Key Field Summary
+// ============================================================================
+
+/**
+ * Props for the record:highlights page component.
+ * Shows key fields as a summary/highlights panel (e.g., top of detail page).
+ * Aligned with @objectstack/spec RecordHighlightsProps.
+ */
+export interface RecordHighlightsComponentProps {
+  /** Fields to display as highlights */
+  fields: string[];
+  /** Layout mode for highlights display */
+  layout?: 'horizontal' | 'vertical' | 'grid';
+  /** ARIA accessibility attributes */
+  aria?: RecordComponentAriaProps;
+}
+
+// ============================================================================
+// record:related_list — Related Records Table
+// ============================================================================
+
+/**
+ * Props for the record:related_list page component.
+ * Displays a list of related records via a relationship field.
+ * Aligned with @objectstack/spec RecordRelatedListProps.
+ */
+export interface RecordRelatedListComponentProps {
+  /** Related object name */
+  objectName: string;
+  /** Field on the related object that links back to this record */
+  relationshipField: string;
+  /** Columns to display in the related list */
+  columns?: string[];
+  /** Sort configuration */
+  sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
+  /** Maximum records to display */
+  limit?: number;
+  /** Filter conditions */
+  filter?: any;
+  /** Section title */
+  title?: string;
+  /** Show "View All" link */
+  showViewAll?: boolean;
+  /** Available actions for the related list */
+  actions?: string[];
+  /** ARIA accessibility attributes */
+  aria?: RecordComponentAriaProps;
+}
+
+// ============================================================================
+// record:activity — Activity Timeline
+// ============================================================================
+
+/**
+ * Props for the record:activity page component.
+ * Displays an activity feed/timeline for a record.
+ * Aligned with @objectstack/spec RecordActivityProps.
+ */
+export interface RecordActivityComponentProps {
+  /** Activity types to display */
+  types?: string[];
+  /** Filter mode for activity types */
+  filterMode?: string;
+  /** Show filter toggle UI */
+  showFilterToggle?: boolean;
+  /** Maximum activities to display */
+  limit?: number;
+  /** Show completed/resolved activities */
+  showCompleted?: boolean;
+  /** Merge all activity types into a single timeline */
+  unifiedTimeline?: boolean;
+  /** Show comment input box */
+  showCommentInput?: boolean;
+  /** Enable @mentions in comments */
+  enableMentions?: boolean;
+  /** Enable emoji reactions on activities */
+  enableReactions?: boolean;
+  /** Enable threaded comment replies */
+  enableThreading?: boolean;
+  /** Show subscribe/unsubscribe toggle */
+  showSubscriptionToggle?: boolean;
+  /** ARIA accessibility attributes */
+  aria?: RecordComponentAriaProps;
+}
+
+// ============================================================================
+// record:chatter — Comments & Discussion
+// ============================================================================
+
+/**
+ * Props for the record:chatter page component.
+ * Provides a chat/discussion panel for a record.
+ * Aligned with @objectstack/spec RecordChatterProps.
+ */
+export interface RecordChatterComponentProps {
+  /** Panel position */
+  position?: 'bottom' | 'right' | 'left';
+  /** Panel width (CSS value) */
+  width?: string;
+  /** Whether the chatter panel is collapsible */
+  collapsible?: boolean;
+  /** Whether the chatter panel starts collapsed */
+  defaultCollapsed?: boolean;
+  /** Activity feed configuration within chatter */
+  feed?: RecordActivityComponentProps;
+  /** ARIA accessibility attributes */
+  aria?: RecordComponentAriaProps;
+}
+
+// ============================================================================
+// record:path — Record Path / Progress Indicator
+// ============================================================================
+
+/**
+ * Props for the record:path page component.
+ * Displays a progress/stage indicator for the record (e.g., Lead → Qualified → Won).
+ * Aligned with @objectstack/spec RecordPathProps.
+ */
+export interface RecordPathComponentProps {
+  /** Field that holds the current status/stage value */
+  statusField: string;
+  /** Ordered list of stages */
+  stages: Array<{
+    /** Stage value (matches statusField values) */
+    value: string;
+    /** Display label for the stage */
+    label: string;
+  }>;
+  /** ARIA accessibility attributes */
+  aria?: RecordComponentAriaProps;
+}

package/src/reports.ts

@@ -69,6 +69,16 @@ export interface ReportField {
    * Sort order
    */
   sortOrder?: number;
+
+  /**
+   * Custom render style (e.g., 'badge' for status fields)
+   */
+  renderAs?: 'badge' | 'text';
+
+  /**
+   * Color mapping for badge rendering (value → CSS class or color)
+   */
+  colorMap?: Record<string, string>;
 }
 
 /**
@@ -246,6 +256,14 @@ export interface ReportExportConfig {
   options?: Record<string, any>;
 }
 
+/**
+ * Report Type
+ * - tabular: flat table
+ * - summary: grouped with subtotals
+ * - matrix: pivot table
+ */
+export type ReportType = 'tabular' | 'summary' | 'matrix';
+
 /**
  * Report Schema - Main report configuration
  */
@@ -262,6 +280,11 @@ export interface ReportSchema extends BaseSchema {
    */
   description?: string;
 
+  /**
+   * Report type (tabular, summary, matrix)
+   */
+  reportType?: ReportType;
+
   /**
    * Data source configuration
    */
@@ -331,6 +354,26 @@ export interface ReportSchema extends BaseSchema {
    * Report data
    */
   data?: any[];
+
+  /**
+   * Conditional formatting rules
+   */
+  conditionalFormatting?: Array<{
+    field: string;
+    operator: 'equals' | 'not_equals' | 'contains' | 'greater_than' | 'less_than';
+    value: any;
+    backgroundColor?: string;
+    textColor?: string;
+  }>;
+
+  /**
+   * Chart configuration (visual chart editor output)
+   */
+  chartConfig?: {
+    chartType?: string;
+    xAxisField?: string;
+    yAxisFields?: string[];
+  };
 }
 
 /**

package/src/theme.ts

@@ -78,6 +78,12 @@ export type { ZIndex } from '@objectstack/spec/ui';
  */
 export type { ThemeMode } from '@objectstack/spec/ui';
 
+/**
+ * Theme Mode Schema
+ * Canonical Zod schema from @objectstack/spec/ui.
+ */
+export type { ThemeModeSchema } from '@objectstack/spec/ui';
+
 // Import spec types for local use in interfaces below
 import type {
   ColorPalette,

package/src/views.ts

@@ -20,11 +20,12 @@ import type { BaseSchema, SchemaNode } from './base';
 import type { ActionSchema } from './crud';
 import type { TableColumn } from './data-display';
 import type { FormField } from './form';
+import type { SelectOptionMetadata } from './field-types';
 
 /**
  * View Type
  */
-export type ViewType = 'list' | 'detail' | 'grid' | 'kanban' | 'calendar' | 'timeline' | 'map';
+export type ViewType = 'list' | 'detail' | 'grid' | 'kanban' | 'calendar' | 'timeline' | 'map' | 'gallery' | 'gantt';
 
 /**
  * Detail View Field Configuration
@@ -39,9 +40,14 @@ export interface DetailViewField {
    */
   label?: string;
   /**
-   * Field type for rendering
+   * Field type for rendering.
+   * Supports both display-oriented types (image, link, badge, json, html, markdown, custom)
+   * and data-oriented types (number, currency, percent, boolean, select, lookup, master_detail,
+   * email, url, phone, user) for type-aware cell rendering via getCellRenderer.
    */
-  type?: 'text' | 'image' | 'link' | 'badge' | 'date' | 'datetime' | 'json' | 'html' | 'markdown' | 'custom';
+  type?: 'text' | 'number' | 'currency' | 'percent' | 'boolean' | 'select' | 'lookup' | 'master_detail'
+    | 'email' | 'url' | 'phone' | 'user'
+    | 'image' | 'link' | 'badge' | 'date' | 'datetime' | 'json' | 'html' | 'markdown' | 'custom';
   /**
    * Format string (e.g., date format)
    */
@@ -66,6 +72,22 @@ export interface DetailViewField {
    * Span across columns (for grid layout)
    */
   span?: number;
+  /**
+   * Options for select/lookup fields
+   */
+  options?: SelectOptionMetadata[];
+  /**
+   * Referenced object name for lookup/master_detail fields
+   */
+  reference_to?: string;
+  /**
+   * Display field on the referenced object for lookup/master_detail fields
+   */
+  reference_field?: string;
+  /**
+   * Currency code for currency fields (e.g. 'USD', 'EUR')
+   */
+  currency?: string;
 }
 
 /**
@@ -114,6 +136,11 @@ export interface DetailViewSection {
    * @example 'muted', 'primary/10'
    */
   headerColor?: string;
+  /**
+   * When true, hide fields whose value is null, undefined, or empty string.
+   * If all fields are hidden, the entire section is hidden.
+   */
+  hideEmpty?: boolean;
 }
 
 /**
@@ -146,6 +173,207 @@ export interface DetailViewTab {
   badge?: string | number;
 }
 
+/**
+ * Comment Entry - represents a single comment on a record
+ */
+export interface CommentEntry {
+  /** Unique identifier */
+  id: string | number;
+  /** Comment text */
+  text: string;
+  /** Author display name */
+  author: string;
+  /** Avatar URL (optional) */
+  avatarUrl?: string;
+  /** Timestamp when the comment was created */
+  createdAt: string;
+  /** Whether this comment is pinned/starred */
+  pinned?: boolean;
+  /** Mentioned user IDs extracted from the comment text */
+  mentions?: string[];
+  /** Object/record this comment belongs to (for cross-record search) */
+  objectName?: string;
+  /** Record ID this comment belongs to (for cross-record search) */
+  recordId?: string | number;
+}
+
+/**
+ * Mention notification - delivered when a user is @mentioned in a comment
+ */
+export interface MentionNotification {
+  /** Unique notification ID */
+  id: string;
+  /** Type of notification */
+  type: 'mention';
+  /** ID of the user being notified */
+  recipientId: string;
+  /** The comment that contains the mention */
+  commentId: string | number;
+  /** Author who mentioned the recipient */
+  mentionedBy: string;
+  /** The comment text (or excerpt) */
+  commentText: string;
+  /** Object name the comment belongs to */
+  objectName?: string;
+  /** Record ID the comment belongs to */
+  recordId?: string | number;
+  /** When the mention was created */
+  createdAt: string;
+  /** Whether the notification has been read */
+  read?: boolean;
+  /** Delivery channels */
+  channels?: Array<'in_app' | 'email' | 'push'>;
+}
+
+/**
+ * Comment search result - returned when searching comments across records
+ */
+export interface CommentSearchResult {
+  /** The matching comment */
+  comment: CommentEntry;
+  /** Object name the comment belongs to */
+  objectName: string;
+  /** Record ID the comment belongs to */
+  recordId: string | number;
+  /** Highlighted text snippet with search term marked */
+  highlight?: string;
+}
+
+/**
+ * Activity Entry - represents a single activity/field change on a record
+ */
+export interface ActivityEntry {
+  /** Unique identifier */
+  id: string | number;
+  /** Activity type */
+  type: 'field_change' | 'create' | 'delete' | 'comment' | 'status_change';
+  /** Field that was changed (for field_change type) */
+  field?: string;
+  /** Previous value */
+  oldValue?: any;
+  /** New value */
+  newValue?: any;
+  /** User who made the change */
+  user: string;
+  /** Timestamp of the change */
+  timestamp: string;
+  /** Human-readable description of the change */
+  description?: string;
+}
+
+// ============================================================================
+// Feed / Chatter Protocol Types
+// Aligned with @objectstack/spec FeedItemSchema, MentionSchema, ReactionSchema,
+// FieldChangeEntrySchema, RecordSubscriptionSchema
+// ============================================================================
+
+/**
+ * Feed item type — determines rendering style in the activity timeline.
+ * Aligned with @objectstack/spec FeedItemSchema.type enum.
+ */
+export type FeedItemType = 'comment' | 'field_change' | 'task' | 'event' | 'system' | 'email' | 'call';
+
+/**
+ * FeedItem — A single item in the unified activity feed.
+ * Aligned with @objectstack/spec FeedItemSchema.
+ */
+export interface FeedItem {
+  /** Unique identifier */
+  id: string | number;
+  /** Feed item type */
+  type: FeedItemType;
+  /** Actor / author display name */
+  actor: string;
+  /** Actor avatar URL */
+  actorAvatarUrl?: string;
+  /** Main body / text content (may contain Markdown) */
+  body?: string;
+  /** Creation timestamp (ISO 8601) */
+  createdAt: string;
+  /** Last update timestamp (ISO 8601) */
+  updatedAt?: string;
+  /** Source of the feed item (e.g., 'manual', 'api', 'automation') */
+  source?: string;
+  /** Parent feed item ID (for threading) */
+  parentId?: string | number;
+  /** Number of replies (if this is a root comment) */
+  replyCount?: number;
+  /** Field change entries (for field_change type) */
+  fieldChanges?: FieldChangeEntry[];
+  /** Mentions within this feed item */
+  mentions?: Mention[];
+  /** Reactions on this feed item */
+  reactions?: Reaction[];
+  /** Whether this item is pinned */
+  pinned?: boolean;
+  /** Whether this item has been edited */
+  edited?: boolean;
+}
+
+/**
+ * FieldChangeEntry — A single field change within a feed item.
+ * Aligned with @objectstack/spec FieldChangeEntrySchema.
+ */
+export interface FieldChangeEntry {
+  /** Field API name */
+  field: string;
+  /** Field display label */
+  fieldLabel?: string;
+  /** Previous raw value */
+  oldValue?: unknown;
+  /** New raw value */
+  newValue?: unknown;
+  /** Previous human-readable display value */
+  oldDisplayValue?: string;
+  /** New human-readable display value */
+  newDisplayValue?: string;
+}
+
+/**
+ * Mention — An @mention within a feed item.
+ * Aligned with @objectstack/spec MentionSchema.
+ */
+export interface Mention {
+  /** Mention target type */
+  type: 'user' | 'team' | 'group';
+  /** Mentioned entity ID */
+  id: string;
+  /** Display name */
+  name: string;
+  /** Offset in the body text */
+  offset?: number;
+  /** Length of the mention text */
+  length?: number;
+}
+
+/**
+ * Reaction — An emoji reaction on a feed item.
+ * Aligned with @objectstack/spec ReactionSchema.
+ */
+export interface Reaction {
+  /** Emoji identifier (e.g. '👍', '❤️', '🎉') */
+  emoji: string;
+  /** Number of users who reacted with this emoji */
+  count: number;
+  /** Whether the current user reacted with this emoji */
+  reacted?: boolean;
+  /** IDs of users who reacted */
+  userIds?: string[];
+}
+
+/**
+ * RecordSubscription — Notification subscription state for a record.
+ * Aligned with @objectstack/spec RecordSubscriptionSchema.
+ */
+export interface RecordSubscription {
+  /** Record ID */
+  recordId: string | number;
+  /** Whether the current user is subscribed */
+  subscribed: boolean;
+  /** Notification channels */
+  channels?: Array<'in_app' | 'email' | 'push'>;
+}
+
 /**
  * Detail View Schema - Display detailed information about a single record
  * Enhanced in Phase 2 with better organization and features
@@ -172,6 +400,15 @@ export interface DetailViewSchema extends BaseSchema {
    * Data to display (if not fetching from API)
    */
   data?: any;
+  /**
+   * Primary field name whose value is displayed as the record title in the header.
+   * Falls back to `title` when not set or when the field value is empty.
+   */
+  primaryField?: string;
+  /**
+   * Field names whose values are rendered as summary Badges next to the header title.
+   */
+  summaryFields?: string[];
   /**
    * Layout mode
    */
@@ -274,6 +511,30 @@ export interface DetailViewSchema extends BaseSchema {
      */
     fields?: string[];
   }>;
+  /**
+   * Record navigation configuration for prev/next navigation.
+   * Allows navigating through a result set from within the detail view.
+   */
+  recordNavigation?: {
+    /** All record IDs in the current view's result set */
+    recordIds: Array<string | number>;
+    /** Current record's index in the result set (0-based) */
+    currentIndex: number;
+    /** Callback to navigate to a specific record by ID */
+    onNavigate: (recordId: string | number) => void;
+  };
+  /**
+   * Comments associated with this record
+   */
+  comments?: CommentEntry[];
+  /**
+   * Callback to add a new comment
+   */
+  onAddComment?: (text: string) => void | Promise<void>;
+  /**
+   * Activity history entries for this record
+   */
+  activities?: ActivityEntry[];
 }
 
 /**
@@ -331,6 +592,17 @@ export interface ViewSwitcherSchema extends BaseSchema {
    * Storage key for persisting view
    */
   storageKey?: string;
+  /**
+   * Show "+" button to add/create a new view
+   */
+  allowCreateView?: boolean;
+  /**
+   * Per-view action icons (e.g., share, settings, duplicate, delete)
+   */
+  viewActions?: Array<{
+    type: 'share' | 'settings' | 'duplicate' | 'delete';
+    icon?: string;
+  }>;
 }
 
 /**