vectis-ui 0.8.1 → 0.9.0

package/dist/components/VCalendar/gesture.js.map

@@ -1 +1 @@
-{"version":3,"file":"gesture.js","names":[],"sources":["../../../src/components/VCalendar/gesture.ts"],"sourcesContent":["// @keyboard @a11y @core\n/**\n * What the two grids' drag engines share, written once.\n *\n * VCalendarMonth and VCalendarTimeGrid both let an event be picked up, moved and dropped —\n * with a pointer and with the keyboard. Everything that does not depend on what a CELL is\n * lives here: the gesture state and its ghost, the pointer's move, release and cancel, the\n * capture, paging at an edge, the keyboard grab, drop and cancel, the focus handed back to a\n * card, and the flag that stops a drop from also reading as a click.\n *\n * What is NOT here is what genuinely differs, which is also why the two components exist\n * separately: turning a point into a cell (a day square on one side, a day and a minute on\n * the other), working out the new times from it, and the gesture kinds each grid adds. Those\n * stay with each grid, as hooks this composable calls, and the pure half of them is already\n * in `layout.ts`.\n *\n * It lives in the component's folder rather than in `composables/`, the `edgeStep.ts` and\n * `VCombobox/infiniteScroll.ts` arrangement: both consumers are inside this component, so it\n * fails the admission rule that folder keeps.\n */\nimport { computed, nextTick, ref, watch } from 'vue'\nimport type { Ref } from 'vue'\n\nimport { isRtl as isElementRtl } from '../../utils/direction'\n\nimport { useMessages } from '../../i18n/state'\n\nimport { EDGE_BAND, useEdgeStep } from './edgeStep'\nimport { calendarIntent, type CalendarIntent } from './keyboard'\nimport { DRAG_THRESHOLD, inlineEdgeAt, pointWithin, type GridGeometry } from './layout'\nimport type { CalendarEvent, CalendarEventId, CalendarEventTimes } from './types'\n\n/**\n * The prefix marking the copy an event leaves behind at its old place while it is being\n * dragged. It is written into the id rather than held beside it so that the ghost travels\n * through the same list, the same layout and the same `v-for` key as everything else.\n */\nconst GHOST_PREFIX = '__vectis-calendar-ghost__'\n\n/**\n * The id the ghost of a dragged event carries. It has to DIFFER from the event's own, or the\n * two would collide in every map the layout keys by id and only one would ever be drawn.\n */\nexport const ghostIdOf = (id: CalendarEventId) => `${GHOST_PREFIX}${id}`\n/**\n * The dragged event's own id, read back off its ghost's. It is what the card is handed as\n * `ghostOf`: an event's colour is derived from its id, so a ghost coloured from its own\n * would not match the card it belongs to. `hueOf` reads a number and its digits as the same\n * event, so the string form returned here is enough.\n */\nexport const originalIdOf = (id: CalendarEventId) => String(id).slice(GHOST_PREFIX.length)\nexport const isGhostId = (id: CalendarEventId) => String(id).startsWith(GHOST_PREFIX)\n\n/**\n * The id a card belongs to, read back off the DOM.\n *\n * An id may be a NUMBER and an attribute is always text, so a numeric one has to be turned\n * back into one — otherwise every card of a numerically-keyed calendar would look up as a\n * miss and nothing would drag. Which of the two it is, is settled by asking the map that\n * holds the originals rather than by guessing from the text.\n */\nexport function cardIdOf(card: HTMLElement, has: (id: CalendarEventId) => boolean) {\n  const raw = card.dataset.eventId ?? ''\n  return has(raw) ? raw : Number(raw)\n}\n\n/**\n * A grid's measured box as the pure geometry wants it: plain numbers, no element.\n *\n * `inlineStart` is the edge the first column starts at, which is the RIGHT one in a\n * right-to-left page — which is also why containment never goes through this, see\n * `pointWithin`.\n */\nexport function gridGeometryOf(rect: DOMRect, columns: number, rtl: boolean): GridGeometry {\n  return {\n    top: rect.top,\n    height: rect.height,\n    inlineStart: rtl ? rect.right : rect.left,\n    inlineSize: rect.width,\n    columns,\n  }\n}\n\n/** The state every gesture carries, whatever each grid adds to it. */\nexport interface GestureBase {\n  id: CalendarEventId\n  /**\n   * Where the event was when the gesture began. Every pointer frame is computed from THIS and\n   * never from the frame before it, so a long drag cannot accumulate rounding drift.\n   */\n  origin: CalendarEventTimes\n  /** What the card shows right now. The model is not touched until the gesture ends. */\n  preview: CalendarEventTimes\n  /** The pointer holding the gesture, or null for a keyboard grab. */\n  pointerId: number | null\n  originX: number\n  originY: number\n  /**\n   * Where the pointer last was. Two things move the calendar UNDER a still pointer — paging at\n   * an edge, and auto-scrolling — and each has to work out afresh what the pointer is now over.\n   */\n  lastX: number\n  lastY: number\n  /** Whether it moved past the threshold, which is what separates a drag from a click. */\n  moved: boolean\n  /**\n   * Whether the pointer is off the calendar altogether — over the toolbar, or over the page\n   * beside it. Letting go there abandons the gesture whole and writes nothing.\n   *\n   * A KEYBOARD grab can never set it, and structurally rather than by a guard: `onPointermove`\n   * is the only writer, and it returns on the id mismatch first — a grab's `pointerId` is null,\n   * which no real pointer's id ever equals.\n   */\n  outside: boolean\n  /**\n   * The reading direction, read ONCE when the gesture begins. It cannot change under a live\n   * drag, and asking the document on every frame costs a style resolution each time.\n   */\n  rtl: boolean\n}\n\n/** What a grid hands over to start a gesture; the rest is filled in here. */\nexport type GestureInit<G extends GestureBase> = Omit<\n  G,\n  'preview' | 'lastX' | 'lastY' | 'moved' | 'outside' | 'rtl'\n>\n\n/**\n * A gesture held by the KEYBOARD rather than by a pointer: grabbed with Space, and waiting\n * for the arrows to move it. Both grids draw the card differently in that state, which is\n * what makes it worth a name.\n */\nexport const isGrabbed = (state: GestureBase | null) => state !== null && state.pointerId === null\n\n/** The two intents that move a grabbed event, which only a grid can turn into times. */\nexport type GrabStep = Extract<CalendarIntent, { kind: 'grabMove' | 'grabResize' }>\n\nexport interface CalendarGestureOptions<E extends CalendarEvent, G extends GestureBase> {\n  /** Every event as it is currently drawn, the ghost's original among them. */\n  events: () => readonly E[]\n  /** The event drawn under an id, for the handlers. */\n  eventOf: (id: CalendarEventId) => E | undefined\n  /** The view's own box: what \"outside the calendar\" is measured against. */\n  rootEl: Ref<HTMLElement | null>\n  /**\n   * The element the pointer is captured on once a press travels. It must contain every surface\n   * a gesture can start on, and carry the move, up, cancel and leave bindings: capture retargets\n   * every later pointer event to it, which is what makes one set of bindings serve every kind of\n   * gesture.\n   */\n  captureEl: Ref<HTMLElement | null>\n  /** The box the cells occupy, which points and edges are read against. */\n  measureEl: Ref<HTMLElement | null>\n  /** How many columns that box is divided into. */\n  columns: () => number\n  /** Whether events may be moved at all. */\n  editable: () => boolean\n  /** The node every card points at to say how it can be moved. */\n  hintId: () => string\n  /** The step a grabbed event moves by, handed to the keyboard table. */\n  slotMinutes: () => number\n  edgeStepDelay: () => number\n  /** Whatever the grid's cells are made of, so paging under a still pointer re-places the card. */\n  layout: () => unknown\n  /** Works out where the gesture's event belongs from the pointer's last position. */\n  applyPoint: (state: G, rect: DOMRect) => void\n  /** Called on every pointer move past the threshold, after the edge watch, with both rects. */\n  onEdges?: (state: G, rootRect: DOMRect | undefined) => void\n  /** Everything else a gesture leaves running, dropped on every path out of one. */\n  onRelease?: () => void\n  /**\n   * A pointer gesture let go inside the calendar. Returns true when the grid has answered it\n   * itself — a slot drawn out — and nothing is left to drop.\n   */\n  onLetGo?: (state: G) => boolean\n  /** A gesture that moved, committed: the grid reports the new times. */\n  onDrop: (state: G) => void\n  /** What a keyboard grab of this event starts, or null when it cannot be grabbed. */\n  grab: (item: E) => GestureInit<G> | null\n  /** Applies one arrow step to a grabbed event. Returns false when the step means nothing here. */\n  onGrabStep: (state: G, step: GrabStep, item: E) => boolean\n  step: (direction: -1 | 1) => void\n  announce: (message: string) => void\n}\n\nexport function useCalendarGesture<E extends CalendarEvent, G extends GestureBase>(\n  options: CalendarGestureOptions<E, G>,\n) {\n  const m = useMessages()\n  const gesture = ref<G | null>(null) as Ref<G | null>\n\n  /** True while a card is being held by the keyboard rather than dragged by a pointer. */\n  const grabbing = computed(() => isGrabbed(gesture.value))\n\n  const isRtl = () => isElementRtl(options.measureEl.value)\n\n  /**\n   * The echo of where the gestured event began, so the reader can see what they are moving it\n   * FROM. A press that has not travelled yet produces none, or a click would flash a second\n   * card over the first.\n   */\n  const ghostEvent = computed<E | null>(() => {\n    const state = gesture.value\n    if (!state?.moved) return null\n    const original = options.events().find((event) => event.id === state.id)\n    return original ? ({ ...original, ...state.origin, id: ghostIdOf(state.id) } as E) : null\n  })\n\n  /**\n   * A list with the gestured event moved to wherever it is now, plus its echo.\n   *\n   * The echo is listed whether or not it has a box to draw on, because this is what the id maps\n   * are built from and the template reads a card's event back out of them. An echo whose day\n   * the view has paged past simply produces no placement, as any event off show does.\n   */\n  function withPreview(events: readonly E[]): E[] {\n    const state = gesture.value\n    if (!state) return [...events]\n    const moving = events.map((event) =>\n      event.id === state.id ? ({ ...event, ...state.preview } as E) : event,\n    )\n    return ghostEvent.value ? [...moving, ghostEvent.value] : moving\n  }\n\n  /**\n   * The flag that keeps a drop from also reading as a click.\n   *\n   * A pointer that moved past the threshold ends on a `click` the browser fires anyway, and\n   * without this the card would be dropped AND opened. It is a plain variable rather than a\n   * ref: nothing renders from it, and a reactive one would re-render the grid at the end of\n   * every gesture for no visible change.\n   *\n   * TRAP — three writes, and each is load-bearing.\n   *\n   * `pointerup` SETS it, outside the calendar included, because `pointerup` fires before\n   * `click`: an abandoned drag would otherwise end by opening the very event it refused to move.\n   *\n   * `pointercancel` does NOT, and must never share a helper with the release that does: no click\n   * follows a cancel, so a `true` left behind there would swallow the next genuine one.\n   *\n   * Every press CLEARS it before any guard runs. The click that lowers it only reaches a card\n   * when it lands on one, and drawing out a new event ends on a CELL, so the flag would stay up\n   * — and a press that starts no gesture, which `creatable` without `editable` reaches every\n   * time, would never overwrite it. The reader clicks an event, nothing happens, they click\n   * again. Clearing at the press is what makes the flag unable to outlive its own interaction,\n   * and the order is the argument: the click it exists to swallow follows its own `pointerup`\n   * with no press in between.\n   */\n  let dragged = false\n\n  /** Closes the books on the previous gesture. Every press handler calls it first. */\n  function endLastGesture() {\n    dragged = false\n  }\n\n  /** Whether the gesture that just ended actually moved; asking lowers the flag. */\n  function consumeDrag() {\n    const was = dragged\n    dragged = false\n    return was\n  }\n\n  const edge = useEdgeStep(options.step, options.edgeStepDelay)\n\n  /** Which edge is counting down, as the attribute the stylesheet reads. */\n  const edgeCue = computed(() =>\n    edge.pending.value === -1 ? 'start' : edge.pending.value === 1 ? 'end' : undefined,\n  )\n\n  function release() {\n    edge.cancel()\n    options.onRelease?.()\n  }\n\n  /**\n   * Starts a gesture. Every entry point funnels through here, so the rules that make a gesture\n   * safe — one at a time, the origin captured once — are written once. The pointer itself is\n   * only taken hold of once the press travels, in `onPointermove`.\n   */\n  function start(init: GestureInit<G>, rtl = isRtl()) {\n    gesture.value = {\n      ...init,\n      preview: { ...init.origin },\n      lastX: init.originX,\n      lastY: init.originY,\n      moved: false,\n      outside: false,\n      rtl,\n    } as G\n  }\n\n  /**\n   * Takes hold of the pointer on the capture element, so the drag keeps following it past the\n   * calendar's edges.\n   *\n   * TRAP — called when the press crosses the drag threshold, NEVER at the press. The browser\n   * sends the `click` that follows a captured `pointerup` to the CAPTURE element, so a press\n   * captured at once reaches the scroller instead of the card or the cell under it: clicking an\n   * event would open nothing and clicking an empty slot would report nothing, on every calendar\n   * whose events can be moved or drawn. Neither jsdom nor a synthetic pointer event reproduces\n   * the retargeting (a synthetic pointer cannot be captured), so the unit suite pins WHEN the\n   * capture is asked for rather than where the click lands.\n   */\n  function capture(pointerId: number) {\n    // @fallback\n    /*\n     * Wrapped because a pointer event fired by a TEST refers to no real pointer,\n     * and the call then throws. Failing to capture merely means the drag stops at the edge of\n     * the capture element, which no test is checking.\n     */\n    try {\n      options.captureEl.value?.setPointerCapture(pointerId)\n    } catch {\n      /* a synthetic pointer: nothing to capture */\n    }\n  }\n\n  /** Re-reads the measured box and works the gesture out again, for a caller outside a handler. */\n  function reapply(state: G) {\n    const rect = options.measureEl.value?.getBoundingClientRect()\n    if (rect) options.applyPoint(state, rect)\n  }\n\n  function onPointermove(event: PointerEvent) {\n    const state = gesture.value\n    if (!state || state.pointerId !== event.pointerId) return\n\n    state.lastX = event.clientX\n    state.lastY = event.clientY\n\n    // Below the threshold nothing has happened yet. That is what keeps a click a click: the\n    // hand's tremor during a press would otherwise register as a one-pixel drag.\n    if (\n      !state.moved &&\n      Math.abs(event.clientX - state.originX) < DRAG_THRESHOLD &&\n      Math.abs(event.clientY - state.originY) < DRAG_THRESHOLD\n    ) {\n      return\n    }\n\n    if (!state.moved) capture(event.pointerId)\n    state.moved = true\n    // Each box is measured ONCE per move and handed to everything that reads it.\n    const rootRect = options.rootEl.value?.getBoundingClientRect()\n    const rect = options.measureEl.value?.getBoundingClientRect()\n\n    /*\n     * Outside is measured against the view's own box — never the cells' box, whose rect\n     * excludes the day names, the all-day band and the hour gutter — and the rect goes in RAW:\n     * containment has no reading direction, where `inlineStart` is the right edge in RTL.\n     *\n     * TRAP — neither the placement nor the edge watch below is gated on it, and neither may\n     * become so. The card must keep following the pointer while it is out, which is what makes\n     * coming back in seamless, and paging must keep running, pushing past the edge being how one\n     * crosses into the next period. Being outside decides what happens on RELEASE, nothing else.\n     */\n    state.outside = rootRect ? !pointWithin({ x: state.lastX, y: state.lastY }, rootRect) : false\n\n    if (!rect) return\n    options.applyPoint(state, rect)\n    edge.watchEdge(\n      inlineEdgeAt(\n        state.lastX,\n        gridGeometryOf(rect, options.columns(), state.rtl),\n        EDGE_BAND,\n        state.rtl,\n      ),\n    )\n    options.onEdges?.(state, rootRect)\n  }\n\n  function onPointerup(event: PointerEvent) {\n    const state = gesture.value\n    if (!state || state.pointerId !== event.pointerId) return\n    gesture.value = null\n    dragged = state.moved\n    release()\n\n    /*\n     * Let go with the pointer off the calendar and the gesture is abandoned whole. Nothing is\n     * announced: the pointer says nothing on a SUCCESSFUL drop either — `grabbed`, `dropped` and\n     * `reverted` belong to the keyboard grab, which has no pointer to show where the event went.\n     */\n    if (state.outside) return\n    if (options.onLetGo?.(state)) return\n    // A press that never travelled is an ordinary click, which the button's own click event is\n    // about to report. Writing anything here would move an event nobody dragged.\n    if (state.moved) options.onDrop(state)\n  }\n\n  /*\n   * The gesture was taken away — a system gesture, a context menu, the page starting to scroll.\n   * Nothing is written and nothing is announced: the card goes back to where the model still\n   * says it is.\n   */\n  function onPointercancel() {\n    gesture.value = null\n    release()\n  }\n\n  /*\n   * A press that leaves the capture element before it has travelled far enough to be captured.\n   * Its `pointerup` then lands outside and never reaches the bindings, so without this the\n   * gesture would outlive the press: a mouse keeps the same pointer id, and bringing it back over\n   * the calendar with the button up would pick the event up and carry it. A captured pointer\n   * never leaves, so a real drag is untouched.\n   */\n  function onPointerleave(event: PointerEvent) {\n    const state = gesture.value\n    if (!state || state.pointerId !== event.pointerId || state.moved) return\n    onPointercancel()\n  }\n\n  /*\n   * Paging swaps the cells out from under a live drag, and the dragged event's day is then off\n   * screen — the card would vanish until the next pointer move, which never comes if the hand is\n   * holding still against the edge. Re-applying the last position once the new cells are\n   * rendered is what keeps the card under the pointer across the boundary.\n   */\n  watch(\n    options.layout,\n    () => {\n      const state = gesture.value\n      if (state?.moved) reapply(state)\n    },\n    { flush: 'post' },\n  )\n\n  /**\n   * Hands the focus back to a card once it has landed somewhere else, which the re-render has\n   * just taken it from.\n   *\n   * TRAP — the card is found by WALKING the cards rather than by building an attribute\n   * selector. An id belongs to the consumer, so it may hold a quote or a backslash a selector\n   * would need escaped, and `CSS.escape` cannot do that escaping here: jsdom defines no `CSS`\n   * object at all, so the call threw on every keyboard grab, from inside a `nextTick` where\n   * nothing could catch it — an unhandled rejection, which fails the run while every assertion\n   * still passes. Comparing the attribute's own text sidesteps the question, `data-event-id`\n   * being written as exactly `String(event.id)`.\n   */\n  function refocusCard(id: CalendarEventId) {\n    void nextTick(() => {\n      const cards = options.measureEl.value?.querySelectorAll<HTMLElement>('.v-calendar-event')\n      Array.from(cards ?? [])\n        .find((card) => card.dataset.eventId === String(id))\n        ?.focus()\n    })\n  }\n\n  /** Puts the focus on a cell by its id, once the render that made it tabbable has run. */\n  function focusCell(id: string, deferred = false) {\n    const move = () => document.getElementById(id)?.focus()\n    if (deferred) void nextTick(move)\n    else move()\n  }\n\n  /** The event a card stands for, read back off the attribute the card publishes. */\n  const idOfCard = (card: HTMLElement) => cardIdOf(card, (id) => options.eventOf(id) !== undefined)\n\n  /**\n   * A card answers a different table from the grid it sits in — that is what a grab mode IS.\n   * Without it the grid would offer a gesture the pointer alone could reach (WCAG 2.1.1).\n   */\n  function onCardKeydown(event: KeyboardEvent, card: HTMLElement) {\n    const item = options.eventOf(idOfCard(card))\n    if (!item) return\n\n    const held = grabbing.value && gesture.value?.id === item.id\n    const state = held ? gesture.value! : null\n    const intent = calendarIntent(\n      event.key,\n      event.shiftKey,\n      held ? 'grabbed' : 'event',\n      options.slotMinutes(),\n      state?.rtl ?? isRtl(),\n    )\n    if (!intent) return\n\n    if (!state) {\n      // An event that cannot be moved keeps a button's ordinary behaviour: Space presses it,\n      // which the card's click handler reports.\n      const init = intent.kind === 'grab' ? options.grab(item) : null\n      if (!init) return\n      /*\n       * Space is ALSO how a button is pressed, on its release. Cancelling the keydown is what\n       * stops that press, so the keystroke that takes hold of the event does not open it too:\n       * without it every attempt to move something would fire the consumer's editor over it.\n       */\n      event.preventDefault()\n      start(init)\n      options.announce(m.value.calendar.grabbed)\n      return\n    }\n\n    event.preventDefault()\n\n    if (intent.kind === 'grabMove' || intent.kind === 'grabResize') {\n      if (!options.onGrabStep(state, intent, item)) return\n      state.moved = true\n      refocusCard(state.id)\n      return\n    }\n\n    if (intent.kind === 'activate') {\n      gesture.value = null\n      if (state.moved) options.onDrop(state)\n      options.announce(m.value.calendar.dropped)\n      refocusCard(state.id)\n      return\n    }\n\n    if (intent.kind === 'cancel') {\n      gesture.value = null\n      options.announce(m.value.calendar.reverted)\n      refocusCard(state.id)\n    }\n  }\n\n  /**\n   * The five things every card is told about the gesture, bound with `v-bind` so the two grids\n   * cannot describe the same state in two different ways.\n   */\n  function cardState(id: CalendarEventId) {\n    const state = gesture.value\n    const mine = state !== null && state.id === id\n    return {\n      /*\n       * TRAP — only once the press has travelled. A dragged card takes no pointer events, so\n       * marked at the press it lets the release land on the cell beneath it: the click then goes\n       * to that cell, and clicking an event reports an empty slot instead of opening it.\n       */\n      dragging: mine && state.pointerId !== null && state.moved,\n      rejected: mine && state.outside,\n      grabbed: mine && state.pointerId === null,\n      hintId: options.editable() && !isGhostId(id) ? options.hintId() : undefined,\n      ghostOf: isGhostId(id) ? originalIdOf(id) : undefined,\n    }\n  }\n\n  return {\n    gesture,\n    grabbing,\n    ghostEvent,\n    withPreview,\n    edgeCue,\n    isRtl,\n    start,\n    reapply,\n    release,\n    endLastGesture,\n    consumeDrag,\n    onPointermove,\n    onPointerup,\n    onPointercancel,\n    onPointerleave,\n    onCardKeydown,\n    refocusCard,\n    focusCell,\n    idOfCard,\n    cardState,\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"gesture.js","names":[],"sources":["../../../src/components/VCalendar/gesture.ts"],"sourcesContent":["// @keyboard @a11y @core\n/**\n * What the two grids' drag engines share, written once.\n *\n * VCalendarMonth and VCalendarTimeGrid both let an event be picked up, moved and dropped —\n * with a pointer and with the keyboard. Everything that does not depend on what a CELL is\n * lives here: the gesture state and its ghost, the pointer's move, release and cancel, the\n * capture, paging at an edge, the keyboard grab, drop and cancel, the focus handed back to a\n * card, and the flag that stops a drop from also reading as a click.\n *\n * What is NOT here is what genuinely differs, which is also why the two components exist\n * separately: turning a point into a cell (a day square on one side, a day and a minute on\n * the other), working out the new times from it, and the gesture kinds each grid adds. Those\n * stay with each grid, as hooks this composable calls, and the pure half of them is already\n * in `layout.ts`.\n *\n * It lives in the component's folder rather than in `composables/`, the `edgeStep.ts` and\n * `VCombobox/infiniteScroll.ts` arrangement: both consumers are inside this component, so it\n * fails the admission rule that folder keeps.\n */\nimport { computed, nextTick, ref, watch } from 'vue'\nimport type { Ref } from 'vue'\n\nimport { isRtl as isElementRtl } from '../../utils/direction'\n\nimport { useMessages } from '../../i18n/state'\n\nimport { EDGE_BAND, useEdgeStep } from './edgeStep'\nimport { calendarIntent, type CalendarIntent } from './keyboard'\nimport { DRAG_THRESHOLD, inlineEdgeAt, pointWithin, type GridGeometry } from './layout'\nimport type { CalendarEvent, CalendarEventId, CalendarEventTimes } from './types'\n\n/**\n * The prefix marking the copy an event leaves behind at its old place while it is being\n * dragged. It is written into the id rather than held beside it so that the ghost travels\n * through the same list, the same layout and the same `v-for` key as everything else.\n */\nconst GHOST_PREFIX = '__vectis-calendar-ghost__'\n\n/**\n * The id the ghost of a dragged event carries. It has to DIFFER from the event's own, or the\n * two would collide in every map the layout keys by id and only one would ever be drawn.\n */\nexport const ghostIdOf = (id: CalendarEventId) => `${GHOST_PREFIX}${id}`\n/**\n * The dragged event's own id, read back off its ghost's. It is what the card is handed as\n * `ghostOf`: an event's colour is derived from its id, so a ghost coloured from its own\n * would not match the card it belongs to. `hueOf` reads a number and its digits as the same\n * event, so the string form returned here is enough.\n */\nexport const originalIdOf = (id: CalendarEventId) => String(id).slice(GHOST_PREFIX.length)\nexport const isGhostId = (id: CalendarEventId) => String(id).startsWith(GHOST_PREFIX)\n\n/**\n * The id a card belongs to, read back off the DOM.\n *\n * An id may be a NUMBER and an attribute is always text, so a numeric one has to be turned\n * back into one: otherwise every card of a numerically-keyed calendar would look up as a\n * miss and nothing would drag. Which of the two it is, is settled by asking the map that\n * holds the originals rather than by guessing from the text.\n */\nexport function cardIdOf(card: HTMLElement, has: (id: CalendarEventId) => boolean) {\n  const raw = card.dataset.eventId ?? ''\n  return has(raw) ? raw : Number(raw)\n}\n\n/**\n * A grid's measured box as the pure geometry wants it: plain numbers, no element.\n *\n * `inlineStart` is the edge the first column starts at, which is the RIGHT one in a\n * right-to-left page. This is also why containment never goes through this, see\n * `pointWithin`.\n */\nexport function gridGeometryOf(rect: DOMRect, columns: number, rtl: boolean): GridGeometry {\n  return {\n    top: rect.top,\n    height: rect.height,\n    inlineStart: rtl ? rect.right : rect.left,\n    inlineSize: rect.width,\n    columns,\n  }\n}\n\n/** The state every gesture carries, whatever each grid adds to it. */\nexport interface GestureBase {\n  id: CalendarEventId\n  /**\n   * Where the event was when the gesture began. Every pointer frame is computed from THIS and\n   * never from the frame before it, so a long drag cannot accumulate rounding drift.\n   */\n  origin: CalendarEventTimes\n  /** What the card shows right now. The model is not touched until the gesture ends. */\n  preview: CalendarEventTimes\n  /** The pointer holding the gesture, or null for a keyboard grab. */\n  pointerId: number | null\n  originX: number\n  originY: number\n  /**\n   * Where the pointer last was. Two things move the calendar UNDER a still pointer: paging at\n   * an edge, and auto-scrolling. Each has to work out afresh what the pointer is now over.\n   */\n  lastX: number\n  lastY: number\n  /** Whether it moved past the threshold, which is what separates a drag from a click. */\n  moved: boolean\n  /**\n   * Whether the pointer is off the calendar altogether: over the toolbar, or over the page\n   * beside it. Letting go there abandons the gesture whole and writes nothing.\n   *\n   * A KEYBOARD grab can never set it, and structurally rather than by a guard: `onPointermove`\n   * is the only writer, and it returns on the id mismatch first: a grab's `pointerId` is null,\n   * which no real pointer's id ever equals.\n   */\n  outside: boolean\n  /**\n   * The reading direction, read ONCE when the gesture begins. It cannot change under a live\n   * drag, and asking the document on every frame costs a style resolution each time.\n   */\n  rtl: boolean\n}\n\n/** What a grid hands over to start a gesture; the rest is filled in here. */\nexport type GestureInit<G extends GestureBase> = Omit<\n  G,\n  'preview' | 'lastX' | 'lastY' | 'moved' | 'outside' | 'rtl'\n>\n\n/**\n * A gesture held by the KEYBOARD rather than by a pointer: grabbed with Space, and waiting\n * for the arrows to move it. Both grids draw the card differently in that state, which is\n * what makes it worth a name.\n */\nexport const isGrabbed = (state: GestureBase | null) => state !== null && state.pointerId === null\n\n/** The two intents that move a grabbed event, which only a grid can turn into times. */\nexport type GrabStep = Extract<CalendarIntent, { kind: 'grabMove' | 'grabResize' }>\n\nexport interface CalendarGestureOptions<E extends CalendarEvent, G extends GestureBase> {\n  /** Every event as it is currently drawn, the ghost's original among them. */\n  events: () => readonly E[]\n  /** The event drawn under an id, for the handlers. */\n  eventOf: (id: CalendarEventId) => E | undefined\n  /** The view's own box: what \"outside the calendar\" is measured against. */\n  rootEl: Ref<HTMLElement | null>\n  /**\n   * The element the pointer is captured on once a press travels. It must contain every surface\n   * a gesture can start on, and carry the move, up, cancel and leave bindings: capture retargets\n   * every later pointer event to it, which is what makes one set of bindings serve every kind of\n   * gesture.\n   */\n  captureEl: Ref<HTMLElement | null>\n  /** The box the cells occupy, which points and edges are read against. */\n  measureEl: Ref<HTMLElement | null>\n  /** How many columns that box is divided into. */\n  columns: () => number\n  /** Whether events may be moved at all. */\n  editable: () => boolean\n  /** The node every card points at to say how it can be moved. */\n  hintId: () => string\n  /** The step a grabbed event moves by, handed to the keyboard table. */\n  slotMinutes: () => number\n  edgeStepDelay: () => number\n  /** Whatever the grid's cells are made of, so paging under a still pointer re-places the card. */\n  layout: () => unknown\n  /** Works out where the gesture's event belongs from the pointer's last position. */\n  applyPoint: (state: G, rect: DOMRect) => void\n  /** Called on every pointer move past the threshold, after the edge watch, with both rects. */\n  onEdges?: (state: G, rootRect: DOMRect | undefined) => void\n  /** Everything else a gesture leaves running, dropped on every path out of one. */\n  onRelease?: () => void\n  /**\n   * A pointer gesture let go inside the calendar. Returns true when the grid has answered it\n   * itself, such as a slot drawn out, and nothing is left to drop.\n   */\n  onLetGo?: (state: G) => boolean\n  /** A gesture that moved, committed: the grid reports the new times. */\n  onDrop: (state: G) => void\n  /** What a keyboard grab of this event starts, or null when it cannot be grabbed. */\n  grab: (item: E) => GestureInit<G> | null\n  /** Applies one arrow step to a grabbed event. Returns false when the step means nothing here. */\n  onGrabStep: (state: G, step: GrabStep, item: E) => boolean\n  step: (direction: -1 | 1) => void\n  announce: (message: string) => void\n}\n\nexport function useCalendarGesture<E extends CalendarEvent, G extends GestureBase>(\n  options: CalendarGestureOptions<E, G>,\n) {\n  const m = useMessages()\n  const gesture = ref<G | null>(null) as Ref<G | null>\n\n  /** True while a card is being held by the keyboard rather than dragged by a pointer. */\n  const grabbing = computed(() => isGrabbed(gesture.value))\n\n  const isRtl = () => isElementRtl(options.measureEl.value)\n\n  /**\n   * The echo of where the gestured event began, so the reader can see what they are moving it\n   * FROM. A press that has not travelled yet produces none, or a click would flash a second\n   * card over the first.\n   */\n  const ghostEvent = computed<E | null>(() => {\n    const state = gesture.value\n    if (!state?.moved) return null\n    const original = options.events().find((event) => event.id === state.id)\n    return original ? ({ ...original, ...state.origin, id: ghostIdOf(state.id) } as E) : null\n  })\n\n  /**\n   * A list with the gestured event moved to wherever it is now, plus its echo.\n   *\n   * The echo is listed whether or not it has a box to draw on, because this is what the id maps\n   * are built from and the template reads a card's event back out of them. An echo whose day\n   * the view has paged past simply produces no placement, as any event off show does.\n   */\n  function withPreview(events: readonly E[]): E[] {\n    const state = gesture.value\n    if (!state) return [...events]\n    const moving = events.map((event) =>\n      event.id === state.id ? ({ ...event, ...state.preview } as E) : event,\n    )\n    return ghostEvent.value ? [...moving, ghostEvent.value] : moving\n  }\n\n  /**\n   * The flag that keeps a drop from also reading as a click.\n   *\n   * A pointer that moved past the threshold ends on a `click` the browser fires anyway, and\n   * without this the card would be dropped AND opened. It is a plain variable rather than a\n   * ref: nothing renders from it, and a reactive one would re-render the grid at the end of\n   * every gesture for no visible change.\n   *\n   * TRAP — three writes, and each is load-bearing.\n   *\n   * `pointerup` SETS it, outside the calendar included, because `pointerup` fires before\n   * `click`: an abandoned drag would otherwise end by opening the very event it refused to move.\n   *\n   * `pointercancel` does NOT, and must never share a helper with the release that does: no click\n   * follows a cancel, so a `true` left behind there would swallow the next genuine one.\n   *\n   * Every press CLEARS it before any guard runs. The click that lowers it only reaches a card\n   * when it lands on one, and drawing out a new event ends on a CELL, so the flag would stay up\n   * — and a press that starts no gesture, which `creatable` without `editable` reaches every\n   * time, would never overwrite it. The reader clicks an event, nothing happens, they click\n   * again. Clearing at the press is what makes the flag unable to outlive its own interaction,\n   * and the order is the argument: the click it exists to swallow follows its own `pointerup`\n   * with no press in between.\n   *\n   * A key on a card clears it too, for the same reason from the other side: after a CAPTURED\n   * release the browser sends its click to the capture element, which no card handler hears,\n   * so the flag outlives the drag, and the next click a card receives may be the keyboard's,\n   * with no press before it.\n   */\n  let dragged = false\n\n  /**\n   * Closes the books on the previous gesture. Every press handler calls it first.\n   *\n   * A keyboard grab still held is abandoned here, as Escape would abandon it: every press\n   * handler refuses to start while a gesture is live, so a grab left behind froze every\n   * pointer gesture of the grid with nothing on screen to say why.\n   */\n  function endLastGesture() {\n    dragged = false\n    if (grabbing.value) revertGrab()\n  }\n\n  /** Puts a keyboard grab back where it was taken from, writing nothing, and says so. */\n  function revertGrab() {\n    const state = gesture.value\n    if (!state) return\n    gesture.value = null\n    options.announce(m.value.calendar.reverted)\n    return state\n  }\n\n  /**\n   * A keyboard grab ends when the focus moves on to something else, the toolbar or another\n   * control. Focus that goes NOWHERE is left alone: a card redrawn in another column loses it\n   * that way on every step, and `refocusCard` hands it back.\n   */\n  function onFocusout(event: FocusEvent) {\n    const state = gesture.value\n    const next = event.relatedTarget as HTMLElement | null\n    if (!grabbing.value || !state || !next) return\n    const card = next.closest<HTMLElement>('.v-calendar-event')\n    if (card && card.dataset.eventId === String(state.id)) return\n    revertGrab()\n  }\n\n  /** Whether the gesture that just ended actually moved; asking lowers the flag. */\n  function consumeDrag() {\n    const was = dragged\n    dragged = false\n    return was\n  }\n\n  const edge = useEdgeStep(options.step, options.edgeStepDelay)\n\n  /** Which edge is counting down, as the attribute the stylesheet reads. */\n  const edgeCue = computed(() =>\n    edge.pending.value === -1 ? 'start' : edge.pending.value === 1 ? 'end' : undefined,\n  )\n\n  function release() {\n    edge.cancel()\n    options.onRelease?.()\n  }\n\n  /**\n   * Starts a gesture. Every entry point funnels through here, so the rules that make a gesture\n   * safe — one at a time, the origin captured once — are written once. The pointer itself is\n   * only taken hold of once the press travels, in `onPointermove`.\n   */\n  function start(init: GestureInit<G>, rtl = isRtl()) {\n    gesture.value = {\n      ...init,\n      preview: { ...init.origin },\n      lastX: init.originX,\n      lastY: init.originY,\n      moved: false,\n      outside: false,\n      rtl,\n    } as G\n  }\n\n  /**\n   * Takes hold of the pointer on the capture element, so the drag keeps following it past the\n   * calendar's edges.\n   *\n   * TRAP — called when the press crosses the drag threshold, NEVER at the press. The browser\n   * sends the `click` that follows a captured `pointerup` to the CAPTURE element, so a press\n   * captured at once reaches the scroller instead of the card or the cell under it: clicking an\n   * event would open nothing and clicking an empty slot would report nothing, on every calendar\n   * whose events can be moved or drawn. Neither jsdom nor a synthetic pointer event reproduces\n   * the retargeting (a synthetic pointer cannot be captured), so the unit suite pins WHEN the\n   * capture is asked for rather than where the click lands.\n   */\n  function capture(pointerId: number) {\n    // @fallback\n    /*\n     * Wrapped because a pointer event fired by a TEST refers to no real pointer,\n     * and the call then throws. Failing to capture merely means the drag stops at the edge of\n     * the capture element, which no test is checking.\n     */\n    try {\n      options.captureEl.value?.setPointerCapture(pointerId)\n    } catch {\n      /* a synthetic pointer: nothing to capture */\n    }\n  }\n\n  /** Re-reads the measured box and works the gesture out again, for a caller outside a handler. */\n  function reapply(state: G) {\n    const rect = options.measureEl.value?.getBoundingClientRect()\n    if (rect) options.applyPoint(state, rect)\n  }\n\n  function onPointermove(event: PointerEvent) {\n    const state = gesture.value\n    if (!state || state.pointerId !== event.pointerId) return\n\n    state.lastX = event.clientX\n    state.lastY = event.clientY\n\n    // Below the threshold nothing has happened yet. That is what keeps a click a click: the\n    // hand's tremor during a press would otherwise register as a one-pixel drag.\n    if (\n      !state.moved &&\n      Math.abs(event.clientX - state.originX) < DRAG_THRESHOLD &&\n      Math.abs(event.clientY - state.originY) < DRAG_THRESHOLD\n    ) {\n      return\n    }\n\n    if (!state.moved) capture(event.pointerId)\n    state.moved = true\n    // Each box is measured ONCE per move and handed to everything that reads it.\n    const rootRect = options.rootEl.value?.getBoundingClientRect()\n    const rect = options.measureEl.value?.getBoundingClientRect()\n\n    /*\n     * Outside is measured against the view's own box — never the cells' box, whose rect\n     * excludes the day names, the all-day band and the hour gutter — and the rect goes in RAW:\n     * containment has no reading direction, where `inlineStart` is the right edge in RTL.\n     *\n     * TRAP — neither the placement nor the edge watch below is gated on it, and neither may\n     * become so. The card must keep following the pointer while it is out, which is what makes\n     * coming back in seamless, and paging must keep running, pushing past the edge being how one\n     * crosses into the next period. Being outside decides what happens on RELEASE, nothing else.\n     */\n    state.outside = rootRect ? !pointWithin({ x: state.lastX, y: state.lastY }, rootRect) : false\n\n    if (!rect) return\n    options.applyPoint(state, rect)\n    edge.watchEdge(\n      inlineEdgeAt(\n        state.lastX,\n        gridGeometryOf(rect, options.columns(), state.rtl),\n        EDGE_BAND,\n        state.rtl,\n      ),\n    )\n    options.onEdges?.(state, rootRect)\n  }\n\n  function onPointerup(event: PointerEvent) {\n    const state = gesture.value\n    if (!state || state.pointerId !== event.pointerId) return\n    gesture.value = null\n    dragged = state.moved\n    release()\n\n    /*\n     * Let go with the pointer off the calendar and the gesture is abandoned whole. Nothing is\n     * announced: the pointer says nothing on a SUCCESSFUL drop either — `grabbed`, `dropped` and\n     * `reverted` belong to the keyboard grab, which has no pointer to show where the event went.\n     */\n    if (state.outside) return\n    if (options.onLetGo?.(state)) return\n    // A press that never travelled is an ordinary click, which the button's own click event is\n    // about to report. Writing anything here would move an event nobody dragged.\n    if (state.moved) options.onDrop(state)\n  }\n\n  /*\n   * The gesture was taken away — a system gesture, a context menu, the page starting to scroll.\n   * Nothing is written and nothing is announced: the card goes back to where the model still\n   * says it is.\n   */\n  function onPointercancel(event: PointerEvent) {\n    // Another pointer's cancel, a second finger starting to pan, is not this gesture's. A\n    // keyboard grab carries no pointer id, so no cancel can end it either.\n    if (gesture.value?.pointerId !== event.pointerId) return\n    abandon()\n  }\n\n  function abandon() {\n    gesture.value = null\n    release()\n  }\n\n  /*\n   * A press that leaves the capture element before it has travelled far enough to be captured.\n   * Its `pointerup` then lands outside and never reaches the bindings, so without this the\n   * gesture would outlive the press: a mouse keeps the same pointer id, and bringing it back over\n   * the calendar with the button up would pick the event up and carry it. A captured pointer\n   * never leaves, so a real drag is untouched.\n   */\n  function onPointerleave(event: PointerEvent) {\n    const state = gesture.value\n    if (!state || state.pointerId !== event.pointerId || state.moved) return\n    abandon()\n  }\n\n  /*\n   * Paging swaps the cells out from under a live drag, and the dragged event's day is then off\n   * screen — the card would vanish until the next pointer move, which never comes if the hand is\n   * holding still against the edge. Re-applying the last position once the new cells are\n   * rendered is what keeps the card under the pointer across the boundary.\n   */\n  watch(\n    options.layout,\n    () => {\n      const state = gesture.value\n      if (state?.moved) reapply(state)\n    },\n    { flush: 'post' },\n  )\n\n  /**\n   * Hands the focus back to a card once it has landed somewhere else, which the re-render has\n   * just taken it from.\n   *\n   * TRAP — the card is found by WALKING the cards rather than by building an attribute\n   * selector. An id belongs to the consumer, so it may hold a quote or a backslash a selector\n   * would need escaped, and `CSS.escape` cannot do that escaping here: jsdom defines no `CSS`\n   * object at all, so the call threw on every keyboard grab, from inside a `nextTick` where\n   * nothing could catch it — an unhandled rejection, which fails the run while every assertion\n   * still passes. Comparing the attribute's own text sidesteps the question, `data-event-id`\n   * being written as exactly `String(event.id)`.\n   */\n  function refocusCard(id: CalendarEventId) {\n    void nextTick(() => {\n      // Searched from the view's root: the time grid's all-day bars sit in its sticky header,\n      // outside the box the cells occupy.\n      const cards = options.rootEl.value?.querySelectorAll<HTMLElement>('.v-calendar-event')\n      Array.from(cards ?? [])\n        .find((card) => card.dataset.eventId === String(id))\n        ?.focus()\n    })\n  }\n\n  /** Puts the focus on a cell by its id, once the render that made it tabbable has run. */\n  function focusCell(id: string, deferred = false, focusOptions?: FocusOptions) {\n    const move = () => document.getElementById(id)?.focus(focusOptions)\n    if (deferred) void nextTick(move)\n    else move()\n  }\n\n  /** The event a card stands for, read back off the attribute the card publishes. */\n  const idOfCard = (card: HTMLElement) => cardIdOf(card, (id) => options.eventOf(id) !== undefined)\n\n  /**\n   * A card answers a different table from the grid it sits in — that is what a grab mode IS.\n   * Without it the grid would offer a gesture the pointer alone could reach (WCAG 2.1.1).\n   */\n  function onCardKeydown(event: KeyboardEvent, card: HTMLElement) {\n    // Whatever click follows is this key's, never the end of an earlier drag.\n    dragged = false\n    const item = options.eventOf(idOfCard(card))\n    if (!item) return\n\n    const held = grabbing.value && gesture.value?.id === item.id\n    const state = held ? gesture.value! : null\n    const intent = calendarIntent(\n      event,\n      held ? 'grabbed' : 'event',\n      options.slotMinutes(),\n      state?.rtl ?? isRtl(),\n    )\n    if (!intent) return\n\n    if (!state) {\n      // An event that cannot be moved keeps a button's ordinary behaviour: Space presses it,\n      // which the card's click handler reports.\n      const init = intent.kind === 'grab' ? options.grab(item) : null\n      if (!init) return\n      /*\n       * Space is ALSO how a button is pressed, on its release. Cancelling the keydown is what\n       * stops that press, so the keystroke that takes hold of the event does not open it too:\n       * without it every attempt to move something would fire the consumer's editor over it.\n       */\n      event.preventDefault()\n      start(init)\n      options.announce(m.value.calendar.grabbed)\n      return\n    }\n\n    event.preventDefault()\n\n    if (intent.kind === 'grabMove' || intent.kind === 'grabResize') {\n      if (!options.onGrabStep(state, intent, item)) return\n      state.moved = true\n      refocusCard(state.id)\n      return\n    }\n\n    if (intent.kind === 'activate') {\n      gesture.value = null\n      if (state.moved) options.onDrop(state)\n      options.announce(m.value.calendar.dropped)\n      refocusCard(state.id)\n      return\n    }\n\n    if (intent.kind === 'cancel') {\n      revertGrab()\n      refocusCard(state.id)\n    }\n  }\n\n  /**\n   * The five things every card is told about the gesture, bound with `v-bind` so the two grids\n   * cannot describe the same state in two different ways.\n   */\n  function cardState(id: CalendarEventId) {\n    const state = gesture.value\n    const mine = state !== null && state.id === id\n    return {\n      /*\n       * TRAP — only once the press has travelled. A dragged card takes no pointer events, so\n       * marked at the press it lets the release land on the cell beneath it: the click then goes\n       * to that cell, and clicking an event reports an empty slot instead of opening it.\n       */\n      dragging: mine && state.pointerId !== null && state.moved,\n      rejected: mine && state.outside,\n      grabbed: mine && state.pointerId === null,\n      hintId: options.editable() && !isGhostId(id) ? options.hintId() : undefined,\n      ghostOf: isGhostId(id) ? originalIdOf(id) : undefined,\n    }\n  }\n\n  return {\n    gesture,\n    grabbing,\n    ghostEvent,\n    withPreview,\n    edgeCue,\n    isRtl,\n    start,\n    reapply,\n    release,\n    endLastGesture,\n    consumeDrag,\n    onPointermove,\n    onPointerup,\n    onPointercancel,\n    onPointerleave,\n    onFocusout,\n    onCardKeydown,\n    refocusCard,\n    focusCell,\n    idOfCard,\n    cardState,\n  }\n}\n"],"mappings":"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"}

package/dist/components/VCalendar/keyboard.d.ts

@@ -43,6 +43,10 @@ export type CalendarIntent =
  | {
     kind: 'activate';
 }
+/** Open the focused day, which only a month square offers. */
+ | {
+    kind: 'openDay';
+}
 /** Take hold of a card, so the arrows move it. */
  | {
     kind: 'grab';
@@ -65,20 +69,33 @@ export type CalendarIntent =
 /**
  * Where the focus is when the key arrives, which is what decides the answer:
  *
- * - `cell` — an empty part of the grid. The arrows travel, Enter creates.
- * - `event` — a card, at rest. Space takes hold of it; every other key is the browser's,
+ * - `cell`: an empty part of the grid. The arrows travel, Enter creates, Shift and Enter
+ *   open the day (a month square's number takes no tab stop, so this is its keyboard route).
+ * - `event`: a card, at rest. Space takes hold of it; every other key is the browser's,
  *   Enter included, which presses the card as a button and so opens the event. Enter is the
  *   one a reader tries first on a button, and `event-activate` has no other keyboard route.
- * - `grabbed` — a card being moved. The arrows now move the EVENT, Enter commits, Escape
+ * - `grabbed`: a card being moved. The arrows now move the EVENT, Enter commits, Escape
  *   puts it back where it was.
  */
 export type CalendarFocus = 'cell' | 'event' | 'grabbed';
+/** The part of a keyboard event the table reads; a `KeyboardEvent` is one. */
+export interface KeyChord {
+    key: string;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+}
 /**
  * What a key means. Returning nothing says the key is none of this table's business and
- * the event must be left entirely alone — which is what keeps Tab, the browser's own
+ * the event must be left entirely alone. That keeps keeps Tab, the browser's own
  * shortcuts and anything a consumer has bound working.
  *
+ * A key held with Alt, Ctrl or Meta is ALWAYS left alone, whatever it is: Alt+Left is the
+ * browser's Back and Ctrl+Home scrolls the page, and answering them here also cancelled them.
+ * Shift is part of the table.
+ *
  * `rtl` is passed in rather than read here: which way is "forward" is a property of the
  * document, and a pure table has no business consulting one.
  */
-export declare function calendarIntent(key: string, shiftKey: boolean, focus: CalendarFocus, slotMinutes: number, rtl: boolean): CalendarIntent | undefined;
+export declare function calendarIntent(chord: KeyChord, focus: CalendarFocus, slotMinutes: number, rtl: boolean): CalendarIntent | undefined;

package/dist/components/VCalendar/keyboard.js

@@ -1,48 +1,49 @@
 //#region src/components/VCalendar/keyboard.ts
-function e(e, t, n, r, i) {
-	let a = r > 0 ? r : 1, o = i ? -1 : 1;
-	if (n === "grabbed") switch (e) {
+function e(e, t, n, r) {
+	if (e.altKey || e.ctrlKey || e.metaKey) return;
+	let { key: i } = e, a = e.shiftKey === !0, o = n > 0 ? n : 1, s = r ? -1 : 1;
+	if (t === "grabbed") switch (i) {
 		case "ArrowLeft": return {
 			kind: "grabMove",
-			days: -o,
+			days: -s,
 			minutes: 0
 		};
 		case "ArrowRight": return {
 			kind: "grabMove",
-			days: o,
+			days: s,
 			minutes: 0
 		};
-		case "ArrowUp": return t ? {
+		case "ArrowUp": return a ? {
 			kind: "grabResize",
-			minutes: -a
+			minutes: -o
 		} : {
 			kind: "grabMove",
 			days: 0,
-			minutes: -a
+			minutes: -o
 		};
-		case "ArrowDown": return t ? {
+		case "ArrowDown": return a ? {
 			kind: "grabResize",
-			minutes: a
+			minutes: o
 		} : {
 			kind: "grabMove",
 			days: 0,
-			minutes: a
+			minutes: o
 		};
 		case "Enter":
 		case " ": return { kind: "activate" };
 		case "Escape": return { kind: "cancel" };
 		default: return;
 	}
-	if (n === "event") return e === " " ? { kind: "grab" } : void 0;
-	switch (e) {
+	if (t === "event") return i === " " ? { kind: "grab" } : void 0;
+	switch (i) {
 		case "ArrowLeft": return {
 			kind: "moveFocus",
-			days: -o,
+			days: -s,
 			minutes: 0
 		};
 		case "ArrowRight": return {
 			kind: "moveFocus",
-			days: o,
+			days: s,
 			minutes: 0
 		};
 		case "ArrowUp": return {
@@ -71,7 +72,7 @@ function e(e, t, n, r, i) {
 			kind: "period",
 			delta: 1
 		};
-		case "Enter":
+		case "Enter": return a ? { kind: "openDay" } : { kind: "activate" };
 		case " ": return { kind: "activate" };
 		default: return;
 	}

package/dist/components/VCalendar/keyboard.js.map

@@ -1 +1 @@
-{"version":3,"file":"keyboard.js","names":[],"sources":["../../../src/components/VCalendar/keyboard.ts"],"sourcesContent":["// @keyboard @a11y\n/**\n * The pure half of VCalendar's keyboard: it answers the single question \"what does this\n * key mean here?\", and does nothing else. Moving the focus, writing to the model, calling\n * `preventDefault` and announcing the result all stay in the component, where the reactive\n * state lives.\n *\n * It sits in VCalendar's own folder rather than in `utils/` because it has exactly one\n * consumer, which fails the admission rule for shared code (the same reasoning as\n * `VDatePicker/keyboard.ts` and `VHotkeys/platform.ts`). Being pure is also what makes the\n * whole keyboard testable without mounting anything, since the environment the tests run\n * in lays nothing out and the handlers in the component only ever move DOM focus.\n *\n * `utils/arrowNav` is deliberately not used. It navigates a flat DOM list of controls; this\n * navigates a two-dimensional space of DATES AND TIMES whose edges are a domain clamp, not\n * a list end — the same reason VDatePicker, VCombobox and VTimePicker stay out of it.\n *\n * WHY A GRAB MODE, and not arrows that move an event outright. Every gesture the pointer\n * offers has to have a keyboard equivalent (WCAG 2.1.1), and a card is reached by the\n * arrows in the first place — so if the arrows also moved it, arriving at an event and\n * nudging it would be the same keystroke, and there would be no way to pass over one\n * without dragging it. Entering a mode separates the two, and Escape gives back the one\n * thing a pointer drag has that a keypress does not: the chance to change your mind.\n */\n\nimport { MINUTES_PER_HOUR } from './layout'\n\n/** What one key means, given where the focus is. */\nexport type CalendarIntent =\n  /** Move the focused cell by whole days and whole hours. */\n  | { kind: 'moveFocus'; days: number; minutes: number }\n  /** Jump to the first or last day of the row. */\n  | { kind: 'rowEdge'; edge: 'start' | 'end' }\n  /** Show the previous or next period, as the toolbar's buttons do. */\n  | { kind: 'period'; delta: -1 | 1 }\n  /** Take up what is focused: report an empty cell, or commit a move under way. */\n  | { kind: 'activate' }\n  /** Take hold of a card, so the arrows move it. */\n  | { kind: 'grab' }\n  /** Abandon a move under way and put the event back. */\n  | { kind: 'cancel' }\n  /** Move the grabbed event. */\n  | { kind: 'grabMove'; days: number; minutes: number }\n  /** Change how long the grabbed event lasts. */\n  | { kind: 'grabResize'; minutes: number }\n\n/**\n * Where the focus is when the key arrives, which is what decides the answer:\n *\n * - `cell` — an empty part of the grid. The arrows travel, Enter creates.\n * - `event` — a card, at rest. Space takes hold of it; every other key is the browser's,\n *   Enter included, which presses the card as a button and so opens the event. Enter is the\n *   one a reader tries first on a button, and `event-activate` has no other keyboard route.\n * - `grabbed` — a card being moved. The arrows now move the EVENT, Enter commits, Escape\n *   puts it back where it was.\n */\nexport type CalendarFocus = 'cell' | 'event' | 'grabbed'\n\n/**\n * What a key means. Returning nothing says the key is none of this table's business and\n * the event must be left entirely alone — which is what keeps Tab, the browser's own\n * shortcuts and anything a consumer has bound working.\n *\n * `rtl` is passed in rather than read here: which way is \"forward\" is a property of the\n * document, and a pure table has no business consulting one.\n */\nexport function calendarIntent(\n  key: string,\n  shiftKey: boolean,\n  focus: CalendarFocus,\n  slotMinutes: number,\n  rtl: boolean,\n): CalendarIntent | undefined {\n  const step = slotMinutes > 0 ? slotMinutes : 1\n  // The inline arrows follow the reading direction; the block ones never do, because down\n  // is later in the day in every script.\n  const inline = rtl ? -1 : 1\n\n  if (focus === 'grabbed') {\n    switch (key) {\n      case 'ArrowLeft':\n        return { kind: 'grabMove', days: -inline, minutes: 0 }\n      case 'ArrowRight':\n        return { kind: 'grabMove', days: inline, minutes: 0 }\n      case 'ArrowUp':\n        return shiftKey\n          ? { kind: 'grabResize', minutes: -step }\n          : { kind: 'grabMove', days: 0, minutes: -step }\n      case 'ArrowDown':\n        return shiftKey\n          ? { kind: 'grabResize', minutes: step }\n          : { kind: 'grabMove', days: 0, minutes: step }\n      case 'Enter':\n      case ' ':\n        return { kind: 'activate' }\n      case 'Escape':\n        return { kind: 'cancel' }\n      default:\n        return undefined\n    }\n  }\n\n  if (focus === 'event') return key === ' ' ? { kind: 'grab' } : undefined\n\n  switch (key) {\n    case 'ArrowLeft':\n      return { kind: 'moveFocus', days: -inline, minutes: 0 }\n    case 'ArrowRight':\n      return { kind: 'moveFocus', days: inline, minutes: 0 }\n    case 'ArrowUp':\n      return { kind: 'moveFocus', days: 0, minutes: -MINUTES_PER_HOUR }\n    case 'ArrowDown':\n      return { kind: 'moveFocus', days: 0, minutes: MINUTES_PER_HOUR }\n    case 'Home':\n      return { kind: 'rowEdge', edge: 'start' }\n    case 'End':\n      return { kind: 'rowEdge', edge: 'end' }\n    case 'PageUp':\n      return { kind: 'period', delta: -1 }\n    case 'PageDown':\n      return { kind: 'period', delta: 1 }\n    case 'Enter':\n    case ' ':\n      return { kind: 'activate' }\n    default:\n      return undefined\n  }\n}\n"],"mappings":";AAkEA,SAAgB,EACd,GACA,GACA,GACA,GACA,GAC4B;CAC5B,IAAM,IAAO,IAAc,IAAI,IAAc,GAGvC,IAAS,IAAM,KAAK;CAE1B,IAAI,MAAU,WACZ,QAAQ,GAAR;EACE,KAAK,aACH,OAAO;GAAE,MAAM;GAAY,MAAM,CAAC;GAAQ,SAAS;EAAE;EACvD,KAAK,cACH,OAAO;GAAE,MAAM;GAAY,MAAM;GAAQ,SAAS;EAAE;EACtD,KAAK,WACH,OAAO,IACH;GAAE,MAAM;GAAc,SAAS,CAAC;EAAK,IACrC;GAAE,MAAM;GAAY,MAAM;GAAG,SAAS,CAAC;EAAK;EAClD,KAAK,aACH,OAAO,IACH;GAAE,MAAM;GAAc,SAAS;EAAK,IACpC;GAAE,MAAM;GAAY,MAAM;GAAG,SAAS;EAAK;EACjD,KAAK;EACL,KAAK,KACH,OAAO,EAAE,MAAM,WAAW;EAC5B,KAAK,UACH,OAAO,EAAE,MAAM,SAAS;EAC1B,SACE;CACJ;CAGF,IAAI,MAAU,SAAS,OAAO,MAAQ,MAAM,EAAE,MAAM,OAAO,IAAI,KAAA;CAE/D,QAAQ,GAAR;EACE,KAAK,aACH,OAAO;GAAE,MAAM;GAAa,MAAM,CAAC;GAAQ,SAAS;EAAE;EACxD,KAAK,cACH,OAAO;GAAE,MAAM;GAAa,MAAM;GAAQ,SAAS;EAAE;EACvD,KAAK,WACH,OAAO;GAAE,MAAM;GAAa,MAAM;GAAG,SAAS;EAAkB;EAClE,KAAK,aACH,OAAO;GAAE,MAAM;GAAa,MAAM;GAAG,SAAA;EAA0B;EACjE,KAAK,QACH,OAAO;GAAE,MAAM;GAAW,MAAM;EAAQ;EAC1C,KAAK,OACH,OAAO;GAAE,MAAM;GAAW,MAAM;EAAM;EACxC,KAAK,UACH,OAAO;GAAE,MAAM;GAAU,OAAO;EAAG;EACrC,KAAK,YACH,OAAO;GAAE,MAAM;GAAU,OAAO;EAAE;EACpC,KAAK;EACL,KAAK,KACH,OAAO,EAAE,MAAM,WAAW;EAC5B,SACE;CACJ;AACF"}
+{"version":3,"file":"keyboard.js","names":[],"sources":["../../../src/components/VCalendar/keyboard.ts"],"sourcesContent":["// @keyboard @a11y\n/**\n * The pure half of VCalendar's keyboard: it answers the single question \"what does this\n * key mean here?\", and does nothing else. Moving the focus, writing to the model, calling\n * `preventDefault` and announcing the result all stay in the component, where the reactive\n * state lives.\n *\n * It sits in VCalendar's own folder rather than in `utils/` because it has exactly one\n * consumer, which fails the admission rule for shared code (the same reasoning as\n * `VDatePicker/keyboard.ts` and `VHotkeys/platform.ts`). Being pure is also what makes the\n * whole keyboard testable without mounting anything, since the environment the tests run\n * in lays nothing out and the handlers in the component only ever move DOM focus.\n *\n * `utils/arrowNav` is deliberately not used. It navigates a flat DOM list of controls; this\n * navigates a two-dimensional space of DATES AND TIMES whose edges are a domain clamp, not\n * a list end — the same reason VDatePicker, VCombobox and VTimePicker stay out of it.\n *\n * WHY A GRAB MODE, and not arrows that move an event outright. Every gesture the pointer\n * offers has to have a keyboard equivalent (WCAG 2.1.1), and a card is reached by the\n * arrows in the first place — so if the arrows also moved it, arriving at an event and\n * nudging it would be the same keystroke, and there would be no way to pass over one\n * without dragging it. Entering a mode separates the two, and Escape gives back the one\n * thing a pointer drag has that a keypress does not: the chance to change your mind.\n */\n\nimport { MINUTES_PER_HOUR } from './layout'\n\n/** What one key means, given where the focus is. */\nexport type CalendarIntent =\n  /** Move the focused cell by whole days and whole hours. */\n  | { kind: 'moveFocus'; days: number; minutes: number }\n  /** Jump to the first or last day of the row. */\n  | { kind: 'rowEdge'; edge: 'start' | 'end' }\n  /** Show the previous or next period, as the toolbar's buttons do. */\n  | { kind: 'period'; delta: -1 | 1 }\n  /** Take up what is focused: report an empty cell, or commit a move under way. */\n  | { kind: 'activate' }\n  /** Open the focused day, which only a month square offers. */\n  | { kind: 'openDay' }\n  /** Take hold of a card, so the arrows move it. */\n  | { kind: 'grab' }\n  /** Abandon a move under way and put the event back. */\n  | { kind: 'cancel' }\n  /** Move the grabbed event. */\n  | { kind: 'grabMove'; days: number; minutes: number }\n  /** Change how long the grabbed event lasts. */\n  | { kind: 'grabResize'; minutes: number }\n\n/**\n * Where the focus is when the key arrives, which is what decides the answer:\n *\n * - `cell`: an empty part of the grid. The arrows travel, Enter creates, Shift and Enter\n *   open the day (a month square's number takes no tab stop, so this is its keyboard route).\n * - `event`: a card, at rest. Space takes hold of it; every other key is the browser's,\n *   Enter included, which presses the card as a button and so opens the event. Enter is the\n *   one a reader tries first on a button, and `event-activate` has no other keyboard route.\n * - `grabbed`: a card being moved. The arrows now move the EVENT, Enter commits, Escape\n *   puts it back where it was.\n */\nexport type CalendarFocus = 'cell' | 'event' | 'grabbed'\n\n/** The part of a keyboard event the table reads; a `KeyboardEvent` is one. */\nexport interface KeyChord {\n  key: string\n  shiftKey?: boolean\n  altKey?: boolean\n  ctrlKey?: boolean\n  metaKey?: boolean\n}\n\n/**\n * What a key means. Returning nothing says the key is none of this table's business and\n * the event must be left entirely alone. That keeps keeps Tab, the browser's own\n * shortcuts and anything a consumer has bound working.\n *\n * A key held with Alt, Ctrl or Meta is ALWAYS left alone, whatever it is: Alt+Left is the\n * browser's Back and Ctrl+Home scrolls the page, and answering them here also cancelled them.\n * Shift is part of the table.\n *\n * `rtl` is passed in rather than read here: which way is \"forward\" is a property of the\n * document, and a pure table has no business consulting one.\n */\nexport function calendarIntent(\n  chord: KeyChord,\n  focus: CalendarFocus,\n  slotMinutes: number,\n  rtl: boolean,\n): CalendarIntent | undefined {\n  if (chord.altKey || chord.ctrlKey || chord.metaKey) return undefined\n  const { key } = chord\n  const shiftKey = chord.shiftKey === true\n  const step = slotMinutes > 0 ? slotMinutes : 1\n  // The inline arrows follow the reading direction; the block ones never do, because down\n  // is later in the day in every script.\n  const inline = rtl ? -1 : 1\n\n  if (focus === 'grabbed') {\n    switch (key) {\n      case 'ArrowLeft':\n        return { kind: 'grabMove', days: -inline, minutes: 0 }\n      case 'ArrowRight':\n        return { kind: 'grabMove', days: inline, minutes: 0 }\n      case 'ArrowUp':\n        return shiftKey\n          ? { kind: 'grabResize', minutes: -step }\n          : { kind: 'grabMove', days: 0, minutes: -step }\n      case 'ArrowDown':\n        return shiftKey\n          ? { kind: 'grabResize', minutes: step }\n          : { kind: 'grabMove', days: 0, minutes: step }\n      case 'Enter':\n      case ' ':\n        return { kind: 'activate' }\n      case 'Escape':\n        return { kind: 'cancel' }\n      default:\n        return undefined\n    }\n  }\n\n  if (focus === 'event') return key === ' ' ? { kind: 'grab' } : undefined\n\n  switch (key) {\n    case 'ArrowLeft':\n      return { kind: 'moveFocus', days: -inline, minutes: 0 }\n    case 'ArrowRight':\n      return { kind: 'moveFocus', days: inline, minutes: 0 }\n    case 'ArrowUp':\n      return { kind: 'moveFocus', days: 0, minutes: -MINUTES_PER_HOUR }\n    case 'ArrowDown':\n      return { kind: 'moveFocus', days: 0, minutes: MINUTES_PER_HOUR }\n    case 'Home':\n      return { kind: 'rowEdge', edge: 'start' }\n    case 'End':\n      return { kind: 'rowEdge', edge: 'end' }\n    case 'PageUp':\n      return { kind: 'period', delta: -1 }\n    case 'PageDown':\n      return { kind: 'period', delta: 1 }\n    case 'Enter':\n      return shiftKey ? { kind: 'openDay' } : { kind: 'activate' }\n    case ' ':\n      return { kind: 'activate' }\n    default:\n      return undefined\n  }\n}\n"],"mappings":";AAkFA,SAAgB,EACd,GACA,GACA,GACA,GAC4B;CAC5B,IAAI,EAAM,UAAU,EAAM,WAAW,EAAM,SAAS;CACpD,IAAM,EAAE,WAAQ,GACV,IAAW,EAAM,aAAa,IAC9B,IAAO,IAAc,IAAI,IAAc,GAGvC,IAAS,IAAM,KAAK;CAE1B,IAAI,MAAU,WACZ,QAAQ,GAAR;EACE,KAAK,aACH,OAAO;GAAE,MAAM;GAAY,MAAM,CAAC;GAAQ,SAAS;EAAE;EACvD,KAAK,cACH,OAAO;GAAE,MAAM;GAAY,MAAM;GAAQ,SAAS;EAAE;EACtD,KAAK,WACH,OAAO,IACH;GAAE,MAAM;GAAc,SAAS,CAAC;EAAK,IACrC;GAAE,MAAM;GAAY,MAAM;GAAG,SAAS,CAAC;EAAK;EAClD,KAAK,aACH,OAAO,IACH;GAAE,MAAM;GAAc,SAAS;EAAK,IACpC;GAAE,MAAM;GAAY,MAAM;GAAG,SAAS;EAAK;EACjD,KAAK;EACL,KAAK,KACH,OAAO,EAAE,MAAM,WAAW;EAC5B,KAAK,UACH,OAAO,EAAE,MAAM,SAAS;EAC1B,SACE;CACJ;CAGF,IAAI,MAAU,SAAS,OAAO,MAAQ,MAAM,EAAE,MAAM,OAAO,IAAI,KAAA;CAE/D,QAAQ,GAAR;EACE,KAAK,aACH,OAAO;GAAE,MAAM;GAAa,MAAM,CAAC;GAAQ,SAAS;EAAE;EACxD,KAAK,cACH,OAAO;GAAE,MAAM;GAAa,MAAM;GAAQ,SAAS;EAAE;EACvD,KAAK,WACH,OAAO;GAAE,MAAM;GAAa,MAAM;GAAG,SAAS;EAAkB;EAClE,KAAK,aACH,OAAO;GAAE,MAAM;GAAa,MAAM;GAAG,SAAA;EAA0B;EACjE,KAAK,QACH,OAAO;GAAE,MAAM;GAAW,MAAM;EAAQ;EAC1C,KAAK,OACH,OAAO;GAAE,MAAM;GAAW,MAAM;EAAM;EACxC,KAAK,UACH,OAAO;GAAE,MAAM;GAAU,OAAO;EAAG;EACrC,KAAK,YACH,OAAO;GAAE,MAAM;GAAU,OAAO;EAAE;EACpC,KAAK,SACH,OAAO,IAAW,EAAE,MAAM,UAAU,IAAI,EAAE,MAAM,WAAW;EAC7D,KAAK,KACH,OAAO,EAAE,MAAM,WAAW;EAC5B,SACE;CACJ;AACF"}

package/dist/components/VCalendar/layout.d.ts

@@ -23,10 +23,10 @@ export declare function windowOf(startHour: number, endHour: number): TimeWindow
 /**
  * Minutes since midnight back into an `HH:mm` string.
  *
- * TRAP — the value is held one minute short of midnight rather than allowed to reach it.
+ * TRAP: the value is held one minute short of midnight rather than allowed to reach it.
  * A day's last moment is 1440 in this arithmetic, but `24:00` is not a time any of the
- * design system's helpers accept (`isValidTime` rejects it), and the alternative — writing
- * `00:00` on the following day — would turn an ordinary evening appointment into one that
+ * design system's helpers accept (`isValidTime` rejects it). Writing
+ * `00:00` on the following day would turn an ordinary evening appointment into one that
  * runs past midnight, which every gesture then treats differently. One minute is invisible at
  * every zoom this component offers; an event that changed kind under the pointer is not.
  */
@@ -36,8 +36,8 @@ export declare function minutesAt(time: string | undefined, fallback: number): n
 /**
  * The weekdays a calendar shows, in reading order.
  *
- * The array does double duty: it says which days are VISIBLE — `[1,2,3,4,5]` hides the
- * weekend everywhere — and its first entry is the day a week starts on. Given nothing, the
+ * The array does double duty: it says which days are VISIBLE: `[1,2,3,4,5]` hides the
+ * weekend everywhere, and its first entry is the day a week starts on. Given nothing, the
  * seven days rotated to `firstDayOfWeek`, which the calendar takes from its prop of that
  * name or from the locale.
  */
@@ -48,7 +48,7 @@ export declare function isVisibleDay(iso: string, weekdays: readonly number[]):
  * The first visible day at or after `iso` (or at or before it, going backwards).
  *
  * The loop is bounded at seven because a non-empty weekday list always contains one of any
- * seven consecutive days — the bound is a guard against an empty list, never a real limit.
+ * seven consecutive days: the bound is a guard against an empty list, never a real limit.
  */
 export declare function snapToVisibleDay(iso: string, weekdays: readonly number[], direction?: -1 | 1): string;
 /** Moves `count` VISIBLE days from `iso`, skipping over the hidden ones. */
@@ -61,7 +61,7 @@ export declare function columnCount(view: CalendarView, customDays: number): num
  * `day`, `4days` and `custom` run forward from the anchor over the visible days alone, so
  * a four-day view of a Monday-to-Friday calendar shows four WORKING days rather than four
  * calendar ones. `week` shows the week the anchor falls in, starting on `weekdays[0]`.
- * `month` returns every day of the anchor's month that is visible — the grid that renders
+ * `month` returns every day of the anchor's month that is visible: the grid that renders
  * them cuts them back into weeks itself.
  *
  * `year` returns an empty list on purpose: that view is twelve month names, not a row of
@@ -71,7 +71,7 @@ export declare function visibleDays(anchor: string, view: CalendarView, weekdays
 /**
  * Where Previous and Next land.
  *
- * TRAP — the day-shaped views step over VISIBLE days, not calendar ones. Stepping by one
+ * TRAP: the day-shaped views step over VISIBLE days, not calendar ones. Stepping by one
  * calendar day from a Friday in a Monday-to-Friday calendar would land on a Saturday the
  * grid does not draw; the view would then show the same week it already showed, and the
  * button would look broken with nothing in the console to say why.
@@ -85,8 +85,8 @@ export declare function visibleRange(anchor: string, view: CalendarView, weekday
 /**
  * How long an event lasts, in minutes, counting the days between its dates.
  *
- * A time that is not one reads as the far end of its day — midnight for a start, the next
- * midnight for an end — so a malformed event errs towards being long, and towards the band.
+ * A time that is not one reads as the far end of its day: midnight for a start, the next
+ * midnight for an end, so a malformed event errs towards being long, and towards the band.
  */
 export declare function durationOf(times: CalendarEventTimes): number;
 /** Whether an event runs from one day into the next without lasting a whole day. */
@@ -95,8 +95,8 @@ export declare function spansMidnight(times: CalendarEventTimes): boolean;
  * Whether an event belongs in the band above the grid rather than in a day's column.
  *
  * A day's column holds up to twenty-four hours, so an event running past midnight for less
- * than that is drawn as two cards — the evening in one column, the early morning in the next —
- * and only one lasting a whole day or more becomes a bar. Exactly twenty-four hours is a bar:
+ * than that is drawn as two cards, the evening in one column and the early morning in the next.
+ * Only one lasting a whole day or more becomes a bar. Exactly twenty-four hours is a bar:
  * two cards covering the same hours of two columns would read as two events.
  *
  * An event whose end comes before its start has no column to go in either, so it goes to the
@@ -128,9 +128,9 @@ export interface EventSegment {
     part: SegmentPart;
 }
 /**
- * Cuts the timed events into the boxes the day columns draw. All-day events produce none —
- * they are the band's business — and so does an event whose day is not on show or whose
- * hours fall entirely outside the window.
+ * Cuts the timed events into the boxes the day columns draw. All-day events produce none;
+ * they belong in the band. Nor does an event whose day is not on show or whose hours fall
+ * entirely outside the window.
  *
  * `minDuration` is applied HERE, by stretching the end, so that `packDayColumn` below sees
  * ordinary intervals and can stay a plain interval algorithm. Were the minimum applied
@@ -142,7 +142,7 @@ export declare function timedSegments(events: readonly CalendarEvent[], days: re
 export interface PlacedSegment extends EventSegment {
     /** Which column of its cluster it sits in, counted from zero. */
     column: number;
-    /** How many columns it takes up — more than one when the room beside it is free. */
+    /** How many columns it takes up: more than one when the room beside it is free. */
     span: number;
     /** How many columns its cluster has. It is what both of the above are read against. */
     columns: number;
@@ -150,7 +150,7 @@ export interface PlacedSegment extends EventSegment {
 /**
  * Shares one day's width out between the events happening at the same time.
  *
- * Three passes. First the segments are cut into CLUSTERS — runs joined by overlap, where an
+ * Three passes. First the segments are cut into CLUSTERS: runs joined by overlap, where an
  * event starting after everything before it has finished begins a new one. That is what
  * stops a crowded morning from squeezing a lone afternoon meeting into a sliver. Then,
  * inside a cluster, each event takes the first column whose last occupant has already
@@ -159,13 +159,13 @@ export interface PlacedSegment extends EventSegment {
  * nothing in the next column overlaps it, so a single event never leaves a gap it could
  * have filled.
  *
- * The order is fixed — by start, then longest first, then by id — so the same list always
+ * The order is fixed by start, then longest first, then by id, so the same list always
  * produces the same picture. Without the id to break the last tie, two events at the same
  * time for the same length would swap places whenever the array was re-sorted, and the
  * whole day would appear to shuffle for no reason.
  *
- * Overlap is strictly `a.start < b.end && b.start < a.end`, so events that merely touch —
- * one ending exactly as the next begins — share a column instead of splitting the width.
+ * Overlap is strictly `a.start < b.end && b.start < a.end`, so events that merely touch
+ * (one ending exactly as the next begins) share a column instead of splitting the width.
  */
 export declare function packDayColumn(segments: readonly EventSegment[]): PlacedSegment[];
 /**
@@ -180,8 +180,8 @@ export type { MonthCell };
 /**
  * The month view, cut into weeks.
  *
- * It keeps the fixed six rows `buildMonthGrid` produces — padded with the neighbouring
- * months — so the grid is the same height whichever month is on show and the page does not
+ * It keeps the fixed six rows `buildMonthGrid` produces: padded with the neighbouring
+ * months, so the grid is the same height whichever month is on show and the page does not
  * jump as one steps through the year. Each row is then filtered down to the visible
  * weekdays, which is what makes a Monday-to-Friday month five columns wide rather than
  * seven with two blanks.
@@ -189,6 +189,16 @@ export type { MonthCell };
 export declare function monthWeeks(anchor: string, weekdays: readonly number[]): MonthCell[][];
 /** The first day of each month of the anchor's year, which is what the year view lays out. */
 export declare function monthsOfYear(anchor: string): string[];
+/**
+ * The last day an event puts anything on.
+ *
+ * Its `end` date, except for a timed event ending at midnight EXACTLY: it has nothing on
+ * that day, which is why `timedSegments` draws it whole on its first day. Every other view
+ * has to agree, or twenty-four hours from one midnight to the next becomes a two-day bar and
+ * an evening ending at 00:00 is listed on the following day too. An all-day event's dates
+ * are whole days, so its end is kept as it stands.
+ */
+export declare function lastDayOf(event: CalendarEvent): string;
 /** Whether an event covers a given day at all, all-day or timed. */
 export declare function coversDay(event: CalendarEvent, iso: string): boolean;
 /**
@@ -198,12 +208,12 @@ export declare function coversDay(event: CalendarEvent, iso: string): boolean;
  *
  * WHY ONE PASS RATHER THAN A FILTER PER DAY. The month view needs all 42 squares filled, and
  * filtering and sorting the list once per square walks the whole event list 42 times and sorts
- * it 42 times — `cells × events`, with a sort each. Measured on the bench: 7.8 ms per render at
+ * it 42 times: `cells × events`, with a sort each. Measured on the bench: 7.8 ms per render at
  * 2000 events, and the month view rebuilds it every time a drag carries a chip onto another
  * day, so that is roughly half a frame spent rebuilding lists the gesture left alone.
  *
  * Here each event is placed once, into the days it actually covers, and each day is sorted
- * once — `events × span + cells × k log k`. The walk is bounded to the grid on both ends, so
+ * once: `events × span + cells × k log k`. The walk is bounded to the grid on both ends, so
  * an event running from last year costs its visible part and nothing more.
  */
 export declare function eventsByDay<T extends CalendarEvent>(events: readonly T[], days: readonly string[]): Map<string, T[]>;
@@ -229,8 +239,8 @@ export interface AllDaySpan {
  * one day on the Friday and one on the following Monday, because those are the two days it
  * actually covers on screen.
  *
- * The rows are the same greedy pass the day columns use — each bar takes the first row
- * whose last bar has already ended — and the ordering is fixed, longest first at equal
+ * The rows are the same greedy pass the day columns use: each bar takes the first row
+ * whose last bar has already ended, and the ordering is fixed, longest first at equal
  * starts, so the band cannot reshuffle when the array is re-sorted.
  */
 export declare function packAllDay(events: readonly CalendarEvent[], days: readonly string[]): AllDaySpan[];
@@ -250,7 +260,7 @@ export interface GridGeometry {
  * and what moment that height stands for.
  *
  * Both answers are brought back inside the grid, so a pointer dragged past an edge keeps
- * producing the nearest sensible value rather than none — which is what makes a drag that
+ * producing the nearest sensible value rather than none. That is what makes a drag that
  * wanders off the component behave as the user expects instead of stopping dead.
  */
 export declare function pointToCell(point: {
@@ -262,10 +272,10 @@ export declare function pointToCell(point: {
 };
 /** Rounds a moment to the nearest step the calendar allows. */
 export declare function snapToSlot(minutes: number, step: number): number;
-/** Rounds a moment DOWN to the step containing it — where a drawn slot begins. */
+/** Rounds a moment DOWN to the step containing it: where a drawn slot begins. */
 export declare function floorToSlot(minutes: number, step: number): number;
 /**
- * How many whole days an event covers beyond its first — zero for one that starts and ends
+ * How many whole days an event covers beyond its first: zero for one that starts and ends
  * on the same day, two for a trip from Monday to Wednesday.
  */
 export declare function daySpan(times: CalendarEventTimes): number;
@@ -275,11 +285,11 @@ export declare function daySpan(times: CalendarEventTimes): number;
  * This is the counterpart of `timeGrid.ts`'s `moveEvent`, and the two must not be confused: that one is for
  * a timed move INSIDE a single day and deliberately collapses `end` onto `start`, so putting
  * a three-day trip through it would silently squash it into one Tuesday. This one is for the
- * whole-day gestures — an all-day bar dragged along the band, a chip dragged across a month —
+ * whole-day gestures (an all-day bar dragged along the band, a chip dragged across a month),
  * where the times are carried along untouched and only the dates move.
  */
 export declare function moveEventToDay(origin: CalendarEventTimes, target: string): CalendarEventTimes;
-/** The measurements of a month grid — the same struct, with rows where a time window was. */
+/** The measurements of a month grid: the same struct, with rows where a time window was. */
 export interface MonthGeometry extends GridGeometry {
     rows: number;
 }
@@ -287,7 +297,7 @@ export interface MonthGeometry extends GridGeometry {
  * Turns a point on the screen into a square of the month.
  *
  * The block axis is a ROW here rather than a moment, which is the whole difference from
- * `pointToCell` — the inline half is the same arithmetic, RTL flip included. It is sound
+ * `pointToCell`: the inline half is the same arithmetic, RTL flip included. It is sound
  * because every week of a month is drawn the same height: the rows share what space there is
  * and a day too full for its box clips rather than growing.
  */
@@ -303,7 +313,7 @@ export declare function pointToMonthCell(point: {
  * edge, 1 for the end one, nothing in between.
  *
  * It answers in READING order, so the start edge is the left one normally and the right one
- * in a right-to-left page — which is what makes "hold at the edge to go back" mean the same
+ * in a right-to-left page. That makes "hold at the edge to go back" mean the same
  * thing in both.
  */
 export declare function inlineEdgeAt(x: number, geometry: {
@@ -323,7 +333,7 @@ export declare function blockEdgeAt(y: number, geometry: {
     height: number;
 }, band: number): number;
 /**
- * Whether a point falls inside a box — how a drag decides, on release, whether it is over the
+ * Whether a point falls inside a box: how a drag decides, on release, whether it is over the
  * calendar at all or over the toolbar, or over the page beside it.
  *
  * It takes the box as the browser MEASURED it, and never the `GridGeometry` the rest of this file
@@ -336,10 +346,10 @@ export declare function blockEdgeAt(y: number, geometry: {
  * The edges COUNT as inside: a rect is a pair of floats on a screen that may be scaled by a
  * fraction, and an exclusive boundary would refuse a drop that looked, and was, on target.
  *
- * TRAP — a box that measures nothing contains EVERYTHING. That is the same answer `inlineEdgeAt`
+ * TRAP: a box that measures nothing contains EVERYTHING. That is the same answer `inlineEdgeAt`
  * and `blockEdgeAt` give a box of no size, and for the same reason: with no measurement there is
  * no outside to be on. Take a zero-size box literally instead and the calendar refuses every drop
- * wherever nothing has been laid out — in a hidden tab, before the first frame, and in jsdom,
+ * wherever nothing has been laid out: in a hidden tab, before the first frame, and in jsdom,
  * which measures nothing at all and where all but a handful of the drag tests would go red at
  * once.
  */
@@ -359,7 +369,7 @@ export declare function timesOf(event: CalendarEvent): CalendarEventTimes;
  *
  * It is what a drag asks before it writes its preview. A slot is a quarter of an hour, some
  * sixteen pixels at the default hour height, so most pointer moves land on the times already
- * shown — and the gesture state is deeply reactive, so an EQUAL but new object would still
+ * shown, and the gesture state is deeply reactive, so an EQUAL but new object would still
  * re-run the whole layout and re-render every cell of the grid for a picture that did not
  * change.
  */