Merge pull request #31 from getditto/CX-539_Query_Editor

CX-539:  Simple Query Editor with option to share results with existing Share API implementation

Author: biozal

README.md

@@ -347,6 +347,84 @@ In the second scenario, you can be quite confident that your data is still the m
 That said, the aim of this tool is to provide heuristics that you can combine with an understanding of your data model to get an accurate picture of the state of your device.
 If you have specific knowledge about your data model or update frequency, you can use that knowledge to get a clearer view of the data you have locally.
 
+## `QueryEditorView`
+
+The `QueryEditorView` provides an interactive interface for executing DQL (Ditto Query Language) statements against your Ditto database. This tool helps developers test queries, inspect data, and perform CRUD operations during development and debugging, with built-in export functionality for query results.
+
+### Usage
+
+The `QueryEditorView` can be used as a standalone widget in your Flutter application:
+
+```dart
+import 'package:ditto_flutter_tools/ditto_flutter_tools.dart';
+
+// In your widget build method
+Scaffold(
+  appBar: AppBar(title: Text('Query Editor')),
+  body: QueryEditorView(ditto: myDittoInstance),
+)
+```
+
+Or navigate to it from your debug menu:
+
+```dart
+Navigator.push(
+  context,
+  MaterialPageRoute(
+    builder: (context) => QueryEditorView(ditto: ditto),
+  ),
+);
+```
+
+### Features
+
+The query editor provides:
+
+1. **Multi-line Query Input** - A text field for entering DQL statements with syntax hints
+2. **Async Query Execution** - Non-blocking query execution with loading indicator  
+3. **Paginated Results Display** - Large result sets with configurable pagination (10, 25, 50, 100 items per page)
+4. **Export Functionality** - Share query results as JSON files using the native Share API
+5. **Error Handling** - Clear error messages for invalid queries or execution failures
+6. **Multiple Query Types** - Supports SELECT, INSERT, UPDATE, and DELETE operations
+
+### Export Functionality
+
+The query editor includes built-in export capabilities:
+
+#### Share Results
+- **Smart Export**: Share button only appears when query results contain actual data (not status messages)
+- **JSON Format**: Results are exported as raw JSON data without formatting or metadata
+- **Automatic Cleanup**: Temporary files are automatically cleaned up after sharing
+
+#### Export Features
+- **JSON Files**: Query results are exported with `.json` extension and proper MIME type
+- **Raw Data Only**: Exports only the actual query result data, no headers or formatting
+
+### Query Results & Pagination
+
+The view handles multiple result types with advanced pagination:
+
+1. **Query Results (SELECT)**: 
+   - Each document displayed as a separate item
+   - Configurable pagination (10, 25, 50, 100 items per page)
+   - Page navigation controls with direct page input
+   - Results counter showing total items and current page range
+   - Export functionality available for data results
+
+2. **Mutation Results (INSERT/UPDATE/DELETE)**: 
+   - List of affected document IDs
+   - Number of documents modified  
+   - Transaction/commit ID when available
+   - No export functionality (status messages only)
+
+### DQL Documentation
+
+For comprehensive DQL syntax and examples, refer to the official Ditto documentation:
+- [Read Operations](https://docs.ditto.live/sdk/latest/crud/read)
+- [Create Operations](https://docs.ditto.live/sdk/latest/crud/create)  
+- [Update Operations](https://docs.ditto.live/sdk/latest/crud/update)
+- [Delete Operations](https://docs.ditto.live/sdk/latest/crud/delete)
+
 
 ## `PermissionsHealthView`
 
@@ -506,6 +584,8 @@ This package uses the following third-party libraries:
 - **Repository**: https://pub.dev/packages/share_plus
 - **Note**: Used for all export functionality (logs and database) to provide a consistent, native sharing experience across iOS, Android, macOS, and Linux platforms.
 
+
+
 ## Support
 
 For support, please contact Ditto Support (<[email protected]>).

example/lib/constants/routes.dart

@@ -6,3 +6,4 @@ const String peerSyncStatusRoute = '/peer-sync-status';
 const String permissionsHealthRoute = '/permissions-health';
 const String diskUsageRoute = '/disk-usage';
 const String systemSettingsRoute = '/system-settings';
+const String queryEditorRoute = '/query-editor';

example/lib/main.dart

@@ -13,6 +13,7 @@ import 'screens/peer_sync_status_screen.dart';
 import 'screens/permissions_health_screen.dart';
 import 'screens/disk_usage_screen.dart';
 import 'screens/system_settings_screen.dart';
+import 'screens/query_editor_screen.dart';
 import 'constants/routes.dart';
 
 Future<void> main() async {
@@ -129,6 +130,9 @@ class _DittoExampleState extends State<DittoExample> {
             systemSettingsRoute: (context, state, data) => SystemSettingsScreen(
                   ditto: dittoService.ditto,
                 ),
+            queryEditorRoute: (context, state, data) => QueryEditorScreen(
+              ditto: dittoService.ditto,
+            ),
           },
         ),
       );

example/lib/screens/query_editor_screen.dart

@@ -0,0 +1,22 @@
+import 'package:ditto_flutter_tools/ditto_flutter_tools.dart';
+import 'package:flutter/material.dart';
+import 'package:ditto_live/ditto_live.dart';
+
+class QueryEditorScreen extends StatelessWidget {
+  final Ditto ditto;
+
+  const QueryEditorScreen({
+    super.key,
+    required this.ditto,
+  });
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(title: const Text("Query Editor")),
+      body: QueryEditorView(
+        ditto: ditto,
+      ),
+    );
+  }
+}

example/lib/widgets/main_list_view.dart

@@ -115,6 +115,60 @@ class MainListView extends StatelessWidget {
               ],
             ),
           ),
+
+          const SizedBox(height: 20),
+          // DITTO Store Section
+          Padding(
+            padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 8),
+            child: Text(
+              "DITTO STORE",
+              style: TextStyle(
+                fontSize: 13,
+                fontWeight: FontWeight.w600,
+                color: Theme.of(context)
+                    .textTheme
+                    .labelLarge
+                    ?.color
+                    ?.withOpacity(0.6),
+                letterSpacing: 0.5,
+              ),
+            ),
+          ),
+          Container(
+            margin: const EdgeInsets.symmetric(horizontal: 16),
+            decoration: BoxDecoration(
+              color: Theme.of(context).colorScheme.surface,
+              borderRadius: BorderRadius.circular(10),
+              border: Border.all(
+                  color:
+                  Theme.of(context).colorScheme.outline.withOpacity(0.3)),
+            ),
+            child: Column(
+              children: [
+                ListTile(
+                  leading: Container(
+                    width: 32,
+                    height: 32,
+                    decoration: BoxDecoration(
+                      color: Colors.lightBlue,
+                      borderRadius: BorderRadius.circular(8),
+                    ),
+                    child: const Icon(
+                      Icons.code,
+                      color: Colors.white,
+                      size: 20,
+                    ),
+                  ),
+                  title: const Text("Query Editor"),
+                  trailing: Icon(Icons.chevron_right,
+                      color: Theme.of(context).colorScheme.onSurfaceVariant),
+                  onTap: () =>
+                      Beamer.of(context).beamToNamed(queryEditorRoute),
+                ),
+              ],
+            ),
+          ),
+
           const SizedBox(height: 20),
           // SYSTEM Section
           Padding(

example/pubspec.lock

@@ -338,10 +338,10 @@ packages:
     dependency: transitive
     description:
       name: intl
-      sha256: d6f56758b7d3014a48af9701c085700aac781a92a87a62b1333b46d8879661cf
+      sha256: "3bc132a9dbce73a7e4a21a17d06e1878839ffbf975568bc875c60537824b0c4d"
       url: "https://pub.dev"
     source: hosted
-    version: "0.19.0"
+    version: "0.18.1"
   json_annotation:
     dependency: "direct main"
     description:

lib/ditto_flutter_tools.dart

@@ -13,5 +13,6 @@ export "src/permissions_health/wifi_permissions_cross_platform.dart"
 export "src/sync_status_view.dart" show SyncStatusView;
 export "src/sync_status_helper.dart" show SyncStatusHelper, SyncStatus;
 export "src/peer_list.dart" show PeerListView;
-export "src/system_settings_view.dart" show SystemSettingsView;
 export "src/peer_sync_status/peer_sync_status_view.dart" show PeerSyncStatusView;
+export "src/system_settings_view.dart" show SystemSettingsView;
+export "src/query_editor/query_editor_view.dart" show QueryEditorView;