@object-ui/plugin-aggrid 0.4.1 → 2.0.0

package/QUICKSTART.md

@@ -0,0 +1,186 @@
+# Quick Start Guide - ObjectAgGrid
+
+## Installation
+
+The ObjectAgGrid component is already installed as part of the @object-ui/plugin-aggrid package.
+
+## Basic Usage
+
+### Step 1: Import Required Packages
+
+```typescript
+import { ObjectStackAdapter } from '@object-ui/data-objectstack';
+import '@object-ui/plugin-aggrid';  // Auto-registers the component
+```
+
+### Step 2: Create a Data Source
+
+```typescript
+const dataSource = new ObjectStackAdapter({
+  baseUrl: 'https://your-api.example.com',
+  token: 'your-auth-token'  // Optional
+});
+```
+
+### Step 3: Define Your Schema
+
+```typescript
+const gridSchema = {
+  type: 'object-aggrid',
+  objectName: 'contacts',  // The object to fetch from your backend
+  dataSource: dataSource,
+  pagination: true,
+  pageSize: 20,
+  theme: 'quartz',
+  height: 600
+};
+```
+
+### Step 4: Use in Your Component
+
+```typescript
+import { SchemaRenderer } from '@object-ui/components';
+
+function MyComponent() {
+  return (
+    <div>
+      <h1>My Contacts</h1>
+      <SchemaRenderer schema={gridSchema} />
+    </div>
+  );
+}
+```
+
+## Common Use Cases
+
+### Show Only Specific Fields
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'contacts',
+  dataSource: dataSource,
+  fieldNames: ['name', 'email', 'phone', 'company'],  // Only show these
+  pagination: true
+};
+```
+
+### Enable Inline Editing
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'tasks',
+  dataSource: dataSource,
+  editable: true,
+  singleClickEdit: true,  // Single-click to edit
+  callbacks: {
+    onCellValueChanged: (event) => {
+      console.log('Updated:', event.data);
+      // Changes are automatically saved to backend!
+    }
+  }
+};
+```
+
+### Add Filters and Sorting
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'products',
+  dataSource: dataSource,
+  filters: {
+    category: 'Electronics',
+    price: { $lt: 1000 }
+  },
+  sort: {
+    price: 'asc'
+  }
+};
+```
+
+### Enable CSV Export
+
+```typescript
+const schema = {
+  type: 'object-aggrid',
+  objectName: 'sales',
+  dataSource: dataSource,
+  exportConfig: {
+    enabled: true,
+    fileName: 'sales-report.csv'
+  }
+};
+```
+
+## What Happens Automatically
+
+When you use ObjectAgGrid, it automatically:
+
+1. ✅ Fetches the object schema (field definitions) from your backend
+2. ✅ Generates appropriate column definitions based on field types
+3. ✅ Applies proper formatters (currency, dates, percentages, etc.)
+4. ✅ Loads data with pagination
+5. ✅ Saves edits back to the backend (when `editable: true`)
+
+## Field Types Automatically Formatted
+
+- **Currency**: `$1,234.56`
+- **Percent**: `45.5%`
+- **Date**: Localized date format
+- **Boolean**: ✓ Yes / ✗ No
+- **Email**: Clickable mailto links
+- **Phone**: Clickable tel links
+- **URL**: Clickable external links
+- **Color**: Color swatches
+- **Rating**: Star ratings ⭐⭐⭐⭐⭐
+- And 20+ more field types!
+
+## Backend Requirements
+
+Your ObjectStack backend should provide:
+
+1. **Metadata Endpoint**: Returns object schema with field definitions
+   ```typescript
+   GET /api/v1/metadata/object/{objectName}
+   ```
+
+2. **Data Endpoint**: Returns paginated data
+   ```typescript
+   GET /api/data/{objectName}?$top=20&$skip=0
+   ```
+
+3. **Update Endpoint** (for editable grids):
+   ```typescript
+   PATCH /api/data/{objectName}/{id}
+   ```
+
+## Next Steps
+
+- See `OBJECT_AGGRID_CN.md` for Chinese documentation
+- See `examples/object-aggrid-demo.tsx` for complete examples
+- See `README.md` for full API reference
+
+## Troubleshooting
+
+**Data not loading?**
+- Check that your `dataSource` is properly initialized
+- Verify the `objectName` exists in your backend
+- Check browser console for errors
+
+**Columns not showing?**
+- Verify your object schema has field definitions
+- Check that fields have `name` and `type` properties
+
+**Editing not working?**
+- Make sure `editable: true` is set
+- Verify fields are not marked as `readonly`
+- Check that your backend update endpoint is working
+
+## Support
+
+For issues or questions, please refer to:
+- Full documentation in `README.md`
+- Chinese documentation in `OBJECT_AGGRID_CN.md`
+- Implementation details in `IMPLEMENTATION_SUMMARY.md`

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/AddressField-Bntpynvd.js

@@ -0,0 +1,95 @@
+import { j as e } from "./index-B87wd1E0.js";
+import { Label as d, Input as r } from "@object-ui/components";
+function u({ value: n, onChange: o, field: h, readonly: a, ...i }) {
+  const s = n || {}, l = (t, c) => {
+    o({
+      ...s,
+      [t]: c
+    });
+  }, x = (t) => [
+    t.street,
+    t.city,
+    [t.state, t.zipCode].filter(Boolean).join(" "),
+    t.country
+  ].filter(Boolean).join(", ") || "-";
+  return a ? /* @__PURE__ */ e.jsx("span", { className: "text-sm", children: x(s) }) : /* @__PURE__ */ e.jsxs("div", { className: "space-y-3", children: [
+    /* @__PURE__ */ e.jsxs("div", { children: [
+      /* @__PURE__ */ e.jsx(d, { htmlFor: "street", className: "text-xs", children: "Street Address" }),
+      /* @__PURE__ */ e.jsx(
+        r,
+        {
+          id: "street",
+          type: "text",
+          value: s.street || "",
+          onChange: (t) => l("street", t.target.value),
+          placeholder: "123 Main St",
+          disabled: a || i.disabled,
+          className: i.className
+        }
+      )
+    ] }),
+    /* @__PURE__ */ e.jsxs("div", { className: "grid grid-cols-2 gap-3", children: [
+      /* @__PURE__ */ e.jsxs("div", { children: [
+        /* @__PURE__ */ e.jsx(d, { htmlFor: "city", className: "text-xs", children: "City" }),
+        /* @__PURE__ */ e.jsx(
+          r,
+          {
+            id: "city",
+            type: "text",
+            value: s.city || "",
+            onChange: (t) => l("city", t.target.value),
+            placeholder: "San Francisco",
+            disabled: a || i.disabled
+          }
+        )
+      ] }),
+      /* @__PURE__ */ e.jsxs("div", { children: [
+        /* @__PURE__ */ e.jsx(d, { htmlFor: "state", className: "text-xs", children: "State / Province" }),
+        /* @__PURE__ */ e.jsx(
+          r,
+          {
+            id: "state",
+            type: "text",
+            value: s.state || "",
+            onChange: (t) => l("state", t.target.value),
+            placeholder: "CA",
+            disabled: a || i.disabled
+          }
+        )
+      ] })
+    ] }),
+    /* @__PURE__ */ e.jsxs("div", { className: "grid grid-cols-2 gap-3", children: [
+      /* @__PURE__ */ e.jsxs("div", { children: [
+        /* @__PURE__ */ e.jsx(d, { htmlFor: "zipCode", className: "text-xs", children: "ZIP / Postal Code" }),
+        /* @__PURE__ */ e.jsx(
+          r,
+          {
+            id: "zipCode",
+            type: "text",
+            value: s.zipCode || "",
+            onChange: (t) => l("zipCode", t.target.value),
+            placeholder: "94102",
+            disabled: a || i.disabled
+          }
+        )
+      ] }),
+      /* @__PURE__ */ e.jsxs("div", { children: [
+        /* @__PURE__ */ e.jsx(d, { htmlFor: "country", className: "text-xs", children: "Country" }),
+        /* @__PURE__ */ e.jsx(
+          r,
+          {
+            id: "country",
+            type: "text",
+            value: s.country || "",
+            onChange: (t) => l("country", t.target.value),
+            placeholder: "United States",
+            disabled: a || i.disabled
+          }
+        )
+      ] })
+    ] })
+  ] });
+}
+export {
+  u as AddressField
+};