@object-ui/core 3.0.3 → 3.1.0

package/src/protocols/ResponsiveProtocol.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/core - Responsive Protocol Bridge
+ *
+ * Converts spec-aligned ResponsiveConfig schemas into Tailwind CSS
+ * utility classes for visibility, grid columns, and ordering across
+ * breakpoints. Also provides runtime width-based visibility checks.
+ *
+ * @module protocols/ResponsiveProtocol
+ * @packageDocumentation
+ */
+
+import type { SpecResponsiveConfig } from '@object-ui/types';
+
+// ============================================================================
+// Breakpoint Definitions
+// ============================================================================
+
+/** Breakpoint name type matching Tailwind defaults. */
+export type BreakpointKey = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+
+/** Breakpoint minimum pixel widths aligned with Tailwind CSS defaults. */
+export const BREAKPOINT_VALUES: Record<BreakpointKey, number> = {
+  xs: 0,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536,
+};
+
+/** Ordered breakpoint keys from smallest to largest. */
+const BREAKPOINT_ORDER: BreakpointKey[] = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+// ============================================================================
+// Resolved Types
+// ============================================================================
+
+/** Fully resolved responsive configuration. */
+export interface ResolvedResponsiveConfig {
+  breakpoint?: BreakpointKey;
+  hiddenOn: BreakpointKey[];
+  columns: Partial<Record<BreakpointKey, number>>;
+  order: Partial<Record<BreakpointKey, number>>;
+}
+
+// ============================================================================
+// Config Resolution
+// ============================================================================
+
+/**
+ * Resolve a responsive configuration by applying defaults.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Fully resolved responsive configuration
+ */
+export function resolveResponsiveConfig(config: SpecResponsiveConfig): ResolvedResponsiveConfig {
+  return {
+    breakpoint: config.breakpoint as BreakpointKey | undefined,
+    hiddenOn: (config.hiddenOn ?? []) as BreakpointKey[],
+    columns: (config.columns ?? {}) as Partial<Record<BreakpointKey, number>>,
+    order: (config.order ?? {}) as Partial<Record<BreakpointKey, number>>,
+  };
+}
+
+// ============================================================================
+// Visibility Classes
+// ============================================================================
+
+/**
+ * Generate Tailwind CSS classes for responsive visibility.
+ *
+ * If `breakpoint` is set, the element is hidden below that breakpoint
+ * (e.g. breakpoint "md" → `['hidden', 'md:block']`).
+ *
+ * If `hiddenOn` contains breakpoints, the element is hidden at those
+ * specific sizes (e.g. hiddenOn: ["sm", "lg"] → `['sm:hidden', 'md:block', 'lg:hidden', 'xl:block']`).
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Array of Tailwind CSS class strings
+ */
+export function getVisibilityClasses(config: SpecResponsiveConfig): string[] {
+  const classes: string[] = [];
+
+  // Minimum breakpoint visibility
+  if (config.breakpoint) {
+    const bp = config.breakpoint as BreakpointKey;
+    if (bp !== 'xs') {
+      classes.push('hidden');
+      classes.push(`${bp}:block`);
+    }
+  }
+
+  // Per-breakpoint hidden overrides
+  const hiddenOn = (config.hiddenOn ?? []) as BreakpointKey[];
+  if (hiddenOn.length > 0) {
+    for (let i = 0; i < BREAKPOINT_ORDER.length; i++) {
+      const bp = BREAKPOINT_ORDER[i];
+      const isHidden = hiddenOn.includes(bp);
+      const prevHidden = i > 0 ? hiddenOn.includes(BREAKPOINT_ORDER[i - 1]) : false;
+
+      if (isHidden && !prevHidden) {
+        classes.push(bp === 'xs' ? 'hidden' : `${bp}:hidden`);
+      } else if (!isHidden && prevHidden) {
+        classes.push(bp === 'xs' ? 'block' : `${bp}:block`);
+      }
+    }
+  }
+
+  return classes;
+}
+
+// ============================================================================
+// Column Classes
+// ============================================================================
+
+/**
+ * Generate Tailwind grid-cols classes for responsive column layouts.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Array of Tailwind CSS grid column class strings
+ */
+export function getColumnClasses(config: SpecResponsiveConfig): string[] {
+  const classes: string[] = [];
+  const columns = (config.columns ?? {}) as Partial<Record<BreakpointKey, number>>;
+
+  for (const bp of BREAKPOINT_ORDER) {
+    const cols = columns[bp];
+    if (cols == null) continue;
+    const prefix = bp === 'xs' ? '' : `${bp}:`;
+    classes.push(`${prefix}grid-cols-${cols}`);
+  }
+
+  return classes;
+}
+
+// ============================================================================
+// Order Classes
+// ============================================================================
+
+/**
+ * Generate Tailwind order utility classes for responsive ordering.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Array of Tailwind CSS order class strings
+ */
+export function getOrderClasses(config: SpecResponsiveConfig): string[] {
+  const classes: string[] = [];
+  const order = (config.order ?? {}) as Partial<Record<BreakpointKey, number>>;
+
+  for (const bp of BREAKPOINT_ORDER) {
+    const ord = order[bp];
+    if (ord == null) continue;
+    const prefix = bp === 'xs' ? '' : `${bp}:`;
+    classes.push(`${prefix}order-${ord}`);
+  }
+
+  return classes;
+}
+
+// ============================================================================
+// Runtime Width Check
+// ============================================================================
+
+/**
+ * Determine whether a component should be hidden at a given viewport width.
+ *
+ * Checks both the minimum `breakpoint` threshold and the `hiddenOn` list.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @param width - Current viewport width in pixels
+ * @returns `true` if the component should be hidden at the given width
+ */
+export function shouldHideAtBreakpoint(config: SpecResponsiveConfig, width: number): boolean {
+  // Check minimum breakpoint
+  if (config.breakpoint) {
+    const minWidth = BREAKPOINT_VALUES[config.breakpoint as BreakpointKey];
+    if (minWidth !== undefined && width < minWidth) {
+      return true;
+    }
+  }
+
+  // Check hiddenOn list
+  const hiddenOn = (config.hiddenOn ?? []) as BreakpointKey[];
+  if (hiddenOn.length > 0) {
+    const currentBp = getCurrentBreakpoint(width);
+    return hiddenOn.includes(currentBp);
+  }
+
+  return false;
+}
+
+/**
+ * Determine the current breakpoint name for a given width.
+ */
+function getCurrentBreakpoint(width: number): BreakpointKey {
+  for (let i = BREAKPOINT_ORDER.length - 1; i >= 0; i--) {
+    if (width >= BREAKPOINT_VALUES[BREAKPOINT_ORDER[i]]) {
+      return BREAKPOINT_ORDER[i];
+    }
+  }
+  return 'xs';
+}

package/src/protocols/SharingProtocol.ts

@@ -0,0 +1,185 @@
+/**
+ * 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 - Sharing Protocol Bridge
+ *
+ * Converts spec-aligned SharingConfig and EmbedConfig schemas into
+ * runtime-usable configurations. Provides embed code generation and
+ * configuration validation.
+ *
+ * @module protocols/SharingProtocol
+ * @packageDocumentation
+ */
+
+import type { SharingConfig, EmbedConfig } from '@object-ui/types';
+
+// ============================================================================
+// Resolved Types
+// ============================================================================
+
+/** Fully resolved sharing configuration. */
+export interface ResolvedSharingConfig {
+  enabled: boolean;
+  publicLink?: string;
+  password?: string;
+  allowedDomains: string[];
+  expiresAt?: string;
+  allowAnonymous: boolean;
+}
+
+/** Fully resolved embed configuration. */
+export interface ResolvedEmbedConfig {
+  enabled: boolean;
+  allowedOrigins: string[];
+  width: string;
+  height: string;
+  showHeader: boolean;
+  showNavigation: boolean;
+  responsive: boolean;
+}
+
+/** Validation result for sharing configuration. */
+export interface SharingValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+// ============================================================================
+// Sharing Config Resolution
+// ============================================================================
+
+/**
+ * Resolve a sharing configuration by applying spec defaults.
+ *
+ * @param config - Partial SharingConfig from the spec
+ * @returns Fully resolved sharing configuration
+ */
+export function resolveSharingConfig(config: Partial<SharingConfig>): ResolvedSharingConfig {
+  return {
+    enabled: config.enabled ?? false,
+    publicLink: config.publicLink,
+    password: config.password,
+    allowedDomains: config.allowedDomains ?? [],
+    expiresAt: config.expiresAt,
+    allowAnonymous: config.allowAnonymous ?? false,
+  };
+}
+
+// ============================================================================
+// Embed Config Resolution
+// ============================================================================
+
+/**
+ * Resolve an embed configuration by applying spec defaults.
+ *
+ * @param config - Partial EmbedConfig from the spec
+ * @returns Fully resolved embed configuration
+ */
+export function resolveEmbedConfig(config: Partial<EmbedConfig>): ResolvedEmbedConfig {
+  return {
+    enabled: config.enabled ?? false,
+    allowedOrigins: config.allowedOrigins ?? [],
+    width: config.width ?? '100%',
+    height: config.height ?? '600px',
+    showHeader: config.showHeader ?? true,
+    showNavigation: config.showNavigation ?? false,
+    responsive: config.responsive ?? true,
+  };
+}
+
+// ============================================================================
+// Embed Code Generation
+// ============================================================================
+
+/**
+ * Generate an HTML iframe embed snippet from an EmbedConfig and URL.
+ *
+ * @param config - EmbedConfig from the spec
+ * @param url - The URL to embed
+ * @returns HTML string containing an iframe element
+ */
+export function generateEmbedCode(config: EmbedConfig, url: string): string {
+  const resolved = resolveEmbedConfig(config);
+  const sanitizedUrl = escapeHtmlAttr(url);
+  const title = 'Embedded content';
+
+  const parts = [
+    `<iframe`,
+    `  src="${sanitizedUrl}"`,
+    `  width="${escapeHtmlAttr(resolved.width)}"`,
+    `  height="${escapeHtmlAttr(resolved.height)}"`,
+    `  title="${title}"`,
+    `  frameborder="0"`,
+    `  allowfullscreen`,
+  ];
+
+  if (resolved.responsive) {
+    parts.push(`  style="max-width: 100%; border: none;"`);
+  } else {
+    parts.push(`  style="border: none;"`);
+  }
+
+  parts.push(`></iframe>`);
+
+  return parts.join('\n');
+}
+
+/**
+ * Escape a string for safe use in an HTML attribute value.
+ */
+function escapeHtmlAttr(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// ============================================================================
+// Sharing Config Validation
+// ============================================================================
+
+/**
+ * Validate a sharing configuration and return any errors.
+ *
+ * @param config - SharingConfig to validate
+ * @returns Validation result with `valid` flag and error messages
+ */
+export function validateSharingConfig(config: SharingConfig): SharingValidationResult {
+  const errors: string[] = [];
+
+  if (config.enabled && !config.publicLink) {
+    errors.push('A public link is required when sharing is enabled.');
+  }
+
+  if (config.expiresAt) {
+    const expiryDate = new Date(config.expiresAt);
+    if (isNaN(expiryDate.getTime())) {
+      errors.push('expiresAt must be a valid ISO 8601 date string.');
+    }
+  }
+
+  if (config.allowedDomains) {
+    for (const domain of config.allowedDomains) {
+      if (!domain || domain.trim().length === 0) {
+        errors.push('allowedDomains contains an empty or whitespace-only entry.');
+        break;
+      }
+    }
+  }
+
+  if (config.password !== undefined && config.password.length === 0) {
+    errors.push('Password must not be an empty string when provided.');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/protocols/index.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 * from './DndProtocol.js';
+export * from './KeyboardProtocol.js';
+export * from './NotificationProtocol.js';
+export * from './ResponsiveProtocol.js';
+export * from './SharingProtocol.js';

package/src/utils/__tests__/debug-collector.test.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { DebugCollector } from '../debug-collector';
+
+describe('DebugCollector', () => {
+  beforeEach(() => {
+    DebugCollector.resetInstance();
+  });
+
+  it('should return a singleton instance', () => {
+    const a = DebugCollector.getInstance();
+    const b = DebugCollector.getInstance();
+    expect(a).toBe(b);
+  });
+
+  it('should collect perf entries', () => {
+    const collector = DebugCollector.getInstance();
+    collector.addPerf({ type: 'button', id: 'btn1', durationMs: 5.2, timestamp: Date.now() });
+    const entries = collector.getEntries('perf');
+    expect(entries).toHaveLength(1);
+    expect(entries[0].kind).toBe('perf');
+    expect((entries[0].data as any).type).toBe('button');
+  });
+
+  it('should collect expr entries', () => {
+    const collector = DebugCollector.getInstance();
+    collector.addExpr({ expression: '${data.x > 1}', result: true, timestamp: Date.now() });
+    const entries = collector.getEntries('expr');
+    expect(entries).toHaveLength(1);
+    expect(entries[0].kind).toBe('expr');
+    expect((entries[0].data as any).result).toBe(true);
+  });
+
+  it('should collect event entries', () => {
+    const collector = DebugCollector.getInstance();
+    collector.addEvent({ action: 'navigate', payload: { to: '/home' }, timestamp: Date.now() });
+    const entries = collector.getEntries('event');
+    expect(entries).toHaveLength(1);
+    expect(entries[0].kind).toBe('event');
+    expect((entries[0].data as any).action).toBe('navigate');
+  });
+
+  it('should return all entries when no kind filter', () => {
+    const collector = DebugCollector.getInstance();
+    collector.addPerf({ type: 'text', durationMs: 1, timestamp: Date.now() });
+    collector.addExpr({ expression: 'a', result: 1, timestamp: Date.now() });
+    collector.addEvent({ action: 'click', timestamp: Date.now() });
+    expect(collector.getEntries()).toHaveLength(3);
+  });
+
+  it('should notify subscribers on new entry', () => {
+    const collector = DebugCollector.getInstance();
+    const fn = vi.fn();
+    collector.subscribe(fn);
+    collector.addPerf({ type: 'card', durationMs: 2, timestamp: Date.now() });
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenCalledWith(expect.objectContaining({ kind: 'perf' }));
+  });
+
+  it('should allow unsubscribe', () => {
+    const collector = DebugCollector.getInstance();
+    const fn = vi.fn();
+    const unsub = collector.subscribe(fn);
+    unsub();
+    collector.addPerf({ type: 'x', durationMs: 0, timestamp: Date.now() });
+    expect(fn).not.toHaveBeenCalled();
+  });
+
+  it('should clear entries', () => {
+    const collector = DebugCollector.getInstance();
+    collector.addPerf({ type: 'x', durationMs: 0, timestamp: Date.now() });
+    collector.addExpr({ expression: 'a', result: 1, timestamp: Date.now() });
+    collector.clear();
+    expect(collector.getEntries()).toHaveLength(0);
+  });
+
+  it('should cap entries at MAX_ENTRIES', () => {
+    const collector = DebugCollector.getInstance();
+    for (let i = 0; i < 250; i++) {
+      collector.addPerf({ type: `c${i}`, durationMs: i, timestamp: Date.now() });
+    }
+    // MAX_ENTRIES is 200
+    expect(collector.getEntries().length).toBeLessThanOrEqual(200);
+  });
+
+  it('should swallow subscriber errors gracefully', () => {
+    const collector = DebugCollector.getInstance();
+    const badFn = vi.fn(() => { throw new Error('boom'); });
+    const goodFn = vi.fn();
+    collector.subscribe(badFn);
+    collector.subscribe(goodFn);
+    collector.addPerf({ type: 'x', durationMs: 0, timestamp: Date.now() });
+    expect(goodFn).toHaveBeenCalledTimes(1);
+  });
+});

package/src/utils/__tests__/debug.test.ts

@@ -7,7 +7,7 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { debugLog, debugTime, debugTimeEnd } from '../debug';
+import { debugLog, debugTime, debugTimeEnd, parseDebugFlags, isDebugEnabled } from '../debug';
 
 describe('Debug Utilities', () => {
   let consoleSpy: ReturnType<typeof vi.spyOn>;
@@ -80,4 +80,55 @@ describe('Debug Utilities', () => {
       expect(consoleSpy).not.toHaveBeenCalled();
     });
   });
+
+  describe('parseDebugFlags', () => {
+    it('should return enabled:false for empty search string', () => {
+      expect(parseDebugFlags('')).toEqual({ enabled: false });
+    });
+
+    it('should detect __debug master switch', () => {
+      expect(parseDebugFlags('?__debug')).toEqual({ enabled: true });
+    });
+
+    it('should detect individual sub-flags', () => {
+      expect(parseDebugFlags('?__debug_schema')).toEqual({ enabled: true, schema: true });
+      expect(parseDebugFlags('?__debug_perf')).toEqual({ enabled: true, perf: true });
+      expect(parseDebugFlags('?__debug_data')).toEqual({ enabled: true, data: true });
+      expect(parseDebugFlags('?__debug_expr')).toEqual({ enabled: true, expr: true });
+      expect(parseDebugFlags('?__debug_events')).toEqual({ enabled: true, events: true });
+      expect(parseDebugFlags('?__debug_registry')).toEqual({ enabled: true, registry: true });
+    });
+
+    it('should combine multiple sub-flags', () => {
+      const flags = parseDebugFlags('?__debug_schema&__debug_perf&__debug_data');
+      expect(flags).toEqual({ enabled: true, schema: true, perf: true, data: true });
+    });
+
+    it('should handle unrelated params gracefully', () => {
+      const flags = parseDebugFlags('?foo=bar&baz=1');
+      expect(flags).toEqual({ enabled: false });
+    });
+
+    it('should handle __debug mixed with sub-flags', () => {
+      const flags = parseDebugFlags('?__debug&__debug_schema');
+      expect(flags).toEqual({ enabled: true, schema: true });
+    });
+  });
+
+  describe('isDebugEnabled', () => {
+    it('should return true when globalThis.OBJECTUI_DEBUG is true', () => {
+      (globalThis as any).OBJECTUI_DEBUG = true;
+      expect(isDebugEnabled()).toBe(true);
+    });
+
+    it('should return true when globalThis.OBJECTUI_DEBUG is "true"', () => {
+      (globalThis as any).OBJECTUI_DEBUG = 'true';
+      expect(isDebugEnabled()).toBe(true);
+    });
+
+    it('should return false when no debug flag is set', () => {
+      (globalThis as any).OBJECTUI_DEBUG = undefined;
+      expect(isDebugEnabled()).toBe(false);
+    });
+  });
 });

package/src/utils/__tests__/expand-fields.test.ts

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { buildExpandFields } from '../expand-fields';
+
+describe('buildExpandFields', () => {
+  const sampleFields = {
+    name: { type: 'text', label: 'Name' },
+    email: { type: 'email', label: 'Email' },
+    account: { type: 'lookup', label: 'Account', reference_to: 'accounts' },
+    parent: { type: 'master_detail', label: 'Parent', reference_to: 'contacts' },
+    status: { type: 'select', label: 'Status' },
+  };
+
+  it('should return lookup and master_detail field names', () => {
+    const result = buildExpandFields(sampleFields);
+    expect(result).toEqual(['account', 'parent']);
+  });
+
+  it('should return empty array when no lookup/master_detail fields exist', () => {
+    const fields = {
+      name: { type: 'text' },
+      age: { type: 'number' },
+    };
+    expect(buildExpandFields(fields)).toEqual([]);
+  });
+
+  it('should return empty array for null/undefined schema', () => {
+    expect(buildExpandFields(null)).toEqual([]);
+    expect(buildExpandFields(undefined)).toEqual([]);
+  });
+
+  it('should return empty array for empty fields object', () => {
+    expect(buildExpandFields({})).toEqual([]);
+  });
+
+  it('should filter by string columns when provided', () => {
+    const result = buildExpandFields(sampleFields, ['name', 'account']);
+    expect(result).toEqual(['account']);
+  });
+
+  it('should filter by ListColumn objects with field property', () => {
+    const columns = [
+      { field: 'name', label: 'Name' },
+      { field: 'parent', label: 'Parent Contact' },
+    ];
+    const result = buildExpandFields(sampleFields, columns);
+    expect(result).toEqual(['parent']);
+  });
+
+  it('should support columns with name property', () => {
+    const columns = [
+      { name: 'account', label: 'Account' },
+    ];
+    const result = buildExpandFields(sampleFields, columns);
+    expect(result).toEqual(['account']);
+  });
+
+  it('should support columns with fieldName property', () => {
+    const columns = [
+      { fieldName: 'parent', label: 'Parent' },
+    ];
+    const result = buildExpandFields(sampleFields, columns);
+    expect(result).toEqual(['parent']);
+  });
+
+  it('should return empty array when columns have no lookup fields', () => {
+    const result = buildExpandFields(sampleFields, ['name', 'email']);
+    expect(result).toEqual([]);
+  });
+
+  it('should handle mixed string and object columns', () => {
+    const columns = [
+      'name',
+      { field: 'account' },
+      'parent',
+    ];
+    const result = buildExpandFields(sampleFields, columns);
+    expect(result).toEqual(['account', 'parent']);
+  });
+
+  it('should return all lookup fields when columns is empty array', () => {
+    // Empty columns array does not satisfy the length > 0 check,
+    // so no column restriction is applied → all lookup fields returned
+    const result = buildExpandFields(sampleFields, []);
+    expect(result).toEqual(['account', 'parent']);
+  });
+
+  it('should handle malformed field definitions gracefully', () => {
+    const fields = {
+      name: null,
+      account: { type: 'lookup' },
+      broken: 'not-an-object',
+      empty: {},
+    };
+    const result = buildExpandFields(fields as any);
+    expect(result).toEqual(['account']);
+  });
+
+  it('should handle only lookup fields', () => {
+    const fields = {
+      ref1: { type: 'lookup', reference_to: 'obj1' },
+      ref2: { type: 'lookup', reference_to: 'obj2' },
+    };
+    expect(buildExpandFields(fields)).toEqual(['ref1', 'ref2']);
+  });
+
+  it('should handle only master_detail fields', () => {
+    const fields = {
+      detail1: { type: 'master_detail', reference_to: 'obj1' },
+    };
+    expect(buildExpandFields(fields)).toEqual(['detail1']);
+  });
+});