@object-ui/react 0.5.0 → 3.0.0

package/src/hooks/useSchemaPersistence.ts

@@ -0,0 +1,222 @@
+/**
+ * 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

@@ -0,0 +1,201 @@
+/**
+ * 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

@@ -0,0 +1,140 @@
+/**
+ * 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

@@ -0,0 +1,144 @@
+/**
+ * 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,
+  };
+}