⛩️ Katashi UI Kit (ngx-katashi-ui)

Production-ready, reusable Angular UI Component Library & Design System for modern enterprise web applications.

📋 Table of Contents

• Overview & Architecture
• Key Features
• Installation & Quick Start
• Global Setup (Styles & Assets)
• Component API & Usage Catalog
  • 1. Data Display
  • 2. Form Controls & Editors
  • 3. Feedback & Overlays
  • 4. Layout & Navigation
  • 5. Pre-built Pages & Views
  • 6. Theme System & Dark Mode
• Internationalization (i18n)
• Documentation Architecture for GitHub & npm
• License & Support

🚀 Overview & Architecture

ngx-katashi-ui is engineered specifically for modern Angular applications using Standalone Components, Signals, and RxJS. It provides a comprehensive UI kit covering data tables, rich text editing, file handling, modals, slide-overs, dashboards, and error views.

Why ngx-katashi-ui?

• ⚡ 100% Standalone Component Architecture: Import only what you need. Zero NgModule overhead.
• 🎨 Complete Design System: Built-in CSS custom properties, responsive typography, flex grid system, dark/light themes, and custom scrollbars.
• 🎯 Embedded Bootstrap Icons: Self-contained web font — no CDN dependencies required.
• 🌐 Built-in i18n: Out-of-the-box support for English (en) and French (fr) with dynamic language switching via SharedI18nService.
• 📊 Enterprise Data Table: High-performance <dynamic-table> supporting custom cell templates, sorting, badge rendering, prices, dates, and actions.

✨ Key Features

| Category | Provided Components & Services | |---|---| | Data Presentation | <dynamic-table>, katashiTableCell directive, <badge>, <paginator>, <stat-card>, <no-data> | | Form Controls | <katashi-select>, <date-range-picker>, <qr-generator>, <katashi-editor>, <upload-file>, <upload-multi-files>, <upload-xlsx> | | Feedback & Overlays | <modal> (ModalService), <notifier> (NotifierService), <confirm-dialog>, <dropdown>, <loader> | | Layout & Structure | <content-layout>, <page-header>, <accordion> & <accordion-item>, <tabset> & <tab>, <swiper> & <swiper-item> | | Pre-built Views | <auth-login>, <error-401>, <error-403>, <error-404>, <error-500>, <error-502>, <under-dev> | | Theme Engine | <themes> switcher component, ThemesService with custom CSS variables |

📦 Installation & Quick Start

Install the package from the public npm registry:

npm install ngx-katashi-ui

Peer Dependencies

Ensure your project has the required Angular core dependencies installed:

npm install @angular/cdk @angular/forms @angular/router bootstrap-icons qrcode xlsx

⚙️ Global Setup (Styles & Assets)

1. Import Global SCSS Theme

In your main Angular application's src/styles.scss:

// Import Katashi UI Design System, tokens, and Bootstrap Icons font
@use 'ngx-katashi-ui/src/styles/styles.scss';

2. Configure Static Assets in angular.json (Optional)

To serve static icons and media bundled with the library, update your angular.json:

"architect": {
  "build": {
    "options": {
      "assets": [
        "src/favicon.ico",
        "src/assets",
        {
          "glob": "**/*",
          "input": "node_modules/ngx-katashi-ui/src/assets",
          "output": "/assets/"
        }
      ]
    }
  }
}

📚 Component API & Usage Catalog

1. Data Display

Dynamic Table (<dynamic-table>)

A feature-rich data table supporting formatted columns (ID, title, price, date, email, badge) and custom cell directives.

import { Component } from '@angular/core';
import { DynamicTableComponent, DynamicTableCellDirective, TableColumn } from 'ngx-katashi-ui';

@Component({
  selector: 'app-users-view',
  standalone: true,
  imports: [DynamicTableComponent, DynamicTableCellDirective],
  template: `
    <dynamic-table
      [columns]="columns"
      [data]="users"
      [tableTitle]="'Registered Users'"
      currency="EUR"
      [showActions]="true"
      (actionClick)="handleAction($event)">
      
      <!-- Custom Template for Action Column -->
      <ng-template katashiTableCell="actions" let-row>
        <button class="btn btn-sm btn-primary" (click)="editUser(row)">Edit</button>
      </ng-template>
    </dynamic-table>
  `
})
export class UsersViewComponent {
  columns: TableColumn[] = [
    { key: 'id', label: 'ID', valueType: 'id' },
    { key: 'name', label: 'User Name', valueType: 'title' },
    { key: 'email', label: 'Email Address', valueType: 'email' },
    { key: 'balance', label: 'Account Balance', valueType: 'price' },
    { key: 'status', label: 'Status', valueType: 'badge' }
  ];

  users = [
    { id: 'USR-001', name: 'Habib Bouzidi', email: '[email protected]', balance: 1450.5, status: 'Active' }
  ];

  handleAction(event: any) { console.log('Action triggered:', event); }
  editUser(user: any) { console.log('Editing user:', user); }
}

Stat Card (<stat-card>)

<stat-card
  [title]="'Total Revenue'"
  [value]="'$45,210'"
  [icon]="'bi-currency-dollar'"
  [trend]="'+12.5%'"
  [trendPositive]="true">
</stat-card>

2. Form Controls & Editors

Select Dropdown (<katashi-select>)

Searchable, customizable single/multi-select control.

import { Component } from '@angular/core';
import { SelectComponent, SelectOption } from 'ngx-katashi-ui';

@Component({
  selector: 'app-form-demo',
  standalone: true,
  imports: [SelectComponent],
  template: `
    <katashi-select
      [options]="roles"
      [placeholder]="'Select User Role'"
      (selectionChange)="onRoleSelected($event)">
    </katashi-select>
  `
})
export class FormDemoComponent {
  roles: SelectOption[] = [
    { label: 'Administrator', value: 'admin' },
    { label: 'Editor', value: 'editor' },
    { label: 'Viewer', value: 'viewer' }
  ];

  onRoleSelected(selected: SelectOption) {
    console.log('Selected role:', selected);
  }
}

QR Code Generator (<qr-generator>)

<qr-generator
  [value]="'https://github.com/habibbouzidi/ngx-katashi-ui'"
  [size]="200"
  [downloadable]="true">
</qr-generator>

File & XLSX Uploaders

<!-- Single File Upload -->
<upload-file (fileSelected)="onFileUploaded($event)"></upload-file>

<!-- Multi File Upload -->
<upload-multi-files (filesSelected)="onFilesUploaded($event)"></upload-multi-files>

<!-- Excel Parsing & Import Uploader -->
<upload-xlsx (dataParsed)="onExcelDataParsed($event)"></upload-xlsx>

3. Feedback & Overlays

Modal Dialog (ModalService & <modal>)

Inject ModalService programmatically anywhere in your code:

import { Component, inject, TemplateRef } from '@angular/core';
import { ModalService } from 'ngx-katashi-ui';

@Component({
  selector: 'app-modal-demo',
  standalone: true,
  template: `
    <button (click)="openConfirmation(tmpl)">Open Dialog</button>
    <ng-template #tmpl>
      <p>Are you sure you want to delete this resource?</p>
    </ng-template>
  `
})
export class ModalDemoComponent {
  private modalService = inject(ModalService);

  openConfirmation(template: TemplateRef<any>) {
    this.modalService.open({
      title: 'Confirm Deletion',
      content: template,
      backdrop: true,
      centered: true,
      buttons: [
        { text: 'Cancel', class: 'btn-secondary', action: () => this.modalService.close() },
        { text: 'Delete', class: 'btn-danger', action: () => this.performDelete() }
      ]
    });
  }

  performDelete() {
    console.log('Resource deleted');
    this.modalService.close();
  }
}

Notifier Toasts (NotifierService & <notifier>)

import { inject } from '@angular/core';
import { NotifierService } from 'ngx-katashi-ui';

export class ServiceDemo {
  private notifier = inject(NotifierService);

  showToast() {
    this.notifier.success('Operation completed successfully!');
    // Also available: .error(), .warning(), .info()
  }
}

4. Layout & Navigation

<!-- Content Layout Container -->
<content-layout>
  <page-header
    [title]="'User Management'"
    [subtitle]="'Manage system users and access permissions'">
  </page-header>

  <!-- Accordion -->
  <accordion>
    <accordion-item title="Section 1">Content 1</accordion-item>
    <accordion-item title="Section 2">Content 2</accordion-item>
  </accordion>

  <!-- Tabset -->
  <tabset>
    <tab title="General">General Settings Content</tab>
    <tab title="Security">Security Settings Content</tab>
  </tabset>
</content-layout>

5. Pre-built Pages & Views

Use ready-to-render error and template pages for quick application bootstrapping:

<!-- Error Pages -->
<error-401></error-401>
<error-403></error-403>
<error-404></error-404>
<error-500></error-500>
<error-502></error-502>

<!-- Under Development & Login Views -->
<auth-login (loginSubmit)="onLogin($event)"></auth-login>
<under-dev></under-dev>

6. Theme System & Dark Mode

Inject ThemesService or include <themes> to switch themes at runtime:

import { inject } from '@angular/core';
import { ThemesService } from 'ngx-katashi-ui';

export class AppComponent {
  private themeService = inject(ThemesService);

  toggleDarkMode() {
    this.themeService.setTheme('dark'); // 'light' | 'dark' | 'orange' | 'red'
  }
}

🌐 Internationalization (i18n)

ngx-katashi-ui contains an internal translation dictionary for English (en) and French (fr).

Toggle the active language dynamically:

import { inject } from '@angular/core';
import { SharedI18nService } from 'ngx-katashi-ui';

export class AppLanguageComponent {
  private i18n = inject(SharedI18nService);

  setFrench() {
    this.i18n.setLanguage('fr');
  }

  setEnglish() {
    this.i18n.setLanguage('en');
  }
}

📖 Documentation Architecture for GitHub & npm

To ensure that both your GitHub Repository and your npm Package Page stay 100% synchronized:

1. Single Source of Truth (README.md):
   • The primary documentation lives at the root of the project in README.md.
2. Automated Build Copy (ng-packagr):
   • When you run npm run build, ng-packagr automatically copies root README.md into dist/README.md.
3. Publish Output (npm publish):
   • Running npm publish uploads dist/, rendering this full guide on npmjs.com/package/ngx-katashi-ui.
4. GitHub Output (git push):
   • Pushing your repository renders this guide on github.com/habibbouzidi/ngx-katashi-ui.

📄 License & Author

• Author: Habib Bouzidi (GitHub Profile)
• License: Released under the MIT License.