@object-ui/types 0.3.1 → 2.0.0

package/src/permissions.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 - Permission & RBAC Types
+ * 
+ * Complete RBAC (Role-Based Access Control) type definitions for
+ * object/field/row-level permissions aligned with @objectstack/spec v2.0.1.
+ * 
+ * @module permissions
+ * @packageDocumentation
+ */
+
+// ============================================================================
+// Role-Based Access Control (RBAC)
+// ============================================================================
+
+/** Standard CRUD permission actions */
+export type PermissionAction = 'create' | 'read' | 'update' | 'delete' | 'export' | 'import' | 'share' | 'admin';
+
+/** Permission effect */
+export type PermissionEffect = 'allow' | 'deny';
+
+/** Role definition for RBAC */
+export interface RoleDefinition {
+  /** Unique role identifier */
+  name: string;
+  /** Display label */
+  label: string;
+  /** Role description */
+  description?: string;
+  /** Parent role for inheritance */
+  inherits?: string[];
+  /** Whether this is a system role */
+  system?: boolean;
+  /** Object-level permissions */
+  permissions: ObjectLevelPermission[];
+}
+
+/** Object-level permission assignment */
+export interface ObjectLevelPermission {
+  /** Target object name */
+  object: string;
+  /** Allowed actions */
+  actions: PermissionAction[];
+  /** Permission effect */
+  effect?: PermissionEffect;
+  /** Conditions for conditional permissions */
+  conditions?: PermissionCondition[];
+}
+
+/** Field-level permission */
+export interface FieldLevelPermission {
+  /** Target field name */
+  field: string;
+  /** Read permission */
+  read?: boolean;
+  /** Write permission */
+  write?: boolean;
+  /** Permission effect */
+  effect?: PermissionEffect;
+  /** Mask value for restricted fields (e.g., '****' for SSN) */
+  mask?: string;
+}
+
+/** Row-level permission (record-level security) */
+export interface RowLevelPermission {
+  /** Filter expression to scope visible records */
+  filter: string;
+  /** Actions allowed on matching records */
+  actions: PermissionAction[];
+  /** Description of the rule */
+  description?: string;
+}
+
+/** Permission condition for conditional access */
+export interface PermissionCondition {
+  /** Field to evaluate */
+  field: string;
+  /** Comparison operator */
+  operator: 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'not_in' | 'contains' | 'is_null' | 'is_not_null';
+  /** Value to compare */
+  value: unknown;
+}
+
+/** Complete permission configuration for an object */
+export interface ObjectPermissionConfig {
+  /** Object name */
+  object: string;
+  /** Default permissions for unauthenticated users */
+  publicAccess?: PermissionAction[];
+  /** Role-based permissions */
+  roles: Record<string, {
+    actions: PermissionAction[];
+    fieldPermissions?: FieldLevelPermission[];
+    rowPermissions?: RowLevelPermission[];
+  }>;
+  /** Field-level permission defaults */
+  fieldDefaults?: FieldLevelPermission[];
+  /** Sharing rules */
+  sharingRules?: SharingRuleConfig[];
+}
+
+/** Sharing rule configuration */
+export interface SharingRuleConfig {
+  /** Rule name */
+  name: string;
+  /** Share with type */
+  type: 'role' | 'user' | 'group' | 'public';
+  /** Target entity (role name, user ID, group name) */
+  entity: string;
+  /** Permitted actions */
+  actions: PermissionAction[];
+  /** Filter to scope which records are shared */
+  filter?: string;
+}
+
+/** Permission check result */
+export interface PermissionCheckResult {
+  /** Whether the action is allowed */
+  allowed: boolean;
+  /** Reason for denial */
+  reason?: string;
+  /** Applicable field restrictions */
+  fieldRestrictions?: FieldLevelPermission[];
+  /** Row filter to apply */
+  rowFilter?: string;
+}
+
+/** Permission context for evaluating permissions */
+export interface PermissionContext {
+  /** Current user */
+  user: {
+    id: string;
+    roles: string[];
+    groups?: string[];
+    [key: string]: unknown;
+  };
+  /** Target object */
+  object: string;
+  /** Target action */
+  action: PermissionAction;
+  /** Target record (for row-level checks) */
+  record?: Record<string, unknown>;
+  /** Target field (for field-level checks) */
+  field?: string;
+}
+
+/** Permission guard configuration for UI components */
+export interface PermissionGuardConfig {
+  /** Required permission */
+  permission: string | PermissionAction;
+  /** Target object */
+  object?: string;
+  /** Fallback behavior when denied */
+  fallback?: 'hide' | 'disable' | 'redirect' | 'custom';
+  /** Custom fallback component type */
+  fallbackComponent?: string;
+  /** Redirect path for 'redirect' fallback */
+  redirectPath?: string;
+}

package/src/plugin-scope.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 - Plugin Scope Isolation
+ * 
+ * Section 3.3: Plugin scope isolation types to prevent conflicts between plugins.
+ * Provides scoped component registration, state management, and event bus.
+ * 
+ * @module plugin-scope
+ * @packageDocumentation
+ */
+
+/**
+ * Plugin Scope Interface
+ * 
+ * Provides isolated access to the component registry, state management,
+ * and event bus for a specific plugin, preventing conflicts between plugins.
+ */
+export interface PluginScope {
+  /**
+   * Plugin name
+   */
+  name: string;
+  
+  /**
+   * Plugin version
+   */
+  version: string;
+  
+  /**
+   * Register a component in the scoped namespace.
+   * Components will be registered as "pluginName:type" to prevent conflicts.
+   * 
+   * @param type - Component type identifier (e.g., 'table', 'chart')
+   * @param component - Component renderer
+   * @param meta - Optional component metadata
+   * 
+   * @example
+   * // Plugin 'my-grid' registers a 'table' component
+   * // Registered as 'my-grid:table'
+   * scope.registerComponent('table', TableComponent, {
+   *   label: 'Data Table',
+   *   category: 'data'
+   * });
+   */
+  registerComponent(type: string, component: any, meta?: ComponentMeta): void;
+  
+  /**
+   * Get a component from the scoped namespace.
+   * First tries scoped lookup (pluginName:type), then falls back to global.
+   * 
+   * @param type - Component type identifier
+   * @returns Component renderer or undefined if not found
+   */
+  getComponent(type: string): any | undefined;
+  
+  /**
+   * Scoped state management.
+   * Each plugin has its own isolated state that won't conflict with others.
+   * 
+   * @param key - State key unique to this plugin
+   * @param initialValue - Initial state value
+   * @returns Tuple of [currentValue, setValue]
+   * 
+   * @example
+   * const [config, setConfig] = scope.useState('config', { theme: 'light' });
+   */
+  useState<T>(key: string, initialValue: T): [T, (value: T | ((prev: T) => T)) => void];
+  
+  /**
+   * Get scoped state value without setter.
+   * 
+   * @param key - State key
+   * @returns Current state value or undefined
+   */
+  getState<T>(key: string): T | undefined;
+  
+  /**
+   * Set scoped state value directly.
+   * 
+   * @param key - State key
+   * @param value - New state value
+   */
+  setState<T>(key: string, value: T): void;
+  
+  /**
+   * Subscribe to scoped events.
+   * Events are namespaced to prevent cross-plugin conflicts.
+   * 
+   * @param event - Event name (will be prefixed with plugin namespace)
+   * @param handler - Event handler function
+   * @returns Unsubscribe function
+   * 
+   * @example
+   * const unsubscribe = scope.on('data-updated', (data) => {
+   *   console.log('Scoped event received:', data);
+   * });
+   */
+  on(event: string, handler: PluginEventHandler): () => void;
+  
+  /**
+   * Emit a scoped event.
+   * Only subscribers within this plugin scope will receive it.
+   * 
+   * @param event - Event name
+   * @param data - Event data
+   * 
+   * @example
+   * scope.emit('data-updated', { rows: 100 });
+   */
+  emit(event: string, data?: any): void;
+  
+  /**
+   * Emit a global event that all plugins can receive.
+   * Use sparingly for cross-plugin communication.
+   * 
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emitGlobal(event: string, data?: any): void;
+  
+  /**
+   * Subscribe to global events from any plugin.
+   * 
+   * @param event - Event name
+   * @param handler - Event handler function
+   * @returns Unsubscribe function
+   */
+  onGlobal(event: string, handler: PluginEventHandler): () => void;
+  
+  /**
+   * Clean up all plugin resources (state, event listeners, etc.)
+   * Called automatically when plugin is unloaded.
+   */
+  cleanup(): void;
+}
+
+/**
+ * Component metadata for registration
+ */
+export interface ComponentMeta {
+  label?: string;
+  icon?: string;
+  category?: string;
+  inputs?: ComponentInput[];
+  defaultProps?: Record<string, any>;
+  defaultChildren?: any[];
+  examples?: Record<string, any>;
+  isContainer?: boolean;
+  resizable?: boolean;
+  resizeConstraints?: {
+    width?: boolean;
+    height?: boolean;
+    minWidth?: number;
+    maxWidth?: number;
+    minHeight?: number;
+    maxHeight?: number;
+  };
+}
+
+/**
+ * Component input definition
+ */
+export interface ComponentInput {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'object' | 'color' | 'date' | 'code' | 'file' | 'slot';
+  label?: string;
+  defaultValue?: any;
+  required?: boolean;
+  enum?: string[] | { label: string; value: any }[];
+  description?: string;
+  advanced?: boolean;
+  inputType?: string;
+}
+
+/**
+ * Event handler type
+ */
+export type PluginEventHandler = (data?: any) => void;
+
+/**
+ * Plugin scope configuration
+ */
+export interface PluginScopeConfig {
+  /**
+   * Whether to enable state isolation (default: true)
+   */
+  enableStateIsolation?: boolean;
+  
+  /**
+   * Whether to enable event isolation (default: true)
+   */
+  enableEventIsolation?: boolean;
+  
+  /**
+   * Whether to allow global event access (default: true)
+   */
+  allowGlobalEvents?: boolean;
+  
+  /**
+   * Maximum state size per plugin in bytes (default: 5MB)
+   */
+  maxStateSize?: number;
+}