@fourfold/angular-foundation

A comprehensive Angular foundation library providing architectural patterns, data services, authentication utilities, and unstyled UI components for rapid application development.

Installation

npm install @fourfold/angular-foundation

Quick Start

import {
  SsrPlatformService,
  FirestoreService,
  BaseHttpService,
  ThemeStoreService,
  authGuard
} from '@fourfold/angular-foundation';

Configuration

Logging Control

By default, the library only logs errors to keep production consoles clean. You can control logging verbosity globally or per-service:

import { FOUNDATION_LOGGING_CONFIG } from '@fourfold/angular-foundation';

// In your app.config.ts or main providers
export const appConfig: ApplicationConfig = {
  providers: [
    // Option 1: Completely silent (no logs at all)
    {
      provide: FOUNDATION_LOGGING_CONFIG,
      useValue: { level: 'silent' }
    },

    // Option 2: Development mode (show all debug info)
    {
      provide: FOUNDATION_LOGGING_CONFIG,
      useValue: { level: 'debug' }
    },

    // Option 3: Granular control per namespace
    {
      provide: FOUNDATION_LOGGING_CONFIG,
      useValue: {
        level: 'error',  // Default for all services
        namespaces: {
          'Firestore': 'debug',  // Show Firestore cache hits/misses
          'Cache': 'info',       // Show Cache operations
          'Http': 'silent'       // Silence HTTP logs completely
        }
      }
    }
  ]
};

Available log levels (from quietest to most verbose):

• 'silent' - No logs at all
• 'error' - Only errors (default)
• 'warn' - Errors and warnings
• 'info' - Errors, warnings, and informational messages
• 'debug' - All above + operation details (cache hits, API calls)
• 'verbose' - Maximum verbosity (network status, browser features)

Common namespaces: 'Firestore', 'Cache', 'Storage', 'Http', 'Auth', 'Theme'

Core Features

🏗️ Architectural Patterns

BaseStore & CollectionStore Abstract classes for reactive state management with built-in loading, error states, and auth awareness.

import { BaseStore, CollectionStore } from '@fourfold/angular-foundation';

@Injectable({ providedIn: 'root' })
export class UsersStore extends BaseStore<User> {
  protected async fetchData(): Promise<User[]> {
    return this.http.get<User[]>('/api/users');
  }
}

📡 Data Services

BaseHttpService Enhanced HTTP client with retry logic, error handling, and file upload support.

import { BaseHttpService } from '@fourfold/angular-foundation';

@Injectable({ providedIn: 'root' })
export class ApiService extends BaseHttpService {
  async getUsers(): Promise<User[]> {
    return this.get<User[]>('/api/users');
  }
  
  async uploadFile(file: File): Promise<UploadResponse> {
    return this.uploadFile<UploadResponse>('/api/upload', file);
  }
}

FirestoreService Streamlined Firestore operations with automatic caching and offline support.

import { FirestoreService } from '@fourfold/angular-foundation';

// Reactive collection data
users$ = this.firestore.collection$<User>('users');

// Query with conditions
const adults = await this.firestore.getDocsWhere('users', 
  where('age', '>=', 18)
);

ListFilterService Generic filtering, sorting, and pagination for data collections.

import { ListFilterService } from '@fourfold/angular-foundation';

const filteredUsers = this.listFilter.filterItems(users, {
  searchTerm: 'john',
  filters: { status: 'active' },
  sortConfig: { field: 'name', direction: 'asc' }
});

🔐 Authentication

Guards & Types Generic authentication utilities that work with any auth system.

import { authGuard, AuthUser, AuthService } from '@fourfold/angular-foundation';

// Route protection
const routes: Routes = [
  {
    path: 'admin',
    canActivate: [authGuard],
    loadComponent: () => import('./admin.component')
  }
];

// Implement your auth service
@Injectable({ providedIn: 'root' })
export class MyAuthService implements AuthService<MyUser> {
  isAuthenticated(): boolean | Observable<boolean> {
    return this.user !== null;
  }
  
  getCurrentUser(): MyUser | null {
    return this.user;
  }
}

🎨 Platform Services

SsrPlatformService SSR-safe platform detection and browser utilities.

import { SsrPlatformService } from '@fourfold/angular-foundation';

// Safe platform detection
if (this.platform.isBrowser) {
  // Browser-only code
}

// Reactive window dimensions
const width = this.platform.windowWidth();

ThemeStoreService Enhanced theme management with system preference detection and multiple theme support.

import { ThemeStoreService } from '@fourfold/angular-foundation';

// Current theme reactive state
const currentTheme = this.themeStore.currentTheme();
const isDark = this.themeStore.isDark();

// Toggle between light/dark
this.themeStore.toggleTheme();

// Set specific theme
this.themeStore.setTheme('dark-blue');

🧩 UI Components

Unstyled Component Library Accessible, headless components using CSS custom properties for theming.

import { 
  ButtonComponent,
  ChipComponent,
  LoadingStateComponent,
  ErrorStateComponent,
  TooltipComponent
} from '@fourfold/angular-foundation';

// Usage in templates
<ff-button variant="primary" size="lg" (clicked)="handleClick()">
  Click me
</ff-button>

<ff-chip 
  variant="success" 
  [closable]="true" 
  (closed)="handleRemove()"
>
  Success Tag
</ff-chip>

⚡ HTTP Infrastructure

Interceptors Complete HTTP infrastructure with functional interceptors.

import { 
  authInterceptor,
  loadingInterceptor,
  errorHandlingInterceptor,
  retryInterceptor
} from '@fourfold/angular-foundation';

// In your app config
export const appConfig: ApplicationConfig = {
  providers: [
    provideHttpClient(
      withInterceptors([
        authInterceptor,
        loadingInterceptor,
        errorHandlingInterceptor,
        retryInterceptor
      ])
    )
  ]
};

Advanced Usage

Custom Store Implementation

import { BaseStore } from '@fourfold/angular-foundation';

@Injectable({ providedIn: 'root' })
export class ProductsStore extends BaseStore<Product> {
  constructor(
    private http: HttpClient,
    @Inject(AUTH_STORE) authStore?: AuthStore
  ) {
    super(authStore);
  }

  protected async fetchData(): Promise<Product[]> {
    return this.http.get<Product[]>('/api/products').toPromise();
  }

  // Custom methods
  async addProduct(product: Partial<Product>): Promise<void> {
    const newProduct = await this.http.post<Product>('/api/products', product).toPromise();
    this._data.update(items => [...items, newProduct]);
  }
}

Theme Configuration

import { ThemeConfig, ThemeStoreService } from '@fourfold/angular-foundation';

const themeConfig: ThemeConfig = {
  defaultTheme: 'light',
  themes: {
    light: { isDark: false, name: 'Light Theme' },
    dark: { isDark: true, name: 'Dark Theme' },
    'dark-blue': { isDark: true, name: 'Dark Blue' }
  }
};

// Configure theme service
ThemeStoreService.configure(themeConfig);

Authentication Integration

// Define your user type
interface AppUser extends AuthUser {
  roles: string[];
  permissions: string[];
}

// Implement auth service
@Injectable({ providedIn: 'root' })
export class AppAuthService implements AuthService<AppUser> {
  private userSubject = new BehaviorSubject<AppUser | null>(null);
  
  isAuthenticated(): Observable<boolean> {
    return this.userSubject.pipe(map(user => !!user));
  }
  
  getCurrentUser(): AppUser | null {
    return this.userSubject.value;
  }
  
  hasRole(role: string): boolean {
    return this.getCurrentUser()?.roles.includes(role) ?? false;
  }
}

// Configure auth tokens
providers: [
  { provide: AUTH_SERVICE, useClass: AppAuthService },
  { provide: AUTH_CONFIG, useValue: { loginRoute: '/login' } }
]

Development

# Run tests
npm run lib:test

# Build library
npm run lib:build

# Release new version
npm run lib:release

# Publish to npm
npm run lib:publish

API Reference

Exports by Category

// Architectural Patterns
export { BaseStore, CollectionStore } from './lib/patterns';

// Data Services  
export { FirestoreService, FirebaseMetricsService } from './lib/services/firestore';
export { BaseHttpService } from './lib/services/http';
export { ListFilterService } from './lib/services/list-filter';

// Authentication
export { authGuard, roleGuard, AuthUser, AuthService } from './lib/services/auth';

// Platform Services
export { SsrPlatformService } from './lib/services/ssr-platform';
export { ThemeStoreService } from './lib/services/theme-store';

// UI Components
export { 
  ButtonComponent, 
  ChipComponent, 
  LoadingStateComponent,
  ErrorStateComponent,
  TooltipComponent 
} from './lib/components';

// HTTP Infrastructure
export { 
  authInterceptor,
  loadingInterceptor, 
  errorHandlingInterceptor,
  retryInterceptor
} from './lib/services/http/interceptors';

TypeScript Support

The library is built with strict TypeScript and provides comprehensive type definitions:

• Generic type parameters for stores and services
• Strict typing for auth interfaces
• Type-safe theme configurations
• Component prop types with Input/Output decorators

SSR Compatibility

All services are designed to work seamlessly with Angular Universal:

• Platform detection utilities
• Safe window/document access
• Hydration-safe state management
• Server-side rendering optimizations

Versioning

This package follows Semantic Versioning. Use conventional commits:

git commit -m "feat: add new service"     # Minor bump
git commit -m "fix: correct SSR issue"   # Patch bump  
git commit -m "feat!: breaking change"   # Major bump

Contributing

1. Make changes with conventional commits
2. Test thoroughly (npm run lib:test)
3. Follow the established patterns and conventions
4. Update documentation for new features

License

MIT