Initial Commit
This commit is contained in:
86
openspec/changes/enterprise-react-calendar/proposal.md
Normal file
86
openspec/changes/enterprise-react-calendar/proposal.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# OpenSpec Change: enterprise-react-calendar
|
||||
|
||||
- **Change ID**: enterprise-react-calendar
|
||||
- **Package**: `@suaveplan/react-calendar`
|
||||
- **Category**: react
|
||||
- **Target path**: `react/forms/react-calendar`
|
||||
- **Status**: PROPOSED
|
||||
- **Date**: 2026-04-24
|
||||
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-calendar.md`
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Deliver `@suaveplan/react-calendar` on genesis from scratch at enterprise quality. Headless calendar engine (`useCalendar`) plus `Calendar` component with month/week/day/agenda views. Ships four per-view components, `CalendarHeader`, typed `CalendarEvent`/`CalendarEventMap` with `@suaveplan/events` emitter. Genesis adds Storybook stories (zero currently exist), Playwright E2E, event store indexing for O(1) lookups, and `@suaveplan/datetime` integration for timezone-aware date math.
|
||||
|
||||
---
|
||||
|
||||
## Current-state audit (genesis)
|
||||
|
||||
Package does not exist on genesis — fresh build.
|
||||
|
||||
---
|
||||
|
||||
## Available workspace deps on genesis
|
||||
|
||||
| Package | Role |
|
||||
|---|---|
|
||||
| `@suaveplan/error` (`workspace:^`) | `CalendarError` |
|
||||
| `@suaveplan/events` (`workspace:^`) | `EventBus` for calendar events |
|
||||
| `@suaveplan/datetime` (`workspace:^`) | Timezone-aware date math |
|
||||
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
|
||||
| `zod` (`catalog:forms`) | Event/config schemas |
|
||||
| `@opentelemetry/api` (`catalog:observability`) | `calendar.navigate` span |
|
||||
|
||||
External: `tslib catalog:build`. React 18 peer.
|
||||
|
||||
---
|
||||
|
||||
## Preserved public API surface
|
||||
|
||||
```ts
|
||||
Calendar, CalendarAgendaView, CalendarDayView, CalendarHeader,
|
||||
CalendarMonthView, CalendarWeekView
|
||||
useCalendar (+ UseCalendarReturn)
|
||||
|
||||
// Types
|
||||
CalendarConfig, CalendarEvent, CalendarEventMap,
|
||||
CalendarHeaderProps, CalendarProps, CalendarView,
|
||||
CalendarViewProps, DateRange, NavigationDirection
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New additions for genesis
|
||||
|
||||
1. **`@suaveplan/datetime` integration** — `useCalendar` uses `@suaveplan/datetime` `addDuration`/`startOf`/`endOf` for view range computation; accepts optional `timeZone`.
|
||||
2. **O(1) event lookup** — event store is a `Map<string, CalendarEvent[]>` keyed by ISO date string.
|
||||
3. **`CalendarError`** — codes: `CALENDAR_INVALID_EVENT`, `CALENDAR_VIEW_NOT_SUPPORTED`.
|
||||
4. **Stories** — `Calendar` (month, week, day, agenda, with-events, empty, playground), `CalendarHeader` (all navigations), each view component.
|
||||
5. **Playwright E2E** — click next/prev, verify date advances; add event, verify appears in month view.
|
||||
|
||||
---
|
||||
|
||||
## File layout
|
||||
|
||||
```text
|
||||
react/forms/react-calendar/
|
||||
package.json
|
||||
tsconfig.json
|
||||
vitest.config.ts
|
||||
src/
|
||||
index.ts
|
||||
hooks/
|
||||
use-calendar/ (ts + types + md + test + index)
|
||||
components/
|
||||
calendar/ (tsx + types + md + test + stories + index)
|
||||
calendar-header/ (tsx + types + md + test + stories + index)
|
||||
month-view/ week-view/ day-view/ agenda-view/
|
||||
types/
|
||||
calendar.types.ts
|
||||
utils/
|
||||
cn.ts
|
||||
e2e/
|
||||
calendar.spec.ts
|
||||
```
|
||||
93
openspec/changes/enterprise-react-calendar/tasks.md
Normal file
93
openspec/changes/enterprise-react-calendar/tasks.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# Tasks: enterprise-react-calendar
|
||||
|
||||
**Change ID**: enterprise-react-calendar
|
||||
**Package**: `@suaveplan/react-calendar`
|
||||
**Target path**: `react/forms/react-calendar`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/events`, `@suaveplan/datetime`, `@suaveplan/react-translate`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create directory tree per proposal layout.
|
||||
- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, exports map.
|
||||
- [ ] Dependencies: `@suaveplan/error workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/datetime workspace:^`, `@suaveplan/react-translate workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
|
||||
- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Error codes and types
|
||||
|
||||
- [ ] Define `CalendarError` extending `SuaveplanError`; codes: `CALENDAR_INVALID_EVENT`, `CALENDAR_VIEW_NOT_SUPPORTED`.
|
||||
- [ ] Define all types in `src/types/calendar.types.ts`: `CalendarView`, `CalendarEvent`, `CalendarEventMap`, `CalendarConfig`, `CalendarProps`, `CalendarViewProps`, `CalendarHeaderProps`, `DateRange`, `NavigationDirection`, `UseCalendarReturn`.
|
||||
- [ ] Write `CalendarEventSchema` Zod schema.
|
||||
|
||||
---
|
||||
|
||||
## 3. Hook — `useCalendar`
|
||||
|
||||
- [ ] State: `view: CalendarView`, `currentDate: Date`, `events: Map<string, CalendarEvent[]>` (keyed by `yyyy-MM-dd`).
|
||||
- [ ] Date math via `@suaveplan/datetime` `addDuration`, `startOf`, `endOf`; optional `timeZone` in config.
|
||||
- [ ] Exposes: `navigate(direction: NavigationDirection)`, `setView(view)`, `addEvent(event)`, `removeEvent(id)`, `updateEvent(id, partial)`, `getEventsForDate(date)`, `getEventsForRange(start, end)`, `visibleRange: DateRange`.
|
||||
- [ ] Emits `@suaveplan/events` events: `event:added`, `event:removed`, `event:updated`, `view:changed`, `navigation` — uses `@suaveplan/events` `EventBus`.
|
||||
- [ ] OTel `calendar.navigate` span on `navigate()`.
|
||||
- [ ] Write `use-calendar.test.tsx` (≤500 lines): navigate months/weeks/days, add/remove/update events, getEventsForDate O(1) verified, timeZone option. `{ timeout: 10000 }`.
|
||||
- [ ] Write `use-calendar.md`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Components
|
||||
|
||||
### CalendarHeader
|
||||
|
||||
- [ ] Prev/Next/Today buttons + view switcher. `useTranslation` for all copy.
|
||||
- [ ] Write test, stories (all-navigations, view-switching), md.
|
||||
|
||||
### CalendarMonthView
|
||||
|
||||
- [ ] 6-week grid; renders `CalendarEvent` chips per day cell; handles overflow with "+N more".
|
||||
- [ ] Write test, stories (default, with-events, empty), md.
|
||||
|
||||
### CalendarWeekView
|
||||
|
||||
- [ ] 7-column time grid; positions events by start/end time.
|
||||
- [ ] Write test, stories, md.
|
||||
|
||||
### CalendarDayView
|
||||
|
||||
- [ ] Single-day time grid.
|
||||
- [ ] Write test, stories, md.
|
||||
|
||||
### CalendarAgendaView
|
||||
|
||||
- [ ] List of upcoming events grouped by date.
|
||||
- [ ] Write test, stories, md.
|
||||
|
||||
### Calendar
|
||||
|
||||
- [ ] Composes Header + active view; controlled/uncontrolled; `"use client"` at entry.
|
||||
- [ ] Write test, stories (month, week, day, agenda, with-events, empty, playground), md.
|
||||
|
||||
---
|
||||
|
||||
## 5. E2E
|
||||
|
||||
- [ ] `e2e/calendar.spec.ts` — Playwright:
|
||||
- Click "Next" in month view, verify date header advances by 1 month.
|
||||
- Add event programmatically, verify chip appears in correct day cell.
|
||||
- Switch to week view, verify current week shown.
|
||||
|
||||
---
|
||||
|
||||
## 6. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-calendar` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-calendar` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-calendar`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user