@object-ui/react 0.3.0 → 0.5.0

package/src/components/form/FormRenderer.tsx

@@ -0,0 +1,209 @@
+/**
+ * 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.
+ */
+
+import React from 'react';
+import { useForm, FormProvider, UseFormReturn } from 'react-hook-form';
+import type { FormView, FormSection } from '@objectstack/spec/ui';
+import { FieldFactory } from './FieldFactory';
+
+export interface FormRendererProps {
+  /**
+   * The FormView schema from @objectstack/spec
+   */
+  schema: FormView;
+  /**
+   * Initial form data
+   */
+  data?: Record<string, any>;
+  /**
+   * Form submission handler
+   */
+  onSubmit?: (data: Record<string, any>) => void | Promise<void>;
+  /**
+   * Form change handler
+   */
+  onChange?: (data: Record<string, any>) => void;
+  /**
+   * Custom class name for the form
+   */
+  className?: string;
+  /**
+   * Whether the form is disabled
+   */
+  disabled?: boolean;
+}
+
+/**
+ * FormRenderer component that renders forms based on FormViewSchema
+ * from @objectstack/spec
+ */
+export const FormRenderer: React.FC<FormRendererProps> = ({
+  schema,
+  data = {},
+  onSubmit,
+  onChange,
+  className = '',
+  disabled = false,
+}) => {
+  // Create form methods with react-hook-form
+  const methods = useForm({
+    defaultValues: data,
+    mode: 'onChange',
+  });
+
+  const { handleSubmit, watch } = methods;
+
+  // Watch for form changes
+  React.useEffect(() => {
+    if (onChange) {
+      const subscription = watch((value) => {
+        onChange(value as Record<string, any>);
+      });
+      return () => subscription.unsubscribe();
+    }
+  }, [watch, onChange]);
+
+  // Handle form submission
+  const onSubmitForm = handleSubmit(async (formData) => {
+    if (onSubmit) {
+      await onSubmit(formData);
+    }
+  });
+
+  // Render sections or fields
+  const renderContent = () => {
+    if (!schema.sections || schema.sections.length === 0) {
+      return null;
+    }
+
+    return (
+      <div className="space-y-6">
+        {schema.sections.map((section, index) => (
+          <FormSectionRenderer
+            key={index}
+            section={section}
+            methods={methods}
+            disabled={disabled}
+          />
+        ))}
+      </div>
+    );
+  };
+
+  return (
+    <FormProvider {...methods}>
+      <form onSubmit={onSubmitForm} className={`space-y-6 ${className}`}>
+        {renderContent()}
+        
+        {/* Submit button - optional, can be customized */}
+        <div className="flex justify-end gap-2">
+          <button
+            type="submit"
+            disabled={disabled}
+            className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Submit
+          </button>
+        </div>
+      </form>
+    </FormProvider>
+  );
+};
+
+interface FormSectionRendererProps {
+  section: FormSection;
+  methods: UseFormReturn<any>;
+  disabled?: boolean;
+}
+
+// Grid column classes for different column counts
+const GRID_COLS = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-1 md:grid-cols-2',
+  3: 'grid-cols-1 md:grid-cols-3',
+  4: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-4',
+} as const;
+
+// Column span classes
+const COL_SPAN = {
+  1: 'col-span-1',
+  2: 'col-span-2',
+  3: 'col-span-3',
+  4: 'col-span-4',
+} as const;
+
+/**
+ * Renders a form section with grid layout
+ */
+const FormSectionRenderer: React.FC<FormSectionRendererProps> = ({
+  section,
+  methods,
+  disabled = false,
+}) => {
+  const [isCollapsed, setIsCollapsed] = React.useState(section.collapsed || false);
+
+  // Determine grid columns based on section.columns
+  const gridCols = GRID_COLS[section.columns || 1];
+
+  const handleToggleCollapse = () => {
+    if (section.collapsible) {
+      setIsCollapsed(!isCollapsed);
+    }
+  };
+
+  return (
+    <div className="border rounded-lg p-4">
+      {section.label && (
+        <div
+          className={`flex items-center justify-between mb-4 ${
+            section.collapsible ? 'cursor-pointer' : ''
+          }`}
+          onClick={handleToggleCollapse}
+        >
+          <h3 className="text-lg font-semibold">{section.label}</h3>
+          {section.collapsible && (
+            <span className="text-sm text-gray-500">
+              {isCollapsed ? '▶' : '▼'}
+            </span>
+          )}
+        </div>
+      )}
+
+      {!isCollapsed && (
+        <div className={`grid ${gridCols} gap-4`}>
+          {section.fields.map((field, index) => {
+            // Handle both string fields (legacy) and FormFieldSchema objects
+            const fieldName = typeof field === 'string' ? field : field.field;
+            const fieldConfig = typeof field === 'string' ? { field: fieldName } : field;
+
+            // Skip hidden fields
+            if (fieldConfig.hidden) {
+              return null;
+            }
+
+            // Calculate colSpan for grid
+            const colSpan = fieldConfig.colSpan || 1;
+            const colSpanClass = COL_SPAN[Math.min(colSpan, section.columns || 1) as keyof typeof COL_SPAN];
+
+            return (
+              <div key={`${fieldName}-${index}`} className={colSpanClass}>
+                <FieldFactory
+                  field={fieldConfig}
+                  methods={methods}
+                  disabled={disabled || fieldConfig.readonly}
+                />
+              </div>
+            );
+          })}
+        </div>
+      )}
+    </div>
+  );
+};
+
+FormRenderer.displayName = 'FormRenderer';

package/src/components/form/README.md

@@ -0,0 +1,352 @@
+# FormRenderer Component
+
+The `FormRenderer` component is a React component that renders forms based on the `FormView` schema from `@objectstack/spec`. It provides a flexible and powerful way to create forms with minimal code.
+
+## Features
+
+- ✅ **Schema-driven**: Define forms using JSON schema from `@objectstack/spec`
+- ✅ **Multi-column layouts**: Support for 1-4 column grid layouts
+- ✅ **Collapsible sections**: Organize forms with collapsible sections
+- ✅ **Form state management**: Built-in state management using `react-hook-form`
+- ✅ **Multiple field types**: Text, Number, Checkbox, Textarea, Select, Date, DateTime, Time
+- ⏳ **Conditional fields**: Show/hide fields based on conditions (planned)
+- ⏳ **Schema validation**: Zod validation support (planned)
+- ✅ **Column spanning**: Fields can span multiple columns
+- ✅ **Help text**: Display helpful descriptions for fields
+- ✅ **Required fields**: Mark fields as required with validation
+
+## Installation
+
+The FormRenderer component is part of the `@object-ui/react` package:
+
+```bash
+npm install @object-ui/react @objectstack/spec react-hook-form
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @object-ui/react @objectstack/spec react-hook-form
+```
+
+## Basic Usage
+
+```tsx
+import { FormRenderer } from '@object-ui/react';
+import type { FormView } from '@objectstack/spec/ui';
+
+const schema: FormView = {
+  type: 'simple',
+  sections: [
+    {
+      label: 'Contact Information',
+      collapsible: false,
+      collapsed: false,
+      columns: 2,
+      fields: [
+        {
+          field: 'firstName',
+          label: 'First Name',
+          required: true,
+          widget: 'text',
+        },
+        {
+          field: 'lastName',
+          label: 'Last Name',
+          required: true,
+          widget: 'text',
+        },
+        {
+          field: 'email',
+          label: 'Email',
+          required: true,
+          widget: 'email',
+          helpText: 'We will never share your email',
+        },
+      ],
+    },
+  ],
+};
+
+function MyForm() {
+  const handleSubmit = (data: Record<string, any>) => {
+    console.log('Form submitted:', data);
+  };
+
+  return (
+    <FormRenderer
+      schema={schema}
+      onSubmit={handleSubmit}
+    />
+  );
+}
+```
+
+## Props
+
+### FormRendererProps
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `schema` | `FormView` | Yes | The FormView schema from @objectstack/spec |
+| `data` | `Record<string, any>` | No | Initial form data |
+| `onSubmit` | `(data: Record<string, any>) => void \| Promise<void>` | No | Form submission handler |
+| `onChange` | `(data: Record<string, any>) => void` | No | Form change handler |
+| `className` | `string` | No | Custom CSS class for the form |
+| `disabled` | `boolean` | No | Whether the form is disabled |
+
+## Schema Structure
+
+### FormView
+
+The main schema that defines the entire form.
+
+```typescript
+interface FormView {
+  type: 'simple' | 'tabbed' | 'wizard';
+  sections?: FormSection[];
+  data?: DataSource; // Optional data source configuration
+}
+```
+
+### FormSection
+
+Defines a section of the form with its own layout.
+
+```typescript
+interface FormSection {
+  label?: string;
+  collapsible?: boolean;
+  collapsed?: boolean;
+  columns: 1 | 2 | 3 | 4;
+  fields: (string | FormField)[];
+}
+```
+
+### FormField
+
+Defines individual form fields.
+
+```typescript
+interface FormField {
+  field: string; // Field name
+  label?: string;
+  placeholder?: string;
+  helpText?: string;
+  readonly?: boolean;
+  required?: boolean;
+  hidden?: boolean;
+  colSpan?: number; // Number of columns to span (1-4)
+  widget?: string; // Widget type (text, number, checkbox, etc.)
+  dependsOn?: string; // Field dependency
+  visibleOn?: string; // Visibility condition
+}
+```
+
+## Supported Widget Types
+
+The `FieldFactory` component supports the following widget types:
+
+### Text Input Types
+- `text`, `string` - Basic text input
+- `email` - Email input with validation
+- `password` - Password input (masked)
+- `url` - URL input
+- `tel`, `phone` - Telephone/phone number input
+- `textarea` - Multi-line text input
+- `markdown` - Markdown text editor (textarea with monospace font)
+- `html` - HTML/Rich text editor (textarea with monospace font)
+
+### Numeric Input Types
+- `number`, `integer`, `float` - Number input
+- `currency` - Currency input with $ prefix
+- `percent` - Percentage input with % suffix
+
+### Boolean & Selection Types
+- `checkbox`, `boolean` - Checkbox input
+- `select`, `dropdown` - Select dropdown
+
+### Date & Time Types
+- `date` - Date picker
+- `datetime`, `datetime-local` - DateTime picker
+- `time` - Time picker
+
+### File Upload Types
+- `file` - File upload input
+- `image` - Image upload input (defaults to image/* mime types)
+
+### Relationship Types
+- `lookup` - Lookup/reference field (select with options)
+- `master_detail` - Master-detail relationship (select with options)
+- `user`, `owner` - User selection field (select with options)
+
+### Complex & Special Types
+- `location` - Geographic location (latitude/longitude inputs)
+- `object` - JSON object editor (textarea with JSON validation)
+- `formula` - Read-only computed field
+- `summary` - Read-only aggregation/rollup field
+- `auto_number` - Read-only auto-generated number
+- `vector` - Vector/embedding display (read-only)
+- `grid` - Sub-table/grid editor (placeholder)
+
+## Extended Field Properties
+
+Some field types support additional properties beyond the base FormField schema:
+
+```typescript
+interface ExtendedFormField extends FormField {
+  // For file/image uploads
+  multiple?: boolean;
+  accept?: string[];
+  
+  // For select/lookup/user fields
+  options?: Array<{
+    label: string;
+    value: string;
+    disabled?: boolean;
+  }>;
+}
+```
+
+Example usage with extended properties:
+
+```tsx
+{
+  field: 'avatar',
+  label: 'Profile Picture',
+  widget: 'image',
+  accept: ['image/png', 'image/jpeg'],
+  multiple: false
+}
+
+{
+  field: 'account',
+  label: 'Account',
+  widget: 'lookup',
+  options: [
+    { label: 'Account 1', value: '1' },
+    { label: 'Account 2', value: '2' }
+  ]
+}
+```
+
+## Known Limitations
+
+### Version 0.3.0
+
+- **Conditional Visibility**: The `visibleOn` and `dependsOn` properties are not yet implemented. Fields are visible by default unless explicitly marked as `hidden`.
+- **Advanced Select Options**: While select/lookup/user fields support options via the `ExtendedFormField` interface, they don't yet support advanced features like search, async loading, or custom rendering.
+- **Rich Text Editors**: The `markdown` and `html` widgets currently use plain textareas with monospace fonts. Full WYSIWYG editors are planned for future releases.
+- **File Upload Preview**: File and image widgets support uploads but don't yet show previews or provide upload progress indicators.
+- **Location Maps**: The location widget provides lat/lng inputs but doesn't include map visualization or geocoding.
+- **Grid Editor**: The grid widget is a placeholder and doesn't yet provide spreadsheet-like editing capabilities.
+- **Validation**: Currently only basic required field validation is supported via react-hook-form. Advanced Zod schema validation is planned for future releases.
+
+These features are planned for future releases.
+
+## Examples
+
+### Multi-Section Form
+
+```tsx
+const schema: FormView = {
+  type: 'simple',
+  sections: [
+    {
+      label: 'Personal Information',
+      collapsible: true,
+      collapsed: false,
+      columns: 2,
+      fields: [
+        { field: 'firstName', label: 'First Name', required: true, widget: 'text' },
+        { field: 'lastName', label: 'Last Name', required: true, widget: 'text' },
+        { field: 'email', label: 'Email', required: true, widget: 'email' },
+        { field: 'phone', label: 'Phone', widget: 'tel' },
+      ],
+    },
+    {
+      label: 'Preferences',
+      collapsible: true,
+      collapsed: true,
+      columns: 1,
+      fields: [
+        {
+          field: 'newsletter',
+          label: 'Subscribe to newsletter',
+          widget: 'checkbox',
+          helpText: 'Receive updates about our products',
+        },
+      ],
+    },
+  ],
+};
+```
+
+### Form with Initial Data
+
+```tsx
+const initialData = {
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com',
+  newsletter: true,
+};
+
+<FormRenderer
+  schema={schema}
+  data={initialData}
+  onSubmit={handleSubmit}
+/>
+```
+
+### Form with Column Spanning
+
+```tsx
+const schema: FormView = {
+  type: 'simple',
+  sections: [
+    {
+      label: 'Contact',
+      columns: 2,
+      fields: [
+        { field: 'name', label: 'Name', widget: 'text' },
+        { field: 'email', label: 'Email', widget: 'email' },
+        {
+          field: 'message',
+          label: 'Message',
+          widget: 'textarea',
+          colSpan: 2, // Spans both columns
+        },
+      ],
+    },
+  ],
+};
+```
+
+## Architecture
+
+The FormRenderer is built on top of:
+
+- **react-hook-form**: For form state management and validation
+- **@objectstack/spec**: For schema definitions
+
+## Customization
+
+You can customize the appearance of the form by:
+
+1. Using the `className` prop on the FormRenderer
+2. Using Tailwind CSS classes in your application
+3. Extending the FieldFactory component for custom widgets
+
+## Related Components
+
+- `FieldFactory`: Renders individual form fields based on widget type
+- `SchemaRenderer`: General-purpose schema renderer for ObjectUI
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please read the [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.

package/src/components/form/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+export { FormRenderer } from './FormRenderer';
+export type { FormRendererProps } from './FormRenderer';
+export { FieldFactory } from './FieldFactory';
+export type { FieldFactoryProps, ExtendedFormField } from './FieldFactory';

package/src/context/SchemaRendererContext.tsx

@@ -0,0 +1,43 @@
+import React, { createContext, useContext, useMemo } from 'react';
+
+interface SchemaRendererContextType {
+  dataSource: any;
+  debug?: boolean;
+}
+
+const SchemaRendererContext = createContext<SchemaRendererContextType | null>(null);
+
+export { SchemaRendererContext };
+
+export const SchemaRendererProvider = ({ 
+  children, 
+  dataSource, 
+  debug 
+}: { 
+  children: React.ReactNode; 
+  dataSource: any; 
+  debug?: boolean 
+}) => {
+  const value = useMemo(() => ({ dataSource, debug }), [dataSource, debug]);
+  return (
+    <SchemaRendererContext.Provider value={value}>
+      {children}
+    </SchemaRendererContext.Provider>
+  );
+};
+
+export const useSchemaContext = () => {
+  const context = useContext(SchemaRendererContext);
+  if (!context) {
+    throw new Error('useSchemaContext must be used within a SchemaRendererProvider');
+  }
+  return context;
+};
+
+export const useDataScope = (path?: string) => {
+  const context = useContext(SchemaRendererContext);
+  const dataSource = context?.dataSource;
+  if (!dataSource || !path) return dataSource;
+  // Simple path resolution for now. In real app might be more complex
+  return path.split('.').reduce((acc, part) => acc && acc[part], dataSource);
+}

package/src/context/index.ts

@@ -1 +1,9 @@
-export {};
+/**
+ * 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.
+ */
+
+export * from './SchemaRendererContext';

package/src/hooks/index.ts

@@ -1 +1,11 @@
-export {};
+/**
+ * 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.
+ */
+
+export * from './useExpression';
+export * from './useActionRunner';
+