ng-adflowtail 0.1.0

package/README.md

@@ -0,0 +1,657 @@
+# ng-adflowtail 🚀
+
+A highly professional, developer-friendly, and lightweight Angular 22 component library built on top of **Tailwind CSS**, **Flowbite**, and modern **Angular Signals**.
+
+`ng-adflowtail` is architected with a **secondary entry points** design (similar to `@angular/material`). This enables absolute tree-shaking, meaning consumers only bundle the precise widgets and logic they import, leading to ultra-slim production bundles.
+
+---
+
+## Key Features
+
+- **Angular 22 Core**: Leverages the absolute latest APIs including Standalone Components, Signal-based Inputs/Outputs, Computeds, and Host Directives.
+- **Advanced State Management**: Built natively around Signals to ensure highly performant and predictable change detection.
+- **Signals-Based Forms**: Clean integration with modern Angular Signal Forms (`@angular/forms/signals`).
+- **Dynamic CSS Custom Properties (Theming)**: Easily brand components in real-time by passing a single hex/rgb color string. The built-in directive dynamically computes complementary brand shades using modern CSS `color-mix()`.
+- **Responsive & Accessible**: Fully styled with Tailwind CSS and Flowbite, implementing modern accessibility requirements and responsive layouts.
+- **Full Tree-Shaking**: Secondary entry points keep your production bundles optimal.
+
+---
+
+## Table of Contents
+
+1. [Prerequisites & Installation](#prerequisites--installation)
+2. [Tailwind CSS Configuration](#tailwind-css-configuration)
+3. [Architecture & Imports](#architecture--scaffolding)
+4. [Branding & Custom Theming](#branding--custom-theming)
+5. [Component: AdMultiSelect](#component-admultiselect)
+6. [Component: AdDataTable](#component-addatatable)
+7. [Adding New Components (Library Developers)](#adding-new-components)
+8. [Build & Publish Commands](#build--publish)
+
+---
+
+## Prerequisites & Installation
+
+### 1. Install the NPM Package
+Install `ng-adflowtail` and its required peers `flowbite` and `tslib`:
+
+```bash
+npm install ng-adflowtail flowbite tslib
+```
+
+### 2. Install Tailwind CSS
+Ensure your Angular project has Tailwind CSS set up. If not, follow the official [Tailwind CSS installation guide for Angular](https://tailwindcss.com/docs/guides/angular).
+
+---
+
+## Tailwind CSS Configuration
+
+Because `ng-adflowtail` relies on Tailwind classes, you **must** configure Tailwind to scan the library's compiled templates inside `node_modules` so that styles are not purged in production builds.
+
+### For Tailwind CSS v4 (Modern CSS Configuration)
+Add the `@source` directive in your main CSS file (e.g., `styles.css`):
+
+```css
+@import "tailwindcss";
+
+/* Add the source path to scan ng-adflowtail templates */
+@source "../../node_modules/ng-adflowtail";
+```
+
+### For Tailwind CSS v3 (`tailwind.config.js`)
+Add the `ng-adflowtail` path to your `content` array:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./src/**/*.{html,ts}",
+    "./node_modules/ng-adflowtail/**/*.{js,mjs,html}" // Add this line
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [
+    require('flowbite/plugin') // Enable Flowbite utility classes
+  ],
+}
+```
+
+---
+
+## Architecture & Scaffolding
+
+To import components, use their specialized entry points. Do **not** import everything from `ng-adflowtail` directly.
+
+```typescript
+// Core Directives & Shared Interfaces (Primary Entry Point)
+import { AdPrimaryColorDirective, AdColumn } from 'ng-adflowtail';
+
+// Individual Secondary Entry Points
+import { AdMultiSelect } from 'ng-adflowtail/ad-multi-select';
+import { AdDataTable } from 'ng-adflowtail/ad-data-table';
+```
+
+---
+
+## Branding & Custom Theming
+
+### `AdPrimaryColorDirective` (`[adPrimaryColor]`)
+
+Both `AdMultiSelect` and `AdDataTable` support dynamic theming via the `primaryColor` input. This input is automatically mapped on both components using Angular's robust **Host Directives** feature, delegating to the standalone `AdPrimaryColorDirective`.
+
+This directive dynamically binds modern CSS Custom Properties (`--color-brand`, `--color-fg-brand`, etc.) to the host elements. Under the hood, it uses native CSS `color-mix()` to calculate brand states on-the-fly based on any valid CSS color input (hex, rgb, hsl, or web colors):
+
+```typescript
+// Mapped custom properties on the host element style:
+--color-brand: [primaryColor];
+--color-brand-soft: color-mix(in srgb, [primaryColor] 10%, transparent);
+--color-brand-softer: color-mix(in srgb, [primaryColor] 5%, transparent);
+--color-brand-medium: color-mix(in srgb, [primaryColor] 20%, transparent);
+--color-brand-strong: color-mix(in srgb, [primaryColor] 90%, black);
+```
+
+#### Example: Dynamic Color Picker Implementation
+You can bind a color input or a signal directly to the widgets:
+
+```html
+<!-- Fully rebranded multi-select -->
+<ad-multi-select 
+  [formField]="userForm.permissions" 
+  [options]="permissionOptions" 
+  primaryColor="#0d9488" 
+/>
+
+<!-- Rebranded data table -->
+<ad-data-table 
+  [data]="users" 
+  [config]="tableConfig" 
+  primaryColor="#7c3aed" 
+/>
+```
+
+---
+
+## Component: AdMultiSelect
+
+The `AdMultiSelect` component (`ng-adflowtail/ad-multi-select`) is a highly interactive, accessible dropdown multi-select. It is integrated natively with the new **Angular Signal-based Forms** (`@angular/forms/signals`), displaying selection tokens as elegant, dismissible chips.
+
+### Key Features
+- **Signal Forms**: Directly binds to form fields via the `formField` input parameter.
+- **Interactive Tokens**: Selected values render as clean chips with a close button.
+- **Global Actions**: Includes fast-access "Select all" and "Clear" utilities.
+- **Robust UX**: Includes click-outside detection and `Escape` keyboard key handling to dismiss the dropdown panel safely.
+- **Validation-Driven**: Automatically applies red borders and error displays when the bound signal form is `touched` and `invalid`.
+
+---
+
+### Multi-Select API Spec
+
+#### `@Input()` Bindings
+| Input | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `formField` (Required) | `FieldTree<string[]>` | — | The signal forms field node to bind (e.g. `myForm.roles`). |
+| `options` | `AdMultiSelectOption[]` | `[]` | List of items available in the dropdown selector. |
+| `placeholder` | `string` | `'Select options'` | Label shown when no selection has been made yet. |
+| `disabled` | `boolean` | `false` | Disables user interaction and prevents opening the menu. |
+| `errorMessage` | `string` | `''` | Custom message text shown underneath the input on validation failure. |
+| `primaryColor` | `string` | — | Overrides default branding colors with computed dynamic CSS colors. |
+
+#### Model Interfaces
+
+```typescript
+export interface AdMultiSelectOption {
+  label: string;
+  value: string;
+}
+```
+
+---
+
+### Complete Multi-Select Example
+
+#### Component TS (`app.component.ts`)
+```typescript
+import { Component, signal } from '@angular/core';
+import { form, required } from '@angular/forms/signals';
+import { AdMultiSelect, AdMultiSelectOption } from 'ng-adflowtail/ad-multi-select';
+
+interface PermissionForm {
+  permissions: string[];
+}
+
+@Component({
+  selector: 'app-permission-manager',
+  standalone: true,
+  imports: [AdMultiSelect],
+  templateUrl: './app.component.html'
+})
+export class AppPermissionManager {
+  // Brand color customization
+  protected readonly themeColor = signal<string>('#0d9488'); // Custom Teal
+
+  // Local state container
+  protected readonly formModel = signal<PermissionForm>({
+    permissions: ['read']
+  });
+
+  // Signal forms validation & controller
+  protected readonly userForm = form(this.formModel, (path) => {
+    required(path.permissions, { message: 'Please select at least one permission.' });
+  });
+
+  // Available options
+  protected readonly permissionOptions: AdMultiSelectOption[] = [
+    { label: 'Read Access', value: 'read' },
+    { label: 'Write Access', value: 'write' },
+    { label: 'Delete Actions', value: 'delete' },
+    { label: 'Super Admin', value: 'admin' }
+  ];
+
+  protected onSubmit(event: Event) {
+    event.preventDefault();
+    if (this.userForm.valid()) {
+      console.log('Submitting verified model state:', this.formModel());
+    } else {
+      this.userForm.markAsTouched();
+      console.warn('Form validation failed.');
+    }
+  }
+}
+```
+
+#### Component HTML Template (`app.component.html`)
+```html
+<div class="max-w-md p-6 bg-white dark:bg-gray-800 rounded-xl shadow border border-gray-200 dark:border-gray-700">
+  <form (submit)="onSubmit($event)" class="space-y-4">
+    <div>
+      <label class="block mb-2 text-sm font-semibold text-gray-900 dark:text-white">
+        Role Permissions
+      </label>
+      
+      <!-- Multi Select Binding -->
+      <ad-multi-select
+        [formField]="userForm.permissions"
+        [options]="permissionOptions"
+        [primaryColor]="themeColor()"
+        placeholder="Select key permissions"
+        errorMessage="At least one permission is mandatory"
+      />
+    </div>
+
+    <!-- Active State Inspector -->
+    <div class="p-3 bg-gray-50 dark:bg-gray-900/50 rounded-lg text-xs">
+      <p class="font-semibold text-gray-500">Live Form Value:</p>
+      <code class="text-indigo-600 dark:text-indigo-400">{{ formModel() | json }}</code>
+    </div>
+
+    <button type="submit" class="w-full text-white bg-blue-600 hover:bg-blue-700 font-medium rounded-lg text-sm px-5 py-2.5">
+      Save Rules
+    </button>
+  </form>
+</div>
+```
+
+---
+
+## Component: AdDataTable
+
+The `AdDataTable` component (`ng-adflowtail/ad-data-table`) is a high-performance, feature-rich responsive table widget that simplifies handling large datasets.
+
+### Key Features
+- **Dynamic Columns**: Configurable fields with automated rendering based on data types (`text`, `number`, `date`, `currency` pre-formatted for SAR, `status`, `action`, `template`).
+- **Flexible Row Actions**: Built-in row buttons (EDIT, DELETE, VIEW) with custom text, colors, visibility conditions, and disable state callbacks per row.
+- **Built-in Global Search**: Instant master text filter across row records.
+- **Advanced Column Filters**: Supports field-by-field searching with specific widgets (`text`, `select`, `multiSelect`, `date`, `dateRange`, `number`, `autocomplete`).
+- **Paging Controls**: Custom pagination bar showing start/end ranges, previous/next controls, and customizable page size selections.
+
+---
+
+### Data Table API Spec
+
+#### `@Input()` Bindings
+| Input | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `title` | `string` | `''` | Headline shown above the table card. |
+| `data` | `any[]` | `[]` | Array of data records to display. |
+| `tableStyle` | `string` | — | Custom inline styling or CSS classes applied directly to the outer wrapper. |
+| `config` | `TableConfig` | See defaults below | Master schema and controls governing column capabilities and pagination. |
+| `primaryColor` | `string` | — | Overrides default branding colors with computed dynamic CSS colors. |
+
+**Default TableConfig Object:**
+```typescript
+{
+  columns: [],
+  itemsPerPage: 10,
+  showPagination: true,
+  showPageSize: true,
+  pageSizeOptions: [5, 10, 25, 50],
+  showSearch: true,
+  searchPlaceholder: 'Search...',
+  showActions: false,
+  showColumnSearch: false
+}
+```
+
+#### `@Output()` Events
+| Event | Payload Type | Description |
+| :--- | :--- | :--- |
+| `pageChange` | `number` | Emits the new page number selected by the user. |
+| `pageSizeChange` | `number` | Emits the new page size count chosen in the dropdown. |
+| `rowClick` | `any` | Emits the raw record object when a row is clicked. |
+| `actionClick` | `{ action: DataTableButtonAction; item: any }` | Triggered when a predefined action button in a row is clicked. |
+| `searchChange` | `string` | Emits the global search string entered by the user. |
+| `columnSearchChange` | `ColumnSearchEvent` | Triggered when any column-specific search input values are modified. |
+
+---
+
+### Data Table Types & Interfaces
+
+```typescript
+export type DataTableButtonAction = 'EDIT' | 'DELETE' | 'VIEW';
+
+export interface TableColumn {
+  field: string;
+  header: string;
+  type?: 'text' | 'number' | 'date' | 'currency' | 'status' | 'action' | 'template';
+  format?: string;
+  actionTemplate?: (item: any) => string;
+  statusColors?: { [key: string]: string };
+  searchable?: boolean;
+  searchPlaceholder?: string;
+  searchType?: 'text' | 'select' | 'multiSelect' | 'date' | 'dateRange' | 'number' | 'autocomplete';
+  searchOptions?: Array<{ value: any; label: string }>;
+  multiSelectConfig?: {
+    maxItems?: number;
+    showSelectAll?: boolean;
+  };
+  autocompleteConfig?: {
+    apiUrl?: string;
+    debounceTime?: number;
+    minChars?: number;
+    valueField?: string;
+    labelField?: string;
+    customSearchFn?: (searchTerm: string) => Promise<Array<{ value: any; label: string }>>;
+  };
+  actions?: TableAction[];
+}
+
+export interface TableAction {
+  id: DataTableButtonAction;
+  label: string;
+  icon?: string;
+  color?: 'primary' | 'success' | 'danger' | 'warning' | 'info' | 'secondary';
+  className?: string;
+  visible?: (item: any) => boolean;
+  disabled?: (item: any) => boolean;
+  tooltip?: string;
+}
+
+export interface TableConfig {
+  columns: TableColumn[];
+  totalCount?: number;
+  currentPage?: number;
+  pageSize?: number;
+  itemsPerPage?: number;
+  showPagination?: boolean;
+  showPageSize?: boolean;
+  pageSizeOptions?: number[];
+  showSearch?: boolean;
+  searchPlaceholder?: string;
+  showActions?: boolean;
+  showColumnSearch?: boolean;
+}
+
+export interface ColumnSearchEvent {
+  column: string;
+  value: any;
+  field: string;
+  searchType: string;
+}
+```
+
+---
+
+### Complete Data Table Example
+
+#### Component TS (`app.component.ts`)
+```typescript
+import { Component, computed, OnInit, signal } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { AdDataTable, TableConfig, ColumnSearchEvent } from 'ng-adflowtail/ad-data-table';
+
+interface Employee {
+  id: number;
+  name: string;
+  email: string;
+  department: string;
+  salary: number;
+  hireDate: string;
+  status: 'Active' | 'On Leave' | 'Terminated';
+}
+
+@Component({
+  selector: 'app-dashboard-table',
+  standalone: true,
+  imports: [CommonModule, AdDataTable],
+  templateUrl: './app.component.html'
+})
+export class AppDashboardTable implements OnInit {
+  protected readonly brandColor = signal<string>('#7c3aed'); // Violet theme
+
+  // Datastore
+  protected readonly employees = signal<Employee[]>([]);
+
+  // Filtering, Search and Pagination states
+  protected readonly currentPage = signal<number>(1);
+  protected readonly pageSize = signal<number>(5);
+  protected readonly globalSearch = signal<string>('');
+  protected readonly columnFilters = signal<Record<string, string>>({});
+
+  ngOnInit() {
+    // Bootstrap dummy data
+    this.employees.set([
+      { id: 101, name: 'Ahmad Al-Harbi', email: 'ahmad@company.com', department: 'Engineering', salary: 18500, hireDate: '2023-04-12', status: 'Active' },
+      { id: 102, name: 'Sarah Connor', email: 'sarah@company.com', department: 'Operations', salary: 14200, hireDate: '2021-08-19', status: 'Active' },
+      { id: 103, name: 'John Doe', email: 'john.d@company.com', department: 'Engineering', salary: 12000, hireDate: '2025-01-05', status: 'On Leave' },
+      { id: 104, name: 'Lina Gamil', email: 'lina@company.com', department: 'Marketing', salary: 9800, hireDate: '2022-11-01', status: 'Active' },
+      { id: 105, name: 'Michael Scott', email: 'michael@company.com', department: 'Sales', salary: 11500, hireDate: '2019-03-15', status: 'Terminated' }
+    ]);
+  }
+
+  // Reactive computed: filters records
+  protected readonly filteredEmployees = computed(() => {
+    let list = this.employees();
+    const search = this.globalSearch().toLowerCase();
+    const colFilters = this.columnFilters();
+
+    // 1. Process Global Master Search
+    if (search) {
+      list = list.filter(item => 
+        item.name.toLowerCase().includes(search) || 
+        item.email.toLowerCase().includes(search) ||
+        item.department.toLowerCase().includes(search)
+      );
+    }
+
+    // 2. Process Specific Column Searches
+    for (const [key, value] of Object.entries(colFilters)) {
+      if (value) {
+        list = list.filter(item => {
+          const itemVal = (item as any)[key]?.toString().toLowerCase();
+          return itemVal?.includes(value.toLowerCase());
+        });
+      }
+    }
+
+    return list;
+  });
+
+  // Reactive computed: extracts sliced pagination view
+  protected readonly paginatedEmployees = computed(() => {
+    const list = this.filteredEmployees();
+    const start = (this.currentPage() - 1) * this.pageSize();
+    const end = start + this.pageSize();
+    return list.slice(start, end);
+  });
+
+  protected readonly totalCount = computed(() => this.filteredEmployees().length);
+
+  // Dynamic Reactive Table Config
+  protected readonly tableConfig = computed<TableConfig>(() => ({
+    columns: [
+      { field: 'id', header: 'ID', type: 'number' },
+      { field: 'name', header: 'Full Name', type: 'text', searchable: true },
+      { field: 'email', header: 'Email Address', type: 'text', searchable: true },
+      { 
+        field: 'department', 
+        header: 'Department', 
+        type: 'text', 
+        searchable: true,
+        searchType: 'select',
+        searchOptions: [
+          { value: 'Engineering', label: 'Engineering' },
+          { value: 'Operations', label: 'Operations' },
+          { value: 'Marketing', label: 'Marketing' },
+          { value: 'Sales', label: 'Sales' }
+        ]
+      },
+      { field: 'salary', header: 'Base Salary', type: 'currency' },
+      { field: 'hireDate', header: 'Hire Date', type: 'date' },
+      { 
+        field: 'status', 
+        header: 'Status', 
+        type: 'status', 
+        searchable: true,
+        searchType: 'select',
+        searchOptions: [
+          { value: 'Active', label: 'Active' },
+          { value: 'On Leave', label: 'On Leave' },
+          { value: 'Terminated', label: 'Terminated' }
+        ],
+        statusColors: {
+          'Active': 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-400',
+          'On Leave': 'bg-amber-100 text-amber-800 dark:bg-amber-900/30 dark:text-amber-400',
+          'Terminated': 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-400'
+        }
+      },
+      {
+        field: 'actions',
+        header: 'Actions',
+        type: 'action',
+        actions: [
+          { id: 'VIEW', label: 'View Profile', color: 'primary' },
+          { 
+            id: 'DELETE', 
+            label: 'Remove', 
+            color: 'danger', 
+            disabled: (row) => row.status === 'Terminated' // Disable delete button for terminated staff
+          }
+        ]
+      }
+    ],
+    showPagination: true,
+    showPageSize: true,
+    pageSizeOptions: [5, 10, 20],
+    showSearch: true,
+    searchPlaceholder: 'Search directory...',
+    showActions: true,
+    showColumnSearch: true,
+    totalCount: this.totalCount(),
+    currentPage: this.currentPage(),
+    pageSize: this.pageSize()
+  }));
+
+  // Handle Reactive Handlers
+  protected onPageChange(page: number) {
+    this.currentPage.set(page);
+  }
+
+  protected onPageSizeChange(size: number) {
+    this.pageSize.set(size);
+    this.currentPage.set(1); // Reset to first page
+  }
+
+  protected onGlobalSearch(searchTerm: string) {
+    this.globalSearch.set(searchTerm);
+    this.currentPage.set(1);
+  }
+
+  protected onColumnSearch(event: ColumnSearchEvent) {
+    this.columnFilters.update(filters => ({
+      ...filters,
+      [event.field]: event.value
+    }));
+    this.currentPage.set(1);
+  }
+
+  protected onActionTriggered(event: { action: string; item: any }) {
+    console.log(`Action triggered: [${event.action}] on record ID:`, event.item.id);
+  }
+
+  protected onRowSelected(row: any) {
+    console.log('Row record clicked:', row);
+  }
+}
+```
+
+#### Component HTML Template (`app.component.html`)
+```html
+<div class="container mx-auto p-4">
+  <ad-data-table
+    title="Staff Directory"
+    [data]="paginatedEmployees()"
+    [config]="tableConfig()"
+    [primaryColor]="brandColor()"
+    (pageChange)="onPageChange($event)"
+    (pageSizeChange)="onPageSizeChange($event)"
+    (searchChange)="onGlobalSearch($event)"
+    (columnSearchChange)="onColumnSearch($event)"
+    (actionClick)="onActionTriggered($event)"
+    (rowClick)="onRowSelected($event)"
+  />
+</div>
+```
+
+---
+
+## Adding New Components
+
+If you are a library developer working on the `ng-adflowtail` monorepo workspace, you can easily add new components using ng-packagr's standard secondary entry points system.
+
+### Steps to scaffold a new widget `ad-badge`
+
+#### 1. Setup Folder Structure
+Create a new folder alongside the main `src` directory in `projects/ng-adflowtail/`:
+
+```
+projects/ng-adflowtail/
+├── src/                      # primary entry point
+├── ad-multi-select/          # secondary entry point 1
+├── ad-data-table/            # secondary entry point 2
+└── ad-badge/                 # <--- Your new secondary entry point
+    ├── ng-package.json
+    └── src/
+        ├── public-api.ts
+        └── lib/
+            ├── ad-badge.ts
+            ├── ad-badge.html
+            └── ad-badge.css
+```
+
+#### 2. Create `projects/ng-adflowtail/ad-badge/ng-package.json`
+Define the secondary packaging schema pointing back to the library:
+
+```json
+{
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}
+```
+
+#### 3. Create `projects/ng-adflowtail/ad-badge/src/public-api.ts`
+Export your exports correctly:
+
+```typescript
+export * from './lib/ad-badge';
+```
+
+#### 4. Configure compiler paths mapping in Root `tsconfig.json`
+Allow main apps in the monorepo to resolve imports locally during development:
+
+```json
+"paths": {
+  "ng-adflowtail": ["./projects/ng-adflowtail/src/public-api.ts"],
+  "ng-adflowtail/ad-data-table": ["./projects/ng-adflowtail/ad-data-table/src/public-api.ts"],
+  "ng-adflowtail/ad-multi-select": ["./projects/ng-adflowtail/ad-multi-select/src/public-api.ts"],
+  "ng-adflowtail/ad-badge": ["./projects/ng-adflowtail/ad-badge/src/public-api.ts"]  // Add this
+}
+```
+
+---
+
+## Build & Publish
+
+### Compile the entire package
+Use the Angular CLI to run a production build. Under the hood, `ng-packagr` compiles all the secondary entry points in sequence:
+
+```bash
+ng build ng-adflowtail
+```
+
+The compiled distributable files are stored under `/dist/ng-adflowtail`.
+
+### Publish to NPM
+Navigate to the build directory and run the publish command:
+
+```bash
+cd dist/ng-adflowtail
+npm publish --access public
+```
+
+---
+
+## License
+
+MIT © Ahmad Workspace. Fully custom-crafted components built for Angular 22 and styled with Tailwind CSS & Flowbite.