@konce-pt/react 0.11.2 → 0.14.0

package/dist/toast/toast-container.d.ts

@@ -1,17 +1,23 @@
 import { type ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+import { type KptToastPosition } from './toast-store.ts';
 export interface KptToastContainerProps extends ComponentPropsWithRef<'div'>, KptI18nOverrides {
+    /** Położenie toastów, które nie podały własnego `position`. Domyślnie `bottom-end`. */
+    position?: KptToastPosition;
 }
 /**
  * Kontener renderujący toasty z `kptToast`. Umieść raz w aplikacji, np. w komponencie głównym.
  *
- * Ogłaszanie idzie przez dwa stałe, niewidoczne regiony na żywo — uprzejmy dla zwykłych toastów
- * i natychmiastowy dla błędów — a nie przez same toasty: region musi istnieć, zanim pojawi się
+ * Ogłaszanie idzie przez dwa stałe, niewidoczne regiony na żywo - uprzejmy dla zwykłych toastów
+ * i natychmiastowy dla błędów - a nie przez same toasty: region musi istnieć, zanim pojawi się
  * w nim treść, a zagnieżdżone regiony część czytników ogłasza dwa razy. Gdy wskaźnik albo fokus
  * jest na toastach, liczniki stoją, więc komunikat nie znika w trakcie czytania.
  *
+ * Toasty rosną w rogu z `position` kontenera albo z własnego `position` - każdy róg to osobny stos,
+ * przy górnej krawędzi najnowszy jest na górze, przy dolnej na dole.
+ *
  * @example
  * <KptToastContainer />
  * // gdziekolwiek: kptToast.success('Zapisano');
  */
-export declare function KptToastContainer({ locale, dictionary, className, ...rest }: Readonly<KptToastContainerProps>): import("react").JSX.Element;
+export declare function KptToastContainer({ position, locale, dictionary, className, ...rest }: Readonly<KptToastContainerProps>): import("react").JSX.Element;

package/dist/toast/toast-container.js

@@ -1,9 +1,12 @@
+'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useRef, useState } from 'react';
 import { cn } from "../internal/cn.js";
 import { useKptMessages } from "../i18n/i18n-context.js";
 import { KptIcon } from "../icon/icon.js";
-import { kptToast, useKptToasts } from "./toast-store.js";
+import { kptToast, useKptToasts, useKptToastsPaused } from "./toast-store.js";
+/** Kolejność grup w DOM - stała, żeby dodanie toastu w innym rogu nie przestawiało pozostałych. */
+const POSITIONS = ['top-start', 'top-center', 'top-end', 'bottom-start', 'bottom-center', 'bottom-end'];
 const ICONS = {
     info: 'info',
     success: 'circle-check',
@@ -13,21 +16,27 @@ const ICONS = {
 /**
  * Kontener renderujący toasty z `kptToast`. Umieść raz w aplikacji, np. w komponencie głównym.
  *
- * Ogłaszanie idzie przez dwa stałe, niewidoczne regiony na żywo — uprzejmy dla zwykłych toastów
- * i natychmiastowy dla błędów — a nie przez same toasty: region musi istnieć, zanim pojawi się
+ * Ogłaszanie idzie przez dwa stałe, niewidoczne regiony na żywo - uprzejmy dla zwykłych toastów
+ * i natychmiastowy dla błędów - a nie przez same toasty: region musi istnieć, zanim pojawi się
  * w nim treść, a zagnieżdżone regiony część czytników ogłasza dwa razy. Gdy wskaźnik albo fokus
  * jest na toastach, liczniki stoją, więc komunikat nie znika w trakcie czytania.
  *
+ * Toasty rosną w rogu z `position` kontenera albo z własnego `position` - każdy róg to osobny stos,
+ * przy górnej krawędzi najnowszy jest na górze, przy dolnej na dole.
+ *
  * @example
  * <KptToastContainer />
  * // gdziekolwiek: kptToast.success('Zapisano');
  */
-export function KptToastContainer({ locale, dictionary, className, ...rest }) {
+export function KptToastContainer({ position = 'bottom-end', locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const toasts = useKptToasts();
+    const paused = useKptToastsPaused();
+    // Toasty pogrupowane po rogu; tylko niepuste grupy, każda w osobnym przypiętym stosie.
+    const groups = POSITIONS.map((at) => ({ position: at, toasts: toasts.filter((toast) => (toast.position ?? position) === at) })).filter((group) => group.toasts.length);
     const [politeText, setPoliteText] = useState('');
     const [alertText, setAlertText] = useState('');
-    // Ostatni ogłoszony toast — zamknięcie nowszego nie może ponownie ogłosić starszego.
+    // Ostatni ogłoszony toast - zamknięcie nowszego nie może ponownie ogłosić starszego.
     const lastAnnounced = useRef(0);
     const holds = useRef(new Set());
     const hold = (reason, on) => {
@@ -41,7 +50,7 @@ export function KptToastContainer({ locale, dictionary, className, ...rest }) {
             kptToast.resume();
     };
     useEffect(() => {
-        // Pusty kontener nie dostanie już `mouseleave`, więc zdejmujemy wstrzymanie sami —
+        // Pusty kontener nie dostanie już `mouseleave`, więc zdejmujemy wstrzymanie sami -
         // inaczej kolejne toasty czekałyby w nieskończoność.
         if (!toasts.length && holds.current.size) {
             holds.current.clear();
@@ -55,7 +64,7 @@ export function KptToastContainer({ locale, dictionary, className, ...rest }) {
         for (const toast of fresh) {
             const text = toast.title ? `${toast.title}. ${toast.message}` : toast.message;
             const set = toast.variant === 'danger' ? setAlertText : setPoliteText;
-            // Czyścimy region przed wpisaniem — ten sam tekst drugi raz inaczej nie zostałby ogłoszony.
+            // Czyścimy region przed wpisaniem - ten sam tekst drugi raz inaczej nie zostałby ogłoszony.
             set('');
             frames.push(requestAnimationFrame(() => set(text)));
         }
@@ -67,8 +76,8 @@ export function KptToastContainer({ locale, dictionary, className, ...rest }) {
             return;
         hold('focus', false);
     };
-    return (_jsxs("div", { className: cn('kpt-toast-container-host', className), ...rest, children: [_jsx("div", { className: "kpt-toast-container", role: toasts.length ? 'region' : undefined, "aria-label": toasts.length ? t('toast.region') : undefined, onMouseEnter: () => hold('pointer', true), onMouseLeave: () => hold('pointer', false), onFocus: () => hold('focus', true), onBlur: onBlur, children: toasts.map((toast) => (_jsxs("div", { className: "kpt-toast", "data-variant": toast.variant, children: [_jsx(KptIcon, { className: "kpt-toast__icon", name: ICONS[toast.variant] }), _jsxs("div", { className: "kpt-toast__content", children: [toast.title ? _jsx("div", { className: "kpt-toast__title", children: toast.title }) : null, _jsx("div", { className: "kpt-toast__message", children: toast.message })] }), toast.action ? (_jsx("button", { className: "kpt-toast__action", type: "button", onClick: () => {
+    return (_jsxs("div", { className: cn('kpt-toast-container-host', className), ...rest, children: [groups.map((group) => (_jsx("div", { className: "kpt-toast-container", role: "region", "data-position": group.position, "data-paused": paused ? '' : undefined, "aria-label": t('toast.region'), onMouseEnter: () => hold('pointer', true), onMouseLeave: () => hold('pointer', false), onFocus: () => hold('focus', true), onBlur: onBlur, children: group.toasts.map((toast) => (_jsxs("div", { className: "kpt-toast", "data-variant": toast.variant, "data-appearance": toast.appearance, children: [_jsx(KptIcon, { className: "kpt-toast__icon", name: ICONS[toast.variant] }), _jsxs("div", { className: "kpt-toast__content", children: [toast.title ? _jsx("div", { className: "kpt-toast__title", children: toast.title }) : null, _jsx("div", { className: "kpt-toast__message", children: toast.message })] }), toast.action ? (_jsx("button", { className: "kpt-toast__action", type: "button", onClick: () => {
                                 toast.action?.run();
                                 kptToast.dismiss(toast.id);
-                            }, children: toast.action.label })) : null, _jsx("button", { className: "kpt-toast__close", type: "button", onClick: () => kptToast.dismiss(toast.id), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })] }, toast.id))) }), _jsx("span", { className: "kpt-toast-container__live", "aria-live": "polite", "aria-atomic": "true", children: politeText }), _jsx("span", { className: "kpt-toast-container__live", "aria-live": "assertive", "aria-atomic": "true", children: alertText })] }));
+                            }, children: toast.action.label })) : null, toast.closable ? (_jsx("button", { className: "kpt-toast__close", type: "button", onClick: () => kptToast.dismiss(toast.id), "aria-label": t('common.close'), children: _jsx(KptIcon, { name: "x" }) })) : null, toast.progress && toast.duration > 0 ? (_jsx("span", { className: "kpt-toast__timer", "aria-hidden": "true", style: { '--_duration': `${toast.duration}ms` } })) : null] }, toast.id))) }, group.position))), _jsx("span", { className: "kpt-toast-container__live", "aria-live": "polite", "aria-atomic": "true", children: politeText }), _jsx("span", { className: "kpt-toast-container__live", "aria-live": "assertive", "aria-atomic": "true", children: alertText })] }));
 }

package/dist/toast/toast-store.d.ts

@@ -1,19 +1,54 @@
 import type { KptAlertVariant } from '../shared/types.ts';
-/** Przycisk akcji w toaście, np. „Cofnij”. Kliknięcie uruchamia `run` i zamyka toast. */
+/** Przycisk akcji w toaście, np. "Cofnij". Kliknięcie uruchamia `run` i zamyka toast. */
 export interface KptToastAction {
     label: string;
     run: () => void;
 }
+/**
+ * Róg albo środek krawędzi okna, przy którym rosną toasty. `start`/`end` są logiczne - w układzie
+ * od prawej do lewej zamieniają się stronami same.
+ */
+export type KptToastPosition = 'top-start' | 'top-center' | 'top-end' | 'bottom-start' | 'bottom-center' | 'bottom-end';
+/** `outline` - jasna powierzchnia z akcentem na krawędzi; `filled` - całe tło w barwie wariantu. */
+export type KptToastAppearance = 'outline' | 'filled';
 export interface KptToast {
     id: number;
     message: string;
     title?: string;
     variant: KptAlertVariant;
-    /** Czas życia w ms; 0 = bez auto-zamykania. */
+    /**
+     * Czas życia w ms; 0 = bez auto-zamykania. Domyślnie 4000 ms, a dla toastu z `action` - 0:
+     * użytkownik klawiatury albo czytnika nie zdąży dojść do przycisku "Cofnij" w kontenerze na końcu
+     * strony, zanim toast zniknie (WCAG 2.2.1). Jawne `duration` zawsze wygrywa - poza jednym
+     * przypadkiem: toast bez X, bez akcji i bez czasu nie dałby się zamknąć, więc dostaje 5000 ms.
+     */
     duration: number;
     action?: KptToastAction;
+    /** Położenie tego toastu; bez wartości - `position` kontenera. */
+    position?: KptToastPosition;
+    appearance: KptToastAppearance;
+    /** `false` chowa przycisk X. */
+    closable: boolean;
+    /** Pasek czasu na dole toastu - kurczy się do zamknięcia i staje razem z licznikiem. */
+    progress: boolean;
 }
 export type KptToastOptions = Partial<Omit<KptToast, 'id' | 'message'>>;
+/** Wartości domyślne toastów całej aplikacji - `kptToast.configure(...)`. Opcje toastu wygrywają. */
+export interface KptToastConfig {
+    /** Czas życia toastu bez akcji (ms). Domyślnie 4000. */
+    duration?: number;
+    appearance?: KptToastAppearance;
+    closable?: boolean;
+    progress?: boolean;
+}
+/** Czas toastu, którego inaczej nie dałoby się zamknąć (bez X, bez akcji, bez czasu). */
+export declare const KPT_TOAST_FALLBACK_DURATION = 5000;
+/**
+ * Pełny toast z opcji i konfiguracji. Kolejność: opcja toastu > `kptToast.configure` > wartość
+ * biblioteki. Na końcu bezpiecznik: toast, którego nie da się zamknąć ani przyciskiem, ani akcją,
+ * dostaje czas, bo inaczej zostałby na ekranie na zawsze.
+ */
+export declare function resolveKptToast(id: number, message: string, options: KptToastOptions, config: KptToastConfig | null): KptToast;
 declare function show(message: string, options?: KptToastOptions): number;
 declare function dismiss(id: number): void;
 declare function clear(): void;
@@ -21,8 +56,11 @@ declare function clear(): void;
 declare function pause(): void;
 /** Wznawia liczniki od pozostałego czasu. */
 declare function resume(): void;
+/** Domyślny wygląd i zachowanie toastów w całej aplikacji; wołaj raz, przy starcie. */
+declare function configure(next: KptToastConfig): void;
 /** Powiadomienia (toasty). Renderuje je `<KptToastContainer />`, umieszczony raz w aplikacji. */
 export declare const kptToast: {
+    configure: typeof configure;
     show: typeof show;
     info: (message: string, options?: KptToastOptions) => number;
     success: (message: string, options?: KptToastOptions) => number;
@@ -35,4 +73,6 @@ export declare const kptToast: {
 };
 /** Bieżąca lista toastów. Używane przez kontener; przydaje się też do własnego renderowania. */
 export declare function useKptToasts(): KptToast[];
+/** Czy liczniki stoją (wskaźnik albo fokus na toastach, albo `kptToast.pause()`). */
+export declare function useKptToastsPaused(): boolean;
 export {};

package/dist/toast/toast-store.js

@@ -1,7 +1,31 @@
 import { useSyncExternalStore } from 'react';
+/** Czas toastu, którego inaczej nie dałoby się zamknąć (bez X, bez akcji, bez czasu). */
+export const KPT_TOAST_FALLBACK_DURATION = 5000;
+/**
+ * Pełny toast z opcji i konfiguracji. Kolejność: opcja toastu > `kptToast.configure` > wartość
+ * biblioteki. Na końcu bezpiecznik: toast, którego nie da się zamknąć ani przyciskiem, ani akcją,
+ * dostaje czas, bo inaczej zostałby na ekranie na zawsze.
+ */
+export function resolveKptToast(id, message, options, config) {
+    const closable = options.closable ?? config?.closable ?? true;
+    let duration = options.duration ?? (options.action ? 0 : (config?.duration ?? 4000));
+    if (!closable && !options.action && duration <= 0)
+        duration = KPT_TOAST_FALLBACK_DURATION;
+    return {
+        variant: 'info',
+        ...options,
+        id,
+        message,
+        duration,
+        closable,
+        appearance: options.appearance ?? config?.appearance ?? 'outline',
+        progress: options.progress ?? config?.progress ?? false,
+    };
+}
 let toasts = [];
 let seq = 0;
 let paused = false;
+let config = null;
 const timers = new Map();
 const listeners = new Set();
 function emit() {
@@ -10,7 +34,7 @@ function emit() {
 }
 function show(message, options = {}) {
     const id = ++seq;
-    const toast = { id, message, variant: 'info', duration: 4000, ...options };
+    const toast = resolveKptToast(id, message, options, config);
     toasts = [...toasts, toast];
     emit();
     if (toast.duration > 0) {
@@ -48,6 +72,7 @@ function pause() {
     if (paused)
         return;
     paused = true;
+    emit();
     const now = Date.now();
     for (const timer of timers.values()) {
         if (!timer.handle)
@@ -62,11 +87,17 @@ function resume() {
     if (!paused)
         return;
     paused = false;
+    emit();
     for (const id of timers.keys())
         start(id);
 }
+/** Domyślny wygląd i zachowanie toastów w całej aplikacji; wołaj raz, przy starcie. */
+function configure(next) {
+    config = { ...next };
+}
 /** Powiadomienia (toasty). Renderuje je `<KptToastContainer />`, umieszczony raz w aplikacji. */
 export const kptToast = {
+    configure,
     show,
     info: (message, options) => show(message, { ...options, variant: 'info' }),
     success: (message, options) => show(message, { ...options, variant: 'success' }),
@@ -88,3 +119,7 @@ function subscribe(listener) {
 export function useKptToasts() {
     return useSyncExternalStore(subscribe, () => toasts, () => EMPTY);
 }
+/** Czy liczniki stoją (wskaźnik albo fokus na toastach, albo `kptToast.pause()`). */
+export function useKptToastsPaused() {
+    return useSyncExternalStore(subscribe, () => paused, () => false);
+}

package/dist/toolbar/llms.txt

@@ -1,18 +1,18 @@
 # KptToolbar (@konce-pt/react)
 
-The top bar — a horizontal strip for application content (logo, actions).
+The top bar - a horizontal strip for application content (logo, actions).
 Import: `import { KptToolbar, KptToolbarSpacer } from '@konce-pt/react';`
 
 ## DOM
     <div class="kpt-toolbar kpt-toolbar--elevated">
-      …children…
+      ...children...
       <span kpttoolbarspacer=""></span>
-      …children…
+      ...children...
     </div>
 
 ## Props
-- `elevated`: boolean — adds a shadow under the bar
-- `wrap`: boolean — lets the content wrap onto further rows when it runs out of room
+- `elevated`: boolean - adds a shadow under the bar
+- `wrap`: boolean - lets the content wrap onto further rows when it runs out of room
 - `className`, `ref` and every other `<div>` prop go to the bar itself
 
 `wrap` is opt-in because wrapping changes what `<KptToolbarSpacer>` does: in a single-row bar it
@@ -30,10 +30,10 @@ serves both ports).
       <KptButton variant="text">Sign out</KptButton>
     </KptToolbar>
 
-    <KptAppShell toolbar={<KptToolbar elevated>…</KptToolbar>} sidenav={…}>…</KptAppShell>
+    <KptAppShell toolbar={<KptToolbar elevated>...</KptToolbar>} sidenav={...}>...</KptAppShell>
 
 ## Responsiveness
-Below the `sm` breakpoint the bar shrinks on its own — a lower height
+Below the `sm` breakpoint the bar shrinks on its own - a lower height
 (`--kpt-toolbar-height-compact`), narrower inline padding and a smaller gap. No props involved.
 
 ## Tokens

package/dist/toolbar/toolbar.d.ts

@@ -4,13 +4,13 @@ export interface KptToolbarProps extends ComponentPropsWithRef<'div'> {
     elevated?: boolean;
     /**
      * Pozwala zawartości paska zawinąć się do kolejnych wierszy, gdy zabraknie miejsca.
-     * Opcjonalne, bo zawijanie zmienia zachowanie `<KptToolbarSpacer>` — w jednowierszowym
+     * Opcjonalne, bo zawijanie zmienia zachowanie `<KptToolbarSpacer>` - w jednowierszowym
      * pasku rozpycha on treść, a w zawijanym potrafi zepchnąć resztę do nowego wiersza.
      */
     wrap?: boolean;
 }
 /**
- * Górny pasek (toolbar) — pozioma belka na treść aplikacji (logo, akcje).
+ * Górny pasek (toolbar) - pozioma belka na treść aplikacji (logo, akcje).
  * Poniżej breakpointa `sm` pasek sam zbiega się do niższej wysokości i węższych marginesów.
  *
  * @example
@@ -22,7 +22,7 @@ export interface KptToolbarProps extends ComponentPropsWithRef<'div'> {
  */
 export declare function KptToolbar({ elevated, wrap, className, ...rest }: Readonly<KptToolbarProps>): import("react").JSX.Element;
 /**
- * Elastyczny odstęp rozpychający zawartość paska. Nosi atrybut `kpttoolbarspacer` —
+ * Elastyczny odstęp rozpychający zawartość paska. Nosi atrybut `kpttoolbarspacer` -
  * to po nim celuje wspólny SCSS (nazwy atrybutów w selektorach CSS są w HTML
  * case-insensitive, więc jedna reguła obsługuje oba porty).
  */

package/dist/toolbar/toolbar.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { cn } from "../internal/cn.js";
 /**
- * Górny pasek (toolbar) — pozioma belka na treść aplikacji (logo, akcje).
+ * Górny pasek (toolbar) - pozioma belka na treść aplikacji (logo, akcje).
  * Poniżej breakpointa `sm` pasek sam zbiega się do niższej wysokości i węższych marginesów.
  *
  * @example
@@ -15,7 +15,7 @@ export function KptToolbar({ elevated = false, wrap = false, className, ...rest
     return (_jsx("div", { className: cn('kpt-toolbar', elevated && 'kpt-toolbar--elevated', className), "data-wrap": wrap ? '' : undefined, ...rest }));
 }
 /**
- * Elastyczny odstęp rozpychający zawartość paska. Nosi atrybut `kpttoolbarspacer` —
+ * Elastyczny odstęp rozpychający zawartość paska. Nosi atrybut `kpttoolbarspacer` -
  * to po nim celuje wspólny SCSS (nazwy atrybutów w selektorach CSS są w HTML
  * case-insensitive, więc jedna reguła obsługuje oba porty).
  */

package/dist/tooltip/llms.txt

@@ -1,32 +1,31 @@
 # KptTooltip (@konce-pt/react)
 
-A tooltip shown on hover and focus. Light — the element is appended to `body` and positioned
+A tooltip shown on hover and focus. Light - the element is appended to `body` and positioned
 against the child. Import: `import { KptTooltip } from '@konce-pt/react';`
 
 ## DOM
-The component renders NO wrapper of its own — it clones the child and attaches the handlers and a
+The component renders NO wrapper of its own - it clones the child and attaches the handlers and a
 ref to it, so the tree stays exactly as it would be without the tooltip. This is the port of the
 `[kptTooltip]` directive, which likewise added nothing to the DOM.
 
     <!-- while visible, appended to body: -->
-    <div class="kpt-tooltip" role="tooltip" style="position: fixed; …">Save changes</div>
+    <div class="kpt-tooltip" role="tooltip" style="position: fixed; ...">Save changes</div>
 
 ## Props
-- `text`: string — the bubble content; empty text disables the tooltip
+- `text`: string - the bubble content; empty text disables the tooltip
 - `position`: 'top' | 'bottom' | 'left' | 'right' (default 'top')
-- `onlyWhenTruncated`: boolean — show it only when the content does not fit
-- `children` — exactly one element, the one that gets hover and focus
+- `onlyWhenTruncated`: boolean - show it only when the content does not fit
+- `children` - exactly one element, the one that gets hover and focus
 
 ## onlyWhenTruncated
 The check runs at hover time, not at render, so the result is always current after a width or zoom
 change, with no observers. It measures the host AND its direct children, because
-`text-overflow: ellipsis` usually sits on an inner element — and such an element shrinks to the
+`text-overflow: ellipsis` usually sits on an inner element - and such an element shrinks to the
 available width instead of stretching its parent, so measuring the host alone would find nothing.
 
 ## Styling
-The bubble carries inline styles built from tokens rather than a class from the shared stylesheet,
-exactly like the Angular directive — it is created outside React's tree, so there is nothing to
-attach a stylesheet rule to reliably.
+The bubble is created outside React's tree, so its look comes from `.kpt-tooltip` in `@konce-pt/styles`
+(see "Styling and the top layer" below), the same rule the Angular directive uses.
 
 ## Examples
     <KptTooltip text="Save changes" position="bottom"><KptButton>Save</KptButton></KptTooltip>
@@ -45,5 +44,8 @@ attach a stylesheet rule to reliably.
   the tooltip) and with `onlyWhenTruncated`, where the text is already in the DOM; the visible
   bubble is then `aria-hidden`.
 - `Escape` closes the bubble, and the pointer can move onto it without it disappearing (a 120 ms
-  grace period) — WCAG 1.4.13.
-- It does NOT replace an accessible name — an icon-only button still needs its own label.
+  grace period) - WCAG 1.4.13.
+- It does NOT replace an accessible name - an icon-only button still needs its own label.
+
+## Styling and the top layer
+The bubble is styled by `.kpt-tooltip` from `@konce-pt/styles`, in the `kpt.components` layer - override it from your own CSS without `!important`; only `position: fixed` and the coordinates stay inline. Inside an open `<dialog>` or popover the bubble is attached to that element, because a modal dialog lives in the top layer and anything outside it is hidden behind it regardless of `z-index`. A hover shows the bubble after 300 ms (sliding across a toolbar does not light every icon); focus shows it at once. Changing the text while the bubble is visible updates it.

package/dist/tooltip/tooltip.d.ts

@@ -9,18 +9,19 @@ export interface KptTooltipProps {
      * Dzięki temu podpowiedź nie powtarza tekstu, który i tak widać.
      */
     onlyWhenTruncated?: boolean;
-    /** Dokładnie jeden element — to on dostaje obsługę hovera i fokusu. */
+    /** Dokładnie jeden element - to on dostaje obsługę hovera i fokusu. */
     children: ReactNode;
 }
 /**
- * Dymek podpowiedzi pokazywany na hover i focus. Lekki — element dodawany do `body`
- * i pozycjonowany względem dziecka.
+ * Dymek podpowiedzi pokazywany na hover i focus. Lekki - element dodawany do `body` (albo do
+ * otwartego `<dialog>`/popovera dziecka, żeby był widoczny w warstwie szczytowej) i pozycjonowany
+ * względem dziecka. Wygląd daje klasa `.kpt-tooltip` z `@konce-pt/styles` w warstwie `kpt.components`.
  *
  * Port dyrektywy `[kptTooltip]`: nie renderuje własnego opakowania, tylko dokleja handlery
  * i ref do przekazanego elementu, więc drzewo DOM zostaje takie samo jak bez tooltipa.
  *
  * Dostępność (jak w porcie Angulara): tekst trafia do czytników przez trwały, ukryty opis
- * powiązany `aria-describedby` z elementem przyjmującym fokus — pomijany, gdy powtarzałby
+ * powiązany `aria-describedby` z elementem przyjmującym fokus - pomijany, gdy powtarzałby
  * jego nazwę albo przy `onlyWhenTruncated`. `Escape` zamyka dymek, a wskaźnik może na niego
  * przejść bez zniknięcia (WCAG 1.4.13).
  *