@object-ui/plugin-form 3.0.3 → 3.1.0

package/src/EmbeddableForm.tsx

@@ -0,0 +1,240 @@
+/**
+ * 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.
+ */
+
+/**
+ * EmbeddableForm Component
+ *
+ * A standalone embeddable form that can be accessed without authentication.
+ * Designed for external data collection use cases (surveys, registrations, etc.).
+ *
+ * Features:
+ * - Renders from ObjectFormSchema or inline field definitions
+ * - No authentication required (public access)
+ * - URL prefill parameters support (?name=John&email=...)
+ * - Configurable branding (logo, colors, title)
+ * - Success/thank-you page after submission
+ */
+
+import React, { useState, useCallback, useMemo } from 'react';
+import type { DataSource, FormField } from '@object-ui/types';
+import { ObjectForm } from './ObjectForm';
+
+export interface EmbeddableFormConfig {
+  /** Unique form ID */
+  formId: string;
+  /** Object name to create records in */
+  objectName: string;
+  /** Form title displayed at the top */
+  title?: string;
+  /** Form description / instructions */
+  description?: string;
+  /** Fields to include in the form (subset of object fields) */
+  fields?: string[];
+  /** Custom field definitions for inline forms */
+  customFields?: FormField[];
+  /** Branding configuration */
+  branding?: {
+    logo?: string;
+    primaryColor?: string;
+    backgroundColor?: string;
+  };
+  /** Thank you page configuration */
+  thankYouPage?: {
+    title?: string;
+    message?: string;
+    redirectUrl?: string;
+    redirectDelay?: number;
+  };
+  /** Allow multiple submissions */
+  allowMultiple?: boolean;
+}
+
+export interface EmbeddableFormProps {
+  /** Form configuration */
+  config: EmbeddableFormConfig;
+  /** Data source for creating records */
+  dataSource?: DataSource;
+  /** URL search parameters for prefilling fields */
+  prefillParams?: Record<string, string>;
+  /** Additional CSS class */
+  className?: string;
+}
+
+/**
+ * EmbeddableForm — Standalone form for external data collection.
+ *
+ * Can be rendered at a public URL (e.g., `/forms/:formId`) without auth.
+ * Submissions create records in the specified object via DataSource.
+ */
+export const EmbeddableForm: React.FC<EmbeddableFormProps> = ({
+  config,
+  dataSource,
+  prefillParams,
+  className,
+}) => {
+  const [submitted, setSubmitted] = useState(false);
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  // Build initial data from URL prefill params or window.location.search
+  const initialData = useMemo(() => {
+    const data: Record<string, string> = {};
+    // Explicit prefillParams take priority
+    if (prefillParams) {
+      for (const [key, value] of Object.entries(prefillParams)) {
+        data[key] = value;
+      }
+    }
+    // Also parse URL search parameters for prefilling (Phase 14 L2)
+    if (typeof window !== 'undefined') {
+      const urlParams = new URLSearchParams(window.location.search);
+      urlParams.forEach((value, key) => {
+        if (!(key in data)) {
+          data[key] = value;
+        }
+      });
+    }
+    return Object.keys(data).length > 0 ? data : undefined;
+  }, [prefillParams]);
+
+  const handleSubmit = useCallback(async (formData: Record<string, any>) => {
+    setSubmitting(true);
+    setError(null);
+
+    try {
+      if (dataSource) {
+        await dataSource.create(config.objectName, formData);
+      }
+      setSubmitted(true);
+
+      // Handle redirect after delay
+      if (config.thankYouPage?.redirectUrl) {
+        const delay = config.thankYouPage.redirectDelay ?? 3000;
+        setTimeout(() => {
+          window.location.href = config.thankYouPage!.redirectUrl!;
+        }, delay);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to submit form. Please try again.');
+    } finally {
+      setSubmitting(false);
+    }
+  }, [dataSource, config]);
+
+  const handleReset = useCallback(() => {
+    setSubmitted(false);
+    setError(null);
+  }, []);
+
+  // Branding styles
+  const brandingStyle = useMemo(() => {
+    const style: React.CSSProperties = {};
+    if (config.branding?.backgroundColor) {
+      style.backgroundColor = config.branding.backgroundColor;
+    }
+    return style;
+  }, [config.branding]);
+
+  // Thank you page
+  if (submitted) {
+    const thankYou = config.thankYouPage;
+    return (
+      <div
+        className={`min-h-screen flex items-center justify-center p-4 ${className || ''}`}
+        style={brandingStyle}
+      >
+        <div className="max-w-md w-full bg-card rounded-lg shadow-lg p-8 text-center space-y-4">
+          <div className="text-4xl">✓</div>
+          <h2 className="text-xl font-semibold text-foreground">
+            {thankYou?.title || 'Thank You!'}
+          </h2>
+          <p className="text-muted-foreground">
+            {thankYou?.message || 'Your submission has been received successfully.'}
+          </p>
+          {config.allowMultiple && (
+            <button
+              onClick={handleReset}
+              className="mt-4 px-4 py-2 text-sm font-medium rounded-md border border-input bg-background hover:bg-accent hover:text-accent-foreground transition-colors"
+            >
+              Submit Another Response
+            </button>
+          )}
+          {thankYou?.redirectUrl && (
+            <p className="text-xs text-muted-foreground">
+              Redirecting in {Math.ceil((thankYou.redirectDelay ?? 3000) / 1000)} seconds...
+            </p>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={`min-h-screen flex items-center justify-center p-4 ${className || ''}`}
+      style={brandingStyle}
+    >
+      <div className="max-w-2xl w-full bg-card rounded-lg shadow-lg overflow-hidden">
+        {/* Header */}
+        <div
+          className="p-6 border-b"
+          style={config.branding?.primaryColor ? { borderBottomColor: config.branding.primaryColor } : undefined}
+        >
+          {config.branding?.logo && (
+            <img
+              src={config.branding.logo}
+              alt="Logo"
+              className="h-8 mb-4"
+            />
+          )}
+          {config.title && (
+            <h1 className="text-xl font-semibold text-foreground">
+              {config.title}
+            </h1>
+          )}
+          {config.description && (
+            <p className="text-sm text-muted-foreground mt-1">
+              {config.description}
+            </p>
+          )}
+        </div>
+
+        {/* Form body */}
+        <div className="p-6">
+          {error && (
+            <div className="mb-4 p-3 bg-destructive/10 border border-destructive/30 rounded-md text-sm text-destructive">
+              {error}
+            </div>
+          )}
+          <ObjectForm
+            schema={{
+              type: 'object-form',
+              objectName: config.objectName,
+              mode: 'create',
+              fields: config.fields,
+              customFields: config.customFields,
+              initialData,
+              onSuccess: handleSubmit,
+              submitLabel: submitting ? 'Submitting...' : 'Submit',
+            }}
+            dataSource={dataSource}
+          />
+        </div>
+
+        {/* Footer */}
+        <div className="px-6 py-3 border-t bg-muted/20 text-center">
+          <p className="text-xs text-muted-foreground">
+            Powered by ObjectStack
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default EmbeddableForm;

package/src/FormAnalytics.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.
+ */
+
+/**
+ * FormAnalytics Component
+ *
+ * Displays basic analytics for form submissions:
+ * - Total submissions count
+ * - Fill rate (completed vs started)
+ * - Average completion time
+ * - Field drop-off rates
+ *
+ * This is an L1 Foundation component for Phase 14.
+ */
+
+import React, { useMemo } from 'react';
+import { Card, CardHeader, CardTitle, CardContent, CardDescription } from '@object-ui/components';
+
+export interface FormSubmissionMetric {
+  /** Total number of form submissions */
+  totalSubmissions: number;
+  /** Number of forms started but not completed */
+  abandonedSubmissions?: number;
+  /** Average time to complete form in seconds */
+  avgCompletionTime?: number;
+  /** Submissions per day over the last N days */
+  dailySubmissions?: Array<{
+    date: string;
+    count: number;
+  }>;
+  /** Field-level drop-off data */
+  fieldDropOff?: Array<{
+    fieldName: string;
+    label: string;
+    completionRate: number;
+  }>;
+}
+
+export interface FormAnalyticsProps {
+  /** Form identifier */
+  formId: string;
+  /** Form title */
+  formTitle?: string;
+  /** Submission metrics data */
+  metrics: FormSubmissionMetric;
+  /** Additional CSS class */
+  className?: string;
+}
+
+function formatDuration(seconds: number): string {
+  if (seconds < 60) return `${Math.round(seconds)}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m ${Math.round(seconds % 60)}s`;
+  return `${Math.floor(seconds / 3600)}h ${Math.floor((seconds % 3600) / 60)}m`;
+}
+
+/**
+ * FormAnalytics — Basic form analytics dashboard showing submission metrics.
+ *
+ * Displays fill rate, completion time, and field-level drop-off data
+ * for embeddable forms and data collection workflows.
+ */
+export const FormAnalytics: React.FC<FormAnalyticsProps> = ({
+  formId,
+  formTitle,
+  metrics,
+  className,
+}) => {
+  const fillRate = useMemo(() => {
+    if (!metrics.abandonedSubmissions) return 100;
+    const total = metrics.totalSubmissions + metrics.abandonedSubmissions;
+    if (total === 0) return 0;
+    return Math.round((metrics.totalSubmissions / total) * 100);
+  }, [metrics.totalSubmissions, metrics.abandonedSubmissions]);
+
+  // Find max count for bar chart scaling
+  const maxDaily = useMemo(() => {
+    if (!metrics.dailySubmissions?.length) return 1;
+    return Math.max(...metrics.dailySubmissions.map(d => d.count), 1);
+  }, [metrics.dailySubmissions]);
+
+  return (
+    <div className={`space-y-4 ${className || ''}`}>
+      {/* Header */}
+      <div>
+        <h2 className="text-lg font-semibold text-foreground">
+          {formTitle || `Form Analytics`}
+        </h2>
+        <p className="text-sm text-muted-foreground">
+          Form ID: {formId}
+        </p>
+      </div>
+
+      {/* Metric cards */}
+      <div className="grid grid-cols-1 sm:grid-cols-3 gap-4">
+        {/* Total Submissions */}
+        <Card>
+          <CardHeader className="pb-2">
+            <CardDescription>Total Submissions</CardDescription>
+            <CardTitle className="text-2xl">
+              {metrics.totalSubmissions.toLocaleString()}
+            </CardTitle>
+          </CardHeader>
+        </Card>
+
+        {/* Fill Rate */}
+        <Card>
+          <CardHeader className="pb-2">
+            <CardDescription>Fill Rate</CardDescription>
+            <CardTitle className="text-2xl">
+              {fillRate}%
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="w-full bg-muted rounded-full h-2">
+              <div
+                className="bg-primary rounded-full h-2 transition-all"
+                style={{ width: `${fillRate}%` }}
+              />
+            </div>
+          </CardContent>
+        </Card>
+
+        {/* Avg Completion Time */}
+        <Card>
+          <CardHeader className="pb-2">
+            <CardDescription>Avg. Completion Time</CardDescription>
+            <CardTitle className="text-2xl">
+              {metrics.avgCompletionTime
+                ? formatDuration(metrics.avgCompletionTime)
+                : '—'}
+            </CardTitle>
+          </CardHeader>
+        </Card>
+      </div>
+
+      {/* Daily Submissions Chart */}
+      {metrics.dailySubmissions && metrics.dailySubmissions.length > 0 && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Daily Submissions
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            <div className="flex items-end gap-1 h-32">
+              {metrics.dailySubmissions.map((day, idx) => (
+                <div key={idx} className="flex-1 flex flex-col items-center gap-1">
+                  <div
+                    className="w-full bg-primary/80 rounded-t transition-all hover:bg-primary"
+                    style={{ height: `${(day.count / maxDaily) * 100}%`, minHeight: day.count > 0 ? '4px' : '0' }}
+                    title={`${day.date}: ${day.count} submissions`}
+                  />
+                  <span className="text-[10px] text-muted-foreground truncate w-full text-center">
+                    {day.date.slice(-5)}
+                  </span>
+                </div>
+              ))}
+            </div>
+          </CardContent>
+        </Card>
+      )}
+
+      {/* Field Drop-off */}
+      {metrics.fieldDropOff && metrics.fieldDropOff.length > 0 && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Field Completion Rates
+            </CardTitle>
+            <CardDescription>
+              Percentage of users who completed each field
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className="space-y-3">
+              {metrics.fieldDropOff.map((field, idx) => (
+                <div key={idx} className="space-y-1">
+                  <div className="flex justify-between text-sm">
+                    <span className="text-foreground">{field.label}</span>
+                    <span className="text-muted-foreground">{field.completionRate}%</span>
+                  </div>
+                  <div className="w-full bg-muted rounded-full h-1.5">
+                    <div
+                      className={`rounded-full h-1.5 transition-all ${
+                        field.completionRate >= 80
+                          ? 'bg-green-500'
+                          : field.completionRate >= 50
+                          ? 'bg-yellow-500'
+                          : 'bg-destructive'
+                      }`}
+                      style={{ width: `${field.completionRate}%` }}
+                    />
+                  </div>
+                </div>
+              ))}
+            </div>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+};
+
+export default FormAnalytics;

package/src/FormSection.tsx

@@ -55,6 +55,13 @@ export interface FormSectionProps {
    * Additional CSS classes
    */
   className?: string;
+
+  /**
+   * Override the default responsive grid classes.
+   * When provided, replaces the viewport-based grid-cols classes
+   * (e.g. with container-query-based classes like `@md:grid-cols-2`).
+   */
+  gridClassName?: string;
 }
 
 /**
@@ -78,6 +85,7 @@ export const FormSection: React.FC<FormSectionProps> = ({
   columns = 1,
   children,
   className,
+  gridClassName,
 }) => {
   const [isCollapsed, setIsCollapsed] = useState(initialCollapsed);
 
@@ -133,7 +141,7 @@ export const FormSection: React.FC<FormSectionProps> = ({
 
       {/* Section Content */}
       {!isCollapsed && (
-        <div className={cn('grid gap-4', gridCols[columns])}>
+        <div className={cn('grid gap-4', gridClassName || gridCols[columns])}>
           {children}
         </div>
       )}