@object-ui/components 3.0.3 → 3.1.1

package/src/hooks/use-config-draft.ts

@@ -0,0 +1,127 @@
+/**
+ * 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, useRef } from 'react';
+
+export interface UseConfigDraftOptions {
+  /** Panel mode: 'create' starts dirty; 'edit' starts clean */
+  mode?: 'create' | 'edit';
+  /** Optional callback invoked on every field change */
+  onUpdate?: (field: string, value: any) => void;
+  /** Maximum undo history size (default: 50) */
+  maxHistory?: number;
+}
+
+export interface UseConfigDraftReturn<T extends Record<string, any>> {
+  /** The mutable draft copy */
+  draft: T;
+  /** Whether the draft differs from the source */
+  isDirty: boolean;
+  /** Update a single field in the draft */
+  updateField: (field: string, value: any) => void;
+  /** Revert draft back to source */
+  discard: () => void;
+  /** Low-level setter (use updateField for individual changes) */
+  setDraft: React.Dispatch<React.SetStateAction<T>>;
+  /** Undo the last change */
+  undo: () => void;
+  /** Redo a previously undone change */
+  redo: () => void;
+  /** Whether undo is available */
+  canUndo: boolean;
+  /** Whether redo is available */
+  canRedo: boolean;
+}
+
+/**
+ * Generic draft-state management for configuration panels.
+ *
+ * Mirrors the proven draft → save / discard pattern from ViewConfigPanel
+ * while being reusable across Dashboard, Form, Page, Report, and any
+ * future config panel. Includes undo/redo history support.
+ *
+ * @param source - The "committed" configuration object.
+ * @param options - Optional mode and change callback.
+ */
+export function useConfigDraft<T extends Record<string, any>>(
+  source: T,
+  options?: UseConfigDraftOptions,
+): UseConfigDraftReturn<T> {
+  const maxHistory = options?.maxHistory ?? 50;
+  const [draft, setDraft] = useState<T>({ ...source });
+  const [isDirty, setIsDirty] = useState(options?.mode === 'create');
+  const pastRef = useRef<T[]>([]);
+  const futureRef = useRef<T[]>([]);
+  const [, forceRender] = useState(0);
+
+  // Reset draft when source identity changes
+  useEffect(() => {
+    setDraft({ ...source });
+    setIsDirty(options?.mode === 'create');
+    pastRef.current = [];
+    futureRef.current = [];
+  }, [source]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const updateField = useCallback(
+    (field: string, value: any) => {
+      setDraft((prev) => {
+        pastRef.current = [...pastRef.current.slice(-(maxHistory - 1)), prev];
+        futureRef.current = [];
+        return { ...prev, [field]: value };
+      });
+      setIsDirty(true);
+      forceRender((n) => n + 1);
+      options?.onUpdate?.(field, value);
+    },
+    [options?.onUpdate, maxHistory], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+
+  const undo = useCallback(() => {
+    if (pastRef.current.length === 0) return;
+    setDraft((prev) => {
+      const past = [...pastRef.current];
+      const previous = past.pop()!;
+      pastRef.current = past;
+      futureRef.current = [prev, ...futureRef.current];
+      return previous;
+    });
+    forceRender((n) => n + 1);
+  }, []);
+
+  const redo = useCallback(() => {
+    if (futureRef.current.length === 0) return;
+    setDraft((prev) => {
+      const future = [...futureRef.current];
+      const next = future.shift()!;
+      futureRef.current = future;
+      pastRef.current = [...pastRef.current, prev];
+      return next;
+    });
+    forceRender((n) => n + 1);
+  }, []);
+
+  const discard = useCallback(() => {
+    setDraft({ ...source });
+    setIsDirty(false);
+    pastRef.current = [];
+    futureRef.current = [];
+    forceRender((n) => n + 1);
+  }, [source]);
+
+  return {
+    draft,
+    isDirty,
+    updateField,
+    discard,
+    setDraft,
+    undo,
+    redo,
+    canUndo: pastRef.current.length > 0,
+    canRedo: futureRef.current.length > 0,
+  };
+}

package/src/index.css

@@ -74,11 +74,15 @@
 
   --radius: 0.5rem;
 
+  --config-panel-width: 320px;
+
   --chart-1: 12 76% 61%;
   --chart-2: 173 58% 39%;
   --chart-3: 197 37% 24%;
   --chart-4: 43 74% 66%;
   --chart-5: 27 87% 67%;
+
+  font-family: 'Inter', ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
 }
 
 .dark {

package/src/index.ts

@@ -23,6 +23,18 @@ export { registerPlaceholders } from './renderers/placeholders';
 export * from './ui';
 export * from './custom';
 
+// Export hooks
+export { useConfigDraft } from './hooks/use-config-draft';
+export type { UseConfigDraftOptions, UseConfigDraftReturn } from './hooks/use-config-draft';
+
+// Export config panel types
+export type {
+  ControlType,
+  ConfigField,
+  ConfigSection,
+  ConfigPanelSchema,
+} from './types/config-panel';
+
 // Export an init function to ensure components are registered
 // This is a workaround for bundlers that might tree-shake side-effect imports
 export function initializeComponents() {
@@ -30,3 +42,6 @@ export function initializeComponents() {
   // Simply importing this module should register all components
   return true;
 }
+
+// Debug panel (tree-shakeable — only included when imported)
+export * from './debug';

package/src/renderers/action/action-bar.tsx

@@ -0,0 +1,221 @@
+/**
+ * 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.
+ */
+
+/**
+ * action:bar — Location-aware action toolbar.
+ *
+ * Renders a set of ActionSchema items filtered by a given location.
+ * Each action is rendered using its `component` type (action:button, action:icon,
+ * action:menu, action:group) via the ComponentRegistry. Actions beyond the
+ * `maxVisible` threshold are grouped into an overflow "More" dropdown.
+ *
+ * This is the "bridge" component that connects ActionSchema metadata to the UI,
+ * enabling server-driven action rendering at list_toolbar, record_header,
+ * list_item, record_more, record_related, and global_nav locations.
+ *
+ * @example
+ * ```tsx
+ * <SchemaRenderer schema={{
+ *   type: 'action:bar',
+ *   location: 'record_header',
+ *   actions: [
+ *     { name: 'mark_complete', label: 'Mark Complete', type: 'script', icon: 'check', component: 'action:button' },
+ *     { name: 'delete', label: 'Delete', type: 'api', icon: 'trash-2', variant: 'destructive', component: 'action:button' },
+ *   ],
+ * }} />
+ * ```
+ */
+
+import React, { forwardRef, useMemo } from 'react';
+import { ComponentRegistry } from '@object-ui/core';
+import type { ActionSchema, ActionLocation, ActionComponent } from '@object-ui/types';
+import { useCondition } from '@object-ui/react';
+import { cn } from '../../lib/utils';
+import { useIsMobile } from '../../hooks/use-mobile';
+
+export interface ActionBarSchema {
+  type: 'action:bar';
+  /** Actions to render */
+  actions?: ActionSchema[];
+  /** Filter actions by this location */
+  location?: ActionLocation;
+  /** Maximum visible inline actions before overflow into "More" menu (default: 3) */
+  maxVisible?: number;
+  /** Maximum visible inline actions on mobile devices (default: 1). Desktop uses maxVisible instead. */
+  mobileMaxVisible?: number;
+  /** Visibility condition expression */
+  visible?: string;
+  /** Layout direction */
+  direction?: 'horizontal' | 'vertical';
+  /** Gap between items (Tailwind gap class, default: 'gap-2') */
+  gap?: string;
+  /** Button variant for all actions (can be overridden per-action) */
+  variant?: string;
+  /** Button size for all actions (can be overridden per-action) */
+  size?: string;
+  /** Custom CSS class */
+  className?: string;
+  [key: string]: any;
+}
+
+const ActionBarRenderer = forwardRef<HTMLDivElement, { schema: ActionBarSchema; [key: string]: any }>(
+  ({ schema, className, ...props }, ref) => {
+    const {
+      'data-obj-id': dataObjId,
+      'data-obj-type': dataObjType,
+      style,
+      data,
+      ...rest
+    } = props;
+
+    const isVisible = useCondition(schema.visible ? `\${${schema.visible}}` : undefined);
+    const isMobile = useIsMobile();
+
+    // Filter actions by location and deduplicate by name
+    const filteredActions = useMemo(() => {
+      const actions = schema.actions || [];
+      const located = !schema.location
+        ? actions
+        : actions.filter(
+            a => !a.locations || a.locations.length === 0 || a.locations.includes(schema.location!),
+          );
+      // Deduplicate by action name — keep first occurrence
+      const seen = new Set<string>();
+      return located.filter(a => {
+        if (!a.name) return true;
+        if (seen.has(a.name)) return false;
+        seen.add(a.name);
+        return true;
+      });
+    }, [schema.actions, schema.location]);
+
+    // Split into visible inline actions and overflow
+    // On mobile, show fewer actions inline (default: 1)
+    const maxVisible = isMobile
+      ? (schema.mobileMaxVisible ?? 1)
+      : (schema.maxVisible ?? 3);
+    const { inlineActions, overflowActions } = useMemo(() => {
+      if (filteredActions.length <= maxVisible) {
+        return { inlineActions: filteredActions, overflowActions: [] as ActionSchema[] };
+      }
+      return {
+        inlineActions: filteredActions.slice(0, maxVisible),
+        overflowActions: filteredActions.slice(maxVisible),
+      };
+    }, [filteredActions, maxVisible]);
+
+    if (schema.visible && !isVisible) return null;
+    if (filteredActions.length === 0) return null;
+
+    const direction = schema.direction || 'horizontal';
+    const gap = schema.gap || 'gap-2';
+
+    // Render overflow menu for excess actions
+    const MenuRenderer = overflowActions.length > 0 ? ComponentRegistry.get('action:menu') : null;
+    const overflowMenu = MenuRenderer ? (
+      <MenuRenderer
+        schema={{
+          type: 'action:menu' as const,
+          actions: overflowActions,
+          variant: schema.variant || 'ghost',
+          size: schema.size || 'sm',
+        }}
+      />
+    ) : null;
+
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex items-center',
+          direction === 'vertical' ? 'flex-col items-stretch' : 'flex-row flex-wrap',
+          gap,
+          schema.className,
+          className,
+        )}
+        role="toolbar"
+        aria-label="Actions"
+        {...rest}
+        {...{ 'data-obj-id': dataObjId, 'data-obj-type': dataObjType, style }}
+      >
+        {inlineActions.map((action) => {
+          const componentType: ActionComponent = action.component || 'action:button';
+          const Renderer = ComponentRegistry.get(componentType);
+          if (!Renderer) return null;
+
+          return (
+            <Renderer
+              key={action.name}
+              schema={{
+                ...action,
+                type: componentType,
+                actionType: action.type,
+                variant: action.variant || schema.variant,
+                size: action.size || schema.size,
+              }}
+              data={data}
+            />
+          );
+        })}
+
+        {overflowActions.length > 0 && overflowMenu}
+      </div>
+    );
+  },
+);
+
+ActionBarRenderer.displayName = 'ActionBarRenderer';
+
+ComponentRegistry.register('action:bar', ActionBarRenderer, {
+  namespace: 'action',
+  label: 'Action Bar',
+  inputs: [
+    { name: 'actions', type: 'object', label: 'Actions' },
+    {
+      name: 'location',
+      type: 'enum',
+      label: 'Location',
+      enum: ['list_toolbar', 'list_item', 'record_header', 'record_more', 'record_related', 'global_nav'],
+    },
+    {
+      name: 'maxVisible',
+      type: 'number',
+      label: 'Max Visible Actions',
+      defaultValue: 3,
+    },
+    {
+      name: 'direction',
+      type: 'enum',
+      label: 'Direction',
+      enum: ['horizontal', 'vertical'],
+      defaultValue: 'horizontal',
+    },
+    {
+      name: 'variant',
+      type: 'enum',
+      label: 'Default Variant',
+      enum: ['default', 'secondary', 'outline', 'ghost'],
+      defaultValue: 'outline',
+    },
+    {
+      name: 'size',
+      type: 'enum',
+      label: 'Default Size',
+      enum: ['sm', 'md', 'lg'],
+      defaultValue: 'sm',
+    },
+    { name: 'className', type: 'string', label: 'CSS Class', advanced: true },
+  ],
+  defaultProps: {
+    maxVisible: 3,
+    direction: 'horizontal',
+    variant: 'outline',
+    size: 'sm',
+    actions: [],
+  },
+});

package/src/renderers/action/action-button.tsx

@@ -28,7 +28,7 @@ import { Loader2 } from 'lucide-react';
 import { resolveIcon } from './resolve-icon';
 
 export interface ActionButtonProps {
-  schema: ActionSchema & { type: string; className?: string };
+  schema: ActionSchema & { type: string; className?: string; actionType?: string };
   className?: string;
   /** Override context for this specific action */
   context?: Record<string, any>;
@@ -41,15 +41,19 @@ const ActionButtonRenderer = forwardRef<HTMLButtonElement, ActionButtonProps>(
       'data-obj-id': dataObjId,
       'data-obj-type': dataObjType,
       style,
+      data,
       ...rest
     } = props;
 
     const { execute } = useAction();
     const [loading, setLoading] = useState(false);
 
-    // Evaluate visibility and enabled conditions
-    const isVisible = useCondition(schema.visible ? `\${${schema.visible}}` : undefined);
-    const isEnabled = useCondition(schema.enabled ? `\${${schema.enabled}}` : undefined);
+    // Record data may be passed from SchemaRenderer (e.g. DetailView passes record data)
+    const recordData = data != null && typeof data === 'object' ? data as Record<string, any> : {};
+
+    // Evaluate visibility and enabled conditions with record data context
+    const isVisible = useCondition(schema.visible ? `\${${schema.visible}}` : undefined, recordData);
+    const isEnabled = useCondition(schema.enabled ? `\${${schema.enabled}}` : undefined, recordData);
 
     // Resolve icon
     const Icon = resolveIcon(schema.icon);
@@ -63,14 +67,21 @@ const ActionButtonRenderer = forwardRef<HTMLButtonElement, ActionButtonProps>(
       setLoading(true);
 
       try {
+        // Route params correctly:
+        // - Array of objects with name+type → ActionParamDef[] → pass as actionParams for collection
+        // - Otherwise → pass as actual param values
+        const paramsPayload = Array.isArray(schema.params)
+          ? { actionParams: schema.params as any }
+          : { params: schema.params as Record<string, any> | undefined };
+
         await execute({
-          type: schema.type,
+          type: schema.actionType || schema.type,
           name: schema.name,
           target: schema.target,
           execute: schema.execute,
           endpoint: schema.endpoint,
           method: schema.method,
-          params: schema.params as Record<string, any> | undefined,
+          ...paramsPayload,
           confirmText: schema.confirmText,
           successMessage: schema.successMessage,
           errorMessage: schema.errorMessage,

package/src/renderers/action/index.ts

@@ -16,3 +16,4 @@ import './action-button';
 import './action-icon';
 import './action-menu';
 import './action-group';
+import './action-bar';

package/src/renderers/complex/__tests__/data-table-airtable-ux.test.tsx

@@ -0,0 +1,239 @@
+/**
+ * Data Table - Airtable UX Enhancements Tests
+ *
+ * Tests for row hover expand button, column header context menu,
+ * and hide column functionality.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import React from 'react';
+import { SchemaRenderer } from '@object-ui/react';
+
+// Import data-table to ensure it's registered
+import '../data-table';
+
+const baseSchema = {
+  type: 'data-table',
+  columns: [
+    { header: 'Name', accessorKey: 'name' },
+    { header: 'Email', accessorKey: 'email' },
+    { header: 'Role', accessorKey: 'role' },
+  ],
+  data: [
+    { id: 1, name: 'Alice', email: 'alice@test.com', role: 'Admin' },
+    { id: 2, name: 'Bob', email: 'bob@test.com', role: 'User' },
+  ],
+  pagination: false,
+  searchable: false,
+  showRowNumbers: true,
+};
+
+// =========================================================================
+// 1. Row hover expand button
+// =========================================================================
+describe('Row hover expand button', () => {
+  it('should render expand buttons on rows when onRowClick is configured', async () => {
+    const onRowClick = vi.fn();
+    render(
+      <SchemaRenderer
+        schema={{ ...baseSchema, onRowClick }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    // Expand buttons should exist (hidden via CSS, visible on hover)
+    const expandButtons = screen.getAllByTestId('row-expand-button');
+    expect(expandButtons.length).toBe(2);
+  });
+
+  it('should not render expand buttons when onRowClick is not configured', async () => {
+    render(<SchemaRenderer schema={baseSchema} />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    expect(screen.queryAllByTestId('row-expand-button')).toHaveLength(0);
+  });
+
+  it('should call onRowClick when expand button is clicked', async () => {
+    const onRowClick = vi.fn();
+    render(
+      <SchemaRenderer
+        schema={{ ...baseSchema, onRowClick }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    const expandButtons = screen.getAllByTestId('row-expand-button');
+    fireEvent.click(expandButtons[0]);
+
+    expect(onRowClick).toHaveBeenCalledTimes(1);
+    expect(onRowClick).toHaveBeenCalledWith(
+      expect.objectContaining({ name: 'Alice' })
+    );
+  });
+});
+
+// =========================================================================
+// 2. Column header context menu
+// =========================================================================
+describe('Column header context menu', () => {
+  it('should show context menu on right-click of column header', async () => {
+    render(<SchemaRenderer schema={baseSchema} />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Name')).toBeInTheDocument();
+    });
+
+    // Right-click on the "Name" column header
+    const nameHeader = screen.getByText('Name').closest('th');
+    expect(nameHeader).toBeTruthy();
+    fireEvent.contextMenu(nameHeader!);
+
+    // Context menu should appear
+    await waitFor(() => {
+      expect(screen.getByTestId('column-context-menu')).toBeInTheDocument();
+    });
+
+    // Should contain Sort and Hide options
+    expect(screen.getByText('Sort ascending')).toBeInTheDocument();
+    expect(screen.getByText('Sort descending')).toBeInTheDocument();
+    expect(screen.getByText('Hide column')).toBeInTheDocument();
+  });
+
+  it('should hide column when "Hide column" is clicked', async () => {
+    render(<SchemaRenderer schema={baseSchema} />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Email')).toBeInTheDocument();
+    });
+
+    // Right-click on the "Email" column header
+    const emailHeader = screen.getByText('Email').closest('th');
+    fireEvent.contextMenu(emailHeader!);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('column-context-menu')).toBeInTheDocument();
+    });
+
+    // Click "Hide column"
+    fireEvent.click(screen.getByText('Hide column'));
+
+    // The "Email" column should no longer be visible
+    await waitFor(() => {
+      expect(screen.queryByText('Email')).not.toBeInTheDocument();
+    });
+
+    // Other columns should still be visible
+    expect(screen.getByText('Name')).toBeInTheDocument();
+    expect(screen.getByText('Role')).toBeInTheDocument();
+  });
+
+  it('should sort ascending when "Sort ascending" is clicked from context menu', async () => {
+    render(
+      <SchemaRenderer
+        schema={{
+          ...baseSchema,
+          sortable: true,
+        }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Name')).toBeInTheDocument();
+    });
+
+    // Right-click on the "Name" column header
+    const nameHeader = screen.getByText('Name').closest('th');
+    fireEvent.contextMenu(nameHeader!);
+
+    await waitFor(() => {
+      expect(screen.getByTestId('column-context-menu')).toBeInTheDocument();
+    });
+
+    // Click "Sort ascending"
+    fireEvent.click(screen.getByText('Sort ascending'));
+
+    // Context menu should close
+    await waitFor(() => {
+      expect(screen.queryByTestId('column-context-menu')).not.toBeInTheDocument();
+    });
+  });
+});
+
+// =========================================================================
+// 3. Group/row hover styling
+// =========================================================================
+describe('Row group hover class', () => {
+  it('should apply group/row hover class to table rows', async () => {
+    render(<SchemaRenderer schema={baseSchema} />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    // Data rows should have group/row class for hover effects
+    const aliceRow = screen.getByText('Alice').closest('tr');
+    expect(aliceRow).toHaveClass('group/row');
+  });
+});
+
+// =========================================================================
+// 5. Filler rows behavior
+// =========================================================================
+describe('Filler rows', () => {
+  it('should not render filler rows when pagination is disabled', async () => {
+    // pagination: false with pageSize: 10 and only 2 data rows
+    // should NOT produce empty filler rows
+    render(
+      <SchemaRenderer
+        schema={{ ...baseSchema, pagination: false, pageSize: 10 }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    const table = screen.getByRole('table');
+    const tbody = table.querySelector('tbody');
+    const allRows = tbody!.querySelectorAll('tr');
+
+    // Should only have data rows (2) + add-record row if any, no filler rows
+    // With 2 data items and no add-record, expect exactly 2 rows
+    const fillerRows = Array.from(allRows).filter(
+      (row) => row.querySelector('td[class*="p-0"]') && row.textContent === ''
+    );
+    expect(fillerRows).toHaveLength(0);
+  });
+
+  it('should render filler rows when pagination is enabled and page is not full', async () => {
+    render(
+      <SchemaRenderer
+        schema={{ ...baseSchema, pagination: true, pageSize: 5, searchable: false }}
+      />
+    );
+
+    await waitFor(() => {
+      expect(screen.getByText('Alice')).toBeInTheDocument();
+    });
+
+    const table = screen.getByRole('table');
+    const tbody = table.querySelector('tbody');
+    const allRows = tbody!.querySelectorAll('tr');
+
+    // With 2 data rows and pageSize 5, expect 3 filler rows (5 - 2 = 3)
+    const fillerRows = Array.from(allRows).filter(
+      (row) => row.querySelector('td[class*="p-0"]') && row.textContent === ''
+    );
+    expect(fillerRows).toHaveLength(3);
+  });
+});