@radix-ng/primitives 0.11.1 → 0.12.0

package/portal/stories/portal.docs.mdx

@@ -0,0 +1,85 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Utilities/Portal" />
+
+# Portal
+
+#### Renders an Angular component or template in a different part of the DOM.
+
+## Features
+
+- ✅ Render any Angular component or template outside of your App's main structure.
+- ✅ Appends to a custom container element, which can be configured as needed.
+
+## Installation
+
+To use the [Angular CDK Portal](https://material.angular.io/cdk/portal/overview), first install the CDK package:
+
+```bash
+npm install @angular/cdk
+```
+
+## Basic Usage
+
+### Defining a Portal
+
+First, create the component or template that you want to render in a different location:
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'component-portal-content',
+  standalone: true,
+  template: `
+    <p>This is portal content!</p>
+  `
+})
+export class PortalContentComponent {}
+```
+
+### Using the Portal
+
+In your main component, set up the portal and the outlet:
+
+```typescript
+// app.component.ts
+import { Component, ViewChild, AfterViewInit, inject, ApplicationRef, Injector, ViewContainerRef } from '@angular/core';
+import { CdkPortal, DomPortalOutlet } from '@angular/cdk/portal';
+import { PortalContentComponent } from './portal-content.component';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  template: `
+    <ng-template cdkPortal>
+      <app-portal-content></app-portal-content>
+    </ng-template>
+    <div #portalOutlet></div>
+  `
+})
+export class AppComponent implements AfterViewInit {
+  private readonly appRef = inject(ApplicationRef);
+  private readonly injector = inject(Injector);
+
+  @ViewChild(CdkPortal) portal: CdkPortal;
+  @ViewChild('portalOutlet', { read: ViewContainerRef }) portalOutlet: ViewContainerRef;
+
+  private host: DomPortalOutlet;
+
+  ngAfterViewInit() {
+    this.host = new DomPortalOutlet(this.portalOutlet.element.nativeElement, this.injector, this.appRef);
+    this.host.attach(this.portal);
+  }
+}
+```
+
+## Anatomy
+
+The Angular CDK Portal utility consists of a few key elements:
+
+1. **Portal**:
+   An Angular directive (`CdkPortal`) that defines the content to be rendered elsewhere.
+
+2. **Portal Outlet**:
+   An Angular directive (`CdkPortalOutlet`) or a host (`DomPortalOutlet`) where the portal content will be rendered.

package/presence/__test__/presence-test.component.ts

@@ -0,0 +1,51 @@
+import { Component, ElementRef, NgZone, OnInit } from '@angular/core';
+import { usePresence } from '../src/presence';
+import { CollapseContext, transitionCollapsing } from '../src/transitions/transition.collapse';
+
+@Component({
+    selector: 'app-presence',
+    template: `
+        <div #element>Presence Component</div>
+    `,
+    styles: [
+        `
+            .collapse {
+                transition: height 0.5s ease-in-out;
+            }
+            .collapsing {
+                height: 0px;
+            }
+            .show {
+                height: auto;
+            }
+        `
+
+    ]
+})
+export class PresenceComponent implements OnInit {
+    private context: CollapseContext = {
+        direction: 'show',
+        dimension: 'height'
+    };
+    private element!: HTMLElement;
+
+    constructor(
+        private zone: NgZone,
+        private elRef: ElementRef
+    ) {}
+
+    ngOnInit(): void {
+        this.element = this.elRef.nativeElement.querySelector('div');
+        const options = {
+            context: this.context,
+            animation: true,
+            state: 'stop' as const
+        };
+
+        usePresence(this.zone, this.element, transitionCollapsing, options).subscribe();
+    }
+
+    getContext(): CollapseContext {
+        return this.context;
+    }
+}

package/presence/__test__/presence.spec.ts

@@ -0,0 +1,50 @@
+import { NgZone } from '@angular/core';
+import { ComponentFixture, fakeAsync, TestBed, tick } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import { PresenceComponent } from './presence-test.component';
+
+describe('presence', () => {
+    let component: PresenceComponent;
+    let fixture: ComponentFixture<PresenceComponent>;
+    let zone: NgZone;
+
+    beforeEach(async () => {
+        await TestBed.configureTestingModule({
+            declarations: [PresenceComponent],
+            providers: [{ provide: NgZone, useValue: new NgZone({ enableLongStackTrace: false }) }]
+        }).compileComponents();
+
+        fixture = TestBed.createComponent(PresenceComponent);
+        component = fixture.componentInstance;
+        zone = TestBed.inject(NgZone);
+
+        fixture.detectChanges(); // triggers ngOnInit
+    });
+
+    it('should create', () => {
+        expect(component).toBeTruthy();
+    });
+
+    it('should initialize element and context correctly', () => {
+        const element = fixture.debugElement.query(By.css('div')).nativeElement;
+
+        const context = component.getContext();
+
+        expect(component['element']).toBe(element);
+        expect(context).toEqual({ direction: 'show', dimension: 'height', maxSize: '0px' });
+    });
+
+    it('should complete animation correctly', fakeAsync(() => {
+        const element = fixture.debugElement.query(By.css('div')).nativeElement;
+
+        zone.runOutsideAngular(() => {
+            element.dispatchEvent(new Event('transitionend'));
+        });
+
+        tick(600);
+        fixture.detectChanges();
+
+        expect(element.classList.contains('collapsing')).toBe(false);
+        expect(element.classList.contains('show')).toBe(true);
+    }));
+});

package/presence/index.ts

@@ -0,0 +1,4 @@
+export * from './src/presence';
+export * from './src/transitions/transition.collapse';
+export * from './src/transitions/transition.toast';
+export * from './src/types';

package/presence/src/presence.ts

@@ -0,0 +1,119 @@
+import { NgZone } from '@angular/core';
+import { EMPTY, endWith, filter, fromEvent, Observable, of, race, Subject, takeUntil, timer } from 'rxjs';
+import { TransitionContext, TransitionEndFn, TransitionOptions, TransitionStartFn } from './types';
+import { getTransitionDurationMs, runInZone } from './utils';
+
+const noopFn: TransitionEndFn = () => {
+    /* Noop */
+};
+const TransitionsMap = new Map<HTMLElement, TransitionContext<any>>();
+
+/**
+ * Manages the presence of an element with optional transition animation.
+ *
+ * @template T - The type of the context object used in the transition.
+ * @param {NgZone} zone - The Angular zone to control the change detection context.
+ * @param {HTMLElement} element - The target HTML element to apply the transition.
+ * @param {TransitionOptions<T>} options - Options for controlling the transition behavior.
+ *   @param {T} [options.context] - An optional context object to pass through the transition.
+ *   @param {boolean} options.animation - A flag indicating if the transition should be animated.
+ *   @param {'start' | 'continue' | 'stop'} options.state - The desired state of the transition.
+ * @param {TransitionStartFn<T>} startFn - A function to start the transition.
+ * @returns {Observable<void>} - An observable that emits when the transition completes.
+ *
+ * The `usePresence` function is designed to manage the presence and visibility of an HTML element,
+ * optionally applying a transition animation. It utilizes Angular's NgZone for efficient change
+ * detection management and allows for different states of transitions ('start', 'continue', 'stop').
+ * The function takes a start function to handle the beginning of the transition and returns an
+ * observable that completes when the transition ends.
+ *
+ * Example usage:
+ *
+ * const options: TransitionOptions<MyContext> = {
+ *   context: {}, // your context object
+ *   animation: true,
+ *   state: 'start'
+ * };
+ *
+ * const startFn: TransitionStartFn<MyContext> = (el, animation, context) => {
+ *   el.classList.add('active');
+ *   return () => el.classList.remove('active');
+ * };
+ *
+ * usePresence(zone, element, startFn, options).subscribe(() => {
+ *   console.log('Transition completed');
+ * });
+ */
+const usePresence = <T>(
+    zone: NgZone,
+    element: HTMLElement,
+    startFn: TransitionStartFn<T>,
+    options: TransitionOptions<T>
+): Observable<void> => {
+    let context = options.context || <T>{};
+
+    const transitionTimerDelayMs = options.transitionTimerDelayMs ?? 5;
+    const state = options.state ?? 'stop';
+
+    const running = TransitionsMap.get(element);
+
+    if (running) {
+        switch (state) {
+            case 'continue':
+                return EMPTY;
+            case 'stop':
+                zone.run(() => running.transition$.complete());
+                context = { ...running.context, ...context };
+                TransitionsMap.delete(element);
+                break;
+        }
+    }
+    const endFn = startFn(element, options.animation, context) || noopFn;
+
+    if (!options.animation || window.getComputedStyle(element).transitionProperty === 'none') {
+        zone.run(() => endFn());
+        return of(undefined).pipe(runInZone(zone));
+    }
+
+    const transition$ = new Subject<void>();
+    const finishTransition$ = new Subject<void>();
+    const stop$ = transition$.pipe(endWith(true));
+
+    TransitionsMap.set(element, {
+        transition$,
+        complete: () => {
+            finishTransition$.next();
+            finishTransition$.complete();
+        },
+        context
+    });
+
+    const transitionDurationMs = getTransitionDurationMs(element);
+
+    zone.runOutsideAngular(() => {
+        const transitionEnd$ = fromEvent<TransitionEvent>(element, 'transitionend').pipe(
+            filter(({ target }) => target === element),
+            takeUntil(stop$)
+        );
+        const timer$ = timer(transitionDurationMs + transitionTimerDelayMs).pipe(takeUntil(stop$));
+
+        race(timer$, transitionEnd$, finishTransition$)
+            .pipe(takeUntil(stop$))
+            .subscribe(() => {
+                TransitionsMap.delete(element);
+                zone.run(() => {
+                    endFn();
+                    transition$.next();
+                    transition$.complete();
+                });
+            });
+    });
+
+    return transition$.asObservable();
+};
+
+const completeTransition = (element: HTMLElement) => {
+    TransitionsMap.get(element)?.complete();
+};
+
+export { completeTransition, usePresence };

package/presence/src/transitions/transition.collapse.ts

@@ -0,0 +1,99 @@
+import { TransitionStartFn } from '../types';
+import { triggerReflow } from '../utils';
+
+export type CollapseContext = {
+    direction: 'show' | 'hide';
+    dimension: 'width' | 'height';
+    maxSize?: string;
+};
+
+// Define constants for class names
+const COLLAPSE_CLASS = 'collapse';
+const COLLAPSING_CLASS = 'collapsing';
+const SHOW_CLASS = 'show';
+/**
+ * Function to handle the start of a collapsing transition.
+ *
+ * @param element - The HTML element to animate.
+ * @param animation - Whether to use animation or not.
+ * @param context - The context containing direction and dimension information.
+ * @returns A function to clean up the animation.
+ */
+export const transitionCollapsing: TransitionStartFn<CollapseContext> = (
+    element: HTMLElement,
+    animation: boolean,
+    context: CollapseContext
+) => {
+    const { direction, dimension } = context;
+    let { maxSize } = context;
+    const { classList } = element;
+
+    /**
+     * Sets initial classes based on the direction.
+     */
+    function setInitialClasses() {
+        classList.add(COLLAPSE_CLASS);
+        if (direction === 'show') {
+            classList.add(SHOW_CLASS);
+        } else {
+            classList.remove(SHOW_CLASS);
+        }
+    }
+
+    if (!animation) {
+        setInitialClasses();
+        return;
+    }
+
+    if (!maxSize) {
+        maxSize = measureCollapsingElementDimensionPx(element, dimension);
+        context.maxSize = maxSize;
+
+        // Fix the height before starting the animation
+        element.style[dimension] = direction !== 'show' ? maxSize : '0px';
+
+        classList.remove(COLLAPSE_CLASS, COLLAPSING_CLASS, 'show');
+
+        triggerReflow(element);
+
+        // Start the animation
+        classList.add(COLLAPSING_CLASS);
+    }
+
+    element.style[dimension] = direction === 'show' ? maxSize : '0px';
+
+    return () => {
+        setInitialClasses();
+        classList.remove(COLLAPSING_CLASS);
+        element.style[dimension] = '';
+    };
+};
+
+/**
+ * Measures the dimension of the collapsing element in pixels.
+ *
+ * @param element - The HTML element to measure.
+ * @param dimension - The dimension ('width' or 'height') to measure.
+ * @returns The size of the dimension in pixels.
+ */
+function measureCollapsingElementDimensionPx(element: HTMLElement, dimension: 'width' | 'height'): string {
+    // SSR fix
+    if (typeof navigator === 'undefined') {
+        return '0px';
+    }
+
+    const { classList } = element;
+    const hasShownClass = classList.contains(SHOW_CLASS);
+    if (!hasShownClass) {
+        classList.add(SHOW_CLASS);
+    }
+
+    element.style[dimension] = '';
+    const dimensionSize = element.getBoundingClientRect()[dimension] + 'px';
+
+    if (!hasShownClass) {
+        classList.remove(SHOW_CLASS);
+    }
+
+    return dimensionSize;
+}

package/presence/src/transitions/transition.toast.ts

@@ -0,0 +1,27 @@
+import { TransitionStartFn } from '../types';
+import { triggerReflow } from '../utils';
+
+export const toastFadeInTransition: TransitionStartFn = (element: HTMLElement, animation: boolean) => {
+    const { classList } = element;
+
+    if (animation) {
+        classList.add('fade');
+    } else {
+        classList.add('show');
+        return;
+    }
+
+    triggerReflow(element);
+    classList.add('show', 'showing');
+
+    return () => {
+        classList.remove('showing');
+    };
+};
+
+export const toastFadeOutTransition: TransitionStartFn = ({ classList }: HTMLElement) => {
+    classList.add('showing');
+    return () => {
+        classList.remove('show', 'showing');
+    };
+};

package/presence/src/types.ts

@@ -0,0 +1,20 @@
+import { Subject } from 'rxjs';
+
+type TransitionOptions<T> = {
+    context?: T;
+    animation: boolean;
+    state?: 'continue' | 'stop';
+    transitionTimerDelayMs?: number;
+};
+
+type TransitionContext<T> = {
+    transition$: Subject<any>;
+    complete: () => void;
+    context: T;
+};
+
+type TransitionStartFn<T = any> = (element: HTMLElement, animation: boolean, context: T) => TransitionEndFn | void;
+
+type TransitionEndFn = () => void;
+
+export { TransitionContext, TransitionEndFn, TransitionOptions, TransitionStartFn };

package/presence/src/utils.ts

@@ -0,0 +1,63 @@
+import { NgZone } from '@angular/core';
+import { Observable } from 'rxjs';
+
+/**
+ * Ensures that the observable stream runs inside Angular's NgZone.
+ *
+ * This function is a higher-order function that takes an observable stream as input and ensures
+ * that all emissions, errors, and completion notifications are run inside Angular's NgZone. This
+ * is particularly useful for ensuring that change detection is triggered properly in Angular
+ * applications.
+ *
+ * @template T - The type of the items emitted by the observable.
+ * @param {NgZone} zone - The Angular zone to control the change detection context.
+ * @returns {(source: Observable<T>) => Observable<T>} - A function that takes an observable as input
+ * and returns an observable that runs inside Angular's NgZone.
+ *
+ * Example usage:
+ *
+ * const source$ = of('some value');
+ * const zoned$ = source$.pipe(runInZone(zone));
+ * zoned$.subscribe(value => {
+ *   console.log('Value:', value);
+ * });
+ */
+function runInZone<T>(zone: NgZone): (source: Observable<T>) => Observable<T> {
+    return (source: Observable<T>) =>
+        new Observable((observer) =>
+            source.subscribe({
+                next: (value) => zone.run(() => observer.next(value)),
+                error: (err) => zone.run(() => observer.error(err)),
+                complete: () => zone.run(() => observer.complete())
+            })
+        );
+}
+
+/**
+ * Calculates the total transition duration in milliseconds for a given HTML element.
+ *
+ * This function retrieves the computed style of the specified element and extracts the
+ * transition duration and delay properties. It then converts these values from seconds
+ * to milliseconds and returns their sum, representing the total transition duration.
+ *
+ * @param {HTMLElement} element - The HTML element for which to calculate the transition duration.
+ * @returns {number} - The total transition duration in milliseconds.
+ *
+ * Example usage:
+ *
+ * const durationMs = getTransitionDurationMs(element);
+ * console.log(`Transition duration: ${durationMs} ms`);
+ */
+function getTransitionDurationMs(element: HTMLElement): number {
+    const { transitionDelay, transitionDuration } = window.getComputedStyle(element);
+    const transitionDelaySec = parseFloat(transitionDelay);
+    const transitionDurationSec = parseFloat(transitionDuration);
+
+    return (transitionDelaySec + transitionDurationSec) * 1000;
+}
+
+export { getTransitionDurationMs, runInZone };
+
+export function triggerReflow(element: HTMLElement) {
+    return (element || document.body).getBoundingClientRect();
+}

package/presence/stories/presence-story.componen.ts

@@ -0,0 +1,69 @@
+import { Component, ElementRef, inject, NgZone, OnInit } from '@angular/core';
+import { usePresence } from '../src/presence';
+import { CollapseContext, transitionCollapsing } from '../src/transitions/transition.collapse';
+
+@Component({
+    selector: 'app-presence',
+    standalone: true,
+    template: `
+        <div>
+            <button (click)="toggle()">Toggle</button>
+            <div class="collapse-content" #collapseContent>Content to be collapsed</div>
+        </div>
+    `,
+    styles: [
+        `
+            .collapse-content {
+                overflow: hidden;
+                transition: height 0.5s ease-in-out;
+            }
+            .collapse:not(.show) {
+                display: none;
+            }
+            .show {
+                height: auto;
+            }
+        `
+
+    ]
+})
+export class PresenceStoryComponent implements OnInit {
+    private elRef = inject(ElementRef);
+    private zone = inject(NgZone);
+
+    private element!: HTMLElement;
+
+    private _isCollapsed = false;
+    private afterInit = false;
+
+    set collapsed(isCollapsed: boolean) {
+        if (this._isCollapsed !== isCollapsed) {
+            this._isCollapsed = isCollapsed;
+            if (this.afterInit) {
+                this.initCollapse(this._isCollapsed, true);
+            }
+        }
+    }
+
+    ngOnInit(): void {
+        this.element = this.elRef.nativeElement.querySelector('.collapse-content');
+        this.initCollapse(this._isCollapsed, false);
+        this.afterInit = true;
+    }
+
+    toggle(open: boolean = this._isCollapsed) {
+        this.collapsed = !open;
+    }
+
+    private initCollapse(collapsed: boolean, animation: boolean): void {
+        const options = {
+            context: {
+                direction: collapsed ? 'hide' : 'show',
+                dimension: 'height'
+            } as CollapseContext,
+            animation
+        };
+
+        usePresence(this.zone, this.element, transitionCollapsing, options).subscribe();
+    }
+}

package/presence/stories/presence.docs.mdx

@@ -0,0 +1,40 @@
+import { ArgTypes, Canvas, Markdown, Meta } from '@storybook/blocks';
+
+<Meta title="Primitives/Presence" />
+
+# Presence
+
+The `usePresence` function is a utility designed to manage transitions and animations
+for DOM elements in an Angular application.
+It provides a consistent way to handle animations, ensuring that they run correctly within Angular's zone.
+
+By using `usePresence`, developers can manage transitions and animations in a consistent and performant manner, ensuring that their Angular applications remain responsive and efficient.
+
+## Function Signature
+
+```typescript
+export const usePresence = <T>(
+  zone: NgZone,
+  element: HTMLElement,
+  startFn: TransitionStartFn<T>,
+  options: TransitionOptions<T>
+): Observable<void> => { ... }
+
+```
+
+### Parameters
+
+- `zone` (NgZone): Angular's NgZone service, which is used to manage change detection and ensure that transitions and animations are run outside of Angular's zone, avoiding unnecessary change detection cycles.
+- `element` (HTMLElement): The DOM element that the transition will be applied to.
+- startFn (`TransitionStartFn<T>`): A function that initiates the transition. It takes the element, the animation flag, and the context as parameters, and returns a cleanup function (TransitionEndFn) to be called when the transition ends.
+- options (`TransitionOptions<T>`): An object containing options for the transition.
+  - context (T): A context object that provides additional information needed for the transition.
+  - animation (boolean): A boolean indicating whether the transition should include animation.
+  - state ('stop' | 'continue'): Specifies whether to stop any running transition ('stop') or continue with the current one ('continue'). The default value is 'stop'.
+  - transitionTimerDelayMs (number, optional): An optional delay (in milliseconds) to be added to the transition timer. Default value is 5.
+
+## Notes
+
+- Transition Context: The context object can hold any additional data required for the transition. It allows for flexible and reusable transition logic.
+- Zone Management: Running transition logic outside Angular's zone prevents unnecessary change detection cycles, improving performance.
+- Customizable Delay: The optional transitionTimerDelayMs allows for fine-tuning the transition timing.

package/presence/stories/presence.stories.ts

@@ -0,0 +1,29 @@
+import { componentWrapperDecorator, Meta, moduleMetadata, StoryObj } from '@storybook/angular';
+import { PresenceStoryComponent } from './presence-story.componen';
+
+export default {
+    title: 'Primitives/Presence',
+    decorators: [
+        moduleMetadata({
+            imports: [PresenceStoryComponent]
+        }),
+        componentWrapperDecorator(
+            (story) =>
+                `<div class="radix-themes light light-theme"
+                      data-radius="medium"
+                      data-scaling="100%">${story}</div>`
+        )
+    ]
+} as Meta;
+
+type Story = StoryObj;
+
+export const Default: Story = {
+    render: (args) => ({
+        props: args,
+        template: `
+<app-presence></app-presence>
+
+`
+    })
+};