@object-ui/core 3.0.2 → 3.1.0

package/dist/utils/expand-fields.js

@@ -0,0 +1,68 @@
+/**
+ * ObjectUI — expand-fields utility
+ * 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.
+ */
+/**
+ * Build an array of field names that should be included in `$expand`
+ * when fetching data. This scans the given object schema fields
+ * (and optional column configuration) for `lookup` and `master_detail`
+ * field types, so the backend (e.g. objectql) returns expanded objects
+ * instead of raw foreign-key IDs.
+ *
+ * @param schemaFields - Object map of field metadata from `getObjectSchema()`,
+ *   e.g. `{ account: { type: 'lookup', reference_to: 'accounts' }, ... }`.
+ * @param columns - Optional explicit column list. When provided, only
+ *   lookup/master_detail fields that appear in `columns` are expanded.
+ *   Accepts `string[]` or `ListColumn[]` (objects with a `field` property).
+ * @returns Array of field names to pass as `$expand`.
+ *
+ * @example
+ * ```ts
+ * const fields = {
+ *   name: { type: 'text' },
+ *   account: { type: 'lookup', reference_to: 'accounts' },
+ *   parent: { type: 'master_detail', reference_to: 'contacts' },
+ * };
+ * buildExpandFields(fields);
+ * // → ['account', 'parent']
+ *
+ * buildExpandFields(fields, ['name', 'account']);
+ * // → ['account']
+ * ```
+ */
+export function buildExpandFields(schemaFields, columns) {
+    if (!schemaFields || typeof schemaFields !== 'object') {
+        return [];
+    }
+    // Collect all lookup / master_detail field names from the schema
+    const lookupFieldNames = [];
+    for (const [fieldName, fieldDef] of Object.entries(schemaFields)) {
+        if (fieldDef &&
+            typeof fieldDef === 'object' &&
+            (fieldDef.type === 'lookup' || fieldDef.type === 'master_detail')) {
+            lookupFieldNames.push(fieldName);
+        }
+    }
+    if (lookupFieldNames.length === 0) {
+        return [];
+    }
+    // When columns are provided, restrict expansion to visible columns only
+    if (columns && Array.isArray(columns) && columns.length > 0) {
+        const columnFieldNames = new Set();
+        for (const col of columns) {
+            if (typeof col === 'string') {
+                columnFieldNames.add(col);
+            }
+            else if (col && typeof col === 'object') {
+                const name = col.field ?? col.name ?? col.fieldName;
+                if (name)
+                    columnFieldNames.add(name);
+            }
+        }
+        return lookupFieldNames.filter((f) => columnFieldNames.has(f));
+    }
+    return lookupFieldNames;
+}

package/dist/utils/extract-records.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+/**
+ * Extract an array of records from various API response formats.
+ * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
+ *
+ * This utility normalises the different shapes returned by ObjectStack,
+ * OData, and MSW mock endpoints so that every data-fetching component
+ * can rely on a single extraction path.
+ */
+export declare function extractRecords(results: unknown): any[];

package/dist/utils/extract-records.js

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+/**
+ * Extract an array of records from various API response formats.
+ * Supports: raw array, { records: [] }, { data: [] }, { value: [] }.
+ *
+ * This utility normalises the different shapes returned by ObjectStack,
+ * OData, and MSW mock endpoints so that every data-fetching component
+ * can rely on a single extraction path.
+ */
+export function extractRecords(results) {
+    if (Array.isArray(results)) {
+        return results;
+    }
+    if (results && typeof results === 'object') {
+        if (Array.isArray(results.records)) {
+            return results.records;
+        }
+        if (Array.isArray(results.data)) {
+            return results.data;
+        }
+        if (Array.isArray(results.value)) {
+            return results.value;
+        }
+    }
+    return [];
+}

package/dist/utils/normalize-quick-filter.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+/**
+ * QuickFilter Normalization Utility
+ *
+ * Adapter layer that converts between two QuickFilter formats:
+ * - Spec format:     { field, operator, value }
+ * - ObjectUI format: { id, label, filters[], icon?, defaultActive? }
+ *
+ * Both formats are accepted; spec-format items are auto-converted to ObjectUI format.
+ */
+import type { QuickFilterItem, ObjectUIQuickFilterItem } from '@object-ui/types';
+/** Normalized ObjectUI QuickFilter shape (output of normalizeQuickFilter) */
+export type NormalizedQuickFilter = ObjectUIQuickFilterItem;
+/**
+ * Normalize a single QuickFilter item.
+ * - If it's already in ObjectUI format (has id + label + filters), return as-is.
+ * - If it's in Spec format (has field + operator), convert to ObjectUI format.
+ */
+export declare function normalizeQuickFilter(item: QuickFilterItem): NormalizedQuickFilter;
+/**
+ * Normalize an array of QuickFilter items (mixed formats accepted).
+ */
+export declare function normalizeQuickFilters(items: QuickFilterItem[] | undefined): NormalizedQuickFilter[] | undefined;

package/dist/utils/normalize-quick-filter.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+/**
+ * Map a human-readable / spec operator to the ObjectStack AST operator.
+ */
+function mapSpecOperator(op) {
+    switch (op) {
+        case 'equals':
+        case 'eq': return '=';
+        case 'notEquals':
+        case 'ne':
+        case 'neq': return '!=';
+        case 'contains': return 'contains';
+        case 'notContains': return 'notcontains';
+        case 'greaterThan':
+        case 'gt': return '>';
+        case 'greaterOrEqual':
+        case 'gte': return '>=';
+        case 'lessThan':
+        case 'lt': return '<';
+        case 'lessOrEqual':
+        case 'lte': return '<=';
+        case 'in': return 'in';
+        case 'notIn': return 'not in';
+        case 'before': return '<';
+        case 'after': return '>';
+        default: return op;
+    }
+}
+/**
+ * Normalize a single QuickFilter item.
+ * - If it's already in ObjectUI format (has id + label + filters), return as-is.
+ * - If it's in Spec format (has field + operator), convert to ObjectUI format.
+ */
+export function normalizeQuickFilter(item) {
+    // Already in ObjectUI format
+    if ('id' in item && 'filters' in item && item.label && Array.isArray(item.filters)) {
+        return item;
+    }
+    // Spec format: { field, operator, value }
+    if ('field' in item && 'operator' in item) {
+        const op = mapSpecOperator(item.operator);
+        return {
+            id: `${item.field}-${item.operator}-${String(item.value ?? '')}`,
+            label: item.label || `${item.field} ${item.operator} ${String(item.value ?? '')}`,
+            filters: [[item.field, op, item.value]],
+            icon: item.icon,
+            defaultActive: item.defaultActive,
+        };
+    }
+    // Unknown format — return as-is
+    return item;
+}
+/**
+ * Normalize an array of QuickFilter items (mixed formats accepted).
+ */
+export function normalizeQuickFilters(items) {
+    if (!items || items.length === 0)
+        return undefined;
+    return items.map(normalizeQuickFilter);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -24,10 +24,10 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^3.0.4",
+    "@objectstack/spec": "^3.2.0",
     "lodash": "^4.17.23",
     "zod": "^4.3.6",
-    "@object-ui/types": "3.0.2"
+    "@object-ui/types": "3.1.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

package/src/__tests__/protocols/DndProtocol.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect } from 'vitest';
+import type { DndConfig, DragItem, DropZone, DragConstraint } from '@object-ui/types';
+import {
+  resolveDndConfig,
+  createDragItemProps,
+  createDropZoneProps,
+  resolveDragConstraints,
+} from '../../protocols/DndProtocol';
+
+describe('DndProtocol', () => {
+  // ==========================================================================
+  // resolveDndConfig
+  // ==========================================================================
+  describe('resolveDndConfig', () => {
+    it('should apply all defaults for minimal config', () => {
+      const config = {} as DndConfig;
+      const resolved = resolveDndConfig(config);
+
+      expect(resolved.enabled).toBe(false);
+      expect(resolved.sortable).toBe(false);
+      expect(resolved.autoScroll).toBe(true);
+      expect(resolved.touchDelay).toBe(200);
+      expect(resolved.dragItem).toBeUndefined();
+      expect(resolved.dropZone).toBeUndefined();
+    });
+
+    it('should preserve explicit values', () => {
+      const config = {
+        enabled: true,
+        sortable: true,
+        autoScroll: false,
+        touchDelay: 500,
+      } as DndConfig;
+      const resolved = resolveDndConfig(config);
+
+      expect(resolved.enabled).toBe(true);
+      expect(resolved.sortable).toBe(true);
+      expect(resolved.autoScroll).toBe(false);
+      expect(resolved.touchDelay).toBe(500);
+    });
+
+    it('should pass through dragItem and dropZone', () => {
+      const dragItem = { type: 'card' } as DragItem;
+      const dropZone = { accept: ['card'] } as DropZone;
+      const config = { dragItem, dropZone } as DndConfig;
+      const resolved = resolveDndConfig(config);
+
+      expect(resolved.dragItem).toBe(dragItem);
+      expect(resolved.dropZone).toBe(dropZone);
+    });
+  });
+
+  // ==========================================================================
+  // createDragItemProps
+  // ==========================================================================
+  describe('createDragItemProps', () => {
+    it('should return correct props for a basic drag item', () => {
+      const item = { type: 'card', label: 'Task card' } as DragItem;
+      const props = createDragItemProps(item);
+
+      expect(props.draggable).toBe(true);
+      expect(props['aria-roledescription']).toBe('draggable');
+      expect(props['aria-label']).toBe('Task card');
+      expect(props.role).toBe('listitem');
+      expect(props['data-drag-type']).toBe('card');
+      expect(props['data-drag-handle']).toBe('element');
+      expect(props['data-drag-disabled']).toBe('false');
+    });
+
+    it('should set draggable false when disabled', () => {
+      const item = { type: 'card', disabled: true } as DragItem;
+      const props = createDragItemProps(item);
+
+      expect(props.draggable).toBe(false);
+      expect(props['data-drag-disabled']).toBe('true');
+    });
+
+    it('should use ariaLabel over label when both provided', () => {
+      const item = { type: 'card', label: 'Label', ariaLabel: 'Aria Label' } as DragItem;
+      const props = createDragItemProps(item);
+
+      expect(props['aria-label']).toBe('Aria Label');
+    });
+
+    it('should handle translation object for ariaLabel', () => {
+      const item = {
+        type: 'card',
+        ariaLabel: { key: 'drag.label', defaultValue: 'Translated label' },
+      } as unknown as DragItem;
+      const props = createDragItemProps(item);
+
+      expect(props['aria-label']).toBe('Translated label');
+    });
+
+    it('should use custom role and handle when provided', () => {
+      const item = { type: 'row', role: 'option', handle: 'grip' } as DragItem;
+      const props = createDragItemProps(item);
+
+      expect(props.role).toBe('option');
+      expect(props['data-drag-handle']).toBe('grip');
+    });
+  });
+
+  // ==========================================================================
+  // createDropZoneProps
+  // ==========================================================================
+  describe('createDropZoneProps', () => {
+    it('should return correct props for a basic drop zone', () => {
+      const zone = { accept: ['card', 'task'], label: 'Column' } as unknown as DropZone;
+      const props = createDropZoneProps(zone);
+
+      expect(props['aria-dropeffect']).toBe('move');
+      expect(props['aria-label']).toBe('Column');
+      expect(props.role).toBe('list');
+      expect(props['data-drop-accept']).toBe('card,task');
+      expect(props['data-drop-highlight']).toBe('true');
+    });
+
+    it('should use explicit dropEffect and role', () => {
+      const zone = { accept: ['item'], dropEffect: 'copy', role: 'region' } as unknown as DropZone;
+      const props = createDropZoneProps(zone);
+
+      expect(props['aria-dropeffect']).toBe('copy');
+      expect(props.role).toBe('region');
+    });
+
+    it('should set maxItems when provided', () => {
+      const zone = { accept: ['card'], maxItems: 10 } as unknown as DropZone;
+      const props = createDropZoneProps(zone);
+
+      expect(props['data-drop-max-items']).toBe(10);
+    });
+
+    it('should handle ariaLabel as translation object', () => {
+      const zone = {
+        accept: ['card'],
+        ariaLabel: { key: 'drop.label', defaultValue: 'Drop here' },
+      } as unknown as DropZone;
+      const props = createDropZoneProps(zone);
+
+      expect(props['aria-label']).toBe('Drop here');
+    });
+  });
+
+  // ==========================================================================
+  // resolveDragConstraints
+  // ==========================================================================
+  describe('resolveDragConstraints', () => {
+    it('should return base styles for default axis (both)', () => {
+      const constraint = {} as DragConstraint;
+      const styles = resolveDragConstraints(constraint);
+
+      expect(styles.position).toBe('relative');
+      expect(styles.touchAction).toBe('none');
+    });
+
+    it('should set touchAction to pan-y for x axis', () => {
+      const constraint = { axis: 'x' } as DragConstraint;
+      const styles = resolveDragConstraints(constraint);
+
+      expect(styles.touchAction).toBe('pan-y');
+    });
+
+    it('should set touchAction to pan-x for y axis', () => {
+      const constraint = { axis: 'y' } as DragConstraint;
+      const styles = resolveDragConstraints(constraint);
+
+      expect(styles.touchAction).toBe('pan-x');
+    });
+
+    it('should set overflow hidden for parent bounds', () => {
+      const constraint = { bounds: 'parent' } as DragConstraint;
+      const styles = resolveDragConstraints(constraint);
+
+      expect(styles.overflow).toBe('hidden');
+    });
+
+    it('should set grid CSS custom properties', () => {
+      const constraint = { grid: [20, 30] } as unknown as DragConstraint;
+      const styles = resolveDragConstraints(constraint);
+
+      expect(styles['--drag-grid-x']).toBe('20px');
+      expect(styles['--drag-grid-y']).toBe('30px');
+    });
+  });
+});

package/src/__tests__/protocols/KeyboardProtocol.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect } from 'vitest';
+import type { KeyboardNavigationConfig, FocusTrapConfig } from '@object-ui/types';
+import {
+  resolveKeyboardConfig,
+  parseShortcutKey,
+  matchesShortcut,
+  createFocusTrapConfig,
+} from '../../protocols/KeyboardProtocol';
+
+describe('KeyboardProtocol', () => {
+  // ==========================================================================
+  // resolveKeyboardConfig
+  // ==========================================================================
+  describe('resolveKeyboardConfig', () => {
+    it('should apply defaults for empty config', () => {
+      const config = {} as KeyboardNavigationConfig;
+      const resolved = resolveKeyboardConfig(config);
+
+      expect(resolved.shortcuts).toEqual([]);
+      expect(resolved.rovingTabindex).toBe(false);
+      expect(resolved.focusManagement.tabOrder).toBe('auto');
+      expect(resolved.focusManagement.skipLinks).toBe(false);
+      expect(resolved.focusManagement.focusVisible).toBe(true);
+      expect(resolved.focusManagement.arrowNavigation).toBe(false);
+      expect(resolved.focusManagement.focusTrap).toBeUndefined();
+    });
+
+    it('should resolve ariaLabel from string', () => {
+      const config = { ariaLabel: 'Navigation' } as KeyboardNavigationConfig;
+      const resolved = resolveKeyboardConfig(config);
+
+      expect(resolved.ariaLabel).toBe('Navigation');
+    });
+
+    it('should resolve ariaLabel from translation object', () => {
+      const config = {
+        ariaLabel: { key: 'nav.label', defaultValue: 'Nav panel' },
+      } as unknown as KeyboardNavigationConfig;
+      const resolved = resolveKeyboardConfig(config);
+
+      expect(resolved.ariaLabel).toBe('Nav panel');
+    });
+
+    it('should preserve explicit values', () => {
+      const config = {
+        rovingTabindex: true,
+        role: 'toolbar',
+        ariaDescribedBy: 'desc-id',
+      } as KeyboardNavigationConfig;
+      const resolved = resolveKeyboardConfig(config);
+
+      expect(resolved.rovingTabindex).toBe(true);
+      expect(resolved.role).toBe('toolbar');
+      expect(resolved.ariaDescribedBy).toBe('desc-id');
+    });
+  });
+
+  // ==========================================================================
+  // parseShortcutKey
+  // ==========================================================================
+  describe('parseShortcutKey', () => {
+    it('should parse Ctrl+S', () => {
+      const parsed = parseShortcutKey('Ctrl+S');
+
+      expect(parsed.key).toBe('s');
+      expect(parsed.ctrlOrMeta).toBe(true);
+      expect(parsed.shift).toBe(false);
+      expect(parsed.alt).toBe(false);
+    });
+
+    it('should parse Alt+Shift+N', () => {
+      const parsed = parseShortcutKey('Alt+Shift+N');
+
+      expect(parsed.key).toBe('n');
+      expect(parsed.ctrlOrMeta).toBe(false);
+      expect(parsed.shift).toBe(true);
+      expect(parsed.alt).toBe(true);
+    });
+
+    it('should parse single key Escape', () => {
+      const parsed = parseShortcutKey('Escape');
+
+      expect(parsed.key).toBe('escape');
+      expect(parsed.ctrlOrMeta).toBe(false);
+      expect(parsed.shift).toBe(false);
+      expect(parsed.alt).toBe(false);
+    });
+
+    it('should be case insensitive', () => {
+      const parsed = parseShortcutKey('ctrl+s');
+
+      expect(parsed.key).toBe('s');
+      expect(parsed.ctrlOrMeta).toBe(true);
+    });
+
+    it('should parse single key F1', () => {
+      const parsed = parseShortcutKey('F1');
+
+      expect(parsed.key).toBe('f1');
+      expect(parsed.ctrlOrMeta).toBe(false);
+      expect(parsed.shift).toBe(false);
+      expect(parsed.alt).toBe(false);
+    });
+
+    it('should recognise Meta as ctrlOrMeta', () => {
+      const parsed = parseShortcutKey('Meta+K');
+
+      expect(parsed.ctrlOrMeta).toBe(true);
+      expect(parsed.key).toBe('k');
+    });
+  });
+
+  // ==========================================================================
+  // matchesShortcut
+  // ==========================================================================
+  describe('matchesShortcut', () => {
+    it('should match Ctrl+S event', () => {
+      const event = { key: 's', ctrlKey: true };
+      expect(matchesShortcut(event, 'Ctrl+S')).toBe(true);
+    });
+
+    it('should match Meta+S event (Cmd on Mac)', () => {
+      const event = { key: 's', metaKey: true };
+      expect(matchesShortcut(event, 'Ctrl+S')).toBe(true);
+    });
+
+    it('should not match when key differs', () => {
+      const event = { key: 'a', ctrlKey: true };
+      expect(matchesShortcut(event, 'Ctrl+S')).toBe(false);
+    });
+
+    it('should not match when modifier is missing', () => {
+      const event = { key: 's' };
+      expect(matchesShortcut(event, 'Ctrl+S')).toBe(false);
+    });
+
+    it('should not match when extra modifier is present', () => {
+      const event = { key: 's', ctrlKey: true, shiftKey: true };
+      expect(matchesShortcut(event, 'Ctrl+S')).toBe(false);
+    });
+
+    it('should match Escape without modifiers', () => {
+      const event = { key: 'Escape' };
+      expect(matchesShortcut(event, 'Escape')).toBe(true);
+    });
+  });
+
+  // ==========================================================================
+  // createFocusTrapConfig
+  // ==========================================================================
+  describe('createFocusTrapConfig', () => {
+    it('should apply defaults for minimal config', () => {
+      const config = {} as FocusTrapConfig;
+      const resolved = createFocusTrapConfig(config);
+
+      expect(resolved.enabled).toBe(false);
+      expect(resolved.returnFocus).toBe(true);
+      expect(resolved.escapeDeactivates).toBe(true);
+      expect(resolved.initialFocus).toBeUndefined();
+    });
+
+    it('should preserve explicit values', () => {
+      const config = {
+        enabled: true,
+        initialFocus: '#first-input',
+        returnFocus: false,
+        escapeDeactivates: false,
+      } as FocusTrapConfig;
+      const resolved = createFocusTrapConfig(config);
+
+      expect(resolved.enabled).toBe(true);
+      expect(resolved.initialFocus).toBe('#first-input');
+      expect(resolved.returnFocus).toBe(false);
+      expect(resolved.escapeDeactivates).toBe(false);
+    });
+  });
+});