refactor: improve sheet import UX

apps/client/src/common/api/excel.ts

@@ -1,5 +1,9 @@
 import axios, { AxiosResponse } from 'axios';
-import type { SpreadsheetPreviewResponse, SpreadsheetWorksheetMetadata, SpreadsheetWorksheetOptions } from 'ontime-types';
+import type {
+  SpreadsheetPreviewResponse,
+  SpreadsheetWorksheetMetadata,
+  SpreadsheetWorksheetOptions,
+} from 'ontime-types';
 import { ImportMap } from 'ontime-utils';
 
 import { apiEntryUrl } from './constants';

apps/client/src/common/api/sheets.ts

@@ -76,6 +76,9 @@ export const previewRundown = async (
   return response.data;
 };
 
+/**
+ * Fetches derived metadata for a single worksheet by reading its rows and detecting headers.
+ */
 export const getWorksheetMetadata = async (
   sheetId: string,
   worksheet: string,
@@ -92,12 +95,15 @@ export const getWorksheetMetadata = async (
   return response.data;
 };
 
-export const getWorksheetNames = async (
+/**
+ * Fetches the available worksheets for a Google Sheet. Metadata is loaded lazily per worksheet.
+ */
+export const getWorksheetOptions = async (
   sheetId: string,
   requestOptions?: RequestOptions,
 ): Promise<SpreadsheetWorksheetOptions> => {
   const response: AxiosResponse<SpreadsheetWorksheetOptions> = await axios.post(
-    `${sheetsPath}/${sheetId}/worksheets`,
+    `${sheetsPath}/${sheetId}/worksheet-options`,
     undefined,
     {
       signal: requestOptions?.signal,

apps/client/src/common/components/autocomplete-input/AutocompleteInput.tsx

@@ -1,5 +1,5 @@
 import { Autocomplete as BaseAutocomplete } from '@base-ui/react/autocomplete';
-import type { ReactNode } from 'react';
+import type { ReactNode, Ref } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
 import { cx } from '../../utils/styleUtils';
@@ -15,6 +15,7 @@ export interface AutocompleteInputProps extends Omit<InputProps, 'value' | 'defa
   onValueChange: (value: string) => void;
   emptyLabel?: string;
   trailingElement?: (option: string) => ReactNode;
+  inputRef?: Ref<HTMLInputElement>;
 }
 
 export default function AutocompleteInput({
@@ -23,6 +24,7 @@ export default function AutocompleteInput({
   emptyLabel,
   fluid,
   height = 'medium',
+  inputRef,
   onValueChange,
   options,
   trailingElement,
@@ -30,16 +32,31 @@ export default function AutocompleteInput({
   variant = 'subtle',
   ...inputProps
 }: AutocompleteInputProps) {
-  const inputRef = useRef<HTMLInputElement | null>(null);
+  const internalInputRef = useRef<HTMLInputElement | null>(null);
   const [open, setOpen] = useState(false);
 
+  const handleInputRef = (node: HTMLInputElement | null) => {
+    internalInputRef.current = node;
+
+    if (!inputRef) {
+      return;
+    }
+
+    if (typeof inputRef === 'function') {
+      inputRef(node);
+      return;
+    }
+
+    inputRef.current = node;
+  };
+
   // close the popover when the parent scrollable container scrolls or the window resizes
   useEffect(() => {
     if (!open) {
       return;
     }
 
-    const scrollTarget = getScrollParent(inputRef.current);
+    const scrollTarget = getScrollParent(internalInputRef.current);
     const handleScroll = () => setOpen(false);
 
     scrollTarget.addEventListener('scroll', handleScroll, { passive: true });
@@ -63,7 +80,7 @@ export default function AutocompleteInput({
       onValueChange={onValueChange}
     >
       <BaseAutocomplete.Input
-        ref={inputRef}
+        ref={handleInputRef}
         className={cx([
           inputStyles.input,
           inputStyles[variant],

apps/client/src/common/components/info/Info.module.scss

@@ -30,7 +30,7 @@
 
 .title {
   color: $ui-white;
-  font-size: 1.125rem;
+  font-size: 1rem;
   font-weight: 600;
 }
 

apps/client/src/common/components/modal/Modal.module.scss

@@ -40,8 +40,6 @@
 }
 
 .title {
-  font-size: 1rem;
-  font-weight: 600;
   padding-block: 1rem;
 
   display: flex;
@@ -49,6 +47,11 @@
   justify-content: space-between;
 }
 
+.titleText {
+  font-size: 1rem;
+  font-weight: 600;
+}
+
 .body {
   display: flex;
   flex-direction: column;

apps/client/src/common/components/modal/Modal.tsx

@@ -38,9 +38,9 @@ export default function Modal({
     >
       <BaseDialog.Portal>
         {showBackdrop && <BaseDialog.Backdrop className={style.backdrop} />}
-        <BaseDialog.Popup className={cx([style.modal, size === 'wide' && style.wide])}>
+        <BaseDialog.Popup aria-label={title} className={cx([style.modal, size === 'wide' && style.wide])}>
           <div className={style.title}>
-            {title}
+            {title ? <BaseDialog.Title className={style.titleText}>{title}</BaseDialog.Title> : <div />}
             {showCloseButton && (
               <IconButton variant='subtle-white' onClick={onClose}>
                 <IoClose />

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/GSheetSetup.tsx

@@ -1,7 +1,8 @@
+import type { SpreadsheetWorksheetOptions } from 'ontime-types';
 import { ChangeEvent, useEffect, useState } from 'react';
 import { IoCheckmark, IoShieldCheckmarkOutline } from 'react-icons/io5';
 
-import { getWorksheetNames } from '../../../../../common/api/sheets';
+import { getWorksheetOptions } from '../../../../../common/api/sheets';
 import { maybeAxiosError } from '../../../../../common/api/utils';
 import Button from '../../../../../common/components/buttons/Button';
 import CopyTag from '../../../../../common/components/copy-tag/CopyTag';
@@ -13,10 +14,11 @@ import { useSheetStore } from './useSheetStore';
 
 interface GSheetSetupProps {
   onCancel: () => void;
+  onWorksheetOptionsLoaded?: (options: SpreadsheetWorksheetOptions) => void;
 }
 
 export default function GSheetSetup(props: GSheetSetupProps) {
-  const { onCancel } = props;
+  const { onCancel, onWorksheetOptionsLoaded } = props;
 
   const { revoke, connect, verifyAuth } = useGoogleSheet();
   const [file, setFile] = useState<File | null>(null);
@@ -92,8 +94,9 @@ export default function GSheetSetup(props: GSheetSetupProps) {
       if (result.authenticated !== 'pending') {
         if (result.authenticated == 'authenticated') {
           try {
-            const names = await getWorksheetNames(result.sheetId);
-            setWorksheets(names);
+            const worksheetOptions = await getWorksheetOptions(result.sheetId);
+            setWorksheets(worksheetOptions.worksheets);
+            onWorksheetOptionsLoaded?.(worksheetOptions);
           } catch (error) {
             const message = maybeAxiosError(error);
             patchStepData({ worksheet: { available: false, error: message } });

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/ImportReview.tsx

@@ -1,91 +0,0 @@
-import { CustomFields, Rundown, RundownSummary } from 'ontime-types';
-import { millisToString } from 'ontime-utils';
-import { useState } from 'react';
-
-import Button from '../../../../../common/components/buttons/Button';
-import useRundown from '../../../../../common/hooks-query/useRundown';
-import { formatDuration } from '../../../../../common/utils/time';
-import * as Panel from '../../../panel-utils/PanelUtils';
-import PreviewSpreadsheet from './preview/PreviewRundown';
-import useGoogleSheet from './useGoogleSheet';
-import { useSheetStore } from './useSheetStore';
-
-interface ImportReviewProps {
-  rundown: Rundown;
-  customFields: CustomFields;
-  summary: RundownSummary;
-  onFinished: () => void;
-  onCancel: () => void;
-  onBack: () => void;
-}
-
-export default function ImportReview({
-  rundown,
-  customFields,
-  summary,
-  onFinished,
-  onCancel,
-  onBack,
-}: ImportReviewProps) {
-  const { data: currentRundown } = useRundown();
-  const [loading, setLoading] = useState(false);
-  const { importRundown } = useGoogleSheet();
-  const resetPreview = useSheetStore((state) => state.resetPreview);
-
-  const handleCancel = () => {
-    resetPreview();
-    onCancel();
-  };
-
-  const applyImport = async () => {
-    setLoading(true);
-
-    // we need to import on-top of the currently loaded rundown
-    // so the id needs to match
-    await importRundown(
-      {
-        [currentRundown.id]: { ...rundown, id: currentRundown.id, title: currentRundown.title },
-      },
-      customFields,
-    );
-    setLoading(false);
-    onFinished();
-  };
-
-  return (
-    <Panel.Section>
-      <Panel.Title>
-        Review Rundown
-        <Panel.InlineElements>
-          <Button onClick={handleCancel} variant='ghosted' disabled={loading}>
-            Cancel
-          </Button>
-          <Button onClick={onBack} variant='subtle' disabled={loading}>
-            Back
-          </Button>
-          <Button onClick={applyImport} variant='primary' loading={loading}>
-            Apply
-          </Button>
-        </Panel.InlineElements>
-      </Panel.Title>
-      <Panel.ListGroup>
-        <Panel.ListItem>
-          <b>Title</b> {rundown.title}
-        </Panel.ListItem>
-        <Panel.ListItem>
-          <b>Number of entries</b> {rundown.flatOrder.length}
-        </Panel.ListItem>
-        <Panel.ListItem>
-          <b>Start time</b> {millisToString(summary.start)}
-        </Panel.ListItem>
-        <Panel.ListItem>
-          <b>End time</b> {millisToString(summary.end)}
-        </Panel.ListItem>
-        <Panel.ListItem>
-          <b>Total duration</b> {formatDuration(summary.duration)}
-        </Panel.ListItem>
-      </Panel.ListGroup>
-      <PreviewSpreadsheet rundown={rundown} customFields={customFields} />
-    </Panel.Section>
-  );
-}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/SourcesPanel.module.scss

@@ -7,7 +7,7 @@
   justify-content: center;
   background-color: $gray-1350;
   border: 1px solid $white-10;
-  border-radius: 3px;
+  border-radius: $component-border-radius-md;
 }
 
 .uploadSection {
@@ -29,7 +29,8 @@
   }
 }
 
-.singleActionCell {
-  width: 50px;
-  text-align: center;
+@media (max-width: $medium-screen) {
+  .uploadSection {
+    flex-direction: column;
+  }
 }

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/SourcesPanel.tsx

@@ -1,21 +1,29 @@
-import { ImportMap, getErrorMessage } from 'ontime-utils';
-import { ChangeEvent, useRef, useState } from 'react';
+import type { SpreadsheetPreviewResponse, SpreadsheetWorksheetMetadata } from 'ontime-types';
+import { getErrorMessage, ImportMap } from 'ontime-utils';
+import { ChangeEvent, useCallback, useRef, useState } from 'react';
 import { IoCloudOutline, IoDownloadOutline } from 'react-icons/io5';
 
 import {
-  importRundownPreview as importRundownPreviewExcel,
+  getWorksheetMetadata as getExcelWorksheetMetadata,
+  importRundownPreview as importExcelPreview,
   upload as uploadExcel,
 } from '../../../../../common/api/excel';
-import { getWorksheetNames } from '../../../../../common/api/sheets';
+import {
+  getWorksheetMetadata as getGoogleWorksheetMetadata,
+  getWorksheetOptions,
+  previewRundown as previewGoogleSheet,
+  uploadRundown,
+} from '../../../../../common/api/sheets';
 import { maybeAxiosError } from '../../../../../common/api/utils';
 import Button from '../../../../../common/components/buttons/Button';
 import * as Editor from '../../../../../common/components/editor-utils/EditorUtils';
+import Modal from '../../../../../common/components/modal/Modal';
+import useRundown from '../../../../../common/hooks-query/useRundown';
 import { validateExcelImport } from '../../../../../common/utils/uploadUtils';
 import * as Panel from '../../../panel-utils/PanelUtils';
 import GSheetInfo from './GSheetInfo';
 import GSheetSetup from './GSheetSetup';
-import ImportMapForm from './import-map/ImportMapForm';
-import ImportReview from './ImportReview';
+import SheetImportEditor from './sheet-import/SheetImportEditor';
 import useGoogleSheet from './useGoogleSheet';
 import { useSheetStore } from './useSheetStore';
 
@@ -25,21 +33,17 @@ export default function SourcesPanel() {
   const [importFlow, setImportFlow] = useState<'none' | 'excel' | 'gsheet' | 'finished'>('none');
   const [error, setError] = useState('');
   const [hasFile, setHasFile] = useState<'none' | 'loading' | 'done'>('none');
+  const [initialWorksheetMetadata, setInitialWorksheetMetadata] = useState<SpreadsheetWorksheetMetadata | null>(null);
 
-  const { exportRundown, importRundownPreview, verifyAuth } = useGoogleSheet();
+  const { data: currentRundown } = useRundown();
+  const { importRundown, verifyAuth } = useGoogleSheet();
 
   const setWorksheets = useSheetStore((state) => state.setWorksheets);
+  const worksheetNames = useSheetStore((state) => state.worksheetNames);
   const authenticationStatus = useSheetStore((state) => state.authenticationStatus);
   const setAuthenticationStatus = useSheetStore((state) => state.setAuthenticationStatus);
-  const rundown = useSheetStore((state) => state.rundown);
-  const setRundown = useSheetStore((state) => state.setRundown);
-  const customFields = useSheetStore((state) => state.customFields);
-  const setCustomFields = useSheetStore((state) => state.setCustomFields);
-  const summary = useSheetStore((state) => state.summary);
-  const setSummary = useSheetStore((state) => state.setSummary);
   const setSheetId = useSheetStore((state) => state.setSheetId);
   const sheetId = useSheetStore((state) => state.sheetId);
-  const resetPreview = useSheetStore((state) => state.resetPreview);
 
   const fileInputRef = useRef<HTMLInputElement>(null);
 
@@ -53,15 +57,18 @@ export default function SourcesPanel() {
     }
     try {
       setHasFile('loading');
+      setError('');
       validateExcelImport(fileToUpload);
-      const names = await uploadExcel(fileToUpload);
-      setWorksheets(names);
+      const worksheetOptions = await uploadExcel(fileToUpload);
+      setWorksheets(worksheetOptions.worksheets);
+      setInitialWorksheetMetadata(worksheetOptions.metadata);
       setImportFlow('excel');
       setHasFile('done');
     } catch (error) {
       const errorMessage = getErrorMessage(error);
       setError(`Error uploading file: ${errorMessage}`);
       setWorksheets(null);
+      setInitialWorksheetMetadata(null);
       setHasFile('none');
     }
   };
@@ -73,27 +80,29 @@ export default function SourcesPanel() {
   const resetFlow = () => {
     // we purposely omit clearing the authentication status
     setImportFlow('none');
-    setRundown(null);
     setHasFile('none');
     setWorksheets(null);
-    setCustomFields(null);
-    setSummary(null);
     setError('');
     setSheetId(null);
+    setInitialWorksheetMetadata(null);
   };
 
   const openGSheetFlow = async () => {
+    setError('');
+    setInitialWorksheetMetadata(null);
     const result = await verifyAuth();
     if (result) {
       setAuthenticationStatus(result.authenticated);
       setSheetId(result.sheetId);
       if (result.authenticated === 'authenticated' && result.sheetId) {
         try {
-          const names = await getWorksheetNames(result.sheetId);
-          setWorksheets(names);
+          const worksheetOptions = await getWorksheetOptions(result.sheetId);
+          setWorksheets(worksheetOptions.worksheets);
+          setInitialWorksheetMetadata(worksheetOptions.metadata);
         } catch (error) {
           const message = maybeAxiosError(error);
           setError(`Error getting worksheets: ${message}`);
+          setInitialWorksheetMetadata(null);
         }
       }
     }
@@ -104,57 +113,65 @@ export default function SourcesPanel() {
     resetFlow();
   };
 
-  const handleSubmitImportPreview = async (importMap: ImportMap) => {
-    setError(''); // to clear previous error
-    if (importFlow === 'excel') {
-      try {
-        const previewData = await importRundownPreviewExcel(importMap);
-        setRundown(previewData.rundown);
-        setCustomFields(previewData.customFields);
-        setSummary(previewData.summary);
-      } catch (error) {
-        setError(maybeAxiosError(error));
-      }
-    }
-
-    if (importFlow === 'gsheet') {
-      if (!sheetId) return;
-      await importRundownPreview(sheetId, importMap);
-    }
-  };
-
-  const cancelImportMap = async () => {
+  const cancelImportFlow = () => {
     resetFlow();
-    if (authenticationStatus === 'authenticated') {
-      const result = await verifyAuth();
-      if (result) {
-        setAuthenticationStatus(result.authenticated);
-      }
-    }
   };
 
   const handleFinished = () => {
     setImportFlow('finished');
-    setRundown(null);
     setHasFile('none');
     setWorksheets(null);
-    setCustomFields(null);
     setError('');
   };
 
-  const handleSubmitExport = async (importMap: ImportMap) => {
-    if (!sheetId) return;
-    await exportRundown(sheetId, importMap);
+  const handleApplyImport = async (preview: SpreadsheetPreviewResponse) => {
+    if (!currentRundown) {
+      throw new Error('No current rundown loaded');
+    }
+
+    await importRundown(
+      {
+        [currentRundown.id]: {
+          ...preview.rundown,
+          id: currentRundown.id,
+          title: currentRundown.title,
+        },
+      },
+      preview.customFields,
+    );
+    handleFinished();
   };
 
+  const loadWorksheetMetadata = useCallback(
+    (worksheet: string) =>
+      importFlow === 'excel'
+        ? getExcelWorksheetMetadata(worksheet)
+        : getGoogleWorksheetMetadata(sheetId as string, worksheet),
+    [importFlow, sheetId],
+  );
+
+  const previewImport = useCallback(
+    (importMap: ImportMap): Promise<SpreadsheetPreviewResponse> =>
+      importFlow === 'excel' ? importExcelPreview(importMap) : previewGoogleSheet(sheetId as string, importMap),
+    [importFlow, sheetId],
+  );
+
+  const exportToGoogleSheet = useCallback(
+    (importMap: ImportMap): Promise<void> => uploadRundown(sheetId as string, importMap),
+    [sheetId],
+  );
+
   const isExcelFlow = importFlow === 'excel';
   const isGSheetFlow = importFlow === 'gsheet';
   const isAuthenticated = authenticationStatus === 'authenticated';
   const showInput = importFlow === 'none';
   const showCompleted = importFlow === 'finished';
-  const showAuth = isGSheetFlow && !isAuthenticated;
-  const showImportMap = (isGSheetFlow && isAuthenticated) || (isExcelFlow && hasFile === 'done');
-  const showReview = rundown !== null && customFields !== null && summary !== null;
+  const showAuth = isGSheetFlow && (!isAuthenticated || !worksheetNames?.length);
+  const showImportWorkspace =
+    (isExcelFlow && hasFile === 'done' && Boolean(worksheetNames?.length)) ||
+    (isGSheetFlow && isAuthenticated && Boolean(sheetId) && Boolean(worksheetNames?.length));
+  const importModalTitle = isExcelFlow ? 'Import spreadsheet' : 'Synchronise with Google Sheet';
+  const sourceKey = isExcelFlow ? 'excel' : sheetId ? `gsheet:${sheetId}` : null;
 
   return (
     <Panel.Section>
@@ -207,26 +224,35 @@ export default function SourcesPanel() {
             </Button>
           </div>
         )}
-        {showAuth && <GSheetSetup onCancel={cancelGSheetFlow} />}
-        {showImportMap && !showReview && (
-          <ImportMapForm
-            hasErrors={Boolean(error)}
-            isSpreadsheet={isExcelFlow}
-            onCancel={cancelImportMap}
-            onSubmitExport={handleSubmitExport}
-            onSubmitImport={handleSubmitImportPreview}
-          />
-        )}
-        {showReview && (
-          <ImportReview
-            rundown={rundown}
-            customFields={customFields}
-            summary={summary}
-            onFinished={handleFinished}
-            onCancel={cancelImportMap}
-            onBack={resetPreview}
+        {showAuth && (
+          <GSheetSetup
+            onCancel={cancelGSheetFlow}
+            onWorksheetOptionsLoaded={(worksheetOptions) => {
+              setWorksheets(worksheetOptions.worksheets);
+              setInitialWorksheetMetadata(worksheetOptions.metadata);
+            }}
           />
         )}
+        <Modal
+          isOpen={showImportWorkspace}
+          title={importModalTitle}
+          showBackdrop
+          showCloseButton
+          size='wide'
+          onClose={cancelImportFlow}
+          bodyElements={
+            <SheetImportEditor
+              sourceKey={sourceKey ?? 'spreadsheet'}
+              worksheetNames={worksheetNames ?? []}
+              initialMetadata={initialWorksheetMetadata}
+              loadMetadata={loadWorksheetMetadata}
+              previewImport={previewImport}
+              onApply={handleApplyImport}
+              onCancel={cancelImportFlow}
+              onExport={isGSheetFlow && sheetId ? exportToGoogleSheet : undefined}
+            />
+          }
+        />
       </Panel.Card>
     </Panel.Section>
   );

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/import-map/ImportMapForm.tsx

@@ -1,250 +0,0 @@
-import { ImportMap, checkRegex } from 'ontime-utils';
-import { useEffect, useState } from 'react';
-import { useFieldArray, useForm } from 'react-hook-form';
-import { IoAdd, IoTrash } from 'react-icons/io5';
-
-import Button from '../../../../../../common/components/buttons/Button';
-import IconButton from '../../../../../../common/components/buttons/IconButton';
-import Info from '../../../../../../common/components/info/Info';
-import Input from '../../../../../../common/components/input/input/Input';
-import Select from '../../../../../../common/components/select/Select';
-import Tooltip from '../../../../../../common/components/tooltip/Tooltip';
-import * as Panel from '../../../../panel-utils/PanelUtils';
-import useGoogleSheet from '../useGoogleSheet';
-import { useSheetStore } from '../useSheetStore';
-import { NamedImportMap, convertToImportMap, getPersistedOptions, persistImportMap } from './importMapUtils';
-
-import style from '../SourcesPanel.module.scss';
-
-interface ImportMapFormProps {
-  hasErrors: boolean;
-  isSpreadsheet: boolean;
-  onCancel: () => void;
-  onSubmitExport: (importMap: ImportMap) => Promise<void>;
-  onSubmitImport: (importMap: ImportMap) => Promise<void>;
-}
-
-export default function ImportMapForm({
-  hasErrors,
-  isSpreadsheet,
-  onCancel,
-  onSubmitExport,
-  onSubmitImport,
-}: ImportMapFormProps) {
-  const namedImportMap = getPersistedOptions();
-  const { revoke } = useGoogleSheet();
-  const {
-    control,
-    handleSubmit,
-    register,
-    setValue,
-    watch,
-    formState: { errors, isValid },
-  } = useForm<NamedImportMap>({
-    mode: 'onChange',
-    defaultValues: namedImportMap,
-    values: namedImportMap,
-  });
-
-  const { fields, append, remove } = useFieldArray({
-    control,
-    name: 'custom',
-  });
-
-  const stepData = useSheetStore((state) => state.stepData);
-  const worksheetNames = useSheetStore((state) => state.worksheetNames);
-
-  const [loading, setLoading] = useState<'' | 'export' | 'import'>('');
-
-  // Set first sheet as default worksheet when 'event schedule' sheet is not there
-  useEffect(() => {
-    if (!worksheetNames || worksheetNames.length === 0) return;
-    if (!worksheetNames.includes(namedImportMap.Worksheet)) {
-      setValue('Worksheet', worksheetNames[0], { shouldValidate: true, shouldDirty: true });
-    }
-  }, [worksheetNames, setValue, namedImportMap.Worksheet]);
-
-  const handleExport = async (values: NamedImportMap) => {
-    setLoading('export');
-    const importMap = convertToImportMap(values);
-
-    await onSubmitExport(importMap);
-    setLoading('');
-  };
-
-  const handleRevoke = async () => {
-    await revoke();
-    onCancel();
-  };
-
-  const handleImportPreview = async (values: NamedImportMap) => {
-    setLoading('import');
-    const importMap = convertToImportMap(values);
-    persistImportMap(values);
-    await onSubmitImport(importMap);
-    setLoading('');
-  };
-
-  const deleteCustomImport = (index: number) => {
-    remove(index);
-  };
-
-  const addCustomImport = () => {
-    append({});
-  };
-
-  const isLoading = Boolean(loading);
-  const canSubmitSpreadsheet = isSpreadsheet && !isLoading;
-  const canSubmitGSheet = !isLoading && !stepData.worksheet.error;
-  const canSubmit = !hasErrors && isValid && (canSubmitSpreadsheet || canSubmitGSheet);
-
-  return (
-    <Panel.Section as='form' id='import-map'>
-      <Panel.Title>
-        Import options
-        <Panel.InlineElements>
-          {!isSpreadsheet && (
-            <Tooltip
-              text='Revoke the google authentication'
-              render={<Button />}
-              onClick={handleRevoke}
-              disabled={isLoading}
-            >
-              Revoke
-            </Tooltip>
-          )}
-          <Button onClick={onCancel} disabled={isLoading}>
-            Cancel
-          </Button>
-          {!isSpreadsheet && (
-            <Button
-              variant='primary'
-              onClick={handleSubmit(handleExport)}
-              disabled={!canSubmitGSheet}
-              loading={loading === 'export'}
-            >
-              Export
-            </Button>
-          )}
-          <Button
-            variant='primary'
-            onClick={handleSubmit(handleImportPreview)}
-            disabled={!canSubmit}
-            loading={loading === 'import'}
-          >
-            Import preview
-          </Button>
-        </Panel.InlineElements>
-      </Panel.Title>
-      <Info>
-        Match your spreadsheet columns to Ontime fields. <br />
-        You can also add Custom Fields by providing a name for Ontime and the spreadsheet column name.
-      </Info>
-      <Panel.Table>
-        <thead>
-          <tr>
-            <th>Ontime field</th>
-            <th>Column name in spreadsheet</th>
-            <th className={style.singleActionCell} />
-          </tr>
-        </thead>
-        <tbody>
-          {Object.entries(namedImportMap).map(([label, importName]) => {
-            if (label === 'custom') {
-              return null;
-            }
-            if (label === 'Worksheet') {
-              return (
-                <tr key={importName as string}>
-                  <td>{label}</td>
-                  <td>
-                    <Select
-                      id={importName as string}
-                      value={watch(label as keyof NamedImportMap) as string}
-                      onValueChange={(value: string | null) => {
-                        if (value === null) return;
-                        setValue(label as keyof NamedImportMap, value, { shouldDirty: true });
-                      }}
-                      options={worksheetNames?.map((name) => ({ value: name, label: name })) || []}
-                    />
-                  </td>
-                  <td className={style.singleActionCell} />
-                </tr>
-              );
-            }
-            return (
-              <tr key={importName as string}>
-                <td>{label}</td>
-                <td>
-                  <Input
-                    id={importName as string}
-                    fluid
-                    maxLength={25}
-                    defaultValue={importName as string}
-                    placeholder='Use default column name'
-                    {...register(label as keyof NamedImportMap)}
-                  />
-                </td>
-                <td className={style.singleActionCell} />
-              </tr>
-            );
-          })}
-          {fields.map((field, index) => {
-            const ontimeName = field.ontimeName;
-            const importName = field.importName;
-            const maybeOntimeError = errors.custom?.[index]?.ontimeName?.message;
-            const key = `custom.${index}.ontimeName`;
-            return (
-              <tr key={key}>
-                <td>
-                  <Input
-                    maxLength={25}
-                    fluid
-                    defaultValue={ontimeName}
-                    placeholder='Name of the field as shown in Ontime'
-                    {...register(`custom.${index}.ontimeName`, {
-                      validate: (value) => {
-                        if (!checkRegex.isAlphanumericWithSpace(value))
-                          return 'Only alphanumeric characters and space are allowed';
-                        return true;
-                      },
-                    })}
-                  />
-                  {maybeOntimeError && <Panel.Error>{maybeOntimeError}</Panel.Error>}
-                </td>
-                <td>
-                  <Input
-                    maxLength={25}
-                    fluid
-                    defaultValue={importName}
-                    placeholder='Name of the column in the spreadsheet'
-                    {...register(`custom.${index}.importName`)}
-                  />
-                </td>
-                <td className={style.singleActionCell}>
-                  <IconButton
-                    variant='ghosted-destructive'
-                    aria-label='Delete entry'
-                    onClick={() => deleteCustomImport(index)}
-                  >
-                    <IoTrash />
-                  </IconButton>
-                </td>
-              </tr>
-            );
-          })}
-          <tr>
-            <td />
-            <Panel.InlineElements as='td' align='end'>
-              <Button onClick={addCustomImport}>
-                Add custom field <IoAdd />
-              </Button>
-            </Panel.InlineElements>
-            <td />
-          </tr>
-        </tbody>
-      </Panel.Table>
-      <Panel.Error>{stepData.worksheet.error}</Panel.Error>
-    </Panel.Section>
-  );
-}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/import-map/__test__/importMapUtils.test.ts

@@ -1,38 +0,0 @@
-import { ImportCustom } from 'ontime-utils';
-
-import { NamedImportMap, convertToImportMap } from '../importMapUtils';
-
-describe('convertToImportMap', () => {
-  it('converts a namedImportMap to a importMap', () => {
-    const defaultNamedImporMap = {
-      Worksheet: 'event schedule',
-      Start: 'time start',
-      'Link start': 'link start',
-      End: 'time end',
-      Duration: 'duration',
-      Cue: 'cue',
-      Title: 'title',
-      Skip: 'skip',
-      Note: 'notes',
-      Colour: 'colour',
-      'End action': 'end action',
-      'Timer type': 'timer type',
-      'Time warning': 'warning time',
-      'Time danger': 'danger time',
-      custom: [
-        { ontimeName: 'Custom1        ', importName: 'custom1' },
-        { ontimeName: 'Custom2', importName: 'custom2' },
-        { ontimeName: 'Custom3', importName: 'custom3' },
-        { ontimeName: 'EmptyImportName', importName: '' },
-        { ontimeName: '', importName: 'EmptyOntimeName' },
-      ] as ImportCustom[],
-    } as NamedImportMap;
-
-    const importMap = convertToImportMap(defaultNamedImporMap);
-    expect(importMap.custom).toStrictEqual({
-      Custom1: 'custom1',
-      Custom2: 'custom2',
-      Custom3: 'custom3',
-    });
-  });
-});

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/import-map/importMapUtils.ts

@@ -1,92 +0,0 @@
-import { ImportCustom, ImportMap } from 'ontime-utils';
-
-import { makeStageKey } from '../../../../../../common/utils/localStorage';
-
-export type NamedImportMap = typeof namedImportMap;
-
-// Record of label and import name
-const namedImportMap = {
-  Worksheet: 'event schedule',
-  Flag: 'flag',
-  Start: 'time start',
-  'Link start': 'link start',
-  End: 'time end',
-  Duration: 'duration',
-  Cue: 'cue',
-  Title: 'title',
-  'Count to end': 'count to end',
-  Skip: 'skip',
-  Note: 'notes',
-  Colour: 'colour',
-  'End action': 'end action',
-  'Timer type': 'timer type',
-  'Time warning': 'warning time',
-  'Time danger': 'danger time',
-  ID: 'id',
-  custom: [] as ImportCustom[],
-};
-
-function isNamedImportMap(obj: unknown): obj is NamedImportMap {
-  if (typeof obj !== 'object' || obj === null) {
-    return false;
-  }
-
-  const keys = Object.keys(namedImportMap);
-  return keys.every((key) => Object.hasOwn(obj, key));
-}
-
-export function convertToImportMap(namedImportMap: NamedImportMap): ImportMap {
-  const custom = namedImportMap.custom.reduce((accumulator, { ontimeName, importName }) => {
-    if (ontimeName && importName) {
-      accumulator[ontimeName.trim()] = importName.trim();
-    }
-    return accumulator;
-  }, {});
-
-  return {
-    worksheet: namedImportMap.Worksheet,
-    flag: namedImportMap.Flag,
-    timeStart: namedImportMap.Start,
-    linkStart: namedImportMap['Link start'],
-    timeEnd: namedImportMap.End,
-    duration: namedImportMap.Duration,
-    cue: namedImportMap.Cue,
-    title: namedImportMap.Title,
-    countToEnd: namedImportMap['Count to end'],
-    skip: namedImportMap.Skip,
-    note: namedImportMap.Note,
-    colour: namedImportMap.Colour,
-    endAction: namedImportMap['End action'],
-    timerType: namedImportMap['Timer type'],
-    timeWarning: namedImportMap['Time warning'],
-    timeDanger: namedImportMap['Time danger'],
-    custom,
-    id: namedImportMap.ID,
-  };
-}
-
-const importMapKey = makeStageKey('import-map');
-
-export function persistImportMap(options: NamedImportMap) {
-  localStorage.setItem(importMapKey, JSON.stringify(options));
-}
-
-function getPersistImportMap(): unknown {
-  const options = localStorage.getItem(importMapKey);
-  if (!options) {
-    throw new Error('no import options found');
-  }
-  return JSON.parse(options);
-}
-
-export function getPersistedOptions(): NamedImportMap {
-  try {
-    const options = getPersistImportMap();
-    if (!isNamedImportMap(options)) {
-      return namedImportMap;
-    }
-    return options;
-  } catch {
-    return namedImportMap;
-  }
-}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/preview/PreviewRundown.module.scss

@@ -1,28 +0,0 @@
-.center {
-  text-align: center;
-}
-
-.nowrap {
-  white-space: nowrap;
-}
-
-tr .secondaryRow {
-  background-color: $white-7;
-  padding-left: 2em;
-}
-
-.linkStartActive {
-  flex-shrink: 0;
-  color: $active-indicator;
-  transform: rotate(-45deg);
-}
-
-.flex {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-}
-
-.subdued {
-  opacity: $opacity-disabled;
-}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/preview/PreviewRundown.tsx

@@ -1,195 +0,0 @@
-import { CustomFields, Rundown, isOntimeEvent, isOntimeGroup, isOntimeMilestone } from 'ontime-types';
-import { millisToString } from 'ontime-utils';
-import { Fragment } from 'react';
-import { IoLink } from 'react-icons/io5';
-
-import Tag from '../../../../../../common/components/tag/Tag';
-import { getAccessibleColour } from '../../../../../../common/utils/styleUtils';
-import * as Panel from '../../../../panel-utils/PanelUtils';
-
-import style from './PreviewRundown.module.scss';
-
-interface PreviewRundownProps {
-  rundown: Rundown;
-  customFields: CustomFields;
-}
-
-function booleanToText(value?: boolean) {
-  return value ? 'Yes' : undefined;
-}
-
-export default function PreviewRundown({ rundown, customFields }: PreviewRundownProps) {
-  // we only count Ontime Events which are 1 based in client
-  let eventIndex = 0;
-
-  const fieldKeys = Object.keys(customFields);
-  const fieldLabels = fieldKeys.map((key) => customFields[key].label);
-
-  return (
-    <Panel.Table className={style.nowrap}>
-      <thead>
-        <tr>
-          <th>#</th>
-          <th>Type</th>
-          <th>Cue</th>
-          <th>Title</th>
-          <th>Flag</th>
-          <th>Time Start</th>
-          <th>Time End</th>
-          <th>Duration</th>
-          <th>Warning Time</th>
-          <th>Danger Time</th>
-          <th>Count to end</th>
-          <th>Skip</th>
-          <th>Colour</th>
-          <th>Timer Type</th>
-          <th>End Action</th>
-          {fieldLabels.map((label) => (
-            <th key={label}>{label}</th>
-          ))}
-          <th>ID</th>
-        </tr>
-      </thead>
-      <tbody>
-        {rundown.flatOrder.map((entryId) => {
-          const entry = rundown.entries[entryId];
-          if (isOntimeGroup(entry)) {
-            const colour = entry.colour ? getAccessibleColour(entry.colour) : {};
-            return (
-              <tr key={entry.id}>
-                <td /> {/** Index */}
-                <td className={style.center}>
-                  <Tag>{entry.type}</Tag>
-                </td>
-                <td /> {/** CUE */}
-                <td>{entry.title}</td>
-                <td /> {/** Flag */}
-                <td /> {/** Time Start */}
-                <td /> {/** Time End */}
-                <td /> {/** Duration */}
-                <td /> {/** Warning Time */}
-                <td /> {/** Danger Time */}
-                <td /> {/** Count to end */}
-                <td /> {/** Skip */}
-                <td style={{ ...colour }}>{entry.colour}</td>
-                <td /> {/** Timer Type */}
-                <td /> {/** End Action */}
-                {fieldKeys.map((field) => {
-                  let value = '';
-                  if (field in entry.custom) {
-                    value = entry.custom[field];
-                  }
-                  return <td key={field}>{value}</td>;
-                })}
-                <td className={style.center}>
-                  <Tag>{entry.id}</Tag>
-                </td>
-              </tr>
-            );
-          }
-          if (isOntimeMilestone(entry)) {
-            const colour = entry.colour ? getAccessibleColour(entry.colour) : {};
-            return (
-              <Fragment key={entry.id}>
-                <tr>
-                  <td /> {/** Index */}
-                  <td className={style.center}>
-                    <Tag>{entry.type}</Tag>
-                  </td>
-                  <td className={style.nowrap}>{entry.cue}</td>
-                  <td>{entry.title}</td>
-                  <td /> {/** Flag */}
-                  <td /> {/** Time Start */}
-                  <td /> {/** Time End */}
-                  <td /> {/** Duration */}
-                  <td /> {/** Warning Time */}
-                  <td /> {/** Danger Time */}
-                  <td /> {/** Count to end */}
-                  <td /> {/** Skip */}
-                  <td style={{ ...colour }}>{entry.colour}</td>
-                  <td /> {/** Timer Type */}
-                  <td /> {/** End Action */}
-                  {fieldKeys.map((field) => {
-                    let value = '';
-                    if (field in entry.custom) {
-                      value = entry.custom[field];
-                    }
-                    return <td key={field}>{value}</td>;
-                  })}
-                  <td className={style.center}>
-                    <Tag>{entry.id}</Tag>
-                  </td>
-                </tr>
-                {entry.note && (
-                  <tr>
-                    <td colSpan={99} className={style.secondaryRow}>
-                      Note: {entry.note}
-                    </td>
-                  </tr>
-                )}
-              </Fragment>
-            );
-          }
-          if (!isOntimeEvent(entry)) {
-            return null;
-          }
-          eventIndex += 1;
-          const colour = entry.colour ? getAccessibleColour(entry.colour) : {};
-          const countToEnd = booleanToText(entry.countToEnd);
-          const skip = booleanToText(entry.skip);
-          const flag = booleanToText(entry.flag);
-
-          return (
-            <Fragment key={entry.id}>
-              <tr>
-                <td className={style.center}>
-                  <Tag>{eventIndex}</Tag>
-                </td>
-                <td className={style.center}>
-                  <Tag>{entry.type}</Tag>
-                </td>
-                <td className={style.nowrap}>{entry.cue}</td>
-                <td>{entry.title}</td>
-                <td className={style.center}>{flag && <Tag>{flag}</Tag>}</td>
-                <td className={style.flex}>
-                  <span className={entry.linkStart ? style.subdued : undefined}>{millisToString(entry.timeStart)}</span>
-                  {entry.linkStart && <IoLink className={style.linkStartActive} />}
-                </td>
-                <td>{millisToString(entry.timeEnd)}</td>
-                <td>{millisToString(entry.duration)}</td>
-                <td>{millisToString(entry.timeWarning)}</td>
-                <td>{millisToString(entry.timeDanger)}</td>
-                <td className={style.center}>{countToEnd && <Tag>{countToEnd}</Tag>}</td>
-                <td>{skip && <Tag>{skip}</Tag>}</td>
-                <td style={{ ...colour }}>{entry.colour}</td>
-                <td className={style.center}>
-                  <Tag>{entry.timerType}</Tag>
-                </td>
-                <td className={style.center}>
-                  <Tag>{entry.endAction}</Tag>
-                </td>
-                {fieldKeys.map((field) => {
-                  let value = '';
-                  if (field in entry.custom) {
-                    value = entry.custom[field];
-                  }
-                  return <td key={field}>{value}</td>;
-                })}
-                <td className={style.center}>
-                  <Tag>{entry.id}</Tag>
-                </td>
-              </tr>
-              {entry.note && (
-                <tr>
-                  <td colSpan={99} className={style.secondaryRow}>
-                    Note: {entry.note}
-                  </td>
-                </tr>
-              )}
-            </Fragment>
-          );
-        })}
-      </tbody>
-    </Panel.Table>
-  );
-}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/MappingFieldRow.tsx

@@ -0,0 +1,63 @@
+import type { ReactNode } from 'react';
+import { IoCheckmark } from 'react-icons/io5';
+
+import AutocompleteInput from '../../../../../../common/components/autocomplete-input/AutocompleteInput';
+import { cx } from '../../../../../../common/utils/styleUtils';
+import type { MappingWarning } from './importMapUtils';
+
+import style from './SheetImportEditor.module.scss';
+
+export function getWarningText(warning: MappingWarning): string {
+  switch (warning.kind) {
+    case 'duplicate':
+      return 'Column mapped more than once';
+    case 'missing':
+      return 'Column not in current headers, check preview';
+    case 'invalid-name':
+      return 'Column cannot be converted into an Ontime field name';
+    case 'name-collision':
+      return 'Column name resolves to a duplicate column';
+    default:
+      return '';
+  }
+}
+
+interface MappingFieldRowProps {
+  header: ReactNode;
+  value: string;
+  onValueChange: (value: string) => void;
+  warning?: MappingWarning;
+  options: string[];
+  assigned: Set<string>;
+  disabled?: boolean;
+}
+
+export default function MappingFieldRow({
+  header,
+  value,
+  onValueChange,
+  warning,
+  options,
+  assigned,
+  disabled = false,
+}: MappingFieldRowProps) {
+  const warningText = warning ? getWarningText(warning) : undefined;
+
+  return (
+    <div className={style.mappingField}>
+      {header}
+      {warningText && <span className={style.mappingFieldWarning}>{warningText}</span>}
+      <AutocompleteInput
+        className={cx([style.columnInput, warning && style.columnInputWarn])}
+        maxLength={50}
+        options={options}
+        trailingElement={(option) => (assigned.has(option) ? <IoCheckmark /> : null)}
+        placeholder='Spreadsheet column'
+        disabled={disabled}
+        title={warningText}
+        value={value}
+        onValueChange={onValueChange}
+      />
+    </div>
+  );
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/SheetImportEditor.module.scss

@@ -0,0 +1,162 @@
+.editor {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  width: 100%;
+  max-width: none;
+  height: 100%;
+  min-height: 0;
+}
+
+.editorToolbar {
+  display: flex;
+  gap: 0.75rem 1rem;
+  align-items: center;
+  justify-content: space-between;
+  padding-inline: 0.5rem 0;
+}
+
+.editorFooter {
+  padding: 0.75rem 0 0.5rem;
+}
+
+.worksheetControl {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.worksheetLabel {
+  color: $gray-300;
+  font-size: 0.9rem;
+  font-weight: 600;
+  white-space: nowrap;
+}
+
+.addColumnTrigger {
+  justify-content: center;
+  white-space: nowrap;
+}
+
+.editorBody {
+  flex: 1;
+  min-height: 0;
+  display: grid;
+  grid-template-columns: minmax(18rem, 22rem) minmax(0, 1fr);
+  gap: 1rem;
+}
+
+.mappingPane,
+.previewPane {
+  min-height: 0;
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  border: 1px solid $white-10;
+  background-color: $gray-1350;
+  border-radius: $component-border-radius-md;
+}
+
+.mappingPaneHeader,
+.previewPaneHeader {
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  min-height: 3.5rem;
+  padding: 0.75rem 1rem;
+  border-bottom: 1px solid $white-10;
+}
+
+.mappingPaneHeader {
+  align-items: flex-start;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+
+.mappingPaneActions {
+  justify-content: flex-end;
+  flex-wrap: wrap;
+  row-gap: 0.5rem;
+  max-width: 100%;
+}
+
+.mappingPaneTitle,
+.previewPaneTitle {
+  color: $ui-white;
+  font-size: 0.95rem;
+  font-weight: 600;
+}
+
+.mappingPaneTitle {
+  align-self: center;
+}
+
+.mappingList {
+  min-height: 0;
+  overflow: auto;
+  padding: 0.75rem 0.75rem 2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.mappingField {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+}
+
+.mappingFieldHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.5rem;
+}
+
+.mappingFieldTitle {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+}
+
+.mappingFieldLabel {
+  color: $ui-white;
+  font-size: 0.9rem;
+  font-weight: 600;
+}
+
+.mappingFieldWarning {
+  color: $orange-400;
+  font-size: 0.8rem;
+  line-height: 1.3;
+}
+
+.tableShell {
+  flex: 1;
+  min-height: 0;
+  overflow: auto;
+}
+
+.columnInput {
+  width: 100%;
+}
+
+.columnInputWarn {
+  border-color: $orange-400;
+  box-shadow: 0 0 0 1px rgba($orange-400, 0.2);
+}
+
+@media (max-width: $medium-screen) {
+  .editorBody {
+    grid-template-columns: 1fr;
+  }
+
+  .editorToolbar {
+    align-items: center;
+  }
+
+  .worksheetControl {
+    justify-content: space-between;
+  }
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/SheetImportEditor.tsx

@@ -0,0 +1,140 @@
+import type { SpreadsheetPreviewResponse, SpreadsheetWorksheetMetadata } from 'ontime-types';
+import type { ImportMap } from 'ontime-utils';
+import { IoArrowUpOutline, IoEye } from 'react-icons/io5';
+
+import Button from '../../../../../../common/components/buttons/Button';
+import Select from '../../../../../../common/components/select/Select';
+import * as Panel from '../../../../panel-utils/PanelUtils';
+import PreviewTable from './preview/PreviewTable';
+import SheetImportMappingPane from './SheetImportMappingPane';
+import { useSheetImportForm } from './useSheetImportForm';
+
+import style from './SheetImportEditor.module.scss';
+
+interface SheetImportEditorProps {
+  sourceKey: string;
+  worksheetNames: string[];
+  initialMetadata: SpreadsheetWorksheetMetadata | null;
+  loadMetadata: (worksheet: string) => Promise<SpreadsheetWorksheetMetadata>;
+  previewImport: (importMap: ImportMap) => Promise<SpreadsheetPreviewResponse>;
+  onApply: (preview: SpreadsheetPreviewResponse) => Promise<void>;
+  onCancel: () => void;
+  onExport?: (importMap: ImportMap) => Promise<void>;
+}
+
+export default function SheetImportEditor({
+  sourceKey,
+  worksheetNames,
+  initialMetadata,
+  loadMetadata,
+  previewImport,
+  onApply,
+  onCancel,
+  onExport,
+}: SheetImportEditorProps) {
+  const {
+    values,
+    setValue,
+    fields,
+    addCustomField,
+    removeCustomField,
+    sampleHeaders,
+    assignedHeaders,
+    warnings,
+    columnLabels,
+    worksheetHeaders,
+    state,
+    toolbarStatus,
+    isLoadingMetadata,
+    isBusy,
+    canPreview,
+    displayError,
+    handlePreviewSubmit,
+    handleExportSubmit,
+    handleApply,
+  } = useSheetImportForm({
+    sourceKey,
+    worksheetNames,
+    initialMetadata,
+    loadMetadata,
+    previewImport,
+    onApply,
+    onExport,
+  });
+
+  return (
+    <Panel.Section as='form' id='spreadsheet-import-workspace' className={style.editor} onSubmit={handlePreviewSubmit}>
+      <Panel.InlineElements align='apart' wrap='wrap' className={style.editorToolbar}>
+        <label className={style.worksheetControl}>
+          <span className={style.worksheetLabel}>Worksheet</span>
+          <Select
+            options={worksheetNames.map((name) => ({ value: name, label: name }))}
+            value={values.worksheet}
+            onValueChange={(nextValue) =>
+              setValue('worksheet', nextValue ?? '', { shouldDirty: true, shouldValidate: true })
+            }
+          />
+        </label>
+        {toolbarStatus && <Panel.Description>{toolbarStatus}</Panel.Description>}
+      </Panel.InlineElements>
+
+      <div className={style.editorBody}>
+        <SheetImportMappingPane
+          values={values}
+          setValue={setValue}
+          warnings={warnings}
+          sampleHeaders={sampleHeaders}
+          assignedHeaders={assignedHeaders}
+          fields={fields}
+          addCustomField={addCustomField}
+          removeCustomField={removeCustomField}
+          isBusy={isBusy}
+        />
+
+        <section className={style.previewPane}>
+          <div className={style.previewPaneHeader}>
+            <span className={style.previewPaneTitle}>Import preview</span>
+          </div>
+          <div className={style.tableShell}>
+            <PreviewTable
+              preview={state.preview}
+              columnLabels={columnLabels}
+              isLoadingMetadata={isLoadingMetadata}
+              worksheetHeaders={worksheetHeaders}
+            />
+          </div>
+        </section>
+      </div>
+
+      {displayError && <Panel.Error>{displayError}</Panel.Error>}
+      <Panel.InlineElements align='end' wrap='wrap' className={style.editorFooter}>
+        <Button onClick={onCancel} disabled={isBusy}>
+          Cancel
+        </Button>
+        {onExport && (
+          <Button onClick={handleExportSubmit} disabled={!canPreview} loading={state.loading === 'export'}>
+            <IoArrowUpOutline />
+            Export
+          </Button>
+        )}
+        <Button
+          variant={state.preview ? undefined : 'primary'}
+          onClick={handlePreviewSubmit}
+          disabled={!canPreview}
+          loading={state.loading === 'preview'}
+        >
+          <IoEye />
+          Preview import
+        </Button>
+        <Button
+          variant='primary'
+          onClick={handleApply}
+          disabled={!state.preview || isBusy}
+          loading={state.loading === 'apply'}
+        >
+          Apply import
+        </Button>
+      </Panel.InlineElements>
+    </Panel.Section>
+  );
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/SheetImportMappingPane.tsx

@@ -0,0 +1,118 @@
+import { useRef } from 'react';
+import { type FieldArrayWithId, type UseFormSetValue } from 'react-hook-form';
+import { IoAdd, IoTrash } from 'react-icons/io5';
+
+import Button from '../../../../../../common/components/buttons/Button';
+import IconButton from '../../../../../../common/components/buttons/IconButton';
+import Checkbox from '../../../../../../common/components/checkbox/Checkbox';
+import * as Panel from '../../../../panel-utils/PanelUtils';
+import {
+  type ImportFormValues,
+  type MappingWarning,
+  builtInFieldDefs,
+  getResolvedCustomFields,
+} from './importMapUtils';
+import MappingFieldRow from './MappingFieldRow';
+
+import style from './SheetImportEditor.module.scss';
+
+interface SheetImportMappingPaneProps {
+  values: ImportFormValues;
+  setValue: UseFormSetValue<ImportFormValues>;
+  warnings: Record<string, MappingWarning | undefined>;
+  sampleHeaders: string[];
+  assignedHeaders: Set<string>;
+  fields: FieldArrayWithId<ImportFormValues, 'custom', 'id'>[];
+  addCustomField: () => void;
+  removeCustomField: (index: number) => void;
+  isBusy: boolean;
+}
+
+export default function SheetImportMappingPane({
+  values,
+  setValue,
+  warnings,
+  sampleHeaders,
+  assignedHeaders,
+  fields,
+  addCustomField,
+  removeCustomField,
+  isBusy,
+}: SheetImportMappingPaneProps) {
+  const listRef = useRef<HTMLDivElement>(null);
+  const resolvedCustomFields = getResolvedCustomFields(values.custom);
+
+  const handleAddCustomField = () => {
+    addCustomField();
+    requestAnimationFrame(() => listRef.current?.scrollTo({ top: listRef.current.scrollHeight, behavior: 'smooth' }));
+  };
+
+  return (
+    <section className={style.mappingPane}>
+      <Panel.InlineElements align='apart' className={style.mappingPaneHeader}>
+        <span className={style.mappingPaneTitle}>Fields</span>
+        <Panel.InlineElements relation='inner' className={style.mappingPaneActions}>
+          <Button className={style.addColumnTrigger} onClick={handleAddCustomField} disabled={isBusy}>
+            <IoAdd />
+            Add
+          </Button>
+        </Panel.InlineElements>
+      </Panel.InlineElements>
+
+      <div ref={listRef} className={style.mappingList}>
+        {builtInFieldDefs.map((def, index) => (
+          <MappingFieldRow
+            key={def.importKey}
+            header={
+              <label className={style.mappingFieldTitle}>
+                <Checkbox
+                  checked={values.builtIn[index]?.enabled !== false}
+                  onCheckedChange={(next) =>
+                    setValue(`builtIn.${index}.enabled`, next === true, { shouldDirty: true, shouldValidate: true })
+                  }
+                />
+                <span className={style.mappingFieldLabel}>{def.label}</span>
+              </label>
+            }
+            value={values.builtIn[index]?.header ?? ''}
+            onValueChange={(nextValue) =>
+              setValue(`builtIn.${index}.header`, nextValue, { shouldDirty: true, shouldValidate: true })
+            }
+            warning={values.builtIn[index]?.enabled !== false ? warnings[`builtIn.${index}.header`] : undefined}
+            options={sampleHeaders}
+            assigned={assignedHeaders}
+            disabled={values.builtIn[index]?.enabled === false}
+          />
+        ))}
+
+        {fields.map((field, index) => (
+          <MappingFieldRow
+            key={field.id}
+            header={
+              <div className={style.mappingFieldHeader}>
+                <span className={style.mappingFieldLabel}>
+                  {resolvedCustomFields[index]?.ontimeName || values.custom[index]?.importName || `Custom ${index + 1}`}
+                </span>
+                <IconButton
+                  variant='ghosted-destructive'
+                  aria-label={`Delete custom column ${resolvedCustomFields[index]?.ontimeName || values.custom[index]?.importName || `Custom ${index + 1}`}`}
+                  onClick={() => removeCustomField(index)}
+                >
+                  <IoTrash />
+                </IconButton>
+              </div>
+            }
+            value={values.custom[index]?.importName ?? ''}
+            onValueChange={(nextValue) => {
+              setValue(`custom.${index}.importName`, nextValue, { shouldDirty: true, shouldValidate: true });
+              setValue(`custom.${index}.ontimeName`, '', { shouldDirty: true, shouldValidate: true });
+            }}
+            warning={warnings[`custom.${index}.importName`]}
+            options={sampleHeaders}
+            assigned={assignedHeaders}
+          />
+        ))}
+      </div>
+    </section>
+  );
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/__tests__/importMapUtils.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  builtInFieldDefs,
+  convertToImportMap,
+  createDefaultFormValues,
+  getImportWarnings,
+  getResolvedCustomFields,
+} from '../importMapUtils';
+
+const cueIndex = builtInFieldDefs.findIndex((field) => field.label === 'Cue');
+const titleIndex = builtInFieldDefs.findIndex((field) => field.label === 'Title');
+
+describe('getImportWarnings()', () => {
+  it('warns when two mappings target the same spreadsheet column', () => {
+    const values = createDefaultFormValues();
+    values.builtIn[titleIndex] = { header: 'title', enabled: true };
+    values.custom = [{ ontimeName: '', importName: 'title' }];
+
+    const warnings = getImportWarnings(values, ['title']);
+
+    expect(warnings[`builtIn.${titleIndex}.header`]).toBeUndefined();
+    expect(warnings['custom.0.importName']).toStrictEqual({ kind: 'duplicate' });
+  });
+
+  it('warns when a mapped column is not present in the worksheet', () => {
+    const values = createDefaultFormValues();
+    values.builtIn[titleIndex] = { header: 'headline', enabled: true };
+
+    const warnings = getImportWarnings(values, ['title', 'cue']);
+
+    expect(warnings[`builtIn.${titleIndex}.header`]).toStrictEqual({ kind: 'missing' });
+  });
+
+  it('matches worksheet headers case-insensitively and ignores disabled or blank mappings', () => {
+    const values = createDefaultFormValues();
+    values.builtIn[cueIndex] = { header: 'title', enabled: false };
+    values.builtIn[titleIndex] = { header: 'TITLE', enabled: true };
+    values.custom = [
+      { ontimeName: '', importName: '' },
+      { ontimeName: '', importName: '   ' },
+    ];
+
+    const warnings = getImportWarnings(values, ['title']);
+
+    expect(warnings[`builtIn.${cueIndex}.header`]).toBeUndefined();
+    expect(warnings[`builtIn.${titleIndex}.header`]).toBeUndefined();
+    expect(warnings['custom.0.importName']).toBeUndefined();
+    expect(warnings['custom.1.importName']).toBeUndefined();
+  });
+
+  it('warns when a custom header cannot be converted into an Ontime field name', () => {
+    const values = createDefaultFormValues();
+    values.custom = [{ ontimeName: '', importName: '***' }];
+
+    const warnings = getImportWarnings(values, ['***']);
+
+    expect(warnings['custom.0.importName']).toStrictEqual({ kind: 'invalid-name' });
+  });
+
+  it('warns when a custom header resolves to an existing Ontime field name', () => {
+    const values = createDefaultFormValues();
+    values.custom = [
+      { ontimeName: '', importName: 'Artist-1' },
+      { ontimeName: '', importName: 'Artist/1' },
+      { ontimeName: '', importName: 'Title!' },
+      { ontimeName: '', importName: 'Presenter-1' },
+    ];
+
+    const warnings = getImportWarnings(values, ['Artist-1', 'Artist/1', 'Title!', 'Presenter-1'], ['Presenter 1']);
+
+    expect(warnings['custom.0.importName']).toBeUndefined();
+    expect(warnings['custom.1.importName']).toStrictEqual({ kind: 'name-collision' });
+    expect(warnings['custom.2.importName']).toStrictEqual({ kind: 'name-collision' });
+    expect(warnings['custom.3.importName']).toStrictEqual({ kind: 'name-collision' });
+  });
+});
+
+describe('getResolvedCustomFields()', () => {
+  it('trims spreadsheet headers and derives the Ontime field name from them', () => {
+    const resolved = getResolvedCustomFields([
+      { ontimeName: '', importName: '  FOH/Monitor  ' },
+      { ontimeName: '', importName: 'Artist-1' },
+    ]);
+
+    expect(resolved).toStrictEqual([
+      { ontimeName: 'FOH Monitor', importName: 'FOH/Monitor' },
+      { ontimeName: 'Artist 1', importName: 'Artist-1' },
+    ]);
+  });
+
+  it('keeps invalid or empty custom headers unresolved', () => {
+    const resolved = getResolvedCustomFields([
+      { ontimeName: '', importName: '' },
+      { ontimeName: '', importName: '***' },
+    ]);
+
+    expect(resolved).toStrictEqual([
+      { ontimeName: '', importName: '' },
+      { ontimeName: '', importName: '***' },
+    ]);
+  });
+});
+
+describe('convertToImportMap()', () => {
+  it('uses resolved custom field names, skips invalid custom rows, and clears disabled built-in fields', () => {
+    const values = createDefaultFormValues();
+    values.builtIn[titleIndex] = { header: 'title', enabled: false };
+    values.custom = [
+      { ontimeName: 'ignored', importName: 'FOH/Monitor' },
+      { ontimeName: 'ignored', importName: '***' },
+    ];
+
+    const importMap = convertToImportMap(values);
+
+    expect(importMap.title).toBe('');
+    expect(importMap.cue).toBe('cue');
+    expect(importMap.custom).toStrictEqual({
+      'FOH Monitor': 'FOH/Monitor',
+    });
+  });
+});

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/__tests__/spreadsheetImportUtils.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest';
+
+import { type ImportFormValues, builtInFieldDefs, createDefaultFormValues } from '../importMapUtils';
+import { deriveHeaderOptionsState } from '../spreadsheetImportUtils';
+
+function makeValues(patch: Partial<ImportFormValues>): ImportFormValues {
+  return {
+    ...createDefaultFormValues(),
+    ...patch,
+  };
+}
+
+function patchBuiltIn(
+  base: ImportFormValues,
+  patches: Record<string, Partial<{ header: string; enabled: boolean }>>,
+): ImportFormValues {
+  return {
+    ...base,
+    builtIn: base.builtIn.map((field, i) => {
+      const patch = patches[builtInFieldDefs[i].label];
+      return patch ? { ...field, ...patch } : field;
+    }),
+  };
+}
+
+describe('deriveHeaderOptionsState()', () => {
+  it('excludes disabled built-in fields from assigned headers', () => {
+    const values = patchBuiltIn(createDefaultFormValues(), {
+      Title: { header: 'title', enabled: true },
+      Cue: { header: 'cue', enabled: false },
+    });
+    const { assignedHeaders } = deriveHeaderOptionsState(values, ['title', 'cue']);
+
+    expect(assignedHeaders.has('title')).toBe(true);
+    expect(assignedHeaders.has('cue')).toBe(false);
+  });
+
+  it('includes custom fields in assigned headers', () => {
+    const values = makeValues({
+      custom: [{ ontimeName: 'MyField', importName: 'custom col' }],
+    });
+    const { assignedHeaders } = deriveHeaderOptionsState(values, ['custom col', 'other']);
+
+    expect(assignedHeaders.has('custom col')).toBe(true);
+    expect(assignedHeaders.has('other')).toBe(false);
+  });
+
+  it('deduplicates and filters empty sample headers', () => {
+    const values = makeValues({});
+    const { sampleHeaders } = deriveHeaderOptionsState(values, ['Title', 'Title', '', '  ', 'Cue']);
+
+    expect(sampleHeaders).toEqual(['title', 'cue']);
+  });
+
+  it('deduplicates headers case-insensitively', () => {
+    const values = makeValues({});
+    const { sampleHeaders } = deriveHeaderOptionsState(values, ['Title', 'TITLE', 'title', 'Artist']);
+
+    expect(sampleHeaders).toEqual(['title', 'artist']);
+  });
+
+  it('matches headers case-insensitively', () => {
+    const values = patchBuiltIn(createDefaultFormValues(), {
+      Title: { header: 'TITLE', enabled: true },
+    });
+    const { assignedHeaders } = deriveHeaderOptionsState(values, ['title', 'Cue']);
+
+    expect(assignedHeaders.has('title')).toBe(true);
+  });
+});

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/importMapUtils.ts

@@ -0,0 +1,222 @@
+import type { ImportMap } from 'ontime-utils';
+
+import { makeStageKey } from '../../../../../../common/utils/localStorage';
+
+export type MappingWarning = {
+  kind: 'duplicate' | 'missing' | 'invalid-name' | 'name-collision';
+};
+
+export type BuiltInFieldDef = {
+  label: string;
+  importKey: keyof Omit<ImportMap, 'worksheet' | 'custom'>;
+  defaultHeader: string;
+};
+
+export const builtInFieldDefs = [
+  { label: 'Flag', importKey: 'flag', defaultHeader: 'flag' },
+  { label: 'Start', importKey: 'timeStart', defaultHeader: 'time start' },
+  { label: 'Link start', importKey: 'linkStart', defaultHeader: 'link start' },
+  { label: 'End', importKey: 'timeEnd', defaultHeader: 'time end' },
+  { label: 'Duration', importKey: 'duration', defaultHeader: 'duration' },
+  { label: 'Cue', importKey: 'cue', defaultHeader: 'cue' },
+  { label: 'Title', importKey: 'title', defaultHeader: 'title' },
+  { label: 'Count to end', importKey: 'countToEnd', defaultHeader: 'count to end' },
+  { label: 'Skip', importKey: 'skip', defaultHeader: 'skip' },
+  { label: 'Note', importKey: 'note', defaultHeader: 'notes' },
+  { label: 'Colour', importKey: 'colour', defaultHeader: 'colour' },
+  { label: 'End action', importKey: 'endAction', defaultHeader: 'end action' },
+  { label: 'Timer type', importKey: 'timerType', defaultHeader: 'timer type' },
+  { label: 'Time warning', importKey: 'timeWarning', defaultHeader: 'warning time' },
+  { label: 'Time danger', importKey: 'timeDanger', defaultHeader: 'danger time' },
+  { label: 'ID', importKey: 'id', defaultHeader: 'id' },
+] as const satisfies readonly BuiltInFieldDef[];
+
+export type ImportFormValues = {
+  worksheet: string;
+  builtIn: Array<{ header: string; enabled: boolean }>;
+  custom: Array<{ ontimeName: string; importName: string }>;
+};
+
+export function createDefaultFormValues(): ImportFormValues {
+  return {
+    worksheet: 'event schedule',
+    builtIn: builtInFieldDefs.map((def) => ({
+      header: def.defaultHeader,
+      enabled: def.defaultHeader.trim().length > 0,
+    })),
+    custom: [],
+  };
+}
+
+function sanitiseOntimeCustomFieldLabel(importName: string): string {
+  // Replace punctuation with spaces, then collapse repeated whitespace into single spaces.
+  const sanitised = importName
+    .replace(/[^a-z0-9 ]+/gi, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return sanitised;
+}
+
+export function getResolvedCustomFields(customFields: ImportFormValues['custom']): ImportFormValues['custom'] {
+  return customFields.map(({ importName }) => {
+    const trimmedImportName = importName.trim();
+
+    if (!trimmedImportName) {
+      return { importName: '', ontimeName: '' };
+    }
+
+    const baseLabel = sanitiseOntimeCustomFieldLabel(trimmedImportName);
+    if (!baseLabel) {
+      return {
+        importName: trimmedImportName,
+        ontimeName: '',
+      };
+    }
+
+    return {
+      importName: trimmedImportName,
+      ontimeName: baseLabel,
+    };
+  });
+}
+
+export function convertToImportMap(values: ImportFormValues): ImportMap {
+  const custom = getResolvedCustomFields(values.custom).reduce<Record<string, string>>(
+    (accumulator, { ontimeName, importName }) => {
+      if (ontimeName && importName) {
+        accumulator[ontimeName] = importName;
+      }
+      return accumulator;
+    },
+    {},
+  );
+
+  const result: Record<string, unknown> = {
+    worksheet: values.worksheet,
+    custom,
+  };
+
+  for (let i = 0; i < builtInFieldDefs.length; i++) {
+    const def = builtInFieldDefs[i];
+    result[def.importKey] = values.builtIn[i].enabled ? values.builtIn[i].header : '';
+  }
+
+  return result as ImportMap;
+}
+
+function getImportMapKey(sourceKey: string) {
+  return makeStageKey(`import-map:${sourceKey}`);
+}
+
+export function persistImportState(sourceKey: string, values: ImportFormValues) {
+  localStorage.setItem(getImportMapKey(sourceKey), JSON.stringify(values));
+}
+
+function isPersistedFormValues(obj: unknown): obj is ImportFormValues {
+  if (typeof obj !== 'object' || obj === null) {
+    return false;
+  }
+
+  const candidate = obj as Record<string, unknown>;
+  return (
+    typeof candidate.worksheet === 'string' &&
+    Array.isArray(candidate.builtIn) &&
+    candidate.builtIn.length === builtInFieldDefs.length &&
+    Array.isArray(candidate.custom)
+  );
+}
+
+export function getPersistedImportState(sourceKey: string): ImportFormValues {
+  const storageKey = getImportMapKey(sourceKey);
+  try {
+    const raw = localStorage.getItem(storageKey);
+    if (!raw) {
+      return createDefaultFormValues();
+    }
+
+    const parsed: unknown = JSON.parse(raw);
+    if (isPersistedFormValues(parsed)) {
+      return parsed;
+    }
+
+    // Invalid schema - delete malformed data
+    localStorage.removeItem(storageKey);
+    return createDefaultFormValues();
+  } catch {
+    // Parse error - delete corrupted data
+    localStorage.removeItem(storageKey);
+    return createDefaultFormValues();
+  }
+}
+
+function normaliseColumn(value: string | undefined): string {
+  return value?.trim().toLowerCase() ?? '';
+}
+
+/**
+ * Validates import mappings and generates warnings for duplicate or missing spreadsheet columns.
+ */
+export function getImportWarnings(
+  values: ImportFormValues,
+  detectedSpreadsheetColumns: string[],
+  existingCustomFieldLabels: string[] = [],
+): Record<string, MappingWarning | undefined> {
+  const normalisedHeaders = new Set(detectedSpreadsheetColumns.map(normaliseColumn).filter(Boolean));
+  const builtInLabels = new Set(builtInFieldDefs.map((def) => def.label.toLowerCase()));
+  const existingLabels = new Set(existingCustomFieldLabels.map((label) => label.trim().toLowerCase()).filter(Boolean));
+  const seenColumns = new Set<string>();
+  const seenDerivedLabels = new Set<string>();
+  const warnings: Record<string, MappingWarning | undefined> = {};
+
+  // 1. check built-in fields
+  for (let i = 0; i < values.builtIn.length; i++) {
+    const field = values.builtIn[i];
+    if (!field.enabled) continue;
+
+    const normalised = normaliseColumn(field.header);
+    if (!normalised) continue;
+
+    const key = `builtIn.${i}.header`;
+
+    if (seenColumns.has(normalised)) {
+      warnings[key] = { kind: 'duplicate' };
+    } else if (normalisedHeaders.size > 0 && !normalisedHeaders.has(normalised)) {
+      warnings[key] = { kind: 'missing' };
+    }
+
+    seenColumns.add(normalised);
+  }
+
+  // 2. check custom fields
+  values.custom.forEach(({ importName }, index) => {
+    const normalised = normaliseColumn(importName);
+    if (!normalised) return;
+
+    const key = `custom.${index}.importName`;
+    const sanitisedLabel = sanitiseOntimeCustomFieldLabel(importName);
+
+    if (seenColumns.has(normalised)) {
+      warnings[key] = { kind: 'duplicate' };
+    } else if (!sanitisedLabel) {
+      warnings[key] = { kind: 'invalid-name' };
+    } else if (normalisedHeaders.size > 0 && !normalisedHeaders.has(normalised)) {
+      warnings[key] = { kind: 'missing' };
+    } else {
+      const normalisedDerivedLabel = sanitisedLabel.toLowerCase();
+      if (
+        builtInLabels.has(normalisedDerivedLabel) ||
+        existingLabels.has(normalisedDerivedLabel) ||
+        seenDerivedLabels.has(normalisedDerivedLabel)
+      ) {
+        warnings[key] = { kind: 'name-collision' };
+      }
+    }
+
+    seenColumns.add(normalised);
+    if (sanitisedLabel) {
+      seenDerivedLabels.add(sanitisedLabel.toLowerCase());
+    }
+  });
+
+  return warnings;
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/preview/PreviewTable.module.scss

@@ -0,0 +1,64 @@
+.emptyState {
+  height: 100%;
+  min-height: 16rem;
+  display: grid;
+  place-content: center;
+  gap: 0.35rem;
+  padding: 1.5rem;
+  text-align: center;
+}
+
+.emptyTitle {
+  color: $ui-white;
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.emptyBody {
+  color: $gray-400;
+  font-size: 0.95rem;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: calc(1rem - 2px);
+  text-align: left;
+  table-layout: auto;
+
+  thead {
+    position: sticky;
+    top: 0;
+    z-index: $zindex-floating;
+    background-color: $gray-1350;
+  }
+
+  th {
+    font-weight: 400;
+    color: $gray-400;
+    text-transform: capitalize;
+    vertical-align: top;
+    white-space: normal;
+  }
+
+  th,
+  td {
+    padding: 0.5rem;
+    min-width: 8rem;
+    vertical-align: top;
+  }
+
+  tr:nth-child(even) {
+    background-color: $white-1;
+  }
+}
+
+.rowNumber {
+  width: 4.5rem;
+  min-width: 4.5rem;
+}
+
+.rowType {
+  width: 7rem;
+  min-width: 7rem;
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/preview/PreviewTable.tsx

@@ -0,0 +1,78 @@
+import type { CustomField, CustomFieldKey } from 'ontime-types';
+import { isOntimeEvent, isOntimeGroup, isOntimeMilestone } from 'ontime-types';
+import { useMemo } from 'react';
+
+import { type PreviewState, getCellValue } from './previewTableUtils';
+
+import style from './PreviewTable.module.scss';
+
+interface PreviewTableProps {
+  preview: PreviewState | null;
+  columnLabels: string[];
+  isLoadingMetadata: boolean;
+  worksheetHeaders: string[];
+}
+
+export default function PreviewTable({
+  preview,
+  columnLabels,
+  isLoadingMetadata,
+  worksheetHeaders,
+}: PreviewTableProps) {
+  const customFieldKeyByLabel = useMemo(() => {
+    if (!preview) return new Map<CustomField['label'], CustomFieldKey>();
+    return new Map(Object.entries(preview.customFields).map(([fieldId, field]) => [field.label, fieldId]));
+  }, [preview]);
+
+  if (!preview) {
+    let emptyContent = 'Select the fields you want to import, then click Preview import.';
+
+    if (isLoadingMetadata) {
+      emptyContent = 'Loading worksheet metadata...';
+    } else if (worksheetHeaders.length === 0) {
+      emptyContent =
+        'No column headers detected in this worksheet. Try a different worksheet or ensure the first row contains column headers.';
+    }
+
+    return (
+      <div className={style.emptyState}>
+        <div className={style.emptyTitle}>Preview not generated</div>
+        <div className={style.emptyBody}>{emptyContent}</div>
+      </div>
+    );
+  }
+
+  let eventIndex = 0;
+
+  return (
+    <table className={style.table}>
+      <thead>
+        <tr>
+          <th className={style.rowNumber}>#</th>
+          <th className={style.rowType}>Type</th>
+          {columnLabels.map((label, index) => (
+            <th key={`${label}-${index}`}>{label}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {preview.rundown.flatOrder.map((entryId) => {
+          const entry = preview.rundown.entries[entryId];
+          const isEvent = isOntimeEvent(entry);
+          if (isEvent) eventIndex++;
+          const hasType = isEvent || isOntimeGroup(entry) || isOntimeMilestone(entry);
+
+          return (
+            <tr key={entryId}>
+              <td className={style.rowNumber}>{isEvent ? eventIndex : ''}</td>
+              <td className={style.rowType}>{hasType ? entry.type : ''}</td>
+              {columnLabels.map((label, colIndex) => (
+                <td key={`${entryId}-${colIndex}`}>{getCellValue(label, entry, customFieldKeyByLabel)}</td>
+              ))}
+            </tr>
+          );
+        })}
+      </tbody>
+    </table>
+  );
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/preview/previewTableUtils.ts

@@ -0,0 +1,74 @@
+import type { CustomField, CustomFieldKey, CustomFields, OntimeEntry, Rundown, RundownSummary } from 'ontime-types';
+import { isOntimeEvent, isOntimeMilestone } from 'ontime-types';
+import type { ImportMap } from 'ontime-utils';
+import { millisToString } from 'ontime-utils';
+
+import { builtInFieldDefs } from '../importMapUtils';
+
+export type PreviewState = {
+  rundown: Rundown;
+  customFields: CustomFields;
+  summary: RundownSummary;
+};
+
+type BuiltInImportKey = keyof Omit<ImportMap, 'worksheet' | 'custom'>;
+
+const importKeyByLabel = new Map<string, BuiltInImportKey>(builtInFieldDefs.map((def) => [def.label, def.importKey]));
+
+function booleanToText(value?: boolean): string {
+  return value ? 'Yes' : '';
+}
+
+function getBuiltInValue(label: string, entry: OntimeEntry): string {
+  const importKey = importKeyByLabel.get(label);
+  if (!importKey) return '';
+
+  switch (importKey) {
+    case 'flag':
+      return isOntimeEvent(entry) ? booleanToText(entry.flag) : '';
+    case 'timeStart':
+      return 'timeStart' in entry ? millisToString(entry.timeStart) : '';
+    case 'linkStart':
+      return isOntimeEvent(entry) ? booleanToText(entry.linkStart) : '';
+    case 'timeEnd':
+      return isOntimeEvent(entry) ? millisToString(entry.timeEnd) : '';
+    case 'duration':
+      return isOntimeEvent(entry) ? millisToString(entry.duration) : '';
+    case 'cue':
+      return isOntimeEvent(entry) || isOntimeMilestone(entry) ? entry.cue : '';
+    case 'title':
+      return 'title' in entry ? entry.title : '';
+    case 'countToEnd':
+      return isOntimeEvent(entry) ? booleanToText(entry.countToEnd) : '';
+    case 'skip':
+      return isOntimeEvent(entry) ? booleanToText(entry.skip) : '';
+    case 'note':
+      return 'note' in entry ? (entry.note ?? '') : '';
+    case 'colour':
+      return 'colour' in entry ? (entry.colour ?? '') : '';
+    case 'endAction':
+      return isOntimeEvent(entry) ? entry.endAction : '';
+    case 'timerType':
+      return isOntimeEvent(entry) ? entry.timerType : '';
+    case 'timeWarning':
+      return isOntimeEvent(entry) ? millisToString(entry.timeWarning) : '';
+    case 'timeDanger':
+      return isOntimeEvent(entry) ? millisToString(entry.timeDanger) : '';
+    case 'id':
+      return entry.id;
+    default:
+      return '';
+  }
+}
+
+export function getCellValue(
+  label: string,
+  entry: OntimeEntry,
+  customFieldKeyByLabel: Map<CustomField['label'], CustomFieldKey>,
+): string {
+  const customFieldId = customFieldKeyByLabel.get(label);
+  if (customFieldId && 'custom' in entry) {
+    return entry.custom?.[customFieldId] ?? '';
+  }
+  return getBuiltInValue(label, entry);
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/spreadsheetImportUtils.ts

@@ -0,0 +1,36 @@
+import type { ImportFormValues } from './importMapUtils';
+
+export function normaliseHeaderName(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+/**
+ * Derives the autocomplete option state for spreadsheet header mapping inputs.
+ * Walks the enabled built-in mappings and all custom mappings, normalizes
+ * their assigned header names, and returns both the unique worksheet headers to
+ * offer in the UI and the subset already assigned to any field.
+ */
+export function deriveHeaderOptionsState(values: ImportFormValues, headers: string[]) {
+  const sampleHeaders = [...new Set(headers.map(normaliseHeaderName).filter(Boolean))];
+
+  const assignedColumns = new Set<string>();
+
+  for (const field of values.builtIn) {
+    if (!field.enabled) continue;
+    const normalized = normaliseHeaderName(field.header);
+    if (normalized) {
+      assignedColumns.add(normalized);
+    }
+  }
+
+  for (const { importName } of values.custom) {
+    const normalized = normaliseHeaderName(importName);
+    if (normalized) {
+      assignedColumns.add(normalized);
+    }
+  }
+
+  const assignedHeaders = new Set(sampleHeaders.filter((header) => assignedColumns.has(normaliseHeaderName(header))));
+
+  return { sampleHeaders, assignedHeaders };
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/sheet-import/useSheetImportForm.ts

@@ -0,0 +1,294 @@
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import type { SpreadsheetPreviewResponse, SpreadsheetWorksheetMetadata } from 'ontime-types';
+import { millisToString } from 'ontime-utils';
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import { useFieldArray, useForm } from 'react-hook-form';
+
+import { maybeAxiosError } from '../../../../../../common/api/utils';
+import useCustomFields from '../../../../../../common/hooks-query/useCustomFields';
+import { formatDuration } from '../../../../../../common/utils/time';
+import {
+  type ImportFormValues,
+  builtInFieldDefs,
+  convertToImportMap,
+  getImportWarnings,
+  getPersistedImportState,
+  getResolvedCustomFields,
+  persistImportState,
+} from './importMapUtils';
+import type { PreviewState } from './preview/previewTableUtils';
+import { deriveHeaderOptionsState } from './spreadsheetImportUtils';
+
+type ImportAction =
+  | { type: 'startPreview' }
+  | { type: 'startApply' }
+  | { type: 'startExport' }
+  | { type: 'previewSuccess'; preview: PreviewState }
+  | { type: 'applySuccess' }
+  | { type: 'exportSuccess' }
+  | { type: 'clearPreview'; error?: string }
+  | { type: 'failure'; error: string }
+  | { type: 'reset' };
+
+type ImportState = {
+  loading: '' | 'preview' | 'apply' | 'export';
+  error: string;
+  preview: PreviewState | null;
+};
+
+const initialImportState: ImportState = {
+  loading: '',
+  error: '',
+  preview: null,
+};
+
+function importReducer(state: ImportState, action: ImportAction): ImportState {
+  switch (action.type) {
+    case 'startPreview':
+      return { ...state, loading: 'preview', error: '' };
+    case 'startApply':
+      return { ...state, loading: 'apply', error: '' };
+    case 'startExport':
+      return { ...state, loading: 'export', error: '' };
+    case 'previewSuccess':
+      return { loading: '', error: '', preview: action.preview };
+    case 'applySuccess':
+    case 'exportSuccess':
+      return { ...state, loading: '' };
+    case 'clearPreview':
+      return { ...state, error: action.error ?? '', preview: null };
+    case 'failure': {
+      if (state.loading === 'preview') {
+        return { loading: '', error: action.error, preview: null };
+      }
+      return { ...state, loading: '', error: action.error };
+    }
+    case 'reset':
+      return initialImportState;
+    default:
+      return state;
+  }
+}
+
+function getPreferredWorksheet(worksheetNames: string[], current: string, fallback: string): string {
+  if (worksheetNames.includes(current)) {
+    return current;
+  }
+  if (worksheetNames.includes(fallback)) {
+    return fallback;
+  }
+  return worksheetNames[0] ?? '';
+}
+
+const emptyHeaders: string[] = [];
+
+function buildColumnLabels(values: ImportFormValues): string[] {
+  const builtIn: string[] = [];
+  for (let i = 0; i < values.builtIn.length; i++) {
+    if (values.builtIn[i].enabled) {
+      builtIn.push(builtInFieldDefs[i].label);
+    }
+  }
+
+  const custom: string[] = [];
+  for (const { ontimeName } of getResolvedCustomFields(values.custom)) {
+    if (ontimeName) {
+      custom.push(ontimeName);
+    }
+  }
+
+  return [...builtIn, ...custom];
+}
+
+interface UseSheetImportFormProps {
+  sourceKey: string;
+  worksheetNames: string[];
+  initialMetadata: SpreadsheetWorksheetMetadata | null;
+  loadMetadata: (worksheet: string) => Promise<SpreadsheetWorksheetMetadata>;
+  previewImport: (importMap: ReturnType<typeof convertToImportMap>) => Promise<SpreadsheetPreviewResponse>;
+  onApply: (preview: PreviewState) => Promise<void>;
+  onExport?: (importMap: ReturnType<typeof convertToImportMap>) => Promise<void>;
+}
+
+export function useSheetImportForm({
+  sourceKey,
+  worksheetNames,
+  initialMetadata,
+  loadMetadata,
+  previewImport,
+  onApply,
+  onExport,
+}: UseSheetImportFormProps) {
+  const initialFormValues = useMemo(() => {
+    const persisted = getPersistedImportState(sourceKey);
+    const worksheet = getPreferredWorksheet(worksheetNames, persisted.worksheet, initialMetadata?.worksheet ?? '');
+    return { ...persisted, worksheet };
+  }, [initialMetadata?.worksheet, sourceKey, worksheetNames]);
+
+  const {
+    control,
+    handleSubmit,
+    reset,
+    setValue,
+    watch,
+    formState: { isValid },
+  } = useForm<ImportFormValues>({
+    mode: 'onChange',
+    defaultValues: initialFormValues,
+  });
+
+  const { fields, append, remove } = useFieldArray({ control, name: 'custom' });
+  const values = watch();
+  const { data: existingCustomFields } = useCustomFields();
+
+  // --- Worksheet metadata via react-query ---
+  const queryClient = useQueryClient();
+
+  useEffect(() => {
+    queryClient.removeQueries({ queryKey: ['worksheet-metadata', sourceKey] });
+    if (initialMetadata) {
+      queryClient.setQueryData(['worksheet-metadata', sourceKey, initialMetadata.worksheet], initialMetadata);
+    }
+  }, [initialMetadata, sourceKey, queryClient]);
+
+  const worksheetMetadataQuery = useQuery({
+    queryKey: ['worksheet-metadata', sourceKey, values.worksheet],
+    queryFn: () => loadMetadata(values.worksheet),
+    enabled: Boolean(values.worksheet) && worksheetNames.includes(values.worksheet),
+    staleTime: Infinity,
+  });
+
+  const headers = worksheetMetadataQuery.data?.headers ?? emptyHeaders;
+  const isLoadingMetadata = worksheetMetadataQuery.isLoading;
+  const metadataError = worksheetMetadataQuery.error ? maybeAxiosError(worksheetMetadataQuery.error) : '';
+
+  // --- Derived state ---
+  const { sampleHeaders, assignedHeaders } = useMemo(
+    () => deriveHeaderOptionsState(values, headers),
+    [values, headers],
+  );
+  const columnLabels = buildColumnLabels(values);
+
+  const [state, dispatch] = useReducer(importReducer, initialImportState);
+  const existingCustomFieldLabels = useMemo(
+    () => Object.values(existingCustomFields).map((field) => field.label),
+    [existingCustomFields],
+  );
+  const warnings = getImportWarnings(values, headers, existingCustomFieldLabels);
+  const warningCount = Object.values(warnings).filter(Boolean).length;
+
+  // Rehydrate the form from persisted/default state whenever the source context changes.
+  useEffect(() => {
+    reset(initialFormValues);
+    dispatch({ type: 'reset' });
+  }, [initialMetadata, initialFormValues, reset, sourceKey]);
+
+  // Keep the worksheet selection valid if the available worksheets change underneath the form.
+  useEffect(() => {
+    if (worksheetNames.length === 0) return;
+    if (worksheetNames.includes(values.worksheet)) return;
+    setValue('worksheet', worksheetNames[0], { shouldDirty: true, shouldValidate: true });
+  }, [setValue, values.worksheet, worksheetNames]);
+
+  // Clear preview on any form change.
+  useEffect(() => {
+    const sub = watch(() => {
+      if (state.preview) {
+        dispatch({ type: 'clearPreview' });
+      }
+    });
+    return () => sub.unsubscribe();
+  }, [watch, state.preview]);
+
+  // Race condition guard for async preview requests.
+  const requestIdRef = useRef(0);
+
+  const handlePreview = useCallback(
+    async (formValues: ImportFormValues) => {
+      const importMap = convertToImportMap(formValues);
+      const id = ++requestIdRef.current;
+
+      try {
+        dispatch({ type: 'startPreview' });
+        const previewData = await previewImport(importMap);
+
+        if (requestIdRef.current !== id) return;
+
+        dispatch({ type: 'previewSuccess', preview: previewData });
+      } catch (error) {
+        if (requestIdRef.current !== id) return;
+        dispatch({ type: 'failure', error: maybeAxiosError(error) });
+      }
+    },
+    [previewImport],
+  );
+
+  const handleApply = useCallback(async () => {
+    if (!state.preview) return;
+
+    try {
+      dispatch({ type: 'startApply' });
+      await onApply(state.preview);
+      persistImportState(sourceKey, values);
+      dispatch({ type: 'applySuccess' });
+    } catch (error) {
+      dispatch({ type: 'failure', error: maybeAxiosError(error) });
+    }
+  }, [onApply, sourceKey, state.preview, values]);
+
+  const handleExport = useCallback(
+    async (formValues: ImportFormValues) => {
+      if (!onExport) return;
+      try {
+        dispatch({ type: 'startExport' });
+        const importMap = convertToImportMap(formValues);
+        await onExport(importMap);
+        dispatch({ type: 'exportSuccess' });
+      } catch (error) {
+        dispatch({ type: 'failure', error: maybeAxiosError(error) });
+      }
+    },
+    [onExport],
+  );
+
+  const isBusy = Boolean(state.loading);
+  const canPreview = isValid && !isLoadingMetadata && !isBusy && worksheetNames.length > 0;
+  const displayError = metadataError || state.error;
+  const addCustomField = useCallback(() => {
+    append({ importName: '', ontimeName: '' });
+  }, [append]);
+
+  const toolbarStatus = (() => {
+    const warningText = warningCount > 0 ? ` | warnings: ${warningCount}` : '';
+
+    if (!state.preview) {
+      return `entries: – | start: – | end: – | duration: –${warningText}`;
+    }
+
+    const { flatOrder } = state.preview.rundown;
+    const { start, end, duration } = state.preview.summary;
+    return `entries: ${flatOrder.length} | start: ${millisToString(start)} | end: ${millisToString(end)} | duration: ${formatDuration(duration)}${warningText}`;
+  })();
+
+  return {
+    values,
+    setValue,
+    fields,
+    addCustomField,
+    removeCustomField: remove,
+    sampleHeaders,
+    assignedHeaders,
+    warnings,
+    columnLabels,
+    worksheetHeaders: headers,
+    state,
+    toolbarStatus,
+    isLoadingMetadata,
+    isBusy,
+    canPreview,
+    displayError,
+    handlePreviewSubmit: handleSubmit(handlePreview),
+    handleExportSubmit: handleSubmit(handleExport),
+    handleApply,
+  };
+}

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/useGoogleSheet.ts

@@ -9,23 +9,13 @@ import {
   getRundownQueryKey,
 } from '../../../../../common/api/constants';
 import { patchData } from '../../../../../common/api/db';
-import {
-  previewRundown,
-  requestConnection,
-  revokeAuthentication,
-  uploadRundown,
-  verifyAuthenticationStatus,
-} from '../../../../../common/api/sheets';
+import { requestConnection, revokeAuthentication, verifyAuthenticationStatus } from '../../../../../common/api/sheets';
 import { maybeAxiosError } from '../../../../../common/api/utils';
 import { useSheetStore } from './useSheetStore';
 
 export default function useGoogleSheet() {
   const queryClient = useQueryClient();
-  // functions push data to store
   const patchStepData = useSheetStore((state) => state.patchStepData);
-  const setRundown = useSheetStore((state) => state.setRundown);
-  const setCustomFields = useSheetStore((state) => state.setCustomFields);
-  const setSummary = useSheetStore((state) => state.setSummary);
 
   /** whether the current session has been authenticated */
   const verifyAuth = async (): Promise<{ authenticated: AuthenticationStatus; sheetId: string } | void> => {
@@ -57,29 +47,6 @@ export default function useGoogleSheet() {
     }
   };
 
-  /** fetches data from a worksheet by its ID */
-  const importRundownPreview = async (sheetId: string, fileOptions: ImportMap) => {
-    try {
-      const data = await previewRundown(sheetId, fileOptions);
-      setRundown(data.rundown);
-      setCustomFields(data.customFields);
-      setSummary(data.summary);
-    } catch (error) {
-      patchStepData({ pullPush: { available: true, error: maybeAxiosError(error) } });
-    }
-  };
-
-  /** writes data to a worksheet by its ID */
-  const exportRundown = async (sheetId: string, fileOptions: ImportMap) => {
-    try {
-      // write data to google
-      await uploadRundown(sheetId, fileOptions);
-      patchStepData({ pullPush: { available: false, error: '' } });
-    } catch (error) {
-      patchStepData({ pullPush: { available: true, error: maybeAxiosError(error) } });
-    }
-  };
-
   /** applies rundown and customFields to current project */
   const importRundown = async (rundowns: ProjectRundowns, customFields: CustomFields) => {
     try {
@@ -92,6 +59,7 @@ export default function useGoogleSheet() {
       await queryClient.invalidateQueries({ queryKey: CUSTOM_FIELDS });
     } catch (error) {
       patchStepData({ pullPush: { available: true, error: maybeAxiosError(error) } });
+      throw error;
     }
   };
 
@@ -99,9 +67,6 @@ export default function useGoogleSheet() {
     connect,
     revoke,
     verifyAuth,
-
-    importRundownPreview,
     importRundown,
-    exportRundown,
   };
 }

apps/client/src/features/app-settings/panel/manage-panel/sources-panel/useSheetStore.ts

@@ -1,5 +1,4 @@
-import { AuthenticationStatus, CustomFields, Rundown, RundownSummary } from 'ontime-types';
-import { ImportMap, defaultImportMap } from 'ontime-utils';
+import { AuthenticationStatus } from 'ontime-types';
 import { create } from 'zustand';
 
 type SheetStore = {
@@ -14,19 +13,7 @@ type SheetStore = {
   authenticationStatus: AuthenticationStatus;
   setAuthenticationStatus: (status: AuthenticationStatus) => void;
 
-  // we get this from a preview response
-  rundown: Rundown | null;
-  setRundown: (rundown: Rundown | null) => void;
-  customFields: CustomFields | null;
-  setCustomFields: (customFields: CustomFields | null) => void;
-  summary: RundownSummary | null;
-  setSummary: (metadata: RundownSummary | null) => void;
-
-  spreadsheetImportMap: ImportMap;
-  patchSpreadsheetImportMap: <T extends keyof ImportMap>(field: T, value: ImportMap[T]) => void;
-
   reset: () => void;
-  resetPreview: () => void;
 };
 
 const initialStepData = {
@@ -41,10 +28,6 @@ const initialState = {
   worksheetNames: null,
   sheetId: null,
   authenticationStatus: 'not_authenticated' as AuthenticationStatus,
-  rundown: null,
-  customFields: null,
-  summary: null,
-  spreadsheetImportMap: defaultImportMap,
 };
 
 export const useSheetStore = create<SheetStore>((set, get) => ({
@@ -61,19 +44,5 @@ export const useSheetStore = create<SheetStore>((set, get) => ({
 
   setAuthenticationStatus: (status: AuthenticationStatus) => set({ authenticationStatus: status }),
 
-  setRundown: (rundown: Rundown | null) => set({ rundown }),
-
-  setCustomFields: (customFields: CustomFields | null) => set({ customFields }),
-
-  setSummary: (summary: RundownSummary | null) => set({ summary }),
-
-  patchSpreadsheetImportMap: <T extends keyof ImportMap>(field: T, value: ImportMap[T]) => {
-    const currentImportMap = get().spreadsheetImportMap;
-    if (currentImportMap[field] !== value) {
-      currentImportMap[field] = value;
-    }
-  },
-
   reset: () => set(initialState),
-  resetPreview: () => set({ rundown: null, customFields: null, summary: null }),
 }));

apps/client/src/theme/_ontimeStyles.scss

@@ -78,6 +78,7 @@ $aux-text-size: calc(1rem - 3px);
 // media queries
 $min-tablet: 500px;
 $small-screen: 800px;
+$medium-screen: 1100px;
 $small-desktop: 1440px;
 
 .blink {

apps/server/src/api-data/excel/excel.service.ts

@@ -7,6 +7,7 @@ import { existsSync } from 'fs';
 import { extname } from 'path';
 
 import { CustomFields, Rundown, RundownSummary } from 'ontime-types';
+import type { SpreadsheetWorksheetMetadata } from 'ontime-types';
 import { type ImportMap } from 'ontime-utils';
 import xlsx from 'xlsx';
 import type { WorkBook } from 'xlsx';
@@ -16,10 +17,8 @@ import { parseCustomFields } from '../custom-fields/customFields.parser.js';
 import { getProjectCustomFields, processRundown } from '../rundown/rundown.dao.js';
 import { parseRundown } from '../rundown/rundown.parser.js';
 import { parseExcel } from './excel.parser.js';
-import type { SpreadsheetWorksheetMetadata } from 'ontime-types';
-
-import { getWorksheetMetadataFromRows } from './spreadsheetMetadata.utils.js';
 import { rundownToTabular } from './excel.utils.js';
+import { getWorksheetMetadataFromRows } from './spreadsheetMetadata.utils.js';
 
 // we keep the excel data in memory to allow the flow upload -> preview
 let excelData: WorkBook = xlsx.utils.book_new();

apps/server/src/api-data/sheets/sheets.controller.ts

@@ -27,6 +27,9 @@ import {
   upload,
 } from './sheets.service.js';
 
+/**
+ * Starts the Google device authorization flow for the provided sheet.
+ */
 export async function requestConnection(
   req: Request,
   res: Response<{ verification_url: string; user_code: string } | ErrorResponse>,
@@ -50,6 +53,9 @@ export async function requestConnection(
   await deleteFile(filePath);
 }
 
+/**
+ * Returns the current Google Sheets authentication status for this server session.
+ */
 export async function verifyAuthentication(
   _req: Request,
   res: Response<{ authenticated: AuthenticationStatus } | ErrorResponse>,
@@ -63,6 +69,9 @@ export async function verifyAuthentication(
   }
 }
 
+/**
+ * Clears the current Google Sheets authentication session.
+ */
 export async function revokeAuthentication(
   _req: Request,
   res: Response<{ authenticated: AuthenticationStatus } | ErrorResponse>,
@@ -76,7 +85,10 @@ export async function revokeAuthentication(
   }
 }
 
-export async function getWorksheetNamesFromSheet(
+/**
+ * Lists worksheet titles. Metadata is loaded lazily for the selected worksheet.
+ */
+export async function getWorksheetOptionsFromSheet(
   req: Request,
   res: Response<SpreadsheetWorksheetOptions | ErrorResponse>,
 ) {
@@ -90,7 +102,13 @@ export async function getWorksheetNamesFromSheet(
   }
 }
 
-export async function getWorksheetMetadataFromSheet(req: Request, res: Response<SpreadsheetWorksheetMetadata | ErrorResponse>) {
+/**
+ * Returns derived metadata for a single worksheet by inspecting its row data.
+ */
+export async function getWorksheetMetadataFromSheet(
+  req: Request,
+  res: Response<SpreadsheetWorksheetMetadata | ErrorResponse>,
+) {
   try {
     const { sheetId } = req.params;
     const { worksheet } = req.body;
@@ -102,10 +120,10 @@ export async function getWorksheetMetadataFromSheet(req: Request, res: Response<
   }
 }
 
-export async function readFromSheet(
-  req: Request,
-  res: Response<SpreadsheetPreviewResponse | ErrorResponse>,
-) {
+/**
+ * Reads a Google Sheet worksheet and converts it into a rundown preview.
+ */
+export async function readFromSheet(req: Request, res: Response<SpreadsheetPreviewResponse | ErrorResponse>) {
   try {
     const { sheetId } = req.params;
     const { options } = req.body;
@@ -117,6 +135,9 @@ export async function readFromSheet(
   }
 }
 
+/**
+ * Writes the current rundown back to the selected Google Sheet worksheet.
+ */
 export async function writeToSheet(req: Request, res: Response<void | ErrorResponse>) {
   try {
     const { sheetId } = req.params;

apps/server/src/api-data/sheets/sheets.router.ts

@@ -6,7 +6,7 @@ import express from 'express';
 
 import {
   getWorksheetMetadataFromSheet,
-  getWorksheetNamesFromSheet,
+  getWorksheetOptionsFromSheet,
   readFromSheet,
   requestConnection,
   revokeAuthentication,
@@ -28,7 +28,7 @@ router.post('/:sheetId/connect', uploadClientSecret, validateRequestConnection,
 
 router.post('/revoke', revokeAuthentication);
 
-router.post('/:sheetId/worksheets', validateSheetId, getWorksheetNamesFromSheet);
+router.post('/:sheetId/worksheet-options', validateSheetId, getWorksheetOptionsFromSheet);
 router.post('/:sheetId/metadata', validateWorksheetMetadata, getWorksheetMetadataFromSheet);
 
 router.post('/:sheetId/read', validateSheetOptions, readFromSheet);

apps/server/src/api-data/sheets/sheets.service.ts

@@ -20,14 +20,13 @@ import {
   isOntimeEvent,
   isOntimeMilestone,
 } from 'ontime-types';
+import type { SpreadsheetWorksheetMetadata } from 'ontime-types';
 import { ImportMap, getErrorMessage } from 'ontime-utils';
 
 import { logger } from '../../classes/Logger.js';
 import { consoleSubdued } from '../../utils/console.js';
 import { parseCustomFields } from '../custom-fields/customFields.parser.js';
 import { parseExcel } from '../excel/excel.parser.js';
-import type { SpreadsheetWorksheetMetadata } from 'ontime-types';
-
 import { getWorksheetMetadataFromRows } from '../excel/spreadsheetMetadata.utils.js';
 import { getCurrentRundown, getProjectCustomFields, processRundown } from '../rundown/rundown.dao.js';
 import { parseRundowns } from '../rundown/rundown.parser.js';
@@ -224,10 +223,10 @@ export function hasAuth(): { authenticated: AuthenticationStatus; sheetId: strin
   return { authenticated: currentAuthClient ? 'authenticated' : 'not_authenticated', sheetId: currentSheetId };
 }
 
-async function verifySheet(
-  sheetId = currentSheetId,
-  authClient = currentAuthClient,
-): Promise<string[]> {
+/**
+ * Validates that a spreadsheet exists and returns its worksheet titles without reading cell data.
+ */
+async function verifySheet(sheetId = currentSheetId, authClient = currentAuthClient): Promise<string[]> {
   if (!sheetId || !authClient) {
     throw new Error('Missing sheet ID or authentication');
   }
@@ -284,8 +283,7 @@ export async function handleInitialConnection(
 }
 
 /**
- * Allow calling verification for sheetId
- * @returns
+ * Returns the available worksheet titles. Metadata is loaded lazily per worksheet.
  */
 export async function getWorksheetOptions(
   sheetId: string,
@@ -296,29 +294,16 @@ export async function getWorksheetOptions(
   currentSheetId = sheetId;
 
   const worksheets = await verifySheet(sheetId);
-  const metadata = await getInitialWorksheetMetadata(sheetId, worksheets);
 
   return {
     worksheets,
-    metadata,
+    metadata: null,
   };
 }
 
-async function getInitialWorksheetMetadata(
-  sheetId: string,
-  worksheets: string[],
-): Promise<SpreadsheetWorksheetMetadata | null> {
-  for (const worksheet of worksheets) {
-    try {
-      return await getWorksheetMetadata(sheetId, worksheet);
-    } catch {
-      // Continue looking for the first worksheet with usable headers.
-    }
-  }
-
-  return null;
-}
-
+/**
+ * Reads worksheet rows from Google Sheets and derives import metadata from the detected header row.
+ */
 export async function getWorksheetMetadata(sheetId: string, worksheet: string) {
   if (!currentAuthClient) {
     throw new Error('Not authenticated');
@@ -344,6 +329,9 @@ export async function getWorksheetMetadata(sheetId: string, worksheet: string) {
   return getWorksheetMetadataFromRows(worksheet, googleResponse.data.values);
 }
 
+/**
+ * Validates that a worksheet exists and computes the A1 range needed to read its current grid.
+ */
 async function verifyWorksheet(sheetId: string, worksheet: string): Promise<{ worksheetId: number; range: string }> {
   if (!currentAuthClient) {
     throw new Error('Not authenticated');

e2e/tests/features/301-spreadsheet-import.spec.ts

@@ -1,41 +1,94 @@
-import { expect, test } from '@playwright/test';
+import { expect, test, type Page } from '@playwright/test';
 
-const fileToUpload = 'e2e/tests/fixtures/test-sheet.xlsx';
+const fileToUpload = 'e2e/tests/fixtures/Ontime rundown template v4.xlsx';
 
-test('sheet file upload', async ({ page }) => {
+test('imports spreadsheet and applies imported rundown to editor', async ({ page }) => {
   await page.goto('/editor');
   await page.getByRole('button', { name: 'Edit' }).click();
+
+  // clear the rundown
   await page.getByRole('button', { name: 'Rundown menu' }).click();
   await page.getByRole('menuitem', { name: 'Clear all' }).click();
   await page.getByRole('button', { name: 'Delete all' }).click();
+  await expect(page.getByTestId('rundown-event')).toHaveCount(0);
 
+  // open the spreadsheet
   await page.getByRole('button', { name: 'Toggle settings' }).click();
-  await page.getByRole('button', { name: 'Import spreadsheet' }).click();
+  await page.getByRole('button', { name: 'Project settings' }).click();
+  await page.getByRole('button', { name: 'Import spreadsheet' }).first().click();
+  await expect(page.getByText('Synchronise your rundown with an external source')).toBeVisible();
 
-  // workaround to upload file on hidden input
-  // https://playwright.dev/docs/api/class-filechooser
+  // upload the spreadsheet
   const fileChooserPromise = page.waitForEvent('filechooser');
   await page.getByRole('button', { name: 'Import from spreadsheet', exact: true }).click();
   const fileChooser = await fileChooserPromise;
   await fileChooser.setFiles(fileToUpload);
+  const worksheetSelect = page.getByRole('combobox', { name: 'Worksheet', exact: true });
+  await expect(worksheetSelect).toBeVisible();
+  await worksheetSelect.click();
+  await page.getByRole('option', { name: 'Event schedule advanced' }).click();
+  await expect(worksheetSelect).toContainText('Event schedule advanced');
 
-  await page.getByRole('row', { name: 'Worksheet' }).getByRole('combobox').click();
-  await page.getByRole('option', { name: 'test' }).click();
-
-  await page.getByRole('button', { name: 'Import preview' }).click();
-  await page.getByRole('button', { name: 'Apply' }).click();
+  // apply import
+  await page.getByRole('button', { name: 'Preview import' }).click();
+  await page.getByRole('button', { name: 'Apply import' }).click();
+  await expect(page.getByText('Import successful')).toBeVisible();
   await page.getByRole('button', { name: 'Return' }).click();
 
+  // verify the data in the rundown
   await page.getByRole('button', { name: 'Close settings' }).scrollIntoViewIfNeeded();
   await page.getByRole('button', { name: 'Close settings' }).click();
 
-  // asset test events
-  const firstTitle = page.getByTestId('entry-1').getByTestId('entry__title');
-  await expect(firstTitle).toHaveValue('Attempt light check');
+  await expectGroupSummary(page, {
+    title: 'Morning Sessions',
+    entries: '5',
+    start: '10:00:00',
+    end: '12:00:00',
+    duration: '2h',
+  });
+  await expectGroupSummary(page, {
+    title: 'Lunch',
+    entries: '1',
+    start: '12:00:00',
+    end: '13:00:00',
+    duration: '1h',
+  });
+  await expectGroupSummary(page, {
+    title: 'Afternoon Sessions',
+    entries: '4',
+    start: '13:00:00',
+    end: '14:00:00',
+    duration: '1h',
+  });
 
-  const secondTitle = page.getByTestId('entry-2').getByTestId('entry__title');
-  await expect(secondTitle).toHaveValue('Preset');
+  await expectInputValue(page, 'Lunch / Countdown to next session');
 
-  const thirdTitle = page.getByTestId('entry-3').getByTestId('entry__title');
-  await expect(thirdTitle).toHaveValue('Albania');
+  await expectInputValue(page, '11:30 - House staff setup lunch in lobby');
 });
+
+async function expectGroupSummary(
+  page: Page,
+  {
+    title,
+    entries,
+    start,
+    end,
+    duration,
+  }: { title: string; entries: string; start: string; end: string; duration: string },
+) {
+  const group = page.getByTestId('rundown-group').filter({ has: page.locator(`input[value="${title}"]`) });
+
+  await expect(group).toHaveCount(1);
+  await expect(group).toContainText('Entries');
+  await expect(group).toContainText(entries);
+  await expect(group).toContainText('Start');
+  await expect(group).toContainText(start);
+  await expect(group).toContainText('End');
+  await expect(group).toContainText(end);
+  await expect(group).toContainText('Duration');
+  await expect(group).toContainText(duration);
+}
+
+async function expectInputValue(page: Page, value: string) {
+  await expect(page.locator(`input[value="${value}"]`)).toHaveCount(1);
+}

packages/types/src/api/spreadsheet/Spreadsheet.type.ts

@@ -0,0 +1,19 @@
+import type { CustomFields } from '../../definitions/core/CustomFields.type.js';
+import type { Rundown } from '../../definitions/core/Rundown.type.js';
+import type { RundownSummary } from '../rundown-controller/BackendResponse.type.js';
+
+export type SpreadsheetWorksheetMetadata = {
+  worksheet: string;
+  headers: string[];
+};
+
+export type SpreadsheetWorksheetOptions = {
+  worksheets: string[];
+  metadata: SpreadsheetWorksheetMetadata | null;
+};
+
+export type SpreadsheetPreviewResponse = {
+  rundown: Rundown;
+  customFields: CustomFields;
+  summary: RundownSummary;
+};

packages/types/src/index.ts

@@ -92,6 +92,11 @@ export type {
 } from './api/rundown-controller/BackendResponse.type.js';
 export type { LinkOptions } from './api/session-controller/BackendResponse.type.js';
 export type { CustomViewSummary, CustomViewsListResponse } from './api/custom-views/customViews.type.js';
+export type {
+  SpreadsheetWorksheetMetadata,
+  SpreadsheetWorksheetOptions,
+  SpreadsheetPreviewResponse,
+} from './api/spreadsheet/Spreadsheet.type.js';
 
 // web socket
 export { MessageTag } from './api/websocket/data.type.js';