@the-syllabus/analysis-renderers 0.2.0

package/src/types/designTokens.ts

@@ -0,0 +1,236 @@
+/**
+ * Design Token System - TypeScript Interfaces
+ *
+ * Mirrors the Pydantic schema from the backend style school generator.
+ * Used for typing API responses from GET /v1/styles/tokens/{schoolKey}.
+ */
+
+export interface SemanticTriple {
+  bg: string;
+  text: string;
+  border: string;
+}
+
+export interface CategoricalItem {
+  bg: string;
+  text: string;
+  border: string;
+  label: string;
+}
+
+export interface PrimitiveTokens {
+  color_primary: string;
+  color_secondary: string;
+  color_tertiary: string;
+  color_accent: string;
+  color_accent_alt: string;
+  color_background: string;
+  color_highlight: string;
+  color_text: string;
+  color_muted: string;
+  color_positive: string;
+  color_negative: string;
+  series_palette: string[];
+  font_primary: string;
+  font_title: string;
+  font_caption: string;
+  font_number: string;
+}
+
+export interface SurfaceTokens {
+  surface_default: string;
+  surface_alt: string;
+  surface_elevated: string;
+  surface_inset: string;
+  border_default: string;
+  border_light: string;
+  border_accent: string;
+  text_default: string;
+  text_muted: string;
+  text_faint: string;
+  text_on_accent: string;
+  text_inverse: string;
+  shadow_sm: string;
+  shadow_md: string;
+  shadow_lg: string;
+}
+
+export interface ScaleTokens {
+  type_display: string;
+  type_heading: string;
+  type_subheading: string;
+  type_body: string;
+  type_caption: string;
+  type_label: string;
+  weight_light: string;
+  weight_regular: string;
+  weight_medium: string;
+  weight_semibold: string;
+  weight_bold: string;
+  weight_title: string;
+  leading_tight: string;
+  leading_normal: string;
+  leading_loose: string;
+  space_2xs: string;
+  space_xs: string;
+  space_sm: string;
+  space_md: string;
+  space_lg: string;
+  space_xl: string;
+  space_2xl: string;
+  space_3xl: string;
+  radius_sm: string;
+  radius_md: string;
+  radius_lg: string;
+  radius_xl: string;
+  radius_pill: string;
+}
+
+export interface SemanticTokens {
+  severity_high: SemanticTriple;
+  severity_medium: SemanticTriple;
+  severity_low: SemanticTriple;
+  visibility_explicit: SemanticTriple;
+  visibility_implicit: SemanticTriple;
+  visibility_hidden: SemanticTriple;
+  modality_ontological: SemanticTriple;
+  modality_methodological: SemanticTriple;
+  modality_normative: SemanticTriple;
+  modality_epistemic: SemanticTriple;
+  modality_causal: SemanticTriple;
+  change_stable: SemanticTriple;
+  change_narrowed: SemanticTriple;
+  change_expanded: SemanticTriple;
+  change_inverted: SemanticTriple;
+  change_metaphorized: SemanticTriple;
+  centrality_core: SemanticTriple;
+  centrality_supporting: SemanticTriple;
+  centrality_peripheral: SemanticTriple;
+  status_completed: SemanticTriple;
+  status_running: SemanticTriple;
+  status_pending: SemanticTriple;
+  status_failed: SemanticTriple;
+}
+
+export interface CategoricalTokens {
+  // Tactics (10)
+  tactic_conceptual_recycling: CategoricalItem;
+  tactic_silent_revision: CategoricalItem;
+  tactic_selective_continuity: CategoricalItem;
+  tactic_retroactive_framing: CategoricalItem;
+  tactic_escalation: CategoricalItem;
+  tactic_narrative_bootstrapping: CategoricalItem;
+  tactic_framework_migration: CategoricalItem;
+  tactic_condition_shift: CategoricalItem;
+  tactic_biographical_teleology: CategoricalItem;
+  tactic_strategic_amnesia: CategoricalItem;
+  // Forms (5)
+  form_proto_form: CategoricalItem;
+  form_full_form: CategoricalItem;
+  form_contradictory_form: CategoricalItem;
+  form_absent_but_implied: CategoricalItem;
+  form_different_framing: CategoricalItem;
+  // Idea types (11)
+  idea_central_thesis: CategoricalItem;
+  idea_supporting_argument: CategoricalItem;
+  idea_supporting_framework: CategoricalItem;
+  idea_methodological_tool: CategoricalItem;
+  idea_conceptual_framework: CategoricalItem;
+  idea_empirical_finding: CategoricalItem;
+  idea_normative_claim: CategoricalItem;
+  idea_analytical_distinction: CategoricalItem;
+  idea_rhetorical_strategy: CategoricalItem;
+  idea_rhetorical_device: CategoricalItem;
+  idea_historical_analysis: CategoricalItem;
+  // Condition types (8)
+  condition_conceptual_foundation: CategoricalItem;
+  condition_audience_preparation: CategoricalItem;
+  condition_authority_establishment: CategoricalItem;
+  condition_framework_provision: CategoricalItem;
+  condition_problem_definition: CategoricalItem;
+  condition_methodological_precedent: CategoricalItem;
+  condition_intellectual_toolkit: CategoricalItem;
+  condition_cross_domain_transfer: CategoricalItem;
+  // Relationship types (8)
+  relationship_direct_precursor: CategoricalItem;
+  relationship_methodological_ancestor: CategoricalItem;
+  relationship_counter_position: CategoricalItem;
+  relationship_indirect_contextualizer: CategoricalItem;
+  relationship_stylistic_influence: CategoricalItem;
+  relationship_conceptual_sibling: CategoricalItem;
+  relationship_different_field_relevant: CategoricalItem;
+  relationship_tangential: CategoricalItem;
+  // Strength (3)
+  strength_strong: CategoricalItem;
+  strength_moderate: CategoricalItem;
+  strength_weak: CategoricalItem;
+  // Awareness (3)
+  awareness_explicit: CategoricalItem;
+  awareness_implicit: CategoricalItem;
+  awareness_unconscious: CategoricalItem;
+  // Pattern types (7)
+  pattern_analytical_method: CategoricalItem;
+  pattern_cognitive_habit: CategoricalItem;
+  pattern_recurring_metaphor: CategoricalItem;
+  pattern_problem_solving_approach: CategoricalItem;
+  pattern_theoretical_framework: CategoricalItem;
+  pattern_argumentative_structure: CategoricalItem;
+  pattern_epistemic_commitment: CategoricalItem;
+}
+
+export interface ComponentTokens {
+  page_accent: string;
+  page_accent_hover: string;
+  page_accent_bg: string;
+  section_header_bg: string;
+  section_header_border: string;
+  section_header_text: string;
+  card_bg: string;
+  card_border: string;
+  card_border_accent: string;
+  card_header_bg: string;
+  card_header_text: string;
+  chip_weight_0_bg: string;
+  chip_weight_0_text: string;
+  chip_weight_0_border: string;
+  chip_weight_25_bg: string;
+  chip_weight_25_text: string;
+  chip_weight_25_border: string;
+  chip_weight_50_bg: string;
+  chip_weight_50_text: string;
+  chip_weight_50_border: string;
+  chip_weight_75_bg: string;
+  chip_weight_75_text: string;
+  chip_weight_75_border: string;
+  chip_weight_100_bg: string;
+  chip_weight_100_text: string;
+  chip_weight_100_border: string;
+  chip_header_bg: string;
+  chip_header_text: string;
+  prose_lede_color: string;
+  prose_lede_weight: string;
+  prose_blockquote_border: string;
+  prose_blockquote_bg: string;
+  timeline_connector: string;
+  timeline_connector_width: string;
+  timeline_node_bg: string;
+  timeline_node_border: string;
+  evidence_dot_bg: string;
+  evidence_connector: string;
+  stat_number_color: string;
+  stat_label_color: string;
+  stat_card_bg: string;
+}
+
+export interface DesignTokenSet {
+  school_key: string;
+  school_name: string;
+  generated_at: string;
+  version: string;
+  primitives: PrimitiveTokens;
+  surfaces: SurfaceTokens;
+  scales: ScaleTokens;
+  semantic: SemanticTokens;
+  categorical: CategoricalTokens;
+  components: ComponentTokens;
+}

package/src/types/index.ts

@@ -0,0 +1,53 @@
+/**
+ * Renderer type definitions — shared across all consumer apps.
+ */
+
+import React from 'react';
+
+/** The props every top-level renderer receives. */
+export interface RendererProps {
+  /** The full analysis result data — renderers pick what they need */
+  data: unknown;
+  /** Renderer-specific configuration from the view definition */
+  config: Record<string, unknown>;
+  /** Children views (for container renderers like tabs) */
+  children?: React.ReactNode;
+}
+
+export type RendererComponent = React.ComponentType<RendererProps>;
+
+/** The props every cell renderer receives (inside card grids). */
+export interface CellRendererProps {
+  /** The individual item to render inside a card */
+  item: Record<string, unknown>;
+  /** The full renderer_config from the view definition */
+  config: Record<string, unknown>;
+}
+
+export type CellRendererComponent = React.ComponentType<CellRendererProps>;
+
+/** The props every sub-renderer receives (inside accordion sections). */
+export interface SubRendererProps {
+  data: unknown;
+  config: Record<string, unknown>;
+}
+
+export type SubRendererComponent = React.FC<SubRendererProps>;
+
+// Re-export from sibling type files
+export type {
+  StyleOverrides,
+} from './styles';
+export { getSO } from './styles';
+
+export type {
+  DesignTokenSet,
+  SemanticTriple,
+  CategoricalItem,
+  PrimitiveTokens,
+  SurfaceTokens,
+  ScaleTokens,
+  SemanticTokens,
+  CategoricalTokens,
+  ComponentTokens,
+} from './designTokens';

package/src/types/styles.ts

@@ -0,0 +1,44 @@
+/**
+ * Shared style override types for the renderer system.
+ *
+ * StyleOverrides is the contract between the polish system (analyzer-v2)
+ * and the frontend renderers. The polisher generates CSS property maps
+ * for each injection point; renderers apply them as inline styles.
+ *
+ * 24 injection points total: 10 existing + 14 fine-grained.
+ */
+
+export interface StyleOverrides {
+  // === Existing injection points ===
+  section_header?: Record<string, string>;
+  section_content?: Record<string, string>;
+  card?: Record<string, string>;
+  chip?: Record<string, string>;
+  badge?: Record<string, string>;
+  timeline_node?: Record<string, string>;
+  prose?: Record<string, string>;
+  accent_color?: string;
+  view_wrapper?: Record<string, string>;
+  items_container?: Record<string, string>;
+
+  // === Fine-grained injection points ===
+  section_title?: Record<string, string>;
+  section_description?: Record<string, string>;
+  card_header?: Record<string, string>;
+  card_body?: Record<string, string>;
+  chip_label?: Record<string, string>;
+  chip_expanded?: Record<string, string>;
+  prose_lede?: Record<string, string>;
+  prose_body?: Record<string, string>;
+  prose_quote?: Record<string, string>;
+  timeline_connector?: Record<string, string>;
+  stat_number?: Record<string, string>;
+  stat_label?: Record<string, string>;
+  hero_card?: Record<string, string>;
+  view_header?: Record<string, string>;
+}
+
+/** Helper to extract StyleOverrides from a renderer config object. */
+export function getSO(config: Record<string, unknown>): StyleOverrides | undefined {
+  return config._style_overrides as StyleOverrides | undefined;
+}

package/src/utils/tokenFlattener.ts

@@ -0,0 +1,64 @@
+/**
+ * Token Flattener - Converts nested DesignTokenSet to flat CSS custom properties.
+ *
+ * Transforms the structured token hierarchy into a flat Record<string, string>
+ * where keys are CSS custom property names (--dt-*) and values are token values.
+ * This is injected into the DOM via element.style.setProperty() by DesignTokenContext.
+ */
+
+import { DesignTokenSet, SemanticTriple, CategoricalItem } from '../types/designTokens';
+
+/**
+ * Flattens a nested DesignTokenSet into a flat Record<string, string>
+ * where keys are CSS custom property names (--dt-*) and values are the token values.
+ */
+export function flattenTokens(tokens: DesignTokenSet): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  // Tier 1: Primitives (skip non-CSS values like series_palette array)
+  const primitives = tokens.primitives;
+  for (const [key, value] of Object.entries(primitives)) {
+    if (key === 'series_palette') {
+      // Store each series color individually
+      (value as string[]).forEach((color, i) => {
+        result[`--dt-series-${i}`] = color;
+      });
+    } else {
+      result[`--dt-${key.replace(/_/g, '-')}`] = value as string;
+    }
+  }
+
+  // Tier 2: Surfaces
+  for (const [key, value] of Object.entries(tokens.surfaces)) {
+    result[`--dt-${key.replace(/_/g, '-')}`] = value as string;
+  }
+
+  // Tier 3: Scales
+  for (const [key, value] of Object.entries(tokens.scales)) {
+    result[`--dt-${key.replace(/_/g, '-')}`] = value as string;
+  }
+
+  // Tier 4: Semantic (each is a SemanticTriple with bg, text, border)
+  for (const [key, triple] of Object.entries(tokens.semantic)) {
+    const t = triple as SemanticTriple;
+    result[`--dt-${key.replace(/_/g, '-')}-bg`] = t.bg;
+    result[`--dt-${key.replace(/_/g, '-')}-text`] = t.text;
+    result[`--dt-${key.replace(/_/g, '-')}-border`] = t.border;
+  }
+
+  // Tier 5: Categorical (each is a CategoricalItem with bg, text, border, label)
+  for (const [key, item] of Object.entries(tokens.categorical)) {
+    const c = item as CategoricalItem;
+    result[`--dt-${key.replace(/_/g, '-')}-bg`] = c.bg;
+    result[`--dt-${key.replace(/_/g, '-')}-text`] = c.text;
+    result[`--dt-${key.replace(/_/g, '-')}-border`] = c.border;
+    // Labels are not CSS properties - they're accessed via JS context
+  }
+
+  // Tier 6: Components
+  for (const [key, value] of Object.entries(tokens.components)) {
+    result[`--dt-${key.replace(/_/g, '-')}`] = value as string;
+  }
+
+  return result;
+}