@object-ui/plugin-form 3.0.3 → 3.1.0

package/src/__tests__/autoLayout.test.ts

@@ -0,0 +1,342 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isWideFieldType,
+  isAutoGeneratedFieldType,
+  inferColumns,
+  inferModalSize,
+  applyAutoColSpan,
+  filterCreateModeFields,
+  applyAutoLayout,
+} from '../autoLayout';
+import type { FormField } from '@object-ui/types';
+
+describe('autoLayout', () => {
+  describe('isWideFieldType', () => {
+    it('returns true for wide form field types', () => {
+      expect(isWideFieldType('field:textarea')).toBe(true);
+      expect(isWideFieldType('field:markdown')).toBe(true);
+      expect(isWideFieldType('field:html')).toBe(true);
+      expect(isWideFieldType('field:grid')).toBe(true);
+      expect(isWideFieldType('field:rich-text')).toBe(true);
+    });
+
+    it('returns true for raw wide field types', () => {
+      expect(isWideFieldType('textarea')).toBe(true);
+      expect(isWideFieldType('markdown')).toBe(true);
+      expect(isWideFieldType('html')).toBe(true);
+      expect(isWideFieldType('grid')).toBe(true);
+      expect(isWideFieldType('rich-text')).toBe(true);
+    });
+
+    it('returns false for narrow field types', () => {
+      expect(isWideFieldType('field:text')).toBe(false);
+      expect(isWideFieldType('field:number')).toBe(false);
+      expect(isWideFieldType('field:select')).toBe(false);
+      expect(isWideFieldType('text')).toBe(false);
+      expect(isWideFieldType('boolean')).toBe(false);
+    });
+  });
+
+  describe('isAutoGeneratedFieldType', () => {
+    it('returns true for auto-generated types', () => {
+      expect(isAutoGeneratedFieldType('formula')).toBe(true);
+      expect(isAutoGeneratedFieldType('summary')).toBe(true);
+      expect(isAutoGeneratedFieldType('auto_number')).toBe(true);
+      expect(isAutoGeneratedFieldType('autonumber')).toBe(true);
+    });
+
+    it('returns false for user-editable types', () => {
+      expect(isAutoGeneratedFieldType('text')).toBe(false);
+      expect(isAutoGeneratedFieldType('number')).toBe(false);
+      expect(isAutoGeneratedFieldType('select')).toBe(false);
+    });
+  });
+
+  describe('inferColumns', () => {
+    it('returns 1 column for 0 fields', () => {
+      expect(inferColumns(0)).toBe(1);
+    });
+
+    it('returns 1 column for 1-3 fields', () => {
+      expect(inferColumns(1)).toBe(1);
+      expect(inferColumns(2)).toBe(1);
+      expect(inferColumns(3)).toBe(1);
+    });
+
+    it('returns 2 columns for 4+ fields', () => {
+      expect(inferColumns(4)).toBe(2);
+      expect(inferColumns(8)).toBe(2);
+      expect(inferColumns(20)).toBe(2);
+    });
+  });
+
+  describe('inferModalSize', () => {
+    it('returns default for 0 or 1 column', () => {
+      expect(inferModalSize(0)).toBe('default');
+      expect(inferModalSize(1)).toBe('default');
+    });
+
+    it('returns lg for 2 columns', () => {
+      expect(inferModalSize(2)).toBe('lg');
+    });
+
+    it('returns xl for 3 columns', () => {
+      expect(inferModalSize(3)).toBe('xl');
+    });
+
+    it('returns full for 4+ columns', () => {
+      expect(inferModalSize(4)).toBe('full');
+      expect(inferModalSize(5)).toBe('full');
+    });
+  });
+
+  describe('applyAutoColSpan', () => {
+    it('returns fields unchanged when columns is 1', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:textarea' },
+      ];
+      const result = applyAutoColSpan(fields, 1);
+      expect(result).toEqual(fields);
+    });
+
+    it('sets colSpan for wide fields in multi-column layout', () => {
+      const fields: FormField[] = [
+        { name: 'name', label: 'Name', type: 'field:text' },
+        { name: 'desc', label: 'Description', type: 'field:textarea' },
+        { name: 'notes', label: 'Notes', type: 'field:markdown' },
+      ];
+      const result = applyAutoColSpan(fields, 2);
+
+      expect(result[0].colSpan).toBeUndefined();
+      expect(result[1].colSpan).toBe(2);
+      expect(result[2].colSpan).toBe(2);
+    });
+
+    it('does not override user-defined colSpan', () => {
+      const fields: FormField[] = [
+        { name: 'desc', label: 'Description', type: 'field:textarea', colSpan: 1 },
+      ];
+      const result = applyAutoColSpan(fields, 2);
+      expect(result[0].colSpan).toBe(1);
+    });
+
+    it('does not mutate original fields', () => {
+      const fields: FormField[] = [
+        { name: 'desc', label: 'Description', type: 'field:textarea' },
+      ];
+      const result = applyAutoColSpan(fields, 2);
+      expect(fields[0].colSpan).toBeUndefined();
+      expect(result[0].colSpan).toBe(2);
+    });
+  });
+
+  describe('filterCreateModeFields', () => {
+    const objectSchema = {
+      name: 'test',
+      fields: {
+        name: { type: 'text', label: 'Name' },
+        total: { type: 'formula', label: 'Total' },
+        count: { type: 'summary', label: 'Count' },
+        record_no: { type: 'auto_number', label: 'Record #' },
+        email: { type: 'email', label: 'Email' },
+      },
+    };
+
+    it('filters out formula, summary, and auto_number fields', () => {
+      const fields: FormField[] = [
+        { name: 'name', label: 'Name', type: 'field:text' },
+        { name: 'total', label: 'Total', type: 'field:text' },
+        { name: 'count', label: 'Count', type: 'field:text' },
+        { name: 'record_no', label: 'Record #', type: 'field:text' },
+        { name: 'email', label: 'Email', type: 'field:text' },
+      ];
+
+      const result = filterCreateModeFields(fields, objectSchema);
+
+      expect(result).toHaveLength(2);
+      expect(result.map(f => f.name)).toEqual(['name', 'email']);
+    });
+
+    it('keeps all fields when objectSchema has no fields metadata', () => {
+      const fields: FormField[] = [
+        { name: 'name', label: 'Name', type: 'field:text' },
+        { name: 'total', label: 'Total', type: 'field:text' },
+      ];
+
+      const result = filterCreateModeFields(fields, { name: 'test' });
+      expect(result).toHaveLength(2);
+    });
+
+    it('keeps custom fields not in object schema', () => {
+      const fields: FormField[] = [
+        { name: 'custom_field', label: 'Custom', type: 'field:text' },
+      ];
+
+      const result = filterCreateModeFields(fields, objectSchema);
+      expect(result).toHaveLength(1);
+    });
+  });
+
+  describe('applyAutoLayout', () => {
+    it('infers 1 column for 3 fields', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:number' },
+        { name: 'c', label: 'C', type: 'field:select' },
+      ];
+
+      const result = applyAutoLayout(fields, null, undefined, 'create');
+      expect(result.columns).toBe(1);
+      expect(result.fields).toHaveLength(3);
+    });
+
+    it('infers 2 columns for 5 fields', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:text' },
+        { name: 'c', label: 'C', type: 'field:text' },
+        { name: 'd', label: 'D', type: 'field:text' },
+        { name: 'e', label: 'E', type: 'field:text' },
+      ];
+
+      const result = applyAutoLayout(fields, null, undefined, 'edit');
+      expect(result.columns).toBe(2);
+    });
+
+    it('applies colSpan to wide fields when columns > 1', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:text' },
+        { name: 'c', label: 'C', type: 'field:text' },
+        { name: 'd', label: 'D', type: 'field:textarea' },
+      ];
+
+      const result = applyAutoLayout(fields, null, undefined, 'edit');
+      expect(result.columns).toBe(2);
+      expect(result.fields[3].colSpan).toBe(2);
+      // Regular fields should not have colSpan
+      expect(result.fields[0].colSpan).toBeUndefined();
+    });
+
+    it('filters auto-generated fields in create mode', () => {
+      const fields: FormField[] = [
+        { name: 'name', label: 'Name', type: 'field:text' },
+        { name: 'total', label: 'Total', type: 'field:text' },
+        { name: 'email', label: 'Email', type: 'field:text' },
+        { name: 'count', label: 'Count', type: 'field:text' },
+      ];
+
+      const objectSchema = {
+        name: 'test',
+        fields: {
+          name: { type: 'text' },
+          total: { type: 'formula' },
+          email: { type: 'email' },
+          count: { type: 'summary' },
+        },
+      };
+
+      const result = applyAutoLayout(fields, objectSchema, undefined, 'create');
+      expect(result.fields.map(f => f.name)).toEqual(['name', 'email']);
+      expect(result.columns).toBe(1); // Only 2 fields after filtering → 1 column
+    });
+
+    it('does not filter auto-generated fields in edit mode', () => {
+      const fields: FormField[] = [
+        { name: 'name', label: 'Name', type: 'field:text' },
+        { name: 'total', label: 'Total', type: 'field:text' },
+      ];
+
+      const objectSchema = {
+        name: 'test',
+        fields: {
+          name: { type: 'text' },
+          total: { type: 'formula' },
+        },
+      };
+
+      const result = applyAutoLayout(fields, objectSchema, undefined, 'edit');
+      expect(result.fields).toHaveLength(2);
+    });
+
+    it('respects user-provided columns', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:text' },
+      ];
+
+      const result = applyAutoLayout(fields, null, 3, 'edit');
+      expect(result.columns).toBe(3);
+    });
+
+    it('applies auto colSpan even with user-provided columns', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:textarea' },
+      ];
+
+      const result = applyAutoLayout(fields, null, 3, 'edit');
+      expect(result.columns).toBe(3);
+      expect(result.fields[1].colSpan).toBe(3);
+    });
+
+    it('does not override user-defined colSpan on fields', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:textarea', colSpan: 1 },
+        { name: 'c', label: 'C', type: 'field:text' },
+        { name: 'd', label: 'D', type: 'field:text' },
+      ];
+
+      const result = applyAutoLayout(fields, null, undefined, 'edit');
+      expect(result.columns).toBe(2);
+      expect(result.fields[1].colSpan).toBe(1); // User override preserved
+    });
+
+    it('does not mutate original fields array', () => {
+      const fields: FormField[] = [
+        { name: 'a', label: 'A', type: 'field:text' },
+        { name: 'b', label: 'B', type: 'field:textarea' },
+        { name: 'c', label: 'C', type: 'field:text' },
+        { name: 'd', label: 'D', type: 'field:text' },
+      ];
+
+      const result = applyAutoLayout(fields, null, undefined, 'edit');
+      expect(fields[1].colSpan).toBeUndefined();
+      expect(result.fields[1].colSpan).toBe(2);
+    });
+
+    it('handles empty fields array', () => {
+      const result = applyAutoLayout([], null, undefined, 'create');
+      expect(result.fields).toEqual([]);
+      expect(result.columns).toBe(1);
+    });
+
+    it('infers columns based on field count after create-mode filtering', () => {
+      // Start with 5 fields, but 3 are auto-generated → 2 remain → 1 column
+      const fields: FormField[] = [
+        { name: 'name', label: 'Name', type: 'field:text' },
+        { name: 'f1', label: 'F1', type: 'field:text' },
+        { name: 'f2', label: 'F2', type: 'field:text' },
+        { name: 'f3', label: 'F3', type: 'field:text' },
+        { name: 'f4', label: 'F4', type: 'field:text' },
+      ];
+
+      const objectSchema = {
+        name: 'test',
+        fields: {
+          name: { type: 'text' },
+          f1: { type: 'formula' },
+          f2: { type: 'summary' },
+          f3: { type: 'auto_number' },
+          f4: { type: 'text' },
+        },
+      };
+
+      const result = applyAutoLayout(fields, objectSchema, undefined, 'create');
+      // Only 'name' and 'f4' remain after filtering
+      expect(result.fields).toHaveLength(2);
+      expect(result.columns).toBe(1);
+    });
+  });
+});

package/src/autoLayout.ts

@@ -0,0 +1,168 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Auto-Layout for ObjectForm
+ *
+ * Provides intelligent, zero-configuration default layout for metadata-driven forms.
+ * When the user has not explicitly set columns/colSpan/sections, this module
+ * infers optimal layout based on field count and field types.
+ *
+ * Priority: User configuration > Auto-layout inference
+ */
+
+import type { FormField } from '@object-ui/types';
+
+/** Field types that should span full width in multi-column layouts */
+const WIDE_FIELD_TYPES = new Set([
+  'field:textarea',
+  'field:markdown',
+  'field:html',
+  'field:grid',
+  'field:rich-text',
+  'textarea',
+  'markdown',
+  'html',
+  'grid',
+  'rich-text',
+]);
+
+/** Object field types that are auto-generated and should be hidden in create mode */
+const AUTO_GENERATED_FIELD_TYPES = new Set([
+  'formula',
+  'summary',
+  'auto_number',
+  'autonumber',
+]);
+
+/**
+ * Check if a field type is "wide" (should span full row in multi-column layout).
+ */
+export function isWideFieldType(type: string): boolean {
+  return WIDE_FIELD_TYPES.has(type);
+}
+
+/**
+ * Check if an object field type is auto-generated (formula, summary, auto_number).
+ */
+export function isAutoGeneratedFieldType(type: string): boolean {
+  return AUTO_GENERATED_FIELD_TYPES.has(type);
+}
+
+/**
+ * Infer optimal number of columns based on the number of visible fields
+ * and whether any wide fields are present.
+ *
+ * Rules:
+ * - 0-3 fields → 1 column
+ * - 4+ fields → 2 columns
+ */
+export function inferColumns(fieldCount: number): number {
+  if (fieldCount <= 3) return 1;
+  return 2;
+}
+
+/**
+ * Apply colSpan to wide fields so they span the full row.
+ * Only sets colSpan if the field does not already have one explicitly set.
+ *
+ * @returns A new array of fields with colSpan applied where needed.
+ */
+export function applyAutoColSpan(fields: FormField[], columns: number): FormField[] {
+  if (columns <= 1) return fields;
+
+  return fields.map(field => {
+    // User-defined colSpan takes priority
+    if (field.colSpan !== undefined) return field;
+
+    // Wide field types should span full row
+    if (field.type && isWideFieldType(field.type)) {
+      return { ...field, colSpan: columns };
+    }
+
+    return field;
+  });
+}
+
+/**
+ * Filter out auto-generated/readonly fields for create mode.
+ * These fields (formula, summary, auto_number) are computed server-side
+ * and should not appear in create forms.
+ *
+ * @param fields - The form fields array
+ * @param objectSchema - The object schema with original field metadata
+ * @returns Filtered fields array
+ */
+export function filterCreateModeFields(
+  fields: FormField[],
+  objectSchema: any
+): FormField[] {
+  if (!objectSchema?.fields) return fields;
+
+  return fields.filter(field => {
+    const objField = objectSchema.fields[field.name];
+    if (!objField) return true; // keep fields not in schema (custom fields)
+
+    return !isAutoGeneratedFieldType(objField.type);
+  });
+}
+
+/**
+ * Infer an appropriate modal size based on the number of layout columns.
+ * Used to auto-upgrade the modal width when auto-layout detects multi-column forms.
+ *
+ * Mapping:
+ * - 1 column  → 'default' (max-w-lg)
+ * - 2 columns → 'lg'      (max-w-2xl)
+ * - 3 columns → 'xl'      (max-w-4xl)
+ * - 4+ columns → 'full'   (max-w-[95vw])
+ */
+export function inferModalSize(columns: number): 'sm' | 'default' | 'lg' | 'xl' | 'full' {
+  if (columns <= 1) return 'default';
+  if (columns === 2) return 'lg';
+  if (columns === 3) return 'xl';
+  return 'full';
+}
+
+/**
+ * Main auto-layout orchestrator.
+ * Applies intelligent defaults only when the user has not explicitly configured layout.
+ *
+ * @param formFields - Generated form fields
+ * @param objectSchema - The original object schema (with field types)
+ * @param schemaColumns - User-provided columns (from ObjectFormSchema)
+ * @param mode - Form mode ('create' | 'edit' | 'view')
+ * @returns Object with processed fields and inferred columns
+ */
+export function applyAutoLayout(
+  formFields: FormField[],
+  objectSchema: any,
+  schemaColumns: number | undefined,
+  mode: string | undefined
+): { fields: FormField[]; columns: number | undefined } {
+  let fields = [...formFields];
+
+  // Step 1: Filter auto-generated fields in create mode
+  if (mode === 'create') {
+    fields = filterCreateModeFields(fields, objectSchema);
+  }
+
+  // Step 2: If user explicitly set columns, respect it but still apply auto colSpan
+  if (schemaColumns !== undefined) {
+    fields = applyAutoColSpan(fields, schemaColumns);
+    return { fields, columns: schemaColumns };
+  }
+
+  // Step 3: Infer columns from field count
+  const columns = inferColumns(fields.length);
+
+  // Step 4: Apply auto colSpan for wide fields
+  fields = applyAutoColSpan(fields, columns);
+
+  return { fields, columns };
+}

package/src/index.tsx

@@ -14,6 +14,15 @@ export { ObjectForm };
 export type { ObjectFormProps } from './ObjectForm';
 export { FormSection } from './FormSection';
 export type { FormSectionProps } from './FormSection';
+export {
+  applyAutoLayout,
+  inferColumns,
+  inferModalSize,
+  isWideFieldType,
+  isAutoGeneratedFieldType,
+  applyAutoColSpan,
+  filterCreateModeFields,
+} from './autoLayout';
 export { TabbedForm } from './TabbedForm';
 export type { TabbedFormProps, TabbedFormSchema, FormSectionConfig } from './TabbedForm';
 export { WizardForm } from './WizardForm';
@@ -24,6 +33,10 @@ export { DrawerForm } from './DrawerForm';
 export type { DrawerFormProps, DrawerFormSchema } from './DrawerForm';
 export { ModalForm } from './ModalForm';
 export type { ModalFormProps, ModalFormSchema } from './ModalForm';
+export { EmbeddableForm } from './EmbeddableForm';
+export type { EmbeddableFormProps, EmbeddableFormConfig } from './EmbeddableForm';
+export { FormAnalytics } from './FormAnalytics';
+export type { FormAnalyticsProps, FormSubmissionMetric } from './FormAnalytics';
 
 // Register object-form component
 const ObjectFormRenderer: React.FC<{ schema: any }> = ({ schema }) => {
@@ -80,3 +93,42 @@ ComponentRegistry.register('form', ObjectFormRenderer, {
 // Note: 'form' type (without namespace) is handled by @object-ui/components Form component
 // This plugin registers as 'view:form' (with view namespace) for the view protocol
 // ObjectForm internally uses { type: 'form' } to render the basic Form component
+
+// Register embeddable-form component for standalone public forms
+import { EmbeddableForm } from './EmbeddableForm';
+
+const EmbeddableFormRenderer: React.FC<{ schema: any }> = ({ schema }) => {
+  return <EmbeddableForm config={schema} />;
+};
+
+ComponentRegistry.register('embeddable-form', EmbeddableFormRenderer, {
+  namespace: 'plugin-form',
+  label: 'Embeddable Form',
+  category: 'plugin',
+  inputs: [
+    { name: 'formId', type: 'string', label: 'Form ID', required: true },
+    { name: 'objectName', type: 'string', label: 'Object Name', required: true },
+    { name: 'title', type: 'string', label: 'Form Title' },
+    { name: 'description', type: 'string', label: 'Description' },
+    { name: 'fields', type: 'array', label: 'Fields' },
+    { name: 'allowMultiple', type: 'boolean', label: 'Allow Multiple Submissions' },
+  ]
+});
+
+// Register form-analytics component for submission dashboards
+import { FormAnalytics } from './FormAnalytics';
+
+const FormAnalyticsRenderer: React.FC<{ schema: any }> = ({ schema }) => {
+  return <FormAnalytics formId={schema.formId} formTitle={schema.formTitle} metrics={schema.metrics || { totalSubmissions: 0 }} />;
+};
+
+ComponentRegistry.register('form-analytics', FormAnalyticsRenderer, {
+  namespace: 'plugin-form',
+  label: 'Form Analytics',
+  category: 'plugin',
+  inputs: [
+    { name: 'formId', type: 'string', label: 'Form ID', required: true },
+    { name: 'formTitle', type: 'string', label: 'Form Title' },
+    { name: 'metrics', type: 'object', label: 'Submission Metrics' },
+  ]
+});