@softium/calendar 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * softium-ui Calendar — core types.
+ *
+ * Ported from the calendary project into softium-ui's token-CSS conventions.
+ * Server / Google-Calendar / today-task concerns are intentionally dropped —
+ * this is a pure UI component driven by local state (or host-provided state).
+ */
+type ViewType = 'day' | 'week' | 'month' | 'year';
+type RecurrenceFreq = 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'YEARLY';
+interface Recurrence {
+    freq: RecurrenceFreq;
+    /** every N periods (1 = every period) */
+    interval: number;
+    /** weekly only — weekdays as Mon=0 … Sun=6 (matches the recurrence editor) */
+    byweekday?: number[];
+    /** repeat until this date (inclusive) */
+    until?: Date;
+    /** repeat this many occurrences */
+    count?: number;
+}
+interface Category {
+    id: string;
+    name: string;
+    /** hex color, e.g. "#E30000" */
+    color: string;
+}
+/** a single day's holiday/observance label, shown in the month view's date header */
+interface Holiday {
+    date: Date;
+    name: string;
+}
+interface CalendarEvent {
+    id: string;
+    title: string;
+    /** start date (time-of-day carried separately in startTime) */
+    date: Date;
+    /** end date for multi-day / period events */
+    endDate?: Date;
+    /** "HH:MM" */
+    startTime?: string;
+    /** "HH:MM" */
+    endTime?: string;
+    description?: string;
+    categoryId?: string;
+    recurrence?: Recurrence;
+    /** dates excluded from a recurring series */
+    exdate?: Date[];
+    /** true for a generated occurrence of a recurring series (never persisted) */
+    isRecurringInstance?: boolean;
+    /** id of the master event a recurring instance came from */
+    recurringEventId?: string;
+}
+/** the working draft shown in an event's time-grid position while editing */
+interface PreviewEvent {
+    title: string;
+    startTime: string;
+    endTime: string;
+    description: string;
+    categoryId: string;
+    startDate?: Date;
+    endDate?: Date;
+    isPeriod?: boolean;
+}
+
+interface UseCalendarOptions {
+    initialEvents?: CalendarEvent[];
+    initialCategories?: Category[];
+}
+interface CalendarController {
+    events: CalendarEvent[];
+    setEvents: React.Dispatch<React.SetStateAction<CalendarEvent[]>>;
+    addEvent: (data: Omit<CalendarEvent, 'id'>) => CalendarEvent;
+    updateEvent: (id: string, data: Partial<CalendarEvent>) => void;
+    deleteEvent: (id: string) => void;
+    /** undo/redo over event add/update/delete/move (see setEvents) */
+    canUndo: boolean;
+    canRedo: boolean;
+    undo: () => void;
+    redo: () => void;
+    categories: Category[];
+    setCategories: React.Dispatch<React.SetStateAction<Category[]>>;
+    addCategory: (data: {
+        name: string;
+        color: string;
+    }) => string;
+    updateCategory: (id: string, data: Partial<Category>) => void;
+    deleteCategory: (id: string) => void;
+    reorderCategories: (from: number, to: number) => void;
+    selectedCategoryIds: string[];
+    toggleCategory: (id: string) => void;
+    setSelectedCategoryIds: React.Dispatch<React.SetStateAction<string[]>>;
+}
+/**
+ * useCalendar — self-contained local state for events + categories + the
+ * category filter selection. No server/Google concerns; this is the state a
+ * host would otherwise wire to its own backend.
+ */
+declare function useCalendar(options?: UseCalendarOptions): CalendarController;
+
+interface CalendarProps {
+    /** UI language for the calendar's own strings. Default 'ko'. */
+    language?: string;
+    /** an external controller (from useCalendar); one is created internally if omitted */
+    controller?: CalendarController;
+    initialEvents?: CalendarEvent[];
+    initialCategories?: Category[];
+    initialDate?: Date;
+    initialView?: ViewType;
+    /** holidays/observances shown as a label in the month view's date header */
+    holidays?: Holiday[];
+    className?: string;
+}
+/**
+ * Calendar — the full calendar UI: a toolbar (title, prev/next/today, search,
+ * category filter, view switcher) over month/week/day/year views, with an
+ * event create/edit modal. Ported from the calendary project into softium
+ * token CSS; server / Google-Calendar / today-task concerns removed. Runs off
+ * local state (or a host-provided controller).
+ */
+declare function Calendar({ language, controller, initialEvents, initialCategories, initialDate, initialView, holidays, className, }: CalendarProps): ReactNode;
+
+interface MonthViewProps {
+    currentDate: Date;
+    events: CalendarEvent[];
+    selectedCategoryIds: string[];
+    categories: Category[];
+    language: string;
+    /** holidays/observances shown as a label next to the date number */
+    holidays?: Holiday[];
+    selectedEvent: CalendarEvent | null;
+    previewEvent: PreviewEvent | null;
+    expandedRows: Set<number>;
+    setExpandedRows: (updater: (prev: Set<number>) => Set<number>) => void;
+    onEventClick: (event: CalendarEvent, element?: HTMLElement) => void;
+    /** open the create modal for a single day (the "+ new" hover button) */
+    onAddEventClick: (date: Date, x?: number, y?: number) => void;
+    /** open the create modal for a dragged multi-day range */
+    onRangeSelect: (start: Date, end: Date, x: number, y: number) => void;
+    /** drag an event chip/bar onto another day to move it — for a recurring
+     * event, the host is expected to resolve a "this/following/all" scope
+     * (e.g. via a dialog) before actually committing the move */
+    onEventMove: (event: CalendarEvent, newDate: Date) => void;
+    /** drag a non-recurring period bar's start/end edge onto another day to resize it */
+    onEventResize: (event: CalendarEvent, edge: 'start' | 'end', newDate: Date) => void;
+}
+declare function MonthView({ currentDate, events, selectedCategoryIds, categories, language, holidays, selectedEvent, previewEvent, expandedRows, setExpandedRows, onEventClick, onAddEventClick, onRangeSelect, onEventMove, onEventResize, }: MonthViewProps): react.JSX.Element;
+
+interface WeekViewProps {
+    currentDate: Date;
+    events: CalendarEvent[];
+    selectedCategoryIds: string[];
+    categories: Category[];
+    language: string;
+    selectedEvent: CalendarEvent | null;
+    previewEvent: PreviewEvent | null;
+    onEventClick: (event: CalendarEvent, element?: HTMLElement) => void;
+    onAddEventClick: (date: Date, hour?: number, clientX?: number, clientY?: number) => void;
+    /** drag an empty time-grid area (snapped to 15 min) to create a timed event */
+    onTimeRangeSelect: (date: Date, startMin: number, endMin: number) => void;
+    /** drag (any event) or resize (non-recurring only) to a new start/end
+     * time; `newDate` is set only when a "move" drag also crossed into a
+     * different day column. For a recurring event, the host is expected to
+     * resolve a "this/following/all" scope before actually committing */
+    onEventTimeChange: (event: CalendarEvent, startMin: number, endMin: number, newDate?: Date) => void;
+}
+/** WeekView — a 7-day × 24-hour time grid with absolutely-positioned event chips. */
+declare function WeekView({ currentDate, events, selectedCategoryIds, categories, language, selectedEvent, previewEvent, onEventClick, onAddEventClick, onTimeRangeSelect, onEventTimeChange, }: WeekViewProps): react.JSX.Element;
+
+interface DayViewProps {
+    currentDate: Date;
+    events: CalendarEvent[];
+    selectedCategoryIds: string[];
+    categories: Category[];
+    language: string;
+    selectedEvent: CalendarEvent | null;
+    previewEvent: PreviewEvent | null;
+    onEventClick: (event: CalendarEvent, element?: HTMLElement) => void;
+    onAddEventClick: (date: Date, hour?: number, clientX?: number, clientY?: number) => void;
+    /** drag an empty time-grid area (snapped to 15 min) to create a timed event */
+    onTimeRangeSelect: (date: Date, startMin: number, endMin: number) => void;
+    /** drag (any event) or resize (non-recurring only) to a new start/end
+     * time. For a recurring event, the host is expected to resolve a
+     * "this/following/all" scope before actually committing */
+    onEventTimeChange: (event: CalendarEvent, startMin: number, endMin: number) => void;
+}
+/** DayView — a single-day × 24-hour time grid. */
+declare function DayView({ currentDate, events, selectedCategoryIds, categories, language, selectedEvent, previewEvent, onEventClick, onAddEventClick, onTimeRangeSelect, onEventTimeChange, }: DayViewProps): react.JSX.Element;
+
+interface YearViewProps {
+    currentDate: Date;
+    events: CalendarEvent[];
+    selectedCategoryIds: string[];
+    categories: Category[];
+    language: string;
+    onDateClick: (date: Date) => void;
+    onViewChange: (view: 'month') => void;
+}
+/** YearView — a 12-up grid of mini month calendars with per-day event dots. */
+declare function YearView({ currentDate, events, selectedCategoryIds, categories, language, onDateClick, onViewChange, }: YearViewProps): react.JSX.Element;
+
+type DeleteType = 'this' | 'following' | 'all';
+interface DeleteOptionsDialogProps {
+    language: string;
+    selectedDeleteType: DeleteType;
+    setSelectedDeleteType: (type: DeleteType) => void;
+    onCancel: () => void;
+    onDelete: () => void;
+}
+/**
+ * DeleteOptionsDialog — the recurring-event delete scope picker (this / this &
+ * following / all), shown in a small centered dialog. Ported from calendary.
+ */
+declare function DeleteOptionsDialog({ language, selectedDeleteType, setSelectedDeleteType, onCancel, onDelete, }: DeleteOptionsDialogProps): react.JSX.Element;
+
+interface EventSaveData {
+    title: string;
+    startTime: string;
+    endTime: string;
+    description: string;
+    categoryId: string;
+    startDate: Date;
+    endDate?: Date;
+    recurrence?: Recurrence;
+}
+interface EventModalProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** the event being edited, or null when creating */
+    event?: CalendarEvent | null;
+    selectedDate: Date | null;
+    selectedEndDate?: Date | null;
+    defaultStartTime?: string;
+    defaultEndTime?: string;
+    categories: Category[];
+    selectedCategoryIds: string[];
+    language: string;
+    onSave: (data: EventSaveData) => void;
+    onDelete?: (deleteType: DeleteType) => void;
+    /** live preview callback (drives the ghost chip in the views) */
+    onChange?: (data: EventSaveData | null) => void;
+    onToggleCategory: (id: string) => void;
+    onAddCategory: (data: {
+        name: string;
+        color: string;
+    }) => string;
+    onUpdateCategory: (id: string, data: {
+        name: string;
+        color: string;
+    }) => void;
+    onDeleteCategory: (id: string) => void;
+    onReorderCategories: (from: number, to: number) => void;
+}
+/**
+ * EventModal — the create/edit event dialog. Ported from calendary's
+ * EventCreatePopover into a centered token-CSS modal: title, start/end date,
+ * start/end time (duration-preserving), a category picker with inline add/edit,
+ * a description field, and a recurrence editor. Save / Cancel / Delete footer;
+ * deleting a recurring event opens the scope picker.
+ */
+declare function EventModal({ open, onOpenChange, event, selectedDate, selectedEndDate, defaultStartTime, defaultEndTime, categories, selectedCategoryIds, language, onSave, onDelete, onChange, onToggleCategory, onAddCategory, onUpdateCategory, onDeleteCategory, onReorderCategories, }: EventModalProps): react.JSX.Element | null;
+
+type RecurrenceEndType = 'never' | 'date' | 'count';
+interface RecurrenceSectionProps {
+    language: string;
+    recurrenceFreq: RecurrenceFreq;
+    setRecurrenceFreq: (freq: RecurrenceFreq) => void;
+    /** weekdays as Mon=0 … Sun=6 */
+    selectedWeekdays: number[];
+    setSelectedWeekdays: (weekdays: number[]) => void;
+    recurrenceEndType: RecurrenceEndType;
+    setRecurrenceEndType: (type: RecurrenceEndType) => void;
+    recurrenceCount: string | number;
+    setRecurrenceCount: (count: string | number) => void;
+    recurrenceEndDate: Date | undefined;
+    setRecurrenceEndDate: (date: Date | undefined) => void;
+    internalStartDate: Date | undefined;
+}
+/**
+ * RecurrenceSection — frequency segmented tabs, a weekly weekday picker, and an
+ * end-condition selector (never / date / count). Ported from calendary. Fully
+ * controlled; all state lives in the parent event modal.
+ */
+declare function RecurrenceSection({ language, recurrenceFreq, setRecurrenceFreq, selectedWeekdays, setSelectedWeekdays, recurrenceEndType, setRecurrenceEndType, recurrenceCount, setRecurrenceCount, setRecurrenceEndDate, internalStartDate, }: RecurrenceSectionProps): react.JSX.Element;
+
+interface RecurrenceScopeDialogProps {
+    language: string;
+    selectedScope: DeleteType;
+    setSelectedScope: (type: DeleteType) => void;
+    onCancel: () => void;
+    onConfirm: () => void;
+}
+/**
+ * RecurrenceScopeDialog — the recurring-event drag-move scope picker (this /
+ * this & following / all), shown in a small centered dialog. Same shape as
+ * DeleteOptionsDialog but a separate component: the confirm action here is
+ * "move" (primary button), not "delete" (danger button), and the two flows
+ * are independent enough that sharing one component wasn't worth the prop
+ * branching.
+ */
+declare function RecurrenceScopeDialog({ language, selectedScope, setSelectedScope, onCancel, onConfirm, }: RecurrenceScopeDialogProps): react.JSX.Element;
+
+interface CategoryItemProps {
+    cat: Category;
+    index: number;
+    checked: boolean;
+    language: string;
+    colorPalette: string[];
+    /** whether this row is in inline-edit mode */
+    editing: boolean;
+    onToggle: (id: string) => void;
+    onEditStart: (cat: Category) => void;
+    onEditCommit: (id: string, data: {
+        name: string;
+        color: string;
+    }) => void;
+    onEditCancel: () => void;
+    onDelete: (id: string) => void;
+    /** native drag reorder wiring */
+    onDragStartRow: (index: number) => void;
+    onDragEnterRow: (index: number) => void;
+    onDropRow: () => void;
+}
+/**
+ * CategoryItem — one row in the category list: a color-dot checkbox + name, a
+ * hover "⋯" menu (edit / delete), an inline edit mode with a color-swatch
+ * popover, and native drag-to-reorder. Ported from calendary's
+ * DraggableCategoryItem (Google-calendar branches dropped).
+ */
+declare function CategoryItem({ cat, index, checked, language, colorPalette, editing, onToggle, onEditStart, onEditCommit, onEditCancel, onDelete, onDragStartRow, onDragEnterRow, onDropRow, }: CategoryItemProps): react.JSX.Element;
+
+interface CategoryFilterProps {
+    categories: Category[];
+    selectedCategoryIds: string[];
+    language: string;
+    onToggle: (id: string) => void;
+    onAdd: (data: {
+        name: string;
+        color: string;
+    }) => string;
+    onUpdate: (id: string, data: {
+        name: string;
+        color: string;
+    }) => void;
+    onDelete: (id: string) => void;
+    onReorder: (from: number, to: number) => void;
+}
+/**
+ * CategoryFilter — the header's "N selected" popover: the multi-select category
+ * list (drag-reorderable) plus an inline add row. Ported from calendary's
+ * category dropdown.
+ */
+declare function CategoryFilter({ categories, selectedCategoryIds, language, onToggle, onAdd, onUpdate, onDelete, onReorder, }: CategoryFilterProps): react.JSX.Element;
+
+interface SegmentOption<T extends string> {
+    value: T;
+    label: ReactNode;
+}
+interface SegmentTabsProps<T extends string> {
+    value: T;
+    onValueChange: (value: T) => void;
+    options: SegmentOption<T>[];
+    /** each tab grows to fill (used inside grids/rows). Default false. */
+    block?: boolean;
+    className?: string;
+}
+/**
+ * SegmentTabs — an iOS-style segmented control: a muted track with a raised
+ * white pill on the active tab. Ported from calendary's SegmentTabs.
+ */
+declare function SegmentTabs<T extends string>({ value, onValueChange, options, block, className, }: SegmentTabsProps<T>): react.JSX.Element;
+
+/** Apple-style category color presets (ported from calendary). */
+declare const COLOR_PRESETS: string[];
+/** nearest preset to an arbitrary hex, by RGB euclidean distance */
+declare function findClosestPresetColor(hex: string): string;
+/** hex → rgba at the given alpha (used for the event-chip fill tint) */
+declare function withAlpha(color: string | undefined, alpha: number): string;
+
+/**
+ * All occurrence *dates* of a recurring series that fall in [from, to]
+ * (inclusive), honouring interval / byweekday / until / count. No rrule dep —
+ * a compact engine covering DAILY / WEEKLY / MONTHLY / YEARLY. Exported for
+ * "this and following" recurrence splits (see Calendar.tsx's
+ * handleRecurrenceScopeConfirm), which needs to know how many occurrences
+ * land before a given split date to carry over a correct remaining `count`.
+ */
+declare function occurrencesInRange(base: Date, rec: Recurrence, from: Date, to: Date): Date[];
+/**
+ * Expand every recurring master in `events` into concrete instances that fall
+ * inside [startDate, endDate]; non-recurring events pass through unchanged.
+ */
+declare function expandRecurringEvents(events: CalendarEvent[], startDate: Date, endDate: Date): CalendarEvent[];
+/** whether `date` falls inside an event's [date, endDate] span (day-granular) */
+declare function eventCoversDate(event: CalendarEvent, date: Date): boolean;
+/** events on a given date, category-filtered, sorted by start time */
+declare function getEventsForDate(date: Date | null, events: CalendarEvent[], selectedCategoryIds: string[]): CalendarEvent[];
+/** first free hour ("HH:00") on a date, 09:00–23:00, else 09:00 */
+declare function getNextAvailableTime(date: Date | null, events: CalendarEvent[]): string;
+
+declare const monthNames: Record<string, string[]>;
+declare const dayNames: Record<string, string[]>;
+/** the month grid, including leading/trailing days from adjacent months */
+declare function getDaysInMonth(date: Date): {
+    days: Date[];
+    rows: number;
+};
+/** the seven days (Sun→Sat) of the week containing `date` */
+declare function getWeekDays(date: Date): Date[];
+declare function isSameDay(a: Date | null, b: Date | null): boolean;
+declare function isToday(date: Date | null): boolean;
+declare function isCurrentMonth(date: Date | null, currentDate: Date): boolean;
+declare function getPreviousPeriodDate(currentDate: Date, viewType: ViewType): Date;
+declare function getNextPeriodDate(currentDate: Date, viewType: ViewType): Date;
+/** YYYY-MM-DD (local) */
+declare function formatDate(date: Date): string;
+/** clientY inside a time-grid column's bounding rect → minutes-of-day (0–1440), unclamped-snap-ready */
+declare function minutesFromY(clientY: number, rect: {
+    top: number;
+    height: number;
+}): number;
+/** round to the nearest `step` minutes (default 15) */
+declare function snapMinutes(minutes: number, step?: number): number;
+/** minutes-of-day → "HH:MM", clamped to a valid time */
+declare function minutesToHHMM(minutes: number): string;
+/** "HH:MM" → minutes-of-day */
+declare function hhmmToMinutes(hhmm: string | undefined): number;
+
+/** The calendar ships ko/en strings inline (like the source), chosen by `language`. */
+type CalLocale = 'ko' | 'en';
+
+/**
+ * @softium/calendar
+ *
+ * A full calendar UI (month / week / day / year views + an event create/edit
+ * modal with categories and recurrence), token-CSS themed. Import the stylesheet
+ * once:  import '@softium/calendar/styles.css';
+ */
+declare const VERSION = "0.0.0";
+
+export { COLOR_PRESETS, type CalLocale, Calendar, type CalendarController, type CalendarEvent, type CalendarProps, type Category, CategoryFilter, type CategoryFilterProps, CategoryItem, type CategoryItemProps, DayView, type DayViewProps, DeleteOptionsDialog, type DeleteOptionsDialogProps, type DeleteType, EventModal, type EventModalProps, type EventSaveData, type Holiday, MonthView, type MonthViewProps, type PreviewEvent, type Recurrence, type RecurrenceEndType, type RecurrenceFreq, RecurrenceScopeDialog, type RecurrenceScopeDialogProps, RecurrenceSection, type RecurrenceSectionProps, type SegmentOption, SegmentTabs, type SegmentTabsProps, type UseCalendarOptions, VERSION, type ViewType, WeekView, type WeekViewProps, YearView, type YearViewProps, dayNames, eventCoversDate, expandRecurringEvents, findClosestPresetColor, formatDate, getDaysInMonth, getEventsForDate, getNextAvailableTime, getNextPeriodDate, getPreviousPeriodDate, getWeekDays, hhmmToMinutes, isCurrentMonth, isSameDay, isToday, minutesFromY, minutesToHHMM, monthNames, occurrencesInRange, snapMinutes, useCalendar, withAlpha };