Merge pull request #51 from xsoulspace/light-experiments

Light experiments

Author: Arenukvern

.cursor/rules/dart_dev.mdc

@@ -0,0 +1,71 @@
+---
+description: 
+globs: *.dart
+alwaysApply: false
+---
+You are a senior Dart programmer specializing in Flutter, Flame and Game development. Generate code adhering to:
+
+1. **Dart and Flutter best practices**:
+
+   - Clean code and design patterns
+   - Use Dart 3.8, Flutter 3.32
+   - Use async / await instead of then
+
+2. **Enhanced Documentation**:
+   - Write precise, future-proof dartdoc comments that focus on the specific purpose
+   - Include cross-references to related classes and real usage examples
+   - Document relationships between related components
+   - Avoid scope limitations unless absolutely necessary
+   - Use {@template} for reusable component documentation
+   - Include practical code samples showing real usage patterns
+   - Document all parameters with `///`
+   - Add warning comments for important usage notes
+   - Reference concrete implementations in the codebase
+
+   ```dart
+   /// {@template game_button}
+   /// Custom button widget for game interactions
+   /// {@endtemplate}
+   class GameButton extends StatelessWidget {
+     /// {@macro game_button}
+     const GameButton({
+       required this.onPressed,
+       this.icon,
+       super.key,
+     });
+   ```
+
+
+2. Coding standards:
+
+   - Explicit type declarations
+   - Dart naming conventions (PascalCase for classes, camelCase for variables/functions)
+   - Prefer const constructors
+   - Extension methods for added functionality (e.g., GameId)
+   - Use required commas linter rule in dart
+   - Prefer arrow functions style for dart
+   - Prefer const constructors with named parameters with const values instead of nullable ones
+
+3. Flutter widgets and concepts:
+
+   - Dart 3.8 syntax for null safety, pattern matching, and more
+   - Appropriate use of StatelessWidget or Stateful widgets
+   - Custom reusable widgets (use ui_kit) instead of methods
+   - Cupertino or Material Design as appropriate
+   - Proper error handling and async/await for asynchronous operations
+   - flutter_animate for animations
+
+4. Project structure:
+
+   - Follow existing organization
+   - Use common imports (lib/common_imports.dart)
+
+5. Additional requirements:
+   - Implement routing using go_router
+   - Write unit tests for business logic and widget tests for UI components
+   - Implement proper form validation and user input handling
+   - Use [] when referencing code
+   - Generate readable, short, and concise documentation
+   - Use {@template} and {@macro} to create and use dart doc code snippets
+
+Generate concise, efficient code following these guidelines while maintaining existing project structure and conventions.

.cursor/rules/dart_doc.mdc

@@ -0,0 +1,116 @@
+---
+description: when generating dartdoc or documentation for dart 
+globs: 
+alwaysApply: false
+---
+Please add comprehensive Dart documentation comments to the specified classes, following these guidelines:
+
+1. Use /// for documentation comments.
+2. Start with a brief, single-sentence summary of the class's purpose.
+3. Follow with a more detailed description if necessary, keeping it concise.
+4. Include an @ai annotation with specific instructions for AI tools on how to interpret and use this class.
+5. Document all public members (methods, properties, etc.) with clear, concise explanations of their purpose and usage.
+6. Use [bracketed] references for any mentioned identifiers within the class.
+7. Include code examples where appropriate, using ```dart code fences.
+8. Mention any important relationships with other classes or libraries.
+9. Use PREFER, AVOID, or CONSIDER for recommendations about usage patterns.
+10. Add @deprecated tags with explanations for any deprecated members.
+11. Place doc comments before metadata annotations.
+12. Use prose to explain parameters, return values, and exceptions.
+13. For boolean properties, start comments with "Whether" followed by a description.
+14. Document only the getter for properties with both a getter and setter.
+15. Consider including a code sample in the class-level comment.
+
+Example format:
+
+````dart
+/// A widget that displays a customizable progress indicator.
+///
+/// This class provides a flexible way to show loading progress in your app.
+/// It supports both determinate and indeterminate progress modes.
+///
+/// Use [ProgressIndicator.circular] for a circular indicator, or
+/// [ProgressIndicator.linear] for a linear one.
+///
+/// ```dart
+/// ProgressIndicator(
+///   value: 0.7,
+///   backgroundColor: Colors.grey[300],
+///   valueColor: AlwaysStoppedAnimation<Color>(Colors.blue),
+/// )
+/// ```
+///
+/// See also:
+///
+///  * [CircularProgressIndicator], which shows progress along a circular arc.
+///  * [LinearProgressIndicator], which displays progress along a line.
+///
+/// @ai When generating code involving this class, ensure proper initialization
+/// of [value] and consider the appropriate use of [backgroundColor] and [valueColor].
+class ProgressIndicator extends StatefulWidget {
+  /// Creates a progress indicator.
+  ///
+  /// The [value] argument should be null for an indeterminate progress indicator.
+  /// For determinate progress indicators, [value] should be a non-null value
+  /// between 0.0 and 1.0, inclusive.
+  ///
+  /// @ai Ensure [value] is within the valid range when provided.
+  const ProgressIndicator({
+    Key? key,
+    this.value,
+    this.backgroundColor,
+    this.valueColor,
+    this.semanticsLabel,
+    this.semanticsValue,
+  }) : super(key: key);
+
+  /// The progress value between 0.0 and 1.0.
+  ///
+  /// If null, the progress indicator is indeterminate.
+  ///
+  /// @ai Use this property to control the progress. Ensure it's between 0.0 and 1.0.
+  final double? value;
+
+  /// The progress indicator's background color.
+  ///
+  /// @ai Consider using a contrasting color to [valueColor] for better visibility.
+  final Color? backgroundColor;
+
+  /// The progress indicator's color as an animated value.
+  ///
+  /// @ai Use [AlwaysStoppedAnimation] for a solid color, or custom animations for dynamic effects.
+  final Animation<Color?>? valueColor;
+
+  /// Creates a circular progress indicator.
+  ///
+  /// @ai Use this constructor for a circular representation of progress.
+  const ProgressIndicator.circular({Key? key}) : this(key: key);
+
+  /// Creates a linear progress indicator.
+  ///
+  /// @ai Use this constructor for a linear representation of progress.
+  const ProgressIndicator.linear({Key? key}) : this(key: key);
+
+  /// This method is deprecated and will be removed in the next major version.
+  ///
+  /// Use [newMethod] instead.
+  @Deprecated('Use newMethod() instead')
+  void oldMethod() {
+    // ...
+  }
+
+  @override
+  State<ProgressIndicator> createState() => _ProgressIndicatorState();
+}
+````
+
+Please apply this documentation style to the following classes:
+
+1. ClassA
+2. ClassB
+3. ClassC
+
+Ensure that the documentation is clear, concise, and provides valuable information for both human developers and AI tools. Use `dart format` to format the code correctly.
+
+References:
+@Dart