@object-ui/types 3.0.2 → 3.1.0

package/src/data-display.ts

@@ -341,6 +341,13 @@ export interface DataTableSchema extends BaseSchema {
    * @default false
    */
   selectable?: boolean | 'single' | 'multiple';
+  /**
+   * Selection checkbox display style
+   * - 'always': Checkboxes are always visible
+   * - 'hover': Checkboxes only appear on row hover
+   * @default 'always'
+   */
+  selectionStyle?: 'always' | 'hover';
   /**
    * Enable column sorting
    * @default true
@@ -388,6 +395,12 @@ export interface DataTableSchema extends BaseSchema {
    * @default false
    */
   editable?: boolean;
+  /**
+   * Enable single-click editing mode
+   * When true with editable, clicking a cell enters edit mode (instead of double-click)
+   * @default false
+   */
+  singleClickEdit?: boolean;
   /**
    * Cell value change handler
    * Called when a cell value is edited
@@ -413,6 +426,41 @@ export interface DataTableSchema extends BaseSchema {
    * Function that returns a CSS class string for each row
    */
   rowClassName?: (row: any, index: number) => string | undefined;
+  /**
+   * Dynamic row inline style
+   * Function that returns CSSProperties for each row (e.g., from conditionalFormatting).
+   */
+  rowStyle?: (row: any, index: number) => React.CSSProperties | undefined;
+  /**
+   * Number of columns to freeze (left-pin)
+   * When set, the first N columns remain fixed while the rest scroll horizontally.
+   * @default 0
+   */
+  frozenColumns?: number;
+  /**
+   * Show row numbers in the first column (Airtable-style)
+   * @default false
+   */
+  showRowNumbers?: boolean;
+  /**
+   * Show "+ Add record" row at the bottom of the table (Airtable-style)
+   * @default false
+   */
+  showAddRow?: boolean;
+  /**
+   * Callback when the "+ Add record" row is clicked
+   */
+  onAddRecord?: () => void;
+  /**
+   * Column resize handler
+   * Called when a column is resized
+   */
+  onColumnResize?: (columnKey: string, width: number) => void;
+  /**
+   * Column reorder handler (new order of accessorKeys)
+   * Called when columns are reordered via drag-and-drop
+   */
+  onColumnReorder?: (newOrder: string[]) => void;
 }
 
 /**
@@ -593,6 +641,64 @@ export interface ChartSchema extends BaseSchema {
   config?: Record<string, any>;
 }
 
+/**
+ * Aggregation function for pivot table values
+ */
+export type PivotAggregation = 'sum' | 'count' | 'avg' | 'min' | 'max';
+
+/**
+ * Pivot table (cross-tabulation) component
+ *
+ * Renders a matrix where rows correspond to one field,
+ * columns to another, and cells show an aggregated value.
+ */
+export interface PivotTableSchema extends BaseSchema {
+  type: 'pivot';
+  /**
+   * Pivot table title
+   */
+  title?: string;
+  /**
+   * Field used for row headers
+   */
+  rowField: string;
+  /**
+   * Field used for column headers
+   */
+  columnField: string;
+  /**
+   * Field whose values are aggregated in cells
+   */
+  valueField: string;
+  /**
+   * Aggregation function applied to valueField
+   * @default 'sum'
+   */
+  aggregation?: PivotAggregation;
+  /**
+   * Source data rows
+   */
+  data: Record<string, unknown>[];
+  /**
+   * Show a totals column on the right
+   * @default false
+   */
+  showRowTotals?: boolean;
+  /**
+   * Show a totals row at the bottom
+   * @default false
+   */
+  showColumnTotals?: boolean;
+  /**
+   * Numeric format string (e.g. "$,.2f") — applied via simple prefix/suffix/decimals
+   */
+  format?: string;
+  /**
+   * Mapping of column header values to Tailwind text-color classes
+   */
+  columnColors?: Record<string, string>;
+}
+
 /**
  * Timeline event
  */
@@ -706,6 +812,7 @@ export type DataDisplaySchema =
   | MarkdownSchema
   | TreeViewSchema
   | ChartSchema
+  | PivotTableSchema
   | TimelineSchema
   | HtmlSchema
   | StatisticSchema

package/src/data.ts

@@ -237,6 +237,19 @@ export interface DataSource<T = any> {
    */
   getView?(objectName: string, viewId: string): Promise<any | null>;
 
+  /**
+   * Persist a view configuration to the backend.
+   * Called when a user saves view settings (columns, filters, sort, toggles, etc.)
+   * from the inline ViewConfigPanel.
+   * Optional — implementations that do not support view persistence may omit this.
+   *
+   * @param objectName - Object name
+   * @param viewId - View identifier (e.g., 'all', 'pipeline')
+   * @param config - The full view configuration to persist
+   * @returns Promise resolving to the persisted config (or void)
+   */
+  updateViewConfig?(objectName: string, viewId: string, config: Record<string, any>): Promise<Record<string, any> | void>;
+
   /**
    * Get an application definition by name or ID.
    * Used by app shells to render server-defined navigation, branding, and layout.
@@ -296,6 +309,42 @@ export interface DataSource<T = any> {
       onProgress?: (percent: number) => void;
     },
   ): Promise<FileUploadResult[]>;
+
+  /**
+   * Perform server-side aggregation on a resource.
+   * Used by chart widgets to offload grouping/aggregation to the backend,
+   * avoiding large data downloads.
+   * Optional — when not implemented, chart components will fall back to
+   * fetching all records via `find()` and aggregating client-side.
+   *
+   * @param resource - Resource name (e.g., 'opportunity')
+   * @param params - Aggregation parameters (field, function, groupBy, filter)
+   * @returns Promise resolving to aggregated results
+   */
+  aggregate?(resource: string, params: AggregateParams): Promise<AggregateResult[]>;
+}
+
+/**
+ * Parameters for server-side aggregation.
+ * Describes how to group and aggregate data on the backend.
+ */
+export interface AggregateParams {
+  /** Field to aggregate (e.g., 'amount') */
+  field: string;
+  /** Aggregation function (e.g., 'sum', 'count', 'avg', 'min', 'max') */
+  function: string;
+  /** Field to group by (e.g., 'stage') */
+  groupBy: string;
+  /** Optional filter to apply before aggregation */
+  filter?: any;
+}
+
+/**
+ * Result of a server-side aggregation.
+ * Each entry represents one group with the aggregated value.
+ */
+export interface AggregateResult {
+  [key: string]: any;
 }
 
 /**

package/src/designer.ts

@@ -393,11 +393,11 @@ export interface ReportDesignerSchema extends BaseSchema {
 }
 
 // ============================================================================
-// View Designer (List View Layout Editor)
+// Unified View Configuration
 // ============================================================================
 
-/** Column configuration for the view designer */
-export interface ViewDesignerColumn {
+/** Column configuration for rich view columns */
+export interface ViewColumnConfig {
   /** Field name */
   field: string;
   /** Display label */
@@ -412,35 +412,224 @@ export interface ViewDesignerColumn {
   order?: number;
 }
 
-/** View designer schema */
-export interface ViewDesignerSchema extends BaseSchema {
-  type: 'view-designer';
-  /** Object name this view is for */
-  objectName: string;
-  /** View identifier (for editing existing views) */
-  viewId?: string;
-  /** View display label */
-  viewLabel?: string;
+/** View type union */
+export type UnifiedViewType = 'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map' | 'chart';
+
+/**
+ * Unified data model for view configuration.
+ *
+ * Used by ViewConfigPanel (create/edit).
+ * Columns may be simple field-name strings or rich ViewColumnConfig objects;
+ * consumers should handle both.
+ */
+export interface UnifiedViewConfig {
+  /** View identifier */
+  id?: string;
+  /** Display label */
+  label?: string;
   /** View type */
-  viewType?: 'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map';
-  /** Columns / fields to display */
-  columns?: ViewDesignerColumn[];
-  /** Filter conditions */
-  filters?: Array<{ field: string; operator: string; value: any }>;
+  type?: UnifiedViewType;
+  /** Column configuration — simple field names or rich ViewColumnConfig objects */
+  columns?: Array<string | ViewColumnConfig>;
+  /** Filter conditions in @objectstack/spec JSON-rules array format */
+  filter?: any[];
   /** Sort configuration */
-  sort?: Array<{ field: string; direction: 'asc' | 'desc' }>;
-  /** Available fields from the object schema */
-  availableFields?: Array<{ name: string; label: string; type: string }>;
-  /** Type-specific options */
-  options?: Record<string, any>;
-  /** Read-only mode */
-  readOnly?: boolean;
-  /** Callback when view config changes */
-  onChange?: string;
-  /** Callback when view is saved */
-  onSave?: string;
-  /** Callback when cancelled */
-  onCancel?: string;
+  sort?: Array<{ field: string; order?: string; direction?: string; id?: string }>;
+  /** Description */
+  description?: string;
+  /** Enable search bar */
+  showSearch?: boolean;
+  /** Enable user filter controls */
+  showFilters?: boolean;
+  /** Enable user sort controls */
+  showSort?: boolean;
+  /** Allow data export */
+  allowExport?: boolean;
+  /** Show view description */
+  showDescription?: boolean;
+  /** Enable "add record via form" action */
+  addRecordViaForm?: boolean;
+  /** Export options */
+  exportOptions?: any;
+
+  // -- Type-specific options (nested per @objectstack/spec protocol) ----------
+
+  /** Kanban-specific options */
+  kanban?: {
+    groupByField?: string;
+    groupField?: string;
+    titleField?: string;
+    columns?: string[];
+  };
+  /** Calendar-specific options */
+  calendar?: {
+    startDateField?: string;
+    endDateField?: string;
+    titleField?: string;
+    colorField?: string;
+    allDayField?: string;
+    defaultView?: string;
+  };
+  /** Map-specific options */
+  map?: {
+    locationField?: string;
+    titleField?: string;
+    latitudeField?: string;
+    longitudeField?: string;
+    zoom?: number;
+    center?: { lat: number; lng: number };
+  };
+  /** Gallery-specific options */
+  gallery?: {
+    imageField?: string;
+    titleField?: string;
+    subtitleField?: string;
+  };
+  /** Timeline-specific options */
+  timeline?: {
+    dateField?: string;
+    titleField?: string;
+    descriptionField?: string;
+  };
+  /** Gantt-specific options */
+  gantt?: {
+    startDateField?: string;
+    endDateField?: string;
+    titleField?: string;
+    progressField?: string;
+    dependenciesField?: string;
+    colorField?: string;
+  };
+  /** Chart-specific options */
+  chart?: {
+    chartType?: string;
+    xAxisField?: string;
+    yAxisFields?: string[];
+    aggregation?: string;
+    series?: any[];
+    config?: any;
+    filter?: any;
+  };
+
+  /** Catch-all for additional properties */
+  [key: string]: any;
+}
+
+// ============================================================================
+// Dashboard Configuration
+// ============================================================================
+
+/** All supported color variants for dashboard widgets */
+export const DASHBOARD_COLOR_VARIANTS = [
+  'default', 'blue', 'teal', 'orange', 'purple', 'success', 'warning', 'danger',
+] as const;
+
+/** Color variant for dashboard widgets */
+export type DashboardColorVariant = (typeof DASHBOARD_COLOR_VARIANTS)[number];
+
+/** All supported widget visualization types */
+export const DASHBOARD_WIDGET_TYPES = [
+  'metric', 'bar', 'line', 'pie', 'donut', 'area', 'scatter', 'table', 'pivot', 'list', 'custom',
+] as const;
+
+/** Widget visualization type */
+export type DashboardWidgetType = (typeof DASHBOARD_WIDGET_TYPES)[number];
+
+/** Layout position for a single dashboard widget */
+export interface DashboardWidgetConfig {
+  /** Widget identifier */
+  id: string;
+  /** Widget title */
+  title?: string;
+  /** Widget description */
+  description?: string;
+  /** Visualization type */
+  type?: DashboardWidgetType;
+  /** Data source object name */
+  object?: string;
+  /** Filter conditions applied to widget data */
+  filter?: any[];
+  /** Category / x-axis field */
+  categoryField?: string;
+  /** Value / y-axis field */
+  valueField?: string;
+  /** Aggregation function (count, sum, avg, min, max) */
+  aggregate?: string;
+  /** Chart-specific configuration */
+  chartConfig?: any;
+  /** Color variant */
+  colorVariant?: DashboardColorVariant;
+  /** Grid layout position */
+  layout?: { x: number; y: number; w: number; h: number };
+  /** Clickable action URL */
+  actionUrl?: string;
+}
+
+/**
+ * Unified data model for dashboard configuration.
+ *
+ * Used by the DashboardConfigPanel for create/edit workflows.
+ * Mirrors the pattern of UnifiedViewConfig for view configuration.
+ */
+export interface DashboardConfig {
+  /** Dashboard identifier */
+  id?: string;
+  /** Display title */
+  title?: string;
+  /** Dashboard description */
+  description?: string;
+  /** Number of grid columns (default: 12) */
+  columns?: number;
+  /** Grid gap in pixels */
+  gap?: number;
+  /** Auto-refresh interval in seconds */
+  refreshInterval?: number;
+  /** Dashboard widgets */
+  widgets?: DashboardWidgetConfig[];
+
+  // -- Global filters --------------------------------------------------------
+
+  /** Global filter conditions applied across all widgets */
+  globalFilters?: any[];
+  /** Date range filter configuration */
+  dateRange?: {
+    enabled?: boolean;
+    field?: string;
+    presets?: string[];
+  };
+  /** User-selectable filter fields */
+  userFilters?: Array<{
+    field: string;
+    label?: string;
+    type?: string;
+  }>;
+
+  // -- Appearance ------------------------------------------------------------
+
+  /** Show dashboard header with title/description */
+  showHeader?: boolean;
+  /** Show global filter bar */
+  showFilters?: boolean;
+  /** Show date range picker */
+  showDateRange?: boolean;
+  /** Action buttons in dashboard header */
+  headerActions?: Array<{
+    label: string;
+    action?: string;
+    icon?: string;
+    variant?: string;
+  }>;
+
+  // -- Accessibility ---------------------------------------------------------
+
+  /** ARIA properties */
+  aria?: {
+    label?: string;
+    description?: string;
+  };
+
+  /** Catch-all for additional properties */
+  [key: string]: any;
 }
 
 // ============================================================================