@servicetitan/dte-pdf-editor 1.92.1 → 1.92.2

package/src/components/field-sidebar/data-model-field-type-list.tsx

@@ -1,37 +1,111 @@
 import { Flex, SearchField, Text } from '@servicetitan/anvil2';
-import { FC, Fragment, useMemo, useState } from 'react';
-import { type DataModelFieldGroup, type FieldTypeOption } from '../../interface/types';
+import { FC, Fragment, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import {
+    type DataModelFieldGroup,
+    type FieldTypeOption,
+    type FormInfo,
+} from '../../interface/types';
 import { getFieldSampleData } from '../../utils';
 import { FieldType } from './field-type';
+import { FormFieldsPanel, FormsList } from './form-fields-type-list';
 
 interface DataModelFieldTypeListProps {
     dataModelGroups?: DataModelFieldGroup[];
+    /**
+     * Forms offered as a group after the data model groups, already narrowed to the ones that have
+     * fields. Omitted (or empty, with nothing loading) hides the group; `onSelectForm` must be
+     * provided for the group to render.
+     */
+    forms?: FormInfo[];
+    /** The form whose fields are shown in place of the group list; null shows the group list. */
+    selectedForm?: FormInfo | null;
+    /** Draggable options for `selectedForm`. */
+    formFieldOptions?: FieldTypeOption[];
+    /** Placeholder rows to draw while it is still unknown which forms have fields. */
+    loadingFormsCount?: number;
+    isLoadingFormFields?: boolean;
+    onSelectForm?(form: FormInfo | null): void;
     onDragStart(fieldOption: FieldTypeOption): void;
     onDragEnd(): void;
 }
 
+const matchesSearch = (label: string, searchLower: string) =>
+    label.toLowerCase().includes(searchLower);
+
 export const DataModelFieldTypeList: FC<DataModelFieldTypeListProps> = ({
     dataModelGroups = [],
+    formFieldOptions = [],
+    forms,
+    isLoadingFormFields = false,
+    loadingFormsCount = 0,
     onDragEnd,
     onDragStart,
+    onSelectForm,
+    selectedForm = null,
 }) => {
     const [searchText, setSearchText] = useState('');
+    const searchLower = searchText.trim().toLowerCase();
+    const showForms = (!!forms?.length || loadingFormsCount > 0) && !!onSelectForm;
 
     const searchedFieldGroups = useMemo(() => {
-        if (!searchText) {
+        if (!searchLower) {
             return dataModelGroups;
         }
 
-        const searchLower = searchText.toLowerCase();
         return dataModelGroups
             .map(group => ({
                 ...group,
-                fields: group.fields.filter(({ label }) =>
-                    label.toLowerCase().includes(searchLower),
-                ),
+                fields: group.fields.filter(({ label }) => matchesSearch(label, searchLower)),
             }))
             .filter(group => group.fields.length > 0);
-    }, [dataModelGroups, searchText]);
+    }, [dataModelGroups, searchLower]);
+
+    const searchedForms = useMemo(() => {
+        if (!forms?.length) {
+            return [];
+        }
+        if (!searchLower) {
+            return forms;
+        }
+        return forms.filter(form => matchesSearch(form.name, searchLower));
+    }, [forms, searchLower]);
+
+    const searchedFormFieldOptions = useMemo(() => {
+        if (!searchLower) {
+            return formFieldOptions;
+        }
+        return formFieldOptions.filter(option => matchesSearch(option.label, searchLower));
+    }, [formFieldOptions, searchLower]);
+
+    const isFormDetail = showForms && !!selectedForm;
+
+    /*
+     * Both slide panels share one scroller. The Forms group sits below every data model group, so
+     * a form is usually picked with the list scrolled far down — and the fields panel, being much
+     * shorter, would then be scrolled clean past its own content. Start the fields panel at the
+     * top and hand the list back the offset it was left at.
+     *
+     * The offset is tracked as the user scrolls rather than read when the panel switches: by then
+     * the list has already collapsed (see formula-modal.css) and the browser has clamped the
+     * scroller back to 0.
+     */
+    const scrollerRef = useRef<HTMLDivElement>(null);
+    const listScrollTopRef = useRef(0);
+
+    useLayoutEffect(() => {
+        const scroller = scrollerRef.current;
+        if (!scroller) {
+            return;
+        }
+        scroller.scrollTop = isFormDetail ? 0 : listScrollTopRef.current;
+    }, [isFormDetail]);
+
+    const handleScroll = () => {
+        if (!isFormDetail && scrollerRef.current) {
+            listScrollTopRef.current = scrollerRef.current.scrollTop;
+        }
+    };
+
     return (
         <Fragment>
             <SearchField
@@ -40,30 +114,70 @@ export const DataModelFieldTypeList: FC<DataModelFieldTypeListProps> = ({
                 className="dte-field-sidebar-search"
                 onChange={e => setSearchText(e.target.value ?? '')}
             />
-            {searchedFieldGroups.map(group => (
-                <div key={group.groupName} className="dte-field-type-group">
-                    <Flex alignItems="center" gap={1} className="dte-field-type-group-header">
-                        <Text variant="headline" el="h6" size="small">
-                            {group.groupName}
-                        </Text>
-                    </Flex>
-                    {group.fields.map(fieldOption => {
-                        const key = `${fieldOption.type}-${group.groupName}-${fieldOption.path}`;
-                        return (
-                            <FieldType
-                                key={key}
+            <div
+                className="dte-formula-sidebar-slide-outer"
+                ref={scrollerRef}
+                onScroll={handleScroll}
+            >
+                <div
+                    className={`dte-formula-sidebar-slide-track${isFormDetail ? ' --detail' : ''}`}
+                >
+                    <div className="dte-formula-sidebar-slide-panel">
+                        {searchedFieldGroups.map(group => (
+                            <div key={group.groupName} className="dte-field-type-group">
+                                <Flex
+                                    alignItems="center"
+                                    gap={1}
+                                    className="dte-field-type-group-header"
+                                >
+                                    <Text variant="headline" el="h6" size="small">
+                                        {group.groupName}
+                                    </Text>
+                                </Flex>
+                                {group.fields.map(fieldOption => {
+                                    const key = `${fieldOption.type}-${group.groupName}-${fieldOption.path}`;
+                                    return (
+                                        <FieldType
+                                            key={key}
+                                            onDragEnd={onDragEnd}
+                                            onDragStart={() => onDragStart(fieldOption)}
+                                            label={fieldOption.label}
+                                            sampleData={getFieldSampleData(
+                                                fieldOption.sampleData,
+                                                fieldOption.fieldType,
+                                            )}
+                                        />
+                                    );
+                                })}
+                            </div>
+                        ))}
+                        {showForms && (searchedForms.length > 0 || !searchLower) && (
+                            <FormsList
+                                forms={searchedForms}
+                                loadingCount={loadingFormsCount}
+                                onSelectForm={onSelectForm}
+                            />
+                        )}
+                    </div>
+
+                    <div className="dte-formula-sidebar-slide-panel --form-fields">
+                        {isFormDetail && (
+                            <FormFieldsPanel
+                                form={selectedForm}
+                                fieldOptions={searchedFormFieldOptions}
+                                hasHiddenFields={
+                                    formFieldOptions.length > 0 &&
+                                    searchedFormFieldOptions.length === 0
+                                }
+                                isLoading={isLoadingFormFields}
+                                onBack={() => onSelectForm(null)}
                                 onDragEnd={onDragEnd}
-                                onDragStart={() => onDragStart(fieldOption)}
-                                label={fieldOption.label}
-                                sampleData={getFieldSampleData(
-                                    fieldOption.sampleData,
-                                    fieldOption.fieldType,
-                                )}
+                                onDragStart={onDragStart}
                             />
-                        );
-                    })}
+                        )}
+                    </div>
                 </div>
-            ))}
+            </div>
         </Fragment>
     );
 };

package/src/components/field-sidebar/e-sign-field-type-list.tsx

@@ -13,7 +13,6 @@ export const ESignFieldTypeList: FC<ESignFieldTypeListProps> = ({ onDragEnd, onD
         <div className="dte-field-type-items-wrapper">
             {E_SIGN_FIELD_TYPES.map(fieldOption => (
                 <FieldType
-                    icon={fieldOption.icon}
                     key={fieldOption.subType}
                     label={fieldOption.label}
                     onDragEnd={onDragEnd}

package/src/components/field-sidebar/field-sidebar.tsx

@@ -14,15 +14,21 @@ import { DataModelFieldTypeList } from './data-model-field-type-list';
 import { ESignFieldTypeList } from './e-sign-field-type-list';
 import { FieldMenuGroup } from './field-menu-group';
 import { FillableFieldTypeList } from './fillable-field-type-list';
-import { FormFieldsTypeList } from './form-fields-type-list';
 import { GenericFieldTypeList } from './generic-field-type-list';
 
 interface FieldSidebarProps {
     dataModelGroups?: DataModelFieldGroup[];
+    /**
+     * Forms listed as a group inside the Merge Tags tab (alongside the data model groups).
+     * Hidden when empty, when `onSelectForm` is missing, or when `hideFields` names
+     * `FieldTypeEnum.forms`.
+     */
     forms?: FormInfo[];
     formFieldOptions?: FieldTypeOption[];
     hideFields?: FieldTypeEnum[];
     selectedForm?: FormInfo | null;
+    /** Placeholder rows to draw while it is still unknown which forms have fields. */
+    loadingFormsCount?: number;
     isLoadingFormFields?: boolean;
     onDragEnd(): void;
     onDragStart(fieldOption: FieldTypeOption): void;
@@ -35,6 +41,7 @@ export const FieldSidebar: FC<FieldSidebarProps> = ({
     forms,
     hideFields,
     isLoadingFormFields = false,
+    loadingFormsCount = 0,
     onDragEnd,
     onDragStart,
     onSelectForm,
@@ -49,15 +56,14 @@ export const FieldSidebar: FC<FieldSidebarProps> = ({
     };
 
     const filteredMenuGroups = useMemo(() => {
-        let groups = menuGroups;
-        if (hideFields?.length) {
-            groups = groups.filter(menuGroup => !hideFields.includes(menuGroup.key));
+        if (!hideFields?.length) {
+            return menuGroups;
         }
-        if (!forms?.length || !onSelectForm) {
-            groups = groups.filter(menuGroup => menuGroup.key !== FieldTypeEnum.forms);
-        }
-        return groups;
-    }, [forms?.length, hideFields, onSelectForm]);
+        return menuGroups.filter(menuGroup => !hideFields.includes(menuGroup.key));
+    }, [hideFields]);
+
+    // The list itself hides the group when there are no forms or no selection handler.
+    const visibleForms = hideFields?.includes(FieldTypeEnum.forms) ? undefined : forms;
 
     return (
         <Flex className="dte-field-sidebar-container skeleton-item">
@@ -85,17 +91,12 @@ export const FieldSidebar: FC<FieldSidebarProps> = ({
                     {activeFieldType === FieldTypeEnum.dataModel && (
                         <DataModelFieldTypeList
                             dataModelGroups={dataModelGroups}
-                            onDragStart={onDragStart}
-                            onDragEnd={onDragEnd}
-                        />
-                    )}
-                    {activeFieldType === FieldTypeEnum.forms && forms && onSelectForm && (
-                        <FormFieldsTypeList
-                            fieldOptions={formFieldOptions}
-                            forms={forms}
+                            forms={visibleForms}
+                            formFieldOptions={formFieldOptions}
+                            loadingFormsCount={visibleForms ? loadingFormsCount : 0}
                             isLoadingFormFields={isLoadingFormFields}
-                            onDragEnd={onDragEnd}
                             onDragStart={onDragStart}
+                            onDragEnd={onDragEnd}
                             onSelectForm={onSelectForm}
                             selectedForm={selectedForm}
                         />

package/src/components/field-sidebar/field-type.tsx

@@ -1,22 +1,15 @@
-import { Flex, Icon, Svg, Text } from '@servicetitan/anvil2';
+import { Flex, Icon, Text } from '@servicetitan/anvil2';
 import IconDragIndicator from '@servicetitan/anvil2/assets/icons/material/round/drag_indicator.svg';
 import { FC } from 'react';
 
 interface FieldTypeProps {
-    icon?: Svg;
     label: string;
     sampleData?: string | number | null;
     onDragEnd(): void;
     onDragStart(): void;
 }
 
-export const FieldType: FC<FieldTypeProps> = ({
-    icon,
-    label,
-    onDragEnd,
-    onDragStart,
-    sampleData,
-}) => {
+export const FieldType: FC<FieldTypeProps> = ({ label, onDragEnd, onDragStart, sampleData }) => {
     return (
         <div
             draggable
@@ -31,10 +24,7 @@ export const FieldType: FC<FieldTypeProps> = ({
         >
             <Icon svg={IconDragIndicator} size="medium" />
             <Flex direction="column" style={{ overflow: 'hidden' }}>
-                <Flex alignItems="center" gap="2">
-                    {icon && <Icon svg={icon} size="medium" />}
-                    <Text size="small">{label}</Text>
-                </Flex>
+                <Text size="small">{label}</Text>
                 {sampleData && (
                     <Text
                         size="small"

package/src/components/field-sidebar/fillable-field-type-list.tsx

@@ -37,7 +37,6 @@ export const FillableFieldTypeList: FC<FillableFieldTypeListProps> = ({
             {searchedFieldTypes.map(fieldOption => {
                 return (
                     <FieldType
-                        icon={fieldOption.icon}
                         key={fieldOption.subType}
                         label={fieldOption.label}
                         onDragEnd={onDragEnd}

package/src/components/field-sidebar/form-fields-type-list.tsx

@@ -1,4 +1,4 @@
-import { Button, Flex, Text } from '@servicetitan/anvil2';
+import { Button, Flex, Skeleton, Text } from '@servicetitan/anvil2';
 import IconArrowBack from '@servicetitan/anvil2/assets/icons/material/round/keyboard_arrow_left.svg';
 import IconArrowForward from '@servicetitan/anvil2/assets/icons/material/round/keyboard_arrow_right.svg';
 import { FC, Fragment } from 'react';
@@ -6,112 +6,154 @@ import { type FieldTypeOption, type FormInfo } from '../../interface/types';
 import { getFieldSampleData } from '../../utils';
 import { FieldType } from './field-type';
 
-export interface FormFieldsTypeListProps {
+/** Heading of the Forms group inside the Merge Tags tab. */
+export const FORMS_GROUP_NAME = 'Forms';
+
+/** A form's field count is unknown until it answers, so the placeholder settles on a short list. */
+const FIELD_SKELETON_ROWS = 4;
+
+/** Placeholder rows, shaped like the real ones, for a list whose contents are still in flight. */
+const SkeletonRows: FC<{ count: number; className: string }> = ({ className, count }) => {
+    return (
+        <Fragment>
+            {Array.from({ length: count }, (_, index) => (
+                <div key={index} className={`${className} --skeleton`} aria-hidden>
+                    <Skeleton.Text />
+                </div>
+            ))}
+        </Fragment>
+    );
+};
+
+export interface FormsListProps {
     forms: FormInfo[];
-    selectedForm: FormInfo | null;
+    /**
+     * Rows to draw as placeholders instead of the list. Forms are only listed once they are known
+     * to have fields, so until the fields arrive there is nothing truthful to show.
+     */
+    loadingCount?: number;
+    /** Rendered when the (possibly search-filtered) list is empty. */
+    emptyText?: string;
+    onSelectForm(form: FormInfo): void;
+}
+
+/**
+ * Root level of the Forms group: one clickable row per form. Selecting a form hands off to
+ * `FormFieldsPanel`, which lists that form's draggable fields.
+ */
+export const FormsList: FC<FormsListProps> = ({
+    emptyText = 'No forms configured.',
+    forms,
+    loadingCount = 0,
+    onSelectForm,
+}) => {
+    return (
+        <div className="dte-field-type-group">
+            <Flex alignItems="center" gap={1} className="dte-field-type-group-header">
+                <Text variant="headline" el="h6" size="small">
+                    {FORMS_GROUP_NAME}
+                </Text>
+            </Flex>
+            {loadingCount > 0 ? (
+                <SkeletonRows count={loadingCount} className="dte-formula-field-list-item" />
+            ) : forms.length > 0 ? (
+                <ul className="dte-formula-field-list" role="listbox" aria-label={FORMS_GROUP_NAME}>
+                    {forms.map(form => (
+                        <li
+                            key={form.id}
+                            role="option"
+                            className="dte-formula-field-list-item"
+                            onMouseDown={e => {
+                                e.preventDefault();
+                                onSelectForm(form);
+                            }}
+                        >
+                            <Flex justifyContent="space-between" alignItems="center">
+                                {/*
+                                 * Same Text as the data model rows use (via FieldType): a bare
+                                 * span would inherit the host page's font instead of Anvil2's,
+                                 * so the Forms rows would not match the groups above them.
+                                 */}
+                                <Text size="small" className="dte-text-ellipsis" title={form.name}>
+                                    {form.name}
+                                </Text>
+                                <IconArrowForward />
+                            </Flex>
+                        </li>
+                    ))}
+                </ul>
+            ) : (
+                <Text size="small" subdued variant="body">
+                    {emptyText}
+                </Text>
+            )}
+        </div>
+    );
+};
+
+export interface FormFieldsPanelProps {
+    form: FormInfo;
     fieldOptions: FieldTypeOption[];
-    isLoadingFormFields?: boolean;
-    onSelectForm(form: FormInfo | null): void;
+    isLoading?: boolean;
+    /** Rendered when the form has fields but none match the current search. */
+    hasHiddenFields?: boolean;
+    onBack(): void;
     onDragEnd(): void;
     onDragStart(fieldOption: FieldTypeOption): void;
 }
 
-export const FormFieldsTypeList: FC<FormFieldsTypeListProps> = ({
+/**
+ * Detail level of the Forms group: a back button naming the form, then its fields as the same
+ * draggable rows the data model groups use, so a form field drops onto the PDF like any merge tag.
+ */
+export const FormFieldsPanel: FC<FormFieldsPanelProps> = ({
     fieldOptions,
-    forms,
-    isLoadingFormFields = false,
+    form,
+    hasHiddenFields = false,
+    isLoading = false,
+    onBack,
     onDragEnd,
     onDragStart,
-    onSelectForm,
-    selectedForm,
 }) => {
     return (
-        <Flex direction="column" gap={3} flex={1} style={{ minHeight: 0 }}>
-            <div className="dte-formula-sidebar-slide-outer">
-                <div
-                    className={`dte-formula-sidebar-slide-track${selectedForm ? ' --detail' : ''}`}
+        <Fragment>
+            <Button
+                style={{ width: '100%' }}
+                appearance="ghost"
+                size="small"
+                icon={IconArrowBack}
+                title={form.name}
+                onClick={onBack}
+            >
+                <Text
+                    size="medium"
+                    className="dte-text-ellipsis"
+                    style={{ fontWeight: 'bold', width: '100%' }}
                 >
-                    <div className="dte-formula-sidebar-slide-panel">
-                        {forms.length > 0 ? (
-                            <ul
-                                className="dte-formula-field-list"
-                                role="listbox"
-                                aria-label="Forms"
-                            >
-                                {forms.map(form => (
-                                    <li
-                                        key={form.id}
-                                        role="option"
-                                        className="dte-formula-field-list-item"
-                                        onMouseDown={e => {
-                                            e.preventDefault();
-                                            onSelectForm(form);
-                                        }}
-                                    >
-                                        <Flex justifyContent="space-between" alignItems="center">
-                                            <span className="dte-text-ellipsis" title={form.name}>
-                                                {form.name}
-                                            </span>
-                                            <IconArrowForward />
-                                        </Flex>
-                                    </li>
-                                ))}
-                            </ul>
-                        ) : (
-                            <Text size="small" subdued variant="body">
-                                No forms configured.
-                            </Text>
-                        )}
-                    </div>
-
-                    <div className="dte-formula-sidebar-slide-panel --form-fields">
-                        {selectedForm ? (
-                            <Fragment>
-                                <Button
-                                    style={{ width: '100%' }}
-                                    appearance="ghost"
-                                    size="small"
-                                    icon={IconArrowBack}
-                                    title={selectedForm.name}
-                                    onClick={() => onSelectForm(null)}
-                                >
-                                    <Text
-                                        size="medium"
-                                        className="dte-text-ellipsis"
-                                        style={{ fontWeight: 'bold', width: '100%' }}
-                                    >
-                                        {selectedForm.name}
-                                    </Text>
-                                </Button>
-                                <div className="dte-field-type-group">
-                                    {isLoadingFormFields ? (
-                                        <Text size="small" subdued variant="body">
-                                            Loading fields…
-                                        </Text>
-                                    ) : fieldOptions.length === 0 ? (
-                                        <Text size="small" subdued variant="body">
-                                            No fields on this form.
-                                        </Text>
-                                    ) : (
-                                        fieldOptions.map(option => (
-                                            <FieldType
-                                                key={option.path}
-                                                label={option.label}
-                                                sampleData={getFieldSampleData(
-                                                    option.sampleData,
-                                                    option.fieldType,
-                                                )}
-                                                onDragEnd={onDragEnd}
-                                                onDragStart={() => onDragStart(option)}
-                                            />
-                                        ))
-                                    )}
-                                </div>
-                            </Fragment>
-                        ) : null}
-                    </div>
-                </div>
+                    {form.name}
+                </Text>
+            </Button>
+            <div className="dte-field-type-group">
+                {isLoading ? (
+                    <SkeletonRows count={FIELD_SKELETON_ROWS} className="dte-field-type-item" />
+                ) : fieldOptions.length === 0 ? (
+                    <Text size="small" subdued variant="body">
+                        {hasHiddenFields
+                            ? 'No fields match the search.'
+                            : 'No fields on this form.'}
+                    </Text>
+                ) : (
+                    fieldOptions.map(option => (
+                        <FieldType
+                            key={option.path}
+                            label={option.label}
+                            sampleData={getFieldSampleData(option.sampleData, option.fieldType)}
+                            onDragEnd={onDragEnd}
+                            onDragStart={() => onDragStart(option)}
+                        />
+                    ))
+                )}
             </div>
-        </Flex>
+        </Fragment>
     );
 };

package/src/components/field-sidebar/generic-field-type-list.tsx

@@ -16,7 +16,6 @@ export const GenericFieldTypeList: FC<GenericFieldTypeListProps> = ({ onDragEnd,
                 return (
                     <FieldType
                         key={key}
-                        icon={fieldOption.icon}
                         label={fieldOption.label}
                         onDragEnd={onDragEnd}
                         onDragStart={() => onDragStart(fieldOption)}