frappe-ui 1.0.0-beta.71 → 1.0.0-beta.72

package/experimental/Calendar/Calendar.api.md

@@ -12,6 +12,12 @@
     type: 'CalendarEvent[]',
     default: '[]'
   },
+  {
+    name: 'loading',
+    description: 'Whether the events for the visible range are still on their way.\n\nOnly the Agenda reads it, and only to tell an empty list apart from one that\nhas not arrived: a grid with nothing in it still draws the days, where a list\nwith nothing in it is a blank panel, and saying "nothing on" of a range still\nbeing fetched is saying something that may not be true.',
+    required: false,
+    type: 'boolean'
+  },
   {
     name: 'config',
     description: 'Behavior overrides, merged over the defaults.',
@@ -23,7 +29,7 @@
     name: 'onClick',
     description: 'Replaces the default single-click behavior (opening the event\npopover) with your own handler.',
     required: false,
-    type: '((data: { e: MouseEvent; calendarEvent: CalendarEvent; }) => void)'
+    type: '((data: { e: MouseEvent | KeyboardEvent; calendarEvent: CalendarEvent; }) => void)'
   },
   {
     name: 'onDblClick',
@@ -48,12 +54,22 @@
   {
     name: 'event-popover-content',
     description: '',
-    type: '{ calendarEvent: { [x: string]: unknown; id?: string | number | undefined; name?: string | number | '
+    type: '{ calendarEvent: CalendarEvent; date: Date; isEditMode: boolean; close: () => void; }'
+  },
+  {
+    name: 'event-description',
+    description: '',
+    type: '{ calendarEvent: CalendarEvent; date: Date; description: string; timing: CalendarRowTag | null; }'
+  },
+  {
+    name: 'event-suffix',
+    description: '',
+    type: '{ calendarEvent: CalendarEvent; date: Date; description: string; timing: CalendarRowTag | null; }'
   },
   {
-    name: 'daily-header',
+    name: 'event-participant',
     description: '',
-    type: '{ parseDateWithDay: any; currentDate: any; fullDay: any; }'
+    type: '{ calendarEvent: CalendarEvent; date: Date; description: string; timing: CalendarRowTag | null; }'
   }
 ]
 

package/experimental/Calendar/Calendar.md

@@ -1,6 +1,6 @@
 # Calendar
 
-A date and event view for schedules, with Month, Week, and Day modes.
+A date and event view for schedules, with Month, Week, Day, and Agenda modes.
 
 > **Parked** — `Calendar` left the root export in `1.0.0` and now ships from
 > [`frappe-ui/experimental`](/docs/experimental) with its public API unchanged.
@@ -19,10 +19,9 @@ import type { CalendarEvent, CalendarConfig } from 'frappe-ui/experimental'
 ## Custom Header
 
 Pass a `#header` slot to replace the default toolbar. The slot receives the
-current title (`currentMonthYear`), the active view (`activeView`), the
-enabled view options (`enabledModes`), and navigation functions
-(`increment`, `decrement`, `updateActiveView`, `setCalendarDate`,
-`onMonthYearChange`).
+current title (`currentMonthYear`), the active view (`activeView`), the enabled
+view options (`enabledModes`), and navigation functions (`increment`,
+`decrement`, `updateActiveView`, `setCalendarDate`, `onMonthYearChange`).
 
 <ComponentPreview name="Calendar-CustomHeader" csr="true" />
 
@@ -45,43 +44,86 @@ Each entry in `events` is a `CalendarEvent`:
 }
 ```
 
-An event runs from `fromDate fromTime` to `toDate toTime`, dates inclusive.
-One whose `toDate` is later than its `fromDate` spans those days: the Month
-view draws it as a single bar across them, and the Week view puts it in the
-all-day row. A timed event that crosses midnight but is shorter than a day
-(an evening running late) stays in the time grid, cut at midnight into a
-piece per day. A timed event ending at `00:00` stops as that day begins, so
-it does not occupy it. Dragging a spanning event moves both ends together.
+An event runs from `fromDate fromTime` to `toDate toTime`, dates inclusive. One
+whose `toDate` is later than its `fromDate` spans those days: the Month view
+draws it as a single bar across them, and the Week view puts it in the all-day
+row. A timed event that crosses midnight but is shorter than a day (an evening
+running late) stays in the time grid, cut at midnight into a piece per day. A
+timed event ending at `00:00` stops as that day begins, so it does not occupy
+it. Dragging a spanning event moves both ends together.
 
 `isFullDay` events ignore their times and cover `fromDate`..`toDate` whole.
 
-The calendar keeps an internal copy of `events` and refreshes it when the
-prop changes. Edits made inside the calendar (create, drag, resize, delete)
-mutate the copy and come back through the `create`, `update`, and `delete`
-emits — persist them and refresh your source of truth from there.
+The calendar keeps an internal copy of `events` and refreshes it when the prop
+changes. Edits made inside the calendar (create, drag, resize, delete) mutate
+the copy and come back through the `create`, `update`, and `delete` emits —
+persist them and refresh your source of truth from there.
 
-`CalendarColorMap` exports the color palette (`amber`, `violet`, `pink`,
-`cyan`, `blue`, `orange`, `green`) with the CSS variables used per state, for
-building matching UI such as a color picker.
+`CalendarColorMap` exports the color palette (`amber`, `violet`, `pink`, `cyan`,
+`blue`, `orange`, `green`) with the CSS variables used per state, for building
+matching UI such as a color picker.
 
 ## Month view
 
 The Month view is a strip of week rows covering the month in view, and it
-scrolls when the rows outgrow the calendar's height. The arrows, Today, and
-the month picker move the month and scroll the strip to their date.
+scrolls when the rows outgrow the calendar's height. The arrows, Today, and the
+month picker move the month and scroll the strip to their date.
 
 Each row is as tall as its busiest day needs. Multi-day events run as bars
-across the top of the row; single-day events sit beneath them in their
-cells with the title wrapping to a second line, so every event is shown —
-there is no "n more".
-
-Below the `sm` breakpoint the days stack instead: a row per day, a heading
-where each month begins, and a week strip above to keep your place. Clicking a date number in either layout
-opens that day in the Day view.
-
-`rangeChange` reports the strip's full extent for the Month view — the
-padding days of the first and last weeks included — so a data source that
-fetches by range has events for every cell.
+across the top of the row; single-day events sit beneath them in their cells
+with the title wrapping to a second line, so every event is shown — there is no
+"n more".
+
+Below the `sm` breakpoint it is the same grid a size down: shorter pills, a
+tighter lane, and a cell that shows what fits in it with a `+n` count for the
+rest — a full week trades its last lane of bars for those counts. Clicking a
+date number at either width opens that day in the Day view.
+
+`rangeChange` reports the strip's full extent for the Month view — the padding
+days of the first and last weeks included — so a data source that fetches by
+range has events for every cell.
+
+## Agenda view
+
+The Agenda view is three months as a list of days, each day a card: its name,
+its date, how much is on it once that is more than one thing, then its events as
+rows. A day with nothing on it is not listed — an empty row says nothing the
+dates either side of it do not, and neither does a line counting how many were
+skipped. Cards are grouped under the week they fall in, which replaces the month
+dividers a flat list needs. Today's card carries a dot before its name; it, the
+day before it and the day after say so in words beside their dates, and a day
+already spent fades its header. An event that has ended is dimmed, the way a
+pill in the grid is once its time has passed. An event under way says so with
+its own tag.
+
+The window covers the month in view and the two after it, padded out to whole
+weeks at either end the way the Month view's strip is — the list groups its days
+under the week they fall in, and a week is either listed or it is not. A single
+month would be 31 days on the 1st and one day on the 31st, which is why it is
+three. The arrows step a month at a time, so each move keeps two thirds of what
+was on screen, and `rangeChange` reports exactly the span listed, padding
+included, so a data source fetching by range agrees with it. The header names
+the three months themselves, not the days the padding reaches into.
+
+Rows have the room a grid pill does not, so they carry a description line and
+tags. `Calendar` fills in the description itself — where the event is, and which
+day of a stay the row is (`Day 2/3`) — and marks a draft as a pill does, an
+outline in its colour on the plain ground rather than a tinted block. Where it stands against the clock
+reads right after that: `Now` in blue while it runs and `Soon` in amber in the
+hour before it, and nothing beyond that: an hour count would only restate the
+time written beside it. Who is coming (`participant`) stands at the row's far
+end, the one edge a card aligns on other than the time column, so the counts of
+a day's rows line up — and the `#event-description` and `#event-suffix` slots
+let you say the rest.
+
+Drawn narrower than 640px — a phone, or a pane a sidebar has squeezed — the list
+stacks. A day's name becomes a band over its rows rather than a column beside
+them, and each row takes two lines: the title, its tags and who is coming on the
+first, the time and the description on the second. The list measures its own
+width for this, so a calendar in a narrow pane reads the same way a phone's
+does.
+
+<ComponentPreview name="Calendar-Agenda" csr="true" />
 
 ## Config
 
@@ -90,7 +132,7 @@ defaults:
 
 ```ts
 {
-  defaultMode: 'Month',   // 'Day' | 'Week' | 'Month'
+  defaultMode: 'Month',   // 'Day' | 'Week' | 'Month' | 'Agenda'
   disableModes: [],       // views removed from the view switcher
   isEditMode: false,      // create / drag / resize / delete
   enableShortcuts: true,  // keyboard shortcuts (below)
@@ -108,8 +150,8 @@ defaults:
 
 ## Keyboard shortcuts
 
-With `enableShortcuts` on: `m` / `w` / `d` switch views, `t` jumps to today,
-`←` / `→` navigate, and `Delete` removes the event whose popover is open
+With `enableShortcuts` on: `m` / `w` / `d` / `a` switch views, `t` jumps to
+today, `←` / `→` navigate, and `Delete` removes the event whose popover is open
 (edit mode only).
 
 They stay out of the way of whatever is on top: nothing fires while a field has
@@ -119,17 +161,26 @@ focus, or while a dialog, popover, menu or select is open anywhere on the page.
 
 By default, a single click on an event opens its detail popover and a double
 click opens the edit modal (edit mode only). Clicking an empty cell opens the
-new-event modal in edit mode. Each behavior is replaceable with the
-`onClick`, `onDblClick`, and `onCellClick` callback props — passing one turns
-the default off for that interaction.
+new-event modal in edit mode. Each behavior is replaceable with the `onClick`,
+`onDblClick`, and `onCellClick` callback props — passing one turns the default
+off for that interaction.
 
 The popover's content is replaceable with the `#event-popover-content` slot,
 which receives `{ calendarEvent, date, isEditMode, close }`.
 
-`CalendarActiveEvent` exports the ref holding the id of the event whose
-popover is open. Set it from outside to highlight an event, or clear it with
-an empty string. The ref is module-level: every `<Calendar>` on the page
-shares it.
+The Agenda's rows take three more slots: `#event-description` for the line
+under the title, `#event-suffix` for the tags beside it, and
+`#event-participant` for the row's far end, where the event's `participant`
+string is shown unless you fill it — with faces in front of the count, say. All
+three receive `{ calendarEvent, date, description, timing }`, where
+`description` and `timing` are what the calendar derived itself, so you can add
+to them rather than work them out again. The suffix has no tags of its own to
+hand you — it is yours to fill. Grid pills have no room for any of these and
+ignore the slots.
+
+`CalendarActiveEvent` exports the ref holding the id of the event whose popover
+is open. Set it from outside to highlight an event, or clear it with an empty
+string. The ref is module-level: every `<Calendar>` on the page shares it.
 
 ## Template ref
 

package/experimental/Calendar/Calendar.vue

@@ -2,7 +2,13 @@
   <!-- No overflow-hidden here: each view scrolls itself, and clipping at the
        root only cut the focus outline off the header's buttons. -->
   <div class="flex h-full flex-col">
+    <!-- v-if on the slot, not a fallback inside it: `renderSlot` falls back whenever a
+         slot renders nothing, so a consumer passing an empty <template #header /> — a
+         phone, which draws its own — got this header anyway and had to cover it with an
+         element that renders nothing. Asking whether the slot was passed at all is the
+         question that was being asked. -->
     <slot
+      v-if="$slots.header"
       name="header"
       v-bind="{
         currentMonthYear,
@@ -17,7 +23,8 @@
         onMonthYearChange,
         selectedMonthDate,
       }"
-    >
+    />
+    <template v-else>
       <div class="mb-2 flex justify-between">
         <!-- left side  -->
         <!-- Year, Month -->
@@ -63,7 +70,7 @@
           />
         </div>
       </div>
-    </slot>
+    </template>
 
     <CalendarMonthly
       v-if="activeView === 'Month'"
@@ -96,17 +103,32 @@
       :current-date="selectedDay"
       :config="overrideConfig"
     >
-      <template #header="{ parseDateWithDay, currentDate, fullDay }">
-        <slot
-          name="daily-header"
-          v-bind="{ parseDateWithDay, currentDate, fullDay }"
-        />
-      </template>
       <template #event-popover-content="slotProps">
         <slot name="event-popover-content" v-bind="slotProps" />
       </template>
     </CalendarDaily>
 
+    <CalendarAgenda
+      v-else-if="activeView === 'Agenda'"
+      :events="events"
+      :anchor="agendaAnchor"
+      :jump="agendaJump"
+      :loading="loading"
+    >
+      <template #event-description="slotProps">
+        <slot name="event-description" v-bind="slotProps" />
+      </template>
+      <template #event-suffix="slotProps">
+        <slot name="event-suffix" v-bind="slotProps" />
+      </template>
+      <template #event-participant="slotProps">
+        <slot name="event-participant" v-bind="slotProps" />
+      </template>
+      <template #event-popover-content="slotProps">
+        <slot name="event-popover-content" v-bind="slotProps" />
+      </template>
+    </CalendarAgenda>
+
     <NewEventModal
       v-if="showEventModal"
       v-model="showEventModal"
@@ -123,7 +145,6 @@ import {
   ref,
   watch,
   nextTick,
-  type Component,
 } from 'vue'
 import { Button } from '#components/Button'
 import { TabButtons } from '#components/TabButtons'
@@ -136,18 +157,18 @@ import {
 } from './calendarUtils'
 import { dayjs } from '#utils/dayjs'
 import { isTargetEditable } from '#composables/useKeyboardShortcut'
-import DayIcon from './Icon/DayIcon.vue'
-import WeekIcon from './Icon/WeekIcon.vue'
-import MonthIcon from './Icon/MonthIcon.vue'
 import DatePicker from '#components/DatePicker/DatePicker.vue'
 import CalendarMonthly from './CalendarMonthly.vue'
 import CalendarWeekly from './CalendarWeekly.vue'
 import CalendarDaily from './CalendarDaily.vue'
+import CalendarAgenda from './CalendarAgenda.vue'
 import NewEventModal from './NewEventModal.vue'
 import useEventModal from './composables/useEventModal'
 import { isAnyPopoverOpen } from './useEventBase'
 import { stripPlacement } from './eventSpan'
 import { stripRange } from './monthStrip'
+import { activeEvent } from './composables/useCalendarData'
+import { agendaMonths, agendaRange } from './agendaDays'
 import {
   ACTIVE_VIEW_KEY,
   CALENDAR_ACTIONS_KEY,
@@ -173,6 +194,9 @@ const emit = defineEmits<{
   ]
 }>()
 
+/** Bumped by setCalendarDate; the Agenda scrolls back to its anchor on every bump. */
+const agendaJump = ref(0)
+
 const defaultConfig: CalendarConfig = {
   scrollToHour: 15,
   disableModes: [],
@@ -266,24 +290,17 @@ function handleShortcuts(e: KeyboardEvent) {
   if (isOverlayOpen()) return
   if (isTargetEditable(e)) return
 
-  if (e.key.toLowerCase() === 'm') {
-    activeView.value = 'Month'
-  }
-  if (e.key.toLowerCase() === 'w') {
-    activeView.value = 'Week'
-  }
-  if (e.key.toLowerCase() === 'd') {
-    activeView.value = 'Day'
-  }
-  if (e.key.toLowerCase() === 't') {
-    setCalendarDate()
-  }
-  if (e.key === 'ArrowLeft') {
-    decrement()
-  }
-  if (e.key === 'ArrowRight') {
-    increment()
-  }
+  const view = viewShortcuts[e.key.toLowerCase()]
+  if (view) activeView.value = view
+  if (e.key.toLowerCase() === 't') setCalendarDate()
+  if (e.key === 'ArrowLeft') decrement()
+  if (e.key === 'ArrowRight') increment()
+}
+const viewShortcuts: Record<string, CalendarMode> = {
+  m: 'Month',
+  w: 'Week',
+  a: 'Agenda',
+  d: 'Day',
 }
 
 provide(ACTIVE_VIEW_KEY, activeView)
@@ -388,6 +405,9 @@ function handleCellClick(
     return
   }
 
+  // Clicking the list or the grid itself is how you let go of the event.
+  activeEvent.value = ''
+
   const data: CalendarCellClickData = {
     e,
     view: activeView.value,
@@ -406,14 +426,21 @@ function handleCellClick(
 type CalendarActionOption = {
   label: CalendarMode
   value: CalendarMode
-  iconLeft: Component
+  iconLeft: string
 }
 
-// Calendar View Options
+// Calendar View Options.
+//
+// Named lucide icons rather than four SVGs of the library's own: the set draws each
+// view as the shape of what it lays out — one pane, columns, a grid, a stack of
+// rows. Being lucide they also carry the same weight and
+// optical size as every other icon on the page, which hand-drawn glyphs at a fixed
+// 16px did not.
 const actionOptions: CalendarActionOption[] = [
-  { label: 'Day', value: 'Day', iconLeft: DayIcon },
-  { label: 'Week', value: 'Week', iconLeft: WeekIcon },
-  { label: 'Month', value: 'Month', iconLeft: MonthIcon },
+  { label: 'Day', value: 'Day', iconLeft: 'lucide-square-square' },
+  { label: 'Week', value: 'Week', iconLeft: 'lucide-columns-3' },
+  { label: 'Month', value: 'Month', iconLeft: 'lucide-grid-3x3' },
+  { label: 'Agenda', value: 'Agenda', iconLeft: 'lucide-rows-3' },
 ]
 let enabledModes = actionOptions.filter(
   (mode) => !overrideConfig.disableModes.includes(mode.value),
@@ -458,16 +485,19 @@ let date = ref(
 )
 let selectedDay = computed(() => currentMonthDates.value[date.value])
 
+/**
+ * The day the calendar is on, whichever view it is in: the one `date` points
+ * at, which every view moves — a step of the month or the week lands it on the
+ * first day in the period, a step of the day on the next one, and a date the
+ * host sets on that date. Reported the same way in every view so a host's mini
+ * month circles the day the reader picked. It used to answer the Month view
+ * with 1 and the Week view with the week's Sunday, and a mini month handed
+ * those circled the 1st, or the Sunday, while the calendar sat on the 11th the
+ * reader had just clicked in it.
+ */
 function computeCurrentDay(): number | null {
-  if (activeView.value === 'Week') {
-    const weekDates = datesInWeeks.value[week.value] || []
-    return weekDates[0] ? weekDates[0].getDate() : null
-  }
-  if (activeView.value === 'Day') {
-    const day = selectedDay.value
-    return day ? new Date(day).getDate() : null
-  }
-  return 1
+  const day = selectedDay.value
+  return day ? new Date(day).getDate() : null
 }
 
 let currentDay = ref(computeCurrentDay())
@@ -500,8 +530,14 @@ const incrementClickEvents: Record<CalendarMode, () => void> = {
   Month: incrementMonth,
   Week: incrementWeek,
   Day: incrementDay,
+  // The Agenda's window is anchored on a month and covers three, so its arrows
+  // step one — each move keeps two thirds of what was on screen.
+  Agenda: incrementMonth,
 }
 
+/** The day the Agenda is anchored on: whatever day the calendar is sitting on. */
+const agendaAnchor = computed(() => selectedDay.value ?? new Date())
+
 // decrementMonth lands on the month's last day, which is right for stepping
 // back a day across a month edge but scrolls the Month strip to its bottom;
 // the Month view's own arrow lands on the first day, as the other arrow does.
@@ -515,6 +551,9 @@ const decrementClickEvents: Record<CalendarMode, () => void> = {
   Month: decrementMonthView,
   Week: decrementWeek,
   Day: decrementDay,
+  // Lands on the 1st rather than the last day, which is where the window's
+  // first month wants to start reading.
+  Agenda: decrementMonthView,
 }
 
 function incrementMonth() {
@@ -666,6 +705,18 @@ const currentMonthYear = computed(() => {
     }
   }
 
+  // The Agenda is anchored on whole months, so it names them rather than the
+  // dates its ends happen to land on — `agendaMonths`, not the listed range,
+  // which pads to whole weeks and would have the title naming a month for the
+  // sake of the two days of it the first week reaches back into.
+  if (activeView.value === 'Agenda') {
+    const { start, end } = agendaMonths(agendaAnchor.value)
+    const short = (d: Date) => monthList[d.getMonth()].slice(0, 3)
+    return start.getFullYear() === end.getFullYear()
+      ? `${short(start)} – ${short(end)} ${end.getFullYear()}`
+      : `${short(start)} ${start.getFullYear()} – ${short(end)} ${end.getFullYear()}`
+  }
+
   // Non-week views or empty week fallback
   if (activeView.value !== 'Week')
     return formatMonthYear(currentMonth.value, currentYear.value)
@@ -695,6 +746,10 @@ function isCurrentMonthDate(date?: Date) {
 function setCalendarDate(d?: Date | string) {
   const dt = d ? new Date(d) : new Date()
   if (dt.toString() === 'Invalid Date') return
+  // Counted, not compared: the Agenda reads this to know it has been sent somewhere,
+  // which is not the same as its anchor changing — Today, pressed halfway down the
+  // list on the day it is already anchored on, moves nothing and means everything.
+  agendaJump.value++
   currentYear.value = dt.getFullYear()
   currentMonth.value = dt.getMonth()
   currentDate.value = dt
@@ -735,6 +790,17 @@ function getVisibleRange() {
     }
   }
 
+  // The Agenda reports what it actually lists — three months from where it is
+  // anchored, less the days already spent — so a consumer's fetch window and
+  // its "new event" anchor agree with what is on screen.
+  if (activeView.value === 'Agenda') {
+    const { start, end } = agendaRange(agendaAnchor.value)
+    return {
+      startDate: dayjs(start).format('YYYY-MM-DD'),
+      endDate: dayjs(end).format('YYYY-MM-DD'),
+    }
+  }
+
   // The Month strip's first and last weeks reach into the neighbouring months.
   const range = stripRange(currentMonth.value, currentYear.value)
   return {