@konce-pt/nav 0.0.0-stage → 0.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +49 -2
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/sidenav.d.ts +77 -0
- package/dist/sidenav.js +93 -0
- package/package.json +43 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 konce.pt
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,50 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI" width="100%" />
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
5
|
+
# @konce-pt/nav
|
|
6
|
+
|
|
7
|
+
Rdzeń nawigacji bocznej [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): indeks pozycji menu
|
|
8
|
+
po `id`, ulubione (przypinanie), lista ostatnio otwartych i ich zapis w `localStorage`.
|
|
9
|
+
Czysty TypeScript, **zero zależności runtime**, bez wiązania z frameworkiem.
|
|
10
|
+
|
|
11
|
+
Zwykle nie instalujesz go samodzielnie: używa go `KptSidenav` z `@konce-pt/angular`
|
|
12
|
+
oraz `@konce-pt/react`, które re-eksportują jego typy. Sięgnij po niego wprost, gdy budujesz własne menu
|
|
13
|
+
albo liczysz ścieżkę aktywnej pozycji po stronie serwera.
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
npm i @konce-pt/nav
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { indexSidenav, pushSidenavRecent, sidenavActivePath, toggleSidenavPin } from '@konce-pt/nav';
|
|
21
|
+
|
|
22
|
+
const groups = [
|
|
23
|
+
{ id: 'main', label: 'Main', items: [{ id: 'reports', label: 'Reports', children: [{ id: 'sales', label: 'Sales' }] }] },
|
|
24
|
+
];
|
|
25
|
+
|
|
26
|
+
const index = indexSidenav(groups);
|
|
27
|
+
sidenavActivePath('sales', index); // Set { 'main', 'reports' } - te gałęzie są rozwinięte
|
|
28
|
+
toggleSidenavPin(['home'], 'sales'); // ['home', 'sales']
|
|
29
|
+
pushSidenavRecent(['home', 'sales'], 'home', 5); // ['home', 'sales']
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## API
|
|
33
|
+
|
|
34
|
+
- **Indeks** - `indexSidenav`, `groupAsItem`, `resolveSidenavIds`, `sidenavActivePath`, `isSidenavBranch`, `isSidenavGroupCollapsible`
|
|
35
|
+
- **Ulubione i ostatnie** - `toggleSidenavPin`, `pushSidenavRecent`
|
|
36
|
+
- **Zapis** - `readSidenavState`, `writeSidenavState` (błędy pamięci są połykane, brak `localStorage` to SSR)
|
|
37
|
+
- **Typy** - `KptSidenavItem`, `KptSidenavGroup`, `KptSidenavEntry`, `KptSidenavQuickTab`, `KptSidenavChevron`, `KptSidenavStoredState`
|
|
38
|
+
|
|
39
|
+
Pełny opis: [`llms.txt`](https://ui.konce.pt/llms/nav/llms.txt) (EN)
|
|
40
|
+
i [`llms-pl.txt`](https://ui.konce.pt/llms/nav/llms-pl.txt) (PL).
|
|
41
|
+
|
|
42
|
+
## Testy
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
pnpm --filter @konce-pt/nav exec node --test "src/**/*.test.ts"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Licencja
|
|
49
|
+
|
|
50
|
+
MIT © [konce.pt](https://konce.pt)
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
export type { KptSidenavChevron, KptSidenavEntry, KptSidenavGroup, KptSidenavItem, KptSidenavQuickTab, KptSidenavStoredState, } from './sidenav.ts';
|
|
2
|
+
export { groupAsItem, indexSidenav, isSidenavBranch, isSidenavGroupCollapsible, pushSidenavRecent, readSidenavState, resolveSidenavIds, sidenavActivePath, toggleSidenavPin, writeSidenavState, } from './sidenav.ts';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { groupAsItem, indexSidenav, isSidenavBranch, isSidenavGroupCollapsible, pushSidenavRecent, readSidenavState, resolveSidenavIds, sidenavActivePath, toggleSidenavPin, writeSidenavState, } from "./sidenav.js";
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
/** Pozycja nawigacji. `id` musi być unikalne w całym menu (razem z `id` grup) - po nim działają ulubione i ostatnie. */
|
|
2
|
+
export interface KptSidenavItem<T = unknown> {
|
|
3
|
+
id: string;
|
|
4
|
+
label: string;
|
|
5
|
+
/** Nazwa ikony z rejestru. Bez ikony pozycja na górze ulubionych i ostatnich zostawia puste miejsce po ikonie. */
|
|
6
|
+
icon?: string;
|
|
7
|
+
/** Adres - pozycja renderuje się jako `<a href>`. Bez niego (i bez `children`) to `<button>`. */
|
|
8
|
+
url?: string;
|
|
9
|
+
/** `target` odnośnika, np. `_blank`. */
|
|
10
|
+
target?: string;
|
|
11
|
+
value?: T;
|
|
12
|
+
/** Licznik albo krótka etykieta po prawej (liczba elementów, nowe zgłoszenia). */
|
|
13
|
+
badge?: string | number;
|
|
14
|
+
/** Pozycje podrzędne - pozycja staje się rozwijaną gałęzią (bez własnego adresu). */
|
|
15
|
+
children?: readonly KptSidenavItem<T>[];
|
|
16
|
+
/** Stan początkowy gałęzi; dalej rozwijaniem steruje komponent. */
|
|
17
|
+
expanded?: boolean;
|
|
18
|
+
disabled?: boolean;
|
|
19
|
+
/** `false` wyłącza pinezkę tej pozycji. Domyślnie przypiąć da się każdą. */
|
|
20
|
+
pinnable?: boolean;
|
|
21
|
+
}
|
|
22
|
+
/** Grupa pozycji z nagłówkiem (np. "Dashboards", "Pages"). Przypięta, trafia do ulubionych jako rozwijana gałąź. */
|
|
23
|
+
export interface KptSidenavGroup<T = unknown> {
|
|
24
|
+
id: string;
|
|
25
|
+
label: string;
|
|
26
|
+
/** Ikona grupy na liście ulubionych (nagłówek w menu jej nie pokazuje). */
|
|
27
|
+
icon?: string;
|
|
28
|
+
items: readonly KptSidenavItem<T>[];
|
|
29
|
+
/** `false` wyłącza pinezkę nagłówka grupy. */
|
|
30
|
+
pinnable?: boolean;
|
|
31
|
+
/**
|
|
32
|
+
* Czy nagłówek zwija tę grupę. Nadpisuje `collapsibleGroups` panelu w obie strony: `true` robi
|
|
33
|
+
* zwijaną tylko tę grupę, `false` wyłącza ją spod `collapsibleGroups`.
|
|
34
|
+
*/
|
|
35
|
+
collapsible?: boolean;
|
|
36
|
+
/**
|
|
37
|
+
* Stan początkowy zwijanej grupy: `false` startuje zwinięta (chyba że jest w niej aktywna
|
|
38
|
+
* pozycja). Domyślnie rozwinięta.
|
|
39
|
+
*/
|
|
40
|
+
expanded?: boolean;
|
|
41
|
+
}
|
|
42
|
+
/** Zakładka szybkiego dostępu. */
|
|
43
|
+
export type KptSidenavQuickTab = 'favorites' | 'recent';
|
|
44
|
+
/** Strona strzałki gałęzi: przed ikoną (`start`) albo na końcu wiersza (`end`). */
|
|
45
|
+
export type KptSidenavChevron = 'start' | 'end';
|
|
46
|
+
/** Stan zapisywany pod `storageKey`. */
|
|
47
|
+
export interface KptSidenavStoredState {
|
|
48
|
+
favorites: string[];
|
|
49
|
+
recent: string[];
|
|
50
|
+
}
|
|
51
|
+
/** Wpis indeksu: pozycja (grupa jako gałąź) i `id` jej przodków, od korzenia. */
|
|
52
|
+
export interface KptSidenavEntry<T = unknown> {
|
|
53
|
+
item: KptSidenavItem<T>;
|
|
54
|
+
ancestors: readonly string[];
|
|
55
|
+
/** Pozycja to grupa z nagłówkiem, nie wiersz menu. */
|
|
56
|
+
group: boolean;
|
|
57
|
+
}
|
|
58
|
+
/** Grupa w kształcie pozycji - tak wygląda przypięta na liście ulubionych. */
|
|
59
|
+
export declare function groupAsItem<T>(group: KptSidenavGroup<T>): KptSidenavItem<T>;
|
|
60
|
+
/** Indeks wszystkich pozycji i grup po `id`. Przy powtórzonym `id` wygrywa pierwsze wystąpienie. */
|
|
61
|
+
export declare function indexSidenav<T>(groups: readonly KptSidenavGroup<T>[]): ReadonlyMap<string, KptSidenavEntry<T>>;
|
|
62
|
+
/** Pozycje dla listy `id` w jej kolejności; `id` nieznane w menu (usunięta strona) są pomijane. */
|
|
63
|
+
export declare function resolveSidenavIds<T>(ids: readonly string[], index: ReadonlyMap<string, KptSidenavEntry<T>>): KptSidenavItem<T>[];
|
|
64
|
+
/** Czy nagłówek grupy ją zwija: własne `collapsible` grupy, a bez niego ustawienie panelu. */
|
|
65
|
+
export declare function isSidenavGroupCollapsible(group: KptSidenavGroup, panelDefault: boolean): boolean;
|
|
66
|
+
/** Czy pozycja ma pozycje podrzędne (gałąź). */
|
|
67
|
+
export declare function isSidenavBranch(item: KptSidenavItem): boolean;
|
|
68
|
+
/** Przypina albo odpina `id`. Nowe przypięcie trafia na koniec listy. */
|
|
69
|
+
export declare function toggleSidenavPin(favorites: readonly string[], id: string): string[];
|
|
70
|
+
/** Dopisuje `id` na początek ostatnich, bez powtórzeń, przycięte do `limit`. */
|
|
71
|
+
export declare function pushSidenavRecent(recent: readonly string[], id: string, limit: number): string[];
|
|
72
|
+
/** Przodkowie aktywnej pozycji - te gałęzie są rozwinięte, dopóki użytkownik ich nie zwinie. */
|
|
73
|
+
export declare function sidenavActivePath<T>(active: string | null | undefined, index: ReadonlyMap<string, KptSidenavEntry<T>>): ReadonlySet<string>;
|
|
74
|
+
/** Odczyt stanu spod `key`; `null`, gdy go nie ma, jest uszkodzony albo pamięć jest niedostępna (SSR). */
|
|
75
|
+
export declare function readSidenavState(key: string): KptSidenavStoredState | null;
|
|
76
|
+
/** Zapis stanu pod `key`. Brak miejsca albo pamięci nie przerywa pracy menu. */
|
|
77
|
+
export declare function writeSidenavState(key: string, state: KptSidenavStoredState): void;
|
package/dist/sidenav.js
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Czysty model nawigacji `kpt-sidenav`: indeks pozycji po `id`, przypinanie, lista ostatnich
|
|
3
|
+
* i zapis w `localStorage`. Wspólny dla portów Angulara i Reacta.
|
|
4
|
+
*/
|
|
5
|
+
/** Grupa w kształcie pozycji - tak wygląda przypięta na liście ulubionych. */
|
|
6
|
+
export function groupAsItem(group) {
|
|
7
|
+
return { id: group.id, label: group.label, icon: group.icon, children: group.items, pinnable: group.pinnable };
|
|
8
|
+
}
|
|
9
|
+
/** Indeks wszystkich pozycji i grup po `id`. Przy powtórzonym `id` wygrywa pierwsze wystąpienie. */
|
|
10
|
+
export function indexSidenav(groups) {
|
|
11
|
+
const index = new Map();
|
|
12
|
+
const walk = (items, ancestors) => {
|
|
13
|
+
for (const item of items) {
|
|
14
|
+
if (!index.has(item.id))
|
|
15
|
+
index.set(item.id, { item, ancestors, group: false });
|
|
16
|
+
if (item.children?.length)
|
|
17
|
+
walk(item.children, [...ancestors, item.id]);
|
|
18
|
+
}
|
|
19
|
+
};
|
|
20
|
+
for (const group of groups) {
|
|
21
|
+
if (!index.has(group.id))
|
|
22
|
+
index.set(group.id, { item: groupAsItem(group), ancestors: [], group: true });
|
|
23
|
+
walk(group.items, [group.id]);
|
|
24
|
+
}
|
|
25
|
+
return index;
|
|
26
|
+
}
|
|
27
|
+
/** Pozycje dla listy `id` w jej kolejności; `id` nieznane w menu (usunięta strona) są pomijane. */
|
|
28
|
+
export function resolveSidenavIds(ids, index) {
|
|
29
|
+
const out = [];
|
|
30
|
+
for (const id of ids) {
|
|
31
|
+
const entry = index.get(id);
|
|
32
|
+
if (entry)
|
|
33
|
+
out.push(entry.item);
|
|
34
|
+
}
|
|
35
|
+
return out;
|
|
36
|
+
}
|
|
37
|
+
/** Czy nagłówek grupy ją zwija: własne `collapsible` grupy, a bez niego ustawienie panelu. */
|
|
38
|
+
export function isSidenavGroupCollapsible(group, panelDefault) {
|
|
39
|
+
return group.collapsible ?? panelDefault;
|
|
40
|
+
}
|
|
41
|
+
/** Czy pozycja ma pozycje podrzędne (gałąź). */
|
|
42
|
+
export function isSidenavBranch(item) {
|
|
43
|
+
return !!item.children?.length;
|
|
44
|
+
}
|
|
45
|
+
/** Przypina albo odpina `id`. Nowe przypięcie trafia na koniec listy. */
|
|
46
|
+
export function toggleSidenavPin(favorites, id) {
|
|
47
|
+
return favorites.includes(id) ? favorites.filter((x) => x !== id) : [...favorites, id];
|
|
48
|
+
}
|
|
49
|
+
/** Dopisuje `id` na początek ostatnich, bez powtórzeń, przycięte do `limit`. */
|
|
50
|
+
export function pushSidenavRecent(recent, id, limit) {
|
|
51
|
+
if (limit <= 0)
|
|
52
|
+
return [];
|
|
53
|
+
return [id, ...recent.filter((x) => x !== id)].slice(0, limit);
|
|
54
|
+
}
|
|
55
|
+
/** Przodkowie aktywnej pozycji - te gałęzie są rozwinięte, dopóki użytkownik ich nie zwinie. */
|
|
56
|
+
export function sidenavActivePath(active, index) {
|
|
57
|
+
return new Set(active ? (index.get(active)?.ancestors ?? []) : []);
|
|
58
|
+
}
|
|
59
|
+
function storage() {
|
|
60
|
+
try {
|
|
61
|
+
return typeof localStorage === 'undefined' ? null : localStorage;
|
|
62
|
+
}
|
|
63
|
+
catch {
|
|
64
|
+
// Safari w trybie prywatnym i zablokowane cookies rzucają już przy odczycie właściwości.
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
const isStringArray = (value) => Array.isArray(value) && value.every((x) => typeof x === 'string');
|
|
69
|
+
/** Odczyt stanu spod `key`; `null`, gdy go nie ma, jest uszkodzony albo pamięć jest niedostępna (SSR). */
|
|
70
|
+
export function readSidenavState(key) {
|
|
71
|
+
try {
|
|
72
|
+
const raw = storage()?.getItem(key);
|
|
73
|
+
if (!raw)
|
|
74
|
+
return null;
|
|
75
|
+
const parsed = JSON.parse(raw);
|
|
76
|
+
return {
|
|
77
|
+
favorites: isStringArray(parsed.favorites) ? parsed.favorites : [],
|
|
78
|
+
recent: isStringArray(parsed.recent) ? parsed.recent : [],
|
|
79
|
+
};
|
|
80
|
+
}
|
|
81
|
+
catch {
|
|
82
|
+
return null;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
/** Zapis stanu pod `key`. Brak miejsca albo pamięci nie przerywa pracy menu. */
|
|
86
|
+
export function writeSidenavState(key, state) {
|
|
87
|
+
try {
|
|
88
|
+
storage()?.setItem(key, JSON.stringify(state));
|
|
89
|
+
}
|
|
90
|
+
catch {
|
|
91
|
+
// Pełna pamięć albo zablokowany zapis - stan zostaje w komponencie.
|
|
92
|
+
}
|
|
93
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,46 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@konce-pt/nav",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.19.0",
|
|
4
|
+
"description": "Navigation core for Koncept UI - item index, favorites, recently opened items and their storage for the side navigation. Framework-free TypeScript, zero runtime dependencies.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "konce.pt",
|
|
7
|
+
"homepage": "https://ui.konce.pt/",
|
|
8
|
+
"repository": {
|
|
9
|
+
"type": "git",
|
|
10
|
+
"url": "git+https://gitlab.com/konce-pt/koncept-ui.git",
|
|
11
|
+
"directory": "packages/nav"
|
|
12
|
+
},
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
|
|
15
|
+
},
|
|
16
|
+
"keywords": [
|
|
17
|
+
"navigation",
|
|
18
|
+
"sidenav",
|
|
19
|
+
"favorites",
|
|
20
|
+
"design-system",
|
|
21
|
+
"koncept-ui",
|
|
22
|
+
"kpt"
|
|
23
|
+
],
|
|
24
|
+
"type": "module",
|
|
25
|
+
"sideEffects": false,
|
|
26
|
+
"files": [
|
|
27
|
+
"dist"
|
|
28
|
+
],
|
|
29
|
+
"module": "./dist/index.js",
|
|
30
|
+
"types": "./dist/index.d.ts",
|
|
31
|
+
"exports": {
|
|
32
|
+
".": {
|
|
33
|
+
"types": "./dist/index.d.ts",
|
|
34
|
+
"default": "./dist/index.js"
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
"devDependencies": {
|
|
38
|
+
"typescript": "~6.0.3"
|
|
39
|
+
},
|
|
40
|
+
"scripts": {
|
|
41
|
+
"build": "tsc -p tsconfig.build.json",
|
|
42
|
+
"test": "node --test --experimental-test-coverage --test-coverage-exclude=\"src/**/*.test.ts\" --test-coverage-lines=99 --test-coverage-branches=99 --test-coverage-functions=99 \"src/**/*.test.ts\"",
|
|
43
|
+
"lint": "eslint .",
|
|
44
|
+
"clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
|
|
45
|
+
}
|
|
6
46
|
}
|