@konce-pt/react 0.8.2 → 0.8.5

package/dist/chat-message/chat-message.d.ts

@@ -0,0 +1,53 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+import type { KptChatAttachment, KptChatAuthor, KptChatGroupPosition, KptChatMessage as KptChatMessageModel, KptChatReaction, KptChatReactionOption, KptChatReplyRef, KptChatStatus } from '@konce-pt/chat';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+/** Wygląd bąbla. `system` nie rysuje bąbla w ogóle — to komunikat, nie wypowiedź. */
+export type KptChatMessageVariant = 'neutral' | 'primary' | 'solid' | 'ghost' | 'system';
+export interface KptChatMessageProps extends Omit<ComponentPropsWithRef<'div'>, 'children'>, KptI18nOverrides {
+    /** Cała wiadomość naraz. Pojedyncze propsy poniżej mają nad nią priorytet. */
+    message?: KptChatMessageModel | null;
+    author?: KptChatAuthor | null;
+    text?: string | null;
+    time?: Date | string | number | null;
+    attachments?: readonly KptChatAttachment[] | null;
+    reactions?: readonly KptChatReaction[] | null;
+    replyTo?: KptChatReplyRef | null;
+    status?: KptChatStatus | null;
+    /** Strona listy: `start` to cudza wiadomość, `end` własna. */
+    align?: 'start' | 'end';
+    /** Wariant kolorystyczny; bez niego wynika z `align` (własna = `primary`). */
+    variant?: KptChatMessageVariant | null;
+    position?: KptChatGroupPosition;
+    system?: boolean;
+    showAuthor?: boolean;
+    showAvatar?: boolean;
+    showMeta?: boolean;
+    tail?: boolean;
+    /** Akcje pod kursorem: odpowiedz i zareaguj. Domyślnie wyłączone. */
+    actions?: boolean;
+    /** Zestaw wybieraka reakcji. Domyślnie pięć wbudowanych; można go skrócić lub przestawić. */
+    reactionOptions?: readonly KptChatReactionOption[];
+    onRetry?: () => void;
+    onReply?: () => void;
+    /** Wybrana reakcja (emoji). Biblioteka niczego nie dopisuje do modelu — robi to aplikacja. */
+    onReact?: (emoji: string) => void;
+    /** Kliknięcie w cytat — aplikacja może przewinąć listę do oryginału. */
+    onQuoted?: (quote: KptChatReplyRef) => void;
+    /** Treść bąbla. Wygrywa z `text`, więc bąbel przyjmuje cokolwiek. */
+    children?: ReactNode;
+}
+/**
+ * Pojedyncza wiadomość czatu — bąbel z treścią, godziną, statusem wysyłki i opcjonalnym
+ * awatarem, cytatem, załącznikami i reakcjami.
+ *
+ * Działa na dwa sposoby: dostaje gotowy obiekt przez `message` (tak używa go `KptChat`)
+ * albo pojedyncze propsy, gdy budujesz listę samodzielnie.
+ *
+ * Wygląd wewnątrz grupy steruje `position`: zapadnięty narożnik od strony nadawcy i ogonek
+ * tylko przy ostatnim bąblu. Wylicza to `buildChatRows()` z `@konce-pt/chat`.
+ *
+ * @example
+ * <KptChatMessage message={msg} align="end" position="last" />
+ * <KptChatMessage align="end" status="failed" onRetry={resend}>Nie poszło</KptChatMessage>
+ */
+export declare function KptChatMessage({ message, author, text, time, attachments, reactions, replyTo, status, align, variant, position, system, showAuthor, showAvatar, showMeta, tail, actions, reactionOptions, onRetry, onReply, onReact, onQuoted, children, locale, dictionary, className, ...rest }: Readonly<KptChatMessageProps>): import("react").JSX.Element;

package/dist/chat-message/chat-message.js

@@ -0,0 +1,112 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { KPT_CHAT_REACTIONS, canRetry, toDate } from '@konce-pt/chat';
+import { cn } from "../internal/cn.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
+import { KptAvatar } from "../avatar/avatar.js";
+import { KptIcon } from "../icon/icon.js";
+import { KptIconButton } from "../icon-button/icon-button.js";
+/** Ikona statusu wysyłki. `read` używa tej samej ikony co `delivered`, różni je kolor. */
+const STATUS_ICONS = {
+    sending: 'clock',
+    sent: 'check',
+    delivered: 'checks',
+    read: 'checks',
+    failed: 'alert-triangle',
+};
+/**
+ * Pojedyncza wiadomość czatu — bąbel z treścią, godziną, statusem wysyłki i opcjonalnym
+ * awatarem, cytatem, załącznikami i reakcjami.
+ *
+ * Działa na dwa sposoby: dostaje gotowy obiekt przez `message` (tak używa go `KptChat`)
+ * albo pojedyncze propsy, gdy budujesz listę samodzielnie.
+ *
+ * Wygląd wewnątrz grupy steruje `position`: zapadnięty narożnik od strony nadawcy i ogonek
+ * tylko przy ostatnim bąblu. Wylicza to `buildChatRows()` z `@konce-pt/chat`.
+ *
+ * @example
+ * <KptChatMessage message={msg} align="end" position="last" />
+ * <KptChatMessage align="end" status="failed" onRetry={resend}>Nie poszło</KptChatMessage>
+ */
+export function KptChatMessage({ message = null, author = null, text = null, time = null, attachments = null, reactions = null, replyTo = null, status = null, align = 'start', variant = null, position = 'single', system = false, showAuthor = false, showAvatar = false, showMeta = true, tail = true, actions = false, reactionOptions = KPT_CHAT_REACTIONS, onRetry, onReply, onReact, onQuoted, children, locale, dictionary, className, ...rest }) {
+    const { t, locale: activeLocale } = useKptMessages({ locale, dictionary });
+    const rowRef = useRef(null);
+    /** Czy wybierak reakcji jest otwarty. */
+    const [pickerOpen, setPickerOpen] = useState(false);
+    // Kliknięcie obok zamyka wybierak. Sam `onBlur` nie wystarcza: w Safari kliknięcie w przycisk
+    // nie przenosi na niego fokusu, więc wybierak zostawałby otwarty na zawsze. Faza przechwytywania
+    // i `pointerdown` (nie `click`) — własne `onClick` opcji zdąży się wykonać przed zamknięciem.
+    useEffect(() => {
+        if (!pickerOpen)
+            return;
+        const close = (event) => {
+            if (!rowRef.current?.contains(event.target))
+                setPickerOpen(false);
+        };
+        document.addEventListener('pointerdown', close, true);
+        return () => document.removeEventListener('pointerdown', close, true);
+    }, [pickerOpen]);
+    const isSystem = system || (message?.system ?? false);
+    const resolvedAuthor = author ?? message?.author ?? null;
+    const resolvedText = text ?? message?.text ?? '';
+    const resolvedStatus = status ?? message?.status ?? null;
+    const resolvedReplyTo = replyTo ?? message?.replyTo ?? null;
+    const resolvedAttachments = attachments ?? message?.attachments ?? [];
+    const resolvedReactions = reactions ?? message?.reactions ?? [];
+    const rawTime = time ?? message?.sentAt ?? null;
+    const sentAt = rawTime === null ? null : toDate(rawTime);
+    const timeLabel = sentAt
+        ? new Intl.DateTimeFormat(activeLocale, { hour: '2-digit', minute: '2-digit' }).format(sentAt)
+        : '';
+    /*
+     * Wariant domyślny bierze się z wyrównania. Własna wiadomość dostaje pełny `solid`,
+     * bo motyw biblioteki jest monochromatyczny: pastelowy `primary-subtle` ma tę samą
+     * jasność co `muted`, więc własny i cudzy bąbel byłyby nie do odróżnienia. Kto woli
+     * ciszej, ustawia `variant="primary"` ręcznie.
+     */
+    const resolvedVariant = isSystem
+        ? 'system'
+        : (variant ?? (align === 'end' ? 'solid' : 'neutral'));
+    /* Ogonek tylko na końcu grupy i tylko tam, gdzie bąbel ma tło, z którego da się go wyciąć. */
+    const hasTail = tail &&
+        resolvedVariant !== 'ghost' &&
+        resolvedVariant !== 'system' &&
+        (position === 'last' || position === 'single');
+    const statusIcon = resolvedStatus ? STATUS_ICONS[resolvedStatus] : null;
+    const retryable = canRetry(resolvedStatus);
+    /*
+     * Etykieta dla czytnika ekranu. Bez niej z bąbla płynie sama treść — bez nadawcy,
+     * godziny i informacji, że wiadomość się nie wysłała.
+     */
+    const ariaLabel = isSystem
+        ? resolvedText
+        : [resolvedAuthor?.name, timeLabel, resolvedStatus ? t('chat.' + resolvedStatus) : '']
+            .filter(Boolean)
+            .join(', ');
+    if (isSystem) {
+        return (_jsx("div", { className: cn('kpt-chat-message-host', className), role: "note", "aria-label": ariaLabel, ...rest, children: _jsx("p", { className: "kpt-chat-message__system", children: resolvedText }) }));
+    }
+    return (_jsx("div", { className: cn('kpt-chat-message-host', className), role: "article", "aria-label": ariaLabel, ...rest, children: _jsxs("div", { ref: rowRef, className: "kpt-chat-message__row", "data-align": align, children: [align === 'start' ? (_jsx("span", { className: "kpt-chat-message__avatar", "aria-hidden": "true", children: showAvatar ? (_jsx(KptAvatar, { size: "sm", src: resolvedAuthor?.avatar ?? null, name: resolvedAuthor?.name ?? '' })) : null })) : null, _jsxs("div", { className: "kpt-chat-message__stack", children: [showAuthor && resolvedAuthor ? (_jsx("span", { className: "kpt-chat-message__author", children: resolvedAuthor.name })) : null, _jsxs("div", { className: "kpt-chat-message__bubble", "data-variant": resolvedVariant, "data-align": align, "data-position": position, "data-status": resolvedStatus ?? undefined, "data-tail": hasTail ? '' : undefined, children: [resolvedReplyTo ? (_jsxs("button", { type: "button", className: "kpt-chat-message__quote", onClick: () => onQuoted?.(resolvedReplyTo), children: [_jsx("span", { className: "kpt-chat-message__quote-author", children: resolvedReplyTo.author }), _jsx("span", { className: "kpt-chat-message__quote-text", children: resolvedReplyTo.excerpt })] })) : null, resolvedText ? _jsx("p", { className: "kpt-chat-message__text", children: resolvedText }) : null, children, resolvedAttachments.length ? (_jsx("ul", { className: "kpt-chat-message__files", children: resolvedAttachments.map((file) => (_jsxs("li", { className: "kpt-chat-message__file", children: [file.thumbnail ? (_jsx("img", { className: "kpt-chat-message__file-thumb", src: file.thumbnail, alt: file.name })) : (_jsx(KptIcon, { name: "paperclip" })), _jsx("a", { className: "kpt-chat-message__file-name", href: file.url, download: file.url ? file.name : undefined, children: file.name }), file.size ? (_jsx("span", { className: "kpt-chat-message__file-size", children: fileSize(file.size) })) : null] }, file.id))) })) : null, showMeta ? (_jsxs("span", { className: "kpt-chat-message__meta", children: [timeLabel ? (_jsx("time", { className: "kpt-chat-message__time", dateTime: sentAt?.toISOString(), children: timeLabel })) : null, statusIcon ? (_jsx(KptIcon, { className: "kpt-chat-message__status", name: statusIcon })) : null] })) : null, resolvedReactions.length ? (_jsx("ul", { className: "kpt-chat-message__reactions", "data-align": align, children: resolvedReactions.map((reaction) => (_jsxs("li", { className: "kpt-chat-message__reaction", "data-reacted": reaction.reacted ? '' : undefined, children: [_jsx("span", { "aria-hidden": "true", children: reaction.emoji }), _jsx("span", { className: "kpt-chat-message__reaction-count", children: reaction.count })] }, reaction.emoji))) })) : null] })] }), _jsx("span", { className: "kpt-chat-message__actions", "data-open": pickerOpen ? '' : undefined, children: retryable ? (_jsx(KptIconButton, { hostProps: { className: 'kpt-chat-message__retry' }, size: "sm", "aria-label": t('chat.retry'), onClick: () => onRetry?.(), children: _jsx(KptIcon, { name: "refresh" }) })) : actions ? (_jsxs(_Fragment, { children: [_jsx(KptIconButton, { size: "sm", "aria-label": t('chat.replyTo', { author: resolvedAuthor?.name ?? '' }), onClick: () => onReply?.(), children: _jsx(KptIcon, { name: "corner-up-left" }) }), _jsxs("span", { className: "kpt-chat-message__react", onKeyDown: (event) => {
+                                    if (event.key === 'Escape')
+                                        setPickerOpen(false);
+                                }, onBlur: (event) => {
+                                    // Przechodzenie Tabem między opcjami wybieraka go nie zamyka.
+                                    if (!event.currentTarget.contains(event.relatedTarget))
+                                        setPickerOpen(false);
+                                }, children: [_jsx(KptIconButton, { size: "sm", "aria-label": t('chat.react'), "aria-expanded": pickerOpen, onClick: () => setPickerOpen((open) => !open), children: _jsx(KptIcon, { name: "mood-smile" }) }), pickerOpen ? (_jsx("span", { className: "kpt-chat-message__picker", role: "group", "aria-label": t('chat.react'), children: reactionOptions.map((option) => {
+                                            const label = t('chat.react' + option.kind[0].toUpperCase() + option.kind.slice(1));
+                                            const reacted = resolvedReactions.some((item) => item.emoji === option.emoji && item.reacted);
+                                            return (_jsx("button", { type: "button", className: "kpt-chat-message__pick", "aria-label": label, title: label, "aria-pressed": reacted, onClick: () => {
+                                                    onReact?.(option.emoji);
+                                                    setPickerOpen(false);
+                                                }, children: _jsx("span", { "aria-hidden": "true", children: option.emoji }) }, option.kind));
+                                        }) })) : null] })] })) : null })] }) }));
+}
+/** Rozmiar załącznika w kB/MB — surowe bajty nic nie mówią przy pliku obok nazwy. */
+function fileSize(bytes) {
+    if (bytes < 1024)
+        return bytes + ' B';
+    if (bytes < 1024 * 1024)
+        return Math.round(bytes / 1024) + ' kB';
+    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}

package/dist/chat-message/llms.txt

@@ -0,0 +1,73 @@
+# KptChatMessage (@konce-pt/react/chat)
+
+A single chat bubble: content, a clock, a send status, and optionally an avatar, a quote,
+attachments and reactions.
+Import: `import { KptChatMessage } from '@konce-pt/react/chat';`
+
+## DOM
+    <div class="kpt-chat-message-host" role="article" aria-label="Anna, 09:22, Read">
+      <div class="kpt-chat-message__row" data-align="start">
+        <span class="kpt-chat-message__avatar">…KptAvatar…</span>
+        <div class="kpt-chat-message__stack">
+          <span class="kpt-chat-message__author">Anna Kowalska</span>
+          <div class="kpt-chat-message__bubble"
+               data-variant="neutral" data-align="start" data-position="last" data-tail>
+            <button class="kpt-chat-message__quote">…</button>
+            <p class="kpt-chat-message__text">…</p>
+            <ul class="kpt-chat-message__files">…</ul>
+            <span class="kpt-chat-message__meta"><time>09:22</time>…</span>
+            <ul class="kpt-chat-message__reactions">…</ul>
+          </div>
+        </div>
+        <span class="kpt-chat-message__actions">…KptIconButton, .kpt-chat-message__picker…</span>
+      </div>
+    </div>
+
+## Props
+- `message`: `KptChatMessage` — the whole object; the single props below win over it
+- `author`, `text`, `time`, `status`, `attachments`, `reactions`, `replyTo`
+- `align`: `'start' | 'end'`; `variant`: `'neutral' | 'primary' | 'solid' | 'ghost' | 'system'`
+- `position`: `'single' | 'first' | 'middle' | 'last'`; `system`: boolean
+- `showAuthor`, `showAvatar`, `showMeta` (default true), `tail` (default true), `actions`
+- `reactionOptions`: `readonly KptChatReactionOption[]` (default `KPT_CHAT_REACTIONS`) — the picker set
+- `onRetry`, `onReply`: `() => void`; `onReact`: `(emoji: string) => void`; `onQuoted`: `(quote) => void`
+- `children` — bubble content; it renders next to `text`, so the bubble takes anything
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## The default variant follows the alignment
+Your own message gets the full `solid`, someone else's gets `neutral`. The theme is monochrome, so
+the difference between bubbles is lightness, not hue — `--kpt-color-primary-subtle` has exactly the
+lightness of `--kpt-color-muted`, which would make the two sides indistinguishable. For a quieter
+list set `variant="primary"` by hand.
+
+## Grouping is what the shape is made of
+`position` decides which corner collapses and which bubble wears the tail — inside a group the
+corner on the sender's side drops to `--kpt-radius-sm`. `KptChat` gets all of it from
+`buildChatRows()`; set it by hand only when you build the list yourself. The tail is skipped for
+`ghost` and `system`, which have no background to cut it out of.
+
+## An unsent message must be able to say so
+`status="failed"` outlines the bubble and puts a retry arrow **outside** it, in the action column
+on the outer side of the list. `KptChat` also keeps the meta row visible on such a bubble even in
+the middle of a group — the arrow with nothing to explain it would be a mystery.
+Statuses: `sending` (clock), `sent` (check), `delivered` (double check), `read` (the same icon in
+the accent colour) and `failed`.
+
+## Examples
+    <KptChatMessage message={msg} align="end" position="last" />
+    <KptChatMessage align="end" status="failed" onRetry={resend}>It did not go out</KptChatMessage>
+    <KptChatMessage system text="Anna joined the conversation" />
+
+## i18n
+`retry`, `react`, `replyTo` (`{author}`) and the status names from the `chat` namespace. The clock
+is formatted by `Intl` in the active locale.
+
+## Tokens
+`--kpt-color-muted` (incoming) / `--kpt-color-primary` + `--kpt-color-on-primary` (own),
+failed `--kpt-color-danger-subtle` + `--kpt-color-danger-border` — the failed rule also resets the
+text colour, or a white `solid` label would land on pale pink.
+
+## Accessibility
+The host is an `article` labelled with author, time and status — content alone would say nothing
+about who wrote it or whether it was sent. The status icon is `aria-hidden`; the meaning travels in
+the label. A system notice is a `note`, never an `article`.

package/dist/chat-typing/chat-typing.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentPropsWithRef } from 'react';
+import type { KptChatAuthor } from '@konce-pt/chat';
+import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
+export interface KptChatTypingProps extends Omit<ComponentPropsWithRef<'div'>, 'children'>, KptI18nOverrides {
+    /** Osoby piszące w tej chwili. Pusta lista chowa wskaźnik. */
+    authors?: readonly KptChatAuthor[];
+    /** Własna etykieta zamiast tej ze słownika. */
+    label?: string;
+}
+/**
+ * Wskaźnik pisania — trzy kropki i informacja, kto pisze.
+ *
+ * Pusta lista autorów nie renderuje niczego, więc można go trzymać w drzewie na stałe
+ * i sterować wyłącznie danymi.
+ *
+ * Element jest `role="status"` z `aria-live="polite"`: czytnik ogłasza wejście i zniknięcie
+ * wskaźnika, ale nie przerywa czytania wiadomości. Sama animacja kropek nic nie mówi —
+ * informację niesie etykieta.
+ *
+ * @example
+ * <KptChatTyping authors={typing} />
+ */
+export declare function KptChatTyping({ authors, label, locale, dictionary, className, ...rest }: Readonly<KptChatTypingProps>): import("react").JSX.Element | null;

package/dist/chat-typing/chat-typing.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../internal/cn.js";
+import { useKptMessages } from "../i18n/i18n-context.js";
+/**
+ * Wskaźnik pisania — trzy kropki i informacja, kto pisze.
+ *
+ * Pusta lista autorów nie renderuje niczego, więc można go trzymać w drzewie na stałe
+ * i sterować wyłącznie danymi.
+ *
+ * Element jest `role="status"` z `aria-live="polite"`: czytnik ogłasza wejście i zniknięcie
+ * wskaźnika, ale nie przerywa czytania wiadomości. Sama animacja kropek nic nie mówi —
+ * informację niesie etykieta.
+ *
+ * @example
+ * <KptChatTyping authors={typing} />
+ */
+export function KptChatTyping({ authors = [], label = '', locale, dictionary, className, ...rest }) {
+    const { t } = useKptMessages({ locale, dictionary });
+    if (authors.length === 0 && !label)
+        return null;
+    /*
+     * Jedna osoba jest wymieniona z imienia, przy większej liczbie liczy się głowy —
+     * lista nazwisk rozjeżdża wiersz i i tak nikt jej nie czyta.
+     */
+    const text = label ||
+        (authors.length === 1
+            ? t('chat.typing', { name: authors[0].name })
+            : t('chat.typingMany', { count: authors.length }));
+    return (_jsx("div", { className: cn('kpt-chat-typing-host', className), role: "status", "aria-live": "polite", ...rest, children: _jsxs("div", { className: "kpt-chat-typing", children: [_jsxs("span", { className: "kpt-chat-typing__bubble", "aria-hidden": "true", children: [_jsx("span", { className: "kpt-chat-typing__dot" }), _jsx("span", { className: "kpt-chat-typing__dot" }), _jsx("span", { className: "kpt-chat-typing__dot" })] }), text ? _jsx("span", { className: "kpt-chat-typing__label", children: text }) : null] }) }));
+}

package/dist/chat-typing/llms.txt

@@ -0,0 +1,41 @@
+# KptChatTyping (@konce-pt/react/chat)
+
+The typing indicator — three dots and a line saying who is typing.
+Import: `import { KptChatTyping } from '@konce-pt/react/chat';`
+
+## DOM
+    <div class="kpt-chat-typing-host" role="status" aria-live="polite">
+      <div class="kpt-chat-typing">
+        <span class="kpt-chat-typing__bubble" aria-hidden="true">
+          <span class="kpt-chat-typing__dot"></span>
+          <span class="kpt-chat-typing__dot"></span>
+          <span class="kpt-chat-typing__dot"></span>
+        </span>
+        <span class="kpt-chat-typing__label">Anna is typing…</span>
+      </div>
+    </div>
+
+## Props
+- `authors`: `KptChatAuthor[]` — an empty list renders nothing at all
+- `label`: string — your own wording instead of the dictionary's
+- `className`, `ref` and every other `<div>` prop go to the host
+
+## One name, then a headcount
+One person is named; from two up the component counts heads. A list of names breaks the line and
+nobody reads it anyway.
+
+## Examples
+    <KptChatTyping authors={[anna]} />
+    <KptChatTyping authors={typing} />
+    <KptChatTyping label="The assistant is thinking…" />
+
+## i18n
+`typing` (`{name}`) and `typingMany` (`{count}`) from the `chat` namespace.
+
+## Tokens
+The bubble `--kpt-color-surface-variant`, the dots `--kpt-color-text-muted`.
+
+## Accessibility
+`role="status"` with `aria-live="polite"` announces the indicator without interrupting a message
+being read. Under `prefers-reduced-motion` the dots stop bouncing and pulse instead — they are the
+only carrier of "someone is typing", so switching them off entirely would remove the message.

package/dist/chip/chip.d.ts

@@ -2,8 +2,16 @@ import type { ComponentPropsWithRef } from 'react';
 import { type KptI18nOverrides } from '../i18n/i18n-context.tsx';
 import type { KptHostProps } from '../internal/types.ts';
 export type KptChipVariant = 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info';
+/** Wielkość liter etykiety. */
+export type KptChipTextTransform = 'none' | 'capitalize' | 'uppercase' | 'lowercase';
 export interface KptChipProps extends ComponentPropsWithRef<'span'>, KptI18nOverrides {
     variant?: KptChipVariant;
+    /**
+     * Wielkość liter etykiety. `capitalize` podnosi pierwszą literę każdego słowa — także po
+     * dywizie („Agent-Ready"), bo CSS nie wie, gdzie kończy się wyraz złożony; przy takich
+     * napisach pewniejszy jest zapis wprost w treści.
+     */
+    textTransform?: KptChipTextTransform;
     /** Dokłada przycisk usuwania. */
     removable?: boolean;
     disabled?: boolean;
@@ -18,5 +26,6 @@ export interface KptChipProps extends ComponentPropsWithRef<'span'>, KptI18nOver
  * @example
  * <KptChip>Angular</KptChip>
  * <KptChip variant="success" removable onRemove={remove}>UI</KptChip>
+ * <KptChip textTransform="capitalize">nowość · zestaw startowy</KptChip>
  */
-export declare function KptChip({ variant, removable, disabled, onRemove, locale, dictionary, hostProps, className, children, ...rest }: Readonly<KptChipProps>): import("react").JSX.Element;
+export declare function KptChip({ variant, textTransform, removable, disabled, onRemove, locale, dictionary, hostProps, className, children, ...rest }: Readonly<KptChipProps>): import("react").JSX.Element;

package/dist/chip/chip.js

@@ -8,9 +8,10 @@ import { useKptMessages } from "../i18n/i18n-context.js";
  * @example
  * <KptChip>Angular</KptChip>
  * <KptChip variant="success" removable onRemove={remove}>UI</KptChip>
+ * <KptChip textTransform="capitalize">nowość · zestaw startowy</KptChip>
  */
-export function KptChip({ variant = 'neutral', removable = false, disabled = false, onRemove, locale, dictionary, hostProps, className, children, ...rest }) {
+export function KptChip({ variant = 'neutral', textTransform = 'none', removable = false, disabled = false, onRemove, locale, dictionary, hostProps, className, children, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const { className: hostClassName, ...hostRest } = hostProps ?? {};
-    return (_jsx("span", { className: cn('kpt-chip-host', hostClassName), ...hostRest, children: _jsxs("span", { className: cn('kpt-chip', disabled && 'kpt-chip--disabled', className), "data-variant": variant, ...rest, children: [children, removable ? (_jsx("button", { type: "button", className: "kpt-chip__remove", disabled: disabled, onClick: onRemove, "aria-label": t('common.remove'), children: _jsx(KptIcon, { name: "x" }) })) : null] }) }));
+    return (_jsx("span", { className: cn('kpt-chip-host', hostClassName), ...hostRest, children: _jsxs("span", { className: cn('kpt-chip', disabled && 'kpt-chip--disabled', className), "data-variant": variant, "data-text-transform": textTransform === 'none' ? undefined : textTransform, ...rest, children: [children, removable ? (_jsx("button", { type: "button", className: "kpt-chip__remove", disabled: disabled, onClick: onRemove, "aria-label": t('common.remove'), children: _jsx(KptIcon, { name: "x" }) })) : null] }) }));
 }

package/dist/chip/llms.txt

@@ -13,6 +13,7 @@ Import: `import { KptChip } from '@konce-pt/react';`
 
 ## Props
 - `variant`: 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info' (default 'neutral')
+- `textTransform`: 'none' | 'capitalize' | 'uppercase' | 'lowercase' (default 'none') — the label's letter case
 - `removable`: boolean — adds the remove button
 - `disabled`: boolean
 - `onRemove()` — fired by the remove button
@@ -31,6 +32,14 @@ The remove button's label comes from `common.remove` in the dictionary.
     <KptChip>React</KptChip>
     <KptChip variant="success" removable onRemove={() => drop(tag)}>UI</KptChip>
     <KptCard.Tags><KptChip variant="info">Daily</KptChip></KptCard.Tags>
+    <KptChip textTransform="capitalize">new · starter kit</KptChip>
+
+## Letter case
+`textTransform` lands as `data-text-transform` on `.kpt-chip` and sets `text-transform` there, so
+the label can stay in the application's own wording while the chip decides how it is displayed.
+`capitalize` raises the first letter of every word — **including after a hyphen**
+("Agent-Ready"), because CSS does not know where a compound word ends. For labels with a hyphen,
+spelling it out in the content is the exact route.
 
 ## Tokens
 `--kpt-color-muted`, `--kpt-color-on-muted` and the semantic colour pairs of each variant

package/dist/data-view/data-view.d.ts

@@ -6,8 +6,20 @@ export interface KptDataViewProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     layout?: KptDataViewLayout;
     defaultLayout?: KptDataViewLayout;
     onLayoutChange?: (layout: KptDataViewLayout) => void;
-    /** Rozmiar strony; 0 wyłącza stronicowanie. */
+    /** Rozmiar strony; 0 wyłącza stronicowanie. Sterowalny — select paginatora go zmienia. */
     pageSize?: number;
+    defaultPageSize?: number;
+    onPageSizeChange?: (pageSize: number) => void;
+    /** Rozmiary do wyboru w paginatorze. Pusta lista = select z jedną, bieżącą wartością. */
+    pageSizeOptions?: readonly number[];
+    /** Liczba kolumn siatki jako SUFIT, nie sztywna liczba; 0 = tyle, ile się zmieści. */
+    gridColumns?: number;
+    defaultGridColumns?: number;
+    onGridColumnsChange?: (columns: number) => void;
+    /** Wartości w pasku gęstości. Mniej niż dwie = paska nie ma po co pokazywać. */
+    gridColumnsOptions?: readonly number[];
+    /** Najwęższa sensowna karta — poniżej tego siatka zdejmuje kolumnę, zamiast ściskać. */
+    gridMinWidth?: string;
     paginated?: boolean;
     /** Szablon elementu — odpowiednik `<ng-template let-item>` z Angulara. */
     renderItem: (item: T, index: number) => ReactNode;
@@ -16,6 +28,6 @@ export interface KptDataViewProps<T> extends Omit<ComponentPropsWithRef<'div'>,
  * DataView — lista elementów w układzie listy albo siatki, z opcjonalnym stronicowaniem.
  *
  * @example
- * <KptDataView items={products} pageSize={6} renderItem={(p) => <div>{p.name}</div>} />
+ * <KptDataView items={products} defaultPageSize={6} renderItem={(p) => <div>{p.name}</div>} />
  */
-export declare function KptDataView<T>({ items, layout, defaultLayout, onLayoutChange, pageSize, paginated, renderItem, locale, dictionary, className, ...rest }: Readonly<KptDataViewProps<T>>): import("react").JSX.Element;
+export declare function KptDataView<T>({ items, layout, defaultLayout, onLayoutChange, pageSize, defaultPageSize, onPageSizeChange, pageSizeOptions, gridColumns, defaultGridColumns, onGridColumnsChange, gridColumnsOptions, gridMinWidth, paginated, renderItem, locale, dictionary, className, ...rest }: Readonly<KptDataViewProps<T>>): import("react").JSX.Element;

package/dist/data-view/data-view.js

@@ -9,17 +9,34 @@ import { KptPaginator } from "../paginator/paginator.js";
  * DataView — lista elementów w układzie listy albo siatki, z opcjonalnym stronicowaniem.
  *
  * @example
- * <KptDataView items={products} pageSize={6} renderItem={(p) => <div>{p.name}</div>} />
+ * <KptDataView items={products} defaultPageSize={6} renderItem={(p) => <div>{p.name}</div>} />
  */
-export function KptDataView({ items = [], layout, defaultLayout = 'grid', onLayoutChange, pageSize = 0, paginated = true, renderItem, locale, dictionary, className, ...rest }) {
+export function KptDataView({ items = [], layout, defaultLayout = 'grid', onLayoutChange, pageSize, defaultPageSize = 0, onPageSizeChange, pageSizeOptions = [], gridColumns, defaultGridColumns = 0, onGridColumnsChange, gridColumnsOptions = [], gridMinWidth = '10rem', paginated = true, renderItem, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const [currentLayout, setLayout] = useControllableState({
         value: layout,
         defaultValue: defaultLayout,
         onChange: onLayoutChange,
     });
+    const [size, setSize] = useControllableState({
+        value: pageSize,
+        defaultValue: defaultPageSize,
+        onChange: onPageSizeChange,
+    });
+    const [columns, setColumns] = useControllableState({
+        value: gridColumns,
+        defaultValue: defaultGridColumns,
+        onChange: onGridColumnsChange,
+    });
     const [pageIndex, setPageIndex] = useState(0);
-    const showPager = paginated && pageSize > 0 && items.length > pageSize;
-    const pageItems = !paginated || pageSize <= 0 ? items : items.slice(pageIndex * pageSize, pageIndex * pageSize + pageSize);
-    return (_jsx("div", { className: cn('kpt-data-view-host', className), ...rest, children: _jsxs("div", { className: "kpt-data-view", children: [_jsxs("div", { className: "kpt-data-view__toolbar", children: [_jsx("div", { className: "kpt-data-view__count", children: t('dataView.count', { count: items.length }) }), _jsxs("div", { className: "kpt-data-view__switch", children: [_jsx("button", { type: "button", className: cn(currentLayout === 'list' && 'is-active'), "aria-label": t('dataView.list'), onClick: () => setLayout('list'), children: _jsx(KptIcon, { name: "list" }) }), _jsx("button", { type: "button", className: cn(currentLayout === 'grid' && 'is-active'), "aria-label": t('dataView.grid'), onClick: () => setLayout('grid'), children: _jsx(KptIcon, { name: "menu" }) })] })] }), _jsx("div", { className: "kpt-data-view__content", "data-layout": currentLayout, children: pageItems.length ? (pageItems.map((item, index) => (_jsx("div", { className: "kpt-data-view__item", children: renderItem(item, index) }, index)))) : (_jsx("div", { className: "kpt-data-view__empty", children: t('dataView.empty') })) }), showPager ? (_jsx(KptPaginator, { length: items.length, pageIndex: pageIndex, onPageIndexChange: setPageIndex, pageSize: pageSize, pageSizeOptions: [pageSize] })) : null] }) }));
+    // Opcje selecta: własna lista albo — gdy pusta — sam bieżący rozmiar.
+    const pagerSizeOptions = pageSizeOptions.length ? pageSizeOptions : [size];
+    // Pager zostaje na ekranie także wtedy, gdy wszystko mieści się na jednej stronie, o ile jest
+    // w czym wybierać. Bez tego wybranie największego rozmiaru chowa select, którym użytkownik
+    // właśnie się posłużył — i nie ma jak wrócić do mniejszego.
+    // Pasek gęstości ma sens tylko w siatce i tylko wtedy, gdy jest w czym wybierać.
+    const showColumns = currentLayout === 'grid' && gridColumnsOptions.length > 1;
+    const showPager = paginated && size > 0 && (items.length > size || pagerSizeOptions.length > 1);
+    const pageItems = !paginated || size <= 0 ? items : items.slice(pageIndex * size, pageIndex * size + size);
+    return (_jsx("div", { className: cn('kpt-data-view-host', className), ...rest, children: _jsxs("div", { className: "kpt-data-view", children: [_jsxs("div", { className: "kpt-data-view__toolbar", children: [_jsx("div", { className: "kpt-data-view__count", children: t('dataView.count', { count: items.length }) }), _jsxs("div", { className: "kpt-data-view__controls", children: [showColumns ? (_jsx("div", { className: "kpt-data-view__columns", role: "group", "aria-label": t('dataView.columns'), children: gridColumnsOptions.map((n) => (_jsxs("button", { type: "button", className: cn(columns === n && 'is-active'), "aria-pressed": columns === n, onClick: () => setColumns(n), children: [_jsx(KptIcon, { name: "grid-dots" }), n] }, n))) })) : null, _jsxs("div", { className: "kpt-data-view__switch", children: [_jsx("button", { type: "button", className: cn(currentLayout === 'list' && 'is-active'), "aria-label": t('dataView.list'), "aria-pressed": currentLayout === 'list', onClick: () => setLayout('list'), children: _jsx(KptIcon, { name: "list" }) }), _jsx("button", { type: "button", className: cn(currentLayout === 'grid' && 'is-active'), "aria-label": t('dataView.grid'), "aria-pressed": currentLayout === 'grid', onClick: () => setLayout('grid'), children: _jsx(KptIcon, { name: "layout-grid" }) })] })] })] }), _jsx("div", { className: "kpt-data-view__content", "data-layout": currentLayout, "data-columns": columns ? '' : undefined, style: { '--_min': gridMinWidth, '--_cols': columns || undefined }, children: pageItems.length ? (pageItems.map((item, index) => (_jsx("div", { className: "kpt-data-view__item", children: renderItem(item, index) }, index)))) : (_jsx("div", { className: "kpt-data-view__empty", children: t('dataView.empty') })) }), showPager ? (_jsx(KptPaginator, { length: items.length, pageIndex: pageIndex, onPageIndexChange: setPageIndex, pageSize: size, onPageSizeChange: setSize, pageSizeOptions: pagerSizeOptions })) : null] }) }));
 }

package/dist/data-view/llms.txt

@@ -20,7 +20,11 @@ Import: `import { KptDataView } from '@konce-pt/react';`
 ## Props
 - `items`: `T[]`
 - `layout` / `defaultLayout` / `onLayoutChange` — `'list' | 'grid'` (default `'grid'`)
-- `pageSize`: number — 0 turns pagination off
+- `pageSize` / `defaultPageSize` / `onPageSizeChange` — number; 0 turns pagination off
+- `pageSizeOptions`: number[] (empty = the select offers the current size only)
+- `gridColumns` / `defaultGridColumns` / `onGridColumnsChange` — number; 0 = as many as fit
+- `gridColumnsOptions`: number[] (fewer than two = no density bar)
+- `gridMinWidth`: string (default `10rem`) — the narrowest card worth rendering
 - `paginated`: boolean (default true)
 - `renderItem(item, index)` — required; the equivalent of `<ng-template let-item>`
 - `className`, `ref` and every other `<div>` prop go to the host
@@ -29,20 +33,29 @@ Import: `import { KptDataView } from '@konce-pt/react';`
 `data-layout` on the content switches the grid rules; the toolbar only flips it. Everything else —
 the item's markup — is the caller's, which is why there are no card props here.
 
+## The column count is a ceiling
+The density bar shows up in the grid layout when `gridColumnsOptions` holds more than one value.
+The chosen number caps the grid rather than pinning it: the track minimum grows to the width of
+one of N columns, so a narrow container drops to two or one column instead of squeezing cards
+below `gridMinWidth`.
+
 ## The pager appears when it is needed
-Only when `paginated`, `pageSize > 0` and there are more items than fit on a page — a paginator
-under a single page of results is noise.
+Only when `paginated`, the page size is above 0, and either the items outgrow one page or
+`pageSizeOptions` holds more than one size — a paginator under a single page of results is noise,
+but hiding it right after someone picks the largest size would strand them there.
 
 ## Examples
-    <KptDataView items={products} pageSize={6} renderItem={(p) => <div>{p.name}</div>} />
+    <KptDataView items={products} defaultPageSize={6} renderItem={(p) => <div>{p.name}</div>} />
+    <KptDataView items={products} defaultPageSize={6} pageSizeOptions={[3, 6, 9]} renderItem={renderCard} />
+    <KptDataView items={products} defaultGridColumns={2} gridColumnsOptions={[2, 3, 4]} gridMinWidth="14rem" renderItem={renderCard} />
     <KptDataView items={products} layout="list" paginated={false} renderItem={renderCard} />
 
 ## i18n
-The count and the two switch buttons come from the `dataView` namespace (`count` with `{count}`,
-`list`, `grid`, `empty`).
+The count, the two switch buttons and the density group come from the `dataView` namespace
+(`count` with `{count}`, `list`, `grid`, `columns`, `empty`).
 
 ## Tokens
-The grid gap `--kpt-space-4`, the active switch `--kpt-color-primary`.
+The grid gap `--kpt-space-3`, the active switch `--kpt-color-primary`.
 
 ## Accessibility
 Both layout buttons carry labels from the dictionary; an empty list renders a message instead of

package/dist/internal/dev.d.ts

@@ -0,0 +1 @@
+export declare function isDevBuild(): boolean;

package/dist/internal/dev.js

@@ -0,0 +1,3 @@
+export function isDevBuild() {
+    return typeof process !== 'undefined' && process?.env?.['NODE_ENV'] !== 'production';
+}

package/dist/internal/overlay.d.ts

@@ -21,6 +21,11 @@ export interface KptOverlayProps {
      * zasłoniłby to pole i zabrałby mu każde kliknięcie.
      */
     withBackdrop?: boolean;
+    /**
+     * Otwieraj nad wyzwalaczem, dopóki jest tam miejsce (odpowiednik `placement="top"` w porcie
+     * Angulara, gdzie kolejnością pozycji steruje CDK). Bez tego panel wychodzi spod wyzwalacza.
+     */
+    preferAbove?: boolean;
     children: ReactNode;
 }
-export declare function KptOverlay({ open, anchor, onClose, matchAnchorWidth, offset, align, withBackdrop, children, }: Readonly<KptOverlayProps>): import("react").ReactPortal | null;
+export declare function KptOverlay({ open, anchor, onClose, matchAnchorWidth, offset, align, withBackdrop, preferAbove, children, }: Readonly<KptOverlayProps>): import("react").ReactPortal | null;

package/dist/internal/overlay.js

@@ -4,7 +4,7 @@ import { createPortal } from 'react-dom';
 import { useKptOverlayContainer } from "./overlay-container.js";
 /** Ta sama warstwa co `--kpt-z-overlay` w tokenach — panel ma być nad treścią aplikacji. */
 const Z_INDEX = 'var(--kpt-z-overlay, 1100)';
-export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, offset = 4, align = 'start', withBackdrop = true, children, }) {
+export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, offset = 4, align = 'start', withBackdrop = true, preferAbove = false, children, }) {
     const container = useKptOverlayContainer();
     const panelRef = useRef(null);
     const [position, setPosition] = useState(null);
@@ -17,13 +17,15 @@ export function KptOverlay({ open, anchor, onClose, matchAnchorWidth = false, of
         const below = window.innerHeight - rect.bottom;
         // Odbicie w górę tylko wtedy, gdy pod spodem naprawdę brakuje miejsca, a nad wyzwalaczem
         // jest go więcej — inaczej panel skakałby przy każdym przewinięciu o kilka pikseli.
-        const flip = panelHeight > 0 && below < panelHeight + offset && rect.top > below;
+        // Przy `preferAbove` jest odwrotnie: panel stoi nad wyzwalaczem, dopóki się tam mieści.
+        const fitsAbove = panelHeight === 0 || rect.top > panelHeight + offset;
+        const flip = preferAbove ? fitsAbove : panelHeight > 0 && below < panelHeight + offset && rect.top > below;
         setPosition({
             top: flip ? rect.top - panelHeight - offset : rect.bottom + offset,
             left: align === 'end' ? rect.right - panelWidth : rect.left,
             ...(matchAnchorWidth ? { width: rect.width } : {}),
         });
-    }, [anchor, matchAnchorWidth, offset, align]);
+    }, [anchor, matchAnchorWidth, offset, align, preferAbove]);
     useLayoutEffect(() => {
         if (!open) {
             setPosition(null);