exodeui-angular 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# ExodeUI Angular
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Angular runtime for the [ExodeUI](https://exodeui.com/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular) motion engine.** Use `<exodeui-canvas>` to play interactive, physics-driven UI animation designed in ExodeUI inside standalone Angular components — with `@Input`/`@Output` bindings and a service for imperative control.
+
+[![npm version](https://img.shields.io/npm/v/exodeui-angular.svg)](https://www.npmjs.com/package/exodeui-angular)
+[![license](https://img.shields.io/npm/l/exodeui-angular.svg)](https://www.npmjs.com/package/exodeui-angular)
+[![website](https://img.shields.io/badge/docs-exodeui.com-0f172a)](https://exodeui.com/docs?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular)
+
+ExodeUI is an AI-native **motion development environment (MDE)**: vector design, timeline animation, Rapier physics and state-machine logic on a single canvas, exported as portable `.exode` artboards. This package renders those artboards with the same Canvas 2D engine used by every ExodeUI framework runtime.
+
+---
+
+## Highlights
+
+- **Angular 17+ standalone component.** Drop it into any feature module or standalone app, `OnPush` by default.
+- **Zone-safe performance.** The render loop runs outside `NgZone`, so 60/120fps animation never triggers change detection; outputs re-enter the zone only when they fire.
+- **Typed inputs and outputs.** Every sensor, layout and callback is an `@Input`/`@Output`.
+- **Service for imperative control.** Inject `ExodeUIService`, register the engine once, and drive inputs from anywhere.
+- **Behaviour parity.** Matches the [React](https://www.npmjs.com/package/exodeui), [Vue](https://www.npmjs.com/package/exodeui-vue), [Svelte](https://www.npmjs.com/package/exodeui-svelte), [Solid](https://www.npmjs.com/package/exodeui-solid) and [vanilla](https://www.npmjs.com/package/exodeui-vanilla) runtimes.
+
+## Installation
+
+```bash
+npm install exodeui-angular
+# or
+pnpm add exodeui-angular
+```
+
+Requires `@angular/core` and `@angular/common` `>= 17`.
+
+## Quick start
+
+### `app.component.html`
+
+```html
+<div style="width: 800px; height: 600px;">
+  <exodeui-canvas
+    [artboard]="artboard"
+    fit="Contain"
+    alignment="Center"
+    (ready)="exoService.register($event)"
+    (trigger)="onTrigger($event)"
+    (navigation)="onNavigation($event)"
+  ></exodeui-canvas>
+</div>
+```
+
+### `app.component.ts`
+
+```ts
+import { Component, inject } from '@angular/core';
+import { ExodeUICanvasComponent, ExodeUIService } from 'exodeui-angular';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ExodeUICanvasComponent],
+  templateUrl: './app.component.html',
+})
+export class AppComponent {
+  exoService = inject(ExodeUIService);
+  artboard = /* parsed .exode JSON */;
+
+  onTrigger({ name, anim }: { name: string; anim: string }) {
+    console.log('trigger', name, anim);
+  }
+
+  onNavigation({ type, value }: { type: string; value: string }) {
+    if (type === 'url') window.location.href = value;
+  }
+}
+```
+
+### Drive motion from your own UI
+
+```ts
+selectTab(index: number) {
+  this.exoService.updateInput('activeTab', index);
+  this.exoService.fireTrigger('TabChange');
+}
+```
+
+### Static frame
+
+```html
+<exodeui-canvas [artboard]="artboard" [autoPlay]="false" [currentTime]="1.25" />
+```
+
+## Supported features
+
+| Capability | Included |
+| --- | --- |
+| Canvas 2D renderer with DPR-aware scaling | ✅ |
+| State machine + logic nodes (AND / OR / XOR / NOT) | ✅ |
+| Boolean, number, text, trigger, array, random inputs | ✅ |
+| 2D physics (Rapier): dynamic, static, kinematic bodies | ✅ |
+| Spring, drag, joystick, pointer and keyboard sensors | ✅ |
+| Responsive layouts, breakpoints and spatial constraints | ✅ |
+| Line graphs, bar charts and pie charts with live data | ✅ |
+| Text inputs, toggles, dropdowns, sliders and list views | ✅ |
+| Scroll-linked and viewport-driven animation | ✅ |
+| `.exode` JSON and compressed `.bexode` loading | ✅ |
+| Glow, light trails, pattern grids, masks | ✅ |
+
+## API
+
+### `<exodeui-canvas>` inputs
+
+| Input | Type | Default | Description |
+| --- | --- | --- | --- |
+| `artboard` | `Artboard` | — | Parsed artboard JSON |
+| `src` | `string` | — | `.exode` / `.bexode` URL or JSON string |
+| `buffer` | `ArrayBuffer \| Uint8Array` | — | Pre-read `.bexode` buffer |
+| `revision` | `number` | `0` | Bump to force a reload |
+| `fit` | `Fit` | `'Contain'` | Fit mode |
+| `alignment` | `Alignment` | `'Center'` | Alignment |
+| `layoutScaleFactor` | `number` | — | Extra scale for `Fit: 'Layout'` |
+| `autoPlay` | `boolean` | `true` | Auto-start the loop |
+| `interactive` | `boolean` | `true` | Enable input handling |
+| `preventScroll` | `boolean` | `true` | Block page scroll on wheel/touch |
+| `highRefreshRate` | `boolean` | `true` | Sub-frame pacing on 120Hz displays |
+| `currentTime` | `number` | — | Render a fixed time when `autoPlay` is false |
+| `scrollX/Y`, `viewportScrollX/Y` | `number` | — | External scroll sensors |
+| `mouseX/Y`, `isMouseDown` | `number \| boolean` | — | External pointer sensors |
+| `inputs` | `Record<string, any>` | — | Inputs applied on load |
+| `callbacks` | `Record<string, Function>` | — | Named listeners from the editor |
+
+### Outputs
+
+`(ready)`, `(trigger)`, `(inputUpdate)`, `(componentChange)`, `(toggle)`, `(inputChange)`, `(inputFocus)`, `(inputBlur)`, `(navigation)`, `(buttonClick)`, `(graphPointClick)`, `(log)`, `(logicUpdate)`, `(fpsUpdate)`
+
+### Component methods
+
+`getEngine()`, `play()`, `pause()`, `seek(time)`, `resize()`, `setLayout(fit, alignment?, scale?)`, `setOptions(options)`, `setInputBool/Number/Text`, `fireTrigger`, `updateInput`, `updateGraphData`, `getInputValue`
+
+### `ExodeUIService`
+
+`register(engine)`, `updateInput`, `setInputBool`, `setInputNumber`, `setInputText`, `fireTrigger`, `updateObjectOptions`, `updateConstraint`, `updateGraphData`, `updateObjectProperty`, `setDropdownOptions`, `getInputValue`
+
+## FAQ
+
+**Does it break zone stability?** No — animation and pointer handling run outside `NgZone`; only emitted events re-enter it.
+
+**Does it work with Angular Universal / SSR?** Yes, the canvas initialises after `ngAfterViewInit`.
+
+**Is ExodeUI a Rive or Lottie alternative?** It targets interactive UI, not linear playback — see the [Rive comparison](https://exodeui.com/alternatives/rive/?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular).
+
+**How do I update chart data?** Call `updateGraphData`, `updateBarChartData` or `updatePieChartData` on the service or component.
+
+**What is a `.exode` file?** The portable artboard exported by the ExodeUI editor — plain JSON, or compressed `.bexode`.
+
+## Related packages
+
+- [exodeui](https://www.npmjs.com/package/exodeui) — React runtime and Vite plugin
+- [exodeui-vanilla](https://www.npmjs.com/package/exodeui-vanilla) — framework-free runtime
+- [exodeui-vue](https://www.npmjs.com/package/exodeui-vue) — Vue 3 runtime
+- [exodeui-svelte](https://www.npmjs.com/package/exodeui-svelte) — Svelte 5 runtime
+- [exodeui-solid](https://www.npmjs.com/package/exodeui-solid) — SolidJS runtime
+
+## Learn more
+
+- [Documentation](https://exodeui.com/docs?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular)
+- [Examples and templates](https://exodeui.com/examples?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular)
+- [Component gallery](https://exodeui.com/components?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular)
+- [For teams](https://exodeui.com/for/teams?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular)
+- [Glossary](https://exodeui.com/glossary?utm_source=npm&utm_medium=readme&utm_campaign=exodeui-angular)
+
+## License
+
+MIT © ExodeUI