@v-office/website-headless 0.0.1

package/README.md

@@ -0,0 +1,86 @@
+# @v-office/website-headless
+
+The **behavior layer** for v-office websites. The invariant: **this package
+never contains UI.** It is `.ts` only. Imported UI lives one layer up in
+`@v-office/website-components` and renders over the hooks here; the
+structural requirements that UI must satisfy (`checkout/structure.ts`) live
+HERE, so a site's own UI is held to the same contract.
+
+```
+@v-office/sdk-core           domain contracts + PMS adapters
+@v-office/website-sdk        website facade (static + live namespaces)
+@v-office/website-headless   ←  THIS: orchestration hooks, validation, legal
+                             gates, derived manifest, enhancement engines
+@v-office/website-components imported UI over these hooks (a site may copy and own it)
+userland                     pages, brand components, tokens, copy
+```
+
+## Entry points
+
+| Import                       | Contents                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@v-office/website-headless` | Framework-free runtime: `createCheckoutFlow` — the whole checkout machine (stay → quote → selections → § 7 gate → book → pay) as a store with `getState` / `subscribe` / actions / `update` / `start` / `dispose`; `createStore`, the primitive every flow here builds on; `fetchQuote` + the quote view model, `book()`/`pay()` runners, the payment-return snapshot, validation rules, `CHECKOUT_PARTS` + `assertCheckoutStructure`, `logSdkFailure` |
+| `…/manifest`                 | `siteManifest()` Astro integration — writes `dist/site-manifest.json` with installed package versions and per-surface states derived from the site's imports (`imported` = imports the component from website-components, `custom` = imports the surface's hook without it; see `manifest/surfaces.ts`). Three signals cross-checked per build. Node-only; import it in `astro.config` and nowhere else                                                |
+| `…/enhance`                  | Progressive enhancement for server-rendered markup: card image strips, history-backed content overlays, the rental gallery's layered viewer. They bind site markup and own none of it                                                                                                                                                                                                                                                                  |
+
+The flows are stores: a UI calls `getState()`, `subscribe(listener)` and the
+actions, and feeds its inputs through `update()`. No framework code lives here.
+`@v-office/website-components` (React) ships `useCheckoutFlow` for React sites
+that render their own booking UI; a site that wants neither writes the binding
+itself — it is this small:
+
+```ts
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import {
+  createCheckoutFlow,
+  type CheckoutFlow,
+  type CheckoutFlowOptions,
+} from "@v-office/website-headless";
+
+export function useCheckoutFlow(options: CheckoutFlowOptions) {
+  const ref = useRef<CheckoutFlow | null>(null);
+  ref.current ??= createCheckoutFlow(options);
+  const flow = ref.current;
+  useEffect(() => flow.update(options));
+  useEffect(() => {
+    flow.start();
+    return () => flow.dispose();
+  }, [flow]);
+  const state = useSyncExternalStore(flow.subscribe, flow.getState, flow.getState);
+  return { ...state, ...flow };
+}
+```
+
+Vue: a `shallowRef` set in `subscribe`; Svelte: the store contract is the same
+two functions; a plain `<script>` island: call `getState()` in the listener.
+
+## The one hard rule
+
+**This package never constructs an SDK instance, never renders markup and never depends on a UI framework.**
+Construction needs site credentials (`src/lib/voffice.ts` in each site);
+rendering is the components' or the site's job. Every function takes the SDK
+instance (or a `getSdk` thunk) from the caller. Copy/messages are always
+parameters — the rules live here, the words live in the site.
+
+## Development
+
+```bash
+pnpm install
+pnpm build        # tsdown → dist/ (index, manifest, enhance; .mjs + .d.mts)
+pnpm check        # tsc · oxlint · oxfmt --check
+pnpm test         # vitest, jsdom environment
+```
+
+The tests cover the pure rules (validation, insurance gate, stay helpers,
+quote adapter, manifest derivation), the checkout flow driven as a store
+against a fake SDK, and the structural gate against rendered markup. Nothing
+books or pays for real. vitest is used because the structural gate needs a
+DOM (jsdom); the SDKs use `node --test` because they do not.
+
+## Publishing
+
+The **Publish** workflow (`.github/workflows/publishSDK.yml`, choice
+`website-headless`) publishes the exact version in `package.json` to npm after
+build, check and tests pass; it never bumps versions. Set the version by hand,
+merge, run the workflow. Consumers pin the exact version and receive updates
+through fleet rollouts (docs/website-platform/process/06-package-rollout.md).

package/dist/enhance/index.d.mts

@@ -0,0 +1,181 @@
+//#region src/enhance/carousel.d.ts
+/**
+ * Per-card image carousel: drives the prev/next chevrons by calling
+ * `scrollTo` on the natively-scrolling image track (overflow-x: auto
+ * with scroll-snap on the track on touch devices, or scroll-snap
+ * none + JS-driven scrollTo on hover-capable devices).
+ *
+ * Native scroll matters for two reasons:
+ *   1. Lazy-loaded `<img loading="lazy">` only triggers load when
+ *      the image enters the visible viewport via real scroll. With
+ *      transform-based shifting, the browser doesn't recognize the
+ *      image as "in view", so subsequent images stay un-loaded
+ *      (white squares) when the user clicks next.
+ *   2. The scroll-snap behavior native scroll provides on touch is
+ *      what the iOS swipe momentum/snap relies on; transform-based
+ *      shifting can't reproduce it.
+ *
+ * Dots are optional and only updated when present.
+ */
+declare function initImageCarousels(selector?: string): void;
+declare function initRentalCarousel(viewport: HTMLElement): void;
+//#endregion
+//#region src/enhance/overlay.d.ts
+/**
+ * The rental page's history-integrated overlay — one controller, two callers.
+ *
+ * WHY IT EXISTS. The amenities modal and the description modal each carried
+ * their own copy of this, and the two were identical: diffed after renaming the
+ * modal noun, they differed in line wrapping and nothing else. Roughly seventy
+ * lines of history handling, scroll locking, ESC and focus written twice, which
+ * is two places for the same behaviour to be corrected in and one of them to be
+ * forgotten.
+ *
+ * WHAT IT DOES NOT DECIDE. Nothing visual. The card, the backdrop, the header
+ * bar and the scroll region are the component's; this file opens and closes
+ * them. It also states no selectors of its own — every one is passed in, so the
+ * markup and the string that finds it stay in the same file and a grep for
+ * `data-amenities-overlay` still lands on the component that owns it.
+ *
+ * WHY `hidden` AND NOT `<dialog>`. This controller inherited the mechanism
+ * rather than choosing it: every overlay on the page — the gallery lightbox,
+ * the fullscreen viewer, the floor plan, the map — shows and hides by toggling
+ * the `hidden` attribute, — see the view-transition helper below for why that stayed when
+ * the fades went in. A second mechanism here would mean two ways to open a
+ * layer on one page and two ways for the crossfade to have to work. Moving all
+ * five onto `<dialog>` is a real question and a separate one; moving one is
+ * not an improvement.
+ *
+ * WHY THE HISTORY ENTRY. A modal that swallows the back button is the single
+ * worst thing a phone page can do: the gesture that means „go back" navigates
+ * away from the rental instead of closing what is over it. Opening pushes one
+ * state, and every close routes through `history.back()`, so the X, the ESC
+ * key, a click beside the card, the browser's own button and the trackpad
+ * swipe all take the same path and leave the history stack level.
+ *
+ * NOT ADOPTED BY THE OTHER TWO OVERLAYS on the rental page, and both for a stated
+ * reason.
+ * `RentalMap` is a fullscreen layer with no backdrop to click, no scroll region
+ * to reset and unconditional focus on open; taking it would mean three option
+ * flags to describe one caller, which is the API bending rather than the
+ * callers converging. `RentalGallery`'s controller is `is:inline` and cannot
+ * import anything at all — see the note in `gallery.ts`.
+ */
+/** Run `mutate` inside a view transition where the browser has one and the
+ *  visitor has not asked for less motion; run it directly otherwise. */
+declare function withViewTransition(mutate: () => void): void;
+/** Install the page's single pair of modality listeners. Safe to call often. */
+declare function trackInputModality(): void;
+/** Focus `el` only when the last real input was a keyboard one. */
+declare function focusForKeyboard(el: HTMLElement | null): void;
+/** Every selector the controller needs, stated by the caller. Each is scoped to
+ *  `root`, so two overlays on one page cannot reach into each other. */
+interface HistoryOverlayOptions {
+  /** The component's own root — the element that wraps BOTH the page-side
+   *  trigger and the overlay, so one lookup finds everything. */
+  root: string;
+  /** The dimmed backdrop. It carries the `hidden` toggle, and a click that
+   *  lands on it rather than on the card inside dismisses. */
+  overlay: string;
+  /** The inner scroll region, reset to the top on close. It is not the card:
+   *  the card is the clip and the header, the block inside it is the scroller. */
+  scroller: string;
+  /** The trigger on the page. */
+  open: string;
+  /** The X in the overlay's header. */
+  close: string;
+  /** Value stored on the pushed history entry, so a close can tell ITS OWN
+   *  state from someone else's before calling `back()`. Unique per overlay. */
+  historyKey: string;
+}
+/** Bind one overlay. Returns silently when the markup is not on this page, so
+ *  a component whose overlay self-hides costs nothing. */
+declare function initHistoryOverlay(options: HistoryOverlayOptions): void;
+//#endregion
+//#region src/enhance/gallery.d.ts
+/**
+ * The gallery's layered overlays, as an engine the component configures.
+ *
+ * WHAT IT OWNS: opening and closing a stack of layers, the browser-history
+ * entry each one pushes, the scroll lock, layered ESC, focus on open and
+ * restore on close, the lazily-loaded photo reveal, the scroll-snap viewer's
+ * index and its prev/next stepping, and keeping a page-level carousel on the
+ * photo the visitor was last looking at.
+ *
+ * WHAT IT DECIDES: nothing visual. It states **no selector of its own** — every
+ * one is passed in, the rule `overlay.ts` already set, so the markup and the
+ * string that finds it stay in the same file and a grep for
+ * `data-gallery-lightbox` still lands on the component that owns it. It sets no
+ * class, reads no colour and renders no markup.
+ *
+ * WHY THE LAYERS ARE A LIST. The controller this replaces hardcoded its three
+ * layers and their nesting order in three separate places — the `popstate`
+ * handler, the `keydown` handler and the body-scroll restore — and opened with
+ * `if (!lightbox || !lightboxClose || !fullscreen || !fsTrack) return`. A page
+ * that opens the viewer straight from the photos, with no intermediate grid,
+ * therefore got **no gallery at all** and no error saying so. That is not a
+ * hypothetical composition: it is the obvious one for a site whose photos are
+ * already a full-width strip. Layers are now whatever the caller lists,
+ * outermost first, and a layer whose markup is absent is simply not bound.
+ *
+ * WHY IT IS A MODULE AND NOT `is:inline`. It was inline from the gallery's first
+ * commit with no reason recorded, and the cost was stated in two places: the
+ * four-line copy of `withViewTransition` it had to carry, and the third copy of
+ * the input-modality listeners `overlay.ts` names in its own header. An
+ * `is:inline` script is processed by neither Vite nor Astro and can import
+ * nothing, so both copies were forced rather than chosen.
+ *
+ * The one thing that changes by importing: the emitted script crosses Vite's
+ * `assetsInlineLimit` (4096 bytes), so Astro links it as an external module
+ * instead of writing it into the page. Any gate that located MARKUP by
+ * searching the built HTML was, until it read markup only, able to match the
+ * selector literals in the inlined source — see the note in the blueprints'
+ * `fact-check.py`. That is fixed there rather than worked around here.
+ */
+/** One overlay the gallery can open. Absent markup → not bound, no error. */
+interface GalleryLayer {
+  /** Stable name, used for this layer's history entry. */
+  name: string;
+  /** The panel that carries the `hidden` toggle. */
+  panel: string;
+  /** Everything that opens it. */
+  open: string;
+  /** The X inside it. */
+  close?: string;
+  /** Backdrop: a click that lands on it and not on the card inside dismisses. */
+  backdrop?: string;
+  /** Inner scroll region, reset to the top on close. Not the card — the card is
+   *  the clip and the header, the block inside it is the scroller. */
+  scroller?: string;
+  /** This layer is the photo viewer: its openers carry an image index and it
+   *  drives `track`. */
+  opensAt?: "index";
+  /** Preload the panel's image on the first hover/focus of any opener, so the
+   *  panel does not open onto an empty surface while the bytes arrive. */
+  warmOnIntent?: boolean;
+  /** Publish the panel image's real aspect ratio as `--fp-ar` once known, so a
+   *  wrong width/height guess does not size the box. */
+  fitImage?: string;
+}
+interface GalleryOptions {
+  /** The element wrapping every trigger and every layer, so one lookup finds
+   *  them all and two galleries on a page cannot reach into each other. */
+  root: string;
+  /** Horizontal scroll-snap track inside the viewer layer. */
+  track?: string;
+  trackPrev?: string;
+  trackNext?: string;
+  /** Element whose text becomes `n / total`. */
+  counter?: string;
+  /** A page-level carousel kept in sync with the viewer on close. */
+  carousel?: string;
+  carouselCounter?: string;
+  /** Attribute on a viewer opener carrying its image index. */
+  indexAttr?: string;
+  /** Outermost first. */
+  layers: GalleryLayer[];
+}
+/** Bind one gallery. Returns silently when its root is not on this page. */
+declare function initGallery(options: GalleryOptions): void;
+//#endregion
+export { type GalleryLayer, type GalleryOptions, type HistoryOverlayOptions, focusForKeyboard, initGallery, initHistoryOverlay, initImageCarousels, initRentalCarousel, trackInputModality, withViewTransition };