@gridui/calendar 0.0.0-stage → 0.0.0

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# @gridui/calendar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Composable scheduling views. The family has no provider requirement and no dependency on DatePicker or Grid. Applications own events, timezone conversion, editing, resource filtering and persistence.
+
+```tsx
+import "@gridui/theme/styles.css";
+import "@gridui/button/styles.css";
+import "@gridui/calendar/styles.css";
+
+import { Calendar, CalendarDayView, CalendarToolbar, useCalendar } from "@gridui/calendar";
+
+const state = useCalendar({ defaultDate: "2026-11-02" });
+
+<Calendar frame="outline">
+    <CalendarToolbar
+        date={state.date}
+        view={state.view}
+        onNavigate={state.navigate}
+        onViewChange={state.setView}
+        views={["day"]}
+    />
+    <CalendarDayView
+        date={state.date}
+        events={events}
+        resources={resources}
+        onEventSelect={openEditor}
+    />
+</Calendar>;
+```
+
+## Components
+
+- `Calendar` is an optional surface. `frame="none"` is the default; `outline` adds one outer border. It adds no seams between children.
+- `CalendarDayView` displays one date. Optional `resources` create one column per declared resource; without resources all events share one column. When resources are supplied, events without a matching `resourceId` are excluded. Resource IDs must be unique and the list must not be empty.
+- `CalendarWeekView` displays 1–7 consecutive dates from `weekStartsOn` (0 = Sunday, default 1). `days={5}` displays a work week when the week starts on Monday. Resource filtering remains with the caller.
+- `CalendarMonthView` displays six weeks. `onDateSelect` handles date and overflow actions. `maxEvents` defaults to 3; without a drill-down handler all events remain reachable instead of being silently hidden.
+- `CalendarAgendaView` displays the next `days` dates (default 7), omitting empty dates. `empty` and `allDayLabel` accept application content.
+- `CalendarEvent` is a native button for custom event compositions. CVA selects its structural `appearance` (`block`, `compact`); `colors` supplies presentation values. `selected` and native button props remain independent of any event store.
+- `CalendarToolbar` accepts explicit state/callbacks, optional view choices, localized labels, a title override and children for application actions. It owns no frame or separator. Arrow labels and view names default to English.
+- `useCalendar` is optional. It supports controlled/uncontrolled dates and views and previous/next navigation. A required `defaultDate` makes initial rendering deterministic. Month navigation clamps the day to the target month's last day. Day navigation moves one day; week/agenda navigation moves seven. Callers with a different agenda length can supply their own navigation callback.
+
+All views forward native div props and refs. They can be rendered independently and in any order. `renderEvent`, `getEventLabel` and `onEventSelect` receive the original event plus its visible date, view and cross-day continuation flags. `selectedEventId` is controlled by the caller. A custom renderer supplies button content; do not nest interactive elements inside it. `CalendarEvent` can instead be composed directly for another interaction structure.
+
+Time views accept integer `startHour`/`endHour` within 0–24 (defaults 8–18), a positive `hourHeight` in pixels (default 56), and `formatTime`. Timed overlaps use separate columns; adjacent exclusive endpoints reuse a column. Optional `onTimeSelect` enables keyboard-accessible hour slots; `getTimeLabel` can localize their accessible names. All-day events occupy the matching date/resource column. Narrow time columns retain full accessible event labels; Agenda offers a readable alternative for dense schedules.
+
+## Application-owned composition
+
+The caller owns the active view and renders the matching component. `CalendarToolbar` only emits callbacks and `useCalendar` only helps manage state; neither is required. Existing Button or Tabs controls can switch views directly:
+
+```tsx
+const [view, setView] = useState<"day" | "week">("day");
+const [selectedEvent, setSelectedEvent] = useState<CalendarEventData | null>(null);
+const schedule = { date, events, onEventSelect: setSelectedEvent };
+
+<>
+    <Button aria-pressed={view === "day"} onClick={() => setView("day")}>Day</Button>
+    <Button aria-pressed={view === "week"} onClick={() => setView("week")}>Week</Button>
+    {view === "day" ? <CalendarDayView {...schedule} /> : <CalendarWeekView {...schedule} />}
+    {selectedEvent && <EventEditor event={selectedEvent} onClose={() => setSelectedEvent(null)} />}
+</>;
+```
+
+`EventEditor` is an application component. Calendar never opens an overlay, edits an event, or interprets a booking status. The caller can use an ID to look up its full business record when an event is selected.
+
+Both `CalendarEventData.colors` and `CalendarEvent.colors` accept `CalendarEventColors`:
+
+```tsx
+colors: {
+    accent: "var(--gridui-warning-border)",
+    background: "var(--gridui-warning-background)",
+    foreground: "var(--gridui-warning-foreground)",
+}
+```
+
+Each property is optional and accepts a CSS color, including theme variables. `accent` controls the event's leading edge and selected outline. It defaults to the theme accent; the default background blends that accent into the theme background, and the default foreground uses the theme text color. Explicit foreground colors also apply to time labels. All views preserve these colors for timed and all-day segments. Applications map business state or categories to colors and supply suitable foreground/background pairs; Calendar has no status-to-color mapping. Native `style` and `className` remain available on standalone `CalendarEvent`.
+
+## Date and event contract
+
+`CalendarDate` is a Gregorian `YYYY-MM-DD` civil date. Timed event `start` and `end` use `YYYY-MM-DDTHH:mm`; all-day events set `allDay: true` and use date-only values. End is **exclusive** in both cases. An all-day event on November 2 ends on November 3. A midnight end does not create an event on the following date. Overnight and multi-day events are segmented across views without changing the original event.
+
+Values have no UTC offset or implicit timezone conversion. Convert instants into the calendar's display timezone before providing them. This keeps browser timezone and daylight-saving changes from shifting the chosen civil date. Time geometry depicts wall-clock hours, not elapsed duration across timezone transitions. Events require nonempty unique IDs and positive durations; malformed dates/times throw `RangeError`.
+
+`locale` defaults to `en-US` and controls date captions. Applications supply `today` to show a current-date indicator; the library does not read the clock during rendering. Status names, tooltips, timezone labels, recurrence, validation against a booking service, drag/drop, resizing and editors are application concerns.
+
+## Grid and border ownership
+
+Load `@gridui/grid/styles.css` when using this composition:
+
+```tsx
+<FrameSection>
+    <Grid columns={{ base: 1, lg: 4 }} frame="internal">
+        <GridItem>{dateNavigation}</GridItem>
+        <GridItem span={{ base: 1, lg: 3 }}>
+            <Calendar>
+                <Split direction="column">
+                    <section className="p-gridui-16">{toolbar}</section>
+                    <section><CalendarWeekView date={date} events={events} /></section>
+                </Split>
+            </Calendar>
+        </GridItem>
+    </Grid>
+</FrameSection>
+```
+
+FrameSection owns the outside frame, Grid owns column/row seams, and Split owns the seam between toolbar and schedule. Calendar views paint only internal date/time separators. Their roots have no outer borders. Put Split around region wrappers, not directly around controls with functional outlines. Avoid nesting `Calendar frame="outline"` inside an already framed cell unless an inset card is intentional.
+
+CSS owns the time-grid geometry, event positioning, cell lines and responsive reflow. CVA owns surface and structural event variants; caller colors are scoped to each event. Tailwind owns ordinary alignment, spacing and typography. No Layout private classes, DOM inspection of a parent grid, or negative border offsets are required.
+
+See [component ownership](../../docs/component-ownership.md) and [release history](.changeset/history/).

package/dist/calendar/calendar.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace Calendar
+ * @description Calendar
+ */
+import type { ComponentPropsWithRef, FC } from "react";
+export type CalendarProps = ComponentPropsWithRef<"div"> & {
+    readonly frame?: "none" | "outline";
+};
+/** Optional surface. Views and toolbar have no dependency on this wrapper. */
+export declare const Calendar: FC<CalendarProps>;

package/dist/calendar/style.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace Calendar
+ * @description Style
+ */
+export declare const calendarStyles: (props?: ({
+    frame?: "none" | "outline" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/calendar-agenda-view/calendar-agenda-view.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarAgendaView
+ * @description Calendar Agenda View
+ */
+import type { CalendarViewOptions } from "../shared/types";
+import type { ComponentPropsWithRef, FC, ReactNode } from "react";
+export type CalendarAgendaViewProps = Omit<ComponentPropsWithRef<"div">, "children"> & CalendarViewOptions & {
+    readonly days?: number;
+    readonly empty?: ReactNode;
+    readonly allDayLabel?: string;
+    readonly formatTime?: (minute: number) => string;
+};
+export declare const CalendarAgendaView: FC<CalendarAgendaViewProps>;

package/dist/calendar-day-view/calendar-day-view.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarDayView
+ * @description Calendar Day View
+ */
+import { type TimeGridProps } from "../shared/time-grid";
+import type { CalendarResource } from "../shared/types";
+import type { FC } from "react";
+export type CalendarDayViewProps = Omit<TimeGridProps, "columns" | "view"> & {
+    readonly resources?: readonly CalendarResource[];
+};
+export declare const CalendarDayView: FC<CalendarDayViewProps>;

package/dist/calendar-event/calendar-event.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarEvent
+ * @description Calendar Event
+ */
+import type { CalendarEventColors } from "../shared/types";
+import type { ComponentPropsWithRef, FC } from "react";
+export type CalendarEventProps = ComponentPropsWithRef<"button"> & {
+    readonly colors?: CalendarEventColors | undefined;
+    readonly appearance?: "block" | "compact";
+    readonly selected?: boolean;
+};
+export declare const CalendarEvent: FC<CalendarEventProps>;

package/dist/calendar-event/style.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarEvent
+ * @description Style
+ */
+export declare const eventStyles: (props?: ({
+    appearance?: "block" | "compact" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;

package/dist/calendar-month-view/calendar-month-view.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarMonthView
+ * @description Calendar Month View
+ */
+import type { CalendarDate, CalendarViewOptions } from "../shared/types";
+import type { ComponentPropsWithRef, FC } from "react";
+export type CalendarMonthViewProps = Omit<ComponentPropsWithRef<"div">, "children"> & CalendarViewOptions & {
+    readonly weekStartsOn?: number;
+    readonly maxEvents?: number;
+    readonly onDateSelect?: (date: CalendarDate) => void;
+    readonly getMoreLabel?: (count: number, date: CalendarDate) => string;
+};
+export declare const CalendarMonthView: FC<CalendarMonthViewProps>;

package/dist/calendar-toolbar/calendar-toolbar.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarToolbar
+ * @description Calendar Toolbar
+ */
+import type { CalendarDate, CalendarView } from "../shared/types";
+import type { ComponentPropsWithRef, FC, ReactNode } from "react";
+export type CalendarToolbarLabels = {
+    readonly previous: string;
+    readonly next: string;
+    readonly today: string;
+    readonly views: string;
+    readonly day: string;
+    readonly week: string;
+    readonly month: string;
+    readonly agenda: string;
+};
+export type CalendarToolbarProps = Omit<ComponentPropsWithRef<"div">, "title"> & {
+    readonly date: CalendarDate;
+    readonly view: CalendarView;
+    readonly onNavigate: (direction: -1 | 1) => void;
+    readonly onViewChange: (view: CalendarView) => void;
+    readonly onToday?: () => void;
+    readonly locale?: string;
+    readonly weekStartsOn?: number;
+    readonly views?: readonly CalendarView[];
+    readonly labels?: Partial<CalendarToolbarLabels>;
+    readonly title?: ReactNode;
+};
+export declare const CalendarToolbar: FC<CalendarToolbarProps>;

package/dist/calendar-week-view/calendar-week-view.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace CalendarWeekView
+ * @description Calendar Week View
+ */
+import { type TimeGridProps } from "../shared/time-grid";
+import type { FC } from "react";
+export type CalendarWeekViewProps = Omit<TimeGridProps, "columns" | "view"> & {
+    readonly weekStartsOn?: number;
+    readonly days?: number;
+};
+export declare const CalendarWeekView: FC<CalendarWeekViewProps>;

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @author WMXPY
+ * @package Calendar
+ * @namespace Root
+ * @description Index
+ */
+export type { CalendarProps } from "./calendar/calendar";
+export { Calendar } from "./calendar/calendar";
+export type { CalendarAgendaViewProps } from "./calendar-agenda-view/calendar-agenda-view";
+export { CalendarAgendaView } from "./calendar-agenda-view/calendar-agenda-view";
+export type { CalendarDayViewProps } from "./calendar-day-view/calendar-day-view";
+export { CalendarDayView } from "./calendar-day-view/calendar-day-view";
+export type { CalendarEventProps } from "./calendar-event/calendar-event";
+export { CalendarEvent } from "./calendar-event/calendar-event";
+export type { CalendarMonthViewProps } from "./calendar-month-view/calendar-month-view";
+export { CalendarMonthView } from "./calendar-month-view/calendar-month-view";
+export type { CalendarToolbarLabels, CalendarToolbarProps } from "./calendar-toolbar/calendar-toolbar";
+export { CalendarToolbar } from "./calendar-toolbar/calendar-toolbar";
+export type { CalendarWeekViewProps } from "./calendar-week-view/calendar-week-view";
+export { CalendarWeekView } from "./calendar-week-view/calendar-week-view";
+export type { TimeSelection as CalendarTimeSelection } from "./shared/time-grid";
+export type { CalendarDate, CalendarEventColors, CalendarEventContext, CalendarEventData, CalendarResource, CalendarTimeOptions, CalendarView, CalendarViewOptions } from "./shared/types";
+export type { UseCalendarOptions } from "./use-calendar/use-calendar";
+export { useCalendar } from "./use-calendar/use-calendar";