@riverbankcms/sdk 0.90.1 → 0.92.0

package/dist/cli/init-docs/content/workflow-add-block.md

@@ -49,6 +49,16 @@ riverbankcms block list home
 riverbankcms block upsert <page-id> <block-id> --kind <block-kind> --data '<json>'
 ```
 
+### Authoring Block JSON
+
+Use `block-types.md` and `block-types-site.md` as the source of truth for fields.
+
+- Fields marked `required` must be present with a valid value.
+- Fields not marked `required` may be omitted. You do not need to include every optional key or set unused optional values to `null`.
+- Defaults shown in the block reference are applied by the editor/rendering contract. Include an optional field only when you want to override that default.
+- For nested objects and repeaters, required child fields apply once you include the parent value. For example, an omitted `images` repeater is valid, but `images: [{}]` is not because the item is present and its required `image` field is missing.
+- `null` is only valid for field types that explicitly accept clearing to no value. When in doubt, omit optional fields instead of sending `null`.
+
 **Examples:**
 
 Add a hero block:
@@ -59,6 +69,44 @@ riverbankcms block upsert home main-hero \
   --data '{"heading": "Welcome", "subheading": "to our website"}'
 ```
 
+Add a minimal media and text block:
+
+`block.media-text` has many display and carousel fields, but most are optional controls with defaults. A minimal content-only block only needs rich text:
+
+```json
+{
+  "text": {
+    "type": "doc",
+    "content": [
+      {
+        "type": "paragraph",
+        "content": [{ "type": "text", "text": "Welcome to our space." }]
+      }
+    ]
+  }
+}
+```
+
+Add media only when you have a complete media item:
+
+```json
+{
+  "text": {
+    "type": "doc",
+    "content": [{ "type": "paragraph", "content": [] }]
+  },
+  "images": [
+    {
+      "image": {
+        "type": "image",
+        "src": "/images/studio.jpg",
+        "alt": "A bright studio room"
+      }
+    }
+  ]
+}
+```
+
 Add a body text block:
 
 ```bash

package/dist/cli/init-docs/content/workflow-custom-block.md

@@ -105,6 +105,16 @@ Common field types for custom blocks:
 | `repeater` | List of nested fields | `schema`, `minItems`, `maxItems` |
 | `group` | Grouped fields | `schema` |
 
+### Step 2.5: Model Required Fields Carefully
+
+The same content authoring rules apply to custom blocks and system blocks:
+
+- Leave `required` unset or `false` for fields that can be omitted from pushed JSON.
+- Use `defaultValue` for optional controls that should have a stable editor/rendering default.
+- Set `required: true` only when every pushed block must provide that field.
+- For repeaters and groups, required child fields apply when the parent item/object is present. If a repeater item has `{ id: 'title', required: true }`, then every item in that repeater must include `title`.
+- In React overrides, type optional fields as optional and handle missing values with defaults or conditional rendering.
+
 ### Step 3: Create React Override Component
 
 Create a component to render your block:

package/dist/client/{accordion-4K7VGZ3I.mjs → accordion-BUDH2G3S.mjs}

@@ -1,5 +1,5 @@
-import { defineIslandPropsDecoder } from './chunk-B4H6QMPY.mjs';
-import './chunk-3H5CLFKT.mjs';
+import { defineIslandPropsDecoder } from './chunk-R3CZQLXF.mjs';
+import './chunk-GH6IIOOE.mjs';
 
 // src/rendering/islands/enhancers/accordion.ts
 var decode = defineIslandPropsDecoder("accordion");

package/dist/client/{bookingForm-3QXA3CIS.mjs → bookingForm-NQMCELVB.mjs}

@@ -1,15 +1,15 @@
 "use client";
-import { buildBookingPaymentSelectionViewModel, usePolling } from './chunk-5AJIMWKS.mjs';
-import { SpinnerNode } from './chunk-KNTLBQ3N.mjs';
+import { buildBookingPaymentSelectionViewModel, usePolling } from './chunk-N2WJPTF7.mjs';
+import { SpinnerNode } from './chunk-QQNVQ62W.mjs';
 import { buildRouteIslandApiConfig } from './chunk-L4J5Y62O.mjs';
-import { scrollToBlock, useDiscountCodeUi, buildCheckoutReturnUrls, DiscountCodeDisclosure } from './chunk-SLY6UDAS.mjs';
+import { scrollToBlock, useDiscountCodeUi, buildCheckoutReturnUrls, DiscountCodeDisclosure } from './chunk-ZJDBOLX7.mjs';
 import { FieldValidationMessage, getFieldValidationControlProps } from './chunk-3DCJ45Z2.mjs';
 import './chunk-WBQG7VJA.mjs';
-import { isSpamProtectionEnabled, getChallengeUrl, AltchaWidget } from './chunk-HIHOQGIP.mjs';
-import { BlockApiProvider, useBlockApi, FeedbackMessage } from './chunk-WHZQDPBZ.mjs';
+import { isSpamProtectionEnabled, getChallengeUrl, AltchaWidget } from './chunk-LJCX6V7Q.mjs';
+import { BlockApiProvider, useBlockApi, FeedbackMessage } from './chunk-TNGL2WJF.mjs';
 import { mountReactIsland } from './chunk-N7PBWBWQ.mjs';
-import { defineIslandPropsDecoder, resolveBookingSiteId, resolveDefaultBookingServiceId, getBookingRedirectStateFromLocation, deriveBookingFormViewState, logger, getBookingSuccessMessage, resolveAppointmentCheckoutVerificationState, themeButtonClassName, toSelectedCollectionOptionKind, assertNever, prepareBookingSubmission, formatBookingSubmissionPreparationError, resolveBookingPaymentStep, BOOKING_FORM_DATA_RESERVED_KEYS, clearWorkflowFeedback, reportWorkflowError, reportWorkflowSuccess, okWith, err } from './chunk-B4H6QMPY.mjs';
-import { resolveBookingTimeZoneId, DEFAULT_BOOKING_TIME_ZONE, unsafeAsFormId, unsafeAsAppointmentResourceId, unsafeAsCustomerPassId, unsafeAsAppointmentServiceId, formatLocalScheduleDate, addLocalScheduleDays, parseBookingLocalDate, unsafeAsPassId, formatBookingInstant } from './chunk-3H5CLFKT.mjs';
+import { defineIslandPropsDecoder, resolveBookingSiteId, resolveDefaultBookingServiceId, getBookingRedirectStateFromLocation, deriveBookingFormViewState, logger, getBookingSuccessMessage, getBookingServiceSlidingScale, formatBookingCentsAsCurrencyInput, parseBookingCurrencyInputToCents, resolveAppointmentCheckoutVerificationState, themeButtonClassName, toSelectedCollectionOptionKind, assertNever, prepareBookingSubmission, formatBookingSubmissionPreparationError, resolveBookingPaymentStep, BOOKING_FORM_DATA_RESERVED_KEYS, isBookingServiceSlidingAmountInRange, clearWorkflowFeedback, reportWorkflowError, reportWorkflowSuccess, okWith, err } from './chunk-R3CZQLXF.mjs';
+import { resolveBookingTimeZoneId, DEFAULT_BOOKING_TIME_ZONE, unsafeAsFormId, unsafeAsAppointmentResourceId, unsafeAsCustomerPassId, unsafeAsAppointmentServiceId, formatLocalScheduleDate, addLocalScheduleDays, parseBookingLocalDate, unsafeAsPassId, formatCurrencyAmount, formatBookingInstant } from './chunk-GH6IIOOE.mjs';
 import React2, { useRef, useState, useMemo, useReducer, useEffect, useCallback, useLayoutEffect } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
@@ -514,6 +514,7 @@ function useBookingSubmission(_siteId) {
         customFields: data.customFields,
         timezone: data.timezone,
         discountCode: data.discountCode,
+        selectedSlidingAmount: data.selectedSlidingAmount,
         selectedCollectionOptionKind: data.selectedCollectionOptionKind,
         altchaSolution: data.altchaSolution ?? null,
         successUrl: data.successUrl,
@@ -583,6 +584,9 @@ function createInitialBookingFlowReducerState(input) {
     fieldValues: collectInitialFieldValues(initialData),
     touchedFields: {},
     discountCode: toOptionalString(initialData.discountCode) ?? "",
+    selectedSlidingAmountInput: toOptionalString(
+      initialData.selectedSlidingAmountInput
+    ) ?? "",
     selectedCollectionOptionKind: toSelectedCollectionOptionKind(
       initialData.selectedCollectionOptionKind
     ),
@@ -635,6 +639,7 @@ function bookingFlowReducer(state, event) {
         selectedDate: void 0,
         selectedSlot: null,
         selectedAppointmentPackageId: void 0,
+        selectedSlidingAmountInput: "",
         selectedCollectionOptionKind: void 0,
         validationErrors: clearBookingFormError(state.validationErrors)
       };
@@ -688,6 +693,13 @@ function bookingFlowReducer(state, event) {
         selectedAppointmentPackageId: void 0,
         validationErrors: clearBookingFormError(state.validationErrors)
       };
+    case "sliding-amount-changed":
+      return {
+        ...state,
+        selectedSlidingAmountInput: event.value,
+        selectedAppointmentPackageId: void 0,
+        validationErrors: clearBookingFormError(state.validationErrors)
+      };
     case "appointment-package-selected":
       return {
         ...state,
@@ -790,6 +802,7 @@ function toBookingFormData(state) {
     selectedDate: state.selectedDate,
     selectedSlot: state.selectedSlot?.startAt,
     discountCode: state.discountCode || void 0,
+    selectedSlidingAmountInput: state.selectedSlidingAmountInput || void 0,
     selectedCollectionOptionKind: state.selectedCollectionOptionKind,
     selectedAppointmentPackageId: state.selectedAppointmentPackageId
   };
@@ -807,7 +820,8 @@ function buildBookingStepResolution(input) {
     input.form.settings?.serviceIds && input.form.settings.serviceIds.length > 1
   );
   const selectedService = paymentResolution.service;
-  const needsPayment = paymentResolution.mode !== "hidden" || Boolean(
+  const selectedServiceSlidingScale = getBookingServiceSlidingScale(selectedService);
+  const needsPayment = Boolean(selectedServiceSlidingScale) || paymentResolution.mode !== "hidden" || Boolean(
     input.enableAppointmentPackages && selectedService && (selectedService.priceAmount ?? 0) > 0
   );
   const hasFields = Boolean(input.form.schema?.fields.length);
@@ -851,6 +865,18 @@ function validateBookingStep(input) {
         services: input.services,
         defaultServiceId: input.defaultServiceId
       });
+      const slidingScale = getBookingServiceSlidingScale(resolution.service);
+      if (slidingScale && !isBookingServiceSlidingAmountInRange(
+        slidingScale,
+        parseBookingCurrencyInputToCents(input.data.selectedSlidingAmountInput)
+      )) {
+        return {
+          ok: false,
+          errors: createFormBookingValidationError(
+            "Please choose an amount within the sliding scale"
+          )
+        };
+      }
       if (resolution.mode === "hidden" || resolution.mode === "disclosure_only") {
         return { ok: true };
       }
@@ -1260,11 +1286,27 @@ function useHeadlessBookingFlow(options) {
   const selectedServiceId = state.selectedServiceId ?? defaultServiceId;
   const selectedResourceId = state.selectedResourceId ?? defaultResourceId;
   const selectedService = options.services.find((service) => service.id === selectedServiceId) ?? null;
+  const lastSlidingServiceIdRef = useRef(null);
+  useEffect(() => {
+    const selectedId = selectedService?.id ?? null;
+    if (lastSlidingServiceIdRef.current === selectedId) return;
+    lastSlidingServiceIdRef.current = selectedId;
+    const slidingScale = getBookingServiceSlidingScale(selectedService);
+    dispatch({
+      type: "sliding-amount-changed",
+      value: slidingScale?.suggestedAmount !== null && slidingScale?.suggestedAmount !== void 0 ? formatBookingCentsAsCurrencyInput(slidingScale.suggestedAmount) : ""
+    });
+  }, [selectedService]);
   const hasPortalBearerAuth = (api.config.authOverrides?.portal ?? api.config.auth).type === "bearer";
+  const selectedServiceSlidingScale = getBookingServiceSlidingScale(selectedService);
+  const selectedSlidingAmount = parseBookingCurrencyInputToCents(
+    state.selectedSlidingAmountInput
+  );
+  const selectedAppointmentPriceAmount = selectedServiceSlidingScale && selectedSlidingAmount !== null ? selectedSlidingAmount : selectedService?.priceAmount ?? 0;
   const canLoadAppointmentPackages = Boolean(
-    options.enableAppointmentPackages && hasPortalBearerAuth && selectedService && (selectedService.priceAmount ?? 0) > 0
+    options.enableAppointmentPackages && hasPortalBearerAuth && selectedService && !selectedServiceSlidingScale && (selectedService.priceAmount ?? 0) > 0
   );
-  const appointmentPackagesUnavailableReason = !options.enableAppointmentPackages ? "disabled" : !selectedService || (selectedService.priceAmount ?? 0) <= 0 ? "missing-priced-service" : !hasPortalBearerAuth ? "missing-portal-auth" : null;
+  const appointmentPackagesUnavailableReason = !options.enableAppointmentPackages ? "disabled" : !selectedService || selectedServiceSlidingScale || (selectedService.priceAmount ?? 0) <= 0 ? "missing-priced-service" : !hasPortalBearerAuth ? "missing-portal-auth" : null;
   const data = useMemo(() => toBookingFormData(state), [state]);
   const availabilityDatesQuery = useMemo(
     () => buildBookingAvailabilityQuery({
@@ -1494,13 +1536,13 @@ function useHeadlessBookingFlow(options) {
     state.selectedSlot
   ]);
   const appointmentDiscountContext = useMemo(
-    () => selectedService && (selectedService.priceAmount ?? 0) > 0 ? { type: "appointment", serviceId: selectedService.id } : null,
-    [selectedService?.id, selectedService?.priceAmount]
+    () => selectedService && selectedAppointmentPriceAmount > 0 ? { type: "appointment", serviceId: selectedService.id } : null,
+    [selectedAppointmentPriceAmount, selectedService?.id]
   );
   const discountUi = useDiscountCodeUi({
     api,
     discountContext: appointmentDiscountContext,
-    subtotalCents: selectedService?.priceAmount ?? 0
+    subtotalCents: selectedAppointmentPriceAmount
   });
   const { submit, clearFeedback } = useBookingSubmission(options.siteId);
   const submittingRef = useRef(false);
@@ -1643,6 +1685,7 @@ function useHeadlessBookingFlow(options) {
         type: "appointment-package-selected",
         packageId: packageId ? unsafeAsCustomerPassId(packageId) : null
       }),
+      setSlidingAmountInput: (value) => dispatch({ type: "sliding-amount-changed", value }),
       setDiscountCode: (code) => {
         dispatch({ type: "discount-code-changed", code });
         latestRef.current.setDiscountCode(code);
@@ -1713,11 +1756,11 @@ function useHeadlessBookingFlow(options) {
     () => selectedService && paymentResolution.mode !== "unsupported" ? buildBookingPaymentSelectionViewModel({
       serviceTitle: selectedService.title,
       paymentTerms: selectedService.paymentTerms,
-      priceAmount: selectedService.priceAmount,
+      priceAmount: selectedAppointmentPriceAmount,
       priceCurrency: selectedService.priceCurrency,
       bookingStartAt: state.selectedSlot?.startAt
     }) : null,
-    [paymentResolution.mode, selectedService, state.selectedSlot?.startAt]
+    [paymentResolution.mode, selectedAppointmentPriceAmount, selectedService, state.selectedSlot?.startAt]
   );
   const appointmentPackageItems = appointmentPackages.tag === "loaded" ? appointmentPackages.value : [];
   const selectedAppointmentPackage = appointmentPackageItems.find(
@@ -1746,6 +1789,9 @@ function useHeadlessBookingFlow(options) {
     selection: null,
     selectedCollectionOptionKind: state.selectedCollectionOptionKind,
     selectedAppointmentPackageId: state.selectedAppointmentPackageId,
+    selectedSlidingAmountInput: state.selectedSlidingAmountInput,
+    selectedSlidingAmount,
+    slidingScale: selectedServiceSlidingScale,
     appointmentPackages: appointmentPackagesModel,
     errorMessage: paymentResolution.errorMessage ?? "This service cannot be booked right now."
   } : {
@@ -1754,6 +1800,9 @@ function useHeadlessBookingFlow(options) {
     selection: paymentSelection,
     selectedCollectionOptionKind: state.selectedCollectionOptionKind,
     selectedAppointmentPackageId: state.selectedAppointmentPackageId,
+    selectedSlidingAmountInput: state.selectedSlidingAmountInput,
+    selectedSlidingAmount,
+    slidingScale: selectedServiceSlidingScale,
     appointmentPackages: appointmentPackagesModel
   };
   return {
@@ -1959,6 +2008,9 @@ var paymentOptionLayoutStyle = {
 var summaryStackStyle = {
   gap: "0.125rem"
 };
+function formatBookingAmount(amount, currency) {
+  return formatCurrencyAmount(amount, currency, { decimals: "auto" });
+}
 function HeadlessBookingDefaultForm({
   booking,
   onSubmit
@@ -2235,6 +2287,7 @@ function HeadlessBookingPaymentSelectionStep({
   }
   const packageOptions = booking.payment.appointmentPackages.items;
   const hasPackageOptions = packageOptions.length > 0;
+  const slidingScale = booking.payment.slidingScale;
   return /* @__PURE__ */ jsxs("div", { className: "ab-stack", children: [
     /* @__PURE__ */ jsxs("div", { className: "ab-info-box", children: [
       /* @__PURE__ */ jsx("h3", { className: "ab-subtitle", children: viewModel.sectionTitle }),
@@ -2245,6 +2298,28 @@ function HeadlessBookingPaymentSelectionStep({
       booking.payment.appointmentPackages.state.message,
       " You can continue with the normal payment option."
     ] }) : null,
+    slidingScale ? /* @__PURE__ */ jsxs("div", { className: "rb-space-y-2", children: [
+      /* @__PURE__ */ jsx("label", { htmlFor: "appointment-sliding-amount", className: "form-label", children: "Choose your price" }),
+      /* @__PURE__ */ jsxs("p", { className: "rb-caption status-muted", children: [
+        formatBookingAmount(slidingScale.minAmount, slidingScale.currency),
+        " to ",
+        formatBookingAmount(slidingScale.maxAmount, slidingScale.currency),
+        slidingScale.suggestedAmount !== null ? `, suggested ${formatBookingAmount(slidingScale.suggestedAmount, slidingScale.currency)}` : ""
+      ] }),
+      /* @__PURE__ */ jsx(
+        "input",
+        {
+          id: "appointment-sliding-amount",
+          type: "number",
+          className: "form-input",
+          min: slidingScale.minAmount / 100,
+          max: slidingScale.maxAmount / 100,
+          step: "0.01",
+          value: booking.payment.selectedSlidingAmountInput,
+          onChange: (event) => booking.actions.setSlidingAmountInput(event.target.value)
+        }
+      )
+    ] }) : null,
     /* @__PURE__ */ jsxs("div", { className: "ab-stack", role: "list", "aria-label": "Payment options", children: [
       packageOptions.map((appointmentPackage) => {
         const isSelected = booking.payment.selectedAppointmentPackageId === appointmentPackage.customerPassId;