@konce-pt/roadmap 0.8.0

package/dist/timeline.d.ts

@@ -0,0 +1,90 @@
+import type { KptRoadmapPositionMode, KptRoadmapZoom, KptTimeRange, KptTimelineOptions } from './types.ts';
+/** Pojedyncza kolumna dolnego poziomu nagłówka i linii siatki. */
+export interface KptTimelineCell {
+    /** Indeks w `cells` (0-based) — podstawa skali 'uniform'. */
+    index: number;
+    /** Klucz trackBy. */
+    key: string;
+    /** Początek jednostki (ms, lokalny). */
+    start: number;
+    /** Początek następnej jednostki (ms, wyłącznie). Uwzględnia doby 23/25 h. */
+    end: number;
+    /** Etykieta dolnego poziomu, np. '35', '24', '09:00'. */
+    label: string;
+    /** Podpis pod etykietą, np. '24.08–30.08' albo 'pon'. */
+    sublabel?: string;
+    /** Pełny opis do atrybutu `title`. */
+    title: string;
+    /** Lewa krawędź 0..1. */
+    ratioStart: number;
+    /** Prawa krawędź 0..1. */
+    ratioEnd: number;
+    isToday: boolean;
+    isWeekend: boolean;
+    /** Poza oknem godzin roboczych (tylko `workHours.mode === 'dim'`). */
+    isNonWorking: boolean;
+    isMonthBoundary: boolean;
+    isQuarterBoundary: boolean;
+    isYearBoundary: boolean;
+    /** Przed tą kolumną wycięto zakres (`workHours.mode === 'skip'`). */
+    hasGapBefore: boolean;
+}
+/** Grupa kolumn tworząca górny poziom nagłówka (np. miesiąc nad tygodniami). */
+export interface KptTimelineBand {
+    key: string;
+    start: number;
+    end: number;
+    /** Indeks pierwszej i ostatniej obejmowanej kolumny (włącznie). */
+    fromIndex: number;
+    toIndex: number;
+    /** Liczba obejmowanych kolumn. */
+    span: number;
+    ratioStart: number;
+    ratioEnd: number;
+    /** Etykieta główna, np. 'sierpień'. */
+    label: string;
+    /** Etykieta pomocnicza, np. '2026'. */
+    sublabel?: string;
+    /** Pierwsze pasmo danego roku — nośnik czarnego znacznika roku. */
+    isYearStart: boolean;
+    /** Rok do znacznika; ustawiony tylko gdy `isYearStart`. */
+    yearBadge?: string;
+}
+/** Geometria paska na osi (wartości 0..1). */
+export interface KptSpanGeom {
+    left: number;
+    width: number;
+    /** Item zaczyna się przed lewą krawędzią zakresu. */
+    clippedStart: boolean;
+    /** Item kończy się za prawą krawędzią zakresu. */
+    clippedEnd: boolean;
+    /** Czy jakakolwiek część mieści się w zakresie. */
+    visible: boolean;
+}
+/** Niemutowalny model osi czasu — wynik `buildTimeline`. */
+export interface KptTimelineModel {
+    zoom: KptRoadmapZoom;
+    range: KptTimeRange;
+    positionMode: KptRoadmapPositionMode;
+    cells: readonly KptTimelineCell[];
+    bands: readonly KptTimelineBand[];
+    /** Czy górny poziom nagłówka istnieje. */
+    hasBands: boolean;
+    /** Pozycja „dziś" 0..1 albo null, gdy poza zakresem. */
+    todayRatio: number | null;
+    /** Czas → pozycja 0..1 (monotoniczna, clampowana do zakresu). */
+    toRatio(timestamp: number): number;
+    /** Pozycja 0..1 → czas (odwrotność `toRatio`; podstawa pod drag&drop). */
+    fromRatio(ratio: number): number;
+    /** Geometria przedziału wraz z informacją o przycięciu. */
+    span(startTs: number, endTs: number): KptSpanGeom;
+}
+/**
+ * Buduje model osi czasu: kolumny, pasma nagłówka i skalę.
+ * Wszystkie obliczenia w czasie LOKALNYM przeglądarki.
+ *
+ * @param range zakres osi w ms — zwykle wynik `resolveRange`
+ * @param zoom  poziom przybliżenia
+ * @param opts  locale, „dziś", weekendy, godziny robocze, tryb pozycjonowania
+ */
+export declare function buildTimeline(range: KptTimeRange, zoom: KptRoadmapZoom, opts?: KptTimelineOptions): KptTimelineModel;

package/dist/timeline.js

@@ -0,0 +1,375 @@
+/*
+ * Model osi czasu: kolumny dolnego poziomu nagłówka, pasma górnego poziomu
+ * oraz skala czas ↔ pozycja.
+ *
+ * Skala domyślna ('uniform') odwzorowuje czas odcinkami: każda kolumna ma równą
+ * szerokość, a wewnątrz niej interpolujemy liniowo po ms. Dzięki temu doba po
+ * zmianie czasu (23/25 h) i luty nie są węższe od sąsiadów, a skala pozostaje
+ * ciągła i monotoniczna — zadanie może zaczynać się w środku dnia.
+ */
+import { addHours, addUnits, floorToUnit, isSameDay, isoWeekNumber, isoWeekYear, quarterOf, toTimestamp, } from "./calendar.js";
+import { clamp, linearScale } from "./scale.js";
+/** Domyślna jednostka górnego poziomu nagłówka dla danego zoomu. */
+const DEFAULT_BAND = {
+    hour: 'day',
+    day: 'week',
+    week: 'month',
+    month: 'quarter',
+    quarter: 'year',
+    year: 'none',
+};
+const DEFAULT_MAX_CELLS = 4000;
+const DEFAULT_WEEKEND = [0, 6];
+function resolveOptions(zoom, opts) {
+    const workHours = opts?.workHours;
+    return {
+        locale: opts?.locale,
+        todayTs: opts?.today !== undefined ? toTimestamp(opts.today) : Date.now(),
+        weekendDays: opts?.weekendDays ?? DEFAULT_WEEKEND,
+        // Okno godzin roboczych ma sens tylko przy kolumnach godzinowych.
+        workHours: zoom === 'hour' && workHours
+            ? {
+                from: workHours.from,
+                to: workHours.to,
+                mode: workHours.mode ?? 'skip',
+                skipWeekends: workHours.skipWeekends ?? true,
+            }
+            : null,
+        bandUnit: opts?.bandUnit ?? DEFAULT_BAND[zoom],
+        positionMode: opts?.positionMode ?? 'uniform',
+        weekPrefix: opts?.weekPrefix ?? 'W',
+        maxCells: opts?.maxCells ?? DEFAULT_MAX_CELLS,
+    };
+}
+function makeFormatters(locale) {
+    return {
+        dayNum: new Intl.DateTimeFormat(locale, { day: 'numeric' }),
+        weekdayShort: new Intl.DateTimeFormat(locale, { weekday: 'short' }),
+        dayMonth: new Intl.DateTimeFormat(locale, { day: '2-digit', month: '2-digit' }),
+        monthLong: new Intl.DateTimeFormat(locale, { month: 'long' }),
+        monthShort: new Intl.DateTimeFormat(locale, { month: 'short' }),
+        dayLong: new Intl.DateTimeFormat(locale, { weekday: 'long', day: 'numeric', month: 'long', year: 'numeric' }),
+        hour: new Intl.DateTimeFormat(locale, { hour: '2-digit', minute: '2-digit', hour12: false }),
+    };
+}
+function isWeekendDay(date, o) {
+    return o.weekendDays.includes(date.getDay());
+}
+/** Czy dana godzina mieści się w oknie roboczym (i poza weekendem, gdy tak ustawiono)? */
+function isWorkingSlot(date, o) {
+    const wh = o.workHours;
+    if (!wh)
+        return true;
+    if (wh.skipWeekends && isWeekendDay(date, o))
+        return false;
+    const hour = date.getHours();
+    return hour >= wh.from && hour < wh.to;
+}
+/**
+ * Kotwica przypisania kolumny do pasma.
+ * Dla tygodnia bierzemy czwartek — tak samo jak ISO wyznacza rok tygodnia,
+ * więc tydzień na przełomie miesiąca trafia do miesiąca swojego czwartku.
+ */
+function bandAnchor(cellStart, zoom) {
+    if (zoom !== 'week')
+        return cellStart;
+    const anchor = new Date(cellStart);
+    anchor.setDate(anchor.getDate() + 3);
+    return anchor;
+}
+/**
+ * Wielka pierwsza litera. `Intl` zwraca nazwy zgodne z ortografią języka — po polsku,
+ * francusku czy czesku miesiące i dni tygodnia pisze się małą literą, po angielsku
+ * i niemiecku wielką. Na osi czasu i w podpowiedziach chcemy jednolitego wyglądu
+ * niezależnie od języka, więc podnosimy wyłącznie pierwszy znak; reszta zostaje bez
+ * zmian, żeby „wtorek, 15 września 2026" nie stało się „Wtorek, 15 Września 2026".
+ */
+function capitalizeFirst(text) {
+    if (!text)
+        return text;
+    const first = text.charAt(0);
+    const upper = first.toLocaleUpperCase();
+    // `toLocaleUpperCase` bywa dłuższe niż źródło (np. niemieckie ß → SS) — wtedy
+    // zostawiamy oryginał, bo zamiana zmieniłaby długość i wygląd etykiety.
+    return upper.length === first.length ? upper + text.slice(1) : text;
+}
+function cellLabels(start, zoom, o, f) {
+    switch (zoom) {
+        case 'hour':
+            return {
+                label: f.hour.format(start),
+                title: capitalizeFirst(`${f.dayLong.format(start)}, ${f.hour.format(start)}`),
+            };
+        case 'day':
+            return {
+                label: f.dayNum.format(start),
+                sublabel: capitalizeFirst(f.weekdayShort.format(start)),
+                title: capitalizeFirst(f.dayLong.format(start)),
+            };
+        case 'week': {
+            // Podpis to prawdziwy zakres dat tygodnia: poniedziałek – niedziela.
+            const sunday = new Date(start);
+            sunday.setDate(sunday.getDate() + 6);
+            const range = `${f.dayMonth.format(start)}–${f.dayMonth.format(sunday)}`;
+            return {
+                label: `${o.weekPrefix}${isoWeekNumber(start)}`,
+                sublabel: range,
+                title: `${o.weekPrefix}${isoWeekNumber(start)} ${isoWeekYear(start)} · ${range}`,
+            };
+        }
+        case 'month':
+            return {
+                label: capitalizeFirst(f.monthShort.format(start)),
+                title: capitalizeFirst(`${f.monthLong.format(start)} ${start.getFullYear()}`),
+            };
+        case 'quarter':
+            return { label: `Q${quarterOf(start)}`, title: `Q${quarterOf(start)} ${start.getFullYear()}` };
+        case 'year':
+            return { label: String(start.getFullYear()), title: String(start.getFullYear()) };
+    }
+}
+function bandLabels(start, unit, f) {
+    switch (unit) {
+        case 'hour':
+            return { label: f.hour.format(start) };
+        case 'day':
+            return { label: capitalizeFirst(f.dayLong.format(start)) };
+        case 'week':
+            return { label: `W${isoWeekNumber(start)}`, sublabel: capitalizeFirst(f.monthLong.format(start)) };
+        case 'month':
+            return { label: capitalizeFirst(f.monthLong.format(start)), sublabel: String(start.getFullYear()) };
+        case 'quarter':
+            return { label: `Q${quarterOf(start)}`, sublabel: String(start.getFullYear()) };
+        case 'year':
+            return { label: String(start.getFullYear()) };
+    }
+}
+/**
+ * Rok kolumny użyty do wykrycia granicy roku.
+ * Przy zoomie tygodniowym musi to być rok tygodnia ISO — inaczej W53/2026
+ * (28.12.2026) dostałaby błędnie znacznik „2027".
+ */
+function yearOfCell(date, zoom) {
+    return zoom === 'week' ? isoWeekYear(date) : date.getFullYear();
+}
+/**
+ * Początek następnej kolumny albo `null`, gdy kursor nie potrafi się już posunąć.
+ * DST wiosną przy zoomie godzinowym: 02:00 nie istnieje, więc `setHours`
+ * normalizuje na 03:00 i zwykły krok mógłby nie wyprzedzić `cursor` — wtedy
+ * przeskakujemy o dwie godziny.
+ */
+function nextBoundary(cursor, zoom) {
+    const next = addUnits(cursor, zoom, 1);
+    if (next.getTime() > cursor.getTime())
+        return next;
+    const jumped = addHours(cursor, 2);
+    return jumped.getTime() > cursor.getTime() ? jumped : null;
+}
+/**
+ * Czy kolumna obejmuje „dziś"? Dla jednostek grubszych niż tydzień akceptujemy
+ * dodatkowo zgodność samej daty — `todayTs` bywa znormalizowane do północy.
+ */
+function isTodayCell(cursor, next, zoom, o, today) {
+    const withinSpan = o.todayTs >= cursor.getTime() && o.todayTs < next.getTime();
+    if (zoom === 'hour' || zoom === 'day' || zoom === 'week')
+        return withinSpan;
+    return withinSpan || isSameDay(cursor, today);
+}
+/** Flagi wyglądu kolumny: tło weekendu/godzin niepracujących i granice okresów. */
+function cellDecorations(cursor, zoom, o) {
+    const isDayGrid = zoom === 'day' || zoom === 'hour';
+    return {
+        isWeekend: isDayGrid && isWeekendDay(cursor, o),
+        isNonWorking: o.workHours?.mode === 'dim' && !isWorkingSlot(cursor, o),
+        isMonthBoundary: isDayGrid && cursor.getDate() === 1,
+        isQuarterBoundary: (zoom === 'month' || zoom === 'quarter') && cursor.getMonth() % 3 === 0,
+    };
+}
+function buildCells(range, zoom, o, f) {
+    const cells = [];
+    const today = new Date(o.todayTs);
+    // Startujemy od granicy jednostki — inaczej pierwsza kolumna byłaby ucięta.
+    let cursor = floorToUnit(new Date(range.start), zoom);
+    let pendingGap = false;
+    let previousYear = null;
+    let guard = 0;
+    while (cursor.getTime() < range.end && guard++ < o.maxCells) {
+        const next = nextBoundary(cursor, zoom);
+        if (next === null)
+            break;
+        if (o.workHours?.mode === 'skip' && !isWorkingSlot(cursor, o)) {
+            pendingGap = true;
+            cursor = next;
+            continue;
+        }
+        const year = yearOfCell(cursor, zoom);
+        const labels = cellLabels(cursor, zoom, o, f);
+        cells.push({
+            index: cells.length,
+            key: String(cursor.getTime()),
+            start: cursor.getTime(),
+            end: next.getTime(),
+            label: labels.label,
+            sublabel: labels.sublabel,
+            title: labels.title,
+            ratioStart: 0,
+            ratioEnd: 0,
+            isToday: isTodayCell(cursor, next, zoom, o, today),
+            ...cellDecorations(cursor, zoom, o),
+            isYearBoundary: previousYear !== null && year !== previousYear,
+            hasGapBefore: pendingGap,
+        });
+        pendingGap = false;
+        previousYear = year;
+        cursor = next;
+    }
+    return cells;
+}
+function applyRatios(cells, mode, range) {
+    const count = cells.length;
+    if (count === 0)
+        return;
+    if (mode === 'uniform') {
+        const step = 1 / count;
+        for (const cell of cells) {
+            cell.ratioStart = cell.index * step;
+            cell.ratioEnd = (cell.index + 1) * step;
+        }
+        return;
+    }
+    const scale = linearScale(range.start, range.end, 0, 1);
+    for (const cell of cells) {
+        cell.ratioStart = clamp(scale(cell.start), 0, 1);
+        cell.ratioEnd = clamp(scale(cell.end), 0, 1);
+    }
+}
+/** Indeks kolumny zawierającej `ts`, albo pierwszej kolumny po `ts`. */
+function findCell(cells, ts) {
+    let lo = 0;
+    let hi = cells.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (ts >= cells[mid].end)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+function buildBands(cells, zoom, o, f) {
+    const unit = o.bandUnit;
+    if (unit === 'none' || cells.length === 0)
+        return [];
+    const bands = [];
+    let seenYear = null;
+    for (const cell of cells) {
+        const anchor = bandAnchor(new Date(cell.start), zoom);
+        const bandStart = floorToUnit(anchor, unit);
+        const key = String(bandStart.getTime());
+        const last = bands.at(-1);
+        if (last?.key === key) {
+            last.toIndex = cell.index;
+            last.span += 1;
+            last.ratioEnd = cell.ratioEnd;
+            last.end = cell.end;
+            continue;
+        }
+        const labels = bandLabels(bandStart, unit, f);
+        const year = unit === 'week' ? isoWeekYear(bandStart) : bandStart.getFullYear();
+        const isYearStart = seenYear === null ? bands.length === 0 : year !== seenYear;
+        seenYear = year;
+        bands.push({
+            key,
+            start: cell.start,
+            end: cell.end,
+            fromIndex: cell.index,
+            toIndex: cell.index,
+            span: 1,
+            ratioStart: cell.ratioStart,
+            ratioEnd: cell.ratioEnd,
+            label: labels.label,
+            sublabel: labels.sublabel,
+            isYearStart,
+            // Znacznik roku niesie tylko pierwsze pasmo danego roku.
+            yearBadge: isYearStart ? String(year) : undefined,
+        });
+    }
+    return bands;
+}
+/**
+ * Buduje model osi czasu: kolumny, pasma nagłówka i skalę.
+ * Wszystkie obliczenia w czasie LOKALNYM przeglądarki.
+ *
+ * @param range zakres osi w ms — zwykle wynik `resolveRange`
+ * @param zoom  poziom przybliżenia
+ * @param opts  locale, „dziś", weekendy, godziny robocze, tryb pozycjonowania
+ */
+export function buildTimeline(range, zoom, opts) {
+    const o = resolveOptions(zoom, opts);
+    const f = makeFormatters(o.locale);
+    const cells = buildCells(range, zoom, o, f);
+    applyRatios(cells, o.positionMode, range);
+    const bands = buildBands(cells, zoom, o, f);
+    const count = cells.length;
+    const first = cells[0];
+    const last = cells[count - 1];
+    /** Czas → 0..1. Skala odcinkowa: indeks kolumny + interpolacja w jej wnętrzu. */
+    const toRatio = (ts) => {
+        if (count === 0)
+            return 0;
+        if (o.positionMode === 'linear') {
+            return clamp(linearScale(range.start, range.end, 0, 1)(ts), 0, 1);
+        }
+        if (ts <= first.start)
+            return 0;
+        if (ts >= last.end)
+            return 1;
+        const index = findCell(cells, ts);
+        const cell = cells[index];
+        // `ts` może wpaść w lukę wyciętą przez `workHours: 'skip'` — wtedy
+        // interpolacja wychodzi poza [0, 1] i clamp dociąga ją do krawędzi kolumny.
+        const inner = clamp(linearScale(cell.start, cell.end, 0, 1)(ts), 0, 1);
+        return (index + inner) / count;
+    };
+    const fromRatio = (ratio) => {
+        if (count === 0)
+            return range.start;
+        if (o.positionMode === 'linear') {
+            return range.start + clamp(ratio, 0, 1) * (range.end - range.start);
+        }
+        const scaled = clamp(ratio, 0, 1) * count;
+        const index = Math.min(count - 1, Math.floor(scaled));
+        const cell = cells[index];
+        // Poprawnie odwzorowuje także dobę 25-godzinną — długość bierzemy z kolumny.
+        return cell.start + (scaled - index) * (cell.end - cell.start);
+    };
+    const span = (startTs, endTs) => {
+        const lo = Math.min(startTs, endTs);
+        const hi = Math.max(startTs, endTs);
+        const axisStart = count > 0 ? first.start : range.start;
+        const axisEnd = count > 0 ? last.end : range.end;
+        const left = toRatio(lo);
+        const right = toRatio(hi);
+        return {
+            left,
+            width: Math.max(0, right - left),
+            clippedStart: lo < axisStart,
+            clippedEnd: hi > axisEnd,
+            // Kamień milowy ma zerową szerokość, więc sam dotyk krawędzi wystarczy.
+            visible: hi >= axisStart && lo <= axisEnd,
+        };
+    };
+    const todayInRange = count > 0 && o.todayTs >= first.start && o.todayTs <= last.end;
+    return {
+        zoom,
+        range,
+        positionMode: o.positionMode,
+        cells,
+        bands,
+        hasBands: bands.length > 0,
+        todayRatio: todayInRange ? toRatio(o.todayTs) : null,
+        toRatio,
+        fromRatio,
+        span,
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,222 @@
+/** Akceptowane formy daty na wejściu; rdzeń normalizuje je do epoch ms (czas LOKALNY). */
+export type KptDateInput = Date | number | string;
+/** Poziom przybliżenia osi czasu. */
+export type KptRoadmapZoom = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour';
+/** Warianty kolorystyczne spójne z resztą biblioteki. */
+export type KptRoadmapVariant = 'neutral' | 'primary' | 'success' | 'danger' | 'warning' | 'info';
+/** Zamknięty przedział czasu w epoch ms. */
+export interface KptTimeRange {
+    /** Początek włącznie (ms). */
+    start: number;
+    /** Koniec wyłącznie (ms). */
+    end: number;
+}
+/** Punkt w układzie px overlaya SVG. */
+export interface KptRoadmapPoint {
+    x: number;
+    y: number;
+}
+/** Prostokąt w px overlaya SVG. */
+export interface KptRoadmapRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Typ zależności wg konwencji zarządzania projektami. */
+export type KptRoadmapLinkType = 'FS' | 'SS' | 'FF' | 'SF';
+/** Krawędź grafu zależności między dwoma itemami. */
+export interface KptRoadmapLink<TMeta = unknown> {
+    /** Stabilny klucz (trackBy); generowany z `from`/`to`/`type`, gdy brak. */
+    id?: string;
+    /** `id` itemu-poprzednika. */
+    from: string;
+    /** `id` itemu-następnika. */
+    to: string;
+    /** Domyślnie 'FS' (finish-to-start). */
+    type?: KptRoadmapLinkType;
+    /** Wyprzedzenie/opóźnienie w ms (ujemne = lead). Domyślnie 0. */
+    lag?: number;
+    variant?: KptRoadmapVariant;
+    color?: string;
+    meta?: TMeta;
+}
+/** Ograniczenia edycyjne — zarezerwowane pod drag&drop (v1 ich nie czyta). */
+export interface KptRoadmapConstraints {
+    /** Item nie może zacząć się wcześniej niż tu. */
+    minStart?: KptDateInput;
+    /** Item nie może skończyć się później niż tu. */
+    maxEnd?: KptDateInput;
+    /** Minimalny czas trwania w ms. */
+    minDurationMs?: number;
+    /** Przyciąganie do jednostki podczas przeciągania. */
+    snap?: KptRoadmapZoom | 'none';
+}
+/** Pojedynczy pasek / kamień milowy roadmapy. */
+export interface KptRoadmapItem<TMeta = unknown> {
+    /** Unikalny identyfikator (klucz trackBy i cel zależności). */
+    id: string;
+    /** Etykieta główna (kolumna sticky + wnętrze paska). */
+    label: string;
+    /** Etykieta pomocnicza (druga linia w kolumnie sticky). */
+    sublabel?: string;
+    /** Początek (czas lokalny). */
+    start: KptDateInput;
+    /** Koniec wyłącznie. Brak ⇒ kamień milowy (`end = start`). */
+    end?: KptDateInput;
+    /** Wymusza render jako romb, nawet gdy `end` podane. */
+    milestone?: boolean;
+    variant?: KptRoadmapVariant;
+    /** Dowolny kolor CSS — nadpisuje `variant`. */
+    color?: string;
+    /** Postęp 0..1; render jako wypełnienie wewnątrz paska. */
+    progress?: number;
+    /** Przynależność do grupy/swimlane. Brak ⇒ wiersz na poziomie 0. */
+    groupId?: string;
+    /** Zależności skrótowo: `string` = FS bez lagu. Scalane z `config.links`. */
+    dependsOn?: readonly (string | KptRoadmapLink)[];
+    /** Nazwa ikony (KptIconName) renderowana przed etykietą. */
+    icon?: string;
+    disabled?: boolean;
+    draggable?: boolean;
+    resizable?: boolean;
+    locked?: boolean;
+    constraints?: KptRoadmapConstraints;
+    /** Dane aplikacyjne przekazywane do szablonów i zdarzeń. */
+    meta?: TMeta;
+}
+/** Znormalizowany item — daty jako ms, wyliczone flagi. Wynik rdzenia. */
+export interface KptRoadmapNormalizedItem<TMeta = unknown> {
+    readonly source: KptRoadmapItem<TMeta>;
+    readonly id: string;
+    readonly start: number;
+    readonly end: number;
+    readonly isMilestone: boolean;
+    readonly durationMs: number;
+}
+/** Sposób wyliczania paska zbiorczego grupy. */
+export type KptRoadmapSummaryMode = 'auto' | 'none';
+/** Grupa / swimlane. Może być zagnieżdżona przez `parentId`. */
+export interface KptRoadmapGroup<TMeta = unknown> {
+    id: string;
+    label: string;
+    sublabel?: string;
+    /** Grupa nadrzędna — API gotowe na drzewo; `depth` steruje wcięciem. */
+    parentId?: string;
+    /** Stan początkowy zwinięcia (dalej sterowany sygnałem komponentu). */
+    collapsed?: boolean;
+    variant?: KptRoadmapVariant;
+    color?: string;
+    /** 'auto' (domyślnie) = pasek od min(start) do max(end) potomków. */
+    summary?: KptRoadmapSummaryMode;
+    meta?: TMeta;
+}
+/** Okno godzin roboczych dla zoomu 'hour'. */
+export interface KptWorkHours {
+    /** Pierwsza godzina robocza włącznie, 0..23 (domyślnie 8). */
+    from: number;
+    /** Ostatnia godzina wyłącznie, 1..24 (domyślnie 18). */
+    to: number;
+    /**
+     * 'skip' — godziny poza oknem nie mają kolumn (oś się skraca) [domyślne],
+     * 'dim'  — kolumny istnieją, dostają flagę `isNonWorking`.
+     */
+    mode?: 'skip' | 'dim';
+    /** Czy pomijać także całe dni weekendowe (domyślnie true przy mode='skip'). */
+    skipWeekends?: boolean;
+}
+/**
+ * Sposób odwzorowania czasu na pozycję.
+ * 'uniform' — każda kolumna ma równą szerokość, wewnątrz interpolacja liniowa po ms.
+ *             Doba po zmianie czasu (23/25 h) i luty nie są węższe od sąsiadów.
+ * 'linear'  — czysto liniowo (start..end → 0..1); kolumny wtedy nierówne.
+ */
+export type KptRoadmapPositionMode = 'uniform' | 'linear';
+export interface KptTimelineOptions {
+    /** BCP-47 dla `Intl`. Domyślnie locale z KptI18n. */
+    locale?: string;
+    /** „Dziś" — wstrzykiwalne dla testów i SSR. Domyślnie `new Date()`. */
+    today?: KptDateInput;
+    /** Dni weekendu wg `Date#getDay()`. Domyślnie `[0, 6]`. */
+    weekendDays?: readonly number[];
+    /** Godziny robocze — tylko przy `zoom: 'hour'`. */
+    workHours?: KptWorkHours;
+    /** Jednostka górnego poziomu nagłówka. Brak ⇒ domyślna dla zoomu. */
+    bandUnit?: KptRoadmapZoom | 'none';
+    /**
+     * Prefiks numeru tygodnia (domyślnie 'W').
+     * Rdzeń nie zna warstwy i18n — komponent podaje tu wartość z KptI18n.
+     */
+    weekPrefix?: string;
+    /** Domyślnie 'uniform'. */
+    positionMode?: KptRoadmapPositionMode;
+    /** Bezpiecznik przed eksplozją liczby kolumn. Domyślnie 4000. */
+    maxCells?: number;
+}
+export type KptRoadmapRowMode = 'row-per-item' | 'pack';
+export interface KptRoadmapRowOptions {
+    /** 'row-per-item' (domyślnie) lub 'pack' (kilka itemów w jednym wierszu). */
+    mode?: KptRoadmapRowMode;
+    /** Wysokość wiersza itemu w px. Domyślnie 44. */
+    itemHeight?: number;
+    /** Wysokość wiersza nagłówka grupy w px. Domyślnie 38. */
+    groupHeight?: number;
+    /** Wysokość jednego pasa w trybie 'pack'. Domyślnie 28. */
+    laneHeight?: number;
+    /** Minimalny odstęp między itemami w tym samym pasie (ms). Domyślnie 0. */
+    packMinGapMs?: number;
+    /** Czy pokazywać wiersz nagłówka dla itemów bez `groupId`. Domyślnie false. */
+    showUngroupedHeader?: boolean;
+    /** Etykieta pseudo-grupy dla itemów bez `groupId`. */
+    ungroupedLabel?: string;
+}
+export interface KptRoadmapDependencyOptions {
+    /** Czy rysować overlay zależności. Domyślnie true. */
+    enabled?: boolean;
+    /** Długość wąsa wychodzącego z paska w px. Domyślnie 12. */
+    stub?: number;
+    /** Promień zaokrąglenia narożników łamanej w px. Domyślnie 6. */
+    cornerRadius?: number;
+    /** Rozmiar grotu strzałki w px. Domyślnie 6. */
+    arrowSize?: number;
+    /** Podświetlać zależności naruszone (następnik startuje za wcześnie). Domyślnie true. */
+    highlightViolations?: boolean;
+}
+/** Zarezerwowane pod v2 (drag&drop, resize, inline edit). W v1 ignorowane. */
+export interface KptRoadmapInteractionOptions {
+    selectable?: boolean;
+    draggable?: boolean;
+    resizable?: boolean;
+    linkable?: boolean;
+    snap?: KptRoadmapZoom | 'none';
+}
+/** Pełna konfiguracja roadmapy — jeden obiekt wejściowy komponentu. */
+export interface KptRoadmapConfig<TItem = unknown, TGroup = unknown> {
+    items: readonly KptRoadmapItem<TItem>[];
+    groups?: readonly KptRoadmapGroup<TGroup>[];
+    /** Zależności podane grafowo (alternatywa/uzupełnienie `item.dependsOn`). */
+    links?: readonly KptRoadmapLink[];
+    /** Domyślnie 'week'. */
+    zoom?: KptRoadmapZoom;
+    /** Zakres osi. Częściowy ⇒ brakujący kraniec z `autoRange`. Brak ⇒ cały `autoRange`. */
+    range?: Partial<KptTimeRange>;
+    locale?: string;
+    today?: KptDateInput;
+    timeline?: KptTimelineOptions;
+    rows?: KptRoadmapRowOptions;
+    dependencies?: KptRoadmapDependencyOptions;
+    interaction?: KptRoadmapInteractionOptions;
+}
+/** Rodzaj zmiany zgłaszanej przez interakcję (zdefiniowany w v1, emitowany od v2). */
+export type KptRoadmapChangeKind = 'move' | 'resize-start' | 'resize-end' | 'link-add' | 'link-remove';
+/** Ładunek zdarzenia edycji — stabilny kontrakt na przyszłość. */
+export interface KptRoadmapChange<TMeta = unknown> {
+    kind: KptRoadmapChangeKind;
+    item: KptRoadmapItem<TMeta>;
+    /** Poprzednie wartości (ms). */
+    previous: KptTimeRange;
+    /** Nowe wartości (ms). */
+    next: KptTimeRange;
+    /** Dla 'link-add' / 'link-remove'. */
+    link?: KptRoadmapLink;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/*
+ * Rdzeń roadmapy — czyste typy TypeScript (bez DOM i bez frameworka).
+ * Współdzielone przez warstwę Angular (Faza 1) i React (Faza 2).
+ *
+ * Kontrakt: wejście jest READONLY — rdzeń nigdy nie mutuje obiektów użytkownika.
+ * Edycja (drag&drop) odbywa się przez zdarzenia, nie przez mutację danych.
+ */
+export {};