shirkasoft-ui-components 1.1.2 → 1.2.0

package/README.md

@@ -11,6 +11,10 @@
   Created by <a href="https://shirkasoft.com" target="_blank"><strong>Shirkasoft</strong></a>
 </p>
 
+<p align="center">
+  <img src="projects/showcase/public/readme.png" alt="Shirkasoft UI Components showcase" />
+</p>
+
 Angular 21+ UI components library built with **Tailwind CSS**, **standalone components**, **Angular signals**, and **light/dark theme** support via CSS custom properties.
 
 ## Installation
@@ -80,6 +84,12 @@ document.documentElement.classList.toggle('dark');
 | 12  | Tooltip       | `shk-tooltip`        | —                    | —                      |
 | 13  | Sidebar       | `shk-sidebar`        | —                    | —                      |
 | 14  | Rail Sidebar  | `shk-rail-sidebar`   | —                    | —                      |
+| 15  | Skeleton      | `shk-skeleton`       | —                    | —                      |
+| 16  | Tag           | `shk-tag`            | —                    | —                      |
+| 17  | Button        | `shk-button`         | —                    | —                      |
+| 18  | Knob          | `shk-knob`           | ✅                   | —                      |
+| 19  | Loading       | `shk-loading-*`      | —                    | —                      |
+| 20  | Tabs          | `shk-tabs`           | —                    | —                      |
 
 ---
 
@@ -789,6 +799,212 @@ interface RailSidebarItem {
 
 ---
 
+### Skeleton (`shk-skeleton`)
+
+Placeholder block shown while content is loading. Rectangular or circular, with `wave`, `pulse` or no animation.
+
+```html
+<shk-skeleton height="1.5rem" width="60%" />
+<shk-skeleton shape="circle" size="5rem" />
+<shk-skeleton width="16rem" height="5rem" borderRadius="12px" animation="pulse" />
+```
+
+| Input          | Type                          | Default      |
+| -------------- | ----------------------------- | ------------ |
+| `shape`        | `'rectangle' \| 'circle'`     | `'rectangle'`|
+| `size`         | `string`                      | `''` (circle)|
+| `width`        | `string`                      | `'100%'`     |
+| `height`       | `string`                      | `'1rem'`     |
+| `borderRadius` | `string`                      | `'0.25rem'`  |
+| `animation`    | `'wave' \| 'pulse' \| 'none'` | `'wave'`     |
+| `style`        | `object`                      | `{}`         |
+| `styleClass`   | `string`                      | `''`         |
+
+---
+
+### Tag (`shk-tag`)
+
+Small label used to highlight a value, status or category.
+
+```html
+<shk-tag value="Activo" severity="success" [rounded]="true" />
+<shk-tag value="Precio" severity="contrast" icon="dollar-sign" />
+```
+
+```typescript
+type TagSeverity = 'secondary' | 'success' | 'info' | 'warning' | 'danger' | 'contrast';
+```
+
+| Input        | Type           | Default       |
+| ------------ | -------------- | ------------- |
+| `value`      | `string \| number` | `''`       |
+| `severity`   | `TagSeverity`  | `'secondary'` |
+| `rounded`    | `boolean`      | `false`       |
+| `icon`       | `string`       | `''` (lucide) |
+| `style`      | `object`       | `{}`          |
+| `styleClass` | `string`       | `''`          |
+
+---
+
+### Button (`shk-button`)
+
+Generic button with severity variants, lucide icons, sizes and a loading state. Icons are resolved by name from a built-in lucide registry (`plus`, `pencil`, `trash-2`, `search`, `arrow-right`, …).
+
+```html
+<shk-button label="Añadir" icon="plus" (onClick)="create()" />
+<shk-button label="Eliminar" severity="danger" [outlined]="true" />
+<shk-button [label]="loading() ? 'Cargando…' : 'Guardar'" [loading]="loading()" />
+<shk-button icon="search" severity="secondary" [rounded]="true" ariaLabel="Buscar" />
+```
+
+```typescript
+type ButtonSeverity = 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'danger' | 'help' | 'contrast';
+type ButtonSize = 'small' | 'large';
+type ButtonIconPosition = 'left' | 'right' | 'top' | 'bottom';
+```
+
+| Input         | Type               | Default      |
+| ------------- | ------------------ | ------------ |
+| `label`       | `string`           | `''`         |
+| `icon`        | `string`           | `''` (lucide)|
+| `iconPos`     | `ButtonIconPosition`| `'left'`     |
+| `severity`    | `ButtonSeverity`   | `'primary'`  |
+| `outlined`    | `boolean`          | `false`      |
+| `text`        | `boolean`          | `false`      |
+| `raised`      | `boolean`          | `false`      |
+| `rounded`     | `boolean`          | `false`      |
+| `size`        | `ButtonSize`       | `undefined`  |
+| `disabled`    | `boolean`          | `false`      |
+| `loading`     | `boolean`          | `false`      |
+| `loadingIcon` | `string`           | `'refresh'`  |
+| `loadingText` | `string`           | `''`         |
+| `type`        | `'button' \| 'submit' \| 'reset'` | `'button'` |
+| `ariaLabel`   | `string`           | `''`         |
+| `title`       | `string`           | `''`         |
+| `style`       | `object`           | `{}`         |
+| `styleClass`  | `string`           | `''`         |
+
+| Output   | Type         |
+| -------- | ------------ |
+| `onClick`| `MouseEvent` |
+
+---
+
+### Knob (`shk-knob`)
+
+SVG radial knob with pointer drag and keyboard (arrow keys) support. Implements `ControlValueAccessor` (reactive forms / `[(ngModel)]`), and also offers `[(value)]`.
+
+```html
+<shk-knob [formControl]="scoreCtrl" [min]="0" [max]="10" [step]="0.5" [size]="120" />
+<shk-knob [(value)]="value" valueColor="#3b82f6" rangeColor="#e2e8f0" />
+```
+
+| Input         | Type      | Default                          |
+| ------------- | --------- | -------------------------------- |
+| `value`       | `model<number>` | `0`                        |
+| `min`         | `number`  | `0`                              |
+| `max`         | `number`  | `100`                            |
+| `step`        | `number`  | `1`                              |
+| `size`        | `number`  | `100` (px)                       |
+| `strokeWidth` | `number`  | `14`                             |
+| `valueColor`  | `string`  | `var(--shk-primary-600)`         |
+| `rangeColor`  | `string`  | `var(--shk-surface-200)`         |
+| `showValue`   | `boolean` | `true`                           |
+| `disabled`    | `boolean` | `false`                          |
+| `readonly`    | `boolean` | `false`                          |
+| `ariaLabel`   | `string`  | `''`                             |
+
+| Output   | Type     |
+| -------- | -------- |
+| `change` | `number` |
+| `end`    | `number` |
+
+---
+
+### Loading (`shk-loading-*`)
+
+A set of reusable loading indicators: spinner, indeterminate/determinate bar, dots and overlay.
+
+```html
+<shk-loading-spinner [size]="'2.5rem'" [thickness]="4" label="Cargando…" />
+<shk-loading-bar [indeterminate]="true" height="0.5rem" />
+<shk-loading-bar [indeterminate]="false" [progress]="progress()" />
+<shk-loading-dots [count]="5" label="Enviando…" />
+<shk-loading-overlay [visible]="loading" message="Cargando datos…" [backdrop]="'light'">
+  <!-- content to cover -->
+</shk-loading-overlay>
+```
+
+**`shk-loading-spinner`**
+
+| Input      | Type     | Default |
+| ---------- | -------- | ------- |
+| `size`     | `string` | `'2rem'`|
+| `thickness`| `number` | `3`     |
+| `color`    | `string` | primary token |
+| `label`    | `string` | `''`    |
+
+**`shk-loading-bar`**
+
+| Input          | Type      | Default      |
+| -------------- | --------- | ------------ |
+| `height`       | `string`  | `'0.25rem'`  |
+| `indeterminate`| `boolean` | `true`       |
+| `progress`     | `number`  | `0` (0-100)  |
+| `color`        | `string`  | primary token|
+| `rounded`      | `boolean` | `true`       |
+
+**`shk-loading-dots`**
+
+| Input   | Type     | Default      |
+| ------- | -------- | ------------ |
+| `size`  | `string` | `'0.5rem'`   |
+| `color` | `string` | primary token|
+| `count` | `number` | `3`          |
+| `label` | `string` | `''`         |
+
+**`shk-loading-overlay`**
+
+| Input        | Type                               | Default        |
+| ------------ | ---------------------------------- | -------------- |
+| `visible`    | `boolean`                          | `false`        |
+| `message`    | `string`                           | `''`           |
+| `spinnerSize`| `string`                           | `'2.5rem'`     |
+| `color`      | `string`                           | primary token  |
+| `backdrop`   | `'transparent' \| 'light' \| 'dark'` | `'transparent'` |
+
+---
+
+### Tabs (`shk-tabs`)
+
+Tabbed content with a PrimeNG-like nested API. Values can be numbers or strings; the active value is two-way bindable.
+
+```html
+<shk-tabs [value]="activeTab()" (valueChange)="onTabChange($event)" [scrollable]="true">
+  <shk-tablist [scrollable]="true">
+    <shk-tab [value]="0">General</shk-tab>
+    <shk-tab [value]="1">Detalle</shk-tab>
+    <shk-tab [value]="2" [disabled]="true">Bloqueado</shk-tab>
+  </shk-tablist>
+  <shk-tabpanels>
+    <shk-tabpanel [value]="0">Contenido General</shk-tabpanel>
+    <shk-tabpanel [value]="1">Contenido Detalle</shk-tabpanel>
+  </shk-tabpanels>
+</shk-tabs>
+```
+
+| Selector      | Inputs                   | Outputs         |
+| ------------- | ------------------------ | --------------- |
+| `shk-tabs`    | `value` (model), `scrollable` | `valueChange` |
+| `shk-tablist` | `scrollable`, `styleClass` | —              |
+| `shk-tab`     | `value`, `disabled`, `styleClass` | —        |
+| `shk-tabpanels`| —                       | —              |
+| `shk-tabpanel`| `value`                  | —              |
+
+> Panels are rendered lazily: only the active panel exists in the DOM.
+
+---
+
 ## Development
 
 ```bash