@object-ui/core 3.0.3 → 3.1.0

package/dist/protocols/ResponsiveProtocol.js

@@ -0,0 +1,158 @@
+/**
+ * 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.
+ */
+/** Breakpoint minimum pixel widths aligned with Tailwind CSS defaults. */
+export const BREAKPOINT_VALUES = {
+    xs: 0,
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    '2xl': 1536,
+};
+/** Ordered breakpoint keys from smallest to largest. */
+const BREAKPOINT_ORDER = ['xs', 'sm', 'md', 'lg', 'xl', '2xl'];
+// ============================================================================
+// Config Resolution
+// ============================================================================
+/**
+ * Resolve a responsive configuration by applying defaults.
+ *
+ * @param config - SpecResponsiveConfig from the spec
+ * @returns Fully resolved responsive configuration
+ */
+export function resolveResponsiveConfig(config) {
+    return {
+        breakpoint: config.breakpoint,
+        hiddenOn: (config.hiddenOn ?? []),
+        columns: (config.columns ?? {}),
+        order: (config.order ?? {}),
+    };
+}
+// ============================================================================
+// 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) {
+    const classes = [];
+    // Minimum breakpoint visibility
+    if (config.breakpoint) {
+        const bp = config.breakpoint;
+        if (bp !== 'xs') {
+            classes.push('hidden');
+            classes.push(`${bp}:block`);
+        }
+    }
+    // Per-breakpoint hidden overrides
+    const hiddenOn = (config.hiddenOn ?? []);
+    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) {
+    const classes = [];
+    const columns = (config.columns ?? {});
+    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) {
+    const classes = [];
+    const order = (config.order ?? {});
+    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, width) {
+    // Check minimum breakpoint
+    if (config.breakpoint) {
+        const minWidth = BREAKPOINT_VALUES[config.breakpoint];
+        if (minWidth !== undefined && width < minWidth) {
+            return true;
+        }
+    }
+    // Check hiddenOn list
+    const hiddenOn = (config.hiddenOn ?? []);
+    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) {
+    for (let i = BREAKPOINT_ORDER.length - 1; i >= 0; i--) {
+        if (width >= BREAKPOINT_VALUES[BREAKPOINT_ORDER[i]]) {
+            return BREAKPOINT_ORDER[i];
+        }
+    }
+    return 'xs';
+}

package/dist/protocols/SharingProtocol.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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';
+/** 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[];
+}
+/**
+ * Resolve a sharing configuration by applying spec defaults.
+ *
+ * @param config - Partial SharingConfig from the spec
+ * @returns Fully resolved sharing configuration
+ */
+export declare function resolveSharingConfig(config: Partial<SharingConfig>): ResolvedSharingConfig;
+/**
+ * Resolve an embed configuration by applying spec defaults.
+ *
+ * @param config - Partial EmbedConfig from the spec
+ * @returns Fully resolved embed configuration
+ */
+export declare function resolveEmbedConfig(config: Partial<EmbedConfig>): ResolvedEmbedConfig;
+/**
+ * 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 declare function generateEmbedCode(config: EmbedConfig, url: string): string;
+/**
+ * Validate a sharing configuration and return any errors.
+ *
+ * @param config - SharingConfig to validate
+ * @returns Validation result with `valid` flag and error messages
+ */
+export declare function validateSharingConfig(config: SharingConfig): SharingValidationResult;

package/dist/protocols/SharingProtocol.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+// ============================================================================
+// 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) {
+    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) {
+    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, url) {
+    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) {
+    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) {
+    const errors = [];
+    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/dist/protocols/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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/dist/protocols/index.js

@@ -0,0 +1,12 @@
+/**
+ * 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/dist/utils/debug-collector.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+/**
+ * DebugCollector — lightweight, tree-shakeable event collector
+ * for perf / expression / action debug data.
+ *
+ * Usage in production is a no-op when the singleton is never imported.
+ * Consumers call `DebugCollector.getInstance()` and subscribe via
+ * `.subscribe()`.
+ */
+export interface PerfEntry {
+    type: string;
+    id?: string;
+    durationMs: number;
+    timestamp: number;
+}
+export interface ExprEntry {
+    expression: string;
+    result: unknown;
+    context?: Record<string, unknown>;
+    timestamp: number;
+}
+export interface EventEntry {
+    action: string;
+    payload?: unknown;
+    timestamp: number;
+}
+export type DebugEntry = {
+    kind: 'perf';
+    data: PerfEntry;
+} | {
+    kind: 'expr';
+    data: ExprEntry;
+} | {
+    kind: 'event';
+    data: EventEntry;
+};
+type DebugSubscriber = (entry: DebugEntry) => void;
+export declare class DebugCollector {
+    private static instance;
+    private entries;
+    private subscribers;
+    static getInstance(): DebugCollector;
+    /** Reset singleton — only used for testing */
+    static resetInstance(): void;
+    addPerf(entry: PerfEntry): void;
+    addExpr(entry: ExprEntry): void;
+    addEvent(entry: EventEntry): void;
+    getEntries(kind?: DebugEntry['kind']): DebugEntry[];
+    clear(): void;
+    subscribe(fn: DebugSubscriber): () => void;
+    private push;
+}
+export {};

package/dist/utils/debug-collector.js

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+const MAX_ENTRIES = 200;
+export class DebugCollector {
+    constructor() {
+        Object.defineProperty(this, "entries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "subscribers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+    }
+    static getInstance() {
+        if (!DebugCollector.instance) {
+            DebugCollector.instance = new DebugCollector();
+        }
+        return DebugCollector.instance;
+    }
+    /** Reset singleton — only used for testing */
+    static resetInstance() {
+        DebugCollector.instance = null;
+    }
+    addPerf(entry) {
+        this.push({ kind: 'perf', data: entry });
+    }
+    addExpr(entry) {
+        this.push({ kind: 'expr', data: entry });
+    }
+    addEvent(entry) {
+        this.push({ kind: 'event', data: entry });
+    }
+    getEntries(kind) {
+        if (!kind)
+            return this.entries.slice();
+        return this.entries.filter((e) => e.kind === kind);
+    }
+    clear() {
+        this.entries = [];
+    }
+    subscribe(fn) {
+        this.subscribers.add(fn);
+        return () => this.subscribers.delete(fn);
+    }
+    push(entry) {
+        this.entries.push(entry);
+        if (this.entries.length > MAX_ENTRIES) {
+            this.entries = this.entries.slice(-MAX_ENTRIES);
+        }
+        for (const fn of this.subscribers) {
+            try {
+                fn(entry);
+            }
+            catch { /* subscriber errors must not break debug flow */ }
+        }
+    }
+}
+Object.defineProperty(DebugCollector, "instance", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: null
+});

package/dist/utils/debug.d.ts

@@ -5,7 +5,43 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render';
+export type DebugCategory = 'schema' | 'registry' | 'expression' | 'action' | 'plugin' | 'render' | 'dashboard';
+/**
+ * Fine-grained debug flags parsed from URL parameters.
+ *
+ * @example
+ * ```
+ * ?__debug              → { enabled: true }
+ * ?__debug_schema       → { enabled: true, schema: true }
+ * ?__debug_perf&__debug_data → { enabled: true, perf: true, data: true }
+ * ```
+ */
+export interface DebugFlags {
+    /** Master switch — true when any debug parameter is present */
+    enabled: boolean;
+    schema?: boolean;
+    perf?: boolean;
+    data?: boolean;
+    expr?: boolean;
+    events?: boolean;
+    registry?: boolean;
+}
+/**
+ * Parse debug flags from a URL search string (e.g. `?__debug&__debug_schema`).
+ * SSR-safe — returns `{ enabled: false }` when `window` is unavailable.
+ *
+ * @param search — Optional search string. Defaults to `window.location.search` when available.
+ */
+export declare function parseDebugFlags(search?: string): DebugFlags;
+/**
+ * Check whether debug mode is enabled.
+ *
+ * Resolution order (first truthy wins):
+ * 1. URL parameter `?__debug` (browser only)
+ * 2. `globalThis.OBJECTUI_DEBUG`
+ * 3. `process.env.OBJECTUI_DEBUG`
+ */
+export declare function isDebugEnabled(): boolean;
 /**
  * Log a debug message when OBJECTUI_DEBUG is enabled.
  * No-op in production or when debug mode is off.
@@ -28,4 +64,3 @@ export declare function debugTime(label: string): void;
  * End a debug timer and log the elapsed time.
  */
 export declare function debugTimeEnd(label: string): void;
-export {};

package/dist/utils/debug.js

@@ -5,11 +5,70 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-function isDebugEnabled() {
+const DEBUG_PARAM_PREFIX = '__debug';
+/**
+ * Parse debug flags from a URL search string (e.g. `?__debug&__debug_schema`).
+ * SSR-safe — returns `{ enabled: false }` when `window` is unavailable.
+ *
+ * @param search — Optional search string. Defaults to `window.location.search` when available.
+ */
+export function parseDebugFlags(search) {
+    let qs = search;
+    if (qs === undefined) {
+        try {
+            qs = typeof window !== 'undefined' ? window.location.search : '';
+        }
+        catch {
+            qs = '';
+        }
+    }
+    const params = new URLSearchParams(qs);
+    const hasMain = params.has(DEBUG_PARAM_PREFIX);
+    const schema = params.has(`${DEBUG_PARAM_PREFIX}_schema`);
+    const perf = params.has(`${DEBUG_PARAM_PREFIX}_perf`);
+    const data = params.has(`${DEBUG_PARAM_PREFIX}_data`);
+    const expr = params.has(`${DEBUG_PARAM_PREFIX}_expr`);
+    const events = params.has(`${DEBUG_PARAM_PREFIX}_events`);
+    const registry = params.has(`${DEBUG_PARAM_PREFIX}_registry`);
+    const anySub = schema || perf || data || expr || events || registry;
+    const enabled = hasMain || anySub;
+    return {
+        enabled,
+        ...(schema && { schema }),
+        ...(perf && { perf }),
+        ...(data && { data }),
+        ...(expr && { expr }),
+        ...(events && { events }),
+        ...(registry && { registry }),
+    };
+}
+/**
+ * Check whether debug mode is enabled.
+ *
+ * Resolution order (first truthy wins):
+ * 1. URL parameter `?__debug` (browser only)
+ * 2. `globalThis.OBJECTUI_DEBUG`
+ * 3. `process.env.OBJECTUI_DEBUG`
+ */
+export function isDebugEnabled() {
     try {
+        // 1. URL parameter (browser only, SSR-safe)
+        if (typeof window !== 'undefined') {
+            try {
+                const flags = parseDebugFlags(window.location.search);
+                if (flags.enabled)
+                    return true;
+            }
+            catch { /* ignore */ }
+        }
+        // 2. globalThis flag
         const g = typeof globalThis !== 'undefined' && globalThis.OBJECTUI_DEBUG;
-        return ((g === true || g === 'true') ||
-            (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true'));
+        if (g === true || g === 'true')
+            return true;
+        // 3. process.env
+        if (typeof process !== 'undefined' && process.env?.OBJECTUI_DEBUG === 'true')
+            return true;
+        return false;
     }
     catch {
         return false;

package/dist/utils/expand-fields.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function buildExpandFields(schemaFields?: Record<string, any> | null, columns?: (string | {
+    field?: string;
+    name?: string;
+    fieldName?: string;
+})[]): string[];