@codefluss/base-types 0.0.2-alpha.1 → 0.0.2-alpha.2

package/src/dependencies.ts

@@ -1,8 +1,18 @@
 /**
  * Dependency Injection Types
  *
- * These types define the external dependencies that the plugin requires
- * from the host application. All dependencies must be injected via props.
+ * Defines the external dependencies that plugins require from the host
+ * application. All dependencies are injected via props — plugins never
+ * import host-application code directly.
+ *
+ * The **plugin-driven architecture** ensures plugins are self-contained:
+ * the host provides Design System tokens, utility functions, a renderer
+ * component, and optional callbacks through these interfaces.
+ *
+ * @see {@link PluginDependencies} — Top-level dependency container
+ * @see {@link PluginDesignSystem} — Design token access API
+ * @see {@link PluginUtils} — Shared utility functions
+ * @see {@link PluginCallbacks} — Host communication callbacks
  *
  * @package @codefluss/base-types
  * @version 1.0.0
@@ -11,533 +21,1093 @@
 import type { ComponentType } from 'react';
 
 /**
- * Responsive font size values for different breakpoints
+ * Responsive font size values for different viewport breakpoints.
+ *
+ * Each value is a CSS font-size string (e.g., `'1rem'`, `'16px'`).
+ *
+ * @see {@link DesignSystemFont.responsive}
+ *
+ * @example
+ * ```typescript
+ * const sizes: ResponsiveFontSizes = {
+ *   mobile: '1rem',
+ *   tablet: '1.25rem',
+ *   desktop: '1.5rem',
+ * };
+ * ```
  */
 export interface ResponsiveFontSizes {
+  /** Font size on mobile viewports */
   mobile: string;
+
+  /** Font size on tablet viewports */
   tablet: string;
+
+  /** Font size on desktop viewports */
   desktop: string;
 }
 
 /**
- * Responsive line height values for different breakpoints
+ * Responsive line height values for different viewport breakpoints.
+ *
+ * Values are unitless multipliers (e.g., `1.4` means 140% of font size).
+ *
+ * @see {@link DesignSystemFont.responsiveLineHeight}
  */
 export interface ResponsiveLineHeights {
+  /** Line height on mobile viewports */
   mobile: number;
+
+  /** Line height on tablet viewports */
   tablet: number;
+
+  /** Line height on desktop viewports */
   desktop: number;
 }
 
 /**
- * Design System Font Configuration
+ * Design System font configuration for a single typography preset.
+ *
+ * Each preset defines a complete typographic style — family, size, weight,
+ * line-height, and optional responsive overrides.
+ *
+ * @see {@link PluginDesignSystem.fonts}
+ *
+ * @example
+ * ```typescript
+ * const heading1: DesignSystemFont = {
+ *   family: '"Inter", sans-serif',
+ *   size: '2.5rem',
+ *   weight: '700',
+ *   lineHeight: '1.2',
+ *   element: 'h1',
+ *   responsive: { mobile: '1.75rem', tablet: '2rem', desktop: '2.5rem' },
+ * };
+ * ```
  */
 export interface DesignSystemFont {
+  /** CSS `font-family` value (e.g., `'"Inter", sans-serif'`) */
   family: string;
+
+  /** CSS `font-size` value — desktop default (e.g., `'2.5rem'`) */
   size: string;
+
+  /** CSS `font-weight` value (e.g., `'700'`, `'bold'`) */
   weight: string;
+
+  /** CSS `line-height` value (e.g., `'1.2'`, `'28px'`) */
   lineHeight: string;
+
+  /**
+   * Recommended HTML element for this preset (e.g., `'h1'`, `'h2'`, `'p'`).
+   * Used by heading/paragraph plugins to pick the semantic element.
+   */
   element?: string; // HTML element (h1, h2, p, etc.)
+
+  /**
+   * Per-viewport font size overrides.
+   * When provided, the plugin should apply these sizes at each breakpoint.
+   * @see {@link ResponsiveFontSizes}
+   */
   responsive?: ResponsiveFontSizes; // Optional responsive font sizes
+
+  /**
+   * Per-viewport line-height overrides.
+   * @see {@link ResponsiveLineHeights}
+   */
   responsiveLineHeight?: ResponsiveLineHeights; // Optional responsive line heights
 }
 
 /**
- * Design System Color Configuration
+ * Design System color configuration for a single color preset.
+ *
+ * @see {@link PluginDesignSystem.colors}
+ *
+ * @example
+ * ```typescript
+ * const primary: DesignSystemColor = { value: '#3b82f6', label: 'Primary' };
+ * ```
  */
 export interface DesignSystemColor {
+  /** CSS color value (hex, rgb, hsl, or CSS variable) */
   value: string;
+
+  /** Human-readable label displayed in color pickers */
   label: string;
 }
 
 /**
- * Box Model Value - Single side values
+ * Four-sided box model value for spacing (padding / margin / gap).
+ *
+ * @see BoxModelValue in `common-types.ts` for the canonical definition.
+ * This is a parallel declaration required by the dependencies module.
  */
 export interface BoxModelValue {
+  /** Top spacing in pixels */
   top: number;
+
+  /** Right spacing in pixels */
   right: number;
+
+  /** Bottom spacing in pixels */
   bottom: number;
+
+  /** Left spacing in pixels */
   left: number;
 }
 
 /**
- * Grid Preset Values (Container-specific)
- * Clean camelCase naming
+ * Grid preset values for container grid layout configuration.
+ *
+ * Defines the complete grid parameters: columns, rows, gaps, and alignment.
+ * Uses clean camelCase naming.
+ *
+ * @see {@link DesignSystemGrid}
+ *
+ * @example
+ * ```typescript
+ * const defaultGrid: GridPresetValues = {
+ *   columns: 3,
+ *   rows: 1,
+ *   columnGap: 16,
+ *   rowGap: 16,
+ *   maxWidth: 1200,
+ *   margin: 'auto',
+ *   alignmentHorizontal: 'stretch',
+ *   alignmentVertical: 'start',
+ *   alignmentContent: 'start',
+ * };
+ * ```
  */
 export interface GridPresetValues {
+  /** Number of grid columns */
   columns: number;
+
+  /** Number of grid rows */
   rows: number;
+
+  /** Horizontal gap between columns in pixels */
   columnGap: number;
+
+  /** Vertical gap between rows in pixels */
   rowGap: number;
+
+  /** Maximum grid width in pixels */
   maxWidth: number;
+
+  /** Horizontal margin — number (px) or CSS string (e.g., `'auto'`) */
   margin: number | string;
+
+  /** CSS `justify-items` value (e.g., `'stretch'`, `'center'`) */
   alignmentHorizontal: string;
+
+  /** CSS `align-items` value (e.g., `'start'`, `'center'`, `'stretch'`) */
   alignmentVertical: string;
+
+  /** CSS `align-content` value (e.g., `'start'`, `'stretch'`) */
   alignmentContent: string;
 }
 
 /**
- * Responsive spacing values for different breakpoints
- * Only 3 viewports: mobile, tablet, desktop
+ * Responsive box model values — spacing for each viewport breakpoint.
+ *
+ * @see {@link BoxModelValue}
+ *
+ * @example
+ * ```typescript
+ * const padding: ResponsiveBoxValues = {
+ *   mobile:  { top: 8, right: 8, bottom: 8, left: 8 },
+ *   tablet:  { top: 16, right: 16, bottom: 16, left: 16 },
+ *   desktop: { top: 24, right: 24, bottom: 24, left: 24 },
+ * };
+ * ```
  */
 export interface ResponsiveBoxValues {
+  /** Spacing values on mobile viewports */
   mobile: BoxModelValue;
+
+  /** Spacing values on tablet viewports */
   tablet: BoxModelValue;
+
+  /** Spacing values on desktop viewports */
   desktop: BoxModelValue;
 }
 
 /**
- * Spacing Preset - Combined margin + padding with responsive values
+ * Spacing preset — combined margin and padding with responsive values.
+ *
+ * Presets are managed in the Design System and referenced by ID.
+ * Plugins use `spacingPresetId` to apply a preset, with optional per-element overrides.
+ *
+ * @see {@link DesignSystemSpacing.getPreset}
+ *
+ * @example
+ * ```typescript
+ * const preset: SpacingPreset = {
+ *   presetId: 'spacing-text-default',
+ *   name: 'Text Default',
+ *   margin:  { mobile: { top: 0, ... }, tablet: { ... }, desktop: { ... } },
+ *   padding: { mobile: { top: 8, ... }, tablet: { ... }, desktop: { ... } },
+ * };
+ * ```
  */
 export interface SpacingPreset {
+  /** Unique preset identifier (e.g., `'spacing-text-default'`, `'default'`) */
   presetId: string;
+
+  /** Human-readable preset name shown in the editor */
   name: string;
+
+  /** Responsive margin values (per-viewport) */
   margin: ResponsiveBoxValues;
+
+  /** Responsive padding values (per-viewport) */
   padding: ResponsiveBoxValues;
 }
 
 /**
- * Responsive spacing scale entry
+ * Responsive spacing scale entry — a single token in the spacing scale.
+ *
+ * Defines a spacing value that varies by viewport.
+ *
+ * @see {@link DesignSystemSpacing.scaleResponsive}
  */
 export interface ResponsiveSpacingScale {
+  /** Spacing value on mobile viewports */
   mobile: number;
+
+  /** Spacing value on tablet viewports */
   tablet: number;
+
+  /** Spacing value on desktop viewports */
   desktop: number;
+
+  /** CSS unit for this scale entry (e.g., `'px'`, `'rem'`) */
   unit: string;
 }
 
 /**
- * Design System Spacing Configuration
- * Clean, type-safe API
+ * Design System spacing configuration — provides spacing presets and scales.
+ *
+ * @see {@link PluginDesignSystem.spacing}
  */
 export interface DesignSystemSpacing {
-  /** Spacing scale values */
+  /** Base spacing scale values (e.g., `[0, 4, 8, 12, 16, 24, 32, 48, 64]`) */
   scale: number[];
-  
-  /** Responsive spacing scales by token */
+
+  /** Responsive spacing scales keyed by design token name */
   scaleResponsive: Map<string, ResponsiveSpacingScale>;
-  
+
   /**
-   * Get a spacing preset by ID
-   * @param presetId - The preset identifier
-   * @returns The spacing preset (guaranteed to exist, falls back to 'default')
+   * Retrieve a spacing preset by ID.
+   *
+   * Guaranteed to return a valid preset — falls back to `'default'`
+   * if the requested ID is not found.
+   *
+   * @param presetId - The preset identifier (e.g., `'spacing-text-default'`)
+   * @returns The spacing preset with margin and padding values
    */
   getPreset(presetId: string): SpacingPreset;
 }
 
 /**
- * Design System Grid Configuration
- * Clean, type-safe API
+ * Design System grid configuration — provides grid layout presets.
+ *
+ * @see {@link PluginDesignSystem.grid}
  */
 export interface DesignSystemGrid {
   /**
-   * Get a grid preset by ID
-   * @param presetId - The preset identifier
-   * @returns The grid preset values (guaranteed to exist, falls back to 'default')
+   * Retrieve a grid preset by ID.
+   *
+   * Guaranteed to return valid values — falls back to `'default'`
+   * if the requested ID is not found.
+   *
+   * @param presetId - The preset identifier (e.g., `'default'`, `'narrow'`)
+   * @returns Grid preset values (columns, rows, gaps, alignment)
    */
   getPreset(presetId: string): GridPresetValues;
 }
 
 /**
- * Breakpoint configuration for responsive design
+ * Breakpoint configuration for a single viewport.
+ *
+ * @see {@link DesignSystemBreakpoints}
  */
 export interface BreakpointConfig {
+  /** Minimum viewport width in pixels for this breakpoint */
   minWidth: number;
+
+  /** Breakpoint display name (e.g., `'Mobile'`, `'Tablet'`, `'Desktop'`) */
   name: string;
 }
 
 /**
- * Design System Breakpoints
+ * Design System breakpoint definitions for responsive design.
+ *
+ * @see {@link PluginDesignSystem.breakpoints}
+ *
+ * @example
+ * ```typescript
+ * const breakpoints: DesignSystemBreakpoints = {
+ *   mobile:  { minWidth: 0, name: 'Mobile' },
+ *   tablet:  { minWidth: 768, name: 'Tablet' },
+ *   desktop: { minWidth: 1024, name: 'Desktop' },
+ * };
+ * ```
  */
 export interface DesignSystemBreakpoints {
+  /** Mobile breakpoint configuration */
   mobile: BreakpointConfig;
+
+  /** Tablet breakpoint configuration */
   tablet: BreakpointConfig;
+
+  /** Desktop breakpoint configuration */
   desktop: BreakpointConfig;
 }
 
 /**
- * Design System Layout Configuration
+ * Design System layout configuration — global layout defaults.
+ *
+ * @see {@link PluginDesignSystem.layout}
  */
 export interface DesignSystemLayout {
+  /** Maximum content width (CSS value, e.g., `'1200px'`) */
   maxWidth?: string;
+
+  /** Default gap between elements (CSS value) */
   gap?: string;
+
+  /** Default padding (CSS value) */
   padding?: string;
+
+  /** Default margin (CSS value) */
   margin?: string;
 }
 
 /**
- * Button Style Preset Configuration (Unified)
- * 
- * Complete button style preset that replaces the separate
- * ButtonSizePreset and ButtonVariantPreset interfaces.
- * Matches design_system_button_styles table structure.
+ * Unified button style preset from the Design System.
+ *
+ * Contains all styling for a button variant: colors (per state),
+ * typography, spacing, border, effects, and animations.
+ * Matches the `design_system_button_styles` database table structure.
+ *
+ * @see {@link PluginDesignSystem.buttons}
+ *
+ * @example
+ * ```typescript
+ * const primary: ButtonStylePreset = {
+ *   id: 'btn-1',
+ *   presetId: 'primary',
+ *   name: 'Primary',
+ *   size: 'md',
+ *   backgroundColorPresetId: 'primary',
+ *   textColorPresetId: 'primary-foreground',
+ *   defaultTransitionDuration: 150,
+ *   hoverTransitionDuration: 150,
+ *   activeTransitionDuration: 100,
+ *   disabledOpacity: 0.5,
+ *   isDefault: true,
+ * };
+ * ```
  */
 export interface ButtonStylePreset {
-  // Identifiers
+  // ── Identifiers ──
+
+  /** Database row ID */
   id: string;
+
+  /** Unique preset identifier (e.g., `'primary'`, `'secondary'`, `'ghost'`) */
   presetId: string;
+
+  /** Human-readable name shown in the editor */
   name: string;
+
+  /** Size variant (e.g., `'sm'`, `'md'`, `'lg'`) */
   size: string;
-  
-  // Typography
+
+  // ── Typography ──
+
+  /** Design System font preset ID for button text */
   fontSizePresetId?: string;
+
+  /** CSS `font-weight` value */
   fontWeight?: string;
-  
-  // Spacing (reference to spacing preset)
+
+  // ── Spacing ──
+
+  /** Spacing preset ID for internal padding */
   spacingPresetId?: string;
-  
-  // Border
+
+  // ── Border ──
+
+  /** Border radius preset ID */
   borderRadiusPresetId?: string;
-  
-  // Effect Presets
+
+  // ── Effect Presets ──
+
+  /** Box shadow preset ID */
   shadowPresetId?: string;
+
+  /** Focus ring preset ID (accessibility) */
   focusRingPresetId?: string;
-  
-  // Animation Presets
+
+  // ── Animation Presets ──
+
+  /** Entry/exit animation preset ID */
   animationPresetId?: string;
+
+  /** Hover animation effect preset ID */
   hoverEffectPresetId?: string;
-  
-  // Colors - Default State
+
+  // ── Colors: Default State ──
+
+  /** Background color preset ID (default state) */
   backgroundColorPresetId?: string;
+
+  /** Text color preset ID (default state) */
   textColorPresetId?: string;
+
+  /** Border color preset ID (default state) */
   borderColorPresetId?: string;
-  
-  // Colors - Hover State
+
+  // ── Colors: Hover State ──
+
+  /** Background color preset ID on hover */
   hoverBackgroundColorPresetId?: string;
+
+  /** Text color preset ID on hover */
   hoverTextColorPresetId?: string;
+
+  /** Border color preset ID on hover */
   hoverBorderColorPresetId?: string;
-  
-  // Colors - Active/Pressed State
+
+  // ── Colors: Active/Pressed State ──
+
+  /** Background color preset ID when pressed */
   activeBackgroundColorPresetId?: string;
+
+  /** Text color preset ID when pressed */
   activeTextColorPresetId?: string;
+
+  /** Border color preset ID when pressed */
   activeBorderColorPresetId?: string;
-  
-  // Transition Durations (in milliseconds)
+
+  // ── Transition Durations ──
+
+  /** Default state transition duration in milliseconds */
   defaultTransitionDuration: number;
+
+  /** Hover state transition duration in milliseconds */
   hoverTransitionDuration: number;
+
+  /** Active/pressed state transition duration in milliseconds */
   activeTransitionDuration: number;
-  
-  // Disabled State
+
+  // ── Disabled State ──
+
+  /** Opacity applied when the button is disabled (0–1) */
   disabledOpacity: number;
-  
-  // Text Decoration per state
+
+  // ── Text Decoration per State ──
+
+  /** CSS `text-decoration` in default state */
   defaultTextDecoration?: string;
+
+  /** CSS `text-decoration` on hover */
   hoverTextDecoration?: string;
+
+  /** CSS `text-decoration` when active/pressed */
   activeTextDecoration?: string;
-  
-  // Text Transform per state
+
+  // ── Text Transform per State ──
+
+  /** CSS `text-transform` in default state */
   defaultTextTransform?: string;
+
+  /** CSS `text-transform` on hover */
   hoverTextTransform?: string;
+
+  /** CSS `text-transform` when active/pressed */
   activeTextTransform?: string;
-  
-  // Metadata
+
+  // ── Metadata ──
+
+  /** Description of when/where to use this preset */
   usageDescription?: string;
+
+  /** Whether this is the default preset for new button instances */
   isDefault: boolean;
 }
 
 /**
- * @deprecated Use ButtonStylePreset instead
- * Legacy Button Size Preset Configuration
+ * Legacy button size preset configuration.
+ *
+ * @deprecated Use {@link ButtonStylePreset} instead — this interface
+ * will be removed in a future version.
  */
 export interface ButtonSizePreset {
+  /** Button preset ID */
   button_id: string;
+
+  /** Preset display name */
   name: string;
+
+  /** CSS padding value */
   padding: string;
+
+  /** CSS font-size value */
   fontSize: string;
+
+  /** Icon size value */
   iconSize: string;
+
+  /** CSS min-height value */
   minHeight: string;
+
+  /** CSS border-radius value */
   borderRadius?: string;
+
+  /** CSS font-weight value */
   fontWeight?: string;
+
+  /** Description of intended usage */
   usage_description?: string;
 }
 
 /**
- * @deprecated Use ButtonStylePreset instead
- * Legacy Button Variant Preset Configuration
+ * Legacy button variant preset configuration.
+ *
+ * @deprecated Use {@link ButtonStylePreset} instead — this interface
+ * will be removed in a future version.
  */
 export interface ButtonVariantPreset {
+  /** Background color */
   background: string;
+
+  /** Background color on hover */
   hoverBackground: string;
+
+  /** Text color */
   textColor: string;
+
+  /** Border color */
   borderColor: string;
 }
 
 /**
- * Shadow Configuration
+ * Shadow configuration with optional dark-mode variant.
+ *
+ * @see {@link PluginDesignSystem.shadows}
+ *
+ * @example
+ * ```typescript
+ * const shadow: ShadowConfig = {
+ *   value: '0 4px 6px rgba(0, 0, 0, 0.1)',
+ *   dark: '0 4px 6px rgba(0, 0, 0, 0.3)',
+ * };
+ * ```
  */
 export interface ShadowConfig {
+  /** CSS `box-shadow` value for light mode */
   value: string;
+
+  /** CSS `box-shadow` value for dark mode (falls back to `value` if not set) */
   dark?: string;
 }
 
 /**
- * Accordion Style Preset Configuration
- * 
- * Complete accordion style preset for collapsible components.
- * Matches design_system_accordion_presets table structure.
+ * Accordion style preset from the Design System.
+ *
+ * Contains all styling for collapsible accordion components: header/body
+ * colors, typography, spacing, animations, and state variants.
+ * Matches the `design_system_accordion_presets` database table structure.
+ *
+ * @see {@link PluginDesignSystem.accordions}
  */
 export interface AccordionStylePreset {
-  // Identifiers
+  // ── Identifiers ──
+
+  /** Database row ID */
   id: string;
+
+  /** Unique preset identifier (e.g., `'default'`, `'sm'`, `'lg'`) */
   presetId: string;
+
+  /** Human-readable preset name */
   name: string;
-  
-  // Header Settings
+
+  // ── Header Settings ──
+
+  /** CSS height for the accordion header (e.g., `'48px'`) */
   headerHeight?: string;
+
+  /** Font preset ID for header text */
   headerFontSizePresetId?: string;
+
+  /** CSS `font-weight` for header text */
   headerFontWeight?: string;
+
+  /** Spacing preset ID for header padding */
   headerPaddingPresetId?: string;
+
+  /** Background color preset ID for header (default state) */
   headerBackgroundColorPresetId?: string;
+
+  /** Background color preset ID for header on hover */
   headerHoverBackgroundColorPresetId?: string;
+
+  /** Text color preset ID for header */
   headerTextColorPresetId?: string;
+
+  /** Border color preset ID for header */
   headerBorderColorPresetId?: string;
-  
-  // Body Settings
+
+  // ── Body Settings ──
+
+  /** Minimum height for the accordion body (e.g., `'100px'`) */
   bodyMinHeight?: string;
+
+  /** Spacing preset ID for body padding */
   bodyPaddingPresetId?: string;
+
+  /** Background color preset ID for body */
   bodyBackgroundColorPresetId?: string;
+
+  /** Border color preset ID for body */
   bodyBorderColorPresetId?: string;
-  
-  // General
+
+  // ── General ──
+
+  /** Border radius preset ID */
   borderRadiusPresetId?: string;
+
+  /** Box shadow preset ID */
   shadowPresetId?: string;
+
+  /** Outer spacing preset ID */
   spacingPresetId?: string;
-  
-  // Animation
+
+  // ── Animation ──
+
+  /** Expand/collapse transition duration in milliseconds */
   transitionDuration: number;
+
+  /** CSS easing function (e.g., `'ease-in-out'`) */
   transitionEasing?: string;
-  
-  // State Colors
+
+  // ── State Colors ──
+
+  /** Background color preset ID when expanded */
   expandedBackgroundColorPresetId?: string;
+
+  /** Text color preset ID when expanded */
   expandedTextColorPresetId?: string;
-  
-  // Metadata
+
+  // ── Metadata ──
+
+  /** Description of when/where to use this preset */
   usageDescription?: string;
+
+  /** Whether this is the default preset for new accordion instances */
   isDefault: boolean;
 }
 
 /**
- * Form Style Preset Configuration (Unified)
- * 
- * Complete form style preset that contains all styling for form elements.
- * Matches design_system_form_styles table structure.
+ * Unified form style preset from the Design System.
+ *
+ * Contains all styling for form elements: input fields, labels, descriptions,
+ * error states, and submit buttons. Matches the `design_system_form_styles`
+ * database table structure.
+ *
+ * @see {@link PluginDesignSystem.forms}
  */
 export interface FormStylePreset {
-  // Identifiers
+  // ── Identifiers ──
+
+  /** Database row ID */
   id: string;
+
+  /** Unique preset identifier (e.g., `'default'`, `'outlined'`) */
   presetId: string;
+
+  /** Human-readable preset name */
   name: string;
+
+  /** Visual variant (e.g., `'filled'`, `'outlined'`, `'underlined'`) */
   variant: string;
+
+  /** Size variant (e.g., `'sm'`, `'md'`, `'lg'`) */
   size: string;
-  
-  // Typography
+
+  // ── Typography ──
+
+  /** Font preset ID for input text */
   fontSizePresetId?: string;
-  
-  // Spacing
+
+  // ── Spacing ──
+
+  /** Horizontal padding in pixels */
   paddingX: number;
+
+  /** Vertical padding in pixels */
   paddingY: number;
+
+  /** Border width in pixels */
   borderWidth: number;
+
+  /** Border radius preset ID */
   borderRadiusPresetId?: string;
-  
-  // Effect Presets
+
+  // ── Effect Presets ──
+
+  /** Box shadow preset ID */
   shadowPresetId?: string;
+
+  /** Focus ring preset ID */
   focusRingPresetId?: string;
-  
-  // Animation Presets
+
+  // ── Animation Presets ──
+
+  /** Entry/exit animation preset ID */
   animationPresetId?: string;
+
+  /** Hover animation effect preset ID */
   hoverEffectPresetId?: string;
-  
-  // Colors - Default State
+
+  // ── Colors: Default State ──
+
+  /** Input background color preset ID */
   backgroundColorPresetId?: string;
+
+  /** Input text color preset ID */
   textColorPresetId?: string;
+
+  /** Input border color preset ID */
   borderColorPresetId?: string;
+
+  /** Placeholder text color preset ID */
   placeholderColorPresetId?: string;
+
+  /** Focus ring color preset ID */
   focusRingColorPresetId?: string;
-  
-  // Colors - Hover State
+
+  // ── Colors: Hover State ──
+
+  /** Background color preset ID on hover */
   hoverBackgroundColorPresetId?: string;
+
+  /** Border color preset ID on hover */
   hoverBorderColorPresetId?: string;
-  
-  // Disabled State
+
+  // ── Disabled State ──
+
+  /** Opacity applied when the input is disabled (0–1) */
   disabledOpacity: number;
-  
-  // Error State
+
+  // ── Error State ──
+
+  /** Border color preset ID in error state */
   errorBorderColorPresetId?: string;
+
+  /** Error message text color preset ID */
   errorTextColorPresetId?: string;
-  
-  // Submit Button Reference
+
+  // ── Submit Button ──
+
+  /** Button style preset ID for the form's submit button */
   submitButtonPresetId?: string;
-  
-  // Container Styling
+
+  // ── Container Styling ──
+
+  /** Background color preset ID for the form container */
   containerBackgroundColorPresetId?: string;
+
+  /** Spacing preset ID for the form container */
   containerSpacingPresetId?: string;
-  
-  // Label Styling
+
+  // ── Label Styling ──
+
+  /** Font preset ID for field labels */
   labelFontPresetId?: string;
+
+  /** Color preset ID for field labels */
   labelColorPresetId?: string;
-  
-  // Description/Help Text Styling
+
+  // ── Description/Help Text ──
+
+  /** Font preset ID for help/description text */
   descriptionFontPresetId?: string;
+
+  /** Color preset ID for help/description text */
   descriptionColorPresetId?: string;
-  
-  // Field Spacing
+
+  // ── Field Spacing ──
+
+  /** Vertical gap between form fields in pixels */
   fieldGap?: number;
-  
-  // Metadata
+
+  // ── Metadata ──
+
+  /** Description of when/where to use this preset */
   usageDescription?: string;
+
+  /** Whether this is the default preset for new form instances */
   isDefault: boolean;
 }
 
 /**
- * Design System API
+ * Design System API — the unified interface for accessing design tokens.
  *
- * Interface for accessing global design system values.
- * The host application must provide an implementation.
+ * Plugins receive this via {@link PluginDependencies.designSystem}.
+ * The host application provides an implementation backed by the database
+ * or configuration files.
+ *
+ * @see {@link PluginDependencies}
+ *
+ * @example
+ * ```typescript
+ * // Inside a plugin component
+ * const { designSystem } = dependencies;
+ * const font = designSystem.fonts.getPreset('heading-1');
+ * const color = designSystem.colors.getPreset('primary');
+ * const spacing = designSystem.spacing.getPreset('default');
+ * ```
  */
 export interface PluginDesignSystem {
+  /**
+   * Typography preset system.
+   * @see {@link DesignSystemFont}
+   */
   fonts: {
+    /**
+     * Get a font preset by ID.
+     * @param presetId - Font preset identifier (e.g., `'heading-1'`, `'body'`)
+     * @returns Font configuration or `undefined` if not found
+     */
     getPreset: (presetId: string) => DesignSystemFont | undefined;
   };
+
+  /**
+   * Color preset system.
+   * @see {@link DesignSystemColor}
+   */
   colors: {
+    /**
+     * Get a color preset by ID.
+     * @param presetId - Color preset identifier (e.g., `'primary'`, `'foreground'`)
+     * @returns Color configuration or `undefined` if not found
+     */
     getPreset: (presetId: string) => DesignSystemColor | undefined;
   };
+
+  /**
+   * Spacing system with presets and scales.
+   * @see {@link DesignSystemSpacing}
+   */
   spacing: DesignSystemSpacing;
+
+  /**
+   * Grid layout system (optional, container-specific).
+   * @see {@link DesignSystemGrid}
+   */
   grid?: DesignSystemGrid; // Container-specific, optional
+
+  /**
+   * Layout preset system for global layout defaults.
+   * @see {@link DesignSystemLayout}
+   */
   layout: {
+    /**
+     * Get a layout preset by ID.
+     * @param presetId - Layout preset identifier
+     * @returns Layout configuration or `undefined` if not found
+     */
     getPreset: (presetId: string) => DesignSystemLayout | undefined;
   };
+
+  /**
+   * Viewport breakpoint configuration.
+   * @see {@link DesignSystemBreakpoints}
+   */
   breakpoints: {
+    /**
+     * Get all breakpoint configurations.
+     * @returns Mobile, tablet, and desktop breakpoint definitions
+     */
     getConfig: () => DesignSystemBreakpoints;
   };
+
   /**
-   * Button System (optional)
-   * Provides unified button style presets from design system database
-   * Each preset contains colors, typography, spacing, and effects
+   * Button style preset system (optional).
+   *
+   * Provides unified button styling from the design system database.
+   * Each preset contains colors, typography, spacing, and effects.
+   *
+   * @see {@link ButtonStylePreset}
    */
   buttons?: {
     /**
-     * Get button style preset by ID
-     * @param presetId - Button preset identifier (e.g., 'primary', 'secondary', 'custom-1')
-     * @returns Button style preset or undefined if not found
+     * Get a button style preset by ID.
+     * @param presetId - Button preset identifier (e.g., `'primary'`, `'secondary'`)
+     * @returns Button style preset or `undefined` if not found
      */
     getPreset: (presetId: string) => ButtonStylePreset | undefined;
+
     /**
-     * List all available button style presets
-     * @returns Array of button style presets sorted by sort_order
+     * List all available button style presets.
+     * @returns Array of button style presets sorted by sort order
      */
     listPresets?: () => ButtonStylePreset[];
   };
+
   /**
-   * Form System (optional)
-   * Provides unified form style presets from design system database
-   * Each preset contains colors, typography, spacing, and effects for form elements
+   * Form style preset system (optional).
+   *
+   * Provides unified form element styling from the design system database.
+   *
+   * @see {@link FormStylePreset}
    */
   forms?: {
     /**
-     * Get form style preset by ID
-     * @param presetId - Form preset identifier (e.g., 'default', 'outlined', 'custom-1')
-     * @returns Form style preset or undefined if not found
+     * Get a form style preset by ID.
+     * @param presetId - Form preset identifier (e.g., `'default'`, `'outlined'`)
+     * @returns Form style preset or `undefined` if not found
      */
     getPreset: (presetId: string) => FormStylePreset | undefined;
+
     /**
-     * List all available form style presets
-     * @returns Array of form style presets sorted by sort_order
+     * List all available form style presets.
+     * @returns Array of form style presets sorted by sort order
      */
     listPresets?: () => FormStylePreset[];
   };
+
   /**
-   * Accordion System (optional)
-   * Provides unified accordion style presets from design system database
-   * Each preset contains colors, typography, spacing, and effects for accordion components
+   * Accordion style preset system (optional).
+   *
+   * Provides unified accordion styling from the design system database.
+   *
+   * @see {@link AccordionStylePreset}
    */
   accordions?: {
     /**
-     * Get accordion style preset by ID
-     * @param presetId - Accordion preset identifier (e.g., 'default', 'sm', 'lg', 'custom-1')
-     * @returns Accordion style preset or undefined if not found
+     * Get an accordion style preset by ID.
+     * @param presetId - Accordion preset identifier (e.g., `'default'`, `'sm'`, `'lg'`)
+     * @returns Accordion style preset or `undefined` if not found
      */
     getPreset: (presetId: string) => AccordionStylePreset | undefined;
+
     /**
-     * List all available accordion style presets
-     * @returns Array of accordion style presets sorted by sort_order
+     * List all available accordion style presets.
+     * @returns Array of accordion style presets sorted by sort order
      */
     listPresets?: () => AccordionStylePreset[];
   };
+
   /**
-   * Shadow System (optional)
-   * Provides shadow presets with light and dark mode variants
+   * Shadow preset system (optional).
+   *
+   * Provides box-shadow values with optional dark-mode variants.
+   *
+   * @see {@link ShadowConfig}
    */
   shadows?: {
+    /**
+     * Get a shadow preset by ID.
+     * @param presetId - Shadow preset identifier (e.g., `'sm'`, `'md'`, `'lg'`)
+     * @returns Shadow configuration (guaranteed to exist)
+     */
     getPreset: (presetId: string) => ShadowConfig;
   };
 }
 
 /**
- * Utility Functions API
+ * Utility functions API injected into plugins by the host application.
  *
- * Interface for utility functions required by the plugin.
- * The host application must provide implementations.
+ * @see {@link PluginDependencies.utils}
  */
 export interface PluginUtils {
   /**
-   * Class name utility (e.g., clsx, classnames, tailwind-merge)
-   * Combines multiple class names intelligently
+   * Class name utility function (e.g., `clsx`, `classnames`, `tailwind-merge`).
+   *
+   * Combines and deduplicates class names intelligently.
+   *
+   * @param inputs - Class names, arrays, objects, or falsy values
+   * @returns Merged class name string
+   *
+   * @example
+   * ```typescript
+   * const { cn } = dependencies.utils;
+   * const className = cn('base', isActive && 'active', { 'selected': isSelected });
+   * ```
    */
   cn: (...inputs: any[]) => string;
 }
 
 /**
- * Plugin Renderer Props
+ * Props for the `PluginRenderer` component injected by the host application.
  *
- * Props interface for the PluginRenderer component.
- * This is injected by the host application to render child plugins.
+ * Container plugins use this to recursively render their child elements.
+ * The host provides the actual implementation that resolves plugin IDs
+ * to component instances.
+ *
+ * @see {@link PluginDependencies.PluginRenderer}
  */
 export interface PluginRendererProps {
   /**
-   * Plugin ID to render (e.g., 'base-text', 'base-image')
+   * Plugin ID to render (e.g., `'base-text'`, `'base-image'`)
    */
   pluginId: string;
 
   /**
-   * Element ID for tracking
+   * Unique element ID for tracking and callbacks
    */
   elementId: string;
 
   /**
-   * Plugin data/configuration
+   * Plugin data / configuration object
    */
   data: Record<string, unknown>;
 
   /**
-   * Current language code
+   * Current language code (ISO) for content resolution
    */
   language: string;
 
   /**
-   * Is in editor mode?
+   * Whether the host is in editor mode (interactive editing enabled)
+   * @default false
    */
   isEditorMode?: boolean;
 
   /**
-   * Is element selected?
+   * Whether this element is currently selected in the editor
+   * @default false
    */
   isSelected?: boolean;
 
   /**
-   * Click handler
+   * Click handler for element selection
+   * @param id - Element ID that was clicked
    */
   onClick?: (id: string) => void;
 }
 
 /**
- * Plugin Callbacks
+ * Event callbacks for plugin-to-host communication.
+ *
+ * Plugins invoke these to notify the host application of user actions
+ * like content edits, child additions/removals, and layout changes.
  *
- * Event callbacks that plugins can use to communicate with the host application.
+ * @see {@link PluginDependencies.callbacks}
  */
 export interface PluginCallbacks {
   /**
-   * Called when content changes (for text, rich-text components)
-   * @param elementId - ID of the element
-   * @param language - Language code
+   * Called when text content changes (for text, rich-text components).
+   *
+   * @param elementId - ID of the element being edited
+   * @param language - ISO language code of the content
    * @param content - New content value
    */
   onContentChange?: (
@@ -547,10 +1117,11 @@ export interface PluginCallbacks {
   ) => void;
 
   /**
-   * Called when child element is dropped into container
-   * @param containerId - ID of the container element
+   * Called when a child element is dropped into a container.
+   *
+   * @param containerId - ID of the receiving container
    * @param droppedElementId - ID of the dropped element
-   * @param index - Optional insertion index
+   * @param index - Optional insertion index (append if omitted)
    */
   onChildAdded?: (
     containerId: string,
@@ -559,15 +1130,17 @@ export interface PluginCallbacks {
   ) => void;
 
   /**
-   * Called when child element is removed from container
-   * @param containerId - ID of the container element
+   * Called when a child element is removed from a container.
+   *
+   * @param containerId - ID of the container
    * @param removedElementId - ID of the removed element
    */
   onChildRemoved?: (containerId: string, removedElementId: string) => void;
 
   /**
-   * Called when container layout is changed
-   * @param containerId - ID of the container element
+   * Called when a container's layout mode changes.
+   *
+   * @param containerId - ID of the container
    * @param layoutMode - New layout mode
    */
   onLayoutChange?: (
@@ -577,30 +1150,47 @@ export interface PluginCallbacks {
 }
 
 /**
- * Complete Plugin Dependencies
+ * Complete plugin dependencies — everything a plugin receives from the host.
+ *
+ * This is the full dependency interface used by the `dependencies.ts` module.
+ * It includes the `PluginRenderer` component and optional callbacks,
+ * which are not present in the simplified version in `plugin-system.ts`.
+ *
+ * **Plugin-driven architecture:** Plugins never import host code directly.
+ * All external functionality is injected through this interface.
  *
- * All external dependencies that must be injected into the plugin.
- * PLUGIN-DRIVEN ARCHITECTURE: Plugins receive dependencies from the host app.
+ * @see {@link PluginDesignSystem} for design token access
+ * @see {@link PluginUtils} for utility functions
+ * @see {@link PluginRendererProps} for the renderer component props
+ * @see {@link PluginCallbacks} for event communication
  */
 export interface PluginDependencies {
   /**
    * Design System API for accessing global design tokens
+   * (fonts, colors, spacing, breakpoints, etc.).
+   * @see {@link PluginDesignSystem}
    */
   designSystem: PluginDesignSystem;
 
   /**
-   * Utility functions (e.g., cn for classnames)
+   * Utility functions (e.g., `cn` for class name merging).
+   * @see {@link PluginUtils}
    */
   utils: PluginUtils;
 
   /**
-   * PluginRenderer component for rendering child plugins
-   * CRITICAL: Container plugins need this to render their NESTED children
+   * Component for recursively rendering child plugins inside containers.
+   *
+   * **Critical** for container plugins with `supportsChildren = true` —
+   * they use this to render their nested children.
+   *
+   * @see {@link PluginRendererProps}
    */
   PluginRenderer: ComponentType<PluginRendererProps>;
 
   /**
-   * Optional callbacks for communication with host app
+   * Optional event callbacks for communicating with the host application.
+   * @see {@link PluginCallbacks}
    */
   callbacks?: PluginCallbacks;
 }