@konce-pt/angular 0.3.0 → 0.5.0

package/README.md

@@ -32,15 +32,16 @@
 - 🎨 **100% tokenized** — every style is a `var(--kpt-*)` CSS custom property. Light/dark theme, neutral OKLCH palette. Swap the brand by swapping one token layer.
 - 🧩 **Standalone components** — no NgModules. Import only what you use; tree-shakeable.
 - ♿ **Built on Angular CDK** — overlays, a11y, focus management, virtual scrolling.
+- 🌍 **i18n built in** — English (default) & Polish out of the box, runtime locale switch, add any language with one JSON.
 
 ## Installation
 
 ```bash
-npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles
+npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
 # or: pnpm add / yarn add
 ```
 
-Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms`, `@angular/cdk` (all `^22`).
+`@angular/core`, `@angular/common` and `@angular/forms` (all `^22`) are already in an Angular app; **`@angular/cdk` (`^22`) is a required peer** — overlay components (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu…) build on the CDK Overlay — so install it explicitly (above). Optional: `@konce-pt/validators` for the Polish-market validators (NIP, REGON, PESEL, IBAN, postal code).
 
 ## Setup
 
@@ -63,9 +64,18 @@ Zoneless bootstrap (Angular 22) lives in your app config — no CSS imports in `
 
 ```ts
 import { provideZonelessChangeDetection } from '@angular/core';
-// providers: [provideZonelessChangeDetection(), /* provideKptTablerIcons() */]
+// import { provideKptI18n } from '@konce-pt/angular';
+// import { provideKptTablerIcons } from '@konce-pt/angular/icons';
+
+providers: [
+  provideZonelessChangeDetection(),   // required (zoneless)
+  // provideKptI18n({ locale: 'pl' }), // optional — UI is English by default; set for Polish/other
+  // provideKptTablerIcons(),          // optional — full Tabler icon set
+]
 ```
 
+The UI language defaults to **English** and works with **zero config** — `provideKptI18n(...)` is optional and only needed for Polish (or a custom language). See [Internationalization](#internationalization-i18n) below.
+
 Dark theme: set `<html data-theme="dark">` (or rely on `prefers-color-scheme`).
 
 > **Why not `import '…css'` in `main.ts`?** Angular CLI (`@angular/build`) turns side-effect CSS imports into a separate stylesheet that isn't linked from `index.html`, so the app builds **without styles**. Use `angular.json → styles[]` instead.
@@ -166,6 +176,40 @@ import { provideKptTablerIcons } from '@konce-pt/angular/icons';
 // providers: [provideKptTablerIcons()]
 ```
 
+## Internationalization (i18n)
+
+Component labels ship in **English (default)** and **Polish**. The `KptI18n` service is `providedIn: 'root'`, so **English works out of the box with no provider**. Call `provideKptI18n(...)` only to start in Polish (or another language), or to register/override dictionaries. All user-facing strings — aria-labels, empty states, paginator, calendars, rich-text menus — read from this signal-based service, so switching locale updates the UI instantly (zoneless-friendly).
+
+```ts
+import { provideKptI18n } from '@konce-pt/angular';
+// providers: [provideKptI18n({ locale: 'pl' })]   // optional — Polish UI (EN is the default)
+```
+
+Switch at runtime:
+
+```ts
+import { inject } from '@angular/core';
+import { KptI18n } from '@konce-pt/angular';
+
+const i18n = inject(KptI18n);
+i18n.setLocale('en');
+```
+
+**Add any language with one JSON** (shape = the `KptMessages` contract; missing keys fall back to English):
+
+```ts
+import de from './i18n/de.json';
+provideKptI18n({ locale: 'de', messages: { de } });
+```
+
+**Override individual labels** of an existing language:
+
+```ts
+provideKptI18n({ messages: { en: { paginator: { rowsPerPage: 'Rows per page:' } } } });
+```
+
+Calendar weekday/month names come from the browser's `Intl` API for the active locale. Per-component label inputs (e.g. `emptyMessage`, `acceptLabel`) still take precedence over the dictionary.
+
 ## Documentation
 
 - **Storybook** — interactive docs for every component.
@@ -192,13 +236,16 @@ import { provideKptTablerIcons } from '@konce-pt/angular/icons';
 - 📊 **Flagowa tabela danych** — sortowanie, filtr, paginacja, virtual scroll, zaznaczanie, przestawianie/zamrażanie kolumn, eksport CSV, szablony komórek.
 - 🎨 **100% na tokenach** — każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
 - 🧩 **Standalone** — bez NgModules, tree-shaking.
+- 🌍 **Wbudowane i18n** — angielski (domyślny) i polski, przełączanie języka w runtime, dowolny język jednym plikiem JSON.
 
 ### Instalacja
 
 ```bash
-npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles
+npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
 ```
 
+`@angular/core`, `@angular/common` i `@angular/forms` (`^22`) są już w aplikacji Angulara; **`@angular/cdk` (`^22`) to wymagany peer** — komponenty overlay (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu…) bazują na CDK Overlay — więc instaluj go jawnie (powyżej). Opcjonalnie: `@konce-pt/validators` (walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy).
+
 ### Konfiguracja
 
 **Angular CLI (zalecane)** — dodaj CSS do tablicy **`styles`** w `angular.json`; kolejność ważna, `src/styles.scss` **na końcu**:
@@ -215,8 +262,45 @@ npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles
 
 > W Angular CLI **nie** używaj `import '…css'` w `main.ts` — bundler wrzuca taki CSS do osobnego, niepodlinkowanego arkusza i aplikacja jest bez stylów. Dla **Vite/webpack** import w `main.ts` działa (tak robi playground).
 
+Zoneless bootstrap (Angular 22) w konfiguracji aplikacji — bez importów CSS w `main.ts`:
+
+```ts
+import { provideZonelessChangeDetection } from '@angular/core';
+// import { provideKptI18n } from '@konce-pt/angular';
+// import { provideKptTablerIcons } from '@konce-pt/angular/icons';
+
+providers: [
+  provideZonelessChangeDetection(),   // wymagane (zoneless)
+  // provideKptI18n({ locale: 'pl' }), // opcjonalne — UI domyślnie po angielsku; ustaw dla PL/innego
+  // provideKptTablerIcons(),          // opcjonalne — pełny zestaw Tabler
+]
+```
+
+Język UI to domyślnie **angielski** i działa **bez żadnej konfiguracji** — `provideKptI18n(...)` jest opcjonalny, potrzebny tylko dla polskiego (lub własnego języka); szczegóły w sekcji i18n niżej.
+
 Motyw ciemny: `<html data-theme="dark">`; nadpisania `--kpt-color-*` w `styles.scss`. Pełny zestaw ikon Tabler: `provideKptTablerIcons()` z `@konce-pt/angular/icons`.
 
+### Internacjonalizacja (i18n)
+
+Etykiety komponentów są dostępne po **angielsku (domyślnie)** i **polsku**. Serwis `KptI18n` jest `providedIn: 'root'`, więc **angielski działa od razu, bez providera**. `provideKptI18n(...)` wołasz tylko, by wystartować po polsku (lub w innym języku) albo zarejestrować/nadpisać słowniki. Wszystkie napisy (aria-label, stany puste, paginator, kalendarze, menu edytora) pochodzą z tego serwisu opartego o sygnały — zmiana języka odświeża UI natychmiast (zoneless).
+
+```ts
+import { provideKptI18n } from '@konce-pt/angular';
+// providers: [provideKptI18n({ locale: 'pl' })]   // opcjonalne — polski interfejs (EN domyślnie)
+```
+
+Przełączanie w runtime: `inject(KptI18n).setLocale('en')`.
+
+**Własny język jednym plikiem JSON** (kształt = kontrakt `KptMessages`; brakujące klucze spadają na EN):
+
+```ts
+import de from './i18n/de.json';
+provideKptI18n({ locale: 'de', messages: { de } });
+```
+
+Nadpisanie pojedynczych etykiet: `provideKptI18n({ messages: { pl: { paginator: { rowsPerPage: 'Na stronie:' } } } })`.
+Nazwy dni/miesięcy w kalendarzach pochodzą z `Intl` wg locale. Inputy etykiet per-komponent (np. `emptyMessage`) mają priorytet nad słownikiem.
+
 ### Komponenty (70+)
 
 Formularze (Signal Forms), przyciski i akcje, layout, nawigacja, dane (z flagową `kpt-data-table`), feedback i overlay — pełna lista w tabeli powyżej. Każdy komponent ma plik `llms.txt` z opisem API obok źródła.

package/dist/README.md

@@ -32,15 +32,16 @@
 - 🎨 **100% tokenized** — every style is a `var(--kpt-*)` CSS custom property. Light/dark theme, neutral OKLCH palette. Swap the brand by swapping one token layer.
 - 🧩 **Standalone components** — no NgModules. Import only what you use; tree-shakeable.
 - ♿ **Built on Angular CDK** — overlays, a11y, focus management, virtual scrolling.
+- 🌍 **i18n built in** — English (default) & Polish out of the box, runtime locale switch, add any language with one JSON.
 
 ## Installation
 
 ```bash
-npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles
+npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
 # or: pnpm add / yarn add
 ```
 
-Peer dependencies: `@angular/core`, `@angular/common`, `@angular/forms`, `@angular/cdk` (all `^22`).
+`@angular/core`, `@angular/common` and `@angular/forms` (all `^22`) are already in an Angular app; **`@angular/cdk` (`^22`) is a required peer** — overlay components (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu…) build on the CDK Overlay — so install it explicitly (above). Optional: `@konce-pt/validators` for the Polish-market validators (NIP, REGON, PESEL, IBAN, postal code).
 
 ## Setup
 
@@ -63,9 +64,18 @@ Zoneless bootstrap (Angular 22) lives in your app config — no CSS imports in `
 
 ```ts
 import { provideZonelessChangeDetection } from '@angular/core';
-// providers: [provideZonelessChangeDetection(), /* provideKptTablerIcons() */]
+// import { provideKptI18n } from '@konce-pt/angular';
+// import { provideKptTablerIcons } from '@konce-pt/angular/icons';
+
+providers: [
+  provideZonelessChangeDetection(),   // required (zoneless)
+  // provideKptI18n({ locale: 'pl' }), // optional — UI is English by default; set for Polish/other
+  // provideKptTablerIcons(),          // optional — full Tabler icon set
+]
 ```
 
+The UI language defaults to **English** and works with **zero config** — `provideKptI18n(...)` is optional and only needed for Polish (or a custom language). See [Internationalization](#internationalization-i18n) below.
+
 Dark theme: set `<html data-theme="dark">` (or rely on `prefers-color-scheme`).
 
 > **Why not `import '…css'` in `main.ts`?** Angular CLI (`@angular/build`) turns side-effect CSS imports into a separate stylesheet that isn't linked from `index.html`, so the app builds **without styles**. Use `angular.json → styles[]` instead.
@@ -166,6 +176,40 @@ import { provideKptTablerIcons } from '@konce-pt/angular/icons';
 // providers: [provideKptTablerIcons()]
 ```
 
+## Internationalization (i18n)
+
+Component labels ship in **English (default)** and **Polish**. The `KptI18n` service is `providedIn: 'root'`, so **English works out of the box with no provider**. Call `provideKptI18n(...)` only to start in Polish (or another language), or to register/override dictionaries. All user-facing strings — aria-labels, empty states, paginator, calendars, rich-text menus — read from this signal-based service, so switching locale updates the UI instantly (zoneless-friendly).
+
+```ts
+import { provideKptI18n } from '@konce-pt/angular';
+// providers: [provideKptI18n({ locale: 'pl' })]   // optional — Polish UI (EN is the default)
+```
+
+Switch at runtime:
+
+```ts
+import { inject } from '@angular/core';
+import { KptI18n } from '@konce-pt/angular';
+
+const i18n = inject(KptI18n);
+i18n.setLocale('en');
+```
+
+**Add any language with one JSON** (shape = the `KptMessages` contract; missing keys fall back to English):
+
+```ts
+import de from './i18n/de.json';
+provideKptI18n({ locale: 'de', messages: { de } });
+```
+
+**Override individual labels** of an existing language:
+
+```ts
+provideKptI18n({ messages: { en: { paginator: { rowsPerPage: 'Rows per page:' } } } });
+```
+
+Calendar weekday/month names come from the browser's `Intl` API for the active locale. Per-component label inputs (e.g. `emptyMessage`, `acceptLabel`) still take precedence over the dictionary.
+
 ## Documentation
 
 - **Storybook** — interactive docs for every component.
@@ -192,13 +236,16 @@ import { provideKptTablerIcons } from '@konce-pt/angular/icons';
 - 📊 **Flagowa tabela danych** — sortowanie, filtr, paginacja, virtual scroll, zaznaczanie, przestawianie/zamrażanie kolumn, eksport CSV, szablony komórek.
 - 🎨 **100% na tokenach** — każdy styl to `var(--kpt-*)`. Motyw jasny/ciemny, neutralna paleta OKLCH.
 - 🧩 **Standalone** — bez NgModules, tree-shaking.
+- 🌍 **Wbudowane i18n** — angielski (domyślny) i polski, przełączanie języka w runtime, dowolny język jednym plikiem JSON.
 
 ### Instalacja
 
 ```bash
-npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles
+npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles @angular/cdk
 ```
 
+`@angular/core`, `@angular/common` i `@angular/forms` (`^22`) są już w aplikacji Angulara; **`@angular/cdk` (`^22`) to wymagany peer** — komponenty overlay (select, autocomplete, datepicker, date-range, dialog, drawer, tooltip, popover, menu…) bazują na CDK Overlay — więc instaluj go jawnie (powyżej). Opcjonalnie: `@konce-pt/validators` (walidatory PL: NIP, REGON, PESEL, IBAN, kod pocztowy).
+
 ### Konfiguracja
 
 **Angular CLI (zalecane)** — dodaj CSS do tablicy **`styles`** w `angular.json`; kolejność ważna, `src/styles.scss` **na końcu**:
@@ -215,8 +262,45 @@ npm i @konce-pt/angular @konce-pt/tokens @konce-pt/styles
 
 > W Angular CLI **nie** używaj `import '…css'` w `main.ts` — bundler wrzuca taki CSS do osobnego, niepodlinkowanego arkusza i aplikacja jest bez stylów. Dla **Vite/webpack** import w `main.ts` działa (tak robi playground).
 
+Zoneless bootstrap (Angular 22) w konfiguracji aplikacji — bez importów CSS w `main.ts`:
+
+```ts
+import { provideZonelessChangeDetection } from '@angular/core';
+// import { provideKptI18n } from '@konce-pt/angular';
+// import { provideKptTablerIcons } from '@konce-pt/angular/icons';
+
+providers: [
+  provideZonelessChangeDetection(),   // wymagane (zoneless)
+  // provideKptI18n({ locale: 'pl' }), // opcjonalne — UI domyślnie po angielsku; ustaw dla PL/innego
+  // provideKptTablerIcons(),          // opcjonalne — pełny zestaw Tabler
+]
+```
+
+Język UI to domyślnie **angielski** i działa **bez żadnej konfiguracji** — `provideKptI18n(...)` jest opcjonalny, potrzebny tylko dla polskiego (lub własnego języka); szczegóły w sekcji i18n niżej.
+
 Motyw ciemny: `<html data-theme="dark">`; nadpisania `--kpt-color-*` w `styles.scss`. Pełny zestaw ikon Tabler: `provideKptTablerIcons()` z `@konce-pt/angular/icons`.
 
+### Internacjonalizacja (i18n)
+
+Etykiety komponentów są dostępne po **angielsku (domyślnie)** i **polsku**. Serwis `KptI18n` jest `providedIn: 'root'`, więc **angielski działa od razu, bez providera**. `provideKptI18n(...)` wołasz tylko, by wystartować po polsku (lub w innym języku) albo zarejestrować/nadpisać słowniki. Wszystkie napisy (aria-label, stany puste, paginator, kalendarze, menu edytora) pochodzą z tego serwisu opartego o sygnały — zmiana języka odświeża UI natychmiast (zoneless).
+
+```ts
+import { provideKptI18n } from '@konce-pt/angular';
+// providers: [provideKptI18n({ locale: 'pl' })]   // opcjonalne — polski interfejs (EN domyślnie)
+```
+
+Przełączanie w runtime: `inject(KptI18n).setLocale('en')`.
+
+**Własny język jednym plikiem JSON** (kształt = kontrakt `KptMessages`; brakujące klucze spadają na EN):
+
+```ts
+import de from './i18n/de.json';
+provideKptI18n({ locale: 'de', messages: { de } });
+```
+
+Nadpisanie pojedynczych etykiet: `provideKptI18n({ messages: { pl: { paginator: { rowsPerPage: 'Na stronie:' } } } })`.
+Nazwy dni/miesięcy w kalendarzach pochodzą z `Intl` wg locale. Inputy etykiet per-komponent (np. `emptyMessage`) mają priorytet nad słownikiem.
+
 ### Komponenty (70+)
 
 Formularze (Signal Forms), przyciski i akcje, layout, nawigacja, dane (z flagową `kpt-data-table`), feedback i overlay — pełna lista w tabeli powyżej. Każdy komponent ma plik `llms.txt` z opisem API obok źródła.