@object-ui/types 0.3.0

package/src/data.ts

@@ -0,0 +1,341 @@
+/**
+ * @object-ui/types - Data Source Types
+ * 
+ * Type definitions for data fetching and management.
+ * These interfaces define the universal adapter pattern for data access.
+ * 
+ * @module data
+ * @packageDocumentation
+ */
+
+/**
+ * Query parameters for data fetching.
+ * Follows OData/REST conventions for universal compatibility.
+ */
+export interface QueryParams {
+  /**
+   * Fields to select (projection)
+   * @example ['id', 'name', 'email']
+   */
+  $select?: string[];
+
+  /**
+   * Filter expression
+   * @example { age: { $gt: 18 }, status: 'active' }
+   */
+  $filter?: Record<string, any>;
+
+  /**
+   * Sort order
+   * @example { createdAt: 'desc', name: 'asc' }
+   */
+  $orderby?: Record<string, 'asc' | 'desc'>;
+
+  /**
+   * Number of records to skip (for pagination)
+   */
+  $skip?: number;
+
+  /**
+   * Maximum number of records to return
+   */
+  $top?: number;
+
+  /**
+   * Related entities to expand/include
+   * @example ['author', 'comments']
+   */
+  $expand?: string[];
+
+  /**
+   * Search query (full-text search)
+   */
+  $search?: string;
+
+  /**
+   * Total count of records (for pagination)
+   */
+  $count?: boolean;
+
+  /**
+   * Additional custom parameters
+   */
+  [key: string]: any;
+}
+
+/**
+ * Query result with pagination metadata
+ */
+export interface QueryResult<T = any> {
+  /**
+   * Result data array
+   */
+  data: T[];
+
+  /**
+   * Total number of records (if requested)
+   */
+  total?: number;
+
+  /**
+   * Current page number (1-indexed)
+   */
+  page?: number;
+
+  /**
+   * Page size
+   */
+  pageSize?: number;
+
+  /**
+   * Whether there are more records
+   */
+  hasMore?: boolean;
+
+  /**
+   * Cursor for cursor-based pagination
+   */
+  cursor?: string;
+
+  /**
+   * Additional metadata
+   */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Universal data source interface.
+ * This is the core abstraction that makes Object UI backend-agnostic.
+ * 
+ * Implementations can connect to:
+ * - REST APIs
+ * - GraphQL endpoints
+ * - ObjectQL servers
+ * - Firebase/Supabase
+ * - Local arrays/JSON
+ * - Any data source
+ * 
+ * @template T - The data type
+ * 
+ * @example
+ * ```typescript
+ * class RestDataSource implements DataSource<User> {
+ *   async find(resource, params) {
+ *     const response = await fetch(`/api/${resource}?${buildQuery(params)}`);
+ *     return response.json();
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+export interface DataSource<T = any> {
+  /**
+   * Fetch multiple records.
+   * 
+   * @param resource - Resource name (e.g., 'users', 'posts')
+   * @param params - Query parameters
+   * @returns Promise resolving to query result
+   */
+  find(resource: string, params?: QueryParams): Promise<QueryResult<T>>;
+
+  /**
+   * Fetch a single record by ID.
+   * 
+   * @param resource - Resource name
+   * @param id - Record identifier
+   * @param params - Additional query parameters
+   * @returns Promise resolving to the record or null
+   */
+  findOne(resource: string, id: string | number, params?: QueryParams): Promise<T | null>;
+
+  /**
+   * Create a new record.
+   * 
+   * @param resource - Resource name
+   * @param data - Record data
+   * @returns Promise resolving to the created record
+   */
+  create(resource: string, data: Partial<T>): Promise<T>;
+
+  /**
+   * Update an existing record.
+   * 
+   * @param resource - Resource name
+   * @param id - Record identifier
+   * @param data - Updated data (partial)
+   * @returns Promise resolving to the updated record
+   */
+  update(resource: string, id: string | number, data: Partial<T>): Promise<T>;
+
+  /**
+   * Delete a record.
+   * 
+   * @param resource - Resource name
+   * @param id - Record identifier
+   * @returns Promise resolving to true if successful
+   */
+  delete(resource: string, id: string | number): Promise<boolean>;
+
+  /**
+   * Execute a bulk operation (optional).
+   * 
+   * @param resource - Resource name
+   * @param operation - Operation type
+   * @param data - Bulk data
+   * @returns Promise resolving to operation result
+   */
+  bulk?(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+}
+
+/**
+ * Data scope context for managing data state.
+ * Provides reactive data management within the UI.
+ */
+export interface DataScope {
+  /**
+   * Data source instance
+   */
+  dataSource?: DataSource;
+
+  /**
+   * Current data
+   */
+  data?: any;
+
+  /**
+   * Loading state
+   */
+  loading?: boolean;
+
+  /**
+   * Error state
+   */
+  error?: Error | string | null;
+
+  /**
+   * Refresh data
+   */
+  refresh?: () => Promise<void>;
+
+  /**
+   * Set data
+   */
+  setData?: (data: any) => void;
+}
+
+/**
+ * Data context for component trees.
+ * Allows components to access and share data.
+ */
+export interface DataContext {
+  /**
+   * Named data scopes
+   */
+  scopes: Record<string, DataScope>;
+
+  /**
+   * Register a data scope
+   */
+  registerScope: (name: string, scope: DataScope) => void;
+
+  /**
+   * Get a data scope by name
+   */
+  getScope: (name: string) => DataScope | undefined;
+
+  /**
+   * Remove a data scope
+   */
+  removeScope: (name: string) => void;
+}
+
+/**
+ * Data binding configuration.
+ * Defines how a component's data is sourced and updated.
+ */
+export interface DataBinding {
+  /**
+   * Data source name
+   */
+  source?: string;
+
+  /**
+   * Resource name
+   */
+  resource?: string;
+
+  /**
+   * Query parameters
+   */
+  params?: QueryParams;
+
+  /**
+   * Transform function for data
+   */
+  transform?: (data: any) => any;
+
+  /**
+   * Auto-refresh interval (ms)
+   */
+  refreshInterval?: number;
+
+  /**
+   * Cache data
+   */
+  cache?: boolean;
+
+  /**
+   * Cache TTL (ms)
+   */
+  cacheTTL?: number;
+}
+
+/**
+ * Validation error
+ */
+export interface ValidationError {
+  /**
+   * Field name
+   */
+  field: string;
+
+  /**
+   * Error message
+   */
+  message: string;
+
+  /**
+   * Error code
+   */
+  code?: string;
+}
+
+/**
+ * API error response
+ */
+export interface APIError {
+  /**
+   * Error message
+   */
+  message: string;
+
+  /**
+   * HTTP status code
+   */
+  status?: number;
+
+  /**
+   * Error code
+   */
+  code?: string;
+
+  /**
+   * Validation errors
+   */
+  errors?: ValidationError[];
+
+  /**
+   * Additional error data
+   */
+  data?: any;
+}

package/src/disclosure.ts

@@ -0,0 +1,113 @@
+/**
+ * @object-ui/types - Disclosure Component Schemas
+ * 
+ * Type definitions for collapsible and expandable components.
+ * 
+ * @module disclosure
+ * @packageDocumentation
+ */
+
+import type { BaseSchema, SchemaNode } from './base';
+
+/**
+ * Accordion item
+ */
+export interface AccordionItem {
+  /**
+   * Unique item identifier
+   */
+  value: string;
+  /**
+   * Item title/trigger
+   */
+  title: string;
+  /**
+   * Item content
+   */
+  content: SchemaNode | SchemaNode[];
+  /**
+   * Whether item is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Item icon
+   */
+  icon?: string;
+}
+
+/**
+ * Accordion component
+ */
+export interface AccordionSchema extends BaseSchema {
+  type: 'accordion';
+  /**
+   * Accordion items
+   */
+  items: AccordionItem[];
+  /**
+   * Accordion type
+   * @default 'single'
+   */
+  accordionType?: 'single' | 'multiple';
+  /**
+   * Whether items are collapsible
+   * @default true
+   */
+  collapsible?: boolean;
+  /**
+   * Default expanded item values
+   */
+  defaultValue?: string | string[];
+  /**
+   * Controlled expanded item values
+   */
+  value?: string | string[];
+  /**
+   * Change handler
+   */
+  onValueChange?: (value: string | string[]) => void;
+  /**
+   * Accordion variant
+   * @default 'default'
+   */
+  variant?: 'default' | 'bordered' | 'separated';
+}
+
+/**
+ * Collapsible component
+ */
+export interface CollapsibleSchema extends BaseSchema {
+  type: 'collapsible';
+  /**
+   * Trigger content/label
+   */
+  trigger: string | SchemaNode;
+  /**
+   * Collapsible content
+   */
+  content: SchemaNode | SchemaNode[];
+  /**
+   * Default open state
+   * @default false
+   */
+  defaultOpen?: boolean;
+  /**
+   * Controlled open state
+   */
+  open?: boolean;
+  /**
+   * Whether collapsible is disabled
+   */
+  disabled?: boolean;
+  /**
+   * Open state change handler
+   */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Union type of all disclosure schemas
+ */
+export type DisclosureSchema =
+  | AccordionSchema
+  | CollapsibleSchema;

package/src/feedback.ts

@@ -0,0 +1,170 @@
+/**
+ * @object-ui/types - Feedback Component Schemas
+ * 
+ * Type definitions for feedback and status indication components.
+ * 
+ * @module feedback
+ * @packageDocumentation
+ */
+
+import type { BaseSchema, SchemaNode } from './base';
+
+/**
+ * Loading/Spinner component
+ */
+export interface LoadingSchema extends BaseSchema {
+  type: 'loading';
+  /**
+   * Loading text/message
+   */
+  label?: string;
+  /**
+   * Spinner size
+   * @default 'default'
+   */
+  size?: 'sm' | 'default' | 'lg';
+  /**
+   * Spinner variant
+   * @default 'spinner'
+   */
+  variant?: 'spinner' | 'dots' | 'pulse';
+  /**
+   * Whether to show fullscreen overlay
+   * @default false
+   */
+  fullscreen?: boolean;
+}
+
+/**
+ * Progress bar component
+ */
+export interface ProgressSchema extends BaseSchema {
+  type: 'progress';
+  /**
+   * Progress value (0-100)
+   */
+  value?: number;
+  /**
+   * Maximum value
+   * @default 100
+   */
+  max?: number;
+  /**
+   * Progress bar variant
+   * @default 'default'
+   */
+  variant?: 'default' | 'success' | 'warning' | 'error';
+  /**
+   * Show percentage label
+   * @default false
+   */
+  showLabel?: boolean;
+  /**
+   * Progress bar size
+   * @default 'default'
+   */
+  size?: 'sm' | 'default' | 'lg';
+  /**
+   * Indeterminate/loading state
+   * @default false
+   */
+  indeterminate?: boolean;
+}
+
+/**
+ * Skeleton loading placeholder
+ */
+export interface SkeletonSchema extends BaseSchema {
+  type: 'skeleton';
+  /**
+   * Skeleton variant
+   * @default 'text'
+   */
+  variant?: 'text' | 'circular' | 'rectangular';
+  /**
+   * Width
+   */
+  width?: string | number;
+  /**
+   * Height
+   */
+  height?: string | number;
+  /**
+   * Number of lines (for text variant)
+   * @default 1
+   */
+  lines?: number;
+  /**
+   * Enable animation
+   * @default true
+   */
+  animate?: boolean;
+}
+
+/**
+ * Toast notification (declarative schema)
+ */
+export interface ToastSchema extends BaseSchema {
+  type: 'toast';
+  /**
+   * Toast title
+   */
+  title?: string;
+  /**
+   * Toast description
+   */
+  description?: string;
+  /**
+   * Toast variant
+   * @default 'default'
+   */
+  variant?: 'default' | 'success' | 'warning' | 'error' | 'info';
+  /**
+   * Auto-dismiss duration in milliseconds
+   * @default 5000
+   */
+  duration?: number;
+  /**
+   * Toast position
+   * @default 'bottom-right'
+   */
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+  /**
+   * Action button
+   */
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+  /**
+   * Dismiss handler
+   */
+  onDismiss?: () => void;
+}
+
+/**
+ * Toaster container (for toast management)
+ */
+export interface ToasterSchema extends BaseSchema {
+  type: 'toaster';
+  /**
+   * Toast position
+   * @default 'bottom-right'
+   */
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+  /**
+   * Maximum number of toasts to show
+   * @default 5
+   */
+  limit?: number;
+}
+
+/**
+ * Union type of all feedback schemas
+ */
+export type FeedbackSchema =
+  | LoadingSchema
+  | ProgressSchema
+  | SkeletonSchema
+  | ToastSchema
+  | ToasterSchema;