spine-framework 0.3.124 → 0.3.126

package/.framework/src/hooks/useSchemaRecord.ts

@@ -1,39 +1,28 @@
-/**
- * @module src/hooks/useSchemaRecord
- * @audience installer
- * @layer frontend-hook
- * @stability stable
- *
- * Schema-record data management hooks. Two complementary hooks:
- *
- * - **`useSchemaRecord`** — given an already-fetched record and its schema
- *   type, returns structured `FieldDefinition[]`, a managed `data` state
- *   seeded from `record.data` with schema defaults, and field setters.
- *   Used on detail/edit pages where the record is fetched by a parent hook.
- *
- * - **`useTypeSelection`** — fetches all types of a given `kind` and exposes
- *   a `selectedTypeId` state. Used on create pages for the type-first flow
- *   where the user picks a type before filling in fields.
- *
- * **Data seeding invariant:** `useSchemaRecord` re-seeds `data` state only
- * when `record.id` or `schemaType.id` changes, not on every render. This
- * prevents losing unsaved edits during re-renders.
- *
- * @seeAlso src/hooks/useEntityRecord.ts (fetches the record passed here)
- * @seeAlso src/hooks/useForm.ts (consumes FieldDefinition[] from this hook)
- * @seeAlso src/types/types.ts (FieldDefinition, ItemType)
- */
-
 import { useState, useEffect, useCallback } from 'react'
 import { apiFetch } from '../lib/api'
 import { FieldDefinition, ItemType } from '../types/types'
 
-// ─── TYPES ───────────────────────────────────────────────────────────────────
 
-/**
- * A record from the `types` table as loaded for schema resolution.
- * @prop design_schema - Full design schema including fields and views
- */
+
+
+
+
+
+// CIL[BEGIN chunk_id="uschemarecord_module_header_1783718716" type="module_header" identity="module_header" parent="none"]
+// CIL[DOC-MACRO purpose="Define SchemaType interface for type records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the SchemaType interface definition"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with id, name, slug, optional fields, and design_schema" 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-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.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"]
 export interface SchemaType {
   id: string
   name: string
@@ -44,11 +33,21 @@ export interface SchemaType {
   app_id?: string
   design_schema: ItemType['design_schema']
 }
-
-/**
- * A generic record that may carry its resolved type in a nested `type` join.
- * @prop data - The JSONB `data` column; all custom field values live here
- */
+// CIL[END chunk_id="uschemarecord_module_header_1783718716"]
+// CIL[BEGIN chunk_id="uschemarecord_schemarecord_1783718716" type="interface" identity="SchemaRecord" parent="none"]
+// CIL[DOC-MACRO purpose="Define SchemaRecord interface for generic records"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the SchemaRecord interface definition"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with id, optional type_id/type, data JSONB, and index signature" 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-hook. 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, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .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"]
 export interface SchemaRecord {
   id: string
   type_id?: string
@@ -56,23 +55,39 @@ export interface SchemaRecord {
   data: Record<string, any>
   [key: string]: any
 }
-
-/** Options for `useSchemaRecord`. */
+// CIL[END chunk_id="uschemarecord_schemarecord_1783718716"]
+// CIL[BEGIN chunk_id="uschemarecord_options_1783718716" type="interface" identity="UseSchemaRecordOptions" parent="none"]
+// CIL[DOC-MACRO purpose="Define options interface for useSchemaRecord hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the UseSchemaRecordOptions interface definition"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/src/pages/admin/IntegrationsPage.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Simple interface with typeApiKind field" 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-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, custom/apps/cortex/pages/operations/OperationsDashboard.tsx, .framework/src/pages/admin/TypeDetailPage.tsx, .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"]
 export interface UseSchemaRecordOptions {
-  typeApiKind: string // e.g. 'account', 'person', 'item'
+  typeApiKind: string
 }
-
-/**
- * Return value of `useSchemaRecord`.
- *
- * @prop fields - Ordered `FieldDefinition[]` from schema; empty if no schema
- * @prop data - Managed field values (seeded from `record.data` + defaults)
- * @prop setData - Replace the entire data map
- * @prop setField - Update a single field by name
- * @prop schemaType - The resolved schema type (passed through)
- * @prop loading - Always false (data is derived, not fetched here)
- * @prop error - Always null
- */
+// CIL[END chunk_id="uschemarecord_options_1783718716"]
+// CIL[BEGIN chunk_id="uschemarecord_result_1783718716" type="interface" identity="UseSchemaRecordResult" parent="none"]
+// CIL[DOC-MACRO purpose="Define return type for useSchemaRecord hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the UseSchemaRecordResult interface definition"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[\".framework/src/pages/admin/TypeDetailPage.tsx\",\".framework/functions/_shared/schema-utils.ts\",\".framework/functions/_shared/principal.ts\",\".framework/functions/_shared/db.ts\",\"custom/apps/cortex/pages/operations/OperationsDashboard.tsx\",\"\\\"]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with fields array, managed data, setters, and metadata" 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-hook. Direct callers: 0. Direct calls: 0. Related files: .framework/src/pages/admin/TypeDetailPage.tsx, .framework/functions/_shared/schema-utils.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, custom/apps/cortex/pages/operations/OperationsDashboard.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 interface UseSchemaRecordResult {
   fields: FieldDefinition[]
   data: Record<string, any>
@@ -82,38 +97,29 @@ export interface UseSchemaRecordResult {
   loading: boolean
   error: string | null
 }
-
-// ─── useSchemaRecord ─────────────────────────────────────────────────────────
-
-/**
- * Given an already-fetched record and its resolved schema type, returns
- * structured field definitions and a managed data state for the record's
- * `.data` JSONB column, with schema defaults seeded on load.
- *
- * Does NOT fetch anything — this is a pure derived-state hook.
- *
- * @param record - Fetched record (or null while loading)
- * @param schemaType - Resolved schema type (or null while loading)
- * @returns `UseSchemaRecordResult`
- *
- * @inputSpec record.data: Record<string, any> | undefined — custom field values
- * @inputSpec schemaType.design_schema.fields: FieldDefinition map
- * @outputSpec fields: FieldDefinition[] — ordered array with `.name` injected
- * @sideEffects React state mutations (data re-seed on record/type change only)
- * @calledBy DataDetailPage.tsx, create pages
- *
- * @example
- * ```tsx
- * const { fields, data, setField } = useSchemaRecord(record, schemaType)
- * ```
- */
+// CIL[END chunk_id="uschemarecord_result_1783718716"]
+// CIL[BEGIN chunk_id="uschemarecord_usefunction_1783718716" type="function" identity="useSchemaRecord" parent="none"]
+// CIL[DOC-LEARNING topic="runtime-type:generic/schema_defaults" content="useSchemaRecord seeds empty record state from schemaType.design_schema.fields using each field's default value. It provides the schema used by GenericDetailPage for new records."]
+// CIL[DOC-NOTE type="design_schema_caveat" content="A field missing a default will be undefined. The hook depends on the type record being loaded from the types table, which can fail if the type slug or kind is wrong."]
+// CIL[DOC-MACRO purpose="Manage record data state with schema defaults and field definitions"]
+// CIL[DOC-RESPONSIBILITY responsibility="Provide derived state management for record data and fields"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="managed data, field definitions, setters" errors="none" side_effects="React state mutations"]
+// CIL[DOC-MICRO logic_summary="Seed data from record.data with schema defaults, provide field setters, re-seed only on record/type change" notable_decisions="['reseed_on_id_change_only', 'default_value_seeding']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. 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 useSchemaRecord(
   record: SchemaRecord | null,
   schemaType: SchemaType | null
 ): UseSchemaRecordResult {
   const [data, setDataState] = useState<Record<string, any>>({})
 
-  // Re-seed data state only when the record id or schema type id changes
   const recordId = record?.id ?? null
   const schemaTypeId = schemaType?.id ?? null
 
@@ -122,7 +128,6 @@ export function useSchemaRecord(
 
     const base = record.data ? { ...record.data } : {}
 
-    // Seed defaults for fields that have no value
     if (schemaType?.design_schema?.fields) {
       for (const [name, field] of Object.entries(schemaType.design_schema.fields)) {
         if (base[name] === undefined && (field as any).defaultValue !== undefined) {
@@ -132,7 +137,6 @@ export function useSchemaRecord(
     }
 
     setDataState(base)
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [recordId, schemaTypeId])
 
   const setData = useCallback((newData: Record<string, any>) => {
@@ -157,19 +161,21 @@ export function useSchemaRecord(
     error: null
   }
 }
-
-// ─── useTypeSelection ─────────────────────────────────────────────────────────
-
-/**
- * Return value of `useTypeSelection`.
- *
- * @prop types - All active types of the requested kind
- * @prop selectedType - The full `SchemaType` for `selectedTypeId`, or null
- * @prop selectedTypeId - Controlled string state for the `<select>` value
- * @prop setSelectedTypeId - Setter for `selectedTypeId`
- * @prop loading - True while fetching types
- * @prop error - Error message or null
- */
+// CIL[END chunk_id="uschemarecord_usefunction_1783718716"]
+// CIL[BEGIN chunk_id="uschemarecord_typeselectionresult_1783718716" type="interface" identity="UseTypeSelectionResult" parent="none"]
+// CIL[DOC-MACRO purpose="Define return type for useTypeSelection hook"]
+// CIL[DOC-RESPONSIBILITY responsibility="Own the UseTypeSelectionResult interface definition"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="interface definition" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Interface with types array, selected type/id, setters, and loading state" 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-hook. 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 interface UseTypeSelectionResult {
   types: SchemaType[]
   selectedType: SchemaType | null
@@ -178,19 +184,21 @@ export interface UseTypeSelectionResult {
   loading: boolean
   error: string | null
 }
-
-/**
- * Fetches all active types of a given `kind` and exposes a controlled
- * `selectedTypeId` state for the type-first create flow.
- *
- * @param kind - Type kind: `'account'`, `'person'`, `'item'`, etc.
- * @returns `UseTypeSelectionResult`
- *
- * @inputSpec kind: string — passed as `?kind=<kind>&is_active=true` to `/api/types`
- * @outputSpec types: SchemaType[] — active types; empty while loading
- * @sideEffects Network request via apiFetch on mount and kind change
- * @calledBy Create pages (e.g. AccountCreatePage, ItemCreatePage)
- */
+// CIL[END chunk_id="uschemarecord_typeselectionresult_1783718716"]
+// CIL[BEGIN chunk_id="uschemarecord_typeselection_1783718716" type="function" identity="useTypeSelection" parent="none"]
+// CIL[DOC-MACRO purpose="Fetch and manage type selection for create flows"]
+// CIL[DOC-RESPONSIBILITY responsibility="Fetch active types by kind and manage selection state"]
+// CIL[DOC-CONTEXT module="useSchemaRecord" layer="frontend-hook" related_files="[]"]
+// CIL[DOC-CONTRACT inputs="none" outputs="types array, selected type, selection state" errors="network errors" side_effects="Network requests, React state mutations"]
+// CIL[DOC-MICRO logic_summary="Fetch active types by kind on mount and kind change, manage selectedTypeId state, resolve selectedType by id" notable_decisions="['controlled_selection_state', 'fetch_on_kind_change']"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.95" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-VECTOR type="context" content="Layer: frontend-hook. 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 useTypeSelection(kind: string): UseTypeSelectionResult {
   const [types, setTypes] = useState<SchemaType[]>([])
   const [selectedTypeId, setSelectedTypeId] = useState('')
@@ -221,3 +229,4 @@ export function useTypeSelection(kind: string): UseTypeSelectionResult {
 
   return { types, selectedType, selectedTypeId, setSelectedTypeId, loading, error }
 }
+// CIL[END chunk_id="uschemarecord_typeselection_1783718716"]