@konce-pt/datetime 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,66 @@
+<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/datetime
+
+Rdzeń kalendarza i zegara dla kontrolek daty [Koncept UI](https://gitlab.com/konce-pt/koncept-ui).
+Czysty TypeScript, **zero zależności runtime**, bez wiązania z frameworkiem — siatki dni, miesięcy,
+lat i dekad, pasma zakresów oraz znaczniki tarczy zegara.
+
+Zwykle nie instalujesz go samodzielnie: `@konce-pt/react` używa go pod `KptDatepicker`,
+`KptDateRange` i `KptClock`. Sięgnij po niego wprost, gdy budujesz własną kontrolkę daty
+na tym samym zachowaniu.
+
+```bash
+npm i @konce-pt/datetime
+```
+
+```ts
+import { buildDayGrid, pickRangeDay, formatDate } from '@konce-pt/datetime';
+
+// Sześć pełnych tygodni od poniedziałku — panel nie zmienia wysokości przy przewijaniu.
+const weeks = buildDayGrid({
+  page: { y: 2026, m: 8 },
+  selectedIso: '2026-09-10',
+  todayIso: '2026-09-06',
+  minDate: '2026-09-01',
+});
+
+// Protokół klikania zakresu: start → koniec → od nowa, z normalizacją kolejności.
+pickRangeDay({ start: '2026-09-10', end: '' }, '2026-09-05');
+// { start: '2026-09-05', end: '2026-09-10' }
+
+formatDate('2026-09-06', 'pl'); // '06.09.2026'
+```
+
+## Wartości to stringi, nie `Date`
+
+Każdy format jest tekstowy: `'RRRR-MM-DD'`, `'RRRR-MM'`, `'RRRR'`, `'MM'`, `'RRRR-MM-DDTHH:mm'`,
+`'HH:mm'`. To one trafiają do formularza i na serwer, i nie niosą strefy, którą kalendarz mógłby
+zgubić. `Date` służy wyłącznie do arytmetyki lokalnej — `toIso()` czyta datę lokalną, bo
+`toISOString()` przesunąłby dzień o offset strefy.
+
+## API
+
+- **Daty i godziny** — `pad`, `toIso`, `parseDate`, `parseTime`, `parseDateTime`, `datePart`,
+  `timePart`, `formatDate`, `formatTime`, `from12h`
+- **Stos widoków** — `KPT_CALENDAR_LEVELS`, `commitLevelFor`, `topLevelFor`, `resolveStartView`,
+  `initialPage`, `pageBy`, `canPageBack`, `canPageForward`, `buildDayGrid`, `buildMonthCells`,
+  `buildYearCells`, `buildDecadeCells`, `selectedYearMonth`, `isYearDisabled`,
+  `isMonthYearDisabled`, `decadeStart`, `centuryStart`
+- **Zakresy** — `buildRangeGrid`, `pickRangeDay`, `clampVisibleMonths`
+- **Tarcza zegara** — `hourMarks`, `minuteMarks`, `hourFromAngle`, `minuteFromAngle`, `handAngle`,
+  `handIsInner`, `markPosition`
+
+Pełny opis: [`llms.txt`](./llms.txt) (EN) i [`llms-pl.txt`](./llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/datetime exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/calendar.d.ts

@@ -0,0 +1,97 @@
+/** Granulacja wyboru w kontrolce daty. */
+export type KptDateSelectionMode = 'date' | 'monthYear' | 'year' | 'month' | 'datetime' | 'time';
+/** Poziom panelu: dni → miesiące → lata → dekady. */
+export type KptCalendarView = 'day' | 'month' | 'year' | 'decade';
+/** Kolejność poziomów panelu, od najdrobniejszego. Indeks = „wysokość" widoku. */
+export declare const KPT_CALENDAR_LEVELS: readonly ["day", "month", "year", "decade"];
+/** Widoczna strona kalendarza: rok + miesiąc (0–11). */
+export interface KptCalendarPage {
+    y: number;
+    m: number;
+}
+export interface KptDayCell {
+    day: number;
+    iso: string;
+    inMonth: boolean;
+    today: boolean;
+    selected: boolean;
+    disabled: boolean;
+}
+/** Komórka siatki miesięcy/lat/dekad — niesie cel nawigacji (rok + ewentualny miesiąc). */
+export interface KptGridCell {
+    label: string;
+    y: number;
+    m: number;
+    selected: boolean;
+    /** Zawiera dzisiejszą datę — obrys jak „dziś" w siatce dni. */
+    current: boolean;
+    disabled: boolean;
+}
+/** Poziom, na którym klik w komórkę zatwierdza wartość zamiast schodzić niżej. */
+export declare function commitLevelFor(mode: KptDateSelectionMode): KptCalendarView;
+/** Tryb 'month' nie ma roku ani dekady — wartością jest samo 'MM'. */
+export declare function topLevelFor(mode: KptDateSelectionMode): KptCalendarView;
+/**
+ * Poziom startowy panelu, przycięty do zakresu trybu: nigdy poniżej poziomu zatwierdzania
+ * (`startView="day"` w trybie 'year' nie ma sensu) i nigdy powyżej szczytu stosu.
+ */
+export declare function resolveStartView(mode: KptDateSelectionMode, wanted: KptCalendarView | null): KptCalendarView;
+/** Początek dekady widocznej w siatce lat (1979 → 1970). */
+export declare function decadeStart(year: number): number;
+/** Początek strony dekad: 12 dekad, czyli 120 lat (1979 → 1920, strona 1920–2039). */
+export declare function centuryStart(year: number): number;
+/** Strzałki ‹ › — krok zależny od poziomu: miesiąc, rok, dekada, strona dekad. */
+export declare function pageBy(page: KptCalendarPage, level: KptCalendarView, dir: 1 | -1): KptCalendarPage;
+/** Strzałka wstecz gaśnie, gdy cała poprzednia strona wypada przed `minDate`. */
+export declare function canPageBack(page: KptCalendarPage, level: KptCalendarView, minDate: string | null): boolean;
+/** Strzałka w przód gaśnie, gdy cała następna strona wypada za `maxDate`. */
+export declare function canPageForward(page: KptCalendarPage, level: KptCalendarView, maxDate: string | null): boolean;
+export declare function isYearDisabled(year: number, minDate: string | null, maxDate: string | null): boolean;
+export declare function isMonthYearDisabled(year: number, monthIndex: number, minDate: string | null, maxDate: string | null): boolean;
+export interface DayGridOptions {
+    page: KptCalendarPage;
+    selectedIso: string;
+    todayIso: string;
+    minDate?: string | null;
+    maxDate?: string | null;
+}
+/**
+ * Siatka dni — zawsze sześć pełnych tygodni od poniedziałku, także gdy część wypada poza miesiąc.
+ * Stała liczba wierszy trzyma wysokość panelu, więc przewijanie miesięcy nie skacze.
+ */
+export declare function buildDayGrid({ page, selectedIso, todayIso, minDate, maxDate, }: DayGridOptions): KptDayCell[][];
+/** Rok i miesiąc bieżącej wartości — zaznaczenie w siatkach wyższych poziomów. */
+export declare function selectedYearMonth(value: string, mode: KptDateSelectionMode): {
+    y: number | null;
+    m: number | null;
+};
+export interface MonthCellsOptions {
+    year: number;
+    monthNames: string[];
+    selected: {
+        y: number | null;
+        m: number | null;
+    };
+    today: Date;
+    monthOnly?: boolean;
+    numeric?: boolean;
+    minDate?: string | null;
+    maxDate?: string | null;
+}
+export declare function buildMonthCells({ year, monthNames, selected, today, monthOnly, numeric, minDate, maxDate, }: MonthCellsOptions): KptGridCell[];
+export interface YearCellsOptions {
+    year: number;
+    selected: {
+        y: number | null;
+        m: number | null;
+    };
+    today: Date;
+    minDate?: string | null;
+    maxDate?: string | null;
+}
+/** Strona lat to pełna dekada: 10 komórek, 1970–1979. */
+export declare function buildYearCells({ year, selected, today, minDate, maxDate, }: YearCellsOptions): KptGridCell[];
+/** Strona dekad to 12 dekad, czyli 120 lat. */
+export declare function buildDecadeCells({ year, selected, today, minDate, maxDate, }: YearCellsOptions): KptGridCell[];
+/** Strona kalendarza, od której otwiera się panel dla danej wartości i trybu. */
+export declare function initialPage(value: string, mode: KptDateSelectionMode, today: Date): KptCalendarPage;

package/dist/calendar.js

@@ -0,0 +1,223 @@
+import { pad, parseDate, toIso } from "./iso.js";
+/** Kolejność poziomów panelu, od najdrobniejszego. Indeks = „wysokość" widoku. */
+export const KPT_CALENDAR_LEVELS = ['day', 'month', 'year', 'decade'];
+/** Poziom, na którym klik w komórkę zatwierdza wartość zamiast schodzić niżej. */
+export function commitLevelFor(mode) {
+    switch (mode) {
+        case 'monthYear':
+        case 'month':
+            return 'month';
+        case 'year':
+            return 'year';
+        default:
+            return 'day';
+    }
+}
+/** Tryb 'month' nie ma roku ani dekady — wartością jest samo 'MM'. */
+export function topLevelFor(mode) {
+    return mode === 'month' ? 'month' : 'decade';
+}
+/**
+ * Poziom startowy panelu, przycięty do zakresu trybu: nigdy poniżej poziomu zatwierdzania
+ * (`startView="day"` w trybie 'year' nie ma sensu) i nigdy powyżej szczytu stosu.
+ */
+export function resolveStartView(mode, wanted) {
+    const commit = KPT_CALENDAR_LEVELS.indexOf(commitLevelFor(mode));
+    const top = KPT_CALENDAR_LEVELS.indexOf(topLevelFor(mode));
+    const index = wanted ? KPT_CALENDAR_LEVELS.indexOf(wanted) : commit;
+    return KPT_CALENDAR_LEVELS[Math.min(Math.max(index, commit), top)];
+}
+/** Początek dekady widocznej w siatce lat (1979 → 1970). */
+export function decadeStart(year) {
+    return Math.floor(year / 10) * 10;
+}
+/** Początek strony dekad: 12 dekad, czyli 120 lat (1979 → 1920, strona 1920–2039). */
+export function centuryStart(year) {
+    return Math.floor(year / 120) * 120;
+}
+/** Strzałki ‹ › — krok zależny od poziomu: miesiąc, rok, dekada, strona dekad. */
+export function pageBy(page, level, dir) {
+    const { y, m } = page;
+    switch (level) {
+        case 'month':
+            return { y: y + dir, m };
+        case 'year':
+            return { y: y + dir * 10, m };
+        case 'decade':
+            return { y: y + dir * 120, m };
+        default: {
+            const next = m + dir;
+            if (next < 0)
+                return { y: y - 1, m: 11 };
+            if (next > 11)
+                return { y: y + 1, m: 0 };
+            return { y, m: next };
+        }
+    }
+}
+/** Strzałka wstecz gaśnie, gdy cała poprzednia strona wypada przed `minDate`. */
+export function canPageBack(page, level, minDate) {
+    if (!minDate)
+        return true;
+    const { y, m } = page;
+    switch (level) {
+        case 'month':
+            return `${y - 1}-12` >= minDate.slice(0, 7);
+        case 'year':
+            return decadeStart(y) - 1 >= +minDate.slice(0, 4);
+        case 'decade':
+            return centuryStart(y) - 1 >= +minDate.slice(0, 4);
+        default:
+            // Ostatni dzień poprzedniego miesiąca.
+            return toIso(new Date(y, m, 0)) >= minDate;
+    }
+}
+/** Strzałka w przód gaśnie, gdy cała następna strona wypada za `maxDate`. */
+export function canPageForward(page, level, maxDate) {
+    if (!maxDate)
+        return true;
+    const { y, m } = page;
+    switch (level) {
+        case 'month':
+            return `${y + 1}-01` <= maxDate.slice(0, 7);
+        case 'year':
+            return decadeStart(y) + 10 <= +maxDate.slice(0, 4);
+        case 'decade':
+            return centuryStart(y) + 120 <= +maxDate.slice(0, 4);
+        default:
+            return toIso(new Date(y, m + 1, 1)) <= maxDate;
+    }
+}
+export function isYearDisabled(year, minDate, maxDate) {
+    if (minDate && year < +minDate.slice(0, 4))
+        return true;
+    if (maxDate && year > +maxDate.slice(0, 4))
+        return true;
+    return false;
+}
+export function isMonthYearDisabled(year, monthIndex, minDate, maxDate) {
+    const ym = `${year}-${pad(monthIndex + 1)}`;
+    if (minDate && ym < minDate.slice(0, 7))
+        return true;
+    if (maxDate && ym > maxDate.slice(0, 7))
+        return true;
+    return false;
+}
+/**
+ * Siatka dni — zawsze sześć pełnych tygodni od poniedziałku, także gdy część wypada poza miesiąc.
+ * Stała liczba wierszy trzyma wysokość panelu, więc przewijanie miesięcy nie skacze.
+ */
+export function buildDayGrid({ page, selectedIso, todayIso, minDate = null, maxDate = null, }) {
+    const { y, m } = page;
+    const first = new Date(y, m, 1);
+    const startOffset = (first.getDay() + 6) % 7; // poniedziałek = 0
+    const gridStart = new Date(y, m, 1 - startOffset);
+    const weeks = [];
+    for (let w = 0; w < 6; w++) {
+        const row = [];
+        for (let d = 0; d < 7; d++) {
+            const date = new Date(gridStart.getFullYear(), gridStart.getMonth(), gridStart.getDate() + w * 7 + d);
+            const iso = toIso(date);
+            row.push({
+                day: date.getDate(),
+                iso,
+                inMonth: date.getMonth() === m,
+                today: iso === todayIso,
+                selected: iso === selectedIso,
+                disabled: (minDate != null && iso < minDate) || (maxDate != null && iso > maxDate),
+            });
+        }
+        weeks.push(row);
+    }
+    return weeks;
+}
+/** Rok i miesiąc bieżącej wartości — zaznaczenie w siatkach wyższych poziomów. */
+export function selectedYearMonth(value, mode) {
+    switch (mode) {
+        case 'month': {
+            const match = /^(\d{2})$/.exec(value);
+            return { y: null, m: match ? +match[1] - 1 : null };
+        }
+        case 'year':
+            return { y: /^\d{4}$/.test(value) ? +value : null, m: null };
+        case 'monthYear': {
+            const match = /^(\d{4})-(\d{2})$/.exec(value);
+            return match ? { y: +match[1], m: +match[2] - 1 } : { y: null, m: null };
+        }
+        case 'time':
+            return { y: null, m: null };
+        default: {
+            const date = parseDate(value);
+            return date ? { y: date.getFullYear(), m: date.getMonth() } : { y: null, m: null };
+        }
+    }
+}
+export function buildMonthCells({ year, monthNames, selected, today, monthOnly = false, numeric = false, minDate = null, maxDate = null, }) {
+    const todayY = today.getFullYear();
+    const todayM = today.getMonth();
+    return monthNames.map((name, i) => ({
+        label: numeric ? pad(i + 1) : name,
+        y: year,
+        m: i,
+        // W trybie 'month' rok nie istnieje, więc zaznaczenie i „dziś" nie mogą go brać pod uwagę.
+        selected: selected.m === i && (monthOnly || selected.y === year),
+        current: todayM === i && (monthOnly || todayY === year),
+        disabled: monthOnly ? false : isMonthYearDisabled(year, i, minDate, maxDate),
+    }));
+}
+/** Strona lat to pełna dekada: 10 komórek, 1970–1979. */
+export function buildYearCells({ year, selected, today, minDate = null, maxDate = null, }) {
+    const start = decadeStart(year);
+    const todayY = today.getFullYear();
+    return Array.from({ length: 10 }, (_, i) => {
+        const cellYear = start + i;
+        return {
+            label: String(cellYear),
+            y: cellYear,
+            m: 0,
+            selected: selected.y === cellYear,
+            current: todayY === cellYear,
+            disabled: isYearDisabled(cellYear, minDate, maxDate),
+        };
+    });
+}
+/** Strona dekad to 12 dekad, czyli 120 lat. */
+export function buildDecadeCells({ year, selected, today, minDate = null, maxDate = null, }) {
+    const start = centuryStart(year);
+    const todayY = today.getFullYear();
+    return Array.from({ length: 12 }, (_, i) => {
+        const from = start + i * 10;
+        const to = from + 9;
+        return {
+            label: `${from} – ${to}`,
+            y: from,
+            m: 0,
+            selected: selected.y != null && selected.y >= from && selected.y <= to,
+            current: todayY >= from && todayY <= to,
+            // Dekada wypada z zakresu dopiero, gdy poza nim są oba jej krańce.
+            disabled: isYearDisabled(from, minDate, maxDate) && isYearDisabled(to, minDate, maxDate),
+        };
+    });
+}
+/** Strona kalendarza, od której otwiera się panel dla danej wartości i trybu. */
+export function initialPage(value, mode, today) {
+    const fallback = { y: today.getFullYear(), m: today.getMonth() };
+    switch (mode) {
+        case 'monthYear': {
+            const match = /^(\d{4})-(\d{2})$/.exec(value);
+            return match ? { y: +match[1], m: +match[2] - 1 } : fallback;
+        }
+        case 'year':
+            return { y: /^\d{4}$/.test(value) ? +value : today.getFullYear(), m: 0 };
+        case 'month':
+            return { y: today.getFullYear(), m: 0 };
+        case 'datetime': {
+            const date = parseDate(value.slice(0, 10));
+            return date ? { y: date.getFullYear(), m: date.getMonth() } : fallback;
+        }
+        default: {
+            const date = parseDate(value) ?? today;
+            return { y: date.getFullYear(), m: date.getMonth() };
+        }
+    }
+}

package/dist/clock.d.ts

@@ -0,0 +1,35 @@
+export interface KptClockMark {
+    label: string;
+    /** Wartość docelowa: godzina 24h dla tarczy godzin, minuta dla tarczy minut. */
+    value: number;
+    /** Pozycja w procentach tarczy (0–100). */
+    x: number;
+    y: number;
+    inner: boolean;
+    selected: boolean;
+}
+export declare const KPT_CLOCK_R_OUTER = 40;
+export declare const KPT_CLOCK_R_INNER = 26;
+/** Pozycja znacznika (% tarczy) na pierścieniu o promieniu `radius`: 12 na górze, zegarowo. */
+export declare function markPosition(index: number, radius: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Znaczniki godzin. W 12h jeden pierścień pokazujący wybraną połowę doby; w 24h zewnętrzny
+ * (12, 1–11) i wewnętrzny (00, 13–23), bo 24 liczby na jednym okręgu byłyby nieczytelne.
+ */
+export declare function hourMarks(hour: number, hourFormat: 12 | 24): KptClockMark[];
+/** Znaczniki minut co pięć — pozostałe wartości wchodzą przeciąganiem. */
+export declare function minuteMarks(minute: number): KptClockMark[];
+/**
+ * Godzina z kąta wskaźnika. W 24h o pierścieniu — a więc o 12–23 kontra 0–11 — decyduje promień
+ * kliknięcia, podany jako ułamek promienia tarczy.
+ */
+export declare function hourFromAngle(deg: number, radiusRatio: number, hourFormat: 12 | 24, hour: number): number;
+/** Minuta z kąta wskaźnika, dociągnięta do `minuteStep`. */
+export declare function minuteFromAngle(deg: number, minuteStep: number): number;
+/** Kąt wskaźnika w stopniach dla bieżącego etapu tarczy. */
+export declare function handAngle(hour: number, minute: number, phase: 'hours' | 'minutes'): number;
+/** Czy wskaźnik sięga wewnętrznego pierścienia (24h, godziny 0 i 13–23). */
+export declare function handIsInner(hour: number, hourFormat: 12 | 24, phase: 'hours' | 'minutes'): boolean;

package/dist/clock.js

@@ -0,0 +1,93 @@
+import { from12h, pad } from "./iso.js";
+export const KPT_CLOCK_R_OUTER = 40;
+export const KPT_CLOCK_R_INNER = 26;
+/** Pozycja znacznika (% tarczy) na pierścieniu o promieniu `radius`: 12 na górze, zegarowo. */
+export function markPosition(index, radius) {
+    const theta = (index / 12) * 2 * Math.PI;
+    return { x: 50 + radius * Math.sin(theta), y: 50 - radius * Math.cos(theta) };
+}
+/**
+ * Znaczniki godzin. W 12h jeden pierścień pokazujący wybraną połowę doby; w 24h zewnętrzny
+ * (12, 1–11) i wewnętrzny (00, 13–23), bo 24 liczby na jednym okręgu byłyby nieczytelne.
+ */
+export function hourMarks(hour, hourFormat) {
+    if (hourFormat === 12) {
+        const ampm = hour < 12 ? 'AM' : 'PM';
+        return Array.from({ length: 12 }, (_, i) => {
+            const h12 = i === 0 ? 12 : i;
+            // Wartość docelowa bierze bieżące AM/PM — tarcza pokazuje tylko jedną połowę doby.
+            const value = from12h(h12, ampm);
+            return {
+                label: String(h12),
+                value,
+                ...markPosition(i, KPT_CLOCK_R_OUTER),
+                inner: false,
+                selected: hour === value,
+            };
+        });
+    }
+    const outer = Array.from({ length: 12 }, (_, i) => {
+        const value = i === 0 ? 12 : i;
+        return {
+            label: String(value),
+            value,
+            ...markPosition(i, KPT_CLOCK_R_OUTER),
+            inner: false,
+            selected: hour === value,
+        };
+    });
+    const inner = Array.from({ length: 12 }, (_, i) => {
+        const value = i === 0 ? 0 : i + 12;
+        // `pad` daje '00' dla północy; 13–23 są już dwucyfrowe.
+        return {
+            label: pad(value),
+            value,
+            ...markPosition(i, KPT_CLOCK_R_INNER),
+            inner: true,
+            selected: hour === value,
+        };
+    });
+    return [...outer, ...inner];
+}
+/** Znaczniki minut co pięć — pozostałe wartości wchodzą przeciąganiem. */
+export function minuteMarks(minute) {
+    return Array.from({ length: 12 }, (_, i) => {
+        const value = i * 5;
+        return {
+            label: pad(value),
+            value,
+            ...markPosition(i, KPT_CLOCK_R_OUTER),
+            inner: false,
+            selected: minute === value,
+        };
+    });
+}
+/**
+ * Godzina z kąta wskaźnika. W 24h o pierścieniu — a więc o 12–23 kontra 0–11 — decyduje promień
+ * kliknięcia, podany jako ułamek promienia tarczy.
+ */
+export function hourFromAngle(deg, radiusRatio, hourFormat, hour) {
+    const index = Math.round(deg / 30) % 12;
+    if (hourFormat === 12) {
+        const ampm = hour < 12 ? 'AM' : 'PM';
+        return from12h(index === 0 ? 12 : index, ampm);
+    }
+    const inner = radiusRatio < (KPT_CLOCK_R_OUTER + KPT_CLOCK_R_INNER) / 2 / 50;
+    if (inner)
+        return index === 0 ? 0 : index + 12;
+    return index === 0 ? 12 : index;
+}
+/** Minuta z kąta wskaźnika, dociągnięta do `minuteStep`. */
+export function minuteFromAngle(deg, minuteStep) {
+    const step = Math.max(1, minuteStep);
+    const raw = Math.round(deg / 6) % 60;
+    return (Math.round(raw / step) * step) % 60;
+}
+/** Kąt wskaźnika w stopniach dla bieżącego etapu tarczy. */
+export function handAngle(hour, minute, phase) {
+    return phase === 'hours' ? (hour % 12) * 30 : minute * 6;
+}
+/** Czy wskaźnik sięga wewnętrznego pierścienia (24h, godziny 0 i 13–23). */
+export function handIsInner(hour, hourFormat, phase) {
+    return phase === 'hours' && hourFormat === 24 && (hour === 0 || hour >= 13);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { datePart, formatDate, formatTime, from12h, pad, parseDate, parseDateTime, parseTime, timePart, toIso, } from './iso.ts';
+export { KPT_CALENDAR_LEVELS, buildDayGrid, buildDecadeCells, buildMonthCells, buildYearCells, canPageBack, canPageForward, centuryStart, commitLevelFor, decadeStart, initialPage, isMonthYearDisabled, isYearDisabled, pageBy, resolveStartView, selectedYearMonth, topLevelFor, } from './calendar.ts';
+export type { DayGridOptions, KptCalendarPage, KptCalendarView, KptDateSelectionMode, KptDayCell, KptGridCell, MonthCellsOptions, YearCellsOptions, } from './calendar.ts';
+export { buildRangeGrid, clampVisibleMonths, pickRangeDay } from './range.ts';
+export type { KptDateRangeMode, KptDateRangeValue, KptMonthPanel, KptRangeDayCell, RangeGridOptions, } from './range.ts';
+export { KPT_CLOCK_R_INNER, KPT_CLOCK_R_OUTER, handAngle, handIsInner, hourFromAngle, hourMarks, markPosition, minuteFromAngle, minuteMarks, } from './clock.ts';
+export type { KptClockMark } from './clock.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { datePart, formatDate, formatTime, from12h, pad, parseDate, parseDateTime, parseTime, timePart, toIso, } from "./iso.js";
+export { KPT_CALENDAR_LEVELS, buildDayGrid, buildDecadeCells, buildMonthCells, buildYearCells, canPageBack, canPageForward, centuryStart, commitLevelFor, decadeStart, initialPage, isMonthYearDisabled, isYearDisabled, pageBy, resolveStartView, selectedYearMonth, topLevelFor, } from "./calendar.js";
+export { buildRangeGrid, clampVisibleMonths, pickRangeDay } from "./range.js";
+export { KPT_CLOCK_R_INNER, KPT_CLOCK_R_OUTER, handAngle, handIsInner, hourFromAngle, hourMarks, markPosition, minuteFromAngle, minuteMarks, } from "./clock.js";

package/dist/iso.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Formaty tekstowe kontrolek daty. Wszystkie wartości są stringami ISO-podobnymi — nigdy `Date`
+ * — bo to one jadą do formularza i na serwer, a `Date` niesie strefę, której kalendarz nie ma.
+ */
+/** Liczba na dwie cyfry: 7 → '07'. */
+export declare function pad(value: number): string;
+/** Data lokalna → 'RRRR-MM-DD'. Celowo bez `toISOString()`, które przesuwa dzień o strefę. */
+export declare function toIso(date: Date): string;
+/** 'RRRR-MM-DD' → `Date` (lokalna północ) albo `null`, gdy format się nie zgadza. */
+export declare function parseDate(iso: string): Date | null;
+/** 'HH:mm' → `{ h, m }` albo `null`. */
+export declare function parseTime(value: string): {
+    h: number;
+    m: number;
+} | null;
+/** 'RRRR-MM-DDTHH:mm' (albo ze spacją) → części albo `null`. */
+export declare function parseDateTime(value: string): {
+    date: string;
+    h: number;
+    m: number;
+} | null;
+/** Sama data z wartości 'RRRR-MM-DD' lub 'RRRR-MM-DDTHH:mm'. */
+export declare function datePart(value: string): string;
+/** Sama godzina z wartości 'RRRR-MM-DDTHH:mm'; pusty string, gdy jej nie ma. */
+export declare function timePart(value: string): string;
+/** Godzina do prezentacji: 24h ('09:05') albo 12h z AM/PM ('9:05 AM'). */
+export declare function formatTime(h: number, m: number, hourFormat?: 12 | 24): string;
+/** Data do prezentacji: 'iso' zostawia 'RRRR-MM-DD', 'pl' daje 'DD.MM.RRRR'. */
+export declare function formatDate(iso: string, displayFormat?: 'pl' | 'iso'): string;
+/** Godzina 12h + AM/PM → doba 24h (12 AM = 0, 12 PM = 12). */
+export declare function from12h(h12: number, ampm: 'AM' | 'PM'): number;

package/dist/iso.js

@@ -0,0 +1,58 @@
+/**
+ * Formaty tekstowe kontrolek daty. Wszystkie wartości są stringami ISO-podobnymi — nigdy `Date`
+ * — bo to one jadą do formularza i na serwer, a `Date` niesie strefę, której kalendarz nie ma.
+ */
+/** Liczba na dwie cyfry: 7 → '07'. */
+export function pad(value) {
+    return String(value).padStart(2, '0');
+}
+/** Data lokalna → 'RRRR-MM-DD'. Celowo bez `toISOString()`, które przesuwa dzień o strefę. */
+export function toIso(date) {
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+/** 'RRRR-MM-DD' → `Date` (lokalna północ) albo `null`, gdy format się nie zgadza. */
+export function parseDate(iso) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso ?? '');
+    if (!match)
+        return null;
+    return new Date(+match[1], +match[2] - 1, +match[3]);
+}
+/** 'HH:mm' → `{ h, m }` albo `null`. */
+export function parseTime(value) {
+    const match = /^(\d{2}):(\d{2})$/.exec(value ?? '');
+    return match ? { h: +match[1], m: +match[2] } : null;
+}
+/** 'RRRR-MM-DDTHH:mm' (albo ze spacją) → części albo `null`. */
+export function parseDateTime(value) {
+    const match = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})$/.exec(value ?? '');
+    return match ? { date: match[1], h: +match[2], m: +match[3] } : null;
+}
+/** Sama data z wartości 'RRRR-MM-DD' lub 'RRRR-MM-DDTHH:mm'. */
+export function datePart(value) {
+    return value ? value.slice(0, 10) : '';
+}
+/** Sama godzina z wartości 'RRRR-MM-DDTHH:mm'; pusty string, gdy jej nie ma. */
+export function timePart(value) {
+    const match = /[T ](\d{2}:\d{2})$/.exec(value ?? '');
+    return match ? match[1] : '';
+}
+/** Godzina do prezentacji: 24h ('09:05') albo 12h z AM/PM ('9:05 AM'). */
+export function formatTime(h, m, hourFormat = 24) {
+    if (hourFormat === 12) {
+        const h12 = h % 12 === 0 ? 12 : h % 12;
+        return `${h12}:${pad(m)} ${h < 12 ? 'AM' : 'PM'}`;
+    }
+    return `${pad(h)}:${pad(m)}`;
+}
+/** Data do prezentacji: 'iso' zostawia 'RRRR-MM-DD', 'pl' daje 'DD.MM.RRRR'. */
+export function formatDate(iso, displayFormat = 'pl') {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso ?? '');
+    if (!match)
+        return '';
+    return displayFormat === 'iso' ? iso : `${match[3]}.${match[2]}.${match[1]}`;
+}
+/** Godzina 12h + AM/PM → doba 24h (12 AM = 0, 12 PM = 12). */
+export function from12h(h12, ampm) {
+    const base = h12 % 12;
+    return ampm === 'PM' ? base + 12 : base;
+}

package/dist/range.d.ts

@@ -0,0 +1,49 @@
+import type { KptCalendarPage } from './calendar.ts';
+export interface KptDateRangeValue {
+    start: string;
+    end: string;
+}
+/** Granulacja zakresu: same daty, daty z godziną, same godziny. */
+export type KptDateRangeMode = 'date' | 'datetime' | 'time';
+export interface KptRangeDayCell {
+    day: number;
+    iso: string;
+    inMonth: boolean;
+    today: boolean;
+    isStart: boolean;
+    isEnd: boolean;
+    inRange: boolean;
+    /** Pasmo zakresu wychodzi z tej komórki w prawo / dochodzi z lewej — do zaokrągleń kapsuły. */
+    rangeStart: boolean;
+    rangeEnd: boolean;
+    /** Pusty slot siatki: dni sąsiednich miesięcy przy wielu panelach. */
+    blank: boolean;
+    disabled: boolean;
+}
+/** Jeden miesiąc panelu kalendarza. */
+export interface KptMonthPanel {
+    key: string;
+    label: string;
+    weeks: KptRangeDayCell[][];
+}
+export interface RangeGridOptions {
+    page: KptCalendarPage;
+    start: string;
+    end: string;
+    todayIso: string;
+    /** Ukrywa dni sąsiednich miesięcy — konieczne, gdy paneli jest kilka. */
+    hideOutside?: boolean;
+}
+/**
+ * Siatka dni z pasmem zakresu. Przy kilku panelach dni sąsiednich miesięcy stają się pustymi
+ * slotami: inaczej ta sama data byłaby klikalna dwa razy — jako wygaszona w jednym panelu
+ * i właściwa w drugim — a pasmo malowałoby się w obu miejscach.
+ */
+export declare function buildRangeGrid({ page, start, end, todayIso, hideOutside, }: RangeGridOptions): KptRangeDayCell[][];
+/**
+ * Kolejny klik w zakresie: pierwszy ustawia początek, drugi koniec, trzeci zaczyna od nowa.
+ * Klik przed początkiem nie tworzy odwróconego zakresu — kolejność jest normalizowana.
+ */
+export declare function pickRangeDay(current: KptDateRangeValue, iso: string): KptDateRangeValue;
+/** Liczba paneli miesięcy: 1–3, bo więcej nie mieści się w typowym overlayu. */
+export declare function clampVisibleMonths(value: number): number;

package/dist/range.js

@@ -0,0 +1,52 @@
+import { toIso } from "./iso.js";
+/**
+ * Siatka dni z pasmem zakresu. Przy kilku panelach dni sąsiednich miesięcy stają się pustymi
+ * slotami: inaczej ta sama data byłaby klikalna dwa razy — jako wygaszona w jednym panelu
+ * i właściwa w drugim — a pasmo malowałoby się w obu miejscach.
+ */
+export function buildRangeGrid({ page, start, end, todayIso, hideOutside = false, }) {
+    const { y, m } = page;
+    const hasBand = !!start && !!end && start < end;
+    const first = new Date(y, m, 1);
+    const startOffset = (first.getDay() + 6) % 7;
+    const gridStart = new Date(y, m, 1 - startOffset);
+    const weeks = [];
+    for (let w = 0; w < 6; w++) {
+        const row = [];
+        for (let d = 0; d < 7; d++) {
+            const date = new Date(gridStart.getFullYear(), gridStart.getMonth(), gridStart.getDate() + w * 7 + d);
+            const iso = toIso(date);
+            const inMonth = date.getMonth() === m;
+            row.push({
+                day: date.getDate(),
+                iso,
+                inMonth,
+                today: iso === todayIso,
+                isStart: iso === start,
+                isEnd: iso === end,
+                inRange: hasBand && iso > start && iso < end,
+                rangeStart: hasBand && iso === start,
+                rangeEnd: hasBand && iso === end,
+                blank: hideOutside && !inMonth,
+                disabled: false,
+            });
+        }
+        weeks.push(row);
+    }
+    return weeks;
+}
+/**
+ * Kolejny klik w zakresie: pierwszy ustawia początek, drugi koniec, trzeci zaczyna od nowa.
+ * Klik przed początkiem nie tworzy odwróconego zakresu — kolejność jest normalizowana.
+ */
+export function pickRangeDay(current, iso) {
+    const { start, end } = current;
+    if (!start || (start && end))
+        return { start: iso, end: '' };
+    return iso < start ? { start: iso, end: start } : { start, end: iso };
+}
+/** Liczba paneli miesięcy: 1–3, bo więcej nie mieści się w typowym overlayu. */
+export function clampVisibleMonths(value) {
+    const n = Math.trunc(value);
+    return Number.isFinite(n) ? Math.min(3, Math.max(1, n)) : 1;
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@konce-pt/datetime",
+  "version": "0.8.0",
+  "description": "Calendar and clock core for Koncept UI date controls — day/month/year/decade grids, ranges, dial marks. 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/datetime"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "calendar",
+    "datepicker",
+    "date-range",
+    "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})\""
+  }
+}