@object-ui/core 0.5.0 → 3.0.0

package/dist/adapters/resolveDataSource.js

@@ -0,0 +1,59 @@
+/**
+ * ObjectUI — resolveDataSource
+ * 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.
+ *
+ * Factory function to create the right DataSource from a ViewData config.
+ */
+import { ApiDataSource } from './ApiDataSource.js';
+import { ValueDataSource } from './ValueDataSource.js';
+/**
+ * Resolve a ViewData configuration into a concrete DataSource instance.
+ *
+ * - `provider: 'object'` → returns `fallback` (the context DataSource — typically ObjectStackAdapter)
+ * - `provider: 'api'`    → returns a new `ApiDataSource`
+ * - `provider: 'value'`  → returns a new `ValueDataSource`
+ *
+ * @param viewData - The ViewData configuration from the schema
+ * @param fallback - The default DataSource from context (for `provider: 'object'`)
+ * @param options  - Additional options for adapter construction
+ * @returns A DataSource instance, or null if neither viewData nor fallback is available
+ *
+ * @example
+ * ```ts
+ * const ds = resolveDataSource(
+ *   { provider: 'api', read: { url: '/api/users' } },
+ *   contextDataSource,
+ * );
+ * const result = await ds.find('users');
+ * ```
+ */
+export function resolveDataSource(viewData, fallback, options) {
+    if (!viewData) {
+        return fallback ?? null;
+    }
+    switch (viewData.provider) {
+        case 'object':
+            // Delegate to the context DataSource (ObjectStackAdapter, etc.)
+            return fallback ?? null;
+        case 'api': {
+            const config = {
+                read: viewData.read,
+                write: viewData.write,
+                fetch: options?.fetch,
+                defaultHeaders: options?.defaultHeaders,
+            };
+            return new ApiDataSource(config);
+        }
+        case 'value':
+            return new ValueDataSource({
+                items: (viewData.items ?? []),
+                idField: options?.idField,
+            });
+        default:
+            // Unknown provider — fall back to context
+            return fallback ?? null;
+    }
+}

package/dist/data-scope/DataScopeManager.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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/core - DataScope Manager
+ *
+ * Runtime implementation of the DataContext interface for managing
+ * named data scopes. Provides row-level data access control and
+ * reactive data state management within the UI component tree.
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+import type { DataScope, DataContext, DataSource } from '@object-ui/types';
+/**
+ * Row-level filter for restricting data access within a scope
+ */
+export interface RowLevelFilter {
+    /** Field to filter on */
+    field: string;
+    /** Filter operator */
+    operator: 'eq' | 'ne' | 'gt' | 'lt' | 'gte' | 'lte' | 'in' | 'nin' | 'contains';
+    /** Filter value */
+    value: any;
+}
+/**
+ * Configuration for creating a data scope
+ */
+export interface DataScopeConfig {
+    /** Data source instance */
+    dataSource?: DataSource;
+    /** Initial data */
+    data?: any;
+    /** Row-level filters to apply */
+    filters?: RowLevelFilter[];
+    /** Whether this scope is read-only */
+    readOnly?: boolean;
+}
+/**
+ * DataScopeManager — Runtime implementation of DataContext.
+ *
+ * Manages named data scopes for the component tree, providing:
+ * - Scope registration and lookup
+ * - Row-level security via filters
+ * - Data state management (data, loading, error)
+ *
+ * @example
+ * ```ts
+ * const manager = new DataScopeManager();
+ * manager.registerScope('contacts', {
+ *   dataSource: myDataSource,
+ *   data: [],
+ * });
+ * const scope = manager.getScope('contacts');
+ * ```
+ */
+export declare class DataScopeManager implements DataContext {
+    scopes: Record<string, DataScope>;
+    private filters;
+    private readOnlyScopes;
+    private listeners;
+    /**
+     * Register a data scope
+     */
+    registerScope(name: string, scope: DataScope): void;
+    /**
+     * Register a data scope with configuration
+     */
+    registerScopeWithConfig(name: string, config: DataScopeConfig): void;
+    /**
+     * Get a data scope by name
+     */
+    getScope(name: string): DataScope | undefined;
+    /**
+     * Remove a data scope
+     */
+    removeScope(name: string): void;
+    /**
+     * Check if a scope is read-only
+     */
+    isReadOnly(name: string): boolean;
+    /**
+     * Get row-level filters for a scope
+     */
+    getFilters(name: string): RowLevelFilter[];
+    /**
+     * Set row-level filters for a scope
+     */
+    setFilters(name: string, filters: RowLevelFilter[]): void;
+    /**
+     * Apply row-level filters to a dataset
+     */
+    applyFilters(name: string, data: any[]): any[];
+    /**
+     * Update data in a scope
+     */
+    updateScopeData(name: string, data: any): void;
+    /**
+     * Update loading state for a scope
+     */
+    updateScopeLoading(name: string, loading: boolean): void;
+    /**
+     * Update error state for a scope
+     */
+    updateScopeError(name: string, error: Error | string | null): void;
+    /**
+     * Subscribe to scope changes
+     */
+    onScopeChange(name: string, listener: (scope: DataScope) => void): () => void;
+    /**
+     * Get all registered scope names
+     */
+    getScopeNames(): string[];
+    /**
+     * Clear all scopes
+     */
+    clear(): void;
+    private notifyListeners;
+}
+/**
+ * Default DataScopeManager instance
+ */
+export declare const defaultDataScopeManager: DataScopeManager;

package/dist/data-scope/DataScopeManager.js

@@ -0,0 +1,229 @@
+/**
+ * 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.
+ */
+/**
+ * DataScopeManager — Runtime implementation of DataContext.
+ *
+ * Manages named data scopes for the component tree, providing:
+ * - Scope registration and lookup
+ * - Row-level security via filters
+ * - Data state management (data, loading, error)
+ *
+ * @example
+ * ```ts
+ * const manager = new DataScopeManager();
+ * manager.registerScope('contacts', {
+ *   dataSource: myDataSource,
+ *   data: [],
+ * });
+ * const scope = manager.getScope('contacts');
+ * ```
+ */
+export class DataScopeManager {
+    constructor() {
+        Object.defineProperty(this, "scopes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "filters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {}
+        });
+        Object.defineProperty(this, "readOnlyScopes", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    /**
+     * Register a data scope
+     */
+    registerScope(name, scope) {
+        this.scopes[name] = scope;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Register a data scope with configuration
+     */
+    registerScopeWithConfig(name, config) {
+        const scope = {
+            dataSource: config.dataSource,
+            data: config.data,
+            loading: false,
+            error: null,
+        };
+        if (config.filters) {
+            this.filters[name] = config.filters;
+        }
+        if (config.readOnly) {
+            this.readOnlyScopes.add(name);
+        }
+        this.scopes[name] = scope;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Get a data scope by name
+     */
+    getScope(name) {
+        return this.scopes[name];
+    }
+    /**
+     * Remove a data scope
+     */
+    removeScope(name) {
+        delete this.scopes[name];
+        delete this.filters[name];
+        this.readOnlyScopes.delete(name);
+        this.listeners.delete(name);
+    }
+    /**
+     * Check if a scope is read-only
+     */
+    isReadOnly(name) {
+        return this.readOnlyScopes.has(name);
+    }
+    /**
+     * Get row-level filters for a scope
+     */
+    getFilters(name) {
+        return this.filters[name] || [];
+    }
+    /**
+     * Set row-level filters for a scope
+     */
+    setFilters(name, filters) {
+        this.filters[name] = filters;
+    }
+    /**
+     * Apply row-level filters to a dataset
+     */
+    applyFilters(name, data) {
+        const scopeFilters = this.filters[name];
+        if (!scopeFilters || scopeFilters.length === 0) {
+            return data;
+        }
+        return data.filter(row => {
+            return scopeFilters.every(filter => {
+                const fieldValue = row[filter.field];
+                return evaluateFilter(fieldValue, filter.operator, filter.value);
+            });
+        });
+    }
+    /**
+     * Update data in a scope
+     */
+    updateScopeData(name, data) {
+        const scope = this.scopes[name];
+        if (!scope)
+            return;
+        if (this.readOnlyScopes.has(name)) {
+            throw new Error(`Cannot update read-only scope: ${name}`);
+        }
+        scope.data = data;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Update loading state for a scope
+     */
+    updateScopeLoading(name, loading) {
+        const scope = this.scopes[name];
+        if (!scope)
+            return;
+        scope.loading = loading;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Update error state for a scope
+     */
+    updateScopeError(name, error) {
+        const scope = this.scopes[name];
+        if (!scope)
+            return;
+        scope.error = error;
+        this.notifyListeners(name, scope);
+    }
+    /**
+     * Subscribe to scope changes
+     */
+    onScopeChange(name, listener) {
+        if (!this.listeners.has(name)) {
+            this.listeners.set(name, []);
+        }
+        this.listeners.get(name).push(listener);
+        return () => {
+            const arr = this.listeners.get(name);
+            if (arr) {
+                const idx = arr.indexOf(listener);
+                if (idx >= 0)
+                    arr.splice(idx, 1);
+            }
+        };
+    }
+    /**
+     * Get all registered scope names
+     */
+    getScopeNames() {
+        return Object.keys(this.scopes);
+    }
+    /**
+     * Clear all scopes
+     */
+    clear() {
+        this.scopes = {};
+        this.filters = {};
+        this.readOnlyScopes.clear();
+        this.listeners.clear();
+    }
+    notifyListeners(name, scope) {
+        const arr = this.listeners.get(name);
+        if (arr) {
+            arr.forEach(listener => listener(scope));
+        }
+    }
+}
+/**
+ * Evaluate a single filter condition against a field value
+ */
+function evaluateFilter(fieldValue, operator, filterValue) {
+    switch (operator) {
+        case 'eq':
+            return fieldValue === filterValue;
+        case 'ne':
+            return fieldValue !== filterValue;
+        case 'gt':
+            return fieldValue > filterValue;
+        case 'lt':
+            return fieldValue < filterValue;
+        case 'gte':
+            return fieldValue >= filterValue;
+        case 'lte':
+            return fieldValue <= filterValue;
+        case 'in':
+            return Array.isArray(filterValue) && filterValue.includes(fieldValue);
+        case 'nin':
+            return Array.isArray(filterValue) && !filterValue.includes(fieldValue);
+        case 'contains':
+            return typeof fieldValue === 'string' && fieldValue.includes(String(filterValue));
+        default:
+            return true;
+    }
+}
+/**
+ * Default DataScopeManager instance
+ */
+export const defaultDataScopeManager = new DataScopeManager();

package/dist/data-scope/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @object-ui/core - DataScope Module
+ *
+ * Runtime data scope management for row-level security and
+ * reactive data state within the UI component tree.
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+export { DataScopeManager, defaultDataScopeManager, type RowLevelFilter, type DataScopeConfig, } from './DataScopeManager.js';

package/dist/data-scope/index.js

@@ -0,0 +1,10 @@
+/**
+ * @object-ui/core - DataScope Module
+ *
+ * Runtime data scope management for row-level security and
+ * reactive data state within the UI component tree.
+ *
+ * @module data-scope
+ * @packageDocumentation
+ */
+export { DataScopeManager, defaultDataScopeManager, } from './DataScopeManager.js';

package/dist/errors/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+export interface ErrorCodeEntry {
+    code: string;
+    message: string;
+    suggestion: string;
+    docUrl: string;
+}
+export declare const ERROR_CODES: Record<string, ErrorCodeEntry>;
+/**
+ * Check whether a string is a known ObjectUI error code.
+ */
+export declare function isErrorCode(code: unknown): code is keyof typeof ERROR_CODES;
+/**
+ * Base error class for all ObjectUI errors.
+ */
+export declare class ObjectUIError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+    /**
+     * Convert error to JSON for logging / debugging.
+     */
+    toJSON(): {
+        name: string;
+        message: string;
+        code: string;
+        details: Record<string, unknown> | undefined;
+        stack: string | undefined;
+    };
+}
+/**
+ * Type guard to check if an error is an ObjectUIError.
+ */
+export declare function isObjectUIError(error: unknown): error is ObjectUIError;
+/** Thrown when a schema is invalid or fails validation. */
+export declare class SchemaError extends ObjectUIError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Thrown when a registry operation fails. */
+export declare class RegistryError extends ObjectUIError {
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+/** Thrown when expression evaluation fails. */
+export declare class ExpressionError extends ObjectUIError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/** Thrown when a plugin operation fails. */
+export declare class PluginError extends ObjectUIError {
+    constructor(message: string, code: string, details?: Record<string, unknown>);
+}
+/** Thrown when validation of user input / field config fails. */
+export declare class FieldValidationError extends ObjectUIError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Create an `ObjectUIError` (or subclass) from a known error code.
+ *
+ * @param code   - A registered error code (e.g. `"OBJUI-001"`).
+ * @param params - Values to interpolate into the message template.
+ * @param details - Optional extra details attached to the error.
+ */
+export declare function createError(code: string, params?: Record<string, string>, details?: Record<string, unknown>): ObjectUIError;
+/**
+ * Format an error message with actionable fix suggestions in development mode.
+ *
+ * @param error - The `ObjectUIError` to format.
+ * @param isDev - When `true`, appends the suggestion and documentation link.
+ */
+export declare function formatErrorMessage(error: ObjectUIError, isDev?: boolean): string;