@konce-pt/roadmap 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,54 @@
+<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/roadmap
+
+Rdzeń roadmapy typu Gantt [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): arytmetyka
+kalendarzowa (ISO 8601), model osi czasu, układ wierszy z pakowaniem pasów i geometria zależności.
+Czysty TypeScript, **zero zależności runtime**, bez wiązania z frameworkiem.
+
+Zwykle nie instalujesz go samodzielnie: używają go `@konce-pt/angular/roadmap`
+i `@konce-pt/react/roadmap`, i oba re-eksportują jego API. Sięgnij po niego wprost, gdy liczysz
+harmonogram po stronie serwera albo budujesz własny widok na tej samej geometrii.
+
+```bash
+npm i @konce-pt/roadmap
+```
+
+```ts
+import { buildTimeline, autoRange, isoWeekNumber } from '@konce-pt/roadmap';
+
+// Numeracja ISO: tydzień 1 zawiera pierwszy czwartek roku.
+isoWeekNumber(new Date(2027, 0, 1)); // 53
+
+// Oś wyliczona z danych i wyrównana do pełnych jednostek.
+const range = autoRange(items, { zoom: 'week' });
+
+// Kolumny równej szerokości mimo zmiany czasu; span() daje pozycję paska jako ułamek osi.
+const timeline = buildTimeline(range, 'week', { weekPrefix: 'W' });
+timeline.span(start, end); // { left, width, visible, clippedStart, clippedEnd }
+```
+
+## API
+
+- **Kalendarz** — `isoWeekNumber`, `isoWeekYear`, `isoWeekday`, `isoWeeksInYear`, `startOfIsoWeek`,
+  `startOfDay`, `addDays`, `addHours`, `addMonths`, `addUnits`, `floorToUnit`, `ceilToUnit`,
+  `countUnits`, `diffDays`, `daysInMonth`, `isSameDay`, `toTimestamp`
+- **Oś czasu** — `buildTimeline`
+- **Wiersze** — `normalizeItems`, `buildRows`, `packLanes`, `sliceRows`, `spanOf`, `rollupProgress`
+- **Zależności** — `resolveLinks`, `linkGeometry`, `roundedPolyline`, `arrowHead`
+- **Zakres** — `autoRange`, `resolveRange`
+- **Typy** — `KptRoadmapConfig` i wszystko, do czego się odwołuje
+
+Pełny opis: [`llms.txt`](./llms.txt) (EN) i [`llms-pl.txt`](./llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/roadmap exec node --import ../../scripts/test-node-setup.mjs --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/auto-range.d.ts

@@ -0,0 +1,22 @@
+import type { KptRoadmapConfig, KptRoadmapItem, KptRoadmapNormalizedItem, KptRoadmapZoom, KptTimeRange } from './types.ts';
+export interface KptAutoRangeOptions {
+    zoom: KptRoadmapZoom;
+    /** Margines po obu stronach w jednostkach zoomu. */
+    padUnits?: number;
+    /** Minimalna szerokość osi w jednostkach zoomu. */
+    minUnits?: number;
+    /** Czy zakres ma zawsze obejmować „dziś". Domyślnie true. */
+    includeToday?: boolean;
+    today?: number;
+}
+/**
+ * Zakres osi wyliczony z danych: min(start)…max(end) powiększony o margines
+ * i wyrównany do granic jednostki zoomu.
+ * Dla pustej listy zwraca okno wokół „dziś" o szerokości `minUnits`.
+ */
+export declare function autoRange(items: readonly KptRoadmapItem[], opts: KptAutoRangeOptions): KptTimeRange;
+/**
+ * Ostateczny zakres osi. `config.range` ma priorytet, a brakujący kraniec
+ * uzupełniamy z `autoRange`. Wynik zawsze leży na granicach jednostki zoomu.
+ */
+export declare function resolveRange(config: Pick<KptRoadmapConfig, 'range' | 'zoom' | 'today' | 'timeline'>, items: readonly (KptRoadmapItem | KptRoadmapNormalizedItem)[]): KptTimeRange;

package/dist/auto-range.js

@@ -0,0 +1,88 @@
+/*
+ * Wyznaczanie zakresu osi czasu z danych.
+ *
+ * Krańce zawsze wyrównujemy na zewnątrz do granicy jednostki zoomu, żeby
+ * pierwsza i ostatnia kolumna nie były ucięte w połowie.
+ */
+import { addUnits, ceilToUnit, countUnits, floorToUnit, toTimestamp } from "./calendar.js";
+import { extent } from "./scale.js";
+/** Margines po obu stronach danych, w jednostkach zoomu. */
+const DEFAULT_PAD = {
+    hour: 2,
+    day: 2,
+    week: 1,
+    month: 1,
+    quarter: 1,
+    year: 0,
+};
+/** Minimalna szerokość osi, w jednostkach zoomu — żeby jeden item nie dał jednej kolumny. */
+const DEFAULT_MIN = {
+    hour: 12,
+    day: 14,
+    week: 8,
+    month: 6,
+    quarter: 4,
+    year: 3,
+};
+/** Zbiera skrajne wartości czasu z itemów, pomijając wpisy z niepoprawną datą. */
+function collectBounds(items) {
+    const bounds = [];
+    for (const item of items) {
+        const start = toTimestamp(item.start);
+        if (!Number.isFinite(start))
+            continue;
+        const end = item.end !== undefined ? toTimestamp(item.end) : start;
+        bounds.push(start, Number.isFinite(end) ? end : start);
+    }
+    return bounds;
+}
+/**
+ * Zakres osi wyliczony z danych: min(start)…max(end) powiększony o margines
+ * i wyrównany do granic jednostki zoomu.
+ * Dla pustej listy zwraca okno wokół „dziś" o szerokości `minUnits`.
+ */
+export function autoRange(items, opts) {
+    const { zoom } = opts;
+    const pad = opts.padUnits ?? DEFAULT_PAD[zoom];
+    const minUnits = opts.minUnits ?? DEFAULT_MIN[zoom];
+    const todayTs = opts.today ?? Date.now();
+    const bounds = collectBounds(items);
+    if ((opts.includeToday ?? true) && bounds.length > 0)
+        bounds.push(todayTs);
+    const [min, max] = bounds.length > 0 ? extent(bounds) : [todayTs, todayTs];
+    // Margines dodajemy po polach daty (DST-safe), nie przez arytmetykę na ms.
+    let start = floorToUnit(addUnits(new Date(min), zoom, -pad), zoom);
+    let end = ceilToUnit(addUnits(new Date(max), zoom, pad), zoom);
+    // Dociągnięcie do minimalnej szerokości — symetrycznie, zaczynając od prawej.
+    let units = countUnits(start, end, zoom);
+    while (units < minUnits) {
+        end = addUnits(end, zoom, 1);
+        units++;
+        if (units < minUnits) {
+            start = addUnits(start, zoom, -1);
+            units++;
+        }
+    }
+    return { start: start.getTime(), end: end.getTime() };
+}
+/**
+ * Ostateczny zakres osi. `config.range` ma priorytet, a brakujący kraniec
+ * uzupełniamy z `autoRange`. Wynik zawsze leży na granicach jednostki zoomu.
+ */
+export function resolveRange(config, items) {
+    const zoom = config.zoom ?? 'week';
+    const todaySource = config.today ?? config.timeline?.today;
+    const today = todaySource !== undefined ? toTimestamp(todaySource) : Date.now();
+    // `KptRoadmapNormalizedItem` niesie oryginał w `source` — sprowadzamy oba kształty
+    // do postaci akceptowanej przez `autoRange`.
+    const raw = items.map((item) => ('source' in item ? item.source : item));
+    const auto = autoRange(raw, { zoom, today });
+    const startTs = config.range?.start ?? auto.start;
+    const endTs = config.range?.end ?? auto.end;
+    const start = floorToUnit(new Date(startTs), zoom);
+    let end = ceilToUnit(new Date(endTs), zoom);
+    // Zakres musi obejmować co najmniej jedną kolumnę.
+    if (end.getTime() <= start.getTime())
+        end = addUnits(start, zoom, 1);
+    return { start: start.getTime(), end: end.getTime() };
+}

package/dist/calendar.d.ts

@@ -0,0 +1,64 @@
+import type { KptDateInput, KptRoadmapZoom } from './types.ts';
+/** Normalizuje dowolne wejście daty do epoch ms. Zwraca NaN dla wartości nieparsowalnych. */
+export declare function toTimestamp(value: KptDateInput): number;
+/**
+ * Początek lokalnej doby.
+ *
+ * Guard: w strefach, gdzie przejście DST wypada o północy (np. America/Santiago),
+ * `setHours(0, …)` potrafi wylądować w dobie poprzedniej — wtedy korygujemy
+ * o jedną dobę w przód.
+ */
+export declare function startOfDay(date: Date): Date;
+/** Dodaje `n` dób kalendarzowych, zachowując godzinę ścienną (DST-safe). */
+export declare function addDays(date: Date, n: number): Date;
+/** Dodaje `n` godzin ściennych. Godzina nieistniejąca (wiosna) normalizuje się w przód. */
+export declare function addHours(date: Date, n: number): Date;
+/** Liczba dni w miesiącu (`month` 0-indeksowany). */
+export declare function daysInMonth(year: number, month: number): number;
+/** Dodaje `n` miesięcy z przycięciem dnia (31 stycznia + 1 miesiąc = 28/29 lutego). */
+export declare function addMonths(date: Date, n: number): Date;
+/**
+ * Różnica w pełnych dobach kalendarzowych.
+ * `Math.round` jest konieczny: doba DST ma 23 h (0.958) albo 25 h (1.042),
+ * więc `Math.floor` gubiłby jeden dzień dwa razy w roku.
+ */
+export declare function diffDays(a: Date, b: Date): number;
+/** Czy obie daty wypadają w tej samej lokalnej dobie? */
+export declare function isSameDay(a: Date, b: Date): boolean;
+/**
+ * Dzień tygodnia wg ISO 8601: 1 = poniedziałek … 7 = niedziela.
+ * `Date#getDay()` zwraca 0 dla niedzieli, stąd przesunięcie.
+ */
+export declare function isoWeekday(date: Date): number;
+/** Poniedziałek tygodnia ISO zawierającego `date` (początek doby). */
+export declare function startOfIsoWeek(date: Date): Date;
+/**
+ * Rok tygodnia ISO 8601 — bywa różny od `getFullYear()` na przełomie roku.
+ * Przykłady: 2025-12-29 → 2026 (tydzień 1), 2027-01-03 → 2026 (tydzień 53).
+ */
+export declare function isoWeekYear(date: Date): number;
+/**
+ * Numer tygodnia ISO 8601 (1..53).
+ * Tydzień zaczyna się w poniedziałek, a tydzień 1 to ten, który zawiera pierwszy
+ * czwartek roku (równoważnie: zawiera 4 stycznia).
+ *
+ * `Math.round` jest tu krytyczny: przy DST różnica dwóch północy to 7 dni ±1 h
+ * (6.994 / 7.006), więc `Math.floor` zaniżałby numer tygodnia przez pół roku.
+ */
+export declare function isoWeekNumber(date: Date): number;
+/** Liczba tygodni ISO w danym roku tygodniowym (52 albo 53). */
+export declare function isoWeeksInYear(weekYear: number): number;
+/** Początek jednostki zoomu zawierającej `date` (w dół). */
+export declare function floorToUnit(date: Date, zoom: KptRoadmapZoom): Date;
+/** Dodaje `n` jednostek zoomu (DST-safe — po polach daty, nie po ms). */
+export declare function addUnits(date: Date, zoom: KptRoadmapZoom, n: number): Date;
+/** Początek następnej jednostki zoomu; bez zmian, gdy `date` już leży na granicy. */
+export declare function ceilToUnit(date: Date, zoom: KptRoadmapZoom): Date;
+/**
+ * Liczba pełnych jednostek zoomu między dwiema granicami (DST-safe).
+ * Dla 'hour' liczymy wprost po ms — doba DST po prostu ma 23 albo 25 godzin
+ * i tyle właśnie powinno powstać kolumn.
+ */
+export declare function countUnits(start: Date, end: Date, zoom: KptRoadmapZoom): number;
+/** Numer kwartału (1..4) dla danej daty. */
+export declare function quarterOf(date: Date): number;

package/dist/calendar.js

@@ -0,0 +1,205 @@
+/*
+ * Arytmetyka kalendarzowa w czasie LOKALNYM, odporna na zmianę czasu (DST).
+ *
+ * Roadmapa jest narzędziem planistycznym — użytkownik myśli zegarem ściennym,
+ * więc wszystkie obliczenia idą po lokalnych polach daty.
+ *
+ * ZASADA: nigdy nie dodajemy milisekund. `t + 86_400_000` na 2026-03-29 00:00 CET
+ * daje 2026-03-30 01:00 (dryf kumulatywny), a na 2026-10-25 daje tę samą datę
+ * dwa razy. Zamiast tego iterujemy po polach `Date` (`setDate`, `setHours`),
+ * bo one normalizują wynik do lokalnego zegara ściennego.
+ *
+ * Wszystkie różnice dni/tygodni liczymy przez `Math.round`, nigdy `floor`/`ceil`:
+ * doba DST to 0.958 albo 1.042 doby, a `round` te odchyłki pochłania.
+ */
+const MS_DAY = 86_400_000;
+const MS_WEEK = 604_800_000;
+const MS_HOUR = 3_600_000;
+/** Normalizuje dowolne wejście daty do epoch ms. Zwraca NaN dla wartości nieparsowalnych. */
+export function toTimestamp(value) {
+    if (typeof value === 'number')
+        return value;
+    if (value instanceof Date)
+        return value.getTime();
+    return new Date(value).getTime();
+}
+/** Kopia obiektu Date — nigdy nie mutujemy argumentów. */
+function clone(date) {
+    return new Date(date);
+}
+/**
+ * Początek lokalnej doby.
+ *
+ * Guard: w strefach, gdzie przejście DST wypada o północy (np. America/Santiago),
+ * `setHours(0, …)` potrafi wylądować w dobie poprzedniej — wtedy korygujemy
+ * o jedną dobę w przód.
+ */
+export function startOfDay(date) {
+    const result = clone(date);
+    result.setHours(0, 0, 0, 0);
+    if (result.getDate() !== date.getDate() || result.getMonth() !== date.getMonth()) {
+        result.setTime(date.getTime());
+        result.setHours(0, 0, 0, 0);
+        if (result.getTime() < date.getTime() - MS_DAY)
+            result.setDate(result.getDate() + 1);
+    }
+    return result;
+}
+/** Dodaje `n` dób kalendarzowych, zachowując godzinę ścienną (DST-safe). */
+export function addDays(date, n) {
+    const result = clone(date);
+    result.setDate(result.getDate() + n);
+    return result;
+}
+/** Dodaje `n` godzin ściennych. Godzina nieistniejąca (wiosna) normalizuje się w przód. */
+export function addHours(date, n) {
+    const result = clone(date);
+    result.setHours(result.getHours() + n);
+    return result;
+}
+/** Liczba dni w miesiącu (`month` 0-indeksowany). */
+export function daysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+/** Dodaje `n` miesięcy z przycięciem dnia (31 stycznia + 1 miesiąc = 28/29 lutego). */
+export function addMonths(date, n) {
+    const result = clone(date);
+    const day = result.getDate();
+    result.setDate(1);
+    result.setMonth(result.getMonth() + n);
+    result.setDate(Math.min(day, daysInMonth(result.getFullYear(), result.getMonth())));
+    return result;
+}
+/**
+ * Różnica w pełnych dobach kalendarzowych.
+ * `Math.round` jest konieczny: doba DST ma 23 h (0.958) albo 25 h (1.042),
+ * więc `Math.floor` gubiłby jeden dzień dwa razy w roku.
+ */
+export function diffDays(a, b) {
+    return Math.round((startOfDay(b).getTime() - startOfDay(a).getTime()) / MS_DAY);
+}
+/** Czy obie daty wypadają w tej samej lokalnej dobie? */
+export function isSameDay(a, b) {
+    return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+}
+// ──────────────────────────────────────────────────────────────────── ISO 8601
+/**
+ * Dzień tygodnia wg ISO 8601: 1 = poniedziałek … 7 = niedziela.
+ * `Date#getDay()` zwraca 0 dla niedzieli, stąd przesunięcie.
+ */
+export function isoWeekday(date) {
+    return ((date.getDay() + 6) % 7) + 1;
+}
+/** Poniedziałek tygodnia ISO zawierającego `date` (początek doby). */
+export function startOfIsoWeek(date) {
+    const day = startOfDay(date);
+    return startOfDay(addDays(day, -(isoWeekday(day) - 1)));
+}
+/**
+ * Czwartek tygodnia ISO zawierającego `date`.
+ *
+ * Czwartek jest kotwicą ISO: rok czwartka to rok tygodnia, a odległość między
+ * czwartkami dwóch tygodni to zawsze dokładnie N tygodni.
+ */
+function isoThursday(date) {
+    const day = startOfDay(date);
+    return startOfDay(addDays(day, 4 - isoWeekday(day)));
+}
+/**
+ * Rok tygodnia ISO 8601 — bywa różny od `getFullYear()` na przełomie roku.
+ * Przykłady: 2025-12-29 → 2026 (tydzień 1), 2027-01-03 → 2026 (tydzień 53).
+ */
+export function isoWeekYear(date) {
+    return isoThursday(date).getFullYear();
+}
+/**
+ * Numer tygodnia ISO 8601 (1..53).
+ * Tydzień zaczyna się w poniedziałek, a tydzień 1 to ten, który zawiera pierwszy
+ * czwartek roku (równoważnie: zawiera 4 stycznia).
+ *
+ * `Math.round` jest tu krytyczny: przy DST różnica dwóch północy to 7 dni ±1 h
+ * (6.994 / 7.006), więc `Math.floor` zaniżałby numer tygodnia przez pół roku.
+ */
+export function isoWeekNumber(date) {
+    const thursday = isoThursday(date);
+    const jan4 = new Date(thursday.getFullYear(), 0, 4);
+    const firstThursday = isoThursday(jan4);
+    return 1 + Math.round((thursday.getTime() - firstThursday.getTime()) / MS_WEEK);
+}
+/** Liczba tygodni ISO w danym roku tygodniowym (52 albo 53). */
+export function isoWeeksInYear(weekYear) {
+    // 28 grudnia zawsze leży w ostatnim tygodniu ISO danego roku.
+    return isoWeekNumber(new Date(weekYear, 11, 28));
+}
+// ─────────────────────────────────────────────────── zaokrąglanie do jednostki
+/** Początek jednostki zoomu zawierającej `date` (w dół). */
+export function floorToUnit(date, zoom) {
+    const result = clone(date);
+    switch (zoom) {
+        case 'hour':
+            result.setMinutes(0, 0, 0);
+            return result;
+        case 'day':
+            return startOfDay(result);
+        case 'week':
+            return startOfIsoWeek(result);
+        case 'month':
+            result.setDate(1);
+            return startOfDay(result);
+        case 'quarter':
+            result.setMonth(Math.floor(result.getMonth() / 3) * 3, 1);
+            return startOfDay(result);
+        case 'year':
+            result.setMonth(0, 1);
+            return startOfDay(result);
+    }
+}
+/** Dodaje `n` jednostek zoomu (DST-safe — po polach daty, nie po ms). */
+export function addUnits(date, zoom, n) {
+    switch (zoom) {
+        case 'hour':
+            return addHours(date, n);
+        case 'day':
+            return addDays(date, n);
+        case 'week':
+            return addDays(date, n * 7);
+        case 'month':
+            return addMonths(date, n);
+        case 'quarter':
+            return addMonths(date, n * 3);
+        case 'year':
+            return addMonths(date, n * 12);
+    }
+}
+/** Początek następnej jednostki zoomu; bez zmian, gdy `date` już leży na granicy. */
+export function ceilToUnit(date, zoom) {
+    const floored = floorToUnit(date, zoom);
+    if (floored.getTime() === date.getTime())
+        return floored;
+    return addUnits(floored, zoom, 1);
+}
+/**
+ * Liczba pełnych jednostek zoomu między dwiema granicami (DST-safe).
+ * Dla 'hour' liczymy wprost po ms — doba DST po prostu ma 23 albo 25 godzin
+ * i tyle właśnie powinno powstać kolumn.
+ */
+export function countUnits(start, end, zoom) {
+    switch (zoom) {
+        case 'hour':
+            return Math.round((end.getTime() - start.getTime()) / MS_HOUR);
+        case 'day':
+            return diffDays(start, end);
+        case 'week':
+            return Math.round(diffDays(start, end) / 7);
+        case 'month':
+            return (end.getFullYear() - start.getFullYear()) * 12 + (end.getMonth() - start.getMonth());
+        case 'quarter':
+            return Math.round(((end.getFullYear() - start.getFullYear()) * 12 + (end.getMonth() - start.getMonth())) / 3);
+        case 'year':
+            return end.getFullYear() - start.getFullYear();
+    }
+}
+/** Numer kwartału (1..4) dla danej daty. */
+export function quarterOf(date) {
+    return Math.floor(date.getMonth() / 3) + 1;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export * from './types.ts';
+export * from './scale.ts';
+export * from './calendar.ts';
+export * from './timeline.ts';
+export * from './layout.ts';
+export * from './links.ts';
+export * from './auto-range.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+/* Rdzeń roadmapy (pure TS) — barrel eksportów. */
+export * from "./types.js";
+export * from "./scale.js";
+export * from "./calendar.js";
+export * from "./timeline.js";
+export * from "./layout.js";
+export * from "./links.js";
+export * from "./auto-range.js";

package/dist/layout.d.ts

@@ -0,0 +1,94 @@
+import type { KptRoadmapGroup, KptRoadmapItem, KptRoadmapNormalizedItem, KptRoadmapRowOptions, KptTimeRange } from './types.ts';
+export type KptRoadmapRowKind = 'group' | 'item';
+/** Item osadzony w konkretnym wierszu i pasie. */
+export interface KptRoadmapPlacedItem<TMeta = unknown> extends KptRoadmapNormalizedItem<TMeta> {
+    /** Indeks pasa w obrębie wiersza (0 przy trybie 'row-per-item'). */
+    lane: number;
+    rowKey: string;
+}
+/** Wyliczony agregat grupy. */
+export interface KptRoadmapGroupState {
+    collapsed: boolean;
+    /** Liczba itemów należących do grupy. */
+    itemCount: number;
+    /** Zakres zbiorczy (null, gdy grupa pusta). */
+    span: KptTimeRange | null;
+    /** Postęp ważony czasem trwania, 0..1 (null, gdy żaden item go nie podaje). */
+    progress: number | null;
+}
+/** Wiersz renderowalny — jednostka wirtualizacji. */
+export interface KptRoadmapRow<TItem = unknown, TGroup = unknown> {
+    key: string;
+    kind: KptRoadmapRowKind;
+    /** Indeks w spłaszczonej liście widocznych wierszy. */
+    index: number;
+    /** Poziom zagnieżdżenia — wcięcie w kolumnie etykiet. */
+    depth: number;
+    /** Offset od góry w px (skumulowany). */
+    top: number;
+    height: number;
+    /** Liczba pasów (>1 tylko w trybie 'pack'). */
+    laneCount: number;
+    /** Wypełnione dla `kind === 'group'`. */
+    group?: KptRoadmapGroup<TGroup>;
+    groupState?: KptRoadmapGroupState;
+    /** Wypełnione dla `kind === 'item'`. */
+    items: readonly KptRoadmapPlacedItem<TItem>[];
+}
+/** Wpis odrzucony przy normalizacji — do ostrzeżeń w trybie deweloperskim. */
+export interface KptRoadmapInvalidItem {
+    id: string;
+    reason: string;
+}
+export interface KptRoadmapLayout<TItem = unknown, TGroup = unknown> {
+    rows: readonly KptRoadmapRow<TItem, TGroup>[];
+    /** Łączna wysokość w px. */
+    totalHeight: number;
+    /** Wszystkie znormalizowane itemy po `id` — także te w zwiniętych grupach. */
+    byId: ReadonlyMap<string, KptRoadmapNormalizedItem<TItem>>;
+    /** Mapa `itemId → rowKey` dla itemów widocznych. */
+    rowOfItem: ReadonlyMap<string, string>;
+    /** Itemy odrzucone (zła data, duplikat `id`). */
+    invalid: readonly KptRoadmapInvalidItem[];
+}
+/**
+ * Normalizuje itemy: daty na ms, brak `end` oznacza kamień milowy.
+ * Odrzuca wpisy z nieparsowalną datą oraz duplikaty `id`.
+ */
+export declare function normalizeItems<T>(items: readonly KptRoadmapItem<T>[]): {
+    valid: KptRoadmapNormalizedItem<T>[];
+    invalid: KptRoadmapInvalidItem[];
+};
+/** Zakres zbiorczy listy itemów: min(start)…max(end). */
+export declare function spanOf(items: readonly KptRoadmapNormalizedItem[]): KptTimeRange | null;
+/**
+ * Postęp grupy ważony czasem trwania.
+ * Kamienie milowe mają zerową długość, więc liczymy je z wagą 1.
+ */
+export declare function rollupProgress(items: readonly KptRoadmapNormalizedItem[]): number | null;
+/**
+ * Zachłanne przydzielanie pasów (interval partitioning).
+ * Itemy sortujemy po czasie startu i wkładamy do pierwszego pasa, w którym
+ * poprzednie zadanie zdążyło się skończyć. Zwraca liczbę użytych pasów.
+ */
+export declare function packLanes(items: KptRoadmapPlacedItem[], minGapMs?: number): number;
+/**
+ * Spłaszcza grupy i itemy do listy wierszy renderowalnych.
+ *
+ * Kolejność: grupy w kolejności podanej przez użytkownika, wewnątrz itemy
+ * posortowane po czasie startu, na końcu itemy bez `groupId`. Zwinięta grupa
+ * nie emituje wierszy potomnych, ale jej zakres zbiorczy nadal obejmuje dzieci.
+ *
+ * @param collapsed zbiór `id` grup zwiniętych (stan trzymany w sygnale komponentu)
+ */
+export declare function buildRows<TItem, TGroup>(items: readonly KptRoadmapItem<TItem>[], groups: readonly KptRoadmapGroup<TGroup>[] | undefined, collapsed: ReadonlySet<string>, opts?: KptRoadmapRowOptions): KptRoadmapLayout<TItem, TGroup>;
+/**
+ * Wycinek wierszy widocznych w oknie przewijania.
+ * Szuka binarnie po skumulowanym `top`, więc działa także dla wierszy
+ * o różnej wysokości (tryb 'pack').
+ */
+export declare function sliceRows<TItem, TGroup>(layout: KptRoadmapLayout<TItem, TGroup>, scrollTop: number, viewportHeight: number, buffer?: number): {
+    rows: readonly KptRoadmapRow<TItem, TGroup>[];
+    startIndex: number;
+    endIndex: number;
+};