@djangocfg/ui-tools 2.1.91

package/src/tools/JsonForm/templates/ArrayFieldTemplate.tsx

@@ -0,0 +1,74 @@
+"use client"
+
+import { Plus } from 'lucide-react';
+import React from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+import { ArrayFieldTemplateProps } from '@rjsf/utils';
+
+/**
+ * Array field template for JSON Schema Form
+ * Renders array items with add/remove controls
+ *
+ * NOTE: In RJSF v6, `items` is an array of ReactElement (already rendered),
+ * NOT an array of objects with {children, hasRemove, etc.}.
+ * The actual rendering of each item (including remove buttons) is handled
+ * by ArrayFieldItemTemplate.
+ */
+export function ArrayFieldTemplate(props: ArrayFieldTemplateProps) {
+  const {
+    title,
+    items,
+    canAdd,
+    onAddClick,
+    required,
+  } = props;
+
+  return (
+    <div className="space-y-4">
+      {title && (
+        <div className="flex items-center justify-between">
+          <h3 className="text-lg font-semibold">
+            {title}
+            {required && <span className="text-destructive ml-1">*</span>}
+          </h3>
+          {canAdd && (
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={onAddClick}
+              className="gap-2"
+            >
+              <Plus className="h-4 w-4" />
+              Add Item
+            </Button>
+          )}
+        </div>
+      )}
+
+      {/* In RJSF v6, items is already an array of ReactElements */}
+      <div className="space-y-3">
+        {items}
+      </div>
+
+      {items.length === 0 && (
+        <div className="text-center py-8 text-muted-foreground border-2 border-dashed rounded-md">
+          No items added yet.
+          {canAdd && (
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={onAddClick}
+              className="mt-2 gap-2"
+            >
+              <Plus className="h-4 w-4" />
+              Add First Item
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/tools/JsonForm/templates/BaseInputTemplate.tsx

@@ -0,0 +1,107 @@
+"use client"
+
+import React, { ChangeEvent, FocusEvent, useCallback, useMemo } from 'react';
+
+import { Input } from '@djangocfg/ui-core/components';
+import { getInputProps, WidgetProps } from '@rjsf/utils';
+
+/**
+ * Base input template for JSON Schema Form
+ *
+ * This template is CRITICAL for rendering primitive types (string, number)
+ * inside arrays. Without it, array items with primitive types will render
+ * as empty containers.
+ *
+ * RJSF uses this template for:
+ * - Array items with primitive types (e.g., array of strings)
+ * - Fields without explicit widget mapping
+ * - All text-based widgets internally
+ *
+ * @see https://rjsf-team.github.io/react-jsonschema-form/docs/advanced-customization/custom-templates/#baseinputtemplate
+ */
+export function BaseInputTemplate(props: WidgetProps) {
+  const {
+    id,
+    type,
+    value,
+    readonly,
+    disabled,
+    autofocus,
+    onBlur,
+    onFocus,
+    onChange,
+    options,
+    schema,
+    rawErrors,
+    placeholder,
+  } = props;
+
+  // Get input props from RJSF utils (handles step, min, max, etc.)
+  const inputProps = useMemo(() => {
+    return getInputProps(schema, type, options);
+  }, [schema, type, options]);
+
+  // Safely convert value to string for input
+  const safeValue = useMemo(() => {
+    if (value === null || value === undefined) return '';
+    return String(value);
+  }, [value]);
+
+  const hasError = useMemo(() => {
+    return rawErrors && rawErrors.length > 0;
+  }, [rawErrors]);
+
+  // Handle text change - transform empty strings based on schema type
+  const handleChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
+    const val = event.target.value;
+
+    // Empty value handling
+    if (val === '') {
+      onChange(options?.emptyValue ?? '');
+      return;
+    }
+
+    // Number type conversion
+    if (inputProps.type === 'number' || schema.type === 'number' || schema.type === 'integer') {
+      const num = Number(val);
+      onChange(isNaN(num) ? val : num);
+      return;
+    }
+
+    onChange(val);
+  }, [onChange, inputProps.type, schema.type, options?.emptyValue]);
+
+  const handleBlur = useCallback((event: FocusEvent<HTMLInputElement>) => {
+    onBlur(id, event.target.value);
+  }, [id, onBlur]);
+
+  const handleFocus = useCallback((event: FocusEvent<HTMLInputElement>) => {
+    onFocus(id, event.target.value);
+  }, [id, onFocus]);
+
+  // Determine input type
+  const inputType = useMemo(() => {
+    if (inputProps.type) return inputProps.type;
+    if (schema.type === 'number' || schema.type === 'integer') return 'number';
+    return 'text';
+  }, [inputProps.type, schema.type]);
+
+  return (
+    <Input
+      id={id}
+      type={inputType}
+      value={safeValue}
+      disabled={disabled}
+      readOnly={readonly}
+      autoFocus={autofocus}
+      onChange={handleChange}
+      onBlur={handleBlur}
+      onFocus={handleFocus}
+      placeholder={placeholder}
+      className={hasError ? 'border-destructive' : ''}
+      step={inputProps.step}
+      min={inputProps.min}
+      max={inputProps.max}
+    />
+  );
+}

package/src/tools/JsonForm/templates/ErrorListTemplate.tsx

@@ -0,0 +1,35 @@
+"use client"
+
+import { AlertCircle } from 'lucide-react';
+import React from 'react';
+
+import { Alert, AlertDescription, AlertTitle } from '@djangocfg/ui-core/components';
+import { ErrorListProps } from '@rjsf/utils';
+
+/**
+ * Error list template for JSON Schema Form
+ * Displays validation errors at the top of the form
+ */
+export function ErrorListTemplate(props: ErrorListProps) {
+  const { errors } = props;
+
+  if (!errors || errors.length === 0) {
+    return null;
+  }
+
+  return (
+    <Alert variant="destructive" className="mb-6">
+      <AlertCircle className="h-4 w-4" />
+      <AlertTitle>Validation Errors</AlertTitle>
+      <AlertDescription>
+        <ul className="list-disc list-inside space-y-1 mt-2">
+          {errors.map((error, index) => (
+            <li key={index} className="text-sm">
+              {error.stack}
+            </li>
+          ))}
+        </ul>
+      </AlertDescription>
+    </Alert>
+  );
+}

package/src/tools/JsonForm/templates/FieldTemplate.tsx

@@ -0,0 +1,62 @@
+"use client"
+
+import React from 'react';
+
+import { Label } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { FieldTemplateProps } from '@rjsf/utils';
+
+/**
+ * Field template for JSON Schema Form
+ * Controls the layout and styling of individual form fields
+ */
+export function FieldTemplate(props: FieldTemplateProps) {
+  const {
+    id,
+    classNames,
+    style,
+    label,
+    help,
+    required,
+    description,
+    errors,
+    children,
+    displayLabel,
+    hidden,
+    rawErrors,
+  } = props;
+
+  if (hidden) {
+    return <div className="hidden">{children}</div>;
+  }
+
+  const hasError = rawErrors && rawErrors.length > 0;
+
+  return (
+    <div
+      className={cn('space-y-2', classNames)}
+      style={style}
+    >
+      {displayLabel && label && (
+        <Label htmlFor={id} className={cn(hasError && 'text-destructive')}>
+          {label}
+          {required && <span className="text-destructive ml-1">*</span>}
+        </Label>
+      )}
+
+      {description && (
+        <div className="text-sm text-muted-foreground">{description}</div>
+      )}
+
+      <div>{children}</div>
+
+      {errors && (
+        <div className="text-sm text-destructive">{errors}</div>
+      )}
+
+      {help && (
+        <div className="text-sm text-muted-foreground">{help}</div>
+      )}
+    </div>
+  );
+}

package/src/tools/JsonForm/templates/ObjectFieldTemplate.tsx

@@ -0,0 +1,116 @@
+"use client"
+
+import { ChevronDown } from 'lucide-react';
+import React, { useState } from 'react';
+
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+import { ObjectFieldTemplateProps } from '@rjsf/utils';
+
+/**
+ * Object field template for JSON Schema Form
+ *
+ * Supports:
+ * - Collapsible groups via ui:collapsible option
+ * - Grid layout via ui:grid option
+ * - Custom styling via ui:className
+ *
+ * Usage in uiSchema:
+ * ```json
+ * {
+ *   "colors": {
+ *     "ui:collapsible": true,
+ *     "ui:collapsed": false,
+ *     "ui:grid": 2
+ *   }
+ * }
+ * ```
+ */
+export function ObjectFieldTemplate(props: ObjectFieldTemplateProps) {
+  const {
+    title,
+    description,
+    properties,
+    required,
+    uiSchema,
+  } = props;
+
+  // UI options
+  const isCollapsible = uiSchema?.['ui:collapsible'] === true;
+  const defaultCollapsed = uiSchema?.['ui:collapsed'] === true;
+  const gridCols = uiSchema?.['ui:grid'] as number | undefined;
+  const className = uiSchema?.['ui:className'] as string | undefined;
+
+  // Collapsible state
+  const [isOpen, setIsOpen] = useState(!defaultCollapsed);
+
+  // Check if this is root object (no title usually means root)
+  const isRoot = !title;
+
+  // Grid class based on columns
+  const gridClass = gridCols
+    ? `grid gap-4 grid-cols-${gridCols}`
+    : 'space-y-4';
+
+  // Content wrapper
+  const content = (
+    <div className={cn(gridClass, className)}>
+      {properties.map((element) => (
+        <div key={element.name} className="property-wrapper">
+          {element.content}
+        </div>
+      ))}
+    </div>
+  );
+
+  // Root object - no wrapper
+  if (isRoot) {
+    return <div className="space-y-6">{content}</div>;
+  }
+
+  // Collapsible group
+  if (isCollapsible) {
+    return (
+      <Collapsible open={isOpen} onOpenChange={setIsOpen} className="space-y-2">
+        <CollapsibleTrigger className="flex w-full items-center justify-between rounded-lg border bg-muted/50 px-4 py-3 text-left hover:bg-muted transition-colors">
+          <div>
+            <h3 className="text-sm font-semibold">
+              {title}
+              {required && <span className="text-destructive ml-1">*</span>}
+            </h3>
+            {description && (
+              <p className="text-xs text-muted-foreground mt-0.5">{description}</p>
+            )}
+          </div>
+          <ChevronDown
+            className={cn(
+              'h-4 w-4 text-muted-foreground transition-transform duration-200',
+              isOpen && 'rotate-180'
+            )}
+          />
+        </CollapsibleTrigger>
+        <CollapsibleContent className="pl-1 pr-1 pt-2">
+          {content}
+        </CollapsibleContent>
+      </Collapsible>
+    );
+  }
+
+  // Regular group with title
+  return (
+    <div className="space-y-4">
+      {title && (
+        <div className="border-b pb-2">
+          <h3 className="text-sm font-semibold">
+            {title}
+            {required && <span className="text-destructive ml-1">*</span>}
+          </h3>
+          {description && (
+            <p className="text-xs text-muted-foreground mt-1">{description}</p>
+          )}
+        </div>
+      )}
+      {content}
+    </div>
+  );
+}

package/src/tools/JsonForm/templates/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Custom templates for JSON Schema Form
+ *
+ * Templates control the layout and structure of form sections
+ */
+
+export { FieldTemplate } from './FieldTemplate';
+export { ObjectFieldTemplate } from './ObjectFieldTemplate';
+export { ArrayFieldTemplate } from './ArrayFieldTemplate';
+export { ArrayFieldItemTemplate } from './ArrayFieldItemTemplate';
+export { ErrorListTemplate } from './ErrorListTemplate';
+export { BaseInputTemplate } from './BaseInputTemplate';

package/src/tools/JsonForm/types.ts

@@ -0,0 +1,83 @@
+import type { RJSFSchema, UiSchema } from '@rjsf/utils';
+import type { IChangeEvent, FormProps } from '@rjsf/core';
+
+/**
+ * JSON Schema Form props interface
+ */
+export interface JsonSchemaFormProps<T = any> extends Partial<FormProps<T>> {
+  /** JSON Schema that defines the form structure */
+  schema: RJSFSchema;
+
+  /** UI Schema for customizing the form appearance */
+  uiSchema?: UiSchema;
+
+  /** Initial form data */
+  formData?: T;
+
+  /** Callback when form is submitted */
+  onSubmit?: (data: IChangeEvent<T>) => void;
+
+  /** Callback when form data changes */
+  onChange?: (data: IChangeEvent<T>) => void;
+
+  /** Callback when form has validation errors */
+  onError?: (errors: any[]) => void;
+
+  /** Whether to show error list at the top of form */
+  showErrorList?: false | 'top' | 'bottom';
+
+  /** Whether to live validate on change */
+  liveValidate?: boolean;
+
+  /** Whether the form is disabled */
+  disabled?: boolean;
+
+  /** Whether the form is read-only */
+  readonly?: boolean;
+
+  /** Custom CSS class name */
+  className?: string;
+
+  /** Whether to show submit button */
+  showSubmitButton?: boolean;
+
+  /** Submit button text */
+  submitButtonText?: string;
+}
+
+/**
+ * Field template props
+ */
+export interface FieldTemplateProps {
+  id: string;
+  label: string;
+  required: boolean;
+  description?: string;
+  errors?: any;
+  help?: string;
+  displayLabel?: boolean;
+  children: React.ReactNode;
+  classNames?: string;
+  rawErrors?: string[];
+  schema: RJSFSchema;
+}
+
+/**
+ * Widget props base interface
+ */
+export interface BaseWidgetProps {
+  id: string;
+  value: any;
+  required: boolean;
+  disabled: boolean;
+  readonly: boolean;
+  autofocus: boolean;
+  onChange: (value: any) => void;
+  onBlur: (id: string, value: any) => void;
+  onFocus: (id: string, value: any) => void;
+  options: any;
+  schema: RJSFSchema;
+  label: string;
+  placeholder?: string;
+  rawErrors?: string[];
+}

package/src/tools/JsonForm/utils.ts

@@ -0,0 +1,213 @@
+import consola from 'consola';
+
+import { RJSFSchema } from '@rjsf/utils';
+
+/**
+ * Utility functions for JSON Schema Form
+ */
+
+/**
+ * Safely validates and normalizes JSON Schema
+ * Ensures schema is valid before rendering
+ */
+export function validateSchema(schema: any): RJSFSchema | null {
+  if (!schema || typeof schema !== 'object') {
+    if (process.env.NODE_ENV === 'development') {
+      consola.error('[JsonSchemaForm] Invalid schema: must be an object', schema);
+    }
+    return null;
+  }
+
+  // Basic schema validation - more permissive
+  // Schema is valid if it has type OR properties OR $ref OR $schema
+  const hasValidStructure =
+    schema.type ||
+    schema.properties ||
+    schema.$ref ||
+    schema.$schema;
+
+  if (!hasValidStructure) {
+    if (process.env.NODE_ENV === 'development') {
+      consola.error('[JsonSchemaForm] Invalid schema: missing type, properties, $ref, or $schema', schema);
+    }
+    return null;
+  }
+
+  if (process.env.NODE_ENV === 'development') {
+    consola.success('[JsonSchemaForm] Schema validated successfully:', {
+      type: schema.type,
+      title: schema.title,
+      hasProperties: !!schema.properties,
+      hasRequired: !!schema.required,
+    });
+  }
+
+  return schema as RJSFSchema;
+}
+
+/**
+ * Safely normalizes form data
+ * Removes undefined values and ensures data structure matches schema
+ */
+export function normalizeFormData<T = any>(
+  formData: any,
+  schema: RJSFSchema
+): T {
+  if (formData === null || formData === undefined) {
+    return (schema.type === 'object' ? {} : schema.type === 'array' ? [] : null) as T;
+  }
+
+  // Deep clone to avoid mutations
+  const normalized = JSON.parse(JSON.stringify(formData));
+
+  // Remove undefined values recursively
+  return removeUndefined(normalized) as T;
+}
+
+/**
+ * Recursively removes undefined values from an object
+ */
+function removeUndefined(obj: any): any {
+  if (obj === null || obj === undefined) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map(removeUndefined).filter((item) => item !== undefined);
+  }
+
+  if (typeof obj === 'object') {
+    const cleaned: any = {};
+    for (const key in obj) {
+      if (obj[key] !== undefined) {
+        cleaned[key] = removeUndefined(obj[key]);
+      }
+    }
+    return cleaned;
+  }
+
+  return obj;
+}
+
+/**
+ * Merges schema defaults with form data
+ */
+export function mergeDefaults(
+  formData: any,
+  schema: RJSFSchema
+): any {
+  if (!schema) return formData;
+
+  const result = { ...formData };
+
+  if (schema.type === 'object' && schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      const prop = propSchema as RJSFSchema;
+
+      // Apply default if field is missing
+      if (result[key] === undefined && prop.default !== undefined) {
+        result[key] = prop.default;
+      }
+
+      // Recursively merge nested objects
+      if (prop.type === 'object' && result[key]) {
+        result[key] = mergeDefaults(result[key], prop);
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Safely parses JSON string with error handling
+ */
+export function safeJsonParse<T = any>(
+  jsonString: string,
+  fallback: T
+): T {
+  try {
+    return JSON.parse(jsonString);
+  } catch (error) {
+    consola.error('[JsonSchemaForm] JSON parse error:', error);
+    return fallback;
+  }
+}
+
+/**
+ * Safely stringifies object to JSON
+ */
+export function safeJsonStringify(
+  obj: any,
+  pretty: boolean = true
+): string {
+  try {
+    return JSON.stringify(obj, null, pretty ? 2 : 0);
+  } catch (error) {
+    consola.error('[JsonSchemaForm] JSON stringify error:', error);
+    return '{}';
+  }
+}
+
+/**
+ * Checks if schema has required fields
+ */
+export function hasRequiredFields(schema: RJSFSchema): boolean {
+  return Array.isArray(schema.required) && schema.required.length > 0;
+}
+
+/**
+ * Gets all required field paths from schema
+ */
+export function getRequiredFields(
+  schema: RJSFSchema,
+  prefix: string = ''
+): string[] {
+  const required: string[] = [];
+
+  if (schema.required && Array.isArray(schema.required)) {
+    required.push(...schema.required.map((field) =>
+      prefix ? `${prefix}.${field}` : field
+    ));
+  }
+
+  if (schema.type === 'object' && schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      const prop = propSchema as RJSFSchema;
+      const fieldPath = prefix ? `${prefix}.${key}` : key;
+      required.push(...getRequiredFields(prop, fieldPath));
+    }
+  }
+
+  return required;
+}
+
+/**
+ * Validates form data against required fields
+ */
+export function validateRequiredFields(
+  formData: any,
+  schema: RJSFSchema
+): { valid: boolean; missing: string[] } {
+  const requiredFields = getRequiredFields(schema);
+  const missing: string[] = [];
+
+  for (const field of requiredFields) {
+    const value = getNestedValue(formData, field);
+    if (value === undefined || value === null || value === '') {
+      missing.push(field);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+  };
+}
+
+/**
+ * Gets nested value from object by path
+ */
+function getNestedValue(obj: any, path: string): any {
+  return path.split('.').reduce((current, key) => current?.[key], obj);
+}