spine-framework 0.3.144 → 0.4.0

package/.framework/src/components/shared/FieldRenderer.tsx

@@ -1,27 +1,36 @@
-
-
-
-// CIL[BEGIN chunk_id="FieldRenderer_module_header_1783927912" type="module_header" identity="module_header" parent="none"]
-// CIL[DOC-MACRO purpose="Import dependencies and define field renderer component interfaces"]
-// CIL[DOC-RESPONSIBILITY responsibility="Manage React imports and field renderer prop types"]
-// CIL[DOC-CONTEXT module="field-renderer" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Imported modules and interface" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Imports React, field types, and defines FieldRendererProps interface" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[BEGIN stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/components/shared/FieldRenderer.tsx"]
+// CIL[DOC-MACRO purpose="Import dependencies and types used to render schema-driven form fields"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare module-level imports for React, sanitization, markdown parsing, FieldDefinition, and the RichTextEditor component"]
+// CIL[DOC-CONTEXT module="components/shared" layer="ui" related_files=".framework/src/components/ui/RichTextEditor.tsx,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="none" outputs="imported symbols available to FieldRenderer, toSafeHtml, resolveRenderType, and FieldRendererProps" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Import React, DOMPurify, marked, FieldDefinition type, and RichTextEditor component" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-AUDIENCE audience="developer"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-component. Direct callers: 0. Direct calls: 0. Related files: custom/apps/portal/pages/ContentPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
-// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
-// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[DOC-AUDIENCE audience="framework-developers,ui-developers"]
+
 import React from 'react'
 import DOMPurify from 'dompurify'
 import { marked } from 'marked'
 import { FieldDefinition } from '../../types/types'
 import { RichTextEditor } from '../ui/RichTextEditor'
 
+// CIL[DOC-VECTOR type="context" content="purpose='Import dependencies and types used to render schema-driven form fields'; No verified external callers; imports: .framework/src/types/types.ts,.framework/src/components/ui/RichTextEditor.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:toSafeHtml:function" type="function" identity="toSafeHtml" parent="~/.framework/src/components/shared/FieldRenderer.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Sanitize raw HTML or markdown text for safe rendering as HTML"]
+// CIL[DOC-RESPONSIBILITY responsibility="Convert a raw string to sanitized HTML, detecting existing HTML and falling back to markdown parsing"]
+// CIL[DOC-CONTEXT module="components/shared" layer="ui" related_files=".framework/src/components/shared/FieldRenderer.tsx,.framework/src/components/ui/RichTextEditor.tsx,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="raw: string | undefined" outputs="sanitized HTML string" errors="none" side_effects="Runs DOMPurify and marked.parse"]
+// CIL[DOC-MICRO logic_summary="Trim input, detect common HTML tags, parse markdown if plain, then sanitize with DOMPurify" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
 function toSafeHtml(raw: string | undefined): string {
   const source = (raw ?? '').trim()
   if (!source) return '<p class="text-slate-400 italic">—</p>'
@@ -29,6 +38,23 @@ function toSafeHtml(raw: string | undefined): string {
   const html = likelyHtml ? source : (marked.parse(source, { async: false }) as string)
   return DOMPurify.sanitize(html)
 }
+// CIL[DOC-VECTOR type="context" content="purpose='Sanitize raw HTML or markdown text for safe rendering as HTML'; No verified external callers; imports: .framework/src/types/types.ts,.framework/src/components/ui/RichTextEditor.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:toSafeHtml:function"]
+
+
+// CIL[BEGIN stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:FieldRendererProps:interface" type="interface" identity="FieldRendererProps" parent="~/.framework/src/components/shared/FieldRenderer.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Define the props accepted by the FieldRenderer component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type-check the field, value, change handlers, readonly flag, error, and optional display type"]
+// CIL[DOC-CONTEXT module="components/shared" layer="ui" related_files=".framework/src/components/shared/FieldRenderer.tsx,.framework/src/components/ui/RichTextEditor.tsx,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="props object" outputs="typed prop contract for FieldRenderer" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Declare an interface describing the props consumed by FieldRenderer" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 
 interface FieldRendererProps {
   field: FieldDefinition
@@ -39,23 +65,23 @@ interface FieldRendererProps {
   error?: string
   displayType?: string
 }
-// CIL[END chunk_id="FieldRenderer_module_header_1783927912"]
-// CIL[BEGIN chunk_id="FieldRenderer_resolverendertype_1783927912" type="function" identity="resolveRenderType" parent="none"]
-// CIL[DOC-LEARNING topic="runtime-type:generic/field_rendering" content="FieldRenderer maps field.data_type or display_type to a widget: text, textarea, email, phone, url, number, date, datetime, checkbox, select, multiselect, radio, color, file, json. display_type overrides data_type when provided."]
-// CIL[DOC-NOTE type="design_schema_caveat" content="Unknown data_type or display_type silently falls back to text. Select/multiselect fields must define options or the user sees an empty control."]
-// CIL[DOC-MACRO purpose="Resolve canonical render type from field definition and display type"]
-// CIL[DOC-RESPONSIBILITY responsibility="Map display types and data types to render types"]
-// CIL[DOC-CONTEXT module="field-renderer" layer="frontend-component" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/migrations/025_retype_threads_messages.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Render type string" errors="none" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Display type overrides data type, maps to canonical render types" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-component. Direct callers: 1. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/migrations/025_retype_threads_messages.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/schema-utils.ts, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 1. Total affected: 1."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Define the props accepted by the FieldRenderer component'; No verified external callers; imports: .framework/src/types/types.ts,.framework/src/components/ui/RichTextEditor.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:FieldRendererProps:interface"]
+
+// CIL[BEGIN stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:resolveRenderType:function" type="function" identity="resolveRenderType" parent="~/.framework/src/components/shared/FieldRenderer.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Map a FieldDefinition and optional display override to a concrete render type string"]
+// CIL[DOC-RESPONSIBILITY responsibility="Resolve the widget type to render based on displayType override or field.data_type"]
+// CIL[DOC-CONTEXT module="components/shared" layer="ui" related_files=".framework/src/components/shared/FieldRenderer.tsx,.framework/src/components/ui/RichTextEditor.tsx,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="field: FieldDefinition, displayType?: string" outputs="render type string (text, rich_text, textarea, email, phone, etc.)" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Switch on displayType if provided, otherwise map field.data_type to a canonical render type" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
 function resolveRenderType(field: FieldDefinition, displayType?: string): string {
   if (displayType) {
     switch (displayType) {
@@ -124,21 +150,23 @@ function resolveRenderType(field: FieldDefinition, displayType?: string): string
       return 'text'
   }
 }
-// CIL[END chunk_id="FieldRenderer_resolverendertype_1783927912"]
-// CIL[BEGIN chunk_id="FieldRenderer_fieldrenderer_1783927912" type="function" identity="FieldRenderer" parent="none"]
-// CIL[DOC-MACRO purpose="Render appropriate input widget or display element for field type"]
-// CIL[DOC-RESPONSIBILITY responsibility="Display field as editable input or read-only value based on type"]
-// CIL[DOC-CONTEXT module="field-renderer" layer="frontend-component" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/migrations/025_retype_threads_messages.sql\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
-// CIL[DOC-CONTRACT inputs="none" outputs="Rendered field widget" errors="none" side_effects="Renders UI, calls onChange"]
-// CIL[DOC-MICRO logic_summary="Switches on render type to return appropriate input or display component" notable_decisions="[]"]
-// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
-// CIL[DOC-STABILITY stability="stable"]
-// CIL[DOC-VECTOR type="context" content="Layer: frontend-component. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/migrations/025_retype_threads_messages.sql, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, custom/apps/portal/pages/ContentPage.tsx, \."]
-// CIL[DOC-VECTOR type="blast_radius" content="Direct callers: 0. Total affected: 0."]
-// CIL[DOC-VECTOR type="configuration" content="No configuration dependencies."]
-// CIL[DOC-VECTOR type="constraint" content="No test paths identified."]
+// CIL[DOC-VECTOR type="context" content="purpose='Map a FieldDefinition and optional display override to a concrete render type string'; No verified external callers; imports: .framework/src/types/types.ts,.framework/src/components/ui/RichTextEditor.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
 // CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
 // CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:resolveRenderType:function"]
+
+// CIL[BEGIN stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:FieldRenderer:component" type="component" identity="FieldRenderer" parent="~/.framework/src/components/shared/FieldRenderer.tsx:module_header:module_header"]
+// CIL[DOC-MACRO purpose="Render a schema-driven form field with the appropriate input or read-only display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Pick a render type and render the matching input or read-only widget, including labels, descriptions, and error messages"]
+// CIL[DOC-CONTEXT module="components/shared" layer="ui" related_files=".framework/src/components/shared/FieldRenderer.tsx,.framework/src/components/ui/RichTextEditor.tsx,.framework/src/types/types.ts"]
+// CIL[DOC-CONTRACT inputs="field, value, onChange, readonly, error, displayType" outputs="JSX form field with label, control, description, and error" errors="none" side_effects="Invokes onChange callback on user interaction"]
+// CIL[DOC-MICRO logic_summary="Compute renderType from field and displayType, then switch on renderType to render the correct control, fallback to text input, and wrap with label/description/error" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+
 export function FieldRenderer({ field, value, onChange, readonly = false, error, displayType }: FieldRendererProps) {
   const renderType = resolveRenderType(field, displayType)
 
@@ -237,37 +265,64 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
           />
         )
 
-      case 'date':
+      case 'date': {
+        const parsed = value ? new Date(value) : null
+        if (parsed && isNaN(parsed.getTime())) {
+          return (
+            <input
+              type="text"
+              value={String(value)}
+              readOnly
+              className={`input bg-slate-50 ${error ? 'border-red-500' : ''}`}
+            />
+          )
+        }
         return (
           <input
             type="date"
-            value={value ? new Date(value).toISOString().split('T')[0] : ''}
+            value={parsed ? parsed.toISOString().split('T')[0] : ''}
             onChange={(e) => onChange?.(e.target.value || null)}
             readOnly={readonly}
             className={`input ${error ? 'border-red-500' : ''}`}
           />
         )
+      }
 
-      case 'datetime':
+      case 'datetime': {
+        const parsed = value ? new Date(value) : null
+        if (parsed && isNaN(parsed.getTime())) {
+          return (
+            <input
+              type="text"
+              value={String(value)}
+              readOnly
+              className={`input bg-slate-50 ${error ? 'border-red-500' : ''}`}
+            />
+          )
+        }
         return (
           <input
             type="datetime-local"
-            value={value ? new Date(value).toISOString().slice(0, 16) : ''}
+            value={parsed ? parsed.toISOString().slice(0, 16) : ''}
             onChange={(e) => onChange?.(e.target.value || null)}
             readOnly={readonly}
             className={`input ${error ? 'border-red-500' : ''}`}
           />
         )
+      }
 
       case 'select':
         return readonly ? (
           <div className={`text-slate-900 ${error ? 'border-red-500' : ''}`}>
             {(() => {
               if (!value) return <span className="text-slate-400 italic">—</span>
+
+
               const option = field.options?.find((opt) => {
                 const optVal = typeof opt === 'string' ? opt : opt.value
                 return optVal === value
               })
+
               return typeof option === 'string' ? option : option?.label || value
             })()}
           </div>
@@ -279,8 +334,14 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
           >
             <option value="">Select...</option>
             {field.options?.map((option) => {
+
+
               const optVal = typeof option === 'string' ? option : option.value
+
+
+
               const optLabel = typeof option === 'string' ? option : option.label
+
               return (
                 <option key={optVal} value={optVal}>
                   {optLabel}
@@ -294,20 +355,35 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
         return (
           <div className="space-y-2">
             {field.options?.map((option) => {
+
+
               const optionValue = typeof option === 'string' ? option : option.value
+
+
+
               const optionLabel = typeof option === 'string' ? option : option.label
+
               return (
                 <label key={optionValue} className="flex items-center">
                   <input
                     type="checkbox"
                     checked={Array.isArray(value) && value.includes(optionValue)}
                     onChange={(e) => {
+
+
                       const currentValue = Array.isArray(value) ? value : []
+
                       if (e.target.checked) {
                         onChange?.([...currentValue, optionValue])
                       } else {
                         onChange?.(currentValue.filter((v: string) => v !== optionValue))
                       }
+
+
+
+
+
+
                     }}
                     disabled={readonly}
                     className="mr-2"
@@ -323,8 +399,14 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
         return (
           <div className="space-y-2">
             {field.options?.map((option) => {
+
+
               const optionValue = typeof option === 'string' ? option : option.value
+
+
+
               const optionLabel = typeof option === 'string' ? option : option.label
+
               return (
                 <label key={optionValue} className="flex items-center">
                   <input
@@ -373,6 +455,8 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
                 onChange?.(JSON.parse(e.target.value))
               } catch {
               }
+
+
             }}
             className={`textarea font-mono text-sm ${error ? 'border-red-500' : ''}`}
             rows={field.rows || 6}
@@ -410,7 +494,10 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
           <input
             type="file"
             onChange={(e) => {
+
+
               const file = e.target.files?.[0]
+
               if (file) onChange?.(file.name)
             }}
             className={`input ${error ? 'border-red-500' : ''}`}
@@ -469,6 +556,7 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
           />
         )
     }
+
   }
 
   return (
@@ -492,4 +580,10 @@ export function FieldRenderer({ field, value, onChange, readonly = false, error,
     </div>
   )
 }
-// CIL[END chunk_id="FieldRenderer_fieldrenderer_1783927912"]
+// CIL[DOC-VECTOR type="context" content="purpose='Render a schema-driven form field with the appropriate input or read-only display'; No verified external callers; imports: .framework/src/types/types.ts,.framework/src/components/ui/RichTextEditor.tsx"]
+// CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
+// CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified"]
+// CIL[DOC-VECTOR type="constraint" content="Standard runtime; no special invariants documented"]
+// CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+// CIL[END stable_id="~/.framework/src/components/shared/FieldRenderer.tsx:FieldRenderer:component"]