@ilamy/calendar 1.8.1 → 2.0.1

package/dist/plugins/agenda.d.ts

@@ -0,0 +1,349 @@
+import { ComponentType, ReactNode as ReactNode2 } from "react";
+import { Dayjs as Dayjs2, ManipulateType as ManipulateType2 } from "dayjs";
+/**
+* Core calendar event interface representing a single calendar event.
+* This is the primary data structure for calendar events.
+*/
+interface CalendarEvent {
+	/** Unique identifier for the event */
+	id: string | number;
+	/** Display title of the event */
+	title: string;
+	/** Start date and time of the event */
+	start: Dayjs2;
+	/** End date and time of the event */
+	end: Dayjs2;
+	/**
+	* Color for the event (supports CSS color values, hex, rgb, hsl, or CSS class names)
+	* @example "#3b82f6", "blue-500", "rgb(59, 130, 246)"
+	*/
+	color?: string;
+	/**
+	* Background color for the event (supports CSS color values, hex, rgb, hsl, or CSS class names)
+	* @example "#dbeafe", "blue-100", "rgba(59, 130, 246, 0.1)"
+	*/
+	backgroundColor?: string;
+	/** Optional description or notes for the event */
+	description?: string;
+	/** Optional location where the event takes place */
+	location?: string;
+	/**
+	* Whether this is an all-day event
+	* @default false
+	*/
+	allDay?: boolean;
+	/**
+	* UID for iCalendar compatibility
+	* Unique identifier across calendar systems
+	*/
+	uid?: string;
+	/** Single resource assignment */
+	resourceId?: string | number;
+	/** Multiple resource assignment (cross-resource events) */
+	resourceIds?: (string | number)[];
+	/**
+	* Custom data associated with the event
+	* Use this to store additional metadata specific to your application
+	* @example { meetingType: 'standup', attendees: ['john', 'jane'] }
+	*/
+	data?: Record<string, unknown>;
+}
+/**
+* Supported days of the week for calendar configuration.
+* Used for setting the first day of the week and other week-related settings.
+*/
+type WeekDays = "sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday";
+/**
+* Configuration for business hours.
+* Defines the working hours to be highlighted on the calendar.
+*/
+interface BusinessHours {
+	/**
+	* Days of the week to apply business hours to.
+	* @default ['monday', 'tuesday', 'wednesday', 'thursday', 'friday']
+	*/
+	daysOfWeek?: WeekDays[];
+	/**
+	* Start time for business hours in 24-hour format (0-24).
+	* @default 9
+	*/
+	startTime?: number;
+	/**
+	* End time for business hours in 24-hour format (0-24).
+	* @default 17
+	*/
+	endTime?: number;
+}
+/**
+* Resource interface representing a calendar resource (person, room, equipment, etc.)
+*/
+interface Resource {
+	/** Unique identifier for the resource */
+	id: string | number;
+	/** Display title of the resource */
+	title: string;
+	/**
+	* Color for the resource (supports CSS color values, hex, rgb, hsl, or CSS class names)
+	* @example "#3b82f6", "blue-500", "rgb(59, 130, 246)"
+	*/
+	color?: string;
+	/**
+	* Background color for the resource (supports CSS color values, hex, rgb, hsl, or CSS class names)
+	* @example "#dbeafe", "blue-100", "rgba(59, 130, 246, 0.1)"
+	*/
+	backgroundColor?: string;
+	/**
+	* Configuration for resource-specific business hours.
+	* If provided, these will be used instead of the global business hours for this resource.
+	*/
+	businessHours?: BusinessHours | BusinessHours[];
+	/**
+	* Custom data associated with the resource
+	* Use this to store additional metadata specific to your application
+	* @example { avatar: 'https://example.com/avatar.png', role: 'admin' }
+	*/
+	data?: Record<string, unknown>;
+}
+interface PluginDateRange {
+	start: Dayjs2;
+	end: Dayjs2;
+}
+interface PluginMutationArgs {
+	event: CalendarEvent;
+	updates?: Partial<CalendarEvent>;
+	currentEvents: CalendarEvent[];
+	scope: unknown;
+}
+/** Structured result from `applyEdit` when a mutation updates multiple stored rows. */
+interface PluginMutationResult {
+	events: CalendarEvent[];
+	/** Existing rows to persist via `onEventUpdate`. */
+	updated: CalendarEvent[];
+	/** New rows to persist via `onEventAdd`. */
+	added: CalendarEvent[];
+	/** Existing rows to persist via `onEventDelete`. */
+	deleted: CalendarEvent[];
+}
+/**
+* Calendar configuration handed to a view's `columns()`/`renderHeader()`.
+* Carries the resource axis (`resources`, `orientation`) so a resource-capable
+* view can compose both arrangements. `range()` receives only the
+* `firstDayOfWeek` slice (see its own signature).
+*/
+interface ViewConfig {
+	firstDayOfWeek: number;
+	hiddenDays?: Set<number>;
+	businessHours?: BusinessHours | BusinessHours[];
+	hideNonBusinessHours?: boolean;
+	/** The resource axis. Set only when the calendar renders resources. */
+	resources?: Resource[];
+	/**
+	* The calendar-level resource arrangement (the user's choice): where the
+	* resource axis goes. Only meaningful when `resources` is set.
+	*/
+	orientation?: "vertical" | "horizontal";
+	/**
+	* Week-view granularity when `resources` is set: 'hourly' (default) nests
+	* hour slots under each day; 'daily' shows one cell per day.
+	*/
+	weekViewGranularity?: "hourly" | "daily";
+}
+/**
+* One column of a 'vertical' view (time flows down the column).
+* Formalizes the calendar's existing VerticalGrid column input.
+*/
+interface VerticalColumnSpec {
+	/** Stable column id; drives testids and React keys. */
+	id: string;
+	/** The date this column represents; gutter/label columns leave it unset. */
+	day?: Dayjs2;
+	/** The cells of the column: hour slots (gridType 'hour') or dates ('day'). */
+	days: Dayjs2[];
+	gridType?: "day" | "hour";
+	className?: string;
+	/** Label-only column (e.g. the time gutter): renders no events. */
+	noEvents?: boolean;
+	renderCell?: (date: Dayjs2) => ReactNode2;
+	/**
+	* Resource-axis identity when the column belongs to one resource. The
+	* single carrier: consumers derive the id from `resource.id`.
+	*/
+	resource?: Resource;
+}
+/** One cell of a 'horizontal' row. */
+interface HorizontalCellSpec {
+	id: string;
+	day?: Dayjs2;
+	/** A grouped cell spanning several dates (nested-axis arrangements). */
+	days?: Dayjs2[];
+	gridType: "day" | "hour";
+	className?: string;
+}
+/**
+* One row of a 'horizontal' view (date cells flow across the row).
+* Formalizes the calendar's existing HorizontalGrid row input.
+*/
+interface HorizontalRowSpec {
+	/** Stable row id; drives testids and React keys (matches VerticalColumnSpec.id). */
+	id: string;
+	columns?: HorizontalCellSpec[];
+	className?: string;
+	showDayNumber?: boolean;
+	/** Resource-axis identity when the row belongs to one resource. */
+	resource?: Resource;
+}
+/** Context passed to a view's `renderHeader`. */
+interface ViewHeaderContext {
+	date: Dayjs2;
+	config: ViewConfig;
+}
+/**
+* Describes a view type — contributed by a plugin or built into the calendar
+* core (the four built-ins are themselves `PluginView` entries). A view either
+* declares `columns` + `layout` and renders through the shared grid engines,
+* or renders entirely through `component` (the escape hatch).
+*/
+interface PluginView {
+	/** Unique view id, e.g. 'resource-week'. */
+	name: string;
+	/** View-switcher label (or a translation key; unknown keys render as-is). */
+	label?: string;
+	/**
+	* View-switcher icon (a component taking `className`, e.g. a lucide icon).
+	* Always shown in the switcher; the label appears beside it only when the
+	* view is selected, and as a hover tooltip otherwise.
+	*/
+	icon: ComponentType<{
+		className?: string;
+	}>;
+	/**
+	* The escape hatch: renders the whole view when `columns`/`layout` are
+	* absent. Spec-driven views omit it. A view with neither renders nothing
+	* (dev builds log a warning).
+	*/
+	component?: ComponentType;
+	/** How far prev/next steps when `navigationStep` is absent ('week', 'month', …). */
+	navigationUnit?: ManipulateType2;
+	/**
+	* How far prev/next jumps; defaults to one `navigationUnit`. Custom-duration
+	* views (a 40-day grid, a 4-day vertical view) set `{ amount: 40, unit: 'day' }`
+	* so navigation moves a full window.
+	*
+	* This also selects the header title/date-picker form (the core derives it
+	* generically, never by view name): a single `day`/`week`/`month`/`year` step
+	* borrows that grid's picker and title; any other step (amount > 1, or a custom
+	* unit) shows the day picker over the view's `range`. A third-party view gets
+	* the right picker for free just by declaring how it navigates.
+	*/
+	navigationStep?: {
+		amount: number;
+		unit: ManipulateType2;
+	};
+	/**
+	* Visible range for navigation callbacks and the event pipeline. Views
+	* without `range` fall back to the month 6x7 grid range. Receives only the
+	* `firstDayOfWeek` slice of the config; the full axis config reaches
+	* `columns()`/`renderHeader()`.
+	*/
+	range?: (date: Dayjs2, config: Pick<ViewConfig, "firstDayOfWeek">) => {
+		start: Dayjs2;
+		end: Dayjs2;
+	};
+	/**
+	* Column/row specs for the shared renderer. Return `VerticalColumnSpec[]`
+	* when `layout` is 'vertical', `HorizontalRowSpec[]` when 'horizontal'.
+	* Omit (together with `layout`) to render `component` instead.
+	*/
+	columns?: (date: Dayjs2, config: ViewConfig) => VerticalColumnSpec[] | HorizontalRowSpec[];
+	/**
+	* The view's intrinsic shape (the author's choice): which engine renders it
+	* when the calendar has NO resources. 'vertical' = time flows down;
+	* 'horizontal' = date cells flow across in stacked rows. With resources on
+	* a resource-capable view, the calendar-level `orientation` wins instead:
+	* `engine = resources && supportsResources ? orientation : layout`.
+	*/
+	layout?: "vertical" | "horizontal";
+	/** Header row content rendered above the grid by the shared renderer. */
+	renderHeader?: (ctx: ViewHeaderContext) => ReactNode2;
+	/**
+	* Whether `columns()` composes the resource axis when `config.resources`
+	* is set. Defaults to false; the view switcher hides resource-incapable
+	* views on a resource calendar.
+	*/
+	supportsResources?: boolean;
+}
+/**
+* A calendar plugin contributes optional behavior and UI through generic hooks
+* named after pipeline moments and mount points, never after a feature. The
+* core stays agnostic of any specific plugin (e.g. recurrence).
+*
+* Hooks follow the Rollup/Vite execution kinds:
+* - `transformEvents` is sequential: each plugin receives the previous
+*   plugin's output, forming a transform chain.
+* - `managesEvent` is first-match: the first plugin whose managesEvent returns
+*   true owns its scoped mutations.
+* - `renderSlot` is additive: every plugin may contribute to a mount point.
+*
+* `slotName` is an opaque string identifier and `context` is opaque to the
+* core. The built-in slot names and their context shapes live in the calendar
+* core, which this contract does NOT depend on, so adding a slot never changes
+* this interface. A plugin narrows `context` by `slotName` at its boundary.
+*
+* `scope` is opaque to the core: the owner produces it (via the mutation-scope
+* slot) and consumes it in `applyEdit` / `applyDelete`. A plugin that provides
+* `applyEdit` / `applyDelete` should also render the mutation-scope slot so the
+* core can gather that scope before mutating.
+*/
+interface IlamyPlugin {
+	name: string;
+	transformEvents?: (events: CalendarEvent[], range: PluginDateRange) => CalendarEvent[];
+	managesEvent?: (event: CalendarEvent) => boolean;
+	applyEdit?: (args: PluginMutationArgs) => CalendarEvent[] | PluginMutationResult;
+	applyDelete?: (args: PluginMutationArgs) => CalendarEvent[] | PluginMutationResult;
+	renderSlot?: (slotName: string, context: unknown) => ReactNode2;
+	/**
+	* Contributes arbitrary data to a named point. Additive: all plugins may
+	* contribute to the same point; the runtime aggregates all results via
+	* `collect`. Parallel to `renderSlot` but for data rather than UI nodes.
+	*/
+	contribute?: (point: string, context: unknown) => unknown[];
+	/**
+	* Registers new view types that the calendar can switch to. Each entry in
+	* the array describes one view (id, component, navigation unit, …).
+	*/
+	views?: PluginView[];
+	/**
+	* Wraps the calendar subtree so the plugin's own React context is available
+	* to its views, slots, and components. Rendered as the outermost wrapper
+	* among all plugin providers.
+	*/
+	provider?: ComponentType<{
+		children: ReactNode2;
+	}>;
+}
+/**
+* The date window the agenda lists (and that prev/next steps over).
+*
+* A named period is the calendar period *containing* the reference date, so it
+* can extend backward to the period's start (e.g. 'month' on the 14th lists from
+* the 1st) and stays aligned with the matching grid view and header label. A
+* number is a rolling window of that many days starting *at* the reference date
+* and counting forward (e.g. 8 on the 14th lists the 14th–21st) — there is no
+* calendar boundary to anchor it to, so it does not look backward.
+*/
+type AgendaWindow = "day" | "week" | "month" | number;
+interface AgendaViewOptions {
+	/**
+	* The date window the agenda lists and that prev/next steps over. Default 'month'.
+	* A named period ('day' | 'week' | 'month') is the calendar period *containing*
+	* the current date, so it can include earlier days of that period (and aligns
+	* with the matching grid view + header label). A number is a rolling window of
+	* that many days starting *at* the current date and counting forward.
+	*/
+	window?: AgendaWindow;
+}
+/** Builds the agenda `PluginView` for the given window. */
+declare const createAgendaView: ({ window }?: AgendaViewOptions) => PluginView;
+/** Opt-in agenda plugin: registers the `agenda` view. Pass to `IlamyCalendar`'s `plugins`. */
+declare const agendaPlugin: (options?: AgendaViewOptions) => IlamyPlugin;
+export { createAgendaView, agendaPlugin, AgendaWindow, AgendaViewOptions };

package/dist/plugins/agenda.js

@@ -0,0 +1 @@
+import{I as s,K as J}from"../shared/chunk-a9j9sahk.js";import{L as $}from"../shared/chunk-jfadfww5.js";import{List as w}from"lucide-react";import{createElement as y}from"react";import{useIlamyCalendarContext as d}from"@ilamy/calendar";import*as b from"@radix-ui/react-scroll-area";import{jsx as z,jsxs as S}from"react/jsx-runtime";function V({className:l,children:r,viewPortProps:c,...f}){return S(b.Root,{className:s("relative",l),"data-slot":"scroll-area",...f,children:[z(b.Viewport,{...c,className:s("focus-visible:ring-ring/50 size-full rounded-[inherit] transition-[color,box-shadow] outline-none focus-visible:ring-[3px] focus-visible:outline-1",c?.className),"data-slot":"scroll-area-viewport",children:r}),z(k,{}),z(b.Corner,{})]})}function k({className:l,orientation:r="vertical",...c}){return z(b.ScrollAreaScrollbar,{className:s("flex touch-none p-px transition-colors select-none",r==="vertical"&&"h-full w-2.5 border-l border-l-transparent",r==="horizontal"&&"h-2.5 flex-col border-t border-t-transparent",l),"data-slot":"scroll-area-scrollbar",orientation:r,...c,children:z(b.ScrollAreaThumb,{className:"bg-border relative flex-1 rounded-full","data-slot":"scroll-area-thumb"})})}var R={day:(l)=>({start:l.startOf("day"),end:l.endOf("day")}),week:(l,r)=>{let c=(l.day()-r+7)%7,f=l.subtract(c,"day").startOf("day");return{start:f,end:f.add(6,"day").endOf("day")}},month:(l)=>({start:l.startOf("month"),end:l.endOf("month")})},u={day:{amount:1,unit:"day"},week:{amount:1,unit:"week"},month:{amount:1,unit:"month"}},q=(l,r,c=0)=>{if(typeof r==="number")return{start:l.startOf("day"),end:l.add(r-1,"day").endOf("day")};return R[r](l,c)},Y=(l)=>{if(typeof l==="number")return{amount:l,unit:"day"};return u[l]};var I=(l,r,c)=>{if(l.allDay)return l.start.isSameOrBefore(c)&&l.end.isSameOrAfter(r);return l.start.isSameOrAfter(r)&&l.start.isSameOrBefore(c)},E=(l,r)=>{let c=l.allDay?0:1,f=r.allDay?0:1;if(c!==f)return c-f;return l.start.valueOf()-r.start.valueOf()},Z=(l,r)=>{let c=[],f=r.end.startOf("day"),m=r.start.startOf("day");while(m.isSameOrBefore(f)){let i=m.startOf("day"),h=m.endOf("day"),N=l.filter((x)=>I(x,i,h)).sort(E);if(N.length>0)c.push({key:m.format("YYYY-MM-DD"),date:i,events:N});m=m.add(1,"day")}return c};import{useIlamyCalendarContext as g}from"@ilamy/calendar";import{memo as C}from"react";import{jsx as P,jsxs as _,Fragment as j}from"react/jsx-runtime";var D=({rangeStart:l,rangeEnd:r,now:c,axis:f="vertical",render:m,withDot:i=!0})=>{let h=c??$(),N=h.valueOf();if(!(N>=l.valueOf()&&N<r.valueOf()))return null;let x=r.diff(l,"minute"),o=h.diff(l,"minute")/x*100;if(m)return P(j,{children:m({currentTime:h,rangeStart:l,rangeEnd:r,progress:o,axis:f})});if(f==="horizontal")return _("div",{className:"absolute top-0 bottom-0 z-50 flex -translate-x-1/2 flex-col items-center pointer-events-none","data-testid":"current-time-indicator",style:{left:`${o}%`},children:[i&&P("div",{className:"size-2 shrink-0 rounded-full bg-red-500"}),P("div",{className:"w-0.5 flex-1 bg-red-500"})]});return _("div",{className:"absolute right-0 left-0 z-50 flex -translate-y-1/2 items-center pointer-events-none","data-testid":"current-time-indicator",style:{top:`${o}%`},children:[i&&P("div",{className:"size-2 shrink-0 rounded-full bg-red-500"}),P("div",{className:"h-0.5 flex-1 bg-red-500"})]})},F=C(D);import{jsx as G,jsxs as p}from"react/jsx-runtime";var O=({today:l,dayNumber:r,weekday:c,className:f,"data-testid":m})=>{return p("div",{className:s("flex flex-col items-center",f),"data-testid":m,"data-today":l?"true":void 0,children:[c!=null&&G("div",{className:s("w-full truncate text-center text-xs text-muted-foreground",l&&"text-primary"),children:c}),G("div",{className:s("flex h-5 w-5 shrink-0 items-center justify-center rounded-full text-xs font-medium",l&&"bg-primary text-primary-foreground"),children:r})]})};import{useIlamyCalendarContext as v}from"@ilamy/calendar";import{jsx as H,jsxs as a}from"react/jsx-runtime";var t=(l)=>l==="24-hour"?"HH:mm":"h:mm A",L=({event:l,day:r})=>{let{t:c,timeFormat:f,onEventClick:m}=v(),i=l.start.format(t(f)),h=l.allDay?c("allDay"):i,N=l.start.startOf("day"),x=l.end.startOf("day").diff(N,"day")+1,o=r.startOf("day").diff(N,"day")+1,W=Boolean(l.allDay)&&x>1,A=`(${c("day")} ${o}/${x})`,U=W?A:null;return a("button",{className:"hover:bg-accent flex w-full cursor-pointer items-center gap-2 rounded px-2 py-1 text-left text-sm",onClick:()=>m(l),type:"button",children:[H("span",{className:"text-muted-foreground w-20 shrink-0",children:h}),H("span",{className:s("size-3 shrink-0 rounded-full border",l.backgroundColor||"bg-blue-500",l.color),style:{backgroundColor:l.backgroundColor}}),H("span",{className:"truncate",children:l.title}),U&&H("span",{className:"text-muted-foreground shrink-0 text-xs",children:U})]})};import{jsx as Q,jsxs as M}from"react/jsx-runtime";var B=({group:l})=>{let{view:r,renderCurrentTimeIndicator:c}=g(),f=l.date.isSame($(),"day"),m;if(c)m=(i)=>c({...i,view:r});return M("div",{className:"flex gap-4 border-b px-2 py-3","data-testid":J("agenda-day",l.key),children:[Q("div",{className:"text-muted-foreground flex w-16 shrink-0 flex-col items-center text-center",children:Q(O,{className:"flex-col-reverse",dayNumber:l.date.format("D"),today:f,weekday:l.date.format("ddd")})}),M("div",{className:"relative flex flex-1 flex-col gap-1",children:[f&&Q(F,{rangeEnd:l.date.endOf("day"),rangeStart:l.date.startOf("day"),render:m}),l.events.map((i)=>Q(L,{day:l.date,event:i},J(l.key,i.id)))]})]})};import{jsx as X}from"react/jsx-runtime";var T=({window:l})=>{let{currentDate:r,getEventsForDateRange:c,t:f,firstDayOfWeek:m}=d(),i=q(r,l,m),h=c(i.start,i.end),N=Z(h,i);if(N.length===0)return X("div",{className:"text-muted-foreground flex h-full items-center justify-center p-4 text-sm","data-testid":"agenda-empty",children:f("agendaNoEvents")});return X(V,{className:"h-full","data-testid":"agenda-view",children:X("div",{className:"flex flex-col",children:N.map((x)=>X(B,{group:x},x.key))})})};var K=({window:l="month"}={})=>({name:"agenda",label:"agenda",icon:w,navigationStep:Y(l),range:(r,c)=>q(r,l,c.firstDayOfWeek),supportsResources:!1,component:()=>y(T,{window:l})});var n=(l={})=>({name:"agenda",views:[K(l)]});export{K as createAgendaView,n as agendaPlugin};