@object-ui/types 0.5.0 → 3.0.0

package/src/objectql.ts

@@ -22,119 +22,82 @@ import type { BaseSchema } from './base';
 import type { TableColumn } from './data-display';
 import type { FormField } from './form';
 
+// ============================================================================
+// Spec-Canonical Types — imported from @objectstack/spec/ui
+// Rule: "Never Redefine Types. ALWAYS import them."
+// ============================================================================
+
 /**
  * HTTP Method for API requests
+ * Canonical definition from @objectstack/spec/ui.
  */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export type { HttpMethod } from '@objectstack/spec/ui';
 
 /**
  * HTTP Request Configuration for API Provider
- * Aligned with @objectstack/spec HttpRequestSchema
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface HttpRequest {
-  /** API endpoint URL */
-  url: string;
-  /** HTTP method (default: GET) */
-  method?: HttpMethod;
-  /** Custom HTTP headers */
-  headers?: Record<string, string>;
-  /** Query parameters */
-  params?: Record<string, unknown>;
-  /** Request body for POST/PUT/PATCH - supports JSON objects, strings, FormData, or Blob */
-  body?: Record<string, unknown> | string | FormData | Blob;
-}
+export type { HttpRequest } from '@objectstack/spec/ui';
 
 /**
  * View Data Source Configuration
- * Aligned with @objectstack/spec ViewDataSchema
- * 
+ * Canonical definition from @objectstack/spec/ui.
+ *
  * Supports three modes:
  * 1. 'object': Standard Protocol - Auto-connects to ObjectStack Metadata and Data APIs
  * 2. 'api': Custom API - Explicitly provided API URLs
  * 3. 'value': Static Data - Hardcoded data array
  */
-export type ViewData =
-  | {
-      provider: 'object';
-      /** Target object name */
-      object: string;
-    }
-  | {
-      provider: 'api';
-      /** Configuration for fetching data */
-      read?: HttpRequest;
-      /** Configuration for submitting data (for forms/editable tables) */
-      write?: HttpRequest;
-    }
-  | {
-      provider: 'value';
-      /** Static data array */
-      items: unknown[];
-    };
+export type { ViewData } from '@objectstack/spec/ui';
 
 /**
  * List Column Configuration
- * Enhanced version aligned with @objectstack/spec ListColumnSchema
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface ListColumn {
-  /** Field name (snake_case) */
-  field: string;
-  /** Display label override */
-  label?: string;
-  /** Column width in pixels */
-  width?: number;
-  /** Text alignment */
-  align?: 'left' | 'center' | 'right';
-  /** Hide column by default */
-  hidden?: boolean;
-  /** Allow sorting by this column */
-  sortable?: boolean;
-  /** Allow resizing this column */
-  resizable?: boolean;
-  /** Allow text wrapping */
-  wrap?: boolean;
-  /** Renderer type override (e.g., "currency", "date") */
-  type?: string;
-}
+export type { ListColumn } from '@objectstack/spec/ui';
 
 /**
  * Selection Configuration
- * Aligned with @objectstack/spec SelectionConfigSchema
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface SelectionConfig {
-  /** Selection mode */
-  type?: 'none' | 'single' | 'multiple';
-}
+export type { SelectionConfig } from '@objectstack/spec/ui';
 
 /**
  * Pagination Configuration
- * Aligned with @objectstack/spec PaginationConfigSchema
+ * Canonical definition from @objectstack/spec/ui.
  */
-export interface PaginationConfig {
-  /** Number of records per page (default: 25) */
-  pageSize?: number;
-  /** Available page size options */
-  pageSizeOptions?: number[];
-}
+export type { PaginationConfig } from '@objectstack/spec/ui';
+
+// Import spec types for local use in interfaces below
+import type {
+  HttpMethod,
+  HttpRequest,
+  ViewData,
+  ListColumn,
+  SelectionConfig,
+  PaginationConfig,
+  GroupingConfig,
+  RowColorConfig,
+} from '@objectstack/spec/ui';
 
 /**
  * Kanban Configuration
- * Aligned with @objectstack/spec KanbanConfigSchema
+ * Canonical definition from @objectstack/spec/ui (KanbanConfigSchema).
  */
-export interface KanbanConfig {
+export type KanbanConfig = {
   /** Field to group columns by (usually status/select) */
   groupByField: string;
   /** Field to sum at top of column (e.g. amount) */
   summarizeField?: string;
   /** Fields to show on cards */
   columns: string[];
-}
+};
 
 /**
  * Calendar Configuration
- * Aligned with @objectstack/spec CalendarConfigSchema
+ * Canonical definition from @objectstack/spec/ui (CalendarConfigSchema).
  */
-export interface CalendarConfig {
+export type CalendarConfig = {
   /** Start date field */
   startDateField: string;
   /** End date field */
@@ -143,13 +106,13 @@ export interface CalendarConfig {
   titleField: string;
   /** Color field */
   colorField?: string;
-}
+};
 
 /**
  * Gantt Configuration
- * Aligned with @objectstack/spec GanttConfigSchema
+ * Canonical definition from @objectstack/spec/ui (GanttConfigSchema).
  */
-export interface GanttConfig {
+export type GanttConfig = {
   /** Start date field */
   startDateField: string;
   /** End date field */
@@ -162,7 +125,7 @@ export interface GanttConfig {
   dependenciesField?: string;
   /** Color field */
   colorField?: string;
-}
+};
 
 /**
  * Sort Configuration
@@ -422,6 +385,20 @@ export interface ObjectGridSchema extends BaseSchema {
    */
   editable?: boolean;
   
+  /**
+   * Grouping Configuration (Airtable-style)
+   * Groups rows by specified fields with collapsible sections.
+   * Aligned with @objectstack/spec GroupingConfigSchema.
+   */
+  grouping?: GroupingConfig;
+
+  /**
+   * Row Color Configuration (Airtable-style)
+   * Colors rows based on field values.
+   * Aligned with @objectstack/spec RowColorConfigSchema.
+   */
+  rowColor?: RowColorConfig;
+
   /**
    * Enable keyboard navigation (Grid mode)
    * Arrow keys, Tab, Enter for cell navigation
@@ -437,16 +414,96 @@ export interface ObjectGridSchema extends BaseSchema {
    * @default 0
    */
   frozenColumns?: number;
+
+  /**
+   * Navigation configuration for row click behavior.
+   * Controls how record detail is displayed when a row is clicked.
+   * Aligned with @objectstack/spec ListView.navigation.
+   */
+  navigation?: ViewNavigationConfig;
+
+  /**
+   * Callback for page-level navigation (used by 'page' mode).
+   * Called with recordId and action ('view' | 'edit').
+   */
+  onNavigate?: (recordId: string | number, action?: string) => void;
+}
+
+/**
+ * Form Section Configuration
+ * Aligns with @objectstack/spec FormSection
+ */
+export interface ObjectFormSection {
+  /**
+   * Section identifier
+   */
+  name?: string;
+  
+  /**
+   * Section label
+   */
+  label?: string;
+  
+  /**
+   * Section description
+   */
+  description?: string;
+  
+  /**
+   * Whether the section can be collapsed
+   * @default false
+   */
+  collapsible?: boolean;
+  
+  /**
+   * Whether the section is initially collapsed
+   * @default false
+   */
+  collapsed?: boolean;
+  
+  /**
+   * Number of columns for field layout
+   * @default 1
+   */
+  columns?: 1 | 2 | 3 | 4;
+  
+  /**
+   * Field names or inline field configurations for this section
+   */
+  fields: (string | FormField)[];
 }
 
 /**
  * ObjectForm Schema
  * A smart form component that generates forms from ObjectQL object schemas.
  * It automatically creates form fields based on object metadata.
+ * 
+ * Supports multiple form variants aligned with @objectstack/spec FormView:
+ * - `simple`  – Flat field list (default)
+ * - `tabbed`  – Fields organized in tabs
+ * - `wizard`  – Multi-step form with navigation
+ * - `split`   – Side-by-side panels (reserved)
+ * - `drawer`  – Slide-out form panel (reserved)
+ * - `modal`   – Dialog-based form (reserved)
  */
 export interface ObjectFormSchema extends BaseSchema {
   type: 'object-form';
   
+  /**
+   * Form variant type.
+   * Aligns with @objectstack/spec FormView.type
+   * 
+   * - `simple`  – Standard flat form (default)
+   * - `tabbed`  – Sections as tabs
+   * - `wizard`  – Multi-step wizard with progress indicator
+   * - `split`   – Side-by-side panel layout (reserved)
+   * - `drawer`  – Slide-out form (reserved)
+   * - `modal`   – Dialog form (reserved)
+   *
+   * @default 'simple'
+   */
+  formType?: 'simple' | 'tabbed' | 'wizard' | 'split' | 'drawer' | 'modal';
+  
   /**
    * ObjectQL object name (e.g., 'users', 'accounts', 'contacts')
    */
@@ -493,7 +550,14 @@ export interface ObjectFormSchema extends BaseSchema {
   initialData?: Record<string, any>;
   
   /**
-   * Field groups for organized layout
+   * Form sections for organized layout.
+   * Used by tabbed/wizard/simple forms to group fields.
+   * Aligns with @objectstack/spec FormView.sections
+   */
+  sections?: ObjectFormSection[];
+  
+  /**
+   * Field groups for organized layout (legacy, prefer sections)
    */
   groups?: Array<{
     title?: string;
@@ -512,27 +576,56 @@ export interface ObjectFormSchema extends BaseSchema {
    * - `inline`     – compact inline layout, typically used in toolbars
    * - `grid`       – **experimental** grid layout
    *
-   * Note: As of the current implementation, the underlying form renderer does not yet
-   * support a native `grid` layout and will internally treat `layout: "grid"` as
-   * `layout: "vertical"`. This value is exposed in the schema for forward compatibility,
-   * and behavior may change once grid support is implemented.
-   *
    * @default 'vertical'
    */
   layout?: 'vertical' | 'horizontal' | 'inline' | 'grid';
   
   /**
    * Grid columns (for grid layout).
-   *
-   * Intended number of columns when using a `grid` layout. Current renderers that do
-   * not implement true grid support may ignore this value and fall back to a vertical
-   * layout. When grid layout is supported, this value should control how many form
-   * fields are placed per row.
-   *
    * @default 2
    */
   columns?: number;
   
+  /**
+   * Default active tab (section name). Only used when formType is 'tabbed'.
+   */
+  defaultTab?: string;
+  
+  /**
+   * Tab position. Only used when formType is 'tabbed'.
+   * @default 'top'
+   */
+  tabPosition?: 'top' | 'bottom' | 'left' | 'right';
+  
+  /**
+   * Allow skipping steps. Only used when formType is 'wizard'.
+   * @default false
+   */
+  allowSkip?: boolean;
+  
+  /**
+   * Show step indicator. Only used when formType is 'wizard'.
+   * @default true
+   */
+  showStepIndicator?: boolean;
+  
+  /**
+   * Text for Next button. Only used when formType is 'wizard'.
+   * @default 'Next'
+   */
+  nextText?: string;
+  
+  /**
+   * Text for Previous button. Only used when formType is 'wizard'.
+   * @default 'Back'
+   */
+  prevText?: string;
+  
+  /**
+   * Called when wizard step changes. Only used when formType is 'wizard'.
+   */
+  onStepChange?: (step: number) => void;
+  
   /**
    * Show submit button
    * @default true
@@ -591,6 +684,66 @@ export interface ObjectFormSchema extends BaseSchema {
    * Custom CSS class
    */
   className?: string;
+
+  // ─── Split Form Props ──────────────────────────────────
+  
+  /**
+   * Split panel direction. Only used when formType is 'split'.
+   * @default 'horizontal'
+   */
+  splitDirection?: 'horizontal' | 'vertical';
+  
+  /**
+   * Size of the left/top panel in the split layout (percentage 1-99).
+   * Only used when formType is 'split'.
+   * @default 50
+   */
+  splitSize?: number;
+  
+  /**
+   * Whether the split panels can be resized. Only used when formType is 'split'.
+   * @default true
+   */
+  splitResizable?: boolean;
+
+  // ─── Drawer Form Props ─────────────────────────────────
+  
+  /**
+   * Whether the drawer is open. Only used when formType is 'drawer'.
+   * @default true
+   */
+  open?: boolean;
+  
+  /**
+   * Callback when open state changes. Only used when formType is 'drawer'.
+   */
+  onOpenChange?: (open: boolean) => void;
+  
+  /**
+   * Drawer slide-in side. Only used when formType is 'drawer'.
+   * @default 'right'
+   */
+  drawerSide?: 'top' | 'bottom' | 'left' | 'right';
+  
+  /**
+   * Drawer width (CSS value). Only used when formType is 'drawer'.
+   * @default '50%'
+   */
+  drawerWidth?: string;
+
+  // ─── Modal Form Props ──────────────────────────────────
+  
+  /**
+   * Modal dialog size. Only used when formType is 'modal'.
+   * @default 'default'
+   */
+  modalSize?: 'sm' | 'default' | 'lg' | 'xl' | 'full';
+  
+  /**
+   * Whether to show a close button in the modal header. Only used when formType is 'modal'.
+   * @default true
+   */
+  modalCloseButton?: boolean;
 }
 
 /**
@@ -625,6 +778,29 @@ export interface ObjectViewSchema extends BaseSchema {
    */
   layout?: 'drawer' | 'modal' | 'page';
   
+  /**
+   * Default list view type
+   * @default 'grid'
+   */
+  defaultViewType?: 'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map';
+  
+  /**
+   * Named list views (e.g., "All Records", "My Records", "Active").
+   * Aligned with @objectstack/spec View.listViews.
+   */
+  listViews?: Record<string, NamedListView>;
+  
+  /**
+   * Default named list view to display
+   */
+  defaultListView?: string;
+  
+  /**
+   * Navigation config for row/item click behavior.
+   * Aligned with @objectstack/spec ListView.navigation.
+   */
+  navigation?: ViewNavigationConfig;
+  
   /**
    * Table/Grid configuration
    * Inherits from ObjectGridSchema
@@ -637,6 +813,16 @@ export interface ObjectViewSchema extends BaseSchema {
    */
   form?: Partial<Omit<ObjectFormSchema, 'type' | 'objectName' | 'mode'>>;
   
+  /**
+   * Fields that support text search
+   */
+  searchableFields?: string[];
+  
+  /**
+   * Fields available for the filter UI
+   */
+  filterableFields?: string[];
+  
   /**
    * Show search box
    * @default true
@@ -661,6 +847,13 @@ export interface ObjectViewSchema extends BaseSchema {
    */
   showRefresh?: boolean;
   
+  /**
+   * Show view switcher (for multi-view)
+   * When false (default), view type is fixed at creation in ViewDesigner
+   * @default false
+   */
+  showViewSwitcher?: boolean;
+  
   /**
    * Enable/disable built-in operations
    */
@@ -682,30 +875,163 @@ export interface ObjectViewSchema extends BaseSchema {
   className?: string;
 }
 
+/**
+ * Named List View Definition
+ * Used in ObjectViewSchema.listViews for named views (e.g., "All", "My Records").
+ */
+export interface NamedListView {
+  /** View display label */
+  label: string;
+  
+  /** View type (grid, kanban, etc.) */
+  type?: 'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map';
+  
+  /** Columns/fields to display */
+  columns?: string[];
+  
+  /** Filter conditions */
+  filter?: any[];
+  
+  /** Sort configuration */
+  sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
+  
+  /** Type-specific options (kanban groupField, calendar startDateField, etc.) */
+  options?: Record<string, any>;
+}
+
+/**
+ * Navigation configuration for row/item click behavior.
+ * Aligned with @objectstack/spec ListView.navigation.
+ */
+export interface ViewNavigationConfig {
+  /**
+   * How to open the target view on interaction
+   * - page: Full page navigation
+   * - drawer: Slide-out panel
+   * - modal: Dialog overlay
+   * - split: Side-by-side panel
+   * - popover: Hover/click preview card
+   * - new_window: Open in new browser tab
+   * - none: No navigation on click
+   * @default 'page'
+   */
+  mode: 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none';
+  
+  /** Target view/form config name */
+  view?: string;
+  
+  /** Prevent default navigation behavior */
+  preventNavigation?: boolean;
+  
+  /** Open in new tab (for page/new_window modes) */
+  openNewTab?: boolean;
+  
+  /** Width for drawer/modal/split modes (e.g., '600px', '50%') */
+  width?: string | number;
+}
+
 /**
  * Generic View Definition
- * Aligned with @objectstack/spec View/ListView
+ * Aligned with @objectstack/spec View/ListView.
  * Defines the data requirement, not just the visual component.
  */
 export interface ListViewSchema extends BaseSchema {
   type: 'list-view';
   
+  /** View name identifier */
+  name?: string;
+  
+  /** View display label */
+  label?: string;
+  
   /** Object Name */
   objectName: string;
   
-  /** View Type (grid, kanban, etc) */
+  /** View Type (grid, kanban, etc.) @default 'grid' */
   viewType?: 'grid' | 'kanban' | 'gallery' | 'calendar' | 'timeline' | 'gantt' | 'map';
   
-  /** Fields to fetch/display */
+  /** Columns definition (string field names or full column config) */
+  columns?: string[] | Array<{
+    field: string;
+    label?: string;
+    width?: number | string;
+    align?: 'left' | 'center' | 'right';
+    hidden?: boolean;
+    sortable?: boolean;
+    resizable?: boolean;
+    wrap?: boolean;
+    type?: string;
+    link?: boolean;
+    action?: string;
+  }>;
+  
+  /** Fields to fetch/display (alias for simple string[] columns) */
   fields?: string[];
   
   /** Filter conditions */
-  filters?: Array<any[] | string>; // placeholder for FilterCondition
+  filters?: Array<any[] | string>;
   
   /** Sort order */
   sort?: Array<{ field: string; order: 'asc' | 'desc' }>;
   
-  /** Visual Component overrides */
+  /** Fields that support text search */
+  searchableFields?: string[];
+  
+  /** Fields available for filter UI */
+  filterableFields?: string[];
+  
+  /** Row selection mode */
+  selection?: { type: 'none' | 'single' | 'multiple' };
+  
+  /** Pagination configuration */
+  pagination?: { pageSize: number; pageSizeOptions?: number[] };
+  
+  /** Allow column resizing @default false */
+  resizable?: boolean;
+  
+  /** Show alternating row colors @default false */
+  striped?: boolean;
+  
+  /** Show cell borders @default false */
+  bordered?: boolean;
+  
+  /** Navigation config for row click behavior */
+  navigation?: ViewNavigationConfig;
+
+  /**
+   * Callback for page-level navigation (used by 'page' mode).
+   * Called with recordId and action ('view' | 'edit').
+   */
+  onNavigate?: (recordId: string | number, action?: string) => void;
+  
+  /** Kanban-specific configuration */
+  kanban?: {
+    groupField: string;
+    titleField?: string;
+    cardFields?: string[];
+    [key: string]: any;
+  };
+  
+  /** Calendar-specific configuration */
+  calendar?: {
+    startDateField: string;
+    endDateField?: string;
+    titleField?: string;
+    defaultView?: 'month' | 'week' | 'day' | 'agenda';
+    [key: string]: any;
+  };
+  
+  /** Gantt-specific configuration */
+  gantt?: {
+    startDateField: string;
+    endDateField: string;
+    titleField?: string;
+    progressField?: string;
+    dependenciesField?: string;
+    [key: string]: any;
+  };
+  
+  /** Visual Component overrides (legacy, prefer typed configs above) */
   options?: Record<string, any>;
 }