@object-ui/react 3.3.0 → 3.3.1

package/src/hooks/useSchemaPersistence.ts

@@ -1,222 +0,0 @@
-/**
- * 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';
-
-/**
- * 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 function createLocalStorageAdapter(prefix = 'objectui-schema'): SchemaPersistenceAdapter {
-  return {
-    async save(id: string, schema: Record<string, unknown>): Promise<string> {
-      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: string[] = JSON.parse(localStorage.getItem(indexKey) || '[]');
-      if (!index.includes(id)) {
-        index.push(id);
-        localStorage.setItem(indexKey, JSON.stringify(index));
-      }
-      return id;
-    },
-    async load(id: string): Promise<Record<string, unknown> | null> {
-      const key = `${prefix}:${id}`;
-      const raw = localStorage.getItem(key);
-      if (!raw) return null;
-      const entry = JSON.parse(raw);
-      return entry.schema ?? null;
-    },
-    async list(): Promise<Array<{ id: string; name?: string; updatedAt?: string }>> {
-      const indexKey = `${prefix}:__index__`;
-      const index: string[] = 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: string): Promise<void> {
-      const key = `${prefix}:${id}`;
-      localStorage.removeItem(key);
-      const indexKey = `${prefix}:__index__`;
-      const index: string[] = 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?: SchemaPersistenceAdapter,
-): SchemaPersistenceResult {
-  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<Error | null>(null);
-  const [isDirty, setIsDirty] = useState(false);
-  const [lastSavedAt, setLastSavedAt] = useState<Date | null>(null);
-
-  const save = useCallback(
-    async (id: string, schema: Record<string, unknown>): Promise<string | null> => {
-      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: string): Promise<Record<string, unknown> | null> => {
-    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 (): Promise<Array<{ id: string; name?: string; updatedAt?: string }>> => {
-    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: string): Promise<boolean> => {
-    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/src/hooks/useViewData.ts

@@ -1,201 +0,0 @@
-/**
- * ObjectUI — useViewData
- * 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.
- *
- * A React hook that resolves a ViewData configuration into a DataSource
- * and provides reactive data fetching with loading/error states.
- */
-
-import { useState, useEffect, useCallback, useMemo, useContext } from 'react';
-import type { DataSource, ViewData, QueryParams, QueryResult } from '@object-ui/types';
-import { resolveDataSource, type ResolveDataSourceOptions } from '@object-ui/core';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface UseViewDataOptions<T = any> {
-  /** The ViewData configuration from the schema */
-  viewData?: ViewData | null;
-  /** Resource name (object name, used for DataSource.find calls) */
-  resource?: string;
-  /** Initial query parameters */
-  params?: QueryParams;
-  /** Explicit data source override (bypasses context) */
-  dataSource?: DataSource<T> | null;
-  /** Options for adapter construction */
-  adapterOptions?: ResolveDataSourceOptions;
-  /** If true, skip the initial fetch (useful for forms in create mode) */
-  skip?: boolean;
-}
-
-export interface UseViewDataResult<T = any> {
-  /** Resolved data array */
-  data: T[];
-  /** Total number of records (from server or array length) */
-  totalCount: number;
-  /** Whether data is being fetched */
-  loading: boolean;
-  /** Error from the last fetch attempt */
-  error: Error | null;
-  /** The resolved DataSource instance (can be used for create/update/delete) */
-  dataSource: DataSource<T> | null;
-  /** Re-fetch data with current or new params */
-  refresh: (newParams?: QueryParams) => Promise<void>;
-  /** Fetch a single record by ID */
-  fetchOne: (id: string | number) => Promise<T | null>;
-  /** Whether more records are available */
-  hasMore: boolean;
-}
-
-// ---------------------------------------------------------------------------
-// Hook
-// ---------------------------------------------------------------------------
-
-/**
- * useViewData — resolves ViewData into a DataSource and provides reactive data.
- *
- * This hook centralizes the data resolution pattern that was previously
- * duplicated across plugins (ObjectGrid, ObjectView, etc.). It:
- *
- * 1. Resolves the ViewData config to the right DataSource adapter
- *    - `provider: 'object'` → context DataSource (ObjectStackAdapter)
- *    - `provider: 'api'`    → ApiDataSource (raw HTTP)
- *    - `provider: 'value'`  → ValueDataSource (in-memory)
- * 2. Fetches data automatically on mount
- * 3. Provides loading/error states and refresh capability
- *
- * @example
- * ```tsx
- * function MyGrid({ schema }) {
- *   const { data, loading, error, refresh, dataSource } = useViewData({
- *     viewData: schema.data,
- *     resource: schema.objectName,
- *     params: { $top: 50 },
- *   });
- *
- *   if (loading) return <Spinner />;
- *   if (error) return <ErrorMessage error={error} />;
- *   return <Table data={data} />;
- * }
- * ```
- */
-export function useViewData<T = any>(options: UseViewDataOptions<T>): UseViewDataResult<T> {
-  const {
-    viewData,
-    resource = '',
-    params,
-    dataSource: explicitDataSource,
-    adapterOptions,
-    skip = false,
-  } = options;
-
-  // Get context DataSource
-  const context = useContext(SchemaRendererContext);
-  const contextDataSource = context?.dataSource ?? null;
-
-  // Resolve the DataSource — memoize to prevent re-creation on every render.
-  // We key on the viewData provider + config identity.
-  const resolvedDataSource = useMemo(() => {
-    if (explicitDataSource) return explicitDataSource;
-    return resolveDataSource<T>(viewData, contextDataSource, adapterOptions);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [
-    explicitDataSource,
-    viewData?.provider,
-    // For 'api' provider, key on read/write URLs
-    viewData?.provider === 'api' ? (viewData as any).read?.url : undefined,
-    viewData?.provider === 'api' ? (viewData as any).write?.url : undefined,
-    // For 'value' provider, key on items reference (or length as proxy)
-    viewData?.provider === 'value' ? (viewData as any).items?.length : undefined,
-    contextDataSource,
-  ]);
-
-  // State
-  const [data, setData] = useState<T[]>([]);
-  const [totalCount, setTotalCount] = useState(0);
-  const [loading, setLoading] = useState(!skip);
-  const [error, setError] = useState<Error | null>(null);
-  const [hasMore, setHasMore] = useState(false);
-
-  // Stable params reference
-  const paramsKey = useMemo(() => JSON.stringify(params ?? {}), [params]);
-
-  // Fetch function
-  const fetchData = useCallback(
-    async (fetchParams?: QueryParams) => {
-      if (!resolvedDataSource || !resource) {
-        setLoading(false);
-        return;
-      }
-
-      setLoading(true);
-      setError(null);
-
-      try {
-        const mergedParams = fetchParams ?? (params ? { ...params } : undefined);
-        const result: QueryResult<T> = await resolvedDataSource.find(resource, mergedParams);
-        setData(result.data ?? []);
-        setTotalCount(result.total ?? result.data?.length ?? 0);
-        setHasMore(result.hasMore ?? false);
-      } catch (err) {
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setData([]);
-        setTotalCount(0);
-      } finally {
-        setLoading(false);
-      }
-    },
-    [resolvedDataSource, resource, params],
-  );
-
-  // Auto-fetch on mount / when deps change
-  useEffect(() => {
-    if (skip) {
-      setLoading(false);
-      return;
-    }
-
-    // For value provider, data is synchronous — still go through fetchData
-    // for consistency, but it resolves immediately.
-    fetchData();
-
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [resolvedDataSource, resource, paramsKey, skip]);
-
-  // Refresh function (can accept new params)
-  const refresh = useCallback(
-    async (newParams?: QueryParams) => {
-      await fetchData(newParams);
-    },
-    [fetchData],
-  );
-
-  // Fetch one record
-  const fetchOne = useCallback(
-    async (id: string | number): Promise<T | null> => {
-      if (!resolvedDataSource) return null;
-      try {
-        return await resolvedDataSource.findOne(resource, id);
-      } catch {
-        return null;
-      }
-    },
-    [resolvedDataSource, resource],
-  );
-
-  return {
-    data,
-    totalCount,
-    loading,
-    error,
-    dataSource: resolvedDataSource,
-    refresh,
-    fetchOne,
-    hasMore,
-  };
-}

package/src/hooks/useViewSharing.ts

@@ -1,140 +0,0 @@
-/**
- * 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';
-
-/** 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;
-}
-
-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: SavedView[] = []): ViewSharingResult {
-  const [views, setViews] = useState<SavedView[]>(initialViews);
-  const [activeViewId, setActiveViewId] = useState<string | null>(
-    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: Omit<SavedView, 'id' | 'updatedAt'>): string => {
-      const id = `view-${++viewCounter}`;
-      const view: SavedView = {
-        ...input,
-        id,
-        updatedAt: new Date(),
-      };
-      setViews((prev) => [...prev, view]);
-      return id;
-    },
-    []
-  );
-
-  const setActiveView = useCallback((viewId: string) => {
-    setActiveViewId(viewId);
-  }, []);
-
-  const deleteView = useCallback((viewId: string) => {
-    setViews((prev) => prev.filter((v) => v.id !== viewId));
-    setActiveViewId((current) => (current === viewId ? null : current));
-  }, []);
-
-  const duplicateView = useCallback(
-    (viewId: string, newName: string): string => {
-      const original = views.find((v) => v.id === viewId);
-      if (!original) return '';
-      const id = `view-${++viewCounter}`;
-      const duplicate: SavedView = {
-        ...original,
-        id,
-        name: newName,
-        isDefault: false,
-        updatedAt: new Date(),
-      };
-      setViews((prev) => [...prev, duplicate]);
-      return id;
-    },
-    [views]
-  );
-
-  const setVisibility = useCallback(
-    (viewId: string, visibility: ViewVisibility) => {
-      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]
-  );
-}

package/src/hooks/useViewTransition.ts

@@ -1,144 +0,0 @@
-/**
- * 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';
-import { useReducedMotion } from './useReducedMotion';
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface ViewTransitionConfig {
-  /** Enable view transitions (default: true) */
-  enabled?: boolean;
-  /** Fallback animation class when View Transitions API is unsupported */
-  fallbackClass?: string;
-  /** Transition duration in ms (default: 300) */
-  duration?: number;
-  /** Called before transition starts */
-  onTransitionStart?: () => void;
-  /** Called after transition completes */
-  onTransitionEnd?: () => void;
-}
-
-export interface ViewTransitionResult {
-  /** Whether the View Transitions API is supported */
-  isSupported: boolean;
-  /** Whether a transition is currently in progress */
-  isTransitioning: boolean;
-  /** Execute a callback with a view transition */
-  startTransition: (callback: () => void | Promise<void>) => Promise<void>;
-  /** CSS class to apply during transitions */
-  transitionClass: string;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const DEFAULT_DURATION = 300;
-const DEFAULT_FALLBACK_CLASS = 'oui-view-transition-fallback';
-
-/** Minimal type for the native ViewTransition object returned by the API. */
-interface ViewTransition {
-  finished: Promise<void>;
-  ready: Promise<void>;
-  updateCallbackDone: Promise<void>;
-}
-
-function supportsViewTransitions(): boolean {
-  return (
-    typeof document !== 'undefined' &&
-    'startViewTransition' in document
-  );
-}
-
-// ---------------------------------------------------------------------------
-// useViewTransition hook
-// ---------------------------------------------------------------------------
-
-/**
- * Hook for integrating with the browser View Transitions API.
- *
- * Uses the native `document.startViewTransition()` when available and
- * falls back to a temporary CSS class for animation when unsupported.
- * Respects `prefers-reduced-motion`.
- *
- * @example
- * ```tsx
- * function ViewSwitcher({ onViewChange }: { onViewChange: (v: string) => void }) {
- *   const { startTransition, transitionClass, isTransitioning } = useViewTransition();
- *
- *   const handleChange = (view: string) => {
- *     startTransition(() => onViewChange(view));
- *   };
- *
- *   return (
- *     <div className={transitionClass}>
- *       ...
- *     </div>
- *   );
- * }
- * ```
- */
-export function useViewTransition(
-  config: ViewTransitionConfig = {},
-): ViewTransitionResult {
-  const {
-    enabled = true,
-    fallbackClass = DEFAULT_FALLBACK_CLASS,
-    duration = DEFAULT_DURATION,
-    onTransitionStart,
-    onTransitionEnd,
-  } = config;
-
-  const reducedMotion = useReducedMotion();
-  const [isTransitioning, setIsTransitioning] = useState(false);
-
-  const isSupported = useMemo(() => supportsViewTransitions(), []);
-
-  const startTransition = useCallback(
-    async (callback: () => void | Promise<void>): Promise<void> => {
-      // Skip transition when disabled or user prefers reduced motion
-      if (!enabled || reducedMotion) {
-        await callback();
-        return;
-      }
-
-      onTransitionStart?.();
-      setIsTransitioning(true);
-
-      try {
-        if (isSupported) {
-          // Use native View Transitions API
-          const transition = (document as Document & {
-            startViewTransition: (cb: () => void | Promise<void>) => ViewTransition;
-          }).startViewTransition(callback);
-          await transition.finished;
-        } else {
-          // Fallback: apply class, run callback, remove class after duration
-          await callback();
-          await new Promise<void>((resolve) => setTimeout(resolve, duration));
-        }
-      } finally {
-        setIsTransitioning(false);
-        onTransitionEnd?.();
-      }
-    },
-    [enabled, reducedMotion, isSupported, duration, onTransitionStart, onTransitionEnd],
-  );
-
-  const transitionClass = isTransitioning && !isSupported ? fallbackClass : '';
-
-  return {
-    isSupported,
-    isTransitioning,
-    startTransition,
-    transitionClass,
-  };
-}