@object-ui/types 0.3.0

package/src/objectql.ts

@@ -0,0 +1,301 @@
+/**
+ * @object-ui/types - ObjectQL Component Schemas
+ * 
+ * Type definitions for ObjectQL-specific components.
+ * These schemas enable building ObjectQL-aware interfaces directly from object metadata.
+ * 
+ * @module objectql
+ * @packageDocumentation
+ */
+
+import type { BaseSchema } from './base';
+import type { TableColumn } from './data-display';
+import type { FormField } from './form';
+
+/**
+ * ObjectTable Schema
+ * A specialized table component that automatically fetches and displays data from ObjectQL objects.
+ * It reads the object schema from ObjectQL and generates columns automatically.
+ */
+export interface ObjectTableSchema extends BaseSchema {
+  type: 'object-table';
+  
+  /**
+   * ObjectQL object name (e.g., 'users', 'accounts', 'contacts')
+   */
+  objectName: string;
+  
+  /**
+   * Optional title for the table
+   */
+  title?: string;
+  
+  /**
+   * Optional description
+   */
+  description?: string;
+  
+  /**
+   * Field names to display as columns
+   * If not specified, uses all visible fields from object schema
+   */
+  fields?: string[];
+  
+  /**
+   * Custom column configurations
+   * Overrides auto-generated columns for specific fields
+   */
+  columns?: TableColumn[];
+  
+  /**
+   * Enable/disable built-in operations
+   */
+  operations?: {
+    /**
+     * Enable create operation
+     * @default true
+     */
+    create?: boolean;
+    
+    /**
+     * Enable read/view operation
+     * @default true
+     */
+    read?: boolean;
+    
+    /**
+     * Enable update operation
+     * @default true
+     */
+    update?: boolean;
+    
+    /**
+     * Enable delete operation
+     * @default true
+     */
+    delete?: boolean;
+    
+    /**
+     * Enable export operation
+     * @default false
+     */
+    export?: boolean;
+    
+    /**
+     * Enable import operation
+     * @default false
+     */
+    import?: boolean;
+  };
+  
+  /**
+   * Default filters to apply
+   */
+  defaultFilters?: Record<string, any>;
+  
+  /**
+   * Default sort configuration
+   */
+  defaultSort?: {
+    field: string;
+    order: 'asc' | 'desc';
+  };
+  
+  /**
+   * Page size
+   * @default 10
+   */
+  pageSize?: number;
+  
+  /**
+   * Enable row selection
+   * @default false
+   */
+  selectable?: boolean | 'single' | 'multiple';
+  
+  /**
+   * Show search box
+   * @default true
+   */
+  showSearch?: boolean;
+  
+  /**
+   * Show filters
+   * @default true
+   */
+  showFilters?: boolean;
+  
+  /**
+   * Show pagination
+   * @default true
+   */
+  showPagination?: boolean;
+  
+  /**
+   * Custom row actions
+   */
+  rowActions?: string[];
+  
+  /**
+   * Custom batch actions
+   */
+  batchActions?: string[];
+  
+  /**
+   * Custom CSS class
+   */
+  className?: string;
+}
+
+/**
+ * ObjectForm Schema
+ * A smart form component that generates forms from ObjectQL object schemas.
+ * It automatically creates form fields based on object metadata.
+ */
+export interface ObjectFormSchema extends BaseSchema {
+  type: 'object-form';
+  
+  /**
+   * ObjectQL object name (e.g., 'users', 'accounts', 'contacts')
+   */
+  objectName: string;
+  
+  /**
+   * Form mode
+   */
+  mode: 'create' | 'edit' | 'view';
+  
+  /**
+   * Record ID (required for edit/view modes)
+   */
+  recordId?: string | number;
+  
+  /**
+   * Optional title for the form
+   */
+  title?: string;
+  
+  /**
+   * Optional description
+   */
+  description?: string;
+  
+  /**
+   * Field names to include in the form
+   * If not specified, uses all editable fields from object schema
+   */
+  fields?: string[];
+  
+  /**
+   * Custom field configurations
+   * Overrides auto-generated fields for specific fields
+   */
+  customFields?: FormField[];
+  
+  /**
+   * Field groups for organized layout
+   */
+  groups?: Array<{
+    title?: string;
+    description?: string;
+    fields: string[];
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+  }>;
+  
+  /**
+   * Form layout.
+   *
+   * Supported layouts:
+   * - `vertical`   – label above field (default)
+   * - `horizontal` – label and field in a row
+   * - `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;
+  
+  /**
+   * Show submit button
+   * @default true
+   */
+  showSubmit?: boolean;
+  
+  /**
+   * Submit button text
+   */
+  submitText?: string;
+  
+  /**
+   * Show cancel button
+   * @default true
+   */
+  showCancel?: boolean;
+  
+  /**
+   * Cancel button text
+   */
+  cancelText?: string;
+  
+  /**
+   * Show reset button
+   * @default false
+   */
+  showReset?: boolean;
+  
+  /**
+   * Initial values (for create mode)
+   */
+  initialValues?: Record<string, any>;
+  
+  /**
+   * Callback on successful submission
+   */
+  onSuccess?: (data: any) => void | Promise<void>;
+  
+  /**
+   * Callback on error
+   */
+  onError?: (error: Error) => void;
+  
+  /**
+   * Callback on cancel
+   */
+  onCancel?: () => void;
+  
+  /**
+   * Read-only mode
+   * @default false
+   */
+  readOnly?: boolean;
+  
+  /**
+   * Custom CSS class
+   */
+  className?: string;
+}
+
+/**
+ * Union type of all ObjectQL component schemas
+ */
+export type ObjectQLComponentSchema =
+  | ObjectTableSchema
+  | ObjectFormSchema;

package/src/overlay.ts

@@ -0,0 +1,418 @@
+/**
+ * @object-ui/types - Overlay Component Schemas
+ * 
+ * Type definitions for modal, dialog, and overlay components.
+ * 
+ * @module overlay
+ * @packageDocumentation
+ */
+
+import type { BaseSchema, SchemaNode } from './base';
+
+/**
+ * Position type for overlays
+ */
+export type OverlayPosition = 'top' | 'right' | 'bottom' | 'left';
+
+/**
+ * Alignment type for overlays
+ */
+export type OverlayAlignment = 'start' | 'center' | 'end';
+
+/**
+ * Dialog component
+ */
+export interface DialogSchema extends BaseSchema {
+  type: 'dialog';
+  /**
+   * Dialog title
+   */
+  title?: string;
+  /**
+   * Dialog description
+   */
+  description?: string;
+  /**
+   * Dialog content
+   */
+  content?: SchemaNode | SchemaNode[];
+  /**
+   * Dialog trigger (button or element that opens the dialog)
+   */
+  trigger?: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Dialog footer content
+   */
+  footer?: SchemaNode | SchemaNode[];
+  /**
+   * Whether dialog is modal (prevents interaction with background)
+   * @default true
+   */
+  modal?: boolean;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Alert dialog (confirmation dialog)
+ */
+export interface AlertDialogSchema extends BaseSchema {
+  type: 'alert-dialog';
+  /**
+   * Dialog title
+   */
+  title?: string;
+  /**
+   * Dialog description
+   */
+  description?: string;
+  /**
+   * Dialog trigger
+   */
+  trigger?: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Cancel button label
+   * @default 'Cancel'
+   */
+  cancelLabel?: string;
+  /**
+   * Confirm button label
+   * @default 'Confirm'
+   */
+  confirmLabel?: string;
+  /**
+   * Confirm button variant
+   * @default 'default'
+   */
+  confirmVariant?: 'default' | 'destructive';
+  /**
+   * Confirm handler
+   */
+  onConfirm?: () => void | Promise<void>;
+  /**
+   * Cancel handler
+   */
+  onCancel?: () => void;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Sheet/Drawer side panel
+ */
+export interface SheetSchema extends BaseSchema {
+  type: 'sheet';
+  /**
+   * Sheet title
+   */
+  title?: string;
+  /**
+   * Sheet description
+   */
+  description?: string;
+  /**
+   * Sheet content
+   */
+  content?: SchemaNode | SchemaNode[];
+  /**
+   * Sheet trigger
+   */
+  trigger?: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Sheet side
+   * @default 'right'
+   */
+  side?: OverlayPosition;
+  /**
+   * Sheet footer content
+   */
+  footer?: SchemaNode | SchemaNode[];
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Drawer component (alternative name for Sheet)
+ */
+export interface DrawerSchema extends BaseSchema {
+  type: 'drawer';
+  /**
+   * Drawer title
+   */
+  title?: string;
+  /**
+   * Drawer description
+   */
+  description?: string;
+  /**
+   * Drawer content
+   */
+  content?: SchemaNode | SchemaNode[];
+  /**
+   * Drawer trigger
+   */
+  trigger?: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Drawer direction
+   * @default 'right'
+   */
+  direction?: OverlayPosition;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Popover component
+ */
+export interface PopoverSchema extends BaseSchema {
+  type: 'popover';
+  /**
+   * Popover content
+   */
+  content: SchemaNode | SchemaNode[];
+  /**
+   * Popover trigger
+   */
+  trigger: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Popover side
+   * @default 'bottom'
+   */
+  side?: OverlayPosition;
+  /**
+   * Popover alignment
+   * @default 'center'
+   */
+  align?: OverlayAlignment;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Tooltip component
+ */
+export interface TooltipSchema extends BaseSchema {
+  type: 'tooltip';
+  /**
+   * Tooltip content/text
+   */
+  content: string | SchemaNode;
+  /**
+   * Element to attach tooltip to
+   */
+  children: SchemaNode;
+  /**
+   * Tooltip side
+   * @default 'top'
+   */
+  side?: OverlayPosition;
+  /**
+   * Tooltip alignment
+   * @default 'center'
+   */
+  align?: OverlayAlignment;
+  /**
+   * Delay before showing (ms)
+   * @default 200
+   */
+  delayDuration?: number;
+}
+
+/**
+ * Hover card component
+ */
+export interface HoverCardSchema extends BaseSchema {
+  type: 'hover-card';
+  /**
+   * Hover card content
+   */
+  content: SchemaNode | SchemaNode[];
+  /**
+   * Hover trigger element
+   */
+  trigger: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Hover card side
+   * @default 'bottom'
+   */
+  side?: OverlayPosition;
+  /**
+   * Open delay (ms)
+   * @default 200
+   */
+  openDelay?: number;
+  /**
+   * Close delay (ms)
+   * @default 300
+   */
+  closeDelay?: number;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Menu item
+ */
+export interface MenuItem {
+  /**
+   * Menu item label
+   */
+  label: string;
+  /**
+   * Menu item icon
+   */
+  icon?: string;
+  /**
+   * Whether item is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Click handler
+   */
+  onClick?: () => void;
+  /**
+   * Keyboard shortcut
+   */
+  shortcut?: string;
+  /**
+   * Submenu items
+   */
+  children?: MenuItem[];
+  /**
+   * Separator (renders as divider)
+   */
+  separator?: boolean;
+}
+
+/**
+ * Dropdown menu component
+ */
+export interface DropdownMenuSchema extends BaseSchema {
+  type: 'dropdown-menu';
+  /**
+   * Menu items
+   */
+  items: MenuItem[];
+  /**
+   * Menu trigger
+   */
+  trigger: SchemaNode;
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Menu side
+   * @default 'bottom'
+   */
+  side?: OverlayPosition;
+  /**
+   * Menu alignment
+   * @default 'start'
+   */
+  align?: OverlayAlignment;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Context menu component
+ */
+export interface ContextMenuSchema extends BaseSchema {
+  type: 'context-menu';
+  /**
+   * Menu items
+   */
+  items: MenuItem[];
+  /**
+   * Element to attach context menu to
+   */
+  children: SchemaNode | SchemaNode[];
+}
+
+/**
+ * Union type of all overlay schemas
+ */
+export type OverlaySchema =
+  | DialogSchema
+  | AlertDialogSchema
+  | SheetSchema
+  | DrawerSchema
+  | PopoverSchema
+  | TooltipSchema
+  | HoverCardSchema
+  | DropdownMenuSchema
+  | ContextMenuSchema;