@object-ui/react 3.3.0 → 3.3.1

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]);
-}

package/src/hooks/useCrudShortcuts.ts

@@ -1,126 +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';
-import {
-  useKeyboardShortcuts,
-  type KeyboardShortcutDefinition,
-} from './useKeyboardShortcuts';
-
-export interface CrudShortcutCallbacks {
-  onCreate?: () => void;
-  onEdit?: () => void;
-  onDelete?: () => void;
-  onSave?: () => void;
-  onDuplicate?: () => void;
-  onCancel?: () => void;
-  onSearch?: () => void;
-}
-
-/**
- * Registers standard CRUD keyboard shortcuts using the useKeyboardShortcuts hook.
- *
- * Shortcuts:
- * - Ctrl/Cmd+N: Create new record
- * - Ctrl/Cmd+E: Edit selected record
- * - Delete / Backspace: Delete selected record(s)
- * - Ctrl/Cmd+S: Save current record
- * - Ctrl/Cmd+D: Duplicate selected record
- * - Escape: Cancel/close current operation
- * - Ctrl/Cmd+F: Focus search
- *
- * @example
- * ```tsx
- * useCrudShortcuts({
- *   onCreate: () => openCreateDialog(),
- *   onSave: () => saveRecord(),
- *   onDelete: () => deleteSelected(),
- *   onCancel: () => closeDialog(),
- * });
- * ```
- */
-export function useCrudShortcuts(
-  callbacks: CrudShortcutCallbacks,
-  enabled = true
-): void {
-  const shortcuts = useMemo<KeyboardShortcutDefinition[]>(() => {
-    const defs: KeyboardShortcutDefinition[] = [];
-
-    if (callbacks.onCreate) {
-      defs.push({
-        key: 'n',
-        ctrlOrMeta: true,
-        handler: () => callbacks.onCreate!(),
-        description: 'New record',
-      });
-    }
-
-    if (callbacks.onEdit) {
-      defs.push({
-        key: 'e',
-        ctrlOrMeta: true,
-        handler: () => callbacks.onEdit!(),
-        description: 'Edit selected record',
-      });
-    }
-
-    if (callbacks.onDelete) {
-      defs.push(
-        {
-          key: 'Delete',
-          handler: () => callbacks.onDelete!(),
-          description: 'Delete selected record(s)',
-        },
-        {
-          key: 'Backspace',
-          handler: () => callbacks.onDelete!(),
-          description: 'Delete selected record(s)',
-        }
-      );
-    }
-
-    if (callbacks.onSave) {
-      defs.push({
-        key: 's',
-        ctrlOrMeta: true,
-        handler: () => callbacks.onSave!(),
-        description: 'Save current record',
-      });
-    }
-
-    if (callbacks.onDuplicate) {
-      defs.push({
-        key: 'd',
-        ctrlOrMeta: true,
-        handler: () => callbacks.onDuplicate!(),
-        description: 'Duplicate selected record',
-      });
-    }
-
-    if (callbacks.onCancel) {
-      defs.push({
-        key: 'Escape',
-        handler: () => callbacks.onCancel!(),
-        description: 'Cancel/close current operation',
-      });
-    }
-
-    if (callbacks.onSearch) {
-      defs.push({
-        key: 'f',
-        ctrlOrMeta: true,
-        handler: () => callbacks.onSearch!(),
-        description: 'Focus search',
-      });
-    }
-
-    return defs;
-  }, [callbacks]);
-
-  useKeyboardShortcuts(shortcuts, { enabled });
-}

package/src/hooks/useDataRefresh.ts

@@ -1,58 +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, useEffect } from 'react';
-import type { DataSource } from '@object-ui/types';
-
-/**
- * Reusable hook that encapsulates the data-refresh pattern:
- *  1. A numeric `refreshKey` that triggers React effect re-runs when incremented.
- *  2. An imperative `refresh()` function to trigger a re-fetch on demand.
- *  3. Auto-subscription to `DataSource.onMutation()` — if the DataSource
- *     implements the optional mutation event bus, the hook auto-refreshes
- *     whenever a mutation occurs on the matching `objectName`.
- *
- * @param dataSource - The DataSource instance (may be undefined during initial render)
- * @param objectName - The resource/object name to watch for mutations
- * @returns `{ refreshKey, refresh }` — include `refreshKey` in your effect deps
- *
- * @example
- * ```tsx
- * const { refreshKey, refresh } = useDataRefresh(dataSource, schema.objectName);
- *
- * useEffect(() => {
- *   dataSource.find(objectName, params).then(setData);
- * }, [objectName, refreshKey]);
- *
- * // Or trigger manually:
- * <button onClick={refresh}>Refresh</button>
- * ```
- */
-export function useDataRefresh(
-  dataSource: DataSource | undefined,
-  objectName: string | undefined,
-): { refreshKey: number; refresh: () => void } {
-  const [refreshKey, setRefreshKey] = useState(0);
-
-  const refresh = useCallback(() => {
-    setRefreshKey(k => k + 1);
-  }, []);
-
-  // Auto-subscribe to DataSource mutation events
-  useEffect(() => {
-    if (!dataSource?.onMutation || !objectName) return;
-    const unsub = dataSource.onMutation((event) => {
-      if (event.resource === objectName) {
-        setRefreshKey(k => k + 1);
-      }
-    });
-    return unsub;
-  }, [dataSource, objectName]);
-
-  return { refreshKey, refresh };
-}

package/src/hooks/useDebugMode.ts

@@ -1,95 +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, useEffect, useCallback, useMemo } from 'react';
-import { parseDebugFlags, type DebugFlags } from '@object-ui/core';
-
-/**
- * Result returned by {@link useDebugMode}.
- */
-export interface UseDebugModeResult {
-  /** Whether debug mode is currently enabled */
-  enabled: boolean;
-  /** Fine-grained debug flags parsed from the URL */
-  flags: DebugFlags;
-  /** Toggle debug mode on/off */
-  toggle: () => void;
-  /** Explicitly set debug mode */
-  setEnabled: (value: boolean) => void;
-}
-
-/**
- * Hook for managing debug mode.
- *
- * Automatically detects `?__debug` (and sub-flags like `?__debug_schema`)
- * from the URL. Supports manual toggle and Ctrl+Shift+D keyboard shortcut.
- *
- * SSR-safe — returns disabled state when `window` is unavailable.
- *
- * @example
- * ```tsx
- * function App() {
- *   const debug = useDebugMode();
- *   return (
- *     <>
- *       {debug.enabled && <DebugPanel flags={debug.flags} />}
- *       <button onClick={debug.toggle}>Toggle Debug</button>
- *     </>
- *   );
- * }
- * ```
- */
-export function useDebugMode(): UseDebugModeResult {
-  const urlFlags = useMemo(() => {
-    try {
-      return typeof window !== 'undefined'
-        ? parseDebugFlags(window.location.search)
-        : { enabled: false } as DebugFlags;
-    } catch {
-      return { enabled: false } as DebugFlags;
-    }
-  }, []);
-
-  const [manualEnabled, setManualEnabled] = useState<boolean | null>(null);
-
-  // Effective enabled: manual override wins, then URL flags
-  const enabled = manualEnabled !== null ? manualEnabled : urlFlags.enabled;
-
-  // Flags reflect URL-parsed flags plus effective enabled state
-  const flags: DebugFlags = useMemo(
-    () => ({ ...urlFlags, enabled }),
-    [urlFlags, enabled],
-  );
-
-  const toggle = useCallback(() => {
-    setManualEnabled((prev) => {
-      if (prev === null) return !urlFlags.enabled;
-      return !prev;
-    });
-  }, [urlFlags.enabled]);
-
-  const setEnabled = useCallback((value: boolean) => {
-    setManualEnabled(value);
-  }, []);
-
-  // Ctrl+Shift+D keyboard shortcut
-  useEffect(() => {
-    if (typeof window === 'undefined') return;
-
-    const handler = (e: KeyboardEvent) => {
-      if (e.ctrlKey && e.shiftKey && e.key === 'D') {
-        e.preventDefault();
-        toggle();
-      }
-    };
-    document.addEventListener('keydown', handler);
-    return () => document.removeEventListener('keydown', handler);
-  }, [toggle]);
-
-  return { enabled, flags, toggle, setEnabled };
-}