@mohsinonxrm/pptb-fetchxml-studio 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,120 @@
+# Changelog
+
+All notable changes to FetchXML Studio will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-15
+
+### 🎉 Initial Release
+
+FetchXML Studio v1.0.0 - A powerful FetchXML query builder for PowerPlatform Toolbox.
+
+### ✨ Features
+
+#### Query Builder
+- Tree-based visual query builder with hierarchical FetchXML structure
+- Full entity, attribute, filter, order, and link-entity support
+- Context-aware properties panel for each node type
+- Nested filter groups with AND/OR logic
+- Support for all FetchXML operators (60+ operators)
+- Aggregate queries with groupby and distinct
+- Query hints for performance optimization
+
+#### Relationships & Joins
+- Relationship picker with 1:N, N:1, N:N categorization
+- Inner and outer join support
+- Filter link-entity for any/all/not any/not all scenarios
+- Value-of conditions for cross-entity comparisons
+- Entity name conditions for outer join filtering
+
+#### Results Grid
+- Virtualized DataGrid for large datasets (react-window)
+- Rich cell rendering for lookups, option sets, dates, currency
+- Multi-column sorting (click + Shift+click)
+- Row selection (single and multi-select)
+- Resizable and reorderable columns
+- Formatted values with raw value toggle
+
+#### FetchXML Editor
+- Monaco editor with XML syntax highlighting
+- Bi-directional editing (visual ↔ XML)
+- Parse FetchXML to visual builder
+- Copy to clipboard
+- LayoutXML preview tab
+
+#### Views
+- Load system and personal views
+- Optimized view execution via SavedQuery/UserQuery APIs
+- Save queries as personal views
+- Update existing views
+- Solution-aware save (add to solution)
+
+#### Data Operations
+- Export to Excel with native data types
+- Delete selected records
+- Bulk delete jobs (async)
+- Run on-demand workflows on selection
+- Batch progress tracking with ETA
+
+#### User Experience
+- Dark/Light theme support (follows PPTB theme)
+- Lazy metadata loading
+- Intelligent caching (per-session)
+- Resizable split panes
+- Keyboard shortcuts (Ctrl+Enter to execute)
+
+#### Security
+- Privilege-aware operations
+- Export/Delete privilege checks
+- Bulk delete privilege validation
+- Workflow execution privilege checks
+
+### 🏗️ Technical
+
+- Built with React 19 and TypeScript 5.9
+- Fluent UI v9 components
+- Monaco Editor integration
+- ExcelJS for native Excel export
+- Vite build tooling
+- PowerPlatform Toolbox integration via @pptb/types
+
+### 📚 Documentation
+
+- Comprehensive README with feature overview
+- Debug logging system documentation
+- Project structure guide
+- Contributing guidelines
+
+---
+
+## Development History
+
+### Pre-release commits (dev branch)
+
+- `feat: Beta release enhancements - Settings, Export, and UX improvements`
+- `feat(preview): add LayoutXML tab to preview pane`
+- `feat(commands): add record action commands - delete, bulk delete, workflow`
+- `feat(columns): Add/Edit Columns panels with related entity support`
+- `feat(export): add Export to Excel with status feedback and privilege check`
+- `feat(paging): fix paging with cookies and page size support`
+- `feat(grid): multi-entity metadata & column display name fixes`
+- `feat(builder): Sprint 1 - Foundation & Layout improvements`
+- `feat(save): implement Save View functionality`
+- `feat(sort): Add multi-column sort with FetchXML integration`
+- `feat(results): Add Column from Results Grid`
+- `feat(views): Load view LayoutXML for column configuration`
+- `feat(layout): Add column resize and reorder`
+- `feat(layout): Add LayoutXML foundation`
+- `feat(filter): Add filter link-entity support for any/not any/all scenarios`
+- `feat(condition): Add valueof cross-entity comparison`
+- `feat(condition): Add valueof same-row column comparison`
+- `feat(condition): Add entityname support for outer join filtering`
+- `feat(views): Add Load View picker and optimized view execution`
+- `feat(parser): Add FetchXML parser with Monaco editor dialog`
+- `feat: Implement Phases 1-4 - DataGrid UI polish`
+- `feat: add filter consistency, cascading validation, and global metadata caching`
+- `feat(entity-selector): implement advanced filtering with publisher/solution multiselect`
+- `feat(ui): add resizable panes with visual grip indicators and command bar`
+- `Initial commit - setup main branch`

package/README.md

@@ -0,0 +1,250 @@
+# FetchXML Studio for PowerPlatform Toolbox
+
+A powerful, modern FetchXML query builder and data explorer for [PowerPlatform Toolbox](https://github.com/PowerPlatformToolBox/desktop-app). Inspired by the XrmToolBox FetchXML Builder, reimagined with React 19, Fluent UI v9, and seamless Dataverse integration.
+
+![Version](https://img.shields.io/badge/version-1.0.0-blue)
+![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript)
+![Fluent UI](https://img.shields.io/badge/Fluent%20UI-v9-0078D4?logo=microsoft)
+
+## ✨ Features
+
+### 🔧 Visual Query Builder
+- **Tree-based hierarchy** — Build FetchXML queries visually with entities, attributes, filters, orders, and link-entities
+- **Smart property editors** — Context-aware panels for each node type (fetch options, conditions, relationships)
+- **Full FetchXML support** — Aggregate queries, grouping, distinct, top/count, paging, and advanced hints
+- **Nested filters** — Create complex AND/OR filter groups with unlimited nesting
+- **Link-entity relationships** — Browse and add 1:N, N:1, and N:N relationships with inner/outer joins
+
+### 📊 Results Grid
+- **Virtualized DataGrid** — Handle large result sets with smooth scrolling (powered by react-window)
+- **Rich cell rendering** — Power Apps-style display for lookups, option sets, dates, currency, and more
+- **Multi-column sorting** — Click headers to sort; Shift+click for multi-column sort
+- **Row selection** — Select single or multiple records for bulk operations
+- **Resizable & reorderable columns** — Customize your view with drag-and-drop columns
+- **Formatted values** — Display OData formatted values or raw values (configurable)
+
+### 📝 FetchXML Editor
+- **Monaco editor** — Full-featured XML editor with syntax highlighting and line numbers
+- **Bi-directional editing** — Edit XML directly and parse back to the visual builder
+- **Copy to clipboard** — One-click copy of generated FetchXML
+- **LayoutXML preview** — See the column layout configuration
+
+### 📥 Load & Save Views
+- **Load system/personal views** — Browse and load existing Dataverse views
+- **Optimized view execution** — Uses SavedQuery/UserQuery APIs for better performance
+- **Save to Dataverse** — Save your queries as new personal views or update existing ones
+- **Solution-aware** — Add views to solutions during save
+
+### 📤 Export & Data Operations
+- **Export to Excel** — Native Excel export with proper data types (numbers, dates, currencies)
+- **Formatted value options** — Export formatted, raw, or both value types
+- **Record deletion** — Delete selected records with confirmation
+- **Bulk delete jobs** — Submit async bulk delete operations to Dataverse
+- **Run workflows** — Execute on-demand workflows on selected records
+
+### 🎨 User Experience
+- **Dark/Light themes** — Follows PowerPlatform Toolbox theme with Fluent UI tokens
+- **Lazy metadata loading** — Loads only what's needed, when it's needed
+- **Intelligent caching** — In-memory cache prevents duplicate API calls
+- **Resizable panes** — Adjust the layout to your preference
+- **Keyboard shortcuts** — Execute queries, copy XML, and more
+
+### 🔒 Privilege-Aware
+- **Security checks** — Validates user privileges before operations
+- **Export privilege check** — Only shows export option if user has access
+- **Delete privilege check** — Validates delete permissions per entity
+
+## 🖼️ Interface Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│  [Entity Selector ▼]  [Load View ▼]  [Save View]           [⚙ Settings]│
+├──────────────────────┬──────────────────────────────────────────────────┤
+│                      │  [FetchXML]  [LayoutXML]  [Results]   [▶ Execute]│
+│   Query Tree         ├──────────────────────────────────────────────────┤
+│                      │                                                   │
+│   📁 fetch           │   Results Grid / Monaco Editor                   │
+│   └─📁 entity        │                                                   │
+│      ├─📋 attribute  │   ┌────────────┬────────────┬──────────────┐     │
+│      ├─📋 attribute  │   │ Column 1   │ Column 2   │ Column 3     │     │
+│      ├─🔽 order      │   ├────────────┼────────────┼──────────────┤     │
+│      ├─🔍 filter     │   │ Value      │ Value      │ Value        │     │
+│      │  └─ condition │   │ Value      │ Value      │ Value        │     │
+│      └─🔗 link-entity│   └────────────┴────────────┴──────────────┘     │
+│                      │                                                   │
+├──────────────────────┤   [◀ Prev] Page 1 of 10 [Next ▶]  100 records    │
+│                      │                                                   │
+│   Properties Panel   │   [+ Add Columns] [✎ Edit Columns] [⬇ Export]   │
+│   (context-aware)    │   [🗑 Delete] [Bulk Delete] [⚡ Run Workflow]    │
+│                      │                                                   │
+└──────────────────────┴──────────────────────────────────────────────────┘
+```
+
+## 🚀 Getting Started
+
+### Prerequisites
+- [PowerPlatform Toolbox](https://github.com/PowerPlatformToolBox/desktop-app) desktop application
+- Connection to a Dataverse environment
+
+### Installation
+FetchXML Studio is available as a tool in PowerPlatform Toolbox. Install it from the tool gallery or load as a custom tool.
+
+## 🛠️ Development
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/mohsinonxrm/pptb-fetchxml-studio.git
+cd pptb-fetchxml-studio
+
+# Install dependencies
+npm install
+
+# Start development server
+npm run dev
+```
+
+### Building
+
+```bash
+# Production build
+npm run build
+
+# Preview production build
+npm run preview
+```
+
+### Debug Logging
+
+Enable debug logging in the browser console:
+
+```javascript
+// Enable specific category
+enableDebug("metadataAPI");       // API calls and responses
+enableDebug("treeExpansion");     // Tree node operations
+enableDebug("relationshipPicker"); // Relationship loading
+enableDebug("linkEntityEditor");  // Link-entity configuration
+enableDebug("propertiesPanel");   // Property editor routing
+
+// Enable all
+enableAllDebug();
+
+// Disable
+disableDebug("metadataAPI");
+disableAllDebug();
+```
+
+## 📦 Tech Stack
+
+| Technology | Purpose |
+|------------|---------|
+| **React 19** | UI framework with latest features (transitions, actions) |
+| **TypeScript 5.9** | Type-safe development |
+| **Vite** | Fast build tooling and HMR |
+| **Fluent UI v9** | Microsoft's design system (Tree, DataGrid, Tabs, etc.) |
+| **Monaco Editor** | VS Code's editor for XML editing |
+| **react-window** | Virtualized list rendering for large datasets |
+| **exceljs** | Native Excel file generation |
+| **@pptb/types** | PowerPlatform Toolbox API types |
+
+## 📁 Project Structure
+
+```
+src/
+├── app/
+│   └── AppShell.tsx              # Main layout with split panes
+├── features/fetchxml/
+│   ├── api/
+│   │   ├── pptbClient.ts         # Dataverse API wrapper
+│   │   ├── dataverseMetadata.ts  # Metadata fetching
+│   │   ├── excelExport.ts        # Excel export logic
+│   │   └── formattedValues.ts    # OData formatted value handling
+│   ├── model/
+│   │   ├── nodes.ts              # TypeScript node definitions
+│   │   ├── fetchxml.ts           # FetchXML generation
+│   │   ├── fetchxmlParser.ts     # FetchXML parsing
+│   │   ├── layoutxml.ts          # LayoutXML generation
+│   │   └── operators.ts          # Operator definitions by type
+│   ├── state/
+│   │   ├── builderStore.tsx      # React context state management
+│   │   └── cache.ts              # Metadata caching
+│   └── ui/
+│       ├── LeftPane/             # Tree view and properties
+│       ├── RightPane/            # Tabs, editor, grid
+│       ├── Toolbar/              # Entity selector, view picker
+│       ├── Dialogs/              # Delete, bulk delete, workflow
+│       └── Settings/             # Display preferences
+└── shared/
+    ├── components/               # Reusable pickers
+    ├── hooks/                    # Custom React hooks
+    └── utils/                    # Debug utilities
+```
+
+## 🔧 FetchXML Features Support
+
+| Feature | Status |
+|---------|--------|
+| Basic queries | ✅ |
+| Attributes (select columns) | ✅ |
+| All-attributes | ✅ |
+| Filters (and/or) | ✅ |
+| Nested filters | ✅ |
+| All condition operators | ✅ |
+| Link-entity (joins) | ✅ |
+| Inner/outer joins | ✅ |
+| N:N relationships | ✅ |
+| Orders (sorting) | ✅ |
+| Multi-column sort | ✅ |
+| Aggregate queries | ✅ |
+| Groupby | ✅ |
+| Distinct | ✅ |
+| Top/Count | ✅ |
+| Paging with cookies | ✅ |
+| Value-of conditions | ✅ |
+| Entity name on conditions | ✅ |
+| Filter link-entity (any/all) | ✅ |
+| Query hints | ✅ |
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Commit Convention
+This project follows [Conventional Commits](https://www.conventionalcommits.org/):
+- `feat:` New feature
+- `fix:` Bug fix
+- `refactor:` Code refactoring
+- `docs:` Documentation
+- `chore:` Maintenance
+
+## 📋 Roadmap
+
+- [ ] Import/export query definitions (JSON)
+- [ ] Quick query templates
+- [ ] Query history
+- [ ] Web API code generation
+- [ ] Query performance insights
+- [ ] Syntax validation in Monaco
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## 🙏 Acknowledgments
+
+- [XrmToolBox FetchXML Builder](https://github.com/rappen/FetchXMLBuilder) - Original inspiration
+- [PowerPlatform Toolbox](https://github.com/PowerPlatformToolBox/desktop-app) - Host platform
+- [Fluent UI](https://react.fluentui.dev/) - UI component library
+- [Monaco Editor](https://microsoft.github.io/monaco-editor/) - Code editor
+
+---
+
+Built with ❤️ for the Power Platform community

package/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs['recommended-latest'],
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/index.html

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<link rel="icon" type="image/svg+xml" href="/vite.svg" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>FetchXML Studio</title>
+		<style>
+			/* Reset browser defaults for PPTB iframe */
+			* {
+				margin: 0;
+				padding: 0;
+				box-sizing: border-box;
+			}
+
+			html,
+			body {
+				margin: 0;
+				padding: 0;
+				width: 100%;
+				height: 100%;
+				overflow: hidden;
+				position: fixed;
+				top: 0;
+				left: 0;
+				right: 0;
+				bottom: 0;
+			}
+
+			#root {
+				width: 100%;
+				height: 100%;
+				overflow: hidden;
+				position: absolute;
+				top: 0;
+				left: 0;
+				right: 0;
+				bottom: 0;
+			}
+
+			/* Modern scrollbar styling */
+			::-webkit-scrollbar {
+				width: 8px;
+				height: 8px;
+			}
+
+			::-webkit-scrollbar-track {
+				background: transparent;
+			}
+
+			::-webkit-scrollbar-thumb {
+				background: rgba(128, 128, 128, 0.4);
+				border-radius: 4px;
+			}
+
+			::-webkit-scrollbar-thumb:hover {
+				background: rgba(128, 128, 128, 0.6);
+			}
+
+			/* Firefox scrollbar */
+			* {
+				scrollbar-width: thin;
+				scrollbar-color: rgba(128, 128, 128, 0.4) transparent;
+			}
+		</style>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="/src/main.tsx"></script>
+	</body>
+</html>

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mohsinonxrm/pptb-fetchxml-studio",
+  "version": "1.0.0",
+  "type": "module",
+  "cspExceptions": {
+    "connect-src": [
+      "https://*.dynamics.com",
+      "https://*.crm*.dynamics.com"
+    ],
+    "script-src": [
+      "https://cdn.jsdelivr.net"
+    ],
+    "style-src": [
+      "https://cdn.jsdelivr.net"
+    ]
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fluentui-contrib/react-data-grid-react-window": "^1.4.1",
+    "@fluentui/react-calendar-compat": "^0.3.14",
+    "@fluentui/react-components": "^9.72.4",
+    "@fluentui/react-datepicker-compat": "^0.6.19",
+    "@fluentui/react-icons": "^2.0.313",
+    "@fluentui/react-timepicker-compat": "^0.4.24",
+    "@monaco-editor/react": "^4.7.0",
+    "exceljs": "^4.4.0",
+    "react": "^19.1.1",
+    "react-dom": "^19.1.1",
+    "react-window": "^2.2.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.36.0",
+    "@pptb/types": "^1.0.7",
+    "@types/node": "^24.6.0",
+    "@types/react": "^19.1.16",
+    "@types/react-dom": "^19.1.9",
+    "@types/react-window": "^1.8.8",
+    "@vitejs/plugin-react": "^5.1.0",
+    "eslint": "^9.36.0",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.22",
+    "globals": "^16.4.0",
+    "monaco-editor": "^0.54.0",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.45.0",
+    "vite": "^7.1.12"
+  }
+}

package/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>