@konce-pt/react 0.8.2 → 0.8.5

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

package/dist/order-list/llms.txt

@@ -1,6 +1,7 @@
 # KptOrderList (@konce-pt/react)
 
-A list with manual reordering. Click selects an item, the buttons move it up and down.
+A list with manual reordering. Click selects an item, the buttons move it up and down, and
+`dragdrop` lets you drag it into place.
 Import: `import { KptOrderList } from '@konce-pt/react';`
 
 ## DOM
@@ -19,23 +20,33 @@ Import: `import { KptOrderList } from '@konce-pt/react';`
 ## Props
 - `items` / `defaultItems` / `onItemsChange` — the list; the callback receives the new order
 - `header`: string
+- `dragdrop` — `false` by default; enables dragging (opt-in, nothing changes without it)
 - `renderItem(item, index)` — required; the equivalent of `<ng-template let-item>`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The selection follows the item
 After a move the selection jumps to the new index, so pressing the button again moves the same
-entry — with the selection pinned to a position, the second press would move its neighbour.
+entry — with the selection pinned to a position, the second press would move its neighbour. A drop
+does the same.
+
+## Where a dragged item lands
+Dropping onto a row puts the dragged item at that row's position and everything else shifts, while
+the buttons keep swapping with the neighbour. Dropping on the empty part of the list appends at the
+end. While a drag is running the row under the cursor carries a `--dragover` modifier and the
+dragged one `is-dragging`.
 
 ## Examples
-    <KptOrderList items={tasks} onItemsChange={setTasks} header="Order" renderItem={(item) => item} />
+    <KptOrderList items={tasks} onItemsChange={setTasks} header="Order" dragdrop renderItem={(item) => item} />
     <KptOrderList defaultItems={steps} renderItem={(step) => step.name} />
 
 ## i18n
-The buttons use `orderList.up` and `orderList.down`.
+The buttons use `orderList.up` and `orderList.down`. Dragging carries no visible label, so it adds
+no dictionary keys.
 
 ## Tokens
 The selection `--kpt-color-primary`, the buttons `--kpt-color-surface-raised`.
 
 ## Accessibility
 Both buttons are labelled from the dictionary and go disabled while nothing is selected, so the
-control never looks broken.
+control never looks broken. Native HTML5 drag and drop has no keyboard equivalent, so they stay the
+full keyboard path — `dragdrop` never replaces them.

package/dist/order-list/order-list.d.ts

@@ -5,14 +5,16 @@ export interface KptOrderListProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     defaultItems?: T[];
     onItemsChange?: (items: T[]) => void;
     header?: string;
+    /** Włącza przestawianie pozycji metodą przeciągnij-i-upuść. */
+    dragdrop?: boolean;
     /** Szablon elementu — odpowiednik `<ng-template let-item>` z Angulara. */
     renderItem: (item: T, index: number) => ReactNode;
 }
 /**
  * OrderList — lista z ręcznym porządkowaniem. Klik zaznacza element, przyciski przesuwają go
- * w górę i w dół.
+ * w górę i w dół. Z `dragdrop` pozycje przestawia się także przeciąganiem.
  *
  * @example
- * <KptOrderList items={tasks} onItemsChange={setTasks} header="Kolejność" renderItem={(t) => t.name} />
+ * <KptOrderList items={tasks} onItemsChange={setTasks} header="Kolejność" dragdrop renderItem={(t) => t.name} />
  */
-export declare function KptOrderList<T>({ items, defaultItems, onItemsChange, header, renderItem, locale, dictionary, className, ...rest }: Readonly<KptOrderListProps<T>>): import("react").JSX.Element;
+export declare function KptOrderList<T>({ items, defaultItems, onItemsChange, header, dragdrop, renderItem, locale, dictionary, className, ...rest }: Readonly<KptOrderListProps<T>>): import("react").JSX.Element;

package/dist/order-list/order-list.js

@@ -7,12 +7,12 @@ import { KptIcon } from "../icon/icon.js";
 const EMPTY = [];
 /**
  * OrderList — lista z ręcznym porządkowaniem. Klik zaznacza element, przyciski przesuwają go
- * w górę i w dół.
+ * w górę i w dół. Z `dragdrop` pozycje przestawia się także przeciąganiem.
  *
  * @example
- * <KptOrderList items={tasks} onItemsChange={setTasks} header="Kolejność" renderItem={(t) => t.name} />
+ * <KptOrderList items={tasks} onItemsChange={setTasks} header="Kolejność" dragdrop renderItem={(t) => t.name} />
  */
-export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, header = '', renderItem, locale, dictionary, className, ...rest }) {
+export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, header = '', dragdrop = false, renderItem, locale, dictionary, className, ...rest }) {
     const { t } = useKptMessages({ locale, dictionary });
     const [list, setList] = useControllableState({
         value: items,
@@ -20,6 +20,12 @@ export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, heade
         onChange: onItemsChange,
     });
     const [selected, setSelected] = useState(null);
+    /** Indeks przeciąganej pozycji; `null` gdy nic nie jest przeciągane. */
+    const [dragIndex, setDragIndex] = useState(null);
+    /** Indeks pozycji pod kursorem — rysuje wskaźnik miejsca upuszczenia. */
+    const [overIndex, setOverIndex] = useState(null);
+    /** Kursor nad pustym obszarem listy — upuszczenie tam dopina na koniec. */
+    const [listOver, setListOver] = useState(false);
     const move = (dir) => {
         if (selected === null)
             return;
@@ -33,5 +39,64 @@ export function KptOrderList({ items, defaultItems = EMPTY, onItemsChange, heade
         // przesuwałoby sąsiada zamiast tego samego wpisu.
         setSelected(target);
     };
-    return (_jsx("div", { className: cn('kpt-order-list-host', className), ...rest, children: _jsxs("div", { className: "kpt-order-list", children: [_jsxs("div", { className: "kpt-order-list__controls", children: [_jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.up'), onClick: () => move(-1), children: _jsx(KptIcon, { name: "arrow-up" }) }), _jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.down'), onClick: () => move(1), children: _jsx(KptIcon, { name: "arrow-down" }) })] }), _jsxs("div", { className: "kpt-order-list__panel", children: [header ? _jsx("div", { className: "kpt-order-list__header", children: header }) : null, _jsx("ul", { className: "kpt-order-list__items", children: list.map((item, index) => (_jsx("li", { className: cn('kpt-order-list__item', selected === index && 'is-selected'), onClick: () => setSelected(index), children: renderItem(item, index) }, index))) })] })] }) }));
+    const clearDrag = () => {
+        setDragIndex(null);
+        setOverIndex(null);
+        setListOver(false);
+    };
+    const onDragStart = (index, event) => {
+        if (!dragdrop)
+            return;
+        setDragIndex(index);
+        event.dataTransfer.setData('text/plain', String(index));
+        event.dataTransfer.effectAllowed = 'move';
+    };
+    const onDragOver = (index, event) => {
+        if (dragIndex === null)
+            return;
+        // Zatrzymujemy propagację, żeby `<ul>` nie uznał, że kursor jest nad pustym obszarem.
+        event.preventDefault();
+        event.stopPropagation();
+        setOverIndex(index);
+        setListOver(false);
+    };
+    const onDrop = (index, event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        const from = dragIndex;
+        clearDrag();
+        if (from === null || from === index)
+            return;
+        // Indeks celu liczony na tablicy sprzed usunięcia — element ląduje na pozycji tego,
+        // na który go upuszczono (ten sam wzór co przestawianie kolumn w KptDataTable).
+        const next = [...list];
+        const [moved] = next.splice(from, 1);
+        if (moved === undefined)
+            return;
+        next.splice(index, 0, moved);
+        setList(next);
+        setSelected(index);
+    };
+    const onListDragOver = (event) => {
+        if (dragIndex === null)
+            return;
+        event.preventDefault();
+        setListOver(true);
+        setOverIndex(null);
+    };
+    const onListDrop = (event) => {
+        event.preventDefault();
+        const from = dragIndex;
+        clearDrag();
+        if (from === null)
+            return;
+        const next = [...list];
+        const [moved] = next.splice(from, 1);
+        if (moved === undefined)
+            return;
+        next.push(moved);
+        setList(next);
+        setSelected(next.length - 1);
+    };
+    return (_jsx("div", { className: cn('kpt-order-list-host', className), ...rest, children: _jsxs("div", { className: "kpt-order-list", children: [_jsxs("div", { className: "kpt-order-list__controls", children: [_jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.up'), onClick: () => move(-1), children: _jsx(KptIcon, { name: "arrow-up" }) }), _jsx("button", { type: "button", disabled: selected === null, "aria-label": t('orderList.down'), onClick: () => move(1), children: _jsx(KptIcon, { name: "arrow-down" }) })] }), _jsxs("div", { className: "kpt-order-list__panel", children: [header ? _jsx("div", { className: "kpt-order-list__header", children: header }) : null, _jsx("ul", { className: cn('kpt-order-list__items', listOver && 'is-dragover'), onDragOver: onListDragOver, onDragLeave: () => setListOver(false), onDrop: onListDrop, children: list.map((item, index) => (_jsx("li", { className: cn('kpt-order-list__item', selected === index && 'is-selected', dragIndex === index && 'is-dragging', dragdrop && 'kpt-order-list__item--draggable', overIndex === index && dragIndex !== index && 'kpt-order-list__item--dragover'), draggable: dragdrop || undefined, onClick: () => setSelected(index), onDragStart: (event) => onDragStart(index, event), onDragOver: (event) => onDragOver(index, event), onDragLeave: () => setOverIndex(null), onDrop: (event) => onDrop(index, event), onDragEnd: clearDrag, children: renderItem(item, index) }, index))) })] })] }) }));
 }

package/dist/peek/llms.txt

@@ -0,0 +1,42 @@
+# KptPeek (@konce-pt/react)
+
+A peek card — content tied to what you are looking at, shown without leaving the text. Hover opens
+it, the card itself is interactive, and a click pins it.
+Import: `import { KptPeek } from '@konce-pt/react';`
+
+## DOM
+    <span class="kpt-peek-host">
+      <a class="kpt-peek__trigger" aria-expanded="true" aria-controls="…">…trigger…</a>
+    </span>
+    <!-- while open, in a portal on document.body: -->
+    <div class="kpt-peek__panel" role="dialog" tabindex="-1" data-pinned>…children…</div>
+
+## Props
+- `trigger`: ReactNode — the element the card hangs on; a mention, an avatar, a chip, a link
+- `children`: ReactNode — the card content
+- `placement`: 'top' | 'bottom' (default 'bottom')
+- `openDelay`: number (default 300), `closeDelay`: number (default 200)
+- `disabled`: boolean — the card never opens; the trigger stays a plain link or button
+- `label`: string — the card's accessible name; without it the trigger's text is used
+- `onOpenChange`: `(open: boolean) => void` — the moment to fetch the card's data
+- `className`, `ref` and every other `<span>` prop go to the host
+
+## The props land on the trigger itself
+A valid element passed as `trigger` is cloned with the handlers and `aria-expanded` merged in, so
+the state sits on the element a screen reader actually reads — not on some `<span>` next to it.
+Anything else (a bare string) gets wrapped in a `<span>`.
+
+## Hover is not the only way in
+Hover opens after `openDelay` and leaving closes after `closeDelay` — the pointer needs time to
+travel from the trigger to the card, so entering the card cancels the close. Focus opens it with no
+delay. A click, Enter or a tap **pins** the card: it stays after the pointer leaves and focus moves
+inside it. That is the only route to the card's content where there is no hover at all. Escape
+closes it and hands focus back to the trigger; so does a pointer press outside.
+
+## Which of the three
+`KptTooltip` carries plain text and cannot be clicked. `KptPopover` opens on click and puts a
+backdrop over the page. `KptPeek` opens on hover, the card is interactive, and nothing is covered.
+
+## Tokens
+`--kpt-color-surface-raised`, `--kpt-color-border`, `--kpt-elevation-3`, `--kpt-color-focus-ring`,
+`--kpt-z-overlay`.

package/dist/peek/peek.d.ts

@@ -0,0 +1,35 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+/** Z której strony wyzwalacza wychodzi karta. */
+export type KptPeekPlacement = 'top' | 'bottom';
+export interface KptPeekProps extends Omit<ComponentPropsWithRef<'span'>, 'content'> {
+    /** Element, na którym wisi karta — wzmianka, awatar, chip albo zwykły link. */
+    trigger: ReactNode;
+    /** Treść karty. */
+    children?: ReactNode;
+    placement?: KptPeekPlacement;
+    /** Zwłoka otwarcia po najechaniu (ms) — bez niej karty mrugają przy przejeżdżaniu przez tekst. */
+    openDelay?: number;
+    /** Zwłoka zamknięcia po zjeździe kursora (ms) — tyle jest na przejazd z wyzwalacza na kartę. */
+    closeDelay?: number;
+    /** Wyłączona karta nie otwiera się wcale; wyzwalacz zostaje zwykłym linkiem czy przyciskiem. */
+    disabled?: boolean;
+    /** Nazwa karty dla czytnika ekranu; bez niej bierze się tekst wyzwalacza. */
+    label?: string;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Karta podglądu pod kursorem — treść powiązana z tym, na co się patrzy, bez opuszczania tekstu.
+ * Tym różni się od sąsiadów: `KptTooltip` niesie sam tekst i nie da się w nim kliknąć,
+ * a `KptPopover` otwiera dopiero klik i zasłania stronę backdropem.
+ *
+ * Hover pokazuje kartę po `openDelay`, zjazd kursora chowa ją po `closeDelay` — kursor musi mieć
+ * czas przejechać z wyzwalacza na kartę, więc najazd na kartę anuluje zamknięcie. Fokus otwiera
+ * kartę od razu, a klik, Enter albo dotyk **przypina** ją: karta zostaje mimo zjazdu kursora,
+ * a fokus wchodzi do środka. To jedyna droga do treści karty tam, gdzie hovera nie ma w ogóle.
+ *
+ * @example
+ * <KptPeek trigger={<a href="/ludzie/anna">@Anna Kowalska</a>}>
+ *   <KptCard>Profil, projekty, kontakt…</KptCard>
+ * </KptPeek>
+ */
+export declare function KptPeek({ trigger, children, placement, openDelay, closeDelay, disabled, label, onOpenChange, className, ...rest }: Readonly<KptPeekProps>): import("react").JSX.Element;

package/dist/peek/peek.js

@@ -0,0 +1,127 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cloneElement, isValidElement, useCallback, useEffect, useId, useRef, useState, } from 'react';
+import { cn } from "../internal/cn.js";
+import { KptOverlay } from "../internal/overlay.js";
+import { mergeSlotProps } from "../internal/slot.js";
+/**
+ * Karta podglądu pod kursorem — treść powiązana z tym, na co się patrzy, bez opuszczania tekstu.
+ * Tym różni się od sąsiadów: `KptTooltip` niesie sam tekst i nie da się w nim kliknąć,
+ * a `KptPopover` otwiera dopiero klik i zasłania stronę backdropem.
+ *
+ * Hover pokazuje kartę po `openDelay`, zjazd kursora chowa ją po `closeDelay` — kursor musi mieć
+ * czas przejechać z wyzwalacza na kartę, więc najazd na kartę anuluje zamknięcie. Fokus otwiera
+ * kartę od razu, a klik, Enter albo dotyk **przypina** ją: karta zostaje mimo zjazdu kursora,
+ * a fokus wchodzi do środka. To jedyna droga do treści karty tam, gdzie hovera nie ma w ogóle.
+ *
+ * @example
+ * <KptPeek trigger={<a href="/ludzie/anna">@Anna Kowalska</a>}>
+ *   <KptCard>Profil, projekty, kontakt…</KptCard>
+ * </KptPeek>
+ */
+export function KptPeek({ trigger, children, placement = 'bottom', openDelay = 300, closeDelay = 200, disabled = false, label, onOpenChange, className, ...rest }) {
+    const hostRef = useRef(null);
+    const triggerRef = useRef(null);
+    const panelRef = useRef(null);
+    const timer = useRef(undefined);
+    const [open, setOpen] = useState(false);
+    /** Przypięta karta zostaje po zjeździe kursora — przypina ją klik, Enter albo dotyk. */
+    const [pinned, setPinned] = useState(false);
+    const panelId = useId();
+    const stop = useCallback(() => {
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = undefined;
+    }, []);
+    const schedule = useCallback((action, delay) => {
+        stop();
+        if (delay <= 0)
+            action();
+        else
+            timer.current = setTimeout(action, delay);
+    }, [stop]);
+    const show = useCallback(() => {
+        setOpen((was) => {
+            if (!was)
+                onOpenChange?.(true);
+            return true;
+        });
+    }, [onOpenChange]);
+    const close = useCallback(() => {
+        stop();
+        setPinned(false);
+        setOpen((was) => {
+            if (was)
+                onOpenChange?.(false);
+            return false;
+        });
+    }, [onOpenChange, stop]);
+    const hoverIn = useCallback(() => {
+        if (disabled)
+            return;
+        schedule(show, open ? 0 : openDelay);
+    }, [disabled, open, openDelay, schedule, show]);
+    const hoverOut = useCallback(() => {
+        if (pinned)
+            return;
+        schedule(close, closeDelay);
+    }, [close, closeDelay, pinned, schedule]);
+    const focusIn = useCallback(() => {
+        if (disabled)
+            return;
+        schedule(show, 0);
+    }, [disabled, schedule, show]);
+    const focusOut = useCallback(() => {
+        // Sprawdzenie po klatce: w chwili `blur` aktywnym elementem jest jeszcze `body`, więc
+        // przejście Tabem z wyzwalacza do karty wyglądałoby jak wyjście na zewnątrz.
+        schedule(() => {
+            const active = document.activeElement;
+            if (hostRef.current?.contains(active) || panelRef.current?.contains(active))
+                return;
+            close();
+        }, 0);
+    }, [close, schedule]);
+    /** Klik, Enter albo dotyk: karta zostaje i przyjmuje fokus. */
+    const pin = useCallback(() => {
+        if (disabled)
+            return;
+        setPinned(true);
+        show();
+        // Panel powstaje dopiero po przerysowaniu portalu, więc fokus idzie w następnej klatce.
+        setTimeout(() => panelRef.current?.focus({ preventScroll: true }));
+    }, [disabled, show]);
+    useEffect(() => stop, [stop]);
+    // Przypiętej karty nie zamyka zjazd kursora, więc kliknięcie obok musi ją zdjąć. Faza
+    // przechwytywania i `pointerdown`: własne `onClick` w karcie zdąży się wykonać wcześniej.
+    useEffect(() => {
+        if (!open)
+            return;
+        const outside = (event) => {
+            const target = event.target;
+            if (hostRef.current?.contains(target) || panelRef.current?.contains(target))
+                return;
+            close();
+        };
+        document.addEventListener('pointerdown', outside, true);
+        return () => document.removeEventListener('pointerdown', outside, true);
+    }, [close, open]);
+    const triggerProps = {
+        className: 'kpt-peek__trigger',
+        ref: triggerRef,
+        onMouseEnter: hoverIn,
+        onMouseLeave: hoverOut,
+        onFocus: focusIn,
+        onBlur: focusOut,
+        onClick: pin,
+        'aria-expanded': open,
+        'aria-controls': open ? panelId : undefined,
+    };
+    return (_jsxs("span", { ref: hostRef, className: cn('kpt-peek-host', className), ...rest, children: [isValidElement(trigger) ? (
+            // Propsy idą na sam wyzwalacz, nie na opakowanie: `aria-expanded` ma siedzieć na tym
+            // elemencie, po którym jeździ czytnik ekranu, a nie na obojętnym `<span>` obok.
+            cloneElement(trigger, mergeSlotProps(triggerProps, trigger.props))) : (_jsx("span", { ...triggerProps, children: trigger })), _jsx(KptOverlay, { open: open, anchor: triggerRef.current, onClose: close, offset: 8, withBackdrop: false, preferAbove: placement === 'top', children: _jsx("div", { ref: panelRef, id: panelId, className: "kpt-peek__panel", role: "dialog", tabIndex: -1, "aria-label": label || triggerRef.current?.textContent?.trim() || undefined, "data-pinned": pinned ? '' : undefined, onMouseEnter: hoverIn, onMouseLeave: hoverOut, onFocus: focusIn, onBlur: focusOut, onKeyDown: (event) => {
+                        if (event.key !== 'Escape')
+                            return;
+                        close();
+                        triggerRef.current?.focus({ preventScroll: true });
+                    }, children: children }) })] }));
+}

package/dist/pick-list/llms.txt

@@ -1,7 +1,7 @@
 # KptPickList (@konce-pt/react)
 
 Transfers items between two lists. Click to select, the middle buttons move the selection or
-everything.
+everything, a double-click sends one row across, and `dragdrop` adds dragging.
 Import: `import { KptPickList } from '@konce-pt/react';`
 
 ## DOM
@@ -22,13 +22,24 @@ Import: `import { KptPickList } from '@konce-pt/react';`
 - `source` / `defaultSource` / `onSourceChange` — the left list
 - `target` / `defaultTarget` / `onTargetChange` — the right list
 - `sourceHeader`, `targetHeader` — without them `pickList.available` / `pickList.selected`
+- `dragdrop` — `false` by default; enables dragging (opt-in, nothing changes without it)
 - `renderItem(item, index)` — required; the equivalent of `<ng-template let-item>`
 - `className`, `ref` and every other `<div>` prop go to the host
 
 ## The selection is kept by reference
 Selected items live in a `Set` of references, not of indexes: after a move the indexes on both
-sides shift, while a reference stays the same. That is also why a moved item never carries its
-selection over — the selection is cleared on every move.
+sides shift, while a reference stays the same. The buttons clear the whole selection of the side
+they empty; a double-click or a drag only drops the one item that left.
+
+## A double-click moves one item
+It sends exactly the row you clicked to the other panel and appends it at the end, whatever else is
+selected. It does not need `dragdrop` — the two clicks underneath cancel each other out, so the rest
+of the selection is left alone.
+
+## Where a dragged item lands
+Dropping onto a row puts the dragged item at that row's position: inside one panel that reorders,
+across panels it transfers. Dropping on the empty part of a panel appends at the end. While a drag
+is running the row under the cursor carries a `--dragover` modifier and the dragged one `is-dragging`.
 
 ## Two lists, two controlled values
 Both sides are independent controllable values, so the component works uncontrolled (`default*`),
@@ -38,15 +49,18 @@ half-controlled, or fully controlled by the form.
     <KptPickList
       source={available} onSourceChange={setAvailable}
       target={selected} onTargetChange={setSelected}
+      dragdrop
       renderItem={(item) => item.name}
     />
 
 ## i18n
-The headers and the four move buttons come from the `pickList` namespace.
+The headers and the four move buttons come from the `pickList` namespace. Dragging and the
+double-click carry no visible label, so they add no dictionary keys.
 
 ## Tokens
 The selection `--kpt-color-primary`, the headers `--kpt-color-surface-variant`.
 
 ## Accessibility
 Every move button is labelled from the dictionary, so "move all right" is distinguishable from
-"move right" without seeing the double chevron.
+"move right" without seeing the double chevron. Native HTML5 drag and drop has no keyboard
+equivalent, so those buttons stay the full keyboard path — `dragdrop` never replaces them.

package/dist/pick-list/pick-list.d.ts

@@ -11,18 +11,23 @@ export interface KptPickListProps<T> extends Omit<ComponentPropsWithRef<'div'>,
     sourceHeader?: string;
     /** Nagłówek listy docelowej; bez niego `pickList.selected`. */
     targetHeader?: string;
+    /** Włącza porządkowanie i przenoszenie elementów metodą przeciągnij-i-upuść. */
+    dragdrop?: boolean;
     /** Szablon elementu — odpowiednik `<ng-template let-item>` z Angulara. */
     renderItem: (item: T, index: number) => ReactNode;
 }
 /**
  * PickList — transfer elementów między dwiema listami. Klik zaznacza, przyciski pośrodku
- * przenoszą zaznaczone albo wszystko.
+ * przenoszą zaznaczone albo wszystko, dwuklik przerzuca pojedynczy element na drugą stronę.
+ * Z `dragdrop` dochodzi przeciąganie — porządkowanie wewnątrz panelu i przenoszenie na
+ * konkretną pozycję drugiego panelu.
  *
  * @example
  * <KptPickList
  *   source={available} onSourceChange={setAvailable}
  *   target={selected} onTargetChange={setSelected}
+ *   dragdrop
  *   renderItem={(item) => item.name}
  * />
  */
-export declare function KptPickList<T>({ source, defaultSource, onSourceChange, target, defaultTarget, onTargetChange, sourceHeader, targetHeader, renderItem, locale, dictionary, className, ...rest }: Readonly<KptPickListProps<T>>): import("react").JSX.Element;
+export declare function KptPickList<T>({ source, defaultSource, onSourceChange, target, defaultTarget, onTargetChange, sourceHeader, targetHeader, dragdrop, renderItem, locale, dictionary, className, ...rest }: Readonly<KptPickListProps<T>>): import("react").JSX.Element;