@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-angular-calls/references/picture-in-picture.md

@@ -0,0 +1,285 @@
+# Picture-in-Picture on Angular
+
+Same browser APIs as React (Video PiP + Document PiP) — the SDK and underlying primitives are identical because Angular wraps the JS Calls SDK. For API-level details, browser support, and the Document PiP path, read `cometchat-react-calls/references/picture-in-picture.md` first. This reference covers Angular-specific wiring.
+
+---
+
+## Video PiP — Angular component pattern
+
+```ts
+// components/pip-button/pip-button.component.ts
+@Component({
+  selector: "app-pip-button",
+  template: `
+    <button (click)="togglePip()" [disabled]="!supported" *ngIf="supported">
+      {{ inPip ? "Exit PiP" : "Enter PiP" }}
+    </button>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class PipButtonComponent implements OnInit, OnDestroy {
+  @Input() videoRef!: ElementRef<HTMLVideoElement>;
+  inPip = false;
+  supported = typeof document !== "undefined" && document.pictureInPictureEnabled;
+
+  private enterListener?: () => void;
+  private leaveListener?: () => void;
+
+  constructor(private zone: NgZone, private cd: ChangeDetectorRef) {}
+
+  ngOnInit() {
+    if (!this.videoRef?.nativeElement) return;
+    const video = this.videoRef.nativeElement;
+
+    this.enterListener = () => this.zone.run(() => { this.inPip = true; this.cd.markForCheck(); });
+    this.leaveListener = () => this.zone.run(() => { this.inPip = false; this.cd.markForCheck(); });
+
+    video.addEventListener("enterpictureinpicture", this.enterListener);
+    video.addEventListener("leavepictureinpicture", this.leaveListener);
+  }
+
+  ngOnDestroy() {
+    const video = this.videoRef?.nativeElement;
+    if (!video) return;
+    if (this.enterListener) video.removeEventListener("enterpictureinpicture", this.enterListener);
+    if (this.leaveListener) video.removeEventListener("leavepictureinpicture", this.leaveListener);
+    if (document.pictureInPictureElement) {
+      document.exitPictureInPicture().catch(() => {});
+    }
+  }
+
+  async togglePip() {
+    if (!this.videoRef?.nativeElement) return;
+    if (this.inPip) {
+      await document.exitPictureInPicture();
+    } else {
+      try {
+        await this.videoRef.nativeElement.requestPictureInPicture();
+      } catch (err) {
+        console.warn("PiP request failed:", err);
+      }
+    }
+  }
+}
+```
+
+The `@Input() videoRef` is the parent's `<video>` element via `@ViewChild`. NgZone wraps the events so OnPush components re-render correctly.
+
+Usage in the call screen:
+
+```ts
+@Component({
+  selector: "app-ongoing-call",
+  template: `
+    <video #remoteVideo autoplay playsinline [class.hidden]="inPip"></video>
+    <app-pip-button [videoRef]="remoteVideo"></app-pip-button>
+  `,
+  styles: [`
+    .hidden { visibility: hidden; }
+  `],
+})
+export class OngoingCallComponent {
+  @ViewChild("remoteVideo") remoteVideo!: ElementRef<HTMLVideoElement>;
+  inPip = false;
+}
+```
+
+---
+
+## Document PiP — Angular host element transfer
+
+Document PiP lets you put arbitrary HTML in a floating window, including a full Angular component subtree. The challenge: detaching + re-attaching a DOM node mid-Angular-lifecycle.
+
+```ts
+// services/document-pip.service.ts
+import { Injectable, NgZone, RendererFactory2, Renderer2 } from "@angular/core";
+
+@Injectable({ providedIn: "root" })
+export class DocumentPipService {
+  private pipWindow: Window | null = null;
+  private renderer: Renderer2;
+
+  constructor(private zone: NgZone, private rendererFactory: RendererFactory2) {
+    this.renderer = rendererFactory.createRenderer(null, null);
+  }
+
+  get supported(): boolean {
+    return typeof window !== "undefined" && "documentPictureInPicture" in window;
+  }
+
+  async openWindow(content: HTMLElement, options: { width?: number; height?: number } = {}): Promise<Window | null> {
+    if (!this.supported) return null;
+
+    this.pipWindow = await (window as unknown as {
+      documentPictureInPicture: { requestWindow: (o: object) => Promise<Window> };
+    }).documentPictureInPicture.requestWindow({
+      width: options.width ?? 360,
+      height: options.height ?? 480,
+    });
+
+    // Copy stylesheets so kit + Angular Material styles work in the PiP window
+    for (const sheet of Array.from(document.styleSheets)) {
+      try {
+        const cssText = Array.from(sheet.cssRules ?? []).map(r => r.cssText).join("\n");
+        const style = this.pipWindow.document.createElement("style");
+        style.textContent = cssText;
+        this.pipWindow.document.head.appendChild(style);
+      } catch {
+        if (sheet.href) {
+          const link = this.pipWindow.document.createElement("link");
+          link.rel = "stylesheet";
+          link.href = sheet.href;
+          this.pipWindow.document.head.appendChild(link);
+        }
+      }
+    }
+
+    this.pipWindow.document.body.appendChild(content);
+
+    return this.pipWindow;
+  }
+
+  closeWindow() {
+    if (this.pipWindow) {
+      this.pipWindow.close();
+      this.pipWindow = null;
+    }
+  }
+}
+```
+
+Then in the call component:
+
+```ts
+@Component({
+  // ...
+  template: `
+    <div #callRoot class="call-root">
+      <video #remoteVideo autoplay playsinline></video>
+      <app-control-panel></app-control-panel>
+    </div>
+  `,
+})
+export class OngoingCallComponent {
+  @ViewChild("callRoot", { static: true }) callRoot!: ElementRef<HTMLElement>;
+
+  constructor(private docPip: DocumentPipService, private zone: NgZone) {}
+
+  async enterDocumentPip() {
+    const pipWin = await this.docPip.openWindow(this.callRoot.nativeElement);
+    if (!pipWin) return;
+
+    pipWin.addEventListener("pagehide", () => {
+      this.zone.run(() => {
+        // Restore the call-root back to the original mount point
+        const host = document.getElementById("call-host");
+        if (host && this.callRoot.nativeElement) {
+          host.appendChild(this.callRoot.nativeElement);
+        }
+      });
+    });
+  }
+}
+```
+
+When you transfer the DOM node into the PiP window, Angular's change detection still works because the node is the same. Click handlers, OnPush updates, NgZone events all continue functioning across the window boundary. This is the magic of Document PiP.
+
+---
+
+## Auto-PiP on tab/window backgrounding
+
+```ts
+@Component({...})
+export class OngoingCallComponent implements OnInit, OnDestroy {
+  private visibilitySub?: Subscription;
+
+  ngOnInit() {
+    if (!document.pictureInPictureEnabled) return;
+    this.visibilitySub = fromEvent(document, "visibilitychange").subscribe(() => {
+      if (document.visibilityState === "hidden" && this.callActive) {
+        this.zone.run(() => {
+          this.remoteVideo.nativeElement.requestPictureInPicture().catch(() => {});
+        });
+      }
+    });
+  }
+
+  ngOnDestroy() {
+    this.visibilitySub?.unsubscribe();
+  }
+}
+```
+
+Same caveats as React — Safari rejects auto-PiP from non-user-gesture contexts in some versions. Test on real Safari before relying on this.
+
+---
+
+## Auto-leave on hangup
+
+```ts
+async endCall() {
+  if (document.pictureInPictureElement) {
+    await document.exitPictureInPicture();
+  }
+  this.docPip.closeWindow();
+
+  CometChatCalls.leaveSession();   // v5 canonical (endSession is a deprecated shim)
+  // ...rest of cleanup
+}
+```
+
+---
+
+## SSR considerations (Angular Universal)
+
+Document and Video PiP both reference `document.pictureInPictureEnabled` and `window.documentPictureInPicture`. Both are browser-only — guard:
+
+```ts
+import { isPlatformBrowser } from "@angular/common";
+
+constructor(@Inject(PLATFORM_ID) private platformId: object) {}
+
+get supported() {
+  return isPlatformBrowser(this.platformId)
+    && typeof document !== "undefined"
+    && document.pictureInPictureEnabled;
+}
+```
+
+Without this, SSR build crashes at boot.
+
+---
+
+## Anti-patterns
+
+1. **`requestPictureInPicture()` from `ngOnInit`.** Browsers reject — needs user gesture. `(click)` is the trigger.
+2. **Skipping `NgZone.run`** for PiP enter/leave events. OnPush components don't re-render.
+3. **Document PiP without copying stylesheets.** PiP window unstyled.
+4. **Forgetting `pagehide` cleanup** when user closes the PiP window via system X. DOM node stays detached; controls broken.
+5. **No SSR guard.** Universal build crashes.
+6. **Two separate video elements** (one for normal, one for PiP). Use one `<video>` and `[class.hidden]` it.
+7. **Auto-PiP in `ngOnInit` with no user-gesture context.** Safari rejects.
+
+---
+
+## Verification checklist
+
+- [ ] PiP button feature-detects `document.pictureInPictureEnabled`
+- [ ] Button hidden / disabled when unsupported
+- [ ] PiP request from `(click)`, not `ngOnInit`
+- [ ] `enterpictureinpicture` / `leavepictureinpicture` listeners wrapped in NgZone
+- [ ] OnPush components call `markForCheck()` after PiP state change
+- [ ] In-page video hidden while PiP active
+- [ ] Hangup path calls `document.exitPictureInPicture()` if active
+- [ ] Document PiP path closes window via `docPip.closeWindow()`
+- [ ] SSR builds: `isPlatformBrowser` guards
+- [ ] Real-browser smoke: Chrome (both APIs) + Safari (Video PiP) + Firefox (Video PiP)
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/picture-in-picture.md` — sister reference (browser API details, Document PiP semantics, browser support)
+- `references/custom-ui.md` — Angular custom call UI (PiP integration via @ViewChild on the video element)
+- `references/lazy-loading-pitfalls.md` — eager loading + SSR guards
+- `cometchat-angular-calls` SKILL.md — base hard rules

package/skills/cometchat-angular-calls/references/raise-hand.md

@@ -0,0 +1,167 @@
+# Raise hand on Angular
+
+Same SDK API as web (`@cometchat/calls-sdk-javascript`). Angular-specific wiring: NgZone wrap on listeners, RxJS Subject for the raised-hands roster, OnPush + markForCheck.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/raise-hand
+**Read first:** `cometchat-react-calls/references/raise-hand.md` — integration shape + anti-patterns are identical; this reference is the Angular-specific wiring.
+
+---
+
+## SDK API (same as web)
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+CometChatCalls.raiseHand();
+CometChatCalls.lowerHand();
+```
+
+---
+
+## Angular wiring — service-driven roster
+
+Centralize raise-hand state in a service so any component can subscribe:
+
+```ts
+// services/raise-hand.service.ts
+import { Injectable, NgZone, OnDestroy } from "@angular/core";
+import { BehaviorSubject } from "rxjs";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+interface RaisedParticipant { uid: string; name: string; raisedAt: number; }
+
+@Injectable({ providedIn: "root" })
+export class RaiseHandService implements OnDestroy {
+  private readonly raised = new Map<string, RaisedParticipant>();
+  readonly raised$ = new BehaviorSubject<RaisedParticipant[]>([]);
+
+  private onRaised = (p: { uid: string; name: string }) => {
+    this.zone.run(() => {
+      this.raised.set(p.uid, { ...p, raisedAt: Date.now() });
+      this.emit();
+    });
+  };
+
+  private onLowered = (p: { uid: string }) => {
+    this.zone.run(() => {
+      this.raised.delete(p.uid);
+      this.emit();
+    });
+  };
+
+  constructor(private zone: NgZone) {
+    CometChatCalls.addEventListener("onParticipantHandRaised", this.onRaised);
+    CometChatCalls.addEventListener("onParticipantHandLowered", this.onLowered);
+  }
+
+  ngOnDestroy() {
+    CometChatCalls.removeEventListener("onParticipantHandRaised", this.onRaised);
+    CometChatCalls.removeEventListener("onParticipantHandLowered", this.onLowered);
+  }
+
+  raise() { CometChatCalls.raiseHand(); }
+  lower() { CometChatCalls.lowerHand(); }
+
+  private emit() {
+    const sorted = Array.from(this.raised.values()).sort((a, b) => a.raisedAt - b.raisedAt);
+    this.raised$.next(sorted);
+  }
+}
+```
+
+The `NgZone.run` wrapping is the canonical Angular rule (see `references/ngzone-and-async-callbacks.md`) — without it, `BehaviorSubject.next` doesn't trigger change detection in OnPush components.
+
+---
+
+## Toggle button component
+
+```ts
+@Component({
+  selector: "app-raise-hand-button",
+  template: `
+    <button
+      (click)="toggle()"
+      [class.active]="raised"
+      [attr.aria-pressed]="raised"
+      [attr.aria-label]="raised ? 'Lower hand' : 'Raise hand'"
+    >
+      ✋ {{ raised ? "Lower" : "Raise" }}
+    </button>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class RaiseHandButtonComponent {
+  raised = false;
+  constructor(private svc: RaiseHandService, private cd: ChangeDetectorRef) {}
+
+  toggle() {
+    if (this.raised) this.svc.lower();
+    else this.svc.raise();
+    this.raised = !this.raised;
+    this.cd.markForCheck();
+  }
+}
+```
+
+---
+
+## Roster component (host view)
+
+```ts
+@Component({
+  selector: "app-raised-hands-list",
+  template: `
+    <div *ngIf="(raised$ | async) as list">
+      <ul *ngIf="list.length > 0" aria-label="Raised hands queue">
+        <li *ngFor="let p of list; trackBy: trackByUid">
+          ✋ {{ p.name }} <span class="ago">{{ secondsAgo(p.raisedAt) }}</span>
+        </li>
+      </ul>
+    </div>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class RaisedHandsListComponent {
+  raised$ = this.svc.raised$;
+  constructor(private svc: RaiseHandService) {}
+  trackByUid(_: number, p: RaisedParticipant) { return p.uid; }
+  secondsAgo(t: number) { return `${Math.round((Date.now() - t) / 1000)}s ago`; }
+}
+```
+
+`trackByUid` is critical — without it, Angular re-renders every list item on every emit, which is bad for FlatList-style smooth scroll.
+
+---
+
+## Anti-patterns
+
+Same shape as web sister reference, plus Angular-specific:
+
+1. **Service NOT provided in `root`.** If raise-hand service is provided in a feature module, it instantiates on lazy-load — listeners attach late. Provide in root so it boots with the app.
+2. **Skipping `markForCheck` with OnPush.** Service emits, component doesn't re-render.
+3. **Forgetting `ngOnDestroy` cleanup.** Service is `providedIn: "root"` so it lives forever, but the listeners would survive across logout/re-login. Reset on `CometChatUIKit.logout`.
+4. **`*ngFor` without `trackBy`.** Re-renders thrash; tile state lost.
+
+---
+
+## Verification checklist
+
+- [ ] `RaiseHandService` provided in root
+- [ ] `NgZone.run` wraps both listener callbacks
+- [ ] `BehaviorSubject` emits sorted-by-raisedAt list
+- [ ] Toggle button has `aria-pressed` + `aria-label`
+- [ ] Roster uses `trackBy: trackByUid`
+- [ ] OnPush components call `markForCheck()` on state change
+- [ ] Listeners cleaned up in `ngOnDestroy`
+- [ ] `hideRaiseHandButton: true` in CallSettings if using custom UI
+- [ ] Browser smoke: 3 tabs in same call → host's roster updates with markForCheck
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/raise-hand.md` — sister reference
+- `references/ngzone-and-async-callbacks.md` — NgZone primer
+- `references/group-calls.md` — group call architecture in Angular
+- `cometchat-a11y` — `aria-pressed` + screen reader announcements
+- Canonical docs: https://www.cometchat.com/docs/calls/javascript/raise-hand