@doany-ai/calendar 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
+# @doany-ai/calendar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Booking the business's services on a Doany site: the services a visitor can book, a date and time picker, the booking flow, class sessions with seats, and the page a booking's link opens. Hooks read and book through the SDK client the site gives `<DoanyProvider>`; the components are defaults the site restyles through the theme variables, adjusts through props (every word through `labels`), or replaces while keeping the hooks.
+
+The business sets its services up in its Catalog (type, options with duration and price, how clients book, cancellation rules, questions). The site only reads them and books. Nothing here creates services.
+
+```jsx
+import { ServiceList, BookingFlow, SessionList, BookingStatus } from "@doany-ai/calendar";
+import { Link, useParams } from "react-router-dom";
+
+// /book — what can be booked; each card leads to its booking page
+<ServiceList hrefFor={(s) => `/book/${s.id}`} renderLink={({ href, className, children }) => <Link to={href} className={className}>{children}</Link>} />
+
+// /book/:serviceSettingId — pick a time, say who, done
+const { serviceSettingId } = useParams();
+<BookingFlow serviceSettingId={serviceSettingId} />
+
+// /classes — upcoming sessions with seats; Register opens the form in a dialog
+<SessionList />
+
+// /bookings/:registrationId — the page a booking's link opens; cancel within the policy
+const { registrationId } = useParams();
+<BookingStatus registrationId={registrationId} />
+```
+
+Keep `AuthProvider` in `src/App.jsx`: `BookingFlow` and `SessionList` read the signed-in account to prefill the form. List the pages in `doany/features.jsonc` under `booking`.
+
+## Records
+
+What the hooks return, as the platform gives them (the fields this package reads; `src/types.ts` has them all).
+
+- **BookableService** (`services.list` / `useBookableServices`): `id` (what `slots` and `book` take), `item_name`, `booking_mode` (`appointment` | `class`), `is_listed` (false: the business quotes first — not in the list, readable by id), `variants[]` (`id`, `name`, `duration_minutes`, `price_amount`, `currency`, `is_default`), `payment_requirement` (`none` | `full_online`), `location_type` (`business_address` | `customer_address` | `online`) + `address`, `phone_required`, `booking_fields[]` (the questions: `key`, `type`, `label`, `required`, `options`), `allow_customer_cancel`, `cancellation_cutoff_minutes`, `cancellation_policy_text`, `booking_horizon_days`, `seat_capacity`.
+- **Slot** (`useSlots`): `start_at`, `end_at`, `slot_token` (good for five minutes; holds nothing), `token_expires_at`.
+- **Booking** (`useSessions`): an appointment or a class session: `id`, `version`, `kind`, `status`, `item_name`, `variant_name`, `start_at`, `end_at`, `timezone`, `price_amount`, `currency`, `payment_requirement`, `location_type`, `address`, `booking_fields_snapshot`, `allowed_actions` (`create_registration` while seats are open); a session adds `capacity`, `remaining_seats`, `allowed_variants[]` (the tickets).
+- **Registration** (`useRegistration`, in every booking result): one person's place: `id`, `booking_id`, `version`, `status` (`pending_payment` | `confirmed` | `canceled` | `expired`), `order_id` (when paid online), `hold_expires_at`, `allowed_actions` (`cancel` when the policy allows).
+- **BookingResult** (`useBook`, `useRegister`): `{ booking, registration, access_token, order_access_token }`. The SDK keeps the tokens for the browser session, so the calls that follow need none.
+
+Times are ISO instants; the components show them in the visitor's timezone (`timezone` prop, default the browser's). Prices are in the currency's smallest unit (`12000` = $120.00).
+
+## Components
+
+### `ServiceList`
+
+The bookable services as cards (name, price, length, a Book button), with "Load more" while there are more.
+
+| prop | |
+| --- | --- |
+| `params` | `{ booking_mode?: "appointment" \| "class", limit? }` |
+| `hrefFor` | `(service) => string`: each card's link |
+| `renderLink` | `({ href, className, children }) => node`: render links with the site's router |
+| `onSelect` | `(service) => void`: instead of a link |
+| `renderItem` | `(service) => node`: replaces the card |
+| `empty` | node shown when nothing can be booked |
+| `footer` | node inside each card, under its text |
+| `variant` | `"grid"` (default): tiles. `"menu"`: the services grouped by their catalog category, with a category bar and a search box, each a row — a service menu |
+| `showDetails` | read each service's description, category and image from the catalog (`doany.catalog.list({ type: "service" })`); default `true`. A catalog that cannot be read leaves the cards without them |
+| `locale`, `labels`, `className` | |
+
+### `ServiceCard`
+
+One service: `service`, `href` / `onSelect`, `renderLink`, `footer`, `locale`, `labels`, `className`.
+
+### `BookingFlow`
+
+Book an appointment: the variant (when the service has several), a day and a time, who it is for, then the confirmation.
+
+| prop | |
+| --- | --- |
+| `serviceSettingId` | required: the service (`BookableService.id`) |
+| `catalogItemVariantId` | skip the variant choice |
+| `timezone` | the timezone times are shown in; default the browser's |
+| `address` | for a service at the customer's address |
+| `layout` | `"split"` (default): the service's summary (image, description, length, price, place, chosen time, timezone) in a column beside the steps. `"stacked"`: one column, summary on top |
+| `order` | `"when-first"` (default): day and time, then the details. `"who-first"`: the details first, then the time; the chosen time books at once |
+| `image`, `showDetails` | the summary's image (the catalog item's by default) and whether to read the catalog's description and image at all (default `true`) |
+| `renderPayment` | `(result) => node`: for a service paid online, what to render while the payment is due — the site's checkout for `result.registration.order_id` (`@doany-ai/commerce`'s `OrderCheckout`) |
+| `onBooked` | `(result) => void` |
+| `children` | `(result) => node`: under the confirmation, links onward |
+| `locale`, `labels`, `className` | |
+
+A slot taken by someone else meanwhile (`SLOT_UNAVAILABLE`) sends the visitor back to pick another; the times are re-read.
+
+### `DateTimePicker`
+
+The calendar and the day's times, with the timezone under it. For a site that draws its own flow around it.
+
+| prop | |
+| --- | --- |
+| `service`, `variant` | required |
+| `timezone`, `onTimezoneChange` | |
+| `value`, `onChange` | the chosen `Slot` |
+| `onConfirm`, `confirmLabel` | the button that appears beside the chosen slot (`selectTime` label by default) |
+| `layout` | `"wide"` (default): the times beside the calendar. `"narrow"`: under it |
+| `locale`, `labels`, `className` | |
+
+### `AttendeeForm`
+
+Name, email, phone and the service's questions. `fields` (the service's `booking_fields`), `phoneRequired`, `defaultValues`, `onSubmit(attendee)`, `submitLabel`, `busy`, `error`, `secondaryAction`, `labels`, `className`. The flow adds the timezone before booking.
+
+### `SessionCalendar`
+
+A month of class sessions: the days with sessions are marked on the calendar; the chosen day's sessions, with their seats, are listed beside it, each with Register (the same dialog as `SessionList`).
+
+| prop | |
+| --- | --- |
+| `serviceSettingId` | only this class |
+| `timezone`, `renderPayment`, `onRegistered`, `locale`, `labels`, `className` | as in `SessionList` |
+
+### `PackageList`, `PackageCard`
+
+The packages of uses a visitor can buy (`doany.catalog.list({ type: "plan", purchasable: true })`), as pricing cards: name, price, description, and the way to buy — which the site provides, because buying is `@doany-ai/commerce`'s job:
+
+```jsx
+<PackageList
+  highlight={(item) => item.name === "10-Class Pack"}
+  renderBuy={(item, variant) => <BuyButton items={[{ catalog_item_variant_id: variant.id, quantity: 1 }]} successPath={(id) => `/orders/${id}`} />}
+/>
+```
+
+| prop | |
+| --- | --- |
+| `renderBuy` | `(item, variant) => node`: the buying control. Left out, a plain Buy button calls `onBuy` |
+| `onBuy` | `(item, variant) => void` |
+| `highlight` | `(item) => boolean`: the card to mark out |
+| `footerFor` | `(item) => node`: under each description |
+| `category`, `limit`, `renderItem`, `empty`, `locale`, `labels`, `className` | |
+
+### `SessionList`
+
+Upcoming class sessions grouped by day, each with its seats and a Register button that opens the form in a dialog.
+
+| prop | |
+| --- | --- |
+| `params` | `{ service_setting_id?, from?, to?, limit? }` |
+| `timezone` | default the browser's |
+| `renderPayment` | as in `BookingFlow` |
+| `onRegistered` | `(result) => void` |
+| `empty` | node when there are no sessions |
+| `locale`, `labels`, `className` | |
+
+### `BookingStatus`
+
+The page a booking's link opens (`/bookings/<registration id>#t=<token>`): status, what, when, where, and Cancel within the policy.
+
+| prop | |
+| --- | --- |
+| `registrationId` | required |
+| `accessToken` | default: the link's `#t=`, else this browser session's |
+| `timezone` | default the browser's |
+| `allowCancel` | default `true` |
+| `children` | `(status, detail) => node` |
+| `locale`, `labels`, `className` | |
+
+## Hooks
+
+| hook | returns |
+| `useServiceDetails()` | query of the catalog's service items, plus `byItem`: a `Map` from catalog item id to `{ description, category, image_url, … }` |
+| `usePackages({ limit?, category? })` | query of the packages on sale, plus `packages` |
+| --- | --- |
+| `useBookableServices({ booking_mode?, limit? })` | react-query infinite query + `services` (every page so far) + `timezone` (the business's) |
+| `useBookableService(id)` | query of one `BookableService` |
+| `useSlots(serviceSettingId, { catalogItemVariantId, date: "YYYY-MM-DD", timezone })` | infinite query + `slots` |
+| `useBook()` | mutation: `mutate({ service_setting_id, catalog_item_variant_id, start_at, slot_token, attendee: { name, timezone, email?, phone?, answers? }, address? })` → `BookingResult` |
+| `useSessions({ service_setting_id?, from?, to?, limit? })` | infinite query + `sessions` + `timezone` |
+| `useSession(bookingId)` | query of one `Booking` |
+| `useRegister()` | mutation: `mutate({ bookingId, attendee, catalog_item_variant_id?, expected: { booking_version, payment_requirement, item_version?, variant_version? } })` → `BookingResult` |
+| `useRegistration(registrationId, { accessToken? })` | query of `{ registration, booking }`; polls while `pending_payment` |
+| `useCancelRegistration()` | mutation: `mutate({ registrationId, registration_version, booking_version, reason?, accessToken? })` |
+| `readBookingLinkToken(registrationId)` | the token in the page's link, for a page that calls the SDK itself |
+
+Helpers: `formatDuration(minutes)`, `formatTime(iso, timezone, locale)`, `formatDay`, `formatDateTime`, `formatTimezone`, `localDate(date, timezone)`, `browserTimezone()`, `servicePriceLabel(service, locale)`, `variantPriceLabel(variant, locale)`, `defaultVariant(service)`.
+
+## Labels
+
+Every word the components show is in `labels` (`Partial<CalendarLabels>`; the rest keep their defaults). A site in another language passes its words once to the outer component; it passes them on.
+
+`free`, `fromPrice(price)`, `duration(minutes)`, `book`, `askForQuote`, `noServices`, `loadError`, `tryAgain`, `loadMore`, `loadingMore`, `notAvailable`, `selectDateTime`, `timezone`, `noSlots`, `previousMonth`, `nextMonth`, `options`, `yourDetails`, `name`, `email`, `phone`, `confirmBooking`, `booking`, `back`, `slotTaken`, `bookingFailed`, `rateLimited`, `bookedTitle`, `bookedBody(when)`, `payToConfirmTitle`, `payToConfirmBody(until)`, `payNow`, `seatsLeft(n)`, `full`, `register`, `registered`, `noSessions`, `statusConfirmed`, `statusPendingPayment`, `statusCanceled`, `statusExpired`, `cancelBooking`, `cancelConfirm`, `keepBooking`, `canceling`, `cancelFailed`, `cancelProcessing`, `bookingNotFound`, `bookingCheckFailed`, `cancellationPolicy`, `location`, `online`, `atYourAddress`.
+
+Failure wording: the site's label (`loadError`, `bookingFailed`, `cancelFailed`) when set, else the platform's own message, else the default.
+
+## Customizing
+
+Stop at the first level that does what was asked:
+
+1. **Theme**: the variables in the site's `src/index.css` (`--primary`, `--radius`, `--font-heading`, …) style every component here.
+2. **Props**: `className`, `labels`, `renderLink`, `renderItem`, `empty`, `renderPayment`, `children`.
+3. **Hooks**: build the part yourself on `useBookableServices`, `useSlots`, `useBook`, `useSessions`, `useRegister`, `useRegistration`, `useCancelRegistration`.
+
+The package ships no CSS: the site's Tailwind build scans `node_modules/@doany-ai/calendar/dist` (the general and service scaffolds do).
+
+## Develop
+
+```bash
+npm install
+npm run typecheck   # includes tests/sdk-contract.types.ts: the real SDK client satisfies CalendarClient
+npm test
+npm run build
+```

package/dist/booking-link.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The access token of the registration this page was opened for by a link,
+ * or the one this tab kept from such a link. Only taken for the registration
+ * whose id is a segment of the page's path.
+ */
+export declare function readBookingLinkToken(registrationId: string | null | undefined): string | undefined;
+/** The given token, else the booking link's. */
+export declare function useBookingAccessToken(registrationId: string | null | undefined, given?: string): string | undefined;

package/dist/booking-link.js

@@ -0,0 +1,60 @@
+import { useMemo } from "react";
+// A booking link carries the registration's access token after the `#`:
+// `/bookings/<registration id>#t=<token>`, the way an order link does
+// (docs/specs/basic-modules-redesign/api/conventions.md). The hash never
+// reaches a server. The token is kept for the tab, per registration, so a
+// payment that leaves the site and comes back (no hash) still finds it.
+const storageKey = (registrationId) => `doany_booking_link_token_${registrationId}`;
+function pathSegments(pathname) {
+    return pathname.split("/").map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            return segment;
+        }
+    });
+}
+function session() {
+    try {
+        return typeof window !== "undefined" ? window.sessionStorage : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The access token of the registration this page was opened for by a link,
+ * or the one this tab kept from such a link. Only taken for the registration
+ * whose id is a segment of the page's path.
+ */
+export function readBookingLinkToken(registrationId) {
+    if (!registrationId || typeof window === "undefined")
+        return undefined;
+    const { hash, pathname } = window.location;
+    let token;
+    if (hash && pathSegments(pathname).includes(registrationId)) {
+        token = new URLSearchParams(hash.slice(1)).get("t") || undefined;
+        if (token) {
+            try {
+                session()?.setItem(storageKey(registrationId), token);
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+    if (!token) {
+        try {
+            token = session()?.getItem(storageKey(registrationId)) || undefined;
+        }
+        catch {
+            token = undefined;
+        }
+    }
+    return token;
+}
+/** The given token, else the booking link's. */
+export function useBookingAccessToken(registrationId, given) {
+    return useMemo(() => given ?? readBookingLinkToken(registrationId), [registrationId, given]);
+}

package/dist/components/attendee-form.d.ts

@@ -0,0 +1,28 @@
+import { type CalendarLabels } from "../labels.js";
+import type { BookingField } from "../types.js";
+/** What the form collects; the flow adds the timezone. */
+export interface AttendeeInput {
+    name: string;
+    email?: string;
+    phone?: string;
+    answers: Record<string, unknown>;
+}
+export interface AttendeeFormProps {
+    /** The service's questions, asked after name and contact. */
+    fields?: BookingField[];
+    /** The service requires a phone; otherwise an email or a phone, one of them. */
+    phoneRequired?: boolean;
+    defaultValues?: Partial<AttendeeInput>;
+    onSubmit: (attendee: AttendeeInput) => void;
+    /** Wins over the `confirmBooking` label. */
+    submitLabel?: string;
+    busy?: boolean;
+    /** Shown above the button: why the booking could not be made. */
+    error?: string | null;
+    /** Rendered beside the submit button, e.g. a Back button. */
+    secondaryAction?: React.ReactNode;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+/** Who the booking is for: name, a way to reach them, and the service's questions. */
+export declare function AttendeeForm({ fields, phoneRequired, defaultValues, onSubmit, submitLabel, busy, error, secondaryAction, labels: given, className, }: AttendeeFormProps): import("react").JSX.Element;

package/dist/components/attendee-form.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@doany-ai/app-core";
+import { Button } from "@doany-ai/app-core/ui/button";
+import { Checkbox } from "@doany-ai/app-core/ui/checkbox";
+import { Input } from "@doany-ai/app-core/ui/input";
+import { Label } from "@doany-ai/app-core/ui/label";
+import { Textarea } from "@doany-ai/app-core/ui/textarea";
+import { Loader2 } from "lucide-react";
+import { useState } from "react";
+import { calendarLabels } from "../labels.js";
+import { isE164, normalizePhone } from "../phone.js";
+function Question({ field, value, onChange }) {
+    const id = `doany-booking-${field.key}`;
+    if (field.type === "checkbox") {
+        return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Checkbox, { id: id, checked: Boolean(value), onCheckedChange: (checked) => onChange(checked === true), required: field.required }), _jsx(Label, { htmlFor: id, children: field.label })] }));
+    }
+    if (field.type === "select") {
+        return (_jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: id, children: field.label }), _jsxs("select", { id: id, value: typeof value === "string" ? value : "", onChange: (e) => onChange(e.target.value), required: field.required, className: "h-10 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground focus:outline-none focus:ring-2 focus:ring-ring", children: [_jsx("option", { value: "", children: "\u2014" }), (field.options ?? []).map((option) => (_jsx("option", { value: option, children: option }, option)))] })] }));
+    }
+    if (field.type === "multiselect") {
+        const chosen = Array.isArray(value) ? value : [];
+        return (_jsxs("fieldset", { className: "space-y-2", children: [_jsx("legend", { className: "text-sm font-medium", children: field.label }), (field.options ?? []).map((option) => {
+                    const optionId = `${id}-${option}`;
+                    const on = chosen.includes(option);
+                    return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(Checkbox, { id: optionId, checked: on, onCheckedChange: (checked) => onChange(checked === true ? [...chosen, option] : chosen.filter((o) => o !== option)) }), _jsx(Label, { htmlFor: optionId, children: option })] }, option));
+                })] }));
+    }
+    if (field.type === "textarea") {
+        return (_jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: id, children: field.label }), _jsx(Textarea, { id: id, value: typeof value === "string" ? value : "", onChange: (e) => onChange(e.target.value), required: field.required })] }));
+    }
+    return (_jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: id, children: field.label }), _jsx(Input, { id: id, value: typeof value === "string" ? value : "", onChange: (e) => onChange(e.target.value), required: field.required })] }));
+}
+/** Who the booking is for: name, a way to reach them, and the service's questions. */
+export function AttendeeForm({ fields = [], phoneRequired = false, defaultValues, onSubmit, submitLabel, busy = false, error, secondaryAction, labels: given, className, }) {
+    const labels = calendarLabels(given);
+    const [name, setName] = useState(defaultValues?.name ?? "");
+    const [email, setEmail] = useState(defaultValues?.email ?? "");
+    const [phone, setPhone] = useState(defaultValues?.phone ?? "");
+    const [answers, setAnswers] = useState(defaultValues?.answers ?? {});
+    const submit = (event) => {
+        event.preventDefault();
+        onSubmit({
+            name: name.trim(),
+            ...(email.trim() ? { email: email.trim() } : {}),
+            ...(phone.trim() ? { phone: normalizePhone(phone) } : {}),
+            answers,
+        });
+    };
+    return (_jsxs("form", { onSubmit: submit, className: cn("space-y-4", className), children: [_jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: "doany-attendee-name", children: labels.name }), _jsx(Input, { id: "doany-attendee-name", autoComplete: "name", value: name, onChange: (e) => setName(e.target.value), required: true })] }), _jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: "doany-attendee-email", children: labels.email }), _jsx(Input, { id: "doany-attendee-email", type: "email", autoComplete: "email", value: email, onChange: (e) => setEmail(e.target.value), required: !phoneRequired && !phone.trim() })] }), _jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: "doany-attendee-phone", children: labels.phone }), _jsx(Input, { id: "doany-attendee-phone", type: "tel", autoComplete: "tel", value: phone, onChange: (e) => {
+                            // The platform takes E.164 only: say so before the submit does.
+                            const normalized = normalizePhone(e.target.value);
+                            e.target.setCustomValidity(!normalized || isE164(normalized) ? "" : labels.phoneFormat);
+                            setPhone(e.target.value);
+                        }, required: phoneRequired })] }), fields.map((field) => (_jsx(Question, { field: field, value: answers[field.key], onChange: (v) => setAnswers((a) => ({ ...a, [field.key]: v })) }, field.key))), error && (_jsx("p", { role: "alert", className: "text-sm text-destructive", children: error })), _jsxs("div", { className: "flex items-center gap-3 pt-1", children: [secondaryAction, _jsxs(Button, { type: "submit", className: "h-10 flex-1 rounded-full", disabled: busy, children: [busy && _jsx(Loader2, { className: "mr-2 h-4 w-4 animate-spin" }), busy ? labels.booking : (submitLabel ?? labels.confirmBooking)] })] })] }));
+}

package/dist/components/booking-flow.d.ts

@@ -0,0 +1,48 @@
+import { type ReactNode } from "react";
+import { type CalendarLabels } from "../labels.js";
+import type { BookingFunding, BookingResult } from "../types.js";
+export interface BookingFlowProps {
+    /** The service's booking settings id (`BookableService.id`). */
+    serviceSettingId: string;
+    /** Preselect a variant; the service's default otherwise. */
+    catalogItemVariantId?: string;
+    /** The timezone to start in; the visitor's own otherwise. They can change it. */
+    timezone?: string;
+    /** For a service at the customer's address: where. */
+    address?: string;
+    /** Pay with a package the customer holds (its entitlement) instead of the service's default. */
+    funding?: BookingFunding;
+    /**
+     * `split` (default): the service's summary in a column beside the steps
+     * when the flow is at least 48rem wide, on top of them otherwise (its own
+     * width, not the screen's). `stacked`: always on top, in one row.
+     */
+    layout?: "split" | "stacked";
+    /**
+     * `when-first` (default): day and time, then who it is for. `who-first`:
+     * the details first, then the time; the chosen time books at once.
+     */
+    order?: "when-first" | "who-first";
+    /** An image for the summary; the catalog item's own when left out. */
+    image?: string | null;
+    /** Show the catalog's description and image in the summary. Default `true`. */
+    showDetails?: boolean;
+    /**
+     * A service paid online: the payment, given the booking (its
+     * `registration.order_id`); e.g. `<OrderCheckout orderId=…/>` from
+     * `@doany-ai/commerce`. Left out, the flow shows that payment is due.
+     */
+    renderPayment?: (result: BookingResult) => ReactNode;
+    /** The booking was made (confirmed, or awaiting its payment). */
+    onBooked?: (result: BookingResult) => void;
+    /** Under the confirmation: links onward. */
+    children?: (result: BookingResult) => ReactNode;
+    locale?: string;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+/**
+ * Book an appointment in one place: the service's variant, a day and a time,
+ * who it is for, then the confirmation (or the payment that confirms it).
+ */
+export declare function BookingFlow({ serviceSettingId, catalogItemVariantId, timezone: given, address, funding, layout, order, image: givenImage, showDetails, renderPayment, onBooked, children, locale, labels: givenLabels, className, }: BookingFlowProps): import("react").JSX.Element;

package/dist/components/booking-flow.js

@@ -0,0 +1,138 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Image } from "@doany-ai/app-core/media";
+import { cn } from "@doany-ai/app-core";
+import { useAuth } from "@doany-ai/app-core/auth";
+import { Button } from "@doany-ai/app-core/ui/button";
+import { Input } from "@doany-ai/app-core/ui/input";
+import { Label } from "@doany-ai/app-core/ui/label";
+import { Skeleton } from "@doany-ai/app-core/ui/skeleton";
+import { CalendarCheck, CheckCircle2, Clock, Globe, MapPin, Tag, Users } from "lucide-react";
+import { useState } from "react";
+import { browserTimezone, defaultVariant, formatDateTime, formatTimezone, variantPriceLabel } from "../format.js";
+import { useBook, useBookableService, useServiceDetails } from "../hooks.js";
+import { calendarLabels } from "../labels.js";
+import { AttendeeForm } from "./attendee-form.js";
+import { DateTimePicker } from "./date-time-picker.js";
+function messageOf(cause, labels, given) {
+    const { code, message } = (cause ?? {});
+    if (code === "SLOT_UNAVAILABLE")
+        return { text: labels.slotTaken, slotTaken: true };
+    if (code === "RATE_LIMITED")
+        return { text: labels.rateLimited, slotTaken: false };
+    return { text: given?.bookingFailed ?? (message || labels.bookingFailed), slotTaken: false };
+}
+function VariantChoice({ service, value, onChange, locale, labels }) {
+    if (service.variants.length < 2)
+        return null;
+    return (_jsx("div", { role: "radiogroup", "aria-label": labels.options, className: "flex flex-wrap gap-2", children: service.variants.map((variant) => {
+            const on = variant.id === value.id;
+            const price = variantPriceLabel(variant, locale, { free: labels.free });
+            return (_jsxs("button", { type: "button", role: "radio", "aria-checked": on, onClick: () => onChange(variant), className: cn("rounded-lg border px-4 py-2 text-sm font-medium transition-colors", on ? "border-primary bg-primary text-primary-foreground" : "border-border bg-background text-foreground hover:border-primary/60"), children: [variant.name, variant.duration_minutes ? ` · ${labels.duration(variant.duration_minutes)}` : "", price ? ` · ${price}` : ""] }, variant.id));
+        }) }));
+}
+function Summary({ service, variant, slot, timezone, image, description, locale, labels, stacked, }) {
+    const price = variantPriceLabel(variant, locale, { free: labels.free });
+    const place = service.location_type === "online" ? labels.online : service.location_type === "customer_address" ? labels.atYourAddress : service.address;
+    const rows = [
+        [Clock, variant.duration_minutes ? labels.duration(variant.duration_minutes) : null],
+        [Tag, price],
+        [service.booking_mode === "class" ? Users : MapPin, service.booking_mode === "class" && service.seat_capacity ? labels.classSeats(service.seat_capacity) : place],
+        [CalendarCheck, slot ? formatDateTime(slot.start_at, timezone, locale) : null],
+        [Globe, formatTimezone(timezone, locale)],
+    ];
+    // On top of the steps the summary is one row that wraps; beside them, a
+    // column. `stacked` is always the row; `split` is the row until the flow
+    // is 48rem wide. (The classes are spelled out: Tailwind finds them by
+    // scanning the built file for literal tokens.)
+    return (_jsxs("aside", { className: cn("flex flex-wrap items-start gap-x-8 gap-y-3", !stacked && "[@container(min-width:48rem)]:block [@container(min-width:48rem)]:space-y-4"), children: [_jsxs("div", { className: "flex items-start gap-4", children: [image ? _jsx(Image, { src: image, alt: "", className: "h-16 w-16 shrink-0 rounded-xl object-cover" }) : null, _jsxs("div", { className: "space-y-1", children: [_jsx("h2", { className: "font-heading text-xl font-semibold leading-tight tracking-tight", children: service.item_name }), description ? _jsx("p", { className: cn("line-clamp-2 text-sm text-muted-foreground", !stacked && "[@container(min-width:48rem)]:line-clamp-4"), children: description }) : null] })] }), _jsx("ul", { className: cn("flex flex-wrap gap-x-5 gap-y-1.5 text-sm text-muted-foreground", !stacked && "[@container(min-width:48rem)]:block [@container(min-width:48rem)]:space-y-2.5"), children: rows.map(([Icon, text], i) => text ? (_jsxs("li", { className: cn("flex items-center gap-2", i === 3 && "font-medium text-foreground"), children: [_jsx(Icon, { className: "h-4 w-4 shrink-0", "aria-hidden": "true" }), _jsx("span", { children: text })] }, i)) : null) })] }));
+}
+/**
+ * Book an appointment in one place: the service's variant, a day and a time,
+ * who it is for, then the confirmation (or the payment that confirms it).
+ */
+export function BookingFlow({ serviceSettingId, catalogItemVariantId, timezone: given, address, funding, layout = "split", order = "when-first", image: givenImage, showDetails = true, renderPayment, onBooked, children, locale, labels: givenLabels, className, }) {
+    const labels = calendarLabels(givenLabels);
+    const { data: service, isLoading, isError } = useBookableService(serviceSettingId);
+    const details = useServiceDetails(showDetails);
+    const { user } = useAuth();
+    const [timezone, setTimezone] = useState(given ?? browserTimezone());
+    const [variantId, setVariantId] = useState(catalogItemVariantId ?? null);
+    const [slot, setSlot] = useState(null);
+    const [attendee, setAttendee] = useState(null);
+    // A service at the customer's address needs one: the site's `address` prop,
+    // else the one the visitor types with their details.
+    const [customerAddress, setCustomerAddress] = useState("");
+    const [addressMissing, setAddressMissing] = useState(false);
+    const [step, setStep] = useState(order === "who-first" ? "who" : "when");
+    const [result, setResult] = useState(null);
+    const book = useBook();
+    const stacked = layout === "stacked";
+    if (isLoading) {
+        return (_jsxs("div", { className: cn("space-y-4", className), "aria-busy": "true", children: [_jsx(Skeleton, { className: "h-6 w-1/3" }), _jsx(Skeleton, { className: "h-72 w-full rounded-2xl" })] }));
+    }
+    if (isError || !service) {
+        return (_jsx("p", { role: "alert", className: cn("py-10 text-center text-sm text-destructive", className), children: labels.notAvailable }));
+    }
+    const variant = service.variants.find((v) => v.id === variantId) ?? defaultVariant(service);
+    if (!variant) {
+        return (_jsx("p", { role: "alert", className: cn("py-10 text-center text-sm text-destructive", className), children: labels.notAvailable }));
+    }
+    const item = details.byItem.get(service.catalog_item_id);
+    const image = givenImage === undefined ? item?.image_url : givenImage;
+    const description = showDetails ? item?.description : null;
+    const asksAddress = service.location_type === "customer_address" && !address;
+    const bookingAddress = address || (asksAddress ? customerAddress.trim() : "");
+    const place = (who, at) => book.mutate({
+        service_setting_id: service.id,
+        catalog_item_variant_id: variant.id,
+        start_at: at.start_at,
+        slot_token: at.slot_token,
+        attendee: { ...who, timezone },
+        ...(bookingAddress ? { address: bookingAddress } : {}),
+        ...(funding ? { funding } : {}),
+    }, {
+        onSuccess: (booked) => {
+            setResult(booked);
+            setStep("done");
+            onBooked?.(booked);
+        },
+        onError: (cause) => {
+            if (messageOf(cause, labels, givenLabels).slotTaken) {
+                setSlot(null);
+                setStep("when");
+            }
+        },
+    });
+    const error = book.isError ? messageOf(book.error, labels, givenLabels).text : null;
+    let body;
+    if (step === "done" && result) {
+        const pending = result.registration?.status === "pending_payment";
+        body = (_jsxs("div", { className: "space-y-6", children: [pending ? (_jsxs("div", { className: "space-y-4", children: [_jsxs("div", { className: "rounded-xl border border-border bg-muted/40 p-5", children: [_jsx("h3", { className: "font-heading text-lg font-semibold", children: labels.payToConfirmTitle }), _jsx("p", { className: "mt-1 text-sm text-muted-foreground", children: labels.payToConfirmBody(result.registration?.hold_expires_at ? formatDateTime(result.registration.hold_expires_at, timezone, locale) : "") })] }), renderPayment?.(result)] })) : (_jsxs("div", { className: "flex items-start gap-3 rounded-xl bg-success/10 p-5 text-success", children: [_jsx(CheckCircle2, { className: "mt-0.5 h-5 w-5 shrink-0", "aria-hidden": "true" }), _jsxs("div", { children: [_jsx("h3", { className: "font-heading text-lg font-semibold", children: labels.bookedTitle }), _jsx("p", { className: "mt-1 text-sm", children: labels.bookedBody(slot ? formatDateTime(slot.start_at, timezone, locale) : "") })] })] })), children?.(result)] }));
+    }
+    else if (step === "who") {
+        body = (_jsxs("div", { className: "space-y-5", children: [_jsx("h3", { className: "font-heading text-base font-semibold", children: labels.yourDetails }), asksAddress ? (_jsxs("div", { className: "space-y-2", children: [_jsx(Label, { htmlFor: "doany-booking-address", children: labels.yourAddress }), _jsx(Input, { id: "doany-booking-address", autoComplete: "street-address", value: customerAddress, onChange: (e) => {
+                                setCustomerAddress(e.target.value);
+                                setAddressMissing(false);
+                            }, "aria-invalid": addressMissing || undefined, required: true }), addressMissing ? (_jsx("p", { role: "alert", className: "text-sm text-destructive", children: labels.addressRequired })) : null] })) : null, _jsx(AttendeeForm, { fields: service.booking_fields, phoneRequired: service.phone_required, defaultValues: { name: user?.full_name ?? "", email: user?.email ?? "", ...(attendee ?? {}) }, onSubmit: (who) => {
+                        if (asksAddress && !customerAddress.trim()) {
+                            setAddressMissing(true);
+                            return;
+                        }
+                        setAttendee(who);
+                        if (order === "who-first")
+                            setStep("when");
+                        else if (slot)
+                            place(who, slot);
+                    }, busy: book.isPending, error: error, submitLabel: order === "who-first" ? labels.selectTime : undefined, labels: givenLabels, secondaryAction: order === "when-first" ? (_jsx(Button, { type: "button", variant: "outline", className: "h-10 rounded-lg px-5", onClick: () => setStep("when"), disabled: book.isPending, children: labels.back })) : null })] }));
+    }
+    else {
+        body = (_jsxs("div", { className: "space-y-5", children: [_jsx(VariantChoice, { service: service, value: variant, onChange: (v) => { setVariantId(v.id); setSlot(null); }, locale: locale, labels: labels }), error && (_jsx("p", { role: "alert", className: "text-sm text-destructive", children: error })), _jsx(DateTimePicker, { service: service, variant: variant, timezone: timezone, onTimezoneChange: setTimezone, value: slot, onChange: setSlot, onConfirm: (at) => {
+                        setSlot(at);
+                        if (order === "who-first" && attendee)
+                            place(attendee, at);
+                        else
+                            setStep("who");
+                    }, confirmLabel: order === "who-first" ? labels.confirmBooking : undefined, layout: stacked ? "narrow" : "wide", locale: locale, labels: givenLabels }), order === "who-first" && book.isPending ? _jsx("p", { className: "text-sm text-muted-foreground", children: labels.booking }) : null] }));
+    }
+    return (_jsx("section", { className: cn("overflow-hidden rounded-2xl border border-border bg-card text-card-foreground shadow-card [container-type:inline-size]", className), children: _jsxs("div", { className: cn(!stacked && "grid [@container(min-width:48rem)]:grid-cols-[minmax(200px,250px)_minmax(0,1fr)]"), children: [_jsx("div", { className: cn("border-b border-border p-6", !stacked && "[@container(min-width:48rem)]:border-b-0 [@container(min-width:48rem)]:border-r"), children: _jsx(Summary, { service: service, variant: variant, slot: slot, timezone: timezone, image: image, description: description, locale: locale, labels: labels, stacked: stacked }) }), _jsx("div", { className: "p-6", children: body })] }) }));
+}

package/dist/components/booking-status.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+import { type CalendarLabels } from "../labels.js";
+import type { Booking, Registration, RegistrationStatus } from "../types.js";
+export interface BookingStatusProps {
+    /** The registration, from the booking link `/bookings/<id>` or a `BookingFlow` result. */
+    registrationId: string;
+    /** Its access token. Default: the one in the link's `#t=`, else this browser session's. */
+    accessToken?: string;
+    /** The timezone to show times in. Default: the visitor's. */
+    timezone?: string;
+    /** Let the visitor cancel, within the service's policy. Default `true`. */
+    allowCancel?: boolean;
+    /** Under everything: links onward. Receives the status. */
+    children?: (status: RegistrationStatus | undefined, detail: {
+        registration: Registration;
+        booking: Booking;
+    } | undefined) => ReactNode;
+    locale?: string;
+    labels?: Partial<CalendarLabels>;
+    className?: string;
+}
+/** The page a booking's link opens: what was booked, when, where, and the way to cancel it. */
+export declare function BookingStatus({ registrationId, accessToken, timezone: given, allowCancel, children, locale, labels: givenLabels, className }: BookingStatusProps): import("react").JSX.Element;

package/dist/components/booking-status.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@doany-ai/app-core";
+import { Button } from "@doany-ai/app-core/ui/button";
+import { Skeleton } from "@doany-ai/app-core/ui/skeleton";
+import { CalendarCheck, Clock, Loader2, MapPin, XCircle } from "lucide-react";
+import { useState } from "react";
+import { useBookingAccessToken } from "../booking-link.js";
+import { browserTimezone, formatDateTime } from "../format.js";
+import { operationSettled, useCalendarOperation, useCancelRegistration, useRegistration } from "../hooks.js";
+import { calendarLabels } from "../labels.js";
+const statusLabel = (status, labels) => status === "confirmed" ? labels.statusConfirmed : status === "pending_payment" ? labels.statusPendingPayment : status === "canceled" ? labels.statusCanceled : labels.statusExpired;
+function where(booking, labels) {
+    if (booking.location_type === "online")
+        return labels.online;
+    if (booking.location_type === "customer_address")
+        return labels.atYourAddress;
+    if (booking.location_type === "business_address")
+        return booking.address ?? null;
+    return null;
+}
+/** The page a booking's link opens: what was booked, when, where, and the way to cancel it. */
+export function BookingStatus({ registrationId, accessToken, timezone: given, allowCancel = true, children, locale, labels: givenLabels, className }) {
+    const labels = calendarLabels(givenLabels);
+    const timezone = given ?? browserTimezone();
+    // The token the page opened with: the given one, the link's `#t=`, or this
+    // browser session's. The detail, the cancel and its operation all use it.
+    const token = useBookingAccessToken(registrationId, accessToken);
+    const { data, isLoading, isError, error, refetch } = useRegistration(registrationId, { accessToken: token });
+    const cancel = useCancelRegistration();
+    const operationId = cancel.data && "operation_id" in cancel.data ? cancel.data.operation_id : null;
+    const operation = useCalendarOperation(operationId, { registrationId, accessToken: token });
+    const [confirming, setConfirming] = useState(false);
+    if (isLoading) {
+        return (_jsxs("div", { className: cn("space-y-3", className), "aria-busy": "true", children: [_jsx(Skeleton, { className: "h-6 w-1/3" }), _jsx(Skeleton, { className: "h-24 w-full rounded-2xl" })] }));
+    }
+    if (isError || !data) {
+        const missing = error?.status === 404;
+        return (_jsxs("div", { role: "alert", className: cn("space-y-3 py-10 text-center text-sm", className), children: [_jsx("p", { className: "text-destructive", children: missing ? labels.bookingNotFound : labels.bookingCheckFailed }), !missing && (_jsx(Button, { variant: "outline", size: "sm", onClick: () => void refetch(), children: labels.tryAgain }))] }));
+    }
+    const { registration, booking } = data;
+    const status = registration.status;
+    const live = status === "confirmed" || status === "pending_payment";
+    const canCancel = allowCancel && live && registration.allowed_actions.includes("cancel");
+    const Icon = status === "confirmed" ? CalendarCheck : status === "pending_payment" ? Clock : XCircle;
+    const tone = status === "confirmed" ? "bg-success/10 text-success" : status === "pending_payment" ? "bg-muted text-muted-foreground" : "bg-destructive/10 text-destructive";
+    const place = where(booking, labels);
+    const meetingUrl = booking.location_type === "online" ? (booking.meeting?.meeting_url ?? null) : null;
+    // A cancel that waits on a payment: processing until its operation settles.
+    const settled = operationSettled(operation.data);
+    const processing = Boolean(operationId) && !settled;
+    const operationFailed = settled && operation.data?.status !== "succeeded";
+    return (_jsxs("section", { className: cn("space-y-5", className), children: [_jsxs("div", { className: cn("flex items-center gap-3 rounded-2xl p-4", tone), children: [_jsx(Icon, { className: "h-5 w-5 shrink-0", "aria-hidden": "true" }), _jsx("p", { className: "font-semibold", children: statusLabel(status, labels) })] }), _jsxs("dl", { className: "space-y-3 rounded-2xl border border-border bg-card p-5 text-sm", children: [_jsxs("div", { children: [_jsx("dt", { className: "text-muted-foreground", children: booking.item_name }), _jsx("dd", { className: "font-heading text-lg font-semibold", children: formatDateTime(booking.start_at, timezone, locale) })] }), _jsx("div", { className: "text-muted-foreground", children: booking.variant_name }), place && (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(MapPin, { className: "h-4 w-4 shrink-0 text-muted-foreground", "aria-hidden": "true" }), _jsx("span", { children: place })] })), meetingUrl && live && (_jsx("div", { children: _jsx("a", { href: meetingUrl, target: "_blank", rel: "noreferrer", className: "font-medium underline underline-offset-4", children: labels.joinMeeting }) }))] }), canCancel && (_jsxs("div", { className: "space-y-3", children: [processing ? (_jsxs("p", { className: "flex items-center gap-2 text-sm text-muted-foreground", children: [_jsx(Loader2, { className: "h-4 w-4 animate-spin", "aria-hidden": "true" }), labels.cancelProcessing] })) : confirming ? (_jsxs("div", { className: "flex flex-wrap items-center gap-3", children: [_jsx("span", { className: "text-sm", children: labels.cancelConfirm }), _jsx(Button, { variant: "destructive", size: "sm", className: "rounded-full", disabled: cancel.isPending, onClick: () => cancel.mutate({ registrationId, accessToken: token, registration_version: registration.version, booking_version: booking.version }, { onSettled: () => setConfirming(false) }), children: cancel.isPending ? labels.canceling : labels.cancelBooking }), _jsx(Button, { variant: "outline", size: "sm", className: "rounded-full", onClick: () => setConfirming(false), disabled: cancel.isPending, children: labels.keepBooking })] })) : (_jsx(Button, { variant: "outline", size: "sm", className: "rounded-full", onClick: () => setConfirming(true), children: labels.cancelBooking })), (cancel.isError || operationFailed || operation.isError) && (_jsx("p", { role: "alert", className: "text-sm text-destructive", children: givenLabels?.cancelFailed ?? (cancel.error?.message || labels.cancelFailed) }))] })), children?.(status, data)] }));
+}