@konce-pt/angular 0.7.11 → 0.7.12

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @konce-pt/angular
 
+## 0.7.12
+
+### Patch Changes
+
+- Dokumentacja `llms.txt` jest teraz po angielsku i to ona jest wersją kanoniczną. 81 plików
+  z `packages/angular/**` trafia do tarballa npm, czyli do `node_modules` u konsumentów
+  biblioteki, gdzie czyta je ich asystent — polskie API sheety były ostatnią niekonsekwencją
+  w paczce, której README i opisy w `package.json` są angielskie od początku.
+
+  Dotychczasowa polska treść żyje w repozytorium obok, jako `llms-pl.txt`, i do paczki nie
+  trafia. Wersja angielska przejmuje istniejącą nazwę pliku, więc dla konsumenta nic się nie
+  przesuwa: `node_modules/@konce-pt/angular/**/llms.txt` leży dokładnie tam, gdzie leżał.
+
+  Identyfikatory, tokeny i klucze i18n przechodzą bez zmian — przetłumaczone są proza,
+  komentarze i napisy widoczne dla użytkownika w przykładach. Polszczyzna zostaje tam, gdzie
+  jest tematem: walidatory NIP/REGON/PESEL, `displayFormat: 'pl'` i przykłady słownika PL.
+
 ## 0.7.11
 
 ### Minor Changes

package/charts/src/lib/llms.txt

@@ -1,51 +1,51 @@
 # KptChart (kpt-chart)
 
-Wykres SVG w czystym Angularze (sygnały, zoneless), bez zależności typu Chart.js/D3.
-Rdzeń obliczeń to czysty TypeScript (przenośny do React w Fazie 2).
+An SVG chart in plain Angular (signals, zoneless), with no Chart.js/D3-style dependency.
+The computation core is plain TypeScript (portable to React in stage 2).
 Import: `import { KptChart } from '@konce-pt/angular/charts';`
 
-## Typy wykresów (config.type)
-- `line` — liniowy; interpolacja `linear` | `cubic` | `cubic-monotonic`; `area?: boolean`, `points?: boolean`,
-  `crosshair?: boolean` (hover punktu → pionowa prowadnica + podświetlona pigułka etykiety osi X)
-- `bar` — słupkowy; `orientation: 'vertical' | 'horizontal'`, `borderRadius?: px`
-- `pie` — kołowy
-- `doughnut` — pierścieniowy; `innerRadius?: 0..1` (domyślnie 0.6)
-- `polarArea` — równe kąty, promień ∝ wartość
-- `radar` — osie promieniowe + wielokąt serii
+## Chart types (config.type)
+- `line` — a line chart; interpolation `linear` | `cubic` | `cubic-monotonic`; `area?: boolean`, `points?: boolean`,
+  `crosshair?: boolean` (hovering a point → a vertical guide + a highlighted pill on the X axis label)
+- `bar` — a bar chart; `orientation: 'vertical' | 'horizontal'`, `borderRadius?: px`
+- `pie` — a pie chart
+- `doughnut` — a doughnut; `innerRadius?: 0..1` (default 0.6)
+- `polarArea` — equal angles, the radius proportional to the value
+- `radar` — radial axes + a polygon per series
 
-## Wejścia
-- `config: KptChartConfig` (wymagane) — jeden obiekt sterujący całością
-- `width` / `height`: jednostki viewBoxa (600×360); wykres skaluje się do kontenera
+## Inputs
+- `config: KptChartConfig` (required) — a single object driving everything
+- `width` / `height`: viewBox units (600×360); the chart scales to its container
 
-## KptChartConfig (skrót)
+## KptChartConfig (in brief)
 - `labels: string[]`, `series: { name; data: number[]; color? }[]`
 - `legend`: `{ display?, position: top|bottom|left|right, align: start|center|end, pointStyle: circle|rect|rectRot|triangle|line, title? }`
 - `title` / `subtitle`: `{ display?, text, align, color?, font?, padding? }`
 - `tooltip`: `{ enabled?, format?(ctx: {series,label,value}): string }`
 - `animation`: `{ enabled?, duration=400, delay=0, stagger=60 }`
 
-## Interakcje
-- Hover na punkcie/słupku/wycinku → tooltip (seria, etykieta, wartość); dymek clampowany do krawędzi.
-- Klik w legendę → ukrycie/pokazanie serii (pie/doughnut/polar: ukrycie wycinka) z przeliczeniem skali.
-- Hover na legendzie → podświetlenie serii, wygaszenie pozostałych.
+## Interactions
+- Hovering a point/bar/slice → a tooltip (series, label, value); the bubble is clamped to the edges.
+- Clicking the legend → hide/show a series (pie/doughnut/polar: hide a slice) with the scale recomputed.
+- Hovering the legend → highlight that series, dim the rest.
 
-## Animacje
-Linia: `stroke-dasharray/offset`. Słupki: `scaleY/scaleX` (origin od osi). Wycinki/radar: `scale` od środka.
-Stagger `delay = index * stagger`. Wyłączane przez `animation.enabled=false` i `prefers-reduced-motion`.
+## Animations
+Line: `stroke-dasharray/offset`. Bars: `scaleY/scaleX` (origin at the axis). Slices/radar: `scale` from the center.
+Stagger `delay = index * stagger`. Disabled by `animation.enabled=false` and by `prefers-reduced-motion`.
 
-## Przykład
+## Example
     <kpt-chart [config]="{
       type: 'line',
-      labels: ['Sty','Lut','Mar'],
-      series: [{ name: 'Sprzedaż', data: [12, 19, 7] }],
+      labels: ['Jan','Feb','Mar'],
+      series: [{ name: 'Sales', data: [12, 19, 7] }],
       interpolation: 'cubic-monotonic',
       legend: { position: 'top' }
     }" />
 
-## Tokeny / stylowanie
-Paleta z tokenów semantycznych (`--kpt-color-primary|info|success|warning|danger` + skala).
-SCSS w `@layer kpt.components`, klasy `kpt-chart__*`. Kolory serii nadpisywalne przez `series[].color`.
+## Tokens / styling
+The palette comes from the semantic tokens (`--kpt-color-primary|info|success|warning|danger` + the scale).
+SCSS lives in `@layer kpt.components`, classes `kpt-chart__*`. Series colors can be overridden through `series[].color`.
 
-## Rdzeń (pure TS, opcjonalnie)
-Eksport funkcji: `linePath`, `areaPath`, `barLayout`, `pieSlices`, `polarSlices`, `radarGrid`,
-`radarPoints`, `niceScale`, `seriesColor`, `KPT_CHART_PALETTE` — do własnych rozszerzeń/SSR.
+## Core (pure TS, optional)
+Exported functions: `linePath`, `areaPath`, `barLayout`, `pieSlices`, `polarSlices`, `radarGrid`,
+`radarPoints`, `niceScale`, `seriesColor`, `KPT_CHART_PALETTE` — for your own extensions or SSR.

package/grid/src/lib/llms.txt

@@ -1,37 +1,37 @@
 # KptGrid / KptCol / KptFlex (@konce-pt/angular/grid)
 
-Ergonomia Angulara nad arkuszem `@konce-pt/grid`. Dyrektywy ustawiają wyłącznie
-custom properties inline — nie dodają ani nie usuwają klas, układ przelicza
-natywny silnik CSS.
+Angular ergonomics over the `@konce-pt/grid` stylesheet. The directives set nothing but
+inline custom properties — they neither add nor remove classes, and the layout is computed by
+the native CSS engine.
 
 Import: `import { KptGrid, KptCol, KptFlex } from '@konce-pt/angular/grid';`
-Skrót: `import { KPT_GRID_IMPORTS } from '@konce-pt/angular/grid';` → `imports: [...KPT_GRID_IMPORTS]`
+Shorthand: `import { KPT_GRID_IMPORTS } from '@konce-pt/angular/grid';` → `imports: [...KPT_GRID_IMPORTS]`
 
-Wymaga arkusza: `import '@konce-pt/grid';` (Angular CLI: `angular.json` → `styles[]`).
+Requires the stylesheet: `import '@konce-pt/grid';` (Angular CLI: `angular.json` → `styles[]`).
 
-## Breakpointy (mobile-first)
+## Breakpoints (mobile-first)
 `sm` >= 640px, `md` >= 768px, `lg` >= 1024px, `xl` >= 1280px, `2xl` >= 1536px.
-Wartość obowiązuje od swojego breakpointa w górę, dopóki nie nadpisze jej kolejna:
-`[kptCol]="12" [kptColLg]="5"` daje 12 na mobile, `sm` i `md`, a 5 dopiero od `lg`.
+A value applies from its breakpoint upward until the next one overrides it:
+`[kptCol]="12" [kptColLg]="5"` gives 12 on mobile, `sm` and `md`, and 5 only from `lg` up.
 
-## KptGrid — selektor `[kptGrid]`, `kpt-grid`
-Klasa hosta: `kpt-grid`.
-- `columns`: number — liczba kolumn (domyślnie 12 z CSS). Warianty: `columnsSm`,
+## KptGrid — selector `[kptGrid]`, `kpt-grid`
+Host class: `kpt-grid`.
+- `columns`: number — the column count (12 by default, from CSS). Variants: `columnsSm`,
   `columnsMd`, `columnsLg`, `columnsXl`, `columns2xl`.
-- `gap`: string — odstęp w obu osiach, np. `'1.5rem'`, `'var(--kpt-space-6)'`.
-- `gapX`, `gapY`: string — odstęp w jednej osi, nadpisuje `gap`.
-- `container`: boolean — tryb container queries (patrz niżej).
-
-## KptCol — selektor `[kptCol]`, `[kptColSm]` … `[kptColSelf]`
-- `kptCol`: number | string — rozpiętość, baza mobile-first.
-- `kptColSm`, `kptColMd`, `kptColLg`, `kptColXl`, `kptCol2xl` — nadpisania per breakpoint.
-- `kptColStart`: number — linia siatki, od której zaczyna się kolumna (1-based); tak robi się offsety.
-- `kptColOrder`: number — kolejność wizualna. Nie zmienia DOM: czytniki ekranu
-  i nawigacja klawiaturą idą za DOM, więc nie przenoś nim treści interaktywnej.
+- `gap`: string — the gap on both axes, e.g. `'1.5rem'`, `'var(--kpt-space-6)'`.
+- `gapX`, `gapY`: string — the gap on one axis, overriding `gap`.
+- `container`: boolean — container query mode (see below).
+
+## KptCol — selector `[kptCol]`, `[kptColSm]` … `[kptColSelf]`
+- `kptCol`: number | string — the span, the mobile-first base.
+- `kptColSm`, `kptColMd`, `kptColLg`, `kptColXl`, `kptCol2xl` — per-breakpoint overrides.
+- `kptColStart`: number — the grid line the column starts at (1-based); this is how offsets are done.
+- `kptColOrder`: number — the visual order. It does not change the DOM: screen readers
+  and keyboard navigation follow the DOM, so do not use it to move interactive content around.
 - `kptColSelf`: string — `align-self` (`start`, `end`, `center`, `stretch`, `baseline`).
 
-## KptFlex — selektor `[kptFlex]`
-Klasa hosta: `kpt-flex`. Te same zmienne i breakpointy co grid, jeden wymiar.
+## KptFlex — selector `[kptFlex]`
+Host class: `kpt-flex`. The same variables and breakpoints as the grid, in one dimension.
 - `direction`: 'row' | 'row-reverse' | 'column' | 'column-reverse' (+ `directionMd`, `directionLg`)
 - `wrap`: 'wrap' | 'nowrap' | 'wrap-reverse'
 - `justify`, `align` (+ `justifyMd`, `alignMd`): `start` | `end` | `center` | `stretch` |
@@ -39,53 +39,53 @@ Klasa hosta: `kpt-flex`. Te same zmienne i breakpointy co grid, jeden wymiar.
 - `gap`, `gapX`, `gapY`: string
 - `container`: boolean
 
-Wartości bez odpowiednika w inputach podaje się klasami utility z `@konce-pt/grid`:
+Values with no matching input are supplied with utility classes from `@konce-pt/grid`:
 `kpt-grow-1`, `kpt-shrink-0`, `kpt-order-first`, `kpt-self-end`, `kpt-gap-6`.
 
-## Tryb kontenerowy (`container`)
-Spany dzieci reagują na szerokość TEJ siatki zamiast okna — karta w wąskim
-sidebarze układa się jednokolumnowo, choć viewport jest szeroki.
+## Container mode (`container`)
+The children's spans react to the width of THIS grid instead of the window — a card in a narrow
+sidebar lays itself out in a single column even though the viewport is wide.
 
-Ograniczenie CSS, nie paczki: `@container` odpytuje najbliższy kontener przodka,
-więc element nie może odpytać własnego. Responsywne są zmienne dziecka (span,
-start, order, self); liczba kolumn i odstępy nadal idą za viewportem.
+A CSS limitation, not a package one: `@container` queries the nearest ancestor container,
+so an element cannot query its own. What is responsive are the child's variables (span,
+start, order, self); the column count and the gaps still follow the viewport.
 
-## Przykłady
+## Examples
     <div kptGrid>
-      <div [kptCol]="12" [kptColSm]="6" [kptColMd]="4">Karta</div>
-      <div [kptCol]="12" [kptColSm]="6" [kptColMd]="4">Karta</div>
-      <div [kptCol]="12" [kptColMd]="4">Karta</div>
+      <div [kptCol]="12" [kptColSm]="6" [kptColMd]="4">Card</div>
+      <div [kptCol]="12" [kptColSm]="6" [kptColMd]="4">Card</div>
+      <div [kptCol]="12" [kptColMd]="4">Card</div>
     </div>
 
-    <!-- 18 kolumn bez rekompilacji SCSS -->
+    <!-- 18 columns with no SCSS recompilation -->
     <div kptGrid [columns]="18" gap="1.5rem">
       <div [kptCol]="18" [kptColLg]="5">Sidebar</div>
-      <div [kptCol]="18" [kptColLg]="13">Treść</div>
+      <div [kptCol]="18" [kptColLg]="13">Content</div>
     </div>
 
-    <!-- offset i zmiana kolejności na mobile -->
+    <!-- an offset and a reordering on mobile -->
     <div kptGrid>
       <div [kptCol]="6" [kptColStart]="4">start 4, span 6</div>
-      <div [kptCol]="12" [kptColMd]="6" class="kpt-order-first kpt-order-md-none">drugi w DOM</div>
-      <div [kptCol]="12" [kptColMd]="6">pierwszy w DOM</div>
+      <div [kptCol]="12" [kptColMd]="6" class="kpt-order-first kpt-order-md-none">second in the DOM</div>
+      <div [kptCol]="12" [kptColMd]="6">first in the DOM</div>
     </div>
 
     <!-- flexbox -->
     <div kptFlex direction="column" directionMd="row" justify="space-between" align="center" gap="1rem">
-      <span>Lewa</span>
-      <span>Prawa</span>
+      <span>Left</span>
+      <span>Right</span>
     </div>
 
-    <!-- układ formularza (preset CSS, bez klas na dzieciach) -->
+    <!-- a form layout (a CSS preset, no classes on the children) -->
     <form class="kpt-grid kpt-form-grid">
-      <kpt-form-field label="Imię"><kpt-input [(value)]="firstName" /></kpt-form-field>
-      <kpt-form-field label="Nazwisko"><kpt-input [(value)]="lastName" /></kpt-form-field>
-      <kpt-form-field label="Notatki" class="kpt-col-md-12"><kpt-input [(value)]="notes" /></kpt-form-field>
+      <kpt-form-field label="First name"><kpt-input [(value)]="firstName" /></kpt-form-field>
+      <kpt-form-field label="Last name"><kpt-input [(value)]="lastName" /></kpt-form-field>
+      <kpt-form-field label="Notes" class="kpt-col-md-12"><kpt-input [(value)]="notes" /></kpt-form-field>
     </form>
 
 ## Custom properties
-Siatka: `--kpt-grid-columns`, `--kpt-gap`, `--kpt-gap-x`, `--kpt-gap-y`,
+The grid: `--kpt-grid-columns`, `--kpt-gap`, `--kpt-gap-x`, `--kpt-gap-y`,
 `--kpt-justify`, `--kpt-align`, `--kpt-content`, `--kpt-flex-direction`, `--kpt-flex-wrap`.
-Dziecko: `--kpt-col`, `--kpt-col-start`, `--kpt-order`, `--kpt-self`, `--kpt-flex`,
+The child: `--kpt-col`, `--kpt-col-start`, `--kpt-order`, `--kpt-self`, `--kpt-flex`,
 `--kpt-grow`, `--kpt-shrink`.
-Każda ma warianty per breakpoint: `--kpt-col` → `--kpt-col-md`.
+Each one has per-breakpoint variants: `--kpt-col` → `--kpt-col-md`.