@jmruthers/pace-core 0.6.8 → 0.6.10

package/docs/api-reference/components.md

@@ -889,7 +889,7 @@ import {
 
 ## Alert
 
-A flexible and accessible alert component for displaying important messages. Uses semantic HTML (`<aside>`) for better accessibility and semantic meaning.
+A flexible and accessible alert component for displaying important messages. Uses semantic HTML (`<div>`) with ARIA roles for better accessibility and semantic meaning.
 
 ### Props
 
@@ -913,7 +913,7 @@ interface AlertDescriptionProps extends React.HTMLAttributes<HTMLParagraphElemen
 ```tsx
 import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
 
-// Basic alert (renders as <aside> element)
+// Basic alert (renders as <div> element)
 <Alert>
   <AlertTitle>Success</AlertTitle>
   <AlertDescription>Your changes have been saved.</AlertDescription>
@@ -934,14 +934,14 @@ import { Alert, AlertTitle, AlertDescription } from '@jmruthers/pace-core';
 
 ### Variants
 
-- **default**: Standard alert with background and border (renders as `<aside>`)
-- **destructive**: Red alert for errors and warnings (renders as `<aside>`)
+- **default**: Standard alert with background and border (renders as `<div>`)
+- **destructive**: Red alert for errors and warnings (renders as `<div>`)
 - **inline**: Lightweight text formatting without background (renders as fragment)
 
 ### Semantic HTML
 
 The Alert component uses semantic HTML for better accessibility:
-- **Default and destructive variants**: Render as `<aside>` elements with `role="alert"`
+- **Default and destructive variants**: Render as `<div>` elements with `role="alert"`
 - **Inline variant**: Renders as a React Fragment (no wrapper element)
 - **AlertTitle**: Renders as `<h5>` (default/destructive) or `<strong>` (inline)
 - **AlertDescription**: Renders as `<p>` (default/destructive) or `<span>` (inline)

package/docs/api-reference/rpc-functions.md

@@ -16,10 +16,10 @@ RPC functions are PostgreSQL functions that provide a secure, standardized way t
 
 All RPC functions follow the `<family>_<domain>_<verb>` pattern:
 
-- **`data_*`** prefix for read operations (e.g., `data_file_reference_list`, `data_user_organisations_get`)
+- **`data_*`** prefix for read operations (e.g., `data_file_reference_list`, `data_user_organisations_get`, `data_app_resolve`)
 - **`app_*`** prefix for write operations (e.g., `app_cake_dish_create`, `app_file_reference_create`)
 - **`rbac_*`** prefix for RBAC operations (exception to standard pattern, e.g., `rbac_permission_check`, `rbac_role_grant`)
-- **`util_*`** prefix for utility functions (e.g., `util_app_resolve`)
+- **`util_*`** prefix for utility functions (legacy - use `data_*` for read operations instead, e.g., `util_get_cake_app_id`)
 - **CRUD verbs**: `create`, `read`, `get`, `list`, `update`, `delete`
 - **Bulk operations**: Use `_bulk` suffix (e.g., `app_cake_dish_create_bulk`)
 
@@ -155,7 +155,7 @@ Documented in [RBAC API Reference](../rbac/api-reference.md):
 - `rbac_check_distribution_or_page_permission` - Check distribution or page permissions
 
 **Utility:**
-- `util_app_resolve` - Resolve app ID from app name
+- `data_app_resolve` - Resolve app ID from app name (renamed from `util_app_resolve`)
 - `util_get_cake_app_id` - Get CAKE app ID (application-specific utility)
 - `debug_auth_context` - Debug authentication context (development only)
 - `handle_new_user` - Handle new user registration (triggered automatically)

package/docs/implementation-guides/data-tables.md

@@ -1514,6 +1514,72 @@ function UserManagement() {
 
 DataTable provides advanced editing capabilities for columns, including searchable and creatable select fields, grouped options, and customizable number inputs.
 
+### Automatic Label Display for Select Fields
+
+DataTable automatically displays labels for select fields in read mode, eliminating the need for custom cell renderers. When a column has `fieldType: 'select'` and `fieldOptions`, the table will automatically show the label (e.g., "Mobile") instead of the raw value (e.g., `1`).
+
+**Automatic Behavior:**
+- ✅ **No custom cell renderer needed** - Labels are displayed automatically
+- ✅ **Works with simple options** - `{ value: 1, label: 'Mobile' }`
+- ✅ **Works with grouped options** - Supports groups and separators
+- ✅ **Type coercion** - Handles both string and number values (e.g., `"1"` matches `1`)
+- ✅ **Fallback to raw value** - If label not found, displays the original value
+- ✅ **Preserves custom renderers** - If you provide a custom `cell` renderer, it won't be overridden
+
+**Example:**
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'phone_type_id',
+    header: 'Phone Type',
+    fieldType: 'select',
+    fieldOptions: [
+      { value: 1, label: 'Mobile' },
+      { value: 2, label: 'Home' },
+      { value: 3, label: 'Work' },
+    ],
+    // No cell renderer needed - automatically displays "Mobile", "Home", or "Work"
+  }
+];
+```
+
+**Before (required custom cell renderer):**
+```tsx
+{
+  accessorKey: 'phone_type_id',
+  header: 'Phone Type',
+  fieldType: 'select',
+  fieldOptions: [
+    { value: 1, label: 'Mobile' },
+    { value: 2, label: 'Home' },
+  ],
+  cell: ({ row }) => {
+    const option = fieldOptions.find(opt => opt.value === row.original.phone_type_id);
+    return option?.label || row.original.phone_type_id;
+  }
+}
+```
+
+**After (automatic):**
+```tsx
+{
+  accessorKey: 'phone_type_id',
+  header: 'Phone Type',
+  fieldType: 'select',
+  fieldOptions: [
+    { value: 1, label: 'Mobile' },
+    { value: 2, label: 'Home' },
+  ]
+  // No cell renderer needed - automatically displays labels
+}
+```
+
+**Note:** This automatic behavior only applies when:
+- `fieldType: 'select'` is specified
+- `fieldOptions` is provided and not empty
+- No custom `cell` renderer is already defined
+
 ### Select Fields with Search and Create
 
 Editable select columns support type-to-search functionality and the ability to create new options on-the-fly when needed.
@@ -2008,6 +2074,8 @@ The import automatically recognizes and maps:
 />
 ```
 
+> **📚 Import Function Guide**: For detailed guidance on implementing performant, reliable `onImport` handlers, see the [DataTable Import Function Guide](./data-table-import-guide.md). This guide covers batch operations, error handling, validation, performance optimization, and best practices for large imports.
+
 ### Custom Export
 
 The export filename is automatically generated from the table `title` prop:
@@ -2123,18 +2191,198 @@ onExport={async (options) => {
 
 ### Import Column Mapping
 
-The import automatically maps CSV columns using this priority:
+The import automatically maps CSV columns using a comprehensive fallback chain that supports flexible column matching. This eliminates the need for manual column mapping in most cases.
 
-1. **Column Header Match** (case-insensitive)
-   - CSV header "Type" → maps to column with `header: "Type"`
-   
-2. **editAccessorKey Match** (for reference fields)
+#### Automatic Mapping Fallback Chain
+
+The import tries multiple matching strategies in order:
+
+1. **Exact Header Match (case-sensitive)**
+   - CSV header "Meal" → maps to column with `header: "Meal"`
+
+2. **Exact Header Match (case-insensitive)**
+   - CSV header "meal" or "MEAL" → maps to column with `header: "Meal"`
+
+3. **AccessorKey Match**
+   - CSV header "meal_display" → maps to column with `accessorKey: "meal_display"`
+   - Works case-insensitively: "Meal_Display" or "MEAL_DISPLAY" also match
+
+4. **Normalized Match**
+   - Handles whitespace and special character variations
+   - CSV header "Meal Date" → matches "MealDate", "meal-date", "meal_date"
+   - Normalization: converts to lowercase, replaces spaces/special chars with underscores
+
+5. **ImportAliases Match**
+   - CSV header matches any value in the column's `importAliases` array
+   - Works case-insensitively and with normalization
+
+6. **editAccessorKey Match** (for reference fields)
    - CSV header "Type" or "Type (ID)" → maps to `editAccessorKey` field
+   - Also matches direct field names: "meal_mealtype_id" → `editAccessorKey: "meal_mealtype_id"`
+
+7. **Use as-is** (fallback)
+   - If no match is found, the CSV column name is used as-is (lowercase)
+   - A warning is logged for unmapped columns
+
+#### Using ImportAliases for Flexible CSV Formats
+
+The `importAliases` property allows you to define alternative CSV headers that should map to a column. This is especially useful when:
+- CSV files use different naming conventions than your table headers
+- CSV files use more descriptive names (e.g., "Meal Date" vs "Meal")
+- You need to support multiple CSV formats
+
+**Example: Column with ImportAliases**
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'meal_display',
+    header: 'Meal',  // Display-friendly header
+    importAliases: ['Meal Date', 'meal_date', 'MealDate'],  // CSV can use these
+  },
+  {
+    accessorKey: 'dish_code',
+    header: 'Dish',  // Display-friendly header
+    importAliases: ['Dish Code', 'dish_code', 'DishCode'],  // CSV can use these
+  },
+  {
+    accessorKey: 'mealtype_name',
+    header: 'Type',
+    editAccessorKey: 'meal_mealtype_id',
+    importAliases: ['Meal Type', 'meal_type', 'MealType'],  // CSV can use these
+  }
+];
+```
+
+**CSV File:**
+```csv
+Unit Number,Meal Date,Meal Type,Dish Code,Dish Name
+1,2025-01-20,Main,ABC123,Spaghetti
+```
+
+**Result:**
+- "Meal Date" maps to `meal_display` (via `importAliases`)
+- "Meal Type" maps to `meal_mealtype_id` (via `importAliases` → `editAccessorKey`)
+- "Dish Code" maps to `dish_code` (via `importAliases`)
+- No warnings generated
+
+#### Best Practices for Column Definitions
+
+To maximize automatic column mapping success:
+
+1. **Use Descriptive AccessorKeys**
+   ```tsx
+   // ✅ Good - accessorKey matches common CSV naming
+   {
+     accessorKey: 'meal_date',
+     header: 'Meal',
+   }
    
-3. **accessorKey/id Match** (fallback)
-   - CSV header matches column `accessorKey` or `id`
+   // CSV "meal_date" or "Meal Date" will match automatically
+   ```
+
+2. **Add ImportAliases for Common Variations**
+   ```tsx
+   {
+     accessorKey: 'meal_display',
+     header: 'Meal',
+     importAliases: ['Meal Date', 'meal_date', 'MealDate', 'Meal Date'],
+   }
+   ```
 
-If no match is found, the CSV column name is used as-is (useful for new fields).
+3. **Document Acceptable CSV Formats**
+   ```tsx
+   {
+     accessorKey: 'dish_code',
+     header: 'Dish',
+     // CSV can use: "Dish", "Dish Code", "dish_code", "DishCode"
+     importAliases: ['Dish Code', 'dish_code', 'DishCode'],
+   }
+   ```
+
+4. **For Reference Fields, Include Both Display and ID Aliases**
+   ```tsx
+   {
+     accessorKey: 'mealtype_name',
+     header: 'Type',
+     editAccessorKey: 'meal_mealtype_id',
+     // CSV can use display name or ID field name
+     importAliases: ['Meal Type', 'meal_type', 'MealType', 'meal_mealtype_id'],
+   }
+   ```
+
+#### Complete Example: Flexible Column Mapping
+
+```tsx
+const columns: DataTableColumn<Meal>[] = [
+  {
+    accessorKey: 'unit_number',
+    header: 'Unit',
+  },
+  {
+    accessorKey: 'meal_display',
+    header: 'Meal',
+    importAliases: ['Meal Date', 'meal_date', 'MealDate'],
+  },
+  {
+    accessorKey: 'mealtype_name',
+    header: 'Type',
+    editAccessorKey: 'meal_mealtype_id',
+    importAliases: ['Meal Type', 'meal_type', 'MealType'],
+  },
+  {
+    accessorKey: 'dish_code',
+    header: 'Dish',
+    importAliases: ['Dish Code', 'dish_code', 'DishCode'],
+  },
+  {
+    accessorKey: 'dish_name',
+    header: 'Dish Name',
+    importAliases: ['Dish Name', 'dish_name', 'DishName'],
+  },
+];
+
+// This CSV will map correctly without warnings:
+// Unit Number,Meal Date,Meal Type,Dish Code,Dish Name
+// 1,2025-01-20,Main,ABC123,Spaghetti
+```
+
+#### Troubleshooting Column Mapping
+
+**Issue: Getting warnings for columns that should map**
+
+**Solution 1: Add ImportAliases**
+```tsx
+{
+  accessorKey: 'meal_display',
+  header: 'Meal',
+  importAliases: ['Meal Date'],  // Add the CSV header here
+}
+```
+
+**Solution 2: Check AccessorKey Format**
+- Ensure `accessorKey` uses snake_case or matches CSV format
+- CSV "Meal Date" will normalize to "meal_date"
+- If your `accessorKey` is "mealDisplay", add "meal_display" to `importAliases`
+
+**Solution 3: Verify Column Definition**
+- Ensure column has either `accessorKey` or `id`
+- Ensure column has `header` property
+- Check that `editAccessorKey` is set for reference fields
+
+**Issue: Reference fields not mapping correctly**
+
+**Solution:**
+- Ensure `editAccessorKey` is set
+- Add both display name and ID to `importAliases`:
+  ```tsx
+  {
+    accessorKey: 'mealtype_name',
+    header: 'Type',
+    editAccessorKey: 'meal_mealtype_id',
+    importAliases: ['Meal Type', 'meal_mealtype_id'],  // Both variations
+  }
+  ```
 
 ### Form Integration
 

package/docs/rbac/RBAC_CONTRACT.md

@@ -629,18 +629,6 @@ The following ESLint rules enforce this contract (all as **ERROR** severity):
 7. **`no-resource-permission-string-literals`** - Detects string literals in `useResourcePermissions` calls
 8. **`no-permission-wrapper-functions`** - Detects wrapper functions around pace-core permission hooks
 
-### Runtime Compliance
-
-Use runtime compliance checking in development:
-
-```tsx
-import { checkRuntimeCompliance } from '@jmruthers/pace-core/rbac/compliance';
-
-// In development mode
-if (import.meta.env.DEV) {
-  checkRuntimeCompliance();
-}
-```
 
 ## enforcePermissions Configuration
 

package/docs/standards/2-project-structure-standards.md

@@ -15,7 +15,7 @@ This guide defines the standard project structure and file organization patterns
 ## Table of Contents
 
 1. [Standard Directory Structure](#standard-directory-structure)
-2. [File Organization Patterns](#file-organization-patterns)
+2. [File Organization Standard](#file-organization-standard)
 3. [Naming Conventions](#naming-conventions)
 4. [Import Path Configuration](#import-path-configuration)
 5. [Component Organization](#component-organization)
@@ -125,11 +125,11 @@ your-app/
 
 ---
 
-## File Organization Patterns
+## File Organization Standard
 
-### Pattern 1: Feature-Based Organization (Recommended for Small-Medium Apps)
+### Feature-Based Organization
 
-Organize components, hooks, and related code by feature/domain:
+**MUST** organize components, hooks, and related code by feature/domain:
 
 ```
 src/
@@ -163,73 +163,11 @@ src/
     └── users.ts
 ```
 
-**When to use:** Small to medium-sized apps (< 20 features)
-
-### Pattern 2: Domain-Driven Organization (Recommended for Large Apps)
-
-For larger applications, organize by domain with internal structure:
-
-```
-src/
-├── domains/
-│   ├── events/
-│   │   ├── components/
-│   │   │   ├── EventCard.tsx
-│   │   │   └── EventList.tsx
-│   │   ├── hooks/
-│   │   │   └── useEventData.ts
-│   │   ├── services/
-│   │   │   └── EventService.ts
-│   │   ├── types.ts
-│   │   └── index.ts              # Domain barrel export
-│   │
-│   └── users/
-│       ├── components/
-│       ├── hooks/
-│       ├── services/
-│       ├── types.ts
-│       └── index.ts
-│
-├── shared/                        # Shared across domains
-│   ├── components/
-│   │   ├── Layout.tsx
-│   │   └── Navigation.tsx
-│   ├── hooks/
-│   │   └── useAppConfig.ts
-│   └── utils/
-│       └── formatDate.ts
-│
-└── pages/
-    ├── events/
-    │   ├── EventsListPage.tsx
-    │   └── EventDetailPage.tsx
-    └── users/
-        └── UsersPage.tsx
-```
-
-**When to use:** Large apps with multiple distinct domains (> 20 features, clear domain boundaries)
-
-### Pattern 3: Hybrid Organization
-
-Combine feature-based and domain-based as needed:
-
-```
-src/
-├── components/
-│   ├── events/                   # Feature-based (simple features)
-│   └── shared/                   # Shared components
-│
-├── domains/
-│   └── complex-feature/          # Domain-based (complex features)
-│       ├── components/
-│       ├── hooks/
-│       └── services/
-│
-└── pages/
-    └── [pages organized by route]
-```
-
-**When to use:** Apps with mixed complexity levels
+**Why feature-based?** Since pace apps are already split by domain, organizing code by feature within each app provides:
+- **Clear boundaries** - Related code stays together
+- **Easy navigation** - Find all code for a feature in one place
+- **Simplified imports** - Consistent path structure
+- **Better maintainability** - Changes to a feature are localized
 
 ---
 
@@ -582,7 +520,7 @@ src/
 ```
 
 **Migration Steps:**
-1. Group components by feature/domain
+1. Group components by feature
 2. Move to `src/components/[feature]/`
 3. Remove duplicate pace-core components (use pace-core instead)
 4. Update imports to use path aliases
@@ -613,7 +551,7 @@ src/
 ```
 
 **Migration Steps:**
-1. Identify features/domains in your app
+1. Identify features in your app
 2. Reorganize by feature, not type
 3. Use pace-core for UI primitives (Button, Input, Card)
 4. Keep only feature-specific components
@@ -694,7 +632,7 @@ your-app/
    git commit -am "Backup before structure migration"
    ```
 
-3. **Identify Features/Domains**
+3. **Identify Features**
    - List all features in your app
    - Group related components/hooks/utils
    - Identify pace-core duplicates