@axinom/mosaic-ui 0.74.0 → 0.74.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axinom/mosaic-ui",
-  "version": "0.74.0",
+  "version": "0.74.1",
   "engines": {
     "node": ">=20.19.0"
   },
@@ -112,5 +112,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "8be80fd805ce6806abff3a5dbbe84ead9af9aea2"
+  "gitHead": "4e25b38a8dac4aaada88ec0ca96c94bfcb12b19c"
 }

package/src/components/FormStation/FormStation.tsx

@@ -67,6 +67,22 @@ export interface FormStationProps<
   validationSchema?: OptionalObjectSchema<ObjectSchemaDefinition<TValues>>;
   /** URL to navigate to when the form is reset (usually on a create station) */
   cancelNavigationUrl?: string;
+  /**
+   * Called when the header's 'Cancel' action was selected and the form was
+   * reset. Takes precedence over `cancelNavigationUrl`.
+   */
+  onCancel?: () => void;
+  /**
+   * Called once the header's save action saved the form successfully. Setting
+   * it also makes that action submit the form directly, instead of saving on
+   * navigation.
+   */
+  onSaveCompleted?: () => void;
+  /**
+   * If set to true, a dirty form is saved when the user navigates away, and
+   * navigation is cancelled while the form is invalid. (default: true)
+   */
+  saveOnNavigate?: boolean;
   /** Component which contains additional information */
   infoPanel?: JSX.Element;
   /** Optional flag for removing the padding around child components. */
@@ -101,6 +117,9 @@ export const FormStation = <TValues extends Data, TSubmitResponse = unknown>({
   actions,
   actionsWidth,
   cancelNavigationUrl,
+  onCancel,
+  onSaveCompleted,
+  saveOnNavigate = true,
   initialData,
   saveData,
   validationSchema,
@@ -191,13 +210,15 @@ export const FormStation = <TValues extends Data, TSubmitResponse = unknown>({
             defaultTitle={defaultTitle}
             subtitle={subtitle}
             cancelNavigationUrl={cancelNavigationUrl}
+            onCancel={onCancel}
+            onSaveCompleted={onSaveCompleted}
             className={classes.header}
             setTabTitle={setTabTitle}
             showSaveHeaderAction={showSaveHeaderAction}
             saveHeaderActionConfig={saveHeaderActionConfig}
             setValidationError={setValidationError}
           />
-          {!bulkEditContext && (
+          {saveOnNavigate && !bulkEditContext && (
             <SaveOnNavigate
               isSubmitting={isFormSubmitting}
               onNavigationCancelled={setValidationError}

package/src/components/FormStation/FormStationHeader/FormStationHeader.tsx

@@ -21,6 +21,8 @@ export const FormStationHeader: React.FC<
     titleProperty?: string;
     defaultTitle?: string;
     cancelNavigationUrl?: string;
+    onCancel?: () => void;
+    onSaveCompleted?: () => void;
     setTabTitle?: boolean;
     showSaveHeaderAction?: boolean;
     saveHeaderActionConfig?: Pick<PageHeaderJsActionProps, 'label' | 'icon'>;
@@ -31,6 +33,8 @@ export const FormStationHeader: React.FC<
   defaultTitle,
   subtitle,
   cancelNavigationUrl,
+  onCancel,
+  onSaveCompleted,
   className,
   setTabTitle,
   showSaveHeaderAction,
@@ -71,7 +75,23 @@ export const FormStationHeader: React.FC<
           kind: 'action',
           actionType: PageHeaderActionType.Context,
           onClick: async () => {
-            if (quickEditContext?.isQuickEditMode) {
+            if (onSaveCompleted) {
+              // No navigation happens, so `SaveOnNavigate` cannot do the save.
+              const errors = await validateForm();
+              if (Object.keys(errors).length > 0) {
+                setValidationError();
+                return;
+              }
+
+              try {
+                await submitForm();
+              } catch {
+                // The station error is already set by the submit handler.
+                return;
+              }
+
+              onSaveCompleted();
+            } else if (quickEditContext?.isQuickEditMode) {
               quickEditContext.refresh();
             } else if (bulkEditContext?.isBulkEditMode) {
               const errors = await validateForm();
@@ -111,7 +131,17 @@ export const FormStationHeader: React.FC<
       });
     }
 
-    if (cancelNavigationUrl) {
+    if (onCancel) {
+      actionItems.push({
+        label: 'Cancel',
+        icon: IconName.X,
+        kind: 'action',
+        onClick: () => {
+          resetForm();
+          onCancel();
+        },
+      });
+    } else if (cancelNavigationUrl) {
       actionItems.push({
         label: 'Cancel',
         icon: IconName.X,
@@ -130,6 +160,8 @@ export const FormStationHeader: React.FC<
     cancelNavigationUrl,
     dirty,
     history,
+    onCancel,
+    onSaveCompleted,
     quickEditContext,
     resetForm,
     saveHeaderActionConfig.icon,

package/src/components/FormStation/ModalForm/ModalForm.module.scss

@@ -0,0 +1,18 @@
+@import '../../../styles/common.scss';
+
+.container {
+  @include boxSizing;
+
+  display: grid;
+  grid-template-rows: minmax(0, 1fr);
+
+  // The modal sizes itself to its content, so the form claims its own width.
+  width: calc(100vw - #{$modal-padding-side} - #{$modal-padding-side});
+}
+
+// FormStation sizes itself to the viewport minus the app header, which is the
+// wrong box inside a modal. Doubled class to outrank it regardless of
+// stylesheet order.
+.station.station {
+  height: calc(100vh - #{$modal-padding-top} - #{$modal-padding-bottom});
+}

package/src/components/FormStation/ModalForm/ModalForm.spec.tsx

@@ -0,0 +1,290 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { useFormikContext } from 'formik';
+import React, { useEffect } from 'react';
+import { act } from 'react-dom/test-utils';
+import { Link, MemoryRouter, Route } from 'react-router-dom';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import * as Yup from 'yup';
+import { noop } from '../../../helpers/utils';
+import { initializeUi } from '../../../initialize';
+import { TextButton } from '../../Buttons';
+import type { ObjectSchemaDefinition } from '../FormStation.models';
+import { ModalForm } from './ModalForm';
+import { useModalForm } from './useModalForm';
+
+vi.mock('../../../initialize');
+
+interface FormValues {
+  something: string;
+}
+
+const initialData = {
+  loading: false,
+  data: { something: 'initial' },
+};
+
+/** Makes the form dirty, so the header shows its 'Save' action. */
+const ChangeValue: React.FC = () => {
+  const context = useFormikContext();
+  useEffect(() => {
+    context.setFieldValue('something', 'changed');
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  return null;
+};
+
+/** Waits for Formik's asynchronous state updates to settle. */
+const settle = async (): Promise<void> => {
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+};
+
+const headerActions = (): HTMLElement[] =>
+  Array.from(
+    document.querySelectorAll<HTMLElement>(
+      '[data-test-id="page-header-actions"] [data-test-id="action"]',
+    ),
+  );
+
+describe('ModalForm', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+
+    initializeUi({
+      showNotification: () => -1,
+      addIndicator: () => -1,
+      removeIndicator: noop,
+      on: () => noop,
+      setTitle: noop,
+      setSaveIndicator: noop,
+    });
+  });
+
+  const renderModalForm = (
+    props: Partial<React.ComponentProps<typeof ModalForm<FormValues>>> = {},
+  ): { closeModal: () => void; saveData: () => void } => {
+    const closeModal = vi.fn();
+    const saveData = vi.fn();
+
+    render(
+      <MemoryRouter>
+        <ModalForm<FormValues>
+          title="Modal Form"
+          closeModal={closeModal}
+          initialData={initialData}
+          saveData={saveData}
+          {...props}
+        >
+          <ChangeValue />
+        </ModalForm>
+      </MemoryRouter>,
+    );
+
+    return { closeModal, saveData };
+  };
+
+  it('shows the given title', async () => {
+    renderModalForm();
+    await settle();
+
+    expect(screen.getByTestId('page-header-title')).toHaveTextContent(
+      'Modal Form',
+    );
+  });
+
+  it('closes the modal without saving when cancelled', async () => {
+    const { closeModal, saveData } = renderModalForm();
+    await settle();
+
+    // 'Undo Changes', 'Save' and 'Cancel'
+    const actions = headerActions();
+    expect(actions).toHaveLength(3);
+
+    fireEvent.click(actions[2]);
+    await settle();
+
+    expect(saveData).not.toHaveBeenCalled();
+    expect(closeModal).toHaveBeenCalledTimes(1);
+  });
+
+  it('saves the data and closes the modal when saved', async () => {
+    const { closeModal, saveData } = renderModalForm();
+    await settle();
+
+    fireEvent.click(headerActions()[1]);
+    await settle();
+
+    expect(saveData).toHaveBeenCalledTimes(1);
+    expect(saveData).toHaveBeenCalledWith(
+      { something: 'changed' },
+      initialData,
+      expect.anything(),
+    );
+    expect(closeModal).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps the modal open and shows the error when saving fails', async () => {
+    const { closeModal } = renderModalForm({
+      saveData: () => {
+        throw { title: 'Saving failed' };
+      },
+    });
+    await settle();
+
+    fireEvent.click(headerActions()[1]);
+    await settle();
+
+    expect(closeModal).not.toHaveBeenCalled();
+    expect(screen.getByText('Saving failed')).toBeInTheDocument();
+  });
+
+  it('keeps the modal open and does not save an invalid form', async () => {
+    const { closeModal, saveData } = renderModalForm({
+      validationSchema: Yup.object<ObjectSchemaDefinition<FormValues>>({
+        something: Yup.string().max(3, 'Too long'),
+      }),
+    });
+    await settle();
+
+    fireEvent.click(headerActions()[1]);
+    await settle();
+
+    expect(saveData).not.toHaveBeenCalled();
+    expect(closeModal).not.toHaveBeenCalled();
+    expect(
+      screen.getByText('Please fix the errors in the form to proceed.'),
+    ).toBeInTheDocument();
+  });
+
+  it('does not show a save action while the form is pristine', async () => {
+    render(
+      <MemoryRouter>
+        <ModalForm<FormValues>
+          title="Modal Form"
+          closeModal={noop}
+          initialData={initialData}
+          saveData={noop}
+        />
+      </MemoryRouter>,
+    );
+    await settle();
+
+    // Only 'Cancel' - the others appear once the form is dirty.
+    expect(headerActions()).toHaveLength(1);
+  });
+
+  it('discards the changes instead of saving them when navigating away', async () => {
+    let path = '';
+    const closeModal = vi.fn();
+    const saveData = vi.fn();
+
+    render(
+      <MemoryRouter>
+        <ModalForm<FormValues>
+          title="Modal Form"
+          closeModal={closeModal}
+          initialData={initialData}
+          saveData={saveData}
+        >
+          <ChangeValue />
+        </ModalForm>
+        <Link to="/somewhere-else">Go</Link>
+        <Route
+          path="*"
+          render={({ location }) => {
+            path = location.pathname;
+            return null;
+          }}
+        />
+      </MemoryRouter>,
+    );
+    await settle();
+
+    fireEvent.click(screen.getByText('Go'));
+    await settle();
+
+    expect(saveData).not.toHaveBeenCalled();
+    expect(path).toBe('/somewhere-else');
+  });
+
+  it('does not block navigation while the form is invalid', async () => {
+    let path = '';
+
+    render(
+      <MemoryRouter>
+        <ModalForm<FormValues>
+          title="Modal Form"
+          closeModal={noop}
+          initialData={initialData}
+          saveData={noop}
+          validationSchema={Yup.object<ObjectSchemaDefinition<FormValues>>({
+            something: Yup.string().max(3, 'Too long'),
+          })}
+        >
+          <ChangeValue />
+        </ModalForm>
+        <Link to="/somewhere-else">Go</Link>
+        <Route
+          path="*"
+          render={({ location }) => {
+            path = location.pathname;
+            return null;
+          }}
+        />
+      </MemoryRouter>,
+    );
+    await settle();
+
+    fireEvent.click(screen.getByText('Go'));
+    await settle();
+
+    expect(path).toBe('/somewhere-else');
+  });
+
+  describe('useModalForm', () => {
+    const Host: React.FC = () => {
+      const { ModalWrapper, openModal } = useModalForm<FormValues>({
+        title: 'Modal Form',
+        initialData,
+        saveData: noop,
+        children: <ChangeValue />,
+      });
+
+      return (
+        <>
+          <TextButton text="Open" onButtonClicked={openModal} />
+          <ModalWrapper />
+        </>
+      );
+    };
+
+    it('opens the form in a modal and closes it again when cancelled', async () => {
+      render(
+        <MemoryRouter>
+          <Host />
+        </MemoryRouter>,
+      );
+
+      expect(screen.queryByTestId('modal')).not.toBeInTheDocument();
+
+      fireEvent.click(screen.getByText('Open'));
+      await settle();
+
+      expect(screen.getByTestId('modal')).toBeInTheDocument();
+      expect(screen.getByTestId('page-header-title')).toHaveTextContent(
+        'Modal Form',
+      );
+
+      const actions = headerActions();
+      fireEvent.click(actions[actions.length - 1]);
+      await settle();
+
+      // The modal plays an exit animation before it unmounts.
+      fireEvent.animationEnd(screen.getByTestId('modal'));
+      await settle();
+
+      expect(screen.queryByTestId('modal')).not.toBeInTheDocument();
+    });
+  });
+});

package/src/components/FormStation/ModalForm/ModalForm.stories.tsx

@@ -0,0 +1,191 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Field } from 'formik';
+import React from 'react';
+import { MemoryRouter } from 'react-router';
+import { action } from 'storybook/actions';
+import * as Yup from 'yup';
+import { createGroups } from '../../../helpers/storybook';
+import { TextButton } from '../../Buttons';
+import {
+  CustomTagsField,
+  SelectField,
+  SingleLineTextField,
+  TagsField,
+} from '../../FormElements';
+import { useModal } from '../../Modal';
+import type { ObjectSchemaDefinition } from '../FormStation.models';
+import { ModalForm } from './ModalForm';
+import { useModalForm } from './useModalForm';
+
+interface MovieValues {
+  title?: string;
+  genres?: string[];
+  ratings?: string;
+  shortDescription?: string;
+  cast?: string[];
+}
+
+type ModalFormStoryType = typeof ModalForm<MovieValues>;
+
+const groups = createGroups({
+  Content: [],
+  Behavior: [],
+  Styling: [],
+});
+
+const meta: Meta<ModalFormStoryType> = {
+  title: 'Primary Components/Station Controls/FormStation/ModalForm',
+  component: ModalForm,
+  argTypes: {
+    ...groups,
+    closeModal: {
+      control: false,
+    },
+  },
+  decorators: [
+    // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+    (Story) => (
+      <MemoryRouter>
+        <Story />
+      </MemoryRouter>
+    ),
+  ],
+};
+export default meta;
+
+const formFields = (
+  <>
+    <Field name="title" label="Title" as={SingleLineTextField} />
+    <Field
+      name="genres"
+      label="Genre(s)"
+      tagsOptions={['Crime', 'Drama', 'Thriller']}
+      as={TagsField}
+    />
+    <Field
+      name="ratings"
+      label="Age Rating"
+      options={[
+        { value: 'PG', label: 'Parental Guidance Suggested (PG)' },
+        { value: 'PG-13', label: 'Parents Strongly Cautioned (PG-13)' },
+        { value: 'R', label: 'Restricted (R)' },
+      ]}
+      as={SelectField}
+    />
+    <Field
+      name="shortDescription"
+      label="Short Description"
+      placeholder="Enter a short description..."
+      as={SingleLineTextField}
+    />
+    <Field name="cast" label="Cast" as={CustomTagsField} />
+  </>
+);
+
+const defaultArgs = {
+  title: 'Edit Movie',
+  subtitle: 'Movies',
+  saveData: (...args: unknown[]): Promise<void> => {
+    action('saveData')(args);
+    return new Promise<void>((resolve) => setTimeout(resolve, 500));
+  },
+  validationSchema: Yup.object<ObjectSchemaDefinition<MovieValues>>({
+    title: Yup.string().required().max(25).label('Title'),
+    shortDescription: Yup.string().required().label('Short Description'),
+  }),
+  initialData: {
+    loading: false,
+    data: {
+      title: 'The Silent Sea',
+      genres: ['Drama'],
+      ratings: 'PG-13',
+      shortDescription: 'A crew searches an abandoned lunar research station.',
+      cast: ['Bae Doona'],
+    },
+  },
+  children: formFields,
+};
+
+/** The form hosted in a modal by the `useModal` hook. */
+export const Default: StoryObj<ModalFormStoryType> = {
+  args: defaultArgs,
+  render: (args) =>
+    React.createElement(() => {
+      const { ModalWrapper, openModal } = useModal(({ closeModal }) => (
+        <ModalForm<MovieValues> {...args} closeModal={closeModal} />
+      ));
+
+      return (
+        <div>
+          <TextButton text="Edit Movie" onButtonClicked={openModal} />
+          <ModalWrapper />
+        </div>
+      );
+    }),
+};
+
+/** The same form, set up with the `useModalForm` hook instead. */
+export const WithUseModalForm: StoryObj<ModalFormStoryType> = {
+  args: defaultArgs,
+  render: (args) =>
+    React.createElement(() => {
+      const { ModalWrapper, openModal } = useModalForm<MovieValues>(args);
+
+      return (
+        <div>
+          <TextButton text="Edit Movie" onButtonClicked={openModal} />
+          <ModalWrapper />
+        </div>
+      );
+    }),
+};
+
+/** A failing save keeps the modal open and shows the error on the form. */
+export const SaveFailing: StoryObj<ModalFormStoryType> = {
+  args: {
+    ...defaultArgs,
+    saveData: () => {
+      throw {
+        title: 'Unable to save the movie.',
+        body: 'The service did not respond. Please try again later.',
+      };
+    },
+  },
+  render: (args) =>
+    React.createElement(() => {
+      const { ModalWrapper, openModal } = useModalForm<MovieValues>(args);
+
+      return (
+        <div>
+          <TextButton text="Edit Movie" onButtonClicked={openModal} />
+          <ModalWrapper />
+        </div>
+      );
+    }),
+};
+
+/** A narrower form, requested with the `width` prop. */
+export const CustomWidth: StoryObj<ModalFormStoryType> = {
+  args: {
+    ...defaultArgs,
+    title: 'Add Genre',
+    subtitle: undefined,
+    width: '800px',
+    validationSchema: Yup.object<ObjectSchemaDefinition<MovieValues>>({
+      title: Yup.string().required().max(25).label('Title'),
+    }),
+    initialData: { loading: false, data: { title: '' } },
+    children: <Field name="title" label="Title" as={SingleLineTextField} />,
+  },
+  render: (args) =>
+    React.createElement(() => {
+      const { ModalWrapper, openModal } = useModalForm<MovieValues>(args);
+
+      return (
+        <div>
+          <TextButton text="Add Genre" onButtonClicked={openModal} />
+          <ModalWrapper />
+        </div>
+      );
+    }),
+};