@trackunit/iris-app 1.12.9 → 1.12.11

package/src/generators/preset/files/.agents/skills/graphql-timeseries/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: graphql-timeseries
+description: Use when querying machine insights, engine metrics, fuel data, operating hours, or building charts with historical time-based data.
+---
+
+# GraphQL Time Series API
+
+## Overview
+
+Query time series data through GraphQL using PromQL (Prometheus Query Language). Use `rangeQuery` for time series charts, `instantQuery` for current values.
+
+## When to Use
+
+- Querying engine metrics (speed, temperature, fuel rate)
+- Building historical data charts
+- Calculating increases over time periods (daily fuel usage, operating hours)
+- Getting current sensor values
+
+**Not for:** Static entity data (use `graphql` skill).
+
+## Query Structure
+
+### Range Query (Time Series Data)
+
+```graphql
+query GetTimeSeriesData($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(query: "metric_name", start: $start, end: $end, step: $step) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result {
+              values { timestamp value }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Instant Query (Single Point in Time)
+
+```graphql
+query GetInstantData($assetId: ID!, $time: DateTime!) {
+  asset(id: $assetId) {
+    timeSeries {
+      instantQuery(query: "metric_name", time: $time) {
+        data {
+          ... on TimeSeriesVectorData {
+            result { value { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Common Metrics
+
+### Machine Insights
+
+Not all assets have all insights. Common metrics include:
+
+**Engine Metrics:**
+- `machine_insight_engine_speed`
+- `machine_insight_engine_coolant_temperature`
+- `machine_insight_engine_oil_pressure`
+- `machine_insight_engine_oil_temperature`
+- `machine_insight_engine_fuel_rate`
+- `machine_insight_engine_total_fuel_used`
+- `machine_insight_engine_percent_load_at_current_speed`
+- `machine_insight_cumulative_engine_hours`
+
+**Fuel & Emissions:**
+- `machine_insight_fuel_level`
+- `machine_insight_fuel_tank_capacity`
+- `machine_insight_fuel_used_last_24`
+- `machine_insight_cumulative_co2_emissions`
+
+**Operating Hours:**
+- `machine_insight_cumulative_operating_hours`
+- `machine_insight_cumulative_idle_hours`
+- `machine_insight_cumulative_moving_hours`
+- `machine_insight_cumulative_productive_hours`
+
+**Battery & Electric:**
+- `machine_insight_battery_state_of_charge_percent`
+- `machine_insight_battery_state_of_health_percent`
+- `machine_insight_battery_temperature`
+- `machine_insight_battery_current`
+- `machine_insight_battery_potential`
+
+**Location & Movement:**
+- `machine_insight_speed`
+- `machine_insight_altitude`
+- `machine_insight_total_vehicle_distance`
+
+**Environmental:**
+- `machine_insight_ambient_air_temperature`
+- `machine_insight_barometric_pressure`
+
+## PromQL Examples
+
+### Calculate Daily Increases
+
+```graphql
+query IncreaseOperatingHours($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(
+        query: "increase(machine_insight_cumulative_operating_hours[1d])",
+        start: $start,
+        end: $end,
+        step: $step
+      ) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result { values { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Filter with Conditions
+
+```graphql
+query HighFuelConsumption($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(
+        query: "increase(machine_insight_engine_total_fuel_used[1d]) > 13",
+        start: $start,
+        end: $end,
+        step: $step
+      ) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result { values { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Combine Metrics
+
+```graphql
+query FuelWithHighIdle($assetId: ID!, $start: DateTime!, $end: DateTime!, $step: Duration!) {
+  asset(id: $assetId) {
+    timeSeries {
+      rangeQuery(
+        query: "(increase(machine_insight_engine_total_fuel_used[1d]) > 13) and (increase(machine_insight_cumulative_idle_hours[1d]) > 4)",
+        start: $start,
+        end: $end,
+        step: $step
+      ) {
+        data {
+          ... on TimeSeriesMatrixData {
+            result { values { timestamp value } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Key Points
+
+- **Always use fragments** for both `TimeSeriesMatrixData` and `TimeSeriesVectorData`
+- **Use PromQL functions**: `increase()`, `rate()`, `avg_over_time()`
+- **Filter at query level** with operators: `>`, `<`, `>=`, `<=`, `==`, `!=`
+- **Time windows** use brackets: `[1d]`, `[1h]`, `[15m]`
+- **Step intervals**: Choose based on data granularity needed
+- **Timestamps** are Unix timestamps in seconds
+- **Values** are returned as strings - convert to numbers as needed
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing fragment for data type | Use `... on TimeSeriesMatrixData` or `TimeSeriesVectorData` |
+| Not handling missing metrics | Not all assets have all insights; handle empty results |
+| Using values as numbers directly | Values are strings; convert with `parseFloat()` |
+| Wrong step interval | Match step to desired chart granularity |

package/src/generators/preset/files/.agents/skills/irisx-app-sdk/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: irisx-app-sdk
+description: Use when creating apps, adding extensions, configuring CSP/scopes, or needing SDK command reference. Core SDK documentation.
+---
+
+# IrisX App SDK Development
+
+## Overview
+
+IrisX Apps are React applications that integrate into Trackunit Manager at defined extension points. Use SDK commands (not generic React/Node.js) for all project operations.
+
+## When to Use
+
+- Creating new apps or extensions
+- Configuring security (CSP headers, scopes)
+- Looking up extension types or SDK commands
+- Understanding runtime hooks availability
+
+**Not for:** GraphQL setup (use `graphql` skill), browser testing (use `browser-testing` skill).
+
+## Extension Points
+
+Extensions are React applications that integrate into specific points in Trackunit Manager:
+
+| Extension Type | Location |
+|----------------|----------|
+| `ASSET_HOME_EXTENSION` | New tabs in Assets Home screen |
+| `SITE_HOME_EXTENSION` | New tabs in Site Home screen |
+| `FLEET_EXTENSION` | Menu items in Main Menu |
+| `REPORT_EXTENSION` | New reports in Reports screen |
+| `WIDGET_EXTENSION` | Dashboard widgets |
+| `IRIS_APP_SETTINGS_EXTENSION` | Configuration UI in App library |
+| `ADMIN_EXTENSION` | Admin UI tabs (admin-only) |
+| `CUSTOMER_HOME_EXTENSION` | UI within Customer Home |
+| `ASSET_EVENTS_ACTIONS_EXTENSION` | UI in Asset Home Events |
+| `LIFECYCLE_EXTENSION` | Handles app install/uninstall events |
+| `SERVERLESS_FUNCTION_EXTENSION` | Serverless backend functions |
+
+## Commands
+
+### Create New App
+
+```bash
+npx nx generate @trackunit/iris-app:create [name-of-your-app]
+```
+
+See: [Creating a new app](https://developers.trackunit.com/docs/creating-a-new-app)
+
+### Create New Extension
+
+```bash
+npx nx g @trackunit/iris-app:extend --name=[my-extension-name] --app=[app-name] --directory=[feature] --type=[extension-type]
+```
+
+See: [Creating a new extension](https://developers.trackunit.com/docs/creating-a-new-extension)
+
+### Run App
+
+```bash
+npx nx run [name-of-your-app]:serve
+```
+
+See: [Running the Iris App SDK](https://developers.trackunit.com/docs/running-the-iris-app-sdk)
+
+## Security Configuration
+
+IrisX Apps are locked down by default. External API requests and embedded content require proper Content Security Policy (CSP) configuration in the app manifest.
+
+### CSP Headers Example
+
+```typescript
+cspHeader: {
+  'frame-src': ['https://api.example.com', 'https://dashboard.example.com'],
+  'script-src': ['https://api.example.com'],
+  'connect-src': ['https://api.example.com'],
+},
+```
+
+### Scopes Example
+
+```typescript
+scopes: [
+  {scope: "required.scope.1", optional: false},
+  {scope: "required.scope.2", optional: true},
+],
+```
+
+Apps requiring API access need scopes configured in the manifest, and the app must be deployed with those scopes to work locally. Never submit an app automatically - instruct the user to do so.
+
+See: [Embedding IrisX Dashboards in Apps](https://developers.trackunit.com/docs/analytics-dashboards-in-apps#troubleshooting)
+
+## Runtime Hooks
+
+IrisX Apps have access to runtime hooks from `@trackunit/react-core-hooks`:
+
+- `useAssetRuntime()` - Asset information in asset-scoped extensions
+- `useCustomerRuntime()` - Customer data
+- `useEventRuntime()` - Event details
+- `useSiteRuntime()` - Site information
+- Plus navigation, user context, and utility hooks
+
+See the `react-core-hooks` skill for full details.
+
+## Quality Assurance
+
+Before completing any task: Always use `read_lints` to check for and fix all ESLint and TypeScript errors in modified files.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `create-react-app` or `npm init` | Use `nx generate @trackunit/iris-app:create` |
+| Mocking data without asking | Always use real GraphQL API |
+| Missing scopes in manifest | Add required scopes; deploy to enable locally |
+| External API blocked | Add domain to `cspHeader` in manifest |
+| Auto-submitting app | Never auto-submit; instruct user to deploy |

package/src/generators/preset/files/.agents/skills/react-core-hooks/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: react-core-hooks
+description: Use when needing asset/site/customer runtime data, user context, navigation, toasts, or confirmation dialogs in IrisX Apps.
+---
+
+# React Core Hooks
+
+## Overview
+
+Reference for `@trackunit/react-core-hooks` - runtime context, navigation, user information, and UI interaction hooks for IrisX Apps.
+
+## When to Use
+
+- Accessing current asset/site/customer context
+- Getting user information or preferences
+- Navigating within Trackunit Manager
+- Showing toasts or confirmation dialogs
+- Managing widget configuration
+
+## 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 { gotoAssetHome, gotoSiteHome } = useNavigateInHost();
+gotoAssetHome(assetId);
+gotoSiteHome(siteId);
+```
+
+### useHasAccessTo
+
+Check user access to pages or asset-scoped pages.
+
+```typescript
+const hasAccess = useHasAccessTo({ page: "sites" });
+const hasAssetAccess = useHasAccessTo({ assetId, page: "asset-home" });
+```
+
+### useCurrentUser
+
+Access current user information. Returns flat properties directly.
+
+```typescript
+const { email, name, accountId, userId } = useCurrentUser();
+```
+
+### useCurrentUserLanguage
+
+Get/set user language preference.
+
+```typescript
+const { language, setLanguage } = useCurrentUserLanguage();
+```
+
+### useCurrentUserTimeZonePreference
+
+Get/set user timezone preference.
+
+```typescript
+const { timeZonePreference, setTimeZonePreference } = useCurrentUserTimeZonePreference();
+```
+
+### useToken
+
+Access authentication token.
+
+```typescript
+const { token } = useToken();
+```
+
+## UI & Interaction
+
+### useToast
+
+Show toast notifications.
+
+```typescript
+const { addToast } = useToast();
+addToast({ intent: "success", title: "Operation completed" });
+```
+
+### useConfirmationDialog
+
+Show confirmation dialogs.
+
+```typescript
+const { confirm } = useConfirmationDialog();
+const confirmed = await confirm({
+  title: "Confirm Action",
+  message: "Are you sure?",
+  primaryActionType: "danger",
+  primaryActionLabel: "Delete",
+  secondaryActionLabel: "Cancel"
+});
+```
+
+### useModalDialogContext
+
+Manage modal dialogs.
+
+```typescript
+const { openModal, closeModal } = useModalDialogContext();
+```
+
+### useErrorHandler
+
+Handle errors consistently.
+
+```typescript
+const { logError } = useErrorHandler();
+logError(new Error("Something went wrong"));
+```
+
+## Data & State Management
+
+### useAssetSorting
+
+Asset sorting functionality.
+
+```typescript
+const { sortingState, setSortBy } = useAssetSorting();
+// sortingState.sortBy, sortingState.order
+```
+
+### useFilterBarContext
+
+Filter bar state management. Provides domain-specific filter values.
+
+```typescript
+const { assetsFilterBarValues, customersFilterBarValues } = useFilterBarContext();
+```
+
+### useTimeRange
+
+Time range context (read-only).
+
+```typescript
+const { timeRange, temporalPeriod } = useTimeRange();
+```
+
+## Widget Configuration
+
+### useWidgetConfig
+
+Access widget configuration, filters, time range, and edit mode state.
+
+```typescript
+const {
+  data, setData, dataVersion, loadingData,
+  title, setTitle,
+  filters, timeRange,
+  isEditMode, openEditMode, closeEditMode,
+  pollInterval, setLoadingState
+} = useWidgetConfig();
+```
+
+## Note
+
+All hooks require their respective providers to be set up in your app's component tree. IrisX App SDK handles this automatically for extensions.

package/src/generators/preset/files/.agents/skills/tables-and-sorting/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: tables-and-sorting
+description: Use when building data tables with filtering, sorting, pagination, or displaying lists of assets, users, or other entities.
+---
+
+# Tables with Filtering & Sorting
+
+## Overview
+
+Create interactive data tables using `@trackunit/react-table`, `@trackunit/filters-filter-bar`, and server-side pagination with GraphQL. Always use `useMemo` and `manualSorting: true` for large datasets.
+
+## When to Use
+
+- Building asset management interfaces
+- Creating user administration tables
+- Developing dashboard data grids
+- Implementing reporting interfaces with large datasets
+
+**Not for:** Simple lists without filtering (use standard components).
+
+## Required Imports
+
+```typescript
+import { Table, useTable } from '@trackunit/react-table';
+import { TextCell, DateTimeCell } from '@trackunit/react-table-base-components';
+import { FilterBar, useFilterBar } from '@trackunit/filters-filter-bar';
+import { useAssetQueryFilters } from '@trackunit/filters-filter-bar-asset-graphql';
+import { usePaginationQuery } from '@trackunit/react-graphql-hooks';
+import { createColumnHelper, SortingState } from '@tanstack/react-table';
+import { useBrandFilter, useModelsFilter } from '@trackunit/filters-asset-filter-definitions';
+```
+
+## Valid Implementation
+
+```typescript
+type Asset = { id: string; name: string; createdAt: string };
+const columnHelper = createColumnHelper<Asset>();
+
+const AssetTable = () => {
+  // Setup filters with proper naming
+  const filterBar = useFilterBar({
+    name: "assetFilters",
+    filterBarDefinition: { 
+      brand: useBrandFilter(),
+      model: useModelsFilter() 
+    }
+  });
+
+  // Convert filter values to GraphQL variables
+  const filterVariables = useAssetQueryFilters(filterBar.filterBarConfig.values);
+
+  // Server-side sorting state
+  const [sorting, setSorting] = useState<SortingState>([]);
+
+  // GraphQL query with filters
+  const { data, loading, pagination } = usePaginationQuery(GetAssetsDocument, {
+    variables: { first: 50, ...filterVariables },
+    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 content={original.name} />,
+      header: "Asset Name",
+      enableSorting: true,
+    }),
+    columnHelper.accessor('createdAt', {
+      cell: ({ row: { original } }) => <DateTimeCell date={new 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} />
+      <Table 
+        {...table} 
+        loading={loading} 
+        pagination={pagination}
+        onRowClick={(row) => navigateToAsset(row.original.id)}
+      />
+    </>
+  );
+};
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing `useMemo` for columns/data | Wrap in `useMemo` to prevent re-renders |
+| `manualSorting: false` on large datasets | Use `manualSorting: true` for server-side sorting |
+| Missing filter variables in query | Spread `filterVariables` into GraphQL variables |
+| Using `getValue()` in cells | Use Trackunit cell components (`TextCell`, `DateTimeCell`) |
+| No `onRowClick` handler | Add navigation or detail view on row click |
+
+## 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`, `DateTimeCell`, `PlainDateCell`) for consistency
+- **Implement `onRowClick`** for navigation or detail views
+- **Sync state properly** between filters, sorting, and GraphQL queries