@gobrand/react-calendar 0.0.3

package/README.md

@@ -0,0 +1,303 @@
+# @temporal-calendar/react
+
+React hook for building calendars with the Temporal API.
+
+## Installation
+
+```bash
+pnpm add @temporal-calendar/react
+```
+
+## Philosophy
+
+- **Data-agnostic**: Works with any data type (events, tasks, posts, etc.)
+- **Type-safe**: Full TypeScript support with TanStack-style type inference
+- **Zero abstractions**: Direct use of Temporal API primitives
+- **Minimal API surface**: Just a hook and utility functions
+
+## Quick Start
+
+```tsx
+import { useCalendar, createCalendarViews, createCalendarAccessor } from '@temporal-calendar/react';
+import { Temporal } from '@js-temporal/polyfill';
+
+type Event = {
+  id: string;
+  title: string;
+  start: Temporal.ZonedDateTime;
+};
+
+// Define how to extract dates from your data
+const accessor = createCalendarAccessor<Event>({
+  getDate: (event) => event.start.toPlainDate(),
+  getStart: (event) => event.start,
+  getEnd: (event) => event.start,
+});
+
+function MyCalendar() {
+  const calendar = useCalendar({
+    data: events,
+    views: createCalendarViews({
+      month: { weekStartsOn: 1, accessor },
+    }),
+  });
+
+  const month = calendar.getMonth();
+
+  return (
+    <div>
+      <header>
+        <button onClick={calendar.previousMonth}>←</button>
+        <h2>{calendar.getTitle('month')}</h2>
+        <button onClick={calendar.nextMonth}>→</button>
+        <button onClick={calendar.goToToday}>Today</button>
+      </header>
+
+      <div className="grid grid-cols-7 gap-2">
+        {getWeekdays(1).map(day => (
+          <div key={day}>{day}</div>
+        ))}
+
+        {month.weeks.flat().map(day => (
+          <div
+            key={day.date.toString()}
+            className={`
+              ${!day.isCurrentMonth && 'opacity-40'}
+              ${day.isToday && 'bg-blue-100'}
+            `}
+          >
+            <div>{day.date.day}</div>
+            {day.items.map(event => (
+              <div key={event.id}>{event.title}</div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Multi-View Calendar
+
+```tsx
+import { useCalendar, createCalendarViews } from '@temporal-calendar/react';
+
+const calendar = useCalendar({
+  data: events,
+  views: createCalendarViews({
+    month: { weekStartsOn: 1, accessor: monthAccessor },
+    week: { weekStartsOn: 1, startHour: 8, endHour: 18, accessor: weekAccessor },
+    day: { startHour: 8, endHour: 18, slotDuration: 30, accessor: dayAccessor },
+  }),
+});
+
+// Switch views
+calendar.setCurrentView('week');
+
+// Get current view data
+const month = calendar.getMonth();  // Type-safe! Only available if month view configured
+const week = calendar.getWeek();    // Type-safe! Only available if week view configured
+const day = calendar.getDay();      // Type-safe! Only available if day view configured
+```
+
+## API
+
+### `useCalendar<TOptions>(options)`
+
+Main hook for calendar state management.
+
+**Options:**
+```tsx
+{
+  data: T[];                          // Your data array
+  views: CalendarViewOptions<T>;      // View configurations
+  timeZone?: string;                  // IANA timezone (default: system)
+  state?: CalendarState;              // External state (for controlled mode)
+  onStateChange?: (state) => void;    // State change callback
+}
+```
+
+**Returns:** `Calendar<T, TOptions>` with methods based on configured views
+
+**Common methods:**
+- `getState()` - Get current state
+- `setState(updater)` - Update state
+- `goToToday()` - Navigate to today
+- `goToDate(date)` - Navigate to specific date
+- `getTitle(view)` - Get formatted title for view
+- `dateRange` - Current date range (for data fetching)
+- `currentView` - Current view name
+- `setCurrentView(view)` - Switch views
+
+**View-specific methods** (conditionally available based on configured views):
+
+**Month view:**
+- `getMonth()` - Returns `{ month: PlainYearMonth, weeks: CalendarWeek<T>[] }`
+- `nextMonth()` / `previousMonth()`
+- `goToMonth(year, month)`
+
+**Week view:**
+- `getWeek()` - Returns `{ weekStart, weekEnd, days: CalendarDay<T>[] }`
+- `nextWeek()` / `previousWeek()`
+
+**Day view:**
+- `getDay()` - Returns `{ date, timeSlots: { hour, minute, items: T[] }[] }`
+- `nextDay()` / `previousDay()`
+
+### `createCalendarViews<T>(config)`
+
+Type-safe builder for view configurations.
+
+```tsx
+const views = createCalendarViews<Event>({
+  month: {
+    weekStartsOn: 1,              // 0 (Sun) - 6 (Sat)
+    accessor: monthAccessor,       // CalendarAccessor<Event>
+  },
+  week: {
+    weekStartsOn: 1,
+    startHour: 8,                 // 0-23
+    endHour: 18,                  // 0-24
+    slotDuration: 30,             // Minutes
+    accessor: weekAccessor,
+  },
+  day: {
+    startHour: 8,
+    endHour: 18,
+    slotDuration: 30,
+    accessor: dayAccessor,
+  },
+});
+```
+
+### `createCalendarAccessor<T>(config)`
+
+Define how to extract date information from your data.
+
+```tsx
+const accessor = createCalendarAccessor<Event>({
+  getDate: (item) => Temporal.PlainDate,      // Required
+  getStart?: (item) => Temporal.ZonedDateTime, // For time-based views
+  getEnd?: (item) => Temporal.ZonedDateTime,   // For time-based views
+});
+```
+
+### Utility Functions
+
+All utilities from `@temporal-calendar/core` are re-exported:
+
+**Formatting:**
+- `getWeekdays(weekStartsOn?)` - Localized weekday names
+- `getMonthName(month, locale?)` - Localized month name
+- `formatTime(time, locale?)` - Format PlainTime
+
+**Navigation:**
+- `nextMonth(month)` / `previousMonth(month)`
+- `nextWeek(date)` / `previousWeek(date)`
+- `nextDay(date)` / `previousDay(date)`
+- `goToToday()` - Get current PlainDate
+
+**Timezone:**
+- `getMonthRange(timeZone?, weekStartsOn?)` - Week-aligned month range
+- `getWeekRange(timeZone?, weekStartsOn?)` - Current week range
+- `getDayRange(timeZone?)` - Today in timezone
+- `getCurrentTimeZone()` - Get system timezone
+- `convertToTimezone(zdt, timeZone)` - Convert between timezones
+- `createZonedDateTime(date, time, timeZone)` - Create ZonedDateTime
+
+**Layout:**
+- `getEventPosition(start, end, startHour, endHour, slotDuration)` - Calculate event positioning for time-based grids
+
+## Data Structures
+
+### `CalendarDay<T>`
+
+```tsx
+{
+  date: Temporal.PlainDate;
+  isCurrentMonth: boolean;
+  isToday: boolean;
+  items: T[];  // Your data filtered to this day
+}
+```
+
+### `CalendarWeek<T>`
+
+```tsx
+CalendarDay<T>[]  // Array of 7 days
+```
+
+### `CalendarMonth<T>`
+
+```tsx
+{
+  month: Temporal.PlainYearMonth;
+  weeks: CalendarWeek<T>[];
+}
+```
+
+### `CalendarWeekView<T>`
+
+```tsx
+{
+  weekStart: Temporal.PlainDate;
+  weekEnd: Temporal.PlainDate;
+  days: CalendarDay<T>[];
+}
+```
+
+### `CalendarDayView<T>`
+
+```tsx
+{
+  date: Temporal.PlainDate;
+  timeSlots: {
+    hour: number;
+    minute: number;
+    items: T[];  // Items overlapping this time slot
+  }[];
+}
+```
+
+## Type Safety
+
+The hook uses TanStack-style type inference to provide conditional types based on your configuration:
+
+```tsx
+// Only month view configured
+const calendar = useCalendar({
+  data: events,
+  views: createCalendarViews({ month: { ... } }),
+});
+
+calendar.getMonth();     // ✅ Available
+calendar.nextMonth();    // ✅ Available
+calendar.getWeek();      // ❌ Type error - week view not configured
+
+// All views configured
+const calendar = useCalendar({
+  data: events,
+  views: createCalendarViews({
+    month: { ... },
+    week: { ... },
+    day: { ... },
+  }),
+});
+
+calendar.getMonth();     // ✅ Available
+calendar.getWeek();      // ✅ Available
+calendar.getDay();       // ✅ Available
+```
+
+## Examples
+
+See the [demo app](../../apps/demo) for complete examples:
+- **Month view**: [PostMonthlyView.tsx](../../apps/demo/src/components/PostMonthlyView.tsx)
+- **Week view**: [PostWeeklyView.tsx](../../apps/demo/src/components/PostWeeklyView.tsx)
+- **Day view**: [PostDailyView.tsx](../../apps/demo/src/components/PostDailyView.tsx)
+- **Custom view**: [PostAgendaView.tsx](../../apps/demo/src/components/PostAgendaView.tsx)
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+var react = require('react');
+var calendarCore = require('@gobrand/calendar-core');
+
+// src/index.ts
+function useCalendar(options) {
+  const [calendarRef] = react.useState(() => ({
+    current: calendarCore.createCalendar(options)
+  }));
+  const [state, setState] = react.useState(() => calendarRef.current.getState());
+  calendarRef.current.setOptions((prev) => ({
+    ...prev,
+    ...options,
+    state: {
+      ...state,
+      ...options.state
+    },
+    onStateChange: (updater) => {
+      setState(updater);
+      options.onStateChange?.(updater);
+    }
+  }));
+  return calendarRef.current;
+}
+
+exports.useCalendar = useCalendar;
+Object.keys(calendarCore).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return calendarCore[k]; }
+  });
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from '@gobrand/calendar-core';
+import { type Calendar, type CalendarOptions } from '@gobrand/calendar-core';
+export declare function useCalendar<TOptions extends CalendarOptions<any>>(options: TOptions): Calendar<TOptions['data'] extends (infer T)[] ? T : never, TOptions>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,wBAAwB,CAAC;AAEvC,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,wBAAwB,CAAC;AAChC,wBAAgB,WAAW,CAAC,QAAQ,SAAS,eAAe,CAAC,GAAG,CAAC,EAC/D,OAAO,EAAE,QAAQ,GAChB,QAAQ,CACT,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,EAChD,QAAQ,CACT,CA2BA"}

package/dist/index.js

@@ -0,0 +1,26 @@
+import { useState } from 'react';
+import { createCalendar } from '@gobrand/calendar-core';
+export * from '@gobrand/calendar-core';
+
+// src/index.ts
+function useCalendar(options) {
+  const [calendarRef] = useState(() => ({
+    current: createCalendar(options)
+  }));
+  const [state, setState] = useState(() => calendarRef.current.getState());
+  calendarRef.current.setOptions((prev) => ({
+    ...prev,
+    ...options,
+    state: {
+      ...state,
+      ...options.state
+    },
+    onStateChange: (updater) => {
+      setState(updater);
+      options.onStateChange?.(updater);
+    }
+  }));
+  return calendarRef.current;
+}
+
+export { useCalendar };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gobrand/react-calendar",
+  "version": "0.0.3",
+  "description": "React hooks and components for building calendars using the Temporal API",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/go-brand/calendar.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/go-brand/calendar/issues"
+  },
+  "homepage": "https://github.com/go-brand/calendar#readme",
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly --declaration --declarationMap",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@js-temporal/polyfill": "^0.5.1",
+    "@gobrand/calendar-core": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.4",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/ui": "^2.1.8",
+    "jsdom": "^25.0.1",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^2.1.8"
+  },
+  "keywords": [
+    "react",
+    "hooks",
+    "temporal",
+    "calendar",
+    "date",
+    "datetime",
+    "time",
+    "temporal-api",
+    "react-hooks"
+  ]
+}