@blotch/angular-lynx 0.0.0-stage → 22.2.0

package/README.md

@@ -1,3 +1,182 @@
-# Temporary Holding Version
+# @blotch/angular-lynx
 
-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 renderer for [Lynx](https://lynxjs.org/). Write Angular components, render to native iOS, Android, and Web via the Lynx engine.
+
+## Quick Start
+
+```bash
+npm create angular-lynx my-app
+```
+
+Or add to an existing Angular project:
+
+```bash
+ng add @blotch/angular-lynx
+```
+
+## Features
+
+- Standalone components with signals, `@if`/`@for`/`@switch`, DI, and pipes
+- Zoneless change detection — signals as the primary reactivity model
+- Full Angular Router with in-memory navigation for Lynx
+- Gestures — tap, pan, long-press, fling, pinch, rotation with composition
+- Animations — CSS transitions, keyframes, and programmatic `animate()` API
+- Content projection, portals, `@defer`, and lazy-loaded routes
+- Tailwind CSS via `@lynx-js/tailwind-preset`
+
+## Documentation
+
+Full docs and guides at [angularlynx.dev](https://angularlynx.dev).
+
+---
+
+## Animation API
+
+Three animation approaches are available, all running natively on the Lynx engine.
+
+### CSS Transitions
+
+Apply `transition` in your stylesheet. Lynx interpolates property changes automatically.
+
+```css
+.box {
+  background-color: #6200ee;
+  transition: background-color 0.5s ease-in-out;
+}
+
+.box-active {
+  background-color: #03dac6;
+}
+```
+
+```html
+<view class="box" [class.box-active]="isActive()" (bindtap)="toggle()">
+  <text>Tap me</text>
+</view>
+```
+
+### CSS Keyframe Animations
+
+Define `@keyframes` in your stylesheet and apply via class toggle.
+
+```css
+@keyframes rotate {
+  0% {
+    transform: rotate(0deg);
+  }
+  100% {
+    transform: rotate(360deg);
+  }
+}
+
+.spinning {
+  animation: rotate 2s linear infinite;
+}
+```
+
+```html
+<view class="box" [class.spinning]="spin()">
+  <text>Rotating</text>
+</view>
+```
+
+### JavaScript Animate API
+
+Use `element.animate()` on a native element reference for programmatic control. Calls the Lynx `__ElementAnimate` PAPI under the hood.
+
+```typescript
+import { Component, viewChild, type ElementRef } from '@angular/core';
+import { type LynxAnimation } from '@blotch/angular-lynx';
+
+@Component({
+  selector: 'app-example',
+  template: `
+    <view #box class="box" (bindtap)="runAnimation()">
+      <text>Tap to animate</text>
+    </view>
+  `,
+})
+export class ExampleComponent {
+  boxRef = viewChild<ElementRef>('box');
+  #animation: LynxAnimation | null = null;
+
+  runAnimation(): void {
+    setTimeout(() => {
+      const el = this.boxRef();
+      if (!el) return;
+
+      // Cancel previous animation before starting a new one.
+      this.#animation?.cancel();
+
+      this.#animation = el.nativeElement.animate(
+        [
+          { transform: 'scale(1)', opacity: 1 },
+          { transform: 'scale(1.3)', opacity: 0.7 },
+          { transform: 'scale(1)', opacity: 1 },
+        ],
+        {
+          duration: 600,
+          easing: 'ease-in-out',
+        },
+      );
+    }, 0);
+  }
+}
+```
+
+#### `animate()` API
+
+```typescript
+element.nativeElement.animate(
+  keyframes: Record<string, string | number>[],
+  options?: number | LynxAnimationOptions,
+): LynxAnimation
+```
+
+**Parameters:**
+
+| Parameter   | Type                                 | Description                                                               |
+| ----------- | ------------------------------------ | ------------------------------------------------------------------------- |
+| `keyframes` | `Record<string, string \| number>[]` | Array of keyframe objects. Each object maps CSS property names to values. |
+| `options`   | `number \| LynxAnimationOptions`     | Duration in ms (shorthand) or full options object.                        |
+
+**`LynxAnimationOptions`:**
+
+| Option                          | Type               | Description                                                                            |
+| ------------------------------- | ------------------ | -------------------------------------------------------------------------------------- |
+| `duration`                      | `number \| string` | Animation duration in milliseconds.                                                    |
+| `delay`                         | `number \| string` | Delay before animation starts.                                                         |
+| `iterations` / `iterationCount` | `number \| string` | Number of repetitions. Use `Infinity` for infinite.                                    |
+| `easing` / `timingFunction`     | `string`           | Easing function (`linear`, `ease-in`, `ease-out`, `ease-in-out`, `cubic-bezier(...)`). |
+| `fill` / `fillMode`             | `string`           | How styles persist after animation (`none`, `forwards`, `backwards`, `both`).          |
+| `direction`                     | `string`           | Play direction (`normal`, `reverse`, `alternate`, `alternate-reverse`).                |
+| `name`                          | `string`           | Optional animation name (auto-generated if omitted).                                   |
+
+**Returns:** `LynxAnimation` with control methods:
+
+| Method     | Description                        |
+| ---------- | ---------------------------------- |
+| `play()`   | Resume a paused animation.         |
+| `pause()`  | Pause the animation.               |
+| `cancel()` | Cancel and clean up the animation. |
+
+#### Animation Events
+
+Lynx fires standard animation events on elements. Listen in templates using bind-prefixed event names:
+
+```html
+<view
+  class="animated-box"
+  (bindanimationend)="onAnimationEnd($event)"
+  (bindtransitionend)="onTransitionEnd($event)"
+>
+  <text>Animated</text>
+</view>
+```
+
+Available events: `animationstart`, `animationend`, `animationcancel`, `animationiteration`, `transitionstart`, `transitionend`, `transitioncancel`.
+
+#### Important Notes
+
+- The `animate()` API is **main-thread only**. Calling it on the background thread throws an error.
+- Wrap `animate()` calls inside `setTimeout(() => { ... }, 0)` when triggered from Lynx event callbacks to avoid mutating the element tree inside a worklet.

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@blotch/angular-lynx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "22.2.0",
+  "description": "Angular renderer for the Lynx cross-platform native UI framework",
+  "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
+  "bugs": {
+    "url": "https://github.com/Blotch-Smart-Frames/AngularLynx/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Blotch-Smart-Frames/AngularLynx.git",
+    "directory": "packages/runtime"
+  },
+  "files": [
+    "dist",
+    "schematics",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/blotch-angular-lynx.d.ts",
+      "default": "./fesm2022/blotch-angular-lynx.mjs"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "peerDependencies": {
+    "@angular/common": "^22.2.0",
+    "@angular/core": "^22.2.0",
+    "@angular/forms": "^22.2.0",
+    "@angular/localize": "^22.2.0",
+    "@angular/platform-browser": "^22.2.0",
+    "@angular/router": "^22.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@angular/forms": {
+      "optional": true
+    },
+    "@angular/localize": {
+      "optional": true
+    }
+  },
+  "schematics": "./schematics/collection.json",
+  "module": "fesm2022/blotch-angular-lynx.mjs",
+  "typings": "types/blotch-angular-lynx.d.ts",
+  "type": "module"
 }

package/schematics/add-i18n/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularLynxAddI18n",
+  "title": "AngularLynx add-i18n schematic",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Adds Angular i18n support with @angular/localize and provideLocale() to an existing project.",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project to add i18n support to.",
+      "$default": {
+        "$source": "projectName"
+      }
+    }
+  },
+  "required": []
+}

package/schematics/add-tailwind/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularLynxAddTailwind",
+  "title": "AngularLynx add-tailwind schematic",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Adds Tailwind CSS with @lynx-js/tailwind-preset to an existing AngularLynx project.",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project to add Tailwind CSS to.",
+      "$default": {
+        "$source": "projectName"
+      }
+    }
+  },
+  "required": []
+}

package/schematics/add-testing/schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularLynxAddTesting",
+  "title": "AngularLynx add-testing schematic",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Adds AngularLynx Testing Library with Vitest to an existing project.",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project to add testing to.",
+      "$default": {
+        "$source": "projectName"
+      }
+    }
+  },
+  "required": []
+}

package/schematics/collection.json

@@ -0,0 +1,30 @@
+{
+  "schematics": {
+    "ng-add": {
+      "description": "Transforms an Angular project into a Lynx-native application",
+      "factory": "./ng-add/index",
+      "schema": "./ng-add/schema.json"
+    },
+    "add-tailwind": {
+      "description": "Adds Tailwind CSS with @lynx-js/tailwind-preset to an existing project",
+      "factory": "./add-tailwind/index",
+      "schema": "./add-tailwind/schema.json"
+    },
+    "add-testing": {
+      "description": "Adds AngularLynx Testing Library with Vitest to an existing project",
+      "factory": "./add-testing/index",
+      "schema": "./add-testing/schema.json"
+    },
+    "add-i18n": {
+      "description": "Adds Angular i18n support with @angular/localize and provideLocale() to an existing project",
+      "factory": "./add-i18n/index",
+      "schema": "./add-i18n/schema.json"
+    },
+    "component": {
+      "description": "Generates a standalone Angular component with Lynx element template",
+      "factory": "./component/index",
+      "schema": "./component/schema.json",
+      "aliases": ["c"]
+    }
+  }
+}

package/schematics/component/schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularLynxComponent",
+  "title": "AngularLynx component schematic",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Generates a standalone Angular component with Lynx element template.",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the component.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the component?"
+    },
+    "path": {
+      "type": "string",
+      "format": "path",
+      "description": "The path at which to create the component, relative to the source root.",
+      "visible": false
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "prefix": {
+      "type": "string",
+      "description": "The selector prefix to use. Defaults to the project prefix from angular.json."
+    },
+    "inlineStyle": {
+      "type": "boolean",
+      "description": "Include styles inline in the component.ts file.",
+      "default": true,
+      "alias": "s"
+    },
+    "inlineTemplate": {
+      "type": "boolean",
+      "description": "Include template inline in the component.ts file.",
+      "default": true,
+      "alias": "t"
+    },
+    "skipTests": {
+      "type": "boolean",
+      "description": "Do not generate a spec file.",
+      "default": false
+    },
+    "flat": {
+      "type": "boolean",
+      "description": "Create the component files at the top level of the path, without a subdirectory.",
+      "default": false
+    }
+  },
+  "required": ["name"]
+}

package/schematics/files/lynx.config.ts.template

@@ -0,0 +1,17 @@
+import { pluginAngularLynx } from '@blotch/rsbuild-plugin-angular-lynx';
+import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin';
+import { defineConfig } from '@lynx-js/rspeedy';
+
+export default defineConfig({
+  source: {
+    entry: './src/main.ts',
+  },
+  plugins: [
+    pluginQRCode({
+      schema(url) {
+        return `${url}?fullscreen=true`;
+      },
+    }),
+    pluginAngularLynx(),
+  ],
+});

package/schematics/files/src/rspeedy-env.d.ts.template

@@ -0,0 +1 @@
+/// <reference types="@lynx-js/rspeedy/client" />

package/schematics/ng-add/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "SchematicsAngularLynxNgAdd",
+  "title": "AngularLynx ng-add schematic",
+  "type": "object",
+  "additionalProperties": false,
+  "description": "Transforms an Angular project into a Lynx-native application.",
+  "properties": {
+    "project": {
+      "type": "string",
+      "description": "The name of the project to transform.",
+      "$default": {
+        "$source": "projectName"
+      }
+    },
+    "tailwind": {
+      "type": "boolean",
+      "description": "Whether to add Tailwind CSS with @lynx-js/tailwind-preset.",
+      "default": true,
+      "x-prompt": "Would you like to add Tailwind CSS with Lynx preset?"
+    }
+  },
+  "required": []
+}