npm - shirkasoft-ui-components - Versions diffs - 1.0.22 → 1.0.24 - Mend

shirkasoft-ui-components 1.0.22 → 1.0.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md +685 -0
package/fesm2022/shirkasoft-ui-components.mjs +734 -722
package/fesm2022/shirkasoft-ui-components.mjs.map +1 -1
package/package.json +2 -2

package/README.md ADDED Viewed

@@ -0,0 +1,685 @@
+# Shirkasoft UI Components
+<p align="center">
+  <a href="https://github.com/Ansem13/shirkasoft-ui-components/releases"><img src="https://img.shields.io/npm/v/shirkasoft-ui-components?style=flat&logo=npm&label=version" alt="npm version" /></a>
+  <a href="https://github.com/Ansem13/shirkasoft-ui-components/issues"><img src="https://img.shields.io/github/issues/Ansem13/shirkasoft-ui-components?style=flat&logo=github" alt="GitHub issues" /></a>
+  <a href="https://github.com/Ansem13/shirkasoft-ui-components"><img src="https://img.shields.io/badge/source-github-181717?style=flat&logo=github" alt="GitHub source" /></a>
+  <a href="https://ansem13.github.io/shirkasoft-ui-components/"><img src="https://img.shields.io/badge/showcase-online-10b981?style=flat&logo=githubpages" alt="Showcase" /></a>
+</p>
+<p align="center">
+  Created by <a href="https://shirkasoft.com" target="_blank"><strong>Shirkasoft</strong></a>
+</p>
+Angular 21+ UI components library built with **Tailwind CSS**, **standalone components**, **Angular signals**, and **light/dark theme** support via CSS custom properties.
+## Installation
+```bash
+pnpm add shirkasoft-ui-components
+# or
+npm install shirkasoft-ui-components
+```
+### Peer Dependencies
+| Package | Minimum version |
+|---|---|
+| @angular/common | ^21.2.0 |
+| @angular/core | ^21.2.0 |
+| @angular/forms | ^21.2.0 |
+| rxjs | ^7.8.0 |
+| @jsverse/transloco | >= 8.0.0 |
+| @lucide/angular | ^1.17.0 |
+| chart.js | ^4.4.0 |
+## Theme Setup
+Import the theme in your global `styles.css`:
+```css
+@import '@shirkasoft/ui-components/theme.css';
+```
+The theme is based on `--shk-*` CSS variables. To customize colors, override the variables in `:root` (light mode) and `.dark` (dark mode):
+```css
+:root {
+  --shk-primary-500: #3b82f6;
+  --shk-primary-600: #2563eb;
+  /* ... */
+}
+```
+### Dark mode
+Add the `dark` class to the `<html>` element to enable dark mode.
+```typescript
+document.documentElement.classList.toggle('dark');
+```
+---
+## Components
+| # | Component | Selector | ControlValueAccessor | Associated service |
+|---|---|---|---|---|
+| 1 | TextField | `shk-text-field` | ✅ | — |
+| 2 | Toggle | `shk-toggle` | ✅ | — |
+| 3 | Select | `shk-select` | ✅ | — |
+| 4 | DatePicker | `shk-date-picker` | ✅ | — |
+| 5 | PriceInput | `shk-price-input` | — | — |
+| 6 | FileUpload | `shk-file-upload` | — | — |
+| 7 | Table | `shk-table` | — | — |
+| 8 | Modal | `shk-modal` | — | `ModalService` |
+| 9 | Notification | `shk-notification` | — | `NotificationService` |
+| 10 | ConfirmDialog | `shk-confirm-dialog` | — | `ConfirmDialogService` |
+| 11 | Chart | `shk-chart` | — | — |
+| 12 | Tooltip | `shk-tooltip` | — | — |
+---
+### TextField (`shk-text-field`)
+Text input with support for input, textarea, password, search, credit card formatting, and error validation. Implements `ControlValueAccessor`.
+```html
+<shk-text-field
+  [label]="'Name'"
+  [control]="myControl"
+  [type]="'text'"
+  [placeholder]="'Enter your name'"
+  [disabled]="false"
+  [errorMessages]="{ required: 'This field is required' }"
+  [isTextArea]="false"
+  [searchMode]="false"
+  (searchButtonClick)="onSearch()"
+/>
+```
+| Input | Type | Default |
+|---|---|---|
+| `id` | `string` | `''` |
+| `label` | `string` | `''` |
+| `type` | `string` | `'text'` |
+| `placeholder` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+| `control` | `FormControl` | `undefined` |
+| `formGroup` | `FormGroup` | `undefined` |
+| `errorMessage` | `string` | `''` |
+| `errorMessages` | `{ [key: string]: string }` | `{}` |
+| `isTextArea` | `boolean` | `false` |
+| `textAreaHeight` | `string` | `'h-28'` |
+| `searchMode` | `boolean` | `false` |
+| `searchButtonClick` | `output<void>` | — |
+| `numbersOnly` | `boolean` | `false` |
+| `allowDecimals` | `boolean` | `false` |
+| `maxLength` | `number` | `undefined` |
+| `formatCard` | `boolean` | `false` |
+| `preventNegative` | `boolean` | `false` |
+| `displayValue` | `string` | `''` |
+| `autocomplete` | `string` | `'new-password'` |
+> Also exposes `inputElement` and `textareaElement` as `viewChild`.
+---
+### Toggle (`shk-toggle`)
+Switch or checkbox. Implements `ControlValueAccessor`.
+```html
+<shk-toggle
+  [label]="'Enable notifications'"
+  [mode]="'toggle'"
+  [(checked)]="isChecked"
+  (checkedChange)="onChange($event)"
+/>
+```
+| Input | Type | Default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `mode` | `'toggle' \| 'checkbox'` | `'toggle'` |
+| `checked` | `boolean` | `undefined` |
+| Output | Type |
+|---|---|
+| `checkedChange` | `boolean` |
+---
+### Select (`shk-select`)
+Searchable dropdown with pagination, multiple selection, custom options, and validation. Implements `ControlValueAccessor`.
+```html
+<shk-select
+  [options]="options"
+  [label]="'Country'"
+  [control]="countryControl"
+  [multiple]="false"
+  [isSearchable]="true"
+  [usePagination]="true"
+  [itemsPerPage]="10"
+  [allowCustomEntries]="false"
+  [placeholder]="'Select...'"
+  [isLoading]="false"
+  (selectionChange)="onSelect($event)"
+  (search)="onSearch($event)"
+/>
+```
+```typescript
+interface SelectOption {
+  label: string;
+  value: any;
+  custom?: boolean;
+}
+```
+| Input | Type | Default |
+|---|---|---|
+| `options` | `SelectOption[]` | `[]` |
+| `label` | `string` | `undefined` |
+| `placeholder` | `string` | `'Select...'` |
+| `disabled` | `boolean` | `false` |
+| `control` | `FormControl` | `undefined` |
+| `formGroup` | `FormGroup` | `undefined` |
+| `multiple` | `boolean` | `false` |
+| `isSearchable` | `boolean` | `false` |
+| `usePagination` | `boolean` | `false` |
+| `itemsPerPage` | `number` | `10` |
+| `allowCustomEntries` | `boolean` | `false` |
+| `isLoading` | `boolean` | `false` |
+| `isAllDataLoaded` | `boolean` | `false` |
+| `preserveSearchOnLoad` | `boolean` | `false` |
+| `dropdownUpward` | `boolean` | `false` |
+| `showEmptyOption` | `boolean` | `true` |
+| `emptyMessageKey` | `string` | `'common.no_records'` |
+| `validCombinations` | `string[][]` | `undefined` |
+| `errorMessages` | `{ [key: string]: string }` | `{ required: 'This field is required' }` |
+| Output | Type |
+|---|---|
+| `selectionChange` | `any` |
+| `search` | `string` |
+---
+### DatePicker (`shk-date-picker`)
+Date, month, or year picker. Implements `ControlValueAccessor`. Supports `'date'`, `'month'`, `'year'` views.
+```html
+<shk-date-picker
+  [label]="'Start date'"
+  [control]="dateControl"
+  [view]="'date'"
+  [locale]="'es'"
+  [minValue]="'2024-01-01'"
+  [maxValue]="'2026-12-31'"
+/>
+```
+| Input | Type | Default |
+|---|---|---|
+| `id` | `string` | `''` |
+| `label` | `string` | `''` |
+| `placeholder` | `string` | `''` |
+| `view` | `'date' \| 'month' \| 'year'` | `'date'` |
+| `control` | `FormControl` | `undefined` |
+| `formGroup` | `FormGroup` | `undefined` |
+| `disabled` | `boolean` | `false` |
+| `errorMessage` | `string` | `''` |
+| `errorMessages` | `{ [key: string]: string }` | `{}` |
+| `minValue` | `string` | `''` |
+| `maxValue` | `string` | `''` |
+| `locale` | `string` | `'es'` |
+**Return value** depends on `view`:
+- `'date'` → `'YYYY-MM-DD'`
+- `'month'` → `'YYYY-MM'`
+- `'year'` → `'YYYY'`
+---
+### PriceInput (`shk-price-input`)
+Numeric input with toggle between amount (`$`) and percentage (`%`). Uses Angular `model()` for two-way binding.
+```html
+<shk-price-input
+  [(value)]="price"
+  [(isPercentage)]="isPercent"
+  [label]="'Price'"
+  [min]="0"
+  [max]="10000"
+  [required]="true"
+  [showError]="hasError"
+  [errorMessage]="'Invalid value'"
+/>
+```
+| Input | Type | Default |
+|---|---|---|
+| `value` | `model<number>` | **required** |
+| `isPercentage` | `model<boolean>` | `false` |
+| `label` | `string` | `''` |
+| `inputId` | `string` | `''` |
+| `required` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `min` | `number` | `0` |
+| `max` | `number` | `Infinity` |
+| `showError` | `boolean` | `false` |
+| `errorMessage` | `string` | `''` |
+---
+### FileUpload (`shk-file-upload`)
+File upload with drag & drop, image preview, file type and size validation.
+```html
+<shk-file-upload
+  [label]="'Upload your photo'"
+  [accept]="'image/*'"
+  [maxFileSize]="5 * 1024 * 1024"
+  [maxFiles]="3"
+  [multiple]="true"
+  (fileSelected)="onFilesSelected($event)"
+  (fileRemoved)="onFileRemoved()"
+  (fileError)="onFileError($event)"
+/>
+```
+```typescript
+interface FileUploadError {
+  type: 'size' | 'type';
+  message: string;
+  file: File;
+}
+```
+| Input | Type | Default |
+|---|---|---|
+| `label` | `string` | `'Upload file'` |
+| `accept` | `string` | `'image/*'` |
+| `maxFileSize` | `number` | `2 * 1024 * 1024` (2MB) |
+| `maxFiles` | `number` | `0` (unlimited) |
+| `multiple` | `boolean` | `false` |
+| `fileUploadText` | `string` | `'Select file'` |
+| `changeFilesText` | `string` | `'Change files'` |
+| `fileRecommendation` | `string` | `''` |
+| Output | Type |
+|---|---|
+| `fileSelected` | `File[]` |
+| `fileRemoved` | `void` |
+| `fileError` | `FileUploadError` |
+| `fileWarning` | `FileUploadError` |
+---
+### Table (`shk-table`)
+Data table with sorting, column filters, global search, pagination, row actions, and header actions. Supports client and server-side mode.
+```html
+<shk-table
+  [data]="users"
+  [columns]="columns"
+  [loading]="isLoading"
+  [serverSide]="true"
+  [totalRecords]="totalUsers"
+  [rowActions]="rowActions"
+  [headerActions]="headerActions"
+  [rowsPerPage]="25"
+  [showSearch]="true"
+  (pageChange)="onPageChange($event)"
+  (searchChange)="onSearch($event)"
+  (refresh)="loadData()"
+/>
+```
+```typescript
+interface Column {
+  field: string;
+  header: string;
+  sortable?: boolean;
+  filter?: boolean;
+  filterPlaceholder?: string;
+  width?: string;
+  defaultSort?: true;
+  filterType?: 'text' | 'exact' | 'select';
+  filterOptions?: { label: string; value: any }[];
+  template?: 'text' | 'tag';
+  format?: (row: any) => string;
+  tagValue?: (row: any) => string;
+  tagSeverity?: (row: any) => 'success' | 'danger' | 'warn' | 'info' | undefined;
+  tagStyle?: (row: any) => { [key: string]: string } | undefined;
+}
+interface TableAction {
+  label: string;
+  icon: string;
+  onClick: () => void;
+  class?: string;
+  isVisible?: () => boolean;
+  isDisabled?: () => boolean;
+}
+interface RowAction {
+  label: string | ((data: any) => string);
+  icon: string | ((data: any) => string);
+  onClick: (rowData: any) => void;
+  class?: string | ((data: any) => string);
+  isVisible?: (rowData: any) => boolean;
+  isDisabled?: (rowData: any) => boolean;
+}
+interface PageChangeEvent {
+  first: number;
+  rows: number;
+  page: number;
+  pageCount: number;
+}
+interface FilterChangeEvent {
+  filters: { [key: string]: any };
+}
+```
+| Input | Type | Default |
+|---|---|---|
+| `data` | `any[]` | `[]` |
+| `columns` | `Column[]` | `[]` |
+| `rowsPerPage` | `number` | `10` |
+| `rowsPerPageOptions` | `number[]` | `[10, 25, 50]` |
+| `loading` | `boolean` | `false` |
+| `showActionRow` | `boolean` | `true` |
+| `headerActions` | `TableAction[]` | `[]` |
+| `rowActions` | `RowAction[]` | `[]` |
+| `hasShadow` | `boolean` | `true` |
+| `defaultSortField` | `string` | `''` |
+| `defaultSortOrder` | `number` | `1` |
+| `showSearch` | `boolean` | `true` |
+| `searchPlaceholder` | `string` | `''` |
+| `emptyMessage` | `string` | `''` |
+| `serverSide` | `boolean` | `false` |
+| `totalRecords` | `number` | `0` |
+| `filters` | `{ label: string; value: string }[]` | `[]` |
+| `activeFilter` | `string` | `''` |
+| `customTemplates` | `{ [key: string]: any }` | `{}` |
+| Output | Type |
+|---|---|
+| `pageChange` | `PageChangeEvent` |
+| `filterChange` | `FilterChangeEvent` |
+| `searchChange` | `string` |
+| `filterClick` | `string` |
+| `refresh` | `void` |
+---
+### Modal (`shk-modal`)
+Dynamic modal that loads components via `ModalService`. Supports forms, fullscreen expansion, and accept/cancel buttons.
+```html
+<shk-modal />
+```
+```typescript
+interface ModalConfig {
+  title: string;
+  component: Type<any>;
+  data?: Record<string, any>;
+  width?: string;
+  showButtons?: boolean;
+  showExpandButton?: boolean;
+  acceptLabel?: string;
+  cancelLabel?: string;
+  onClose?: () => void;
+}
+```
+The injected component **must** expose:
+- `form?: FormGroup` (optional, for validation)
+- `onSubmit()` → calls `submitSuccess` or `submitError`
+- `submitSuccess?: EventEmitter<void>` (optional)
+- `submitError?: EventEmitter<void>` (optional)
+- `handleCancel?: () => void` (optional)
+```typescript
+constructor(private modalSrv: ModalService) {}
+openModal() {
+  this.modalSrv.open({
+    title: 'Edit user',
+    component: EditUserComponent,
+    data: { userId: 123 },
+    width: '600px',
+    showButtons: true,
+    showExpandButton: true,
+  });
+}
+closeModal() {
+  this.modalSrv.close();
+}
+```
+**Service methods:**
+| Method | Description |
+|---|---|
+| `open(config: ModalConfig)` | Opens a new modal |
+| `close()` | Closes the current modal |
+| `accept()` | Closes the modal (alias for close) |
+| `clear()` | Closes all modals |
+---
+### Notification (`shk-notification`)
+Toast notification system with configurable positions and optional progress bar.
+```html
+<shk-notification position="right-top" />
+```
+```typescript
+interface Notification {
+  id: string;
+  message: string;
+  type: 'success' | 'error' | 'warning' | 'info';
+  progress?: number;
+  showProgress?: boolean;
+}
+```
+```typescript
+constructor(private notifSrv: NotificationService) {}
+showNotif() {
+  const id = this.notifSrv.addNotification(
+    'Operation successful',
+    'success',
+    false,  // showProgress
+    3000    // duration (ms)
+  );
+}
+updateProgress(id: string, progress: number) {
+  this.notifSrv.updateProgress(id, progress);
+}
+```
+| Input | Type | Default |
+|---|---|---|
+| `position` | `'center-top' \| 'right-top' \| 'left-top'` | `'center-top'` |
+**Service methods:**
+| Method | Description |
+|---|---|
+| `addNotification(msg, type?, showProgress?, duration?)` | Adds a notification |
+| `updateProgress(id, progress)` | Updates the progress bar |
+| `removeNotification(notification)` | Removes a notification |
+| `removeNotificationById(id)` | Removes by ID |
+| `clearAll()` | Removes all notifications |
+---
+### ConfirmDialog (`shk-confirm-dialog`)
+Programmatic confirmation dialog. Used via `ConfirmDialogService` which dynamically creates it.
+```html
+<!-- No need to add it to the template -->
+```
+```typescript
+interface ConfirmConfig {
+  title?: string;
+  message: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  loadingText?: string;
+  type?: 'danger' | 'info' | 'warning';
+  showCancel?: boolean;
+  loading?: boolean;
+}
+```
+```typescript
+constructor(private confirmSrv: ConfirmDialogService) {}
+async deleteItem() {
+  const confirmed = await this.confirmSrv.confirm({
+    title: 'Delete user',
+    message: 'Are you sure you want to delete this user?',
+    confirmLabel: 'Delete',
+    type: 'danger',
+  });
+  if (confirmed) {
+    // proceed with deletion
+  }
+}
+```
+| Input | Type | Default |
+|---|---|---|
+| `title` | `string` | `'Confirm action'` |
+| `message` | `string` | `'Are you sure you want to proceed?'` |
+| `confirmLabel` | `string` | `'Confirm'` |
+| `cancelLabel` | `string` | `'Cancel'` |
+| `loadingText` | `string` | `'Processing…'` |
+| `type` | `'danger' \| 'info' \| 'warning'` | `'danger'` |
+| `loading` | `boolean` | `false` |
+| `showCancel` | `boolean` | `true` |
+| Output | Type |
+|---|---|
+| `closed` | `void` |
+---
+### Chart (`shk-chart`)
+Chart.js wrapper supporting the main chart types.
+```html
+<shk-chart
+  [type]="'bar'"
+  [data]="chartData"
+  [options]="chartOptions"
+/>
+```
+```typescript
+import { COLOR_PALETTE, readThemeColors } from 'shirkasoft-ui-components';
+const colors = readThemeColors(); // current theme colors
+```
+| Input | Type | Default |
+|---|---|---|
+| `type` | `'line' \| 'bar' \| 'pie' \| 'doughnut' \| 'polarArea'` | `'bar'` |
+| `data` | `any` | `{ datasets: [] }` |
+| `options` | `any` | `{}` |
+**Exported utils:**
+| Export | Description |
+|---|---|
+| `COLOR_PALETTE` | Predefined color array (bg + border) |
+| `readThemeColors()` | Reads current theme colors (`--shk-surface-*`) |
+---
+### Tooltip (`shk-tooltip`)
+Tooltip with two modes: `hover` (CSS positioning) and `fixed` (JS-calculated positioning).
+```html
+<shk-tooltip [text]="'Additional info'" [position]="'bottom'" [mode]="'hover'">
+  <button>Hover me</button>
+</shk-tooltip>
+```
+| Input | Type | Default |
+|---|---|---|
+| `text` | `string` | `''` |
+| `position` | `'top' \| 'bottom' \| 'right'` | `'bottom'` |
+| `mode` | `'hover' \| 'fixed'` | `'hover'` |
+| `offset` | `number` | `8` |
+---
+## Development
+```bash
+# Build the library
+pnpm build
+# Serve the showcase (demo app)
+pnpm serve
+# Build the showcase
+pnpm build:showcase
+# Watch for library changes
+pnpm watch
+```
+### Versioning
+```bash
+pnpm version:patch   # 1.0.22 → 1.0.23
+pnpm version:minor   # 1.0.22 → 1.1.0
+pnpm version:major   # 1.0.22 → 2.0.0
+```
+---
+## Publishing
+CI/CD via GitHub Actions:
+- Pushing a `v*` tag automatically publishes to npm.
+- Pushing to `main`/`master` deploys the showcase to GitHub Pages.
+Manual:
+```bash
+bash scripts/publish-lib.sh
+```
+---
+## License
+MIT © Shirkasoft