@servicetitan/dte-unlayer 0.158.0 → 0.159.0

package/src/editor.tsx

@@ -7,6 +7,9 @@ import {
     useRef,
     useState,
 } from 'react';
+import { useBusinessCalendarState } from './business-calendar/business-calendar-state';
+import { BusinessCalendarDrawer } from './business-calendar/BusinessCalendarDrawer';
+import { useBusinessCalendarRequests } from './business-calendar/useBusinessCalendarRequests';
 import { DisplayConditionModal } from './display-conditions/DisplayConditionModal';
 import { ESignDateSignedOffsetModal } from './e-sign-offset/ESignDateSignedOffsetModal';
 import { getErrorMessage } from './log';
@@ -133,6 +136,9 @@ export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props,
         return () => store.setOnCalcFieldSelect();
     }, [props.opts.onCalcFieldSelect, store]);
 
+    const businessCalendar = useBusinessCalendarRequests(store, props.opts);
+    useBusinessCalendarState(store, props.opts);
+
     const { minHeight = 800, style = {} } = props;
 
     return (
@@ -155,6 +161,15 @@ export const UnlayerEditor = forwardRef<UnlayerRef, UnlayerEditorProps>((props,
                     onConditionFormSelect={props.opts.onConditionFormSelect}
                 />
             )}
+            {businessCalendar.drawer && props.opts.onScheduleBindingsChange && (
+                <BusinessCalendarDrawer
+                    key={businessCalendar.drawer.id}
+                    request={businessCalendar.drawer}
+                    host={props.opts}
+                    portalContainer={props.opts.displayConditionModalPortalContainer}
+                    onClose={businessCalendar.closeDrawer}
+                />
+            )}
         </div>
     );
 });

package/src/index.ts

@@ -21,3 +21,13 @@ export { versions } from './unlayer';
 export * from './shared/date-calc';
 export { emptyArrayIfNull } from './shared/nunjucks-helpers';
 export * from './display-conditions/lookupOptionsController';
+export type {
+    BusinessCalendarHostProps,
+    BusinessCalendarRules,
+    BusinessDaySchedule,
+    FieldScheduleBinding,
+    HolidayCatalog,
+    KnownHoliday,
+    SaveScheduleRequest,
+    WeekendDay,
+} from '@servicetitan/dte-shared';

package/src/shared/const.ts

@@ -1,3 +1,4 @@
+import type { BusinessDaySchedule, HolidayCatalog } from '@servicetitan/dte-shared';
 import type { DisplayConditionState } from '../display-conditions/types';
 import type { BusinessCalendar } from './date-calc';
 import { SchemaObject } from './schema';
@@ -49,6 +50,62 @@ export interface UnlayerEventESignOffset {
     value: ESignDateSignedOffsetSettings;
 }
 
+/**
+ * Names shown for e-sign field types whose title differs from the type list entry it is derived
+ * from (by type value). Only the label changes: the stored value stays, so saved designs and the
+ * `esign_<recipient>_<type>` placeholder are unaffected.
+ */
+export const E_SIGN_FIELD_TYPE_LABELS: Readonly<Record<string, string | undefined>> = {
+    [E_SIGN_DATE_SIGNED_OFFSET_TYPE]: 'Calculated Signing Date',
+};
+
+/**
+ * Payload of `--business-calendar-request` (iframe to parent): what a date field's inline schedule
+ * settings (a calculated field's or an e-sign "Date Signed Offset" field's) ask the parent window
+ * to do. `fieldKey` is the tool's instance id (`values.id`), the key DTE binds the schedule to.
+ * - `toggle` / `select`: the exclusion toggle and the schedule picker.
+ * - `create` / `edit`: open the schedule drawer, for a new schedule or `scheduleId`.
+ * - `delete`: delete the selected schedule; the outcome comes back as `--business-calendar-result`.
+ */
+export type UnlayerEventBusinessCalendarRequest =
+    | { action: 'toggle'; fieldKey: string; enabled: boolean }
+    | { action: 'select'; fieldKey: string; scheduleId?: number }
+    | { action: 'create'; fieldKey: string }
+    | { action: 'edit'; fieldKey: string; scheduleId: number }
+    | { action: 'delete'; fieldKey: string; scheduleId: number; requestId: string };
+
+/** Payload of `--business-calendar-result` (parent to iframe): how a `delete` request ended. */
+export interface UnlayerEventBusinessCalendarResult {
+    requestId: string;
+    /** Why it failed, shown under the schedule; absent on success. */
+    error?: string;
+}
+
+/**
+ * Payload of `--business-calendar-state` (parent to iframe), sent whenever the host's schedule
+ * props change: what the property editors show and the calendars the previews use.
+ */
+export interface UnlayerEventBusinessCalendarState {
+    /** Whether the host edits schedules (it passes `onScheduleBindingsChange`). */
+    enabled: boolean;
+    /** The fields whose exclusion toggle is on, by field key, with their schedule (none: default). */
+    bindings: Record<string, { scheduleId?: number }>;
+    /** The schedules a field can pick, default first, as the host passes them. */
+    schedules: BusinessDaySchedule[];
+    schedulesLoading?: boolean;
+    schedulesError?: string;
+    /** The tenant's known holidays, for the schedule preview's names. */
+    holidayCatalog?: HolidayCatalog;
+    holidayCatalogLoading?: boolean;
+    holidayCatalogError?: string;
+    /** Whether the host can delete schedules (it passes `onDeleteSchedule`). */
+    canDeleteSchedule: boolean;
+    /** Calendars of the bound fields, by field key. */
+    fieldCalendars: Record<string, BusinessCalendar>;
+    /** The default calendar's holidays. */
+    holidays?: string[];
+}
+
 export interface UnlayerEditorUnit {
     id: string;
     generic: string;
@@ -78,6 +135,8 @@ export interface UnlayerEventRegister {
     units?: UnlayerEditorUnit[];
     eSignRecipients?: UnlayerEditorESignRecipientInfo[];
     eSignFieldTypes?: string[];
+    /** {@link E_SIGN_FIELD_TYPE_LABELS}, for the e-sign tool's canvas label. */
+    eSignFieldTypeLabels?: Readonly<Record<string, string | undefined>>;
     customTools?: {
         key: string;
         title?: string;

package/src/store.ts

@@ -4,11 +4,15 @@ import { loadScript } from './loadScript';
 import { logUnlayerError } from './log';
 import { toUnlayerMergeTags, type UnlayerMergeTagsConfig } from './merge-tags';
 import { defaultImageValidation } from './shared/configs';
-import type {
-    UnlayerEditorTwin,
-    UnlayerEventConfig,
-    UnlayerEventESignOffset,
-    UnlayerEventRegister,
+import {
+    E_SIGN_FIELD_TYPE_LABELS,
+    type UnlayerEditorTwin,
+    type UnlayerEventBusinessCalendarRequest,
+    type UnlayerEventBusinessCalendarResult,
+    type UnlayerEventBusinessCalendarState,
+    type UnlayerEventConfig,
+    type UnlayerEventESignOffset,
+    type UnlayerEventRegister,
 } from './shared/const';
 import { normalizeESignOffsetSettings } from './shared/e-sign-offset';
 import { unlayerSupportedFonts } from './shared/fonts';
@@ -212,6 +216,9 @@ export class UnlayerStore {
     private isEditorReady = false;
     private isMergeTagsApplied = false;
     private mergeTagsConfig?: UnlayerMergeTagsConfig;
+    /** Latest `--business-calendar-state` payload, and the last one sent to the iframe. */
+    private businessCalendarStateJson?: string;
+    private sentBusinessCalendarStateJson?: string;
 
     private onMessageCB?: (type: string, data: any) => void;
     private onChangeCB?: (info: UnlayerDesignChangeInfo) => void;
@@ -222,6 +229,7 @@ export class UnlayerStore {
     private onFormSelectCB?: (formId: number) => void;
     private onCalcFieldOpenCB?: (usedFormIds: number[]) => void;
     private onCalcFieldSelectCB?: (fieldKeys: string[]) => void;
+    private onBusinessCalendarRequestCB?: (request: UnlayerEventBusinessCalendarRequest) => void;
 
     constructor(readonly props: CreateUnlayerEditorProps) {
         const schemaData = this.props.schema ? schemaBuildMap(this.props.schema) : undefined;
@@ -232,6 +240,7 @@ export class UnlayerStore {
                 .map(field => field.fullKey),
         );
 
+        // Each entry's type value is derived from it; the name shown can differ (E_SIGN_FIELD_TYPE_LABELS).
         this.props.eSignFieldTypes = [
             'Signature',
             'Initials',
@@ -379,6 +388,32 @@ export class UnlayerStore {
         this.onCalcFieldSelectCB = onCalcFieldSelect;
     };
 
+    setOnBusinessCalendarRequest = (
+        onBusinessCalendarRequest?: UnlayerStore['onBusinessCalendarRequestCB'],
+    ) => {
+        this.onBusinessCalendarRequestCB = onBusinessCalendarRequest;
+    };
+
+    /** Tells the iframe how a schedule `delete` request ended. */
+    sendBusinessCalendarResult = (result: UnlayerEventBusinessCalendarResult) => {
+        this.sendMessage('--business-calendar-result', JSON.parse(JSON.stringify(result)));
+    };
+
+    /**
+     * Keeps the schedule state for the iframe and sends it once the tools core has loaded (it
+     * goes out again right after `--config`). An unchanged state isn't sent again.
+     */
+    setBusinessCalendarState = (state: UnlayerEventBusinessCalendarState) => {
+        this.businessCalendarStateJson = JSON.stringify(state);
+
+        if (
+            this.hasCoreLoaded &&
+            this.businessCalendarStateJson !== this.sentBusinessCalendarStateJson
+        ) {
+            this.sendBusinessCalendarState();
+        }
+    };
+
     sendFormList = (forms: FormInfo[]) => {
         this.sendMessage('--form-list', { forms });
     };
@@ -515,12 +550,19 @@ export class UnlayerStore {
             };
 
             this.sendMessage('--config', JSON.parse(JSON.stringify(configData)));
+            // Always: a reloaded tools core starts without it.
+            this.sendBusinessCalendarState();
         } else if (type === '--form-select') {
             this.onFormSelectCB?.(data?.formId);
         } else if (type === '--calc-field-open') {
             this.onCalcFieldOpenCB?.(data?.usedFormIds ?? []);
         } else if (type === '--esign-offset-open') {
             this.openESignOffsetRules(data);
+        } else if (type === '--business-calendar-request') {
+            // It can delete a tenant schedule and replace bindings: only from this editor's iframe.
+            if (e.source === this.iframe?.contentWindow) {
+                this.routeBusinessCalendarRequest(data);
+            }
         } else if (type === '--calc-field-select') {
             if (this.onCalcFieldSelectCB) {
                 this.onCalcFieldSelectCB(data?.fieldKeys ?? []);
@@ -533,6 +575,7 @@ export class UnlayerStore {
                 toolTwins: this.props.toolTwins,
                 eSignRecipients: this.props.eSignRecipients,
                 eSignFieldTypes: this.props.eSignFieldTypes,
+                eSignFieldTypeLabels: E_SIGN_FIELD_TYPE_LABELS,
                 units: this.props.units?.map(unit => ({
                     ...unit,
                     values: {
@@ -581,6 +624,25 @@ export class UnlayerStore {
         });
     };
 
+    private routeBusinessCalendarRequest = (
+        data?: Partial<UnlayerEventBusinessCalendarRequest>,
+    ) => {
+        if (!data?.action || !data.fieldKey) {
+            return;
+        }
+
+        this.onBusinessCalendarRequestCB?.(data as UnlayerEventBusinessCalendarRequest);
+    };
+
+    private sendBusinessCalendarState = () => {
+        if (!this.businessCalendarStateJson) {
+            return;
+        }
+
+        this.sentBusinessCalendarStateJson = this.businessCalendarStateJson;
+        this.sendMessage('--business-calendar-state', JSON.parse(this.businessCalendarStateJson));
+    };
+
     private updateFormFieldSamples = (formId: number, fields: FormFieldInfo[]) => {
         fields.forEach((field, index) => {
             const normalizedFieldId = String(field.id ?? '').replaceAll('-', '');

package/src/unlayer-interface.tsx

@@ -1,3 +1,4 @@
+import type { BusinessCalendarHostProps } from '@servicetitan/dte-shared';
 import {
     UnlayerEditorESignRecipientInfo,
     UnlayerEditorTwin,
@@ -73,7 +74,16 @@ export interface UnlayerEditorCustomTool {
     groupUrl?: string;
 }
 
-export interface CreateUnlayerEditorProps {
+/**
+ * Editor options. The business-day schedule props (`BusinessCalendarHostProps`: `scheduleBindings`,
+ * `schedules`, `holidayCatalog`, `onScheduleBindingsChange`, ...) mean the same as `PdfEditor`'s;
+ * the field key of a binding is the tool's `values.id` (calculated field or e-sign "Date Signed
+ * Offset" field). The schedule UI shows only when `onScheduleBindingsChange` is passed. Changes
+ * to them (and to `holidays` / `fieldCalendars`) reach the editor when the host re-renders
+ * `UnlayerEditor` with new values: new arrays and objects, as for `PdfEditor`, since one changed
+ * in place isn't noticed.
+ */
+export interface CreateUnlayerEditorProps extends BusinessCalendarHostProps {
     tools: UnlayerEditorCustomTool[];
     newSnapshot?: UnlayerEditorTwin;
     toolTwins?: UnlayerEditorTwin[];
@@ -111,14 +121,15 @@ export interface CreateUnlayerEditorProps {
     /**
      * Holidays of the default business-day calendar (`YYYY-MM-DD`, observed days), skipped with
      * Saturday and Sunday by date calculated fields whose toggle is off. Without it the previews
-     * skip weekends only.
+     * skip weekends only. Sent to the editor again whenever it changes.
      */
     holidays?: string[];
     /**
      * Calendars of the date calculated fields bound to a schedule, by field key (the tool's
      * `values.id`), as `POST api/holidays/calendar` resolves them. Fields not listed use the
-     * default calendar (`holidays`). Only the editor previews read it: rendered documents get
-     * their calendars from DTE.
+     * default calendar (`holidays`); while `onScheduleBindingsChange` is passed, so does a field
+     * without a binding in `scheduleBindings`. Only the editor previews read it: rendered
+     * documents get their calendars from DTE. Sent to the editor again whenever it changes.
      */
     fieldCalendars?: Record<string, BusinessCalendar>;
     onFormSelect?: (formId: number) => void;

package/src/unlayer.tsx

@@ -2,7 +2,7 @@ import { emitDisplayCondition } from './display-conditions/displayConditionContr
 import { editorCoreScript, editorCoreStyles, editorCoreTools } from './editor-core';
 import { logUnlayerError } from './log';
 import { toUnlayerMergeTags } from './merge-tags';
-import { constGenericsEditor } from './shared/const';
+import { constGenericsEditor, E_SIGN_FIELD_TYPE_LABELS } from './shared/const';
 import { unlayerSupportedFonts } from './shared/fonts';
 import {
     unlayerCustomEmptyToolState,
@@ -226,10 +226,10 @@ export const createUnlayerEditor = (
 
     const acv = constGenericsEditor.adminConfigProperty;
 
-    const eSignTypeMapping = (eSignFieldTypes ?? []).map(key => ({
-        label: key,
-        value: key.charAt(0).toLowerCase() + key.replace(/ /g, '').slice(1),
-    }));
+    const eSignTypeMapping = (eSignFieldTypes ?? []).map(key => {
+        const value = key.charAt(0).toLowerCase() + key.replace(/ /g, '').slice(1);
+        return { label: E_SIGN_FIELD_TYPE_LABELS[value] ?? key, value };
+    });
 
     const unitsConfig = (units ?? []).reduce(
         (out, unit) => {