mobigrid-module 1.1.28 → 1.1.35

package/README.md

@@ -2,55 +2,204 @@
 
 A flexible and customizable data table interface module with advanced filtering, column management, and action handling capabilities.
 
+## Installation
+
+```bash
+npm install mobigrid-module
+```
+
+## Usage
+
+You can use the `MobigridModule` component by importing it into your React application.
+
+```tsx
+import MobigridModule from 'mobigrid-module';
+import 'mobigrid-module/dist/index.css'; // Import styles if necessary
+
+function App() {
+  const handlePrint = (row) => {
+    console.log('Print ticket:', row.ticket_numbers);
+  };
+
+  const handleRefund = (row) => {
+    console.log('Refund transaction:', row.request_id);
+  };
+
+  // Callback to determine if print button should be shown
+  const canPrintTicket = (row) => {
+    return row.status === 'PAID' && row.canPrint === true;
+  };
+
+  return (
+    <MobigridModule
+      configUrl="https://api.example.com/config"
+      // OR provide configJson directly
+      // configJson={myConfigObject}
+      dataUrl="https://api.example.com/transactions"
+      callbacks={{
+        onPrint: handlePrint,
+        onRefund: handleRefund,
+        checkPrint: canPrintTicket
+      }}
+      customHeaders={{
+        'Authorization': 'Bearer token123'
+      }}
+    />
+  );
+}
+```
+
+## Component Props
+
+The `MobigridModule` accepts the following props:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `configUrl` | `string` | URL to fetch the configuration JSON from. |
+| `configJson` | `object` | Direct configuration object. Use this or `configUrl`. |
+| `dataUrl` | `string` | URL to fetch the table data from. Overrides `data_url` in config. |
+| `preJsUrl` | `string` | URL to fetch a JavaScript file to execute before rendering (e.g., for global functions). |
+| `preJs` | `string` | Direct JavaScript code string to execute. |
+| `callbacks` | `object` | An object containing functions referenced by action buttons or conditions. |
+| `customHeaders` | `object` | Custom HTTP headers to include in API requests (data and config). |
+| `itemsPerPage` | `number` | Number of items to display per page (default: 14). |
+| `dateFormat` | `string` | Format string for dates in API requests (default: "MM-dd-yyyy HH:mm"). |
+| `children` | `ReactNode` | Child components to render at the bottom of the module. |
+
 ## Configuration Structure
 
-The configuration object defines the structure and behavior of a data table interface. It includes filters, columns, actions, and other settings.
+The configuration object defines the structure of the table, filters, and columns. You can provide this via the `configUrl` endpoint or directly via the `configJson` prop.
+
+### Example Configuration (Payment History)
+
+```json
+{
+  "title": "Payment History",
+  "data_url": "https://api.example.com/payments",
+  "Filters": [
+    [
+      {
+        "type": "Text",
+        "name": "request_id",
+        "label": "Request ID"
+      },
+      {
+        "type": "Select",
+        "name": "status",
+        "label": "Status",
+        "options": [
+          { "label": "Paid", "value": "PAID" },
+          { "label": "Failed", "value": "FAILED" }
+        ]
+      }
+    ],
+    [
+      {
+        "type": "Date",
+        "name": "fromDate",
+        "label": "From Date"
+      },
+       {
+        "type": "Date",
+        "name": "toDate",
+        "label": "To Date"
+      }
+    ]
+  ],
+  "colomns": [
+    {
+      "title": "Request ID",
+      "key": "request_id",
+      "type": "text"
+    },
+    {
+      "title": "Date",
+      "key": "created_date",
+      "type": "date",
+      "pattern": "dd/MM/yyyy HH:mm"
+    },
+    {
+      "title": "POS Code",
+      "key": "pos_code",
+      "type": "text"
+    },
+    {
+      "title": "Amount",
+      "key": "amount",
+      "type": "money",
+      "currency": "MAD"
+    },
+    {
+      "title": "Status",
+      "key": "status",
+      "type": "status"
+    },
+    {
+      "title": "Actions",
+      "key": "ACTIONS_BUTTONS",
+      "actions": [
+        {
+          "label": "Print",
+          "icon": "icon-printer",
+          "action": "onPrint",
+          "condition": "checkPrint"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Filters Configuration
+
+Filters are defined as an array of arrays (rows of filters).
+
+- **`type`**: The type of filter. Supported types:
+    - `"Text"`: Simple text input.
+    - `"Select"`: Dropdown menu. Use `urlSource` for dynamic options or `options` for static ones.
+    - `"Date"`: Date picker.
+- **`name`**: The query parameter key that will be sent to the `data_url`.
+- **`label`**: The label displayed for the filter.
+- **`urlSource`**: (For `Select` type) URL to fetch options from. Expects an array of objects `{ label, value }`.
+- **`options`**: (For `Select` type) Static array of options `{ label, value }`.
 
-### Container Props
+### Columns Configuration (`colomns`)
 
-The module accepts the following configuration properties:
+Defines the table columns.
 
-- **configUrl**: URL to fetch configuration from
-- **preJsUrl**: URL to fetch pre-processing JavaScript
-- **configJson**: Direct configuration object (alternative to configUrl)
-- **preJs**: Direct pre-processing JavaScript (alternative to preJsUrl)
-- **customHeaders**: Custom HTTP headers for API requests
-- **itemsPerPage**: Number of items to display per page
-- **dateFormat**: Default date format for date fields
-- **children**: React child components
+- **`title`**: Header text for the column.
+- **`key`**: The key in the data object to display (e.g., `request_id`, `amount`).
+- **`type`**: formatting type.
+    - `"text"`: Default display.
+    - `"date"`: Formats date using `pattern` (default: `dd-MM-yyyy`).
+    - `"money"`: Formats as currency. Usage: `currency` prop required (e.g., "MAD").
+    - `"status"`: Displays a colored badge based on status value (PENDING, PAID, CANCELLED, etc.).
+    - `"ACTIONS_BUTTONS"`: Special column for action buttons.
+- **`scroll`**: If true, limits height and adds scrollbar for long content.
 
-### Main Properties
+### Actions Configuration
 
-- **title**: The title of the configuration
-- **data_url**: API endpoint for fetching data
-- **Filters**: Array of filter groups for data filtering
-- **columns**: Defines the table columns and their properties
-- **extractColumns**: Columns used for data export
-- **detailsColumns**: Columns shown in detail view
+For columns with `key: "ACTIONS_BUTTONS"`, you can define an `actions` array.
 
-### Filter Types
+- **`label`**: Text on the button.
+- **`icon`**: Icon name (referenced from Feather icons, prefixed with `icon-`).
+- **`action`**: The name of the callback function in the `callbacks` prop to execute on click. receives the row data.
+- **`condition`**: (Optional) The name of the callback function in the `callbacks` prop to determine visibility. Receives row data and must return `boolean`.
 
-- **Select**: Dropdown with options (static or dynamic from urlSource)
-- **Text**: Basic text input
-- **Date**: Date picker input
-- **Export**: Export functionality
-- **Button**: Action buttons (e.g., search)
+## Development
 
-### Column Properties
+To build the project:
 
-- **title**: Column header text
-- **key**: Data field identifier
-- **type**: Data type (date, money, dropdown, etc.)
-- **pattern**: Format pattern (for dates)
-- **actions**: Available actions for dropdown columns
+```bash
+npm run build
+```
 
-### Additional Settings
+To deploy (build, version bump, publish, and push):
 
-- **max_diff**: Maximum difference value
-- **pagesNum**: Number of pages
-- **service_path**: Service implementation path
-- **authorized_profiles**: Allowed user profile IDs
-- **modal_size**: Size of modal windows
-- **components**: Required component names
+```bash
+# Default bump is patch
+./deploy.sh
 
-## Example Configuration
+# Specify bump type
+./deploy.sh minor
+```