@object-ui/react 0.3.1 → 2.0.0

package/src/hooks/usePageVariables.tsx

@@ -0,0 +1,157 @@
+/**
+ * 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 React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
+import type { PageVariable } from '@object-ui/types';
+
+/**
+ * Page variables context value.
+ * Provides access to page-level state variables.
+ */
+export interface PageVariablesContextValue {
+  /** Current variable values */
+  variables: Record<string, any>;
+  /** Set a single variable value */
+  setVariable: (name: string, value: any) => void;
+  /** Set multiple variable values at once */
+  setVariables: (updates: Record<string, any>) => void;
+  /** Reset all variables to their default values */
+  resetVariables: () => void;
+}
+
+const PageVariablesContext = createContext<PageVariablesContextValue | null>(null);
+
+/**
+ * Initialize page variables from their definitions.
+ * Sets each variable to its defaultValue or type-appropriate default.
+ */
+function initializeVariables(definitions?: PageVariable[]): Record<string, any> {
+  if (!definitions || definitions.length === 0) return {};
+
+  const initial: Record<string, any> = {};
+  for (const def of definitions) {
+    if (def.defaultValue !== undefined) {
+      initial[def.name] = def.defaultValue;
+    } else {
+      // Type-appropriate defaults
+      switch (def.type) {
+        case 'number':
+          initial[def.name] = 0;
+          break;
+        case 'boolean':
+          initial[def.name] = false;
+          break;
+        case 'object':
+          initial[def.name] = {};
+          break;
+        case 'array':
+          initial[def.name] = [];
+          break;
+        case 'string':
+        default:
+          initial[def.name] = '';
+          break;
+      }
+    }
+  }
+  return initial;
+}
+
+/**
+ * Props for PageVariablesProvider
+ */
+export interface PageVariablesProviderProps {
+  /** Variable definitions from PageSchema.variables */
+  definitions?: PageVariable[];
+  /** Child components */
+  children: React.ReactNode;
+}
+
+/**
+ * PageVariablesProvider — Provides page-level state variables to the component tree.
+ *
+ * Initializes variables from their definitions and provides read/write access
+ * to all child components via the usePageVariables hook.
+ *
+ * @example
+ * ```tsx
+ * <PageVariablesProvider definitions={[
+ *   { name: 'selectedId', type: 'string', defaultValue: '' },
+ *   { name: 'count', type: 'number', defaultValue: 0 },
+ * ]}>
+ *   <MyComponents />
+ * </PageVariablesProvider>
+ * ```
+ */
+export const PageVariablesProvider: React.FC<PageVariablesProviderProps> = ({
+  definitions,
+  children,
+}) => {
+  const [variables, setVariablesState] = useState<Record<string, any>>(() =>
+    initializeVariables(definitions)
+  );
+
+  const setVariable = useCallback((name: string, value: any) => {
+    setVariablesState((prev) => ({ ...prev, [name]: value }));
+  }, []);
+
+  const setVariables = useCallback((updates: Record<string, any>) => {
+    setVariablesState((prev) => ({ ...prev, ...updates }));
+  }, []);
+
+  const resetVariables = useCallback(() => {
+    setVariablesState(initializeVariables(definitions));
+  }, [definitions]);
+
+  const value = useMemo<PageVariablesContextValue>(
+    () => ({ variables, setVariable, setVariables, resetVariables }),
+    [variables, setVariable, setVariables, resetVariables]
+  );
+
+  return (
+    <PageVariablesContext.Provider value={value}>
+      {children}
+    </PageVariablesContext.Provider>
+  );
+};
+
+PageVariablesProvider.displayName = 'PageVariablesProvider';
+
+/**
+ * Hook to access page-level variables.
+ *
+ * Returns the current variable values and setter functions.
+ * Returns a no-op fallback if used outside a PageVariablesProvider.
+ *
+ * @example
+ * ```tsx
+ * const { variables, setVariable } = usePageVariables();
+ * const userId = variables.selectedId;
+ * setVariable('selectedId', '123');
+ * ```
+ */
+export function usePageVariables(): PageVariablesContextValue {
+  const ctx = useContext(PageVariablesContext);
+  if (!ctx) {
+    // Graceful fallback — allows components to work outside a Page
+    return {
+      variables: {},
+      setVariable: () => {},
+      setVariables: () => {},
+      resetVariables: () => {},
+    };
+  }
+  return ctx;
+}
+
+/**
+ * Hook to check if a PageVariablesProvider is available.
+ */
+export function useHasPageVariables(): boolean {
+  return useContext(PageVariablesContext) !== null;
+}

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/index.ts

@@ -10,4 +10,26 @@ export * from './SchemaRenderer';
 export * from './hooks'; // will be empty for now
 export * from './context'; // will be empty for now
 export * from './components/form';
+export * from './LazyPluginLoader';
+
+// Built-in i18n support
+export {
+  I18nProvider,
+  useObjectTranslation,
+  useI18nContext,
+  createI18n,
+  getDirection,
+  getAvailableLanguages,
+  formatDate,
+  formatDateTime,
+  formatRelativeTime,
+  formatCurrency,
+  formatNumber,
+  type I18nConfig,
+  type I18nProviderProps,
+  type TranslationKeys,
+  type DateFormatOptions,
+  type CurrencyFormatOptions,
+  type NumberFormatOptions,
+} from '@object-ui/i18n';
 

package/src/utils/i18n.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolves an I18nLabel to a plain string.
+ * I18nLabel can be either a string or an object { key, defaultValue?, params? }.
+ * When it's an object, we return the defaultValue or the key as fallback.
+ */
+export function resolveI18nLabel(label: string | { key: string; defaultValue?: string; params?: Record<string, any> } | undefined): string | undefined {
+  if (label === undefined || label === null) return undefined;
+  if (typeof label === 'string') return label;
+  return label.defaultValue || label.key;
+}

package/tsconfig.json

@@ -9,6 +9,7 @@
     "composite": true
   },
   "include": ["src"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.test.tsx"],
   "references": [
     { "path": "../types" },
     { "path": "../core" }