@konce-pt/react 0.8.3 → 0.8.5

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);

package/dist/mention/llms.txt

@@ -0,0 +1,60 @@
+# KptMention / KptMentions (@konce-pt/react)
+
+Mentions in text: `@someone` as an element you can hover to see a peek card with the rest of the
+connections. `KptMention` is a single mention; `KptMentions` turns a whole paragraph into text plus
+mentions.
+Import: `import { KptMention, KptMentions } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-mentions-host">
+      <span class="kpt-mentions__text">A question for </span>
+      <span class="kpt-peek-host kpt-mention-host">
+        <button class="kpt-mention" data-kind="person">@Anna Kowalska</button>
+      </span>
+      <span class="kpt-mentions__text"> about the estimate.</span>
+    </span>
+
+## KptMention — props
+- `item`: `KptMentionItem` — the whole entry at once; the single props below win over it
+- `id`, `label`, `kind`: string — `kind` lands in `data-kind`, so it can be styled per type
+- `prefix`: string (default '@'), `href`: string | null — with `href` the mention is a link
+- `placement`, `openDelay` — passed to `KptPeek`
+- `disabled`: boolean — no card; the mention stays a plain highlighted word
+- `children`: ReactNode — the card
+
+## KptMentions — props
+- `text`: string — the content with `@id` or `@[Name with spaces](id)`
+- `items`: `readonly KptMentionItem[]` — entries the ids resolve against
+- `prefix`, `placement` — passed to every mention
+- `renderCard`: `(item, id, label) => ReactNode` — the card; without it mentions are plain words
+
+## Example
+    <KptMentions
+      text={note}
+      items={people}
+      renderCard={(item, id, label) => <KptCard>{item?.data?.role ?? label}</KptCard>}
+    />
+
+## The text stays text
+`KptMentions` does not render HTML: the paragraph goes in as a plain string, `parseMentionText()`
+from `@konce-pt/mention` splits it into segments and the mention is an element the library builds
+itself. An application does not have to push user-written content through a sanitizer to get
+mentions out of it.
+
+An id that is not on the list still renders — the label falls back to the id, because a note has to
+stay readable after someone leaves the team. Without `renderCard` the mention is a highlighted
+word, not a button: there is nothing to open, so it does not pretend otherwise.
+
+## Mentions in the editor
+`KptRichText` takes `mentions`, `mentionLimit` and `onMention`: typing `@` opens the suggestion
+list, arrows and Enter (or Tab) insert the mention as
+`<span class="kpt-mention" data-mention="id" contenteditable="false">`. The id survives saving, and
+`contenteditable="false"` keeps the mention in one piece.
+
+## Tokens
+The mention is underlined with a **dotted** line: `--kpt-color-primary-border` at rest, darkening
+to `--kpt-color-primary` on hover and while the card is open. Dotted, not solid — a solid underline
+would read as a link, and a mention usually leads nowhere, it opens a card. Text
+`--kpt-color-primary`; a mention without a card `--kpt-color-text` + `--kpt-font-weight-medium` and
+no line at all, since there is nothing to promise. Focus ring `--kpt-color-focus-ring`. The card
+takes its own tokens from `KptPeek`.

package/dist/mention/mention.d.ts

@@ -0,0 +1,38 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import type { KptMentionItem } from '@konce-pt/mention';
+import { type KptPeekPlacement } from '../peek/peek.tsx';
+export interface KptMentionProps extends Omit<ComponentPropsWithRef<'span'>, 'id' | 'prefix' | 'children'> {
+    /** Cała pozycja naraz. Pojedyncze propsy poniżej mają nad nią priorytet. */
+    item?: KptMentionItem | null;
+    /** Identyfikator zapisany w treści — nie zmienia się przy zmianie nazwy. */
+    id?: string;
+    /** Nazwa do pokazania; bez niej bierze się ją z `item`, a w ostateczności z `id`. */
+    label?: string;
+    /** Rodzaj (osoba, zadanie, dokument) — ląduje w `data-kind`, więc da się go ostylować. */
+    kind?: string;
+    /** Znak przed nazwą. Pusty łańcuch zostawia samą nazwę. */
+    prefix?: string;
+    /** Adres, pod który prowadzi klik. Bez niego wzmianka jest przyciskiem otwierającym kartę. */
+    href?: string | null;
+    placement?: KptPeekPlacement;
+    openDelay?: number;
+    /** Wyłączona wzmianka nie otwiera karty — zostaje samym napisem. */
+    disabled?: boolean;
+    /** Treść karty. Bez niej wzmianka też zostaje napisem: nie ma czego pokazać. */
+    children?: ReactNode;
+}
+/**
+ * Wzmianka w tekście — `@ktoś` albo `@coś` jako element, na który da się najechać i zobaczyć
+ * kartę podglądu z resztą powiązań. Treść karty daje aplikacja przez `children`: biblioteka nie
+ * wie, czym jest wzmiankowana rzecz, a osoba, zadanie i dokument wyglądają inaczej.
+ *
+ * Wyzwalacz jest `<button>`, a nie `<span>`: karta otwiera się też z klawiatury i dotyku
+ * (przypięcie), a to wymaga elementu, na który da się wejść Tabem. Z `href` staje się linkiem,
+ * bo wtedy klik prowadzi gdzieś naprawdę.
+ *
+ * @example
+ * <KptMention id="anna.k" label="Anna Kowalska">
+ *   <KptCard>Profil, projekty, kontakt…</KptCard>
+ * </KptMention>
+ */
+export declare function KptMention({ item, id, label, kind, prefix, href, placement, openDelay, disabled, children, className, ...rest }: Readonly<KptMentionProps>): import("react").JSX.Element;

package/dist/mention/mention.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "../internal/cn.js";
+import { KptPeek } from "../peek/peek.js";
+/**
+ * Wzmianka w tekście — `@ktoś` albo `@coś` jako element, na który da się najechać i zobaczyć
+ * kartę podglądu z resztą powiązań. Treść karty daje aplikacja przez `children`: biblioteka nie
+ * wie, czym jest wzmiankowana rzecz, a osoba, zadanie i dokument wyglądają inaczej.
+ *
+ * Wyzwalacz jest `<button>`, a nie `<span>`: karta otwiera się też z klawiatury i dotyku
+ * (przypięcie), a to wymaga elementu, na który da się wejść Tabem. Z `href` staje się linkiem,
+ * bo wtedy klik prowadzi gdzieś naprawdę.
+ *
+ * @example
+ * <KptMention id="anna.k" label="Anna Kowalska">
+ *   <KptCard>Profil, projekty, kontakt…</KptCard>
+ * </KptMention>
+ */
+export function KptMention({ item = null, id = '', label = '', kind = '', prefix = '@', href = null, placement = 'bottom', openDelay = 300, disabled = false, children, className, ...rest }) {
+    const display = prefix + (label || item?.label || id || item?.id || '');
+    const resolvedKind = kind || item?.kind || undefined;
+    const plain = disabled || !children;
+    if (plain) {
+        // Bez karty wzmianka nie udaje kontrolki: zostaje wyróżnionym napisem, którego nie ma
+        // po co dotykać Tabem.
+        return (_jsx("span", { className: cn('kpt-mention-host', className), ...rest, children: _jsx("span", { className: "kpt-mention", "data-plain": "", "data-kind": resolvedKind, children: display }) }));
+    }
+    const trigger = href ? (_jsx("a", { className: "kpt-mention", href: href, "data-kind": resolvedKind, children: display })) : (_jsx("button", { type: "button", className: "kpt-mention", "data-kind": resolvedKind, children: display }));
+    return (_jsx(KptPeek, { className: cn('kpt-mention-host', className), trigger: trigger, placement: placement, openDelay: openDelay, label: display, ...rest, children: children }));
+}

package/dist/mention/mentions.d.ts

@@ -0,0 +1,31 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import { type KptMentionItem } from '@konce-pt/mention';
+import type { KptPeekPlacement } from '../peek/peek.tsx';
+export interface KptMentionsProps<T = unknown> extends Omit<ComponentPropsWithRef<'span'>, 'children' | 'prefix'> {
+    /** Treść z wzmiankami: `@id` albo `@[Nazwa ze spacją](id)`. */
+    text?: string;
+    /** Pozycje, po których rozwiązują się identyfikatory. Nieznane `id` zostaje etykietą. */
+    items?: readonly KptMentionItem<T>[];
+    /** Znak przed nazwą we wzmiance. */
+    prefix?: string;
+    placement?: KptPeekPlacement;
+    /** Karta wzmianki. Bez niej wzmianki są samym napisem, bo nie ma czego pokazać. */
+    renderCard?: (item: KptMentionItem<T> | null, id: string, label: string) => ReactNode;
+}
+/**
+ * Akapit ze wzmiankami — tekst wchodzi jako zwykły napis, a `@wzmianki` wychodzą z niego jako
+ * elementy z kartą podglądu. Rozbiciem zajmuje się `parseMentionText()` z `@konce-pt/mention`
+ * (czysty TS z testami), więc oba porty czytają tę samą treść tak samo.
+ *
+ * Wzmianek nie renderujemy z HTML-a: treść zostaje tekstem, a wzmianka jest elementem, który
+ * biblioteka sama zbudowała. Aplikacja nie musi więc przepuszczać przez sanitizer czegoś,
+ * co i tak pochodzi od jej użytkowników.
+ *
+ * @example
+ * <KptMentions
+ *   text={note}
+ *   items={people}
+ *   renderCard={(item, id, label) => <KptCard>{item?.data?.role ?? label}</KptCard>}
+ * />
+ */
+export declare function KptMentions<T = unknown>({ text, items, prefix, placement, renderCard, className, ...rest }: Readonly<KptMentionsProps<T>>): import("react").JSX.Element;

package/dist/mention/mentions.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { parseMentionText } from '@konce-pt/mention';
+import { cn } from "../internal/cn.js";
+import { KptMention } from "./mention.js";
+/**
+ * Akapit ze wzmiankami — tekst wchodzi jako zwykły napis, a `@wzmianki` wychodzą z niego jako
+ * elementy z kartą podglądu. Rozbiciem zajmuje się `parseMentionText()` z `@konce-pt/mention`
+ * (czysty TS z testami), więc oba porty czytają tę samą treść tak samo.
+ *
+ * Wzmianek nie renderujemy z HTML-a: treść zostaje tekstem, a wzmianka jest elementem, który
+ * biblioteka sama zbudowała. Aplikacja nie musi więc przepuszczać przez sanitizer czegoś,
+ * co i tak pochodzi od jej użytkowników.
+ *
+ * @example
+ * <KptMentions
+ *   text={note}
+ *   items={people}
+ *   renderCard={(item, id, label) => <KptCard>{item?.data?.role ?? label}</KptCard>}
+ * />
+ */
+export function KptMentions({ text = '', items = [], prefix = '@', placement = 'bottom', renderCard, className, ...rest }) {
+    const segments = parseMentionText(text, items);
+    return (_jsx("span", { className: cn('kpt-mentions-host', className), ...rest, children: segments.map((segment, index) => segment.kind === 'text' ? (_jsx("span", { className: "kpt-mentions__text", children: segment.text }, index)) : (_jsx(KptMention, { id: segment.id, label: segment.label, kind: segment.item?.kind ?? '', prefix: prefix, placement: placement, children: renderCard?.(segment.item, segment.id, segment.label) }, index))) }));
+}