@object-ui/react 3.1.5 → 3.3.1

package/src/hooks/useActionEngine.ts

@@ -1,84 +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.
- */
-
-/**
- * useActionEngine — React hook wrapping ActionEngine for location-based action management.
- *
- * Provides declarative access to the ActionEngine's location filtering, bulk operations,
- * keyboard shortcut handling, and execution pipeline from React components.
- *
- * @example
- * ```tsx
- * const { getActionsForLocation, executeAction } = useActionEngine({
- *   actions: schema.actions,
- *   context: { record, user },
- * });
- *
- * const toolbarActions = getActionsForLocation('list_toolbar');
- * ```
- */
-
-import { useCallback, useMemo } from 'react';
-import {
-  ActionEngine,
-  type ActionLocation,
-  type ActionDef,
-  type ActionContext,
-  type ActionResult,
-} from '@object-ui/core';
-
-export interface UseActionEngineOptions {
-  /** Action definitions to register */
-  actions?: ActionDef[];
-  /** Action context (record, user, etc.) */
-  context?: ActionContext;
-}
-
-export interface UseActionEngineReturn {
-  /** Get actions available at a specific location, sorted by priority */
-  getActionsForLocation: (location: ActionLocation) => ActionDef[];
-  /** Get actions that support bulk operations */
-  getBulkActions: () => ActionDef[];
-  /** Execute an action by name */
-  executeAction: (name: string, contextOverride?: Partial<ActionContext>) => Promise<ActionResult>;
-  /** Handle a keyboard shortcut */
-  handleShortcut: (keys: string) => Promise<ActionResult | null>;
-  /** The underlying ActionEngine instance */
-  engine: ActionEngine;
-}
-
-export function useActionEngine(options: UseActionEngineOptions = {}): UseActionEngineReturn {
-  const { actions = [], context = {} } = options;
-
-  const engine = useMemo(() => {
-    const e = new ActionEngine(context);
-    e.registerActions(actions);
-    return e;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [JSON.stringify(actions), JSON.stringify(context)]);
-
-  const getActionsForLocation = useCallback(
-    (location: ActionLocation) => engine.getActionsForLocation(location),
-    [engine],
-  );
-
-  const getBulkActions = useCallback(() => engine.getBulkActions(), [engine]);
-
-  const executeAction = useCallback(
-    (name: string, contextOverride?: Partial<ActionContext>) =>
-      engine.executeAction(name, contextOverride),
-    [engine],
-  );
-
-  const handleShortcut = useCallback(
-    (keys: string) => engine.handleShortcut(keys),
-    [engine],
-  );
-
-  return { getActionsForLocation, getBulkActions, executeAction, handleShortcut, engine };
-}

package/src/hooks/useActionRunner.ts

@@ -1,119 +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 {
-  ActionRunner,
-  type ActionContext,
-  type ActionDef,
-  type ActionResult,
-  type ConfirmationHandler,
-  type ToastHandler,
-  type ModalHandler,
-  type NavigationHandler,
-} from '@object-ui/core';
-
-export interface UseActionRunnerOptions {
-  context?: ActionContext;
-  /** Custom confirmation handler — wire to Shadcn AlertDialog or similar */
-  onConfirm?: ConfirmationHandler;
-  /** Custom toast handler — wire to Sonner or similar */
-  onToast?: ToastHandler;
-  /** Custom modal handler — render modals in response to modal actions */
-  onModal?: ModalHandler;
-  /** Custom navigation handler — SPA-aware routing */
-  onNavigate?: NavigationHandler;
-}
-
-/**
- * Hook for executing actions with loading state, typed with ActionDef.
- * 
- * @example
- * ```tsx
- * const { execute, loading, error, result } = useActionRunner({
- *   context: { data: formData },
- *   onToast: (msg, opts) => toast[opts?.type || 'info'](msg),
- * });
- * 
- * const handleClick = () => {
- *   execute({
- *     type: 'api',
- *     api: '/api/save',
- *     successMessage: 'Saved successfully!',
- *   });
- * };
- * ```
- */
-export function useActionRunner(
-  optionsOrContext: UseActionRunnerOptions | ActionContext = {},
-) {
-  // Backwards compat: if no 'context' key, treat entire object as context
-  const options: UseActionRunnerOptions = 'context' in optionsOrContext
-    ? optionsOrContext as UseActionRunnerOptions
-    : { context: optionsOrContext as ActionContext };
-
-  const { context = {}, onConfirm, onToast, onModal, onNavigate } = options;
-
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const [result, setResult] = useState<ActionResult | null>(null);
-
-  const runner = useMemo(() => {
-    const r = new ActionRunner(context);
-    if (onConfirm) r.setConfirmHandler(onConfirm);
-    if (onToast) r.setToastHandler(onToast);
-    if (onModal) r.setModalHandler(onModal);
-    if (onNavigate) r.setNavigationHandler(onNavigate);
-    return r;
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [JSON.stringify(context)]);
-
-  const execute = useCallback(
-    async (action: ActionDef): Promise<ActionResult> => {
-      setLoading(true);
-      setError(null);
-      setResult(null);
-
-      try {
-        const actionResult = await runner.execute(action);
-        setResult(actionResult);
-
-        if (!actionResult.success) {
-          setError(actionResult.error || 'Action failed');
-        }
-
-        return actionResult;
-      } catch (err) {
-        const errorMessage = (err as Error).message;
-        setError(errorMessage);
-        const failureResult = { success: false, error: errorMessage };
-        setResult(failureResult);
-        return failureResult;
-      } finally {
-        setLoading(false);
-      }
-    },
-    [runner]
-  );
-
-  const updateContext = useCallback(
-    (newContext: Partial<ActionContext>) => {
-      runner.updateContext(newContext);
-    },
-    [runner]
-  );
-
-  return {
-    execute,
-    loading,
-    error,
-    result,
-    updateContext,
-    runner
-  };
-}

package/src/hooks/useAnimation.ts

@@ -1,117 +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 { useMemo } from 'react';
-
-/** Animation trigger type */
-export type AnimationTriggerType = 'enter' | 'exit' | 'hover' | 'focus' | 'click';
-
-/** Easing presets aligned with EasingFunctionSchema */
-export type EasingPreset =
-  | 'linear'
-  | 'ease'
-  | 'ease-in'
-  | 'ease-out'
-  | 'ease-in-out'
-  | 'spring';
-
-/** Transition preset aligned with TransitionPresetSchema */
-export type TransitionPresetType =
-  | 'fade'
-  | 'slide-up'
-  | 'slide-down'
-  | 'slide-left'
-  | 'slide-right'
-  | 'scale'
-  | 'scale-fade'
-  | 'none';
-
-export interface AnimationConfig {
-  /** The animation/transition preset */
-  preset?: TransitionPresetType;
-  /** Duration in milliseconds */
-  duration?: number;
-  /** Delay in milliseconds */
-  delay?: number;
-  /** Easing function */
-  easing?: EasingPreset;
-  /** Whether animation is enabled */
-  enabled?: boolean;
-}
-
-/** Resolved CSS classes and styles for animation */
-export interface AnimationResult {
-  /** Tailwind CSS classes for the animation */
-  className: string;
-  /** Inline style for custom durations/delays (only when needed) */
-  style: React.CSSProperties;
-}
-
-const EASING_MAP: Record<EasingPreset, string> = {
-  linear: 'linear',
-  ease: 'ease',
-  'ease-in': 'ease-in',
-  'ease-out': 'ease-out',
-  'ease-in-out': 'ease-in-out',
-  spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
-};
-
-const PRESET_CLASSES: Record<TransitionPresetType, string> = {
-  fade: 'animate-in fade-in',
-  'slide-up': 'animate-in slide-in-from-bottom-2',
-  'slide-down': 'animate-in slide-in-from-top-2',
-  'slide-left': 'animate-in slide-in-from-right-2',
-  'slide-right': 'animate-in slide-in-from-left-2',
-  scale: 'animate-in zoom-in-95',
-  'scale-fade': 'animate-in fade-in zoom-in-95',
-  none: '',
-};
-
-/**
- * Hook for applying spec-driven animations to components.
- * Implements ComponentAnimationSchema and TransitionPresetSchema
- * from @objectstack/spec v2.0.7.
- *
- * @example
- * ```tsx
- * function Card() {
- *   const animation = useAnimation({ preset: 'fade', duration: 200, easing: 'ease-out' });
- *   return <div className={animation.className} style={animation.style}>...</div>;
- * }
- * ```
- */
-export function useAnimation(config: AnimationConfig = {}): AnimationResult {
-  const {
-    preset = 'none',
-    duration,
-    delay,
-    easing = 'ease-out',
-    enabled = true,
-  } = config;
-
-  return useMemo(() => {
-    if (!enabled || preset === 'none') {
-      return { className: '', style: {} };
-    }
-
-    const className = PRESET_CLASSES[preset] || '';
-    const style: React.CSSProperties = {};
-
-    if (duration !== undefined) {
-      style.animationDuration = `${duration}ms`;
-    }
-    if (delay !== undefined) {
-      style.animationDelay = `${delay}ms`;
-    }
-    if (easing) {
-      style.animationTimingFunction = EASING_MAP[easing] || easing;
-    }
-
-    return { className, style };
-  }, [preset, duration, delay, easing, enabled]);
-}

package/src/hooks/useClientNotifications.ts

@@ -1,251 +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.
- */
-
-/**
- * @object-ui/react - useClientNotifications
- *
- * Bridge hook between the @objectstack/client notifications API
- * and the local NotificationContext state. Fetches server-side
- * notifications and surfaces them through the existing provider.
- */
-
-import { useCallback, useContext, useEffect, useRef, useState } from 'react';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
-import { useNotifications } from '../context/NotificationContext';
-import type { NotificationSeverityLevel } from '../context/NotificationContext';
-
-/* ------------------------------------------------------------------ */
-/*  Public types                                                      */
-/* ------------------------------------------------------------------ */
-
-export interface UseClientNotificationsOptions {
-  /** ObjectStack client instance (optional, from context if available) */
-  client?: any;
-  /** Whether to auto-fetch notifications on mount */
-  autoFetch?: boolean;
-  /** Polling interval in ms (0 to disable) */
-  pollInterval?: number;
-}
-
-export interface UseClientNotificationsResult {
-  /** Fetch notifications from server */
-  fetchNotifications: () => Promise<void>;
-  /** Register device for push notifications */
-  registerDevice: (token: string, platform: string) => Promise<void>;
-  /** Get notification preferences */
-  getPreferences: () => Promise<any>;
-  /** Update notification preferences */
-  updatePreferences: (prefs: any) => Promise<void>;
-  /** Mark a notification as read on the server */
-  markAsRead: (id: string) => Promise<void>;
-  /** Loading state */
-  loading: boolean;
-  /** Error state */
-  error: Error | null;
-}
-
-/* ------------------------------------------------------------------ */
-/*  Helpers                                                           */
-/* ------------------------------------------------------------------ */
-
-/** Normalise severity coming from the server into a valid local level. */
-function toSeverity(value: unknown): NotificationSeverityLevel {
-  const valid: NotificationSeverityLevel[] = ['info', 'success', 'warning', 'error'];
-  if (typeof value === 'string' && valid.includes(value as NotificationSeverityLevel)) {
-    return value as NotificationSeverityLevel;
-  }
-  return 'info';
-}
-
-/**
- * Resolve the ObjectStack client from explicit option or SchemaRendererContext.
- *
- * The dataSource stored in context is typically an ObjectStackAdapter which
- * exposes `getClient()`.  When the caller passes a client directly we use
- * that instead.
- */
-function useResolvedClient(explicit?: any): any {
-  const rendererCtx = useContext(SchemaRendererContext);
-  if (explicit) return explicit;
-
-  const dataSource = rendererCtx?.dataSource;
-  if (dataSource && typeof dataSource.getClient === 'function') {
-    return dataSource.getClient();
-  }
-  return null;
-}
-
-/* ------------------------------------------------------------------ */
-/*  Hook                                                              */
-/* ------------------------------------------------------------------ */
-
-/**
- * Bridge between the `@objectstack/client` notifications API and the
- * local {@link NotificationContext}.
- *
- * The hook resolves the ObjectStack client either from the explicit
- * `client` option or from the `SchemaRendererContext` dataSource, then
- * delegates to `client.notifications.*` methods.  Fetched notifications
- * are fed into the local provider via `useNotifications().notify()`.
- *
- * @example
- * ```tsx
- * function NotificationBell() {
- *   const { fetchNotifications, loading } = useClientNotifications({
- *     autoFetch: true,
- *     pollInterval: 30_000,
- *   });
- *
- *   return <Button onClick={fetchNotifications} disabled={loading}>🔔</Button>;
- * }
- * ```
- */
-export function useClientNotifications(
-  options: UseClientNotificationsOptions = {},
-): UseClientNotificationsResult {
-  const { client: explicitClient, autoFetch = false, pollInterval = 0 } = options;
-
-  const client = useResolvedClient(explicitClient);
-  const { notify, markAsRead: localMarkAsRead } = useNotifications();
-
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Track IDs that have already been pushed into the local context so we
-  // don't add duplicates on subsequent fetches / polls.
-  const seenIdsRef = useRef<Set<string>>(new Set());
-
-  /* ---- fetchNotifications ---- */
-
-  const fetchNotifications = useCallback(async () => {
-    if (!client?.notifications) return;
-
-    setLoading(true);
-    setError(null);
-
-    try {
-      const result = await client.notifications.list({});
-      const items: any[] = Array.isArray(result) ? result : result?.data ?? result?.items ?? [];
-
-      for (const item of items) {
-        const id = String(item.id ?? '');
-        if (!id || seenIdsRef.current.has(id)) continue;
-
-        seenIdsRef.current.add(id);
-        notify({
-          title: item.title ?? 'Notification',
-          message: item.message ?? item.body,
-          severity: toSeverity(item.severity ?? item.level),
-          duration: 0, // server-driven notifications are persistent
-        });
-      }
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error('Failed to fetch notifications'));
-    } finally {
-      setLoading(false);
-    }
-  }, [client, notify]);
-
-  /* ---- registerDevice ---- */
-
-  const registerDevice = useCallback(
-    async (token: string, platform: string) => {
-      if (!client?.notifications) return;
-      setError(null);
-      try {
-        await client.notifications.registerDevice(token, platform);
-      } catch (err) {
-        const wrapped = err instanceof Error ? err : new Error('Failed to register device');
-        setError(wrapped);
-        throw wrapped;
-      }
-    },
-    [client],
-  );
-
-  /* ---- getPreferences ---- */
-
-  const getPreferences = useCallback(async () => {
-    if (!client?.notifications) return null;
-    setError(null);
-    try {
-      return await client.notifications.getPreferences();
-    } catch (err) {
-      const wrapped = err instanceof Error ? err : new Error('Failed to get preferences');
-      setError(wrapped);
-      throw wrapped;
-    }
-  }, [client]);
-
-  /* ---- updatePreferences ---- */
-
-  const updatePreferences = useCallback(
-    async (prefs: any) => {
-      if (!client?.notifications) return;
-      setError(null);
-      try {
-        await client.notifications.updatePreferences(prefs);
-      } catch (err) {
-        const wrapped = err instanceof Error ? err : new Error('Failed to update preferences');
-        setError(wrapped);
-        throw wrapped;
-      }
-    },
-    [client],
-  );
-
-  /* ---- markAsRead (server + local) ---- */
-
-  const markAsRead = useCallback(
-    async (id: string) => {
-      // Optimistically mark locally first
-      localMarkAsRead(id);
-
-      if (!client?.notifications) return;
-      setError(null);
-      try {
-        await client.notifications.markAsRead(id);
-      } catch (err) {
-        const wrapped = err instanceof Error ? err : new Error('Failed to mark as read');
-        setError(wrapped);
-        throw wrapped;
-      }
-    },
-    [client, localMarkAsRead],
-  );
-
-  /* ---- auto-fetch on mount ---- */
-
-  useEffect(() => {
-    if (autoFetch && client?.notifications) {
-      fetchNotifications();
-    }
-  }, [autoFetch, client, fetchNotifications]);
-
-  /* ---- polling ---- */
-
-  useEffect(() => {
-    if (!pollInterval || pollInterval <= 0 || !client?.notifications) return;
-
-    const id = setInterval(() => {
-      fetchNotifications();
-    }, pollInterval);
-
-    return () => clearInterval(id);
-  }, [pollInterval, client, fetchNotifications]);
-
-  return {
-    fetchNotifications,
-    registerDevice,
-    getPreferences,
-    updatePreferences,
-    markAsRead,
-    loading,
-    error,
-  };
-}

package/src/hooks/useColumnSummary.ts

@@ -1,87 +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 { useMemo } from 'react';
-
-/** Summary function types aligned with ColumnSummarySchema */
-export type SummaryFunction = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'distinct';
-
-export interface ColumnSummaryConfig {
-  /** The field/column to aggregate */
-  field: string;
-  /** The aggregation function */
-  function: SummaryFunction;
-  /** Optional label for the summary */
-  label?: string;
-  /** Number format options */
-  format?: Intl.NumberFormatOptions;
-}
-
-export interface ColumnSummaryResult {
-  /** The computed value */
-  value: number;
-  /** Formatted display string */
-  formatted: string;
-  /** The label */
-  label: string;
-}
-
-/**
- * Hook for computing column-level summaries (SUM, AVG, COUNT, MIN, MAX, DISTINCT).
- * Implements ColumnSummarySchema from @objectstack/spec v2.0.7.
- *
- * @example
- * ```tsx
- * const summary = useColumnSummary(data, { field: 'amount', function: 'sum', label: 'Total' });
- * // summary.formatted => "$12,345.67"
- * ```
- */
-export function useColumnSummary(
-  data: Record<string, unknown>[],
-  config: ColumnSummaryConfig,
-  locale?: string
-): ColumnSummaryResult {
-  return useMemo(() => {
-    const values = data
-      .map((row) => {
-        const val = row[config.field];
-        return typeof val === 'number' ? val : Number(val);
-      })
-      .filter((v) => !isNaN(v));
-
-    let value: number;
-
-    switch (config.function) {
-      case 'sum':
-        value = values.reduce((acc, v) => acc + v, 0);
-        break;
-      case 'avg':
-        value = values.length > 0 ? values.reduce((acc, v) => acc + v, 0) / values.length : 0;
-        break;
-      case 'count':
-        value = data.length;
-        break;
-      case 'min':
-        value = values.length > 0 ? Math.min(...values) : 0;
-        break;
-      case 'max':
-        value = values.length > 0 ? Math.max(...values) : 0;
-        break;
-      case 'distinct':
-        value = new Set(data.map((row) => row[config.field])).size;
-        break;
-      default:
-        value = 0;
-    }
-
-    const formatted = new Intl.NumberFormat(locale, config.format).format(value);
-    const label = config.label ?? config.function.toUpperCase();
-
-    return { value, formatted, label };
-  }, [data, config.field, config.function, config.label, config.format, locale]);
-}