@konce-pt/table 0.8.0

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,56 @@
+<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/table
+
+Rdzeń tabeli danych [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): filtry kolumn, agregacje
+wiersza podsumowania, escapowanie CSV i zamiana wartości komórki na tekst. Czysty TypeScript,
+**zero zależności runtime**, bez wiązania z frameworkiem.
+
+Zwykle nie instalujesz go samodzielnie: używają go `KptDataTable` z `@konce-pt/angular`
+i z `@konce-pt/react`. Sięgnij po niego wprost, gdy budujesz własną tabelę na tym samym zachowaniu
+filtrów i podsumowań.
+
+```bash
+npm i @konce-pt/table
+```
+
+```ts
+import { aggregate, matchesColumnFilter, escapeCsvCell } from '@konce-pt/table';
+
+// Filtr `select` dopasowuje też komórkę-tablicę (lista tagów albo członków zespołu).
+matchesColumnFilter({ type: 'select', multiple: true }, ['Anna', 'Jan'], ['Jan']); // true
+
+// Pusty zbiór: suma to 0, średnia null — komórka renderuje się pusta, nie `NaN`.
+aggregate([], 'qty', 'sum'); // 0
+
+// Wartość zaczynająca się od `=` byłaby w arkuszu formułą.
+escapeCsvCell('=SUM(A1:A9)'); // "'=SUM(A1:A9)"
+```
+
+## Wartości komórek bywają czymkolwiek
+
+`toText()` jest jedną definicją tego, „co mówi komórka" — dla filtrowania, sortowania i podsumowań.
+Zwykły obiekt daje pusty string, nie `'[object Object]'`: ten drugi udawałby treść, przez co filtr
+tekstowy „obj" dopasowywałby każdy wiersz z obiektem w komórce.
+
+## API
+
+- **Tekst komórki** — `toText`
+- **Filtry kolumn** — `matchesColumnFilter`, `isEmptyFilterValue`, typy `KptColumnFilter`,
+  `KptColumnFilterType`, `KptTableFilterOption`
+- **Agregacje** — `aggregate`, `toNumber`, typy `KptColumnSummary`, `KptSummaryFn`
+- **CSV** — `escapeCsvCell`
+
+Pełny opis: [`llms.txt`](./llms.txt) (EN) i [`llms-pl.txt`](./llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/table exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/cell-text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Tekst z dowolnej wartości komórki. Prymitywy, `Date` i tablice zachowują się jak `String()`,
+ * natomiast zwykły obiekt daje **pusty string**, nie `'[object Object]'`: ten drugi udawałby
+ * sensowną zawartość — filtr tekstowy „obj" dopasowywałby każdy wiersz z obiektem w komórce,
+ * a sortowanie uznawało je wszystkie za równe.
+ */
+export declare function toText(value: unknown): string;

package/dist/cell-text.js

@@ -0,0 +1,29 @@
+/*
+ * Zamiana wartości komórki na tekst dla filtrowania, sortowania i podsumowań.
+ */
+/**
+ * Tekst z dowolnej wartości komórki. Prymitywy, `Date` i tablice zachowują się jak `String()`,
+ * natomiast zwykły obiekt daje **pusty string**, nie `'[object Object]'`: ten drugi udawałby
+ * sensowną zawartość — filtr tekstowy „obj" dopasowywałby każdy wiersz z obiektem w komórce,
+ * a sortowanie uznawało je wszystkie za równe.
+ */
+export function toText(value) {
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+            return String(value);
+        case 'object':
+            if (value === null)
+                return '';
+            if (value instanceof Date)
+                return value.toString();
+            if (Array.isArray(value))
+                return value.map(toText).join(',');
+            return '';
+        default:
+            return '';
+    }
+}

package/dist/column-filter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Opcja filtra `select`. Kształt strukturalny, więc `KptOption` z obu portów pasuje tu bez
+ * konwersji — paczka nie zna żadnego z nich.
+ */
+export interface KptTableFilterOption {
+    label: string;
+    value: unknown;
+    disabled?: boolean;
+}
+/** Rodzaj kontrolki filtra w nagłówku kolumny. */
+export type KptColumnFilterType = 'text' | 'number' | 'select' | 'dateRange' | 'numberRange' | 'slider';
+export interface KptColumnFilter {
+    type: KptColumnFilterType;
+    /** Opcje dla `type: 'select'`. */
+    options?: KptTableFilterOption[];
+    /** Wielokrotny wybór dla `type: 'select'`. */
+    multiple?: boolean;
+    /** Placeholder kontrolki. */
+    placeholder?: string;
+    /** Dolna granica dla `type: 'slider'` (domyślnie 0). */
+    min?: number;
+    /** Górna granica dla `type: 'slider'` (domyślnie 100). */
+    max?: number;
+    /** Krok dla `type: 'slider'` (domyślnie 1). */
+    step?: number;
+}
+/** Filtr „pusty" (nie wybrano nic) przepuszcza każdy wiersz. */
+export declare function isEmptyFilterValue(value: unknown): boolean;
+/** Czy komórka przechodzi filtr kolumny. Wartości pustych filtrów odsiewa `isEmptyFilterValue`. */
+export declare function matchesColumnFilter(filter: KptColumnFilter, cell: unknown, value: unknown): boolean;

package/dist/column-filter.js

@@ -0,0 +1,73 @@
+/*
+ * Dopasowanie wiersza do filtrów kolumn tabeli.
+ * Komponent trzyma tylko stan filtrów; cała semantyka „czy komórka pasuje" jest tutaj.
+ */
+import { toText } from "./cell-text.js";
+import { toNumber } from "./summary.js";
+/** Data komórki w formacie `YYYY-MM-DD` — do porównań leksykograficznych z granicami zakresu. */
+function toIsoDate(value) {
+    if (value instanceof Date) {
+        const p = (n) => String(n).padStart(2, '0');
+        return `${value.getFullYear()}-${p(value.getMonth() + 1)}-${p(value.getDate())}`;
+    }
+    return toText(value);
+}
+/** Filtr „pusty" (nie wybrano nic) przepuszcza każdy wiersz. */
+export function isEmptyFilterValue(value) {
+    return value == null || value === '' || (Array.isArray(value) && value.length === 0);
+}
+const matchesText = (cell, value) => toText(cell).toLowerCase().includes(toText(value).toLowerCase());
+const matchesNumber = (cell, value) => toText(cell).includes(toText(value));
+const matchesSelect = (cell, value) => {
+    const picked = Array.isArray(value) ? value : [value];
+    // Komórka-tablica (np. lista tagów/członków) → dopasuj, gdy zawiera dowolną z wybranych wartości.
+    if (Array.isArray(cell))
+        return cell.some((c) => picked.includes(c));
+    return picked.includes(cell);
+};
+const matchesNumberRange = (cell, value) => {
+    const { min, max } = value ?? {};
+    const lo = min == null || min === '' ? null : Number.parseFloat(min);
+    const hi = max == null || max === '' ? null : Number.parseFloat(max);
+    if (lo === null && hi === null)
+        return true;
+    const num = toNumber(cell);
+    if (Number.isNaN(num))
+        return false;
+    if (lo !== null && num < lo)
+        return false;
+    if (hi !== null && num > hi)
+        return false;
+    return true;
+};
+const matchesSlider = (cell, value) => {
+    const [lo, hi] = value;
+    const num = toNumber(cell);
+    if (Number.isNaN(num))
+        return false;
+    return num >= lo && num <= hi;
+};
+const matchesDateRange = (cell, value) => {
+    const { start, end } = value ?? {};
+    if (!start && !end)
+        return true;
+    const iso = toIsoDate(cell);
+    if (start && iso < start)
+        return false;
+    if (end && iso > end)
+        return false;
+    return true;
+};
+/** Mapa zamiast `switch` — `Record` po unii typów wymusza komplet, więc nie ma martwego `default`. */
+const MATCHERS = {
+    text: matchesText,
+    number: matchesNumber,
+    select: matchesSelect,
+    numberRange: matchesNumberRange,
+    slider: matchesSlider,
+    dateRange: matchesDateRange,
+};
+/** Czy komórka przechodzi filtr kolumny. Wartości pustych filtrów odsiewa `isEmptyFilterValue`. */
+export function matchesColumnFilter(filter, cell, value) {
+    return MATCHERS[filter.type](cell, value);
+}

package/dist/csv-export.d.ts

@@ -0,0 +1,2 @@
+/** Escapuje pojedynczą wartość komórki/nagłówka do bezpiecznego pola CSV (separator `;`). */
+export declare function escapeCsvCell(value: unknown): string;

package/dist/csv-export.js

@@ -0,0 +1,31 @@
+/*
+ * Escapowanie komórek CSV dla eksportu tabeli.
+ */
+// Znak startowy, który arkusz kalkulacyjny czyta jako początek formuły (CWE-1236).
+const FORMULA_PREFIX = /^[=+\-@\t\r]/;
+function stringifyCsvValue(value) {
+    switch (typeof value) {
+        case 'undefined':
+            return '';
+        case 'string':
+            return value;
+        case 'number':
+        case 'boolean':
+        case 'bigint':
+            return String(value);
+        default:
+            if (value === null)
+                return '';
+            if (value instanceof Date)
+                return value.toISOString();
+            return JSON.stringify(value);
+    }
+}
+/** Escapuje pojedynczą wartość komórki/nagłówka do bezpiecznego pola CSV (separator `;`). */
+export function escapeCsvCell(value) {
+    let text = stringifyCsvValue(value);
+    // Wiodący `'` każe arkuszowi traktować komórkę jako tekst — sam znak nie jest wyświetlany.
+    if (FORMULA_PREFIX.test(text))
+        text = `'${text}`;
+    return /[",\n;]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { toText } from './cell-text.ts';
+export { escapeCsvCell } from './csv-export.ts';
+export { aggregate, toNumber } from './summary.ts';
+export type { KptColumnSummary, KptSummaryFn } from './summary.ts';
+export { isEmptyFilterValue, matchesColumnFilter } from './column-filter.ts';
+export type { KptColumnFilter, KptColumnFilterType, KptTableFilterOption } from './column-filter.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { toText } from "./cell-text.js";
+export { escapeCsvCell } from "./csv-export.js";
+export { aggregate, toNumber } from "./summary.js";
+export { isEmptyFilterValue, matchesColumnFilter } from "./column-filter.js";

package/dist/summary.d.ts

@@ -0,0 +1,19 @@
+/** Wbudowana agregacja kolumny w wierszu podsumowania. */
+export type KptSummaryFn = 'sum' | 'avg' | 'min' | 'max' | 'count';
+export interface KptColumnSummary {
+    /**
+     * Agregacja wbudowana albo własna funkcja liczona na całym zbiorze wierszy
+     * (po filtrach, ze wszystkich stron).
+     */
+    fn: KptSummaryFn | ((rows: readonly Record<string, unknown>[]) => unknown);
+    /** Formatowanie wyniku (np. waluta). Bez niego wartość renderowana jest surowo. */
+    format?: (value: unknown) => string;
+}
+/** Liczba z komórki: `number` bez zmian, string przez `parseFloat`, reszta → `NaN` (pomijana). */
+export declare function toNumber(value: unknown): number;
+/**
+ * Agreguje jedno pole po wierszach. `count` liczy wiersze; pozostałe funkcje pomijają
+ * wartości nieliczbowe. Pusty zbiór liczb: `sum` → 0, `avg`/`min`/`max` → `null`
+ * (komórka renderuje się wtedy pusta).
+ */
+export declare function aggregate(rows: readonly Record<string, unknown>[], field: string, fn: KptSummaryFn): number | null;

package/dist/summary.js

@@ -0,0 +1,45 @@
+/*
+ * Agregacje wiersza podsumowania (`<tfoot>`) tabeli danych.
+ */
+/**
+ * Sumowanie liczb zmiennoprzecinkowych daje ogony (`0.1 + 0.2` → `0.30000000000000004`),
+ * które bez tego przycięcia wyciekłyby wprost do komórki podsumowania.
+ */
+function trimFloat(value) {
+    return Math.round(value * 1e10) / 1e10;
+}
+/** Liczba z komórki: `number` bez zmian, string przez `parseFloat`, reszta → `NaN` (pomijana). */
+export function toNumber(value) {
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string' && value.trim() !== '')
+        return Number.parseFloat(value);
+    return Number.NaN;
+}
+/**
+ * Agreguje jedno pole po wierszach. `count` liczy wiersze; pozostałe funkcje pomijają
+ * wartości nieliczbowe. Pusty zbiór liczb: `sum` → 0, `avg`/`min`/`max` → `null`
+ * (komórka renderuje się wtedy pusta).
+ */
+export function aggregate(rows, field, fn) {
+    if (fn === 'count')
+        return rows.length;
+    const nums = [];
+    for (const row of rows) {
+        const num = toNumber(row[field]);
+        if (!Number.isNaN(num))
+            nums.push(num);
+    }
+    switch (fn) {
+        case 'sum':
+            return trimFloat(nums.reduce((acc, n) => acc + n, 0));
+        case 'avg':
+            return nums.length === 0 ? null : trimFloat(nums.reduce((acc, n) => acc + n, 0) / nums.length);
+        case 'min':
+            return nums.length === 0 ? null : Math.min(...nums);
+        case 'max':
+            return nums.length === 0 ? null : Math.max(...nums);
+        default:
+            return null;
+    }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@konce-pt/table",
+  "version": "0.8.0",
+  "description": "Data-table core for Koncept UI — column filters, aggregations, CSV escaping, cell-to-text. 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/table"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "data-table",
+    "table",
+    "filtering",
+    "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})\""
+  }
+}