@xplortech/apollo-angular 2.11.0

package/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md — `@xplortech/apollo-angular`
+
+**Angular 19+** standalone bindings for Apollo web components (`@xplortech/apollo-core`). Part of the Apollo monorepo: https://github.com/xplor/apollo
+
+## Conventions
+
+See the root [AGENTS.md](https://github.com/xplor/apollo/blob/main/AGENTS.md) for npm-only workflows, Conventional Commits (**scope `angular`**), PR `Refs:` lines, and shared design-system rules.
+
+## This package (from repo root)
+
+| Task | Command |
+|------|---------|
+| Build | `nx build @xplortech/apollo-angular` |
+| TypeScript compile | `nx tsc @xplortech/apollo-angular` |
+| Clean | `nx clean @xplortech/apollo-angular` |
+
+There is no per-package lint or test target; lint runs at the workspace level via `npm run lint`.
+
+**Nx Release group:** `core`.
+
+## Public API
+
+- Usage, `[(ngModel)]`, and registration patterns: [README.md](./README.md)
+- Depends on `@xplortech/apollo-core` for custom elements and loader
+- Built from Stencil-generated proxies in `src/directives/` (regenerated by `nx build @xplortech/apollo-core`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023, Xplor XT1, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# Apollo Angular
+
+Angular bindings for the Apollo design system (`@xplortech/apollo-core` web components). Use this package in Angular apps for typed inputs, RxJS-backed outputs, and `[(ngModel)]` / reactive forms on form controls.
+
+## Installation
+
+Published as **`@xplortech/apollo-angular`** on the public npm registry (same scope as `@xplortech/apollo-core` and `@xplortech/apollo-react`).
+
+```bash
+npm install @xplortech/apollo-angular @xplortech/apollo-core
+```
+
+Peer dependencies: **Angular 19+**, **RxJS 7+**, and **TypeScript 5+**.
+
+Import styles once in your app (path may vary with your bundler):
+
+```ts
+// e.g. in styles.css / styles.scss
+@import '@xplortech/apollo-angular/css/apollo.css';
+```
+
+## Usage
+
+The package ships **standalone** Angular component wrappers (Angular 14+, the default since v17). Custom elements register automatically when you import any wrapper — there is no `APP_INITIALIZER` setup required.
+
+### Standalone components
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { TextValueAccessor, XplButton, XplInput } from '@xplortech/apollo-angular';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  // FormsModule + TextValueAccessor enable [(ngModel)] on xpl-input.
+  imports: [FormsModule, XplButton, XplInput, TextValueAccessor],
+  template: `
+    <xpl-input [(ngModel)]="email" label="Email" type="email"></xpl-input>
+    <xpl-button variant="primary" (click)="save()">Save</xpl-button>
+  `,
+})
+export class AppComponent {
+  email = '';
+  save() {}
+}
+```
+
+### NgModule consumers
+
+If your app still uses `NgModule`, import `DIRECTIVES` (the full array of wrappers) or individual wrappers into the `imports` array:
+
+```ts
+import { NgModule } from '@angular/core';
+import { DIRECTIVES } from '@xplortech/apollo-angular';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [...DIRECTIVES],
+})
+export class AppModule {}
+```
+
+## Forms (`[(ngModel)]` and reactive forms)
+
+These wrappers integrate as Angular `ControlValueAccessor` implementations:
+
+| Component     | Form value    | Update event (internal) | Value accessor        |
+|---------------|---------------|-------------------------|-----------------------|
+| `XplInput`    | `value`       | `valueChange`           | `TextValueAccessor`   |
+| `XplCheckbox` | `checked`     | `checkboxChange`        | `BooleanValueAccessor`|
+| `XplRadio`    | `selectedValue` | `radioChange`         | `RadioValueAccessor`  |
+| `XplToggle`   | `checked`     | `toggleChange`          | `BooleanValueAccessor`|
+| `XplSelect`   | `selectedValues` | `changeEvent`        | `SelectValueAccessor` |
+
+> **Standalone imports:** each form control's value accessor is a **separate
+> standalone directive**. To use `[(ngModel)]` or `formControlName` you must
+> import the matching value accessor alongside the component (see below), or
+> import the full `DIRECTIVES` array (which includes every wrapper **and** every
+> value accessor). `NgModule` consumers that import `...DIRECTIVES` get form
+> binding automatically.
+
+### Template-driven forms
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import {
+  BooleanValueAccessor,
+  TextValueAccessor,
+  XplCheckbox,
+  XplInput,
+  XplToggle,
+} from '@xplortech/apollo-angular';
+
+@Component({
+  selector: 'app-profile',
+  standalone: true,
+  imports: [
+    FormsModule,
+    XplCheckbox,
+    XplInput,
+    XplToggle,
+    // Value accessors register NG_VALUE_ACCESSOR on the hosts above.
+    TextValueAccessor,
+    BooleanValueAccessor,
+  ],
+  template: `
+    <xpl-input [(ngModel)]="name" label="Name"></xpl-input>
+    <xpl-checkbox [(ngModel)]="agreed" label="I agree"></xpl-checkbox>
+    <xpl-toggle [(ngModel)]="enabled">Enabled</xpl-toggle>
+  `,
+})
+export class ProfileComponent {
+  name = '';
+  agreed = false;
+  enabled = false;
+}
+```
+
+### Reactive forms
+
+```ts
+import { Component } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule } from '@angular/forms';
+import {
+  BooleanValueAccessor,
+  TextValueAccessor,
+  XplInput,
+  XplToggle,
+} from '@xplortech/apollo-angular';
+
+@Component({
+  selector: 'app-settings',
+  standalone: true,
+  imports: [
+    ReactiveFormsModule,
+    XplInput,
+    XplToggle,
+    TextValueAccessor,
+    BooleanValueAccessor,
+  ],
+  template: `
+    <form [formGroup]="form">
+      <xpl-input formControlName="name" label="Name"></xpl-input>
+      <xpl-toggle formControlName="enabled">Enabled</xpl-toggle>
+    </form>
+  `,
+})
+export class SettingsComponent {
+  form = this.fb.group({ name: '', enabled: false });
+  constructor(private fb: FormBuilder) {}
+}
+```
+
+> **Tip:** to avoid importing individual value accessors, import the whole
+> `DIRECTIVES` array in a standalone component's `imports` — it registers every
+> wrapper and value accessor at once.
+
+**Specialized input types:** `<xpl-input type="date">`, `type="time"`, `type="phone"`, `type="color"`, and `type="file"` all work with `[(ngModel)]`. Internally, `xpl-input` renders a sub-component (e.g. `xpl-input-date`) and forwards its events. Prefer `<xpl-input type="date" [(ngModel)]="val">` over using the sub-components directly.
+
+## Events and complex props
+
+Stencil `@Event()` names are exposed as Angular `@Output()` `EventEmitter`s and emit `CustomEvent` instances. Use `.detail` to read the payload:
+
+```html
+<xpl-table
+  [data]="rows"
+  [columns]="cols"
+  (tableSelect)="onSelect($event.detail)"
+></xpl-table>
+```
+
+Pass objects and arrays directly as `[propName]` bindings — Angular forwards them as DOM properties:
+
+```html
+<xpl-table [data]="rows" [columns]="cols"></xpl-table>
+```
+
+## Further reading
+
+- [Apollo repo](https://github.com/xplor/apollo)
+- Core components and behavior: `@xplortech/apollo-core` / Storybook in this monorepo
+- [Stencil Angular output target docs](https://stenciljs.com/docs/angular)