@bookslot/react 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taulant Sela
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# @bookslot/react
 
-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.
+The [BookSlot](https://bookslot.taulantsela.com) booking widget as a React component. Works in Next.js (App Router and Pages Router), Vite, Remix and any other React app.
+
+```bash
+npm install @bookslot/react
+```
+
+```tsx
+import { BookSlotWidget } from "@bookslot/react";
+
+export function Booking() {
+  return <BookSlotWidget shop="your-shop-slug" />;
+}
+```
+
+That's a working booking form. It loads the widget from BookSlot, resizes itself to fit, and shows the shop's services and free times. Find your shop slug in the BookSlot dashboard.
+
+The package is already marked `"use client"`, so in the Next.js App Router a server component can render it with `shop`, `theme`, `service`, `staff` and `customer`. Callbacks such as `onBooked` are functions, which React can't send from the server, so pass those from a client component.
+
+## Match your site, prefill, react to bookings (Pro)
+
+```tsx
+<BookSlotWidget
+  shop="your-shop-slug"
+  theme={{ primary: "#2dd4bf", scheme: "dark", radius: 6, font: "system" }}
+  service="svc_…"                                   // preselect; can change any time
+  staff="stf_…"                                     // preselect a staff member
+  customer={{ name: user.name, email: user.email, fields: { any_allergies: "None" } }}
+  onBooked={(booking) => router.push(`/thanks?id=${booking.appointmentId}`)}
+/>
+```
+
+On the Free plan the widget still works, but it ignores these options and shows a "Powered by BookSlot" badge. BookSlot enforces this on its server, so editing the props can't unlock them.
+
+## Props
+
+| Prop | Type | |
+|---|---|---|
+| `shop` | `string` | Required. The shop's slug. |
+| `bookslotUrl` | `string` | Where BookSlot runs. Defaults to the hosted service. |
+| `theme` | `{ primary?, background?, text?, radius?, font?, scheme? }` | Pro. Hex colours, radius 0–32, font `sans` / `system` / `serif` / `mono`, scheme `light` / `dark` / `auto`. Changing it reloads the widget. |
+| `service` | `string` | Pro. Service id to preselect, listed in **Dashboard → Widget**. |
+| `staff` | `string` | Pro. Staff member id to preselect, listed in **Dashboard → Widget**; `""` switches back to anyone. |
+| `customer` | `{ name?, email?, phone?, notes?, fields? }` | Pro. Fills in the form; `fields` answers custom questions by key. Sent with `postMessage`, never in the URL. |
+| `initialHeight` | `number` | Height before the widget reports its size. Default 720. |
+| `maxWidth` | `number \| string` | Default 480px. |
+| `title` | `string` | Accessible title of the iframe. |
+| `className`, `style` | | Applied to the wrapper `div`. |
+| `onReady` | `({ shop }) => void` | The widget loaded. |
+| `onResize` | `({ height }) => void` | The widget changed height. |
+| `onBooked` | `(booking) => void` | Pro. `{ appointmentId, serviceId, serviceName, staffId, staffName, startsAt, endsAt, when }`. |
+| `onError` | `({ message }) => void` | Pro for booking errors; also called if the widget script can't load. |
+
+## Without React
+
+Load the script and call it directly:
+
+```html
+<script src="https://bookslot.taulantsela.com/widget.js" data-shop="your-shop-slug" async></script>
+```
+
+`loadBookSlot(url?)` is exported too, if you want the underlying `BookSlot.mount` API in React.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,155 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  BookSlotWidget: () => BookSlotWidget,
+  DEFAULT_BOOKSLOT_URL: () => DEFAULT_BOOKSLOT_URL,
+  loadBookSlot: () => loadBookSlot
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var DEFAULT_BOOKSLOT_URL = "https://bookslot.taulantsela.com";
+function apiFor(origin, { justLoaded = false } = {}) {
+  var _a;
+  const globals = window;
+  const registered = (_a = globals.__bookslot) == null ? void 0 : _a[origin];
+  if (registered) return registered;
+  const legacy = globals.BookSlot;
+  return justLoaded && legacy && !legacy.origin ? legacy : void 0;
+}
+var loading = /* @__PURE__ */ new Map();
+function loadBookSlot(bookslotUrl = DEFAULT_BOOKSLOT_URL) {
+  if (typeof window === "undefined") {
+    return Promise.reject(new Error("BookSlot can only load in the browser"));
+  }
+  const base = bookslotUrl.replace(/\/+$/, "");
+  const origin = new URL(base || "/", window.location.href).origin;
+  const src = `${base}/widget.js`;
+  const loaded = loading.has(src) ? void 0 : apiFor(origin);
+  if (loaded) return Promise.resolve(loaded);
+  let promise = loading.get(src);
+  if (!promise) {
+    promise = new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.src = src;
+      script.async = true;
+      script.onload = () => {
+        const api = apiFor(origin, { justLoaded: true });
+        if (api) resolve(api);
+        else reject(new Error(`BookSlot: ${src} loaded but did not define BookSlot`));
+      };
+      script.onerror = () => {
+        loading.delete(src);
+        script.remove();
+        reject(new Error(`BookSlot: could not load ${src}`));
+      };
+      document.head.appendChild(script);
+    });
+    loading.set(src, promise);
+  }
+  return promise;
+}
+function BookSlotWidget({
+  shop,
+  bookslotUrl = DEFAULT_BOOKSLOT_URL,
+  theme,
+  service,
+  staff,
+  customer,
+  initialHeight,
+  maxWidth,
+  title,
+  className,
+  style,
+  onReady,
+  onResize,
+  onBooked,
+  onError
+}) {
+  const container = (0, import_react.useRef)(null);
+  const widget = (0, import_react.useRef)(null);
+  const latest = (0, import_react.useRef)({ service, staff, customer, onReady, onResize, onBooked, onError });
+  (0, import_react.useEffect)(() => {
+    latest.current = { service, staff, customer, onReady, onResize, onBooked, onError };
+  });
+  const themeKey = JSON.stringify(theme != null ? theme : {});
+  (0, import_react.useEffect)(() => {
+    let cancelled = false;
+    let instance = null;
+    loadBookSlot(bookslotUrl).then(
+      (api) => {
+        if (cancelled || !container.current) return;
+        const { service: service2, staff: staff2, customer: customer2 } = latest.current;
+        instance = api.mount(container.current, {
+          shop,
+          theme: JSON.parse(themeKey),
+          service: service2,
+          staff: staff2 || void 0,
+          prefill: customer2,
+          height: initialHeight,
+          maxWidth,
+          title
+        });
+        instance.on("ready", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onReady) == null ? void 0 : _b.call(_a, d);
+        }).on("resize", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onResize) == null ? void 0 : _b.call(_a, d);
+        }).on("booked", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onBooked) == null ? void 0 : _b.call(_a, d);
+        }).on("error", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onError) == null ? void 0 : _b.call(_a, d);
+        });
+        widget.current = instance;
+      },
+      (error) => {
+        var _a, _b;
+        if (!cancelled) (_b = (_a = latest.current).onError) == null ? void 0 : _b.call(_a, { message: error.message });
+      }
+    );
+    return () => {
+      cancelled = true;
+      instance == null ? void 0 : instance.destroy();
+      widget.current = null;
+    };
+  }, [shop, bookslotUrl, themeKey, initialHeight, maxWidth, title]);
+  (0, import_react.useEffect)(() => {
+    var _a;
+    if (service || staff !== void 0) (_a = widget.current) == null ? void 0 : _a.prefill({}, service, staff);
+  }, [service, staff]);
+  const customerKey = JSON.stringify(customer != null ? customer : {});
+  (0, import_react.useEffect)(() => {
+    var _a;
+    if (customerKey !== "{}") (_a = widget.current) == null ? void 0 : _a.prefill(JSON.parse(customerKey));
+  }, [customerKey]);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ref: container, className, style });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BookSlotWidget,
+  DEFAULT_BOOKSLOT_URL,
+  loadBookSlot
+});

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+declare const DEFAULT_BOOKSLOT_URL = "https://bookslot.taulantsela.com";
+type BookSlotTheme = {
+    /** Hex colour for buttons and highlights. */
+    primary?: string;
+    /** Hex colour for the widget background. */
+    background?: string;
+    /** Hex colour for text. */
+    text?: string;
+    /** Corner radius in pixels, 0–32. */
+    radius?: number;
+    font?: "sans" | "system" | "serif" | "mono";
+    scheme?: "light" | "dark" | "auto";
+};
+type BookSlotCustomer = {
+    name?: string;
+    email?: string;
+    phone?: string;
+    notes?: string;
+    /** Answers to the shop's custom questions, keyed by question key (Dashboard → Booking form). */
+    fields?: Record<string, string | number | boolean>;
+};
+type BookSlotBooking = {
+    appointmentId: string;
+    serviceId: string;
+    serviceName: string;
+    /** Who it's with; null when the shop has no staff. */
+    staffId: string | null;
+    staffName: string | null;
+    /** ISO timestamp. */
+    startsAt: string;
+    /** ISO timestamp. */
+    endsAt: string;
+    /** Human-readable time in the shop's timezone, e.g. "Thu, 12 Nov 2026 · 11:00–12:00". */
+    when: string;
+};
+type BookSlotWidgetProps = {
+    /** The shop's slug from the BookSlot dashboard. */
+    shop: string;
+    /** Where BookSlot runs. Defaults to the hosted service. */
+    bookslotUrl?: string;
+    /** Pro: match your site's look. Changing it reloads the widget. */
+    theme?: BookSlotTheme;
+    /** Pro: service id to preselect (listed in Dashboard → Widget). Can change at any time. */
+    service?: string;
+    /** Pro: staff member id to preselect (listed in Dashboard → Widget), or "" for anyone. Can change at any time. */
+    staff?: string;
+    /** Pro: details of the signed-in user. Sent by postMessage, never in the URL. */
+    customer?: BookSlotCustomer;
+    /** Height in pixels before the widget reports its own size. Default 720. */
+    initialHeight?: number;
+    /** Max width of the frame. Default 480px. */
+    maxWidth?: number | string;
+    /** Accessible title of the iframe. */
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (detail: {
+        shop: string;
+    }) => void;
+    onResize?: (detail: {
+        height: number;
+    }) => void;
+    /** Pro: a booking was made. */
+    onBooked?: (booking: BookSlotBooking) => void;
+    /** Pro: a booking failed. */
+    onError?: (detail: {
+        message: string;
+    }) => void;
+};
+type EventName = "ready" | "resize" | "booked" | "error";
+type BookSlotInstance = {
+    on(type: EventName, fn: (detail: unknown) => void): BookSlotInstance;
+    prefill(customer: BookSlotCustomer, service?: string, staff?: string): BookSlotInstance;
+    destroy(): void;
+};
+type BookSlotApi = {
+    version: number;
+    /** The BookSlot address this API talks to. */
+    origin?: string;
+    mount(target: HTMLElement, options: Record<string, unknown>): BookSlotInstance;
+};
+/** Loads widget.js once per BookSlot address and resolves with that address's API. */
+declare function loadBookSlot(bookslotUrl?: string): Promise<BookSlotApi>;
+declare function BookSlotWidget({ shop, bookslotUrl, theme, service, staff, customer, initialHeight, maxWidth, title, className, style, onReady, onResize, onBooked, onError, }: BookSlotWidgetProps): react.JSX.Element;
+
+export { type BookSlotBooking, type BookSlotCustomer, type BookSlotTheme, BookSlotWidget, type BookSlotWidgetProps, DEFAULT_BOOKSLOT_URL, loadBookSlot };

package/dist/index.d.ts

@@ -0,0 +1,89 @@
+import * as react from 'react';
+import { CSSProperties } from 'react';
+
+declare const DEFAULT_BOOKSLOT_URL = "https://bookslot.taulantsela.com";
+type BookSlotTheme = {
+    /** Hex colour for buttons and highlights. */
+    primary?: string;
+    /** Hex colour for the widget background. */
+    background?: string;
+    /** Hex colour for text. */
+    text?: string;
+    /** Corner radius in pixels, 0–32. */
+    radius?: number;
+    font?: "sans" | "system" | "serif" | "mono";
+    scheme?: "light" | "dark" | "auto";
+};
+type BookSlotCustomer = {
+    name?: string;
+    email?: string;
+    phone?: string;
+    notes?: string;
+    /** Answers to the shop's custom questions, keyed by question key (Dashboard → Booking form). */
+    fields?: Record<string, string | number | boolean>;
+};
+type BookSlotBooking = {
+    appointmentId: string;
+    serviceId: string;
+    serviceName: string;
+    /** Who it's with; null when the shop has no staff. */
+    staffId: string | null;
+    staffName: string | null;
+    /** ISO timestamp. */
+    startsAt: string;
+    /** ISO timestamp. */
+    endsAt: string;
+    /** Human-readable time in the shop's timezone, e.g. "Thu, 12 Nov 2026 · 11:00–12:00". */
+    when: string;
+};
+type BookSlotWidgetProps = {
+    /** The shop's slug from the BookSlot dashboard. */
+    shop: string;
+    /** Where BookSlot runs. Defaults to the hosted service. */
+    bookslotUrl?: string;
+    /** Pro: match your site's look. Changing it reloads the widget. */
+    theme?: BookSlotTheme;
+    /** Pro: service id to preselect (listed in Dashboard → Widget). Can change at any time. */
+    service?: string;
+    /** Pro: staff member id to preselect (listed in Dashboard → Widget), or "" for anyone. Can change at any time. */
+    staff?: string;
+    /** Pro: details of the signed-in user. Sent by postMessage, never in the URL. */
+    customer?: BookSlotCustomer;
+    /** Height in pixels before the widget reports its own size. Default 720. */
+    initialHeight?: number;
+    /** Max width of the frame. Default 480px. */
+    maxWidth?: number | string;
+    /** Accessible title of the iframe. */
+    title?: string;
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (detail: {
+        shop: string;
+    }) => void;
+    onResize?: (detail: {
+        height: number;
+    }) => void;
+    /** Pro: a booking was made. */
+    onBooked?: (booking: BookSlotBooking) => void;
+    /** Pro: a booking failed. */
+    onError?: (detail: {
+        message: string;
+    }) => void;
+};
+type EventName = "ready" | "resize" | "booked" | "error";
+type BookSlotInstance = {
+    on(type: EventName, fn: (detail: unknown) => void): BookSlotInstance;
+    prefill(customer: BookSlotCustomer, service?: string, staff?: string): BookSlotInstance;
+    destroy(): void;
+};
+type BookSlotApi = {
+    version: number;
+    /** The BookSlot address this API talks to. */
+    origin?: string;
+    mount(target: HTMLElement, options: Record<string, unknown>): BookSlotInstance;
+};
+/** Loads widget.js once per BookSlot address and resolves with that address's API. */
+declare function loadBookSlot(bookslotUrl?: string): Promise<BookSlotApi>;
+declare function BookSlotWidget({ shop, bookslotUrl, theme, service, staff, customer, initialHeight, maxWidth, title, className, style, onReady, onResize, onBooked, onError, }: BookSlotWidgetProps): react.JSX.Element;
+
+export { type BookSlotBooking, type BookSlotCustomer, type BookSlotTheme, BookSlotWidget, type BookSlotWidgetProps, DEFAULT_BOOKSLOT_URL, loadBookSlot };

package/dist/index.js

@@ -0,0 +1,129 @@
+"use client";
+
+// src/index.tsx
+import { useEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+var DEFAULT_BOOKSLOT_URL = "https://bookslot.taulantsela.com";
+function apiFor(origin, { justLoaded = false } = {}) {
+  var _a;
+  const globals = window;
+  const registered = (_a = globals.__bookslot) == null ? void 0 : _a[origin];
+  if (registered) return registered;
+  const legacy = globals.BookSlot;
+  return justLoaded && legacy && !legacy.origin ? legacy : void 0;
+}
+var loading = /* @__PURE__ */ new Map();
+function loadBookSlot(bookslotUrl = DEFAULT_BOOKSLOT_URL) {
+  if (typeof window === "undefined") {
+    return Promise.reject(new Error("BookSlot can only load in the browser"));
+  }
+  const base = bookslotUrl.replace(/\/+$/, "");
+  const origin = new URL(base || "/", window.location.href).origin;
+  const src = `${base}/widget.js`;
+  const loaded = loading.has(src) ? void 0 : apiFor(origin);
+  if (loaded) return Promise.resolve(loaded);
+  let promise = loading.get(src);
+  if (!promise) {
+    promise = new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.src = src;
+      script.async = true;
+      script.onload = () => {
+        const api = apiFor(origin, { justLoaded: true });
+        if (api) resolve(api);
+        else reject(new Error(`BookSlot: ${src} loaded but did not define BookSlot`));
+      };
+      script.onerror = () => {
+        loading.delete(src);
+        script.remove();
+        reject(new Error(`BookSlot: could not load ${src}`));
+      };
+      document.head.appendChild(script);
+    });
+    loading.set(src, promise);
+  }
+  return promise;
+}
+function BookSlotWidget({
+  shop,
+  bookslotUrl = DEFAULT_BOOKSLOT_URL,
+  theme,
+  service,
+  staff,
+  customer,
+  initialHeight,
+  maxWidth,
+  title,
+  className,
+  style,
+  onReady,
+  onResize,
+  onBooked,
+  onError
+}) {
+  const container = useRef(null);
+  const widget = useRef(null);
+  const latest = useRef({ service, staff, customer, onReady, onResize, onBooked, onError });
+  useEffect(() => {
+    latest.current = { service, staff, customer, onReady, onResize, onBooked, onError };
+  });
+  const themeKey = JSON.stringify(theme != null ? theme : {});
+  useEffect(() => {
+    let cancelled = false;
+    let instance = null;
+    loadBookSlot(bookslotUrl).then(
+      (api) => {
+        if (cancelled || !container.current) return;
+        const { service: service2, staff: staff2, customer: customer2 } = latest.current;
+        instance = api.mount(container.current, {
+          shop,
+          theme: JSON.parse(themeKey),
+          service: service2,
+          staff: staff2 || void 0,
+          prefill: customer2,
+          height: initialHeight,
+          maxWidth,
+          title
+        });
+        instance.on("ready", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onReady) == null ? void 0 : _b.call(_a, d);
+        }).on("resize", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onResize) == null ? void 0 : _b.call(_a, d);
+        }).on("booked", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onBooked) == null ? void 0 : _b.call(_a, d);
+        }).on("error", (d) => {
+          var _a, _b;
+          return (_b = (_a = latest.current).onError) == null ? void 0 : _b.call(_a, d);
+        });
+        widget.current = instance;
+      },
+      (error) => {
+        var _a, _b;
+        if (!cancelled) (_b = (_a = latest.current).onError) == null ? void 0 : _b.call(_a, { message: error.message });
+      }
+    );
+    return () => {
+      cancelled = true;
+      instance == null ? void 0 : instance.destroy();
+      widget.current = null;
+    };
+  }, [shop, bookslotUrl, themeKey, initialHeight, maxWidth, title]);
+  useEffect(() => {
+    var _a;
+    if (service || staff !== void 0) (_a = widget.current) == null ? void 0 : _a.prefill({}, service, staff);
+  }, [service, staff]);
+  const customerKey = JSON.stringify(customer != null ? customer : {});
+  useEffect(() => {
+    var _a;
+    if (customerKey !== "{}") (_a = widget.current) == null ? void 0 : _a.prefill(JSON.parse(customerKey));
+  }, [customerKey]);
+  return /* @__PURE__ */ jsx("div", { ref: container, className, style });
+}
+export {
+  BookSlotWidget,
+  DEFAULT_BOOKSLOT_URL,
+  loadBookSlot
+};

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@bookslot/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "React component for the BookSlot booking widget",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "booking",
+    "appointments",
+    "scheduling",
+    "widget",
+    "react",
+    "nextjs",
+    "bookslot"
+  ],
+  "homepage": "https://bookslot.taulantsela.com",
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}