@the-syllabus/analysis-renderers 0.2.0

package/src/cells/TemplateCardCell.tsx

@@ -0,0 +1,439 @@
+/**
+ * TemplateCardCell -- Schema-driven card renderer.
+ *
+ * Instead of hardcoding field→UI mapping in React, this cell renderer
+ * interprets a `card_template` JSON structure from the view definition.
+ * Each "slot" in the template maps to an atomic rendering block:
+ *
+ *   badge_row       -- Row of colored badges (category or semantic colors)
+ *   heading         -- Title text, optionally hidden when it matches a label
+ *   prose           -- Paragraph text with optional subdued state
+ *   chip_list       -- Array of string chips with optional link hints
+ *   evidence_trail  -- Multi-step evidence chain (prior -> current -> assessment)
+ *   key_value       -- Key-value pairs rendered as a compact table
+ *   separator       -- Visual divider
+ *
+ * Template schema (in renderer_config.card_template):
+ *   {
+ *     wrapper_class?: string,           -- CSS class for outer div
+ *     border_accent?: ColorRef,         -- Border-left color from design tokens
+ *     border_weight_field?: string,     -- Field to read for border thickness
+ *     border_weight_map?: Record<string, string>,  -- value -> CSS width
+ *     slots: SlotConfig[]               -- Ordered list of content blocks
+ *   }
+ *
+ * New renderers = new JSON. No React code needed.
+ */
+
+import React, { useState } from 'react';
+import { CellRendererProps } from '../types';
+import { useDesignTokens } from '../tokens/DesignTokenContext';
+import { EvidenceTrail, EvidenceTrailStep, EvidenceTrailItem } from '../components/EvidenceTrail';
+
+// ── Types ──────────────────────────────────────────────
+
+interface ColorRef {
+  category: string;
+  key_field: string;
+}
+
+interface BadgeConfig {
+  field: string;
+  color_mode: 'category' | 'semantic';
+  color_category?: string;
+  color_scale?: string;
+  transform?: 'lowercase' | 'uppercase' | 'titlecase';
+  value_map?: Record<string, string>;
+  default_value?: string;
+}
+
+interface EvidenceStepConfig {
+  label: string;
+  field: string;
+  variant: 'prior' | 'current' | 'assessment';
+  item_title_field?: string;
+  item_quote_field?: string;
+  item_cite_field?: string;
+  is_text?: boolean;
+}
+
+interface SlotConfig {
+  type: string;
+  field?: string;
+  label?: string;
+  // badge_row
+  badges?: BadgeConfig[];
+  // heading
+  hide_when_matches_label?: ColorRef;
+  // prose
+  subdued_when?: { field: string; equals: string };
+  // chip_list
+  link_title_pattern?: string;
+  // evidence_trail
+  steps?: EvidenceStepConfig[];
+  accent_from?: ColorRef;
+  collapsed_by_default?: boolean;
+  // key_value
+  entries?: Array<{ field: string; label: string }>;
+}
+
+interface CardTemplate {
+  wrapper_class?: string;
+  border_accent?: ColorRef;
+  border_weight_field?: string;
+  border_weight_map?: Record<string, string>;
+  slots: SlotConfig[];
+}
+
+type GetCategoryColor = (cat: string, key: string) => { bg: string; text: string; border: string; label?: string } | null;
+type GetSemanticColor = (scale: string, level: string) => { bg: string; text: string; border: string } | null;
+type GetLabel = (cat: string, key: string) => string;
+
+// ── Block: badge_row ───────────────────────────────────
+
+function BadgeRowBlock({ badges, item, getCategoryColor, getSemanticColor, getLabel }: {
+  badges: BadgeConfig[];
+  item: Record<string, unknown>;
+  getCategoryColor: GetCategoryColor;
+  getSemanticColor: GetSemanticColor;
+  getLabel: GetLabel;
+}) {
+  return (
+    <div className="ar-card-badge-row">
+      {badges.map((badge, idx) => {
+        const rawValue = String(item[badge.field] || badge.default_value || '');
+        if (!rawValue) return null;
+
+        let displayValue = rawValue;
+        let colors: { bg: string; text: string; border?: string } | null = null;
+
+        if (badge.color_mode === 'category' && badge.color_category) {
+          colors = getCategoryColor(badge.color_category, rawValue);
+          displayValue = getLabel(badge.color_category, rawValue) || rawValue.replace(/_/g, ' ');
+        } else if (badge.color_mode === 'semantic' && badge.color_scale) {
+          const key = rawValue.toLowerCase();
+          const tokenKey = badge.value_map?.[key] || key;
+          colors = getSemanticColor(badge.color_scale, tokenKey);
+          displayValue = key;
+        }
+
+        if (badge.transform === 'lowercase') displayValue = displayValue.toLowerCase();
+        else if (badge.transform === 'uppercase') displayValue = displayValue.toUpperCase();
+        else if (badge.transform === 'titlecase') displayValue = displayValue.replace(/\b\w/g, c => c.toUpperCase());
+
+        const fallback = { bg: '#f8fafc', text: '#334155', border: '#e2e8f0' };
+        const c = colors || fallback;
+
+        const isSemantic = badge.color_mode === 'semantic';
+        const className = isSemantic
+          ? `ar-severity-badge ar-severity-badge--${rawValue.toLowerCase()}`
+          : 'ar-card-type-badge';
+
+        return (
+          <span
+            key={idx}
+            className={className}
+            style={{ background: c.bg, color: c.text, borderColor: c.border }}
+          >
+            {displayValue}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+// ── Block: heading ─────────────────────────────────────
+
+function HeadingBlock({ field, item, hideWhenMatchesLabel, getLabel }: {
+  field: string;
+  item: Record<string, unknown>;
+  hideWhenMatchesLabel?: ColorRef;
+  getLabel: GetLabel;
+}) {
+  const text = String(item[field] || '');
+  if (!text) return null;
+
+  if (hideWhenMatchesLabel) {
+    const keyValue = String(item[hideWhenMatchesLabel.key_field] || '');
+    const label = getLabel(hideWhenMatchesLabel.category, keyValue);
+    if (text === label) return null;
+  }
+
+  return <h4 className="ar-card-heading">{text}</h4>;
+}
+
+// ── Block: prose ───────────────────────────────────────
+
+function ProseBlock({ field, item, subduedWhen }: {
+  field: string;
+  item: Record<string, unknown>;
+  subduedWhen?: { field: string; equals: string };
+}) {
+  const text = String(item[field] || '');
+  if (!text) return null;
+
+  const isSubdued = subduedWhen
+    && String(item[subduedWhen.field] || '').toLowerCase() === subduedWhen.equals;
+
+  return (
+    <p className={`ar-card-prose${isSubdued ? ' ar-card-prose--subdued' : ''}`}>
+      {text}
+    </p>
+  );
+}
+
+// ── Block: chip_list ───────────────────────────────────
+
+function ChipListBlock({ field, item, label, linkTitlePattern }: {
+  field: string;
+  item: Record<string, unknown>;
+  label?: string;
+  linkTitlePattern?: string;
+}) {
+  const values = item[field] as string[] | undefined;
+  if (!values || !Array.isArray(values) || values.length === 0) return null;
+
+  return (
+    <div className="ar-card-chip-list">
+      {label && <span className="ar-card-section-label">{label}</span>}
+      <div className="gen-idea-tags">
+        {values.map(val => (
+          <span
+            key={val}
+            className="gen-idea-tag gen-idea-tag--linked"
+            title={linkTitlePattern ? linkTitlePattern.replace('{value}', val) : undefined}
+          >
+            {val}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+// ── Block: evidence_trail ──────────────────────────────
+
+function EvidenceTrailBlock({ steps, item, label, accentFrom, collapsedByDefault, getCategoryColor }: {
+  steps: EvidenceStepConfig[];
+  item: Record<string, unknown>;
+  label?: string;
+  accentFrom?: ColorRef;
+  collapsedByDefault?: boolean;
+  getCategoryColor: GetCategoryColor;
+}) {
+  const [collapsed, setCollapsed] = useState(collapsedByDefault ?? false);
+
+  const trailSteps: EvidenceTrailStep[] = [];
+
+  for (const sc of steps) {
+    const raw = item[sc.field];
+    if (raw === undefined || raw === null || raw === '') continue;
+
+    const variant = sc.variant as EvidenceTrailStep['variant'];
+
+    if (sc.is_text || typeof raw === 'string') {
+      trailSteps.push({ label: sc.label, variant, text: String(raw) });
+    } else if (Array.isArray(raw)) {
+      const items: EvidenceTrailItem[] = raw.map((entry: unknown) => {
+        if (typeof entry === 'string') return { quote: entry };
+        if (typeof entry === 'object' && entry !== null) {
+          const e = entry as Record<string, unknown>;
+          return {
+            title: sc.item_title_field ? String(e[sc.item_title_field] || '') : undefined,
+            quote: sc.item_quote_field ? String(e[sc.item_quote_field] || '') : undefined,
+            cite: sc.item_cite_field ? String(e[sc.item_cite_field] || '') : undefined,
+          };
+        }
+        return { quote: String(entry) };
+      });
+      if (items.length > 0) {
+        trailSteps.push({ label: sc.label, variant, items });
+      }
+    }
+  }
+
+  if (trailSteps.length === 0) return null;
+
+  let accentColor: string | undefined;
+  let borderColor: string | undefined;
+  if (accentFrom) {
+    const keyValue = String(item[accentFrom.key_field] || '');
+    const colors = getCategoryColor(accentFrom.category, keyValue);
+    if (colors) {
+      accentColor = colors.text;
+      borderColor = colors.border;
+    }
+  }
+
+  // Count total evidence pieces for the summary
+  const pieceCount = trailSteps.reduce((n, s) => n + (s.items?.length || (s.text ? 1 : 0)), 0);
+
+  return (
+    <div className="gen-evidence-trail">
+      <button
+        type="button"
+        className={`gen-evidence-toggle${collapsed ? ' gen-evidence-toggle--collapsed' : ''}`}
+        onClick={(e) => { e.stopPropagation(); setCollapsed(!collapsed); }}
+      >
+        <span className="gen-evidence-toggle-icon">{'\u25B6'}</span>
+        <span className="gen-evidence-toggle-label">
+          {label || 'Evidence Trail'}
+        </span>
+        <span className="gen-evidence-count">{pieceCount}</span>
+      </button>
+      {!collapsed && (
+        <EvidenceTrail steps={trailSteps} accentColor={accentColor} borderColor={borderColor} />
+      )}
+    </div>
+  );
+}
+
+// ── Block: key_value ───────────────────────────────────
+
+function KeyValueBlock({ entries, item }: {
+  entries: Array<{ field: string; label: string }>;
+  item: Record<string, unknown>;
+}) {
+  const pairs = entries
+    .map(e => ({ label: e.label, value: item[e.field] }))
+    .filter(p => p.value != null && p.value !== '');
+
+  if (pairs.length === 0) return null;
+
+  return (
+    <div className="gen-template-kv">
+      {pairs.map((p, idx) => (
+        <div key={idx} className="gen-template-kv-row">
+          <span className="gen-template-kv-label">{p.label}</span>
+          <span className="gen-template-kv-value">{String(p.value)}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ── Block: separator ───────────────────────────────────
+
+function SeparatorBlock() {
+  return <hr className="gen-template-separator" />;
+}
+
+// ── Slot dispatcher ────────────────────────────────────
+
+function TemplateSlot({ slot, item, getCategoryColor, getSemanticColor, getLabel }: {
+  slot: SlotConfig;
+  item: Record<string, unknown>;
+  getCategoryColor: GetCategoryColor;
+  getSemanticColor: GetSemanticColor;
+  getLabel: GetLabel;
+}) {
+  switch (slot.type) {
+    case 'badge_row':
+      return slot.badges ? (
+        <BadgeRowBlock
+          badges={slot.badges}
+          item={item}
+          getCategoryColor={getCategoryColor}
+          getSemanticColor={getSemanticColor}
+          getLabel={getLabel}
+        />
+      ) : null;
+
+    case 'heading':
+      return slot.field ? (
+        <HeadingBlock
+          field={slot.field}
+          item={item}
+          hideWhenMatchesLabel={slot.hide_when_matches_label}
+          getLabel={getLabel}
+        />
+      ) : null;
+
+    case 'prose':
+      return slot.field ? (
+        <ProseBlock field={slot.field} item={item} subduedWhen={slot.subdued_when} />
+      ) : null;
+
+    case 'chip_list':
+      return slot.field ? (
+        <ChipListBlock
+          field={slot.field}
+          item={item}
+          label={slot.label}
+          linkTitlePattern={slot.link_title_pattern}
+        />
+      ) : null;
+
+    case 'evidence_trail':
+      return slot.steps ? (
+        <EvidenceTrailBlock
+          steps={slot.steps}
+          item={item}
+          label={slot.label}
+          accentFrom={slot.accent_from}
+          collapsedByDefault={slot.collapsed_by_default}
+          getCategoryColor={getCategoryColor}
+        />
+      ) : null;
+
+    case 'key_value':
+      return slot.entries ? (
+        <KeyValueBlock entries={slot.entries} item={item} />
+      ) : null;
+
+    case 'separator':
+      return <SeparatorBlock />;
+
+    default:
+      return null;
+  }
+}
+
+// ── Main component ─────────────────────────────────────
+
+export function TemplateCardCell({ item, config }: CellRendererProps) {
+  const { getCategoryColor, getSemanticColor, getLabel } = useDesignTokens();
+
+  const template = config.card_template as CardTemplate | undefined;
+  if (!template || !template.slots) {
+    return <p className="gen-empty">No card template configured.</p>;
+  }
+
+  // Compute wrapper styles from template config
+  const wrapperClass = template.wrapper_class || '';
+  const severityField = template.border_weight_field;
+  const severityValue = severityField ? String(item[severityField] || '').toLowerCase() : '';
+  const severityModifier = severityValue ? ` ${wrapperClass}--${severityValue}` : '';
+
+  let borderStyle: React.CSSProperties | undefined;
+  if (template.border_accent) {
+    const keyValue = String(item[template.border_accent.key_field] || '');
+    const colors = getCategoryColor(template.border_accent.category, keyValue);
+    if (colors) {
+      const width = template.border_weight_map?.[severityValue] || '4px';
+      borderStyle = {
+        borderTopColor: colors.text,
+        borderTopWidth: width,
+        borderTopStyle: 'solid',
+      };
+    }
+  }
+
+  const className = `${wrapperClass}${severityModifier}`.trim() || undefined;
+
+  return (
+    <div className={className} style={borderStyle}>
+      {template.slots.map((slot, idx) => (
+        <TemplateSlot
+          key={idx}
+          slot={slot}
+          item={item}
+          getCategoryColor={getCategoryColor}
+          getSemanticColor={getSemanticColor}
+          getLabel={getLabel}
+        />
+      ))}
+    </div>
+  );
+}

package/src/cells/index.ts

@@ -0,0 +1,98 @@
+/**
+ * Cell Renderer Registry — Domain-specific card content components.
+ */
+
+import React from 'react';
+import { TemplateCardCell } from './TemplateCardCell';
+import type { CellRendererProps, CellRendererComponent } from '../types';
+
+export type { CellRendererProps, CellRendererComponent };
+
+/** Registry of cell renderers keyed by config.cell_renderer string */
+export const cellRenderers: Record<string, CellRendererComponent> = {
+  template_card: TemplateCardCell,
+};
+
+// Field classification for intelligent rendering
+const TITLE_FIELDS = ['name', 'title', 'finding', 'concept', 'idea', 'theme'];
+const BODY_FIELDS = ['condition', 'description', 'analysis', 'significance', 'explanation', 'mechanism', 'details', 'summary', 'how_it_enables', 'how_it_constrains', 'effect'];
+const EVIDENCE_FIELDS = ['evidence', 'reasoning', 'supporting_evidence', 'rationale', 'justification'];
+const META_FIELDS = new Set(['_category', 'docKey', 'condition_id', 'id', 'index', 'order']);
+
+function classifyField(key: string): 'title' | 'body' | 'evidence' | 'tag' | 'skip' {
+  if (META_FIELDS.has(key)) return 'skip';
+  if (TITLE_FIELDS.includes(key)) return 'title';
+  if (BODY_FIELDS.includes(key)) return 'body';
+  if (EVIDENCE_FIELDS.includes(key)) return 'evidence';
+  return 'tag';
+}
+
+function formatLabel(key: string): string {
+  return key.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+/**
+ * Default cell renderer — auto-classifies item fields into visual tiers.
+ */
+export function DefaultCardCell({ item, config }: CellRendererProps) {
+  const titleFieldOverride = config.card_title_field as string | undefined;
+  const bodyFieldOverride = config.card_body_field as string | undefined;
+
+  let titleText = '';
+  let bodyText = '';
+  let evidenceText = '';
+  const tags: Array<[string, string]> = [];
+
+  for (const [key, value] of Object.entries(item)) {
+    if (value == null || value === '') continue;
+    if (typeof value === 'object') continue;
+
+    const strVal = String(value);
+
+    if (titleFieldOverride && key === titleFieldOverride) {
+      titleText = strVal;
+      continue;
+    }
+    if (bodyFieldOverride && key === bodyFieldOverride) {
+      bodyText = strVal;
+      continue;
+    }
+
+    const cls = classifyField(key);
+    if (cls === 'skip') continue;
+    if (cls === 'title' && !titleText) { titleText = strVal; continue; }
+    if (cls === 'body' && !bodyText) { bodyText = strVal; continue; }
+    if (cls === 'evidence' && !evidenceText) { evidenceText = strVal; continue; }
+    if (cls === 'tag') tags.push([key, strVal]);
+  }
+
+  if (!titleText && bodyText && bodyText.length < 120) {
+    titleText = bodyText;
+    bodyText = '';
+  }
+
+  return React.createElement('div', { className: 'card-cell-default' },
+    titleText
+      ? React.createElement('div', { className: 'card-cell-title' },
+          titleText.length > 200 ? titleText.slice(0, 200) + '\u2026' : titleText
+        )
+      : null,
+    bodyText
+      ? React.createElement('p', { className: 'card-cell-body' }, bodyText)
+      : null,
+    evidenceText
+      ? React.createElement('blockquote', { className: 'card-cell-evidence' }, evidenceText)
+      : null,
+    tags.length > 0
+      ? React.createElement('div', { className: 'card-cell-tags' },
+          ...tags.slice(0, 4).map(([k, v]) =>
+            React.createElement('span', { key: k, className: 'card-cell-tag' },
+              React.createElement('span', { className: 'card-cell-tag-label' }, formatLabel(k)),
+              ' ',
+              v.replace(/_/g, ' ')
+            )
+          )
+        )
+      : null
+  );
+}

package/src/components/ConditionCards.tsx

@@ -0,0 +1,109 @@
+/**
+ * ConditionCards — Domain-specific sub-renderers for Conditions of Possibility sections.
+ *
+ * Extracted from AccordionRenderer to follow the data-driven sub-renderer pattern.
+ * These preserve the rich visual treatment for enabling/constraining conditions:
+ *   - Condition type colored chips
+ *   - How-managed semantic badges
+ *   - Prior works tags
+ *   - Evidence blockquotes
+ *
+ * Registered as named sub-renderers in SubRenderers.tsx:
+ *   enabling_conditions  → EnableConditionsSubRenderer
+ *   constraining_conditions → ConstrainConditionsSubRenderer
+ */
+
+import React from 'react';
+import type { SubRendererProps } from '../types';
+import { useDesignTokens } from '../tokens/DesignTokenContext';
+import type { StyleOverrides } from '../types/styles';
+
+// ── Enabling Conditions Sub-Renderer ─────────────────────
+
+export function EnableConditionsSubRenderer({ data, config }: SubRendererProps) {
+  const { getCategoryColor } = useDesignTokens();
+
+  if (!data || !Array.isArray(data) || data.length === 0) return null;
+  const conditions = data as Array<Record<string, unknown>>;
+  const sectionDesc = (config.section_description as string) ||
+    'How the author\'s prior work makes the current argument possible';
+  const so = config._style_overrides as StyleOverrides | undefined;
+
+  return (
+    <>
+      <p className="gen-section-desc" style={so?.prose || undefined}>{sectionDesc}</p>
+      <div className="gen-conditions-grid">
+        {conditions.map(cond => (
+          <div key={String(cond.condition_id)} className="gen-condition-card enabling" style={so?.card || undefined}>
+            <div className="gen-condition-header">
+              <span
+                className="gen-condition-type"
+                style={{
+                  borderColor: getCategoryColor('condition', String(cond.condition_type))?.text || 'var(--dt-text-muted, #64748b)',
+                  color: getCategoryColor('condition', String(cond.condition_type))?.text || 'var(--dt-text-muted, #64748b)',
+                  ...so?.chip,
+                }}
+              >
+                {String(cond.condition_type || '').replace(/_/g, ' ')}
+              </span>
+              {cond.how_managed ? (
+                <span className={`gen-managed-badge managed-${cond.how_managed}`} style={so?.badge || undefined}>
+                  {String(cond.how_managed)}
+                </span>
+              ) : null}
+            </div>
+            <p className="gen-condition-desc">{String(cond.description || '')}</p>
+            {cond.how_it_enables ? (
+              <p className="gen-condition-enables">
+                <strong>How it enables:</strong> {String(cond.how_it_enables)}
+              </p>
+            ) : null}
+            {Array.isArray(cond.prior_works_involved) && cond.prior_works_involved.length > 0 && (
+              <div className="gen-condition-works">
+                {(cond.prior_works_involved as string[]).map((w, i) => (
+                  <span key={i} className="gen-work-tag">{w}</span>
+                ))}
+              </div>
+            )}
+            {cond.evidence ? (
+              <blockquote className="gen-condition-evidence">{String(cond.evidence)}</blockquote>
+            ) : null}
+          </div>
+        ))}
+      </div>
+    </>
+  );
+}
+
+// ── Constraining Conditions Sub-Renderer ─────────────────
+
+export function ConstrainConditionsSubRenderer({ data, config }: SubRendererProps) {
+  if (!data || !Array.isArray(data) || data.length === 0) return null;
+  const constraints = data as Array<Record<string, unknown>>;
+  const sectionDesc = (config.section_description as string) ||
+    'How prior work limits or constrains the current argument';
+  const so = config._style_overrides as StyleOverrides | undefined;
+
+  return (
+    <>
+      <p className="gen-section-desc" style={so?.prose || undefined}>{sectionDesc}</p>
+      <div className="gen-constraints-list">
+        {constraints.map((constraint, i) => (
+          <div key={String(constraint.constraint_id || i)} className="gen-constraint-card" style={so?.card || undefined}>
+            {constraint.type ? (
+              <span className="gen-constraint-type" style={so?.chip || undefined}>
+                {String(constraint.type).replace(/_/g, ' ')}
+              </span>
+            ) : null}
+            <p>{String(constraint.description || '')}</p>
+            {constraint.how_navigated ? (
+              <p className="gen-constraint-nav">
+                <strong>How navigated:</strong> {String(constraint.how_navigated)}
+              </p>
+            ) : null}
+          </div>
+        ))}
+      </div>
+    </>
+  );
+}