@trackunit/iris-app 1.12.7 → 1.12.10

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

package/src/generators/preset/files/.agents/skills/widget-extensions/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: widget-extensions
+description: Use when creating dashboard widgets, KPI displays, configurable widgets with edit dialogs, or data visualizations for dashboards.
+---
+
+# Widget Extensions
+
+## Overview
+
+Widget extensions are React components that integrate into Trackunit Manager dashboards. Use `useWidgetConfig` for data, filters, and edit mode. Supports KPI, CHART, LIST, MAP, and OTHER types.
+
+## When to Use
+
+- Creating dashboard KPIs or metrics
+- Building data visualization widgets
+- Adding configurable widgets with edit dialogs
+- Displaying filtered/time-ranged data in dashboards
+
+**Not for:** Full-page extensions (use `FLEET_EXTENSION` or `ASSET_HOME_EXTENSION`).
+
+## Creating Widget Extensions
+
+```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 (handles both display and edit mode)
+
+## Widget Manifest
+
+```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", // CHART | KPI | LIST | MAP | OTHER
+  
+  size: {
+    default: { width: 2, height: 2 }, // 1-6 grid units
+    allowFullWidth: false,
+  },
+  
+  header: {
+    name: "My Widget",
+    image: { name: "ChartBar" }, // IconByName or IconByPath
+    hasEditDialog: true,
+  },
+  
+  footer: {
+    linkDescription: "View details",
+    link: "/my-app/details",
+    poweredByImage: { path: "/assets/logo.svg" },
+  },
+  
+  preview: {
+    description: "Displays chart data for analysis",
+  },
+  
+  supportedLocations: ["MY_HOME", "PLAYGROUND"],
+  
+  supportedFilters: {
+    TIME_RANGE: { include: ["ALL"] },
+    ASSETS: { include: ["assetType", "brands", "models"] },
+    CUSTOMERS: { include: ["customerType", "criticality"] },
+    SITES: { include: ["siteType", "location"] },
+  },
+};
+```
+
+## Widget Types
+
+| Type | Use Case |
+|------|----------|
+| `KPI` | Single metric displays (typically 1x1) |
+| `CHART` | Data visualization (charts, graphs) |
+| `LIST` | Tabular or list-based data |
+| `MAP` | Geographic or spatial data |
+| `OTHER` | Custom or specialized widgets |
+
+## Supported Locations
+
+- `MY_HOME` - User's personal dashboard
+- `SITE_HOME` - Site-specific dashboards
+- `PLAYGROUND` - Widget testing playground
+
+## Widget Development
+
+### Basic Widget Component
+
+```typescript
+import { useWidgetConfig } from '@trackunit/react-core-hooks';
+
+export const App = () => {
+  const {
+    data, setData, dataVersion, loadingData,
+    title, setTitle,
+    filters, timeRange,
+    isEditMode, openEditMode, closeEditMode,
+    pollInterval, setLoadingState
+  } = useWidgetConfig();
+
+  if (isEditMode) {
+    return <EditDialog />;
+  }
+
+  return (
+    <WidgetBody>
+      <h2>{title}</h2>
+      {/* Widget content */}
+    </WidgetBody>
+  );
+};
+```
+
+### useWidgetConfig Hook
+
+**Data Management:**
+- `data: Record<string, unknown> | null` - Widget configuration data
+- `setData(data, version)` - Update widget data
+- `dataVersion: number | null` - Current data version for migrations
+- `loadingData: boolean` - Whether widget data is loading
+
+**Title Management:**
+- `title: string` - Widget title
+- `setTitle(title)` - Update widget title
+
+**Context:**
+- `filters` - Applied filters (assets, customers, sites)
+- `timeRange` - Selected time range (startMsInEpoch, endMsInEpoch)
+- `isEditMode: boolean` - Whether widget is in edit mode
+
+**Edit Mode:**
+- `openEditMode()` - Enter edit mode
+- `closeEditMode()` - 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: "yourDataHere"}, dataVersion: 1 }});
+        }}
+        onCancel={closeEditMode}
+        initialData={data}
+      />
+    );
+  }
+  
+  return <MainWidgetContent />;
+};
+```
+
+## Filter Support
+
+### Using Filters
+
+```typescript
+const { filters, timeRange } = useWidgetConfig();
+
+const selectedAssets = filters.assetsFilterBarValues?.assetType;
+const selectedCustomers = filters.customersFilterBarValues?.customerType;
+const selectedSites = filters.sitesFilterBarValues?.siteType;
+
+const startTime = timeRange?.startMsInEpoch;
+const endTime = timeRange?.endMsInEpoch;
+```
+
+## KPI Widget Example
+
+```typescript
+import { useWidgetConfig } from '@trackunit/react-core-hooks';
+import { useQuery } from '@trackunit/react-graphql-hooks';
+
+export const App = () => {
+  const { filters, timeRange, 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 });
+  }, [kpiData, loading, setLoadingState]);
+  
+  return (
+    <div className="kpi-widget">
+      <div className="kpi-value">{kpiData?.totalCount}</div>
+      <div className="kpi-label">Total Assets</div>
+    </div>
+  );
+};
+```
+
+## 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 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
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using generic widget libraries | Use Trackunit IrisX App SDK patterns |
+| Not handling `isEditMode` | Check `isEditMode` and render edit dialog |
+| Missing `setLoadingState` call | Call `setLoadingState` to show loading indicators |
+| Ignoring `filters` from context | Apply filters to data queries |
+| Not using `dataVersion` | Increment version when changing data schema |
+| Missing empty/error states | Handle no data and error conditions gracefully |

package/src/generators/preset/files/.cursor/mcp.json

@@ -1,5 +1,9 @@
 {
   "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    },
     "nx-mcp": {
       "command": "npx",
       "args": ["-y", "nx-mcp@latest"]

package/src/generators/preset/root-files/AGENTS.md

@@ -0,0 +1,43 @@
+# IrisX App SDK Workspace
+
+This is an IrisX App workspace. Follow these rules for all development.
+
+## Building Real Applications
+
+You are building real applications that work with actual Trackunit data.
+
+- 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
+4. If not available, ask the user
+
+## IrisX App Commands
+
+**ALWAYS use these specific commands** (never generic React/Node.js commands):
+
+- **Create new app:** `npx nx generate @trackunit/iris-app:create [name-of-your-app]`
+- **Create new extension:** `npx nx g @trackunit/iris-app:extend --name=[my-extension-name] --app=[app-name] --directory=[feature] --type=[extension-type]`
+- **Run app:** `npx nx run [name-of-your-app]:serve`
+
+Available extension types:
+- `ASSET_HOME_EXTENSION` - Tabs in Asset Home screen
+- `SITE_HOME_EXTENSION` - Tabs in Site Home screen
+- `FLEET_EXTENSION` - Menu items in Main Menu
+- `REPORT_EXTENSION` - Reports in Reports screen
+- `WIDGET_EXTENSION` - Dashboard widgets
+- `IRIS_APP_SETTINGS_EXTENSION` - Configuration 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
+
+## Quality Assurance
+
+Before completing any task: Always check for and fix all ESLint and TypeScript errors in modified files.

package/src/generators/preset/root-files/CLAUDE.md

@@ -0,0 +1,17 @@
+@AGENTS.md
+
+# IrisX App Workspace
+
+This is an IrisX App project generated by the Trackunit SDK. Follow AGENTS.md for all development rules.
+
+## Skills
+
+SDK-specific skills are located in `.agents/skills/`. When a skill is referenced in AGENTS.md, read it from `.agents/skills/[skill-name]/SKILL.md`.
+
+If skills from `.agents/skills/` are not appearing in your available skills list, suggest the user symlink them for automatic discovery:
+
+```bash
+ln -s .agents/skills .claude/skills
+```
+
+Note: If the user already has a `.claude/skills` folder, they should symlink individual skills or the contents instead.