spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/src/components/app-shell/GenericListPage.tsx

@@ -14,15 +14,14 @@ import { DataStats } from '../runtime/DataStats'
 import { DataFilters } from '../runtime/DataFilters'
 import { DataTable } from '../runtime/DataTable'
 import { PageInstructions } from '../admin/PageInstructions'
+// CIL[END stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:module_header:module_header"]
 // CIL[DOC-VECTOR type="context" content="purpose='Imports and module setup for the generic list page'; No verified external callers; imports: .framework/src/hooks/useListSchema.ts,.framework/src/hooks/useEntityList.ts,.framework/src/components/runtime/DataHeader.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/app-shell/GenericListPage.tsx:module_header:module_header"]
 
-// CIL[BEGIN stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:genericlistpageprops:interface" type="interface" identity="genericlistpageprops" parent="~/.framework/src/components/app-shell/GenericListPage.tsx"]
 // CIL[DOC-MACRO purpose="Props interface for GenericListPage"]
 // CIL[DOC-RESPONSIBILITY responsibility="Define the expected props for the list page"]
 // CIL[DOC-CONTEXT module="app-shell" layer="framework" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/app-shell/GenericListPage.tsx,.framework/src/components/runtime/DataFilters.tsx,.framework/src/components/runtime/DataHeader.tsx,.framework/src/components/runtime/DataStats.tsx,.framework/src/components/runtime/DataTable.tsx,.framework/src/hooks/useEntityList.ts,.framework/src/hooks/useListSchema.ts"]
@@ -30,21 +29,21 @@ import { PageInstructions } from '../admin/PageInstructions'
 // CIL[DOC-MICRO logic_summary="TypeScript interface describing typeSlug, viewSlug, appPrefix, and detailPath" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:GenericListPageProps:interface" type="interface" identity="GenericListPageProps" parent="~/.framework/src/components/app-shell/GenericListPage.tsx"]
 interface GenericListPageProps {
   typeSlug: string
   viewSlug?: string
   appPrefix: string
   detailPath: string
 }
+// CIL[END stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:GenericListPageProps:interface"]
 // CIL[DOC-VECTOR type="context" content="purpose='Props interface for GenericListPage'; No verified external callers; imports: .framework/src/hooks/useListSchema.ts,.framework/src/hooks/useEntityList.ts,.framework/src/components/runtime/DataHeader.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/app-shell/GenericListPage.tsx:genericlistpageprops:interface"]
 
-// CIL[BEGIN stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:genericlistpage:function" type="function" identity="genericlistpage" parent="~/.framework/src/components/app-shell/GenericListPage.tsx"]
 // CIL[DOC-MACRO purpose="Render the generic list page for an app type"]
 // CIL[DOC-RESPONSIBILITY responsibility="Display a sortable, filterable data table with schema-driven headers, stats, filters, and instructions"]
 // CIL[DOC-CONTEXT module="app-shell" layer="framework" related_files=".framework/src/components/admin/PageInstructions.tsx,.framework/src/components/app-shell/GenericListPage.tsx,.framework/src/components/runtime/DataFilters.tsx,.framework/src/components/runtime/DataHeader.tsx,.framework/src/components/runtime/DataStats.tsx,.framework/src/components/runtime/DataTable.tsx,.framework/src/hooks/useEntityList.ts,.framework/src/hooks/useListSchema.ts"]
@@ -52,6 +51,7 @@ interface GenericListPageProps {
 // CIL[DOC-MICRO logic_summary="Resolve the list schema, build a config, load entity data, and render the list page with header, instructions, stats, filters, and table" notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:GenericListPage:component" type="component" identity="GenericListPage" parent="~/.framework/src/components/app-shell/GenericListPage.tsx"]
 export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: GenericListPageProps) {
   const resolvedViewSlug = viewSlug || 'default_list'
 
@@ -61,8 +61,13 @@ export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: G
     viewSlug: resolvedViewSlug
   })
 
+  // nav_item `view` is a single slug shared by list + detail pages; a
+  // detail-shaped view (sections, no fields) must not resolve here.
+  const resolvedListView = view && ((view as any).type === 'list' || (view as any).fields)
+    ? view
+    : schema?.views?.default_list ?? view
 
-  const config = view && schema ? {
+  const config = resolvedListView && schema ? {
     entity: 'items',
     typeSlug,
     icon: 'database',
@@ -71,12 +76,22 @@ export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: G
       listAction: 'list'
     },
     list: {
-      defaultSort: (view as any).default_sort || { field: 'created_at', direction: 'desc' },
-      stats: (view as any).stats || [],
-      filters: (view as any).filters || [],
-      columns: Object.entries((view as any).fields || {}).map(([key, fieldConfig]: [string, any]) => ({
+      defaultSort: (resolvedListView as any).default_sort || { field: 'created_at', direction: 'desc' },
+      stats: (resolvedListView as any).stats || [],
+      // Docs allow bare field-name strings; DataFilters needs full
+      // EntityFilter objects, so normalize strings against the schema.
+      filters: ((resolvedListView as any).filters || []).map((f: any) => {
+        if (typeof f !== 'string') return f
+        const field: any = (schema.fields as any)?.[f] || (schema.fields as any)?.[f.replace(/^data\./, '')] || {}
+        const options = (field.options || []).map((o: any) => (typeof o === 'string' ? o : o.value))
+        const type = field.data_type === 'boolean' || field.data_type === 'checkbox'
+          ? 'boolean'
+          : options.length ? 'enum' : 'search'
+        return { key: f, label: field.label || f, type, options: options.length ? options : undefined }
+      }),
+      columns: Object.entries((resolvedListView as any).fields || {}).map(([key, fieldConfig]: [string, any]) => ({
         key,
-        label: schema.fields[key]?.label || key,
+        label: schema.fields[key]?.label || schema.fields[key.replace(/^data\./, '')]?.label || key,
         sortable: fieldConfig.sortable !== false,
         display_type: fieldConfig.display_type
       }))
@@ -115,32 +130,13 @@ export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: G
   return (
     <div className="space-y-6">
       <DataHeader
-        title={schema?.fields ? Object.keys(schema.fields).length > 0 ? (view as any)?.label || typeSlug : typeSlug : typeSlug}
+        title={schema?.fields ? Object.keys(schema.fields).length > 0 ? (resolvedListView as any)?.label || typeSlug : typeSlug : typeSlug}
         icon={config.icon}
         description={`Manage ${typeSlug}`}
         newButtonHref={`${appPrefix}/${detailPath}/new`}
       />
 
-      <PageInstructions
-        sections={[
-          {
-            title: 'What this page is for',
-            content: `This page lists all ${typeSlug} records for this app. It displays the stored records, their field values, and current status based on the app type schema.`,
-          },
-          {
-            title: 'How to find records',
-            content: `Use the filters above the table to narrow results. Click any column header to sort ascending or descending. The available columns and filters are defined by the type's design schema.`,
-          },
-          {
-            title: 'How to create, view, and edit records',
-            content: `Click the New button in the top-right to create a new ${typeSlug}. Click any row to open its detail view. From the detail view you can edit field values or delete the record. Permissions may restrict which actions are available to your role.`,
-          },
-          {
-            title: 'Understanding the stats',
-            content: `The cards above the table show summary counts and key metrics for this record type. Use them to quickly assess volume and status before drilling into the list.`,
-          },
-        ]}
-      />
+      <PageInstructions pageKey="runtime-list" />
 
       <DataStats
         stats={config.list.stats}
@@ -170,10 +166,10 @@ export function GenericListPage({ typeSlug, viewSlug, appPrefix, detailPath }: G
     </div>
   )
 }
+// CIL[END stable_id="~/.framework/src/components/app-shell/GenericListPage.tsx:GenericListPage:component"]
 // CIL[DOC-VECTOR type="context" content="purpose='Render the generic list page for an app type'; No verified external callers; imports: .framework/src/hooks/useListSchema.ts,.framework/src/hooks/useEntityList.ts,.framework/src/components/runtime/DataHeader.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/app-shell/GenericListPage.tsx:genericlistpage:function"]

package/.framework/src/components/auth/TurnstileWidget.tsx

@@ -16,12 +16,15 @@ export const turnstileEnabled = !!SITE_KEY
 export function TurnstileWidget({ onToken }: { onToken: (token: string | null) => void }) {
   if (!SITE_KEY) return null
   return (
-    <Turnstile
-      siteKey={SITE_KEY}
-      onSuccess={onToken}
-      onExpire={() => onToken(null)}
-      onError={() => onToken(null)}
-    />
+    <div className="flex justify-center">
+      <Turnstile
+        siteKey={SITE_KEY}
+        options={{ theme: 'light' }}
+        onSuccess={onToken}
+        onExpire={() => onToken(null)}
+        onError={() => onToken(null)}
+      />
+    </div>
   )
 }
 // CIL[END stable_id="~/.framework/src/components/auth/TurnstileWidget.tsx:module_header:module_header"]

package/.framework/src/components/kb/KBArticleEditor.tsx

@@ -1,4 +1,12 @@
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Schema-driven knowledge-article editor — loads a record's design_schema and renders view/edit/new modes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load type schema + article record, render main fields (title/content/description) plus a metadata sidebar, and handle save/publish/delete"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=".framework/src/components/ui/RichTextEditor.tsx, .framework/src/components/shared/SchemaFields.tsx, .framework/functions/_shared/kb.ts"]
+// CIL[DOC-CONTRACT inputs="KBArticleEditorProps (typeSlug, mode, articleId, onPublish?, sidebarFieldNames?, ...)" outputs="React editor view" errors="inline banner" side_effects="admin-data get/create/update/remove, optional custom onPublish or /api/kb publish"]
+// CIL[DOC-MICRO logic_summary="Fields split into main (title, content) and sidebar (everything else, optionally allowlisted via sidebarFieldNames); handleSave always saves first, then publishes via onPublish or /api/kb?action=publish; header wraps and truncates gracefully so long titles/dates never clip or overlap the action buttons" notable_decisions="custom onPublish callers save at current status — the backend decides publication after validation so a hard-failing draft never becomes published"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
+// CIL[DOC-AUDIENCE audience="developers"]
 
 
 
@@ -49,6 +57,13 @@ import { ArrowLeft, Save, Send, Trash, X, Edit } from 'lucide-react'
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:KBArticleEditorProps:interface" type="interface" identity="KBArticleEditorProps" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Props interface for KBArticleEditor"]
+// CIL[DOC-RESPONSIBILITY responsibility="Declare mode, record id, permission flags, callbacks, publish overrides, and the sidebar field allowlist"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="onPublish replaces the default /api/kb publish call; sidebarFieldNames filters the metadata sidebar (empty array hides it entirely while still seeding formData)" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export interface KBArticleEditorProps {
   typeSlug: string
   typeName?: string
@@ -109,6 +124,13 @@ export interface KBArticleEditorProps {
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:KBRecord:interface" type="interface" identity="KBRecord" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Minimal runtime-record shape the editor consumes"]
+// CIL[DOC-RESPONSIBILITY responsibility="Type the article record's id/title/status/created_at plus an open data bag"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="none" outputs="none" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Loose shape — extra record fields pass through the index signature" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 interface KBRecord {
   id: string
   title: string
@@ -146,6 +168,13 @@ interface KBRecord {
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:getFieldDefault:function" type="function" identity="getFieldDefault" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Default value for a schema field when no record value exists"]
+// CIL[DOC-RESPONSIBILITY responsibility="Map data_type to a sensible empty value: [] for multiselect/array, false for booleans, null for numbers/dates, first option for selects, '' otherwise"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="def: schema field definition" outputs="default value" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Branch on data_type; select/radio take the first option's value" notable_decisions="[]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function getFieldDefault(def: any): any {
   if (def.data_type === 'multiselect' || (def.data_type === 'array' && def.options)) return []
   if (def.data_type === 'boolean' || def.data_type === 'checkbox' || def.data_type === 'switch') return false
@@ -189,6 +218,13 @@ function getFieldDefault(def: any): any {
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:initialFormData:function" type="function" identity="initialFormData" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Seed the form's initial values from schema + existing record"]
+// CIL[DOC-RESPONSIBILITY responsibility="Hydrate every schema field from the record (system fields top-level, data fields under record.data) or fall back to field defaults"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=""]
+// CIL[DOC-CONTRACT inputs="schema, record|null" outputs="formData object" errors="none" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="New records additionally get status='draft' and empty title/content/description" notable_decisions="system:true fields read record[field] directly; others read record.data[field]"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 function initialFormData(schema: any, record: KBRecord | null): Record<string, any> {
   const values: Record<string, any> = {}
   Object.entries(schema?.fields || {}).forEach(([fieldName, fieldDef]: [string, any]) => {
@@ -237,6 +273,13 @@ function initialFormData(schema: any, record: KBRecord | null): Record<string, a
 
 
 // CIL[BEGIN stable_id="~/.framework/src/components/kb/KBArticleEditor.tsx:KBArticleEditor:component" type="component" identity="KBArticleEditor" parent="~/.framework/src/components/kb/KBArticleEditor.tsx"]
+// CIL[DOC-MACRO purpose="Render and operate the schema-driven article editor"]
+// CIL[DOC-RESPONSIBILITY responsibility="Load schema+record, hydrate formData, render the wrapping header, main fields, and metadata sidebar, and run save/publish/delete flows"]
+// CIL[DOC-CONTEXT module=".framework/src/components/kb/KBArticleEditor.tsx" layer="framework_ui" related_files=".framework/src/components/ui/RichTextEditor.tsx, .framework/src/components/shared/SchemaFields.tsx"]
+// CIL[DOC-CONTRACT inputs="KBArticleEditorProps" outputs="editor JSX" errors="save/publish/delete failures in an inline banner" side_effects="admin-data CRUD, kb publish or custom onPublish callback"]
+// CIL[DOC-MICRO logic_summary="Header uses flex-wrap + min-w-0/truncate so title, badge and date wrap instead of clipping behind the buttons; onFormChange fires only for post-init edits via a ref flag; publish saves first then delegates to onPublish or /api/kb?action=publish" notable_decisions="DOMPurify sanitizes stored rich text in view mode (stored-XSS defense)"]
+// CIL[DOC-CONFIDENCE pass="second" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="stable"]
 export function KBArticleEditor({
   typeSlug,
   typeName,
@@ -486,27 +529,27 @@ export function KBArticleEditor({
 
   return (
     <div className="flex flex-col h-full">
-      <div className="px-6 py-3 border-b border-border shrink-0 flex items-center justify-between gap-4">
-        <div className="flex items-center gap-3 min-w-0">
+      <div className="px-6 py-3 border-b border-border shrink-0 flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
+        <div className="flex items-center gap-3 min-w-0 flex-wrap">
           {onBack && (
             <Button variant="ghost" size="sm" onClick={onBack} className="gap-1 text-muted-foreground">
               <ArrowLeft className="h-3.5 w-3.5" /> KB
             </Button>
           )}
-          <h1 className="text-base font-semibold truncate">
+          <h1 className="text-base font-semibold truncate max-w-[44ch]">
             {isCreating ? `New ${typeName || typeSlug}` : (record?.title || 'Edit Article')}
           </h1>
           {!isCreating && record && (
-            <div className="hidden sm:flex items-center gap-2">
+            <div className="hidden sm:flex items-center gap-2 shrink-0">
               <Badge variant={record.status === 'published' ? 'default' : 'outline'} className="text-xs">
                 {record.status || 'draft'}
               </Badge>
-              <span className="text-xs text-muted-foreground">{formatDateTime(record.created_at)}</span>
+              <span className="text-xs text-muted-foreground whitespace-nowrap">{formatDateTime(record.created_at)}</span>
             </div>
           )}
         </div>
 
-        <div className="flex items-center gap-2 shrink-0">
+        <div className="flex items-center gap-2 flex-wrap">
           {mode === 'view' && articleId && canEdit && (
             <Button size="sm" variant="outline" onClick={() => articleId && onEdit?.(articleId)} className="gap-1">
               <Edit className="h-3.5 w-3.5" /> Edit

package/.framework/src/components/layout/Layout.tsx

@@ -11,6 +11,7 @@
 import React, { useState } from 'react'
 import { Sidebar, SidebarContent } from './Sidebar'
 import { useAuth } from '../../contexts/AuthContext'
+import { useBranding } from '../../hooks/useBranding'
 import { useLocation } from 'react-router-dom'
 // CIL[DOC-VECTOR type="context" content="purpose='Module imports and top-level declarations for the Layout component.'; No verified external callers; imports: .framework/src/components/layout/Sidebar.tsx,.framework/src/contexts/AuthContext.tsx"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only"]
@@ -50,6 +51,7 @@ interface LayoutProps {
 export function Layout({ children }: LayoutProps) {
   const [sidebarOpen, setSidebarOpen] = useState(false)
   const { user, logout } = useAuth()
+  const branding = useBranding()
   const location = useLocation()
 
   const isActive = (href: string) =>
@@ -87,8 +89,8 @@ export function Layout({ children }: LayoutProps) {
           </svg>
         </button>
         <div className="flex items-center gap-3">
-          <img src="/spine-logo.svg" alt="Spine Framework" className="h-8 w-auto" />
-          <span className="text-lg font-semibold tracking-tight text-slate-900 whitespace-nowrap">Spine Framework</span>
+          <img src={branding.logo_url} alt={branding.app_name} className="h-8 w-auto" />
+          <span className="text-lg font-semibold tracking-tight text-slate-900 whitespace-nowrap">{branding.title}</span>
         </div>
       </div>