@trackunit/iris-app 1.12.9 → 1.12.10

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.