@shimmer-from-structure/angular 2.2.0

package/ng-package.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "./dist",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  },
+  "allowedNonPeerDependencies": ["@shimmer-from-structure/core"]
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@shimmer-from-structure/angular",
+  "version": "2.2.0",
+  "description": "Angular adapter for shimmer-from-structure",
+  "peerDependencies": {
+    "@angular/core": "^19.0.0",
+    "@angular/common": "^19.0.0"
+  },
+  "dependencies": {
+    "@shimmer-from-structure/core": "*"
+  },
+  "devDependencies": {
+    "@angular/compiler": "^19.0.0",
+    "@angular/compiler-cli": "^19.0.0",
+    "@angular/core": "^19.0.0",
+    "@angular/common": "^19.0.0",
+    "@angular/platform-browser": "^19.0.0",
+    "@angular/platform-browser-dynamic": "^19.0.0",
+    "ng-packagr": "^19.0.0",
+    "typescript": "~5.6.0",
+    "vitest": "^4.0.17",
+    "jsdom": "^27.4.0",
+    "@testing-library/dom": "^10.4.1",
+    "zone.js": "~0.15.0",
+    "rxjs": "~7.8.0"
+  },
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "test": "vitest run",
+    "format": "prettier --write .",
+    "prepublishOnly": "cp ../../README.md ."
+  },
+  "keywords": [
+    "angular",
+    "shimmer",
+    "skeleton",
+    "loading"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/darula-hpp/shimmer-from-structure.git",
+    "directory": "packages/angular"
+  },
+  "author": "Olebogeng Mbedzi",
+  "license": "MIT"
+}

package/src/public-api.ts

@@ -0,0 +1,14 @@
+// Public API Surface
+export { ShimmerComponent } from './shimmer.component';
+export {
+    SHIMMER_CONFIG,
+    provideShimmerConfig,
+    injectShimmerConfig,
+    shimmerDefaults,
+} from './shimmer-config.service';
+export type {
+    ShimmerInputs,
+    ShimmerConfig,
+    ShimmerContextValue,
+    ElementInfo,
+} from './types';

package/src/shimmer-config.service.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from 'vitest';
+import { TestBed } from '@angular/core/testing';
+import {
+    provideShimmerConfig,
+    injectShimmerConfig,
+    shimmerDefaults,
+    SHIMMER_CONFIG,
+} from './shimmer-config.service';
+
+describe('shimmer-config.service', () => {
+    describe('shimmerDefaults', () => {
+        it('exports default values', () => {
+            expect(shimmerDefaults).toBeDefined();
+            expect(shimmerDefaults.shimmerColor).toBeDefined();
+            expect(shimmerDefaults.backgroundColor).toBeDefined();
+            expect(shimmerDefaults.duration).toBeDefined();
+            expect(shimmerDefaults.fallbackBorderRadius).toBeDefined();
+        });
+    });
+
+    describe('provideShimmerConfig', () => {
+        it('creates a provider object', () => {
+            const config = { shimmerColor: '#fff', duration: 2 };
+            const provider = provideShimmerConfig(config);
+
+            expect(provider.provide).toBe(SHIMMER_CONFIG);
+            expect(provider.useValue).toBe(config);
+        });
+    });
+
+    describe('injectShimmerConfig', () => {
+        it('returns defaults when no provider is configured', () => {
+            TestBed.configureTestingModule({});
+
+            TestBed.runInInjectionContext(() => {
+                const config = injectShimmerConfig();
+
+                expect(config.shimmerColor).toBe(shimmerDefaults.shimmerColor);
+                expect(config.backgroundColor).toBe(shimmerDefaults.backgroundColor);
+                expect(config.duration).toBe(shimmerDefaults.duration);
+                expect(config.fallbackBorderRadius).toBe(shimmerDefaults.fallbackBorderRadius);
+            });
+        });
+
+        it('merges provided config with defaults', () => {
+            TestBed.configureTestingModule({
+                providers: [
+                    provideShimmerConfig({
+                        shimmerColor: 'rgba(255, 255, 255, 0.8)',
+                        duration: 3,
+                    }),
+                ],
+            });
+
+            TestBed.runInInjectionContext(() => {
+                const config = injectShimmerConfig();
+
+                expect(config.shimmerColor).toBe('rgba(255, 255, 255, 0.8)');
+                expect(config.duration).toBe(3);
+                // Should use defaults for non-provided values
+                expect(config.backgroundColor).toBe(shimmerDefaults.backgroundColor);
+                expect(config.fallbackBorderRadius).toBe(shimmerDefaults.fallbackBorderRadius);
+            });
+        });
+
+        it('returns fully resolved ShimmerContextValue', () => {
+            TestBed.configureTestingModule({
+                providers: [
+                    provideShimmerConfig({
+                        shimmerColor: '#aaa',
+                        backgroundColor: '#bbb',
+                        duration: 1.5,
+                        fallbackBorderRadius: 10,
+                    }),
+                ],
+            });
+
+            TestBed.runInInjectionContext(() => {
+                const config = injectShimmerConfig();
+
+                expect(config.shimmerColor).toBe('#aaa');
+                expect(config.backgroundColor).toBe('#bbb');
+                expect(config.duration).toBe(1.5);
+                expect(config.fallbackBorderRadius).toBe(10);
+            });
+        });
+    });
+});

package/src/shimmer-config.service.ts

@@ -0,0 +1,48 @@
+import { InjectionToken, inject } from '@angular/core';
+import type { ShimmerConfig, ShimmerContextValue } from '@shimmer-from-structure/core';
+import { shimmerDefaults } from '@shimmer-from-structure/core';
+
+/**
+ * Injection token for global shimmer configuration.
+ * Use `provideShimmerConfig()` to configure in your app.
+ */
+export const SHIMMER_CONFIG = new InjectionToken<ShimmerConfig>('SHIMMER_CONFIG');
+
+/**
+ * Provider function for shimmer configuration.
+ * Use in your app's providers array.
+ *
+ * @example
+ * ```typescript
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideShimmerConfig({
+ *       shimmerColor: 'rgba(255, 255, 255, 0.3)',
+ *       duration: 1.5
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export function provideShimmerConfig(config: ShimmerConfig) {
+    return { provide: SHIMMER_CONFIG, useValue: config };
+}
+
+/**
+ * Inject and resolve shimmer configuration.
+ * Merges injected config with defaults.
+ * Returns fully resolved ShimmerContextValue with all properties defined.
+ */
+export function injectShimmerConfig(): ShimmerContextValue {
+    const config = inject(SHIMMER_CONFIG, { optional: true }) ?? {};
+
+    return {
+        shimmerColor: config.shimmerColor ?? shimmerDefaults.shimmerColor,
+        backgroundColor: config.backgroundColor ?? shimmerDefaults.backgroundColor,
+        duration: config.duration ?? shimmerDefaults.duration,
+        fallbackBorderRadius: config.fallbackBorderRadius ?? shimmerDefaults.fallbackBorderRadius,
+    };
+}
+
+// Re-export defaults for testing and reference
+export { shimmerDefaults };

package/src/shimmer.component.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { Component } from '@angular/core';
+import { TestBed, ComponentFixture, fakeAsync, tick } from '@angular/core/testing';
+import { ShimmerComponent } from './shimmer.component';
+import { provideShimmerConfig, SHIMMER_CONFIG } from './shimmer-config.service';
+
+// Test wrapper component for content projection
+@Component({
+    selector: 'test-host',
+    standalone: true,
+    imports: [ShimmerComponent],
+    template: `
+    <shimmer [loading]="loading">
+      <div class="test-content" style="width: 100px; height: 50px;">Content</div>
+    </shimmer>
+  `,
+})
+class TestHostComponent {
+    loading = true;
+}
+
+describe('ShimmerComponent', () => {
+    let fixture: ComponentFixture<TestHostComponent>;
+    let hostComponent: TestHostComponent;
+
+    beforeEach(async () => {
+        vi.useFakeTimers();
+
+        await TestBed.configureTestingModule({
+            imports: [TestHostComponent, ShimmerComponent],
+        }).compileComponents();
+
+        fixture = TestBed.createComponent(TestHostComponent);
+        hostComponent = fixture.componentInstance;
+    });
+
+    it('renders children normally when loading=false', fakeAsync(() => {
+        hostComponent.loading = false;
+        fixture.detectChanges();
+        tick();
+
+        const content = fixture.nativeElement.querySelector('.test-content');
+        expect(content).toBeTruthy();
+        expect(content.textContent).toBe('Content');
+
+        // Should not have the measure container when not loading
+        const measureContainer = fixture.nativeElement.querySelector('.shimmer-measure-container');
+        expect(measureContainer).toBeFalsy();
+    }));
+
+    it('renders shimmer structure when loading=true', fakeAsync(() => {
+        hostComponent.loading = true;
+        fixture.detectChanges();
+        tick();
+
+        // Should render the measure container
+        const measureContainer = fixture.nativeElement.querySelector('.shimmer-measure-container');
+        expect(measureContainer).toBeTruthy();
+    }));
+
+    it('applies transparent text style to measure container', fakeAsync(() => {
+        hostComponent.loading = true;
+        fixture.detectChanges();
+        tick();
+
+        // Check that the measure container has the class
+        const measureContainer = fixture.nativeElement.querySelector('.shimmer-measure-container');
+        expect(measureContainer).toBeTruthy();
+        expect(measureContainer.classList.contains('shimmer-measure-container')).toBe(true);
+    }));
+});
+
+describe('ShimmerComponent with config provider', () => {
+    let fixture: ComponentFixture<TestHostComponent>;
+
+    beforeEach(async () => {
+        vi.useFakeTimers();
+
+        await TestBed.configureTestingModule({
+            imports: [TestHostComponent, ShimmerComponent],
+            providers: [
+                provideShimmerConfig({
+                    shimmerColor: 'rgba(255, 0, 0, 0.5)',
+                    backgroundColor: '#ff0000',
+                    duration: 2,
+                    fallbackBorderRadius: 8,
+                }),
+            ],
+        }).compileComponents();
+
+        fixture = TestBed.createComponent(TestHostComponent);
+    });
+
+    it('uses provided config values', fakeAsync(() => {
+        fixture.componentInstance.loading = true;
+        fixture.detectChanges();
+        tick();
+
+        // The config should be injected - we can verify by checking the SHIMMER_CONFIG token
+        const config = TestBed.inject(SHIMMER_CONFIG);
+        expect(config.shimmerColor).toBe('rgba(255, 0, 0, 0.5)');
+        expect(config.backgroundColor).toBe('#ff0000');
+        expect(config.duration).toBe(2);
+        expect(config.fallbackBorderRadius).toBe(8);
+    }));
+});
+
+describe('ShimmerComponent input overrides', () => {
+    @Component({
+        selector: 'test-override-host',
+        standalone: true,
+        imports: [ShimmerComponent],
+        template: `
+      <shimmer
+        [loading]="true"
+        [shimmerColor]="'#00ff00'"
+        [backgroundColor]="'#0000ff'"
+        [duration]="3"
+        [fallbackBorderRadius]="12"
+      >
+        <div>Content</div>
+      </shimmer>
+    `,
+    })
+    class TestOverrideHostComponent { }
+
+    beforeEach(async () => {
+        vi.useFakeTimers();
+
+        await TestBed.configureTestingModule({
+            imports: [TestOverrideHostComponent, ShimmerComponent],
+            providers: [
+                provideShimmerConfig({
+                    shimmerColor: 'rgba(255, 0, 0, 0.5)',
+                    duration: 1,
+                }),
+            ],
+        }).compileComponents();
+    });
+
+    it('component inputs override provider config', fakeAsync(() => {
+        const fixture = TestBed.createComponent(TestOverrideHostComponent);
+        fixture.detectChanges();
+        tick();
+
+        // The shimmer component should use input values over config
+        const shimmer = fixture.debugElement.children[0].componentInstance as ShimmerComponent;
+        expect(shimmer.resolvedShimmerColor()).toBe('#00ff00');
+        expect(shimmer.resolvedBackgroundColor()).toBe('#0000ff');
+        expect(shimmer.resolvedDuration()).toBe(3);
+        expect(shimmer.resolvedFallbackBorderRadius()).toBe(12);
+    }));
+});

package/src/shimmer.component.ts

@@ -0,0 +1,264 @@
+import {
+  Component,
+  input,
+  signal,
+  computed,
+  effect,
+  ElementRef,
+  viewChild,
+  AfterViewInit,
+  OnDestroy,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+} from '@angular/core';
+import { NgIf, NgFor } from '@angular/common';
+import {
+  extractElementInfo,
+  createResizeObserver,
+  type ElementInfo,
+} from '@shimmer-from-structure/core';
+import { injectShimmerConfig } from './shimmer-config.service';
+
+/**
+ * Shimmer component that creates loading skeleton overlays based on content structure.
+ * Automatically measures projected content and creates matching shimmer blocks.
+ *
+ * @example
+ * ```html
+ * <shimmer [loading]="isLoading">
+ *   <div class="card">
+ *     <h2>{{ title }}</h2>
+ *     <p>{{ description }}</p>
+ *   </div>
+ * </shimmer>
+ * ```
+ */
+@Component({
+  selector: 'shimmer',
+  standalone: true,
+  imports: [NgIf, NgFor],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  template: `
+    <div style="position: relative;">
+      <!-- Always render content -->
+      <div
+        #measureContainer
+        [class.shimmer-measure-container]="loading()"
+        [attr.aria-hidden]="loading() ? 'true' : null"
+        [style.pointer-events]="loading() ? 'none' : null"
+      >
+        <ng-content></ng-content>
+      </div>
+
+      <!-- Shimmer overlay - only when loading -->
+      @if (loading()) {
+        <div
+          style="
+            position: absolute;
+            top: 0;
+            left: 0;
+            right: 0;
+            bottom: 0;
+            overflow: hidden;
+            pointer-events: none;
+          "
+        >
+          @for (element of elements(); track $index) {
+            <div
+              [style.position]="'absolute'"
+              [style.left.px]="element.x"
+              [style.top.px]="element.y"
+              [style.width.px]="element.width"
+              [style.height.px]="element.height"
+              [style.backgroundColor]="resolvedBackgroundColor()"
+              [style.borderRadius]="
+                element.borderRadius === '0px'
+                  ? resolvedFallbackBorderRadius() + 'px'
+                  : element.borderRadius
+              "
+              [style.overflow]="'hidden'"
+            >
+              <div
+                class="shimmer-animation-element"
+                [style.background]="
+                  'linear-gradient(90deg, transparent, ' + resolvedShimmerColor() + ', transparent)'
+                "
+                [style.animationDuration]="resolvedDuration() + 's'"
+              ></div>
+            </div>
+          }
+        </div>
+      }
+    </div>
+  `,
+  styles: [
+    `
+      :host {
+        display: contents;
+      }
+
+      .shimmer-measure-container * {
+        color: transparent !important;
+      }
+
+      .shimmer-measure-container img,
+      .shimmer-measure-container svg,
+      .shimmer-measure-container video {
+        opacity: 0;
+      }
+
+      .shimmer-animation-element {
+        position: absolute;
+        top: 0;
+        left: 0;
+        width: 100%;
+        height: 100%;
+        animation: shimmer-animation 1.5s infinite;
+      }
+
+      @keyframes shimmer-animation {
+        0% {
+          transform: translateX(-100%);
+        }
+        100% {
+          transform: translateX(100%);
+        }
+      }
+    `,
+  ],
+})
+export class ShimmerComponent implements AfterViewInit, OnDestroy {
+  // Inputs using Angular signals
+  loading = input<boolean>(true);
+  shimmerColor = input<string | undefined>(undefined);
+  backgroundColor = input<string | undefined>(undefined);
+  duration = input<number | undefined>(undefined);
+  fallbackBorderRadius = input<number | undefined>(undefined);
+
+  // View child reference
+  measureContainer = viewChild<ElementRef<HTMLDivElement>>('measureContainer');
+
+  // Internal state
+  elements = signal<ElementInfo[]>([]);
+
+  // Inject global config
+  private contextConfig = injectShimmerConfig();
+
+  // Resolved values (props > context > defaults)
+  resolvedShimmerColor = computed(() => this.shimmerColor() ?? this.contextConfig.shimmerColor);
+  resolvedBackgroundColor = computed(
+    () => this.backgroundColor() ?? this.contextConfig.backgroundColor
+  );
+  resolvedDuration = computed(() => this.duration() ?? this.contextConfig.duration);
+  resolvedFallbackBorderRadius = computed(
+    () => this.fallbackBorderRadius() ?? this.contextConfig.fallbackBorderRadius
+  );
+
+  // Cleanup function for ResizeObserver
+  private resizeCleanup: (() => void) | undefined;
+  private mutationObserver: MutationObserver | undefined;
+
+  constructor() {
+    // Effect to re-measure when loading state changes
+    effect((onCleanup) => {
+      const isLoading = this.loading();
+      const container = this.measureContainer();
+
+      if (isLoading && container) {
+        // Clean up existing observers before setting up new ones
+        this.cleanup();
+
+        // Set up observers for this loading session
+        this.setupObservers();
+
+        // Defer measurement to next frame to ensure content is rendered
+        requestAnimationFrame(() => this.measureElements());
+      } else {
+        // Cleanup when not loading
+        this.cleanup();
+      }
+
+      // Cleanup on effect re-run or component destruction
+      onCleanup(() => {
+        this.cleanup();
+      });
+    });
+  }
+
+  ngAfterViewInit(): void {
+    // Effect will handle setup when container becomes available
+  }
+
+  ngOnDestroy(): void {
+    this.cleanup();
+  }
+
+  private setupObservers(): void {
+    const container = this.measureContainer()?.nativeElement;
+    if (!container) return;
+
+    // Set up ResizeObserver
+    this.resizeCleanup = createResizeObserver(container, () => this.measureElements());
+
+    // Set up MutationObserver for content changes
+    this.mutationObserver = new MutationObserver(() => {
+      if (this.loading()) {
+        this.measureElements();
+      }
+    });
+
+    this.mutationObserver.observe(container, {
+      childList: true,
+      subtree: true,
+      characterData: true,
+      attributes: false,
+    });
+  }
+
+  private measureElements(): void {
+    const container = this.measureContainer()?.nativeElement;
+    if (!container || !this.loading()) return;
+
+    // Temporarily disconnect mutation observer to avoid recursion
+    this.mutationObserver?.disconnect();
+
+    const containerRect = container.getBoundingClientRect();
+    const extractedElements: ElementInfo[] = [];
+
+    Array.from(container.children).forEach((child) => {
+      extractedElements.push(...extractElementInfo(child, containerRect));
+    });
+
+    this.elements.set(extractedElements);
+
+    // Reconnect mutation observer
+    if (this.mutationObserver && container) {
+      this.mutationObserver.observe(container, {
+        childList: true,
+        subtree: true,
+        characterData: true,
+        attributes: false,
+      });
+    }
+  }
+
+  private cleanup(): void {
+    if (this.resizeCleanup) {
+      this.resizeCleanup();
+      this.resizeCleanup = undefined;
+    }
+    if (this.mutationObserver) {
+      this.mutationObserver.disconnect();
+      this.mutationObserver = undefined;
+    }
+  }
+
+  /**
+   * Manually trigger re-measurement of elements.
+   * Useful when content changes programmatically.
+   */
+  remeasure(): void {
+    this.measureElements();
+  }
+}

package/src/test/setup.ts

@@ -0,0 +1,42 @@
+import 'zone.js';
+import { vi } from 'vitest';
+
+// Mock getBoundingClientRect since jsdom doesn't support layout
+Element.prototype.getBoundingClientRect = vi.fn(() => ({
+    width: 100,
+    height: 50,
+    top: 0,
+    left: 0,
+    bottom: 50,
+    right: 100,
+    x: 0,
+    y: 0,
+    toJSON: () => { },
+}));
+
+// Mock ResizeObserver
+global.ResizeObserver = class ResizeObserver {
+    observe() { }
+    unobserve() { }
+    disconnect() { }
+};
+
+// Mock getComputedStyle
+const originalGetComputedStyle = window.getComputedStyle;
+window.getComputedStyle = (elt) => {
+    const styles = originalGetComputedStyle(elt);
+    // Add borderRadius support for our tests
+    if (!styles.borderRadius) {
+        Object.defineProperty(styles, 'borderRadius', {
+            value: '4px',
+            writable: true,
+        });
+    }
+    return styles;
+};
+
+// Mock requestAnimationFrame
+global.requestAnimationFrame = (cb) => {
+    setTimeout(cb, 0);
+    return 0;
+};

package/src/types.ts

@@ -0,0 +1,35 @@
+
+/**
+ * Input properties for the Shimmer component
+ */
+export interface ShimmerInputs {
+    /**
+     * Whether the component is in loading state
+     * @default true
+     */
+    loading?: boolean;
+
+    /**
+     * Color of the shimmer effect gradient
+     */
+    shimmerColor?: string;
+
+    /**
+     * Background color of the shimmer blocks
+     */
+    backgroundColor?: string;
+
+    /**
+     * Duration of one shimmer animation cycle in seconds
+     */
+    duration?: number;
+
+    /**
+     * Fallback border radius (in pixels) when element has no border-radius
+     * @default 4
+     */
+    fallbackBorderRadius?: number;
+}
+
+// Re-export core types for convenience
+export type { ShimmerConfig, ShimmerContextValue, ElementInfo } from '@shimmer-from-structure/core';