@urbicon-ui/blocks 6.1.4

package/dist/components/Calendar/calendar.engine.js

@@ -0,0 +1,439 @@
+/**
+ * Event-layout, recurrence and navigation logic for the Calendar component.
+ *
+ * Pure date geometry (grids, week numbers, ranges, comparison, formatting)
+ * lives in the Svelte-free `$lib/date` layer and is imported from there. This
+ * module keeps only the Calendar-specific concerns: positioning timed and
+ * multi-day events, expanding recurrence rules and time-slot generation.
+ * No Svelte dependencies — fully testable in isolation.
+ */
+import { daysBetween, stripTime, toIso } from '../../date';
+/**
+ * Get day info for a multi-day event on a specific date.
+ * Returns the 0-based day index, total days, and start/end flags.
+ */
+export function getEventDayInfo(event, date) {
+    const startDay = stripTime(event.start);
+    const endDay = event.end ? stripTime(event.end) : startDay;
+    const currentDay = stripTime(date);
+    const totalDays = daysBetween(startDay, endDay) + 1;
+    const dayIndex = daysBetween(startDay, currentDay);
+    return {
+        dayIndex,
+        totalDays,
+        isStart: dayIndex === 0,
+        isEnd: dayIndex === totalDays - 1
+    };
+}
+/**
+ * Determine whether text on a given background color should be light or dark.
+ * Supports hex (#rgb, #rrggbb), rgb(), oklch(), and CSS named colors.
+ * Returns 'white' or 'black' based on perceived luminance.
+ */
+export function getContrastTextColor(bgColor) {
+    // Try to parse oklch
+    const oklchMatch = bgColor.match(/oklch\(\s*([\d.]+)/);
+    if (oklchMatch) {
+        const lightness = parseFloat(oklchMatch[1]);
+        // oklch lightness: 0 = black, 1 = white
+        return lightness > 0.6 ? 'black' : 'white';
+    }
+    // Try to parse hex
+    const hexMatch = bgColor.match(/^#?([\da-f]{3,8})$/i);
+    if (hexMatch) {
+        let hex = hexMatch[1];
+        if (hex.length === 3) {
+            hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+        }
+        const r = parseInt(hex.slice(0, 2), 16);
+        const g = parseInt(hex.slice(2, 4), 16);
+        const b = parseInt(hex.slice(4, 6), 16);
+        // Relative luminance approximation
+        const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+        return luminance > 0.5 ? 'black' : 'white';
+    }
+    // Try to parse rgb/rgba
+    const rgbMatch = bgColor.match(/rgba?\(\s*(\d+)\s*,?\s*(\d+)\s*,?\s*(\d+)/);
+    if (rgbMatch) {
+        const r = parseInt(rgbMatch[1], 10);
+        const g = parseInt(rgbMatch[2], 10);
+        const b = parseInt(rgbMatch[3], 10);
+        const luminance = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+        return luminance > 0.5 ? 'black' : 'white';
+    }
+    // Default: assume dark background
+    return 'white';
+}
+/**
+ * Compute layout segments for multi-day events in the month grid.
+ * Each multi-day event is split into per-week segments with column positions.
+ *
+ * @param events - All events to layout
+ * @param grid - The 2D date grid from getMonthGrid()
+ * @param maxRows - Maximum bar rows per week before overflow (default: 3)
+ * @returns Per-week array of bar segments and overflow counts
+ */
+export function getMultiDayEventLayout(events, grid, maxRows = 3) {
+    // Filter to multi-day events only
+    const multiDay = events.filter((e) => {
+        if (!e.end)
+            return false;
+        const s = stripTime(e.start);
+        const ed = stripTime(e.end);
+        return ed.getTime() > s.getTime();
+    });
+    // Sort by start date, then by duration (longer events first for stable stacking)
+    multiDay.sort((a, b) => {
+        const diff = stripTime(a.start).getTime() - stripTime(b.start).getTime();
+        if (diff !== 0)
+            return diff;
+        const aDur = (a.end ? stripTime(a.end).getTime() : stripTime(a.start).getTime()) -
+            stripTime(a.start).getTime();
+        const bDur = (b.end ? stripTime(b.end).getTime() : stripTime(b.start).getTime()) -
+            stripTime(b.start).getTime();
+        return bDur - aDur;
+    });
+    return grid.map((week) => {
+        const weekStart = stripTime(week[0]);
+        const weekEnd = stripTime(week[6]);
+        const occupiedRows = [];
+        const allSegments = [];
+        for (const event of multiDay) {
+            const evStart = stripTime(event.start);
+            const evEnd = event.end ? stripTime(event.end) : evStart;
+            if (evEnd < weekStart || evStart > weekEnd)
+                continue;
+            const visStart = evStart < weekStart ? weekStart : evStart;
+            const visEnd = evEnd > weekEnd ? weekEnd : evEnd;
+            const startCol = daysBetween(weekStart, visStart);
+            const endCol = daysBetween(weekStart, visEnd);
+            const spanCols = endCol - startCol + 1;
+            const isFirstSegment = evStart.getTime() >= weekStart.getTime();
+            const isLastSegment = evEnd.getTime() <= weekEnd.getTime();
+            // Find first available row
+            let assignedRow = 0;
+            while (true) {
+                if (!occupiedRows[assignedRow]) {
+                    occupiedRows[assignedRow] = Array(7).fill(false);
+                }
+                let fits = true;
+                for (let c = startCol; c <= endCol; c++) {
+                    if (occupiedRows[assignedRow][c]) {
+                        fits = false;
+                        break;
+                    }
+                }
+                if (fits)
+                    break;
+                assignedRow++;
+            }
+            if (!occupiedRows[assignedRow]) {
+                occupiedRows[assignedRow] = Array(7).fill(false);
+            }
+            for (let c = startCol; c <= endCol; c++) {
+                occupiedRows[assignedRow][c] = true;
+            }
+            allSegments.push({
+                eventId: event.id,
+                startCol,
+                spanCols,
+                isFirstSegment,
+                isLastSegment,
+                row: assignedRow
+            });
+        }
+        const visible = allSegments.filter((s) => s.row < maxRows);
+        const overflow = allSegments.filter((s) => s.row >= maxRows).length;
+        return { segments: visible, overflow };
+    });
+}
+/**
+ * Generate time slots for a time grid.
+ *
+ * @param startHour - First visible hour (0-23)
+ * @param endHour - Last visible hour, exclusive (1-24)
+ * @param interval - Slot interval in minutes (30 or 60)
+ * @returns Array of TimeSlot objects
+ */
+export function generateTimeSlots(startHour, endHour, interval = 60) {
+    const slots = [];
+    for (let hour = startHour; hour < endHour; hour++) {
+        slots.push({
+            hour,
+            minute: 0,
+            label: `${String(hour).padStart(2, '0')}:00`
+        });
+        if (interval === 30) {
+            slots.push({
+                hour,
+                minute: 30,
+                label: `${String(hour).padStart(2, '0')}:30`
+            });
+        }
+    }
+    return slots;
+}
+/**
+ * Position timed events within a time grid for a single day.
+ * Calculates top/height as percentages and resolves overlapping columns
+ * via a sweep-line algorithm for O(n log n) performance.
+ *
+ * @param events - Timed events for a single day
+ * @param forDate - The specific day being rendered
+ * @param startHour - First visible hour
+ * @param endHour - Last visible hour (exclusive)
+ * @returns Array of positioned events with layout info
+ */
+export function positionEvents(events, forDate, startHour, endHour) {
+    if (events.length === 0)
+        return [];
+    const totalMinutes = (endHour - startHour) * 60;
+    const gridStartMinutes = startHour * 60;
+    const dayStartMs = stripTime(forDate).getTime();
+    const dayEndMs = dayStartMs + 24 * 60 * 60 * 1000;
+    const positioned = [];
+    for (const event of events) {
+        const evStartMs = event.start.getTime();
+        const evEndMs = event.end ? event.end.getTime() : evStartMs + 60 * 60 * 1000; // default 1h duration
+        // Calculate minutes within this day (clamped to day boundaries)
+        const startMins = evStartMs < dayStartMs ? 0 : (evStartMs - dayStartMs) / 60000;
+        let endMins = evEndMs > dayEndMs ? 24 * 60 : (evEndMs - dayStartMs) / 60000;
+        // Handle midnight end (00:00 next day)
+        if (endMins === 0 && evEndMs > dayStartMs)
+            endMins = 24 * 60;
+        // Clamp to visible grid range
+        const clampedStart = Math.max(startMins - gridStartMinutes, 0);
+        const clampedEnd = Math.min(endMins - gridStartMinutes, totalMinutes);
+        if (clampedEnd <= clampedStart)
+            continue;
+        positioned.push({
+            event,
+            top: (clampedStart / totalMinutes) * 100,
+            height: Math.max(((clampedEnd - clampedStart) / totalMinutes) * 100, 2),
+            column: 0,
+            totalColumns: 1
+        });
+    }
+    resolveOverlaps(positioned);
+    return positioned;
+}
+/**
+ * Resolve overlapping events by assigning column indices via sweep-line.
+ * Mutates the input array in place.
+ */
+function resolveOverlaps(events) {
+    if (events.length <= 1)
+        return;
+    // Sort by top, then longer events first for stable stacking
+    events.sort((a, b) => a.top - b.top || b.height - a.height);
+    // Find connected overlap groups
+    const groups = [];
+    let group = [events[0]];
+    let groupBottom = events[0].top + events[0].height;
+    for (let i = 1; i < events.length; i++) {
+        const ev = events[i];
+        if (ev.top < groupBottom - 0.01) {
+            group.push(ev);
+            groupBottom = Math.max(groupBottom, ev.top + ev.height);
+        }
+        else {
+            groups.push(group);
+            group = [ev];
+            groupBottom = ev.top + ev.height;
+        }
+    }
+    groups.push(group);
+    // Assign columns within each group
+    for (const g of groups) {
+        if (g.length === 1)
+            continue;
+        const columns = [];
+        for (const ev of g) {
+            let placed = false;
+            for (let c = 0; c < columns.length; c++) {
+                const last = columns[c][columns[c].length - 1];
+                if (last.top + last.height <= ev.top + 0.01) {
+                    columns[c].push(ev);
+                    ev.column = c;
+                    placed = true;
+                    break;
+                }
+            }
+            if (!placed) {
+                ev.column = columns.length;
+                columns.push([ev]);
+            }
+        }
+        const total = columns.length;
+        for (const ev of g) {
+            ev.totalColumns = total;
+        }
+    }
+}
+/**
+ * Expand a recurring event into concrete instances within a date range.
+ * Only generates occurrences that fall within [rangeStart, rangeEnd].
+ * Each instance gets a unique ID (`${originalId}-${YYYY-MM-DD}`) and
+ * preserves all other event properties with adjusted dates.
+ *
+ * @param event - Source event with a recurrence rule
+ * @param rangeStart - Start of the visible range (inclusive)
+ * @param rangeEnd - End of the visible range (inclusive)
+ * @returns Array of concrete CalendarEvent instances
+ */
+export function expandRecurrence(event, rangeStart, rangeEnd) {
+    const rule = event.recurrence;
+    if (!rule)
+        return [event];
+    const interval = rule.interval ?? 1;
+    const eventDuration = event.end ? event.end.getTime() - event.start.getTime() : 0;
+    const exceptions = new Set((rule.exceptions ?? []).map((d) => toIso(d)));
+    const results = [];
+    let occurrenceCount = 0;
+    const maxOccurrences = rule.count ?? 1000; // safety limit
+    const untilDate = rule.until ? stripTime(rule.until) : null;
+    // Use a cursor starting from the event's original start date
+    let cursor = new Date(event.start);
+    // Fast-forward cursor to near rangeStart to avoid iterating through
+    // thousands of periods for old recurring events
+    const eventStart = stripTime(event.start);
+    const rangeStartDay = stripTime(rangeStart);
+    if (eventStart < rangeStartDay && !rule.count) {
+        const gap = daysBetween(eventStart, rangeStartDay);
+        switch (rule.frequency) {
+            case 'daily': {
+                const periodsToSkip = Math.max(0, Math.floor(gap / interval) - 1) * interval;
+                cursor = new Date(eventStart);
+                cursor.setDate(cursor.getDate() + periodsToSkip);
+                break;
+            }
+            case 'weekly': {
+                const weeksGap = Math.floor(gap / 7);
+                const periodsToSkip = Math.max(0, Math.floor(weeksGap / interval) - 1) * interval;
+                cursor = new Date(eventStart);
+                cursor.setDate(cursor.getDate() + periodsToSkip * 7);
+                break;
+            }
+            case 'monthly': {
+                const monthsGap = (rangeStartDay.getFullYear() - eventStart.getFullYear()) * 12 +
+                    (rangeStartDay.getMonth() - eventStart.getMonth());
+                const periodsToSkip = Math.max(0, Math.floor(monthsGap / interval) - 1) * interval;
+                cursor = new Date(eventStart);
+                cursor.setMonth(cursor.getMonth() + periodsToSkip);
+                break;
+            }
+            case 'yearly': {
+                const yearsGap = rangeStartDay.getFullYear() - eventStart.getFullYear();
+                const periodsToSkip = Math.max(0, Math.floor(yearsGap / interval) - 1) * interval;
+                cursor = new Date(eventStart);
+                cursor.setFullYear(cursor.getFullYear() + periodsToSkip);
+                break;
+            }
+        }
+    }
+    // For frequencies that need day-level iteration
+    let isFirstIteration = true;
+    while (occurrenceCount < maxOccurrences) {
+        // Check if we've passed the end of the range or the until date
+        if (stripTime(cursor) > stripTime(rangeEnd))
+            break;
+        if (untilDate && stripTime(cursor) > untilDate)
+            break;
+        const occurrences = getOccurrencesForCursor(cursor, rule, event.start, isFirstIteration);
+        isFirstIteration = false;
+        for (const occDate of occurrences) {
+            if (occurrenceCount >= maxOccurrences)
+                break;
+            if (untilDate && stripTime(occDate) > untilDate)
+                break;
+            const occKey = toIso(occDate);
+            // Skip exceptions — don't count against the occurrence limit
+            if (exceptions.has(occKey)) {
+                continue;
+            }
+            // Only include if within visible range
+            const occEnd = eventDuration > 0 ? new Date(occDate.getTime() + eventDuration) : undefined;
+            const occStart = stripTime(occDate);
+            const occEndDay = occEnd ? stripTime(occEnd) : occStart;
+            if (occEndDay >= stripTime(rangeStart) && occStart <= stripTime(rangeEnd)) {
+                // Create instance preserving time-of-day from original
+                const instanceStart = new Date(occDate);
+                instanceStart.setHours(event.start.getHours(), event.start.getMinutes(), event.start.getSeconds());
+                const instanceEnd = eventDuration > 0
+                    ? new Date(instanceStart.getTime() + eventDuration)
+                    : event.end
+                        ? new Date(instanceStart)
+                        : undefined;
+                results.push({
+                    ...event,
+                    id: `${event.id}-${occKey}`,
+                    start: instanceStart,
+                    end: instanceEnd
+                });
+            }
+            occurrenceCount++;
+        }
+        // Advance cursor based on frequency
+        cursor = advanceCursor(cursor, rule.frequency, interval);
+    }
+    return results;
+}
+/** Get occurrence dates for a single cursor position. */
+function getOccurrencesForCursor(cursor, rule, originalStart, isFirstIteration) {
+    switch (rule.frequency) {
+        case 'daily':
+            return [new Date(cursor)];
+        case 'weekly': {
+            if (rule.byDay && rule.byDay.length > 0) {
+                // Generate occurrences for each specified day in this week
+                const weekStart = new Date(cursor);
+                weekStart.setDate(weekStart.getDate() - weekStart.getDay());
+                const days = rule.byDay.map((day) => {
+                    const d = new Date(weekStart);
+                    d.setDate(weekStart.getDate() + day);
+                    return d;
+                });
+                // Only filter out days before the original start in the first iteration
+                if (isFirstIteration) {
+                    return days.filter((d) => stripTime(d) >= stripTime(originalStart));
+                }
+                return days;
+            }
+            return [new Date(cursor)];
+        }
+        case 'monthly': {
+            if (rule.byMonthDay && rule.byMonthDay.length > 0) {
+                return rule.byMonthDay
+                    .map((dayNum) => {
+                    const d = new Date(cursor.getFullYear(), cursor.getMonth(), dayNum);
+                    return d;
+                })
+                    .filter((d) => d.getMonth() === cursor.getMonth());
+            }
+            return [new Date(cursor)];
+        }
+        case 'yearly':
+            return [new Date(cursor)];
+        default:
+            return [new Date(cursor)];
+    }
+}
+/** Advance the cursor by one period based on frequency and interval. */
+function advanceCursor(cursor, frequency, interval) {
+    const next = new Date(cursor);
+    switch (frequency) {
+        case 'daily':
+            next.setDate(next.getDate() + interval);
+            break;
+        case 'weekly':
+            next.setDate(next.getDate() + 7 * interval);
+            break;
+        case 'monthly':
+            next.setMonth(next.getMonth() + interval);
+            break;
+        case 'yearly':
+            next.setFullYear(next.getFullYear() + interval);
+            break;
+    }
+    return next;
+}

package/dist/components/Calendar/calendar.types.d.ts

@@ -0,0 +1,141 @@
+import type { Snippet } from 'svelte';
+/** Category for grouping events by type with shared color coding. */
+export interface CalendarEventCategory {
+    /** Unique identifier for this category. */
+    id: string;
+    /** Display label (e.g., "Restmuell", "Papier"). */
+    label: string;
+    /** CSS color value (hex, oklch, rgb) or Tailwind class for dot/border rendering. */
+    color: string;
+    /** Optional icon snippet rendered alongside the label. */
+    icon?: Snippet;
+}
+/** A single calendar event/appointment. */
+export interface CalendarEvent {
+    /** Unique identifier. */
+    id: string;
+    /** Event title. */
+    title: string;
+    /** Start date/time. */
+    start: Date;
+    /** End date/time. Optional for all-day events. */
+    end?: Date;
+    /** Whether this is an all-day event. @default true */
+    allDay?: boolean;
+    /** Category ID linking to CalendarEventCategory. */
+    categoryId?: string;
+    /** Optional description or status text. */
+    description?: string;
+    /** Optional secondary helper text. */
+    helperText?: string;
+    /** Arbitrary metadata for consumer use. */
+    meta?: Record<string, unknown>;
+    /** Recurrence rule for repeating events. */
+    recurrence?: RecurrenceRule;
+}
+/** Recurrence rule for repeating events. */
+export interface RecurrenceRule {
+    /** How often the event repeats. */
+    frequency: 'daily' | 'weekly' | 'monthly' | 'yearly';
+    /** Repeat every N periods (e.g. 2 = every 2 weeks). @default 1 */
+    interval?: number;
+    /** Specific weekdays for weekly recurrence (0=Sun, 1=Mon, ..., 6=Sat). */
+    byDay?: number[];
+    /** Specific day(s) of month for monthly recurrence (1-31). */
+    byMonthDay?: number[];
+    /** End date — recurrence stops after this date (inclusive). */
+    until?: Date;
+    /** Maximum number of occurrences (including the original). */
+    count?: number;
+    /** Exception dates where the event does NOT occur. */
+    exceptions?: Date[];
+}
+/** Selection value depending on selection mode. */
+export type CalendarSelection = Date | DateRange | Date[];
+/** A date range with inclusive start and end. */
+export interface DateRange {
+    start: Date;
+    end: Date;
+}
+/** Context passed to custom dayCell snippets. */
+export interface DayCellContext {
+    date: Date;
+    events: CalendarEvent[];
+    isToday: boolean;
+    isSelected: boolean;
+    isDisabled: boolean;
+    isOutsideMonth: boolean;
+    isFocused: boolean;
+}
+/** Metadata for a multi-day event on a specific date. */
+export interface EventDayInfo {
+    event: CalendarEvent;
+    /** 0-based index: which day of the multi-day event this is. */
+    dayIndex: number;
+    /** Total duration in days. 1 for single-day events. */
+    totalDays: number;
+    /** Whether this date is the start of the event. */
+    isStart: boolean;
+    /** Whether this date is the end of the event. */
+    isEnd: boolean;
+}
+/** Context passed to custom eventItem snippets. */
+export interface EventItemContext {
+    event: CalendarEvent;
+    category?: CalendarEventCategory;
+    /** 0-based index: which day of the multi-day event (only set for multi-day). */
+    dayIndex?: number;
+    /** Total duration in days (only set for multi-day, > 1). */
+    totalDays?: number;
+    /** Whether this date is the start of the event. */
+    isStart?: boolean;
+    /** Whether this date is the end of the event. */
+    isEnd?: boolean;
+}
+/** A single time slot in the time grid. */
+export interface TimeSlot {
+    hour: number;
+    minute: number;
+    label: string;
+}
+/** A positioned event in the time grid. */
+export interface PositionedEvent {
+    event: CalendarEvent;
+    /** Top offset as percentage of grid height. */
+    top: number;
+    /** Height as percentage of grid height. */
+    height: number;
+    /** Column index when events overlap (0-based). */
+    column: number;
+    /** Total number of overlapping columns. */
+    totalColumns: number;
+}
+/** A segment of a multi-day event bar rendered within one week row. */
+export interface MultiDayBarSegment {
+    /** Event ID (resolved to full event object by the consumer). */
+    eventId: string;
+    /** 0-based start column in the 7-column grid. */
+    startCol: number;
+    /** Number of columns this segment spans. */
+    spanCols: number;
+    /** Whether this is the first visual segment of the event. */
+    isFirstSegment: boolean;
+    /** Whether this is the last visual segment of the event. */
+    isLastSegment: boolean;
+    /** Vertical row index for stacking (0, 1, 2, ...). */
+    row: number;
+}
+/** Available view modes for the calendar. */
+export type CalendarViewMode = 'month' | 'year' | 'week' | 'day' | 'agenda';
+/** Context passed to custom header snippets. */
+export interface HeaderContext {
+    view: CalendarViewMode;
+    month: number;
+    year: number;
+    title: string;
+    navigate: (delta: number) => void;
+    navigateMonth: (delta: number) => void;
+    goToToday: () => void;
+    canGoBack: boolean;
+    canGoForward: boolean;
+}

package/dist/components/Calendar/calendar.types.js

@@ -0,0 +1 @@
+export {};