@flamingo-stack/openframe-frontend-core 0.0.560 → 0.0.561-1846.5000.1

package/src/components/ui/date-picker.tsx

@@ -100,12 +100,18 @@ interface CalendarNavButtonProps {
   "aria-label"?: string;
 }
 
+/** The DS icon button, at its standard size in every placement — month
+ *  navigation is a primary control, not chrome to be shrunk to fit. What has
+ *  to give instead is the calendar's WIDTH: a `bare` host states one wide
+ *  enough for the caption to sit between the two buttons (see the meeting
+ *  scheduler's `CALENDAR_W`). */
 function CalendarNavButton({ direction, onClick, disabled, "aria-label": ariaLabel }: CalendarNavButtonProps) {
   return (
     <Button
       type="button"
       variant="outline"
       size="icon"
+      className="shrink-0"
       onClick={onClick}
       disabled={disabled}
       aria-label={ariaLabel}
@@ -118,7 +124,7 @@ function CalendarNavButton({ direction, onClick, disabled, "aria-label": ariaLab
 // DatePickerCalendar Component
 // ============================================================================
 
-interface DatePickerCalendarProps {
+export interface DatePickerCalendarProps {
   mode: DatePickerMode;
   selected: Date | DateRange | undefined;
   onSelect: (value: Date | DateRange | undefined) => void;
@@ -132,9 +138,54 @@ interface DatePickerCalendarProps {
    * lines up with the surrounding controls per the Figma filter-menu.
    */
   fluid?: boolean;
+  /**
+   * The calendar ALONE — the Figma `Date Picker` component as drawn, with no
+   * card surface and no outer inset: the nav header flush to both edges, 8px,
+   * then a full-bleed grid. Seven columns divide the container, so the
+   * cells are as wide as the host makes them.
+   *
+   * FIXED 272px tall at every one of those widths (8 + the 48px icon-button
+   * header + a 24px weekday strip + six 32px rows; 268 on a phone, where the
+   * DS icon button is 44), which is the design's own contract — the
+   * component is drawn 240 tall at 340, 282 and 240 wide. Height that ignored
+   * the width is what lets a host place it in a card that states a height, and
+   * keeps a phone-width month from becoming a 356px band.
+   *
+   * The DAY inside each cell stays square, so the selection and today's tint
+   * read as rounded squares rather than as pills stretched across a wide
+   * cell.
+   *
+   * For hosts that place the calendar inside a panel they already own — the
+   * meeting scheduler — where the standalone card chrome reads as a card
+   * inside a card and its 16px inset fights the panel's own 24px one. The
+   * popover and filter-menu keep the surface; nothing about the type, colours
+   * or day states changes between the two.
+   */
+  bare?: boolean;
+  /**
+   * Days to disable ON TOP of the `fromDate`/`toDate` bounds — a matcher, so a
+   * host can disable by predicate. "Inside the allowed window" and "actually
+   * selectable" are different questions, and only the host can answer the
+   * second (the meeting scheduler greys out days with no bookable slot).
+   */
+  disabledDays?: Matcher | Matcher[];
+  /**
+   * Controlled visible month; pair with `onMonthChange`. Omit both and the
+   * calendar owns its month, which is the right default — a host needs these
+   * only when paging is ALSO a data event, e.g. the scheduler refetches
+   * availability per month and would otherwise show an unpopulated month.
+   */
+  month?: Date;
+  onMonthChange?: (month: Date) => void;
 }
 
-function DatePickerCalendar({
+/**
+ * The calendar surface behind every date control in the design system —
+ * `DatePicker`'s popover and `DateFilterMenu` — exported so a host that needs
+ * an always-visible day grid renders THIS one. A second hand-styled day grid
+ * is how the two drift apart.
+ */
+export function DatePickerCalendar({
   mode,
   selected,
   onSelect,
@@ -143,6 +194,10 @@ function DatePickerCalendar({
   toDate,
   locale,
   fluid = false,
+  bare = false,
+  disabledDays: extraDisabledDays,
+  month: monthProp,
+  onMonthChange,
 }: DatePickerCalendarProps) {
   const today = new Date();
 
@@ -199,19 +254,105 @@ function DatePickerCalendar({
   };
 
   // Fixed 40px cells by default; in fluid mode cells flex to fill the width.
-  const cellOuter = fluid ? "flex-1 aspect-square min-w-0" : "size-10";
-  const cellInner = fluid ? "size-full" : "size-10";
+  // `bare` is a fluid layout by definition — its cell size IS container/7.
+  const isFluid = fluid || bare;
+  // BARE: fixed row height, elastic width — the Figma component is 240px tall
+  // at every width it is drawn at (340 on a phone, 282 on a tablet, 240 on the
+  // desktop card), so a month occupies the same band whatever column it lands
+  // in. 8 + the 48px header + a 24px weekday strip + six 32px rows = 272.
+  //
+  // Height that does NOT follow the width is the whole point: seven square
+  // cells across a phone's 340px would be a 356px-tall month, half again what
+  // the design budgets, and the same rule handed a wide column a month tall
+  // enough to push a card that states its height.
+  const cellOuter = bare ? "flex-1 min-w-0 h-[32px]" : isFluid ? "flex-1 aspect-square min-w-0" : "size-10";
+  // ...but the DAY ITSELF stays square inside that wider cell: `h-full` gives
+  // the button the row's height and `aspect-square` turns it into a 32x32
+  // rounded square, centred by the cell. `w-auto` is load-bearing — it drops
+  // the width the button would otherwise take, leaving `aspect-square` inert.
+  //
+  // This is why the day STATES below are painted on the button in bare mode
+  // rather than on the cell: react-day-picker puts `selected`/`today` on the
+  // cell, and a cell 48px wide by 30 tall renders the selection as a stretched
+  // pill. Same colours, same radius, smaller box.
+  const cellInner = bare
+    ? "h-full w-auto aspect-square rounded-[6px]"
+    : isFluid
+      ? "size-full"
+      : "size-10";
+  // The weekday strip is a LABEL row, not a day: `bare` gives it the height of
+  // its own text rather than a full row.
+  const weekdayOuter = bare ? "flex-1 min-w-0 h-6" : cellOuter;
+
+  // Day states, per paint target (see `cellInner`). Range mode is never bare —
+  // a range MUST fill its cells or the middle would break into islands — so
+  // only these three single-day states fork.
+  const hoverClass = bare ? "[&>button]:hover:bg-ods-bg-surface" : "hover:bg-ods-bg-surface hover:rounded-[6px]";
+  const todayClass = bare
+    ? "[&>button]:bg-ods-bg-surface [&>button]:hover:!bg-ods-bg-surface"
+    : "bg-ods-bg-surface rounded-[6px] hover:!bg-ods-bg-surface";
+  /**
+   * Today's tint applies only while today is NOT part of the selection.
+   *
+   * Both states paint the same box, and both have to use `!important` to beat
+   * react-day-picker's concatenated base classes — so on hover the two rules
+   * had equal specificity and the winner came down to their order in the
+   * generated stylesheet. Today's tint won, and a selected today turned GREY
+   * under the pointer, as if it had been deselected.
+   *
+   * Deciding it here rather than in CSS: "today" is a hint about where you
+   * are in the month, and once that day is chosen the selection is the
+   * stronger statement — there is nothing left for the tint to say.
+   */
+  const dayNumber = (date: Date): number => date.getFullYear() * 10000 + date.getMonth() * 100 + date.getDate();
+  const isSelectedDay = (date: Date): boolean => {
+    const n = dayNumber(date);
+    if (mode === "single") {
+      const picked = selected as Date | undefined;
+      return !!picked && dayNumber(picked) === n;
+    }
+    const range = rangeSelected;
+    if (!range?.from) return false;
+    if (!range.to) return dayNumber(range.from) === n;
+    return n >= dayNumber(range.from) && n <= dayNumber(range.to);
+  };
+  const isUnclaimedToday = (date: Date): boolean => dayNumber(date) === dayNumber(today) && !isSelectedDay(date);
+
+  const selectedClass = bare
+    ? "[&>button]:!bg-ods-accent [&>button]:!text-ods-card [&>button]:!font-bold [&>button]:hover:!bg-ods-accent"
+    : "!bg-ods-accent !text-ods-card !font-bold !rounded-[6px] hover:!bg-ods-accent";
+
+  // Surface + inset, per placement. Bare drops the card and the 16px inset
+  // (the host's panel provides both) and replaces the inset with the 8px the
+  // design puts between the header and the grid — the ONLY spacing it keeps.
+  const surfaceClass = bare
+    ? "flex w-full flex-col"
+    : cn("bg-ods-card border border-ods-border rounded-[6px] overflow-hidden", isFluid && "w-full");
+  // Bare: an unpadded header row over the grid, 8px apart — the calendar's
+  // whole height is the two of them added up, never the container's.
+  const captionRowClass = cn("flex items-center justify-between gap-1", bare ? "shrink-0" : "px-4 pt-4");
+  // The caption is the only elastic thing in the header: it takes the space
+  // the two fixed buttons leave and truncates rather than pushing into them.
+  // "September 2026" is ~131px at text-h4, and the two 48px buttons plus their
+  // gaps take 104 — so a `bare` host has to state a width of ~256 or more, or
+  // the label and the next-month button collide (worse in a locale with longer
+  // month names).
+  const captionClass = "min-w-0 flex-1 truncate text-center text-h4 text-ods-text-primary";
 
   const classNames: DayPickerProps["classNames"] = {
-    root: cn("p-4 date-picker-calendar", fluid && "w-full"),
-    months: "flex gap-8",
-    month: cn("flex flex-col gap-2", fluid && "w-full"),
+    root: cn(
+      "date-picker-calendar",
+      bare ? "flex w-full flex-col pt-[var(--spacing-system-xsf)]" : cn("p-4", isFluid && "w-full"),
+    ),
+    months: cn("flex gap-8", bare && "w-full"),
+    month: cn("flex flex-col", bare ? "w-full" : cn("gap-2", isFluid && "w-full")),
     month_caption: "hidden",
     nav: "hidden",
-    month_grid: cn("border-collapse", fluid && "w-full"),
+    month_grid: cn("border-collapse", bare ? "flex w-full flex-col" : isFluid && "w-full"),
     weekdays: "flex",
+    ...(bare ? { weeks: "flex flex-col" } : {}),
     weekday: cn(
-      cellOuter,
+      weekdayOuter,
       "flex items-center justify-center",
       "text-h6 text-ods-text-secondary"
     ),
@@ -222,7 +363,7 @@ function DatePickerCalendar({
       "text-h4 text-ods-text-primary",
       "cursor-pointer",
       "transition-colors duration-150",
-      "hover:bg-ods-bg-surface hover:rounded-[6px]"
+      hoverClass
     ),
     day_button: cn(
       cellInner,
@@ -230,9 +371,10 @@ function DatePickerCalendar({
       "cursor-pointer bg-transparent border-none outline-none",
       "text-inherit font-inherit"
     ),
-    today: "bg-ods-bg-surface rounded-[6px] hover:!bg-ods-bg-surface",
+    // Painted through the `todayTint` modifier instead — see `isUnclaimedToday`.
+    today: "",
     selected: cn(
-      "!bg-ods-accent !text-ods-card !font-bold !rounded-[6px] hover:!bg-ods-accent",
+      selectedClass,
       // In range mode, selected class should not override range_start/range_end/range_middle
       mode === "range" && "range-selected"
     ),
@@ -250,7 +392,19 @@ function DatePickerCalendar({
     // `disabled` <button> does not inherit the cell's cursor on its own.
     disabled: cn(
       "!text-ods-text-disabled !cursor-not-allowed hover:!bg-transparent",
-      "[&>button]:!cursor-not-allowed [&>button]:!text-ods-text-disabled"
+      "[&>button]:!cursor-not-allowed [&>button]:!text-ods-text-disabled",
+      // Also drop the `today` tint, or an unselectable today renders BLANK:
+      // `--color-text-disabled` and `--color-bg-surface` are the SAME token
+      // (`--ods-system-greys-soft-grey`), so the number disappears into the
+      // highlight — grey on identical grey. Reachable by any picker whose
+      // `fromDate` is in the future, and permanently by the meeting scheduler,
+      // where today usually has no bookable slots left.
+      //
+      // Dropping the tint rather than repainting the text: a disabled day is
+      // not actionable, so a highlight claiming otherwise is the wrong signal.
+      // The day still reads as today's position in the month by being the one
+      // dimmed cell between yesterday and tomorrow.
+      "!bg-transparent [&>button]:!bg-transparent"
     ),
     hidden: "invisible",
     // Range styles matching Figma design:
@@ -269,11 +423,19 @@ function DatePickerCalendar({
     range_middle: "range-middle !bg-ods-open-yellow-light !text-ods-card !font-medium !rounded-none hover:!bg-ods-open-yellow-light",
   };
 
-  const [month, setMonth] = React.useState<Date>(
+  // Controlled when the host passes `month`, self-owned otherwise. The
+  // internal state is kept either way so an uncontrolled calendar still works;
+  // controlled it is simply never read, which keeps `changeMonth` one path.
+  const [uncontrolledMonth, setUncontrolledMonth] = React.useState<Date>(
     mode === "single"
       ? (selected as Date) || today
       : (selected as DateRange)?.from || today
   );
+  const month = monthProp ?? uncontrolledMonth;
+  const changeMonth = (next: Date): void => {
+    setUncontrolledMonth(next);
+    onMonthChange?.(next);
+  };
 
   /**
    * `fromDate` / `toDate` → what react-day-picker **v9** actually understands.
@@ -294,8 +456,11 @@ function DatePickerCalendar({
     const matchers: Matcher[] = [];
     if (fromDate) matchers.push({ before: fromDate });
     if (toDate) matchers.push({ after: toDate });
+    if (extraDisabledDays) {
+      matchers.push(...(Array.isArray(extraDisabledDays) ? extraDisabledDays : [extraDisabledDays]));
+    }
     return matchers;
-  }, [fromDate, toDate]);
+  }, [fromDate, toDate, extraDisabledDays]);
 
   // Out-of-bounds days are disabled, not hidden — a month keeps its shape, and
   // the greyed-out day is what tells the user the bound exists. Navigation stops
@@ -311,21 +476,13 @@ function DatePickerCalendar({
   const canGoPrevious = !fromDate || monthIndex(month) > monthIndex(fromDate);
   const canGoNext = !toDate || lastVisibleMonth < monthIndex(toDate);
 
-  const handlePreviousMonth = () => {
-    setMonth((prev) => {
-      const newMonth = new Date(prev);
-      newMonth.setMonth(newMonth.getMonth() - 1);
-      return newMonth;
-    });
-  };
-
-  const handleNextMonth = () => {
-    setMonth((prev) => {
-      const newMonth = new Date(prev);
-      newMonth.setMonth(newMonth.getMonth() + 1);
-      return newMonth;
-    });
+  const shiftMonth = (by: number) => {
+    const next = new Date(month);
+    next.setMonth(next.getMonth() + by);
+    changeMonth(next);
   };
+  const handlePreviousMonth = () => shiftMonth(-1);
+  const handleNextMonth = () => shiftMonth(1);
 
   const formatMonthYear = (date: Date): string => {
     return date.toLocaleDateString("en-US", {
@@ -372,17 +529,15 @@ function DatePickerCalendar({
 
   if (mode === "single") {
     return (
-      <div className={cn("bg-ods-card border border-ods-border rounded-[6px] overflow-hidden", fluid && "w-full")}>
-        <div className="flex items-center justify-between px-4 pt-4">
+      <div className={surfaceClass}>
+        <div className={captionRowClass}>
           <CalendarNavButton
             direction="left"
             onClick={handlePreviousMonth}
             disabled={!canGoPrevious}
             aria-label="Previous month"
           />
-          <span className="text-h4 text-ods-text-primary">
-            {formatMonthYear(month)}
-          </span>
+          <span className={captionClass}>{formatMonthYear(month)}</span>
           <CalendarNavButton
             direction="right"
             onClick={handleNextMonth}
@@ -395,8 +550,10 @@ function DatePickerCalendar({
           selected={selected as Date | undefined}
           onSelect={(date) => onSelect(date)}
           month={month}
-          onMonthChange={setMonth}
+          onMonthChange={changeMonth}
           classNames={classNames}
+          modifiers={{ todayTint: isUnclaimedToday }}
+          modifiersClassNames={{ todayTint: todayClass }}
           showOutsideDays
           fixedWeeks
           disabled={disabledDays}
@@ -410,7 +567,7 @@ function DatePickerCalendar({
   // Range mode
   return (
     <div
-      className={cn("bg-ods-card border border-ods-border rounded-md overflow-hidden", fluid && "w-full")}
+      className={cn("bg-ods-card border border-ods-border rounded-md overflow-hidden", isFluid && "w-full")}
       onMouseLeave={() => setHoveredDate(undefined)}
     >
       <style>{rangeStyles}</style>
@@ -424,9 +581,7 @@ function DatePickerCalendar({
               disabled={!canGoPrevious}
               aria-label="Previous month"
             />
-            <span className="text-h4 text-ods-text-primary">
-              {formatMonthYear(month)}
-            </span>
+            <span className={captionClass}>{formatMonthYear(month)}</span>
             {monthsToShow === 1 && (
               <CalendarNavButton
                 direction="right"
@@ -442,10 +597,10 @@ function DatePickerCalendar({
             selected={draftRange}
             onSelect={(_range, triggerDate) => handleRangeSelect(triggerDate)}
             onDayMouseEnter={(day) => setHoveredDate(day)}
-            modifiers={{ preview: isPreviewDate }}
-            modifiersClassNames={{ preview: "bg-ods-bg-surface" }}
+            modifiers={{ preview: isPreviewDate, todayTint: isUnclaimedToday }}
+            modifiersClassNames={{ preview: "bg-ods-bg-surface", todayTint: todayClass }}
             month={month}
-            onMonthChange={setMonth}
+            onMonthChange={changeMonth}
             classNames={classNames}
             showOutsideDays
             fixedWeeks
@@ -460,9 +615,7 @@ function DatePickerCalendar({
           <div className="flex-1 border-l border-ods-border">
             <div className="flex items-center justify-between px-4 pt-4">
               <div className="size-10 md:size-12" />
-              <span className="text-h4 text-ods-text-primary">
-                {formatMonthYear(getSecondMonth(month))}
-              </span>
+              <span className={captionClass}>{formatMonthYear(getSecondMonth(month))}</span>
               <CalendarNavButton
                 direction="right"
                 onClick={handleNextMonth}
@@ -475,8 +628,8 @@ function DatePickerCalendar({
               selected={draftRange}
               onSelect={(_range, triggerDate) => handleRangeSelect(triggerDate)}
               onDayMouseEnter={(day) => setHoveredDate(day)}
-              modifiers={{ preview: isPreviewDate }}
-              modifiersClassNames={{ preview: "bg-ods-bg-surface" }}
+              modifiers={{ preview: isPreviewDate, todayTint: isUnclaimedToday }}
+              modifiersClassNames={{ preview: "bg-ods-bg-surface", todayTint: todayClass }}
               month={getSecondMonth(month)}
               classNames={classNames}
               showOutsideDays

package/src/components/ui/field-wrapper.tsx

@@ -7,6 +7,13 @@ import { cn } from "../../utils/cn"
 export interface FieldWrapperProps {
   /** Label text displayed above the field */
   label?: string
+  /**
+   * `id` of the control the label names. Without it the label is decoration:
+   * clicking it focuses nothing and assistive tech reads the field unnamed,
+   * which is why every caller that cared was rendering its own <Label> instead
+   * of using `label` here.
+   */
+  htmlFor?: string
   /**
    * Status message displayed below the field, on ONE line, ellipsized on
    * overflow (full text via the native `title`).
@@ -33,7 +40,7 @@ const errorVariantClasses = {
 } as const
 
 const FieldWrapper = React.forwardRef<HTMLDivElement, FieldWrapperProps>(
-  ({ label, error, errorVariant = "error", className, children }, ref) => {
+  ({ label, htmlFor, error, errorVariant = "error", className, children }, ref) => {
     const hasChrome = label != null || error != null
 
     return (
@@ -44,7 +51,7 @@ const FieldWrapper = React.forwardRef<HTMLDivElement, FieldWrapperProps>(
           // Field-wrapped controls with `label=`-prop controls showed two label
           // sizes side by side — the exact inconsistency the admin editors kept
           // reporting. One label scale, owned here and in Field together.
-          <Label className="mb-1">
+          <Label className="mb-1" htmlFor={htmlFor}>
             {label}
           </Label>
         )}

package/src/hooks/use-meeting-booking.ts

@@ -1,6 +1,7 @@
 'use client'
 
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { useCallback, useLayoutEffect, useRef, useState } from 'react'
 import { contentFetch } from '../utils/embed-content-fetch'
 import { MAX_MONTH_OFFSET } from '../utils/hubspot-meetings-convention'
 import type {
@@ -13,14 +14,31 @@ import type {
  * useMeetingBooking — data layer for `<HubSpotMeetingScheduler>` (the widget
  * files never inline fetch; same split as `useContactSubmission`/ContactForm).
  *
- * Availability: plain `useState` + `useEffect` + `AbortController` self-fetch
- * (NO client cache layer). An `initialAvailability` seed (SSR mode) renders
- * immediately, but the hook REFETCHES UNCONDITIONALLY after mount — the seed
- * is first-paint scaffolding for a 60-second-volatile resource, not truth.
+ * REQUIRES a `QueryClientProvider` in the host, like every other query-backed
+ * surface in this lib (tickets, chat, onboarding-guides). `@tanstack/react-query`
+ * is a declared peer dependency; the lib never mounts a provider of its own.
  *
- * Booking: single POST guarded by `isSubmitting` (the only double-booking
- * guard — the transport never retries POST). Errors surface as typed
- * `MeetingBookingErrorCode`s the widget keys its recovery UI off.
+ * Availability is a per-month GET, cached per (host, link, month). The cache is
+ * the point: paging back to a month already seen is INSTANT and silent, which
+ * is what a hand-rolled `useEffect` + `useState` could not do — it re-fetched
+ * and re-skeletoned the same month every time the visitor stepped back.
+ *
+ * Deliberately NOT `placeholderData: keepPreviousData`. The payload is
+ * month-scoped, so last month's slots under this month's caption describe days
+ * that aren't on screen — a grid that lights up the wrong dates is worse than
+ * one that is briefly inert. What kills the flicker instead is WHERE the
+ * loading state lands: the calendar is fully derivable from the date alone, so
+ * it keeps rendering (with nothing selectable yet) while only the times column
+ * — the part that genuinely has no answer — shows a placeholder.
+ *
+ * `staleTime` is deliberately short: HubSpot slots go stale in about a minute,
+ * and a slot that is gone by the time it is clicked costs a booking. Fresh
+ * enough to trust, cached enough not to blink.
+ *
+ * Booking: a mutation, guarded so a second submit can't start while one is in
+ * flight (the transport never retries POST — this is the only double-booking
+ * guard). Errors surface as typed `MeetingBookingErrorCode`s the widget keys
+ * its recovery UI off, never as thrown rejections.
  *
  * All requests go through the host proxy (`apiBaseUrl` prefix, FaqSection
  * precedent) via `contentFetch`, so embedded hosts with an embed-auth adapter
@@ -42,28 +60,33 @@ const KNOWN_CODES: MeetingBookingErrorCode[] = [
   'MEETING_UNAVAILABLE',
 ]
 
+/** ~half HubSpot's own slot volatility window — see the docblock. */
+const AVAILABILITY_STALE_MS = 30_000
+
+/** Query key for one month of one link. Exported so a host can prefetch or
+ *  invalidate a month it knows changed (e.g. after booking elsewhere). */
+export function meetingAvailabilityKey(apiBaseUrl: string, meetingId: string, monthOffset: number) {
+  return ['meeting-availability', apiBaseUrl, meetingId, monthOffset] as const
+}
+
 export function useMeetingBooking(options: {
   meetingId: string
   apiBaseUrl?: string
   initialAvailability?: MeetingAvailability
 }) {
   const { meetingId, apiBaseUrl = '', initialAvailability } = options
-  const seededFor = initialAvailability?.meetingId === meetingId ? initialAvailability : undefined
+  const queryClient = useQueryClient()
 
-  const [availability, setAvailability] = useState<MeetingAvailability | null>(seededFor ?? null)
-  const [monthOffset, setMonthOffsetState] = useState(seededFor?.monthOffset ?? 0)
-  const [isLoadingAvailability, setIsLoadingAvailability] = useState(!seededFor)
-  const [availabilityError, setAvailabilityError] = useState<string | null>(null)
-  const [isSubmitting, setIsSubmitting] = useState(false)
-  const submittingRef = useRef(false)
+  const seededOffset = initialAvailability?.meetingId === meetingId ? initialAvailability.monthOffset : undefined
+  const [monthOffset, setMonthOffsetState] = useState(seededOffset ?? 0)
 
   const setMonthOffset = useCallback((offset: number) => {
     setMonthOffsetState(Math.max(0, Math.min(MAX_MONTH_OFFSET, offset)))
   }, [])
 
-  // Link switch resets paging — without this, the new link is fetched at the
-  // PREVIOUS link's month. Layout effect so the fetch effect below sees the
-  // reset offset in the same commit.
+  // Link switch resets paging — without this, the new link is queried at the
+  // PREVIOUS link's month. Layout effect so the query below sees the reset
+  // offset in the same commit.
   const prevMeetingIdRef = useRef(meetingId)
   useLayoutEffect(() => {
     if (prevMeetingIdRef.current === meetingId) return
@@ -71,58 +94,40 @@ export function useMeetingBooking(options: {
     setMonthOffsetState(0)
   }, [meetingId])
 
-  // Unconditional (re)fetch on mount and on (meetingId, monthOffset) change —
-  // even when SSR-seeded (the seed may already be stale).
-  useEffect(() => {
-    const controller = new AbortController()
-    let active = true
-    const load = async () => {
-      // Same-month refresh (the unconditional post-mount refetch of an SSR
-      // seed) keeps the grid on screen; a DIFFERENT month or link has nothing
-      // truthful to show — loading turns on so the widget renders its
-      // per-region skeletons instead of a stale grid under a new caption.
-      setAvailabilityError(null)
-      if (!availability || availability.meetingId !== meetingId || availability.monthOffset !== monthOffset) {
-        setIsLoadingAvailability(true)
-      }
-      try {
-        const params = new URLSearchParams({ meeting: meetingId, monthOffset: String(monthOffset) })
-        const res = await contentFetch(`${apiBaseUrl}/api/meetings/availability?${params}`, {
-          signal: controller.signal,
-        })
-        if (!res.ok) throw new Error(`availability ${res.status}`)
-        const data = (await res.json()) as MeetingAvailability
-        if (active) setAvailability(data)
-      } catch (err) {
-        if (!active || (err instanceof DOMException && err.name === 'AbortError')) return
-        setAvailabilityError(err instanceof Error ? err.message : 'Failed to load availability')
-      } finally {
-        if (active) setIsLoadingAvailability(false)
-      }
-    }
-    void load()
-    return () => {
-      active = false
-      controller.abort()
-    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- refetch is keyed on (meetingId, monthOffset) only; `availability` is read for skeleton gating, not as a trigger
-  }, [meetingId, monthOffset, apiBaseUrl])
+  // The SSR seed covers exactly one (link, month) cell of the cache.
+  const seed =
+    initialAvailability?.meetingId === meetingId && initialAvailability.monthOffset === monthOffset
+      ? initialAvailability
+      : undefined
 
-  const refetchAvailability = useCallback(async () => {
-    try {
+  const availabilityQuery = useQuery({
+    queryKey: meetingAvailabilityKey(apiBaseUrl, meetingId, monthOffset),
+    queryFn: async ({ signal }) => {
       const params = new URLSearchParams({ meeting: meetingId, monthOffset: String(monthOffset) })
-      const res = await contentFetch(`${apiBaseUrl}/api/meetings/availability?${params}`)
-      if (res.ok) setAvailability((await res.json()) as MeetingAvailability)
-    } catch {
-      /* recovery refetch is best-effort — the stale grid stays visible */
-    }
-  }, [meetingId, monthOffset, apiBaseUrl])
+      const res = await contentFetch(`${apiBaseUrl}/api/meetings/availability?${params}`, { signal })
+      if (!res.ok) throw new Error(`availability ${res.status}`)
+      return (await res.json()) as MeetingAvailability
+    },
+    staleTime: AVAILABILITY_STALE_MS,
+    initialData: seed,
+    // Stamped as infinitely old on purpose: the seed is first-paint
+    // scaffolding for a 60-second-volatile resource, not truth, so it paints
+    // immediately AND is refetched immediately.
+    initialDataUpdatedAt: seed ? 0 : undefined,
+  })
 
-  const book = useCallback(
-    async (payload: Record<string, unknown>): Promise<BookingResult> => {
-      if (submittingRef.current) return { ok: false, code: 'VALIDATION', message: 'Already submitting' }
-      submittingRef.current = true
-      setIsSubmitting(true)
+  const refetchAvailability = useCallback(async () => {
+    // Recovery path (a slot taken from under the visitor): drop the cached
+    // month so the grid reloads from the network, not from the copy that
+    // still lists the taken slot. Best-effort — a failure leaves the stale
+    // grid up rather than blanking the card.
+    await queryClient
+      .invalidateQueries({ queryKey: meetingAvailabilityKey(apiBaseUrl, meetingId, monthOffset) })
+      .catch(() => undefined)
+  }, [queryClient, apiBaseUrl, meetingId, monthOffset])
+
+  const bookMutation = useMutation<BookingResult, never, Record<string, unknown>>({
+    mutationFn: async (payload) => {
       try {
         const res = await contentFetch(`${apiBaseUrl}/api/meetings/book`, {
           method: 'POST',
@@ -138,22 +143,41 @@ export function useMeetingBooking(options: {
         return { ok: false, code, message: typeof data.error === 'string' ? data.error : undefined }
       } catch {
         return { ok: false, code: 'TEMPORARILY_UNAVAILABLE' }
+      }
+    },
+    // A booking is not a read — never retried, at any layer.
+    retry: false,
+  })
+
+  // `isPending` alone would not stop a second submit dispatched in the same
+  // tick as the first; the ref closes that window the way the pre-query
+  // implementation did.
+  const submittingRef = useRef(false)
+  const { mutateAsync } = bookMutation
+  const book = useCallback(
+    async (payload: Record<string, unknown>): Promise<BookingResult> => {
+      if (submittingRef.current) return { ok: false, code: 'VALIDATION', message: 'Already submitting' }
+      submittingRef.current = true
+      try {
+        return await mutateAsync(payload)
       } finally {
         submittingRef.current = false
-        setIsSubmitting(false)
       }
     },
-    [apiBaseUrl],
+    [mutateAsync],
   )
 
   return {
-    availability,
-    isLoadingAvailability,
-    availabilityError,
+    availability: availabilityQuery.data ?? null,
+    /** No availability for this month yet — the times column has nothing to show. */
+    isLoadingAvailability: availabilityQuery.isPending,
+    /** ANY request in flight, including a silent revalidation of cached data. */
+    isFetchingAvailability: availabilityQuery.isFetching,
+    availabilityError: availabilityQuery.error ? availabilityQuery.error.message : null,
     monthOffset,
     setMonthOffset,
     refetchAvailability,
     book,
-    isSubmitting,
+    isSubmitting: bookMutation.isPending,
   } as const
 }