@konce-pt/mention 0.8.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+<p align="center">
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — Angular component library" width="100%" />
+</p>
+
+# @konce-pt/mention
+
+Rdzeń wzmianek [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): wyciąganie `@wzmianek`
+z tekstu, aktywne zapytanie przy kursorze i dopasowanie podpowiedzi bez znaków diakrytycznych.
+Czysty TypeScript, **zero zależności runtime**, bez wiązania z frameworkiem.
+
+Zwykle nie instalujesz go samodzielnie: używają go `KptMention`, `KptMentions` i `KptRichText`
+z `@konce-pt/angular` oraz `@konce-pt/react`. Sięgnij po niego wprost, gdy wzmianki mają działać
+w twoim własnym polu tekstowym albo po stronie serwera.
+
+```bash
+npm i @konce-pt/mention
+```
+
+```ts
+import { filterMentions, mentionQuery, parseMentionText } from '@konce-pt/mention';
+
+const people = [
+  { id: 'anna.k', label: 'Anna Kowalska' },
+  { id: 'lukasz.w', label: 'Łukasz Wiśniewski' },
+];
+
+// Akapit rozbity na tekst i wzmianki — z `raw` każdej z nich wraca oryginał znak w znak.
+parseMentionText('Pytanie do @anna.k o kosztorys.', people);
+
+// Co podpowiedzieć przy kursorze (tu: po wpisaniu „@luk").
+const query = mentionQuery('Pytanie do @luk', 15); // { query: 'luk', start: 11, end: 15 }
+filterMentions(people, query.query); // [{ id: 'lukasz.w', … }]
+```
+
+## Wzmianka to nie kolorowy napis
+
+`mail@example.com` nie może stać się wzmianką, a Enter w podpowiedziach nie może wstawić nazwy
+w innym miejscu, niż użytkownik pisze. Te same reguły są potrzebne w akapicie do czytania,
+w zwykłym polu tekstowym, w edytorze i w obu portach — dlatego siedzą w jednym module z testami.
+
+## API
+
+- **Parsowanie** — `parseMentionText`, `mentionToken`, `collectMentions`, typ `KptMentionSegment`
+- **Zapytanie przy kursorze** — `mentionQuery`, `applyMention`, typ `KptMentionQuery`
+- **Dopasowanie** — `filterMentions`, `foldMentionText`, `KPT_MENTION_LIMIT`
+- **Model** — typ `KptMentionItem`
+
+Pełny opis: [`llms.txt`](https://ui.konce.pt/llms/mention/llms.txt) (EN)
+i [`llms-pl.txt`](https://ui.konce.pt/llms/mention/llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/mention exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { KptMentionItem, KptMentionSegment } from './types.ts';
+export { parseMentionText, mentionToken, collectMentions } from './parse.ts';
+export { filterMentions, foldMentionText, KPT_MENTION_LIMIT } from './match.ts';
+export { mentionQuery, applyMention } from './query.ts';
+export type { KptMentionQuery } from './query.ts';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { parseMentionText, mentionToken, collectMentions } from "./parse.js";
+export { filterMentions, foldMentionText, KPT_MENTION_LIMIT } from "./match.js";
+export { mentionQuery, applyMention } from "./query.js";

package/dist/match.d.ts

@@ -0,0 +1,13 @@
+import type { KptMentionItem } from './types.ts';
+/** Ile podpowiedzi pokazujemy domyślnie: tyle mieści się bez przewijania pod kursorem. */
+export declare const KPT_MENTION_LIMIT = 8;
+/** Tekst do porównań: bez diakrytyków, małymi literami. */
+export declare function foldMentionText(value: string): string;
+/**
+ * Pozycje pasujące do zapytania, w kolejności trafności. Puste zapytanie zwraca początek listy —
+ * zaraz po `@` nie ma czego filtrować, a pusta lista podpowiedzi wyglądałaby jak brak wyników.
+ *
+ * Szukamy po etykiecie, identyfikatorze i `keywords` (alias, e-mail, numer zadania), ale ranga
+ * bierze się z najlepszego trafienia, nie z pierwszego lepszego pola.
+ */
+export declare function filterMentions<T = unknown>(items: readonly KptMentionItem<T>[], query: string, limit?: number): KptMentionItem<T>[];

package/dist/match.js

@@ -0,0 +1,67 @@
+/*
+ * Dopasowanie pozycji do tego, co użytkownik wpisał po `@`.
+ *
+ * Porównujemy bez znaków diakrytycznych i bez wielkości liter: „lukasz" ma znaleźć „Łukasza",
+ * bo przy pisaniu wzmianki nikt nie przełącza się na polską klawiaturę w środku zdania.
+ * Kolejność wyników: najpierw trafienia od początku etykiety, potem od początku słowa w środku,
+ * na końcu zwykłe zawieranie — lista podpowiedzi ma dawać oczywisty pierwszy wybór.
+ */
+/** Ile podpowiedzi pokazujemy domyślnie: tyle mieści się bez przewijania pod kursorem. */
+export const KPT_MENTION_LIMIT = 8;
+/**
+ * Litery z kreską przekreślającą, których NFD nie rozkłada. `ł` to osobny znak Unicode, a nie
+ * `l` ze znakiem diakrytycznym, więc samo `normalize('NFD')` zostawiłoby „Łukasza" poza zasięgiem
+ * zapytania „lukasz" — a to najczęstszy przypadek w polskich nazwiskach.
+ */
+const STROKED = new Map([
+    ['ł', 'l'],
+    ['đ', 'd'],
+    ['ø', 'o'],
+    ['ħ', 'h'],
+    ['ŧ', 't'],
+]);
+/** Tekst do porównań: bez diakrytyków, małymi literami. */
+export function foldMentionText(value) {
+    return value
+        .normalize('NFD')
+        .replace(/\p{Diacritic}/gu, '')
+        .toLowerCase()
+        .replace(/[łđøħŧ]/gu, (char) => STROKED.get(char) ?? char);
+}
+/** Ranga trafienia: 0 — początek etykiety, 1 — początek słowa, 2 — środek, -1 — brak. */
+function rank(haystack, needle) {
+    const at = haystack.indexOf(needle);
+    if (at < 0)
+        return -1;
+    if (at === 0)
+        return 0;
+    return /[\s.\-_/]/.test(haystack[at - 1]) ? 1 : 2;
+}
+/**
+ * Pozycje pasujące do zapytania, w kolejności trafności. Puste zapytanie zwraca początek listy —
+ * zaraz po `@` nie ma czego filtrować, a pusta lista podpowiedzi wyglądałaby jak brak wyników.
+ *
+ * Szukamy po etykiecie, identyfikatorze i `keywords` (alias, e-mail, numer zadania), ale ranga
+ * bierze się z najlepszego trafienia, nie z pierwszego lepszego pola.
+ */
+export function filterMentions(items, query, limit = KPT_MENTION_LIMIT) {
+    const needle = foldMentionText(query.trim());
+    if (!needle)
+        return items.slice(0, limit);
+    const scored = [];
+    items.forEach((item, index) => {
+        const fields = [item.label, item.id, ...(item.keywords ?? [])];
+        let best = -1;
+        for (const field of fields) {
+            const value = rank(foldMentionText(field), needle);
+            if (value >= 0 && (best < 0 || value < best))
+                best = value;
+        }
+        if (best >= 0)
+            scored.push({ item, rank: best, index });
+    });
+    // Remis rozstrzyga kolejność wejściowa: aplikacja zna wagę pozycji (ostatnio używane,
+    // osoby z zespołu) lepiej niż my, więc jej układu nie mieszamy.
+    scored.sort((a, b) => a.rank - b.rank || a.index - b.index);
+    return scored.slice(0, limit).map((entry) => entry.item);
+}

package/dist/parse.d.ts

@@ -0,0 +1,18 @@
+import type { KptMentionItem, KptMentionSegment } from './types.ts';
+/**
+ * Tekst rozbity na segmenty: zwykła treść i wzmianki. Nie renderuje niczego — z tego komponent
+ * składa akapit, w którym wzmianka jest elementem z kartą, a reszta zostaje tekstem.
+ *
+ * Kolejność i sklejenie segmentów oddają wejście znak w znak, więc z `segments.map(text).join('')`
+ * wraca oryginał — inaczej podgląd rozjechałby się z tym, co zapisano.
+ */
+export declare function parseMentionText<T = unknown>(text: string, items?: readonly KptMentionItem<T>[]): KptMentionSegment<T>[];
+/**
+ * Zapis wzmianki do wstawienia w tekst. Etykieta idzie do zapisu tylko wtedy, gdy jest potrzebna
+ * — czyli gdy różni się od `id` — żeby prosty `@anna.k` nie puchł bez powodu.
+ */
+export declare function mentionToken(item: KptMentionItem): string;
+/** Same wzmianki z tekstu, w kolejności wystąpienia (duplikaty zostają — to lista, nie zbiór). */
+export declare function collectMentions<T = unknown>(text: string, items?: readonly KptMentionItem<T>[]): Extract<KptMentionSegment<T>, {
+    kind: 'mention';
+}>[];

package/dist/parse.js

@@ -0,0 +1,58 @@
+/*
+ * Rozbicie tekstu na treść i wzmianki.
+ *
+ * Dwa zapisy, oba zaczynają się `@`:
+ * - `@id` — identyfikator bez spacji (`@anna.k`, `@zad-142`); etykietę bierze się z listy pozycji,
+ *   a gdy jej tam nie ma — zostaje samo `id`, bo tekst ma dalej dać się przeczytać.
+ * - `@[Anna Kowalska](anna.k)` — zapis z etykietą, jedyny sposób na nazwę ze spacją. Etykieta jest
+ *   tylko do pokazania: gdy `id` uda się rozwiązać, wygrywa nazwa z listy, bo dane bywają
+ *   świeższe niż tekst zapisany miesiąc temu.
+ *
+ * `@` w środku wyrazu (`mail@example.com`) wzmianką nie jest — musi stać na początku tekstu albo
+ * po znaku, który nie jest literą, cyfrą ani podkreśleniem.
+ */
+/** Znaki identyfikatora: litery (z ogonkami), cyfry, `_`, `-`, `.`. Kropka nie może kończyć. */
+const ID = String.raw `[\p{L}\p{N}_][\p{L}\p{N}_.-]*[\p{L}\p{N}_]|[\p{L}\p{N}_]`;
+/** `@[Etykieta](id)` albo `@id`; grupa 1/2 to zapis z etykietą, grupa 3 — sam identyfikator. */
+const MENTION = new RegExp(String.raw `(?<![\p{L}\p{N}_])@(?:\[([^\]\n]+)\]\((${ID})\)|(${ID}))`, 'gu');
+/** Mapa `id → pozycja`; lista bywa krótka, ale tekst potrafi mieć setki wzmianek. */
+function index(items) {
+    return new Map(items.map((item) => [item.id, item]));
+}
+/**
+ * Tekst rozbity na segmenty: zwykła treść i wzmianki. Nie renderuje niczego — z tego komponent
+ * składa akapit, w którym wzmianka jest elementem z kartą, a reszta zostaje tekstem.
+ *
+ * Kolejność i sklejenie segmentów oddają wejście znak w znak, więc z `segments.map(text).join('')`
+ * wraca oryginał — inaczej podgląd rozjechałby się z tym, co zapisano.
+ */
+export function parseMentionText(text, items = []) {
+    if (!text)
+        return [];
+    const known = index(items);
+    const segments = [];
+    let last = 0;
+    for (const match of text.matchAll(MENTION)) {
+        const start = match.index;
+        if (start > last)
+            segments.push({ kind: 'text', text: text.slice(last, start) });
+        const id = (match[2] ?? match[3]);
+        const item = known.get(id) ?? null;
+        segments.push({ kind: 'mention', id, label: item?.label ?? match[1] ?? id, item, raw: match[0] });
+        last = start + match[0].length;
+    }
+    if (last < text.length)
+        segments.push({ kind: 'text', text: text.slice(last) });
+    return segments;
+}
+/**
+ * Zapis wzmianki do wstawienia w tekst. Etykieta idzie do zapisu tylko wtedy, gdy jest potrzebna
+ * — czyli gdy różni się od `id` — żeby prosty `@anna.k` nie puchł bez powodu.
+ */
+export function mentionToken(item) {
+    return item.label === item.id ? `@${item.id}` : `@[${item.label}](${item.id})`;
+}
+/** Same wzmianki z tekstu, w kolejności wystąpienia (duplikaty zostają — to lista, nie zbiór). */
+export function collectMentions(text, items = []) {
+    return parseMentionText(text, items).filter((segment) => segment.kind === 'mention');
+}

package/dist/query.d.ts

@@ -0,0 +1,24 @@
+/** Zapytanie otwarte przez `@` tuż przed kursorem. */
+export interface KptMentionQuery {
+    /** Tekst po `@`, bez samego znaku. */
+    query: string;
+    /** Pozycja znaku `@` w tekście. */
+    start: number;
+    /** Pozycja kursora (koniec zapytania). */
+    end: number;
+}
+/**
+ * Zapytanie wzmianki przy kursorze albo `null`, gdy w tym miejscu nic się nie pisze.
+ *
+ * Warunki są celowo ciasne, bo `@` w tekście najczęściej nie jest wzmianką:
+ * - `@` stoi na początku tekstu albo po znaku, który nie jest literą, cyfrą ani `_`
+ *   (dzięki temu `mail@example.com` nie otwiera podpowiedzi),
+ * - między `@` a kursorem nie ma białego znaku ani drugiego `@`,
+ * - zapytanie nie przekracza `MAX_QUERY` znaków — po tylu znakach to już nie jest nazwa.
+ */
+export declare function mentionQuery(text: string, caret: number): KptMentionQuery | null;
+/** Tekst po wstawieniu zapisu wzmianki w miejsce zapytania — razem z nową pozycją kursora. */
+export declare function applyMention(text: string, query: KptMentionQuery, token: string): {
+    text: string;
+    caret: number;
+};

package/dist/query.js

@@ -0,0 +1,42 @@
+/*
+ * Aktywne zapytanie `@…` przy kursorze — to, co w polu tekstowym albo w edytorze decyduje,
+ * czy pokazać podpowiedzi i czego w nich szukać.
+ */
+/** Ile znaków po `@` jeszcze uznajemy za pisanie wzmianki. Dalej to już zwykłe zdanie. */
+const MAX_QUERY = 32;
+/**
+ * Zapytanie wzmianki przy kursorze albo `null`, gdy w tym miejscu nic się nie pisze.
+ *
+ * Warunki są celowo ciasne, bo `@` w tekście najczęściej nie jest wzmianką:
+ * - `@` stoi na początku tekstu albo po znaku, który nie jest literą, cyfrą ani `_`
+ *   (dzięki temu `mail@example.com` nie otwiera podpowiedzi),
+ * - między `@` a kursorem nie ma białego znaku ani drugiego `@`,
+ * - zapytanie nie przekracza `MAX_QUERY` znaków — po tylu znakach to już nie jest nazwa.
+ */
+export function mentionQuery(text, caret) {
+    const end = Math.max(0, Math.min(caret, text.length));
+    const from = Math.max(0, end - MAX_QUERY - 1);
+    for (let index = end - 1; index >= from; index -= 1) {
+        const char = text[index];
+        if (/\s/.test(char))
+            return null;
+        if (char !== '@')
+            continue;
+        const before = index > 0 ? text[index - 1] : '';
+        if (before && /[\p{L}\p{N}_]/u.test(before))
+            return null;
+        return { query: text.slice(index + 1, end), start: index, end };
+    }
+    return null;
+}
+/** Tekst po wstawieniu zapisu wzmianki w miejsce zapytania — razem z nową pozycją kursora. */
+export function applyMention(text, query, token) {
+    // Spacja po wzmiance: bez niej kolejne słowo skleiłoby się z nazwą, a kursor i tak ma iść dalej.
+    // Gdy spacja już tam stoi (wzmianka wpisywana w środku zdania), drugiej nie dokładamy.
+    const spaced = /\s/.test(text[query.end] ?? '');
+    const insert = spaced ? token : `${token} `;
+    return {
+        text: text.slice(0, query.start) + insert + text.slice(query.end),
+        caret: query.start + insert.length,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Pozycja, na którą można się powołać w tekście.
+ *
+ * `id` jest tym, co zostaje zapisane w treści — musi przeżyć zmianę nazwy, więc etykieta nigdy
+ * nie jest identyfikatorem. `kind` pozwala trzymać w jednym polu kilka rodzajów (osoba, zadanie,
+ * dokument) i wybrać po nim szablon karty. `data` to ładunek aplikacji, przekazywany bez zmian
+ * do szablonu karty.
+ */
+export interface KptMentionItem<T = unknown> {
+    id: string;
+    label: string;
+    kind?: string;
+    /** Dodatkowy tekst do wyszukiwania: alias, e-mail, numer zadania. */
+    keywords?: readonly string[];
+    data?: T;
+}
+/** Kawałek tekstu po rozbiciu na zwykłą treść i wzmianki. */
+export type KptMentionSegment<T = unknown> = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'mention';
+    /** Identyfikator z tekstu — nawet wtedy, gdy nie ma go w podanej liście pozycji. */
+    id: string;
+    /** Etykieta do pokazania: z listy pozycji, z zapisu `@[Etykieta](id)` albo samo `id`. */
+    label: string;
+    /** Pozycja z listy, o ile `id` udało się rozwiązać. */
+    item: KptMentionItem<T> | null;
+    /** Surowy zapis z tekstu — do zamiany z powrotem bez zgadywania składni. */
+    raw: string;
+};

package/dist/types.js

@@ -0,0 +1,5 @@
+/*
+ * Model wzmianki. Te typy przechodzą przez granicę biblioteki: aplikacja wypełnia je swoimi
+ * danymi (osoby, zadania, dokumenty), oba porty (Angular i React) renderują je tak samo.
+ */
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@konce-pt/mention",
+  "version": "0.8.5",
+  "description": "Mention core for Koncept UI — parsing @mentions in text, the active query at the caret and diacritics-insensitive matching. Framework-free TypeScript, zero runtime dependencies.",
+  "license": "MIT",
+  "author": "konce.pt",
+  "homepage": "https://ui.konce.pt/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/konce-pt/koncept-ui.git",
+    "directory": "packages/mention"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "mention",
+    "mentions",
+    "autocomplete",
+    "design-system",
+    "koncept-ui",
+    "kpt"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}