@asksable/site-connector 0.1.6 → 0.3.0

package/README.md

@@ -40,9 +40,97 @@ import { BookingWidgetPanel, useSableSiteProfile } from '@asksable/site-connecto
 - `useSableSiteProfile`
 - `useSableSiteClient`
 - `useSableSiteConfig`
+- `useSableLocale`
+- `useTranslation`
 - `BookingWidgetPanel`
 - `getResolvedSiteProfile`
-- types for public site and booking payloads
+- `createTranslator`, `pickLocaleField`, `localeToIntl`, `TRANSLATIONS`, `DEFAULT_LOCALE`
+- types: `SableSiteConfig`, `Locale`, `TranslationKey`, `TranslationOverrides`, plus public site / booking payloads
+
+## Multi-language support
+
+The booking widget translates its own UI chrome (form labels, buttons, summaries, error messages, date/time formatting) to match the host site's language. **Every Sable customer website MUST declare its current language to the widget** so the customer never sees mismatched copy (e.g. an English "Confirm Booking" button on a Spanish-language site).
+
+Supported locales: `'en'` (default), `'es'`. Adding a locale requires a package version bump.
+
+### Three usage modes
+
+| Site type | Pattern |
+| --- | --- |
+| **Single-language site (English only)** | Omit `language` entirely or pass `'en'`. Widget defaults to English. |
+| **Single-language site (Spanish only)** | Pass `language: 'es'` once at provider mount. |
+| **Multi-language site with a toggle** | Pass a reactive value that updates when the toggle changes. The provider re-renders, the widget re-renders with the new locale. |
+
+### Multi-language example
+
+```tsx
+import { SableSiteProvider } from '@asksable/site-connector'
+import { useLanguage } from './your-i18n-context'
+
+function App() {
+  const { lang } = useLanguage() // your toggle owns this state
+  return (
+    <SableSiteProvider
+      config={{
+        apiUrl: import.meta.env.VITE_SABLE_PUBLIC_API_URL,
+        siteSlug: import.meta.env.VITE_SABLE_SITE_SLUG,
+        language: lang,
+      }}
+    >
+      <Routes />
+    </SableSiteProvider>
+  )
+}
+```
+
+The widget responds instantly to language changes — your toggle component flips both the host site's text and the widget by sharing the same `language` state.
+
+### Override individual strings (rare)
+
+When a specific client needs different brand voice (e.g. "Reserva mi entrega" instead of the canonical "Confirmar reserva"), pass `translationOverrides`:
+
+```tsx
+<SableSiteProvider
+  config={{
+    apiUrl,
+    siteSlug,
+    language: lang,
+    translationOverrides: {
+      es: { btnConfirmBooking: 'Reserva mi entrega' },
+    },
+  }}
+>
+  <App />
+</SableSiteProvider>
+```
+
+Use overrides sparingly. If a change would benefit all customers, extend the canonical dictionary in `translations.ts` and bump the package version instead.
+
+### What the widget translates
+
+Form labels, button text, mobile step labels, helper text, success/cancelled state copy, error messages, ARIA labels, date/time formatting (via `Intl.DateTimeFormat(locale)`), and currency formatting.
+
+### What the widget does NOT translate
+
+- **Service names, descriptions, category names** — these come from the Sable workspace. The widget reads `nameEn` / `nameEs` (or any `${field}En` / `${field}Es`) fields when available, falling back to the base field. If the workspace only entered one locale, that text renders regardless of UI language. (Future workstream: dashboard support for entering both locales.)
+- **Customer-typed input** — names, notes, etc.
+
+### Detecting locale in custom components
+
+If you build something inside `SableSiteProvider` that needs locale awareness, use the exposed hooks:
+
+```tsx
+import { useTranslation, useSableLocale } from '@asksable/site-connector'
+
+function MyComponent() {
+  const { t, locale } = useTranslation()
+  // t('contactFullName') → "Nombre completo" when locale is 'es'
+}
+```
+
+### For template builders
+
+Every Sable website template should include the `language` prop wiring as part of the boilerplate. If the template supports a toggle, the toggle component must flip both the host site's text and the widget by sharing the same language state. **Never let the widget and host site drift to different locales** — pass a single reactive `language` value into `SableSiteConfig` and the widget stays in sync automatically.
 
 ## Public API Contract
 

package/dist/bones/booking-widget.bones.json

@@ -0,0 +1,495 @@
+{
+    "breakpoints": {
+        "375": {
+            "name": "booking-widget",
+            "viewportWidth": 375,
+            "width": 375,
+            "height": 738,
+            "bones": [
+                [
+                    0,
+                    0,
+                    100,
+                    738,
+                    8,
+                    true
+                ],
+                [
+                    5.3333,
+                    20,
+                    89.3333,
+                    24,
+                    8
+                ],
+                [
+                    5.3333,
+                    77,
+                    89.3333,
+                    130,
+                    8
+                ],
+                [
+                    5.3333,
+                    207,
+                    89.3333,
+                    1,
+                    8
+                ],
+                [
+                    5.3333,
+                    210,
+                    89.3333,
+                    152,
+                    8
+                ],
+                [
+                    5.3333,
+                    362,
+                    89.3333,
+                    1,
+                    8
+                ],
+                [
+                    5.3333,
+                    662,
+                    89.3333,
+                    48,
+                    16
+                ]
+            ]
+        },
+        "768": {
+            "name": "booking-widget",
+            "viewportWidth": 768,
+            "width": 768,
+            "height": 738,
+            "bones": [
+                [
+                    0,
+                    0,
+                    100,
+                    738,
+                    8,
+                    true
+                ],
+                [
+                    3.125,
+                    20,
+                    93.75,
+                    31,
+                    8
+                ],
+                [
+                    3.125,
+                    88,
+                    93.75,
+                    107,
+                    8
+                ],
+                [
+                    3.125,
+                    195,
+                    93.75,
+                    1,
+                    8
+                ],
+                [
+                    3.125,
+                    198,
+                    93.75,
+                    107,
+                    8
+                ],
+                [
+                    3.125,
+                    305,
+                    93.75,
+                    1,
+                    8
+                ],
+                [
+                    3.125,
+                    666,
+                    93.75,
+                    48,
+                    16
+                ]
+            ]
+        },
+        "1280": {
+            "name": "booking-widget",
+            "viewportWidth": 1280,
+            "width": 1280,
+            "height": 738,
+            "bones": [
+                [
+                    0,
+                    0,
+                    100,
+                    738,
+                    8,
+                    true
+                ],
+                [
+                    3.75,
+                    48,
+                    92.5,
+                    31,
+                    8
+                ],
+                [
+                    3.75,
+                    111,
+                    25.8997,
+                    21,
+                    8
+                ],
+                [
+                    3.75,
+                    158,
+                    25.8997,
+                    121,
+                    12
+                ],
+                [
+                    3.75,
+                    280,
+                    25.8997,
+                    121,
+                    12
+                ],
+                [
+                    32.1497,
+                    111,
+                    41.2512,
+                    579,
+                    16,
+                    true
+                ],
+                [
+                    34.7278,
+                    136,
+                    9.2981,
+                    31,
+                    6
+                ],
+                [
+                    66.1353,
+                    137,
+                    2.1875,
+                    28,
+                    6
+                ],
+                [
+                    68.6353,
+                    137,
+                    2.1875,
+                    28,
+                    6
+                ],
+                [
+                    34.7278,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    39.9512,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    45.1746,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    50.3979,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    55.6213,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    60.8447,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    66.0681,
+                    190,
+                    4.7546,
+                    29,
+                    8
+                ],
+                [
+                    60.8447,
+                    247,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    66.0681,
+                    247,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    34.7278,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    39.9512,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    45.1746,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    50.3979,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    55.6213,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    60.8447,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    66.0681,
+                    301,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    34.7278,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    39.9512,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    45.1746,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    50.3979,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    55.6213,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    60.8447,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    66.0681,
+                    355,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    34.7278,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    39.9512,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    45.1746,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    50.3979,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    55.6213,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    60.8447,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    66.0681,
+                    409,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    34.7278,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    39.9512,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    45.1746,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    50.3979,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    55.6213,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    60.8447,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    66.0681,
+                    463,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    34.7278,
+                    517,
+                    4.7546,
+                    48,
+                    8
+                ],
+                [
+                    34.7278,
+                    589,
+                    36.095,
+                    26,
+                    8
+                ],
+                [
+                    48.0713,
+                    640,
+                    1.25,
+                    16,
+                    "50%"
+                ],
+                [
+                    49.79,
+                    639,
+                    7.688,
+                    18,
+                    8
+                ],
+                [
+                    75.9009,
+                    111,
+                    10.7581,
+                    21,
+                    8
+                ],
+                [
+                    75.9009,
+                    156,
+                    19.8804,
+                    120,
+                    8
+                ]
+            ]
+        }
+    },
+    "_hash": "020501954315e528d46c293201a85b5d"
+}

package/dist/bones/registry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/bones/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/bones/registry.ts"],"names":[],"mappings":""}

package/dist/bones/registry.js

@@ -0,0 +1,10 @@
+"use client";
+// Auto-generated by `npx boneyard-js build` — do not edit
+import { registerBones } from 'boneyard-js';
+import { configureBoneyard } from 'boneyard-js/react';
+import _booking_widget from './booking-widget.bones.json';
+configureBoneyard({ "color": "#efede7", "animate": "pulse" });
+registerBones({
+    "booking-widget": _booking_widget,
+});
+//# sourceMappingURL=registry.js.map

package/dist/bones/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/bones/registry.ts"],"names":[],"mappings":"AAAA,YAAY,CAAA;AACZ,0DAA0D;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,eAAe,MAAM,6BAA6B,CAAA;AAEzD,iBAAiB,CAAC,EAAC,OAAO,EAAC,SAAS,EAAC,SAAS,EAAC,OAAO,EAAC,CAAC,CAAA;AAExD,aAAa,CAAC;IACZ,gBAAgB,EAAE,eAAe;CAClC,CAAC,CAAA"}

package/dist/booking-widget.d.ts

@@ -1,9 +1,84 @@
 import { type ReactNode } from 'react';
+import './bones/registry.js';
+/**
+ * Pre-existing context required by reschedule mode. The host (or the
+ * customer arriving via magic link) is moving an existing booking, so
+ * the widget needs to know what booking is being moved and any data
+ * that should pre-fill or lock down the form.
+ */
+export type BookingRescheduleContext = {
+    appointmentId: string;
+    /** Original startTime (ms epoch) of the booking being moved. Shown
+     *  as crossed-out in the sidebar so the user knows what they're
+     *  giving up. */
+    formerStartTime: number;
+    formerEndTime: number;
+    /** Locked service for the reschedule — cannot be changed without
+     *  cancelling and re-booking. */
+    serviceId: string;
+    /** Optional staff lock. When set, the staff picker is pre-filled
+     *  to this member; when omitted the widget falls back to "any
+     *  available". */
+    staffMemberId?: string;
+    /** Pre-fill values for the contact form, sourced from the original
+     *  appointment's customer record. */
+    customerName?: string;
+    customerEmail?: string;
+    customerPhone?: string;
+    /** Display label for the sidebar's "Reschedule by" line, sourced
+     *  from the original appointment record (host display name). */
+    rescheduledByName?: string;
+};
 type BookingWidgetProps = {
     title?: string;
     description?: string;
     mobileHeader?: ReactNode;
+    /**
+     * Widget mode. 'create' (default) is the original behavior. In
+     * 'reschedule' mode the widget pre-fills service/staff/customer
+     * from `rescheduleContext`, swaps the CTA copy, and routes the
+     * submit through `onRescheduleSubmit` instead of the public-create
+     * mutation. Adding this as an opt-in prop keeps the npm package
+     * fully backward compatible — every existing consumer that omits
+     * `mode` continues to behave exactly as before.
+     */
+    mode?: 'create' | 'reschedule';
+    rescheduleContext?: BookingRescheduleContext;
+    /**
+     * Submit handler for reschedule mode. Receives the new slot the
+     * user picked. The host pages this through `api.appointments
+     * .rescheduleAppointment` (admin path) or a magic-link-protected
+     * public mutation (customer path). Required when `mode` is
+     * 'reschedule'.
+     */
+    onRescheduleSubmit?: (args: {
+        newStartTime: number;
+        newEndTime: number;
+    }) => Promise<void>;
+    /**
+     * Destination for the success-state CTA after a new booking is submitted.
+     * Defaults to the host site's home page so embedded sites don't trap the
+     * customer back on `/booking` after the thank-you state.
+     */
+    successRedirectHref?: string;
+    /**
+     * Dev-only: forces the widget into a terminal state without
+     * calling any backend mutation. Used by the dev preview page to
+     * iterate on success/cancel visuals without spinning through the
+     * form each time. Strip from prod surfaces — these never call any
+     * backend.
+     *
+     * - `'success'`: renders the "You're All Set!" view (or the
+     *   reschedule variant when `mode === 'reschedule'`).
+     * - `'cancelled'`: renders the "Booking cancelled" view (preview
+     *   only — the customer-side cancel mutation isn't built yet).
+     *
+     * The legacy `__devForceSuccess` boolean is still accepted for
+     * back-compat with surfaces that use the old prop.
+     */
+    __devForceState?: 'success' | 'cancelled' | 'payment-full' | 'payment-deposit';
+    __devForceSuccess?: boolean;
 };
-export declare function BookingWidgetPanel({ title, description, mobileHeader, }: BookingWidgetProps): import("react/jsx-runtime").JSX.Element;
+export declare function BookingWidgetPanel({ title, description, mobileHeader, mode, rescheduleContext, onRescheduleSubmit, successRedirectHref, __devForceState, __devForceSuccess, }: BookingWidgetProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=booking-widget.d.ts.map

package/dist/booking-widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"booking-widget.d.ts","sourceRoot":"","sources":["../src/booking-widget.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA+D,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAOnG,KAAK,kBAAkB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,SAAS,CAAA;CACzB,CAAA;AAID,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,WAAW,EACX,YAAY,GACb,EAAE,kBAAkB,2CA+gCpB"}
+{"version":3,"file":"booking-widget.d.ts","sourceRoot":"","sources":["../src/booking-widget.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAqH,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AASzJ,OAAO,qBAAqB,CAAA;AA4C5B;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,aAAa,EAAE,MAAM,CAAA;IACrB;;qBAEiB;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,aAAa,EAAE,MAAM,CAAA;IACrB;qCACiC;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB;;sBAEkB;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;yCACqC;IACrC,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;oEACgE;IAChE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,KAAK,kBAAkB,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,SAAS,CAAA;IACxB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IAC9B,iBAAiB,CAAC,EAAE,wBAAwB,CAAA;IAC5C;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE;QAC1B,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;;;;;;OAcG;IACH,eAAe,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,cAAc,GAAG,iBAAiB,CAAA;IAC9E,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B,CAAA;AAKD,wBAAgB,kBAAkB,CAAC,EACjC,KAAK,EACL,WAAW,EACX,YAAY,EACZ,IAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,mBAAyB,EACzB,eAAe,EACf,iBAAiB,GAClB,EAAE,kBAAkB,2CA2uEpB"}