@fhss-web-team/frontend-utils 1.0.0 → 1.0.1

package/README.md

@@ -4,7 +4,7 @@
 
 This package is designed for use in Angular applications and includes integration with Keycloak for authentication.
 
-## 📆 Installation
+## Installation
 
 Install the package and its required peer dependencies:
 
@@ -12,8 +12,199 @@ Install the package and its required peer dependencies:
 npm install @fhss-web-team/frontend-utils
 ```
 
-## 🚀 Usage
-Refer to each directory’s `README.md` for specific exports and usage patterns:
-- [Components](./src/lib/components/README.md)
-- [Services](./src/lib/services/README.md)
-- [Signals](./src/lib/signals/README.md)
+# Documentation
+- [Components](#components)
+- [Services](#services)
+- [Signals](#signals)
+
+## Components
+
+This directory contains reusable Angular components designed to streamline development and maintain consistency across BYU websites. 
+
+### BYU Header
+This is the header displayed on all BYU websites. It displays the BYU logo, site title, breadcrumbs, and navigation menu.
+
+#### Features:
+- **Logo**: Displays the BYU logo.
+- **Title and Subtitle**: Configurable links for the site title and subtitle.
+- **Breadcrumbs**: Displays a breadcrumb trail for navigation.
+- **Navigation Menu**: Supports both simple links and dropdown menus.
+- **Authentication**: Integrates with the [auth service](#auth) to display user information and provide sign-in/sign-out functionality.
+
+#### Configuration:
+The header is configured using a `HeaderConfig` object. Below is the structure:
+
+```typescript
+type HeaderLink = {
+  text: string;
+  path: string;
+};
+
+type HeaderMenu = HeaderLink | {
+  text: string;
+  items: HeaderLink[];
+};
+
+export type HeaderConfig = {
+  title: HeaderLink;
+  subtitle?: HeaderLink;
+  breadcrumbs?: HeaderLink[];
+  menu?: HeaderMenu[];
+};
+```
+
+#### Usage:
+Pass the `HeaderConfig` object to the `byu-header` component:
+
+```html
+<byu-header [config]="headerConfig"></byu-header>
+```
+
+Example `HeaderConfig`:
+
+```typescript
+const headerConfig = {
+  title: { text: 'Home', path: '/' },
+  subtitle: { text: 'About Us', path: '/about' },
+  breadcrumbs: [
+    { text: 'Home', path: '/' },
+    { text: 'Section', path: '/section' }
+  ],
+  menu: [
+    { text: 'Services', path: '/services' },
+    {
+      text: 'More',
+      items: [
+        { text: 'Contact', path: '/contact' },
+        { text: 'Help', path: '/help' }
+      ]
+    }
+  ]
+};
+```
+
+---
+
+### BYU Footer
+This is the footer displayed on all BYU websites. It provides essential information and links to comply with legal and institutional requirements.
+
+#### Features:
+- **University Name**: Displays "Brigham Young University" with a link to the main BYU website.
+- **Address**: Displays the university's address.
+- **Copyright Notice**: Automatically updates the year to the current year.
+- **Privacy Links**: Includes links to the Privacy Notice and Cookie Preferences pages.
+
+#### Usage:
+Add the `byu-footer` component to your template:
+
+```html
+<byu-footer />
+```
+
+The footer does not require any configuration and is ready to use out of the box.
+
+---
+
+### User Management Table
+This component provides a table for managing user data, including search, filtering, sorting, and pagination functionalities. It will use the site's backend's `/api/user-management/` route.
+
+#### Features:
+- **Search**: Allows searching for users by their NetID or other attributes.
+- **Filtering**: Supports filtering by account types (e.g., NonBYU, Student, Employee).
+- **Sorting**: Columns can be sorted by attributes such as NetID, First Name, Last Name, Account Type, and Created Date.
+- **Pagination**: Includes a paginator to navigate through large datasets.
+- **Dynamic Data**: Fetches user data dynamically from the server.
+
+#### Configuration:
+The table uses the following signals for configuration:
+- `search`: A string for filtering users by search terms.
+- `accountTypes`: An array of account types to filter users.
+- `sortBy`: The column to sort by (e.g., `netId`, `preferredFirstName`).
+- `sortDirection`: The sorting direction (`asc` or `desc`).
+- `pageCount`: The number of rows per page.
+- `pageOffset`: The offset for pagination.
+- `createdAfter` and `createdBefore`: Filtering by creationg date
+
+#### Usage:
+Add the `app-user-management` component to your template:
+
+```html
+<app-user-management />
+```
+
+The component automatically handles data fetching and UI updates based on user interactions.
+
+
+
+## Services
+
+The services in this library provide reusable logic and utilities to simplify common tasks such as authentication, data fetching, and state management. They are designed to integrate seamlessly with Angular applications and follow best practices for dependency injection and reactive programming.
+
+### Auth
+Wraps the `keycloak-angular` service to provide a simplified interface for authentication and authorization. 
+
+#### Features:
+- **Login and Logout**: Methods to handle user login and logout.
+- **Authentication Signals**: Signals to track authentication status, tokens, and user information.
+- **Token Management**: Provides access to tokens (e.g., `token`, `idToken`, `refreshToken`) and their parsed forms.
+- **Role and Access Management**: Signals for realm and resource roles.
+- **Time Skew and Configuration**: Signals for Keycloak configuration properties like `timeSkew`, `responseMode`, and `flow`.
+
+
+
+
+## Signals
+
+### fetchSignal
+The `fetchSignal` helper provides a reactive way to perform HTTP requests in Angular applications. It supports various HTTP methods and automatically tracks dependencies for reactivity.
+
+#### Features:
+- **Reactive Requests**: Automatically updates when input signals change.
+- **Support for Multiple Methods**: Includes `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
+- **Response Parsing**: Supports JSON, text, Blob, and ArrayBuffer responses.
+- **Error Handling**: Tracks errors and status codes reactively.
+- **Auto-Refresh**: Automatically refreshes requests when dependencies change.
+
+#### Usage:
+```typescript
+import { fetchSignal } from '@fhss-web-team/frontend-utils';
+
+// Example: Reactive GET request
+const request = () => ({
+  url: '/api/data',
+  params: { filter: 'active' },
+});
+const dataSignal = fetchSignal.json(request, true);
+
+// Access reactive properties
+dataSignal.value(); // Current response value
+dataSignal.isLoading(); // Loading state
+dataSignal.error(); // Error details
+dataSignal.refresh(); // Manually refresh the request
+```
+
+---
+
+### debounced
+The `debounced` helper creates a debounced version of a signal, delaying updates until after a specified wait time.
+
+#### Features:
+- **Debounced Updates**: Reduces the frequency of updates to a signal.
+- **Customizable Delay**: Specify the debounce delay in milliseconds.
+
+#### Usage:
+```typescript
+import { signal } from '@angular/core';
+import { debounced } from '@fhss-web-team/frontend-utils';
+
+// Example: Debounced search input
+const searchInput = signal('');
+const debouncedSearch = debounced(searchInput, 300);
+
+// Update the input signal
+searchInput.set('new search term');
+
+// The debounced signal updates after 300ms
+debouncedSearch(); // 'new search term' (after delay)
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fhss-web-team/frontend-utils",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "peerDependencies": {
     "@angular/common": "^19.2.0",
     "@angular/core": "^19.2.0"