proje-react-panel 1.7.0 → 1.9.0

package/src/__tests__/components/form/FormGroups.test.tsx

@@ -0,0 +1,194 @@
+/**
+ * @jest-environment jsdom
+ */
+import { TextDecoder, TextEncoder } from 'util';
+// react-router reads TextEncoder at import time and jsdom has none — set it up before the
+// imports below pull the router in.
+Object.assign(globalThis, { TextEncoder, TextDecoder });
+
+import 'reflect-metadata';
+import React from 'react';
+import { describe, expect, it } from '@jest/globals';
+import { render } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import { FormProvider, useForm } from 'react-hook-form';
+import { Input, getInputFields } from '../../../decorators/form/Input';
+import { Form, getFormConfiguration } from '../../../decorators/form/Form';
+import { InnerForm } from '../../../components/form/InnerForm';
+import { AnyClass } from '../../../types/AnyClass';
+
+const onSubmit = async () => ({});
+
+@Form({ onSubmit })
+class UngroupedForm {
+  @Input({ label: 'Name' })
+  name: string;
+
+  @Input({ label: 'Slug' })
+  slug: string;
+
+  @Input({ type: 'textarea', label: 'Summary', rows: 6 })
+  summary: string;
+
+  @Input({ type: 'hidden' })
+  id: string;
+}
+
+@Form({
+  onSubmit,
+  groups: [
+    { key: 'content', label: 'Content' },
+    { key: 'seo', label: 'SEO', collapsible: true },
+    { key: 'advanced', label: 'Advanced', collapsible: true, defaultCollapsed: true },
+    // Declared but never used by a field — it must not produce an empty fieldset.
+    { key: 'unused', label: 'Unused' },
+  ],
+})
+class GroupedForm {
+  @Input({ label: 'Title', group: 'content' })
+  title: string;
+
+  @Input({ label: 'Meta title', group: 'seo' })
+  metaTitle: string;
+
+  @Input({ label: 'Body', group: 'content' })
+  body: string;
+
+  @Input({ label: 'Cache key', group: 'advanced' })
+  cacheKey: string;
+
+  // No group at all: stays outside every fieldset.
+  @Input({ label: 'Name' })
+  name: string;
+
+  // Hidden fields never belong to a section, even when they ask for one.
+  @Input({ type: 'hidden', group: 'content' })
+  id: string;
+}
+
+@Form({
+  onSubmit,
+  groups: [{ key: 'content', label: 'Content' }],
+})
+class UndeclaredGroupForm {
+  @Input({ label: 'Notes', group: 'internal' })
+  notes: string;
+
+  @Input({ label: 'Title', group: 'content' })
+  title: string;
+}
+
+function renderForm<T extends AnyClass>(model: new () => T) {
+  const inputs = getInputFields(model as never);
+  const formClass = getFormConfiguration(model as never);
+
+  function Harness() {
+    const form = useForm();
+    return (
+      <MemoryRouter>
+        <FormProvider {...form}>
+          <InnerForm inputs={inputs} formClass={formClass} />
+        </FormProvider>
+      </MemoryRouter>
+    );
+  }
+
+  return render(<Harness />);
+}
+
+const labelsOf = (root: ParentNode) =>
+  Array.from(root.querySelectorAll('.form-field .label span')).map(node => node.textContent);
+
+describe('form field groups', () => {
+  it('leaves a form without groups exactly as it was', () => {
+    const { container } = renderForm(UngroupedForm);
+
+    expect(container.querySelectorAll('fieldset').length).toBe(0);
+    expect(container.querySelectorAll('details').length).toBe(0);
+    expect(labelsOf(container)).toEqual(['Name:', 'Slug:', 'Summary:']);
+
+    // Every field is still a direct child of the form's single wrapper div, in source order.
+    const fields = Array.from(container.querySelectorAll('.form-field'));
+    const wrapper = container.querySelector('form > div');
+    expect(fields.length).toBe(4);
+    fields.forEach(field => expect(field.parentElement).toBe(wrapper));
+    expect(fields[3].querySelector('input')?.getAttribute('type')).toBe('hidden');
+  });
+
+  it('honours rows on a textarea', () => {
+    const { container } = renderForm(UngroupedForm);
+
+    expect(container.querySelector('textarea')?.getAttribute('rows')).toBe('6');
+  });
+
+  it('puts each field in the fieldset its group names', () => {
+    const { container } = renderForm(GroupedForm);
+
+    expect(labelsOf(container.querySelector('fieldset[data-group="content"]')!)).toEqual([
+      'Title:',
+      'Body:',
+    ]);
+    expect(labelsOf(container.querySelector('fieldset[data-group="seo"]')!)).toEqual([
+      'Meta title:',
+    ]);
+    expect(labelsOf(container.querySelector('fieldset[data-group="advanced"]')!)).toEqual([
+      'Cache key:',
+    ]);
+  });
+
+  it('orders the fieldsets like @Form({ groups }) does and skips the empty ones', () => {
+    const { container } = renderForm(GroupedForm);
+
+    const groups = Array.from(container.querySelectorAll('fieldset')).map(fieldset =>
+      fieldset.getAttribute('data-group')
+    );
+    expect(groups).toEqual(['content', 'seo', 'advanced']);
+  });
+
+  it('labels a non-collapsible group with a legend', () => {
+    const { container } = renderForm(GroupedForm);
+
+    const content = container.querySelector('fieldset[data-group="content"]')!;
+    expect(content.querySelector('legend')?.textContent).toBe('Content');
+    expect(content.querySelector('details')).toBeNull();
+  });
+
+  it('renders collapsible groups as details/summary and honours defaultCollapsed', () => {
+    const { container } = renderForm(GroupedForm);
+
+    const seo = container.querySelector('fieldset[data-group="seo"] details') as HTMLDetailsElement;
+    const advanced = container.querySelector(
+      'fieldset[data-group="advanced"] details'
+    ) as HTMLDetailsElement;
+
+    expect(seo.querySelector('summary')?.textContent).toBe('SEO');
+    expect(seo.open).toBe(true);
+    expect(advanced.open).toBe(false);
+  });
+
+  it('keeps ungrouped and hidden fields outside every fieldset', () => {
+    const { container } = renderForm(GroupedForm);
+
+    const wrapper = container.querySelector('form > div')!;
+    const directFields = Array.from(wrapper.children).filter(child =>
+      child.classList.contains('form-field')
+    );
+
+    expect(directFields.length).toBe(2);
+    expect(directFields[0].querySelector('.label span')?.textContent).toBe('Name:');
+    expect(directFields[1].querySelector('input')?.getAttribute('type')).toBe('hidden');
+    expect(container.querySelector('fieldset input[type="hidden"]')).toBeNull();
+  });
+
+  it('appends a group nobody declared at the end, labelled with its key', () => {
+    const { container } = renderForm(UndeclaredGroupForm);
+
+    const groups = Array.from(container.querySelectorAll('fieldset')).map(fieldset =>
+      fieldset.getAttribute('data-group')
+    );
+    expect(groups).toEqual(['content', 'internal']);
+    expect(container.querySelector('fieldset[data-group="internal"] legend')?.textContent).toBe(
+      'internal'
+    );
+  });
+});

package/src/__tests__/components/form/RichTextField.test.tsx

@@ -0,0 +1,181 @@
+/**
+ * @jest-environment jsdom
+ */
+import 'reflect-metadata';
+import React from 'react';
+import { describe, expect, it, beforeEach, jest } from '@jest/globals';
+import { act, render, screen, waitFor } from '@testing-library/react';
+import { FormProvider, useForm, UseFormReturn } from 'react-hook-form';
+import { getInputFields } from '../../../decorators/form/Input';
+import { RichTextInput } from '../../../decorators/form/inputs/RichTextInput';
+import { FormField } from '../../../components/form/FormField';
+
+// The real editor is kept — only its instance is captured, so the assertions below run against
+// actual ProseMirror state (document, selection) instead of a stand-in.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let capturedEditor: any = null;
+
+jest.mock('@tiptap/react', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const actual = jest.requireActual('@tiptap/react') as any;
+  return {
+    ...actual,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    useEditor: (...args: any[]) => {
+      const editor = actual.useEditor(...args);
+      capturedEditor = editor;
+      return editor;
+    },
+  };
+});
+
+class ArticleForm {
+  @RichTextInput({ label: 'Body', placeholder: 'Write something…' })
+  body: string;
+}
+
+class ToolbarForm {
+  @RichTextInput({ label: 'Body', toolbar: ['bold', 'italic'] })
+  body: string;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let form: UseFormReturn<any>;
+
+function Harness({
+  model = ArticleForm,
+  defaultValue = '',
+}: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model?: any;
+  defaultValue?: string;
+}) {
+  form = useForm({ defaultValues: { body: defaultValue } });
+  const inputs = getInputFields(model);
+  return (
+    <FormProvider {...form}>
+      {inputs.map(input => (
+        <FormField key={input.name} input={input} register={form.register} />
+      ))}
+    </FormProvider>
+  );
+}
+
+async function renderEditor(props: Parameters<typeof Harness>[0] = {}) {
+  const utils = render(<Harness {...props} />);
+  // The editor is behind a lazy import (optional peer dependency), so it lands a tick later.
+  await screen.findByTestId('rich-text-body');
+  await waitFor(() => expect(capturedEditor).not.toBeNull());
+  return utils;
+}
+
+function typeIntoEditor(text: string) {
+  act(() => {
+    capturedEditor.commands.insertContent(text);
+  });
+}
+
+describe('RichTextInput', () => {
+  beforeEach(() => {
+    capturedEditor = null;
+  });
+
+  it('marks the field as richtext in the metadata', () => {
+    const body = getInputFields(ArticleForm).find(input => input.name === 'body');
+
+    expect(body?.type).toBe('richtext');
+  });
+
+  it('mounts with the HTML it is given as a value', async () => {
+    await renderEditor({ defaultValue: '<p>kayıtlı içerik</p>' });
+
+    expect(capturedEditor.getHTML()).toBe('<p>kayıtlı içerik</p>');
+    expect(screen.getByTestId('rich-text-body').textContent).toContain('kayıtlı içerik');
+  });
+
+  it('shows the placeholder while the document is empty', async () => {
+    await renderEditor();
+
+    const content = screen.getByTestId('rich-text-body');
+    expect(content.className).toContain('is-empty');
+    expect(content.getAttribute('data-placeholder')).toBe('Write something…');
+  });
+
+  it('writes the edited HTML into the form value', async () => {
+    await renderEditor();
+
+    typeIntoEditor('merhaba');
+
+    await waitFor(() => expect(form.getValues('body')).toBe('<p>merhaba</p>'));
+    expect(screen.getByTestId('rich-text-body').className).not.toContain('is-empty');
+  });
+
+  it('reports an emptied editor as an empty value, not as <p></p>', async () => {
+    await renderEditor({ defaultValue: '<p>silinecek</p>' });
+
+    act(() => {
+      capturedEditor.commands.clearContent(true);
+    });
+
+    await waitFor(() => expect(form.getValues('body')).toBe(''));
+  });
+
+  it('syncs content that arrives after mount (getDetailsData)', async () => {
+    await renderEditor();
+
+    act(() => {
+      form.setValue('body', '<p>sunucudan gelen</p>');
+    });
+
+    await waitFor(() => expect(capturedEditor.getHTML()).toBe('<p>sunucudan gelen</p>'));
+    expect(screen.getByTestId('rich-text-body').textContent).toContain('sunucudan gelen');
+  });
+
+  it('leaves the caret alone while typing in the middle of the text', async () => {
+    await renderEditor({ defaultValue: '<p>AB</p>' });
+
+    // Typing at the very end would hide a caret reset, since a reset lands there too.
+    act(() => {
+      capturedEditor.commands.setTextSelection(2);
+    });
+    typeIntoEditor('X');
+    const afterFirstKey = capturedEditor.state.selection.from;
+    typeIntoEditor('Y');
+
+    // Re-feeding the value into the editor on every keystroke would push the caret to the end
+    // of the document, so the second character would land after the B instead of before it.
+    expect(afterFirstKey).toBe(3);
+    expect(capturedEditor.state.selection.from).toBe(4);
+    expect(capturedEditor.getText()).toBe('AXYB');
+  });
+
+  it('renders only the toolbar buttons the decorator asks for', async () => {
+    await renderEditor({ model: ToolbarForm });
+
+    const buttons = document.querySelectorAll('.rich-text-toolbar-button');
+    expect(Array.from(buttons).map(button => button.getAttribute('title'))).toEqual([
+      'Bold',
+      'Italic',
+    ]);
+  });
+
+  it('defaults to the full toolbar', async () => {
+    await renderEditor();
+
+    expect(document.querySelectorAll('.rich-text-toolbar-button').length).toBe(6);
+  });
+
+  it('applies formatting from the toolbar to the form value', async () => {
+    await renderEditor();
+
+    typeIntoEditor('kalın');
+    act(() => {
+      capturedEditor.commands.selectAll();
+    });
+    act(() => {
+      (screen.getByTitle('Bold') as HTMLButtonElement).click();
+    });
+
+    await waitFor(() => expect(form.getValues('body')).toBe('<p><strong>kalın</strong></p>'));
+  });
+});

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/CustomField.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { InputConfiguration } from '../../decorators/form/Input';
+import { useFormContext, Controller } from 'react-hook-form';
+import { CustomInputConfiguration } from '../../decorators/form/inputs/CustomInput';
+
+interface CustomFieldProps {
+  input: InputConfiguration;
+  fieldName: string;
+  error?: string;
+}
+
+export function CustomField({ input, fieldName, error }: CustomFieldProps) {
+  const inputCustom = input as CustomInputConfiguration;
+  const { control } = useFormContext();
+
+  return (
+    <Controller
+      name={fieldName}
+      control={control}
+      render={({ field }) => {
+        return (
+          <>
+            {inputCustom.render({
+              fieldName,
+              value: field.value,
+              onChange: field.onChange,
+              error,
+            })}
+          </>
+        );
+      }}
+    />
+  );
+}

package/src/components/form/FormField.tsx

@@ -5,6 +5,10 @@ import { Uploader } from './Uploader';
 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;
@@ -79,9 +83,15 @@ 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': {
         return (
           <input type={input.inputType} {...register(fieldName)} placeholder={input.placeholder} />
@@ -98,7 +108,8 @@ export function FormField({ input, register, error, baseName }: FormFieldProps)
       default:
         return null;
     }
-  }, [input, register, fieldName]);
+    // NOTE: error message is a dependency because 'custom' forwards it into the render prop.
+  }, [input, register, fieldName, error?.message]);
 
   return (
     <div className={`form-field ${input.type === 'nested' ? 'nested-form-field' : ''}`}>

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