@object-ui/plugin-aggrid 0.4.0 → 0.5.0

package/README.md

@@ -31,6 +31,21 @@ pnpm add @object-ui/plugin-aggrid ag-grid-community ag-grid-react
 
 Note: `ag-grid-community` and `ag-grid-react` are peer dependencies and must be installed separately.
 
+### Next.js App Router Setup
+
+If you're using Next.js with the App Router and dynamic imports, you may need to import AG Grid CSS in your root layout to ensure styles load correctly:
+
+```typescript
+// app/layout.tsx
+import 'ag-grid-community/styles/ag-grid.css';
+import 'ag-grid-community/styles/ag-theme-quartz.css';
+import 'ag-grid-community/styles/ag-theme-alpine.css';
+import 'ag-grid-community/styles/ag-theme-balham.css';
+import 'ag-grid-community/styles/ag-theme-material.css';
+```
+
+This is necessary when the plugin is loaded dynamically (e.g., via `React.lazy()` or dynamic imports in client components), as Next.js may not properly process CSS imports from dynamically loaded modules.
+
 ## Usage
 
 ### Automatic Registration (Side-Effect Import)
@@ -497,7 +512,212 @@ pnpm type-check
 
 MIT
 
-## Resources
+## Object AgGrid - Metadata-Driven AG Grid
+
+The `object-aggrid` component extends the standard `aggrid` with metadata-driven capabilities using `@objectstack/client`. It automatically fetches object schemas and data, and generates appropriate column definitions based on field types.
+
+### Features
+
+- **Automatic Metadata Fetching**: Retrieves object schema from ObjectStack backend
+- **Automatic Data Loading**: Fetches data with pagination, filtering, and sorting
+- **Field Type Support**: Supports all ObjectUI field types with appropriate formatters and renderers
+- **Inline Editing**: Automatically saves changes to the backend
+- **Zero Column Configuration**: Columns are generated from metadata
+- **Selective Field Display**: Optionally show only specific fields
+
+### Installation
+
+```bash
+pnpm add @object-ui/plugin-aggrid @object-ui/data-objectstack ag-grid-community ag-grid-react
+```
+
+### Usage
+
+```typescript
+import '@object-ui/plugin-aggrid';
+import { ObjectStackAdapter } from '@object-ui/data-objectstack';
+
+// Create data source
+const dataSource = new ObjectStackAdapter({
+  baseUrl: 'https://api.example.com',
+  token: 'your-api-token'
+});
+
+// Use in schema
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'contacts',  // Object to fetch
+  dataSource: dataSource,  // ObjectStack data source
+  pagination: true,
+  pageSize: 20,
+  theme: 'quartz',
+  height: 600
+};
+```
+
+### Supported Field Types
+
+The component automatically applies appropriate formatters and cell renderers for all field types:
+
+- **Text Types**: text, textarea, markdown, html
+- **Numeric Types**: number, currency (with locale formatting), percent
+- **Boolean**: Displays ✓ Yes / ✗ No
+- **Date/Time**: date, datetime, time (with locale formatting)
+- **Contact**: email (clickable mailto), phone (clickable tel), url (clickable link)
+- **Select/Lookup**: select, lookup, master_detail (shows labels)
+- **Visual**: color (with color swatch), image, avatar, rating (stars)
+- **Advanced**: formula, summary, auto_number, user, file
+
+### Schema API for Object AgGrid
+
+```typescript
+{
+  type: 'object-aggrid',
+  
+  // Required
+  objectName: string,              // Name of the object to fetch
+  dataSource: DataSource,          // ObjectStack data source instance
+  
+  // Optional Field Configuration
+  fieldNames?: string[],           // Show only these fields (default: all)
+  fields?: FieldMetadata[],        // Override field metadata
+  
+  // Query Parameters
+  filters?: Record<string, any>,   // Query filters
+  sort?: Record<string, 'asc' | 'desc'>, // Sorting
+  pageSize?: number,               // Rows per page (default: 10)
+  
+  // Display Options (same as aggrid)
+  pagination?: boolean,            // Enable pagination (default: true)
+  theme?: string,                  // Grid theme (default: 'quartz')
+  height?: number | string,        // Grid height (default: 500)
+  
+  // Editing
+  editable?: boolean,              // Enable inline editing (auto-saves to backend)
+  
+  // Export, Status Bar, Callbacks, etc. (same as aggrid)
+  exportConfig?: ExportConfig,
+  statusBar?: StatusBarConfig,
+  columnConfig?: ColumnConfig,
+  callbacks?: {
+    onDataLoaded?: (data: any[]) => void,
+    onDataError?: (error: Error) => void,
+    // ... other aggrid callbacks
+  }
+}
+```
+
+### Examples
+
+#### Basic Usage
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'users',
+  dataSource: myDataSource,
+  pagination: true,
+  pageSize: 25
+};
+```
+
+#### With Field Selection
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'contacts',
+  dataSource: myDataSource,
+  fieldNames: ['name', 'email', 'phone', 'company'],
+  pagination: true
+};
+```
+
+#### With Filters and Sorting
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'products',
+  dataSource: myDataSource,
+  filters: {
+    category: 'Electronics',
+    price: { $lt: 1000 }
+  },
+  sort: {
+    price: 'asc'
+  },
+  pagination: true
+};
+```
+
+#### Editable Grid with Auto-Save
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'tasks',
+  dataSource: myDataSource,
+  editable: true,               // Enable editing
+  singleClickEdit: true,        // Single-click to edit
+  callbacks: {
+    onCellValueChanged: (event) => {
+      // Changes are automatically saved to backend
+      console.log('Saved:', event.data);
+    }
+  }
+};
+```
+
+#### With Export
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'sales',
+  dataSource: myDataSource,
+  exportConfig: {
+    enabled: true,
+    fileName: 'sales-report.csv'
+  }
+};
+```
+
+### Field Type Formatting Examples
+
+**Currency Field:**
+```typescript
+// Schema defines: { type: 'currency', currency: 'USD', precision: 2 }
+// Renders as: $1,234.56
+```
+
+**Percent Field:**
+```typescript
+// Schema defines: { type: 'percent', precision: 1 }
+// Renders as: 45.5%
+```
+
+**Email Field:**
+```typescript
+// Schema defines: { type: 'email' }
+// Renders as: <a href="mailto:user@example.com">user@example.com</a>
+```
+
+**Rating Field:**
+```typescript
+// Schema defines: { type: 'rating', max: 5 }
+// Renders as: ⭐⭐⭐⭐⭐
+```
+
+**Color Field:**
+```typescript
+// Schema defines: { type: 'color' }
+// Renders as: [color swatch] #FF5733
+```
+
+## License
+
+
 
 - [AG Grid Community Documentation](https://www.ag-grid.com/documentation/)
 - [AG Grid Column Definitions](https://www.ag-grid.com/documentation/javascript/column-definitions/)

package/dist/{AgGridImpl-DKkq6v1B.js → AgGridImpl-BQ6tBvrq.js}

@@ -1,35 +1,35 @@
-import { j as u } from "./index-B6NPAFZx.js";
-import { useRef as J, useMemo as p, useCallback as i } from "react";
-import { AgGridReact as K } from "ag-grid-react";
-function Y({
-  rowData: f = [],
-  columnDefs: c = [],
-  gridOptions: v = {},
+import { j as d } from "./index-CLKYMco3.js";
+import { useRef as O, useMemo as f, useCallback as i } from "react";
+import { AgGridReact as Q } from "ag-grid-react";
+function Z({
+  rowData: u = [],
+  columnDefs: g = [],
+  gridOptions: m = {},
   pagination: x = !1,
-  paginationPageSize: P = 10,
-  domLayout: A = "normal",
-  animateRows: b = !0,
+  paginationPageSize: b = 10,
+  domLayout: P = "normal",
+  animateRows: A = !0,
   rowSelection: S,
   theme: H = "quartz",
-  height: d = 500,
-  className: O = "",
-  editable: m = !1,
+  height: c = 500,
+  className: B = "",
+  editable: p = !1,
   editType: j,
   singleClickEdit: y = !1,
   stopEditingWhenCellsLoseFocus: R = !0,
   exportConfig: o,
-  statusBar: g,
+  statusBar: h,
   callbacks: t,
   columnConfig: a,
-  enableRangeSelection: z = !1,
-  enableCharts: E = !1,
+  enableRangeSelection: V = !1,
+  enableCharts: z = !1,
   contextMenu: l
 }) {
-  const n = J(null), h = p(() => {
-    if (!g?.enabled) return;
-    const e = g.aggregations || ["count", "sum", "avg"], s = [];
+  const n = O(null), C = f(() => {
+    if (!h?.enabled) return;
+    const e = h.aggregations || ["count", "sum", "avg"], s = [];
     return e.includes("count") && s.push({ statusPanel: "agAggregationComponent", statusPanelParams: { aggFuncs: ["count"] } }), e.includes("sum") && s.push({ statusPanel: "agAggregationComponent", statusPanelParams: { aggFuncs: ["sum"] } }), e.includes("avg") && s.push({ statusPanel: "agAggregationComponent", statusPanelParams: { aggFuncs: ["avg"] } }), e.includes("min") && s.push({ statusPanel: "agAggregationComponent", statusPanelParams: { aggFuncs: ["min"] } }), e.includes("max") && s.push({ statusPanel: "agAggregationComponent", statusPanelParams: { aggFuncs: ["max"] } }), s;
-  }, [g]), C = i(() => {
+  }, [h]), v = i(() => {
     if (!n.current?.api) return;
     const e = {
       fileName: o?.fileName || "export.csv",
@@ -38,17 +38,17 @@ function Y({
       onlySelected: o?.onlySelected || !1
     };
     if (n.current.api.exportDataAsCsv(e), t?.onExport) {
-      const s = o?.onlySelected ? n.current.api.getSelectedRows() : f;
+      const s = o?.onlySelected ? n.current.api.getSelectedRows() : u;
       t.onExport(s || [], "csv");
     }
-  }, [o, t, f]), N = i((e) => {
+  }, [o, t, u]), E = i((e) => {
     if (!l?.enabled) return [];
     const s = [];
     return (l.items || ["copy", "copyWithHeaders", "separator", "export"]).forEach((r) => {
       r === "export" ? s.push({
         name: "Export CSV",
         icon: "<span>📥</span>",
-        action: () => C()
+        action: () => v()
       }) : r === "autoSizeAll" ? s.push({
         name: "Auto-size All Columns",
         action: () => {
@@ -69,7 +69,7 @@ function Y({
         }
       });
     })), s;
-  }, [l, C, t]), V = i((e) => {
+  }, [l, v, t]), N = i((e) => {
     t?.onCellClicked?.(e);
   }, [t]), F = i((e) => {
     t?.onRowClicked?.(e);
@@ -79,85 +79,89 @@ function Y({
     t?.onCellValueChanged?.(e);
   }, [t]), G = i((e) => {
     n.current = e;
-  }, []), $ = p(() => c ? c.map((e) => {
+  }, []), $ = f(() => g ? g.map((e) => {
     const s = { ...e };
-    return m && e.editable !== !1 && (s.editable = !0), a && (a.resizable !== void 0 && e.resizable === void 0 && (s.resizable = a.resizable), a.sortable !== void 0 && e.sortable === void 0 && (s.sortable = a.sortable), a.filterable !== void 0 && e.filter === void 0 && (s.filter = a.filterable)), s;
-  }) : [], [c, m, a]), q = p(() => ({
-    ...v,
+    return p && e.editable !== !1 && (s.editable = !0), a && (a.resizable !== void 0 && e.resizable === void 0 && (s.resizable = a.resizable), a.sortable !== void 0 && e.sortable === void 0 && (s.sortable = a.sortable), a.filterable !== void 0 && e.filter === void 0 && (s.filter = a.filterable)), s;
+  }) : [], [g, p, a]), q = f(() => ({
+    ...m,
     pagination: x,
-    paginationPageSize: P,
-    domLayout: A,
-    animateRows: b,
+    paginationPageSize: b,
+    domLayout: P,
+    animateRows: A,
     rowSelection: S,
     editType: j,
     singleClickEdit: y,
     stopEditingWhenCellsLoseFocus: R,
-    statusBar: h ? { statusPanels: h } : void 0,
-    enableRangeSelection: z,
-    enableCharts: E,
-    getContextMenuItems: l?.enabled ? N : void 0,
+    statusBar: C ? { statusPanels: C } : void 0,
+    enableRangeSelection: V,
+    enableCharts: z,
+    getContextMenuItems: l?.enabled ? E : void 0,
     // Default options for better UX
-    suppressCellFocus: !m,
+    suppressCellFocus: !p,
     enableCellTextSelection: !0,
     ensureDomOrder: !0,
+    // Virtual scrolling optimizations for large datasets
+    rowBuffer: m.rowBuffer ?? 10,
+    debounceVerticalScrollbar: m.debounceVerticalScrollbar ?? u.length > 1e3,
     // Event handlers
-    onCellClicked: V,
+    onCellClicked: N,
     onRowClicked: F,
     onSelectionChanged: I,
     onCellValueChanged: w,
     onGridReady: G
   }), [
-    v,
+    m,
     x,
+    b,
     P,
     A,
-    b,
     S,
     j,
     y,
     R,
-    h,
+    C,
+    V,
     z,
-    E,
     l,
+    E,
+    p,
+    u.length,
     N,
-    m,
-    V,
     F,
     I,
     w,
     G
-  ]), B = p(() => ({
-    height: typeof d == "number" ? `${d}px` : d,
+  ]), J = f(() => ({
+    height: typeof c == "number" ? `${c}px` : c,
     width: "100%"
-  }), [d]), D = [
+  }), [c]), K = [
     `ag-theme-${H}`,
     "rounded-xl",
     "border",
     "border-border",
     "overflow-hidden",
     "shadow-lg",
-    O
+    B
   ].filter(Boolean).join(" ");
-  return /* @__PURE__ */ u.jsxs("div", { className: "ag-grid-container", children: [
-    o?.enabled && /* @__PURE__ */ u.jsx("div", { className: "mb-2 flex gap-2", children: /* @__PURE__ */ u.jsx(
+  return /* @__PURE__ */ d.jsxs("div", { className: "ag-grid-container", children: [
+    o?.enabled && /* @__PURE__ */ d.jsx("div", { className: "mb-2 flex gap-2", children: /* @__PURE__ */ d.jsx(
       "button",
       {
-        onClick: C,
+        onClick: v,
         className: "px-3 py-1.5 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-md transition-colors",
         children: "Export CSV"
       }
     ) }),
-    /* @__PURE__ */ u.jsx(
+    /* @__PURE__ */ d.jsx(
       "div",
       {
-        className: D,
-        style: B,
-        children: /* @__PURE__ */ u.jsx(
-          K,
+        className: K,
+        style: J,
+        children: /* @__PURE__ */ d.jsx(
+          Q,
           {
             ref: n,
-            rowData: f,
+            rowData: u,
             columnDefs: $,
             gridOptions: q
           }
@@ -167,5 +171,5 @@ function Y({
   ] });
 }
 export {
-  Y as default
+  Z as default
 };