spine-framework 0.3.124 → 0.3.126

package/.framework/src/components/ui/Form.tsx

@@ -1,53 +1,61 @@
-/**
- * @module src/components/ui/Form
- * @audience installer
- * @layer frontend-component
- * @stability stable
- *
- * Schema-driven form layout components.
- *
- * **`Form`** — renders a `<form>` element from an ordered `FieldDefinition[]`
- * array via `FieldRenderer`. Manages touched-based error display (errors only
- * shown for fields the user has interacted with). Includes Submit + optional
- * Cancel buttons.
- *
- * **`FormField`** — single field wrapper delegating to `FieldRenderer` with
- * touched-based error display.
- *
- * **`FormSection`** — optional titled group container for logical field
- * groups within a form.
- *
- * **`FormRow`** / **`FormColumn`** — two-column responsive grid layout
- * helpers. `FormColumn` accepts `span=2` to span both columns.
- *
- * @seeAlso src/components/shared/FieldRenderer.tsx
- * @seeAlso src/hooks/useForm.ts (state management companion)
- */
 
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="Form_moduleheader_1783907801" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and form dependencies"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies for form components"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React, FieldDefinition, FieldRenderer, Button, cn" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, types, field renderer, button component, and utility function" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" 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/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.tsx, .framework/src/pages/admin/RolesPage.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import { FieldDefinition } from '../../types/types'
 import { FieldRenderer } from '../shared/FieldRenderer'
 import { Button } from './button'
 import { cn } from '../../lib/utils'
-
-/**
- * Props for `Form`.
- *
- * @prop fields - Ordered field definitions to render
- * @prop data - Controlled field values keyed by field name
- * @prop errors - Validation errors per field name
- * @prop touched - Map of fields that have been interacted with
- * @prop onChange - `(field, value)` change callback
- * @prop onBlur - `(field)` blur callback for marking a field as touched
- * @prop onSubmit - Form submit handler (receives the native `FormEvent`)
- * @prop isSubmitting - Shows spinner on submit button when true
- * @prop submitText - Submit button label (default: `'Submit'`)
- * @prop cancelText - Cancel button label (default: `'Cancel'`)
- * @prop onCancel - Cancel button callback
- * @prop showCancel - Shows the cancel button (default: `false`)
- * @prop disabled - Disables all fields and the submit button
- * @prop className - Additional Tailwind classes for the `<form>` element
- */
+// CIL[END chunk_id="Form_moduleheader_1783907801"]
+// CIL[BEGIN chunk_id="Form_formprops_1783907801" type="interface" identity="FormProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define main form component props interface"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify all props needed for Form component configuration"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[\".framework/src/components/ui/dialog.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FormProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Comprehensive props for fields, data, validation, and form actions" 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/components/ui/dialog.tsx, .framework/src/components/ui/table-primitives.tsx, .framework/functions/_shared/schema-utils.ts, 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface FormProps {
   fields: FieldDefinition[]
   data: Record<string, any>
@@ -64,14 +72,21 @@ interface FormProps {
   disabled?: boolean
   className?: string
 }
-
-/**
- * Schema-driven `<form>` with submit + optional cancel actions.
- *
- * @param props - `FormProps`
- * @returns Form element with field list and action buttons
- * @sideEffects Calls `e.preventDefault()` on submit before forwarding to `onSubmit`
- */
+// CIL[END chunk_id="Form_formprops_1783907801"]
+// CIL[BEGIN chunk_id="Form_form_1783907801" type="function" identity="Form" parent="none"]
+// CIL[DOC-MACRO purpose="Render schema-driven form with validation and actions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Handle form submission, field rendering, and error display"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/table-primitives.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Form element" errors="none" side_effects="Calls onSubmit, onChange, onBlur callbacks"]
+// CIL[DOC-MICRO logic_summary="Maps fields to FieldRenderer, shows errors only for touched fields" 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: custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/table-primitives.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function Form({
   fields,
   data,
@@ -142,16 +157,21 @@ export function Form({
     </form>
   )
 }
-
-/**
- * Props for `FormField`.
- *
- * @prop field - Field definition
- * @prop value - Current value
- * @prop error - Validation error string
- * @prop touched - Whether this field has been interacted with (gates error display)
- * @prop onChange / onBlur / readonly - Passed through to `FieldRenderer`
- */
+// CIL[END chunk_id="Form_form_1783907801"]
+// CIL[BEGIN chunk_id="Form_formfieldprops_1783907801" type="interface" identity="FormFieldProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props for single form field wrapper"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify props needed for individual field rendering"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FormFieldProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Props for field definition, value, error state, and callbacks" 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/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/IntegrationsPage.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface FormFieldProps {
   field: FieldDefinition
   value: any
@@ -161,14 +181,21 @@ interface FormFieldProps {
   onBlur?: () => void
   readonly?: boolean
 }
-
-/**
- * Single field with touched-gated error display.
- *
- * @param props - `FormFieldProps`
- * @returns `FieldRenderer` instance with error shown only when touched
- * @sideEffects none (delegates to `onChange` / `onBlur`)
- */
+// CIL[END chunk_id="Form_formfieldprops_1783907801"]
+// CIL[BEGIN chunk_id="Form_formfield_1783907801" type="function" identity="FormField" parent="none"]
+// CIL[DOC-MACRO purpose="Render single form field with touched-gated error display"]
+// CIL[DOC-RESPONSIBILITY responsibility="Wrap FieldRenderer with conditional error visibility"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/db.ts\",\"custom/apps/portal/pages/ContentPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FieldRenderer component" errors="none" side_effects="Delegates to onChange/onBlur"]
+// CIL[DOC-MICRO logic_summary="Passes error to FieldRenderer only when field has been touched" 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/functions/_shared/schema-utils.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/db.ts, 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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function FormField({
   field,
   value,
@@ -189,27 +216,42 @@ export function FormField({
     />
   )
 }
-
-/**
- * Props for `FormSection`.
- *
- * @prop title - Optional section heading
- * @prop description - Optional subtitle text
- */
+// CIL[END chunk_id="Form_formfield_1783907801"]
+// CIL[BEGIN chunk_id="Form_formsectionprops_1783907801" type="interface" identity="FormSectionProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props for form section container"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify props for grouping form fields with title/description"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FormSectionProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Props for optional title, description, children, and styling" 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: none."]
+// 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"]
 interface FormSectionProps {
   title?: string
   description?: string
   children: React.ReactNode
   className?: string
 }
-
-/**
- * Titled group container for a set of related form fields.
- *
- * @param props - `FormSectionProps`
- * @returns `<div>` with optional title/description and `children` below
- * @sideEffects none (pure rendering)
- */
+// CIL[END chunk_id="Form_formsectionprops_1783907801"]
+// CIL[BEGIN chunk_id="Form_formsection_1783907801" type="function" identity="FormSection" parent="none"]
+// CIL[DOC-MACRO purpose="Render titled group container for form fields"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display optional title/description with children content"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Styled div container" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Conditionally renders header section when title or description provided" 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: none."]
+// 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"]
 export function FormSection({ title, description, children, className }: FormSectionProps) {
   return (
     <div className={cn('space-y-4', className)}>
@@ -227,20 +269,40 @@ export function FormSection({ title, description, children, className }: FormSec
     </div>
   )
 }
-
-/** Props for `FormRow`. */
+// CIL[END chunk_id="Form_formsection_1783907801"]
+// CIL[BEGIN chunk_id="Form_formrowprops_1783907801" type="interface" identity="FormRowProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props for responsive form row container"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify props for two-column grid layout row"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FormRowProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Props for children content and optional styling classes" 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: none."]
+// 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"]
 interface FormRowProps {
   children: React.ReactNode
   className?: string
 }
-
-/**
- * Two-column responsive grid row for form fields.
- *
- * @param props - children + optional className
- * @returns `<div>` with `grid-cols-1 sm:grid-cols-2 gap-4`
- * @sideEffects none (pure rendering)
- */
+// CIL[END chunk_id="Form_formrowprops_1783907801"]
+// CIL[BEGIN chunk_id="Form_formrow_1783907801" type="function" identity="FormRow" parent="none"]
+// CIL[DOC-MACRO purpose="Render two-column responsive grid for form fields"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide responsive grid layout container"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Grid div container" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Uses Tailwind grid classes for responsive two-column layout" 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: none."]
+// 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"]
 export function FormRow({ children, className }: FormRowProps) {
   return (
     <div className={cn('grid grid-cols-1 sm:grid-cols-2 gap-4', className)}>
@@ -248,25 +310,41 @@ export function FormRow({ children, className }: FormRowProps) {
     </div>
   )
 }
-
-/**
- * Props for `FormColumn`.
- *
- * @prop span - Column span within a `FormRow` (1 or 2, default: 1)
- */
+// CIL[END chunk_id="Form_formrow_1783907801"]
+// CIL[BEGIN chunk_id="Form_formcolumnprops_1783907801" type="interface" identity="FormColumnProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props for form column within grid row"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify props for column span and content"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="FormColumnProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Props for children, column span (1 or 2), and styling" 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: none."]
+// 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"]
 interface FormColumnProps {
   children: React.ReactNode
   span?: 1 | 2
   className?: string
 }
-
-/**
- * Column within a `FormRow` grid.
- *
- * @param props - `FormColumnProps`
- * @returns `<div>` with appropriate `col-span` class
- * @sideEffects none (pure rendering)
- */
+// CIL[END chunk_id="Form_formcolumnprops_1783907801"]
+// CIL[BEGIN chunk_id="Form_formcolumn_1783907801" type="function" identity="FormColumn" parent="none"]
+// CIL[DOC-MACRO purpose="Render column within FormRow grid with span control"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide column container with configurable span"]
+// CIL[DOC-CONTEXT module="Form" layer="frontend-component" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Column div with span classes" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Maps span values to Tailwind col-span classes for grid layout" 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: none."]
+// 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"]
 export function FormColumn({ children, span = 1, className }: FormColumnProps) {
   const spanClasses = {
     1: 'col-span-1',
@@ -279,3 +357,4 @@ export function FormColumn({ children, span = 1, className }: FormColumnProps) {
     </div>
   )
 }
+// CIL[END chunk_id="Form_formcolumn_1783907801"]

package/.framework/src/components/ui/ItemCard.tsx

@@ -1,43 +1,50 @@
-/**
- * @module src/components/ui/ItemCard
- * @audience installer
- * @layer frontend-component
- * @stability stable
- *
- * Item display components for grid-based views.
- *
- * **`ItemCard`** — renders a single `Item` in either full (`compact=false`)
- * or compact (`compact=true`) form. Derives its display values from
- * `item.title`, `item.description`, and the first 3 entries of `item.data`.
- * Optional action buttons (`onView`, `onEdit`, `onDelete`) are shown when
- * `showActions=true`.
- *
- * **`ItemGrid`** — renders a responsive grid of `ItemCard` instances.
- * Shows a spinner on `loading=true` and an empty state with a doc icon
- * when `items` is empty.
- *
- * @seeAlso src/components/ui/ItemListView.tsx (combines with DataTable)
- * @seeAlso src/types/types.ts (Item, ItemType)
- * @seeAlso src/lib/utils.ts (formatDateTime, truncateText)
- */
 
+
+
+
+
+
+
+
+
+
+
+// CIL[BEGIN chunk_id="ItemCard_moduleheader_1783907801" type="module_header" identity="imports" parent="none"]
+// CIL[DOC-MACRO purpose="Import React and item display dependencies"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide all external dependencies for item card components"]
+// CIL[DOC-CONTEXT module="ItemCard" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="React, Item types, UI components, icons, utils" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Imports React, item types, badge, button, icons, and utility functions" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" 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/pages/admin/RolesPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/src/components/ui/dialog.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 import React from 'react'
 import { Item, ItemType } from '../../types/types'
 import { Badge } from './badge'
 import { Button } from './button'
 import { Box, FileText, Calendar, User, MoreVertical } from 'lucide-react';
 import { formatDateTime, truncateText } from '../../lib/utils'
-
-/**
- * Props for `ItemCard`.
- *
- * @prop item - `Item` with optional resolved `item_type` relation
- * @prop onEdit - Edit action callback
- * @prop onDelete - Delete action callback
- * @prop onView - View action callback
- * @prop showActions - Shows action buttons (default: `true`)
- * @prop compact - Condensed single-line layout (default: `false`)
- */
+// CIL[END chunk_id="ItemCard_moduleheader_1783907801"]
+// CIL[BEGIN chunk_id="ItemCard_itemcardprops_1783907801" type="interface" identity="ItemCardProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props for item card component"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify all props needed for ItemCard component configuration"]
+// CIL[DOC-CONTEXT module="ItemCard" layer="frontend-component" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/src/components/ui/dialog.tsx\",\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ItemCardProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Props for item data, action callbacks, and display options" 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/components/layout/Sidebar.tsx, .framework/src/components/ui/dialog.tsx, custom/apps/portal/pages/ContentPage.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface ItemCardProps {
   item: Item & { item_type?: ItemType | string }
   onEdit?: (item: Item) => void
@@ -46,14 +53,21 @@ interface ItemCardProps {
   showActions?: boolean
   compact?: boolean
 }
-
-/**
- * Item card with optional action buttons.
- *
- * @param props - `ItemCardProps`
- * @returns White rounded card in full or compact layout
- * @sideEffects none (delegates actions to `onEdit` / `onDelete` / `onView`)
- */
+// CIL[END chunk_id="ItemCard_itemcardprops_1783907801"]
+// CIL[BEGIN chunk_id="ItemCard_itemcard_1783907801" type="function" identity="ItemCard" parent="none"]
+// CIL[DOC-MACRO purpose="Render item card with optional actions in full or compact mode"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display item data with type badge, metadata, and action buttons"]
+// CIL[DOC-CONTEXT module="ItemCard" layer="frontend-component" related_files="[\"custom/apps/cortex/functions/custom_cil-embeddings.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/RolesPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Item card component" errors="none" side_effects="Calls action callbacks"]
+// CIL[DOC-MICRO logic_summary="Renders different layouts based on compact prop, extracts data from item" 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: custom/apps/cortex/functions/custom_cil-embeddings.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/RolesPage.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function ItemCard({
   item,
   onEdit,
@@ -224,15 +238,21 @@ export function ItemCard({
     </div>
   )
 }
-
-/**
- * Props for `ItemGrid`.
- *
- * @prop items - Typed item array with resolved `item_type`
- * @prop loading - Shows spinner while true
- * @prop compact - Passes compact mode to each `ItemCard`
- * @prop emptyMessage - Text shown when `items` is empty
- */
+// CIL[END chunk_id="ItemCard_itemcard_1783907801"]
+// CIL[BEGIN chunk_id="ItemCard_itemgridprops_1783907801" type="interface" identity="ItemGridProps" parent="none"]
+// CIL[DOC-MACRO purpose="Define props for item grid container"]
+// CIL[DOC-RESPONSIBILITY responsibility="Specify all props needed for ItemGrid component configuration"]
+// CIL[DOC-CONTEXT module="ItemCard" layer="frontend-component" related_files="[\".framework/src/components/layout/Sidebar.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="ItemGridProps interface" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Props for items array, loading state, actions, and display options" 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/components/layout/Sidebar.tsx, .framework/functions/_shared/principal.ts, .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/src/pages/admin/IntegrationsPage.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 interface ItemGridProps {
   items: (Item & { item_type: ItemType })[]
   loading?: boolean
@@ -242,14 +262,21 @@ interface ItemGridProps {
   compact?: boolean
   emptyMessage?: string
 }
-
-/**
- * Responsive card grid for items.
- *
- * @param props - `ItemGridProps`
- * @returns Responsive grid, loading spinner, or empty state
- * @sideEffects none (delegates actions to `onEdit` / `onDelete` / `onView`)
- */
+// CIL[END chunk_id="ItemCard_itemgridprops_1783907801"]
+// CIL[BEGIN chunk_id="ItemCard_itemgrid_1783907801" type="function" identity="ItemGrid" parent="none"]
+// CIL[DOC-MACRO purpose="Render responsive grid of item cards with loading and empty states"]
+// CIL[DOC-RESPONSIBILITY responsibility="Display items in grid layout with loading spinner and empty message"]
+// CIL[DOC-CONTEXT module="ItemCard" layer="frontend-component" related_files="[\"custom/apps/portal/pages/ContentPage.tsx\",\".framework/src/pages/admin/RolesPage.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/components/ui/dialog.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="Grid container or loading/empty states" errors="none" side_effects="Delegates to ItemCard actions"]
+// CIL[DOC-MICRO logic_summary="Maps items to ItemCard components, handles loading and empty states" 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: custom/apps/portal/pages/ContentPage.tsx, .framework/src/pages/admin/RolesPage.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/components/ui/dialog.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="implementation_pattern" content="" status="pending_human_input"]
+// CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
 export function ItemGrid({
   items,
   loading = false,
@@ -294,3 +321,4 @@ export function ItemGrid({
     </div>
   )
 }
+// CIL[END chunk_id="ItemCard_itemgrid_1783907801"]