proje-react-panel 1.8.0 → 1.9.0

package/src/__tests__/optionalTiptap.test.tsx

@@ -0,0 +1,89 @@
+/**
+ * @jest-environment jsdom
+ */
+import 'reflect-metadata';
+import React from 'react';
+import { TextDecoder, TextEncoder } from 'util';
+import { beforeAll, describe, expect, it, jest } from '@jest/globals';
+import { render, screen, waitFor } from '@testing-library/react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { Input, getInputFields } from '../decorators/form/Input';
+import { RichTextInput } from '../decorators/form/inputs/RichTextInput';
+import { FormField } from '../components/form/FormField';
+
+// @tiptap/* is declared optional in peerDependenciesMeta, so a panel that never uses a richtext
+// field must work with the packages absent. Both are made unresolvable here; the flags record
+// whether anything reached for them at all.
+let reactRequested = false;
+let starterKitRequested = false;
+
+jest.mock('@tiptap/react', () => {
+  reactRequested = true;
+  throw new Error("Cannot find module '@tiptap/react'");
+});
+
+jest.mock('@tiptap/starter-kit', () => {
+  starterKitRequested = true;
+  throw new Error("Cannot find module '@tiptap/starter-kit'");
+});
+
+class PlainForm {
+  @Input({ label: 'Name' })
+  name: string;
+}
+
+class ArticleForm {
+  @RichTextInput({ label: 'Body' })
+  body: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function Harness({ model }: { model: any }) {
+  const form = useForm({ defaultValues: { name: '', body: '' } });
+  const inputs = getInputFields(model);
+  return (
+    <FormProvider {...form}>
+      {inputs.map(input => (
+        <FormField key={input.name} input={input} register={form.register} />
+      ))}
+    </FormProvider>
+  );
+}
+
+describe('@tiptap as an optional peer dependency', () => {
+  beforeAll(() => {
+    // jsdom ships neither; react-router reads them at import time. Nothing to do with tiptap.
+    Object.assign(globalThis, { TextEncoder, TextDecoder });
+  });
+
+  it('imports the whole library without @tiptap installed', async () => {
+    const library = await import('../index');
+
+    expect(typeof library.FormPage).toBe('function');
+    expect(typeof library.RichTextInput).toBe('function');
+    expect(typeof library.ListPage).toBe('function');
+    expect(reactRequested).toBe(false);
+    expect(starterKitRequested).toBe(false);
+  });
+
+  it('renders the other field types without @tiptap installed', () => {
+    render(<Harness model={PlainForm} />);
+
+    expect(screen.getByText('Name:')).toBeTruthy();
+    expect(reactRequested).toBe(false);
+  });
+
+  it('tells the developer what to install when a richtext field is actually used', async () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    render(<Harness model={ArticleForm} />);
+
+    const message = await screen.findByRole('alert');
+    expect(message.textContent).toContain('@tiptap/react');
+    expect(message.textContent).toContain('@tiptap/starter-kit');
+    await waitFor(() => expect(reactRequested).toBe(true));
+    expect(consoleError).toHaveBeenCalled();
+
+    consoleError.mockRestore();
+  });
+});

package/src/components/form/FormField.tsx

@@ -6,6 +6,9 @@ import { Checkbox } from './Checkbox';
 import { Label } from './Label';
 import { Select } from './Select';
 import { CustomField } from './CustomField';
+//NOTE: safe to import statically — RichTextField pulls the optional @tiptap/* peers in itself,
+// through a dynamic import, only once a richtext field is actually rendered.
+import { RichTextField } from './RichTextField';
 
 interface FormFieldProps {
   input: InputConfiguration;
@@ -80,9 +83,13 @@ export function FormField({ input, register, error, baseName }: FormFieldProps)
   const renderedField = useMemo(() => {
     switch (input.type) {
       case 'textarea':
-        return <textarea {...register(fieldName)} placeholder={input.placeholder} />;
+        return (
+          <textarea {...register(fieldName)} placeholder={input.placeholder} rows={input.rows} />
+        );
       case 'select':
         return <Select input={input} fieldName={fieldName} />;
+      case 'richtext':
+        return <RichTextField input={input} fieldName={fieldName} />;
       case 'custom':
         return <CustomField input={input} fieldName={fieldName} error={error?.message} />;
       case 'input': {

package/src/components/form/InnerForm.tsx

@@ -1,9 +1,9 @@
-import React, { useRef, useState } from 'react';
+import React, { useMemo, useRef, useState } from 'react';
 import { useFormContext } from 'react-hook-form';
 import { InputConfiguration } from '../../decorators/form/Input';
 import { FormField } from './FormField';
 import { useNavigate } from 'react-router';
-import { FormConfiguration } from '../../decorators/form/Form';
+import { FormConfiguration, FormGroup } from '../../decorators/form/Form';
 import { AnyClass } from '../../types/AnyClass';
 import { toast } from 'react-toastify';
 
@@ -12,6 +12,63 @@ interface InnerFormProps<T extends AnyClass> {
   formClass: FormConfiguration<T>;
 }
 
+interface GroupSection {
+  key: string;
+  label: string;
+  collapsible: boolean;
+  defaultCollapsed: boolean;
+  inputs: InputConfiguration[];
+}
+
+/**
+ * Splits the inputs into the fields rendered straight into the form and the grouped sections.
+ * With no `group` on any field every input stays ungrouped, so the markup is byte-for-byte what
+ * it was before groups existed — no stray fieldset around existing panels' CSS.
+ */
+function splitIntoGroups(
+  inputs: InputConfiguration[],
+  groups?: FormGroup[]
+): { ungrouped: InputConfiguration[]; sections: GroupSection[] } {
+  const ungrouped: InputConfiguration[] = [];
+  const inputsByGroup = new Map<string, InputConfiguration[]>();
+  const appearanceOrder: string[] = [];
+
+  inputs?.forEach(input => {
+    // Hidden fields carry no label and no layout; a fieldset around them would only add noise.
+    if (!input.group || input.type === 'hidden') {
+      ungrouped.push(input);
+      return;
+    }
+    if (!inputsByGroup.has(input.group)) {
+      inputsByGroup.set(input.group, []);
+      appearanceOrder.push(input.group);
+    }
+    inputsByGroup.get(input.group)!.push(input);
+  });
+
+  const declared = groups ?? [];
+  const declaredKeys = declared.map(group => group.key);
+  const orderedKeys = [
+    ...declaredKeys.filter(key => inputsByGroup.has(key)),
+    // A group nobody declared in @Form({ groups }) still renders — labelled with its own key,
+    // appended after the declared ones, in the order the fields introduced it.
+    ...appearanceOrder.filter(key => !declaredKeys.includes(key)),
+  ];
+
+  const sections = orderedKeys.map(key => {
+    const declaration = declared.find(group => group.key === key);
+    return {
+      key,
+      label: declaration?.label ?? key,
+      collapsible: declaration?.collapsible ?? false,
+      defaultCollapsed: declaration?.defaultCollapsed ?? false,
+      inputs: inputsByGroup.get(key)!,
+    };
+  });
+
+  return { ungrouped, sections };
+}
+
 export function InnerForm<T extends AnyClass>({ inputs, formClass }: InnerFormProps<T>) {
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
   //TODO: any is not a good solution, we need to find a better way to do this
@@ -19,6 +76,29 @@ export function InnerForm<T extends AnyClass>({ inputs, formClass }: InnerFormPr
   const navigate = useNavigate();
   const form = useFormContext<T>();
   const loadingRef = useRef(false);
+  const { ungrouped, sections } = useMemo(
+    () => splitIntoGroups(inputs, formClass.groups),
+    [inputs, formClass.groups]
+  );
+
+  const renderField = (input: InputConfiguration) => (
+    <FormField
+      key={input.name || ''}
+      input={input}
+      register={form.register}
+      error={
+        input.name
+          ? {
+              message: (
+                form.formState.errors[input.name as keyof T] as {
+                  message: string;
+                }
+              )?.message,
+            }
+          : undefined
+      }
+    />
+  );
 
   return (
     <form
@@ -75,23 +155,25 @@ export function InnerForm<T extends AnyClass>({ inputs, formClass }: InnerFormPr
             {errorMessage}
           </div>
         )}
-        {inputs?.map((input: InputConfiguration) => (
-          <FormField
-            key={input.name || ''}
-            input={input}
-            register={form.register}
-            error={
-              input.name
-                ? {
-                    message: (
-                      form.formState.errors[input.name as keyof T] as {
-                        message: string;
-                      }
-                    )?.message,
-                  }
-                : undefined
-            }
-          />
+        {ungrouped.map(renderField)}
+        {sections.map(section => (
+          <fieldset
+            key={section.key}
+            data-group={section.key}
+            className={`form-group-section${section.collapsible ? ' form-group-section-collapsible' : ''}`}
+          >
+            {section.collapsible ? (
+              <details open={!section.defaultCollapsed}>
+                <summary className="form-group-summary">{section.label}</summary>
+                <div className="form-group-fields">{section.inputs.map(renderField)}</div>
+              </details>
+            ) : (
+              <>
+                <legend className="form-group-legend">{section.label}</legend>
+                <div className="form-group-fields">{section.inputs.map(renderField)}</div>
+              </>
+            )}
+          </fieldset>
         ))}
         <button type="submit" className="submit-button">
           Submit

package/src/components/form/RichTextField.tsx

@@ -0,0 +1,218 @@
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { useController, useFormContext } from 'react-hook-form';
+import type { Editor } from '@tiptap/react';
+import { InputConfiguration } from '../../decorators/form/Input';
+import {
+  DEFAULT_RICH_TEXT_TOOLBAR,
+  RichTextInputConfiguration,
+  RichTextToolbarItem,
+} from '../../decorators/form/inputs/RichTextInput';
+
+const DEFAULT_MIN_HEIGHT = 160;
+
+export interface RichTextFieldProps {
+  input: InputConfiguration;
+  fieldName: string;
+}
+
+interface Tiptap {
+  react: typeof import('@tiptap/react');
+  starterKit: (typeof import('@tiptap/starter-kit'))['default'];
+}
+
+//NOTE: @tiptap/* is an optional peer dependency, so it may only be reached through a dynamic
+// import — a static one would put ~100kb (and a hard install requirement) on every panel,
+// including the ones that never declare a richtext field. The promise is cached at module level
+// so a form with several richtext fields loads the editor once.
+let tiptapPromise: Promise<Tiptap> | null = null;
+
+function loadTiptap(): Promise<Tiptap> {
+  if (!tiptapPromise) {
+    const pending = Promise.all([import('@tiptap/react'), import('@tiptap/starter-kit')]).then(
+      ([react, starterKit]) => ({ react, starterKit: starterKit.default })
+    );
+    // A failed load is not cached: a chunk that failed to arrive should be retried on the next
+    // mount instead of leaving the field broken for the rest of the session.
+    pending.catch(() => {
+      tiptapPromise = null;
+    });
+    tiptapPromise = pending;
+  }
+  return tiptapPromise;
+}
+
+interface ToolbarButton {
+  label: string;
+  title: string;
+  isActive: (editor: Editor) => boolean;
+  run: (editor: Editor) => void;
+}
+
+const TOOLBAR_BUTTONS: Record<RichTextToolbarItem, ToolbarButton> = {
+  bold: {
+    label: 'B',
+    title: 'Bold',
+    isActive: editor => editor.isActive('bold'),
+    run: editor => editor.chain().focus().toggleBold().run(),
+  },
+  italic: {
+    label: 'I',
+    title: 'Italic',
+    isActive: editor => editor.isActive('italic'),
+    run: editor => editor.chain().focus().toggleItalic().run(),
+  },
+  heading: {
+    label: 'H2',
+    title: 'Heading',
+    isActive: editor => editor.isActive('heading', { level: 2 }),
+    run: editor => editor.chain().focus().toggleHeading({ level: 2 }).run(),
+  },
+  bulletList: {
+    label: '••',
+    title: 'Bullet list',
+    isActive: editor => editor.isActive('bulletList'),
+    run: editor => editor.chain().focus().toggleBulletList().run(),
+  },
+  orderedList: {
+    label: '1.',
+    title: 'Numbered list',
+    isActive: editor => editor.isActive('orderedList'),
+    run: editor => editor.chain().focus().toggleOrderedList().run(),
+  },
+  link: {
+    label: '🔗',
+    title: 'Link',
+    isActive: editor => editor.isActive('link'),
+    run: editor => {
+      const current = editor.getAttributes('link').href as string | undefined;
+      const url = window.prompt('Link URL', current ?? 'https://');
+      //NOTE: null is "cancelled", empty string is "remove the link".
+      if (url === null) return;
+      if (url === '') {
+        editor.chain().focus().extendMarkRange('link').unsetLink().run();
+        return;
+      }
+      editor.chain().focus().extendMarkRange('link').setLink({ href: url }).run();
+    },
+  },
+};
+
+export function RichTextField({ input, fieldName }: RichTextFieldProps) {
+  const [tiptap, setTiptap] = useState<Tiptap | null>(null);
+  const [loadFailed, setLoadFailed] = useState(false);
+
+  useEffect(() => {
+    let active = true;
+    loadTiptap().then(
+      modules => {
+        if (active) setTiptap(modules);
+      },
+      (error: unknown) => {
+        console.error(
+          "proje-react-panel: a 'richtext' input needs @tiptap/react and @tiptap/starter-kit installed.",
+          error
+        );
+        if (active) setLoadFailed(true);
+      }
+    );
+    return () => {
+      active = false;
+    };
+  }, []);
+
+  if (loadFailed) {
+    return (
+      <div className="rich-text-missing" role="alert">
+        Rich text editor unavailable — install @tiptap/react and @tiptap/starter-kit.
+      </div>
+    );
+  }
+
+  if (!tiptap) {
+    return <div className="rich-text-loading">Loading editor…</div>;
+  }
+
+  return <RichTextEditor input={input} fieldName={fieldName} tiptap={tiptap} />;
+}
+
+function RichTextEditor({ input, fieldName, tiptap }: RichTextFieldProps & { tiptap: Tiptap }) {
+  const richInput = input as RichTextInputConfiguration;
+  // Hooks off a dynamically loaded module: safe because the module object is cached, so the
+  // hook identity never changes between renders of this component.
+  const { EditorContent, useEditor } = tiptap.react;
+  const { control } = useFormContext();
+  //NOTE: register() would bind the value to a DOM node; TipTap owns an uncontrolled
+  // contenteditable of its own, so the value goes through the controller instead.
+  const { field } = useController({ name: fieldName, control });
+  const toolbar = richInput.toolbar ?? DEFAULT_RICH_TEXT_TOOLBAR;
+  const incomingHtml = typeof field.value === 'string' ? field.value : '';
+
+  // The HTML the editor last emitted or received. The outside -> editor sync compares against
+  // this instead of the previous prop value: while the user types, react-hook-form hands our
+  // own HTML straight back, and calling setContent for that would jump the caret to the start.
+  const editorHtmlRef = useRef<string>(incomingHtml);
+
+  // onUpdate is captured when the editor is created; the ref keeps it pointed at the live handler.
+  const onChangeRef = useRef(field.onChange);
+  onChangeRef.current = field.onChange;
+
+  const editor = useEditor({
+    extensions: [tiptap.starterKit],
+    content: editorHtmlRef.current,
+    //NOTE: toolbar highlighting reads editor state, so the field has to re-render with it.
+    shouldRerenderOnTransaction: true,
+    onUpdate: ({ editor: updatedEditor }) => {
+      // An empty document still serializes to '<p></p>'; report it as empty so required
+      // validators (@IsNotEmpty and friends) see what the user actually sees.
+      const html = updatedEditor.isEmpty ? '' : updatedEditor.getHTML();
+      editorHtmlRef.current = html;
+      onChangeRef.current(html);
+    },
+  });
+
+  useEffect(() => {
+    if (!editor) return;
+    // getDetailsData resolves after the form mounts, so the value can arrive late — but only
+    // replace the document when it really differs from what the editor already holds.
+    if (incomingHtml === editorHtmlRef.current) return;
+    editorHtmlRef.current = incomingHtml;
+    editor.commands.setContent(incomingHtml, { emitUpdate: false });
+  }, [editor, incomingHtml]);
+
+  const buttons = useMemo(
+    () => toolbar.map(item => ({ item, ...TOOLBAR_BUTTONS[item] })),
+    [toolbar]
+  );
+
+  return (
+    <div className="rich-text-field">
+      <div className="rich-text-toolbar" role="toolbar" aria-label={`${input.label ?? fieldName}`}>
+        {buttons.map(button => {
+          const active = editor ? button.isActive(editor) : false;
+          return (
+            <button
+              key={button.item}
+              type="button"
+              title={button.title}
+              aria-label={button.title}
+              aria-pressed={active}
+              disabled={!editor}
+              className={`rich-text-toolbar-button${active ? ' is-active' : ''}`}
+              onClick={() => editor && button.run(editor)}
+            >
+              {button.label}
+            </button>
+          );
+        })}
+      </div>
+      <EditorContent
+        editor={editor}
+        id={fieldName}
+        data-testid={`rich-text-${fieldName}`}
+        data-placeholder={input.placeholder}
+        className={`rich-text-content${!editor || editor.isEmpty ? ' is-empty' : ''}`}
+        style={{ minHeight: `${richInput.minHeight ?? DEFAULT_MIN_HEIGHT}px` }}
+      />
+    </div>
+  );
+}

package/src/decorators/form/Form.ts

@@ -5,12 +5,21 @@ import { GetDetailsDataFN } from '../details/Details';
 const DETAILS_METADATA_KEY = 'DetailsMetaData';
 export type OnSubmitFN<T, L = T> = (data: T | FormData) => Promise<L>;
 
+export interface FormGroup {
+  key: string;
+  label: string;
+  collapsible?: boolean;
+  defaultCollapsed?: boolean;
+}
+
 interface FormOptions<T extends AnyClass, L = T> {
   onSubmit: OnSubmitFN<T, L>;
   onSubmitSuccess?: (data: L) => void;
   getDetailsData?: GetDetailsDataFN<T>;
   type?: 'json' | 'formData';
   redirectSuccessUrl?: string;
+  //NOTE: declares the section headings and their order; fields opt in with @Input({ group }).
+  groups?: FormGroup[];
 }
 
 export interface FormConfiguration<T extends AnyClass, L = T> {
@@ -19,6 +28,7 @@ export interface FormConfiguration<T extends AnyClass, L = T> {
   getDetailsData?: GetDetailsDataFN<T>;
   type: 'json' | 'formData';
   redirectSuccessUrl?: string;
+  groups?: FormGroup[];
 }
 
 export function Form<T extends AnyClass, L = T>(options?: FormOptions<T, L>): ClassDecorator {
@@ -45,6 +55,7 @@ export function getFormConfiguration<T extends AnyClass, K extends AnyClassConst
     getDetailsData: formOptions.getDetailsData,
     type: formOptions.type ?? 'json',
     redirectSuccessUrl: formOptions.redirectSuccessUrl,
+    groups: formOptions.groups,
   };
   return formConfiguration;
 }

package/src/decorators/form/Input.ts

@@ -8,7 +8,7 @@ const isFieldSensitive = (fieldName: string): boolean => {
 };
 
 export type InputTypes = 'input' | 'textarea' | 'file-upload' | 'checkbox' | 'hidden' | 'nested';
-export type ExtendedInputTypes = InputTypes | 'select' | 'custom';
+export type ExtendedInputTypes = InputTypes | 'select' | 'custom' | 'richtext';
 
 export interface InputOptions {
   type?: InputTypes;
@@ -19,6 +19,9 @@ export interface InputOptions {
   defaultValue?: string;
   includeInCSV?: boolean;
   includeInJSON?: boolean;
+  //NOTE: the visual section this field belongs to, matched against @Form({ groups }) by key.
+  group?: string;
+  rows?: number;
 }
 
 export interface ExtendedInputOptions extends Omit<InputOptions, 'type'> {
@@ -36,6 +39,8 @@ export interface InputConfiguration {
   defaultValue?: string;
   includeInCSV: boolean;
   includeInJSON: boolean;
+  group?: string;
+  rows?: number;
 }
 
 export function Input(options?: InputOptions): PropertyDecorator {

package/src/decorators/form/inputs/RichTextInput.ts

@@ -0,0 +1,38 @@
+import { ExtendedInput, ExtendedInputOptions, InputConfiguration, InputOptions } from '../Input';
+
+export type RichTextToolbarItem =
+  | 'bold'
+  | 'italic'
+  | 'heading'
+  | 'bulletList'
+  | 'orderedList'
+  | 'link';
+
+export const DEFAULT_RICH_TEXT_TOOLBAR: RichTextToolbarItem[] = [
+  'bold',
+  'italic',
+  'heading',
+  'bulletList',
+  'orderedList',
+  'link',
+];
+
+export interface RichTextInputOptions extends InputOptions {
+  toolbar?: RichTextToolbarItem[];
+  minHeight?: number;
+}
+
+export interface RichTextInputConfiguration extends InputConfiguration {
+  type: 'richtext';
+  toolbar?: RichTextToolbarItem[];
+  minHeight?: number;
+}
+
+//NOTE: the editor itself lives behind a lazy import in FormField, because @tiptap/* is an
+// optional peer dependency — this decorator is safe to import without it installed.
+export function RichTextInput(options?: RichTextInputOptions): PropertyDecorator {
+  return ExtendedInput({
+    ...options,
+    type: 'richtext',
+  } as ExtendedInputOptions);
+}

package/src/index.ts

@@ -18,9 +18,16 @@ export { LinkCell } from './decorators/list/cells/LinkCell';
 
 //FORM
 export { FormPage } from './components/form/FormPage';
-export { Form, type OnSubmitFN } from './decorators/form/Form';
+export { Form, type OnSubmitFN, type FormGroup } from './decorators/form/Form';
 export { Input } from './decorators/form/Input';
 export { SelectInput } from './decorators/form/inputs/SelectInput';
+export {
+  RichTextInput,
+  DEFAULT_RICH_TEXT_TOOLBAR,
+  type RichTextInputOptions,
+  type RichTextInputConfiguration,
+  type RichTextToolbarItem,
+} from './decorators/form/inputs/RichTextInput';
 export {
   CustomInput,
   type CustomInputOptions,