pict-section-recordset 1.0.58 → 1.0.59

package/docs/README.md

@@ -0,0 +1,76 @@
+# Pict-Section-RecordSet
+
+> Dynamic record set management views with CRUD operations
+
+Pict-Section-RecordSet provides automatic CRUD (Create, Read, Update, Delete) views for managing record sets in Pict applications. Built on top of pict-section-form, it offers list views, detail views, filtering, pagination, and seamless integration with Meadow API endpoints.
+
+## Features
+
+- **Automatic CRUD Views** - List, detail, create, and edit views generated from configuration
+- **Built-in Filtering** - Configurable filter controls with various input types
+- **Pagination Support** - Navigate large record sets with configurable page sizes
+- **Meadow Integration** - Native support for Meadow REST API endpoints
+- **Faceted Search** - Search with facets for filtering by field values and ranges
+- **Custom Providers** - Extensible provider system for any data source
+- **Router Integration** - Built-in routing for navigation between views
+
+## Quick Start
+
+```javascript
+const libPictRecordSet = require('pict-section-recordset');
+
+// Create a record set application
+const app = new libPictRecordSet.PictRecordSetApplication(pict, {
+    Name: 'User Management',
+    Hash: 'UserManagement',
+    pict_configuration: {
+        Product: 'UserManager'
+    }
+});
+
+// Initialize the application
+app.initialize();
+```
+
+## Installation
+
+```bash
+npm install pict-section-recordset
+```
+
+## Core Concepts
+
+### Record Providers
+
+Record providers handle data fetching, creating, updating, and deleting. The package includes:
+
+- **RecordSetProviderBase** - Base class for custom providers
+- **RecordSetProviderMeadowEndpoints** - Provider for Meadow REST APIs
+
+### Views
+
+The package provides several view types:
+
+- **List View** - Displays records in a table with sorting and pagination
+- **Detail View** - Shows a single record with all fields
+- **Create View** - Form for creating new records
+- **Edit View** - Form for editing existing records
+- **Dashboard View** - Overview with statistics and quick actions
+
+### Filters
+
+Filters allow users to narrow down record sets. Filter types include text search, date ranges, select dropdowns, and custom filter controls.
+
+## Documentation
+
+- [Record Providers](record-providers.md) - Creating and configuring data providers
+- [Filters](filters.md) - Configuring filter controls
+- [API Reference](api-reference.md) - Complete API documentation
+
+## Related Packages
+
+- [pict](https://github.com/stevenvelozo/pict) - Core Pict framework
+- [pict-section-form](https://github.com/stevenvelozo/pict-section-form) - Dynamic forms framework
+- [pict-application](https://github.com/stevenvelozo/pict-application) - Application base class
+- [meadow](https://github.com/stevenvelozo/meadow) - REST API framework
+- [fable](https://github.com/stevenvelozo/fable) - Service provider framework

package/docs/_sidebar.md

@@ -0,0 +1,19 @@
+- Getting Started
+
+  - [Introduction](/)
+  - [Record Providers](record-providers.md)
+
+- Views
+
+  - [Create View](views/create/)
+  - [Read View](views/read/)
+  - [List View](views/list/)
+  - [Dashboard View](views/dashboard/)
+
+- Configuration
+
+  - [Filters](filters.md)
+
+- Reference
+
+  - [API Reference](api-reference.md)

package/docs/api-reference.md

@@ -0,0 +1,233 @@
+# API Reference
+
+Complete API documentation for Pict-Section-RecordSet.
+
+## PictRecordSetApplication
+
+Main application class for record set management.
+
+### Constructor
+
+```javascript
+new PictRecordSetApplication(pFable, pOptions, pServiceHash)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFable` | object | Pict/Fable instance |
+| `pOptions` | object | Application configuration |
+| `pServiceHash` | string | Service identifier |
+
+### Configuration Options
+
+```javascript
+{
+    Name: 'My Record Set App',
+    Hash: 'MyRecordSetApp',
+    pict_configuration: {
+        Product: 'MyProduct'
+    }
+}
+```
+
+---
+
+## RecordSetProviderBase
+
+Base class for record providers.
+
+### Methods
+
+#### getRecord(pIDOrGuid, fCallback)
+
+Retrieves a single record.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pIDOrGuid` | string/number | Record identifier |
+| `fCallback` | function | Callback `(error, record)` |
+
+#### getRecords(pFilter, fCallback)
+
+Retrieves multiple records with filtering.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFilter` | object | Filter configuration |
+| `fCallback` | function | Callback `(error, result)` |
+
+**Filter Object:**
+
+```javascript
+{
+    Entity: 'EntityName',
+    FilterString: 'FBV~Field~EQ~Value',
+    Offset: 0,
+    PageSize: 25,
+    Facets: {
+        ReturnRecords: true,
+        Fields: ['Field1', 'Field2'],
+        Ranges: [{ Field: 'Date', Start: '2020', End: '2025', Gap: 'YEAR' }]
+    }
+}
+```
+
+**Result Object:**
+
+```javascript
+{
+    Records: [...],
+    Facets: {
+        Field1: { 'value1': 10, 'value2': 5 },
+        ByRange: { '2020': 100, '2021': 150 }
+    }
+}
+```
+
+#### createRecord(pRecord, fCallback)
+
+Creates a new record.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pRecord` | object | Record data |
+| `fCallback` | function | Callback `(error, newRecord)` |
+
+#### updateRecord(pRecord, fCallback)
+
+Updates an existing record.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pRecord` | object | Record data with ID |
+| `fCallback` | function | Callback `(error, updatedRecord)` |
+
+#### deleteRecord(pIDOrGuid, fCallback)
+
+Deletes a record.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pIDOrGuid` | string/number | Record identifier |
+| `fCallback` | function | Callback `(error, success)` |
+
+---
+
+## RecordSetProviderMeadowEndpoints
+
+Provider for Meadow REST API endpoints. Extends RecordSetProviderBase.
+
+### Additional Configuration
+
+```javascript
+{
+    // Base URL for API
+    APIEndpoint: '/1.0/',
+
+    // Entity name
+    Entity: 'User',
+
+    // Use schema endpoint for auto-configuration
+    UseSchemaEndpoint: true
+}
+```
+
+### Meadow Endpoints Used
+
+| Operation | Endpoint |
+|-----------|----------|
+| Get One | `GET /{Entity}/{id}` |
+| Get Many | `GET /{Entity}s/FilteredTo/{filter}/{offset}/{limit}` |
+| Create | `POST /{Entity}` |
+| Update | `PUT /{Entity}` |
+| Delete | `DELETE /{Entity}/{id}` |
+| Schema | `GET /{Entity}/Schema` |
+
+---
+
+## Views
+
+### List View
+
+Displays records in a table format.
+
+```javascript
+// Configuration
+{
+    ViewType: 'List',
+    Columns: [
+        { Field: 'Name', Header: 'Name', Sortable: true },
+        { Field: 'Email', Header: 'Email' },
+        { Field: 'Status', Header: 'Status' }
+    ],
+    PageSize: 25,
+    ShowPagination: true
+}
+```
+
+### Detail View
+
+Shows a single record.
+
+```javascript
+// Configuration
+{
+    ViewType: 'Read',
+    Fields: [
+        { Field: 'Name', Label: 'Full Name' },
+        { Field: 'Email', Label: 'Email Address' },
+        { Field: 'CreatedDate', Label: 'Created', Format: 'date' }
+    ]
+}
+```
+
+### Create/Edit View
+
+Form for creating or editing records. Uses pict-section-form configuration.
+
+---
+
+## Router
+
+Built-in routing for navigation.
+
+### Routes
+
+| Route | View |
+|-------|------|
+| `/` | Dashboard |
+| `/list` | List view |
+| `/view/{id}` | Detail view |
+| `/create` | Create form |
+| `/edit/{id}` | Edit form |
+
+### Programmatic Navigation
+
+```javascript
+// Navigate to list
+pict.providers.RecordSetRouter.navigateTo('list');
+
+// Navigate to detail view
+pict.providers.RecordSetRouter.navigateTo('view', { id: 123 });
+
+// Navigate to edit
+pict.providers.RecordSetRouter.navigateTo('edit', { id: 123 });
+```
+
+---
+
+## Module Exports
+
+```javascript
+const libPictRecordSet = require('pict-section-recordset');
+
+// Main meta controller
+libPictRecordSet  // RecordSet MetaController
+
+// Application class
+libPictRecordSet.PictRecordSetApplication
+
+// Providers
+libPictRecordSet.RecordSetProviderBase
+libPictRecordSet.RecordSetProviderMeadowEndpoints
+```

package/docs/cover.md

@@ -0,0 +1,11 @@
+# Pict-Section-RecordSet <small>1</small>
+
+> Dynamic record set management views with CRUD operations
+
+- Automatic Create, Read, Update, Delete views
+- Built-in filtering, pagination, and search
+- Meadow endpoint integration for API-driven data
+- Extensible record providers for custom data sources
+
+[GitHub](https://github.com/stevenvelozo/pict-section-recordset)
+[Get Started](#pict-section-recordset)

package/docs/filters.md

@@ -0,0 +1,151 @@
+# Filters
+
+Filters allow users to narrow down record sets based on field values.
+
+## Filter Types
+
+The record set supports various filter control types:
+
+| Type | Description |
+|------|-------------|
+| `Text` | Free-text search input |
+| `Select` | Dropdown selection |
+| `DateRange` | Date range picker |
+| `NumberRange` | Numeric range inputs |
+| `Checkbox` | Boolean toggle |
+| `MultiSelect` | Multiple selection |
+
+## Filter Configuration
+
+Configure filters in your record set manifest:
+
+```javascript
+const filterConfig = {
+    Filters: [
+        {
+            Hash: 'NameFilter',
+            Name: 'Name',
+            FilterType: 'Text',
+            Field: 'Name',
+            Operator: 'LIKE'
+        },
+        {
+            Hash: 'StatusFilter',
+            Name: 'Status',
+            FilterType: 'Select',
+            Field: 'Status',
+            Options: [
+                { Value: 'active', Label: 'Active' },
+                { Value: 'inactive', Label: 'Inactive' },
+                { Value: 'pending', Label: 'Pending' }
+            ]
+        },
+        {
+            Hash: 'DateFilter',
+            Name: 'Created Date',
+            FilterType: 'DateRange',
+            Field: 'CreatedDate'
+        }
+    ]
+};
+```
+
+## Filter Operators
+
+Available operators for filter conditions:
+
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `EQ` | Equals | `Status EQ 'active'` |
+| `NE` | Not equals | `Status NE 'deleted'` |
+| `GT` | Greater than | `Age GT 18` |
+| `GE` | Greater or equal | `Age GE 21` |
+| `LT` | Less than | `Price LT 100` |
+| `LE` | Less or equal | `Price LE 50` |
+| `LIKE` | Contains | `Name LIKE 'John'` |
+| `IN` | In list | `Status IN ['active','pending']` |
+
+## Filter String Format
+
+Filters are converted to Meadow filter strings:
+
+```
+FBV~FieldName~Operator~Value
+```
+
+Multiple filters are joined:
+
+```
+FBV~Name~LIKE~John~FBV~Status~EQ~active
+```
+
+## Dynamic Filters
+
+Filters can be generated from record data:
+
+```javascript
+// Auto-generate select options from unique field values
+const filter = {
+    Hash: 'DepartmentFilter',
+    Name: 'Department',
+    FilterType: 'Select',
+    Field: 'Department',
+    DynamicOptions: true,  // Fetch options from data
+    FacetField: 'Department'  // Use facet for counts
+};
+```
+
+## Filter Events
+
+Handle filter changes in your application:
+
+```javascript
+// Listen for filter changes
+pict.PictSectionRecordSet.on('filter-changed', (filterState) => {
+    console.log('Active filters:', filterState);
+});
+
+// Programmatically set filters
+pict.PictSectionRecordSet.setFilter('StatusFilter', 'active');
+
+// Clear all filters
+pict.PictSectionRecordSet.clearFilters();
+```
+
+## Custom Filter Controls
+
+Create custom filter input providers:
+
+```javascript
+const libFilterProvider = require('pict-section-recordset').FilterProvider;
+
+class CustomRangeFilter extends libFilterProvider
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+    }
+
+    // Render custom filter UI
+    render(pFilterConfig, pContainer)
+    {
+        // Custom rendering logic
+    }
+
+    // Get filter value
+    getValue()
+    {
+        return {
+            min: this.minInput.value,
+            max: this.maxInput.value
+        };
+    }
+
+    // Convert to filter string
+    toFilterString()
+    {
+        const value = this.getValue();
+        return `FBV~${this.options.Field}~GE~${value.min}~FBV~${this.options.Field}~LE~${value.max}`;
+    }
+}
+```

package/docs/index.html

@@ -0,0 +1,51 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Pict-Section-RecordSet Documentation</title>
+    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+    <meta name="description" content="Documentation for Pict-Section-RecordSet - Dynamic record set management views with CRUD operations" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0" />
+    <meta name="keywords" content="pict, recordset, crud, javascript, framework, meadow, data management" />
+    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" />
+    <style>
+      :root {
+        --theme-color: #42b983;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script>
+      window.$docsify = {
+        name: 'Pict-Section-RecordSet',
+        repo: 'https://github.com/stevenvelozo/pict-section-recordset',
+        loadSidebar: '_sidebar.md',
+        subMaxLevel: 3,
+        auto2top: true,
+        coverpage: 'cover.md',
+        onlyCover: false,
+        search: {
+          placeholder: 'Search',
+          noData: 'No results found',
+          depth: 3
+        },
+        copyCode: {
+          buttonText: 'Copy',
+          successText: 'Copied'
+        }
+      };
+    </script>
+    <!-- Docsify v4 -->
+    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+    <!-- Syntax highlighting -->
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-javascript.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-json.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
+    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-markdown.min.js"></script>
+    <!-- Search plugin -->
+    <script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js"></script>
+    <!-- Copy code plugin -->
+    <script src="//cdn.jsdelivr.net/npm/docsify-copy-code@2"></script>
+  </body>
+</html>

package/docs/record-providers.md

@@ -0,0 +1,155 @@
+# Record Providers
+
+Record providers handle all data operations for your record sets.
+
+## Provider Types
+
+### RecordSetProviderBase
+
+The base class for creating custom record providers:
+
+```javascript
+const libRecordSetProviderBase = require('pict-section-recordset').RecordSetProviderBase;
+
+class MyRecordProvider extends libRecordSetProviderBase
+{
+    constructor(pFable, pOptions, pServiceHash)
+    {
+        super(pFable, pOptions, pServiceHash);
+    }
+
+    // Get a single record by ID
+    getRecord(pIDOrGuid, fCallback)
+    {
+        // Fetch record from your data source
+        const record = this.fetchFromDatabase(pIDOrGuid);
+        fCallback(null, record);
+    }
+
+    // Get multiple records with filtering
+    getRecords(pFilter, fCallback)
+    {
+        // Fetch records with filter applied
+        const records = this.queryDatabase(pFilter);
+        fCallback(null, { Records: records });
+    }
+
+    // Create a new record
+    createRecord(pRecord, fCallback)
+    {
+        const newRecord = this.insertIntoDatabase(pRecord);
+        fCallback(null, newRecord);
+    }
+
+    // Update an existing record
+    updateRecord(pRecord, fCallback)
+    {
+        const updated = this.updateInDatabase(pRecord);
+        fCallback(null, updated);
+    }
+
+    // Delete a record
+    deleteRecord(pIDOrGuid, fCallback)
+    {
+        this.deleteFromDatabase(pIDOrGuid);
+        fCallback(null, true);
+    }
+}
+
+module.exports = MyRecordProvider;
+```
+
+### RecordSetProviderMeadowEndpoints
+
+Provider for Meadow REST API endpoints:
+
+```javascript
+const libMeadowProvider = require('pict-section-recordset').RecordSetProviderMeadowEndpoints;
+
+// The provider automatically handles:
+// - GET /Entity/{id} - Get single record
+// - GET /Entities/FilteredTo/{filter}/0/100 - Get filtered records
+// - POST /Entity - Create record
+// - PUT /Entity - Update record
+// - DELETE /Entity/{id} - Delete record
+```
+
+## Filter Object
+
+When fetching records, you can pass a filter object:
+
+```javascript
+const filter = {
+    // Entity name (can override for LiteExtended, etc.)
+    Entity: 'User',
+
+    // Meadow-style filter string
+    FilterString: 'FBV~Name~EQ~John',
+
+    // Pagination
+    Offset: 0,
+    PageSize: 25,
+
+    // Faceting for search
+    Facets: {
+        ReturnRecords: true,
+        Fields: ['Status', 'Department'],
+        Ranges: [
+            {
+                Field: 'CreatedDate',
+                Start: '2020-01-01',
+                End: '2025-12-31',
+                Gap: 'YEAR'
+            }
+        ]
+    }
+};
+
+provider.getRecords(filter, (err, result) => {
+    console.log(result.Records);  // Array of records
+    console.log(result.Facets);   // Facet counts
+});
+```
+
+## Provider Configuration
+
+```javascript
+const providerConfig = {
+    ProviderIdentifier: 'MyRecordProvider',
+
+    // Auto-initialize with application
+    AutoInitialize: true,
+    AutoInitializeOrdinal: 1,
+
+    // Don't solve with app (records loaded on demand)
+    AutoSolveWithApp: false
+};
+```
+
+## Registering Providers
+
+Register your provider with the Pict instance:
+
+```javascript
+// Add the provider type
+pict.addProviderSingleton('MyRecordProvider', providerConfig, MyRecordProvider);
+
+// Or instantiate directly
+const provider = pict.instantiateServiceProvider('RecordSetProviderBase', {
+    ProviderIdentifier: 'UserProvider'
+});
+```
+
+## Using with Meadow Endpoints
+
+The Meadow provider can auto-generate configuration from schema:
+
+```javascript
+// Fetch schema from Meadow endpoint
+fetch('/1.0/User/Schema')
+    .then(response => response.json())
+    .then(schema => {
+        // Use schema to configure the record set
+        app.configureFromSchema(schema);
+    });
+```