@grandgular/rive-angular 0.1.2 → 0.3.0

package/README.md

@@ -20,6 +20,7 @@ This library provides a **modern, Angular-native** way to integrate Rive animati
 - 🌐 **SSR-ready**: Full server-side rendering support
 - 🧹 **Automatic cleanup**: Proper resource management and lifecycle handling
 - 📦 **File caching**: Built-in service for preloading and caching .riv files
+- 🛠️ **Developer Experience**: Built-in debug mode, validation, and detailed error codes
 
 ### Comparison with alternatives
 
@@ -36,6 +37,7 @@ This library provides a **modern, Angular-native** way to integrate Rive animati
 | SSR support | ✅ Full | ⚠️ Limited |
 | Performance | Optimized (zoneless) | Standard |
 | File caching | ✅ Built-in service | ❌ Manual |
+| Validation | ✅ Built-in | ❌ None |
 
 #### vs. rive-react
 
@@ -140,6 +142,55 @@ export class InteractiveComponent {
 }
 ```
 
+### Text Runs
+
+Rive text runs allow you to update text content at runtime. The library provides two approaches:
+
+#### Declarative (Controlled Keys)
+
+Use the `textRuns` input for reactive, template-driven text updates:
+
+```html
+<rive-canvas
+  src="assets/hello.riv"
+  [textRuns]="{ greeting: userName(), subtitle: 'Welcome' }"
+/>
+```
+
+Keys present in `textRuns` are **controlled** — the input is the source of truth and will override any imperative changes.
+
+#### Imperative (Uncontrolled Keys)
+
+Use methods for reading values or managing keys not in `textRuns`:
+
+```typescript
+riveRef = viewChild.required(RiveCanvasComponent);
+
+// Read current value
+const greeting = this.riveRef().getTextRunValue('greeting');
+
+// Set uncontrolled key
+this.riveRef().setTextRunValue('dynamicText', 'New value');
+```
+
+#### Nested Text Runs
+
+For text runs inside nested components, use the `AtPath` variants:
+
+```typescript
+this.riveRef().setTextRunValueAtPath(
+  'button_text',
+  'Click Me',
+  'NestedArtboard/ButtonComponent'
+);
+```
+
+#### Controlled vs Uncontrolled
+
+- **Controlled**: Keys in `textRuns` input — managed by Angular, input is source of truth
+- **Uncontrolled**: Keys not in `textRuns` — managed imperatively via methods
+- **Warning**: Calling `setTextRunValue()` on a controlled key logs a warning and the change will be overwritten on next input update
+
 ### Preloading files with RiveFileService
 
 For better performance, you can preload and cache .riv files:
@@ -185,6 +236,75 @@ export class PreloadComponent {
 }
 ```
 
+## Debug Mode
+
+The library provides a built-in debug mode to help you troubleshoot animations.
+
+### Global Configuration
+
+Enable debug mode globally in your `app.config.ts`:
+
+```typescript
+import { provideRiveDebug } from '@grandgular/rive-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRiveDebug({ logLevel: 'debug' })
+  ]
+};
+```
+
+Available log levels: `'none' | 'error' | 'warn' | 'info' | 'debug'`
+
+### Local Override
+
+Enable debug mode for a specific component instance:
+
+```typescript
+<rive-canvas
+  src="assets/animation.riv"
+  [debugMode]="true" 
+/>
+```
+
+When debug mode is enabled, the library will log:
+- Loading progress and file details
+- Available artboards, animations, and state machines
+- Validation warnings (e.g., misspelled animation names)
+
+## Error Handling & Validation
+
+The library validates your configuration against the loaded Rive file and provides structured error codes.
+
+### Validation
+
+Validation errors (e.g., missing artboard or animation) are **non-fatal**. They are emitted via the `loadError` output but do not crash the application.
+
+```typescript
+<rive-canvas
+  src="assets/anim.riv"
+  [artboard]="'WrongName'"
+  (loadError)="onError($event)"
+/>
+```
+
+In this case, `onError` receives a `RiveValidationError` with code `RIVE_201`, and the library logs a warning with available artboard names.
+
+### Error Codes
+
+| Code | Type | Description |
+|------|------|-------------|
+| `RIVE_101` | Load | File not found (404) |
+| `RIVE_102` | Load | Invalid .riv file format |
+| `RIVE_103` | Load | Network error |
+| `RIVE_201` | Validation | Artboard not found |
+| `RIVE_202` | Validation | Animation not found |
+| `RIVE_203` | Validation | State machine not found |
+| `RIVE_204` | Validation | Input/Trigger not found in State Machine |
+| `RIVE_205` | Validation | Text run not found |
+| `RIVE_301` | Config | No animation source provided |
+| `RIVE_302` | Config | Invalid canvas element |
+
 ## API Reference
 
 ### RiveCanvasComponent
@@ -206,18 +326,22 @@ export class PreloadComponent {
 | `shouldUseIntersectionObserver` | `boolean` | `true` | Auto-pause when off-screen |
 | `shouldDisableRiveListeners` | `boolean` | `false` | Disable Rive event listeners |
 | `automaticallyHandleEvents` | `boolean` | `false` | Auto-handle Rive events (e.g., OpenUrlEvent) |
+| `debugMode` | `boolean` | `undefined` | Enable verbose logging for this instance |
+| `textRuns` | `Record<string, string>` | - | Declarative text run values. Keys present are controlled by input. |
 
 #### Outputs
 
 | Output | Type | Description |
 |--------|------|-------------|
 | `loaded` | `void` | Emitted when animation loads successfully |
-| `loadError` | `Error` | Emitted when animation fails to load |
+| `loadError` | `Error` | Emitted when animation fails to load or validation errors occur |
 | `stateChange` | `RiveEvent` | Emitted on state machine state changes |
 | `riveEvent` | `RiveEvent` | Emitted for custom Rive events |
-| `riveReady` | `Rive` | Emitted when Rive instance is created |
+| `riveReady` | `Rive` | Emitted when Rive instance is **fully loaded** and ready (after `loaded`) |
+
+#### Public Signals (Readonly)
 
-#### Public Signals
+All signals are **readonly** and cannot be mutated externally. Use the public methods to control the animation.
 
 | Signal | Type | Description |
 |--------|------|-------------|
@@ -226,6 +350,8 @@ export class PreloadComponent {
 | `isLoaded` | `Signal<boolean>` | Whether animation is loaded |
 | `riveInstance` | `Signal<Rive \| null>` | Direct access to Rive instance |
 
+**Note:** Signals are readonly to prevent external mutation. Use component methods (`playAnimation()`, `pauseAnimation()`, etc.) to control the animation state.
+
 #### Public Methods
 
 | Method | Description |
@@ -236,6 +362,10 @@ export class PreloadComponent {
 | `reset()` | Reset animation to beginning |
 | `setInput(stateMachine: string, input: string, value: number \| boolean)` | Set state machine input value |
 | `fireTrigger(stateMachine: string, trigger: string)` | Fire state machine trigger |
+| `getTextRunValue(name: string): string \| undefined` | Get text run value |
+| `setTextRunValue(name: string, value: string)` | Set text run value (warns if key is controlled) |
+| `getTextRunValueAtPath(name: string, path: string): string \| undefined` | Get nested text run value |
+| `setTextRunValueAtPath(name: string, value: string, path: string)` | Set nested text run |
 
 ### RiveFileService
 
@@ -255,6 +385,7 @@ Service for preloading and caching .riv files.
 interface RiveFileParams {
   src?: string;
   buffer?: ArrayBuffer;
+  debug?: boolean;
 }
 
 interface RiveFileState {
@@ -277,26 +408,25 @@ The library is fully compatible with Angular Universal and server-side rendering
 2. **Preload files**: Use `RiveFileService` to preload and cache .riv files for instant display
 3. **Disable unnecessary listeners**: Set `shouldDisableRiveListeners` to `true` for decorative animations without interactivity
 4. **Use OnPush**: The component already uses `OnPush` change detection for optimal performance
+5. **Reactive updates**: The component now reactively updates layout when `fit` or `alignment` change without full reload
 
-## Troubleshooting
-
-### Animation not loading
-
-- Verify the .riv file path is correct
-- Check browser console for errors
-- Ensure `@rive-app/canvas` is installed
-
-### State machine inputs not working
+## Recent Improvements (v0.2.0)
 
-- Verify state machine and input names match your .riv file
-- Check that the animation has loaded before calling `setInput` or `fireTrigger`
-- Use the `loaded` output to ensure timing
+### Quality & Stability
+- ✅ **Readonly signals** prevent accidental state mutation
+- ✅ **Dynamic DPR** support for multi-monitor setups
+- ✅ **Reactive configuration** - all inputs trigger appropriate updates
+- ✅ **Type-safe configuration** - eliminated unsafe type assertions
+- ✅ **Fixed race conditions** in file service and cache management
+- ✅ **Proper timing** - `riveReady` emits after full load
 
-### Memory leaks with RiveFileService
+### Developer Experience
+- 🛠️ **Enhanced validation** with detailed error messages
+- 🐛 **Comprehensive debugging** via `provideRiveDebug()`
+- 📝 **Better error codes** for programmatic error handling
+- 🧪 **Improved testability** with DI-based services
 
-- Always call `releaseFile` when done with a file
-- Use `DestroyRef.onDestroy` to auto-release files on component destroy
-- The service uses reference counting - files are only cleaned up when ref count reaches 0
+See [CHANGELOG.md](./CHANGELOG.md) for complete details, migration guide, and all improvements.
 
 ## Requirements