@codefluss/base-types 0.0.1-alpha.1

package/src/plugin-system.ts

@@ -0,0 +1,785 @@
+/**
+ * Plugin System Type Definitions
+ *
+ * Core types for the headless plugin architecture.
+ * These types define the contract between plugins and the Context Panel UI.
+ *
+ * @package @codefluss/base-types
+ * @version 1.0.0
+ */
+
+import type { ComponentType } from "react";
+import type { PluginDesignSystem, PluginUtils } from "./dependencies";
+
+/**
+ * Property control type
+ * Defines which UI control to render in Context Panel
+ */
+export type PropertyControlType =
+  | "input"
+  | "slider"
+  | "select"
+  | "color-picker"
+  | "toggle"
+  | "textarea"
+  | "number-input"
+  | "number-with-unit" // Container-specific
+  | "box-model"
+  | "spacing" // Combined margin + padding control
+  | "spacing-combined" // Combined margin + padding control (UI variant)
+  | "grid" // Container-specific
+  | "typography-toolbar"
+  | "gradient-editor"
+  | "border-editor"
+  | "font-preset-select" // Design System font presets
+  | "color-preset-select" // Design System color presets
+  | "text-align-toggle" // Horizontal text alignment toggle buttons
+  | "vertical-align-toggle"; // Vertical alignment toggle buttons (align-self)
+
+/**
+ * Property type
+ * Semantic type of the property value
+ */
+export type PropertyType =
+  | "text"
+  | "number"
+  | "range"
+  | "select"
+  | "color"
+  | "toggle"
+  | "multiLangText"
+  | "boxModel"
+  | "box-model"
+  | "spacing" // Combined margin + padding
+  | "spacing-combined" // Combined margin + padding (UI variant)
+  | "grid"
+  | "toolbar"
+  | "gradient"
+  | "border";
+
+/**
+ * Property category for organization
+ */
+export type PropertyCategory = "content" | "style" | "layout" | "advanced";
+
+/**
+ * Slider control configuration
+ */
+export interface SliderConfig {
+  min: number;
+  max: number;
+  step: number;
+  showValue?: boolean;
+  unit?: string; // 'px', '%', 'em', etc.
+  marks?: Array<{ value: number; label: string }>;
+}
+
+/**
+ * Number input control configuration
+ */
+export interface NumberConfig {
+  min?: number;
+  max?: number;
+  step?: number;
+  unit?: string; // 'px', '%', 'em', etc.
+}
+
+/**
+ * Number with unit control configuration (Container-specific)
+ */
+export interface NumberWithUnitConfig {
+  min?: number;
+  max?: number;
+  step?: number;
+  units?: string[]; // ['px', '%', 'em', 'rem', 'vw', 'vh']
+  defaultUnit?: string;
+  allowEmpty?: boolean; // Allow empty/null values (container-specific)
+}
+
+/**
+ * Select control configuration
+ */
+export interface SelectConfig {
+  options: Array<{ value: string; label: string; icon?: ComponentType }>;
+  searchable?: boolean;
+}
+
+/**
+ * Text input control configuration
+ */
+export interface InputConfig {
+  placeholder?: string;
+  pattern?: RegExp;
+  validationMessage?: string;
+}
+
+/**
+ * Color picker control configuration
+ */
+export interface ColorPickerConfig {
+  format?: "hex" | "rgb" | "hsl";
+  alpha?: boolean;
+  presets?: string[];
+}
+
+/**
+ * Textarea control configuration
+ */
+export interface TextareaConfig {
+  rows?: number;
+  autoResize?: boolean;
+  placeholder?: string;
+}
+
+/**
+ * Box model control configuration
+ */
+export interface BoxModelConfig {
+  min?: number;
+  max?: number;
+  unit?: string;
+  linkedByDefault?: boolean;
+}
+
+/**
+ * Spacing control configuration (combined margin + padding)
+ */
+export interface SpacingConfig {
+  paddingMin?: number;
+  paddingMax?: number;
+  marginMin?: number;
+  marginMax?: number;
+  unit?: string;
+}
+
+/**
+ * Typography toolbar control configuration
+ */
+export interface TypographyToolbarConfig {
+  showBold?: boolean;
+  showItalic?: boolean;
+  showUnderline?: boolean;
+  showAlignment?: boolean;
+  showFontSize?: boolean;
+  showColor?: boolean;
+}
+
+/**
+ * Gradient editor control configuration
+ */
+export interface GradientEditorConfig {
+  allowLinear?: boolean;
+  allowRadial?: boolean;
+  maxStops?: number;
+  colorFormat?: "hex" | "rgb" | "hsl";
+}
+
+/**
+ * Border editor control configuration
+ */
+export interface BorderEditorConfig {
+  allowIndividualSides?: boolean;
+  allowRadius?: boolean;
+  maxWidth?: number;
+}
+
+/**
+ * Font preset select control configuration
+ * Shows typography presets from Design System
+ */
+export interface FontPresetSelectConfig {
+  /** Filter fonts by category (e.g., "heading", "body") */
+  category?: string;
+  /** Placeholder text */
+  placeholder?: string;
+}
+
+/**
+ * Color preset select control configuration
+ * Shows color presets from Design System (no free text)
+ */
+export interface ColorPresetSelectConfig {
+  /** Filter colors by category */
+  category?: string;
+  /** Placeholder text */
+  placeholder?: string;
+  /** Show color preview swatch */
+  showSwatch?: boolean;
+  /** Allow "None" option for transparent/no color */
+  allowNone?: boolean;
+}
+
+/**
+ * Alignment toggle control configuration
+ * Icon-based toggle buttons for text-align or align-self
+ */
+export interface AlignmentToggleConfig {
+  /** Include justify option for horizontal alignment */
+  includeJustify?: boolean;
+  /** Include stretch option for vertical alignment */
+  includeStretch?: boolean;
+  /** Include auto/inherit option */
+  includeAuto?: boolean;
+}
+
+/**
+ * Display mode configuration
+ */
+export interface DisplayConfig {
+  /**
+   * Show in tooltip on hover vs always visible in panel
+   */
+  mode?: "tooltip" | "panel" | "both";
+
+  /**
+   * Collapsible section
+   */
+  collapsible?: boolean;
+
+  /**
+   * Default collapsed state
+   */
+  defaultCollapsed?: boolean;
+
+  /**
+   * Layout mode for property controls in panel (container-specific)
+   * Determines how controls are arranged (single column, 2-column grid, etc.)
+   */
+  layout?: "grid-2" | "grid-3" | "single" | string;
+
+  /**
+   * Conditional visibility based on other property values
+   * @example { when: 'layout.mode', equals: 'flexbox' }
+   */
+  condition?: {
+    when: string; // Property key to watch
+    equals?: unknown; // Show when equals this value
+    notEquals?: unknown; // Show when not equals this value
+  };
+}
+
+/**
+ * UI configuration for property
+ * This is the metadata that tells Context Panel HOW to render
+ */
+export interface PropertyUIConfig {
+  control: PropertyControlType;
+  slider?: SliderConfig;
+  number?: NumberConfig;
+  numberWithUnit?: NumberWithUnitConfig; // Container-specific
+  select?: SelectConfig;
+  input?: InputConfig;
+  textarea?: TextareaConfig;
+  colorPicker?: ColorPickerConfig;
+  boxModel?: BoxModelConfig;
+  spacing?: SpacingConfig; // Combined margin + padding control
+  typographyToolbar?: TypographyToolbarConfig;
+  gradientEditor?: GradientEditorConfig;
+  borderEditor?: BorderEditorConfig;
+  fontPresetSelect?: FontPresetSelectConfig; // Design System font presets
+  colorPresetSelect?: ColorPresetSelectConfig; // Design System color presets
+  alignmentToggle?: AlignmentToggleConfig; // Alignment toggle buttons
+  display?: DisplayConfig;
+}
+
+/**
+ * Property validation rules
+ */
+export interface PropertyValidation {
+  pattern?: RegExp;
+  min?: number;
+  max?: number;
+  message?: string;
+  custom?: (value: unknown) => boolean | string;
+}
+
+/**
+ * Property priority for progressive disclosure
+ * Determines visual hierarchy and default visibility in Context Panel
+ */
+export type PropertyPriority = "quick" | "common" | "advanced";
+
+/**
+ * Property definition (headless metadata)
+ *
+ * This is the core interface that plugins use to define their properties.
+ * The Context Panel UI reads this and auto-generates appropriate controls.
+ */
+export interface PropertyDefinition {
+  /**
+   * Property key (dot notation for nested properties)
+   * @example 'style.fontSize', 'layout.padding.top'
+   */
+  key: string;
+
+  /**
+   * Property type (semantic)
+   */
+  type: PropertyType;
+
+  /**
+   * Display label for UI
+   */
+  label: string;
+
+  /**
+   * Default value (null = use global default if applicable)
+   */
+  default: unknown;
+
+  /**
+   * Description shown in UI
+   */
+  description?: string;
+
+  /**
+   * Property category for organization
+   */
+  category?: PropertyCategory;
+
+  /**
+   * Whether property is required
+   */
+  required?: boolean;
+
+  /**
+   * Property priority for progressive disclosure (optional)
+   * - quick: Always visible, no accordion (most important)
+   * - common: Collapsible, default open (frequently used)
+   * - advanced: Collapsible, default closed (rarely used)
+   * Defaults to 'common' if not specified
+   */
+  priority?: PropertyPriority;
+
+  /**
+   * Design System integration
+   * If true, shows "Use Global Default" toggle
+   */
+  useGlobal?: boolean;
+
+  /**
+   * Design System key to reference
+   * @example 'fonts.body.size', 'colors.text-primary'
+   */
+  globalKey?: string;
+
+  /**
+   * UI control configuration (headless)
+   */
+  ui?: PropertyUIConfig;
+
+  /**
+   * Validation rules
+   */
+  validation?: PropertyValidation;
+}
+
+/**
+ * Plugin metadata
+ */
+export interface PluginMeta {
+  description?: string;
+  tags?: string[];
+  thumbnail?: string;
+  documentation?: string;
+}
+
+/**
+ * Plugin Capabilities - PLUGIN-DRIVEN ARCHITECTURE
+ *
+ * Declares what the plugin can do and how it should be handled by the app.
+ * This is the core of the plugin-driven architecture:
+ * The plugin ITSELF defines its capabilities, not the app.
+ */
+export interface PluginCapabilities {
+  /**
+   * Can this plugin contain child components?
+   * true = container/layout component
+   * false = leaf component (text, image, button, etc.)
+   */
+  supportsChildren: boolean;
+
+  /**
+   * Is this a root component?
+   * true = can be placed at canvas/section level (containers, sections)
+   * false = must be inside another component (text, buttons, images)
+   */
+  isRootComponent: boolean;
+
+  /**
+   * Does this plugin require a parent container?
+   * true = cannot exist at top level, must be inside a container
+   * false = can be placed directly on canvas
+   *
+   * @example Text component: requiresParent = true (must be in container)
+   * @example Container component: requiresParent = false (can be at top level)
+   */
+  requiresParent: boolean;
+
+  /**
+   * Children architecture type
+   * 'nested' = NESTED architecture with direct children arrays (RECOMMENDED)
+   * 'flat' = FLAT architecture with parentId references (DEPRECATED)
+   * null = does not support children
+   */
+  childrenType: "nested" | "flat" | null;
+
+  /**
+   * Allowed child plugin IDs
+   * Empty array = all plugins allowed as children
+   * ['text', 'image'] = only specific plugins allowed
+   * Only applicable if supportsChildren = true
+   */
+  allowedChildPlugins: string[];
+
+  /**
+   * Allowed parent plugin IDs
+   * Empty array = can be child of any container
+   * ['base-container'] = can only be inside specific containers
+   * Only applicable if requiresParent = true
+   */
+  allowedParentPlugins?: string[];
+
+  /**
+   * Maximum number of children allowed
+   * null = unlimited children
+   * number = specific limit
+   * Only applicable if supportsChildren = true
+   */
+  maxChildren: number | null;
+
+  /**
+   * Minimum number of children required
+   * 0 = no minimum requirement
+   * Only applicable if supportsChildren = true
+   */
+  minChildren: number;
+}
+
+/**
+ * ============================================================================
+ * Dual-Component Architecture Props
+ * ============================================================================
+ *
+ * These interfaces support the Dual-Component Pattern where plugins have:
+ * - Editor Component ('use client') - Interactive editing with React hooks
+ * - Renderer Component (NO 'use client') - Server-side rendering for view mode
+ *
+ * This pattern enables:
+ * - Better SEO (content in initial HTML)
+ * - Improved performance (smaller JS bundles, faster FCP/LCP)
+ * - Clear separation between editor and view mode
+ */
+
+/**
+ * Plugin Dependencies
+ *
+ * External dependencies injected by host application.
+ * These are provided by the web-app and contain design system,
+ * utilities, and callbacks needed by plugins.
+ */
+export interface PluginDependencies {
+	/**
+	 * Design System instance
+	 * Provides access to fonts, colors, spacing, and other design tokens
+	 */
+	designSystem: PluginDesignSystem;
+
+	/**
+	 * Utility functions
+	 * Helper functions for common operations
+	 */
+	utils: PluginUtils;
+
+	/**
+	 * Callbacks (Editor only)
+	 * Functions to update element data and properties
+	 */
+	onContentChange?: (
+		elementId: string,
+		language: string,
+		content: unknown,
+	) => void;
+	onPropertyChange?: (
+		elementId: string,
+		property: string,
+		value: unknown,
+	) => void;
+}
+
+/**
+ * Base Props for ALL Plugin Components
+ *
+ * Defines the minimal required props that EVERY plugin must accept.
+ * Both Editor Components and Renderers should extend this interface.
+ *
+ * @template TData - Plugin-specific data type
+ *
+ * @example
+ * ```typescript
+ * interface HeadingEditorProps extends BasePluginProps<HeadingComponentData>, EditorModeProps {}
+ * interface HeadingRendererProps extends RendererProps<HeadingComponentData> {}
+ * ```
+ */
+export interface BasePluginProps<TData = unknown> {
+  /**
+   * Unique element ID
+   * Used for data attributes, callbacks, and DOM references
+   */
+  elementId: string;
+
+  /**
+   * Plugin-specific data
+   * Contains all configurable properties and content
+   */
+  data: TData;
+
+  /**
+   * Current language (ISO code)
+   * Used for multi-language content resolution
+   * @example 'de', 'en', 'fr', 'es', 'it'
+   */
+  language: string;
+
+  /**
+   * Injected dependencies
+   * Design system, utilities, and callbacks provided by host application
+   */
+  dependencies: PluginDependencies;
+}
+
+/**
+ * Editor Mode Props
+ *
+ * Additional props needed ONLY for Editor Components.
+ * These props enable interactive editing functionality.
+ *
+ * Editor Components should combine:
+ * - BasePluginProps<TData> (required base props)
+ * - EditorModeProps (editor-specific features)
+ *
+ * @example
+ * ```typescript
+ * export interface HeadingEditorProps
+ *   extends BasePluginProps<HeadingComponentData>,
+ *           EditorModeProps {}
+ * ```
+ */
+export interface EditorModeProps {
+  /**
+   * Is component currently selected in editor?
+   * Used for visual feedback and activation of editing features
+   */
+  isSelected?: boolean;
+
+  /**
+   * Click handler for component selection
+   * Called when user clicks on the component
+   */
+  onClick?: (elementId: string) => void;
+
+  /**
+   * Content change callback
+   * Called when user edits text content (contentEditable)
+   * @example onContentChange('heading-1', 'de', 'Neuer Titel')
+   */
+  onContentChange?: (
+    elementId: string,
+    language: string,
+    content: unknown,
+  ) => void;
+
+  /**
+   * Property change callback
+   * Called when user changes properties via Context Panel
+   * @example onPropertyChange('heading-1', 'style.fontSize', '32px')
+   */
+  onPropertyChange?: (
+    elementId: string,
+    property: string,
+    value: unknown,
+  ) => void;
+}
+
+/**
+ * Renderer Props (View/SSR Mode)
+ *
+ * Minimal props for Server-Side Rendering components.
+ * These components do NOT use 'use client' and should work in Node.js environment.
+ *
+ * Key differences from BasePluginProps:
+ * - No callbacks (onContentChange, onPropertyChange)
+ * - Minimal dependencies (only designSystem and utils, no callbacks)
+ * - Should use pure functions, no React hooks
+ *
+ * @template TData - Plugin-specific data type
+ *
+ * @example
+ * ```typescript
+ * // heading-renderer.tsx (NO 'use client')
+ * export interface HeadingRendererProps extends RendererProps<HeadingComponentData> {}
+ *
+ * export function HeadingRenderer({ elementId, data, language, dependencies }: HeadingRendererProps) {
+ *   const content = resolveTextContent(data, language); // Pure function
+ *   const styles = resolveTextStyles(data, dependencies.designSystem); // Pure function
+ *   return <h1 style={styles}>{content}</h1>;
+ * }
+ * ```
+ */
+export interface RendererProps<TData = unknown> {
+  /**
+   * Unique element ID
+   * Used for data attributes and DOM references
+   */
+  elementId: string;
+
+  /**
+   * Plugin-specific data
+   * Contains all configurable properties and content
+   */
+  data: TData;
+
+  /**
+   * Current language (ISO code)
+   * Used for multi-language content resolution
+   */
+  language: string;
+
+  /**
+   * Minimal dependencies (design system and utils only)
+   * No callbacks since renderers are read-only
+   */
+  dependencies: Pick<PluginDependencies, "designSystem" | "utils">;
+}
+
+/**
+ * Container Props
+ *
+ * Additional props for plugins that support children (containers, layouts).
+ * Used by both Editor Components and Renderers when the plugin has supportsChildren = true.
+ *
+ * @example
+ * ```typescript
+ * // Editor Component
+ * export interface ContainerEditorProps
+ *   extends BasePluginProps<ContainerData>,
+ *           EditorModeProps,
+ *           ContainerProps {}
+ *
+ * // Renderer Component
+ * export interface ContainerRendererProps
+ *   extends RendererProps<ContainerData>,
+ *           Pick<ContainerProps, 'children'> {}
+ * ```
+ */
+export interface ContainerProps {
+  /**
+   * Child components (rendered recursively)
+   * React nodes to be rendered inside this container
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Drop event handler (Editor only)
+   * Called when user drops an element into this container
+   *
+   * @param targetId - Container element ID
+   * @param droppedId - Dragged element ID
+   * @param position - Drop position ('before', 'after', 'inside')
+   */
+  onDrop?: (
+    targetId: string,
+    droppedId: string,
+    position: "before" | "after" | "inside",
+  ) => void;
+}
+
+/**
+ * Plugin configuration (headless)
+ *
+ * Complete plugin definition with component, properties, and metadata.
+ */
+export interface PluginConfig {
+  /**
+   * Unique plugin identifier
+   */
+  id: string;
+
+  /**
+   * Display name
+   */
+  name: string;
+
+  /**
+   * Semantic version
+   */
+  version: string;
+
+  /**
+   * Plugin category
+   */
+  category: "basic" | "layout" | "advanced";
+
+  /**
+   * Project types this plugin is available for.
+   * - undefined or [] = available for ALL project types (default, backward-compatible)
+   * - ['landing'] = only available for landing page projects
+   * - ['blog'] = only available for blog projects
+   * - ['landing', 'blog'] = available for both
+   */
+  projectTypes?: string[];
+
+  /**
+   * Semantic context for dynamic data binding.
+   * - 'static' = content defined at design time (default for most plugins)
+   * - 'dynamic' = content bound to collection entry at runtime (blog, shop items)
+   */
+  contentBinding?: "static" | "dynamic";
+
+  /**
+   * Icon component (optional)
+   */
+  icon?: ComponentType;
+
+  /**
+   * React component to render
+   */
+  component: ComponentType<any>;
+
+  /**
+   * Property definitions
+   */
+  properties: PropertyDefinition[];
+
+  /**
+   * Default values for new instances
+   */
+  defaults: Record<string, unknown>;
+
+  /**
+   * Localized strings for UI
+   */
+  locales: Record<string, unknown>;
+
+  /**
+   * Server-side rendering support
+   */
+  ssr: boolean;
+
+  /**
+   * Responsive design support
+   */
+  responsive: boolean;
+
+  /**
+   * PLUGIN-DRIVEN ARCHITECTURE:
+   * Plugin capabilities define what the plugin can do
+   * The app reads these to understand how to handle the plugin
+   */
+  capabilities: PluginCapabilities;
+
+  /**
+   * Plugin metadata
+   */
+  meta?: PluginMeta;
+}