@trackunit/iris-app 1.12.7 → 1.12.10

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

@@ -1,155 +0,0 @@
-## 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 { getData, setData } = 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/rules-index.mdc

@@ -1,10 +0,0 @@
----
-alwaysApply: true
----
-This file contains a list of helpful information and context that the agent can reference when working in this codebase. Each entry provides specific guidance or rules for different aspects of the project. You can read these files using the readFile tool if the users prompt seems related.
-
-- [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.](./irisx-app-sdk-customfields.md)
-- [This rule covers GraphQL API integration in Trackunit IrisX App SDK workspace. All GraphQL development MUST follow the Trackunit GraphQL API patterns and commands.](./irisx-app-sdk-graphql.md)
-- [Time series API, get time series data from GraphQL. Machine insights data over time.](./graphql-timeseries.md)
-- [Use these rules when building Widget Extensions for an Iris App.](./widget-extensions.md)
-- [Use these rules whne building App SDK specific React Hook, Runtime Hooks](./react-core-hooks.md)

package/src/generators/preset/files/.cursor/rules/structured-development.mdc

@@ -1,86 +0,0 @@
----
-alwaysApply: true
----
-
-# Structured Feature Development Documentation
-
-## Overview
-When developing new features, maintain concise documentation to track progress, decisions, and implementation details.
-
-## Process
-1. **Check for existing documentation**: Look in `/docs` folder for a markdown file named after the feature (e.g., `user-authentication.md`, `shopping-cart.md`)
-2. **Create or update**: 
-   - If documentation exists: Update it with new requirements and progress
-   - If it doesn't exist: Create a new file with the feature name as filename
-3. **Use visual aids**: Include mermaid diagrams for complex flows, architecture, or data relationships
-4. **Keep it current**: Update the documentation as development progresses
-
-## Important Guidelines
-- **Be concise**: Keep descriptions brief and to the point
-- **Only document what was requested**: Do not make up future steps or tasks that weren't part of the user's suggestions, unless explitly asked.
-- **Focus on implementation**: Document what was actually built, not theoretical features
-
-## Task Analysis Process
-1. **Analyze the user's request**: Understand exactly what the user asked for
-2. **Break down into tasks**: Split the request into specific, actionable tasks
-3. **Document only requested work**: Only include tasks that directly relate to the user's request
-4. **Optional sections**: Todo and In Progress sections are OPTIONAL - only include them if there are actual remaining tasks from the user's request
-
-## Required File Structure
-
-### File Naming
-Use kebab-case naming convention: `feature-name.md`
-
-### Template Structure
-
-```markdown
-# Feature Name
-
-## Description
-Brief overview of what the feature does and why it's needed.
-
-## Architecture
-Technical approach and key design decisions.
-
-## Progress Tracking
-
-### ✅ Completed Steps
-- [x] Task 1: Description
-- [x] Task 2: Description
-
-### 🔄 In Progress  
-*OPTIONAL: Only include if there are actual tasks from the user's request that are currently being worked on*
-- [ ] Task 3: Description
-- [ ] Task 4: Description
-
-### 📝 Todo
-*OPTIONAL: Only include if there are remaining tasks from the user's request that haven't been started*
-- [ ] Task 5: Description
-- [ ] Task 6: Description
-
-## Technologies Used
-- **Technology Name**: Brief description of usage
-- **Library Name**: Version and purpose
-
-## Implementation Details
-Key technical specifics:
-- API endpoints used
-- Configuration requirements
-- Performance considerations
-
-## Good To Know
-Important findings, decisions, and gotchas:
-- Quirks or workarounds implemented
-- Alternative approaches considered
-- Performance implications
-- Security considerations
-- Testing strategies
-```
-
-## Best Practices
-- Keep descriptions brief and focused
-- Only document requested features and tasks
-- Include mermaid diagrams for complex flows
-- Document actual implementation details
-- Update progress as development happens
-- **CRITICAL**: Never add tasks or features that weren't explicitly mentioned in the user's request

package/src/generators/preset/files/.cursor/rules/tables-and-sorting.mdc

@@ -1,126 +0,0 @@
----
-alwaysApply: false
----
-# 📊 Trackunit Table with Filtering & Sorting
-
-Create interactive data tables with server-side filtering, sorting, and pagination using Trackunit components and GraphQL.
-
-## 🎯 When to Apply
-- Building asset management interfaces
-- Creating user administration tables  
-- Developing dashboard data grids
-- Implementing reporting interfaces with large datasets
-- Any UI requiring interactive table features (filter/sort/paginate)
-
-## 🔧 Required Imports
-```typescript
-import { Table, useTable, TextCell, DateCell } from '@trackunit/react-table';
-import { FilterBar, useFilterBar } from '@trackunit/filters-filter-bar';
-import { usePaginationQuery } from '@trackunit/react-graphql-hooks';
-import { createColumnHelper, SortingState } from '@tanstack/react-table';
-import { useBrandFilter, useModelFilter } from '@trackunit/filters-asset-filters';
-```
-
-## ✅ Valid Implementation
-
-```typescript
-const AssetTable = () => {
-  // Setup filters with proper naming
-  const filterBar = useFilterBar({
-    name: "assetFilters",
-    filterBarDefinition: { 
-      brand: useBrandFilter(),
-      model: useModelFilter() 
-    }
-  });
-
-  // Server-side sorting state
-  const [sorting, setSorting] = useState<SortingState>([]);
-
-  // GraphQL query with filters
-  const { data, loading, error, pagination } = usePaginationQuery(GetAssetsDocument, {
-    variables: { first: 50, ...filterBar.selectedFilters },
-    pageSize: 50,
-  });
-
-  // Transform data with useMemo
-  const assets = useMemo(() => 
-    data?.assets.edges.map(edge => ({ ...edge.node, id: edge.node.id })) ?? [], 
-    [data]
-  );
-
-  // Define columns with proper cell components
-  const columns = useMemo(() => [
-    columnHelper.accessor('name', {
-      cell: ({ row: { original } }) => <TextCell text={original.name} />,
-      header: "Asset Name",
-      enableSorting: true,
-    }),
-    columnHelper.accessor('createdAt', {
-      cell: ({ row: { original } }) => <DateCell date={original.createdAt} />,
-      header: "Created",
-      enableSorting: true,
-    }),
-  ], []);
-
-  // Setup table with manual sorting
-  const { table } = useTable({
-    data: assets,
-    columns,
-    enableSorting: true,
-    manualSorting: true,
-    state: { sorting },
-    onSortingChange: setSorting,
-  });
-
-  return (
-    <>
-      <FilterBar filterBar={filterBar} />
-      <Table 
-        table={table} 
-        loading={loading} 
-        error={error} 
-        pagination={pagination}
-        onRowClick={(row) => navigateToAsset(row.original.id)}
-      />
-    </>
-  );
-};
-```
-
-## ❌ Invalid Implementation
-
-```typescript
-// DON'T: Missing useMemo optimization
-const columns = [
-  columnHelper.accessor('name', {
-    cell: ({ getValue }) => getValue(), // Wrong: Use TextCell component
-    header: "Name"
-  })
-];
-
-// DON'T: Client-side sorting on large datasets
-const { table } = useTable({
-  data: assets,
-  columns,
-  enableSorting: true,
-  manualSorting: false, // Wrong: Should be true for server-side
-});
-
-// DON'T: Missing filter integration
-const { data } = usePaginationQuery(GetAssetsDocument, {
-  variables: { first: 50 }, // Wrong: Missing filter variables
-});
-
-// DON'T: No row click handler
-<Table table={table} loading={loading} />
-```
-
-## 🎯 Key Requirements
-
-- **Always use `useMemo`** for data transformation and column definitions
-- **Enable `manualSorting: true`** for datasets > 1000 items  
-- **Integrate filter state** with GraphQL variables using spread operator
-- **Use Trackunit cell components** (`TextCell`, `DateCell`) for consistency
-- **Implement `onRowClick`** for navigation or detail views
-- **Sync state properly** between filters, sorting, and GraphQL queries

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

@@ -1,323 +0,0 @@
-# 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] --app=[app-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", "PLAYGROUND"],
-  
-  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
-    pollInterval,
-    setLoadingState
-  } = useWidgetConfig();
-
-  if (isEditMode) {
-    return <EditDialog />;
-  }
-
-  return (
-    <WidgetBody>
-      <h2>{title}</h2>
-      {/* Widget content */}
-    </WidgetBody>
-  );
-};
-```
-
-### 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, closeEditMode } = useWidgetConfig();
-  
-  if (isEditMode) {
-    return (
-      <WidgetEditBody
-        onSave={async () => {
-          await closeEditMode({ newData: { data: { demo: "youDataHere"}, dataVersion: 1 });
-        }}
-        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 '@trackunit/react-graphql-hooks';
-
-export const App = () => {
-  const { filters, timeRange, data, pollInterval, setLoadingState} = useWidgetConfig();
-  
-  const { data: kpiData, loading } = useQuery(MY_KPI_QUERY, {
-    variables: {
-      filters: {
-        assetIds: filters.assetsFilterBarValues?.assetIds,
-        timeRange: {
-          start: timeRange?.startMsInEpoch,
-          end: timeRange?.endMsInEpoch,
-        },
-      },
-    },
-    pollInterval
-  });
-
-  useEffect(() => {
-    void setLoadingState({ hasData: !!kpiData, isLoading: loading });
-  }, [data, loading, setLoadingState]);
-  
-  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.