ape-calendar 0.2.0 → 0.5.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, ButtonHTMLAttributes } from 'react';
-import { LocaleInput, EventInput } from '@fullcalendar/core';
+import { LocaleInput, EventInput, BusinessHoursInput } from '@fullcalendar/core';
 import { Locale } from 'react-day-picker';
 import * as PopoverPrimitive from '@radix-ui/react-popover';
 
@@ -9,7 +9,7 @@ import * as PopoverPrimitive from '@radix-ui/react-popover';
  * Default event status union. Consumers can pass their own string union as a
  * generic parameter to override.
  */
-type DefaultEventStatus = 'draft' | 'published' | 'scheduled' | 'archived';
+type DefaultEventStatus = 'draft' | 'published' | 'scheduled' | 'archived' | 'cancelled' | 'finalizado';
 /**
  * Minimum shape a calendar event must satisfy. Consumers extend this interface
  * with their own domain fields (eventType, modalities, audience, etc.) and pass
@@ -41,11 +41,36 @@ interface BaseCalendarEvent<Status extends string = DefaultEventStatus> {
     durationMinutes?: number;
     isAllDay?: boolean;
 }
-type CalendarView = 'day' | 'week' | 'month';
+/**
+ * Calendar views. Designs prioritise `list` / `week` / `month`; `day` is kept
+ * for consumers that still rely on the single-day time grid.
+ */
+type CalendarView = 'list' | 'day' | 'week' | 'month';
 interface CalendarVisibleRange {
     start: Date;
     end: Date;
 }
+/**
+ * Direction to move the visible range by one step in the current view.
+ */
+type CalendarNavDirection = 'prev' | 'next' | 'today';
+/**
+ * Availability ("horario de atención") band rendered as a subtle background in
+ * the time-grid views. Shape matches FullCalendar's `businessHours` input so it
+ * can be fed straight through `mapAvailabilityToBusinessHours`.
+ *
+ * Mirror this shape in `ape-calendar-form` (AvailabilityScheduleDialog emits it)
+ * — the two packages intentionally do not depend on each other.
+ */
+interface AvailabilitySlot {
+    /** Days of week the slot applies to. 0=Sunday … 6=Saturday. */
+    daysOfWeek: number[];
+    /** Start of the slot, `HH:mm` (24h). */
+    startTime: string;
+    /** End of the slot, `HH:mm` (24h). */
+    endTime: string;
+}
+type AvailabilitySchedule = AvailabilitySlot[];
 type CalendarUpdateSource = 'mini' | 'macro' | 'system';
 interface SlotActionState {
     isOpen: boolean;
@@ -74,10 +99,76 @@ interface EventTimeChangePayload<E> {
     revert: () => void;
 }
 
+interface EventListRowMessages {
+    edit?: (title: string) => string;
+    delete?: (title: string) => string;
+}
+interface EventListRowProps<Status extends string, E extends BaseCalendarEvent<Status>> {
+    event: E;
+    onEdit: (event: E) => void;
+    onDelete: (event: E) => void;
+    locale?: string;
+    /** Map of status → label override for the EventStatusBadge. */
+    statusLabels?: Partial<Record<Status, string>>;
+    /** Domain-specific meta (event type, modality…). Same contract as MacroCalendar. */
+    renderEventMeta?: (event: E) => ReactNode;
+    messages?: EventListRowMessages;
+}
+/**
+ * Single row of the agenda/list view: time chip on the left, title + meta in
+ * the middle, status badge + actions on the right — matching the Figma agenda
+ * layout. Rendered by `EventAgendaList`; usable standalone.
+ */
+declare const EventListRow: <Status extends string, E extends BaseCalendarEvent<Status>>({ event, onEdit, onDelete, locale, statusLabels, renderEventMeta, messages, }: EventListRowProps<Status, E>) => react_jsx_runtime.JSX.Element;
+
+interface EventAgendaListMessages extends EventListRowMessages {
+    /** Empty placeholder per day when there are events elsewhere in the range. */
+    noEventsForDay?: string;
+    /** Global empty state when no events in the entire range. */
+    noEvents?: string;
+}
+interface EventAgendaListDayInfo<E> {
+    hasEvents: boolean;
+    events: E[];
+}
+interface EventAgendaListProps<Status extends string, E extends BaseCalendarEvent<Status>> {
+    events: E[];
+    /** Half-open `[start, end)` window — all days in between are rendered. */
+    range: {
+        start: Date;
+        end: Date;
+    };
+    /** BCP-47 locale string. Default: `'es-CO'`. */
+    locale?: string;
+    statusLabels?: Partial<Record<Status, string>>;
+    renderEventMeta?: (event: E) => ReactNode;
+    /**
+     * Slot rendered between the day anchor and the event list — used by portals
+     * to inject availability pills ("Horario de atención" / "No tenemos atención")
+     * or any other per-day header. The library does NOT derive this from the
+     * `availability` prop; the portal decides.
+     */
+    renderDayHeader?: (date: Date, info: EventAgendaListDayInfo<E>) => ReactNode;
+    onEditEvent: (event: E) => void;
+    onDeleteEvent: (event: E) => void;
+    messages?: EventAgendaListMessages;
+    className?: string;
+}
+/**
+ * Day-grouped agenda list — the calendar's "list" view. Each day renders a
+ * left anchor (number + short month + weekday) and a stack of {@link EventListRow}s.
+ * Empty days still render so the consumer can show a "no attention" pill via
+ * the `renderDayHeader` slot.
+ */
+declare const EventAgendaList: <Status extends string, E extends BaseCalendarEvent<Status>>({ events, range, locale, statusLabels, renderEventMeta, renderDayHeader, onEditEvent, onDeleteEvent, messages, className, }: EventAgendaListProps<Status, E>) => react_jsx_runtime.JSX.Element;
+
 interface MacroCalendarMessages {
-    moreLink?: (count: number) => string;
+    /** `+N more` link. String form interpolates `{count}`; function form receives the count. */
+    moreLink?: string | ((count: number) => string);
     allDayText?: string;
     todayHeaderAria?: string;
+    /** Empty-state text shown by the list view when there are no events in range. */
+    noEvents?: string;
 }
 interface MacroCalendarProps<Status extends string, E extends BaseCalendarEvent<Status>> {
     events: E[];
@@ -101,14 +192,39 @@ interface MacroCalendarProps<Status extends string, E extends BaseCalendarEvent<
     fullCalendarLocale?: LocaleInput;
     /** First day of the week (0=Sunday, 1=Monday, etc.). Default: 1. */
     firstDay?: number;
+    /** Availability ("horario de atención") band painted as a subtle time-grid background. */
+    availability?: AvailabilitySchedule;
     statusLabels?: Partial<Record<Status, string>>;
     renderEventMeta?: (event: E) => ReactNode;
+    /** Custom render for a day-column header. Falls back to the built-in header when omitted. */
+    renderDayHeader?: (date: Date, info: {
+        isToday: boolean;
+    }) => ReactNode;
+    /**
+     * Per-day header slot for the agenda/list view (e.g. "Horario de atención"
+     * pill, "No tenemos atención"…). The library does not derive this from the
+     * `availability` prop — the portal decides.
+     */
+    renderAgendaDayHeader?: (date: Date, info: EventAgendaListDayInfo<E>) => ReactNode;
     messages?: MacroCalendarMessages;
     /** Status values that cannot be dragged. Default: `['archived']`. */
     immutableStatuses?: Status[];
+    /** Extra guard for moving/resizing an event. Composed (AND) with `immutableStatuses`. */
+    eventAllow?: (event: E, startAt: string, endAt: string) => boolean;
+    /** Height passed to FullCalendar. Default: `'100%'` (requires a sized parent). */
+    height?: number | string;
+    /** Duration of the just-created/moved highlight flash, in ms. Default: `650`. */
+    highlightDurationMs?: number;
+    /** Time-grid row height as `HH:mm:ss`. Default: `'00:30:00'`. */
+    slotDuration?: string;
+    /**
+     * Drag/resize granularity as `HH:mm:ss`. Default: `'00:15:00'`. Values below
+     * 5 min may feel nervous when dragging.
+     */
+    snapDuration?: string;
     className?: string;
 }
-declare const MacroCalendar: <Status extends string, E extends BaseCalendarEvent<Status>>({ events, activeView, selectedDate, highlightEventIds, onDeleteEvent, onEditEvent, onEventTimeChange, onDateClick, onDateSelected, onVisibleRangeChange, onSwitchToDay, locale, fullCalendarLocale, firstDay, statusLabels, renderEventMeta, messages, immutableStatuses, className, }: MacroCalendarProps<Status, E>) => react_jsx_runtime.JSX.Element;
+declare const MacroCalendar: <Status extends string, E extends BaseCalendarEvent<Status>>({ events, activeView, selectedDate, highlightEventIds, onDeleteEvent, onEditEvent, onEventTimeChange, onDateClick, onDateSelected, onVisibleRangeChange, onSwitchToDay, locale, fullCalendarLocale, firstDay, availability, statusLabels, renderEventMeta, renderDayHeader, renderAgendaDayHeader, messages, immutableStatuses, eventAllow, height, highlightDurationMs, slotDuration, snapDuration, className, }: MacroCalendarProps<Status, E>) => react_jsx_runtime.JSX.Element;
 
 interface MiniMonthCalendarMessages {
     previousMonth?: string;
@@ -139,16 +255,33 @@ declare const MiniMonthCalendar: <Status extends string = string>({ selectedDate
 interface CalendarToolbarMessages {
     groupAriaLabel?: string;
     newEvent?: string;
+    today?: string;
+    previous?: string;
+    next?: string;
     views?: Partial<Record<CalendarView, string>>;
 }
 interface CalendarToolbarProps {
     activeView: CalendarView;
     onChangeView: (view: CalendarView) => void;
+    /**
+     * View buttons to show, in order. Default: `['month', 'week', 'list']`. The
+     * `week` button represents the day/week time grid (it stays active in `day`
+     * view too); `day` itself is reached via the "Hoy" control, not a button.
+     */
+    views?: CalendarView[];
+    /** Emits a navigation intent. Wire with `shiftDate(selectedDate, activeView, dir)`. */
+    onNavigate?: (direction: CalendarNavDirection) => void;
+    /** Highlights the "Hoy" button as active (e.g. day view focused on today). */
+    todayActive?: boolean;
+    /** Current period label (e.g. "Mayo 2026") rendered next to the nav controls. */
+    periodLabel?: ReactNode;
+    /** Slot for consumer-owned filters (status, regional…). Rendered between nav and views. */
+    filtersSlot?: ReactNode;
     onNewEvent?: () => void;
     messages?: CalendarToolbarMessages;
     className?: string;
 }
-declare const CalendarToolbar: ({ activeView, onChangeView, onNewEvent, messages, className, }: CalendarToolbarProps) => react_jsx_runtime.JSX.Element;
+declare const CalendarToolbar: ({ activeView, onChangeView, views, onNavigate, todayActive, periodLabel, filtersSlot, onNewEvent, messages, className, }: CalendarToolbarProps) => react_jsx_runtime.JSX.Element;
 
 interface EventChipPopoverMessages {
     edit?: string;
@@ -201,6 +334,53 @@ interface EventBlockContentProps<Status extends string, E extends BaseCalendarEv
 }
 declare const EventBlockContent: <Status extends string, E extends BaseCalendarEvent<Status>>({ event, onEdit, onDelete, locale, statusLabels, messages, }: EventBlockContentProps<Status, E>) => react_jsx_runtime.JSX.Element;
 
+interface EventTypeFilterItem {
+    id: string;
+    label: string;
+    /** Optional leading icon. When omitted, a colored dot is shown. */
+    icon?: ReactNode;
+    /** Optional dot color (any CSS color). Used when `icon` is absent. */
+    color?: string;
+    /** Optional count shown on the right (e.g. number of events of this type). */
+    count?: number;
+}
+interface EventTypeFilterListProps {
+    items: EventTypeFilterItem[];
+    /** Currently selected item ids. An empty array means "all". */
+    selectedIds: string[];
+    onToggle: (id: string) => void;
+    className?: string;
+}
+/**
+ * Sidebar list to filter events by type, with optional counts (as in the
+ * agenda designs). A building block — not a layout wrapper. The consumer owns
+ * the actual filtering and the surrounding sidebar.
+ */
+declare const EventTypeFilterList: ({ items, selectedIds, onToggle, className, }: EventTypeFilterListProps) => react_jsx_runtime.JSX.Element;
+
+interface StatusFilterOption<Status extends string> {
+    status: Status;
+    label: string;
+    /** Optional dot color (any CSS color). */
+    color?: string;
+}
+interface StatusFilterSelectProps<Status extends string> {
+    options: StatusFilterOption<Status>[];
+    /** Currently selected statuses. An empty array means "all". */
+    selected: Status[];
+    onToggle: (status: Status) => void;
+    /** Always-visible trigger label. Default: `"Estado del evento"`. */
+    placeholder?: string;
+    className?: string;
+}
+/**
+ * Multi-select dropdown to filter events by status (the "Estado del evento"
+ * control in the toolbar). The placeholder stays visible at all times; a count
+ * badge reflects how many statuses are active. Generic over the consumer's
+ * status union — emits toggle intents, the consumer owns the filtering.
+ */
+declare const StatusFilterSelect: <Status extends string>({ options, selected, onToggle, placeholder, className, }: StatusFilterSelectProps<Status>) => react_jsx_runtime.JSX.Element;
+
 interface MoreEventsPopoverMessages {
     header?: (count: number) => string;
     editAria?: (title: string) => string;
@@ -269,9 +449,13 @@ declare const EventStatusBadge: <Status extends string = string>({ status, label
 interface EventTypeChipProps {
     label: string;
     icon?: ReactNode;
+    /** When provided, renders a ✕ button that fires this callback (e.g. clear the filter). */
+    onRemove?: () => void;
+    /** Accessible label for the remove button. Default: `"Remove"`. */
+    removeLabel?: string;
     className?: string;
 }
-declare const EventTypeChip: ({ label, icon, className }: EventTypeChipProps) => react_jsx_runtime.JSX.Element;
+declare const EventTypeChip: ({ label, icon, onRemove, removeLabel, className, }: EventTypeChipProps) => react_jsx_runtime.JSX.Element;
 
 interface EmptyEventsStateProps {
     title?: string;
@@ -288,7 +472,7 @@ declare const PopoverPortal: react.FC<PopoverPrimitive.PopoverPortalProps>;
 declare const PopoverClose: react.ForwardRefExoticComponent<PopoverPrimitive.PopoverCloseProps & react.RefAttributes<HTMLButtonElement>>;
 declare const PopoverContent: react.ForwardRefExoticComponent<Omit<PopoverPrimitive.PopoverContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 
-type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost';
 type ButtonSize = 'sm' | 'md' | 'lg';
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
@@ -299,8 +483,86 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
 }
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
+interface SelectOption<T extends string> {
+    value: T;
+    label: string;
+    /** Optional dot color (any CSS color). Used when `icon` is absent. */
+    color?: string;
+    /** Optional leading icon. Takes precedence over `color`. */
+    icon?: ReactNode;
+}
+interface SelectBaseProps<T extends string> {
+    /** Always-visible label on the trigger (never replaced by the selection). */
+    placeholder: string;
+    options: SelectOption<T>[];
+    align?: 'start' | 'center' | 'end';
+    className?: string;
+    'aria-label'?: string;
+}
+interface SelectSingleProps<T extends string> extends SelectBaseProps<T> {
+    multiple?: false;
+    value: T | null;
+    onChange: (value: T | null) => void;
+    /** Re-clicking the active option clears it. Default: `true`. */
+    clearable?: boolean;
+}
+interface SelectMultipleProps<T extends string> extends SelectBaseProps<T> {
+    multiple: true;
+    /** Selected values. Empty means "all" — the consumer owns the filtering. */
+    value: T[];
+    onToggle: (value: T) => void;
+}
+type SelectProps<T extends string> = SelectSingleProps<T> | SelectMultipleProps<T>;
+/**
+ * Popover-backed listbox dropdown. The trigger keeps `placeholder` visible at
+ * all times; multi mode shows a count badge, single mode appends the chosen
+ * label. Built on the {@link Popover} primitive (no extra Radix deps). Generic
+ * over the consumer's value union — emits intents, never owns selection state.
+ */
+declare const Select: <T extends string>(props: SelectProps<T>) => react_jsx_runtime.JSX.Element;
+
 declare const APE_CALENDAR_ROOT_CLASS = "ape-calendar";
 
+interface UseCalendarControllerOptions {
+    /** View the calendar starts on. Default: `'week'`. */
+    initialView?: CalendarView;
+    /** Date the calendar starts on. Default: now. */
+    initialDate?: Date;
+    /** First day of the week (0=Sunday … 6=Saturday). Default: `1`. */
+    firstDay?: number;
+    /** BCP-47 locale used to build {@link CalendarController.periodLabel}. Default: `'es-CO'`. */
+    locale?: string;
+}
+interface CalendarController {
+    activeView: CalendarView;
+    selectedDate: Date;
+    /** Last range reported by the calendar (kept in sync via `onVisibleRangeChange`). */
+    visibleRange: CalendarVisibleRange;
+    /** Localized label for the current period — spread onto `CalendarToolbar.periodLabel`. */
+    periodLabel: string;
+    /** True when the "Hoy" control is the active state (day view on today). */
+    todayActive: boolean;
+    onChangeView: (view: CalendarView) => void;
+    onNavigate: (direction: CalendarNavDirection) => void;
+    onSelectDate: (date: Date) => void;
+    onVisibleRangeChange: (start: Date, end: Date) => void;
+    onToday: () => void;
+    setActiveView: (view: CalendarView) => void;
+    setSelectedDate: (date: Date) => void;
+}
+/**
+ * Encapsulates the calendar's view/date state and the opinionated navigation
+ * behavior so every portal behaves identically:
+ *
+ * - "Hoy" jumps to today in day view (re-pressing it falls back to week).
+ * - Picking a day from the month or list view opens that day's week.
+ * - prev/next step by the current view (via {@link shiftDate}).
+ *
+ * The calendar stays fully controlled — this hook owns the consumer-side state
+ * and returns handlers to spread onto `CalendarToolbar` and `MacroCalendar`.
+ */
+declare const useCalendarController: ({ initialView, initialDate, firstDay, locale, }?: UseCalendarControllerOptions) => CalendarController;
+
 declare const toDayKey: (date: Date) => DayKey;
 declare const isSameDay: (left: Date, right: Date) => boolean;
 /**
@@ -326,5 +588,35 @@ declare const formatDurationLabel: (durationMinutes: number, messages?: {
     min?: string;
     h?: string;
 }) => string;
+/**
+ * Maps an {@link AvailabilitySchedule} to FullCalendar's `businessHours` input.
+ * Useful when a consumer wants to constrain selection/dragging to the available
+ * window. Note: FullCalendar shades the NON-business area when this is set —
+ * for the colored "horario de atención" band use {@link mapAvailabilityToBackgroundEvents}.
+ */
+declare const mapAvailabilityToBusinessHours: (schedule: AvailabilitySchedule) => BusinessHoursInput;
+/**
+ * Maps an {@link AvailabilitySchedule} to recurring FullCalendar background
+ * events, used to paint the colored availability band in time-grid views. The
+ * band color is driven by the `cal-availability-band` class (CSS var
+ * `--cal-availability-bg`) so it stays themeable.
+ */
+declare const mapAvailabilityToBackgroundEvents: (schedule: AvailabilitySchedule) => EventInput[];
+/**
+ * Returns the half-open `[start, end)` range of the week that contains `date`.
+ * `firstDay` follows the same convention as FullCalendar (0=Sunday … 6=Saturday).
+ * Start is set to midnight of the week's first day; end is midnight 7 days later.
+ * Used by the agenda list to derive its visible window from `selectedDate`.
+ */
+declare const getWeekRange: (date: Date, firstDay?: number) => {
+    start: Date;
+    end: Date;
+};
+/**
+ * Returns the date a calendar should jump to when the user navigates one step
+ * in the given view. `today` always resolves to now. Used by the toolbar's
+ * prev/next/today controls (the calendar is date-controlled by the consumer).
+ */
+declare const shiftDate: (date: Date, view: CalendarView, direction: CalendarNavDirection) => Date;
 
-export { APE_CALENDAR_ROOT_CLASS, type BaseCalendarEvent, Button, type ButtonProps, type ButtonSize, type ButtonVariant, CalendarToolbar, type CalendarToolbarMessages, type CalendarToolbarProps, type CalendarUpdateSource, type CalendarView, type CalendarVisibleRange, DayEventDot, type DayEventDotProps, type DayKey, type DefaultEventStatus, EmptyEventsState, type EmptyEventsStateProps, EventBlockContent, type EventBlockContentMessages, type EventBlockContentProps, EventChipMonth, type EventChipMonthProps, EventChipPopover, type EventChipPopoverMessages, type EventChipPopoverProps, EventStatusBadge, type EventStatusBadgeProps, type EventTimeChangePayload, EventTypeChip, type EventTypeChipProps, MacroCalendar, type MacroCalendarMessages, type MacroCalendarProps, MiniMonthCalendar, type MiniMonthCalendarMessages, type MiniMonthCalendarProps, MoreEventsPopover, type MoreEventsPopoverMessages, type MoreEventsPopoverProps, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverPortal, PopoverTrigger, type SlotAction, type SlotActionPayload, type SlotActionState, SlotContextActions, type SlotContextActionsMessages, type SlotContextActionsProps, formatDurationLabel, formatHourLabel, getEventDayKeys, getEventDayStatuses, isSameDay, mapEventToCalendarInput, toDayKey };
+export { APE_CALENDAR_ROOT_CLASS, type AvailabilitySchedule, type AvailabilitySlot, type BaseCalendarEvent, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CalendarController, type CalendarNavDirection, CalendarToolbar, type CalendarToolbarMessages, type CalendarToolbarProps, type CalendarUpdateSource, type CalendarView, type CalendarVisibleRange, DayEventDot, type DayEventDotProps, type DayKey, type DefaultEventStatus, EmptyEventsState, type EmptyEventsStateProps, EventAgendaList, type EventAgendaListDayInfo, type EventAgendaListMessages, type EventAgendaListProps, EventBlockContent, type EventBlockContentMessages, type EventBlockContentProps, EventChipMonth, type EventChipMonthProps, EventChipPopover, type EventChipPopoverMessages, type EventChipPopoverProps, EventListRow, type EventListRowMessages, type EventListRowProps, EventStatusBadge, type EventStatusBadgeProps, type EventTimeChangePayload, EventTypeChip, type EventTypeChipProps, type EventTypeFilterItem, EventTypeFilterList, type EventTypeFilterListProps, MacroCalendar, type MacroCalendarMessages, type MacroCalendarProps, MiniMonthCalendar, type MiniMonthCalendarMessages, type MiniMonthCalendarProps, MoreEventsPopover, type MoreEventsPopoverMessages, type MoreEventsPopoverProps, Popover, PopoverAnchor, PopoverClose, PopoverContent, PopoverPortal, PopoverTrigger, Select, type SelectMultipleProps, type SelectOption, type SelectProps, type SelectSingleProps, type SlotAction, type SlotActionPayload, type SlotActionState, SlotContextActions, type SlotContextActionsMessages, type SlotContextActionsProps, type StatusFilterOption, StatusFilterSelect, type StatusFilterSelectProps, type UseCalendarControllerOptions, formatDurationLabel, formatHourLabel, getEventDayKeys, getEventDayStatuses, getWeekRange, isSameDay, mapAvailabilityToBackgroundEvents, mapAvailabilityToBusinessHours, mapEventToCalendarInput, shiftDate, toDayKey, useCalendarController };