@object-ui/react 2.0.0 → 3.0.1

package/dist/hooks/usePerformanceBudget.js

@@ -0,0 +1,209 @@
+/**
+ * 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 { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+const DEFAULTS = {
+    maxLCP: 600,
+    maxFCP: 300,
+    maxRenderTime: 16,
+    maxMemoryMB: 128,
+    warnOnViolation: true,
+};
+// ---------------------------------------------------------------------------
+// Helpers (same getFCP/getLCP pattern as usePerformance.ts)
+// ---------------------------------------------------------------------------
+function getFCP() {
+    if (typeof performance === 'undefined' || !performance.getEntriesByType)
+        return null;
+    try {
+        const entries = performance.getEntriesByType('paint');
+        const entry = entries.find((e) => e.name === 'first-contentful-paint');
+        return entry ? Math.round(entry.startTime) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function getLCP() {
+    if (typeof performance === 'undefined' || !performance.getEntriesByType)
+        return null;
+    try {
+        const entries = performance.getEntriesByType('largest-contentful-paint');
+        const entry = entries.length > 0 ? entries[entries.length - 1] : undefined;
+        return entry ? Math.round(entry.startTime) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Chrome-only memory API (guarded). */
+function getMemoryMB() {
+    try {
+        const mem = performance.memory;
+        if (mem?.usedJSHeapSize != null) {
+            return Math.round((mem.usedJSHeapSize / (1024 * 1024)) * 100) / 100;
+        }
+    }
+    catch {
+        /* not available */
+    }
+    return null;
+}
+function buildViolationKey(metric) {
+    return metric;
+}
+// ---------------------------------------------------------------------------
+// usePerformanceBudget hook
+// ---------------------------------------------------------------------------
+/**
+ * Hook for performance budget enforcement aligned with ROADMAP Q3 3.3.
+ *
+ * Monitors Web Vitals (LCP, FCP), memory usage, and component render times
+ * against configurable thresholds. Violations are recorded, deduplicated,
+ * and optionally logged to the console in development mode.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const budget = usePerformanceBudget({
+ *     maxLCP: 500,
+ *     maxRenderTime: 16,
+ *     onViolation: (v) => analytics.track('perf_violation', v),
+ *   });
+ *
+ *   if (!budget.isWithinBudget) {
+ *     console.warn('Performance budget exceeded:', budget.violations);
+ *   }
+ *
+ *   return <Dashboard />;
+ * }
+ * ```
+ */
+export function usePerformanceBudget(userBudget = {}) {
+    const budget = useMemo(() => ({
+        maxLCP: userBudget.maxLCP ?? DEFAULTS.maxLCP,
+        maxFCP: userBudget.maxFCP ?? DEFAULTS.maxFCP,
+        maxRenderTime: userBudget.maxRenderTime ?? DEFAULTS.maxRenderTime,
+        maxMemoryMB: userBudget.maxMemoryMB ?? DEFAULTS.maxMemoryMB,
+        warnOnViolation: userBudget.warnOnViolation ?? DEFAULTS.warnOnViolation,
+    }), [
+        userBudget.maxLCP,
+        userBudget.maxFCP,
+        userBudget.maxRenderTime,
+        userBudget.maxMemoryMB,
+        userBudget.warnOnViolation,
+    ]);
+    const onViolationRef = useRef(userBudget.onViolation);
+    useEffect(() => {
+        onViolationRef.current = userBudget.onViolation;
+    }, [userBudget.onViolation]);
+    const [violations, setViolations] = useState([]);
+    const seenRef = useRef(new Set());
+    const [snapshot, setSnapshot] = useState({ lcp: null, fcp: null, memoryMB: null });
+    // -------------------------------------------------------------------
+    // Violation recording with deduplication
+    // -------------------------------------------------------------------
+    const recordViolation = useCallback((metric, budgetValue, actual) => {
+        const key = buildViolationKey(metric);
+        if (seenRef.current.has(key))
+            return;
+        seenRef.current.add(key);
+        const violation = {
+            metric,
+            budget: budgetValue,
+            actual: Math.round(actual * 100) / 100,
+            timestamp: Date.now(),
+        };
+        setViolations((prev) => [...prev, violation]);
+        if (budget.warnOnViolation && process.env.NODE_ENV !== 'production') {
+            console.warn(`[ObjectUI] Performance budget violated: ${metric} = ${violation.actual} (budget: ${budgetValue})`);
+        }
+        onViolationRef.current?.(violation);
+    }, [budget.warnOnViolation]);
+    // -------------------------------------------------------------------
+    // Collect Web Vitals & memory on mount
+    // -------------------------------------------------------------------
+    useEffect(() => {
+        const timer = setTimeout(() => {
+            const fcp = getFCP();
+            const lcp = getLCP();
+            const memoryMB = getMemoryMB();
+            setSnapshot({ lcp, fcp, memoryMB });
+            if (fcp != null && fcp > budget.maxFCP) {
+                recordViolation('fcp', budget.maxFCP, fcp);
+            }
+            if (lcp != null && lcp > budget.maxLCP) {
+                recordViolation('lcp', budget.maxLCP, lcp);
+            }
+            if (memoryMB != null && memoryMB > budget.maxMemoryMB) {
+                recordViolation('memory', budget.maxMemoryMB, memoryMB);
+            }
+        }, 0);
+        return () => clearTimeout(timer);
+    }, [budget.maxFCP, budget.maxLCP, budget.maxMemoryMB, recordViolation]);
+    // -------------------------------------------------------------------
+    // Periodic memory monitoring
+    // -------------------------------------------------------------------
+    useEffect(() => {
+        // Only run when memory API is available
+        if (getMemoryMB() == null)
+            return;
+        const interval = setInterval(() => {
+            const memoryMB = getMemoryMB();
+            if (memoryMB != null) {
+                setSnapshot((prev) => ({ ...prev, memoryMB }));
+                if (memoryMB > budget.maxMemoryMB) {
+                    recordViolation('memory', budget.maxMemoryMB, memoryMB);
+                }
+            }
+        }, 10000);
+        return () => clearInterval(interval);
+    }, [budget.maxMemoryMB, recordViolation]);
+    // -------------------------------------------------------------------
+    // Public API
+    // -------------------------------------------------------------------
+    const checkMetric = useCallback((metric, value) => {
+        let threshold;
+        switch (metric) {
+            case 'lcp':
+                threshold = budget.maxLCP;
+                break;
+            case 'fcp':
+                threshold = budget.maxFCP;
+                break;
+            case 'renderTime':
+                threshold = budget.maxRenderTime;
+                break;
+            case 'memory':
+                threshold = budget.maxMemoryMB;
+                break;
+        }
+        const withinBudget = value <= threshold;
+        if (!withinBudget) {
+            recordViolation(metric, threshold, value);
+        }
+        return withinBudget;
+    }, [budget.maxLCP, budget.maxFCP, budget.maxRenderTime, budget.maxMemoryMB, recordViolation]);
+    const trackRender = useCallback((durationMs) => {
+        return checkMetric('renderTime', durationMs);
+    }, [checkMetric]);
+    const clearViolations = useCallback(() => {
+        setViolations([]);
+        seenRef.current.clear();
+    }, []);
+    return useMemo(() => ({
+        violations,
+        isWithinBudget: violations.length === 0,
+        checkMetric,
+        trackRender,
+        clearViolations,
+        snapshot,
+    }), [violations, checkMetric, trackRender, clearViolations, snapshot]);
+}

package/dist/hooks/useReducedMotion.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+/**
+ * Hook that detects the user's motion preference.
+ * Implements MotionConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * Respects the `prefers-reduced-motion` media query to provide
+ * accessible animation experiences.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedCard() {
+ *   const prefersReducedMotion = useReducedMotion();
+ *
+ *   return (
+ *     <div className={prefersReducedMotion ? '' : 'animate-fade-in'}>
+ *       Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useReducedMotion(): boolean;

package/dist/hooks/useReducedMotion.js

@@ -0,0 +1,48 @@
+/**
+ * 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 { useState, useEffect } from 'react';
+/**
+ * Hook that detects the user's motion preference.
+ * Implements MotionConfigSchema from @objectstack/spec v2.0.7.
+ *
+ * Respects the `prefers-reduced-motion` media query to provide
+ * accessible animation experiences.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedCard() {
+ *   const prefersReducedMotion = useReducedMotion();
+ *
+ *   return (
+ *     <div className={prefersReducedMotion ? '' : 'animate-fade-in'}>
+ *       Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useReducedMotion() {
+    const [prefersReducedMotion, setPrefersReducedMotion] = useState(() => {
+        if (typeof window === 'undefined')
+            return false;
+        return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    });
+    useEffect(() => {
+        if (typeof window === 'undefined')
+            return;
+        const mediaQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+        const handleChange = (event) => {
+            setPrefersReducedMotion(event.matches);
+        };
+        mediaQuery.addEventListener('change', handleChange);
+        return () => {
+            mediaQuery.removeEventListener('change', handleChange);
+        };
+    }, []);
+    return prefersReducedMotion;
+}

package/dist/hooks/useSchemaPersistence.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+/**
+ * Persistence adapter interface for schema save/load operations.
+ * Implement this to connect to any backend (REST API, GraphQL, localStorage, etc.).
+ */
+export interface SchemaPersistenceAdapter {
+    /** Save a schema to the backend. Returns the saved schema ID. */
+    save: (id: string, schema: Record<string, unknown>) => Promise<string>;
+    /** Load a schema from the backend by ID. */
+    load: (id: string) => Promise<Record<string, unknown> | null>;
+    /** List all available schemas. */
+    list?: () => Promise<Array<{
+        id: string;
+        name?: string;
+        updatedAt?: string;
+    }>>;
+    /** Delete a schema from the backend. */
+    delete?: (id: string) => Promise<void>;
+}
+export interface SchemaPersistenceState {
+    /** Whether a save/load operation is in progress */
+    loading: boolean;
+    /** The last error from a save/load operation */
+    error: Error | null;
+    /** Whether the current schema has unsaved changes */
+    isDirty: boolean;
+    /** The last saved timestamp */
+    lastSavedAt: Date | null;
+}
+export interface SchemaPersistenceResult extends SchemaPersistenceState {
+    /** Save the current schema */
+    save: (id: string, schema: Record<string, unknown>) => Promise<string | null>;
+    /** Load a schema by ID */
+    load: (id: string) => Promise<Record<string, unknown> | null>;
+    /** List available schemas */
+    list: () => Promise<Array<{
+        id: string;
+        name?: string;
+        updatedAt?: string;
+    }>>;
+    /** Delete a schema */
+    remove: (id: string) => Promise<boolean>;
+    /** Mark the current schema as dirty (has unsaved changes) */
+    markDirty: () => void;
+    /** Clear the error state */
+    clearError: () => void;
+}
+/**
+ * Default localStorage adapter for schema persistence.
+ * Useful for development and demos.
+ */
+export declare function createLocalStorageAdapter(prefix?: string): SchemaPersistenceAdapter;
+/**
+ * Hook for persisting designer schemas (save/load/list/delete).
+ * Implements schema persistence for @object-ui/plugin-designer.
+ *
+ * Accepts a pluggable adapter for connecting to any backend.
+ * Falls back to a localStorage adapter for development use.
+ *
+ * @example
+ * ```tsx
+ * // With default localStorage adapter
+ * const persistence = useSchemaPersistence();
+ *
+ * // Save current design
+ * await persistence.save('my-page', pageSchema);
+ *
+ * // Load a design
+ * const schema = await persistence.load('my-page');
+ *
+ * // With custom API adapter
+ * const apiAdapter: SchemaPersistenceAdapter = {
+ *   save: (id, schema) => fetch(`/api/schemas/${id}`, { method: 'PUT', body: JSON.stringify(schema) }).then(r => r.json()),
+ *   load: (id) => fetch(`/api/schemas/${id}`).then(r => r.json()),
+ *   list: () => fetch('/api/schemas').then(r => r.json()),
+ *   delete: (id) => fetch(`/api/schemas/${id}`, { method: 'DELETE' }).then(() => {}),
+ * };
+ * const persistence = useSchemaPersistence(apiAdapter);
+ * ```
+ */
+export declare function useSchemaPersistence(adapter?: SchemaPersistenceAdapter): SchemaPersistenceResult;

package/dist/hooks/useSchemaPersistence.js

@@ -0,0 +1,173 @@
+/**
+ * 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 { useState, useCallback, useRef, useMemo } from 'react';
+/**
+ * Default localStorage adapter for schema persistence.
+ * Useful for development and demos.
+ */
+export function createLocalStorageAdapter(prefix = 'objectui-schema') {
+    return {
+        async save(id, schema) {
+            const key = `${prefix}:${id}`;
+            const entry = { schema, updatedAt: new Date().toISOString() };
+            localStorage.setItem(key, JSON.stringify(entry));
+            // Update the index
+            const indexKey = `${prefix}:__index__`;
+            const index = JSON.parse(localStorage.getItem(indexKey) || '[]');
+            if (!index.includes(id)) {
+                index.push(id);
+                localStorage.setItem(indexKey, JSON.stringify(index));
+            }
+            return id;
+        },
+        async load(id) {
+            const key = `${prefix}:${id}`;
+            const raw = localStorage.getItem(key);
+            if (!raw)
+                return null;
+            const entry = JSON.parse(raw);
+            return entry.schema ?? null;
+        },
+        async list() {
+            const indexKey = `${prefix}:__index__`;
+            const index = JSON.parse(localStorage.getItem(indexKey) || '[]');
+            return index.map((id) => {
+                const raw = localStorage.getItem(`${prefix}:${id}`);
+                const entry = raw ? JSON.parse(raw) : {};
+                return { id, name: id, updatedAt: entry.updatedAt };
+            });
+        },
+        async delete(id) {
+            const key = `${prefix}:${id}`;
+            localStorage.removeItem(key);
+            const indexKey = `${prefix}:__index__`;
+            const index = JSON.parse(localStorage.getItem(indexKey) || '[]');
+            localStorage.setItem(indexKey, JSON.stringify(index.filter((i) => i !== id)));
+        },
+    };
+}
+/**
+ * Hook for persisting designer schemas (save/load/list/delete).
+ * Implements schema persistence for @object-ui/plugin-designer.
+ *
+ * Accepts a pluggable adapter for connecting to any backend.
+ * Falls back to a localStorage adapter for development use.
+ *
+ * @example
+ * ```tsx
+ * // With default localStorage adapter
+ * const persistence = useSchemaPersistence();
+ *
+ * // Save current design
+ * await persistence.save('my-page', pageSchema);
+ *
+ * // Load a design
+ * const schema = await persistence.load('my-page');
+ *
+ * // With custom API adapter
+ * const apiAdapter: SchemaPersistenceAdapter = {
+ *   save: (id, schema) => fetch(`/api/schemas/${id}`, { method: 'PUT', body: JSON.stringify(schema) }).then(r => r.json()),
+ *   load: (id) => fetch(`/api/schemas/${id}`).then(r => r.json()),
+ *   list: () => fetch('/api/schemas').then(r => r.json()),
+ *   delete: (id) => fetch(`/api/schemas/${id}`, { method: 'DELETE' }).then(() => {}),
+ * };
+ * const persistence = useSchemaPersistence(apiAdapter);
+ * ```
+ */
+export function useSchemaPersistence(adapter) {
+    const defaultAdapter = useRef(createLocalStorageAdapter());
+    const adapterRef = useRef(adapter ?? defaultAdapter.current);
+    // Keep the ref up to date if the adapter prop changes
+    adapterRef.current = adapter ?? defaultAdapter.current;
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const [isDirty, setIsDirty] = useState(false);
+    const [lastSavedAt, setLastSavedAt] = useState(null);
+    const save = useCallback(async (id, schema) => {
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await adapterRef.current.save(id, schema);
+            setIsDirty(false);
+            setLastSavedAt(new Date());
+            return result;
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    const load = useCallback(async (id) => {
+        setLoading(true);
+        setError(null);
+        try {
+            const result = await adapterRef.current.load(id);
+            setIsDirty(false);
+            return result;
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            return null;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    const list = useCallback(async () => {
+        setLoading(true);
+        setError(null);
+        try {
+            if (adapterRef.current.list) {
+                return await adapterRef.current.list();
+            }
+            return [];
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            return [];
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    const remove = useCallback(async (id) => {
+        setLoading(true);
+        setError(null);
+        try {
+            if (adapterRef.current.delete) {
+                await adapterRef.current.delete(id);
+                return true;
+            }
+            return false;
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+            return false;
+        }
+        finally {
+            setLoading(false);
+        }
+    }, []);
+    const markDirty = useCallback(() => setIsDirty(true), []);
+    const clearError = useCallback(() => setError(null), []);
+    return useMemo(() => ({
+        loading,
+        error,
+        isDirty,
+        lastSavedAt,
+        save,
+        load,
+        list,
+        remove,
+        markDirty,
+        clearError,
+    }), [loading, error, isDirty, lastSavedAt, save, load, list, remove, markDirty, clearError]);
+}

package/dist/hooks/useViewSharing.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/** View sharing visibility aligned with ViewSharingSchema */
+export type ViewVisibility = 'private' | 'team' | 'organization' | 'public';
+/** A saved view configuration */
+export interface SavedView {
+    id: string;
+    name: string;
+    /** The view configuration (filters, sort, columns, etc.) */
+    config: Record<string, unknown>;
+    /** Who can see this view */
+    visibility: ViewVisibility;
+    /** Who created this view */
+    createdBy?: string;
+    /** Whether this is the default view */
+    isDefault?: boolean;
+    /** When the view was last modified */
+    updatedAt: Date;
+}
+export interface ViewSharingResult {
+    /** All available views */
+    views: SavedView[];
+    /** Currently active view */
+    activeView: SavedView | null;
+    /** Save a new view or update existing */
+    saveView: (view: Omit<SavedView, 'id' | 'updatedAt'>) => string;
+    /** Set the active view */
+    setActiveView: (viewId: string) => void;
+    /** Delete a view */
+    deleteView: (viewId: string) => void;
+    /** Duplicate a view */
+    duplicateView: (viewId: string, newName: string) => string;
+    /** Update view visibility */
+    setVisibility: (viewId: string, visibility: ViewVisibility) => void;
+}
+/**
+ * Hook for managing shared/personal view configurations.
+ * Implements ViewSharingSchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const viewSharing = useViewSharing(initialViews);
+ *
+ * // Save current filters/sort as a named view
+ * viewSharing.saveView({
+ *   name: 'My Open Tasks',
+ *   config: { filters: currentFilters, sort: currentSort },
+ *   visibility: 'private',
+ * });
+ * ```
+ */
+export declare function useViewSharing(initialViews?: SavedView[]): ViewSharingResult;

package/dist/hooks/useViewSharing.js

@@ -0,0 +1,74 @@
+/**
+ * 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 { useState, useCallback, useMemo } from 'react';
+let viewCounter = 0;
+/**
+ * Hook for managing shared/personal view configurations.
+ * Implements ViewSharingSchema from @objectstack/spec v2.0.7.
+ *
+ * @example
+ * ```tsx
+ * const viewSharing = useViewSharing(initialViews);
+ *
+ * // Save current filters/sort as a named view
+ * viewSharing.saveView({
+ *   name: 'My Open Tasks',
+ *   config: { filters: currentFilters, sort: currentSort },
+ *   visibility: 'private',
+ * });
+ * ```
+ */
+export function useViewSharing(initialViews = []) {
+    const [views, setViews] = useState(initialViews);
+    const [activeViewId, setActiveViewId] = useState(initialViews.find((v) => v.isDefault)?.id ?? initialViews[0]?.id ?? null);
+    const activeView = useMemo(() => views.find((v) => v.id === activeViewId) ?? null, [views, activeViewId]);
+    const saveView = useCallback((input) => {
+        const id = `view-${++viewCounter}`;
+        const view = {
+            ...input,
+            id,
+            updatedAt: new Date(),
+        };
+        setViews((prev) => [...prev, view]);
+        return id;
+    }, []);
+    const setActiveView = useCallback((viewId) => {
+        setActiveViewId(viewId);
+    }, []);
+    const deleteView = useCallback((viewId) => {
+        setViews((prev) => prev.filter((v) => v.id !== viewId));
+        setActiveViewId((current) => (current === viewId ? null : current));
+    }, []);
+    const duplicateView = useCallback((viewId, newName) => {
+        const original = views.find((v) => v.id === viewId);
+        if (!original)
+            return '';
+        const id = `view-${++viewCounter}`;
+        const duplicate = {
+            ...original,
+            id,
+            name: newName,
+            isDefault: false,
+            updatedAt: new Date(),
+        };
+        setViews((prev) => [...prev, duplicate]);
+        return id;
+    }, [views]);
+    const setVisibility = useCallback((viewId, visibility) => {
+        setViews((prev) => prev.map((v) => v.id === viewId ? { ...v, visibility, updatedAt: new Date() } : v));
+    }, []);
+    return useMemo(() => ({
+        views,
+        activeView,
+        saveView,
+        setActiveView,
+        deleteView,
+        duplicateView,
+        setVisibility,
+    }), [views, activeView, saveView, setActiveView, deleteView, duplicateView, setVisibility]);
+}