@douglasneuroinformatics/libui 2.5.3 → 2.6.1

package/src/components/Form/BooleanField/BooleanField.stories.tsx

@@ -0,0 +1,49 @@
+import React, { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { BooleanField } from './BooleanField.js';
+
+type Story = StoryObj<typeof BooleanField>;
+
+export default { component: BooleanField } as Meta<typeof BooleanField>;
+
+export const Radio: Story = {
+  decorators: [
+    (Story) => {
+      const [value, setValue] = useState<boolean | undefined>();
+      return (
+        <Story
+          args={{
+            description: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
+            label: 'Boolean Field',
+            name: 'boolean',
+            setValue,
+            value,
+            variant: 'radio'
+          }}
+        />
+      );
+    }
+  ]
+};
+
+export const Checkbox: Story = {
+  decorators: [
+    (Story) => {
+      const [value, setValue] = useState<boolean | undefined>(false);
+      return (
+        <Story
+          args={{
+            description: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
+            label: 'Boolean Field',
+            name: 'boolean',
+            setValue,
+            value,
+            variant: 'checkbox'
+          }}
+        />
+      );
+    }
+  ]
+};

package/src/components/Form/DateField/DateField.spec.tsx

@@ -0,0 +1,99 @@
+import React from 'react';
+
+import { toBasicISOString } from '@douglasneuroinformatics/libjs';
+import { getByText, render, screen } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { DateField } from './DateField.js';
+
+describe('DateField', () => {
+  const setError = vi.fn();
+  const setValue = vi.fn();
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should render an input with an empty string value ', () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    expect(input).toBeInTheDocument();
+    expect(input.value).toBe('');
+  });
+  it('should allow typing arbitrary text while focused', async () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    await userEvent.type(input, 'foo');
+    expect(input.value).toBe('foo');
+  });
+  it('should not initially show the datepicker', () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    expect(() => screen.getByTestId('datepicker')).toThrow();
+  });
+  it('should show the datepicker when the input is clicked', async () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input = screen.getByRole('textbox');
+    expect(() => screen.getByTestId('datepicker')).toThrow();
+    await userEvent.click(input);
+    expect(screen.getByTestId('datepicker')).toBeInTheDocument();
+  });
+  it('should discard invalid text when unfocused, once the date picker is closed', async () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    await userEvent.type(input, 'foo');
+    expect(input.value).toBe('foo');
+    const datepicker = screen.getByTestId('datepicker');
+    await userEvent.click(datepicker);
+    expect(datepicker).toBeInTheDocument();
+    await userEvent.type(input, 'foo');
+    await userEvent.click(screen.getByText('Date'));
+    expect(() => screen.getByTestId('datepicker')).toThrow();
+    expect(input.value).toBe('');
+  });
+  it('should not attempt to set the value if the date is invalid', async () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    await userEvent.type(input, 'foo');
+    expect(input.value).toBe('foo');
+    await userEvent.click(screen.getByText('Date'));
+    expect(input.value).toBe('');
+    expect(setValue).not.toHaveBeenCalled();
+  });
+  it('should attempt to set the value if the user enters a correct date', async () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    await userEvent.type(input, '2000-01-01');
+    await userEvent.click(screen.getByText('Date'));
+    expect(input.value).toBe('2000-01-01');
+    expect(setValue).toHaveBeenCalledOnce();
+    expect(setValue).toHaveBeenCalledWith(new Date('2000-01-01'));
+  });
+  it('should allow setting the date using the date picker', async () => {
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={undefined} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    let datepicker: HTMLElement;
+    let expectedDate: Date;
+    let expectedDateString: string;
+
+    await userEvent.click(input);
+    datepicker = screen.getByTestId('datepicker');
+    await userEvent.click(getByText(datepicker, '1'));
+    expectedDate = new Date(new Date().setDate(1));
+    expectedDateString = toBasicISOString(expectedDate);
+    expect(toBasicISOString(setValue.mock.lastCall[0])).toBe(expectedDateString);
+
+    await userEvent.click(input);
+    datepicker = screen.getByTestId('datepicker');
+    await userEvent.click(getByText(datepicker, '2'));
+    expectedDate = new Date(new Date().setDate(2));
+    expectedDateString = toBasicISOString(expectedDate);
+    expect(toBasicISOString(setValue.mock.lastCall[0])).toBe(expectedDateString);
+  });
+  it('should render the value provided as a prop', () => {
+    const today = new Date();
+    render(<DateField label="Date" name="date" setError={setError} setValue={setValue} value={today} />);
+    const input: HTMLInputElement = screen.getByRole('textbox');
+    expect(input.value).toBe(toBasicISOString(today));
+  });
+});

package/src/components/Form/DateField/DateField.stories.tsx

@@ -0,0 +1,28 @@
+import React, { useState } from 'react';
+
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { DateField } from './DateField.js';
+
+type Story = StoryObj<typeof DateField>;
+
+export default { component: DateField } as Meta<typeof DateField>;
+
+export const Default: Story = {
+  decorators: [
+    (Story) => {
+      const [value, setValue] = useState<Date | undefined>();
+      return (
+        <Story
+          args={{
+            description: 'Lorem ipsum dolor sit amet consectetur adipisicing elit.',
+            label: 'Date of Birth',
+            name: 'date-of-birth',
+            setValue,
+            value
+          }}
+        />
+      );
+    }
+  ]
+};

package/src/components/Form/Form.stories.tsx

@@ -0,0 +1,360 @@
+/* eslint-disable perfectionist/sort-objects */
+
+import React from 'react';
+
+import type { FormFields } from '@douglasneuroinformatics/libui-form-types';
+import type { Meta, StoryObj } from '@storybook/react';
+import { z } from 'zod';
+
+import { Heading } from '../Heading/Heading.js';
+import { Form } from './Form.js';
+
+const $ExampleFormData = z.object({
+  booleanCheck: z.boolean().optional(),
+  booleanRadio: z.boolean().optional(),
+  recordArray: z.array(
+    z.object({
+      recordArrayStringInput: z.string().optional(),
+      showRecordArrayDynamicField: z.boolean().optional(),
+      recordArrayDynamicField: z.string().optional()
+    })
+  ),
+  date: z.date().optional(),
+  numberInput: z.number().optional(),
+  numberSlider: z.number().optional(),
+  numberRecord: z.record(z.number()),
+  numberRadio: z.number().min(1).max(5).int().optional(),
+  numberSelect: z.number().min(1).max(5).int().optional(),
+  stringSelect: z.enum(['a', 'b', 'c']).optional(),
+  setListbox: z.set(z.enum(['a', 'b', 'c', 'd'])).optional(),
+  setSelect: z.set(z.enum(['a', 'b', 'c', 'd'])).optional(),
+  showDynamicField: z.boolean().optional(),
+  dynamicField: z.string().optional(),
+  stringTextArea: z.string().optional(),
+  stringPassword: z.string().optional(),
+  stringInput: z.string().optional(),
+  stringRadio: z.enum(['a', 'b', 'c']).optional()
+});
+type ExampleFormSchemaType = typeof $ExampleFormData;
+type ExampleFormData = z.TypeOf<typeof $ExampleFormData>;
+
+export default {
+  component: Form,
+  decorators: [
+    (Story) => (
+      <div className="container mx-auto max-w-5xl">
+        <Heading className="my-8 text-center" variant="h1">
+          Example Form
+        </Heading>
+        <Story />
+      </div>
+    )
+  ],
+  tags: ['autodocs']
+} as Meta<typeof Form>;
+
+const booleanFields: FormFields<Pick<ExampleFormData, 'booleanCheck' | 'booleanRadio'>> = {
+  booleanRadio: {
+    kind: 'boolean',
+    label: 'Radio',
+    variant: 'radio'
+  },
+  booleanCheck: {
+    kind: 'boolean',
+    label: 'Checkbox',
+    variant: 'checkbox'
+  }
+};
+
+const dateFields: FormFields<Pick<ExampleFormData, 'date'>> = {
+  date: {
+    kind: 'date',
+    label: 'Datepicker (Default)'
+  }
+};
+
+const numberFields: FormFields<Pick<ExampleFormData, 'numberInput' | 'numberRadio' | 'numberSelect' | 'numberSlider'>> =
+  {
+    numberInput: {
+      description: 'This is a number field',
+      kind: 'number',
+      label: 'Input',
+      max: 10,
+      min: 0,
+      variant: 'input'
+    },
+    numberRadio: {
+      description: 'This is a number field',
+      kind: 'number',
+      variant: 'radio',
+      label: 'Radio',
+      options: {
+        1: 'Very Low',
+        2: 'Low',
+        3: 'Medium',
+        4: 'High',
+        5: 'Very High'
+      }
+    },
+    numberSlider: {
+      description: 'This is a number field',
+      kind: 'number',
+      label: 'Slider',
+      max: 10,
+      min: 0,
+      variant: 'slider'
+    },
+    numberSelect: {
+      description: 'This is a number field',
+      kind: 'number',
+      variant: 'select',
+      label: 'Select',
+      options: {
+        1: 'Very Low',
+        2: 'Low',
+        3: 'Medium',
+        4: 'High',
+        5: 'Very High'
+      }
+    }
+  };
+
+const setFields: FormFields<Pick<ExampleFormData, 'setListbox' | 'setSelect'>> = {
+  setListbox: {
+    kind: 'set',
+    label: 'Listbox',
+    options: {
+      a: 'Option A',
+      b: 'Option B',
+      c: 'Option C',
+      d: 'Option D'
+    },
+    variant: 'listbox'
+  },
+  setSelect: {
+    kind: 'set',
+    label: 'Select',
+    options: {
+      a: 'Option A',
+      b: 'Option B',
+      c: 'Option C',
+      d: 'Option D'
+    },
+    variant: 'select'
+  }
+};
+
+const stringFields: FormFields<
+  Pick<ExampleFormData, 'stringInput' | 'stringPassword' | 'stringRadio' | 'stringSelect' | 'stringTextArea'>
+> = {
+  stringSelect: {
+    kind: 'string',
+    label: 'Select',
+    options: {
+      a: 'Option A',
+      b: 'Option B',
+      c: 'Option C'
+    },
+    variant: 'select'
+  },
+  stringTextArea: {
+    kind: 'string',
+    label: 'Text Area',
+    variant: 'textarea'
+  },
+  stringPassword: {
+    kind: 'string',
+    label: 'Password',
+    variant: 'password'
+  },
+  stringInput: {
+    description: 'This is a string field',
+    kind: 'string',
+    label: 'Input',
+    variant: 'input'
+  },
+  stringRadio: {
+    kind: 'string',
+    label: 'Radio',
+    options: {
+      a: 'Option A',
+      b: 'Option B',
+      c: 'Option C'
+    },
+    variant: 'radio'
+  }
+};
+
+const dynamicFields: FormFields<Pick<ExampleFormData, 'dynamicField' | 'showDynamicField'>> = {
+  showDynamicField: {
+    kind: 'boolean',
+    label: 'Show Dynamic Field?',
+    variant: 'checkbox'
+  },
+  dynamicField: {
+    kind: 'dynamic',
+    deps: ['showDynamicField'],
+    render(data) {
+      if (!data?.showDynamicField) {
+        return null;
+      }
+      return {
+        kind: 'string',
+        label: 'Dynamic Field',
+        variant: 'input'
+      };
+    }
+  }
+};
+
+const numberRecordFields: FormFields<Pick<ExampleFormData, 'numberRecord'>> = {
+  numberRecord: {
+    kind: 'number-record',
+    label: 'Number Record',
+    items: {
+      q1: {
+        label: 'Question 1'
+      },
+      q2: {
+        label: 'Question 2'
+      },
+      q3: {
+        label: 'Question 3'
+      }
+    },
+    options: {
+      1: 'Very Low',
+      2: 'Low',
+      3: 'Medium',
+      4: 'High',
+      5: 'Very High'
+    },
+    variant: 'likert'
+  }
+};
+
+const recordArrayFields: FormFields<Pick<ExampleFormData, 'recordArray'>> = {
+  recordArray: {
+    description: 'This is a record-array field',
+    kind: 'record-array',
+    label: 'Record Array',
+    fieldset: {
+      recordArrayStringInput: {
+        kind: 'string',
+        label: 'String',
+        variant: 'input'
+      },
+      showRecordArrayDynamicField: {
+        kind: 'boolean',
+        label: 'Show Dynamic Field',
+        variant: 'radio'
+      },
+      recordArrayDynamicField: {
+        kind: 'dynamic',
+        render(fieldset) {
+          if (!fieldset.showRecordArrayDynamicField) {
+            return null;
+          }
+          return {
+            kind: 'string',
+            label: 'Dynamic Field',
+            variant: 'input'
+          };
+        }
+      }
+    }
+  }
+};
+
+const ungroupedContent = {
+  ...booleanFields,
+  ...dateFields,
+  ...numberFields,
+  ...setFields,
+  ...stringFields,
+  ...dynamicFields,
+  ...numberRecordFields,
+  ...recordArrayFields
+} as const;
+
+export const Grouped: StoryObj<typeof Form<ExampleFormSchemaType>> = {
+  args: {
+    content: [
+      {
+        title: 'Boolean',
+        description: "The following variants are available for 'boolean' fields",
+        fields: booleanFields
+      },
+      {
+        title: 'Date',
+        description: `The following variants are available for 'date' fields`,
+        fields: dateFields
+      },
+      {
+        title: 'Number',
+        description: `The following variants are available for 'number' fields`,
+        fields: numberFields
+      },
+      {
+        title: 'Set',
+        description: `The following variants are available for 'set' fields`,
+        fields: setFields
+      },
+      {
+        title: 'String',
+        description: `The following variants are available for 'string' fields`,
+        fields: stringFields
+      },
+      {
+        title: 'Dynamic',
+        description: `A 'dynamic' field may be used with any data type. For a given data type T, a dynamic field must define a render method that returns either a scalar field for type T, or null to indicate the field should not be shown to the user. The render function receives as its first and only argument the current values in the form, unless it is in the context of a record-array field, in which case it will receive the current value of the fieldset in which it is situated. To optimize performance, a dynamic field must specify an array of dependent fields, a change in which will trigger a rerender of the component.`,
+        fields: dynamicFields
+      },
+      {
+        title: 'Number Record',
+        fields: numberRecordFields
+      },
+      {
+        title: 'Record Array',
+        description: `A 'record-array' field is composed of an array of given set of fields (referred to as a fieldset). A fieldset may include any number of fields, which can be any scalar kind. However, only one fieldset may be defined for a single fieldset array field.`,
+        fields: recordArrayFields
+      }
+    ],
+    onSubmit: (data) => {
+      alert(JSON.stringify(data, (_key, value) => (value instanceof Set ? [...value] : (value as unknown)), 2));
+    },
+    validationSchema: $ExampleFormData
+  }
+};
+
+export const Ungrouped: StoryObj<typeof Form<ExampleFormSchemaType>> = {
+  args: {
+    content: ungroupedContent,
+    onSubmit: (data) => {
+      alert(JSON.stringify(data, (_key, value) => (value instanceof Set ? [...value] : (value as unknown)), 2));
+    },
+    validationSchema: $ExampleFormData
+  }
+};
+
+export const WithRequiredFields: StoryObj<typeof Form<ExampleFormSchemaType>> = {
+  args: {
+    content: ungroupedContent,
+    onSubmit: (data) => {
+      alert(JSON.stringify(data, (_key, value) => (value instanceof Set ? [...value] : (value as unknown)), 2));
+    },
+    revalidateOnBlur: true,
+    validationSchema: $ExampleFormData.required()
+  }
+};
+
+export const ReadOnly: StoryObj<typeof Form<ExampleFormSchemaType>> = {
+  args: {
+    content: ungroupedContent,
+    readOnly: true,
+    onSubmit: (data) => {
+      alert(JSON.stringify(data, (_key, value) => (value instanceof Set ? [...value] : (value as unknown)), 2));
+    },
+    validationSchema: $ExampleFormData
+  }
+};

package/src/components/Form/Form.test.tsx

@@ -0,0 +1,119 @@
+import React from 'react';
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { userEvent } from '@testing-library/user-event';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+
+import { Form } from './Form.js';
+
+describe('Form', () => {
+  const testid = 'test-form';
+  const onError = vi.fn();
+  const onSubmit = vi.fn();
+
+  describe('conditional rendering', () => {
+    beforeEach(() => {
+      render(
+        <Form
+          content={{
+            a: {
+              kind: 'boolean',
+              label: 'Field A',
+              variant: 'checkbox'
+            },
+            b: {
+              deps: ['a'],
+              kind: 'dynamic',
+              render: (data) => {
+                if (!data?.a) {
+                  return null;
+                }
+                return {
+                  kind: 'string',
+                  label: 'Field B',
+                  variant: 'input'
+                };
+              }
+            }
+          }}
+          data-testid={testid}
+          validationSchema={z
+            .object({
+              a: z.boolean().default(false),
+              b: z.string().optional()
+            })
+            .refine((data) => !data.a || data.b)}
+          onError={onError}
+          onSubmit={onSubmit}
+        />
+      );
+    });
+
+    afterEach(() => {
+      vi.clearAllMocks();
+    });
+
+    it('should render', () => {
+      expect(screen.getByTestId(testid)).toBeInTheDocument();
+    });
+
+    it('should initially display field a, but not field b', () => {
+      expect(screen.getByLabelText('Field A')).toBeInTheDocument();
+      expect(() => screen.getByLabelText('Field B')).toThrow();
+    });
+
+    it('should display field b after checking field a, then remove field b when a is unchecked', () => {
+      const a = screen.getByLabelText('Field A');
+      expect(a).toHaveAttribute('data-state', 'unchecked');
+      fireEvent.click(a);
+      expect(a).toHaveAttribute('data-state', 'checked');
+      expect(screen.getByLabelText('Field B')).toBeInTheDocument();
+      fireEvent.click(a);
+      expect(() => screen.getByLabelText('Field B')).toThrow();
+    });
+
+    it('should allow submitting the form if field A is not checked', async () => {
+      fireEvent.submit(screen.getByTestId(testid));
+      await waitFor(() => expect(onSubmit).toHaveBeenCalledOnce());
+      expect(onError).not.toBeCalled();
+    });
+
+    it('should not allow submitting the form if field A has been checked', async () => {
+      fireEvent.click(screen.getByLabelText('Field A'));
+      fireEvent.submit(screen.getByTestId(testid));
+      await waitFor(() => expect(onError).toHaveBeenCalledOnce());
+      expect(onSubmit).not.toHaveBeenCalled();
+    });
+
+    it('should allow submitting the form if field A has been checked and then unchecked', async () => {
+      const a = screen.getByLabelText('Field A');
+      expect(a).toHaveAttribute('data-state', 'unchecked');
+      fireEvent.click(a);
+      expect(a).toHaveAttribute('data-state', 'checked');
+      fireEvent.click(a);
+      expect(a).toHaveAttribute('data-state', 'unchecked');
+      fireEvent.submit(screen.getByTestId(testid));
+      await waitFor(() => expect(onSubmit).toHaveBeenCalledOnce());
+      expect(onError).not.toBeCalled();
+    });
+
+    it('should delete the data associated when field b when it is removed from the DOM', async () => {
+      const a = screen.getByLabelText('Field A');
+      fireEvent.click(a);
+      let b: HTMLInputElement = screen.getByLabelText('Field B');
+      await userEvent.type(b, 'TEST');
+      expect(b.value).toBe('TEST');
+      fireEvent.click(a);
+      expect(b).not.toBeInTheDocument();
+      fireEvent.click(a);
+      b = screen.getByLabelText('Field B');
+      expect(b).toBeInTheDocument();
+      expect(b.value).toBe('');
+      fireEvent.click(a);
+      fireEvent.submit(screen.getByTestId(testid));
+      await waitFor(() => expect(onSubmit).toHaveBeenCalledOnce());
+      expect(onSubmit.mock.lastCall[0].b).toBeUndefined();
+    });
+  });
+});