@trackunit/iris-app 1.4.9 → 1.4.10

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 1.4.10 (2025-07-11)
+
+### 🧱 Updated Dependencies
+
+- Updated iris-app-build-utilities to 1.4.10
+- Updated iris-app-webpack-plugin to 1.4.10
+- Updated iris-app-api to 1.4.10
+- Updated react-test-setup to 1.1.10
+- Updated shared-utils to 1.6.10
+
 ## 1.4.9 (2025-07-11)
 
 ### 🧱 Updated Dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/iris-app",
-  "version": "1.4.9",
+  "version": "1.4.10",
   "license": "SEE LICENSE IN LICENSE.txt",
   "main": "src/index.js",
   "generators": "./generators.json",
@@ -32,12 +32,12 @@
     "@npmcli/arborist": "^7.3.1",
     "webpack-bundle-analyzer": "^4.8.0",
     "win-ca": "^3.5.1",
-    "@trackunit/iris-app-build-utilities": "1.4.9",
-    "@trackunit/shared-utils": "1.6.9",
-    "@trackunit/iris-app-api": "1.4.9",
-    "@trackunit/iris-app-webpack-plugin": "1.4.9",
+    "@trackunit/iris-app-build-utilities": "1.4.10",
+    "@trackunit/shared-utils": "1.6.10",
+    "@trackunit/iris-app-api": "1.4.10",
+    "@trackunit/iris-app-webpack-plugin": "1.4.10",
     "tslib": "^2.6.2",
-    "@trackunit/react-test-setup": "1.1.9"
+    "@trackunit/react-test-setup": "1.1.10"
   },
   "types": "./src/index.d.ts",
   "type": "commonjs"

package/src/generators/preset/files/.cursor/rules/irisx-app-sdk-customfields.mdc

@@ -0,0 +1,311 @@
+---
+description: CustomFields are the primary mechanism for storing data from IrisX applications. They allow IrisX App developers to extend the Trackunit data model by storing additional information on entities like assets, accounts, groups, and sites. 
+globs: 
+alwaysApply: false
+---
+
+# CustomFields Rule for Trackunit IrisX App SDK
+
+## Overview
+**CustomFields are the primary mechanism for storing data from IrisX applications.** They allow IrisX App developers to extend the Trackunit data model by storing additional information on entities like assets, accounts, groups, and sites. 
+
+### Key Use Cases:
+- **Extending the data model**: Add new fields and attributes to existing Trackunit entities
+- **Storing user input**: Capture and persist form data, user preferences, and settings
+- **Storing metadata**: Keep application-specific information, configuration data, and operational metrics
+- **Fleet-specific data**: Custom attributes unique to specific fleet management needs
+- **Performance metrics**: Custom KPIs and measurement data not available in standard Trackunit data
+- **Business logic data**: Information required for app-specific workflows and processes
+
+**Important**: CustomFields are the recommended and supported way to persist any data your IrisX app needs to store. Do not attempt to use external databases or storage solutions - use CustomFields for all persistent data requirements.
+
+## 1. Defining Custom Fields
+
+### Manifest Configuration
+
+Custom fields must be defined in your IrisX App manifest using the `customFieldDefinitions` array:
+
+```typescript
+// In your app manifest
+customFieldDefinitions: [
+  {
+    type: 'STRING',
+    entityType: 'ASSET',
+    key: 'myCustomField',
+    translations: [{
+      language: 'en',
+      title: 'My Custom Field',
+      description: 'Description of what this field stores',
+    }],
+    uiEditable: true,
+    uiVisible: true,
+    scopeType: ScopeType.ACCOUNT
+  }
+]
+```
+
+### Required Properties
+
+- **`type`**: Field data type (see supported types below)
+- **`entityType`**: Entity the field applies to (`ACCOUNT`, `ASSET`, `GROUP`, `SITE`)
+- **`key`**: Programmatic identifier (cannot be changed after creation)
+- **`translations`**: UI labels and descriptions for each supported language
+- **`scopeType`**: Data access scope (see scope types below)
+
+### Optional Properties
+
+- **`uiEditable`**: Whether field can be edited in Manager UI (default: true)
+- **`uiVisible`**: Whether field is visible in Manager UI (default: true)
+
+## 2. Supported Field Types
+
+| Type | Description | Extra Properties |
+|------|-------------|------------------|
+| `BOOLEAN` | True/false values | - |
+| `DATE` | ISO8601 formatted dates | - |
+| `DROPDOWN` | Predefined option lists | `allValues`, `multiSelect`, `dropDownValueReplacements` |
+| `EMAIL` | Email addresses with mailto links | - |
+| `NUMBER` | Numeric values | `minimum`, `maximum`, `isInteger`, `unitSi`, `unitUs` |
+| `PHONE_NUMBER` | E.164 formatted phone numbers | - |
+| `STRING` | Free text | `minimumLength`, `maximumLength`, `pattern` |
+| `WEB_ADDRESS` | URLs as clickable links | - |
+| `JSON` | JSON objects | - |
+| `MONETARY` | Currency values (ISO 4217) | `minimum`, `maximum`, `currency` |
+
+### Example Field Definitions
+
+```typescript
+// String field with validation
+{
+  type: 'STRING',
+  entityType: 'ASSET',
+  key: 'serialNumber',
+  translations: [{ language: 'en', title: 'Serial Number', description: 'Asset serial number' }],
+  minimumLength: 5,
+  maximumLength: 20,
+  pattern: '^[A-Z0-9]+$'
+}
+
+// Number field with units
+{
+  type: 'NUMBER',
+  entityType: 'ASSET',
+  key: 'fuelCapacity',
+  translations: [{ language: 'en', title: 'Fuel Capacity', description: 'Tank capacity' }],
+  minimum: 0,
+  maximum: 1000,
+  unitSi: 'L',
+  unitUs: 'gal'
+}
+
+// Dropdown with multiple selection
+{
+  type: 'DROPDOWN',
+  entityType: 'ASSET',
+  key: 'features',
+  translations: [{ language: 'en', title: 'Features', description: 'Available features' }],
+  allValues: ['GPS', 'Camera', 'Bluetooth', 'WiFi'],
+  multiSelect: true
+}
+```
+
+## 3. Scope Types
+
+| Scope | Description |
+|-------|-------------|
+| `ACCOUNT` | Values shared within a single account only |
+| `ACCOUNT_WRITE_GLOBAL_READ` | Account can write, all accounts can read |
+| `GLOBAL` | Values shared between all accounts with entity access |
+
+## 4. Using Custom Fields in React Components
+
+### Required Hooks
+
+Use these hooks to interact with custom fields:
+
+```typescript
+import { 
+  useCustomFieldsValueAndDefinition,
+  useUpdateCustomFieldValues,
+  useCurrentUserSystemOfMeasurement
+} from '@trackunit/react-core-contexts-host';
+```
+
+### Basic Implementation Pattern
+
+```typescript
+import React from 'react';
+import { useForm } from 'react-hook-form';
+import { Card, CardBody, CardHeader, CardFooter, Button, Spinner } from '@trackunit/react-components';
+import { CustomField } from '@trackunit/react-core-contexts-host';
+
+const CustomFieldsForm = ({ assetId }: { assetId: string }) => {
+  const { register, handleSubmit, formState, setValue, control } = useForm({
+    shouldUnregister: false,
+  });
+  
+  const { systemOfMeasurement } = useCurrentUserSystemOfMeasurement();
+  
+  const { fields, loading } = useCustomFieldsValueAndDefinition({
+    entityType: "ASSET",
+    entityId: assetId,
+    systemOfMeasurement: systemOfMeasurement ?? "SI",
+  });
+  
+  const { updateCustomFields, inProgress } = useUpdateCustomFieldValues(
+    assetId,
+    "ASSET",
+    fields,
+    systemOfMeasurement ?? "SI"
+  );
+
+  if (loading) {
+    return <Spinner />;
+  }
+
+  return (
+    <Card>
+      <CardHeader heading="Custom Fields" />
+      <CardBody>
+        {fields.map(field => {
+          const isEditable = field.valueEditable && (field.definition.uiEditable ?? true);
+          return (
+            <CustomField
+              key={field.definition.key}
+              control={control}
+              field={field}
+              formState={formState}
+              isEditable={isEditable}
+              register={register}
+              setValue={setValue}
+              unitPreference={systemOfMeasurement}
+            />
+          );
+        })}
+      </CardBody>
+      <CardFooter>
+        <Button 
+          loading={inProgress} 
+          onClick={handleSubmit(updateCustomFields)}
+        >
+          {inProgress ? "Saving..." : "Save Changes"}
+        </Button>
+      </CardFooter>
+    </Card>
+  );
+};
+```
+
+## 5. Best Practices
+
+### Field Design
+- **Use descriptive keys**: Choose clear, descriptive field keys that won't need changing
+- **Add proper translations**: Always provide meaningful titles and descriptions
+- **Set appropriate constraints**: Use min/max values, length limits, and patterns for validation
+- **Consider data types**: Choose the most appropriate type for your data
+
+### Performance
+- **Batch updates**: Use `useUpdateCustomFieldValues` to update multiple fields at once
+- **Handle loading states**: Always show loading indicators while fetching data
+- **Error handling**: Implement proper error handling for failed updates
+
+### Data Management
+- **Plan for migration**: Consider existing data when changing field definitions
+- **Use appropriate scopes**: Choose the right scope type for your data sharing needs
+- **Validate user input**: Implement client-side validation matching your field constraints
+
+## 6. Common Use Cases
+
+### Fleet Management
+```typescript
+// Store vehicle-specific information
+{
+  type: 'NUMBER',
+  entityType: 'ASSET',
+  key: 'fuelEfficiency',
+  translations: [{ language: 'en', title: 'Fuel Efficiency', description: 'Miles per gallon' }],
+  unitSi: 'L/100km',
+  unitUs: 'mpg'
+}
+```
+
+### Asset Utilization
+```typescript
+// Track custom performance metrics
+{
+  type: 'JSON',
+  entityType: 'ASSET',
+  key: 'performanceMetrics',
+  translations: [{ language: 'en', title: 'Performance Data', description: 'Custom metrics' }]
+}
+```
+
+### Driver Safety
+```typescript
+// Store safety-related information
+{
+  type: 'DROPDOWN',
+  entityType: 'ASSET',
+  key: 'safetyRating',
+  translations: [{ language: 'en', title: 'Safety Rating', description: 'Driver safety score' }],
+  allValues: ['Excellent', 'Good', 'Fair', 'Poor']
+}
+```
+
+## 7. Local Development
+
+- Custom fields are available immediately in local development
+- Changes to field definitions require app redeployment
+- Test with various data types and edge cases
+- Verify validation rules work as expected
+
+## 8. Deployment Considerations
+
+- **Field keys are immutable**: Cannot be changed after creation
+- **Definition updates**: Changing field definitions affects all existing data
+- **Migration planning**: Consider data migration when modifying existing fields
+- **Approval process**: Custom field changes require app approval and marketplace submission
+
+## 9. Error Handling
+
+```typescript
+const CustomFieldsComponent = () => {
+  const { fields, loading, error } = useCustomFieldsValueAndDefinition({
+    entityType: "ASSET",
+    entityId: assetId,
+    systemOfMeasurement: systemOfMeasurement ?? "SI",
+  });
+
+  if (loading) return <Spinner />;
+  if (error) return <ErrorState message="Failed to load custom fields" />;
+  
+  // Render fields...
+};
+```
+
+## 10. Integration with Trackunit Components
+
+Always use the provided `CustomField` component for consistent UI:
+
+```typescript
+import { CustomField } from '@trackunit/react-core-contexts-host';
+
+// This handles all field types automatically
+<CustomField
+  control={control}
+  field={field}
+  formState={formState}
+  isEditable={isEditable}
+  register={register}
+  setValue={setValue}
+  unitPreference={systemOfMeasurement}
+/>
+```
+
+## References
+
+- [Save Data from Your App](https://developers.trackunit.com/docs/save-data-from-your-app)
+- [Defining a Custom Field](https://developers.trackunit.com/docs/defining-a-custom-field)
+- [Using a Custom Field](https://developers.trackunit.com/docs/using-a-custom-field)
+- [Local Development](https://developers.trackunit.com/docs/local-development)
+- [Deploying a New Custom Field](https://developers.trackunit.com/docs/deploying-a-new-custom-field) 

package/src/generators/preset/files/.cursor/rules/irisx-app-sdk.mdc

@@ -5,6 +5,23 @@ alwaysApply: true
 ---
 You are currently in an IrisX App workspace. Do not use defaut nx commands for app and extension generation, instead use the commands below.
 
+## Building Real Applications
+
+You are building real applications that work with actual Trackunit data. Key principles:
+
+- Never mock data unless explicitly requested by the user
+- Always use Trackunit's GraphQL API to fetch real data
+- If data is not available via GraphQL, ask the user how they want to obtain the data
+- Only use mock data if the user explicitly requests it for testing purposes
+
+When building any feature:
+1. Identify what data you need
+2. Check if it's available via Trackunit's GraphQL API
+3. If available, use the GraphQL API (see GraphQL rules for implementation)
+4. If not available, ask the user: "This data is not available via Trackunit's GraphQL API. How would you like to obtain [specific data description]?"
+
+## IrisX App Development Guidelines
+
 Key Points:
 1. An IrisX App is a container that packages multiple extensions with marketplace metadata and app manifest
 2. Extensions are React applications that integrate into specific points in Trackunit Manager
@@ -48,6 +65,16 @@ cspHeader: {
 
 For more information: [Embedding IrisX Dashboards in Apps](mdc:https:/developers.trackunit.com/docs/analytics-dashboards-in-apps#troubleshooting)
 
+
+## Runtime Hooks Available
+
+IrisX Apps have access to runtime hooks from `@trackunit/react-core-hooks` that provide context-specific data:
+- `useAssetRuntime()` for asset information in asset-scoped extensions
+- `useCustomerRuntime()` for customer data
+- `useEventRuntime()` for event details
+- `useSiteRuntime()` for site information
+- Plus navigation, user context, and utility hooks (see react-core-hooks rule for full list)
+
 DO NOT use generic React/Node.js commands for project creation or management - always use the Trackunit IrisX App SDK commands.
 
 

package/src/generators/preset/files/.cursor/rules/react-core-hooks.mdc

@@ -0,0 +1,160 @@
+---
+description: Use these rules whne building App SDK specific React Hook, Runtime Hooks
+alwaysApply: false
+---
+## React Core Hooks Library
+
+Available hooks from `@trackunit/react-core-hooks` for IrisX App development.
+
+### Runtime Hooks
+
+**`useAssetRuntime()`** - Access asset information in asset-scoped extensions
+```typescript
+const { assetInfo, loading, error } = useAssetRuntime();
+// assetInfo.assetId, assetInfo.name, etc.
+```
+
+**`useCustomerRuntime()`** - Access customer information
+```typescript
+const { customerInfo, loading, error } = useCustomerRuntime();
+// customerInfo.customerId, customerInfo.name, etc.
+```
+
+**`useEventRuntime()`** - Access event information in event-scoped extensions
+```typescript
+const { eventInfo, loading, error } = useEventRuntime();
+// eventInfo.eventId, eventInfo.type, etc.
+```
+
+**`useSiteRuntime()`** - Access site information in site-scoped extensions
+```typescript
+const { siteInfo, loading, error } = useSiteRuntime();
+// siteInfo.siteId, siteInfo.name, etc.
+```
+
+**`useIrisAppName()`** - Get current app name
+```typescript
+const { appName, loading, error } = useIrisAppName();
+```
+
+**`useIrisAppId()`** - Get current app ID
+```typescript
+const { irisAppId, loading, error } = useIrisAppId();
+```
+
+### Navigation & User Context
+
+**`useNavigateInHost()`** - Navigate within Trackunit Manager
+```typescript
+const { navigateToAsset, navigateToSite } = useNavigateInHost();
+navigateToAsset({ assetId: "123" });
+```
+
+**`useHasAccessTo()`** - Check user permissions
+```typescript
+const hasAccess = useHasAccessTo({ permission: "assets.read" });
+```
+
+**`useCurrentUser()`** - Access current user information
+```typescript
+const { user } = useCurrentUser();
+// user.id, user.email, etc.
+```
+
+**`useCurrentUserLanguage()`** - Get/set user language preference
+```typescript
+const { language, setLanguage } = useCurrentUserLanguage();
+```
+
+**`useCurrentUserTimeZonePreference()`** - Get user timezone
+```typescript
+const { timeZone } = useCurrentUserTimeZonePreference();
+```
+
+**`useToken()`** - Access authentication token
+```typescript
+const { token } = useToken();
+```
+
+### UI & Interaction
+
+**`useToast()`** - Show toast notifications
+```typescript
+const { showToast } = useToast();
+showToast({ message: "Success!", type: "success" });
+```
+
+**`useConfirmationDialog()`** - Show confirmation dialogs
+```typescript
+const { showConfirmationDialog } = useConfirmationDialog();
+const confirmed = await showConfirmationDialog({ message: "Are you sure?" });
+```
+
+**`useModalDialogContext()`** - Manage modal dialogs
+```typescript
+const { openModal, closeModal } = useModalDialogContext();
+```
+
+**`useErrorHandler()`** - Handle errors consistently
+```typescript
+const { handleError } = useErrorHandler();
+handleError(new Error("Something went wrong"));
+```
+
+### Data & State Management
+
+**`useLocalStorage()`** - Persist state in localStorage
+```typescript
+const [value, setValue, reset] = useLocalStorage({
+  key: "myKey",
+  defaultState: { count: 0 }
+});
+```
+
+**`useLocalStorageReducer()`** - localStorage with reducer pattern
+```typescript
+const [state, dispatch] = useLocalStorageReducer({
+  key: "counterState",
+  defaultState: { count: 0 },
+  reducer: (state, action) => { /* reducer logic */ }
+});
+```
+
+**`useAssetSorting()`** - Asset sorting functionality
+```typescript
+const { sortField, sortDirection, setSorting } = useAssetSorting();
+```
+
+**`useFilterBarContext()`** - Filter bar state management
+```typescript
+const { filters, setFilters, clearFilters } = useFilterBarContext();
+```
+
+**`useTimeRange()`** - Time range selection
+```typescript
+const { timeRange, setTimeRange } = useTimeRange();
+```
+
+
+
+### Widget Configuration
+
+**`useWidgetConfig()`** - Access widget configuration (synchronous)
+```typescript
+const config = useWidgetConfig();
+```
+
+**`useWidgetConfigAsync()`** - Access widget configuration (asynchronous)
+```typescript
+const { getConfig, setConfig } = useWidgetConfigAsync();
+const config = await getConfig();
+```
+
+
+
+
+
+All hooks require their respective providers to be set up in your app's component tree.
+
+```
+

package/src/generators/preset/files/.cursor/rules/widget-extensions.mdc

@@ -0,0 +1,325 @@
+---
+description: Use these rules when building Widget Extensions for an Iris App.
+globs: 
+alwaysApply: false
+---
+
+# Widget Extensions
+
+Widget extensions are specialized components that integrate into Trackunit Manager's dashboard systems, providing customizable UI elements for data visualization and user interaction.
+
+## Key Concepts
+
+1. **Widget Extensions** are React applications that render within widget containers on various pages
+2. **Supported Locations** define where widgets can be placed in Trackunit Manager
+3. **Widget Types** categorize widgets by their primary purpose and visual style
+4. **Filter Support** enables widgets to respond to user-applied filters
+5. **Configuration** allows widgets to store and manage their own settings
+
+## Creating Widget Extensions
+
+### Generate a new widget extension:
+```bash
+npx nx g @trackunit/iris-app:extend --name=[my-widget-name] --directory=[feature] --type=WIDGET_EXTENSION
+```
+
+This creates:
+- `extension-manifest.ts` - Widget configuration and metadata
+- `src/app.tsx` - Main widget component
+- `src/editDialog.tsx` - Configuration dialog (if `hasEditDialog: true`)
+
+## Widget Extension Manifest
+
+The manifest defines widget metadata, appearance, and behavior:
+
+```typescript
+import { WidgetExtensionManifest } from '@trackunit/iris-app-api';
+
+const widgetExtensionManifest: WidgetExtensionManifest = {
+  id: "my-widget-id",
+  type: "WIDGET_EXTENSION",
+  sourceRoot: "libs/[feature]/[widget-name]/src",
+  
+  widgetType: "CHART", // Required: Widget classification
+  
+  size: {
+    default: {
+      width: 2,  // 1-6 grid units
+      height: 2, // 1-6 grid units
+    },
+    allowFullWidth: false, // Optional: Allow full-width expansion
+  },
+  
+  header: {
+    name: "My Widget", // Display name
+    image: { name: "ChartBar" }, // Icon (IconByName or IconByPath)
+    hasEditDialog: true, // Optional: Enable edit button
+  },
+  
+  footer: { // Optional: Footer with link
+    linkDescription: "View details",
+    link: "/my-app/details",
+    poweredByImage: { path: "/assets/logo.svg" },
+  },
+  
+  preview: { // Optional: Description for widget drawer
+    description: "Displays chart data for analysis",
+  },
+  
+  supportedLocations: ["MY_HOME", "SITE_HOME"],
+  
+  supportedFilters: { // Optional: Enable filter support
+    TIME_RANGE: { include: ["ALL"] },
+    ASSETS: { include: ["assetType", "brands", "models"] },
+    CUSTOMERS: { include: ["customerType", "criticality"] },
+    SITES: { include: ["siteType", "location"] },
+  },
+};
+
+export default widgetExtensionManifest;
+```
+
+## Widget Types
+
+Available widget types that determine visual presentation:
+
+- **`"KPI"`** - Single metric displays (typically 1x1 size)
+- **`"CHART"`** - Data visualization widgets (charts, graphs)
+- **`"LIST"`** - Tabular or list-based data presentation
+- **`"MAP"`** - Geographic or spatial data visualization
+- **`"OTHER"`** - Custom or specialized widgets
+
+## Supported Locations
+
+Widgets can be placed in these locations:
+
+- **`"MY_HOME"`** - User's personal dashboard
+- **`"SITE_HOME"`** - Site-specific dashboards
+
+## Widget Development
+
+### Basic Widget Component
+
+```typescript
+import { useWidgetConfig } from '@trackunit/react-core-hooks';
+
+export const App = () => {
+  const { 
+    data, 
+    setData, 
+    dataVersion,
+    title, 
+    setTitle,
+    filters,
+    timeRange,
+    isEditMode,
+    openEditMode,
+    closeEditMode
+  } = useWidgetConfig();
+
+  if (isEditMode) {
+    return <EditDialog />;
+  }
+
+  return (
+    <div>
+      <h2>{title}</h2>
+      {/* Widget content */}
+    </div>
+  );
+};
+```
+
+### Widget Configuration Hook
+
+The `useWidgetConfig()` hook provides:
+
+**Data Management:**
+- `data: Record<string, unknown>` - Widget configuration data
+- `setData: (data: Record<string, unknown>, version: number) => Promise<void>` - Update widget data
+- `dataVersion: number` - Current data version for migrations
+
+**Title Management:**
+- `title: string` - Widget title
+- `setTitle: (title: string) => Promise<void>` - Update widget title
+
+**Context Information:**
+- `filters: { assetsFilterBarValues, customersFilterBarValues, sitesFilterBarValues }` - Applied filters
+- `timeRange: { startMsInEpoch, endMsInEpoch }` - Selected time range
+- `isEditMode: boolean` - Whether widget is in edit mode
+
+**Edit Mode Control:**
+- `openEditMode: () => Promise<void>` - Enter edit mode
+- `closeEditMode: () => Promise<void>` - Exit edit mode
+
+### Widget with Edit Dialog
+
+```typescript
+import { useWidgetConfig } from '@trackunit/react-core-hooks';
+import { WidgetEditBody } from '@trackunit/react-widgets';
+
+export const App = () => {
+  const { isEditMode, data, setData, closeEditMode } = useWidgetConfig();
+  
+  if (isEditMode) {
+    return (
+      <WidgetEditBody
+        onSave={(newData) => {
+          setData(newData, 1);
+          closeEditMode();
+        }}
+        onCancel={closeEditMode}
+        initialData={data}
+      />
+    );
+  }
+  
+  return <MainWidgetContent />;
+};
+```
+
+## Filter Support
+
+### Supported Filter Types
+
+Configure which filters your widget responds to:
+
+```typescript
+supportedFilters: {
+  // Time range filtering
+  TIME_RANGE: { include: ["ALL"] },
+  
+  // Asset filtering
+  ASSETS: { 
+    include: [
+      "assetType", "brands", "models", "types", 
+      "activity", "criticality", "lastSeen", "groups",
+      "siteIds", "customerIds", "ownerAccountIds",
+      // Add custom fields support
+      ...allAssetFilterKeysWithCustomFields
+    ]
+  },
+  
+  // Customer filtering
+  CUSTOMERS: { 
+    include: [
+      "customerType", "criticality", "servicePlan",
+      ...allCustomerFilterKeysWithCustomFields
+    ]
+  },
+  
+  // Site filtering
+  SITES: { 
+    include: [
+      "siteType", "location", "area",
+      ...allSiteFilterKeysWithCustomFields
+    ]
+  },
+}
+```
+
+### Using Filters in Widgets
+
+```typescript
+const { filters, timeRange } = useWidgetConfig();
+
+// Access filter values
+const selectedAssets = filters.assetsFilterBarValues?.assetType;
+const selectedCustomers = filters.customersFilterBarValues?.customerType;
+const selectedSites = filters.sitesFilterBarValues?.siteType;
+
+// Use time range
+const startTime = timeRange?.startMsInEpoch;
+const endTime = timeRange?.endMsInEpoch;
+```
+
+## Widget Lifecycle
+
+### 1. Widget Creation
+- Generated via `@trackunit/iris-app:extend` command
+- Manifest defines widget metadata and capabilities
+- React component handles rendering and user interaction
+
+### 2. Widget Registration
+- Widget appears in the widget drawer based on `supportedLocations`
+- Users can add widgets to their dashboards
+- Widget configuration is persisted automatically
+
+### 3. Widget Runtime
+- Widget receives context (filters, time range, etc.)
+- Widget can store and retrieve configuration data
+- Widget responds to user interactions and filter changes
+
+## Best Practices
+
+### Widget Design
+1. **Responsive Layout** - Design for different grid sizes
+2. **Loading States** - Show loading indicators for async operations
+3. **Error Handling** - Gracefully handle data loading errors
+4. **Empty States** - Provide meaningful empty state messages
+
+### Data Management
+1. **Use Real Data** - Always fetch from Trackunit GraphQL API
+2. **Respect Filters** - Apply user-selected filters to your data queries
+3. **Efficient Updates** - Only update widget data when necessary
+4. **Version Control** - Use `dataVersion` for configuration migrations
+
+### Configuration
+1. **Meaningful Defaults** - Provide sensible default configurations
+2. **Validation** - Validate user input in edit dialogs
+3. **Persistence** - Use `setData()` to save configuration changes
+4. **User Experience** - Keep configuration UI simple and intuitive
+
+## Example: KPI Widget
+
+```typescript
+import { useWidgetConfig } from '@trackunit/react-core-hooks';
+import { useQuery } from '@apollo/client';
+
+export const App = () => {
+  const { filters, timeRange, data } = useWidgetConfig();
+  
+  const { data: kpiData, loading } = useQuery(MY_KPI_QUERY, {
+    variables: {
+      filters: {
+        assetIds: filters.assetsFilterBarValues?.assetIds,
+        timeRange: {
+          start: timeRange?.startMsInEpoch,
+          end: timeRange?.endMsInEpoch,
+        },
+      },
+    },
+  });
+
+  if (loading) return <Spinner />;
+  
+  return (
+    <div className="kpi-widget">
+      <div className="kpi-value">{kpiData?.totalCount}</div>
+      <div className="kpi-label">Total Assets</div>
+    </div>
+  );
+};
+```
+
+## Common Patterns
+
+### Chart Widget
+- Use `widgetType: "CHART"`
+- Implement responsive chart sizing
+- Support time range filtering
+- Show data trends and comparisons
+
+### List Widget
+- Use `widgetType: "LIST"`
+- Implement pagination for large datasets
+- Support asset/customer filtering
+- Provide links to detailed views
+
+### Map Widget
+- Use `widgetType: "MAP"`
+- Set `allowFullWidth: true` for better visibility
+- Support location-based filtering
+- Show asset positions and movement
+
+DO NOT use generic React widget libraries - always use the Trackunit IrisX App SDK widget patterns and components.