@keepui/ui 0.4.0 → 0.5.0

package/README.md

@@ -1,153 +1,167 @@
 # KeepUI
 
-> Angular cross-platform UI component library with optional Capacitor support.
-
-[![npm version](https://img.shields.io/npm/v/@keepui/ui.svg)](https://www.npmjs.com/package/@keepui/ui)
-[![license](https://img.shields.io/npm/l/@keepui/ui.svg)](LICENSE)
-
----
-
-## Table of Contents
-
-- [Purpose](#purpose)
-- [Package Structure](#package-structure)
-- [Installation](#installation)
-- [Setup](#setup)
-  - [1. Import styles](#1-import-styles)
-  - [2. Register providers](#2-register-providers)
-- [Available Components](#available-components)
-  - [`<keepui-button>`](#keepui-button)
-  - [`<keepui-card>`](#keepui-card)
-  - [`<keepui-icon>`](#keepui-icon)
-  - [`<keepui-icon-action-button>`](#keepui-icon-action-button)
-  - [`<keepui-image-preview>`](#keepui-image-preview)
-- [i18n](#i18n)
-- [Theming](#theming)
-- [Architecture Notes](#architecture-notes)
-- [Testing](#testing)
-- [Building](#building)
-- [Publishing to npm](#publishing-to-npm)
-
----
-
-## Purpose
-
-KeepUI is a reusable Angular component library designed to work seamlessly across:
-
-- **Standard Angular web applications** (browser only)
-- **Angular + Capacitor applications** (iOS, Android, PWA)
-
-The library uses a **Port/Adapter pattern** to keep UI components fully decoupled from platform-specific APIs. Components never import `@capacitor/*` directly; they depend on injected interface implementations registered via functional providers.
+> Component library for Angular with multi-platform support (web and Angular + Capacitor).
+> Built on **Tailwind CSS v4** with full **light/dark** theming and **i18n** via `@jsverse/transloco`.
+>
+> **Auto-generated** from JSDoc in the source files.
+> Do **not** edit manually — run `npm run docs:generate` to update.
 
 ---
+## 1. Package identity
 
-## Package Structure
-
-| Package | Description |
+| Field | Value |
 |---|---|
-| `@keepui/ui` | Core components, ports, tokens, services, web adapter |
-| `@keepui/ui/capacitor` | Capacitor adapter — use *instead of* the web provider |
+| Package name | `@keepui/ui` |
+| Angular compat | `>= 19` |
+| Style engine | Tailwind CSS v4 |
+| i18n engine | `@jsverse/transloco` |
 
 ---
+## 2. Installation
 
-## Installation
+### Option A — local build (development)
 
 ```bash
-# Using ng add (recommended):
-ng add @keepui/ui
+npm run build         # outputs to dist/keep-ui
+npm install /absolute/path/to/dist/keep-ui
+```
 
-# Or manually:
+### Option B — npm registry
+
+```bash
 npm install @keepui/ui
 ```
 
-For Capacitor support (optional):
+### Required peer dependencies
 
 ```bash
-npm install @capacitor/core @capacitor/camera
-npx cap sync
+npm install @angular/common @angular/core @jsverse/transloco
 ```
 
 ---
+## 3. Global styles (required)
 
-## Setup
-
-### 1. Import styles
-
-KeepUI components use CSS custom properties for theming. Import the library styles in your global stylesheet **before** any component-level styles.
-
-**If your project uses Tailwind CSS v4:**
+Add once to the host application's global stylesheet (e.g. `src/styles.css`):
 
 ```css
-/* src/styles.css */
-@import "tailwindcss";
 @import "@keepui/ui/styles";
 ```
 
-**If your project does NOT use Tailwind:**
+Provides:
+- Light theme CSS custom properties (default)
+- Dark theme via `[data-theme="dark"]`
+- Auto dark via `@media (prefers-color-scheme: dark)`
+- Tailwind v4 `@theme inline` mappings for all `bg-keepui-*`, `text-keepui-*`, `border-keepui-*`, `shadow-keepui-*` utilities
 
-```css
-/* src/styles.css */
-@import "@keepui/ui/styles/prebuilt.css";
-```
+#### Theme switching at runtime
 
-### 2. Register providers
+```ts
+document.documentElement.setAttribute('data-theme', 'dark');   // force dark
+document.documentElement.setAttribute('data-theme', 'light');  // force light
+document.documentElement.removeAttribute('data-theme');         // follow OS
+```
 
-Register one platform provider plus the i18n provider in `app.config.ts`.
+---
+## 4. Provider setup (`app.config.ts`)
 
-**Web:**
+### Web application
 
 ```ts
-// src/app/app.config.ts
-import { ApplicationConfig } from '@angular/core';
-import { provideRouter } from '@angular/router';
 import { provideKeepUi, provideKeepUiI18n } from '@keepui/ui';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    provideRouter(routes),
-    provideKeepUi(),
-    provideKeepUiI18n({ defaultLang: 'en' }),
+    provideKeepUi(),              // registers WebFileService for FILE_PORT
+    provideKeepUiI18n(),          // default language: 'en'
+    // provideKeepUiI18n({ defaultLang: 'es' }),
   ],
 };
 ```
 
-**Angular + Capacitor:**
+### Angular + Capacitor application
 
 ```ts
-// src/app/app.config.ts
-import { ApplicationConfig } from '@angular/core';
-import { provideRouter } from '@angular/router';
-import { provideKeepUiI18n } from '@keepui/ui';
 import { provideKeepUiCapacitor } from '@keepui/ui/capacitor';
+import { provideKeepUiI18n } from '@keepui/ui';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideKeepUiCapacitor(), provideKeepUiI18n()],
+};
+```
+
+> **Rule:** Never register both `provideKeepUi()` and `provideKeepUiCapacitor()` at the same time.
+
+### Available provider functions
 
+#### `provideKeepUiI18n(options?: KeepUiI18nOptions = {}): EnvironmentProviders`
+
+Registers all providers required for KeepUI internationalisation.
+
+- Configures a self-contained Transloco instance scoped to `'keepui'`.
+- Bundles all translations **inline** — no HTTP assets required.
+- Provides {@link KeepUiLanguageService} so the host app can switch locale.
+
+### Usage in `app.config.ts`
+```ts
 export const appConfig: ApplicationConfig = {
   providers: [
-    provideRouter(routes),
-    provideKeepUiCapacitor(),          // instead of provideKeepUi()
-    provideKeepUiI18n({ defaultLang: 'en' }),
+    provideKeepUi(),
+    provideKeepUiI18n(),                // default language: 'en'
+    provideKeepUiI18n({ defaultLang: 'es' }), // or start in Spanish
   ],
 };
 ```
 
-> **Note:** Use `provideKeepUiCapacitor()` **instead of** `provideKeepUi()` — never both.
+### Changing language at runtime
+```ts
+const lang = inject(KeepUiLanguageService);
+lang.setLanguage('de');
+```
+
+> **Note:** If your application already calls `provideTransloco()`, do NOT
+> call `provideKeepUiI18n()` — instead configure your Transloco loader to
+> handle the `'keepui/{lang}'` scope paths, and provide `KeepUiLanguageService`
+> manually.
+
+#### `provideKeepUi(): EnvironmentProviders`
+
+Registers KeepUI core providers for a **web** Angular application.
+
+Registers `WebFileService` as the implementation of `FILE_PORT`, enabling
+all KeepUI components to use the browser's native file picker.
+
+Add to `app.config.ts`:
+```ts
+export const appConfig: ApplicationConfig = {
+  providers: [provideKeepUi()],
+};
+```
 
 ---
 
-## Available Components
+## 5. Component API reference
 
-### `<keepui-button>`
+All components are **standalone**. Import directly from `@keepui/ui`.
 
-Accessible, themed action button with variants, shapes, sizes, loading state, full-width layout, and named icon slots.
+### 5.1 `ButtonComponent`
+
+**Selector:** `keepui-button`
+**Import:** `import { ButtonComponent } from '@keepui/ui';`
+
+Accessible, themed action button with support for variants, shapes, sizes,
+loading state, full-width layout, and named icon slots.
+
+Works identically on **web** and **Angular + Capacitor** (no native API usage).
 
 ```html
-<!-- Basic -->
+<!-- Basic usage -->
 <keepui-button (clicked)="save()">Save</keepui-button>
 
-<!-- Variant + shape -->
-<keepui-button variant="danger" shape="rounded" size="auto">Delete</keepui-button>
+<!-- Primary, pill-shaped, fixed width -->
+<keepui-button variant="primary" shape="pill">Confirm</keepui-button>
 
-<!-- With leading icon -->
-<keepui-button variant="primary" size="auto">
+<!-- With leading icon (any inline element) -->
+<keepui-button variant="outline" size="auto">
   <svg slot="leading" width="16" height="16" aria-hidden="true">…</svg>
   Upload
 </keepui-button>
@@ -155,338 +169,789 @@ Accessible, themed action button with variants, shapes, sizes, loading state, fu
 <!-- Loading state -->
 <keepui-button [loading]="isSaving()">Saving…</keepui-button>
 
-<!-- Full-width -->
-<keepui-button [fullWidth]="true">Submit</keepui-button>
+<!-- Full-width, danger -->
+<keepui-button variant="danger" [fullWidth]="true">Delete account</keepui-button>
 
-<!-- Icon-only (ariaLabel required) -->
+<!-- Icon-only (requires ariaLabel for accessibility) -->
 <keepui-button variant="ghost" size="auto" ariaLabel="Close dialog">
   <svg slot="leading" …>…</svg>
 </keepui-button>
 ```
 
-**Inputs:**
+#### Inputs
 
 | Input | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | Visual style. |
-| `size` | `'md' \| 'auto'` | `'md'` | `md`: 160 px wide, 40 px tall. `auto`: padding-driven width. |
-| `shape` | `'pill' \| 'rounded'` | `'pill'` | Border-radius style. |
-| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML `type` attribute. |
-| `disabled` | `boolean` | `false` | Disables the button. |
-| `loading` | `boolean` | `false` | Shows spinner, disables button, sets `aria-busy="true"`. |
-| `fullWidth` | `boolean` | `false` | Expands the button to 100% container width. |
-| `ariaLabel` | `string` | `''` | Accessible label. Required for icon-only buttons. |
-
-**Outputs:**
-
-| Output | Type | Description |
+| `variant` | `ButtonVariant` | `'primary'` | Visual style of the button. |
+| `size` | `ButtonSize` | `'md'` | Size mode.
+- `md` → fixed 160 px wide, 40 px tall.
+- `auto` → padding-driven width, 40 px tall. |
+  | `shape` | `ButtonShape` | `'pill'` | Border-radius style. |
+  | `type` | `ButtonType` | `'button'` | HTML `type` attribute of the inner `<button>`. |
+  | `disabled` | `boolean` | `false` | Disables the button when `true`. |
+  | `loading` | `boolean` | `false` | Replaces the content with an animated spinner and sets `aria-busy`.
+  Also disables the button until the operation completes. |
+  | `fullWidth` | `boolean` | `false` | Expands the button to fill its container width. |
+  | `ariaLabel` | `string` | `''` | Accessible label for icon-only buttons.
+  When provided, sets the `aria-label` attribute on the inner `<button>`. |
+
+#### Outputs
+
+| Output | Emitter type | Description |
 |---|---|---|
-| `clicked` | `void` | Emitted on click (only when enabled and not loading). |
+| `clicked` | `OutputEmitterRef<void>` | Emitted when the button is clicked and is not disabled or loading. |
 
-**Slots:**
+#### Content slots (`ng-content`)
 
 | Slot | Description |
 |---|---|
-| `slot="leading"` | Element placed before the label (e.g. icon). Hidden during loading. |
-| `slot="trailing"` | Element placed after the label (e.g. icon). Hidden during loading. |
-| *(default)* | Button label / content. |
+| *(default)* | Main projected content |
+| `[slot='leading']` | Leading icon/element. Hidden while `loading`. |
+| `[slot='trailing']` | Trailing icon/element. Hidden while `loading`. |
 
 ---
+### 5.2 `CardComponent`
 
-### `<keepui-card>`
+**Selector:** `keepui-card`
+**Import:** `import { CardComponent } from '@keepui/ui';`
 
-Versatile container with variant, padding, color, clickable, selected, and scrollable states.
+Contenedor versátil con soporte de variante, padding, color, estado clickable,
+seleccionado y scrollable.
 
-```html
-<!-- Basic -->
-<keepui-card>Content</keepui-card>
+`padding="screen"` aplica padding lateral y superior pero omite el inferior
+intencionadamente para que el contenido parezca continuar más allá del área visible,
+invitando al usuario a hacer scroll. Un `div` espaciador se inserta automáticamente
+al final del contenido proyectado: cuando el usuario llega al fondo, el espaciador
+reproduce el padding inferior correcto sin que el consumidor deba declararlo.
 
-<!-- Outlined with large padding -->
-<keepui-card variant="outlined" padding="lg">…</keepui-card>
+```html
+<keepui-card>Contenido</keepui-card>
 
-<!-- Clickable + selectable -->
-<keepui-card [clickable]="true" [selected]="isSelected()" (clicked)="select()">
-  Option A
+<keepui-card variant="flat" padding="lg" [clickable]="true" (clicked)="onSelect()">
+  Card clicable
 </keepui-card>
 
-<!-- Full-height scrollable panel -->
 <div class="h-screen overflow-hidden">
   <keepui-card padding="screen" [scrollable]="true" [fullHeight]="true">
-    Long list content…
+    Contenido largo — el padding inferior se gestiona automáticamente
   </keepui-card>
 </div>
 ```
 
-> `padding="screen"` applies lateral and top padding but omits the bottom intentionally so content appears to continue beyond the visible area. A spacer `<div>` is inserted automatically at the end of the projected content — when the user scrolls to the bottom, the correct bottom gap appears without extra markup from the consumer.
-
-**Inputs:**
+#### Inputs
 
 | Input | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `'flat' \| 'outlined'` | `'outlined'` | With or without border. |
-| `padding` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'screen'` | `'md'` | Internal padding. |
-| `colors` | `'primary' \| 'secondary'` | `'primary'` | Background surface token. |
-| `clickable` | `boolean` | `false` | Enables hover, focus ring, and button role. |
-| `selected` | `boolean` | `false` | Applies brand border when active. |
-| `scrollable` | `boolean` | `false` | Activates `overflow-y-auto`. Combine with `fullHeight`. |
-| `fullHeight` | `boolean` | `false` | Applies `h-full` to host and inner container. |
+| `variant` | `CardVariant` | `'outlined'` |  |
+| `padding` | `CardPadding` | `'md'` |  |
+| `colors` | `CardColors` | `'primary'` |  |
+| `clickable` | `boolean` | `false` |  |
+| `selected` | `boolean` | `false` |  |
+| `scrollable` | `boolean` | `false` |  |
+| `fullHeight` | `boolean` | `false` |  |
 
-**Outputs:**
+#### Outputs
 
-| Output | Type | Description |
+| Output | Emitter type | Description |
 |---|---|---|
-| `clicked` | `void` | Emitted on click or Enter / Space (requires `clickable`). |
+| `clicked` | `OutputEmitterRef<void>` |  |
 
 ---
+### 5.3 `IconActionButtonComponent`
 
-### `<keepui-icon>`
+**Selector:** `keepui-icon-action-button`
+**Import:** `import { IconActionButtonComponent } from '@keepui/ui';`
 
-Renders an SVG symbol via `<use href="#name">`. The consuming application is responsible for registering SVG symbols in the DOM (e.g. with an `IconRegistryService`).
+Circular icon-only action button with `default` and `danger` variants,
+loading state, and full accessibility support.
 
-The icon color is inherited from `currentColor` — apply any Tailwind text-color class directly to `keepui-icon`.
+Because this button renders no visible text, `ariaLabel` is **required** to
+satisfy WCAG 2.1 SC 4.1.2 (Name, Role, Value).
+
+The icon color is inherited automatically via `currentColor` from the button's
+text color, so SVG symbols defined with `stroke="currentColor"` will adapt to
+both variants and themes without extra classes.
 
 ```html
-<!-- Decorative — aria-hidden="true" applied automatically -->
-<keepui-icon name="check-icon" [size]="20" />
+<keepui-icon-action-button icon="edit-icon" ariaLabel="Editar" />
 
-<!-- Semantic standalone icon — role="img" + aria-label applied -->
-<keepui-icon name="close-icon" ariaLabel="Close dialog" />
+<keepui-icon-action-button
+  icon="trash-icon"
+  variant="danger"
+  ariaLabel="Eliminar elemento"
+  [loading]="isDeleting()"
+/>
+```
 
-<!-- Inside a button slot -->
-<keepui-button variant="primary" size="auto">
-  <keepui-icon slot="leading" name="add-icon" [size]="16" />
-  New item
-</keepui-button>
+#### Inputs
 
-<!-- Custom color -->
-<keepui-icon name="star-icon" [size]="24" class="text-ku-action-primary" />
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `icon` | `unknown` | — | ID of the SVG symbol to render (without the `#` prefix). |
+| `ariaLabel` | `unknown` | — | Accessible label for the button. Always required — icon-only buttons must
+ have a programmatic name for screen readers (WCAG 2.1 SC 4.1.2). |
+| `variant` | `IconActionButtonVariant` | `'default'` | Visual style variant. |
+| `iconSize` | `number` | `20` | Size of the inner icon in pixels. |
+| `type` | `IconActionButtonType` | `'button'` | HTML `type` attribute of the inner `<button>`. |
+| `disabled` | `boolean` | `false` | Disables the button when `true`. |
+| `loading` | `boolean` | `false` | Shows an animated spinner and disables the button.
+ Also sets `aria-busy="true"` on the element. |
+
+---
+### 5.4 `IconComponent`
+
+**Selector:** `keepui-icon`
+**Import:** `import { IconComponent } from '@keepui/ui';`
+
+Generic SVG sprite icon renderer.
+
+Renders a `<use href="#name">` reference pointing to an SVG symbol pre-registered
+in the DOM by the consuming application (e.g. via `IconRegistryService`).
+
+Accessibility:
+- When used decoratively (default), the SVG carries `aria-hidden="true"` automatically.
+- When used as a standalone meaningful icon, supply an `ariaLabel` — the SVG will
+  receive `role="img"` and `aria-label` accordingly.
+
+```html
+<!-- Decorative — hidden from screen readers -->
+<keepui-icon name="check-icon" [size]="20" aria-hidden="true" />
+
+<!-- Meaningful standalone icon -->
+<keepui-icon name="close-icon" ariaLabel="Cerrar" />
 ```
 
-**Inputs:**
+#### Inputs
 
 | Input | Type | Default | Description |
 |---|---|---|---|
-| `name` ★ | `string` | — | ID of the SVG symbol (without `#`). Required. |
+| `name` | `unknown` | — | ID of the SVG symbol to render (without the `#` prefix). |
 | `size` | `number` | `24` | Width and height of the icon in pixels. |
 | `viewBox` | `string` | `'0 0 24 24'` | `viewBox` attribute forwarded to the `<svg>` element. |
-| `ariaLabel` | `string` | `''` | When provided: sets `role="img"` and `aria-label`. When omitted: `aria-hidden="true"` is applied automatically. |
+| `ariaLabel` | `string` | `''` | Accessible label for standalone icons.
+When provided, sets `role="img"` and `aria-label` on the SVG.
+When omitted, the SVG is marked `aria-hidden="true"` (decorative). |
+
+---
+### 5.5 `ImagePreviewComponent`
 
-> ★ Required input.
+**Selector:** `keepui-image-preview`
+**Import:** `import { ImagePreviewComponent } from '@keepui/ui';`
+
+Standalone component that allows the user to pick and preview an image.
+
+This component is fully platform-agnostic. It delegates file picking to
+whatever `FilePort` implementation is provided via `FILE_PORT`.
+
+UI strings are fully internationalised via Transloco (scope `'keepui'`).
+Call `provideKeepUiI18n()` in your `app.config.ts` and use
+`KeepUiLanguageService.setLanguage(lang)` to change locale at runtime.
+
+Usage:
+```html
+<keepui-image-preview />
+```
+
+Prerequisites — register providers in `app.config.ts`:
+- Web:      `provideKeepUi()` + `provideKeepUiI18n()`
+- Capacitor: `provideKeepUiCapacitor()` + `provideKeepUiI18n()`
+
+#### Public signals (readable from outside)
+
+| Signal | Type | Description |
+|---|---|---|
+| `imageUrl` | `Signal<string | null>` | URL of the selected image, ready to bind to `[src]`. |
+| `error` | `Signal<string | null>` | Error message if the last pick operation failed. |
+| `loading` | `Signal<boolean>` | True while the pick operation is in progress. |
 
 ---
+### 5.6 `SignalDropdownComponent`
 
-### `<keepui-icon-action-button>`
+**Selector:** `keepui-signal-dropdown`
+**Import:** `import { SignalDropdownComponent } from '@keepui/ui';`
 
-Circular icon-only action button with `default` and `danger` variants, loading state, and full accessibility support.
+Signal-based accessible dropdown / select component.
 
-`ariaLabel` is **required** because the button contains no visible text (WCAG 2.1 SC 4.1.2). The icon color is inherited automatically via `currentColor` from the button's text color.
+Fully platform-agnostic — no native API usage. The panel opens in `fixed`
+position so it is never clipped by overflow-hidden ancestors. It repositions
+itself automatically on scroll and resize.
+
+The `value` and `touched` properties are `model()` signals so the component
+integrates seamlessly with Angular signal-based forms.
 
 ```html
-<!-- Default variant -->
-<keepui-icon-action-button icon="edit-icon" ariaLabel="Edit" />
+<keepui-signal-dropdown
+  label="País"
+  placeholder="Selecciona un país"
+  [options]="countries"
+  [(value)]="selectedCountry"
+/>
+```
 
-<!-- Danger variant -->
-<keepui-icon-action-button
-  icon="trash-icon"
-  variant="danger"
-  ariaLabel="Delete item"
+#### Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `''` | Optional label text rendered above the dropdown. |
+| `placeholder` | `string` | `''` | Placeholder shown when no value is selected. |
+| `options` | `unknown` | — | Array of options to display in the panel. |
+| `width` | `SignalDropdownWidth` | `'full'` | Layout width of the wrapper. |
+| `required` | `boolean` | `false` | Marks the field as required. Adds `aria-required` and a visual asterisk. |
+| `errorMessage` | `string` | `''` | Human-readable error message shown below the dropdown. Takes precedence over `errors[0]`. |
+| `errors` | `readonly string[]` | `[]` | Array of error strings. The first item is displayed when `errorMessage` is empty.
+ Set together with `invalid=true` to trigger the error state. |
+| `selectId` | `string` | ``ku-dropdown-${Math.random(` | Stable `id` used to link the `<label>` with the trigger `<button>`.
+ A random suffix is generated by default. |
+| `disabled` | `boolean` | `false` | Disables the dropdown. |
+| `invalid` | `boolean` | `false` | Forces the error visual state regardless of the `touched` model.
+ Useful for external form validation. |
+
+#### Outputs
+
+| Output | Emitter type | Description |
+|---|---|---|
+| `valueChange` | `OutputEmitterRef<T | null>` | Emitted when the selected value changes. |
+
+---
+### 5.7 `SignalTextareaComponent`
+
+**Selector:** `keepui-signal-textarea`
+**Import:** `import { SignalTextareaComponent } from '@keepui/ui';`
+
+Signal-based accessible textarea component with character counter,
+resize control, and integrated error display.
+
+The `value` and `touched` properties are `model()` signals so the component
+integrates seamlessly with Angular signal-based forms.
+
+```html
+<keepui-signal-textarea
+  label="Descripción"
+  placeholder="Escribe aquí…"
+  [rows]="5"
+  [maxLength]="500"
+  [(value)]="description"
 />
+```
 
-<!-- Loading state -->
-<keepui-icon-action-button
-  icon="upload-icon"
-  ariaLabel="Upload file"
-  [loading]="isUploading()"
+#### Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `label` | `string` | `''` | Optional label text rendered above the textarea. |
+| `placeholder` | `string` | `''` | Placeholder passed to the underlying `<textarea>`. |
+| `rows` | `number` | `4` | Number of visible text rows. |
+| `width` | `SignalTextareaWidth` | `'full'` | Layout width of the wrapper. |
+| `resize` | `SignalTextareaResize` | `'none'` | CSS `resize` behaviour. |
+| `required` | `boolean` | `false` | Marks the field as required. |
+| `errorMessage` | `string` | `''` | Human-readable error message. Takes precedence over `errors[0]`. |
+| `errors` | `readonly string[]` | `[]` | Array of error strings. The first item is displayed when `errorMessage` is empty.
+ Set together with `invalid=true` to trigger the error state. |
+| `textareaId` | `string` | ``ku-textarea-${Math.random(` | Stable `id` used to link the `<label>` with the `<textarea>`.
+ A random suffix is generated by default. |
+| `disabled` | `boolean` | `false` | Disables the textarea. |
+| `maxLength` | `number | undefined` | `undefined` | Maximum number of characters allowed. Shows a character counter when set. |
+| `invalid` | `boolean` | `false` | Forces the error visual state regardless of the `touched` model.
+ Useful for external form validation. |
+
+---
+### 5.8 `SignalTextInputComponent`
+
+**Selector:** `keepui-signal-text-input`
+**Import:** `import { SignalTextInputComponent } from '@keepui/ui';`
+
+Signal-based accessible text input supporting all common HTML input types,
+leading/trailing icons, a trailing content slot, and a built-in
+password-visibility toggle (when `type="password"`).
+
+The `value` and `touched` properties are `model()` signals so the component
+integrates seamlessly with Angular signal-based forms.
+
+Password toggle labels are translated via Transloco (scope `'keepui'`).
+Call `provideKeepUiI18n()` in your `app.config.ts` to activate i18n.
+
+```html
+<keepui-signal-text-input
+  label="Email"
+  type="email"
+  placeholder="usuario@ejemplo.com"
+  leadingIcon="mail-icon"
+  [(value)]="email"
 />
 
-<!-- Disabled -->
-<keepui-icon-action-button icon="share-icon" ariaLabel="Share" [disabled]="true" />
+<!-- Password with toggle -->
+<keepui-signal-text-input
+  label="Contraseña"
+  type="password"
+  [(value)]="password"
+/>
 ```
 
-**Inputs:**
+#### Inputs
 
 | Input | Type | Default | Description |
 |---|---|---|---|
-| `icon` ★ | `string` | — | ID of the SVG symbol (without `#`). Required. |
-| `ariaLabel` ★ | `string` | — | Accessible label. Required (no visible text). |
-| `variant` | `'default' \| 'danger'` | `'default'` | Visual style. |
-| `iconSize` | `number` | `20` | Size of the inner icon in pixels. |
-| `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | HTML `type` attribute. |
-| `disabled` | `boolean` | `false` | Disables the button. |
-| `loading` | `boolean` | `false` | Shows spinner, disables button, sets `aria-busy="true"`. |
-
-> ★ Required input.
+| `label` | `string` | `''` | Optional label text rendered above the input. |
+| `placeholder` | `string` | `''` | Placeholder passed to the underlying `<input>`. |
+| `type` | `SignalTextInputType` | `'text'` | HTML `type` attribute. Use `'password'` to enable the visibility toggle. |
+| `width` | `SignalTextInputWidth` | `'full'` | Layout width of the wrapper. |
+| `leadingIcon` | `string` | `''` | Name of the leading icon (SVG symbol ID). Leave empty for no icon. |
+| `trailingIcon` | `string` | `''` | Name of the trailing icon (SVG symbol ID). Ignored when `type="password"`. |
+| `hasTrailingSlot` | `boolean` | `false` | When `true`, a slot for custom trailing content is enabled
+ (projects `[trailingSlot]` content). Overrides `trailingIcon`. |
+| `required` | `boolean` | `false` | Marks the field as required. Adds `aria-required` and a visual asterisk. |
+| `showRequiredIndicator` | `boolean` | `true` | When `false`, hides the visual asterisk even if `required=true`. |
+| `errorMessage` | `string` | `''` | Human-readable error message. Takes precedence over `errors[0]`. |
+| `errors` | `readonly string[]` | `[]` | Array of error strings. The first item is displayed when `errorMessage` is empty.
+ Set together with `invalid=true` to trigger the error state. |
+| `inputId` | `string` | ``ku-text-input-${Math.random(` | Stable `id` used to link the `<label>` with the `<input>`.
+ A random suffix is generated by default. |
+| `disabled` | `boolean` | `false` | Disables the input. |
+| `invalid` | `boolean` | `false` | Forces the error visual state regardless of the `touched` model.
+ Useful for external form validation. |
 
 ---
 
-### `<keepui-image-preview>`
+## 6. Type definitions
 
-Standalone image picker and preview. Delegates file selection to the registered `FilePort` implementation — works identically on web and native (Capacitor) without any code change. UI strings are fully internationalised via Transloco.
+> Visual style variant of the button.
 
-```html
-<keepui-image-preview />
+```ts
+type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
 ```
 
-No inputs or outputs. Exposes three readable signals for advanced use cases:
+> Size mode of the button.
+- `md`: fixed width (160 px) and height (40 px).
+- `auto`: height fixed (40 px), width grows with padding to fit content.
 
-| Signal | Type | Description |
-|---|---|---|
-| `imageUrl` | `Signal<string \| null>` | Data URL of the selected image, ready to bind to `[src]`. |
-| `error` | `Signal<string \| null>` | Error message if the last pick operation failed. |
-| `loading` | `Signal<boolean>` | `true` while the pick operation is in progress. |
+```ts
+type ButtonSize = 'md' | 'auto';
+```
+
+> Border-radius style of the button.
+- `pill`: fully rounded (`rounded-full`).
+- `rounded`: moderately rounded (`rounded-2xl`).
+
+```ts
+type ButtonShape = 'pill' | 'rounded';
+```
 
-**Prerequisites** — register in `app.config.ts`:
+> HTML `type` attribute for the underlying `<button>` element.
 
 ```ts
-// Web
-provideKeepUi()
-provideKeepUiI18n({ defaultLang: 'en' })
+type ButtonType = 'button' | 'submit' | 'reset';
+```
 
-// Capacitor
-provideKeepUiCapacitor()
-provideKeepUiI18n({ defaultLang: 'en' })
+```ts
+type CardVariant = 'flat' | 'outlined';
 ```
 
----
+```ts
+type CardPadding = 'none' | 'sm' | 'md' | 'lg' | 'screen';
+```
+
+```ts
+type CardColors = 'primary' | 'secondary';
+```
+
+```ts
+type IconActionButtonVariant = 'default' | 'danger';
+```
+
+```ts
+type IconActionButtonType = 'button' | 'submit' | 'reset';
+```
+
+> Layout width of the dropdown wrapper.
+
+```ts
+type SignalDropdownWidth = 'full' | 'half' | 'auto';
+```
+
+> Layout width of the text input wrapper.
+
+```ts
+type SignalTextInputWidth = 'full' | 'half' | 'auto';
+```
 
-## i18n
+> HTML `type` attribute for the underlying `<input>` element.
+Use `'password'` to enable the built-in show/hide toggle.
 
-KeepUI uses [`@jsverse/transloco`](https://jsverse.github.io/transloco/) with the scope `'keepui'`.
+```ts
+type SignalTextInputType = | 'text'
+  | 'email'
+  | 'tel'
+  | 'number'
+  | 'password'
+  | 'search'
+  | 'url'
+  | 'date';
+```
 
-**Supported languages:** `en` · `es` · `de`
+> Layout width of the textarea wrapper.
+
+```ts
+type SignalTextareaWidth = 'full' | 'half' | 'auto';
+```
 
-**Change locale at runtime:**
+> CSS `resize` behaviour of the `<textarea>` element.
+- `none` → not resizable (default).
+- `vertical` → user can drag to resize vertically.
+- `horizontal` → user can drag to resize horizontally.
+- `both` → user can drag freely.
 
 ```ts
-import { KeepUiLanguageService, KeepUiLanguage } from '@keepui/ui';
+type SignalTextareaResize = 'none' | 'vertical' | 'horizontal' | 'both';
+```
+
+---
 
-@Component({ … })
-export class MyComponent {
-  private readonly langService = inject(KeepUiLanguageService);
+## 7. Interfaces & models
 
-  switch(lang: KeepUiLanguage) {
-    this.langService.setLanguage(lang);
-  }
+### `FileResult`
+
+Represents the result of a file/image selection operation.
+This model is platform-agnostic and used across all adapters.
+
+```ts
+interface FileResult {
+  /** A data URL (e.g. `data:image/jpeg;base64,...`) or an HTTP/file URL ready to display. */
+  dataUrl: string;
+  /** MIME type of the selected file, e.g. `image/jpeg`. */
+  mimeType: string;
+}
+```
+
+### `FilePort`
+
+Platform-agnostic port (interface) for file/image selection.
+
+Provide a concrete implementation via the `FILE_PORT` injection token.
+- Web: `WebFileService`
+- Capacitor: `CapacitorFileService` (from `@keepui/ui/capacitor`)
+
+```ts
+interface FilePort {
+  /** Opens a platform-native image picker and returns the selected image.
+Resolves with a `FileResult` containing a displayable URL and MIME type.
+Rejects if the user cancels or an error occurs. */
+  pickImage(): Promise<FileResult>;
 }
 ```
 
 ---
 
-## Theming
+## 8. Services
 
-KeepUI uses CSS custom properties for all design tokens. The `data-theme` attribute on `<html>` switches between `light` (default) and `dark`.
+### `KeepUiLanguageService`
 
-**Switch theme at runtime:**
+Service that exposes a public API for changing the active language of all
+KeepUI components at runtime.
 
+### Usage
 ```ts
-document.documentElement.setAttribute('data-theme', 'dark');
+// Inject anywhere in the host application
+const lang = inject(KeepUiLanguageService);
+
+// Switch to Spanish
+lang.setLanguage('es');
+
+// Read the active language
+console.log(lang.activeLanguage()); // 'es'
 ```
 
-**Override tokens in your own CSS:**
+Register via `provideKeepUiI18n()` in `app.config.ts`.
+
+**Public properties:**
+
+| Property | Type | Description |
+|---|---|---|
+| `activeLanguage` | — | Signal that reflects the currently active KeepUI locale. |
+| `availableLanguages` | `readonly KeepUiLanguage[]` | Ordered list of all supported locales. |
+
+**Public methods:**
+
+- `setLanguage(lang: KeepUiLanguage): void` — Changes the active language for all KeepUI components.
+
+### `WebFileService`
+
+Web implementation of `FilePort`.
+
+Uses a hidden `<input type="file">` and the `FileReader` API to let the user
+pick an image from the file system in a browser environment.
+
+This implementation has no dependency on Capacitor or any native plugin.
+
+**Public methods:**
+
+- `pickImage(): Promise<FileResult>` —
+
+---
+
+## 9. Internationalisation (i18n)
+
+Use typed constants instead of raw strings:
+
+```ts
+import { KEEPUI_TRANSLATION_KEYS as T } from '@keepui/ui';
+
+// Example
+translocoService.translate(T.IMAGE_PREVIEW.SELECT_IMAGE);
+```
+
+**Supported languages:** `en` (English), `es` (Spanish), `de` (German)
+
+**Translation keys:**
+
+| Constant path | Translation key |
+|---|---|
+| `IMAGE_PREVIEW.SELECT_IMAGE` | `imagePreview.selectImage` |
+| `IMAGE_PREVIEW.LOADING` | `imagePreview.loading` |
+| `IMAGE_PREVIEW.PREVIEW_ALT` | `imagePreview.previewAlt` |
+| `IMAGE_PREVIEW.ERROR_UNEXPECTED` | `imagePreview.errorUnexpected` |
+| `SIGNAL_TEXT_INPUT.SHOW_PASSWORD` | `signalTextInput.showPassword` |
+| `SIGNAL_TEXT_INPUT.HIDE_PASSWORD` | `signalTextInput.hidePassword` |
+
+**Changing language at runtime:**
+
+```ts
+import { KeepUiLanguageService } from '@keepui/ui';
+
+const lang = inject(KeepUiLanguageService);
+lang.setLanguage('es');  // 'en' | 'es' | 'de'
+```
+
+---
+
+## 10. CSS design tokens
+
+Override any variable in your CSS to customise the theme:
 
 ```css
 :root {
-  --ku-action-primary: #6366f1;
+  --keepui-primary:            #3b82f6;
+  --keepui-primary-hover:      #2563eb;
+  --keepui-primary-active:     #1d4ed8;
+  --keepui-primary-foreground: #ffffff;
+  --keepui-background:         #f5f5f5;
+  --keepui-surface:            #ffffff;
+  --keepui-surface-hover:      #f0f0f0;
+  --keepui-border:             #e0e0e0;
+  --keepui-border-strong:      #cccccc;
+  --keepui-text:               #1f2937;
+  --keepui-text-muted:         #6b7280;
+  --keepui-text-disabled:      #9ca3af;
+  --keepui-error:              #dc2626;
+  --keepui-error-foreground:   #ffffff;
+  --keepui-success:            #16a34a;
+  --keepui-warning:            #f59e0b;
+  --keepui-shadow-sm:          0 1px 3px rgba(0,0,0,.12);
+  --keepui-shadow-md:          0 3px 6px rgba(0,0,0,.15);
+  --keepui-shadow-lg:          0 6px 12px rgba(0,0,0,.18);
 }
 
 [data-theme="dark"] {
-  --ku-action-primary: #818cf8;
+  --keepui-primary:            #60a5fa;
+  --keepui-primary-foreground: #0f172a;
+  --keepui-background:         #0f172a;
+  --keepui-surface:            #1e293b;
+  --keepui-surface-hover:      #334155;
+  --keepui-border:             #334155;
+  --keepui-border-strong:      #475569;
+  --keepui-text:               #f1f5f9;
+  --keepui-text-muted:         #94a3b8;
+  --keepui-text-disabled:      #64748b;
+  --keepui-error:              #f87171;
+  --keepui-error-foreground:   #0f172a;
+  --keepui-success:            #4ade80;
+  --keepui-warning:            #fbbf24;
 }
 ```
 
-Refer to the bundled `themes.css` file for the full list of available tokens.
-
 ---
 
-## Architecture Notes
+## 11. Tailwind utility classes
 
-### Port/Adapter Pattern
+Generated automatically after `@import "@keepui/ui/styles"` with Tailwind v4:
 
 ```
-ImagePreviewComponent
-       │
-       │ inject(FILE_PORT)
-       ▼
-   FilePort (interface)
-       │
-   ┌───┴──────────────────┐
-   │                      │
-WebFileService    CapacitorFileService
-(browser <input>)  (@capacitor/camera)
+bg-keepui-background      bg-keepui-surface        bg-keepui-surface-hover
+bg-keepui-primary         bg-keepui-primary-hover  bg-keepui-primary-active
+bg-keepui-error           bg-keepui-success        bg-keepui-warning
+
+text-keepui-text          text-keepui-text-muted   text-keepui-text-disabled
+text-keepui-primary       text-keepui-primary-fg   text-keepui-error
+
+border-keepui-border      border-keepui-border-strong  border-keepui-primary
+
+shadow-keepui-sm          shadow-keepui-md         shadow-keepui-lg
+
+focus-visible:ring-keepui-primary
 ```
 
-- Components depend only on the `FilePort` interface via the `FILE_PORT` injection token.
-- `provideKeepUi()` registers `WebFileService`.
-- `provideKeepUiCapacitor()` registers `CapacitorFileService`.
-- Capacitor dependencies are **not** pulled into web builds.
+---
+### 5.10 `TabGroupComponent`
 
-### Secondary Entrypoint
+**Selector:** `keepui-tab-group`
+**Import:** `import { TabGroupComponent, Tab, TabGroupVariant } from '@keepui/ui';`
 
-`@keepui/ui/capacitor` is a secondary ng-packagr entrypoint compiled alongside the main package. Keeping it separate means Capacitor dependencies are never included in web-only builds.
+Accessible pill-style tab group implementing the WAI-ARIA `tablist` pattern.
+Supports icons, disabled tabs, keyboard navigation (arrow keys, `Home`, `End`)
+and two visual variants. No internal i18n strings — tab labels are provided
+by the consumer.
 
-### Types
+```html
+<!-- Default variant -->
+<keepui-tab-group
+  [tabs]="tabs"
+  [selectedTabId]="activeTab"
+  (tabChange)="activeTab = $event"
+  ariaLabel="Main sections"
+/>
 
-Every component that exposes custom TypeScript types places those types in a sibling `<component>.types.ts` file and re-exports them from the main entrypoint. Import them directly from `@keepui/ui`:
+<!-- Filled variant -->
+<keepui-tab-group
+  variant="filled"
+  [tabs]="tabs"
+  [selectedTabId]="activeTab"
+  (tabChange)="activeTab = $event"
+/>
+```
 
 ```ts
-import {
-  ButtonVariant, ButtonSize, ButtonShape, ButtonType,
-  CardVariant, CardPadding, CardColors,
-  IconActionButtonVariant, IconActionButtonType,
-} from '@keepui/ui';
+readonly tabs: Tab[] = [
+  { id: 'home',     label: 'Home' },
+  { id: 'profile',  label: 'Profile', icon: 'user-icon' },
+  { id: 'settings', label: 'Settings', disabled: true },
+];
 ```
 
+#### Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `tabs` | `Tab[]` | *(required)* | List of tabs to render. |
+| `selectedTabId` | `string` | *(required)* | ID of the currently active tab. |
+| `variant` | `TabGroupVariant` | `'default'` | Visual style: `'default'` or `'filled'`. |
+| `ariaLabel` | `string` | `''` | Accessible label for the `tablist` element. |
+
+#### Outputs
+
+| Output | Emitter type | Description |
+|---|---|---|
+| `tabChange` | `OutputEmitterRef<string>` | Emits the `id` of the selected tab. |
+
+#### `Tab` interface
+
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | ✅ | Unique identifier. |
+| `label` | `string` | ✅ | Visible tab label. |
+| `icon` | `string` | — | SVG symbol ID (without `#`) for an optional icon. |
+| `disabled` | `boolean` | — | When `true`, the tab is not selectable. Default `false`. |
+
+#### Accessibility
+
+- Container: `role="tablist"` with optional `aria-label`.
+- Each button: `role="tab"`, `aria-selected`, `aria-disabled`, managed `tabindex`.
+- Keyboard: `ArrowRight`/`ArrowLeft` (and `Down`/`Up`) navigate between tabs; `Home`/`End` jump to extremes.
+- Focus ring: `focus-visible:ring-2 focus-visible:ring-ku-action-primary`.
+- Touch target: `min-h-[2.75rem]` on every tab button.
+
 ---
+### 5.11 `StepperComponent`
 
-## Testing
+**Selector:** `keepui-stepper`
+**Import:** `import { StepperComponent, StepperStep, StepperSize, StepperOrientation } from '@keepui/ui';`
 
-Use `MockFileService` to test components that depend on `FILE_PORT`:
+Visual step-progress indicator with optional interactive navigation.
+Renders numbered circles connected by animated progress bars. Completed steps
+show a check-mark; the active step is highlighted with a ring; future steps are muted.
+Steps can carry an icon that replaces the number.
 
-```ts
-import { MockFileService, FILE_PORT } from '@keepui/ui';
+```html
+<!-- Read-only progress indicator -->
+<keepui-stepper [steps]="steps" [activeIndex]="1" />
+
+<!-- Interactive (allows going back to completed steps) -->
+<keepui-stepper
+  [steps]="steps"
+  [activeIndex]="currentStep"
+  (stepChange)="currentStep = $event"
+  ariaLabel="Registration process"
+/>
 
-TestBed.configureTestingModule({
-  imports: [ImagePreviewComponent],
-  providers: [{ provide: FILE_PORT, useClass: MockFileService }],
-});
+<!-- Small, vertical -->
+<keepui-stepper
+  [steps]="steps"
+  [activeIndex]="currentStep"
+  size="sm"
+  orientation="vertical"
+/>
 ```
 
-`MockFileService` resolves successfully by default. Set `nextError` to test error paths:
-
 ```ts
-const mock = TestBed.inject(FILE_PORT) as MockFileService;
-mock.nextError = new Error('Camera cancelled');
+readonly steps: StepperStep[] = [
+  { id: '1', label: 'Account' },
+  { id: '2', label: 'Profile', icon: 'user-icon' },
+  { id: '3', label: 'Plan' },
+  { id: '4', label: 'Confirm', disabled: true },
+];
 ```
 
----
+#### Inputs
 
-## Building
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `steps` | `StepperStep[]` | *(required)* | List of steps to render. |
+| `activeIndex` | `number` | `0` | Zero-based index of the currently active step. |
+| `size` | `StepperSize` | `'md'` | Size of step circles and connectors: `'md'` or `'sm'`. |
+| `orientation` | `StepperOrientation` | `'horizontal'` | Layout direction: `'horizontal'` or `'vertical'`. |
+| `ariaLabel` | `string` | `''` | Accessible label for the `<nav>` element. |
 
-```bash
-# Production build (APF, partial compilation):
-npm run build
+#### Outputs
 
-# Development build (without schematics):
-npm run build:dev
+| Output | Emitter type | Description |
+|---|---|---|
+| `stepChange` | `OutputEmitterRef<number>` | Emits the zero-based index of the clicked step (completed or active steps only). |
 
-# Schematics only:
-npm run build:schematics
+#### `StepperStep` interface
 
-# Run unit tests:
-npm test
-```
+| Property | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | ✅ | Unique identifier. |
+| `label` | `string` | ✅ | Label shown below the step circle. |
+| `icon` | `string` | — | SVG symbol ID (without `#`) rendered inside the circle instead of the step number. |
+| `disabled` | `boolean` | — | When `true`, the step is not interactive. Default `false`. |
 
-Output is placed in `dist/keep-ui/` following Angular Package Format.
+#### Accessibility
+
+- Container: `<nav>` with optional `aria-label`.
+- List: `role="list"` / `role="listitem"` with `aria-current="step"` on the active item.
+- Completed and active steps render as `<button>` elements with `aria-label` equal to the step label.
+- Future and disabled steps render as inert `<span>` elements.
+- Focus ring: `focus-visible:ring-2 focus-visible:ring-ku-action-primary`.
+- Touch target: `min-h-[2.75rem] min-w-[2.75rem]` on every interactive step bubble.
 
 ---
 
-## Publishing to npm
+## 12. Integration checklist
 
-```bash
-npm run build
-cd dist/keep-ui
-npm publish --access public
-```
+- [ ] `@keepui/ui` installed in `package.json`
+- [ ] `@import "@keepui/ui/styles"` in global stylesheet
+- [ ] Tailwind v4 configured (via `@tailwindcss/postcss` or `@tailwindcss/vite`)
+- [ ] `provideKeepUi()` **or** `provideKeepUiCapacitor()` registered in `app.config.ts`
+- [ ] `provideKeepUiI18n()` registered in `app.config.ts`
+- [ ] Components imported individually in each standalone component or NgModule
+- [ ] `[data-theme="dark"]` toggle wired if dark mode switching is needed
+- [ ] `KeepUiLanguageService.setLanguage()` called if runtime i18n is needed
+
+---
 
-Ensure `package.json` has the correct `name`, `version`, and `peerDependencies` before publishing.
+## 13. What NOT to do
 
+- Do **not** import from `@keepui/ui/src/lib/...` — only from `@keepui/ui` or `@keepui/ui/capacitor`.
+- Do **not** call both `provideKeepUi()` and `provideKeepUiCapacitor()`.
+- Do **not** hardcode `FILE_PORT` implementations inside components — always use the token.
+- Do **not** skip `@import "@keepui/ui/styles"` — without it, all theme utility classes are missing.
+- Do **not** import `@capacitor/*` in code that also imports `@keepui/ui` core.